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

package/lib/types/index.d.ts

@@ -1,23 +1,45 @@
 /**
- * `sandbox-grant-advisor`: turn a Windows ACL provisioning failure that has no
- * path forward into a diagnosis the model — and the user reading the
- * transcript — can act on.
+ * `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.
  *
- * Three reports of one signature (`#7538`, `#7622`, `#7646`) describe the same
- * shape: the host-side write grant for a sandboxed workspace cannot be applied,
- * every sandboxed command then fails identically **before it runs**, and the
- * error text is a bare Win32 line:
+ * ## The two 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
+ * for a sandboxed workspace cannot be applied, every sandboxed command then
+ * fails identically **before it runs**, and the error text is a bare Win32 line:
  *
  *   SetNamedSecurityInfoW failed (Win32 5): grantWrite(D:\ws)
  *
  * The grant is materialized lazily on the first confined call and nothing is
  * cached when it throws, so the failure repeats per command rather than once
  * (850 calls / 39 sessions in `#7622`; 52,588 output tokens with no output in
- * `#7538`). The `workspace-write` policy is simply unusable in such a
- * workspace, and the remedy the backend documents — the directory must grant
- * the caller `WRITE_OWNER` — never reaches the user, so sessions escape into
+ * `#7538`). The remedy the backend documents — the directory must grant the
+ * caller `WRITE_OWNER` — never reaches the user, so sessions escape into
  * `danger-full-access` or die on the model's output cap.
  *
+ * `#7720` sharpens where this lands: because the grant is materialized at
+ * sandbox *initialization*, that failure takes **every** shell tool with it, not
+ * one operation — the reporter could not run `netstat` or `icacls` to diagnose
+ * the failure they were looking at. It also contributes the two remedies that
+ * look right and are not (`takeown /R /D Y`, `icacls /reset /T /C`), which the
+ * ACL advisory now names along with the reason each fails.
+ *
+ * **Persistent shell startup (#7638).** With the `minimal` preset on Windows the
+ * only shell tool is a persistent PTY (`dsh-terminal-bash` +
+ * `dsh-tool-pwsh-persistent`), and under a *confining* sandbox mode every call
+ * fails instantly with
+ *
+ *   PTY shell exited during startup
+ *
+ * — the backend cannot create the pseudo-console inside the sandbox, so the
+ * child exits before its first prompt. Retrying never helps, the message points
+ * at no cause, and because `minimal` mounts no fallback shell tool the session
+ * has no command execution left at all. The reporter's own three-arm control
+ * makes the sandbox mode the discriminator: minimal × confining fails, minimal ×
+ * `danger-full-access` succeeds, `standard` (one-shot shell) × confining
+ * succeeds.
+ *
  * ## Where it acts, and why there
  *
  * One listener on the public `tools/post-execute` waterfall
@@ -28,44 +50,66 @@
  * to the model in the same step (`PostToolDecision`'s `additionalContexts`,
  * a durable user-role message).
  *
- * `ctx.sandbox.confine(argv, policy, signal)` sees the failure too, and cannot
- * do this: its signature carries no agent, so a wrapper could detect the
- * condition and never deliver a word about it to the session that is stuck.
+ * `ctx.sandbox.confine(argv, policy, signal)` sees the confinement failure too,
+ * and cannot do this: its signature carries no agent, so a wrapper could detect
+ * the condition and never deliver a word about it to the session that is stuck.
+ *
+ * The PTY family needs one fact the failure text does not carry — the effective
+ * sandbox mode — and takes it from `ctx.sandboxPolicy.resolve({ session })`:
+ * the same resolver the terminal layer calls before spawning, with the same
+ * session. See `src/mode.ts` for why that lookup is guarded rather than
+ * imported, and what happens when it cannot answer.
  *
  * ## What it does
  *
- * 1. **One durable advisory per agent.** On the first recognized provisioning
- *    failure, the failing tool result is enriched with a user-role notice that
- *    names the missing right (`WRITE_OWNER` on the directory, not
- *    `SeSecurityPrivilege`), gives the unelevated one-line `icacls` remedy, and
- *    gives the discriminator that separates a Modify-only directory from a
- *    wrong prerequisite. Attached through `additionalContexts`, so the model
- *    sees it beside the failure rather than only in a log the model never reads.
- * 2. **An optional bounded fail-fast.** With `enforceAfter` set, a call this
- *    plugin has *watched fail* this way is refused at `tools/pre-execute` once
- *    the environment has failed at least that many times. It is off by 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.
+ * 1. **One durable advisory per agent, per family.** On the first recognized
+ *    failure of a family, the failing tool result is enriched with a user-role
+ *    notice. For the ACL family it names the missing right (`WRITE_OWNER` on the
+ *    directory, not `SeSecurityPrivilege`), gives the unelevated one-line
+ *    `icacls` remedy, gives the discriminator that separates a Modify-only
+ *    directory from a wrong prerequisite, and names the two remedies that look
+ *    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
+ *    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
+ *    this plugin has *watched fail* this way is refused at `tools/pre-execute`
+ *    once the environment has failed at least that many times. It is off by
+ *    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
+ *    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.
  *
  * ## Honest boundaries
  *
  * - **The Windows path cannot be witnessed on macOS**, where this plugin was
  *   built and tested. What is tested is the decision layer: classification,
- *   once-per-agent delivery, the fail-fast budget, and the wiring to the real
- *   `ToolRuntime` — against synthetic results carrying the producer's exact
- *   error shape, with the format taken from
- *   `packages/subprocess/win32-process/src/errors.ts`.
+ *   once-per-agent-per-family delivery, the sandbox-mode gate and its
+ *   fail-closed behaviour, the fail-fast budget, and the wiring to the real
+ *   `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`.
  * - **It does not repair anything.** No ACL is written, no privilege is
- *   requested, nothing is elevated: the `icacls` line is the user's to run.
+ *   requested, nothing is elevated, no preset is installed and no mode is
+ *   changed: both remedies are the user's to apply.
  * - **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**: the failure should name the outstanding
- *   condition at the site that knows it (`grantWrite` computes
+ * - **The real fix is upstream**, in both 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). This plugin is the stopgap.
+ *   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.
  *
  * @module @argszero/cordis-plugin-sandbox-grant-advisor
  */
