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

package/lib/recursive_ask.tool.d.ts

@@ -1,7 +1,24 @@
 import type { RecursiveRuntime } from './runtime.ts';
+import { RUN_START_GATE_ID } from './run-start.ts';
 /** The identifiers the workflow uses for its three human gates. */
 export declare const ASK_GATE_IDS: readonly ["tdd-mode", "qa-signoff", "gate-block"];
 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 declare function isRunStartGate(gateId: string): boolean;
+/** Every gate id `recursive_ask` accepts, workflow gates first. */
+export declare function askGateIds(): string[];
+/** The artifact a gate's answer belongs in — the run-start gate's is fixed to the Phase 0 requirements. */
+export declare function askGateArtifact(gateId: AskAnyGateId): string;
 /** The plugin's own documented bounds — see the module comment on why these are not a claimed mirror. */
 export declare const MAX_HEADER_CHARS = 12;
 export declare const MAX_LABEL_CHARS = 30;
@@ -41,6 +58,21 @@ export declare class AskValidationError extends Error {
 export declare function validateAskQuestion(question: AskQuestion): AskQuestion;
 /** Build the question for a gate, validated. */
 export declare 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 declare function buildAskQuestionFor(gateId: AskAnyGateId): AskQuestion;
+/**
+ * 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 declare function validateAskAnswerFor(gateId: AskAnyGateId, answer: string): string;
 /**
  * Validate an answer against its gate.
  *
@@ -84,5 +116,33 @@ export declare function pendingGateFor(artifactFile: string, artifactText: strin
  * ⚠ 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 declare function createRecursiveAskTool(recursive: RecursiveRuntime): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/**
+ * 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.
+ *
+ * ⚠ 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.
+ *
+ * ⚠ 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`.
+ */
+export declare function recordRunStartAnswer(recursive: RecursiveRuntime, root: string, runId: string, answer: string | undefined, exec: {
+    agent?: unknown;
+    signal?: unknown;
+    callId?: unknown;
+}): Promise<Record<string, unknown>>;

package/lib/recursive_init.tool.d.ts

@@ -1,2 +1,17 @@
 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.
+ */
 export declare function createRecursiveInitTool(recursive: RecursiveRuntime): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/run-start.d.ts

@@ -0,0 +1,55 @@
+/** The gate id `recursive_ask` answers for a run start. Deliberately NOT in ASK_GATE_IDS. */
+export declare const RUN_START_GATE_ID = "run-start";
+/** The Phase 0 artifact the approval is recorded in. */
+export declare const RUN_START_ARTIFACT = "00-requirements.md";
+/** The artifact field the approval reads back from. */
+export declare const RUN_START_MARKER = "Run Start";
+/** The approving label. The ONLY label that starts a run. */
+export declare const RUN_START_APPROVE = "Start run";
+/** The withholding label: the spec stays a spec. */
+export declare 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 declare const RUN_START_GATE: {
+    readonly id: "run-start";
+    readonly header: "Start run";
+    readonly question: "Approve phase 0 and start this run? Approving creates an armed goal the harness will keep driving.";
+    readonly options: readonly [{
+        readonly label: "Start run";
+        readonly description: "Record the approval and arm the run goal.";
+    }, {
+        readonly label: "Hold";
+        readonly description: "Leave the spec inert: no run goal, no autonomous rounds.";
+    }];
+    readonly marker: "Run Start";
+};
+/** The durable line an approval writes. */
+export declare function runStartApprovalLine(): string;
+/** Is a `run-start` answer the approving one? */
+export declare function isRunStartApproval(answer: string): boolean;
+/** Where the Phase 0 requirements artifact lives for a run rooted at `root`. */
+export declare function runStartArtifactPath(root: string, runId: string): string;
+/** The artifact text, or null when the file is absent (a read failure is not an approval). */
+export declare function readRunStartArtifact(root: string, runId: string): string | 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 declare function readRunStartApproval(root: string, runId: string): {
+    approved: boolean;
+    artifact: string;
+    reason: string;
+};
+/**
+ * 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 declare const RUN_START_NOT_APPROVED = "run not started: phase 0 approval has not been granted";

package/lib/runtime.d.ts

@@ -15,7 +15,7 @@ import { type SubagentsRuntimeLike, type SubagentStartRequestLike, type Subagent
 import { type RecursivePhaseState } from './lifecycle.ts';
 import { type EnforcementConfig, type ToolGuardDecision, type ToolExecLike } from './enforcement.ts';
 import { type CreateWorktreeResult, type PromoteBranchResult } from './worktree.ts';
-import { syncRunGoal, type GoalServiceLike } from './goals-projection.ts';
+import { syncRunGoal, type GoalServiceLike, type SyncResult } from './goals-projection.ts';
 import { type TeamRuntimeLike, type AuditToPassResult, type TeamCallerHandle, type TeamTaskViewLike, type AuditRoundOutcome } from './teams-loop.ts';
 import type { ContinuableChildId, ContinuableMessageId } from './delegation.ts';
 declare module '@deepseek-ai/cordis' {
@@ -39,6 +39,41 @@ export interface LintArtifactResult {
     warnings: string[];
     passed: boolean;
 }
+/**
+ * PHASE 0 — the structural seam for the host's human-question channel (`ctx.userQuestions`).
+ *
+ * Declared here as a minimal seam for the same reason as every other harness touchpoint in this plugin:
+ * the live `UserQuestionService` satisfies it structurally, so the plugin never imports the host package,
+ * and a test can drive the run-start gate with a fake that behaves like the real one. The error case is
+ * part of the contract, not an afterthought: the real `ask()` REJECTS (NO_PROVIDER / CALLER_NOT_LIVE /
+ * ASK_ABORTED) instead of resolving with something that could be mistaken for an answer, which is what
+ * lets `recursive_ask` fail closed rather than invent an approval.
+ */
+export interface UserQuestionsLike {
+    ask(request: {
+        questions: Array<{
+            id: string;
+            header?: string;
+            question: string;
+            options?: Array<{
+                label: string;
+                description?: string;
+            }>;
+        }>;
+        agent?: unknown;
+        signal?: AbortSignal;
+        /** Links the card to the tool call that asked, the way plan-mode's exit does. */
+        wait?: {
+            callId?: unknown;
+        };
+    }): Promise<{
+        answers: Array<{
+            id: string;
+            selected: string[];
+            custom?: string;
+        }>;
+    }>;
+}
 /**
  * T15 (G): the folded status PLUS the rolling guard-decision evidence. Declared
  * as an intersection rather than by editing RecursiveStatusResult/foldRun — the
@@ -79,8 +114,20 @@ export declare class RecursiveRuntime extends Service {
         subagents?: SubagentsRuntimeLike | null;
         workflow?: WorkflowEngineLike | null;
     });
-    /** T10: the native jobs registry, when the composition mounts one. */
+    /**
+     * T10: the native jobs registry, when the composition mounts one. */
     private readonly jobs;
+    /**
+     * PHASE 0 — attach the goals service after construction.
+     *
+     * The composition resolves `goals` with ONE `ctx.get` at apply time and passes it to the constructor,
+     * which is fine for a service that is already mounted. This seam exists for the two cases that pattern
+     * cannot cover: a composition that mounts `goals` later (the same late-attach reason `attachSubagents`
+     * and `attachLlmInventory` exist), and a test that needs the REAL runtime wired to a structural fake —
+     * a fake passed through the plugin's Config is dropped, because the Config schema is the settings
+     * namespace and strips keys it does not declare.
+     */
+    attachGoals(service: GoalServiceLike | null): void;
     /**
      * T23 — write a gate's answer into an artifact as a marker line.
      *
@@ -160,7 +207,7 @@ export declare class RecursiveRuntime extends Service {
     knownProviderNames(): string[];
     private readonly repoRoot;
     private readonly workspaceRegistry;
-    private readonly goalsService;
+    private goalsService;
     /**
      * T27 — the hook registry, EXPOSED so a sibling plugin can participate in a run
      * without patching this one:
@@ -216,10 +263,49 @@ export declare class RecursiveRuntime extends Service {
         history?: string;
         lock?: LockArtifactResult;
     }>;
+    /**
+     * PHASE 0 — read a run's start approval from its own Phase 0 artifact.
+     *
+     * The approval is a DURABLE line in `.recursive/run/<runId>/00-requirements.md`, not a value held in
+     * memory, for the reason every other gate here is durable: a decision that only exists in a session
+     * cannot be cited, and cannot survive the session it was made in. Read-only; asking changes nothing.
+     */
+    readRunStartApproval(root: string, runId: string): {
+        approved: boolean;
+        artifact: string;
+        reason: string;
+    };
+    /**
+     * PHASE 0 — the harness's blocking human-question channel (`ctx.userQuestions`), when this composition
+     * mounts one.
+     *
+     * ⚠ WHY THE PLUGIN REACHES FOR THIS AT ALL. The other three gates answer through a question card and a
+     * relayed label, which is fine for a decision the workflow acts on later. STARTING A RUN is different:
+     * the first human turn is the only place the harness can say "arming this goal means autonomous rounds"
+     * BEFORE arming it. This channel is the same one plan-mode's exit uses; `ask()` resolves only with a
+     * real answer from a real person, and it THROWS when there is no answerer or no live root agent. So the
+     * absence of this service cannot be papered over: `recursive_ask` refuses the run-start gate and names
+     * the missing channel (RM5502).
+     */
+    private userQuestions;
+    /** Late-bind the human-question channel when the composition mounts it. */
+    attachUserQuestions(service: UserQuestionsLike | null): void;
+    /** The human-question channel this composition mounted, or null. */
+    get userQuestionsChannel(): UserQuestionsLike | null;
     /**
      * T1 (goals projection): project the run into the native goals service so it is
      * a first-class durable, resumable, blockable object. Best-effort — the run's
      * filesystem state is the source of truth; a goal is the durable projection.
+     *
+     * ⚠ PHASE 0 — AND IT ARMS NOTHING UNLESS THE RUN WAS STARTED. `create` returns an ARMED goal, and an
+     * armed goal is the harness driving autonomous rounds, so this is the one place where "project the
+     * state" can quietly equal "start the run". The approval is therefore REQUIRED from the caller and
+     * has no default here: a caller that has not resolved the run's approval cannot arm a goal by
+     * forgetting to pass one, and `syncRunGoal` refuses every branch that would create one without it.
+     *
+     * Unapproved is the EXPECTED state for a scaffolded run, so the refusal comes back as a plain
+     * `{ ok: false }` carrying {@link RUN_START_NOT_APPROVED}: callers must treat that as normal work,
+     * never as a warning (see `armRunGoalIfApproved`, the one caller that arms).
      */
     projectRunToGoal(agent: {
         session?: {
@@ -227,15 +313,21 @@ export declare class RecursiveRuntime extends Service {
                 cwd?: string;
             };
         };
-    } | null | undefined, runId: string, state?: Parameters<typeof syncRunGoal>[3]): {
-        ok: true;
-        phase: import("./goals-projection.ts").GoalPhase;
-        ref?: import("./goals-projection.ts").GoalRefLike;
-        created?: boolean;
-    } | {
-        ok: boolean;
-        reason: string;
-    };
+    } | null | undefined, runId: string, state?: Parameters<typeof syncRunGoal>[3], approved?: boolean): SyncResult;
+    /**
+     * PHASE 0 — the approved-run arm step: read the run's approval from `root` and project the goal only
+     * if it is there. This is the phase-progress path (`syncRunGoal` reached on ordinary work), so the
+     * unapproved case is deliberately silent: `{ ok: false, reason: RUN_START_NOT_APPROVED }` with no
+     * goal, no write and no throw. Read on EVERY call rather than cached, because the approval can arrive
+     * mid-session and a cached "not yet" would leave an approved run unable to arm until a plugin reload.
+     */
+    armRunGoalIfApproved(agent: {
+        session?: {
+            header?: {
+                cwd?: string;
+            };
+        };
+    } | null | undefined, root: string, runId: string, state?: Parameters<typeof syncRunGoal>[3]): SyncResult;
     /** T1: block the run's goal on a gate-block (durable + UI-visible). */
     blockRunToGoal(agent: {
         session?: {
@@ -246,31 +338,20 @@ export declare class RecursiveRuntime extends Service {
     } | null | undefined, runId: string, reason: {
         code: string;
         message: string;
-    }): {
-        ok: true;
-        phase: import("./goals-projection.ts").GoalPhase;
-        ref?: import("./goals-projection.ts").GoalRefLike;
-        created?: boolean;
-    } | {
-        ok: boolean;
-        reason: string;
-    };
-    /** T1: re-arm the run's goal on a reopen (blocked/paused -> active). */
+    }): SyncResult;
+    /**
+     * T1: re-arm the run's goal on a reopen (blocked/paused -> active). Never starts an unstarted run —
+     * REOPEN IS NOT A BACK DOOR TO STARTING A RUN. `approved` is required for the same reason as in
+     * `projectRunToGoal`: the phase-0 gate cannot be defaulted open. An approved run's approval outlives
+     * a reopen because it is a durable line in the run's own Phase 0 artifact, not a held value.
+     */
     resumeRunToGoal(agent: {
         session?: {
             header?: {
                 cwd?: string;
             };
         };
-    } | null | undefined, runId: string): {
-        ok: true;
-        phase: import("./goals-projection.ts").GoalPhase;
-        ref?: import("./goals-projection.ts").GoalRefLike;
-        created?: boolean;
-    } | {
-        ok: boolean;
-        reason: string;
-    };
+    } | null | undefined, runId: string, approved?: boolean): SyncResult;
     /**
      * Workspace-scoped control-plane root (R1 binding invariant).
      * Resolves the session agent's canonical cwd -> workspace path via the
@@ -571,6 +652,31 @@ export declare class RecursiveRuntime extends Service {
         existing: string[];
         worktree?: CreateWorktreeResult;
     }>;
+    /**
+     * PHASE 0 — THE APPROVAL ACT: record the human's `Start run` decision and arm the run's goal.
+     *
+     * ⚠ THE ONLY PATH THAT STARTS A RUN. It exists as one method rather than as "write a line, then
+     * project the goal" at the tool, because those two steps must not be separable: an approval recorded
+     * without the arm (or an arm without the record) is exactly the half-state that made this defect hard
+     * to see. `tests/run-start-approval.spec.ts` drives both halves through this one call.
+     *
+     * The approval line goes into the run's own Phase 0 artifact, so it is durable, citable, and survives
+     * the session — and so a reader of the run can answer "was this run started, and by what?" without the
+     * transcript. `answer` is validated against the gate's own labels before it reaches here.
+     */
+    approveRunStart(root: string, runId: string, agent?: {
+        session?: {
+            header?: {
+                cwd?: string;
+            };
+        };
+    } | null, answer?: string): {
+        ok: boolean;
+        reason: string;
+        path: string;
+        replaced: boolean;
+        goal: SyncResult;
+    };
     /**
      * Create a linked worktree for a run under the given workspace root. The
      * worktree branch defaults to `recursive/<runId>` and is cut from the given

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@try-works/dsh-recursive-mode",
   "description": "recursive-mode workflow as a DeepSeek Harness bundle: RecursiveRuntime service + 13 recursive_* tools (recursive_status, recursive_init, recursive_lock, recursive_lint, recursive_closeout, recursive_scratch, recursive_worktree, recursive_phase, recursive_audit_team, recursive_review, recursive_delegate, recursive_ask, recursive_preview)",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/scripts/test-recursive-mode-smoke.ts

@@ -185,7 +185,11 @@ async function main() {
       complete: (_agent, ref) => { goalCurrent = { ...(goalCurrent ?? { id: ref.id, revision: ref.revision }), phase: 'complete', revision: ref.revision + 1 }; return goalCurrent },
       clear: (_agent, ref) => { goalCurrent = undefined; return { id: ref.id, revision: ref.revision + 1 } },
     }
-    const goalSync = syncRunGoal(goalService, {}, '10-smoke', 'active')
+    // PHASE 0: scaffolding a run must not start it. Without an approval the projection creates NOTHING —
+    // this is the defect the gate closes, so the smoke script proves the refusal as well as the arm.
+    const unapproved = syncRunGoal(goalService, {}, '10-smoke', 'active')
+    check('PHASE 0 no goal without approval', unapproved.ok === false && goalCurrent === undefined)
+    const goalSync = syncRunGoal(goalService, {}, '10-smoke', 'active', true)
     check('T1 run goal armed', goalSync.ok === true && goalCurrent?.objective === 'recursive-run:10-smoke · active')
     const goalBlock = blockRunGoal(goalService, {}, '10-smoke', { code: 'prerequisite-blockers', message: 'monotonic lock-order' })
     check('T1 gate-block blocks the run goal', goalBlock.ok === true && goalCurrent?.phase === 'blocked')

package/src/errors.ts

@@ -147,6 +147,18 @@ 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"',
+  },
+  RUN_START_UNANSWERED: {
+    code: 'RM5503',
+    klass: 'runtime',
+    problem: 'the user-questions channel mounted in this composition refused the run-start question, so no person was asked',
+    next: 'use recursive_ask without an answer to surface the question, and retry it with answer: ' + '"Start run" once the user has approved the run start',
+  },
   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