@argszero/dsh-cancel-cause-guard 0.1.0 → 0.2.0

package/README.md

@@ -8,8 +8,9 @@ The harness ships an `Agent.cancel(cause)` whose argument is a **closed** union
 `{ kind: 'disposed' }` — and that union is enforced by TypeScript alone. Nothing on
 the write path refuses a value outside it, and one such value does not merely log
 something odd: it ends the session's usefulness. This plugin normalizes the
-out-of-union value at the last moment the harness still lets a plugin see it, so the
-turn ends with a readable reason instead of `null`.
+out-of-union value at the last moment the harness still lets a plugin see it, and
+backstops the session's own `append` so that even a cancellation it never gets to
+see cannot commit an unreadable row.
 
 ## The defect
 
@@ -31,10 +32,10 @@ throws before the catch body assigns `turnEnds`, which is still at its `null`
 initializer, and the `finally` appends unconditionally:
 
 ```ts
-let turnEnds: TurnEndReason | null = null                 // agent.ts:310
+let turnEnds: TurnEndReason | null = null                 // agent.ts:312
 ...
 } finally {
-  this.session.append('turn/end', { turn, reason: turnEnds! })   // agent.ts:385
+  this.session.append('turn/end', { turn, reason: turnEnds! })   // agent.ts:387
 }
 ```
 
@@ -46,7 +47,7 @@ dereferences it then throws — the chat client does `location.turn.end?.data.re
 while rendering — and one such row blanks the entire conversation area, for every
 session, including newly created ones.
 
-Reported three times: discussions **#8832**, **#9156** and **#9646**.
+Reported four times: discussions **#8832**, **#9156**, **#9646** and **#9699**.
 
 ### The version boundary
 
@@ -56,8 +57,25 @@ malformed-but-readable row rather than a `null` one. From `0.1.7-rc.2` on, the s
 abuse is fatal — which is why this is a **guard** and not a report: the shape of the
 failure changed under callers that had not changed at all.
 
+### The two callers an entry guard cannot reach
+
+`ReactLoopAgent.cancel` is the only aborter of the signals the loop owns — the
+function's own comment says so — so shadowing that method covers every caller that
+goes through the agent **instance**. Two do not:
+
+- a caller that reaches the **class** rather than the instance
+  (`ReactLoopAgent.prototype.cancel.call(agent, cause)`, or a second copy of the
+  loop in the same process), which no observable hook hands over; and
+- an instance that **refuses** the own `cancel` property, where the entry guard
+  reports that it is not in force and nothing protects the session at all.
+
+Both end with the same unreadable row. That is what the second half of this plugin
+is for.
+
 ## What it does
 
+### 1. Normalize the cause at the entry
+
 It listens to `agent/created` — the serial, awaited lifecycle edge that hands over the
 **live agent instance** (`dsh-agent/src/index.ts:550`) — and shadows that instance's
 `cancel` with a wrapper that normalizes anything outside the union into
@@ -83,8 +101,35 @@ It listens to `agent/created` — the serial, awaited lifecycle edge that hands
   detached `const cancel = agent.cancel` still reaches the method with the receiver
   its body requires.
 
-Every rewrite is logged with the offending value rendered as JSON, so the producer can
-be found and fixed rather than tolerated.
+### 2. Backstop the row at the write
+
+The same lifecycle edge hands over the **live session**, and `Session.append` is a
+prototype method of it — so one own-property write shadows the append path for every
+writer, the loop's own rows included. Only one event type is inspected.
+
+- **The row it writes is the row the loop meant to write.** When a `turn/end` arrives
+  whose reason no reader can dereference, the backstop commits
+  `{ kind: 'aborted', reason: { kind: 'hook', reason: <text> } }` instead: the turn
+  *was* interrupted by a cancellation, `aborted` is a member every reader knows, and
+  `hook` is the member that says the cancellation came from outside the union.
+- **It does not invent a variant.** `TurnEndReasonMap` is merge-extensible, so a new
+  `kind` would be a value the readers have never seen — trading a loud failure for a
+  silent one.
+- **The test is dereferenceability, not membership.** A reason is left alone when it
+  is a non-null object carrying a non-empty string `kind`, because a plugin may
+  legitimately extend the map with a variant this plugin knows nothing about. What is
+  refused is the shape no reader can read at all: `null`, absent, or not an object.
+- **It never edits the caller's payload.** The replacement is a new object; the one
+  the loop handed over is left as it was.
+- **Every other event is forwarded untouched**, whatever it carries, and a
+  `turn/end` whose payload is not an object is reported rather than rebuilt — the
+  event map promises `{ turn, reason }`, and writing the missing half would be
+  inventing a durable row.
+- **It is switchable off** with `backstop: false`, for an operator who wants the
+  append path to be exactly the harness's.
+
+Every cause rewrite and every repaired row is logged, with the offending value
+rendered as JSON, so the producer can be found and fixed rather than tolerated.
 
 ## Install
 
@@ -114,14 +159,16 @@ Or, if you compose `cordis.yml` by hand:
 
 | Key | Default | Meaning |
 |---|---|---|
-| `mode` | `'normalize'` | `normalize` rewrites an out-of-union cause to `{ kind: 'hook', reason }`; `observe` passes the caller's value through untouched and only records the producer. |
-| `reason` | absent | Reason text to record in place of the value's own name. Absent names the cause after the value that produced it — the only handle on whoever produced it. |
+| `mode` | `'normalize'` | `normalize` rewrites an out-of-union cause to `{ kind: 'hook', reason }` and repairs an unreadable `turn/end` reason; `observe` passes both through untouched and only records what arrived. |
+| `reason` | absent | Reason text to record in place of the value's own name. Absent names the cause after the value that produced it — the only handle on whoever produced it — and names a repaired row after what it is: a cancellation the entry guard never saw. |
 | `maxReasonChars` | `200` | Bound on the minted reason, in characters. |
+| `backstop` | `true` | Whether the durable backstop is installed as well. `false` leaves the session's own `append` untouched. |
 
 A configuration the plugin cannot honour is refused **at mount** rather than quietly
 replaced: an unknown key, a mode this plugin does not have, a `reason` that would name
-nothing, or a bound that is not a positive integer. A misspelled `mode` that mounts and
-guards nothing is how an operator believes a guard is in force when it is not.
+nothing, a bound that is not a positive integer, or a `backstop` that is not a boolean.
+A misspelled `mode` that mounts and guards nothing is how an operator believes a guard
+is in force when it is not.
 
 ## Diagnostics
 
@@ -134,46 +181,68 @@ cause, which is not a member of AgentCancelCause; the turn was recorded as
 Which plugin passes it is the value itself: the reason carries its own name.
 ```
 
-`observe` mode says the value was passed through instead, so the operator sees the
-real failure and the log does not claim a repair.
+One warning per repaired `turn/end` row, in a deliberately different sentence — a row
+this arm repaired is a cancellation the **entry guard never saw**, and an operator has
+to be able to tell the two apart:
+
+```
+cancel-cause-guard: session <id>: a turn/end row for turn 4 reached the log with a
+reason no reader can dereference (null); it was recorded as { "kind": "aborted",
+"reason": { "kind": "hook", "reason": "a cancellation cause the entry guard never
+saw" } }. 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.
+```
+
+`observe` mode says the value (or the row) was passed through instead, so the operator
+sees the real failure and the log does not claim a repair.
 
-Two refusals are warned about at the moment they matter, because a guard that is
+Four refusals are warned about at the moment they matter, because a guard that is
 silently absent is the thing an operator cannot see:
 
 - an agent that carries no `cancel` method at all;
 - an agent that refuses an own `cancel` property (a sealed or non-writable instance),
   where the install is confirmed by **reading the property back**, not by the absence
-  of a throw.
+  of a throw — the durable backstop covers this agent's session all the same;
+- a session that carries no `append` method;
+- a session that refuses an own `append` property.
 
 ## What it is not
 
 - **It 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; the sessions that already have one stay unreadable until the row is removed.
-- **It does not cover a caller that reaches the class rather than the instance** —
-  `ReactLoopAgent.prototype.cancel.call(agent, …)`, or a second copy of the loop.
-  Nothing observable hands that path over, which is why `mode: 'observe'` exists: an
-  operator who wants to see the failure happen may mount this plugin as a reporter and
-  still get the producer named in the log.
-- **It does not patch the union away.** Values that are already members are neither
-  copied, rewritten, nor reported.
+- **It does not patch the unions away.** Causes that are already members are neither
+  copied, rewritten, nor reported, and a `turn/end` reason a reader can dereference is
+  forwarded as it is, whatever variant it names.
 - **It calls no model and needs no service.** `inject` is empty: the whole seam is the
-  agent instance the lifecycle edge delivers.
+  agent instance and the session the lifecycle edge delivers.
+- **It writes no history.** Both arms only affect rows that are about to be committed;
+  a row already in the log is never read, rewritten or deleted.
 
 ## Evidence
 
 - `test/lifecycle.spec.mjs` — the plugin mounted through a real Cordis context, against
