@gajae-code/coding-agent 0.3.0 → 0.3.1

package/src/debug/crash-diagnostics.ts

@@ -0,0 +1,223 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const CRASH_DIAGNOSTICS_ENV = "GJC_CRASH_DIAGNOSTICS";
+const CRASH_DIAGNOSTICS_DIR_ENV = "GJC_CRASH_DIAGNOSTICS_DIR";
+const STDERR_PREVIEW_BYTES = 4096;
+const DIRECTORY_MODE = 0o700;
+const REPORT_FILE_MODE = 0o600;
+
+export type CrashProcessKind = "bash" | "python" | "lsp" | "dap" | "mcp" | "browser" | "worker" | "native" | "unknown";
+
+export type CrashClass =
+	| "clean_exit"
+	| "non_zero_exit"
+	| "signal_exit"
+	| "timeout"
+	| "cancelled"
+	| "spawn_error"
+	| "protocol_exit"
+	| "native_panic"
+	| "unknown";
+
+export interface CrashClassificationInput {
+	kind: CrashProcessKind;
+	command?: string[];
+	exitCode?: number | null;
+	signal?: string | null;
+	cancelled?: boolean;
+	timedOut?: boolean;
+	spawnError?: unknown;
+	stderr?: string;
+	protocol?: string;
+}
+
+export interface CrashClassification {
+	kind: CrashProcessKind;
+	class: CrashClass;
+	crashed: boolean;
+	exitCode: number | null;
+	signal: string | null;
+	command?: string[];
+	protocol?: string;
+	reason: string;
+}
+
+export interface CrashReport extends CrashClassification {
+	schemaVersion: 1;
+	createdAt: string;
+	pid: number;
+	cwd: string;
+	stderrPreview?: string;
+	spawnError?: string;
+}
+
+export interface CrashReportWriteResult {
+	report: CrashReport;
+	path: string | null;
+	enabled: boolean;
+}
+
+export function crashDiagnosticsEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	const value = env[CRASH_DIAGNOSTICS_ENV];
+	return value === "1" || value === "true" || value === "yes";
+}
+
+export function getCrashDiagnosticsDirectory(env: NodeJS.ProcessEnv = process.env): string {
+	return env[CRASH_DIAGNOSTICS_DIR_ENV] ?? path.join(os.tmpdir(), "gjc-crash-diagnostics");
+}
+
+export function classifyProcessCrash(input: CrashClassificationInput): CrashClassification {
+	const exitCode = input.exitCode ?? null;
+	const signal = input.signal ?? null;
+	const command = input.command;
+	const protocol = input.protocol;
+
+	if (input.timedOut) {
+		return {
+			kind: input.kind,
+			class: "timeout",
+			crashed: true,
+			exitCode,
+			signal,
+			command,
+			protocol,
+			reason: "process timed out",
+		};
+	}
+	if (input.cancelled) {
+		return {
+			kind: input.kind,
+			class: "cancelled",
+			crashed: false,
+			exitCode,
+			signal,
+			command,
+			protocol,
+			reason: "process was cancelled",
+		};
+	}
+	if (input.spawnError !== undefined) {
+		return {
+			kind: input.kind,
+			class: "spawn_error",
+			crashed: true,
+			exitCode,
+			signal,
+			command,
+			protocol,
+			reason: stringifyError(input.spawnError),
+		};
+	}
+	if (signal) {
+		return {
+			kind: input.kind,
+			class: "signal_exit",
+			crashed: true,
+			exitCode,
+			signal,
+			command,
+			protocol,
+			reason: `process exited after signal ${signal}`,
+		};
+	}
+	if (exitCode === 0) {
+		return {
+			kind: input.kind,
+			class: "clean_exit",
+			crashed: false,
+			exitCode,
+			signal,
+			command,
+			protocol,
+			reason: "process exited cleanly",
+		};
+	}
+	if (exitCode !== null) {
+		return {
+			kind: input.kind,
+			class: "non_zero_exit",
+			crashed: true,
+			exitCode,
+			signal,
+			command,
+			protocol,
+			reason: `process exited with code ${exitCode}`,
+		};
+	}
+	return {
+		kind: input.kind,
+		class: "protocol_exit",
+		crashed: true,
+		exitCode,
+		signal,
+		command,
+		protocol,
+		reason: "process exited before protocol completion",
+	};
+}
+
+export async function writeCrashReport(
+	input: CrashClassificationInput,
+	options: { cwd?: string; env?: NodeJS.ProcessEnv; now?: Date } = {},
+): Promise<CrashReportWriteResult> {
+	const classification = classifyProcessCrash(input);
+	const report: CrashReport = {
+		schemaVersion: 1,
+		createdAt: (options.now ?? new Date()).toISOString(),
+		pid: process.pid,
+		cwd: options.cwd ?? process.cwd(),
+		...classification,
+		stderrPreview: input.stderr ? trimStartBytes(input.stderr, STDERR_PREVIEW_BYTES) : undefined,
+		spawnError: input.spawnError === undefined ? undefined : stringifyError(input.spawnError),
+	};
+	const enabled = crashDiagnosticsEnabled(options.env);
+
+	if (!classification.crashed || !enabled) {
+		return { report, path: null, enabled };
+	}
+
+	try {
+		const dir = getCrashDiagnosticsDirectory(options.env);
+		await ensurePrivateDiagnosticsDirectory(dir);
+		const filename = `${report.createdAt.replace(/[:.]/g, "-")}-${report.kind}-${report.class}-${process.pid}.json`;
+		const reportPath = path.join(dir, filename);
+		await writePrivateCrashReport(reportPath, `${JSON.stringify(report, null, 2)}\n`);
+		return { report, path: reportPath, enabled };
+	} catch {
+		return { report, path: null, enabled };
+	}
+}
+
+export function formatCrashDiagnosticNotice(result: CrashReportWriteResult): string | null {
+	if (!result.report.crashed || !result.enabled) return null;
+	const location = result.path ? ` report=${result.path}` : "";
+	return `[crash:${result.report.kind}:${result.report.class}] ${result.report.reason}${location}`;
+}
+
+async function ensurePrivateDiagnosticsDirectory(dir: string): Promise<void> {
+	await fs.mkdir(dir, { recursive: true, mode: DIRECTORY_MODE });
+	await fs.chmod(dir, DIRECTORY_MODE);
+}
+
+async function writePrivateCrashReport(reportPath: string, contents: string): Promise<void> {
+	const file = await fs.open(reportPath, "wx", REPORT_FILE_MODE);
+	try {
+		await file.writeFile(contents);
+	} finally {
+		await file.close();
+	}
+	await fs.chmod(reportPath, REPORT_FILE_MODE);
+}
+
+function stringifyError(error: unknown): string {
+	if (error instanceof Error) return error.message;
+	return String(error);
+}
+
+function trimStartBytes(value: string, maxBytes: number): string {
+	const bytes = Buffer.from(value);
+	if (bytes.byteLength <= maxBytes) return value;
+	return Buffer.from(bytes.subarray(bytes.byteLength - maxBytes)).toString("utf8");
+}

