@argszero/cordis-plugin-sandbox-grant-advisor 0.5.0 → 0.6.0

package/lib/index.js

@@ -2,7 +2,7 @@
  * `sandbox-grant-advisor`: turn an environment failure that has no path forward
  * into a diagnosis the model — and the user reading the transcript — can act on.
  *
- * ## The two failures it recognizes
+ * ## The three failures it recognizes
  *
  * **Workspace provisioning (Windows ACL).** Four reports of one signature
  * (`#7538`, `#7622`, `#7646`, `#7720`) describe the same shape: the host-side write grant
@@ -40,13 +40,42 @@
  * `danger-full-access` succeeds, `standard` (one-shot shell) × confining
  * succeeds.
  *
+ * **A confined child that never started (native init, `#7876` + `#7877`).** The
+ * third family is not a message at all: two reports of one exit code —
+ * `0xC0000142` `STATUS_DLL_INIT_FAILED` — describing a child that died while the
+ * loader was initializing its native images, before its entry point. In `#7876`
+ * the packaged desktop's sandbox runner never runs, because `sandbox-local`
+ * starts it as `[process.execPath, entry]` and in that build `process.execPath`
+ * is the Electron executable, which starts as an *application* unless the child
+ * carries `ELECTRON_RUN_AS_NODE=1` — so every confined command reports this code
+ * with no output at all, while the unpacked `node apps/cli/lib/bin.js web` host
+ * is unaffected. In `#7877` it is an MSYS2/Git-Bash program: under the restricted
+ * token bash cannot create its own signal pipe (`couldn't create signal pipe,
+ * Win32 error 5`), so it dies in the same phase, while `cmd.exe` and `pwsh` run
+ * fine under the identical mode. Retrying is the one thing that cannot work, and
+ * the code tells the model nothing on its own.
+ *
+ * This family is read from the **canonical value of a successful result**, which
+ * is why the seam below now inspects both outcomes. The producer never marks it
+ * an error: upstream's runner-failure rules admit only exit `127` with the
+ * `windows-acl-run: ` signature (`packages/sandbox/sandbox-local/src/index.ts`),
+ * `classifyRunnerFailure` skips every other code before it looks at stderr
+ * (`packages/sandbox/sandbox/src/diagnostics.ts`), and the renderer reports a
+ * nonzero exit as `[exit code: N]` rather than as `isError`
+ * (`packages/shell/tool-pwsh/src/render.ts`). Every version of this plugin
+ * before `0.6.0` read error results only and was structurally blind to it. See
+ * `src/signature.ts` for why the read is `ToolExecutionSuccess.value` — the
+ * tool's own canonical output, never a line of rendered text — and which three
+ * narrowings keep the recognition from firing on something else.
+ *
  * ## Where it acts, and why there
  *
  * One listener on the public `tools/post-execute` waterfall
  * (`@deepseek-ai/dsh-tools`). Admissibility was decided by which half of the
  * defect this seam can reach: the failure text (the provider propagates its
- * error unchanged, and the tool pipeline turns it into an `isError` result), an
- * agent identity to attribute it to (`exec.agent`), and a channel that speaks
+ * error unchanged, and the tool pipeline turns it into an `isError` result) or,
+ * for the native-init family, the canonical value a successful result carries,
+ * an agent identity to attribute it to (`exec.agent`), and a channel that speaks
  * to the model in the same step (`PostToolDecision`'s `additionalContexts`,
  * a durable user-role message).
  *
@@ -71,7 +100,14 @@
  *    right and are not (`takeown`, `icacls /reset`), each with its reason. For the PTY family it names the
  *    combination that fails (persistent PTY × a confining mode), states the
  *    resolved mode, says plainly that no command can fix it, and hands the
- *    user-side preset choice over. Both ride `additionalContexts`, so the model
+ *    user-side preset choice over. For the native-init family it states the
+ *    resolved mode, says the process never reached its entry point, enumerates
+ *    the two producers measured under a confining mode with the check that
+ *    separates them (what program the reader ran; whether this host is the
+ *    packaged desktop binary, which the plugin **measures and reports** rather
+ *    than assumes), and carries the one conversion a model can actually make —
+ *    rewrite the work as PowerShell or `cmd` when the program that could not
+ *    start was an MSYS2 one. All three ride `additionalContexts`, so the model
  *    sees the diagnosis beside the failure rather than only in a log it never
  *    reads.
  * 2. **A bounded fail-fast, ACL family only.** With `enforceAfter` set, a call
@@ -80,9 +116,10 @@
  *    default: the useful signal here is the diagnosis, and a plugin that blocks
  *    command execution for a reason it merely recognizes is a risk, not a
  *    feature. See the README for why the blocking half is deliberately narrow
- *    and why it does not cover the PTY family.
- * 3. **A disclosure when it withholds.** The PTY advisory is only sent when the
- *    resolved mode actually confines; if the mode is not confining, or cannot be
+ *    and why it does not cover the two mode-gated families.
+ * 3. **A disclosure when it withholds.** The PTY and native-init advisories are
+ *    only sent when the resolved mode actually confines; if the mode is not
+ *    confining, or cannot be
  *    resolved at all, the failure is left exactly as it was **and the host log
  *    says so once**. Silence alone would make "the sandbox is not the cause" and
  *    "this plugin could not tell" indistinguishable from the outside.
@@ -96,26 +133,36 @@
  *   `ToolRuntime` — against synthetic results carrying the producers' exact
  *   error shapes, with the formats taken from
  *   `packages/subprocess/win32-process/src/errors.ts` and
- *   `packages/terminal/terminal-bash/src/{index,session}.ts`.
+ *   `packages/terminal/terminal-bash/src/{index,session}.ts`. The native-init
+ *   family is exercised the same way and needs no Windows to be faithful, because
+ *   what it reads is a number in a JSON value: the test builds the shipped shell
+ *   tools' own foreground projection with the reported codes, including the
+ *   signed form the reporter saw (`-1073741502`) and the real MSYS2 stderr, so the
+ *   recognition runs against the producer's data rather than against a message
+ *   this plugin invented.
  * - **It does not repair anything.** No ACL is written, no privilege is
- *   requested, nothing is elevated, no preset is installed and no mode is
- *   changed: both remedies are the user's to apply.
+ *   requested, nothing is elevated, no environment variable is set for another
+ *   process, no preset is installed and no mode is changed: the remedies are the
+ *   user's (or, for the one in-session conversion, the model's own rewrite).
  * - **It complements, rather than replaces, `repeat-guard-escalation`.** That
  *   guard keys on *call identity* (identical arguments retried); this one keys
  *   on the *environment signature*, which is how several different commands can
  *   share one cause. They can be mounted together.
- * - **The real fix is upstream**, in both families: the ACL failure should name
+ * - **The real fix is upstream**, in all three families: the ACL failure should
+ *   name
  *   the outstanding condition at the site that knows it (`grantWrite` computes
  *   `hasExactGrant`/`hasExactDeny`/`hasExactLabel` and discards which was
- *   false), and the PTY startup path should either report "this sandbox mode is
- *   incompatible with the PTY backend" or fall back to a one-shot shell. This
- *   plugin is the stopgap.
+ *   false), the PTY startup path should either report "this sandbox mode is
+ *   incompatible with the PTY backend" or fall back to a one-shot shell, and the
+ *   sandbox runner should be launched with the environment its own execution
+ *   needs (`ELECTRON_RUN_AS_NODE` when argv[0] is an Electron binary) or with a
+ *   documented, checkable refusal for MSYS2 programs. This plugin is the stopgap.
  *
  * @module @argszero/cordis-plugin-sandbox-grant-advisor
  */
 import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm';
-import { advisoryText, ACL_DISCUSSIONS, denialText, PTY_DISCUSSIONS } from './advice.js';
-import { classifyProvisioningFailure, classifyPtyStartupFailure } from './signature.js';
+import { advisoryText, ACL_DISCUSSIONS, denialText, NATIVE_INIT_DISCUSSIONS, PTY_DISCUSSIONS } from './advice.js';
+import { classifyNativeInitDeath, classifyProvisioningFailure, classifyPtyStartupFailure } from './signature.js';
 import { confines, resolveSandboxMode } from './mode.js';
 import { advisedOf, callKey, observe, observeSuccess, recordAdvice, recordDenial, recordWithheld, shouldDeny, } from './state.js';
 export const name = 'sandbox-grant-advisor';
