@gajae-code/coding-agent 0.13.2 → 0.14.0

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

@@ -58,7 +58,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"bash": {
 		"name": "bash",
 		"label": "Bash",
-		"description": "Executes bash command in shell session for terminal operations like git, bun, cargo, python.\n\n<instruction>\n- Use `cwd` to set working directory, not `cd dir && …`\n- Prefer `env: { NAME: \"…\" }` for multiline, quote-heavy, or untrusted values; reference as `$NAME`\n- Quote variable expansions like `\"$NAME\"` to preserve exact content\n- PTY mode is opt-in: set `pty: true` only when the command needs a real terminal (e.g. `sudo`, `ssh` requiring user input); default is `false`\n- Use `;` only when later commands should run regardless of earlier failures\n- Internal URIs (`agent://`, `artifact://`, `rule://`, `local://`) are auto-resolved to filesystem paths\n</instruction>\n\n<critical>\n- Use bash only for terminal operations that dedicated tools do not cover.\n- Never pipe through `| head -n N` or `| tail -n N` — output is already truncated. Recover omitted output only when the result includes an `artifact://<id>` footer or metadata reference; truncation without a reference leaves the visible output incomplete with no recoverable artifact.\n- Never redirect with `2>&1` or `2>/dev/null` — stdout and stderr are already merged.\n</critical>\n\n<output>\n- Returns output and exit code.\n- Truncated output is recoverable only when the result includes an `artifact://<id>` footer or metadata reference; truncation evidence without such a reference means the visible output is incomplete and no artifact is recoverable.\n- Exit codes shown on non-zero exit\n</output>\n# Output minimizer\n\n- Bash stdout/stderr may be rewritten before you see it: long output keeps only the last 1 KiB by default to reduce noise and input-token use. Explicit `tools.artifactTailBytes` / `tools.artifactHeadBytes` settings can set the tail budget or retain both ends. Prefer focused commands and dedicated `search`/`find` tools over producing broad output. Test/lint runners (e.g. `bun test`, `cargo test`, ESLint) are also passed through heuristic filters that drop noise and keep failures.\n- When the local minimizer changes visible text, successful artifact storage appends a footer containing an `artifact://<id>` reference. Complete artifacts are labeled as full output; hard-capped artifacts report omitted bytes instead. If artifact allocation/storage is unavailable before a writer/save operation is attempted, truncation may have no reference or diagnostic. If an artifact writer/save operation is attempted and fails, a bounded diagnostic is emitted without inventing an artifact URI.\n- ACP/client-terminal output can arrive already truncated from the beginning. Treat any truncation notice or metadata as evidence that the visible tail is incomplete. Recover omitted output only when an `artifact://` footer or metadata reference is present; truncation evidence without a reference means the visible output is incomplete and no artifact is recoverable. Output with neither truncation evidence nor an artifact reference is the complete emitted output.",
+		"description": "Executes bash command in shell session for terminal operations like git, bun, cargo, python.\n\n<instruction>\n- Use `cwd` to set working directory, not `cd dir && …`\n- Prefer `env: { NAME: \"…\" }` for multiline, quote-heavy, or untrusted values; reference as `$NAME`\n- Quote variable expansions like `\"$NAME\"` to preserve exact content\n- PTY mode is opt-in: set `pty: true` only when the command needs a real terminal (e.g. `sudo`, `ssh` requiring user input); default is `false`\n- Use `;` only when later commands should run regardless of earlier failures\n- Internal URIs (`agent://`, `artifact://`, `rule://`, `local://`) are auto-resolved to filesystem paths\n</instruction>\n\n<critical>\n- Use bash only for terminal operations that dedicated tools do not cover.\n- Never pipe through `| head -n N` or `| tail -n N` — output is already truncated. Recover omitted output only when the result includes an `artifact://<id>` footer or metadata reference; truncation without a reference leaves the visible output incomplete with no recoverable artifact.\n- Never redirect with `2>&1` or `2>/dev/null` — stdout and stderr are already merged.\n</critical>\n\n<output>\n- Returns output and exit code.\n- Truncated output is recoverable only when the result includes an `artifact://<id>` footer or metadata reference; truncation evidence without such a reference means the visible output is incomplete and no artifact is recoverable.\n- Exit codes shown on non-zero exit\n</output>\n\n# Waiting for background work\n\n- A long blocking `sleep N` (or `sleep N && …`) emits nothing for the entire duration and is indistinguishable from a hung session. Never use it to wait for subagents or background jobs.\n- To wait for detached task subagents, use `subagent await` — it emits periodic liveness while waiting.\n- To wait for background bash jobs, use `job poll` — it reports status on each tick.\n- Short sleeps for rate-limiting or pacing (e.g. `sleep 2` between retries) are fine.\n\n# Output minimizer\n\n- Bash stdout/stderr may be rewritten before you see it: long output keeps only the last 1 KiB by default to reduce noise and input-token use. Explicit `tools.artifactTailBytes` / `tools.artifactHeadBytes` settings can set the tail budget or retain both ends. Prefer focused commands and dedicated `search`/`find` tools over producing broad output. Test/lint runners (e.g. `bun test`, `cargo test`, ESLint) are also passed through heuristic filters that drop noise and keep failures.\n- When the local minimizer changes visible text, successful artifact storage appends a footer containing an `artifact://<id>` reference. Complete artifacts are labeled as full output; hard-capped artifacts report omitted bytes instead. If artifact allocation/storage is unavailable before a writer/save operation is attempted, truncation may have no reference or diagnostic. If an artifact writer/save operation is attempted and fails, a bounded diagnostic is emitted without inventing an artifact URI.\n- ACP/client-terminal output can arrive already truncated from the beginning. Treat any truncation notice or metadata as evidence that the visible tail is incomplete. Recover omitted output only when an `artifact://` footer or metadata reference is present; truncation evidence without a reference means the visible output is incomplete and no artifact is recoverable. Output with neither truncation evidence nor an artifact reference is the complete emitted output.",
 		"parameters": {
 			"type": "object",
 			"properties": {
@@ -1073,7 +1073,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. 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 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>",
 		"parameters": {
 			"type": "object",
 			"properties": {
@@ -1100,7 +1100,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 					"properties": {
 						"path": {
 							"type": "string",
-							"description": "binary path to spawn"
+							"description": "binary path to spawn (default: the installed Chrome/Chromium)"
 						},
 						"cdp_url": {
 							"type": "string",
@@ -1115,11 +1115,11 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 						},
 						"user_data_dir": {
 							"type": "string",
-							"description": "Chrome user data directory containing profiles"
+							"description": "non-default Chrome user data directory containing profiles (required for Chrome 136+ CDP)"
 						},
 						"profile_directory": {
 							"type": "string",
-							"description": "Chrome profile directory name, e.g. Profile 10"
+							"description": "Chrome profile directory name, e.g. \"Profile 10\" (default \"Default\")"
 						},
 						"background": {
 							"type": "boolean",
@@ -2708,7 +2708,7 @@ 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 only custom runtime skill locations: nearest project `.gjc/skills`; then, 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>`. Duplicate names use that exact precedence. Built-in, bundled, and internal workflow skills are intentionally excluded.\n- Returns thin metadata only: name, description, source scope, path, and use conditions when present.\n- When zero candidates are returned because discovery config is disabled (`skills.enabled`, `skills.enablePiProject`, `skills.enablePiUser`), 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- 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 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 (`deep-interview`, `ralplan`, `team`, `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.",
 		"parameters": {
 			"type": "object",
 			"properties": {

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

@@ -41,7 +41,11 @@ export function formatUltragoalAskBlockMessage(diagnostic: UltragoalAskBlockDiag
 	].join("\n");
 }
 
-export async function assertUltragoalAskAllowed(cwd: string, context: UltragoalAskGuardContext = {}): Promise<void> {
+export async function assertUltragoalAskAllowed(
+	cwd: string,
+	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
@@ -51,7 +55,7 @@ export async function assertUltragoalAskAllowed(cwd: string, context: UltragoalA
 	const sessionId = sessionScopedAskGuardId(context, activeSkill);
 	const diagnostic = await isUltragoalAskBlocked(cwd, { sessionId });
 	if (!diagnostic.active) return;
-	const nudge = await consumeUltragoalAskNudge(cwd, sessionId);
+	const nudge = await consumeUltragoalAskNudge(cwd, sessionId, agentDir);
 	if (nudge.nudged) throw new ToolError(nudge.message);
 	throw new ToolError(formatUltragoalAskBlockMessage(diagnostic));
 }
@@ -60,6 +64,7 @@ export function guardToolForUltragoalAsk<T extends AgentTool>(
 	tool: T,
 	getCwd: () => string,
 	getContext: () => UltragoalAskGuardContext = () => ({}),
+	getSessionAgentDir: () => string | undefined = () => undefined,
 ): T {
 	if (tool.name !== "ask") return tool;
 	const candidate = tool as GuardedTool;
@@ -69,7 +74,9 @@ export function guardToolForUltragoalAsk<T extends AgentTool>(
 			if (prop === ULTRAGOAL_ASK_GUARD) return true;
 			if (prop !== "execute") return Reflect.get(target, prop, receiver);
 			return async (...args: unknown[]): Promise<unknown> => {
-				await assertUltragoalAskAllowed(getCwd(), getContext());
+				// The wrapper runs BEFORE AskTool.execute(): resolve the nudge
+				// budget against the SESSION profile, never the process-global one.
+				await assertUltragoalAskAllowed(getCwd(), getContext(), getSessionAgentDir());
 				return Reflect.apply(target.execute, target, args);
 			};
 		},

package/src/utils/herdr-pane.ts

@@ -0,0 +1,345 @@
+/**
+ * Herdr agent lifecycle reporter.
+ *
+ * When gjc runs inside a Herdr pane (`HERDR_ENV=1`), report semantic agent
+ * state through Herdr's documented custom-integration API so the pane is
+ * recognized as the "gjc" agent in Herdr's sidebar and workspace rollups:
+ *
+ *   - `idle`    — waiting at the input prompt (also reported at startup)
+ *   - `working` — agent turn in progress
+ *   - `blocked` — waiting on a user decision (ask tool)
+ *
+ * The session title is reported through the same API as display-only pane
+ * metadata, so a pane shows what it is working on instead of a bare agent
+ * label. Herdr renders that title on the pane border and exposes it to the
+ * sidebar as the `pane` token.
+ *
+ * Reporting is strictly best-effort and never blocks or fails a turn. Outside
+ * a Herdr pane every entry point is a no-op. Herdr also clears the authority
+ * when the pane's foreground process exits, so a hard kill still recovers.
+ *
+ * Original implementation contributed by @ox8884 (#4318).
+ */
+import { logger } from "@gajae-code/utils";
+
+const HERDR_ENV = "HERDR_ENV";
+const HERDR_PANE_ID_ENV = "HERDR_PANE_ID";
+const HERDR_BIN_PATH_ENV = "HERDR_BIN_PATH";
+const HERDR_COMMAND = "herdr";
+const AGENT_LABEL = "gjc";
+const SOURCE = "custom:gjc";
+/** A report is a fire-and-forget status ping; a hung herdr CLI must never accumulate. */
+const HERDR_REPORT_TIMEOUT_MS = 1500;
+/** Release runs on the shutdown path, so it is bounded even tighter. */
+const HERDR_RELEASE_TIMEOUT_MS = 1000;
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/g;
+/** Herdr truncates to the pane width anyway; this only bounds the argv. */
+const MAX_PANE_TITLE_CHARS = 120;
+
+/**
+ * Metadata reports carry their own per-source sequence in Herdr, independent of
+ * the lifecycle-state sequence, so title updates need a counter of their own.
+ * Module scope because the title is a property of the process, not of one
+ * reporter instance: `setSessionTerminalTitle` is called from controllers that
+ * never see the reporter.
+ */
+let metadataSeq = 0;
+
+function nextMetadataSeq(): number {
+	metadataSeq += 1;
+	return metadataSeq;
+}
+
+export type HerdrAgentState = "idle" | "working" | "blocked";
+
+export interface HerdrPaneEnvironment {
+	paneId: string;
+	binPath: string;
+}
+
+export interface HerdrReportProcess {
+	exited: Promise<number>;
+	kill(): void;
+	unref(): void;
+}
+
+export interface HerdrReporterOptions {
+	env?: NodeJS.ProcessEnv;
+	which?: (command: string) => string | null;
+	spawn?: (
+		command: string[],
+		options: { env: NodeJS.ProcessEnv; stdin: "ignore"; stdout: "ignore"; stderr: "ignore" },
+	) => HerdrReportProcess;
+}
+
+/** Session event shape consumed by the reporter. Narrow on purpose: the state
+ * machine is driven only by lifecycle transitions, never by message content. */
+export interface HerdrSessionEvent {
+	type: string;
+	toolName?: string;
+}
+
+export interface HerdrReporter {
+	/** Report a new agent state. Deduplicated against the last reported state. */
+	report(state: HerdrAgentState): void;
+	/** Release this pane's lifecycle authority and stop listening. Idempotent. */
+	release(): void;
+	/** Current reported state, for tests and diagnostics. */
+	readonly state: HerdrAgentState | null;
+}
+
+function defaultSpawn(
+	command: string[],
+	options: { env: NodeJS.ProcessEnv; stdin: "ignore"; stdout: "ignore"; stderr: "ignore" },
+): HerdrReportProcess {
+	return Bun.spawn(command, options);
+}
+
+/**
+ * Resolve the pane environment. Returns null unless gjc is demonstrably inside
+ * a Herdr pane AND a herdr binary is resolvable.
+ *
+ * `HERDR_BIN_PATH` is honored first because Herdr sets it for its own panes;
+ * otherwise the binary is resolved from PATH. No home-directory guessing: an
+ * unverified path scavenged from an install layout is a command this process
+ * would execute, and PATH/`HERDR_BIN_PATH` are the trust boundary Herdr itself
+ * documents.
+ */
+export function resolveHerdrPaneEnvironment(options: HerdrReporterOptions = {}): HerdrPaneEnvironment | null {
+	const env = options.env ?? process.env;
+	if (env[HERDR_ENV]?.trim() !== "1") return null;
+
+	const paneId = env[HERDR_PANE_ID_ENV]?.trim();
+	// A pane id is forwarded verbatim as an argv element; reject anything that is
+	// not an opaque identifier rather than trusting the surrounding environment.
+	// The leading character must be alphanumeric so a pane id can never be parsed
+	// by the herdr CLI as an option.
+	if (!paneId || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(paneId)) return null;
+
+	const configured = env[HERDR_BIN_PATH_ENV]?.trim();
+	if (configured) return { paneId, binPath: configured };
+
+	const which = options.which ?? Bun.which;
+	try {
+		const resolved = which(HERDR_COMMAND);
+		return resolved ? { paneId, binPath: resolved } : null;
+	} catch (error) {
+		logger.debug("herdr binary lookup failed", { error: String(error) });
+		return null;
+	}
+}
+
+/** Build the argv for a state report. Exported for tests. */
+export function buildHerdrReportArgs(paneId: string, state: HerdrAgentState, seq: number): string[] {
+	return [
+		"pane",
+		"report-agent",
+		paneId,
+		"--source",
+		SOURCE,
+		"--agent",
+		AGENT_LABEL,
+		"--state",
+		state,
+		"--seq",
+		String(seq),
+	];
+}
+
+/** Build the argv for an authority release. Exported for tests. */
+export function buildHerdrReleaseArgs(paneId: string, seq: number): string[] {
+	return ["pane", "release-agent", paneId, "--source", SOURCE, "--agent", AGENT_LABEL, "--seq", String(seq)];
+}
+
+/**
+ * Collapse a session name into a single-line pane title. Control characters are
+ * removed rather than escaped: the value reaches a terminal surface, and a
+ * model-generated session name must never be able to inject escapes.
+ */
+export function sanitizeHerdrPaneTitle(title: string | undefined): string | undefined {
+	if (!title) return undefined;
+	const sanitized = title.replace(CONTROL_CHARS, " ").replace(/\s+/g, " ").trim();
+	if (!sanitized) return undefined;
+	if (sanitized.length <= MAX_PANE_TITLE_CHARS) return sanitized;
+	// Truncate by UTF-16 code units (the Herdr argv is a string), then step back
+	// if the cut lands on the high surrogate of a pair so the title never ends
+	// with a lone surrogate.
+	let bound = MAX_PANE_TITLE_CHARS;
+	const last = sanitized.charCodeAt(bound - 1);
+	if (last >= 0xd800 && last <= 0xdbff) bound -= 1;
+	return sanitized.slice(0, bound).trimEnd();
+}
+
+/** Build the argv for a pane title report. Exported for tests. */
+export function buildHerdrTitleArgs(paneId: string, title: string, seq: number): string[] {
+	return [
+		"pane",
+		"report-metadata",
+		paneId,
+		"--source",
+		SOURCE,
+		"--agent",
+		AGENT_LABEL,
+		"--title",
+		title,
+		"--seq",
+		String(seq),
+	];
+}
+
+/** Build the argv that retracts a previously reported pane title. Exported for tests. */
+export function buildHerdrClearTitleArgs(paneId: string, seq: number): string[] {
+	return ["pane", "report-metadata", paneId, "--source", SOURCE, "--clear-title", "--seq", String(seq)];
+}
+
+/**
+ * Spawn a detached, timeout-bounded herdr CLI invocation. Every failure mode is
+ * swallowed: a status ping must never surface in a session.
+ */
+function runHerdrCommand(binPath: string, args: string[], timeoutMs: number, options: HerdrReporterOptions): void {
+	const env = options.env ?? process.env;
+	const spawn = options.spawn ?? defaultSpawn;
+
+	let proc: HerdrReportProcess;
+	try {
+		proc = spawn([binPath, ...args], {
+			env,
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+		});
+	} catch (error) {
+		// Missing/unexecutable binary: reporting is best-effort, never fatal.
+		logger.debug("herdr report failed to start", { error: String(error) });
+		return;
+	}
+	proc.unref();
+	const timer = setTimeout(() => {
+		try {
+			proc.kill();
+		} catch {}
+	}, timeoutMs);
+	timer.unref?.();
+	// Bun.spawn surfaces spawn failure through `exited` rejection, so this
+	// handler is what keeps an ENOENT from becoming an unhandled rejection.
+	void proc.exited
+		.then(exitCode => {
+			clearTimeout(timer);
+			if (exitCode !== 0) logger.debug("herdr report exited non-zero", { exitCode });
+		})
+		.catch(error => {
+			clearTimeout(timer);
+			logger.debug("herdr report failed", { error: String(error) });
+		});
+}
+
+/**
+ * Report the current session title for this pane. No-op outside a Herdr pane or
+ * when the session has no usable name, so a pane keeps the last real title
+ * instead of flickering to a placeholder during startup or a rename.
+ */
+export function syncHerdrPaneTitle(sessionName: string | undefined, options: HerdrReporterOptions = {}): void {
+	const title = sanitizeHerdrPaneTitle(sessionName);
+	if (!title) return;
+
+	const paneEnv = resolveHerdrPaneEnvironment(options);
+	if (!paneEnv) return;
+
+	runHerdrCommand(
+		paneEnv.binPath,
+		buildHerdrTitleArgs(paneEnv.paneId, title, nextMetadataSeq()),
+		HERDR_REPORT_TIMEOUT_MS,
+		options,
+	);
+}
+
+/**
+ * Create a reporter bound to a pane. `subscribe` supplies the session event
+ * stream and is parameterized so the state machine is testable without a live
+ * session.
+ */
+export function createHerdrReporter(
+	paneEnv: HerdrPaneEnvironment,
+	subscribe: (listener: (event: HerdrSessionEvent) => void) => () => void,
+	options: HerdrReporterOptions = {},
+): HerdrReporter {
+	let seq = 0;
+	let currentState: HerdrAgentState | null = null;
+	let released = false;
+	/** Nesting depth of blocking ask calls; a nested ask must not unblock early. */
+	let askDepth = 0;
+
+	const run = (args: string[], timeoutMs: number): void => {
+		runHerdrCommand(paneEnv.binPath, args, timeoutMs, options);
+	};
+
+	const report = (state: HerdrAgentState): void => {
+		if (released || state === currentState) return;
+		currentState = state;
+		seq += 1;
+		run(buildHerdrReportArgs(paneEnv.paneId, state, seq), HERDR_REPORT_TIMEOUT_MS);
+	};
+
+	let unsubscribe: (() => void) | null = subscribe(event => {
+		switch (event.type) {
+			case "agent_start":
+				askDepth = 0;
+				report("working");
+				break;
+			case "agent_end":
+				askDepth = 0;
+				report("idle");
+				break;
+			case "tool_execution_start":
+				if (event.toolName === "ask") {
+					askDepth += 1;
+					report("blocked");
+				}
+				break;
+			case "tool_execution_end":
+				if (event.toolName === "ask" && askDepth > 0) {
+					askDepth -= 1;
+					if (askDepth === 0) report("working");
+				}
+				break;
+		}
+	});
+
+	// A freshly started agent is idle at the prompt.
+	report("idle");
+
+	return {
+		report,
+		release() {
+			if (released) return;
+			released = true;
+			unsubscribe?.();
+			unsubscribe = null;
+			seq += 1;
+			run(buildHerdrReleaseArgs(paneEnv.paneId, seq), HERDR_RELEASE_TIMEOUT_MS);
+			// The pane outlives gjc, so a session title left behind would label a
+			// plain shell with the work of a session that already ended.
+			run(buildHerdrClearTitleArgs(paneEnv.paneId, nextMetadataSeq()), HERDR_RELEASE_TIMEOUT_MS);
+		},
+		get state() {
+			return currentState;
+		},
+	};
+}
+
+/**
+ * Install the Herdr reporter for a running session. No-op outside a Herdr pane.
+ * Returns the reporter so callers can release it deterministically, or null.
+ */
+export function installHerdrReporter(
+	subscribe: (listener: (event: HerdrSessionEvent) => void) => () => void,
+	options: HerdrReporterOptions = {},
+): HerdrReporter | null {
+	const paneEnv = resolveHerdrPaneEnvironment(options);
+	if (!paneEnv) return null;
+
+	const reporter = createHerdrReporter(paneEnv, subscribe, options);
+	// `exit` handlers must be synchronous; release() only spawns and returns.
+	process.once("exit", reporter.release);
+	return reporter;
+}

package/src/utils/title-generator.ts

@@ -10,6 +10,7 @@ import { resolveRoleSelection } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
 import titleSystemPrompt from "../prompts/system/title-system.md" with { type: "text" };
 import { syncCmuxWorkspaceTitle } from "./cmux-workspace";
+import { syncHerdrPaneTitle } from "./herdr-pane";
 
 const TITLE_SYSTEM_PROMPT = prompt.render(titleSystemPrompt);
 
@@ -220,6 +221,7 @@ export function setTerminalTitle(title: string): void {
 export function setSessionTerminalTitle(sessionName: string | undefined, cwd?: string): void {
 	setTerminalTitle(formatSessionTerminalTitle(sessionName, cwd));
 	void syncCmuxWorkspaceTitle(sessionName);
+	syncHerdrPaneTitle(sessionName);
 }
 
 /**

package/src/web/scrapers/index.ts

@@ -161,13 +161,15 @@ export {
 	handleYouTube,
 };
 
-export const specialHandlers: SpecialHandler[] = [
+export const specialHandlers: SpecialHandler[] = [];
+
+specialHandlers.push(
 	// Git hosting
 	handleGitHubGist,
 	handleGitHub,
 	handleGitLab,
 	// Video/Media
-	handleYouTube,
+	(url, timeout, signal) => handleYouTube(url, timeout, signal),
 	handleVimeo,
 	handleSpotify,
 	handleDiscogs,
@@ -203,7 +205,7 @@ export const specialHandlers: SpecialHandler[] = [
 	handleBrew,
 	handlePyPI,
 	handleCratesIo,
-	handleDockerHub,
+	(url, timeout, signal) => handleDockerHub(url, timeout, signal),
 	handleFdroid,
 	handleFlathub,
 	handleGoPkg,
@@ -249,4 +251,4 @@ export const specialHandlers: SpecialHandler[] = [
 	handleSpdx,
 	handleWikidata,
 	handleWikipedia,
-];
+);

package/dist/types/cli/malloc-env-guard.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/defaults/gjc-defaults.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/memory-backend/lazy-loading.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime/boot-ordering.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime/lazy-service.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime/network-prewarm-service.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime/workspace-tree-service.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime-mcp/config.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime-mcp/http.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime-mcp/manager-pool.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime-mcp/pool-key.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime-mcp/pool.test.d.ts

@@ -1 +0,0 @@
-export {};