stitchkit 0.96.1 → 0.98.0

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/cli.txt

@@ -205,6 +205,21 @@ fields in declaration order, so `myapp generate "a fox"` is
 `--prompt "a fox"`. A piped value fills the first required unset field:
 `echo "a fox" | myapp generate`.
 
+Automatic stdin routing skips TTYs and waits at most **250 ms for the first byte**.
+An empty open pipe or EOF without data leaves the field unset, so normal schema
+validation reports the missing field instead of waiting indefinitely. Once any
+byte arrives, the reader collects the entire stream until EOF, including chunks
+separated by long pauses; it decodes UTF-8 after collecting all bytes and trims
+surrounding whitespace. Read errors or a close before EOF fail the invocation.
+Explicit arguments and commands without required unset fields never read stdin.
+
+A producer that takes longer than 250 ms to start must supply its value as an
+argument (for example, `myapp generate --prompt "$(slow-producer)"`) or the
+application must provide an explicit `CliConfig.stdin` reader that waits for it.
+That hook is not wrapped in the availability timeout. `-` remains literal data,
+not a special stdin marker. JSONL stream/batch commands own their input and wait
+for lines as usual; MCP/serve and long-running handlers have no new deadline.
+
 A token is an option only when it is a long form (`--name`, `--name=value`,
 `--`) or `-` followed by a letter. Anything else that starts with `-` is data:
 `myapp note a "- item"` fills a positional, and after an option that expects a

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 43 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 43 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 43 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 |

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.