github-router 0.3.162 → 0.3.168

package/dist/browser-ext/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": 3,
   "name": "github-router browser bridge",
   "short_name": "gh-router-browser",
-  "version": "0.3.162",
+  "version": "0.3.168",
   "description": "Bridge between Claude (via github-router /mcp) and the browser. Implements tab control, navigation, clicks, form fill, downloads, screenshots, devtools eval. Blocks navigation to chrome://settings.",
   "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqJElxuBlonBS3TVW9FJN0mGTtShB3L1hoaYf6k39SOr1ogGYmF90EjRxy1i21k9wQQjPf26bcBu/9X67KrQjQV0uB38CaNukgiSeoLjfptN811u+PJHx6BP+jx3Qa6/3VenNPxHC8WEU0GXql8QSjIHEyCwKb6fMASXOK94JyB5Ywov2x8mt/+9ncqBBBMVzf6r5Sagy4PL1XnryLsuADD/vOEkPet8wXgH/Oj7v5tTsQQZ7U1JT51PoDs2BFnXc5v3TkVgZwd32k3ONh+nkDw1Hof+4zwUGOyJE6eMrlYzRlKM4Qxdf9JpavQvqfieAbTRWcyKeclnHeoIfE7cDBQIDAQAB",
   "background": {

package/dist/{engine-DHFa2_hK.js → engine-RA1Orodr.js}

@@ -1,4 +1,4 @@
-import { A as BROWSE_DEFAULT_MODEL, F as REVIEW_DEFAULT_MODEL, I as appendPlanReminder, L as runWorkerAgent, M as EXPLORE_DEFAULT_MODEL, N as IMPLEMENT_DEFAULT_MODEL, P as PLAN_DEFAULT_MODEL, R as withNoOutputRetry, j as DEFAULT_MODEL } from "./peer-mcp-personas-Bfq3FPKc.js";
+import { F as PLAN_DEFAULT_MODEL, I as REVIEW_DEFAULT_MODEL, L as appendPlanReminder, M as DEFAULT_MODEL, N as EXPLORE_DEFAULT_MODEL, P as IMPLEMENT_DEFAULT_MODEL, R as runWorkerAgent, j as BROWSE_DEFAULT_MODEL, z as withNoOutputRetry } from "./peer-mcp-personas-D826LsJJ.js";
 import "./paths-CTlT1nTo.js";
 import "./lifecycle-ChPBRt6K.js";
 import "./lifecycle-BUXxiltc.js";

package/dist/main.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $ as buildOpenAIErrorEvent, $t as resolveModel, At as ArtifactClient, B as buildToolbeltAwareness, Bt as pickClaudeDefault, C as repoFingerprint, Ct as parseJsonOrDiagnose, D as trustRepo, Dt as extractTarGzMember, E as stopReviewStateDir, Et as provisionAndIndexColbert, Ft as DEFAULT_CODEX_MODEL_FALLBACKS, G as assetFor, Gt as setupGitHubToken, H as toolbeltSkipSet, Ht as withInstallLock, It as DEFAULT_PORT, J as ADVISOR_TOOL_INSTRUCTIONS, Jt as cacheModels, K as searchWeb, Kt as tryRefreshAndRetry, Lt as UPSTREAM_FETCH_TIMEOUT_MS, Mt as toolbeltPathOverride, Nt as DEFAULT_CLAUDE_MODEL_FALLBACKS, O as resolveSealedGate, Ot as extractZipMember, Pt as DEFAULT_CODEX_MODEL, Q as buildAnthropicErrorEvent, Qt as resolveCodexModel, Rt as UPSTREAM_INACTIVITY_TIMEOUT_MS, S as isSubagentContext, St as readResponseBodyCapped, T as stopGateEnabledForRepo, Tt as hasSupportedBrowserInstalled, U as vscodeRipgrepPath, Ut as setupCopilotToken, V as toolbeltEnabled, Vt as getPackageVersion, W as TOOLBELT_TOOLS, Wt as setupGitHubAgentToken, X as injectAdvisorTool, Xt as filterBetaHeader, Y as buildAdvisorStream, Yt as cacheVSCodeVersion, Z as isAdvisorRequested, Zt as isNullish, _ as stopReviewEnabled, _t as resolveMcpToolTimeoutMs, a as buildPeerAwarenessSnippet, an as GITHUB_API_BASE_URL, at as handleMcpPost, b as fileLastPromptStore, bt as createChatCompletions, c as buildSessionBindHookCommand, cn as githubHeaders, ct as browserToolsEnabled, d as decideStopHook, dt as standInToolEnabled, en as sleep, et as isControllerClosedError, f as fileBlockBudget, ft as workerToolsEnabled, g as stopGateId, gt as assembleResponsesPayload, h as stopGateDisabled, ht as getTokenCount, i as buildAgentPrompt, in as forwardError, it as handleMcpDelete, jt as collapsePathKeys, k as liveExec, kt as shouldUseInsecureTls, l as buildStopHookCommand, ln as state, lt as fleetToolsEnabled, m as launchBaselineKey, mt as createMessages, n as MCP_GROUPS, nn as fetchWithTransientRetry, nt as readIteratorWithTimeout, o as personasFor, on as copilotBaseUrl, ot as agentToolsEnabled, p as injectStopHookIntoSettingsFile, pt as countTokens, q as ADVISOR_INTERNAL_TOOL_NAME, qt as cacheCopilotVersion, r as assertMcpToolSurfaceConsistent, rn as HTTPError, rt as relayAnthropicStream, s as buildArtifactOpenHookCommand, sn as copilotHeaders, st as browseAgentEnabled, t as GROUP_META, tn as getModels, tt as logStreamError, u as captureLaunchBaseline, ut as implementerSubagentModel, v as fileBaselineStore, vt as pickEndpoint, w as repoRoot, wt as provisionBrowserAssets, x as fileReviewDebounce, xt as MAX_RESPONSE_BODY_BYTES, y as fileFindingsStore, yt as createResponses, z as availableToolCommands, zt as generateRandomPort } from "./peer-mcp-personas-Bfq3FPKc.js";
+import { $ as buildAnthropicErrorEvent, $t as resolveCodexModel, A as liveExec, At as shouldUseInsecureTls, B as availableToolCommands, Bt as generateRandomPort, C as isSubagentContext, Ct as readResponseBodyCapped, D as stopReviewStateDir, Dt as provisionAndIndexColbert, E as stopGateEnabledForRepo, Et as hasSupportedBrowserInstalled, Ft as DEFAULT_CODEX_MODEL, G as TOOLBELT_TOOLS, Gt as setupGitHubAgentToken, H as toolbeltEnabled, Ht as getPackageVersion, It as DEFAULT_CODEX_MODEL_FALLBACKS, J as ADVISOR_INTERNAL_TOOL_NAME, Jt as cacheCopilotVersion, K as assetFor, Kt as setupGitHubToken, Lt as DEFAULT_PORT, Mt as collapsePathKeys, Nt as toolbeltPathOverride, O as trustRepo, Ot as extractTarGzMember, Pt as DEFAULT_CLAUDE_MODEL_FALLBACKS, Q as isAdvisorRequested, Qt as isNullish, Rt as UPSTREAM_FETCH_TIMEOUT_MS, S as fileReviewDebounce, St as MAX_RESPONSE_BODY_BYTES, T as repoRoot, Tt as provisionBrowserAssets, U as toolbeltSkipSet, Ut as withInstallLock, V as buildToolbeltAwareness, Vt as pickClaudeDefault, W as vscodeRipgrepPath, Wt as setupCopilotToken, X as buildAdvisorStream, Xt as cacheVSCodeVersion, Y as ADVISOR_TOOL_INSTRUCTIONS, Yt as cacheModels, Z as injectAdvisorTool, Zt as filterBetaHeader, _ as stopGatePlanMode, _t as assembleResponsesPayload, a as buildPeerAwarenessSnippet, an as forwardError, at as handleMcpDelete, b as fileFindingsStore, bt as createResponses, c as buildSessionBindHookCommand, cn as copilotHeaders, ct as browseAgentEnabled, d as decideStopHook, dt as implementerSubagentModel, en as resolveModel, et as buildOpenAIErrorEvent, f as fileBlockBudget, ft as standInToolEnabled, g as stopGateId, gt as getTokenCount, h as stopGateDisabled, ht as createMessages, i as buildAgentPrompt, in as HTTPError, it as relayAnthropicStream, jt as ArtifactClient, k as resolveSealedGate, kt as extractZipMember, l as buildStopHookCommand, ln as githubHeaders, lt as browserToolsEnabled, m as launchBaselineKey, mt as countTokens, n as MCP_GROUPS, nn as getModels, nt as logStreamError, o as personasFor, on as GITHUB_API_BASE_URL, ot as handleMcpPost, p as injectStopHookIntoSettingsFile, pt as workerToolsEnabled, q as searchWeb, qt as tryRefreshAndRetry, r as assertMcpToolSurfaceConsistent, rn as fetchWithTransientRetry, rt as readIteratorWithTimeout, s as buildArtifactOpenHookCommand, sn as copilotBaseUrl, st as agentToolsEnabled, t as GROUP_META, tn as sleep, tt as isControllerClosedError, u as captureLaunchBaseline, un as state, ut as fleetToolsEnabled, v as stopReviewEnabled, vt as resolveMcpToolTimeoutMs, w as repoFingerprint, wt as parseJsonOrDiagnose, x as fileLastPromptStore, xt as createChatCompletions, y as fileBaselineStore, yt as pickEndpoint, zt as UPSTREAM_INACTIVITY_TIMEOUT_MS } from "./peer-mcp-personas-D826LsJJ.js";
 import { a as removeOwnClaudeConfigMirror, i as isUnderClaudeConfigMirror, l as writeArtifactCredsToMirror, n as ensureClaudeConfigMirror, r as ensurePaths, t as PATHS, u as writeRuntimeFileSecure } from "./paths-CTlT1nTo.js";
 import { c as killManagedTree, d as runCommandCapture, f as runCommandVoid, l as parseBoolEnv, s as killChildProcessTree, u as resolveExecutable } from "./lifecycle-ChPBRt6K.js";
 import { a as sweepRegistry } from "./lifecycle-BUXxiltc.js";
