@gajae-code/coding-agent 0.11.11 → 0.12.1

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/agent-fragments/ralplan-persistence.md

@@ -1,6 +1,7 @@
 Persistence (ralplan runs only):
-- Only when the assignment references a ralplan stage or `stage_n`, persist the full artifact through:
+- Only when the assignment references a ralplan stage or `stage_n`, it must also provide the ralplan owner `session_id` and `run_id`. If either identifier is missing, do not persist; return a compact error asking the caller to supply both.
+- Persist the full artifact through:
 
-  gjc ralplan --write --stage {{stage}} --stage_n <N> --artifact-env GJC_RALPLAN_ARTIFACT --json
+  gjc ralplan --write --session-id <owner-session-id> --run-id <run-id> --stage {{stage}} --stage_n <N> --artifact-env GJC_RALPLAN_ARTIFACT --json
 
-  Use the assignment-provided `stage_n`; on a duplicate-write error retry with the incremented N. Return the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) and the role's compact verdict only. Otherwise, do not call `gjc ralplan --write`; return the full result in `yield.result.data`.
+  Use the assignment-provided owner `session_id`, `run_id`, and `stage_n`; never substitute the role subagent's own session id. On a duplicate-write error retry with the incremented N. Return the write receipt (`session_id`, `run_id`, `path`, `sha256`, `stage`, `stage_n`) and the role's compact verdict only. Otherwise, do not call `gjc ralplan --write`; return the full result in `yield.result.data`.

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/eager-todo.md

@@ -2,11 +2,15 @@
 Before substantive work, create a phased todo.
 
 You MUST call `todo_write` first in this turn.
-You MUST initialize the todo list with a single `init` op.
+Your call MUST use the top-level `ops` array with exactly one `init` operation.
+The `init` operation MUST contain `list`, whose entries each have a unique `phase` and an `items` array of task strings.
+Use this canonical shape:
+```json
+{"ops":[{"op":"init","list":[{"phase":"Investigation","items":["Locate relevant source and existing tests","Reproduce failure with focused contract test"]},{"phase":"Implementation","items":["Apply root cause fix across callsites"]},{"phase":"Verification","items":["Run focused tests and static checks"]}]}]}
+```
 You MUST cover the entire request from investigation through implementation and verification — not just the next immediate step.
-Task descriptions MUST be specific. A future turn MUST execute them without re-planning.
-You MUST keep task `content` to a short label (5-10 words). Put file paths, implementation steps, and specifics in `details`.
-You MUST keep exactly one task `in_progress` and all later tasks `pending`.
+Task strings MUST be specific, unique labels of 5-10 words. A future turn MUST execute them without re-planning.
+The tool automatically promotes the first task after initialization. Add extra context later with a separate `note` operation only when needed.
 
 After `todo_write` succeeds, continue the request in the same turn.
 Do not call `todo_write` again unless task state materially changed.

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

@@ -22,13 +22,13 @@ Optimize for correctness first, maintainability second, and brevity third. Prefe
 - Clear, low-risk implementation requests use direct tools and focused verification; do not invoke workflows or role agents for ceremony. Small verification needs do not turn a clear request into a planning workflow.
 - Ambiguous implementation asks with a missing target, scope, acceptance criteria, or safety boundary require clarification or the appropriate planning workflow before mutation.
 - 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.
+- 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 → final receipt → approval or valid non-off runtime admission → separately authorized execution.
+- Clear work with non-trivial architecture or sequencing risk uses `/skill:ralplan --deliberate`; reconciliation must persist its final receipt before choosing approval or an admitted handoff. A valid non-off final runtime receipt enters the existing handoff chain; otherwise it stops pending approval.
 - 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.
+- An explicit user request to use a worktree (for example, "use worktree") overrides direct editing: delegate implementation through `task` with `isolated: true`. This is the in-session counterpart of launching `gjc --worktree`; if task isolation is unavailable, report that conflict instead of editing in the parent session.
 - Active skills are authoritative: never ignore an invoked skill; read the full skill text and follow it exactly.
