stitchkit 0.96.0 → 0.97.0

package/llms/telegram.txt

@@ -77,7 +77,10 @@ const operators = createTelegramOperatorChannel<'users' | 'payments' | 'errors'>
 operators.post(`New user ${user.id}`, 'users')
 ```
 
-What to post stays the bot's. On the way down, drain it within the grace period
+Every message is masked before it leaves: a bot token always — bots post their
+errors here, and an error about a local Bot API file carries the token in its
+path — plus any `sensitivePatterns` the bot adds; `telegramOperatorSender` also
+masks its own exact token. What to post stays the bot's. On the way down, drain it within the grace period
 and close it: `drain: (context) => operators.drain(context.signal)`,
 `close: () => operators.close()` in a resource.
 
@@ -176,7 +179,7 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `TelegramBroadcastConfig` / `TelegramBroadcastSend` / `TelegramBroadcastReport` / `TelegramBroadcastRunOutcome` / `TelegramBroadcastOutcome` / `TelegramBroadcastRecipient` | _type_ | `name`, `directory`, `recipients()`, `send({ recipient, attempt })`, `maxAttempts`, `signal`, `onProgress`; counts `delivered` / `unreachable` / `failed` / `uncertain` / `pending` and `finished` / `stopped` / `halted` / `dry-run` |
 | `telegramBroadcastSender` / `TelegramBroadcastSenderConfig` / `TelegramBroadcastMessage` | function / _type_ | the standard `send`: `sendMessage` with a text or `copyMessage` of a prepared message, through the Bot API |
 | `createTelegramOperatorChannel` | function | the operator chat, apart from the journal: `post(text, topic?)` returns at once and never throws; paced sends into forum topics, 429 honoured, oldest dropped on overflow, `drain(signal)` and `close()` for the way down |
-| `TelegramOperatorChannelConfig` / `TelegramOperatorChannel` / `TelegramOperatorMessage` / `TelegramOperatorDrop` / `TelegramChatId` | _type_ | `chatId`, `topics`, `send`, `maxQueued`, `minIntervalMs`, `maxAttempts`, `onDropped`; a drop is `overflow` / `refused` / `attempts` / `closed` with its classification |
+| `TelegramOperatorChannelConfig` / `TelegramOperatorChannel` / `TelegramOperatorMessage` / `TelegramOperatorDrop` / `TelegramChatId` | _type_ | `chatId`, `topics`, `send`, `maxQueued`, `minIntervalMs`, `maxAttempts`, `onDropped`, `sensitivePatterns` (a bot token is always masked); a drop is `overflow` / `refused` / `attempts` / `closed` with its classification |
 | `telegramOperatorSender` / `TelegramOperatorSenderConfig` | function / _type_ | the standard `send`: `sendMessage` into the chat and topic, plain text unless `parseMode` |
 | `createTelegramLocalFiles` | function | files the local Bot API server wrote under `<root>/<token>/`: `resolve(file_path)` and `remove(file_path)` only inside the bot's directory, judged on real paths so a link is judged by where it leads; `check()` for readiness. Recommended root variable: `BOT_API_FILES_ROOT` |
 | `TelegramLocalFilesConfig` / `TelegramLocalFiles` / `TelegramLocalFilesCheck` / `TelegramLocalFileError` / `TelegramLocalFileRefusal` | _type_ / class | `root`, `token`; refusals `root-not-absolute` / `bot-directory-unavailable` / `outside-bot-directory` / `missing` / `not-a-file`, never carrying the path or the token |

package/llms/{upgrading-0.37.0-0.56.0.txt → upgrading-0.37.0-0.58.0.txt}

@@ -1,14 +1,93 @@
-# Upgrading 0.37.0 → 0.56.0 — stitchkit docs slice
+# Upgrading 0.37.0 → 0.58.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.37.0 → 0.56.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.37.0 → 0.58.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.37.0 → 0.56.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.37.0 → 0.58.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.58.0
+
+### The default history projection rejects invalid chronology
+
+`projectAgentHistory` no longer forwards records a provider contract cannot
+accept. A completed assistant record before the first user message, and an
+assistant record whose tool calls have no matching results, are omitted with an
+inspectable decision instead of being sent upstream:
+
+```ts
+// before — a leading assistant record was forwarded as-is
+projectAgentHistory(messages)
+// after — opt in explicitly, and only where the provider contract permits it
+projectAgentHistory(messages, { leadingAssistant: 'allow' })
+```
+
+Two consequences the changelog does not spell out. First, the projection can now
+return **fewer** messages than the history holds, so any assertion or metric
+that compared projected length against stored length will move; read the
+detailed projection instead — it reports what was omitted and why, which is the
+supported way to see the difference. Second, the omission is silent to the
+provider but not to you: if a conversation suddenly loses its leading context,
+the decision record is where that shows up, not the transcript.
+
+### Operator events redact `internalCause` by default
+
+Raw provider and tool failures no longer travel in operator events unless the
+sink asks for them:
+
+```ts
+// before — internalCause was present
+createAgentObservability({ write })
+// after — an explicit operator-only opt-in
+createAgentObservability({ write, includeInternalCause: true })
+```
+
+The consequence to check before upgrading: any dashboard, alert or log
+processor keyed on `internalCause` goes blind the moment you upgrade, and it
+goes blind quietly — the field is absent, not empty. Set the flag on the
+operator sink you own. Product delivery stays redacted regardless of the flag;
+this option cannot widen what reaches a user.
+
+## Released migration: 0.57.0
+
+### Duplicate admission results carry the complete identity
+
+Custom `AgentRuntimeStore` adapters must persist and return the input and
+assistant identities associated with an idempotency key:
+
+```ts
+// before
+return { outcome: 'duplicate', runId, snapshot }
+
+// after
+return { outcome: 'duplicate', input, inputMessageId, runId, assistantMessageId, snapshot }
+```
+
+Prefer replacing the custom aggregate reducer with `createAgentRuntimeStore()`;
+its admission record and transaction driver implement this contract
+automatically. Historical note: 0.59.0 reshaped this driver again, so an adapter
+crossing both versions should read that section first and migrate once.
+
+### `AgentRuntimeEvent` adds a post-commit `admission` variant
+
+Add it to any exhaustive publisher switch. Its `assistant` is either the pending
+placeholder for a new assignment or the canonical persisted assistant for a
+duplicate:
+
+```ts
+case 'admission':
+  await persistProductProjection(event.input, event.run, event.assistant)
+  break
+```
+
+The consequence for an exhaustive switch written without a `default` branch is a
+compile error, which is the point. The consequence for a switch that *has* a
+`default` is worse and silent: post-commit admissions fall into it and are
+projected as an unknown event. Grep for publisher switches before upgrading.
+
 ## Released migration: 0.56.0
 
 ### Surface manifests are version 2

package/llms/{upgrading-0.57.0-0.69.0.txt → upgrading-0.59.0-0.71.0.txt}

@@ -1,14 +1,119 @@
-# Upgrading 0.57.0 → 0.69.0 — stitchkit docs slice
+# Upgrading 0.59.0 → 0.71.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.57.0 → 0.69.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.59.0 → 0.71.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.57.0 → 0.69.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.59.0 → 0.71.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.71.0
+
+The Agent coding tools. Two of the three changes are visible to the compiler;
+the third is the one to read carefully, because nothing will point at it.
+
+### If you implement `authorize`
+
+The operation union gained `edit`, `list` and `glob` and lost `patch`. An
+exhaustive matcher stops compiling and the compiler shows you every arm. **A
+matcher with a default branch does not**, and that is the dangerous case:
+
+```ts
+// before — and after this upgrade, silently wrong in both directions
+if (request.operation === 'patch') return reviewPatch(request)
+return true            // now also authorizes edit, list and glob
+// …or: return false   // now also kills edit_file
+```
+
+```ts
+// after
+switch (request.operation) {
+  case 'edit':   return reviewEdit(request)   // the old `patch` payload, unchanged
+  case 'list':
+  case 'glob':   return true                  // or your own policy
+  // …existing read / write / search / shell / artifact-read arms
+}
+```
+
+`write` gained `createsDirectories` — the workspace-relative directories the
+call would create, outermost first, reported **before** anything is created. A
+host that wants to refuse implicit directory creation now can.
+
+### If you call `apply_patch`
+
+It is `edit_file`, and it is one call:
+
+```ts
+// before
+const read = await readFile({ path })
+await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: true })
+await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: false })
+
+// after
+await editFile({ path, oldText, newText })
+```
+
+`expectedSha256` is optional and still refuses a stale base with `CONFLICT` when
+you pass it; `edit_file` returns the resulting `sha256`, so a chain of edits
+never needs to re-read. If you key an approval policy or a UI label on the string
+`apply_patch`, update the key — nothing will fail loudly.
+
+### If you match on `INTERNAL_SERVER_ERROR` from a coding tool
+
+Ordinary outcomes no longer arrive that way. A missing file is `NOT_FOUND`, an
+existing file without `overwrite` is `CONFLICT`, an ambiguous snippet is
+`CONFLICT` with the occurrence count, a path outside the root is `FORBIDDEN`.
+Code that treated any coding-tool failure as an internal fault will now see
+codes it did not before; code that showed the model an empty error now has a
+sentence and a `hint` to show it. Host-level causes are unchanged and still
+scrubbed.
+
+### If you write files into new directories
+
+Nothing to change: `write_file` creates missing parents inside the root. Read
+`createdDirectories` in the result if you want to notice a typo — a path that
+was a failure before is now a successful write into a new tree.
+
+### If you want a step to know its context budget
+
+Opt in by reading it; nothing is injected for you:
+
+```ts
+loop: {
+  prepareStep: ({ contextUsage }) => {
+    const used = contextUsage?.usedTokens
+    if (used?.provenance === 'unavailable') return {}      // no step has landed yet
+    const fraction = (used?.value ?? 0) / (contextUsage?.contextWindow ?? 1)
+    // …render it wherever you put it
+    return {}
+  },
+}
+```
+
+Put it at the **tail** of the conversation rather than in the system
+instructions unless you have a reason: changing the system prompt on every step
+invalidates the provider's prefix cache for the whole conversation, and on a long
+run that is a multiple of the input cost.
+
+## Released migration: 0.70.0
+
+### Descriptor-backed Agent filesystem containment
+
+Built-in coding file/search tools and `createAgentHarnessFileResources` now require a runtime
+that can address an opened directory descriptor: Linux `/proc/self/fd`, or the packaged macOS
+Node-API backend added in 0.70.1. This is what keeps a mutable parent rename or outside-symlink replacement from changing
+the authorized target between validation and the actual effect.
+
+No call-site change is needed on those platforms. The 0.70.0 notes incorrectly inferred macOS and
+FreeBSD support from `/dev/fd`; macOS is restored by 0.70.1 and FreeBSD remains unsupported. On
+Windows or another platform without that
+boundary, move the built-in filesystem operations to a supported worker or replace them with
+application-owned tools backed by an equivalent native handle API. They fail closed rather than
+falling back to path spelling. `run_command` remains separately available under its explicit
+executable alias and authorization policy; this change does not claim an executable sandbox.
+
 ## Released migration: 0.69.0
 
 ### Direct coding-tool operation names
@@ -1035,82 +1140,3 @@ createAgentRuntimeStore({
 `runAgentStoreConformance()` against the migrated adapter before switching production traffic.
 If an application implements `AgentRuntimeStore` directly, its duplicate result must also include
 the canonical `run` and the retained `assistant` for a terminal run.
-
-## Released migration: 0.58.0
-
-### The default history projection rejects invalid chronology
-
-`projectAgentHistory` no longer forwards records a provider contract cannot
-accept. A completed assistant record before the first user message, and an
-assistant record whose tool calls have no matching results, are omitted with an
-inspectable decision instead of being sent upstream:
-
-```ts
-// before — a leading assistant record was forwarded as-is
-projectAgentHistory(messages)
-// after — opt in explicitly, and only where the provider contract permits it
-projectAgentHistory(messages, { leadingAssistant: 'allow' })
-```
-
-Two consequences the changelog does not spell out. First, the projection can now
-return **fewer** messages than the history holds, so any assertion or metric
-that compared projected length against stored length will move; read the
-detailed projection instead — it reports what was omitted and why, which is the
-supported way to see the difference. Second, the omission is silent to the
-provider but not to you: if a conversation suddenly loses its leading context,
-the decision record is where that shows up, not the transcript.
-
-### Operator events redact `internalCause` by default
-
-Raw provider and tool failures no longer travel in operator events unless the
-sink asks for them:
-
-```ts
-// before — internalCause was present
-createAgentObservability({ write })
-// after — an explicit operator-only opt-in
-createAgentObservability({ write, includeInternalCause: true })
-```
-
-The consequence to check before upgrading: any dashboard, alert or log
-processor keyed on `internalCause` goes blind the moment you upgrade, and it
-goes blind quietly — the field is absent, not empty. Set the flag on the
-operator sink you own. Product delivery stays redacted regardless of the flag;
-this option cannot widen what reaches a user.
-
-## Released migration: 0.57.0
-
-### Duplicate admission results carry the complete identity
-
-Custom `AgentRuntimeStore` adapters must persist and return the input and
-assistant identities associated with an idempotency key:
-
-```ts
-// before
-return { outcome: 'duplicate', runId, snapshot }
-
-// after
-return { outcome: 'duplicate', input, inputMessageId, runId, assistantMessageId, snapshot }
-```
-
-Prefer replacing the custom aggregate reducer with `createAgentRuntimeStore()`;
-its admission record and transaction driver implement this contract
-automatically. Historical note: 0.59.0 reshaped this driver again, so an adapter
-crossing both versions should read that section first and migrate once.
-
-### `AgentRuntimeEvent` adds a post-commit `admission` variant
-
-Add it to any exhaustive publisher switch. Its `assistant` is either the pending
-placeholder for a new assignment or the canonical persisted assistant for a
-duplicate:
-
-```ts
-case 'admission':
-  await persistProductProjection(event.input, event.run, event.assistant)
-  break
-```
-
-The consequence for an exhaustive switch written without a `default` branch is a
-compile error, which is the point. The consequence for a switch that *has* a
-`default` is worse and silent: post-commit admissions fall into it and are
-projected as an unknown event. Grep for publisher switches before upgrading.

package/llms/{upgrading-0.70.0-0.96.0.txt → upgrading-0.72.0-0.97.0.txt}

@@ -1,14 +1,50 @@
-# Upgrading 0.70.0 → 0.96.0 — stitchkit docs slice
+# Upgrading 0.72.0 → 0.97.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.70.0 → 0.96.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.72.0 → 0.97.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.70.0 → 0.96.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.72.0 → 0.97.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.97.0
+
+### schedule delivery
+
+**Who must act:** consumers of `createAgentScheduleService`, exhaustive switches on
+`AgentSchedule.state`, and operators opening existing agent-runtime SQLite stores.
+
+- Stop old scheduler processes and back up SQLite before startup. The store migrates
+  transactionally to v4; old binaries cannot open it. Rollback uses the backup.
+- Handle `failed` as a terminal schedule state. To refuse future delivery (including
+  recurring delivery), return `{ status: 'terminal', reason: 'destination closed' }`.
+  The occurrence remains unadvanced; `schedule/failed` carries `terminal: true`.
+- A throw or `{ status: 'retry', reason: 'temporarily unavailable' }` retries the same
+  key after 1, 2, 4, 8, 16, 32, then 60 seconds. `nextAt` remains the original due time;
+  `retryAt`, `attempts` and `lastError` expose retry diagnostics. Success clears them.
+- Resolve `void` only after durable consumer admission. Honor the supplied `signal`:
+  dispatch has a 30-second deadline and a 60-second lease. Durable deduplication by
+  `idempotencyKey` is required even after abort or crash; do not implement sleeps in dispatch.
+- Stale/cancelled attempts emit no `schedule/fired` or `schedule/late`. Observe the
+  cancellation event instead of relying on a synthetic cancelled firing.
+
+```ts
+// before
+async function dispatch(request) {
+  if (await destinationClosed(request.conversationId)) throw new Error('closed')
+  await admit(request)
+}
+// after: use this callback as createAgentScheduleService({ dispatch, ... })
+async function dispatch(request) {
+  if (await destinationClosed(request.conversationId)) {
+    return { status: 'terminal', reason: 'destination closed' }
+  }
+  await admit({ ...request, signal: request.signal }) // durably deduplicates idempotencyKey
+}
+```
+
 ## Released migration: 0.96.0
 
 ### resource-context-admission
@@ -1040,108 +1076,3 @@ const snapshot: CreditWindowSnapshot = { state: 'open', capacityBytes: 100, /*
 // after
 const snapshot: CreditWindowSnapshot = { state: 'open', capacityBytes: 100, /* … */ waiting: 0 }
 ```
