[nateEc]

Summary

An existing coding session can discover opted-in workflows, inspect required inputs, and drive the public lease loop with --driver skill. next --prepare and report reuse the local driver's base-overlay, worktree, commit/push and cleanup implementation, so the session never needs the graph or workspace git commands.

Run-id operations resolve the owning local scope and original checkout independently of cwd, including from a workflow worktree or outside the product repo. Duplicate ids are rejected. Repeated preparation preserves edits, and cancelled, stale or mismatched reports are checked before git delivery.

Type of Change

• New feature
• Bilingual guides, CLI-served skill, discovery stub and generated command reference

Test Plan

• npm run typecheck
• npm run lint
• Workflow/hook/skill coverage: a 24-file broad run passed 1,324 tests; its guide-example and error-catalog failures were corrected and the five affected suites passed 83 tests. The one timing-sensitive command-concurrency assertion passed in isolation; all remaining tests in the broad run passed. No outstanding test failure remains.
• Discovery regressions: explicit opt-in, disabled/invalid workflow omission, alias ambiguity and canonical-name precedence, description/total hook bounds, and preserving existing Cursor user rules when discovery yields.
• Session workspace regressions: preparation handback preserves edits, base instructions replace branch-authored instructions, actual commits reach the bare remote, duplicate reports do not commit again, cancellation preserves uncommitted work, and run lookup rejects duplicate ids across scopes.
• npx vitest run commands-reference -u
• npm run test:e2e -- workflow-session-1086 (build runs first): one real-CLI round trip passed on this commit, with a disposable HOME and local bare remote. It checks SessionStart discovery, alias metadata/input inspection, skill-driver start, preparation from outside the repo, a repeated next and report from the worktree, rejection of an agent-mediated required approval, acceptance through the driver UI channel, a later report from outside the repo, base-config restoration, remote file contents, cleanup and served workflow skill content. Work itself is simulated by fixture edits, without a model account.

Related Issues

Fixes #1086

The requirement-enforcement companion is #1303 (#1082). This branch targets current main independently and does not repeat that commit. The standard session profile declares no scoped-env/setup capability it cannot provide. The combined changes were also verified in an isolated integration checkout (details below).

Notes for Reviewers

Only the existing teamai stub is deployed. skill-data/workflow/SKILL.md is served by the installed CLI and points to current help instead of duplicating flags. Invocable context contains bounded metadata only, never the graph, prompt or command body. A full name wins over an alias; duplicate aliases do not resolve. --describe creates no run.

The local preparation record contains workspace contracts, paths and fingerprints, including hashes rather than conflict contents. It contains no prompt or env values. A per-run driver lock serializes local execution and public preparation/report, while git/network work stays outside the run lock. Public report polls reconciliation before committing, verifies the active attempt/driver/revision, derives changes/read from git, and cleans up only after an accepted successful engine report. Direct-person approvals retain the existing agent_in_path restriction.

Run lookup scans configured data homes rather than adding a second run index. It reanchors self-mode configuration to the run's retained checkout so branch-authored configuration cannot choose the owning team merely because the caller is in that worktree. Session hosts remain responsible for truthful capabilities, actual tool/model/token metadata, stopping cancelled tools and applying an explicitly requested model; unsupported model selection is a reported model_unavailable failure.

Integration with #1303: an isolated merge checkout passed typecheck, 25 focused limit/session/discovery/reference tests, both real-CLI safety/session E2Es, and a separate capability test showing that a valid secret-requiring step remains pending for a session declaring no env capability and can then be leased by a capable driver. Secret values remain absent from its lease. The test merge resolved the expected adjacent parser/type/help/doc additions; no dependency commits are duplicated in this PR.

Review follow-up (1c5c63a)

Addressed the interactive editing finding by retaining interactive/read-only flags in persisted preparation data and applying the existing local-driver exemption. Both writable interactive and explicit read-only cases are covered. Fixed the actual failed CI shard by updating every skill-serving/recall catalog expectation for the added workflow skill. All five session-driver regressions, typecheck, lint and nine build-first CLI session/skill-serving E2E cases passed at this head.

Follow-up verification (2026-10-25)