@@ -87,12 +131,21 @@ export declare const SOURCE_KIND = "sandbox-grant-advisor";
 export declare const DEFAULT_ENFORCE_AFTER = 0;
 /** Default denial budget once the blocking half is enabled. */
 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`.
+ */
+export declare const ENFORCED_FAMILY = "acl-provisioning";
 /** Configures what is watched and whether the blocking half runs. */
 export interface Config {
     /**
-     * Provisioning failures after which an identical, already-failing call is
+     * 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.
+     * advisory half is unaffected and always on. The blocking half does not apply
+     * to the persistent-shell family.
      */
     enforceAfter?: number;
     /**

package/lib/types/mode.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Which sandbox mode a call ran under, and whether that mode confines.
+ *
+ * The persistent-shell diagnosis is only true under a **confining** mode. The
+ * terminal backend hands the shell argv straight through when the resolved mode
+ * is `danger-full-access` and confines it otherwise
+ * (`packages/terminal/terminal-bash/src/index.ts`:
+ * `if (policy.mode === 'danger-full-access') return argv`), so the same
+ * `PTY shell exited during startup` under `danger-full-access` is a different
+ * story — a broken or missing shell — and this plugin must stay silent about it
+ * rather than assert a sandbox cause it cannot support. The report that frames
+ * this family (#7638) says the same thing from the other side: its author's
+ * three-arm control shows the mode is the discriminator (minimal × confining
+ * fails, minimal × `danger-full-access` succeeds, standard × confining
+ * succeeds).
+ *
+ * The answer is taken from `ctx.sandboxPolicy.resolve({ session })` — the same
+ * resolver the terminal layer itself calls before spawning, with the same
+ * session — so what is quoted in the advisory is the policy that actually
+ * governed the failing call, not a guess reconstructed from configuration.
+ *
+ * ## Why this is a guarded lookup instead of an import
+ *
+ * `@deepseek-ai/dsh-sandbox-policy` is **optional** in this plugin's world: a
+ * composition may simply not mount the service, and this plugin must degrade to
+ * silence rather than fail to load. Two consequences shape this module:
+ *
+ * - A declared peer dependency is a claim about versions, and this package's
+ *   packaging guard refuses both an import that is not declared and a
+ *   declaration that is not imported. A *type-only* import would therefore turn
+ *   an optional integration into a mandatory claim on every line the peer range
+ *   admits — and a range that admits a line nobody ran is exactly the defect
+ *   that guard exists to prevent.
+ * - What is left is the consumer-side capability guard: look the service up,
+ *   check the shape of the answer instead of trusting it, and **fail closed**
+ *   (`{ ok: false }`): an unresolvable mode withholds the advisory, and the
+ *   caller discloses that withholding on the host side. An unresolvable mode is
+ *   emphatically *not* an invitation to fall back to the deployment default —
+ *   a session that overrode its mode to `danger-full-access` would then be
+ *   diagnosed as if it were confined.
+ *
+ * The call site this module depends on is stable across every line the peer
+ * range claims: `resolve(request?: SandboxPolicyRequest): SandboxExecutionPolicy`
+ * is declared at the same position of `lib/types/index.d.ts` in every published
+ * build from `0.1.2-rc.1` to `0.1.7-rc.1`, and `Agent.session` is present on
+ * the same span of `@deepseek-ai/dsh-agent`.
+ *
+ * @module
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+/** The three modes the harness resolves. */
+export type SandboxModeName = 'read-only' | 'workspace-write' | 'danger-full-access';
+/**
+ * Whether a mode confines the process it is asked to spawn.
+ * @param mode - the resolved mode.
+ * @returns true for every mode except `danger-full-access`.
+ */
+export declare function confines(mode: SandboxModeName): boolean;
+/** The outcome of resolving one agent's effective sandbox mode. */
+export type ModeResolution = 
+/**
+ * The mode the failing call ran under. `danger-full-access` is reported too:
+ * it is a real answer, and the caller's job (not this module's) is to decide
+ * that a non-confining mode is not this plugin's story.
+ */
+{
+    readonly ok: true;
+    readonly mode: SandboxModeName;
+}
+/** No answer was available, and why — the host side says so out loud. */
+ | {
+    readonly ok: false;
+    readonly withheld: string;
+};
+/**
+ * Resolve the effective sandbox mode for one agent's call.
+ *
+ * The service is looked up through `ctx.get` — the documented optional lookup —
+ * and the resolver is invoked with the agent's own session, so a session that
+ * logged a `sandbox/mode` override is answered with that override rather than
+ * with the deployment default.
+ * @param ctx - the plugin's context.
+ * @param agent - the agent whose call failed.
+ * @returns the mode, or the reason it could not be resolved.
+ */
+export declare function resolveSandboxMode(ctx: Context, agent: Agent): ModeResolution;

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: four reports (#7538, #7622, #7646, #7720) 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, the unelevated `icacls` fix, 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.3.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"