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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 argszero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,278 @@
-# Temporary Holding Version
+# @argszero/dsh-cancel-cause-guard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A prevention guard for the one `turn/end` row that makes a whole conversation view
+unreadable.
+
+The harness ships an `Agent.cancel(cause)` whose argument is a **closed** union —
+`{ kind: 'user' }`, `{ kind: 'parent' }`, `{ kind: 'hook', reason }`,
+`{ 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, and
+backstops the session's own `append` so that even a cancellation it never gets to
+see cannot commit an unreadable row.
+
+## The defect
+
+`ReactLoopAgent.cancel` passes its argument straight to `AbortController.abort()`, so
+the cause becomes `signal.reason`. The turn's `catch` reads it back through
+`abortedCancelCause` (`dsh-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 `catch`**. A value outside the union therefore
+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:312
+...
+} finally {
+  this.session.append('turn/end', { turn, reason: turnEnds! })   // agent.ts:387
+}
+```
+
+The non-null assertion on that line is what makes it compile, and the row lands 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`, so `reason` is a TypeScript-only invariant. Every reader that
+dereferences it then throws — the chat client does `location.turn.end?.data.reason.kind`
+while rendering — and one such row blanks the entire conversation area, for every
+session, including newly created ones.
+
+Reported four times: discussions **#8832**, **#9156**, **#9646** and **#9699**.
+
+### 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 — 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
+`{ kind: 'hook', reason: <the value's own name> }` before the loop ever sees it.
+
+- **`hook` is the right member, not a convenient one.** It is the member the union
+  reserves for plugins: a plugin did cancel the turn, and the reason names which one.
+- **One property write covers every instance-level caller.** `ReactLoopAgent.cancel`
+  is a prototype method, so an **own** property of that name shadows it for the loop's
+  own `agent.cancel({ kind: 'user' })`, the chat client's stop button, and any
+  third-party plugin alike.
+- **A valid cause is forwarded by reference.** The object the loop reads back out of
+  the signal is the object the caller passed; nothing is copied and nothing is
+  reported.
+- **A cancellation is never refused.** The wrapper normalizes, forwards and reports,
+  in that order, and touches nothing but the cause — a plugin that stopped a stop
+  would be worse than the defect.
+- **Two shapes are covered, and only one of them looks like a mistake.** An object
+  whose `kind` is missing or unknown (`{ kind: 'thinking-loop' }`), and a value that
+  is not an object at all — most often `undefined`, from a caller whose own
+  declaration made the argument optional, where `cause.kind` throws one line earlier.
+- **The wrapper binds the original to the agent it came from**, so a caller holding a
+  detached `const cancel = agent.cancel` still reaches the method with the receiver
+  its body requires.
+
+### 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
+
+```sh
+npm install @argszero/dsh-cancel-cause-guard
+```
+
+Then mount it from your profile's bundle patch (`dsh.bundle.patch`):
+
+```yaml
+- insert:
+    - id: cancel-cause-guard
+      name: '@argszero/dsh-cancel-cause-guard'
+```
+
+Or, if you compose `cordis.yml` by hand:
+
+```yaml
+- set:
+    - id: cancel-cause-guard
+      name: '@argszero/dsh-cancel-cause-guard'
+      config:
+        mode: normalize
+```
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `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, 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
+
+One warning per rewritten (or, in `observe` mode, merely reported) cause:
+
+```
+cancel-cause-guard: session <id>: a caller passed "thinking-loop" as a cancellation
+cause, which is not a member of AgentCancelCause; the turn was recorded as
+{ "kind": "aborted", "reason": { "kind": "hook", "reason": "thinking-loop" } }.
+Which plugin passes it is the value itself: the reason carries its own name.
+```
+
+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.
+
+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 — 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 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 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, 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 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
+  cause throwing `unreachable variant: "thinking-loop"` unguarded and returning
+  `{ kind: 'hook', reason: 'thinking-loop' }` guarded, and records the `0.1.6-alpha.2`
+  boundary where no such function exists. Run it with
+  `npm run witness:cancel-cause`.
+- `npm run test:inject` — mutates the source, rebuilds, and requires each mutation to be
+  caught by the suite. An arm whose mutation leaves the suite green proves nothing about
+  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, 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
+
+The suite is measured green against each of these, with `peerDependencies` restricted to
+the same three:
+
+| Harness line | Cordis series |
+|---|---|
+| `0.1.7-rc.2` | `4.0.4` |
+| `0.2.0-rc.2` | `4.0.4` |
+| `0.2.1-alpha.2` | `~4.0.5-alpha.1` |
+
+Earlier generations are **not** covered and are not claimed: `0.1.6-alpha.2` and below
+have no `abortedCancelCause`, so there is nothing for this plugin to prevent there.
+
+## License
+
+MIT.

package/cordis.patch.yml

@@ -0,0 +1,72 @@
+# The @argszero/dsh-cancel-cause-guard bundle patch: mount and go.
+#
+# One `turn/end` row can make a whole conversation view unreadable. When a caller
+# cancels a turn with a value outside 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 hands it 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**:
+# the assignment never runs, `turnEnds` stays at its `null` initializer, and the
+# unconditional `finally` appends `turn/end` with that `null`
+# (`dsh-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 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, and the
+# chat client does exactly that while rendering, so one such row blanks the
+# 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 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.
+#
+# **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:
+#
+#   - set:
+#       - id: cancel-cause-guard
+#         config:
+#           # 'normalize' (default) rewrites an out-of-union cause to
+#           # { kind: 'hook', reason }. 'observe' passes the caller's value through
+#           # untouched — the turn fails exactly as it would have — and only records
+#           # the producer in the log.
+#           mode: normalize
+#           # Reason text to record in place of the offending value's own name.
+#           # Absent (the default) names the cause after the value that produced it,
+#           # which is the only handle on whoever produced it.
+#           # 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.
+
+- insert:
+    - id: cancel-cause-guard
+      name: '@argszero/dsh-cancel-cause-guard'

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