stitchkit 0.96.1 → 0.98.0

package/dist/entrypoints/cli.js

@@ -18,7 +18,7 @@ import {
   readCapped,
   renderCliView,
   routeCliArgv
-} from "../index-t9rhjr9f.js";
+} from "../index-f1nb70ae.js";
 import"../index-sbdmyz75.js";
 import"../index-hmp4800j.js";
 import {

package/dist/entrypoints/tools.js

@@ -60,7 +60,7 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "../index-t9rhjr9f.js";
+} from "../index-f1nb70ae.js";
 import"../index-sbdmyz75.js";
 import {
   collectToolSurface

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/{index-t9rhjr9f.js → index-f1nb70ae.js}

@@ -1336,16 +1336,52 @@ async function pollUntilDone(params) {
 
 // src/tools/cli/io.ts
 import { writeSync } from "node:fs";
-async function readPipedStdin() {
-  if (process.stdin.isTTY)
-    return null;
-  const chunks = [];
-  for await (const chunk of process.stdin) {
-    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
-  }
-  const text = Buffer.concat(chunks).toString("utf8").trim();
-  return text.length > 0 ? text : null;
+
+// src/tools/cli/stdin.ts
+function readPipedStdin(input = process.stdin) {
+  if (input.isTTY || input.readableEnded)
+    return Promise.resolve(null);
+  if (input.destroyed)
+    return Promise.reject(new Error("stdin closed before EOF"));
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    const cleanup = () => {
+      clearTimeout(timer);
+      input.pause();
+      input.off("data", onData);
+      input.off("end", onEnd);
+      input.off("error", onError);
+      input.off("close", onClose);
+    };
+    const onData = (chunk) => {
+      if (chunk.length === 0)
+        return;
+      clearTimeout(timer);
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    };
+    const onEnd = () => {
+      cleanup();
+      const text = Buffer.concat(chunks).toString("utf8").trim();
+      resolve(text.length > 0 ? text : null);
+    };
+    const onError = (error) => {
+      cleanup();
+      reject(error);
+    };
+    const onClose = () => onError(new Error("stdin closed before EOF"));
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve(null);
+    }, 250);
+    input.on("end", onEnd);
+    input.on("error", onError);
+    input.on("close", onClose);
+    input.on("data", onData);
+    input.resume();
+  });
 }
+
+// src/tools/cli/io.ts
 function createCliIo(config) {
   let pendingWrite;
   let writeFailed = false;

package/dist/tools/cli/config.d.ts

@@ -84,7 +84,11 @@ export interface CliConfig<TAuth = unknown, TContext extends Record<string, unkn
     stderr?: (text: string) => void;
     /** Exit hook — default `process.exit`; injectable for tests. */
     exit?: (code: number) => void;
-    /** Read piped stdin — default reads when not a TTY; injectable for tests. */
+    /**
+     * Read stdin for the first required unset field. The default skips TTYs,
+     * waits up to 250 ms for the first byte, then reads to EOF without a deadline.
+     * Override to explicitly wait for a delayed producer; no probe wraps this hook.
+     */
     stdin?: () => Promise<string | null>;
 }
 //# sourceMappingURL=config.d.ts.map

package/dist/tools/cli/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,MAAM,WAAW,SAAS,CACxB,KAAK,GAAG,OAAO,EACf,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,QAAQ,SAAS,SAAS,GAAG,SAAS,CACtC,SAAQ,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC;IACnD,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACtE;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC;IACtF,qFAAqF;IACrF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;+DAC2D;IAC3D,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,0EAA0E;IAC1E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kEAAkE;IAClE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrE;;;OAGG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,gEAAgE;IAChE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACtC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,MAAM,WAAW,SAAS,CACxB,KAAK,GAAG,OAAO,EACf,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,QAAQ,SAAS,SAAS,GAAG,SAAS,CACtC,SAAQ,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC;IACnD,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACtE;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC;IACtF,qFAAqF;IACrF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;+DAC2D;IAC3D,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,0EAA0E;IAC1E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kEAAkE;IAClE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrE;;;OAGG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,gEAAgE;IAChE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACtC"}

package/dist/tools/cli/io.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/io.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAa1C,yFAAyF;AACzF,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACzC;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC,GAC9D,KAAK,CAqEP"}
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/io.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG1C,yFAAyF;AACzF,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACzC;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC,GAC9D,KAAK,CAqEP"}

package/dist/tools/cli/stdin.d.ts

@@ -0,0 +1,6 @@
+import type { Readable } from 'node:stream';
+/** Probe automatic stdin routing briefly; once data starts, only EOF completes it. */
+export declare function readPipedStdin(input?: Readable & {
+    isTTY?: boolean;
+}): Promise<string | null>;
+//# sourceMappingURL=stdin.d.ts.map

package/dist/tools/cli/stdin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdin.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/stdin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,sFAAsF;AACtF,wBAAgB,cAAc,CAC5B,KAAK,GAAE,QAAQ,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAkB,GACpD,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwCxB"}

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 |