-
-## Released migration: 0.71.0
-
-The Agent coding tools. Two of the three changes are visible to the compiler;
-the third is the one to read carefully, because nothing will point at it.
-
-### If you implement `authorize`
-
-The operation union gained `edit`, `list` and `glob` and lost `patch`. An
-exhaustive matcher stops compiling and the compiler shows you every arm. **A
-matcher with a default branch does not**, and that is the dangerous case:
-
-```ts
-// before — and after this upgrade, silently wrong in both directions
-if (request.operation === 'patch') return reviewPatch(request)
-return true            // now also authorizes edit, list and glob
-// …or: return false   // now also kills edit_file
-```
-
-```ts
-// after
-switch (request.operation) {
-  case 'edit':   return reviewEdit(request)   // the old `patch` payload, unchanged
-  case 'list':
-  case 'glob':   return true                  // or your own policy
-  // …existing read / write / search / shell / artifact-read arms
-}
-```
-
-`write` gained `createsDirectories` — the workspace-relative directories the
-call would create, outermost first, reported **before** anything is created. A
-host that wants to refuse implicit directory creation now can.
-
-### If you call `apply_patch`
-
-It is `edit_file`, and it is one call:
-
-```ts
-// before
-const read = await readFile({ path })
-await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: true })
-await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: false })
-
-// after
-await editFile({ path, oldText, newText })
-```
-
-`expectedSha256` is optional and still refuses a stale base with `CONFLICT` when
-you pass it; `edit_file` returns the resulting `sha256`, so a chain of edits
-never needs to re-read. If you key an approval policy or a UI label on the string
-`apply_patch`, update the key — nothing will fail loudly.
-
-### If you match on `INTERNAL_SERVER_ERROR` from a coding tool
-
-Ordinary outcomes no longer arrive that way. A missing file is `NOT_FOUND`, an
-existing file without `overwrite` is `CONFLICT`, an ambiguous snippet is
-`CONFLICT` with the occurrence count, a path outside the root is `FORBIDDEN`.
-Code that treated any coding-tool failure as an internal fault will now see
-codes it did not before; code that showed the model an empty error now has a
-sentence and a `hint` to show it. Host-level causes are unchanged and still
-scrubbed.
-
-### If you write files into new directories
-
-Nothing to change: `write_file` creates missing parents inside the root. Read
-`createdDirectories` in the result if you want to notice a typo — a path that
-was a failure before is now a successful write into a new tree.
-
-### If you want a step to know its context budget
-
-Opt in by reading it; nothing is injected for you:
-
-```ts
-loop: {
-  prepareStep: ({ contextUsage }) => {
-    const used = contextUsage?.usedTokens
-    if (used?.provenance === 'unavailable') return {}      // no step has landed yet
-    const fraction = (used?.value ?? 0) / (contextUsage?.contextWindow ?? 1)
-    // …render it wherever you put it
-    return {}
-  },
-}
-```
-
-Put it at the **tail** of the conversation rather than in the system
-instructions unless you have a reason: changing the system prompt on every step
-invalidates the provider's prefix cache for the whole conversation, and on a long
-run that is a multiple of the input cost.
-
-## Released migration: 0.70.0
-
-### Descriptor-backed Agent filesystem containment
-
-Built-in coding file/search tools and `createAgentHarnessFileResources` now require a runtime
-that can address an opened directory descriptor: Linux `/proc/self/fd`, or the packaged macOS
-Node-API backend added in 0.70.1. This is what keeps a mutable parent rename or outside-symlink replacement from changing
-the authorized target between validation and the actual effect.
-
-No call-site change is needed on those platforms. The 0.70.0 notes incorrectly inferred macOS and
-FreeBSD support from `/dev/fd`; macOS is restored by 0.70.1 and FreeBSD remains unsupported. On
-Windows or another platform without that
-boundary, move the built-in filesystem operations to a supported worker or replace them with
-application-owned tools backed by an equivalent native handle API. They fail closed rather than
-falling back to path spelling. `run_command` remains separately available under its explicit
-executable alias and authorization policy; this change does not claim an executable sandbox.

