@yagni-app/code-staging 1.1.4-staging.1422.1 → 1.1.4-staging.1424.1

package/README.md

@@ -23,6 +23,19 @@ correct, autonomous work than a coding agent that starts blank.
 npm install -g @yagni-app/code
 ```
 
+Or use the installer, which also repairs an npm global prefix your user
+cannot write to (common on managed machines) without sudo:
+
+```bash
+# macOS / Linux
+curl -fsSL https://yagni.app/install.sh | sh
+```
+
+```powershell
+# Windows (PowerShell)
+irm https://yagni.app/install.ps1 | iex
+```
+
 Requires Node.js 22.19 or newer (`node --version`); an older Node stops at
 launch with an upgrade message instead of crashing mid-session.
 

package/dist/extension/index.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { Text } from "@earendil-works/pi-tui";
 import { DEFAULT_ADVISOR_LIMITS, formatAdvisorSubtotal, makeAdvisorState } from "./advisor.js";
 import { makeChildUsageState } from "./childUsage.js";
-import { appendGrant, loadGrants, resolveRepoKey, storagePrefix } from "./permission/approvedPrefixes.js";
+import { appendGrant, createGrantsRefresher, loadGrants, resolveRepoKey, storagePrefix } from "./permission/approvedPrefixes.js";
 import { redactCommand } from "./redact.js";
 import { formatGuardianSubtotal, GUARDIAN_MODEL_TIER, makeGuardianState, resolveGuardianLimits, reviewCommand, deriveGuardianTimeoutMs } from "./permission/guardian.js";
 import { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
@@ -751,11 +751,22 @@ export async function registerYagni(pi, deps = {}) {
             }
         })();
     };
-    // YAG-510: persisted "don't ask again" grants, per-repo keyed. Loaded once
-    // at startup (grants added by other concurrent sessions appear next launch —
-    // the startup load is the trust boundary; live reload was reviewed and
-    // rejected as a same-session self-authorization path, PR #1698).
+    // YAG-510: persisted "don't ask again" grants, per-repo keyed. Loaded at
+    // startup PLUS refreshed at ask time (adopt-only — see refreshGrants
+    // below): grants banked by concurrent sessions are adopted at the next
+    // grant consultation, while same-session self-authorization stays closed
+    // — the OS sandbox's denyWrite band on ~/.yagni-code (pinned by test)
+    // means planting a grant still requires an approved unsandboxed write.
+    // (Supersedes the pure load-once posture from the PR #1698 review: the
+    // dead-grant re-asks it produced — 11 in the 5-day operator dataset —
+    // outweighed the same-tick write race it guarded against, and the
+    // guard it actually needed lives in the sandbox, not the load.)
     const sessionGrants = evalMode ? [] : loadGrants();
+    // Ask-time adopt-only refresh (the dead-grant re-ask fix): the
+    // createGrantsRefresher seam (approvedPrefixes.ts — owns the stamp pair,
+    // the failure trail, and the null-baseline recovery, all unit-tested
+    // directly); the gate merges whatever it returns ADOPT-ONLY.
+    const grantsRefresher = createGrantsRefresher();
     // Prior sandboxed failures (the auto-sandbox rung's session state): a
     // bash tool_result whose output carries a sandbox-denial signature marks
     // the command — its later escape attempts go to the consent dialog (the
@@ -990,6 +1001,7 @@ export async function registerYagni(pi, deps = {}) {
         },
         grants: sessionGrants,
         resolveRepoKey,
+        refreshGrants: () => (evalMode ? null : grantsRefresher()),
         persistGrant: (grant) => {
             if (!evalMode)
                 appendGrant(grant);

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

@@ -307,7 +307,26 @@ export declare function rulesFilePath(homeOverride?: string | null): string;
  * missing). Fail-soft — never throws.
  */
 export declare function resolveRepoKey(cwd: string): string;
-/** Load persisted grants. Malformed or missing file → empty (fail-soft). */
+/**
+ * loadGrants's result TRIPLE — distinguishes the three terminal states the
+ * refresher keys on: parsed grants, a PARSED-EMPTY store (version-1 file
+ * with an empty list — a legitimate bulk cleanup), and a FAILURE (missing
+ * file, unreadable, malformed). The failure carries a CAUSE — the errno
+ * code for I/O throws (a fixed OS vocabulary: ENOENT/EACCES/EISDIR…),
+ * "malformed" for content the parser or validator rejects — so the
+ * refresher's trail names the real failure instead of an undifferentiated
+ * string.
+ */
+export type GrantsLoad = {
+    ok: true;
+    grants: ApprovedPrefixGrant[];
+} | {
+    ok: false;
+    cause: string;
+};
+export declare function loadGrantsSentinel(homeOverride?: string | null): GrantsLoad;
+/** Load persisted grants. Malformed or missing file → empty (fail-soft).
+ * Delegates to loadGrantsSentinel so the row validation is shared. */
 export declare function loadGrants(homeOverride?: string | null): ApprovedPrefixGrant[];
 /**
  * Persist a new grant: re-read the file, merge (drop exact duplicates), write.
@@ -316,4 +335,35 @@ export declare function loadGrants(homeOverride?: string | null): ApprovedPrefix
  * never (fail-soft, returns the in-memory merge even if the write fails).
  */
 export declare function appendGrant(grant: ApprovedPrefixGrant, homeOverride?: string | null): ApprovedPrefixGrant[];
+/**
+ * The ask-time adopt-only grant refresh (the dead-grant re-ask fix) — the
+ * PRODUCTION seam index.ts wires into the gate's refreshGrants dep.
+ *
+ * One consultation: stat rules.json and compare against the last-seen stamp
+ * (an mtimeMs+size pair — mtimeMs alone can miss a same-tick rewrite);
+ * return the fresh grant list ONLY when the file changed, null when it
+ * hasn't. The gate merges whatever returns ADOPT-ONLY (append; its session
+ * grants are never removed) — this side only supplies the data.
+ *
+ * Failure contracts, all test-pinned:
+ *   - a PARSED-EMPTY store (version-1, empty list — a legitimate bulk
+ *     cleanup) consumes the stamp: no adoption (there is nothing to
+ *     adopt), but no re-read storm either, and no trail — it is a healthy
+ *     state, not a failure;
+ *   - a FAILED load (missing, unreadable, malformed — the fail-soft-empty
+ *     class loadGrants cannot distinguish on its own) leaves one sink line
+ *     (grants_refresh_failed) and does NOT consume the stamp: the next
+ *     consultation retries until a real parse succeeds, so a repair adopts
+ *     instead of reading as unchanged forever;
+ *   - a PERSISTENTLY ABSENT store is the normal fresh-install state: when
+ *     it was absent at boot too (null baseline), its stat throw is SILENT
+ *     — one warn per grant check all session would drown the signal for
+ *     every new user. The trail fires only when a store that EXISTED
+ *     becomes unreadable, or when the throw is something other than a
+ *     plain absence (ENOENT);
+ *   - a NULL baseline also makes the FIRST consultation adopt whatever
+ *     is on disk — recovery from a boot-time read failure without waiting
+ *     for a further file change.
+ */
+export declare function createGrantsRefresher(homeOverride?: string | null): () => ApprovedPrefixGrant[] | null;
 //# sourceMappingURL=approvedPrefixes.d.ts.map

package/dist/extension/permission/approvedPrefixes.js

@@ -26,10 +26,11 @@
  * testable without touching the filesystem.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { classifyCommand, isSafeRedirect, shellParse, tokenize } from "./execPolicy.js";
 import { SAFE_ENV_VARS } from "../permissionRules/shellRules.js";
+import { logEvent } from "../errorSink.js";
 import { codeStateHome } from "../stateHome.js";
 // --- Derivation ---
 /**
@@ -987,32 +988,52 @@ export function resolveRepoKey(cwd) {
         return cwd;
     }
 }
-/** Load persisted grants. Malformed or missing file → empty (fail-soft). */
-export function loadGrants(homeOverride = null) {
+/** loadGrants with the sentinel: parsed grants vs parsed-empty vs failure. */
+/**
+ * The ONE row validator every loader goes through — the boot-time loader
+ * and the refresh sentinel must agree on what counts as a grant by
+ * CONSTRUCTION, never by duplicated predicates (drift between them was a
+ * review finding: a grant accepted at boot but rejected at refresh — or
+ * vice versa — silently breaks the adoption contract).
+ */
+function isValidGrant(g) {
+    if (typeof g !== "object" || g === null)
+        return false;
+    const row = g;
+    return (typeof row.repoKey === "string" &&
+        typeof row.addedAt === "string" &&
+        typeof row.cwd === "string" &&
+        ((Array.isArray(row.pattern) &&
+            row.pattern.length > 0 &&
+            row.pattern.every((t) => typeof t === "string") &&
+            isDerivablePattern(row.pattern)) ||
+            (Array.isArray(row.pattern) &&
+                row.pattern.length === 0 &&
+                typeof row.literal === "string" &&
+                row.literal.length > 0)));
+}
+export function loadGrantsSentinel(homeOverride = null) {
     try {
         const path = rulesFilePath(homeOverride);
         if (!existsSync(path))
-            return [];
+            return { ok: false, cause: "ENOENT" };
         const parsed = JSON.parse(readFileSync(path, "utf8"));
-        if (parsed?.version !== 1 || !Array.isArray(parsed.grants))
-            return [];
-        return parsed.grants.filter((g) => typeof g?.repoKey === "string" &&
-            typeof g?.addedAt === "string" &&
-            typeof g?.cwd === "string" &&
-            // literal rung: empty pattern + a non-empty string literal
-            ((Array.isArray(g?.pattern) &&
-                g.pattern.length > 0 &&
-                g.pattern.every((t) => typeof t === "string") &&
-                isDerivablePattern(g.pattern)) ||
-                (Array.isArray(g?.pattern) &&
-                    g.pattern.length === 0 &&
-                    typeof g?.literal === "string" &&
-                    g.literal.length > 0)));
+        if (parsed?.version !== 1 || !Array.isArray(parsed.grants)) {
+            return { ok: false, cause: "malformed" };
+        }
+        return { ok: true, grants: parsed.grants.filter(isValidGrant) };
     }
-    catch {
-        return [];
+    catch (err) {
+        const code = err instanceof Error ? err.code : undefined;
+        return { ok: false, cause: typeof code === "string" ? code : "malformed" };
     }
 }
+/** Load persisted grants. Malformed or missing file → empty (fail-soft).
+ * Delegates to loadGrantsSentinel so the row validation is shared. */
+export function loadGrants(homeOverride = null) {
+    const load = loadGrantsSentinel(homeOverride);
+    return load.ok ? load.grants : [];
+}
 /**
  * Persist a new grant: re-read the file, merge (drop exact duplicates), write.
  * The re-read is the concurrency guard — a parallel session's grant appended
@@ -1036,4 +1057,100 @@ export function appendGrant(grant, homeOverride = null) {
     }
     return merged;
 }
+/**
+ * The ask-time adopt-only grant refresh (the dead-grant re-ask fix) — the
+ * PRODUCTION seam index.ts wires into the gate's refreshGrants dep.
+ *
+ * One consultation: stat rules.json and compare against the last-seen stamp
+ * (an mtimeMs+size pair — mtimeMs alone can miss a same-tick rewrite);
+ * return the fresh grant list ONLY when the file changed, null when it
+ * hasn't. The gate merges whatever returns ADOPT-ONLY (append; its session
+ * grants are never removed) — this side only supplies the data.
+ *
+ * Failure contracts, all test-pinned:
+ *   - a PARSED-EMPTY store (version-1, empty list — a legitimate bulk
+ *     cleanup) consumes the stamp: no adoption (there is nothing to
+ *     adopt), but no re-read storm either, and no trail — it is a healthy
+ *     state, not a failure;
+ *   - a FAILED load (missing, unreadable, malformed — the fail-soft-empty
+ *     class loadGrants cannot distinguish on its own) leaves one sink line
+ *     (grants_refresh_failed) and does NOT consume the stamp: the next
+ *     consultation retries until a real parse succeeds, so a repair adopts
+ *     instead of reading as unchanged forever;
+ *   - a PERSISTENTLY ABSENT store is the normal fresh-install state: when
+ *     it was absent at boot too (null baseline), its stat throw is SILENT
+ *     — one warn per grant check all session would drown the signal for
+ *     every new user. The trail fires only when a store that EXISTED
+ *     becomes unreadable, or when the throw is something other than a
+ *     plain absence (ENOENT);
+ *   - a NULL baseline also makes the FIRST consultation adopt whatever
+ *     is on disk — recovery from a boot-time read failure without waiting
+ *     for a further file change.
+ */
+export function createGrantsRefresher(homeOverride = null) {
+    let stamp = null;
+    try {
+        const st = statSync(rulesFilePath(homeOverride));
+        stamp = { mtimeMs: st.mtimeMs, size: st.size };
+    }
+    catch {
+        stamp = null;
+    }
+    return () => {
+        try {
+            const st = statSync(rulesFilePath(homeOverride));
+            const current = { mtimeMs: st.mtimeMs, size: st.size };
+            if (stamp !== null && current.mtimeMs === stamp.mtimeMs && current.size === stamp.size) {
+                return null;
+            }
+            const load = loadGrantsSentinel(homeOverride);
+            if (load.ok) {
+                // Parsed — a real answer, including the legitimate parsed-empty
+                // store: consume the stamp. An empty grant list adopts nothing
+                // (null, not []) — the gate's adopt-only merge is a no-op on it.
+                stamp = current;
+                return load.grants.length === 0 ? null : load.grants;
+            }
+            // The failed-load class: not a parse — a missing, unreadable, or
+            // malformed store. Fail-soft (null), trail the CAUSE (the sentinel's
+            // errno/malformed code — the same fixed vocabulary the stat catch
+            // carries), and do NOT consume the stamp so the next consultation
+            // retries.
+            logEvent({
+                source: "permission-rules",
+                level: "warn",
+                event: "grants_refresh_failed",
+                fields: { error: load.cause },
+            });
+            return null;
+        }
+        catch (err) {
+            // The stat throw. ABSENCE is only newsworthy when the store previously
+            // existed (a store that vanished mid-session) or the throw is not a
+            // plain ENOENT — a store absent since boot is the fresh-install
+            // normal and stays silent. After ONE vanished-store trail the stamp
+            // is nulled: subsequent consultations take the silent fresh-install
+            // posture (no per-check storm for the rest of the session).
+            const isPlainAbsence = err instanceof Error && err.code === "ENOENT";
+            if (!isPlainAbsence || stamp !== null) {
+                logEvent({
+                    source: "permission-rules",
+                    level: "warn",
+                    event: "grants_refresh_failed",
+                    // The errno code (a fixed OS vocabulary — EACCES/EPERM/EISDIR…),
+                    // not err.constructor.name, which is "Error" for every Node fs
+                    // throw and distinguishes nothing.
+                    fields: {
+                        error: err instanceof Error && typeof err.code === "string"
+                            ? err.code
+                            : "stat_or_read_failed",
+                    },
+                });
+            }
+            if (isPlainAbsence)
+                stamp = null;
+            return null;
+        }
+    };
+}
 //# sourceMappingURL=approvedPrefixes.js.map

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

@@ -0,0 +1,45 @@
+/**
+ * Env-prefix diagnosis: the single most common SELF-INFLICTED prompt cause
+ * in operator data (14/120 out-of-sandbox dialogs in a 5-day window traced
+ * to one invented variable). An unverified env prefix
+ * (`GH_RUN_VIEW_LOG_CACHE_DISABLED=1 gh run view …`) defeats three layers
+ * at once:
+ *
+ *   1. the exec policy — the assignment is not in SAFE_ENV_VARS, so
+ *      canonicalization refuses to strip it and an otherwise-allow command
+ *      classifies prompt;
+ *   2. grants — the same canonicalization backs grant matching, so a
+ *      banked prefix never matches the decorated shape;
+ *   3. the sandbox escape rung — where classification-gated, the
+ *      non-allow verdict declines it.
+ *
+ * This module names the cause at the moment it bites: when stripping the
+ * leading env assignments flips the classification prompt→allow, the
+ * prefix IS the approval trigger — and the cure is the plain command, not
+ * a permission.
+ *
+ * PURE — no I/O, no state; mirrors the exec policy's own failure-isolated
+ * contract (a classify error reads as "no diagnosis", never a crash).
+ */
+import { type ExecPolicy } from "./execPolicy.js";
+export interface EnvPrefixDiagnosis {
+    /** The leading env var names whose presence flipped the classification. */
+    vars: string[];
+    /** The command with all leading env assignments stripped. */
+    strippedCommand: string;
+}
+/**
+ * Does an UNVERIFIED env prefix flip this command from grant-coverable to
+ * uncovered? True only when ALL hold:
+ *   - the command starts with env assignments (stripAllEnvVars changes it),
+ *   - at least one leading var is NOT in SAFE_ENV_VARS (a safe prefix strips
+ *     during grant canonicalization, so `CI=true pnpm test` still matches a
+ *     `pnpm test` grant — no diagnosis warranted),
+ *   - the stripped command classifies `allow` while the full command does
+ *     not (the classifier's never-allow decoration rule — any env prefix
+ *     floors the segment to prompt — is the flip's mechanism).
+ */
+export declare function envPrefixFlipsClassification(command: string, policy: ExecPolicy): EnvPrefixDiagnosis | null;
+/** One user/model-facing sentence for the diagnosis, or null. */
+export declare function envPrefixAdvice(d: EnvPrefixDiagnosis | null): string | null;
+//# sourceMappingURL=envPrefixDiagnosis.d.ts.map

package/dist/extension/permission/envPrefixDiagnosis.js

@@ -0,0 +1,82 @@
+/**
+ * Env-prefix diagnosis: the single most common SELF-INFLICTED prompt cause
+ * in operator data (14/120 out-of-sandbox dialogs in a 5-day window traced
+ * to one invented variable). An unverified env prefix
+ * (`GH_RUN_VIEW_LOG_CACHE_DISABLED=1 gh run view …`) defeats three layers
+ * at once:
+ *
+ *   1. the exec policy — the assignment is not in SAFE_ENV_VARS, so
+ *      canonicalization refuses to strip it and an otherwise-allow command
+ *      classifies prompt;
+ *   2. grants — the same canonicalization backs grant matching, so a
+ *      banked prefix never matches the decorated shape;
+ *   3. the sandbox escape rung — where classification-gated, the
+ *      non-allow verdict declines it.
+ *
+ * This module names the cause at the moment it bites: when stripping the
+ * leading env assignments flips the classification prompt→allow, the
+ * prefix IS the approval trigger — and the cure is the plain command, not
+ * a permission.
+ *
+ * PURE — no I/O, no state; mirrors the exec policy's own failure-isolated
+ * contract (a classify error reads as "no diagnosis", never a crash).
+ */
+import { classifyCommand } from "./execPolicy.js";
+import { SAFE_ENV_VARS, stripAllEnvVars } from "../permissionRules/shellRules.js";
+/** Leading env assignment names, in order (used for the diagnosis text). */
+function leadingEnvVarNames(command) {
+    const names = [];
+    let s = command.trim();
+    // Same assignment pattern family as stripAllEnvVars (quoted values with
+    // escapes, +=, array subscripts) — kept separate so the name extraction
+    // can drift from the strip without silent disagreement.
+    for (;;) {
+        const m = s.match(/^([A-Za-z_][A-Za-z0-9_]*(?:\[[^\]]*\])?)\+?=(?:'[^'\n\r]*'|"(?:\\.|[^"$`\\\n\r])*"|\\.|[^ \t\n\r$`;|&()<>\\'"])*[ \t]+/);
+        if (!m)
+            return names;
+        names.push(m[1]);
+        s = s.slice(m[0].length);
+    }
+}
+/**
+ * Does an UNVERIFIED env prefix flip this command from grant-coverable to
+ * uncovered? True only when ALL hold:
+ *   - the command starts with env assignments (stripAllEnvVars changes it),
+ *   - at least one leading var is NOT in SAFE_ENV_VARS (a safe prefix strips
+ *     during grant canonicalization, so `CI=true pnpm test` still matches a
+ *     `pnpm test` grant — no diagnosis warranted),
+ *   - the stripped command classifies `allow` while the full command does
+ *     not (the classifier's never-allow decoration rule — any env prefix
+ *     floors the segment to prompt — is the flip's mechanism).
+ */
+export function envPrefixFlipsClassification(command, policy) {
+    const raw = command.trim();
+    if (!raw)
+        return null;
+    const vars = leadingEnvVarNames(raw);
+    if (vars.length === 0)
+        return null;
+    if (vars.every((v) => SAFE_ENV_VARS.has(v)))
+        return null;
+    const stripped = stripAllEnvVars(raw);
+    if (stripped === raw)
+        return null;
+    try {
+        const full = classifyCommand(raw, policy).decision;
+        const bare = classifyCommand(stripped, policy).decision;
+        if (full !== "prompt" || bare !== "allow")
+            return null;
+    }
+    catch {
+        return null; // a classifier error is never a diagnosis
+    }
+    return { vars, strippedCommand: stripped };
+}
+/** One user/model-facing sentence for the diagnosis, or null. */
+export function envPrefixAdvice(d) {
+    if (!d)
+        return null;
+    return (`An unverified environment-variable prefix (${d.vars.join(", ")}) is the only reason this needs approval — ` +
+        `it defeats grants and auto-allow even when the underlying command is safe. Run the plain command instead: \`${d.strippedCommand.slice(0, 80)}${d.strippedCommand.length > 80 ? "…" : ""}\``);
+}
+//# sourceMappingURL=envPrefixDiagnosis.js.map

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

@@ -122,14 +122,6 @@ export type AllowRuleFloorOutcome = {
     kind: "hold";
 };
 export declare function allowRuleFloorVerdict(toolName: string, params: Record<string, unknown>, mode: PermissionMode, policy: PermissionPolicy): AllowRuleFloorOutcome;
-/**
- * Pure permission decision for one tool call under a mode + policy. Auto allows
- * ordinary tools; plan blocks the write/exec set; review marks writes for confirmation
- * unless a recorded decision blesses them. A dangerouslyDisableSandbox retry that
- * will run unsandboxed is flagged BEFORE any mode/exec-policy handling — the
- * consent flow owns it in every mode (Claude Code's default-mode contract:
- * passthrough → ask, never a silent LLM-approved escape).
- */
 export declare function decideGate(toolName: string, params: Record<string, unknown>, mode: PermissionMode, policy: PermissionPolicy): GateDecision;
 /**
  * Terminal outcome of one prompt-band decision (YAG-510). One storage event
@@ -243,6 +235,20 @@ export interface RegisterPermissionDeps {
     /** Persist a new grant (fire-and-forget; the in-memory list is updated
      * either way). index.ts wires approvedPrefixes.appendGrant. */
     persistGrant?: (grant: ApprovedPrefixGrant) => void;
+    /**
+     * Adopt-only grant refresh, consulted at ASK TIME (both grant sites):
+     * when the persisted store changed since session start (a sibling
+     * session banked a grant), return the fresh list — the gate merges it
+     * ADOPT-ONLY (new grants append; session grants are never removed or
+     * mutated, so a corrupted/emptied file cannot strip what the session
+     * already holds). Return null/undefined when nothing changed. Fail-soft:
+     * a throw leaves the session list untouched. The self-authoring hole a
+     * mid-session re-read could open is closed by the sandbox itself — the
+     * escape flow only runs while the OS sandbox is up, and ~/.yagni-code is
+     * in its denyWrite band, so planting a grant still requires an approved
+     * unsandboxed write (the same bar as today).
+     */
+    refreshGrants?: () => ApprovedPrefixGrant[] | null;
     /**
      * persist a user-level permission rule string (e.g.
      * `Bash(git push:*)`) into ~/.yagni-code/config.json permissions.allow.
@@ -415,6 +421,13 @@ export declare function buildModeContextMessage(mode: PermissionMode): string;
 export declare function filterStaleModeContext<T>(messages: T[], currentMode?: PermissionMode): T[];
 /** Legacy alias — the original plan-mode filter name. */
 export declare const filterStalePlanContext: typeof filterStaleModeContext;
