@yagni-app/code-staging 1.1.6-staging.1445.1 → 1.1.6-staging.1449.1

package/dist/extension/index.js

@@ -773,31 +773,70 @@ export async function registerYagni(pi, deps = {}) {
     // the command — its later escape attempts go to the consent dialog (the
     // sandbox genuinely cannot run it). Content stays local: only the trimmed
     // command string is held in memory, never logged.
-    const sandboxedFailures = new Map();
     const SANDBOXED_FAILURES_MAX = 50;
+    /** Bounded LRU map keyed by the CANONICAL command (sandboxFailureKey): a
+     * retry differing by quote rendering or safe decoration must hit the same
+     * entry — raw-string keys would miss exactly the variable shapes the
+     * grants layer canonicalizes for. Shared by both brake maps (the boolean
+     * seed set and the escalation counter) so the refresh + eviction policy
+     * lives in ONE place — the two copies drifted once already (the counter
+     * missed the delete-then-set refresh and evicted a hot key at the cap).
+     * upsert performs the delete-then-set refresh (a re-touched key moves to
+     * the END of insertion order, so the evicted key is always the
+     * least-recently-touched one) and evicts at the cap. A null key (an
+     * uncanonicalizable command) is a no-op returning undefined. */
+    const makeSandboxFailureMap = (nextValue) => {
+        const map = new Map();
+        return {
+            has: (key) => map.has(key),
+            get: (key) => map.get(key),
+            /** Canonical-keyed upsert: refresh LRU order, compute the value from
+             * the existing one, evict at the cap. */
+            upsert: (command) => {
+                const key = sandboxFailureKey(command);
+                if (!key)
+                    return undefined;
+                const value = nextValue(map.get(key), key);
+                map.delete(key);
+                map.set(key, value);
+                if (map.size > SANDBOXED_FAILURES_MAX) {
+                    const oldest = map.keys().next().value;
+                    if (oldest !== undefined)
+                        map.delete(oldest);
+                }
+                return { key, value };
+            },
+            clear: () => { map.clear(); },
+        };
+    };
+    const sandboxedFailures = makeSandboxFailureMap(() => true);
     const recordSandboxedFailure = (command) => {
-        // The CANONICAL key (sandboxFailureKey): a retry differing by quote
-        // rendering or safe decoration must hit the same entry — raw-string
-        // keys would miss exactly the variable shapes the grants layer
-        // canonicalizes for.
-        const key = sandboxFailureKey(command);
-        if (!key)
-            return;
-        sandboxedFailures.delete(key);
-        sandboxedFailures.set(key, true);
-        if (sandboxedFailures.size > SANDBOXED_FAILURES_MAX) {
-            const oldest = sandboxedFailures.keys().next().value;
-            if (oldest !== undefined)
-                sandboxedFailures.delete(oldest);
-        }
+        sandboxedFailures.upsert(command);
     };
     const hasSandboxedFailure = (command) => sandboxedFailures.has(sandboxFailureKey(command));
+    // Unrecognized-failure escalation (the generic backstop behind the
+    // signature vocabulary): a sandboxed failure whose output matches NO
+    // known signature counts per canonical key; the SECOND occurrence seeds
+    // the brake. Arithmetic lands on the rung's documented contract — first
+    // failure (count 1, no seed), the escape's one silent sandboxed retry
+    // fails (count 2, seed), every further escape dialogs — for every
+    // failure shape, not just the enumerated ones. Worst case is a command
+    // failing twice for non-sandbox reasons: one dialog the user declines
+    // (the code's documented fail-safe direction). Recognized signatures
+    // still seed at 1 — the escalation never weakens the existing valve.
+    const unrecognizedSandboxFailures = makeSandboxFailureMap((existing) => (existing ?? 0) + 1);
+    const countSandboxedFailure = (command) => {
+        // The shared map's upsert refreshes LRU order, increments the count,
+        // and evicts at the cap — the same policy the seed set uses.
+        return unrecognizedSandboxFailures.upsert(command)?.value ?? 0;
+    };
     // A mode transition is a trust-posture change — the auto-sandbox rung's
     // prior-failure evidence clears with the gate's other session caches
     // (the gate's own fallback map clears via modeHolder.onSet; this map is
     // the production one, so it must clear here too).
     modeHolder.onSet(() => {
         sandboxedFailures.clear();
+        unrecognizedSandboxFailures.clear();
     });
     // settings-based permission rules, loaded once at startup (same
     // trust-boundary posture as grants: no mid-session reload). User config
@@ -957,7 +996,29 @@ export async function registerYagni(pi, deps = {}) {
             }),
         prefixConsultTransportAttribution: () => attributionHeaders(env),
         onPrefixConsult: makePrefixErrorSink(),
-        guardianReview: (command, deps) => reviewCommand(command, { ...deps, modelTier: guardianTier }),
+        // The Guardian consult rides the same in-process direct transport as
+        // the prefix consult: one /v1/chat/completions POST per review,
+        // no child spawn, no grounded context. Kill switches compose: the
+        // workspace/env kill switch still disables the consult entirely (checked
+        // in the gate), and YAGNI_GUARDIAN_LEGACY_TRANSPORT forces the proven
+        // child-spawn path as a targeted transport rollback (reviewCommand
+        // itself reads the knob — the wiring here never needs to know). Transport
+        // absence otherwise falls back to the legacy child path, which never
+        // happens in production (baseUrl/getTokenFn are session-lifetime
+        // values) — the fallback is the injectable test seam.
+        guardianReview: (command, deps) => reviewCommand(command, {
+            ...deps,
+            modelTier: guardianTier,
+            ...(guardianDisabled
+                ? {}
+                : {
+                    transport: {
+                        baseUrl,
+                        getToken: getTokenFn,
+                        attribution: () => attributionHeaders(env),
+                    },
+                }),
+        }),
         onGuardianReview: (ev) => {
             guardianLogSink(ev);
             // A malformed verdict (repair FAILED — still really failing) is a real
@@ -1887,18 +1948,41 @@ export async function registerYagni(pi, deps = {}) {
                 .join("\n");
             if (isSandboxDenialOutput(text)) {
                 recordSandboxedFailure(command);
-                // The seed must be observable (debug tier only — no command content,
-                // the closed signature class rides the field): a false-positive seed
-                // session-long disables auto-sandbox for a command, and without this
-                // line the only symptom would be unexplained dialogs.
+                // The seed must be observable (info tier — readSessionTrail filters
+                // debug, and an invisible seed made the incident session
+                // undebuggable; no command content, the closed signature class
+                // rides the field): a false-positive seed session-long disables
+                // auto-sandbox for a command, and without this line the only
+                // symptom would be unexplained dialogs.
                 const signature = sandboxDenialSignature(text);
                 logEvent({
                     source: "sandbox",
-                    level: "debug",
+                    level: "info",
                     event: "sandbox_failure_seeded",
                     fields: { signature },
                 });
             }
+            else {
+                // Unrecognized-failure escalation: no known signature — count it;
+                // the second unrecognized failure of the same canonical command
+                // seeds the brake (the rung then dialogs instead of auto-sandboxing
+                // into the same failure forever). Seed fires only on the 1→2
+                // transition — a later third failure never re-seeds.
+                const count = countSandboxedFailure(command);
+                if (count === 2) {
+                    recordSandboxedFailure(command);
+                    logEvent({
+                        source: "sandbox",
+                        level: "info",
+                        event: "sandbox_failure_seeded",
+                        // count rides the field so the trail distinguishes the
+                        // escalation's seed (always 2) from a recognized seed (1) —
+                        // closed vocabulary only; no failure text (content stays out of
+                        // the always-on trail, the recognized branch's contract).
+                        fields: { signature: "unrecognized", count },
+                    });
+                }
+            }
         }
     });
     // Seed the unified error trail from tool-exec failures. A tool's SUCCESS

