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

package/lib/advice.js

@@ -1,29 +1,77 @@
 /**
- * What the model — and through it the user — is told about a provisioning
- * failure, and what is deliberately withheld.
+ * What the model — and through it the user — is told about a recognized
+ * environment 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:
+ * by a test, one family at a time. The two families are shaped by the same two
+ * questions, and they answer them differently:
  *
- * - **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.
+ * - **The ACL failure** (`acl-provisioning`) *is* fixable by the caller, so its
+ *   advice names the right the caller is missing and gives the command.
+ *   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.
+ * - **The persistent-shell failure** (`pty-startup`) is *not* fixable by the
+ *   caller — least of all by the model, which has no shell to run anything in.
+ *   So its advice says so and stops: the remedy is a user-side preset choice,
+ *   and the model's instruction is to stop retrying and use its file tools.
+ *   Handing the model a command here would be advice to run something that
+ *   cannot run, and naming a one-shot shell tool would be advice to call a tool
+ *   the failing composition does not mount.
+ *
+ * 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
+ * family that is `icacls <dir>`, looking for an ACE that names the caller's own
+ * SID and grants `(F)` — which separates "Modify-only directory" from "the
+ * documented prerequisite is wrong", the open question upstream. For the PTY
+ * family it is the **effective sandbox mode**, which is why that advisory is
+ * only ever built with the mode the call actually ran under.
  *
  * @module
  */
 import { failureLine } from './signature.js';
-/** The upstream threads this advisory is a stopgap for. */
-export const DISCUSSIONS = '#7538 / #7622 / #7646';
+/** The upstream threads the ACL advisory is a stopgap for. */
+export const ACL_DISCUSSIONS = '#7538 / #7622 / #7646 / #7720';
+/** The upstream thread the persistent-shell advisory is a stopgap for. */
+export const PTY_DISCUSSIONS = '#7638';
 /** The documented prerequisite, quoted from the backend's README. */
 export const PREREQUISITE = 'granted directories must be caller-owned and grant `WRITE_OWNER`';