-- Before explicit execution approval, planning and interview workflows NEVER edit product source, run mutating shell commands, commit, push, open PRs, or delegate implementation.
+- Before explicit execution approval or a valid non-off ralplan final runtime receipt, planning and interview workflows NEVER edit product source, run mutating shell commands, commit, push, open PRs, or delegate implementation.
 </routing>
 </gjc-runtime>
 {{/unless}}
@@ -83,8 +83,14 @@ Use tools whenever they materially improve correctness, completeness, or groundi
 
 {{#if toolDiscoveryActive}}
 <tool-discovery>
-Use `{{toolRefs.search_tool_bm25}}` to activate hidden tools when a purpose-built capability would improve the task; then call the activated tool. Essential tools stay loaded up front.
+Use `{{toolRefs.search_tool_bm25}}` to activate hidden tools when a purpose-built capability would improve the task; then call the activated tool. Activation makes a tool available, but does not perform its action. Essential tools stay loaded up front.
 Discoverable capabilities include browser automation, scheduling, debugging, and external integrations.
+{{#has tools "task"}}
+For requested subagents, delegation, or independent parallel lanes, call `{{toolRefs.task}}` before saying agents are running.
+{{else}}
+For requested subagents, delegation, or independent parallel lanes, search for `subagent delegation` before saying agents are running.
+{{/has}}
+Do not claim a web search, browser action, integration, or subagent ran without that tool's result.
 </tool-discovery>
 {{/if}}
 

package/src/prompts/tools/bash.md

@@ -44,13 +44,13 @@ Use it only for sanctioned GJC workflow CLI persistence or state read/write/cont
 {{else}}
 - Use bash only for terminal operations that dedicated tools do not cover.
 {{/when}}
-- Never pipe through `| head -n N` or `| tail -n N` — output is already truncated with the full result available via `artifact://<id>`.
+- Never pipe through `| head -n N` or `| tail -n N` — output is already truncated. Recover omitted output only when the result includes an `artifact://<id>` footer or metadata reference; truncation without a reference leaves the visible output incomplete with no recoverable artifact.
 - Never redirect with `2>&1` or `2>/dev/null` — stdout and stderr are already merged.
 </critical>
 
 <output>
 - Returns output and exit code.
-- Truncated output is retrievable from `artifact://<id>` (linked in metadata)
+- Truncated output is recoverable only when the result includes an `artifact://<id>` footer or metadata reference; truncation evidence without such a reference means the visible output is incomplete and no artifact is recoverable.
 - Exit codes shown on non-zero exit
 </output>
 
@@ -64,6 +64,6 @@ Use it only for sanctioned GJC workflow CLI persistence or state read/write/cont
 
 # Output minimizer
 
-- Bash stdout/stderr may be rewritten before you see it: long output is head/tail truncated, and test/lint runners (e.g. `bun test`, `cargo test`, ESLint) are passed through heuristic filters that drop noise and keep failures.
-- When the minimizer changes the visible text, the tool appends a `[raw output: artifact://<id>]` footer pointing at the **full untouched capture**. If a run looks suspicious (e.g. only a version banner) or you need the exact bytes, read that artifact.
-- If no footer is present, what you see is what the command actually emitted.
+- Bash stdout/stderr may be rewritten before you see it: long output keeps only the last 1 KiB by default to reduce noise and input-token use. Explicit `tools.artifactTailBytes` / `tools.artifactHeadBytes` settings can set the tail budget or retain both ends. Prefer focused commands and dedicated `search`/`find` tools over producing broad output. Test/lint runners (e.g. `bun test`, `cargo test`, ESLint) are also passed through heuristic filters that drop noise and keep failures.
+- When the local minimizer changes visible text, successful artifact storage appends a footer containing an `artifact://<id>` reference. Complete artifacts are labeled as full output; hard-capped artifacts report omitted bytes instead. If artifact allocation/storage is unavailable before a writer/save operation is attempted, truncation may have no reference or diagnostic. If an artifact writer/save operation is attempted and fails, a bounded diagnostic is emitted without inventing an artifact URI.
+- ACP/client-terminal output can arrive already truncated from the beginning. Treat any truncation notice or metadata as evidence that the visible tail is incomplete. Recover omitted output only when an `artifact://` footer or metadata reference is present; truncation evidence without a reference means the visible output is incomplete and no artifact is recoverable. Output with neither truncation evidence nor an artifact reference is the complete emitted output.

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/prompts/tools/search-tool-bm25.md

@@ -12,6 +12,11 @@ Behavior:
 - Repeated searches add to the active tool set; they do not remove earlier selections
 - Newly activated tools become available before the next model call in the same overall turn
 
+Follow-through:
+- Activation only changes the active tool set; it does not execute a discovered tool or complete its work.
+- If the task still needs a newly activated capability, call that tool in the next model turn. Do not claim that a browser action, web search, integration, or subagent ran until its tool result is present.
+- If discovery was the only requested action, report availability as availability, not as completed work.
+
 Not for repository/file/code search. Tool discovery only.
 
 Returns JSON with:

package/src/prompts/tools/task.md

@@ -28,7 +28,7 @@ Subagents have no conversation history. Every fact, file path, and direction the
 {{#if independentMode}}- `.inheritContext`: independent mode cannot inherit parent conversation. Omit it or set `"none"`; any non-`none` value is rejected before scheduling.{{/if}}
 {{#if customSchemaEnabled}}- `schema`: JTD schema for expected structured output (do not put format rules in assignments){{/if}}
 - `spawnPlan` (optional): required before any batch with more than 4 tasks; include whyParallel, whyNotLocal, independence, expectedReceiptShape, and maxInlineTokens.
-{{#if isolationEnabled}}- `isolated`: run in isolated env; use when tasks edit overlapping files{{/if}}
+{{#if isolationEnabled}}- `isolated`: run in an isolated environment; REQUIRED when the user explicitly requests a worktree (for example, "use worktree"), and use when tasks edit overlapping files{{/if}}
 </parameters>
 
 <rules>

package/src/reminders/star-reminder.ts

@@ -18,6 +18,10 @@ import type { ImageContent, MessageAttribution } from "@gajae-code/ai";
 import { getConfigRootDir, isEnoent } from "@gajae-code/utils";
 import { withFileLock } from "../config/file-lock";
 import type { CustomMessage } from "../session/messages";
+import { type GhResult, type RunGh, runGhDefault } from "../utils/gh";
+
+export type { GhResult, RunGh };
+export { runGhDefault };
 
 export const STAR_REMINDER_REPO = "Yeachan-Heo/gajae-code";
 export const STAR_REMINDER_CUSTOM_TYPE = "star-reminder";
@@ -34,15 +38,6 @@ export interface StarReminderState {
 
 export type StarCheckStatus = "starred" | "unstarred" | "unavailable";
 
-export interface GhResult {
-	exitCode: number;
-	stdout: string;
-	stderr: string;
-	timedOut?: boolean;
-}
-
-export type RunGh = (args: string[], options?: { timeoutMs?: number }) => Promise<GhResult>;
-
 export interface StarReminderDeps {
 	statePath?: string;
 	now?: () => Date;
@@ -187,39 +182,6 @@ export async function recordDeclinedAfterNo(deps?: StarReminderDeps): Promise<St
 	}, deps);
 }
 
-// --------------------------------------------------------------------------
-// gh helpers
-// --------------------------------------------------------------------------
-
-/** Default `gh` runner. Returns an unavailable-style result instead of throwing. */
-export async function runGhDefault(args: string[], options?: { timeoutMs?: number }): Promise<GhResult> {
-	const ghPath = Bun.which("gh");
-	if (!ghPath) {
-		return { exitCode: -1, stdout: "", stderr: "gh not found", timedOut: false };
-	}
-	const timeoutMs = options?.timeoutMs ?? GH_TIMEOUT_MS;
-	let timedOut = false;
-	try {
-		const proc = Bun.spawn([ghPath, ...args], { stdout: "pipe", stderr: "pipe", stdin: "ignore" });
-		const timer = setTimeout(() => {
-			timedOut = true;
-			proc.kill();
-		}, timeoutMs);
-		try {
-			const [stdout, stderr] = await Promise.all([
-				new Response(proc.stdout).text(),
-				new Response(proc.stderr).text(),
-			]);
-			const exitCode = await proc.exited;
-			return { exitCode, stdout, stderr, timedOut };
-		} finally {
-			clearTimeout(timer);
-		}
-	} catch (err) {
-		return { exitCode: -1, stdout: "", stderr: err instanceof Error ? err.message : String(err), timedOut };
-	}
-}
-
 function resolveRunGh(deps?: StarReminderDeps): RunGh {
 	return deps?.runGh ?? runGhDefault;
 }

package/src/runtime-mcp/manager.ts

@@ -75,6 +75,7 @@ const STARTUP_TIMEOUT_GRACE_MS = 500;
  * budget derived from the readiness deadline (see `maxStartupTimeoutMs`).
  */
 const MAX_STARTUP_TIMEOUT_MS = 1_750;
+const DEFAULT_EXACT_CONFIG_STARTUP_TIMEOUT_MS = 30_000;
 
 export function resolveStartupTimeoutMs(configs: MCPServerConfig[], maxStartupTimeoutMs?: number): number {
 	const ceiling =
@@ -88,6 +89,17 @@ export function resolveStartupTimeoutMs(configs: MCPServerConfig[], maxStartupTi
 	return Math.min(ceiling, Math.max(STARTUP_TIMEOUT_MS, Math.max(...configuredTimeouts) + STARTUP_TIMEOUT_GRACE_MS));
 }
 
+export function resolveExactConfigStartupTimeoutMs(configs: MCPServerConfig[]): number {
+	const effectiveTimeouts = configs.map(config => {
+		const timeout = config.timeout;
+		return typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0
+			? timeout
+			: DEFAULT_EXACT_CONFIG_STARTUP_TIMEOUT_MS;
+	});
+	if (effectiveTimeouts.length === 0) return STARTUP_TIMEOUT_MS;
+	return Math.max(...effectiveTimeouts) + STARTUP_TIMEOUT_GRACE_MS;
+}
+
 function trackPromise<T>(promise: Promise<T>): TrackedPromise<T> {
 	const tracked: TrackedPromise<T> = { promise, status: "pending" };
 	promise.then(
@@ -650,10 +662,13 @@ export class MCPManager {
 		}
 
 		if (connectionTasks.length > 0) {
-			const startupTimeoutMs = resolveStartupTimeoutMs(
-				connectionTasks.map(task => task.config),
-				this.#maxStartupTimeoutMs,
-			);
+			const configs = connectionTasks.map(task => task.config);
+			// An exact config is explicit operator intent, so its declared connection
+			// windows govern startup. Ordinary discovery keeps the short ceiling.
+			const startupTimeoutMs =
+				this.#toolsOnly && this.#maxStartupTimeoutMs === undefined
+					? resolveExactConfigStartupTimeoutMs(configs)
+					: resolveStartupTimeoutMs(configs, this.#maxStartupTimeoutMs);
 			const firstUnexpectedFailure = Promise.withResolvers<{ reason: unknown }>();
 			if (this.#toolsOnly) {
 				for (const task of connectionTasks) {

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/acp/adapter.ts

@@ -8,7 +8,7 @@ type JsonObject = Record<string, unknown>;
 
 /** The small agent-side ACP surface used for reverse requests. */
 export interface AcpReverseConnection {
-	request?(method: string, params: JsonObject): Promise<unknown>;
+	request?(method: string, params: JsonObject, options?: { cancellationSignal?: AbortSignal }): Promise<unknown>;
 	[key: string]: unknown;
 }
 
@@ -42,6 +42,7 @@ export type AcpReconnectFailedHandler = (error: SdkClientError) => void;
 export type AcpFrameHandler = (frame: SdkFrame) => void;
 type ReverseRequest = {
 	state: "pending" | "cancelled";
+	controller?: AbortController;
 	cancelTimer?: NodeJS.Timeout;
 };
 
@@ -142,7 +143,10 @@ export class AcpSdkAdapter {
 		if (this.#closed) return;
 		this.#closed = true;
 		if (this.#heartbeat) clearInterval(this.#heartbeat);
-		for (const request of this.#reverseRequests.values()) if (request.cancelTimer) clearTimeout(request.cancelTimer);
+		for (const request of this.#reverseRequests.values()) {
+			request.controller?.abort();
+			if (request.cancelTimer) clearTimeout(request.cancelTimer);
+		}
 		this.#reverseRequests.clear();
 		this.#unsubscribe?.();
 		this.#unsubscribeReconnect?.();
@@ -263,6 +267,7 @@ export class AcpSdkAdapter {
 		if (this.#closed || !this.#providers.length) return;
 		if (this.#reclaiming) return await this.#reclaiming;
 		this.#reclaiming = (async () => {
+			this.#abortActiveReverseRequests();
 			this.#connectionId = this.#client.connectionId;
 			if (!this.#connectionId) this.#connectionId = await this.#waitForConnectionId();
 			for (const provider of this.#providers) await this.registerProvider(provider);
@@ -349,13 +354,14 @@ export class AcpSdkAdapter {
 			!this.#ownsReverseLease(connectionId, capability, leaseId)
 		)
 			return;
-		const active: ReverseRequest = { state: "pending" };
+		const controller = new AbortController();
+		const active: ReverseRequest = { state: "pending", controller };
 		this.#reverseRequests.set(id, active);
 		try {
 			const request = frame.payload as JsonObject | undefined;
 			const method = typeof request?.method === "string" ? request.method : "";
 			const payload = request?.payload && typeof request.payload === "object" ? (request.payload as JsonObject) : {};
-			const result = await this.#forwardReverse(method, payload);
+			const result = await this.#forwardReverse(method, payload, controller.signal);
 			if (!this.#canRespondToReverse(id, active, connectionId, capability, leaseId)) return;
 
 			this.#client.send({ type: "reverse_response", id, connectionId, leaseId, ok: true, result });
@@ -404,6 +410,7 @@ export class AcpSdkAdapter {
 		const request: ReverseRequest = this.#reverseRequests.get(id) ?? { state: "pending" };
 		if (request.state === "cancelled") return;
 		request.state = "cancelled";
+		request.controller?.abort();
 		request.cancelTimer = setTimeout(() => this.#finishReverse(id, request), this.#reverseCancelTtlMs);
 		this.#reverseRequests.set(id, request);
 	}
@@ -414,9 +421,18 @@ export class AcpSdkAdapter {
 		this.#reverseRequests.delete(id);
 	}
 
-	async #forwardReverse(method: string, payload: JsonObject): Promise<unknown> {
+	#abortActiveReverseRequests(): void {
+		for (const [id, request] of this.#reverseRequests) {
+			request.state = "cancelled";
+			request.controller?.abort();
+			this.#finishReverse(id, request);
+		}
+	}
+
+	async #forwardReverse(method: string, payload: JsonObject, signal: AbortSignal): Promise<unknown> {
 		if (!method || !this.#connection) throw new AcpSdkAdapterError("acp_reverse_unavailable");
-		if (this.#connection.request) return await this.#connection.request(method, payload);
+		if (this.#connection.request)
+			return await this.#connection.request(method, payload, { cancellationSignal: signal });
 		const target = this.#connection[method];
 		if (typeof target !== "function")
 			throw new AcpSdkAdapterError("acp_reverse_unsupported", `ACP client does not support ${method}.`);

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");
 }