@try-works/dsh-recursive-mode 0.1.18 → 0.2.0

package/lib/init-templates.d.ts

@@ -8,6 +8,10 @@ export interface GitContext {
     baseBranch: string;
     worktreeBranch: string;
     baseCommit: string;
+    /** True when the init cwd is a linked git worktree (git-dir != git-common-dir). */
+    isWorktree: boolean;
+    /** Upstream branch with the remote prefix stripped (origin/dev -> dev), null when none/detached. */
+    upstreamBranch: string | null;
     notes: string;
 }
 /**

package/lib/recursive_worktree.tool.d.ts

@@ -0,0 +1,7 @@
+import type { RecursiveRuntime } from './runtime.ts';
+/**
+ * `recursive_worktree` — create a linked git worktree for a run and/or
+ * promote a branch up the dev/stage/main chain. Workspace-scoped: the
+ * operations run under the SESSION's control-plane root only.
+ */
+export declare function createRecursiveWorktreeTool(recursive: RecursiveRuntime): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/runtime.d.ts

@@ -7,6 +7,7 @@ import { type SubagentProviderLike, type RouteDecision, type CapabilityProbe } f
 import { type SubagentsRuntimeLike, type SubagentStartRequestLike, type SubagentResultLike, type Reference } from './delegation.ts';
 import { type PhaseTransitionIntent, type SessionEventLike, type RecursivePhaseState, type GateCheckResult } from './lifecycle.ts';
 import { type EnforcementConfig, type PreStepGateDecision, type ToolGuardDecision, type ToolExecLike } from './enforcement.ts';
+import { type CreateWorktreeResult, type PromoteBranchResult } from './worktree.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         recursive: RecursiveRuntime;
@@ -180,6 +181,12 @@ export declare class RecursiveRuntime extends Service {
      * required section (get_artifact_required_sections) + TODO + FAIL gates.
      * Also scaffolds addenda/subagents/router-prompts/evidence dirs. Returns the
      * run dir + created artifacts.
+     *
+     * When `opts.createWorktree` is true, a linked worktree is first created at
+     * `.worktrees/<runId>/` and the run is scaffolded INSIDE it (per the
+     * "all subsequent phases execute in worktree context" rule). The worktree
+     * branch defaults to `recursive/<runId>` and is cut from `opts.baseBranch`
+     * (default: current HEAD branch of the root checkout).
      */
     initRun(runId: string, agent?: {
         session?: {
@@ -187,12 +194,32 @@ export declare class RecursiveRuntime extends Service {
                 cwd?: string;
             };
         };
-    } | null): Promise<{
+    } | null, opts?: {
+        createWorktree?: boolean;
+        baseBranch?: string;
+    }): Promise<{
         runDir: string;
         runId: string;
         created: string[];
         existing: string[];
+        worktree?: CreateWorktreeResult;
     }>;
+    /**
+     * Create a linked worktree for a run under the given workspace root. The
+     * worktree branch defaults to `recursive/<runId>` and is cut from the given
+     * base branch (default: the current HEAD branch of the root checkout).
+     * Refuses to create over an existing run directory. Workspace-scoped.
+     */
+    createRunWorktree(root: string, runId: string, baseBranch?: string): CreateWorktreeResult;
+    /**
+     * Promote a branch up the dev/stage/main chain (fast-forward). Workspace-scoped.
+     */
+    promoteRunBranch(root: string, fromBranch: string, toBranch: string): PromoteBranchResult;
+    /**
+     * Worktree + branch status for a workspace root: the linked worktrees,
+     * which branch each is on, and the current checkout's base/upstream context.
+     */
+    worktreeStatus(root: string): Record<string, unknown>;
     /**
      * Lock a DRAFT artifact (or reopen a LOCKED one). Validates prerequisites;
      * writes Status/LockedAt/LockHash + receipt. Returns the lock result.

package/lib/ts-lint.d.ts

@@ -105,6 +105,14 @@ export declare function normalizeComparisonReference(value: string | null): stri
 export declare function parseDiffBasisSource(content: string): string;
 /** get_run_diff_basis: read diff-basis fields from 00-worktree.md. */
 export declare function getRunDiffBasis(runDir: string): Record<string, string | null>;
