@zachwill/pi-orchestrate 0.2.1 → 0.4.0

package/extension/worker-session.ts

@@ -10,6 +10,7 @@ import {
   DefaultPackageManager,
   ModelRuntime,
   type ModelRegistry,
+  type PromptOptions,
   type ResourceLoader,
   SessionManager,
   SettingsManager,
@@ -18,7 +19,7 @@ import {
   type CreateAgentSessionResult,
   type DefaultResourceLoader,
 } from "@earendil-works/pi-coding-agent";
-import { Effect, Exit, Schema, Scope } from "effect";
+import { Cause, Effect, Exit, Schema, Scope } from "effect";
 import type {
   WorkerDefinition,
   WorkerMessageDirection,
@@ -27,13 +28,14 @@ import type {
 } from "./domain.js";
 
 const DIRECT_CHILD_BOUNDARY =
-  "You are a direct child worker session. Do not spawn, delegate to, or orchestrate other workers or child sessions. Complete the assigned task yourself and return the result directly to the parent orchestrator.";
+  "You are a direct child worker session. Do not spawn, delegate to, or orchestrate descendant Pi worker sessions. Complete the assigned task yourself and return the result directly to the parent orchestrator.";
 const ORCHESTRATE_PACKAGE_ROOT = canonicalPath(fileURLToPath(new URL("..", import.meta.url)));
 
 interface WorkerAgentSession {
   readonly sessionFile: string | undefined;
   readonly messages: AgentMessage[];
-  prompt(instructions: string): Promise<void>;
+  prompt(instructions: string, options?: PromptOptions): Promise<void>;
+  abortCompaction(): void;
   abort(): Promise<void>;
   dispose(): void;
   bindExtensions(bindings: { mode: "print" }): Promise<void>;
@@ -75,21 +77,66 @@ export interface WorkerSessionFactory {
   create(options: WorkerSessionFactoryOptions): Promise<WorkerSessionHandle>;
 }
 
+const WorkerModelAcquisitionOperation = Schema.Literals([
+  "select-model",
+  "create-model-runtime",
+  "register-providers",
+  "refresh-providers",
+  "resolve-model",
+  "authenticate-model",
+  "configure-runtime-auth",
+]);
+type WorkerModelAcquisitionOperation = typeof WorkerModelAcquisitionOperation.Type;
+
+const WorkerResourceAcquisitionOperation = Schema.Literals([
+  "create-settings",
+  "resolve-extensions",
+  "create-services",
+  "validate-skills",
+]);
+type WorkerResourceAcquisitionOperation = typeof WorkerResourceAcquisitionOperation.Type;
+
+const WorkerAgentSessionAcquisitionOperation = Schema.Literals([
+  "create-session-manager",
+  "create-session",
+  "create-runtime",
+  "bind-extensions",
+  "verify-durability",
+  "subscribe-events",
+]);
+type WorkerAgentSessionAcquisitionOperation = typeof WorkerAgentSessionAcquisitionOperation.Type;
+
 export class WorkerModelAcquisitionError extends Schema.TaggedErrorClass<WorkerModelAcquisitionError>()(
   "WorkerSession.ModelAcquisitionError",
-  { message: Schema.String, cause: Schema.Defect() },
+  { operation: WorkerModelAcquisitionOperation, message: Schema.String, cause: Schema.Defect() },
 ) {}
 
 export class WorkerResourceAcquisitionError extends Schema.TaggedErrorClass<WorkerResourceAcquisitionError>()(
   "WorkerSession.ResourceAcquisitionError",
-  { message: Schema.String, cause: Schema.Defect() },
+  { operation: WorkerResourceAcquisitionOperation, message: Schema.String, cause: Schema.Defect() },
 ) {}
 
 export class WorkerAgentSessionAcquisitionError extends Schema.TaggedErrorClass<WorkerAgentSessionAcquisitionError>()(
   "WorkerSession.AgentSessionAcquisitionError",
-  { message: Schema.String, cause: Schema.Defect() },
+  { operation: WorkerAgentSessionAcquisitionOperation, message: Schema.String, cause: Schema.Defect() },
 ) {}
 
+const WorkerSessionCleanupOperation = Schema.Literals([
+  "unsubscribe",
+  "runtime",
+  "raw-session",
+  "resource-loader",
+  "scope-close",
+]);
+export type WorkerSessionCleanupOperation = typeof WorkerSessionCleanupOperation.Type;
+
+export interface WorkerSessionCleanupFailure {
+  readonly operation: WorkerSessionCleanupOperation;
+  readonly cause: unknown;
+}
+
+export type WorkerSessionCleanupReporter = (failure: WorkerSessionCleanupFailure) => void;
+
 interface SettingsManagerInput {
   cwd: string;
   agentDir: string;
@@ -137,6 +184,7 @@ export interface WorkerSessionDependencies {
   createServices(input: ServicesInput): Promise<AgentSessionServices>;
   createAgentSession(input: AgentSessionInput): Promise<{ session: WorkerAgentSession }>;
   createRuntime(input: RuntimeInput): OwnedWorkerRuntime;
+  reportCleanupFailure(failure: WorkerSessionCleanupFailure): void;
 }
 
 const defaultDependencies: WorkerSessionDependencies = {
@@ -163,6 +211,12 @@ const defaultDependencies: WorkerSessionDependencies = {
         throw new Error("Worker sessions do not support runtime replacement");
       },
     ) as unknown as OwnedWorkerRuntime,
+  reportCleanupFailure: ({ operation }) => {
+    process.emitWarning("Worker session cleanup failed", {
+      code: "PI_ORCHESTRATE_WORKER_CLEANUP",
+      detail: `Operation: ${operation}`,
+    });
+  },
 };
 
 export function resolveWorkerModel(
@@ -204,11 +258,41 @@ export function isOrchestrationExtensionPath(path: string): boolean {
   return isWithin(canonicalPath(path), ORCHESTRATE_PACKAGE_ROOT);
 }
 
-function resourceLoaderFinalizer(resourceLoader: ResourceLoader): Effect.Effect<void> {
+function reportCleanupFailure(
+  reporter: WorkerSessionCleanupReporter,
+  operation: WorkerSessionCleanupOperation,
+  cause: unknown,
+): Effect.Effect<void> {
   return Effect.sync(() => {
+    try {
+      reporter({ operation, cause });
+    } catch {
+      // Reporting must never make best-effort cleanup fail.
+    }
+  });
+}
+
+function bestEffortCleanup(
+  reporter: WorkerSessionCleanupReporter,
+  operation: WorkerSessionCleanupOperation,
+  cleanup: () => void | Promise<void>,
+): Effect.Effect<void> {
+  return Effect.tryPromise({
+    try: async () => cleanup(),
+    catch: (cause) => cause,
+  }).pipe(
+    Effect.catch((cause) => reportCleanupFailure(reporter, operation, cause)),
+  );
+}
+
+function resourceLoaderFinalizer(
+  resourceLoader: ResourceLoader,
+  reporter: WorkerSessionCleanupReporter,
+): Effect.Effect<void> {
+  return bestEffortCleanup(reporter, "resource-loader", () => {
     if (!("dispose" in resourceLoader) || typeof resourceLoader.dispose !== "function") return;
     resourceLoader.dispose();
-  }).pipe(Effect.ignoreCause);
+  });
 }
 
 function describeError(error: unknown, fallback: string): string {
@@ -267,6 +351,7 @@ class DefaultWorkerSessionHandle implements WorkerSessionHandle {
     private readonly reusable: boolean,
     sessionFile: string,
     private readonly scope: Scope.Closeable,
+    private readonly cleanupReporter: WorkerSessionCleanupReporter,
   ) {
     this.sessionFile = sessionFile;
   }
@@ -323,7 +408,10 @@ class DefaultWorkerSessionHandle implements WorkerSessionHandle {
     const previousAssistant = lastAssistant(this.runtime.session.messages);
     let failureMessage: string | undefined;
     try {
-      await this.runtime.session.prompt(instructions);
+      await this.runtime.session.prompt(instructions, {
+        expandPromptTemplates: false,
+        source: "extension",
+      });
     } catch (error) {
       failureMessage = describeError(error, "Worker prompt failed");
     } finally {
@@ -346,7 +434,21 @@ class DefaultWorkerSessionHandle implements WorkerSessionHandle {
 
   async abort(): Promise<void> {
     if (this.prompting) this.abortRequested = true;
-    await this.runtime.session.abort();
+
+    let firstFailure: unknown;
+    try {
+      this.runtime.session.abortCompaction();
+    } catch (error) {
+      firstFailure = error;
+    }
+
+    try {
+      await this.runtime.session.abort();
+    } catch (error) {
+      if (firstFailure === undefined) firstFailure = error;
+    }
+
+    if (firstFailure !== undefined) throw firstFailure;
   }
 
   dispose(): Promise<void> {
@@ -357,7 +459,9 @@ class DefaultWorkerSessionHandle implements WorkerSessionHandle {
     this.usageListeners.clear();
     this.activityListeners.clear();
     this.messageDirectionListeners.clear();
-    this.disposePromise = Effect.runPromise(disposeWorkerSession(this.scope));
+    this.disposePromise = Effect.runPromise(
+      disposeWorkerSession(this.scope, this.cleanupReporter),
+    );
     return this.disposePromise;
   }
 
@@ -395,19 +499,32 @@ function selectedModelCoordinates(
   throw new Error(`Worker "${definition.name}" has no configured model and no parent model is available`);
 }
 
-function modelAcquisitionError(cause: unknown, fallback: string): WorkerModelAcquisitionError {
-  return new WorkerModelAcquisitionError({ message: describeError(cause, fallback), cause });
+function modelAcquisitionError(
+  operation: WorkerModelAcquisitionOperation,
+  fallback: string,
+): (cause: unknown) => WorkerModelAcquisitionError {
+  return (cause) => new WorkerModelAcquisitionError({
+    operation,
+    message: describeError(cause, fallback),
+    cause,
+  });
 }
 
-function resourceAcquisitionError(cause: unknown): WorkerResourceAcquisitionError {
-  return new WorkerResourceAcquisitionError({
+function resourceAcquisitionError(
+  operation: WorkerResourceAcquisitionOperation,
+): (cause: unknown) => WorkerResourceAcquisitionError {
+  return (cause) => new WorkerResourceAcquisitionError({
+    operation,
     message: describeError(cause, "Worker resource acquisition failed"),
     cause,
   });
 }
 
-function agentSessionAcquisitionError(cause: unknown): WorkerAgentSessionAcquisitionError {
-  return new WorkerAgentSessionAcquisitionError({
+function agentSessionAcquisitionError(
+  operation: WorkerAgentSessionAcquisitionOperation,
+): (cause: unknown) => WorkerAgentSessionAcquisitionError {
+  return (cause) => new WorkerAgentSessionAcquisitionError({
+    operation,
     message: describeError(cause, "Worker agent session acquisition failed"),
     cause,
   });
@@ -417,20 +534,24 @@ const refreshModelRuntime = Effect.fn("WorkerSession.refreshModelRuntime")(funct
   modelRuntime: ModelRuntime,
   definition: WorkerDefinition,
 ) {
+  const refreshError = modelAcquisitionError(
+    "refresh-providers",
+    "Worker model refresh failed",
+  );
   const result = yield* Effect.tryPromise({
     try: () => modelRuntime.refresh({ allowNetwork: false }),
-    catch: (cause) => modelAcquisitionError(cause, "Worker model refresh failed"),
+    catch: refreshError,
   });
   if (result.errors.size > 0) {
     const errors = [...result.errors].map(([id, error]) => `${id}: ${error.message}`).join("; ");
     const cause = new Error(
       `Worker "${definition.name}" failed to refresh child model providers: ${errors}`,
     );
-    return yield* Effect.fail(modelAcquisitionError(cause, "Worker model refresh failed"));
+    return yield* Effect.fail(refreshError(cause));
   }
   if (result.aborted) {
     const cause = new Error(`Worker "${definition.name}" child model refresh was aborted`);
-    return yield* Effect.fail(modelAcquisitionError(cause, "Worker model refresh failed"));
+    return yield* Effect.fail(refreshError(cause));
   }
 });
 
@@ -440,14 +561,14 @@ const prepareChildModelRuntime = Effect.fn("WorkerSession.prepareChildModelRunti
 ) {
   const selected = yield* Effect.try({
     try: () => selectedModelCoordinates(options.definition, options.parentModel),
-    catch: (cause) => modelAcquisitionError(cause, "Worker model selection failed"),
+    catch: modelAcquisitionError("select-model", "Worker model selection failed"),
   });
   const modelRuntime = yield* Effect.tryPromise({
     try: () => dependencies.createModelRuntime({
       authPath: join(options.agentDir, "auth.json"),
       modelsPath: join(options.agentDir, "models.json"),
     }),
-    catch: (cause) => modelAcquisitionError(cause, "Worker model runtime creation failed"),
+    catch: modelAcquisitionError("create-model-runtime", "Worker model runtime creation failed"),
   });
 
   yield* Effect.try({
@@ -457,18 +578,20 @@ const prepareChildModelRuntime = Effect.fn("WorkerSession.prepareChildModelRunti
         if (config) modelRuntime.registerProvider(providerId, { ...config });
       }
     },
-    catch: (cause) => modelAcquisitionError(cause, "Worker model provider registration failed"),
+    catch: modelAcquisitionError("register-providers", "Worker model provider registration failed"),
   });
+  // Worker-session owns this pre-service refresh so dynamic parent providers exist
+  // before selected-model authentication is copied.
   yield* refreshModelRuntime(modelRuntime, options.definition);
 
   const model = yield* Effect.try({
     try: () => modelRuntime.getModel(selected.provider, selected.modelId),
-    catch: (cause) => modelAcquisitionError(cause, "Worker model resolution failed"),
+    catch: modelAcquisitionError("resolve-model", "Worker model resolution failed"),
   });
   if (model) {
     const auth = yield* Effect.tryPromise({
       try: () => options.modelRegistry.getApiKeyAndHeaders(model),
-      catch: (cause) => modelAcquisitionError(cause, "Worker model authentication failed"),
+      catch: modelAcquisitionError("authenticate-model", "Worker model authentication failed"),
     });
     if (auth.ok) {
       yield* Effect.tryPromise({
@@ -480,7 +603,7 @@ const prepareChildModelRuntime = Effect.fn("WorkerSession.prepareChildModelRunti
             await modelRuntime.setRuntimeApiKey(selected.provider, auth.apiKey);
           }
         },
-        catch: (cause) => modelAcquisitionError(cause, "Worker model runtime key setup failed"),
+        catch: modelAcquisitionError("configure-runtime-auth", "Worker model runtime key setup failed"),
       });
     }
   }
@@ -515,8 +638,13 @@ function contextLoaderOptions(
 
 const disposeWorkerSession = Effect.fn("WorkerSession.dispose")(function* (
   scope: Scope.Closeable,
+  reporter: WorkerSessionCleanupReporter,
 ) {
-  yield* Scope.close(scope, Exit.void).pipe(Effect.ignoreCause);
+  yield* Scope.close(scope, Exit.void).pipe(
+    Effect.catchCause((cause) =>
+      reportCleanupFailure(reporter, "scope-close", Cause.squash(cause))
+    ),
+  );
 });
 
 const acquireWorkerServices = Effect.fn("WorkerSession.acquireServices")(function* (
@@ -532,7 +660,7 @@ const acquireWorkerServices = Effect.fn("WorkerSession.acquireServices")(functio
       projectTrusted: options.projectTrusted,
       compaction: definition.compaction,
     }),
-    catch: resourceAcquisitionError,
+    catch: resourceAcquisitionError("create-settings"),
   });
   const extensionPaths = yield* Effect.tryPromise({
     try: () => dependencies.resolveExtensionPaths({
@@ -540,7 +668,7 @@ const acquireWorkerServices = Effect.fn("WorkerSession.acquireServices")(functio
       agentDir: options.agentDir,
       settingsManager,
     }),
-    catch: resourceAcquisitionError,
+    catch: resourceAcquisitionError("resolve-extensions"),
   }).pipe(Effect.map((paths) => paths.filter((path) => !isOrchestrationExtensionPath(path))));
 
   return yield* Effect.acquireRelease(
@@ -562,9 +690,12 @@ const acquireWorkerServices = Effect.fn("WorkerSession.acquireServices")(functio
           appendSystemPrompt: [definition.systemPrompt, DIRECT_CHILD_BOUNDARY],
         },
       }),
-      catch: resourceAcquisitionError,
+      catch: resourceAcquisitionError("create-services"),
     }),
-    (services) => resourceLoaderFinalizer(services.resourceLoader),
+    (services) => resourceLoaderFinalizer(
+      services.resourceLoader,
+      dependencies.reportCleanupFailure,
+    ),
   );
 });
 
@@ -573,16 +704,28 @@ interface AgentSessionOwnership {
   runtime: OwnedWorkerRuntime | undefined;
 }
 
-function rawSessionFinalizer(session: WorkerAgentSession): Effect.Effect<void> {
-  return Effect.sync(() => session.dispose()).pipe(Effect.ignoreCause);
+function rawSessionFinalizer(
+  session: WorkerAgentSession,
+  reporter: WorkerSessionCleanupReporter,
+): Effect.Effect<void> {
+  return bestEffortCleanup(reporter, "raw-session", () => session.dispose());
 }
 
-function agentSessionFinalizer(ownership: AgentSessionOwnership): Effect.Effect<void> {
+function agentSessionFinalizer(
+  ownership: AgentSessionOwnership,
+  reporter: WorkerSessionCleanupReporter,
+): Effect.Effect<void> {
   const runtime = ownership.runtime;
-  if (!runtime) return rawSessionFinalizer(ownership.session);
-  return Effect.tryPromise(() => runtime.dispose()).pipe(
-    Effect.catch(() => rawSessionFinalizer(ownership.session)),
-    Effect.ignoreCause,
+  if (!runtime) return rawSessionFinalizer(ownership.session, reporter);
+  return Effect.tryPromise({
+    try: () => runtime.dispose(),
+    catch: (cause) => cause,
+  }).pipe(
+    Effect.catch((cause) =>
+      reportCleanupFailure(reporter, "runtime", cause).pipe(
+        Effect.andThen(rawSessionFinalizer(ownership.session, reporter)),
+      )
+    ),
   );
 }
 
@@ -593,12 +736,15 @@ const acquireAgentSession = Effect.fn("WorkerSession.acquireAgentSession")(funct
   return yield* Effect.acquireRelease(
     Effect.tryPromise({
       try: () => dependencies.createAgentSession(input),
-      catch: agentSessionAcquisitionError,
+      catch: agentSessionAcquisitionError("create-session"),
     }).pipe(Effect.map(({ session }) => {
       const ownership: AgentSessionOwnership = { session, runtime: undefined };
       return ownership;
     })),
-    agentSessionFinalizer,
+    (ownership) => agentSessionFinalizer(
+      ownership,
+      dependencies.reportCleanupFailure,
+    ),
   );
 });
 
@@ -609,22 +755,27 @@ const acquireAgentSessionRuntime = Effect.fn("WorkerSession.acquireAgentSessionR
 ) {
   const runtime = yield* Effect.try({
     try: () => dependencies.createRuntime({ session: ownership.session, services }),
-    catch: agentSessionAcquisitionError,
+    catch: agentSessionAcquisitionError("create-runtime"),
   });
   ownership.runtime = runtime;
   return runtime;
 });
 
 const acquireSessionSubscription = Effect.fn("WorkerSession.acquireSubscription")(function* (
+  dependencies: WorkerSessionDependencies,
   runtime: OwnedWorkerRuntime,
   handle: DefaultWorkerSessionHandle,
 ) {
   return yield* Effect.acquireRelease(
     Effect.try({
       try: () => runtime.session.subscribe((event) => handle.receiveSessionEvent(event)),
-      catch: agentSessionAcquisitionError,
+      catch: agentSessionAcquisitionError("subscribe-events"),
     }),
-    (unsubscribe) => Effect.sync(unsubscribe).pipe(Effect.ignoreCause),
+    (unsubscribe) => bestEffortCleanup(
+      dependencies.reportCleanupFailure,
+      "unsubscribe",
+      unsubscribe,
+    ),
   );
 });
 
@@ -638,6 +789,9 @@ const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
     const { selected, modelRuntime } = yield* prepareChildModelRuntime(options, dependencies);
     const services = yield* acquireWorkerServices(options, dependencies, modelRuntime);
 
+    // createAgentSessionServices owns extension-provider registration and refresh, but
+    // Pi 0.80.10 discards that refresh result. Keep this worker-owned probe so provider
+    // errors and aborts remain typed acquisition failures before session creation.
     yield* refreshModelRuntime(modelRuntime, definition);
     const model = yield* Effect.try({
       try: () => {
@@ -649,14 +803,14 @@ const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
         }
         return resolvedModel;
       },
-      catch: (cause) => modelAcquisitionError(cause, "Worker model resolution failed"),
+      catch: modelAcquisitionError("resolve-model", "Worker model resolution failed"),
     });
     const sessionManager = yield* Effect.try({
       try: () => dependencies.createSessionManager({
         cwd: options.cwd,
         parentSessionFile: options.parentSessionFile,
       }),
-      catch: agentSessionAcquisitionError,
+      catch: agentSessionAcquisitionError("create-session-manager"),
     });
     const ownership = yield* acquireAgentSession(dependencies, {
       services,
@@ -668,7 +822,7 @@ const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
     const runtime = yield* acquireAgentSessionRuntime(dependencies, ownership, services);
     yield* Effect.tryPromise({
       try: () => runtime.session.bindExtensions({ mode: "print" }),
-      catch: agentSessionAcquisitionError,
+      catch: agentSessionAcquisitionError("bind-extensions"),
     });
 
     yield* Effect.try({
@@ -684,7 +838,7 @@ const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
           );
         }
       },
-      catch: resourceAcquisitionError,
+      catch: resourceAcquisitionError("validate-skills"),
     });
     const sessionFile = yield* Effect.try({
       try: () => {
@@ -693,7 +847,7 @@ const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
         }
         return runtime.session.sessionFile;
       },
-      catch: agentSessionAcquisitionError,
+      catch: agentSessionAcquisitionError("verify-durability"),
     });
 
     const handle = new DefaultWorkerSessionHandle(
@@ -701,15 +855,24 @@ const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
       definition.lifecycle === "reusable",
       sessionFile,
       scope,
+      dependencies.reportCleanupFailure,
     );
-    yield* acquireSessionSubscription(runtime, handle);
+    yield* acquireSessionSubscription(dependencies, runtime, handle);
     return handle;
   }).pipe(Scope.provide(scope));
 
   return yield* acquisition.pipe(
     Effect.catchCause((cause) =>
       Effect.gen(function* () {
-        yield* Scope.close(scope, Exit.failCause(cause)).pipe(Effect.ignoreCause);
+        yield* Scope.close(scope, Exit.failCause(cause)).pipe(
+          Effect.catchCause((cleanupCause) =>
+            reportCleanupFailure(
+              dependencies.reportCleanupFailure,
+              "scope-close",
+              Cause.squash(cleanupCause),
+            )
+          ),
+        );
         return yield* Effect.failCause(cause);
       })
     ),

package/extension/worker-settlement.ts

@@ -0,0 +1,106 @@
+import { Schema } from "effect";
+import type { RunId, WorkerId } from "./domain.js";
+
+const NonnegativeFinite = Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0));
+const NonnegativeInteger = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+
+const WorkerUsage = Schema.Struct({
+  input: NonnegativeFinite,
+  output: NonnegativeFinite,
+  cacheRead: NonnegativeFinite,
+  cacheWrite: NonnegativeFinite,
+  cost: NonnegativeFinite,
+  contextTokens: NonnegativeFinite,
+  turns: NonnegativeInteger,
+});
+
+const WorkerOutcome = Schema.Union([
+  Schema.Struct({
+    status: Schema.Literal("completed"),
+    assistantText: Schema.String,
+  }),
+  Schema.Struct({
+    status: Schema.Literal("ready"),
+    assistantText: Schema.String,
+  }),
+  Schema.Struct({
+    status: Schema.Literal("failed"),
+    message: Schema.String,
+    assistantText: Schema.optionalKey(Schema.String),
+  }),
+  Schema.Struct({
+    status: Schema.Literal("aborted"),
+    message: Schema.optionalKey(Schema.String),
+    assistantText: Schema.optionalKey(Schema.String),
+  }),
+]);
+
+const FailureStage = Schema.Literals([
+  "startup",
+  "prompt",
+  "workflow",
+  "cancellation",
+]);
+
+/** Canonical schema for settlement details written by the current runtime. */
+export const WorkerSettlementDetails = Schema.Struct({
+  eventId: Schema.String,
+  sequence: NonnegativeInteger,
+  ownerSessionId: Schema.String,
+  runId: Schema.String,
+  workerId: Schema.String,
+  generation: NonnegativeInteger,
+  mode: Schema.Literals(["async", "inline"]),
+  worker: Schema.String,
+  title: Schema.String,
+  lifecycle: Schema.Literals(["one-shot", "reusable"]),
+  status: Schema.Literals(["completed", "ready", "failed", "aborted"]),
+  outcome: WorkerOutcome,
+  usage: WorkerUsage,
+  startedAt: NonnegativeInteger,
+  settledAt: NonnegativeInteger,
+  synthesisGroupId: Schema.optionalKey(Schema.String),
+  synthesisGroupSize: Schema.optionalKey(NonnegativeInteger),
+  sessionFile: Schema.optionalKey(Schema.String),
+  failureStage: Schema.optionalKey(FailureStage),
+}).check(
+  Schema.makeFilter((settlement) => {
+    if (settlement.outcome.status !== settlement.status) {
+      return "outcome status must match settlement status";
+    }
+    if (settlement.settledAt < settlement.startedAt) {
+      return "settlement timestamp must not precede start timestamp";
+    }
+    if (
+      settlement.failureStage !== undefined &&
+      settlement.status !== "failed" &&
+      settlement.status !== "aborted"
+    ) {
+      return "failure stage requires a failed or aborted settlement";
+    }
+  }),
+);
+
+export interface WorkerSettlementDetails
+  extends Schema.Schema.Type<typeof WorkerSettlementDetails> {}
+
+export type SettlementFailureStage = NonNullable<
+  WorkerSettlementDetails["failureStage"]
+>;
+
+/** Runtime refinement preserves the nominal IDs already allocated by the domain. */
+export type WorkerSettlement = Omit<
+  WorkerSettlementDetails,
+  "runId" | "workerId"
+> & {
+  readonly runId: RunId;
+  readonly workerId: WorkerId;
+};
+
+const decodeCurrentWorkerSettlement = Schema.decodeUnknownResult(
+  WorkerSettlementDetails,
+);
+
+export function decodePersistedWorkerSettlementDetails(value: unknown) {
+  return decodeCurrentWorkerSettlement(value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zachwill/pi-orchestrate",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Concurrent worker orchestration for Pi",
   "files": ["extension/", "examples/", "README.md", "LICENSE"],