@llblab/pi-actors 0.20.2 → 0.22.0

package/lib/observability.ts

@@ -5,7 +5,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
 import * as AsyncRuns from "./async-runs.ts";
 import * as Paths from "./paths.ts";
@@ -52,9 +52,25 @@ export interface RunSummary {
 
 export interface RunRetirementCandidate {
   activeSubagents: number;
+  childRuns: number;
   descendantSubagents: number;
   run: string;
   stateDir: string;
+  terminalChildRuns: number;
+}
+
+export interface RunRetirementExecution {
+  action: "stop" | "cancel" | "skip" | "failed";
+  error?: string;
+  run: string;
+  stateDir: string;
+}
+
+export interface RunRetirementExecutorOptions {
+  attempted?: Set<string>;
+  cancelRun: (candidate: RunRetirementCandidate) => Record<string, unknown>;
+  notify?: (message: string, level: "info" | "warning" | "error") => void;
+  sendStop: (candidate: RunRetirementCandidate) => Promise<unknown>;
 }
 
 export interface RunTransition {
@@ -93,6 +109,7 @@ const TERMINAL = new Set<RunObservedStatus>([
   "killed",
 ]);
 const PROC_DESCENDANT_SCAN_TTL_MS = 1000;
+const RUN_STATE_DISCOVERY_MAX_DEPTH = 8;
 
 const procDescendantScanCache = new Map<
   string,
@@ -120,6 +137,30 @@ function getUpdatedAt(status: Record<string, unknown>): string | undefined {
       : undefined;
 }
 
+function listRunStateDirs(
+  stateRoot: string,
+  depth = 0,
+  seen = new Set<string>(),
+): string[] {
+  if (!existsSync(stateRoot) || seen.has(stateRoot)) return [];
+  seen.add(stateRoot);
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = readdirSync(stateRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const result: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const child = join(stateRoot, entry.name);
+    if (existsSync(join(child, "run.json"))) result.push(child);
+    if (depth + 1 < RUN_STATE_DISCOVERY_MAX_DEPTH)
+      result.push(...listRunStateDirs(child, depth + 1, seen));
+  }
+  return result;
+}
+
 function observeRun(stateDir: string): RunObservation | undefined {
   try {
     const status = AsyncRuns.getRunStatus(stateDir);
@@ -178,9 +219,8 @@ export function summarizeRuns(
       total: 0,
     };
   }
-  const runs = readdirSync(stateRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => observeRun(join(stateRoot, entry.name)))
+  const runs = listRunStateDirs(stateRoot)
+    .map((stateDir) => observeRun(stateDir))
     .filter((run): run is RunObservation => Boolean(run))
     .filter((run) => ownerId === undefined || run.ownerId === ownerId)
     .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
@@ -242,7 +282,7 @@ function getRunningRunPidMap(stateRoot: string, ownerId?: string): Map<string, s
   const pids = new Map<string, string>();
   for (const run of summarizeRunsWithoutSubagents(stateRoot, ownerId).runs) {
     if (run.status !== "running") continue;
-    const status = AsyncRuns.getRunStatus(join(stateRoot, run.run));
+    const status = AsyncRuns.getRunStatus(run.stateDir ?? join(stateRoot, run.run));
     const pid = Number(status.pid || 0);
     if (pid > 0) pids.set(String(pid), run.run);
   }
@@ -264,9 +304,8 @@ function summarizeRunsWithoutSubagents(
       runs: [],
       total: 0,
     };
-  const runs = readdirSync(stateRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => observeRun(join(stateRoot, entry.name)))
+  const runs = listRunStateDirs(stateRoot)
+    .map((stateDir) => observeRun(stateDir))
     .filter((run): run is RunObservation => Boolean(run))
     .filter((run) => ownerId === undefined || run.ownerId === ownerId)
     .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
@@ -370,28 +409,102 @@ export function renderRunStatus(
   return renderSubagentStatus(summary.runningSubagents, frame);
 }
 
+function isNestedStateDir(parent: string, child: string): boolean {
+  const path = relative(parent, child);
+  return Boolean(path) && !path.startsWith("..") && !isAbsolute(path);
+}
+
 export function findRunRetirementCandidates(
   summary: RunSummary,
 ): RunRetirementCandidate[] {
   return summary.runs
-    .filter((run) => {
+    .map((run) => {
       const activeSubagents = Math.max(0, Math.floor(run.activeSubagents ?? 0));
       const descendantSubagents = Math.max(0, Math.floor(run.descendantSubagents ?? 0));
-      return (
-        run.status === "running" &&
-        run.retireWhen === "children_terminal" &&
-        run.stateDir &&
-        activeSubagents + descendantSubagents <= 0
-      );
+      const childRuns = run.stateDir
+        ? summary.runs.filter(
+            (child) =>
+              child.stateDir !== undefined &&
+              child.stateDir !== run.stateDir &&
+              isNestedStateDir(run.stateDir!, child.stateDir),
+          )
+        : [];
+      const runningChildRuns = childRuns.filter((child) => child.status === "running").length;
+      return {
+        activeSubagents,
+        childRuns: childRuns.length,
+        descendantSubagents,
+        ready:
+          run.status === "running" &&
+          run.retireWhen === "children_terminal" &&
+          run.stateDir !== undefined &&
+          !run.terminalHandled &&
+          activeSubagents + descendantSubagents + runningChildRuns <= 0,
+        run,
+        terminalChildRuns: childRuns.filter((child) => TERMINAL.has(child.status)).length,
+      };
     })
-    .map((run) => ({
-      activeSubagents: Math.max(0, Math.floor(run.activeSubagents ?? 0)),
-      descendantSubagents: Math.max(0, Math.floor(run.descendantSubagents ?? 0)),
-      run: run.run,
-      stateDir: run.stateDir!,
+    .filter((item) => item.ready)
+    .map((item) => ({
+      activeSubagents: item.activeSubagents,
+      childRuns: item.childRuns,
+      descendantSubagents: item.descendantSubagents,
+      run: item.run.run,
+      stateDir: item.run.stateDir!,
+      terminalChildRuns: item.terminalChildRuns,
     }));
 }
 
+export async function executeRunRetirements(
+  summary: RunSummary,
+  options: RunRetirementExecutorOptions,
+): Promise<RunRetirementExecution[]> {
+  const results: RunRetirementExecution[] = [];
+  for (const candidate of findRunRetirementCandidates(summary)) {
+    if (options.attempted?.has(candidate.stateDir)) {
+      results.push({ action: "skip", run: candidate.run, stateDir: candidate.stateDir });
+      continue;
+    }
+    options.attempted?.add(candidate.stateDir);
+    try {
+      await options.sendStop(candidate);
+      options.notify?.(
+        `Retiring actor ${candidate.run} after child runs reached terminal state`,
+        "info",
+      );
+      results.push({ action: "stop", run: candidate.run, stateDir: candidate.stateDir });
+      continue;
+    } catch (error) {
+      try {
+        const cancelResult = options.cancelRun(candidate);
+        const cancelled = Boolean((cancelResult as { cancelled?: unknown }).cancelled);
+        options.notify?.(
+          cancelled
+            ? `Retiring actor ${candidate.run} by cancellation after graceful stop failed`
+            : `Actor retirement skipped for ${candidate.run}: ${error instanceof Error ? error.message : String(error)}`,
+          cancelled ? "warning" : "error",
+        );
+        results.push({
+          action: cancelled ? "cancel" : "skip",
+          ...(cancelled ? {} : { error: error instanceof Error ? error.message : String(error) }),
+          run: candidate.run,
+          stateDir: candidate.stateDir,
+        });
+      } catch (cancelError) {
+        const message = cancelError instanceof Error ? cancelError.message : String(cancelError);
+        options.notify?.(`Actor retirement failed for ${candidate.run}: ${message}`, "error");
+        results.push({
+          action: "failed",
+          error: message,
+          run: candidate.run,
+          stateDir: candidate.stateDir,
+        });
+      }
+    }
+  }
+  return results;
+}
+
 export function detectRunTransitions(
   previous: Map<string, RunObservedStatus>,
   summary: RunSummary,

package/lib/recipe-discovery.ts

@@ -88,11 +88,11 @@ function listRecipeFiles(root: string): string[] {
     .filter(
       (entry) =>
         entry.isFile() &&
-        entry.name.endsWith(".json") &&
+        (entry.name.endsWith(".json") || entry.name.endsWith(".md")) &&
         entry.name !== "legacy-tool-registry-migration-report.json",
     )
     .map((entry) => join(root, entry.name))
-    .sort();
+    .sort((a, b) => a.replace(/\.md$/, ".json").localeCompare(b.replace(/\.md$/, ".json")) || (a.endsWith(".json") ? -1 : 1));
 }
 
 function getRecipeConfigDiagnostics(
@@ -100,9 +100,15 @@ function getRecipeConfigDiagnostics(
   config: TemplateRecipeConfig | undefined,
 ): string[] {
   if (!config) return [`Invalid recipe: ${file}`];
+  const commandTemplateConfig =
+    typeof config.template === "object" && config.template !== null
+      ? config.template
+      : config;
   return CommandTemplates.getCommandTemplateWarnings(
-    typeof config.template === "string" ? config.template : { template: config.template },
-  ).map((warning) => `Recipe ${file}: ${warning}`);
+    commandTemplateConfig as CommandTemplates.CommandTemplateConfig,
+  ).map(
+    (warning) => `Recipe ${file}: ${warning}`,
+  );
 }
 
 function readDiscoveredRecipe(
@@ -218,13 +224,22 @@ export function discoverRecipeSources(
   const diagnostics: string[] = getRecipeRootDiagnostics(sources);
   for (const [id, bucket] of byId) {
     bucket.sort(
-      (a, b) => a.priority - b.priority || a.path.localeCompare(b.path),
+      (a, b) =>
+        a.priority - b.priority ||
+        a.path.replace(/\.md$/, ".json").localeCompare(b.path.replace(/\.md$/, ".json")) ||
+        (a.path.endsWith(".json") ? -1 : 1),
     );
     const winner = bucket[0];
     winner.active = true;
     winner.shadows = bucket.slice(1).map((entry) => entry.path);
     active.set(id, winner);
-    for (const shadow of bucket.slice(1)) shadow.shadowed = true;
+    for (const shadow of bucket.slice(1)) {
+      shadow.shadowed = true;
+      if (winner.path.endsWith(".json") && shadow.path.endsWith(".md"))
+        shadow.diagnostics.push(
+          `Markdown recipe ${shadow.path} is shadowed by JSON recipe ${winner.path}`,
+        );
+    }
     if (winner.invalid)
       diagnostics.push(
         `Recipe ${id} is invalid and blocks lower-priority recipes`,

package/lib/recipe-references.ts

@@ -6,7 +6,7 @@
 
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, resolve } from "node:path";
+import { basename, dirname, extname, resolve } from "node:path";
 
 import type {
   CommandTemplateConfig,
@@ -101,7 +101,9 @@ export function resolveRecipePath(
   if (expanded.includes("/")) return resolve(expanded);
   return resolve(
     recipeRoot,
-    expanded.endsWith(".json") ? expanded : `${expanded}.json`,
+    expanded.endsWith(".json") || expanded.endsWith(".md")
+      ? expanded
+      : `${expanded}.json`,
   );
 }
 
@@ -110,20 +112,26 @@ function isBareRecipeName(value: string): boolean {
   return Boolean(trimmed) && !trimmed.includes("/") && !trimmed.startsWith("~") && !trimmed.includes("{");
 }
 
-function recipeNameFile(value: string): string {
+function recipeNameFiles(value: string): string[] {
   const trimmed = value.trim();
-  return trimmed.endsWith(".json") ? trimmed : `${trimmed}.json`;
+  if (trimmed.endsWith(".json") || trimmed.endsWith(".md")) return [trimmed];
+  return [`${trimmed}.json`, `${trimmed}.md`];
 }
 
 function resolveRecipeImportPath(value: string, currentRecipeRoot: string): string {
   if (!isBareRecipeName(value)) return resolveRecipePath(value, currentRecipeRoot);
-  const file = recipeNameFile(value);
   const roots = [
     Paths.getRecipeRoot(),
     currentRecipeRoot,
     Paths.getPackagedRecipeRoot(),
   ];
-  const candidates = [...new Set(roots.map((root) => resolve(root, file)))];
+  const candidates = [
+    ...new Set(
+      roots.flatMap((root) =>
+        recipeNameFiles(value).map((file) => resolve(root, file)),
+      ),
+    ),
+  ];
   return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
 }
 
@@ -134,14 +142,14 @@ export function getRecipePath(
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();
   if (!trimmed || hasWhitespace(trimmed)) return undefined;
-  if (trimmed.endsWith(".json")) return resolveRecipePath(trimmed, recipeRoot);
-  const path = resolveRecipePath(trimmed, recipeRoot);
+  if (trimmed.endsWith(".json") || trimmed.endsWith(".md"))
+    return resolveRecipePath(trimmed, recipeRoot);
+  const jsonPath = resolveRecipePath(trimmed, recipeRoot);
+  const mdPath = resolveRecipePath(`${trimmed}.md`, recipeRoot);
+  const path = existsSync(jsonPath) ? jsonPath : mdPath;
   if (!existsSync(path)) return undefined;
   try {
-    const raw = JSON.parse(readFileSync(path, "utf8")) as Record<
-      string,
-      unknown
-    >;
+    const raw = readRawRecipeConfig(path);
     return raw && typeof raw === "object" && Object.hasOwn(raw, "template")
       ? path
       : undefined;
@@ -232,6 +240,123 @@ function getRecipeCommandTemplate(
   return normalizeRecipeTemplate({ ...envelope, template });
 }
 
+function parseMarkdownScalar(value: string): unknown {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  if (
+    (trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+    (trimmed.startsWith("[") && trimmed.endsWith("]"))
+  ) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      return trimmed;
+    }
+  }
+  const quoted = trimmed.match(/^(?:"([^"]*)"|'([^']*)')$/);
+  if (quoted) return quoted[1] ?? quoted[2] ?? "";
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "null") return null;
+  if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed);
+  return trimmed;
+}
+
+function parseMarkdownFrontmatterObject(
+  lines: string[],
+): Record<string, unknown> | unknown[] {
+  if (lines.every((line) => /^\s*-\s+/.test(line))) {
+    return lines.map((line) => parseMarkdownScalar(line.replace(/^\s*-\s+/, "")));
+  }
+  const result: Record<string, unknown> = {};
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(/^\s{2}([A-Za-z_][A-Za-z0-9_.-]*):\s*(.*)$/);
+    if (!match) continue;
+    if (match[2]) {
+      result[match[1]] = parseMarkdownScalar(match[2]);
+      continue;
+    }
+    const nested: string[] = [];
+    while (index + 1 < lines.length && /^\s{4}/.test(lines[index + 1])) {
+      index += 1;
+      nested.push(lines[index].slice(2));
+    }
+    result[match[1]] = parseMarkdownFrontmatterObject(nested);
+  }
+  return result;
+}
+
+function parseMarkdownFrontmatter(value: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const lines = value.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const match = line.match(/^([A-Za-z_][A-Za-z0-9_.-]*):\s*(.*)$/);
+    if (!match) continue;
+    if (match[2]) {
+      result[match[1]] = parseMarkdownScalar(match[2]);
+      continue;
+    }
+    const nested: string[] = [];
+    while (index + 1 < lines.length && /^\s+/.test(lines[index + 1])) {
+      index += 1;
+      nested.push(lines[index]);
+    }
+    result[match[1]] = parseMarkdownFrontmatterObject(nested);
+  }
+  return result;
+}
+
+function findMarkdownRecipeFence(
+  body: string,
+): { info: string; body: string } | undefined {
+  const pattern = /```([^\n`]*)\n([\s\S]*?)```/g;
+  for (const match of body.matchAll(pattern)) {
+    const info = match[1].trim().toLowerCase();
+    if (
+      info.includes("recipe") ||
+      info.includes("template") ||
+      info.includes("command") ||
+      info.includes("json")
+    ) {
+      return { info, body: match[2].trim() };
+    }
+  }
+  return undefined;
+}
+
+function parseMarkdownRecipeConfig(
+  content: string,
+): Record<string, unknown> | undefined {
+  const lines = content.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return undefined;
+  const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  if (end === -1) return undefined;
+  const frontmatter = parseMarkdownFrontmatter(lines.slice(1, end).join("\n"));
+  const fence = findMarkdownRecipeFence(lines.slice(end + 1).join("\n"));
+  if (!fence) return Object.hasOwn(frontmatter, "template") ? frontmatter : undefined;
+  const text = fence.body.trim();
+  if (!text) return undefined;
+  if (
+    fence.info.includes("json") ||
+    fence.info.includes("recipe") ||
+    text.startsWith("{") ||
+    text.startsWith("[") ||
+    text.startsWith('"')
+  ) {
+    try {
+      const parsed = JSON.parse(text) as unknown;
+      if (isRecord(parsed) && Object.hasOwn(parsed, "template"))
+        return { ...frontmatter, ...parsed };
+      return { ...frontmatter, template: parsed };
+    } catch {
+      if (fence.info.includes("json") || fence.info.includes("recipe")) return undefined;
+    }
+  }
+  return { ...frontmatter, template: text };
+}
+
 export function readRawRecipeConfig(
   path: string,
 ): Record<string, unknown> | undefined {
@@ -243,10 +368,9 @@ export function readRawRecipeConfig(
     );
   }
   try {
-    const raw = JSON.parse(readFileSync(path, "utf8")) as Record<
-      string,
-      unknown
-    >;
+    const content = readFileSync(path, "utf8");
+    if (path.endsWith(".md")) return parseMarkdownRecipeConfig(content);
+    const raw = JSON.parse(content) as Record<string, unknown>;
     return raw && typeof raw === "object" ? raw : undefined;
   } catch {
     return undefined;
@@ -254,7 +378,7 @@ export function readRawRecipeConfig(
 }
 
 export function getRecipeIdFromPath(file: string): string {
-  return basename(file, ".json");
+  return basename(file, extname(file));
 }
 
 function readRecipeConfig(value: unknown): TemplateRecipeConfig | undefined {

package/lib/runtime-notifier.ts

@@ -0,0 +1,207 @@
+/**
+ * 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 mailbox/state files remain canonical.
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  watch,
+  type FSWatcher,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+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;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+
+export function runtimeWakeFile(stateDir: string): string {
+  return join(stateDir, "wake.jsonl");
+}
+
+function normalizeWakeEvent(
+  stateDir: string,
+  event: { actor: string; metadata?: Record<string, unknown>; reason: string },
+): RuntimeWakeEvent {
+  const actor = event.actor.trim();
+  const reason = event.reason.trim();
+  if (!actor) throw new Error("Runtime wake event requires actor.");
+  if (!reason) throw new Error("Runtime wake event requires reason.");
+  return {
+    actor,
+    id: randomUUID(),
+    ...(event.metadata ? { metadata: event.metadata } : {}),
+    reason,
+    state_dir: stateDir,
+    ts: new Date().toISOString(),
+  };
+}
+
+export function notifyRuntimeWake(
+  stateDir: string,
+  event: { actor: string; metadata?: Record<string, unknown>; reason: string },
+): RuntimeWakeEvent {
+  const normalized = normalizeWakeEvent(stateDir, event);
+  const file = runtimeWakeFile(stateDir);
+  mkdirSync(dirname(file), { recursive: true });
+  appendFileSync(file, `${JSON.stringify(normalized)}\n`, "utf8");
+  return normalized;
+}
+
+export function parseRuntimeWakeEventLine(
+  line: string,
+): RuntimeWakeEvent | undefined {
+  try {
+    const record = JSON.parse(line) as Record<string, unknown>;
+    if (
+      typeof record.actor !== "string" ||
+      typeof record.id !== "string" ||
+      typeof record.reason !== "string" ||
+      typeof record.state_dir !== "string" ||
+      typeof record.ts !== "string"
+    ) {
+      return undefined;
+    }
+    return {
+      actor: record.actor,
+      id: record.id,
+      ...(record.metadata &&
+      typeof record.metadata === "object" &&
+      !Array.isArray(record.metadata)
+        ? { metadata: record.metadata as Record<string, unknown> }
+        : {}),
+      reason: record.reason,
+      state_dir: record.state_dir,
+      ts: record.ts,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function readRuntimeWakeEvents(stateDir: string): RuntimeWakeEvent[] {
+  const file = runtimeWakeFile(stateDir);
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8")
+    .split("\n")
+    .filter((line) => line.trim())
+    .map(parseRuntimeWakeEventLine)
+    .filter((event): event is RuntimeWakeEvent => Boolean(event));
+}
+
+export function createFileRuntimeNotifier(
+  stateDir: string,
+  options: FileRuntimeNotifierOptions = {},
+): RuntimeNotifier {
+  const file = runtimeWakeFile(stateDir);
+  const pollIntervalMs = Math.max(
+    25,
+    Number(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS),
+  );
+
+  return {
+    notify: (event) => notifyRuntimeWake(stateDir, event),
+    subscribe: (actor, onWake, subscribeOptions = {}) => {
+      mkdirSync(dirname(file), { recursive: true });
+      let position =
+        options.replay || !existsSync(file) ? 0 : statSync(file).size;
+      let closed = false;
+      const reconcile = (reason: RuntimeReconcileReason): void => {
+        if (closed) return;
+        subscribeOptions.onReconcile?.({
+          actor,
+          reason,
+          state_dir: stateDir,
+          ts: new Date().toISOString(),
+        });
+      };
+      const drain = (): void => {
+        if (closed || !existsSync(file)) return;
+        const buffer = readFileSync(file);
+        if (position > buffer.length) position = 0;
+        const chunk = buffer.subarray(position).toString("utf8");
+        position = buffer.length;
+        for (const line of chunk.split("\n")) {
+          if (!line.trim()) continue;
+          const event = parseRuntimeWakeEventLine(line);
+          if (event && event.actor === actor) {
+            onWake(event);
+            reconcile("wake");
+          }
+        }
+      };
+
+      let watcher: FSWatcher | undefined;
+      if (options.watch !== false) {
+        try {
+          watcher = watch(
+            dirname(file),
+            { persistent: false },
+            (_eventType, changedFile) => {
+              if (!changedFile || String(changedFile) === basename(file)) drain();
+            },
+          );
+        } catch {
+          // fs.watch availability varies by platform/filesystem; polling below is the fallback.
+        }
+      }
+      reconcile("initial");
+      const timer = setInterval(() => {
+        drain();
+        reconcile("poll");
+      }, pollIntervalMs);
+      timer.unref?.();
+      return {
+        close: () => {
+          closed = true;
+          clearInterval(timer);
+          watcher?.close();
+        },
+      };
+    },
+  };
+}