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

package/lib/index.js

@@ -5390,12 +5390,30 @@ 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",
@@ -5462,6 +5480,33 @@ 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\""
+	},
+	/**
+	* ⚠ 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",
@@ -6819,6 +6864,129 @@ 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. A channel that
+*      RESOLVES with an answer the gate does not recognise is a person's decision the gate cannot record
+*      and it ends the call (RM5504). A channel that FAILS ends the call too (RM5503), naming the cause the
+*      channel threw — and there the caller may take the relayed route deliberately, with `relay=true`,
+*      which the result reports as `source: "relayed"` rather than as a person's own selection, so a
+*      composition whose channel cannot deliver the question can still start a run. A failure that means
+*      the question was cancelled, aborted, or timed out is never relayable. Only a composition with no
+*      channel at all falls back to the relayed answer unconditionally, which is the contract the other
+*      three gates have.
+*   3. THE GOAL CANNOT BE CREATED WITHOUT IT. `syncRunGoal` refuses to create a goal for a run whose
+*      approval record is absent, in EVERY branch that would create one — not only the "no goal yet"
+*      branch. That is the property `tests/run-start-approval.spec.ts` asserts, because a single
+*      unguarded branch is exactly how this defect existed in the first place.
+*
+* A SPEC MAY EXIST BEFORE A RUN EXISTS, and this module does not forbid that: the scaffold, the Phase
+* 0 artifacts and every later phase document are all created by `recursive_init` as before. What is
+* withheld is the GOAL — the object that makes the harness drive rounds. A run that is scaffolded and
+* never approved is a spec: readable, editable, lockable, and inert.
+*/
+/** 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 +7014,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 +7115,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 +7193,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. 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."
+				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 +7213,15 @@ 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(" | ") + "."
+			},
+			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: {
@@ -7021,29 +7235,33 @@ 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(" | ")) };
+			if (args.relay === true && !isRunStartGate(gateId)) return { error: toolError("RELAY_ONLY_FOR_RUN_START", "gate is " + gateId) };
 			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, args.relay === true);
 			const marker = answerMarker(gateId, answer);
 			const written = recursive.recordAskAnswer(root, runId, artifact, marker);
 			return {
@@ -7057,6 +7275,197 @@ function createRecursiveAskTool(recursive) {
 		}
 	});
 }
+/**
+* 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.
+*/
+async function recordRunStartAnswer(recursive, root, runId, answer, exec, relay = false) {
+	const question = buildAskQuestionFor(RUN_START_GATE_ID);
+	const channel = recursive.userQuestionsChannel;
+	const channelOutcome = channel ? await askRunStartDirectly(channel, exec) : null;
+	if (channelOutcome !== null && channelOutcome.kind === "unusable") 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,
+			channel: {
+				outcome: "unavailable",
+				cause: channelOutcome.cause,
+				relayable: channelOutcome.relayable
+			}
+		};
+		if (answer === void 0) 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 === void 0) return {
+		error: toolError("RUN_START_NO_CHANNEL"),
+		gate: RUN_START_GATE_ID,
+		runId,
+		artifact: RUN_START_ARTIFACT,
+		question
+	};
+	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",
+		...channelOutcome !== null && channelOutcome.kind === "unavailable" ? { channel: {
+			outcome: "unavailable",
+			cause: channelOutcome.cause,
+			relayable: channelOutcome.relayable,
+			relayed: true
+		} } : {},
+		path: outcome.path,
+		replaced: outcome.replaced,
+		armed: outcome.ok && outcome.goal.ok,
+		goal: outcome.goal
+	};
+}
+/**
+* ⚠ 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.
+*/
+const NON_RELAYABLE_CHANNEL_CODES = [
+	"ASK_CANCELLED",
+	"ASK_ABORTED",
+	"ASK_TIMED_OUT"
+];
+/**
+* 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.
+*/
+function classifyChannelFailure(err) {
+	const code = err?.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 : name;
+	const relayable = !(hasCode && NON_RELAYABLE_CHANNEL_CODES.includes(code));
+	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) {
+	const offered = RUN_START_GATE.options.map((option) => option.label);
+	const list = (values) => JSON.stringify(values.join(" | "));
+	if (item === void 0) 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);
+	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.
+*/
+async function askRunStartDirectly(channel, exec) {
+	const known = RUN_START_GATE.options.map((option) => option.label);
+	try {
+		const item = (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);
+		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]
+		};
+	} catch (err) {
+		return {
+			kind: "unavailable",
+			...classifyChannelFailure(err)
+		};
+	}
+}
 //#endregion
 //#region src/lifecycle.ts
 /**
@@ -8911,8 +9320,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 +9353,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 +9375,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 +9403,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 +9418,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 +9434,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 +10053,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 +10261,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", approved = false) {
+		if (!agent) return {
+			ok: false,
+			reason: "no agent"
+		};
+		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.
 	*/
