@fungi.computer/shiitake 0.3.1 → 0.4.0

package/dist/internal/session-context.d.ts

@@ -7,4 +7,4 @@ import type { ShiitakeEffectOptions } from "./effect-contracts.js";
  * context or its context cannot be read; a window the host cannot describe is
  * null, never guessed.
  */
-export declare function readSessionContext(options: ShiitakeEffectOptions, sessionId: string): Effect.Effect<SessionContext | undefined>;
+export declare function readSessionContext(options: ShiitakeEffectOptions, sessionId: string, cursor: string | null, cache?: boolean): Effect.Effect<SessionContext | undefined>;

package/dist/internal/session-context.js

@@ -2,6 +2,7 @@ import * as Effect from "effect/Effect";
 import { estimateContextTokens } from "@earendil-works/pi-ai/utils/estimate";
 import { reportCatchFailure } from "./failure.js";
 import { buildSessionContext, readSessionContextPath, readSessionModelPreference, } from "./woodstock/index.js";
+const contextByOwner = new WeakMap();
 /**
  * The context size compaction measures against the model's window, for the
  * Session's settled context: the next run starts from it. Null before the
@@ -18,28 +19,98 @@ function settledContextTokens(store, sessionId) {
  * context or its context cannot be read; a window the host cannot describe is
  * null, never guessed.
  */