+/**
+ * The widened-rung kill-switch (read once per gate registration — the same
+ * env-var contract as YAGNI_COMPOUND_PREFIX_GRANTS): truthy restores the
+ * classify=allow gate for auto-mode escapes, reverting the rung to its
+ * pre-widening read-only shape without a release.
+ */
+export declare function escapeClassifyGateKnob(env?: NodeJS.ProcessEnv): boolean;
 /** The decision source of ONE tool_call (telemetry), carried per invocation
  * because tool calls run concurrently: refined by the user dialog, hooks,
  * and Guardian outcomes as the call moves through the gate. */

package/dist/extension/permission/gate.js

@@ -36,6 +36,7 @@ import { isDebug } from "../diagnostics.js";
 import { buildDiagnosticEvent, checkCircuitBreaker, DEFAULT_GUARDIAN_LIMITS, } from "./guardian.js";
 import { askCustomPrefix, CUSTOM_PREFIX_CANCELLED } from "./prefixInput.js";
 import { computeCustomPrefixUnit, describeCustomPrefixFill } from "./approvedPrefixes.js";
+import { envPrefixAdvice, envPrefixFlipsClassification } from "./envPrefixDiagnosis.js";
 export function createModeHolder(initial = "auto") {
     let current = initial;
     const listeners = new Set();
@@ -108,6 +109,17 @@ function sideEffectToolsFor(policy) {
  * consent flow owns it in every mode (Claude Code's default-mode contract:
  * passthrough → ask, never a silent LLM-approved escape).
  */
+/**
+ * The prompt-band justification with the env-prefix diagnosis appended
+ * when an unverified env prefix is the ONLY reason the command needs
+ * approval. PURE — wraps the diagnosis module for decideGate's three
+ * prompt-return sites so the consult prompt and storage events all see
+ * the same sentence.
+ */
+function withEnvPrefixDiagnosis(command, execPolicy, justification) {
+    const advice = envPrefixAdvice(envPrefixFlipsClassification(command, execPolicy));
+    return advice ? `${justification}. ${advice}` : justification;
+}
 export function decideGate(toolName, params, mode, policy) {
     if (mode === "plan") {
         // Non-bash tools in planBlockTools are held outright — they are
@@ -133,8 +145,14 @@ export function decideGate(toolName, params, mode, policy) {
                     // prompt — Guardian reviews. The gate handler runs the Guardian
                     // and handles allow/ask/deny. Grants and cache are skipped in
                     // plan mode (they can cover writes). Guardian unavailable/capped/
-                    // disabled → block (fail closed).
-                    return { block: false, classify: "prompt", classifyJustification: classification.justification };
+                    // disabled → block (fail closed). The justification carries the
+                    // env-prefix diagnosis when an unverified env prefix is the sole
+                    // approval trigger (the most common self-inflicted cause).
+                    return {
+                        block: false,
+                        classify: "prompt",
+                        classifyJustification: withEnvPrefixDiagnosis(command, execPolicy, classification.justification),
+                    };
                 }
                 catch {
                     // classifyCommand threw — fail closed in plan mode.
@@ -176,7 +194,11 @@ export function decideGate(toolName, params, mode, policy) {
                 // In auto mode the handler runs the Guardian; in review mode the
                 // handler runs the Guardian first, then falls back to user confirm.
                 if (mode === "auto") {
-                    return { block: false, classify: "prompt", classifyJustification: classification.justification };
+                    return {
+                        block: false,
+                        classify: "prompt",
+                        classifyJustification: withEnvPrefixDiagnosis(command, execPolicy, classification.justification),
+                    };
                 }
                 // review mode
                 if (policy.isBlessed?.(toolName, params))
@@ -185,7 +207,7 @@ export function decideGate(toolName, params, mode, policy) {
                     block: false,
                     confirm: true,
                     classify: "prompt",
-                    classifyJustification: classification.justification,
+                    classifyJustification: withEnvPrefixDiagnosis(command, execPolicy, classification.justification),
                 };
             }
             catch {
@@ -297,6 +319,16 @@ export function filterStaleModeContext(messages, currentMode) {
 }
 /** Legacy alias — the original plan-mode filter name. */
 export const filterStalePlanContext = filterStaleModeContext;
+/**
+ * The widened-rung kill-switch (read once per gate registration — the same
+ * env-var contract as YAGNI_COMPOUND_PREFIX_GRANTS): truthy restores the
+ * classify=allow gate for auto-mode escapes, reverting the rung to its
+ * pre-widening read-only shape without a release.
+ */
+export function escapeClassifyGateKnob(env = process.env) {
+    const v = env.YAGNI_ESCAPE_CLASSIFY_GATE;
+    return v === "1" || v === "true";
+}
 const MODE_COPY = {
     auto: "auto: coding changes apply directly; external tracker changes ask first (default).",
     plan: "plan: write, edit, and bash are held so the agent can explore and propose only.",
@@ -439,6 +471,42 @@ export function registerPermissionGate(pi, deps = {}) {
     // startup load is the trust boundary (PR #1698 review).
     const compoundPrefixGrantsEnabled = process.env.YAGNI_COMPOUND_PREFIX_GRANTS !== "0";
     const grants = [...(deps.grants ?? [])];
+    // Adopt-only refresh (the dead-grant re-ask fix): consulted at each GRANT
+    // consultation — when a sibling session banked a grant after this one
+    // booted, this session adopts it for the ask it was about to open, so a
+    // remembered approval actually lands everywhere. Adopt-only: new grants
+    // append; existing session grants are never removed or mutated. Fail-soft:
+    // a throw (or null) leaves the session list untouched.
+    const grantKeyOf = (g) => `${g.repoKey}\u0000${g.pattern.join(" ")}\u0000${g.literal ?? ""}`;
+    const refreshGrantsAdoptOnly = () => {
+        try {
+            const fresh = deps.refreshGrants?.();
+            if (!fresh)
+                return;
+            const known = new Set(grants.map(grantKeyOf));
+            for (const g of fresh) {
+                if (!known.has(grantKeyOf(g))) {
+                    grants.push(g);
+                    known.add(grantKeyOf(g));
+                }
+            }
+        }
+        catch (err) {
+            // Fail-soft — but never SILENT: a persistently failing refresh would
+            // resurrect the dead-grant re-ask bug with no diagnostic trail, so a
+            // thrown refresh leaves one sink line (error class only, no command
+            // content — the same discipline as every sibling gate trace).
+            try {
+                logEvent({
+                    source: "permission-rules",
+                    level: "warn",
+                    event: "grants_refresh_failed",
+                    fields: { error: err instanceof Error ? err.constructor.name : typeof err },
+                });
+            }
+            catch { /* telemetry must never affect the gate */ }
+        }
+    };
     // Keyed by cwd: a session can change working directory (cd, /go worktrees),
     // and a repoKey memoized from the first cwd would let repo-A grants match
     // commands running in repo B (PR #1694 review).
@@ -1098,6 +1166,7 @@ export function registerPermissionGate(pi, deps = {}) {
                 // confirm-each-command). A grant can never cover forbidden commands:
                 // decideGate already returned block for those.
                 if (modeAtEntry === "auto" && command) {
+                    refreshGrantsAdoptOnly();
                     const grant = matchesGrant(command, grants, resolveRepoKeyFor(cwd));
                     if (grant || (compoundPrefixGrantsEnabled && matchesCompoundGrants(command, grants, resolveRepoKeyFor(cwd), effectivePolicy.execPolicy ?? DEFAULT_EXEC_POLICY))) {
                         if (grant) {
@@ -1611,7 +1680,9 @@ export function registerPermissionGate(pi, deps = {}) {
      * One flow for every mode; REPLACES the Guardian and the review/plan
      * confirm machinery for this call. Order: tally → forbidden check →
      * compound evaluation (grants + readonly segments) → exact-command cache →
-     * human ask (with remember/editable-prefix options) → headless fail-closed.
+     * auto-sandbox rung (mode-scoped: AUTO accepts every non-forbidden shape;
+     * plan/review still require an allow classification) → human ask (with
+     * remember/editable-prefix options) → headless fail-closed.
      */
     const gateSandboxEscape = async (event, ctx, slot, modeAtEntry) => {
         const cmdRaw = event.input?.command;
@@ -1664,6 +1735,8 @@ export function registerPermissionGate(pi, deps = {}) {
         // is plan-mode-skipped.
         const repoKey = resolveRepoKeyFor(cwd);
         const inPlanMode = modeAtEntry === "plan";
+        if (!inPlanMode)
+            refreshGrantsAdoptOnly();
         const compound = evaluateCompoundForEscape(command, grants, repoKey, execPolicy);
         if (compound.forbidden) {
             emitGateEvent(slot, { ...eventBase, outcome: "escape_forbidden_blocked", consulted: false });
@@ -1726,15 +1799,30 @@ export function registerPermissionGate(pi, deps = {}) {
             }
             catch { /* telemetry must never affect the gate */ }
         };
+        // The classification gate is MODE-SCOPED: auto mode runs the FIRST
+        // escape attempt inside the sandbox whatever its shape (the rung's
+        // strictly-less-authority argument covers write shapes too — a
+        // sandboxed run of `mv` enforces the fs scope; the "Yes, run it"
+        // button it replaces ran unsandboxed); plan and review keep the
+        // classify=allow requirement (plan's no-mutation contract and
+        // review's human-confirms-each-bash contract both outrank the rung
+        // for mutating shapes). A classifier crash keeps the dialog (fail
+        // closed) in every mode. The kill-switch knob (YAGNI_ESCAPE_CLASSIFY_GATE
+        // truthy, the YAGNI_COMPOUND_PREFIX_GRANTS sibling pattern) restores the
+        // classify=allow gate in auto mode too — a bad interaction can be
+        // disabled without a release.
+        const classifyGateApplies = modeAtEntry !== "auto" || escapeClassifyGateKnob();
         let classifyAllowForAutoSandbox = false;
-        try {
-            classifyAllowForAutoSandbox =
-                classifyCommand(command, execPolicy).decision === "allow";
-        }
-        catch {
-            classifyAllowForAutoSandbox = false; // classifier crash → dialog (fail closed)
+        if (classifyGateApplies) {
+            try {
+                classifyAllowForAutoSandbox =
+                    classifyCommand(command, execPolicy).decision === "allow";
+            }
+            catch {
+                classifyAllowForAutoSandbox = false; // classifier crash → dialog (fail closed)
+            }
         }
-        if (!classifyAllowForAutoSandbox)
+        if (!classifyAllowForAutoSandbox && classifyGateApplies)
             declineTrace("classify_not_allow");
         else if (hasSandboxedFailure(command))
             declineTrace("prior_failure");
@@ -1751,7 +1839,7 @@ export function registerPermissionGate(pi, deps = {}) {
                 emitGateEvent(slot, { ...eventBase, outcome: "escape_auto_sandboxed", consulted: false });
                 if (ctx?.hasUI) {
                     try {
-                        ctx.ui.notify("Ran this command inside the sandbox instead of unsandboxed (read-only; ask if a sandbox restriction blocks it).", "info");
+                        ctx.ui.notify("Ran this command inside the sandbox instead of unsandboxed; if a sandbox restriction blocks it, ask.", "info");
                     }
                     catch { /* notify must never block */ }
                 }
@@ -1833,6 +1921,13 @@ export function registerPermissionGate(pi, deps = {}) {
             ? `Yes, and don't ask again for \`${seeds.description}\` in this repo`
             : null;
         const customLabel = "Yes, and don't ask again for a custom prefix…";
+        // The env-prefix diagnosis (self-inflicted prompt cause): when an
+        // unverified env prefix is the ONLY reason the command needs approval,
+        // the dialog says so up front — the cure is the plain command, and the
+        // user reading "drop the prefix" decides faster than reading a
+        // decorated command they must parse for risk.
+        const envPrefixNote = envPrefixAdvice(envPrefixFlipsClassification(command, execPolicy));
+        const escapeTitle = `Run outside of the sandbox\n$ ${boundedCommand(command)}${envPrefixNote ? `\n\n${envPrefixNote}` : ""}`;
         const options = [
             ASK_YES_ESC,
             ...(rememberLabel ? [rememberLabel] : []),
@@ -1844,7 +1939,7 @@ export function registerPermissionGate(pi, deps = {}) {
         let choice;
         let selectThrew = false;
         try {
-            choice = await ctx.ui.select(`Run outside of the sandbox\n$ ${boundedCommand(command)}`, options, { ...(ctx.signal ? { signal: ctx.signal } : {}) });
+            choice = await ctx.ui.select(escapeTitle, options, { ...(ctx.signal ? { signal: ctx.signal } : {}) });
         }
         catch (err) {
             selectThrew = true;
@@ -2001,7 +2096,7 @@ export function registerPermissionGate(pi, deps = {}) {
                 // dialog-layer failure — retryErrored routes the resolution to
                 // "error" (escape_ask_failed), never dismissed/user_reject.
                 try {
-                    choice = await ctx.ui.select(`Run outside of the sandbox\n$ ${boundedCommand(command)}`, [ASK_YES_ESC, ...(rememberLabel ? [rememberLabel] : []), ASK_NO_ESC], { ...(ctx.signal ? { signal: ctx.signal } : {}) });
+                    choice = await ctx.ui.select(escapeTitle, [ASK_YES_ESC, ...(rememberLabel ? [rememberLabel] : []), ASK_NO_ESC], { ...(ctx.signal ? { signal: ctx.signal } : {}) });
                 }
                 catch (err) {
                     retryErrored = true;
@@ -2018,7 +2113,7 @@ export function registerPermissionGate(pi, deps = {}) {
             else {
                 // cancelled input → re-offer the plain dialog (same throw handling)
                 try {
-                    choice = await ctx.ui.select(`Run outside of the sandbox\n$ ${boundedCommand(command)}`, [ASK_YES_ESC, ...(rememberLabel ? [rememberLabel] : []), ASK_NO_ESC], { ...(ctx.signal ? { signal: ctx.signal } : {}) });
+                    choice = await ctx.ui.select(escapeTitle, [ASK_YES_ESC, ...(rememberLabel ? [rememberLabel] : []), ASK_NO_ESC], { ...(ctx.signal ? { signal: ctx.signal } : {}) });
                 }
                 catch (err) {
                     retryErrored = true;
@@ -2087,9 +2182,12 @@ export function registerPermissionGate(pi, deps = {}) {
         }
         emitGateEvent(slot, { ...eventBase, outcome: "escape_ask_denied", consulted: false, prefixConsult: foldStatus() });
         if (resolution === "no") {
+            // ONE diagnosis pass (the decline reason rides the same env-prefix
+            // note the dialog title showed — computed once, not per call site).
+            const denyNote = envPrefixAdvice(envPrefixFlipsClassification(command, execPolicy));
             return {
                 block: true,
-                reason: "The user declined running this command outside the sandbox. Try a sandboxed alternative — the /sandbox panel's Network tab can usually fix the restriction that caused the failure.",
+                reason: `The user declined running this command outside the sandbox. Try a sandboxed alternative — the /sandbox panel's Network tab can usually fix the restriction that caused the failure.${denyNote ? ` ${denyNote}` : ""}`,
             };
         }
         // Unreachable defensive tail: every resolution is handled above.

package/dist/extension/sandbox/session.js

@@ -108,7 +108,7 @@ export function makeBashComposition(manager, settings, cwd, onShellResolutionRet
             : "Default to running commands in the sandbox. Do NOT set dangerouslyDisableSandbox: true unless the user explicitly asks you to bypass the sandbox, or a specific command just failed with evidence of a sandbox restriction. " +
                 "Evidence of sandbox-caused failures includes: \"Operation not permitted\" errors for file/network operations, access denied to paths outside allowed directories, network connection failures to non-allowlisted hosts, unix-socket connection errors, and TLS certificate verification failures (x509: OSStatus -26276, tls: failed to verify certificate). " +
                 "Commands can fail for many reasons unrelated to the sandbox (missing files, wrong arguments, ordinary network issues) — only retry unsandboxed on that evidence. " +
-                "When you see it: retry the SAME command unchanged, adding only dangerouslyDisableSandbox: true, briefly explain what restriction likely caused the failure, and mention that the user can manage restrictions with /sandbox. This will prompt the user for permission. " +
+                "When you see it: retry the SAME command unchanged, adding only dangerouslyDisableSandbox: true, briefly explain what restriction likely caused the failure, and mention that the user can manage restrictions with /sandbox. In auto mode the retry first runs inside the sandbox again (no prompt); you are only asked for permission when the sandbox genuinely cannot run the command. " +
                 "Treat each command you execute with dangerouslyDisableSandbox: true individually. Even if you have recently run a command with this setting, you should default to running future commands within the sandbox. " +
                 "Do not suggest adding sensitive paths like ~/.bashrc, ~/.zshrc, ~/.ssh/*, or credential files to the sandbox allowlist.";
         // Heredoc caveat (verified live): macOS bash 3.2 writes heredoc temp
@@ -122,9 +122,15 @@ export function makeBashComposition(manager, settings, cwd, onShellResolutionRet
         // directory takes priority for temporary files — stated here so the two
         // guidance lines never read as mutually exclusive always-rules.
         const tmpdirNote = "For temporary files, use the $TMPDIR environment variable unless your system prompt names a scratchpad directory — the scratchpad takes priority for temporary files. TMPDIR is automatically set to the correct sandbox-writable directory in sandbox mode. Do NOT use /tmp directly - use $TMPDIR instead.";
+        // The env-prefix caveat: an unverified env prefix is the single most
+        // common self-inflicted prompt cause in operator data (14/120 dialogs in
+        // the 5-day window traced to one invented variable) — it defeats grants,
+        // 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.";
         const wrapped = {
             ...def,
-            description: `${def.description}\n\n## Command sandbox\nCommands run inside an OS sandbox: ${restrictions.join("; ")}. ${strictNote}\n${heredocNote}\n${tmpdirNote}`,
+            description: `${def.description}\n\n## Command sandbox\nCommands run inside an OS sandbox: ${restrictions.join("; ")}. ${strictNote}\n${heredocNote}\n${tmpdirNote}\n${envPrefixNote}`,
             parameters: schema,
             async execute(id, params, signal, onUpdate, ctx) {
                 const input = params;

package/dist/upgrade.js

@@ -271,7 +271,13 @@ function failureHint(method) {
         return `Try \`brew update\` and \`brew reinstall ${BREW_FORMULA}\`, or \`brew doctor\` if that fails too.`;
     }
     // Never suggest sudo: on managed machines the fix is a user-writable
-    // prefix, which the installer sets up automatically.
+    // prefix, which the installer sets up automatically. Windows has no `sh`,
+    // so it gets the PowerShell installer instead of a command that fails with
+    // "'sh' is not recognized".
+    if (process.platform === "win32") {
+        return ("If it was a permissions error, close any running yagni sessions and re-run the installer " +
+            "in PowerShell: irm https://yagni.app/install.ps1 | iex");
+    }
     return ("If it was a permissions error, the installer repairs the global prefix without sudo: " +
         "curl -fsSL https://yagni.app/install.sh | sh");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.1.4-staging.1422.1",
+  "version": "1.1.4-staging.1424.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": "708eff198d4e1268db1a212ebcd03bf9434bff88"
+  "yagniSourceSha": "bd7d06bc8fc95da1e22d6b06146cf7a0ea20ad78"
 }