-  the real `AgentRegistry` and the real `agent/created` dispatch: the guard is installed
-  by the time the announce dispatch settles, it does not touch an agent published before
-  the mount, unmounting restores the instance (both when the fiber disposes and when the
-  agent does), and `world({ mounted: false })` is the control arm for each.
-- `test/guard.spec.mjs` — the mechanism: an own property over a prototype method, the
-  options handed through untouched, the original bound to its agent, the mark a second
-  mount recognises, the undo that reveals the prototype method again rather than copying
-  it in, and every refusal.
+  the real `AgentRegistry` and the real `agent/created` dispatch, on a real
+  `@deepseek-ai/dsh-session` `Session`: the guard and the backstop are installed by the
+  time the announce dispatch settles, neither touches an agent published before the
+  mount, unmounting restores both properties (when the fiber disposes and when the
+  agent does), a sealed instance is still backstopped at the write, and
+  `world({ mounted: false })` is the control arm for each — including the arm that
+  writes the `{"turn":1,"reason":null}` row **unmounted** and reads it back out of the
+  log, which is the defect reproduced against the shipped class rather than described.
+- `test/backstop.spec.mjs` — the second mechanism: an own property over a prototype
+  method, the row it writes for each unreadable shape, what it leaves alone (a readable
+  reason by reference, a plugin's own variant, every other event type), the payload it
+  does not mutate, and every refusal.
+- `test/guard.spec.mjs` — the first mechanism: an own property over a prototype method,
+  the options handed through untouched, the original bound to its agent, the mark a
+  second mount recognises, the undo that reveals the prototype method again rather than
+  copying it in, and every refusal.
 - `test/cause.spec.mjs` — the pure half: what each shape becomes, what it is called, the
   bound, and the values that must never throw inside `cancel`.
-- `test/config.spec.mjs` — the defaults, detaching, and the five refusals.
+- `test/config.spec.mjs` — the defaults, detaching, and the refusals.
 - `scripts/witness-cancel-cause.mjs` — the consequence, proved against the **published**
   `@deepseek-ai/dsh-agent-loop` sources rather than a stand-in: it extracts
   `abortedCancelCause` and `assertNever` from the shipped tarball, shows a bare-string
@@ -186,7 +255,9 @@ silently absent is the thing an operator cannot see:
   the test that was supposed to hold the line, and is reported as `SILENT`.
 - `npm run probe:lines` — runs the suite once per released line, each with every harness
   package pinned to that line. That measurement is where the supported-lines list below
-  comes from.
+  comes from, and it covers the backstop's seam too: the suite's own session is the
+  line's published `Session`, and the unmounted control arm asserts that this line's
+  write path accepts `reason: null`.
 
 ## Supported lines
 

package/cordis.patch.yml

@@ -15,24 +15,33 @@
 # surface message slots, `request/header` and `tool/result`, and `turn/end.reason` is
 # a TypeScript-only invariant. Every reader that dereferences it then throws, and the
 # chat client does exactly that while rendering, so one such row blanks the
-# conversation area. Reported three times: discussions #8832, #9156 and #9646.
+# conversation area. Reported four times: discussions #8832, #9156, #9646 and #9699.
 #
 # A harness older than `0.1.7` had no such function and recorded the same abuse as a
 # malformed-but-readable row, which is why this is a guard: the failure changed shape
 # under callers that had not changed at all.
 #
-# This plugin closes the seam that is left. It listens to `agent/created` — the
-# serial, awaited lifecycle edge that hands over the **live agent instance**
-# (`dsh-agent/src/index.ts:550`) — and shadows that instance's `cancel` with a wrapper
-# that carries anything outside the union as `{ kind: 'hook', reason: <the value's own
-# name> }` before the loop ever sees it. `hook` is the member the union reserves for
-# plugins, so the rewrite is not a lie: a plugin did cancel the turn, and the reason
-# names which one. One own-property write covers every instance-level caller, because
-# `ReactLoopAgent.cancel` is a prototype method.
+# This plugin closes the defect at two depths. **At the entry**, it listens to
+# `agent/created` — the serial, awaited lifecycle edge that hands over the **live agent
+# instance** (`dsh-agent/src/index.ts:550`) — and shadows that instance's `cancel` with
+# a wrapper that carries anything outside the union as `{ kind: 'hook', reason: <the
+# value's own name> }` before the loop ever sees it. `hook` is the member the union
+# reserves for plugins, so the rewrite is not a lie: a plugin did cancel the turn, and
+# the reason names which one. One own-property write covers every instance-level caller,
+# because `ReactLoopAgent.cancel` is a prototype method.
 #
-# It never refuses a cancellation, forwards an already-valid cause by reference, and
-# cannot repair rows already on disk (it reads no history). Mounting it bounds the
-# defect from that point on.
+# **At the write**, the same edge hands over the **live session**, and the plugin
+# shadows that session's `append` too — so a `turn/end` row whose reason no reader can
+# dereference is committed as `{ kind: 'aborted', reason: { kind: 'hook', reason: … } }`
+# instead. That arm 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.
+#
+# It never refuses a cancellation, forwards an already-valid cause by reference, leaves
+# any reason a reader can dereference untouched (a plugin's own `TurnEndReasonMap`
+# variant included), and cannot repair rows already on disk (it reads no history).
+# Mounting it bounds the defect from that point on.
 #
 # Optional config:
 #
@@ -50,6 +59,10 @@
 #           # reason: plugin-bug
 #           # Bound on the minted reason, in characters. Defaults to 200.
 #           maxReasonChars: 200
+#           # Whether the durable backstop is installed as well (default true).
+#           # `false` leaves the session's own `append` untouched, so only the entry
+#           # guard is in force — set it if another plugin already owns that method.
+#           backstop: true
 #
 # 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.

package/lib/backstop.js

@@ -0,0 +1,222 @@
+/**
+ * The durable backstop: the `turn/end` row is never committed with a reason the
+ * conversation view cannot read.
+ *
+ * ## Why the cause guard alone is not enough
+ *
+ * The entry guard (`./guard.ts`) normalizes a cause before the loop ever sees it,
+ * and it covers every caller that goes through the **instance** method — which is
+ * every caller in the shipped tree. Two callers it cannot cover remain, and both
+ * end with the same unreadable row:
+ *
+ * - a caller that reaches the class rather than the instance
+ *   (`ReactLoopAgent.prototype.cancel.call(agent, cause)`, or a second copy of the
+ *   loop in the same process), which no observable hook hands over; and
+ * - an agent instance that refuses the own `cancel` property, where the entry
+ *   guard reports `not-writable` and is simply absent.
+ *
+ * In both cases the out-of-union cause reaches `abortedCancelCause`'s
+ * `assertNever` **inside the turn's `catch`**, `turnEnds` stays at its `null`
+ * initializer, and the unconditional `finally` commits
+ * `{"type":"turn/end","data":{"turn":N,"reason":null}}`. The write path accepts it
+ * — `validateSessionEventData` inspects surface message slots, `request/header`
+ * and `tool/result`, and `turn/end.reason` is a TypeScript-only invariant — so
+ * the row is durable before any reader can object. The chat client then
+ * dereferences `reason.kind` while rendering and throws, which blanks the whole
+ * conversation area, for every session, across restarts.
+ *
+ * ## The seam
+ *
+ * `Session.append` is a **prototype** method of the session the agent holds, so an
+ * own-property write on `agent.session` shadows it for every writer — the loop's
+ * own `turn/start` / `step/start` / `turn/end` and any plugin's, alike. Only one
+ * event type is inspected; everything else is forwarded untouched.
+ *
+ * ## What it writes
+ *
+ * It does not invent a variant. A new `kind` would be a value the readers switch
+ * over have never seen, which trades a loud failure for a silent one — and
+ * `TurnEndReasonMap` is merge-extensible, so this plugin cannot even enumerate
+ * the members. It writes instead **the row the loop meant to write**: the turn was
+ * interrupted by a cancellation, and the cause came from outside the closed union,
+ * so it is `{ kind: 'aborted', reason: { kind: 'hook', reason: <text> } }` —
+ * `aborted` is a member every reader knows, and `hook` is the member
+ * `AgentCancelCause` reserves for whoever outside the union cancelled the turn.
+ *
+ * The test is deliberately **dereferenceability, not membership**: a reason is
+ * left alone when it is a non-null object carrying a non-empty string `kind`,
+ * because a plugin may legitimately extend `TurnEndReasonMap` with a variant this
+ * plugin knows nothing about. What is refused is the shape no reader can read at
+ * all — `null`, absent, or not an object.
+ *
+ * @module @argszero/dsh-cancel-cause-guard/backstop
+ */
+import { truncate } from "./cause.js";
+/**
+ * The brand an installed append wrapper carries.
+ *
+ * `Symbol.for` for the reason {@link GUARD_MARK} uses it: two copies of this
+ * plugin in one process must recognise each other's work rather than stack.
+ */
+export const APPEND_GUARD_MARK = Symbol.for('argszero.dsh-cancel-cause-guard/append-guarded');
+/** The event type this backstop inspects, and the only one it rewrites. */
+const TURN_END = 'turn/end';
+/**
+ * The reason text for a row whose reason carried nothing at all.
+ *
+ * Named for what the operator has to know: the cancellation did not pass the
+ * entry guard, so its cause was never seen and cannot be named.
+ */
+export const UNSEEN_CAUSE_REASON = 'a cancellation cause the entry guard never saw';
+/**
+ * Whether a value is a reason a reader can dereference.
+ *
+ * The whole consequence of the defect is one expression — `reason.kind` — so the
+ * property this asks about is exactly that one: an object, not null, whose `kind`
+ * is non-empty text. Membership in `TurnEndReasonMap` is deliberately **not**
+ * asked, because the map is merge-extensible and a plugin's own variant would
+ * then be rewritten by a plugin that had never heard of it.
+ * @param reason - the value the loop is about to commit as `turn/end.reason`.
+ * @returns whether a reader may dereference `reason.kind`.
+ */
+export function isReadableTurnEndReason(reason) {
+    if (typeof reason !== 'object' || reason === null)
+        return false;
+    const kind = readKind(reason);
+    return typeof kind === 'string' && kind.trim().length > 0;
+}
+/**
+ * The reason to commit for a row whose own reason is unreadable.
+ *
+ * The configured reason wins when the operator set one; otherwise the text says
+ * the one thing that is certainly true — no entry guard saw this cancellation.
+ * @param options - the configured reason and its bound.
+ * @returns the reason text for the replacement row.
+ */
+export function unseenCauseReason(options) {
+    const text = options.reason ?? UNSEEN_CAUSE_REASON;
+    return truncate(text, options.maxReasonChars);
+}
+/**
+ * Shadow one session's `append` so an unreadable `turn/end` reason never lands.
+ *
+ * Every refusal is reported as an outcome rather than thrown: a session this
+ * plugin could not guard is a session that keeps the defect, not a reason to fail
+ * the lifecycle edge that delivered it.
+ * @param session - the live session the agent appends to.
+ * @param options - the mode, the reason override, the bound, and the report callback.
+ * @returns the outcome and an undo.
+ */
+export function guardSessionAppend(session, options) {
+    if (session === undefined || session === null)
+        return { outcome: 'no-append', restore: () => { } };
+    const current = session.append;
+    if (typeof current !== 'function')
+        return { outcome: 'no-append', restore: () => { } };
+    if (current[APPEND_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.
+    const hadOwn = Object.prototype.hasOwnProperty.call(session, 'append');
+    const wrapper = function guardedAppend(...args) {
+        const decided = decide(args, options);
+        if (decided === undefined)
+            return Reflect.apply(original, session, args);
+        options.onRepaired(decided.report);
+        // In `observe` mode the report is the whole contribution: the unreadable row
+        // is committed exactly as it would have been, so the operator sees the real
+        // failure, and the log names it rather than claiming a repair.
+        if (options.mode === 'observe')
+            return Reflect.apply(original, session, args);
+        const forwarded = args.slice();
+        forwarded[1] = { ...args[1], reason: decided.reason };
+        return Reflect.apply(original, session, forwarded);
+    };
+    wrapper[APPEND_GUARD_MARK] = true;
+    try {
+        ;
+        session.append = wrapper;
+    }
+    catch {
+        // A sealed session, or an `append` 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 (session.append !== 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 session
+            // itself, may have replaced it, and undoing that would be a third party's
+            // state being written by this one.
+            if (session.append !== wrapper)
+                return;
+            if (hadOwn)
+                session.append = original;
+            else
+                delete session.append;
+        },
+    };
+}
+/**
+ * What one `append` call should become, if anything.
+ *
+ * Only `turn/end` with an object payload is eligible. A payload that is not an
+ * object is left alone rather than rebuilt: the event map promises `{ turn, reason }`,
+ * and a setter that invented the missing half would be writing a row of its own
+ * making into a durable log. It is reported instead.
+ * @param args - the arguments the caller passed to `append`.
+ * @param options - the configured reason and its bound.
+ * @returns the reason to commit and the report, or undefined when nothing changes.
+ */
+function decide(args, options) {
+    if (args[0] !== TURN_END)
+        return undefined;
+    const data = args[1];
+    if (typeof data !== 'object' || data === null || Array.isArray(data))
+        return undefined;
+    const reason = data.reason;
+    if (isReadableTurnEndReason(reason))
+        return undefined;
+    return {
+        reason: { kind: 'aborted', reason: { kind: 'hook', reason: unseenCauseReason(options) } },
+        report: {
+            turn: data.turn,
+            original: reason,
+            normalized: { kind: 'hook', reason: unseenCauseReason(options) },
+            described: describeReason(reason),
+        },
+    };
+}
+/** A rendering of the unreadable reason, for the log line. */
+function describeReason(reason) {
+    if (reason === undefined)
+        return 'absent';
+    if (reason === null)
+        return 'null';
+    const kind = typeof reason === 'object' ? readKind(reason) : undefined;
+    if (typeof kind === 'string' && kind.trim().length > 0)
+        return `no kind string (${String(kind)})`;
+    return Object.prototype.toString.call(reason);
+}
+/** The `kind` a value carries, read without letting a hostile accessor escape. */
+function readKind(value) {
+    try {
+        return value.kind;
+    }
+    catch {
+        // It runs inside `append`: a guard that threw while inspecting a payload
+        // would abort the append in the guard rather than in its caller.
+        return undefined;
+    }
+}

package/lib/cause.js

@@ -193,7 +193,13 @@ function plainText(value) {
         return UNSPECIFIED_REASON;
     }
 }
-/** Bound one reason so a hostile value cannot write a wall of text into the log. */
-function truncate(text, maxChars) {
+/**
+ * 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

@@ -1,9 +1,10 @@
 /**
  * Configuration resolution for the cancellation-cause guard.
  *
- * The surface is deliberately three fields. A guard that rewrites a value on a
- * path as hot as cancellation 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.
+ * 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
@@ -17,8 +18,9 @@ export const DEFAULTS = Object.freeze({
     mode: 'normalize',
     reason: undefined,
     maxReasonChars: DEFAULT_MAX_REASON_CHARS,
+    backstop: true,
 });
-const CONFIG_KEYS = new Set(['mode', 'reason', 'maxReasonChars']);
+const CONFIG_KEYS = new Set(['mode', 'reason', 'maxReasonChars', 'backstop']);
 const MODES = new Set(['normalize', 'observe']);
 /**
  * Resolve, validate and detach the guard configuration.
@@ -34,7 +36,7 @@ export function resolveConfig(config = {}) {
     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)');
+                + '(allowed: mode, reason, maxReasonChars, backstop)');
         }
     }
     const mode = config.mode ?? DEFAULTS.mode;
@@ -55,5 +57,9 @@ export function resolveConfig(config = {}) {
             + `after the value that produced it (the default resolves to "${UNSPECIFIED_REASON}" only `
             + 'for a cause that carried no name)');
     }
-    return Object.freeze({ mode, reason, maxReasonChars });
+    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/index.js

@@ -33,9 +33,12 @@
  *
  * ## What this plugin does
  *
- * 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
+ * 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
@@ -44,27 +47,39 @@
  * third-party plugin — because `ReactLoopAgent.cancel` is a prototype method and
  * the shadow is an own property.
  *
- * Every rewrite is logged, with the offending value rendered as JSON, so the
- * producer can be found and fixed rather than merely tolerated.
+ * **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.
+ * 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.
  *
- * It also cannot cover the one caller that reaches the class rather than the
- * instance, which is why `mode: 'observe'` exists: an operator who wants to see
- * the failure happen may mount this plugin as a reporter and still get the
- * producer named in the log.
+ * `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. */
@@ -93,51 +108,126 @@ const LOG_PREFIX = 'cancel-cause-guard:';
  */
 export function apply(ctx, config = {}) {
     const settings = resolveConfig(config);
-    /** The guards this plugin installed and has not yet unwound, by agent instance. */
+    /** 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 handle of guards.values())
-            handle.restore();
+        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, agent.session.id, report, settings.mode); },
+            onNormalized: report => { reportNormalized(ctx, sessionId, report, settings.mode); },
         });
         switch (handle.outcome) {
             case 'patched':
-                guards.set(agent, handle);
-                ctx.logger.debug(`${LOG_PREFIX} agent ${agent.session.id}: cancellation causes outside the union will be `
+                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');
-                return;
+                break;
             case 'already-guarded':
-                ctx.logger.debug(`${LOG_PREFIX} agent ${agent.session.id}: already guarded by this plugin, leaving the `
+                ctx.logger.debug(`${LOG_PREFIX} agent ${sessionId}: already guarded by this plugin, leaving the `
                     + 'existing wrapper in place');
-                return;
+                break;
             case 'no-cancel':
-                ctx.logger.warn(`${LOG_PREFIX} agent ${agent.session.id} carries no cancel method, so an out-of-union `
+                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');
-                return;
+                break;
             /* v8 ignore next 4 -- the read-back check makes both write failures one outcome. */
             case 'not-writable':
-                ctx.logger.warn(`${LOG_PREFIX} agent ${agent.session.id} refuses an own "cancel" property, so this guard `
+                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 handle = guards.get(agent);
-        if (handle === undefined)
+        const shadows = guards.get(agent);
+        if (shadows === undefined)
             return;
-        handle.restore();
+        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.
  *

package/lib/types/backstop.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The durable backstop: the `turn/end` row is never committed with a reason the
+ * conversation view cannot read.
+ *
+ * ## Why the cause guard alone is not enough
+ *
+ * The entry guard (`./guard.ts`) normalizes a cause before the loop ever sees it,
+ * and it covers every caller that goes through the **instance** method — which is
+ * every caller in the shipped tree. Two callers it cannot cover remain, and both
+ * end with the same unreadable row:
+ *
+ * - a caller that reaches the class rather than the instance
+ *   (`ReactLoopAgent.prototype.cancel.call(agent, cause)`, or a second copy of the
+ *   loop in the same process), which no observable hook hands over; and
+ * - an agent instance that refuses the own `cancel` property, where the entry
+ *   guard reports `not-writable` and is simply absent.
+ *
+ * In both cases the out-of-union cause reaches `abortedCancelCause`'s
+ * `assertNever` **inside the turn's `catch`**, `turnEnds` stays at its `null`
+ * initializer, and the unconditional `finally` commits
+ * `{"type":"turn/end","data":{"turn":N,"reason":null}}`. The write path accepts it
+ * — `validateSessionEventData` inspects surface message slots, `request/header`
+ * and `tool/result`, and `turn/end.reason` is a TypeScript-only invariant — so
+ * the row is durable before any reader can object. The chat client then
+ * dereferences `reason.kind` while rendering and throws, which blanks the whole
+ * conversation area, for every session, across restarts.
+ *
+ * ## The seam
+ *
+ * `Session.append` is a **prototype** method of the session the agent holds, so an
+ * own-property write on `agent.session` shadows it for every writer — the loop's
+ * own `turn/start` / `step/start` / `turn/end` and any plugin's, alike. Only one
+ * event type is inspected; everything else is forwarded untouched.
+ *
+ * ## What it writes
+ *
+ * It does not invent a variant. A new `kind` would be a value the readers switch
+ * over have never seen, which trades a loud failure for a silent one — and
+ * `TurnEndReasonMap` is merge-extensible, so this plugin cannot even enumerate
+ * the members. It writes instead **the row the loop meant to write**: the turn was
+ * interrupted by a cancellation, and the cause came from outside the closed union,
+ * so it is `{ kind: 'aborted', reason: { kind: 'hook', reason: <text> } }` —
+ * `aborted` is a member every reader knows, and `hook` is the member
+ * `AgentCancelCause` reserves for whoever outside the union cancelled the turn.
+ *
+ * The test is deliberately **dereferenceability, not membership**: a reason is
+ * left alone when it is a non-null object carrying a non-empty string `kind`,
+ * because a plugin may legitimately extend `TurnEndReasonMap` with a variant this
+ * plugin knows nothing about. What is refused is the shape no reader can read at
+ * all — `null`, absent, or not an object.
+ *
+ * @module @argszero/dsh-cancel-cause-guard/backstop
+ */
+import type { BackstopHandle, BackstopOptions } from './types.ts';
+/**
+ * The brand an installed append wrapper carries.
+ *
+ * `Symbol.for` for the reason {@link GUARD_MARK} uses it: two copies of this
+ * plugin in one process must recognise each other's work rather than stack.
+ */
+export declare const APPEND_GUARD_MARK: unique symbol;
+/**
+ * The reason text for a row whose reason carried nothing at all.
+ *
+ * Named for what the operator has to know: the cancellation did not pass the
+ * entry guard, so its cause was never seen and cannot be named.
+ */
+export declare const UNSEEN_CAUSE_REASON = "a cancellation cause the entry guard never saw";
+/**
+ * Whether a value is a reason a reader can dereference.
+ *
+ * The whole consequence of the defect is one expression — `reason.kind` — so the
+ * property this asks about is exactly that one: an object, not null, whose `kind`
+ * is non-empty text. Membership in `TurnEndReasonMap` is deliberately **not**
+ * asked, because the map is merge-extensible and a plugin's own variant would
+ * then be rewritten by a plugin that had never heard of it.
+ * @param reason - the value the loop is about to commit as `turn/end.reason`.
+ * @returns whether a reader may dereference `reason.kind`.
+ */
+export declare function isReadableTurnEndReason(reason: unknown): boolean;
+/**
+ * The reason to commit for a row whose own reason is unreadable.
+ *
+ * The configured reason wins when the operator set one; otherwise the text says
+ * the one thing that is certainly true — no entry guard saw this cancellation.
+ * @param options - the configured reason and its bound.
+ * @returns the reason text for the replacement row.
+ */
+export declare function unseenCauseReason(options: {
+    reason?: string | undefined;
+    maxReasonChars: number;
+}): string;
+/**
+ * Shadow one session's `append` so an unreadable `turn/end` reason never lands.
+ *
+ * Every refusal is reported as an outcome rather than thrown: a session this
+ * plugin could not guard is a session that keeps the defect, not a reason to fail
+ * the lifecycle edge that delivered it.
+ * @param session - the live session the agent appends to.
+ * @param options - the mode, the reason override, the bound, and the report callback.
+ * @returns the outcome and an undo.
+ */
+export declare function guardSessionAppend(session: unknown, options: BackstopOptions): BackstopHandle;
+//# sourceMappingURL=backstop.d.ts.map

package/lib/types/cause.d.ts

@@ -111,4 +111,12 @@ export declare function reasonText(value: unknown, maxChars?: number): string;
  * @returns a bounded, single-line rendering.
  */
 export declare function describeValue(value: unknown, maxChars?: number): string;
+/**
+ * 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 declare function truncate(text: string, maxChars: number): string;
 //# sourceMappingURL=cause.d.ts.map

package/lib/types/config.d.ts

@@ -1,9 +1,10 @@
 /**
  * Configuration resolution for the cancellation-cause guard.
  *
- * The surface is deliberately three fields. A guard that rewrites a value on a
- * path as hot as cancellation 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.
+ * 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

package/lib/types/index.d.ts

@@ -33,9 +33,12 @@
  *
  * ## What this plugin does
  *
- * 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
+ * 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
@@ -44,31 +47,42 @@
  * third-party plugin — because `ReactLoopAgent.cancel` is a prototype method and
  * the shadow is an own property.
  *
- * Every rewrite is logged, with the offending value rendered as JSON, so the
- * producer can be found and fixed rather than merely tolerated.
+ * **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.
+ * 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.
  *
- * It also cannot cover the one caller that reaches the class rather than the
- * instance, which is why `mode: 'observe'` exists: an operator who wants to see
- * the failure happen may mount this plugin as a reporter and still get the
- * producer named in the log.
+ * `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 type { Context } from '@deepseek-ai/cordis';
 import type { Config } from './types.ts';
 export { DEFAULT_MAX_REASON_CHARS, describeValue, isCancelCause, normalizeCancelCause, reasonText, UNSPECIFIED_REASON } from './cause.ts';
+export { APPEND_GUARD_MARK, UNSEEN_CAUSE_REASON, guardSessionAppend, isReadableTurnEndReason, unseenCauseReason } from './backstop.ts';
 export { DEFAULTS, resolveConfig } from './config.ts';
 export { GUARD_MARK, guardCancel } from './guard.ts';
 export type { GuardOptions } from './guard.ts';
-export type { Config, GuardHandle, GuardMode, GuardOutcome, NormalizedCause, ResolvedConfig, } from './types.ts';
+export type { BackstopHandle, BackstopOptions, BackstopOutcome, Config, GuardHandle, GuardMode, GuardOutcome, NormalizedCause, RepairedTurnEnd, ResolvedConfig, } from './types.ts';
 /** Cordis plugin name, used by loader diagnostics. */
 export declare const name = "cancel-cause-guard";
 /**

package/lib/types/types.d.ts

@@ -27,12 +27,21 @@ export interface Config {
     readonly reason?: string | undefined;
     /** Bound on the reason text the guard mints. Defaults to 200. */
     readonly maxReasonChars?: number | undefined;
+    /**
+     * Whether the durable backstop is installed as well. Defaults to `true`.
+     *
+     * Set `false` to leave the session's own `append` untouched — for an operator
+     * who wants the write path to be exactly the harness's, and accepts that a
+     * cancellation which bypasses the entry guard can then blank a conversation.
+     */
+    readonly backstop?: boolean | undefined;
 }
 /** The configuration after defaults, validation and detaching. */
 export interface ResolvedConfig {
     readonly mode: GuardMode;
     readonly reason: string | undefined;
     readonly maxReasonChars: number;
+    readonly backstop: boolean;
 }
 /** What {@link guardCancel} found when it reached an agent. */
 export type GuardOutcome = 
@@ -63,4 +72,45 @@ export interface GuardHandle {
     /** Restore the instance's own `cancel`, when this guard installed one. */
     readonly restore: () => void;
 }
+/**
+ * What {@link guardSessionAppend} found when it reached a session.
+ *
+ * The four names mean what {@link GuardOutcome}'s do, for the other property: the
+ * session's `append` now refuses to commit an unreadable `turn/end` reason, some
+ * copy of this plugin is already in place, the session has no callable `append`,
+ * or it refused the own property.
+ */
+export type BackstopOutcome = 'patched' | 'already-guarded' | 'no-append' | 'not-writable';
+/** How one durable backstop is told to behave. */
+export interface BackstopOptions {
+    /** What to do with an unreadable `turn/end` reason. */
+    readonly mode: GuardMode;
+    /** Reason text to record in place of a cause that was never seen. */
+    readonly reason?: string | undefined;
+    /** Bound on the reason text the backstop mints. */
+    readonly maxReasonChars: number;
+    /** Called once per repaired (or, in `observe` mode, merely reported) row. */
+    readonly onRepaired: (report: RepairedTurnEnd) => void;
+}
+/** One `turn/end` row the backstop repaired, as it was reported. */
+export interface RepairedTurnEnd {
+    /** The turn number the row carried, for the log line. */
+    readonly turn: unknown;
+    /** The reason as it arrived — `null`, absent, or a value no reader can dereference. */
+    readonly original: unknown;
+    /** The `hook` member the replacement row carries. */
+    readonly normalized: {
+        readonly kind: 'hook';
+        readonly reason: string;
+    };
+    /** How the original was described for the log. */
+    readonly described: string;
+}
+/** The handle {@link guardSessionAppend} returns: how it went, and an undo. */
+export interface BackstopHandle {
+    /** What happened when the backstop was installed. */
+    readonly outcome: BackstopOutcome;
+    /** Restore the session's own `append`, when this backstop installed one. */
+    readonly restore: () => void;
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@argszero/dsh-cancel-cause-guard",
-  "description": "A plugin that cancels an agent's turn with a cause outside the closed AgentCancelCause union — a bare string like agent.cancel('thinking-loop'), or an object whose kind the union does not have — does not merely log something odd: it makes the whole conversation view unreadable. ReactLoopAgent.cancel hands the value to AbortController.abort(), so it becomes signal.reason; the turn's catch reads it back through abortedCancelCause, whose switch ends in assertNever *inside the catch body*, so turnEnds stays at its null initializer and the unconditional finally appends turn/end with that null (agent-loop/src/agent.ts:385, and the non-null assertion on the line is what makes it compile). Nothing on the write path refuses it — the append-time validator inspects surface slots, request/header and tool/result, and turn/end.reason is a TypeScript-only invariant. Every reader that dereferences it then throws, and the chat view does exactly that while rendering (ui-chat/src/client/contract/turn-process.ts:72), so one such row blanks the conversation area for every session. Reported three times (#8832, #9156, #9646). This plugin closes the seam that is left: it listens to agent/created — the serial, awaited lifecycle edge that hands over the live agent instance (packages/core/agent/src/index.ts:550) — and shadows that instance's cancel with a wrapper that carries anything outside the union as { kind: 'hook', reason } before the loop ever sees it. hook is the member the union 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, because ReactLoopAgent.cancel is a prototype method and the shadow is an own property. Every rewrite is logged with the offending value rendered as JSON, so the producer can be found and fixed rather than tolerated. It never refuses a cancellation, forwards an already-valid cause by reference, and cannot repair rows already on disk. Zero runtime dependencies beyond the harness packages it declares.",
-  "version": "0.1.0",
+  "description": "A plugin that keeps one abusive cancellation from making a whole conversation view unreadable. ReactLoopAgent.cancel hands its argument to AbortController.abort(), so it becomes signal.reason; the turn's catch reads it back through abortedCancelCause, whose switch ends in assertNever *inside the catch body*, so 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 that line is what makes it compile). Nothing on the write path refuses it: the append-time validator inspects surface slots, request/header and tool/result, and turn/end.reason is a TypeScript-only invariant. Every reader that dereferences it then throws, and the chat view does exactly that while rendering (ui-chat/src/client/contract/turn-process.ts:72), so one such row blanks the conversation area for every session, newly created ones included. Reported four times (#8832, #9156, #9646, #9699). This plugin closes the defect at two depths. At the entry: it listens to agent/created — the serial, awaited lifecycle edge that hands over the live agent instance (packages/core/agent/src/index.ts:550) — and shadows that instance's cancel with a wrapper that carries anything outside the union as { kind: 'hook', reason } before the loop ever sees it; hook is the member the union reserves for plugins, so the rewrite is not a lie, and one property write covers every instance-level caller 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 append too, so a turn/end row whose reason no reader can dereference is committed as { kind: 'aborted', reason: { kind: 'hook', reason: <text> } } instead — the arm that covers a caller which reaches the class rather than the instance, or an instance that refuses the own cancel property. 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 tolerated. It never refuses a cancellation, forwards an already-valid cause by reference, leaves any reason a reader can dereference untouched (a plugin's own TurnEndReasonMap variant included), and cannot repair rows already on disk. Zero runtime dependencies beyond the harness packages it declares.",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },