stitchkit 0.96.0 → 0.97.0

package/dist/entrypoints/telegram.js

@@ -636,6 +636,17 @@ function createTelegramLocalFiles(config) {
 }
 // src/telegram/operator-channel.ts
 var TEXT_LIMIT = 4096;
+var MASK = "[redacted]";
+function masked(text, patterns) {
+  let output = text;
+  for (const pattern of patterns) {
+    output = output.replace(new RegExp(pattern.source, `${pattern.flags.replace(/[gy]/g, "")}g`), MASK);
+  }
+  return output;
+}
+function literal(value) {
+  return new RegExp(value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+}
 function timer(milliseconds, signal) {
   return new Promise((resolve2, reject) => {
     if (signal.aborted)
@@ -660,6 +671,7 @@ function createTelegramOperatorChannel(config) {
   const minIntervalMs = config.minIntervalMs ?? 3000;
   const maxAttempts = config.maxAttempts ?? 3;
   const sleep = config.sleep ?? timer;
+  const patterns = [TELEGRAM_BOT_TOKEN_PATTERN, ...config.sensitivePatterns ?? []];
   const queue = [];
   const idle = new Set;
   let lifetime = new AbortController;
@@ -740,7 +752,7 @@ function createTelegramOperatorChannel(config) {
       try {
         const item = {
           ...topic !== undefined && { topic },
-          text,
+          text: masked(text, patterns),
           attempts: 0
         };
         if (closed) {
@@ -786,12 +798,13 @@ function createTelegramOperatorChannel(config) {
   };
 }
 function telegramOperatorSender(config) {
+  const token = literal(config.token);
   return (message, signal) => callTelegramBotApi({
     token: config.token,
     method: "sendMessage",
     params: {
       chat_id: message.chatId,
-      text: message.text,
+      text: masked(message.text, [token]),
       ...message.threadId !== undefined && { message_thread_id: message.threadId },
       ...config.parseMode && { parse_mode: config.parseMode },
       link_preview_options: { is_disabled: true }

package/dist/{index-p9e0w8hs.js → index-1m2thnq0.js}

@@ -337,10 +337,25 @@ function migrateAgentRuntimeSqliteV2ToV3(database) {
   database.prepare("UPDATE stitchkit_agent_runtime_meta SET value = '3' WHERE key = 'schema_version'").run();
 }
 
+// src/agent-runtime/store-migrations/v3-to-v4.ts
+function migrateAgentRuntimeSqliteV3ToV4(database) {
+  database.exec(`
+    ALTER TABLE stitchkit_agent_runtime_schedules ADD COLUMN retry_at TEXT;
+    ALTER TABLE stitchkit_agent_runtime_schedules ADD COLUMN attempts INTEGER NOT NULL DEFAULT 0;
+    ALTER TABLE stitchkit_agent_runtime_schedules ADD COLUMN last_error TEXT;
+    ALTER TABLE stitchkit_agent_runtime_schedules ADD COLUMN eligible_at TEXT
+      GENERATED ALWAYS AS (MAX(next_at, COALESCE(retry_at, next_at), COALESCE(claim_until, next_at))) VIRTUAL;
+    DROP INDEX stitchkit_agent_runtime_schedules_due;
+    CREATE INDEX stitchkit_agent_runtime_schedules_due
+      ON stitchkit_agent_runtime_schedules (eligible_at, id) WHERE state = 'scheduled';
+    UPDATE stitchkit_agent_runtime_meta SET value = '4' WHERE key = 'schema_version';
+  `);
+}
+
 // src/agent-runtime/sqlite-schema.ts
 var MetaRowSchema = z3.object({ value: z3.string() });
 var TableRowSchema = z3.object({ name: z3.string() });
-var SCHEMA_VERSION = 3;
+var SCHEMA_VERSION = 4;
 var TABLES = [
   "stitchkit_agent_runtime_heads",
   "stitchkit_agent_runtime_runs",
@@ -373,12 +388,20 @@ function initializeAgentRuntimeSqlite(database) {
       if (version === 1) {
         migrateAgentRuntimeSqliteV1ToV2(database);
         migrateAgentRuntimeSqliteV2ToV3(database);
+        migrateAgentRuntimeSqliteV3ToV4(database);
         initializeSqliteConversationPurge(database);
         database.exec("COMMIT");
         return;
       }
       if (version === 2) {
         migrateAgentRuntimeSqliteV2ToV3(database);
+        migrateAgentRuntimeSqliteV3ToV4(database);
+        initializeSqliteConversationPurge(database);
+        database.exec("COMMIT");
+        return;
+      }
+      if (version === 3) {
+        migrateAgentRuntimeSqliteV3ToV4(database);
         initializeSqliteConversationPurge(database);
         database.exec("COMMIT");
         return;
@@ -437,6 +460,7 @@ function initializeAgentRuntimeSqlite(database) {
     createAgentRuntimeSqliteV2Tables(database);
     createAgentRuntimeSqliteV3Tables(database);
     database.prepare("INSERT INTO stitchkit_agent_runtime_meta (key, value) VALUES ('schema_version', '3')").run();
+    migrateAgentRuntimeSqliteV3ToV4(database);
     initializeSqliteConversationPurge(database);
     database.exec("COMMIT");
   } catch (error) {

package/dist/telegram/operator-channel.d.ts

@@ -48,6 +48,12 @@ export interface TelegramOperatorChannelConfig<TTopic extends string> {
     readonly onDropped?: (drop: TelegramOperatorDrop<TTopic>) => void;
     /** Default: a timer. Rejects when `signal` aborts. */
     readonly sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+    /**
+     * More secrets to mask in every message before it leaves. A bot token is
+     * always masked: bots post their errors here, and an error about a local Bot
+     * API file carries `<root>/<token>/…` in its path.
+     */
+    readonly sensitivePatterns?: readonly RegExp[];
 }
 export interface TelegramOperatorChannel<TTopic extends string> {
     /** Queue one message. Returns at once and never throws. */

package/dist/telegram/operator-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operator-channel.d.ts","sourceRoot":"","sources":["../../src/telegram/operator-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAA+B,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAEvF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAK7C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB,CAAC,MAAM,SAAS,MAAM;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED,MAAM,WAAW,6BAA6B,CAAC,MAAM,SAAS,MAAM;IAClE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5D,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,uBAAuB,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3F,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAClE,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,uBAAuB,CAAC,MAAM,SAAS,MAAM;IAC5D,2DAA2D;IAC3D,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,kFAAkF;IAClF,KAAK,IAAI,IAAI,CAAC;CACf;AA4BD,wBAAgB,6BAA6B,CAAC,MAAM,SAAS,MAAM,GAAG,KAAK,EACzE,MAAM,EAAE,6BAA6B,CAAC,MAAM,CAAC,GAC5C,uBAAuB,CAAC,MAAM,CAAC,CA8IjC;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CAC/B;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,6BAA6B,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAgB/C"}
+{"version":3,"file":"operator-channel.d.ts","sourceRoot":"","sources":["../../src/telegram/operator-channel.ts"],"names":[],"mappings":"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"}

package/llms/agent-runtime.2.txt

@@ -13,6 +13,230 @@ Parts of this slice:
 # Guide: Agent application runtime  (docs/guide/agent-runtime.md)  (continued)
 ==============================================================================
 
+## What happens to a run when new input arrives
+
+`runs.inputPolicy` decides. It takes five values, or a function returning one:
+
+| policy | the run in flight | what it already produced |
+|--------|-------------------|--------------------------|
+| `queue` (default) | finishes first | kept |
+| `inject` | continues, and answers the new input too | kept, and built on |
+| `interrupt` | ends | kept, and marked as cut off |
+| `interrupt-next` | ends; this input runs before ordinary queued work | kept, and marked as cut off |
+| `supersede` | ends | discarded from the prompt, kept in the record |
+
+`interrupt-next` is the explicit priority path for an urgent input. If A is
+running, ordinary B is queued, and urgent C arrives, the coordinator aborts A,
+waits for A to settle and then runs C before B. B keeps its durable identity and
+eventually runs. Urgent inputs remain FIFO among themselves. They do not
+coalesce into an ordinary pending run: that would erase the priority boundary.
+
+`interrupt` and `supersede` differ in exactly one thing, and the question that
+picks between them is **not** "was the run interrupted" but **"did anyone see
+what it produced"**:
+
+- The user pressed **stop**. The partial answer was streamed to their screen and
+  they read it. It belongs in the conversation — dropping it makes the history
+  lie to the model about what the human has seen. That is `interrupt`.
+- A newer message **superseded** the run. Whether the partial reached anyone
+  depends on the delivery surface: a token stream shows it as it is produced, a
+  surface that sends nothing until the run is done never showed it at all. When
+  it reached nobody, it is not part of the conversation. That is `supersede`.
+
+**Stitchkit cannot answer that question for you** — delivery belongs to the
+transport, and the runtime sees an abort, not a screen. Hence a declared policy
+(→ ADR 0108), and hence `inputPolicy` accepting a function, so one application
+can hold two surfaces with different rules without the core learning which is
+which:
+
+```ts
+runs: {
+  inputPolicy: (input) =>
+    protocol.parseContext(input.context).surface === 'operator' ? 'queue' : 'supersede',
+}
+```
+
+`input.context` is the **raw** context here — admission runs before the runtime
+parses it, so the callback narrows it itself with the protocol it already has.
+
+A superseded run ends with `terminalReason: 'superseded'`, run state
+`'superseded'` and an assistant message of status `'superseded'`. **The record
+is kept** — excluded from the projection, not deleted — so an operator can see
+what was thrown away, and run identity, admission receipts and the terminal CAS
+keep the row they depend on. Compaction leaves it alone for the same reason: a
+turn whose answer is never spoken is not a turn that may be summarised into one,
+because that would both feed the discarded text to the summariser and drop the
+record in `replacedMessageIds`.
+
+It is also outside the token budget. `selectAgentHistory` removes it with reason
+`'superseded'` and does not count it, so an abandoned fragment cannot push a
+real turn out of a context it never occupies.
+
+### How an interrupted turn reaches the model
+
+An interrupted turn is projected, and says so:
+
+```text
+{ role: 'assistant', content: [
+    { type: 'text', text: 'We are the team, where would you like' },
+    { type: 'text', text: '[interrupted: this turn was cut off before it finished]' },
+]}
+```
+
+`history.interruptedAssistant` chooses the form, and the difference between the
+first two is structural rather than cosmetic. **An assistant turn in provider
+history is a commitment**: the model reads its own previous turn as something it
+said and stays consistent with it. A system line is context.
+
+| value | form | right when |
+|-------|------|-----------|
+| `assistant-marked` (default) | assistant turn plus a marker | the human read the text |
+| `system-note` | `[interrupted] partial response: …` as a system line | the fragment reached nobody |
+| `omit` | not projected at all | you want it gone from the request |
+
+There is deliberately no value that reproduces what the projection used to do,
+which was to send the partial as an ordinary assistant turn and drop its
+`control` marker on the way. That was the defect, not a behaviour to stay
+compatible with.
+
+`projectAgentHistoryDetailed` reports what reached the provider, including part
+types that no projected content stands for:
+
+```ts
+const { decisions } = await projectAgentHistoryDetailed(snapshot.messages)
+// → { messageId: 'assistant-2', action: 'projected', reason: 'projected',
+//      omittedParts: ['source', 'provider'] }
+// → { messageId: 'assistant-1', action: 'omitted', reason: 'superseded' }
+```
+
+`runtime.stop(key, 'supersede')` is the same decision taken by hand: the
+process-local escape hatch chooses the reason, so a caller that knows the answer
+was never delivered can discard it without a newer input arriving.
+
+### An input that joins a run in flight
+
+`inject` is right when the new input **refines** rather than redirects, and the
+steps already taken are still worth something: *"summarise this thread… actually,
+in bullet points"* should not throw away the reading the first message paid for.
+
+What happens:
+
+1. The input is admitted exactly like any other — a committed user message and a
+   **queued run**, durable before anything else happens.
+2. At the running loop's next step boundary, that input joins its prompt. Only
+   that input: an unrelated queued submission is never carried in.
+3. When the run finishes, its terminal commit — **one transaction** — records
+   the input as one the run answered and settles the queued successor with
+   `terminalReason: 'absorbed'` and `absorbedIntoRunId` naming the run that
+   answered it. Every ticket for that successor resolves to the same answer.
+
+Nothing durable happens between 1 and 3, and that is the design (→ ADR 0113).
+A run that crashes, is closed, or is interrupted after taking an input on
+commits no absorption at all, so what is left behind is an ordinary queued
+successor — the state every other policy already produces and recovery already
+handles. **There is no ordering in which an accepted input becomes
+unanswerable.** Only a run that *completes* may absorb; an interrupted one took
+the input into its prompt and then stopped, and does not get to say it answered
+it.
+
+An absorbed run has **no assistant message of its own** — it produced none, and
+writing an empty one would be a record claiming otherwise. Its answer is
+reachable through `absorbedIntoRunId`, and the store follows that pointer itself
+when a submission arrives on the absorbed run's idempotency key, so a retry
+after a restart returns the answer rather than an empty terminal record.
+
+It does publish one more `run-state` event, carrying `'superseded'`. It never
+enters the run executor, so that event is the only thing that tells a delivery
+surface following its `runId` that it is no longer queued.
+
+With `coalescePending`, one successor can carry several inputs, and an
+absorption covers a successor **whole or not at all** — a partial one would
+leave a terminal run with inputs nobody answered. Inputs that coalesce before
+the absorbing run's last step boundary join the same absorption. One that
+arrives after it cancels the absorption: the successor then answers all of its
+inputs itself, and the absorbing run has answered one of them too. A duplicate
+answer, never a missing one.
+
+(0.63.0 shipped a version of this that committed the absorption at the step
+boundary, before the answer existed, and it was withdrawn in 0.65.0. ADR 0113
+records what that ordering broke.)
+
+With `runs.coalescePending: true`, an active lane has at most one queued
+successor. Every later accepted input is atomically appended to that successor;
+its `AgentRun.inputMessageIds` records the whole batch and every input ticket
+resolves to the same terminal run. Coalescing never mutates the active run.
+
+`AbortSignal.aborted` is only a cooperation request. A successor does not begin
+while the predecessor still owns managed callbacks. A hung predecessor blocks
+the lane in the first version.
+
+Shutdown is two-phase, and both budgets carry the names they carry everywhere
+else in Stitchkit:
+
+```ts
+const closed = await runtime.close({ gracePeriodMs: 30_000, forceTimeoutMs: 5_000 })
+if (!closed.settled) {
+  console.warn(`exiting with ${closed.remaining} run(s) still in flight`)
+}
+```
+
+`close` first rejects new process-local admissions and gives active runs
+`gracePeriodMs` to finish on their own. Only after that budget expires does it
+abort them with reason `shutdown`; `forceTimeoutMs` then bounds the settlement
+wait for a non-cooperative model or tool, measured from the abort — the two
+budgets add up rather than overlapping.
+
+**`close()` reports what it achieved rather than promising an outcome it cannot
+reach.** The result is `{ settled, timedOut, remaining }`: `settled` when every
+in-flight run finished, `timedOut` with a `remaining` count when the force
+budget expired first. There is no combination of budgets that is both bounded
+and guaranteed to leave nothing in flight — that is the trade the budgets exist
+to make, and the result is where you read which side of it you got:
+
+| budgets | behaviour | can return with a run in flight |
+|---------|-----------|---------------------------------|
+| neither | aborts immediately, waits for settlement | no — unbounded wait |
+| `gracePeriodMs` only | waits, aborts, then waits for settlement | no — unbounded wait |
+| `forceTimeoutMs` only | aborts immediately, waits at most that long | **yes** — `timedOut` |
+| both | waits, aborts, waits at most that long | **yes** — `timedOut` |
+
+A caller that wants the old shape still writes `await runtime.close(…)` and
+ignores the result. A caller deciding whether to exit the process reads it.
+Durably queued records rejected from the local queue remain recoverable through
+`scanRecoverable`; close never marks them terminal on its own.
+
+Use `await runtime.interrupt({ conversationId, runId })` when the interruption
+must be durable: it first commits `interrupt_requested`, then aborts the local
+coordinator signal. If provider completion races that revision change, the terminal path reloads
+the canonical snapshot. An already-terminal winner settles the ticket directly; a still-owned
+`interrupt_requested` run is committed as `interrupted`, and unrelated aggregate-head conflicts
+remain retriable while the run is active with the same owner and fencing token. A stale owner or
+fencing token remains a conflict. Only the execution that applies the terminal mutation publishes the
+**delivery** `terminal` event — a loser settles from canonical state without republishing the turn,
+and its `AgentRuntimeResult.metrics` is `undefined`. The **operator** `run-terminal` event is not
+gated that way: a losing execution still ran, and still spent whatever it spent, so it reports its
+own usage. The two channels answer to different readers — delivering a turn twice is a user's
+problem, and omitting a run's cost is an operator's.
+`runtime.stop(key)` is the process-local signal-only escape hatch.
+
+When an operator has positive evidence that another process owning one known
+run is gone, close that run through the runtime boundary rather than updating
+an adapter table or JSON payload directly:
+
+```ts
+await runtime.abandon({
+  conversationId,
+  runId,
+  expectedRevision: run.revision,
+  staleOwner: true,
+})
+```
+
+The revision protects against stale operator evidence. The mutation updates the
+canonical run and failed assistant atomically, removes the run from recovery
+indexes, and publishes the resulting `run-state`. A run that moved since it was
+read returns a conflict; `staleOwner: true` is mandatory evidence, not a default.
+
 ## Store operations
 
 `AgentRuntimeStore` remains the runtime-facing aggregate. Application adapters

package/llms/agent-runtime.3.txt

@@ -111,7 +111,7 @@ Server-only optional application runtime. See the
 | `AgentSandboxProcess` / `AgentSandboxOutputStream` | _types_ | structural child/output interface for optional lifecycle-owned `AgentProcessSandbox.spawn`, without Node ambient type dependencies |
 | `AgentEventSearchResultSchema` / `AgentEventSearchResult` / `createSqliteAgentEventSearch` / `createAgentEventSearchTools` | schema / _type_ / functions | authorized FTS5 search with exact event addresses and `session_*` tools |
 | `createSqliteAgentSpillStore` | function | durable content-address-checked artifact storage, bounded read/search, retention facts and archive participation |
-| `AgentScheduleSchema` / `AgentSchedule` / `AgentScheduleService` / `createAgentScheduleService` / `createAgentScheduleTools` | schema / _types_ / functions | durable `at`/`after`/timezone-explicit `every`, stable dispatch identity and Agent tools |
+| `AgentScheduleSchema` / `AgentSchedule` / `AgentScheduleService` / `AgentScheduleDeliveryOutcomeSchema` / `AgentScheduleDeliveryOutcome` / `createAgentScheduleService` / `createAgentScheduleTools` | schemas / _types_ / functions | durable `at`/`after`/timezone-explicit `every`, indexed retry eligibility, typed retry/terminal failure, bounded dispatch and fenced stable occurrence identity (ADR 0202) |
 | `AgentChildBudgetSchema` / `AgentChildBudget` / `AgentChildStateSchema` / `AgentChildState` / `AgentChildRecordSchema` / `AgentChildRecord` | schema / _type_ | durable child graph, bounded seed and measured budget state |
 | `AgentChildBlockingKindSchema` / `AgentChildBlockingKind` / `AgentChildBlockingSourceSchema` / `AgentChildBlockingSource` / `AgentChildBlockingEventSchema` / `AgentChildBlockingEvent` / `AgentChildBlockingDecision` | schemas / _types_ | parent-owned request identities; responses discriminate approval decisions from JSON input values |
 | `AgentChildHandle` / `AgentChildManager` / `SqliteAgentChildManagerConfig` / `createSqliteAgentChildManager` / `createAgentChildTools` / `agentChildBudgetStopPolicy` | _type_ / functions | host execution port, child lifecycle, cascade (given to `createAgentRuntime` as `children`), messaging, Agent tools, and the child runtime's own budget stop policy — `recordStepUsage` at every step boundary, `policy_stop` as `child-budget` when spent |

package/llms/agent-runtime.txt

@@ -19,7 +19,7 @@ description: Configure Stitchkit's optional durable history, stream loop, run co
 type: architecture
 status: active
 created: 2026-08-22
-updated: 2026-08-29
+updated: 2026-09-26 16:00 +07:00
 ---
 
 # Agent application runtime
@@ -636,6 +636,23 @@ has invoked a tool is never automatically replayed.
 `createAgentScheduleService` persists `at`, `after` and `every` input. Repeating
 schedules require an explicit IANA time zone. Dispatch uses a stable
 `schedule:<id>:<occurrence>` idempotency key, and restart lateness is recorded.
+Resolve `void` after durable admission; return `{ status: 'retry', reason }` for a
+transient refusal or `{ status: 'terminal', reason }` to stop the entire schedule in
+`failed` state. Throws retry too. Backoff is 1, 2, 4, 8, 16, 32, then 60 seconds,
+capped at 60 seconds and persisted across restart. `retryAt`, `attempts` and `lastError`
+show retry diagnostics; success resets them. `nextAt` and `lateByMs` retain the original
+occurrence time. Recurring schedules fire once after an idle stretch and advance to the
+next future slot on their original cadence.
+
+Dispatch receives an `AbortSignal`, has a 30-second deadline and holds a unique
+60-second lease. A late or cancelled attempt cannot settle or emit firing events.
+Honor the signal and durably deduplicate the key: a crash after admission but before
+settlement can replay delivery. This is at-least-once, not exactly-once.
+Due selection is indexed, limited to 32 parallel deliveries per tick; one hung batch
+can delay newly due work by at most its deadline. The service keeps one nearest-due
+timer plus per-attempt deadline timers. Storage failures use a bounded recovery timer;
+idle ticks do not write. SQLite v4 migration preserves due times and claims; stop older
+scheduler processes before migration. See [ADR 0202](../decisions/0202-schedule-retries-preserve-occurrence-identity.md).
 `createAgentScheduleTools` exposes the exact `schedule_after`, `schedule_at`,
 `schedule_every`, `schedule_list` and `schedule_cancel` surface.
 
@@ -667,227 +684,3 @@ a successor input into the run already in flight.
 ```text
 input + queued run → running → execution settled → terminal CAS → successor
 ```
-
-## What happens to a run when new input arrives
-
-`runs.inputPolicy` decides. It takes five values, or a function returning one:
-
-| policy | the run in flight | what it already produced |
-|--------|-------------------|--------------------------|
-| `queue` (default) | finishes first | kept |
-| `inject` | continues, and answers the new input too | kept, and built on |
-| `interrupt` | ends | kept, and marked as cut off |
-| `interrupt-next` | ends; this input runs before ordinary queued work | kept, and marked as cut off |
-| `supersede` | ends | discarded from the prompt, kept in the record |
-
-`interrupt-next` is the explicit priority path for an urgent input. If A is
-running, ordinary B is queued, and urgent C arrives, the coordinator aborts A,
-waits for A to settle and then runs C before B. B keeps its durable identity and
-eventually runs. Urgent inputs remain FIFO among themselves. They do not
-coalesce into an ordinary pending run: that would erase the priority boundary.
-
-`interrupt` and `supersede` differ in exactly one thing, and the question that
-picks between them is **not** "was the run interrupted" but **"did anyone see
-what it produced"**:
-
-- The user pressed **stop**. The partial answer was streamed to their screen and
-  they read it. It belongs in the conversation — dropping it makes the history
-  lie to the model about what the human has seen. That is `interrupt`.
-- A newer message **superseded** the run. Whether the partial reached anyone
-  depends on the delivery surface: a token stream shows it as it is produced, a
-  surface that sends nothing until the run is done never showed it at all. When
-  it reached nobody, it is not part of the conversation. That is `supersede`.
-
-**Stitchkit cannot answer that question for you** — delivery belongs to the
-transport, and the runtime sees an abort, not a screen. Hence a declared policy
-(→ ADR 0108), and hence `inputPolicy` accepting a function, so one application
-can hold two surfaces with different rules without the core learning which is
-which:
-
-```ts
-runs: {
-  inputPolicy: (input) =>
-    protocol.parseContext(input.context).surface === 'operator' ? 'queue' : 'supersede',
-}
-```
-
-`input.context` is the **raw** context here — admission runs before the runtime
-parses it, so the callback narrows it itself with the protocol it already has.
-
-A superseded run ends with `terminalReason: 'superseded'`, run state
-`'superseded'` and an assistant message of status `'superseded'`. **The record
-is kept** — excluded from the projection, not deleted — so an operator can see
-what was thrown away, and run identity, admission receipts and the terminal CAS
-keep the row they depend on. Compaction leaves it alone for the same reason: a
-turn whose answer is never spoken is not a turn that may be summarised into one,
-because that would both feed the discarded text to the summariser and drop the
-record in `replacedMessageIds`.
-
-It is also outside the token budget. `selectAgentHistory` removes it with reason
-`'superseded'` and does not count it, so an abandoned fragment cannot push a
-real turn out of a context it never occupies.
-
-### How an interrupted turn reaches the model
-
-An interrupted turn is projected, and says so:
-
-```text
-{ role: 'assistant', content: [
-    { type: 'text', text: 'We are the team, where would you like' },
-    { type: 'text', text: '[interrupted: this turn was cut off before it finished]' },
-]}
-```
-
-`history.interruptedAssistant` chooses the form, and the difference between the
-first two is structural rather than cosmetic. **An assistant turn in provider
-history is a commitment**: the model reads its own previous turn as something it
-said and stays consistent with it. A system line is context.
-
-| value | form | right when |
-|-------|------|-----------|
-| `assistant-marked` (default) | assistant turn plus a marker | the human read the text |
-| `system-note` | `[interrupted] partial response: …` as a system line | the fragment reached nobody |
-| `omit` | not projected at all | you want it gone from the request |
-
-There is deliberately no value that reproduces what the projection used to do,
-which was to send the partial as an ordinary assistant turn and drop its
-`control` marker on the way. That was the defect, not a behaviour to stay
-compatible with.
-
-`projectAgentHistoryDetailed` reports what reached the provider, including part
-types that no projected content stands for:
-
-```ts
-const { decisions } = await projectAgentHistoryDetailed(snapshot.messages)
-// → { messageId: 'assistant-2', action: 'projected', reason: 'projected',
-//      omittedParts: ['source', 'provider'] }
-// → { messageId: 'assistant-1', action: 'omitted', reason: 'superseded' }
-```
-
-`runtime.stop(key, 'supersede')` is the same decision taken by hand: the
-process-local escape hatch chooses the reason, so a caller that knows the answer
-was never delivered can discard it without a newer input arriving.
-
-### An input that joins a run in flight
-
-`inject` is right when the new input **refines** rather than redirects, and the
-steps already taken are still worth something: *"summarise this thread… actually,
-in bullet points"* should not throw away the reading the first message paid for.
-
-What happens:
-
-1. The input is admitted exactly like any other — a committed user message and a
-   **queued run**, durable before anything else happens.
-2. At the running loop's next step boundary, that input joins its prompt. Only
-   that input: an unrelated queued submission is never carried in.
-3. When the run finishes, its terminal commit — **one transaction** — records
-   the input as one the run answered and settles the queued successor with
-   `terminalReason: 'absorbed'` and `absorbedIntoRunId` naming the run that
-   answered it. Every ticket for that successor resolves to the same answer.
-
-Nothing durable happens between 1 and 3, and that is the design (→ ADR 0113).
-A run that crashes, is closed, or is interrupted after taking an input on
-commits no absorption at all, so what is left behind is an ordinary queued
-successor — the state every other policy already produces and recovery already
-handles. **There is no ordering in which an accepted input becomes
-unanswerable.** Only a run that *completes* may absorb; an interrupted one took
-the input into its prompt and then stopped, and does not get to say it answered
-it.
-
-An absorbed run has **no assistant message of its own** — it produced none, and
-writing an empty one would be a record claiming otherwise. Its answer is
-reachable through `absorbedIntoRunId`, and the store follows that pointer itself
-when a submission arrives on the absorbed run's idempotency key, so a retry
-after a restart returns the answer rather than an empty terminal record.
-
-It does publish one more `run-state` event, carrying `'superseded'`. It never
-enters the run executor, so that event is the only thing that tells a delivery
-surface following its `runId` that it is no longer queued.
-
-With `coalescePending`, one successor can carry several inputs, and an
-absorption covers a successor **whole or not at all** — a partial one would
-leave a terminal run with inputs nobody answered. Inputs that coalesce before
-the absorbing run's last step boundary join the same absorption. One that
-arrives after it cancels the absorption: the successor then answers all of its
-inputs itself, and the absorbing run has answered one of them too. A duplicate
-answer, never a missing one.
-
-(0.63.0 shipped a version of this that committed the absorption at the step
-boundary, before the answer existed, and it was withdrawn in 0.65.0. ADR 0113
-records what that ordering broke.)
-
-With `runs.coalescePending: true`, an active lane has at most one queued
-successor. Every later accepted input is atomically appended to that successor;
-its `AgentRun.inputMessageIds` records the whole batch and every input ticket
-resolves to the same terminal run. Coalescing never mutates the active run.
-
-`AbortSignal.aborted` is only a cooperation request. A successor does not begin
-while the predecessor still owns managed callbacks. A hung predecessor blocks
-the lane in the first version.
-
-Shutdown is two-phase, and both budgets carry the names they carry everywhere
-else in Stitchkit:
-
-```ts
-const closed = await runtime.close({ gracePeriodMs: 30_000, forceTimeoutMs: 5_000 })
-if (!closed.settled) {
-  console.warn(`exiting with ${closed.remaining} run(s) still in flight`)
-}
-```
-
-`close` first rejects new process-local admissions and gives active runs
-`gracePeriodMs` to finish on their own. Only after that budget expires does it
-abort them with reason `shutdown`; `forceTimeoutMs` then bounds the settlement
-wait for a non-cooperative model or tool, measured from the abort — the two
-budgets add up rather than overlapping.
-
-**`close()` reports what it achieved rather than promising an outcome it cannot
-reach.** The result is `{ settled, timedOut, remaining }`: `settled` when every
-in-flight run finished, `timedOut` with a `remaining` count when the force
-budget expired first. There is no combination of budgets that is both bounded
-and guaranteed to leave nothing in flight — that is the trade the budgets exist
-to make, and the result is where you read which side of it you got:
-
-| budgets | behaviour | can return with a run in flight |
-|---------|-----------|---------------------------------|
-| neither | aborts immediately, waits for settlement | no — unbounded wait |
-| `gracePeriodMs` only | waits, aborts, then waits for settlement | no — unbounded wait |
-| `forceTimeoutMs` only | aborts immediately, waits at most that long | **yes** — `timedOut` |
-| both | waits, aborts, waits at most that long | **yes** — `timedOut` |
-
-A caller that wants the old shape still writes `await runtime.close(…)` and
-ignores the result. A caller deciding whether to exit the process reads it.
-Durably queued records rejected from the local queue remain recoverable through
-`scanRecoverable`; close never marks them terminal on its own.
-
-Use `await runtime.interrupt({ conversationId, runId })` when the interruption
-must be durable: it first commits `interrupt_requested`, then aborts the local
-coordinator signal. If provider completion races that revision change, the terminal path reloads
-the canonical snapshot. An already-terminal winner settles the ticket directly; a still-owned
-`interrupt_requested` run is committed as `interrupted`, and unrelated aggregate-head conflicts
-remain retriable while the run is active with the same owner and fencing token. A stale owner or
-fencing token remains a conflict. Only the execution that applies the terminal mutation publishes the
-**delivery** `terminal` event — a loser settles from canonical state without republishing the turn,
-and its `AgentRuntimeResult.metrics` is `undefined`. The **operator** `run-terminal` event is not
-gated that way: a losing execution still ran, and still spent whatever it spent, so it reports its
-own usage. The two channels answer to different readers — delivering a turn twice is a user's
-problem, and omitting a run's cost is an operator's.
-`runtime.stop(key)` is the process-local signal-only escape hatch.
-
-When an operator has positive evidence that another process owning one known
-run is gone, close that run through the runtime boundary rather than updating
-an adapter table or JSON payload directly:
-
-```ts
-await runtime.abandon({
-  conversationId,
-  runId,
-  expectedRevision: run.revision,
-  staleOwner: true,
-})
-```
-
-The revision protects against stale operator evidence. The mutation updates the
-canonical run and failed assistant atomically, removes the run from recovery
-indexes, and publishes the resulting `run-state`. A run that moved since it was
-read returns a conflict; `staleOwner: true` is mandatory evidence, not a default.

package/llms/stitchkit.txt

@@ -77,11 +77,11 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 41 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 42 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 21 of the 41 minors since 0.56.2, most recently 0.94.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 42 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -91,7 +91,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 9 of the 41 minors since 0.56.2, most recently 0.96.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 9 of the 42 minors since 0.56.2, most recently 0.96.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |