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

package/lib/advice.js

@@ -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.
@@ -20,6 +21,24 @@
  *   separates "this is the label failure" from "this is something else", and
  *   because rolling back is the reach it invites while making the very problem
  *   it closed come back.
+ *
+ *   **The remedy is forked on ownership, because one command cannot serve both
+ *   environments.** The reports split into two rights situations behind an
+ *   identical error: a workspace **the caller owns** (`#7622`, `#7646`, `#7720`,
+ *   `#7750`, `#7804`), where the owner's implicit `WRITE_DAC` satisfies the DACL
+ *   half and `(WO)` is the whole of what is missing — so the `icacls /grant`
+ *   that supplies it *can itself run*, unelevated; and a directory **the caller
+ *   does not own** (`#7771`: owner `BUILTIN\Administrators`, held deny-only for
+ *   their token), where `WRITE_DAC` is missing too, so `icacls /grant` is denied
+ *   for the very command that would fix it, and `(WO)` alone would not be enough
+ *   even if it went through. The classifier cannot tell these apart — the text is
+ *   identical — so the advisory does what it can do instead of guessing: it hands
+ *   over the **ownership check** (`(Get-Acl "<dir>").Owner`) as the branch
+ *   selector, then gives each branch the command that actually works there, and
+ *   says why the other branch's command is not a fallback. A single unconditional
+ *   one-liner would send the second environment to a command that is refused
+ *   before it runs — the same defect this module exists to answer, a remedy that
+ *   does not work delivered confidently.
  * - **The persistent-shell failure** (`pty-startup`) is *not* fixable by the
  *   caller — least of all by the model, which has no shell to run anything in.
  *   So its advice says so and stops: the remedy is a user-side preset choice,
@@ -27,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
@@ -34,15 +66,21 @@
  * 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
  */
-import { failureLine } from './signature.js';
+import { failureLine, STATUS_DLL_INIT_FAILED } from './signature.js';
 /** The upstream threads the ACL advisory is a stopgap for. */
-export const ACL_DISCUSSIONS = '#7538 / #7622 / #7646 / #7720 / #7750 / #7735';
+export const ACL_DISCUSSIONS = '#7538 / #7622 / #7646 / #7720 / #7750 / #7735 / #7771 / #7804 / #7816';
 /** The upstream thread the persistent-shell advisory is a stopgap for. */
 export const PTY_DISCUSSIONS = '#7638';
+/** The upstream threads the native-init-death advisory is a stopgap for. */
+export const NATIVE_INIT_DISCUSSIONS = '#7876 / #7877';
 /** The documented prerequisite, quoted from the backend's README. */
 export const PREREQUISITE = 'granted directories must be caller-owned and grant `WRITE_OWNER`';
 /**
@@ -81,6 +119,19 @@ export const NOT_FIXES = [
 ];
 /** Placeholder the user replaces with the directory the error named. */
 const PLACEHOLDER = '<the directory from the error line above>';