+/**
+ * Where a user's own preset changes actually live.
+ *
+ * This is deliberately **not** the legacy `$DSH_HOME/.agent-presets/<id>/`
+ * directory: that shape predates declarative presets and **nothing reads it any
+ * more** (the registry "neither scans directories nor accepts preset paths").
+ * A preset is a `@deepseek-ai/dsh-agent-preset` row, and changing one means
+ * overriding or inserting that row in a patch layer, which is what this path
+ * names. Advising a folder the harness stopped reading would be the same defect
+ * this plugin exists to answer — a remedy that does not work, delivered
+ * confidently.
+ */
+export const PROFILE_PATCH = '$DSH_HOME/profiles/<profile>/cordis.patch.yml';
+/** The machine-wide patch layer, for a change that should hold in every profile. */
+export const GLOBAL_PATCH = '$DSH_HOME/cordis.patch.yml';
+/** The row id the shipped `minimal` preset is declared under. */
+export const MINIMAL_PRESET_ROW = 'preset-minimal';
+/** The one-shot shell tool the `standard` preset mounts on Windows. */
+export const ONE_SHOT_SHELL = '@deepseek-ai/dsh-tool-pwsh';
+/**
+ * The two remedies that look like the fix and are not.
+ *
+ * Both were applied by the reporter of `#7720` before finding the one that
+ * works, and both are the *natural* reach: making yourself the owner and
+ * resetting the directory's ACL are how one normally repairs a Windows
+ * permission problem. They fail here for two different reasons, and naming the
+ * reason is what makes this section worth its lines — a reader who already
+ * tried them learns why, and a reader who has not is spared the attempt. See
+ * {@link nonFixes} for when this is emitted.
+ */
+export const NOT_FIXES = [
+    'takeown /F "<dir>" /R /D Y',
+    'icacls "<dir>" /reset /T /C',
+];
 /** Placeholder the user replaces with the directory the error named. */
 const PLACEHOLDER = '<the directory from the error line above>';
 /**
@@ -58,15 +106,66 @@ function diagnosis(failure) {
             ].join('\n');
     }
 }
+/**
+ * The "this is not the fix" lines for one class of failure.
+ *
+ * Emitted only for `apply-denied`, the class whose whole diagnosis is the
+ * missing `WRITE_OWNER` right — because only there is the claim true:
+ *
+ * - `read-denied` wants `READ_CONTROL`, and taking ownership *does* carry it,
+ *   so calling `takeown` a non-fix there would be false.
+ * - `apply-other` already says the missing-rights story does not apply
+ *   verbatim, so a section that presupposes it would contradict its own
+ *   diagnosis.
+ *
+ * A negative claim still has to be earned: the failure to avoid is advice that
+ * is confidently wrong in the other direction.
+ * @param failure - the recognized provisioning failure.
+ * @param path - the directory the error named, or the placeholder.
+ * @returns the section's lines, or an empty array for a class it does not fit.
+ */
+function nonFixes(failure, path) {
+    if (failure.klass !== 'apply-denied')
+        return [];
+    return [
+        'What will NOT fix it — both look like the right move, and both were tried and reported:',
+        `  takeown /F "${path}" /R /D Y`,
+        "    makes you the owner, but ownership's implicit rights are READ_CONTROL and WRITE_DAC only.",
+        '    The owner does not implicitly hold WRITE_OWNER, which is the right this call needs.',
+        `  icacls "${path}" /reset /T /C`,
+        '    restores inheritance, and inheritance is what supplied the Modify-only ACE above.',
+        '',
+    ];
+}
 /**
  * Build the advisory attached to the failing tool result.
+ *
+ * The family decides everything: one function so a caller does not have to
+ * remember which family needs which fact, and so the mode requirement of the
+ * PTY family is enforced by construction rather than by convention.
+ * @param failure - the recognized failure.
+ * @param context - what the caller knows about the failing call.
+ * @returns the user-role notice text, with any remedy ready to paste.
+ * @throws when a PTY failure is advised without its resolved sandbox mode.
+ */
+export function advisoryText(failure, context = {}) {
+    if (failure.family === 'pty-startup') {
+        if (context.mode === undefined) {
+            throw new Error('sandbox-grant-advisor: the persistent-shell advisory requires the resolved sandbox mode');
+        }
+        return ptyAdvisory(failure, context.mode, context.tool, context.href);
+    }
+    return aclAdvisory(failure, context.href);
+}
+/**
+ * Build the advisory for a workspace-provisioning failure.
  * @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) {
+function aclAdvisory(failure, href) {
     const path = failure.path ?? PLACEHOLDER;
-    const where = href === undefined ? `tracked upstream (discussions ${DISCUSSIONS})` : `tracked upstream: ${href}`;
+    const where = href === undefined ? `tracked upstream (discussions ${ACL_DISCUSSIONS})` : `tracked upstream: ${href}`;
     return [
         'Sandbox provisioning failed — no sandboxed command can run in this workspace until its ACL applies.',
         '',
@@ -84,14 +183,74 @@ export function advisoryText(failure, href) {
         `  PowerShell: icacls "${path}" /grant "$env:USERNAME:(OI)(CI)F"`,
         `  cmd:        icacls "${path}" /grant "%USERNAME%:(OI)(CI)F"`,
         '',
+        ...nonFixes(failure, path),
         '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 advisory for a persistent-shell startup failure.
+ *
+ * The one thing this text must never do is hand the model a command to run:
+ * there is no shell to run it in. That is why the remedy is addressed to the
+ * user (preset choice), while the model's instruction is to stop — the
+ * alternative, naming a one-shot shell tool, would be advice to call a tool the
+ * failing composition does not mount (`minimal` mounts exactly one platform
+ * shell, the persistent PTY: the design note
+ * `.agents/notes/implemented/simplification/2026-09-03-minimal-profiles-persistent-shell-only.md`).
+ * @param failure - the recognized failure.
+ * @param mode - the resolved sandbox mode the failing call ran under.
+ * @param tool - the tool whose call failed, when the caller knows it.
+ * @param href - optional URL shown for the upstream thread.
+ * @returns the user-role notice text.
+ */
+function ptyAdvisory(failure, mode, tool, href) {
+    const where = href === undefined ? `tracked upstream (discussion ${PTY_DISCUSSIONS})` : `tracked upstream: ${href}`;
+    const call = tool === undefined ? 'This tool' : `The \`${tool}\` tool`;
+    return [
+        'Persistent shell failed to start — command execution is unavailable in this session, and retrying cannot fix it.',
+        '',
+        'What was reported:',
+        `  ${failureLine(failure)}`,
+        '',
+        `${call} is a PERSISTENT PTY session (a shell that stays alive between calls), and this session's sandbox mode is`,
+        `\`${mode}\` — not \`danger-full-access\`. A confining mode spawns the shell through the sandbox, and there the`,
+        'terminal backend cannot create the pseudo-console at all, so the child exits before its first prompt. The same',
+        'shell works under `danger-full-access`, and the one-shot shell tool works under the same confining mode:',
+        'persistent PTY × confining sandbox is the combination that fails.',
+        '',
+        'Do NOT retry, and do not look for a command that fixes it: every attempt will fail identically, and there is no',
+        'shell to run a command in. Use your file read/write tools instead, and hand the choice below to the user.',
+        '',
+        'What unblocks the session — the user\'s decision, not the model\'s:',
+        '  1. switch the agent preset to `standard`, whose shell tool is a one-shot subprocess (no PTY) and works',
+        '     under the sandbox; or',
+        `  2. override the \`${MINIMAL_PRESET_ROW}\` row in your profile patch — \`${PROFILE_PATCH}\`, or`,
+        `     \`${GLOBAL_PATCH}\` for every profile — replacing its \`persistent-shell\` group with`,
+        `     \`${ONE_SHOT_SHELL}\` (a one-shot subprocess, no PTY); the patch layer is yours, so an upgrade`,
+        '     will not overwrite it; or',
+        '  3. run the session with `danger-full-access`, which drops the very confinement the sandbox exists to give.',
+        '     Prefer 1 or 2.',
+        '',
+        'How to read this: the failure names no cause and points at no remedy, so the diagnosis is delivered here instead.',
+        'This is a stopgap, ' + where + '. Unless the mode is `danger-full-access`, this plugin stays silent, because a',
+        'shell can fail to start for other reasons and a confident wrong cause is worse than no answer.',
+    ].join('\n');
+}
 /**
  * Build the pre-dispatch denial for the optional fail-fast half.
+ *
+ * The blocking half is deliberately **ACL-only**, and this function's parameter
+ * type is where that is enforced. The PTY family gets an advisory and nothing
+ * else, for a reason that is about the remedy rather than about the failure:
+ * the ACL remedy is a command the user can run *while the session continues*,
+ * so refusing further identical calls cannot make the session unfinishable —
+ * spending the budget always lets the call through, and a repaired environment
+ * is discovered by exactly that. The PTY remedy is a preset swap, which happens
+ * between sessions; refusing calls could only pad a session that is already
+ * unable to do the thing being refused.
  * @param failure - the recognized failure.
  * @param observed - how many provisioning failures this agent has produced.
  * @param denial - this denial's 1-based ordinal.

package/lib/index.js

@@ -1,23 +1,45 @@
 /**
- * `sandbox-grant-advisor`: turn a Windows ACL provisioning failure that has no
- * path forward into a diagnosis the model — and the user reading the
- * transcript — can act on.
+ * `sandbox-grant-advisor`: turn an environment failure that has no path forward
+ * into a diagnosis the model — and the user reading the transcript — can act on.
  *
- * Three reports of one signature (`#7538`, `#7622`, `#7646`) describe the same
- * shape: the host-side write grant for a sandboxed workspace cannot be applied,
- * every sandboxed command then fails identically **before it runs**, and the
- * error text is a bare Win32 line:
+ * ## The two failures it recognizes
+ *
+ * **Workspace provisioning (Windows ACL).** Four reports of one signature
+ * (`#7538`, `#7622`, `#7646`, `#7720`) describe the same shape: the host-side write grant
+ * for a sandboxed workspace cannot be applied, every sandboxed command then
+ * fails identically **before it runs**, and the error text is a bare Win32 line:
  *
  *   SetNamedSecurityInfoW failed (Win32 5): grantWrite(D:\ws)
  *
  * The grant is materialized lazily on the first confined call and nothing is
  * cached when it throws, so the failure repeats per command rather than once
  * (850 calls / 39 sessions in `#7622`; 52,588 output tokens with no output in
- * `#7538`). The `workspace-write` policy is simply unusable in such a
- * workspace, and the remedy the backend documents — the directory must grant
- * the caller `WRITE_OWNER` — never reaches the user, so sessions escape into
+ * `#7538`). The remedy the backend documents — the directory must grant the
+ * caller `WRITE_OWNER` — never reaches the user, so sessions escape into
  * `danger-full-access` or die on the model's output cap.
  *
+ * `#7720` sharpens where this lands: because the grant is materialized at
+ * sandbox *initialization*, that failure takes **every** shell tool with it, not
+ * one operation — the reporter could not run `netstat` or `icacls` to diagnose
+ * the failure they were looking at. It also contributes the two remedies that
+ * look right and are not (`takeown /R /D Y`, `icacls /reset /T /C`), which the
+ * ACL advisory now names along with the reason each fails.
+ *
+ * **Persistent shell startup (#7638).** With the `minimal` preset on Windows the
+ * only shell tool is a persistent PTY (`dsh-terminal-bash` +
+ * `dsh-tool-pwsh-persistent`), and under a *confining* sandbox mode every call
+ * fails instantly with
+ *
+ *   PTY shell exited during startup
+ *
+ * — the backend cannot create the pseudo-console inside the sandbox, so the
+ * child exits before its first prompt. Retrying never helps, the message points
+ * at no cause, and because `minimal` mounts no fallback shell tool the session
+ * has no command execution left at all. The reporter's own three-arm control
+ * makes the sandbox mode the discriminator: minimal × confining fails, minimal ×
+ * `danger-full-access` succeeds, `standard` (one-shot shell) × confining
+ * succeeds.
+ *
  * ## Where it acts, and why there
  *
  * One listener on the public `tools/post-execute` waterfall
@@ -28,51 +50,74 @@
  * to the model in the same step (`PostToolDecision`'s `additionalContexts`,
  * a durable user-role message).
  *
- * `ctx.sandbox.confine(argv, policy, signal)` sees the failure too, and cannot
- * do this: its signature carries no agent, so a wrapper could detect the
- * condition and never deliver a word about it to the session that is stuck.
+ * `ctx.sandbox.confine(argv, policy, signal)` sees the confinement failure too,
+ * and cannot do this: its signature carries no agent, so a wrapper could detect
+ * the condition and never deliver a word about it to the session that is stuck.
+ *
+ * The PTY family needs one fact the failure text does not carry — the effective
+ * sandbox mode — and takes it from `ctx.sandboxPolicy.resolve({ session })`:
+ * the same resolver the terminal layer calls before spawning, with the same
+ * session. See `src/mode.ts` for why that lookup is guarded rather than
+ * imported, and what happens when it cannot answer.
  *
  * ## What it does
  *
- * 1. **One durable advisory per agent.** On the first recognized provisioning
- *    failure, the failing tool result is enriched with a user-role notice that
- *    names the missing right (`WRITE_OWNER` on the directory, not
- *    `SeSecurityPrivilege`), gives the unelevated one-line `icacls` remedy, and
- *    gives the discriminator that separates a Modify-only directory from a
- *    wrong prerequisite. Attached through `additionalContexts`, so the model
- *    sees it beside the failure rather than only in a log the model never reads.
- * 2. **An optional bounded fail-fast.** With `enforceAfter` set, a call this
- *    plugin has *watched fail* this way is refused at `tools/pre-execute` once
- *    the environment has failed at least that many times. It is off by default:
- *    the useful signal here is the diagnosis, and a plugin that blocks command
- *    execution for a reason it merely recognizes is a risk, not a feature. See
- *    the README for why the blocking half is deliberately narrow.
+ * 1. **One durable advisory per agent, per family.** On the first recognized
+ *    failure of a family, the failing tool result is enriched with a user-role
+ *    notice. For the ACL family it names the missing right (`WRITE_OWNER` on the
+ *    directory, not `SeSecurityPrivilege`), gives the unelevated one-line
+ *    `icacls` remedy, gives the discriminator that separates a Modify-only
+ *    directory from a wrong prerequisite, and names the two remedies that look
+ *    right and are not (`takeown`, `icacls /reset`), each with its reason. For the PTY family it names the
+ *    combination that fails (persistent PTY × a confining mode), states the
+ *    resolved mode, says plainly that no command can fix it, and hands the
+ *    user-side preset choice over. Both ride `additionalContexts`, so the model
+ *    sees the diagnosis beside the failure rather than only in a log it never
+ *    reads.
+ * 2. **A bounded fail-fast, ACL family only.** With `enforceAfter` set, a call
+ *    this plugin has *watched fail* this way is refused at `tools/pre-execute`
+ *    once the environment has failed at least that many times. It is off by
+ *    default: the useful signal here is the diagnosis, and a plugin that blocks
+ *    command execution for a reason it merely recognizes is a risk, not a
+ *    feature. See the README for why the blocking half is deliberately narrow
+ *    and why it does not cover the PTY family.
+ * 3. **A disclosure when it withholds.** The PTY advisory is only sent when the
+ *    resolved mode actually confines; if the mode is not confining, or cannot be
+ *    resolved at all, the failure is left exactly as it was **and the host log
+ *    says so once**. Silence alone would make "the sandbox is not the cause" and
+ *    "this plugin could not tell" indistinguishable from the outside.
  *
  * ## Honest boundaries
  *
  * - **The Windows path cannot be witnessed on macOS**, where this plugin was
  *   built and tested. What is tested is the decision layer: classification,
- *   once-per-agent delivery, the fail-fast budget, and the wiring to the real
- *   `ToolRuntime` — against synthetic results carrying the producer's exact
- *   error shape, with the format taken from
- *   `packages/subprocess/win32-process/src/errors.ts`.
+ *   once-per-agent-per-family delivery, the sandbox-mode gate and its
+ *   fail-closed behaviour, the fail-fast budget, and the wiring to the real
+ *   `ToolRuntime` — against synthetic results carrying the producers' exact
+ *   error shapes, with the formats taken from
+ *   `packages/subprocess/win32-process/src/errors.ts` and
+ *   `packages/terminal/terminal-bash/src/{index,session}.ts`.
  * - **It does not repair anything.** No ACL is written, no privilege is
- *   requested, nothing is elevated: the `icacls` line is the user's to run.
+ *   requested, nothing is elevated, no preset is installed and no mode is
+ *   changed: both remedies are the user's to apply.
  * - **It complements, rather than replaces, `repeat-guard-escalation`.** That
  *   guard keys on *call identity* (identical arguments retried); this one keys
  *   on the *environment signature*, which is how several different commands can
  *   share one cause. They can be mounted together.
- * - **The real fix is upstream**: the failure should name the outstanding
- *   condition at the site that knows it (`grantWrite` computes
+ * - **The real fix is upstream**, in both families: the ACL failure should name
+ *   the outstanding condition at the site that knows it (`grantWrite` computes
  *   `hasExactGrant`/`hasExactDeny`/`hasExactLabel` and discards which was
- *   false). This plugin is the stopgap.
+ *   false), and the PTY startup path should either report "this sandbox mode is
+ *   incompatible with the PTY backend" or fall back to a one-shot shell. This
+ *   plugin is the stopgap.
  *
  * @module @argszero/cordis-plugin-sandbox-grant-advisor
  */
 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';