-	projectRunToGoal(agent, runId, state = "active") {
+	armRunGoalIfApproved(agent, root, runId, state = "active") {
 		if (!agent) return {
 			ok: false,
 			reason: "no agent"
 		};
-		return syncRunGoal(this.goalsService, agent, runId, state);
+		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 +10336,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 +10997,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 +11160,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,
@@ -10936,15 +11512,107 @@ function createRecursiveStatusTool(recursive) {
 	});
 }
 //#endregion
+//#region src/run-id.ts
+/**
+* A RUN ID IS A NAME, NOT A PATH.
+*
+* WHY THIS MODULE EXISTS. Every consumer of a run id JOINS it onto a directory
+* that already carries the meaning "the run layer":
+*
+*     join(root, '.recursive', 'run', runId)   // runtime.ts, run.ts, handoff.ts, scratch.ts
+*     join(repoRoot, '.worktrees', runId)      // worktree.ts (a linked worktree)
+*     'recursive/' + runId                     // worktree.ts (the run's git branch)
+*
+* `join` is a PATH operation: absolute paths, drive specifiers and `..` segments
+* are all legal input to it, and each one silently changes what the call means.
+* A caller who passes `E:\tmp\rm-live-diagnostics\01-calculator-lib` is asking
+* for a run "on another drive"; what they get is a `mkdir` of
+*
+*     <workspace>\.recursive\run\E:\tmp\rm-live-diagnostics\01-calculator-lib
+*
+* which is not drive-qualified at all — on POSIX and Windows alike the colon is
+* just another character in a relative component. The result is a bogus nested
+* folder INSIDE the workspace, created before anything can refuse it, surfacing
+* far away as an ENOENT-shaped runtime failure (RM5501) with the operator's
+* filesystem already dirty.
+*
+* SO THE RULE IS ENFORCED WHERE THE NAME ENTERS, and NOT by teaching the runtime
+* to accept a path. The joins in `runtime.ts` are CORRECT for a name; what was
+* missing was a gate on the name. Do not "fix" this back: a run on another drive
+* or in a worktree is reached through the session's control-plane root
+* (`recursive_worktree`, `00-worktree.md`) — the run layer is never relocated by
+* smuggling a path into the id.
+*
+* The charset below is deliberately the SAME one the read path already uses
+* (`live-route.ts` `DOC_SAFE_RE`) so a name this gate accepts is a name that
+* route can serve.
+*/
+/**
+* The accepted shape, as prose that can be embedded in a model-facing parameter
+* description and in a refusal detail, so the rule is stated once.
+*/
+const RUN_ID_RULE = "letters, digits, dot, underscore or dash only, no leading or trailing dot, no path separator, no drive specifier and no \"..\" segment";
+/** Directory-name charset — the read path's `DOC_SAFE_RE`, verbatim. */
+const RUN_ID_CHARS = /^[A-Za-z0-9._-]+$/;
+/**
+* Why a run id is refused, or `null` when it is a usable NAME.
+*
+* The returned string is the SPECIFIC problem (which rule the id broke), with no
+* trailing punctuation and no sentence of its own, so a caller can hand it to
+* `toolError('BAD_RUN_ID', …)` as the detail. `RUN_ID_RULE` states the shape.
+*
+* The order of the checks is part of the message quality: a Windows absolute
+* path is reported as a drive-qualified path (what the caller passed) rather
+* than as a separator complaint (what that path is made of).
+*/
+function runIdProblem(raw) {
+	if (raw === "") return "runId is empty";
+	if (raw.length > 100) return "runId is " + raw.length + " characters, over the 100 allowed";
+	if (/^[A-Za-z]:/.test(raw)) return "runId is a Windows drive-qualified path, starting with \"" + raw.slice(0, 2) + "\"";
+	if (raw.includes("/") || raw.includes("\\")) return "runId contains the path separator \"" + (raw.includes("/") ? "/" : "\\") + "\"";
+	if (raw.includes(":")) return "runId contains a colon (\":\"), which is a drive and stream separator on Windows";
+	if (raw.includes("..")) return "runId contains a \"..\" segment, which escapes the run directory";
+	if (raw.startsWith(".")) return "runId starts with \".\", which makes it a hidden name or a relative path segment";
+	if (raw.endsWith(".")) return "runId ends with \".\"";
+	if (!RUN_ID_CHARS.test(raw)) {
+		if (/\s/.test(raw)) return "runId contains a space or other whitespace character inside the name";
+		return "runId contains a character outside the allowed set";
+	}
+	return null;
+}
+//#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.
+*
+* AND A RUN ID IS A NAME, NOT A PATH. This is the boundary where the name enters, so it is the boundary
+* that refuses a path-shaped one — loudly, and before `initRun` can mkdir anything. The check lives here
+* (through the shared `run-id.ts` rule) rather than in `runtime.ts` because `initRun` is not the only
+* caller and because the runtime's `join(root, '.recursive', 'run', runId)` is CORRECT for a name; what
+* was missing was a gate on the name. Teaching the runtime to accept a path would silently relocate the
+* run layer instead of rejecting the call. See `run-id.ts` for the rule, the evidence behind it, and the
+* "do not fix this back" note.
+*/
 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. The runId is the NAME of the run directory under .recursive/run/ and is never a path (see the parameter description): a path-shaped runId is refused before anything is written.",
 		parameters: {
 			runId: {
 				type: "string",
-				description: "Run id (e.g. 03-something). Required."
+				description: "Run id — the NAME of the run directory under .recursive/run/ (e.g. 03-something, 01-calculator-lib), never a path: " + RUN_ID_RULE + ". A run on another drive or inside a worktree is reached with recursive_worktree, not by passing a path here. Required."
 			},
 			createWorktree: {
 				type: "boolean",
@@ -10963,9 +11631,12 @@ function createRecursiveInitTool(recursive) {
 			}]
 		},
 		async execute(args, exec) {
-			if (!args.runId || args.runId.trim() === "") return { error: toolError("MISSING_RUN_ID") };
+			const runId = args.runId?.trim() ?? "";
+			if (runId === "") return { error: toolError("MISSING_RUN_ID") };
+			const problem = runIdProblem(runId);
+			if (problem !== null) return { error: toolError("BAD_RUN_ID", problem + " - run ids allow letters, digits, dot, underscore or dash only, no leading or trailing dot, no path separator, no drive specifier and no \"..\" segment - e.g. 01-calculator-lib, fixture-run") };
 			try {
-				return await recursive.initRun(args.runId.trim(), exec.agent, {
+				return await recursive.initRun(runId, exec.agent, {
 					createWorktree: args.createWorktree === true,
 					baseBranch: args.baseBranch?.trim() || void 0
 				});
@@ -11179,6 +11850,16 @@ function createRecursiveLintTool(recursive) {
 * SESSION's workspace only (R1 workspace-scoping invariant). The run is resolved
 * via the session agent's cwd -> workspace registry; a runId outside the current
 * workspace is rejected.
+*
+* A RUN ID IS A NAME, NOT A PATH HERE TOO, and "outside the current workspace is rejected" is NOT enough
+* on its own: `closeoutRun` joins the id onto the run layer and then writes a receipt under it, and its
+* scoping check is `runDir.startsWith(runRoot)` — a string prefix test, not containment. A `..\` segment
+* that lands on a SIBLING of the run layer passes that check whenever the sibling's name begins with
+* `run`, so a path-shaped id can still receive a write. MEASURED pre-fix: `..\run-away` and `../run-away`
+* were accepted and reached the report; the other shapes below were stopped only by the sibling not
+* existing, which is the operator's filesystem deciding, not the tool. The rule is `run-id.ts`; this
+* boundary is where the name enters, so this is where it is refused, with `recursive_init`'s refusal shape
+* — `BAD_RUN_ID` (RM1107), same detail sentence.
 */
 function createRecursiveCloseoutTool(recursive) {
 	return defineTool({
@@ -11191,7 +11872,7 @@ function createRecursiveCloseoutTool(recursive) {
 			},
 			runId: {
 				type: "string",
-				description: "Run id (e.g. 03-something). Required. Must resolve inside the current workspace."
+				description: "Run id — the NAME of the run directory under .recursive/run/ (e.g. 03-something), never a path: " + RUN_ID_RULE + ". Required. Must resolve inside the current workspace."
 			}
 		},
 		output: {
@@ -11203,9 +11884,12 @@ function createRecursiveCloseoutTool(recursive) {
 		},
 		async execute(args, exec) {
 			if (!args.phase || !args.runId || args.runId.trim() === "") return { error: toolError("MISSING_PHASE_AND_RUN") };
+			const runId = args.runId.trim();
+			const problem = runIdProblem(runId);
+			if (problem !== null) return { error: toolError("BAD_RUN_ID", problem + " - run ids allow letters, digits, dot, underscore or dash only, no leading or trailing dot, no path separator, no drive specifier and no \"..\" segment - e.g. 01-calculator-lib, fixture-run") };
 			const root = await recursive.resolveWorkspaceRoot(exec.agent);
 			if (!root) return { error: toolError("NO_WORKSPACE") };
-			return await recursive.closeoutRun(root, args.runId.trim(), args.phase.trim(), exec.agent);
+			return await recursive.closeoutRun(root, runId, args.phase.trim(), exec.agent);
 		}
 	});
 }
@@ -11215,6 +11899,16 @@ function createRecursiveCloseoutTool(recursive) {
 * `recursive_scratch` — read/write/append the run-scoped disposable scratchpad
 * (R5) under the CURRENT session workspace only (R1). Scratch is git-ignored
 * and never citable as an Input.
+*
+* A RUN ID IS A NAME, NOT A PATH HERE TOO. `scratchRun` joins it onto the run layer, and it then WRITES
+* (write/append) into the directory it landed on, so a path-shaped id does not merely fail to find a run:
+* with a `..\` segment it can find and write into a SIBLING of the run layer, because the runtime's
+* workspace-scoping check is `runDir.startsWith(runRoot)` — a string prefix test, not containment — and a
+* sibling directory whose name begins with `run` passes it. MEASURED pre-fix: `..\run-away` was accepted
+* and `scratchRun` wrote `scratch.md` into `<workspace>\.recursive\run-away\scratch\`. The rule is
+* `run-id.ts`; the gate sits here, at the boundary where the name enters, rather than in `scratchRun`, for
+* the same reason `recursive_init`'s does. Refusal shape is `recursive_init`'s, `BAD_RUN_ID` (RM1107),
+* composed identically: one rule, one message.
 */
 function createRecursiveScratchTool(recursive) {
 	return defineTool({
@@ -11227,7 +11921,7 @@ function createRecursiveScratchTool(recursive) {
 			},
 			runId: {
 				type: "string",
-				description: "Run id (e.g. 03-something). Required; must resolve inside the current workspace."
+				description: "Run id — the NAME of the run directory under .recursive/run/ (e.g. 03-something), never a path: " + RUN_ID_RULE + ". Required; must resolve inside the current workspace."
 			},
 			target: {
 				type: "string",
@@ -11250,6 +11944,8 @@ function createRecursiveScratchTool(recursive) {
 			const runId = args.runId?.trim() ?? "";
 			const target = args.target ?? "";
 			if (!action || !runId || !target) return { error: toolError("MISSING_SCRATCH_ARGS") };
+			const problem = runIdProblem(runId);
+			if (problem !== null) return { error: toolError("BAD_RUN_ID", problem + " - run ids allow letters, digits, dot, underscore or dash only, no leading or trailing dot, no path separator, no drive specifier and no \"..\" segment - e.g. 01-calculator-lib, fixture-run") };
 			if (target !== "md" && target !== "ts") return { error: toolError("BAD_TARGET") };
 			const root = await recursive.resolveWorkspaceRoot(exec.agent);
 			if (!root) return { error: toolError("NO_WORKSPACE") };
@@ -11263,6 +11959,22 @@ function createRecursiveScratchTool(recursive) {
 * `recursive_worktree` — create a linked git worktree for a run and/or
 * promote a branch up the dev/stage/main chain. Workspace-scoped: the
 * operations run under the SESSION's control-plane root only.
+*
+* A RUN ID IS A NAME, NOT A PATH HERE TOO, and this is the worst place to be without the rule: a `create`
+* builds TWO things out of the id — the linked worktree directory `.worktrees/<runId>` AND the git branch
+* `recursive/<runId>` (git accepts '/' inside a ref) — so a path-shaped id used to leave a worktree and a
+* ref behind, not just a folder. MEASURED pre-fix, per id, against a fresh repo: `nested/child-run`
+* returned ok:true and created BOTH `.worktrees/nested/child-run` and
+* `refs/heads/recursive/nested/child-run`, while the shapes git itself refuses as ref syntax
+* (`recursive//tmp/x`, `recursive/C:…`, `.hidden-run`, a trailing space) failed the worktree add and
+* created neither. The rule is `run-id.ts` and is not restated here; the gate sits at this boundary, ahead
+* of `createRunWorktree`, so the refusal no longer depends on git happening to dislike the ref name.
+*
+* The refusal is `BAD_RUN_ID` (RM1107), composed exactly as `recursive_init` composes it — same code, same
+* detail, same sentence. One message for one rule is what keeps a caller from having to learn a second
+* vocabulary for the same defect, and the shared remedy it carries ("call recursive_init again") is right
+* for this tool as well: a `create` for a run that does not exist yet is exactly what `recursive_init`
+* with `createWorktree: true` does.
 */
 function createRecursiveWorktreeTool(recursive) {
 	return defineTool({
@@ -11271,7 +11983,7 @@ function createRecursiveWorktreeTool(recursive) {
 		parameters: {
 			runId: {
 				type: "string",
-				description: "Run id the worktree is created for (e.g. 03-something). Required for create."
+				description: "Run id the worktree is created for — the NAME of the run (e.g. 03-something), never a path: " + RUN_ID_RULE + ". A path-shaped id is refused for create. Required for create."
 			},
 			action: {
 				type: "string",
@@ -11303,7 +12015,10 @@ function createRecursiveWorktreeTool(recursive) {
 			if (!root) return { error: toolError("NO_WORKSPACE") };
 			if (action === "create") {
 				if (!args.runId || args.runId.trim() === "") return { error: toolError("MISSING_CREATE_RUN_ID") };
-				return recursive.createRunWorktree(root, args.runId.trim(), args.baseBranch?.trim() || void 0);
+				const runId = args.runId.trim();
+				const problem = runIdProblem(runId);
+				if (problem !== null) return { error: toolError("BAD_RUN_ID", problem + " - run ids allow letters, digits, dot, underscore or dash only, no leading or trailing dot, no path separator, no drive specifier and no \"..\" segment - e.g. 01-calculator-lib, fixture-run") };
+				return recursive.createRunWorktree(root, runId, args.baseBranch?.trim() || void 0);
 			}
 			if (action === "promote") {
 				if (!args.fromBranch || !args.toBranch) return { error: toolError("MISSING_PROMOTE_BRANCHES") };
@@ -11322,6 +12037,14 @@ function createRecursiveWorktreeTool(recursive) {
 * (runtime.phaseRules -> phaseRulesFor) as the once-per-phase pre-step
 * reminder, so the agent can re-ask for the rules without re-injecting them on
 * every step. Returns { error } when no active phase is found.
+*
+* A RUN ID IS A NAME, NOT A PATH HERE TOO, INCLUDING WHEN IT IS OMITTED. Omitted and path-shaped are
+* different cases and must stay different: omitted means "the latest run by mtime", which `resolveRunDir`
+* answers by DISCOVERY rather than by joining anything, and that case is untouched below. A path-shaped id,
+* by contrast, is joined by `phaseRules` -> `resolveRunDir` and then read, and `recordInjection` WRITES
+* `memory-injections.json` under whatever directory it resolved to — with no scoping check at all on this
+* path. So the gate fires only on an id that was actually supplied, and `run-id.ts` owns the rule. The
+* refusal is `recursive_init`'s, `BAD_RUN_ID` (RM1107), composed identically.
 */
 function createRecursivePhaseTool(recursive) {
 	return defineTool({
@@ -11329,7 +12052,7 @@ function createRecursivePhaseTool(recursive) {
 		description: "Return the lint rules + instructions for the current recursive-mode phase (required sections, gates, TDD/QA notes). Call once when entering a new phase; the same rules are also auto-injected once per phase transition.",
 		parameters: { runId: {
 			type: "string",
-			description: "Optional run id (defaults to the latest run by mtime)"
+			description: "Optional run id — the NAME of the run directory under .recursive/run/ (e.g. 03-something), never a path: " + RUN_ID_RULE + ". Omit it for the latest run by mtime."
 		} },
 		output: {
 			schema: { type: "json" },
@@ -11339,7 +12062,12 @@ function createRecursivePhaseTool(recursive) {
 			}]
 		},
 		async execute(args, exec) {
-			const result = await recursive.phaseRules(args.runId, exec.agent);
+			const runId = args.runId?.trim();
+			if (runId !== void 0) {
+				const problem = runId === "" ? "runId is empty" : runIdProblem(runId);
+				if (problem !== null) return { error: toolError("BAD_RUN_ID", problem + " - run ids allow letters, digits, dot, underscore or dash only, no leading or trailing dot, no path separator, no drive specifier and no \"..\" segment - e.g. 01-calculator-lib, fixture-run") };
+			}
+			const result = await recursive.phaseRules(runId, exec.agent);
 			if (!result) return { error: toolError("NO_PHASE") };
 			return result;
 		}
@@ -13687,6 +14415,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 () => {