@argszero/dsh-cancel-cause-guard 0.0.0-stage → 0.1.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,207 @@
-# 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, so the
+turn ends with a readable reason instead of `null`.
+
+## 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:310
+...
+} finally {
+  this.session.append('turn/end', { turn, reason: turnEnds! })   // agent.ts:385
+}
+```
+
+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 three times: discussions **#8832**, **#9156** and **#9646**.
+
+### 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.
+
+## What it does
+
+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.
+
+Every rewrite 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 }`; `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. |
+| `maxReasonChars` | `200` | Bound on the minted reason, in characters. |
+
+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.
+
+## 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.
+```
+
+`observe` mode says the value 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
+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.
+
+## 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 calls no model and needs no service.** `inject` is empty: the whole seam is the
+  agent instance the lifecycle edge delivers.
+
+## 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.
+- `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.
+- `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.
+
+## 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,59 @@
+# 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 three times: discussions #8832, #9156 and #9646.
+#
+# 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.
+#
+# 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.
+#
+# 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
+#
+# 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/cause.js

@@ -0,0 +1,199 @@
+/**
+ * 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. */
+function truncate(text, maxChars) {
+    return text.length <= maxChars ? text : `${text.slice(0, maxChars - 1)}…`;
+}

package/lib/config.js

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ *
+ * 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,
+});
+const CONFIG_KEYS = new Set(['mode', 'reason', 'maxReasonChars']);
+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)');
+        }
+    }
+    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)');
+    }
+    return Object.freeze({ mode, reason, maxReasonChars });
+}

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,161 @@
+/**
+ * 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 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.
+ *
+ * Every rewrite 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 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.
+ *
+ * @module @argszero/dsh-cancel-cause-guard
+ */
+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 { 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 guards 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();
+        guards.clear();
+    }, `${LOG_PREFIX}restore()`);
+    ctx.on('agent/created', ({ agent }) => {
+        const handle = guardCancel(agent, {
+            mode: settings.mode,
+            reason: settings.reason,
+            maxReasonChars: settings.maxReasonChars,
+            onNormalized: report => { reportNormalized(ctx, agent.session.id, 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 `
+                    + 'recorded as { kind: "hook", reason } instead of ending the turn with reason null');
+                return;
+            case 'already-guarded':
+                ctx.logger.debug(`${LOG_PREFIX} agent ${agent.session.id}: already guarded by this plugin, leaving the `
+                    + 'existing wrapper in place');
+                return;
+            case 'no-cancel':
+                ctx.logger.warn(`${LOG_PREFIX} agent ${agent.session.id} 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;
+            /* 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 `
+                    + 'is NOT in force for it: an out-of-union cause will end its turn with reason null');
+        }
+    });
+    ctx.on('agent/disposed', ({ agent }) => {
+        const handle = guards.get(agent);
+        if (handle === undefined)
+            return;
+        handle.restore();
+        guards.delete(agent);
+    });
+}
+/**
+ * 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 };

package/lib/types/cause.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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
+ */
+import type { AgentCancelCause } from '@deepseek-ai/dsh-agent';
+/** Bound on a minted reason when the configuration names none. */
+export declare const DEFAULT_MAX_REASON_CHARS = 200;
+/** The reason text standing in for a cause that carried no name at all. */
+export declare const UNSPECIFIED_REASON = "unspecified";
+/** The union member a value from outside the union is carried under. */
+export declare const CARRIER_KIND = "hook";
+/** How one normalization is parameterized. */
+export interface NormalizeOptions {
+    /** Reason text to record, in place of the value's own name. */
+    readonly reason?: string | undefined;
+    /** Bound on the minted reason text. */
+    readonly maxReasonChars?: number | undefined;
+}
+/**
+ * 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 declare function isCancelCause(cause: unknown): cause is AgentCancelCause;
+/**
+ * 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 declare function normalizeCancelCause(cause: unknown, options?: NormalizeOptions): AgentCancelCause;
+/**
+ * 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 declare function reasonText(value: unknown, maxChars?: number): string;
+/**
+ * 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 declare function describeValue(value: unknown, maxChars?: number): string;
+//# sourceMappingURL=cause.d.ts.map

package/lib/types/config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ *
+ * 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 type { Config, ResolvedConfig } from './types.ts';
+/** Defaults for a guard whose only job is to keep a session readable. */
+export declare const DEFAULTS: ResolvedConfig;
+/**
+ * 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 declare function resolveConfig(config?: Config): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/guard.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 type { Agent } from '@deepseek-ai/dsh-agent';
+import type { GuardHandle, GuardMode, NormalizedCause } from './types.ts';
+/**
+ * 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 declare const GUARD_MARK: unique symbol;
+/** How one guard is told to behave. */
+export interface GuardOptions {
+    /** What to do with an out-of-union cause. */
+    readonly mode: GuardMode;
+    /** Reason text to record in place of the value's own name. */
+    readonly reason?: string | undefined;
+    /** Bound on the minted reason text. */
+    readonly maxReasonChars: number;
+    /** Called once per rewritten (or, in `observe` mode, merely reported) cause. */
+    readonly onNormalized: (report: NormalizedCause) => void;
+}
+/**
+ * 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 declare function guardCancel(agent: Agent, options: GuardOptions): GuardHandle;
+//# sourceMappingURL=guard.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 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.
+ *
+ * Every rewrite 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 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.
+ *
+ * @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 { 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';
+/** Cordis plugin name, used by loader diagnostics. */
+export declare 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 declare const inject: readonly string[];
+/**
+ * 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 declare function apply(ctx: Context, config?: Config): void;
+declare const _default: {
+    name: string;
+    inject: readonly string[];
+    apply: typeof apply;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The shapes this plugin's configuration and its guard report take.
+ *
+ * @module @argszero/dsh-cancel-cause-guard/types
+ */
+/**
+ * What the guard does with a cause that is not a member of the closed union.
+ *
+ * - `normalize` — the default, and the reason the plugin exists: the value is
+ *   carried as a `{ kind: 'hook', reason }` cause, the turn ends normally, and
+ *   the log records which value was rewritten.
+ * - `observe` — the value is passed through unchanged, so the turn fails exactly
+ *   as it would without the plugin, and the log records what was seen. This is
+ *   the arm for an operator who wants to find a producer before protecting the
+ *   session from it: the plugin reports, and nothing else changes.
+ */
+export type GuardMode = 'normalize' | 'observe';
+/** The plugin configuration as mounted; every field is optional. */
+export interface Config {
+    /** What to do with an out-of-union cause. Defaults to `normalize`. */
+    readonly mode?: GuardMode | undefined;
+    /**
+     * The reason text to record for every cause the guard rewrites, in place of
+     * the value's own name. Defaults to the name the value carried (`'thinking-loop'`
+     * for `{ kind: 'thinking-loop' }`, a JSON rendering otherwise).
+     */
+    readonly reason?: string | undefined;
+    /** Bound on the reason text the guard mints. Defaults to 200. */
+    readonly maxReasonChars?: number | undefined;
+}
+/** The configuration after defaults, validation and detaching. */
+export interface ResolvedConfig {
+    readonly mode: GuardMode;
+    readonly reason: string | undefined;
+    readonly maxReasonChars: number;
+}
+/** What {@link guardCancel} found when it reached an agent. */
+export type GuardOutcome = 
+/** The instance's own `cancel` now normalizes out-of-union causes. */
+'patched'
+/** Somebody's guard — this plugin's, mounted twice — is already in place. */
+ | 'already-guarded'
+/** The instance carries no callable `cancel`; there is nothing to shadow. */
+ | 'no-cancel'
+/** The instance refuses an own property (`cancel` is non-writable, or the object is sealed). */
+ | 'not-writable';
+/** One cause the guard rewrote, as it was reported. */
+export interface NormalizedCause {
+    /** The value the caller passed. */
+    readonly original: unknown;
+    /** The union member it was carried as. */
+    readonly normalized: {
+        readonly kind: 'hook';
+        readonly reason: string;
+    };
+    /** How the original was described for the log. */
+    readonly described: string;
+}
+/** The handle {@link guardCancel} returns: how it went, and an undo. */
+export interface GuardHandle {
+    /** What happened when the guard was installed. */
+    readonly outcome: GuardOutcome;
+    /** Restore the instance's own `cancel`, when this guard installed one. */
+    readonly restore: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.js

@@ -0,0 +1,6 @@
+/**
+ * The shapes this plugin's configuration and its guard report take.
+ *
+ * @module @argszero/dsh-cancel-cause-guard/types
+ */
+export {};

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@argszero/dsh-cancel-cause-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/argszero/dsh-cancel-cause-guard.git"
+  },
+  "homepage": "https://github.com/argszero/dsh-cancel-cause-guard#readme",
+  "bugs": {
+    "url": "https://github.com/argszero/dsh-cancel-cause-guard/issues"
+  },
+  "keywords": [
+    "cordis",
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "agent-cancel",
+    "cancel-cause",
+    "turn-end",
+    "session-integrity",
+    "agent-lifecycle",
+    "guard"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2 || ~4.0.5-alpha.1",
+    "@deepseek-ai/dsh-agent": ">=0.1.7-rc.2 <0.2.0 || >=0.2.0-rc.1 <0.2.1-alpha.2 || >=0.2.1-alpha.2 <0.3.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
+    "@types/node": "^24.19.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "pretest": "tsc",
+    "test": "node --test \"test/*.spec.mjs\"",
+    "prepublishOnly": "tsc",
+    "test:inject": "node scripts/inject-defects.mjs",
+    "probe:lines": "node scripts/probe-lines.mjs",
+    "witness:cancel-cause": "node scripts/witness-cancel-cause.mjs"
+  },
+  "engines": {
+    "node": "^22.19 || >=24"
+  }
+}