+import { advisoryText, ACL_DISCUSSIONS, denialText, PTY_DISCUSSIONS } from './advice.js';
+import { classifyProvisioningFailure, classifyPtyStartupFailure } from './signature.js';
+import { confines, resolveSandboxMode } 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. */
 export const inject = ['tools'];
@@ -90,6 +135,14 @@ export const SOURCE_KIND = 'sandbox-grant-advisor';
 export const DEFAULT_ENFORCE_AFTER = 0;
 /** Default denial budget once the blocking half is enabled. */
 export const DEFAULT_MAX_DENIALS = 2;
+/**
+ * The family the optional blocking half applies to.
+ *
+ * The ACL remedy is a command the user can run while the session continues; the
+ * PTY remedy is a preset swap between sessions. Refusing calls is only useful
+ * in the first case — see `denialText` in `src/advice.ts`.
+ */
+export const ENFORCED_FAMILY = 'acl-provisioning';
 /** Compile one `*`-wildcard pattern to an anchored RegExp; all else is literal. */
 function wildcardToRegExp(pattern) {
     const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, String.raw `\$&`);
@@ -127,15 +180,25 @@ function failureText(result) {
     return result.error.message.length > 0 ? `${result.error.message}\n${rendered}` : rendered;
 }
 /**
- * The one-line host-side account of a recognized failure.
+ * The one-line host-side account of a recognized ACL failure.
  * @param failure - the recognized failure.
  * @returns a single log line.
  */
