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

package/src/errors.ts

@@ -65,12 +65,30 @@ export const TOOL_ERRORS = {
     problem: 'this gate has no default artifact, so one must be named',
     next: 'pass artifact: <file> so the answer has somewhere durable to land',
   },
+  RELAY_ONLY_FOR_RUN_START: {
+    code: 'RM1150',
+    klass: 'input',
+    problem: 'relay applies only to the run-start gate, which is the only gate that asks the user-questions channel',
+    next: 'drop relay for this gate and answer it with one of its own labels, or call recursive_ask with gate: run-start when the decision is whether to start the run',
+  },
   MISSING_RUN_ID: {
     code: 'RM1101',
     klass: 'input',
     problem: 'runId is required',
     next: 'call recursive_status with no runId to see the latest run id in this workspace',
   },
+  /**
+   * A run id is the NAME of the run directory and is joined onto the run layer
+   * as one path segment, so a path-shaped id is refused before any directory is
+   * created. See `run-id.ts` for the rule and for why it is not the runtime that
+   * learns to accept a path.
+   */
+  BAD_RUN_ID: {
+    code: 'RM1107',
+    klass: 'input',
+    problem: 'runId is not a single directory name',
+    next: 'pass the run directory name such as 03-something, then call recursive_init again',
+  },
   MISSING_ARTIFACT: {
     code: 'RM1102',
     klass: 'input',
@@ -147,6 +165,33 @@ export const TOOL_ERRORS = {
 
   /* 5xxx — the runtime refused an operation it understands. */
 
+  RUN_START_NO_CHANNEL: {
+    code: 'RM5502',
+    klass: 'runtime',
+    problem: 'the run-start gate needs an answer, and this composition mounts no user-questions channel to ask one directly',
+    next: 'call recursive_ask with gate: run-start and no answer to surface the question, then retry with answer: ' + '"Start run"',
+  },
+  /**
+   * ⚠ RM5503 USED TO LIE. Its text asserted "so no person was asked" for EVERY cause, because the caller
+   * that produced it had already thrown the cause away — and a live session showed the cost: the gate
+   * failed 22.9 s into the call with a reason nobody could see, and its `Next:` clause prescribed the very
+   * call that had just failed, so no route to start a run remained. The problem statement now claims only
+   * what the gate knows (no decision came back), and the cause travels in the `detail` the caller
+   * supplies. `RUN_START_ANSWER_UNUSABLE` carries the one case this entry must NOT cover: a person was
+   * reached and their answer was not an approval.
+   */
+  RUN_START_UNANSWERED: {
+    code: 'RM5503',
+    klass: 'runtime',
+    problem: 'the run-start question reached no decision: the mounted user-questions channel failed before a person answered it',
+    next: 'read the cause named in the detail, fix it and call recursive_ask again, or - when this composition cannot deliver the question at all - call recursive_ask with answer: ' + '"Start run"' + ' and relay=true to record the person\'s explicit approval as a relayed one',
+  },
+  RUN_START_ANSWER_UNUSABLE: {
+    code: 'RM5504',
+    klass: 'runtime',
+    problem: 'a person was asked to start this run and their answer was not one of the labels the run-start gate offered',
+    next: 'call recursive_ask again and have the person choose exactly "Start run" or "Hold"; a skipped or custom answer is not an approval, and no relayed answer can replace a decision the person made',
+  },
   RUNTIME_REFUSED: {
     code: 'RM5501',
     klass: 'runtime',

package/src/goals-projection.ts

@@ -15,6 +15,7 @@
  * completed goal may be replaced, per the service contract).
  */
 import type { RunState } from './lifecycle.ts'
+import { RUN_START_NOT_APPROVED } from './run-start.ts'
 
 /** Native goal phase (mirrors @deepseek-ai/dsh-goal GoalPhase). */
 export type GoalPhase = 'active' | 'paused' | 'blocked' | 'complete'
@@ -97,8 +98,31 @@ function mutatePhase(service: GoalServiceLike, agent: AgentHandle, ref: GoalRefL
  * Sync a run's durable goal to the requested phase. Safe: never touches a goal
  * whose objective is not this run's marker, and never re-creates over a
  * non-complete foreign goal.
+ *
+ * ⚠ `approved` IS THE PHASE-0 GATE, and it defaults to the SAFE direction. A goal is not a label:
+ * `create` returns an ARMED view and the harness starts driving autonomous goal rounds for the
+ * session, so creating one is starting the run. The owner's rule is that phase 0 requires explicit
+ * approval, which means the projection must be unable to arm anything on its own — hence a default of
+ * `false` and an explicit refusal in EVERY branch that would call `create`, including the two
+ * replace-a-completed-goal branches (an unapproved run cannot have reached `complete`, but "cannot
+ * happen" is what the single unguarded branch relied on too).
+ *
+ * ⚠ AND IT IS REACHED ON ORDINARY WORK, so the unapproved path is QUIET AND IDEMPOTENT: no goal is
+ * created, nothing is written, no error is thrown, and the run's artifacts are untouched. The caller
+ * reads {@link RUN_START_NOT_APPROVED} to tell "this run has not been started yet" apart from a real
+ * failure, so a normal phase step never surfaces a warning.
+ *
+ * `approved` is passed IN rather than read here because this module is pure: it takes the goal service
+ * seam and nothing else, and the plugin's own filesystem reads live in the runtime (see
+ * `RecursiveRuntime.readRunStartApproval`).
  */
-export function syncRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string, runState: RunState): SyncResult {
+export function syncRunGoal(
+  service: GoalServiceLike | undefined | null,
+  agent: AgentHandle,
+  runId: string,
+  runState: RunState,
+  approved = false,
+): SyncResult {
   if (!service) return { ok: false, reason: 'no goals service' }
   const target = RUN_TO_GOAL_PHASE[runState]
   const current = service.get(agent)
@@ -110,6 +134,7 @@ export function syncRunGoal(service: GoalServiceLike | undefined | null, agent:
     if (phase === target) return { ok: true, phase: target, ref }
     // A completed goal is final: the contract allows it to be REPLACED, not resumed.
     if (phase === 'complete') {
+      if (!approved) return { ok: false, reason: RUN_START_NOT_APPROVED }
       const created = service.create(agent, { objective: goalObjective(runId, runState) })
       return { ok: true, phase: target, ref: refOf(created), created: true }
     }
@@ -121,29 +146,45 @@ export function syncRunGoal(service: GoalServiceLike | undefined | null, agent:
   //    cleared or resumed instead. Never clobber a foreign goal.
   if (current) {
     if (current.phase === 'complete') {
+      if (!approved) return { ok: false, reason: RUN_START_NOT_APPROVED }
       const created = service.create(agent, { objective: goalObjective(runId, runState) })
       return { ok: true, phase: target, ref: refOf(created), created: true }
     }
     return { ok: false, reason: 'a non-matching active goal exists (foreign goal not touched)' }
   }
 
-  // 3. No current goal -> create and arm.
+  // 3. No current goal. This is where the defect lived: scaffolding a run armed it. A run with no
+  //    phase-0 approval stays goal-less — the spec exists, the run does not.
+  if (!approved) return { ok: false, reason: RUN_START_NOT_APPROVED }
   const created = service.create(agent, { objective: goalObjective(runId, runState) })
   return { ok: true, phase: target, ref: refOf(created), created: true }
 }
 
-/** Block the current run goal (used on a gate-block). Never touches a foreign goal. */
+/**
+ * Block the current run goal (used on a gate-block). Never touches a foreign goal.
+ *
+ * ⚠ A RUN THAT WAS NEVER STARTED HAS NO GOAL TO BLOCK, so this reports the unapproved state in the
+ * same words as {@link syncRunGoal} rather than "no current goal to block": the caller's question is
+ * "why is there no goal", and the answer must not depend on which entry point happened to ask.
+ */
 export function blockRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string, reason: { code: string; message: string }): SyncResult {
   if (!service) return { ok: false, reason: 'no goals service' }
   const current = service.get(agent)
-  if (!current) return { ok: false, reason: 'no current goal to block' }
+  if (!current) return { ok: false, reason: RUN_START_NOT_APPROVED }
   if (!isRunGoal(current, runId)) return { ok: false, reason: 'current goal is not for this run (foreign goal not touched)' }
   const ref = refOf(current)
   const ok = !!service.block(agent, ref, reason)
   return ok ? { ok: true, phase: 'blocked', ref } : { ok: false, reason: 'goal block failed' }
 }
 
-/** Bridge a run's blocked goal back to active (used on a reopen). */
-export function resumeRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string): SyncResult {
-  return syncRunGoal(service, agent, runId, 'active')
+/**
+ * Bridge a run's blocked goal back to active (used on a reopen).
+ *
+ * ⚠ REOPEN IS NOT A BACK DOOR TO STARTING A RUN. It routes through {@link syncRunGoal}, so a reopen of
+ * an unapproved run cannot create the goal that init deliberately withheld. An APPROVED run is
+ * unaffected: its approval outlives the reopen, because the approval is a durable line in the run's
+ * own Phase 0 artifact rather than a value held in memory (verified in `tests/run-start-approval.spec.ts`).
+ */
+export function resumeRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string, approved = false): SyncResult {
+  return syncRunGoal(service, agent, runId, 'active', approved)
 }

package/src/index.ts

@@ -4,6 +4,7 @@ import type { ContextFormed } from '@deepseek-ai/dsh-llm'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { RecursiveRuntime } from './runtime.ts'
+import type { UserQuestionsLike } from './runtime.ts'
 import type { JobsRegistryLike } from './jobs-runner.ts'
 import { planGateForExit } from './plan-gate.ts'
 import { registerPhaseSkills, type SkillRegistryLike } from './skills-phase.ts'
@@ -237,6 +238,14 @@ export function apply(ctx: Context, config?: RecursiveModeConfig) {
     ctx.inject(['llm'], (llmCtx: Context) => {
       recursive.attachLlmInventory((llmCtx.get('llm') as LlmInventoryLike | undefined) ?? null)
     })
+    // ⚠ PHASE 0 — THE HUMAN-QUESTION CHANNEL, resolved the same late-attaching way for the same reason:
+    // a composition may mount `userQuestions` after this plugin applies, and the run-start gate asks the
+    // person DIRECTLY through it before it arms a goal — which is what keeps a relayed `Start run` from
+    // being an approval while a person can actually be asked (see run-start.ts).
+    recursive.attachUserQuestions((ctx.get('userQuestions') as UserQuestionsLike | undefined) ?? null)
+    ctx.inject(['userQuestions'], (questionsCtx: Context) => {
+      recursive.attachUserQuestions((questionsCtx.get('userQuestions') as UserQuestionsLike | undefined) ?? null)
+    })
 
     // T7 — THE SETTINGS NAMESPACE, APPLIED ON EVERY APPLY. The settings service edits the
     // Loader entry's config and the Loader RE-APPLIES this plugin, so a toggle in the UI

package/src/recursive_ask.tool.ts

@@ -22,12 +22,44 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
 import { toolError } from './errors.ts'
+import {
+  RUN_START_APPROVE,
+  RUN_START_ARTIFACT,
+  RUN_START_GATE,
+  RUN_START_GATE_ID,
+} from './run-start.ts'
 
 
 /** The identifiers the workflow uses for its three human gates. */
 export const ASK_GATE_IDS = ['tdd-mode', 'qa-signoff', 'gate-block'] as const
 export type AskGateId = (typeof ASK_GATE_IDS)[number]
 
+/**
+ * PHASE 0 — THE FOURTH GATE, AND WHY IT IS NOT IN `ASK_GATE_IDS`.
+ *
+ * The three above are the WORKFLOW's gates, and their membership is asserted as exactly those three.
+ * Starting a run is a different kind of decision — it decides whether there is a run at all, and
+ * approving it ARMS A GOAL the harness will keep driving — so its data lives in `run-start.ts` with its
+ * own contract and its own options. Widening the workflow's gate list must not silently widen what may
+ * start a run.
+ */
+export type AskAnyGateId = AskGateId | typeof RUN_START_GATE_ID
+
+/** Is this gate id the run-start gate? */
+export function isRunStartGate(gateId: string): boolean {
+  return gateId === RUN_START_GATE_ID
+}
+
+/** Every gate id `recursive_ask` accepts, workflow gates first. */
+export function askGateIds(): string[] {
+  return [...ASK_GATE_IDS, RUN_START_GATE_ID]
+}
+
+/** The artifact a gate's answer belongs in — the run-start gate's is fixed to the Phase 0 requirements. */
+export function askGateArtifact(gateId: AskAnyGateId): string {
+  return isRunStartGate(gateId) ? RUN_START_ARTIFACT : GATE_DEFAULT_ARTIFACT[gateId as AskGateId]
+}
+
 /** The plugin's own documented bounds — see the module comment on why these are not a claimed mirror. */
 export const MAX_HEADER_CHARS = 12
 export const MAX_LABEL_CHARS = 30
@@ -137,6 +169,42 @@ export function buildAskQuestion(gateId: AskGateId): AskQuestion {
   })
 }
 
+/**
+ * PHASE 0 — build the question for ANY accepted gate, including the run-start gate.
+ *
+ * A separate entry point rather than a widened `buildAskQuestion` so the three workflow gates keep the
+ * exact signature and behaviour their callers (and `runtime.phaseRules`) already rely on.
+ */
+export function buildAskQuestionFor(gateId: AskAnyGateId): AskQuestion {
+  if (isRunStartGate(gateId)) {
+    return validateAskQuestion({
+      id: RUN_START_GATE.id,
+      header: RUN_START_GATE.header,
+      question: RUN_START_GATE.question,
+      options: RUN_START_GATE.options.map((option) => ({ ...option })),
+    })
+  }
+  return buildAskQuestion(gateId as AskGateId)
+}
+
+/**
+ * PHASE 0 — validate an answer to ANY accepted gate.
+ *
+ * The run-start gate accepts only the labels IT offered, exactly like the other three, and the check is
+ * the same `ASK_GATES`-shaped test against its own options. An answer of `maybe` is refused rather than
+ * recorded, because a recorded non-answer is the failure mode this whole change exists to prevent.
+ */
+export function validateAskAnswerFor(gateId: AskAnyGateId, answer: string): string {
+  if (isRunStartGate(gateId)) {
+    const offered = RUN_START_GATE.options.map((option) => option.label) as readonly string[]
+    if (!offered.includes(answer)) {
+      throw new AskValidationError('answer', 'must be one of ' + offered.join(' | ') + ' (got ' + JSON.stringify(answer) + ')')
+    }
+    return answer
+  }
+  return validateAskAnswer(gateId as AskGateId, answer)
+}
+
 /**
  * Validate an answer against its gate.
  *
@@ -218,35 +286,49 @@ export function pendingGateFor(artifactFile: string, artifactText: string | null
  * ⚠ THE WRITE-BACK IS A MARKER LINE, REPLACED IN PLACE when the artifact already carries one. A
  * second `TDD Mode:` line would leave two answers to one question and make "what was decided?"
  * depend on which a reader found first.
+ *
+ * ⚠ PHASE 0 — `run-start` IS RECORDED BY THE PLUGIN, NEVER BY A BARE MARKER WRITE. See
+ * `recordRunStartAnswer`: it is the only path that can arm a run goal, it prefers the blocking human
+ * channel, and it fails closed when no person can be reached.
  */
 export function createRecursiveAskTool(recursive: RecursiveRuntime) {
   return defineTool({
     name: 'recursive_ask',
-    description: 'Ask one of the three human gates as a structured decision (tdd-mode, qa-signoff, gate-block), or record the answer. 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. One ask per step.',
     parameters: {
-      gate: { type: 'string', description: 'tdd-mode | qa-signoff | gate-block. Required.' },
+      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).' },
-      answer: { type: 'string', description: 'One of the gate\'s option labels. Omit to ASK.' },
+      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) {
-      const gateId = (args.gate ?? '').trim() as AskGateId
+    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 (!ASK_GATE_IDS.includes(gateId)) {
-        return { error: toolError('BAD_ASK_GATE', 'gate must be one of ' + ASK_GATE_IDS.join(' | ')) } 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
 
-      const artifact = (args.artifact ?? GATE_DEFAULT_ARTIFACT[gateId]).trim()
+      // The run-start gate's artifact is FIXED: the Phase 0 requirements document is the run's own
+      // 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()
       let question: AskQuestion
       try {
-        question = buildAskQuestion(gateId)
+        question = buildAskQuestionFor(gateId)
       } catch (err) {
         // The plugin's own gate data failing validation is a defect, so it is reported as one
         // rather than asked: a malformed card would be answered by a person who cannot fix it.
@@ -254,23 +336,291 @@ export function createRecursiveAskTool(recursive: RecursiveRuntime) {
       }
 
       // ASK.
-      if (args.answer === undefined) {
-        return { gate: gateId, marker: ASK_GATES[gateId].marker, artifact, question } as unknown as JsonValue
+      //
+      // ⚠ PHASE 0 EXCEPTION, AND IT IS THE WHOLE POINT OF THE CHANNEL. For the three workflow gates a
+      // 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, 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
       }
 
       // RECORD.
-      let answer: string
-      try {
-        answer = validateAskAnswer(gateId, args.answer)
-      } catch (err) {
-        return { error: toolError('BAD_ASK_ANSWER', err instanceof Error ? err.message : String(err)) } as const
+      let answer: string | undefined
+      if (args.answer === undefined) {
+        answer = undefined
+      } else {
+        try {
+          answer = validateAskAnswerFor(gateId, args.answer)
+        } catch (err) {
+          return { error: toolError('BAD_ASK_ANSWER', err instanceof Error ? err.message : String(err)) } as const
+        }
       }
       if (artifact === '') {
         return { error: toolError('MISSING_ASK_ARTIFACT', 'this gate needs an explicit artifact to record into') } as const
       }
-      const marker = answerMarker(gateId, answer)
+      if (isRunStartGate(gateId)) {
+        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)
       return { gate: gateId, answer, marker, artifact, path: written.path, replaced: written.replaced } as unknown as JsonValue
     },
   })
 }
+
+/**
+ * PHASE 0 — record the answer to the run-start gate, and start the run only if it says so.
+ *
+ * ⚠ 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 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 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,
+  root: string,
+  runId: string,
+  answer: string | undefined,
+  exec: { agent?: unknown; signal?: unknown; callId?: unknown },
+  relay = false,
+): Promise<Record<string, unknown>> {
+  // 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
+
+  // 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 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
+  //    filtered to the gate's own labels; a relayed answer has not, and a marker recording an unoffered
+  //    label would read as a decision while being a transcription error.
+  let decided: string
+  try {
+    decided = validateAskAnswerFor(RUN_START_GATE_ID, final)
+  } catch (err) {
+    return { error: toolError('BAD_ASK_ANSWER', err instanceof Error ? err.message : String(err)) }
+  }
+
+  // 3. Record it, and start the run only for the approving label. A `Hold` is recorded as the decision it
+  //    is — declaring the run not started belongs in the run's own record — and starts nothing.
+  const outcome = recursive.approveRunStart(root, runId, exec.agent as never, decided)
+  return {
+    gate: RUN_START_GATE_ID,
+    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. 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
+    // marker took AND the projection armed the goal, so both are reported rather than one implying the
+    // other.
+    armed: outcome.ok && outcome.goal.ok,
+    goal: outcome.goal,
+  }
+}
+
+/**
+ * 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 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.
+ */
+export async function askRunStartDirectly(
+  channel: NonNullable<RecursiveRuntime['userQuestionsChannel']>,
+  exec: { agent?: unknown; signal?: unknown; callId?: unknown },
+): 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
+    // against its own registry and rejects when it is not the live root, so a fabricated handle can never
+    // produce an answer here.
+    const settled = await channel.ask({
+      questions: [{
+        id: RUN_START_GATE.id,
+        header: RUN_START_GATE.header,
+        question: RUN_START_GATE.question,
+        options: RUN_START_GATE.options.map((option) => ({ ...option })),
+      }],
+      agent: exec.agent,
+      signal: exec.signal,
+      // Links the card to this tool call, the way plan-mode's exit does.
+      wait: { callId: exec.callId },
+    } 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 { kind: 'unusable', detail: describeUnusableAnswer(item) }
+    return { kind: 'answered', answer: selected[0] as string }
+  } catch (err) {
+    return { kind: 'unavailable', ...classifyChannelFailure(err) }
+  }
+}