+/**
+ * verify_recorded_branches: worktree + branch awareness at lint time. Compares
+ * the branches recorded in 00-worktree.md against live git state. Returns a
+ * list of FAIL messages (empty when consistent). Both the base branch and the
+ * worktree branch must resolve; the worktree branch must match the live HEAD
+ * branch, and it must actually be based on the recorded base branch.
+ */
+export declare function verifyRecordedBranches(repoRoot: string, diffBasis: Record<string, string | null>, runDir: string): string[];
 /** normalize_diff_basis: validate + compute the executable diff basis. */
 export declare function normalizeDiffBasis(repoRoot: string, diffBasis: Record<string, string | null>): [Record<string, string> | null, string | null];
 /** get_git_changed_files: git diff --name-only + untracked (--relative). */

package/lib/worktree.d.ts

@@ -0,0 +1,59 @@
+export interface CreateWorktreeOptions {
+    repoRoot: string;
+    runId: string;
+    /** Base branch the worktree branch is cut from (default: current HEAD branch). */
+    baseBranch?: string;
+    /** Worktree branch name (default: `recursive/<runId>`). */
+    worktreeBranch?: string;
+}
+export interface CreateWorktreeResult {
+    ok: boolean;
+    worktreeDir: string;
+    worktreeBranch: string;
+    baseBranch: string;
+    error?: string;
+}
+export interface PromoteBranchOptions {
+    repoRoot: string;
+    /** Branch being promoted (the source of the new commits). */
+    fromBranch: string;
+    /** Promotion target branch (feature -> dev -> stage -> main). */
+    toBranch: string;
+}
+export interface PromoteBranchResult {
+    ok: boolean;
+    fromBranch: string;
+    toBranch: string;
+    action: 'fast-forward' | 'created';
+    error?: string;
+}
+/** Default worktree branch name for a run. */
+export declare function defaultWorktreeBranch(runId: string): string;
+/** One row of `git worktree list --porcelain` (path + branch when attached). */
+export interface WorktreeInfo {
+    path: string;
+    branch: string | null;
+    detached: boolean;
+}
+/** List linked worktrees (path + branch) for a repo root. */
+export declare function listWorktrees(repoRoot: string): WorktreeInfo[];
+/**
+ * Find the worktree path where `branch` is currently checked out, or null.
+ * Parses `git worktree list --porcelain` (block per worktree with a
+ * `branch refs/heads/<name>` line).
+ */
+export declare function findWorktreeForBranch(repoRoot: string, branch: string): string | null;
+/**
+ * Create a linked worktree at `.worktrees/<runId>/` for a run. The worktree
+ * branch is cut from `baseBranch` (default: the current HEAD branch). Returns
+ * the created worktree dir + branch. No-op-safe: if the worktree dir already
+ * exists, returns ok with the existing dir. Refuses to create a worktree when
+ * the run directory already exists (prevents clobbering an in-progress run).
+ */
+export declare function createLinkedWorktree(opts: CreateWorktreeOptions): CreateWorktreeResult;
+/**
+ * Fast-forward `toBranch` to `fromBranch` (promotion up the dev/stage/main
+ * chain). Returns ok:false when the promotion is not a pure fast-forward
+ * (would require a merge commit) or when the from/to branches are missing.
+ */
+export declare function promoteBranch(opts: PromoteBranchOptions): PromoteBranchResult;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@try-works/dsh-recursive-mode",
   "description": "recursive-mode workflow as a DeepSeek Harness bundle: RecursiveRuntime service + recursive_status tool",
-  "version": "0.1.18",
+  "version": "0.2.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/commands.ts

@@ -85,6 +85,28 @@ export function executeRecursiveCommand(root: string, rawInput: string): Recursi
       if (!existsSync(runDir)) return { kind: 'error', text: 'Run not found in current workspace: ' + runId }
       return { kind: 'success', text: 'closeout scaffolded for ' + runId + ' phase ' + phase }
     }
+    case 'worktree': {
+      // /recursive worktree create <runId> [--base <branch>]
+      // /recursive worktree promote <from> <to>
+      // /recursive worktree status
+      const parts = arg.trim().split(/\s+/)
+      const op = parts[0] ?? ''
+      if (op === 'status') return { kind: 'success', text: 'worktree status for workspace ' + root }
+      if (op === 'create') {
+        const runId = parts[1] ?? ''
+        if (!runId) return { kind: 'error', text: 'worktree create requires a run id' }
+        const runDir = join(runRoot, runId)
+        if (existsSync(runDir)) return { kind: 'error', text: 'Run already exists in this workspace: ' + runId }
+        return { kind: 'success', text: 'worktree created for run ' + runId + ' at .worktrees/' + runId }
+      }
+      if (op === 'promote') {
+        const fromBranch = parts[1] ?? ''
+        const toBranch = parts[2] ?? ''
+        if (!fromBranch || !toBranch) return { kind: 'error', text: 'worktree promote requires <from> <to>' }
+        return { kind: 'success', text: 'promoted ' + fromBranch + ' -> ' + toBranch }
+      }
+      return { kind: 'error', text: 'worktree requires create|promote|status' }
+    }
     case 'scratch': {
       const runId = arg.trim()
       if (!runId) return { kind: 'error', text: 'scratch requires a run id' }
@@ -147,6 +169,30 @@ export function registerRecursiveCommand(
           return { kind: 'success', text: 'closeout scaffolded: ' + JSON.stringify(result) }
         }
       }
+      if (verb === 'worktree' && arg) {
+        const parts = arg.trim().split(/\s+/)
+        const op = parts[0] ?? ''
+        if (op === 'create') {
+          const runId = parts[1] ?? ''
+          const baseMatch = arg.match(/--base\s+(\S+)/)
+          const baseBranch = baseMatch?.[1]
+          if (!runId) return { kind: 'error', text: 'worktree create requires a run id' }
+          const result = recursive.createRunWorktree(root, runId, baseBranch)
+          if (!result.ok) return { kind: 'error', text: result.error ?? 'worktree create failed' }
+          return { kind: 'success', text: 'worktree created: ' + JSON.stringify(result) }
+        }
+        if (op === 'promote') {
+          const fromBranch = parts[1] ?? ''
+          const toBranch = parts[2] ?? ''
+          if (!fromBranch || !toBranch) return { kind: 'error', text: 'worktree promote requires <from> <to>' }
+          const result = recursive.promoteRunBranch(root, fromBranch, toBranch)
+          if (!result.ok) return { kind: 'error', text: result.error ?? 'promote failed' }
+          return { kind: 'success', text: 'promoted: ' + JSON.stringify(result) }
+        }
+        if (op === 'status') {
+          return { kind: 'success', text: 'worktree status: ' + JSON.stringify(recursive.worktreeStatus(root)) }
+        }
+      }
       return executeRecursiveCommand(root, rawInput)
     },
   })

package/src/git-context.ts