package/src/debug/runtime-gauges.ts

@@ -0,0 +1,20 @@
+/**
+ * Runtime resource owner gauges (Stage 2 observability).
+ *
+ * Reports counts of long-lived runtime owners as plain data so memory/CPU leak
+ * work can see whether owner maps grow without bound across a session. This is
+ * framework-agnostic on purpose: it does not depend on the TUI metrics surface,
+ * so any consumer (debug report, a metrics bridge, a test) can sample it.
+ */
+import { getShellSessionCount } from "../exec/bash-executor";
+
+/**
+ * Current runtime owner counts, keyed by `<owner>.<resource>`. Extend as more
+ * owners (Python kernels, LSP clients, browser tabs, async jobs, streaming
+ * queues) expose count getters.
+ */
+export function getRuntimeResourceCounts(): Record<string, number> {
+	return {
+		"bash.shellSessions": getShellSessionCount(),
+	};
+}

package/src/deep-interview/render-middleware.ts

@@ -330,6 +330,12 @@ export function renderDeepInterviewAskQuestion(question: string, uiTheme: Theme)
 	return renderModel(model, uiTheme);
 }
 
+export function isDeepInterviewAskQuestion(question: string): boolean {
+	if (parseTopologyQuestion(question) ?? parseRoundQuestion(question)) return true;
+	const normalized = normalizeText(question);
+	return /(?:^|\n)\s*Round\s+\d+\s*\|.*?\bAmbiguity\b/i.test(normalized);
+}
+
 export function formatDeepInterviewSelectorPrompt(question: string): string | null {
 	const model = parseTopologyQuestion(question) ?? parseRoundQuestion(question);
 	if (!model) return null;

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

@@ -125,7 +125,7 @@ Deep Interview threshold: <resolvedThresholdPercent> (source: <resolvedThreshold
 ```json
 {
   "active": true,
-  "current_phase": "deep-interview",
+  "current_phase": "interviewing",
   "state": {
     "interview_id": "<uuid>",
     "type": "greenfield|brownfield",

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

@@ -49,10 +49,12 @@ Restricted read-only role agents (`planner`, `architect`, and `critic`) must pas
 
 After a role agent persists a stage artifact, its model-facing response to the caller SHOULD be receipt-only: return the `gjc ralplan --write --json` receipt (`run_id`, `path`, `stage`, `stage_n`, `sha256`, `created_at`) plus the minimal verdict/status fields the caller needs for routing, and do **not** paste the full persisted markdown back into the parent conversation. Downstream reviewers should receive the artifact path/receipt and read the persisted file themselves when they actually need the body. This preserves the audit trail while preventing Planner/Architect/Critic verdict bodies from being duplicated into the main-agent context.
 
+RECEIPT-ONLY guideline: role agents (`planner`, `architect`, and `critic`) persist durable outputs via `gjc ralplan --write` and return ONLY the receipt fields (`run_id`, `path`, `sha256`) plus verdict/status routing fields; include `stage` and `stage_n` when available, and never return the full persisted body.
+
 This skill runs GJC planning in consensus mode for the provided arguments.
 
 The consensus workflow:
-1. **Planner** creates initial plan and a compact **RALPLAN-DR summary** before review, then persists the stage with `gjc ralplan --write --stage planner --stage_n 1 --artifact "..."`:
+1. **Planner** creates the initial plan and a compact **RALPLAN-DR summary** before review. Launch the Planner ONCE per run as a detached, resumable subagent (await it before the Architect) and record its returned subagent id as the run's persisted Planner id; persist the stage with `gjc ralplan --write --stage planner --stage_n 1 --artifact "..." --planner-id <id> --planner-resumable <true|false>` (see **Persisted Planner** below):
    - After persistence, return only the receipt/path plus compact planning status; do not paste the full plan markdown back to the caller unless explicitly requested.
    - Principles (3-5)
    - Decision Drivers (top 3)
@@ -66,7 +68,7 @@ The consensus workflow:
    - The Critic agent/subagent must persist its evaluation with `gjc ralplan --write --stage critic --stage_n <N> --artifact "..." --json`, then return the receipt/path plus compact verdict/status (`OKAY`/`ITERATE`/`REJECT`) instead of pasting the full evaluation body.
 5. **Re-review loop** (max 5 iterations): Any non-`APPROVE` Critic verdict (`ITERATE` or `REJECT`) MUST run the same full closed loop:
    a. Collect Architect + Critic feedback
-   b. Revise the plan with Planner
+   b. Revise the plan by resuming the SAME persisted Planner subagent with consolidated Architect + Critic feedback (see **Persisted Planner** below); fall back to a fresh Planner spawn only per the fallback routing table
    c. Return to Architect review
       - Persist each Planner revision with `gjc ralplan --write --stage revision --stage_n <N> --artifact "..." --json` before re-review, then pass the receipt/path forward instead of duplicating the full revision markdown in the parent conversation.
    d. Return to Critic evaluation
@@ -88,6 +90,33 @@ The consensus workflow:
 
 Follow the Plan skill's full documentation for consensus mode details.
 
+### Persisted Planner (consensus loop)
+
+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.
+
+**Resume routing table** (per re-review pass, when resuming the persisted Planner id):
+
+| Resume outcome | Action |
+|---|---|
+| `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 |
+| 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:
+
+```
+gjc ralplan --write --stage revision --stage_n <N> --artifact "..." \
+  --planner-id <id> --planner-resumable <true|false> \
+  --fallback-reason <context_unavailable|not_found|no_runner|resume_failed|process_restart|missing_record> \
+  --fallback-attempted-id <id> --fallback-stage-n <N> \
+  --fallback-receipt-path <fresh-planner-stage-artifact-path> --json
+```
+
+Set `--planner-resumable true` only when the parent session is provably persistent; set/record `false` after an observed `context_unavailable`; otherwise omit it (unknown). Fallback flags are recorded only when a fresh-spawn fallback actually occurs: a fallback record requires `--fallback-reason` **together with** `--fallback-attempted-id` and `--fallback-stage-n` (the failed id and the pass it failed on), while `--fallback-receipt-path` (the fresh Planner's stage artifact) is optional.
+
 ## Pre-Execution Gate
 
 ### Why the Gate Exists

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

@@ -50,12 +50,38 @@ Use `goal({"op":"get"})` snapshots inside Ultragoal for ledger reconciliation. T
 
 ## Create goals
 
-1. Run one of:
+1. Decide on the brief. To produce **multiple** stories, separate them with a reserved `@goal:` delimiter line; the title follows on the same line and the objective is everything beneath it until the next delimiter:
+
+   ```text
+   Shared brief constraints / context go here (optional preamble).
+
+   @goal: Parse the intake CSVs
+   Ingest reviewer CSVs from the watch dir, validate headers, and reject
+   malformed rows with a per-row reason. Objectives can span multiple lines
+   and contain `code`, "quotes", or commands — no escaping needed.
+
+   @goal: Normalize records
+   Map raw rows onto the canonical schema and dedupe by record id.
+
+   @goal: Export the audit report
+   Emit an audit-ready report covering every accepted and rejected row.
+   ```
+
+   Delimiter contract:
+   - A `@goal` line is a story boundary **only** when it starts at column 0 (no leading whitespace) and the character right after `@goal` is `:`, whitespace (space or tab), or end-of-line. So `@goal: Title`, `@goal Title`, and a bare `@goal` line all open a story.
+   - `@goalish`, `@goals:`, `@goal-foo`, `@goal.foo`, `@goal/foo`, and any indented or mid-line `@goal` are ordinary objective text, not delimiters. To keep a literal `@goal` line inside an objective, indent it.
+   - A title-only block (no body) uses the title as its objective. An empty title borrows the first body line as the title. A block with **neither** title nor body is rejected — `create-goals` errors instead of writing a placeholder goal.
+   - **Preamble** (any text before the first `@goal` delimiter) is global context/constraints only; it is retained in the brief but is **not** turned into a goal. Every executable story needs its own `@goal` block.
+   - With **no** `@goal` delimiter anywhere, the whole brief becomes a single goal `G001` (unchanged legacy behavior).
+
+   Stories become `G001`, `G002`, … in order.
+
+2. Run one of:
    - `gjc ultragoal create-goals --brief "<brief>"`
    - `gjc ultragoal create-goals --brief-file <path>`
    - `cat <brief> | gjc ultragoal create-goals --from-stdin`
    - `gjc ultragoal create-goals --gjc-goal-mode per-story --brief "<brief>"` only when one GJC goal context per story is explicitly preferred
-2. Inspect `.gjc/ultragoal/goals.json` and refine if needed.
+3. Inspect `.gjc/ultragoal/goals.json` and refine if needed.
 
 ## Complete goals
 

package/src/eval/py/executor.ts

@@ -1,5 +1,6 @@
 import { getProjectDir, logger } from "@gajae-code/utils";
 import { Settings } from "../../config/settings";
+import { formatCrashDiagnosticNotice, writeCrashReport } from "../../debug/crash-diagnostics";
 import { OutputSink } from "../../session/streaming-output";
 import type { ToolSession } from "../../tools";
 import { resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../../tools/output-meta";
@@ -62,6 +63,8 @@ export interface PythonExecutorOptions {
 
 export interface PythonKernelExecutor {
 	execute: (code: string, options?: KernelExecuteOptions) => Promise<KernelExecuteResult>;
+	getExitCode?: () => number | null;
+	peekStderr?: () => string;
 }
 
 export interface PythonResult {
@@ -446,12 +449,29 @@ async function executeWithKernel(
 			const annotation = result.timedOut
 				? formatKernelTimeoutAnnotation(executionTimeoutMs, result.kernelKilled ?? false)
 				: undefined;
+			let crashNotice: string | null = null;
+			if (result.kernelKilled) {
+				crashNotice = formatCrashDiagnosticNotice(
+					await writeCrashReport(
+						{
+							kind: "python",
+							exitCode: kernel.getExitCode?.(),
+							cancelled: false,
+							timedOut: result.timedOut,
+							stderr: kernel.peekStderr?.(),
+							protocol: "eval.py.kernel",
+						},
+						{ cwd: options?.cwd },
+					),
+				);
+			}
+			const notice = [annotation, crashNotice].filter(text => text).join("; ") || undefined;
 			return {
 				exitCode: undefined,
 				cancelled: true,
 				displayOutputs,
 				stdinRequested: result.stdinRequested,
-				...(await sink.dump(annotation)),
+				...(await sink.dump(notice)),
 			};
 		}
 

package/src/eval/py/kernel.ts

@@ -183,6 +183,8 @@ export class PythonKernel {
 	#disposed = false;
 	#shutdownConfirmed = false;
 	#exitedPromise: Promise<number> | null = null;
+	#exitCode: number | null = null;
+	#stderrTail = "";
 	#pending = new Map<string, PendingExecution>();
 	#readBuffer = "";
 
@@ -230,6 +232,7 @@ export class PythonKernel {
 		kernel.#stdin = proc.stdin;
 		kernel.#exitedPromise = proc.exited;
 		void kernel.#exitedPromise.then(code => {
+			kernel.#exitCode = code;
 			kernel.#alive = false;
 			kernel.#abortPendingExecutions(`Python kernel exited with code ${code}`, { kernelKilled: true });
 		});
@@ -255,6 +258,14 @@ export class PythonKernel {
 		return this.#alive && !this.#disposed;
 	}
 
+	getExitCode(): number | null {
+		return this.#exitCode;
+	}
+
+	peekStderr(): string {
+		return this.#stderrTail;
+	}
+
 	async execute(code: string, options?: KernelExecuteOptions): Promise<KernelExecuteResult> {
 		if (!this.isAlive()) {
 			throw new Error("Python kernel is not running");
@@ -493,6 +504,10 @@ export class PythonKernel {
 					const { done, value } = await reader.read();
 					if (done) break;
 					const text = decoder.decode(value);
+					this.#stderrTail += text;
+					if (this.#stderrTail.length > 4096) {
+						this.#stderrTail = this.#stderrTail.slice(-4096);
+					}
 					if (text.trim()) {
 						logger.warn("Python runner stderr", { text });
 					}

package/src/exec/bash-executor.ts

@@ -5,7 +5,9 @@
  */
 import * as fs from "node:fs/promises";
 import { executeShell, type MinimizerOptions, Shell } from "@gajae-code/natives";
+import { postmortem } from "@gajae-code/utils";
 import { Settings, type ShellMinimizerSettings } from "../config/settings";
+import { formatCrashDiagnosticNotice, writeCrashReport } from "../debug/crash-diagnostics";
 import { OutputSink } from "../session/streaming-output";
 import { resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../tools/output-meta";
 import { getOrCreateSnapshot } from "../utils/shell-snapshot";
@@ -58,6 +60,30 @@ export interface BashResult {
 const shellSessions = new Map<string, Shell>();
 const brokenShellSessions = new Set<string>();
 
+/** Number of persistent shell sessions currently retained (owner gauge). */
+export function getShellSessionCount(): number {
+	return shellSessions.size;
+}
+
+/**
+ * Dispose all persistent shell sessions: abort in-flight work and drop the
+ * strong references so the native shells can be finalized. Healthy persistent
+ * sessions are otherwise retained for the whole process lifetime (MEM-7). This
+ * is registered as a postmortem cleanup so shutdown/signals release native
+ * shell resources, and is also callable directly (e.g. on owner teardown).
+ */
+export async function disposeAllShellSessions(): Promise<void> {
+	// Snapshot and drop strong references up front so concurrent callers cannot
+	// reuse a session that is being torn down, then await every native abort so
+	// shutdown/signal cleanup does not return before resources are released.
+	const sessions = [...shellSessions.values()];
+	shellSessions.clear();
+	brokenShellSessions.clear();
+	await Promise.allSettled(sessions.map(session => session.abort()));
+}
+
+postmortem.register("bash-executor:shell-sessions", () => disposeAllShellSessions());
+
 async function resolveShellCwd(cwd: string | undefined): Promise<string | undefined> {
 	if (!cwd) return undefined;
 
@@ -280,6 +306,21 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 			}
 		}
 
+		const crashReport = await writeCrashReport(
+			{
+				kind: "bash",
+				command: [shell, "-lc", finalCommand],
+				exitCode: winner.result.exitCode,
+				stderr: undefined,
+			},
+			{ cwd: commandCwd },
+		);
+		const crashNotice = formatCrashDiagnosticNotice(crashReport);
+		if (crashNotice) {
+			const separator = "\n";
+			sink.push(`${separator}${crashNotice}\n`);
+		}
+
 		// Normal completion
 		return {
 			exitCode: winner.result.exitCode,

package/src/gjc-runtime/cli-write-receipt.ts

@@ -0,0 +1,31 @@
+/**
+ * CLI write/mutation receipt shaping (Workstream B, v4).
+ *
+ * `CliWriteReceipt` is the compact **stdout presentation** returned by a GJC
+ * mutation command. It carries only routing/audit fields a caller needs; it
+ * NEVER echoes the persisted body (full `state` envelope, ultragoal `plan`,
+ * team task body, ralplan `task`, etc.) — echoing those back is a redundant
+ * token leak because the caller already has the content it just wrote.
+ *
+ * This is intentionally a *separate* concept from the persisted
+ * `WorkflowStateReceipt` (the on-disk envelope `receipt` integrity field).
+ * Do NOT use `CliWriteReceipt` as a persistence schema or validate persisted
+ * envelopes against it.
+ */
+export interface CliWriteReceipt {
+	ok: boolean;
+	[field: string]: unknown;
+}
+
+/**
+ * Serialize a write/mutation receipt to compact stdout JSON.
+ * `undefined` fields are dropped so optional routing fields stay absent
+ * rather than serialized as `null`.
+ */
+export function renderCliWriteReceipt(receipt: Record<string, unknown>): string {
+	const out: Record<string, unknown> = {};
+	for (const key of Object.keys(receipt)) {
+		if (receipt[key] !== undefined) out[key] = receipt[key];
+	}
+	return `${JSON.stringify(out)}\n`;
+}