@gajae-code/coding-agent 0.2.5 → 0.3.1

package/src/commands/launch.ts

@@ -52,8 +52,8 @@ export default class Index extends Command {
 			description: "Allow starting in ~ without auto-switching to a temp dir",
 		}),
 		mode: Flags.string({
-			description: "Output mode: text (default), json, rpc, or rpc-ui",
-			options: ["text", "json", "rpc", "acp", "rpc-ui"],
+			description: "Output mode: text (default), json, rpc, acp, rpc-ui, or bridge",
+			options: ["text", "json", "rpc", "acp", "rpc-ui", "bridge"],
 		}),
 		print: Flags.boolean({
 			char: "p",

package/src/commands/state.ts

@@ -9,9 +9,10 @@ export default class State extends Command {
 		'$ gjc state write --input \'{"state":{"interview_id":"abc"}}\' --mode deep-interview --json',
 		"$ gjc state clear --mode deep-interview",
 		"$ gjc state deep-interview read --json",
-		'$ gjc state ralplan write --input \'{"phase":"approval","active":true}\' --json',
+		'$ gjc state ralplan write --input \'{"phase":"planner","active":true}\' --json',
 		"$ gjc state team contract",
 		"$ gjc state deep-interview handoff --to ralplan --json",
+		"$ gjc state doctor --skill ralplan --json",
 	];
 
 	async run(): Promise<void> {

package/src/commands/team.ts

@@ -1,11 +1,14 @@
 import { Args, Command, Flags } from "@gajae-code/utils/cli";
+import { renderCliWriteReceipt } from "../gjc-runtime/cli-write-receipt";
+import { renderTeamStatusMarkdown } from "../gjc-runtime/state-renderer";
 import {
 	buildTeamHudSummary,
 	executeGjcTeamApiOperation,
 	type GjcTeamSnapshot,
 	listGjcTeams,
-	monitorGjcTeam,
+	monitorGjcTeamSnapshot,
 	parseTeamLaunchArgs,
+	persistGjcTeamModeStateSummary,
 	readGjcTeamEvents,
 	readGjcTeamSnapshot,
 	shutdownGjcTeam,
@@ -31,6 +34,7 @@ async function syncTeamHud(snapshot: GjcTeamSnapshot): Promise<void> {
 			hud: await buildTeamHudSummary(snapshot, events.at(-1)),
 			source: "gjc-team",
 		});
+		await persistGjcTeamModeStateSummary(snapshot, process.cwd());
 	} catch {
 		// HUD sync is best-effort and must not change command semantics.
 	}
@@ -42,27 +46,21 @@ function formatTaskCounts(counts: Record<string, number>): string {
 		.join(" ");
 }
 
-function formatNotificationSummary(snapshot: GjcTeamSnapshot): string {
-	const summary = snapshot.notification_summary;
-	return `notifications: total=${summary.total} replay_eligible=${summary.replay_eligible} pending=${summary.by_state.pending} queued=${summary.by_state.queued} deferred=${summary.by_state.deferred} failed=${summary.by_state.failed}`;
-}
-
-function formatAwaitingIntegrationNextStep(snapshot: GjcTeamSnapshot): string[] {
-	if (snapshot.phase !== "awaiting_integration") return [];
-	return [
-		"next: worker tasks are completed, but integration still needs leader attention before the team is complete",
-	];
+function snapshotWriteReceipt(snapshot: GjcTeamSnapshot): Record<string, unknown> {
+	return {
+		ok: true,
+		team_name: snapshot.team_name,
+		phase: snapshot.phase,
+		state_dir: snapshot.state_dir,
+		tmux_session: snapshot.tmux_session,
+		tmux_target: snapshot.tmux_target,
+		worker_count: snapshot.workers.length,
+		task_counts: snapshot.task_counts,
+	};
 }
 
-function formatIntegrationSummary(snapshot: {
-	integration_by_worker?: Record<string, { status?: string; conflict_files?: string[] }>;
-}): string[] {
-	const entries = Object.entries(snapshot.integration_by_worker ?? {});
-	if (entries.length === 0) return ["integration: no attempts recorded"];
-	return entries.map(([worker, state]) => {
-		const files = state.conflict_files?.length ? ` files=${state.conflict_files.join(",")}` : "";
-		return `integration: ${worker} ${state.status ?? "unknown"}${files}`;
-	});
+function writeReceipt(value: Record<string, unknown>): void {
+	process.stdout.write(renderCliWriteReceipt(value));
 }
 
 function parseInputFlag(argv: string[]): Record<string, unknown> {
@@ -76,12 +74,13 @@ function parseInputFlag(argv: string[]): Record<string, unknown> {
 }
 
 export default class Team extends Command {
-	static description = "Run native GJC tmux team orchestration; --dry-run writes ephemeral .gjc/state/team state only";
+	static description =
+		"Run native GJC tmux team orchestration from inside an existing tmux/GJC --tmux session; --dry-run writes ephemeral .gjc/state/team state only";
 	static strict = false;
 
 	static args = {
 		action: Args.string({
-			description: "start (default), status, list, shutdown, resume, or api",
+			description: "start (default), status, monitor, list, shutdown, resume, or api",
 			required: false,
 		}),
 	};
@@ -96,8 +95,10 @@ export default class Team extends Command {
 	};
 
 	static examples = [
+		"gjc --tmux  # start/attach the required tmux-backed leader session first",
 		'gjc team 3:executor "Implement the approved plan"',
 		"gjc team status <team-name> --json",
+		"gjc team monitor <team-name> --json",
 		'gjc team api claim-task --input \'{"team_name":"demo","worker_id":"worker-1"}\' --json',
 		'gjc team 2:executor --dry-run --json "Preview state only"',
 		"gjc team shutdown <team-name>",
@@ -119,26 +120,36 @@ export default class Team extends Command {
 			return;
 		}
 
-		if (action === "status" || action === "resume") {
+		if (action === "status") {
 			const teamName = rest.find(arg => !arg.startsWith("--"));
 			if (!teamName) throw new Error("missing_team_name");
-			const snapshot = await monitorGjcTeam(teamName);
-			await syncTeamHud(snapshot);
+			const snapshot = await readGjcTeamSnapshot(teamName);
 			if (json) {
 				writeJson(snapshot);
 				return;
 			}
 			writeText([
-				`team: ${snapshot.team_name}`,
-				`phase: ${snapshot.phase}`,
-				`tmux: ${snapshot.tmux_target || snapshot.tmux_session}`,
-				`state: ${snapshot.state_dir}`,
-				`tasks: ${snapshot.task_total} (${formatTaskCounts(snapshot.task_counts)})`,
-				`workers: ${snapshot.workers.map(worker => `${worker.id}:${worker.status}`).join(" ")}`,
-				formatNotificationSummary(snapshot),
-				...formatAwaitingIntegrationNextStep(snapshot),
-				...formatIntegrationSummary(snapshot),
+				renderTeamStatusMarkdown(snapshot).trimEnd(),
+				"- mode: read-only status; use `gjc team monitor <team>` or `gjc team resume <team>` for recovery/integration",
 			]);
+			void formatTaskCounts(snapshot.task_counts);
+			return;
+		}
+
+		if (action === "monitor" || action === "resume") {
+			const teamName = rest.find(arg => !arg.startsWith("--"));
+			if (!teamName) throw new Error("missing_team_name");
+			const snapshot = await monitorGjcTeamSnapshot(teamName);
+			await syncTeamHud(snapshot);
+			if (json) {
+				writeReceipt(snapshotWriteReceipt(snapshot));
+				return;
+			}
+			writeText([
+				renderTeamStatusMarkdown(snapshot).trimEnd(),
+				"- mode: mutating monitor; liveness recovery and integration may have run",
+			]);
+			void formatTaskCounts(snapshot.task_counts);
 			return;
 		}
 
@@ -148,7 +159,7 @@ export default class Team extends Command {
 			const snapshot = await shutdownGjcTeam(teamName);
 			await syncTeamHud(snapshot);
 			if (json) {
-				writeJson(snapshot);
+				writeReceipt(snapshotWriteReceipt(snapshot));
 				return;
 			}
 			writeText([`team: ${snapshot.team_name}`, `phase: ${snapshot.phase}`, `state: ${snapshot.state_dir}`]);
@@ -162,8 +173,12 @@ export default class Team extends Command {
 					"Supported operations:",
 					"send-message broadcast mailbox-list mailbox-mark-delivered mailbox-mark-notified notification-list notification-read notification-replay notification-mark-pane-attempt worker-startup-ack",
 					"create-task read-task list-tasks update-task claim-task transition-task-status release-task-claim",
-					"read-config read-manifest read-worker-status read-worker-heartbeat update-worker-heartbeat write-worker-inbox write-worker-identity",
-					"append-event read-events await-event write-shutdown-request read-shutdown-ack read-monitor-snapshot write-monitor-snapshot read-task-approval write-task-approval",
+					"read-config read-manifest read-worker-status update-worker-status read-worker-heartbeat recover-stale-claims update-worker-heartbeat write-worker-inbox write-worker-identity",
+					"append-event read-events read-traces await-event write-shutdown-request read-shutdown-ack read-monitor-snapshot write-monitor-snapshot read-task-approval write-task-approval",
+					"Completion example:",
+					'transition-task-status --input \'{"team_name":"demo","task_id":"task-1","to":"completed","claim_token":"...","completion_evidence":{"summary":"done","items":[{"kind":"command","status":"passed","summary":"focused tests passed","command":"bun test packages/coding-agent/test/gjc-runtime/team-runtime.test.ts"}]}}\' --json',
+					'Review-only completion may use {"kind":"inspection","status":"verified","summary":"review passed","location":"agent://review"}.',
+					'Typed lane task example: create-task --input \'{"team_name":"demo","subject":"Verify delivery","description":"Run verification","owner":"worker-1","lane":"verification","required_role":"executor","depends_on":["task-1"]}\' --json',
 				]);
 				return;
 			}
@@ -177,7 +192,7 @@ export default class Team extends Command {
 					// API operations without a resolvable snapshot leave HUD state unchanged.
 				}
 			}
-			writeJson(result);
+			writeReceipt(result as Record<string, unknown>);
 			return;
 		}
 
@@ -186,7 +201,7 @@ export default class Team extends Command {
 		const snapshot = await startGjcTeam({ ...options, dryRun });
 		await syncTeamHud(snapshot);
 		if (json) {
-			writeJson(snapshot);
+			writeReceipt(snapshotWriteReceipt(snapshot));
 			return;
 		}
 		writeText([

package/src/config/keybindings.ts

@@ -38,6 +38,7 @@ interface AppKeybindings {
 	"app.session.fork": true;
 	"app.session.resume": true;
 	"app.session.observe": true;
+	"app.jobs.open": true;
 	"app.session.togglePath": true;
 	"app.session.toggleSort": true;
 	"app.session.rename": true;
@@ -149,6 +150,11 @@ export const KEYBINDINGS = {
 		defaultKeys: "ctrl+s",
 		description: "Observe subagent sessions",
 	},
+
+	"app.jobs.open": {
+		defaultKeys: "alt+j",
+		description: "Open monitor/cron jobs overlay",
+	},
 	"app.session.togglePath": {
 		defaultKeys: "ctrl+p",
 		description: "Toggle session path display",

package/src/config/settings-schema.ts

@@ -74,6 +74,7 @@ export type StatusLineSegmentId =
 	| "git"
 	| "pr"
 	| "subagents"
+	| "jobs"
 	| "token_in"
 	| "token_out"
 	| "token_total"
@@ -147,6 +148,7 @@ interface StringDef {
 interface NumberDef {
 	type: "number";
 	default: number;
+	validate?: (value: number) => boolean;
 	ui?: UiNumber;
 }
 
@@ -319,6 +321,12 @@ export const SETTINGS_SCHEMA = {
 
 	cycleOrder: { type: "array", default: DEFAULT_CYCLE_ORDER },
 
+	"gjc.deepInterview.ambiguityThreshold": {
+		type: "number",
+		default: 0.05,
+		validate: (value: number) => Number.isFinite(value) && value > 0 && value <= 1,
+	},
+
 	// ────────────────────────────────────────────────────────────────────────
 	// Appearance
 	// ────────────────────────────────────────────────────────────────────────
@@ -2345,11 +2353,12 @@ export const SETTINGS_SCHEMA = {
 
 	"task.maxConcurrency": {
 		type: "number",
-		default: 32,
+		default: 8,
 		ui: {
 			tab: "tasks",
 			label: "Max Concurrent Tasks",
-			description: "Concurrent limit for subagents",
+			description:
+				"Safer concurrent limit for subagents; higher fan-out still requires an explicit plan above 4 tasks.",
 			options: [
 				{ value: "0", label: "Unlimited" },
 				{ value: "1", label: "1 task" },
@@ -2401,7 +2410,8 @@ export const SETTINGS_SCHEMA = {
 		ui: {
 			tab: "tasks",
 			label: "Fork Context Max Tokens",
-			description: "Approximate token cap for fork-context seeds. 0 uses 25% of the target model context window.",
+			description:
+				"Approximate token cap for explicit full fork-context seeds. 0 uses 15% of the target model context window, with a 15k fallback when the window is unknown.",
 		},
 	},
 

package/src/config/settings.ts

@@ -297,6 +297,11 @@ export class Settings {
 		return getDefault(path);
 	}
 
+	/** Check whether a setting is present in loaded settings/overrides rather than coming from schema defaults. */
+	has(path: SettingPath): boolean {
+		return getByPath(this.#merged, path.split(".")) !== undefined;
+	}
+
 	/**
 	 * Set a setting value (sync).
 	 * Updates global settings and queues a background save.

package/src/dap/client.ts

@@ -1,4 +1,5 @@
 import { logger, ptree } from "@gajae-code/utils";
+import { formatCrashDiagnosticNotice, writeCrashReport } from "../debug/crash-diagnostics";
 import { NON_INTERACTIVE_ENV } from "../exec/non-interactive-env";
 import { ToolAbortError } from "../tools/tool-errors";
 import type {
@@ -532,15 +533,28 @@ export class DapClient {
 		}
 	}
 
-	#handleProcessExit(): void {
+	async #handleProcessExit(): Promise<void> {
 		if (this.#disposed) return;
 		this.#disposed = true;
 		const stderr = this.proc.peekStderr().trim();
 		const exitCode = this.proc.exitCode;
+		const crashNotice = formatCrashDiagnosticNotice(
+			await writeCrashReport(
+				{
+					kind: "dap",
+					command: [this.adapter.resolvedCommand, ...this.adapter.args],
+					exitCode,
+					stderr,
+					protocol: this.adapter.connectMode ?? "stdio",
+				},
+				{ cwd: this.cwd },
+			),
+		);
+		const diagnosticSuffix = crashNotice ? `\n${crashNotice}` : "";
 		const error = new Error(
 			stderr
-				? `DAP adapter exited (code ${exitCode}): ${stderr}`
-				: `DAP adapter exited unexpectedly (code ${exitCode})`,
+				? `DAP adapter exited (code ${exitCode}): ${stderr}${diagnosticSuffix}`
+				: `DAP adapter exited unexpectedly (code ${exitCode})${diagnosticSuffix}`,
 		);
 		this.#rejectPendingRequests(error);
 	}

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(),
+	};
+}