@astrosheep/keiyaku 4.5.0 → 4.5.2

package/build/integrations/marketplace/plugins/keiyaku/.claude-plugin/plugin.json

@@ -1,7 +1,9 @@
 {
   "name": "keiyaku",
-  "version": "0.1.0+codex.20260819155641",
+  "version": "0.1.0",
   "description": "Use the Keiyaku contract, task, and Akuma CLI.",
-  "author": { "name": "Keiyaku" },
+  "author": {
+    "name": "Keiyaku"
+  },
   "skills": "./skills/"
 }

package/build/integrations/marketplace/plugins/keiyaku/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keiyaku",
-  "version": "0.1.0+codex.20260819155641",
+  "version": "0.1.0+codex.20260826051747",
   "description": "Use the Keiyaku contract, task, and Akuma CLI.",
   "author": {
     "name": "Keiyaku"

package/build/integrations/marketplace/plugins/keiyaku/package.json

@@ -1,8 +1,14 @@
 {
   "name": "keiyaku-harness",
-  "version": "0.1.0+codex.20260819155641",
+  "version": "0.1.0",
   "type": "module",
   "main": "./opencode.js",
-  "keywords": ["pi-package"],
-  "pi": { "skills": ["./skills"] }
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  }
 }

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

@@ -84,6 +84,7 @@ choose `--interrupt` when the current attempt itself is the problem.
 
 ```bash
 keiyaku history <aku/...|@alias> --last
+keiyaku history <aku/...|@alias> --id <historyId>
 keiyaku history <aku/...|@alias> [--before <N> | --since <N>] [--limit <N>]
 ```
 
@@ -91,9 +92,17 @@ keiyaku history <aku/...|@alias> [--before <N> | --since <N>] [--limit <N>]
 and says so plainly when no answer exists yet. Snapshot rows elsewhere may
 clip long text; the terminal answer from `call`/`wait` and the bytes from
 `--last` are never clipped — when you need the full result, take it from one
-of those. Cursor reads page the activity timeline; `--before` and `--since`
-are exclusive sequence cursors. `--limit` defaults to 50 and accepts at most
-5000 semantic rows.
+of those. Every completed answered or failed outcome carries one Heart-owned
+public `historyId` shaped as `turn/<positive-safe-integer>` in `status`, `wait`,
+and history output. Use `--id` with that same value to read exactly one retained
+outcome: text writes the complete answer or diagnostic bytes without clipping
+or framing. Provider-native history coordinates remain private. A malformed or
+unknown ID is a typed nonzero refusal. `--id` is mutually exclusive with
+`--last`, `--before`, `--since`, and `--limit`.
+
+Cursor reads page the activity timeline; `--before` and `--since` are exclusive
+sequence cursors. `--limit` defaults to 50 and accepts at most 5000 semantic
+rows.
 
 ## Stop
 
@@ -116,5 +125,7 @@ keiyaku fork <aku/...|@alias> --at <historyId> [--alias @name]
 `fork` starts a child from one exact retained answered-turn coordinate and
 leaves the source untouched. It is a provider capability, not a guarantee:
 when the provider cannot fork from that turn, the command refuses rather than
-fabricating a fresh start. Take the `historyId` from `history` output; it must
-name an answered turn.
+fabricating a fresh start. Pass the same public `historyId` exposed by status,
+wait, or history; Heart privately resolves the provider coordinate. The ID must
+name an answered outcome with a provider fork point. Failed outcomes are not
+forkable.

package/build/integrations/pi/keiyaku.ts

