@gajae-code/coding-agent 0.11.11 → 0.12.0

package/src/modes/utils/ui-helpers.ts

@@ -1,6 +1,6 @@
 import type { AgentMessage } from "@gajae-code/agent-core";
 import type { AssistantMessage, ImageContent, Message } from "@gajae-code/ai";
-import { type Component, Spacer, Text, TruncatedText, type TUI, truncateToWidth } from "@gajae-code/tui";
+import { type Component, Loader, Spacer, Text, TruncatedText, type TUI, truncateToWidth } from "@gajae-code/tui";
 import { settings } from "../../config/settings";
 import { resolveSubskillActivationForSkillInvocation } from "../../extensibility/gjc-plugins";
 import { buildSkillPromptMessage, parseSkillInvocations } from "../../extensibility/skills";
@@ -85,6 +85,99 @@ export function prepareTranscriptRebuild(ui: TUI, policy: TranscriptRebuildPolic
 	if (policy === "replace-identity") ui.resetViewportAnchorIntent();
 	else ui.prepareViewportAnchorForTranscriptRebuild();
 }
+
+export const RESUME_PROGRESS_COMMIT_TIMEOUT_MS = 250;
+
+export interface ResumeProgressLease {
+	readonly committed: Promise<boolean>;
+	clear(): void;
+}
+
+/**
+ * Mount a resume loader on the live status rail and wait for its render generation
+ * to commit before session I/O begins. The commit is advisory: a stopped or
+ * unavailable terminal resolves false and callers continue without blocking.
+ *
+ * Fail open (no-op lease, committed=false) when the status rail or UI lacks the
+ * child-mutation/render-commit surface required to mount progress. Headless and
+ * minimal controller contexts keep resume/migration semantics; full interactive
+ * TUI containers retain progress-before-switch.
+ */
+export function acquireResumeProgressLease(
+	ctx: Pick<InteractiveModeContext, "ui" | "statusContainer">,
+): ResumeProgressLease {
+	if (!canMountResumeProgressLease(ctx)) {
+		return {
+			committed: Promise.resolve(false),
+			clear(): void {},
+		};
+	}
+
+	const statusContainer = ctx.statusContainer as ResumeProgressStatusSurface;
+	const ui = ctx.ui as ResumeProgressUiSurface;
+	const loader = new Loader(
+		ui,
+		spinner => theme?.fg?.("accent", spinner) ?? spinner,
+		message => theme?.fg?.("muted", message) ?? message,
+		"Resuming session…",
+	);
+	statusContainer.addChild(loader);
+	const generation = ui.requestRenderWithGeneration(false, "resume-progress");
+	let active = true;
+	const committed = ui.waitForRenderCommit(generation, RESUME_PROGRESS_COMMIT_TIMEOUT_MS).catch(() => false);
+	return {
+		committed,
+		clear(): void {
+			if (!active) return;
+			active = false;
+			if (statusContainer.children.includes(loader)) statusContainer.removeChild(loader);
+			else loader.stop();
+			ui.requestRender(false, "resume-progress-clear");
+		},
+	};
+}
+
+type ResumeProgressStatusSurface = {
+	addChild: (child: Component) => void;
+	removeChild: (child: Component) => void;
+	children: Component[];
+};
+
+type ResumeProgressUiSurface = InteractiveModeContext["ui"] & {
+	requestRenderWithGeneration: (force?: boolean, source?: string) => number;
+	waitForRenderCommit: (generation: number, timeoutMs?: number) => Promise<boolean>;
+	requestRender: (force?: boolean, source?: string) => void;
+};
+
+function canMountResumeProgressLease(ctx: Pick<InteractiveModeContext, "ui" | "statusContainer">): boolean {
+	const status = ctx.statusContainer as
+		| Partial<{
+				addChild: unknown;
+				removeChild: unknown;
+				children: unknown;
+		  }>
+		| null
+		| undefined;
+	const ui = ctx.ui as
+		| Partial<{
+				requestRenderWithGeneration: unknown;
+				waitForRenderCommit: unknown;
+				requestRender: unknown;
+		  }>
+		| null
+		| undefined;
+
+	return (
+		!!status &&
+		typeof status.addChild === "function" &&
+		typeof status.removeChild === "function" &&
+		Array.isArray(status.children) &&
+		!!ui &&
+		typeof ui.requestRenderWithGeneration === "function" &&
+		typeof ui.waitForRenderCommit === "function" &&
+		typeof ui.requestRender === "function"
+	);
+}
 type TextBlock = { type: "text"; text: string };
 interface RenderInitialMessagesOptions {
 	preserveExistingChat?: boolean;

package/src/prompts/agents/architect.md

@@ -37,11 +37,19 @@ You may receive a forked parent-conversation snapshot as background. Your read-o
 {{restrictedBash}}
 - Never approve code or plans you have not grounded in inspected files.
 - Never give generic advice detached from this codebase.
-- Never approve CRITICAL or HIGH severity issues.
+- Never approve carryover CRITICAL or HIGH severity issues (raised in a prior pass and still unresolved). A fresh CRITICAL/HIGH minted from pass 2 on previously-approved ground blocks only with an explicit why-not-visible-earlier justification (rule 2); without that justification, record it as a non-blocking caveat with its severity noted. On pass 1 every CRITICAL/HIGH blocks.
 - Do not skip spec compliance to jump to style nitpicks.
 - Be constructive: explain why an issue matters and how to fix it or strengthen the design.
 </constraints>
 
+<re_review_ratchet>
+- Rule 1 (delta-only): from pass 2, review only the delta against the prior pass plus the resolution of previously raised findings; do not re-litigate previously-approved ground. The prior pass is identified by the re-review context bundle: prior reviewed-plan path, prior same-lane review path, and the explicit run-level pass number supplied in the assignment.
+- Rule 2 (novelty justification): a new blocker on previously-reviewed ground requires an explicit "why this was not visible in the prior pass" justification (e.g. revealed by a fix, new file evidence); without it, demote to a non-blocking caveat.
+- Rule 3 (verdict monotonicity): once all blockers from the prior pass are resolved, neither Architectural Status (`CLEAR`/`WATCH`/`BLOCK`) nor Code Review Recommendation (`APPROVE`/`COMMENT`/`REQUEST CHANGES`) may worsen absent a rule-2-justified new blocker.
+- Rule 4 (severity discipline): carryover CRITICAL or HIGH severity issues (raised in a prior pass and still unresolved) remain blocking regardless of pass number. A fresh CRITICAL/HIGH minted from pass 2 on previously-approved ground blocks only with an explicit why-not-visible-earlier justification (rule 2); without that justification, record it as a non-blocking caveat with its severity noted. On pass 1 every CRITICAL/HIGH blocks.
+- Rule 5 (counter-review awareness): From pass 2 your output is counter-reviewed by Critic for over-engineering and unnecessary scope expansion; unjustified scope inflation is flagged as a review defect and does not force revision passes. On pass 2+, do not broaden scope, add options, or demand synthesis beyond what resolves prior findings; constructive synthesis (Stage 3) stays full-strength on pass 1 only.
+</re_review_ratchet>
+
 <review_stages>
 1. Understand the request, spec, plan, or diff.
 2. Gather file-backed evidence.

package/src/prompts/agents/critic.md

@@ -32,6 +32,15 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 - For consensus planning, reject shallow alternatives, driver contradictions, vague risks, weak verification, missing acceptance criteria, or under-specified areas needing expansion before execution.
 </constraints>
 
+<re_review_ratchet>
+- Rule 1 (delta-only): from pass 2, review only the delta against the prior pass plus the resolution of previously raised findings; do not re-litigate previously-approved ground. The prior pass is identified by the re-review context bundle (WI-3): prior reviewed-plan path, prior same-lane review path, and the explicit run-level pass number supplied in the assignment.
+- Rule 2 (novelty justification): a new blocker on previously-reviewed ground requires an explicit "why this was not visible in the prior pass" justification (e.g. revealed by a fix, new file evidence); without it, demote to a non-blocking caveat.
+- Rule 3 (verdict monotonicity): once all blockers from the prior pass are resolved, the verdict must not worsen (e.g. ITERATE -> REJECT) absent a rule-2-justified new blocker.
+- Rule 4 (severity discipline): carryover blockers (raised in a prior pass, still unresolved) remain blocking regardless of pass number. A fresh high-severity concern minted from pass 2 on previously-approved ground follows rule 2: it blocks only with the why-not-visible-earlier justification, else it is recorded as a non-blocking caveat with severity noted.
+- Rule 5 (counter-review duty): from pass 2, Critic also reviews the Architect output (routed via the context bundle) for over-engineering and unnecessary scope expansion; flag inflation as a review defect and do NOT convert unjustified Architect demands into ITERATE — inflating demands must not force revision passes.
+- Enrichment lane ("spec too thin — expand") preserved verbatim but justification-gated from pass 2: expansion requests on already-reviewed ground need the rule-2 justification.
+</re_review_ratchet>
+
 <execution_loop>
 1. Read the plan and referenced artifacts.
 2. Extract and verify file references.

package/src/prompts/system/system-prompt.md

@@ -24,7 +24,6 @@ Optimize for correctness first, maintainability second, and brevity third. Prefe
 - Informational questions are answer-only/read-only unless the user explicitly requests a change, command, or execution.
 - Vague requirements use `/skill:deep-interview`: a requirements-only workflow that must not mutate product code. Its spec hands off as deep-interview → ralplan consensus → pending approval → separately approved execution.
 - Clear work with non-trivial architecture or sequencing risk uses `/skill:ralplan --deliberate` and stops pending approval.
-- Deep-interview state is runtime-owned: diagnose with `gjc deep-interview sanity-check`, inspect only the affected bounded selector, and repair through typed operations using CLI-generated/edited drafts (`draft create|edit|show|check|rebase|discard`) consumed with `--draft-id`. Inline JSON request flags are compatibility-only; normal flow must never reconstruct a payload or full envelope.
 - Use `/skill:ultragoal` for durable goal ledgers and `/skill:team` for approved coordinated persistent work.
 - Delegate large implementation slices to `executor`; use `planner`, `architect`, or `critic` for bounded planning and review.
 - Active skills are authoritative: never ignore an invoked skill; read the full skill text and follow it exactly.

package/src/prompts/tools/read.md

@@ -9,12 +9,13 @@ Read files, directories, archives, SQLite databases, images, documents, internal
 ## Parameters
 
 - `path` — required. Local path, internal URI (`agent://`, `artifact://`, `rule://`, `local://`), or URL. Append `:<sel>` for line ranges, raw mode, or special modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).
