@matatbread/matbot-core 0.4.14 → 0.4.16

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.14",
+  "version": "0.4.16",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@matatbread/matbot-plugin-api": "^0.4.14"
+    "@matatbread/matbot-plugin-api": "^0.4.16"
   },
   "devDependencies": {
     "typescript": "^6.0.3"

package/src/config/loader.ts

@@ -21,6 +21,12 @@ export interface MatbotConfig {
    * config rather than data. A stored value always wins; `delete` reverts to the default here.
    */
   defaultSettings?:  ReadonlyMap<string, Readonly<Record<string, unknown>>>;
+  /**
+   * Longest a `tool_function` body may run synchronously — without awaiting — before it is stopped
+   * (`function_timeout_ms`). Absent ⇒ the host's default. `0` ⇒ no limit at all, for testing: bodies run
+   * directly, and a loop that never awaits freezes the process.
+   */
+  functionTimeoutMs?: number;
 }
 
 function asString(v: YamlValue | undefined, label: string): string {
@@ -80,6 +86,21 @@ function toProviderConfig(name: string, raw: YamlMap): ProviderConfig {
   return config;
 }
 
+/**
+ * Parse a config document, optionally over a `base` one it `extends:`.
+ *
+ * **The merge is per TOP-LEVEL KEY, and the derived document REPLACES rather than extends.** A child
+ * declaring `plugins:` supplies the whole list — the base's entries are not appended — and the same
+ * holds for `providers:` and `default_settings:`. There is no deep merge and no per-entry merge: the
+ * unit is the section.
+ *
+ * That is deliberately stated rather than deliberately chosen. Section-replacement is what the one-line
+ * spread has always done, and a caller reading "extends" reasonably expects the other reading, so the
+ * semantics are pinned by test (config-extends.test.ts) — change them on purpose, not by editing this
+ * line. Note also that `extends:` does not today give you a shared base: the CLI chdirs to the base's
+ * directory and rewrites `configPath`, so the base becomes the project (`.data`, `.env`, and every yaml
+ * write land there). See CLAUDE.md, *Default plugin settings*.
+ */
 export function parseConfig(
   text:  string,
   base?: string,
@@ -123,6 +144,17 @@ export function parseConfig(
     }
   }
 
+  const functionTimeoutRaw = doc['function_timeout_ms'];
+  let functionTimeoutMs: number | undefined;
+  if (functionTimeoutRaw !== undefined && functionTimeoutRaw !== null) {
+    functionTimeoutMs = asNumber(functionTimeoutRaw, 'function_timeout_ms');
+    // Refused rather than clamped, like maxRounds: a negative or fractional limit is a typo, and `0` already
+    // means something of its own.
+    if (!Number.isInteger(functionTimeoutMs) || functionTimeoutMs < 0) {
+      throw new Error(`Config: "function_timeout_ms" must be a non-negative integer (milliseconds; 0 removes the limit), got ${functionTimeoutMs}`);
+    }
+  }
+
   const prompt           = typeof doc['prompt']            === 'string' ? doc['prompt']            : undefined;
   const ephemeral        = doc['ephemeral'] === true ? true : undefined;
   const defaultProvider  = typeof doc['default_provider'] === 'string' ? doc['default_provider']  : undefined;
@@ -136,6 +168,7 @@ export function parseConfig(
     ...(defaultProvider  !== undefined ? { defaultProvider  } : {}),
     ...(principal        !== undefined ? { principal        } : {}),
     ...(defaultSettings.size > 0       ? { defaultSettings  } : {}),
+    ...(functionTimeoutMs !== undefined ? { functionTimeoutMs } : {}),
   };
 }
 

package/src/config/yaml.ts

@@ -6,7 +6,7 @@
  *   - Block sequences (- item), including an item whose value is an indented block under a bare `-`
  *   - Scalar types: string, number, boolean, null
  *   - Quoted strings (single and double), as values and as keys
- *   - Comments (# ...)
+ *   - Comments (# ...), outside quotes and at a line start or after whitespace (see stripComment)
  *
  * Does NOT support anchors, aliases, flow syntax, or ${NAME} expansion.
  * ${NAME} placeholders are left intact for the Vault to resolve.
@@ -36,11 +36,47 @@ interface Token {
   line:   number;
 }
 
+// Where a `#` opens a comment, per YAML's own rule: outside a quoted scalar, and at the start of a
+// line or after whitespace. Stripping every `#` truncated values that legitimately contain one —
+// `github:owner/repo#path:sub` lost its subdirectory, and a quoted value lost everything from the `#`
+// on, INCLUDING its closing quote, so it then failed to unquote and kept a stray `"`. Both were silent.
+//
+// A quote only opens a quoted scalar where a scalar can start (line start, or after the `:`/`-` that
+// introduces a value); elsewhere it is an apostrophe in a plain scalar (`title: Matt's config`), and
+// treating it as an opening quote would swallow a real trailing comment.
+//
+// Still unhandled, as before: a `#` inside a block scalar (`|`/`>`) body, and a backslash-escaped quote
+// — this parser does not process escapes anywhere (see `unquote`).
+function stripComment(line: string): string {
+  let quote: string | undefined;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i]!;
+    if (quote !== undefined) {
+      if (ch === quote) quote = undefined;
+      continue;
+    }
+    if ((ch === '"' || ch === "'") && opensScalar(line, i)) { quote = ch; continue; }
+    if (ch === '#' && (i === 0 || line[i - 1] === ' ' || line[i - 1] === '\t')) return line.slice(0, i);
+  }
+  return line;
+}
+
+// Is position `i` somewhere a scalar can begin — nothing but whitespace before it, or the `:`/`-` that
+// introduces one? Keys count: `'@scope/pkg':` is a quoted scalar at line start.
+function opensScalar(line: string, i: number): boolean {
+  for (let j = i - 1; j >= 0; j--) {
+    const ch = line[j]!;
+    if (ch === ' ' || ch === '\t') continue;
+    return ch === ':' || ch === '-';
+  }
+  return true;
+}
+
 function tokenize(text: string): Token[] {
   const tokens: Token[] = [];
   const lines = text.split('\n');
   for (let n = 0; n < lines.length; n++) {
-    const stripped = lines[n]!.replace(/#.*$/, '').trimEnd();
+    const stripped = stripComment(lines[n]!).trimEnd();
     if (stripped.trim() === '') continue;
     const indent = stripped.length - stripped.trimStart().length;
     tokens.push({ indent, raw: stripped.trimStart(), line: n + 1 });

package/src/index.ts

@@ -23,7 +23,7 @@ export { applyCreateSecret, assertStorableKey, unreferenceableKey, REFERENCEABLE
 // that apply one cannot differ on what a patch MEANS, and re-exported here so an app needs no direct
 // plugin-api dependency to get it.
 export { applyProviderPatch, patchedFields } from '@matatbread/matbot-plugin-api';
-export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind } from '@matatbread/matbot-plugin-api';
+export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind, FUNCTION_TIMEOUT } from '@matatbread/matbot-plugin-api';
 // The canonical `type: 'confirm'` answers. Same reason as the patch policy above: an app implementing a
 // PromptFn (or a test standing one in) has to speak them, and must not hard-code the rendered label.
 export { CONFIRM_YES, CONFIRM_NO } from '@matatbread/matbot-plugin-api';
@@ -46,10 +46,11 @@ export {
   contextSwitch, machineBusy, quiesced, onContextQuiesce, scheduleAtEdge,
   installUsageCarrier, createSerialUsageCarrier, recordUsage, recordSpan, currentUsageSink,
   currentUsageScope, currentUsageSite, withUsageScope, withUsageSite,
+  scopeIterator, scopeIterable,
 } from '@matatbread/matbot-plugin-api/host';
 export type {
   Subscribable, Broadcaster, Routed, RoutedFilter, SwapFn, MountTable, PrincipalCarrier, UsageCarrier,
-  UsageScope, Quiescer,
+  UsageScope, Quiescer, ScopeFn,
 } from '@matatbread/matbot-plugin-api/host';
 export * from './session.js';
 export * from './usage.js';

package/src/knowledge/lookup-knowledge-index.ts

@@ -124,9 +124,10 @@ export class LookupKnowledgeIndex implements KnowledgeIndex {
   }
 
   async search(
-    terms:   Array<{ term: string; context?: string }>,
-    _signal: AbortSignal,
+    terms:  Array<{ term: string; context?: string }>,
+    signal: AbortSignal,
   ): Promise<KnowledgeEntry[]> {
+    signal.throwIfAborted();
     if (terms.length === 0) return [];
 
     const scored: Array<{ entry: KnowledgeEntry; score: number }> = [];

package/src/loader.ts

@@ -4,9 +4,10 @@ import { incompatibleRuntimeError, notAPluginError } from '@matatbread/matbot-pl
 import { registerPlugin, setupPlugin, unloadPlugin, recordFailedPlugin, clearFailedPlugin, announcePluginLoaded } from './registry.js';
 
 /**
- * The runtime this process is executing in. Detected the same way the rejected-import branch below
- * already distinguishes platforms (`typeof window`). Used only for the declarative pre-import gate;
- * an absent `matbotRuntime` declaration bypasses the gate entirely.
+ * The runtime this process is executing in — the one place this module decides what platform it is on.
+ * Read by the declarative pre-import gate (an absent `matbotRuntime` declaration bypasses it entirely)
+ * and by the import-rejection branch, which re-derived `typeof window` inline until the two could have
+ * disagreed.
  */
 const CURRENT_RUNTIME: Runtime = typeof window !== 'undefined' ? 'browser' : 'node';
 
@@ -30,6 +31,23 @@ const FRESH_PARAM = 'mbfresh';
 // produce the same stamp and re-hit the cache.
 let freshSeq = 0;
 
+/**
+ * One entry to load, for a host that has already done its own resolution — the object form of a plain
+ * specifier string. Every field is documented on {@link loadPlugins}, which is the only consumer.
+ *
+ * Named, because it was written out twice: once in the parameter list and once again in the `as` cast
+ * of the line that normalises the strings. Two spellings of one shape, where adding a field to the
+ * wrong one narrows what the loader will read from a host that is already passing it.
+ */
+export interface LoadRequest {
+  spec:        string;
+  importSpec?: string;
+  name?:       string;
+  version?:    string;
+  runtimes?:   readonly Runtime[];
+  notes?:      readonly string[];
+}
+
 /**
  * Load plugins from the given specifiers, register them, then run setup().
  *
@@ -100,13 +118,13 @@ let freshSeq = 0;
  *   only as a confusing empty-result error downstream — fail loudly with the reason instead.
  */
 export async function loadPlugins(
-  specifiers: readonly (string | { spec: string; importSpec?: string; name?: string; version?: string; runtimes?: readonly Runtime[]; notes?: readonly string[] })[],
+  specifiers: readonly (string | LoadRequest)[],
   services:   MatbotMachine,
   bustCache = false,
   prompt?:    PromptFn,
   onLoadError: 'skip' | 'throw' = 'skip',
 ): Promise<MatbotPlugin[]> {
-  const reqs = specifiers.map(s => (typeof s === 'string' ? { spec: s } : s) as { spec: string; importSpec?: string; name?: string; version?: string; runtimes?: readonly Runtime[]; notes?: readonly string[] });
+  const reqs: LoadRequest[] = specifiers.map(s => (typeof s === 'string' ? { spec: s } : s));
 
   // A reason reaching a user, decorated with what the host noticed while resolving this spec. The
   // failure a load reports is usually downstream of its cause, and the host is the only layer that
@@ -200,7 +218,7 @@ export async function loadPlugins(
 
     if (result.status === 'rejected') {
       const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
-      if (typeof window !== 'undefined') {
+      if (CURRENT_RUNTIME === 'browser') {
         // Browser: warn and skip — browser environments have no node_modules fallback.
         console.warn(`[matbot] Could not load plugin "${spec}" (browser: use a URL path or configure an import map): ${reason}`);
         recordFailedPlugin({ specifier: spec, error: reason });
@@ -307,19 +325,6 @@ export async function loadPlugins(
   return loaded;
 }
 
-/**
- * Stamp a plugin entry URL with a unique `${FRESH_PARAM}` value to force a fresh
- * evaluation (and, with the node resolve hook, a fresh subtree — see FRESH_PARAM).
- *
- * Diagnostics: cache-busting silently degrades in two ways that are
- * indistinguishable from "it worked" at the call site, so both are logged here.
- *   1. import.meta.resolve throws (e.g. a cwd-relative spec that does not resolve
- *      relative to *this* module's URL) — we fall back to the bare spec, which
- *      re-imports the *cached* module. No busting happens at all.
- *   2. Resolution succeeds but no resolve hook is installed: only the entry is
- *      re-evaluated, while everything it statically imports stays cached. We can
- *      detect (1) here; (2) is noted at the call site.
- */
 /**
  * Classify how a specifier resolves to code, from its shape alone (platform-neutral; no fs).
  * github shorthand is only recognised via the explicit `github:` prefix — a bare `owner/repo`
@@ -379,6 +384,18 @@ function stampFresh(url: string): string {
   return u.href;
 }
 
+/**
+ * Stamp a plugin entry URL with a unique `${FRESH_PARAM}` value to force a fresh evaluation (and, with
+ * the node resolve hook, a fresh subtree — see FRESH_PARAM).
+ *
+ * Diagnostics: cache-busting silently degrades in two ways that are indistinguishable from "it worked"
+ * at the call site, so both are logged.
+ *   1. import.meta.resolve throws (e.g. a cwd-relative spec that does not resolve relative to *this*
+ *      module's URL) — we fall back to the bare spec, which re-imports the *cached* module. No busting
+ *      happens at all. Detected here.
+ *   2. Resolution succeeds but no resolve hook is installed: only the entry is re-evaluated, while
+ *      everything it statically imports stays cached. Noted at the call site.
+ */
 function toFreshUrl(spec: string): string {
   try {
     const fresh = stampFresh(import.meta.resolve(spec));

package/src/media.ts

@@ -151,8 +151,13 @@ export async function ingestMedia(
   }
 
   // Derived, not counted — see MAX_MEDIA_BYTES_PER_SESSION. One listing for the whole batch.
+  //
+  // Filtered by NAMESPACE as well as session: the media store is routinely the host's own file area, so
+  // a `sessionId`-tagged workspace file or a detached job's output shares the listing and was being
+  // charged to the media quota. The quota is over what THIS path stored, which is what the namespace
+  // names — and it is the same pair the per-ref ownership check below tests against.
   let sessionBytes = 0;
-  for await (const held of store.list({ sessionId })) sessionBytes += held.size;
+  for await (const held of store.list({ sessionId, namespace: MEDIA_NAMESPACE })) sessionBytes += held.size;
 
   const out: MessageContent[] = [];
   for (const c of content) {

package/src/registry.ts

@@ -3,7 +3,7 @@ import { RegistryChangeKind } from '@matatbread/matbot-plugin-api';
 import { scopedNotifier, askPermissionGate } from '@matatbread/matbot-plugin-api/host';
 import type {
   MatbotPlugin, MatbotMachine, MatbotRuntime, Mounted,
-  ProviderAdapterFactory, StoreFactory,
+  ProviderAdapterFactory,
 } from './plugin.js';
 import { PLUGIN_API_VERSION, unifyServices } from './plugin.js';
 import { makePluginSettings } from './settings.js';
@@ -18,7 +18,6 @@ import type { SettingsDoc } from './settings.js';
 const state = {
   plugins:         [] as MatbotPlugin[],
   providers:       new Map<string, ProviderAdapterFactory>(),
-  storage:         new Map<string, StoreFactory>(),
   toolRegistry:    undefined as ToolRegistry | undefined,
   frontendPlugins:  new Map<string, FrontendInfo>(),  // pluginName → info, written by services.registerFrontend()
   serviceKeys:     new Map<string, string[]>(),  // pluginName → MatbotMachine keys it registered
@@ -114,24 +113,11 @@ export function registerPlugin(plugin: MatbotPlugin): void {
     throw new Error(`Provider "${plugin.name}" is already registered.`);
   }
 
-  for (const type of Object.keys(plugin.storage ?? {})) {
-    if (state.storage.has(type)) {
-      const owner = state.plugins.find(p => p.storage?.[type] !== undefined)?.name ?? '?';
-      throw new Error(
-        `Storage type "${type}" is already registered by "${owner}". ` +
-        `"${plugin.name}" cannot register it again.`,
-      );
-    }
-  }
-
   state.plugins.push(plugin);
 
   if (plugin.provider !== undefined) {
     state.providers.set(plugin.name, plugin.provider);
   }
-  for (const [type, factory] of Object.entries(plugin.storage ?? {})) {
-    state.storage.set(type, factory);
-  }
 }
 
 // ── Resolution ────────────────────────────────────────────────────────────────
@@ -313,6 +299,9 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
   // own settings — there is no way to name another's.
   const ownSettings = makePluginSettings(services.createStore<SettingsDoc>('settings'), plugin.name);
 
+  // Plugin-scoped notifier, likewise built once. See the `Notifier` member below.
+  const ownNotifier = scopedNotifier(services.Notifier, plugin.name);
+
   // Per-plugin `mounted`: a thin adapter over the host mount table that delivers *this plugin's* scoped
   // machine (and scoped onUnmount) to handlers. The stable `scoped` object reads through the host's
   // re-pointing proxies/registry, so `scoped[key]` is the host's live service by the time a transition
@@ -353,9 +342,11 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
     // being a deliberate read of the concrete gate at that moment.
     get PermissionGate() { return services.PermissionGate; },
     // Everything this plugin publishes is attributed to it by default — the notification analogue of
-    // stamping `pluginName` on its tools. Reads through the host's swap proxy, so a registered
-    // distributed Notifier takes effect for a plugin that captured this in setup().
-    get Notifier() { return scopedNotifier(services.Notifier, plugin.name); },
+    // stamping `pluginName` on its tools. Wrapped ONCE per plugin (below), not per property read: this
+    // was a getter, so every `services.Notifier.notify(...)` minted a fresh three-method object. Swap
+    // safety is unaffected, because what is wrapped is the host's capture-safe proxy — both hosts put
+    // that stable object on the machine — so a registered distributed Notifier still takes effect.
+    Notifier: ownNotifier,
     tools: {
       register:      registerTool,
       remove:        (name: string) => services.tools.remove(name),
@@ -420,16 +411,25 @@ export async function unloadPlugin(pluginName: string, services: MatbotMachine):
   state.systemContextPlugins.delete(pluginName);
 
   if (plugin.provider !== undefined) state.providers.delete(plugin.name);
-  for (const type of Object.keys(plugin.storage   ?? {})) state.storage.delete(type);
 
   state.frontendPlugins.delete(pluginName);
 
   state.plugins.splice(idx, 1);
   services.Notifier.notify({ kind: RegistryChangeKind, source: 'plugins', registry: 'plugins', name: pluginName, operation: 'removed' });
-  await Promise.race([
-    plugin.teardown?.(),
-    new Promise<void>((_, reject) => setTimeout(() => reject(new Error(`Teardown timeout for plugin ${pluginName}`)), 10000))
-  ]);
+  // The timer is cleared however the race settles. Left dangling it outlived every SUCCESSFUL unload,
+  // holding the event loop open for the rest of its 10s — so `plugin unload` followed by exit sat there
+  // with nothing to wait for.
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      plugin.teardown?.(),
+      new Promise<void>((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`Teardown timeout for plugin ${pluginName}`)), 10_000);
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
   return true;
 }
 

package/src/runner.ts

@@ -1,15 +1,15 @@
 import type {
   Session, Message, MessageContent, ModelContent, Usage, UsageSite, ProviderMeta, TruncatedToolResult,
   TurnEvent, RunConfig, ProviderAdapter, ProviderConfig,
-  Tool, ToolRegistry, ToolContext, Store, FileStore, MediaStore, SystemContextRegistry, Vault, PromptFn, FormField,
+  Tool, ToolRegistry, ToolContext, Store, FileStore, MediaStore, SystemContextRegistry, Vault, PromptFn,
   PermissionGate,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
 import type { ToolPresenter } from '@matatbread/matbot-plugin-api';
-import { recordSpan, recordUsage, withUsageSite } from '@matatbread/matbot-plugin-api/host';
+import { recordSpan, recordUsage, withUsageSite, scopeIterable } from '@matatbread/matbot-plugin-api/host';
 import { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
-import { foldOntoUserTurn, bindPluginOps, bindGate } from '@matatbread/matbot-plugin-api';
+import { foldOntoUserTurn, bindPluginOps, bindGate, defaultingPrompt } from '@matatbread/matbot-plugin-api';
 import { addUsage } from './usage.js';
 import { MEDIA_RESIDENCY_BYTES, resolveSessionMedia } from './media.js';
 
@@ -17,24 +17,13 @@ import { MEDIA_RESIDENCY_BYTES, resolveSessionMedia } from './media.js';
 // runner is itself an async generator, so it suspends at every `yield` and resumes under the consumer's
 // context, losing any scope entered around the loop body. Scoping each `next()` instead means the
 // tool's body — and anything it kicks off while running — always resumes under its own site.
-function siteScoped<T>(site: UsageSite, src: AsyncIterable<T>): AsyncIterable<T> {
-  return {
-    [Symbol.asyncIterator]: () => {
-      const it = src[Symbol.asyncIterator]();
-      return {
-        next:  ()  => withUsageSite(site, () => it.next()),
-        ...(it.return ? { return: (v?: never) => withUsageSite(site, () => it.return!(v)) } : {}),
-        ...(it.throw  ? { throw:  (e?: unknown) => withUsageSite(site, () => it.throw!(e))  } : {}),
-      };
-    },
-  };
-}
+//
+// `scopeIterable` is the shared per-pull wrap, as used by `runAs` for the principal: this had its own
+// object-literal copy, which replaced the iterator wholesale and so dropped a class-based tool
+// iterator's own members, prototype and `instanceof`.
+const siteScoped = <T>(site: UsageSite, src: AsyncIterable<T>): AsyncIterable<T> =>
+  scopeIterable(src, f => withUsageSite(site, f));
 
-// Substituted for an errored tool result when the turn was aborted (e.g. a mid-turn steer interrupt):
-// the tool was cut off, not genuinely faulty, and the raw abort reason ("Error: steer") is a leaked
-// internal token that reads as a real failure. A steer's continuation turn is the one place a model
-// reads this, so the wording tells it the call was interrupted and leaves re-running to its judgement —
-// deliberately NOT "re-run it", so a side-effecting tool isn't reflexively repeated.
 // Creator of the marker recording that a provider cut a response short. Marker-role, so it is durable
 // and visible to a reader while elided from every submission: the model's own text is already truncated
 // in the transcript, and a block telling it so invites narrating the cut-off rather than continuing.
@@ -45,6 +34,19 @@ const TRUNCATION_CREATOR = 'matbot-truncation';
 const abortReason = (signal: AbortSignal): string =>
   typeof signal.reason === 'string' ? signal.reason : 'user-abort';
 
+/**
+ * A thrown value as a turn-terminal message, with its `cause` appended when it has one.
+ *
+ * A `throw` carries anything, so this narrows before reaching for `cause`: `'cause' in e` throws
+ * TypeError on a primitive, which made the catch handler ITSELF throw for a provider that rejected
+ * with a string — escaping the generator and skipping the `end()` commit that the branch calling this
+ * exists to perform. The one place in this package that took `any` rather than narrow.
+ */
+const errorText = (e: unknown): string => {
+  const cause = typeof e === 'object' && e !== null && 'cause' in e ? (e as { cause?: unknown }).cause : undefined;
+  return cause ? `${String(e)} (${String(cause)})` : String(e);
+};
+
 /** How long a tool executor may keep the turn alive AFTER the turn was aborted, before the runner stops
  *  reading it. An abort must abort: any executor can fail to end — a child process whose stdout was
  *  inherited by an orphan, a generator awaiting something that never settles, a bridged remote that went
@@ -73,6 +75,11 @@ function abandonDeadline(signal: AbortSignal, ms: number): { wait: Promise<typeo
   };
 }
 
+// Substituted for an errored tool result when the turn was aborted (e.g. a mid-turn steer interrupt):
+// the tool was cut off, not genuinely faulty, and the raw abort reason ("Error: steer") is a leaked
+// internal token that reads as a real failure. A steer's continuation turn is the one place a model
+// reads this, so the wording tells it the call was interrupted and leaves re-running to its judgement —
+// deliberately NOT "re-run it", so a side-effecting tool isn't reflexively repeated.
 const INTERRUPTED_TOOL_RESULT = {
   error: 'Tool call interrupted before completion — the turn was interrupted while it was running. It may not have run to completion, and any side effect may or may not have occurred. Re-run it only if you still need its result.',
 } as const;
@@ -137,12 +144,9 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
   const { config, provider, providerConfig, store, signal } = opts;
   const tools   = opts.tools   ?? new Map<string, Tool>();
   const hookReg = opts.hooks   ?? new HookRegistry();
-  const promptFn: PromptFn = opts.prompt ?? (((p: string | FormField, def?: string): Promise<string> => {
-    const fallback = typeof p === 'string' ? def : p.default;
-    if (fallback !== undefined) return Promise.resolve(fallback);
-    const label = typeof p === 'string' ? p : p.label;
-    return Promise.reject(new Error(`Non-interactive context: cannot prompt for "${label}"`));
-  }) as PromptFn);
+  // The stand-in answers with a field's own default where it has one — which is precisely why the gate
+  // below is handed `opts.prompt` raw instead (see bindGate).
+  const promptFn: PromptFn = opts.prompt ?? defaultingPrompt;
   const vault: Vault = opts.vault ?? {
     async createSecret() { throw new Error('No vault configured'); },
     async writeSecret()  { throw new Error('No vault configured'); },
@@ -408,7 +412,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
             break;
         }
       }
-    } catch (e: any) {
+    } catch (e: unknown) {
       // A provider call cancelled by an in-situ restart (callAc, not the turn signal) is expected — fall
       // through to the restart below rather than surfacing it as a turn abort or an error.
       if (restart || (callAc.signal.aborted && !signal.aborted)) {
@@ -436,7 +440,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
         // carries no session (a failure is not a transcript), so this yields the terminal itself rather
         // than the session — but it commits first, exactly like every other exit.
         bookRound();
-        yield* end({ type: 'error', error: String(e) + (('cause' in e && e.cause) ? ' ('+String(e.cause)+')' : '' ), traceId });
+        yield* end({ type: 'error', error: errorText(e), traceId });
         return;
       }
     }

package/src/session-runner.ts

@@ -165,10 +165,16 @@ function createSink(dispose: () => void): Sink {
   };
 }
 
-export function wireDescription(description: string, wc: { params: string; result: string } | undefined) {
-  return wc
-    ? `${description}\n\nTypeScript params:\n\`\`\`\n${wc.params}\n\`\`\`\n\nTypeScript result:\`\`\`${wc.result}\n\`\`\``
-    : description;
+/**
+ * A tool's description with its wire contract appended — the text the model actually reads for every
+ * tool, every turn. Both blocks are fenced identically; the result block used to omit the newline after
+ * its label and before its fence, so the type opened inline against "TypeScript result:```" and the
+ * block never closed where a reader expects it.
+ */
+export function wireDescription(description: string, wc: { params: string; result: string } | undefined): string {
+  if (wc === undefined) return description;
+  const block = (label: string, type: string): string => `${label}:\n\`\`\`\n${type}\n\`\`\``;
+  return `${description}\n\n${block('TypeScript params', wc.params)}\n\n${block('TypeScript result', wc.result)}`;
 }
 
 export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
@@ -280,295 +286,288 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
     // site, and spelling it here made it something the next caller of `machineBusy` could omit without
     // any symptom — so it moved inside the hold it guards.
     return machineBusy(async () => {
-    try {
-      while (s.queue.length > 0) {
-        // Per-submission concat: the head always runs; if the head is a concat submission it absorbs
-        // the following submissions while they too are concat, stopping at the first non-concat (a turn
-        // boundary). Net effect: maximal runs of consecutive concat submissions merge into one turn,
-        // while every queued/robo submission stays its own ordered turn — concat and queued mix freely.
-        const head  = s.queue.shift()!;
-        const batch = [head];
-        if (head.concatQueue) {
-          while (s.queue.length > 0 && s.queue[0]!.concatQueue) batch.push(s.queue.shift()!);
-        }
-        const content = batch.flatMap(i => i.content);
-        s.runningTraceId = head.traceId;
-        s.replay = [];
-        // Seed replay with the running turn's user message as a single merged `queued`, mirroring the
-        // message persisted just below. notify() (in open()) reaches only subscribers that are live at
-        // enqueue time; a GET /events/sessions/:id that connects after this synchronous preamble — the
-        // common case when the submit POST wins the race against the events stream — would otherwise
-        // find an empty queue and a cleared replay, and never render the user bubble. One merged event
-        // (not one per batch item) matches both stored history on reload and the live fold, so a late
-        // subscriber reconstructs exactly one bubble. A redo carries no new user message (and no
-        // content), so it seeds nothing — its retraction marker already went out at enqueue time.
-        if (head.redo === undefined) {
-          s.replay.push({ type: 'queued', content, queued: 0, concatQueue: false, traceId: head.traceId, rootTraceId: head.rootTraceId });
-        }
+      try {
+        while (s.queue.length > 0) {
+          // Per-submission concat: the head always runs; if the head is a concat submission it absorbs
+          // the following submissions while they too are concat, stopping at the first non-concat (a turn
+          // boundary). Net effect: maximal runs of consecutive concat submissions merge into one turn,
+          // while every queued/robo submission stays its own ordered turn — concat and queued mix freely.
+          const head  = s.queue.shift()!;
+          const batch = [head];
+          if (head.concatQueue) {
+            while (s.queue.length > 0 && s.queue[0]!.concatQueue) batch.push(s.queue.shift()!);
+          }
+          const content = batch.flatMap(i => i.content);
+          s.runningTraceId = head.traceId;
+          s.replay = [];
+          // Seed replay with the running turn's user message as a single merged `queued`, mirroring the
+          // message persisted just below. notify() (in open()) reaches only subscribers that are live at
+          // enqueue time; a GET /events/sessions/:id that connects after this synchronous preamble — the
+          // common case when the submit POST wins the race against the events stream — would otherwise
+          // find an empty queue and a cleared replay, and never render the user bubble. One merged event
+          // (not one per batch item) matches both stored history on reload and the live fold, so a late
+          // subscriber reconstructs exactly one bubble. A redo carries no new user message (and no
+          // content), so it seeds nothing — its retraction marker already went out at enqueue time.
+          if (head.redo === undefined) {
+            s.replay.push({ type: 'queued', content, queued: 0, concatQueue: false, traceId: head.traceId, rootTraceId: head.rootTraceId });
+          }
 
-        let session = await deps.store.get(id);
-        if (session === null) {
-          emit(s, { type: 'error', error: `Session "${id}" not found`, traceId: head.traceId });
-          continue;
-        }
+          let session = await deps.store.get(id);
+          if (session === null) {
+            emit(s, { type: 'error', error: `Session "${id}" not found`, traceId: head.traceId });
+            continue;
+          }
+
+          // A redo re-runs the existing committed user turn — no title derivation, no new user message.
+          if (head.redo === undefined) {
+            if (!session.title && !session.messages.some(m => m.role === 'user')) {
+              // Falls back to the attachment names when the turn has no words of its own: an image-only
+              // first turn is a real submission, and got no title at all — which reads in the session
+              // list as a session that failed to start.
+              const text = content
+                .filter((c): c is Extract<MessageContent, { type: 'text' }> => c.type === 'text')
+                .map(c => c.text).join(' ').trim()
+                || content
+                  .filter((c): c is Extract<MessageContent, { type: 'file-ref' }> => c.type === 'file-ref')
+                  .map(c => c.name).join(', ');
+              if (text) {
+                const words = text.split(/\s+/).slice(0, 8).join(' ');
+                session = { ...session, title: words.length > 60 ? `${words.slice(0, 60)}…` : words };
+              }
+            }
 
-        // A redo re-runs the existing committed user turn — no title derivation, no new user message.
-        if (head.redo === undefined) {
-          if (!session.title && !session.messages.some(m => m.role === 'user')) {
-            // Falls back to the attachment names when the turn has no words of its own: an image-only
-            // first turn is a real submission, and got no title at all — which reads in the session
-            // list as a session that failed to start.
-            const text = content
-              .filter((c): c is Extract<MessageContent, { type: 'text' }> => c.type === 'text')
-              .map(c => c.text).join(' ').trim()
-              || content
-                .filter((c): c is Extract<MessageContent, { type: 'file-ref' }> => c.type === 'file-ref')
-                .map(c => c.name).join(', ');
-            if (text) {
-              const words = text.split(/\s+/).slice(0, 8).join(' ');
-              session = { ...session, title: words.length > 60 ? `${words.slice(0, 60)}…` : words };
+            // Persist-at-turn-start: the user message only hits the store when its turn begins, never
+            // while queued. That is what stops a mid-turn submit from clobbering session state. A robo
+            // resubmission's blocks already carry `origin: 'robo'` (stamped where it was enqueued).
+            session = appendMessage(session, createMessage({ role: 'user', content, traceId: head.traceId, providerName: head.provider }));
+            try {
+              await deps.store.set(session.id, session);
+            } catch (e) {
+              // A read-only store rejects the persist-at-turn-start write (e.g. a session shared read-only
+              // from another profile's partition). That is a per-turn condition, not a host fault: surface
+              // it as a turn error and drop this submission rather than let it escape the detached pump and
+              // crash the process. Any other write failure stays fatal.
+              if (!isReadOnlyError(e)) throw e;
+              emit(s, { type: 'error', error: e.message, traceId: head.traceId });
+              continue;
             }
           }
 
-          // Persist-at-turn-start: the user message only hits the store when its turn begins, never
-          // while queued. That is what stops a mid-turn submit from clobbering session state. A robo
-          // resubmission's blocks already carry `origin: 'robo'` (stamped where it was enqueued).
-          session = appendMessage(session, createMessage({ role: 'user', content, traceId: head.traceId, providerName: head.provider }));
-          try {
-            await deps.store.set(session.id, session);
-          } catch (e) {
-            // A read-only store rejects the persist-at-turn-start write (e.g. a session shared read-only
-            // from another profile's partition). That is a per-turn condition, not a host fault: surface
-            // it as a turn error and drop this submission rather than let it escape the detached pump and
-            // crash the process. Any other write failure stays fatal.
-            if (!isReadOnlyError(e)) throw e;
-            emit(s, { type: 'error', error: e.message, traceId: head.traceId });
+          const resolved = await deps.resolveProvider(head.provider);
+          if (resolved === null) {
+            emit(s, { type: 'error', error: `Unknown provider "${head.provider}"`, traceId: head.traceId });
             continue;
           }
-        }
-
-        const resolved = await deps.resolveProvider(head.provider);
-        if (resolved === null) {
-          emit(s, { type: 'error', error: `Unknown provider "${head.provider}"`, traceId: head.traceId });
-          continue;
-        }
 
-        // A redo re-runs an existing turn with its ephemeral; a steer carries an interrupt's nudge. The
-        // two never coincide on one item, so either supplies runSession's injectedEphemeral.
-        const inject = head.redo?.ephemeral ?? head.injectEphemeral;
-
-        const ac = new AbortController();
-        s.ac = ac;
-        // Fold each tool's wire contract — the `params`/`result` text flattened from its single contract
-        // (a source tool's ToolContracts arms, or a source-less tool's `toolContract`) — into its description
-        // for this turn, so the model reasons about the real TS shapes, not just the loose inputSchema.
-        // Derived here because `services`/ToolTypeIndex are live at dispatch. Tools with only a loose
-        // inputSchema (no contract) are left as-is; absent ToolTypeIndex (browser) ⇒ plain descriptions.
-        const wire = await deps.toolTypeIndex?.()?.wireContracts();
-        const toolPresenter = deps.toolPresenter?.();
-        const mediaStore    = deps.mediaStore?.();
-        const permissionGate = deps.permissionGate?.();
-        const toolMap = deps.tools !== undefined
-          ? new Map<string, Tool>(deps.tools.list().map(t => {
-              const wc = wire?.[t.name];
-              return [t.name, wc !== undefined
-                ? { ...t, description: wireDescription(t.description, wc) }
-                : t];
-            }))
-          : undefined;
-
-        try {
-          // Establish the submitter's principal for the whole turn here, not inside runSession:
-          // pump runs detached (`void pump`), so this scope — not the request that enqueued — is the
-          // turn's async root. Everything downstream (hooks, tools, and any Store/FileStore/Vault
-          // access they trigger) reads it via currentPrincipal(). The consumption is inside the callback
-          // because the pump owns it, not because it must be: runAs rescopes a returned iterator itself.
-          // runAs, not a context switch of its own: the pump holds the machine across the whole queue
-          // (see above), so a turn declares only its owner. Each item carries its own submitter.
-          // The terminal event this turn ended on. `followup` is post-COMMIT, and only `done` is a
-          // commit: an `aborted` turn was cut short (a steer, a user cancel, a screen/toolcall hook
-          // refusing it, a provider round ceiling) and an `error` turn produced no response at all, so
-          // in both cases a followup hook would judge history with no completed answer in it — and a
-          // `resubmit` would undo the very stop that just happened, handing a round ceiling a fresh
-          // budget. Tracked here rather than inferred from `ac.signal`, which only knows about the two
-          // signal-driven aborts and not the policy ones.
-          let terminal: PipelineEvent['type'] | undefined;
-          // One usage scope per pump ITERATION rather than per turn. `followup` is post-commit by
-          // definition and a detached classifier settles whenever it settles, so a scope that ended at
-          // the turn's commit would drop precisely the spend that is hardest to account for otherwise.
-          // The entries array is registered for flush before any work starts, so a late arrival lands
-          // in something already tracked and needs no coordination of its own.
-          await withUsageScope(async usage => {
-          s.pendingUsage.push(usage.entries);
-          await runAs(head.principal, async () => {
-            for await (const ev of runSession({
-              session,
-              config:         { provider: head.provider, traceId: head.traceId },
-              provider:       resolved.adapter,
-              providerConfig: resolved.config,
-              store:          deps.store,
-              signal:         ac.signal,
-              loadPlugin:     deps.loadPlugin,
-              unloadPlugin:   deps.unloadPlugin,
-              ...(toolMap            !== undefined ? { tools:         toolMap            } : {}),
-              ...(deps.tools         !== undefined ? { toolRegistry:  deps.tools         } : {}),
-              ...(toolPresenter      !== undefined ? { toolPresenter                     } : {}),
-              ...(deps.hooks         !== undefined ? { hooks:         deps.hooks         } : {}),
-              ...(deps.systemContext !== undefined ? { systemContext: deps.systemContext } : {}),
-              ...(deps.workdir       !== undefined ? { workdir:       deps.workdir       } : {}),
-              ...(deps.files         !== undefined ? { files:         deps.files         } : {}),
-              ...(mediaStore         !== undefined ? { mediaStore                        } : {}),
-              ...(permissionGate     !== undefined ? { permissionGate                    } : {}),
-              ...(deps.configPath    !== undefined ? { configPath:    deps.configPath    } : {}),
-              ...(deps.vault         !== undefined ? { vault:         deps.vault         } : {}),
-              ...(head.prompt        !== undefined ? { prompt:        head.prompt        } : {}),
-              ...(inject             !== undefined ? { injectedEphemeral: inject } : {}),
-            })) {
-              if (ev.type === 'done' || ev.type === 'aborted' || ev.type === 'error') terminal = ev.type;
-              emit(s, ev);
-            }
-          });
+          // A redo re-runs an existing turn with its ephemeral; a steer carries an interrupt's nudge. The
+          // two never coincide on one item, so either supplies runSession's injectedEphemeral.
+          const inject = head.redo?.ephemeral ?? head.injectEphemeral;
+
+          const ac = new AbortController();
+          s.ac = ac;
+          // Fold each tool's wire contract — the `params`/`result` text flattened from its single contract
+          // (a source tool's ToolContracts arms, or a source-less tool's `toolContract`) — into its description
+          // for this turn, so the model reasons about the real TS shapes, not just the loose inputSchema.
+          // Derived here because `services`/ToolTypeIndex are live at dispatch. Tools with only a loose
+          // inputSchema (no contract) are left as-is; absent ToolTypeIndex (browser) ⇒ plain descriptions.
+          const wire = await deps.toolTypeIndex?.()?.wireContracts();
+          const toolPresenter = deps.toolPresenter?.();
+          const mediaStore    = deps.mediaStore?.();
+          const permissionGate = deps.permissionGate?.();
+          const toolMap = deps.tools !== undefined
+            ? new Map<string, Tool>(deps.tools.list().map(t => {
+                const wc = wire?.[t.name];
+                return [t.name, wc !== undefined
+                  ? { ...t, description: wireDescription(t.description, wc) }
+                  : t];
+              }))
+            : undefined;
 
-          // followup — post-commit, in the queue owner. A hook reads the just-committed turn and may
-          // head-enqueue a robo follow-up (its own real turn, running next). Runs only for a turn that
-          // committed (see `terminal`), and under the submitter's principal because a reactor may itself
-          // call complete() (a classifier).
-          const hooks = deps.hooks;
-          if (terminal === 'done' && hooks) {
-            const committed = await deps.store.get(id);
-            if (committed && head.resubmitDepth < MAX_RESUBMIT_DEPTH) {
-              let followup: { resubmits: MessageContent[][]; markers: MessageContent[]; retract?: { context: MessageContent[]; durable: MessageContent[] } } = { resubmits: [], markers: [] };
+          try {
+            // Establish the submitter's principal for the whole turn here, not inside runSession:
+            // pump runs detached (`void pump`), so this scope — not the request that enqueued — is the
+            // turn's async root. Everything downstream (hooks, tools, and any Store/FileStore/Vault
+            // access they trigger) reads it via currentPrincipal(). The consumption is inside the callback
+            // because the pump owns it, not because it must be: runAs rescopes a returned iterator itself.
+            // runAs, not a context switch of its own: the pump holds the machine across the whole queue
+            // (see above), so a turn declares only its owner. Each item carries its own submitter.
+            // The terminal event this turn ended on. `followup` is post-COMMIT, and only `done` is a
+            // commit: an `aborted` turn was cut short (a steer, a user cancel, a screen/toolcall hook
+            // refusing it, a provider round ceiling) and an `error` turn produced no response at all, so
+            // in both cases a followup hook would judge history with no completed answer in it — and a
+            // `resubmit` would undo the very stop that just happened, handing a round ceiling a fresh
+            // budget. Tracked here rather than inferred from `ac.signal`, which only knows about the two
+            // signal-driven aborts and not the policy ones.
+            let terminal: PipelineEvent['type'] | undefined;
+            // One usage scope per pump ITERATION rather than per turn. `followup` is post-commit by
+            // definition and a detached classifier settles whenever it settles, so a scope that ended at
+            // the turn's commit would drop precisely the spend that is hardest to account for otherwise.
+            // The entries array is registered for flush before any work starts, so a late arrival lands
+            // in something already tracked and needs no coordination of its own.
+            await withUsageScope(async usage => {
+              s.pendingUsage.push(usage.entries);
               await runAs(head.principal, async () => {
-                followup = await hooks.runFollowup({
-                  session:       committed,
-                  resubmitDepth: head.resubmitDepth,
-                  config:        { provider: head.provider, traceId: head.traceId },
-                  signal:        ac.signal,
-                  ...(head.prompt !== undefined ? { prompt: head.prompt } : {}),
-                });
+                for await (const ev of runSession({
+                  session,
+                  config:         { provider: head.provider, traceId: head.traceId },
+                  provider:       resolved.adapter,
+                  providerConfig: resolved.config,
+                  store:          deps.store,
+                  signal:         ac.signal,
+                  loadPlugin:     deps.loadPlugin,
+                  unloadPlugin:   deps.unloadPlugin,
+                  ...(toolMap            !== undefined ? { tools:         toolMap            } : {}),
+                  ...(deps.tools         !== undefined ? { toolRegistry:  deps.tools         } : {}),
+                  ...(toolPresenter      !== undefined ? { toolPresenter                     } : {}),
+                  ...(deps.hooks         !== undefined ? { hooks:         deps.hooks         } : {}),
+                  ...(deps.systemContext !== undefined ? { systemContext: deps.systemContext } : {}),
+                  ...(deps.workdir       !== undefined ? { workdir:       deps.workdir       } : {}),
+                  ...(deps.files         !== undefined ? { files:         deps.files         } : {}),
+                  ...(mediaStore         !== undefined ? { mediaStore                        } : {}),
+                  ...(permissionGate     !== undefined ? { permissionGate                    } : {}),
+                  ...(deps.configPath    !== undefined ? { configPath:    deps.configPath    } : {}),
+                  ...(deps.vault         !== undefined ? { vault:         deps.vault         } : {}),
+                  ...(head.prompt        !== undefined ? { prompt:        head.prompt        } : {}),
+                  ...(inject             !== undefined ? { injectedEphemeral: inject } : {}),
+                })) {
+                  if (ev.type === 'done' || ev.type === 'aborted' || ev.type === 'error') terminal = ev.type;
+                  emit(s, ev);
+                }
               });
-              const resubmits = followup.resubmits;
-
-              // Durable markers a followup hook returned (e.g. a fired trigger's silent tool tracing
-              // what it did). Append-only to the just-committed session; the pump is the sole writer
-              // post-commit, so an unconditional set is safe. Emitted live too (post-`done`, like a
-              // `queued` event) so a live draw matches a reload — the engine surfaces everything it
-              // persists; a frontend filters if it wants to. Skipped when retracting: the pop rewrites
-              // the message tail, so these markers are folded into that single write instead (below)
-              // to keep ordering sane (a separate append here would be sliced into the popped region).
-              if (followup.markers.length > 0 && !followup.retract) {
-                await deps.store.set(id, {
-                  ...committed,
-                  messages: [...committed.messages, {
-                    id:        crypto.randomUUID(),
-                    role:      'marker',
-                    createdAt: new Date().toISOString(),
-                    traceId:   head.traceId,
-                    content:   followup.markers,
-                  }],
-                });
-                notify(s, { type: 'marker', content: followup.markers, traceId: head.traceId });
-              }
-              // unshift in reverse so the hooks' order is preserved at the head of the queue. Stamp
-              // every block `origin: 'robo'` here — once — so it rides into both the live `queued`
-              // event and the persisted user message the pump builds from this item.
-              for (const raw of resubmits.reverse()) {
-                const rt = crypto.randomUUID();
-                // Every block, not just text: `origin` is authorship, orthogonal to what the block
-                // carries, and a resubmission that attached an image was silently presenting it as the
-                // user's own. The arms a stamp would be wrong on don't occur here — a hook returns
-                // content, not a thinking block — so a blanket stamp beats an arm-by-arm list.
-                const content = raw.map(c => ({ ...c, origin: 'robo' as const }));
-                s.queue.unshift({
-                  traceId:       rt,
-                  rootTraceId:   head.rootTraceId,
-                  content,
-                  provider:      head.provider,
-                  principal:     head.principal,
-                  concatQueue:   false,
-                  resubmitDepth: head.resubmitDepth + 1,
-                });
-                notify(s, { type: 'queued', content, queued: 0, concatQueue: false, traceId: rt, rootTraceId: head.rootTraceId });
-              }
 
-              // retract-and-rerun: pop the just-committed turn back to (and excluding) the last user
-              // message, stash the popped messages in a durable retraction marker (LLM-elided like any
-              // marker — so the model never re-reads its superseded answer — but carried in `data` for
-              // a strike-through render and audit), then re-enqueue a redo of that same user turn at the
-              // head, delivering the trigger tool's output as ephemeral context. Unshifted last so it
-              // sits at the very head (runs next) even if a resubmit was also queued above.
-              if (followup.retract) {
-                const lastUserIdx = lastUserIndex(committed);
-                const popped = lastUserIdx >= 0 ? committed.messages.slice(lastUserIdx + 1) : [];
-                // `durable` correction (a contextual fire that landed post-commit) folds onto the user
-                // message we keep — persisted, so the redo AND every later turn see it in history, the
-                // exact durability the clean in-situ path gives. `context` stays ephemeral (redo only).
-                // The fold runs on the *truncated* session, whose last user message is the one we keep,
-                // so it goes through the same helper as the screen and raced-verdict folds.
-                const durable = followup.retract.durable ?? [];
-                const truncated = lastUserIdx >= 0
-                  ? { ...committed, messages: committed.messages.slice(0, lastUserIdx + 1) }
-                  : committed;
-                const kept = foldOntoUserTurn(truncated, durable).messages;
-                const retractionMsg: Message = {
-                  id:        crypto.randomUUID(),
-                  role:      'marker',
-                  createdAt: new Date().toISOString(),
-                  traceId:   head.traceId,
-                  // `retracted` is what was popped (the superseded answer); `injected` is the ephemeral
-                  // context fed to the redo — neither is otherwise persisted, so the pair fully traces
-                  // the swap for a post-mortem (and a frontend can render the strike-through + the cause).
-                  content:   [{ type: 'marker', creator: RETRACTION_CREATOR, data: { retracted: popped, injected: followup.retract.context ?? [], traceId: head.traceId } }],
-                };
-                // Any followup markers ride along as a trailing marker message (not folded into the
-                // retraction marker) so each creator's trace stays its own block.
-                const trailing: Message[] = followup.markers.length > 0
-                  ? [{ id: crypto.randomUUID(), role: 'marker', createdAt: new Date().toISOString(), traceId: head.traceId, content: followup.markers }]
-                  : [];
-                await deps.store.set(id, { ...committed, messages: [...kept, retractionMsg, ...trailing] });
-                // Emit the durable fold live (as a robo-user on the kept user turn) before the retraction
-                // marker, mirroring the screen-time durable path's ordering.
-                if (durable.length > 0) notify(s, { type: 'robo-user', content: durable, traceId: head.traceId });
-                notify(s, { type: 'marker', content: retractionMsg.content, traceId: head.traceId });
-                if (trailing.length > 0) notify(s, { type: 'marker', content: followup.markers, traceId: head.traceId });
-
-                const rt = crypto.randomUUID();
-                s.queue.unshift({
-                  traceId:       rt,
-                  rootTraceId:   head.rootTraceId,
-                  content:       [],
-                  provider:      head.provider,
-                  principal:     head.principal,
-                  concatQueue:   false,
-                  resubmitDepth: head.resubmitDepth + 1,
-                  redo:          { ephemeral: followup.retract.context ?? [] },
-                  ...(head.prompt !== undefined ? { prompt: head.prompt } : {}),
-                });
+              // followup — post-commit, in the queue owner. A hook reads the just-committed turn and may
+              // head-enqueue a robo follow-up (its own real turn, running next). Runs only for a turn that
+              // committed (see `terminal`), and under the submitter's principal because a reactor may itself
+              // call complete() (a classifier).
+              const hooks = deps.hooks;
+              if (terminal === 'done' && hooks) {
+                const committed = await deps.store.get(id);
+                if (committed && head.resubmitDepth < MAX_RESUBMIT_DEPTH) {
+                  let followup: { resubmits: MessageContent[][]; markers: MessageContent[]; retract?: { context: MessageContent[]; durable: MessageContent[] } } = { resubmits: [], markers: [] };
+                  await runAs(head.principal, async () => {
+                    followup = await hooks.runFollowup({
+                      session:       committed,
+                      resubmitDepth: head.resubmitDepth,
+                      config:        { provider: head.provider, traceId: head.traceId },
+                      signal:        ac.signal,
+                      ...(head.prompt !== undefined ? { prompt: head.prompt } : {}),
+                    });
+                  });
+                  const resubmits = followup.resubmits;
+
+                  // Durable markers a followup hook returned (e.g. a fired trigger's silent tool tracing
+                  // what it did). Append-only to the just-committed session; the pump is the sole writer
+                  // post-commit, so an unconditional set is safe. Emitted live too (post-`done`, like a
+                  // `queued` event) so a live draw matches a reload — the engine surfaces everything it
+                  // persists; a frontend filters if it wants to. Skipped when retracting: the pop rewrites
+                  // the message tail, so these markers are folded into that single write instead (below)
+                  // to keep ordering sane (a separate append here would be sliced into the popped region).
+                  if (followup.markers.length > 0 && !followup.retract) {
+                    await deps.store.set(id, {
+                      ...committed,
+                      messages: [...committed.messages,
+                        createMessage({ role: 'marker', content: followup.markers, traceId: head.traceId })],
+                    });
+                    notify(s, { type: 'marker', content: followup.markers, traceId: head.traceId });
+                  }
+                  // unshift in reverse so the hooks' order is preserved at the head of the queue. Stamp
+                  // every block `origin: 'robo'` here — once — so it rides into both the live `queued`
+                  // event and the persisted user message the pump builds from this item.
+                  for (const raw of resubmits.reverse()) {
+                    const rt = crypto.randomUUID();
+                    // Every block, not just text: `origin` is authorship, orthogonal to what the block
+                    // carries, and a resubmission that attached an image was silently presenting it as the
+                    // user's own. The arms a stamp would be wrong on don't occur here — a hook returns
+                    // content, not a thinking block — so a blanket stamp beats an arm-by-arm list.
+                    const content = raw.map(c => ({ ...c, origin: 'robo' as const }));
+                    s.queue.unshift({
+                      traceId:       rt,
+                      rootTraceId:   head.rootTraceId,
+                      content,
+                      provider:      head.provider,
+                      principal:     head.principal,
+                      concatQueue:   false,
+                      resubmitDepth: head.resubmitDepth + 1,
+                    });
+                    notify(s, { type: 'queued', content, queued: 0, concatQueue: false, traceId: rt, rootTraceId: head.rootTraceId });
+                  }
+
+                  // retract-and-rerun: pop the just-committed turn back to (and excluding) the last user
+                  // message, stash the popped messages in a durable retraction marker (LLM-elided like any
+                  // marker — so the model never re-reads its superseded answer — but carried in `data` for
+                  // a strike-through render and audit), then re-enqueue a redo of that same user turn at the
+                  // head, delivering the trigger tool's output as ephemeral context. Unshifted last so it
+                  // sits at the very head (runs next) even if a resubmit was also queued above.
+                  if (followup.retract) {
+                    const lastUserIdx = lastUserIndex(committed);
+                    const popped = lastUserIdx >= 0 ? committed.messages.slice(lastUserIdx + 1) : [];
+                    // `durable` correction (a contextual fire that landed post-commit) folds onto the user
+                    // message we keep — persisted, so the redo AND every later turn see it in history, the
+                    // exact durability the clean in-situ path gives. `context` stays ephemeral (redo only).
+                    // The fold runs on the *truncated* session, whose last user message is the one we keep,
+                    // so it goes through the same helper as the screen and raced-verdict folds.
+                    const durable = followup.retract.durable ?? [];
+                    const truncated = lastUserIdx >= 0
+                      ? { ...committed, messages: committed.messages.slice(0, lastUserIdx + 1) }
+                      : committed;
+                    const kept = foldOntoUserTurn(truncated, durable).messages;
+                    const retractionMsg: Message = createMessage({
+                      role:    'marker',
+                      traceId: head.traceId,
+                      // `retracted` is what was popped (the superseded answer); `injected` is the ephemeral
+                      // context fed to the redo — neither is otherwise persisted, so the pair fully traces
+                      // the swap for a post-mortem (and a frontend can render the strike-through + the cause).
+                      content: [{ type: 'marker', creator: RETRACTION_CREATOR, data: { retracted: popped, injected: followup.retract.context ?? [], traceId: head.traceId } }],
+                    });
+                    // Any followup markers ride along as a trailing marker message (not folded into the
+                    // retraction marker) so each creator's trace stays its own block.
+                    const trailing: Message[] = followup.markers.length > 0
+                      ? [createMessage({ role: 'marker', content: followup.markers, traceId: head.traceId })]
+                      : [];
+                    await deps.store.set(id, { ...committed, messages: [...kept, retractionMsg, ...trailing] });
+                    // Emit the durable fold live (as a robo-user on the kept user turn) before the retraction
+                    // marker, mirroring the screen-time durable path's ordering.
+                    if (durable.length > 0) notify(s, { type: 'robo-user', content: durable, traceId: head.traceId });
+                    notify(s, { type: 'marker', content: retractionMsg.content, traceId: head.traceId });
+                    if (trailing.length > 0) notify(s, { type: 'marker', content: followup.markers, traceId: head.traceId });
+
+                    const rt = crypto.randomUUID();
+                    s.queue.unshift({
+                      traceId:       rt,
+                      rootTraceId:   head.rootTraceId,
+                      content:       [],
+                      provider:      head.provider,
+                      principal:     head.principal,
+                      concatQueue:   false,
+                      resubmitDepth: head.resubmitDepth + 1,
+                      redo:          { ephemeral: followup.retract.context ?? [] },
+                      ...(head.prompt !== undefined ? { prompt: head.prompt } : {}),
+                    });
+                  }
+                }
               }
-            }
+            }, { traceId: head.traceId, rootTraceId: head.rootTraceId });
+          } catch (e) {
+            emit(s, { type: 'error', error: String(e), traceId: head.traceId });
+          } finally {
+            s.ac = undefined;
           }
-          }, { traceId: head.traceId, rootTraceId: head.rootTraceId });
-        } catch (e) {
-          emit(s, { type: 'error', error: String(e), traceId: head.traceId });
-        } finally {
-          s.ac = undefined;
         }
+      } finally {
+        s.running = false;
+        s.runningTraceId = undefined;
+        s.replay  = [];
+        // Accounting is flushed HERE — at the drained queue, not at a turn boundary. "The end of a turn"
+        // is not a well-defined moment to total anything at: steers terminate and resume, a retract
+        // re-enqueues the turn it just popped, followup enqueues resubmissions, and a detached classifier
+        // settles whenever it settles. The queue draining is unambiguous, and it is after all of them.
+        await flushUsage(id, s);
+        // Deterministic busy→idle signal: running is now false, so any subscriber draining the stream
+        // (a frontend's status tracker) reads an authoritative idle the moment it sees this — no racing
+        // the microtask on which `running` flipped. Not in `replay` (transient lifecycle, not history).
+        notify(s, { type: 'idle', sessionId: id });
+        maybeCleanup(id, s);
       }
-    } finally {
-      s.running = false;
-      s.runningTraceId = undefined;
-      s.replay  = [];
-      // Accounting is flushed HERE — at the drained queue, not at a turn boundary. "The end of a turn"
-      // is not a well-defined moment to total anything at: steers terminate and resume, a retract
-      // re-enqueues the turn it just popped, followup enqueues resubmissions, and a detached classifier
-      // settles whenever it settles. The queue draining is unambiguous, and it is after all of them.
-      await flushUsage(id, s);
-      // Deterministic busy→idle signal: running is now false, so any subscriber draining the stream
-      // (a frontend's status tracker) reads an authoritative idle the moment it sees this — no racing
-      // the microtask on which `running` flipped. Not in `replay` (transient lifecycle, not history).
-      notify(s, { type: 'idle', sessionId: id });
-      maybeCleanup(id, s);
-    }
     });
   };
 

package/src/session.ts

@@ -1,4 +1,8 @@
-import type { Session, Message, MessageContent, MessageRole } from './types.js';
+import type { Session, Message } from './types.js';
+
+// `createMessage` lives in plugin-api, where the hook registry can also reach it (core is downstream of
+// that package). Re-exported here so it stays where every consumer already imports it from.
+export { createMessage } from '@matatbread/matbot-plugin-api';
 
 export interface CreateSessionOpts {
   title?:                string;
@@ -32,20 +36,3 @@ export function appendMessage(session: Session, message: Message): Session {
   };
 }
 
-export function createMessage(opts: {
-  role:           MessageRole;
-  content:        MessageContent[];
-  traceId:        string;
-  providerName?:  string;
-  metadata?:      Record<string, unknown>;
-}): Message {
-  return {
-    id:        crypto.randomUUID(),
-    role:      opts.role,
-    content:   opts.content,
-    createdAt: new Date().toISOString(),
-    traceId:   opts.traceId,
-    ...(opts.providerName !== undefined ? { providerName: opts.providerName } : {}),
-    ...(opts.metadata     !== undefined ? { metadata:     opts.metadata     } : {}),
-  };
-}

package/src/settings.ts

@@ -70,6 +70,9 @@ export function settingsDefaultNamespaces(): readonly string[] {
  *  consumer filters `kind === ItemChangeKind && namespace === SETTINGS_NAMESPACE && id === slug(mine)`. */
 export const SETTINGS_NAMESPACE = 'settings';
 
+/** How many times a settings write re-reads and re-compares before giving up. See `update` below. */
+const SETTINGS_CAS_ATTEMPTS = 8;
+
 /**
  * The bus settings writes announce on, installed by the host at boot alongside {@link installSettingsDefaults}.
  *
@@ -134,8 +137,14 @@ export function makePluginSettings(rawStore: Store<SettingsDoc>, namespace: stri
 
   // One CAS retry loop for both writers: read, apply `mutate`, write. A document that vanished between
   // read and write (or never existed) is a plain `set`; otherwise `cas` guards the version we read.
+  //
+  // Bounded, because the loop cannot tell a lost race from a `cas` that will never succeed: a backend
+  // whose compare always fails (a version it does not mint, a medium generation it cannot reconcile)
+  // turned this into a hot spin with no error and no exit. A settings namespace is one document with few
+  // writers, so real contention resolves in one or two passes; exhausting the budget is a fault to
+  // report, not a state to keep retrying.
   const update = async (mutate: (data: Record<string, unknown>) => Record<string, unknown> | undefined): Promise<void> => {
-    for (;;) {
+    for (let attempt = 1; ; attempt++) {
       const doc  = await getDoc();
       const data = mutate(doc?.data ?? {});
       if (data === undefined) return;
@@ -143,6 +152,13 @@ export function makePluginSettings(rawStore: Store<SettingsDoc>, namespace: stri
       if (doc === null) { await store.set(id, next); return; }
       const r = await store.cas(id, doc.version, next);
       if (r.ok) return;
+      if (attempt >= SETTINGS_CAS_ATTEMPTS) {
+        throw new Error(
+          `Settings for "${namespace}" could not be written: ${SETTINGS_CAS_ATTEMPTS} compare-and-swap ` +
+          'attempts all lost. Either something is writing this namespace continuously, or the storage ' +
+          'backend is rejecting every compare.',
+        );
+      }
     }
   };