@gajae-code/coding-agent 0.16.7 → 0.17.1

package/src/tools/read.ts

@@ -479,8 +479,7 @@ function formatSummaryCapFooter(
 	totalLines: number,
 	direction: TruncationDirection = "head",
 ): string {
-	const retained = direction === "last" ? "last" : direction === "both" ? "first and last" : "first";
-	const directionPart = direction === "head" ? "" : `; retained ${retained} summary units`;
+	const directionPart = direction === "head" ? "" : `; truncation: ${direction}`;
 	return `[Summary truncated at ${Math.ceil(maxBytes / 1024)} KiB${directionPart}; re-read ${readPath}:1-${totalLines} or ${readPath}:raw for the full source]`;
 }
 const READ_CHUNK_SIZE = 8 * 1024;
@@ -2498,12 +2497,16 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		}
 	}
 
-	#renderSummary(summary: SummaryResult): {
+	#renderSummary(
+		summary: SummaryResult,
+		direction: TruncationDirection,
+	): {
 		text: string;
 		displayText: string;
 		elidedSpans: number;
 		elidedLines: number;
 		capped: boolean;
+		omissionNotice: string;
 	} {
 		const displayMode = resolveFileDisplayMode(this.session);
 		const shouldAddHashLines = displayMode.hashLines;
@@ -2561,14 +2564,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			i++;
 		}
 
-		const modelParts: string[] = [];
-		const displayParts: string[] = [];
 		const capBytes = this.session.settings.get("read.summaryMaxBytes") * 1024;
-		let usedBytes = 0;
-		let elidedSpans = 0;
-		let elidedLines = 0;
-		let capDropped = false;
-		for (const unit of units) {
+		const rendered = units.map(unit => {
 			let model: string;
 			let display: string;
 			let implicitElidedLines = 0;
@@ -2591,31 +2588,82 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				model = formatSingleLine(unit.line, unit.text, shouldAddHashLines, shouldAddLineNumbers);
 				display = unit.text;
 			}
-			const separatorBytes = modelParts.length > 0 ? 1 : 0;
-			if (usedBytes + separatorBytes + Buffer.byteLength(model, "utf-8") > capBytes) {
-				capDropped = true;
-				elidedSpans++;
-				elidedLines += unit.kind === "line" ? 1 : unit.endLine - unit.startLine + 1;
-				continue;
+			return { model, display, implicitElidedLines };
+		});
+		// Prefix sums include each unit's separator. Removing the final separator
+		// gives the exact UTF-8 body size, without charging recovery footers.
+		const bytes = [0];
+		for (const part of rendered) {
+			bytes.push(bytes[bytes.length - 1] + Buffer.byteLength(part.model, "utf-8") + 1);
+		}
+		const omissionMarker = (head: number, tail: number): string => {
+			const first = units[head];
+			const last = units[tail - 1];
+			const start = first.kind === "line" ? first.line : first.startLine;
+			const end = last.kind === "line" ? last.line : last.endLine;
+			return `[… source lines ${start}-${end} omitted …]`;
+		};
+		let head = units.length;
+		let tail = units.length;
+		const capDropped = bytes[units.length] - 1 > capBytes;
+		if (capDropped) {
+			head = 0;
+			const fits = (nextHead: number, nextTail: number): boolean =>
+				bytes[nextHead] +
+					bytes[units.length] -
+					bytes[nextTail] +
+					Buffer.byteLength(omissionMarker(nextHead, nextTail), "utf-8") <=
+				capBytes;
+			let headBlocked = direction === "last";
+			let tailBlocked = direction === "head";
+			// Keep contiguous edge windows: an oversized unit blocks that edge,
+			// never splits an anchor or turns a prefix/suffix into scattered lines.
+			while (head + 1 < tail && (!headBlocked || !tailBlocked)) {
+				const takeHead = !headBlocked && (tailBlocked || bytes[head] <= bytes[units.length] - bytes[tail]);
+				if (takeHead) {
+					if (fits(head + 1, tail)) head++;
+					else headBlocked = true;
+				} else {
+					if (fits(head, tail - 1)) tail--;
+					else tailBlocked = true;
+				}
 			}
-			usedBytes += separatorBytes + Buffer.byteLength(model, "utf-8");
-			modelParts.push(model);
-			displayParts.push(display);
-			if (unit.kind === "elided" || unit.kind === "merged") {
+		}
+		const modelParts: string[] = [];
+		const displayParts: string[] = [];
+		let elidedSpans = 0;
+		let elidedLines = 0;
+		let omissionNotice = "";
+		for (let index = 0; index < units.length; index++) {
+			const unit = units[index];
+			if (index >= head && index < tail) {
+				if (index === head) {
+					const marker = omissionMarker(head, tail);
+					// A sub-marker budget can retain no units. Keep its source-range
+					// notice with the recovery footers rather than exceeding the body cap.
+					if (Buffer.byteLength(marker, "utf-8") > capBytes) omissionNotice = marker;
+					else {
+						modelParts.push(marker);
+						displayParts.push(marker);
+					}
+				}
 				elidedSpans++;
-				elidedLines += implicitElidedLines;
+				elidedLines += unit.kind === "line" ? 1 : unit.endLine - unit.startLine + 1;
+			} else {
+				const part = rendered[index];
+				modelParts.push(part.model);
+				displayParts.push(part.display);
+				if (unit.kind !== "line") elidedSpans++;
+				elidedLines += part.implicitElidedLines;
 			}
 		}
-		if (capDropped) {
-			modelParts.push("…");
-			displayParts.push("…");
-		}
 		return {
 			text: modelParts.join("\n"),
 			displayText: displayParts.join("\n"),
 			elidedSpans,
 			elidedLines,
 			capped: capDropped,
+			omissionNotice,
 		};
 	}
 
@@ -2911,27 +2959,25 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				(this.session.settings.get("read.summarize.prose") || !PROSE_SUMMARY_EXTENSIONS.has(ext))
 			) {
 				const summary = await this.#trySummarize(absolutePath, fileSize, signal);
-				if (params.truncation !== undefined && params.truncation !== "head" && summary?.parsed) {
-					throw new ToolError(
-						"Explicit truncation for structural summaries is not yet supported; summary direction will be applied after summary units become directional.",
-					);
-				}
 				if (summary?.parsed && summary.elided) {
-					const renderedSummary = this.#renderSummary(summary);
+					const direction = resolveEffectiveDirection(params.truncation, "local-summary", this.session.settings);
+					const renderedSummary = this.#renderSummary(summary, direction);
 					const footer = formatSummaryElisionFooter(
 						localReadPath,
 						renderedSummary.elidedSpans,
 						renderedSummary.elidedLines,
 					);
-					const summaryTotalLines = Math.max(...summary.segments.map(segment => segment.endLine));
+					const summaryTotalLines = summary.totalLines;
 					const modelText = [
 						renderedSummary.text,
+						renderedSummary.omissionNotice,
 						footer,
 						renderedSummary.capped
 							? formatSummaryCapFooter(
 									localReadPath,
 									this.session.settings.get("read.summaryMaxBytes") * 1024,
 									summaryTotalLines,
+									direction,
 								)
 							: "",
 					]

package/src/tools/skill-discovery.ts

@@ -3,6 +3,7 @@ import { prompt, untilAborted } from "@gajae-code/utils";
 import * as z from "zod/v4";
 import {
 	describeDisabledSkillScopes,
+	describeNoSkillMatch,
 	discoverRuntimeSkills,
 	type RuntimeSkillDiscoveryCandidate,
 } from "../extensibility/runtime-skill-discovery";
@@ -14,7 +15,9 @@ const skillDiscoverySchema = z
 		query: z
 			.string()
 			.optional()
-			.describe("words to match against skill name, description, source, or use conditions"),
+			.describe(
+				"words to match against skill name, description, source, or use conditions; every term must appear (conjunctive substring), or one term must equal the exact skill name",
+			),
 		source: z.enum(["all", "project", "user"]).default("all").optional().describe("skill source scope to search"),
 		limit: z.number().min(1).max(50).default(20).optional().describe("maximum results"),
 	})
