@try-works/dsh-recursive-mode 0.4.4 → 0.4.6

package/src/recursive_closeout.tool.ts

@@ -1,36 +1,54 @@
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import { toolError } from './errors.ts'
-import type { JsonValue } from '@deepseek-ai/dsh-util-values'
-import type { RecursiveRuntime } from './runtime.ts'
-
-/**
- * `recursive_closeout` — scaffold a Phase 0-8 closeout receipt under the
- * SESSION's workspace only (R1 workspace-scoping invariant). The run is resolved
- * via the session agent's cwd -> workspace registry; a runId outside the current
- * workspace is rejected.
- */
-export function createRecursiveCloseoutTool(recursive: RecursiveRuntime) {
-  return defineTool({
-    name: 'recursive_closeout',
-    description: 'REPORT what a closeout phase artifact is missing (Phase 4-8): it reads the artifact, lists the required sections and gates that are absent, and records a closeout receipt of its own. It NEVER writes the phase document. For a run in the CURRENT session workspace only. Workspace-scoped: refuses runIds outside the session\'s workspace. Delegates to the RecursiveRuntime service.',
-    parameters: {
-    phase: { type: 'string', description: 'Closeout phase to report on: 04, 05, 06, 07 or 08 (the same phase keys recursive_status prints). Phase 08 additionally fires the training trigger when it has been closed out before.' },
-      runId: { type: 'string', description: 'Run id (e.g. 03-something). Required. Must resolve inside the current workspace.' },
-    },
-    output: {
-      schema: { type: 'json' },
-      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
-    },
-    async execute(args: { phase?: string; runId?: string }, exec) {
-      if (!args.phase || !args.runId || args.runId.trim() === '') {
-        return { error: toolError('MISSING_PHASE_AND_RUN') } as const
-      }
-      const root = await recursive.resolveWorkspaceRoot(exec.agent)
-      if (!root) {
-        return { error: toolError('NO_WORKSPACE') } as const
-      }
-      const result = await recursive.closeoutRun(root, args.runId.trim(), args.phase.trim(), exec.agent as { session?: { header?: { cwd?: string } } } | null)
-      return result as unknown as JsonValue
-    },
-  })
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { toolError } from './errors.ts'
+import { RUN_ID_EXAMPLES, RUN_ID_RULE, runIdProblem } from './run-id.ts'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import type { RecursiveRuntime } from './runtime.ts'
+
+/**
+ * `recursive_closeout` — scaffold a Phase 0-8 closeout receipt under the
+ * SESSION's workspace only (R1 workspace-scoping invariant). The run is resolved
+ * via the session agent's cwd -> workspace registry; a runId outside the current
+ * workspace is rejected.
+ *
+ * A RUN ID IS A NAME, NOT A PATH HERE TOO, and "outside the current workspace is rejected" is NOT enough
+ * on its own: `closeoutRun` joins the id onto the run layer and then writes a receipt under it, and its
+ * scoping check is `runDir.startsWith(runRoot)` — a string prefix test, not containment. A `..\` segment
+ * that lands on a SIBLING of the run layer passes that check whenever the sibling's name begins with
+ * `run`, so a path-shaped id can still receive a write. MEASURED pre-fix: `..\run-away` and `../run-away`
+ * were accepted and reached the report; the other shapes below were stopped only by the sibling not
+ * existing, which is the operator's filesystem deciding, not the tool. The rule is `run-id.ts`; this
+ * boundary is where the name enters, so this is where it is refused, with `recursive_init`'s refusal shape
+ * — `BAD_RUN_ID` (RM1107), same detail sentence.
+ */
+export function createRecursiveCloseoutTool(recursive: RecursiveRuntime) {
+  return defineTool({
+    name: 'recursive_closeout',
+    description: 'REPORT what a closeout phase artifact is missing (Phase 4-8): it reads the artifact, lists the required sections and gates that are absent, and records a closeout receipt of its own. It NEVER writes the phase document. For a run in the CURRENT session workspace only. Workspace-scoped: refuses runIds outside the session\'s workspace. Delegates to the RecursiveRuntime service.',
+    parameters: {
+    phase: { type: 'string', description: 'Closeout phase to report on: 04, 05, 06, 07 or 08 (the same phase keys recursive_status prints). Phase 08 additionally fires the training trigger when it has been closed out before.' },
+      runId: { type: 'string', description: 'Run id — the NAME of the run directory under .recursive/run/ (e.g. 03-something), never a path: ' + RUN_ID_RULE + '. Required. Must resolve inside the current workspace.' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: { phase?: string; runId?: string }, exec) {
+      if (!args.phase || !args.runId || args.runId.trim() === '') {
+        return { error: toolError('MISSING_PHASE_AND_RUN') } as const
+      }
+      const runId = args.runId.trim()
+      // BEFORE `closeoutRun`, which joins the id onto the run layer and writes the closeout receipt under
+      // whatever directory it resolved to.
+      const problem = runIdProblem(runId)
+      if (problem !== null) {
+        return { error: toolError('BAD_RUN_ID', problem + ' - run ids allow ' + RUN_ID_RULE + ' - e.g. ' + RUN_ID_EXAMPLES) } as const
+      }
+      const root = await recursive.resolveWorkspaceRoot(exec.agent)
+      if (!root) {
+        return { error: toolError('NO_WORKSPACE') } as const
+      }
+      const result = await recursive.closeoutRun(root, runId, args.phase.trim(), exec.agent as { session?: { header?: { cwd?: string } } } | null)
+      return result as unknown as JsonValue
+    },
+  })
 }

package/src/recursive_init.tool.ts

@@ -1,14 +1,38 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { codeRuntimeRefusal, toolError } from './errors.ts'
+import { RUN_ID_EXAMPLES, RUN_ID_RULE, runIdProblem } from './run-id.ts'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
 
+/**
+ * PHASE 0 — SCAFFOLDING IS NOT STARTING, AND THE TOOL SAYS SO AT THE MOMENT IT MATTERS.
+ *
+ * A spec may legitimately exist before a run does: this tool writes the run directory and every phase
+ * document, and it still does. What it must NOT do is start the run, because starting is creating and
+ * arming the goal the harness drives autonomous rounds from. That is the owner's rule — *"phase 0
+ * requires explicit approval to start a run and goal"* — so the description below names the gate and the
+ * result carries `runStartApproval`, which is the pointer a caller needs: the run is inert until
+ * `recursive_ask` answers `run-start`.
+ *
+ * `runStartApproval` is read from the run's own Phase 0 artifact on every call, so it is the TRUE state
+ * rather than "this call created something": re-initialising an APPROVED run reports `approved: true`
+ * (and the run keeps its goal), which is what a caller re-scaffolding a run it already started needs to
+ * see.
+ *
+ * AND A RUN ID IS A NAME, NOT A PATH. This is the boundary where the name enters, so it is the boundary
+ * that refuses a path-shaped one — loudly, and before `initRun` can mkdir anything. The check lives here
+ * (through the shared `run-id.ts` rule) rather than in `runtime.ts` because `initRun` is not the only
+ * caller and because the runtime's `join(root, '.recursive', 'run', runId)` is CORRECT for a name; what
+ * was missing was a gate on the name. Teaching the runtime to accept a path would silently relocate the
+ * run layer instead of rejecting the call. See `run-id.ts` for the rule, the evidence behind it, and the
+ * "do not fix this back" note.
+ */
 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). When createWorktree is true, a linked worktree is created first and the run is scaffolded inside it.',
+    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. THIS DOES NOT START THE RUN: no goal exists until the user approves phase 0 through recursive_ask gate=run-start, so the result carries runStartApproval — read it and ask. The runId is the NAME of the run directory under .recursive/run/ and is never a path (see the parameter description): a path-shaped runId is refused before anything is written.',
     parameters: {
-      runId: { type: 'string', description: 'Run id (e.g. 03-something). Required.' },
+      runId: { type: 'string', description: 'Run id — the NAME of the run directory under .recursive/run/ (e.g. 03-something, 01-calculator-lib), never a path: ' + RUN_ID_RULE + '. A run on another drive or inside a worktree is reached with recursive_worktree, not by passing a path here. 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.' },
     },
@@ -17,12 +41,19 @@ export function createRecursiveInitTool(recursive: RecursiveRuntime) {
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
     async execute(args: { runId?: string; createWorktree?: boolean; baseBranch?: string }, exec) {
-      if (!args.runId || args.runId.trim() === '') {
+      const runId = args.runId?.trim() ?? ''
+      if (runId === '') {
         return { error: toolError('MISSING_RUN_ID') } as const
       }
+      // BEFORE `initRun`: that call starts with `mkdirSync(runDir, { recursive: true })`, so a
+      // path-shaped id that reaches it has already made the operator-visible mess it was refused for.
+      const problem = runIdProblem(runId)
+      if (problem !== null) {
+        return { error: toolError('BAD_RUN_ID', problem + ' - run ids allow ' + RUN_ID_RULE + ' - e.g. ' + RUN_ID_EXAMPLES) } as const
+      }
       try {
         const result = await recursive.initRun(
-          args.runId.trim(),
+          runId,
           exec.agent as { session?: { header?: { cwd?: string } } } | null,
           { createWorktree: args.createWorktree === true, baseBranch: args.baseBranch?.trim() || undefined },
         )

package/src/recursive_phase.tool.ts

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { toolError } from './errors.ts'
+import { RUN_ID_EXAMPLES, RUN_ID_RULE, runIdProblem } from './run-id.ts'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
 
@@ -9,20 +10,39 @@ import type { RecursiveRuntime } from './runtime.ts'
  * (runtime.phaseRules -> phaseRulesFor) as the once-per-phase pre-step
  * reminder, so the agent can re-ask for the rules without re-injecting them on
  * every step. Returns { error } when no active phase is found.
+ *
+ * A RUN ID IS A NAME, NOT A PATH HERE TOO, INCLUDING WHEN IT IS OMITTED. Omitted and path-shaped are
+ * different cases and must stay different: omitted means "the latest run by mtime", which `resolveRunDir`
+ * answers by DISCOVERY rather than by joining anything, and that case is untouched below. A path-shaped id,
+ * by contrast, is joined by `phaseRules` -> `resolveRunDir` and then read, and `recordInjection` WRITES
+ * `memory-injections.json` under whatever directory it resolved to — with no scoping check at all on this
+ * path. So the gate fires only on an id that was actually supplied, and `run-id.ts` owns the rule. The
+ * refusal is `recursive_init`'s, `BAD_RUN_ID` (RM1107), composed identically.
  */
 export function createRecursivePhaseTool(recursive: RecursiveRuntime) {
   return defineTool({
     name: 'recursive_phase',
     description: 'Return the lint rules + instructions for the current recursive-mode phase (required sections, gates, TDD/QA notes). Call once when entering a new phase; the same rules are also auto-injected once per phase transition.',
     parameters: {
-      runId: { type: 'string', description: 'Optional run id (defaults to the latest run by mtime)' },
+      runId: { type: 'string', description: 'Optional run id — the NAME of the run directory under .recursive/run/ (e.g. 03-something), never a path: ' + RUN_ID_RULE + '. Omit it for the latest run by mtime.' },
     },
     output: {
       schema: { type: 'json' },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
     async execute(args: { runId?: string }, exec) {
-      const result = await recursive.phaseRules(args.runId, exec.agent as { session?: { header?: { cwd?: string } } } | null)
+      // ABSENT IS NOT INVALID. No runId at all keeps its documented meaning — the latest run by mtime,
+      // resolved by discovery in `resolveRunDir` — so the gate below runs only when a name was supplied,
+      // while an EMPTY one is refused rather than silently read as "latest": a caller that passed `""` did
+      // not ask for discovery, and `resolveRunDir` would otherwise interpret their mistyped id as one.
+      const runId = args.runId?.trim()
+      if (runId !== undefined) {
+        const problem = runId === '' ? 'runId is empty' : runIdProblem(runId)
+        if (problem !== null) {
+          return { error: toolError('BAD_RUN_ID', problem + ' - run ids allow ' + RUN_ID_RULE + ' - e.g. ' + RUN_ID_EXAMPLES) } as const
+        }
+      }
+      const result = await recursive.phaseRules(runId, exec.agent as { session?: { header?: { cwd?: string } } } | null)
       if (!result) return { error: toolError('NO_PHASE') } as const
       return result as unknown as JsonValue
     },

package/src/recursive_scratch.tool.ts

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { toolError } from './errors.ts'
+import { RUN_ID_EXAMPLES, RUN_ID_RULE, runIdProblem } from './run-id.ts'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
 
@@ -7,6 +8,16 @@ import type { RecursiveRuntime } from './runtime.ts'
  * `recursive_scratch` — read/write/append the run-scoped disposable scratchpad
  * (R5) under the CURRENT session workspace only (R1). Scratch is git-ignored
  * and never citable as an Input.
+ *
+ * A RUN ID IS A NAME, NOT A PATH HERE TOO. `scratchRun` joins it onto the run layer, and it then WRITES
+ * (write/append) into the directory it landed on, so a path-shaped id does not merely fail to find a run:
+ * with a `..\` segment it can find and write into a SIBLING of the run layer, because the runtime's
+ * workspace-scoping check is `runDir.startsWith(runRoot)` — a string prefix test, not containment — and a
+ * sibling directory whose name begins with `run` passes it. MEASURED pre-fix: `..\run-away` was accepted
+ * and `scratchRun` wrote `scratch.md` into `<workspace>\.recursive\run-away\scratch\`. The rule is
+ * `run-id.ts`; the gate sits here, at the boundary where the name enters, rather than in `scratchRun`, for
+ * the same reason `recursive_init`'s does. Refusal shape is `recursive_init`'s, `BAD_RUN_ID` (RM1107),
+ * composed identically: one rule, one message.
  */
 export function createRecursiveScratchTool(recursive: RecursiveRuntime) {
   return defineTool({
@@ -14,7 +25,7 @@ export function createRecursiveScratchTool(recursive: RecursiveRuntime) {
     description: 'Read, write, or append the run-scoped disposable scratchpad (scratch/scratch.md or scratch/scratch.ts) for a run in the CURRENT session workspace. Workspace-scoped; scratch is git-ignored and never citable as an Input.',
     parameters: {
       action: { type: 'string', description: 'read | write | append. Required.' },
-      runId: { type: 'string', description: 'Run id (e.g. 03-something). Required; must resolve inside the current workspace.' },
+      runId: { type: 'string', description: 'Run id — the NAME of the run directory under .recursive/run/ (e.g. 03-something), never a path: ' + RUN_ID_RULE + '. Required; must resolve inside the current workspace.' },
       target: { type: 'string', description: 'md | ts. Required.' },
       content: { type: 'string', description: 'Content for write/append. Optional for read.' },
     },
@@ -29,6 +40,11 @@ export function createRecursiveScratchTool(recursive: RecursiveRuntime) {
       if (!action || !runId || !target) {
         return { error: toolError('MISSING_SCRATCH_ARGS') } as const
       }
+      // BEFORE `scratchRun`, which joins the id onto the run layer and then writes through it.
+      const problem = runIdProblem(runId)
+      if (problem !== null) {
+        return { error: toolError('BAD_RUN_ID', problem + ' - run ids allow ' + RUN_ID_RULE + ' - e.g. ' + RUN_ID_EXAMPLES) } as const
+      }
       if (target !== 'md' && target !== 'ts') {
         return { error: toolError('BAD_TARGET') } as const
       }

package/src/recursive_worktree.tool.ts

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { toolError } from './errors.ts'
+import { RUN_ID_EXAMPLES, RUN_ID_RULE, runIdProblem } from './run-id.ts'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
 
@@ -7,13 +8,29 @@ 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.
+ *
+ * A RUN ID IS A NAME, NOT A PATH HERE TOO, and this is the worst place to be without the rule: a `create`
+ * builds TWO things out of the id — the linked worktree directory `.worktrees/<runId>` AND the git branch
+ * `recursive/<runId>` (git accepts '/' inside a ref) — so a path-shaped id used to leave a worktree and a
+ * ref behind, not just a folder. MEASURED pre-fix, per id, against a fresh repo: `nested/child-run`
+ * returned ok:true and created BOTH `.worktrees/nested/child-run` and
+ * `refs/heads/recursive/nested/child-run`, while the shapes git itself refuses as ref syntax
+ * (`recursive//tmp/x`, `recursive/C:…`, `.hidden-run`, a trailing space) failed the worktree add and
+ * created neither. The rule is `run-id.ts` and is not restated here; the gate sits at this boundary, ahead
+ * of `createRunWorktree`, so the refusal no longer depends on git happening to dislike the ref name.
+ *
+ * The refusal is `BAD_RUN_ID` (RM1107), composed exactly as `recursive_init` composes it — same code, same
+ * detail, same sentence. One message for one rule is what keeps a caller from having to learn a second
+ * vocabulary for the same defect, and the shared remedy it carries ("call recursive_init again") is right
+ * for this tool as well: a `create` for a run that does not exist yet is exactly what `recursive_init`
+ * with `createWorktree: true` does.
  */
 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.' },
+      runId: { type: 'string', description: 'Run id the worktree is created for — the NAME of the run (e.g. 03-something), never a path: ' + RUN_ID_RULE + '. A path-shaped id is refused for create. 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).' },
@@ -35,7 +52,15 @@ export function createRecursiveWorktreeTool(recursive: RecursiveRuntime) {
         if (!args.runId || args.runId.trim() === '') {
           return { error: toolError('MISSING_CREATE_RUN_ID') } as const
         }
-        const result = recursive.createRunWorktree(root, args.runId.trim(), args.baseBranch?.trim() || undefined)
+        const runId = args.runId.trim()
+        // BEFORE `createRunWorktree`: that call builds `.worktrees/<runId>` and cuts the branch
+        // `recursive/<runId>`, so a path-shaped id that reaches it has already created both. The gate is
+        // on the name; `run-id.ts` says why the join itself is not the thing to change.
+        const problem = runIdProblem(runId)
+        if (problem !== null) {
+          return { error: toolError('BAD_RUN_ID', problem + ' - run ids allow ' + RUN_ID_RULE + ' - e.g. ' + RUN_ID_EXAMPLES) } as const
+        }
+        const result = recursive.createRunWorktree(root, runId, args.baseBranch?.trim() || undefined)
         return result as unknown as JsonValue
       }
       if (action === 'promote') {

package/src/run-id.ts

@@ -0,0 +1,100 @@
+/**
+ * A RUN ID IS A NAME, NOT A PATH.
+ *
+ * WHY THIS MODULE EXISTS. Every consumer of a run id JOINS it onto a directory
+ * that already carries the meaning "the run layer":
+ *
+ *     join(root, '.recursive', 'run', runId)   // runtime.ts, run.ts, handoff.ts, scratch.ts
+ *     join(repoRoot, '.worktrees', runId)      // worktree.ts (a linked worktree)
+ *     'recursive/' + runId                     // worktree.ts (the run's git branch)
+ *
+ * `join` is a PATH operation: absolute paths, drive specifiers and `..` segments
+ * are all legal input to it, and each one silently changes what the call means.
+ * A caller who passes `E:\tmp\rm-live-diagnostics\01-calculator-lib` is asking
+ * for a run "on another drive"; what they get is a `mkdir` of
+ *
+ *     <workspace>\.recursive\run\E:\tmp\rm-live-diagnostics\01-calculator-lib
+ *
+ * which is not drive-qualified at all — on POSIX and Windows alike the colon is
+ * just another character in a relative component. The result is a bogus nested
+ * folder INSIDE the workspace, created before anything can refuse it, surfacing
+ * far away as an ENOENT-shaped runtime failure (RM5501) with the operator's
+ * filesystem already dirty.
+ *
+ * SO THE RULE IS ENFORCED WHERE THE NAME ENTERS, and NOT by teaching the runtime
+ * to accept a path. The joins in `runtime.ts` are CORRECT for a name; what was
+ * missing was a gate on the name. Do not "fix" this back: a run on another drive
+ * or in a worktree is reached through the session's control-plane root
+ * (`recursive_worktree`, `00-worktree.md`) — the run layer is never relocated by
+ * smuggling a path into the id.
+ *
+ * The charset below is deliberately the SAME one the read path already uses
+ * (`live-route.ts` `DOC_SAFE_RE`) so a name this gate accepts is a name that
+ * route can serve.
+ */
+
+/**
+ * The accepted shape, as prose that can be embedded in a model-facing parameter
+ * description and in a refusal detail, so the rule is stated once.
+ */
+export const RUN_ID_RULE = 'letters, digits, dot, underscore or dash only, no leading or trailing dot, no path separator, no drive specifier and no ".." segment'
+
+/** Two ids in the shapes the scaffold convention actually produces. */
+export const RUN_ID_EXAMPLES = '01-calculator-lib, fixture-run'
+
+/**
+ * Longest run id accepted. Directory-name components cap at 255 bytes on NTFS
+ * and ext4; a run id also becomes a git ref component (`recursive/<runId>`) and
+ * a prefix of every lock/receipt filename inside the run, so the ceiling is set
+ * well below the filesystem limit rather than at it.
+ */
+export const RUN_ID_MAX_LENGTH = 100
+
+/** Directory-name charset — the read path's `DOC_SAFE_RE`, verbatim. */
+const RUN_ID_CHARS = /^[A-Za-z0-9._-]+$/
+
+/**
+ * Why a run id is refused, or `null` when it is a usable NAME.
+ *
+ * The returned string is the SPECIFIC problem (which rule the id broke), with no
+ * trailing punctuation and no sentence of its own, so a caller can hand it to
+ * `toolError('BAD_RUN_ID', …)` as the detail. `RUN_ID_RULE` states the shape.
+ *
+ * The order of the checks is part of the message quality: a Windows absolute
+ * path is reported as a drive-qualified path (what the caller passed) rather
+ * than as a separator complaint (what that path is made of).
+ */
+export function runIdProblem(raw: string): string | null {
+  if (raw === '') return 'runId is empty'
+  if (raw.length > RUN_ID_MAX_LENGTH) return 'runId is ' + raw.length + ' characters, over the ' + RUN_ID_MAX_LENGTH + ' allowed'
+  // A Windows drive-QUALIFIED path (`E:\x`, and the drive-relative `E:x` too).
+  if (/^[A-Za-z]:/.test(raw)) return 'runId is a Windows drive-qualified path, starting with "' + raw.slice(0, 2) + '"'
+  // Path separators: an absolute POSIX path, a UNC path, or any nested path.
+  if (raw.includes('/') || raw.includes('\\')) {
+    return 'runId contains the path separator "' + (raw.includes('/') ? '/' : '\\') + '"'
+  }
+  // A colon that is not a drive prefix is still unmappable on Windows (NTFS
+  // alternate data streams), and the run id is a Windows directory name.
+  if (raw.includes(':')) return 'runId contains a colon (":"), which is a drive and stream separator on Windows'
+  // `..` makes the join resolve to the PARENT of the run layer.
+  if (raw.includes('..')) return 'runId contains a ".." segment, which escapes the run directory'
+  // `.` and `..` are the parent/current directory segments, and a trailing dot is
+  // stripped by the Win32 path parser — `03-foo.` and `03-foo` would then be two
+  // names for one directory.
+  if (raw.startsWith('.')) return 'runId starts with ".", which makes it a hidden name or a relative path segment'
+  if (raw.endsWith('.')) return 'runId ends with "."'
+  if (!RUN_ID_CHARS.test(raw)) {
+    // Whitespace inside the name is called out separately because the caller can
+    // see the id they typed and cannot see why it is refused: the tool trims the
+    // ENDS (so `" 03-x "` already names `03-x`), but an interior space is not
+    // normalized anywhere and would create a directory the caller cannot retype.
+    if (/\s/.test(raw)) return 'runId contains a space or other whitespace character inside the name'
+    return 'runId contains a character outside the allowed set'
+  }
+  return null
+}
+
+/** True when `raw` is a usable run NAME. Convenience for callers that only branch. */
+export function isValidRunId(raw: string): boolean {
+  return runIdProblem(raw) === null
+}

package/src/run-start.ts

@@ -0,0 +1,129 @@
+/**
+ * PHASE 0 — STARTING A RUN IS A HUMAN DECISION, NOT A SIDE EFFECT OF SCAFFOLDING.
+ *
+ * THE DEFECT THIS CLOSES. `recursive_init` scaffolded a run and the plugin then CREATED AND ARMED a
+ * goal for it in the same breath (`syncRunGoal`'s "no current goal -> create and arm" branch). A goal
+ * is not a label: `goals.create` returns an ARMED view, and the harness immediately begins driving
+ * autonomous goal rounds for the session. So asking for a run spec was enough to start an unattended
+ * run — the owner's rule is the opposite: *"creating a spec before a run exists should not create a
+ * goal. Phase 0 requires explicit approval to start a run and goal."*
+ *
+ * WHAT "APPROVAL" IS, EXACTLY. The approving label of the `run-start` gate of `recursive_ask`
+ * (`Start run`, as opposed to `Hold`), recorded here as a durable `- Run Start: Start run` line in the
+ * run's Phase 0 requirements artifact. Three things make that an explicit human act rather than an
+ * inference:
+ *
+ *   1. NO DEFAULT, AND THE VALUE IS THE DECISION. The line is written by the gate itself into the Phase 0
+ *      requirements document, and the gate REFUSES an answer that is not one of the labels it offered.
+ *      An unoffered answer is a transcription error wearing the shape of a decision, and a `Hold` is not
+ *      an approval in any spelling — see {@link readRunStartApproval}, which matches the approving VALUE
+ *      and nothing else, so the presence of a `Run Start` line is never on its own consent.
+ *   2. IT IS ASKED, NOT ASSUMED. When the composition mounts `ctx.userQuestions` — the harness's own
+ *      blocking human channel, the same one plan-mode's exit uses — the question is PUT TO THE PERSON and
+ *      only their selection is recorded; a caller-supplied answer cannot stand in for it. A channel that
+ *      RESOLVES with an answer the gate does not recognise is a person's decision the gate cannot record
+ *      and it ends the call (RM5504). A channel that FAILS ends the call too (RM5503), naming the cause the
+ *      channel threw — and there the caller may take the relayed route deliberately, with `relay=true`,
+ *      which the result reports as `source: "relayed"` rather than as a person's own selection, so a
+ *      composition whose channel cannot deliver the question can still start a run. A failure that means
+ *      the question was cancelled, aborted, or timed out is never relayable. Only a composition with no
+ *      channel at all falls back to the relayed answer unconditionally, which is the contract the other
+ *      three gates have.
+ *   3. THE GOAL CANNOT BE CREATED WITHOUT IT. `syncRunGoal` refuses to create a goal for a run whose
+ *      approval record is absent, in EVERY branch that would create one — not only the "no goal yet"
+ *      branch. That is the property `tests/run-start-approval.spec.ts` asserts, because a single
+ *      unguarded branch is exactly how this defect existed in the first place.
+ *
+ * A SPEC MAY EXIST BEFORE A RUN EXISTS, and this module does not forbid that: the scaffold, the Phase
+ * 0 artifacts and every later phase document are all created by `recursive_init` as before. What is
+ * withheld is the GOAL — the object that makes the harness drive rounds. A run that is scaffolded and
+ * never approved is a spec: readable, editable, lockable, and inert.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { getMdFieldValue } from './status.ts'
+
+/** The gate id `recursive_ask` answers for a run start. Deliberately NOT in ASK_GATE_IDS. */
+export const RUN_START_GATE_ID = 'run-start'
+
+/** The Phase 0 artifact the approval is recorded in. */
+export const RUN_START_ARTIFACT = '00-requirements.md'
+
+/** The artifact field the approval reads back from. */
+export const RUN_START_MARKER = 'Run Start'
+
+/** The approving label. The ONLY label that starts a run. */
+export const RUN_START_APPROVE = 'Start run'
+
+/** The withholding label: the spec stays a spec. */
+export const RUN_START_HOLD = 'Hold'
+
+/**
+ * WHY THIS GATE IS NOT IN `ASK_GATE_IDS`. Those three are the WORKFLOW's gates — phase-3 test
+ * evidence, phase-5 sign-off, resolving a gate block — and their membership is asserted as exactly
+ * three. Starting a run is a different kind of decision: it is the one that decides whether there is
+ * a run at all. It lives here, with its own contract, so widening the workflow's gate list cannot
+ * quietly widen what may start a run.
+ */
+export const RUN_START_GATE = {
+  id: RUN_START_GATE_ID,
+  header: 'Start run',
+  question: 'Approve phase 0 and start this run? Approving creates an armed goal the harness will keep driving.',
+  options: [
+    { label: RUN_START_APPROVE, description: 'Record the approval and arm the run goal.' },
+    { label: RUN_START_HOLD, description: 'Leave the spec inert: no run goal, no autonomous rounds.' },
+  ],
+  marker: RUN_START_MARKER,
+} as const
+
+/** The durable line an approval writes. */
+export function runStartApprovalLine(): string {
+  return '- ' + RUN_START_MARKER + ': ' + RUN_START_APPROVE
+}
+
+/** Is a `run-start` answer the approving one? */
+export function isRunStartApproval(answer: string): boolean {
+  return answer.trim() === RUN_START_APPROVE
+}
+
+/** Where the Phase 0 requirements artifact lives for a run rooted at `root`. */
+export function runStartArtifactPath(root: string, runId: string): string {
+  return join(root, '.recursive', 'run', runId, RUN_START_ARTIFACT)
+}
+
+/** The artifact text, or null when the file is absent (a read failure is not an approval). */
+export function readRunStartArtifact(root: string, runId: string): string | null {
+  try {
+    return readFileSync(runStartArtifactPath(root, runId), 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The approval state of a run, read from its Phase 0 artifact.
+ *
+ * ⚠ MATCHED ON THE VALUE, NOT ON THE LINE'S PRESENCE. `getMdFieldValue` returns the field's VALUE, so
+ * a recorded `- Run Start: Hold` is refused here — a check for "is there a Run Start line?" would read
+ * a refusal as consent, which is the one mistake this whole module exists to prevent.
+ */
+export function readRunStartApproval(root: string, runId: string): { approved: boolean; artifact: string; reason: string } {
+  const content = readRunStartArtifact(root, runId)
+  if (content === null) {
+    return { approved: false, artifact: RUN_START_ARTIFACT, reason: 'the Phase 0 requirements artifact does not exist yet' }
+  }
+  const value = getMdFieldValue(content, RUN_START_MARKER)
+  if (value === null) {
+    return { approved: false, artifact: RUN_START_ARTIFACT, reason: 'no ' + RUN_START_MARKER + ' decision has been recorded' }
+  }
+  if (!isRunStartApproval(value)) {
+    return { approved: false, artifact: RUN_START_ARTIFACT, reason: RUN_START_MARKER + ' is ' + JSON.stringify(value) + ', which does not start a run' }
+  }
+  return { approved: true, artifact: RUN_START_ARTIFACT, reason: '' }
+}
+
+/**
+ * The ONE refusal reason the projection returns before approval, exported so every caller branches on
+ * the same string instead of re-typing it (a re-typed reason is a caller that silently stops matching).
+ */
+export const RUN_START_NOT_APPROVED = 'run not started: phase 0 approval has not been granted'