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

package/README.md

@@ -1,31 +1,48 @@
 # @argszero/cordis-plugin-sandbox-grant-advisor
 
-Turns a Windows sandbox **ACL provisioning failure with no path forward** into a
-diagnosis the model — and the user reading the transcript — can act on.
+Turns a sandbox environment failure that has **no path forward** into a
+diagnosis the model — and the user reading the transcript — can act on. Two
+signatures, one mechanism:
 
 ```
-SetNamedSecurityInfoW failed (Win32 5): grantWrite(D:\ws)
+SetNamedSecurityInfoW failed (Win32 5): grantWrite(D:\ws)   # Windows workspace ACL
+PTY shell exited during startup                             # persistent shell × confining mode
 ```
 
+**This plugin is the stopgap for "the error does not name the outstanding
+condition".** It repairs nothing: no ACL is written, no privilege is requested,
+nothing is elevated, no preset is installed and no mode is changed.
+
+## The two failures it recognizes
+
+Both are recognized on the public **`tools/post-execute`** waterfall
+(`@deepseek-ai/dsh-tools`) — the one seam that has all three of: the failure text
+(providers propagate their error unchanged and the tool pipeline settles it as an
+`isError` result), an agent identity to attribute it to (`exec.agent`), and a
+channel that speaks to the model in the same step (`PostToolDecision`'s
+`additionalContexts`, which the agent loop turns into a durable user-role message
+— `packages/core/agent-loop/src/tool-calls.ts`).
+
+That seam, not `ctx.sandbox.confine`: `confine(argv, policy, signal)` sees the
+confinement failure too, but 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.
+
+### 1. Workspace provisioning — the Windows ACL failure (`acl-provisioning`)
+
 Three reports describe this exact line: [discussion #7538], [discussion #7622],
 [discussion #7646]. In each one every sandboxed command fails the same way,
 before it runs, and the error names neither the missing right nor a remedy.
 
-**This plugin is the stopgap for "the error does not name the outstanding
-condition".** It does not repair anything: no ACL is written, no privilege is
-requested, nothing is elevated.
-
-## The failure it recognizes
-
 The Windows backend provisions a workspace by writing the directory's DACL and
 its mandatory-integrity label in **one** `SetNamedSecurityInfoW` call
-(`packages/sandbox/sandbox-windows-acl/src/acl.ts`:
+(`packages/sandbox/sandbox-windows-acl/src/acl.ts`):
 
 ```ts
 if (applyResult !== abi.ERROR_SUCCESS) throwWin32(api, 'SetNamedSecurityInfoW', applyResult, `${label}(${path})`)
 ```
 
-). Two consequences follow from that one line:
+Two consequences follow from that one line:
 
 1. **The label lives in the SACL, and its half is what gets refused.** The
    owner's implicit rights cover only `READ_CONTROL` and `WRITE_DAC`, so the
@@ -45,53 +62,127 @@ cached when it throws** — so the same failure repeats per command (850 calls
 across 39 sessions in #7622; 52,588 output tokens with no output in #7538),
 which is why the loop cannot separate it from ordinary command noise.
 
-## What it does
-
-One listener on the public **`tools/post-execute`** waterfall
-(`@deepseek-ai/dsh-tools`). That seam — not `ctx.sandbox.confine` — because it is
-the only one that has all three of: the failure text (providers propagate their
-error unchanged, and the tool pipeline settles it as an `isError` result), an
-agent identity to attribute it to (`exec.agent`), and a channel that speaks to
-the model in the same step (`PostToolDecision`'s `additionalContexts`, which the
-agent loop turns into a durable user-role message —
-`packages/core/agent-loop/src/tool-calls.ts`).
-
-1. **One durable advisory per agent.** On the first recognized failure, the
-   result is enriched with a user-role notice that names the missing right, the
-   discriminator, and the unelevated fix:
-
-   ```
-   Sandbox provisioning failed — no sandboxed command can run in this workspace until its ACL applies.
-
-   What was reported:
-     SetNamedSecurityInfoW failed (Win32 5): grantWrite(D:\ws)
-
-   Why it is refused while the directory looks writable: that call is a MERGED write ...
-     ... the label half additionally needs WRITE_OWNER on the directory. ...
-
-   Confirm the cause (unelevated) — `icacls` is a normal user command:
-     icacls "D:\ws"
-
-   Fix it (unelevated, one line) and then run the command again:
-     PowerShell: icacls "D:\ws" /grant "$env:USERNAME:(OI)(CI)F"
-     cmd:        icacls "D:\ws" /grant "%USERNAME%:(OI)(CI)F"
-   ```
-
-   The notice carries its own producer-owned `source.kind`
-   (`sandbox-grant-advisor`) — not the retired `plugin` wrapper, which the
-   current session format refuses — and a bounded one-line `summary` for the
-   transcript row. The host log gets one matching `warn` line, so the fact
-   survives outside the transcript too.
-2. **An optional, bounded fail-fast half** (`enforceAfter`, default **0** =
-   off). It refuses a call **before dispatch** only when both hold: the
-   environment has failed provisioning at least `enforceAfter` times, **and**
-   this exact call (tool + canonical arguments) is one this plugin watched fail.
-   The budget is `maxDenials` (default 2), after which the call proceeds again.
-   The budget is per **episode of brokenness**: a call that finally succeeds stops
-   being a denial target and re-arms it, so an environment that breaks twice can
-   be refused twice — while a session can always make progress by spending the
+On the first recognized failure, the result is enriched with:
+
+```
+Sandbox provisioning failed — no sandboxed command can run in this workspace until its ACL applies.
+
+What was reported:
+  SetNamedSecurityInfoW failed (Win32 5): grantWrite(D:\ws)
+
+Why it is refused while the directory looks writable: that call is a MERGED write ...
+  ... the label half additionally needs WRITE_OWNER on the directory. ...
+
+Confirm the cause (unelevated) — `icacls` is a normal user command:
+  icacls "D:\ws"
+
+Fix it (unelevated, one line) and then run the command again:
+  PowerShell: icacls "D:\ws" /grant "$env:USERNAME:(OI)(CI)F"
+  cmd:        icacls "D:\ws" /grant "%USERNAME%:(OI)(CI)F"
+```
+
+### 2. Persistent shell startup (`pty-startup`)
+
+[Discussion #7638] reports the second shape: with the **`minimal` preset** on
+Windows, and under a **confining** sandbox mode (`workspace-write` / `read-only`,
+not `danger-full-access`), **every** shell call dies instantly with
+
+```
+PTY shell exited during startup
+```
+
+The terminal backend spawns the shell through the sandbox
+(`packages/terminal/terminal-bash/src/index.ts`; the throw is in
+`src/session.ts` and `src/index.ts`, both on the same `waitReason ===
+'session_exit'` branch), and there the pseudo-console cannot be created at all,
+so the child exits before its first prompt. Retrying never helps; the message
+points at no cause.
+
+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. That is why the advisory is only ever
+built with the **resolved** mode the failing call actually ran under — from
+`ctx.sandboxPolicy.resolve({ session })`, the same resolver the terminal layer
+calls before spawning, with the same session.
+
+The advisory that follows is addressed to **two different readers**:
+
+```
+Persistent shell failed to start — command execution is unavailable in this session, and retrying cannot fix it.
+
+What was reported:
+  PTY shell exited during startup
+
+The `bash` tool is a PERSISTENT PTY session (a shell that stays alive between calls), and this session's sandbox mode is
+`workspace-write` — 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. ...
+
+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 `preset-minimal` row in your profile patch — `$DSH_HOME/profiles/<profile>/cordis.patch.yml`, or
+     `$DSH_HOME/cordis.patch.yml` for every profile — replacing its `persistent-shell` group with
+     `@deepseek-ai/dsh-tool-pwsh` (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.
+```
+
+The model's instruction is to **stop** — not to run a command (there is no shell
+to run it in) and not to call a fallback shell tool (`minimal` mounts exactly
+**one** platform-selected persistent shell and **no** one-shot shell, by design:
+`.agents/notes/implemented/simplification/2026-09-03-minimal-profiles-persistent-shell-only.md`).
+Naming a tool the failing composition does not mount would be a wrong remedy,
+which is the main risk this family's text is written to avoid.
+
+The remedy is a **patch layer**, not a directory. The pre-declarative
+`$DSH_HOME/.agent-presets/<id>/` preset folder is a plausible-looking trap: it
+still reads as the natural place to put a preset, and nothing in the harness
+reads it any more (`@deepseek-ai/dsh-agent-preset-registry`: the registry
+"neither scans directories nor accepts preset paths"). Preset changes are
+`@deepseek-ai/dsh-agent-preset` rows — an `insert` for a new one, a patch keyed
+by row id (`preset-minimal`) for a change to a shipped one. A test arm asserts
+the advisory never names the dead directory.
+
+## What it does with a recognized failure
+
+1. **One durable advisory per agent, per family.** An agent that hits both
+   families is told about **both**, once each. The notice carries its own
+   producer-owned `source.kind` (`sandbox-grant-advisor`) — not the retired
+   `plugin` wrapper, which the current session format refuses — and a bounded
+   one-line `summary` for the transcript row. The host log gets one matching
+   `warn` line, so the fact survives outside the transcript too.
+2. **A disclosure when it withholds.** The PTY advisory is only sent when the
+   resolved mode actually confines. If the mode is `danger-full-access`, or
+   cannot be resolved at all (no `sandboxPolicy` service mounted, no agent
+   session, a resolver that throws), 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. Withholding is never a guess: an unresolvable mode is *not* an
+   invitation to fall back to the deployment default.
+3. **An optional, bounded fail-fast half** (`enforceAfter`, default **0** =
+   off) — **ACL family only**. It refuses a call **before dispatch**
+   (`tools/pre-execute`) only when both hold: the environment has failed
+   provisioning at least `enforceAfter` times, **and** this exact call (tool +
+   canonical arguments) is one this plugin watched fail. The budget is
+   `maxDenials` (default 2), after which the call proceeds again. The budget is
+   per **episode of brokenness**: a call that finally succeeds stops being a
+   denial target and re-arms it, so an environment that breaks twice can be
+   refused twice — while a session can always make progress by spending the
    budget it has.
 
+   **Why the blocking half does not extend to the PTY family** (it is
+   ACL-only by construction, in the parameter type): 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 there could only pad a session that is already unable to do
+   the thing being refused.
+
 ## Install
 
 ```sh
@@ -124,6 +215,11 @@ Mount it by adding the patch to your profile, or apply the shipped
         enforceAfter: 3
 ```
 
+`include` / `exclude` narrow **both** families: an untracked call is
+transparent to the plugin entirely, so a watched-out shell call produces no PTY
+advisory (and no withholding note either — the configuration said "not our
+story", which is different from "we could not tell").
+
 ## What it deliberately refuses to explain
 
 Recognition is narrow, because a classifier that names the wrong cause is worse
@@ -135,42 +231,59 @@ than one that stays silent.
   problem, and neither are the `LocalFree`, `LockFileEx`,
   `SetConsoleCtrlHandler` or `SetEnvironmentVariableW` failures thrown by the
   same package.
+- **The PTY family is matched on a whole line, not a substring.** The producer's
+  message *is* the sentence (`PTY shell exited during startup`) with no detail
+  field at all, so any longer line that merely contains it is something
+  **quoting** it — a transcript, a log a failing command printed, a pasted issue
+  body — and the harness is not the producer.
+- **The sibling throw is not classified.** `PTY shell did not reach readiness
+  before startup timeout` means the shell started and then did not reach a
+  prompt: a different cause space (a slow or blocked shell) with a different
+  remedy.
 - **The Win32 code is kept, not flattened.** `ERROR_ACCESS_DENIED` (5) is the
   case the documented prerequisite explains; another code gets a different
   paragraph that says so instead of borrowing the same sentence.
 - **A successful command whose *output* contains the line is not a failure.**
   The gate is the result's error state, not the presence of the text — reading a
   log file that quotes the error must not trigger advice.
-- **Only one advisory per agent.** The environment is explained once; repeating
-  it per failed command would be noise competing with the failure itself.
+- **Only one advisory per agent, per family.** The environment is explained
+  once; repeating it per failed command would be noise competing with the
+  failure itself.
 
 ## Honest boundaries
 
-- **The Windows path itself cannot be witnessed on macOS**, where this plugin was
-  built. What the test suite proves is the decision layer — classification, the
-  once-per-agent rule, the fail-fast budget and its self-feeding guard, and the
-  wiring to a real cordis `Context` and the real `ToolRuntime` — driven by
-  fixtures that throw the producer's exact error shape (`Win32Error`,
-  `packages/subprocess/win32-process/src/errors.ts`). It does **not** prove that
-  `icacls ... :(OI)(CI)F` fixes a given machine; that is the user's one-line
-  experiment, and the advisory says so.
+- **The Windows path itself cannot be witnessed on macOS**, where this plugin
+  was built. What the test suite proves is the decision layer — classification
+  of both families, the once-per-agent-per-family rule, the sandbox-mode gate
+  and its fail-closed behaviour, the fail-fast budget and its self-feeding
+  guard, and the wiring to a real cordis `Context` and the real `ToolRuntime` —
+  driven by fixtures that throw the producers' exact error shapes
+  (`Win32Error`, `packages/subprocess/win32-process/src/errors.ts`; the
+  terminal throws, `packages/terminal/terminal-bash/src/{index,session}.ts`). It
+  does **not** prove that `icacls ... :(OI)(CI)F` fixes a given machine, nor that
+  a given Windows host reproduces the PTY startup failure; those are the user's
+  one-line experiment and the reporter's own control, and both advisories say
+  where they stop.
 - **It repairs nothing and elevates nothing.** If the directory really is
-  Full-control for the caller, the remaining hypothesis is `SeSecurityPrivilege`
-  — i.e. the backend's documented prerequisite would be wrong. That is an
-  upstream question; the advisory states the discriminator rather than assuming
-  the answer.
-- **Delivery to the model is the agent loop's.** `additionalContexts` are ferried
-  on the settled result here and appended as durable user-role events by
+  Full-control for the caller, the remaining ACL hypothesis is
+  `SeSecurityPrivilege` — i.e. the backend's documented prerequisite would be
+  wrong. That is an upstream question; the advisory states the discriminator
+  rather than assuming the answer.
+- **Delivery to the model is the agent loop's.** `additionalContexts` are
+  ferried on the settled result here and appended as durable user-role events by
   `agent-loop`; a direct `ctx.tools.execute()` caller with no agent gets no
   advisory (and no agent to explain anything to).
 - **It complements `@argszero/cordis-plugin-repeat-guard-escalation`, it does not
   replace it.** That guard keys on **call identity** (identical arguments
   retried); this one keys on the **environment signature**, which is how several
   *different* commands share one cause. Mounting both is sensible.
-- **The real fix is upstream.** `grantWrite` already computes
-  `hasExactGrant` / `hasExactDeny` / `hasExactLabel` and discards which one was
-  false, so the diagnostic that turns a 52-minute detour into one line belongs at
-  that site — next to the preflight the grant's lazy materialization wants.
+- **The real fix is upstream, in both families.** For the ACL failure,
+  `grantWrite` already computes `hasExactGrant` / `hasExactDeny` /
+  `hasExactLabel` and discards which one was false, so the diagnostic that turns
+  a 52-minute detour into one line belongs at that site. For the PTY failure,
+  the 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
+  for both.
 
 ## Compatibility
 
@@ -188,6 +301,11 @@ Harness peers — all three carry the **same** range, quoted in full on purpose
   that reason.
 - `@deepseek-ai/cordis@^4.0.2`.
 
+`@deepseek-ai/dsh-sandbox-policy` is **not** a peer: the PTY family's mode
+lookup is a guarded, structural one (`ctx.get('sandboxPolicy')`) precisely so a
+composition that does not mount the service degrades to silence instead of
+failing to load. See `src/mode.ts`.
+
 Probed at the newest build of every line the range admits — `0.1.2-rc.1`,
 `0.1.3-alpha.2`, `0.1.5-rc.3`, `0.1.6-alpha.2`, `0.1.7-rc.1` (the build the third
 report ran) — with `npm run test:probe-lines`, which derives those builds from
@@ -200,6 +318,7 @@ left claimed.
 ```sh
 npm install
 npm test                 # tsc, then the suite (real cordis + real ToolRuntime)
+npm run test:inject      # defect injection: mutate the source, rebuild, require the suite to go red
 npm run test:probe-lines # install the newest build of each admitted line and run the suite against it
 npm run test:probe-lines -- 0.1.7-rc.1  # one line only
 ```
@@ -207,6 +326,16 @@ npm run test:probe-lines -- 0.1.7-rc.1  # one line only
 The suite is mostly control arms: a guard that explains the wrong failure, or
 refuses a call that would have worked, is worse than one that stays silent.
 
+`test:inject` exists because an arm nobody has seen fail proves nothing. It
+mutates the decision layer one defect at a time — the mode gate removed, the
+PTY message matched as a substring, the preset remedy pointed back at the dead
+legacy directory, the two families collapsed into one bookkeeping slot, the
+advisory delivered per call instead of per agent — and requires that specific
+arms fail. It reports `SILENT ARMS: none` when every arm bites, restores the
+source in a `finally`, and prints `EQUIVALENT` (with the reason) for a mutation
+the current runtime cannot distinguish rather than counting it as a pass.
+
 [discussion #7538]: https://github.com/deepseek-ai/deepseek-harness/discussions/7538
 [discussion #7622]: https://github.com/deepseek-ai/deepseek-harness/discussions/7622
 [discussion #7646]: https://github.com/deepseek-ai/deepseek-harness/discussions/7646
+[discussion #7638]: https://github.com/deepseek-ai/deepseek-harness/discussions/7638

package/cordis.patch.yml

@@ -45,6 +45,24 @@
 # is off by default on purpose: it may only refuse a call it has watched fail in
 # this environment, and it is bounded by `maxDenials`, because a plugin that can
 # stop command execution must never be the reason a session cannot finish.
+#
+# A SECOND family is recognized on the same seam (#7638): with the `minimal`
+# preset and a confining sandbox mode, every shell call dies instantly with
+#
+#   PTY shell exited during startup
+#
+# The terminal backend cannot create the pseudo-console inside the sandbox, so
+# the child exits before its first prompt; retrying never helps and `minimal`
+# mounts no fallback shell tool. That advisory states the resolved mode, tells
+# the model to STOP rather than retry, and hands the user a preset choice — it
+# never names a command to run (there is no shell to run it in) and never names
+# a shell tool the failing composition does not mount. It is sent only when the
+# mode the call actually ran under confines; otherwise the failure is left
+# untouched and the host log says so once (silence alone would read as "the
+# sandbox is not the cause", which this plugin cannot claim). The blocking half
+# above deliberately does NOT cover this family: its remedy is a patch-layer
+# change the user makes between sessions, not a command that repairs the
+# running one.
 
 - insert:
     - id: sandbox-grant-advisor

package/lib/advice.js

@@ -1,29 +1,62 @@
 /**
- * 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';
+/** 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';
 /** Placeholder the user replaces with the directory the error named. */
 const PLACEHOLDER = '<the directory from the error line above>';
 /**
@@ -60,13 +93,33 @@ function diagnosis(failure) {
 }
 /**
  * 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.',
         '',
@@ -90,8 +143,67 @@ export function advisoryText(failure, href) {
         '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.