@astrosheep/keiyaku 4.6.13 → 4.6.14

package/build/src/cli/square-identity.js

@@ -1,61 +1,60 @@
 import { createHash } from "node:crypto";
-import { realpath } from "node:fs/promises";
-import { join, resolve } from "node:path";
-import { inbox, Square, SquareError, squareAssignedParticipantName } from "@astrosheep/square";
+import { join } from "node:path";
+import { Square, SquareError } from "@astrosheep/square";
 /**
- * The Square integration's submitting-edge identity policy. Call, fork, tell, and
- * ask share this one adapter, so no command and no generic caller decoder has to
- * know how Square names a participant. Every Square read below is rooted in the
- * submitted environment's own coordinates, never in this process's ambient ones.
+ * The submitting-edge identity policy. Every Square read is rooted in the
+ * submitted environment's actual Body, never this process's ambient identity.
  */
-/** Square's own harness-session coordinates, in its resolution order. */
 const HARNESS_SESSIONS = [
-    { provider: "claude", variable: "CLAUDE_CODE_SESSION_ID" },
-    { provider: "codex", variable: "CODEX_THREAD_ID" },
-    { provider: "opencode", variable: "OPENCODE_SESSION_ID" },
-    { provider: "pi", variable: "PI_SESSION_ID" },
-    { provider: undefined, variable: "PASEO_AGENT_ID" },
+    { provider: "claude", channel: "claude-code", variable: "CLAUDE_CODE_SESSION_ID" },
+    { provider: "codex", channel: "codex", variable: "CODEX_THREAD_ID" },
+    { provider: "opencode", channel: "opencode", variable: "OPENCODE_SESSION_ID" },
+    { provider: "pi", channel: "pi", variable: "PI_SESSION_ID" },
+    { provider: undefined, channel: "paseo", variable: "PASEO_AGENT_ID" },
 ];
 const SEAT_PREFIX = "keiyaku-assigned-";
 const SEAT_DIGEST_DOMAIN = "keiyaku/square-seat/v1";
 const SEAT_DIGEST_LENGTH = 12;
-/** One bounded identity observation; a non-cooperative Square never holds a submission. */
 const IDENTITY_BUDGET_MS = 5_000;
 function declared(environment, variable) {
     const value = environment[variable]?.trim();
     return value === undefined || value === "" ? undefined : value;
 }
-/** A stable, collision-resistant seat for one provider session coordinate. */
+function sessionCoordinates(environment) {
+    return HARNESS_SESSIONS.flatMap(({ variable, channel, provider }) => {
+        const session = declared(environment, variable);
+        return session === undefined ? [] : [{ channel, ...(provider === undefined ? {} : { provider }), session }];
+    });
+}
+function squareBody(environment) {
+    if (environment.CLAUDE_CODE_CHILD_SESSION === "1")
+        return undefined;
+    const coordinates = sessionCoordinates(environment);
+    const native = coordinates.filter(({ provider }) => provider !== undefined);
+    if (native.length > 1)
+        return undefined;
+    const coordinate = native[0] ?? coordinates.find(({ channel }) => channel === "paseo");
+    return coordinate === undefined ? undefined : { channel: coordinate.channel, session: coordinate.session };
+}
 function squareSeatName(provider, session) {
     const digest = createHash("sha256")
         .update(`${SEAT_DIGEST_DOMAIN}\u0000${provider}\u0000${session}`, "utf8")
         .digest("hex");
     return `${SEAT_PREFIX}${digest.slice(0, SEAT_DIGEST_LENGTH)}`;
 }