-function hostLine(failure) {
+function aclHostLine(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})`;
+        + `this account Full control; advisory delivered to the model (discussions ${ACL_DISCUSSIONS})`;
+}
+/**
+ * The one-line host-side account of a recognized persistent-shell failure.
+ * @param mode - the resolved sandbox mode the failing call ran under.
+ * @returns a single log line.
+ */
+function ptyHostLine(mode) {
+    return `sandbox-grant-advisor: persistent shell exited during startup under sandbox mode `
+        + `"${mode}" — a PTY backend cannot start under a confining mode, and retrying cannot help; advisory `
+        + `delivered to the model (discussion ${PTY_DISCUSSIONS})`;
 }
 /**
  * Wrap one notice as a user-role message.
@@ -167,6 +230,12 @@ function notice(text, summary) {
 function prepend(ours, theirs) {
     return [ours, ...theirs ?? []];
 }
+/** The one-line transcript summary for a recognized failure. */
+function summaryOf(failure, mode) {
+    return failure.family === 'pty-startup'
+        ? `persistent shell exited during startup under sandbox mode "${String(mode)}"`
+        : `workspace ACL provisioning failed (Win32 ${String(failure.win32Code)})`;
+}
 /**
  * Install the advisor.
  * @param ctx - context carrying the tool pipeline.
@@ -195,6 +264,26 @@ export function apply(ctx, config = {}) {
             return false;
         return !excludePatterns.some(pattern => pattern.test(toolName));
     }
+    /**
+     * Leave a recognized failure exactly as it is, and say so once on the host.
+     *
+     * Withholding is a decision, not an absence: the transcript shows a bare error
+     * either way, so the difference between "this is not the sandbox's doing" and
+     * "this plugin could not tell" has to be recorded where a maintainer reads it.
+     * Once per agent, because a loop can produce dozens of these.
+     * @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.
+     * @returns undefined, so callers can `return withhold(...)`.
+     */
+    function withhold(agent, state, why) {
+        if (state?.withheld === true)
+            return undefined;
+        states.set(agent, recordWithheld(state));
+        ctx.logger.warn(`sandbox-grant-advisor: persistent-shell startup 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 (discussion ${PTY_DISCUSSIONS})`);
+        return undefined;
+    }
     /**
      * Read one settled call: advance the state, and decide whether it is the
      * failure the model needs told about.
@@ -217,17 +306,81 @@ export function apply(ctx, config = {}) {
                 states.set(agent, observeSuccess(previous, key));
             return undefined;
         }
-        const failure = classifyProvisioningFailure(failureText(result));
+        // The two families read different fields, on purpose. The ACL signature
+        // carries an API name plus a Win32 code, which a command's own output does
+        // not fabricate, so that family may read the merged text (`error.message`
+        // with the rendered content as its fallback). The persistent-shell
+        // signature is a bare sentence, and the rendered content is exactly where a
+        // runner-failure path could carry a command's output — so this family reads
+        // `error.message` alone, the field the layer that threw it filled in. A
+        // sentence quoted from a log must never make this plugin tell a working
+        // session that its shell is dead.
+        //
+        // Honest about the limit: with the current `dsh-tools` runtime the rendered
+        // content of an error result is derived from `error.message`, so today the
+        // two reads agree and this choice is not observable from outside — an
+        // injection arm that swaps in the merged text leaves the suite green, and
+        // that is recorded rather than papered over. The narrower read is kept
+        // because the agreement is the runtime's rendering choice, not a promise
+        // this plugin can rely on: a tool whose `render` produces output of its own
+        // is exactly the case the whole-line rule exists for.
+        const failure = classifyProvisioningFailure(failureText(result))
+            ?? classifyPtyStartupFailure(result.error.message);
         if (failure === undefined)
             return undefined;
-        const advanced = observe(previous, failure, key);
-        if (advanced.advised) {
-            states.set(agent, advanced);
-            return undefined;
+        // The PTY diagnosis IS the sandbox mode, so it is resolved before anything
+        // is recorded: an unconfined mode is not this family's story, and a mode
+        // that cannot be resolved is not something to guess at. Either way the
+        // failure is left untouched and the host log accounts for the silence.
+        if (failure.family === 'pty-startup') {
+            const resolution = resolveSandboxMode(ctx, agent);
+            if (!resolution.ok)
+                return withhold(agent, previous, resolution.withheld);
+            const mode = resolution.mode;
+            if (!confines(mode)) {
+                return withhold(agent, previous, `the failing call ran under \`${mode}\`, where the shell is not spawned through the sandbox`);
+            }
+            if (!claimAdvice(agent, previous, failure, key))
+                return undefined;
+            ctx.logger.warn(ptyHostLine(mode));
+            return notice(advisoryText(failure, advisoryContext(exec.name, mode)), summaryOf(failure, mode));
         }
