@argszero/dsh-cancel-cause-guard 0.0.0-stage → 0.2.0

package/lib/cause.js

@@ -0,0 +1,205 @@
+/**
+ * The closed union the harness writes into `turn/end`, and the normalization
+ * that makes any other value a member of it.
+ *
+ * ## Why a value outside the union is not a cosmetic problem
+ *
+ * `ReactLoopAgent`'s turn body reads the cancellation cause back out of the
+ * signal and switches on it (`abortedCancelCause`, `agent-loop/src/agent.ts:80`):
+ *
+ * ```ts
+ * const cause = signal.reason as AgentCancelCause
+ * switch (cause.kind) {
+ *   case 'user': case 'parent': case 'disposed': return { kind: cause.kind }
+ *   case 'hook': return { kind: 'hook', reason: cause.reason }
+ *   default: return assertNever(cause)
+ * }
+ * ```
+ *
+ * That function is called **inside the turn's `catch`**. A value outside the
+ * union therefore throws before the catch body assigns `turnEnds`, which is
+ * still its `null` initializer, and the `finally` appends unconditionally:
+ *
+ * ```ts
+ * let turnEnds: TurnEndReason | null = null            // agent.ts:310
+ * ...
+ * } finally {
+ *   this.session.append('turn/end', { turn, reason: turnEnds! })   // agent.ts:385
+ * }
+ * ```
+ *
+ * The row lands on disk as `{"type":"turn/end","data":{"turn":N,"reason":null}}`.
+ * Nothing rejects it on the way: the append-time validator inspects surface
+ * message slots, `request/header` and `tool/result` only, so this field is a
+ * TypeScript-only invariant. Readers then dereference it — the chat client does
+ * `location.turn.end?.data.reason.kind`
+ * (`ui-chat/src/client/contract/turn-process.ts:72`) — and one such row throws
+ * while the conversation view renders, which blanks the whole chat area.
+ * Reported three times: discussions #8832, #9156 and #9646.
+ *
+ * ## Two shapes reach it, and only one of them looks like a mistake
+ *
+ * - an object whose `kind` is missing or unknown (`{ kind: 'thinking-loop' }`),
+ *   which `assertNever` refuses; and
+ * - a value that is not an object at all — most often `undefined`, from a
+ *   caller whose own declaration made the argument optional. `cause.kind` on
+ *   `undefined` throws just as effectively, one line earlier.
+ *
+ * Both are normalized here. `hook` is the member the union reserves for
+ * plugins, so a normalized cause says what actually happened: a plugin
+ * cancelled the turn, and the reason names which one.
+ *
+ * @module @argszero/dsh-cancel-cause-guard/cause
+ */
+/** Bound on a minted reason when the configuration names none. */
+export const DEFAULT_MAX_REASON_CHARS = 200;
+/** The reason text standing in for a cause that carried no name at all. */
+export const UNSPECIFIED_REASON = 'unspecified';
+/** The union member a value from outside the union is carried under. */
+export const CARRIER_KIND = 'hook';
+/**
+ * Whether a value is already exactly one of the four union members.
+ *
+ * `hook` is held to the stricter test: its `reason` is part of the member's
+ * contract, and a `hook` whose reason is not a string is normalized rather than
+ * passed through, so that everything downstream of this plugin can rely on the
+ * field being text.
+ * @param cause - the value a caller passed to `Agent.cancel`.
+ * @returns whether the value can be recorded as-is.
+ */
+export function isCancelCause(cause) {
+    switch (readKind(cause)) {
+        case 'user':
+        case 'parent':
+        case 'disposed':
+            return true;
+        case 'hook':
+            return typeof readField(cause, 'reason') === 'string';
+        default:
+            return false;
+    }
+}
+/**
+ * Turn any cancellation cause into a member of the closed union.
+ *
+ * A value that is already a member is returned **unchanged** (same reference),
+ * so the common path allocates nothing and an `{ kind: 'user' }` a caller may
+ * still be holding is the object the loop reads back.
+ * @param cause - the value a caller passed to `Agent.cancel`.
+ * @param options - the reason override and the reason bound.
+ * @returns a member of `AgentCancelCause`.
+ */
+export function normalizeCancelCause(cause, options = {}) {
+    if (isCancelCause(cause))
+        return cause;
+    const limit = options.maxReasonChars ?? DEFAULT_MAX_REASON_CHARS;
+    if (options.reason !== undefined && options.reason.length > 0) {
+        return { kind: CARRIER_KIND, reason: truncate(options.reason, limit) };
+    }
+    if (readKind(cause) === CARRIER_KIND) {
+        // The member is right; only its reason field is not text.
+        return { kind: CARRIER_KIND, reason: reasonText(readField(cause, 'reason'), limit) };
+    }
+    return { kind: CARRIER_KIND, reason: reasonText(cause, limit) };
+}
+/**
+ * The reason text for one value, preferring whatever name it carried.
+ *
+ * The preference order is deliberate: a caller that passed
+ * `{ kind: 'thinking-loop' }` meant the token `thinking-loop`, and a reason
+ * reading `thinking-loop` is more useful to the person reading the session than
+ * the JSON it was embedded in.
+ * @param value - the value to name, or the reason field of a `hook` cause.
+ * @param maxChars - bound on the result.
+ * @returns a non-empty, bounded string.
+ */
+export function reasonText(value, maxChars = DEFAULT_MAX_REASON_CHARS) {
+    if (typeof value === 'string') {
+        return value.trim().length === 0 ? UNSPECIFIED_REASON : truncate(value, maxChars);
+    }
+    if (value === undefined || value === null)
+        return UNSPECIFIED_REASON;
+    const named = carriedKind(value);
+    if (named !== undefined)
+        return truncate(named, maxChars);
+    return truncate(plainText(value), maxChars);
+}
+/**
+ * A descriptive rendering of a value for a log line.
+ *
+ * Separate from {@link reasonText} because the log is read by whoever has to
+ * find the producer, and there the JSON of the offending value is the useful
+ * form — including the `undefined` that {@link reasonText} deliberately hides
+ * behind `unspecified`.
+ * @param value - the value to describe.
+ * @param maxChars - bound on the result.
+ * @returns a bounded, single-line rendering.
+ */
+export function describeValue(value, maxChars = DEFAULT_MAX_REASON_CHARS) {
+    if (value === undefined)
+        return 'undefined';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return truncate(JSON.stringify(value), maxChars);
+    return truncate(plainText(value), maxChars);
+}
+/** The `kind` a value carries, when that is a non-empty string. */
+function carriedKind(value) {
+    const kind = readKind(value);
+    return typeof kind === 'string' && kind.trim().length > 0 ? kind : undefined;
+}
+/**
+ * One field of a value, read without letting a hostile accessor escape.
+ *
+ * It runs inside `cancel`: a guard that threw on the way to naming a cause would
+ * abort the turn in the guard rather than in its caller, which is strictly worse
+ * than the defect. A value whose `kind` cannot be read is therefore treated as a
+ * value with no `kind` at all.
+ */
+function readField(value, field) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    try {
+        return value[field];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The `kind` a value carries, read through {@link readField}. */
+function readKind(value) {
+    return readField(value, 'kind');
+}
+/** A string for any value, never throwing on the ones JSON refuses. */
+function plainText(value) {
+    if (typeof value === 'function')
+        return `function ${value.name ?? ''}`.trim();
+    try {
+        const json = JSON.stringify(value);
+        if (typeof json === 'string' && json.length > 0)
+            return json;
+    }
+    catch {
+        // A circular structure, a BigInt, or a throwing `toJSON`.
+    }
+    try {
+        return String(value);
+    }
+    catch {
+        // A proxy or an object whose `toString` is itself hostile. This module runs
+        // inside `cancel`, and a guard that threw while naming a cause would be the
+        // defect it exists to prevent.
+        return UNSPECIFIED_REASON;
+    }
+}
+/**
+ * Bound one reason so a hostile value cannot write a wall of text into the log.
+ * Shared with the durable backstop, which mints a reason of its own.
+ * @param text - the reason text.
+ * @param maxChars - the bound, in characters.
+ * @returns the text, cut to the bound with a trailing ellipsis when it had to be.
+ */
+export function truncate(text, maxChars) {
+    return text.length <= maxChars ? text : `${text.slice(0, maxChars - 1)}…`;
+}

package/lib/config.js

@@ -0,0 +1,65 @@
+/**
+ * Configuration resolution for the cancellation-cause guard.
+ *
+ * The surface is deliberately four fields. A guard that rewrites a value on
+ * paths as hot as cancellation and the session append has to be readable in one
+ * sitting, and every knob it does not have is a way for an operator to be
+ * surprised by what it did.
+ *
+ * An unknown key is refused rather than ignored: a misspelled `mode` that mounts
+ * and guards nothing is how an operator believes a guard is in force when it is
+ * not — the same refusal `dsh-tool-output-budget` makes, for the same reason.
+ *
+ * @module @argszero/dsh-cancel-cause-guard/config
+ */
+import { DEFAULT_MAX_REASON_CHARS, UNSPECIFIED_REASON } from "./cause.js";
+/** Defaults for a guard whose only job is to keep a session readable. */
+export const DEFAULTS = Object.freeze({
+    mode: 'normalize',
+    reason: undefined,
+    maxReasonChars: DEFAULT_MAX_REASON_CHARS,
+    backstop: true,
+});
+const CONFIG_KEYS = new Set(['mode', 'reason', 'maxReasonChars', 'backstop']);
+const MODES = new Set(['normalize', 'observe']);
+/**
+ * Resolve, validate and detach the guard configuration.
+ * @param config - raw plugin configuration, possibly empty.
+ * @returns a detached, frozen configuration.
+ * @throws {Error} when a key is unknown, a mode is not one this plugin has, a
+ *   reason is not non-empty text, or the bound is not a positive integer.
+ */
+export function resolveConfig(config = {}) {
+    if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+        throw new Error('cancel-cause-guard config: must be an object');
+    }
+    for (const key of Object.keys(config)) {
+        if (!CONFIG_KEYS.has(key)) {
+            throw new Error(`cancel-cause-guard config: unknown key "${key}" `
+                + '(allowed: mode, reason, maxReasonChars, backstop)');
+        }
+    }
+    const mode = config.mode ?? DEFAULTS.mode;
+    if (typeof mode !== 'string' || !MODES.has(mode)) {
+        throw new Error('cancel-cause-guard config: mode must be "normalize" or "observe"');
+    }
+    const maxReasonChars = config.maxReasonChars ?? DEFAULTS.maxReasonChars;
+    if (!Number.isSafeInteger(maxReasonChars) || maxReasonChars < 1) {
+        throw new Error('cancel-cause-guard config: maxReasonChars must be a positive integer');
+    }
+    // A reason override of `''` would make the normalized cause say nothing at
+    // all, which is the one outcome a *reason* field exists to prevent. `undefined`
+    // is the "name it after the value the caller passed" default; an empty string
+    // is a mistake, and is reported as one.
+    const reason = config.reason;
+    if (reason !== undefined && (typeof reason !== 'string' || reason.trim().length === 0)) {
+        throw new Error(`cancel-cause-guard config: reason must be non-empty text, or absent to name the cause `
+            + `after the value that produced it (the default resolves to "${UNSPECIFIED_REASON}" only `
+            + 'for a cause that carried no name)');
+    }
+    const backstop = config.backstop ?? DEFAULTS.backstop;
+    if (typeof backstop !== 'boolean') {
+        throw new Error('cancel-cause-guard config: backstop must be true or false');
+    }
+    return Object.freeze({ mode, reason, maxReasonChars, backstop });
+}

package/lib/guard.js

@@ -0,0 +1,139 @@
+/**
+ * One agent's `cancel`, shadowed so that a cause from outside the closed union
+ * never reaches the loop's `assertNever`.
+ *
+ * ## Why the seam is the instance
+ *
+ * There is no event on the cancellation path and no hook in the append-time
+ * validator: `validateSessionEventData` inspects surface message slots,
+ * `request/header` and `tool/result`, and `turn/end.reason` is a TypeScript-only
+ * invariant, so nothing on the write path can refuse the row that poisons a
+ * session. What the plugin does have is the live agent instance, handed over by
+ * `agent/created` — a `ctx.serial` dispatch that `AgentRegistry.announce`
+ * **awaits** (`packages/core/agent/src/index.ts:550`), so a listener that
+ * settles before its first turn can still change how that agent behaves:
+ *
+ * ```ts
+ * await this.ctx.serial(entry.carrier, 'agent/created', { agent: entry.agent, source, signal })
+ * ```
+ *
+ * `ReactLoopAgent.cancel` is a prototype method (`agent-loop/src/agent.ts:175`),
+ * so an **own** property of that name shadows it for every instance-level
+ * caller — the loop's own `agent.cancel({ kind: 'user' })`
+ * (`agent/src/archive-admission.ts:36`, `agent-loop/src/index.ts:789`), the chat
+ * client's stop button, and any third-party plugin. All of them are covered by
+ * one property write, which is why this is a guard rather than a per-producer
+ * patch.
+ *
+ * ## What the wrapper does, and what it deliberately does not
+ *
+ * It normalizes, forwards, and reports — in that order, and nothing else. It
+ * does not refuse a cancellation (a plugin that stopped a stop would be worse
+ * than the defect), does not touch the options, and does not inspect or rewrite
+ * anything but the cause. A value that is already a union member is forwarded
+ * **by reference**, so the object the loop reads back out of the signal is the
+ * object the caller passed.
+ *
+ * The wrapper binds the original to the agent it came from. A caller holding a
+ * detached `const cancel = agent.cancel` would otherwise have reached the
+ * original with no receiver at all; binding it is the reading the method's own
+ * body requires (`this.phase`, `this.inbox`), and it makes the shadow more
+ * faithful than the property it replaces.
+ *
+ * @module @argszero/dsh-cancel-cause-guard/guard
+ */
+import { describeValue, isCancelCause, normalizeCancelCause } from "./cause.js";
+/**
+ * The brand an installed wrapper carries.
+ *
+ * `Symbol.for` rather than a module-local symbol: two copies of this plugin
+ * loaded into one process — the plugin mounted by two profile entries, or a
+ * second copy pulled in beside the first — would otherwise each install a
+ * wrapper, and the inner one would normalize a cause the outer had already
+ * normalized. With a registry-wide key the second mount recognises the first
+ * and leaves it alone.
+ */
+export const GUARD_MARK = Symbol.for('argszero.dsh-cancel-cause-guard/guarded');
+/**
+ * Shadow one agent's `cancel` with a normalizing wrapper.
+ *
+ * Every refusal is reported as an {@link GuardOutcome} rather than thrown: an
+ * agent this plugin could not guard is a session that keeps the defect, not a
+ * reason to fail the lifecycle edge that delivered it.
+ * @param agent - the live agent instance, as handed over by `agent/created`.
+ * @param options - the guard's behaviour and its report callback.
+ * @returns the outcome and an undo.
+ */
+export function guardCancel(agent, options) {
+    const current = agent.cancel;
+    if (typeof current !== 'function')
+        return { outcome: 'no-cancel', restore: () => { } };
+    if (current[GUARD_MARK] === true) {
+        return { outcome: 'already-guarded', restore: () => { } };
+    }
+    const original = current;
+    // Whether the property was the instance's own before the guard: a prototype
+    // method must be revealed again by deleting the shadow, an own property by
+    // writing the old value back. Writing the prototype method back as an own
+    // property would look like a successful restore while changing the object.
+    const hadOwn = Object.prototype.hasOwnProperty.call(agent, 'cancel');
+    const wrapper = function guardedCancel(cause, cancelOptions) {
+        const decided = decide(cause, options);
+        Reflect.apply(original, agent, [decided, cancelOptions]);
+    };
+    wrapper[GUARD_MARK] = true;
+    try {
+        ;
+        agent.cancel = wrapper;
+    }
+    catch {
+        // A sealed instance, or a `cancel` the agent defined without a setter.
+        return { outcome: 'not-writable', restore: () => { } };
+    }
+    // A refusal to write is not always a throw — a frozen object in sloppy mode
+    // would simply ignore it — so the install is confirmed by reading it back.
+    if (agent.cancel !== wrapper) {
+        return { outcome: 'not-writable', restore: () => { } };
+    }
+    let installed = true;
+    return {
+        outcome: 'patched',
+        restore: () => {
+            if (!installed)
+                return;
+            installed = false;
+            // Only unwind a shadow that is still ours: a later guard, or the agent
+            // itself, may have replaced it, and undoing that would be a third party's
+            // state being written by this one.
+            if (agent.cancel !== wrapper)
+                return;
+            if (hadOwn)
+                agent.cancel = original;
+            else
+                delete agent.cancel;
+        },
+    };
+}
+/**
+ * The cause to forward, and the report that says why.
+ * @param cause - the value the caller passed.
+ * @param options - the guard's behaviour and its report callback.
+ * @returns the value to hand the original `cancel`.
+ */
+function decide(cause, options) {
+    if (isCancelCause(cause))
+        return cause;
+    const normalized = normalizeCancelCause(cause, {
+        reason: options.reason,
+        maxReasonChars: options.maxReasonChars,
+    });
+    options.onNormalized({
+        original: cause,
+        normalized: normalized,
+        described: describeValue(cause, options.maxReasonChars),
+    });
+    // In `observe` mode the report is the whole contribution: the caller's value
+    // goes through untouched, so the turn fails exactly as it would have, and the
+    // only difference is that the log now names what produced it.
+    return options.mode === 'observe' ? cause : normalized;
+}