• Rebased onto main while keeping feat(push): support all namespaced resource types #1234 diagnostic codes and feat(workflow): publish and resume workflow runs across machines (#1084) #1280 publish/resume, driver locks, session continuation and current shared DriverSchema. Regenerated the CLI reference.
• Preserved remote claim before a local run file exists for both workflow next with claim: true and workflow resume. A new next-claim regression failed before the compatibility fix and passes afterwards.
• Broad workflow regression: 25 files / 1,405 tests passed. After the small claim fallback fix, the final command file passed 17/17.
• Built-CLI session-workflow plus cross-machine publish/resume E2E files: 6 passed, covering outside-checkout preparation/reporting, direct HITL approval, remote ownership, detached bases, shallow clones and archived-session continuation.
• Build, type checking and lint passed.
• Addressed the new rejected-push finding: prepared session writers now pass the correct failure flag to workspace finalization, preserve original tool failures with an unpushed warning, and retain rejected commits. Both new success/failure report regressions failed before the correction.
• Fixed the CI Git-conformance regression by restoring the caller checkout as the resume fallback when no same-machine driver workspace applies. Final validation: 24 focused unit tests, all 7 built-CLI Git-conformance cases (including both previously failing missing-commit checks), build, types and lint passed.

Updated head: 9537a12f9ab64d314fb31335bbd7f7c454969c83. Rebased onto main 6ebb31ce.

[github-actions]

• [P1 blocking] Preserve interactive prompt write permissions — src/workflow/local-driver.ts:1041: Prepare an interactive: true prompt step without a workspace, edit a repository file, then report success. Preparation always retains a snapshot, and reporting unconditionally checks it, converting valid interactive edits into read_only_dirty failure. The existing local driver explicitly permits these edits when interactive && !readOnly. Retain those flags in the preparation record/schema and apply the same exemption.

The PR description documents sufficient testing, including a representative build-first real-CLI round trip. No testing-record finding. I only read the diff; I did not run, build, or install PR code.

[github-actions]

No new findings in the specified diff.

• Resolved: The earlier interactive-permission finding is fixed: preparation retains interactive/readOnly, and reporting exempts interactive edits unless explicitly read-only.
• Testing: The PR description documents sufficient testing, including a build-first representative real-CLI round trip. No testing-record finding.

I only read the diff and trusted base review criteria; I did not run, build, or install PR code.

[SaulMoro]

This was generated by AI during triage.

@nateEc Thanks. This branch conflicts with main in src/workflow/types.ts and src/__tests__/workflow-records.test.ts. Main caused it: #1234 (2401d047) added workflow_namespace_conflict and prompt_namespace_conflict to the WorkflowDiagnostic['code'] union and to the diagnostics list in the records test, on the same lines this PR extends. Keeping both sets of codes should resolve it. We'll review the rebased head. #1303, #1304 and #1306 also share most of their workflow files (types.ts, parse.ts, local-driver.ts, src/index.ts, the workflow guides), so whichever lands first will need the other two rebased again.

[SaulMoro]

This was generated by AI during triage.

@nateEc an update to the request for changes: the conflict with main is now wider than the two files it named. #1280 (publish and resume workflow runs across machines) landed and touches the same engine. This head now conflicts in src/index.ts, src/workflow-commands.ts, src/workflow/types.ts, docs/dev/workflow-engine.md, commands.md and workflow-records.test.ts. Please rebase onto current main. Keep #1234's workflow_namespace_conflict and prompt_namespace_conflict codes and #1280's publish/resume state, then rerun the real-CLI record on the result.

[nateEc]

Addressed the review follow-up at 73b8835747b7cf5114dd279461cf08d3876becbc on current main.

• Rebased onto main while keeping feat(push): support all namespaced resource types #1234 diagnostic codes and feat(workflow): publish and resume workflow runs across machines (#1084) #1280 publish/resume, driver locks, session continuation and current shared DriverSchema. Regenerated the CLI reference.
• Preserved remote claim before a local run file exists for both workflow next with claim: true and workflow resume. A new next-claim regression failed before the compatibility fix and passes afterwards.
• Broad workflow regression: 25 files / 1,405 tests passed. After the small claim fallback fix, the final command file passed 17/17.
• Built-CLI session-workflow plus cross-machine publish/resume E2E files: 6 passed, covering outside-checkout preparation/reporting, direct HITL approval, remote ownership, detached bases, shallow clones and archived-session continuation.
• Build, type checking and lint passed.