-        states.set(agent, recordAdvice(advanced));
-        ctx.logger.warn(hostLine(failure));
-        return notice(advisoryText(failure, href), `workspace ACL provisioning failed (Win32 ${String(failure.win32Code)})`);
+        if (!claimAdvice(agent, previous, failure, key))
+            return undefined;
+        ctx.logger.warn(aclHostLine(failure));
+        return notice(advisoryText(failure, advisoryContext(exec.name)), summaryOf(failure));
+    }
+    /**
+     * Record one recognized failure and claim the once-per-agent advisory for its
+     * family.
+     * @param agent - the agent whose call failed.
+     * @param previous - the agent's state before this call, if any.
+     * @param failure - the recognized failure.
+     * @param key - the identity of the failing call.
+     * @returns true when this call is the one that must carry the diagnosis.
+     */
+    function claimAdvice(agent, previous, failure, key) {
+        const advanced = observe(previous, failure.family, failure, key);
+        const first = !advisedOf(advanced, failure.family);
+        states.set(agent, first ? recordAdvice(advanced, failure.family) : advanced);
+        return first;
+    }
+    /**
+     * The advisory context for one failing call.
+     *
+     * Built here rather than at each call site so the optional fields are only
+     * present when they are known — `exactOptionalPropertyTypes` would otherwise
+     * accept an explicit `undefined` that the consumer would have to un-learn.
+     * @param tool - the failing tool's name.
+     * @param mode - the resolved sandbox mode, for the family that needs it.
+     * @returns the context to pass to `advisoryText`.
+     */
+    function advisoryContext(tool, mode) {
+        return {
+            ...href === undefined ? {} : { href },
+            tool,
+            ...mode === undefined ? {} : { mode },
+        };
     }
     // Observe-and-enrich, never veto by itself: delegate first, then fold this
     // plugin's notice onto whatever came back. `additionalContexts` rides both