@@ -1204,7 +1204,7 @@ function buildPeerAgentDefinitions(opts) {
 	});
 	if (opts.implementerModel && opts.implementerModel.length > 0) out.implementer = {
 		description: "Bounded implementation subagent running gpt-5.5 (strong non-Claude coder, high reasoning). Use for well-scoped coding tasks — edits, small features, fixes — you want implemented in an integrated subagent. Model is overridable at spawn.",
-		prompt: "You are a bounded implementation subagent for well-scoped coding tasks. Implement the requested change surgically, matching the surrounding code style and minimizing unrelated churn. Verify with the project's build or tests where applicable. Do the work yourself — do not spawn further subagents. Report exactly what changed and any risks.",
+		prompt: "You are a bounded implementation subagent for well-scoped coding tasks. Implement the requested change surgically, matching the surrounding code style and minimizing unrelated churn. Use the dedicated Edit/Write/Read tools for file changes and Grep/Glob for search; reserve Bash for running builds, tests, and git — do not shell out (sed/awk/python/here-docs) to read or edit files. Verify with the project's build or tests where applicable. Do the work yourself — do not spawn further subagents. Report exactly what changed and any risks.",
 		model: opts.implementerModel
 	};
 	if (opts.workerToolsAvailable) {
@@ -2289,7 +2289,7 @@ async function discoverGateCommands(cwd, opts) {
 	if (files.length === 0) return null;
 	let result;
 	try {
-		const { runWorkerAgent } = await import("./engine-DHFa2_hK.js");
+		const { runWorkerAgent } = await import("./engine-RA1Orodr.js");
 		result = await runWorkerAgent({
 			mode: "explore",
 			workspace: root,
@@ -2443,6 +2443,99 @@ function buildPromptSubmitHookCommand(execPath, scriptPath) {
 	return `${q(execPath)} internal-prompt-submit`;
 }
 
+//#endregion
+//#region src/lib/first-mate/operator-shaping.ts
+/** MCP prefixes denied to the main operator; these remain subagent-only. */
+const OPERATOR_DENIED_MCP_PREFIXES = ["mcp__workers__", "mcp__orchestrate__"];
+/**
+* Decide whether a tool call must be blocked for the main operator. Pure — used
+* both by the PreToolUse hook handler and by config-assertion tests. When
+* operator mode is off, nothing is blocked (normal sessions unaffected).
+*/
+function shouldDenyOperatorTool(toolName, operatorMode) {
+	if (!operatorMode) return false;
+	return OPERATOR_DENIED_MCP_PREFIXES.some((prefix) => toolName.startsWith(prefix));
+}
+/**
+* M4 — fail-CLOSED. If operator/`--agents` mode is active but the reduced
+* worker/orchestrate guard could NOT be installed (e.g. settings.json unwritable),
+* the operator session must NOT start with direct main-thread worker/orchestrate
+* MCP calls available. Non-agents sessions are never affected.
+*/
+function assertShapingInstalled(agentsMode, injectionSucceeded) {
+	if (agentsMode && !injectionSucceeded) throw new Error("cloud-agent operator mode requires the worker/orchestrate PreToolUse hook, but it could not be installed — refusing to start an unguarded operator session.");
+}
+/**
+* The PreToolUse hook decision for a given tool name in operator mode.
+*
+* Bash and file-authoring tools are always allowed. Only direct main-operator
+* calls to local worker/orchestrate MCP tools are blocked so those backends stay
+* reachable through the worker-* Agent subagents rather than the lead context.
+*/
+function operatorPreToolUse(toolName, operatorMode, _input) {
+	if (!operatorMode) return { block: false };
+	if (shouldDenyOperatorTool(toolName, operatorMode)) return {
+		block: true,
+		reason: `${toolName} is subagent-only in cloud-agent operator mode — use the worker-* Agent subagents or delegate implementation to a GitHub cloud agent via the first-mate MCP instead of calling local worker/orchestrate MCP tools from the main operator.`
+	};
+	return { block: false };
+}
+
+//#endregion
+//#region src/internal-first-mate-guard.ts
+function readStdinSync() {
+	try {
+		return readFileSync(0, "utf8");
+	} catch {
+		return "";
+	}
+}
+const internalFirstMateGuard = defineCommand({
+	meta: {
+		name: "internal-first-mate-guard",
+		description: "PreToolUse guard enforcing cloud-agent operator capability shaping."
+	},
+	run() {
+		let toolName = "";
+		let toolInput;
+		let parsed = false;
+		try {
+			const payload = JSON.parse(readStdinSync());
+			if (typeof payload.tool_name === "string") toolName = payload.tool_name;
+			if (typeof payload.tool_input === "object" && payload.tool_input !== null) toolInput = payload.tool_input;
+			parsed = true;
+		} catch {
+			parsed = false;
+		}
+		if (toolName.length === 0) {
+			if (!parsed) {
+				process.stderr.write("operator guard: unparseable PreToolUse payload — blocking (fail-closed)");
+				process.exit(2);
+			}
+			process.exit(0);
+		}
+		const decision = operatorPreToolUse(toolName, true, toolInput);
+		if (decision.block) {
+			process.stderr.write(decision.reason ?? `${toolName} is disabled in operator mode`);
+			process.exit(2);
+		}
+		process.exit(0);
+	}
+});
+/** The regex matcher scoping the guard hook to exactly the denied tools. */
+const FIRST_MATE_GUARD_MATCHER = "mcp__workers__.*|mcp__orchestrate__.*";
+/** Build the hook command string that runs this subcommand. */
+function buildFirstMateGuardHookCommand(execPath, entry) {
+	return `${JSON.stringify(execPath)} ${JSON.stringify(entry)} internal-first-mate-guard`;
+}
+
+//#endregion
+//#region src/lib/injected-skills/first-mate-setup-skill.ts
+const FIRST_MATE_SETUP_SKILL = {
+	name: "gh-first-mate-scaffold",
+	md: "---\nname: gh-first-mate-scaffold\ndescription: Seed a world-class repo-geared agentic-dev foundation through first-mate.\nuser-invocable: true\n---\n\n# gh-first-mate-scaffold\n\nInvoke the `scaffold_repo` MCP tool (`mcp__first-mate__scaffold_repo`) before the first build wave on an owned repository. The goal is not generic TODO stubs; it is a repo-geared foundation that GitHub agents, local agents, reviewers, and CI can read.\n\n## What it seeds\n\n- `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` / `.github/copilot-instructions.md` — identical guidance with overview, detected stack, commands, hard DoD gate, primary OS, conventions, structure, decisions/memory, handoff, testing, and gotchas.\n- `.github/agents/{planner,implementer,reviewer,researcher,tester}.md` mirrored into `.claude/agents/` — role agents with frontmatter, cold-start contract, method, quality bar, output contract, and self-reminder.\n- `docs/adrs/0000-template.md` plus `docs/adr/0001-record-architecture-decisions.md` — Nygard-style decision record foundation.\n- `LEARNINGS.md`, `CHANGELOG.md`, `docs/history/0000-template.md`, `docs/plans/README.md`, and `docs/research/README.md` — durable memory, history, plans, and research conventions.\n- `.github/pull_request_template.md` — summary, type, failure-modes-considered-and-tested, and DoD checklist.\n- `.github/instructions/tests.instructions.md` — path-scoped test guidance filled from detected framework/dir/glob where possible.\n- `.github/workflows/copilot-setup-steps.yml` and starter `.github/workflows/ci.yml` — detected toolchain setup with stable quality-gate job names.\n\nIt does not seed factory-protocol or `docs/factory/` files. Orchestration remains outside the product repo in first-mate.\n\n## Usage\n\n```\nmcp__first-mate__scaffold_repo({ repo: \"owner/repo\" })\nmcp__first-mate__scaffold_repo({ repo: \"owner/repo\", mode: \"enhance\" })\nmcp__first-mate__scaffold_repo({\n  repo: \"owner/repo\",\n  mode: \"add-missing-only\",\n  detection_overrides: { primary_os: \"windows-latest\", test_command: \"npm test\" }\n})\n```\n\nModes:\n\n- `add-missing-only` (default): seed absent files and skip present files.\n- `enhance`: for guidance files, ADR index, changelog, and learnings, append only missing `##` sections; never rewrite existing prose. Other present files are skipped.\n- `overwrite-approved`: replace existing files only when explicitly approved.\n\nAlways inspect the returned per-file report and PR. A no-op result means the repo already has the foundation or has no missing enhanceable sections.\n"
+};
+
 //#endregion
 //#region src/lib/injected-skills/first-mate-skill.ts
 const FIRST_MATE_SKILL = {
@@ -2459,6 +2552,18 @@ Use this skill when the user wants first-mate to drive GitHub cloud coding agent
 The first-mate controller is the durable system of record: missions, units, decisions, handles, and controller state live in its registry and ledger.
 Your job is to run the thin protocol, not to hold the mission in context.
 
+## Foundation-first mandate
+
+Before the first build wave on an owned repository, run \`mcp__first-mate__scaffold_repo\` and verify the PR landed or is already present. The scaffold must seed a repo-geared foundation that GitHub agents and CI can read: guidance, role agents, ADRs, changelog, learnings, PR template, test instructions, Copilot setup, and CI. Do not seed factory-protocol files into product repos; first-mate is the external orchestrator.
+
+Use \`mode: "add-missing-only"\` for new repos, \`mode: "enhance"\` when a repo has existing guidance that should keep its prose while appending missing \`##\` sections, and \`mode: "overwrite-approved"\` only with explicit approval.
+
+## Scoped-work discipline
+
+Well-scoped, testable work items succeed; vague meta-work fails. Discovery/decompose must emit concrete units with acceptance criteria, expected evidence, and dependencies. Keep one active build unit per concern. Parallelism is for read-only producers (research, review, planning) and independent units only, not for racing broad implementation waves.
+
+Judgment and merge policy: merge remains human-gated, evidence-gated, and head/base-bound. Use the best available model tier for plan review, judgment, and merge decisions; never cheap out on plan/judge/merge calls.
+
 ## Start a mission
 
 For a new goal, call mcp__first-mate__start_mission with:
@@ -2469,7 +2574,7 @@ For a new goal, call mcp__first-mate__start_mission with:
 - priority and house_rules only when the user supplied them or they are necessary constraints.
 
 If acceptance criteria are missing or ambiguous, ask the user before starting.
-Do not decompose the mission yourself at start time; v1 mission registration is intentionally simple and later controller wakes/model requests drive decomposition and steering.
+Do not decompose the mission yourself at start time; mission registration is intentionally simple and later controller wakes/model requests drive decomposition and steering. If the user explicitly asks to append scoped work to an existing active mission, use mcp__first-mate__add_units with concrete unit titles.
 
 Invariant (closes the stranding hole): work only ever becomes active inside a turn — start_mission is a tool call, nothing activates a mission server-side. So immediately after start_mission, run one loop turn (advance, then arm the heartbeat) in the SAME turn, before you yield. Never register a mission and stop without arming; otherwise nothing will wake to drive it.
 
@@ -2496,6 +2601,7 @@ Keep verdicts small and typed to the request kind.
 
 Use the request's kind and payload as the contract:
 
+- decompose: split a unit-less active mission into dispatchable units. Return { units: [{ title, repo?, agent?, dependsOn?, model? }] }. \`dependsOn\` entries are 0-based indices into the same units list. Emit once per unit-less active mission; the controller creates durable unit ids and will not ask again after units exist.
 - review_plan: review the plan against the mission goal, acceptance criteria, and house rules. Return { decision: "approve" } when the plan is good enough to implement, or { decision: "refine", instruction: "..." } with a short actionable refinement.
 - answer_agent_question: answer only from the acceptance criteria and supplied context. Return { answer: "..." }. If the answer is not derivable, do not invent policy; escalate by leaving a short answer that says what the human must decide.
 - author_fix: author a concise fix instruction for the cloud agent. Return { instruction: "..." } with the failure, expected behavior, and any bounded check to run.
@@ -2507,6 +2613,8 @@ Delegate heavy reading to workers:
 - Use the worker-review subagent (Agent tool) for compact review of a specific plan, PR summary, or suspicious change.
 - Use the worker-test subagent (Agent tool) when a missing executable check is the blocker.
 
+Operator / --agents mode constraint: delegate product implementation to GitHub cloud agents. Direct \`mcp__workers__*\` / \`mcp__orchestrate__*\` calls are subagent-only for the main operator; use the worker-* Agent subagents when local worker help is genuinely needed. Local tools (Edit/Write/Bash, \`gh\`, \`git\`) remain available, but prefer authoring fix instructions for the cloud agent rather than pulling large diffs or CI logs into the lead context.
+
 Do not read a full diff, full CI log, or full transcript in the lead context. Ask workers for narrow facts and compact excerpts. The ledger is durable memory; context is not.
 
 ## Human requests
@@ -2540,6 +2648,8 @@ Responsiveness (optional): the buckets above already tighten cadence to ~2 min f
 
 Guardrails: never leave more than one [fm-heartbeat] job; never busy-loop advance; if no scheduler tool is available, tell the user the next wake is in nextWakeSeconds seconds and stop.
 
+MCP unavailable: if the first-mate MCP server is not present (this is not a \`--agents\` session and \`mcp__first-mate__advance\` would return a tool-not-found error), do NOT attempt to advance. CronList then CronDelete every [fm-heartbeat] job (same as Disarm above), and report "first-mate paused — re-run under \`github-router claude --agents\` to resume." Stop without further action.
+
 ## Board reports
 
 Use mcp__first-mate__board or mcp__first-mate__mission_status for read-only status checks.
@@ -2549,6 +2659,9 @@ Report compactly:
 - repositories
 - phase counts
 - blocked count and why, when available
+- per-unit handles for non-terminal units: unitId, issue/PR, phase, provider, validation, model, and blockedReason when present
+- resolved cloud-agent model per unit (surfaced on the board — verify model choice before approving plans)
+- terminal work only as summary counts; use include_all only when the user asks for completed/abandoned history
 - next wake time or the next requested action
 
 Never reconstruct status by rereading raw logs when the controller board already has the handles.
@@ -3613,7 +3726,8 @@ const INJECTED_SKILLS = [
 	ORCHESTRATE_SKILL,
 	FLOOR_KEEPER_SKILL,
 	WORKER_SKILL,
-	FIRST_MATE_SKILL
+	FIRST_MATE_SKILL,
+	FIRST_MATE_SETUP_SKILL
 ];
 
 //#endregion
@@ -4046,6 +4160,141 @@ async function stopKeepAwake() {
 	releaseSync();
 }
 
+//#endregion
+//#region src/lib/first-mate/scheduler/autospawn.ts
+/**
+* Opt-in auto-spawn of the first-mate scheduler daemon as a SEPARATE process
+* (a hung tick must not starve the proxy event loop).
+*
+* DEFAULT OFF — gated by GH_ROUTER_FM_DAEMON === "1" (explicit opt-in). The
+* durable [fm-heartbeat] cron is the DEFAULT driver and the proven path; the
+* daemon is experimental and NOT yet safe as the default because two hardening
+* items remain (a verifier-stall wall-clock escalation, and an atomic-claim
+* lock in durable-store) — flip the default only once those land.
+*
+* Requirements + honest boundaries:
+*  - The daemon entry is `scripts/first-mate-daemon.ts` (a TS source file run via
+*    `bun`); it is NOT in the published dist tarball, so auto-spawn only fires
+*    from a source checkout with `bun` available. If the script is absent we
+*    no-op (never a false "spawned" log).
+*  - Spawn failures NEVER crash the proxy: an async ENOENT (`bun` not on PATH)
+*    arrives as an `'error'` EVENT, not a sync throw, so we attach an `'error'`
+*    listener (without it the emitter re-throws → uncaughtException → exit(1)).
+*  - The returned handle MUST be killed by the caller on shutdown (no `detached`);
+*    an orphaned drive-primary daemon would keep merging PRs after the proxy is
+*    gone. The parent ALSO holds the child's stdin write end (`stdio[0]==="pipe"`)
+*    so it can EOF the child for a GRACEFUL stop (lease + pidfile released
+*    immediately, not by expiry) — the cross-platform teardown trigger, since an
+*    external SIGTERM on Windows is a hard kill the child can't observe. `kill()`
+*    stays the hard backstop so a wedged child is never orphaned (see
+*    `wireDaemonTeardown`).
+*  - It owns the deterministic drive loop only; live judgments still wake the
+*    lead via the heartbeat (no server->lead push).
+*/
+function shouldAutoSpawnDaemon(env, agentsEnabled) {
+	if (!agentsEnabled) return false;
+	return env.GH_ROUTER_FM_DAEMON === "1";
+}
+/**
+* The real (non-injected) spawner: node:child_process (not the Bun runtime's spawn) so the
+* bundled dist/main.js stays node-loadable. No `detached` — the caller kills
+* this on shutdown. stdin is "pipe" (parent holds the write end for a graceful
+* EOF stop); stdout/stderr stay "ignore".
+*/
+function nodeDaemonSpawn(cmd, spawnOpts, spawnImpl = spawn) {
+	const proc = spawnImpl(cmd[0], cmd.slice(1), {
+		env: spawnOpts.env,
+		stdio: spawnOpts.stdio
+	});
+	proc.on("error", (err) => consola.debug("first-mate daemon spawn error (ignored):", err));
+	return {
+		pid: proc.pid,
+		kill: () => void proc.kill("SIGKILL"),
+		endStdin: () => {
+			try {
+				proc.stdin?.end();
+			} catch {}
+		}
+	};
+}
+/**
+* Spawn the daemon child if the opt-in gate passes AND the daemon script is
+* present; else return undefined. Never throws, and never lets an async spawn
+* error crash bootstrap.
+*/
+function maybeSpawnDaemon(opts) {
+	const env = opts.env ?? process.env;
+	if (!shouldAutoSpawnDaemon(env, opts.agentsEnabled)) return void 0;
+	const script = nodePath.join(opts.repoRoot ?? process.cwd(), "scripts/first-mate-daemon.ts");
+	if (opts.spawn === void 0 && !existsSync(script)) {
+		consola.debug(`first-mate daemon entry not found (${script}); auto-spawn skipped.`);
+		return;
+	}
+	try {
+		const child = (opts.spawn ?? ((cmd, spawnOpts) => nodeDaemonSpawn(cmd, spawnOpts)))(["bun", script], {
+			env,
+			stdio: [
+				"pipe",
+				"ignore",
+				"ignore"
+			]
+		});
+		return {
+			pid: child.pid,
+			kill: child.kill,
+			endStdin: child.endStdin ?? (() => {})
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* Wire the proxy's teardown to shut the daemon child down GRACEFULLY, then hard
+* kill as a backstop. Ordering (per teardown path):
+*  1. `endStdin()` — EOF the child so it releases its lease/pidfile cleanly (the
+*     cross-platform trigger; on Windows an external SIGTERM would never run the
+*     child's handler, so this EOF is the ONLY graceful path there).
+*  2. `kill()` — hard backstop so a wedged child is never orphaned (a prior
+*     review blocker: an orphaned drive-primary daemon keeps merging PRs).
+*
+* On SIGINT/SIGTERM the kill is deferred by a short, NON-BLOCKING, unref'd grace
+* window (proxy exit is never delayed for it). On `'exit'` — where timers cannot
+* run — we EOF then kill synchronously as a last resort. All steps are
+* once-guarded and non-throwing.
+*/
+function wireDaemonTeardown(handle, opts = {}) {
+	const proc = opts.proc ?? process;
+	const graceMs = opts.graceMs ?? 300;
+	const setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+	let killed = false;
+	const kill = () => {
+		if (killed) return;
+		killed = true;
+		try {
+			handle.kill();
+		} catch {}
+	};
+	let ended = false;
+	const endStdin = () => {
+		if (ended) return;
+		ended = true;
+		try {
+			handle.endStdin();
+		} catch {}
+	};
+	const onSignal = () => {
+		endStdin();
+		const t = setTimer(kill, graceMs);
+		if (t && typeof t.unref === "function") t.unref();
+	};
+	proc.once("SIGINT", onSignal);
+	proc.once("SIGTERM", onSignal);
+	proc.once("exit", () => {
+		endStdin();
+		kill();
+	});
+}
+
 //#endregion
 //#region src/lib/proxy.ts
 function initProxyFromEnv() {
@@ -4095,7 +4344,7 @@ function initProxyFromEnv() {
 //#endregion
 //#region package.json
 var name = "github-router";
-var version$1 = "0.3.162";
+var version$1 = "0.3.168";
 
 //#endregion
 //#region src/lib/approval.ts
@@ -4918,6 +5167,34 @@ function clampEffort(bucketed, supported) {
 
 //#endregion
 //#region src/lib/anthropic-translate/anthropic-request.ts
+/**
+* Steering appended to `instructions` for shim-routed (non-Claude) models when
+* the request carries Claude Code's native file tools. gpt-5.5 and other
+* OpenAI/Gemini-lineage models receive the Edit/Write tool definitions verbatim
+* (the shim never mangles them), but their base prior is to script file ops in
+* Python/Bash rather than call the dedicated tools. Claude models never reach
+* this code path (they fall through to the /v1/messages passthrough), so this is
+* automatically scoped to the models that need the nudge. Strong PREFERENCE, not
+* a Bash ban — running builds/tests/git still belongs in Bash.
+*/
+const FILE_TOOL_GUIDANCE = `<file_tools>
+You have dedicated tools for files: use Read to read a file, Edit to modify an existing file, and Write to create one. Prefer them over shell for reading or editing. Do NOT shell out (cat, sed, awk, echo >, here-docs, or python/one-off scripts) to read, search, or rewrite file contents when a dedicated tool exists — the dedicated tools are safer and produce reviewable diffs. Use Grep/Glob to search rather than shell grep/find. Reserve Bash for commands that have no dedicated tool: builds, tests, git, package managers, and running programs.
+</file_tools>`;
+/**
+* Append `FILE_TOOL_GUIDANCE` to the flattened system `instructions` iff the
+* request carries Claude Code's canonical `Edit` or `Write` tool. The exact
+* capitalized-name match is deliberately precise: it fires for a Claude Code
+* editing session but not for arbitrary MCP tools like `write_file`, and not for
+* non-editing chats (so a plain gpt-5.5 conversation is not polluted). The block
+* is appended AFTER the existing instructions (end-of-prompt recency) and the
+* original system text is preserved, never replaced. Opt out with
+* `GH_ROUTER_DISABLE_SHIM_TOOL_STEERING=1`.
+*/
+function appendFileToolGuidance(instructions, tools) {
+	if (parseBoolEnv(process.env.GH_ROUTER_DISABLE_SHIM_TOOL_STEERING) === true) return instructions;
+	if (!tools?.some((t) => t.name === "Edit" || t.name === "Write")) return instructions;
+	return instructions && instructions.length > 0 ? `${instructions}\n\n${FILE_TOOL_GUIDANCE}` : FILE_TOOL_GUIDANCE;
+}
 /** Flatten Anthropic `system` (string | array of text blocks) into a string. */
 function flattenSystem(system) {
 	if (typeof system === "string") return system.length > 0 ? system : void 0;
@@ -5183,11 +5460,12 @@ function parseAnthropicRequest(body, resolvedModel, model) {
 	}
 	const maxTokens = typeof body.max_tokens === "number" && body.max_tokens > 0 ? body.max_tokens : void 0;
 	const stopSequences = Array.isArray(body.stop_sequences) ? body.stop_sequences.filter((s) => typeof s === "string") : void 0;
+	const tools = parseTools(body.tools);
 	return {
 		model: resolvedModel,
-		instructions: flattenSystem(body.system),
+		instructions: appendFileToolGuidance(flattenSystem(body.system), tools),
 		messages,
-		tools: parseTools(body.tools),
+		tools,
 		toolChoice: parseToolChoice(body.tool_choice),
 		parallelToolCalls: parseDisableParallelToolUse(body.tool_choice),
 		reasoningEffort: body.thinking === void 0 ? defaultReasoningEffort(model) : parseReasoningEffort(body.thinking, model),
@@ -7254,6 +7532,15 @@ async function setupAndServe(options) {
 	const url = srvxServer.url;
 	if (!url) throw new Error("Server started but URL is not available");
 	const serverUrl = url.replace(/\/$/, "");
+	try {
+		const handle = maybeSpawnDaemon({ agentsEnabled: agentToolsEnabled() });
+		if (handle) {
+			wireDaemonTeardown(handle);
+			consola.debug(`first-mate daemon spawn attempted (pid ${handle.pid ?? "?"}).`);
+		}
+	} catch (err) {
+		consola.debug("first-mate daemon auto-spawn skipped:", err);
+	}
 	return {
 		server: srvxServer,
 		serverUrl
@@ -7610,6 +7897,9 @@ function getCodexEnvVars(serverUrl) {
 
 //#endregion
 //#region src/claude.ts
+function isFirstMateSkillName(name$1) {
+	return name$1 === "gh-first-mate" || name$1 === "gh-first-mate-scaffold";
+}
 const claudeArgs = {
 	...sharedServerArgs,
 	model: {
@@ -7857,7 +8147,7 @@ const claude = defineCommand({
 			process$1.stderr.write(`Peer MCP wired (backend=${backend}, personas=[${personaNames}], subagent .md files=${runtime.agentMdPaths.length}, ${subagentVisibility}).${skippedNote}\n`);
 			const sessionCwd = process$1.cwd();
 			if (workerToolsEnabled()) {
-				const skillsToWrite = INJECTED_SKILLS.filter((s) => s.name !== "gh-first-mate" || agentToolsEnabled());
+				const skillsToWrite = INJECTED_SKILLS.filter((s) => !isFirstMateSkillName(s.name) || agentToolsEnabled());
 				let skillsWritten = 0;
 				for (const s of skillsToWrite) if ((await writeInjectedSkill(s.name, s.md).catch(() => ({ written: false }))).written) skillsWritten++;
 				try {
@@ -7880,6 +8170,16 @@ const claude = defineCommand({
 					process$1.stderr.write(`Injected skills (${skillsWritten}/${skillsToWrite.length}): ${skillNames}.\n`);
 				}
 			}
+			if (agentToolsEnabled()) {
+				let shapingInstalled = false;
+				try {
+					await injectStopHookIntoSettingsFile(nodePath.join(PATHS.CLAUDE_CONFIG_DIR, "settings.json"), buildFirstMateGuardHookCommand(process$1.execPath, process$1.argv[1]), "PreToolUse", void 0, FIRST_MATE_GUARD_MATCHER);
+					shapingInstalled = true;
+				} catch (err) {
+					consola.error(`Could not register the operator worker/orchestrate guard hook: ${String(err)}`);
+				}
+				assertShapingInstalled(true, shapingInstalled);
+			}
 			const aiordieSidecar = (process$1.env.AIORDIE_CLAUDE_BIND ?? "").trim();
 			if (aiordieSidecar.length > 0 && !aiordieSidecar.includes("\"")) try {
 				const settingsPath = nodePath.join(PATHS.CLAUDE_CONFIG_DIR, "settings.json");
@@ -8936,6 +9236,7 @@ const internalStopHook = defineCommand({
 				isEnabledForRepo: (cwd) => stopGateEnabledForRepo(cwd),
 				resolveChecks: mode ? buildResolveChecks(mode) : void 0,
 				timeoutMs: Number.isFinite(timeoutEnv) && timeoutEnv > 0 ? timeoutEnv : void 0,
+				planMode: stopGatePlanMode(),
 				reviewDebounce: reviewEnabled ? fileReviewDebounce(stopReviewStateDir()) : void 0,
 				spawnReview: reviewEnabled ? (ctx) => spawnStopReview(ctx, {
 					prompt: userPrompt,
@@ -9381,7 +9682,7 @@ process.on("uncaughtException", (error) => {
 const version = getPackageVersion();
 const argv = process.argv.slice(2);
 const isVersionFlag = argv.includes("--version");
-const isInternalHook = argv[0] === "internal-stop-hook" || argv[0] === "internal-prompt-submit" || argv[0] === "internal-stop-review" || argv[0] === "internal-session-bind" || argv[0] === "internal-artifact-open" || argv[0] === "internal-worker-guard";
+const isInternalHook = argv[0] === "internal-stop-hook" || argv[0] === "internal-prompt-submit" || argv[0] === "internal-stop-review" || argv[0] === "internal-session-bind" || argv[0] === "internal-artifact-open" || argv[0] === "internal-first-mate-guard" || argv[0] === "internal-worker-guard";
 if (!isVersionFlag && !isInternalHook) consola.info(`github-router v${version}`);
 await runMain(defineCommand({
 	meta: {
@@ -9402,6 +9703,7 @@ await runMain(defineCommand({
 		"internal-stop-review": internalStopReview,
 		"internal-session-bind": internalSessionBind,
 		"internal-artifact-open": internalArtifactOpen,
+		"internal-first-mate-guard": internalFirstMateGuard,
 		"internal-worker-guard": internalWorkerGuard
 	}
 }));