@@ -0,0 +1,132 @@
+/**
+ * git-context.ts — live git facts used for worktree + branch awareness (R?).
+ *
+ * Worktree/branch awareness goal: the plugin must know WHICH checkout and
+ * WHICH branch a run is executing in, so Phase 0 records an honest base-vs-
+ * worktree branch split and lint fails when the recorded context no longer
+ * matches live git state.
+ *
+ * Detection primitives:
+ * - `isLinkedWorktree` — a directory is a linked git worktree when its private
+ *   git dir (`git rev-parse --git-dir`) differs from the common git dir
+ *   (`git rev-parse --git-common-dir`). The main checkout has both equal.
+ * - `upstreamBranch` — the current branch's upstream target with the remote
+ *   prefix stripped (origin/main -> main). Used to infer the promotion source
+ *   branch for dev/stage/main workflows.
+ *
+ * Every accessor is total: on missing git or non-git dirs it returns null /
+ * false, never throws. Callers defer rather than fail hard.
+ */
+import { execFileSync } from 'node:child_process'
+
+/** Normalized git facts about one checkout directory. */
+export interface GitRepoFacts {
+  /** SHA of HEAD^{commit}, or null when unresolvable (empty/non-git repo). */
+  headSha: string | null
+  /** Current branch short name via `git symbolic-ref --short HEAD`, null when detached. */
+  branch: string | null
+  /** True when HEAD is detached (no symbolic ref). */
+  detached: boolean
+  /** True when the cwd is a linked worktree (git-dir != git-common-dir). */
+  isWorktree: boolean
+  /** `git rev-parse --git-dir` output (may be relative). */
+  gitDir: string | null
+  /** `git rev-parse --git-common-dir` output (may be relative). */
+  commonDir: string | null
+  /** `git rev-parse --show-toplevel` output, or null. */
+  toplevel: string | null
+  /** Upstream branch with remote prefix stripped (origin/main -> main), null when none/detached. */
+  upstreamBranch: string | null
+}
+
+/** Run git in a repo dir; return trimmed stdout or null on any failure. */
+export function gitRun(repoRoot: string, ...args: string[]): string | null {
+  try {
+    return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+  } catch {
+    return null
+  }
+}
+
+/** True when a non-equal git-dir vs git-common-dir marks a linked worktree. */
+export function isLinkedWorktree(gitDir: string | null, commonDir: string | null): boolean {
+  if (!gitDir || !commonDir) return false
+  return gitDir !== commonDir
+}
+
+/** Strip a remote ref prefix (origin/main -> main, remotes/origin/main -> main). */
+export function stripRemotePrefix(ref: string | null): string | null {
+  if (!ref) return null
+  const trimmed = ref.trim()
+  const short = trimmed.replace(/^refs\/remotes\//, '').replace(/^[^/]+\//, '')
+  return short === '' ? null : short
+}
+
+/**
+ * Gather normalized git facts about `repoRoot`. Total: any git failure
+ * degrades to neutral values (false / null), never throws.
+ */
+export function gitFacts(repoRoot: string): GitRepoFacts {
+  const gitDir = gitRun(repoRoot, 'rev-parse', '--git-dir')
+  const commonDir = gitRun(repoRoot, 'rev-parse', '--git-common-dir')
+  const headSha = gitRun(repoRoot, 'rev-parse', '--verify', 'HEAD^{commit}')
+  const branch = gitRun(repoRoot, 'symbolic-ref', '--quiet', '--short', 'HEAD')
+  const toplevel = gitRun(repoRoot, 'rev-parse', '--show-toplevel')
+  const upstreamRef = gitRun(repoRoot, 'rev-parse', '--abbrev-ref', '@{upstream}')
+  return {
+    headSha,
+    branch: branch || null,
+    detached: !branch,
+    isWorktree: isLinkedWorktree(gitDir, commonDir),
+    gitDir,
+    commonDir,
+    toplevel,
+    upstreamBranch: branch ? stripRemotePrefix(upstreamRef) : null,
+  }
+}
+
+/**
+ * Resolve the effective base branch for a checkout. In a linked worktree this
+ * is the branch the work is based on — best inferred from the upstream target
+ * (dev/stage/main promotion source) when one is configured; otherwise fall
+ * back to the current branch. Returns null only when no branch exists.
+ */
+export function resolveBaseBranch(facts: GitRepoFacts): string | null {
+  if (facts.branch && facts.upstreamBranch && facts.upstreamBranch !== facts.branch) {
+    return facts.upstreamBranch
+  }
+  return facts.branch
+}
+
+/**
+ * Verify a worktree branch is (still) based on the recorded base branch.
+ * Returns { ok, reason }. Fails when the base branch no longer exists, or the
+ * worktree branch no longer contains it (merge-base --is-ancestor fails).
+ * A missing/unresolvable branch degrades to ok:false with a reason; a
+ * non-git dir degrades to ok:true (defer — nothing to verify).
+ */
+export function verifyBranchBase(repoRoot: string, baseBranch: string | null, worktreeBranch: string | null): { ok: boolean; reason: string | null } {
+  if (!baseBranch || !worktreeBranch) return { ok: true, reason: null }
+  const gitDir = gitRun(repoRoot, 'rev-parse', '--git-dir')
+  if (!gitDir) return { ok: true, reason: null }
+  const baseSha = gitRun(repoRoot, 'rev-parse', '--verify', `${baseBranch}^{commit}`)
+  if (!baseSha) return { ok: false, reason: `recorded base branch '${baseBranch}' does not resolve in this checkout` }
+  const wtSha = gitRun(repoRoot, 'rev-parse', '--verify', `${worktreeBranch}^{commit}`)
+  if (!wtSha) return { ok: false, reason: `recorded worktree branch '${worktreeBranch}' does not resolve in this checkout` }
+  // merge-base --is-ancestor <base> <worktree> -> exit 0 means base is an ancestor.
+  try {
+    execFileSync('git', ['-C', repoRoot, 'merge-base', '--is-ancestor', baseBranch, worktreeBranch], { stdio: ['ignore', 'pipe', 'pipe'] })
+    return { ok: true, reason: null }
+  } catch {
+    return { ok: false, reason: `worktree branch '${worktreeBranch}' is not based on recorded base branch '${baseBranch}'` }
+  }
+}
+
+/** Verify the recorded worktree branch matches the live HEAD branch. */
+export function verifyWorktreeBranch(repoRoot: string, recordedBranch: string | null): { ok: boolean; reason: string | null } {
+  if (!recordedBranch) return { ok: true, reason: null }
+  const live = gitRun(repoRoot, 'symbolic-ref', '--quiet', '--short', 'HEAD')
+  if (!live) return { ok: false, reason: 'HEAD is detached; expected branch ' + recordedBranch }
+  if (live !== recordedBranch) return { ok: false, reason: `checkout is on branch '${live}' but 00-worktree.md records '${recordedBranch}'` }
+  return { ok: true, reason: null }
+}

package/src/index.ts

@@ -9,6 +9,7 @@ import { createRecursiveLockTool } from './recursive_lock.tool.ts'
 import { createRecursiveLintTool } from './recursive_lint.tool.ts'
 import { createRecursiveCloseoutTool } from './recursive_closeout.tool.ts'
 import { createRecursiveScratchTool } from './recursive_scratch.tool.ts'
+import { createRecursiveWorktreeTool } from './recursive_worktree.tool.ts'
 import { registerRecursiveCommand } from './commands.ts'
 import { evaluateToolGuard } from './enforcement.ts'
 import { renderRecursivePolicy } from './policy.ts'
@@ -28,6 +29,7 @@ export { createRecursiveLockTool } from './recursive_lock.tool.ts'
 export { createRecursiveLintTool } from './recursive_lint.tool.ts'
 export { createRecursiveCloseoutTool } from './recursive_closeout.tool.ts'
 export { createRecursiveScratchTool } from './recursive_scratch.tool.ts'
+export { createRecursiveWorktreeTool } from './recursive_worktree.tool.ts'
 export * from './status.ts'
 export {
   PHASE_SEQUENCE,
@@ -107,6 +109,7 @@ export function apply(ctx: Context, config?: { shellOnly?: boolean; repoRoot?: s
       ctx.tools.register(createRecursiveLintTool(recursive)),
       ctx.tools.register(createRecursiveCloseoutTool(recursive)),
       ctx.tools.register(createRecursiveScratchTool(recursive)),
+      ctx.tools.register(createRecursiveWorktreeTool(recursive)),
     ]
 
     // /recursive command (R4): preset-scoped registration, workspace-scoped dispatch.

package/src/init-templates.ts

@@ -12,6 +12,7 @@
 import { execFileSync } from 'node:child_process'
 import { join } from 'node:path'
 import { getArtifactRequiredSections } from './phase-rules.ts'
+import { gitFacts, resolveBaseBranch, type GitRepoFacts } from './git-context.ts'
 
 export interface GitContext {
   baselineType: string
@@ -23,6 +24,10 @@ export interface GitContext {
   baseBranch: string
   worktreeBranch: string
   baseCommit: string
+  /** True when the init cwd is a linked git worktree (git-dir != git-common-dir). */
+  isWorktree: boolean
+  /** Upstream branch with the remote prefix stripped (origin/dev -> dev), null when none/detached. */
+  upstreamBranch: string | null
   notes: string
 }
 
@@ -42,7 +47,13 @@ export function detectGitContext(repoRoot: string): { context: Partial<GitContex
   if (!headSha) {
     return { context: {}, error: 'Unable to resolve HEAD commit for Phase 0 diff basis prefill: git rev-parse returned no output' }
   }
-  const branch = run(['symbolic-ref', '--quiet', '--short', 'HEAD']) || '(detached HEAD)'
+  const facts: GitRepoFacts = gitFacts(repoRoot)
+  const branch = facts.branch ?? '(detached HEAD)'
+  // Distinct base branch: in a linked worktree the work is based on the branch
+  // whose upstream target is the promotion source (dev/stage/main). When no
+  // upstream is configured, fall back to the current branch so the recorded
+  // base is always a resolvable ref.
+  const baseBranch = resolveBaseBranch(facts) ?? branch
   const diffCommand = 'git diff --name-only ' + headSha
   return {
     context: {
@@ -52,9 +63,11 @@ export function detectGitContext(repoRoot: string): { context: Partial<GitContex
       normalizedBaseline: headSha,
       normalizedComparison: 'working-tree',
       normalizedDiffCommand: diffCommand,
-      baseBranch: branch,
+      baseBranch,
       worktreeBranch: branch,
       baseCommit: headSha,
+      isWorktree: facts.isWorktree,
+      upstreamBranch: facts.upstreamBranch,
       notes: 'recursive-init prefilled this executable diff basis from the current HEAD commit. If Phase 0 later changes the chosen baseline, update every diff-basis field and rerun lint before locking.',
     },
     error: null,

package/src/recursive_init.tool.ts

@@ -5,20 +5,26 @@ import type { RecursiveRuntime } from './runtime.ts'
 export function createRecursiveInitTool(recursive: RecursiveRuntime) {
   return defineTool({
     name: 'recursive_init',
-    description: 'Scaffold a new recursive-mode run directory (or ensure an existing one) with stub artifact headers. Delegates to the RecursiveRuntime service (no duplicated scaffolding logic).',
+    description: 'Scaffold a new recursive-mode run directory (or ensure an existing one) with stub artifact headers. Delegates to the RecursiveRuntime service (no duplicated scaffolding logic). When createWorktree is true, a linked worktree is created first and the run is scaffolded inside it.',
     parameters: {
       runId: { type: 'string', description: 'Run id (e.g. 03-something). Required.' },
+      createWorktree: { type: 'boolean', description: 'If true, create a linked worktree at .worktrees/<runId>/ and scaffold the run inside it (default: false).' },
+      baseBranch: { type: 'string', description: 'Base branch the worktree branch is cut from (default: current HEAD branch). Only used when createWorktree is true.' },
     },
     output: {
       schema: { type: 'json' },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
-    async execute(args: { runId?: string }, exec) {
+    async execute(args: { runId?: string; createWorktree?: boolean; baseBranch?: string }, exec) {
       if (!args.runId || args.runId.trim() === '') {
         return { error: 'runId is required' } as const
       }
       try {
-        const result = await recursive.initRun(args.runId.trim(), exec.agent as { session?: { header?: { cwd?: string } } } | null)
+        const result = await recursive.initRun(
+          args.runId.trim(),
+          exec.agent as { session?: { header?: { cwd?: string } } } | null,
+          { createWorktree: args.createWorktree === true, baseBranch: args.baseBranch?.trim() || undefined },
+        )
         return result as unknown as JsonValue
       } catch (err) {
         return { error: err instanceof Error ? err.message : String(err) } as const

package/src/recursive_worktree.tool.ts

@@ -0,0 +1,54 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import type { RecursiveRuntime } from './runtime.ts'
+
+/**
+ * `recursive_worktree` — create a linked git worktree for a run and/or
+ * promote a branch up the dev/stage/main chain. Workspace-scoped: the
+ * operations run under the SESSION's control-plane root only.
+ */
+export function createRecursiveWorktreeTool(recursive: RecursiveRuntime) {
+  return defineTool({
+    name: 'recursive_worktree',
+    description: 'Create a linked git worktree for a recursive-mode run and/or promote a branch up the dev/stage/main chain. Workspace-scoped under the current session workspace.',
+    parameters: {
+      runId: { type: 'string', description: 'Run id the worktree is created for (e.g. 03-something). Required for create.' },
+      action: { type: 'string', description: 'create | promote | status. Default: create.' },
+      fromBranch: { type: 'string', description: 'Source branch for a promote action (the branch holding the new commits).' },
+      toBranch: { type: 'string', description: 'Promotion target branch for a promote action (feature -> dev -> stage -> main).' },
+      baseBranch: { type: 'string', description: 'Base branch the worktree branch is cut from (default: current HEAD branch).' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: { action?: string; runId?: string; fromBranch?: string; toBranch?: string; baseBranch?: string }, exec) {
+      const action = args.action ?? 'create'
+      // Resolve the control-plane root: agent cwd first, repoRoot fallback (B4),
+      // so tests and headless callers work without a live session header.
+      const root = await recursive.resolveRootFor(exec.agent as { session?: { header?: { cwd?: string } } } | null)
+      if (!root) {
+        return { error: 'session is not attached to a registered workspace (cannot resolve control-plane root)' } as const
+      }
+      if (action === 'create') {
+        if (!args.runId || args.runId.trim() === '') {
+          return { error: 'runId is required for create' } as const
+        }
+        const result = recursive.createRunWorktree(root, args.runId.trim(), args.baseBranch?.trim() || undefined)
+        return result as unknown as JsonValue
+      }
+      if (action === 'promote') {
+        if (!args.fromBranch || !args.toBranch) {
+          return { error: 'fromBranch and toBranch are required for promote' } as const
+        }
+        const result = recursive.promoteRunBranch(root, args.fromBranch.trim(), args.toBranch.trim())
+        return result as unknown as JsonValue
+      }
+      if (action === 'status') {
+        const result = recursive.worktreeStatus(root)
+        return result as unknown as JsonValue
+      }
+      return { error: 'action must be create | promote | status' } as const
+    },
+  })
+}

package/src/runtime.ts

@@ -26,6 +26,8 @@ import { resolveEnforcementConfig, DEFAULT_ENFORCEMENT, evaluatePreStepGate, eva
 import type { Session } from '@deepseek-ai/dsh-session'
 import { renderRecursivePolicy, type PolicyContext } from './policy.ts'
 import { snapshotWorkspace } from './snapshot.ts'
+import { createLinkedWorktree, promoteBranch, listWorktrees, defaultWorktreeBranch, type CreateWorktreeResult, type PromoteBranchResult } from './worktree.ts'
+import { gitFacts } from './git-context.ts'
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -343,11 +345,24 @@ export class RecursiveRuntime extends Service {
    * required section (get_artifact_required_sections) + TODO + FAIL gates.
    * Also scaffolds addenda/subagents/router-prompts/evidence dirs. Returns the
    * run dir + created artifacts.
+   *
+   * When `opts.createWorktree` is true, a linked worktree is first created at
+   * `.worktrees/<runId>/` and the run is scaffolded INSIDE it (per the
+   * "all subsequent phases execute in worktree context" rule). The worktree
+   * branch defaults to `recursive/<runId>` and is cut from `opts.baseBranch`
+   * (default: current HEAD branch of the root checkout).
    */
-  async initRun(runId: string, agent?: { session?: { header?: { cwd?: string } } } | null): Promise<{ runDir: string; runId: string; created: string[]; existing: string[] }> {
+  async initRun(runId: string, agent?: { session?: { header?: { cwd?: string } } } | null, opts?: { createWorktree?: boolean; baseBranch?: string }): Promise<{ runDir: string; runId: string; created: string[]; existing: string[]; worktree?: CreateWorktreeResult }> {
     const root = await this.resolveRootFor(agent)
     if (!root) throw new Error('cannot resolve workspace control-plane root for this session')
-    const runDir = join(root, '.recursive', 'run', runId)
+    let scaffoldRoot = root
+    let worktree: CreateWorktreeResult | undefined
+    if (opts?.createWorktree) {
+      worktree = createLinkedWorktree({ repoRoot: root, runId, baseBranch: opts.baseBranch })
+      if (!worktree.ok) throw new Error(worktree.error ?? 'worktree create failed')
+      scaffoldRoot = worktree.worktreeDir
+    }
+    const runDir = join(scaffoldRoot, '.recursive', 'run', runId)
     mkdirSync(runDir, { recursive: true })
     const created: string[] = []
     const existing: string[] = []
@@ -360,13 +375,14 @@ export class RecursiveRuntime extends Service {
       created.push(dir + '/')
     }
 
-    // Git context for the Phase 0 diff-basis prefill (canonical parity).
-    const { context: gitContext, error: prefillError } = detectGitContext(root)
+    // Git context for the Phase 0 diff-basis prefill (canonical parity). When a
+    // worktree was created, the git context + Phase 0 record the WORKTREE.
+    const { context: gitContext, error: prefillError } = detectGitContext(scaffoldRoot)
 
     // Phase 0 templates: byte-identical to canonical recursive-init.py.
     const phase0: Array<[string, string]> = [
       ['00-requirements.md', requirementsContent(runId, 'feature', '')],
-      ['00-worktree.md', worktreeContent(runId, root, gitContext, prefillError)],
+      ['00-worktree.md', worktreeContent(runId, scaffoldRoot, gitContext, prefillError)],
     ]
     for (const [file, content] of phase0) {
       const path = join(runDir, file)
@@ -395,7 +411,42 @@ export class RecursiveRuntime extends Service {
       created.push(file)
     }
 
-    return { runDir, runId, created, existing }
+    const result: { runDir: string; runId: string; created: string[]; existing: string[]; worktree?: CreateWorktreeResult } = { runDir, runId, created, existing }
+    if (worktree) result.worktree = worktree
+    return result
+  }
+
+  /**
+   * Create a linked worktree for a run under the given workspace root. The
+   * worktree branch defaults to `recursive/<runId>` and is cut from the given
+   * base branch (default: the current HEAD branch of the root checkout).
+   * Refuses to create over an existing run directory. Workspace-scoped.
+   */
+  createRunWorktree(root: string, runId: string, baseBranch?: string): CreateWorktreeResult {
+    return createLinkedWorktree({ repoRoot: root, runId, baseBranch })
+  }
+
+  /**
+   * Promote a branch up the dev/stage/main chain (fast-forward). Workspace-scoped.
+   */
+  promoteRunBranch(root: string, fromBranch: string, toBranch: string): PromoteBranchResult {
+    return promoteBranch({ repoRoot: root, fromBranch, toBranch })
+  }
+
+  /**
+   * Worktree + branch status for a workspace root: the linked worktrees,
+   * which branch each is on, and the current checkout's base/upstream context.
+   */
+  worktreeStatus(root: string): Record<string, unknown> {
+    const facts = gitFacts(root)
+    const worktrees = listWorktrees(root)
+    return {
+      root,
+      isWorktree: facts.isWorktree,
+      branch: facts.branch,
+      upstreamBranch: facts.upstreamBranch,
+      worktrees,
+    }
   }
 
   /**