@@ -26,10 +29,12 @@ export interface SkillDiscoveryToolDetails {
 	candidates: RuntimeSkillDiscoveryCandidate[];
 	count: number;
 	/**
-	 * Present only when zero candidates were returned AND discovery config gates
-	 * (`skills.enabled` / `skills.trustProjectSkills` / `skills.trustUserSkills`)
-	 * prevented some or all of the requested scope from being searched. Without
-	 * this, a disabled config is indistinguishable from "no skills exist".
+	 * Present only when zero candidates were returned. Either discovery config
+	 * gates (`skills.enabled` / `skills.trustProjectSkills` /
+	 * `skills.trustUserSkills`) prevented some or all of the requested scope from
+	 * being searched, a non-empty query filtered out every scanned skill, or
+	 * diagnostics were produced for observed skills that were skipped or filtered.
+	 * Without this, these cases are indistinguishable from "no skills exist".
 	 */
 	notice?: string;
 	/**
@@ -44,7 +49,7 @@ export interface SkillDiscoveryToolDetails {
 export class SkillDiscoveryTool implements AgentTool<typeof skillDiscoverySchema, SkillDiscoveryToolDetails> {
 	readonly name = "skill_discovery";
 	readonly label = "SkillDiscovery";
-	readonly summary = "Discover project and user runtime skills by thin metadata";
+	readonly summary = "Discover bundled GJC workflow, project, and user runtime skills by thin metadata";
 	readonly loadMode = "essential";
 	readonly description: string;
 	readonly parameters = skillDiscoverySchema;
@@ -95,7 +100,12 @@ export class SkillDiscoveryTool implements AgentTool<typeof skillDiscoverySchema
 			};
 			if (result.diagnostics.messages.length > 0) details.diagnostics = result.diagnostics.messages;
 			if (result.candidates.length === 0) {
-				const notice = describeDisabledSkillScopes(source, this.#getRuntimeSkillPolicy());
+				const notice =
+					describeDisabledSkillScopes(source, this.#getRuntimeSkillPolicy()) ??
+					describeNoSkillMatch(input.query, result.scanned) ??
+					(result.scanned > 0 || result.diagnostics.messages.length > 0
+						? `No skill candidates were returned (${result.scanned} skill${result.scanned === 1 ? "" : "s"} scanned); see diagnostics for filtered or skipped skills.`
+						: undefined);
 				if (notice) details.notice = notice;
 			}
 			return {

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`); 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.\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- 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\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": {
@@ -1109,7 +1109,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"browser": {
 		"name": "browser",
 		"label": "Browser",
-		"description": "Drives a real Chromium tab with full puppeteer access via JS execution.\n\n<instruction>\n- For static web content (articles, docs, issues/PRs, JSON, PDFs, feeds), prefer the `read` tool with a URL. Use this tool only when you need JS execution, authentication, or interactive actions.\n- Four actions:\n  - `open` — acquire (or reuse) a named tab. `name` defaults to `\"main\"`. Optional `url`, `viewport`, and `dialogs: \"accept\" | \"dismiss\"` (auto-handles `alert`/`confirm`/`beforeunload`). The `app` field selects the browser kind (spawned binary, saved Chrome profile, or existing CDP endpoint); omitted means headless Chromium with stealth patches.\n  - `close` — release a tab by `name`, or every tab with `all: true`. `kill: true` also terminates a spawned-app process tree.\n  - `act` — run a list of structured `actions` against an existing tab without writing JS (preferred for routine navigation/interaction). Each step is `{ verb, … }`; verbs: `navigate {url, wait_until?}`, `click {id|selector}`, `type {id|selector, text}`, `fill {selector, value}`, `select {selector, values}`, `press {key, selector?}`, `scroll {dx?, dy?}`, `back`, `wait {selector?|ms?}`, `observe {viewport_only?, include_all?}`, `extract {format?}`, `screenshot`. Address elements by the numeric `id` from a prior `observe` (preferred) or a selector. Steps run in order; the tool returns per-step results.\n  - `run` — execute JS against an existing tab. `code` is the body of an async function with `page`, `browser`, `tab`, `display`, `assert`, `wait` in scope. The return value is JSON-stringified into the tool result; `display(value)` calls accumulate text/images. Use `run` only when an `act` verb does not cover what you need.\n- Tabs survive across `run` calls and across in-process subagents. Open once, reuse many times.\n- Browser kinds: no `app` launches headless Chromium; `app.path` reuses CDP or kills stale same-path processes before spawning — NEVER use it for a daily Chrome profile; use explicit `app.browser: \"chrome\"` profile mode instead. In profile mode, `path` defaults to installed Chrome/Chromium and `profile_directory` defaults to `\"Default\"`, but `user_data_dir` must name a separate non-default Chrome data directory: Chrome 136+ disables remote debugging for its default data directory. Only Chrome/Chromium executables are admitted; Edge, Brave, Vivaldi, Opera, unknown browser brands, and default Chrome data roots are rejected. Use `app.cdp_url` to attach to an already-authorized browser. Saved-profile/CDP automation has access to that profile's cookies and authenticated accounts. Profile mode refuses a matching non-CDP Chrome instead of killing/relaunching it, and `kill: true` can terminate only a Chrome process GJC launched; `app.cdp_url` is externally owned and disconnect-only. CDP must stay on `127.0.0.1`: it grants full browser-account access.\n- Inside `run`, `tab` exposes high-level helpers (`goto`, `observe`, `id`, `click`, `type`, `fill`, `press`, `waitFor`, `screenshot`, `extract`, …); reach for `page` (raw puppeteer Page) when they don't cover it.\n- Selectors accept CSS as well as puppeteer query handlers: `aria/Sign in`, `text/Continue`, `xpath/…`, `pierce/…`.\n- Runtime diagnostics are opt-in: pass `diagnostics: true` to `open` to subscribe the tab to page `Runtime.exceptionThrown` and `console.error` events. The next successful `act`/`run` response then includes at most 20 `runtimeDiagnostics` entries plus `runtimeDiagnosticsDropped`, then drains them. Entries contain only kind, time, origin-only URL, line/column, and a built-in error class from a fixed allowlist — never path segments, query strings, messages, console arguments, values, or stacks. Output is byte-bounded and marks truncation explicitly.\n- Full reference — helpers, browser kinds, CDP/security details, and more examples — read `gjc://tools/browser.md`.\n</instruction>\n\n<critical>\n- You MUST call `open` before `run` or `act`. Neither implicitly creates a tab.\n- You MUST observe before taking a screenshot to understand page state; screenshot only when visual appearance matters.\n- After a `tab.goto()` or any navigation, prior element ids from `tab.observe()` are invalidated. Re-observe before referencing them.\n- `code` runs with full Node access. Treat it as your code, not sandboxed code.\n</critical>\n\n<examples>\n# Open a tab and read structured page data\n`{\"action\":\"open\",\"name\":\"docs\",\"url\":\"https://example.com\"}`\n`{\"action\":\"act\",\"name\":\"docs\",\"actions\":[{\"verb\":\"observe\"}]}`\n\n# Click an observed element, then fill and submit a form\n`{\"action\":\"act\",\"name\":\"docs\",\"actions\":[{\"verb\":\"click\",\"id\":12},{\"verb\":\"fill\",\"selector\":\"input[name=email]\",\"value\":\"me@example.com\"},{\"verb\":\"click\",\"selector\":\"text/Continue\"}]}`\n\n# Use `run` only when `act` has no suitable verb\n`{\"action\":\"run\",\"name\":\"docs\",\"code\":\"const count = await page.locator('canvas').count(); return { count };\"}`\n</examples>\n\n<output>\n- Per call: any `display(value)` outputs (text/images) followed by the JSON-stringified return value of the `code` function. `run` always produces at least a status line.\n</output>",
+		"description": "Drives a real Chromium tab with full puppeteer access via JS execution.\n\n<instruction>\n- For static web content (articles, docs, issues/PRs, JSON, PDFs, feeds), prefer the `read` tool with a URL. Use this tool only when you need JS execution, authentication, or interactive actions.\n- Four actions:\n  - `open` — acquire (or reuse) a named tab. `name` defaults to `\"main\"`. Optional `url`, `viewport`, and `dialogs: \"accept\" | \"dismiss\"` (auto-handles `alert`/`confirm`/`beforeunload`). The `app` field selects the browser kind (spawned binary, saved Chrome profile, or existing CDP endpoint); omitted means headless Chromium with stealth patches.\n  - `close` — release a tab by `name`, or every tab with `all: true`. `kill: true` also terminates a spawned-app process tree.\n  - `act` — run a list of structured `actions` against an existing tab without writing JS (preferred for routine navigation/interaction). Each step is `{ verb, … }`; verbs: `navigate {url, wait_until?}`, `click {id|selector}`, `type {id|selector, text}`, `fill {selector, value}`, `select {selector, values}`, `press {key, selector?}`, `scroll {dx?, dy?}`, `back`, `wait {selector?|ms?}`, `observe {viewport_only?, include_all?}`, `extract {format?}`, `screenshot`. Address elements by the numeric `id` from a prior `observe` (preferred) or a selector. Steps run in order; the tool returns per-step results.\n  - `run` — execute JS against an existing tab. `code` is the body of an async function with `page`, `browser`, `tab`, `display`, `assert`, `wait` in scope. The return value is JSON-stringified into the tool result; `display(value)` calls accumulate text/images. Use `run` only when an `act` verb does not cover what you need.\n- Tabs survive across `run` calls and across in-process subagents. Open once, reuse many times.\n- Browser kinds: no `app` launches headless Chromium; `app.path` reuses CDP or kills stale same-path processes before spawning — NEVER use it for a daily Chrome profile; use explicit `app.browser: \"chrome\"` profile mode instead. In profile mode, `path` defaults to installed Chrome/Chromium and `profile_directory` defaults to `\"Default\"`, but `user_data_dir` must name a separate non-default Chrome data directory: Chrome 136+ disables remote debugging for its default data directory. Only Chrome/Chromium executables are admitted; Edge, Brave, Vivaldi, Opera, unknown browser brands, and default Chrome data roots are rejected. Use `app.cdp_url` to attach to an already-authorized browser. Saved-profile/CDP automation has access to that profile's cookies and authenticated accounts. Profile mode refuses a matching non-CDP Chrome instead of killing/relaunching it, and `kill: true` can terminate only a Chrome process GJC launched; `app.cdp_url` is externally owned and disconnect-only. CDP must stay on `127.0.0.1`: it grants full browser-account access.\n- Inside `run`, `tab` exposes high-level helpers (`goto`, `observe`, `id`, `click`, `type`, `fill`, `press`, `waitFor`, `screenshot`, `extract`, …); reach for `page` (raw puppeteer Page) when they don't cover it.\n- Selectors must be non-empty strings: CSS or puppeteer query handlers (`aria/Sign in`, `text/Continue`, `xpath/…`, `pierce/…`). In `run`, click numeric observation ids with `(await tab.id(58)).click()`, not `tab.click(58)`. Omit optional selectors for unfocused `tab.press()` or page-level `tab.screenshot()`; null and blank selectors are invalid.\n- Runtime diagnostics are opt-in: pass `diagnostics: true` to `open` to subscribe the tab to page `Runtime.exceptionThrown` and `console.error` events. The next successful `act`/`run` response then includes at most 20 `runtimeDiagnostics` entries plus `runtimeDiagnosticsDropped`, then drains them. Entries contain only kind, time, origin-only URL, line/column, and a built-in error class from a fixed allowlist — never path segments, query strings, messages, console arguments, values, or stacks. Output is byte-bounded and marks truncation explicitly.\n- Full reference — helpers, browser kinds, CDP/security details, and more examples — read `gjc://tools/browser.md`.\n</instruction>\n\n<critical>\n- You MUST call `open` before `run` or `act`. Neither implicitly creates a tab.\n- You MUST observe before taking a screenshot to understand page state; screenshot only when visual appearance matters.\n- After a `tab.goto()` or any navigation, prior element ids from `tab.observe()` are invalidated. Re-observe before referencing them.\n- `code` runs with full Node access. Treat it as your code, not sandboxed code.\n</critical>\n\n<examples>\n# Open a tab and read structured page data\n`{\"action\":\"open\",\"name\":\"docs\",\"url\":\"https://example.com\"}`\n`{\"action\":\"act\",\"name\":\"docs\",\"actions\":[{\"verb\":\"observe\"}]}`\n\n# Click an observed element, then fill and submit a form\n`{\"action\":\"act\",\"name\":\"docs\",\"actions\":[{\"verb\":\"click\",\"id\":12},{\"verb\":\"fill\",\"selector\":\"input[name=email]\",\"value\":\"me@example.com\"},{\"verb\":\"click\",\"selector\":\"text/Continue\"}]}`\n\n# Use `run` only when `act` has no suitable verb\n`{\"action\":\"run\",\"name\":\"docs\",\"code\":\"const count = await page.locator('canvas').count(); return { count };\"}`\n</examples>\n\n<output>\n- Per call: any `display(value)` outputs (text/images) followed by the JSON-stringified return value of the `code` function. `run` always produces at least a status line.\n</output>",
 		"parameters": {
 			"type": "object",
 			"properties": {
@@ -2068,7 +2068,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"task": {
 		"name": "task",
 		"label": "Task",
-		"description": "Launches subagents to parallelize workflows.\n\n- Results are delivered automatically when complete.\n- The tool result lists the assigned task ids (e.g. `0-AuthLoader`) — those are the live agent ids.\n- Use `subagent` action `inspect` or `list` to snapshot manager state.\n- To wait or cancel, use the `subagent` tool; its await/cancel doctrine is authoritative.\n\nSubagents have no conversation history. Every fact, file path, and direction they need MUST be explicit in `context` or `assignment`.\n\n<parameters>\n- `agent`: agent type for all tasks\n- `tasks`: tasks to execute in parallel\n - `.id`: filesystem-safe, ≤48 chars, matching `[A-Za-z0-9][A-Za-z0-9_-]*`; prefer CamelCase\n - `.description`: UI label only — subagent never sees it\n - `.assignment`: complete self-contained instructions; one-liners and missing acceptance criteria are PROHIBITED\n- `context`: shared background prepended to every assignment; session-specific only\n- `.inheritContext` (optional): fork-context mode for seeding the subagent with sanitized parent conversation. Omit it or set `\"none\"` for no copied context. `\"receipt\"` copies a minimal receipt-sized snapshot, `\"last-turn\"` copies only the latest exchange, `\"bounded\"` copies the bounded default snapshot, and `\"full\"` copies a larger snapshot up to the configured/model token cap. Non-`none` modes work only when global `task.forkContext.enabled` is true and the target agent declares `forkContext: allowed`; otherwise the call is rejected. Bundled agents that support it: `executor`, `architect`. Use inherited context only when the subagent's value depends on parent context; cloned tokens are billed to the child as fresh input and surfaced in task receipts as fork-context cloned-token accounting.\n\n- `schema`: JTD schema for expected structured output (do not put format rules in assignments)\n- `spawnPlan` (optional): required before any batch with more than 4 tasks; include whyParallel, whyNotLocal, independence, expectedReceiptShape, and maxInlineTokens.\n</parameters>\n\n<rules>\n- HARD runtime gate: calls with more than 4 tasks are rejected before any child launches unless `spawnPlan` is complete.\n- NEVER assign tasks to run project-wide build/test/lint. Caller verifies after the batch.\n- **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates and formatters. You run them once at the end across the union of changed files — avoids redundant runs and racing formatter passes.\n- Each task: ≤3–5 explicit files. No globs, no \"update all\", no package-wide scope. Fan out to a cluster instead.\n- Pass large payloads via `local://<path>` URIs, not inline.\n- Put shared constraints in `context` once; do not duplicate across assignments.\n- Prefer agents that investigate **and** edit in one pass; only spin a read-only discovery step when affected files are genuinely unknown.\n</rules>\n\n<parallelization>\nTest: can task B run correctly without seeing A's output? If no, sequence A → B.\nSequential when one task produces a contract (types, API, schema, core module) the other consumes.\nParallel when tasks touch disjoint files or are independent refactors/tests.\n</parallelization>\n\n<context-fmt>\n# Goal         ← one sentence: what the batch accomplishes\n# Constraints  ← MUST/NEVER rules and session decisions\n# Contract     ← exact types/signatures if tasks share an interface\n</context-fmt>\n\n<assignment-fmt>\n# Target       ← exact files and symbols; explicit non-goals\n# Change       ← step-by-step add/remove/rename; APIs and patterns\n# Acceptance   ← observable result; no project-wide commands\n</assignment-fmt>\n\n<agents>\n# executor\nAutonomous implementation agent for bounded code changes, fixes, and verification-ready edits\n\n# architect\nRead-only architecture and code-review agent with severity-rated findings and status verdicts\n\n# planner\nRead-only planning agent for sequencing, acceptance criteria, risks, and handoff shape\n\n# critic\nRead-only plan critic that approves only actionable, verifiable execution plans\n</agents>",
+		"description": "Launches subagents to parallelize workflows.\n\n- Results are delivered automatically when complete.\n- The tool result lists the assigned task ids (e.g. `0-AuthLoader`) — those are the live agent ids.\n- Use `subagent` action `inspect` or `list` to snapshot manager state.\n- To wait or cancel, use the `subagent` tool; its await/cancel doctrine is authoritative.\n\nSubagents have no conversation history. Every fact, file path, and direction they need MUST be explicit in `context` or `assignment`.\n\n<parameters>\n- `agent`: agent type for all tasks\n- `tasks`: tasks to execute in parallel\n - `.id`: filesystem-safe, ≤48 chars, matching `[A-Za-z0-9][A-Za-z0-9_-]*`; prefer CamelCase\n - `.description`: UI label only — subagent never sees it\n - `.assignment`: complete self-contained instructions; one-liners and missing acceptance criteria are PROHIBITED\n- `context`: shared background prepended to every assignment; session-specific only\n- `.inheritContext` (optional): fork-context mode for seeding the subagent with sanitized parent conversation. Omit it or set `\"none\"` for no copied context. `\"receipt\"` copies a minimal receipt-sized snapshot, `\"last-turn\"` copies only the latest exchange, `\"bounded\"` copies the bounded default snapshot, and `\"full\"` copies a larger snapshot up to the configured/model token cap. Non-`none` modes work only when global `task.forkContext.enabled` is true and the target agent declares `forkContext: allowed`; otherwise the call is rejected. Bundled agents that support it: `executor`, `architect`. Use inherited context only when the subagent's value depends on parent context; cloned tokens are billed to the child as fresh input and surfaced in task receipts as fork-context cloned-token accounting.\n\n- `schema`: JTD schema for expected structured output (do not put format rules in assignments)\n- `spawnPlan` (optional): required before any batch with more than 4 tasks; include whyParallel, whyNotLocal, independence, expectedReceiptShape, and maxInlineTokens.\n\n- `repositoryBinding`: optional authoritative repository/worktree identity. It must match the active session and cannot authorize a foreign repository from this session. For another approved repository, start a fresh session rooted there (for example, `gjc --cwd <approved-worktree>`); do not use `/move` because materialized tasks retain their original binding.\n</parameters>\n\n<rules>\n- HARD runtime gate: calls with more than 4 tasks are rejected before any child launches unless `spawnPlan` is complete.\n- NEVER assign tasks to run project-wide build/test/lint. Caller verifies after the batch.\n- **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates and formatters. You run them once at the end across the union of changed files — avoids redundant runs and racing formatter passes.\n- Each task: ≤3–5 explicit files. No globs, no \"update all\", no package-wide scope. Fan out to a cluster instead.\n- Pass large payloads via `local://<path>` URIs, not inline.\n- Put shared constraints in `context` once; do not duplicate across assignments.\n- Prefer agents that investigate **and** edit in one pass; only spin a read-only discovery step when affected files are genuinely unknown.\n</rules>\n\n<parallelization>\nTest: can task B run correctly without seeing A's output? If no, sequence A → B.\nSequential when one task produces a contract (types, API, schema, core module) the other consumes.\nParallel when tasks touch disjoint files or are independent refactors/tests.\n</parallelization>\n\n<context-fmt>\n# Goal         ← one sentence: what the batch accomplishes\n# Constraints  ← MUST/NEVER rules and session decisions\n# Contract     ← exact types/signatures if tasks share an interface\n</context-fmt>\n\n<assignment-fmt>\n# Target       ← exact files and symbols; explicit non-goals\n# Change       ← step-by-step add/remove/rename; APIs and patterns\n# Acceptance   ← observable result; no project-wide commands\n</assignment-fmt>\n\n<agents>\n# executor\nAutonomous implementation agent for bounded code changes, fixes, and verification-ready edits\n\n# architect\nRead-only architecture and code-review agent with severity-rated findings and status verdicts\n\n# planner\nRead-only planning agent for sequencing, acceptance criteria, risks, and handoff shape\n\n# critic\nRead-only plan critic that approves only actionable, verifiable execution plans\n</agents>",
 		"parameters": {
 			"type": "object",
 			"properties": {
@@ -2123,7 +2123,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 								]
 							},
 							"repositoryBinding": {
-								"description": "authoritative repository identity; omitted items are stamped from session cwd before discovery/spawn and still fail closed on sibling drift",
+								"description": "authoritative repository identity; omitted items are stamped from session cwd before discovery/spawn and still fail closed on sibling drift. A declared binding must match the active session; use a new session rooted in the approved worktree (for example, gjc --cwd <approved-worktree>) for another repository.",
 								"type": "object",
 								"properties": {
 									"schema": {
@@ -2753,12 +2753,12 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"skill_discovery": {
 		"name": "skill_discovery",
 		"label": "SkillDiscovery",
-		"description": "Discover project and user runtime skills without loading full skill content.\n\n<instruction>\n- Searches canonical GJC skill locations in precedence order: project `.gjc/skills` (ancestors from cwd to repo root, closest first), then user locations under the home directory: canonical `<config>/agent/skills`, configured legacy `<config>/skills`, and historical legacy `.gjc/skills`. `<config>` is the home-relative directory name from `GJC_CONFIG_DIR`, then `PI_CONFIG_DIR`, then `.gjc`; even an absolute-looking configured name is joined beneath `<home>`. Project scope shadows user scope; within a scope, earlier locations above win. Bundled GJC workflow skills (`autoresearch`, `deep-interview`, `ralplan`, `ultragoal`) are always available and cannot be replaced by filesystem skills.\n- Returns thin metadata only: name, description, source scope, path, and use conditions when present.\n- Claude Code (`.claude/skills`) and Codex (`.codex/skills`) layouts are explicit import sources into `.gjc`, never invokable candidates. They are not returned as candidates; instead, each convention skill found in a trusted scope is reported in `diagnostics` with the exact copy command that enables it (copy into `.gjc/skills`), so a skill placed in a documented convention location is discoverable in a normal session without being silently loaded.\n- Discovery is on by default in a normal session. When zero candidates are returned because discovery config is disabled (`skills.enabled` master switch, or `skills.trustProjectSkills` / `skills.trustUserSkills` scope trust), the result carries a `notice` explaining which setting blocked the search — an empty result without a `notice` means the searched scopes genuinely contain no matching skills.\n- When skills were scanned but not advertised (protected-name collision with a bundled workflow skill, include/ignore/disable policy filters, invalid frontmatter, shadowing), the result carries a bounded `diagnostics` list explaining why.\n- To load a selected skill's full `SKILL.md`, invoke it through the existing `skill` tool with the exact `name` returned here.\n</instruction>\n\nInput:\n- `query` (optional): words to match against skill name, description, source, or use conditions.\n- `source` (optional): `all`, `project`, or `user`.\n- `limit` (optional): maximum results, 1-50.",
+		"description": "Discover bundled GJC workflow, project, and user runtime skills without loading full skill content.\n\n<instruction>\n- Includes the four bundled GJC workflow skills (`autoresearch`, `deep-interview`, `ralplan`, `ultragoal`) as `source: \"bundled\"` candidates from the generated bundled catalog; they are always available, cannot be replaced by filesystem copies, and are included for `source: \"all\"` but excluded by explicit `source: \"project\"`/`\"user\"` requests.\n- Returns thin metadata only: name, description, source scope, path, and use conditions when present. Bundled paths are stable catalog identifiers, not filesystem paths.\n- In trusted Git projects, `.gjc/skills` may be a symlink to a directory inside the same repository (for example `../.agents/skills`). Link and target identities remain checked through body loading; external targets and symlinked user/profile roots are refused. Do not replace a safe project link with copied files to make discovery work.\n- Claude Code (`.claude/skills`) and Codex (`.codex/skills`) layouts are explicit import sources into `.gjc`, never invokable candidates. They are not returned as candidates; instead, each convention skill found in a trusted scope is reported in `diagnostics` with the exact copy command that enables it (copy into `.gjc/skills`), so a skill placed in a documented convention location is discoverable in a normal session without being silently loaded.\n- Discovery is on by default in a normal session. `query` matching is conjunctive substring: every whitespace-separated term must appear in a skill's name, description, source, or use conditions, unless a term equals the exact skill name — one keyword that appears nowhere in the candidate's metadata drops every candidate, so query with exact names or few terms known to appear literally, not topic keyword lists. When zero candidates are returned, the result carries a `notice` if discovery config disabled a requested scope, a non-empty query filtered out scanned skills, or diagnostics explain observed skills that were skipped or filtered. Only an empty result without a `notice` means no skills were scanned and no diagnostics were produced; never report a zero-candidate result as proof no skill exists.\n- When skills were scanned but not advertised (protected-name collision with a bundled workflow skill, include/ignore/disable policy filters, invalid frontmatter, shadowing), the result carries a bounded `diagnostics` list explaining why.\n- To load a selected skill's full `SKILL.md`, invoke it through the existing `skill` tool with the exact `name` returned here.\n</instruction>\n\nInput:\n- `query` (optional): words to match against skill name, description, source, or use conditions. Every term must appear (conjunctive substring), or one term must equal the exact skill name.\n- `source` (optional): `all`, `project`, or `user`.\n- `limit` (optional): maximum results, 1-50.",
 		"parameters": {
 			"type": "object",
 			"properties": {
 				"query": {
-					"description": "words to match against skill name, description, source, or use conditions",
+					"description": "words to match against skill name, description, source, or use conditions; every term must appear (conjunctive substring), or one term must equal the exact skill name",
 					"type": "string"
 				},
 				"source": {
@@ -2784,7 +2784,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 		"strict": true,
 		"deferrable": false,
 		"loadMode": "essential",
-		"summary": "Discover project and user runtime skills by thin metadata"
+		"summary": "Discover bundled GJC workflow, project, and user runtime skills by thin metadata"
 	},
 	"telegram_send": {
 		"name": "telegram_send",
@@ -2904,7 +2904,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"move_session": {
 		"name": "move_session",
 		"label": "Move Session",
-		"description": "Rescope the session to a narrower working directory.\n\nUse this only when the session's working directory is a broad launcher root (for example a\nmulti-repo workspace like `~/Projects`) and the task has clearly converged on one subdirectory\nor repository: after this call, every later turn resolves relative paths and the bash default\ncwd from the new directory, and project-scoped plugins/capabilities reload for it.\n\n- `path` must be an existing directory; relative paths resolve against the current session cwd.\n  The canonical target must be strictly inside the current session directory — moves to a\n  parent, a sibling project, or an unrelated absolute path are refused.\n- A session can be moved this way at most once, and never while another move is running; a\n  rejected call does not consume the move. Use it once the target repo is identified — not\n  speculatively — because the session file and caches move with the session.\n- This tool is unavailable in subagent sessions and restricted profiles; ask the top-level\n  session to rescope instead.",
+		"description": "Rescope the session to a narrower working directory.\n\nUse this only when the session's working directory is a broad launcher root (for example a\nmulti-repo workspace like `~/Projects`) and the task has clearly converged on one subdirectory\nor repository: after this call, every later turn resolves relative paths and the bash default\ncwd from the new directory, and project-scoped plugins/capabilities reload for it.\n\n- `path` must be an existing directory; relative paths resolve against the current session cwd.\n  The canonical target must be strictly inside the current session directory — moves to a\n  parent, a sibling project, or an unrelated absolute path are refused.\n- A session can be moved this way at most once, and never while another move is running; a\n  rejected call does not consume the move. Use it once the target repo is identified — not\n  speculatively — because the session file and caches move with the session.\n- This tool is unavailable in subagent sessions and restricted profiles; ask the top-level\n  session to rescope instead.\n- For an explicitly requested sibling or unrelated repository, start a new session with\n  `gjc --cwd <approved-worktree>` and delegate from there. A task's `repositoryBinding`\n  verifies the session's repository; it cannot authorize relocation. Already-created task\n  tools retain their original repository binding even after a user-driven cwd move.",
 		"parameters": {
 			"type": "object",
 			"properties": {

package/src/tools/ultragoal-ask-guard.ts

@@ -11,28 +11,16 @@ const ULTRAGOAL_ASK_GUARD = Symbol.for("gajae-code.ultragoalAskGuard");
 type GuardedTool = AgentTool & { [ULTRAGOAL_ASK_GUARD]?: true };
 
 export interface UltragoalAskGuardContext {
-	activeSkillState?: { skill?: string; session_id?: string } | null;
+	/**
+	 * GJC session id of the session asking the question. This is the guard's only
+	 * identity input: durable Ultragoal state and the nudge budget are bound to it
+	 * exclusively. Active-skill metadata is deliberately NOT part of this context —
+	 * a snapshot restored from another session carries that session's id, and
+	 * treating it as the caller's identity leaked a foreign run into the guard.
+	 */
 	sessionId?: string | null;
 }
 