@@ -0,0 +1,159 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+
+type Section = Readonly<{ kind?: string; value?: Readonly<{ rows?: readonly Record<string, unknown>[] }> }>;
+type Report = Readonly<{
+  contracts?: Section;
+  tasks?: Section;
+  akuma?: Section;
+}>;
+
+type ExecResult = Readonly<{ stdout: string; stderr: string; code: number }>;
+
+const REFRESH_TIMEOUT_MS = 10_000;
+
+function rows(section: Section | undefined): readonly Record<string, unknown>[] {
+  return section?.kind === "present" && Array.isArray(section.value?.rows) ? section.value.rows : [];
+}
+
+function failed(section: Section | undefined): boolean {
+  return section?.kind === "failed";
+}
+
+function contractNeedsAttention(row: Record<string, unknown>): boolean {
+  const gates = row.gates;
+  if (typeof gates === "object" && gates !== null && "reports" in gates && Array.isArray(gates.reports)) {
+    for (const report of gates.reports) {
+      if (
+        typeof report === "object" &&
+        report !== null &&
+        "current" in report &&
+        typeof report.current === "object" &&
+        report.current !== null &&
+        "kind" in report.current &&
+        report.current.kind === "attested" &&
+        "verdict" in report.current &&
+        report.current.verdict === "unsatisfied"
+      )
+        return true;
+    }
+  }
+  return row.targetLag !== undefined &&
+    typeof row.targetLag === "object" &&
+    row.targetLag !== null &&
+    "kind" in row.targetLag
+    ? row.targetLag.kind === "unknown"
+    : false;
+}
+
+function taskNeedsAttention(row: Record<string, unknown>): boolean {
+  return row.disposition === "blocked";
+}
+
+function akumaNeedsAttention(row: Record<string, unknown>): boolean {
+  return row.life === "stillborn" || row.life === "hung" || row.life === "untidy";
+}
+
+function summary(report: Report): string {
+  const contractRows = rows(report.contracts);
+  const taskRows = rows(report.tasks);
+  const akumaRows = rows(report.akuma);
+  const attention =
+    Number(failed(report.contracts)) +
+    Number(failed(report.tasks)) +
+    Number(failed(report.akuma)) +
+    contractRows.filter(contractNeedsAttention).length +
+    taskRows.filter(taskNeedsAttention).length +
+    akumaRows.filter(akumaNeedsAttention).length;
+  const parts = [`Keiyaku · ${contractRows.length} contracts`, `${akumaRows.length} fleet`, `${taskRows.length} tasks`];
+  if (attention > 0) parts.push(`! ${attention}`);
+  return parts.join(" · ");
+}
+
+function parseReport(result: ExecResult): Report | undefined {
+  if (result.code !== 0 || result.stdout.trim().length === 0) return undefined;
+  try {
+    const value: unknown = JSON.parse(result.stdout);
+    return typeof value === "object" && value !== null ? (value as Report) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function run(pi: ExtensionAPI, args: readonly string[], timeout = REFRESH_TIMEOUT_MS): Promise<ExecResult> {
+  const bundledCli = resolve(dirname(fileURLToPath(import.meta.url)), "../../src/cli/index.js");
+  if (existsSync(bundledCli)) return await pi.exec(process.execPath, [bundledCli, ...args], { timeout });
+  return await pi.exec("keiyaku", [...args], { timeout });
+}
+
+function lineForWidth(value: string, width: number): string {
+  const clean = value.replaceAll(/[\u0000-\u001f\u007f]/gu, " ");
+  return clean.length <= width ? clean : `${clean.slice(0, Math.max(0, width - 1))}…`;
+}
+
+function overlay(lines: readonly string[], theme: Theme, done: () => void) {
+  return {
+    invalidate(): void {},
+    handleInput(data: string): void {
+      if (data === "\u001b" || data === "q" || data === "Q" || data === "\r") done();
+    },
+    render(width: number): string[] {
+      const inner = Math.max(20, Math.min(100, width - 4));
+      const border = theme.fg("border", "+");
+      const rule = theme.fg("border", "-".repeat(inner));
+      return [
+        `${border}${rule}${border}`,
+        `${theme.fg("border", "|")}${lineForWidth("Keiyaku", inner).padEnd(inner)}${theme.fg("border", "|")}`,
+        `${theme.fg("border", "|")}${" ".repeat(inner)}${theme.fg("border", "|")}`,
+        ...lines.map(
+          (line) => `${theme.fg("border", "|")}${lineForWidth(line, inner).padEnd(inner)}${theme.fg("border", "|")}`,
+        ),
+        `${theme.fg("border", "|")}${" ".repeat(inner)}${theme.fg("border", "|")}`,
+        `${theme.fg("border", "|")}${lineForWidth("esc/q/enter close", inner).padEnd(inner)}${theme.fg("border", "|")}`,
+        `${border}${rule}${border}`,
+      ];
+    },
+  };
+}
+
+export default function keiyakuExtension(pi: ExtensionAPI): void {
+  let refreshInFlight: Promise<void> | undefined;
+
+  const refresh = async (ctx: Pick<ExtensionContext, "hasUI" | "ui">): Promise<void> => {
+    if (!ctx.hasUI) return;
+    refreshInFlight ??= (async () => {
+      const result = await run(pi, ["status", "--json"]);
+      const report = parseReport(result);
+      if (report === undefined) {
+        const diagnostic = result.stderr.trim() || "status unavailable";
+        ctx.ui.setWidget("keiyaku", [`Keiyaku · ${lineForWidth(diagnostic, 100)}`]);
+      } else ctx.ui.setWidget("keiyaku", [summary(report)]);
+    })().finally(() => {
+      refreshInFlight = undefined;
+    });
+    await refreshInFlight;
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    await refresh(ctx);
+  });
+  pi.on("turn_end", async (_event, ctx) => {
+    await refresh(ctx);
+  });
+  pi.registerCommand("keiyaku", {
+    description: "Open the Kanshi world status",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+      const result = await run(pi, ["status"]);
+      const body =
+        result.code === 0 ? result.stdout.trimEnd().split("\n") : [result.stderr.trim() || "status unavailable"];
+      await ctx.ui.custom<void>((_tui, theme, _keybindings, done) => overlay(body, theme, done), {
+        overlay: true,
+        overlayOptions: { anchor: "center", width: 100, maxHeight: 40 },
+      });
+      await refresh(ctx);
+    },
+  });
+}

