@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/utils/photon.ts

@@ -0,0 +1,103 @@
+import type { PathOrFileDescriptor } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const fs = require("node:fs") as typeof import("node:fs");
+
+export type { PhotonImage as PhotonImageType } from "@silvia-odwyer/photon-node";
+
+type ReadFileSync = typeof fs.readFileSync;
+
+const WASM_FILENAME = "photon_rs_bg.wasm";
+
+let photonModule: typeof import("@silvia-odwyer/photon-node") | null = null;
+let loadPromise: Promise<typeof import("@silvia-odwyer/photon-node") | null> | null = null;
+
+function pathOrNull(file: PathOrFileDescriptor): string | null {
+	if (typeof file === "string") return file;
+	if (file instanceof URL) return fileURLToPath(file);
+	return null;
+}
+
+function getFallbackWasmPaths(): string[] {
+	const execDir = path.dirname(process.execPath);
+	return [
+		path.join(execDir, WASM_FILENAME),
+		path.join(execDir, "photon", WASM_FILENAME),
+		path.join(process.cwd(), WASM_FILENAME),
+	];
+}
+
+function patchPhotonWasmRead(): () => void {
+	const originalReadFileSync: ReadFileSync = fs.readFileSync.bind(fs);
+	const fallbackPaths = getFallbackWasmPaths();
+	const mutableFs = fs as { readFileSync: ReadFileSync };
+
+	const patchedReadFileSync: ReadFileSync = ((...args: Parameters<ReadFileSync>) => {
+		const [file, options] = args;
+		const resolvedPath = pathOrNull(file);
+
+		if (resolvedPath?.endsWith(WASM_FILENAME)) {
+			try {
+				return originalReadFileSync(...args);
+			} catch (error) {
+				const err = error as NodeJS.ErrnoException;
+				if (err?.code && err.code !== "ENOENT") throw error;
+
+				for (const fallbackPath of fallbackPaths) {
+					if (!fs.existsSync(fallbackPath)) continue;
+					if (options === undefined) return originalReadFileSync(fallbackPath);
+					return originalReadFileSync(fallbackPath, options);
+				}
+
+				throw error;
+			}
+		}
+
+		return originalReadFileSync(...args);
+	}) as ReadFileSync;
+
+	try {
+		mutableFs.readFileSync = patchedReadFileSync;
+	} catch {
+		Object.defineProperty(fs, "readFileSync", {
+			value: patchedReadFileSync,
+			writable: true,
+			configurable: true,
+		});
+	}
+
+	return () => {
+		try {
+			mutableFs.readFileSync = originalReadFileSync;
+		} catch {
+			Object.defineProperty(fs, "readFileSync", {
+				value: originalReadFileSync,
+				writable: true,
+				configurable: true,
+			});
+		}
+	};
+}
+
+export async function loadPhoton(): Promise<typeof import("@silvia-odwyer/photon-node") | null> {
+	if (photonModule) return photonModule;
+	if (loadPromise) return loadPromise;
+
+	loadPromise = (async () => {
+		const restoreReadFileSync = patchPhotonWasmRead();
+		try {
+			photonModule = await import("@silvia-odwyer/photon-node");
+			return photonModule;
+		} catch {
+			photonModule = null;
+			return photonModule;
+		} finally {
+			restoreReadFileSync();
+		}
+	})();
+
+	return loadPromise;
+}

package/src/worker/control-lane.ts

@@ -0,0 +1,22 @@
+/**
+ * Worker-side control lane writer.
+ *
+ * Control frames go to stderr behind the lane marker, never to stdout. A run
+ * that floods stdout with tool output therefore cannot delay a heartbeat or a
+ * cancellation acknowledgement behind megabytes of queued bulk frames: the two
+ * lanes are separate pipes with separate kernel buffers.
+ *
+ * Writes are synchronous and best effort. A control frame that cannot be
+ * written is not worth aborting a run over, and the orchestrator already treats
+ * a missing heartbeat as a stall.
+ */
+
+import { encodeControlFrame, type WorkerControlFrame } from "./protocol.js";
+
+export function emitControlFrame(frame: WorkerControlFrame): void {
+	try {
+		process.stderr.write(encodeControlFrame(frame));
+	} catch {
+		// The orchestrator's stall watchdog covers a wedged control lane.
+	}
+}

