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

package/lib/types/backstop.d.ts

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

package/lib/types/cause.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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;
+/**
+ * Bound one reason so a hostile value cannot write a wall of text into the log.
+ * Shared with the durable backstop, which mints a reason of its own.
+ * @param text - the reason text.
+ * @param maxChars - the bound, in characters.
+ * @returns the text, cut to the bound with a trailing ellipsis when it had to be.
+ */
+export declare function truncate(text: string, maxChars: number): string;
+//# sourceMappingURL=cause.d.ts.map

package/lib/types/config.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Configuration resolution for the cancellation-cause guard.
+ *
+ * The surface is deliberately four fields. A guard that rewrites a value on
+ * paths as hot as cancellation and the session append has to be readable in one
+ * sitting, and every knob it does not have is a way for an operator to be
+ * surprised by what it did.
+ *
+ * An unknown key is refused rather than ignored: a misspelled `mode` that mounts
+ * and guards nothing is how an operator believes a guard is in force when it is
+ * not — the same refusal `dsh-tool-output-budget` makes, for the same reason.
+ *
+ * @module @argszero/dsh-cancel-cause-guard/config
+ */
+import 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,115 @@
+/**
+ * A prevention guard for the one `turn/end` row that makes a whole conversation
+ * view unreadable.
+ *
+ * ## The defect
+ *
+ * A plugin calls `agent.cancel(cause)` with a value that is not a member of the
+ * closed `AgentCancelCause` union — a bare string such as
+ * `agent.cancel('thinking-loop')`, or an object whose `kind` the union does not
+ * have. `ReactLoopAgent.cancel` passes it straight to
+ * `AbortController.abort(cause)`, so the value becomes `signal.reason`; the
+ * turn's `catch` then reads it back through `abortedCancelCause`, whose `switch`
+ * ends in `assertNever` — **inside the catch body**. The assignment never runs,
+ * `turnEnds` stays at its `null` initializer, and the unconditional `finally`
+ * appends `turn/end` with that `null` (`agent-loop/src/agent.ts:385`; the
+ * non-null assertion on the line is what makes it compile).
+ *
+ * Nothing on the write path refuses the row: the append-time validator inspects
+ * surface message slots, `request/header` and `tool/result`, and
+ * `turn/end.reason` is a TypeScript-only invariant. Every reader that
+ * dereferences it then throws — `ui-chat`'s conversation view does
+ * `location.turn.end?.data.reason.kind` while rendering — and one such row
+ * blanks the entire chat area, for every session, including newly created ones.
+ *
+ * ## The version boundary
+ *
+ * A harness older than `0.1.7` had no such function: the turn's `catch` wrote
+ * `{ kind: 'aborted', reason: signal.reason }` verbatim, so the same abuse
+ * produced a malformed-but-readable row rather than a `null` one. From
+ * `0.1.7-rc.2` on, the same abuse is fatal. That is why this is a guard and not
+ * a report: the shape of the failure changed under callers that had not changed
+ * at all.
+ *
+ * ## What this plugin does
+ *
+ * It closes the defect at two depths, and the second one exists for the callers
+ * the first cannot see.
+ *
+ * **At the entry.** It listens to `agent/created` — the serial, awaited lifecycle
+ * edge that hands over the **live agent instance** — and shadows that instance's
+ * `cancel` with a wrapper that normalizes anything outside the union into
+ * `{ kind: 'hook', reason: <the value's own name> }` before the loop ever sees
+ * it. `hook` is the union member the harness reserves for plugins, so the
+ * rewrite is not a lie: a plugin did cancel the turn, and the reason names which
+ * one. One property write covers every instance-level caller — the loop's own
+ * `agent.cancel({ kind: 'user' })`, the client's stop button, and any
+ * third-party plugin — because `ReactLoopAgent.cancel` is a prototype method and
+ * the shadow is an own property.
+ *
+ * **At the write.** The same edge hands over the **live session**, and the
+ * plugin shadows that session's own `append` too, so a `turn/end` row whose
+ * reason no reader can dereference is committed instead as the row the loop meant
+ * to write: `{ kind: 'aborted', reason: { kind: 'hook', reason: <text> } }`. That
+ * arm is what covers the callers the entry guard cannot reach — one that goes
+ * through the class rather than the instance
+ * (`ReactLoopAgent.prototype.cancel.call(agent, …)`, or a second copy of the loop
+ * in the process), and an instance that refuses the own `cancel` property, where
+ * the entry guard simply reports that it is not in force. Set `backstop: false`
+ * to leave the append path exactly as the harness's.
+ *
+ * Every rewrite and every repaired row is logged, with the offending value
+ * rendered as JSON, so the producer can be found and fixed rather than merely
+ * tolerated.
+ *
+ * ## What it does not do
+ *
+ * It does not refuse a cancellation, does not touch the options, does not rewrite
+ * a cause that is already a member (that one is forwarded by reference), and
+ * cannot repair a session that already carries a `null` row — those rows are on
+ * disk, and this plugin reads no history. Mounting it bounds the defect from that
+ * point on.
+ *
+ * `mode: 'observe'` exists for the operator who wants to see the failure happen:
+ * both arms report and neither rewrites, and the log names what arrived.
+ *
+ * @module @argszero/dsh-cancel-cause-guard
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './types.ts';
+export { DEFAULT_MAX_REASON_CHARS, describeValue, isCancelCause, normalizeCancelCause, reasonText, UNSPECIFIED_REASON } from './cause.ts';
+export { APPEND_GUARD_MARK, UNSEEN_CAUSE_REASON, guardSessionAppend, isReadableTurnEndReason, unseenCauseReason } from './backstop.ts';
+export { DEFAULTS, resolveConfig } from './config.ts';
+export { GUARD_MARK, guardCancel } from './guard.ts';
+export type { GuardOptions } from './guard.ts';
+export type { BackstopHandle, BackstopOptions, BackstopOutcome, Config, GuardHandle, GuardMode, GuardOutcome, NormalizedCause, RepairedTurnEnd, ResolvedConfig, } from './types.ts';
+/** Cordis plugin name, used by loader diagnostics. */
+export declare const name = "cancel-cause-guard";
+/**
+ * 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,116 @@
+/**
+ * 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;
+    /**
+     * Whether the durable backstop is installed as well. Defaults to `true`.
+     *
+     * Set `false` to leave the session's own `append` untouched — for an operator
+     * who wants the write path to be exactly the harness's, and accepts that a
+     * cancellation which bypasses the entry guard can then blank a conversation.
+     */
+    readonly backstop?: boolean | undefined;
+}
+/** The configuration after defaults, validation and detaching. */
+export interface ResolvedConfig {
+    readonly mode: GuardMode;
+    readonly reason: string | undefined;
+    readonly maxReasonChars: number;
+    readonly backstop: boolean;
+}
+/** What {@link guardCancel} found when it reached an agent. */
+export type GuardOutcome = 
+/** 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;
+}
+/**
+ * What {@link guardSessionAppend} found when it reached a session.
+ *
+ * The four names mean what {@link GuardOutcome}'s do, for the other property: the
+ * session's `append` now refuses to commit an unreadable `turn/end` reason, some
+ * copy of this plugin is already in place, the session has no callable `append`,
+ * or it refused the own property.
+ */
+export type BackstopOutcome = 'patched' | 'already-guarded' | 'no-append' | 'not-writable';
+/** How one durable backstop is told to behave. */
+export interface BackstopOptions {
+    /** What to do with an unreadable `turn/end` reason. */
+    readonly mode: GuardMode;
+    /** Reason text to record in place of a cause that was never seen. */
+    readonly reason?: string | undefined;
+    /** Bound on the reason text the backstop mints. */
+    readonly maxReasonChars: number;
+    /** Called once per repaired (or, in `observe` mode, merely reported) row. */
+    readonly onRepaired: (report: RepairedTurnEnd) => void;
+}
+/** One `turn/end` row the backstop repaired, as it was reported. */
+export interface RepairedTurnEnd {
+    /** The turn number the row carried, for the log line. */
+    readonly turn: unknown;
+    /** The reason as it arrived — `null`, absent, or a value no reader can dereference. */
+    readonly original: unknown;
+    /** The `hook` member the replacement row carries. */
+    readonly normalized: {
+        readonly kind: 'hook';
+        readonly reason: string;
+    };
+    /** How the original was described for the log. */
+    readonly described: string;
+}
+/** The handle {@link guardSessionAppend} returns: how it went, and an undo. */
+export interface BackstopHandle {
+    /** What happened when the backstop was installed. */
+    readonly outcome: BackstopOutcome;
+    /** Restore the session's own `append`, when this backstop installed one. */
+    readonly restore: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

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