@gavin-hu/my-pi-agent 0.20.0 → 0.22.0

package/extensions/job/runtime.ts

@@ -1,138 +1,67 @@
 /**
- * Job runtime: the session-scoped job table and process lifecycle.
+ * Job runtime: the session-scoped job table and the durable record.
  *
- * Owns the in-memory `Job` map, live child handles, callbacks, and the repaint
- * clock, and composes the smaller pieces: `store.ts` (durable registry),
- * `logs.ts` (log tails), `log-writer.ts` (the per-job stream, line split, and
- * rotation), `status.ts` (exit-status recovery), `ui.ts` (status chips), and
- * `waiters.ts`.
+ * Owns the in-memory `Job` map and its transitions, and composes the smaller
+ * pieces: `child.ts` (a job's process and its output), `clock.ts` (the repaint
+ * clock and the reattached-job sweep), `store.ts` (the durable registry),
+ * `ui.ts` (status chips), and `waiters.ts`.
  *
  * Registry model: each session is the sole writer of its own
  * `registry-<hash>.json`. `load` merges every session's file and adopts the
  * records of dead peer sessions (so a detached server reattaches and a crashed
- * session's history survives) before reconciling pids. The process/spawn/clock
- * functions are injectable so the whole runtime can be driven by a fake child in
- * tests.
+ * session's history survives) before reconciling pids. The process seams are
+ * injectable so the whole runtime can be driven by a fake child in tests.
  *
  * Concurrency: the runtime assumes the tool is `executionMode: "sequential"`,
  * but job completion is asynchronous, so `finalize` is guarded against running
  * twice and listeners/waiters are removed on cleanup.
  */
 
-import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { KILL_GRACE_MS } from "../../lib/child.ts";
+import { abortableSleep } from "../../lib/timer.ts";
 import { resolveEffectiveCwd } from "../../lib/env.ts";
+import type { KillTreeFn, SpawnFn } from "../../lib/spawn.ts";
+import { createJobChildren, type JobSeams } from "./child.ts";
+import { createExternalSweep, createRepaintClock } from "./clock.ts";
+import { DEFAULT_CONFIG, loadConfig, type JobsConfig } from "./config.ts";
+import { compareJobs } from "./format.ts";
 import {
-	defaultKillTree,
-	defaultSpawn,
-	isPidAlive,
-	type KillTreeFn,
-	type SpawnedProcess,
-	type SpawnFn,
-	startTokenOf,
-	type StdinSink,
-} from "../../lib/spawn.ts";
-import { loadConfig, type JobsConfig } from "./config.ts";
-import { createLogWriter, type LogHandle } from "./log-writer.ts";
-import { sanitizeUntrustedLine } from "../../lib/format.ts";
-import { defaultInterval } from "../../lib/timer.ts";
-import { clipLabel } from "../../lib/tui/columns.ts";
-import { compareJobs, formatLogs } from "./format.ts";
-import { readLogTail } from "./logs.ts";
-import {
+	loadRecords,
 	loadRegistries,
-	mergeRecords,
-	planReconcile,
 	registryDirFor,
 	removeLegacyRegistry,
 	removeRegistry,
 	settleGone,
 } from "./registry.ts";
+import { createOwnership, removeSessionMarker } from "./session.ts";
 import {
-	isSessionAlive,
-	pruneSessionMarkers,
-	readSessionMarker,
-	removeSessionMarker,
-	touchSessionMarker,
-} from "./session.ts";
-import { LOG_ENV, STATUS_ENV, readExitStatus, withExitTrap } from "./status.ts";
-import { type Job, type JobRecord, type JobStatus, type KillSignal } from "./types.ts";
+	type Job,
+	type JobRecord,
+	type JobStatus,
+	type KillSignal,
+	type LogResult,
+	type SendOptions,
+	type SendResult,
+	type StartOptions,
+	type WaitResult,
+} from "./types.ts";
 import { createUiController } from "./ui.ts";
