@astrosheep/keiyaku 4.5.19 → 4.5.21

package/build/src/library/contract-execution.js

@@ -26,7 +26,7 @@ function retainTrailingFailure(context, operation, error) {
 }
 /** The channel's own retirement cannot hide an already returned admission. */
 export async function withContractExecution(input, operation, run) {
-    const progress = new ExecutionProgress();
+    const progress = new ExecutionProgress(input.observe);
     const scope = withScopeAbortSignal(input.scope, input.signal);
     let produced;
     try {
@@ -71,6 +71,13 @@ async function advanceAndContinue(context, checkpoint, start) {
         ...(context.actor === undefined ? {} : { actor: context.actor }),
         ...(context.signal === undefined ? {} : { signal: context.signal }),
     });
+    if (result.kind === "completed")
+        context.progress.observe({
+            kind: "stage",
+            contractId: context.contractId,
+            stage: "continuation",
+            state: "started",
+        });
     const continuation = result.kind !== "completed"
         ? undefined
         : await continueDeliveredDependents({
@@ -78,6 +85,13 @@ async function advanceAndContinue(context, checkpoint, start) {
             completed: result,
             deriveDocument: derivedDocument,
         });
+    if (result.kind === "completed")
+        context.progress.observe({
+            kind: "stage",
+            contractId: context.contractId,
+            stage: "continuation",
+            state: "finished",
+        });
     return { ...result.evidence, ...(continuation === undefined ? {} : { continuation }) };
 }
 /** Review records testimony, then the same shared node judges automatic placement. */

package/build/src/library/contract-forwarding.d.ts

@@ -1,4 +1,5 @@
 import type { ActorId, ContractId } from "../core/facts/types.js";
+import type { ExecutionObserver } from "../protocol/execution-observation.js";
 import type { IntegrationConflictMaterialized } from "../protocol/deliver.js";
 import type { AuditReport } from "../protocol/audit.js";
 import { type AuditComposition } from "./audit.js";
@@ -20,6 +21,7 @@ export declare function executeForwardedDeliver(input: Readonly<{
     requireBranchesToBeUpToDate: boolean;
     hooks: Parameters<typeof executeLocalDelivery>[0]["hooks"];
     signal?: AbortSignal;
+    observe?: ExecutionObserver;
 }>): Promise<Readonly<{
     result: MutationResult<DeliveryValue> | IntegrationConflictMaterialized;
     deliveryFactId?: string;
@@ -32,6 +34,7 @@ export declare function executeForwardedReview(input: Readonly<{
     summary?: string;
     signal?: AbortSignal;
     hooks: Parameters<typeof executeLocalReview>[0]["hooks"];
+    observe?: ExecutionObserver;
 }>): Promise<Readonly<{
     result: MutationResult<Review>;
     reviewFactId?: string;
@@ -45,6 +48,7 @@ export declare function executeForwardedAudit(input: Readonly<{
     requireBranchesToBeUpToDate: boolean;
     hooks: NonNullable<AuditComposition["hooks"]>;
     signal?: AbortSignal;
+    observe?: ExecutionObserver;
 }>): Promise<Readonly<{
     result: MutationResult<AuditReport>;
     auditReport?: AuditReport;

package/build/src/library/contract-forwarding.js

@@ -16,6 +16,7 @@ export async function executeForwardedDeliver(input) {
         overwrite: input.overwrite ?? false,
         ...(input.signal === undefined ? {} : { signal: input.signal }),
         hooks: input.hooks,
+        ...(input.observe === undefined ? {} : { observe: input.observe }),
     });
     if (result.kind !== "accepted")
         return { result };
@@ -38,6 +39,7 @@ export async function executeForwardedReview(input) {
         verdict: input.verdict,
         ...(input.summary === undefined ? {} : { summary: input.summary }),
         hooks: input.hooks,
+        ...(input.observe === undefined ? {} : { observe: input.observe }),
         ...(input.signal === undefined ? {} : { signal: input.signal }),
     });
     const review = result.facts.find((fact) => fact.kind === "attestation");
@@ -49,6 +51,7 @@ export async function executeForwardedAudit(input) {
     const result = await auditContract({
         scope: scopeForRepo(input.repo),
         contractId: input.contractId,
+        ...(input.observe === undefined ? {} : { observe: input.observe }),
         input: {
             includeDirty: input.includeDirty,
             showDiff: input.showDiff,

package/build/src/library/contract-handle.d.ts

@@ -1,3 +1,4 @@
+import { type ContractExecution } from "./execution.js";
 import { type ContractId, type ContractState } from "../core/facts/types.js";
 import { type RepositoryScope } from "../protocol/operations.js";
 import type { AuditReport } from "../protocol/audit.js";
@@ -22,11 +23,17 @@ export declare class KeiyakuHandle {
     guidance(): Promise<string>;
     delivery(): Promise<Delivery | null>;
     amend(input: AmendInput): Promise<AmendResult>;
+    startDelivery(input?: DeliverInput): ContractExecution<MutationResult<Delivery> | IntegrationConflictMaterialized>;
     deliver(input?: DeliverInput): Promise<MutationResult<Delivery> | IntegrationConflictMaterialized>;
+    private runDelivery;
+    startReview(input: ReviewInput): ContractExecution<MutationResult<Review>>;
     review(input: ReviewInput): Promise<MutationResult<Review>>;
+    private runReview;
     abandon(input?: AbandonInput): Promise<MutationResult<void>>;
     arc(input: ArcInput): Promise<MutationResult<void>>;
+    startAudit(input?: AuditInput): ContractExecution<MutationResult<AuditReport>>;
     audit(input?: AuditInput): Promise<MutationResult<AuditReport>>;
+    private runAudit;
     reconcile(input?: ReconcileInput): Promise<ReconcileReport>;
     private deliveryHandle;
 }

package/build/src/library/contract-handle.js

@@ -1,5 +1,6 @@
 /** @architectureCompositionRoot */
 import { documentDiff } from "../markdown/diff.js";
+import { startContractExecution } from "./execution.js";
 import { applyAmendDocument } from "../body/amend.js";
 import { decodeArcDocument } from "../body/arc.js";
 import { decodeContractDocument } from "../body/decode.js";
@@ -156,7 +157,13 @@ export class KeiyakuHandle {
             ...regionObservation,
         };
     }
+    startDelivery(input) {
+        return startContractExecution((observe) => this.runDelivery(input, observe));
+    }
     async deliver(input) {
+        return this.startDelivery(input).result;
+    }
+    async runDelivery(input, observe) {
         const values = input === undefined
             ? undefined
             : requireInput(input, "deliver input", [
@@ -184,10 +191,12 @@ export class KeiyakuHandle {
                 overwrite,
                 ...(signal === undefined ? {} : { signal }),
                 hooks: this.composition.hooks,
+                observe,
             })
             : await requestForwardedContractLive({
                 directory: channel.directory,
                 action: "contract.deliver",
+                observe,
                 request: {
                     action: "contract.deliver",
                     repoRoot: this.scope.primaryWorktree,
@@ -201,7 +210,13 @@ export class KeiyakuHandle {
             });
         return "facts" in result ? { ...result, value: this.deliveryHandle(result.value) } : result;
     }
+    startReview(input) {
+        return startContractExecution((observe) => this.runReview(input, observe));
+    }
     async review(input) {
+        return this.startReview(input).result;
+    }
+    async runReview(input, observe) {
         const values = requireInput(input, "review input", ["verdict", "summary", "signal"]);
         const verdict = values.verdict;
         if (verdict !== "satisfied" && verdict !== "unsatisfied") {
@@ -214,6 +229,7 @@ export class KeiyakuHandle {
             return await requestForwardedContractLive({
                 directory: channel.directory,
                 action: "contract.review",
+                observe,
                 ...(signal === undefined ? {} : { signal }),
                 request: {
                     action: "contract.review",
@@ -231,6 +247,7 @@ export class KeiyakuHandle {
             verdict,
             ...(summary === undefined ? {} : { summary }),
             hooks: this.composition.hooks,
+            observe,
             ...(signal === undefined ? {} : { signal }),
         });
     }
@@ -290,7 +307,13 @@ export class KeiyakuHandle {
             });
         });
     }
+    startAudit(input) {
+        return startContractExecution((observe) => this.runAudit(input, observe));
+    }
     async audit(input) {
+        return this.startAudit(input).result;
+    }
+    async runAudit(input, observe) {
         const values = input === undefined ? undefined : requireInput(input, "audit input", ["includeDirty", "showDiff", "signal"]);
         const includeDirty = optionalBoolean(values?.includeDirty, "includeDirty") ?? false;
         const showDiff = optionalBoolean(values?.showDiff, "showDiff") ?? false;
@@ -305,6 +328,7 @@ export class KeiyakuHandle {
             return await requestForwardedContractLive({
                 directory: channel.directory,
                 action: "contract.audit",
+                observe,
                 request: {
                     action: "contract.audit",
                     repoRoot: this.scope.primaryWorktree,
@@ -320,6 +344,7 @@ export class KeiyakuHandle {
             contractId: this.id,
             input: auditInput,
             composition: this.composition,
+            observe,
         });
     }
     async reconcile(input) {

package/build/src/library/contract-operations.d.ts

@@ -1,3 +1,4 @@
+import { type ExecutionObserver } from "../protocol/execution-observation.js";
 import { type ErasedRequestCommand, type RequestProtocol, type ServiceRequestCommand } from "../akuma/request-wire.js";
 import type { AuditReport } from "../protocol/audit.js";
 import type { IntegrationConflictMaterialized } from "../protocol/deliver.js";
@@ -90,7 +91,7 @@ declare const materializedHandoffReferenceSchema: z.ZodObject<{
     handoffBase: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>;
     recovery: z.ZodObject<{
         materialize: z.ZodLiteral<"deliver --materialize-conflict --include-dirty">;
-        continue: z.ZodLiteral<"deliver --include-dirty">;
+        deliver: z.ZodLiteral<"deliver --include-dirty">;
         staging: z.ZodLiteral<"not-required">;
     }, z.core.$strict>;
     conflictPaths: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<readonly string[], string[]>>;
@@ -215,7 +216,7 @@ declare const contractServiceSchema: z.ZodUnion<readonly [z.ZodObject<{
     handoffBase: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>;
     recovery: z.ZodObject<{
         materialize: z.ZodLiteral<"deliver --materialize-conflict --include-dirty">;
-        continue: z.ZodLiteral<"deliver --include-dirty">;
+        deliver: z.ZodLiteral<"deliver --include-dirty">;
         staging: z.ZodLiteral<"not-required">;
     }, z.core.$strict>;
     conflictPaths: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<readonly string[], string[]>>;
@@ -235,6 +236,7 @@ export type ContractRequestPort = Readonly<{
     audit(input: AuditRequest & Readonly<{
         requester: ContractRequester;
         signal: AbortSignal;
+        observe?: ExecutionObserver;
     }>): Promise<Readonly<{
         result: AuditResult;
         auditReport?: AuditReport;
@@ -242,6 +244,7 @@ export type ContractRequestPort = Readonly<{
     deliver(input: DeliverRequest & Readonly<{
         requester: ContractRequester;
         signal: AbortSignal;
+        observe?: ExecutionObserver;
     }>): Promise<Readonly<{
         result: DeliveryResult;
         deliveryFactId?: string;
@@ -249,6 +252,7 @@ export type ContractRequestPort = Readonly<{
     review(input: ReviewRequest & Readonly<{
         requester: ContractRequester;
         signal: AbortSignal;
+        observe?: ExecutionObserver;
     }>): Promise<Readonly<{
         result: ReviewResult;
         reviewFactId?: string;
@@ -262,6 +266,7 @@ export declare function requestForwardedContractLive<Action extends ContractRequ
     action: Action;
     request: ContractRequestFor<Action>;
     signal?: AbortSignal;
+    observe?: ExecutionObserver;
 }>): Promise<ContractResultFor<Action>>;
 export { executeLocalDelivery, executeLocalReview, executeForwardedAudit, executeForwardedDeliver, executeForwardedReview, } from "./contract-forwarding.js";
 export type { AttestationVerdict, DeliveryExecutionInput, Review, ReviewExecutionInput, } from "./contract-forwarding.js";

package/build/src/library/contract-operations.js

@@ -1,4 +1,5 @@
 import { executionReceipt } from "./execution-result.js";
+import { decodeExecutionEvent, observeExecution } from "../protocol/execution-observation.js";
 import { contractId, snapshotId } from "../core/facts/types.js";
 import { AkumaBodyRequestError, requestBodyCommand } from "../akuma/request-rendezvous.js";
 import { eraseRequestCommand, } from "../akuma/request-wire.js";
@@ -30,7 +31,7 @@ const contractRequestBaseSchema = z.object({ repoRoot: absolutePathSchema, contr
 const conflictRecoverySchema = z
     .object({
     materialize: z.literal("deliver --materialize-conflict --include-dirty"),
-    continue: z.literal("deliver --include-dirty"),
+    deliver: z.literal("deliver --include-dirty"),
     staging: z.literal("not-required"),
 })
     .strict();
@@ -138,10 +139,17 @@ function decodeContractReference(action, value) {
         throw new Error(`malformed stored Contract service evidence for ${action}`);
     return parsed.data;
 }
+function executionObservation(facts) {
+    if (facts.progress === undefined)
+        return {};
+    return { observe: (event) => facts.progress?.(event) };
+}
 async function executeContractRequest(request, facts, port) {
+    const observation = executionObservation(facts);
     if (request.action === "contract.audit") {
         const served = await port.audit({
             ...request,
+            ...observation,
             requester: facts.requester,
             signal: facts.signal,
         });
@@ -160,6 +168,7 @@ async function executeContractRequest(request, facts, port) {
     if (request.action === "contract.deliver") {
         const served = await port.deliver({
             ...request,
+            ...observation,
             overwrite: request.overwrite ?? false,
             requester: facts.requester,
             signal: facts.signal,
@@ -193,6 +202,7 @@ async function executeContractRequest(request, facts, port) {
     }
     const served = await port.review({
         ...request,
+        ...observation,
         requester: facts.requester,
         signal: facts.signal,
     });
@@ -222,6 +232,7 @@ function decodedContractResult(action, value) {
 export function contractRequestProtocol(action) {
     return {
         action,
+        supportsCancellation: true,
         encodeRequest: (request) => {
             const { action: _action, ...payload } = request;
             return payload;
@@ -258,6 +269,15 @@ export async function requestForwardedContractLive(input) {
         directory: input.directory,
         command,
         value: input.request,
+        onProgress: (value) => {
+            try {
+                observeExecution(input.observe, decodeExecutionEvent(value));
+            }
+            catch {
+                observeExecution(input.observe, { kind: "progress-dropped", count: 1 });
+            }
+        },
+        onProgressGap: (count) => observeExecution(input.observe, { kind: "progress-dropped", count }),
         ...(input.signal === undefined ? {} : { signal: input.signal }),
     }).catch((error) => {
         if (error instanceof AkumaBodyRequestError &&

package/build/src/library/contract-types.d.ts

@@ -13,6 +13,7 @@ import type { ContractWorkspaceLocation } from "../workspace-place.js";
 export type BindResult = Readonly<Omit<MutationResult<Keiyaku>, "value"> & {
     keiyaku: Keiyaku;
     workspace?: ContractWorkspaceLocation;
+    warnings?: readonly string[];
 } & RegionObservation>;
 export type Fact = JournalEntry;
 export type ContractHistoryEvent = Readonly<{

package/build/src/library/execution-result.d.ts

@@ -103,9 +103,9 @@ export declare const executionStopSchema: z.ZodObject<{
         admission: "admission";
         placement: "placement";
         verification: "verification";
-        reintegration: "reintegration";
         continuation: "continuation";
         reconciliation: "reconciliation";
+        reintegration: "reintegration";
     }>;
     reason: z.ZodEnum<{
         failed: "failed";
@@ -226,9 +226,9 @@ export declare const executionReceiptSchema: z.ZodObject<{
             admission: "admission";
             placement: "placement";
             verification: "verification";
-            reintegration: "reintegration";
             continuation: "continuation";
             reconciliation: "reconciliation";
+            reintegration: "reintegration";
         }>;
         reason: z.ZodEnum<{
             failed: "failed";

package/build/src/library/execution.d.ts

@@ -0,0 +1,8 @@
+import type { ExecutionEvent, ExecutionObserver } from "../protocol/execution-observation.js";
+export type { ExecutionEvent } from "../protocol/execution-observation.js";
+export type ContractExecution<Result> = Readonly<{
+    progress: AsyncIterable<ExecutionEvent>;
+    result: Promise<Result>;
+}>;
+/** An eager invocation with one bounded, optional progress subscription. */
+export declare function startContractExecution<Result>(run: (observe: ExecutionObserver) => Promise<Result>): ContractExecution<Result>;

package/build/src/library/execution.js

@@ -0,0 +1,102 @@
+const MAX_EVENTS = 256;
+const MAX_BYTES = 128 * 1024;
+class BoundedExecutionProgress {
+    pending = [];
+    bytes = 0;
+    dropped = 0;
+    finished = false;
+    unsubscribed = false;
+    subscribed = false;
+    wake;
+    notify() {
+        const waiter = this.wake;
+        this.wake = undefined;
+        waiter?.();
+    }
+    publish = (event) => {
+        if (this.unsubscribed || this.finished)
+            return;
+        const size = Buffer.byteLength(JSON.stringify(event));
+        if (size > MAX_BYTES) {
+            this.dropped += 1;
+            this.notify();
+            return;
+        }
+        while (this.pending.length >= MAX_EVENTS || this.bytes + size > MAX_BYTES) {
+            this.bytes -= this.pending.shift().bytes;
+            this.dropped += 1;
+        }
+        this.pending.push({ event, bytes: size });
+        this.bytes += size;
+        this.notify();
+    };
+    close() {
+        this.finished = true;
+        this.notify();
+    }
+    iterable() {
+        return {
+            [Symbol.asyncIterator]: () => this.iterator(),
+        };
+    }
+    iterator() {
+        if (this.subscribed)
+            throw new Error("execution progress supports one subscription");
+        this.subscribed = true;
+        let reading = false;
+        return {
+            next: async () => {
+                if (reading)
+                    throw new Error("execution progress next calls must be serial");
+                reading = true;
+                try {
+                    for (;;) {
+                        const next = await this.next();
+                        if (next !== undefined)
+                            return next;
+                    }
+                }
+                finally {
+                    reading = false;
+                }
+            },
+            return: async () => {
+                this.unsubscribed = true;
+                this.pending.length = 0;
+                this.bytes = 0;
+                this.dropped = 0;
+                this.notify();
+                return { done: true, value: undefined };
+            },
+        };
+    }
+    async next() {
+        if (this.unsubscribed)
+            return { done: true, value: undefined };
+        if (this.dropped > 0) {
+            const count = this.dropped;
+            this.dropped = 0;
+            return { done: false, value: { kind: "progress-dropped", count } };
+        }
+        const pending = this.pending.shift();
+        if (pending !== undefined) {
+            this.bytes -= pending.bytes;
+            return { done: false, value: pending.event };
+        }
+        if (this.finished)
+            return { done: true, value: undefined };
+        await new Promise((resolve) => {
+            this.wake = resolve;
+        });
+        return undefined;
+    }
+}
+/** An eager invocation with one bounded, optional progress subscription. */
+export function startContractExecution(run) {
+    const observations = new BoundedExecutionProgress();
+    const result = Promise.resolve()
+        .then(() => run(observations.publish))
+        .finally(() => observations.close());
+    void result.catch(() => undefined);
+    return Object.freeze({ progress: observations.iterable(), result });
+}

package/build/src/library/fleet.d.ts

@@ -1,6 +1,7 @@
 /** @architectureCompositionRoot */
 import { type ActivityHistory, type OutcomeRow, type AkumaStatus, type InterruptReceipt } from "../akuma/akuma.js";
 import { type ExecutionContext } from "../akuma/requests.js";
+import type { WaitObserver } from "../akuma/fleet-execution.js";
 import { type DispatchAssociation } from "../dispatch/index.js";
 import { type AkumaAddressInput, type AkumaSetAddressInput } from "./address.js";
 import { type AkumaKillResult, type AkumaObservation, type AkumaObservationStage, type AkumaTellResult, type AkumaWaitResult } from "../akuma/fleet-observation.js";
@@ -10,6 +11,7 @@ export type AkumaWaitInput = AkumaSetAddressInput & Readonly<{
 }>;
 export type AkumaTellInput = AkumaAddressInput & Readonly<{
     body: string;
+    initiator?: string;
 }>;
 export type { TellResult, TellWake } from "../akuma/akuma.js";
 export type { CreatedTaskObservation } from "../task/created-observation.js";
@@ -17,6 +19,7 @@ export type { DispatchAssociation } from "../dispatch/association.js";
 export type { AkumaKillResult, AkumaObservation, AkumaObservationStage, AkumaTellResult, AkumaUnobserved, AkumaWaitResult, } from "../akuma/fleet-observation.js";
 export type AkumaInterruptInput = AkumaAddressInput & Readonly<{
     body: string;
+    initiator?: string;
 }>;
 export type AkumaInterruptResult = Readonly<{
     id: AkumaStatus["id"];
@@ -56,7 +59,7 @@ export type AkumaHistoryResult = Readonly<{
     contract: DispatchAssociation;
 }>;
 export declare function statusAkuma(input: AkumaAddressInput): Promise<AkumaObservation>;
-export declare function waitAkuma(input: AkumaWaitInput, execution?: ExecutionContext): Promise<AkumaWaitResult>;
+export declare function waitAkuma(input: AkumaWaitInput, execution?: ExecutionContext, observer?: WaitObserver): Promise<AkumaWaitResult>;
 export declare function killAkuma(input: AkumaSetAddressInput, execution?: ExecutionContext): Promise<AkumaKillResult>;
 export declare function tellAkuma(input: AkumaTellInput, execution?: ExecutionContext): Promise<AkumaTellResult>;
 export declare function interruptAkuma(input: AkumaInterruptInput): Promise<AkumaInterruptResult>;

package/build/src/library/fleet.js

@@ -4,6 +4,7 @@ import { createAkumaProduct } from "../akuma/akuma-product.js";
 import { executionChannel, localExecutionContext } from "../akuma/requests.js";
 import { requestForwardedFleetKill, requestForwardedFleetTell, requestForwardedFleetWait, } from "../akuma/fleet-request.js";
 import { executeKillAkuma, executeTellAkuma, executeWaitAkuma } from "../akuma/fleet-execution.js";
+import { readAliases } from "../alias/index.js";
 import { observeDispatchAssociation } from "../dispatch/index.js";
 import { observeCreatedTaskObservations } from "../task/created-observation.js";
 import { addressAkuma, addressAkumaSet } from "./address.js";
@@ -23,6 +24,26 @@ async function dispatchAssociation(repo, id) {
 async function createdTasksFor(path, statuses) {
     return await observeCreatedTaskObservations(path, statuses.map((status) => status.id));
 }
+/**
+ * One wait's identity-fact resolver: the alias bound to an Akuma in its world and
+ * its Dispatch association. The alias index is read once, on the first observed
+ * Akuma, and each Akuma's alias is the first binding the canonical order offers.
+ */
+function waitIdentityFacts(path, repo) {
+    let aliases;
+    return async (id) => {
+        if (aliases === undefined) {
+            const bound = new Map();
+            for (const binding of await readAliases(path)) {
+                if (!bound.has(binding.akuId))
+                    bound.set(binding.akuId, binding.alias);
+            }
+            aliases = bound;
+        }
+        const alias = aliases.get(id);
+        return { ...(alias === undefined ? {} : { alias }), contract: await dispatchAssociation(repo, id) };
+    };
+}
 async function observeAkuma(status, path, repo) {
     return (await observeAkumaSet([status], path, repo))[0];
 }
@@ -85,7 +106,7 @@ export async function statusAkuma(input) {
     const addressed = await addressAkuma(input);
     return await observeAkuma(await source(addressed.path).selectHandle({ id: addressed.id }).status(), addressed.path, input.repo);
 }
-export async function waitAkuma(input, execution = localExecutionContext()) {
+export async function waitAkuma(input, execution = localExecutionContext(), observer) {
     const values = requireInput(input, "Keiyaku.wait input");
     for (const key of Object.keys(values)) {
         if (!["path", "akuma", "repo", "completion", "timeoutMs"].includes(key)) {
@@ -94,13 +115,11 @@ export async function waitAkuma(input, execution = localExecutionContext()) {
     }
     const addressed = await addressAkumaSet(setAddress(values));
     const completion = values.completion;
-    if (addressed.ids.length > 1 && completion !== "any" && completion !== "all") {
-        throw new TypeError("completion must be any or all when waiting for multiple Akuma");
-    }
     if (completion !== undefined && completion !== "any" && completion !== "all") {
         throw new TypeError("completion must be any or all");
     }
-    const selected = completion ?? "all";
+    // An omitted mode is any: a plural wait returns when any selected Akuma is complete.
+    const selected = completion ?? "any";
     const timeoutMs = timeout(values.timeoutMs);
     const channel = executionChannel(execution);
     const repo = values.repo;
@@ -117,6 +136,9 @@ export async function waitAkuma(input, execution = localExecutionContext()) {
         ids: addressed.ids,
         completion: selected,
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        identity: waitIdentityFacts(addressed.path, repo),
+        ...(observer?.selected === undefined ? {} : { onSelected: observer.selected }),
+        ...(observer?.observe === undefined ? {} : { observe: observer.observe }),
     }));
 }
 export async function killAkuma(input, execution = localExecutionContext()) {
@@ -136,7 +158,7 @@ export async function killAkuma(input, execution = localExecutionContext()) {
 export async function tellAkuma(input, execution = localExecutionContext()) {
     const values = requireInput(input, "Keiyaku.tell input");
     for (const key of Object.keys(values)) {
-        if (!["path", "akuma", "body", "repo"].includes(key)) {
+        if (!["path", "akuma", "body", "repo", "initiator"].includes(key)) {
             throw new TypeError(`Keiyaku.tell input has unknown field: ${key}`);
         }
     }
@@ -149,18 +171,20 @@ export async function tellAkuma(input, execution = localExecutionContext()) {
             directory: channel.directory,
             target: addressed.id,
             body: values.body,
+            ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
         });
     }
     return await executeTellAkuma({
         path: addressed.path,
         id: addressed.id,
         body: values.body,
+        ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
     });
 }
 export async function interruptAkuma(input) {
     const values = requireInput(input, "Keiyaku.interrupt input");
     for (const key of Object.keys(values)) {
-        if (!["path", "akuma", "body", "repo"].includes(key)) {
+        if (!["path", "akuma", "body", "repo", "initiator"].includes(key)) {
             throw new TypeError(`Keiyaku.interrupt input has unknown field: ${key}`);
         }
     }
@@ -168,7 +192,7 @@ export async function interruptAkuma(input) {
         throw new TypeError("body must be a string");
     const addressed = await addressAkuma(directAddress(values));
     const handle = source(addressed.path).selectHandle({ id: addressed.id });
-    const receipt = await handle.interrupt(values.body);
+    const receipt = await handle.interrupt(values.body, input.initiator === undefined ? {} : { initiator: input.initiator });
     const observation = await observeAkumaStage(addressed.path, addressed.id, values.repo);
     return { id: addressed.id, receipt, observation };
 }

package/build/src/library/keiyaku.d.ts

@@ -122,6 +122,7 @@ export declare const Keiyaku: Readonly<{
             status: {
                 id: import("../akuma/identity.js").AkuId;
                 life: "killed" | "hung" | "untidy" | "running" | "asleep" | "stranded";
+                allowed: import("../akuma/allowed.js").AllowedActions;
                 timeline: {
                     reportedChanges: readonly {
                         sequence: number;
@@ -418,4 +419,5 @@ export declare const Keiyaku: Readonly<{
     }>;
 }>;
 export { executionReceipt } from "./execution-result.js";
+export type { ContractExecution, ExecutionEvent } from "./execution.js";
 export type { ExecutionCleanup, ExecutionStop, ExecutionReceipt, MutationOperation } from "./execution-result.js";

package/build/src/library/mutation.js

@@ -184,13 +184,21 @@ async function reconcileExecution(input, progress) {
     for (const contractId of contracts) {
         try {
             input.scope.signal?.throwIfAborted();
-            const report = await completeReconcile({
-                scope: input.scope,
-                channel: input.channel,
-                contractId,
-                hooks: input.hooks,
-                retryHooks: false,
-            });
+            progress.observe({ kind: "stage", contractId, stage: "reconciliation", state: "started" });
+            const report = await (async () => {
+                try {
+                    return await completeReconcile({
+                        scope: input.scope,
+                        channel: input.channel,
+                        contractId,
+                        hooks: input.hooks,
+                        retryHooks: false,
+                    });
+                }
+                finally {
+                    progress.observe({ kind: "stage", contractId, stage: "reconciliation", state: "finished" });
+                }
+            })();
             reports.push(report);
             progress.recordResidue(contractId, report.settlement);
         }