package/lib/index.js

@@ -0,0 +1,251 @@
+/**
+ * A prevention guard for the one `turn/end` row that makes a whole conversation
+ * view unreadable.
+ *
+ * ## The defect
+ *
+ * A plugin calls `agent.cancel(cause)` with a value that is not a member of the
+ * closed `AgentCancelCause` union — a bare string such as
+ * `agent.cancel('thinking-loop')`, or an object whose `kind` the union does not
+ * have. `ReactLoopAgent.cancel` passes it straight to
+ * `AbortController.abort(cause)`, so the value becomes `signal.reason`; the
+ * turn's `catch` then reads it back through `abortedCancelCause`, whose `switch`
+ * ends in `assertNever` — **inside the catch body**. The assignment never runs,
+ * `turnEnds` stays at its `null` initializer, and the unconditional `finally`
+ * appends `turn/end` with that `null` (`agent-loop/src/agent.ts:385`; the
+ * non-null assertion on the line is what makes it compile).
+ *
+ * Nothing on the write path refuses the row: the append-time validator inspects
+ * surface message slots, `request/header` and `tool/result`, and
+ * `turn/end.reason` is a TypeScript-only invariant. Every reader that
+ * dereferences it then throws — `ui-chat`'s conversation view does
+ * `location.turn.end?.data.reason.kind` while rendering — and one such row
+ * blanks the entire chat area, for every session, including newly created ones.
+ *
+ * ## The version boundary
+ *
+ * A harness older than `0.1.7` had no such function: the turn's `catch` wrote
+ * `{ kind: 'aborted', reason: signal.reason }` verbatim, so the same abuse
+ * produced a malformed-but-readable row rather than a `null` one. From
+ * `0.1.7-rc.2` on, the same abuse is fatal. That is why this is a guard and not
+ * a report: the shape of the failure changed under callers that had not changed
+ * at all.
+ *
+ * ## What this plugin does
+ *
+ * It closes the defect at two depths, and the second one exists for the callers
+ * the first cannot see.
+ *
+ * **At the entry.** It listens to `agent/created` — the serial, awaited lifecycle
+ * edge that hands over the **live agent instance** — and shadows that instance's
+ * `cancel` with a wrapper that normalizes anything outside the union into
+ * `{ kind: 'hook', reason: <the value's own name> }` before the loop ever sees
+ * it. `hook` is the union member the harness reserves for plugins, so the
+ * rewrite is not a lie: a plugin did cancel the turn, and the reason names which
+ * one. One property write covers every instance-level caller — the loop's own
+ * `agent.cancel({ kind: 'user' })`, the client's stop button, and any
+ * third-party plugin — because `ReactLoopAgent.cancel` is a prototype method and
+ * the shadow is an own property.
+ *
+ * **At the write.** The same edge hands over the **live session**, and the
+ * plugin shadows that session's own `append` too, so a `turn/end` row whose
+ * reason no reader can dereference is committed instead as the row the loop meant
+ * to write: `{ kind: 'aborted', reason: { kind: 'hook', reason: <text> } }`. That
+ * arm is what covers the callers the entry guard cannot reach — one that goes
+ * through the class rather than the instance
+ * (`ReactLoopAgent.prototype.cancel.call(agent, …)`, or a second copy of the loop
+ * in the process), and an instance that refuses the own `cancel` property, where
+ * the entry guard simply reports that it is not in force. Set `backstop: false`
+ * to leave the append path exactly as the harness's.
+ *
+ * Every rewrite and every repaired row is logged, with the offending value
+ * rendered as JSON, so the producer can be found and fixed rather than merely
+ * tolerated.
+ *
+ * ## What it does not do
+ *
+ * It does not refuse a cancellation, does not touch the options, does not rewrite
+ * a cause that is already a member (that one is forwarded by reference), and
+ * cannot repair a session that already carries a `null` row — those rows are on
+ * disk, and this plugin reads no history. Mounting it bounds the defect from that
+ * point on.
+ *
+ * `mode: 'observe'` exists for the operator who wants to see the failure happen:
+ * both arms report and neither rewrites, and the log names what arrived.
+ *
+ * @module @argszero/dsh-cancel-cause-guard
+ */
+import { guardSessionAppend } from "./backstop.js";
+import { resolveConfig } from "./config.js";
+import { guardCancel } from "./guard.js";
+export { DEFAULT_MAX_REASON_CHARS, describeValue, isCancelCause, normalizeCancelCause, reasonText, UNSPECIFIED_REASON } from "./cause.js";
+export { APPEND_GUARD_MARK, UNSEEN_CAUSE_REASON, guardSessionAppend, isReadableTurnEndReason, unseenCauseReason } from "./backstop.js";
+export { DEFAULTS, resolveConfig } from "./config.js";
+export { GUARD_MARK, guardCancel } from "./guard.js";
+/** Cordis plugin name, used by loader diagnostics. */
+export const name = 'cancel-cause-guard';
+/**
+ * No service is required.
+ *
+ * The whole seam is the agent instance the lifecycle edge hands over, and asking
+ * for a service this plugin does not use would only be a way for it to fail to
+ * mount — so the list is empty rather than absent, which keeps the declaration
+ * explicit for a reader and identical between the two export forms.
+ */
+export const inject = [];
+/** The prefix of every diagnostic this plugin logs. */
+const LOG_PREFIX = 'cancel-cause-guard:';
+/**
+ * Install the guard.
+ * @param ctx - the plugin context; the listener and the restore are disposed
+ *   with it.
+ * @param config - the configuration as mounted, possibly empty. Defaults are
+ *   applied inside `resolveConfig` rather than in a plain object exported under
+ *   the name `Config`, because the Loader reads that export as a schema and the
+ *   plugin would then fail to mount.
+ * @throws when the configuration names an unknown key or an unusable value; the
+ *   plugin refuses to mount rather than guarding with rules it cannot honour.
+ */
+export function apply(ctx, config = {}) {
+    const settings = resolveConfig(config);
+    /** The shadows this plugin installed and has not yet unwound, by agent instance. */
+    const guards = new Map();
+    // Registered before the listeners so that it is unwound *after* them: the
+    // fiber's effects are disposed in reverse, and unwinding a shadow while a
+    // listener could still install another would leave the last one behind.
+    ctx.effect(() => () => {
+        for (const shadows of guards.values())
+            restoreShadows(shadows);
+        guards.clear();
+    }, `${LOG_PREFIX}restore()`);
+    ctx.on('agent/created', ({ agent }) => {
+        const shadows = {};
+        const sessionId = agent.session.id;
+        const handle = guardCancel(agent, {
+            mode: settings.mode,
+            reason: settings.reason,
+            maxReasonChars: settings.maxReasonChars,
+            onNormalized: report => { reportNormalized(ctx, sessionId, report, settings.mode); },
+        });
+        switch (handle.outcome) {
+            case 'patched':
+                shadows.cancel = handle;
+                ctx.logger.debug(`${LOG_PREFIX} agent ${sessionId}: cancellation causes outside the union will be `
+                    + 'recorded as { kind: "hook", reason } instead of ending the turn with reason null');
+                break;
+            case 'already-guarded':
+                ctx.logger.debug(`${LOG_PREFIX} agent ${sessionId}: already guarded by this plugin, leaving the `
+                    + 'existing wrapper in place');
+                break;
+            case 'no-cancel':
+                ctx.logger.warn(`${LOG_PREFIX} agent ${sessionId} carries no cancel method, so an out-of-union `
+                    + 'cause from any plugin it hands itself to will still end its turn with reason null');
+                break;
+            /* v8 ignore next 4 -- the read-back check makes both write failures one outcome. */
+            case 'not-writable':
+                ctx.logger.warn(`${LOG_PREFIX} agent ${sessionId} refuses an own "cancel" property, so this guard `
+                    + 'is NOT in force for it: an out-of-union cause will end its turn with reason null');
+        }
+        // The durable half, installed after the entry guard so that the ordering is
+        // legible: what the entry guard rewrites never reaches this one, and what
+        // reaches this one is exactly the cancellation the entry guard could not see.
+        if (settings.backstop) {
+            const backstop = guardSessionAppend(agent.session, backstopOptions(ctx, sessionId, settings));
+            switch (backstop.outcome) {
+                case 'patched':
+                    shadows.append = backstop;
+                    ctx.logger.debug(`${LOG_PREFIX} agent ${sessionId}: a turn/end row that reached the log with no `
+                        + 'readable reason will be recorded as { kind: "aborted", reason: { kind: "hook", reason } }');
+                    break;
+                case 'already-guarded':
+                    ctx.logger.debug(`${LOG_PREFIX} agent ${sessionId}: the session is already backstopped by this plugin, `
+                        + 'leaving the existing wrapper in place');
+                    break;
+                case 'no-append':
+                    ctx.logger.warn(`${LOG_PREFIX} agent ${sessionId}: its session carries no append method, so the `
+                        + 'durable backstop is NOT in force for it');
+                    break;
+                /* v8 ignore next 4 -- the read-back check makes both write failures one outcome. */
+                case 'not-writable':
+                    ctx.logger.warn(`${LOG_PREFIX} agent ${sessionId}: its session refuses an own "append" property, so `
+                        + 'the durable backstop is NOT in force for it');
+            }
+        }
+        if (shadows.cancel !== undefined || shadows.append !== undefined)
+            guards.set(agent, shadows);
+    });
+    ctx.on('agent/disposed', ({ agent }) => {
+        const shadows = guards.get(agent);
+        if (shadows === undefined)
+            return;
+        restoreShadows(shadows);
+        guards.delete(agent);
+    });
+}
+/**
+ * Unwind every shadow of one agent.
+ * @param shadows - the handles this plugin installed for that agent.
+ */
+function restoreShadows(shadows) {
+    shadows.cancel?.restore();
+    shadows.append?.restore();
+}
+/**
+ * The backstop options for one agent.
+ * @param ctx - the plugin context, for logging.
+ * @param sessionId - the session the backstop reports against.
+ * @param settings - the resolved configuration.
+ * @returns the options, with the report callback bound.
+ */
+function backstopOptions(ctx, sessionId, settings) {
+    return {
+        mode: settings.mode,
+        reason: settings.reason,
+        maxReasonChars: settings.maxReasonChars,
+        onRepaired: report => { reportRepaired(ctx, sessionId, report, settings.mode); },
+    };
+}
+/**
+ * Record one unreadable `turn/end` reason.
+ *
+ * A warning rather than an error, and deliberately a different sentence from
+ * {@link reportNormalized}: this row was not a cause the entry guard rewrote but
+ * a cancellation the entry guard never saw, and the operator has to be able to
+ * tell the two apart when working out who produced it.
+ * @param ctx - the plugin context, for logging.
+ * @param sessionId - the session whose row it was.
+ * @param report - what the row carried, and what it became.
+ * @param mode - whether the row was repaired or passed through.
+ */
+function reportRepaired(ctx, sessionId, report, mode) {
+    const outcome = mode === 'observe'
+        ? 'it was committed unchanged (mode "observe"), so this session is now unreadable in the chat view'
+        : 'it was recorded as '
+            + `{ "kind": "aborted", "reason": { "kind": "hook", "reason": ${JSON.stringify(report.normalized.reason)} } }`;
+    ctx.logger.warn(`${LOG_PREFIX} session ${sessionId}: a turn/end row for turn ${String(report.turn)} reached the `
+        + `log with a reason no reader can dereference (${report.described}); ${outcome}. `
+        + 'The cancellation never passed the entry guard, so its cause is not in this record: a caller '
+        + 'reached the cancel method through the class rather than through the instance, a second copy '
+        + 'of the loop aborted a signal of its own, or the instance refused the guard.');
+}
+/**
+ * Record one out-of-union cause.
+ *
+ * A warning rather than an error: what the reader needs is the *name* of the
+ * value — the only handle on whoever produced it — and the two modes differ
+ * only in what became of it.
+ * @param ctx - the plugin context, for logging.
+ * @param sessionId - the session whose agent was cancelled.
+ * @param report - what was seen, and what it became.
+ * @param mode - whether the cause was rewritten or passed through.
+ */
+function reportNormalized(ctx, sessionId, report, mode) {
+    const outcome = mode === 'observe'
+        ? 'it was passed through unchanged (mode "observe"), so this turn ends with reason null'
+        : 'the turn was recorded as '
+            + `{ "kind": "aborted", "reason": { "kind": "hook", "reason": ${JSON.stringify(report.normalized.reason)} } }`;
+    ctx.logger.warn(`${LOG_PREFIX} session ${sessionId}: a caller passed ${report.described} as a cancellation `
+        + `cause, which is not a member of AgentCancelCause; ${outcome}. `
+        + 'Which plugin passes it is the value itself: the reason carries its own name.');
+}
+export default { name, inject, apply };