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

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`)
@@ -30,17 +30,32 @@
  *   the advisory can quote the exact line the model and the user are looking
  *   at, and the path can be re-used in the fix command.
  *
- * One signature covers two environments, and the text is identical in both, so
- * the classifier cannot and must not try to tell them apart: a workspace the
- * caller created with `mkdir` that inherits "Authenticated Users: Modify" from
- * the drive root (`#7622`, `#7646`, `#7720`), and a directory on a data volume
- * where **no ACE names the caller at all** so that the inherited entry is the
- * whole of their access (`#7750` on D:/E:, `#7735`'s second defect). Both are
- * the same gate — `WRITE_OWNER` on the directory — and the same one-line remedy
- * satisfies both, which is why they share a class and the advisory names both
- * shapes instead of guessing which one it is looking at. What the text *does*
- * carry that the failure does not is the version boundary: the merged
- * DACL + label write exists only from `0.1.7-alpha.1` on
+ * One signature covers three environments, the text is identical in all of them,
+ * and the classifier cannot and must not try to tell them apart — but the
+ * *remedy* is not the same in all of them, which is why the advisory forks on a
+ * check the user runs rather than on a guess this module cannot make:
+ *
+ * - a workspace the caller created with `mkdir` that inherits "Authenticated
+ *   Users: Modify" from the drive root (`#7622`, `#7646`, `#7720`);
+ * - a directory on a data volume where **no ACE names the caller at all**, so
+ *   the inherited entry is the whole of their access (`#7750` on D:/E:,
+ *   `#7735`'s second defect);
+ * - a directory **the caller does not own** — an installer- or
+ *   administrator-created one, `#7771` (owner `BUILTIN\Administrators`, held
+ *   deny-only for that token), which `#7804` reached from the other direction.
+ *
+ * In the first two the caller is the owner, so their implicit `WRITE_DAC`
+ * satisfies the DACL half and `WRITE_OWNER` is the single missing right — one
+ * unelevated `icacls /grant` supplies exactly it, and `#7750` measured that
+ * remedy working. In the third `WRITE_DAC` is missing as well, so that same
+ * `icacls` is refused for the very command that would fix it and `(WO)` alone
+ * would not be enough even if it went through. The advisory therefore hands over
+ * the ownership check (`(Get-Acl "<dir>").Owner`) as the branch selector and
+ * gives each branch the command that works there — the same class, two rights
+ * situations, and no guess about which one this is.
+ *
+ * What the text *does* carry that the failure does not is the version boundary:
+ * the merged DACL + label write exists only from `0.1.7-alpha.1` on
  * (`packages/sandbox/sandbox-windows-acl/src/acl.ts`, flag
  * `DACL_SECURITY_INFORMATION | LABEL_SECURITY_INFORMATION`), so on an older line
  * the same string belongs to a different cause space.
@@ -67,16 +82,85 @@
  * 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. */
 export type FailureClass = 
 /**
  * `SetNamedSecurityInfoW` returned `ERROR_ACCESS_DENIED` (5): the merged
- * DACL + label write was refused. Both environments in the module doc land
- * here — the `mkdir`-inherited Modify workspace and the data-volume directory
- * with no ACE naming the caller — because the failure text cannot separate
- * them and the remedy is the same `WRITE_OWNER` grant.
+ * DACL + label write was refused. All three environments in the module doc
+ * land here — the `mkdir`-inherited Modify workspace, the data-volume
+ * directory with no ACE naming the caller, and the directory owned by another
+ * account — because the failure text cannot separate them. The first two are
+ * the same rights situation (the caller owns it; `WRITE_OWNER` is the whole of
+ * what is missing) and share the unelevated remedy; the third is missing
+ * `WRITE_DAC` as well, which is why the advisory hands over the ownership
+ * check and forks the command on it.
  */
 'apply-denied'
 /** `SetNamedSecurityInfoW` failed with a Win32 code other than `ERROR_ACCESS_DENIED`. */
@@ -88,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. */
@@ -120,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.
@@ -142,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: six reports (#7538, #7622, #7646, #7720, #7750, #7735) 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, and a data volume where no ACE names the caller at all), 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 unelevated `icacls ... :(OI)(CI)(WO)` fix — the narrowest form of the exact right the backend's prerequisite names, with Full control offered second — 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.4.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",