@gajae-code/coding-agent 0.17.2 → 0.17.5

package/src/tools/read.ts

@@ -14,7 +14,7 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { getActiveSkills } from "../extensibility/skills";
 import { formatHashLine, formatHashLines, formatLineHash, HL_BODY_SEP } from "../hashline/hash";
 import { InternalUrlRouter } from "../internal-urls";
-import { parseInternalUrl } from "../internal-urls/parse";
+import { normalizeInternalUrlInput, parseInternalUrl } from "../internal-urls/parse";
 import type { InternalUrl } from "../internal-urls/types";
 import { getLanguageFromPath, type Theme } from "../modes/theme/theme";
 import readDescription from "../prompts/tools/read.md" with { type: "text" };
@@ -2745,7 +2745,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		// off the URL and surfaced via parseSel rather than confusing handlers.
 		const internalRouter = InternalUrlRouter.instance();
 		if (internalRouter.canHandle(readPath)) {
-			const internalTarget = splitInternalUrlSel(readPath, {
+			const internalTarget = splitInternalUrlSel(normalizeInternalUrlInput(readPath), {
 				activeSkillNames: getActiveSkills().map(skill => skill.name),
 			});
 			const parsed = parseSel(internalTarget.sel);
@@ -3590,7 +3590,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			sourcePath: resource.sourcePath,
 			sourceInternal: url,
 			entityLabel: "resource",
-			ignoreResultLimits: scheme === "skill",
+			ignoreResultLimits: scheme === "skill" || scheme === "embedded",
 			immutable: resource.immutable,
 			raw,
 			truncationDirection: direction,

package/src/tools/steer-fold.ts

@@ -0,0 +1,107 @@
+import { logger } from "@gajae-code/utils";
+import type { FoldReason } from "../async/job-manager";
+import type { ToolSession } from ".";
+
+/** A short foreground wait stays in the foreground even when a steer is admitted. */
+export const STEER_FOLD_GRACE_MS = 2_000;
+
+/** Model-facing line appended to a steer-folded background-start result. */
+export function steerFoldReasonLine(jobId: string): string {
+	return `Folded into background job ${jobId} because a user steer arrived; the command keeps running with its original timeout and its result will wake a later turn.`;
+}
+
+/** Model-facing cause clause for a fold, keyed by the recorded {@link FoldReason}. */
+export function foldReasonClause(reason: FoldReason): string {
+	switch (reason) {
+		case "steer":
+			return "because a user steer arrived";
+		case "chord":
+			return "because the user pressed the fold chord";
+		case "sdk_control":
+			return "because an SDK client requested it";
+		case "timer":
+			return "because the auto-background threshold elapsed";
+	}
+}
+
+/** Model-facing line used when the `job` tool's own wait is folded; states the real trigger. */
+export function foldAwaitReasonLine(folded: ReadonlyMap<string, FoldReason>): string {
+	const jobIds = [...folded.keys()];
+	const names = jobIds.map(id => `\`${id}\``).join(", ");
+	const reasons = [...new Set(folded.values())];
+	const single = reasons.length === 1 ? reasons[0] : undefined;
+	const cause = single ? foldReasonClause(single) : "because the waits were folded";
+	const plural = jobIds.length !== 1;
+	return `Folded the job await for ${names} ${cause}; the job${plural ? "s keep" : " keeps"} running with ${plural ? "their original deadlines" : "its original deadline"}, and ${plural ? "their results" : "its result"} will wake a later turn.`;
+}
+
+type SteerFoldSession = Pick<ToolSession, "settings" | "waitForUserSteering" | "requestForegroundBashBackground">;
+
+/** The session hooks a steer fold needs, resolved once so callers never re-read and non-null-assert them. */
+interface SteerFoldHooks {
+	waitForSteer: NonNullable<ToolSession["waitForUserSteering"]>;
+	requestFold: NonNullable<ToolSession["requestForegroundBashBackground"]>;
+}
+
+/**
+ * Whether a queued user steer may fold the running foreground wait. Mirrors
+ * the loop's steer admission: `busyPromptMode=queue` never admits a steer
+ * into the busy run, so it never folds. `toolInterruptPolicy` is
+ * deliberately NOT a gate: `finish_tools` means "do not kill the batch to
+ * deliver a steer", and a fold kills nothing. It is the one way to deliver
+ * the steer now AND let the command finish, so it applies under both
+ * policies; the policy only decides what the loop does with sibling tools
+ * after the fold returns. The auto-background setting is likewise not
+ * consulted: like the chord, a steer fold is a user action.
+ *
+ * Fails closed: a session that cannot report newly admitted steering or
+ * accept a fold request is not steer-foldable.
+ */
+function steerFoldHooks(session: SteerFoldSession): SteerFoldHooks | undefined {
+	const { waitForUserSteering, requestForegroundBashBackground } = session;
+	if (!waitForUserSteering || !requestForegroundBashBackground) return undefined;
+	if (session.settings.get("busyPromptMode") !== "steer") return undefined;
+	return { waitForSteer: waitForUserSteering, requestFold: requestForegroundBashBackground };
+}
+
+/**
+ * Fold on the first user steer that ARRIVES after the wait has run for
+ * {@link STEER_FOLD_GRACE_MS} since `startedAt`. A steer already queued when
+ * the wait starts, or one that arrives inside the grace window, never folds:
+ * the wait finishes normally and that steer is consumed at the ordinary tool
+ * boundary. The watcher keeps observing so a later qualifying steer still
+ * folds, and re-checks the gate at that moment so a `busyPromptMode` change
+ * during the wait is honored. `requestFold` receives the session's resolved
+ * fold request so the caller targets its own adapter without re-reading the
+ * optional session hook.
+ * Returns a stop function; call it when the wait settles. No-op when steer
+ * folding is gated off at start.
+ */
+export function watchSteerForFold(
+	session: SteerFoldSession,
+	startedAt: number,
+	requestFold: (fold: SteerFoldHooks["requestFold"]) => Promise<unknown>,
+	jobId?: string,
+): () => void {
+	const hooks = steerFoldHooks(session);
+	if (!hooks) return () => {};
+	const watch = new AbortController();
+	const observe = async (): Promise<void> => {
+		while (!watch.signal.aborted) {
+			await hooks.waitForSteer(watch.signal);
+			if (watch.signal.aborted) return;
+			if (Date.now() - startedAt < STEER_FOLD_GRACE_MS) continue;
+			const current = steerFoldHooks(session);
+			if (!current) continue;
+			await requestFold(current.requestFold);
+			return;
+		}
+	};
+	observe().catch((error: unknown) => {
+		logger.warn("Steer-triggered fold failed", {
+			...(jobId ? { jobId } : {}),
+			error: error instanceof Error ? error.message : String(error),
+		});
+	});
+	return () => watch.abort();
+}

package/src/tools/subagent-render.ts

@@ -9,6 +9,7 @@
  */
 import type { Component } from "@gajae-code/tui";
 import { Text } from "@gajae-code/tui";
+import { formatNumber } from "@gajae-code/utils";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import { providerRetryPhaseLabel } from "../task/provider-retry-status";
@@ -22,6 +23,7 @@ import {
 	truncateToWidth,
 } from "./render-utils";
 import {
+	SUBAGENT_ACTIVITY_BUCKET_MS,
 	type SubagentLiveProgress,
 	type SubagentSnapshot,
 	type SubagentToolDetails,
@@ -186,7 +188,28 @@ function renderSubagentStatusLine(snapshot: SubagentSnapshot, theme: Theme, spin
 			)
 		: theme.fg("dim", snapshot.status);
 	const duration = theme.fg("dim", formatDuration(snapshot.durationMs));
-	return `${icon} ${id} ${status} ${duration}`;
+	const live = snapshot.liveProgressAvailable !== false ? snapshot.progress : undefined;
+	return `${icon} ${id} ${status} ${duration}${live ? formatLiveStats(live, theme, Date.now()) : ""}`;
+}
+
+// Live stats ride the cheap status line (rebuilt every render), never the cached
+// body. Quantize age to the producer cadence so incidental renders do not churn it.
+function formatLiveStats(progress: SubagentLiveProgress, theme: Theme, nowMs: number): string {
+	const parts: string[] = [];
+	if (progress.toolCount) parts.push(`${progress.toolCount} ${progress.toolCount === 1 ? "tool" : "tools"}`);
+	if (progress.contextTokens) {
+		parts.push(
+			progress.contextWindow
+				? `${formatNumber(progress.contextTokens)}/${formatNumber(progress.contextWindow)} ctx`
+				: `${formatNumber(progress.contextTokens)} ctx`,
+		);
+	}
+	if (progress.lastActivityMs !== undefined && progress.status === "running") {
+		const ageMs = Math.max(0, nowMs - progress.lastActivityMs);
+		const ageBucketMs = Math.floor(ageMs / SUBAGENT_ACTIVITY_BUCKET_MS) * SUBAGENT_ACTIVITY_BUCKET_MS;
+		parts.push(`last activity ${formatDuration(ageBucketMs)} ago`);
+	}
+	return parts.map(part => `${theme.sep.dot}${theme.fg("dim", part)}`).join("");
 }
 
 function renderSubagentLiveProgress(

package/src/tools/subagent.ts

@@ -120,6 +120,10 @@ export interface SubagentLiveProgress {
 	currentTool?: string;
 	recentTool?: string;
 	recentOutputSummary?: { lineCount: number };
+	toolCount?: number;
+	contextTokens?: number;
+	contextWindow?: number;
+	lastActivityMs?: number;
 	fastMode?: boolean;
 	retryState?: {
 		attempt: number;
@@ -145,6 +149,14 @@ function toSubagentLiveProgress(progress: AgentProgress): SubagentLiveProgress {
 		...(progress.recentOutput.length > 0
 			? { recentOutputSummary: { lineCount: Math.min(progress.recentOutput.length, 6) } }
 			: {}),
+		...(progress.toolCount > 0 ? { toolCount: progress.toolCount } : {}),
+		...(progress.contextTokens !== undefined && progress.contextTokens > 0
+			? { contextTokens: progress.contextTokens }
+			: {}),
+		...(progress.contextWindow !== undefined && progress.contextWindow > 0
+			? { contextWindow: progress.contextWindow }
+			: {}),
+		...(progress.lastActivityMs !== undefined ? { lastActivityMs: progress.lastActivityMs } : {}),
 		...(progress.fastMode ? { fastMode: true } : {}),
 		...(progress.retryState
 			? {
@@ -1104,11 +1116,15 @@ function previewJobOutput(
  * unsafe.
  *
  * Time-derived fields are intentionally excluded so the panel does not churn while
- * idle: raw durations (`durationMs`), current-tool elapsed (`currentToolStartMs`),
+ * idle (the child's last-event timestamp is included; it moves only on real
+ * activity): raw durations (`durationMs`), current-tool elapsed (`currentToolStartMs`),
  * and retry countdowns (`retryState.startedAtMs`) are omitted. Idle duration and
  * countdown ticking is sacrificed by design; every real transition still changes
  * the signature.
  */
+/** Shared cadence for await progress refreshes and rendered last-activity age. */
+export const SUBAGENT_ACTIVITY_BUCKET_MS = 5_000;
+
 export function subagentAwaitRenderedStateSignature(
 	subagents: readonly SubagentSnapshot[],
 	receipt?: Pick<SubagentToolDetails, "awaitOutcome" | "interrupted">,
@@ -1156,6 +1172,16 @@ function canonicalizeProgressForSignature(progress: SubagentLiveProgress): unkno
 		currentTool: progress.currentTool ?? null,
 		recentTool: progress.recentTool ?? null,
 		recentOutputSummary: progress.recentOutputSummary ?? null,
+		toolCount: progress.toolCount ?? 0,
+		contextTokens: progress.contextTokens ?? null,
+		contextWindow: progress.contextWindow ?? null,
+		// Event timestamp, bucketed: it only moves when the child actually does
+		// something (idle gating holds), and the bucket keeps a streaming child from
+		// re-emitting on every delta. The status-line age is quantized to this cadence.
+		lastActivityBucket:
+			progress.lastActivityMs === undefined
+				? null
+				: Math.floor(progress.lastActivityMs / SUBAGENT_ACTIVITY_BUCKET_MS),
 		fastMode: progress.fastMode ?? false,
 		retryFailure: progress.retryFailure ?? null,
 		retryState: progress.retryState

package/src/tools/tool-catalog.generated.ts

@@ -27,7 +27,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"read": {
 		"name": "read",
 		"label": "Read",
-		"description": "Read files, directories, archives, SQLite databases, images, documents, internal resources, and web URLs through a single `path` string.\n\n<instruction>\n- One tool for filesystem, archives, SQLite, images, documents (PDF/DOCX/PPTX/XLSX/RTF/EPUB/ipynb), internal URIs, and web URLs (reader-mode by default).\n- You SHOULD parallelize independent reads when exploring related files.\n- You SHOULD reach for `read` — not a browser/puppeteer tool — for fetching web content.\n</instruction>\n\n## Parameters\n\n- `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`).\n- `truncation` — optional `head` | `last` | `both`; selects which end of an over-budget result to retain. Configured default: last (factory default: `last`); structural summaries and 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.\n## Selectors\nAppend `:<sel>` to `path`. The bare path falls back to the default mode.\n\n- _(none)_ — parseable code → structural summary (signatures kept, bodies elided); a plain text file → a bounded receipt of about undefined lines or undefined KiB, whichever is smaller; the configured truncation direction is last (factory default: last). Line+hash anchors keep their real file line numbers and a footer names the omitted range. Archive members use the larger 3000-line / 50 KiB budget. Converted documents, notebooks, URLs and directory listings still start from the beginning.\n- `:50` / `:50-` — read from line 50 onward.\n- `:50-200` — lines 50–200 inclusive.\n- `:50+150` — 150 lines starting at line 50.\n- `:20+1` — exactly one line.\n- `:5-16,960-973` — multiple ranges in one call (sorted, overlaps merged).\n- `:raw` — verbatim text; no anchors, no summary, no line prefixes.\n- `:2-4:raw` or `:raw:2-4` — range AND verbatim; the two compose in either order.\n- `:conflicts` — one-line-per-block index of every unresolved git merge conflict.\n\n# Files\n\n- Reading a directory path returns a depth-limited dirent listing.\n- Parseable code without a selector returns a **structural summary**: declarations kept, large bodies collapsed to `..` (merged brace pair) or `…` (standalone). Summarized output ends with a footer of the form:\n\n  `[NN lines across MM elided regions; read <path>:raw or a line range like <path>:1-9999 for verbatim content]`\n\n  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.\n- Structural summaries honor explicit `truncation`: `head` retains the beginning, `last` the end, and `both` both ends within the summary byte budget. Complete summary units and their original source anchors stay intact and in source order; budget omissions are marked where they occur. This does not switch to raw source. Summaries that fit are unchanged by direction.\n- 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.\n\n# Documents & Notebooks\n\nExtracts text from PDF, Word, PowerPoint, Excel, RTF, and EPUB. Notebooks (`.ipynb`) are shown as editable `# %% [type] cell:N` text; edits round-trip back to the underlying JSON preserving notebook metadata. Add `:raw` to a notebook to bypass the converter and read the JSON directly.\n\n# Images\n\nReading an image path returns the image itself for visual inspection by a vision-capable model.\n\n# Archives\n\nSupports `.tar`, `.tar.gz`, `.tgz`, `.zip`. Use `archive.ext:path/inside/archive` to read a member, and append a normal selector to the inner path: `archive.zip:dir/file.ts:50-60`.\n\n# SQLite\n\nFor `.sqlite`, `.sqlite3`, `.db`, `.db3`:\n- `file.db` — list tables with row counts\n- `file.db:table` — schema + sample rows\n- `file.db:table:key` — single row by primary key\n- `file.db:table?limit=50&offset=100` — paginated rows\n- `file.db:table?where=status='active'&order=created:desc` — filtered rows\n- `file.db?q=SELECT …` — read-only SELECT query\n\n# URLs\n\n- Default reader-mode: HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs → clean text/markdown.\n- `:raw` returns untouched HTML; line selectors (`:50`, `:50-100`, `:50+150`) paginate the cached fetched output.\n- Bare `host:port` URLs collide with the selector grammar — add a trailing slash before the selector: `https://example.com/:80`.\n\n# Internal URIs\n\n`agent://<id>`, `artifact://<id>`, `rule://<name>`, and `local://<name>.md` resolve transparently and accept the same line selectors as filesystem paths. Use `artifact://<id>` to recover full output that a previous bash/eval/tool result spilled or truncated.\n\n<critical>\n- Always include `path`; never call `read` with `{}`.\n- For line ranges, append the selector to `path`.\n- Re-issue the selector named by a summary footer before relying on elided content.\n</critical>",
+		"description": "Read files, directories, archives, SQLite databases, images, documents, internal resources, and web URLs through a single `path` string.\n\n<instruction>\n- One tool for filesystem, archives, SQLite, images, documents (PDF/DOCX/PPTX/XLSX/RTF/EPUB/ipynb), internal URIs, and web URLs (reader-mode by default).\n- You SHOULD parallelize independent reads when exploring related files.\n- You SHOULD reach for `read` — not a browser/puppeteer tool — for fetching web content.\n</instruction>\n\n## Parameters\n\n- `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`).\n- `truncation` — optional `head` | `last` | `both`; selects which end of an over-budget result to retain. Configured default: last (factory default: `last`); structural summaries and 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.\n## Selectors\nAppend `:<sel>` to `path`. The bare path falls back to the default mode.\n\n- _(none)_ — parseable code → structural summary (signatures kept, bodies elided); a plain text file → a bounded receipt of about undefined lines or undefined KiB, whichever is smaller; the configured truncation direction is last (factory default: last). Line+hash anchors keep their real file line numbers and a footer names the omitted range. Archive members use the larger 3000-line / 50 KiB budget. Converted documents, notebooks, URLs and directory listings still start from the beginning.\n- `:50` / `:50-` — read from line 50 onward.\n- `:50-200` — lines 50–200 inclusive.\n- `:50+150` — 150 lines starting at line 50.\n- `:20+1` — exactly one line.\n- `:5-16,960-973` — multiple ranges in one call (sorted, overlaps merged).\n- `:raw` — verbatim text; no anchors, no summary, no line prefixes.\n- `:2-4:raw` or `:raw:2-4` — range AND verbatim; the two compose in either order.\n- `:conflicts` — one-line-per-block index of every unresolved git merge conflict.\n\n# Files\n\n- Reading a directory path returns a depth-limited dirent listing.\n- Parseable code without a selector returns a **structural summary**: declarations kept, large bodies collapsed to `..` (merged brace pair) or `…` (standalone). Summarized output ends with a footer of the form:\n\n  `[NN lines across MM elided regions; read <path>:raw or a line range like <path>:1-9999 for verbatim content]`\n\n  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.\n- Structural summaries honor explicit `truncation`: `head` retains the beginning, `last` the end, and `both` both ends within the summary byte budget. Complete summary units and their original source anchors stay intact and in source order; budget omissions are marked where they occur. This does not switch to raw source. Summaries that fit are unchanged by direction.\n- 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.\n\n# Documents & Notebooks\n\nExtracts text from PDF, Word, PowerPoint, Excel, RTF, and EPUB. Notebooks (`.ipynb`) are shown as editable `# %% [type] cell:N` text; edits round-trip back to the underlying JSON preserving notebook metadata. Add `:raw` to a notebook to bypass the converter and read the JSON directly.\n\n# Images\n\nReading an image path returns the image itself for visual inspection by a vision-capable model.\n\n# Archives\n\nSupports `.tar`, `.tar.gz`, `.tgz`, `.zip`. Use `archive.ext:path/inside/archive` to read a member, and append a normal selector to the inner path: `archive.zip:dir/file.ts:50-60`.\n\n# SQLite\n\nFor `.sqlite`, `.sqlite3`, `.db`, `.db3`:\n- `file.db` — list tables with row counts\n- `file.db:table` — schema + sample rows\n- `file.db:table:key` — single row by primary key\n- `file.db:table?limit=50&offset=100` — paginated rows\n- `file.db:table?where=status='active'&order=created:desc` — filtered rows\n- `file.db?q=SELECT …` — read-only SELECT query\n\n# URLs\n\n- Default reader-mode: HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs → clean text/markdown.\n- `:raw` returns untouched HTML; line selectors (`:50`, `:50-100`, `:50+150`) paginate the cached fetched output.\n- Bare `host:port` URLs collide with the selector grammar — add a trailing slash before the selector: `https://example.com/:80`.\n\n# Internal URIs\n\n`agent://<id>`, `artifact://<id>`, `rule://<name>`, and `local://<name>.md` resolve transparently and accept the same line selectors as filesystem paths. Use `artifact://<id>` to recover full output that a previous bash/eval/tool result spilled or truncated.\n\nBundled skills have no filesystem home, so the skill tool and skill discovery report them as `embedded:gjc/skills/<name>/SKILL.md`; read that identifier verbatim. Bundled skill fragments, when surfaced, likewise use `embedded:gjc/skill-fragments/...` identifiers.\n\n<critical>\n- Always include `path`; never call `read` with `{}`.\n- For line ranges, append the selector to `path`.\n- Re-issue the selector named by a summary footer before relying on elided content.\n</critical>",
 		"parameters": {
 			"type": "object",
 			"properties": {
@@ -89,6 +89,33 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 				"pty": {
 					"type": "boolean",
 					"description": "run in pty mode"
+				},
+				"activity": {
+					"description": "declare browser activity for the aside browser backend: repl or exec",
+					"type": "object",
+					"properties": {
+						"kind": {
+							"type": "string",
+							"const": "browser"
+						},
+						"provider": {
+							"type": "string",
+							"const": "aside"
+						},
+						"mode": {
+							"type": "string",
+							"enum": [
+								"repl",
+								"exec"
+							]
+						}
+					},
+					"required": [
+						"kind",
+						"provider",
+						"mode"
+					],
+					"additionalProperties": false
 				}
 			},
 			"required": [
@@ -2326,7 +2353,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"job": {
 		"name": "job",
 		"label": "Job",
-		"description": "Inspects, waits, or cancels async jobs.\n\nBackground job results are delivered automatically when complete. Jobs that back task subagents should be controlled via the `subagent` tool when it is available; use `job` for non-subagent jobs (async bash, monitors) and as a compatibility fallback. Running job output stays quiet by default to avoid flooding the conversation; use `tail` when you explicitly want to show/reopen retained output. Reach for this tool only when you need to inspect or intervene.\n\nIn the interactive TUI, a running foreground command can be folded into a background job by pressing the fold chord twice (default `Alt+Shift+B`, plus `Cmd+B` on macOS; remappable via `app.tool.backgroundFold`), or automatically when the user sends a steer after the command has run for at least 2 seconds (with `busyPromptMode=steer` (`toolInterruptPolicy` is not a gate)). This covers managed non-PTY bash, editor/ACP client-terminal commands, and PTY-mode commands. A folded job keeps its original deadline, is never killed or restarted by folding, and its result wakes a later turn automatically; a folded PTY continues output-only and no longer accepts input. Job listings expose `foldReason` (`steer`, `chord`, `timer`, or `sdk_control`) beside `backgrounded` so you can tell why a job left the foreground. `task`/`subagent` waits are not foldable. Raw shell `Ctrl+Z`/`bg` is not the supported path inside GJC because it bypasses job ownership and output-routing contracts.\n\n# Operations\n\n## `list: true`\nUse to inspect what's running.\n\n## `tail: [id, …]`\nShow the retained output buffer for one or more background jobs without waiting.\n- Use this to reopen/tail a backgrounded long-running bash/tool output after folding it away.\n- Output is bounded by the manager retention window; stale cursors may report that only the retained tail is available.\n- Prefer `tail` over polling when you only need to peek at progress, so the conversation can continue without flooding the TUI.\n\n## `poll: [id, …]`\nBlock until the specified jobs finish or the wait window (~30 s, not configurable) elapses.\n- Use when you are genuinely blocked on a result and have no other work to do.\n- Returns the current snapshot when the timer elapses; running jobs remain running.\n- Completed jobs include their final output in the returned snapshot.\n\n## `cancel: [id, …]`\nStop running jobs.\n- Use when a job is stalled, hung, or no longer needed.\n- Returns immediately after cancelling.",
+		"description": "Inspects, waits, or cancels async jobs.\n\nBackground job results are delivered automatically when complete. Jobs that back task subagents should be controlled via the `subagent` tool when it is available; use `job` for non-subagent jobs (async bash, monitors) and as a compatibility fallback. Running job output stays quiet by default to avoid flooding the conversation; use `tail` when you explicitly want to show/reopen retained output. Reach for this tool only when you need to inspect or intervene.\n\nIn the interactive TUI, a running foreground command can be folded into a background job by pressing the fold chord twice (default `Alt+Shift+B`, plus `Cmd+B` on macOS; remappable via `app.tool.backgroundFold`), or automatically when the user sends a steer after the command has run for at least 2 seconds (with `busyPromptMode=steer` (`toolInterruptPolicy` is not a gate)). This covers managed non-PTY bash, editor/ACP client-terminal commands, and PTY-mode commands. A folded job keeps its original deadline, is never killed or restarted by folding, and its result wakes a later turn automatically; a folded PTY continues output-only and no longer accepts input. A `job` await also folds after the same 2-second grace window when a steer arrives, returning immediately with the still-running job id(s) while those jobs keep their original deadlines and wake a later turn with their results. Job listings expose `foldReason` (`steer`, `chord`, `timer`, or `sdk_control`) beside `backgrounded` so you can tell why a job left the foreground. `task`/`subagent` waits are not foldable. Raw shell `Ctrl+Z`/`bg` is not the supported path inside GJC because it bypasses job ownership and output-routing contracts.\n\n# Operations\n\n## `list: true`\nUse to inspect what's running.\n\n## `tail: [id, …]`\nShow the retained output buffer for one or more background jobs without waiting.\n- Use this to reopen/tail a backgrounded long-running bash/tool output after folding it away.\n- Output is bounded by the manager retention window; stale cursors may report that only the retained tail is available.\n- Prefer `tail` over polling when you only need to peek at progress, so the conversation can continue without flooding the TUI.\n\n## `poll: [id, …]`\nBlock until the specified jobs finish or the wait window (~30 s, not configurable) elapses.\n- Use when you are genuinely blocked on a result and have no other work to do.\n- Returns the current snapshot when the timer elapses; running jobs remain running.\n- Completed jobs include their final output in the returned snapshot.\n\n## `cancel: [id, …]`\nStop running jobs.\n- Use when a job is stalled, hung, or no longer needed.\n- Returns immediately after cancelling.",
 		"parameters": {
 			"type": "object",
 			"properties": {

package/src/tools/tool-errors.ts

@@ -1,3 +1,5 @@
+import { markDesignedError } from "@gajae-code/utils/error-classification";
+
 /**
  * Standardized error types for tool execution.
  *
@@ -16,6 +18,7 @@ export class ToolError extends Error {
 	) {
 		super(message);
 		this.name = "ToolError";
+		markDesignedError(this);
 	}
 
 	/** Render error for LLM consumption. Override for custom formatting. */
@@ -33,6 +36,7 @@ export class ToolAbortError extends Error {
 	constructor(message: string = ToolAbortError.MESSAGE) {
 		super(message);
 		this.name = "ToolAbortError";
+		markDesignedError(this);
 	}
 }
 

package/src/utils/git.ts

@@ -805,10 +805,18 @@ export const status = Object.assign(
 // ════════════════════════════════════════════════════════════════════════════
 
 export const stage = {
-	/** Stage files. Empty array stages all (`git add -A`). */
-	async files(cwd: string, files: readonly string[] = [], signal?: AbortSignal): Promise<void> {
+	/**
+	 * Stage files. Empty array stages all (`git add -A`). Accepts a bare signal or
+	 * `{ env, signal }`; `env` exists so a caller can stage into an isolated
+	 * `GIT_INDEX_FILE` instead of the repository's real index.
+	 */
+	async files(
+		cwd: string,
+		files: readonly string[] = [],
+		options: AbortSignal | Pick<CommandOptions, "env" | "signal"> = {},
+	): Promise<void> {
 		const args = files.length === 0 ? ["add", "-A"] : ["add", "--", ...files];
-		await runEffect(cwd, args, { signal });
+		await runEffect(cwd, args, options instanceof AbortSignal ? { signal: options } : options);
 	},
 
 	/** Selectively stage hunks from the provided diff or the current working tree diff. */
@@ -902,6 +910,28 @@ export async function writeTree(cwd: string, options: Pick<CommandOptions, "env"
 	return (await runText(cwd, ["write-tree"], options)).trim();
 }
 
+export interface CommitTreeOptions {
+	readonly env?: Record<string, string | undefined>;
+	readonly parents?: readonly string[];
+	readonly signal?: AbortSignal;
+}
+
+/**
+ * Create a commit object from an existing tree and return its SHA. Plumbing:
+ * unlike `commit` this touches neither the index nor any ref, and runs no
+ * `pre-commit`/`commit-msg` hook.
+ */
+export async function commitTree(
+	cwd: string,
+	tree: string,
+	message: string,
+	options: CommitTreeOptions = {},
+): Promise<string> {
+	const args = ["commit-tree", tree];
+	for (const parent of options.parents ?? []) args.push("-p", parent);
+	return (await runText(cwd, args, { env: options.env, signal: options.signal, stdin: message })).trim();
+}
+
 // ════════════════════════════════════════════════════════════════════════════
 // API: show
 // ════════════════════════════════════════════════════════════════════════════
@@ -1075,6 +1105,26 @@ export const ref = {
 		return result.stdout.trim() || null;
 	},
 
+	/**
+	 * Move a ref to `newValue`, but only while it still holds `expectedOldValue`
+	 * (the empty string asserts the ref does not exist yet). Git verifies the old
+	 * value and writes the new one under its own ref lock, so this is an atomic
+	 * compare-and-swap: a concurrent writer that moved the ref first makes this
+	 * throw instead of silently clobbering their commit.
+	 */
+	async update(
+		cwd: string,
+		refName: string,
+		newValue: string,
+		expectedOldValue: string,
+		options: { reason?: string; signal?: AbortSignal } = {},
+	): Promise<void> {
+		const args = ["update-ref"];
+		if (options.reason) args.push("-m", options.reason);
+		args.push(refName, newValue, expectedOldValue);
+		await runEffect(cwd, args, { signal: options.signal });
+	},
+
 	/** Tags pointing at a ref. */
 	async tags(cwd: string, refName = "HEAD", signal?: AbortSignal): Promise<string[]> {
 		return splitLines(

package/src/utils/markit.ts

@@ -1,7 +1,7 @@
 import { untilAborted } from "@gajae-code/utils";
-import type { Markit, StreamInfo } from "markit-ai";
+import type { Markit, StreamInfo } from "../../vendor/markit-ai/dist/index.js";
 import { ToolAbortError } from "../tools/tool-errors";
-import { ensureMupdfWasmResolution } from "./mupdf-wasm";
+import { prepareMuPdf, sanitizeMuPdfDiagnostic, withMuPdfDiagnostic } from "./mupdf";
 
 export interface MarkitConversionResult {
 	content: string;
@@ -9,20 +9,23 @@ export interface MarkitConversionResult {
 	error?: string;
 }
 
-let markit: () => Markit | Promise<Markit> = async () => {
-	const promise = import("markit-ai").then(({ Markit }) => {
-		const instance = new Markit();
-		markit = () => instance;
-		return instance;
-	});
-	markit = () => promise;
-	return promise;
-};
+let instance: Markit | undefined;
+let instancePromise: Promise<Markit> | undefined;
 
-// #5433: mupdf's wasm asset is not reachable at the Emscripten loader's
-// default bunfs path in compiled binaries. Seed the embedded-asset hook
-// before any markit conversion (and therefore before any mupdf import).
-ensureMupdfWasmResolution();
+async function loadMarkit(): Promise<Markit> {
+	if (instancePromise === undefined) {
+		instancePromise = import("../../vendor/markit-ai/dist/index.js")
+			.then(({ Markit: MarkitConstructor }) => {
+				instance = new MarkitConstructor();
+				return instance;
+			})
+			.catch(error => {
+				instancePromise = undefined;
+				throw error;
+			});
+	}
+	return instancePromise;
+}
 
 function normalizeExtension(extension: string): string {
 	const trimmed = extension.trim().toLowerCase();
@@ -30,33 +33,27 @@ function normalizeExtension(extension: string): string {
 	return trimmed.startsWith(".") ? trimmed : `.${trimmed}`;
 }
 
-function normalizeError(error: unknown): string {
-	if (error instanceof Error && error.message.trim().length > 0) {
-		return error.message.trim();
-	}
-	return "Conversion failed";
-}
-
-/**
- * markit-ai's PDF converter swallows the real mupdf import failure behind a
- * generic "Install it" message (#5433). Re-run the import here so release
- * diagnostics carry the actual module/asset/initialization error.
- */
-async function describeConversionError(error: unknown): Promise<string> {
-	const base = normalizeError(error);
-	if (!base.includes("PDF support requires 'mupdf'")) return base;
-	try {
-		await import("mupdf");
-	} catch (cause) {
-		return `${base} (mupdf import failed: ${normalizeError(cause)})`;
+function normalizeError(error: unknown, pdf = false): string {
+	const messages: string[] = [];
+	const seen = new Set<unknown>();
+	while (error !== undefined && !seen.has(error)) {
+		seen.add(error);
+		if (error instanceof Error) {
+			const message = `${error.name}: ${error.message}`;
+			messages.push(pdf ? sanitizeMuPdfDiagnostic(message) : message);
+			error = error.cause;
+		} else {
+			messages.push(pdf ? sanitizeMuPdfDiagnostic(String(error)) : String(error));
+			break;
+		}
 	}
-	return base;
+	return messages.join("; caused by: ") || "Conversion failed";
 }
 
 async function runMarkitConversion<T>(task: (markit: Markit) => Promise<T>, signal?: AbortSignal): Promise<T> {
 	try {
-		const instance = await markit();
-		return signal ? await untilAborted(signal, () => task(instance)) : await task(instance);
+		const markit = instance ?? (await loadMarkit());
+		return signal ? await untilAborted(signal, () => task(markit)) : await task(markit);
 	} catch (error) {
 		if (error instanceof ToolAbortError) {
 			throw error;
@@ -78,13 +75,22 @@ function finalizeConversion(markdown?: string): MarkitConversionResult {
 
 export async function convertFileWithMarkit(filePath: string, signal?: AbortSignal): Promise<MarkitConversionResult> {
 	try {
-		const result = await runMarkitConversion(markit => markit.convertFile(filePath), signal);
+		if (filePath.toLowerCase().endsWith(".pdf")) await prepareMuPdf();
+		const result = await runMarkitConversion(async markit => {
+			return markit.convertFile(filePath);
+		}, signal);
 		return finalizeConversion(result.markdown);
 	} catch (error) {
 		if (error instanceof ToolAbortError) {
 			throw error;
 		}
-		return { content: "", ok: false, error: await describeConversionError(error) };
+		return {
+			content: "",
+			ok: false,
+			error: filePath.toLowerCase().endsWith(".pdf")
+				? normalizeError(withMuPdfDiagnostic(error), true)
+				: normalizeError(error),
+		};
 	}
 }
 
@@ -100,12 +106,20 @@ export async function convertBufferWithMarkit(
 	};
 
 	try {
-		const result = await runMarkitConversion(markit => markit.convert(Buffer.from(buffer), streamInfo), signal);
+		if (normalizedExtension === ".pdf") await prepareMuPdf();
+		const result = await runMarkitConversion(async markit => {
+			return markit.convert(Buffer.from(buffer), streamInfo);
+		}, signal);
 		return finalizeConversion(result.markdown);
 	} catch (error) {
 		if (error instanceof ToolAbortError) {
 			throw error;
 		}
-		return { content: "", ok: false, error: await describeConversionError(error) };
+		return {
+			content: "",
+			ok: false,
+			error:
+				normalizedExtension === ".pdf" ? normalizeError(withMuPdfDiagnostic(error), true) : normalizeError(error),
+		};
 	}
 }

package/src/utils/mupdf-assets.d.ts

@@ -0,0 +1,4 @@
+declare module "*.wasm" {
+	const assetPath: string;
+	export default assetPath;
+}

package/src/utils/mupdf-embedded.ts

@@ -0,0 +1,4 @@
+// AUTOGENERATED FILE -- DO NOT EDIT DIRECTLY
+// See scripts/embed-mupdf.ts. Source installs resolve the package lazily.
+export const embeddedMuPdfWasm: string | undefined = undefined;
+export const embeddedMuPdfModule: string | undefined = undefined;