@llblab/pi-actors 0.43.1 → 0.45.0

package/scripts/conformance.mjs

@@ -15,6 +15,11 @@ const conformanceSuites = [
   "tests/control.test.ts",
   "tests/runs-controls.test.ts",
   "tests/runs-trace.test.ts",
+  "tests/observability.test.ts",
+  "tests/async-run-control.test.ts",
+  "tests/run-kernel-dogfood.test.ts",
+  "tests/installed.scripts.test.ts",
+  "tests/inspector-overlay.test.ts",
   "tests/tools-inspect-kernel.test.ts",
   "tests/recipes-discovery.test.ts",
   "tests/review-swarm-dogfood.test.ts",

package/scripts/locker.mjs

@@ -11,7 +11,6 @@
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
-  appendFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -32,8 +31,12 @@ async function importRuntimeModule(name) {
   return await import(pathToFileURL(existsSync(compiled) ? compiled : source).href);
 }
 
-const { acquireFileMutationLock, writeJsonAtomic, writeTextAtomic } =
-  await importRuntimeModule("file-state");
+const { acquireFileMutationLock, writeJsonAtomic, writeTextAtomic } = await importRuntimeModule("file-state");
+const { readJsonlFileResilient } = await importRuntimeModule("state-readers");
+const LOCKER_JOURNAL_MAX_RECORDS = 512;
+const LOCKER_JOURNAL_MAX_BYTES = 1024 * 1024;
+const { claimRunControlByIdInStateDir, updateRunControlStatusInStateDir } =
+  await importRuntimeModule("runs-controls");
 const { appendRunTraceEvent } = await importRuntimeModule("runs-trace");
 
 function parseArgs(argv) {
@@ -59,7 +62,6 @@ async function runLocker(argv = process.argv.slice(2)) {
   const queuePath = join(stateDir, "queue.json");
   const locksPath = join(stateDir, "locks.json");
   const journalPath = join(stateDir, "journal.jsonl");
-  const controlsPath = join(stateDir, "controls.jsonl");
   const controlPath = join(stateDir, "control.fifo");
   let runInstanceId;
   mkdirSync(stateDir, { recursive: true });
@@ -96,10 +98,22 @@ async function runLocker(argv = process.argv.slice(2)) {
   }
 
   function journal(event, data = {}) {
-    appendFileSync(
-      journalPath,
-      `${JSON.stringify({ event, ts: new Date().toISOString(), ...data })}\n`,
-    );
+    const release = acquireFileMutationLock(journalPath);
+    try {
+      const records = [...readJsonlFileResilient(journalPath).records,
+        { event, ts: new Date().toISOString(), ...data }]
+        .slice(-LOCKER_JOURNAL_MAX_RECORDS);
+      let content = encodeJournal(records);
+      while (records.length && Buffer.byteLength(content) > LOCKER_JOURNAL_MAX_BYTES) {
+        records.shift();
+        content = encodeJournal(records);
+      }
+      writeTextAtomic(journalPath, content);
+    } finally { release(); }
+  }
+
+  function encodeJournal(records) {
+    return records.length ? `${records.map((record) => JSON.stringify(record)).join("\n")}\n` : "";
   }
 
   function emitTrace(kind, summary, data = {}, level = "info") {
@@ -147,69 +161,6 @@ async function runLocker(argv = process.argv.slice(2)) {
     }
   }
 
-  function acquireControlsLock() {
-    return acquireFileMutationLock(controlsPath);
-  }
-
-  function readControls() {
-    if (!existsSync(controlsPath)) return [];
-    return readFileSync(controlsPath, "utf8")
-      .split("\n")
-      .filter((line) => line.trim())
-      .map((line) => {
-        try {
-          return JSON.parse(line);
-        } catch {
-          return undefined;
-        }
-      })
-      .filter(Boolean);
-  }
-
-  function writeControls(controls) {
-    writeTextAtomic(
-      controlsPath,
-      controls.length
-        ? `${controls.map((control) => JSON.stringify(control)).join("\n")}\n`
-        : "",
-    );
-  }
-
-  function claimControl(id) {
-    const release = acquireControlsLock();
-    try {
-      const controls = readControls();
-      const control = controls.find((item) => item.id === id);
-      if (
-        !control ||
-        control.run_instance_id !== runInstanceId ||
-        (control.status !== "queued" && control.status !== "delivered")
-      ) {
-        return undefined;
-      }
-      control.claimed_at = new Date().toISOString();
-      control.status = "claimed";
-      writeControls(controls);
-      return { ...control };
-    } finally {
-      release();
-    }
-  }
-
-  function finalizeControl(id, status, error) {
-    const release = acquireControlsLock();
-    try {
-      const controls = readControls();
-      const control = controls.find((item) => item.id === id);
-      if (!control || control.status !== "claimed") return;
-      control.status = status;
-      control[`${status}_at`] = new Date().toISOString();
-      if (error) control.error = error;
-      writeControls(controls);
-    } finally {
-      release();
-    }
-  }
 
   function tailJournal(count) {
     if (!existsSync(journalPath)) return [];
@@ -397,7 +348,9 @@ async function runLocker(argv = process.argv.slice(2)) {
   function handleLine(line) {
     const control = normalizeControl(line);
     if (!control) return false;
-    const claimed = claimControl(control.id);
+    const claimed = claimRunControlByIdInStateDir(
+      stateDir, runInstanceId, control.id,
+    );
     if (!claimed) {
       emitTrace(
         "lock.control_rejected",
@@ -409,11 +362,15 @@ async function runLocker(argv = process.argv.slice(2)) {
     }
     try {
       const stopping = handle(claimed) === true;
-      finalizeControl(claimed.id, "handled");
+      updateRunControlStatusInStateDir(
+        stateDir, claimed.id, "handled", {}, ["claimed"],
+      );
       return stopping;
     } catch (error) {
       const text = error instanceof Error ? error.message : String(error);
-      finalizeControl(claimed.id, "failed", text);
+      updateRunControlStatusInStateDir(
+        stateDir, claimed.id, "failed", { error: text }, ["claimed"],
+      );
       journal("lock.error", { error: text });
       emitTrace("lock.error", text, { error: text }, "error");
       return false;

package/scripts/music-player.mjs

@@ -13,7 +13,6 @@
  */
 
 import { spawn, spawnSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
 import {
   accessSync,
   constants,
@@ -50,8 +49,8 @@ async function importRuntimeModule(name) {
   return await import(pathToFileURL(existsSync(compiled) ? compiled : source).href);
 }
 
-const { acquireFileMutationLock, writeTextAtomic } =
-  await importRuntimeModule("file-state");
+const { appendRunControlInStateDir, claimRunControlByIdInStateDir,
+  updateRunControlStatusInStateDir } = await importRuntimeModule("runs-controls");
 const { appendRunTraceEvent } = await importRuntimeModule("runs-trace");
 
 const AUDIO_EXTENSIONS = new Set([
@@ -408,8 +407,8 @@ function playerCommand(ctx, player, volume, track) {
   }
 }
 
-function writeText(path, value, flag = "w") {
-  writeFileSync(path, value, { encoding: "utf8", flag });
+function writeText(path, value) {
+  writeFileSync(path, value, "utf8");
 }
 
 function readText(path) {
@@ -584,7 +583,24 @@ async function startControlServer(ctx, wakeControlLoop) {
     : join(ctx.stateDir, "control.sock");
   if (process.platform !== "win32") rmSync(path, { force: true });
   const server = createServer((socket) => {
-    socket.on("data", wakeControlLoop);
+    let content = "";
+    socket.setEncoding("utf8");
+    socket.on("data", (chunk) => { content += chunk; });
+    socket.on("end", () => {
+      for (const line of content.split("\n")) {
+        if (!line.trim()) continue;
+        try {
+          const claimed = claimControl(ctx, JSON.parse(line));
+          if (!claimed) continue;
+          handleControl(ctx, claimed.command);
+          finalizeControl(ctx, claimed.id, "handled");
+        } catch (error) {
+          const id = (() => { try { return JSON.parse(line).id; } catch { return undefined; } })();
+          finalizeControl(ctx, id, "failed", error instanceof Error ? error.message : String(error));
+        }
+      }
+      wakeControlLoop();
+    });
     socket.resume();
   });
   await new Promise((resolveReady, rejectReady) => {
@@ -606,133 +622,38 @@ async function startControlServer(ctx, wakeControlLoop) {
   };
 }
 
-function acquireControlsLock(ctx) {
-  return acquireFileMutationLock(ctx.controlsFile);
-}
-
-function readControls(ctx) {
-  if (!exists(ctx.controlsFile)) return [];
-  return readFileSync(ctx.controlsFile, "utf8")
-    .split("\n")
-    .filter((line) => line.trim())
-    .map((line) => {
-      try {
-        return JSON.parse(line);
-      } catch {
-        return undefined;
-      }
-    })
-    .filter(Boolean);
-}
-
-function writeControls(ctx, controls) {
-  writeTextAtomic(
-    ctx.controlsFile,
-    controls.length
-      ? `${controls.map((control) => JSON.stringify(control)).join("\n")}\n`
-      : "",
-  );
-}
-
 function commandFromControl(control) {
   if (typeof control.action !== "string") return undefined;
   const action = control.action.trim();
   return CONTROL_COMMANDS.has(action) ? action : undefined;
 }
 
-function runtimeWakeFile(ctx) {
-  return join(ctx.stateDir, "wake.jsonl");
-}
-
-function notifyControlWake(ctx, reason = "control.queued") {
-  try {
-    writeText(
-      runtimeWakeFile(ctx),
-      `${JSON.stringify({
-        actor: `run:${basename(ctx.stateDir)}`,
-        id: randomUUID(),
-        metadata: { command: "music-player" },
-        reason,
-        state_dir: ctx.stateDir,
-        ts: new Date().toISOString(),
-      })}\n`,
-      "a",
-    );
-  } catch {
-    // Wake records are advisory; the Control journal remains authoritative.
-  }
-}
-
 function appendControl(ctx, action) {
-  const release = acquireControlsLock(ctx);
-  try {
-    const run = readJsonFile(runJsonFile(ctx), {});
-    const controls = readControls(ctx);
-    controls.push({
-      action,
-      id: randomUUID(),
-      queued_at: new Date().toISOString(),
-      run_instance_id: run.run_instance_id,
-      status: "queued",
-    });
-    writeControls(ctx, controls);
-  } finally {
-    release();
-  }
-  notifyControlWake(ctx);
+  const run = readJsonFile(runJsonFile(ctx), {});
+  appendRunControlInStateDir(ctx.stateDir, {
+    action,
+    run_instance_id: run.run_instance_id,
+  });
 }
 
-function claimControls(ctx) {
-  const release = acquireControlsLock(ctx);
-  try {
-    const controls = readControls(ctx);
-    const commands = [];
-    let changed = false;
-    const claimedAt = new Date().toISOString();
-    for (const control of controls) {
-      if (control.status !== "queued" && control.status !== "delivered") continue;
-      const command =
-        control.run_instance_id === ctx.runInstanceId
-          ? commandFromControl(control)
-          : undefined;
-      if (!command) {
-        control.failed_at = claimedAt;
-        control.status = "failed";
-        control.error = "Unsupported or stale music-player Control";
-        changed = true;
-        continue;
-      }
-      control.claimed_at = claimedAt;
-      control.status = "claimed";
-      commands.push({ command, id: control.id });
-      changed = true;
-    }
-    if (changed) writeControls(ctx, controls);
-    return commands;
-  } finally {
-    release();
+function claimControl(ctx, wire) {
+  const control = claimRunControlByIdInStateDir(
+    ctx.stateDir, ctx.runInstanceId, wire.id,
+  );
+  const command = control ? commandFromControl(control) : undefined;
+  if (!command && control) {
+    updateRunControlStatusInStateDir(ctx.stateDir, control.id, "failed", {
+      error: "Unsupported music-player Control",
+    }, ["claimed"]);
   }
+  return command && control ? { command, id: control.id } : undefined;
 }
 
 function finalizeControl(ctx, id, status, error) {
   if (!id) return;
-  const release = acquireControlsLock(ctx);
-  try {
-    const controls = readControls(ctx);
-    const timestamp = new Date().toISOString();
-    let changed = false;
-    for (const control of controls) {
-      if (control.id !== id || control.status !== "claimed") continue;
-      control.status = status;
-      if (status === "handled") control.handled_at = timestamp;
-      else control.failed_at = timestamp;
-      if (error) control.error = error;
-      changed = true;
-    }
-    if (changed) writeControls(ctx, controls);
-  } finally {
-    release();
-  }
+  updateRunControlStatusInStateDir(
+    ctx.stateDir, id, status, error ? { error } : {}, ["claimed"],
+  );
 }
 
 function controlsSignature(ctx) {
@@ -754,8 +675,7 @@ function startControlLoop(ctx) {
         const name = file ? String(file) : "";
         if (
           !name ||
-          name === basename(ctx.controlsFile) ||
-          name === basename(runtimeWakeFile(ctx))
+          name === basename(ctx.controlsFile)
         ) {
           dirty = true;
         }
@@ -774,14 +694,6 @@ function startControlLoop(ctx) {
       const signature = controlsSignature(ctx);
       if (dirty || signature !== lastSignature) {
         dirty = false;
-        for (const { command, id } of claimControls(ctx)) {
-          try {
-            handleControl(ctx, command);
-            finalizeControl(ctx, id, "handled");
-          } catch (error) {
-            finalizeControl(ctx, id, "failed", error.message);
-          }
-        }
         lastSignature = controlsSignature(ctx);
         continue;
       }

package/scripts/release-gates.mjs

@@ -165,8 +165,30 @@ try {
       text.includes('importRuntimeModule("runs-trace")') && text.includes("appendRunTraceEvent"),
       `first-party Trace writer bypasses canonical runtime module: ${path}`,
     );
+    if (path !== "scripts/async-runner.mjs") check(
+      text.includes('importRuntimeModule("runs-controls")') &&
+        !/function (?:read|write|claimControls|finalizeControls)\b/u.test(text),
+      `first-party Control writer bypasses canonical runtime module: ${path}`,
+    );
   }
-  console.log("[release] canonical Trace writer residue checked");
+  console.log("[release] canonical Trace and Control writer residue checked");
+
+  // owner | class | lock | record bound | byte bound | recovery
+  const appendOnlyOwners = new Set([
+    "lib/runs-trace.ts", // canonical Run evidence | token lock | 2048 | 4 MiB | compact valid suffix
+    "lib/runs-retention.ts", // shared kernel evidence | token lock | 256 | 1 MiB | skip malformed
+    "scripts/locker.mjs", // first-party actor state | token lock | 512 | 1 MiB | skip malformed
+    "lib/command-templates.ts", // complete execution capture | command owner | n/a | artifact policy | preserve
+    "scripts/async-runner.mjs", // captures/prompts | Run owner | n/a | artifact policy | preserve
+    "scripts/recipe-utils.mjs", // user-declared artifact | caller owner | n/a | caller policy | preserve
+    "scripts/release-gates.mjs", // build/test-only source inventory | n/a | n/a | n/a | self-match
+  ]);
+  const appendOnlyPattern = /\bappendFileSync\b|\b(?:writeFileSync|writeTextAtomic)\s*\([^)]*\{\s*flag:\s*["']a["']/su;
+  for (const path of files.filter((candidate) => /^(?:lib\/.*\.ts|scripts\/.*\.mjs)$/u.test(candidate)))
+    if (appendOnlyPattern.test(stagedText(path) ?? ""))
+      check(appendOnlyOwners.has(path), `unregistered shipped append-only writer: ${path}`);
+  for (const path of appendOnlyOwners) check(fileSet.has(path), `stale append-only owner inventory: ${path}`);
+  console.log(`[release] append-only owner inventory checked: ${appendOnlyOwners.size} source owners`);
 
   check(
     (stagedText("scripts/validate-recipe.mjs") ?? "").includes(
@@ -176,13 +198,13 @@ try {
   );
   console.log("[release] zero-warning Recipe QA gate checked");
 
-  const baselineShippedLines = 28_853;
+  const maximumShippedLines = 29_767;
   const shippedPath = /^(?:lib\/|scripts\/|recipes\/|docs\/|skills\/)/u;
   const shippedLines = files
     .filter((path) => shippedPath.test(path))
     .reduce((total, path) => total + (((stagedText(path) ?? "").match(/\n/gu) ?? []).length + 1), 0);
-  check(shippedLines < baselineShippedLines, `shipped lines ${shippedLines} are not below baseline ${baselineShippedLines}`);
-  console.log(`[release] shipped lines ${shippedLines} < released baseline ${baselineShippedLines}`);
+  check(shippedLines <= maximumShippedLines, `shipped lines ${shippedLines} exceed release maximum ${maximumShippedLines}`);
+  console.log(`[release] shipped lines ${shippedLines} <= release maximum ${maximumShippedLines}`);
 
   const sources = files.filter((path) => path === "index.ts" || (path.startsWith("lib/") && path.endsWith(".ts")));
   const sourceSet = new Set(sources);

package/skills/actors/SKILL.md

@@ -25,11 +25,11 @@ A Run target exposes exactly three inspect views: `recipe`, `trace`, and `contro
 
 ## Recipe
 
-A Recipe defines execution. It may declare args, defaults, imports, artifacts, command-template flags, and `control: ["action"]` when a long-lived service actually consumes actor-local inputs.
+A Recipe defines execution. It may declare named typed args, inline fallbacks, configuration `defaults`, composition `values`, imports, artifacts, command-template flags, and `control: ["action"]` when a long-lived service actually consumes actor-local inputs.
 
 Do not declare Control for ordinary one-shot work. Runtime lifecycle actions such as `kill` stay runtime-owned and must not appear in Recipe Control declarations. Imported Recipes act as local definitions inside one Run; they do not create nested Runs unless execution explicitly spawns them.
 
-Prefer maintained packaged Recipes over ad hoc wrappers. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
+Prefer maintained packaged Recipes over ad hoc wrappers. Use `std:<recipe>` for exact packaged lookup and `skill:<skill>/<recipe-path>` for a component bundled with a Pi-active Skill. File-backed Recipes own `{recipe_dir}` and Skill Recipes own `{skill_dir}`; callers never pass or override these origins. Skill Recipes are components, not automatic tools. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
 
 ## Trace
 
@@ -47,7 +47,7 @@ Trace records bounded structured observations in `trace.jsonl`:
 }
 ```
 
-Trace never carries sender, recipient, route, reply, or message-envelope fields. First-party writers use the canonical append authority, which validates and size-checks under a token-owned cross-process lock before one append-only JSONL write. Use `attention: "notify"` for visible notification and `attention: "followup"` only when the coordinator must receive semantic follow-up context. Prefer artifacts or complete execution captures for large evidence.
+Trace never carries sender, recipient, route, reply, or message-envelope fields. It is a bounded retained suffix: the canonical lock appends within 2,048 events and 4 MiB or atomically keeps the newest suffix plus one warning-only `runtime.trace_compacted` marker. That marker means older history was discarded; terminal/result/execution/artifact evidence stays independently authoritative. `inspect view=trace` reports completeness. Equal timestamps use same-source physical order, fixed source rank, then stable id without exposing an ordinal or claiming cross-source causality. Attention is a wake hint, not a queue: persist durable state or an artifact first, use `notify` for visible status, and reserve `followup` for needed coordinator context. Compaction may discard old hints.
 
 ## Control
 
@@ -57,9 +57,9 @@ The public Control request is exact:
 { "target": "run:<id>", "action": "pause", "input": {}, "verbose": false }
 ```
 
-Valid Controls persist in `controls.jsonl` before delivery; invalid envelopes remain outside the journal. Token-owned locks serialize atomic journal replacements. Service endpoints publish readiness in `control-endpoint.json` with the immutable startup `run_instance_id`; only FIFO and named-pipe endpoints transport Controls. Both transports share one portable envelope: action is at most 64 lowercase ASCII characters, serialized JSON input is at most 380 bytes, and the newline-terminated wire record is at most 512 bytes. Partial writes fail, and controlled FIFO readers remain gap-free across writers. Put larger data in a declared artifact/path and send only its bounded reference or instruction through Control. Delivery revalidates owner, generation, running state, and process identity under the lifecycle lock.
+Valid Controls persist in `controls.jsonl` before delivery; invalid envelopes remain outside it. One token-owned lock rejects a 65th pending Control or 1 MiB rewrite before admission, fails closed on malformed or stale-generation evidence, and atomically admits one queued record. Exact-id claims/finalization preserve a 128-terminal tail, expected-state fencing, and 4 KiB errors. Admitted nonterminal Controls never expire automatically. `inspect view=control` reports capacity, saturation, stale work, bytes, and diagnostics. Endpoints carry immutable startup `run_instance_id`; FIFO and named pipe share limits of 64 action characters, 380 serialized input bytes, and 512 newline-terminated wire bytes. Partial writes fail. Put larger data in an artifact and send only its reference. Delivery revalidates owner, generation, state, and process identity.
 
-`kill` remains a runtime lifecycle action. Use an actor-local action such as `stop` only when the Recipe declares and implements it.
+`kill` remains the runtime recovery path for a stuck saturated Run: it bypasses actor-local Control capacity and adds no synthetic Control. Use actor-local `stop` only when declared and implemented. Restart clears generation-local evidence; archive preserves the bounded terminal tree, while prune preserves only requested artifacts.
 
 ## Run State and Safety
 
@@ -72,6 +72,8 @@ Run state lives under `~/.pi/agent/tmp/pi-actors/runs/<run>/`. Important evidenc
 - `execution.json`: command/session provenance and bounded complete-capture references.
 - `result.json`, logs, and declared artifacts.
 
+Trace/Control quotas do not constrain user-declared artifacts, repositories, media sources, complete captures, or actor-owned workload state. No public noun, tool, target, or view is added by bounded retention.
+
 Never bypass owner filtering, immutable generation fencing, process-identity verification, path containment, redaction, terminal reconciliation, or shutdown kill behavior. Do not edit active Run state to force a result.
 
 ## Operating Pattern
@@ -79,8 +81,8 @@ Never bypass owner filtering, immutable generation fencing, process-identity ver
 1. Inspect the Recipe before launch when its contract or policy matters.
 2. Spawn with explicit values and retain the returned `run:<id>`.
 3. Let short Runs finish; avoid polling.
-4. Inspect Trace when evidence or attention requires it.
-5. Send only declared actor-local Controls.
+4. Inspect Trace when evidence or attention requires it; its summary states whether retained history is complete.
+5. Inspect Control capacity before diagnosing stale work or saturation, then send only declared actor-local Controls.
 6. Use runtime kill/cancel behavior for lifecycle termination.
 7. Inspect artifacts and execution evidence for final validation.
 
@@ -98,6 +100,5 @@ If work may outlive the current turn, needs steering, produces artifacts, fans o
 
 - [Recipe library](../../docs/recipe-library.md)
 - [Async Runs](../../docs/async-runs.md)
-- [Baseline and preservation gates](../../docs/0.43-baseline.md)
 
 Read repository source and tests for exact contracts when changing pi-actors itself. Update this skill whenever durable Run mechanics change.

package/skills/swarm/SKILL.md

@@ -265,9 +265,9 @@ Report white spots, contradictions, evidence, and risks.
 
 Detached execution is an adapter concern, not a portable Swarm-script requirement. When the host offers Runs, launch the composed Recipe, return its id, and rely on terminal follow-up rather than blocking or polling.
 
-`Progress contract`: expose bounded structured Trace, logs, artifacts, status, timestamps, and final result evidence. Read these through Run inspection rather than scraping process output.
+`Progress contract`: expose bounded structured Trace, logs, artifacts, status, timestamps, and final result evidence. Treat Trace as a retained suffix and attention as a wake hint; write durable task cards, checkpoints, and large evidence to artifacts before signaling attention. Read completeness and Control capacity through existing Run inspection rather than scraping output. Artifact size/lifecycle remains separate from Trace/Control quotas.
 
-`Resumable checkpoint goal`: a controlled agent-backed Run may preserve context and accept a declared Control. When the host cannot preserve context, write a handoff artifact and launch a clean-context Run while marking the context loss explicitly.
+`Resumable checkpoint goal`: a controlled agent-backed Run may preserve context and accept a declared Control. Control saturation rejects before admission and admitted work does not expire; lifecycle recovery remains host-owned. When the host cannot preserve context, write a handoff artifact and launch a clean-context Run while marking the context loss explicitly.
 
 `Cancellation boundary`: terminate only an owned active generation whose process identity the runtime can prove. Stale pid reuse must fail closed.
 

package/dist/lib/runtime-notifier.d.ts

@@ -1,48 +0,0 @@
-/**
- * Runtime wake notifications for actor state.
- * Zones: advisory wake layer, file-backed runtime state, cross-platform notification boundary
- * Owns best-effort live wake signals while durable Run state remains canonical.
- */
-export interface RuntimeWakeEvent {
-    actor: string;
-    id: string;
-    metadata?: Record<string, unknown>;
-    reason: string;
-    state_dir: string;
-    ts: string;
-}
-export interface RuntimeNotifierSubscription {
-    close(): void;
-}
-export type RuntimeReconcileReason = "initial" | "poll" | "wake";
-export interface RuntimeReconcileEvent {
-    actor: string;
-    reason: RuntimeReconcileReason;
-    state_dir: string;
-    ts: string;
-}
-export interface RuntimeNotifierSubscribeOptions {
-    onReconcile?: (event: RuntimeReconcileEvent) => void;
-}
-export interface FileRuntimeNotifierOptions {
-    pollIntervalMs?: number;
-    replay?: boolean;
-    watch?: boolean;
-}
-export interface RuntimeNotifier {
-    notify(event: {
-        actor: string;
-        metadata?: Record<string, unknown>;
-        reason: string;
-    }): RuntimeWakeEvent;
-    subscribe(actor: string, onWake: (event: RuntimeWakeEvent) => void, options?: RuntimeNotifierSubscribeOptions): RuntimeNotifierSubscription;
-}
-export declare function runtimeWakeFile(stateDir: string): string;
-export declare function notifyRuntimeWake(stateDir: string, event: {
-    actor: string;
-    metadata?: Record<string, unknown>;
-    reason: string;
-}): RuntimeWakeEvent;
-export declare function parseRuntimeWakeEventLine(line: string): RuntimeWakeEvent | undefined;
-export declare function readRuntimeWakeEvents(stateDir: string): RuntimeWakeEvent[];
-export declare function createFileRuntimeNotifier(stateDir: string, options?: FileRuntimeNotifierOptions): RuntimeNotifier;