package/src/worker/entry.ts

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/**
+ * Worker subprocess entry point.
+ *
+ * Reads a WorkerSpec JSON document from stdin, re-hydrates the runtime
+ * descriptor from the runtime registry (TargetDescriptor is pure data;
+ * RuntimeDescriptor carries functions and cannot cross the stdin boundary),
+ * builds a WorkerRunInput, and dispatches to `startWorkerRun` from the engine
+ * boundary. Emits NDJSON events on stdout.
+ */
+
+// A fleet run puts N of these in the process table at once. Name the process
+// before the spec arrives so an early failure is still identifiable; the agent
+// id is appended once the spec is parsed.
+process.title = "clio-coder-worker";
+
+import { AI_AGENT_NAME } from "../core/agent-environment.js";
+import { deleteInjectedCompileCacheFrom } from "../core/compile-cache.js";
+import {
+	setGitCommitAttributionEnabled,
+	withManagedGitCommitAttributionEnvironment,
+} from "../core/git-commit-attribution.js";
+
+process.env.AI_AGENT = AI_AGENT_NAME;
+
+// Consume the compile-cache pair the dispatcher injected for THIS entry's
+// module graph. Node read NODE_COMPILE_CACHE at bootstrap, before any of this
+// ran, so the worker's own cache stays enabled; deleting the pair here is what
+// keeps it out of every child this process spawns: bash tool commands, hooks,
+// and external runtime subprocesses (claude, antigravity) that would otherwise
+// inherit the unfiltered environment and write into Clio's cache.
+deleteInjectedCompileCacheFrom(process.env);
+
+// Marks this process, and every child a worker's own bash tool spawns, as
+// running inside a dispatched worker rather than the operator's interactive
+// session. `installSkillFromSource` reads this to stamp skill provenance with
+// who performed the install, so a skill a worker drops into a trusted root
+// does not read as operator-installed. Set unconditionally at both local and
+// remote launch, since neither transport otherwise leaves a uniform signal on
+// the worker's own environment.
+process.env.CLIO_CODER_WORKER_RUN = "1";
+
+import { setProtectedModelsProvider, setResidencyNoticeSink } from "../engine/apis/residency.js";
+import { startWorkerRun, type WorkerRunInput, workerProviderSupportsTools } from "../engine/worker-runtime.js";
+import { attestedToolSignature } from "../engine/worker-tools.js";
+import { emitControlFrame } from "./control-lane.js";
+import { projectWorkerEventForStdout } from "./event-projection.js";
+import { startWorkerHeartbeat } from "./heartbeat.js";
+import { createWorkerAgentLedgerPort } from "./ledger-mirror.js";
+import { drainStdout, emitEvent } from "./ndjson.js";
+import { endpointIdentityHash, WORKER_PROTOCOL_VERSION, workerSpecDigest } from "./protocol.js";
+import { observeHostIdentity, observeWorkerResourceFacts } from "./resource-facts.js";
+import { resolveWorkerRuntime } from "./runtime-registry.js";
+import { validateRehydratedWorkerRuntime, type WorkerSpec } from "./spec-contract.js";
+import { createOrderedSteerHandler, createWorkerStdinDemux } from "./stdin-demux.js";
+
+/** Bound between channel-close abort and forced exit for a hung run. */
+const CHANNEL_CLOSE_EXIT_GRACE_MS = 5000;
+
+/**
+ * The process group an abort must escalate against. A remote launch exports
+ * the group leader the login shell established, because `exec` preserves it
+ * across the shell replacement. A local launch is spawned detached, which
+ * makes this process its own group leader. Windows has no process groups and
+ * reports null rather than an id the orchestrator cannot signal.
+ */
+/**
+ * Operator-configured labels for this node. They ride the transport
+ * environment rather than the WorkerSpec because the node, not the request,
+ * is what they describe: the same spec dispatched to two nodes must attest two
+ * different label sets.
+ */
+function configuredNodeLabels(): string[] {
+	return (process.env.CLIO_CODER_WORKER_LABELS ?? "")
+		.split(",")
+		.map((label) => label.trim())
+		.filter((label) => label.length > 0);
+}
+
+function announcedProcessGroupId(): number | null {
+	const declared = Number.parseInt(process.env.CLIO_CODER_WORKER_PGID ?? "", 10);
+	if (Number.isSafeInteger(declared) && declared > 0) return declared;
+	return process.platform === "win32" ? null : process.pid;
+}
+
+/**
+ * Attest this process, this node, and the route identity it resolved, on the
+ * control lane, before any model call. The orchestrator compares every field
+ * against the plan it approved and kills a drifting peer instead of running it.
+ */
+function announceWorker(spec: WorkerSpec, input: WorkerRunInput): void {
+	emitControlFrame({
+		kind: "announce",
+		attestation: {
+			protocolVersion: WORKER_PROTOCOL_VERSION,
+			specVersion: spec.specVersion,
+			pid: process.pid,
+			processGroupId: announcedProcessGroupId(),
+			host: observeHostIdentity(),
+			settingsFingerprint: spec.settingsFingerprint,
+			specDigest: workerSpecDigest(spec),
+			runtimeId: spec.runtimeId,
+			targetId: spec.target.id,
+			endpointIdentityHash: endpointIdentityHash(spec.target.url),
+			wireModelId: spec.wireModelId,
+			toolSignature: attestedToolSignature({
+				allowedTools: spec.allowedTools,
+				toolsSupported: workerProviderSupportsTools(input),
+				...(spec.toolProfile !== undefined ? { toolProfile: spec.toolProfile } : {}),
+				agentId: spec.agentId,
+				task: spec.task,
+			}),
+			resources: observeWorkerResourceFacts(configuredNodeLabels()),
+		},
+	});
+}
+
+async function main(): Promise<number> {
+	// A worker has no TUI, so residency notices go to stderr (the parent
+	// captures it for diagnostics) instead of the shared bus, keeping headless
+	// reconciliation parity with the interactive path.
+	setResidencyNoticeSink((notice) => {
+		process.stderr.write(`[worker] residency ${notice.kind}: ${notice.message}\n`);
+		if (notice.kind === "will-not-fit") {
+			emitEvent({ type: "clio_run_outcome", payload: { outcomeCode: "vram_capacity_fit_failure" } });
+		}
+	});
+	const demux = createWorkerStdinDemux();
+	process.stdin.setEncoding("utf8");
+	process.stdin.on("data", (chunk: string) => demux.feed(chunk));
+	process.stdin.on("end", () => demux.eof());
+	process.stdin.on("error", () => demux.eof());
+	process.stdin.resume();
+
+	const spec = await demux.readSpec();
+	process.title = `clio-coder-worker:${spec.agentId}`;
+	const attributionEnabled = spec.gitCommitAttribution ?? true;
+	setGitCommitAttributionEnabled(attributionEnabled);
+	const attribution = withManagedGitCommitAttributionEnvironment(process.env, {
+		cwd: process.cwd(),
+		enabled: attributionEnabled,
+	});
+	for (const key of Object.keys(process.env)) {
+		if (!(key in attribution.env)) Reflect.deleteProperty(process.env, key);
+	}
+	Object.assign(process.env, attribution.env);
+	if (attribution.diagnostic !== null) {
+		process.stderr.write(`[worker] commit attribution: ${attribution.diagnostic}\n`);
+	}
+	// The worker has no settings view of its own; the dispatcher copied the
+	// operator's configured model ids onto the spec so this process protects
+	// the same residents as the orchestrator.
+	setProtectedModelsProvider(() => spec.protectedModels ?? []);
+	const stopHeartbeat = startWorkerHeartbeat();
+
+	const runtime = await resolveWorkerRuntime(spec.runtimeId);
+	if (!runtime) {
+		process.stderr.write(`[worker] runtime '${spec.runtimeId}' not registered\n`);
+		stopHeartbeat();
+		return 2;
+	}
+	try {
+		validateRehydratedWorkerRuntime(spec, runtime);
+	} catch (err) {
+		process.stderr.write(`[worker] ${err instanceof Error ? err.message : String(err)}\n`);
+		stopHeartbeat();
+		return 2;
+	}
+
+	// The agent ledger is push-fed: the orchestrator replays the board on
+	// subscription and pushes each admitted entry after it, so the port answers
+	// a read from this local mirror instead of stalling a tool call on a round
+	// trip. A run with no ledger still gets a port, and it reads null.
+	const ledgerPort = createWorkerAgentLedgerPort({
+		...(spec.ledger !== undefined ? { ledger: spec.ledger } : {}),
+		emitControlFrame,
+	});
+	demux.onLedgerDelta((entries) => ledgerPort.acceptDelta(entries));
+
+	const input: WorkerRunInput = {
+		systemPrompt: spec.systemPrompt,
+		dynamicPromptMessages: spec.dynamicPromptMessages ?? [],
+		agentId: spec.agentId,
+		task: spec.task,
+		target: spec.target,
+		runtime,
+		wireModelId: spec.wireModelId,
+		allowedTools: spec.allowedTools,
+		budget: spec.budget,
+		...(spec.noSkills !== undefined ? { noSkills: spec.noSkills } : {}),
+		...(spec.skillPaths !== undefined ? { skillPaths: [...spec.skillPaths] } : {}),
+		...(spec.agentSkills !== undefined ? { agentSkills: [...spec.agentSkills] } : {}),
+		...(spec.trustProjectCompatRoots !== undefined ? { trustProjectCompatRoots: spec.trustProjectCompatRoots } : {}),
+		...(spec.onPermission !== undefined ? { onPermission: spec.onPermission } : {}),
+		...(spec.escalation !== undefined ? { escalation: spec.escalation } : {}),
+		...(spec.toolProfile !== undefined ? { toolProfile: spec.toolProfile } : {}),
+		...(spec.autonomy !== undefined ? { autonomy: spec.autonomy } : {}),
+		...(spec.writeRoots !== undefined ? { writeRoots: [...spec.writeRoots] } : {}),
+		...(spec.protectedArtifactState !== undefined
+			? {
+					protectedArtifactState: {
+						version: spec.protectedArtifactState.version,
+						artifacts: structuredClone(spec.protectedArtifactState.artifacts),
+					},
+				}
+			: {}),
+		...(spec.responseSchema !== undefined ? { responseSchema: spec.responseSchema } : {}),
+		...(spec.resultContract !== undefined ? { resultContract: spec.resultContract } : {}),
+		...(spec.product !== undefined ? { product: spec.product } : {}),
+		agentLedger: ledgerPort,
+		cwd: process.cwd(),
+	};
+	if (spec.modelCapabilities) input.modelCapabilities = spec.modelCapabilities;
+	if (spec.sessionId) input.sessionId = spec.sessionId;
+	if (spec.apiKey) input.apiKey = spec.apiKey;
+	if (spec.thinkingLevel) input.thinkingLevel = spec.thinkingLevel;
+	if (spec.runtimeResolution) input.runtimeResolution = spec.runtimeResolution;
+	if (spec.middlewareSnapshot) input.middlewareSnapshot = spec.middlewareSnapshot;
+	// Attest after the runtime is rehydrated and the run input is fully
+	// resolved, so the announced identity describes the run that is about to
+	// start, and strictly before startWorkerRun reaches a model.
+	announceWorker(spec, input);
+	// Slim streaming events before NDJSON serialization: pi's message_update
+	// carries the full cumulative message twice (top-level + assistantMessageEvent
+	// .partial), which reserializes quadratically on stdout. No worker-stdout
+	// consumer reads those cumulative snapshots (see event-projection.ts).
+	const handle = startWorkerRun(input, (event) => emitEvent(projectWorkerEventForStdout(event)));
+	// The demux buffers lines that landed before the runtime handle existed.
+	// Single-shot subprocesses expose no steer method, and an SDK query can race
+	// completion. The runtime emits the receipt-bearing clio_steer_received event
+	// only after it accepts the message; rejected input is diagnostic-only.
+	demux.onSteer(
+		createOrderedSteerHandler(
+			(text) => handle.steer?.(text) ?? false,
+			({ text, sequence }) => emitEvent({ type: "clio_steer_received", payload: { chars: text.trim().length, sequence } }),
+			(reason) => process.stderr.write(`[worker] dropped steer: ${reason}\n`),
+		),
+	);
+	// Permission-decision lines resolve a parked escalation. Unknown or
+	// duplicate requestIds return false and are dropped without crashing the
+	// worker; runtimes without an escalation loop simply have no handler.
+	demux.onPermissionDecision(({ requestId, decision }) => {
+		const resolved = handle.resolvePermission?.(requestId, decision) ?? false;
+		if (!resolved) {
+			process.stderr.write(`[worker] dropped permission_decision for unknown request '${requestId}'\n`);
+		}
+	});
+	// Parent monitor: the control channel closing after the spec means the
+	// dispatcher is gone (orchestrator exit, SSH channel drop). Abort the run
+	// and bound the exit so no worker is ever stranded on a remote node. The
+	// timer is unref'd: it cannot keep an otherwise-finished process alive,
+	// but it fires if a hung run is still holding the event loop.
+	demux.onChannelClose(() => {
+		process.stderr.write("[worker] control channel closed; aborting run\n");
+		emitControlFrame({ kind: "cancel_ack", at: Date.now() });
+		handle.abort();
+		const forceExit = setTimeout(() => process.exit(1), CHANNEL_CLOSE_EXIT_GRACE_MS);
+		forceExit.unref?.();
+	});
+	const onSignal = () => {
+		emitControlFrame({ kind: "cancel_ack", at: Date.now() });
+		handle.abort();
+	};
+	process.on("SIGINT", onSignal);
+	process.on("SIGTERM", onSignal);
+	try {
+		const result = await handle.promise;
+		return result.exitCode;
+	} finally {
+		stopHeartbeat();
+		process.off("SIGINT", onSignal);
+		process.off("SIGTERM", onSignal);
+		const dropped = demux.droppedLineCount();
+		if (dropped > 0) {
+			process.stderr.write(`[worker] dropped ${dropped} unrecognized stdin line(s) after the spec\n`);
+		}
+		// Best-effort dispose of any LMStudioClient instances cached by the
+		// engine so we close their WebSocket sessions cleanly before the worker
+		// process exits.
+	}
+}
+
+main().then(
+	async (code) => {
+		await drainStdout();
+		process.exit(code);
+	},
+	async (err) => {
+		const msg = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`[worker] fatal: ${msg}\n`);
+		await drainStdout();
+		process.exit(2);
+	},
+);

