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

package/lib/types/index.d.ts

@@ -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,20 +133,30 @@
  *   `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
  */
@@ -135,8 +182,9 @@ export declare 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 declare const ENFORCED_FAMILY = "acl-provisioning";
 /** Configures what is watched and whether the blocking half runs. */
@@ -144,8 +192,9 @@ export interface Config {
     /**
      * ACL provisioning failures after which an identical, already-failing call is
      * denied before dispatch. `0` (the default) disables the half entirely; the
-     * advisory half is unaffected and always on. The blocking half does not apply
-     * to the persistent-shell family.
+     * advisory half is unaffected and always on. The blocking half applies to the
+     * ACL family alone: it does not cover the persistent-shell or native-init
+     * families, whose remedies are not a command the session can wait out.
      */
     enforceAfter?: number;
     /**

package/lib/types/signature.d.ts

@@ -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,6 +82,71 @@
  * 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
  */
 /** Which provisioning operation failed, and which diagnosis follows from it. */
@@ -107,7 +172,9 @@ export type FailureFamily =
 /** The Windows sandbox could not provision its workspace (ACL / mandatory label). */
 'acl-provisioning'
 /** The persistent PTY shell could not start under a confining sandbox mode. */
- | 'pty-startup';
+ | 'pty-startup'
+/** A confined Windows child died while its native images were initializing. */
+ | 'native-init';
 /** One recognized provisioning failure, with the producer's own fields kept. */
 export interface ProvisioningFailure {
     /** Which family this failure belongs to. */
@@ -139,8 +206,35 @@ export interface PtyStartupFailure {
     /** The producer's message, kept as the constant so nothing can drift. */
     readonly line: string;
 }
+/**
+ * `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 declare const STATUS_DLL_INIT_FAILED = 3221225794;
+/**
+ * The code a confined Windows child died with, and the forms the caller may have
+ * to quote it in.
+ *
+ * There is no `path` and no `api` here: the producer of this failure is the
+ * operating system's loader, which reports only the status. What the diagnosis
+ * needs beyond the code — the effective sandbox mode — comes from the policy
+ * resolver at the call site, exactly as it does for the PTY family.
+ */
+export interface NativeInitFailure {
+    /** Which family this failure belongs to. */
+    readonly family: 'native-init';
+    /** The exit code exactly as the tool reported it, so it can be quoted back verbatim. */
+    readonly rawExitCode: number;
+    /** The same code normalized to its unsigned 32-bit form, for comparison and printing. */
+    readonly exitCode: number;
+}
 /** Any failure this plugin recognizes, tagged by family. */
