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

package/lib/index.js

@@ -5462,6 +5462,18 @@ const TOOL_ERRORS = {
 		problem: "the run has unresolved delegated work, so this phase cannot lock yet",
 		next: "call recursive_status to see the pending delegation, have the child write its reply.md, then lock again"
 	},
+	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",
@@ -6819,6 +6831,123 @@ function extractAndGroup(runner, env, options = {}) {
 	};
 }
 //#endregion
+//#region src/run-start.ts
+/**
+* PHASE 0 — STARTING A RUN IS A HUMAN DECISION, NOT A SIDE EFFECT OF SCAFFOLDING.
+*
+* THE DEFECT THIS CLOSES. `recursive_init` scaffolded a run and the plugin then CREATED AND ARMED a
+* goal for it in the same breath (`syncRunGoal`'s "no current goal -> create and arm" branch). A goal
+* is not a label: `goals.create` returns an ARMED view, and the harness immediately begins driving
+* autonomous goal rounds for the session. So asking for a run spec was enough to start an unattended
+* run — the owner's rule is the opposite: *"creating a spec before a run exists should not create a
+* goal. Phase 0 requires explicit approval to start a run and goal."*
+*
+* WHAT "APPROVAL" IS, EXACTLY. The approving label of the `run-start` gate of `recursive_ask`
+* (`Start run`, as opposed to `Hold`), recorded here as a durable `- Run Start: Start run` line in the
+* run's Phase 0 requirements artifact. Three things make that an explicit human act rather than an
+* inference:
+*
+*   1. NO DEFAULT, AND THE VALUE IS THE DECISION. The line is written by the gate itself into the Phase 0
+*      requirements document, and the gate REFUSES an answer that is not one of the labels it offered.
+*      An unoffered answer is a transcription error wearing the shape of a decision, and a `Hold` is not
+*      an approval in any spelling — see {@link readRunStartApproval}, which matches the approving VALUE
+*      and nothing else, so the presence of a `Run Start` line is never on its own consent.
+*   2. IT IS ASKED, NOT ASSUMED. When the composition mounts `ctx.userQuestions` — the harness's own
+*      blocking human channel, the same one plan-mode's exit uses — the question is PUT TO THE PERSON and
+*      only their selection is recorded; a caller-supplied answer cannot stand in for it, and a channel
+*      that cannot reach anyone ends the call without a decision (RM5503). Only a composition with no
+*      channel at all falls back to the relayed answer, which is the contract the other three gates have.
+*   3. THE GOAL CANNOT BE CREATED WITHOUT IT. `syncRunGoal` refuses to create a goal for a run whose
+*      approval record is absent, in EVERY branch that would create one — not only the "no goal yet"
+*      branch. That is the property `tests/run-start-approval.spec.ts` asserts, because a single
+*      unguarded branch is exactly how this defect existed in the first place.
+*
+* A SPEC MAY EXIST BEFORE A RUN EXISTS, and this module does not forbid that: the scaffold, the Phase
+* 0 artifacts and every later phase document are all created by `recursive_init` as before. What is
+* withheld is the GOAL — the object that makes the harness drive rounds. A run that is scaffolded and
+* never approved is a spec: readable, editable, lockable, and inert.
+*/
+/** The gate id `recursive_ask` answers for a run start. Deliberately NOT in ASK_GATE_IDS. */
+const RUN_START_GATE_ID = "run-start";
+/** The Phase 0 artifact the approval is recorded in. */
+const RUN_START_ARTIFACT = "00-requirements.md";
+/** The artifact field the approval reads back from. */
+const RUN_START_MARKER = "Run Start";
+/** The approving label. The ONLY label that starts a run. */
+const RUN_START_APPROVE = "Start run";
+/**
+* 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.
+*/
+const RUN_START_GATE = {
+	id: RUN_START_GATE_ID,
+	header: "Start run",
+	question: "Approve phase 0 and start this run? Approving creates an armed goal the harness will keep driving.",
+	options: [{
+		label: RUN_START_APPROVE,
+		description: "Record the approval and arm the run goal."
+	}, {
+		label: "Hold",
+		description: "Leave the spec inert: no run goal, no autonomous rounds."
+	}],
+	marker: RUN_START_MARKER
+};
+/** Is a `run-start` answer the approving one? */
+function isRunStartApproval(answer) {
+	return answer.trim() === RUN_START_APPROVE;
+}
+/** Where the Phase 0 requirements artifact lives for a run rooted at `root`. */
+function runStartArtifactPath(root, runId) {
+	return join(root, ".recursive", "run", runId, RUN_START_ARTIFACT);
+}
+/** The artifact text, or null when the file is absent (a read failure is not an approval). */
+function readRunStartArtifact(root, runId) {
+	try {
+		return readFileSync(runStartArtifactPath(root, runId), "utf8");
+	} catch {
+		return null;
+	}
+}
+/**
+* The approval state of a run, read from its Phase 0 artifact.
+*
+* ⚠ MATCHED ON THE VALUE, NOT ON THE LINE'S PRESENCE. `getMdFieldValue` returns the field's VALUE, so
+* a recorded `- Run Start: Hold` is refused here — a check for "is there a Run Start line?" would read
+* a refusal as consent, which is the one mistake this whole module exists to prevent.
+*/
+function readRunStartApproval(root, runId) {
+	const content = readRunStartArtifact(root, runId);
+	if (content === null) return {
+		approved: false,
+		artifact: RUN_START_ARTIFACT,
+		reason: "the Phase 0 requirements artifact does not exist yet"
+	};
+	const value = getMdFieldValue(content, RUN_START_MARKER);
+	if (value === null) return {
+		approved: false,
+		artifact: RUN_START_ARTIFACT,
+		reason: "no Run Start decision has been recorded"
+	};
+	if (!isRunStartApproval(value)) return {
+		approved: false,
+		artifact: RUN_START_ARTIFACT,
+		reason: "Run Start is " + JSON.stringify(value) + ", which does not start a run"
+	};
+	return {
+		approved: true,
+		artifact: RUN_START_ARTIFACT,
+		reason: ""
+	};
+}
+/**
+* The ONE refusal reason the projection returns before approval, exported so every caller branches on
+* the same string instead of re-typing it (a re-typed reason is a caller that silently stops matching).
+*/
+const RUN_START_NOT_APPROVED = "run not started: phase 0 approval has not been granted";
+//#endregion
 //#region src/recursive_ask.tool.ts
 /**
 * T23 — `recursive_ask`: the three human gates as STRUCTURED decisions, not prose.
@@ -6846,6 +6975,14 @@ const ASK_GATE_IDS = [
 	"qa-signoff",
 	"gate-block"
 ];
+/** Is this gate id the run-start gate? */
+function isRunStartGate(gateId) {
+	return gateId === RUN_START_GATE_ID;
+}
+/** Every gate id `recursive_ask` accepts, workflow gates first. */
+function askGateIds() {
+	return [...ASK_GATE_IDS, RUN_START_GATE_ID];
+}
 const ASK_GATES = {
 	"tdd-mode": {
 		id: "tdd-mode",
@@ -6939,6 +7076,36 @@ function buildAskQuestion(gateId) {
 	});
 }
 /**
+* 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.
+*/
+function buildAskQuestionFor(gateId) {
+	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);
+}
+/**
+* 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.
+*/
+function validateAskAnswerFor(gateId, answer) {
+	if (isRunStartGate(gateId)) {
+		const offered = RUN_START_GATE.options.map((option) => option.label);
+		if (!offered.includes(answer)) throw new AskValidationError("answer", "must be one of " + offered.join(" | ") + " (got " + JSON.stringify(answer) + ")");
+		return answer;
+	}
+	return validateAskAnswer(gateId, answer);
+}
+/**
 * Validate an answer against its gate.
 *
 * An answer that is not one of the offered labels is REFUSED rather than recorded: a marker saying
@@ -6987,15 +7154,19 @@ function pendingGateFor(artifactFile, artifactText) {
 * ⚠ 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.
 */
 function createRecursiveAskTool(recursive) {
 	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. One ask per step.",
 		parameters: {
 			gate: {
 				type: "string",
-				description: "tdd-mode | qa-signoff | gate-block. Required."
+				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",
@@ -7003,11 +7174,11 @@ function createRecursiveAskTool(recursive) {
 			},
 			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)."
+				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."
+				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(" | ") + "."
 			}
 		},
 		output: {
@@ -7021,29 +7192,32 @@ function createRecursiveAskTool(recursive) {
 			const gateId = (args.gate ?? "").trim();
 			const runId = args.runId?.trim() ?? "";
 			if (runId === "") return { error: toolError("MISSING_RUN_ID") };
-			if (!ASK_GATE_IDS.includes(gateId)) return { error: toolError("BAD_ASK_GATE", "gate must be one of " + ASK_GATE_IDS.join(" | ")) };
+			if (!askGateIds().includes(gateId)) return { error: toolError("BAD_ASK_GATE", "gate must be one of " + askGateIds().join(" | ")) };
 			const root = await recursive.resolveWorkspaceRoot(exec.agent);
 			if (!root) return { error: toolError("NO_WORKSPACE") };
-			const artifact = (args.artifact ?? GATE_DEFAULT_ARTIFACT[gateId]).trim();
+			const artifact = (isRunStartGate(gateId) ? RUN_START_ARTIFACT : args.artifact ?? GATE_DEFAULT_ARTIFACT[gateId]).trim();
 			let question;
 			try {
-				question = buildAskQuestion(gateId);
+				question = buildAskQuestionFor(gateId);
 			} catch (err) {
 				return { error: toolError("BAD_ASK_GATE", err instanceof Error ? err.message : String(err)) };
 			}
-			if (args.answer === void 0) return {
+			const channelMounted = recursive.userQuestionsChannel !== null;
+			if (args.answer === void 0 && !(isRunStartGate(gateId) && channelMounted)) return {
 				gate: gateId,
-				marker: ASK_GATES[gateId].marker,
+				marker: isRunStartGate(gateId) ? RUN_START_GATE.marker : ASK_GATES[gateId].marker,
 				artifact,
 				question
 			};
 			let answer;
-			try {
-				answer = validateAskAnswer(gateId, args.answer);
+			if (args.answer === void 0) answer = void 0;
+			else try {
+				answer = validateAskAnswerFor(gateId, args.answer);
 			} catch (err) {
 				return { error: toolError("BAD_ASK_ANSWER", err instanceof Error ? err.message : String(err)) };
 			}
 			if (artifact === "") return { error: toolError("MISSING_ASK_ARTIFACT", "this gate needs an explicit artifact to record into") };
+			if (isRunStartGate(gateId)) return recordRunStartAnswer(recursive, root, runId, answer, exec);
 			const marker = answerMarker(gateId, answer);
 			const written = recursive.recordAskAnswer(root, runId, artifact, marker);
 			return {
@@ -7057,6 +7231,76 @@ function createRecursiveAskTool(recursive) {
 		}
 	});
 }
+/**
+* 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`.
+*/
+async function recordRunStartAnswer(recursive, root, runId, answer, exec) {
+	const channel = recursive.userQuestionsChannel;
+	const fromChannel = channel ? await askRunStartDirectly(channel, exec) : null;
+	if (channel !== null && fromChannel === null) return { error: toolError("RUN_START_UNANSWERED") };
+	const final = fromChannel ?? answer;
+	if (final === void 0) return { error: toolError("RUN_START_NO_CHANNEL") };
+	let decided;
+	try {
+		decided = validateAskAnswerFor(RUN_START_GATE_ID, final);
+	} catch (err) {
+		return { error: toolError("BAD_ASK_ANSWER", err instanceof Error ? err.message : String(err)) };
+	}
+	const outcome = recursive.approveRunStart(root, runId, exec.agent, decided);
+	return {
+		gate: RUN_START_GATE_ID,
+		answer: decided,
+		artifact: RUN_START_ARTIFACT,
+		source: fromChannel === null ? "relayed" : "user-questions",
+		path: outcome.path,
+		replaced: outcome.replaced,
+		armed: outcome.ok && outcome.goal.ok,
+		goal: outcome.goal
+	};
+}
+/**
+* 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).
+*
+* 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.
+*/
+async function askRunStartDirectly(channel, exec) {
+	const known = RUN_START_GATE.options.map((option) => option.label);
+	try {
+		const selected = (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,
+			wait: { callId: exec.callId }
+		})).answers.find((entry) => entry.id === RUN_START_GATE.id)?.selected?.filter((label) => known.includes(label)) ?? [];
+		if (selected.length !== 1) return null;
+		return selected[0];
+	} catch {
+		return null;
+	}
+}
 //#endregion
 //#region src/lifecycle.ts
 /**
@@ -8911,8 +9155,25 @@ function mutatePhase(service, agent, ref, target) {
 * 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`).
 */