package/src/worker/event-projection.ts

@@ -0,0 +1,56 @@
+/**
+ * Worker-only event projection applied just before an event is serialized to
+ * the worker subprocess NDJSON stdout channel.
+ *
+ * pi-agent-core's `message_update` event carries the full cumulative assistant
+ * message twice: once at the top level (`message: AgentMessage`) and once
+ * nested under `assistantMessageEvent.partial: AssistantMessage`. Only the
+ * event's `delta` is incremental. Because both cumulative snapshots are
+ * re-serialized on every streaming delta, a long worker response amplifies
+ * stdout quadratically. Measured against the current emitter: ~72x for a 1KB
+ * response, ~531x for 10KB, ~2570x for 100KB (matching the receipt
+ * 2runue8q1v7q postmortem, which recorded ~4.67M tokens and 133 tool calls on
+ * a canceled native worker run).
+ *
+ * No worker-stdout consumer reads either cumulative field:
+ *   - the dispatch board reads only `assistantMessageEvent.type` to stamp the
+ *     first-token latency (src/interactive/dispatch-board.ts),
+ *   - the streamed answer and the finish contract are reconstructed from the
+ *     last assistant `message_end` (src/tools/dispatch.ts,
+ *     src/domains/dispatch/extension.ts), and
+ *   - token accounting reads `message_end.message.usage`
+ *     (src/domains/observability/projection.ts, dispatch-board.ts).
+ *
+ * The in-process orchestrator surfaces that DO render `assistantMessageEvent.partial`
+ * live (chat-loop, ACP server, status state machine) subscribe to their own
+ * in-process Agent and never cross this NDJSON seam, so slimming the worker
+ * stream leaves interactive streaming untouched. That is why the fix lives here
+ * at the worker stdout boundary rather than in the shared engine emit path.
+ *
+ * This projection drops the two per-delta cumulative snapshots and keeps the
+ * incremental `delta` plus the structural discriminants (`type`,
+ * `contentIndex`), collapsing worker stdout back to linear size while
+ * preserving every consumer contract. Every non-`message_update` event
+ * (including the load-bearing `message_end`/`agent_end` transcripts and every
+ * `clio_*` event) passes through byte-identical, so unknown-event passthrough
+ * and terminal reconstruction are unaffected.
+ */
+
+import type { AgentEvent } from "../engine/types.js";
+import type { ClioWorkerEvent } from "../engine/worker-events.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+export function projectWorkerEventForStdout(event: AgentEvent | ClioWorkerEvent): unknown {
+	if (!isRecord(event) || event.type !== "message_update") return event;
+	// Drop the top-level cumulative AgentMessage snapshot.
+	const { message: _message, assistantMessageEvent, ...rest } = event as Record<string, unknown>;
+	if (!isRecord(assistantMessageEvent)) return rest;
+	// Drop the nested cumulative AssistantMessage snapshot, keep the rest
+	// (`type`, `contentIndex`, `delta`, and any once-per-block fields such as
+	// `content`/`toolCall` that are not re-emitted per delta).
+	const { partial: _partial, ...slimAssistantMessageEvent } = assistantMessageEvent;
+	return { ...rest, assistantMessageEvent: slimAssistantMessageEvent };
+}