@@ -139,8 +186,9 @@ export const DEFAULT_MAX_DENIALS = 2;
  * The family the optional blocking half applies to.
  *
  * The ACL remedy is a command the user can run while the session continues; the
- * PTY remedy is a preset swap between sessions. Refusing calls is only useful
- * in the first case — see `denialText` in `src/advice.ts`.
+ * PTY remedy is a preset swap between sessions and the native-init remedy is a
+ * user-side launch fix (or a rewrite the model makes itself), so refusing calls
+ * is only useful in the first case — see `denialText` in `src/advice.ts`.
  */
 export const ENFORCED_FAMILY = 'acl-provisioning';
 /** Compile one `*`-wildcard pattern to an anchored RegExp; all else is literal. */
@@ -200,6 +248,22 @@ function ptyHostLine(mode) {
         + `"${mode}" — a PTY backend cannot start under a confining mode, and retrying cannot help; advisory `
         + `delivered to the model (discussion ${PTY_DISCUSSIONS})`;
 }
+/**
+ * The one-line host-side account of a recognized native-init death.
+ *
+ * It names the two things a maintainer needs to place the report — the code and
+ * the mode the call ran under — and deliberately not a cause: the code alone
+ * cannot say which producer it was, and a log line that guesses is the same
+ * defect as an advisory that guesses.
+ * @param failure - the recognized failure.
+ * @param mode - the resolved sandbox mode the failing call ran under.
+ * @returns a single log line.
+ */
+function nativeInitHostLine(failure, mode) {
+    return `sandbox-grant-advisor: sandboxed command reported exit ${String(failure.rawExitCode)} `
+        + `(0x${failure.exitCode.toString(16).toUpperCase()} STATUS_DLL_INIT_FAILED) under sandbox mode "${mode}" — the child died before `
+        + `its entry point, so retrying cannot help; advisory delivered to the model (discussions ${NATIVE_INIT_DISCUSSIONS})`;
+}
 /**
  * Wrap one notice as a user-role message.
  *
@@ -232,9 +296,14 @@ function prepend(ours, theirs) {
 }
 /** The one-line transcript summary for a recognized failure. */
 function summaryOf(failure, mode) {
-    return failure.family === 'pty-startup'
-        ? `persistent shell exited during startup under sandbox mode "${String(mode)}"`
-        : `workspace ACL provisioning failed (Win32 ${String(failure.win32Code)})`;
+    if (failure.family === 'pty-startup') {
+        return `persistent shell exited during startup under sandbox mode "${String(mode)}"`;
+    }
+    if (failure.family === 'native-init') {
+        return `sandboxed command never started (exit ${String(failure.rawExitCode)}, STATUS_DLL_INIT_FAILED) `
+            + `under sandbox mode "${String(mode)}"`;
+    }
+    return `workspace ACL provisioning failed (Win32 ${String(failure.win32Code)})`;
 }
 /**
  * Install the advisor.
@@ -270,18 +339,24 @@ export function apply(ctx, config = {}) {
      * Withholding is a decision, not an absence: the transcript shows a bare error
      * either way, so the difference between "this is not the sandbox's doing" and
      * "this plugin could not tell" has to be recorded where a maintainer reads it.
-     * Once per agent, because a loop can produce dozens of these.
+     * Once per agent, because a loop can produce dozens of these. The cited thread
+     * is the *family's* — a withheld native-init death and a withheld PTY startup
+     * failure are different reports, and pointing a maintainer at the wrong one
+     * would be its own small misdiagnosis.
      * @param agent - the agent whose failure was withheld.
      * @param state - the agent's state, to keep the note to one.
      * @param why - what stopped the advisory.
+     * @param failure - the recognized failure that was withheld; only the two
+     *   mode-gated families reach this function, so the thread it cites is exact.
      * @returns undefined, so callers can `return withhold(...)`.
      */
