@try-works/dsh-recursive-mode 0.4.5 → 0.4.7

package/src/recursive_ask.tool.ts

@@ -27,6 +27,7 @@ import {
   RUN_START_ARTIFACT,
   RUN_START_GATE,
   RUN_START_GATE_ID,
+  runStartSpecGuard,
 } from './run-start.ts'
 
 
@@ -294,24 +295,31 @@ export function pendingGateFor(artifactFile: string, artifactText: string | null
 export function createRecursiveAskTool(recursive: RecursiveRuntime) {
   return defineTool({
     name: 'recursive_ask',
-    description: 'Ask a human gate as a structured decision (tdd-mode, qa-signoff, gate-block), or ASK TO START A RUN (run-start: nothing runs, and no goal exists, until this gate is approved). Call without `answer` to ask; call with it to write the answer into the artifact as a durable marker. One ask per step.',
+    description: 'Ask a human gate as a structured decision (tdd-mode, qa-signoff, gate-block), or ASK TO START A RUN (run-start: nothing runs, and no goal exists, until this gate is approved). Call without `answer` to ask; call with it to write the answer into the artifact as a durable marker. For run-start the mounted human channel is asked first and its own selection wins; when that channel cannot deliver the question, the refusal names the cause and `relay=true` with an explicit `answer` records the person\'s relayed approval. The run-start gate is REFUSED while the Phase 0 requirements document is still the unfilled template — the refusal quotes the placeholder lines, and there is nothing to approve until they are written. One ask per step.',
     parameters: {
       gate: { type: 'string', description: 'tdd-mode | qa-signoff | gate-block | run-start. Required. `run-start` is phase 0: approving it records the approval and arms the run goal, which is what makes the harness drive rounds.' },
       runId: { type: 'string', description: 'Run id. Required; must resolve inside the current workspace.' },
       artifact: { type: 'string', description: 'Artifact file the answer belongs in. Optional; defaults per gate (gate-block has none, so it is required for that gate; run-start is always recorded in 00-requirements.md).' },
       answer: { type: 'string', description: 'One of the gate\'s option labels. Omit to ASK. For run-start, the labels are: ' + RUN_START_GATE.options.map((option) => option.label).join(' | ') + '.' },
+      relay: { type: 'boolean', description: 'run-start only, and only after the person has approved in this conversation. Set relay=true when the mounted user-questions channel cannot deliver the run-start question: `answer` then stands in for the channel\'s selection and the result reports source: "relayed" instead of a direct selection. It is refused when the channel reports the question was cancelled, aborted, or timed out, and it is not needed when the person answers the card.' },
     },
     output: {
       schema: { type: 'json' },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
-    async execute(args: { gate?: string; runId?: string; artifact?: string; answer?: string }, exec) {
+    async execute(args: { gate?: string; runId?: string; artifact?: string; answer?: string; relay?: boolean }, exec) {
       const gateId = (args.gate ?? '').trim() as AskAnyGateId
       const runId = args.runId?.trim() ?? ''
       if (runId === '') return { error: toolError('MISSING_RUN_ID') } as const
       if (!askGateIds().includes(gateId)) {
         return { error: toolError('BAD_ASK_GATE', 'gate must be one of ' + askGateIds().join(' | ')) } as const
       }
+      // ⚠ `relay` IS RUN-START ONLY, AND SAYING SO IS THE POINT. The other three gates never consult the
+      // channel, so accepting the flag there would report a fallback that did not happen — the same class
+      // of false claim this tool was fixed for.
+      if (args.relay === true && !isRunStartGate(gateId)) {
+        return { error: toolError('RELAY_ONLY_FOR_RUN_START', 'gate is ' + gateId) } as const
+      }
       const root = await recursive.resolveWorkspaceRoot(exec.agent)
       if (!root) return { error: toolError('NO_WORKSPACE') } as const
 
@@ -319,6 +327,32 @@ export function createRecursiveAskTool(recursive: RecursiveRuntime) {
       // phase-0 record, and letting a caller aim the approval somewhere else is how an approval ends up
       // in a file no reader looks at. Every other gate keeps its per-gate default and its override.
       const artifact = (isRunStartGate(gateId) ? RUN_START_ARTIFACT : args.artifact ?? GATE_DEFAULT_ARTIFACT[gateId as AskGateId]).trim()
+
+      // ⚠ THE ORDERING GUARD, AND IT COMES BEFORE THE QUESTION IS PUT TO ANYBODY. A scaffolded run's Phase 0
+      // document is a template: placeholder requirements, unchecked lists, FAIL gates. Raising "start this run
+      // or hold?" over that asks a person to approve a document that is not a spec — and until this change
+      // nothing even SHOWED it to them. So the gate refuses while the artifact is still the template, naming
+      // the artifact and quoting the placeholder lines, and records nothing.
+      //
+      // It runs before BOTH branches below on purpose: asking the channel first and refusing afterwards would
+      // put the card in front of the person anyway, which is the defect. A refusal here does not weaken any
+      // part of the gate's contract — the person's own answer still wins everywhere below, a spec still
+      // creates no goal, and the relay rules are untouched.
+      if (isRunStartGate(gateId)) {
+        const guard = runStartSpecGuard(root, runId)
+        if (!guard.ok) {
+          return {
+            error: guard.reason,
+            gate: RUN_START_GATE_ID,
+            runId,
+            artifact: RUN_START_ARTIFACT,
+            // The question travels with the refusal so the caller can put the DECISION in the transcript while
+            // it cannot yet raise the card — the same shape the channel refusals use.
+            question: buildAskQuestionFor(RUN_START_GATE_ID),
+          } as unknown as JsonValue
+        }
+      }
+
       let question: AskQuestion
       try {
         question = buildAskQuestionFor(gateId)
@@ -334,7 +368,9 @@ export function createRecursiveAskTool(recursive: RecursiveRuntime) {
       // question is answered by relaying a label, so "no answer means ask". Starting a run is the decision
       // that creates the armed goal, so when this composition mounts the blocking human channel the
       // question is PUT TO THE PERSON whether or not an answer argument arrived — a caller cannot skip the
-      // person by supplying one. Only a composition with no channel falls back to the relayed answer.
+      // person by supplying one. Only a composition with no channel falls back to the relayed answer, and
+      // a channel that FAILED is a third case: it is reported with its cause, and the relayed answer is
+      // taken only when the caller asks for the relay in so many words (see `recordRunStartAnswer`).
       const channelMounted = recursive.userQuestionsChannel !== null
       if (args.answer === undefined && !(isRunStartGate(gateId) && channelMounted)) {
         return { gate: gateId, marker: isRunStartGate(gateId) ? RUN_START_GATE.marker : ASK_GATES[gateId as AskGateId].marker, artifact, question } as unknown as JsonValue
@@ -355,7 +391,7 @@ export function createRecursiveAskTool(recursive: RecursiveRuntime) {
         return { error: toolError('MISSING_ASK_ARTIFACT', 'this gate needs an explicit artifact to record into') } as const
       }
       if (isRunStartGate(gateId)) {
-        return recordRunStartAnswer(recursive, root, runId, answer, exec) as unknown as JsonValue
+        return recordRunStartAnswer(recursive, root, runId, answer, exec, args.relay === true) as unknown as JsonValue
       }
       const marker = answerMarker(gateId as AskGateId, answer as string)
       const written = recursive.recordAskAnswer(root, runId, artifact, marker)
@@ -367,21 +403,35 @@ export function createRecursiveAskTool(recursive: RecursiveRuntime) {
 /**
  * PHASE 0 — record the answer to the run-start gate, and start the run only if it says so.
  *
- * ⚠ THIS GATE NEVER ACCEPTS A RELAYED ANSWER WHILE A HUMAN CHANNEL IS MOUNTED. That is the rule that makes
- * an approval a human act rather than an inference: when `ctx.userQuestions` is present, the question is
- * PUT TO THE PERSON and nothing else can settle it — not the caller's own `answer` argument, and not a
- * fabrication, because `ask()` resolves only with a real selection. A person's decline is likewise final
- * for that call and cannot be overridden by a model that asked for `Start run` in the same breath.
+ * ⚠ THREE OUTCOMES, AND TELLING THEM APART IS THE FIX. The first version of this function collapsed all of
+ * them into one `null`: "the channel threw", "the channel resolved with something unrecognisable", and
+ * "nobody answered" produced the same refusal, whose text asserted a cause ("so no person was asked") the
+ * plugin had already thrown away. A live session paid for that: the call failed after 22.9 s, the operator
+ * could not be told why, and the refusal's own advice prescribed the call that had just failed. So:
+ *
+ *   1. A PERSON WAS REACHED (`unusable`): the channel resolved, so somebody answered, and their answer is
+ *      not a label this gate offered — a skip, a custom value, several labels at once. That is a DECISION
+ *      the gate cannot record, and it is final: neither the caller's `answer` nor `relay=true` may replace
+ *      it. (RM5504)
+ *   2. THE CHANNEL FAILED (`unavailable`): no decision came back at all, and the refusal NAMES THE CAUSE
+ *      from the error the channel threw. Here the run can still be started, because a composition whose
+ *      channel cannot deliver the question would otherwise be unable to start any run — but only by the
+ *      caller asking for the relay in so many words (`relay=true`), which the result reports as
+ *      `source: "relayed"` rather than as a person's own selection. (RM5503)
+ *   3. NO CHANNEL IS MOUNTED: the relayed answer is the only possible source, exactly as before. (RM5502
+ *      when there is no answer either)
  *
- * ⚠ AND WHEN NO CHANNEL IS MOUNTED, THE RELAYED ANSWER IS THE ONLY POSSIBLE SOURCE, so it is used — that
- * is the same contract the other three gates have always had, and refusing it would leave a composition
- * without the channel unable to start any run at all. The question is surfaced first by the ASK branch
- * (the card data the host renders), and the model's `answer` is that person's selection coming back.
+ * ⚠ AND A CANCELLED OR CLOSED QUESTION IS NEVER RELAYABLE. `ASK_CANCELLED`, `ASK_ABORTED` and
+ * `ASK_TIMED_OUT` are the codes that mean the question was settled from outside this gate — the card was
+ * dismissed, the turn was cancelled, or a foreground window ended. The relay is refused for those, so a
+ * question the operator stopped cannot be turned into an approval by asking again in the same breath.
+ * Every other failure is a composition or capability failure — the question reached nobody — which is the
+ * class the relay exists for.
  *
- * ⚠ WHAT THE GATE THEREFORE DOES *NOT* CLAIM, stated rather than implied: in a composition with no
- * `userQuestions` channel, a plugin cannot verify that a person was really asked, so a model could in
- * principle relay a label nobody gave. That is a property of the relay, not of this gate — and it is the
- * reason the channel is consulted in preference whenever it exists. See the header of `run-start.ts`.
+ * ⚠ WHAT THE GATE STILL DOES *NOT* CLAIM: a relayed approval is a relayed approval. The plugin cannot
+ * verify that a person gave the label, and it does not pretend otherwise — the result's `source` and
+ * `channel` fields say where the decision came from, and a direct selection is preferred whenever the
+ * channel can produce one.
  */
 export async function recordRunStartAnswer(
   recursive: RecursiveRuntime,
@@ -389,22 +439,72 @@ export async function recordRunStartAnswer(
   runId: string,
   answer: string | undefined,
   exec: { agent?: unknown; signal?: unknown; callId?: unknown },
+  relay = false,
 ): Promise<Record<string, unknown>> {
-  // 1. ASK THE PERSON DIRECTLY when this composition mounts the channel. An abort or a dismissal is not
-  //    consent, so it settles nothing — and, because the channel was available, it does not hand the
-  //    decision back to the caller either (that is the refusal below).
+  // The question travels in every refusal: a composition whose channel cannot render a card can still put
+  // the exact decision to the person in the transcript, which is what makes the failure recoverable.
+  const question = buildAskQuestionFor(RUN_START_GATE_ID)
   const channel = recursive.userQuestionsChannel
-  const fromChannel = channel ? await askRunStartDirectly(channel, exec) : null
-  if (channel !== null && fromChannel === null) {
-    // The channel exists, so a person COULD have been asked and was not: no answerer, no live root agent,
-    // a dismissal, an abort, or a selection that is not one of this gate's labels. An approval nobody
-    // gave is not recorded, and neither is the caller's argument.
-    return { error: toolError('RUN_START_UNANSWERED') }
+
+  // 1. ASK THE PERSON DIRECTLY when this composition mounts the channel.
+  const channelOutcome: RunStartChannelOutcome | null = channel ? await askRunStartDirectly(channel, exec) : null
+
+  if (channelOutcome !== null && channelOutcome.kind === 'unusable') {
+    // A person WAS asked. Their answer is not an approval this gate can record, and nothing the caller
+    // supplies can stand in for it.
+    return {
+      error: toolError('RUN_START_ANSWER_UNUSABLE', channelOutcome.detail),
+      gate: RUN_START_GATE_ID,
+      runId,
+      artifact: RUN_START_ARTIFACT,
+      question,
+    }
+  }
+
+  if (channelOutcome !== null && channelOutcome.kind === 'unavailable') {
+    const blocked = !relay
+      ? 'the caller did not ask for the relay'
+      : 'the channel reports the question was cancelled, aborted, or timed out, so it is not relayable'
+    if (!relay || !channelOutcome.relayable) {
+      return {
+        error: toolError('RUN_START_UNANSWERED', channelOutcome.detail + ' (' + blocked + ')'),
+        gate: RUN_START_GATE_ID,
+        runId,
+        artifact: RUN_START_ARTIFACT,
+        question,
+        // The diagnosis, as data: a model can quote the cause, and a test can assert on it rather than on
+        // the prose of the sentence above.
+        channel: { outcome: 'unavailable', cause: channelOutcome.cause, relayable: channelOutcome.relayable },
+      }
+    }
+    if (answer === undefined) {
+      // ⚠ THE RELAY NEEDS SOMETHING TO RELAY, AND THIS IS NOT RM5502. A channel IS mounted here, so the
+      // "this composition mounts no user-questions channel" sentence would be false — reachable by asking
+      // for the relay without supplying the answer it relays.
+      return {
+        error: toolError('RUN_START_UNANSWERED', channelOutcome.detail + ' (the relay was authorised but no answer was supplied, so there is no decision to record)'),
+        gate: RUN_START_GATE_ID,
+        runId,
+        artifact: RUN_START_ARTIFACT,
+        question,
+        channel: { outcome: 'unavailable', cause: channelOutcome.cause, relayable: channelOutcome.relayable },
+      }
+    }
   }
+
+  const fromChannel = channelOutcome !== null && channelOutcome.kind === 'answered' ? channelOutcome.answer : null
   const final = fromChannel ?? answer
   if (final === undefined) {
-    // No channel and no answer: there is nothing a person said, so nothing is recorded.
-    return { error: toolError('RUN_START_NO_CHANNEL') }
+    // No channel is mounted and no answer was supplied — the only state left here, because an `answered`
+    // outcome sets `final`, an `unusable` one returned above, and an `unavailable` one either returned
+    // above or carried an answer through the relay. RM5502 says exactly this, and nothing is recorded.
+    return {
+      error: toolError('RUN_START_NO_CHANNEL'),
+      gate: RUN_START_GATE_ID,
+      runId,
+      artifact: RUN_START_ARTIFACT,
+      question,
+    }
   }
 
   // 2. Validate the decision that is about to become durable. A channel selection has already been
@@ -425,8 +525,12 @@ export async function recordRunStartAnswer(
     answer: decided,
     artifact: RUN_START_ARTIFACT,
     // Where the decision came from matters to a reader of the transcript: a direct answer is the person's
-    // own selection; a relayed one came back through the model.
+    // own selection; a relayed one came back through the model. When the relay answered a FAILED channel,
+    // the failure travels with the result, so a relayed approval never reads as a direct selection.
     source: fromChannel === null ? 'relayed' : 'user-questions',
+    ...channelOutcome !== null && channelOutcome.kind === 'unavailable'
+      ? { channel: { outcome: 'unavailable', cause: channelOutcome.cause, relayable: channelOutcome.relayable, relayed: true } }
+      : {},
     path: outcome.path,
     replaced: outcome.replaced,
     // `armed` is the answer to "did the harness get a goal to drive?": the run is started only when the
@@ -438,16 +542,90 @@ export async function recordRunStartAnswer(
 }
 
 /**
- * Ask the run-start question through the blocking channel and return the selection, or null when the
- * person was not reachable (no answerer, no live root agent, a dismissal, an abort).
+ * PHASE 0 — WHAT THE BLOCKING CHANNEL ACTUALLY DID.
+ *
+ * ⚠ THIS TYPE EXISTS BECAUSE ITS ABSENCE WAS THE DEFECT. The first version returned a bare `null` from a
+ * `catch {}` for every failure and for every unrecognisable selection, so "the channel threw NO_PROVIDER",
+ * "the caller is not the live root agent", "the person skipped the question" and "the person typed a
+ * custom value" were ONE value. The refusal built from it then asserted the one cause it could not know.
+ * An outcome carries the cause, the raw message, and whether the failure is the class a relay may answer.
+ */
+export type RunStartChannelOutcome =
+  /** The person answered, and their selection is exactly one of the gate's own labels. */
+  | { kind: 'answered'; answer: string }
+  /** The channel RESOLVED, so a person was reached — but the answer is not a label this gate offered. */
+  | { kind: 'unusable'; detail: string }
+  /** The channel THREW: no decision came back, and the cause is named rather than discarded. */
+  | { kind: 'unavailable'; cause: string; detail: string; relayable: boolean }
+
+/**
+ * ⚠ THE CODES THAT MEAN THE QUESTION WAS CANCELLED OR CLOSED rather than never delivered: the person
+ * dismissed the card, their turn was cancelled, or a foreground window ended. A caller may not convert any
+ * of those into an approval by asking for the relay in the same breath. Every other failure means the
+ * question reached nobody — a composition or capability failure, which is the class the relay exists for.
+ */
+export const NON_RELAYABLE_CHANNEL_CODES = ['ASK_CANCELLED', 'ASK_ABORTED', 'ASK_TIMED_OUT'] as const
+
+/**
+ * Name the failure of one `ask()` call, without inventing anything about it.
+ *
+ * The cause is the error's own `code` when it has one (the harness's `UserQuestionError` carries
+ * `NO_PROVIDER`, `CALLER_NOT_LIVE`, `DELEGATED_CALLER`, `ASK_ABORTED`, …), else its `name`, else its
+ * JavaScript type. `detail` keeps the message verbatim so a reader sees the channel's own words rather
+ * than this plugin's paraphrase — the paraphrase is exactly how the previous version came to assert a
+ * cause nobody had.
+ */
+export function classifyChannelFailure(err: unknown): { cause: string; detail: string; relayable: boolean } {
+  const code = (err as { code?: unknown } | null | undefined)?.code
+  const name = err instanceof Error ? err.name : typeof err
+  const message = err instanceof Error ? err.message : String(err)
+  const hasCode = typeof code === 'string' && code.trim() !== ''
+  const cause = hasCode ? (code as string) : name
+  const relayable = !(hasCode && (NON_RELAYABLE_CHANNEL_CODES as readonly string[]).includes(code as string))
+  return { cause, detail: 'channel threw ' + name + '[' + cause + ']: ' + message, relayable }
+}
+
+/** Describe an answer that arrived but is not a decision this gate can record. */
+function describeUnusableAnswer(item: { selected: string[]; custom?: string } | undefined): string {
+  const offered: readonly string[] = RUN_START_GATE.options.map((option) => option.label)
+  const list = (values: readonly string[]): string => JSON.stringify(values.join(' | '))
+  if (item === undefined) {
+    return 'the channel resolved with no answer for question ' + JSON.stringify(RUN_START_GATE.id) + ' at all'
+  }
+  const raw = item.selected ?? []
+  const custom = item.custom?.trim() ?? ''
+  if (raw.length === 0 && custom === '') {
+    return 'the person skipped the question, and a skip is not an approval'
+  }
+  if (raw.length === 0) {
+    return 'the person answered ' + JSON.stringify(custom) + ' as free text rather than one of ' + list(offered)
+  }
+  // ⚠ THE SUBSET MATTERS. A UI can return a label the gate never offered, so "not exactly one of mine" is
+  // not the same statement as "the person chose something I do not know" — and the refusal says which.
+  const recognised = raw.filter((label) => offered.includes(label))
+  if (recognised.length === 0) {
+    return 'the person selected ' + list(raw) + ', and none of those name a label this gate offered (' + offered.join(' | ') + ')'
+  }
+  if (recognised.length === raw.length) {
+    return 'the person selected ' + list(raw) + ', and an approval is exactly one of ' + list(offered)
+  }
+  return 'the person selected ' + list(raw) + ', of which only ' + list(recognised) + ' name this gate\'s labels ' + list(offered)
+}
+
+/**
+ * Ask the run-start question through the blocking channel and report WHAT HAPPENED.
  *
- * The selection is filtered to the gate's OWN labels before it is returned: a question a UI answered with
- * a free-text custom value must not become an approval just because it arrived on the right channel.
+ * ⚠ THE CATCH IS THE POINT. It used to be `catch { return null }` — a blocking human question whose
+ * failure cause was erased at the exact moment the cause was the only thing worth knowing. Every path out
+ * of this function now says which path it was.
+ *
+ * The selection is filtered to the gate's OWN labels: a question a UI answered with a free-text custom
+ * value must not become an approval just because it arrived on the right channel.
  */
-async function askRunStartDirectly(
+export async function askRunStartDirectly(
   channel: NonNullable<RecursiveRuntime['userQuestionsChannel']>,
   exec: { agent?: unknown; signal?: unknown; callId?: unknown },
-): Promise<string | null> {
+): Promise<RunStartChannelOutcome> {
   const known = RUN_START_GATE.options.map((option) => option.label) as readonly string[]
   try {
     // The agent is passed as the LIVE handle the host gave this tool call. The real service validates it
@@ -467,11 +645,9 @@ async function askRunStartDirectly(
     } as never)
     const item = settled.answers.find((entry) => entry.id === RUN_START_GATE.id)
     const selected = item?.selected?.filter((label) => known.includes(label)) ?? []
-    if (selected.length !== 1) return null
-    return selected[0]
-  } catch {
-    // Quiet by design: the caller reports the situation, and this function's job is only to say whether a
-    // person answered.
-    return null
+    if (selected.length !== 1) return { kind: 'unusable', detail: describeUnusableAnswer(item) }
+    return { kind: 'answered', answer: selected[0] as string }
+  } catch (err) {
+    return { kind: 'unavailable', ...classifyChannelFailure(err) }
   }
 }

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,5 +1,6 @@
 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'
 
@@ -17,13 +18,21 @@ import type { RecursiveRuntime } from './runtime.ts'
  * 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. 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.',
+    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.' },
     },
@@ -32,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
       }