@fungi.computer/shiitake 0.2.0 → 0.3.1

package/dist/internal/extension-runtime.js

@@ -12,7 +12,7 @@ import { ShiitakeError } from "../errors.js";
 import { AdmissionError, ExtensionCommandError, ExtensionRead, ExtensionStateError, ExtensionStop, ExtensionTx, } from "../extensions.js";
 import { decodeClientSessionId } from "./client-boundary.js";
 import { AsyncExtensionTransactionError, invokeExtensionHook, invokeSyncHandler, } from "./extension-hook.js";
-import { setSessionAttention, clearSessionAttention, projectSessionAttention, readAttentionSessionPage, replaceAttentionGrants, hasStoredSession, hasPendingSessionSteer, hasSuccessfulToolResult, advanceCursor, declareSessionDocument, readSessionDocument, writeSessionDocument, deleteAllRecords, deleteRecord, deleteTimer, readAllRecords, readCursor, readDueTimers, readRecord, readRecordPage, readStateLedger, readStatus, readTimer, readTimerWake, writeRecord, writeStateLedger, writeStatus, writeTimer, } from "./woodstock/index.js";
+import { setSessionAttention, clearSessionAttention, projectSessionAttention, readAttentionSessionPage, replaceAttentionGrants, hasStoredSession, readSessionLineage, hasPendingSessionSteer, hasSuccessfulToolResult, advanceCursor, declareSessionDocument, readSessionDocument, writeSessionDocument, deleteAllRecords, deleteRecord, deleteTimer, deleteExtensionTimers, readAllRecords, readCursor, readDueTimers, readRecord, readRecordPage, readStateLedger, readStatus, readTimer, readTimerWake, writeRecord, writeStateLedger, writeStatus, writeTimer, } from "./woodstock/index.js";
 import { JsonValueSchema } from "./json-value.js";
 import { publishOwnerObservation } from "./observation-kernel.js";
 /** The settled consumer name core itself uses for mail and control repair. */
@@ -26,7 +26,7 @@ const decodePromptSections = Schema.decodeUnknownResult(Schema.Array(Schema.Stru
     name: Schema.String.pipe(Schema.check(Schema.isPattern(/^[a-z][A-Za-z0-9_-]{0,63}$/u))),
     text: Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.makeFilter((text) => encoder.encode(text).byteLength <= 8192))),
 })).pipe(Schema.check(Schema.isMaxLength(16))));
