@astrosheep/keiyaku 4.6.7 → 4.6.9

package/build/skills/keiyaku-debt/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: keiyaku-debt
+description: >-
+  Must read when recording confirmed unresolved work or dependencies in Debts.
+---
+
+# Keiyaku Debt
+
+A Debt records confirmed unresolved work and its relationships. Debt is an
+independent product; it is not a Contract, Arc, Akuma, permission, acceptance
+boundary, or fulfillment lifecycle.
+
+## 1. When To Use A Debt
+
+Use a Debt when confirmed unresolved work or a dependency must outlive the
+current conversation. Keep plans and execution progress in reasoning or session
+notes instead.
+
+- Use a `kei` for one independently acceptable outcome.
+- Use an Arc for a chapter inside one `kei`.
+- Use a Debt for confirmed unresolved work and its prerequisites.
+- Do not create a Debt just to mirror a `kei`.
+
+A Debt may exist without a Contract. Associating a Debt with a `kei` does not
+transfer the Contract's holder, acceptance, or lifecycle to the Debt.
+
+## 2. Relationships And Parallel Work
+
+Independent work may proceed in parallel when its dependencies allow it.
+Debt records no execution-progress state.
+
+Use the relationships for their actual meanings:
+
+- `needs` means this Debt must wait for another Debt to become terminal.
+- `parent` groups decomposition; it does not create a dependency.
+- `supersedes` points to work replaced by this Debt.
+- `relates` records a connection without affecting readiness.
+
+Only `needs` orders work. Do not add it because Debts touch the same Region or
+because one Debt is related to another. A terminal Debt releases its dependents.
+
+## 3. Debt Commands
+
+Create and inspect Debts:
+
+```bash
+keiyaku debt add "<title>"
+keiyaku debt add "<title>" --priority 1 --needs <debt-id>
+keiyaku debt show <debt-id>
+keiyaku debt ls
+keiyaku debt ready
+keiyaku debt blocked
+keiyaku debt tree <debt-id>
+keiyaku debt doctor
+```
+
+Use complete Debt IDs for targeted commands. `ls`, `ready`, and `blocked` use
+the current namespace; use `--world` to inspect the complete Debt world.
+
+Close work:
+
+```bash
+keiyaku debt done <debt-id>...
+keiyaku debt drop <debt-id>... --note "<reason>"
+```
+
+Use `done` when the Debt is complete. Use `drop` when it is no longer owed.
+Both terminal states release dependent Debts. Unresolved `needs` appear in
+`blocked`; open work with all prerequisites terminal appears in `ready`.
+
+Update a Debt without changing its lifecycle:
+
+```bash
+keiyaku debt update <debt-id> --title "<title>"
+keiyaku debt update <debt-id> --body "<body>"
+keiyaku debt update <debt-id> --needs <debt-id>
+```
+
+## 4. After Creating A Debt
+
+Read the returned Debt identity. Then:
+
+1. Add or remove relationships when the confirmed prerequisites change.
+2. Mark completed work `done`, or work no longer owed `drop` with a reason.
+3. Use `ready`, `blocked`, `tree`, or `doctor` to inspect the current ledger.
+
+Debt records unresolved work. It does not perform the work, claim acceptance,
+assign a holder, or decide what a Contract may accept.
+
+Read `keiyaku-bind` for Contract authoring and `keiyaku-workflow` for Contract
+lifecycle.

package/build/skills/keiyaku-workflow/SKILL.md

@@ -33,7 +33,7 @@ to create parallel work.
 
 - Separate `kei`s have independently acceptable outcomes.
 - An Arc is a chapter of one `kei`; it is not separately accepted.
-- A Task stores decomposition or dependencies that outlive this conversation.
+- A Debt records confirmed unresolved work and its dependencies.
 
 Use `after` only when one `kei` requires another to be accepted first. Ordinary
 overlap is not a dependency.
@@ -101,7 +101,7 @@ authority.
 | Role | Grant at birth | Return |
 | --- | --- | --- |
 | Holder | The actions the delegated loop will perform; include `contract.review` when this holder will review. Commission with the `kei`, current Arc when one exists, appointed worktree, and holder duties. | Acceptance or abandonment, with receipts. |
