omp-multi-harness 0.1.0

package/src/sessions/resume.ts

@@ -0,0 +1,163 @@
+/**
+ * Session continuation policy (T-408). See _spec/08-sessions-and-parallelism.md.
+ *
+ * A pure decision module: no spawning, no registry access, no disk. The caller feeds it the
+ * stored mapping and whether a sibling run is live, and gets back the session argument to
+ * use. `runWithResume` wraps one `ExternalAgent.run` call with the single fresh-session
+ * fallback the spec allows.
+ */
+import type { AgentName, AgentRequest, AgentResult, AgentRunOptions, ExternalAgent } from "../agents/types.ts";
+import { AgentError, looksLikeAuthFailure } from "../process/process-error.ts";
+import { buildHandoff } from "../routing/handoff.ts";
+
+export interface ResumeContext {
+	agent: AgentName;
+	/** `continueSession` from the request. Default true per spec 08. */
+	continueSession?: boolean;
+	/** Worker session id mapped to `(ompSession, cwd)`, from the session store. */
+	storedSessionId?: string;
+	/** True when another run for the SAME agent in the SAME cwd is already live. */
+	siblingActive?: boolean;
+}
+
+export type ResumeReason =
+	/** `continueSession: false` — the caller asked for a clean slate. */
+	| "fresh-requested"
+	/** Nothing mapped for this (OMP session, repo) yet. */
+	| "no-mapping"
+	/** Normal continuation of the mapped worker session. */
+	| "resume"
+	/** Claude: branch off the mapped session so both runs can proceed. */
+	| "forked"
+	/** Codex: no fork flag exists, so the second parallel run starts clean. */
+	| "fresh-parallel";
+
+export interface SessionDecision {
+	/** Put on `AgentRequest.sessionId`. Undefined means "start a fresh worker session". */
+	sessionId?: string;
+	/**
+	 * Claude only: pass as `fork` to `buildClaudeArgs` so argv gets `--fork-session`.
+	 * `ExternalAgent.run` has no fork field, so the wiring layer must forward this.
+	 */
+	fork: boolean;
+	reason: ResumeReason;
+	/** Merged into `AgentResult.metadata` by `runWithResume`. */
+	metadata: { forked?: true };
+}
+
+/**
+ * Decide the session argument for a run. Two parallel runs on the same agent in the same
+ * cwd must never resume the same worker session — the second forks (Claude) or starts
+ * fresh (Codex), and either way is marked `forked`.
+ */
+export function decideSession(ctx: ResumeContext): SessionDecision {
+	if (ctx.continueSession === false) return { fork: false, reason: "fresh-requested", metadata: {} };
+	if (!ctx.storedSessionId) return { fork: false, reason: "no-mapping", metadata: {} };
+	if (ctx.siblingActive) {
+		return ctx.agent === "claude"
+			? { sessionId: ctx.storedSessionId, fork: true, reason: "forked", metadata: { forked: true } }
+			: { fork: false, reason: "fresh-parallel", metadata: { forked: true } };
+	}
+	return { sessionId: ctx.storedSessionId, fork: false, reason: "resume", metadata: {} };
+}
+
+/** Failures that mean "that worker session is gone", not "the task failed". */
+const RESUME_FAILURE_PATTERNS = [
+	/session (id )?[^\s]* ?(was )?not found/i,
+	/no (such )?session/i,
+	/no (session|conversation|thread) found/i,
+	/unknown session/i,
+	/session .*(does not|doesn't) exist/i,
+	/could not (find|resume|load) (the )?(session|conversation|thread)/i,
+	/failed to resume/i,
+	/resume(d)? session .*(failed|invalid)/i,
+	/(conversation|thread) .*not found/i,
+	/invalid session id/i,
+];
+
+/** Codes that can never be cured by starting a fresh session — never retry on these. */
+const NEVER_RESUME_FALLBACK = new Set(["AUTH_REQUIRED", "PROVIDER_LIMIT", "EXECUTABLE_NOT_FOUND", "CANCELLED", "TIMEOUT", "AGENT_DISABLED", "INVALID_CWD", "WORKSPACE_BUSY"]);
+
+/**
+ * Classify a failure as "the resume failed" vs. a genuine failure. Deliberately
+ * conservative: only the explicit code, or a process failure whose stderr names a missing
+ * session, qualifies. An auth or provider-limit failure must never trigger a retry.
+ */
+export function isResumeFailure(error: unknown): boolean {
+	if (!(error instanceof AgentError)) return false;
+	if (error.code === "SESSION_RESUME_FAILED") return true;
+	if (NEVER_RESUME_FALLBACK.has(error.code)) return false;
+	if (error.code !== "PROCESS_FAILED" && error.code !== "INVALID_OUTPUT") return false;
+	const text = `${error.stderrTail ?? ""}\n${error.message}`;
+	if (looksLikeAuthFailure(text)) return false;
+	return RESUME_FAILURE_PATTERNS.some((p) => p.test(text));
+}
+
+const FRESH_SESSION_PREAMBLE =
+	"The earlier session for this repository could not be resumed, so this is a fresh session with no prior history. " +
+	"Re-read whatever you need from the repository rather than assuming earlier context.";
+
+/** The note appended to the result so the user knows history was lost. */
+export function resumeFallbackNote(agent: AgentName): string {
+	return `Note: the previous ${agent} session could not be resumed. This ran in a fresh session with a compact handoff instead of full history.`;
+}
+
+/**
+ * Task text for the retry: the compact handoff block, never an emulation of the transcript.
+ */
+export function buildResumeFallbackTask(request: AgentRequest, maxHandoffChars: number): string {
+	const context = [request.context?.trim(), FRESH_SESSION_PREAMBLE].filter(Boolean).join("\n\n");
+	return buildHandoff({ task: request.task, mode: request.mode, context, maxChars: maxHandoffChars });
+}
+
+export interface ResumeDeps {
+	decision: SessionDecision;
+	/** Cap for the handoff carried into the fallback run. Defaults to spec's 4 000. */
+	maxHandoffChars?: number;
+	/**
+	 * Runner override. Needed for Claude, whose `--fork-session` argument is not expressible
+	 * on `AgentRequest`. Defaults to `agent.run`.
+	 */
+	run?: (request: AgentRequest, options: AgentRunOptions) => Promise<AgentResult>;
+	/** Called once with the user-visible note when the fallback fires. */
+	onNote?: (note: string) => void;
+}
+
+/**
+ * Run `agent` with the decided session, falling back to a fresh session **exactly once**
+ * when — and only when — the resume itself failed. The fallback carries the compact
+ * handoff, sets `metadata.resumedFallback`, and appends a visible note to the output.
+ */
+export async function runWithResume(
+	agent: ExternalAgent,
+	request: AgentRequest,
+	options: AgentRunOptions,
+	deps: ResumeDeps,
+): Promise<AgentResult> {
+	const { decision } = deps;
+	const run = deps.run ?? ((req, opts) => agent.run(req, opts));
+	const first: AgentRequest = { ...request, sessionId: decision.sessionId };
+
+	try {
+		return withMetadata(await run(first, options), decision.metadata);
+	} catch (e) {
+		// Only a failed *resume* is recoverable, and only when we actually tried to resume.
+		if (!decision.sessionId || !isResumeFailure(e)) throw e;
+
+		const note = resumeFallbackNote(agent.name);
+		deps.onNote?.(note);
+		const retry: AgentRequest = {
+			...request,
+			sessionId: undefined,
+			context: undefined,
+			task: buildResumeFallbackTask(request, deps.maxHandoffChars ?? 4_000),
+		};
+		const result = withMetadata(await run(retry, options), { ...decision.metadata, resumedFallback: true });
+		return { ...result, output: `${result.output}\n\n${note}` };
+	}
+}
+
+function withMetadata(result: AgentResult, extra: Record<string, unknown>): AgentResult {
+	if (Object.keys(extra).length === 0) return result;
+	return { ...result, metadata: { ...result.metadata, ...extra } };
+}

package/src/sessions/store.ts

@@ -0,0 +1,273 @@
+/**
+ * OMP ↔ worker session mapping (T-407). See _spec/08-sessions-and-parallelism.md.
+ *
+ * One JSON file per `(ompSessionId, realpath(cwd))` pair under the **runtime-resolved**
+ * agent dir, so `continueSession: true` survives an OMP restart. Only ids, the cwd and
+ * timestamps are persisted — never task text, tokens, keys, env or cookies.
+ */
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import type { AgentName } from "../agents/types.ts";
+
+/** A worker session id plus when we last saw it. */
+export interface WorkerSessionRef {
+	sessionId: string;
+	/** ISO 8601. */
+	updatedAt: string;
+}
+
+/** The persisted record. Anything not on this shape must never reach disk. */
+export interface HarnessSession {
+	version: 1;
+	ompSessionId: string;
+	cwd: string;
+	workers: {
+		codex?: WorkerSessionRef;
+		claude?: WorkerSessionRef;
+	};
+}
+
+export interface SessionStoreOptions {
+	/**
+	 * Root to store under, in place of the resolved agent dir. Tests pass a temp dir;
+	 * production leaves it unset so `--profile` / `PI_CODING_AGENT_DIR` are honored.
+	 */
+	baseDir?: string;
+	/** Non-fatal problems (corrupt file, rejected id, unwritable dir) land here. */
+	onWarning?: (message: string) => void;
+}
+
+export interface SessionStore {
+	/** Absolute path of the file backing this key. Resolves the agent dir on first use. */
+	path(ompSessionId: string, cwd: string): Promise<string>;
+	/** The mapping, or undefined when there is none — including when the file is corrupt. */
+	get(ompSessionId: string, cwd: string): Promise<HarnessSession | undefined>;
+	/** Convenience: just the worker session id for one agent. */
+	workerSessionId(ompSessionId: string, cwd: string, agent: AgentName): Promise<string | undefined>;
+	/** Upsert one agent's worker session id. Returns the record as persisted. */
+	record(ompSessionId: string, cwd: string, agent: AgentName, workerSessionId: string): Promise<HarnessSession | undefined>;
+	/** Drop one agent's mapping, or the whole record when `agent` is omitted. */
+	clear(ompSessionId: string, cwd: string, agent?: AgentName): Promise<boolean>;
+}
+
+/** Worker session ids are UUIDs (Claude) or opaque thread ids (Codex) — nothing else. */
+const SESSION_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+/** OMP session ids are opaque; cap them so a hostile id cannot bloat the file. */
+const OMP_SESSION_ID = /^[\x20-\x7e]{1,256}$/;
+
+/** `<agentDir>/multi-harness/sessions`. */
+const SUBDIR = join("multi-harness", "sessions");
+
+let cachedAgentDir: Promise<string> | undefined;
+
+/**
+ * The active agent dir, resolved at runtime so `--profile` and `PI_CODING_AGENT_DIR` are
+ * honored. Prefers OMP's own `getAgentDir` (it knows about profiles); falls back to the env
+ * var, then `~/.omp/agent`. Never hard-code the last one at a call site.
+ */
+export async function resolveAgentDir(): Promise<string> {
+	cachedAgentDir ??= (async () => {
+		// PI_CODING_AGENT_DIR is checked FIRST, before OMP's own resolver, for one concrete
+		// reason: upstream `getAgentDir()` reads the env var once at module load and memoizes
+		// it forever. Set before the process starts (the production case) both orders agree.
+		// Changed afterwards, the upstream value is frozen and no reset seam of ours can undo
+		// it — so consulting the env directly is what makes this resolver actually honor the
+		// variable, rather than only appearing to. Env beats --profile in OMP too, so the
+		// precedence is unchanged; when the var is absent we still defer to OMP for profiles.
+		const fromEnv = process.env.PI_CODING_AGENT_DIR;
+		if (fromEnv && fromEnv.length > 0) return resolve(fromEnv);
+
+		// The coding-agent index is the canonical re-export and is already loaded inside OMP;
+		// `pi-utils/dirs` is the same resolver without pulling the whole agent in, which
+		// matters for tests and scripts where the native addon may be missing.
+		for (const specifier of ["@oh-my-pi/pi-coding-agent", "@oh-my-pi/pi-utils/dirs"]) {
+			try {
+				const mod = (await import(specifier)) as { getAgentDir?: () => string };
+				const dir = mod.getAgentDir?.();
+				if (typeof dir === "string" && dir.length > 0) return dir;
+			} catch {
+				// Not importable here — try the next source.
+			}
+		}
+		return join(homedir(), ".omp", "agent");
+	})();
+	return cachedAgentDir;
+}
+
+/** Test seam: forget the memoized agent dir so a changed env is picked up again. */
+export function resetAgentDirCache(): void {
+	cachedAgentDir = undefined;
+}
+
+/**
+ * Canonical cwd for keying. Symlinked and relative paths must land on the same key as the
+ * real path, or two runs in one repo would get two mappings.
+ */
+export function normalizeCwd(cwd: string): string {
+	const absolute = resolve(cwd);
+	try {
+		return realpathSync(absolute);
+	} catch {
+		// Not on disk (yet) — the resolved path is still a stable key.
+		return absolute;
+	}
+}
+
+/** Stable, non-reversible file name for a key. The id and path never appear in it. */
+export function sessionKey(ompSessionId: string, cwd: string): string {
+	return createHash("sha256").update(`${ompSessionId}\0${normalizeCwd(cwd)}`).digest("hex").slice(0, 32);
+}
+
+/** Only the shape above survives a round trip; anything else is treated as corrupt. */
+function parseSession(raw: unknown): HarnessSession | undefined {
+	if (typeof raw !== "object" || raw === null) return undefined;
+	const value = raw as Record<string, unknown>;
+	if (value.version !== 1) return undefined;
+	if (typeof value.ompSessionId !== "string" || typeof value.cwd !== "string") return undefined;
+	const workers: HarnessSession["workers"] = {};
+	const rawWorkers = typeof value.workers === "object" && value.workers !== null ? (value.workers as Record<string, unknown>) : {};
+	for (const agent of ["codex", "claude"] as const) {
+		const entry = rawWorkers[agent];
+		if (typeof entry !== "object" || entry === null) continue;
+		const { sessionId, updatedAt } = entry as Record<string, unknown>;
+		if (typeof sessionId !== "string" || !SESSION_ID.test(sessionId)) continue;
+		workers[agent] = { sessionId, updatedAt: typeof updatedAt === "string" ? updatedAt : new Date(0).toISOString() };
+	}
+	return { version: 1, ompSessionId: value.ompSessionId, cwd: value.cwd, workers };
+}
+
+/** Write via temp + rename so a crash mid-write can never leave a half file in place. */
+function writeAtomic(file: string, body: string): void {
+	const tmp = `${file}.${process.pid.toString(36)}${Math.random().toString(36).slice(2, 8)}.tmp`;
+	try {
+		writeFileSync(tmp, body, { mode: 0o600 });
+		renameSync(tmp, file);
+		// rename keeps the temp file's mode, but an existing target could predate this code.
+		chmodSync(file, 0o600);
+	} catch (e) {
+		try {
+			rmSync(tmp, { force: true });
+		} catch {
+			// best effort
+		}
+		throw e;
+	}
+}
+
+/**
+ * Create a session store. All methods are async because the agent dir is resolved lazily;
+ * none of them ever throw — I/O problems degrade to "no mapping" plus a warning, because a
+ * missing resume is an inconvenience while a thrown error would kill the run.
+ */
+export function createSessionStore(options: SessionStoreOptions = {}): SessionStore {
+	const warn = options.onWarning ?? (() => {});
+
+	async function dir(): Promise<string> {
+		const base = options.baseDir ?? (await resolveAgentDir());
+		const target = join(base, SUBDIR);
+		mkdirSync(target, { recursive: true, mode: 0o700 });
+		// mkdir's mode is masked by umask and skipped for existing dirs; be explicit.
+		chmodSync(target, 0o700);
+		chmodSync(join(base, "multi-harness"), 0o700);
+		return target;
+	}
+
+	async function path(ompSessionId: string, cwd: string): Promise<string> {
+		return join(await dir(), `${sessionKey(ompSessionId, cwd)}.json`);
+	}
+
+	async function read(ompSessionId: string, cwd: string): Promise<HarnessSession | undefined> {
+		let file: string;
+		try {
+			file = await path(ompSessionId, cwd);
+		} catch (e) {
+			warn(`multi-harness: session store unavailable (${(e as Error).message}) — continuing without session mapping`);
+			return undefined;
+		}
+		let body: string;
+		try {
+			body = readFileSync(file, "utf8");
+		} catch (e) {
+			const code = (e as NodeJS.ErrnoException).code;
+			if (code !== "ENOENT") warn(`multi-harness: could not read ${file} (${code ?? (e as Error).message}) — treating as no mapping`);
+			return undefined;
+		}
+		try {
+			const parsed = parseSession(JSON.parse(body));
+			if (!parsed) {
+				warn(`multi-harness: ${file} is not a v1 session record — treating as no mapping`);
+				return undefined;
+			}
+			return parsed;
+		} catch {
+			warn(`multi-harness: ${file} is corrupt JSON — treating as no mapping`);
+			return undefined;
+		}
+	}
+
+	return {
+		path,
+		get: read,
+
+		async workerSessionId(ompSessionId, cwd, agent) {
+			return (await read(ompSessionId, cwd))?.workers[agent]?.sessionId;
+		},
+
+		async record(ompSessionId, cwd, agent, workerSessionId) {
+			if (!SESSION_ID.test(workerSessionId)) {
+				warn(`multi-harness: refusing to persist a malformed ${agent} session id — not saved`);
+				return undefined;
+			}
+			if (!OMP_SESSION_ID.test(ompSessionId)) {
+				warn("multi-harness: refusing to persist a malformed OMP session id — not saved");
+				return undefined;
+			}
+			const existing = await read(ompSessionId, cwd);
+			// Built field by field on purpose: only ids, cwd and timestamps may reach disk.
+			const next: HarnessSession = {
+				version: 1,
+				ompSessionId,
+				cwd: normalizeCwd(cwd),
+				workers: { ...existing?.workers, [agent]: { sessionId: workerSessionId, updatedAt: new Date().toISOString() } },
+			};
+			try {
+				writeAtomic(await path(ompSessionId, cwd), `${JSON.stringify(next, null, "\t")}\n`);
+			} catch (e) {
+				warn(`multi-harness: could not persist the session mapping (${(e as Error).message}) — resume will not survive a restart`);
+				return undefined;
+			}
+			return next;
+		},
+
+		async clear(ompSessionId, cwd, agent) {
+			let file: string;
+			try {
+				file = await path(ompSessionId, cwd);
+			} catch {
+				return false;
+			}
+			if (agent) {
+				const existing = await read(ompSessionId, cwd);
+				if (!existing?.workers[agent]) return false;
+				const workers = { ...existing.workers };
+				delete workers[agent];
+				try {
+					writeAtomic(file, `${JSON.stringify({ ...existing, workers }, null, "\t")}\n`);
+					return true;
+				} catch (e) {
+					warn(`multi-harness: could not clear the ${agent} session mapping (${(e as Error).message})`);
+					return false;
+				}
+			}
+			try {
+				rmSync(file, { force: true });
+				return true;
+			} catch (e) {
+				warn(`multi-harness: could not remove ${file} (${(e as Error).message})`);
+				return false;
+			}
+		},
+	};
+}

package/src/tools/agent-runs.ts

@@ -0,0 +1,169 @@
+/**
+ * `agent_runs` (T-502) — the supervisor's handle on background work: fan out several runs,
+ * then join them, without the user having to drive `/sessions` (_spec/06-tools.md).
+ *
+ * Every answer is compact, model-readable text. Unknown ids and already-finished cancels are
+ * ordinary results, not errors — the supervisor should be able to poll without exception
+ * handling.
+ */
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import type { MultiHarnessConfig } from "../config/schema.ts";
+import { truncateMiddle } from "../routing/handoff.ts";
+import { isTerminal, type RunRegistry, type RunView } from "../runs/types.ts";
+
+const ACTIONS = ["list", "status", "result", "cancel", "wait"] as const;
+const DEFAULT_WAIT_MS = 60_000;
+
+const DESCRIPTION =
+	"Manage delegated agent runs started with background: true. " +
+	"list = every run in this session with status and elapsed time; status = one run without its output; " +
+	"result = the finished output of one run; cancel = stop a run; wait = block until a run finishes or waitMs elapses. " +
+	"Fan out independent work with background runs, then join it here.";
+
+/** What the schema below accepts — see the cast note in `ask-agent.ts`. */
+interface AgentRunsParams {
+	action: (typeof ACTIONS)[number];
+	runId?: string;
+	waitMs?: number;
+}
+
+function elapsed(view: RunView): string {
+	return `${(view.elapsedMs / 1000).toFixed(1)}s`;
+}
+
+/** One line for `list`: everything needed to decide what to do next, nothing more. */
+export function renderRunLine(view: RunView): string {
+	const bits = [view.id, view.agent];
+	if (view.mode) bits.push(view.mode);
+	bits.push(view.status, elapsed(view));
+	if (!isTerminal(view.status) && view.phase) bits.push(view.phase);
+	return `${bits.join(" · ")} — ${view.summary}`;
+}
+
+/**
+ * Full rendering of one run, with its output truncated from the middle at
+ * `limits.maxOutputChars`. Shared with `delegate` so a foreground call and a joined
+ * background run read identically.
+ */
+export function renderRunView(view: RunView, maxOutputChars: number): { text: string; truncated: boolean } {
+	const header = [view.agent, view.status, elapsed(view)];
+	if (view.mode) header.splice(1, 0, view.mode);
+	if (view.workerSessionId) header.push(`session ${view.workerSessionId.slice(0, 8)}`);
+	if (view.readOnly) header.push("read-only");
+
+	if (view.errorCode) {
+		return { text: `[${header.join(" · ")}]\n${view.errorCode}: ${view.errorMessage ?? "failed"}`, truncated: false };
+	}
+
+	const body = truncateMiddle(view.output ?? "(no output)", maxOutputChars);
+	return { text: `[${header.join(" · ")}]\n${body.text}`, truncated: body.truncated };
+}
+
+export interface AgentRunsDeps {
+	pi: ExtensionAPI;
+	getConfig: () => MultiHarnessConfig;
+	/** Taken as a getter so this module never imports the registry implementation. */
+	getRegistry: () => RunRegistry;
+}
+
+/** Details are free-form state carried back to the supervisor, so one shape for every
+ *  branch keeps the tool's inferred result type uniform. */
+type Details = Record<string, unknown>;
+
+function reply(body: string, details?: Details, isError?: boolean) {
+	return { content: [{ type: "text" as const, text: body }], details, isError };
+}
+const missing = (action: string) => reply(`runId is required for action "${action}".`);
+const unknown = (runId: string) => reply(`No run with id ${runId}. Use action "list" to see current runs.`);
+
+export function registerAgentRunsTool({ pi, getConfig, getRegistry }: AgentRunsDeps): void {
+	const z = pi.zod;
+
+	pi.registerTool({
+		name: "agent_runs",
+		label: "Agent Runs",
+		description: DESCRIPTION,
+		// Read-only over the registry; `cancel` stops a child this extension already owns.
+		approval: "read",
+		parameters: z.object({
+			action: z.enum(ACTIONS).describe("list | status | result | cancel | wait"),
+			runId: z.string().optional().describe("Required for status, result, cancel, and wait."),
+			waitMs: z.number().optional().describe("Cap for action \"wait\". Default 60000."),
+		}),
+		async execute(_toolCallId, rawParams) {
+			const params = rawParams as AgentRunsParams;
+			const config = getConfig();
+			const registry = getRegistry();
+
+			if (params.action === "list") {
+				const runs = registry.list();
+				if (runs.length === 0) return reply("No agent runs in this session.");
+				return reply(runs.map(renderRunLine).join("\n"), { count: runs.length, runIds: runs.map((r) => r.id) });
+			}
+
+			const runId = params.runId?.trim();
+			if (!runId) return missing(params.action);
+
+			if (params.action === "cancel") {
+				const before = registry.get(runId);
+				if (!before) return unknown(runId);
+				// Idempotent by contract: cancelling a terminal run reports, never throws.
+				const cancelled = await registry.cancel(runId);
+				const after = registry.get(runId) ?? before;
+				return reply(
+					cancelled ? `Cancelled ${runId} (${after.agent}).` : `${runId} was already ${after.status}; nothing to cancel.`,
+					{ runId, cancelled, status: after.status },
+				);
+			}
+
+			if (params.action === "wait") {
+				const waitMs = params.waitMs && params.waitMs > 0 ? params.waitMs : DEFAULT_WAIT_MS;
+				const view = await registry.wait(runId, waitMs);
+				if (!view) return unknown(runId);
+				if (!isTerminal(view.status)) {
+					return reply(
+						`${runId} is still ${view.status} after ${(waitMs / 1000).toFixed(0)}s — ${view.phase || "no phase"}. Wait again or check status.`,
+						{ runId, status: view.status, timedOut: true },
+					);
+				}
+				const rendered = renderRunView(view, config.limits.maxOutputChars);
+				return reply(rendered.text, {
+					runId,
+					agent: view.agent,
+					status: view.status,
+					durationMs: view.elapsedMs,
+					truncated: rendered.truncated,
+				});
+			}
+
+			const view = registry.get(runId);
+			if (!view) return unknown(runId);
+
+			if (params.action === "status") {
+				const bits = [view.agent, view.status, elapsed(view)];
+				if (view.phase) bits.push(view.phase);
+				return reply(`${runId} · ${bits.join(" · ")} — ${view.summary}`, {
+					runId,
+					agent: view.agent,
+					status: view.status,
+					phase: view.phase,
+					elapsedMs: view.elapsedMs,
+				});
+			}
+
+			// result
+			if (!isTerminal(view.status)) {
+				return reply(`${runId} is still ${view.status} (${elapsed(view)}) — ${view.phase || "no phase"}. Use action "wait" to join it.`, {
+					runId,
+					status: view.status,
+				});
+			}
+			const rendered = renderRunView(view, config.limits.maxOutputChars);
+			return reply(
+				rendered.text,
+				{ runId, agent: view.agent, status: view.status, durationMs: view.elapsedMs, truncated: rendered.truncated },
+				view.status === "failed",
+			);
+		},
+	});
+}