-/** A missing or failed pure migration cannot safely decode the new state. */
+/** A declared migration failed or returned records the new state cannot decode. */
 class IncompatibleStateMigrationError extends Error {
 }
 function boundReason(reason) {
@@ -277,9 +277,12 @@ export function openExtensionRuntime(input) {
                 projectSessionAttention(owner, sessionId, input.readQueueHead(sessionId));
                 frame.observed.add(sessionId);
             },
-            catch: (error) => error instanceof ShiitakeError && error.cause === "invalid"
-                ? stateError("bound", error.message)
-                : stateError("unavailable", "Attention update is unavailable"),
+            catch: (error) => error instanceof ExtensionStateError &&
+                error.reason === "session_absent"
+                ? error
+                : error instanceof ShiitakeError && error.cause === "invalid"
+                    ? stateError("bound", error.message)
+                    : stateError("unavailable", "Attention update is unavailable"),
         })));
         return {
             set: (sessionId, item) => {
@@ -290,7 +293,7 @@ export function openExtensionRuntime(input) {
                     ? Effect.fail(stateError("bound", "Attention item is invalid"))
                     : mutate(sessionId, () => {
                         if (!hasStoredSession(owner, sessionId))
-                            throw new Error("Attention Session is unavailable");
+                            throw stateError("session_absent", "Attention Session is absent");
                         setSessionAttention(owner, sessionId, id, decoded.success);
                     });
             },
@@ -564,6 +567,13 @@ export function openExtensionRuntime(input) {
                 send: sendFor(member),
                 timers: timersFor(member),
                 attention: attentionFor(member),
+                sessionPosition: (sessionId) => requireRead(member.admitted.id).pipe(Effect.andThen(grantGuard(member, "state")), Effect.andThen(storeStep(() => {
+                    const id = decodeClientSessionId(sessionId);
+                    if (!hasStoredSession(owner, id))
+                        throw stateError("unavailable", "Session timeline is unavailable");
+                    return (readSessionLineage(owner, { sessionId: id })
+                        ?.newestSequence ?? 0);
+                }))),
                 hasPendingSteer: (run) => requireRead(member.admitted.id).pipe(Effect.andThen(grantGuard(member, "run_tools")), Effect.andThen(storeStep(() => hasPendingSessionSteer(owner, decodeClientSessionId(run.sessionId), run.workId)))),
                 hasSuccessfulToolResult: (run, toolCallId) => requireRead(member.admitted.id).pipe(Effect.andThen(grantGuard(member, "run_tools")), Effect.andThen(storeStep(() => hasSuccessfulToolResult(owner, decodeClientSessionId(run.sessionId), run.workId, toolCallId)))),
                 observe: (sessionId) => requireFrame(member.admitted.id).pipe(Effect.map((frame) => {
@@ -587,54 +597,60 @@ export function openExtensionRuntime(input) {
             }),
         });
     }
-    /** Pure per-version migrations, applied and re-decoded in one transaction. */
+    /** Pure per-version migrations; prepare owns their transaction with declarations. */
     function migrate(member) {
         const { id, definition, revision } = member.admitted;
         const declared = definition.state.version;
-        owner.transactionSync(() => {
-            const ledger = readStateLedger(owner, id);
-            if (ledger !== undefined && ledger.version > declared)
-                throw new ShiitakeError("extensions", "conflict", `Stored ${id} state version ${String(ledger.version)} is newer than ${String(declared)}`);
-            if (ledger !== undefined && ledger.version < declared) {
-                let rows = readAllRecords(owner, id).map((row) => ({
-                    collection: row.collection,
-                    key: row.key,
-                    value: decodeStoredJson(row.valueJson),
-                }));
-                for (let version = ledger.version; version < declared; version += 1) {
-                    const step = definition.state.migrations[version];
-                    if (step === undefined)
-                        throw new IncompatibleStateMigrationError(`Missing ${id} state migration from ${String(version)}`);
-                    try {
-                        rows = rows.flatMap((row) => step(row));
-                    }
-                    catch (cause) {
-                        throw new IncompatibleStateMigrationError(`Failed ${id} state migration from ${String(version)}`, { cause });
-                    }
+        const ledger = readStateLedger(owner, id);
+        if (ledger !== undefined && ledger.version > declared)
+            throw new ShiitakeError("extensions", "conflict", `Stored ${id} state version ${String(ledger.version)} is newer than ${String(declared)}`);
+        if (ledger !== undefined && ledger.version < declared) {
+            let rows = readAllRecords(owner, id).map((row) => ({
+                collection: row.collection,
+                key: row.key,
+                value: decodeStoredJson(row.valueJson),
+            }));
+            for (let version = ledger.version; version < declared; version += 1) {
+                const step = definition.state.migrations[version];
+                if (step === undefined)
+                    throw new ShiitakeError("extensions", "state_reset_required", `State reset required for ${id}: stored version ${String(ledger.version)}, declared version ${String(declared)}. An operator must authorize the reset; stored records have not been changed.`);
+                try {
+                    rows = rows.flatMap((row) => step(row));
                 }
-                deleteAllRecords(owner, id);
-                for (const row of rows) {
-                    const declaredSpec = definition.state.collections[row.collection];
-                    if (declaredSpec === undefined)
-                        throw new IncompatibleStateMigrationError(`Migrated ${id} record names an undeclared collection`);
-                    const decoded = declaredSpec.indexFromEncoded(row.value);
-                    if (decoded._tag === "Failure")
-                        throw new IncompatibleStateMigrationError(`Migrated ${id} ${row.collection} record is invalid`);
-                    writeRecord(owner, id, row.collection, row.key, decoded.success, JSON.stringify(row.value));
+                catch (cause) {
+                    throw new IncompatibleStateMigrationError(`Failed ${id} state migration from ${String(version)}`, { cause });
                 }
             }
-            writeStateLedger(owner, id, declared, revision);
-        });
+            deleteAllRecords(owner, id);
+            for (const row of rows) {
+                const declaredSpec = definition.state.collections[row.collection];
+                if (declaredSpec === undefined)
+                    throw new IncompatibleStateMigrationError(`Migrated ${id} record names an undeclared collection`);
+                const decoded = declaredSpec.indexFromEncoded(row.value);
+                if (decoded._tag === "Failure")
+                    throw new IncompatibleStateMigrationError(`Migrated ${id} ${row.collection} record is invalid`);
+                writeRecord(owner, id, row.collection, row.key, decoded.success, JSON.stringify(row.value));
+            }
+        }
+        writeStateLedger(owner, id, declared, revision);
     }
-    function activateMember(member, scope) {
+    function activateMember(member, scope, strict = false) {
         const context = contextFor(member);
-        return Effect.suspend(() => member.admitted.definition.activate(context)).pipe(Effect.provideService(Scope.Scope, scope), Effect.exit, Effect.flatMap((exit) => {
+        return Effect.gen(function* () {
+            // Each activation owns its resources. Closing a failed candidate must
+            // not wait for Agent shutdown or release another member's resources.
+            const activationScope = yield* Scope.fork(scope);
+            member.scope = activationScope;
+            const exit = yield* Effect.suspend(() => member.admitted.definition.activate(context)).pipe(Effect.provideService(Scope.Scope, activationScope), Effect.exit);
             if (Exit.isSuccess(exit)) {
                 member.hooks = exit.value;
-                return Effect.void;
+                return;
             }
-            return recordStop(member, stopReason("activation", exit.cause), exit.cause, "own-transaction");
-        }));
+            yield* Scope.close(activationScope, exit);
+            if (strict)
+                return yield* Effect.fail(new ShiitakeError("extensions", "rejected", `Extension ${member.admitted.id} failed to start: ${Cause.pretty(exit.cause)}`));
+            yield* recordStop(member, stopReason("activation", exit.cause), exit.cause, "own-transaction");
+        });
     }
     const running = (capability) => [...members.values()].filter((member) => member.status === "running" &&
         member.hooks !== undefined &&
@@ -668,13 +684,14 @@ export function openExtensionRuntime(input) {
         : Effect.void;
     /**
      * Run pending state migrations. A stored version newer than the declared one
-     * fails construction; any other failure stops only this extension.
+     * fails construction. A missing path isolates this extension with its rows
+     * retained; a failed declared migration also guards runs as incompatible.
      */
     function prepare(member) {
         return Effect.try({
             try: () => {
-                migrate(member);
                 owner.transactionSync(() => {
+                    migrate(member);
                     for (const [name, spec] of Object.entries(member.admitted.documents))
                         declareSessionDocument(owner, {
                             extensionId: member.admitted.id,
@@ -686,9 +703,15 @@ export function openExtensionRuntime(input) {
                 });
             },
             catch: (error) => error,
-        }).pipe(Effect.as(true), Effect.catch((error) => {
-            if (error instanceof ShiitakeError)
-                return Effect.fail(error);
+        }).pipe(Effect.tap(() => Effect.sync(() => {
+            delete member.stateResetRequired;
+        })), Effect.as(true), Effect.catch((error) => {
+            if (error instanceof ShiitakeError) {
+                if (error.cause !== "state_reset_required")
+                    return Effect.fail(error);
+                member.stateResetRequired = error;
+                return recordStop(member, boundReason(error.message), Cause.fail(error), "own-transaction").pipe(Effect.as(false));
+            }
             if (error instanceof IncompatibleStateMigrationError &&
                 (member.admitted.grants.has("run_tools") ||
                     member.admitted.grants.has("files") ||
@@ -702,49 +725,56 @@ export function openExtensionRuntime(input) {
     }
     return Effect.gen(function* () {
         const scope = yield* Scope.make();
-        for (const admitted of input.admitted) {
-            const stored = readStatus(owner, admitted.id);
-            const keepStopped = stored?.status === "stopped" && stored.revision === admitted.revision;
-            const member = {
-                admitted,
-                hooks: undefined,
-                status: keepStopped ? "stopped" : "running",
-                reason: keepStopped ? stored.reason : null,
-                stoppedAt: keepStopped ? stored.stoppedAt : null,
-            };
-            members.set(admitted.id, member);
-            // Every settled consumer has a cursor from its first roster on, so a
-            // later resume replays only what it missed.
-            yield* Effect.try({
-                try: () => {
-                    if (admitted.grants.has("settled"))
+        function startMember(admitted, strict) {
+            return Effect.gen(function* () {
+                const stored = readStatus(owner, admitted.id);
+                const keepStopped = stored?.status === "stopped" && stored.revision === admitted.revision;
+                const member = {
+                    admitted,
+                    hooks: undefined,
+                    status: keepStopped ? "stopped" : "running",
+                    reason: keepStopped ? stored.reason : null,
+                    stoppedAt: keepStopped ? stored.stoppedAt : null,
+                };
+                // Every settled consumer has a cursor from its first roster on, so a
+                // later resume replays only what it missed.
+                yield* Effect.try({
+                    try: () => {
+                        if (admitted.grants.has("settled"))
+                            owner.transactionSync(() => {
+                                if (readCursor(owner, admitted.id) === undefined)
+                                    advanceCursor(owner, admitted.id, readCursor(owner, coreConsumer) ?? 0);
+                            });
+                    },
+                    catch: () => new ShiitakeError("store", "unavailable", "Settled cursor is unavailable"),
+                });
+                const prepared = yield* prepare(member);
+                if (!prepared || keepStopped) {
+                    if (strict)
+                        return yield* Effect.fail(new ShiitakeError("extensions", "rejected", `Extension ${admitted.id} cannot start: ${member.reason ?? "stopped"}`));
+                    return member;
+                }
+                yield* Effect.try({
+                    try: () => {
                         owner.transactionSync(() => {
-                            if (readCursor(owner, admitted.id) === undefined)
-                                advanceCursor(owner, admitted.id, readCursor(owner, coreConsumer) ?? 0);
-                        });
-                },
-                catch: () => new ShiitakeError("store", "unavailable", "Settled cursor is unavailable"),
-            });
-            const prepared = yield* prepare(member).pipe(Effect.onError(() => Scope.close(scope, Exit.void)));
-            if (!prepared)
-                continue;
-            if (keepStopped)
-                continue;
-            yield* Effect.try({
-                try: () => {
-                    owner.transactionSync(() => {
-                        writeStatus(owner, admitted.id, {
-                            status: "running",
-                            reason: null,
-                            stoppedAt: null,
-                            revision: admitted.revision,
+                            writeStatus(owner, admitted.id, {
+                                status: "running",
+                                reason: null,
+                                stoppedAt: null,
+                                revision: admitted.revision,
+                            });
+                            refreshAttentionOwner(admitted.id);
                         });
-                        refreshAttentionOwner(admitted.id);
-                    });
-                },
-                catch: () => new ShiitakeError("store", "unavailable", "Extension status is unavailable"),
+                    },
+                    catch: () => new ShiitakeError("store", "unavailable", "Extension status is unavailable"),
+                });
+                yield* activateMember(member, scope, strict);
+                return member;
             });
-            yield* activateMember(member, scope);
+        }
+        for (const admitted of input.admitted) {
+            const member = yield* startMember(admitted, false).pipe(Effect.onError(() => Scope.close(scope, Exit.void)));
+            members.set(admitted.id, member);
         }
         yield* Effect.try({
             try: () => {
@@ -759,6 +789,70 @@ export function openExtensionRuntime(input) {
             catch: () => new ShiitakeError("store", "unavailable", "Attention grants are unavailable"),
         });
         const runtime = {
+            stage: (admitted) => Effect.gen(function* () {
+                const changed = admitted.filter((next) => {
+                    const previous = members.get(next.id);
+                    return (previous !== undefined &&
+                        previous.admitted.fingerprint !== next.fingerprint);
+                });
+                if (changed.length > 0)
+                    return yield* Effect.fail(new ShiitakeError("extensions", "rejected", `Extensions ${changed.map(({ id }) => id).join(", ")}: this change needs a restart: run fungi stop, then reopen fungi`));
+                const additions = new Map();
+                const discard = Effect.suspend(() => Effect.forEach([...additions.values()].reverse(), (member) => Effect.exit(member.scope === undefined
+                    ? Effect.void
+                    : Scope.close(member.scope, Exit.void)), { concurrency: 1 }).pipe(Effect.tap(() => Effect.sync(() => {
+                    for (const next of admitted)
+                        if (!members.has(next.id))
+                            incompatibleMigrations.delete(next.id);
+                })), Effect.flatMap(Exit.asVoidAll)));
+                yield* Effect.gen(function* () {
+                    for (const next of admitted)
+                        if (!members.has(next.id))
+                            additions.set(next.id, yield* startMember(next, true));
+                }).pipe(Effect.onError(() => discard));
+                const target = new Set(admitted.map(({ id }) => id));
+                let settled = false;
+                return {
+                    discard: Effect.suspend(() => {
+                        if (settled)
+                            return Effect.void;
+                        settled = true;
+                        return discard;
+                    }),
+                    apply: Effect.gen(function* () {
+                        if (settled)
+                            return yield* Effect.fail(new ShiitakeError("extensions", "rejected", "Roster transition already settled"));
+                        // Finish fallible store work atomically before releasing live
+                        // resources. A rolled-back publication must leave both the old
+                        // timers and the old member scopes available.
+                        yield* Effect.try({
+                            try: () => {
+                                owner.transactionSync(() => {
+                                    for (const [id, member] of members)
+                                        if (!target.has(member.admitted.id))
+                                            deleteExtensionTimers(owner, id);
+                                    const changed = replaceAttentionGrants(owner, admitted
+                                        .filter((entry) => entry.grants.has("attention"))
+                                        .map(({ id }) => id));
+                                    for (const id of changed)
+                                        refreshAttentionOwner(id);
+                                });
+                            },
+                            catch: () => new ShiitakeError("store", "unavailable", "Roster publication storage is unavailable"),
+                        });
+                        for (const [id, member] of members)
+                            if (!target.has(member.admitted.id)) {
+                                if (member.scope !== undefined)
+                                    yield* Scope.close(member.scope, Exit.void);
+                                members.delete(id);
+                                incompatibleMigrations.delete(member.admitted.id);
+                            }
+                        for (const [id, member] of additions)
+                            members.set(id, member);
+                        settled = true;
+                    }),
+                };
+            }),
             runParticipants: () => [...members.values()]
                 .filter(isRunParticipant)
                 .map((member) => [member.admitted.id, member.admitted.fingerprint]),
@@ -931,7 +1025,8 @@ export function openExtensionRuntime(input) {
                 if (member?.admitted.grants.has("commands") !== true)
                     return yield* Effect.fail(new ShiitakeError("extensions", "unavailable", "Extension is unavailable"));
                 if (member.status !== "running" || member.hooks === undefined)
-                    return yield* Effect.fail(new ShiitakeError("extensions", "unavailable", `Extension ${extensionId} is stopped: ${member.reason ?? "not activated"}`));
+                    return yield* Effect.fail(member.stateResetRequired ??
+                        new ShiitakeError("extensions", "unavailable", `Extension ${extensionId} is stopped: ${member.reason ?? "not activated"}`));
                 const commands = member.admitted.definition.contract.commands;
                 const spec = Object.hasOwn(commands, command)
                     ? commands[command]

package/dist/internal/host-meta.d.ts

@@ -31,6 +31,13 @@ export type StandardHostMetaResult = Readonly<{
  */
 export type HostMetaOptions = Readonly<{
     schema: Schema.Codec<unknown, Json> | StandardHostMetaSchema;
+    /**
+     * Host-selected SQLite JSON path to its stable principal identity.
+     * The host owns this metadata grammar. When bound metadata is present,
+     * pending lookup and exact cancellation stay within that identity.
+     * Unbound in-process owners retain operational cancellation authority.
+     */
+    identityPath?: string;
 }>;
 /**
  * Check one host-attached value: finite JSON within the cap, and accepted by

package/dist/internal/model-acquisition.js

@@ -14,7 +14,13 @@ function asEffectAcquisition(acquisition) {
         try: () => acquisition.release(),
         catch: releaseFailure,
     });
-    const shared = { model: acquisition.model, release };
+    let shared = {
+        model: acquisition.model,
+        release,
+        retryable: acquisition.retryable,
+    };
+    if (acquisition.failureReason !== undefined)
+        shared = { ...shared, failureReason: acquisition.failureReason };
     if (acquisition.stream === undefined)
         return acquisition.retryAfterMs === undefined
             ? Object.freeze(shared)

package/dist/internal/model-preference.d.ts

@@ -1,4 +1,6 @@
 import * as Schema from "effect/Schema";
+/** The thinking levels a model choice may name, shared by every model path. */
+export declare const reasoningLevels: readonly ["minimal", "low", "medium", "high", "xhigh", "max"];
 /** Secret-free request to the host's maintained model catalogue. */
 export declare const ModelPreferenceSchema: Schema.Struct<{
     readonly providerId: Schema.String;
@@ -11,11 +13,11 @@ export type ModelPreference = Schema.Schema.Type<typeof ModelPreferenceSchema>;
 export declare const parseModelPreference: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
     readonly providerId: string;
     readonly modelId: string;
-    readonly reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    readonly reasoning?: "high" | "low" | "max" | "medium" | "minimal" | "xhigh" | undefined;
 } | null;
 /** Decode the serialized preference with the same maintained schema. */
 export declare const parseModelPreferenceJson: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
     readonly providerId: string;
     readonly modelId: string;
-    readonly reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    readonly reasoning?: "high" | "low" | "max" | "medium" | "minimal" | "xhigh" | undefined;
 } | null;

package/dist/internal/model-preference.js

@@ -1,6 +1,7 @@
 import * as Schema from "effect/Schema";
 const identifier = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256)));
-const reasoningLevels = [
+/** The thinking levels a model choice may name, shared by every model path. */
+export const reasoningLevels = [
     "minimal",
     "low",
     "medium",

package/dist/internal/promise-facade.js

@@ -1,9 +1,8 @@
 import * as Effect from "effect/Effect";
 import * as Predicate from "effect/Predicate";
 import * as Schema from "effect/Schema";
-import { fromTypedSandbox } from "@fungi.computer/mycelium/effect";
 import { ShiitakeError } from "../errors.js";
-import { runShiitakePromise, toPromiseOwner } from "./effect-client.js";
+import { liftTools, runShiitakePromise, toPromiseOwner, } from "./effect-client.js";
 import { adaptModelSource } from "./model-acquisition.js";
 function boundary(boundaryName, message) {
     return new ShiitakeError(boundaryName, "rejected", message);
@@ -138,25 +137,14 @@ function liftOptions(options, runtime) {
     };
     if (options.meta !== undefined)
         Object.assign(base, { meta: options.meta });
-    if (options.storageBudget !== undefined)
-        Object.assign(base, { storageBudget: options.storageBudget });
+    if (options.storagePressure !== undefined)
+        Object.assign(base, { storagePressure: options.storagePressure });
     if (options.compaction !== undefined)
         Object.assign(base, { compaction: options.compaction });
     const toolSource = options.tools;
     if (toolSource === undefined)
         return base;
-    const tools = {
-        modules: toolSource.modules ?? [],
-        sources: toolSource.sources ?? [],
-        sandbox: fromTypedSandbox(toolSource.sandbox),
-        access: toolSource.access ?? {},
-    };
-    return {
-        ...base,
-        tools: toolSource.execution === undefined
-            ? tools
-            : { ...tools, execution: toolSource.execution },
-    };
+    return { ...base, tools: liftTools(toolSource) };
 }
 /** Open the single Promise adaptation over the canonical Effect agent. */
 export function openPromiseAgent(options, make) {

package/dist/internal/run-failure-reason.d.ts

@@ -0,0 +1,10 @@
+import type { MuleRunOutcome } from "@fungi.computer/mule/effect";
+/** Observations, not a classification of arbitrary provider error text. */
+export type UnavailableRunReason = Readonly<{
+    kind: "reason_unavailable";
+    runId: string;
+    provider: string | null;
+    model: string | null;
+}>;
+export declare function unavailableRunReason(observations: Omit<UnavailableRunReason, "kind">): string;
+export declare function returnedFailureReason(run: MuleRunOutcome): string;

package/dist/internal/run-failure-reason.js

@@ -0,0 +1,19 @@
+export function unavailableRunReason(observations) {
+    const reason = {
+        kind: "reason_unavailable",
+        ...observations,
+        provider: observations.provider === "" ? null : observations.provider,
+        model: observations.model === "" ? null : observations.model,
+    };
+    // Watchdog bounds reasons to 200 characters. Bound identity metadata only;
+    // truncation is not redaction and must never make provider prose trusted.
+    return `${reason.kind}: run=${reason.runId}; provider=${reason.provider ?? "unknown"}; model=${reason.model ?? "unknown"}`.slice(0, 200);
+}
+export function returnedFailureReason(run) {
+    // Pi errorMessage can contain raw SDK messages and response bodies.
+    return unavailableRunReason({
+        runId: run.run.value,
+        provider: run.message.provider,
+        model: run.message.model,
+    });
+}

package/dist/internal/run-scope.d.ts

@@ -18,7 +18,10 @@ export declare class ToolSetupError extends ShiitakeError {
     get diagnostic(): string;
 }
 /** Run one accepted command with Pi compaction explicitly composed around Mule. */
-export declare function runAcceptedCommand(options: ShiitakeEffectOptions, prepared: PreparedSessionRun, executionContract: RunContract, extensionModules: readonly ModuleRegistration[], extensionFileTools: readonly FileTool[], compactionHandoff: CompactionHandoffV0 | undefined, promptSections?: () => Effect.Effect<readonly PromptSectionV0[], ShiitakeError>): Effect.Effect<import("@fungi.computer/mule/effect").MuleRunOutcome, ShiitakeError, never>;
+export declare function runAcceptedCommand(options: ShiitakeEffectOptions, prepared: PreparedSessionRun, executionContract: RunContract, extensionModules: readonly ModuleRegistration[], extensionFileTools: readonly FileTool[], compactionHandoff: CompactionHandoffV0 | undefined, promptSections?: () => Effect.Effect<readonly PromptSectionV0[], ShiitakeError>): Effect.Effect<{
+    run: import("@fungi.computer/mule/effect").MuleRunOutcome;
+    failureReason: string | undefined;
+}, ShiitakeError, never>;
 /**
  * Run one accepted compaction request: the run's model acquisition and the
  * Session's one compaction commit, with no model turn and no tools.

package/dist/internal/run-scope.js

@@ -1,10 +1,14 @@
 import { muleEffect, piCodingAgentRetryDefaults, piHttpIdleTimeoutMs, } from "@fungi.computer/mule/effect";
 import { make as makeMycelium } from "@fungi.computer/mycelium/effect";
 import * as Effect from "effect/Effect";
+import * as Cause from "effect/Cause";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
 import { ShiitakeError } from "../errors.js";
 import { compactSession, runWithCompaction, } from "./compaction/session-compaction.js";
 import { openCompactionSettings } from "./compaction/settings.js";
 import { acquireOwnedModel } from "./model-acquisition.js";
+import { returnedFailureReason, unavailableRunReason, } from "./run-failure-reason.js";
 import { isCompactCommand, openMuleRecorder, readSessionGrants, recordLiveRetryEvent, recordSandboxFailure, takeSessionControls, } from "./woodstock/index.js";
 function runtimeFailure(message) {
     return new ShiitakeError("runtime", "rejected", message);
@@ -134,7 +138,8 @@ export function runAcceptedCommand(options, prepared, executionContract, extensi
         })));
         let resume = prepared.resume;
         const settings = openCompactionSettings(options.compaction)(acquired.model);
-        return yield* runWithCompaction({
+        let failureReason;
+        const run = yield* runWithCompaction({
             store: options.store,
             sessionId: prepared.command.sessionId,
             workId: prepared.command.entry.workId,
@@ -148,12 +153,23 @@ export function runAcceptedCommand(options, prepared, executionContract, extensi
             run: (workingMessages, betweenTurns) => {
                 const continuation = resume;
                 resume = undefined;
-                const listener = (event) => recorder(event);
+                // A failed lifecycle notification precedes Mule's returned outcome
+                // (or typed error). Join them before publishing the single terminal;
+                // no observer can win a race against a later diagnostic settlement.
+                let failedEnd;
+                const listener = (event) => {
+                    if (event.type === "run_end" && event.outcome === "failed") {
+                        failedEnd = event;
+                        return Effect.void;
+                    }
+                    return recorder(event);
+                };
                 const input = {
                     model: acquired.model,
                     modelStreamIdleTimeoutMs: options.modelStreamIdleTimeoutMs ?? piHttpIdleTimeoutMs,
                     retry: options.retry ?? piCodingAgentRetryDefaults,
                     retryAfterMs: acquired.retryAfterMs,
+                    retryable: acquired.retryable,
                     systemPrompt: instructions.text,
                     prepareSystemPrompt: () => (promptSections === undefined
                         ? Effect.succeed([])
@@ -181,11 +197,28 @@ export function runAcceptedCommand(options, prepared, executionContract, extensi
                     .run(acquired.stream === undefined
                     ? input
                     : { ...input, stream: acquired.stream }, listener)
-                    .pipe(Effect.mapError((error) => runtimeFailure(error.phase === "model"
-                    ? error.message
-                    : "Mule rejected the durable command run")));
+                    .pipe(Effect.onExit((exit) => {
+                    if (failedEnd === undefined)
+                        return Effect.void;
+                    if (Exit.isSuccess(exit)) {
+                        failureReason = (acquired.failureReason?.(exit.value.message) ??
+                            returnedFailureReason(exit.value)).slice(0, 200);
+                        return recorder(failedEnd, failureReason);
+                    }
+                    const error = Cause.findErrorOption(exit.cause);
+                    return recorder(failedEnd, Option.isSome(error) && error.value.phase === "model"
+                        ? `model:rejected: ${error.value.message}`.slice(0, 200)
+                        : unavailableRunReason({
+                            runId: failedEnd.run.value,
+                            provider: acquired.model.provider,
+                            model: acquired.model.id,
+                        }));
+                }), Effect.mapError((error) => error.phase === "model"
+                    ? new ShiitakeError("model", "rejected", error.message, undefined, error)
+                    : runtimeFailure("Mule rejected the durable command run")));
             },
         });
+        return { run, failureReason };
     }));
 }
 /**

package/dist/internal/runtime-coordinator.d.ts

@@ -5,11 +5,12 @@ import type { AgentRunningWork } from "../client.js";
 import { ShiitakeError } from "../errors.js";
 import { type AdmissionDoor } from "./admission-door.js";
 import type { ShiitakeEffectOptions } from "./effect-contracts.js";
-import type { AdmittedExtensionV0 } from "./extension-roster.js";
+import { type AdmittedExtensionV0 } from "./extension-roster.js";
 import { type ExtensionRuntime } from "./extension-runtime.js";
 import { type RecordAcceptedCancellation, type StorageAdmission } from "./woodstock/index.js";
 /** Bound lifecycle and owner-transaction doors used by the public coordinator. */
 export type RuntimeCoordinator = Readonly<{
+    prepareConfiguration: import("./effect-contracts.js").ShiitakeEffectOwner["prepareConfiguration"];
     activeSessions: Effect.Effect<readonly string[]>;
     runningWork: (jobId: string) => Effect.Effect<AgentRunningWork | null, ShiitakeError>;
     assertOpen: Effect.Effect<void, ShiitakeError>;