-| Deliverer | The ordinary baseline: every Task mutation, Contract audit and delivery, and Akuma management. `keiyaku -C <repo> call worker --alias @deliverer --contract <kei/...> --workdir <appointed-path> -` | The delivery receipt. |
+| Deliverer | The ordinary baseline: every Debt mutation, Contract audit and delivery, and Akuma management. `keiyaku -C <repo> call worker --alias @deliverer --contract <kei/...> --workdir <appointed-path> -` | The delivery receipt. |
 | Reviewer | `--allowed contract.review`: `keiyaku -C <repo> call review-akuma --alias @reviewer --contract <kei/...> --workdir <appointed-path> --allowed contract.review -` | The verdict receipt. Without the grant, `not-allowed` refuses and no verdict is recorded. |
 
 An Archetype's explicit allowed set replaces the ordinary baseline; check

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

@@ -1,3 +1,4 @@
+import { type AkumaCaller } from "./caller.js";
 import type { Settings } from "../settings.js";
 import type { WorldRoot } from "../world.js";
 import { type AllowedAction } from "./allowed.js";
@@ -17,6 +18,7 @@ export type AkumaCallInput = Readonly<{
     allowed?: readonly AllowedAction[];
     schema?: Schema<unknown>;
     initiator?: string;
+    caller?: AkumaCaller;
     signal?: AbortSignal;
 }>;
 type AkumaCallContext = Readonly<{

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

@@ -1,3 +1,4 @@
+import { decodeAkumaCaller } from "./caller.js";
 import { randomUUID } from "node:crypto";
 import { settings as readSettings } from "../settings.js";
 import { readAkumaBirthCwd } from "./akuma-observe.js";
@@ -7,7 +8,7 @@ import { AkumaArchetypeError, loadPreparedArchetype } from "./archetype.js";
 import { spawnAkumaBody } from "./body.js";
 import { canonicalBirthCwd } from "./call-input.js";
 import { requestForwardedAkumaCall } from "./call-request.js";
-import { archetypeName } from "./identity.js";
+import { validateAkumaName } from "../identity/normalize.js";
 import { PreparedCallAdmissionError, executePreparedCall } from "./publication.js";
 import { executionChannel } from "./requests.js";
 async function admitBodyRequest(input) {
@@ -24,6 +25,8 @@ async function admitBodyRequest(input) {
         ...(input.call.initialTell === undefined ? {} : { initialTell: input.call.initialTell }),
         ...(cwd === undefined ? {} : { cwd }),
         recipe: input.recipe,
+        ...(input.call.initiator === undefined ? {} : { birthInitiator: input.call.initiator }),
+        ...(input.call.contractId === undefined ? {} : { contractId: input.call.contractId }),
         ...(input.call.signal === undefined ? {} : { signal: input.call.signal }),
     });
     const bornCwd = await readAkumaBirthCwd(input.path, response.id);
@@ -50,6 +53,7 @@ async function admitDirect(input) {
         result = await executePreparedCall({
             archetype: input.archetype.name,
             cwd,
+            ...(input.call.caller === undefined ? {} : { caller: input.call.caller }),
             ...(input.call.initialTell === undefined ? {} : { initialTell: input.call.initialTell }),
             ...(input.call.signal === undefined ? {} : { signal: input.call.signal }),
             custody: {
@@ -59,6 +63,7 @@ async function admitDirect(input) {
                 spawn: async (launch) => await spawnAkumaBody({
                     paths: launch.paths,
                     seed: launch.seed,
+                    ...(input.call.initiator === undefined ? {} : { birthInitiator: input.call.initiator }),
                     ...(input.call.contractId === undefined ? {} : { completion: { contractId: input.call.contractId } }),
                 }),
                 admitInitialTell: async ({ id, initialTell, signal }) => await new AkumaOwner(id, input.path).admitInitialTell(initialTell, {
@@ -93,7 +98,8 @@ async function admitDirect(input) {
  * then invoke the P3 prepared-call executor under local or request custody.
  */
 export async function admitAkumaCall(path, configuration, input, context) {
-    const name = archetypeName(input.archetype);
+    decodeAkumaCaller(input.caller);
+    const name = validateAkumaName(input.archetype);
     const home = configuration.home === undefined ? {} : { home: configuration.home };
     const settings = configuration.settings ?? (await readSettings({ root: path, ...home }));
     const archetype = await loadPreparedArchetype({ name, project: path, ...home, settings });

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

@@ -1,5 +1,7 @@
+import type { AkumaCaller } from "./caller.js";
 import type { Settings } from "../settings.js";
 import type { WorldRoot } from "../world.js";
+import type { AkumaStreamSnapshot } from "./akuma-stream.js";
 import { type InterruptReceipt } from "./akuma-owner.js";
 import { type AkumaStatus } from "./akuma.js";
 import type { AllowedAction } from "./allowed.js";
@@ -24,12 +26,21 @@ export type AkumaHistoryOptions = Readonly<{
 export type AkumaSignalOptions = Readonly<{
     signal?: AbortSignal;
 }>;
+/** Observes only plugin diagnostics produced in this host, never remote Body logs. */
+export type AkumaHostOptions = Readonly<{
+    reportDiagnostic?: (message: string) => void;
+}>;
+/** Capture the observer capability, not the caller's mutable options object. */
+export declare function captureAkumaHostDiagnostic(host: AkumaHostOptions | undefined): AkumaHostOptions["reportDiagnostic"];
 export type AkumaBirthInput = Readonly<{
     root: WorldRoot;
     cwd?: string;
     home?: string;
     settings?: Settings;
     allowed?: readonly AllowedAction[];
+    caller?: AkumaCaller;
+    initiator?: string;
+    host?: AkumaHostOptions;
 }>;
 export type AkumaTellOptions = AkumaSignalOptions & Readonly<{
     interrupt?: boolean;
@@ -43,10 +54,11 @@ export type { AkumaAskResult, AkumaTellResult, InterruptReceipt, KillEvidence };
 export declare class Akuma {
     readonly id: AkuId;
     private readonly root;
+    private readonly reportDiagnostic;
     private constructor();
     private owner;
     static birth(archetype: string, input: AkumaBirthInput): Promise<Akuma>;
-    static select(root: WorldRoot, selector: string): Akuma;
+    static select(root: WorldRoot, selector: string, host?: AkumaHostOptions): Akuma;
     tell(text: string, options?: AkumaTellOptions): Promise<AkumaTellResult>;
     ask(text: string, options?: AkumaAskOptions<string>): Promise<AkumaAskResult<string>>;
     ask<T>(text: string, options: AkumaAskOptions<T> & Readonly<{
@@ -55,5 +67,6 @@ export declare class Akuma {
     status(): Promise<AkumaStatus>;
     idle(options?: AkumaIdleOptions): Promise<AkumaIdleResult>;
     history(options?: AkumaHistoryOptions): Promise<ActivityHistory>;
+    stream(options?: AkumaSignalOptions): AsyncIterable<AkumaStreamSnapshot>;
     kill(options?: AkumaSignalOptions): Promise<KillEvidence>;
 }

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

@@ -1,4 +1,4 @@
-import { outcomePluginObserver } from "../plugin/akuma-signals.js";
+import { outcomePluginObserver, stderrPluginDiagnostic } from "../plugin/akuma-signals.js";
 import { abortable } from "./abort.js";
 import { admitAkumaCall } from "./akuma-call.js";
 import { defaultWaitComplete } from "./akuma-observe.js";
@@ -6,6 +6,20 @@ import { AkumaOwner } from "./akuma-owner.js";
 import { decodeAskObservation, executeAskAkuma, executeTellAkuma } from "./akuma-selection-execution.js";
 import { parseAkuId } from "./identity.js";
 import { schemaFromStandard, schemaJsonText } from "./schema.js";
+/** Capture the observer capability, not the caller's mutable options object. */
+export function captureAkumaHostDiagnostic(host) {
+    if (host === undefined)
+        return undefined;
+    if (typeof host !== "object" || host === null || Array.isArray(host))
+        throw new TypeError("Akuma host options must be an object");
+    const unknown = Object.keys(host).find((key) => key !== "reportDiagnostic");
+    if (unknown !== undefined)
+        throw new TypeError(`Akuma host options has unknown field: ${unknown}`);
+    const reportDiagnostic = host.reportDiagnostic;
+    if (reportDiagnostic !== undefined && typeof reportDiagnostic !== "function")
+        throw new TypeError("Akuma host reportDiagnostic must be a function");
+    return reportDiagnostic;
+}
 function signalOption(value) {
     if (value === undefined)
         return undefined;
@@ -16,13 +30,15 @@ function signalOption(value) {
 export class Akuma {
     id;
     root;
-    constructor(id, root) {
+    reportDiagnostic;
+    constructor(id, root, reportDiagnostic) {
         this.id = id;
         this.root = root;
+        this.reportDiagnostic = reportDiagnostic;
         Object.freeze(this);
     }
     owner(observing = false) {
-        return new AkumaOwner(this.id, this.root, observing ? outcomePluginObserver({ world: this.root, reportDiagnostic: console.error }) : undefined);
+        return new AkumaOwner(this.id, this.root, observing ? outcomePluginObserver({ world: this.root, reportDiagnostic: this.reportDiagnostic }) : undefined);
     }
     static async birth(archetype, input) {
         if (typeof input !== "object" || input === null || Array.isArray(input)) {
@@ -30,6 +46,7 @@ export class Akuma {
         }
         if (typeof input.root !== "string")
             throw new TypeError("Akuma birth root must be a WorldRoot");
+        const reportDiagnostic = captureAkumaHostDiagnostic(input.host) ?? stderrPluginDiagnostic;
         const admitted = await admitAkumaCall(input.root, {
             ...(input.home === undefined ? {} : { home: input.home }),
             ...(input.settings === undefined ? {} : { settings: input.settings }),
@@ -37,15 +54,18 @@ export class Akuma {
             archetype,
             ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
             ...(input.allowed === undefined ? {} : { allowed: input.allowed }),
+            ...(input.caller === undefined ? {} : { caller: input.caller }),
+            ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
         }, {});
         if (admitted.failure !== undefined)
             throw admitted.failure;
-        return new Akuma(admitted.id, input.root);
+        return new Akuma(admitted.id, input.root, reportDiagnostic);
     }
-    static select(root, selector) {
+    static select(root, selector, host) {
         if (typeof root !== "string")
             throw new TypeError("Akuma.select root must be a WorldRoot");
-        return new Akuma(parseAkuId(selector).id, root);
+        const reportDiagnostic = captureAkumaHostDiagnostic(host) ?? stderrPluginDiagnostic;
+        return new Akuma(parseAkuId(selector).id, root, reportDiagnostic);
     }
     async tell(text, options = {}) {
         if (typeof text !== "string")
@@ -85,7 +105,7 @@ export class Akuma {
         const result = await executeAskAkuma({
             path: this.root,
             id: this.id,
-            outcomeObserved: outcomePluginObserver({ world: this.root, reportDiagnostic: console.error }),
+            outcomeObserved: outcomePluginObserver({ world: this.root, reportDiagnostic: this.reportDiagnostic }),
             body: text,
             ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
             ...(schema === undefined ? {} : { schemaJson: schemaJsonText(schema) }),
@@ -131,6 +151,16 @@ export class Akuma {
             ...(options.limit === undefined ? {} : { limit: options.limit }),
         }));
     }
+    stream(options = {}) {
+        if (typeof options !== "object" || options === null || Array.isArray(options)) {
+            throw new TypeError("Akuma stream options must be an object");
+        }
+        const unknown = Object.keys(options).find((key) => key !== "signal");
+        if (unknown !== undefined)
+            throw new TypeError(`Akuma stream options has unknown field: ${unknown}`);
+        const signal = signalOption(options.signal);
+        return this.owner(true).stream(signal === undefined ? {} : { signal });
+    }
     async kill(options = {}) {
         if (typeof options !== "object" || options === null || Array.isArray(options)) {
             throw new TypeError("Akuma kill options must be an object");

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

@@ -1,5 +1,5 @@
 import { type AkuId, type AkumaPaths } from "./identity.js";
-import { selectHistory, selectSnapshot, type ActivityHistory, type ActivityRow, type ActivitySnapshot, type TurnLedger } from "./projection.js";
+import { selectHistory, type ActivityHistory, type ActivityRow, type ActivitySnapshot } from "./projection.js";
 import type { WorldRoot } from "../world.js";
 import type { AkumaAlias } from "../identity/selector.js";
 import type { AkumaListRow, AkumaStatus, UnbornAkumaListRow } from "./akuma.js";
@@ -25,23 +25,47 @@ type StatusObservationInput = Readonly<{
     ordinaryBudget?: number;
     admittedTellId?: string;
 }>;
-type StatusProjection = Readonly<{
-    ledger: TurnLedger;
-    selected: ReturnType<typeof selectSnapshot>;
-}>;
 /** Private to a live wait: retain only this member's current frontier and last selection. */
 export declare function createLiveStatusReader(paths: AkumaPaths, expected: AkuId): {
     clear: () => void;
+    execution(signal?: AbortSignal): Promise<import("./heart/facts.js").AkumaLife>;
+    tellOutcome: (id: string, signal?: AbortSignal) => Promise<{
+        tell: Readonly<{
+            kind: "tell";
+            sequence: number;
+            id: string;
+            body: string;
+            initiator?: string;
+            schemaJson?: string;
+            recordedAt: string;
+            state: "pending" | "told";
+            deliveries: readonly import("./heart/facts.js").TellDelivery[];
+            binding?: import("./heart/facts.js").TellBinding;
+        }> | null;
+        end: Readonly<{
+            kind: "turn-end";
+            sequence: number;
+            turnSequence: number;
+            outcome: import("./heart/facts.js").TurnOutcome;
+            completedAt: string;
+        }> | undefined;
+    }>;
+    complete(signal?: AbortSignal): Promise<boolean>;
     read(input: StatusObservationInput, signal?: AbortSignal): Promise<LiveStatusObservation>;
 };
-/** Internal live companion for an observation loop; it is not a public result. */
-export declare function bornLiveStatus(paths: AkumaPaths, expected: AkuId, input: StatusObservationInput, signal?: AbortSignal, readProjection?: () => Promise<StatusProjection>): Promise<LiveStatusObservation>;
+/** One-shot observations use the same reader and always release it. */
+export declare function bornLiveStatus(paths: AkumaPaths, expected: AkuId, input: StatusObservationInput, signal?: AbortSignal): Promise<LiveStatusObservation>;
 export declare function bornStatus(paths: AkumaPaths, expected: AkuId, input: StatusObservationInput): Promise<BudgetedStatusObservation>;
 export declare function readLiveStatus(worldPath: WorldRoot, id: AkuId, input: StatusObservationInput, signal?: AbortSignal): Promise<LiveStatusObservation>;
+export type ExecutionProgress = "settled" | "advancing" | "stopped";
+/** Pending input is not execution. An owned launch can bridge the admission gap. */
+export declare function executionProgress(life: AkumaStatus["life"], pending: boolean, wake?: "launching" | "settled" | "failed"): ExecutionProgress;
 export declare function defaultWaitComplete(status: AkumaStatus): boolean;
 /** Probe completion only; returned statuses still come from a full observation. */
-export declare function readWaitComplete(worldPath: WorldRoot, ids: readonly AkuId[], completion: "any" | "all", signal?: AbortSignal): Promise<boolean>;
+export declare function readWaitComplete(worldPath: WorldRoot, ids: readonly AkuId[], completion: "any" | "all", signal?: AbortSignal, probe?: (id: AkuId) => Promise<boolean>): Promise<boolean>;
 export type WaitReason = "completed" | "deadline";
+/** The one observation cadence public waiting and timeline streaming share. */
+export declare const OBSERVATION_POLL_MS = 100;
 /**
  * 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
@@ -49,6 +73,7 @@ export type WaitReason = "completed" | "deadline";
  */
 export declare function waitForObservation<T>(input: Readonly<{
     timeoutMs?: number;
+    pollMs?: number;
     signal?: AbortSignal;
     probe?(): Promise<boolean>;
     observe(): Promise<T>;

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

@@ -1,4 +1,5 @@
-import { readStatusFacts, createStatusFactReader, readLifeSnapshot, HeldAkumaLeash, isHeartAbsent, life, lifeAt, probeLeash, readHeart, readSeal, readSoul, } from "./heart/index.js";
+import { projectAkumaBirth } from "./caller.js";
+import { createStatusFactReader, readLifeSnapshot, HeldAkumaLeash, isHeartAbsent, life, lifeAt, probeLeash, readHeart, readSeal, readSoul, } from "./heart/index.js";
 import { pathsForAkuId } from "./identity.js";
 import { ordinarySnapshotBudget, projectTurns, selectHistory, selectSnapshot, } from "./projection.js";
 import { resolveProviderExecution } from "./providers/index.js";
@@ -88,59 +89,75 @@ export function createLiveStatusReader(paths, expected) {
     };
     return {
         clear,
-        async read(input, signal) {
+        async execution(signal) {
+            return (await bornObservation(paths, expected, () => reader.life(signal))).currentLife;
+        },
+        tellOutcome: reader.tellOutcome,
+        async complete(signal) {
             try {
-                return await bornLiveStatus(paths, expected, input, signal, async () => {
-                    const facts = await reader.read(input, signal);
-                    const ledger = memo?.facts === facts ? memo.ledger : projectTurns(facts);
-                    const options = snapshotSelection(input);
-                    const selected = memo?.ledger === ledger &&
-                        memo.options.aperture === options.aperture &&
-                        memo.options.admittedTellId === options.admittedTellId &&
-                        memo.options.budget.tail === options.budget.tail &&
-                        memo.options.budget.voice === options.budget.voice
-                        ? memo.selected
-                        : selectSnapshot(ledger, options);
-                    memo = { facts, ledger, options, selected };
-                    return { ledger, selected };
-                });
+                const observed = await bornObservation(paths, expected, () => reader.life(signal));
+                return complete(observed.currentLife, observed.snapshot.hasPendingTell);
             }
             catch (error) {
                 clear();
                 throw error;
             }
         },
-    };
-}
-/** Internal live companion for an observation loop; it is not a public result. */
-export async function bornLiveStatus(paths, expected, input, signal, readProjection) {
-    if (input.ordinaryBudget !== undefined && (!Number.isSafeInteger(input.ordinaryBudget) || input.ordinaryBudget < 0))
-        throw new TypeError("ordinary budget must be a nonnegative safe integer");
-    const { snapshot, soul, currentLife } = await bornObservation(paths, expected, () => readLifeSnapshot(paths, signal));
-    const resumeUnsupported = currentLife === "stranded" &&
-        snapshot.latestSession?.provider === soul.provider.name &&
-        (await resolveProviderExecution(soul.provider)).adapter.resume === undefined;
-    const { ledger, selected } = readProjection === undefined ? await readStatusProjection(paths, input, signal) : await readProjection();
-    return {
-        status: {
-            id: soul.id,
-            life: currentLife,
-            cwd: soul.cwd,
-            allowed: soul.allowed,
-            ...(resumeUnsupported ? { strandedReason: "resume-unsupported" } : {}),
-            timeline: selected.snapshot,
+        async read(input, signal) {
+            try {
+                if (input.ordinaryBudget !== undefined &&
+                    (!Number.isSafeInteger(input.ordinaryBudget) || input.ordinaryBudget < 0))
+                    throw new TypeError("ordinary budget must be a nonnegative safe integer");
+                const { snapshot, soul, currentLife } = await bornObservation(paths, expected, () => reader.life(signal));
+                const resumeUnsupported = currentLife === "stranded" &&
+                    snapshot.latestSession?.provider === soul.provider.name &&
+                    (await resolveProviderExecution(soul.provider)).adapter.resume === undefined;
+                const facts = await reader.read(input, signal);
+                const ledger = memo?.facts === facts ? memo.ledger : projectTurns(facts);
+                const options = snapshotSelection(input);
+                const selected = memo?.ledger === ledger &&
+                    memo.options.aperture === options.aperture &&
+                    memo.options.admittedTellId === options.admittedTellId &&
+                    memo.options.budget.tail === options.budget.tail &&
+                    memo.options.budget.voice === options.budget.voice
+                    ? memo.selected
+                    : selectSnapshot(ledger, options);
+                memo = { facts, ledger, options, selected };
+                return {
+                    status: {
+                        id: soul.id,
+                        birth: projectAkumaBirth(soul),
+                        life: currentLife,
+                        cwd: soul.cwd,
+                        // The execution adapter and its one current model are what this Akuma
+                        // actually runs; a birth request the Soul still only seeded is not a
+                        // claim that a native runtime ever used it.
+                        provider: soul.provider.name,
+                        ...(soul.options.model === undefined ? {} : { model: soul.options.model }),
+                        allowed: soul.allowed,
+                        ...(resumeUnsupported ? { strandedReason: "resume-unsupported" } : {}),
+                        timeline: selected.snapshot,
+                    },
+                    ordinarySelected: selected.ordinaryCount,
+                    rows: ledger.rows,
+                };
+            }
+            catch (error) {
+                clear();
+                throw error;
+            }
         },
-        ordinarySelected: selected.ordinaryCount,
-        rows: ledger.rows,
     };
 }
-async function readStatusProjection(paths, input, signal) {
-    const facts = await readStatusFacts(paths, input, signal);
-    const ledger = projectTurns(facts);
-    return {
-        ledger,
-        selected: selectSnapshot(ledger, snapshotSelection(input)),
-    };
+/** One-shot observations use the same reader and always release it. */
+export async function bornLiveStatus(paths, expected, input, signal) {
+    const reader = createLiveStatusReader(paths, expected);
+    try {
+        return await reader.read(input, signal);
+    }
+    finally {
+        reader.clear();
+    }
 }
 export async function bornStatus(paths, expected, input) {
     const { rows: _rows, ...status } = await bornLiveStatus(paths, expected, input);
@@ -149,21 +166,33 @@ export async function bornStatus(paths, expected, input) {
 export async function readLiveStatus(worldPath, id, input, signal) {
     return await bornLiveStatus(pathsForAkuId(worldPath, id), id, input, signal);
 }
+/** Pending input is not execution. An owned launch can bridge the admission gap. */
+export function executionProgress(life, pending, wake = "settled") {
+    if (wake === "launching" || life === "running")
+        return "advancing";
+    if (wake === "failed")
+        return "stopped";
+    if (life === "asleep")
+        return pending ? "advancing" : "settled";
+    return "stopped";
+}
 function complete(life, pending) {
-    return life !== "running" && !pending;
+    return executionProgress(life, pending) !== "advancing";
 }
 export function defaultWaitComplete(status) {
     return complete(status.life, status.timeline.entries.some((entry) => entry.kind === "row" && entry.row.kind === "tell" && entry.row.state === "pending"));
 }
 /** Probe completion only; returned statuses still come from a full observation. */
-export async function readWaitComplete(worldPath, ids, completion, signal) {
+export async function readWaitComplete(worldPath, ids, completion, signal, probe) {
     let completed = 0;
     for (const id of ids) {
         signal?.throwIfAborted();
         try {
             const paths = pathsForAkuId(worldPath, id);
-            const observed = await bornObservation(paths, id, () => readLifeSnapshot(paths, signal));
-            if (complete(observed.currentLife, observed.snapshot.hasPendingTell)) {
+            const ready = probe === undefined
+                ? await bornObservation(paths, id, () => readLifeSnapshot(paths, signal)).then((observed) => complete(observed.currentLife, observed.snapshot.hasPendingTell))
+                : await probe(id);
+            if (ready) {
                 if (completion === "any")
                     return true;
                 completed += 1;
@@ -176,7 +205,8 @@ export async function readWaitComplete(worldPath, ids, completion, signal) {
     }
     return ids.length > 0 && completed === ids.length;
 }
-const OBSERVATION_POLL_MS = 100;
+/** The one observation cadence public waiting and timeline streaming share. */
+export const OBSERVATION_POLL_MS = 100;
 /**
  * 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
@@ -188,22 +218,18 @@ export async function waitForObservation(input) {
         input.signal?.throwIfAborted();
         const ready = input.probe === undefined || (await input.probe());
         input.signal?.throwIfAborted();
-        if (!ready && (deadline === undefined || performance.now() < deadline)) {
-            await abortableDelay(deadline === undefined
-                ? OBSERVATION_POLL_MS
-                : Math.min(OBSERVATION_POLL_MS, Math.max(0, deadline - performance.now())), input.signal);
-            continue;
+        if (ready || (deadline !== undefined && performance.now() >= deadline)) {
+            const value = await input.observe();
+            input.signal?.throwIfAborted();
+            await input.onObserve?.(value);
+            if (input.complete(value))
+                return { reason: "completed", value };
+            if (deadline !== undefined && performance.now() >= deadline)
+                return { reason: "deadline", value };
         }
-        const value = await input.observe();
-        input.signal?.throwIfAborted();
-        await input.onObserve?.(value);
-        if (input.complete(value))
-            return { reason: "completed", value };
-        if (deadline !== undefined && performance.now() >= deadline)
-            return { reason: "deadline", value };
         await abortableDelay(deadline === undefined
-            ? OBSERVATION_POLL_MS
-            : Math.min(OBSERVATION_POLL_MS, Math.max(0, deadline - performance.now())), input.signal);
+            ? (input.pollMs ?? OBSERVATION_POLL_MS)
+            : Math.min(input.pollMs ?? OBSERVATION_POLL_MS, Math.max(0, deadline - performance.now())), input.signal);
     }
 }
 export async function readAkumaBirthCwd(worldPath, id) {

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

@@ -1,5 +1,7 @@
+import { type AkumaCaller } from "./caller.js";
 import type { WorldRoot } from "../world.js";
 import { type OutcomeObserver, type LiveStatusObservation, type WaitReason } from "./akuma-observe.js";
+import { type AkumaStreamSnapshot } from "./akuma-stream.js";
 import type { AkumaStatus } from "./akuma.js";
 import { type TellResult, type TellWakeRuntime } from "./body.js";
 import { type CallInitialTell, type CallInitialTellAdmission } from "./call-initial-tell.js";
@@ -63,7 +65,7 @@ export declare function killAkumaWithRecovery(paths: AkumaPaths, recover?: (path
  * The one lower native Akuma owner: standalone identity, plural selection and
  * the request service all consume these same single-target algorithms. It reads
  * only Heart, leash, provider and filesystem state; optional Alias, Dispatch,
- * Task and Contract associations are composed above this boundary.
+ * Debt and Contract associations are composed above this boundary.
  */
 export declare class AkumaOwner {
     readonly id: AkuId;
@@ -80,6 +82,14 @@ export declare class AkumaOwner {
         since?: number;
         limit?: number;
     }>): Promise<ActivityHistory | ExactHistory>;
+    /**
+     * Continuously observe that same retained timeline. Each emission is the whole
+     * latest bounded window through the existing history projection, and the
+     * operation observes until its caller stops pulling or aborts.
+     */
+    stream(options?: Readonly<{
+        signal?: AbortSignal;
+    }>): AsyncIterable<AkumaStreamSnapshot>;
     waitReceipt(predicate?: (status: AkumaStatus) => boolean, options?: Readonly<{
         timeoutMs?: number;
         signal?: AbortSignal;
@@ -121,12 +131,12 @@ export declare class AkumaOwner {
         timeoutMs?: number;
         signal?: AbortSignal;
         observe?: (observation: LiveStatusObservation) => void | Promise<void>;
+        wake?: () => "launching" | "settled" | "failed";
     }>): Promise<Readonly<{
         reason: WaitReason;
         outcome: TurnOutcome | null;
         completedAt: string | null;
     }>>;
-    private boundTellOutcome;
     interrupt(body: string, options?: Readonly<{
         tellId?: string;
         schemaJson?: string;
@@ -147,6 +157,8 @@ export declare class AkumaOwner {
     }>): Promise<InterruptAdmission>;
     fork(input: Readonly<{
         at: string;
+        caller?: AkumaCaller;
+        initiator?: string;
     }>): Promise<ForkReceipt>;
     kill(options?: Readonly<{
         signal?: AbortSignal;