-import { createJobStore, toRecord } from "./store.ts";
-import { createWaiters } from "./waiters.ts";
-
-/** Characters of sanitized log sent to the model. */
-const LOG_MODEL_CHARS = 16 * 1024;
-/** Default `wait` timeout. */
-const DEFAULT_WAIT_MS = 30_000;
-
-export interface StartOptions {
-	command: string;
-	cwd?: string;
-	label?: string;
-	wake?: boolean;
-	detached?: boolean;
-	/** Give the child a stdin pipe, so `send` can write to it while it runs here. */
-	stdin?: boolean;
-	/** Auto-kill the job after this many milliseconds (SIGTERM, escalating to SIGKILL). */
-	timeoutMs?: number;
-}
-
-export interface LogResult {
-	job: Job;
-	/** Model-facing render of the tail, including status header/truncation note. */
-	text: string;
-	/** Sanitized tail lines, for the `/jobs` log pane. */
-	lines: string[];
-	truncated: boolean;
-	/** True when earlier log lines exist beyond the returned window. */
-	more: boolean;
-}
-
-export interface WaitResult {
-	job: Job;
-	timedOut: boolean;
-	cancelled: boolean;
-}
-
-export interface SendOptions {
-	/** Text written to the job's stdin. */
-	input?: string;
-	/** Append a newline to `input`; defaults to true. */
-	newline?: boolean;
-	/** End the job's stdin after writing, so the child sees EOF. */
-	eof?: boolean;
-}
-
-export interface SendResult {
-	job: Job;
-	/** Characters of `input` written, excluding any newline this call added. */
-	sent: number;
-	/** True when this call ended the job's stdin. */
-	closed: boolean;
-}
+import { createJobStore, type JobStore, toRecord } from "./store.ts";
+import { createWaiters, waitFor } from "./waiters.ts";
 
 export interface RuntimeOptions {
 	spawn?: SpawnFn;
-	liveness?: typeof isPidAlive;
+	liveness?: (pid: number) => boolean;
 	killTree?: KillTreeFn;
-	startToken?: typeof startTokenOf;
+	startToken?: (pid: number) => string | undefined;
 	now?: () => number;
 	/** Platform seam: whether this is Windows. Defaults to the running platform. */
 	isWindows?: () => boolean;
 	/** Fixed config, for tests; production loads it per cwd. */
 	config?: JobsConfig;
-}
-
-interface Handle {
-	/** The job's log: stream, line split, rotation, and the repaint window. */
-	log: LogHandle;
-	killTimer?: ReturnType<typeof setTimeout>;
-	timeoutTimer?: ReturnType<typeof setTimeout>;
-	/** The child's stdin pipe, present only for a job started with `stdin: true`. */
-	stdin?: StdinSink | null;
-	/** True once stdin was ended, or the child closed its end. */
-	stdinClosed?: boolean;
+	/** How long to wait before a shutdown's SIGKILL; the grace, injectable so a test need not sleep. */
+	sleep?: (ms: number) => Promise<void>;
 }
 
 export interface JobsRuntime {
@@ -142,8 +71,8 @@ export interface JobsRuntime {
 	/** Effective working directory, honoring an active worktree root. */
 	effectiveCwd(ctx: ExtensionContext): string;
 	/** Load and reconcile the registry, then paint the UI. */
-	load(ctx: ExtensionContext): void;
-	start(options: StartOptions, ctx: ExtensionContext): Job;
+	load(ctx: ExtensionContext): Promise<void>;
+	start(options: StartOptions, ctx: ExtensionContext): Promise<Job>;
 	list(): JobRecord[];
 	get(id: string): Job | undefined;
 	logs(id: string, lines?: number): LogResult | undefined;
@@ -152,7 +81,7 @@ export interface JobsRuntime {
 	 * gone, was started without `stdin: true`, or belongs to another session.
 	 */
 	send(id: string, options: SendOptions): SendResult;
-	kill(id: string, signal?: KillSignal): Job | undefined;
+	kill(id: string, signal?: KillSignal): Promise<Job | undefined>;
 	wait(
 		id: string,
 		timeoutMs: number | undefined,
@@ -170,31 +99,60 @@ export interface JobsRuntime {
 	/** Kill session-owned jobs (unless detached), stop the clock, persist. */
 	shutdown(): Promise<void>;
 	/** Called when a `wake` job finishes; the index triggers one turn. */
-	onFinish?: (job: Job) => void;
+	onFinish?: (job: JobRecord) => void;
 	/**
-	 * Called when any job reaches a terminal state, whether it was watched to
-	 * completion or observed gone on the clock. The index bridges it to the event
-	 * bus; the runtime itself never reaches for a listener.
+	 * Called when any job reaches a terminal state, however it settled. The index bridges
+	 * it to the event bus; the runtime itself never reaches for a listener.
 	 */
 	onComplete?: (job: JobRecord) => void;
 }
 
 export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
-	const spawn = options.spawn ?? defaultSpawn;
-	const liveness = options.liveness ?? isPidAlive;
-	const killTree = options.killTree ?? defaultKillTree;
-	const startToken = options.startToken ?? startTokenOf;
+	/**
+	 * The process seam, loaded when a session first loads the registry.
+	 *
+	 * Building the runtime is registration: it happens on every Pi start, and
+	 * `lib/spawn.ts` pulls `node:child_process` with it. The load itself has to answer
+	 * whether recorded pids are alive, so the seam arrives with the first `load`
+	 * rather than with the factory — and a runtime whose pids are all its own never
+	 * needs the platform's default at all.
+	 */
+	let seams: Promise<JobSeams> | undefined;
+	const jobSeams = (): Promise<JobSeams> => {
+		seams ??= Promise.all([import("../../lib/spawn.ts"), import("../../lib/lines.ts")]).then(([spawn, lines]) => ({
+			spawn: options.spawn ?? spawn.defaultSpawn,
+			liveness: options.liveness ?? spawn.isPidAlive,
+			killTree: options.killTree ?? spawn.defaultKillTree,
+			startToken: options.startToken ?? spawn.startTokenOf,
+			newSplitter: () => new lines.LineSplitter(),
+		}));
+		return seams;
+	};
+	/** The seam once it has loaded; every path that asks about a pid has awaited it. */
+	let syncSeams: JobSeams | undefined;
+
+	/** Load the seam when it is not here yet, so a pid question can be asked. */
+	const openSeam = async (): Promise<void> => {
+		syncSeams ??= await jobSeams();
+	};
+
 	const now = options.now ?? (() => Date.now());
+	const sleep = options.sleep ?? abortableSleep;
 	const isWindows = options.isWindows ?? (() => process.platform === "win32");
 
+	// The config is read by `load`, once the session has a cwd; until then the shipped
+	// defaults answer, and a test's fixed config overrides both.
+	let config: JobsConfig = options.config ?? DEFAULT_CONFIG;
+	let jobStore: JobStore | undefined;
+	const store = (): JobStore => {
+		jobStore ??= createJobStore();
+		return jobStore;
+	};
+
 	const jobs = new Map<string, Job>();
-	const handles = new Map<string, Handle>();
 	const waiters = createWaiters();
-	const store = createJobStore();
-	let config: JobsConfig = options.config ?? loadConfig(process.cwd());
 	let sessionId = "session";
 	let disposed = false;
-	let clock: (() => void) | undefined;
 
 	/** Jobs this session owns (a dead session's adopted records included). */
 	const ownJobs = (): Job[] => [...jobs.values()].filter((job) => job.sessionId === sessionId);
@@ -204,114 +162,78 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 
 	const effectiveCwd = (ctx: ExtensionContext): string => resolveEffectiveCwd(ctx.cwd);
 
-	const persist = (): void => store.persist(jobs.values());
+	const persist = (): void => store().persist(jobs.values());
 
-	/** Delete a job's log file, best-effort. */
-	const removeLog = (job: JobRecord): void => {
-		try {
-			const path = store.safeLogPath(job);
-			if (path && existsSync(path)) unlinkSync(path);
-			// Both segments are the job's own log; drop the rotated one too.
-			const rotated = store.safeRotatedLogPath(job);
-			if (rotated && existsSync(rotated)) unlinkSync(rotated);
-		} catch {
-			// Log cleanup is best-effort.
-		}
+	/** A fresh line splitter for one job's log, loaded with the seam that starts it. */
+	const newSplitter = (): ReturnType<JobSeams["newSplitter"]> => {
+		if (syncSeams === undefined) throw new Error("the job process seam is not loaded yet.");
+		return syncSeams.newSplitter();
 	};
 
-	/** Delete a job's status file once its code has been observed, best-effort. */
-	const removeStatus = (job: JobRecord): void => {
-		try {
-			const path = store.safeStatusPath(job);
-			if (path && existsSync(path)) unlinkSync(path);
-		} catch {
-			// Status cleanup is best-effort.
-		}
-	};
+	/** The process seam once it has loaded; a pid question before then answers as it always did. */
+	const jobSeam = (): JobSeams | undefined => syncSeams;
 
-	/** Remove every durable artifact a job leaves behind. */
-	const removeArtifacts = (job: JobRecord): void => {
-		store.releaseId(job.id);
-		removeStatus(job);
-		removeLog(job);
-	};
-
-	/** Refresh this session's liveness marker while it runs jobs. */
-	const touchMarker = (): void => {
-		if (disposed) return;
-		touchSessionMarker(store.directory(), sessionId, process.pid, now());
-	};
-
-	/** Whether the session that owns a job is still alive. */
-	const ownerAlive = (owner: string): boolean =>
-		owner === sessionId ||
-		isSessionAlive(readSessionMarker(store.directory(), owner), now(), config.sessionTtlMs, liveness);
+	/** The listeners the index arms on session start; `undefined` after shutdown. */
+	let onCompleteHandler: ((job: JobRecord) => void) | undefined;
+	let onFinishHandler: ((job: JobRecord) => void) | undefined;
 
-	const stopClock = (): void => {
-		clock?.();
-		clock = undefined;
-	};
+	/** Settled before its listener was armed — a load finishes first — and replayed by it. */
+	let heldCompletions: JobRecord[] = [];
+	let heldWakes: JobRecord[] = [];
 
-	const ensureClock = (): void => {
-		const running = [...jobs.values()].some((job) => job.status === "running");
-		if (disposed || !running) {
-			stopClock();
+	/** Publish a terminal transition unless the runtime is shutting down or was reloaded. */
+	const announceComplete = (job: JobRecord): void => {
+		if (disposed) return;
+		if (onCompleteHandler === undefined) {
+			heldCompletions.push(toRecord(job));
 			return;
 		}
-		if (clock) return;
-		clock = defaultInterval(config.repaintMs, () => {
-			touchMarker();
-			pollExternal();
-			// Re-assert the chip every tick. It is otherwise only set on a job
-			// transition, so anything that clears extension statuses (a session reload,
-			// another UI path) would hide a still-running job's chip until the next
-			// transition. The clock is the only periodic hook while jobs run.
-			ui.setStatus();
-		});
+		try {
+			onCompleteHandler(toRecord(job));
+		} catch {
+			// A completion listener must not break the process bookkeeping.
+		}
 	};
 
-	const paint = (): void => {
-		ensureClock();
-		touchMarker();
-		if (disposed) return;
-		ui.paint();
+	/** Fire the one wake turn a finished `wake` job asked for, or hold it until one is armed. */
+	const wakeIfNeeded = (job: JobRecord): void => {
+		if (!job.wake || disposed) return;
+		if (onFinishHandler === undefined) {
+			heldWakes.push(toRecord(job));
+			return;
+		}
+		try {
+			onFinishHandler(job);
+		} catch {
+			// Wake is best-effort.
+		}
 	};
 
 	/**
-	 * Whether a persisted start-time token still matches the live pid.
-	 * Returns true when either side is unavailable, so callers fall back to
-	 * liveness alone; a mismatch means the pid was reused and must not be signalled.
+	 * Announce one terminal transition: the completion, then the wake turn it asked for. Every
+	 * way a record settles ends here — a close event, a pid observed gone, a peer's leftover
+	 * reaped, an orphan killed at load — so no path announces half the pair.
 	 */
-	const tokenMatches = (job: JobRecord): boolean => {
-		if (!job.startToken || job.pid === null) return true;
-		const current = startToken(job.pid);
-		return !current || current === job.startToken;
-	};
-
-	/** Recover an exit code from a job's status file, guarded by the trusted path. */
-	const exitCodeFor = (job: JobRecord): number | undefined => readExitStatus(store.safeStatusPath(job));
-
-	/** A completion listener, published from the index; `undefined` after shutdown. */
-	let onCompleteHandler: ((job: JobRecord) => void) | undefined;
-
-	/** Publish a terminal transition unless the runtime is shutting down or was reloaded. */
-	const announceComplete = (job: Job): void => {
-		if (disposed) return;
-		try {
-			onCompleteHandler?.(toRecord(job));
-		} catch {
-			// A completion listener must not break the process bookkeeping.
-		}
+	const publishSettled = (job: JobRecord): void => {
+		announceComplete(job);
+		wakeIfNeeded(job);
 	};
 
 	/** Move a record to a settled status, resolving any waiters and announcing it. */
-	const settle = (job: Job, patch: { status: JobStatus; exitCode?: number | null; signal?: string | null }): void => {
+	const settle = (
+		job: JobRecord,
+		patch: { status: JobStatus; exitCode?: number | null; signal?: string | null },
+	): void => {
+		// A record this session settles is this session's now: the only peer record the
+		// table settles is one whose owner is gone, and until it is adopted its completion
+		// is reportable by nobody.
+		job.sessionId = sessionId;
 		job.status = patch.status;
 		job.exitCode = patch.exitCode ?? null;
 		job.signal = patch.signal ?? null;
 		job.finishedAt = now();
 		waiters.resolve(job.id);
-		announceComplete(job);
+		publishSettled(job);
 	};
 
 	/**
@@ -322,54 +244,20 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 	 * every clock tick would be a notification storm.
 	 */
 	const settleGoneJob = (job: Job): boolean => {
-		Object.assign(job, settleGone(job, { isAlive: liveness, tokenMatches, readExitCode: exitCodeFor, now: now() }));
+		Object.assign(
+			job,
+			settleGone(job, {
+				isAlive: children.alive,
+				tokenMatches: children.owns,
+				readExitCode: children.exitCode,
+				now: now(),
+			}),
+		);
 		if (job.status === "running") return false;
-		announceComplete(job);
+		publishSettled(job);
 		return true;
 	};
 
-	/** Poll reattached (unowned) jobs, which have no `close` event to observe. */
-	const pollExternal = (): void => {
-		touchMarker();
-		let changed = false;
-		for (const job of jobs.values()) {
-			if (job.status !== "running" || job.owned) continue;
-			const peer = job.sessionId !== sessionId;
-			const alive = peer ? ownerAlive(job.sessionId) : true;
-			// A live peer session owns this job; leave its state to that owner.
-			if (peer && alive) continue;
-			if (job.pid === null || !liveness(job.pid)) {
-				// A record with no pid cannot be judged gone; leave it alone rather than
-				// announcing (and waking) on every tick.
-				if (!settleGoneJob(job)) continue;
-				// A reattached `wake` job has no `close` event, so this is the only place
-				// its completion can trigger the one wake turn.
-				wakeIfNeeded(job);
-				changed = true;
-				continue;
-			}
-			// The owner is gone and the job is not detached: reap the abandoned
-			// process, guarding against pid reuse with the start token.
-			if (peer && !job.detached) {
-				if (tokenMatches(job)) {
-					try {
-						killTree(job.pid, "SIGTERM");
-					} catch {
-						// Already gone.
-					}
-					settle(job, { status: "killed", signal: "SIGTERM" });
-				} else {
-					settle(job, { status: "unknown" });
-				}
-				changed = true;
-			}
-		}
-		if (!changed) return;
-		pruneFinished();
-		persist();
-		if (!disposed) ui.paint();
-	};
-
 	const pruneFinished = (): void => {
 		// Only this session's records are ours to drop; a live peer manages its own.
 		// Prefer dropping already-reported jobs; an unseen completion is only pruned
@@ -382,97 +270,111 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 			const job = finished.shift();
 			if (!job) break;
 			jobs.delete(job.id);
-			removeArtifacts(job);
-		}
-	};
-
-	/** Remember the newest non-empty output line, which `status`/`wait` report. */
-	const recordLine = (job: Job, line: string): void => {
-		const clean = sanitizeUntrustedLine(line);
-		if (clean) job.lastLine = clean;
-	};
-
-	/** The per-job log sink: stream, line split, rotation, and the repaint window. */
-	const logWriter = createLogWriter({
-		now,
-		logPath: (job) => store.safeLogPath(job),
-		rotatedPath: (job) => store.safeRotatedLogPath(job),
-		maxBytes: () => config.maxLogBytes,
-		repaintMs: () => config.repaintMs,
-		onLine: recordLine,
-		onPaint: paint,
-	});
-
-	/** Clear a handle's timers, close its log stream, and drop it. */
-	const disposeHandle = (id: string, options: { endStream: boolean }): void => {
-		const handle = handles.get(id);
-		if (!handle) return;
-		if (handle.killTimer) clearTimeout(handle.killTimer);
-		if (handle.timeoutTimer) clearTimeout(handle.timeoutTimer);
-		logWriter.dispose(handle.log, options);
-		// Release the stdin pipe so a child waiting on input sees EOF instead of a
-		// half-open pipe nobody can write to.
-		if (handle.stdin && !handle.stdinClosed) {
-			try {
-				handle.stdin.end();
-			} catch {
-				// Already closed.
-			}
+			children.removeArtifacts(job);
 		}
-		handle.stdin = null;
-		handle.stdinClosed = true;
-		handles.delete(id);
-	};
-
-	const onChunk = (id: string, chunk: Buffer): void => {
-		const handle = handles.get(id);
-		const job = jobs.get(id);
-		if (!handle || !job) return;
-		logWriter.write(handle.log, job, chunk);
 	};
 
 	const finalize = (id: string, code: number | null, signal: string | null): void => {
-		const handle = handles.get(id);
 		const job = jobs.get(id);
-		if (!handle || !job || job.status !== "running") return;
-		// Commit any buffered output, including a final line without a newline.
-		for (const line of logWriter.flush(handle.log)) recordLine(job, line);
-		// A detached job keeps no parent stream; read its last line from the log.
-		if (!handle.log.stream) {
-			const last = readLogTail(store.safeLogPath(job), 1).lines.at(-1);
-			if (last) job.lastLine = last;
-		}
-		disposeHandle(id, { endStream: true });
+		if (!children.get(id) || !job || job.status !== "running") return;
+		// Commit the child's buffered output, then let its handle go.
+		children.flush(job);
+		children.dispose(id, { endStream: true });
 
 		const status: JobStatus = signal ? "killed" : code === 0 ? "exited" : "failed";
 		settle(job, { status, exitCode: signal ? null : code, signal });
 		// The close event already carried the code, so the status file is redundant.
-		removeStatus(job);
+		children.removeStatus(job);
 
 		pruneFinished();
 		persist();
-		paint();
+		clock.paint();
 		if (!disposed && status === "failed") ui.notifyFailure(job);
-		if (job.wake && !disposed) {
-			try {
-				onFinishHandler?.(job);
-			} catch {
-				// Wake is best-effort.
-			}
-		}
 	};
 
-	let onFinishHandler: ((job: Job) => void) | undefined;
+	/**
+	 * A job's process and its output, over `lib/child.ts`'s supervisor.
+	 *
+	 * The record's questions — is this pid still ours, what did it exit with, what
+	 * does this log say — stay in this module; the handle, the log stream, stdin and
+	 * the escalation are the child's.
+	 */
+	const children = createJobChildren({
+		seams: jobSeam,
+		store,
+		config: () => config,
+		now,
+		newSplitter,
+		table: {
+			record: (id) => jobs.get(id),
+			ids: () => jobs.keys(),
+			insert: (job) => jobs.set(job.id, job),
+			settle,
+			sessionId: () => sessionId,
+			changed: () => {
+				persist();
+				clock.paint();
+			},
+		},
+		onSettled: (id, outcome) => {
+			if (outcome.kind === "closed") finalize(id, outcome.code, outcome.signal);
+			else finalize(id, 1, null);
+		},
+		onPaint: () => clock.paint(),
+	});
 
-	/** Fire the one wake turn for an unowned `wake` job that just finished. */
-	const wakeIfNeeded = (job: Job): void => {
-		if (!job.wake || disposed) return;
-		try {
-			onFinishHandler?.(job);
-		} catch {
-			// Wake is best-effort.
-		}
-	};
+	/**
+	 * Who owns a job: `live`, `quiet`, or `gone`, and this session's own marker. `quiet` is
+	 * not dead — the heartbeat only ticks while a job runs, so a peer that has finished its
+	 * work stops writing one, and reading that as death adopted a live session's records.
+	 */
+	const ownership = createOwnership({
+		directory: () => store().directory(),
+		sessionId: () => sessionId,
+		now,
+		ttlMs: () => config.sessionTtlMs,
+		alive: (pid) => children.alive(pid),
+		startToken: (pid) => children.startToken(pid),
+	});
+
+	/** Poll the jobs this session reattached, which have no `close` event to observe. */
+	const pollExternal = createExternalSweep({
+		records: () => jobs.values(),
+		sessionId: () => sessionId,
+		ownerPresent: (owner) => ownership.state(owner) !== "gone",
+		alive: (pid) => children.alive(pid),
+		owns: (job) => children.owns(job),
+		settleGone: settleGoneJob,
+		settle,
+		signal: (pid) => children.signal({ pid }, "SIGTERM"),
+		touchMarker: () => ownership.touch(),
+		changed: () => {
+			pruneFinished();
+			persist();
+			if (!disposed) ui.paint();
+		},
+	});
+
+	/**
+	 * The repaint clock: the only periodic hook the runtime arms.
+	 *
+	 * Its tick touches this session's liveness marker, polls the jobs it
+	 * reattached, and re-asserts the chip — which is otherwise only set on a job
+	 * transition, so anything that clears extension statuses (a session reload,
+	 * another UI path) would hide a still-running job's chip.
+	 */
+	const clock = createRepaintClock({
+		repaintMs: () => config.repaintMs,
+		running: () => [...jobs.values()].some((job) => job.status === "running"),
+		disposed: () => disposed,
+		touchMarker: () => ownership.touch(),
+		tick: () => {
+			ownership.touch();
+			pollExternal();
+			ui.setStatus();
+		},
+		repaint: () => ui.paint(),
+	});
 
 	const runtime: JobsRuntime = {
 		get config() {
@@ -486,9 +388,9 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 		start,
 		list: () => [...jobs.values()].sort(compareJobs).map(toRecord),
 		get: (id) => jobs.get(id),
-		logs,
-		send,
-		kill,
+		logs: (id, lines) => children.logs(id, lines),
+		send: (id, options) => children.send(id, options),
+		kill: (id, signal) => children.kill(id, signal),
 		wait,
 		clear,
 		pendingCompletions,
@@ -499,23 +401,39 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 		get onFinish() {
 			return onFinishHandler;
 		},
-		set onFinish(handler: ((job: Job) => void) | undefined) {
+		// A load settles its orphans before `session_start` arms this listener, so what it
+		// owed is replayed here rather than announced into nothing.
+		set onFinish(handler: ((job: JobRecord) => void) | undefined) {
 			onFinishHandler = handler;
+			if (handler === undefined) return;
+			const held = heldWakes;
+			heldWakes = [];
+			for (const job of held) wakeIfNeeded(job);
 		},
 		get onComplete() {
 			return onCompleteHandler;
 		},
 		set onComplete(handler: ((job: JobRecord) => void) | undefined) {
 			onCompleteHandler = handler;
+			if (handler === undefined) return;
+			const held = heldCompletions;
+			heldCompletions = [];
+			for (const job of held) announceComplete(job);
 		},
 	};
 
-	function load(ctx: ExtensionContext): void {
+	async function load(ctx: ExtensionContext): Promise<void> {
+		// The seam comes with the first load: this is the first path that asks whether a
+		// recorded pid is still alive, and the only one that needs `child_process`.
+		await openSeam();
 		// A reload or session replacement can reuse this runtime after `shutdown`,
 		// so reset all session state before re-reading the registry.
 		disposed = false;
-		stopClock();
-		for (const id of [...handles.keys()]) disposeHandle(id, { endStream: true });
+		// Anything the last session settled unannounced belongs to its table, not this one.
+		heldCompletions = [];
+		heldWakes = [];
+		clock.stop();
+		children.disposeAll();
 		waiters.resolveAll();
 
 		// The durable registry is keyed by the session's own cwd, not the active
@@ -523,319 +441,59 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 		// out from under the records already collected here. Jobs still run in the
 		// effective root (`start` uses `effectiveCwd`).
 		config = options.config ?? loadConfig(ctx.cwd);
-		store.setDirectory(registryDirFor(ctx.cwd, config.registryDir));
+		store().setDirectory(registryDirFor(ctx.cwd, config.registryDir));
 		sessionId = ctx.sessionManager.getSessionId();
-		store.setSession(sessionId);
+		store().setSession(sessionId);
 		ui.attach(ctx);
 
 		// Announce this session, and drop markers for sessions that are gone.
-		touchMarker();
-		pruneSessionMarkers(store.directory(), now(), config.sessionTtlMs, liveness);
-
-		const { files, counter } = loadRegistries(store.directory());
-		store.setCounter(counter);
-
-		// Merge every session's records. A file whose owner is gone is adopted: its
-		// records will be rewritten under this session and its file deleted.
-		const merged = new Map<string, JobRecord>();
-		const deadSessions = new Set<string>();
-		for (const file of files) {
-			if (file.sessionId !== sessionId && !ownerAlive(file.sessionId)) deadSessions.add(file.sessionId);
-			for (const record of file.jobs) {
-				const existing = merged.get(record.id);
-				merged.set(record.id, existing ? mergeRecords(existing, record, sessionId) : record);
-			}
-		}
+		ownership.touch();
+		ownership.prune();
 
-		// Resolve dead pids (recovering exit codes), then classify the survivors.
-		const settled = [...merged.values()].map((record) =>
-			settleGone(record, { isAlive: liveness, tokenMatches, readExitCode: exitCodeFor, now: now() }),
-		);
-		const { jobs: reconciled, orphans } = planReconcile(settled, liveness, now(), {
-			isOwnerAlive: ownerAlive,
-			currentSessionId: sessionId,
+		const { files, counter } = loadRegistries(store().directory());
+		store().setCounter(counter);
+		const loaded = loadRecords(files, {
+			sessionId,
+			ownerState: ownership.state,
+			process: children,
+			now: now(),
 		});
 
-		for (const record of orphans) {
-			if (record.pid !== null) {
-				try {
-					killTree(record.pid, "SIGTERM");
-				} catch {
-					// The process may already be gone.
-				}
-			}
-			record.status = "killed";
-			record.signal = "SIGTERM";
-			record.finishedAt = now();
+		for (const record of loaded.orphans) {
+			if (record.pid !== null) children.signal({ pid: record.pid }, "SIGTERM");
+			// An orphan killed here is a terminal state like any other, so it is settled the
+			// same way — announced, and woken, once `session_start` arms the listeners.
+			settle(record, { status: "killed", signal: "SIGTERM" });
 		}
 
 		jobs.clear();
-		for (const record of reconciled) {
-			const adopted = deadSessions.has(record.sessionId) ? { ...record, sessionId } : record;
+		for (const record of loaded.records) {
+			const adopted = loaded.deadSessions.has(record.sessionId) ? { ...record, sessionId } : record;
 			jobs.set(adopted.id, { ...adopted, owned: false });
 		}
 
-		// The adopted records now live in this session's file; drop the peers' files.
-		for (const dead of deadSessions) removeRegistry(store.directory(), dead);
-		removeLegacyRegistry(store.directory());
+		for (const dead of loaded.deadSessions) removeRegistry(store().directory(), dead);
+		removeLegacyRegistry(store().directory());
 		// Ids now committed to a registry no longer need their reservation.
-		store.pruneReservations(jobs.keys());
+		store().pruneReservations(jobs.keys());
 
 		pruneFinished();
 		persist();
-		paint();
+		clock.paint();
 	}
 
-	function start(startOptions: StartOptions, ctx: ExtensionContext): Job {
+	async function start(startOptions: StartOptions, ctx: ExtensionContext): Promise<Job> {
 		if (!config.enabled) throw new Error("jobs are disabled.");
 		ui.attach(ctx);
-		const wantsStdin = startOptions.stdin === true;
-		// Windows has no process group to leave and no shell `EXIT` trap to record an
-		// exit code, so a job there cannot outlive the session: refusing an explicit
-		// detach is the honest answer, and it happens before any id is reserved.
-		// `detachedByDefault` stays inert instead of failing every start with a config
-		// the user set on another machine; `doctor` names that.
-		const windows = isWindows();
-		if (windows && startOptions.detached === true) {
-			throw new Error(
-				"A detached job cannot outlive the session on Windows: there is no process group to leave " +
-					"and no shell EXIT trap to record its exit code. Start it with `detached: false`, " +
-					"run it under WSL, or move the work into a `subagent`.",
-			);
-		}
-		const detached = windows ? false : (startOptions.detached ?? config.detachedByDefault);
-		// A detached job outlives this process, so a stdin pipe owned by this session
-		// would hand it EOF the moment the session ends; refuse instead of silently
-		// dropping the pipe (or the detach).
-		if (wantsStdin && detached) {
-			throw new Error("a detached job cannot take stdin; start it with `detached: false`.");
-		}
 		const cwd = startOptions.cwd ? startOptions.cwd : effectiveCwd(ctx);
-		// The registry directory must exist before `nextId`, which reserves the id
-		// with an `O_EXCL` lock file inside it.
-		mkdirSync(store.directory(), { recursive: true });
-		// `store.nextId` folds in the on-disk counters and ids from every session,
-		// so a peer that advanced the shared counter cannot hand us a live job's id.
-		const id = store.nextId(jobs.keys());
-		const logPath = store.logPath(id);
-		// Only a POSIX shell has an `EXIT` trap to record a status, and only a detached
-		// job points its own output at the log so it keeps logging after this process
-		// ends (which on Windows is never: `detached` is false there).
-		const statusPath = windows ? null : store.statusPath(id);
-		const detachOutput = detached;
-
-		// Wrap the command so a POSIX shell records its exit status; the path travels
-		// in the environment so the shell never has to quote it.
-		const program = withExitTrap(startOptions.command, windows, detachOutput);
-		const env: NodeJS.ProcessEnv = { ...process.env };
-		if (statusPath) env[STATUS_ENV] = statusPath;
-		if (detachOutput) env[LOG_ENV] = logPath;
-		let process_: SpawnedProcess;
-		try {
-			process_ = spawn(program, { cwd, env, detachOutput, stdin: wantsStdin });
-		} catch (error) {
-			// A failed spawn must not leave the reserved id behind.
-			store.releaseId(id);
-			throw error;
-		}
-		const pid = process_.pid ?? null;
-		if (detachOutput) process_.unref?.();
-		// Create the file eagerly so `logs` works before the first write, then
-		// append through a stream. A detached job's shell writes the file directly.
-		try {
-			writeFileSync(logPath, "", { flag: "a" });
-		} catch {
-			// A missing directory was already handled by mkdirSync above.
-		}
-		const job: Job = {
-			id,
-			label: sanitizeUntrustedLine((startOptions.label ?? "").trim()) || clipLabel(startOptions.command),
-			command: startOptions.command,
-			cwd,
-			pid,
-			status: "running",
-			exitCode: null,
-			signal: null,
-			startedAt: now(),
-			finishedAt: null,
-			logPath,
-			statusPath,
-			detached,
-			wake: startOptions.wake ?? config.wakeOnFinish,
-			stdin: wantsStdin,
-			sessionId,
-			seen: false,
-			lastLine: "",
-			startToken: pid !== null ? (startToken(pid) ?? null) : null,
-			owned: true,
-		};
-
-		const handle: Handle = {
-			log: logWriter.create(detachOutput ? undefined : logPath),
-		};
-		if (wantsStdin) {
-			const sink = process_.stdin ?? null;
-			handle.stdin = sink;
-			handle.stdinClosed = sink === null;
-			// A child that exits can emit `error`/`close` on the pipe; record it so a
-			// later `send` reports the truth instead of throwing an unhandled stream error.
-			const markClosed = (): void => {
-				const current = handles.get(id);
-				if (current) current.stdinClosed = true;
-			};
-			sink?.on("error", markClosed);
-			sink?.on("close", markClosed);
-		}
-		handles.set(id, handle);
-		jobs.set(id, job);
-
-		if (startOptions.timeoutMs !== undefined) {
-			handle.timeoutTimer = setTimeout(() => {
-				if (jobs.get(id)?.status === "running") kill(id, "SIGTERM");
-			}, startOptions.timeoutMs);
-			handle.timeoutTimer.unref?.();
-		}
-
-		process_.stdout?.on("data", (chunk: Buffer) => onChunk(id, chunk));
-		process_.stderr?.on("data", (chunk: Buffer) => onChunk(id, chunk));
-		process_.on("close", (code, signal) => finalize(id, code, signal));
-		process_.on("error", () => finalize(id, 1, null));
-
+		// A start before `load` still needs the seam; load it rather than refusing.
+		await openSeam();
+		const job = children.start(startOptions, { cwd, windows: isWindows() });
 		persist();
-		paint();
-		return job;
-	}
-
-	function logs(id: string, lines = config.maxLogLines): LogResult | undefined {
-		const job = jobs.get(id);
-		if (!job) return undefined;
-		const current = readLogTail(store.safeLogPath(job), lines);
-		let all = current.lines;
-		let more = current.more;
-		let truncated = current.truncated;
-		// Keep `logs` continuous across a rotation: fill the request from the
-		// previous segment when the live one holds fewer lines.
-		if (all.length < lines) {
-			const previous = readLogTail(store.safeRotatedLogPath(job), lines - all.length);
-			if (previous.lines.length > 0) {
-				all = [...previous.lines, ...all];
-				more = more || previous.more;
-				truncated = truncated || previous.truncated;
-			}
-		}
-		const last = all.at(-1);
-		if (last) job.lastLine = last;
-		const formatted = formatLogs(job, all, LOG_MODEL_CHARS);
-		// A rotation that outran its drain drops the oldest queued chunks; say so once
-		// rather than letting the gap look like a program that skipped output.
-		const dropped = handles.get(id)?.log.droppedBytes ?? 0;
-		const text = dropped > 0 ? `${formatted.text}\n… ${dropped} bytes dropped while the log rotated.` : formatted.text;
-		return {
-			job,
-			text,
-			lines: all,
-			truncated: formatted.truncated || truncated,
-			more,
-		};
-	}
-
-	function kill(id: string, signal: KillSignal = "SIGTERM"): Job | undefined {
-		const job = jobs.get(id);
-		if (!job) return undefined;
-		if (job.status !== "running") return job;
-		const pid = job.pid;
-		if (pid === null) {
-			settle(job, { status: "unknown" });
-			persist();
-			paint();
-			return job;
-		}
-
-		// A reattached pid may have been reused; if the start token disagrees, stop
-		// rather than signal an unrelated process.
-		if (!tokenMatches(job)) {
-			settle(job, { status: "unknown" });
-			persist();
-			paint();
-			return job;
-		}
-
-		// Adopt a peer's job so the outcome persists in our file; the peer's stale
-		// file is dropped on a later load.
-		job.sessionId = sessionId;
-
-		try {
-			killTree(pid, signal, signal === "SIGKILL");
-		} catch {
-			// Best-effort; liveness below decides the final state.
-		}
-
-		const handle = handles.get(id);
-		if (handle) {
-			if (signal !== "SIGKILL") {
-				if (handle.killTimer) clearTimeout(handle.killTimer);
-				handle.killTimer = setTimeout(() => {
-					if (jobs.get(id)?.status === "running") {
-						try {
-							killTree(pid, "SIGKILL", true);
-						} catch {
-							// Already gone.
-						}
-					}
-				}, config.killGraceMs);
-				handle.killTimer.unref?.();
-			}
-		} else {
-			// Reattached/external Job: no `close` event will arrive, so reconcile
-			// after the grace period instead of waiting forever.
-			setTimeout(() => {
-				const current = jobs.get(id);
-				if (current?.status !== "running") return;
-				if (!liveness(pid)) {
-					settle(current, { status: "killed", signal });
-				} else {
-					try {
-						killTree(pid, "SIGKILL", true);
-					} catch {
-						// Best-effort.
-					}
-					settle(current, { status: "killed", signal: "SIGKILL" });
-				}
-				persist();
-				paint();
-			}, config.killGraceMs).unref?.();
-		}
+		clock.paint();
 		return job;
 	}
 
-	function send(id: string, options: SendOptions): SendResult {
-		const job = jobs.get(id);
-		if (!job) throw new Error(`no job "${id}".`);
-		if (job.status !== "running") throw new Error(`job ${id} is ${job.status}; stdin is closed.`);
-		if (!job.stdin) throw new Error(`job ${id} was not started with stdin; restart it with \`stdin: true\`.`);
-		const handle = handles.get(id);
-		// A pipe this session opened but that is closed is a different fact from one
-		// that was never ours, so state it first.
-		if (handle?.stdinClosed) throw new Error(`job ${id} closed its stdin.`);
-		if (!handle?.stdin) throw new Error(`job ${id}'s stdin belongs to the session that started it.`);
-
-		const input = options.input ?? "";
-		const payload = input && options.newline !== false ? `${input}\n` : input;
-		try {
-			if (payload) handle.stdin.write(payload);
-			if (options.eof) {
-				handle.stdin.end();
-				handle.stdinClosed = true;
-			}
-		} catch {
-			// The child closed its end; record it so the next `send` says so.
-			handle.stdinClosed = true;
-			handle.stdin = null;
-			throw new Error(`job ${id} closed its stdin.`);
-		}
-		return { job, sent: input.length, closed: options.eof === true };
-	}
-
 	function wait(
 		id: string,
 		timeoutMs: number | undefined,
@@ -848,26 +506,12 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 			return Promise.resolve({ job, timedOut: false, cancelled: false });
 		}
 		onUpdate?.();
-
-		return new Promise<WaitResult>((resolve) => {
-			let settled = false;
-			let remove = (): void => {};
-			const finish = (timedOut: boolean, cancelled: boolean): void => {
-				if (settled) return;
-				settled = true;
-				if (timer) clearTimeout(timer);
-				signal?.removeEventListener("abort", onAbort);
-				remove();
-				resolve({ job: jobs.get(id) ?? job, timedOut, cancelled });
-			};
-			const resolveWaiter = (): void => finish(false, false);
-			const onAbort = (): void => finish(false, true);
-			const timer = setTimeout(() => finish(true, false), timeoutMs ?? DEFAULT_WAIT_MS);
-
-			remove = waiters.add(id, resolveWaiter);
-			if (signal?.aborted) onAbort();
-			else signal?.addEventListener("abort", onAbort, { once: true });
-		});
+		// The record is read again at settle time, so the answer carries the job as it
+		// finished rather than as it was when the wait began.
+		return waitFor(waiters, id, { timeoutMs, signal }).then((outcome) => ({
+			job: jobs.get(id) ?? job,
+			...outcome,
+		}));
 	}
 
 	function clear(id: string | undefined, all: boolean): { cleared: number; refused?: string } {
@@ -880,9 +524,9 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 			}
 			jobs.delete(id);
 			waiters.resolve(id);
-			removeArtifacts(job);
+			children.removeArtifacts(job);
 			persist();
-			paint();
+			clock.paint();
 			return { cleared: 1 };
 		}
 
@@ -893,23 +537,17 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 			if (job.status === "running") {
 				// Without `all`, running jobs are left alone; with `all`, force-remove them.
 				if (!all) continue;
-				if (job.pid !== null) {
-					try {
-						killTree(job.pid, "SIGKILL", true);
-					} catch {
-						// Best-effort.
-					}
-				}
+				if (job.pid !== null) children.signal({ pid: job.pid }, "SIGKILL");
 				// Drop the handle too: the child will not deliver a `close` we want.
-				disposeHandle(job.id, { endStream: true });
+				children.dispose(job.id, { endStream: true });
 			}
 			jobs.delete(job.id);
 			waiters.resolve(job.id);
-			removeArtifacts(job);
+			children.removeArtifacts(job);
 			cleared++;
 		}
 		persist();
-		paint();
+		clock.paint();
 		return { cleared };
 	}
 
@@ -935,21 +573,24 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 
 	async function shutdown(): Promise<void> {
 		disposed = true;
-		stopClock();
+		clock.stop();
 		const running = [...jobs.values()].filter(
 			(job) => job.status === "running" && !job.detached && job.sessionId === sessionId,
 		);
-		for (const job of running) kill(job.id, "SIGTERM");
+		for (const job of running) await children.kill(job.id, "SIGTERM");
 		if (running.length > 0) {
-			await new Promise((resolve) => setTimeout(resolve, Math.min(config.killGraceMs, 2000)));
+			// The grace is the same for every running job, handled or not: a reattached job has
+			// no child to watch, so a close-driven wait would SIGKILL it on the heels of its
+			// SIGTERM. The cap is the shared default, not a second literal.
+			await sleep(Math.min(config.killGraceMs, KILL_GRACE_MS));
 		}
 		for (const job of running) {
-			if (jobs.get(job.id)?.status === "running") kill(job.id, "SIGKILL");
+			if (jobs.get(job.id)?.status === "running") await children.kill(job.id, "SIGKILL");
 		}
-		for (const id of [...handles.keys()]) disposeHandle(id, { endStream: true });
+		children.disposeAll();
 		waiters.resolveAll();
 		persist();
-		removeSessionMarker(store.directory(), sessionId);
+		removeSessionMarker(store().directory(), sessionId);
 		ui.detach();
 	}