package/src/worker/heartbeat.ts

@@ -0,0 +1,24 @@
+/**
+ * Worker-side heartbeat emitter.
+ *
+ * Beats ride the stderr control lane on a fixed interval so the orchestrator's
+ * watchdog registers activity even when the model is mid-thinking with no
+ * streaming output, and so a saturated bulk stdout queue can never starve them.
+ * An initial beat fires immediately, so short runs still register once before
+ * exit.
+ *
+ * The interval timer is `unref`'d: it must not keep the worker process alive
+ * past the agent run, and the returned stop fn is called from the worker
+ * entry once `handle.promise` resolves.
+ */
+
+import { emitControlFrame } from "./control-lane.js";
+
+export function startWorkerHeartbeat(intervalMs = 1000): () => void {
+	// A beat carries no timestamp: arrival on the orchestrator's clock is the
+	// only instant liveness math may read.
+	emitControlFrame({ kind: "heartbeat" });
+	const id = setInterval(() => emitControlFrame({ kind: "heartbeat" }), intervalMs);
+	id.unref?.();
+	return () => clearInterval(id);
+}

package/src/worker/ledger-mirror.ts

@@ -0,0 +1,95 @@
+/**
+ * Worker-side agent-ledger mirror and port.
+ *
+ * The mirror is the worker's whole view of the board. The orchestrator pushes
+ * `ledger_delta` frames down stdin and the mirror dedupes them by sequence, so
+ * a read answers locally with an explicit watermark instead of blocking a tool
+ * call on a round trip. A read is slightly stale and says so.
+ *
+ * The control lane is one-way, so a post cannot learn the orchestrator's
+ * verdict. The port therefore enforces the body bounds and the per-run post cap
+ * locally to give the model a synchronous typed refusal, while the orchestrator
+ * enforces the same rules authoritatively at append. Only what the orchestrator
+ * admitted is what a receipt counts.
+ */
+
+import {
+	type AgentLedgerBody,
+	type AgentLedgerEntry,
+	type AgentLedgerPort,
+	parseAgentLedgerBody,
+	type WorkerControlFrame,
+} from "./protocol.js";
+
+/** Mirrors the orchestrator's per-run cap so a refusal is synchronous. */
+export const WORKER_AGENT_LEDGER_POST_CAP = 20;
+
+/**
+ * Refusal tokens shared with the orchestrator's append path, so a worker-local
+ * refusal and the authoritative one a receipt counts read the same.
+ */
+export type WorkerAgentLedgerRefusal = "invalid-body" | "per-run-cap" | "no-ledger";
+
+export interface WorkerAgentLedgerMirror {
+	/** Merge one pushed batch, deduping by sequence. */
+	apply(entries: ReadonlyArray<AgentLedgerEntry>): void;
+	entries(): ReadonlyArray<AgentLedgerEntry>;
+	/** Highest sequence this mirror has seen. */
+	watermark(): number;
+}
+
+export function createWorkerAgentLedgerMirror(): WorkerAgentLedgerMirror {
+	const bySequence = new Map<number, AgentLedgerEntry>();
+	let watermark = 0;
+	return {
+		apply(entries: ReadonlyArray<AgentLedgerEntry>): void {
+			for (const entry of entries) {
+				bySequence.set(entry.sequence, entry);
+				if (entry.sequence > watermark) watermark = entry.sequence;
+			}
+		},
+		entries(): ReadonlyArray<AgentLedgerEntry> {
+			return [...bySequence.values()].sort((left, right) => left.sequence - right.sequence);
+		},
+		watermark(): number {
+			return watermark;
+		},
+	};
+}
+
+export interface WorkerAgentLedgerPortDeps {
+	/** The spec's ledger field. Absent when this run has no ledger at all. */
+	ledger?: { id: string; sequence: number };
+	emitControlFrame: (frame: WorkerControlFrame) => void;
+	/** Defaults to a private mirror; injectable so a caller can feed it deltas. */
+	mirror?: WorkerAgentLedgerMirror;
+}
+
+/** The shared port plus the stdin-side entry point that feeds the mirror. */
+export interface WorkerAgentLedgerPort extends AgentLedgerPort {
+	acceptDelta(entries: ReadonlyArray<AgentLedgerEntry>): void;
+}
+
+export function createWorkerAgentLedgerPort(deps: WorkerAgentLedgerPortDeps): WorkerAgentLedgerPort {
+	const mirror = deps.mirror ?? createWorkerAgentLedgerMirror();
+	const { ledger, emitControlFrame } = deps;
+	let posted = 0;
+	return {
+		post(body: AgentLedgerBody): { ok: true } | { ok: false; reason: WorkerAgentLedgerRefusal } {
+			if (ledger === undefined) return { ok: false, reason: "no-ledger" };
+			const parsed = parseAgentLedgerBody(body);
+			if (!parsed.ok) return { ok: false, reason: "invalid-body" };
+			if (posted >= WORKER_AGENT_LEDGER_POST_CAP) return { ok: false, reason: "per-run-cap" };
+			posted += 1;
+			emitControlFrame({ kind: "ledger_post", body: parsed.body });
+			return { ok: true };
+		},
+		read(): { open: boolean; watermark: number; entries: ReadonlyArray<AgentLedgerEntry> } | null {
+			if (ledger === undefined) return null;
+			return { open: true, watermark: mirror.watermark(), entries: mirror.entries() };
+		},
+		acceptDelta(entries: ReadonlyArray<AgentLedgerEntry>): void {
+			mirror.apply(entries);
+		},
+	};
+}