package/dist/extension/mcp/auth.d.ts

@@ -26,6 +26,12 @@ import { type StoredOAuthEntry } from "./authStore.js";
 export interface AuthDeps {
     /** Open a URL in the browser; injected for tests, default is a best-effort opener. */
     openUrl?: (url: string) => Promise<void>;
+    /**
+     * Called with the authorization URL just before the browser is opened, so
+     * the caller can show it: the manual fallback when the opener fails or
+     * mangles the link.
+     */
+    onAuthorizationUrl?: (url: string) => void;
     /** Traditional fetch for revocation (SDK auth uses its own fetch). */
     fetch?: typeof fetch;
 }

package/dist/extension/mcp/auth.js

@@ -22,10 +22,10 @@ import { createServer, get as httpGet } from "node:http";
 import { randomBytes } from "node:crypto";
 import { auth as sdkAuth, discoverOAuthServerInfo } from "@modelcontextprotocol/sdk/client/auth.js";
 import { expandServerEnv } from "./config.js";
-import { runningUnderTest } from "../crashReport.js";
 import { getStoredOAuthEntry, updateStoredOAuthEntry } from "./authStore.js";
 import { deleteStoredOAuthEntry as clearStoredOAuthEntry } from "./authStore.js";
 import { logMcpEvent, redactSensitiveUrlParams } from "./log.js";
