@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/dispatch/state.ts

@@ -0,0 +1,302 @@
+/**
+ * Dispatch run ledger with atomic writes (Phase 6 slice 2).
+ *
+ * On-disk layout under `clioStateDir()`:
+ *   runs.json                    JSON array of RunEnvelope, newest first
+ *   receipts/<runId>.json        per-run RunReceipt
+ *
+ * The ledger holds an in-memory mirror of runs.json. `create()` and `update()`
+ * mutate memory only; `persist()` writes the bounded ring (default 1000, env
+ * override `CLIO_CODER_MAX_DISPATCH_RUNS`) atomically via engine.atomicWrite.
+ *
+ * No worker spawning, no domain wire-up, no SafeEventBus emission yet. Those
+ * land in P6S3 and P6S5. This slice is a pure persistence primitive.
+ *
+ * A crash between recordReceipt and persist leaves the receipt JSON on disk
+ * without a ledger entry. The dispatch extension closes that gap at startup by
+ * scanning receipts/ and adopting verified orphans back into the ledger via
+ * adopt() (see orphan-recovery.ts).
+ */
+
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveGuardrail } from "../../core/guardrails.js";
+import { withStateFileLock } from "../../core/state-file-lock.js";
+import { clioStateDir, stateRootRemoved } from "../../core/xdg.js";
+import { atomicWrite } from "../../engine/session.js";
+import { computeReceiptFindingsSummary } from "./receipt-findings.js";
+import { withReceiptIntegrity } from "./receipt-integrity.js";
+import type { RunEnvelope, RunReceipt, RunReceiptDraft, RunStatus } from "./types.js";
+
+export interface LedgerOptions {
+	maxRuns?: number;
+}
+
+export type CreateRunInput = Omit<
+	RunEnvelope,
+	| "id"
+	| "startedAt"
+	| "endedAt"
+	| "exitCode"
+	| "status"
+	| "pid"
+	| "heartbeatAt"
+	| "receiptPath"
+	| "tokenCount"
+	| "costUsd"
+>;
+
+export interface Ledger {
+	create(input: CreateRunInput): RunEnvelope;
+	update(id: string, patch: Partial<RunEnvelope>): RunEnvelope | null;
+	get(id: string): RunEnvelope | null;
+	list(opts?: { status?: RunStatus; limit?: number }): ReadonlyArray<RunEnvelope>;
+	recordReceipt(id: string, receipt: RunReceiptDraft): RunReceipt;
+	/** Insert a fully-formed envelope recovered from a durable artifact. Returns false when the id already exists. */
+	adopt(envelope: RunEnvelope): boolean;
+	persist(): Promise<void>;
+	reload(): void;
+}
+
+function newRunId(): string {
+	const n = BigInt(`0x${randomBytes(8).toString("hex")}`);
+	const raw = n.toString(36);
+	if (raw.length >= 12) return raw.slice(0, 12);
+	return raw.padStart(12, "0");
+}
+
+function runsPath(): string {
+	return join(clioStateDir(), "runs.json");
+}
+
+function receiptPathFor(runId: string): string {
+	return join(clioStateDir(), "receipts", `${runId}.json`);
+}
+
+function readRuns(): RunEnvelope[] {
+	const path = runsPath();
+	if (!existsSync(path)) return [];
+	const raw = readFileSync(path, "utf8").trim();
+	if (raw.length === 0) return [];
+	const parsed = JSON.parse(raw) as RunEnvelope[];
+	if (!Array.isArray(parsed)) return [];
+	return parsed;
+}
+
+function resolveMaxRuns(opt?: number | undefined): number {
+	if (opt !== undefined && opt > 0) return Math.floor(opt);
+	// env (CLIO_CODER_MAX_DISPATCH_RUNS) > settings guardrails > default; see core/guardrails.ts.
+	return resolveGuardrail("maxDispatchRuns");
+}
+
+function applyPatch(rec: RunEnvelope, patch: Partial<RunEnvelope>): RunEnvelope {
+	const out: RunEnvelope = { ...rec };
+	for (const key of Object.keys(patch) as Array<keyof RunEnvelope>) {
+		const value = patch[key];
+		if (value === undefined) continue;
+		// Generic write into a strongly-typed record. Patch keys are constrained
+		// by Partial<RunEnvelope>, so the value type aligns with the field type.
+		(out as unknown as Record<string, unknown>)[key] = value;
+	}
+	return out;
+}
+
+function cloneEnvelope(envelope: RunEnvelope): RunEnvelope {
+	return structuredClone(envelope);
+}
+
+/**
+ * Only a row this process actually wrote is newer than disk. The mirror also
+ * holds rows read at open time that belong to sibling processes, and letting
+ * those win reverted a sibling's settled run to the snapshot this process
+ * happened to read: a dispatch that finished `completed`/0 reappeared as
+ * `running` with a null receiptPath, and the next recovery pass then sealed it
+ * `dead`/1. So memory wins only for `dirty` ids; every other id takes the disk
+ * copy. A non-dirty mirror row absent from disk was evicted by a sibling's ring
+ * cap and stays evicted rather than being resurrected on every persist.
+ */
+function mergeRunsById(disk: RunEnvelope[], memory: RunEnvelope[], dirty: ReadonlySet<string>): RunEnvelope[] {
+	const merged = new Map<string, RunEnvelope>();
+	for (const r of disk) merged.set(r.id, r);
+	for (const r of memory) {
+		if (!dirty.has(r.id)) continue;
+		merged.set(r.id, r);
+	}
+	const all = Array.from(merged.values());
+	all.sort((a, b) => (a.startedAt < b.startedAt ? 1 : a.startedAt > b.startedAt ? -1 : 0));
+	return all;
+}
+
+/**
+ * Ring eviction takes finished rows only. Rows sort `startedAt` DESC, so a run
+ * that has been executing for hours sits at the bottom and a plain
+ * `slice(0, maxRuns)` drops the process's own live state while maxRuns newer,
+ * already-finished rows survive. Live rows (`endedAt === null`) are therefore
+ * kept unconditionally and the cap is spent on the finished remainder. Order
+ * inside the kept set is unchanged, still `startedAt` DESC.
+ */
+function capRuns(all: RunEnvelope[], maxRuns: number): RunEnvelope[] {
+	if (all.length <= maxRuns) return all;
+	const live = all.filter((r) => r.endedAt === null);
+	if (live.length === 0) return all.slice(0, maxRuns);
+	let finishedBudget = Math.max(0, maxRuns - live.length);
+	const kept: RunEnvelope[] = [];
+	for (const run of all) {
+		if (run.endedAt === null) {
+			kept.push(run);
+			continue;
+		}
+		if (finishedBudget === 0) continue;
+		finishedBudget -= 1;
+		kept.push(run);
+	}
+	return kept;
+}
+
+export function openLedger(opts?: LedgerOptions): Ledger {
+	const maxRuns = resolveMaxRuns(opts?.maxRuns);
+	let runs: RunEnvelope[] = readRuns();
+	// Ids this process has written since the last successful persist. See
+	// mergeRunsById: this is what separates our writes from a sibling's rows we
+	// merely read at open time.
+	const dirty = new Set<string>();
+
+	function findIndex(id: string): number {
+		return runs.findIndex((r) => r.id === id);
+	}
+
+	return {
+		create(input: CreateRunInput): RunEnvelope {
+			const envelope: RunEnvelope = {
+				id: newRunId(),
+				agentId: input.agentId,
+				executionRole: input.executionRole,
+				...(input.agentAudience !== undefined ? { agentAudience: input.agentAudience } : {}),
+				...(input.requestOrigin !== undefined ? { requestOrigin: input.requestOrigin } : {}),
+				task: input.task,
+				...(input.briefing !== undefined ? { briefing: structuredClone(input.briefing) } : {}),
+				...(input.steering !== undefined ? { steering: structuredClone(input.steering) } : {}),
+				targetId: input.targetId,
+				wireModelId: input.wireModelId,
+				runtimeId: input.runtimeId,
+				runtimeKind: input.runtimeKind,
+				...(input.timing !== undefined ? { timing: structuredClone(input.timing) } : {}),
+				startedAt: new Date().toISOString(),
+				endedAt: null,
+				status: "queued",
+				exitCode: null,
+				pid: null,
+				heartbeatAt: null,
+				receiptPath: null,
+				sessionId: input.sessionId,
+				cwd: input.cwd,
+				tokenCount: 0,
+				reasoningTokenCount: 0,
+				...(input.staticShellHash !== undefined ? { staticShellHash: input.staticShellHash } : {}),
+				...(input.sessionShellHash !== undefined ? { sessionShellHash: input.sessionShellHash } : {}),
+				...(input.dynamicHash !== undefined ? { dynamicHash: input.dynamicHash } : {}),
+				...(input.promptSignature !== undefined ? { promptSignature: input.promptSignature } : {}),
+				...(input.toolSignature !== undefined ? { toolSignature: input.toolSignature } : {}),
+				costUsd: 0,
+			};
+			runs.unshift(envelope);
+			dirty.add(envelope.id);
+			return cloneEnvelope(envelope);
+		},
+
+		update(id: string, patch: Partial<RunEnvelope>): RunEnvelope | null {
+			const idx = findIndex(id);
+			if (idx === -1) return null;
+			const current = runs[idx];
+			if (!current) return null;
+			const next = applyPatch(current, patch);
+			runs[idx] = next;
+			dirty.add(id);
+			return cloneEnvelope(next);
+		},
+
+		get(id: string): RunEnvelope | null {
+			const idx = findIndex(id);
+			if (idx === -1) return null;
+			const envelope = runs[idx];
+			return envelope ? cloneEnvelope(envelope) : null;
+		},
+
+		list(opts?: { status?: RunStatus; limit?: number }): ReadonlyArray<RunEnvelope> {
+			let filtered: RunEnvelope[] = runs;
+			if (opts?.status) {
+				const want = opts.status;
+				filtered = filtered.filter((r) => r.status === want);
+			}
+			if (opts?.limit !== undefined && opts.limit >= 0) {
+				filtered = filtered.slice(0, opts.limit);
+			}
+			return Object.freeze(filtered.map((envelope) => cloneEnvelope(envelope)));
+		},
+
+		recordReceipt(id: string, receipt: RunReceiptDraft): RunReceipt {
+			const target = receiptPathFor(id);
+			const idx = findIndex(id);
+			if (idx === -1) {
+				throw new Error(`dispatch ledger missing run for receipt '${id}'`);
+			}
+			const current = runs[idx];
+			if (!current) {
+				throw new Error(`dispatch ledger missing run for receipt '${id}'`);
+			}
+			// Fold the durable findings summary onto the draft before sealing so both
+			// the ACP and worker finalizers get it for free and receipt integrity
+			// digest covers it. Computed cheaply from in-memory fields; never reads
+			// disk or calls buildEvidence.
+			const draft: RunReceiptDraft =
+				receipt.findingsSummary === undefined
+					? { ...receipt, findingsSummary: computeReceiptFindingsSummary(receipt, current) }
+					: receipt;
+			const receiptWithIntegrity = withReceiptIntegrity(draft, current);
+			// The sealed receipt is still returned to the finalizer that asked for
+			// it; what it must not do is write the state root back into existence
+			// under an uninstall. receiptPath stays null because no file was made.
+			if (stateRootRemoved()) return receiptWithIntegrity;
+			atomicWrite(target, JSON.stringify(receiptWithIntegrity, null, 2));
+			runs[idx] = { ...current, receiptPath: target };
+			dirty.add(id);
+			return receiptWithIntegrity;
+		},
+
+		adopt(envelope: RunEnvelope): boolean {
+			if (findIndex(envelope.id) !== -1) return false;
+			runs.push(cloneEnvelope(envelope));
+			runs.sort((a, b) => (a.startedAt < b.startedAt ? 1 : a.startedAt > b.startedAt ? -1 : 0));
+			dirty.add(envelope.id);
+			return true;
+		},
+
+		async persist(): Promise<void> {
+			// Checked twice: before the lock because acquiring it mkdirs the state
+			// root back, and again under it because the removal can land while this
+			// call waits for a sibling process to finish its own critical section.
+			if (stateRootRemoved()) return;
+			const target = runsPath();
+			await withStateFileLock(target, () => {
+				if (stateRootRemoved()) return;
+				const diskRuns = readRuns();
+				const merged = mergeRunsById(diskRuns, runs, dirty);
+				const capped = capRuns(merged, maxRuns);
+				runs = capped;
+				atomicWrite(target, JSON.stringify(capped, null, 2));
+				// Everything this process claimed is now on disk, so the mirror holds
+				// no newer state until the next write. Clearing here is what stops a
+				// long-lived process from re-asserting an old snapshot of its own rows
+				// over a sibling's later update to them.
+				dirty.clear();
+			});
+		},
+
+		reload(): void {
+			runs = readRuns();
+			// The mirror was just replaced wholesale, so any unpersisted claim is gone.
+			dirty.clear();
+		},
+	};
+}

