@astrosheep/keiyaku 4.5.23 → 4.5.25

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-akuma/SKILL.md

@@ -49,6 +49,24 @@ vocabulary, while an explicit empty default permits none. A nested call can use
 only actions permitted by its direct parent Soul. Use `status <aku/...|@alias>`
 to inspect the born worker's frozen effective actions.
 
+## Answer Schemas
+
+For a schema-bearing call or tell through the public API, pass the schema
+directly — `{ schema: z.object({ claim: z.string() }) }` — importing `z` from
+the package root next to `Akuma`. Any Standard Schema v1 value works the same
+way, and the explicit `Schema.zod(...)` and `Schema.json(...)` forms remain
+available for callers who want them.
+
+Keep an answer contract inside simple JSON shape vocabulary: objects, arrays,
+strings, numbers, booleans, enums, literals, and optional or nullable fields.
+Do not attach `.max`, `.min`, `.regex`, `.refine`, `.transform`, or other
+constraint methods. The provider must satisfy the contract, and a fragile or
+unrepresentable constraint fails the loop after submission; the seam refuses
+such a schema at submission and names the offending keyword instead. Enforce
+bounds, formats, and cross-field rules in ordinary caller code after the answer
+arrives, and treat a full JSON Schema through `Schema.json(...)` as the explicit
+waiver a caller signs only when it owns that risk.
+
 ## Akuma Names
 
 An Akuma name selects a reusable worker configuration, not an individual worker.

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-akuma/references/automation.md

@@ -53,14 +53,13 @@ investigation, not as a supposedly fresh judge of its own earlier answer.
 ## Public Entry And A Single Structured Turn
 
 Run an ESM script (`.mjs`) in a project where `@astrosheep/keiyaku` resolves.
-The Zod examples also need `zod` available to the script. A globally installed
-CLI alone does not establish Node package resolution for an arbitrary script.
+Import `z` from the package root; a globally installed CLI alone does not
+establish Node package resolution for an arbitrary script.
 Use `keiyaku ls aku/` to select an available Archetype; names and upstream model
 availability are installation-specific.
 
 ```js
-import { Akuma, Schema, World } from "@astrosheep/keiyaku";
-import { z } from "zod";
+import { Akuma, World, z } from "@astrosheep/keiyaku";
 
 const root = await World.at(process.cwd());
 const archetype = process.env.AKUMA_ARCHETYPE;
@@ -74,11 +73,11 @@ const worker = await Akuma.birth(archetype, {
 console.error("worker", worker.id); // Keep the complete AkuId.
 await worker.idle(); // Let the prompt-free birth Body settle before a schema Tell.
 
-const Finding = Schema.zod(z.object({
+const Finding = z.object({
   claim: z.string(),
   evidence: z.array(z.object({ path: z.string(), observation: z.string() })),
   unknowns: z.array(z.string()),
-}).strict());
+});
 
 const finding = await worker.tell(
   "Read the repository guidance and relevant owner documents. Read only; " +
@@ -90,9 +89,19 @@ console.log(JSON.stringify(finding, null, 2));
 ```
 
 `birth` does not submit a prompt. Plain `tell` returns answer text; schema
-`tell` returns the decoded value, not a JSON string to scrape. For a JSON
-Schema and a custom decoder, use `Schema.json(document, decode)` instead of
-`Schema.zod(...)`.
+`tell` returns the decoded value, not a JSON string to scrape. Pass the schema
+directly; any Standard Schema v1 value works the same way. The explicit
+`Schema.zod(...)` wrapper still works, and `Schema.json(document, decode)` is
+the escape hatch for a caller-owned JSON Schema and custom decoder.
+
+Keep an answer contract inside simple JSON shape vocabulary: objects, arrays,
+strings, numbers, booleans, enums, literals, and optional or nullable fields.
+Do not attach `.max`, `.min`, `.regex`, `.refine`, `.transform`, or other
+constraint methods. The provider must satisfy the contract, and a fragile or
+unrepresentable constraint fails the loop after submission; the seam refuses
+such a schema at submission and names the offending keyword instead. Enforce
+bounds, formats, and cross-field rules in ordinary caller code after the answer
+arrives.
 
 Schema makes shape machine-usable, not claims true. Include evidence and
 unknowns in the requested value; acceptance still needs a suitable judge.