+import { defaultOpenUrl } from "./openUrl.js";
 import { renderAuthErrorPage, renderAuthStateMismatchPage, renderAuthSuccessPage, } from "./callbackPage.js";
 /** Cancellation via an AbortSignal (Ctrl-C / Esc in the /mcp panel). */
 export class AuthenticationCancelledError extends Error {
@@ -207,8 +207,15 @@ export class YagniAuthProvider {
     async saveClientInformation(info) {
         updateStoredOAuthEntry(this.serverName, this.config, (entry) => {
             entry.clientId = info.client_id;
-            if (info.client_secret != null)
+            if (info.client_secret != null) {
                 entry.clientSecret = info.client_secret;
+                entry.clientSecretSource = "dcr";
+            }
+            else if (entry.clientSecretSource === "dcr") {
+                // A previous registration's secret must not outlive its client.
+                delete entry.clientSecret;
+                delete entry.clientSecretSource;
+            }
             // The SDK only calls this from dynamic client registration, so the
             // redirect this provider advertised is exactly what the server pinned.
             entry.redirectUri = this.redirectUri;
@@ -325,7 +332,15 @@ export async function authenticate(serverName, config, deps = {}, opts = {}) {
         //    that errors before redirecting cannot wedge the command loop.
         const state = await provider.state();
         const codePromise = waitForCode(listener, state, { ...bounds, onEvent: (evt, fields) => logMcpEvent(serverName, evt, { ...fields, redirectUri }) });
-        await openUrl(authorizationUrl);
+        deps.onAuthorizationUrl?.(authorizationUrl);
+        try {
+            await openUrl(authorizationUrl);
+        }
+        catch (err) {
+            // Any opener, injected or default: the flow keeps waiting, because the
+            // user has the printed URL. The log records why the window is missing.
+            logMcpEvent(serverName, "oauth_browser_open_failed", { detail: errorText(err) });
+        }
         const code = await loggedPhase(serverName, "callback", { redirectUri }, () => codePromise);
         if (!code) {
             logMcpEvent(serverName, "oauth_result", { phase: "callback", outcome: "provider_denied", errorDescription: "no authorization code received", redirectUri });
@@ -397,26 +412,39 @@ async function trySilentRefresh(serverName, config, stored, serverUrl, bounds) {
  * when the listener we hold is on a different port (the pinned one was
  * unavailable, or `oauth.callbackPort` changed) the client is dropped so the
  * SDK re-registers for the port we will actually answer on. Ports, not
- * strings, are what the registration pins. A pre-registered `oauth.clientId`
- * never carries `redirectUri` and is never touched. A drop that cannot be
- * persisted fails the flow: the alternative is sending a redirect the stored
- * client is not registered for, which strict servers refuse.
+ * strings, are what the registration pins. A stored client with NO redirect
+ * on record was issued by a CLI from before pinning: it is bound to a port we
+ * cannot know, so it is dropped too (`legacy_unpinned`). The auth store only
+ * ever holds DCR-issued ids; a pre-registered `oauth.clientId` lives in the
+ * config and is never touched. A drop that cannot be persisted fails the
+ * flow: the alternative is sending a redirect the stored client is not
+ * registered for, which strict servers refuse.
  */
 function dropPinnedClientIfPortChanged(serverName, config, stored, listener, redirectUri) {
-    if (!stored?.clientId || !stored.redirectUri)
+    if (!stored?.clientId)
         return;
-    if (portOfRedirectUri(stored.redirectUri) === listener.port)
+    const legacy = !stored.redirectUri;
+    if (!legacy && portOfRedirectUri(stored.redirectUri) === listener.port)
         return;
-    const reason = config.oauth?.callbackPort !== undefined ? "callback_port_changed" : "pinned_port_unavailable";
+    const reason = legacy ? "legacy_unpinned" : config.oauth?.callbackPort !== undefined ? "callback_port_changed" : "pinned_port_unavailable";
     const { errors } = updateStoredOAuthEntry(serverName, config, (entry) => {
         delete entry.clientId;
-        delete entry.clientSecret;
         delete entry.redirectUri;
+        // The secret goes with the DCR client unless it is the operator's
+        // (`--client-secret`), which belongs to the config's pre-registered
+        // client and lives nowhere else. Entries from before provenance was
+        // recorded are read the way the old CLI wrote them: an operator's secret
+        // only ever appeared next to a config `oauth.clientId`.
+        const operators = entry.clientSecretSource === "operator" || (entry.clientSecretSource === undefined && Boolean(config.oauth?.clientId));
+        if (!operators) {
+            delete entry.clientSecret;
+            delete entry.clientSecretSource;
+        }
     });
     if (errors.length > 0) {
         closeQuietly(listener.server);
         logMcpEvent(serverName, "oauth_client_reregister_failed", { reason, previousRedirectUri: stored.redirectUri, redirectUri, error: errors[0] });
-        throw new Error(`could not reset the OAuth client registration for ${serverName} (${errors[0]}); its client is pinned to ${stored.redirectUri}`);
+        throw new Error(`could not reset the OAuth client registration for ${serverName} (${errors[0]}); its client is pinned to ${stored.redirectUri ?? "a redirect this CLI has no record of"}`);
     }
     logMcpEvent(serverName, "oauth_client_reregister", {
         reason,
@@ -684,27 +712,6 @@ export async function revokeServerTokens(serverName, config, metadata, clientInf
     await revokeOne(entry.refreshToken, "refresh_token");
     await revokeOne(entry.accessToken, "access_token");
 }
-/** Best-effort browser open without a shell (injected in tests).
- *
- * A no-op under the test runner (crashReport.ts's runningUnderTest): a test
- * that forgets to inject `openUrl` must not pop a real browser window on the
- * developer's machine. Same philosophy as crash-report suppression — make the
- * whole class of leak impossible rather than fixing one call site at a time.
- */
-async function defaultOpenUrl(url) {
-    if (runningUnderTest())
-        return;
-    const { spawn } = await import("node:child_process");
-    const platform = process.platform;
-    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
-    const args = platform === "win32" ? ["/c", "start", "", url] : [url];
-    try {
-        spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
-    }
-    catch {
-        // best-effort — the URL is surfaced to the user by the panel caller
-    }
-}
 /**
  * Revoke tokens + clear stored credentials for a server being removed. Runs
  * RFC 9728/8414 discovery to find the revocation endpoint, revokes (refresh →

package/dist/extension/mcp/authStore.d.ts

@@ -15,10 +15,26 @@ import type { McpHttpServerConfig } from "./config.js";
 export interface StoredOAuthEntry {
     serverName: string;
     serverUrl: string;
-    /** Client id from DCR, or a pre-registered `oauth.clientId`. */
+    /**
+     * Client id issued by dynamic client registration. A pre-registered id
+     * lives in the config (`oauth.clientId`) and is never written here, which
+     * is what lets the interactive flow drop a stored id whose redirect is
+     * unknown (auth.ts `legacy_unpinned`) without discarding an operator's.
+     */
     clientId?: string;
-    /** Pre-registered client secret (`yagni mcp add --client-secret`), NOT a DCR secret. */
+    /**
+     * Client secret: the one DCR issued alongside `clientId` when the server
+     * returns one (Atlassian's current authorization server does), or a
+     * pre-registered one from `yagni mcp add --client-secret`.
+     */
     clientSecret?: string;
+    /**
+     * Who issued `clientSecret`: `dcr` (it belongs to `clientId` and is
+     * dropped with it) or `operator` (`--client-secret`; it belongs to the
+     * config's `oauth.clientId` and survives a DCR client drop). Absent on
+     * entries written before this field existed.
+     */
+    clientSecretSource?: "dcr" | "operator";
     /**
      * The redirect_uri registered with the authorization server when `clientId`
      * came from dynamic client registration. Strict servers (Atlassian, most

package/dist/extension/mcp/openUrl.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Open a URL in the user's default browser without going through a shell.
+ *
+ * The OAuth authorize URL is long and full of `&`. `cmd /c start <url>` on
+ * Windows re-parses its arguments as a shell line, so cmd.exe split the URL
+ * at the first `&` and the browser opened `…/authorize?response_type=code`;
+ * Atlassian ID then showed "The authorize request was incomplete or invalid"
+ * (2026-09-21 customer report). The same re-parse would let a hostile
+ * authorization endpoint execute commands. This mirrors the CLI login's
+ * opener (`yagni-code-cli/src/login.ts`; the extension cannot import that
+ * package, and the CLI's login tests pin the two resolvers together): the
+ * URL is always one literal argv element, and on Windows rundll32's
+ * FileProtocolHandler opens the default browser with no cmd.exe in between.
+ *
+ * A failure to open is thrown, never swallowed here: `authenticate()` logs
+ * it and keeps waiting, because the user still has the printed URL.
+ */
+export type OpenRunner = (cmd: string, args: string[]) => Promise<void>;
+export declare function resolveOpenCommand(url: string, platform?: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Hand an http(s) URL to the OS opener. Anything else (file:, javascript:,
+ * a custom scheme, garbage) is refused without invoking the runner; the
+ * refused URL is named in the error, since it carries no OAuth state. A
+ * runner failure rejects with the command named, so the log can tell a
+ * missing opener from a user who ignored the window.
+ */
+export declare function openUrlWith(url: string, runner: OpenRunner, platform?: NodeJS.Platform): Promise<void>;
+/**
+ * The real runner: a detached child with no stdio. `spawn` reports a missing
+ * binary (ENOENT) asynchronously; waiting for 'spawn' or 'error' turns that
+ * into a rejection instead of an unhandled 'error' event that would take
+ * the session down.
+ */
+export declare const spawnRunner: OpenRunner;
+/**
+ * The default browser opener. A no-op under the test runner: a test that
+ * forgets to inject `openUrl` must not pop a real browser window.
+ */
+export declare function defaultOpenUrl(url: string): Promise<void>;
+//# sourceMappingURL=openUrl.d.ts.map

package/dist/extension/mcp/openUrl.js

@@ -0,0 +1,80 @@
+/**
+ * Open a URL in the user's default browser without going through a shell.
+ *
+ * The OAuth authorize URL is long and full of `&`. `cmd /c start <url>` on
+ * Windows re-parses its arguments as a shell line, so cmd.exe split the URL
+ * at the first `&` and the browser opened `…/authorize?response_type=code`;
+ * Atlassian ID then showed "The authorize request was incomplete or invalid"
+ * (2026-09-21 customer report). The same re-parse would let a hostile
+ * authorization endpoint execute commands. This mirrors the CLI login's
+ * opener (`yagni-code-cli/src/login.ts`; the extension cannot import that
+ * package, and the CLI's login tests pin the two resolvers together): the
+ * URL is always one literal argv element, and on Windows rundll32's
+ * FileProtocolHandler opens the default browser with no cmd.exe in between.
+ *
+ * A failure to open is thrown, never swallowed here: `authenticate()` logs
+ * it and keeps waiting, because the user still has the printed URL.
+ */
+import { runningUnderTest } from "../crashReport.js";
+/** Keeps a failure's detail to one mcp.log-sized line (auth.ts caps at the same length). */
+const DETAIL_MAX = 300;
+export function resolveOpenCommand(url, platform = process.platform) {
+    if (platform === "darwin")
+        return { cmd: "open", args: [url] };
+    if (platform === "win32")
+        return { cmd: "rundll32", args: ["url.dll,FileProtocolHandler", url] };
+    return { cmd: "xdg-open", args: [url] };
+}
+/**
+ * Hand an http(s) URL to the OS opener. Anything else (file:, javascript:,
+ * a custom scheme, garbage) is refused without invoking the runner; the
+ * refused URL is named in the error, since it carries no OAuth state. A
+ * runner failure rejects with the command named, so the log can tell a
+ * missing opener from a user who ignored the window.
+ */
+export async function openUrlWith(url, runner, platform = process.platform) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        /* refused below */
+    }
+    if (!parsed || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) {
+        throw new Error(`refused: not an http(s) URL (${url})`.slice(0, DETAIL_MAX));
+    }
+    const { cmd, args } = resolveOpenCommand(url, platform);
+    try {
+        await runner(cmd, args);
+    }
+    catch (err) {
+        throw new Error(`${cmd}: ${err instanceof Error ? err.message : String(err)}`.slice(0, DETAIL_MAX));
+    }
+}
+/**
+ * The real runner: a detached child with no stdio. `spawn` reports a missing
+ * binary (ENOENT) asynchronously; waiting for 'spawn' or 'error' turns that
+ * into a rejection instead of an unhandled 'error' event that would take
+ * the session down.
+ */
+export const spawnRunner = async (cmd, args) => {
+    const { spawn } = await import("node:child_process");
+    await new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.once("error", reject);
+        child.once("spawn", () => {
+            child.unref();
+            resolve();
+        });
+    });
+};
+/**
+ * The default browser opener. A no-op under the test runner: a test that
+ * forgets to inject `openUrl` must not pop a real browser window.
+ */
+export async function defaultOpenUrl(url) {
+    if (runningUnderTest())
+        return;
+    await openUrlWith(url, spawnRunner);
+}
+//# sourceMappingURL=openUrl.js.map

package/dist/extension/mcp/panel.js

@@ -106,6 +106,10 @@ export function registerMcpPanel(pi, manager, configErrors) {
                 await doReconnect(sub[1], ctx.ui);
                 return;
             }
+            if ((sub[0] === "connect" || sub[0] === "authenticate") && sub[1]) {
+                await doAuthenticate(sub[1], ctx.ui, ctx.signal);
+                return;
+            }
             if (sub[0] === "enable" || sub[0] === "disable") {
                 await doToggle(sub[0], sub.slice(1), ctx.ui);
                 return;
@@ -124,7 +128,9 @@ export function registerMcpPanel(pi, manager, configErrors) {
             return;
         }
         ui.notify(`Starting OAuth for ${name} — your browser will open…`, "info");
-        const result = await manager.authenticateServer(name, signal);
+        const result = await manager.authenticateServer(name, signal, {
+            onAuthorizationUrl: (url) => ui.notify(`Browser didn't open? Open this URL to continue:\n${url}`, "info"),
+        });
         if (result?.status === "connected") {
             await refreshForServer(name);
             ui.notify(`✓ ${name} authenticated and connected`, "info");

package/dist/extension/permission/guardian.d.ts

@@ -2,9 +2,17 @@
  * The Guardian — LLM auto-review of prompt-band bash commands (YAG-504).
  *
  * Pure half: verdict types, state tracking, circuit breaker, JSON parsing.
- * I/O half: reviewCommand spawns a locked-down child pi (same runStage seam
- * the advisor uses) on the efficient tier with read-only tools and a risk
- * policy persona. The child returns a JSON verdict; the gate acts on it.
+ * I/O half: reviewCommand consults the guardian persona over the in-process
+ * direct transport (one /v1/chat/completions POST, same seam the prefix
+ * consult uses) on the efficient tier. The legacy child-spawn path
+ * (runStage, the advisor's seam) remains as the injectable test fallback.
+ * The consult returns a JSON verdict; the gate acts on it.
+ *
+ * The one deliberate verdict-semantics edge of the direct consult: it has no
+ * tools, so a command referencing an opaque script/config is judged from
+ * command text alone where the child could read the file first (Claude
+ * Code's equivalent check is also tool-less). Verdict parsing, the repair
+ * ladder, and the gate's handling are unchanged.
  *
  * Same pure/IO split as advisor.ts (decideConsult pure, askAdvisorTool I/O)
  * and permission.ts (decideGate pure, registerPermissionGate I/O), for the
@@ -46,14 +54,15 @@ export interface GuardianLimits {
 }
 export declare const DEFAULT_GUARDIAN_LIMITS: GuardianLimits;
 /**
- * Client-side safety margin on top of the backend's advertised wall ceiling
- * (YAG-562). The backend now owns the real timeout (first-output + wall) and
- * retries once, so the client must NOT pre-empt it; it derives its own
- * deadline from the catalog's `guardianTimeoutMs * attempts` plus this margin
- * for child boot + read-tool round-trips + teardown, and treats that bound as
- * a last-resort floor, not the normal path.
+ * Client-side safety margin on top of the backend's advertised wall ceiling.
+ * The backend owns the real timeout and retries, so the client must
+ * NOT pre-empt it; it derives its own deadline from the catalog's
+ * `guardianTimeoutMs * attempts` plus this margin, and treats that bound as a
+ * last-resort floor, not the normal path. Sized for the direct HTTP transport
+ * (one request, no child boot or read-tool round-trips); the legacy child
+ * path's spawn+teardown cost sat inside the backend's own advertised ceiling.
  */
-export declare const GUARDIAN_CLIENT_OVERHEAD_MS = 10000;
+export declare const GUARDIAN_CLIENT_OVERHEAD_MS = 2000;
 /**
  * Resolve Guardian limits from the environment. `YAGNI_GUARDIAN_MAX_REVIEWS`
  * overrides the sliding-window review cap; anything non-numeric or < 1 falls
@@ -64,7 +73,7 @@ export declare const GUARDIAN_CLIENT_OVERHEAD_MS = 10000;
 export declare function resolveGuardianLimits(env?: Record<string, string | undefined>): GuardianLimits;
 /**
  * Derive the client's whole-consult deadline from the backend's advertised
- * wall ceiling and attempt count (YAG-562). Falls back to the resolved limit
+ * wall ceiling and attempt count. Falls back to the resolved limit
  * when the catalog omitted the fields (older backend).
  */
 export declare function deriveGuardianTimeoutMs(base: GuardianLimits, advertised: {
@@ -75,6 +84,7 @@ export declare function deriveGuardianTimeoutMs(base: GuardianLimits, advertised
 export declare const GUARDIAN_MODEL_TIER = "efficient";
 /** Read-only tools — the Guardian can read files for context but cannot write or execute. */
 export declare const GUARDIAN_TOOLS: string[];
+export declare function _setGuardianPersonaBodyResolverForTest(resolver: (() => string) | null): void;
 /**
  * The review-cap window. `reviews` counts consults inside a SLIDING window
  * rather than for the session's lifetime: a 24/7 session (a fleet operator's
@@ -148,7 +158,33 @@ export interface ReviewCommandDeps {
      * an `ask` rationale can add information beyond the static rule text.
      */
     execJustification?: string;
+    /**
+     * The direct transport (the production path): one in-process
+     * /v1/chat/completions POST with the guardian persona as the system prompt —
+     * no child spawn, no grounded context. Absent → the legacy child-spawn path
+     * (the injectable test seam, same retention as the prefix consult).
+     *
+     * Accepted regression, pinned in tests: the OpenAI-shaped response carries
+     * token usage but no per-consult dollar cost, so `ReviewResult.cost` is 0
+     * on this path. The backend owns billing via the caller header either way.
+     */
+    transport?: {
+        baseUrl: string;
+        getToken: () => string | undefined;
+        /** Attribution headers (x-yagni-session-id / x-yagni-run-id). */
+        attribution?: () => Record<string, string>;
+    };
 }
+/**
+ * The transport revert knob (read per consult — `reviewCommand` itself calls
+ * it, so a flipped env var takes effect on the next gated command without a
+ * session restart): truthy forces the legacy child-spawn transport even when
+ * the direct transport is wired, so a transport-specific regression has a
+ * targeted rollback that does not disable the consult entirely. The gate's
+ * independent kill switch stays orthogonal.
+ */
+export declare function guardianLegacyTransportKnob(env?: NodeJS.ProcessEnv): boolean;
+export declare function _resetGuardianLegacyTransportWarnForTest(): void;
 /**
  * The synthetic stage a Guardian consult runs as. Borrows the `plan` StageId
  * (same pattern as the advisor) so it doesn't ripple into feed/reducers. The

package/dist/extension/permission/guardian.js

@@ -2,9 +2,17 @@
  * The Guardian — LLM auto-review of prompt-band bash commands (YAG-504).
  *
  * Pure half: verdict types, state tracking, circuit breaker, JSON parsing.
- * I/O half: reviewCommand spawns a locked-down child pi (same runStage seam
- * the advisor uses) on the efficient tier with read-only tools and a risk
- * policy persona. The child returns a JSON verdict; the gate acts on it.
+ * I/O half: reviewCommand consults the guardian persona over the in-process
+ * direct transport (one /v1/chat/completions POST, same seam the prefix
+ * consult uses) on the efficient tier. The legacy child-spawn path
+ * (runStage, the advisor's seam) remains as the injectable test fallback.
+ * The consult returns a JSON verdict; the gate acts on it.
+ *
+ * The one deliberate verdict-semantics edge of the direct consult: it has no
+ * tools, so a command referencing an opaque script/config is judged from
+ * command text alone where the child could read the file first (Claude
+ * Code's equivalent check is also tool-less). Verdict parsing, the repair
+ * ladder, and the gate's handling are unchanged.
  *
  * Same pure/IO split as advisor.ts (decideConsult pure, askAdvisorTool I/O)
  * and permission.ts (decideGate pure, registerPermissionGate I/O), for the
@@ -28,21 +36,25 @@
  * alternating deny/ask.
  */
 import { runStage as defaultRunStage } from "../pipeline/runner.js";
+import { directConsult } from "../pipeline/directConsult.js";
+import { PERSONA_BODIES } from "../pipeline/personas.js";
 import { scrubSecrets } from "../pipeline/scrubSecrets.js";
+import { logEvent } from "../errorSink.js";
 export const DEFAULT_GUARDIAN_LIMITS = {
     maxReviews: 120,
     maxConsecutiveDenials: 3,
     timeoutMs: 15_000,
 };
 /**
- * Client-side safety margin on top of the backend's advertised wall ceiling
- * (YAG-562). The backend now owns the real timeout (first-output + wall) and
- * retries once, so the client must NOT pre-empt it; it derives its own
- * deadline from the catalog's `guardianTimeoutMs * attempts` plus this margin
- * for child boot + read-tool round-trips + teardown, and treats that bound as
- * a last-resort floor, not the normal path.
+ * Client-side safety margin on top of the backend's advertised wall ceiling.
+ * The backend owns the real timeout and retries, so the client must
+ * NOT pre-empt it; it derives its own deadline from the catalog's
+ * `guardianTimeoutMs * attempts` plus this margin, and treats that bound as a
+ * last-resort floor, not the normal path. Sized for the direct HTTP transport
+ * (one request, no child boot or read-tool round-trips); the legacy child
+ * path's spawn+teardown cost sat inside the backend's own advertised ceiling.
  */
-export const GUARDIAN_CLIENT_OVERHEAD_MS = 10_000;
+export const GUARDIAN_CLIENT_OVERHEAD_MS = 2_000;
 /**
  * Resolve Guardian limits from the environment. `YAGNI_GUARDIAN_MAX_REVIEWS`
  * overrides the sliding-window review cap; anything non-numeric or < 1 falls
@@ -61,7 +73,7 @@ export function resolveGuardianLimits(env = process.env) {
 }
 /**
  * Derive the client's whole-consult deadline from the backend's advertised
- * wall ceiling and attempt count (YAG-562). Falls back to the resolved limit
+ * wall ceiling and attempt count. Falls back to the resolved limit
  * when the catalog omitted the fields (older backend).
  */
 export function deriveGuardianTimeoutMs(base, advertised) {
@@ -74,6 +86,31 @@ export function deriveGuardianTimeoutMs(base, advertised) {
 export const GUARDIAN_MODEL_TIER = "efficient";
 /** Read-only tools — the Guardian can read files for context but cannot write or execute. */
 export const GUARDIAN_TOOLS = ["read"];
+/**
+ * The guardian persona body — the system prompt on the direct transport. A
+ * missing/renamed persona must never silently degrade to an empty system
+ * prompt (every consult would run unprompted and the verdicts would drift
+ * with no telemetry signature), so a warn fires ONCE when it resolves empty.
+ * Same reset-export pattern as the prefix persona resolver.
+ */
+let guardianPersonaBodyWarned = false;
+let resolveGuardianPersonaBody = () => PERSONA_BODIES.guardian ?? "";
+export function _setGuardianPersonaBodyResolverForTest(resolver) {
+    resolveGuardianPersonaBody = resolver ?? (() => PERSONA_BODIES.guardian ?? "");
+    guardianPersonaBodyWarned = false;
+}
+function guardianPersonaBody() {
+    const body = resolveGuardianPersonaBody();
+    if (body.length === 0 && !guardianPersonaBodyWarned) {
+        guardianPersonaBodyWarned = true;
+        logEvent({
+            source: "guardian",
+            level: "warn",
+            event: "guardian_persona_body_missing",
+        });
+    }
+    return body;
+}
 // --- State ---
 /**
  * The review-cap window. `reviews` counts consults inside a SLIDING window
@@ -293,6 +330,28 @@ export function formatGuardianSubtotal(state, limits) {
  * it cannot balloon a log line or a Sentry payload.
  */
 export const GUARDIAN_RAW_OUTPUT_CAP = 2048;
+/**
+ * The transport revert knob (read per consult — `reviewCommand` itself calls
+ * it, so a flipped env var takes effect on the next gated command without a
+ * session restart): truthy forces the legacy child-spawn transport even when
+ * the direct transport is wired, so a transport-specific regression has a
+ * targeted rollback that does not disable the consult entirely. The gate's
+ * independent kill switch stays orthogonal.
+ */
+export function guardianLegacyTransportKnob(env = process.env) {
+    const v = env.YAGNI_GUARDIAN_LEGACY_TRANSPORT;
+    return v === "1" || v === "true";
+}
+/**
+ * One-time sink warn when the LEGACY child transport runs in a session whose
+ * gate wired the direct transport — the two paths are indistinguishable in
+ * outcome telemetry, so this line is the only place a transport regression
+ * (forcing the knob for a workspace) becomes visible.
+ */
+let guardianLegacyTransportWarned = false;
+export function _resetGuardianLegacyTransportWarnForTest() {
+    guardianLegacyTransportWarned = false;
+}
 /**
  * The synthetic stage a Guardian consult runs as. Borrows the `plan` StageId
  * (same pattern as the advisor) so it doesn't ripple into feed/reducers. The
@@ -328,39 +387,17 @@ export async function reviewCommand(command, deps) {
         else
             deps.signal.addEventListener("abort", () => controller.abort(), { once: true });
     }
-    try {
-        const justificationLine = deps.execJustification
-            ? `\n\nWhy this command was routed to you (static policy): ${deps.execJustification}`
-            : "";
-        const result = await runStage(stage, { ticket: `Review this shell command for safety. Output only the JSON verdict.${justificationLine}\n\nCommand:\n${command}` }, {
-            cwd: deps.cwd,
-            signal: controller.signal,
-            callerLabel: "guardian",
-        });
-        const cost = result.usage?.cost ?? 0;
-        const output = result.finalOutput.trim();
-        // An aborted child often RESOLVES with empty/partial output instead of
-        // throwing (observed live: ESC → 433ms "empty"). Any result produced
-        // while the caller's signal is aborted is an abort, not an outage — the
-        // gate must not warn or fall back to an ask on it.
-        if (deps.signal?.aborted) {
-            return { verdict: null, error: "aborted", cost };
-        }
-        // The backend now owns the timeout (YAG-562) and streams a terminal error
-        // frame when the consult fails; a result with a `stopReason: "error"` or an
-        // `errorMessage` is a real backend failure, NOT the silent-empty shape. Map
-        // it to a concrete error so the gate shows "review timed out" / "service
-        // unavailable" instead of the misleading "no response". A timeout-shaped
-        // message (stream_idle_timeout / "timed out") is distinguished so the gate
-        // can add its timeout-specific note.
-        if (!output) {
-            if (result.stopReason === "error" || result.errorMessage) {
-                const msg = (result.errorMessage ?? "").toLowerCase();
-                const isTimeout = /stream_idle_timeout|timed out|idle|wall|timeout/i.test(msg);
-                return { verdict: null, error: isTimeout ? "timeout" : "network", cost };
-            }
-            return { verdict: null, error: "empty", cost };
-        }
+    const justificationLine = deps.execJustification
+        ? `\n\nWhy this command was routed to you (static policy): ${deps.execJustification}`
+        : "";
+    const consultPrompt = `Review this shell command for safety. Output only the JSON verdict.${justificationLine}\n\nCommand:\n${command}`;
+    /**
+     * Classify a non-empty model output into a ReviewResult: verdict,
+     * repaired-verdict, or malformed with the scrubbed/capped raw capture.
+     * Shared by both transports so verdict semantics cannot drift between
+     * them (the acceptance criterion: only the transport changes).
+     */
+    const classifyOutput = (output, cost) => {
         const parsed = parseVerdictDetailed(output);
         if (!parsed) {
             // Scrubbed + capped so the local sink and Sentry can see the exact
@@ -385,18 +422,161 @@ export async function reviewCommand(command, deps) {
             };
         }
         return { verdict: parsed.verdict, cost };
-    }
-    catch (err) {
-        // Distinguish the caller aborting (user hit ESC — must NOT be treated as
-        // an outage, or the fallback ask would pop a dialog on an aborted turn),
-        // our own timeout, and real network/process errors.
+    };
+    /**
+     * Classify a thrown consult error: the caller aborting (user hit ESC — must
+     * NOT be treated as an outage, or the fallback ask would pop a dialog on an
+     * aborted turn), our own deadline, and real network/transport errors. The
+     * thrown message itself never reaches telemetry (it can carry provider
+     * payloads — the prefix consult's scrub doctrine); the ERROR CLASS rides
+     * the local sink line — emitted only for the NETWORK classification, with
+     * the resolved outcome in fields, so routine aborts and deadline timeouts
+     * (the two shapes that must NOT read as outages) never emit a warn line.
+     */
+    const classifyThrow = (err) => {
+        const errorClass = err instanceof Error ? err.constructor.name : typeof err;
         if (deps.signal?.aborted) {
             return { verdict: null, error: "aborted", cost: 0 };
         }
         if (controller.signal.aborted) {
             return { verdict: null, error: "timeout", cost: 0 };
         }
+        logEvent({
+            source: "guardian",
+            level: "warn",
+            event: "guardian_consult_error",
+            fields: { outcome: "network", errorClass },
+        });
         return { verdict: null, error: "network", cost: 0 };
+    };
+    /**
+     * The direct transport: one /v1/chat/completions POST with the guardian
+     * persona as the system prompt and the consult prompt as user content —
+     * no child spawn, no grounded context, ~1k input tokens instead of ~31k.
+     */
+    const reviewViaDirect = async () => {
+        const t = deps.transport;
+        // A missing/renamed guardian persona fails CLOSED: an empty system prompt
+        // would consult with no risk taxonomy and no JSON contract — a
+        // permissive bias on a safety gate. Returning an error class lets the
+        // gate's bounded fallback (ask the user / fail closed) handle it. The
+        // outcome stays "network" (the gate treats it identically), but a
+        // PER-OCCURRENCE sink line marks the true shape — a config/packaging bug
+        // must read as "persona missing" at 2am in any session, not as an
+        // outage (the once-per-process body warn may predate a fresh session).
+        const systemPrompt = guardianPersonaBody();
+        if (systemPrompt.length === 0) {
+            logEvent({
+                source: "guardian",
+                level: "error",
+                event: "guardian_persona_missing",
+                fields: { outcome: "network" },
+            });
+            return { verdict: null, error: "network", cost: 0 };
+        }
+        try {
+            const res = await directConsult({ systemPrompt, userContent: consultPrompt, modelTier: deps.modelTier ?? GUARDIAN_MODEL_TIER }, {
+                baseUrl: t.baseUrl,
+                getToken: t.getToken,
+                attribution: t.attribution ?? (() => ({})),
+                callerLabel: "guardian",
+                signal: controller.signal,
+            });
+            const output = res.text.trim();
+            // An aborted request can resolve with empty/partial output instead of
+            // throwing — any result produced while the caller's signal is aborted
+            // is an abort, not an outage.
+            if (deps.signal?.aborted) {
+                return { verdict: null, error: "aborted", cost: res.cost };
+            }
+            if (!output) {
+                // A 200 with no/blank content is an EMPTY result: the backend's
+                // non-stream pipeline has already done its own empty-result retry
+                // and failover by this point, so the client does not retry again —
+                // the gate's bounded error fallback handles it. Aligned with the
+                // child path: a result resolving after the client's own deadline
+                // fired reads as a timeout, never as a silent empty.
+                if (controller.signal.aborted) {
+                    return { verdict: null, error: "timeout", cost: res.cost };
+                }
+                return { verdict: null, error: "empty", cost: res.cost };
+            }
+            return classifyOutput(output, res.cost);
+        }
+        catch (err) {
+            return classifyThrow(err);
+        }
+    };
+    /**
+     * The legacy child transport (the injectable test seam; also the targeted
+     * rollback when the revert knob forces it). Spawns a locked-down child pi
+     * via runStage and reduces its NDJSON stream.
+     */
+    const reviewViaChild = async () => {
+        try {
+            return await runChild();
+        }
+        catch (err) {
+            return classifyThrow(err);
+        }
+    };
+    const runChild = async () => {
+        const result = await runStage(stage, { ticket: consultPrompt }, {
+            cwd: deps.cwd,
+            signal: controller.signal,
+            callerLabel: "guardian",
+        });
+        const cost = result.usage?.cost ?? 0;
+        const output = result.finalOutput.trim();
+        // An aborted child often RESOLVES with empty/partial output instead of
+        // throwing (observed live: ESC → 433ms "empty"). Any result produced
+        // while the caller's signal is aborted is an abort, not an outage — the
+        // gate must not warn or fall back to an ask on it.
+        if (deps.signal?.aborted) {
+            return { verdict: null, error: "aborted", cost };
+        }
+        // The backend now owns the timeout (YAG-562) and streams a terminal error
+        // frame when the consult fails; a result with a `stopReason: "error"` or an
+        // `errorMessage` is a real backend failure, NOT the silent-empty shape. Map
+        // it to a concrete error so the gate shows "review timed out" / "service
+        // unavailable" instead of the misleading "no response". A timeout-shaped
+        // message (stream_idle_timeout / "timed out") is distinguished so the gate
+        // can add its timeout-specific note.
+        if (!output) {
+            if (result.stopReason === "error" || result.errorMessage) {
+                const msg = (result.errorMessage ?? "").toLowerCase();
+                const isTimeout = /stream_idle_timeout|timed out|idle|wall|timeout/i.test(msg);
+                return { verdict: null, error: isTimeout ? "timeout" : "network", cost };
+            }
+            // The client's own deadline firing resolves the child with empty output
+            // (runStage SIGTERMs and resolves, it does not throw) — the previous
+            // classification mislabeled this last-resort abort as "no response";
+            // it is a timeout (observed live: every "empty" event at the derived
+            // 100s deadline).
+            if (controller.signal.aborted) {
+                return { verdict: null, error: "timeout", cost };
+            }
+            return { verdict: null, error: "empty", cost };
+        }
+        return classifyOutput(output, cost);
+    };
+    const useLegacy = !deps.transport || guardianLegacyTransportKnob();
+    if (useLegacy && deps.transport) {
+        // The knob forced the child path in a session that wired the direct
+        // transport — the one line that makes a forced rollback visible in the
+        // local trail (the two paths are otherwise indistinguishable in outcome
+        // telemetry). One-time, never per-call.
+        if (!guardianLegacyTransportWarned) {
+            guardianLegacyTransportWarned = true;
+            logEvent({
+                source: "guardian",
+                level: "warn",
+                event: "guardian_legacy_transport_used",
+            });
+        }
+    }
+    try {
+        return useLegacy ? await reviewViaChild() : await reviewViaDirect();
     }
     finally {
         clearTimeout(timer);

package/dist/extension/pipeline/directConsult.js

@@ -42,10 +42,12 @@ export async function directConsult(req, opts) {
     }
     const data = (await res.json());
     // A 200 with no/blank content is an EMPTY result, not a transport error:
-    // the consult's error classifier treats `empty` as retryable-once (the
-    // backend's own 502-shape body invites exactly that), and a thrown error
-    // here would misclassify that shape as `network`. A genuinely malformed
-    // (non-JSON) body still throws below.
+    // each consult's OWN classifier decides the retry policy for the shape
+    // (the prefix consult retries once — the backend's own 502-shape body
+    // invites it; the guardian consult does not — its non-stream pipeline
+    // already retried and failed over server-side). A thrown error here
+    // would misclassify the shape as `network` for every consult regardless
+    // of its policy. A genuinely malformed (non-JSON) body still throws below.
     const text = data.choices?.[0]?.message?.content ?? "";
     return { text, cost: typeof data.usage?.cost === "number" ? data.usage.cost : 0 };
 }

package/dist/extension/sandbox/bash.d.ts

@@ -148,9 +148,9 @@ export declare function isSandboxDenialOutput(output: string): boolean;
  * offending path when found (pi-sandbox's regex, credited MIT).
  */
 export declare function extractBlockedWritePath(output: string): string | null;
-/** The three network-posture denial classes this classifier knows (closed
+/** The network-posture denial classes this classifier knows (closed
  * set — rides the sink line as a low-cardinality field). */
-export type NetworkDenialClass = "ipc-listen" | "tls-trustd" | "loopback";
+export type NetworkDenialClass = "ipc-listen" | "tls-trustd" | "loopback" | "dns" | "ssh-proxy";
 /**
  * Classify a sandbox network-posture denial from command output. Pure;
  * advisory-only (never widens anything — the fix is a knob the USER flips,
@@ -164,6 +164,20 @@ export type NetworkDenialClass = "ipc-listen" | "tls-trustd" | "loopback";
  *   - loopback:     EPERM/"not permitted" on a connect to 127.0.0.1/
  *                   localhost/::1 (loopback bypasses the proxy via
  *                   no_proxy, so the allowlist can never admit it)
+ *   - dns:          raw name-resolution failure (getaddrinfo/nslookup/ping
+ *                   spellings). The profile denies DNS by design — proxy-
+ *                   aware tools ride the mux where the PARENT resolves;
+ *                   raw resolvers fail. This class exists so the failure
+ *                   reads as the fence working (not the machine losing
+ *                   connectivity) and seeds the rung's brake — a
+ *                   DNS-shaped sandboxed failure re-arms the consent
+ *                   dialog, never loops silently.
+ *   - ssh-proxy:   git-over-SSH through the sandbox's SSH bridge (nc
+ *                   ProxyCommand): the bridge carries no credential, so
+ *                   the mux policy-refuses it even for granted domains;
+ *                   ssh renders the refusal as a dispatch fatal on
+ *                   "UNKNOWN port 65535" (nc's rewrite of the proxied
+ *                   endpoint — a real server renders its own address).
  * Returns null when the output carries no network-posture signature — a
  * plain file-write EPERM must NOT get a network hint.
  */

package/dist/extension/sandbox/bash.js

@@ -437,6 +437,20 @@ export function extractBlockedWritePath(output) {
  *   - loopback:     EPERM/"not permitted" on a connect to 127.0.0.1/
  *                   localhost/::1 (loopback bypasses the proxy via
  *                   no_proxy, so the allowlist can never admit it)
+ *   - dns:          raw name-resolution failure (getaddrinfo/nslookup/ping
+ *                   spellings). The profile denies DNS by design — proxy-
+ *                   aware tools ride the mux where the PARENT resolves;
+ *                   raw resolvers fail. This class exists so the failure
+ *                   reads as the fence working (not the machine losing
+ *                   connectivity) and seeds the rung's brake — a
+ *                   DNS-shaped sandboxed failure re-arms the consent
+ *                   dialog, never loops silently.
+ *   - ssh-proxy:   git-over-SSH through the sandbox's SSH bridge (nc
+ *                   ProxyCommand): the bridge carries no credential, so
+ *                   the mux policy-refuses it even for granted domains;
+ *                   ssh renders the refusal as a dispatch fatal on
+ *                   "UNKNOWN port 65535" (nc's rewrite of the proxied
+ *                   endpoint — a real server renders its own address).
  * Returns null when the output carries no network-posture signature — a
  * plain file-write EPERM must NOT get a network hint.
  */
@@ -513,6 +527,52 @@ export function networkDenialHint(output) {
                 "The local-binding knob is ON by default — this denial means it was turned off; the user can re-enable it in the /sandbox panel (Network tab). Retrying with dangerouslyDisableSandbox is NOT needed once the knob is on.",
         };
     }
+    // ssh-proxy: the SSH-bridge policy refusal — matched BEFORE dns (the
+    // ordering pin): a DNS-shaped failure from an ssh prefix classifies as
+    // dns (the more honest diagnosis — alias resolution failed), while the
+    // bridge refusal is the UNKNOWN-port dispatch fatal or the mux's own
+    // refusal sentence. "UNKNOWN port 65535" is nc's rewrite of the
+    // proxied destination; a refusing-but-real server renders its own
+    // address there, so the UNKNOWN shape is proxy-specific by construction.
+    if (/ssh_dispatch_run_fatal: Connection to UNKNOWN port \d+: (Broken pipe|Connection reset)/i.test(output) ||
+        /kex_exchange_identification: Connection (?:closed|reset) by UNKNOWN port \d+/i.test(output) ||
+        /This proxy requires authentication[^.]*\bdid not offer an authentication method/i.test(output) ||
+        /SSH-2\.0-policy_refusal/.test(output)) {
+        return {
+            cls: "ssh-proxy",
+            hint: "This looks like a sandbox git-over-SSH denial (the SSH bridge routes ssh through the sandbox proxy, which carries no credential — git over SSH cannot ride it even for granted domains). " +
+                "Use the HTTPS remote for this operation, or retry outside the sandbox (the user will be asked). Do not treat this as a network outage.",
+        };
+    }
+    // dns: raw name-resolution failure — the fence denies DNS by design;
+    // proxy-aware tools ride the mux (parent-side resolution), raw
+    // resolvers do not. Per-line discipline matches the EPERM branch
+    // (numbered grep hits, quoted text, and prose-initial lines are data):
+    // "Could not resolve host" is prose-likely enough that a bare
+    // substring match would fire on quoted log lines.
+    {
+        const dnsPhrases = /Could not resolve host(?:name)?|nodename nor servname provided|Name or service not known|Temporary failure in name resolution|getaddrinfo (?:ENOTFOUND|EAI_AGAIN|EAI_NONAME)|cannot resolve \S+: Unknown host|no servers could be reached|no DNS configuration/i;
+        for (const line of output.split("\n")) {
+            const t = line.trim();
+            if (!dnsPhrases.test(t))
+                continue;
+            if (/^\d+:/.test(t))
+                continue; // numbered grep/log hit — data
+            if (/^["']/.test(t))
+                continue; // quoted text — data
+            // Prose-initial: the phrase behind an article/conjunction opener is
+            // data ("if the host could not resolve…"). A `tool:` prefix or the
+            // bare phrase at line head is the diagnostic shape (same split as
+            // the EPERM branch's prose exclusion).
+            if (/^(the|a|an|this|that|it|when|if|note|tip|for|some)\b/i.test(t))
+                continue;
+            return {
+                cls: "dns",
+                hint: "This looks like a sandbox DNS-resolution denial (raw name resolution is unavailable inside the sandbox by design — proxy-aware tools ride the network proxy, where the parent resolves). " +
+                    "This is NOT evidence the machine lost connectivity; do not diagnose network health from inside the sandbox. If this command genuinely needs direct network, retry with dangerouslyDisableSandbox (the user will be asked).",
+            };
+        }
+    }
     return null;
 }
 /**

package/dist/extension/sandbox/session.js

@@ -128,9 +128,15 @@ export function makeBashComposition(manager, settings, cwd, onShellResolutionRet
         // auto-allow, and the escape rung at once. Stated here so the model
         // never mints one.
         const envPrefixNote = "Do not prepend environment variables you have not verified exist (grep the tool's binary/docs/help first) — an unverified prefix defeats grants, auto-allow, and the sandbox retry rung; write the plain command instead.";
+        // The git-over-SSH caveat: the SSH bridge carries no credential, so a
+        // granted domain does NOT make git-over-SSH work — the model that
+        // expects the grant to cover an SSH remote reads the bridge refusal as
+        // a network outage and probes (the incident session burned 10 minutes
+        // on exactly that). The HTTPS remote is the in-sandbox cure.
+        const gitSshNote = "Git commands that talk to a remote over SSH (git@… URLs) cannot ride the sandbox's network proxy on macOS — expect an SSH-bridge or DNS failure and either use the HTTPS remote, or retry outside the sandbox (the user will be asked). A granted domain does not make git-over-SSH work.";
         const wrapped = {
             ...def,
-            description: `${def.description}\n\n## Command sandbox\nCommands run inside an OS sandbox: ${restrictions.join("; ")}. ${strictNote}\n${heredocNote}\n${tmpdirNote}\n${envPrefixNote}`,
+            description: `${def.description}\n\n## Command sandbox\nCommands run inside an OS sandbox: ${restrictions.join("; ")}. ${strictNote}\n${heredocNote}\n${tmpdirNote}\n${envPrefixNote}\n${gitSshNote}`,
             parameters: schema,
             async execute(id, params, signal, onUpdate, ctx) {
                 const input = params;
@@ -358,10 +364,14 @@ export function registerSandbox(pi, opts) {
         if (sessionDomainGrants.has(host))
             return true;
         const ui = uiBridge;
-        if (!ui?.hasUI)
+        if (!ui?.hasUI) {
+            logNetworkAsk(host, "headless", null);
             return false; // headless: fail closed (never grant silently)
-        if (ui.signal?.aborted)
+        }
+        if (ui.signal?.aborted) {
+            logNetworkAsk(host, "aborted", null);
             return false;
+        }
         // Claude-parity grant options. Session grant is memory-only and
         // agent-invisible; project/user write the sandbox config file.
         const dialogOpts = {
@@ -378,13 +388,36 @@ export function registerSandbox(pi, opts) {
                 "Block",
             ], dialogOpts);
         }
-        catch {
+        catch (err) {
+            // A real 600s timeout vs an immediate UI-bridge error are different
+            // failures; the deny behavior is identical, but the trail says which:
+            // the dialog's own timeout throws a name-matched abort/timeout error
+            // (pi's select timeout shape), anything else is a bridge failure.
+            const isTimeout = err instanceof Error && /timeout|abort/i.test(err.name);
+            logNetworkAsk(host, isTimeout ? "timeout" : "error", null);
             return false; // dialog error / timeout: never grant
         }
-        if (choice === undefined || choice === "Block")
+        // A signal abort while the dialog was open resolves select to undefined
+        // — that is the session tearing down, not the user choosing Block.
+        if (ui.signal?.aborted) {
+            logNetworkAsk(host, "aborted", null);
             return false;
-        sessionDomainGrants.add(host);
-        if (choice.startsWith("Allow for this project")) {
+        }
+        if (choice === undefined || choice === "Block") {
+            logNetworkAsk(host, "block", null);
+            return false;
+        }
+        // FAIL-CLOSED choice dispatch: every branch matches its option label
+        // explicitly — an unrecognized choice (a renamed/added dialog option in
+        // a future version) never silently grants; it denies with its own
+        // outcome in the trail.
+        if (choice.startsWith("Allow for this session")) {
+            sessionDomainGrants.add(host);
+            logNetworkAsk(host, "session", null);
+        }
+        else if (choice.startsWith("Allow for this project")) {
+            sessionDomainGrants.add(host);
+            logNetworkAsk(host, "allow", "project");
             try {
                 persistDomainGrant(opts.projectRoot ?? opts.cwd, host, resolvedStateHome);
             }
@@ -397,6 +430,8 @@ export function registerSandbox(pi, opts) {
             }
         }
         else if (choice.startsWith("Allow for all projects")) {
+            sessionDomainGrants.add(host);
+            logNetworkAsk(host, "allow", "user");
             try {
                 persistDomainGrant(null, host, resolvedStateHome);
             }
@@ -405,6 +440,10 @@ export function registerSandbox(pi, opts) {
                 ui.ui.notify?.("Could not persist the domain grant to the config file — it applies to this session only.", "warning");
             }
         }
+        else {
+            logNetworkAsk(host, "unknown", null);
+            return false; // an unrecognized choice never grants
+        }
         // The grant must reach the live srt config before the retry.
         manager.refreshConfig([...effectiveRulesForSandbox()]);
         return true;
@@ -945,6 +984,23 @@ function logFsDenialHint(fs, surface) {
         return;
     logEvent({ source: "sandbox", level: "info", event: "fs_denial_hint", fields: { class: fs.cls, surface } });
 }
+/** Sink line for every network-ask resolution. The ask was invisible in the
+ * incident session's trail — whether the dialog fired, which option was
+ * picked, and where the grant persisted had to be reconstructed from the
+ * config file by hand. outcome: session | allow | block | timeout |
+ * aborted | headless | unknown | error (the closed resolution vocabulary);
+ * tier: where a persistent grant landed (project | user) or null. The
+ * host rides the field (same exposure class as logGrantPersistFailure's
+ * `grant`) — the sink scrubs each line, and the transcript carries hosts
+ * anyway. */
+function logNetworkAsk(host, outcome, tier) {
+    logEvent({
+        source: "sandbox",
+        level: "info",
+        event: "network_ask",
+        fields: { host, outcome, tier },
+    });
+}
 /** Sink line for a failed domain-grant persist — the thrown message is
  * mutateConfigJson's own path/reason text (diagnosable, no file content),
  * same posture as sandbox_persist_failed / rule_save_failed. */

package/dist/mcpCommand.d.ts

@@ -42,6 +42,8 @@ export interface McpCliModule {
         type: "http";
         url: string;
         tools: string[];
+    }, deps?: {
+        onAuthorizationUrl?: (url: string) => void;
     }): Promise<{
         result: "AUTHORIZED";
     }>;
@@ -64,6 +66,7 @@ export interface McpCliModule {
     };
     updateStoredOAuthEntry(serverName: string, config: unknown, mutate: (entry: {
         clientSecret?: string;
+        clientSecretSource?: "dcr" | "operator";
     }) => void): {
         errors: unknown[];
     };

package/dist/mcpCommand.js

@@ -412,7 +412,9 @@ async function connectWorkers(mod, parsed, io, env) {
         if (shadow)
             throw new Error("A project or local yagni-workers entry would override this connection. Remove that entry before connecting");
         io.stdout("Opening YAGNI in your browser. Choose your workspace and permissions; paid Worker requests use that workspace's balance.\n");
-        await mod.authenticate("yagni-workers", config);
+        await mod.authenticate("yagni-workers", config, {
+            onAuthorizationUrl: (url) => io.stdout(`If your browser did not open, visit:\n${url}\n`),
+        });
         writeServerToScope(mod, "yagni-workers", config, "user", io.cwd);
         io.stdout("Workers connected. Start a new YAGNI Code session to use them; /mcp shows connection status.\n");
         return 0;
@@ -491,6 +493,8 @@ function persistAdd(mod, name, serverConfig, parsed, io) {
             if (secret) {
                 mod.updateStoredOAuthEntry(name, serverConfig, (entry) => {
                     entry.clientSecret = secret;
+                    // The operator's secret survives a DCR client drop; a DCR-issued one does not.
+                    entry.clientSecretSource = "operator";
                 });
             }
             else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.1.6-staging.1445.1",
+  "version": "1.1.6-staging.1449.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -58,5 +58,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "df1d49933fa6a71d3b18754a183b5e400a45053a"
+  "yagniSourceSha": "49d55bc47e1e42094c17731b568fd3410e9c4781"
 }