package/src/domains/dispatch/tool-stats.ts

@@ -0,0 +1,132 @@
+/**
+ * Pure aggregation helpers for the per-tool stats folded into a RunReceipt.
+ *
+ * Sourced from the worker's ToolTelemetry stream (`clio_tool_finish` IPC
+ * events). Kept as a small standalone module so receipts have a single source
+ * of truth for the aggregation invariants, and so loops, retries, errors,
+ * blocked admissions, and parallel-batch tool calls all flow through one
+ * code path that unit tests can pin.
+ *
+ * Invariants (pinned by tests/contracts/dispatch.test.ts):
+ *   - Each recognized outcome (ok|error|blocked) increments its own bucket and
+ *     count, so count == ok + errors + blocked whenever every recorded finish
+ *     carried an outcome. The worker ToolFinishEvent always does; a synthetic
+ *     finish without an outcome increments count only.
+ *   - totalDurationMs accumulates only finite non-negative durations.
+ *   - snapshot is sorted by tool-name UTF-16 code unit ascending so receipt
+ *     digests stay deterministic across runs and host locales.
+ *   - countToolCalls returns the sum of count across every entry.
+ */
+
+import type { ActionClass } from "../safety/action-classifier.js";
+import type { ToolActivitySummary, ToolCallStat } from "./types.js";
+
+export interface ToolFinishPayload {
+	tool?: string;
+	durationMs?: number;
+	outcome?: "ok" | "error" | "blocked";
+}
+
+export interface ToolStartPayload {
+	tool?: string;
+}
+
+/** Count starts independently from finishes so a worker crash cannot disappear an in-flight call. */
+export function recordToolStart(inFlight: Map<string, number>, payload: ToolStartPayload): void {
+	if (typeof payload.tool !== "string") return;
+	inFlight.set(payload.tool, (inFlight.get(payload.tool) ?? 0) + 1);
+}
+
+/** Match one finish to its start without inventing a start for legacy or opaque streams. */
+export function recordToolCompletion(inFlight: Map<string, number>, payload: ToolFinishPayload): void {
+	if (typeof payload.tool !== "string") return;
+	const count = inFlight.get(payload.tool) ?? 0;
+	if (count <= 1) inFlight.delete(payload.tool);
+	else inFlight.set(payload.tool, count - 1);
+}
+
+export function snapshotUnfinishedTools(inFlight: ReadonlyMap<string, number>): Array<{ tool: string; count: number }> {
+	return [...inFlight.entries()]
+		.filter(([, count]) => count > 0)
+		.map(([tool, count]) => ({ tool, count }))
+		.sort((a, b) => (a.tool < b.tool ? -1 : a.tool > b.tool ? 1 : 0));
+}
+
+function blankStat(tool: string): ToolCallStat {
+	return { tool, count: 0, ok: 0, errors: 0, blocked: 0, totalDurationMs: 0 };
+}
+
+export function recordToolFinish(stats: Map<string, ToolCallStat>, payload: ToolFinishPayload): void {
+	if (typeof payload.tool !== "string") return;
+	const existing = stats.get(payload.tool) ?? blankStat(payload.tool);
+	existing.count += 1;
+	if (typeof payload.durationMs === "number" && Number.isFinite(payload.durationMs) && payload.durationMs >= 0) {
+		existing.totalDurationMs += payload.durationMs;
+	}
+	if (payload.outcome === "ok") existing.ok += 1;
+	else if (payload.outcome === "error") existing.errors += 1;
+	else if (payload.outcome === "blocked") existing.blocked += 1;
+	stats.set(payload.tool, existing);
+}
+
+export function countToolCalls(stats: Map<string, ToolCallStat>): number {
+	let total = 0;
+	for (const stat of stats.values()) total += stat.count;
+	return total;
+}
+
+export function snapshotToolStats(stats: Map<string, ToolCallStat>): ToolCallStat[] {
+	return [...stats.values()].sort((a, b) => (a.tool < b.tool ? -1 : a.tool > b.tool ? 1 : 0));
+}
+
+/**
+ * Whether a receipt contains an executed tool call that may have changed
+ * state. Failed calls are included because an error result does not prove the
+ * tool rolled back partial filesystem or external side effects. Blocked calls
+ * are excluded because admission stopped them before execution. Unknown tools
+ * are treated conservatively as potentially mutating.
+ */
+export function hasPotentiallyMutatingAttempt(
+	stats: ReadonlyArray<ToolCallStat>,
+	classify: (tool: string) => ActionClass,
+): boolean {
+	return stats.some((stat) => stat.count > stat.blocked && classify(stat.tool) !== "read");
+}
+
+/** Action classes that can change state outside the worker's own context. */
+const MUTATING_ACTION_CLASSES: ReadonlySet<ActionClass> = new Set([
+	"write",
+	"execute",
+	"dispatch",
+	"system_modify",
+	"git_destructive",
+]);
+
+export function summarizeToolActivity(
+	stats: Map<string, ToolCallStat>,
+	classify: (tool: string) => ActionClass,
+): ToolActivitySummary {
+	const summary: ToolActivitySummary = { calls: 0, succeeded: 0, failed: 0, blocked: 0, mutatingSucceeded: false };
+	for (const stat of stats.values()) {
+		summary.calls += stat.count;
+		summary.succeeded += stat.ok;
+		summary.failed += stat.errors;
+		summary.blocked += stat.blocked;
+		if (stat.ok > 0 && MUTATING_ACTION_CLASSES.has(classify(stat.tool))) {
+			summary.mutatingSucceeded = true;
+		}
+	}
+	return summary;
+}
+
+/**
+ * Factual note for a run that finished as succeeded without a single
+ * successful tool call. The outcome stays succeeded (the harness cannot judge
+ * whether the task was semantically accomplished); the note only makes the
+ * emptiness visible wherever outcomeDetail renders.
+ */
+export function zeroSuccessfulToolNote(activity: ToolActivitySummary): string | null {
+	if (activity.succeeded > 0) return null;
+	if (activity.calls === 0) return "completed without executing any tools";
+	return `completed without a successful tool call (${activity.calls} attempted: ${activity.failed} failed, ${activity.blocked} blocked)`;
+}