@@ -106,14 +115,14 @@ the prompts, schemas, routing, and selection to the task rather than always
 running this exact pipeline.
 
 ```js
-const Claims = Schema.zod(z.object({
-  claims: z.array(z.object({ id: z.string(), text: z.string() })).max(12),
-}).strict());
-const Verdict = Schema.zod(z.object({
+const Claims = z.object({
+  claims: z.array(z.object({ id: z.string(), text: z.string() })),
+});
+const Verdict = z.object({
   verdict: z.enum(["supported", "contradicted", "unknown"]),
   evidence: z.array(z.object({ path: z.string(), observation: z.string() })),
   reason: z.string(),
-}).strict());
+});
 
 // Caller-owned concurrency helper, not a Keiyaku API.
 async function mapSettled(items, concurrency, run) {
@@ -145,6 +154,9 @@ const { claims } = await worker.tell(
 if (new Set(claims.map(c => c.id)).size !== claims.length) {
   throw new Error("Duplicate claim ids");
 }
+if (claims.length > 12) {
+  throw new Error("Claim list exceeded the 12-claim budget");
+}
 
 async function freshJudge(prompt) {
   const judge = await Akuma.birth(archetype, { root, cwd: process.cwd(), readonly: true });
@@ -200,6 +212,13 @@ pairwise comparisons, experiment queues, or adaptive sampling instead.
 - `idle({ timeoutMs })` stops waiting at its timeout, not the worker. A
   `Promise.race` timeout also does not cancel a Tell. Use explicit lifecycle
   operations when you intend to interrupt or stop work.
+- `idle()` resolves an `AkumaIdleResult` saying why it returned, so there is
+  no need to re-poll `status()` to distinguish the outcomes. A completed wait
+  resolves `{ kind: "idle", status, reason }` with `reason` naming the settled
+  life (`"asleep"`, `"killed"`, `"hung"`, `"untidy"`, or `"stranded"`); a
+  passed deadline resolves `{ kind: "timeout", status, reason }` with `reason`
+  naming what was still outstanding as `{ running, pendingTell }`. Both arms
+  carry the final observed `status`.
 - Keep input ids, AkuIds, terminal results, failures, and completed stages in
   caller-owned artifacts if the run must survive its orchestrator process.
   On return, `Akuma.select(root, savedId)` reconnects synchronously; `status()`

package/build/src/akuma/akuma-handle.d.ts

@@ -2,6 +2,7 @@ import { type TellResult, type TellWakeRuntime } from "./body.js";
 import { HeldAkumaLeash, type KillEvidence } from "./heart/index.js";
 import { type AkuId, type AkumaPaths } from "./identity.js";
 import { type ActivityHistory, type ExactHistory } from "./projection.js";
+import { type WaitReason } from "./akuma-observe.js";
 import type { AkumaCallExecution, AkumaStatus, ForkReceipt, InterruptReceipt } from "./akuma.js";
 import type { WorldRoot } from "../world.js";
 declare const CALL_EXECUTION: unique symbol;
@@ -25,12 +26,21 @@ export declare class AkumaHandle {
         since?: number;
         limit?: number;
     }>): Promise<ActivityHistory | ExactHistory>;
+    waitReceipt(predicate?: (status: AkumaStatus) => boolean, options?: Readonly<{
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }>): Promise<Readonly<{
+        reason: WaitReason;
+        status: AkumaStatus;
+    }>>;
     wait(predicate?: (status: AkumaStatus) => boolean, options?: Readonly<{
         timeoutMs?: number;
+        signal?: AbortSignal;
     }>): Promise<AkumaStatus>;
     tell(body: string, tellId?: string, recordedAt?: string, runtime?: TellWakeRuntime, options?: Readonly<{
         schemaJson?: string;
         initiator?: string;
+        signal?: AbortSignal;
     }>): Promise<TellResult>;
     interrupt(body: string, options?: Readonly<{
         tellId?: string;

package/build/src/akuma/akuma-handle.js

@@ -8,10 +8,8 @@ import { resolveProviderExecution } from "./providers/index.js";
 import { publishAkuma } from "./publication.js";
 import { spawnAkumaBody } from "./body.js";
 import { AkumaNotBornError } from "./akuma-errors.js";
-import { bornStatus, defaultWaitComplete, readWaitComplete } from "./akuma-observe.js";
+import { bornStatus, defaultWaitComplete, readWaitComplete, waitForObservation, } from "./akuma-observe.js";
 const CALL_EXECUTION = Symbol("akuma-call-execution");
-const POLL_MS = 100;
-const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
 function diagnostic(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -33,10 +31,13 @@ async function takeLeashUntilSignal(paths, bodySequence, signal, unbounded = fal
 export async function settleAkumaKill(paths, signal, retainLeash = false) {
     const request = await requestStop(paths, new Date().toISOString(), signal);
     if (request.kind !== "requested") {
+        // A witnessed Body was already settled: the kill witness Heart recorded is
+        // the kill evidence, not a stop outcome.
+        const evidence = request.kind === "witnessed" ? "killed" : request.kind;
         if (!retainLeash)
-            return { evidence: request.kind };
+            return { evidence };
         const leash = await acquireLeash(paths, signal === undefined ? {} : { signal });
-        return leash === null ? { evidence: "unavailable" } : { evidence: request.kind, leash };
+        return leash === null ? { evidence: "unavailable" } : { evidence, leash };
     }
     const target = request.body;
     const waited = await takeLeashUntilSignal(paths, target.sequence, signal);
@@ -131,24 +132,26 @@ export class AkumaHandle {
             limit,
         });
     }
-    async wait(predicate = defaultWaitComplete, options = {}) {
+    async waitReceipt(predicate = defaultWaitComplete, options = {}) {
         if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) {
             throw new TypeError("Akuma wait timeoutMs must be a nonnegative finite millisecond duration");
         }
-        const deadline = options.timeoutMs === undefined ? undefined : performance.now() + options.timeoutMs;
-        for (;;) {
-            if (predicate !== defaultWaitComplete ||
-                (deadline !== undefined && performance.now() >= deadline) ||
-                (await readWaitComplete(this.worldPath, this.id))) {
-                const status = await this.status();
-                if (predicate(status) || (deadline !== undefined && performance.now() >= deadline))
-                    return status;
-            }
-            await wait(deadline === undefined ? POLL_MS : Math.min(POLL_MS, Math.max(0, deadline - performance.now())));
-        }
+        const waited = await waitForObservation({
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(predicate === defaultWaitComplete
+                ? { probe: async () => await readWaitComplete(this.worldPath, this.id) }
+                : {}),
+            observe: async () => await this.status(),
+            complete: predicate,
+        });
+        return { reason: waited.reason, status: waited.value };
+    }
+    async wait(predicate = defaultWaitComplete, options = {}) {
+        return (await this.waitReceipt(predicate, options)).status;
     }
     async tell(body, tellId = randomUUID(), recordedAt = new Date().toISOString(), runtime, options = {}) {
-        const { schemaJson, initiator } = options;
+        const { schemaJson, initiator, signal } = options;
         const admitted = await recordTell(this.paths, {
             kind: "tell",
             id: tellId,
@@ -159,7 +162,7 @@ export class AkumaHandle {
         });
         if (admitted.kind === "not-born")
             throw new AkumaNotBornError(this.id);
-        return await wakeRecordedTell(this.paths, admitted.tell.id, runtime);
+        return await wakeRecordedTell(this.paths, admitted.tell.id, runtime, signal);
     }
     async interrupt(body, options = {}) {
         const request = await requestPause(this.paths, new Date().toISOString(), options.signal);
@@ -209,7 +212,7 @@ export class AkumaHandle {
         return {
             kind: "interrupted",
             putDown,
-            tell: await wakeRecordedTell(this.paths, recorded.tellId, options.runtime),
+            tell: await wakeRecordedTell(this.paths, recorded.tellId, options.runtime, options.signal),
         };
     }
     async fork(input) {

package/build/src/akuma/akuma-instance.d.ts

@@ -1,13 +1,19 @@
 import type { AllowedAction } from "./allowed.js";
 import type { AkumaStatus } from "./akuma.js";
 import type { InterruptReceipt, KillEvidence } from "./akuma.js";
+import { type WaitReason } from "./akuma-observe.js";
 import { type AkuId } from "./identity.js";
 import { type ActivityHistory } from "./projection.js";
 import type { Settings } from "../settings.js";
 import type { WorldRoot } from "../world.js";
-import { type Schema } from "./schema.js";
+import { type Schema, type StandardSchemaV1 } from "./schema.js";
 export type AkumaIdleOptions = Readonly<{
     timeoutMs?: number;
+    signal?: AbortSignal;
+}>;
+export type AkumaIdleResult = Readonly<{
+    reason: WaitReason;
+    status: AkumaStatus;
 }>;
 export type AkumaHistoryOptions = Readonly<{
     before?: number;
@@ -26,7 +32,7 @@ export type AkumaBirthInput = Readonly<{
     allowed?: readonly AllowedAction[];
 }>;
 export type AkumaTellOptions<T> = Readonly<{
-    schema: Schema<T>;
+    schema: Schema<T> | StandardSchemaV1<T>;
     interrupt?: boolean;
     initiator?: string;
 }>;
@@ -39,13 +45,14 @@ export declare class Akuma {
     static select(root: WorldRoot, selector: string): Akuma;
     tell(text: string, options?: Readonly<{
         initiator?: string;
+        signal?: AbortSignal;
     }>): Promise<string>;
-    tell<T>(text: string, options: AkumaTellOptions<T>): Promise<T>;
+    tell<T>(text: string, options: AkumaTellOptions<T> & AkumaSignalOptions): Promise<T>;
     status(): Promise<AkumaStatus>;
     interrupt(text: string, options?: AkumaSignalOptions & Readonly<{
         initiator?: string;
     }>): Promise<InterruptReceipt>;
-    idle(options?: AkumaIdleOptions): Promise<void>;
+    idle(options?: AkumaIdleOptions): Promise<AkumaIdleResult>;
     history(options?: AkumaHistoryOptions): Promise<ActivityHistory>;
     kill(options?: AkumaSignalOptions): Promise<KillEvidence>;
 }

package/build/src/akuma/akuma-instance.js

@@ -4,15 +4,14 @@ import { spawnAkumaBody } from "./body.js";
 import { decodeAllowedActions, unionAllowedActions } from "./allowed.js";
 import { AkumaDecodeError, AkumaProviderError } from "./akuma-errors.js";
 import { AkumaHandle } from "./akuma-handle.js";
-import { POLL_MS, defaultWaitComplete } from "./akuma.js";
-import { bornStatus } from "./akuma-observe.js";
+import { bornStatus, defaultWaitComplete, waitForObservation } from "./akuma-observe.js";
 import { loadArchetype } from "./archetype.js";
 import { activitySlice, readTell, readTurn } from "./heart/index.js";
 import { parseAkuId, pathsForAkuId } from "./identity.js";
 import { birthAkuma, launchAkuma } from "./publication.js";
 import { projectTurns, selectHistory } from "./projection.js";
 import { settings as readSettings } from "../settings.js";
-import { schemaJsonText } from "./schema.js";
+import { schemaFromStandard, schemaJsonText } from "./schema.js";
 import { abortable } from "./abort.js";
 const HISTORY_LIMIT = 12;
 function signalOption(value) {
@@ -22,25 +21,37 @@ function signalOption(value) {
         throw new TypeError("signal must be an AbortSignal");
     return value;
 }
-function wait(milliseconds) {
-    return new Promise((resolve) => setTimeout(resolve, milliseconds));
-}
 function recordedTell(result) {
     if (result.wake.kind === "failed")
         throw new AkumaProviderError(result.wake.diagnostic);
     return { tellId: result.admission.tellId };
 }
-async function recordPlainTell(id, root, body, tellId, initiator) {
-    const admitted = await new AkumaHandle(id, root).tell(body, tellId, undefined, undefined, initiator === undefined ? {} : { initiator });
+async function recordPlainTell(input) {
+    const { id, root, body, tellId, initiator, signal } = input;
+    const admitted = await new AkumaHandle(id, root).tell(body, tellId, undefined, undefined, {
+        ...(initiator === undefined ? {} : { initiator }),
+        ...(signal === undefined ? {} : { signal }),
+    });
     return recordedTell(admitted);
 }
+function plainTellInput(input) {
+    return {
+        id: input.id,
+        root: input.root,
+        body: input.body,
+        tellId: input.tellId,
+        ...(input.options?.initiator === undefined ? {} : { initiator: input.options.initiator }),
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    };
+}
 async function recordSchemaTell(input) {
-    const { id, body, tellId, options, root } = input;
-    if (options.interrupt === true) {
+    const { id, body, tellId, schema, root } = input;
+    if (input.interrupt === true) {
         const interrupted = await new AkumaHandle(id, root).interrupt(body, {
             tellId,
-            schemaJson: schemaJsonText(options.schema),
-            ...(options.initiator === undefined ? {} : { initiator: options.initiator }),
+            schemaJson: schemaJsonText(schema),
+            ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
         });
         if (interrupted.kind === "unavailable") {
             throw new AkumaProviderError(`schema interrupt unavailable: ${interrupted.evidence}`);
@@ -48,8 +59,9 @@ async function recordSchemaTell(input) {
         return recordedTell(interrupted.tell);
     }
     const admitted = await new AkumaHandle(id, root).tell(body, tellId, undefined, undefined, {
-        schemaJson: schemaJsonText(options.schema),
-        ...(options.initiator === undefined ? {} : { initiator: options.initiator }),
+        schemaJson: schemaJsonText(schema),
+        ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
     });
     return recordedTell(admitted);
 }
@@ -66,19 +78,21 @@ async function boundOutcome(paths, tell) {
     const turn = await readTurn(paths, tell.binding.turnSequence);
     return turn?.end?.outcome ?? null;
 }
-async function awaitTellOutcome(paths, tellId) {
-    for (;;) {
-        const tell = await readTell(paths, tellId);
-        if (tell === null)
-            throw new AkumaProviderError(`recorded Tell ${tellId} is missing from Heart`);
-        const outcome = await boundOutcome(paths, tell);
-        if (outcome !== null)
-            return outcome;
-        if (tell.state === "told" && tell.binding === undefined) {
-            throw new AkumaProviderError(`recorded Tell ${tellId} reached a terminal delivery without a Turn binding`);
-        }
-        await wait(POLL_MS);
-    }
+async function awaitTellOutcome(paths, tellId, signal) {
+    const waited = await waitForObservation({
+        ...(signal === undefined ? {} : { signal }),
+        observe: async () => {
+            const tell = await readTell(paths, tellId);
+            if (tell === null)
+                throw new AkumaProviderError(`recorded Tell ${tellId} is missing from Heart`);
+            const outcome = await boundOutcome(paths, tell);
+            return { outcome, terminalWithoutTurn: tell.state === "told" && tell.binding === undefined };
+        },
+        complete: (observed) => observed.outcome !== null || observed.terminalWithoutTurn,
+    });
+    if (waited.value.outcome !== null)
+        return waited.value.outcome;
+    throw new AkumaProviderError(`recorded Tell ${tellId} reached a terminal delivery without a Turn binding`);
 }
 export class Akuma {
     id;
@@ -134,20 +148,34 @@ export class Akuma {
     async tell(text, options) {
         if (typeof text !== "string")
             throw new TypeError("Akuma tell text must be a string");
+        const signal = signalOption(options?.signal);
+        signal?.throwIfAborted();
         const tellId = randomUUID();
-        const recorded = options === undefined || !("schema" in options)
-            ? await recordPlainTell(this.id, this.root, text, tellId, options?.initiator)
-            : await recordSchemaTell({
+        const schemaOptions = options !== undefined && "schema" in options ? options : undefined;
+        const schema = schemaOptions === undefined ? undefined : schemaFromStandard(schemaOptions.schema);
+        const recorded = schemaOptions === undefined || schema === undefined
+            ? await recordPlainTell(plainTellInput({
                 id: this.id,
+                root: this.root,
                 body: text,
                 tellId,
                 options,
+                signal,
+            }))
+            : await recordSchemaTell({
+                id: this.id,
+                body: text,
+                tellId,
+                schema,
                 root: this.root,
+                ...(schemaOptions.interrupt === undefined ? {} : { interrupt: schemaOptions.interrupt }),
+                ...(schemaOptions.initiator === undefined ? {} : { initiator: schemaOptions.initiator }),
+                ...(signal === undefined ? {} : { signal }),
             });
-        const outcome = await awaitTellOutcome(this.paths, recorded.tellId);
+        const outcome = await awaitTellOutcome(this.paths, recorded.tellId, signal);
         if (outcome.kind !== "answered")
             outcomeError(outcome);
-        if (options === undefined || !("schema" in options))
+        if (schema === undefined)
             return outcome.answer;
         const raw = outcome.answerJson ?? outcome.answer;
         let parsed;
@@ -158,7 +186,7 @@ export class Akuma {
             throw new AkumaDecodeError(error instanceof Error ? error.message : "Answer is not valid JSON", outcome.answer);
         }
         try {
-            return options.schema.decode(parsed);
+            return schema.decode(parsed);
         }
         catch (error) {
             throw new AkumaDecodeError(error instanceof Error ? error.message : "Answer failed schema decode", outcome.answer);
@@ -185,19 +213,20 @@ export class Akuma {
         if (typeof options !== "object" || options === null || Array.isArray(options)) {
             throw new TypeError("Akuma idle options must be an object");
         }
-        const unknown = Object.keys(options).find((key) => key !== "timeoutMs");
+        const unknown = Object.keys(options).find((key) => key !== "timeoutMs" && key !== "signal");
         if (unknown !== undefined)
             throw new TypeError(`Akuma idle options has unknown field: ${unknown}`);
         if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) {
             throw new TypeError("Akuma idle timeoutMs must be a nonnegative finite millisecond duration");
         }
-        const deadline = options.timeoutMs === undefined ? undefined : performance.now() + options.timeoutMs;
-        for (;;) {
-            const observed = await bornStatus(this.paths, this.id, { aperture: "monitoring" });
-            if (defaultWaitComplete(observed.status) || (deadline !== undefined && performance.now() >= deadline))
-                return;
-            await wait(deadline === undefined ? POLL_MS : Math.min(POLL_MS, Math.max(0, deadline - performance.now())));
-        }
+        const signal = signalOption(options.signal);
+        const waited = await waitForObservation({
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            ...(signal === undefined ? {} : { signal }),
+            observe: async () => (await bornStatus(this.paths, this.id, { aperture: "monitoring" })).status,
+            complete: defaultWaitComplete,
+        });
+        return { reason: waited.reason, status: waited.value };
     }
     async history(options = {}) {
         if (typeof options !== "object" || options === null || Array.isArray(options)) {

package/build/src/akuma/akuma-observe.d.ts

@@ -1,5 +1,5 @@
 import { type AkuId, type AkumaPaths } from "./identity.js";
-import { selectHistory, type ActivityHistory, type ActivitySnapshot } from "./projection.js";
+import { selectHistory, type ActivityHistory, type ActivityRow, type ActivitySnapshot } from "./projection.js";
 import type { WorldRoot } from "../world.js";
 import type { AkumaListRow, AkumaStatus, UnbornAkumaListRow } from "./akuma.js";
 export declare function fleetListRow(paths: AkumaPaths, expected: AkuId): Promise<AkumaListRow | UnbornAkumaListRow>;
@@ -7,6 +7,14 @@ export type BudgetedStatusObservation = Readonly<{
     status: AkumaStatus;
     ordinarySelected: number;
 }>;
+/**
+ * The internal live-observation companion for one status frontier.  It is not
+ * part of status or any returned facade result: viewers receive it only while
+ * an observation loop is still streaming.
+ */
+export type LiveStatusObservation = BudgetedStatusObservation & Readonly<{
+    rows: readonly ActivityRow[];
+}>;
 export declare function bornStatus(paths: AkumaPaths, expected: AkuId, input: Readonly<{
     aperture: "monitoring" | "receipt";
     ordinaryBudget?: number;
@@ -17,18 +25,43 @@ export declare function readBudgetedStatus(worldPath: WorldRoot, id: AkuId, inpu
     ordinaryBudget?: number;
     admittedTellId?: string;
 }>): Promise<BudgetedStatusObservation>;
+export declare function readLiveStatus(worldPath: WorldRoot, id: AkuId, input: Readonly<{
+    aperture: "monitoring" | "receipt";
+    ordinaryBudget?: number;
+    admittedTellId?: string;
+}>): Promise<LiveStatusObservation>;
 export declare function defaultWaitComplete(status: AkumaStatus): boolean;
 export declare function readWaitComplete(worldPath: WorldRoot, id: AkuId): Promise<boolean>;
+export type WaitReason = "completed" | "deadline";
+/**
+ * The one deadline-aware observation loop for public Akuma waiting.  It always
+ * reads once before judging a passed deadline, so a zero-duration wait remains
+ * an honest final snapshot and completion wins at the deadline edge.
+ */
+export declare function waitForObservation<T>(input: Readonly<{
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    probe?(): Promise<boolean>;
+    observe(): Promise<T>;
+    complete(value: T): boolean;
+    onObserve?(value: T): void | Promise<void>;
+}>): Promise<Readonly<{
+    reason: WaitReason;
+    value: T;
+}>>;
 /**
  * Successive status observations of one already born Akuma until its
- * observation window closes. Every status observed while the window is open is
- * reported to `observe`; the window's last status is returned. A window that is
- * already closed, or an Akuma already at its completion judgment, reports
- * nothing and returns the current status.
+ * observation window closes. Every acquired observation is reported to
+ * `observe` before completion or deadline judgment, including the first
+ * already-complete observation; the last status is returned.
  */
 export declare function observeAkumaStatus(worldPath: WorldRoot, expected: AkuId, input: Readonly<{
     timeoutMs: number;
-    observe: (status: AkumaStatus) => void;
-}>): Promise<AkumaStatus>;
+    signal?: AbortSignal;
+    observe: (status: LiveStatusObservation) => void;
+}>): Promise<Readonly<{
+    reason: WaitReason;
+    status: AkumaStatus;
+}>>;
 export declare function readAkumaBirthCwd(worldPath: WorldRoot, id: AkuId): Promise<string>;
 export { selectHistory, type ActivityHistory, type ActivitySnapshot };