-function syncRunGoal(service, agent, runId, runState) {
+function syncRunGoal(service, agent, runId, runState, approved = false) {
 	if (!service) return {
 		ok: false,
 		reason: "no goals service"
@@ -8927,12 +9188,18 @@ function syncRunGoal(service, agent, runId, runState) {
 			phase: target,
 			ref
 		};
-		if (phase === "complete") return {
-			ok: true,
-			phase: target,
-			ref: refOf(service.create(agent, { objective: goalObjective(runId, runState) })),
-			created: true
-		};
+		if (phase === "complete") {
+			if (!approved) return {
+				ok: false,
+				reason: RUN_START_NOT_APPROVED
+			};
+			return {
+				ok: true,
+				phase: target,
+				ref: refOf(service.create(agent, { objective: goalObjective(runId, runState) })),
+				created: true
+			};
+		}
 		return mutatePhase(service, agent, ref, target) ? {
 			ok: true,
 			phase: target,
@@ -8943,17 +9210,27 @@ function syncRunGoal(service, agent, runId, runState) {
 		};
 	}
 	if (current) {
-		if (current.phase === "complete") return {
-			ok: true,
-			phase: target,
-			ref: refOf(service.create(agent, { objective: goalObjective(runId, runState) })),
-			created: true
-		};
+		if (current.phase === "complete") {
+			if (!approved) return {
+				ok: false,
+				reason: RUN_START_NOT_APPROVED
+			};
+			return {
+				ok: true,
+				phase: target,
+				ref: refOf(service.create(agent, { objective: goalObjective(runId, runState) })),
+				created: true
+			};
+		}
 		return {
 			ok: false,
 			reason: "a non-matching active goal exists (foreign goal not touched)"
 		};
 	}
+	if (!approved) return {
+		ok: false,
+		reason: RUN_START_NOT_APPROVED
+	};
 	return {
 		ok: true,
 		phase: target,
@@ -8961,7 +9238,13 @@ function syncRunGoal(service, agent, runId, runState) {
 		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.
+*/
 function blockRunGoal(service, agent, runId, reason) {
 	if (!service) return {
 		ok: false,
@@ -8970,7 +9253,7 @@ function blockRunGoal(service, agent, runId, reason) {
 	const current = service.get(agent);
 	if (!current) return {
 		ok: false,
-		reason: "no current goal to block"
+		reason: RUN_START_NOT_APPROVED
 	};
 	if (!isRunGoal(current, runId)) return {
 		ok: false,
@@ -8986,9 +9269,16 @@ function blockRunGoal(service, agent, runId, reason) {
 		reason: "goal block failed"
 	};
 }
-/** Bridge a run's blocked goal back to active (used on a reopen). */
-function resumeRunGoal(service, agent, runId) {
-	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`).
+*/
+function resumeRunGoal(service, agent, runId, approved = false) {
+	return syncRunGoal(service, agent, runId, "active", approved);
 }
 //#endregion
 //#region src/teams-loop.ts
@@ -9598,9 +9888,23 @@ var RecursiveRuntime = class extends Service {
 		this.subagentsSeam = config.subagents ?? null;
 		this.workflow = config.workflow ?? null;
 	}
-	/** T10: the native jobs registry, when the composition mounts one. */
+	/**
+	* T10: the native jobs registry, when the composition mounts one. */
 	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) {
+		this.goalsService = service;
+	}
+	/**
 	* T23 — write a gate's answer into an artifact as a marker line.
 	*
 	* ⚠ REPLACED IN PLACE when the artifact already carries that gate's marker: two `TDD Mode:` lines
@@ -9792,16 +10096,72 @@ var RecursiveRuntime = class extends Service {
 		return report;
 	}
 	/**
+	* 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, runId) {
+		return readRunStartApproval(root, runId);
+	}
+	/**
+	* 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).
+	*/
+	userQuestions = null;
+	/** Late-bind the human-question channel when the composition mounts it. */
+	attachUserQuestions(service) {
+		this.userQuestions = service;
+	}
+	/** The human-question channel this composition mounted, or null. */
+	get userQuestionsChannel() {
+		return this.userQuestions;
+	}
+	/**
 	* 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, runId, state = "active") {
+	projectRunToGoal(agent, runId, state = "active", approved = false) {
 		if (!agent) return {
 			ok: false,
 			reason: "no agent"
 		};
-		return syncRunGoal(this.goalsService, agent, runId, state);
+		return syncRunGoal(this.goalsService, agent, runId, state, approved);
+	}
+	/**
+	* 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, root, runId, state = "active") {
+		if (!agent) return {
+			ok: false,
+			reason: "no agent"
+		};
+		const approval = this.readRunStartApproval(root, runId);
+		return syncRunGoal(this.goalsService, agent, runId, state, approval.approved);
 	}
 	/** T1: block the run's goal on a gate-block (durable + UI-visible). */
 	blockRunToGoal(agent, runId, reason) {
@@ -9811,13 +10171,18 @@ var RecursiveRuntime = class extends Service {
 		};
 		return blockRunGoal(this.goalsService, agent, runId, reason);
 	}
-	/** T1: re-arm the run's goal on a reopen (blocked/paused -> active). */
-	resumeRunToGoal(agent, runId) {
+	/**
+	* 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, runId, approved = false) {
 		if (!agent) return {
 			ok: false,
 			reason: "no agent"
 		};
-		return resumeRunGoal(this.goalsService, agent, runId);
+		return resumeRunGoal(this.goalsService, agent, runId, approved);
 	}
 	/**
 	* Workspace-scoped control-plane root (R1 binding invariant).
@@ -10467,15 +10832,61 @@ var RecursiveRuntime = class extends Service {
 			runDir,
 			runId,
 			created,
-			existing
+			existing,
+			runStartApproval: {
+				...this.readRunStartApproval(scaffoldRoot, runId),
+				gate: RUN_START_GATE_ID
+			}
 		};
 		if (worktree) result.worktree = worktree;
-		try {
-			this.projectRunToGoal(agent, runId, "active");
-		} catch {}
 		return result;
 	}
 	/**
+	* 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, runId, agent, answer = RUN_START_APPROVE) {
+		if (root.trim() === "" || runId.trim() === "") return {
+			ok: false,
+			reason: "a run start needs a workspace root and a run id",
+			path: "",
+			replaced: false,
+			goal: {
+				ok: false,
+				reason: "no run to start"
+			}
+		};
+		runStartArtifactPath(root, runId);
+		const written = this.recordAskAnswer(root, runId, RUN_START_ARTIFACT, "- Run Start: " + answer);
+		const approval = this.readRunStartApproval(root, runId);
+		if (!approval.approved) return {
+			ok: false,
+			reason: approval.reason,
+			path: written.path,
+			replaced: written.replaced,
+			goal: {
+				ok: false,
+				reason: RUN_START_NOT_APPROVED
+			}
+		};
+		const goal = this.armRunGoalIfApproved(agent, root, runId, "active");
+		return {
+			ok: true,
+			reason: "",
+			path: written.path,
+			replaced: written.replaced,
+			goal
+		};
+	}
+	/**
 	* Create a linked worktree for a run under the given workspace root. The
 	* worktree branch defaults to `recursive/<runId>` and is cut from the given
 	* base branch (default: the current HEAD branch of the root checkout).
@@ -10584,7 +10995,7 @@ var RecursiveRuntime = class extends Service {
 		const stale = getStaleDownstreamPhases(runDir, artifact);
 		for (const entry of stale) invalidateReceipt(runDir, entry.artifact);
 		try {
-			this.resumeRunToGoal(agent, runId);
+			this.resumeRunToGoal(agent, runId, this.readRunStartApproval(root, runId).approved);
 		} catch {}
 		return {
 			artifact,
@@ -10937,10 +11348,25 @@ function createRecursiveStatusTool(recursive) {
 }
 //#endregion
 //#region src/recursive_init.tool.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.
+*/
 function createRecursiveInitTool(recursive) {
 	return defineTool({
 		name: "recursive_init",
-		description: "Scaffold a new recursive-mode run directory (or ensure an existing one) with stub artifact headers. Delegates to the RecursiveRuntime service (no duplicated scaffolding logic). When createWorktree is true, a linked worktree is created first and the run is scaffolded inside it.",
+		description: "Scaffold a new recursive-mode run directory (or ensure an existing one) with stub artifact headers. Delegates to the RecursiveRuntime service (no duplicated scaffolding logic). When createWorktree is true, a linked worktree is created first and the run is scaffolded inside it. THIS DOES NOT START THE RUN: no goal exists until the user approves phase 0 through recursive_ask gate=run-start, so the result carries runStartApproval — read it and ask.",
 		parameters: {
 			runId: {
 				type: "string",
@@ -13687,6 +14113,10 @@ function apply(ctx, config) {
 		ctx.inject(["llm"], (llmCtx) => {
 			recursive.attachLlmInventory(llmCtx.get("llm") ?? null);
 		});
+		recursive.attachUserQuestions(ctx.get("userQuestions") ?? null);
+		ctx.inject(["userQuestions"], (questionsCtx) => {
+			recursive.attachUserQuestions(questionsCtx.get("userQuestions") ?? null);
+		});
 		if (config?.enforcement !== void 0) recursive.setEnforcementConfig(config.enforcement);
 		const phaseSkills = registerPhaseSkills(ctx.get("skills"), PHASE_SEQUENCE);
 		yield () => {