@gajae-code/coding-agent 0.4.5 → 0.5.0

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> {

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);

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

@@ -18,6 +18,8 @@ import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import { appendReceiptToConfiguredSpool } from "./receipt-spool";
+import type { ReceiptEnvelope } from "./receipts";
 import type { EventEnvelope, ReceiptFamily, SessionState } from "./types";
 
 interface HarnessRootRegistryEntry {
@@ -227,6 +229,26 @@ async function readJson<T>(file: string): Promise<T | null> {
 		throw error;
 	}
 }
+function isReceiptEnvelope(value: unknown): value is ReceiptEnvelope<unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const envelope = value as Record<string, unknown>;
+	return (
+		typeof envelope.receiptId === "string" &&
+		typeof envelope.schemaVersion === "number" &&
+		typeof envelope.sessionId === "string" &&
+		typeof envelope.family === "string" &&
+		typeof envelope.valid === "boolean" &&
+		typeof envelope.createdAt === "string" &&
+		typeof envelope.source === "string" &&
+		envelope.subject !== null &&
+		typeof envelope.subject === "object" &&
+		envelope.evidence !== null &&
+		typeof envelope.evidence === "object" &&
+		envelope.artifactHashes !== null &&
+		typeof envelope.artifactHashes === "object" &&
+		typeof envelope.sha256 === "string"
+	);
+}
 
 export async function readSessionState(root: string, sessionId: string): Promise<SessionState | null> {
 	return readJson<SessionState>(sessionPaths(root, sessionId).state);
@@ -372,6 +394,7 @@ export async function writeReceiptImmutable(
 		path: file,
 	};
 	await fs.appendFile(paths.receiptsIndex, `${JSON.stringify(entry)}\n`, "utf8");
+	if (isReceiptEnvelope(value)) await appendReceiptToConfiguredSpool(value);
 	return entry;
 }
 

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

@@ -210,6 +210,10 @@ export interface Observation {
 	rpcLive?: boolean;
 	/** ISO timestamp of the most recent RPC frame the owner observed, if any. */
 	rpcLastFrameAt?: string | null;
+	/** True only when owner/rpc/lifecycle gates indicate a prompt can be submitted now. */
+	readyForSubmit?: boolean;
+	/** Present when readyForSubmit is false; mirrors submit's nextAllowedActions reason. */
+	submitUnavailableReason?: string | null;
 }
 
 /** Input to the deterministic recovery classifier. */

package/src/hindsight/mental-models.ts

@@ -295,12 +295,12 @@ export function summarizeMentalModel(model: MentalModelSummary): string {
  * snapshot only; the diff is computed locally for display purposes.
  *
  * This is intentionally minimal — for "what changed" at a glance, not for a
- * full structural diff. Each side is capped at `MAX_LCS_LINES` lines BEFORE
- * the O(n*m) LCS table is built so a long curated model can never hang the
- * TUI; output is then capped at `maxLines` so the rendered diff stays
- * readable. The cap is signalled inline.
+ * full structural diff. Each side is capped at `MAX_LCS_LINES` lines before
+ * the Hunt-Szymanski LCS pass so a long curated model can never hang the TUI;
+ * output is then capped at `maxLines` so the rendered diff stays readable. The
+ * cap is signalled inline.
  */
-/** Hard cap on input line count per side before LCS. Keeps the O(n*m) table tractable. */
+/** Hard cap on input line count per side before LCS. Keeps worst-case repeated-line matching bounded. */
 export const MAX_LCS_LINES = 1_000;
 
 export function diffMentalModelContent(previous: string | null, current: string, maxLines = 200): string {
@@ -346,24 +346,25 @@ export function diffMentalModelContent(previous: string | null, current: string,
 }
 
 function longestCommonSubsequence(a: string[], b: string[]): string[] {
-	const n = a.length;
-	const m = b.length;
-	if (n === 0 || m === 0) return [];
-	const table: number[][] = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
-	for (let i = 0; i < n; i++) {
-		for (let j = 0; j < m; j++) {
-			table[i + 1][j + 1] = a[i] === b[j] ? table[i][j] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+	return longestCommonSubsequenceDense(a, b);
+}
+
+function longestCommonSubsequenceDense(a: string[], b: string[]): string[] {
+	const table: number[][] = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+	for (let i = 0; i < a.length; i++) {
+		for (let j = 0; j < b.length; j++) {
+			table[i + 1]![j + 1] = a[i] === b[j] ? table[i]![j]! + 1 : Math.max(table[i + 1]![j]!, table[i]![j + 1]!);
 		}
 	}
 	const out: string[] = [];
-	let i = n;
-	let j = m;
+	let i = a.length;
+	let j = b.length;
 	while (i > 0 && j > 0) {
 		if (a[i - 1] === b[j - 1]) {
-			out.push(a[i - 1]);
+			out.push(a[i - 1]!);
 			i--;
 			j--;
-		} else if (table[i - 1][j] >= table[i][j - 1]) {
+		} else if (table[i - 1]![j]! >= table[i]![j - 1]!) {
 			i--;
 		} else {
 			j--;