+/**
+ * Whether this process is running on an Electron binary.
+ *
+ * In the packaged desktop the harness host *is* Electron, started with
+ * `ELECTRON_RUN_AS_NODE=1` so it behaves as Node — which is why the variable is
+ * defined here and why its presence is the discriminator the `#7876` producer
+ * turns on: `sandbox-local` launches the sandbox runner as `process.execPath`,
+ * and in that build the exec path is the Electron executable.
+ * @returns true when `process.versions.electron` is set.
+ */
+function electronHost() {
+    return process.versions.electron !== undefined;
+}
 /**
  * The diagnosis paragraph for one class of failure.
  * @param failure - the recognized failure.
@@ -111,7 +162,7 @@ function diagnosis(failure) {
             return [
                 'Why it is refused: this is the same merged write, but the Win32 code is not ERROR_ACCESS_DENIED (5), so',
                 'the missing-rights story above does not apply verbatim — a missing path, a non-directory target, or a',
-                'filesystem that does not carry ACLs are all possibilities. The one-line fix below is safe to try; if the',
+                'filesystem that does not carry ACLs are all possibilities. The commands below are safe to try; if the',
                 'code persists, it is a different failure and worth reporting with the code.',
             ].join('\n');
     }
@@ -129,7 +180,11 @@ function diagnosis(failure) {
  *   diagnosis.
  *
  * A negative claim still has to be earned: the failure to avoid is advice that
- * is confidently wrong in the other direction.
+ * is confidently wrong in the other direction. That is why the `takeown` line
+ * claims only what is true in **both** ownership branches: it supplies the DACL
+ * half and never `WRITE_OWNER`, so it is not the fix by itself — while still
+ * being a legitimate first step (with elevation) where the caller is not the
+ * owner. Calling it useless outright would have been the mirror-image error.
  * @param failure - the recognized provisioning failure.
  * @param path - the directory the error named, or the placeholder.
  * @returns the section's lines, or an empty array for a class it does not fit.
@@ -138,10 +193,11 @@ function nonFixes(failure, path) {
     if (failure.klass !== 'apply-denied')
         return [];
     return [
-        'What will NOT fix it — both look like the right move, and both were tried and reported:',
+        'What will NOT fix it on its own — both look like the right move, and both were tried and reported:',
         `  takeown /F "${path}" /R /D Y`,
-        "    makes you the owner, but ownership's implicit rights are READ_CONTROL and WRITE_DAC only.",
-        '    The owner does not implicitly hold WRITE_OWNER, which is the right this call needs.',
+        "    makes you the owner, and ownership's implicit rights are READ_CONTROL and WRITE_DAC only — so it",
+        '    supplies the DACL half and still not WRITE_OWNER, the right this call needs. In the second branch above',
+        '    it is a legitimate first step with elevation; it is never the fix by itself.',
         `  icacls "${path}" /reset /T /C`,
         '    restores inheritance, and inheritance is what supplied the Modify-only ACE above.',
         '',
@@ -174,11 +230,11 @@ function versionBoundary() {
  *
  * 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 function advisoryText(failure, context = {}) {
     if (failure.family === 'pty-startup') {
@@ -187,6 +243,12 @@ export function advisoryText(failure, context = {}) {
         }
         return ptyAdvisory(failure, context.mode, context.tool, context.href);
     }
+    if (failure.family === 'native-init') {
+        if (context.mode === undefined) {
+            throw new Error('sandbox-grant-advisor: the native-init advisory requires the resolved sandbox mode');
+        }
+        return nativeInitAdvisory(failure, context.mode, context.electronHost ?? electronHost(), context.href);
+    }
     return aclAdvisory(failure, context.href);
 }
 /**
@@ -214,17 +276,36 @@ function aclAdvisory(failure, href) {
         '(WO) / Write owner. If the strongest entry naming you is (M) / Modify — or no entry names you at all and',
         'your access comes from an inherited `Authenticated Users:(M)` — that is this failure.',
         '',
-        'Fix it (unelevated, one line) and then run the command again:',
+        'Ownership decides which of the two commands below can work, so read it first — PowerShell 5.1 or later:',
+        `  (Get-Acl "${path}").Owner      # compare with: whoami`,
+        'If that is not your own account, take the second branch: the first one is refused before it runs.',
+        '',
+        'IF YOU OWN THE DIRECTORY — the usual workspace, whether on the system drive or a data volume:',
+        '  one unelevated line, then run the command again:',
         `  PowerShell: icacls "${path}" /grant "$env:USERNAME:(OI)(CI)(WO)"`,
         `  cmd:        icacls "${path}" /grant "%USERNAME%:(OI)(CI)(WO)"`,
         'WRITE_OWNER is exactly the right the prerequisite names, so this grants nothing the harness did not ask for,',
         'and (OI)(CI) makes the ACE inheritable, so one command reaches the workspace\'s existing subdirectories.',
         'Full control works just as well — the same line with `F` in place of `(WO)`:',
         `  icacls "${path}" /grant "$env:USERNAME:(OI)(CI)F"`,
-        'Both assume you own the directory: owner-implicit rights cover the DACL half of the merged write, so',
-        'WRITE_OWNER is the single missing piece. A directory owned by someone else is a bigger change than a',
-        'one-liner — that is the harness\'s documented prerequisite, and it is why this failure is loud instead of',
-        'silently skipped.',
+        'Why `(WO)` is the whole of what is missing there: an owner holds READ_CONTROL and WRITE_DAC implicitly,',
+        'and WRITE_DAC is what `icacls /grant` itself needs — so the DACL half of the merged write already has what',
+        'it wants, and WRITE_OWNER is the single missing piece.',
+        '',
+        'IF YOU DO NOT OWN IT — a directory an installer or another account created, e.g. owner',
+        '`BUILTIN\\Administrators`:',
+        '  the line above cannot run at all. Changing a DACL takes WRITE_DAC, which you hold neither as owner nor',
+        '  through any ACE, so `icacls /grant` is refused with `Access is denied` — for the very command that would',
+        '  fix it. The merged write wants WRITE_DAC and WRITE_OWNER together, so `(WO)` alone would not be enough',
+        '  here even if it went through. Run the grant once from an account that already holds both — that is, from an',
+        '  ELEVATED prompt:',
+        `  icacls "${path}" /grant "<your-account>:(OI)(CI)F"`,
+        'Full control is used because it is the rights set covering both halves; the other reach both reports name is',
+        'to take ownership first, which also needs elevation (it wants SeTakeOwnership), after which the unelevated',
+        '`(WO)` line above applies:',
+        `  icacls "${path}" /setowner "<your-account>"`,
+        'Or sidestep the ACL entirely: create the workspace under `%USERPROFILE%` — a directory created there',
+        'inherits Full control for you — and open the session on that one.',
         '',
         ...nonFixes(failure, path),
         'How to read this: the harness documents the prerequisite (' + PREREQUISITE + ') and this',
@@ -233,6 +314,78 @@ function aclAdvisory(failure, href) {
         'Your file read/write tools still work; only sandboxed command execution is blocked.',
     ].join('\n');
 }
+/**
+ * Build the advisory for a confined Windows child that never reached its entry
+ * point.
+ *
+ * Three things this text must not do: retry silently (the identical call cannot
+ * start), hand the model a command to run (there may be no working shell to run
+ * it in — that is what died), or assert which producer this is. The code is a
+ * loader status and says nothing about the sandbox by itself, so the diagnosis
+ * is the *class* ("the process never started") plus the two producers that have
+ * been measured under this harness, each with the check that distinguishes it.
+ * One of those checks the plugin answers itself and reports as a fact — whether
+ * this process is an Electron binary — rather than assuming, because a reader
+ * told "this is the packaged desktop" without evidence would be reading a guess
+ * dressed as a finding.
+ * @param failure - the recognized failure.
+ * @param mode - the resolved sandbox mode the failing call ran under.
+ * @param onElectron - whether this process is an Electron binary.
+ * @param href - optional URL shown for the upstream threads.
+ * @returns the user-role notice text.
+ */
+function nativeInitAdvisory(failure, mode, onElectron, href) {
+    const where = href === undefined ? `tracked upstream (discussions ${NATIVE_INIT_DISCUSSIONS})` : `tracked upstream: ${href}`;
+    return [
+        'Sandboxed command never started — the process died while its native libraries were loading.',
+        '',
+        'What was reported:',
+        `  ${failureLine(failure)}        (0xC0000142 STATUS_DLL_INIT_FAILED)`,
+        `The call ran under sandbox mode \`${mode}\`, where the harness starts every command through its`,
+        'restricted-token runner.',
+        '',
+        `0x${failure.exitCode.toString(16).toUpperCase()} is STATUS_DLL_INIT_FAILED: the Windows loader terminated the process while it was`,
+        'initializing its DLLs and C runtime, which is BEFORE the program\'s entry point. A command that ran and',
+        'then failed exits with its own status and prints its own output; this one produced neither. The number',
+        'is also not a portable exit status — those are 0-255, and this is a 32-bit NTSTATUS. Nothing in the code',
+        'says "sandbox" by itself; what makes the sandbox a candidate is the mode above, under which every',
+        'command is spawned through the ACL runner.',
+        '',
+        'Two producers have been measured under a confining Windows mode. Check which one this is:',
+        '  1. An MSYS2 / Git-Bash program — `bash.exe`, `sh.exe`, or anything from a Git for Windows or MSYS2',
+        '     distribution. Under the restricted token its runtime cannot create the pipe it uses for signals,',
+        '     and it aborts in the loader phase (`couldn\'t create signal pipe, Win32 error 5`), while `cmd.exe`',
+        '     and PowerShell run fine in the same workspace under the same mode (#7877).',
+        '     If that is what could not start: write the same work as a PowerShell or `cmd` command instead and',
+        '     continue — do not retry the MSYS2 program.',
+        '  2. The packaged desktop application\'s sandbox runner. `dsh-sandbox-local` starts the runner as',
+        '     `[process.execPath, runner.js]`, and in the packaged build `process.execPath` is the Electron',
+        '     executable, which starts as an *application* unless the child\'s environment carries',
+        '     `ELECTRON_RUN_AS_NODE=1` — so the runner never runs and every confined command reports this code',
+        '     with no output at all (#7876).',
+        onElectron
+            ? '     This process IS an Electron binary (`process.versions.electron` is set), so that producer applies here:'
+            : '     This process is NOT an Electron binary (`process.versions.electron` is unset), so the runner is a real',
+        onElectron
+            ? '     run the same command with `danger-full-access`, or from an unpacked `node apps/cli/lib/bin.js web`'
+            : '     Node binary here and that producer cannot be the cause. If the program was not an MSYS2 one either,',
+        onElectron
+            ? '     host where the runner is a real Node binary. If it works there, the runner never ran and this is the cause.'
+            : '     this failure is outside both measured producers: stop and hand it to the user.',
+        '',
+        'Do not retry this call: the environment has not changed, and the identical call produces the identical',
+        'code. Convert the work only in case 1; otherwise stop and hand it to the user.',
+        '',
+        'Honest boundary — 0xC0000142 has producers this list does not have: a program that cannot load one of',
+        'its own DLLs dies this way too, and the sandbox backend\'s own source records that a child started with',
+        'a hidden console window does as well (which is why that backend avoids `CREATE_NO_WINDOW`). This is not',
+        'a claim that the sandbox caused the failure — the code cannot say that. What is claimed is narrower and',
+        'checkable: the process never reached its entry point, and under this mode these two producers are known.',
+        '',
+        'This is a stopgap, ' + where + '. What it is NOT: this plugin neither changes an environment nor',
+        'widens the sandbox — the checks above are yours to make, and `danger-full-access` is not offered as a fix.',
+    ].join('\n');
+}
 /**
  * Build the advisory for a persistent-shell startup failure.
  *
@@ -286,14 +439,18 @@ function ptyAdvisory(failure, mode, tool, href) {
  * 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.

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.