-const UPSTREAM_PLANNING_ASK_SKILLS = new Set(["deep-interview", "ralplan"]);
-
-function normalizedActiveSkill(context?: UltragoalAskGuardContext): string | undefined {
-	const skill = context?.activeSkillState?.skill?.trim();
-	return skill || undefined;
-}
-
-function sessionScopedAskGuardId(
-	context: UltragoalAskGuardContext,
-	activeSkill: string | undefined,
-): string | undefined {
-	if (activeSkill !== "ultragoal" && !UPSTREAM_PLANNING_ASK_SKILLS.has(activeSkill ?? "")) return undefined;
-	const activeSessionId = context.activeSkillState?.session_id?.trim();
-	if (activeSessionId) return activeSessionId;
-	const sessionId = context.sessionId?.trim();
-	return sessionId || undefined;
-}
-
 export function formatUltragoalAskBlockMessage(diagnostic: UltragoalAskBlockDiagnostic): string {
 	return [
 		diagnostic.message,
@@ -46,13 +34,13 @@ export async function assertUltragoalAskAllowed(
 	context: UltragoalAskGuardContext = {},
 	agentDir?: string,
 ): Promise<void> {
-	const activeSkill = normalizedActiveSkill(context);
-	// Deep-interview and ralplan are upstream planning workflows whose core gates
-	// are `ask` calls. Scope their Ultragoal check to the current session so stale
-	// or ambiguous Ultragoal durable state from another session cannot hijack those
-	// prompts; same-session active Ultragoal state still falls through to the
-	// blocker/nudge checks below.
-	const sessionId = sessionScopedAskGuardId(context, activeSkill);
+	// Durable Ultragoal state is session-scoped, so only the caller's own run may
+	// block `ask`. An anonymous caller has no run attributable to it, so the guard
+	// fails open instead of falling back to GJC_SESSION_ID or an auto-detected
+	// session: either can name another (possibly dead) session's abandoned run and
+	// would make `ask` unusable for every session in the repository.
+	const sessionId = context.sessionId?.trim();
+	if (!sessionId) return;
 	const diagnostic = await isUltragoalAskBlocked(cwd, { sessionId });
 	if (!diagnostic.active) return;
 	const nudge = await consumeUltragoalAskNudge(cwd, sessionId, agentDir);
@@ -76,6 +64,8 @@ export function guardToolForUltragoalAsk<T extends AgentTool>(
 			return async (...args: unknown[]): Promise<unknown> => {
 				// The wrapper runs BEFORE AskTool.execute(): resolve the nudge
 				// budget against the SESSION profile, never the process-global one.
+				// The caller session id is the only binding, so a foreign session's
+				// durable run can never gate this ask.
 				await assertUltragoalAskAllowed(getCwd(), getContext(), getSessionAgentDir());
 				return Reflect.apply(target.execute, target, args);
 			};

package/src/utils/changelog.ts

@@ -87,9 +87,15 @@ export async function parseChangelog(changelogPath: string): Promise<ChangelogEn
  * dev runs, and `GJC_PACKAGE_DIR` / `PI_PACKAGE_DIR` overrides (which scope to
  * optional package assets like docs/examples and do not influence the
  * binary-identity changelog).
+ *
+ * Parsed once per process and cached: the embedded text is immutable, and the
+ * parse runs on the interactive startup path plus every /changelog invocation.
  */
+let displayChangelogEntriesCache: ChangelogEntry[] | undefined;
+
 export function getDisplayChangelogEntries(): ChangelogEntry[] {
-	return parseChangelogContent(CHANGELOG_TEXT);
+	displayChangelogEntriesCache ??= parseChangelogContent(CHANGELOG_TEXT);
+	return displayChangelogEntriesCache;
 }
 
 export function getInstalledVersionChangelogEntry(

package/src/utils/git.ts

@@ -1266,7 +1266,9 @@ export async function clone(url: string, targetDir: string, options: CloneOption
 	const args = ["clone", "--depth", "1"];
 	if (options.ref) args.push("--branch", options.ref, "--single-branch");
 	else args.push("--single-branch");
-	args.push(url, absoluteTarget);
+	// `--` ends option parsing, so a URL that begins with `-` can never be read as
+	// a git option (`--upload-pack=...` and friends).
+	args.push("--", url, absoluteTarget);
 
 	try {
 		await runEffect(path.dirname(absoluteTarget), args, { signal: options.signal });

package/src/utils/markit.ts

@@ -1,6 +1,7 @@
 import { untilAborted } from "@gajae-code/utils";
 import type { Markit, StreamInfo } from "markit-ai";
 import { ToolAbortError } from "../tools/tool-errors";
+import { ensureMupdfWasmResolution } from "./mupdf-wasm";
 
 export interface MarkitConversionResult {
 	content: string;
@@ -18,6 +19,11 @@ let markit: () => Markit | Promise<Markit> = async () => {
 	return promise;
 };
 
+// #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();
+
 function normalizeExtension(extension: string): string {
 	const trimmed = extension.trim().toLowerCase();
 	if (!trimmed) return ".bin";
@@ -31,6 +37,22 @@ function normalizeError(error: unknown): string {
 	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)})`;
+	}
+	return base;
+}
+
 async function runMarkitConversion<T>(task: (markit: Markit) => Promise<T>, signal?: AbortSignal): Promise<T> {
 	try {
 		const instance = await markit();
@@ -62,7 +84,7 @@ export async function convertFileWithMarkit(filePath: string, signal?: AbortSign
 		if (error instanceof ToolAbortError) {
 			throw error;
 		}
-		return { content: "", ok: false, error: normalizeError(error) };
+		return { content: "", ok: false, error: await describeConversionError(error) };
 	}
 }
 
@@ -84,6 +106,6 @@ export async function convertBufferWithMarkit(
 		if (error instanceof ToolAbortError) {
 			throw error;
 		}
-		return { content: "", ok: false, error: normalizeError(error) };
+		return { content: "", ok: false, error: await describeConversionError(error) };
 	}
 }

package/src/utils/mupdf-wasm.ts

@@ -0,0 +1,26 @@
+/**
+ * MuPDF wasm asset resolution inside compiled binaries (#5433).
+ *
+ * `mupdf`'s Emscripten loader resolves `mupdf-wasm.wasm` relative to
+ * `import.meta.url` (or `scriptDirectory`). Inside a `bun build --compile`
+ * bunfs that path points at the bunfs root where the asset does not exist,
+ * so every mupdf import aborted with
+ * `ENOENT: ... /$bunfs/root/mupdf-wasm.wasm`.
+ *
+ * The wasm is embedded via `with { type: "file" }`, which lands it at a
+ * hashed bunfs path. MuPDF's top-level factory call reads
+ * `globalThis["$libmupdf_wasm_Module"]`, so seeding that config with a
+ * `locateFile` hook that returns the embedded asset path makes the loader
+ * read the wasm from the bunfs directly — no disk sidecar needed.
+ *
+ * This must run before the first `import("mupdf")` anywhere in the process.
+ */
+import mupdfWasmPath from "../../../../node_modules/mupdf/dist/mupdf-wasm.wasm" with { type: "file" };
+
+const MODULE_CONFIG_KEY = "$libmupdf_wasm_Module";
+
+export function ensureMupdfWasmResolution(): void {
+	const globalScope = globalThis as typeof globalThis & Record<string, unknown>;
+	if (globalScope[MODULE_CONFIG_KEY] !== undefined) return;
+	globalScope[MODULE_CONFIG_KEY] = { locateFile: () => String(mupdfWasmPath) };
+}