+- `truncation` — optional `head` | `last` | `both`; selects which end of an over-budget result to retain. Configured default: {{TRUNCATION_DEFAULT}} (factory default: `last`); non-file routes such as URLs, directories and converted documents default to `head`. A line-range selector still bounds the selection — this only picks which end of that selection survives the byte/line cap. SQLite row queries page via their own `limit`/`offset` and ignore it.
 
-## Selectors
 
+## Selectors
 Append `:<sel>` to `path`. The bare path falls back to the default mode.
 
-- _(none)_ — parseable code → structural summary (signatures kept, bodies elided); other files → read from the start (up to {{DEFAULT_LIMIT}} lines).
+- _(none)_ — parseable code → structural summary (signatures kept, bodies elided); a plain text file → a bounded receipt of about {{RECEIPT_LINES}} lines or {{RECEIPT_KIB}} KiB, whichever is smaller; the configured truncation direction is {{TRUNCATION_DEFAULT}} (factory default: last). Line+hash anchors keep their real file line numbers and a footer names the omitted range. Archive members use the larger {{DEFAULT_MAX_LINES}}-line / 50 KiB budget. Converted documents, notebooks, URLs and directory listings still start from the beginning.
 - `:50` / `:50-` — read from line 50 onward.
 - `:50-200` — lines 50–200 inclusive.
 - `:50+150` — 150 lines starting at line 50.