The PR description contains the updated verification record. Ready for another review.

[github-actions]

• [P1 blocking] Treat rejected pushes as delivery failures — src/workflow/local-driver.ts:1200: finishWorkspace expects a failed flag, but receives report.outcome === 'success'. If a prepared writer reports success and origin rejects its push, the helper returns unpushed instead of a failure; this wrapper discards that warning and reports success, potentially authorizing final-worktree cleanup despite undelivered commits. Pass report.outcome === 'failed' and preserve the delivery warning for already-failed reports.

• Resolved: The earlier interactive-permission finding remains fixed.

• Testing: The description documents sufficient build-first real-CLI verification. No testing-record finding.

I only read the specified diff and trusted base review criteria; I did not run, build, or install PR code.

[SaulMoro]

@nateEc Thanks for this work. We are taking over #1303, #1304 and #1306 to speed up delivery. We will push the remaining changes to your branches, bring them up to date with main, and keep you as co-author in the squash commit. #1303 and #1306 go first, and #1304 follows once both have merged.

Please hold off on pushing to these branches in the meantime. All three stay blocked until we finish.

[nateEc]

Addressed the review follow-up at 9537a12f9ab64d314fb31335bbd7f7c454969c83 on current main.

• Rebased onto main while keeping feat(push): support all namespaced resource types #1234 diagnostic codes and feat(workflow): publish and resume workflow runs across machines (#1084) #1280 publish/resume, driver locks, session continuation and current shared DriverSchema. Regenerated the CLI reference.
• Preserved remote claim before a local run file exists for both workflow next with claim: true and workflow resume. A new next-claim regression failed before the compatibility fix and passes afterwards.
• Broad workflow regression: 25 files / 1,405 tests passed. After the small claim fallback fix, the final command file passed 17/17.
• Built-CLI session-workflow plus cross-machine publish/resume E2E files: 6 passed, covering outside-checkout preparation/reporting, direct HITL approval, remote ownership, detached bases, shallow clones and archived-session continuation.
• Build, type checking and lint passed.
• Addressed the new rejected-push finding: prepared session writers now pass the correct failure flag to workspace finalization, preserve original tool failures with an unpushed warning, and retain rejected commits. Both new success/failure report regressions failed before the correction.
• Fixed the CI Git-conformance regression by restoring the caller checkout as the resume fallback when no same-machine driver workspace applies. Final validation: 24 focused unit tests, all 7 built-CLI Git-conformance cases (including both previously failing missing-commit checks), build, types and lint passed.

The PR description contains the updated verification record. Ready for another review.

[SaulMoro]

@nateEc Thanks for this work. We are taking over these three PRs to speed up delivery:

• #1303
• #1304
• #1306

We will push the remaining changes to your branches, bring them up to date with main, and keep you as co-author in the squash commit. #1303 and #1306 go first, and #1304 follows once both have merged.

Please hold off on pushing to these branches in the meantime. All three stay blocked until we finish.

[github-actions]

No new findings in the specified diff.

• Resolved: Interactive write permissions remain fixed; preparation retains interactive/readOnly, and reporting applies the existing exemption.
• Resolved: Rejected pushes now fail successful reports; already-failed reports retain their original failure with an unpushed warning.
• Testing: The PR description includes sufficient build-first real-CLI verification. No testing-record finding.

I only read the specified diff and trusted base review criteria; I did not run, build, or install PR code.

[SaulMoro]

#1180's benchmark PR (#1379) also uses teamai workflow next --prepare. It keeps this PR's flag and envelope: with --prepare, next answers { "data": { "lease": { ...lease, "cwd": "<dir>" } } }.

On a benchmark run, --prepare prepares a trial instead of a session: teamai makes a fresh clone, installs the pinned team revision and runs setup, and the driver only launches the tool in cwd. teamai runs baselines and checks inside next --prepare itself. report on a benchmark run commits the trial's work and collects the evidence its judges read. Both route by run kind inside WorkflowClient.next and report, so nothing here changes for other runs.

This PR merges first. I'll rebase #1379 on it afterwards.