@gajae-code/coding-agent 0.5.2 → 0.5.4

package/src/dap/client.ts

@@ -1,6 +1,9 @@
-import { logger, ptree } from "@gajae-code/utils";
+import { existsSync } from "node:fs";
+import * as fs from "node:fs/promises";
+import { logger } from "@gajae-code/utils";
 import { formatCrashDiagnosticNotice, writeCrashReport } from "../debug/crash-diagnostics";
 import { NON_INTERACTIVE_ENV } from "../exec/non-interactive-env";
+import { type OwnedProcess, spawnOwnedProcess } from "../runtime/process-lifecycle";
 import { ToolAbortError } from "../tools/tool-errors";
 import type {
 	DapCapabilities,
@@ -69,10 +72,21 @@ function toErrorMessage(value: unknown): string {
 	return String(value);
 }
 
+async function drainReadable(readable: ReadableStream<Uint8Array>): Promise<void> {
+	const reader = readable.getReader();
+	try {
+		while (!(await reader.read()).done) {}
+	} catch {
+		/* drain best-effort */
+	} finally {
+		reader.releaseLock();
+	}
+}
 export class DapClient {
 	readonly adapter: DapResolvedAdapter;
 	readonly cwd: string;
 	readonly proc: DapClientState["proc"];
+	readonly #owner: OwnedProcess;
 	/** ReadableStream of DAP bytes — from proc.stdout (stdio) or a socket (socket mode). */
 	readonly #readable: ReadableStream<Uint8Array>;
 	/** Write sink — proc.stdin (stdio) or a socket (socket mode). */
@@ -93,14 +107,15 @@ export class DapClient {
 	constructor(
 		adapter: DapResolvedAdapter,
 		cwd: string,
-		proc: DapClientState["proc"],
+		owner: OwnedProcess,
 		options?: { readable?: ReadableStream<Uint8Array>; writeSink?: DapWriteSink; socket?: { end(): void } },
 	) {
 		this.adapter = adapter;
 		this.cwd = cwd;
-		this.proc = proc;
-		this.#readable = options?.readable ?? (proc.stdout as ReadableStream<Uint8Array>);
-		this.#writeSink = options?.writeSink ?? proc.stdin;
+		this.proc = owner.child as DapClientState["proc"];
+		this.#owner = owner;
+		this.#readable = options?.readable ?? (this.proc.stdout as ReadableStream<Uint8Array>);
+		this.#writeSink = options?.writeSink ?? this.proc.stdin;
 		this.#socket = options?.socket;
 	}
 
@@ -116,13 +131,14 @@ export class DapClient {
 			...Bun.env,
 			...NON_INTERACTIVE_ENV,
 		};
-		const proc = ptree.spawn([adapter.resolvedCommand, ...adapter.args], {
+		const owner = spawnOwnedProcess([adapter.resolvedCommand, ...adapter.args], {
 			cwd,
 			stdin: "pipe",
 			env,
-			detached: true,
+			name: `dap:${adapter.name}`,
 		});
-		const client = new DapClient(adapter, cwd, proc);
+		const client = new DapClient(adapter, cwd, owner);
+		const proc = owner.child as DapClientState["proc"];
 		proc.exited.then(() => {
 			client.#handleProcessExit();
 		});
@@ -159,32 +175,40 @@ export class DapClient {
 		env: Record<string, string | undefined>;
 	}): Promise<DapClient> {
 		const socketPath = `/tmp/dap-${adapter.name}-${Date.now()}-${Math.random().toString(36).slice(2)}.sock`;
-		const proc = ptree.spawn([adapter.resolvedCommand, ...adapter.args, `--listen=unix:${socketPath}`], {
+		const owner = spawnOwnedProcess([adapter.resolvedCommand, ...adapter.args, `--listen=unix:${socketPath}`], {
 			cwd,
 			stdin: "pipe",
 			env,
-			detached: true,
+			name: `dap:${adapter.name}:unix-socket`,
 		});
+		const proc = owner.child as DapClientState["proc"];
+		void drainReadable(proc.stdout);
+		let transport: SocketTransport | undefined;
 
-		// Wait for the socket file to appear (dlv needs to start listening)
-		await waitForCondition(
-			() => {
-				try {
-					Bun.file(socketPath).size;
-					return true;
-				} catch {
-					return false;
-				}
-			},
-			10_000,
-			proc,
-		);
+		try {
+			// Wait for the socket file to appear (dlv needs to start listening)
+			await waitForCondition(
+				// `Bun.file(path).size` returns 0 for a missing file instead of
+				// throwing, so it can't gate socket readiness. Use an existence
+				// check so the adapter has actually created the listener socket.
+				() => existsSync(socketPath),
+				10_000,
+				proc,
+			);
 
-		const { readable, writeSink, socket } = await connectSocket({ unix: socketPath });
-		const client = new DapClient(adapter, cwd, proc, { readable, writeSink, socket });
-		proc.exited.then(() => client.#handleProcessExit());
-		void client.#startMessageReader();
-		return client;
+			transport = await connectSocket({ unix: socketPath }, 10_000);
+			const client = new DapClient(adapter, cwd, owner, transport);
+			proc.exited.then(() => client.#handleProcessExit());
+			void client.#startMessageReader();
+			return client;
+		} catch (err) {
+			transport?.socket.end();
+			await owner.dispose();
+			await owner.awaitExit({ timeoutMs: 1_000 });
+			throw err;
+		} finally {
+			await fs.unlink(socketPath).catch(() => undefined);
+		}
 	}
 
 	/** macOS/other: listen on a random TCP port, spawn adapter with --client-addr, accept connection. */
@@ -214,12 +238,14 @@ export class DapClient {
 		});
 
 		const port = server.port;
-		const proc = ptree.spawn([adapter.resolvedCommand, ...adapter.args, `--client-addr=127.0.0.1:${port}`], {
+		const owner = spawnOwnedProcess([adapter.resolvedCommand, ...adapter.args, `--client-addr=127.0.0.1:${port}`], {
 			cwd,
 			stdin: "pipe",
 			env,
-			detached: true,
+			name: `dap:${adapter.name}:client-addr`,
 		});
+		const proc = owner.child as DapClientState["proc"];
+		void drainReadable(proc.stdout);
 
 		// Wait for dlv to connect (with timeout)
 		let rawSocket: Bun.Socket<undefined>;
@@ -230,13 +256,17 @@ export class DapClient {
 		);
 		try {
 			rawSocket = await Promise.race([connPromise, timeoutPromise]);
+		} catch (err) {
+			await owner.dispose();
+			await owner.awaitExit({ timeoutMs: 1_000 });
+			throw err;
 		} finally {
 			clearTimeout(connectTimeout);
 			server.stop();
 		}
 
 		const { readable, writeSink, socket } = wrapBunSocket(rawSocket);
-		const client = new DapClient(adapter, cwd, proc, { readable, writeSink, socket });
+		const client = new DapClient(adapter, cwd, owner, { readable, writeSink, socket });
 		proc.exited.then(() => client.#handleProcessExit());
 		void client.#startMessageReader();
 		return client;
@@ -414,14 +444,14 @@ export class DapClient {
 			/* socket may already be closed */
 		}
 		try {
-			this.proc.kill();
+			await this.#owner.dispose();
+			await this.#owner.awaitExit({ timeoutMs: 1_000 });
 		} catch (error) {
-			logger.debug("Failed to kill DAP adapter", {
+			logger.debug("Failed to dispose DAP adapter", {
 				adapter: this.adapter.name,
 				error: toErrorMessage(error),
 			});
 		}
-		await this.proc.exited.catch(() => {});
 	}
 
 	async #startMessageReader(): Promise<void> {
@@ -604,8 +634,8 @@ function socketToSink(socket: Bun.Socket<undefined>): DapWriteSink {
 }
 
 /** Connect to a unix domain socket and return DAP transport streams. */
-async function connectSocket(options: { unix: string }): Promise<SocketTransport> {
-	const { promise, resolve } = Promise.withResolvers<SocketTransport>();
+async function connectSocket(options: { unix: string }, timeoutMs = 10_000): Promise<SocketTransport> {
+	const { promise, resolve, reject } = Promise.withResolvers<SocketTransport>();
 	let streamController: ReadableStreamDefaultController<Uint8Array>;
 
 	const readable = new ReadableStream<Uint8Array>({
@@ -614,35 +644,46 @@ async function connectSocket(options: { unix: string }): Promise<SocketTransport
 		},
 	});
 
-	Bun.connect({
-		unix: options.unix,
-		socket: {
-			open(socket) {
-				resolve({
-					readable,
-					writeSink: socketToSink(socket),
-					socket,
-				});
-			},
-			data(_socket, data) {
-				streamController.enqueue(new Uint8Array(data));
-			},
-			close() {
-				try {
-					streamController.close();
-				} catch {
-					/* already closed */
-				}
-			},
-			error(_socket, err) {
-				try {
-					streamController.error(err);
-				} catch {
-					/* already closed */
-				}
+	const timeout = setTimeout(() => reject(new Error(`Socket connect timed out after ${timeoutMs}ms`)), timeoutMs);
+	let settled = false;
+	const settle = (fn: () => void) => {
+		if (settled) return;
+		settled = true;
+		clearTimeout(timeout);
+		fn();
+	};
+	try {
+		const socketPromise = Bun.connect({
+			unix: options.unix,
+			socket: {
+				open(socket) {
+					settle(() =>
+						resolve({
+							readable,
+							writeSink: socketToSink(socket),
+							socket,
+						}),
+					);
+				},
+				data(_socket, data) {
+					streamController.enqueue(new Uint8Array(data));
+				},
+				close() {
+					try {
+						streamController.close();
+					} catch {
+						/* already closed */
+					}
+				},
+				error(_socket, err) {
+					settle(() => reject(err));
+				},
 			},
-		},
-	});
+		});
+		void socketPromise.catch(err => settle(() => reject(err)));
+	} catch (err) {
+		settle(() => reject(err));
+	}
 
 	return promise;
 }

package/src/dap/session.ts

@@ -1,7 +1,8 @@
 import * as path from "node:path";
 import * as timers from "node:timers/promises";
-import { logger, ptree, untilAborted } from "@gajae-code/utils";
+import { logger, untilAborted } from "@gajae-code/utils";
 import { NON_INTERACTIVE_ENV } from "../exec/non-interactive-env";
+import { type OwnedProcess, spawnOwnedProcess } from "../runtime/process-lifecycle";
 import { DapClient } from "./client";
 import type {
 	DapAttachArguments,
@@ -63,6 +64,24 @@ import type {
 	DapWriteMemoryResponse,
 } from "./types";
 
+function drainStream(stream: ReadableStream<Uint8Array> | null | undefined): void {
+	if (!stream) return;
+	void (async () => {
+		try {
+			const reader = stream.getReader();
+			try {
+				while (!(await reader.read()).done) {
+					// drain only
+				}
+			} finally {
+				reader.releaseLock();
+			}
+		} catch {
+			// Process stream closed or was already consumed.
+		}
+	})();
+}
+
 interface DapSession {
 	id: string;
 	adapter: DapResolvedAdapter;
@@ -87,6 +106,7 @@ interface DapSession {
 	initializedSeen: boolean;
 	needsConfigurationDone: boolean;
 	configurationDoneSent: boolean;
+	runInTerminalProcesses: Set<OwnedProcess>;
 }
 
 export interface DapOutputSnapshot {
@@ -948,6 +968,7 @@ export class DapSessionManager {
 			initializedSeen: false,
 			needsConfigurationDone: false,
 			configurationDoneSent: false,
+			runInTerminalProcesses: new Set(),
 		};
 		client.onReverseRequest("runInTerminal", async rawArgs => {
 			const args = (rawArgs ?? {}) as DapRunInTerminalArguments;
@@ -957,17 +978,21 @@ export class DapSessionManager {
 			const env = Object.fromEntries(
 				Object.entries(args.env ?? {}).filter((entry): entry is [string, string] => entry[1] !== null),
 			);
-			const proc = ptree.spawn(args.args, {
+			const owner = spawnOwnedProcess(args.args, {
 				cwd: args.cwd ?? session.cwd,
-				stdin: "pipe",
+				stdin: "ignore",
 				env: {
 					...Bun.env,
 					...NON_INTERACTIVE_ENV,
 					...env,
 				},
-				detached: true,
+				name: `dap:${session.id}:runInTerminal`,
 			});
-			return { processId: proc.pid } satisfies DapRunInTerminalResponse;
+			drainStream(owner.child.stdout);
+			drainStream(owner.child.stderr);
+			session.runInTerminalProcesses.add(owner);
+			owner.exited.finally(() => session.runInTerminalProcesses.delete(owner));
+			return { processId: owner.pid } satisfies DapRunInTerminalResponse;
 		});
 		client.onReverseRequest("startDebugging", async rawArgs => {
 			const startArgs = (rawArgs ?? {}) as Partial<DapStartDebuggingArguments>;
@@ -1294,12 +1319,24 @@ export class DapSessionManager {
 		return session;
 	}
 
-	#disposeSession(session: DapSession) {
+	async #disposeSession(session: DapSession) {
 		if (this.#activeSessionId === session.id) {
 			this.#activeSessionId = null;
 		}
 		this.#sessions.delete(session.id);
-		void session.client.dispose().catch(() => {});
+		await this.#disposeRunInTerminalProcesses(session);
+		await session.client.dispose().catch(() => {});
+	}
+
+	async #disposeRunInTerminalProcesses(session: DapSession): Promise<void> {
+		const owners = [...session.runInTerminalProcesses];
+		session.runInTerminalProcesses.clear();
+		await Promise.allSettled(
+			owners.map(async owner => {
+				await owner.dispose();
+				await owner.awaitExit({ timeoutMs: 1_000 });
+			}),
+		);
 	}
 }
 

package/src/defaults/gjc/skills/deep-interview/SKILL.md

@@ -39,7 +39,8 @@ Inspired by the [Ouroboros project](https://github.com/Q00/ouroboros) which demo
 
 <Execution_Policy>
 - Ask ONE question at a time -- never batch multiple questions
-- Preserve the user/session language for every user-facing announcement, topology confirmation, option label, and interview question when state includes `language.instruction`; for example Korean initial ideas must receive Korean deep-interview questions unless the user explicitly requests another language
+- Default to English when no language preference is explicit or obvious. Preserve the user/session language for every user-facing announcement, topology confirmation, option label, and interview question when state includes `language.instruction`; do not add language-specific special cases
+- Before emitting any user-facing natural-language prose governed by `language.instruction`, perform one silent, best-effort self-proofread in the preserved session language for obvious spelling, spacing, grammar, inflection/particle, and word-choice errors, using the same language-agnostic pass for whatever language is active rather than special-casing any single language. Apply it only to newly generated prose and never announce the proofreading, show before/after text, apologize for it, or re-emit a corrected copy. Do not alter code blocks or identifiers, file paths, CLI commands, JSON/configuration keys, `ask` metadata keys, table/round structure, fixed labels, numeric scores, component ids, status tokens, user quotes or source text, Phase 0 threshold markers such as `Deep Interview threshold: <resolvedThresholdPercent> (source: <resolvedThresholdSource>)`, or fixed paths such as `.gjc/specs/deep-interview-{slug}.md`; still apply the self-proofread to generated natural-language clauses or cells inside those structures, including Why now rationale, gap text, next-target phrasing, and coverage notes
 - Target the WEAKEST clarity dimension with each question
 - Before Round 1 ambiguity scoring, run a one-time Round 0 topology enumeration gate that confirms the top-level component list and locks it into state
 - Make weakest-dimension targeting explicit every round: name the weakest dimension, state its score/gap, and explain why the next question is aimed there
@@ -96,7 +97,7 @@ Deep Interview threshold: <resolvedThresholdPercent> (source: <resolvedThreshold
    - Substitute `<resolvedThreshold>`, `<resolvedThresholdPercent>`, and `<resolvedThresholdSource>` throughout the remaining instructions before continuing.
    - Include `threshold_source` in the first `gjc state write` payload and preserve it on later state updates; do not edit `.gjc/state` files directly unless an explicit force override is active.
    - Include both threshold and source in the final spec metadata.
-- Read any `language` object from active deep-interview state and carry `language.instruction` forward mechanically. If absent, infer the user/session language from `{{ARGUMENTS}}` only when it is obvious. Do not surprise a Korean session with English questions.
+- Read any `language` object from active deep-interview state and carry `language.instruction` forward mechanically. If absent, default to English unless `{{ARGUMENTS}}` makes another user/session language obvious or the user explicitly requests another language. Do not add language-specific special cases.
 
 ## Phase 1: Initialize
 
@@ -175,6 +176,8 @@ The first line of this announcement MUST be exactly the Phase 0 threshold marker
 > **Project type:** {greenfield|brownfield}
 > **Current ambiguity:** 100% (we haven't started yet)
 
+Before emitting the prose lines in this announcement, apply the `<Execution_Policy>` self-proofread once; keep the required threshold marker and the quoted `{initial_idea}` unchanged.
+
 ## Round 0: Topology Enumeration Gate
 
 Run this gate exactly once after Phase 1 initialization and before any Phase 2 ambiguity scoring. The goal is to lock the **shape** of the user's scope before depth-first Socratic questioning can overfit to the most-described component.
@@ -293,6 +296,8 @@ Round {n} | Component: {target_component_name} | Targeting: {weakest_dimension}
 
 Options should include contextually relevant choices plus free-text, translated/localized according to `language.instruction` when present.
 
+After applying `language.instruction` to the visible question, options, and generated rationale, apply the self-proofread once to new prose only; preserve only the Round/Component/Targeting/Ambiguity line structure, fixed labels, numeric ambiguity value, component/target identifiers, and `deepInterview.*` metadata keys. Do not exempt generated natural-language rationale such as Why now.
+
 When calling `ask`, SHOULD include optional structured metadata so the runtime can record the round without manual state writes: `deepInterview.round_id?`, `deepInterview.round`, `deepInterview.component`, `deepInterview.dimension`, and `deepInterview.ambiguity`. Keep this metadata aligned with the visible Round/Component/Targeting/Ambiguity line; if metadata cannot be supplied, the legacy formatted question text remains the fallback.
 
 ### Step 2b′: Auto-Answer Opted-Out Questions
@@ -436,6 +441,8 @@ Round {n} complete.
 
 Apply `language.instruction` when present before showing this progress report so status text, gaps, and next-target phrasing stay in the preserved session language.
 
+Then apply the self-proofread once to narrative status text, generated prose cells, gaps, and next-target phrasing; preserve only table structure, fixed status labels, scores, weights, component ids, and trigger tokens.
+
 ### Step 2e: Update State
 
 Update state in two phases. The `ask` answer is first recorded by the runtime as an `answered` shell. Scoring then enriches the same round record to `scored` with global scores, per-component `topology.components[].clarity_scores`, `topology.components[].weakest_dimension`, trigger metadata, established-facts changes, ontology snapshot, `topology.last_targeted_component_id`, `auto_researched_rounds`, `auto_answered_rounds`, and `architect_failures`. When `deepInterview` ask metadata is present, no manual per-round `gjc state write` is required for the answer shell; only scoring enrichment/state maintenance remains. When metadata is absent, use the legacy `gjc state write` path to persist the new round and never patch `.gjc/state` directly unless an explicit force override is active.
@@ -486,6 +493,7 @@ When ambiguity ≤ threshold (or hard cap / early exit):
 
 1. **Generate the specification** using opus model with the prompt-safe transcript. If the full interview transcript or initial context is too large, include the summary plus all concrete decisions, acceptance criteria, unresolved gaps, and ontology snapshots; never overflow the prompt with raw oversized context.
    - Apply `language.instruction` when present so user-facing prose in the spec preserves the session language; keep code identifiers, file paths, commands, JSON/settings keys, and quoted source text unchanged.
+   - Apply the self-proofread once to newly generated spec prose before persistence, including generated natural-language table cells such as coverage notes, while preserving transcript answers, quoted/source text, code identifiers, file paths, commands, JSON/settings keys, table structure/fixed labels, and `.gjc/specs/deep-interview-{slug}.md` unchanged.
 2. **Write the final spec through the workflow CLI**: persist the artifact at `.gjc/specs/deep-interview-{slug}.md`
    - Always use this exact final spec path. Do not write temporary working files to the repo root or other ad hoc paths; repos may allowlist `.gjc/` for planning artifacts while protecting product branches.
    - Use the native deep-interview write command with `--write --stage final --slug {slug} --spec <markdown-or-path> [--json]` for artifact and state persistence; direct `.gjc/` file edits are forbidden unless an explicit force override is active.
@@ -785,6 +793,7 @@ Why bad: 45% ambiguity means nearly half the requirements are unclear. The mathe
 <Final_Checklist>
 - [ ] Phase 0 ran before anything: threshold resolved and first line emitted as `Deep Interview threshold: <resolvedThresholdPercent> (source: <resolvedThresholdSource>)`; state and spec metadata record both `threshold` and `threshold_source`
 - [ ] `language.instruction` preserved across announcements, questions, options, progress reports, and spec prose when present
+- [ ] User-facing natural-language prose, including generated prose clauses/cells inside round lines or tables, was silently self-proofread once according to `language.instruction`, while code/paths/commands/keys/table or round structure/fixed labels/status tokens/quotes/threshold markers/fixed paths remained unchanged
 - [ ] Oversized initial context/history summarized before scoring, question generation, spec generation, or handoff
 - [ ] Round 0 topology gate completed before scoring; `topology.confirmed_at` persisted
 - [ ] Ambiguity scored and displayed every round, naming the weakest component/dimension target (rotating across active components when N > 1)

package/src/defaults/gjc/skills/ralplan/SKILL.md

@@ -94,7 +94,7 @@ Follow the Plan skill's full documentation for consensus mode details.
 
 The Planner is a **same-session persisted subagent**: launched detached once, awaited before the Architect, then **resumed** with consolidated Architect + Critic feedback on every re-review pass instead of being re-spawned. The Architect and Critic stay **fresh, independent spawns each pass** so their verdicts remain reproducible from their pass artifacts alone. Do NOT modify the subagent control surface; this orchestration uses the existing `subagent` resume/steer controls only.
 
-**Persistence boundary:** this is same-parent, active-session continuity only. Resumability depends on the in-memory subagent record (and a persistent parent session — an in-memory parent yields `resumable:false`), not just a session file. The `.gjc` run-state record is an audit/routing hint, NOT a durable cross-process subagent registry. After a process restart, a missing record, or any unavailable/failed resume, use the fresh Planner fallback.
+**Persistence boundary:** this is same-parent, active-session continuity only. Resumability depends on the manager's retained subagent resume metadata and a persistent parent session (an in-memory parent yields `resumable:false`), not just the `.gjc` run-state record. A terminal subagent whose live job record was evicted can still be resumed when its retained resume descriptor points at a saved subagent session file. After a process restart, missing resume metadata, or any unavailable/failed resume, use the fresh Planner fallback.
 
 **Resume routing table** (per re-review pass, when resuming the persisted Planner id):
 
@@ -102,7 +102,7 @@ The Planner is a **same-session persisted subagent**: launched detached once, aw
 |---|---|
 | `running` | `steer`/inject the consolidated feedback to the same id, then await — do NOT fresh-spawn |
 | `queued` | retain/update the queued message or await the same id — do NOT fresh-spawn just because it is queued |
-| `context_unavailable`, `not_found`, `no_runner`, `resume_failed` | fresh Planner spawn for that pass; record the fallback metadata |
+| `context_unavailable`, `not_found`, `no_runner`, `resume_failed` | fresh Planner spawn for that pass; record the fallback metadata. `not_found` should only mean same-session resume metadata is unavailable, not merely that a terminal live job was evicted. |
 | terminal (`completed`/`failed`/`cancelled`) + revision message | resume the same id when context is available; otherwise use the fresh fallback above |
 
 **Recording persisted-Planner metadata** (audit/routing only — never claim `subagent list` proves resumability, since the snapshot does not expose `resumable`). Ride these optional flags on the normal `--write` for the planner/revision stage of the pass:

package/src/defaults/gjc/skills/ultragoal/SKILL.md

@@ -192,7 +192,7 @@ An ultragoal story cannot be checkpointed `complete` until the active agent has
 5. Delegate an `executor` QA/red-team lane to build and run the e2e/read-teaming QA suite appropriate for the story. This lane must try to break the change, not just confirm the happy path. It must start from the approved plan/spec/acceptance criteria, then user-facing contracts, and only then implementation code as supporting evidence. Plan/code mismatches are blockers, not items to paper over with implementation intent.
 6. The executor QA/red-team lane must prove evidence by the real surface under test:
    - GUI/web surfaces require a valid automation transcript plus a non-uniform screenshot. Bare `inlineEvidence` text or typed receipts never prove live GUI/web execution.
-   - CLI surfaces require runtime argv replay: `replaySafe: true`, an allowlisted argv `command`, and replayed normalized stdout matching `recordedStdout`; unsafe commands require audited `replayExempt` metadata plus a structurally valid fallback artifact.
+   - CLI surfaces require runtime argv replay: `replaySafe: true`, an allowlisted argv `command`, and replayed normalized stdout matching `recordedStdout`; unsafe commands require audited `replayExempt` metadata with exact fields `reasonCode`, `reason`, `approvedBy`, and `fallbackArtifactRefs` plus a structurally valid fallback artifact. Allowed `reasonCode` values are exactly `unsafe_side_effect`, `requires_credentials`, `requires_network`, `non_deterministic_external`, `destructive`, `interactive_only`, and `platform_unavailable`.
    - Native/desktop/tui surfaces require a structurally valid screenshot, PTY capture with terminal control codes, or app-automation transcript.
    - API/package/algorithm/math surfaces require a real artifact file or typed receipt. Bare `inlineEvidence` text alone is not sufficient for any surface.
 7. The executor QA/red-team lane must report a matrix using `executorQa.contractCoverage`, `executorQa.surfaceEvidence`, `executorQa.adversarialCases`, and `executorQa.artifactRefs`. Not-applicable rows are allowed only in `contractCoverage` and `surfaceEvidence`; each `status: "not_applicable"` row requires `contractRef` plus `reason`. `adversarialCases` rows cannot be not-applicable.
@@ -316,7 +316,7 @@ The native `checkpoint --status complete` command rejects missing or shallow gat
 }
 ```
 
-For CLI replay artifacts, the JSON at `path` must be an object like `{"schemaVersion":1,"kind":"cli-replay","replaySafe":true,"command":["bun","-e","console.log(\"ultragoal-cli-ok\")"],"recordedStdout":"ultragoal-cli-ok\n"}`. Use `replayExempt` only for audited unsafe/non-deterministic invocations, with a substantive reason, approver, and same-surface fallback artifacts.
+For CLI replay artifacts, the JSON at `path` must be an object like `{"schemaVersion":1,"kind":"cli-replay","replaySafe":true,"command":["bun","-e","console.log(\"ultragoal-cli-ok\")"],"recordedStdout":"ultragoal-cli-ok\n"}`. Use `replayExempt` only for audited unsafe/non-deterministic invocations, with exact fields `reasonCode`, `reason`, `approvedBy`, and `fallbackArtifactRefs`. `reason` must be substantive and audited, `approvedBy` must identify the verifier, and `fallbackArtifactRefs` must reference same-surface structurally valid fallback artifacts. Allowed `reasonCode` values are exactly `unsafe_side_effect`, `requires_credentials`, `requires_network`, `non_deterministic_external`, `destructive`, `interactive_only`, and `platform_unavailable`.
 
 ## Review mode
 

package/src/edit/read-file.ts

@@ -7,10 +7,28 @@
 import { isEnoent } from "@gajae-code/utils";
 import { isNotebookPath, readEditableNotebookText, serializeEditedNotebookText } from "./notebook";
 
+/**
+ * Max byte size of a file the edit modes will load whole. Editing loads + normalizes +
+ * fuzzy-matches + diffs the entire file on the main thread, so a multi-MB/generated file
+ * would block the event loop (F19). Above this, fail fast with an actionable error.
+ */
+export const MAX_EDIT_FILE_BYTES = 8 * 1024 * 1024;
+
 export async function readEditFileText(absolutePath: string, path: string): Promise<string> {
 	try {
+		const file = Bun.file(absolutePath);
+		const size = file.size; // 0 for a missing file; the read below then throws ENOENT.
+		if (size > MAX_EDIT_FILE_BYTES) {
+			throw new Error(
+				`File too large to edit safely: ${path} is ${size} bytes (limit ${MAX_EDIT_FILE_BYTES}). ` +
+					`Editing loads and diffs the whole file on the main thread; make a more targeted change, ` +
+					`split the file, or use a specialized tool.`,
+			);
+		}
+		// Guard BEFORE the notebook fast-path: a >8 MiB .ipynb would otherwise load + JSON-parse
+		// + convert the whole file via readEditableNotebookText, bypassing the F19 freeze guard.
 		if (isNotebookPath(absolutePath)) return await readEditableNotebookText(absolutePath, path);
-		return await Bun.file(absolutePath).text();
+		return await file.text();
 	} catch (error) {
 		if (isEnoent(error)) {
 			throw new Error(`File not found: ${path}`);