@@ -39,6 +40,7 @@ Append `:<sel>` to `path`. The bare path falls back to the default mode.
   `[NN lines across MM elided regions; read <path>:raw or a line range like <path>:1-9999 for verbatim content]`
 
   If the elided body is what you actually need, re-issue the **exact selector the footer names**. NEVER guess what's inside `..` / `…` — those markers carry no content.
+- Directional windows identify the retained first/last lines and the omitted range; use the `re-read <path>:1-<total>` or `:raw` hint in the footer to recover the full content.
 
 # Documents & Notebooks
 

package/src/runtime-mcp/smithery-auth.ts

@@ -2,9 +2,18 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isEnoent, logger } from "@gajae-code/utils";
 import { getAgentDir } from "@gajae-code/utils/dirs";
+import { $credentialEnv } from "@gajae-code/utils/env";
 
 const SMITHERY_AUTH_FILENAME = "smithery.json";
-const SMITHERY_URL = process.env.SMITHERY_URL || "https://smithery.ai";
+/**
+ * Smithery web origin, from trusted environment sources only.
+ *
+ * This origin serves the CLI auth session and the verification URL the user is
+ * sent to, so whatever can set it can drive the login flow. `$env` merges the
+ * caller's `cwd/.env` into `process.env`, so reading it there would let
+ * repository content redirect that flow.
+ */
+const SMITHERY_URL = $credentialEnv("SMITHERY_URL") || "https://smithery.ai";
 
 type SmitheryCliAuthSession = {
 	sessionId: string;
@@ -31,6 +40,11 @@ function normalizeApiKey(value: string | undefined): string | undefined {
 	return trimmed.length > 0 ? trimmed : undefined;
 }
 
+/** Test seam: the Smithery origin and env API key as resolved from trusted env. */
+export function resolveSmitheryEnvForTest(): { url: string; apiKey: string | undefined } {
+	return { url: SMITHERY_URL, apiKey: normalizeApiKey($credentialEnv("SMITHERY_API_KEY")) };
+}
+
 export function getSmitheryLoginUrl(): string {
 	return SMITHERY_URL;
 }
@@ -62,7 +76,8 @@ export async function pollSmitheryCliAuthSession(
 }
 
 export async function getSmitheryApiKey(): Promise<string | undefined> {
-	const envKey = normalizeApiKey(process.env.SMITHERY_API_KEY);
+	// Trusted sources only: this key authenticates every Smithery API call.
+	const envKey = normalizeApiKey($credentialEnv("SMITHERY_API_KEY"));
 	if (envKey) return envKey;
 
 	const authPath = getSmitheryAuthPath();

package/src/runtime-mcp/smithery-connect.ts

@@ -1,4 +1,14 @@
-const SMITHERY_API_BASE_URL = (process.env.SMITHERY_API_URL || "https://api.smithery.ai").replace(/\/+$/, "");
+import { $credentialEnv } from "@gajae-code/utils/env";
+
+/**
+ * Smithery API base, from trusted environment sources only.
+ *
+ * Every request to this base carries `Authorization: Bearer <apiKey>` and the
+ * `/connect` routes return the connection records the agent consumes, so
+ * whatever can set it receives the key and supplies those records. `$env` merges
+ * the caller's `cwd/.env` into `process.env`.
+ */
+const SMITHERY_API_BASE_URL = ($credentialEnv("SMITHERY_API_URL") || "https://api.smithery.ai").replace(/\/+$/, "");
 
 export class SmitheryConnectError extends Error {
 	status: number;

package/src/sdk/broker/lifecycle.ts

@@ -5,7 +5,7 @@ import * as fs from "node:fs/promises";
 import path from "node:path";
 import type { NativeExactUnlinkResult } from "@gajae-code/natives";
 import * as native from "@gajae-code/natives";
-import { resolveEquivalentPath } from "@gajae-code/utils";
+import { $credentialEnv, resolveEquivalentPath } from "@gajae-code/utils";
 
 import {
 	isModelProfileError,
@@ -706,12 +706,31 @@ async function reconcileReadyScope(broker: Broker, id: string, scope: string | u
 	});
 }
 
+/**
+ * Operator override for the session-host command, resolved from trusted
+ * environment sources only.
+ *
+ * The result is spawned directly, so whatever can set it chooses which binary
+ * the broker runs. `$env` merges the caller's `cwd/.env` into `process.env`, so
+ * reading it there would let repository content replace the session host;
+ * resolve it the same way provider credentials are (launching shell plus
+ * GJC/user-owned `.env` files, never the project `.env`).
+ */
+function sdkSessionCommandOverride(): { file: string; args: string[] } | undefined {
+	const configured = $credentialEnv("GJC_SDK_SESSION_COMMAND");
+	if (!configured) return undefined;
+	const [file, ...args] = configured.trim().split(/\s+/);
+	return file ? { file, args } : undefined;
+}
+
+/** Test seam: the session-host command override as resolved from trusted env. */
+export function sdkSessionCommandOverrideForTest(): { file: string; args: string[] } | undefined {
+	return sdkSessionCommandOverride();
+}
+
 function command(broker: Broker): LifecycleCommand {
-	const configured = process.env.GJC_SDK_SESSION_COMMAND;
-	if (configured) {
-		const [file, ...args] = configured.trim().split(/\s+/);
-		if (file) return { file, args };
-	}
+	const configured = sdkSessionCommandOverride();
+	if (configured) return configured;
 	return lifecycleCommandResolversForTest.get(broker)?.() ?? resolveSdkInternalSpawnCommand("session-host-internal");
 }
 

package/src/sdk/bus/control-drain-lease.ts

@@ -0,0 +1,104 @@
+/**
+ * Ordering seam for an in-band SDK identity transition.
+ *
+ * A request arrives through predecessor A, so a successful terminal response cannot
+ * be published until successor B is ready. Native builds may provide a true
+ * send-only connection lease; source/dev builds use the conservative fallback in
+ * which the predecessor server remains alive until the terminal write completes.
+ */
+
+export type TerminalSendOutcome = "written" | "disconnected" | "write_failed";
+
+/** Fence/capability hooks may return false to reject; undefined means ok. */
+export type IdentityControlGateResult = boolean | undefined;
+export type IdentityControlGate = () => IdentityControlGateResult | Promise<IdentityControlGateResult>;
+
+export interface IdentityControlSuccessPathInput {
+	/** Fence predecessor inbound work. The fence must not close its response writer. */
+	fence: IdentityControlGate;
+	/** Optional explicit proof that the predecessor writer is still usable. */
+	ensurePredecessorSendCapable?: IdentityControlGate;
+	/** Start successor B and resolve only after its public endpoint is ready. */
+	startSuccessor: () => Promise<void>;
+	/** Write and flush either the success or non-success terminal response. */
+	sendTerminal: () => Promise<TerminalSendOutcome>;
+	/** Release predecessor A after the terminal response has settled. */
+	stopPredecessor: () => Promise<void>;
+	/** Set only when a caller cannot use the retained-writer fallback. */
+	requireNativeControlDrain?: boolean;
+}
+
+export interface IdentityControlTerminalPathInput {
+	fenceInbound: IdentityControlGate;
+	ensurePredecessorSendCapable?: IdentityControlGate;
+	startSuccessorReady: () => Promise<void>;
+	sendTerminal: () => Promise<TerminalSendOutcome>;
+	stopPredecessor: () => Promise<void>;
+	requireNativeControlDrain?: boolean;
+}
+
+/**
+ * Probe the loaded native addon, never an environment flag or a TypeScript shim.
+ * Older/source installs intentionally report false so callers can select the
+ * retained-writer fallback or fail closed when detach is mandatory.
+ */
+export function isNativeControlDrainAvailable(): boolean {
+	try {
+		// Keep the addon lazy: importing the bus must continue to work without a
+		// compiled native artifact (tests and source distributions do that often).
+		// eslint-disable-next-line @typescript-eslint/no-require-imports
+		const natives = require("@gajae-code/natives") as {
+			NotificationServer?: {
+				prototype?: Record<string, unknown>;
+			};
+		};
+		const prototype = natives.NotificationServer?.prototype;
+		return (
+			typeof prototype?.acquireControlDrain === "function" &&
+			typeof prototype?.sendTerminalAndWait === "function" &&
+			typeof prototype?.closeControlDrain === "function"
+		);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Run the only safe ordering for a successful identity-control response.
+ *
+ * The `finally` is deliberately around both successor startup and terminal
+ * delivery: a failed startup must not leave the fenced predecessor alive, and a
+ * failed/disconnected terminal write must still release it. When native detach
+ * is unavailable the caller is expected to keep A's server up (not call
+ * `stopAndWait`) until `sendTerminal` settles.
+ */
+export async function runIdentityControlSuccessPath(
+	input: IdentityControlSuccessPathInput,
+): Promise<TerminalSendOutcome> {
+	if (input.requireNativeControlDrain && !isNativeControlDrainAvailable())
+		throw new Error("SDK identity control requires the native control-drain lease.");
+
+	if ((await input.fence()) === false) throw new Error("SDK identity control predecessor fence was not acquired.");
+	if ((await input.ensurePredecessorSendCapable?.()) === false)
+		throw new Error("SDK identity control predecessor writer is not send-capable.");
+	try {
+		await input.startSuccessor();
+		return await input.sendTerminal();
+	} finally {
+		await input.stopPredecessor();
+	}
+}
+
+/** Compatibility spelling used by the host wiring design notes. */
+export async function runIdentityControlTerminalPath(
+	input: IdentityControlTerminalPathInput,
+): Promise<TerminalSendOutcome> {
+	return runIdentityControlSuccessPath({
+		fence: input.fenceInbound,
+		ensurePredecessorSendCapable: input.ensurePredecessorSendCapable,
+		startSuccessor: input.startSuccessorReady,
+		sendTerminal: input.sendTerminal,
+		stopPredecessor: input.stopPredecessor,
+		requireNativeControlDrain: input.requireNativeControlDrain,
+	});
+}