-export function readSessionContext(options, sessionId) {
+export function readSessionContext(options, sessionId, cursor, cache = true) {
     return Effect.gen(function* () {
-        // A context too large to read safely has no footer figure.
-        const read = yield* Effect.result(Effect.try({
-            try: () => ({
-                tokens: settledContextTokens(options.store, sessionId),
-                preference: readSessionModelPreference(options.store, sessionId),
-            }),
+        const savedPreference = yield* Effect.result(Effect.try({
+            try: () => readSessionModelPreference(options.store, sessionId),
             catch: (error) => error,
         }));
-        if (read._tag === "Failure" || read.success.tokens === null)
+        if (savedPreference._tag === "Failure") {
+            reportCatchFailure("session-context.preference", savedPreference.failure);
             return undefined;
-        const { tokens, preference } = read.success;
+        }
+        const preference = savedPreference.success;
+        const preferenceKey = JSON.stringify(preference);
+        const ownerCache = contextByOwner.get(options) ?? new Map();
+        contextByOwner.set(options, ownerCache);
+        const previous = cache ? ownerCache.get(sessionId) : undefined;
         const describe = options.model.describe;
-        if (describe === undefined)
-            return Object.freeze({ tokens, window: null });
+        if (previous?.cursor === cursor && previous.preference === preferenceKey) {
+            if (previous.value === undefined || describe === undefined)
+                return previous.value;
+            const previousValue = previous.value;
+            // A null Session override follows a mutable Agent default. Check the
+            // selected window without decoding history again; a changed window is
+            // a distinct effective preference for this cursor.
+            return yield* describe({ sessionId, preference }).pipe(Effect.map(({ contextWindow }) => {
+                if (previousValue.window === contextWindow)
+                    return previousValue;
+                const value = Object.freeze({
+                    tokens: previousValue.tokens,
+                    window: contextWindow,
+                });
+                if (cache && ownerCache.get(sessionId)?.cursor === cursor)
+                    ownerCache.set(sessionId, {
+                        cursor,
+                        preference: preferenceKey,
+                        value,
+                    });
+                return value;
+            }), Effect.catch((error) => Effect.sync(() => {
+                reportCatchFailure("session-context.describe", error);
+                return previousValue;
+            })));
+        }
+        // At most one cached whole-window read per Session, cursor, and
+        // preference: a late describe may publish only while this cursor still
+        // owns the cache entry. Reads before the tip bypass the cache and each read
+        // the whole window. A cold-cache connection also reads the whole kept
+        // window.
+        const contextRead = yield* Effect.result(Effect.try({
+            try: () => settledContextTokens(options.store, sessionId),
+            catch: (error) => error,
+        }));
+        if (contextRead._tag === "Failure") {
+            reportCatchFailure("session-context.figure", contextRead.failure);
+            return undefined;
+        }
+        const tokens = contextRead.success;
+        if (tokens === null) {
+            if (cache)
+                ownerCache.set(sessionId, {
+                    cursor,
+                    preference: preferenceKey,
+                    value: undefined,
+                });
+            return undefined;
+        }
+        if (describe === undefined) {
+            const value = Object.freeze({ tokens, window: null });
+            if (cache)
+                ownerCache.set(sessionId, { cursor, preference: preferenceKey, value });
+            return value;
+        }
+        // Publish the decoded figure before yielding to the host's model
+        // description. Concurrent watchers then reuse these tokens rather than
+        // decoding the same Session window while `describe` is in flight.
+        if (cache)
+            ownerCache.set(sessionId, {
+                cursor,
+                preference: preferenceKey,
+                value: Object.freeze({ tokens, window: null }),
+            });
         // A null Session override follows a mutable Agent default. Resolve through
         // the host's turn-model selector on every read, without acquiring a turn.
-        const window = yield* describe({ sessionId, preference }).pipe(Effect.map(({ contextWindow }) => contextWindow), Effect.catch((error) => Effect.sync(() => {
+        const window = yield* describe({
+            sessionId,
+            preference,
+        }).pipe(Effect.map(({ contextWindow }) => contextWindow), Effect.catch((error) => Effect.sync(() => {
             reportCatchFailure("session-context.describe", error);
             return null;
         })));
-        return Object.freeze({ tokens, window });
+        const value = Object.freeze({ tokens, window });
+        if (cache && ownerCache.get(sessionId)?.cursor === cursor)
+            ownerCache.set(sessionId, { cursor, preference: preferenceKey, value });
+        return value;
     });
 }

package/dist/internal/woodstock/agent-reply.d.ts

@@ -5,13 +5,18 @@ import * as Schema from "effect/Schema";
  * the mail it sent: the replying Agent and Session plus BirdDog's settlement
  * facts. Only `acceptMail` stores it, and only the host passes it.
  */
-export declare const VerifiedAgentReplySchema: Schema.Struct<{
+export declare const VerifiedAgentReplySchema: Schema.Union<readonly [Schema.Struct<{
     readonly commandId: Schema.String;
     readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
     readonly diagnostic: Schema.optionalKey<Schema.String>;
     readonly agentId: Schema.String;
     readonly sessionId: Schema.String;
-}>;
+}>, Schema.Struct<{
+    readonly outcome: Schema.Literal<"undeliverable">;
+    readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+    readonly agentId: Schema.String;
+    readonly sessionId: Schema.optionalKey<Schema.String>;
+}>]>;
 /** A delegated Agent's reply after the admitting host authenticated it. */
 export type VerifiedAgentReply = typeof VerifiedAgentReplySchema.Type;
 /** The tag that marks a host-verified Agent reply in model context. */

package/dist/internal/woodstock/agent-reply.js

@@ -1,4 +1,4 @@
-import { BirdDogReplySchema } from "@fungi.computer/bird-dog/effect";
+import { SettledBirdDogReplySchema, UndeliverableBirdDogReplySchema, } from "@fungi.computer/bird-dog/effect";
 import * as Schema from "effect/Schema";
 const Identifier = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
 /**
@@ -6,11 +6,18 @@ const Identifier = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength
  * the mail it sent: the replying Agent and Session plus BirdDog's settlement
  * facts. Only `acceptMail` stores it, and only the host passes it.
  */
-export const VerifiedAgentReplySchema = Schema.Struct({
-    agentId: Identifier,
-    sessionId: Identifier,
-    ...BirdDogReplySchema.fields,
-});
+export const VerifiedAgentReplySchema = Schema.Union([
+    Schema.Struct({
+        agentId: Identifier,
+        sessionId: Identifier,
+        ...SettledBirdDogReplySchema.fields,
+    }),
+    Schema.Struct({
+        agentId: Identifier,
+        sessionId: Schema.optionalKey(Identifier),
+        ...UndeliverableBirdDogReplySchema.fields,
+    }),
+]);
 /** The tag that marks a host-verified Agent reply in model context. */
 export const AGENT_REPLY_TAG = "fungi_agent_reply";
 // `<` before the tag name, allowing the spacing and case a model would still read as the tag.
@@ -27,14 +34,16 @@ function attribute(value) {
         .replaceAll(">", "&gt;");
 }
 function opening(reply) {
-    const attributes = [
-        ["agent_id", reply.agentId],
-        ["session_id", reply.sessionId],
-        ["command_id", reply.commandId],
-        ["outcome", reply.outcome],
-    ];
-    if (reply.diagnostic !== undefined)
+    const attributes = [["agent_id", reply.agentId]];
+    if (reply.sessionId !== undefined)
+        attributes.push(["session_id", reply.sessionId]);
+    if (reply.outcome !== "undeliverable")
+        attributes.push(["command_id", reply.commandId]);
+    attributes.push(["outcome", reply.outcome]);
+    if (reply.outcome !== "undeliverable" && reply.diagnostic !== undefined)
         attributes.push(["diagnostic", reply.diagnostic]);
+    if (reply.outcome === "undeliverable")
+        attributes.push(["reason", reply.reason]);
     const rendered = attributes
         .map(([name, value]) => `${name}="${attribute(value)}"`)
         .join(" ");

package/dist/internal/woodstock/fleet-store.d.ts

@@ -27,10 +27,11 @@ export declare function createFleetDelegationStore(storage: WatchdogSqliteOwner)
     read: (requestId: string) => {
         readonly [x: string]: string | number | ArrayBuffer | null;
     } | undefined;
-    /** Every delegation this owner has sent and had accepted, newest first. */
+    /** Every recipient-accepted delegation, newest first. */
     sent: () => readonly {
         readonly [x: string]: string | number | ArrayBuffer | null;
     }[];
     reserve(requestId: string, input: string, mail: string): void;
-    recordReceipt(requestId: string, receipt: string): void;
+    recordReceipt(requestId: string, receipt: string, expectedMail: string, acceptedMail: string): void;
+    recordHeld(requestId: string): void;
 };

package/dist/internal/woodstock/fleet-store.js

@@ -81,24 +81,61 @@ export function createFleetDirectoryStore(sql) {
 /** Durable correspondence is frozen before delivery; retries reuse the same row. */
 export function createFleetDelegationStore(storage) {
     storage.sql.exec(`CREATE TABLE IF NOT EXISTS shiitake_fleet_delegations (
-    request_id TEXT PRIMARY KEY, input TEXT NOT NULL, mail TEXT NOT NULL, receipt TEXT
+    request_id TEXT PRIMARY KEY, input TEXT NOT NULL, mail TEXT NOT NULL,
+    receipt TEXT
+  ) STRICT`);
+    storage.sql.exec(`CREATE TABLE IF NOT EXISTS shiitake_fleet_held_delegations (
+    request_id TEXT PRIMARY KEY
   ) STRICT`);
     return {
         read: (requestId) => storage.sql
-            .exec("SELECT input, mail, receipt FROM shiitake_fleet_delegations WHERE request_id = ?", requestId)
+            .exec(`SELECT delegation.input, delegation.mail,
+            CASE
+              WHEN held.request_id IS NOT NULL THEN 'held'
+              WHEN delegation.receipt IS NOT NULL THEN 'accepted'
+              ELSE 'pending'
+            END AS state,
+            delegation.receipt
+          FROM shiitake_fleet_delegations AS delegation
+          LEFT JOIN shiitake_fleet_held_delegations AS held
+            ON held.request_id = delegation.request_id
+          WHERE delegation.request_id = ?`, requestId)
             .toArray()[0],
-        /** Every delegation this owner has sent and had accepted, newest first. */
+        /** Every recipient-accepted delegation, newest first. */
         sent: () => storage.sql
-            .exec("SELECT input, mail, receipt FROM shiitake_fleet_delegations WHERE receipt IS NOT NULL ORDER BY rowid DESC")
+            .exec(`SELECT input, mail, 'accepted' AS state, receipt
+          FROM shiitake_fleet_delegations
+          WHERE receipt IS NOT NULL
+          ORDER BY rowid DESC`)
             .toArray(),
         reserve(requestId, input, mail) {
             storage.transactionSync(() => {
                 storage.sql.exec("INSERT OR IGNORE INTO shiitake_fleet_delegations(request_id, input, mail) VALUES (?, ?, ?)", requestId, input, mail);
             });
         },
-        recordReceipt(requestId, receipt) {
+        recordReceipt(requestId, receipt, expectedMail, acceptedMail) {
+            storage.transactionSync(() => {
+                const row = storage.sql
+                    .exec("SELECT mail, receipt FROM shiitake_fleet_delegations WHERE request_id = ?", requestId)
+                    .toArray()[0];
+                if (row === undefined)
+                    throw new Error("Cannot record acceptance without frozen delegation mail");
+                if (row.receipt !== null) {
+                    if (row.receipt === receipt && row.mail === acceptedMail)
+                        return;
+                    throw new Error("Delegation acceptance conflicts with its recorded receipt");
+                }
+                if (row.mail !== expectedMail)
+                    throw new Error("Delegation mail changed before acceptance was recorded");
+                storage.sql.exec("UPDATE shiitake_fleet_delegations SET mail = ?, receipt = ? WHERE request_id = ? AND receipt IS NULL", acceptedMail, receipt, requestId);
+                storage.sql.exec("DELETE FROM shiitake_fleet_held_delegations WHERE request_id = ?", requestId);
+            });
+        },
+        recordHeld(requestId) {
             storage.transactionSync(() => {
-                storage.sql.exec("UPDATE shiitake_fleet_delegations SET receipt = ? WHERE request_id = ?", receipt, requestId);
+                storage.sql.exec(`INSERT OR IGNORE INTO shiitake_fleet_held_delegations (request_id)
+          SELECT request_id FROM shiitake_fleet_delegations
+          WHERE request_id = ? AND receipt IS NULL`, requestId);
             });
         },
     };

package/dist/internal/woodstock/index.d.ts

@@ -125,6 +125,8 @@ export declare function readSessionSummary(owner: SqliteOwner, sessionId: string
  * `admitNew` may refuse a new Session; a replayed request is never refused.
  */
 export declare function createSession(owner: SqliteOwner, requestId: string, admitNew: () => void): Effect.Effect<string, ShiitakeError>;
+/** Reserve or replay a Session inside an enclosing owner transaction. */
+export declare function createSessionWithinTransaction(owner: SqliteOwner, requestId: string, admitNew: () => void): string;
 /** Permanently delete one idle Session; false when it does not exist. */
 export declare function deleteSession(owner: SqliteOwner, input: Readonly<{
     sessionId: string;

package/dist/internal/woodstock/index.js

@@ -7,7 +7,7 @@ import { diagnosticsByWorkId, projectCommandSettlement, readClientReplayPage, re
 import { sessionIds } from "./identities.js";
 import { openProgress, openToolProgress } from "./progress.js";
 import { encodeStoredSessionEntry, } from "./session-entry.js";
-import { appendSessionEntry, appendCompactionTransitionOwned, appendCompactionNoticeOwned, placeCompactionTransitionOwned, acceptSessionAbort, acceptSessionCancellation, completeSessionLeaf, prepareSessionRun, prepareSessionStore, readSessionEntriesForWork, readSessionCommandAdmission, settleSessionControls, takePendingSessionControls, readSessionEntryById, selectSessionBranch, forkSessionAt, readStoredSessionSummary as readSessionSummaryOwned, readStoredSessionFactPage, createStoredSession, deleteStoredSession, appendOperatorEntry, } from "./session-store.js";
+import { appendSessionEntry, appendCompactionTransitionOwned, appendCompactionNoticeOwned, placeCompactionTransitionOwned, acceptSessionAbort, acceptSessionCancellation, completeSessionLeaf, prepareSessionRun, prepareSessionStore, readSessionEntriesForWork, readSessionCommandAdmission, settleSessionControls, takePendingSessionControls, readSessionEntryById, selectSessionBranch, forkSessionAt, readStoredSessionSummary as readSessionSummaryOwned, readStoredSessionFactPage, createStoredSession, createStoredSessionWithinTransaction, deleteStoredSession, appendOperatorEntry, } from "./session-store.js";
 import { readSessionInboxPage, recordSessionInboxDeletion, } from "./session-inbox.js";
 export * from "./extension-store.js";
 export { readLatestPendingPrompt } from "./client-projection.js";
@@ -66,7 +66,7 @@ export function cancelSession(owner, sessionId, commandId, onlyIfPending, readQu
     return storeEffect(() => {
         const cancellation = acceptSessionCancellation(owner, sessionId, commandId, readQueueHead, record, onlyIfPending, meta);
         if (cancellation?.delivery === "new")
-            publishOwnerObservation(owner, sessionId);
+            publishOwnerObservation(owner, sessionId, "settlement");
         return cancellation;
     });
 }
@@ -83,14 +83,14 @@ export function takeSessionControls(owner, input) {
 export function settleControls(owner, input) {
     return storeEffect(() => {
         settleSessionControls(owner, input);
-        publishOwnerObservation(owner, input.sessionId);
+        publishOwnerObservation(owner, input.sessionId, "settlement");
     });
 }
 /** Resolve Session-scoped abort to private work and record it atomically. */
 export function abortSession(owner, sessionId, readQueueHead, record, meta) {
     return storeEffect(() => {
         const cancellation = acceptSessionAbort(owner, sessionId, readQueueHead, record, meta);
-        publishOwnerObservation(owner, sessionId);
+        publishOwnerObservation(owner, sessionId, "settlement");
         return cancellation?.accepted;
     });
 }
@@ -202,6 +202,10 @@ export function readSessionSummary(owner, sessionId) {
 export function createSession(owner, requestId, admitNew) {
     return storeEffect(() => createStoredSession(owner, decodeClientSessionCreationRequestId({ requestId }), admitNew));
 }
+/** Reserve or replay a Session inside an enclosing owner transaction. */
+export function createSessionWithinTransaction(owner, requestId, admitNew) {
+    return createStoredSessionWithinTransaction(owner, decodeClientSessionCreationRequestId({ requestId }), admitNew);
+}
 /** Permanently delete one idle Session; false when it does not exist. */
 export function deleteSession(owner, input) {
     return storeEffect(() => deleteStoredSession(owner, {
@@ -273,7 +277,9 @@ function appendRecordedEntry(owner, accepted, entry, findExisting, beforeAppend)
         throw rejected("Session fact identity allocation failed");
     });
     if (delivery === "new")
-        publishOwnerObservation(owner, accepted.sessionId);
+        publishOwnerObservation(owner, accepted.sessionId, entry.kind === "run_terminal" || entry.kind === "work_terminal"
+            ? "settlement"
+            : "durable");
 }
 /** Persist an operator-only sandbox diagnostic beside its accepted Session work. */
 export function recordSandboxFailure(owner, accepted, event) {

package/dist/internal/woodstock/run-recovery.js

@@ -56,7 +56,10 @@ export function contextMessageIds(path, activeWorkId) {
             if (entry.value.role === "assistant") {
                 lastWorkAssistant.set(entry.workId, row.id);
             }
-            if (terminalWork.has(entry.workId) || entry.workId === activeWorkId)
+            if ((terminalWork.has(entry.workId) || entry.workId === activeWorkId) &&
+                (entry.value.role !== "assistant" ||
+                    (entry.value.stopReason !== "error" &&
+                        entry.value.stopReason !== "aborted")))
                 messages.add(row.id);
         }
         if ((entry.kind === "compaction" && entry.data.resumesRun) ||

package/dist/internal/woodstock/session-entry.d.ts

@@ -70,13 +70,18 @@ declare const StoredSessionEntrySchema: Schema.Union<readonly [Schema.Struct<{
     readonly kind: Schema.Literal<"command">;
     readonly meta: Schema.optionalKey<Schema.Codec<import("../../extensions.js").Json, import("../../extensions.js").Json, never, never>>;
     /** Present only when the host admitted this line as a verified Agent reply. */
-    readonly reply: Schema.optionalKey<Schema.Struct<{
+    readonly reply: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
         readonly commandId: Schema.String;
         readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
         readonly diagnostic: Schema.optionalKey<Schema.String>;
         readonly agentId: Schema.String;
         readonly sessionId: Schema.String;
-    }>>;
+    }>, Schema.Struct<{
+        readonly outcome: Schema.Literal<"undeliverable">;
+        readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+        readonly agentId: Schema.String;
+        readonly sessionId: Schema.optionalKey<Schema.String>;
+    }>]>>;
     readonly delivery: Schema.optionalKey<Schema.Literals<readonly ["steer", "followUp"]>>;
     readonly requestId: Schema.String;
     readonly targetWorkId: Schema.optionalKey<Schema.String>;
@@ -357,6 +362,11 @@ export declare function decodeStoredSessionEntry(value: string): Result.Result<{
         readonly outcome: "completed" | "failed" | "cancelled" | "interrupted" | "outcome_unknown";
         readonly agentId: string;
         readonly diagnostic?: string;
+    } | {
+        readonly reason: "recipient_offline" | "recipient_left";
+        readonly outcome: "undeliverable";
+        readonly agentId: string;
+        readonly sessionId?: string;
     };
     readonly targetWorkId?: string;
 } | {
@@ -513,8 +523,8 @@ export declare function decodeStoredSessionEntry(value: string): Result.Result<{
     readonly workId: string;
     readonly result: "failed";
     readonly trigger: "manual" | "threshold" | "overflow";
-    readonly usage?: Usage;
     readonly diagnostic?: string;
+    readonly usage?: Usage;
 } | {
     readonly kind: "compaction_notice";
     readonly workId: string;

package/dist/internal/woodstock/session-entry.js

@@ -147,6 +147,7 @@ const assistantMessage = Schema.Struct({
         data: Schema.optionalKey(jsonValue),
     })),
     errorMessage: Schema.optionalKey(Schema.String),
+    providerError: Schema.optionalKey(Schema.String),
     rawStopReason: Schema.optionalKey(Schema.String),
     providerThinkingLevel: Schema.optionalKey(Schema.String),
     endTurn: Schema.optionalKey(Schema.Boolean),

package/dist/internal/woodstock/session-store.d.ts

@@ -254,6 +254,10 @@ export declare function readActiveToolForWork(owner: SqliteOwner, sessionId: str
 export declare function createStoredSession(owner: SqliteOwner, requestId: string, 
 /** Refuses a new Session under storage pressure; replays skip it. */
 admitNew: () => void): string;
+/** Reserve a Session while the caller owns the enclosing SQLite transaction. */
+export declare function createStoredSessionWithinTransaction(owner: SqliteOwner, requestId: string, 
+/** Refuses a new Session under storage pressure; replays skip it. */
+admitNew: () => void): string;
 /**
  * Permanently remove one idle Session: its entries, command admissions,
  * creation receipt and inbox row, so a retried creation request reserves a

package/dist/internal/woodstock/session-store.js

@@ -790,23 +790,27 @@ function ensureSession(owner, sessionId) {
 export function createStoredSession(owner, requestId, 
 /** Refuses a new Session under storage pressure; replays skip it. */
 admitNew) {
-    return owner.transactionSync(() => {
-        const existing = owner.sql
-            .exec("SELECT session_id FROM session_creation_receipts WHERE request_id = ?", requestId)
-            .toArray();
-        const first = existing[0];
-        if (first !== undefined) {
-            const decoded = decodeSessionCreationReceiptRow(first);
-            if (decoded._tag === "Failure")
-                throw unavailable("Session creation receipt is invalid");
-            return decoded.success.session_id;
-        }
-        admitNew();
-        const sessionId = sessionIds.session.generate();
-        ensureSession(owner, sessionId);
-        owner.sql.exec("INSERT INTO session_creation_receipts (request_id, session_id) VALUES (?, ?)", requestId, sessionId);
-        return sessionId;
-    });
+    return owner.transactionSync(() => createStoredSessionWithinTransaction(owner, requestId, admitNew));
+}
+/** Reserve a Session while the caller owns the enclosing SQLite transaction. */
+export function createStoredSessionWithinTransaction(owner, requestId, 
+/** Refuses a new Session under storage pressure; replays skip it. */
+admitNew) {
+    const existing = owner.sql
+        .exec("SELECT session_id FROM session_creation_receipts WHERE request_id = ?", requestId)
+        .toArray();
+    const first = existing[0];
+    if (first !== undefined) {
+        const decoded = decodeSessionCreationReceiptRow(first);
+        if (decoded._tag === "Failure")
+            throw unavailable("Session creation receipt is invalid");
+        return decoded.success.session_id;
+    }
+    admitNew();
+    const sessionId = sessionIds.session.generate();
+    ensureSession(owner, sessionId);
+    owner.sql.exec("INSERT INTO session_creation_receipts (request_id, session_id) VALUES (?, ?)", requestId, sessionId);
+    return sessionId;
 }
 /**
  * Permanently remove one idle Session: its entries, command admissions,
@@ -2280,9 +2284,12 @@ reply) {
 function sameReply(left, right) {
     return (left?.agentId === right?.agentId &&
         left?.sessionId === right?.sessionId &&
-        left?.commandId === right?.commandId &&
         left?.outcome === right?.outcome &&
-        left?.diagnostic === right?.diagnostic);
+        (left?.outcome === "undeliverable"
+            ? right?.outcome === "undeliverable" && left.reason === right.reason
+            : right?.outcome !== "undeliverable" &&
+                left?.commandId === right?.commandId &&
+                left?.diagnostic === right?.diagnostic));
 }
 /**
  * Write one decoded admission (a prompt or a compaction request) and its one

package/dist/remote-client.js

@@ -10,7 +10,7 @@ import * as Schema from "effect/Schema";
 import * as Scope from "effect/Scope";
 import * as Sink from "effect/Sink";
 import * as Stream from "effect/Stream";
-import { parseAccepted, parseWithdrawResult, parseCancelResult, parseLatestPendingPrompt, parseForkedSession, parseCreatedSession, parseDeletedSession, parseExtensionOutput, parseExtensionStatus, parseExtensionStatuses, parseSessionFrame, parseSessionSnapshot, parseSessionSummaryPage, parseShiitakeError, } from "./client-wire.js";
+import { parseAccepted, parseCommandSettlement, parseWithdrawResult, parseCancelResult, parseLatestPendingPrompt, parseForkedSession, parseCreatedSession, parseDeletedSession, parseExtensionOutput, parseExtensionStatus, parseExtensionStatuses, parseSessionFrame, parseSessionSnapshot, parseSessionSummaryPage, parseShiitakeError, } from "./client-wire.js";
 import { ShiitakeError } from "./errors.js";
 import { decodeClientReadOptions, decodeClientSessionCreationRequestId, decodeClientPageCursor, decodeClientSessionId, decodeClientSubscribeOptions, } from "./internal/client-boundary.js";
 import { toPromiseAgent } from "./internal/effect-client.js";
@@ -248,6 +248,10 @@ function makeRemoteEffectAgent(options) {
                     params.set("includeSandboxFailures", "true");
                 return request((signal) => fetch(`${addressedUrl}?${params.toString()}`, { signal }), parseSessionSnapshot, "Session read");
             })),
+            readSettlement: (commandId, timeoutMs = 0) => ensureOpen.pipe(Effect.andThen(request((signal) => fetch(`${addressedUrl}/settlement?${new URLSearchParams({
+                commandId,
+                timeoutMs: String(timeoutMs),
+            }).toString()}`, { signal }), parseCommandSettlement, "Command settlement"))),
             subscribe: (input) => Stream.unwrap(ensureOpen.pipe(Effect.andThen(Effect.try({
                 try: () => decodeClientSubscribeOptions(input),
                 catch: (error) => error instanceof ShiitakeError

package/dist/testing.d.ts

@@ -40,8 +40,11 @@ export type MemoryHost = Readonly<{
     agent: ShiitakeOwnerAgent;
     /** Invoke one canonical reconciliation tick; no timer runs in the background. */
     reconcile: () => Promise<void>;
-    /** Drain pending Agent work with a 1–1,000 tick budget (default 1,000). */
-    settle: (sessionId: string, maxTicks?: number) => Promise<SessionSnapshot>;
+    /** Drain pending Agent work with a 1–1,000 tick budget (default 1,000).
+     * The optional test hook runs after pending work ends, before the snapshot
+     * context read, so load tests can end a timed turn at the terminal.
+     */
+    settle: (sessionId: string, maxTicks?: number, beforeRead?: () => Promise<void>) => Promise<SessionSnapshot>;
     /** Close the Agent and only the database owned by this helper. */
     close: () => Promise<void>;
 }>;

package/dist/testing.js

@@ -176,12 +176,14 @@ export async function memoryHost(options = {}) {
         return {
             agent,
             reconcile: async () => requireBound().reconcile(),
-            settle: async (sessionId, maxTicks) => {
+            settle: async (sessionId, maxTicks, beforeRead) => {
                 const budget = settlementBudgetSchema.parse(maxTicks);
                 for (let tick = 0; tick < budget; tick += 1) {
                     const host = requireBound();
-                    if (!(await host.pendingWork()).pending)
+                    if (!(await host.pendingWork()).pending) {
+                        await beforeRead?.();
                         return agent.session(sessionId).read();
+                    }
                     await host.reconcile();
                 }
                 throw new Error(`Memory host did not settle within ${String(budget)} reconciliation ticks`);

package/docs/api/agent-control.md

@@ -219,7 +219,12 @@ Host-only identity and admitted command metadata for one delegated send.
 ```ts
 type AgentControlDirectory = Readonly<{
   list: (signal, options?) => Promise<readonly AgentControlAgent[]>;
-  send?: (input, sourceSessionId, signal, invocation?) => Promise<Accepted>;
+  send?: (
+    input,
+    sourceSessionId,
+    signal,
+    invocation?,
+  ) => Promise<Accepted | Held>;
   recall?: (input, sourceSessionId, signal) => Promise<CancelResult>;
   create?: (input, signal) => Promise<AgentControlAgent>;
   setModel?: (input, signal) => Promise<void>;
@@ -262,10 +267,10 @@ report back, its store predates the current schema, or the Agent is archived.
 
 ## Functions
 
-### waitForAgentTerminal()
+### waitForAgentSettlement()
 
 ```ts
-function waitForAgentTerminal(
+function waitForAgentSettlement(
   session,
   commandId,
   timeoutMs,
@@ -273,16 +278,16 @@ function waitForAgentTerminal(
   startedAt?,
 ): Promise<
   Readonly<{
-    commandId: string;
-    outcome: "completed" | "failed" | "cancelled" | "interrupted";
-    sequence: number;
-    diagnostic: string | null;
-    meta?: Json;
+    acceptedSender: string | null;
+    terminal: SessionTerminal;
+    content: string;
+    usage: readonly Pick<AssistantMessage, "model" | "provider" | "usage">[];
+    toolCalls: number;
   }>
 >;
 ```
 
-Observe one durable terminal; timeout or abort closes observation, not the work.
+Await one exact durable terminal without opening a transcript observation.
 
 #### Parameters
 
@@ -296,9 +301,10 @@ Observe one durable terminal; timeout or abort closes observation, not the work.
 
 #### Returns
 
-`Promise`\<`Readonly`\<\{ `commandId`: `string`; `outcome`: `"completed"` \|
-`"failed"` \| `"cancelled"` \| `"interrupted"`; `sequence`: `number`;
-`diagnostic`: `string` \| `null`; `meta?`: [`Json`](extensions.md#json); \}\>\>
+`Promise`\<`Readonly`\<\{ `acceptedSender`: `string` \| `null`; `terminal`:
+[`SessionTerminal`](client.md#sessionterminal); `content`: `string`; `usage`:
+readonly `Pick`\<`AssistantMessage`, `"model"` \| `"provider"` \| `"usage"`\>[];
+`toolCalls`: `number`; \}\>\>
 
 ---