headlesscode 1.2.1 → 1.2.2

package/src/cloud/openshell-session.ts

@@ -0,0 +1,119 @@
+/** Run one task in an OpenShell sandbox, preserving its Git worktree afterwards. */
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { spawnSync } from "node:child_process"
+import { writeTaskFiles } from "../orchestrator/cli.js"
+import type { WorktreeSpec } from "../orchestrator/split.js"
+import { runOpenShellWorktreeCommand } from "./openshell-worker.js"
+import { OPENSHELL_HARNESS_ROOT } from "./openshell-provider.js"
+
+const USAGE = `headlesscode openshell-session --repo <path> --task <text> [options]
+
+Options:
+  --repo <path>       Git repository root (required)
+  --task <text>        Task prompt (required)
+  --mode <slug>        HeadlessCode mode (default: code)
+  --model <id>         Optional model override
+  --name <name>        Worktree name (default: openshell-<timestamp>)
+  --timeout-ms <n>     Maximum task runtime (default: 1800000)
+  --image <image>      OpenShell sandbox image
+  --policy <path>      Reviewed OpenShell policy YAML (required)
+  --provider <name>    OpenShell credential provider (repeatable; default: headlesscode-openrouter)
+  --cpu <quantity>     CPU limit (default: 2)
+  --memory <quantity>  Memory limit (default: 4Gi)
+`
+
+export async function openShellSessionMain(argv: string[]): Promise<number> {
+	const parsed = parseArgs(argv)
+	if (parsed.help) {
+		process.stdout.write(USAGE)
+		return 0
+	}
+	if (parsed.error) {
+		process.stderr.write(`headlesscode openshell-session: ${parsed.error}\n\n${USAGE}`)
+		return 2
+	}
+	const repo = path.resolve(parsed.repo!)
+	if (!fs.existsSync(path.join(repo, ".git"))) {
+		process.stderr.write(`headlesscode openshell-session: ${repo} is not a Git repository root\n`)
+		return 2
+	}
+	const policy = parsed.policy ?? process.env.HEADLESSCODE_OPENSHELL_POLICY
+	if (!policy) {
+		process.stderr.write("headlesscode openshell-session: pass --policy or set HEADLESSCODE_OPENSHELL_POLICY to a reviewed policy\n")
+		return 2
+	}
+	const providers = parsed.providerNames ?? (process.env.HEADLESSCODE_OPENSHELL_PROVIDERS ?? "headlesscode-openrouter").split(",").map((value) => value.trim()).filter(Boolean)
+	if (providers.includes("headlesscode-openrouter") && !process.env.HEADLESSCODE_OPENROUTER_API_KEY) {
+		process.stderr.write("headlesscode openshell-session: export HEADLESSCODE_OPENROUTER_API_KEY so OpenShell can store it in the headlesscode-openrouter provider\n")
+		return 2
+	}
+	const name = parsed.name ?? `openshell-${Date.now()}`
+	if (!/^[A-Za-z0-9._-]+$/.test(name) || name === "." || name === "..") {
+		process.stderr.write("headlesscode openshell-session: --name may contain only letters, numbers, dot, underscore, and hyphen\n")
+		return 2
+	}
+	const taskFile = `${name}.md`
+	const spec: WorktreeSpec = { name, issues: [0], taskFile }
+	const issue = { number: 0, title: "User task", body: parsed.task }
+	writeTaskFiles(repo, [spec], [issue])
+	const worktree = path.join(repo, ".worktrees", name)
+	const branch = `headlesscode/${name}-${Date.now()}`
+	const added = spawnSync("git", ["worktree", "add", "-b", branch, worktree, "HEAD"], { cwd: repo, encoding: "utf8" })
+	if (added.status !== 0) {
+		process.stderr.write(`headlesscode openshell-session: worktree creation failed: ${added.stderr || added.stdout}\n`)
+		return 1
+	}
+	fs.copyFileSync(path.join(repo, "plans", "parallel-tasks", taskFile), path.join(worktree, "ORCHESTRATOR_TASK.md"))
+	try {
+		const cliArgs = [
+			"--task-file", path.join(worktree, "ORCHESTRATOR_TASK.md"),
+			"--workspace", worktree,
+			"--mode", parsed.mode ?? "code",
+			...(parsed.model ? ["--model", parsed.model] : []),
+		]
+		const command = `cd ${quote(OPENSHELL_HARNESS_ROOT)} && timeout --signal=TERM --kill-after=10s ${Math.ceil((parsed.timeoutMs ?? 1_800_000) / 1000)}s ./node_modules/.bin/tsx src/cli.ts ${cliArgs.map(quote).join(" ")}`
+		const result = await runOpenShellWorktreeCommand(repo, worktree, command, {
+			...(parsed.model ? { OPENROUTER_MODEL: parsed.model } : {}),
+			ORCHESTRATOR_MODE: parsed.mode ?? "code",
+		}, { image: parsed.image, policy, providers, cpu: parsed.cpu, memory: parsed.memory })
+		process.stdout.write(`OpenShell task finished: ${worktree}\nExit code: ${result.exitCode}\n${result.output}\n`)
+		return result.exitCode === 0 ? 0 : 1
+	} catch (error) {
+		process.stderr.write(`headlesscode openshell-session: ${error instanceof Error ? error.message : String(error)}\n`)
+		return 1
+	}
+}
+
+interface Args { repo?: string; task?: string; mode?: string; model?: string; name?: string; policy?: string; image?: string; providerNames?: string[]; cpu?: string; memory?: string; timeoutMs?: number; help?: boolean; error?: string }
+
+function parseArgs(argv: string[]): Args {
+	const out: Args = {}
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]
+		if (arg === "--help" || arg === "-h") out.help = true
+		else if (["--repo", "--task", "--mode", "--model", "--name", "--policy", "--image", "--timeout-ms", "--provider", "--cpu", "--memory"].includes(arg)) {
+			const value = argv[++i]
+			if (!value || value.startsWith("--")) return { error: `missing value for ${arg}` }
+			if (arg === "--repo") out.repo = value
+			else if (arg === "--task") out.task = value
+			else if (arg === "--mode") out.mode = value
+			else if (arg === "--model") out.model = value
+			else if (arg === "--name") out.name = value
+			else if (arg === "--policy") out.policy = value
+			else if (arg === "--image") out.image = value
+			else if (arg === "--provider") (out.providerNames ??= []).push(value)
+			else if (arg === "--cpu") out.cpu = value
+			else if (arg === "--memory") out.memory = value
+			else {
+				const timeoutMs = Number(value)
+				if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1000) return { error: "--timeout-ms must be an integer of at least 1000" }
+				out.timeoutMs = timeoutMs
+			}
+		} else return { error: `unknown option ${arg}` }
+	}
+	if (!out.help && (!out.repo || !out.task)) return { error: "--repo and --task are required" }
+	return out
+}
+
+function quote(value: string): string { return `'${value.replace(/'/g, `'\\''`)}'` }

package/src/cloud/openshell-subsession.ts

@@ -0,0 +1,63 @@
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+import { mainRepositoryForWorktree, runOpenShellWorktreeCommand } from "./openshell-worker.js"
+import { OPENSHELL_HARNESS_ROOT } from "./openshell-provider.js"
+
+const SESSION_FILES_ROOT = "/workspace/.headlesscode-session"
+
+export async function runOpenShellSubsession<T>(
+	role: "review" | "qa",
+	workspaceRoot: string,
+	payload: Record<string, unknown>,
+): Promise<T> {
+	const workspace = path.resolve(workspaceRoot)
+	const repo = mainRepositoryForWorktree(workspace)
+	const sessionPayload = remapWorkspacePaths(payload, workspace)
+	let stagedPromptDir: string | undefined
+	if (role === "review" && typeof sessionPayload.reviewPromptPath === "string") {
+		// Copy only the selected prompt file into the disposable session clone.
+		stagedPromptDir = fs.mkdtempSync(path.join(os.tmpdir(), "headlesscode-openshell-review-"))
+		try {
+			fs.chmodSync(stagedPromptDir, 0o755)
+			const stagedPrompt = path.join(stagedPromptDir, "review-prompt.md")
+			fs.copyFileSync(String(sessionPayload.reviewPromptPath), stagedPrompt)
+			fs.chmodSync(stagedPrompt, 0o644)
+			sessionPayload.reviewPromptPath = `${SESSION_FILES_ROOT}/review-prompt.md`
+		} catch (error) {
+			fs.rmSync(stagedPromptDir, { recursive: true, force: true })
+			throw error
+		}
+	}
+	const encoded = Buffer.from(JSON.stringify(sessionPayload), "utf8").toString("base64url")
+	const quote = (value: string): string => `'${value.replaceAll("'", "'\\''")}'`
+	const command = `cd ${quote(OPENSHELL_HARNESS_ROOT)} && ./node_modules/.bin/tsx src/cli.ts openshell-${role}-session ${quote(encoded)}`
+	let cleanedUp = false
+	try {
+		const result = await runOpenShellWorktreeCommand(repo, workspace, command, {}, stagedPromptDir ? {
+			readOnlyMounts: [{ source: stagedPromptDir, target: SESSION_FILES_ROOT }],
+			importResults: false,
+		} : { importResults: false })
+		cleanedUp = true
+		const line = result.output.split(/\r?\n/).reverse().find((item) => item.startsWith("HEADLESSCODE_RESULT_JSON:"))
+		if (!line) throw new Error(`OpenShell ${role} session returned no result JSON (exit ${result.exitCode}): ${result.output}`)
+		return JSON.parse(line.slice("HEADLESSCODE_RESULT_JSON:".length)) as T
+	} finally {
+		// If sandbox teardown failed, retain the mounted file for recovery. A
+		// missing marker means validation failed before sandbox creation began.
+		if (stagedPromptDir && (cleanedUp || !fs.existsSync(path.join(workspace, ".harness.openshell-sandbox")))) {
+			fs.rmSync(stagedPromptDir, { recursive: true, force: true })
+		}
+	}
+}
+
+function remapWorkspacePaths(value: unknown, workspace: string): any {
+	if (typeof value === "string") {
+		if (value === workspace) return "/workspace"
+		if (value.startsWith(`${workspace}${path.sep}`)) return `/workspace${value.slice(workspace.length).split(path.sep).join("/")}`
+		return value
+	}
+	if (Array.isArray(value)) return value.map((item) => remapWorkspacePaths(item, workspace))
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, remapWorkspacePaths(item, workspace)]))
+	return value
+}

package/src/cloud/openshell-worker.ts

@@ -0,0 +1,124 @@
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { execFileSync } from "node:child_process"
+
+import { OPENSHELL_HARNESS_ROOT, OpenShellSessionProvider } from "./openshell-provider.js"
+import type { OpenShellSessionProviderOptions } from "./openshell-provider.js"
+import type { CloudSessionRequest, CommandResult } from "./provider.js"
+
+const FORWARDED_ENV = [
+	"OPENROUTER_MODEL", "OPENROUTER_BASE_URL", "HEADLESSCODE_PROJECT", "HEADLESSCODE_MEMORY_DIR",
+	"HEADLESSCODE_MAX_COST_USD", "HEADLESSCODE_MAX_DURATION_MS", "HEADLESSCODE_MAX_ITERATIONS",
+	"HEADLESSCODE_WINDOW_SIZE", "HEADLESSCODE_DECISION_TIMEOUT_MS", "HEADLESSCODE_PRICING_JSON",
+	"HEADLESSCODE_CODE_MODE_BACKEND", "HEADLESSCODE_LOCAL_BACKEND_MODES", "HEADLESSCODE_CODE_MODE_MODEL",
+]
+
+function forwardedEnvironment(env: Record<string, string>): Record<string, string> {
+	const forwarded: Record<string, string> = {}
+	for (const [key, value] of Object.entries({ ...process.env, ...env })) {
+		if (value !== undefined && (FORWARDED_ENV.includes(key) || key.startsWith("HEADLESSCODE_OLLAMA_") || key.startsWith("HEADLESSCODE_CODE_MODE_MODEL__"))) {
+			forwarded[key] = value
+		}
+	}
+	return forwarded
+}
+
+function hostGitIdentity(repo: string): Record<string, string> {
+	const identity = (variable: "GIT_AUTHOR_IDENT" | "GIT_COMMITTER_IDENT"): { name: string; email: string } | undefined => {
+		const result = execFileSync("git", ["var", variable], { cwd: repo, encoding: "utf8" }).trim()
+		const match = /^(.*) <([^<>]+)> \d+ [+-]\d{4}$/.exec(result)
+		return match ? { name: match[1], email: match[2] } : undefined
+	}
+	try {
+		const author = identity("GIT_AUTHOR_IDENT")
+		const committer = identity("GIT_COMMITTER_IDENT")
+		if (!author || !committer) return {}
+		return {
+			GIT_AUTHOR_NAME: author.name,
+			GIT_AUTHOR_EMAIL: author.email,
+			GIT_COMMITTER_NAME: committer.name,
+			GIT_COMMITTER_EMAIL: committer.email,
+		}
+	} catch {
+		// The host can still inspect changes, but Git commits inside the image
+		// require a configured host identity or explicit GIT_* identity env.
+		return {}
+	}
+}
+
+/** Run a command inside an OpenShell sandbox for an existing host worktree. */
+export async function runOpenShellWorktreeCommand(
+	repo: string,
+	worktree: string,
+	command: string,
+	env: Record<string, string> = {},
+	providerOptions: OpenShellSessionProviderOptions = {},
+): Promise<CommandResult> {
+	const policy = providerOptions.policy ?? process.env.HEADLESSCODE_OPENSHELL_POLICY
+	if (!policy || !fs.existsSync(policy)) throw new Error("set HEADLESSCODE_OPENSHELL_POLICY to an existing base policy YAML")
+	const providers = providerOptions.providers ?? (process.env.HEADLESSCODE_OPENSHELL_PROVIDERS ?? "headlesscode-openrouter").split(",").map((value) => value.trim()).filter(Boolean)
+	if (providers.includes("headlesscode-openrouter") && !process.env.HEADLESSCODE_OPENROUTER_API_KEY) throw new Error("set HEADLESSCODE_OPENROUTER_API_KEY so OpenShell can provide the imported credential profile")
+	const worktreePath = path.resolve(worktree)
+	const repoPath = path.resolve(repo)
+	const name = path.basename(worktreePath)
+	const memoryDir = env.HEADLESSCODE_MEMORY_DIR ?? process.env.HEADLESSCODE_MEMORY_DIR
+	const memoryPath = memoryDir ? path.resolve(memoryDir) : undefined
+	if (memoryPath) fs.mkdirSync(memoryPath, { recursive: true })
+	const provider = new OpenShellSessionProvider({ ...providerOptions, policy, providers })
+	const request: CloudSessionRequest = {
+		repo: repoPath,
+		issue: { number: 0, title: `HeadlessCode worker ${name}` },
+		worktreeSpec: { name, issues: [], taskFile: "ORCHESTRATOR_TASK.md" },
+		env: {
+			...forwardedEnvironment(env),
+			...hostGitIdentity(repoPath),
+			...env,
+		},
+	}
+	let handle
+	try {
+		handle = await provider.spawnExistingWorktreeSession(request, worktreePath)
+		await provider.waitReady(handle)
+		return await provider.runHarness(handle, command)
+	} finally {
+		if (handle) await provider.teardown(handle)
+	}
+}
+
+export function mainRepositoryForWorktree(worktree: string): string {
+	const root = path.resolve(worktree)
+	const commonDir = execFileSync("git", ["rev-parse", "--git-common-dir"], { cwd: root, encoding: "utf8" }).trim()
+	return path.dirname(path.resolve(root, commonDir))
+}
+
+/** Internal CLI command used by scripts/run-worker.sh. */
+export async function openShellWorkerMain(argv: string[]): Promise<number> {
+	const separator = argv.indexOf("--")
+	const flags = separator < 0 ? argv : argv.slice(0, separator)
+	const workerArgs = separator < 0 ? [] : argv.slice(separator + 1)
+	let repo = ""
+	let worktree = ""
+	for (let i = 0; i < flags.length; i++) {
+		if (flags[i] === "--repo") repo = flags[++i] ?? ""
+		else if (flags[i] === "--worktree") worktree = flags[++i] ?? ""
+		else {
+			process.stderr.write(`headlesscode openshell-worker: unknown argument ${flags[i]}\n`)
+			return 2
+		}
+	}
+	if (!repo || !worktree || workerArgs.length === 0) {
+		process.stderr.write("Usage: headlesscode openshell-worker --repo <repo> --worktree <path> -- <worker CLI args...>\n")
+		return 2
+	}
+	const quote = (value: string): string => `'${value.replaceAll("'", "'\\''")}'`
+	const cli = process.env.HEADLESSCODE_SANDBOX_CLI ?? "node_modules/.bin/tsx src/cli.ts"
+	const command = `cd ${quote(OPENSHELL_HARNESS_ROOT)} && ${cli} ${workerArgs.map(quote).join(" ")}`
+	try {
+		const result = await runOpenShellWorktreeCommand(repo, worktree, command)
+		process.stdout.write(result.output)
+		return result.exitCode
+	} catch (error) {
+		process.stderr.write(`headlesscode openshell-worker: ${error instanceof Error ? error.message : String(error)}\n`)
+		return 1
+	}
+}

package/src/engine/events.ts

@@ -37,6 +37,9 @@
  *   → `.harness.inject-message` marker; see loop.ts's checkInjectedMessage.
  *   The text has been appended to the session's live history as a plain
  *   user-role message and the next LLM call sees it)
+ *   iteration_intervention_queued / applied / abstained (optional typed
+ *   iteration-boundary monitor; fixed-template requests only, with abstains
+ *   recording malformed, duplicate, timed-out, or late requests)
  *
  * `condensed` is the one structural event that was originally only a log line
  * (`[condense] oldest turns condensed…` in src/engine/condense.ts) — the

package/src/engine/loop.ts

@@ -98,6 +98,10 @@ import type {
 	SessionResult,
 	SessionBudgetUsage,
 	SessionCompletionVerification,
+	IterationBoundaryHook,
+	IterationBoundarySnapshot,
+	IterationBoundaryIntervention,
+	IterationBoundaryToolRecord,
 	ToolContext,
 	ToolResult,
 } from "./types.js"
@@ -146,6 +150,14 @@ const PAUSED_FILENAME = ".harness.paused"
  */
 export const INJECT_MESSAGE_FILENAME = ".harness.inject-message"
 
+/** Fixed, repository-owned monitor corrections. Monitor output never supplies text. */
+const ITERATION_INTERVENTION_TEMPLATES: Record<string, string> = {
+	"specific-correction":
+		"Check the latest tool result. Re-read the affected configuration if necessary, identify the failed precondition, and change the next action before retrying.",
+	"generic-review": "Pause and review your approach before continuing.",
+}
+const DEFAULT_ITERATION_BOUNDARY_TIMEOUT_MS = 250
+
 /**
  * 2026-08-08: raised from 50 — real rounds against non-trivial issues
  * routinely needed MORE than 50 (exploration alone regularly ate 30-45 of
@@ -1356,6 +1368,10 @@ export interface HeadlessSessionConfig {
 	 * pattern as the live-usage-snapshot tests).
 	 */
 	eventHook?: (eventType: string, fields: Record<string, unknown>) => void
+	/** Optional awaited monitor invoked between complete iterations. */
+	iterationBoundaryHook?: IterationBoundaryHook
+	/** Fail-closed timeout for the optional iteration-boundary monitor. */
+	iterationBoundaryTimeoutMs?: number
 	/**
 	 * OPT-IN local exploration phase (default OFF — see
 	 * plans/local-explore-phase-experiment.md): when truthy, HeadlessSession runs a
@@ -1509,6 +1525,8 @@ export interface ResolvedSessionConfig {
 	pausePollIntervalMs: number
 	/** Live event hook (see HeadlessSessionConfig.eventHook). */
 	eventHook?: (eventType: string, fields: Record<string, unknown>) => void
+	iterationBoundaryHook?: IterationBoundaryHook
+	iterationBoundaryTimeoutMs: number
 	/**
 	 * Opt-in local exploration phase (see HeadlessSessionConfig.localExplore).
 	 * undefined/false = OFF (zero behavior change); options object = enabled
@@ -1718,6 +1736,8 @@ export class HeadlessSession {
 	 * when HEADLESSCODE_LAZY_TOOL_CATALOG is off (the default).
 	 */
 	private lazyToolsByName: Map<string, ChatTool> = new Map()
+	/** Intervention ids already applied during this run. */
+	private readonly appliedIterationInterventionIds = new Set<string>()
 
 	constructor(config: HeadlessSessionConfig) {
 		if (!config.llmClient) {
@@ -1798,6 +1818,8 @@ export class HeadlessSession {
 			maxPauseMs: config.maxPauseMs ?? envMaxPauseMs() ?? DEFAULT_MAX_PAUSE_MS,
 			pausePollIntervalMs: config.pausePollIntervalMs ?? DEFAULT_PAUSE_POLL_INTERVAL_MS,
 			eventHook: config.eventHook,
+			iterationBoundaryHook: config.iterationBoundaryHook,
+			iterationBoundaryTimeoutMs: config.iterationBoundaryTimeoutMs ?? DEFAULT_ITERATION_BOUNDARY_TIMEOUT_MS,
 			localExplore: config.localExplore,
 		}
 
@@ -2280,6 +2302,97 @@ export class HeadlessSession {
 		}
 	}
 
+	/**
+	 * Observe one complete iteration and, if requested, append exactly one
+	 * repository-owned correction before the next model request. Runtime
+	 * validation is deliberate: callers may be JavaScript or otherwise bypass
+	 * TypeScript, and malformed monitor output must abstain rather than gain
+	 * authority over the session.
+	 */
+	private async runIterationBoundaryHook(
+		snapshot: IterationBoundarySnapshot,
+		messages: ChatMessage[],
+	): Promise<void> {
+		const hook = this.config.iterationBoundaryHook
+		if (hook === undefined || this.sessionEnded) {
+			return
+		}
+		let timedOut = false
+		let timer: ReturnType<typeof setTimeout> | undefined
+		try {
+			const result = await Promise.race([
+				Promise.resolve().then(() => hook(snapshot)),
+				new Promise<undefined>((resolve) => {
+					timer = setTimeout(() => {
+						timedOut = true
+						resolve(undefined)
+					}, this.config.iterationBoundaryTimeoutMs)
+				}),
+			])
+			if (timedOut || result === undefined) {
+				await this.emitEvent("iteration_intervention_abstained", () =>
+					this.eventFeed.emit("iteration_intervention_abstained", {
+						iteration: snapshot.iteration,
+						reason: timedOut ? "timeout" : "missing",
+					}), { iteration: snapshot.iteration })
+				return
+			}
+			const candidate = result as Partial<IterationBoundaryIntervention> | null
+			if (
+				candidate === null ||
+				typeof candidate !== "object" ||
+				typeof candidate.id !== "string" ||
+				candidate.id.trim() === "" ||
+				typeof candidate.templateId !== "string" ||
+				!Object.prototype.hasOwnProperty.call(ITERATION_INTERVENTION_TEMPLATES, candidate.templateId)
+			) {
+				await this.emitEvent("iteration_intervention_abstained", () =>
+					this.eventFeed.emit("iteration_intervention_abstained", {
+						iteration: snapshot.iteration,
+						reason: "malformed",
+					}), { iteration: snapshot.iteration })
+				return
+			}
+			const id = candidate.id.trim()
+			const templateId = candidate.templateId as string
+			await this.emitEvent("iteration_intervention_queued", () =>
+				this.eventFeed.emit("iteration_intervention_queued", {
+					iteration: snapshot.iteration,
+					interventionId: id,
+					templateId,
+				}), { iteration: snapshot.iteration })
+			if (this.sessionEnded || this.appliedIterationInterventionIds.has(id)) {
+				await this.emitEvent("iteration_intervention_abstained", () =>
+					this.eventFeed.emit("iteration_intervention_abstained", {
+						iteration: snapshot.iteration,
+						interventionId: id,
+						reason: this.sessionEnded ? "session-ended" : "duplicate",
+					}), { iteration: snapshot.iteration })
+				return
+			}
+			this.appliedIterationInterventionIds.add(id)
+			messages.push({ role: "user", content: ITERATION_INTERVENTION_TEMPLATES[templateId] })
+			await this.emitEvent("iteration_intervention_applied", () =>
+				this.eventFeed.emit("iteration_intervention_applied", {
+					iteration: snapshot.iteration,
+					interventionId: id,
+					templateId,
+				}), { iteration: snapshot.iteration })
+		} catch (error) {
+			await this.emitEvent("iteration_intervention_abstained", () =>
+				this.eventFeed.emit("iteration_intervention_abstained", {
+					iteration: snapshot.iteration,
+					reason: "error",
+				}), { iteration: snapshot.iteration })
+			this.logger.warn("[monitor] iteration-boundary hook abstained", {
+				iteration: snapshot.iteration,
+				error: error instanceof Error ? error.message : String(error),
+			})
+		} finally {
+			if (timer !== undefined) clearTimeout(timer)
+		}
+	}
+
 	/**
 	 * (S2) Fire-and-forget auxiliary write dispatcher with an ordering guard:
 	 * appends `fn` to a per-session promise chain so a later-scheduled write
@@ -3303,6 +3416,7 @@ export class HeadlessSession {
 		let consecutiveMistakes = 0
 		let lastCallSignature: string | undefined
 		let toolCalls = 0
+		let previousIterationTools: readonly IterationBoundaryToolRecord[] = []
 		// Commit-before-finishing guardrail: whether the one-per-session
 		// "uncommitted changes" nudge has already been given. A retried
 		// attempt_completion is always accepted afterwards (see
@@ -3463,6 +3577,25 @@ export class HeadlessSession {
 			// report the count at iteration start, not after.
 			const historyMessageCount = messages.length
 			this.scheduleAux(() => this.emitEvent("iteration_start", () => this.eventFeed.iterationStart(iteration, historyMessageCount)))
+			if (iteration > 1) {
+				const boundarySnapshot = Object.freeze({
+						schemaVersion: 1,
+						sessionId: this.sessionId,
+						iteration,
+						maxIterations,
+						toolCalls: previousIterationTools,
+						consecutiveMistakes,
+						readOnlyStreak,
+						identicalCallStreak,
+						repeatedToolFailureStreak: toolFailureStreakCount,
+						inputTokens: this.totalInputTokens,
+						outputTokens: this.totalOutputTokens,
+						cachedTokens: this.totalCachedTokens,
+						totalToolCalls: toolCalls,
+					reasoningAvailable: messages.some((message) => typeof message.reasoning === "string" && message.reasoning.length > 0),
+				})
+				await this.runIterationBoundaryHook(boundarySnapshot, messages)
+			}
 
 			// Pause/resume (dashboard control): block between iterations (never
 			// mid-tool-call — same safe boundary as the budget check below)
@@ -4554,6 +4687,7 @@ export class HeadlessSession {
 			// turn — the executor re-reads the file per call, so the failure
 			// mechanism is stale SEARCH text, not a stale executor).
 			const batchEditedPaths = new Map<string, string>()
+			const boundaryTools: IterationBoundaryToolRecord[] = []
 
 			// (S3) Partition this turn's calls: pure read-only/exploration calls
 			// (read_file/list_files/search_files, the TS code-intel reads, and a
@@ -4769,6 +4903,14 @@ export class HeadlessSession {
 					name: call.name,
 					content: resultContent,
 				})
+				boundaryTools.push({
+					id: call.id,
+					name: call.name,
+					arguments: Object.freeze({ ...call.args }),
+					isError,
+					result: resultContent,
+					...(isError ? { normalizedError: resultContent.split("\n", 1)[0]?.slice(0, 200) ?? "tool_error" } : {}),
+				})
 
 				// Record successful edits so a later sibling call on the same
 				// path can be diagnosed (see above).
@@ -4877,6 +5019,7 @@ export class HeadlessSession {
 					lastCallSignature = undefined
 				}
 			}
+			previousIterationTools = Object.freeze(boundaryTools.map((record) => Object.freeze(record)))
 
 			// Blind tree-walking guardrail (P1.6): after N consecutive
 			// iterations whose every tool call is a plain read/exploration

package/src/engine/types.ts

@@ -151,6 +151,48 @@ export interface ToolResult {
 	isError: boolean
 }
 
+/** Fixed corrections available to an iteration-boundary monitor. */
+export type IterationInterventionTemplateId = "specific-correction" | "generic-review"
+
+/** One completed tool call and its result at an iteration boundary. */
+export interface IterationBoundaryToolRecord {
+	readonly id: string
+	readonly name: string
+	readonly arguments: Readonly<Record<string, unknown>>
+	readonly isError: boolean
+	readonly result: string
+	readonly normalizedError?: string
+}
+
+/** Immutable, versioned observation passed to an optional monitor hook. */
+export interface IterationBoundarySnapshot {
+	readonly schemaVersion: 1
+	readonly sessionId: string
+	readonly iteration: number
+	readonly maxIterations: number
+	readonly toolCalls: readonly IterationBoundaryToolRecord[]
+	readonly consecutiveMistakes: number
+	readonly readOnlyStreak: number
+	readonly identicalCallStreak: number
+	readonly repeatedToolFailureStreak: number
+	readonly inputTokens: number
+	readonly outputTokens: number
+	readonly cachedTokens: number
+	readonly totalToolCalls: number
+	readonly reasoningAvailable: boolean
+}
+
+/** Advisory response accepted from an iteration-boundary monitor. */
+export interface IterationBoundaryIntervention {
+	readonly id: string
+	readonly templateId: IterationInterventionTemplateId
+}
+
+/** Optional monitor callback. It has no authority beyond requesting a fixed correction. */
+export type IterationBoundaryHook = (
+	snapshot: IterationBoundarySnapshot,
+) => IterationBoundaryIntervention | null | undefined | Promise<IterationBoundaryIntervention | null | undefined>
+
 /**
  * Usage of one LLM call made OUTSIDE the main loop's request path — e.g. the
  * cloud vision captioning in src/vision/describe.ts (browser screenshots and

package/src/monitoring/controller.ts

@@ -0,0 +1,73 @@
+import type {
+	FrozenPredictorArtifact,
+	InterventionDecision,
+	IterationInterventionTemplateId,
+	PilotArm,
+	PilotBoundary,
+	Prediction,
+} from "./types.js"
+import { predict, predictedIntervention } from "./predictor.js"
+
+export const SPECIFIC_CORRECTION =
+	"Check the latest tool result. Re-read the affected configuration if necessary, identify the failed precondition, and change the next action before retrying."
+export const GENERIC_REVIEW = "Pause and review your approach before continuing."
+export const TEMPLATE_TEXT: Readonly<Record<IterationInterventionTemplateId, string>> = {
+	"specific-correction": SPECIFIC_CORRECTION,
+	"generic-review": GENERIC_REVIEW,
+}
+
+export interface ControllerState {
+	readonly arm: PilotArm
+	readonly disarmed: boolean
+	readonly appliedInterventionIds: ReadonlySet<string>
+}
+
+export function initialControllerState(arm: PilotArm): ControllerState {
+	return { arm, disarmed: false, appliedInterventionIds: new Set() }
+}
+
+export function decide(
+	artifact: FrozenPredictorArtifact | undefined,
+	boundary: PilotBoundary,
+	state: ControllerState,
+	prediction?: Prediction,
+): { prediction?: Prediction; decision?: InterventionDecision; state: ControllerState } {
+	if (state.disarmed || state.arm === "B") return { prediction, state }
+	const nextPrediction = prediction ?? (artifact === undefined ? undefined : predict(artifact, boundary))
+	if (nextPrediction === undefined || artifact === undefined || !predictedIntervention(artifact, nextPrediction)) {
+		return { prediction: nextPrediction, state }
+	}
+	const templateId: IterationInterventionTemplateId = state.arm === "G" ? "generic-review" : "specific-correction"
+	const interventionId = `${boundary.attemptId}:${boundary.sequence}:${templateId}`
+	if (state.appliedInterventionIds.has(interventionId)) return { prediction: nextPrediction, state }
+	const applied = new Set(state.appliedInterventionIds)
+	applied.add(interventionId)
+	return {
+		prediction: nextPrediction,
+		decision: { interventionId, templateId, reason: "threshold" },
+		state: { ...state, disarmed: true, appliedInterventionIds: applied },
+	}
+}
+
+export function randomDecision(
+	boundary: PilotBoundary,
+	state: ControllerState,
+	probability: number,
+	random: () => number,
+): { decision?: InterventionDecision; state: ControllerState } {
+	if (state.disarmed || state.arm !== "R" || probability <= 0 || random() >= probability) return { state }
+	const interventionId = `${boundary.attemptId}:${boundary.sequence}:specific-correction`
+	if (state.appliedInterventionIds.has(interventionId)) return { state }
+	const applied = new Set(state.appliedInterventionIds)
+	applied.add(interventionId)
+	return {
+		decision: { interventionId, templateId: "specific-correction", reason: "random-schedule" },
+		state: { ...state, disarmed: true, appliedInterventionIds: applied },
+	}
+}
+
+export function applyFixedTemplate(messages: string[], decision: InterventionDecision): void {
+	const text = TEMPLATE_TEXT[decision.templateId]
+	if (typeof text !== "string") throw new Error("unknown intervention template")
+	messages.push(text)
+}