[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.

[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.