@gajae-code/coding-agent 0.11.11 → 0.12.1

package/src/async/job-manager.ts

@@ -32,6 +32,8 @@ export interface AsyncJob {
 	promise: Promise<void>;
 	resultText?: string;
 	errorText?: string;
+	/** Safe, bounded cause when session setup failed before the LLM began work. */
+	setupFailureSummary?: string;
 	metadata?: AsyncJobMetadata;
 	/**
 	 * Registry id of the agent that registered the job (e.g. "0-Main",
@@ -69,9 +71,12 @@ export interface AsyncJobMetadata {
  * non-terminal and non-delivering: the run suspended at a safe boundary and the
  * subagent can be resumed from its persisted sessionFile. `completed` always
  * wins a race with a late pause because the run returns it once it has actually
- * finished.
+ * finished. A `failed` outcome retains a safe setup diagnostic for receipt rendering.
  */
-export type SubagentRunOutcome = { kind: "completed"; text: string } | { kind: "paused"; note?: string };
+export type SubagentRunOutcome =
+	| { kind: "completed"; text: string }
+	| { kind: "failed"; text: string; setupFailureSummary?: string }
+	| { kind: "paused"; note?: string };
 
 /** Canonical lifecycle of a subagent across pause/resume cycles. */
 export type SubagentLifecycle = "running" | "paused" | "queued" | "completed" | "failed" | "cancelled";
@@ -146,7 +151,11 @@ export interface SubagentRecord {
 	historicalJobIds: string[];
 	status: SubagentLifecycle;
 	sessionFile: string | null;
-	/** False for ephemeral sessions (no persistent artifacts dir). */
+	/**
+	 * Explicit veto, not a complete availability result. False always denies;
+	 * true still requires an owner-compatible descriptor or non-blank session
+	 * file, followed by a separately available runner (`no_runner` otherwise).
+	 */
 	resumable: boolean;
 	queued?: { ownerId?: string; seq: number; message?: string; createdAt: number };
 	/** Resolved model the subagent was asked to use, e.g. "openai-codex/gpt-5.5". */
@@ -176,6 +185,22 @@ function sessionFileFromResumeDescriptorData(data: unknown): string | null {
 	return typeof sessionFile === "string" && sessionFile.trim().length > 0 ? sessionFile : null;
 }
 
+/**
+ * Derive retained context from an already owner-compatible descriptor or a
+ * legacy session file. A descriptor is sufficient even when `sessionFile` is
+ * null because the descriptor is the payload the resume runner consumes.
+ */
+function hasRetainedResumeContext(input: {
+	resumable: boolean;
+	sessionFile: string | null;
+	descriptor: ResumeDescriptor | undefined;
+}): boolean {
+	if (!input.resumable) return false;
+	return (
+		input.descriptor !== undefined || (typeof input.sessionFile === "string" && input.sessionFile.trim().length > 0)
+	);
+}
+
 /** A pending resume awaiting a free concurrency slot. */
 interface ResumeQueueEntry {
 	subagentId: string;
@@ -499,7 +524,7 @@ export class AsyncJobManager {
 					typeof result === "string" ? { kind: "completed", text: result } : result;
 
 				if (job.status === "cancelled") {
-					job.resultText = outcome.kind === "completed" ? outcome.text : outcome.note;
+					job.resultText = outcome.kind === "paused" ? outcome.note : outcome.text;
 					this.#runLifecycle(id, "terminal", job);
 					this.#scheduleEviction(id);
 					this.#markRecordTerminal(id, "cancelled");
@@ -509,7 +534,7 @@ export class AsyncJobManager {
 				if (outcome.kind === "paused") {
 					// Sole canonical writer of the running -> paused transition. No
 					// delivery and no eviction scheduling: a paused subagent stays
-					// listed and resumable from its sessionFile.
+					// listed and resumable from its retained resume context.
 					job.status = "paused";
 					this.#freezeEndTime(job);
 					if (outcome.note) job.resultText = outcome.note;
@@ -517,6 +542,18 @@ export class AsyncJobManager {
 					this.#drainResumeQueue();
 					return;
 				}
+				if (outcome.kind === "failed") {
+					job.status = "failed";
+					job.setupFailureSummary = outcome.setupFailureSummary;
+					this.#freezeEndTime(job);
+					job.errorText = outcome.text;
+					this.#enqueueDelivery(id, outcome.text);
+					this.#runLifecycle(id, "terminal", job);
+					this.#scheduleEviction(id);
+					this.#markRecordTerminal(id, "failed");
+					this.#drainResumeQueue();
+					return;
+				}
 
 				job.status = "completed";
 				this.#freezeEndTime(job);
@@ -684,7 +721,9 @@ export class AsyncJobManager {
 			historicalJobIds: [],
 			status: "completed",
 			sessionFile,
-			resumable: sessionFile !== null,
+			// The synthesized record copies this descriptor's owner, so the
+			// descriptor is owner-compatible with the record by construction.
+			resumable: hasRetainedResumeContext({ resumable: true, sessionFile, descriptor }),
 		};
 		this.#subagentRecords.set(record.subagentId, record);
 		return record;
@@ -765,13 +804,24 @@ export class AsyncJobManager {
 	}
 
 	/**
-	 * Resolve the resume runner for a subagent: prefer the per-descriptor runner
-	 * captured at registration time (the originating parent's execution authority),
-	 * falling back to the process-global runner only for descriptors registered
-	 * without one.
+	 * Resolve a descriptor only when `ownerId` matches the record by strict
+	 * equality. Two undefined owners match; a distinguishably foreign descriptor
+	 * is treated as absent for eligibility, runner selection, and execution.
 	 */
-	#resolveResumeRunner(subagentId: string): ResumeRunner | undefined {
-		return this.#descriptorResumeRunners.get(subagentId) ?? this.#resumeRunner;
+	#descriptorForRecord(rec: SubagentRecord): ResumeDescriptor | undefined {
+		const descriptor = this.#resumeDescriptors.get(rec.subagentId);
+		return descriptor !== undefined && descriptor.ownerId === rec.ownerId ? descriptor : undefined;
+	}
+
+	/**
+	 * Resolve the resume runner for a record and its already owner-compatible
+	 * descriptor. Per-descriptor authority is unavailable when the descriptor is foreign.
+	 */
+	#resolveResumeRunner(rec: SubagentRecord, descriptor: ResumeDescriptor | undefined): ResumeRunner | undefined {
+		return (
+			(descriptor !== undefined ? this.#descriptorResumeRunners.get(rec.subagentId) : undefined) ??
+			this.#resumeRunner
+		);
 	}
 
 	getResumeDescriptor(subagentId: string, filter?: AsyncJobFilter): ResumeDescriptor | undefined {
@@ -1045,7 +1095,11 @@ export class AsyncJobManager {
 		return { ok: true, status: rec.status };
 	}
 
-	/** Resume a non-running subagent from its sessionFile, optionally injecting a message first. */
+	/**
+	 * Resume a non-running subagent from retained context: an owner-compatible
+	 * descriptor or a legacy session file. Workflow routing keeps `not_found`,
+	 * `context_unavailable`, `no_runner`, and `resume_failed` distinct.
+	 */
 	resumeSubagent(
 		subagentId: string,
 		filter?: AsyncJobFilter,
@@ -1066,8 +1120,11 @@ export class AsyncJobManager {
 			}
 			return { ok: false, status: "queued", reason: "already_queued" };
 		}
-		if (!rec.resumable || !rec.sessionFile) return { ok: false, reason: "context_unavailable" };
-		if (!this.#resolveResumeRunner(rec.subagentId)) return { ok: false, reason: "no_runner" };
+		const descriptor = this.#descriptorForRecord(rec);
+		if (!hasRetainedResumeContext({ resumable: rec.resumable, sessionFile: rec.sessionFile, descriptor })) {
+			return { ok: false, reason: "context_unavailable" };
+		}
+		if (!this.#resolveResumeRunner(rec, descriptor)) return { ok: false, reason: "no_runner" };
 		if (this.getRunningJobs().length >= this.#maxRunningJobs) {
 			const seq = ++this.#resumeSeq;
 			rec.status = "queued";
@@ -1081,12 +1138,13 @@ export class AsyncJobManager {
 			});
 			return { ok: true, queued: true, status: "queued" };
 		}
-		return this.#startResume(rec, message);
+		return this.#startResume(rec, message, descriptor);
 	}
 
 	#startResume(
 		rec: SubagentRecord,
-		message?: string,
+		message: string | undefined,
+		descriptor: ResumeDescriptor | undefined,
 	): { ok: boolean; status?: SubagentLifecycle; jobId?: string; reason?: string } {
 		if (this.#isOwnerSubagentShutdownFenced(rec.ownerId)) {
 			return { ok: false, status: rec.status, reason: "owner_shutdown_in_progress" };
@@ -1095,8 +1153,8 @@ export class AsyncJobManager {
 		// Clear any retained progress from the previous run so a resumed subagent
 		// never renders the prior run's tool/output as live before it emits again.
 		this.#subagentProgress.delete(rec.subagentId);
-		const runner = this.#resolveResumeRunner(rec.subagentId);
-		const newJobId = runner?.(rec.subagentId, message, this.#resumeDescriptors.get(rec.subagentId));
+		const runner = this.#resolveResumeRunner(rec, descriptor);
+		const newJobId = runner?.(rec.subagentId, message, descriptor);
 		if (!newJobId) return { ok: false, reason: "resume_failed" };
 		if (prevJobId && prevJobId !== newJobId) rec.historicalJobIds.push(prevJobId);
 		rec.currentJobId = newJobId;
@@ -1122,7 +1180,7 @@ export class AsyncJobManager {
 				continue;
 			}
 			try {
-				const result = this.#startResume(rec, entry.message);
+				const result = this.#startResume(rec, entry.message, this.#descriptorForRecord(rec));
 				if (result.reason === "owner_shutdown_in_progress") {
 					index += 1;
 					continue;

package/src/capability/index.ts

@@ -259,10 +259,18 @@ export function initializeWithSettings(activeSettings: Settings): void {
 	for (const id of disabled) disabledProviders.add(id);
 }
 
+function assertDisabledProvidersWritable(activeSettings: Settings): void {
+	if (!activeSettings.canWriteDurableConfig()) {
+		throw new Error(
+			"Cannot change settings while config.yml has invalid YAML syntax. Repair config.yml and reload settings.",
+		);
+	}
+}
 /**
  * Persist current disabled providers to settings.
  */
 function persistDisabledProviders(activeSettings: Settings, providers: ReadonlySet<string>): void {
+	assertDisabledProvidersWritable(activeSettings);
 	activeSettings.set("disabledProviders", Array.from(providers));
 }
 

package/src/cli/fast-help.ts

@@ -93,7 +93,7 @@ Available Tools (default-enabled unless noted):
   bash          - Execute bash commands
   edit          - Edit files with find/replace
   write         - Write files (creates/overwrites)
-  grep          - Search file contents
+  search        - Search file contents
   find          - Find files by glob pattern
   lsp           - Language server protocol (code intelligence)
   python        - Execute Python code (requires: ${APP_NAME} setup python)

package/src/cli/plugin-cli.ts

@@ -7,7 +7,19 @@
 import { APP_NAME, getProjectDir } from "@gajae-code/utils";
 import chalk from "chalk";
 import { resolveOrDefaultProjectRegistryPath } from "../discovery/helpers";
-import { installGjcPluginBundle, isGjcPluginBundleSource, readRegistry } from "../extensibility/gjc-plugins";
+import {
+	applyGjcBundleUpdate,
+	bundleIdentity,
+	type GjcBundleIdentity,
+	type GjcBundleSummary,
+	GjcPluginLoadError,
+	getGjcBundle,
+	installGjcBundle,
+	isGjcPluginBundleSource,
+	isGjcPluginSourceShape,
+	listGjcBundles,
+	previewGjcBundleUpdate,
+} from "../extensibility/gjc-plugins";
 import { PluginManager, parseSettingValue, validateSetting } from "../extensibility/plugins";
 import {
 	getInstalledPluginsRegistryPath,
@@ -312,9 +324,118 @@ async function handleDiscover(args: string[], _flags: PluginCommandArgs["flags"]
 	}
 }
 
+/**
+ * Scope-qualified GJC bundle upgrade: re-resolve the stored source, review the
+ * candidate, then apply it as a compare-and-swap. `--dry-run` stops after the
+ * preview. Requires exactly one of `--user` / `--project` because (scope, name)
+ * is the canonical target.
+ */
+async function handleGjcUpgrade(name: string, flags: PluginCommandArgs["flags"]): Promise<void> {
+	if (flags.user === flags.project) {
+		console.error(chalk.red(`GJC bundle upgrade requires exactly one of --user or --project for "${name}".`));
+		process.exit(1);
+	}
+	const scope: "user" | "project" = flags.user ? "user" : "project";
+	const ctx = { cwd: getProjectDir() };
+	const identity = bundleIdentity(scope, name);
+
+	const emitError = (error: { code: string; message: string; recovery?: string }): never => {
+		if (flags.json) console.log(JSON.stringify({ error }, null, 2));
+		else {
+			console.error(chalk.red(`${theme.status.error} ${error.message}`));
+			if (error.recovery) console.error(chalk.dim(`  Try: ${error.recovery}`));
+		}
+		process.exit(3);
+	};
+
+	// Source re-resolution can throw with a cause carrying the raw locator, so
+	// the whole flow reports a stable code instead of the underlying error.
+	try {
+		await runGjcUpgrade(ctx, identity, name, scope, flags, emitError);
+	} catch (err) {
+		const reason = err instanceof GjcPluginLoadError ? err.code : "upgrade_failed";
+		console.error(chalk.red(`${theme.status.error} Failed to upgrade GJC bundle ${name} (${reason})`));
+		process.exit(1);
+	}
+}
+
+async function runGjcUpgrade(
+	ctx: { cwd: string },
+	identity: GjcBundleIdentity,
+	name: string,
+	scope: "user" | "project",
+	flags: PluginCommandArgs["flags"],
+	emitError: (error: { code: string; message: string; recovery?: string }) => never,
+): Promise<void> {
+	const preview = await previewGjcBundleUpdate(ctx, identity);
+	if (!preview.ok) emitError(preview.error);
+	else if (flags.dryRun || !preview.value.changed) {
+		const { changed, candidateVersion, addedSurfaceIds, removedSurfaceIds } = preview.value;
+		if (flags.json) {
+			console.log(
+				JSON.stringify(
+					{
+						status: changed ? "update-available" : "up-to-date",
+						identity,
+						currentVersion: preview.value.current.version,
+						candidateVersion,
+						addedSurfaceIds,
+						removedSurfaceIds,
+					},
+					null,
+					2,
+				),
+			);
+		} else if (!changed) {
+			console.log(chalk.dim(`GJC bundle ${name} (${scope}) is up to date at ${preview.value.current.version}`));
+		} else {
+			console.log(
+				chalk.cyan(`[dry-run] ${name} (${scope}): ${preview.value.current.version} -> ${candidateVersion}`),
+			);
+			if (addedSurfaceIds.length > 0) console.log(chalk.dim(`  + ${addedSurfaceIds.join(", ")}`));
+			if (removedSurfaceIds.length > 0) console.log(chalk.dim(`  - ${removedSurfaceIds.join(", ")}`));
+		}
+	} else {
+		const applied = await applyGjcBundleUpdate(ctx, preview.value.token);
+		if (!applied.ok) emitError(applied.error);
+		else if (flags.json) {
+			console.log(
+				JSON.stringify(
+					{
+						status: applied.value.status,
+						bundle: applied.value.summary,
+						remnantCount: applied.value.remnantCount,
+					},
+					null,
+					2,
+				),
+			);
+		} else {
+			console.log(
+				chalk.green(
+					`${theme.status.success} ${applied.value.status} GJC bundle ${name}@${applied.value.summary.version} (${scope})`,
+				),
+			);
+			if (applied.value.remnantCount > 0) {
+				console.error(chalk.yellow(`  ${applied.value.remnantCount} leftover directory could not be removed`));
+			}
+		}
+	}
+}
+
 async function handleUpgrade(args: string[], flags: PluginCommandArgs["flags"]): Promise<void> {
-	const manager = await makeMarketplaceManager();
 	const pluginId = args[0];
+	// Scope-qualified GJC bundles upgrade through the lifecycle service, never
+	// through the marketplace manager.
+	if (pluginId && (flags.user || flags.project)) {
+		const scope: "user" | "project" = flags.user ? "user" : "project";
+		const existing = await getGjcBundle({ cwd: getProjectDir() }, bundleIdentity(scope, pluginId));
+		if (existing.ok) {
+			await handleGjcUpgrade(pluginId, flags);
+			return;
+		}
+	}
+	const manager = await makeMarketplaceManager();
 	try {
 		if (pluginId) {
 			if (flags.scope) {
@@ -349,6 +470,15 @@ async function handleUpgrade(args: string[], flags: PluginCommandArgs["flags"]):
 	}
 }
 
+/**
+ * Stable, non-identifying reason for an install failure. The raw spec and the
+ * underlying cause can both carry credentials, a query string, or an absolute
+ * home path, so neither is ever printed.
+ */
+function describeInstallFailure(error: unknown): string {
+	return error instanceof GjcPluginLoadError ? error.code : "install_failed";
+}
+
 async function handleInstall(
 	manager: PluginManager,
 	packages: string[],
@@ -374,27 +504,52 @@ async function handleInstall(
 	const knownMarketplaces = new Set((await mktMgr.listMarketplaces()).map(m => m.name));
 
 	for (const spec of packages) {
-		// GJC plugin bundle classifier: a source containing gajae-plugin.json (or a
-		// git/tarball source) routes to the bundle installer BEFORE marketplace/npm.
-		if (await isGjcPluginBundleSource(spec)) {
+		// A GJC bundle is identified by the SHAPE of its source: a filesystem path,
+		// a git locator, or a tarball. npm and marketplace specs are never any of
+		// those, so shape alone separates the two worlds without resolving.
+		//
+		// Shape is checked BEFORE `isGjcPluginBundleSource`, which resolves the
+		// source: a deleted or unreachable GJC source fails that probe and would
+		// otherwise fall through to npm, losing the create-only refusal the
+		// lifecycle owes for an already-installed target.
+		if (isGjcPluginSourceShape(spec) || (await isGjcPluginBundleSource(spec))) {
 			if (flags.user === flags.project) {
 				console.error(
-					chalk.red(`GJC plugin bundle install requires exactly one of --user or --project for "${spec}".`),
+					// The spec can carry credentials or an absolute home path, so name
+					// the missing flag instead of echoing it back.
+					chalk.red("GJC plugin bundle install requires exactly one of --user or --project."),
 				);
 				process.exit(1);
 			}
 			const scope: "user" | "project" = flags.user ? "user" : "project";
 			try {
-				const res = await installGjcPluginBundle(spec, { scope, cwd: process.cwd(), force: flags.force });
+				const res = await installGjcBundle({ cwd: getProjectDir() }, scope, spec);
+				if (!res.ok) {
+					const doc = {
+						error: { code: res.error.code, message: res.error.message, recovery: res.error.recovery },
+					};
+					if (flags.json) console.log(JSON.stringify(doc, null, 2));
+					else {
+						console.error(chalk.red(`${theme.status.error} ${res.error.message}`));
+						if (res.error.recovery) console.error(chalk.dim(`  Try: ${res.error.recovery}`));
+					}
+					process.exit(3);
+				}
+				const { summary } = res.value;
 				if (flags.json) {
-					console.log(JSON.stringify({ name: res.entry.name, status: res.status, scope }, null, 2));
+					console.log(JSON.stringify({ status: res.value.status, bundle: summary }, null, 2));
 				} else {
 					console.log(
-						chalk.green(`${theme.status.success} ${res.status} GJC plugin ${res.entry.name} (${scope})`),
+						chalk.green(
+							`${theme.status.success} installed GJC plugin ${summary.identity.name}@${summary.version} (${scope})`,
+						),
 					);
 				}
 			} catch (err) {
-				console.error(chalk.red(`${theme.status.error} Failed to install GJC plugin ${spec}: ${err}`));
+				// Never echo the raw spec or the underlying cause: either can carry
+				// credentials, a query string, or an absolute home path.
+				const reason = err instanceof GjcPluginLoadError ? err.code : "install_failed";
+				console.error(chalk.red(`${theme.status.error} Failed to install GJC bundle (${reason})`));
 				process.exit(1);
 			}
 			continue;
@@ -414,7 +569,9 @@ async function handleInstall(
 					),
 				);
 			} catch (err) {
-				console.error(chalk.red(`${theme.status.error} Failed to install ${spec}: ${err}`));
+				// The spec can carry credentials, a query string, or an absolute home
+				// path, so report the failure without echoing it or the raw cause.
+				console.error(chalk.red(`${theme.status.error} Failed to install plugin (${describeInstallFailure(err)})`));
 				process.exit(1);
 			}
 			continue;
@@ -449,7 +606,9 @@ async function handleInstall(
 				}
 			}
 		} catch (err) {
-			console.error(chalk.red(`${theme.status.error} Failed to install ${spec}: ${err}`));
+			// The spec can carry credentials, a query string, or an absolute home
+			// path, so report the failure without echoing it or the raw cause.
+			console.error(chalk.red(`${theme.status.error} Failed to install plugin (${describeInstallFailure(err)})`));
 			process.exit(1);
 		}
 	}
@@ -503,8 +662,7 @@ async function handleList(manager: PluginManager, flags: { json?: boolean }): Pr
 	const mktMgr = await makeMarketplaceManager();
 	const mktPlugins = await mktMgr.listInstalledPlugins();
 	const cwd = getProjectDir();
-	const [gjcUser, gjcProject] = await Promise.all([readRegistry("user", cwd), readRegistry("project", cwd)]);
-	const gjcBundles = [...gjcUser.plugins, ...gjcProject.plugins];
+	const gjcBundles: GjcBundleSummary[] = await listGjcBundles({ cwd });
 
 	if (flags.json) {
 		console.log(JSON.stringify({ npm: npmPlugins, marketplace: mktPlugins, gjc: gjcBundles }, null, 2));
@@ -559,9 +717,9 @@ async function handleList(manager: PluginManager, flags: { json?: boolean }): Pr
 		console.log(chalk.bold("GJC Plugin Bundles:\n"));
 		for (const plugin of gjcBundles) {
 			const status = plugin.enabled ? chalk.green(theme.status.enabled) : chalk.dim(theme.status.disabled);
-			const scopeLabel = chalk.dim(` (${plugin.scope})`);
-			const disabledCount = plugin.disabledSurfaceIds.length;
-			const quarantineCount = plugin.quarantine?.length ?? 0;
+			const scopeLabel = chalk.dim(` (${plugin.identity.scope})`);
+			const disabledCount = plugin.surfaces.filter(s => !s.enabled).length;
+			const quarantineCount = plugin.surfaces.filter(s => s.quarantined).length;
 			const detail = [
 				disabledCount > 0 ? `${disabledCount} disabled` : null,
 				quarantineCount > 0 ? `${quarantineCount} quarantined` : null,
@@ -569,7 +727,7 @@ async function handleList(manager: PluginManager, flags: { json?: boolean }): Pr
 				.filter((v): v is string => Boolean(v))
 				.join(", ");
 			console.log(
-				`${status} ${plugin.name}@${plugin.version}${scopeLabel}${detail ? chalk.dim(` — ${detail}`) : ""}`,
+				`${status} ${plugin.identity.name}@${plugin.version}${scopeLabel}${detail ? chalk.dim(` — ${detail}`) : ""}`,
 			);
 		}
 	}

package/src/cli/read-cli.ts

@@ -15,6 +15,7 @@ import { renderError } from "../tools/tool-errors";
 
 export interface ReadCommandArgs {
 	path: string;
+	truncation?: "head" | "last" | "both";
 }
 
 export async function runReadCommand(cmd: ReadCommandArgs): Promise<void> {
@@ -37,7 +38,7 @@ export async function runReadCommand(cmd: ReadCommandArgs): Promise<void> {
 	const tool = wrapToolWithMetaNotice(new ReadTool(session));
 
 	try {
-		const result = await tool.execute("gjc-read", { path: cmd.path });
+		const result = await tool.execute("gjc-read", { path: cmd.path, truncation: cmd.truncation });
 
 		for (const block of result.content) {
 			if (block.type === "text") {

package/src/cli.ts

@@ -65,6 +65,7 @@ export const commands: CommandEntry[] = [
 	{ name: "migrate", load: () => import("./commands/migrate").then(m => m.default) },
 	{ name: "rlm", load: () => import("./commands/rlm").then(m => m.default) },
 	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
+	{ name: "read", load: () => import("./commands/read").then(m => m.default) },
 	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
 	{ name: "completion", load: () => import("./commands/completion").then(m => m.default) },
 	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },

package/src/commands/deep-interview.ts

@@ -2,8 +2,22 @@ import { Command, Flags } from "@gajae-code/utils/cli";
 import { runNativeDeepInterviewCommand } from "../gjc-runtime/deep-interview-runtime";
 
 export default class DeepInterview extends Command {
-	static description =
-		"Run native GJC deep-interview workflow. Use `draft` for editable CLI-owned mutation inputs; JSON repair verbs are compatibility-only.";
+	static description = `Run native GJC deep-interview workflow.
+
+All deep-interview state operations go through this command — no gjc state needed:
+  read                Print the persisted envelope, revision, content sha, and any pending draft
+  write               One-shot incremental JSON merge into state (--reset replaces; the locked
+                      intent contract survives a reset)
+  stage               Stage one JSON transition draft (--for <transition> --input '<json>'|@file)
+  check               Dry-run the staged draft against current state (same merge apply performs)
+  apply               Commit the staged draft with runtime-owned revision+sha CAS
+  discard             Remove the pending draft
+  clear               Clear deep-interview state for the session (lifecycle passthrough)
+  handoff             Hand off to the next workflow skill (lifecycle passthrough)
+
+Ambiguity is runtime-owned: apply/write derive current_ambiguity from the latest valid scored
+round and clamp it to the deterministic floor. Sessions resolve from --session-id, payload
+session_id, or GJC_SESSION_ID.`;
 	static strict = false;
 	static flags = {
 		quick: Flags.boolean({ description: "Seed a quick deep-interview run" }),
@@ -15,6 +29,11 @@ export default class DeepInterview extends Command {
 		"session-id": Flags.string({
 			description: "Route state/spec handoff through a session-scoped .gjc/_session-{sessionid} directory",
 		}),
+		input: Flags.string({ description: "JSON payload (or @file) for the write/stage verbs" }),
+		for: Flags.string({
+			description: "Transition for stage: initialize-context | record-round | update-facts | merge-state",
+		}),
+		reset: Flags.boolean({ description: "With write: replace state instead of incremental merge" }),
 		write: Flags.boolean({ description: "Persist a final deep-interview spec through the sanctioned GJC CLI/API" }),
 		stage: Flags.string({ description: 'Spec stage for --write (currently "final")' }),
 		slug: Flags.string({ description: "Safe slug for .gjc/_session-{sessionid}/specs/deep-interview-<slug>.md" }),
@@ -27,13 +46,14 @@ export default class DeepInterview extends Command {
 		json: Flags.boolean({ description: "Output JSON" }),
 	};
 	static examples = [
-		'$ gjc deep-interview --trace --standard "<idea>" --json',
-		"$ gjc deep-interview draft create --for initialize-context --session-id <id> --json",
-		"$ gjc deep-interview draft edit --draft-id <id> --expected-draft-revision 1 --op set --path /type --value greenfield --json",
-		"$ gjc deep-interview draft check --draft-id <id> --json",
-		"$ gjc deep-interview initialize-context --draft-id <id> --expected-draft-revision <n> --json",
-		"$ gjc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md --json",
-		"$ gjc deep-interview inspect --session-id <id> --selector summary --json",
+		'$ gjc deep-interview --trace --standard "<idea>"',
+		"$ gjc deep-interview read --json",
+		'$ gjc deep-interview write --input \'{"state":{"threshold":0.05}}\' --json',
+		'$ gjc deep-interview stage --for record-round --input \'{"state":{"rounds":[{"round":1,"round_key":"r1"}]}}\' --json',
+		"$ gjc deep-interview check --json",
+		"$ gjc deep-interview apply --json",
+		"$ gjc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md",
+		"$ gjc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md --deliberate",
 	];
 
 	async run(): Promise<void> {

package/src/commands/harness.ts

@@ -14,6 +14,7 @@ import { existsSync, readFileSync } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { Args, Command, Flags } from "@gajae-code/utils/cli";
+import { $credentialEnv } from "@gajae-code/utils/env";
 import {
 	GJC_TMUX_OWNER_GENERATION_ENV,
 	GJC_TMUX_OWNER_SERVER_KEY_ENV,
@@ -565,20 +566,42 @@ function ownerIsolationPlatform(): NodeJS.Platform {
 		: "linux";
 }
 
+/**
+ * Operator override for the process-start probe command, resolved from trusted
+ * environment sources only.
+ *
+ * The result is spawned, so whatever can set it chooses which binary runs.
+ * `$env` merges the caller's `cwd/.env` into `process.env`, so reading it there
+ * would let repository content pick the command; resolve it the same way
+ * provider credentials are (launching shell plus GJC/user-owned `.env` files,
+ * never the project `.env`). A malformed override stays fatal rather than
+ * silently falling back to `ps`, matching the previous behavior.
+ */
+type ProcessStartCommandOverride = { kind: "none" } | { kind: "invalid" } | { kind: "command"; command: string[] };
+
+function processStartCommandOverride(): ProcessStartCommandOverride {
+	const configured = $credentialEnv("GJC_HARNESS_PROCESS_START_COMMAND");
+	if (!configured) return { kind: "none" };
+	try {
+		const parsed = JSON.parse(configured) as unknown;
+		if (!Array.isArray(parsed) || parsed.length === 0 || parsed.some(value => typeof value !== "string" || !value))
+			return { kind: "invalid" };
+		return { kind: "command", command: parsed as string[] };
+	} catch {
+		return { kind: "invalid" };
+	}
+}
+
+/** Test seam: the process-start command override as resolved from trusted env. */
+export function processStartCommandOverrideForTest(): ProcessStartCommandOverride {
+	return processStartCommandOverride();
+}
+
 function portableProcessStartTime(pid: number): string | null {
 	if (process.platform === "linux") return null;
-	const configured = process.env.GJC_HARNESS_PROCESS_START_COMMAND;
-	let command: string[] = ["ps", "-o", "lstart=", "-p"];
-	if (configured) {
-		try {
-			const parsed = JSON.parse(configured) as unknown;
-			if (!Array.isArray(parsed) || parsed.length === 0 || parsed.some(value => typeof value !== "string" || !value))
-				return null;
-			command = parsed;
-		} catch {
-			return null;
-		}
-	}
+	const override = processStartCommandOverride();
+	if (override.kind === "invalid") return null;
+	const command: string[] = override.kind === "command" ? override.command : ["ps", "-o", "lstart=", "-p"];
 	const result = Bun.spawnSync([...command, String(pid)], {
 		stdout: "pipe",
 		stderr: "ignore",