-    function withhold(agent, state, why) {
+    function withhold(agent, state, why, failure) {
         if (state?.withheld === true)
             return undefined;
         states.set(agent, recordWithheld(state));
-        ctx.logger.warn(`sandbox-grant-advisor: persistent-shell startup failure recognized but no advisory sent — ${why}; the raw `
-            + `error is left exactly as it is, so this is NOT a claim that the sandbox is unrelated (discussion ${PTY_DISCUSSIONS})`);
+        const discussions = failure.family === 'pty-startup' ? PTY_DISCUSSIONS : NATIVE_INIT_DISCUSSIONS;
+        ctx.logger.warn(`sandbox-grant-advisor: ${failure.family} failure recognized but no advisory sent — ${why}; the raw `
+            + `error is left exactly as it is, so this is NOT a claim that the sandbox is unrelated (discussions ${discussions})`);
         return undefined;
     }
     /**
@@ -302,11 +377,20 @@ export function apply(ctx, config = {}) {
         const key = callKey(exec.name, exec.arguments);
         const previous = states.get(agent);
         if (result.isError !== true) {
-            if (previous !== undefined)
-                states.set(agent, observeSuccess(previous, key));
-            return undefined;
+            // A result the pipeline calls a success is not automatically a working
+            // environment: the native-init death arrives exactly here, as the
+            // canonical value of a command that "finished" with a loader status. It is
+            // read from `result.value` and never from the rendered text, so a command
+            // whose own output mentions the code cannot be mistaken for it.
+            const death = classifyNativeInitDeath(result.value);
+            if (death === undefined) {
+                if (previous !== undefined)
+                    states.set(agent, observeSuccess(previous, key));
+                return undefined;
+            }
+            return adviseGated(agent, previous, death, key, exec.name);
         }
-        // The two families read different fields, on purpose. The ACL signature
+        // The two text families read different fields, on purpose. The ACL signature
         // carries an API name plus a Win32 code, which a command's own output does
         // not fabricate, so that family may read the merged text (`error.message`
         // with the rendered content as its fallback). The persistent-shell
@@ -328,28 +412,47 @@ export function apply(ctx, config = {}) {
             ?? classifyPtyStartupFailure(result.error.message);
         if (failure === undefined)
             return undefined;
-        // The PTY diagnosis IS the sandbox mode, so it is resolved before anything
-        // is recorded: an unconfined mode is not this family's story, and a mode
-        // that cannot be resolved is not something to guess at. Either way the
-        // failure is left untouched and the host log accounts for the silence.
-        if (failure.family === 'pty-startup') {
-            const resolution = resolveSandboxMode(ctx, agent);
-            if (!resolution.ok)
-                return withhold(agent, previous, resolution.withheld);
-            const mode = resolution.mode;
-            if (!confines(mode)) {
-                return withhold(agent, previous, `the failing call ran under \`${mode}\`, where the shell is not spawned through the sandbox`);
-            }
-            if (!claimAdvice(agent, previous, failure, key))
-                return undefined;
-            ctx.logger.warn(ptyHostLine(mode));
-            return notice(advisoryText(failure, advisoryContext(exec.name, mode)), summaryOf(failure, mode));
-        }
+        if (failure.family === 'pty-startup')
+            return adviseGated(agent, previous, failure, key, exec.name);
         if (!claimAdvice(agent, previous, failure, key))
             return undefined;
         ctx.logger.warn(aclHostLine(failure));
         return notice(advisoryText(failure, advisoryContext(exec.name)), summaryOf(failure));
     }
+    /**
+     * Diagnose one recognized failure of a **mode-gated** family.
+     *
+     * Both families the plugin gates on the sandbox mode — the persistent shell
+     * and the native-init death — need the same three decisions before anything is
+     * said, and they need them in the same order, so they share one implementation
+     * rather than one each: the effective mode is resolved from the agent's own
+     * session, a mode that does not confine withholds the advisory (the harness
+     * does not spawn commands through the sandbox there, so this is not these
+     * families' story), and a mode that cannot be resolved withholds it too rather
+     * than falling back to a guess. In both withholding cases the failure is left
+     * untouched and the host log accounts for the silence once.
+     * @param agent - the agent whose call failed.
+     * @param previous - the agent's state before this call, if any.
+     * @param failure - the recognized failure, already known to be a gated family.
+     * @param key - the identity of the failing call.
+     * @param tool - the failing tool's name, for the advisory context.
+     * @returns the notice to attach, or undefined.
+     */
+    function adviseGated(agent, previous, failure, key, tool) {
+        const resolution = resolveSandboxMode(ctx, agent);
+        if (!resolution.ok)
+            return withhold(agent, previous, resolution.withheld, failure);
+        const mode = resolution.mode;
+        if (!confines(mode)) {
+            const what = failure.family === 'pty-startup' ? 'the shell' : 'the command';
+            return withhold(agent, previous, `the failing call ran under \`${mode}\`, where ${what} is not spawned `
+                + 'through the sandbox', failure);
+        }
+        if (!claimAdvice(agent, previous, failure, key))
+            return undefined;
+        ctx.logger.warn(failure.family === 'pty-startup' ? ptyHostLine(mode) : nativeInitHostLine(failure, mode));
+        return notice(advisoryText(failure, advisoryContext(tool, mode)), summaryOf(failure, mode));
+    }
     /**
      * Record one recognized failure and claim the once-per-agent advisory for its
      * family.

package/lib/signature.js

@@ -1,5 +1,5 @@
 /**
- * Recognize the two environment failures this plugin explains, and refuse
+ * Recognize the three environment failures this plugin explains, and refuse
  * everything else.
  *
  * ## The ACL provisioning failure (`acl-provisioning`)
@@ -82,10 +82,87 @@
  * different cause space (a slow or blocked shell) with a different remedy, and
  * a classifier that names a wrong cause is worse than one that stays silent.
  *
+ * ## The process that never started (`native-init`)
+ *
+ * The third family is not a message at all: it is a **structured exit code on a
+ * result the pipeline calls a success**. Two reports of one code —
+ * `STATUS_DLL_INIT_FAILED`, `0xC0000142`, seen as `-1073741502` in a tool result
+ * because Windows exit codes are 32-bit NTSTATUS values and Node reports them
+ * signed — describe a confined child that died while its native images were
+ * initializing, i.e. before its entry point. `#7876` is the packaged desktop app:
+ * `sandbox-local` starts the sandbox runner as `[process.execPath, entry]`, and
+ * in that build `process.execPath` is the Electron executable, which starts as an
+ * *app* unless `ELECTRON_RUN_AS_NODE=1` is in the child's environment — so the
+ * runner itself never runs and every confined command reports this code with no
+ * output at all. `#7877` is an MSYS2/Git-Bash program under the restricted
+ * token: bash cannot create its own signal pipe (`couldn't create signal pipe,
+ * Win32 error 5`) and aborts in the same place, while `cmd.exe` and `pwsh` run
+ * fine under the identical mode.
+ *
+ * **This family is the only one that is invisible from the error path**, and that
+ * is the whole reason it is classified from the canonical value instead of from
+ * text. Upstream's runner-failure rules admit exactly one code —
+ * `RUNNER_FAILURE_RULES['windows-acl'] = [{ allowedExitCodes: [127], fatalSignatures:
+ * ['windows-acl-run: '] }]` (`packages/sandbox/sandbox-local/src/index.ts`) — and
+ * `classifyRunnerFailure` skips any other code before it even looks at stderr
+ * (`packages/sandbox/sandbox/src/diagnostics.ts`), so `0xC0000142` is never a
+ * runner failure and `SandboxUnavailableError` is never thrown. The renderer then
+ * reports it the way it reports any finished command — *"Non-zero exits are
+ * reported, not errored … only infrastructure failures (spawn errors, aborts)
+ * surface as isError results"* (`packages/shell/tool-pwsh/src/render.ts`) — as
+ * `[exit code: …]`. A plugin reading only `isError` results (every version of
+ * this one before `0.6.0`) is structurally blind to it, which is exactly why the
+ * model retries a command that can never start.
+ *
+ * The read is `ToolExecutionSuccess.value` — the tool's own canonical output,
+ * documented as *"Execution-local canonical value; deliberately omitted from
+ * durable events"* (`packages/core/tools/src/index.ts`) — so the code arrives
+ * structurally and no line of rendered text can be mistaken for it. Reading it
+ * this way is what makes the recognition safe: a command that prints a line
+ * saying `0xC0000142` is not this failure, and a call whose arguments merely
+ * mention a Windows path is not either.
+ *
+ * Three narrowings, each of which is a thing that could otherwise make the
+ * diagnosis wrong:
+ *
+ * - **The `foreground` discriminator is required.** The shipped shell tools
+ *   project a finished foreground run as `{ kind: 'foreground', exitCode, … }`
+ *   and a still-running background handle as a different shape (`tool-pwsh` /
+ *   `tool-bash`, mirrored by design), so requiring it keeps a value some other
+ *   tool happens to build with an `exitCode` field out of this family. A value
+ *   without it is left alone — the fail-closed direction, since the cost of
+ *   silence is one missing diagnosis and the cost of a wrong match is a confident
+ *   wrong cause.
+ * - **Only `STATUS_DLL_INIT_FAILED` is classified.** `0xC0000142` has producers
+ *   this module does not know about (a program that simply cannot load its own
+ *   DLLs, and the console-hiding that the sandbox backend's own source records as
+ *   producing it), so the advisory enumerates the measured ones and says so
+ *   rather than asserting one. The neighbouring statuses are deliberately **not**
+ *   folded in: `0xC0000409` is the Cygwin/MSYS2 runtime's deliberate fast-fail
+ *   (a different mechanism with a different story), and `0xC0000135` is a missing
+ *   DLL (a packaging problem, not a sandbox one).
+ * - **No platform gate.** The code is a Windows NTSTATUS: a POSIX process cannot
+ *   exit with a value above 255, so the number itself is the platform evidence. A
+ *   `process.platform === 'win32'` check would add nothing a session could
+ *   observe and would make this family untestable on the host this plugin is
+ *   built on — which is how a family ships without ever having been run.
+ *
  * @module
  */
 /** The exact text `dsh-terminal-bash` throws when the shell exits during startup. */
 export const PTY_STARTUP_EXIT = 'PTY shell exited during startup';
+/**
+ * `STATUS_DLL_INIT_FAILED`, the code a Windows process is terminated with when
+ * the loader fails while initializing it — before its entry point runs.
+ *
+ * Written unsigned here, which is how the NTSTATUS is named; a tool result
+ * usually carries it as the 32-bit signed number (`-1073741502`), and
+ * {@link classifyNativeInitDeath} accepts either because it compares the
+ * normalized 32-bit pattern.
+ */
+export const STATUS_DLL_INIT_FAILED = 0xC0000142;
+/** The `kind` discriminator the shipped shell tools put on a finished foreground run. */
+const FOREGROUND = 'foreground';
 /**
  * The producer's format is fixed by `Win32Error`
  * (`packages/subprocess/win32-process/src/errors.ts`):
@@ -149,6 +226,43 @@ export function classifyPtyStartupFailure(message) {
     }
     return undefined;
 }
+/**
+ * Classify one **successful** execution's canonical value as a Windows native-init
+ * death.
+ *
+ * This is the only family read from a result the pipeline calls a success, and
+ * that is a fact about the producer rather than a choice: the code reaches the
+ * tool result as an ordinary nonzero exit status (upstream's runner-failure rules
+ * admit only exit `127` with the `windows-acl-run: ` signature, so this one is
+ * never reclassified), and the renderer reports nonzero exits without erroring.
+ * `ToolExecutionFailure` carries no value at all, so there is nothing to read on
+ * the error path — a session sees this failure exactly when its shell tool
+ * reports a command that "ran".
+ *
+ * Recognized structurally, never from text: the value must be the foreground
+ * shell projection (`kind: 'foreground'`) with an integer `exitCode` whose 32-bit
+ * pattern is {@link STATUS_DLL_INIT_FAILED}. A command's own output claiming the
+ * code cannot reach this function, and neither can a value some other tool built
+ * with an `exitCode` field.
+ * @param value - the settled execution's canonical value (`ToolExecutionSuccess.value`).
+ * @returns the recognized failure, or undefined when this is not one.
+ */
+export function classifyNativeInitDeath(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const probe = value;
+    if (probe.kind !== FOREGROUND)
+        return undefined;
+    const raw = probe.exitCode;
+    if (typeof raw !== 'number' || !Number.isInteger(raw))
+        return undefined;
+    // `>>> 0` maps the signed form Node reports on Windows onto the unsigned
+    // NTSTATUS, and leaves a value that is already unsigned alone.
+    const exitCode = raw >>> 0;
+    if (exitCode !== STATUS_DLL_INIT_FAILED)
+        return undefined;
+    return { family: 'native-init', rawExitCode: raw, exitCode };
+}
 /**
  * The one-line failure the producer wrote, for quoting back verbatim.
  * @param failure - a recognized failure.
@@ -157,6 +271,8 @@ export function classifyPtyStartupFailure(message) {
 export function failureLine(failure) {
     if (failure.family === 'pty-startup')
         return failure.line;
+    if (failure.family === 'native-init')
+        return `[exit code: ${String(failure.rawExitCode)}]`;
     const suffix = failure.detail.length === 0 ? '' : `: ${failure.detail}`;
     return `${failure.api} failed (Win32 ${failure.win32Code})${suffix}`;
 }

package/lib/state.js

@@ -8,10 +8,11 @@
  *
  * ## One record per family
  *
- * This plugin now recognizes two unrelated environment failures — a workspace
- * that cannot be provisioned (`acl-provisioning`) and a persistent shell that
- * cannot start (`pty-startup`). They are different diagnoses with different
- * remedies, so their bookkeeping is kept apart under one agent
+ * This plugin recognizes three unrelated environment failures — a workspace
+ * that cannot be provisioned (`acl-provisioning`), a persistent shell that
+ * cannot start (`pty-startup`), and a confined Windows child that died during
+ * native initialization (`native-init`). They are different diagnoses with
+ * different remedies, so their bookkeeping is kept apart under one agent
  * ({@link AgentState.families}): an agent that hits both is told about both,
  * and an agent that has already been told about one is still told about the
  * other. Sharing one "already advised" flag would silently swallow the second

package/lib/types/advice.d.ts

@@ -3,8 +3,9 @@
  * environment failure, and what is deliberately withheld.
  *
  * The text is assembled here as pure functions so every sentence can be pinned
- * by a test, one family at a time. The two families are shaped by the same two
- * questions, and they answer them differently:
+ * by a test, one family at a time. The three families are shaped by the same
+ * question — is this the sandbox's doing, and what can the reader do about it —
+ * and they answer it differently:
  *
  * - **The ACL failure** (`acl-provisioning`) *is* fixable by the caller, so its
  *   advice names the right the caller is missing and gives the command.
@@ -45,6 +46,19 @@
  *   Handing the model a command here would be advice to run something that
  *   cannot run, and naming a one-shot shell tool would be advice to call a tool
  *   the failing composition does not mount.
+ * - **The native-init death** (`native-init`) is the one whose remedy is **split**:
+ *   the *class* is not the model's to fix, but one of its two measured producers
+ *   is. A confined child that died with `STATUS_DLL_INIT_FAILED` never ran
+ *   anything, so retrying the same call is pure waste — but if the program that
+ *   could not start was an MSYS2/Git-Bash one, the same work expressed with
+ *   PowerShell or `cmd` runs fine under the identical mode, and the model *can*
+ *   make that change because the model is the one that wrote the command. So the
+ *   advice carries a stop instruction, the one in-session conversion, and the
+ *   user-side remedy for the other producer. What it deliberately does **not** do
+ *   is guess which producer this is: the code alone cannot say, and the two
+ *   checks it hands over are facts the reader holds (what program they ran;
+ *   whether this is the packaged desktop app, which the plugin reports rather
+ *   than assumes).
  *
  * Both give a **discriminator, not just a remedy**: applying a fix without
  * confirming the cause teaches nothing when the fix does not work. For the ACL
@@ -52,7 +66,11 @@
  * SID and grants `(F)` — which separates "Modify-only directory" from "the
  * documented prerequisite is wrong", the open question upstream. For the PTY
  * family it is the **effective sandbox mode**, which is why that advisory is
- * only ever built with the mode the call actually ran under.
+ * only ever built with the mode the call actually ran under. For the native-init
+ * family it is two checks the reader performs — which program could not start,
+ * and whether this host is the packaged desktop app — because the code alone
+ * cannot separate the producers and a guess would send half its readers to the
+ * wrong remedy.
  *
  * @module
  */
@@ -62,6 +80,8 @@ import type { SandboxModeName } from './mode.js';
 export declare const ACL_DISCUSSIONS = "#7538 / #7622 / #7646 / #7720 / #7750 / #7735 / #7771 / #7804 / #7816";
 /** The upstream thread the persistent-shell advisory is a stopgap for. */
 export declare const PTY_DISCUSSIONS = "#7638";
+/** The upstream threads the native-init-death advisory is a stopgap for. */
+export declare const NATIVE_INIT_DISCUSSIONS = "#7876 / #7877";
 /** The documented prerequisite, quoted from the backend's README. */
 export declare const PREREQUISITE = "granted directories must be caller-owned and grant `WRITE_OWNER`";
 /**
@@ -103,35 +123,47 @@ export interface AdvisoryContext {
     readonly tool?: string;
     /**
      * The sandbox mode the failing call ran under. Required by the
-     * `pty-startup` family — the whole diagnosis is the mode — and unused by the
-     * ACL family.
+     * `pty-startup` family — the whole diagnosis is the mode — and by the
+     * `native-init` family, whose gate is the same question; unused by the ACL
+     * family.
      */
     readonly mode?: SandboxModeName;
+    /**
+     * Whether this process is an Electron binary (`process.versions.electron`).
+     * Used by the `native-init` family to report — not to assume — which of its
+     * producers this host can have; absent means "ask the live process", so a
+     * caller cannot accidentally state a fact it did not measure.
+     */
+    readonly electronHost?: boolean;
 }
 /**
  * Build the advisory attached to the failing tool result.
  *
  * The family decides everything: one function so a caller does not have to
  * remember which family needs which fact, and so the mode requirement of the
- * PTY family is enforced by construction rather than by convention.
+ * two gated families is enforced by construction rather than by convention.
  * @param failure - the recognized failure.
  * @param context - what the caller knows about the failing call.
  * @returns the user-role notice text, with any remedy ready to paste.
- * @throws when a PTY failure is advised without its resolved sandbox mode.
+ * @throws when a mode-gated failure is advised without its resolved sandbox mode.
  */
 export declare function advisoryText(failure: RecognizedFailure, context?: AdvisoryContext): string;
 /**
  * Build the pre-dispatch denial for the optional fail-fast half.
  *
  * The blocking half is deliberately **ACL-only**, and this function's parameter
- * type is where that is enforced. The PTY family gets an advisory and nothing
- * else, for a reason that is about the remedy rather than about the failure:
+ * type is where that is enforced. The two mode-gated families get an advisory
+ * and nothing else, for a reason that is about the remedy rather than about the
+ * failure:
  * the ACL remedy is a command the user can run *while the session continues*,
  * so refusing further identical calls cannot make the session unfinishable —
  * spending the budget always lets the call through, and a repaired environment
  * is discovered by exactly that. The PTY remedy is a preset swap, which happens
- * between sessions; refusing calls could only pad a session that is already
- * unable to do the thing being refused.
+ * between sessions, and the native-init remedy is a launch fix on the user's
+ * side (the one in-session part — rewriting an MSYS2 command — the model does by
+ * calling a different tool invocation, which has a different call key and is
+ * therefore never the call being refused); refusing calls could only pad a
+ * session that is already unable to do the thing being refused.
  * @param failure - the recognized failure.
  * @param observed - how many provisioning failures this agent has produced.
  * @param denial - this denial's 1-based ordinal.