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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 argszero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# @argszero/cordis-plugin-sandbox-grant-advisor
+
+Turns a Windows sandbox **ACL provisioning failure with no path forward** into a
+diagnosis the model — and the user reading the transcript — can act on.
+
+```
+SetNamedSecurityInfoW failed (Win32 5): grantWrite(D:\ws)
+```
+
+Three reports describe this exact line: [discussion #7538], [discussion #7622],
+[discussion #7646]. In each one every sandboxed command fails the same way,
+before it runs, and the error names neither the missing right nor a remedy.
+
+**This plugin is the stopgap for "the error does not name the outstanding
+condition".** It does not repair anything: no ACL is written, no privilege is
+requested, nothing is elevated.
+
+## The failure it recognizes
+
+The Windows backend provisions a workspace by writing the directory's DACL and
+its mandatory-integrity label in **one** `SetNamedSecurityInfoW` call
+(`packages/sandbox/sandbox-windows-acl/src/acl.ts`:
+
+```ts
+if (applyResult !== abi.ERROR_SUCCESS) throwWin32(api, 'SetNamedSecurityInfoW', applyResult, `${label}(${path})`)
+```
+
+). Two consequences follow from that one line:
+
+1. **The label lives in the SACL, and its half is what gets refused.** The
+   owner's implicit rights cover only `READ_CONTROL` and `WRITE_DAC`, so the
+   combined apply additionally needs **`WRITE_OWNER` on the directory** — an
+   *object right*, which a Full-control directory (the normal workspace case)
+   has and a `mkdir`-created one inheriting "Authenticated Users: Modify"
+   (`0x1301bf`) does not. This is the backend's own documented prerequisite
+   ("granted directories must be caller-owned and grant `WRITE_OWNER`").
+2. **It is not `SeSecurityPrivilege`, and elevation is the wrong lever.** That
+   is the token-privilege form of the same idea, and it is the hypothesis the
+   reports naturally reach for — `whoami /priv` cannot tell the two apart,
+   because `WRITE_OWNER` is an object right and never appears in that table.
+   Granting Full control to the workspace root needs **no** elevation.
+
+The grant is materialized lazily, on the first confined call, and **nothing is
+cached when it throws** — so the same failure repeats per command (850 calls
+across 39 sessions in #7622; 52,588 output tokens with no output in #7538),
+which is why the loop cannot separate it from ordinary command noise.
+
+## What it does
+
+One listener on the public **`tools/post-execute`** waterfall
+(`@deepseek-ai/dsh-tools`). That seam — not `ctx.sandbox.confine` — because it is
+the only one that has all three of: the failure text (providers propagate their
+error unchanged, and the tool pipeline settles it as an `isError` result), an
+agent identity to attribute it to (`exec.agent`), and a channel that speaks to
+the model in the same step (`PostToolDecision`'s `additionalContexts`, which the
+agent loop turns into a durable user-role message —
+`packages/core/agent-loop/src/tool-calls.ts`).
+
+1. **One durable advisory per agent.** On the first recognized failure, the
+   result is enriched with a user-role notice that names the missing right, the
+   discriminator, and the unelevated fix:
+
+   ```
+   Sandbox provisioning failed — no sandboxed command can run in this workspace until its ACL applies.
+
+   What was reported:
+     SetNamedSecurityInfoW failed (Win32 5): grantWrite(D:\ws)
+
+   Why it is refused while the directory looks writable: that call is a MERGED write ...
+     ... the label half additionally needs WRITE_OWNER on the directory. ...
+
+   Confirm the cause (unelevated) — `icacls` is a normal user command:
+     icacls "D:\ws"
+
+   Fix it (unelevated, one line) and then run the command again:
+     PowerShell: icacls "D:\ws" /grant "$env:USERNAME:(OI)(CI)F"
+     cmd:        icacls "D:\ws" /grant "%USERNAME%:(OI)(CI)F"
+   ```
+
+   The notice carries its own producer-owned `source.kind`
+   (`sandbox-grant-advisor`) — not the retired `plugin` wrapper, which the
+   current session format refuses — and a bounded one-line `summary` for the
+   transcript row. The host log gets one matching `warn` line, so the fact
+   survives outside the transcript too.
+2. **An optional, bounded fail-fast half** (`enforceAfter`, default **0** =
+   off). It refuses a call **before dispatch** only when both hold: the
+   environment has failed provisioning at least `enforceAfter` times, **and**
+   this exact call (tool + canonical arguments) is one this plugin watched fail.
+   The budget is `maxDenials` (default 2), after which the call proceeds again.
+   The budget is per **episode of brokenness**: a call that finally succeeds stops
+   being a denial target and re-arms it, so an environment that breaks twice can
+   be refused twice — while a session can always make progress by spending the
+   budget it has.
+
+## Install
+
+```sh
+npm install @argszero/cordis-plugin-sandbox-grant-advisor
+```
+
+Mount it by adding the patch to your profile, or apply the shipped
+`cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: sandbox-grant-advisor
+      name: '@argszero/cordis-plugin-sandbox-grant-advisor'
+```
+
+## Configuration
+
+| option | default | meaning |
+| --- | --- | --- |
+| `enforceAfter` | `0` | Provisioning failures in one agent after which an identical, already-failing call is refused before dispatch. `0` disables the blocking half entirely. |
+| `maxDenials` | `2` | Denials one agent may spend per episode of brokenness. Bounded on purpose; re-armed when a watched call finally succeeds. |
+| `include` | `[]` | Tool-name wildcard patterns to watch; empty means every tool. |
+| `exclude` | `[]` | Tool-name wildcard patterns never watched. |
+| `href` | — | URL quoted in the advisory as the upstream thread, instead of the discussion numbers. |
+
+```yaml
+- set:
+    - id: sandbox-grant-advisor
+      config:
+        enforceAfter: 3
+```
+
+## What it deliberately refuses to explain
+
+Recognition is narrow, because a classifier that names the wrong cause is worse
+than one that stays silent.
+
+- **Only the two `...NamedSecurityInfoW` operations are classified.**
+  `SetEntriesInAclW` merges access entries in process memory — there is no
+  object and no rights involved — so its failure is *not* an ACL-permission
+  problem, and neither are the `LocalFree`, `LockFileEx`,
+  `SetConsoleCtrlHandler` or `SetEnvironmentVariableW` failures thrown by the
+  same package.
+- **The Win32 code is kept, not flattened.** `ERROR_ACCESS_DENIED` (5) is the
+  case the documented prerequisite explains; another code gets a different
+  paragraph that says so instead of borrowing the same sentence.
+- **A successful command whose *output* contains the line is not a failure.**
+  The gate is the result's error state, not the presence of the text — reading a
+  log file that quotes the error must not trigger advice.
+- **Only one advisory per agent.** The environment is explained once; repeating
+  it per failed command would be noise competing with the failure itself.
+
+## Honest boundaries
+
+- **The Windows path itself cannot be witnessed on macOS**, where this plugin was
+  built. What the test suite proves is the decision layer — classification, the
+  once-per-agent rule, the fail-fast budget and its self-feeding guard, and the
+  wiring to a real cordis `Context` and the real `ToolRuntime` — driven by
+  fixtures that throw the producer's exact error shape (`Win32Error`,
+  `packages/subprocess/win32-process/src/errors.ts`). It does **not** prove that
+  `icacls ... :(OI)(CI)F` fixes a given machine; that is the user's one-line
+  experiment, and the advisory says so.
+- **It repairs nothing and elevates nothing.** If the directory really is
+  Full-control for the caller, the remaining hypothesis is `SeSecurityPrivilege`
+  — i.e. the backend's documented prerequisite would be wrong. That is an
+  upstream question; the advisory states the discriminator rather than assuming
+  the answer.
+- **Delivery to the model is the agent loop's.** `additionalContexts` are ferried
+  on the settled result here and appended as durable user-role events by
+  `agent-loop`; a direct `ctx.tools.execute()` caller with no agent gets no
+  advisory (and no agent to explain anything to).
+- **It complements `@argszero/cordis-plugin-repeat-guard-escalation`, it does not
+  replace it.** That guard keys on **call identity** (identical arguments
+  retried); this one keys on the **environment signature**, which is how several
+  *different* commands share one cause. Mounting both is sensible.
+- **The real fix is upstream.** `grantWrite` already computes
+  `hasExactGrant` / `hasExactDeny` / `hasExactLabel` and discards which one was
+  false, so the diagnostic that turns a 52-minute detour into one line belongs at
+  that site — next to the preflight the grant's lazy materialization wants.
+
+## Compatibility
+
+Harness peers — all three carry the **same** range, quoted in full on purpose
+(a partially quoted range admits fewer lines than the published one):
+
+- `@deepseek-ai/dsh-llm@>=0.1.2-rc.1 <0.2.0 || >=0.1.3-alpha.2 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-alpha.1 <0.2.0 || >=0.1.7-alpha.1 <0.2.0` — the only **runtime**
+  import: `createUserMessage` and `boundContextSummary`.
+- `@deepseek-ai/dsh-agent@>=0.1.2-rc.1 <0.2.0 || >=0.1.3-alpha.2 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-alpha.1 <0.2.0 || >=0.1.7-alpha.1 <0.2.0` and
+  `@deepseek-ai/dsh-tools@>=0.1.2-rc.1 <0.2.0 || >=0.1.3-alpha.2 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-alpha.1 <0.2.0 || >=0.1.7-alpha.1 <0.2.0` — imported for their **types** only (`Agent`,
+  `ToolExecution`, `PostToolDecision`, …). Nothing is loaded from them at
+  runtime, but the shipped `lib/types/index.d.ts` still names them, so a consumer
+  on a line outside this range fails to typecheck against this package's own
+  declarations; that is a compatibility claim, and it is declared as a peer for
+  that reason.
+- `@deepseek-ai/cordis@^4.0.2`.
+
+Probed at the newest build of every line the range admits — `0.1.2-rc.1`,
+`0.1.3-alpha.2`, `0.1.5-rc.3`, `0.1.6-alpha.2`, `0.1.7-rc.1` (the build the third
+report ran) — with `npm run test:probe-lines`, which derives those builds from
+this range, installs each one from the registry into a scratch tree and runs the
+suite against it. A line whose probe fails is removed from the range rather than
+left claimed.
+
+## Development
+
+```sh
+npm install
+npm test                 # tsc, then the suite (real cordis + real ToolRuntime)
+npm run test:probe-lines # install the newest build of each admitted line and run the suite against it
+npm run test:probe-lines -- 0.1.7-rc.1  # one line only
+```
+
+The suite is mostly control arms: a guard that explains the wrong failure, or
+refuses a call that would have worked, is worse than one that stays silent.
+
+[discussion #7538]: https://github.com/deepseek-ai/deepseek-harness/discussions/7538
+[discussion #7622]: https://github.com/deepseek-ai/deepseek-harness/discussions/7622
+[discussion #7646]: https://github.com/deepseek-ai/deepseek-harness/discussions/7646

package/cordis.patch.yml

@@ -0,0 +1,51 @@
+# The @argszero/cordis-plugin-sandbox-grant-advisor bundle patch: mount and go.
+#
+# Three reports (#7538, #7622, #7646) describe one Windows failure with no way
+# forward: the host-side write grant for a sandboxed workspace cannot be
+# applied, so every sandboxed command fails before it runs with
+#
+#   SetNamedSecurityInfoW failed (Win32 5): grantWrite(<workspace>)
+#
+# The grant is materialized lazily on the first confined call and caches
+# nothing when it throws, so the failure repeats per command (850 calls across
+# 39 sessions in #7622; 52,588 output tokens with no output in #7538). The
+# error names neither the missing right nor a remedy, which is why sessions
+# escape into danger-full-access or die on the model's output cap.
+#
+# This plugin does not repair ACLs. It observes the public
+# `tools/post-execute` waterfall, recognizes that signature (and only that
+# signature — see the README for what it deliberately refuses to explain), and
+# attaches ONE durable user-role advisory per agent through
+# `additionalContexts`, so the model gets the diagnosis in the same step as the
+# failure:
+#
+#   - the missing right is WRITE_OWNER on the directory — an object right the
+#     caller can grant itself, not SeSecurityPrivilege and not elevation
+#     (the manifest half of the merged DACL+SACL write is what needs it);
+#   - the directory's own ACL is the discriminator (`icacls <dir>`, looking for
+#     an ACE that names your SID with (F));
+#   - the remedy is one unelevated line:
+#       icacls "<dir>" /grant "$env:USERNAME:(OI)(CI)F"
+#
+# Optional config:
+#
+#   - set:
+#       - id: sandbox-grant-advisor
+#         config:
+#           # 0 (default) = advisory only: this plugin never blocks a call.
+#           # Set it to enable the bounded fail-fast half: once the environment
+#           # has failed this way N times, an identical call this plugin has
+#           # WATCHED fail is refused before dispatch.
+#           enforceAfter: 0
+#           maxDenials: 2            # then step aside, so the session can finish
+#           exclude: []              # tool-name wildcards never watched
+#           href: ''                 # optional URL quoted in the advisory
+#
+# The advisory half is always on and never blocks anything. The blocking half
+# is off by default on purpose: it may only refuse a call it has watched fail in
+# this environment, and it is bounded by `maxDenials`, because a plugin that can
+# stop command execution must never be the reason a session cannot finish.
+
+- insert:
+    - id: sandbox-grant-advisor
+      name: '@argszero/cordis-plugin-sandbox-grant-advisor'

package/lib/advice.js

@@ -0,0 +1,116 @@
+/**
+ * What the model — and through it the user — is told about a provisioning
+ * failure, and what is deliberately withheld.
+ *
+ * The text is assembled here as pure functions so every sentence can be pinned
+ * by a test. Two properties matter more than the wording:
+ *
+ * - **It names the right the caller is missing.** The reported failures are
+ *   `ERROR_ACCESS_DENIED` from a *merged* DACL + SACL write. The missing right
+ *   is `WRITE_OWNER` on the directory — an object right the caller can grant
+ *   itself with `icacls`, unelevated. It is **not** `SeSecurityPrivilege`, the
+ *   token privilege the reports naturally reach for; `whoami /priv` cannot show
+ *   the difference, and elevation is the wrong lever.
+ * - **It gives a discriminator, not just a remedy.** Applying a fix without
+ *   confirming the cause teaches nothing when the fix does not work. The
+ *   one-line check (`icacls <dir>`, looking for an ACE that names the caller's
+ *   own SID and grants `(F)`) separates "Modify-only directory" from "the
+ *   documented prerequisite is wrong", which is the open question upstream.
+ *
+ * @module
+ */
+import { failureLine } from './signature.js';
+/** The upstream threads this advisory is a stopgap for. */
+export const DISCUSSIONS = '#7538 / #7622 / #7646';
+/** The documented prerequisite, quoted from the backend's README. */
+export const PREREQUISITE = 'granted directories must be caller-owned and grant `WRITE_OWNER`';
+/** Placeholder the user replaces with the directory the error named. */
+const PLACEHOLDER = '<the directory from the error line above>';
+/**
+ * The diagnosis paragraph for one class of failure.
+ * @param failure - the recognized failure.
+ * @returns one paragraph, honest about what is and is not known.
+ */
+function diagnosis(failure) {
+    switch (failure.klass) {
+        case 'apply-denied':
+            return [
+                'Why it is refused while the directory looks writable: that call is a MERGED write — the DACL and the',
+                'mandatory-integrity label go out as one `SetNamedSecurityInfoW`. The label lives in the SACL, and the',
+                "owner's implicit rights cover only READ_CONTROL and WRITE_DAC, so the label half additionally needs",
+                'WRITE_OWNER on the directory. A workspace created with `mkdir` normally inherits',
+                '"Authenticated Users: Modify" (`0x1301bf`) from the drive root — and that mask has neither right.',
+                'This is a directory ACL fact, not a token privilege: `whoami /priv` will not show it, and',
+                'SeSecurityPrivilege is the wrong lever here.',
+            ].join('\n');
+        case 'read-denied':
+            return [
+                'Why it is refused: the harness could not even read the directory\'s security descriptor, so the grant',
+                'never got as far as writing one. That read wants READ_CONTROL, which the directory is not granting this',
+                'account either.',
+            ].join('\n');
+        case 'apply-other':
+            return [
+                'Why it is refused: this is the same merged write, but the Win32 code is not ERROR_ACCESS_DENIED (5), so',
+                'the missing-rights story above does not apply verbatim — a missing path, a non-directory target, or a',
+                'filesystem that does not carry ACLs are all possibilities. The one-line fix below is safe to try; if the',
+                'code persists, it is a different failure and worth reporting with the code.',
+            ].join('\n');
+    }
+}
+/**
+ * Build the advisory attached to the failing tool result.
+ * @param failure - the recognized failure.
+ * @param href - optional URL shown for the upstream thread.
+ * @returns the user-role notice text, with the fix commands ready to paste.
+ */
+export function advisoryText(failure, href) {
+    const path = failure.path ?? PLACEHOLDER;
+    const where = href === undefined ? `tracked upstream (discussions ${DISCUSSIONS})` : `tracked upstream: ${href}`;
+    return [
+        'Sandbox provisioning failed — no sandboxed command can run in this workspace until its ACL applies.',
+        '',
+        'What was reported:',
+        `  ${failureLine(failure)}`,
+        '',
+        diagnosis(failure),
+        '',
+        'Confirm the cause (unelevated) — `icacls` is a normal user command:',
+        `  icacls "${path}"`,
+        'Look for an ACE that names YOUR OWN account (run `whoami` if unsure) with (F) / Full control.',
+        'If the strongest entry naming you is (M) / Modify, that is this failure.',
+        '',
+        'Fix it (unelevated, one line) and then run the command again:',
+        `  PowerShell: icacls "${path}" /grant "$env:USERNAME:(OI)(CI)F"`,
+        `  cmd:        icacls "${path}" /grant "%USERNAME%:(OI)(CI)F"`,
+        '',
+        'How to read this: the harness documents the prerequisite (' + PREREQUISITE + ') and this',
+        'error does not name it yet, so the advice is delivered here instead. This is a stopgap, ' + where + '.',
+        'What it is NOT: this plugin neither edits ACLs nor elevates — the command above is yours to run.',
+        'Your file read/write tools still work; only sandboxed command execution is blocked.',
+    ].join('\n');
+}
+/**
+ * Build the pre-dispatch denial for the optional fail-fast half.
+ * @param failure - the recognized failure.
+ * @param observed - how many provisioning failures this agent has produced.
+ * @param denial - this denial's 1-based ordinal.
+ * @param maxDenials - the denial budget.
+ * @returns the corrective text the model receives in place of a tool result.
+ */
+export function denialText(failure, observed, denial, maxDenials) {
+    const suffix = maxDenials - denial;
+    return [
+        `Blocked by sandbox-grant-advisor: this exact call has already failed ${String(observed)} times with the`,
+        'same workspace-provisioning error, and the environment has not changed since:',
+        `  ${failureLine(failure)}`,
+        '',
+        'Retrying cannot succeed — the sandbox cannot start a command until the directory grant applies.',
+        'Stop, and either apply the fix or hand the problem to the user:',
+        failure.path === undefined ? '' : `  icacls "${failure.path}" /grant "$env:USERNAME:(OI)(CI)F"`,
+        '',
+        suffix > 0
+            ? `This is automatic block ${String(denial)} of ${String(maxDenials)}; after that the call is allowed again.`
+            : `This is automatic block ${String(denial)} of ${String(maxDenials)} — the last one; further identical calls are allowed again.`,
+    ].filter(line => line !== '').join('\n');
+}

package/lib/index.js

@@ -0,0 +1,285 @@
+/**
+ * `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.
+ *
+ * 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:
+ *
+ *   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
+ * `danger-full-access` or die on the model's output cap.
+ *
+ * ## 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
+ * 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.
+ *
+ * ## 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.
+ *
+ * ## 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`.
+ * - **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.
+ * - **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
+ *   `hasExactGrant`/`hasExactDeny`/`hasExactLabel` and discards which was
+ *   false). This plugin is the stopgap.
+ *
+ * @module @argszero/cordis-plugin-sandbox-grant-advisor
+ */
+import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm';
+import { advisoryText, denialText, DISCUSSIONS } from './advice.js';
+import { classifyProvisioningFailure } from './signature.js';
+import { callKey, observe, observeSuccess, recordAdvice, recordDenial, shouldDeny } from './state.js';
+export const name = 'sandbox-grant-advisor';
+/** The tool pipeline this plugin observes and (optionally) gates. */
+export const inject = ['tools'];
+/**
+ * The producer kind every message this plugin writes carries.
+ *
+ * It is deliberately its own kind rather than the retired `plugin` wrapper: the
+ * current session format admits only a producer-owned kind — a message whose
+ * `source.kind` is the string `plugin` is refused on the way in
+ * (`packages/session/session-format-v3-to-v4/src/message-sources.ts`) — and the
+ * source union is documented as merge-extensible, one kind per producer.
+ */
+export const SOURCE_KIND = 'sandbox-grant-advisor';
+/** Default fail-fast threshold: 0, i.e. the blocking half is off. */
+export const DEFAULT_ENFORCE_AFTER = 0;
+/** Default denial budget once the blocking half is enabled. */
+export const DEFAULT_MAX_DENIALS = 2;
+/** Compile one `*`-wildcard pattern to an anchored RegExp; all else is literal. */
+function wildcardToRegExp(pattern) {
+    const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, String.raw `\$&`);
+    return new RegExp(`^${escaped.replaceAll('*', '.*')}$`);
+}
+/**
+ * Validate a count-like option fail-loud, so a typo cannot silently disable the
+ * blocking half the operator asked for.
+ * @param label - the option name, for the message.
+ * @param value - the resolved value.
+ * @param minimum - the smallest legal value.
+ * @returns the value, once validated.
+ */
+function integerAtLeast(label, value, minimum) {
+    if (!Number.isInteger(value) || value < minimum) {
+        throw new Error(`sandbox-grant-advisor: \`${label}\` must be an integer >= ${minimum} (got ${String(value)})`);
+    }
+    return value;
+}
+/**
+ * The plain text of a failed result, from the authoritative field first.
+ *
+ * `error.message` is what the producing layer recorded and survives content
+ * rewriting by other post-execute listeners; the rendered text is the fallback,
+ * so a result whose content was replaced (spill policies, hooks) is still
+ * classified from its message.
+ * @param result - the failed tool result.
+ * @returns the text to classify.
+ */
+function failureText(result) {
+    const rendered = result.content
+        .filter(block => block.type === 'text')
+        .map(block => block.text)
+        .join('\n');
+    return result.error.message.length > 0 ? `${result.error.message}\n${rendered}` : rendered;
+}
+/**
+ * The one-line host-side account of a recognized failure.
+ * @param failure - the recognized failure.
+ * @returns a single log line.
+ */
+function hostLine(failure) {
+    const where = failure.detail.length === 0 ? '' : ` at ${failure.detail}`;
+    return `sandbox-grant-advisor: workspace ACL provisioning failed (${failure.api} Win32 `
+        + `${String(failure.win32Code)})${where} — sandboxed commands will keep failing until the directory grants `
+        + `this account Full control; advisory delivered to the model (discussions ${DISCUSSIONS})`;
+}
+/**
+ * Wrap one notice as a user-role message.
+ *
+ * The double cast encodes a documented fact the installed type cannot express:
+ * the message source union is **merge-extensible** — "each producer declares its
+ * own `kind` in its own module; there is no shared catch-all `plugin` kind", and
+ * "consumers fall through unknown kinds" — while the union shipped in the peer
+ * package is a closed list written before this producer existed. A plugin cannot
+ * augment an interface it does not own, and the session format admits any
+ * non-empty kind except the retired `plugin` wrapper
+ * (`packages/session/session-format-v3-to-v4/src/message-sources.ts`), which is
+ * asserted by `test/plugin.spec.mjs` against the message this function returns.
+ * @param text - the notice body.
+ * @param summary - one-line account for the transcript row.
+ * @returns the message, identified and frozen by the harness factory.
+ */
+function notice(text, summary) {
+    return createUserMessage({
+        content: [{ type: 'text', text }],
+        source: {
+            kind: SOURCE_KIND,
+            form: 'notice',
+            summary: boundContextSummary(summary),
+        },
+    });
+}
+/** Keep this plugin's notices ahead of any other context on the same result. */
+function prepend(ours, theirs) {
+    return [ours, ...theirs ?? []];
+}
+/**
+ * Install the advisor.
+ * @param ctx - context carrying the tool pipeline.
+ * @param config - resolved options; validated fail-loud here.
+ */
+export function apply(ctx, config = {}) {
+    const enforceAfter = integerAtLeast('enforceAfter', config.enforceAfter ?? DEFAULT_ENFORCE_AFTER, 0);
+    const maxDenials = integerAtLeast('maxDenials', config.maxDenials ?? DEFAULT_MAX_DENIALS, 1);
+    const includePatterns = (config.include ?? []).map(wildcardToRegExp);
+    const excludePatterns = (config.exclude ?? []).map(wildcardToRegExp);
+    const href = config.href;
+    /** One state per agent; a WeakMap keeps a finished agent's state collectable. */
+    const states = new WeakMap();
+    /**
+     * The executions this plugin denied, so the post-execute listener never reads
+     * its own denial as an environment failure. A denial's text quotes the Win32
+     * line on purpose (that is what the model must see), which makes it
+     * indistinguishable from the real thing by content alone — the identity of
+     * the execution object, shared by reference across both seams, is what
+     * separates them.
+     */
+    const ownDenials = new WeakSet();
+    /** Whether a tool participates; untracked calls are transparent. */
+    function tracked(toolName) {
+        if (includePatterns.length > 0 && !includePatterns.some(pattern => pattern.test(toolName)))
+            return false;
+        return !excludePatterns.some(pattern => pattern.test(toolName));
+    }
+    /**
+     * Read one settled call: advance the state, and decide whether it is the
+     * failure the model needs told about.
+     * @param exec - the call that just ran.
+     * @param result - its settled outcome.
+     * @returns the notice to attach, or undefined.
+     */
+    function inspect(exec, result) {
+        const agent = exec.agent;
+        if (agent === undefined || !tracked(exec.name))
+            return undefined;
+        if (ownDenials.has(exec)) {
+            ownDenials.delete(exec);
+            return undefined;
+        }
+        const key = callKey(exec.name, exec.arguments);
+        const previous = states.get(agent);
+        if (result.isError !== true) {
+            if (previous !== undefined)
+                states.set(agent, observeSuccess(previous, key));
+            return undefined;
+        }
+        const failure = classifyProvisioningFailure(failureText(result));
+        if (failure === undefined)
+            return undefined;
+        const advanced = observe(previous, failure, key);
+        if (advanced.advised) {
+            states.set(agent, advanced);
+            return undefined;
+        }
+        states.set(agent, recordAdvice(advanced));
+        ctx.logger.warn(hostLine(failure));
+        return notice(advisoryText(failure, href), `workspace ACL provisioning failed (Win32 ${String(failure.win32Code)})`);
+    }
+    // Observe-and-enrich, never veto by itself: delegate first, then fold this
+    // plugin's notice onto whatever came back. `additionalContexts` rides both
+    // decision variants, so a result another listener blocked still carries the
+    // diagnosis.
+    ctx.on('tools/post-execute', async (exec, result, next) => {
+        let message;
+        try {
+            message = inspect(exec, result);
+        }
+        catch (error) {
+            // A broken advisor must not become a broken tool call.
+            ctx.logger.warn(`sandbox-grant-advisor: result left alone after internal error: ${String(error)}`);
+        }
+        const downstream = await next();
+        if (message === undefined)
+            return downstream;
+        if (downstream.kind === 'block') {
+            return {
+                kind: 'block',
+                feedback: downstream.feedback,
+                additionalContexts: prepend(message, downstream.additionalContexts),
+            };
+        }
+        return { ...downstream, additionalContexts: prepend(message, downstream.additionalContexts) };
+    });
+    // The optional blocking half. Registered only when asked for: with the default
+    // `enforceAfter: 0` this plugin never sits in a waterfall it can veto from.
+    if (enforceAfter === 0)
+        return;
+    ctx.on('tools/pre-execute', (exec, next) => {
+        try {
+            const agent = exec.agent;
+            if (agent === undefined || !tracked(exec.name))
+                return next();
+            const state = states.get(agent);
+            if (!shouldDeny(state, callKey(exec.name, exec.arguments), enforceAfter, maxDenials))
+                return next();
+            if (state === undefined)
+                return next();
+            // Tag before delegating, and spend the budget immediately: the denial must
+            // be accounted for even if a later listener replaces this decision.
+            ownDenials.add(exec);
+            states.set(agent, recordDenial(state));
+            return Promise.resolve({
+                kind: 'deny',
+                reason: denialText(state.last, state.observations, state.denials + 1, maxDenials),
+            });
+        }
+        catch (error) {
+            ctx.logger.warn(`sandbox-grant-advisor: call allowed after internal error: ${String(error)}`);
+            return next();
+        }
+    });
+}

package/lib/signature.js

@@ -0,0 +1,81 @@
+/**
+ * Recognize the Windows ACL provisioning failure that has no path forward.
+ *
+ * The harness's Windows sandbox provisions a workspace by writing the
+ * directory's DACL and its mandatory-integrity label in **one**
+ * `SetNamedSecurityInfoW` call (`packages/sandbox/sandbox-windows-acl/src/acl.ts`).
+ * When that call is refused, the error a session actually sees is the bare
+ * Win32 string — `SetNamedSecurityInfoW failed (Win32 5): grantWrite(D:\ws)` —
+ * with no statement of which right was missing or what the caller can do about
+ * 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
+ * recognition is deliberately narrow:
+ *
+ * - **Only the two `...NamedSecurityInfoW` operations are classified.** Their
+ *   failures are the provisioning path. `SetEntriesInAclW` merges entries in
+ *   process memory (no object, no rights), and the `LocalFree` /
+ *   `SetConsoleCtrlHandler` / `LockFileEx` failures in the same package are
+ *   allocation or lock errors — advising an ACL fix for any of those would send
+ *   a user to change the wrong thing. A classifier that names a wrong cause is
+ *   worse than one that stays silent.
+ * - **The Win32 code is kept, not flattened.** `ERROR_ACCESS_DENIED` (5) is the
+ *   case the documented prerequisite explains; another code is a different
+ *   story and the advisory says so instead of borrowing the same sentence.
+ * - **The producer's detail is preserved verbatim** (`grantWrite(D:\ws)`), so
+ *   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.
+ *
+ * @module
+ */
+/**
+ * The producer's format is fixed by `Win32Error`
+ * (`packages/subprocess/win32-process/src/errors.ts`):
+ * `` `${api} failed (Win32 ${code})${detail ? `: ${detail}` : ''}` ``.
+ * The pattern is written against that shape, but it is anchored on the API
+ * names rather than on surrounding text, so it survives the `Error: ` envelope
+ * a tool result adds and any prefix a provider wraps around it.
+ */
+const SIGNATURE = /\b(SetNamedSecurityInfoW|GetNamedSecurityInfoW) failed \(Win32 (\d+)\)(?:: *([^\r\n]*))?/;
+/** `ERROR_ACCESS_DENIED`. */
+const ACCESS_DENIED = 5;
+/** Split the producer's `label(path)` detail; any other shape yields nothing. */
+function splitDetail(detail) {
+    const match = /^([A-Za-z][A-Za-z0-9_-]*)\((.*)\)$/.exec(detail.trim());
+    if (match === null)
+        return {};
+    const label = match[1];
+    const path = match[2];
+    if (label === undefined || path === undefined)
+        return {};
+    return { label, path };
+}
+/**
+ * Classify one failure message.
+ * @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 function classifyProvisioningFailure(message) {
+    const match = SIGNATURE.exec(message);
+    if (match === null)
+        return undefined;
+    const api = match[1];
+    const code = Number(match[2]);
+    if (api === undefined || !Number.isInteger(code))
+        return undefined;
+    const detail = (match[3] ?? '').trim();
+    const klass = api === 'GetNamedSecurityInfoW'
+        ? 'read-denied'
+        : code === ACCESS_DENIED ? 'apply-denied' : 'apply-other';
+    return { klass, api, win32Code: code, detail, ...splitDetail(detail) };
+}
+/**
+ * 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.
+ */
+export function failureLine(failure) {
+    const suffix = failure.detail.length === 0 ? '' : `: ${failure.detail}`;
+    return `${failure.api} failed (Win32 ${failure.win32Code})${suffix}`;
+}

package/lib/state.js

@@ -0,0 +1,145 @@
+/**
+ * Per-agent bookkeeping: what this environment has already been told, and (in
+ * the optional fail-fast half) which calls have already been refused by it.
+ *
+ * The state is deliberately keyed by **agent**, not by session id string: the
+ * 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:
+ *
+ * - `observations` counts *provisioning failures of this environment*, 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.
+ * - `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.
+ *
+ * @module
+ */
+/**
+ * Canonicalize a parsed argument value into a stable string.
+ *
+ * Key order in a JavaScript object is insertion order, so two structurally
+ * identical calls can serialize differently depending on how the model ordered
+ * its JSON. Sorting keys recursively gives the identity the fail-fast half
+ * needs; unsupported values (functions, symbols, cycles) fall back to a type
+ * tag rather than throwing, because a guard must never be the reason a call
+ * dies.
+ * @param value - the parsed tool arguments.
+ * @returns a stable string.
+ */
+export function canonicalize(value) {
+    const seen = new WeakSet();
+    const walk = (node, depth) => {
+        if (depth > 32)
+            return '<depth>';
+        if (node === null || typeof node !== 'object') {
+            return typeof node === 'bigint' ? `${node.toString()}n` : node;
+        }
+        if (seen.has(node))
+            return '<cycle>';
+        seen.add(node);
+        if (Array.isArray(node))
+            return node.map(item => walk(item, depth + 1));
+        const entries = Object.entries(node)
+            .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+            .map(([key, item]) => [key, walk(item, depth + 1)]);
+        return Object.fromEntries(entries);
+    };
+    return JSON.stringify(walk(value, 0)) ?? '<unserializable>';
+}
+/**
+ * The identity of one call: its tool name plus its canonical arguments.
+ * @param name - the tool name.
+ * @param args - the parsed arguments.
+ * @returns the identity key.
+ */
+export function callKey(name, args) {
+    return `${name}(${canonicalize(args)})`;
+}
+/**
+ * Record one observed provisioning failure.
+ * @param state - the agent's current state, or undefined on first sight.
+ * @param failure - the recognized failure.
+ * @param key - the identity of the call that failed.
+ * @returns the updated state.
+ */
+export function observe(state, failure, key) {
+    const failingKeys = new Set(state?.failingKeys ?? []);
+    failingKeys.add(key);
+    return {
+        observations: (state?.observations ?? 0) + 1,
+        last: failure,
+        failingKeys,
+        denials: state?.denials ?? 0,
+        advised: state?.advised ?? false,
+    };
+}
+/**
+ * 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.
+ *
+ * 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.
+ * @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.
+ */
+export function observeSuccess(state, key) {
+    if (!state.failingKeys.has(key))
+        return state;
+    const failingKeys = new Set(state.failingKeys);
+    failingKeys.delete(key);
+    return { ...state, failingKeys, denials: 0 };
+}
+/**
+ * Whether a call may be refused before dispatch.
+ *
+ * Both conditions are required: the environment has failed provisioning at
+ * least `enforceAfter` times, **and** this exact call is one this plugin watched
+ * 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.
+ * @param state - the agent's current state, or undefined.
+ * @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 function shouldDeny(state, key, enforceAfter, maxDenials) {
+    if (enforceAfter === 0 || state === undefined)
+        return false;
+    if (state.observations < enforceAfter)
+        return false;
+    if (state.denials >= maxDenials)
+        return false;
+    return state.failingKeys.has(key);
+}
+/**
+ * Spend one denial.
+ * @param state - the agent's current state.
+ * @returns the updated state.
+ */
+export function recordDenial(state) {
+    return { ...state, denials: state.denials + 1 };
+}
+/**
+ * Mark the durable advisory as delivered.
+ * @param state - the agent's current state.
+ * @returns the updated state.
+ */
+export function recordAdvice(state) {
+    return { ...state, advised: true };
+}

package/lib/types/advice.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What the model — and through it the user — is told about a provisioning
+ * failure, and what is deliberately withheld.
+ *
+ * The text is assembled here as pure functions so every sentence can be pinned
+ * by a test. Two properties matter more than the wording:
+ *
+ * - **It names the right the caller is missing.** The reported failures are
+ *   `ERROR_ACCESS_DENIED` from a *merged* DACL + SACL write. The missing right
+ *   is `WRITE_OWNER` on the directory — an object right the caller can grant
+ *   itself with `icacls`, unelevated. It is **not** `SeSecurityPrivilege`, the
+ *   token privilege the reports naturally reach for; `whoami /priv` cannot show
+ *   the difference, and elevation is the wrong lever.
+ * - **It gives a discriminator, not just a remedy.** Applying a fix without
+ *   confirming the cause teaches nothing when the fix does not work. The
+ *   one-line check (`icacls <dir>`, looking for an ACE that names the caller's
+ *   own SID and grants `(F)`) separates "Modify-only directory" from "the
+ *   documented prerequisite is wrong", which is the open question upstream.
+ *
+ * @module
+ */
+import type { ProvisioningFailure } from './signature.js';
+/** The upstream threads this advisory is a stopgap for. */
+export declare const DISCUSSIONS = "#7538 / #7622 / #7646";
+/** The documented prerequisite, quoted from the backend's README. */
+export declare const PREREQUISITE = "granted directories must be caller-owned and grant `WRITE_OWNER`";
+/**
+ * Build the advisory attached to the failing tool result.
+ * @param failure - the recognized failure.
+ * @param href - optional URL shown for the upstream thread.
+ * @returns the user-role notice text, with the fix commands ready to paste.
+ */
+export declare function advisoryText(failure: ProvisioningFailure, href?: string): string;
+/**
+ * Build the pre-dispatch denial for the optional fail-fast half.
+ * @param failure - the recognized failure.
+ * @param observed - how many provisioning failures this agent has produced.
+ * @param denial - this denial's 1-based ordinal.
+ * @param maxDenials - the denial budget.
+ * @returns the corrective text the model receives in place of a tool result.
+ */
+export declare function denialText(failure: ProvisioningFailure, observed: number, denial: number, maxDenials: number): string;

package/lib/types/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `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.
+ *
+ * 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:
+ *
+ *   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
+ * `danger-full-access` or die on the model's output cap.
+ *
+ * ## 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
+ * 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.
+ *
+ * ## 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.
+ *
+ * ## 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`.
+ * - **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.
+ * - **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
+ *   `hasExactGrant`/`hasExactDeny`/`hasExactLabel` and discards which was
+ *   false). This plugin is the stopgap.
+ *
+ * @module @argszero/cordis-plugin-sandbox-grant-advisor
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "sandbox-grant-advisor";
+/** The tool pipeline this plugin observes and (optionally) gates. */
+export declare const inject: string[];
+/**
+ * The producer kind every message this plugin writes carries.
+ *
+ * It is deliberately its own kind rather than the retired `plugin` wrapper: the
+ * current session format admits only a producer-owned kind — a message whose
+ * `source.kind` is the string `plugin` is refused on the way in
+ * (`packages/session/session-format-v3-to-v4/src/message-sources.ts`) — and the
+ * source union is documented as merge-extensible, one kind per producer.
+ */
+export declare const SOURCE_KIND = "sandbox-grant-advisor";
+/** Default fail-fast threshold: 0, i.e. the blocking half is off. */
+export declare const DEFAULT_ENFORCE_AFTER = 0;
+/** Default denial budget once the blocking half is enabled. */
+export declare const DEFAULT_MAX_DENIALS = 2;
+/** Configures what is watched and whether the blocking half runs. */
+export interface Config {
+    /**
+     * 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.
+     */
+    enforceAfter?: number;
+    /**
+     * How many denials one agent may spend. Defaults to 2. Bounded on purpose:
+     * an unbounded refusal turns a stuck session into an unfinishable one.
+     */
+    maxDenials?: number;
+    /** Tool-name wildcard patterns to watch; empty means every tool. */
+    include?: string[];
+    /** Tool-name wildcard patterns never watched. */
+    exclude?: string[];
+    /** URL quoted in the advisory as the upstream thread; optional. */
+    href?: string;
+}
+/**
+ * Install the advisor.
+ * @param ctx - context carrying the tool pipeline.
+ * @param config - resolved options; validated fail-loud here.
+ */
+export declare function apply(ctx: Context, config?: Config): void;

package/lib/types/signature.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Recognize the Windows ACL provisioning failure that has no path forward.
+ *
+ * The harness's Windows sandbox provisions a workspace by writing the
+ * directory's DACL and its mandatory-integrity label in **one**
+ * `SetNamedSecurityInfoW` call (`packages/sandbox/sandbox-windows-acl/src/acl.ts`).
+ * When that call is refused, the error a session actually sees is the bare
+ * Win32 string — `SetNamedSecurityInfoW failed (Win32 5): grantWrite(D:\ws)` —
+ * with no statement of which right was missing or what the caller can do about
+ * 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
+ * recognition is deliberately narrow:
+ *
+ * - **Only the two `...NamedSecurityInfoW` operations are classified.** Their
+ *   failures are the provisioning path. `SetEntriesInAclW` merges entries in
+ *   process memory (no object, no rights), and the `LocalFree` /
+ *   `SetConsoleCtrlHandler` / `LockFileEx` failures in the same package are
+ *   allocation or lock errors — advising an ACL fix for any of those would send
+ *   a user to change the wrong thing. A classifier that names a wrong cause is
+ *   worse than one that stays silent.
+ * - **The Win32 code is kept, not flattened.** `ERROR_ACCESS_DENIED` (5) is the
+ *   case the documented prerequisite explains; another code is a different
+ *   story and the advisory says so instead of borrowing the same sentence.
+ * - **The producer's detail is preserved verbatim** (`grantWrite(D:\ws)`), so
+ *   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.
+ *
+ * @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. */
+'apply-denied'
+/** `SetNamedSecurityInfoW` failed with a Win32 code other than `ERROR_ACCESS_DENIED`. */
+ | 'apply-other'
+/** `GetNamedSecurityInfoW` failed: the security descriptor could not even be read. */
+ | 'read-denied';
+/** One recognized provisioning failure, with the producer's own fields kept. */
+export interface ProvisioningFailure {
+    /** Which diagnosis follows from the api/code pair. */
+    readonly klass: FailureClass;
+    /** The API whose checked result failed, exactly as the producer names it. */
+    readonly api: string;
+    /** The Win32 error code as reported. */
+    readonly win32Code: number;
+    /** The producer's detail, e.g. `grantWrite(D:\ws)`; empty when it supplied none. */
+    readonly detail: string;
+    /** The detail's `label(...)` head, when it has that shape. */
+    readonly label?: string;
+    /** The directory the detail names, when it has that shape. */
+    readonly path?: string;
+}
+/**
+ * Classify one failure message.
+ * @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;
+/**
+ * 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.
+ */
+export declare function failureLine(failure: ProvisioningFailure): string;

package/lib/types/state.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Per-agent bookkeeping: what this environment has already been told, and (in
+ * the optional fail-fast half) which calls have already been refused by it.
+ *
+ * The state is deliberately keyed by **agent**, not by session id string: the
+ * 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:
+ *
+ * - `observations` counts *provisioning failures of this environment*, 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.
+ * - `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.
+ *
+ * @module
+ */
+import type { ProvisioningFailure } from './signature.js';
+/** Everything the plugin remembers about one agent. */
+export interface AgentState {
+    /** Provisioning failures observed for this agent. */
+    observations: number;
+    /** The most recent failure, for the denial text. */
+    last: ProvisioningFailure;
+    /** 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. */
+    advised: boolean;
+}
+/**
+ * Canonicalize a parsed argument value into a stable string.
+ *
+ * Key order in a JavaScript object is insertion order, so two structurally
+ * identical calls can serialize differently depending on how the model ordered
+ * its JSON. Sorting keys recursively gives the identity the fail-fast half
+ * needs; unsupported values (functions, symbols, cycles) fall back to a type
+ * tag rather than throwing, because a guard must never be the reason a call
+ * dies.
+ * @param value - the parsed tool arguments.
+ * @returns a stable string.
+ */
+export declare function canonicalize(value: unknown): string;
+/**
+ * The identity of one call: its tool name plus its canonical arguments.
+ * @param name - the tool name.
+ * @param args - the parsed arguments.
+ * @returns the identity key.
+ */
+export declare function callKey(name: string, args: unknown): string;
+/**
+ * Record one observed provisioning failure.
+ * @param state - the agent's current state, or undefined on first sight.
+ * @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;
+/**
+ * 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.
+ *
+ * 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.
+ * @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.
+ */
+export declare function observeSuccess(state: AgentState, key: string): AgentState;
+/**
+ * Whether a call may be refused before dispatch.
+ *
+ * Both conditions are required: the environment has failed provisioning at
+ * least `enforceAfter` times, **and** this exact call is one this plugin watched
+ * 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.
+ * @param state - the agent's current state, or undefined.
+ * @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;
+/**
+ * Spend one denial.
+ * @param state - the agent's current state.
+ * @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;

package/package.json

@@ -0,0 +1,75 @@
+{
+  "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",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/argszero/cordis-plugin-sandbox-grant-advisor.git"
+  },
+  "homepage": "https://github.com/argszero/cordis-plugin-sandbox-grant-advisor#readme",
+  "bugs": {
+    "url": "https://github.com/argszero/cordis-plugin-sandbox-grant-advisor/issues"
+  },
+  "keywords": [
+    "cordis",
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "sandbox",
+    "windows",
+    "acl",
+    "win32",
+    "diagnostics",
+    "guard"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": ">=0.1.2-rc.1 <0.2.0 || >=0.1.3-alpha.2 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-alpha.1 <0.2.0 || >=0.1.7-alpha.1 <0.2.0",
+    "@deepseek-ai/dsh-llm": ">=0.1.2-rc.1 <0.2.0 || >=0.1.3-alpha.2 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-alpha.1 <0.2.0 || >=0.1.7-alpha.1 <0.2.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0 || >=0.1.3-alpha.2 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-alpha.1 <0.2.0 || >=0.1.7-alpha.1 <0.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.1",
+    "@types/node": "^22.10.2",
+    "semver": "^7.6.0",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "pretest": "tsc",
+    "test": "node --test \"test/*.spec.mjs\"",
+    "test:probe-lines": "node scripts/probe-lines.mjs",
+    "prepublishOnly": "tsc"
+  },
+  "engines": {
+    "node": "^22.19 || >=24"
+  }
+}