@yagni-app/code-staging 1.1.1-staging.1352.1 → 1.1.1-staging.1358.1

package/README.md

@@ -23,6 +23,9 @@ correct, autonomous work than a coding agent that starts blank.
 npm install -g @yagni-app/code
 ```
 
+Requires Node.js 22.19 or newer (`node --version`); an older Node stops at
+launch with an upgrade message instead of crashing mid-session.
+
 The command it installs is `yagni`:
 
 ```bash

package/dist/bin.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * yagni — the published bin entry.
+ *
+ * Deliberately tiny: the only static imports are the dependency-free Node
+ * version gate and the (equally dependency-free) distribution record that
+ * names the installed channel. Everything else (`cli.js` and the module graph
+ * behind it) is loaded dynamically AFTER the check passes, so an old Node
+ * prints one clear message and exits instead of blowing up inside a
+ * dependency — or failing to parse one. `cli.js` stays directly runnable
+ * (`node dist/cli.js`) for the e2e lanes; its own entrypoint guard is false
+ * when this shim is argv[1], so the shim calls `runAsEntrypoint()` explicitly.
+ *
+ * Both failure paths set `process.exitCode` and return instead of calling
+ * `process.exit()`: stderr on a pipe is asynchronous on Windows, and an
+ * immediate exit can truncate the very diagnostic this shim exists to print.
+ * Letting the event loop drain flushes it.
+ *
+ * Behavioral coverage lives in `test/bin.test.ts`, which spawns this file
+ * under a faked-old `process.versions.node` and against a stub launcher that
+ * fails to load.
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * yagni — the published bin entry.
+ *
+ * Deliberately tiny: the only static imports are the dependency-free Node
+ * version gate and the (equally dependency-free) distribution record that
+ * names the installed channel. Everything else (`cli.js` and the module graph
+ * behind it) is loaded dynamically AFTER the check passes, so an old Node
+ * prints one clear message and exits instead of blowing up inside a
+ * dependency — or failing to parse one. `cli.js` stays directly runnable
+ * (`node dist/cli.js`) for the e2e lanes; its own entrypoint guard is false
+ * when this shim is argv[1], so the shim calls `runAsEntrypoint()` explicitly.
+ *
+ * Both failure paths set `process.exitCode` and return instead of calling
+ * `process.exit()`: stderr on a pipe is asynchronous on Windows, and an
+ * immediate exit can truncate the very diagnostic this shim exists to print.
+ * Letting the event loop drain flushes it.
+ *
+ * Behavioral coverage lives in `test/bin.test.ts`, which spawns this file
+ * under a faked-old `process.versions.node` and against a stub launcher that
+ * fails to load.
+ */
+import { DISTRIBUTION } from "./distribution.js";
+import { nodeCheckSkipped, nodeVersionProblem } from "./nodeVersion.js";
+function debugEnabled() {
+    const value = process.env.YAGNI_DEBUG;
+    return value !== undefined && value !== "" && value !== "0";
+}
+async function main() {
+    const problem = nodeCheckSkipped() ? null : nodeVersionProblem(process.versions.node, DISTRIBUTION);
+    if (problem !== null) {
+        process.stderr.write(`${problem}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    // A launcher that fails to LOAD (corrupt or partial install, a dependency
+    // missing from node_modules) would otherwise die as a raw unhandled
+    // rejection before the launcher's crash handlers exist — the same opaque
+    // failure this shim is here to prevent. No crash report is possible at this
+    // point (the reporter is part of what failed to load), so say what to do
+    // instead. The message carries the error class and message; YAGNI_DEBUG=1
+    // adds the full stack (resolution chain, parse location) for a support thread.
+    let launcher;
+    try {
+        launcher = await import("./cli.js");
+    }
+    catch (err) {
+        const name = err instanceof Error && err.name ? err.name : "Error";
+        const message = err instanceof Error ? err.message : String(err);
+        const lines = [
+            `${DISTRIBUTION.displayName} failed to load: ${name}: ${message}`,
+            "",
+            "The install looks incomplete or corrupt. Reinstall it:",
+            "",
+            `  npm install -g ${DISTRIBUTION.packageName}`,
+            "",
+        ];
+        if (debugEnabled()) {
+            const stack = err instanceof Error && err.stack ? err.stack : "(no stack)";
+            const cause = err instanceof Error && err.cause !== undefined ? `\ncause: ${String(err.cause)}` : "";
+            lines.push(`${stack}${cause}`, "");
+        }
+        else {
+            lines.push("(YAGNI_DEBUG=1 prints the full stack.)", "");
+        }
+        process.stderr.write(lines.join("\n"));
+        process.exitCode = 1;
+        return;
+    }
+    launcher.runAsEntrypoint();
+}
+await main();
+//# sourceMappingURL=bin.js.map

package/dist/cli.d.ts

@@ -166,5 +166,11 @@ export declare function main(argv: string[]): Promise<number>;
  * test import (argv[1] points at the test runner) does not.
  */
 export declare function isEntrypoint(argv1: string | undefined, moduleUrl: string): boolean;
+/**
+ * Run the launcher as the process entrypoint. Called by the published bin
+ * shim (`bin.js`, after the Node version gate) and by the guard below when
+ * this module is executed directly (`node dist/cli.js`, the e2e lanes).
+ */
+export declare function runAsEntrypoint(): void;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -889,9 +889,12 @@ export function isEntrypoint(argv1, moduleUrl) {
     };
     return resolve(argv1) === resolve(fileURLToPath(moduleUrl));
 }
-// Only auto-run when invoked as the CLI entry, so tests can import this module
-// (e.g. to exercise wantsHelp) without spawning the agent.
-if (isEntrypoint(process.argv[1], import.meta.url)) {
+/**
+ * Run the launcher as the process entrypoint. Called by the published bin
+ * shim (`bin.js`, after the Node version gate) and by the guard below when
+ * this module is executed directly (`node dist/cli.js`, the e2e lanes).
+ */
+export function runAsEntrypoint() {
     // Crash reporting for the LAUNCHER process only (pi runs as a child and the
     // extension covers the session side). Fire-and-forget, sanitized, bounded;
     // YAGNI_DISABLE_CRASH_REPORTS=1 turns it off. Registered before main() so a
@@ -904,4 +907,9 @@ if (isEntrypoint(process.argv[1], import.meta.url)) {
         process.exit(1);
     });
 }
+// Only auto-run when invoked as the CLI entry, so tests can import this module
+// (e.g. to exercise wantsHelp) without spawning the agent.
+if (isEntrypoint(process.argv[1], import.meta.url)) {
+    runAsEntrypoint();
+}
 //# sourceMappingURL=cli.js.map

package/dist/crashReport.d.ts

@@ -77,6 +77,13 @@ export interface SanitizedCrash {
  * payloads…) are never touched.
  */
 export declare function sanitizeCrashError(err: unknown, opts?: SanitizeCrashOptions): SanitizedCrash;
+/**
+ * OS, arch AND the Node version. The runtime is a first-class crash cause
+ * (an old Node dies inside undici on `zlib.createZstdDecompress`), and it
+ * rides the existing `platform` field so the backend and its Sentry tag need
+ * no change. Mirrored in `pi-extension-yagni/src/crashReport.ts`.
+ */
+export declare function platformLabel(): string;
 export type CrashClient = "cli" | "desktop" | "desktop-driver";
 export interface CrashReportInput {
     client: CrashClient;

package/dist/crashReport.js

@@ -177,6 +177,15 @@ export function sanitizeCrashError(err, opts = {}) {
         ...(cappedStack !== undefined ? { stack: cappedStack } : {}),
     };
 }
+/**
+ * OS, arch AND the Node version. The runtime is a first-class crash cause
+ * (an old Node dies inside undici on `zlib.createZstdDecompress`), and it
+ * rides the existing `platform` field so the backend and its Sentry tag need
+ * no change. Mirrored in `pi-extension-yagni/src/crashReport.ts`.
+ */
+export function platformLabel() {
+    return `${process.platform} ${process.arch} node ${process.version}`;
+}
 /**
  * Sanitize + POST one crash report from pre-extracted fields. Resolves on
  * every outcome — timeout, network error, non-2xx, disabled — and never
@@ -199,7 +208,7 @@ export async function sendCrashReport(input) {
         const payload = {
             client: input.client,
             clientVersion: input.clientVersion,
-            platform: `${process.platform} ${process.arch}`,
+            platform: platformLabel(),
             errorClass: sanitizeCrashText(input.errorClass, opts).slice(0, MAX_CRASH_ERROR_CLASS),
             message: sanitizeCrashText(input.message, opts).slice(0, MAX_CRASH_MESSAGE),
             ...(stack !== undefined ? { stack } : {}),

package/dist/doctor.d.ts

@@ -50,6 +50,13 @@ export type BackendProbe = {
 } | {
     kind: "network";
 };
+/**
+ * The Node floor, first in the list because every other check is moot
+ * without it: an old Node dies inside pi's HTTP client mid-request (Sentry
+ * YAGNI-BACKEND-4S: `zlib.createZstdDecompress is not a function`). The bin
+ * shim refuses to launch below the floor; doctor explains it in the same terms.
+ */
+export declare function checkNodeVersion(version: string): CheckResult;
 export declare function checkPiEngine(probe: PiEngineProbe): CheckResult;
 export declare function checkExtension(probe: ExtensionProbe): CheckResult;
 export declare function checkProfileToken(profile: Pick<Profile, "name" | "token">): CheckResult;
@@ -115,6 +122,8 @@ export declare function buildDoctorReport(checks: CheckResult[]): DoctorReport;
 export declare function formatDoctorReport(report: DoctorReport): string;
 export interface DoctorDeps {
     now?: () => number;
+    /** Running Node version (defaults to process.versions.node). */
+    nodeVersion?: string;
     probePiEngine?: () => PiEngineProbe;
     probeExtension?: () => ExtensionProbe;
     readActiveProfile?: () => Promise<Profile>;

package/dist/doctor.js

@@ -21,7 +21,27 @@ import { otelChildEnv, resolveOtelLaunchWithWorkspace } from "./otel.js";
 import { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir, resolveTelemetryProbePath } from "./paths.js";
 import { readActiveProfile } from "./profiles.js";
 import { resolveMcpConfigPath } from "./mcpCommand.js";
+import { MIN_NODE_VERSION, nodeVersionSatisfies } from "./nodeVersion.js";
 // ── Pure check builders ─────────────────────────────────────────────────────
+/**
+ * The Node floor, first in the list because every other check is moot
+ * without it: an old Node dies inside pi's HTTP client mid-request (Sentry
+ * YAGNI-BACKEND-4S: `zlib.createZstdDecompress is not a function`). The bin
+ * shim refuses to launch below the floor; doctor explains it in the same terms.
+ */
+export function checkNodeVersion(version) {
+    const shown = version.startsWith("v") ? version : `v${version}`;
+    if (!nodeVersionSatisfies(version, MIN_NODE_VERSION)) {
+        return {
+            name: "node",
+            status: "fail",
+            detail: `${shown} is older than the ${MIN_NODE_VERSION} floor`,
+            hint: "upgrade Node.js (https://nodejs.org or `nvm install 22`); older Node crashes mid-request on missing zlib APIs",
+            required: true,
+        };
+    }
+    return { name: "node", status: "ok", detail: `${shown} (needs ${MIN_NODE_VERSION}+)`, required: true };
+}
 export function checkPiEngine(probe) {
     if (!probe.binPath || !probe.binExists) {
         return {
@@ -512,6 +532,7 @@ export async function gatherChecks(deps = {}) {
     const probeBash = deps.probeBash ?? (() => bashOnWindowsDefault());
     const probeLatestVersion = deps.probeLatestVersion ?? (() => fetchLatestVersion());
     const checks = [];
+    checks.push(checkNodeVersion(deps.nodeVersion ?? process.versions.node));
     checks.push(checkPiEngine(probePiEngine()));
     checks.push(checkExtension(probeExtension()));
     // win32 only, and skipped means NOT SHOWN: on macOS/Linux there is nothing

package/dist/extension/crashReport.d.ts

@@ -72,6 +72,13 @@ export interface CrashReporterOpts {
     timeoutMs?: number;
 }
 export type CrashReporter = (error: unknown, context?: string, repoRoot?: string) => Promise<void>;
+/**
+ * OS, arch AND the Node version: the runtime is a first-class crash cause (an
+ * old Node dies inside undici on `zlib.createZstdDecompress`), and it rides
+ * the existing `platform` field so the backend and its Sentry tag need no
+ * change. Mirrored in `yagni-code-cli/src/crashReport.ts`.
+ */
+export declare function platformLabel(): string;
 /**
  * Build the fail-soft reporter. The extension runs inside pi's process, so
  * the client label follows the surface: `desktop` under the desktop shell

package/dist/extension/crashReport.js

@@ -145,6 +145,15 @@ export function sanitizeCrashError(err, opts = {}) {
         ...(cappedStack !== undefined ? { stack: cappedStack } : {}),
     };
 }
+/**
+ * OS, arch AND the Node version: the runtime is a first-class crash cause (an
+ * old Node dies inside undici on `zlib.createZstdDecompress`), and it rides
+ * the existing `platform` field so the backend and its Sentry tag need no
+ * change. Mirrored in `yagni-code-cli/src/crashReport.ts`.
+ */
+export function platformLabel() {
+    return `${process.platform} ${process.arch} node ${process.version}`;
+}
 /**
  * Build the fail-soft reporter. The extension runs inside pi's process, so
  * the client label follows the surface: `desktop` under the desktop shell
@@ -163,7 +172,7 @@ export function makeCrashReporter(opts) {
             const payload = {
                 client: isDesktopSurface() ? "desktop" : "cli",
                 clientVersion: env.YAGNI_CODE_VERSION?.trim() || "unknown",
-                platform: `${process.platform} ${process.arch}`,
+                platform: platformLabel(),
                 ...sanitized,
                 ...(context !== undefined ? { context } : {}),
                 timestamp: new Date().toISOString(),
@@ -234,7 +243,7 @@ export function reportFatalCrash(error, opts, context) {
         const payload = {
             client: isDesktopSurface() ? "desktop" : "cli",
             clientVersion: env.YAGNI_CODE_VERSION?.trim() || "unknown",
-            platform: `${process.platform} ${process.arch}`,
+            platform: platformLabel(),
             ...sanitized,
             ...(context !== undefined ? { context } : {}),
             timestamp: new Date().toISOString(),

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

@@ -51,6 +51,8 @@ export interface ApprovedPrefixFile {
     version: 1;
     grants: ApprovedPrefixGrant[];
 }
+/** Tools whose second token is a subcommand worth capturing in a prefix. */
+export declare const MULTI_SUBCOMMAND_TOOLS: Set<string>;
 /**
  * Prefixes that must never be grantable (Claude Code's BARE_SHELL_PREFIXES
  * line, plus the destruction family we keep fenced beyond it).
@@ -152,7 +154,7 @@ export declare function heredocPrefix(command: string): string | null;
  * Returns grants WITHOUT repoKey/addedAt/cwd (the gate fills them in) —
  * seeds are hypothetical until the user picks remember.
  */
-export declare function deriveRememberSeeds(command: string, uncoveredCanonicalSegments: readonly string[], repoKey?: string): {
+export declare function deriveRememberSeeds(command: string, uncoveredSegments: readonly string[], repoKey?: string): {
     seeds: ApprovedPrefixGrant[];
     description: string;
 } | null;

package/dist/extension/permission/approvedPrefixes.js

@@ -29,11 +29,11 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { classifyCommand, isSafeRedirect, shellParse, tokenize } from "./execPolicy.js";
-import { SAFE_ENV_VARS, splitSubcommands } from "../permissionRules/shellRules.js";
+import { SAFE_ENV_VARS } from "../permissionRules/shellRules.js";
 import { codeStateHome } from "../stateHome.js";
 // --- Derivation ---
 /** Tools whose second token is a subcommand worth capturing in a prefix. */
-const MULTI_SUBCOMMAND_TOOLS = new Set([
+export const MULTI_SUBCOMMAND_TOOLS = new Set([
     "git", "gh", "npm", "pnpm", "yarn", "docker", "kubectl", "fly", "cargo", "go",
 ]);
 /**
@@ -211,13 +211,35 @@ export function storagePrefix(command) {
 function hasGitPushRefspecDanger(tokens) {
     return tokens.slice(2).some((t) => t.startsWith("+") || (!t.startsWith("-") && t.includes(":")));
 }
+/** The push shapes a grant pattern covers: a two-token [git, push] grant
+ * covers only `git push …`; a single-token [git] grant (the flag-first
+ * fallback — `git -C repo push …`, or a user-typed bare `git` in the custom
+ * field) covers EVERY subcommand, push included. The push fence must fire
+ * for both shapes or the fencing invariant is defeated by the shorter
+ * pattern. Deliberate deviation from Claude Code: their Bash(git:*) also
+ * matches `git push --force`, but their allow rules never grant UNSANDBOXED
+ * execution (permission and sandbox-wrap are orthogonal — an allowed
+ * command still runs sandboxed). Our escape-flow grants are standing
+ * unsandboxed-run authorizations, so the fence is load-bearing for us. */
+function grantCoversPush(pattern, tokens) {
+    if (tokens[0] !== "git")
+        return false;
+    if (pattern.length >= 2)
+        return pattern[1] === "push";
+    // single-token [git]: covers a push when the COMMAND is one — any bare
+    // `push` word in token position (not a flag value), which also catches
+    // flag-first shapes (`git -C /x push --force-with-lease …`). Over-fencing
+    // in the safe direction: a benign `git push -c push=…`-style flag value
+    // reads as covered-but-fenced only for that command shape, not a grant.
+    return tokens.some((t) => t === "push");
+}
 /**
  * Flags that must never ride a grant even though the exec policy leaves them
  * in the prompt band (e.g. --force-with-lease is Guardian-reviewable but a
  * standing grant for it would be a silent force-push license).
  */
 function hasGrantFencedFlag(pattern, tokens) {
-    if (pattern[0] === "git" && pattern[1] === "push") {
+    if (grantCoversPush(pattern, tokens)) {
         return tokens.some((t) => t.startsWith("--force") || t === "-f");
     }
     return false;
@@ -341,7 +363,7 @@ export function matchesGrant(command, grants, repoKey) {
             continue;
         if (hasGrantFencedFlag(grant.pattern, tokens))
             continue;
-        if (grant.pattern[0] === "git" && grant.pattern[1] === "push" && hasGitPushRefspecDanger(tokens))
+        if (grantCoversPush(grant.pattern, tokens) && hasGitPushRefspecDanger(tokens))
             continue;
         return grant;
     }
@@ -412,6 +434,17 @@ export function heredocPrefix(command) {
     }
     return prefix.length > 0 ? prefix : null;
 }
+/**
+ * Self-match proof for a literal seed: does the seed, as a grant, cover the
+ * very command it was derived from? The single gate every literal rung
+ * shares — a seed that fails it would hand the user a "don't ask again"
+ * option that never works (the dead-rule bug: the multiline -Atc "\"SQL class
+ * matched nothing, ever, and re-asked every invocation). Pure.
+ */
+function literalSeedSelfMatches(command, literal) {
+    const grant = { pattern: [], literal, repoKey: "", addedAt: "", cwd: "" };
+    return matchesGrant(command, [grant], "") !== null;
+}
 /**
  * The FULL remember ladder for one ask, in order (all five rungs — a shape
  * never asks twice):
@@ -424,18 +457,27 @@ export function heredocPrefix(command) {
  * Returns grants WITHOUT repoKey/addedAt/cwd (the gate fills them in) —
  * seeds are hypothetical until the user picks remember.
  */
-export function deriveRememberSeeds(command, uncoveredCanonicalSegments, repoKey) {
-    const derivable = uncoveredCanonicalSegments
+export function deriveRememberSeeds(command, uncoveredSegments, repoKey) {
+    // Rung 1 derives and self-matches on the CANONICAL form of each raw
+    // segment (the anti-dead-rule invariant — the same normalization
+    // matchesGrant applies at match time). The raw segments arrive from
+    // evaluateCompoundForEscape's splitSubcommandsQuoted, which preserves
+    // quoting so a quoted arg body (a `;` inside `-c "…SQL…"`) reads as ONE
+    // argument; canonicalization then strips safe decorations the same way
+    // matching does, keeping the token rung reachable for exactly the plain
+    // single commands it exists for (the psql case).
+    const canonicalSegments = uncoveredSegments.map((seg) => canonicalizeForGrants(seg));
+    const derivable = canonicalSegments
         .map((seg) => derivePrefix(seg))
         .filter((p) => p !== null);
     // Rung 1: every uncovered segment token-derivable AND every seed
     // self-matches its own segment (the fencing proof: a `git push +x:y` shape
     // derives [git, push] but the fenced command never matches it, so the
     // remember option is never offered for a shape the grant can't cover).
-    if (derivable.length === uncoveredCanonicalSegments.length && derivable.length > 0) {
+    if (derivable.length === canonicalSegments.length && derivable.length > 0) {
         const key = repoKey ?? "";
         const seeds = derivable.map((pattern) => ({ pattern, repoKey: key, addedAt: "", cwd: "" }));
-        const allSelfMatch = uncoveredCanonicalSegments.every((seg, i) => matchesGrant(seg, [seeds[i]], key) !== null);
+        const allSelfMatch = canonicalSegments.every((seg, i) => matchesGrant(seg, [seeds[i]], key) !== null);
         if (allSelfMatch) {
             return {
                 seeds: derivable.map((pattern) => ({ pattern, repoKey: "", addedAt: "", cwd: "" })),
@@ -445,9 +487,13 @@ export function deriveRememberSeeds(command, uncoveredCanonicalSegments, repoKey
         // A fenced segment kills the token rung — fall through to the literal
         // rungs below (a narrower prefix may still be rememberable).
     }
-    // Rung 2: heredoc prefix.
+    // Rung 2: heredoc prefix — self-match checked (a literal seed is offered
+    // ONLY when it provably matches the very command being asked about; the
+    // heredoc rung's remainder is its heredoc tail, which the inert-remainder
+    // check admits, so this proof is structural — but it runs anyway: a
+    // shape change upstream must never resurrect a dead seed).
     const hp = heredocPrefix(command);
-    if (hp) {
+    if (hp && literalSeedSelfMatches(command, hp)) {
         return {
             seeds: [{ pattern: [], literal: hp, repoKey: "", addedAt: "", cwd: "" }],
             description: `${truncateSeedLabel(hp)} …`,
@@ -455,10 +501,15 @@ export function deriveRememberSeeds(command, uncoveredCanonicalSegments, repoKey
     }
     // Rung 3: first line of a multiline command — but NEVER an assignment-only
     // first line (`X=…\nreal cmd`): that literal is a dead rule (it matches the
-    // assignment, grants nothing about the real segment).
+    // assignment, grants nothing about the real segment). Self-match checked
+    // too: a first-line prefix whose remainder is NOT inert (the multiline
+    // `-Atc "` SQL body class) matches nothing, ever — offering it would hand
+    // the user a remember option that never works (the dead-rule bug).
     if (command.includes("\n")) {
         const firstLine = command.split("\n")[0].trim();
-        if (firstLine.length > 0 && !/^([A-Za-z_][A-Za-z0-9_]*=\S*)$/.test(firstLine)) {
+        if (firstLine.length > 0 &&
+            !/^([A-Za-z_][A-Za-z0-9_]*=\S*)$/.test(firstLine) &&
+            literalSeedSelfMatches(command, firstLine)) {
             return {
                 seeds: [{ pattern: [], literal: firstLine, repoKey: "", addedAt: "", cwd: "" }],
                 description: `${truncateSeedLabel(firstLine)} …`,
@@ -517,30 +568,89 @@ export function validateGrantForEscape(command, policy, repoKey) {
     // seed every uncovered one — the compound remember unit. A compound whose
     // uncovered segments are all token-derivable AND self-matching gets the
     // multi-grant; otherwise the literal rungs apply to the FULL command.
+    // (uncovered now carries the RAW quote-preserving segments — see
+    // evaluateCompoundForEscape — so the token rung sees quoted arg bodies
+    // as ONE plain command, not a dequoted compound.)
     const compound = evaluateCompoundForEscape(command, [], repoKey, policy);
     if (!compound.forbidden && compound.uncovered.length > 0) {
         const res = deriveRememberSeeds(command, compound.uncovered, repoKey);
         if (res && res.seeds.length > 0)
             return res;
     }
-    const canonical = canonicalizeForGrants(command);
-    const single = isSinglePlainCommand(canonical);
+    // Single-command token rung — derived and self-matched against the RAW
+    // command (the quote-preserving form; the canonical form drops quoting
+    // and makes single commands look compound — the dead-literal bug).
+    const single = isSinglePlainCommand(command);
     if (single) {
-        const pattern = derivePrefix(canonical);
+        const pattern = derivePrefix(command);
         if (pattern) {
             const candidate = { pattern, repoKey, addedAt: new Date().toISOString(), cwd: "" };
-            if (matchesGrant(canonical, [candidate], repoKey)) {
+            if (matchesGrant(command, [candidate], repoKey)) {
                 return { seeds: [candidate], description: describePrefix(pattern) };
             }
         }
     }
-    // literal rungs (heredoc/first-line/full) — validated by construction:
-    // the seed is a prefix of this very command, so it self-matches.
-    return deriveRememberSeeds(command, [canonical]);
+    // literal rungs (heredoc/first-line/full) — each rung self-match-proved
+    // by deriveRememberSeeds; a rung that cannot cover THIS command is not
+    // offered (null = no remember option at all).
+    return deriveRememberSeeds(command, [command]);
+}
+/**
+ * Quote-preserving segment splitter for the ESCAPE flow (a local, faithful
+ * counterpart to shellRules' splitSubcommands — which rejoins tokens with
+ * plain spaces and LOSES the quoting: a `;` inside `-c "…SQL…"` comes back
+ * out as a bare unquoted `;`, and every downstream pass then reads a
+ * single command as a compound — the dead-literal bug). Here, string tokens
+ * carrying shell metacharacters are re-quoted on the join so the segment
+ * string parses back to the SAME tokens; redirect-out operators keep their
+ * fd and target (2>&1, >>file) and background renders as `&`. Known lossy
+ * renderings, none grant-relevant: an input redirect renders as a bare
+ * `<` (target dropped — a construct, never a command word; the segment
+ * falls to the literal rungs, fail-closed), and tokens containing a single
+ * quote use the bash `'​''` idiom our own shellParse does not
+ * implement on re-parse — the command WORD never carries one, so the
+ * derived prefix is unaffected (fail-closed at the rung if it ever did).
+ */
+function splitSubcommandsQuoted(command) {
+    const tokens = shellParse(command);
+    const segments = [];
+    let current = [];
+    const flush = () => {
+        if (current.length > 0) {
+            segments.push(current.join(" "));
+            current = [];
+        }
+    };
+    const renderString = (t) => /[\s;|&<>'"\\$`]/.test(t) ? `'${t.replace(/'/g, `'\\''`)}'` : t;
+    const renderToken = (t) => {
+        if (typeof t === "string")
+            return renderString(t);
+        if (t.op === "redirect") {
+            if (t.direction === "out") {
+                const fd = t.fd === "stderr" ? "2" : "1";
+                return `${fd}${t.append ? ">>" : ">"}${renderString(t.target)}`;
+            }
+            return "<";
+        }
+        if (t.op === "background")
+            return "&";
+        return ""; // pipe/and/or/semi/substitution are boundaries — never rendered
+    };
+    for (const t of tokens) {
+        if (typeof t === "object" && "op" in t && (t.op === "pipe" || t.op === "and" || t.op === "or" || t.op === "semi" || t.op === "substitution")) {
+            flush();
+            continue;
+        }
+        const rendered = renderToken(t);
+        if (rendered !== "")
+            current.push(rendered);
+    }
+    flush();
+    return segments;
 }
 export function evaluateCompoundForEscape(command, grants, repoKey, policy) {
     const isHeredoc = /<<[-~]?\s*(["']?)(\w+)\1/.test(command);
-    const rawSegments = isHeredoc ? [command] : splitSubcommands(command);
+    const rawSegments = isHeredoc ? [command] : splitSubcommandsQuoted(command);
     const segments = [];
     const uncovered = [];
     let forbidden = false;
@@ -579,7 +689,16 @@ export function evaluateCompoundForEscape(command, grants, repoKey, policy) {
             continue;
         }
         segments.push({ segment: canonical, kind: "uncovered" });
-        uncovered.push(canonical);
+        // The seed ladder consumes the RAW trimmed segment, not the canonical
+        // form: canonicalizeForGrants runs the quote-aware tokenizer, and its
+        // re-join DROPS the quoting (a `;` inside `-c "…SQL…"` comes back out as
+        // a bare unquoted `;`) — derivePrefix's isSinglePlainCommand then sees a
+        // compound and kills the token rung, so flag-first single commands
+        // (psql -h … -Atc "…") fall to the dead first-line literal rung
+        // (`… -Atc "` — a rule that matches nothing, ever). The RAW segment
+        // preserves the quoting the tokenizer needs to see the command as ONE
+        // plain command and derive ["psql"].
+        uncovered.push(trimmed);
     }
     return { forbidden, uncovered, segments };
 }

package/dist/extension/permission/gate.js

@@ -26,7 +26,7 @@
  * When the mode leaves plan, stale plan-context messages are filtered out of
  * the context so the model doesn't keep believing it is restricted.
  */
-import { describePrefix, evaluateCompoundForEscape, matchesGrant, storagePrefix, validateGrant, validateGrantForEscape, } from "./approvedPrefixes.js";
+import { derivePrefix, describePrefix, evaluateCompoundForEscape, matchesGrant, storagePrefix, validateGrant, validateGrantForEscape, } from "./approvedPrefixes.js";
 import { logEvent } from "../errorSink.js";
 import { makeBlessStore as defaultMakeBlessStore } from "../bless.js";
 import { classifyCommand, DEFAULT_EXEC_POLICY } from "./execPolicy.js";
@@ -505,6 +505,28 @@ export function registerPermissionGate(pi, deps = {}) {
         // escape_ask_headless_blocked, escape_aborted, escape_ask_failed — policy,
         // infra, and abort outcomes never read as a user action in the trail.
     };
+    /** Persist a grant, fail-soft WITH a trail: the in-memory grant still
+     * applies for this session, but a silent persist failure would leave the
+     * user believing "don't ask again" survived the restart while the same
+     * dialog re-appears next session with zero trace — one warn sink line
+     * (error class only, never the thrown message: appendGrant failures can
+     * carry file paths, and the sink's content discipline is class-level)
+     * makes it observable. */
+    const persistGrantFailSoft = (grant) => {
+        try {
+            deps.persistGrant?.(grant);
+        }
+        catch (err) {
+            logEvent({
+                source: "permission-rules",
+                level: "warn",
+                event: "grant_persist_failed",
+                fields: {
+                    error: err instanceof Error ? err.constructor.name : typeof err,
+                },
+            });
+        }
+    };
     const emitGateEvent = (slot, event) => {
         const mapped = GUARDIAN_OUTCOME_SOURCE[event.outcome];
         if (mapped)
@@ -1152,12 +1174,7 @@ export function registerPermissionGate(pi, deps = {}) {
                                 addedAt: new Date().toISOString(),
                             };
                             grants.push(grantRecord);
-                            try {
-                                deps.persistGrant?.(grantRecord);
-                            }
-                            catch {
-                                // Fail-soft: the in-memory grant still applies this session.
-                            }
+                            persistGrantFailSoft(grantRecord);
                             emitGateEvent(slot, {
                                 ...eventBase,
                                 outcome: "ask_approved_remembered",
@@ -1536,15 +1553,41 @@ export function registerPermissionGate(pi, deps = {}) {
             }
             if (!inputThrew && custom !== undefined && custom.trim().length > 0) {
                 const trimmedCustom = custom.trim();
-                // The custom literal self-matches by construction (startsWith), but
-                // refuse banned/fenced shapes the same way every rung does.
-                const customGrant = { pattern: [], literal: trimmedCustom, repoKey, addedAt: new Date().toISOString(), cwd };
-                if (matchesGrant(command, [customGrant], repoKey)) {
+                // The custom field accepts two shapes:
+                //  (a) a clean command word (`npx`, `psql`) — the first-word rung of
+                //      the ladder — validated by derivePrefix's shape check and
+                //      self-matched as a TOKEN grant (covers every later `npx …` /
+                //      `psql …` regardless of arguments; Claude's `psql:*` semantics).
+                //      A bare word can never pass the literal-remainder check (the
+                //      words after it are "not inert"), which is why the field used
+                //      to reject exactly this input with a dead-rule warning. The
+                //      git-push force/refspec fence is pattern-length-aware (a
+                //      bare `git` grant covers pushes too) — see matchesGrant.
+                //  (b) anything longer — a literal string prefix, validated as
+                //      before (must cover THIS command, banned/fenced shapes
+                //      refused the same way every rung does).
+                const tokenPattern = trimmedCustom.includes(" ") || trimmedCustom.includes("\n")
+                    ? null
+                    : derivePrefix(trimmedCustom);
+                const customGrant = tokenPattern
+                    ? { pattern: tokenPattern, repoKey, addedAt: new Date().toISOString(), cwd }
+                    : { pattern: [], literal: trimmedCustom, repoKey, addedAt: new Date().toISOString(), cwd };
+                // Validation must be compound-aware: the escaped command is often a
+                // compound (`S=…; curl … && echo done`), and matchesGrant alone can
+                // never match a single token grant against a compound. A bare-word
+                // token grant is valid when EVERY segment of the compound is covered
+                // — by the token grant or an existing grant — exactly the ladder's
+                // rung-1 self-match, applied to the user's custom word.
+                const customValid = tokenPattern
+                    ? (() => {
+                        const evalPolicy = deps.policy?.execPolicy ?? DEFAULT_EXEC_POLICY;
+                        const ev = evaluateCompoundForEscape(command, [...grants, customGrant], repoKey, evalPolicy);
+                        return !ev.forbidden && ev.uncovered.length === 0;
+                    })()
+                    : matchesGrant(command, [customGrant], repoKey);
+                if (customValid) {
                     grants.push(customGrant);
-                    try {
-                        deps.persistGrant?.(customGrant);
-                    }
-                    catch { /* fail-soft */ }
+                    persistGrantFailSoft(customGrant);
                     rememberApproved(cwd, command);
                     emitGateEvent(slot, { ...eventBase, outcome: "escape_ask_approved_remembered", consulted: false });
                     return {};
@@ -1617,10 +1660,7 @@ export function registerPermissionGate(pi, deps = {}) {
                     cwd,
                 };
                 grants.push(grantRecord);
-                try {
-                    deps.persistGrant?.(grantRecord);
-                }
-                catch { /* fail-soft: in-memory grant applies this session */ }
+                persistGrantFailSoft(grantRecord);
             }
             rememberApproved(cwd, command);
             emitGateEvent(slot, { ...eventBase, outcome: "escape_ask_approved_remembered", consulted: false });

package/dist/extension/sandbox/bash.js

@@ -299,7 +299,7 @@ export function networkDenialHint(output) {
             return {
                 cls: "ipc-listen",
                 hint: "This looks like a sandbox network-posture denial (a socket bind the sandbox profile denies — test-runner IPC is the usual case). " +
-                    "The user can fix it in the /sandbox panel (Network tab: the Engineering preset or the unix-sockets toggle); retrying with dangerouslyDisableSandbox is NOT needed once the knob is on.",
+                    "The unix-sockets 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.",
             };
         }
     }
@@ -307,7 +307,7 @@ export function networkDenialHint(output) {
         return {
             cls: "tls-trustd",
             hint: "This looks like a sandbox TLS-verification denial (the trustd.agent mach lookup is denied — Go CLIs like gh verify certs through it even on allowlisted domains). " +
-                "The user can fix it in the /sandbox panel (Network tab: the Engineering preset or the trustd toggle); retrying with dangerouslyDisableSandbox is NOT needed once the knob is on.",
+                "The trustd 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.",
         };
     }
     // Loopback connect denials: EPERM/not-permitted text with a loopback
@@ -319,8 +319,8 @@ export function networkDenialHint(output) {
         /(connect|curl|psql|wget|fetch|Failed to connect|Couldn't connect)/i.test(output)) {
         return {
             cls: "loopback",
-            hint: "This looks like a sandbox loopback denial (loopback bypasses the network allowlist, so localhost services are blocked by default). " +
-                "The user can fix it in the /sandbox panel (Network tab: the Engineering preset or the local-binding toggle); retrying with dangerouslyDisableSandbox is NOT needed once the knob is on.",
+            hint: "This looks like a sandbox loopback denial (loopback bypasses the network allowlist, so localhost services need the local-binding knob). " +
+                "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.",
         };
     }
     return null;

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

@@ -18,6 +18,16 @@
  * allow-only (default-deny, /tmp included). Network: proxy-enforced
  * allowlist; loopback needs allowLocalBinding (allowedDomains cannot open it
  * — loopback bypasses the proxy via no_proxy).
+ *
+ * Engineering default (deliberate deviation from Claude Code's opt-in
+ * posture): the three network-posture knobs resolve ON when unset —
+ * allowLocalBinding (loopback bind+connect), the temp-dir unix-socket
+ * posture (macOS: ["$TMPDIR"] path-scoped; Linux: allowAllUnixSockets —
+ * path-scoped entries cannot exist there), and enableWeakerNetworkIsolation
+ * (macOS trustd for Go TLS). An induced knob-off denial makes the model
+ * retry with dangerouslyDisableSandbox, and the escaped command runs with
+ * full user authority — strictly worse than the sandboxed posture the knob
+ * would have allowed. Explicit opt-out (false / []) at any tier still wins.
  */
 import { type WorktreeGitAccess } from "./worktreeGit.js";
 import type { PermissionRule } from "../permissionRules/loadConfig.js";
@@ -68,8 +78,9 @@ export declare function readSandboxSettingsFromFile(configPath: string, warnings
 /**
  * Load + merge sandbox settings from all three config files. Scalars: local
  * beats project beats user; arrays: union. Defaults for scalars land here
- * too (Claude parity): autoAllowBashIfSandboxed true, allowUnsandboxedCommands
- * true, everything else unset/false.
+ * too: autoAllowBashIfSandboxed true, allowUnsandboxedCommands true, and the
+ * three network-posture knobs ON when unset (the Engineering default — see
+ * the file header; an explicit false/[] at any tier still wins).
  */
 export declare function loadSandboxSettings(opts?: {
     cwd?: string;

package/dist/extension/sandbox/config.js

@@ -18,6 +18,16 @@
  * allow-only (default-deny, /tmp included). Network: proxy-enforced
  * allowlist; loopback needs allowLocalBinding (allowedDomains cannot open it
  * — loopback bypasses the proxy via no_proxy).
+ *
+ * Engineering default (deliberate deviation from Claude Code's opt-in
+ * posture): the three network-posture knobs resolve ON when unset —
+ * allowLocalBinding (loopback bind+connect), the temp-dir unix-socket
+ * posture (macOS: ["$TMPDIR"] path-scoped; Linux: allowAllUnixSockets —
+ * path-scoped entries cannot exist there), and enableWeakerNetworkIsolation
+ * (macOS trustd for Go TLS). An induced knob-off denial makes the model
+ * retry with dangerouslyDisableSandbox, and the escaped command runs with
+ * full user authority — strictly worse than the sandboxed posture the knob
+ * would have allowed. Explicit opt-out (false / []) at any tier still wins.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -219,16 +229,47 @@ function union(...lists) {
         return undefined;
     return [...new Set(present.flat())];
 }
+/** The Engineering network-posture defaults — the single flip point for
+ * the default-on decision. If the escape-rate rationale proves wrong in
+ * the field, reverting the posture is editing THIS constant (and the
+ * enableWeakerNetworkIsolation fallback below), not the merge expressions.
+ * Platform-shaped: macOS path-scopes socket binds to the temp dirs;
+ * Linux cannot path-scope (seccomp), so its door is the broader allow-all. */
+function ENGINEERING_NETWORK_DEFAULTS(isDarwin) {
+    return {
+        allowUnixSockets: isDarwin ? ["$TMPDIR"] : [],
+        allowAllUnixSockets: !isDarwin,
+        allowLocalBinding: true,
+    };
+}
 function mergeNetwork(user, project, local) {
     const u = user ?? {};
     const p = project ?? {};
     const l = local ?? {};
+    // Engineering default (deliberate deviation from Claude Code's opt-in
+    // posture): when NO tier sets a posture knob, it resolves ON. Rationale —
+    // a knob-off default does not buy safety: the induced OS denial makes the
+    // model retry with dangerouslyDisableSandbox, and the escaped command runs
+    // with FULL user authority (no network allowlist, no filesystem fences) —
+    // strictly worse than a sandboxed process that can bind an IPC pipe under
+    // $TMPDIR or connect to loopback. An explicit `false` / `[]` from any tier
+    // still wins: opt-out is first-class.
+    //
+    // Platform shape of the DEFAULT socket posture (mirrors the Engineering
+    // preset): macOS path-scopes binds to the temp dirs via `allowUnixSockets:
+    // ["$TMPDIR"]` with allow-all OFF (srt's allow-all would emit a broader
+    // `path-regex ^/` rule that overrides the per-path list); Linux has no
+    // path-scoped unix sockets (seccomp cannot path-filter), so its default
+    // is the broader `allowAllUnixSockets` — the known, documented cost of the
+    // Linux default (it admits /var/run/docker.sock).
+    const isDarwin = process.platform === "darwin";
+    const defaults = ENGINEERING_NETWORK_DEFAULTS(isDarwin);
     return {
         allowedDomains: union(u.allowedDomains, p.allowedDomains, l.allowedDomains) ?? [],
         deniedDomains: union(u.deniedDomains, p.deniedDomains, l.deniedDomains) ?? [],
-        allowUnixSockets: union(u.allowUnixSockets, p.allowUnixSockets, l.allowUnixSockets),
-        allowAllUnixSockets: l.allowAllUnixSockets ?? p.allowAllUnixSockets ?? u.allowAllUnixSockets,
-        allowLocalBinding: l.allowLocalBinding ?? p.allowLocalBinding ?? u.allowLocalBinding,
+        allowUnixSockets: union(u.allowUnixSockets, p.allowUnixSockets, l.allowUnixSockets) ?? defaults.allowUnixSockets,
+        allowAllUnixSockets: l.allowAllUnixSockets ?? p.allowAllUnixSockets ?? u.allowAllUnixSockets ?? defaults.allowAllUnixSockets,
+        allowLocalBinding: l.allowLocalBinding ?? p.allowLocalBinding ?? u.allowLocalBinding ?? defaults.allowLocalBinding,
         httpProxyPort: l.httpProxyPort ?? p.httpProxyPort ?? u.httpProxyPort,
         socksProxyPort: l.socksProxyPort ?? p.socksProxyPort ?? u.socksProxyPort,
     };
@@ -247,8 +288,9 @@ function mergeFilesystem(user, project, local) {
 /**
  * Load + merge sandbox settings from all three config files. Scalars: local
  * beats project beats user; arrays: union. Defaults for scalars land here
- * too (Claude parity): autoAllowBashIfSandboxed true, allowUnsandboxedCommands
- * true, everything else unset/false.
+ * too: autoAllowBashIfSandboxed true, allowUnsandboxedCommands true, and the
+ * three network-posture knobs ON when unset (the Engineering default — see
+ * the file header; an explicit false/[] at any tier still wins).
  */
 export function loadSandboxSettings(opts = {}) {
     const warnings = [];
@@ -290,7 +332,8 @@ export function loadSandboxSettings(opts = {}) {
             userSettings?.enableWeakerNestedSandbox,
         enableWeakerNetworkIsolation: localSettings?.enableWeakerNetworkIsolation ??
             projectSettings?.enableWeakerNetworkIsolation ??
-            userSettings?.enableWeakerNetworkIsolation,
+            userSettings?.enableWeakerNetworkIsolation ??
+            true,
     };
     return { settings, diagnostics: { warnings, unknownKeys } };
 }

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

@@ -73,8 +73,11 @@ export declare function overrideOptions(current: SandboxOverrideChoice): SelectI
 /** Per-mode explanation (Claude's copy, adapted to our surfaces). */
 export declare function modeExplanation(mode: SandboxModeChoice): string;
 export declare function overrideExplanation(choice: SandboxOverrideChoice): string;
-/** The three knobs' resolved state, derived from settings (undefined =
- * unset, which resolves OFF at the runtime). */
+/** The three knobs' resolved state, derived from the settings this layer
+ * is given. NOTE: the panel is fed the MERGED settings (loadSandboxSettings
+ * output — the Engineering default resolves the three knobs ON when unset);
+ * a raw `{}` here would read all-off, which never happens in production
+ * wiring (session.ts builds the panel state from the merged load). */
 export interface NetworkKnobState {
     trustd: boolean;
     /** macOS: the $TMPDIR entry is present in allowUnixSockets; Linux:

package/dist/extension/sandbox/panel.js

@@ -101,8 +101,8 @@ export function networkOptions(knobs, platform) {
     const items = [
         {
             value: "engineering-preset",
-            label: `Engineering preset: tests + gh + localhost in one click${presetApplied(knobs, platform) ? " (applied)" : ""}`,
-            description: "Unix sockets in the temp dir (test-runner IPC), macOS TLS chain verification, and loopback connections — the routine engineering-work knobs",
+            label: `Engineering defaults: tests + gh + localhost (on by default)${presetApplied(knobs, platform) ? " (applied)" : ""}`,
+            description: "Unix sockets in the temp dir (test-runner IPC), macOS TLS chain verification, and loopback connections — ON by default for every session; applying writes the explicit form to this project's local settings",
         },
     ];
     if (isMac) {
@@ -148,12 +148,12 @@ export function networkExplanation(item, platform) {
                 : "Applies: all unix sockets (no path filtering on Linux — docker.sock included) + localhost connections. Held work (test runs, local DB clients) runs sandboxed instead of escaping.";
         case "trustd":
         case "trustd-off":
-            return "Needed for Go TLS verification (gh, gcloud, terraform). Enabling opens a potential data exfiltration vector through the trustd service — off by default.";
+            return "Needed for Go TLS verification (gh, gcloud, terraform). Enabling opens a potential data exfiltration vector through the trustd service — on by default; turn it off here if you don't use Go CLIs.";
         case "unix-sockets":
         case "unix-sockets-off":
             return platform === "darwin"
                 ? "Allows binding unix sockets under $TMPDIR only — every tsx/vitest/node test-runner IPC socket lives there. Writes to $TMPDIR are already sandbox-allowed, so this stays low-risk."
-                : "All-or-nothing on Linux: seccomp cannot filter socket paths, so allowing test-runner IPC also allows docker.sock. Off by default; excludedCommands can keep specific commands out of the sandbox instead.";
+                : "All-or-nothing on Linux: seccomp cannot filter socket paths, so allowing test-runner IPC also allows docker.sock. On by default (the Engineering default); excludedCommands can keep specific commands out of the sandbox instead.";
         case "local-binding":
         case "local-binding-off":
             return "psql/redis to localhost, dev servers on :4567, and any 127.0.0.1 client. Loopback bypasses the per-domain allowlist — this is all-or-nothing for localhost.";

package/dist/nodeVersion.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The Node.js floor gate.
+ *
+ * `engines.node` in package.json is advisory: npm prints an EBADENGINE
+ * warning on a global install and carries on, so a machine running an older
+ * Node ends up with a working `yagni` command that dies deep inside a
+ * dependency instead of failing cleanly. The first real report (Sentry
+ * YAGNI-BACKEND-4S, 2026-09-09) was pi's bundled undici 8 calling
+ * `zlib.createZstdDecompress` — added in Node 22.15 — the moment the backend
+ * answered a request with `content-encoding: zstd`. Node's own default fatal
+ * printer showed an undici stack trace, and nothing said "your Node is too
+ * old".
+ *
+ * `MIN_NODE_VERSION` mirrors `engines.node` (the manifest test pins the two
+ * together). This module is imported by `bin.ts` BEFORE anything else loads,
+ * so it must stay dependency-free and use only syntax every Node this could
+ * plausibly run under can parse.
+ */
+export declare const MIN_NODE_VERSION = "22.19.0";
+/**
+ * Escape hatch for the preflight (`YAGNI_SKIP_NODE_CHECK=1`). Same
+ * truthiness rule as the other switches: set and not "" / "0".
+ */
+export declare const NODE_CHECK_SKIP_ENV = "YAGNI_SKIP_NODE_CHECK";
+export declare function nodeCheckSkipped(env?: NodeJS.ProcessEnv): boolean;
+/** `"v22.19.0"` / `"22.19.0-nightly..."` → `[22, 19, 0]`; anything else → null. */
+export declare function parseNodeVersion(raw: string): [number, number, number] | null;
+/**
+ * Whether `actual` meets the floor. An unparseable version passes: the gate
+ * exists to stop a KNOWN-old Node with a clear message, never to lock out a
+ * runtime whose version string we merely failed to read.
+ */
+export declare function nodeVersionSatisfies(actual: string, min?: string): boolean;
+/**
+ * The names the message speaks in. The same shim ships on two channels
+ * (`@yagni-app/code` as `yagni`, `@yagni-app/code-staging` as
+ * `yagni-staging`), so the caller passes the installed distribution
+ * (`distribution.ts` owns the names; a `CodeDistribution` satisfies this
+ * shape) rather than this module keeping a copy that could drift.
+ */
+export interface NodeGateNames {
+    packageName: string;
+    commandName: string;
+    displayName: string;
+}
+/**
+ * The user-facing explanation when the floor is not met, or null when it is.
+ * Names the symptom the gate prevents so someone who already hit the crash
+ * recognizes it, and spells out the nvm gotcha (global packages live per
+ * Node version there, so the CLI needs a reinstall after switching).
+ */
+export declare function nodeVersionProblem(actual: string, names: NodeGateNames, min?: string): string | null;
+//# sourceMappingURL=nodeVersion.d.ts.map

package/dist/nodeVersion.js

@@ -0,0 +1,79 @@
+/**
+ * The Node.js floor gate.
+ *
+ * `engines.node` in package.json is advisory: npm prints an EBADENGINE
+ * warning on a global install and carries on, so a machine running an older
+ * Node ends up with a working `yagni` command that dies deep inside a
+ * dependency instead of failing cleanly. The first real report (Sentry
+ * YAGNI-BACKEND-4S, 2026-09-09) was pi's bundled undici 8 calling
+ * `zlib.createZstdDecompress` — added in Node 22.15 — the moment the backend
+ * answered a request with `content-encoding: zstd`. Node's own default fatal
+ * printer showed an undici stack trace, and nothing said "your Node is too
+ * old".
+ *
+ * `MIN_NODE_VERSION` mirrors `engines.node` (the manifest test pins the two
+ * together). This module is imported by `bin.ts` BEFORE anything else loads,
+ * so it must stay dependency-free and use only syntax every Node this could
+ * plausibly run under can parse.
+ */
+export const MIN_NODE_VERSION = "22.19.0";
+/**
+ * Escape hatch for the preflight (`YAGNI_SKIP_NODE_CHECK=1`). Same
+ * truthiness rule as the other switches: set and not "" / "0".
+ */
+export const NODE_CHECK_SKIP_ENV = "YAGNI_SKIP_NODE_CHECK";
+export function nodeCheckSkipped(env = process.env) {
+    const value = env[NODE_CHECK_SKIP_ENV];
+    return value !== undefined && value !== "" && value !== "0";
+}
+/** `"v22.19.0"` / `"22.19.0-nightly..."` → `[22, 19, 0]`; anything else → null. */
+export function parseNodeVersion(raw) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(raw.trim());
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+/**
+ * Whether `actual` meets the floor. An unparseable version passes: the gate
+ * exists to stop a KNOWN-old Node with a clear message, never to lock out a
+ * runtime whose version string we merely failed to read.
+ */
+export function nodeVersionSatisfies(actual, min = MIN_NODE_VERSION) {
+    const a = parseNodeVersion(actual);
+    const b = parseNodeVersion(min);
+    if (!a || !b)
+        return true;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return true;
+}
+/**
+ * The user-facing explanation when the floor is not met, or null when it is.
+ * Names the symptom the gate prevents so someone who already hit the crash
+ * recognizes it, and spells out the nvm gotcha (global packages live per
+ * Node version there, so the CLI needs a reinstall after switching).
+ */
+export function nodeVersionProblem(actual, names, min = MIN_NODE_VERSION) {
+    if (nodeVersionSatisfies(actual, min))
+        return null;
+    const shown = actual.startsWith("v") ? actual : `v${actual}`;
+    return [
+        `${names.displayName} needs Node.js ${min} or newer, but this is Node ${shown}.`,
+        "",
+        "Older Node is missing APIs the agent's HTTP client relies on (zstd",
+        "decompression, for one), so a session would crash mid-request with an",
+        'error like "zlib.createZstdDecompress is not a function" instead of',
+        "failing cleanly.",
+        "",
+        "Upgrade Node (https://nodejs.org, or `nvm install 22 && nvm use 22`),",
+        `then run \`${names.commandName}\` again. If your Node comes from nvm, reinstall the CLI`,
+        "afterwards so it lives under the new version:",
+        "",
+        `  npm install -g ${names.packageName}`,
+        "",
+        `(${NODE_CHECK_SKIP_ENV}=1 bypasses this check at your own risk.)`,
+    ].join("\n");
+}
+//# sourceMappingURL=nodeVersion.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.1.1-staging.1352.1",
+  "version": "1.1.1-staging.1358.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)",
@@ -25,7 +25,7 @@
     "node": ">=22.19.0"
   },
   "bin": {
-    "yagni-staging": "dist/cli.js"
+    "yagni-staging": "dist/bin.js"
   },
   "files": [
     "dist",
@@ -58,5 +58,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "1a93f050375804c9206e4660c812aebbb1ec338a"
+  "yagniSourceSha": "d3f818e827670951d1a080060578f482cbdd9fbc"
 }