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

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}`;
 }

package/lib/state.js

@@ -6,21 +6,52 @@
  * failing call carries `exec.agent`, one agent owns one session, and a WeakMap
  * keyed by the agent object lets a finished session's state be collected.
  *
- * Two counters, two meanings — keeping them apart is what stops the plugin from
- * feeding on itself:
+ * ## One record per family
  *
- * - `observations` counts *provisioning failures of this environment*, i.e.
+ * This plugin now recognizes two unrelated environment failures — a workspace
+ * that cannot be provisioned (`acl-provisioning`) and a persistent shell that
+ * cannot start (`pty-startup`). They are different diagnoses with different
+ * remedies, so their bookkeeping is kept apart under one agent
+ * ({@link AgentState.families}): an agent that hits both is told about both,
+ * and an agent that has already been told about one is still told about the
+ * other. Sharing one "already advised" flag would silently swallow the second
+ * diagnosis, which is the failure mode this split exists to prevent.
+ *
+ * Three counters, three meanings — keeping them apart is what stops the plugin
+ * from feeding on itself:
+ *
+ * - `observations` counts *failures of this environment in this family*, i.e.
  *   tool results the environment itself produced. A call this plugin denied is
- *   not one of them, even though its denial text quotes the Win32 line.
+ *   not one of them, even though its denial text quotes the producer's line.
  * - `failingKeys` holds the call identities (tool + canonical arguments) that
  *   have already failed this way. The fail-fast half may only refuse a call it
  *   has *watched fail* — never a call it merely recognizes as similar.
- *
- * `denials` is spent per *episode*: it is re-armed when a watched call finally
- * succeeds (see `observeSuccess`), not carried for the whole session.
+ * - `denials` is spent per *episode*: it is re-armed when a watched call finally
+ *   succeeds (see `observeSuccess`), not carried for the whole session.
  *
  * @module
  */
+/** The state of an agent this plugin has never observed. */
+export function emptyState() {
+    return { families: {}, withheld: false };
+}
+/** The record for one family, if this agent has one. */
+function familyOf(state, family) {
+    return state?.families[family];
+}
+/**
+ * Replace one family's record, leaving the others (and the withheld flag) alone.
+ * @param state - the agent's current state, or undefined on first sight.
+ * @param family - the family being updated.
+ * @param record - the family's new record.
+ * @returns the updated state.
+ */
+function withFamily(state, family, record) {
+    return {
+        families: { ...state?.families, [family]: record },
+        withheld: state?.withheld ?? false,
+    };
+}
 /**
  * Canonicalize a parsed argument value into a stable string.
  *
@@ -63,46 +94,91 @@ export function callKey(name, args) {
     return `${name}(${canonicalize(args)})`;
 }
 /**
- * Record one observed provisioning failure.
+ * Record one observed failure in one family.
  * @param state - the agent's current state, or undefined on first sight.
+ * @param family - the family the failure belongs to.
  * @param failure - the recognized failure.
  * @param key - the identity of the call that failed.
  * @returns the updated state.
  */
-export function observe(state, failure, key) {
-    const failingKeys = new Set(state?.failingKeys ?? []);
+export function observe(state, family, failure, key) {
+    const previous = familyOf(state, family);
+    const failingKeys = new Set(previous?.failingKeys ?? []);
     failingKeys.add(key);
-    return {
-        observations: (state?.observations ?? 0) + 1,
+    return withFamily(state, family, {
+        observations: (previous?.observations ?? 0) + 1,
         last: failure,
         failingKeys,
-        denials: state?.denials ?? 0,
-        advised: state?.advised ?? false,
+        denials: previous?.denials ?? 0,
+        advised: previous?.advised ?? false,
+    });
+}
+/**
+ * Whether this family's durable advisory has already been delivered.
+ * @param state - the agent's current state, or undefined.
+ * @param family - the family in question.
+ * @returns true when the advice is already in the session.
+ */
+export function advisedOf(state, family) {
+    return familyOf(state, family)?.advised ?? false;
+}
+/**
+ * Mark one family's durable advisory as delivered.
+ * @param state - the agent's current state.
+ * @param family - the family that was advised.
+ * @returns the updated state.
+ */
+export function recordAdvice(state, family) {
+    const previous = familyOf(state, family);
+    if (previous === undefined)
+        return state;
+    return withFamily(state, family, { ...previous, advised: true });
+}
+/**
+ * Record that a recognized failure was withheld from the model.
+ * @param state - the agent's current state, or undefined on first sight.
+ * @returns the updated state.
+ */
+export function recordWithheld(state) {
+    return {
+        families: { ...state?.families },
+        withheld: true,
     };
 }
 /**
  * Record that a call carrying the same identity as a previously failing one
- * succeeded. The environment worked at least once for that call, so the entry
- * stops justifying a denial — and is dropped rather than kept, so a later
- * failure re-earns it.
+ * succeeded — in **every** family that was watching that identity.
+ *
+ * The environment worked at least once for that call, so the entry stops
+ * justifying a denial — and is dropped rather than kept, so a later failure
+ * re-earns it. A success is evidence about the environment, not about one
+ * diagnosis: the same call cannot have started working for one family's reason
+ * and not the other's.
  *
- * The denial budget is re-armed at the same moment, and only then. Measured
- * consequence: without it the budget is per agent for the whole session, which
- * makes the entry above unobservable — past `maxDenials` this plugin refuses
- * nothing ever again, so clearing the key would change no decision. With it the
- * bound reads as "at most `maxDenials` refusals per episode of brokenness": an
- * environment that breaks, is repaired and breaks again may be refused again,
- * while a session can always make progress by spending the budget.
+ * Each affected family's denial budget is re-armed at the same moment, and only
+ * then. Measured consequence: without it the budget is per agent for the whole
+ * session, which makes the entry above unobservable — past `maxDenials` this
+ * plugin refuses nothing ever again, so clearing the key would change no
+ * decision. With it, the bound reads as "at most `maxDenials` refusals per
+ * episode of brokenness": an environment that breaks, is repaired and breaks
+ * again may be refused again, while a session can always make progress by
+ * spending the budget.
  * @param state - the agent's current state.
  * @param key - the identity of the call that just succeeded.
- * @returns the updated state, unchanged when the key was not failing.
+ * @returns the updated state, unchanged when no family was watching the key.
  */
 export function observeSuccess(state, key) {
-    if (!state.failingKeys.has(key))
+    const watched = Object.entries(state.families)
+        .filter(([, record]) => record.failingKeys.has(key));
+    if (watched.length === 0)
         return state;
-    const failingKeys = new Set(state.failingKeys);
-    failingKeys.delete(key);
-    return { ...state, failingKeys, denials: 0 };
+    let next = state;
+    for (const [family, record] of watched) {
+        const failingKeys = new Set(record.failingKeys);
+        failingKeys.delete(key);
+        next = withFamily(next, family, { ...record, failingKeys, denials: 0 });
+    }
+    return next;
 }
 /**
  * Whether a call may be refused before dispatch.
@@ -112,34 +188,35 @@ export function observeSuccess(state, key) {
  * fail. The second condition is what keeps the fail-fast half from blocking a
  * workaround: a different command, or the same command under a different policy
  * after the user changed configuration, has no key here.
+ *
+ * Only the `acl-provisioning` family ever reaches this question; see the
+ * `denialText` doc for why the blocking half does not extend to `pty-startup`.
  * @param state - the agent's current state, or undefined.
+ * @param family - the family whose threshold is being asked about.
  * @param key - the identity of the call about to dispatch.
  * @param enforceAfter - the configured threshold; 0 disables the half entirely.
  * @param maxDenials - the configured denial budget.
  * @returns whether to deny.
  */
-export function shouldDeny(state, key, enforceAfter, maxDenials) {
-    if (enforceAfter === 0 || state === undefined)
+export function shouldDeny(state, family, key, enforceAfter, maxDenials) {
+    const record = familyOf(state, family);
+    if (enforceAfter === 0 || record === undefined)
         return false;
-    if (state.observations < enforceAfter)
+    if (record.observations < enforceAfter)
         return false;
-    if (state.denials >= maxDenials)
+    if (record.denials >= maxDenials)
         return false;
-    return state.failingKeys.has(key);
+    return record.failingKeys.has(key);
 }
 /**
  * Spend one denial.
  * @param state - the agent's current state.
+ * @param family - the family being denied.
  * @returns the updated state.
  */
-export function recordDenial(state) {
-    return { ...state, denials: state.denials + 1 };
-}
-/**
- * Mark the durable advisory as delivered.
- * @param state - the agent's current state.
- * @returns the updated state.
- */
-export function recordAdvice(state) {
-    return { ...state, advised: true };
+export function recordDenial(state, family) {
+    const previous = familyOf(state, family);
+    if (previous === undefined)
+        return state;
+    return withFamily(state, family, { ...previous, denials: previous.denials + 1 });
 }

package/lib/types/advice.d.ts

@@ -1,38 +1,112 @@
 /**
- * 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:
- *
- * - **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.
+ * by a test, one family at a time. The two families are shaped by the same two
+ * questions, and they answer them differently:
+ *
+ * - **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 type { ProvisioningFailure } from './signature.js';
-/** The upstream threads this advisory is a stopgap for. */
-export declare const DISCUSSIONS = "#7538 / #7622 / #7646";
+import type { ProvisioningFailure, RecognizedFailure } from './signature.js';
+import type { SandboxModeName } from './mode.js';
+/** The upstream threads the ACL advisory is a stopgap for. */
+export declare const ACL_DISCUSSIONS = "#7538 / #7622 / #7646 / #7720";
+/** The upstream thread the persistent-shell advisory is a stopgap for. */
+export declare const PTY_DISCUSSIONS = "#7638";
 /** The documented prerequisite, quoted from the backend's README. */
 export declare 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 declare 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 declare const GLOBAL_PATCH = "$DSH_HOME/cordis.patch.yml";
+/** The row id the shipped `minimal` preset is declared under. */
+export declare const MINIMAL_PRESET_ROW = "preset-minimal";
+/** The one-shot shell tool the `standard` preset mounts on Windows. */
+export declare 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 declare const NOT_FIXES: readonly ["takeown /F \"<dir>\" /R /D Y", "icacls \"<dir>\" /reset /T /C"];
+/** What the caller knows about the failing call, beyond the failure text. */
+export interface AdvisoryContext {
+    /** URL quoted in place of the discussions list; optional. */
+    readonly href?: string;
+    /** The tool whose call failed, quoted back so the advice is about that call. */
+    readonly tool?: string;
+    /**
+     * The sandbox mode the failing call ran under. Required by the
+     * `pty-startup` family — the whole diagnosis is the mode — and unused by the
+     * ACL family.
+     */
+    readonly mode?: SandboxModeName;
+}
 /**
  * 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 href - optional URL shown for the upstream thread.
- * @returns the user-role notice text, with the fix commands ready to paste.
+ * @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 declare function advisoryText(failure: ProvisioningFailure, href?: string): string;
+export declare function advisoryText(failure: RecognizedFailure, context?: AdvisoryContext): string;
 /**
  * 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.