@argszero/cordis-plugin-sandbox-grant-advisor 0.1.0 → 0.2.0

package/lib/types/signature.d.ts

@@ -1,5 +1,8 @@
 /**
- * Recognize the Windows ACL provisioning failure that has no path forward.
+ * Recognize the two environment failures this plugin explains, and refuse
+ * everything else.
+ *
+ * ## The ACL provisioning failure (`acl-provisioning`)
  *
  * The harness's Windows sandbox provisions a workspace by writing the
  * directory's DACL and its mandatory-integrity label in **one**
@@ -10,7 +13,7 @@
  * it. Every sandboxed command then fails the same way, forever, because the
  * grant is materialized lazily and nothing is cached on the failure path.
  *
- * Recognizing the string is therefore the whole job of this module, and the
+ * Recognizing the string is therefore the whole job of this half, and the
  * recognition is deliberately narrow:
  *
  * - **Only the two `...NamedSecurityInfoW` operations are classified.** Their
@@ -27,6 +30,28 @@
  *   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.
  *
+ * ## The persistent-shell startup failure (`pty-startup`)
+ *
+ * `dsh-terminal-bash` throws `PTY shell exited during startup` when the shell
+ * it spawned through the sandbox exits before reaching its first prompt
+ * (`src/session.ts` and `src/index.ts`, both on the same `waitReason ===
+ * 'session_exit'` branch). The text names no cause and, under the `minimal`
+ * preset — whose only shell tool is a persistent PTY — there is no other shell
+ * tool left to fall back on, so the model reads it as "the command failed" and
+ * retries forever. #7638 is the report: 33 consecutive failures under
+ * `workspace-write`, none under `danger-full-access`, with the reporter's own
+ * three-arm control showing the sandbox mode is the discriminator.
+ *
+ * This family is recognized on an **exact line**, not on a substring, and that
+ * is deliberate. The producer's message has no detail field at all — the whole
+ * message is the sentence — so anything that merely *contains* the phrase is
+ * quoting it (a transcript, a log a failing command printed, a pasted issue
+ * body) rather than producing it. The sibling throw on the same branch, `PTY
+ * shell did not reach readiness before startup timeout`, is **not** classified
+ * here: it means the shell started and then did not reach a prompt, which is a
+ * 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.
+ *
  * @module
  */
 /** Which provisioning operation failed, and which diagnosis follows from it. */
@@ -37,8 +62,16 @@ export type FailureClass =
  | 'apply-other'
 /** `GetNamedSecurityInfoW` failed: the security descriptor could not even be read. */
  | 'read-denied';
+/** The environment failure family a recognized failure belongs to. */
+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';
 /** One recognized provisioning failure, with the producer's own fields kept. */
 export interface ProvisioningFailure {
+    /** Which family this failure belongs to. */
+    readonly family: 'acl-provisioning';
     /** Which diagnosis follows from the api/code pair. */
     readonly klass: FailureClass;
     /** The API whose checked result failed, exactly as the producer names it. */
@@ -52,15 +85,45 @@ export interface ProvisioningFailure {
     /** The directory the detail names, when it has that shape. */
     readonly path?: string;
 }
+/** The exact text `dsh-terminal-bash` throws when the shell exits during startup. */
+export declare const PTY_STARTUP_EXIT = "PTY shell exited during startup";
 /**
- * Classify one failure message.
+ * The persistent-shell startup failure. It carries no producer fields: the
+ * producer's entire message is {@link PTY_STARTUP_EXIT}, and what makes the
+ * diagnosis actionable (the effective sandbox mode) comes from the policy
+ * resolver at the call site rather than from the error text.
+ */
+export interface PtyStartupFailure {
+    /** Which family this failure belongs to. */
+    readonly family: 'pty-startup';
+    /** The producer's message, kept as the constant so nothing can drift. */
+    readonly line: string;
+}
+/** Any failure this plugin recognizes, tagged by family. */
+export type RecognizedFailure = ProvisioningFailure | PtyStartupFailure;
+/**
+ * Classify one failure message against the ACL family.
  * @param message - the failure text, from the result's `error.message` or its rendered content.
  * @returns the recognized failure, or undefined when this is not a provisioning failure.
  */
 export declare function classifyProvisioningFailure(message: string): ProvisioningFailure | undefined;
+/**
+ * Classify one failure message as the persistent-shell startup failure.
+ *
+ * Recognition is by **whole line**, because the producer's message is a bare
+ * sentence with no fields of its own: a line equal to
+ * {@link PTY_STARTUP_EXIT} — with only the `Error: ` envelope a tool result adds
+ * in front of it — is the producer. A longer line that happens to contain the
+ * sentence is something quoting it (a transcript, a log the failing command
+ * printed, a pasted issue body), and advising about the sandbox there would be
+ * advice about the wrong thing.
+ * @param message - the failure text, from the result's `error.message` or its rendered content.
+ * @returns the recognized failure, or undefined when this is not one.
+ */
+export declare function classifyPtyStartupFailure(message: string): PtyStartupFailure | undefined;
 /**
  * The one-line failure the producer wrote, for quoting back verbatim.
  * @param failure - a recognized failure.
- * @returns the message text a `Win32Error` would have produced.
+ * @returns the message text the producing layer would have produced.
  */
-export declare function failureLine(failure: ProvisioningFailure): string;
+export declare function failureLine(failure: RecognizedFailure): string;

package/lib/types/state.d.ts

@@ -6,35 +6,60 @@
  * failing call carries `exec.agent`, one agent owns one session, and a WeakMap
  * keyed by the agent object lets a finished session's state be collected.
  *
- * Two counters, two meanings — keeping them apart is what stops the plugin from
- * feeding on itself:
+ * ## One record per family
  *
- * - `observations` counts *provisioning failures of this environment*, i.e.
+ * 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
+ * ({@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
+ * diagnosis, which is the failure mode this split exists to prevent.
+ *
+ * Three counters, three meanings — keeping them apart is what stops the plugin
+ * from feeding on itself:
+ *
+ * - `observations` counts *failures of this environment in this family*, i.e.
  *   tool results the environment itself produced. A call this plugin denied is
- *   not one of them, even though its denial text quotes the Win32 line.
+ *   not one of them, even though its denial text quotes the producer's line.
  * - `failingKeys` holds the call identities (tool + canonical arguments) that
  *   have already failed this way. The fail-fast half may only refuse a call it
  *   has *watched fail* — never a call it merely recognizes as similar.
- *
- * `denials` is spent per *episode*: it is re-armed when a watched call finally
- * succeeds (see `observeSuccess`), not carried for the whole session.
+ * - `denials` is spent per *episode*: it is re-armed when a watched call finally
+ *   succeeds (see `observeSuccess`), not carried for the whole session.
  *
  * @module
  */
-import type { ProvisioningFailure } from './signature.js';
-/** Everything the plugin remembers about one agent. */
-export interface AgentState {
-    /** Provisioning failures observed for this agent. */
+import type { FailureFamily, RecognizedFailure } from './signature.js';
+/** Everything the plugin remembers about one agent in one failure family. */
+export interface FamilyState {
+    /** Failures of this family observed for this agent. */
     observations: number;
     /** The most recent failure, for the denial text. */
-    last: ProvisioningFailure;
+    last: RecognizedFailure;
     /** Identity keys of the calls that failed this way. */
     failingKeys: Set<string>;
     /** Denials already spent. */
     denials: number;
-    /** Whether the durable advisory has been delivered for this agent. */
+    /** Whether this family's durable advisory has been delivered for this agent. */
     advised: boolean;
 }
+/** Everything the plugin remembers about one agent. */
+export interface AgentState {
+    /** Per-family bookkeeping; a family appears only once it has been observed. */
+    readonly families: Readonly<Partial<Record<FailureFamily, FamilyState>>>;
+    /**
+     * Whether a recognized failure was withheld from the model and the host has
+     * already accounted for it once. Withholding is a real decision — the mode
+     * was not confining, or could not be resolved — and a decision the transcript
+     * cannot show must be visible somewhere, or "this is not the sandbox" and "I
+     * could not tell" read the same from the outside.
+     */
+    readonly withheld: boolean;
+}
+/** The state of an agent this plugin has never observed. */
+export declare function emptyState(): AgentState;
 /**
  * Canonicalize a parsed argument value into a stable string.
  *
@@ -56,29 +81,55 @@ export declare function canonicalize(value: unknown): string;
  */
 export declare function callKey(name: string, args: unknown): string;
 /**
- * Record one observed provisioning failure.
+ * Record one observed failure in one family.
  * @param state - the agent's current state, or undefined on first sight.
+ * @param family - the family the failure belongs to.
  * @param failure - the recognized failure.
  * @param key - the identity of the call that failed.
  * @returns the updated state.
  */
-export declare function observe(state: AgentState | undefined, failure: ProvisioningFailure, key: string): AgentState;
+export declare function observe(state: AgentState | undefined, family: FailureFamily, failure: RecognizedFailure, key: string): AgentState;
+/**
+ * Whether this family's durable advisory has already been delivered.
+ * @param state - the agent's current state, or undefined.
+ * @param family - the family in question.
+ * @returns true when the advice is already in the session.
+ */
+export declare function advisedOf(state: AgentState | undefined, family: FailureFamily): boolean;
+/**
+ * Mark one family's durable advisory as delivered.
+ * @param state - the agent's current state.
+ * @param family - the family that was advised.
+ * @returns the updated state.
+ */
+export declare function recordAdvice(state: AgentState, family: FailureFamily): AgentState;
+/**
+ * Record that a recognized failure was withheld from the model.
+ * @param state - the agent's current state, or undefined on first sight.
+ * @returns the updated state.
+ */
+export declare function recordWithheld(state: AgentState | undefined): AgentState;
 /**
  * Record that a call carrying the same identity as a previously failing one
- * succeeded. The environment worked at least once for that call, so the entry
- * stops justifying a denial — and is dropped rather than kept, so a later
- * failure re-earns it.
+ * succeeded — in **every** family that was watching that identity.
  *
- * The denial budget is re-armed at the same moment, and only then. Measured
- * consequence: without it the budget is per agent for the whole session, which
- * makes the entry above unobservable — past `maxDenials` this plugin refuses
- * nothing ever again, so clearing the key would change no decision. With it the
- * bound reads as "at most `maxDenials` refusals per episode of brokenness": an
- * environment that breaks, is repaired and breaks again may be refused again,
- * while a session can always make progress by spending the budget.
+ * The environment worked at least once for that call, so the entry stops
+ * justifying a denial — and is dropped rather than kept, so a later failure
+ * re-earns it. A success is evidence about the environment, not about one
+ * diagnosis: the same call cannot have started working for one family's reason
+ * and not the other's.
+ *
+ * Each affected family's denial budget is re-armed at the same moment, and only
+ * then. Measured consequence: without it the budget is per agent for the whole
+ * session, which makes the entry above unobservable — past `maxDenials` this
+ * plugin refuses nothing ever again, so clearing the key would change no
+ * decision. With it, the bound reads as "at most `maxDenials` refusals per
+ * episode of brokenness": an environment that breaks, is repaired and breaks
+ * again may be refused again, while a session can always make progress by
+ * spending the budget.
  * @param state - the agent's current state.
  * @param key - the identity of the call that just succeeded.
- * @returns the updated state, unchanged when the key was not failing.
+ * @returns the updated state, unchanged when no family was watching the key.
  */
 export declare function observeSuccess(state: AgentState, key: string): AgentState;
 /**
@@ -89,22 +140,21 @@ export declare function observeSuccess(state: AgentState, key: string): AgentSta
  * fail. The second condition is what keeps the fail-fast half from blocking a
  * workaround: a different command, or the same command under a different policy
  * after the user changed configuration, has no key here.
+ *
+ * Only the `acl-provisioning` family ever reaches this question; see the
+ * `denialText` doc for why the blocking half does not extend to `pty-startup`.
  * @param state - the agent's current state, or undefined.
+ * @param family - the family whose threshold is being asked about.
  * @param key - the identity of the call about to dispatch.
  * @param enforceAfter - the configured threshold; 0 disables the half entirely.
  * @param maxDenials - the configured denial budget.
  * @returns whether to deny.
  */
-export declare function shouldDeny(state: AgentState | undefined, key: string, enforceAfter: number, maxDenials: number): boolean;
+export declare function shouldDeny(state: AgentState | undefined, family: FailureFamily, key: string, enforceAfter: number, maxDenials: number): boolean;
 /**
  * Spend one denial.
  * @param state - the agent's current state.
+ * @param family - the family being denied.
  * @returns the updated state.
  */
-export declare function recordDenial(state: AgentState): AgentState;
-/**
- * Mark the durable advisory as delivered.
- * @param state - the agent's current state.
- * @returns the updated state.
- */
-export declare function recordAdvice(state: AgentState): AgentState;
+export declare function recordDenial(state: AgentState, family: FailureFamily): AgentState;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@argszero/cordis-plugin-sandbox-grant-advisor",
-  "description": "Turns the Windows sandbox's ACL provisioning failure into a diagnosis with a path forward. Three reports (#7538, #7622, #7646) describe one signature — every sandboxed command fails before it runs with `SetNamedSecurityInfoW failed (Win32 5): grantWrite(<workspace>)` — and the error names neither the missing right nor a remedy, so the loop burns tokens and sessions escape into danger-full-access. The host-side grant is materialized lazily and caches nothing on the failure path, so the same failure repeats per command. This plugin observes the public `tools/post-execute` waterfall, classifies that signature (only the two `...NamedSecurityInfoW` operations, keeping the Win32 code and the producer's own detail verbatim), and attaches ONE durable user-role advisory per agent through `additionalContexts`: the missing right is WRITE_OWNER on the directory (an object right the caller can self-grant), not SeSecurityPrivilege and not elevation; the directory's current ACL is the discriminator; the fix is one unelevated `icacls` line. An optional, off-by-default `enforceAfter` refuses an identical call this plugin has watched fail, bounded by `maxDenials`. It never edits an ACL and never elevates, and it complements repeat-guard-escalation, which keys on call identity rather than on the environment signature.",
-  "version": "0.1.0",
+  "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: three reports (#7538, #7622, #7646) 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, the discriminator, and the unelevated `icacls` fix; 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.2.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -67,7 +67,8 @@
     "pretest": "tsc",
     "test": "node --test \"test/*.spec.mjs\"",
     "test:probe-lines": "node scripts/probe-lines.mjs",
-    "prepublishOnly": "tsc"
+    "prepublishOnly": "tsc",
+    "test:inject": "node scripts/inject-defects.mjs"
   },
   "engines": {
     "node": "^22.19 || >=24"