@argszero/cordis-plugin-sandbox-grant-advisor 0.9.1 → 0.11.0

package/lib/index.js

@@ -2,7 +2,7 @@
  * `sandbox-grant-advisor`: turn an environment failure that has no path forward
  * into a diagnosis the model — and the user reading the transcript — can act on.
  *
- * ## The three failures it recognizes
+ * ## The four 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
@@ -68,6 +68,26 @@
  * tool's own canonical output, never a line of rendered text — and which three
  * narrowings keep the recognition from firing on something else.
  *
+ * **Denied inside the workspace (Windows ACL, `#423`).** The fourth family is
+ * the other half of the backend the first one explains, and it is the first
+ * whose remedy is withheld on purpose. There the grant could not be applied at
+ * all; here it *was* applied — on the workspace root, once — and Windows ACE
+ * inheritance silently skipped objects whose DACL the caller could not write.
+ * The backend's provisioning check short-circuits on the root (`hasExactGrant`
+ * returns early once the root carries the ACE, `sandbox-windows-acl/src/acl.ts`),
+ * so those descendants are never revisited and the same command fails forever,
+ * while a directory the harness itself created works. It arrives at the same
+ * seam as the native-init family and for the same structural reason: a denied
+ * command exits nonzero and the shipped shell tools report that as a finished
+ * run, so the fact is in `ToolExecutionSuccess.value` rather than in an error.
+ * Unlike that family it needs no bespoke code — the executors stamp the denial
+ * onto the value as a structured triple (`sandbox: { mode, denied, enforcement? }`,
+ * produced by matching the backend's own refusal dialect in the captured
+ * stderr), so this plugin reads the harness's own reading of its own sandbox.
+ * See `src/signature.ts` for the facts that narrow it, and in particular for
+ * why a denial is the *designed* outcome in three other situations (outside the
+ * workspace, under `read-only`, a runner failure) and must never be advised.
+ *
  * ## Where it acts, and why there
  *
  * One listener on the public `tools/post-execute` waterfall
@@ -107,9 +127,15 @@
  *    packaged desktop binary, which the plugin **measures and reports** rather
  *    than assumes), and carries the one conversion a model can actually make —
  *    rewrite the work as PowerShell or `cmd` when the program that could not
- *    start was an MSYS2 one. All three ride `additionalContexts`, so the model
- *    sees the diagnosis beside the failure rather than only in a log it never
- *    reads.
+ *    start was an MSYS2 one. For the workspace-denial family it prints the path
+ *    it keyed on beside the root it tested it against, says that retrying is
+ *    provably useless (the root-only provisioning check never revisits the
+ *    object), gives the two-sided reachability rule, names the label variant of
+ *    the same shape, and prints **no** repair command — the obvious one is
+ *    refused by Windows with `ERROR_NONE_MAPPED (1332)`, and this project has no
+ *    Windows host to verify a line on. All four 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
@@ -121,8 +147,13 @@
  *    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.
+ *    says so once**. The workspace-denial advisory is withheld the same way when
+ *    the workspace root — the fact the containment claim is tested against —
+ *    cannot be resolved. Silence alone would make "the sandbox is not the cause" and
+ *    "this plugin could not tell" indistinguishable from the outside. A denial
+ *    the classifier *can* place outside the workspace is a different case and is
+ *    left silent on purpose: that is the sanctioned escalation path, not a
+ *    puzzle, and a note about it would be noise.
  *
  * ## Honest boundaries
  *
@@ -139,7 +170,10 @@
  *   tools' own foreground projection with the reported codes, including the
  *   signed form the reporter saw (`-1073741502`) and the real MSYS2 stderr, so the
  *   recognition runs against the producer's data rather than against a message
- *   this plugin invented.
+ *   this plugin invented. The workspace-denial family is exercised the same way:
+ *   the test builds the executors' own `sandbox` stamp and the shipped foreground
+ *   projection, supplies `win32` as the platform fact, and covers both the
+ *   recognized case and each of the narrowings that must stay silent.
  * - **It does not repair anything.** No ACL is written, no privilege is
  *   requested, nothing is elevated, no environment variable is set for another
  *   process, no preset is installed and no mode is changed: the remedies are the
