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

package/lib/index.js

@@ -1,23 +1,38 @@
 /**
- * `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).** Three reports of one signature
+ * (`#7538`, `#7622`, `#7646`) describe the same shape: the host-side write grant
+ * for a sandboxed workspace cannot be applied, every sandboxed command then
+ * fails identically **before it runs**, and the error text is a bare Win32 line:
  *
  *   SetNamedSecurityInfoW failed (Win32 5): grantWrite(D:\ws)
  *
  * The grant is materialized lazily on the first confined call and nothing is
  * cached when it throws, so the failure repeats per command rather than once
  * (850 calls / 39 sessions in `#7622`; 52,588 output tokens with no output in
- * `#7538`). The `workspace-write` policy is simply unusable in such a
- * workspace, and the remedy the backend documents — the directory must grant
- * the caller `WRITE_OWNER` — never reaches the user, so sessions escape into
+ * `#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.
  *
+ * **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 +43,73 @@
  * 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, and gives the discriminator that separates a Modify-only
+ *    directory from a wrong prerequisite. 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 +127,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 +172,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 +222,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 +256,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 +298,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 +409,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) {

package/lib/mode.js

@@ -0,0 +1,135 @@
+/**
+ * Which sandbox mode a call ran under, and whether that mode confines.
+ *
+ * The persistent-shell diagnosis is only true under a **confining** mode. The
+ * terminal backend hands the shell argv straight through when the resolved mode
+ * is `danger-full-access` and confines it otherwise
+ * (`packages/terminal/terminal-bash/src/index.ts`:
+ * `if (policy.mode === 'danger-full-access') return argv`), so the same
+ * `PTY shell exited during startup` under `danger-full-access` is a different
+ * story — a broken or missing shell — and this plugin must stay silent about it
+ * rather than assert a sandbox cause it cannot support. The report that frames
+ * this family (#7638) says the same thing from the other side: its author's
+ * three-arm control shows the mode is the discriminator (minimal × confining
+ * fails, minimal × `danger-full-access` succeeds, standard × confining
+ * succeeds).
+ *
+ * The answer is taken from `ctx.sandboxPolicy.resolve({ session })` — the same
+ * resolver the terminal layer itself calls before spawning, with the same
+ * session — so what is quoted in the advisory is the policy that actually
+ * governed the failing call, not a guess reconstructed from configuration.
+ *
+ * ## Why this is a guarded lookup instead of an import
+ *
+ * `@deepseek-ai/dsh-sandbox-policy` is **optional** in this plugin's world: a
+ * composition may simply not mount the service, and this plugin must degrade to
+ * silence rather than fail to load. Two consequences shape this module:
+ *
+ * - A declared peer dependency is a claim about versions, and this package's
+ *   packaging guard refuses both an import that is not declared and a
+ *   declaration that is not imported. A *type-only* import would therefore turn
+ *   an optional integration into a mandatory claim on every line the peer range
+ *   admits — and a range that admits a line nobody ran is exactly the defect
+ *   that guard exists to prevent.
+ * - What is left is the consumer-side capability guard: look the service up,
+ *   check the shape of the answer instead of trusting it, and **fail closed**
+ *   (`{ ok: false }`): an unresolvable mode withholds the advisory, and the
+ *   caller discloses that withholding on the host side. An unresolvable mode is
+ *   emphatically *not* an invitation to fall back to the deployment default —
+ *   a session that overrode its mode to `danger-full-access` would then be
+ *   diagnosed as if it were confined.
+ *
+ * The call site this module depends on is stable across every line the peer
+ * range claims: `resolve(request?: SandboxPolicyRequest): SandboxExecutionPolicy`
+ * is declared at the same position of `lib/types/index.d.ts` in every published
+ * build from `0.1.2-rc.1` to `0.1.7-rc.1`, and `Agent.session` is present on
+ * the same span of `@deepseek-ai/dsh-agent`.
+ *
+ * @module
+ */
+/**
+ * Whether a mode confines the process it is asked to spawn.
+ * @param mode - the resolved mode.
+ * @returns true for every mode except `danger-full-access`.
+ */
+export function confines(mode) {
+    return mode !== 'danger-full-access';
+}
+/**
+ * Narrow an optional lookup result to the resolver shape.
+ * @param value - whatever `ctx.get('sandboxPolicy')` returned.
+ * @returns the same object, typed as the resolver, or undefined.
+ */
+function asPolicy(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    if (typeof value.resolve !== 'function')
+        return undefined;
+    return value;
+}
+/**
+ * The agent's live session, read defensively.
+ *
+ * `Agent.session` is declared by `@deepseek-ai/dsh-agent`'s runtime face and is
+ * present on every claimed line; it is read as `unknown` here anyway, because a
+ * gate that trusts the shape of its input is the same gate that reports a cause
+ * from the wrong world when the input is not what it expected.
+ * @param agent - the agent whose call failed.
+ * @returns the session object, or undefined.
+ */
+function agentSession(agent) {
+    const session = agent.session;
+    return session !== null && typeof session === 'object' ? session : undefined;
+}
+/**
+ * The mode inside a resolved policy, if it is one this harness defines.
+ * @param resolved - the resolver's return value.
+ * @returns the mode, or undefined when the value is not a recognizable policy.
+ */
+function recognizedMode(resolved) {
+    if (resolved === null || typeof resolved !== 'object')
+        return undefined;
+    const mode = resolved.mode;
+    return mode === 'read-only' || mode === 'workspace-write' || mode === 'danger-full-access'
+        ? mode
+        : undefined;
+}
+/**
+ * Resolve the effective sandbox mode for one agent's call.
+ *
+ * The service is looked up through `ctx.get` — the documented optional lookup —
+ * and the resolver is invoked with the agent's own session, so a session that
+ * logged a `sandbox/mode` override is answered with that override rather than
+ * with the deployment default.
+ * @param ctx - the plugin's context.
+ * @param agent - the agent whose call failed.
+ * @returns the mode, or the reason it could not be resolved.
+ */
+export function resolveSandboxMode(ctx, agent) {
+    const policy = asPolicy(ctx.get('sandboxPolicy'));
+    if (policy === undefined) {
+        return {
+            ok: false,
+            withheld: 'no `sandboxPolicy` service is mounted in this composition, so the effective mode is unknown',
+        };
+    }
+    const session = agentSession(agent);
+    if (session === undefined) {
+        return {
+            ok: false,
+            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 });
+    }
+    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: true, mode };
+}

package/lib/signature.js

@@ -1,5 +1,8 @@
 /**
- * Recognize the Windows ACL provisioning failure that has no path forward.
+ * Recognize the two environment failures this plugin explains, and refuse
+ * everything else.
+ *
+ * ## The ACL provisioning failure (`acl-provisioning`)
  *
  * The harness's Windows sandbox provisions a workspace by writing the
  * directory's DACL and its mandatory-integrity label in **one**
@@ -10,7 +13,7 @@
  * it. Every sandboxed command then fails the same way, forever, because the
  * grant is materialized lazily and nothing is cached on the failure path.
  *
- * Recognizing the string is therefore the whole job of this module, and the
+ * Recognizing the string is therefore the whole job of this half, and the
  * recognition is deliberately narrow:
  *
  * - **Only the two `...NamedSecurityInfoW` operations are classified.** Their
@@ -27,8 +30,32 @@
  *   the advisory can quote the exact line the model and the user are looking
  *   at, and the path can be re-used in the fix command.
  *
+ * ## The persistent-shell startup failure (`pty-startup`)
+ *
+ * `dsh-terminal-bash` throws `PTY shell exited during startup` when the shell
+ * it spawned through the sandbox exits before reaching its first prompt
+ * (`src/session.ts` and `src/index.ts`, both on the same `waitReason ===
+ * 'session_exit'` branch). The text names no cause and, under the `minimal`
+ * preset — whose only shell tool is a persistent PTY — there is no other shell
+ * tool left to fall back on, so the model reads it as "the command failed" and
+ * retries forever. #7638 is the report: 33 consecutive failures under
+ * `workspace-write`, none under `danger-full-access`, with the reporter's own
+ * three-arm control showing the sandbox mode is the discriminator.
+ *
+ * This family is recognized on an **exact line**, not on a substring, and that
+ * is deliberate. The producer's message has no detail field at all — the whole
+ * message is the sentence — so anything that merely *contains* the phrase is
+ * quoting it (a transcript, a log a failing command printed, a pasted issue
+ * body) rather than producing it. The sibling throw on the same branch, `PTY
+ * shell did not reach readiness before startup timeout`, is **not** classified
+ * here: it means the shell started and then did not reach a prompt, which is a
+ * different cause space (a slow or blocked shell) with a different remedy, and
+ * a classifier that names a wrong cause is worse than one that stays silent.
+ *
  * @module
  */
+/** The exact text `dsh-terminal-bash` throws when the shell exits during startup. */
+export const PTY_STARTUP_EXIT = 'PTY shell exited during startup';
 /**
  * The producer's format is fixed by `Win32Error`
  * (`packages/subprocess/win32-process/src/errors.ts`):
@@ -52,7 +79,7 @@ function splitDetail(detail) {
     return { label, path };
 }
 /**
- * Classify one failure message.
+ * Classify one failure message against the ACL family.
  * @param message - the failure text, from the result's `error.message` or its rendered content.
  * @returns the recognized failure, or undefined when this is not a provisioning failure.
  */
@@ -68,14 +95,38 @@ export function classifyProvisioningFailure(message) {
     const klass = api === 'GetNamedSecurityInfoW'
         ? 'read-denied'
         : code === ACCESS_DENIED ? 'apply-denied' : 'apply-other';
-    return { klass, api, win32Code: code, detail, ...splitDetail(detail) };
+    return { family: 'acl-provisioning', klass, api, win32Code: code, detail, ...splitDetail(detail) };
+}
+/**
+ * Classify one failure message as the persistent-shell startup failure.
+ *
+ * Recognition is by **whole line**, because the producer's message is a bare
+ * sentence with no fields of its own: a line equal to
+ * {@link PTY_STARTUP_EXIT} — with only the `Error: ` envelope a tool result adds
+ * in front of it — is the producer. A longer line that happens to contain the
+ * sentence is something quoting it (a transcript, a log the failing command
+ * printed, a pasted issue body), and advising about the sandbox there would be
+ * advice about the wrong thing.
+ * @param message - the failure text, from the result's `error.message` or its rendered content.
+ * @returns the recognized failure, or undefined when this is not one.
+ */
+export function classifyPtyStartupFailure(message) {
+    for (const raw of message.split('\n')) {
+        const line = raw.trim();
+        if (line === PTY_STARTUP_EXIT || line === `Error: ${PTY_STARTUP_EXIT}`) {
+            return { family: 'pty-startup', line: PTY_STARTUP_EXIT };
+        }
+    }
+    return undefined;
 }
 /**
  * The one-line failure the producer wrote, for quoting back verbatim.
  * @param failure - a recognized failure.
- * @returns the message text a `Win32Error` would have produced.
+ * @returns the message text the producing layer would have produced.
  */
 export function failureLine(failure) {
+    if (failure.family === 'pty-startup')
+        return failure.line;
     const suffix = failure.detail.length === 0 ? '' : `: ${failure.detail}`;
     return `${failure.api} failed (Win32 ${failure.win32Code})${suffix}`;
 }