-export type RecognizedFailure = ProvisioningFailure | PtyStartupFailure;
+export type RecognizedFailure = ProvisioningFailure | PtyStartupFailure | NativeInitFailure;
 /**
  * Classify one failure message against the ACL family.
  * @param message - the failure text, from the result's `error.message` or its rendered content.
@@ -161,6 +255,28 @@ export declare function classifyProvisioningFailure(message: string): Provisioni
  * @returns the recognized failure, or undefined when this is not one.
  */
 export declare function classifyPtyStartupFailure(message: string): PtyStartupFailure | 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 declare function classifyNativeInitDeath(value: unknown): NativeInitFailure | undefined;
 /**
  * The one-line failure the producer wrote, for quoting back verbatim.
  * @param failure - a recognized failure.

package/lib/types/state.d.ts

@@ -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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@argszero/cordis-plugin-sandbox-grant-advisor",
-  "description": "Turns two sandbox environment failures that name neither their cause nor a remedy into a diagnosis with a path forward. Family 1, the Windows workspace ACL: nine reports (#7538, #7622, #7646, #7720, #7750, #7735, #7771, #7804, #7816) of one signature — every sandboxed command fails before it runs with `SetNamedSecurityInfoW failed (Win32 5): grantWrite(<workspace>)`, because the merged DACL + mandatory-label write needs WRITE_OWNER on the directory (an object right the caller can self-grant), not SeSecurityPrivilege and not elevation; the host grant is materialized lazily and caches nothing on the failure path, so the same failure repeats per command. Family 2, the persistent shell (#7638): with the `minimal` preset under a confining sandbox mode every shell call dies instantly with `PTY shell exited during startup` because the terminal backend cannot create the pseudo-console inside the sandbox, retrying never helps, and `minimal` mounts no fallback shell tool. The plugin observes the public `tools/post-execute` waterfall, classifies both signatures narrowly (only the two `...NamedSecurityInfoW` operations; the PTY message matched on a whole line, never as a substring, and only under a mode the policy resolver reports as confining), and attaches ONE durable user-role advisory per agent per family through `additionalContexts`. The ACL advisory names the missing right, both environments the identical text can describe (an inherited Modify-only entry, a data volume where no ACE names the caller at all, and a directory owned by another account), the version boundary that arrived with the mandatory label (0.1.7-alpha.1, flag 20, versus the DACL-only flag 4 up to 0.1.6-alpha.x) together with why downgrading is not the remedy, the discriminator, the remedy forked on an ownership check the user runs (`(Get-Acl \"<dir>\").Owner`), because one command cannot serve both rights situations: where the caller owns the directory, the unelevated `icacls ... :(OI)(CI)(WO)` is the whole of what is missing — the owner's implicit WRITE_DAC already covers the DACL half — and where the caller does not own it that same command is refused for want of WRITE_DAC, so the grant has to come from an elevated account, or by taking ownership first, or by moving the workspace under %USERPROFILE% — and the two remedies that look right and are not (`takeown`, `icacls /reset`), each with the reason it fails; the PTY advisory names the failing combination, states the resolved mode, tells the model to stop rather than retry, and hands the user-side preset choice over — it never names a shell tool the failing composition does not mount. An optional, off-by-default `enforceAfter` refuses an identical ACL call this plugin has watched fail, bounded by `maxDenials`; the blocking half is ACL-only by design. It never edits an ACL, never elevates, and never changes a preset or a mode, and it complements repeat-guard-escalation, which keys on call identity rather than on the environment signature.",
-  "version": "0.5.0",
+  "description": "Turns three sandbox environment failures that name neither their cause nor a remedy into a diagnosis with a path forward. Family 1, the Windows workspace ACL: nine reports (#7538, #7622, #7646, #7720, #7750, #7735, #7771, #7804, #7816) of one signature \u2014 every sandboxed command fails before it runs with `SetNamedSecurityInfoW failed (Win32 5): grantWrite(<workspace>)`, because the merged DACL + mandatory-label write needs WRITE_OWNER on the directory (an object right the caller can self-grant), not SeSecurityPrivilege and not elevation; the host grant is materialized lazily and caches nothing on the failure path, so the same failure repeats per command. Family 2, the persistent shell (#7638): with the `minimal` preset under a confining sandbox mode every shell call dies instantly with `PTY shell exited during startup` because the terminal backend cannot create the pseudo-console inside the sandbox, retrying never helps, and `minimal` mounts no fallback shell tool. Family 3, a confined Windows child that died during native initialization (#7876, #7877): every command spawned through the sandbox runner can report exit 0xC0000142 STATUS_DLL_INIT_FAILED with the process never reaching its entry point \u2014 the packaged desktop starts that runner as [process.execPath, entry] and Electron launches as an application unless the child's environment carries ELECTRON_RUN_AS_NODE=1 (#7876), and an MSYS2 / Git-Bash program cannot create its signal pipe under the restricted token while cmd.exe and pwsh run fine in the same workspace under the same mode (#7877) \u2014 and because upstream's runner-failure rules admit only exit 127 with the `windows-acl-run: ` signature, the code is never an error: it arrives as the canonical value of a result the pipeline calls a success. The plugin observes the public `tools/post-execute` waterfall, classifies all three signatures narrowly (only the two `...NamedSecurityInfoW` operations; the PTY message matched on a whole line, never as a substring; the loader status read as a 32-bit integer out of the shell tool's own canonical success value, never from rendered text; both mode-gated families advised only under a mode the policy resolver reports as confining), and attaches ONE durable user-role advisory per agent per family through `additionalContexts`. The ACL advisory names the missing right, both environments the identical text can describe (an inherited Modify-only entry, a data volume where no ACE names the caller at all, and a directory owned by another account), the version boundary that arrived with the mandatory label (0.1.7-alpha.1, flag 20, versus the DACL-only flag 4 up to 0.1.6-alpha.x) together with why downgrading is not the remedy, the discriminator, the remedy forked on an ownership check the user runs (`(Get-Acl \"<dir>\").Owner`), because one command cannot serve both rights situations: where the caller owns the directory, the unelevated `icacls ... :(OI)(CI)(WO)` is the whole of what is missing \u2014 the owner's implicit WRITE_DAC already covers the DACL half \u2014 and where the caller does not own it that same command is refused for want of WRITE_DAC, so the grant has to come from an elevated account, or by taking ownership first, or by moving the workspace under %USERPROFILE% \u2014 and the two remedies that look right and are not (`takeown`, `icacls /reset`), each with the reason it fails; the PTY advisory names the failing combination, states the resolved mode, tells the model to stop rather than retry, and hands the user-side preset choice over \u2014 it never names a shell tool the failing composition does not mount; the native-init advisory states the resolved mode, says the process died before 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), carries the one conversion a model can make itself (rewrite the work as PowerShell or `cmd` when an MSYS2 program is what could not start), and says plainly which producers it does not know \u2014 it never claims the sandbox caused the failure and never offers a widened mode as a fix. An optional, off-by-default `enforceAfter` refuses an identical ACL call this plugin has watched fail, bounded by `maxDenials`; the blocking half is ACL-only by design. It never edits an ACL, never elevates, never sets another process's environment, and never changes a preset or a mode, and it complements repeat-guard-escalation, which keys on call identity rather than on the environment signature.",
+  "version": "0.6.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",