@gajae-code/coding-agent 0.4.5 → 0.5.1

package/src/harness-control-plane/gc-adapter.ts

@@ -0,0 +1,184 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import {
+	type GcCollectResult,
+	type GcContext,
+	type GcError,
+	type GcPruneOutcome,
+	type GcRecord,
+	type GcStoreAdapter,
+	gcPidStatusLabel,
+	gcProbeToLeasePidStatus,
+} from "../gjc-runtime/gc-runtime";
+import { classifyLeaseStatus, readLease, reapDeadOwnerArtifacts } from "./session-lease";
+import {
+	type HarnessRootRegistryForGc,
+	type HarnessRootRegistryListingForGc,
+	listHarnessRootRegistriesForGc,
+	removeHarnessRootRegistryFileForGc,
+	rewriteHarnessRootRegistryForGc,
+	sessionPaths,
+} from "./storage";
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+async function exists(file: string): Promise<boolean> {
+	try {
+		await fs.access(file);
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+function registryErrors(registries: HarnessRootRegistryListingForGc[]): GcError[] {
+	return registries
+		.filter(registry => registry.error)
+		.map(registry => ({
+			store: "registry_entries",
+			scope: registry.file,
+			message: registry.error ?? "registry_error",
+		}));
+}
+
+async function collectRegistries(ctx: GcContext): Promise<HarnessRootRegistryListingForGc[]> {
+	return listHarnessRootRegistriesForGc(ctx.env);
+}
+
+export const harnessLeasesGcAdapter: GcStoreAdapter = {
+	store: "harness_leases",
+	async collect(ctx: GcContext): Promise<GcCollectResult> {
+		const records: GcRecord[] = [];
+		const errors: GcError[] = [];
+		const registries = await collectRegistries(ctx);
+		errors.push(...registryErrors(registries).map(error => ({ ...error, store: "harness_leases" as const })));
+
+		const roots = new Set<string>();
+		for (const registry of registries) {
+			if (registry.error) continue;
+			for (const entry of registry.roots) roots.add(path.resolve(entry.root));
+		}
+
+		for (const root of roots) {
+			const sessionsDir = path.join(root, "sessions");
+			let sessionEntries: string[];
+			try {
+				sessionEntries = await fs.readdir(sessionsDir);
+			} catch (error) {
+				const code = (error as NodeJS.ErrnoException).code;
+				if (code === "ENOENT") continue;
+				errors.push({ store: "harness_leases", scope: sessionsDir, message: errorMessage(error) });
+				continue;
+			}
+
+			for (const sessionId of sessionEntries) {
+				const sessionDir = sessionPaths(root, sessionId).dir;
+				try {
+					const stat = await fs.stat(sessionDir);
+					if (!stat.isDirectory()) continue;
+					const lease = await readLease(root, sessionId);
+					if (!lease) continue;
+					const status = classifyLeaseStatus(lease, { probe: gcProbeToLeasePidStatus(ctx.probe) });
+					const pidProbe = ctx.probe(lease.pid);
+					const pidStatus = gcPidStatusLabel(pidProbe);
+					const removable = status === "dead" && pidProbe.status === "dead";
+					records.push({
+						store: "harness_leases",
+						id: sessionId,
+						root,
+						path: sessionPaths(root, sessionId).lease,
+						pid: lease.pid,
+						pid_status: pidStatus,
+						status,
+						stale: status === "dead",
+						removable,
+						action: "none",
+						reason: removable
+							? `lease owner pid ${lease.pid} is dead`
+							: `lease owner pid ${lease.pid} is ${pidStatus}; keeping`,
+					});
+				} catch (error) {
+					errors.push({ store: "harness_leases", scope: sessionDir, message: errorMessage(error) });
+				}
+			}
+		}
+
+		return { records, errors };
+	},
+	async prune(record: GcRecord, ctx: GcContext): Promise<GcPruneOutcome> {
+		if (!record.root) return { removed: false, skipped: "missing_root" };
+		const lease = await readLease(record.root, record.id);
+		if (!lease) return { removed: false, skipped: "lease_not_dead_or_missing" };
+		const status = classifyLeaseStatus(lease, { probe: gcProbeToLeasePidStatus(ctx.probe) });
+		if (status !== "dead") return { removed: false, skipped: "lease_not_dead_or_missing" };
+		const removed = await reapDeadOwnerArtifacts(record.root, record.id, lease.ownerId, lease.leaseEpoch, {
+			probe: gcProbeToLeasePidStatus(ctx.probe),
+		});
+		return removed ? { removed: true } : { removed: false, skipped: "reaper_guard_rejected" };
+	},
+};
+
+async function splitRegistryRoots(registry: HarnessRootRegistryForGc): Promise<{
+	liveRoots: HarnessRootRegistryForGc["roots"];
+	danglingRoots: HarnessRootRegistryForGc["roots"];
+}> {
+	const liveRoots: HarnessRootRegistryForGc["roots"] = [];
+	const danglingRoots: HarnessRootRegistryForGc["roots"] = [];
+	for (const entry of registry.roots) {
+		const sessionDir = sessionPaths(entry.root, registry.sessionId).dir;
+		if (await exists(sessionDir)) liveRoots.push(entry);
+		else danglingRoots.push(entry);
+	}
+	return { liveRoots, danglingRoots };
+}
+
+export const registryEntriesGcAdapter: GcStoreAdapter = {
+	store: "registry_entries",
+	async collect(ctx: GcContext): Promise<GcCollectResult> {
+		const records: GcRecord[] = [];
+		const errors: GcError[] = [];
+		const registries = await collectRegistries(ctx);
+		errors.push(...registryErrors(registries));
+
+		for (const registry of registries) {
+			if (registry.error) continue;
+			try {
+				const { liveRoots, danglingRoots } = await splitRegistryRoots(registry);
+				if (danglingRoots.length === 0) continue;
+				records.push({
+					store: "registry_entries",
+					id: registry.sessionId,
+					path: registry.file,
+					pid_status: "none",
+					status: "dangling",
+					stale: true,
+					removable: true,
+					action: "none",
+					reason: `dangling roots: ${danglingRoots.map(entry => entry.root).join(", ")}`,
+					detail: `${danglingRoots.length} dangling, ${liveRoots.length} live`,
+				});
+			} catch (error) {
+				errors.push({ store: "registry_entries", scope: registry.file, message: errorMessage(error) });
+			}
+		}
+
+		return { records, errors };
+	},
+	async prune(record: GcRecord, ctx: GcContext): Promise<GcPruneOutcome> {
+		if (!record.path) return { removed: false, skipped: "missing_registry_path" };
+		const registries = await collectRegistries(ctx);
+		const registry = registries.find(entry => entry.file === record.path);
+		if (!registry || registry.error) return { removed: false, skipped: "registry_not_readable" };
+		const { liveRoots, danglingRoots } = await splitRegistryRoots(registry);
+		if (danglingRoots.length === 0) return { removed: false, skipped: "no_dangling_roots" };
+		if (liveRoots.length === 0) {
+			await removeHarnessRootRegistryFileForGc(record.path);
+		} else {
+			await rewriteHarnessRootRegistryForGc(record.path, { sessionId: registry.sessionId, roots: liveRoots });
+		}
+		return { removed: true };
+	},
+};

package/src/harness-control-plane/owner.ts

@@ -20,6 +20,7 @@ import { ControlServer, type EndpointRequest } from "./control-endpoint";
 import { defaultFinalizeChecks, type FinalizeChecks, runFinalize, type ValidationCommandSpec } from "./finalize";
 import { type OperateResult, operate } from "./operate";
 import { preserveDirtyWorktree } from "./preserve";
+import { RECEIPT_SPOOL_DIR_ENV, withReceiptSpoolDir } from "./receipt-spool";
 import {
 	buildReceipt,
 	type ReceiptSubject,
@@ -28,8 +29,7 @@ import {
 	type VanishEvidence,
 	validateReceipt,
 } from "./receipts";
-import type { HarnessRpc } from "./rpc-adapter";
-import { singleFlightAccept } from "./rpc-adapter";
+import { type HarnessRpc, type RpcStateSnapshot, singleFlightAccept } from "./rpc-adapter";
 import {
 	acquireLease,
 	canWriteEvents,
@@ -39,7 +39,7 @@ import {
 	releaseLease,
 	type SessionLease,
 } from "./session-lease";
-import { buildStateView, nextAllowedActions } from "./state-machine";
+import { buildStateView, nextAllowedActions, submitUnavailableReason } from "./state-machine";
 import {
 	appendEvent,
 	controlSocketPath,
@@ -200,11 +200,6 @@ export class RuntimeOwner {
 	}
 
 	async #emitMapped(mapped: NonNullable<ReturnType<typeof observeRpcOutboundFrame>>): Promise<void> {
-		await this.#emit(
-			mapped.severity,
-			mapped.kind,
-			mapped.signal ? { ...mapped.evidence, signal: mapped.signal } : mapped.evidence,
-		);
 		if (mapped.kind === "rpc_agent_completed") {
 			const state = await readSessionState(this.#opts.root, this.#opts.sessionId);
 			if (
@@ -218,6 +213,11 @@ export class RuntimeOwner {
 				await writeSessionState(this.#opts.root, state);
 			}
 		}
+		await this.#emit(
+			mapped.severity,
+			mapped.kind,
+			mapped.signal ? { ...mapped.evidence, signal: mapped.signal } : mapped.evidence,
+		);
 	}
 
 	#aggregateSignals(events: EventEnvelope[]): string[] {
@@ -233,6 +233,20 @@ export class RuntimeOwner {
 		return out;
 	}
 
+	#eventSubmitGateReason(kind: string, evidence: Record<string, unknown>): string | null {
+		const reason = typeof evidence.reason === "string" ? evidence.reason : null;
+		const signal = typeof evidence.signal === "string" ? evidence.signal : null;
+		const rpcActive =
+			kind === "prompt_accepted" ||
+			reason === "pre-state-not-idle" ||
+			kind.startsWith("rpc_") ||
+			signal === "prompt-accepted" ||
+			signal === "streaming" ||
+			signal === "tool-call" ||
+			signal === "test-running";
+		return rpcActive ? "rpc-not-idle" : null;
+	}
+
 	async #emit(severity: Severity, kind: string, evidence: Record<string, unknown>): Promise<void> {
 		const lease = await readLease(this.#opts.root, this.#opts.sessionId);
 		// Single-writer guard: only emit while we still hold a live lease.
@@ -247,6 +261,7 @@ export class RuntimeOwner {
 					ownerLive: true,
 					blockers: [],
 				};
+		const submitGateReason = this.#eventSubmitGateReason(kind, evidence);
 		const envelope: EventEnvelope = {
 			eventId: randomUUID(),
 			cursor: ++this.#cursor,
@@ -255,21 +270,41 @@ export class RuntimeOwner {
 			kind,
 			state: view,
 			evidence,
-			nextAllowedActions: nextAllowedActions(view.lifecycle, true),
+			nextAllowedActions: nextAllowedActions(view.lifecycle, true, { submitUnavailableReason: submitGateReason }),
 			writer: { ownerId: this.ownerId, leaseEpoch: this.#leaseEpoch },
 		};
 		await appendEvent(this.#opts.root, this.#opts.sessionId, envelope);
 	}
 
-	#response(state: SessionState, evidence: Record<string, unknown>, ok = true): PrimitiveResponse {
+	#response(
+		state: SessionState,
+		evidence: Record<string, unknown>,
+		ok = true,
+		submitGateReason: string | null = null,
+	): PrimitiveResponse {
 		return {
 			ok,
 			state: buildStateView(state, true),
 			evidence,
-			nextAllowedActions: nextAllowedActions(state.lifecycle, true),
+			nextAllowedActions: nextAllowedActions(state.lifecycle, true, { submitUnavailableReason: submitGateReason }),
 		};
 	}
 
+	#submitGateReason(state: SessionState, rpcState: RpcStateSnapshot | null): string | null {
+		const rpcReason = rpcState
+			? rpcState.isStreaming || rpcState.steeringQueueDepth > 0 || rpcState.followupQueueDepth > 0
+				? "rpc-not-idle"
+				: null
+			: "rpc-not-live";
+		return submitUnavailableReason(state.lifecycle, true, rpcReason);
+	}
+
+	async #withReceiptSpoolFromInput<T>(input: Record<string, unknown>, fn: () => Promise<T>): Promise<T> {
+		const requested = input[RECEIPT_SPOOL_DIR_ENV];
+		if (typeof requested === "string" && requested.trim()) return withReceiptSpoolDir(requested, fn);
+		return fn();
+	}
+
 	async #handle(req: EndpointRequest): Promise<unknown> {
 		switch (req.verb) {
 			case "ping":
@@ -281,13 +316,13 @@ export class RuntimeOwner {
 			case "retire":
 				return this.#retire();
 			case "finalize":
-				return this.#finalize(req.input);
+				return this.#withReceiptSpoolFromInput(req.input, () => this.#finalize(req.input));
 			case "recover":
-				return this.#recover();
+				return this.#withReceiptSpoolFromInput(req.input, () => this.#recover());
 			case "validate":
-				return this.#validate();
+				return this.#withReceiptSpoolFromInput(req.input, () => this.#validate());
 			case "operate":
-				return this.#operate(req.input);
+				return this.#withReceiptSpoolFromInput(req.input, () => this.#operate(req.input));
 			default:
 				return { ok: false, error: `owner_unsupported_verb:${req.verb}` };
 		}
@@ -297,8 +332,10 @@ export class RuntimeOwner {
 		const state = await this.#loadState();
 		const workspace = state.handle.workspace;
 		let streaming = false;
+		let rpcState: RpcStateSnapshot | null = null;
 		try {
-			streaming = (await this.#opts.rpc.getState()).isStreaming;
+			rpcState = await this.#opts.rpc.getState();
+			streaming = rpcState.isStreaming;
 		} catch {
 			streaming = false;
 		}
@@ -328,12 +365,7 @@ export class RuntimeOwner {
 				gitDelta = "unknown";
 			}
 		}
-		const rpcLive = this.#opts.rpc.isLive
-			? this.#opts.rpc.isLive()
-			: await this.#opts.rpc
-					.getState()
-					.then(() => true)
-					.catch(() => false);
+		const rpcLive = this.#opts.rpc.isLive ? this.#opts.rpc.isLive() : rpcState !== null;
 		const rpcLastFrameAt = this.#opts.rpc.lastFrameAt ? this.#opts.rpc.lastFrameAt() : null;
 		// Sticky semantic signals come from the persisted owner event log -> survive polling gaps.
 		const recent = (await readEvents(this.#opts.root, this.#opts.sessionId, 0)).slice(-200);
@@ -343,6 +375,7 @@ export class RuntimeOwner {
 			(t): t is string => typeof t === "string",
 		);
 		const lastActivityAt = stamps.length > 0 ? (stamps.sort().at(-1) ?? state.updatedAt) : state.updatedAt;
+		const submitGateReason = this.#submitGateReason(state, rpcState);
 		return {
 			lifecycle: state.lifecycle,
 			ownerLive: true,
@@ -354,6 +387,8 @@ export class RuntimeOwner {
 			risk: deleted ? "deleted-worktree" : "normal",
 			rpcLive,
 			rpcLastFrameAt,
+			readyForSubmit: submitGateReason === null,
+			submitUnavailableReason: submitGateReason,
 		};
 	}
 
@@ -543,10 +578,21 @@ export class RuntimeOwner {
 		const prompt = typeof input.prompt === "string" ? input.prompt : "";
 		const state = await this.#loadState();
 		if (!prompt) {
-			return this.#response(state, { accepted: false, reason: "empty-prompt" }, false);
+			return this.#response(
+				state,
+				{ accepted: false, submitted: false, reason: "empty-prompt" },
+				false,
+				"empty-prompt",
+			);
 		}
-		if (state.lifecycle === "blocked") {
-			return this.#response(state, { accepted: false, reason: "lifecycle-blocked" }, false);
+		const lifecycleGate = submitUnavailableReason(state.lifecycle, true);
+		if (lifecycleGate) {
+			return this.#response(
+				state,
+				{ accepted: false, submitted: false, reason: lifecycleGate },
+				false,
+				lifecycleGate,
+			);
 		}
 		const result = await singleFlightAccept(this.#opts.rpc, prompt, this.#opts.acceptanceTimeoutMs);
 		if (result.accepted) {
@@ -560,11 +606,12 @@ export class RuntimeOwner {
 		} else {
 			await this.#emit("warn", "prompt_not_accepted", { reason: result.reason });
 		}
+		const submitGateReason = result.accepted ? null : result.reason === "pre-state-not-idle" ? "rpc-not-idle" : null;
 		return this.#response(
 			state,
 			{
 				accepted: result.accepted,
-				submitted: true,
+				submitted: result.commandId !== null,
 				reason: result.reason,
 				commandId: result.commandId,
 				preSubmitCursor: result.preSubmitCursor,
@@ -572,12 +619,16 @@ export class RuntimeOwner {
 				acceptanceEvidence: result.preSubmitState,
 			},
 			result.accepted,
+			submitGateReason,
 		);
 	}
 
 	async #observe(): Promise<PrimitiveResponse> {
 		const state = await this.#loadState();
-		return this.#response(state, { observation: await this.#observeGit(), ownerRouted: true });
+		const observation = await this.#observeGit();
+		const submitGateReason =
+			typeof observation.submitUnavailableReason === "string" ? observation.submitUnavailableReason : null;
+		return this.#response(state, { observation, ownerRouted: true }, true, submitGateReason);
 	}
 
 	async #retire(): Promise<PrimitiveResponse> {
@@ -619,3 +670,14 @@ export async function resolveOwner(root: string, sessionId: string): Promise<Res
 	const live = status === "live" || status === "expiredAlive" || status === "epermAlive";
 	return { live, socketPath: lease.endpoint?.path ?? null, lease };
 }
+
+/**
+ * Owner liveness for verbs that do not route to the owner (e.g. `classify`): a routable owner
+ * has a live lease and a socket endpoint. This is the same lease/socket probe `observe` uses to
+ * decide routing, so non-routing verbs derive `ownerLive` consistently instead of assuming the
+ * owner is gone (which would misclassify a live owner as vanished/restart-clean).
+ */
+export async function resolveOwnerLive(root: string, sessionId: string): Promise<boolean> {
+	const owner = await resolveOwner(root, sessionId);
+	return owner.live && owner.socketPath !== null;
+}

package/src/harness-control-plane/receipt-spool.ts

@@ -0,0 +1,128 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { withFileLock } from "../config/file-lock";
+import type { ReceiptEnvelope } from "./receipts";
+
+export const RECEIPT_SPOOL_DIR_ENV = "GJC_RECEIPT_SPOOL_DIR";
+export const RECEIPT_SPOOL_FILENAME = "spool.jsonl";
+export const RECEIPT_SPOOL_CURSOR_WIDTH = 12;
+
+export interface ReceiptSpoolRecord {
+	cursor: string;
+	envelope: ReceiptEnvelope<unknown>;
+}
+
+export interface ReceiptSpoolAppendResult {
+	cursor: string;
+	path: string;
+}
+
+const receiptSpoolDirStorage = new AsyncLocalStorage<string | undefined>();
+const spoolQueues = new Map<string, Promise<void>>();
+const noop = (): void => undefined;
+export async function withReceiptSpoolDir<T>(spoolDir: string, fn: () => Promise<T>): Promise<T> {
+	const trimmed = spoolDir.trim();
+	if (!trimmed) throw new Error("receipt_spool_dir_empty");
+	const resolved = path.resolve(trimmed);
+	return receiptSpoolDirStorage.run(resolved, fn);
+}
+
+export function resolveReceiptSpoolDir(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const active = receiptSpoolDirStorage.getStore();
+	if (active !== undefined) return active;
+	const raw = env[RECEIPT_SPOOL_DIR_ENV]?.trim();
+	return raw ? path.resolve(raw) : undefined;
+}
+
+export function receiptSpoolPath(spoolDir: string): string {
+	return path.join(path.resolve(spoolDir), RECEIPT_SPOOL_FILENAME);
+}
+
+function parseCursor(value: unknown): bigint | undefined {
+	if (typeof value !== "string" || !/^\d+$/.test(value)) return undefined;
+	try {
+		return BigInt(value);
+	} catch {
+		return undefined;
+	}
+}
+
+export function formatReceiptSpoolCursor(cursor: bigint): string {
+	const raw = cursor.toString();
+	return raw.length >= RECEIPT_SPOOL_CURSOR_WIDTH ? raw : raw.padStart(RECEIPT_SPOOL_CURSOR_WIDTH, "0");
+}
+
+export async function readHighestReceiptSpoolCursor(spoolDir: string): Promise<bigint> {
+	const spoolFile = receiptSpoolPath(spoolDir);
+	let raw: string;
+	try {
+		raw = await fs.readFile(spoolFile, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return 0n;
+		throw error;
+	}
+
+	let highest = 0n;
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			const parsed = JSON.parse(trimmed) as { cursor?: unknown };
+			const cursor = parseCursor(parsed.cursor);
+			if (cursor !== undefined && cursor > highest) highest = cursor;
+		} catch {
+			// A crash may leave a torn tail; consumers skip malformed lines and so do we.
+		}
+	}
+	return highest;
+}
+
+async function enqueueSpoolAppend<T>(spoolFile: string, task: () => Promise<T>): Promise<T> {
+	const previous = spoolQueues.get(spoolFile) ?? Promise.resolve();
+	const running = previous.catch(noop).then(task);
+	const normalized = running.then(noop, noop);
+	spoolQueues.set(spoolFile, normalized);
+	normalized
+		.finally(() => {
+			if (spoolQueues.get(spoolFile) === normalized) spoolQueues.delete(spoolFile);
+		})
+		.catch(noop);
+	return running;
+}
+
+export async function appendReceiptToSpool(
+	spoolDir: string,
+	envelope: ReceiptEnvelope<unknown>,
+): Promise<ReceiptSpoolAppendResult> {
+	const resolvedDir = path.resolve(spoolDir);
+	const spoolFile = receiptSpoolPath(resolvedDir);
+	return enqueueSpoolAppend(spoolFile, async () => {
+		await fs.mkdir(resolvedDir, { recursive: true, mode: 0o700 });
+		return withFileLock(
+			spoolFile,
+			async () => {
+				const cursor = formatReceiptSpoolCursor((await readHighestReceiptSpoolCursor(resolvedDir)) + 1n);
+				const record: ReceiptSpoolRecord = { cursor, envelope };
+				const handle = await fs.open(spoolFile, "a", 0o600);
+				try {
+					await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+					await handle.sync();
+				} finally {
+					await handle.close();
+				}
+				return { cursor, path: spoolFile };
+			},
+			{ staleMs: 30_000, retries: 100, retryDelayMs: 25 },
+		);
+	});
+}
+
+export async function appendReceiptToConfiguredSpool(
+	envelope: ReceiptEnvelope<unknown>,
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<ReceiptSpoolAppendResult | undefined> {
+	const spoolDir = resolveReceiptSpoolDir(env);
+	if (!spoolDir) return undefined;
+	return appendReceiptToSpool(spoolDir, envelope);
+}

package/src/harness-control-plane/state-machine.ts

@@ -8,6 +8,7 @@
 import type { HarnessLifecycle, NextAllowedAction, PrimitiveResponse, SessionState, SessionStateView } from "./types";
 
 const TERMINAL_LIFECYCLES: ReadonlySet<HarnessLifecycle> = new Set(["completed", "retired"]);
+const SUBMIT_READY_LIFECYCLES: ReadonlySet<HarnessLifecycle> = new Set(["started", "observing"]);
 
 const TRANSITIONS: Record<HarnessLifecycle, readonly HarnessLifecycle[]> = {
 	new: ["started", "blocked", "retired"],
@@ -37,11 +38,32 @@ export function assertTransition(from: HarnessLifecycle, to: HarnessLifecycle):
 	}
 }
 
+export interface NextAllowedActionsOptions {
+	/** Additional live-owner/RPC readiness gate for submit, e.g. rpc-not-idle. */
+	submitUnavailableReason?: string | null;
+}
+
+export function submitUnavailableReason(
+	lifecycle: HarnessLifecycle,
+	ownerLive: boolean,
+	gateReason: string | null = null,
+): string | null {
+	if (isTerminal(lifecycle)) return `lifecycle-terminal:${lifecycle}`;
+	if (lifecycle === "blocked") return "lifecycle-blocked";
+	if (!SUBMIT_READY_LIFECYCLES.has(lifecycle)) return `lifecycle-not-idle:${lifecycle}`;
+	if (!ownerLive) return "owner-not-live";
+	return gateReason;
+}
+
 /**
  * Derive the permitted next actions for a session given its lifecycle and whether
  * a live owner currently holds the lease.
  */
-export function nextAllowedActions(lifecycle: HarnessLifecycle, ownerLive: boolean): NextAllowedAction[] {
+export function nextAllowedActions(
+	lifecycle: HarnessLifecycle,
+	ownerLive: boolean,
+	options: NextAllowedActionsOptions = {},
+): NextAllowedAction[] {
 	const terminal = isTerminal(lifecycle);
 	const actions: NextAllowedAction[] = [];
 	const add = (verb: NextAllowedAction["verb"], available: boolean, reason?: string): void => {
@@ -57,11 +79,10 @@ export function nextAllowedActions(lifecycle: HarnessLifecycle, ownerLive: boole
 	// `start` creates a new session; never re-applicable to an existing record.
 	add("start", false, "session-already-exists");
 
-	// `submit` is owner-routed: it requires a live owner and a non-blocked, non-terminal lifecycle.
-	if (terminal) add("submit", false, `lifecycle-terminal:${lifecycle}`);
-	else if (lifecycle === "blocked") add("submit", false, "lifecycle-blocked");
-	else if (!ownerLive) add("submit", false, "owner-not-live");
-	else add("submit", true);
+	// `submit` is owner-routed: it requires a live owner, a submit-ready lifecycle,
+	// and (for owner-observed responses) an idle/routable RPC backend.
+	const submitReason = submitUnavailableReason(lifecycle, ownerLive, options.submitUnavailableReason ?? null);
+	add("submit", submitReason === null, submitReason ?? undefined);
 
 	// `recover` handles a dead/failed owner, so it is available without a live owner.
 	add("recover", !terminal, terminal ? `lifecycle-terminal:${lifecycle}` : undefined);