@@ -264,17 +417,29 @@ export function apply(ctx, config = {}) {
             if (agent === undefined || !tracked(exec.name))
                 return next();
             const state = states.get(agent);
-            if (!shouldDeny(state, callKey(exec.name, exec.arguments), enforceAfter, maxDenials))
+            const key = callKey(exec.name, exec.arguments);
+            if (!shouldDeny(state, ENFORCED_FAMILY, key, enforceAfter, maxDenials))
                 return next();
             if (state === undefined)
                 return next();
+            const record = state.families[ENFORCED_FAMILY];
+            if (record === undefined)
+                return next();
+            // `denialText` speaks the ACL family's language (the `icacls` line), so the
+            // record is asked to be that family's before it is used: the family tag on
+            // a record and the key it is stored under are not the same fact, and this
+            // is the one place where confusing them would put the wrong remedy in
+            // front of the model.
+            const failure = record.last;
+            if (failure.family !== 'acl-provisioning')
+                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));
+            states.set(agent, recordDenial(state, ENFORCED_FAMILY));
             return Promise.resolve({
                 kind: 'deny',
-                reason: denialText(state.last, state.observations, state.denials + 1, maxDenials),
+                reason: denialText(failure, record.observations, record.denials + 1, maxDenials),
             });
         }
         catch (error) {