package/src/worker/ndjson.ts

@@ -0,0 +1,40 @@
+/**
+ * NDJSON stdout emitter for the worker subprocess. One JSON object per line.
+ *
+ * Failures while serializing or writing go to stderr so a single bad event does
+ * not abort the run. The orchestrator consumes stdout line-by-line; stderr is a
+ * separate channel for operator diagnostics.
+ */
+export function emitEvent(event: unknown): void {
+	try {
+		process.stdout.write(`${JSON.stringify(event)}\n`);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`[worker] failed to emit event: ${msg}\n`);
+	}
+}
+
+/**
+ * Resolve once every previously queued stdout line has been handed to the OS,
+ * or after timeoutMs when the pipe is wedged (reader gone). Write callbacks
+ * are FIFO, so an empty write's callback fires only after all buffered lines
+ * flushed. A large single NDJSON line (a big tool result) can still be
+ * buffered when the run settles; process.exit would truncate it mid-line.
+ */
+export function drainStdout(timeoutMs = 2000): Promise<void> {
+	return new Promise((resolve) => {
+		let done = false;
+		const finish = (): void => {
+			if (done) return;
+			done = true;
+			clearTimeout(timer);
+			resolve();
+		};
+		const timer = setTimeout(finish, timeoutMs);
+		try {
+			process.stdout.write("", finish);
+		} catch {
+			finish();
+		}
+	});
+}