-/** Every harness session coordinate this process declares, able to name a seat or not. */
-function sessionIds(environment) {
-    return HARNESS_SESSIONS.flatMap(({ variable }) => {
-        const session = declared(environment, variable);
-        return session === undefined ? [] : [session];
-    });
-}
-/**
- * The deterministic candidate for this process. Only one provider-backed session
- * may exist: a second coordinate — another provider, or the same raw token under
- * a different one — is ambiguous and selects nothing.
- */
 function seatCandidate(environment) {
-    const names = HARNESS_SESSIONS.flatMap(({ provider, variable }) => {
-        const session = declared(environment, variable);
-        return provider === undefined || session === undefined ? [] : [squareSeatName(provider, session)];
+    const candidates = sessionCoordinates(environment).flatMap(({ provider, session }) => provider === undefined ? [] : [squareSeatName(provider, session)]);
+    return candidates.length === 1 ? candidates[0] : undefined;
+}
+function priorSeatNames(environment) {
+    return sessionCoordinates(environment).flatMap(({ provider, session }) => {
+        if (provider === undefined)
+            return [];
+        const legacy = createHash("sha256").update(session, "utf8").digest("hex").slice(0, 12);
+        const assigned = squareSeatName(provider, session);
+        return [`${provider}-${legacy}`, assigned, assigned.replace(SEAT_PREFIX, "keiyaku-seat-")];
     });
-    return names.length === 1 ? names[0] : undefined;
 }
-/**
- * Square owns the name grammar, so the edge borrows one of Square's own handles
- * instead of restating it. An in-memory square validates without touching any
- * artifact.
- */
 async function usableName(name) {
     try {
         await Square.inMemory({ markdown: "" }).participant(name);
@@ -65,66 +64,27 @@ async function usableName(name) {
         return false;
     }
 }
-/** Square's own canonical coordinate for a location it already published. */
-async function canonical(path) {
-    try {
-        return await realpath(path);
-    }
-    catch {
-        return resolve(path);
-    }
-}
-/**
- * Bindings this session already holds in this Square. Square's session inbox
- * reads the same host registry as native hooks, and it is the only public read
- * that takes the caller's own environment coordinate. Its page is bounded, so a
- * view that hides rows proves nothing about absence here.
- */
-async function joinedBindings(environment, ids, location, signal) {
-    const pages = await Promise.all(ids.map(async (session) => await inbox({ env: environment }, session, {}, { signal })));
-    const here = await canonical(location);
-    return {
-        here: pages.flatMap(({ rows }) => rows).filter(({ squarePath }) => squarePath === here).length,
-        complete: pages.every(({ rows, total }) => total === rows.length),
-    };
-}
-/**
- * A session whose former participant already finished here has no replacement
- * identity: releasing the binding leaves Square's roster as the only evidence of
- * that standing, and a fresh seat would rename a finished caller into a new one.
- */
-async function finishedHere(square, environment, signal) {
-    const former = squareAssignedParticipantName(environment);
-    const previous = seatCandidate(environment)?.replace(SEAT_PREFIX, "keiyaku-seat-");
-    if (former === undefined && previous === undefined)
-        return false;
-    const { participants } = await square.participants({}, { signal });
-    return participants.some(({ name, state }) => (name === former || name === previous) && state === "done");
-}
-/**
- * A binding this edge cannot stand on is never replaced by a fresh name: Square
- * adjudicates standing, ownership, and lifecycle. The edge only distinguishes a
- * Square that is genuinely not there yet from evidence it cannot trust.
- */
-async function standingAt(location, environment, ids, signal) {
+async function standingAt(location, environment, body, signal) {
     let square;
     try {
-        square = await Square.at({ path: location, env: environment }, { signal });
+        square = await Square.at({ path: location, env: environment, body }, { signal });
     }
     catch (error) {
-        // Only a Square that is genuinely not there yet may receive a new seat.
         return error instanceof SquareError && error.code === "unavailable"
             ? { kind: "absent" }
             : { kind: "indeterminate" };
     }
     try {
-        const recognized = await square.recognize(environment);
-        if (recognized !== null)
-            return { kind: "standing", name: recognized.name };
-        const bindings = await joinedBindings(environment, ids, square.location, signal);
-        if (bindings.here > 0 || !bindings.complete)
+        const recognized = await square.recognize();
+        if (recognized.length === 1)
+            return { kind: "standing", name: recognized[0].name };
+        if (recognized.length > 1)
+            return { kind: "indeterminate" };
+        const known = new Set(priorSeatNames(environment));
+        const participants = (await square.participants({}, { signal })).participants;
+        if (participants.some(({ name, state }) => known.has(name) && state !== "not joined"))
             return { kind: "indeterminate" };
-        return (await finishedHere(square, environment, signal)) ? { kind: "indeterminate" } : { kind: "absent" };
+        return { kind: "absent" };
     }
     catch {
         return { kind: "indeterminate" };
@@ -133,11 +93,6 @@ async function standingAt(location, environment, ids, signal) {
         await square.close().catch(() => undefined);
     }
 }
-/**
- * The one bounded attempt. A late settlement keeps no authority: the adapter only
- * reads Square, so nothing arrives after the caller has settled, and no refusal
- * escapes as an unhandled rejection.
- */
 async function bounded(attempt, control) {
     const budget = new AbortController();
     const timer = setTimeout(() => budget.abort(new Error("Square identity observation expired")), control.budgetMs ?? IDENTITY_BUDGET_MS);
@@ -159,22 +114,17 @@ function whenAborted(signal) {
             signal.addEventListener("abort", () => settle(undefined), { once: true });
     });
 }
-/**
- * The Square participant name this submitting session should speak as, or
- * undefined when no honest choice exists. Identity preparation is optional, so it
- * never refuses the enclosing operation and always settles within one budget.
- */
 export async function squareSeat(input, control = {}) {
     const name = declared(input.environment, "SQUARE_PARTICIPANT_NAME");
     if (name !== undefined)
         return (await usableName(name)) ? name : undefined;
-    const ids = sessionIds(input.environment);
-    // No session coordinate: nothing to reuse, nothing to derive, nothing to read.
-    if (ids.length === 0)
+    const body = squareBody(input.environment);
+    const candidate = seatCandidate(input.environment);
+    if (body === undefined)
         return undefined;
     const location = join(input.path, ".square", "KEIYAKU.square");
-    const standing = await bounded(async (signal) => await standingAt(location, input.environment, ids, signal), control);
+    const standing = await bounded(async (signal) => await standingAt(location, input.environment, body, signal), control);
     if (standing?.kind === "standing")
         return standing.name;
-    return standing?.kind === "absent" ? seatCandidate(input.environment) : undefined;
+    return standing?.kind === "absent" ? candidate : undefined;
 }

package/build/src/index.d.ts

@@ -63,7 +63,7 @@ export type { ReconcileCompletion, RepoContractReconcileReport, RepoReconcileRep
 export type { KeiyakuRefusal, KeiyakuRetryReason, NukeConfirmationRefusal, NukeConfirmationRequiredRefusal, OperationRetries, } from "./library/refusal.js";
 export type { RegionOverlap } from "./library/region.js";
 export type { RepoAtInput } from "./library/repo.js";
-export type { KeiyakuPlugin, PluginAkumaCaller, PluginAkumaOrigin, PluginBodyEnd, PluginContext, PluginHooks, PluginInstance, PluginManifest, PluginOutcome, PluginSignal, PluginSignalMap, } from "./plugin/public.js";
+export type { KeiyakuPlugin, PluginAkumaCaller, PluginAkumaOrigin, PluginBodyEnd, PluginContext, PluginHooks, PluginInstance, PluginManifest, PluginOutcome, PluginWaitDeferral, PluginWaitDeferralInput, PluginSignal, PluginSignalMap, } from "./plugin/public.js";
 export type { DeliveryPreviewReport } from "./protocol/delivery-preview.js";
 export type { IntegrationConflictMaterialized, VerificationReuse } from "./protocol/deliver.js";
 export type { ExecutionObservation, ExecutionObserver } from "./protocol/execution-observation.js";

package/build/src/library/akuma-retention.d.ts

@@ -0,0 +1,11 @@
+import type { AkuId } from "../akuma/identity.js";
+import type { WorldRoot } from "../world.js";
+/**
+ * One deterministic, bounded retention sweep over the World's recognized Akuma
+ * entries. The semantic age, lifecycle, and custody judgment stay in the Akuma
+ * owner; this composition supplies only the optional Alias, Dispatch, and
+ * Contract associations that owner must not read itself.
+ */
+export declare function sweepInactiveAkumas(world: WorldRoot, options?: Readonly<{
+    now?: number;
+}>): Promise<readonly AkuId[]>;

package/build/src/library/akuma-retention.js

@@ -0,0 +1,131 @@
+/** @architectureCompositionRoot */
+import { tryAcquireAliasCustody, readAliases } from "../alias/index.js";
+import { knownAkuma } from "../akuma/akuma.js";
+import { boundedMap } from "../akuma/read-pool.js";
+import { readRetentionCandidate, retentionCandidateBound, retentionNow, retireInactiveAkuma, } from "../akuma/retention.js";
+import { observeDispatchAssociations } from "../dispatch/index.js";
+import { observeContractAt } from "../git/observe.js";
+import { isPrivateStateSeatContention, withPrivateStatePublicationSeat } from "../git/private-state-seat.js";
+import { withGitDecodeChannel } from "../git/read-observation.js";
+import { NoGitWorldError, repositoryAt } from "../git/repository.js";
+/**
+ * A World that never became a Git repository has no Dispatch or Contract
+ * authority, so every candidate is free of those associations. Any other
+ * failure to prove the repository keeps all candidates.
+ */
+async function retentionRepository(world) {
+    try {
+        return await repositoryAt(world);
+    }
+    catch (error) {
+        if (error instanceof NoGitWorldError)
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * A Dispatch association is retirable only when it is absent or names a
+ * terminal Contract. Unproven, corrupt, missing-Contract, and active Contract
+ * associations all keep the Akuma.
+ */
+async function dispatchAssociationIsRetirable(repository, association) {
+    if (association.kind === "none")
+        return true;
+    if (association.kind === "failed" || repository === undefined)
+        return false;
+    return await withGitDecodeChannel(repository, async (channel) => {
+        try {
+            const terminal = (await observeContractAt(repository, channel, association.contractId)).state?.terminal;
+            return terminal?.kind === "claimed" || terminal?.kind === "abandoned";
+        }
+        catch {
+            return false;
+        }
+    });
+}
+async function retireCandidate(world, repository, entry, now) {
+    try {
+        const receipt = await retireInactiveAkuma({
+            entry,
+            now,
+            retireUnderCustody: async (retire) => {
+                const retireOrRetain = async () => ((await retire()) ? "retired" : "retained");
+                // Alias writers use this same authority lock. Holding it across the
+                // Dispatch judgment and removal means an Alias cannot appear between
+                // the final check and the deletion.
+                const aliases = await tryAcquireAliasCustody(world);
+                if (aliases === null)
+                    return "retained";
+                try {
+                    if (aliases.bindings.some((binding) => binding.akuId === entry.id))
+                        return "retained";
+                    if (repository === undefined)
+                        return await retireOrRetain();
+                    try {
+                        // Dispatch publication takes this same private-state seat. Holding
+                        // it across the judgment and removal means a Dispatch cannot appear
+                        // between the final check and the deletion.
+                        const retired = await withPrivateStatePublicationSeat(repository, async () => {
+                            const associations = await observeDispatchAssociations(repository, [entry.id]);
+                            if (!(await dispatchAssociationIsRetirable(repository, associations.get(entry.id))))
+                                return "retained";
+                            return await retireOrRetain();
+                        }, { timeoutMs: 0 });
+                        return retired.value;
+                    }
+                    catch (error) {
+                        if (isPrivateStateSeatContention(error))
+                            return "retained";
+                        throw error;
+                    }
+                }
+                finally {
+                    aliases.release();
+                }
+            },
+        });
+        return receipt === "retired";
+    }
+    catch {
+        // One unreadable, corrupt, or unremovable candidate never fails the sweep
+        // or the ordinary operation that triggered it.
+        return false;
+    }
+}
+/**
+ * One deterministic, bounded retention sweep over the World's recognized Akuma
+ * entries. The semantic age, lifecycle, and custody judgment stay in the Akuma
+ * owner; this composition supplies only the optional Alias, Dispatch, and
+ * Contract associations that owner must not read itself.
+ */
+export async function sweepInactiveAkumas(world, options = {}) {
+    const now = options.now ?? retentionNow();
+    const known = await knownAkuma(world);
+    if (known.rows.length === 0)
+        return [];
+    const candidates = (await boundedMap(known.rows, async (entry) => {
+        try {
+            if (!(await retentionCandidateBound(entry.paths, now)))
+                return null;
+            return await readRetentionCandidate(entry, now);
+        }
+        catch {
+            return null;
+        }
+    })).filter((entry) => entry !== null);
+    if (candidates.length === 0)
+        return [];
+    const aliases = new Set((await readAliases(world)).map((binding) => binding.akuId));
+    const repository = await retentionRepository(world);
+    const associations = await observeDispatchAssociations(repository, candidates.map((entry) => entry.id));
+    const retired = [];
+    for (const entry of candidates) {
+        if (aliases.has(entry.id))
+            continue;
+        if (!(await dispatchAssociationIsRetirable(repository, associations.get(entry.id))))
+            continue;
+        if (await retireCandidate(world, repository, entry, now))
+            retired.push(entry.id);
+    }
+    return retired;
+}

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

@@ -28,6 +28,14 @@ declare class AkumasHandle {
     wait(input: AkumaWaitInput): Promise<AkumaWaitResult>;
     kill(input: AkumaKillInput): Promise<AkumaKillResult>;
     history(input: AkumaHistoryInput): Promise<AkumaHistoryResult>;
+    /**
+     * The one write-side maintenance point: a successful birth is already durable,
+     * so one best-effort sweep may follow it. Only an in-flight sweep is
+     * coalesced; a completed or failed sweep leaves the next successful birth free
+     * to start a fresh one. It never changes the birth result or any observation.
+     */
+    private maintain;
+    private sweep;
     private withWorld;
 }
 /**

package/build/src/library/akumas.js

@@ -4,6 +4,7 @@ import { readAkumaRoster } from "../akuma/akuma.js";
 import { localExecutionContext } from "../akuma/requests.js";
 import { readAliases } from "../alias/index.js";
 import { World } from "../world.js";
+import { sweepInactiveAkumas } from "./akuma-retention.js";
 import { callAkumas, forkAkumas } from "./akuma-creation.js";
 import { requireInput } from "./input.js";
 import { askAkumaOn, historyAkuma, killAkumaOn, selectionSeam, statusAkuma, tellAkumaOn, waitAkumaOn, } from "./selection.js";
@@ -13,6 +14,7 @@ class AkumasHandle {
     #execution;
     #selection;
     #reportDiagnostic;
+    #maintenance;
     constructor(world, execution, host) {
         this.#world = world;
         this.#execution = execution;
@@ -29,10 +31,19 @@ class AkumasHandle {
         return withRosterAliases(roster, await readAliases(path));
     }
     call(input) {
-        return callAkumas(this.withWorld(input, "Akumas.call input"), this.#execution, this.#reportDiagnostic);
+        const pending = callAkumas(this.withWorld(input, "Akumas.call input"), this.#execution, this.#reportDiagnostic);
+        return pending.then(async (result) => {
+            await this.maintain(this.#world);
+            return result;
+        });
     }
     fork(input) {
-        return forkAkumas(this.withWorld(input, "Akumas.fork input"));
+        const pending = forkAkumas(this.withWorld(input, "Akumas.fork input"));
+        return pending.then(async (result) => {
+            if (result.kind === "forked")
+                await this.maintain(this.#world);
+            return result;
+        });
     }
     status(input) {
         return statusAkuma(this.withWorld(input, "Akumas.status input"), this.#reportDiagnostic);
@@ -52,6 +63,35 @@ class AkumasHandle {
     history(input) {
         return historyAkuma(this.withWorld(input, "Akumas.history input"), this.#reportDiagnostic);
     }
+    /**
+     * The one write-side maintenance point: a successful birth is already durable,
+     * so one best-effort sweep may follow it. Only an in-flight sweep is
+     * coalesced; a completed or failed sweep leaves the next successful birth free
+     * to start a fresh one. It never changes the birth result or any observation.
+     */
+    maintain(world) {
+        const inFlight = this.#maintenance;
+        if (inFlight !== undefined)
+            return inFlight;
+        const pending = this.sweep(world).finally(() => {
+            this.#maintenance = undefined;
+        });
+        this.#maintenance = pending;
+        return pending;
+    }
+    async sweep(world) {
+        try {
+            await sweepInactiveAkumas(world);
+        }
+        catch (error) {
+            try {
+                this.#reportDiagnostic?.(`akuma retention sweep failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            catch {
+                // A diagnostic sink failure cannot change the ordinary operation.
+            }
+        }
+    }
     withWorld(input, label) {
         const values = requireInput(input, label);
         if (Object.hasOwn(values, "path"))

package/build/src/library/selection.js

@@ -1,4 +1,5 @@
 /** @architectureCompositionRoot */
+import { observeStatusOutcome } from "../akuma/akuma-observe.js";
 import { withoutReportedChanges } from "../akuma/projection.js";
 import { AkumaNotBornError, AkumaObservationError } from "../akuma/akuma-errors.js";
 import { AkumaOwner } from "../akuma/akuma-owner.js";
@@ -12,15 +13,26 @@ import { observeDispatchAssociations } from "../dispatch/index.js";
 import { observeContractAt } from "../git/observe.js";
 import { withGitDecodeChannel } from "../git/read-observation.js";
 import { observeCreatedDebtObservations } from "../debt/created-observation.js";
-import { outcomePluginObserver, stderrPluginDiagnostic } from "../plugin/akuma-signals.js";
+import { outcomePluginObserver, stderrPluginDiagnostic, withAkumaWaitDeferrals } from "../plugin/akuma-signals.js";
 import { addressAkuma, addressAkumaSet, resolveAkuma, resolveAkumaSet, } from "./address.js";
 import { requireInput } from "./input.js";
 import { scopeForRepo } from "./repo.js";
 export function selectionSeam(execution, reportDiagnostic = stderrPluginDiagnostic) {
     const channel = executionChannel(execution);
-    return channel.kind === "body-request" ? forwardedSelection(channel.directory) : localSelection(reportDiagnostic);
+    const routed = channel.kind === "body-request"
+        ? forwardedSelection(channel.directory, reportDiagnostic)
+        : localSelection(reportDiagnostic);
+    return {
+        ...routed,
+        wait: async (addressed, mode) => await withAkumaWaitDeferrals({ world: addressed.path, reportDiagnostic }, addressed.orderedIds, mode.signal, async () => {
+            const result = await routed.wait(addressed, mode);
+            const observer = outcomePluginObserver({ world: addressed.path, reportDiagnostic });
+            await Promise.all(result.observations.map(({ status }) => observeStatusOutcome(status, observer)));
+            return result;
+        }),
+    };
 }
-function forwardedSelection(directory) {
+function forwardedSelection(directory, reportDiagnostic) {
     return {
         addressOne: resolveAkuma,
         addressSet: resolveAkumaSet,
@@ -39,7 +51,7 @@ function forwardedSelection(directory) {
             ...(abort === undefined ? {} : { signal: abort }),
         }),
         ask: async (addressed, input, abort) => {
-            const result = await requestForwardedSelectionAsk({
+            const { result, historyIds } = await requestForwardedSelectionAsk({
                 directory,
                 target: addressed.id,
                 body: input.body,
@@ -49,6 +61,7 @@ function forwardedSelection(directory) {
                 ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
                 ...(abort === undefined ? {} : { signal: abort }),
             });
+            await outcomePluginObserver({ world: addressed.path, reportDiagnostic })(result.akuma, historyIds);
             return (input.schema === undefined
                 ? result
                 : { ...result, observation: decodeAskObservation(result.observation, input.schema) });
@@ -59,7 +72,7 @@ function localSelection(reportDiagnostic) {
     return {
         addressOne: addressAkuma,
         addressSet: addressAkumaSet,
-        wait: async (addressed, mode) => await localWait(addressed, mode, reportDiagnostic),
+        wait: async (addressed, mode) => await localWait(addressed, mode),
         kill: async (addressed, abort) => await executeKillAkuma({
             path: addressed.path,
             ids: addressed.orderedIds,
@@ -231,21 +244,21 @@ function completionMode(value) {
     return value;
 }
 async function forwardedWait(addressed, input) {
-    return await attachWaitAssociations(addressed.path, input.repo, await requestForwardedSelectionWait({
+    const result = await requestForwardedSelectionWait({
         directory: input.directory,
         targets: addressed.orderedIds,
         completion: input.completion,
         ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
         ...(input.signal === undefined ? {} : { signal: input.signal }),
-    }));
+    });
+    return await attachWaitAssociations(addressed.path, input.repo, result);
 }
-async function localWait(addressed, input, reportDiagnostic) {
+async function localWait(addressed, input) {
     try {
         return await composeWaitResult(addressed.path, input.repo, await executeWaitAkuma({
             path: addressed.path,
             ids: addressed.orderedIds,
             completion: input.completion,
-            outcomeObserved: outcomePluginObserver({ world: addressed.path, reportDiagnostic }),
             ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
         }));

package/build/src/plugin/akuma-signals.d.ts

@@ -14,6 +14,7 @@ type PluginSignalEmission = Readonly<{
  * problem reaches the producer only as a diagnostic, never as a thrown error.
  */
 export declare function emitPluginSignal(emission: PluginSignalEmission, signal: PluginSignal): Promise<void>;
+export declare function withAkumaWaitDeferrals<T>(emission: PluginSignalEmission, akumaIds: readonly string[], signal: AbortSignal | undefined, action: () => Promise<T>): Promise<T>;
 /** One public observer operation, never shared with incidental owner reads. */
 export declare function outcomePluginObserver(emission: PluginSignalEmission, observer?: string): (akumaId: string, historyIds: readonly string[]) => Promise<void>;
 export {};

package/build/src/plugin/akuma-signals.js

@@ -21,6 +21,23 @@ export async function emitPluginSignal(emission, signal) {
         reportPluginDiagnostic(emission.reportDiagnostic, "runtime", "signal", error);
     }
 }
+export async function withAkumaWaitDeferrals(emission, akumaIds, signal, action) {
+    signal?.throwIfAborted();
+    let runtime;
+    try {
+        runtime = await pluginRuntime({
+            world: emission.world,
+            ...(emission.settings === undefined ? {} : { settings: emission.settings }),
+            reportDiagnostic: emission.reportDiagnostic,
+        });
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        reportPluginDiagnostic(emission.reportDiagnostic, "runtime", "wait deferral", error);
+        return await action();
+    }
+    return await runtime.withWaitDeferrals(akumaIds, signal, action, emission.reportDiagnostic);
+}
 /** One public observer operation, never shared with incidental owner reads. */
 export function outcomePluginObserver(emission, observer) {
     const seen = new Set();

package/build/src/plugin/public.d.ts

@@ -97,6 +97,13 @@ export type KeiyakuPlugin = Readonly<{
     manifest: PluginManifest;
     activate(context: PluginContext, cancellation?: AbortSignal): Promise<PluginInstance> | PluginInstance;
 }>;
+export type PluginWaitDeferralInput = Readonly<{
+    akumaIds: readonly string[];
+}>;
+export type PluginWaitDeferral = Readonly<{
+    close(cancellation?: AbortSignal): Promise<void> | void;
+}>;
 export type PluginInstance = Readonly<{
     signals?: PluginHooks;
+    waitDeferral?: (input: PluginWaitDeferralInput, cancellation?: AbortSignal) => Promise<PluginWaitDeferral | undefined> | PluginWaitDeferral | undefined;
 }>;

package/build/src/plugin/runtime.d.ts

@@ -9,6 +9,7 @@ type PluginRuntimeInput = Readonly<{
 }>;
 export type PluginRuntime = Readonly<{
     emit(signal: PluginSignal, reportDiagnostic?: PluginDiagnostic): Promise<void>;
+    withWaitDeferrals<T>(akumaIds: readonly string[], signal: AbortSignal | undefined, action: () => Promise<T>, reportDiagnostic?: PluginDiagnostic): Promise<T>;
 }>;
 export declare function reportPluginDiagnostic(report: PluginDiagnostic | undefined, subject: string, stage: string, error: unknown): void;
 export declare function pluginRuntime(input: PluginRuntimeInput): Promise<PluginRuntime>;