package/src/domains/dispatch/transport.ts

@@ -0,0 +1,210 @@
+/**
+ * Worker transport ladder.
+ *
+ * One interface, one wire protocol: a WorkerSpec JSON line into the worker's
+ * stdin, NDJSON events out of its stdout, stderr tail for diagnostics. The
+ * `local` tier is today's subprocess fork; the `ssh` tier launches the same
+ * worker entry on a remote node over an SSH-tunneled channel. Container and
+ * cloud tiers are future implementors of this same interface, not variations
+ * of the protocol.
+ *
+ * SSH tier invariants:
+ *   - The remote environment is a whitelist, never the orchestrator's
+ *     process.env. Remote workers default to CLIO_CODER_RESIDENCY=observe so a
+ *     worker on a node that serves models for the operator can never evict a
+ *     resident model.
+ *   - The orchestrator cwd is entered on the remote node (shared-filesystem
+ *     assumption; path parity is a doctor preflight, and placement refuses
+ *     nodes that have not passed it).
+ *   - Abort closes the channel (the worker's parent monitor aborts on stdin
+ *     EOF) and escalates to a remote `kill` fallback using the pid the worker
+ *     announced, so no remote process is stranded.
+ */
+
+import { spawn } from "node:child_process";
+import { AI_AGENT_NAME } from "../../core/agent-environment.js";
+import { shellQuote } from "../../core/shell-quote.js";
+import type { WorkerSpec } from "../../worker/spec-contract.js";
+import type { RunNodeIdentity } from "./types.js";
+import {
+	type SpawnedWorker,
+	type SpawnOptions,
+	spawnNativeWorker,
+	spawnWorkerProcess,
+	type WorkerProcessOptions,
+} from "./worker-spawn.js";
+
+export type WorkerTransportKind = "local" | "ssh";
+
+/**
+ * What a placement hands a transport: every process option except the env,
+ * which each transport owns. This is derived from WorkerProcessOptions rather
+ * than restated, because a restated subset is how a placed worker's
+ * `onLedgerPost` went missing: this type once listed only cwd, both transports
+ * forwarded exactly that, and every callback dispatch passed for a worker on a
+ * fleet node was dropped at the seam. Assigning the wider option literal to the
+ * narrower parameter is legal, so nothing complained.
+ */
+export type WorkerTransportSpawnOptions = Omit<WorkerProcessOptions, "env">;
+
+export interface WorkerTransport {
+	readonly kind: WorkerTransportKind;
+	readonly node: RunNodeIdentity;
+	spawn(spec: WorkerSpec, opts?: WorkerTransportSpawnOptions): SpawnedWorker;
+}
+
+/** Connection facts for one SSH-reachable fleet node. */
+export interface SshNodeEndpoint {
+	id: string;
+	host: string;
+	user?: string;
+	port?: number;
+	identityFile?: string;
+	/**
+	 * Remote worker-entry invocation. Defaults to `clio-coder worker`, which requires
+	 * a version-matched clio-coder on the remote PATH (the doctor fleet preflight
+	 * verifies both). Operators with non-PATH installs point this at their
+	 * entry, e.g. `/opt/clio-coder/bin/clio-coder worker`.
+	 */
+	clioCoderEntry?: string;
+	/**
+	 * Residency posture exported to the remote worker. Defaults to "observe":
+	 * remote workers must never evict models resident on their node. "manage"
+	 * is an explicit per-node opt-in.
+	 */
+	residency?: "observe" | "manage";
+	connectTimeoutSec?: number;
+	/**
+	 * Operator-declared capability labels for this node, exported to the remote
+	 * worker so its announcement attests the configured labels alongside the
+	 * resource values it observes.
+	 */
+	labels?: ReadonlyArray<string>;
+}
+
+export interface SshTransportOptions {
+	/** ssh client binary; contract tests substitute a fake shim. */
+	sshBinary?: string;
+	shutdownGraceMs?: number;
+}
+
+export const LOCAL_NODE_ID = "local";
+
+export function localNodeIdentity(): RunNodeIdentity {
+	return { id: LOCAL_NODE_ID, kind: "local" };
+}
+
+export function createLocalWorkerTransport(opts?: Omit<SpawnOptions, "cwd">): WorkerTransport {
+	return {
+		kind: "local",
+		node: localNodeIdentity(),
+		spawn(spec, spawnOpts) {
+			// The caller's per-spawn options ride over the transport's own defaults.
+			return spawnNativeWorker(spec, { ...opts, ...spawnOpts });
+		},
+	};
+}
+
+const DEFAULT_SSH_CONNECT_TIMEOUT_SEC = 10;
+const DEFAULT_REMOTE_CLIO_ENTRY = "clio-coder worker";
+
+/**
+ * The env whitelist exported to the remote worker. Nothing from the
+ * orchestrator's process.env crosses the wire; the WorkerSpec already carries
+ * the resolved target (whose URL resolves on the remote node, so a
+ * localhost-served model plane is per-node by construction) and any
+ * orchestrator-supplied credential.
+ */
+function remoteEnvAssignments(node: SshNodeEndpoint): string {
+	const residency = node.residency ?? "observe";
+	// `$$` is the login shell's pid, and it leads the process group the remote
+	// command runs in. `exec` replaces that shell in place, so the worker
+	// inherits both the pid and the group leadership, and the value it announces
+	// is the group an abort must signal.
+	const labels = (node.labels ?? []).map((label) => label.trim()).filter((label) => label.length > 0);
+	const labelAssignment = labels.length > 0 ? ` CLIO_CODER_WORKER_LABELS=${shellQuote(labels.join(","))}` : "";
+	return `AI_AGENT=${AI_AGENT_NAME} CLIO_CODER_RESIDENCY=${residency} CLIO_CODER_WORKER_PGID=$$${labelAssignment}`;
+}
+
+export function buildRemoteWorkerCommand(node: SshNodeEndpoint, cwd: string): string {
+	const entry =
+		node.clioCoderEntry !== undefined && node.clioCoderEntry.trim().length > 0
+			? node.clioCoderEntry.trim()
+			: DEFAULT_REMOTE_CLIO_ENTRY;
+	return `cd ${shellQuote(cwd)} && exec env ${remoteEnvAssignments(node)} ${entry}`;
+}
+
+export function buildSshArgs(node: SshNodeEndpoint, remoteCommand: string): string[] {
+	const connectTimeout = node.connectTimeoutSec ?? DEFAULT_SSH_CONNECT_TIMEOUT_SEC;
+	const args: string[] = [
+		"-o",
+		"BatchMode=yes",
+		"-o",
+		`ConnectTimeout=${connectTimeout}`,
+		// The channel is a byte pipe, never a terminal: a pty would translate
+		// newlines and inject control sequences into the NDJSON stream.
+		"-T",
+	];
+	if (node.port !== undefined) args.push("-p", String(node.port));
+	if (node.identityFile !== undefined && node.identityFile.length > 0) args.push("-i", node.identityFile);
+	if (node.user !== undefined && node.user.length > 0) args.push("-l", node.user);
+	args.push(node.host, "--", remoteCommand);
+	return args;
+}
+
+export function createSshWorkerTransport(node: SshNodeEndpoint, opts?: SshTransportOptions): WorkerTransport {
+	const sshBinary = opts?.sshBinary ?? "ssh";
+	const identity: RunNodeIdentity = { id: node.id, kind: "ssh", host: node.host };
+	return {
+		kind: "ssh",
+		node: identity,
+		spawn(spec, spawnOpts) {
+			const cwd = spawnOpts?.cwd ?? process.cwd();
+			const remote: { pid: number | null; processGroupId: number | null } = { pid: null, processGroupId: null };
+			const killRemote = (): void => {
+				// The negative pid targets the whole remote process group, so a
+				// runtime's own children go with it. Without an announced group the
+				// single pid is the most the orchestrator can prove it may signal.
+				const group = remote.processGroupId;
+				const command =
+					group !== null
+						? `kill -TERM -${group} 2>/dev/null || kill -TERM ${remote.pid ?? group} 2>/dev/null || true`
+						: remote.pid !== null
+							? `kill -TERM ${remote.pid} 2>/dev/null || true`
+							: null;
+				if (command === null) return;
+				// Best-effort second channel: the primary signal is the channel
+				// close (the worker's parent monitor aborts and exits on stdin
+				// EOF); this covers a worker that stopped reading its stdin.
+				try {
+					const fallback = spawn(sshBinary, buildSshArgs(node, command), {
+						stdio: "ignore",
+						detached: true,
+					});
+					fallback.unref();
+				} catch {
+					// the channel-close path remains the primary termination signal
+				}
+			};
+			// The remote command cds itself, so cwd is consumed here and never
+			// applied to the local ssh client. The announce and forced-kill hooks
+			// are the transport's own and compose with the caller's rather than
+			// replacing them; every other option is forwarded as handed.
+			const { cwd: _consumedCwd, onAnnounce, onForcedKill, ...forwarded } = spawnOpts ?? {};
+			return spawnWorkerProcess(sshBinary, buildSshArgs(node, buildRemoteWorkerCommand(node, cwd)), spec, {
+				...(opts?.shutdownGraceMs !== undefined ? { shutdownGraceMs: opts.shutdownGraceMs } : {}),
+				...forwarded,
+				env: process.env,
+				onAnnounce: (attestation) => {
+					remote.pid = attestation.pid;
+					remote.processGroupId = attestation.processGroupId;
+					onAnnounce?.(attestation);
+				},
+				onForcedKill: () => {
+					killRemote();
+					onForcedKill?.();
+				},
+			});
+		},
+	};
+}