@@ -148,7 +182,7 @@
  *   guard keys on *call identity* (identical arguments retried); this one keys
  *   on the *environment signature*, which is how several different commands can
  *   share one cause. They can be mounted together.
- * - **The real fix is upstream**, in all three families: the ACL failure should
+ * - **The real fix is upstream**, in all four families: the ACL failure should
  *   name
  *   the outstanding condition at the site that knows it (`grantWrite` computes
  *   `hasExactGrant`/`hasExactDeny`/`hasExactLabel` and discards which was
@@ -156,14 +190,19 @@
  *   incompatible with the PTY backend" or fall back to a one-shot shell, and the
  *   sandbox runner should be launched with the environment its own execution
  *   needs (`ELECTRON_RUN_AS_NODE` when argv[0] is an Electron binary) or with a
- *   documented, checkable refusal for MSYS2 programs. This plugin is the stopgap.
+ *   documented, checkable refusal for MSYS2 programs. The workspace-denial family
+ *   is the same shape once more: `grantWrite` returns early when the *root*
+ *   already carries the ACE, so the descendants that missed the propagation are
+ *   never repaired — the check would have to look past the root, or the denial
+ *   surface would have to say *which* path was refused instead of only that one
+ *   was. This plugin is the stopgap.
  *
  * @module @argszero/cordis-plugin-sandbox-grant-advisor
  */
 import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm';
-import { advisoryText, ACL_DISCUSSIONS, denialText, NATIVE_INIT_DISCUSSIONS, PTY_DISCUSSIONS } from './advice.js';
-import { classifyNativeInitDeath, classifyProvisioningFailure, classifyPtyStartupFailure } from './signature.js';
-import { confines, resolveSandboxMode } from './mode.js';
+import { advisoryText, ACL_DISCUSSIONS, denialText, DISCUSSIONS_OF, NATIVE_INIT_DISCUSSIONS, PTY_DISCUSSIONS, WORKSPACE_DENIAL_DISCUSSIONS } from './advice.js';
+import { classifyNativeInitDeath, classifyProvisioningFailure, classifyPtyStartupFailure, classifyWorkspaceDenial, hasWorkspaceDenialStamp, } from './signature.js';
+import { confines, resolveSandboxMode, resolveWorkspaceRoot } from './mode.js';
 import { advisedOf, callKey, observe, observeSuccess, recordAdvice, recordDenial, recordWithheld, shouldDeny, } from './state.js';
 export const name = 'sandbox-grant-advisor';
 /** The tool pipeline this plugin observes and (optionally) gates. */
@@ -303,6 +342,10 @@ function summaryOf(failure, mode) {
         return `sandboxed command never started (exit ${String(failure.rawExitCode)}, STATUS_DLL_INIT_FAILED) `
             + `under sandbox mode "${String(mode)}"`;
     }
+    if (failure.family === 'workspace-denial') {
+        const subject = failure.paths[0] ?? 'a path in the workspace';
+        return `denied inside the workspace (${subject}) under sandbox mode "${failure.mode}"`;
+    }
     return `workspace ACL provisioning failed (Win32 ${String(failure.win32Code)})`;
 }
 /**
@@ -346,16 +389,16 @@ export function apply(ctx, config = {}) {
      * @param agent - the agent whose failure was withheld.
      * @param state - the agent's state, to keep the note to one.
      * @param why - what stopped the advisory.
-     * @param failure - the recognized failure that was withheld; only the two
-     *   mode-gated families reach this function, so the thread it cites is exact.
+     * @param family - the recognized family that was withheld. Only families whose
+     *   gate can fail closed reach this function, so the thread it cites is exact.
      * @returns undefined, so callers can `return withhold(...)`.
      */