package/llms/upgrading.txt

@@ -11,9 +11,9 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.70.0 → 0.96.0: `llms/upgrading-0.70.0-0.96.0.txt`
-- 0.57.0 → 0.69.0: `llms/upgrading-0.57.0-0.69.0.txt`
-- 0.37.0 → 0.56.0: `llms/upgrading-0.37.0-0.56.0.txt`
+- 0.72.0 → 0.97.0: `llms/upgrading-0.72.0-0.97.0.txt`
+- 0.59.0 → 0.71.0: `llms/upgrading-0.59.0-0.71.0.txt`
+- 0.37.0 → 0.58.0: `llms/upgrading-0.37.0-0.58.0.txt`
 
 # Upgrading stitchkit
 

package/llms-full.txt

@@ -68,11 +68,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 |
@@ -82,7 +82,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 |
@@ -4846,7 +4846,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
@@ -5463,6 +5463,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.
 
@@ -12829,7 +12846,10 @@ const operators = createTelegramOperatorChannel<'users' | 'payments' | 'errors'>
 operators.post(`New user ${user.id}`, 'users')
 ```
 
-What to post stays the bot's. On the way down, drain it within the grace period
+Every message is masked before it leaves: a bot token always — bots post their
+errors here, and an error about a local Bot API file carries the token in its
+path — plus any `sensitivePatterns` the bot adds; `telegramOperatorSender` also
+masks its own exact token. What to post stays the bot's. On the way down, drain it within the grace period
 and close it: `drain: (context) => operators.drain(context.signal)`,
 `close: () => operators.close()` in a resource.
 
@@ -12999,6 +13019,42 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.97.0
+
+### schedule delivery
+
+**Who must act:** consumers of `createAgentScheduleService`, exhaustive switches on
+`AgentSchedule.state`, and operators opening existing agent-runtime SQLite stores.
+
+- Stop old scheduler processes and back up SQLite before startup. The store migrates
+  transactionally to v4; old binaries cannot open it. Rollback uses the backup.
+- Handle `failed` as a terminal schedule state. To refuse future delivery (including
+  recurring delivery), return `{ status: 'terminal', reason: 'destination closed' }`.
+  The occurrence remains unadvanced; `schedule/failed` carries `terminal: true`.
+- A throw or `{ status: 'retry', reason: 'temporarily unavailable' }` retries the same
+  key after 1, 2, 4, 8, 16, 32, then 60 seconds. `nextAt` remains the original due time;
+  `retryAt`, `attempts` and `lastError` expose retry diagnostics. Success clears them.
+- Resolve `void` only after durable consumer admission. Honor the supplied `signal`:
+  dispatch has a 30-second deadline and a 60-second lease. Durable deduplication by
+  `idempotencyKey` is required even after abort or crash; do not implement sleeps in dispatch.
+- Stale/cancelled attempts emit no `schedule/fired` or `schedule/late`. Observe the
+  cancellation event instead of relying on a synthetic cancelled firing.
+
+```ts
+// before
+async function dispatch(request) {
+  if (await destinationClosed(request.conversationId)) throw new Error('closed')
+  await admit(request)
+}
+// after: use this callback as createAgentScheduleService({ dispatch, ... })
+async function dispatch(request) {
+  if (await destinationClosed(request.conversationId)) {
+    return { status: 'terminal', reason: 'destination closed' }
+  }
+  await admit({ ...request, signal: request.signal }) // durably deduplicates idempotencyKey
+}
+```
+
 ## Released migration: 0.96.0
 
 ### resource-context-admission
@@ -17682,7 +17738,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 |
@@ -18540,7 +18596,7 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `TelegramBroadcastConfig` / `TelegramBroadcastSend` / `TelegramBroadcastReport` / `TelegramBroadcastRunOutcome` / `TelegramBroadcastOutcome` / `TelegramBroadcastRecipient` | _type_ | `name`, `directory`, `recipients()`, `send({ recipient, attempt })`, `maxAttempts`, `signal`, `onProgress`; counts `delivered` / `unreachable` / `failed` / `uncertain` / `pending` and `finished` / `stopped` / `halted` / `dry-run` |
 | `telegramBroadcastSender` / `TelegramBroadcastSenderConfig` / `TelegramBroadcastMessage` | function / _type_ | the standard `send`: `sendMessage` with a text or `copyMessage` of a prepared message, through the Bot API |
 | `createTelegramOperatorChannel` | function | the operator chat, apart from the journal: `post(text, topic?)` returns at once and never throws; paced sends into forum topics, 429 honoured, oldest dropped on overflow, `drain(signal)` and `close()` for the way down |
-| `TelegramOperatorChannelConfig` / `TelegramOperatorChannel` / `TelegramOperatorMessage` / `TelegramOperatorDrop` / `TelegramChatId` | _type_ | `chatId`, `topics`, `send`, `maxQueued`, `minIntervalMs`, `maxAttempts`, `onDropped`; a drop is `overflow` / `refused` / `attempts` / `closed` with its classification |
+| `TelegramOperatorChannelConfig` / `TelegramOperatorChannel` / `TelegramOperatorMessage` / `TelegramOperatorDrop` / `TelegramChatId` | _type_ | `chatId`, `topics`, `send`, `maxQueued`, `minIntervalMs`, `maxAttempts`, `onDropped`, `sensitivePatterns` (a bot token is always masked); a drop is `overflow` / `refused` / `attempts` / `closed` with its classification |
 | `telegramOperatorSender` / `TelegramOperatorSenderConfig` | function / _type_ | the standard `send`: `sendMessage` into the chat and topic, plain text unless `parseMode` |
 | `createTelegramLocalFiles` | function | files the local Bot API server wrote under `<root>/<token>/`: `resolve(file_path)` and `remove(file_path)` only inside the bot's directory, judged on real paths so a link is judged by where it leads; `check()` for readiness. Recommended root variable: `BOT_API_FILES_ROOT` |
 | `TelegramLocalFilesConfig` / `TelegramLocalFiles` / `TelegramLocalFilesCheck` / `TelegramLocalFileError` / `TelegramLocalFileRefusal` | _type_ / class | `root`, `token`; refusals `root-not-absolute` / `bot-directory-unavailable` / `outside-bot-directory` / `missing` / `not-a-file`, never carrying the path or the token |