package/build/src/akuma/abort.js

@@ -2,10 +2,13 @@ export function abortable(operation, signal, disposeLate) {
     signal.throwIfAborted();
     return new Promise((resolve, reject) => {
         let aborted = false;
+        let settled = false;
         const abort = () => {
             aborted = true;
-            if (disposeLate === undefined)
+            if (!settled) {
+                settled = true;
                 reject(signal.reason);
+            }
         };
         signal.addEventListener("abort", abort, { once: true });
         if (signal.aborted)
@@ -13,19 +16,16 @@ export function abortable(operation, signal, disposeLate) {
         void operation.then(async (value) => {
             signal.removeEventListener("abort", abort);
             if (!aborted) {
+                settled = true;
                 resolve(value);
                 return;
             }
-            try {
-                await disposeLate?.(value);
-            }
-            catch (error) {
-                reject(error);
-                return;
-            }
-            reject(signal.reason);
+            void Promise.resolve(disposeLate?.(value)).catch(() => undefined);
         }, (error) => {
             signal.removeEventListener("abort", abort);
+            if (settled)
+                return;
+            settled = true;
             reject(aborted ? signal.reason : error);
         });
     });

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

@@ -1,7 +1,7 @@
 import { type TellResult } from "./body.js";
 import { type KillEvidence } from "./heart/index.js";
 import { type AkuId } from "./identity.js";
-import { type ActivityHistory } from "./projection.js";
+import { type ActivityHistory, type ExactHistory } from "./projection.js";
 import type { AkumaCallExecution, AkumaStatus, ForkReceipt, InterruptReceipt } from "./akuma.js";
 import type { WorldRoot } from "../world.js";
 declare const CALL_EXECUTION: unique symbol;
@@ -11,12 +11,14 @@ export declare class AkumaHandle {
     readonly [CALL_EXECUTION]?: AkumaCallExecution;
     constructor(id: AkuId, worldPath: WorldRoot, execution?: AkumaCallExecution);
     private get paths();
+    private exactHistory;
     status(): Promise<AkumaStatus>;
     history(input?: Readonly<{
+        id?: string;
         before?: number;
         since?: number;
         limit?: number;
-    }>): Promise<ActivityHistory>;
+    }>): Promise<ActivityHistory | ExactHistory>;
     wait(predicate?: (status: AkumaStatus) => boolean, options?: Readonly<{
         timeoutMs?: number;
     }>): Promise<AkumaStatus>;

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

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { CONTROL_RESPONSE_MS, wakeRecordedTell } from "./body.js";
 import { HeldAkumaLeash, activitySlice, readForkPoint, readHeart, readKill, readLastAnsweredTurn, readSoul, recordTell, requestPause, requestStop, } from "./heart/index.js";
-import { pathsForAkuId } from "./identity.js";
-import { projectTurns, selectHistory } from "./projection.js";
+import { parsePublicHistoryId, pathsForAkuId } from "./identity.js";
+import { projectTurns, selectHistory, selectExactHistory, } from "./projection.js";
 import { resolveProviderExecution } from "./providers/index.js";
 import { publishAkuma } from "./publication.js";
 import { spawnAkumaBody } from "./body.js";
@@ -83,10 +83,22 @@ export class AkumaHandle {
     get paths() {
         return pathsForAkuId(this.worldPath, this.id);
     }
+    async exactHistory(input) {
+        if (typeof input.id !== "string" || input.id.trim() === "")
+            throw new TypeError("Akuma history id must be a nonblank string");
+        if (input.before !== undefined || input.since !== undefined || input.limit !== undefined)
+            throw new TypeError("Akuma history id cannot be combined with before, since, or limit");
+        if (parsePublicHistoryId(input.id) === null)
+            throw new TypeError("Akuma history id must match turn/<positive safe integer>");
+        const slice = await activitySlice(this.paths);
+        return selectExactHistory(projectTurns(slice.rows, { lowestRetained: slice.lowestRetained, highest: slice.highest }).rows, input.id);
+    }
     async status() {
         return (await bornStatus(this.paths, this.id, { aperture: "monitoring" })).status;
     }
     async history(input = {}) {
+        if (input.id !== undefined)
+            return this.exactHistory(input);
         if (input.before !== undefined && input.since !== undefined) {
             throw new TypeError("Akuma history before and since are mutually exclusive");
         }

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

@@ -42,11 +42,17 @@ export declare class Akuma {
     listArchetypes(): Promise<readonly string[]>;
     call(input: AkumaCallLaunchInput): Promise<AkumaHandle>;
     beginCall(input: AkumaCallLaunchInput, context: AkumaCallContext): Promise<AkumaBornCall>;
-    finishCall(born: AkumaBornCall): Promise<AkumaHandle>;
+    finishCall(born: AkumaBornCall, completion?: Readonly<{
+        participantName?: string;
+        contractId?: string;
+    }>): Promise<AkumaHandle>;
     [CALL_WITH_CONTEXT](input: AkumaCallLaunchInput, context: AkumaCallContext): Promise<AkumaHandle>;
     list(input?: AkumaListInput): Promise<AkumaList>;
 }
 export declare function callAkumaWithContext(akuma: Akuma, input: AkumaCallLaunchInput, context: AkumaCallContext): Promise<AkumaHandle>;
 export declare function beginAkumaCall(akuma: Akuma, input: AkumaCallLaunchInput, context: AkumaCallContext): Promise<AkumaBornCall>;
-export declare function finishAkumaCall(akuma: Akuma, born: AkumaBornCall): Promise<AkumaHandle>;
+export declare function finishAkumaCall(akuma: Akuma, born: AkumaBornCall, completion?: Readonly<{
+    participantName?: string;
+    contractId?: string;
+}>): Promise<AkumaHandle>;
 export {};

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

@@ -112,13 +112,18 @@ export class Akuma {
             },
         };
     }
-    async finishCall(born) {
+    async finishCall(born, completion = {}) {
         if (born.kind === "requested") {
             return new AkumaHandle(born.id, this.path, { cwd: born.cwd, source: born.execution.source });
         }
         const published = await launchAkuma({
             allocated: born.allocated,
-            launch: async (allocated) => await spawnAkumaBody({ paths: allocated.paths, seed: born.seed, initialBody: born.initialBody }),
+            launch: async (allocated) => await spawnAkumaBody({
+                paths: allocated.paths,
+                seed: born.seed,
+                initialBody: born.initialBody,
+                ...(Object.keys(completion).length === 0 ? {} : { completion }),
+            }),
         });
         return new AkumaHandle(published.id, this.path, {
             cwd: born.execution.cwd,
@@ -174,6 +179,6 @@ export async function callAkumaWithContext(akuma, input, context) {
 export async function beginAkumaCall(akuma, input, context) {
     return await akuma.beginCall(input, context);
 }
-export async function finishAkumaCall(akuma, born) {
-    return await akuma.finishCall(born);
+export async function finishAkumaCall(akuma, born, completion = {}) {
+    return await akuma.finishCall(born, completion);
 }

package/build/src/akuma/body.d.ts

@@ -11,6 +11,10 @@ export type BodyLaunch = Readonly<{
     birthSession?: Omit<SessionFact, "sequence">;
     initialBody?: string;
     refuseIfHeld?: boolean;
+    completion?: Readonly<{
+        participantName?: string;
+        contractId?: string;
+    }>;
 }>;
 export type TellWake = Readonly<{
     kind: "told";

package/build/src/akuma/body.js

@@ -1,11 +1,11 @@
 import { appendFile } from "node:fs/promises";
-import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { abortableDelay } from "./abort.js";
 import { BodySupervisor } from "./body-supervisor.js";
 import { driveTurn, turnRecipe } from "./turn-drive.js";
 import { HeldAkumaLeash, breakBody, endTurn, finishBodyIfIdle, heartExists, isHeartAbsent, readHeart, readNonterminalRequests, watchHeart, } from "./heart/index.js";
 import { worldRootForAkumaPaths } from "./identity.js";
+import { keiyakuSquarePath } from "../world.js";
 import { resolveProviderExecution } from "./providers/index.js";
 import { clearBodyRequestTransport, settleBodyRequests, } from "./request-serve.js";
 import { spawnDetachedProcess, } from "../runtime/proc/run.js";
@@ -78,29 +78,30 @@ async function persistTurn(paths, turnSequence, result, completedAt) {
     await endTurn(paths, { turnSequence, outcome: { kind: "failed", diagnostic }, completedAt });
     return { outcome: "failed", diagnostic };
 }
-const OUTCOME_PREVIEW_LIMIT = 1_000;
-function outcomePreview(identity, outcome) {
-    const text = outcome.outcome === "answered" ? outcome.answer : outcome.diagnostic;
-    if (text.length <= OUTCOME_PREVIEW_LIMIT)
-        return text;
-    return `${text.slice(0, OUTCOME_PREVIEW_LIMIT)}\n\nkeiyaku history ${identity} --last`;
+function completionMessage(identity, completion) {
+    const participant = completion?.participantName;
+    const contract = completion?.contractId;
+    const header = [identity, participant === undefined ? undefined : `(@${participant})`, contract]
+        .filter((value) => value !== undefined)
+        .join(" ");
+    return `${header}\n✓ came back`;
 }
 function boundedDiagnostic(error) {
     const text = diagnostic(error);
     return text.length <= 500 ? text : `${text.slice(0, 500)}...`;
 }
-async function expressInitialOutcome(launch, outcome) {
+async function expressInitialOutcome(launch) {
     try {
         const { Square } = await import("@astrosheep/square");
         const identity = launch.seed?.id ?? (await readHeart(launch.paths)).soul?.id;
         if (identity === undefined)
             return;
-        const square = await Square.at({ path: join(worldRootForAkumaPaths(launch.paths), ".square", "PUBLIC.square") });
+        const square = await Square.at({ path: keiyakuSquarePath(worldRootForAkumaPaths(launch.paths)) });
         try {
             const joined = await square.implicitJoin(identity);
             if (joined.state === "done" || joined.participant === undefined)
                 return;
-            await joined.participant.express(outcomePreview(identity, outcome));
+            await joined.participant.express(completionMessage(identity, launch.completion));
         }
         finally {
             await square.close();
@@ -217,7 +218,7 @@ async function runBodyTurns(input) {
         }
         const outcome = await persistTurn(launch.paths, result.turnSequence, result, runtime.now());
         if (initial !== undefined)
-            await expressInitialOutcome(launch, outcome);
+            await expressInitialOutcome(launch);
         if (outcome.outcome === "failed") {
             await breakBody(launch.paths, { sequence: bodySequence, end: "broke-off", at: runtime.now() });
             return;
@@ -344,8 +345,14 @@ async function awaitWake(paths, tellId, after, child, changed) {
         if (winner.kind === "exited") {
             return winner.exit.code === LEASH_HELD_EXIT ? { kind: "held" } : failedChild(winner.exit);
         }
-        await child.terminate();
-        await child.exited;
+        try {
+            await child.terminate();
+        }
+        catch (error) {
+            /* Termination rejection leaves physical custody unresolved; release it deliberately. */
+            child.release();
+            return { kind: "failed", diagnostic: diagnostic(error) };
+        }
         return winner.kind === "observer-failed"
             ? { kind: "failed", diagnostic: diagnostic(winner.error) }
             : { kind: "failed", diagnostic: "Heart observer closed" };
@@ -355,11 +362,11 @@ async function wakePendingTells(paths, tellId, runtime) {
     const watching = new AbortController();
     let changed;
     try {
+        changed = await runtime.observeHeart(paths, watching.signal);
         const beforeHeart = await readHeart(paths);
         if (tellId === undefined && beforeHeart.pending.length === 0)
             return null;
         const before = beforeHeart.latestBody?.sequence ?? 0;
-        changed = await runtime.observeHeart(paths, watching.signal);
         return await awaitWake(paths, tellId, before, await runtime.spawn(paths), changed);
     }
     catch (error) {

package/build/src/akuma/heart/index.js

@@ -1,7 +1,8 @@
+import { parsePublicHistoryId } from "../identity.js";
 import { answeredTurnFact, endBodyFact, finishBodyFact, insertActivityFact, insertTurnEndFact, insertTurnStartFact, insertPauseControl, insertSessionFact, insertStopControl, killFactForBody, latestBodyFact, latestKillFact, latestSessionFact, lastAnsweredTurnFact, pauseFact, sessionFactForCoordinate, stopFact, } from "./rows.js";
 import { insertTellDeliveryFact, insertTellFact, insertTellReceiptFact, pendingTellFacts, tellFact, tellIdsForFence, } from "./tells.js";
 import { activityFactSlice, lastActivityAt as readLastActivityAt, pruneActivityFacts, } from "./timeline.js";
-import { isHeartAbsent, readSealFromLeash, readTransaction, transaction, withHeart } from "./storage.js";
+import { isHeartAbsent, readSealFromLeash, readTransaction, transaction, withHeart, withReadOnlyHeart, } from "./storage.js";
 import { soulFact } from "./soul.js";
 export { HeartAbsentError, HeldAkumaLeash, classifyHeartSchema, initializeHeart, isHeartAbsent, probeLeash, watchHeart, } from "./storage.js";
 export { admitRequest, readNonterminalRequests, readRequest, refuseRequest, reserveRequest, serveRequest, serveUpstreamRequest, voidRequest, } from "./request-authority.js";
@@ -162,7 +163,7 @@ export async function finishBodyIfIdle(paths, input) {
 }
 export async function readHeart(paths) {
     try {
-        return await withHeart(paths, (heart) => readTransaction(heart, () => ({
+        return await withReadOnlyHeart(paths, (heart) => readTransaction(heart, () => ({
             soul: soulFact(heart),
             latestBody: latestBodyFact(heart),
             latestSession: latestSessionFact(heart),
@@ -193,9 +194,12 @@ export async function readLastAnsweredTurn(paths) {
     return await withHeart(paths, lastAnsweredTurnFact);
 }
 export async function readForkPoint(paths, historyId) {
+    const turnSequence = parsePublicHistoryId(historyId);
+    if (turnSequence === null)
+        return null;
     try {
         return await withHeart(paths, (heart) => {
-            const turn = answeredTurnFact(heart, historyId);
+            const turn = answeredTurnFact(heart, turnSequence);
             const outcome = turn?.end?.outcome;
             if (outcome?.kind !== "answered" || outcome.historyId === undefined)
                 return null;

package/build/src/akuma/heart/rows.d.ts

@@ -116,4 +116,4 @@ export declare function sessionFactForCoordinate(database: DatabaseSync, coordin
 export declare function latestKillFact(database: DatabaseSync): KillFact | null;
 export declare function killFactForBody(database: DatabaseSync, bodySequence: number): KillFact | null;
 export declare function lastAnsweredTurnFact(database: DatabaseSync): TurnFact | null;
-export declare function answeredTurnFact(database: DatabaseSync, historyId: string): TurnFact | null;
+export declare function answeredTurnFact(database: DatabaseSync, turnSequence: number): TurnFact | null;

package/build/src/akuma/heart/rows.js

@@ -263,10 +263,10 @@ export function lastAnsweredTurnFact(database) {
         .get();
     return row === undefined ? null : decodeTurnRow(row);
 }
-export function answeredTurnFact(database, historyId) {
+export function answeredTurnFact(database, turnSequence) {
     const row = database
         .prepare(`SELECT sequence, body_sequence, started_at, end_sequence, outcome, history_id,
-    session_json, answer, diagnostic, completed_at FROM turns WHERE outcome = 'answered' AND history_id = ?`)
-        .get(historyId);
+    session_json, answer, diagnostic, completed_at FROM turns WHERE outcome = 'answered' AND sequence = ?`)
+        .get(turnSequence);
     return row === undefined ? null : decodeTurnRow(row);
 }

package/build/src/akuma/heart/storage.d.ts

@@ -10,6 +10,7 @@ export declare class HeartAbsentError extends Error {
 export declare function isHeartAbsent(error: unknown): error is HeartAbsentError;
 export declare function classifyHeartSchema(paths: AkumaPaths): Promise<"current" | "unsupported">;
 export declare function withHeart<T>(paths: AkumaPaths, body: (database: DatabaseSync) => T): Promise<T>;
+export declare function withReadOnlyHeart<T>(paths: AkumaPaths, body: (database: DatabaseSync) => T): Promise<T>;
 export declare function transaction<T>(database: DatabaseSync, body: () => T): T;
 export declare function readTransaction<T>(database: DatabaseSync, body: () => T): T;
 export declare function initializeHeart(paths: AkumaPaths): Promise<void>;

package/build/src/akuma/heart/storage.js

@@ -12,7 +12,7 @@ const ACTIVITY_LIMIT = 5_000;
 const SQLITE_CANTOPEN = 14;
 export async function watchHeart(paths, signal) {
     const heart = basename(paths.heart);
-    const changes = [];
+    let changed = false;
     let failure;
     let wake;
     // fs.watch opens the directory synchronously. Its throw is therefore the
@@ -20,7 +20,7 @@ export async function watchHeart(paths, signal) {
     const watcher = watchDirectory(dirname(paths.heart), { signal }, (_event, filename) => {
         const name = filename?.toString();
         if (name === undefined || name === heart || name === `${heart}-wal`) {
-            changes.push(undefined);
+            changed = true;
             wake?.();
         }
     });
@@ -36,8 +36,8 @@ export async function watchHeart(paths, signal) {
     return (async function* () {
         try {
             for (;;) {
-                if (changes.length > 0) {
-                    changes.shift();
+                if (changed) {
+                    changed = false;
                     yield;
                     continue;
                 }
@@ -82,9 +82,9 @@ function isBusy(error) {
         message.includes("database is locked") ||
         message.includes("database is busy"));
 }
-async function openExistingDatabase(path, timeout) {
+async function openExistingDatabase(path, timeout, mode = "rw") {
     const uri = pathToFileURL(path);
-    uri.searchParams.set("mode", "rw");
+    uri.searchParams.set("mode", mode);
     try {
         return timeout === undefined ? new DatabaseSync(uri.href) : new DatabaseSync(uri.href, { timeout });
     }
@@ -115,6 +115,19 @@ async function openHeart(path, verify = true) {
         throw error;
     }
 }
+async function openHeartReadOnly(path, verify = true) {
+    const database = await openExistingDatabase(path, undefined, "ro");
+    try {
+        database.exec("PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000");
+        if (verify)
+            assertHeartSchemaVersion(database);
+        return database;
+    }
+    catch (error) {
+        database.close();
+        throw error;
+    }
+}
 export async function classifyHeartSchema(paths) {
     let database;
     try {
@@ -141,6 +154,15 @@ export async function withHeart(paths, body) {
         database.close();
     }
 }
+export async function withReadOnlyHeart(paths, body) {
+    const database = await openHeartReadOnly(paths.heart);
+    try {
+        return body(database);
+    }
+    finally {
+        database.close();
+    }
+}
 export function transaction(database, body) {
     database.exec("BEGIN IMMEDIATE");
     try {

package/build/src/akuma/identity.d.ts

@@ -2,6 +2,7 @@ declare const AKU_ID: unique symbol;
 export type AkuId = string & {
     readonly [AKU_ID]: true;
 };
+export declare function parsePublicHistoryId(value: string): number | null;
 export type AkumaPaths = Readonly<{
     directory: string;
     heart: string;