-    function withhold(agent, state, why, failure) {
+    function withhold(agent, state, why, family) {
         if (state?.withheld === true)
             return undefined;
         states.set(agent, recordWithheld(state));
-        const discussions = failure.family === 'pty-startup' ? PTY_DISCUSSIONS : NATIVE_INIT_DISCUSSIONS;
-        ctx.logger.warn(`sandbox-grant-advisor: ${failure.family} failure recognized but no advisory sent — ${why}; the raw `
+        const discussions = DISCUSSIONS_OF[family];
+        ctx.logger.warn(`sandbox-grant-advisor: ${family} failure recognized but no advisory sent — ${why}; the raw `
             + `error is left exactly as it is, so this is NOT a claim that the sandbox is unrelated (discussions ${discussions})`);
         return undefined;
     }
@@ -383,12 +426,20 @@ export function apply(ctx, config = {}) {
             // read from `result.value` and never from the rendered text, so a command
             // whose own output mentions the code cannot be mistaken for it.
             const death = classifyNativeInitDeath(result.value);
-            if (death === undefined) {
-                if (previous !== undefined)
-                    states.set(agent, observeSuccess(previous, key));
-                return undefined;
+            if (death !== undefined)
+                return adviseGated(agent, previous, death, key, exec.name);
+            // The workspace-denial family is the other value-read one, and it is read
+            // only when the host is Windows: the mechanism it explains is ACE
+            // inheritance, which no other backend has, so on macOS/Linux the same
+            // stamp is a different story and is left alone with no note at all (that
+            // is the designed denial path there, not a puzzle). The platform test
+            // comes first so a non-Windows host never pays for the policy lookup.
+            if (process.platform === 'win32' && hasWorkspaceDenialStamp(result.value)) {
+                return adviseWorkspaceDenial(agent, previous, result.value, exec.arguments, key, exec.name);
             }
-            return adviseGated(agent, previous, death, key, exec.name);
+            if (previous !== undefined)
+                states.set(agent, observeSuccess(previous, key));
+            return undefined;
         }
         // The two text families read different fields, on purpose. The ACL signature
         // carries an API name plus a Win32 code, which a command's own output does
@@ -441,12 +492,12 @@ export function apply(ctx, config = {}) {
     function adviseGated(agent, previous, failure, key, tool) {
         const resolution = resolveSandboxMode(ctx, agent);
         if (!resolution.ok)
-            return withhold(agent, previous, resolution.withheld, failure);
+            return withhold(agent, previous, resolution.withheld, failure.family);
         const mode = resolution.mode;
         if (!confines(mode)) {
             const what = failure.family === 'pty-startup' ? 'the shell' : 'the command';
             return withhold(agent, previous, `the failing call ran under \`${mode}\`, where ${what} is not spawned `
-                + 'through the sandbox', failure);
+                + 'through the sandbox', failure.family);
         }
         if (!claimAdvice(agent, previous, failure, key))
             return undefined;
@@ -468,6 +519,59 @@ export function apply(ctx, config = {}) {
         states.set(agent, first ? recordAdvice(advanced, failure.family) : advanced);
         return first;
     }
+    /**
+     * Diagnose one denial whose target lies **inside** the agent's own workspace.
+     *
+     * The fourth family reads the executor's structured stamp rather than a
+     * message, so what is left here is the one fact the stamp cannot carry: the
+     * workspace root, which the containment claim has to be tested against. It is
+     * resolved from the agent's own session (the same resolver the enforcing
+     * providers are handed), and a root that cannot be resolved withholds the
+     * advisory rather than guessing — but only after the stamp has been seen, so
+     * an ordinary successful call costs no note. Once the root is known the
+     * classifier decides; a value that is a denial but names no in-workspace path
+     * is the designed escalation path and is left silent on purpose, which is why
+     * the `undefined` from the classifier is *not* routed through `withhold`.
+     * @param agent - the agent whose call was denied.
+     * @param previous - the agent's state before this call, if any.
+     * @param value - the settled call's canonical value.
+     * @param args - the settled call's parsed arguments.
+     * @param key - the identity of the denied call.
+     * @param tool - the denied tool's name, for the advisory context.
+     * @returns the notice to attach, or undefined.
+     */
+    function adviseWorkspaceDenial(agent, previous, value, args, key, tool) {
+        const resolution = resolveWorkspaceRoot(ctx, agent);
+        if (!resolution.ok)
+            return withhold(agent, previous, resolution.withheld, 'workspace-denial');
+        const failure = classifyWorkspaceDenial(value, args, {
+            platform: process.platform,
+            workspaceRoot: resolution.workspaceRoot,
+        });
+        if (failure === undefined)
+            return undefined;
+        if (!claimAdvice(agent, previous, failure, key))
+            return undefined;
+        ctx.logger.warn(workspaceDenialHostLine(failure));
+        return notice(advisoryText(failure, advisoryContext(tool)), summaryOf(failure));
+    }
+    /**
+     * The one-line host-side account of a recognized workspace-internal denial.
+     *
+     * It carries the path the plugin keyed on, because this family's whole claim
+     * is that one named path lies inside one named root — a maintainer reading the
+     * log is entitled to see both halves of the string comparison rather than a
+     * verdict about it.
+     * @param failure - the recognized failure.
+     * @returns a single log line.
+     */
+    function workspaceDenialHostLine(failure) {
+        const subject = failure.paths[0] ?? '<no path recovered>';
+        const more = failure.paths.length > 1 ? ` (+${String(failure.paths.length - 1)} more inside the same root)` : '';
+        return `sandbox-grant-advisor: confined command denied ${subject}${more}, which is INSIDE the workspace `
+            + `${failure.workspaceRoot}, under sandbox mode "${failure.mode}" — the root-only grant skipped this object and `
+            + `is never revisited, so retrying cannot help; advisory delivered to the model (discussion ${WORKSPACE_DENIAL_DISCUSSIONS})`;
+    }
     /**
      * The advisory context for one failing call.
      *

package/lib/mode.js

@@ -19,6 +19,13 @@
  * session — so what is quoted in the advisory is the policy that actually
  * governed the failing call, not a guess reconstructed from configuration.
  *
+ * The same lookup answers the **workspace root** for the fourth family
+ * (`workspace-denial`, #423), whose claim is that the path a denied command
+ * named lies inside the session's own workspace. Same request, same fail-closed
+ * posture, separate function ({@link resolveWorkspaceRoot}), so that neither
+ * family can fail on a field it never reads and each can name the failure in its
+ * own words.
+ *
  * ## Why this is a guarded lookup instead of an import
  *
  * `@deepseek-ai/dsh-sandbox-policy` is **optional** in this plugin's world: a
@@ -106,10 +113,60 @@ function recognizedMode(resolved) {
  * @returns the mode, or the reason it could not be resolved.
  */
 export function resolveSandboxMode(ctx, agent) {
+    const lookup = policyOf(ctx, agent);
+    if (!lookup.ok)
+        return { ok: false, withheld: lookup.withheld };
+    const mode = recognizedMode(lookup.resolved);
+    if (mode === undefined) {
+        return { ok: false, withheld: '`sandboxPolicy.resolve` returned a value without a recognizable mode' };
+    }
+    return { ok: true, mode };
+}
+/**
+ * The workspace root the policy resolver reports for one agent's call.
+ *
+ * The same lookup, the same request and the same fail-closed posture as
+ * {@link resolveSandboxMode}, and for the same reason: the root is what the
+ * enforcing providers were handed, so it is the value the workspace-denial
+ * family must test containment against rather than one reconstructed from
+ * configuration. The two are separate functions rather than one that returns
+ * both because each family needs one of them, and a family that needs only the
+ * mode must not be able to fail on a missing root (nor the other way round).
+ * @param ctx - the plugin's context.
+ * @param agent - the agent whose call failed.
+ * @returns the root, or the reason it could not be resolved.
+ */
+export function resolveWorkspaceRoot(ctx, agent) {
+    const lookup = policyOf(ctx, agent);
+    if (!lookup.ok) {
+        return {
+            ok: false,
+            withheld: lookup.why === 'unmounted'
+                ? 'no `sandboxPolicy` service is mounted in this composition, so the workspace root is unknown'
+                : lookup.withheld,
+        };
+    }
+    const resolved = lookup.resolved;
+    const root = resolved === null || typeof resolved !== 'object'
+        ? undefined
+        : resolved.workspaceRoot;
+    if (typeof root !== 'string' || root.length === 0) {
+        return { ok: false, withheld: '`sandboxPolicy.resolve` returned a value without a usable workspace root' };
+    }
+    return { ok: true, workspaceRoot: root };
+}
+/**
+ * Ask the mounted policy service for one agent's resolved policy.
+ * @param ctx - the plugin's context.
+ * @param agent - the agent whose call is being placed.
+ * @returns the resolver's answer, or the reason there is none.
+ */
+function policyOf(ctx, agent) {
     const policy = asPolicy(ctx.get('sandboxPolicy'));
     if (policy === undefined) {
         return {
             ok: false,
+            why: 'unmounted',
             withheld: 'no `sandboxPolicy` service is mounted in this composition, so the effective mode is unknown',
         };
     }
@@ -117,19 +174,14 @@ export function resolveSandboxMode(ctx, agent) {
     if (session === undefined) {
         return {
             ok: false,
+            why: 'no-session',
             withheld: 'the agent exposes no session, and the policy must be resolved from it rather than from the deployment default',
         };
     }
-    let resolved;
     try {
-        resolved = policy.resolve({ session });
+        return { ok: true, resolved: policy.resolve({ session }) };
     }
     catch (error) {
-        return { ok: false, withheld: `\`sandboxPolicy.resolve\` threw (${String(error)})` };
-    }
-    const mode = recognizedMode(resolved);
-    if (mode === undefined) {
-        return { ok: false, withheld: '`sandboxPolicy.resolve` returned a value without a recognizable mode' };
+        return { ok: false, why: 'threw', withheld: `\`sandboxPolicy.resolve\` threw (${String(error)})` };
     }
-    return { ok: true, mode };
 }

package/lib/signature.js

@@ -1,5 +1,5 @@
 /**
- * Recognize the three environment failures this plugin explains, and refuse
+ * Recognize the four environment failures this plugin explains, and refuse
  * everything else.
  *
  * ## The ACL provisioning failure (`acl-provisioning`)
@@ -147,6 +147,82 @@
  *   observe and would make this family untestable on the host this plugin is
  *   built on — which is how a family ships without ever having been run.
  *
+ * ## Denied inside the workspace (`workspace-denial`)
+ *
+ * The fourth family is the other half of the same backend the first one
+ * explains. There the grant could not be applied at all and every command died
+ * before it ran; here the grant *was* applied and the workspace looks
+ * provisioned — and part of the tree still refuses writes. `#423` is the
+ * report: under `workspace-write` on Windows, a command writing into a
+ * subdirectory that was created or moved in from outside the session is denied,
+ * forever, while the same command against a directory the harness itself
+ * created succeeds.
+ *
+ * Like the native-init family, and for the same structural reason, this one is
+ * **invisible from the error path**: a denied command exits nonzero, and the
+ * shipped shell tools report a nonzero exit as a finished run rather than as
+ * `isError`, so the fact arrives in `ToolExecutionSuccess.value`. Unlike that
+ * family it does not need a bespoke code to be read — the shipped executors
+ * *stamp the denial* onto the value, as a structured triple no line of rendered
+ * text can fabricate:
+ *
+ *   `sandbox: { mode, denied: true, enforcement? }`
+ *
+ * (`packages/shell/bash-sandbox/src/index.ts` and `pwsh-sandbox`, both on
+ * `classifyDenial`; projected into the tool result value by `tool-bash` /
+ * `tool-pwsh`). `denied` is produced by matching the backend's own refusal
+ * dialect in the *captured stderr* — `'access is denied'`, `'access to the
+ * path'`, `'permission denied'`, `'operation not permitted'` for the
+ * `windows-acl` backend — so the value is the harness's reading of its own
+ * sandbox, not this plugin's reading of a message.
+ *
+ * **`denied` alone is not this family, and the narrowings are the whole
+ * design.** A denial is the *sanctioned* outcome in three other situations, and
+ * advising about a missing inherited grant in any of them would be the
+ * confidently wrong cause this module exists to avoid:
+ *
+ * - **Outside the workspace.** `fs-sandbox` throws its marker only when a path
+ *   falls outside the writable roots, and a confined shell denying a path
+ *   outside the workspace is the designed escalation path — the denial surface
+ *   offers one retry under a wider mode, and that offer is correct there.
+ * - **Under `read-only`.** That mode denies *every* write by construction
+ *   (`fs-sandbox`'s `checkedTarget`: `read-only` throws before any containment
+ *   question is asked), so an in-workspace denial under it is the mode working.
+ * - **A runner failure.** The executor refuses to call a run denied when the
+ *   runner itself failed (`denied: !runnerFailed && …`), and a value that
+ *   carries `runnerFailed: true` is left alone for the same reason.
+ *
+ * What is left is exactly the anomaly: **a denial under `workspace-write` of a
+ * path inside the session's own workspace**, which is the one combination the
+ * harness is supposed to make impossible. The mode comes off the value (the
+ * executor stamped the mode it actually ran under, so no policy lookup can
+ * disagree with it), and the containment test needs the workspace root, which
+ * comes from the policy resolver at the call site —
+ * {@link classifyWorkspaceDenial} takes it as a fact rather than reading it, so
+ * the recognition stays a pure function of its inputs.
+ *
+ * **The in-workspace half of that test is keyed on the command's own text**, and
+ * deliberately not on the stderr the denial was inferred from: the regex looks
+ * for drive-qualified or UNC path literals in the call's `command` argument, and
+ * the family is recognized only when **every** such literal it finds lies under
+ * the workspace root. A command that names an outside path as well — an
+ * interpreter shipped under `C:\Program Files`, an output directory on another
+ * volume — is refused rather than guessed at, and so is a command that names
+ * only relative paths: in both cases the plugin cannot say *which* path was
+ * denied, and silence is the fail-closed direction. The paths it did key on are
+ * carried into the advisory, so the reader can see the reasoning rather than
+ * take it on faith.
+ *
+ * **The platform gate is real here, and unlike the native-init family it cannot
+ * be dropped.** The mechanism is Windows ACE inheritance: the backend writes the
+ * grant once, on the workspace root, and relies on the operating system to
+ * propagate it to descendants, which needs `WRITE_DAC` on each descendant at
+ * that moment. Every other backend applies its policy per call to the process
+ * (landlock rules, a bwrap profile, a seatbelt profile) and has no descendant to
+ * miss, so the same value on those hosts is a different story. `win32` is
+ * therefore part of recognition, passed in rather than read, and the suite runs
+ * this family with the platform fact supplied.
+ *
  * @module
  */
 /** The exact text `dsh-terminal-bash` throws when the shell exits during startup. */
@@ -163,6 +239,16 @@ export const PTY_STARTUP_EXIT = 'PTY shell exited during startup';
 export const STATUS_DLL_INIT_FAILED = 0xC0000142;
 /** The `kind` discriminator the shipped shell tools put on a finished foreground run. */
 const FOREGROUND = 'foreground';
+/**
+ * The mode in which a write **inside** the workspace is supposed to succeed.
+ *
+ * It is the only mode this family is recognized under, and that is a fact about
+ * the other two rather than about this one: `read-only` denies every write by
+ * construction, and `danger-full-access` spawns nothing through the sandbox at
+ * all — so a denial under either is the mode doing its job, and the one place a
+ * denial is an anomaly is here.
+ */
+export const DENIAL_MODE = 'workspace-write';
 /**
  * The producer's format is fixed by `Win32Error`
  * (`packages/subprocess/win32-process/src/errors.ts`):
@@ -273,6 +359,121 @@ export function failureLine(failure) {
         return failure.line;
     if (failure.family === 'native-init')
         return `[exit code: ${String(failure.rawExitCode)}]`;
+    if (failure.family === 'workspace-denial') {
+        const status = failure.exitCode === null ? '' : `[exit code: ${String(failure.exitCode)}] `;
+        return `${status}sandbox: { mode: "${failure.mode}", denied: true }`;
+    }
     const suffix = failure.detail.length === 0 ? '' : `: ${failure.detail}`;
     return `${failure.api} failed (Win32 ${failure.win32Code})${suffix}`;
 }
+/**
+ * The drive-qualified and UNC path literals in one command line.
+ *
+ * Deliberately crude, in the direction that keeps the diagnosis honest. A
+ * literal is taken to end at the first character a shell token cannot carry
+ * unquoted, so a path containing a space is recovered as its first segment — a
+ * **prefix** of the real path, which preserves the containment answer for every
+ * path that lies under the root (a prefix of a descendant is still a descendant)
+ * and refuses the test for paths whose root itself contains a space. A path that
+ * appears twice is returned once.
+ * @param command - the `command` argument of the failing shell call.
+ * @returns the literals found, in order, without trailing separators.
+ */
+export function windowsPathsIn(command) {
+    const found = [];
+    for (const match of command.matchAll(/(?:[A-Za-z]:[\\/]|\\\\)[^\s"'`|<>;&,]*/g)) {
+        const literal = match[0].replace(/[\\/]+$/, '');
+        if (literal.length >= 3 && !found.includes(literal))
+            found.push(literal);
+    }
+    return found;
+}
+/**
+ * Whether one path lies at or under one root, the way Windows compares them.
+ * @param root - the workspace root.
+ * @param path - the candidate path.
+ * @returns true when `path` is `root` itself or a descendant of it.
+ */
+export function isInsideWorkspace(root, path) {
+    const canon = (value) => value.replaceAll('/', '\\').replace(/\\+$/, '').toLowerCase();
+    const base = canon(root);
+    const target = canon(path);
+    if (base.length === 0 || target.length === 0)
+        return false;
+    return target === base || target.startsWith(`${base}\\`);
+}
+/**
+ * Whether one settled value carries the executors' workspace-denial stamp.
+ *
+ * The **structural half** of the fourth family's recognition, split out so that
+ * "this is not a denial at all" (silent, and the overwhelming majority of
+ * successful calls) stays distinguishable from "this is a denial and the plugin
+ * could not finish placing it" — the case the disclosure rule requires the host
+ * log to account for. It reads the value the executors wrote, never a line of
+ * rendered text, and it is deliberately platform-blind: the platform gate is a
+ * fact the classifier takes as an argument, and a stamp test that baked it in
+ * could not be used to decide whether a missing platform fact is worth saying
+ * out loud.
+ *
+ * What it does **not** decide is which path was denied — that needs the call's
+ * arguments and the workspace root, and belongs to
+ * {@link classifyWorkspaceDenial}. A stamp alone is the sanctioned outcome in
+ * three other situations (outside the workspace, under `read-only`, a runner
+ * failure); this function excludes the third by itself and leaves the first two
+ * to the classifier, which is the only place they can be separated.
+ * @param value - a settled execution's canonical value.
+ * @returns true when the value is a foreground shell projection stamped
+ *   `denied: true` under `workspace-write` with no runner failure.
+ */
+export function hasWorkspaceDenialStamp(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const probe = value;
+    if (probe.kind !== FOREGROUND)
+        return false;
+    const sandbox = probe.sandbox;
+    if (sandbox === null || typeof sandbox !== 'object')
+        return false;
+    const { mode, denied, runnerFailed } = sandbox;
+    return mode === DENIAL_MODE && denied === true && runnerFailed !== true;
+}
+/**
+ * Classify one **successful** execution's canonical value as a workspace-internal
+ * denial, and recover the paths the call named.
+ *
+ * Four facts, in the order they narrow: the call ran on Windows (the mechanism
+ * is ACE inheritance, which no other backend has); the value carries the
+ * executor's denial stamp ({@link hasWorkspaceDenialStamp}); the call's
+ * `command` argument carries at least one absolute Windows path literal; and
+ * **all** of them lie under the workspace root. The last is the one that
+ * separates this family from the sanctioned escalation path — a command naming
+ * any path outside its own workspace is refused rather than guessed at, because
+ * the plugin cannot say which path the sandbox refused.
+ * @param value - the settled execution's canonical value (`ToolExecutionSuccess.value`).
+ * @param args - the settled call's parsed arguments (`ToolExecution.arguments`).
+ * @param facts - the host platform and the session's workspace root.
+ * @returns the recognized failure, or undefined when this is not one.
+ */
+export function classifyWorkspaceDenial(value, args, facts) {
+    if (facts.platform !== 'win32')
+        return undefined;
+    if (!hasWorkspaceDenialStamp(value))
+        return undefined;
+    const probe = value;
+    const command = args?.command;
+    if (typeof command !== 'string')
+        return undefined;
+    const named = windowsPathsIn(command);
+    if (named.length === 0)
+        return undefined;
+    if (!named.every(path => isInsideWorkspace(facts.workspaceRoot, path)))
+        return undefined;
+    const exitCode = typeof probe.exitCode === 'number' && Number.isInteger(probe.exitCode) ? probe.exitCode : null;
+    return {
+        family: 'workspace-denial',
+        mode: DENIAL_MODE,
+        exitCode,
+        paths: named,
+        workspaceRoot: facts.workspaceRoot,
+    };
+}