@argszero/cordis-plugin-sandbox-grant-advisor 0.10.0 → 0.12.0

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,
+    };
+}

package/lib/types/advice.d.ts

@@ -3,7 +3,7 @@
  * environment failure, and what is deliberately withheld.
  *
  * The text is assembled here as pure functions so every sentence can be pinned
- * by a test, one family at a time. The three families are shaped by the same
+ * by a test, one family at a time. The four families are shaped by the same
  * question — is this the sandbox's doing, and what can the reader do about it —
  * and they answer it differently:
  *
@@ -112,6 +112,31 @@
  *   want of that variable. A withdrawn cause earns its sentence because this
  *   advisory shipped it twice; a confidently wrong cause is worse than two named
  *   ones with one shared remedy.
+ * - **The workspace-internal denial** (`workspace-denial`, #423) is the fourth,
+ *   and it is the first whose remedy is **withheld on purpose**. The failure is
+ *   not that a command failed but that the workspace's own grant does not cover
+ *   part of the workspace: the grant is written once on the root and depends on
+ *   ACE inheritance, so an already-existing object whose DACL the caller could
+ *   not write kept its older DACL, and the backend's root-only `hasExactGrant`
+ *   check means it is never revisited. Retrying is therefore provably useless,
+ *   which is what the text leads with. What it does **not** do is print a repair
+ *   command: the obvious one (`icacls` recursing the capability SID) is refused
+ *   by Windows itself with `ERROR_NONE_MAPPED` (1332), because that SID has no
+ *   name to map, and the line that would work needs the right that is missing —
+ *   so the advisory states the mechanism, names the ceiling, and says out loud
+ *   that it prints no command because this project has no Windows host to verify
+ *   one on. That is the same standard the standing-grant section is held to, and
+ *   it is the reason this family can be useful without being prescriptive.
+ *   Its discriminator is the **two-sided** one, which is not obvious and which a
+ *   reader checking only the ACE would get wrong: reading and listing use the
+ *   normal token while writing and deleting use the restricted one, so an object
+ *   whose DACL names only `Administrators`/`SYSTEM` plus the capability SID is
+ *   refused on the read side too and looks granted to a grep for the SID
+ *   (#423 measured it). The variant that would otherwise be missed gets its own
+ *   sentence as well — the same shape with the missing coverage on the mandatory
+ *   label instead of the DACL (reported 2026-09-29 in the same thread), which is
+ *   indistinguishable from inside a session and separable by the repository's own
+ *   diagnosis skill.
  *
  * Both give a **discriminator, not just a remedy**: applying a fix without
  * confirming the cause teaches nothing when the fix does not work. For the ACL
@@ -126,10 +151,16 @@
  * wrong remedy. Inside that Electron answer there is a third thing the code
  * cannot separate, and the advisory deliberately does not try: it names both
  * measurements and says the remedy does not depend on choosing between them.
+ * For the workspace-denial family the discriminator is the **path**, which is
+ * why the advisory prints the path it keyed on beside the root it tested it
+ * against: the reader can audit the plugin's own reasoning instead of taking a
+ * claim about two strings on faith. That family's check is also the one place
+ * where a single fact is not enough — reachability has two sides, and the text
+ * says which one a check on the ACE alone would miss.
  *
  * @module
  */
-import type { ProvisioningFailure, RecognizedFailure } from './signature.js';
+import type { FailureFamily, ProvisioningFailure, RecognizedFailure } from './signature.js';
 import type { SandboxModeName } from './mode.js';
 /**
  * The upstream threads the ACL advisory is a stopgap for.
@@ -159,7 +190,29 @@ export declare const PTY_DISCUSSIONS = "#7638 / #8322";
  * launched from a terminal does not, which is the same variable the PTY family
  * now names.
  */
-export declare const NATIVE_INIT_DISCUSSIONS = "#7876 / #7877 / #8193 / #8208 / #8313";
+export declare const NATIVE_INIT_DISCUSSIONS = "#7876 / #7877 / #8193 / #8208 / #8313 / #8336 / #8334";
+/**
+ * The upstream thread the workspace-denial advisory is a stopgap for.
+ *
+ * One thread, because this family is one report and its own follow-up: `#423`
+ * is the failure and its measurements (170 of 729 objects missing the grant,
+ * root-level files among them, and the two-sided reachability rule), and the
+ * second comment in that thread is the mandatory-label variant of the same
+ * shape.
+ */
+export declare const WORKSPACE_DENIAL_DISCUSSIONS = "#423";
+/**
+ * The thread list each family's withholding note cites.
+ *
+ * A withheld recognition is a decision the host log has to account for, and the
+ * note a maintainer reads is only useful if it points at *that* family's
+ * report — a withheld native-init death and a withheld workspace denial are
+ * different reports, and a note that cites the wrong one is its own small
+ * misdiagnosis. Kept beside the constants it assembles rather than at the
+ * withholding site, so a family added without a thread is a type error instead
+ * of a note that quietly cites another family's.
+ */
+export declare const DISCUSSIONS_OF: Record<FailureFamily, string>;
 /** The documented prerequisite, quoted from the backend's README. */
 export declare const PREREQUISITE = "granted directories must be caller-owned and grant `WRITE_OWNER`";
 /**

package/lib/types/index.d.ts

@@ -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,7 +190,12 @@
  *   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
  */

package/lib/types/mode.d.ts

@@ -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
@@ -73,6 +80,18 @@ export type ModeResolution =
     readonly ok: false;
     readonly withheld: string;
 };
+/** The outcome of resolving one agent's workspace root. */
+export type RootResolution = 
+/** The workspace root the enforcing providers were handed. */
+{
+    readonly ok: true;
+    readonly workspaceRoot: string;
+}
+/** No answer was available, and why — the host side says so out loud. */
+ | {
+    readonly ok: false;
+    readonly withheld: string;
+};
 /**
  * Resolve the effective sandbox mode for one agent's call.
  *
@@ -85,3 +104,18 @@ export type ModeResolution =
  * @returns the mode, or the reason it could not be resolved.
  */
 export declare function resolveSandboxMode(ctx: Context, agent: Agent): ModeResolution;
+/**
+ * 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 declare function resolveWorkspaceRoot(ctx: Context, agent: Agent): RootResolution;