title: Managed worktrees CLI lifecycle

scenario:
  id: managed-worktrees-cli
  surface: runtime
  category: agent-runtime.agent-turn-execution
  coverage:
    primary:
      - agent-runtime.managed-worktrees-lifecycle
  objective: Prove the real child CLI creates a manual managed worktree with ignored-file provisioning and its repository setup hook, snapshots dirty state during removal, restores tracked, untracked, and provisioned files with their modes, and preserves the active manual worktree through gc.
  successCriteria:
    - Create provisions ignored files with their modes and runs the repository setup hook with canonical source and worktree paths.
    - Dirty removal pins a snapshot ref in the source repository and retains the removed record for restoration.
    - Restore rebuilds tracked and untracked changes plus provisioned ignored files with their modes without putting the synthetic snapshot commit in branch history.
    - Garbage collection returns its structured result while preserving the active manual worktree.
  docsRefs:
    - docs/concepts/managed-worktrees.md
    - docs/concepts/qa-e2e-automation.md
  codeRefs:
    - src/cli/worktrees-cli.ts
    - src/agents/worktrees/service.ts
    - src/agents/worktrees/provisioned-files.ts
    - test/e2e/qa-lab/runtime/managed-worktrees-cli-product-proof.e2e.test.ts
  execution:
    kind: vitest
    path: test/e2e/qa-lab/runtime/managed-worktrees-cli-product-proof.e2e.test.ts
    summary: Run the real child CLI through managed worktree provisioning, snapshot removal, restoration, and manual-owner garbage collection.