@try-works/dsh-recursive-mode 0.2.3 → 0.3.0

package/lib/index.js

@@ -4316,6 +4316,218 @@ async function delegate(input) {
 		throw delegationError(message, "DELEGATION_FAILED");
 	}
 }
+/** Read the verdict from a review-schema structured result (pure). */
+function readVerdictFromStructured(result) {
+	const verdict = result.structured?.verdict;
+	if (verdict === "APPROVE" || verdict === "REVISE" || verdict === "REJECT") return verdict;
+	return "APPROVE";
+}
+/** Read the repair instruction from a review-schema structured result (pure). */
+function readRepairFromStructured(result) {
+	const findings = result.structured?.findings;
+	const titles = Array.isArray(findings) ? findings.map((f) => f.title ?? "").filter(Boolean) : [];
+	if (titles.length > 0) return "Address the findings: " + titles.join("; ");
+	return "REVISE: address the review findings and re-submit.";
+}
+/**
+* Run a multi-round delegated task on ONE durable continuable child:
+* 1. `startContinuable` (initial prompt) — `start()` is never called.
+* 2. `awaitRoundResult` observes the child's settlement for that round.
+* 3. On REVISE: `followup` delivers the repair instruction to the SAME child.
+* 4. On APPROVE/REJECT: finish (accepted only when the verdict is APPROVE and
+*    the result evaluates as accepted).
+*
+* `awaitRoundResult(childId, messageId)` is the ONLY parent-side observation
+* seam: in live usage it waits for the child's settlement notice (the child's
+* `reportFrom` lands in the parent's inbox); in tests it is a fake queue.
+*/
+async function delegateContinuable(input) {
+	const { subagents, provider, label, prompt, parent, toolFilter, maxDepth } = input;
+	const maxRounds = input.maxRounds ?? 3;
+	const readVerdict = input.readVerdict ?? readVerdictFromStructured;
+	const readRepair = input.readRepair ?? readRepairFromStructured;
+	const startContinuable = subagents?.startContinuable;
+	const followup = subagents?.followup;
+	if (!(startContinuable !== void 0 && followup !== void 0 && input.awaitRoundResult !== void 0) || subagents === void 0 || parent === void 0) try {
+		const oneShot = await delegate({
+			subagents,
+			provider,
+			request: {
+				prompt: [{
+					type: "text",
+					text: prompt
+				}],
+				label,
+				toolFilter,
+				maxDepth,
+				parent
+			}
+		});
+		const verdict = readVerdict(oneShot);
+		return {
+			ok: true,
+			rounds: [{
+				text: prompt,
+				result: oneShot
+			}],
+			accepted: verdict === "APPROVE" && evaluateDelegationResult(oneShot).accepted,
+			fellBackToOneShot: true
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			reason: err instanceof Error ? err.message : String(err),
+			rounds: [],
+			accepted: false,
+			fellBackToOneShot: true
+		};
+	}
+	const messageIds = [];
+	const rounds = [];
+	let childId;
+	const request = {
+		prompt: [{
+			type: "text",
+			text: prompt
+		}],
+		parent
+	};
+	if (toolFilter !== void 0) request.toolFilter = toolFilter;
+	if (maxDepth !== void 0) request.maxDepth = maxDepth;
+	const spec = {
+		provider,
+		label,
+		request
+	};
+	if (input.childId !== void 0) spec.childId = input.childId;
+	try {
+		const started = await startContinuable(spec);
+		childId = started.childId;
+		messageIds.push(started.messageId);
+		rounds.push({ text: prompt });
+		for (let round = 0; round < maxRounds; round += 1) {
+			const current = rounds[round];
+			const observed = await input.awaitRoundResult(childId, messageIds[messageIds.length - 1]);
+			if (observed === null) return {
+				ok: false,
+				reason: "continuable child produced no settlement for round " + (round + 1),
+				childId,
+				messageIds,
+				rounds,
+				accepted: false
+			};
+			current.result = observed;
+			const verdict = readVerdict(observed);
+			if (verdict !== "REVISE") {
+				const accepted = verdict === "APPROVE" && evaluateDelegationResult(observed).accepted;
+				return {
+					ok: accepted,
+					reason: accepted ? "delegation completed" : "delegation stopped with verdict " + verdict,
+					childId,
+					messageIds,
+					rounds,
+					accepted
+				};
+			}
+			const repair = readRepair(observed);
+			if (!repair) return {
+				ok: false,
+				reason: "REVISE verdict without a repair instruction",
+				childId,
+				messageIds,
+				rounds,
+				accepted: false
+			};
+			const followupId = await followup(parent, childId, [{
+				type: "text",
+				text: repair
+			}], { source: {
+				kind: "coordinator",
+				form: "relay",
+				senderSessionId: parent.id ?? ""
+			} });
+			messageIds.push(followupId);
+			current.revise = true;
+			current.repair = repair;
+			rounds.push({ text: repair });
+		}
+		return {
+			ok: false,
+			reason: "max rounds reached without an APPROVE",
+			childId,
+			messageIds,
+			rounds,
+			accepted: false
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			reason: err instanceof Error ? err.message : String(err),
+			childId,
+			messageIds,
+			rounds,
+			accepted: false
+		};
+	}
+}
+/**
+* T4 kill switch: interrupt one live continuable child's current turn. Admission
+* is synchronous, the effect asynchronous, and the child's pending inbox is
+* preserved (keepInbox semantics) — a followup later resumes the parked queue.
+*/
+function interruptContinuable(subagents, childId, parentSessionId) {
+	const interrupt = subagents?.interrupt;
+	if (interrupt === void 0) return {
+		ok: false,
+		reason: "no continuable interrupt seam"
+	};
+	try {
+		interrupt(childId, {
+			kind: "user",
+			parentSessionId
+		});
+		return { ok: true };
+	} catch (err) {
+		return {
+			ok: false,
+			reason: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+/**
+* T4 closeout: release one continuable child (host drains its Activation and
+* disposes its handle). No-op when the seam lacks the method (one-shot hosts).
+*/
+async function drainContinuableChildren(subagents, parent, childIds) {
+	if (subagents?.drainContinuableChildren === void 0 || childIds.length === 0) return { ok: true };
+	try {
+		await subagents.drainContinuableChildren(parent, childIds);
+		return { ok: true };
+	} catch (err) {
+		return {
+			ok: false,
+			reason: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+/**
+* T4 closeout (host teardown path): release every continuable descendant below
+* the given live parents (mirrors the live `drainContinuableDescendants`).
+* No-op when the seam lacks the method; the host owns this at session teardown.
+*/
+async function drainContinuableDescendants(subagents, parents) {
+	const drain = subagents?.drainContinuableDescendants;
+	if (drain === void 0 || parents.length === 0) return { ok: true };
+	try {
+		await drain(parents);
+		return { ok: true };
+	} catch (err) {
+		return {
+			ok: false,
+			reason: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
 function norm(repoRelative) {
 	return repoRelative.replace(/\\/g, "/").replace(/^\/+/, "");
 }
@@ -4690,6 +4902,23 @@ function evaluateToolGuard(exec, worktreeRoot, activeRunId, mode = "advisory") {
 	}
 	return { kind: "allow" };
 }
+/**
+* T6 (approval ask→policy bridge): an `ask` decision must never be a silent
+* allow. Under `strict` it coerces to `deny`; under `advisory` it stays `allow`
+* but flags a `warn` so the caller never lets it through unlogged. Non-ask
+* decisions pass through unchanged.
+*/
+function coerceAskToDecision(decision, mode = "advisory") {
+	if (decision.kind !== "ask") return decision;
+	if (mode === "strict") return {
+		kind: "deny",
+		reason: decision.reason ?? "ask under strict enforcement denies"
+	};
+	return {
+		kind: "allow",
+		warn: decision.reason ?? "ask under advisory enforcement allows"
+	};
+}
 /** Resolve a tool-target path to an absolute path under the worktree root. */
 function resolveTargetPath(target, worktreeRoot) {
 	const normalized = target.replace(/\\/g, "/");
@@ -5055,6 +5284,291 @@ function promoteBranch(opts) {
 	}
 }
 //#endregion
+//#region src/goals-projection.ts
+/** Marker embedded in the goal objective so a goal can be matched to its run. */
+function runGoalTag(runId) {
+	return "recursive-run:" + runId;
+}
+/** The durable objective string for a run goal. */
+function goalObjective(runId, runState = "active") {
+	return runGoalTag(runId) + " · " + runState;
+}
+/** Map a run state onto the native goal phase it should project to. */
+const RUN_TO_GOAL_PHASE = {
+	new: "active",
+	active: "active",
+	paused: "paused",
+	blocked: "blocked",
+	complete: "complete"
+};
+/** Is this goal's objective the marker for `runId`? */
+function isRunGoal(goal, runId) {
+	return goal?.objective?.startsWith(runGoalTag(runId)) === true;
+}
+/** Read a live ref (id + revision) for a goal. */
+function refOf(goal) {
+	return {
+		id: goal.id,
+		revision: goal.revision
+	};
+}
+/** Commit a phase mutation; the real service returns a truthy GoalView on success. */
+function mutatePhase(service, agent, ref, target) {
+	switch (target) {
+		case "blocked": return !!service.block(agent, ref, {
+			code: "run-gate-block",
+			message: "recursive run gate block"
+		});
+		case "paused": return !!service.pause(agent, ref);
+		case "complete": return !!service.complete(agent, ref);
+		case "active": return !!service.resume(agent, ref);
+	}
+}
+/**
+* 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.
+*/
+function syncRunGoal(service, agent, runId, runState) {
+	if (!service) return {
+		ok: false,
+		reason: "no goals service"
+	};
+	const target = RUN_TO_GOAL_PHASE[runState];
+	const current = service.get(agent);
+	if (current && isRunGoal(current, runId)) {
+		const phase = current.phase ?? "active";
+		const ref = refOf(current);
+		if (phase === target) return {
+			ok: true,
+			phase: target,
+			ref
+		};
+		if (phase === "complete") 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,
+			ref
+		} : {
+			ok: false,
+			reason: "goal mutation failed"
+		};
+	}
+	if (current) {
+		if (current.phase === "complete") 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)"
+		};
+	}
+	return {
+		ok: true,
+		phase: target,
+		ref: refOf(service.create(agent, { objective: goalObjective(runId, runState) })),
+		created: true
+	};
+}
+/** Block the current run goal (used on a gate-block). Never touches a foreign goal. */
+function blockRunGoal(service, agent, runId, reason) {
+	if (!service) return {
+		ok: false,
+		reason: "no goals service"
+	};
+	const current = service.get(agent);
+	if (!current) return {
+		ok: false,
+		reason: "no current goal to block"
+	};
+	if (!isRunGoal(current, runId)) return {
+		ok: false,
+		reason: "current goal is not for this run (foreign goal not touched)"
+	};
+	const ref = refOf(current);
+	return !!service.block(agent, ref, reason) ? {
+		ok: true,
+		phase: "blocked",
+		ref
+	} : {
+		ok: false,
+		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");
+}
+//#endregion
+//#region src/teams-loop.ts
+/** Whether a view is the loop's expected task (guards CAS against foreign ids). */
+function isSameTask(task, id) {
+	return task.id === id;
+}
+/**
+* Render a per-phase task history (board-facing; pure). One line per round plus
+* the final task status — no live data, no mutation.
+*/
+function renderTaskHistory(task, rounds) {
+	const lines = [];
+	if (task !== void 0) lines.push("task " + task.id + " (" + task.status + ", rev " + task.revision + "): " + task.subject);
+	for (const round of rounds) {
+		const repair = round.repair ? " — " + round.repair : "";
+		lines.push("round " + round.round + ": " + round.verdict + " (task rev " + round.taskRevision + ")" + repair);
+	}
+	return lines.join("\n");
+}
+/**
+* T3 driver: audit the phase until it passes, on ONE durable team task.
+*
+* Transition trail (the fake records exactly this order):
+*   createTask(pending) → claim(in_progress) → waitForChange → audit round
+*   → REVISE: updateTask(edit, repair) → waitForChange → re-audit SAME task
+*   → APPROVE: updateTask(complete) → lockPhase()
+*   → REJECT / cap / stuck: updateTask(release) + interrupt, NO lock.
+*/
+async function auditToPass(input) {
+	const { teams, caller, runId, phase, runAuditRound, lockPhase } = input;
+	const maxRounds = input.maxRounds ?? 3;
+	const waitTimeoutMs = input.waitTimeoutMs ?? 3e4;
+	const waitForChange = teams.waitForChange;
+	const interrupt = teams.interrupt;
+	const rounds = [];
+	const createRequest = {
+		subject: "Audit to pass: " + runId + " " + phase,
+		description: "drive " + phase + " through draft → audit → repair → re-audit → pass → lock for run " + runId
+	};
+	if (input.blockedBy !== void 0) createRequest.blockedBy = input.blockedBy;
+	if (input.writeScopes !== void 0) createRequest.writeScopes = input.writeScopes;
+	const task = await teams.createTask(caller, createRequest);
+	const claim = await teams.updateTask(caller, {
+		taskId: task.id,
+		expectedRevision: task.revision,
+		action: "claim"
+	});
+	if (!isSameTask(claim, task.id)) return {
+		ok: false,
+		reason: "claim returned a foreign task",
+		taskId: task.id,
+		rounds,
+		locked: false,
+		taskView: claim
+	};
+	let current = claim;
+	rounds.push({
+		round: 0,
+		verdict: "REVISE",
+		taskRevision: current.revision
+	});
+	try {
+		for (let round = 1; round <= maxRounds; round += 1) {
+			if (waitForChange !== void 0) await waitForChange(caller, waitTimeoutMs, void 0);
+			const outcome = await runAuditRound(round, current);
+			if (!isSameTask(current, task.id)) return {
+				ok: false,
+				reason: "round observed a foreign task",
+				taskId: task.id,
+				rounds,
+				locked: false,
+				taskView: current
+			};
+			if (outcome.verdict === "APPROVE") {
+				const completed = await teams.updateTask(caller, {
+					taskId: task.id,
+					expectedRevision: current.revision,
+					action: "complete"
+				});
+				await lockPhase();
+				rounds.push({
+					round,
+					verdict: "APPROVE",
+					taskRevision: completed.revision
+				});
+				return {
+					ok: outcome.accepted,
+					reason: outcome.accepted ? "audit passed and phase locked" : "verdict APPROVE but delegation not accepted",
+					taskId: task.id,
+					rounds,
+					locked: true,
+					taskView: completed
+				};
+			}
+			if (outcome.verdict === "REJECT") {
+				const released = await teams.updateTask(caller, {
+					taskId: task.id,
+					expectedRevision: current.revision,
+					action: "release"
+				});
+				rounds.push({
+					round,
+					verdict: "REJECT",
+					taskRevision: released.revision
+				});
+				return {
+					ok: false,
+					reason: "audit rejected at round " + round,
+					taskId: task.id,
+					rounds,
+					locked: false,
+					taskView: released
+				};
+			}
+			const repair = outcome.repair ?? "REVISE: address the review findings and re-submit.";
+			const edited = await teams.updateTask(caller, {
+				taskId: task.id,
+				expectedRevision: current.revision,
+				action: "edit",
+				description: current.description + "\nround " + round + " repair: " + repair
+			});
+			current = edited;
+			rounds.push({
+				round,
+				verdict: "REVISE",
+				repair,
+				taskRevision: edited.revision
+			});
+		}
+		const released = await teams.updateTask(caller, {
+			taskId: task.id,
+			expectedRevision: current.revision,
+			action: "release"
+		});
+		return {
+			ok: false,
+			reason: "max rounds reached without an APPROVE",
+			taskId: task.id,
+			rounds,
+			locked: false,
+			taskView: released
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		if (interrupt !== void 0) try {
+			interrupt(caller, input.reviewerName ?? "auditor");
+		} catch {}
+		return {
+			ok: false,
+			reason: message,
+			taskId: task.id,
+			rounds,
+			locked: false,
+			taskView: current
+		};
+	}
+}
+/** Whether a task view is currently claimed by the named owner (board-facing). */
+function isTaskClaimedBy(task, ownerName) {
+	return task.ownerName === ownerName && task.status === "in_progress";
+}
+//#endregion
 //#region src/runtime.ts
 var RecursiveRuntime = class extends Service {
 	/** Recursive-mode runtime service. Owns run-state reads + lock/init/lint operations. */
@@ -5062,11 +5576,74 @@ var RecursiveRuntime = class extends Service {
 		super(ctx, "recursive");
 		this.repoRoot = config.repoRoot ?? process.cwd();
 		this.workspaceRegistry = config.workspaceRegistry ?? null;
+		this.goalsService = config.goals ?? null;
 	}
 	repoRoot;
 	workspaceRegistry;
+	goalsService;
 	_enforcementConfig = null;
 	/**
+	* T3 (agentTeams task loop): run the audit→repair→re-audit state machine on
+	* ONE durable team task. The `teams` seam (live `ctx.agentTeams`) is injected
+	* per-call so the loop stays unit-testable; `runAuditRound` is the caller's
+	* round executor (live usage wires T4's continuable delegation). Locking the
+	* phase artifact is `lockPhase` — the loop NEVER locks before an APPROVE.
+	*/
+	async auditToPass(input) {
+		const { teams, caller, runId, phase, artifact, runAuditRound, agent } = input;
+		let lockResult;
+		const lockPhase = async () => {
+			lockResult = await this.lockArtifact(runId, artifact, false, agent);
+		};
+		const result = await auditToPass({
+			teams,
+			caller,
+			runId,
+			phase,
+			blockedBy: input.blockedBy,
+			writeScopes: input.writeScopes,
+			reviewerName: input.reviewerName,
+			maxRounds: input.maxRounds,
+			waitTimeoutMs: input.waitTimeoutMs,
+			runAuditRound,
+			lockPhase
+		});
+		const report = {
+			...result,
+			history: renderTaskHistory(result.taskView, result.rounds)
+		};
+		if (lockResult !== void 0) report.lock = lockResult;
+		return report;
+	}
+	/**
+	* 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.
+	*/
+	projectRunToGoal(agent, runId, state = "active") {
+		if (!agent) return {
+			ok: false,
+			reason: "no agent"
+		};
+		return syncRunGoal(this.goalsService, agent, runId, state);
+	}
+	/** T1: block the run's goal on a gate-block (durable + UI-visible). */
+	blockRunToGoal(agent, runId, reason) {
+		if (!agent) return {
+			ok: false,
+			reason: "no agent"
+		};
+		return blockRunGoal(this.goalsService, agent, runId, reason);
+	}
+	/** T1: re-arm the run's goal on a reopen (blocked/paused -> active). */
+	resumeRunToGoal(agent, runId) {
+		if (!agent) return {
+			ok: false,
+			reason: "no agent"
+		};
+		return resumeRunGoal(this.goalsService, agent, runId);
+	}
+	/**
 	* Workspace-scoped control-plane root (R1 binding invariant).
 	* Resolves the session agent's canonical cwd -> workspace path via the
 	* registry; NEVER scans list(). Returns null when unavailable (defer).
@@ -5127,8 +5704,16 @@ var RecursiveRuntime = class extends Service {
 	/**
 	* Phase B (native delegation): build a review bundle (R1) + file-backed
 	* handoff docs (R2), resolve the role via the router policy (R3), and call
-	* ctx.subagents.start() with the full request (R4). Workspace-scoped: every
-	* path resolves under the session's control-plane root.
+	* ctx.subagents with the full request (R4). Workspace-scoped: every path
+	* resolves under the session's control-plane root.
+	*
+	* `mode: 'continuable'` (T4) runs the audit→repair→re-audit loop on ONE
+	* durable continuable child (startContinuable → followup with the repair
+	* instruction → settle) and drains the child on closeout. It requires an
+	* `awaitRoundResult` observer (the parent-side settlement seam) AND the exact
+	* live `parent` Agent (continuable followup is object-identity authority);
+	* when either is absent it falls back to one-shot `delegate()` with a flag —
+	* never silently. One-shot `start()` is never called on the continuable path.
 	*/
 	async delegateReview(input) {
 		const policy = loadRouterPolicy(input.policyPath ?? routerPolicyPath(input.root));
@@ -5194,11 +5779,33 @@ var RecursiveRuntime = class extends Service {
 			toolFilter: input.toolFilter ?? defaultReviewToolFilter(),
 			maxDepth: input.maxDepth ?? 2
 		};
+		if (input.parent !== void 0) request.parent = input.parent;
 		let result = null;
 		let error = null;
+		let continuable = null;
 		if (decision.tier === "native" || decision.tier === "external-cli") {
 			if (!input.subagents) error = "no ctx.subagents runtime available (self-audit fallback)";
-			else try {
+			else if (input.mode === "continuable") {
+				continuable = await delegateContinuable({
+					subagents: input.subagents,
+					provider: decision.provider,
+					label: input.delegationId + "/" + input.childId,
+					prompt,
+					childId: input.childId,
+					maxDepth: input.maxDepth ?? 2,
+					toolFilter: input.toolFilter ?? defaultReviewToolFilter(),
+					maxRounds: input.maxRounds ?? 3,
+					awaitRoundResult: input.awaitRoundResult,
+					parent: input.parent
+				});
+				if (continuable.fellBackToOneShot) {
+					result = continuable.rounds[0]?.result ?? null;
+					if (!result) error = "continuable fallback produced no result";
+				} else if (continuable.ok && continuable.rounds.length > 0) {
+					result = continuable.rounds[continuable.rounds.length - 1].result ?? null;
+					if (!result) error = "continuable child produced no final result";
+				} else error = continuable.reason ?? "continuable delegation failed";
+			} else try {
 				result = await delegate({
 					subagents: input.subagents,
 					provider: decision.provider,
@@ -5218,7 +5825,7 @@ var RecursiveRuntime = class extends Service {
 			subagentId: input.childId,
 			phase: input.phase,
 			purpose: input.role + " for run " + input.runId,
-			executionMode: decision.tier,
+			executionMode: decision.tier + (input.mode === "continuable" ? " (continuable)" : ""),
 			artifactPath: input.artifactPath,
 			upstreamArtifacts: input.upstreamArtifacts,
 			reviewBundle: bundle.repoRelativePath,
@@ -5251,7 +5858,12 @@ var RecursiveRuntime = class extends Service {
 			result,
 			evaluation,
 			actionRecordPath,
-			error
+			error,
+			continuable: continuable ? {
+				rounds: continuable.rounds,
+				childId: continuable.childId,
+				fellBackToOneShot: continuable.fellBackToOneShot
+			} : null
 		};
 	}
 	/** R6: validate a child's claimed references against actual files. */
@@ -5413,6 +6025,9 @@ var RecursiveRuntime = class extends Service {
 			existing
 		};
 		if (worktree) result.worktree = worktree;
+		try {
+			this.projectRunToGoal(agent, runId, "active");
+		} catch {}
 		return result;
 	}
 	/**
@@ -5466,7 +6081,16 @@ var RecursiveRuntime = class extends Service {
 		if (!existsSync(artifactPath)) throw new Error("Artifact not found: " + artifact);
 		if (getLockStatus(artifactPath) === "LOCKED") throw new Error("Artifact already LOCKED: " + artifact);
 		const blockers = getPrerequisiteBlockers(runDir, artifact);
-		if (blockers.length > 0) throw new Error("Prerequisite blockers: " + blockers.map((b) => b.artifact + " (" + b.status + ")").join(", "));
+		if (blockers.length > 0) {
+			const message = "monotonic lock-order: " + blockers.map((b) => b.artifact + " (" + b.status + ")").join(", ");
+			try {
+				this.blockRunToGoal(agent, runId, {
+					code: "prerequisite-blockers",
+					message
+				});
+			} catch {}
+			throw new Error("Prerequisite blockers: " + blockers.map((b) => b.artifact + " (" + b.status + ")").join(", "));
+		}
 		let content = readFileSync(artifactPath, "utf8");
 		const lockedAt = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
 		content = setOrInsertField(content, "Status", "LOCKED", ["Phase"]);
@@ -5495,6 +6119,9 @@ var RecursiveRuntime = class extends Service {
 		const hadReceipt = invalidateReceipt(runDir, artifact);
 		const stale = getStaleDownstreamPhases(runDir, artifact);
 		for (const entry of stale) invalidateReceipt(runDir, entry.artifact);
+		try {
+			this.resumeRunToGoal(agent, runId);
+		} catch {}
 		return {
 			artifact,
 			runId,
@@ -5942,6 +6569,135 @@ function createRecursivePhaseTool(recursive) {
 	});
 }
 //#endregion
+//#region src/recursive_audit_team.tool.ts
+/**
+* `recursive_audit_team` — the T3 entry path: a turn-driven adapter over the
+* live `agentTeams` task board. ONE call advances the audit→repair→re-audit
+* state machine by one transition, so the agent drives the loop across turns
+* as continuable-child settlement notices arrive in its inbox.
+*
+* Why one step per call: the live subagents service has no public parent-side
+* "await settlement" promise — a continuable child's verdict arrives as a
+* `subagent-settled` message on a LATER turn. The pure whole-loop driver
+* (`auditToPass` in teams-loop.ts) models the full state machine and is the
+* tested reference; this tool is its honest turn-driven shell.
+*/
+/** Project one live task view to an owned, lossless-JSON-safe record. */
+function taskViewToJson(view) {
+	return {
+		id: view.id,
+		revision: view.revision,
+		subject: view.subject,
+		description: view.description,
+		status: view.status,
+		blockedBy: [...view.blockedBy],
+		writeScopes: [...view.writeScopes],
+		ownerName: view.ownerName ?? null,
+		ready: view.ready,
+		writeScopeWarnings: [...view.writeScopeWarnings]
+	};
+}
+/** Wrap a non-JSON-pure value in the standard error envelope. */
+function errorJson(message) {
+	return { error: message };
+}
+function createRecursiveAuditTeamTool(teams) {
+	return defineTool({
+		name: "recursive_audit_team",
+		description: "Advance one agentTeams Task-board transition for the recursive audit loop (create → claim → edit(REVISE) → complete(APPROVE) → release/interrupt). Drive one step per turn as continuable-child settlement notices arrive; complete the task (and lock the phase) ONLY after an APPROVE verdict.",
+		parameters: {
+			action: {
+				type: "string",
+				description: "create | claim | edit | complete | release | interrupt | get | list. Required."
+			},
+			taskId: {
+				type: "string",
+				description: "Task id for claim/edit/complete/release/interrupt/get."
+			},
+			expectedRevision: {
+				type: "number",
+				description: "CAS revision for claim/edit/complete/release."
+			},
+			subject: {
+				type: "string",
+				description: "Task subject (create)."
+			},
+			description: {
+				type: "string",
+				description: "Task description (create) or appended repair note (edit)."
+			},
+			blockedBy: {
+				type: "array",
+				items: { type: "string" },
+				description: "Task blockers (create)."
+			},
+			writeScopes: {
+				type: "array",
+				items: { type: "string" },
+				description: "Advisory write scopes (create)."
+			},
+			targetName: {
+				type: "string",
+				description: "Teammate name to interrupt (interrupt)."
+			}
+		},
+		output: {
+			schema: { type: "json" },
+			render: (_args, value) => [{
+				type: "text",
+				text: JSON.stringify(value, null, 2)
+			}]
+		},
+		async execute(args, exec) {
+			const action = args.action ?? "";
+			if (!teams) return errorJson("agentTeams service is not available in this composition");
+			const caller = exec.agent ?? {};
+			try {
+				switch (action) {
+					case "create": {
+						if (!args.subject || !args.description) return errorJson("create requires subject and description");
+						const createRequest = {
+							subject: args.subject,
+							description: args.description
+						};
+						if (args.blockedBy !== void 0) createRequest.blockedBy = args.blockedBy;
+						if (args.writeScopes !== void 0) createRequest.writeScopes = args.writeScopes;
+						return taskViewToJson(await teams.createTask(caller, createRequest));
+					}
+					case "claim":
+					case "edit":
+					case "complete":
+					case "release": {
+						if (!args.taskId || args.expectedRevision === void 0) return errorJson(action + " requires taskId and expectedRevision");
+						const updateAction = action;
+						const updateRequest = {
+							taskId: args.taskId,
+							expectedRevision: args.expectedRevision,
+							action: updateAction
+						};
+						if (action === "edit" && args.description !== void 0) updateRequest.description = args.description;
+						return taskViewToJson(await teams.updateTask(caller, updateRequest));
+					}
+					case "interrupt":
+						if (!args.targetName) return errorJson("interrupt requires targetName");
+						if (!teams.interrupt) return errorJson("no interrupt seam");
+						return { previousStatus: teams.interrupt(caller, args.targetName).previousStatus };
+					case "get":
+						if (!args.taskId) return errorJson("get requires taskId");
+						if (!teams.getTask) return errorJson("no getTask seam");
+						return taskViewToJson(teams.getTask(caller, args.taskId));
+					case "list":
+						if (!teams.listTasks) return errorJson("no listTasks seam");
+						return teams.listTasks(caller).map(taskViewToJson);
+					default: return errorJson("unsupported action: " + action + " (create|claim|edit|complete|release|interrupt|get|list)");
+				}
+			} catch (err) {
+				return errorJson(err instanceof Error ? err.message : String(err));
+			}
+		}
+	});
+}
+//#endregion
 //#region src/bootstrap.ts
 /**
 * Idempotent scaffold installer (R3). TS port of install-recursive-mode.py's
@@ -6661,14 +7417,30 @@ function queryOf(req, name) {
 	if (q < 0) return "";
 	return new URLSearchParams(url.slice(q + 1)).get(name) ?? "";
 }
+/** Phase-doc basename allowlist (the run artifact sequence: single *.md, no subdirs). */
+const PHASE_DOC_FILES = new Set(RUN_ARTIFACT_SEQUENCE);
+/** runId/file safety: alphanumerics, dot, underscore, dash only; no '..', no separators. */
+const DOC_SAFE_RE = /^[A-Za-z0-9._-]+$/;
+/** Invalid runId or file name (path traversal / subdir / non-phase doc) — reject. */
+function docTargetError(runId, file) {
+	if (!DOC_SAFE_RE.test(runId) || runId.includes("..")) return "invalid runId";
+	if (!DOC_SAFE_RE.test(file) || file.includes("..") || file.includes("/") || file.includes("\\")) return "invalid file";
+	if (!file.endsWith(".md")) return "invalid file: must be a .md phase doc";
+	if (!PHASE_DOC_FILES.has(file)) return "invalid file: not a phase doc";
+	return null;
+}
 /**
-* Build the two read-only routes. Returns [state, events] in registration order.
-* @param host - the resolved-root + fs-fold seam (the RecursiveRuntime adapter).
+* The lazy per-phase doc route (0.2.4): GET the raw markdown of one run phase
+* doc, read ON DEMAND from the filesystem. NOT part of the /state or /events
+* projection payloads (they stay fold-only). Same browser-marker tripwire as
+* state/events; the client root is re-validated by the host (never trusted:
+* an unknown root -> 400), then the resolved doc path is containment-checked
+* under join(root, '.recursive', 'run', runId).
 */
-function makeRecursiveRoutes(host) {
-	return [{
+function docRoute(host) {
+	return {
 		kind: "exact",
-		path: "/.recursive/api/state",
+		path: "/.recursive/api/doc",
 		handler: async (req, res) => {
 			if (req.method !== "GET") {
 				res.writeHead(405);
@@ -6680,75 +7452,142 @@ function makeRecursiveRoutes(host) {
 				res.end();
 				return;
 			}
-			const sessionId = queryOf(req, "sessionId") || void 0;
-			const cwd = queryOf(req, "cwd");
-			const root = sessionId === void 0 && cwd === "" ? null : await host.resolveRoot(sessionId, cwd);
-			if (root === null) {
-				json(res, 200, {
-					root: null,
-					projection: {},
-					revision: 0
+			const root = queryOf(req, "root");
+			const runId = queryOf(req, "runId");
+			const file = queryOf(req, "file");
+			const targetError = docTargetError(runId, file);
+			if (root === "" || targetError !== null) {
+				json(res, 400, {
+					ok: false,
+					error: targetError ?? "missing root"
 				});
 				return;
 			}
-			json(res, 200, {
-				root,
-				projection: await host.snapshot(root),
-				revision: host.revision(root)
-			});
-		}
-	}, {
-		kind: "exact",
-		path: "/.recursive/api/events",
-		handler: async (req, res) => {
-			if (req.method !== "GET") {
-				res.writeHead(405);
-				res.end();
+			const resolvedRoot = await host.resolveRoot(void 0, root);
+			if (resolvedRoot === null || resolve(resolvedRoot) !== resolve(root)) {
+				json(res, 400, {
+					ok: false,
+					error: "root is not a known workspace"
+				});
 				return;
 			}
-			if (!browserMarker(req)) {
-				res.writeHead(403);
-				res.end();
+			const runBase = resolve(root, ".recursive", "run", runId);
+			const docPath = resolve(runBase, file);
+			if (docPath === runBase || !docPath.startsWith(runBase + sep)) {
+				json(res, 400, {
+					ok: false,
+					error: "doc path escapes the run dir"
+				});
 				return;
 			}
-			const sessionId = queryOf(req, "sessionId") || void 0;
-			const cwd = queryOf(req, "cwd");
-			const root = sessionId === void 0 && cwd === "" ? null : await host.resolveRoot(sessionId, cwd);
-			if (root === null) {
-				res.writeHead(200, {
-					"content-type": "text/event-stream; charset=utf-8",
-					"cache-control": "no-cache",
-					connection: "keep-alive"
+			if (!existsSync(docPath)) {
+				json(res, 404, {
+					ok: false,
+					error: "phase doc not found"
 				});
-				res.write("data: {\"root\":null,\"projection\":{},\"revision\":0}\n\n");
-				res.end();
 				return;
 			}
+			const text = readFileSync(docPath, "utf8");
 			res.writeHead(200, {
-				"content-type": "text/event-stream; charset=utf-8",
-				"cache-control": "no-cache",
-				connection: "keep-alive"
+				"content-type": "text/markdown; charset=utf-8",
+				"cache-control": "no-store"
 			});
-			const push = async () => {
-				const projection = await host.snapshot(root);
-				const payload = {
+			res.end(text);
+		}
+	};
+}
+/**
+* Build the read-only routes. Returns [state, events, doc] in registration order.
+* @param host - the resolved-root + fs-fold seam (the RecursiveRuntime adapter).
+*/
+function makeRecursiveRoutes(host) {
+	return [
+		{
+			kind: "exact",
+			path: "/.recursive/api/state",
+			handler: async (req, res) => {
+				if (req.method !== "GET") {
+					res.writeHead(405);
+					res.end();
+					return;
+				}
+				if (!browserMarker(req)) {
+					res.writeHead(403);
+					res.end();
+					return;
+				}
+				const sessionId = queryOf(req, "sessionId") || void 0;
+				const cwd = queryOf(req, "cwd");
+				const root = sessionId === void 0 && cwd === "" ? null : await host.resolveRoot(sessionId, cwd);
+				if (root === null) {
+					json(res, 200, {
+						root: null,
+						projection: {},
+						revision: 0
+					});
+					return;
+				}
+				json(res, 200, {
 					root,
-					projection,
+					projection: await host.snapshot(root),
 					revision: host.revision(root)
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: "/.recursive/api/events",
+			handler: async (req, res) => {
+				if (req.method !== "GET") {
+					res.writeHead(405);
+					res.end();
+					return;
+				}
+				if (!browserMarker(req)) {
+					res.writeHead(403);
+					res.end();
+					return;
+				}
+				const sessionId = queryOf(req, "sessionId") || void 0;
+				const cwd = queryOf(req, "cwd");
+				const root = sessionId === void 0 && cwd === "" ? null : await host.resolveRoot(sessionId, cwd);
+				if (root === null) {
+					res.writeHead(200, {
+						"content-type": "text/event-stream; charset=utf-8",
+						"cache-control": "no-cache",
+						connection: "keep-alive"
+					});
+					res.write("data: {\"root\":null,\"projection\":{},\"revision\":0}\n\n");
+					res.end();
+					return;
+				}
+				res.writeHead(200, {
+					"content-type": "text/event-stream; charset=utf-8",
+					"cache-control": "no-cache",
+					connection: "keep-alive"
+				});
+				const push = async () => {
+					const projection = await host.snapshot(root);
+					const payload = {
+						root,
+						projection,
+						revision: host.revision(root)
+					};
+					res.write("data: " + JSON.stringify(payload) + "\n\n");
 				};
-				res.write("data: " + JSON.stringify(payload) + "\n\n");
-			};
-			const heartbeat = setInterval(() => {
-				res.write(": ping\n\n");
-			}, HEARTBEAT_MS);
-			const close = () => {
-				clearInterval(heartbeat);
-			};
-			req.once("close", close);
-			res.once("close", close);
-			await push();
-		}
-	}];
+				const heartbeat = setInterval(() => {
+					res.write(": ping\n\n");
+				}, HEARTBEAT_MS);
+				const close = () => {
+					clearInterval(heartbeat);
+				};
+				req.once("close", close);
+				res.once("close", close);
+				await push();
+			}
+		},
+		docRoute(host)
+	];
 }
 /**
 * Register the routes at most ONCE per process. WebServer.register throws on a
@@ -6808,12 +7647,15 @@ function apply(ctx, config) {
 	if (config?.shellOnly) return;
 	ctx.effect(function* () {
 		const workspaceRegistry = ctx.get("workspaceRegistry");
+		const goals = ctx.get("goals");
 		const recursive = new RecursiveRuntime(ctx, {
 			repoRoot: config?.repoRoot ?? process.cwd(),
-			workspaceRegistry
+			workspaceRegistry,
+			goals
 		});
 		const repairedRoots = /* @__PURE__ */ new Set();
 		const reminderGate = new ReminderOnceGate();
+		const agentTeams = ctx.get("agentTeams");
 		const disposers = [
 			ctx.tools.register(createRecursiveStatusTool(recursive)),
 			ctx.tools.register(createRecursiveInitTool(recursive)),
@@ -6822,7 +7664,8 @@ function apply(ctx, config) {
 			ctx.tools.register(createRecursiveCloseoutTool(recursive)),
 			ctx.tools.register(createRecursiveScratchTool(recursive)),
 			ctx.tools.register(createRecursiveWorktreeTool(recursive)),
-			ctx.tools.register(createRecursivePhaseTool(recursive))
+			ctx.tools.register(createRecursivePhaseTool(recursive)),
+			...agentTeams ? [ctx.tools.register(createRecursiveAuditTeamTool(agentTeams))] : []
 		];
 		const commands = ctx.get("commands");
 		if (commands) disposers.push(registerRecursiveCommand({ commands }, recursive));
@@ -6849,6 +7692,10 @@ function apply(ctx, config) {
 			const decision = evaluateToolGuard(exec, exec?.agent?.session?.header?.cwd ?? "", "", recursive.enforcementConfig.toolGuards);
 			if (decision.kind === "allow") return typeof next === "function" ? next() : { kind: "allow" };
 			if (decision.kind === "deny") return decision;
+			const coerced = coerceAskToDecision(decision, recursive.enforcementConfig.toolGuards);
+			if (coerced.kind === "deny") return coerced;
+			if (coerced.kind === "allow" && coerced.warn) console.warn("[recursive] tool guard (advisory): " + coerced.warn + " — allowing");
+			return typeof next === "function" ? next() : { kind: "allow" };
 		}));
 		const agentRuntime = ctx;
 		if (agentRuntime.on) disposers.push(agentRuntime.on("agent/pre-step", async (payload, next) => {
@@ -6928,4 +7775,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { DEFAULT_ENFORCEMENT, OPTIONAL_PHASES, PHASES, PHASE_SEQUENCE, RECURSIVE_API_PREFIX, RUN_ARTIFACT_SEQUENCE, RUN_STATES, RecursiveRuntime, apply, buildDelegationPrompt, buildReviewBundle, capabilityProbe, childScratchPath, contentSha256, coupleGateBlockToGoal, createChildBrief, createHandoff, createRecursiveCloseoutTool, createRecursiveInitTool, createRecursiveLintTool, createRecursiveLockTool, createRecursivePhaseTool, createRecursiveScratchTool, createRecursiveStatusTool, createRecursiveWorktreeTool, defaultReviewToolFilter, delegate, delegationDecisionBasis, delegationError, detectTamper, discoverRuns, escapeRegExp, evaluateDelegationResult, evaluateToolGuard, foldRun, foldRunCard, getAllStaleReceipts, getArtifactState, getGateStatus, getLatestRunDirectory, getLockStatus, getMdFieldValue, getNextLegalPhase, getPrerequisiteBlockers, getPrerequisites, getStaleDownstreamPhases, getTodoStats, getWorkflowProfile, inject, invalidateReceipt, isCoreArtifact, loadRouterPolicy, lockHashFromContent, makeRecursiveRoutes, mountRecursiveRoutesOnce, name, normalizeForLockHash, phaseIndex, probeCapabilities, readReceipt, receiptPath, renderRecursivePolicy, replyPath, resolveEnforcementConfig, resolveRole, resolveRunDir, reviewBundleDir, reviewOutputSchema, routerPolicyPath, snapshotWorkspace, trimMdValue, validateChain, validateReferences, validateTransition, writeActionRecord, writeReceipt };
+export { DEFAULT_ENFORCEMENT, OPTIONAL_PHASES, PHASES, PHASE_SEQUENCE, RECURSIVE_API_PREFIX, RUN_ARTIFACT_SEQUENCE, RUN_STATES, RecursiveRuntime, apply, auditToPass, buildDelegationPrompt, buildReviewBundle, capabilityProbe, childScratchPath, coerceAskToDecision, contentSha256, coupleGateBlockToGoal, createChildBrief, createHandoff, createRecursiveCloseoutTool, createRecursiveInitTool, createRecursiveLintTool, createRecursiveLockTool, createRecursivePhaseTool, createRecursiveScratchTool, createRecursiveStatusTool, createRecursiveWorktreeTool, defaultReviewToolFilter, delegate, delegateContinuable, delegationDecisionBasis, delegationError, detectTamper, discoverRuns, drainContinuableChildren, drainContinuableDescendants, escapeRegExp, evaluateDelegationResult, evaluateToolGuard, foldRun, foldRunCard, getAllStaleReceipts, getArtifactState, getGateStatus, getLatestRunDirectory, getLockStatus, getMdFieldValue, getNextLegalPhase, getPrerequisiteBlockers, getPrerequisites, getStaleDownstreamPhases, getTodoStats, getWorkflowProfile, inject, interruptContinuable, invalidateReceipt, isCoreArtifact, isTaskClaimedBy, loadRouterPolicy, lockHashFromContent, makeRecursiveRoutes, mountRecursiveRoutesOnce, name, normalizeForLockHash, phaseIndex, probeCapabilities, readReceipt, readRepairFromStructured, readVerdictFromStructured, receiptPath, renderRecursivePolicy, renderTaskHistory, replyPath, resolveEnforcementConfig, resolveRole, resolveRunDir, reviewBundleDir, reviewOutputSchema, routerPolicyPath, snapshotWorkspace, trimMdValue, validateChain, validateReferences, validateTransition, writeActionRecord, writeReceipt };