@llblab/pi-actors 0.43.0 → 0.44.0

package/docs/0.43-baseline.md

@@ -1,44 +0,0 @@
-# 0.43 Migration Baseline
-
-Release `0.43.0` uses commit `14e46931899347f08b3f1db94bc03a4f260e75a6` (`0.42.3`) as the frozen preservation and compression baseline.
-
-Commit `261297a2250711ca7f412a489cce4477ef899e89` has the same Git tree, so the two commits contain no product-code delta. The release gate may use the former as the canonical baseline while `dev` starts from the latter topology.
-
-## Shipped-line ceiling
-
-The baseline contains 35,077 lines under the shipped surfaces measured by `scripts/release-gates.mjs`:
-
-- `lib/`
-- `scripts/`
-- `recipes/`
-- `docs/`
-- `skills/`
-
-Release validation fails when the retained shipped tree exceeds that ceiling. The ceiling guards the breaking communication-plane deletion against replacement bloat; it does not grant deleted communication behavior preservation status.
-
-## Retained invariants
-
-The preservation suite keeps evidence for the safety properties that survive the migration:
-
-- owner-filtered Run discovery;
-- immutable `run_instance_id` fencing;
-- process identity checks and canonical lifecycle locking;
-- shutdown kill and parent teardown;
-- terminal reconciliation and bounded captures;
-- owned Pi session provenance;
-- path containment and structured redaction;
-- automatic-review retry, reset, transaction, and lineage safety;
-- generation-bound Control and canonical Trace evidence.
-
-Rooms, peer routing, messages, mailboxes, communication topology, and their tests do not belong to the retained baseline.
-
-## Validation
-
-Run:
-
-```bash
-npm run test:preservation
-npm run release:validate
-```
-
-The release gate also rejects removed-surface residue, Domain DAG violations, ABCd context drift, stale package contents, and shipped-line growth above the frozen ceiling.

package/docs/actors-deep-reference.md

@@ -1,108 +0,0 @@
-# Actors Deep Reference
-
-## Kernel
-
-```text
-Recipe --spawn--> Run
-Run = Recipe + Trace + Control
-```
-
-- Recipe owns executable definition and declared actor-local actions.
-- Run owns one generation of execution and evidence.
-- Trace owns observations.
-- Control owns actor-local inputs.
-
-`register_tool` persists capabilities but does not participate in running Control.
-
-## Choosing Execution
-
-Use a foreground tool for short work with one natural response. Use a Run when execution may outlive the turn, needs later inspection or steering, produces artifacts, runs as a service, or coordinates repeated/parallel command-template cells.
-
-Do not background shell processes outside the Run lifecycle.
-
-## Recipe Resolution
-
-Active user Recipes shadow packaged Recipes by name. Invalid active shadowing fails with both active and blocked fallback paths instead of silently executing another definition. Imports resolve under Recipe-root priority, enforce a 1 MiB file limit and depth limit 32, reject cycles, and act as local definitions inside one Run.
-
-Current model/thinking placeholders resolve from Pi context before launch and persist provenance in `run.json`.
-
-## Command Templates
-
-String leaves execute without shell parsing. Arrays sequence commands. Objects add `parallel`, `concurrency`, `min_successful`, `when`, `timeout`, `delay`, `retry`, `failure`, `recover`, `repeat`, `accept_output`, and `output` behavior.
-
-Placeholders support typed args, defaults, fallback, and conditional expansion. Prefer explicit scripts when shell semantics or a maintained service loop matters.
-
-## Control Discipline
-
-Public shape:
-
-```json
-{"target":"run:<id>","action":"action","input":{},"verbose":false}
-```
-
-Recipe actions use lowercase stable names. Do not declare runtime-reserved lifecycle actions. Inputs must remain bounded JSON. A controlled service publishes readiness only after its consumer can read the endpoint and includes its immutable generation id.
-
-Controls persist before transport and keep durable outcome evidence. Never infer owner identity from caller-provided input.
-
-## Trace Discipline
-
-Trace events use stable `kind` names and concise summaries. Put structured bounded evidence in `data`; put large evidence in artifacts. Use attention sparingly:
-
-- omitted/`log`: inspectable only;
-- `notify`: visible status;
-- `followup`: semantic coordinator follow-up.
-
-Trace has no address or response semantics.
-
-## Lifecycle Discipline
-
-Retain these invariants:
-
-- owner filtering;
-- immutable generation fencing;
-- process identity verification;
-- canonical lifecycle locks;
-- shutdown and parent-teardown kill;
-- terminal notification reconciliation;
-- bounded logs and complete captures;
-- owned Pi session provenance;
-- path containment and redaction;
-- review retry/reset safety.
-
-A lifecycle operation that cannot prove identity or ownership fails closed.
-
-## Operating Patterns
-
-### One-shot pipeline
-
-Spawn the Recipe, wait for terminal follow-up when needed, inspect Trace/result/artifacts, and validate outputs. Do not send Controls the process does not implement.
-
-### Controlled service
-
-Spawn, inspect `view=control` for endpoint readiness, send only declared actions, inspect Trace for outcomes, then use the declared actor-local stop action or runtime lifecycle termination as appropriate.
-
-### Parallel review
-
-Use maintained review Recipes with explicit model/thinking and bounded concurrency. Preflight provider/model policy before fanout. Keep reviewer artifacts immutable and run merge/judge stages only after required evidence succeeds.
-
-### Resource locking
-
-Use `resource-locker` only when methodology needs lease-backed resource exclusion. Include owner/resource identity in Control input and treat lock Trace as coordination evidence, not kernel authority.
-
-## Diagnostics
-
-- `inspect target=runtime` for failed Runs, stale Controls, and attention Trace.
-- `inspect target=recipes` for active/shadowed/invalid Recipe state.
-- `inspect target=tool:<name>` for registered capability schema.
-- `inspect target=run:<id> view=recipe|trace|control` for generation evidence.
-- `/actor-inspector` for owner-filtered actor-instance navigation.
-
-Avoid repeated polling. Deferred terminal results arrive as Pi follow-ups.
-
-## Related
-
-- [Runs](./async-runs.md)
-- [Recipe library](./recipe-library.md)
-- [Command templates](./command-templates.md)
-- [Template Recipes](./template-recipes.md)
-- [Actor Inspector](./actor-inspector.md)

package/docs/component-recipes.md

@@ -1,45 +0,0 @@
-# Component Recipes
-
-Component Recipes are weakly coupled command-template cells used inside higher-level Recipes. They do not create a social protocol or become independently addressable peers.
-
-## Contract
-
-A useful component has:
-
-- explicit typed inputs and caller-owned policy knobs;
-- one narrow responsibility;
-- deterministic output shape or declared artifact;
-- bounded failure behavior;
-- no hidden model/provider assumption;
-- no actor-local Control unless it owns a real service loop.
-
-## Families
-
-- normalization and prompt shaping;
-- planning and task-card generation;
-- evidence maps, contradiction maps, and criticism;
-- review, verification, merge, judge, and quorum stages;
-- artifact generation, manifesting, and deterministic writes;
-- validation and package/skill summaries.
-
-## Composition
-
-Import components by alias and call named nodes in a template array/object. Parent command-template flags own sequence, parallelism, concurrency, retries, failure scope, recovery, repetition, and output acceptance.
-
-Variable branch output should converge into stable JSON, Markdown, artifacts, or command results before downstream stages. Large evidence belongs in artifacts or complete captures; concise milestones belong in Trace.
-
-## Boundaries
-
-- Imports are definitions inside one Run.
-- One-shot components omit Control.
-- Components never infer caller identity or lifecycle authority.
-- A parent may declare artifacts that imported cells write.
-- A child failure follows explicit parent failure/recovery policy.
-
-Use the packaged Recipe library before creating a new component. Add one only when at least two stable compositions need the same narrow behavior.
-
-## Related
-
-- [Recipe library](./recipe-library.md)
-- [Template Recipes](./template-recipes.md)
-- [Command templates](./command-templates.md)

package/docs/task-first-recipes.md

@@ -1,261 +0,0 @@
-# Task-First Recipe Design
-
-Task-first recipe design starts from a high-level operator or coordinator task, then derives the component cells, utility recipes, helper scripts, and runtime semantics needed to make that task reusable.
-
-This complements atom-first growth. Atom-first asks: "What small capability can we expose?" Task-first asks: "What complete work pattern should an agent/operator be able to invoke, and which atoms must exist to support it?"
-
-## Method
-
-For each high-level recipe candidate:
-
-1. Name the task in operator language.
-2. Define the trigger and expected output artifact.
-3. Sketch the recipe pipeline at the highest useful abstraction.
-4. Identify missing component cells.
-5. Decide which cells are subagent components, local utilities, or helper-backed transforms.
-6. Keep domain policy knobs public: models, tools, paths, evidence/risk policy, output shape, actual Control actions, and validation gates.
-7. Add only the next smallest recipe/helper slice that validates the design.
-
-## High-Level Recipe Cells
-
-### Release Readiness Cell
-
-Purpose: decide whether a repo/package is ready for release.
-
-Pipeline:
-
-```text
-scope snapshot → changelog/package check → release lens reviews → risk verifier → readiness report → release checklist artifact
-```
-
-Likely needed cells:
-
-- Package metadata reader
-- Changelog section extractor
-- Package contents summarizer
-- Validation command wrapper
-- Release-risk reviewer
-- Readiness merger/judge
-- Release checklist artifact writer
-
-Existing seeds:
-
-- `utility-changelog-section`
-- `utility-package-summary`
-- `utility-validation-wrapper`
-- `pipeline-review-readiness`
-- `subagent-judge`
-- `subagent-artifact`
-
-Implemented seed:
-
-- `pipeline-release-readiness`: changelog section → package summary → packaged skill summary → validation wrapper → release review coordinator → artifact report.
-
-### Repository Health Cell
-
-Purpose: summarize repo state for the next coordinator turn or release prep.
-
-Pipeline:
-
-```text
-git status/log → package/docs/backlog snapshot → validation summary → health report → next action recommendation
-```
-
-Likely needed cells:
-
-- Git status/log utility
-- Package version reader
-- Backlog open/blocked extractor
-- Docs index checker
-- Validation summary normalizer
-- Next-action recommender
-
-Existing seeds:
-
-- `utility-markdown-index`
-- `utility-validation-wrapper`
-- `subagent-normalize`
-- `subagent-plan`
-
-Implemented seed:
-
-- `pipeline-repo-health`: git status/log → docs index → validation wrapper → normalized artifact report.
-
-### Async Run Operations Cell
-
-Purpose: inspect, summarize, and decide actions for local async runs.
-
-Pipeline:
-
-```text
-Run summary → Trace tail → stale/active classification → recommended Inspect or Control action
-```
-
-Likely needed cells:
-
-- Run summary helper
-- bounded Trace tail reader
-- Stale-run classifier
-- Inspect/Control action recommender
-- Run report artifact
-
-Existing seeds:
-
-- `utility-run-summary`
-- `utility-jsonl-tail`
-- `pipeline-artifact-report`
-
-Implemented seed:
-
-- `pipeline-async-run-ops`: structured run operations snapshot → normalized operations report → artifact report. The snapshot combines Run summary, Trace tail, and recommended Inspect/Control actions before the LLM normalization step.
-
-### Research Brief Cell
-
-Purpose: turn a question and source set into a bounded evidence-backed brief.
-
-Pipeline:
-
-```text
-question framing → evidence map → contradiction map → claim verification → synthesis → evidence gaps → next evidence slice
-```
-
-Likely needed cells:
-
-- Question framer
-- Source inventory utility
-- Evidence mapper
-- Contradiction mapper
-- Verifier
-- Synthesis merger
-- Limitations normalizer
-
-Existing seeds:
-
-- `pipeline-research-synthesis`
-- `subagent-evidence-map`
-- `subagent-contradiction-map`
-- `subagent-verify`
-
-### Consensus-First Build Cell
-
-Purpose: turn several expert proposals into one coherent artifact without parallel writers fragmenting the result.
-
-Pipeline:
-
-```text
-mission → lens proposers in room → consensus transcript → named implementer writes artifact → QA reviewer checks artifact + transcript → finalizer applies fixes → artifact assertions
-```
-
-Use this for creative demos, single-file artifacts, specs, docs, prompt packs, and product/UX deliverables where broad input matters but one owner should shape the final file. Proposers remain read-only. The implementer becomes the first stage with write tools. QA inspects without mutation, and the finalizer writes only after reading immutable QA evidence.
-
-Required gates:
-
-- Artifact path, report path, and minimum acceptance checks are explicit inputs.
-- The workflow fails if the requested artifact is missing, too small, or not self-contained enough for the task.
-- The Run completes only after QA/finalizer acceptance, not merely after proposal generation.
-
-Existing seeds:
-
-- `subagent-review` / `subagent-verify` for QA stages.
-- `pipeline-quorum-review` for independent proposals and synthesis.
-- `pipeline-artifact-write` or a small helper script for deterministic artifact assertion.
-
-Next recipe direction:
-
-- Add a generic packaged consensus-build pipeline once the interface stabilizes around proposer roles, implementer prompt, QA prompt, artifact assertions, and public model/tool knobs.
-
-### Implementation Tasking Cell
-
-Purpose: prepare bounded work for one or more implementation agents.
-
-Pipeline:
-
-```text
-goal → mutation zones → task cards → validation gates → conflict risks → integrator handoff
-```
-
-Likely needed cells:
-
-- Mutation-zone planner
-- Task-card generator
-- Ownership/conflict checker
-- Validation-gate normalizer
-- Integrator handoff artifact
-
-Existing seeds:
-
-- `pipeline-development-tasking`
-- `subagent-task-card`
-- `subagent-conflict-report`
-
-### Documentation Maintenance Cell
-
-Purpose: keep docs/index/readme surfaces coherent after changes.
-
-Pipeline:
-
-```text
-doc file inventory → index diff → stale link/routing review → rewrite suggestion → docs maintenance artifact
-```
-
-Likely needed cells:
-
-- Markdown index utility
-- Link checker wrapper
-- Docs consistency reviewer
-- Docs update planner
-- Docs artifact writer
-
-Existing seeds:
-
-- `utility-markdown-index`
-- `subagent-review`
-- `subagent-plan`
-- `subagent-artifact`
-
-Implemented seed:
-
-- `pipeline-docs-maintenance`: docs index → documentation review → maintenance plan → artifact report.
-
-### Media/Playlist Operations Cell
-
-Purpose: convert local media directories into controllable playback workflows.
-
-Pipeline:
-
-```text
-media scan → playlist build → playback start → message summary → controls
-```
-
-Likely needed cells:
-
-- Playlist builder
-- Music player
-- Run/message summary
-- Control recommender
-
-Existing seeds:
-
-- `utility-playlist-build`
-- `music-player`
-- `utility-run-summary`
-- `utility-jsonl-tail`
-
-Implemented seed:
-
-- `pipeline-media-library`: playlist build → media-library artifact report.
-
-## Selection Rule
-
-Prefer adding a high-level recipe when at least three cells already exist and the missing cells are small. Prefer adding an atom when multiple high-level recipes need the same missing cell.
-
-## Near-Term Candidates
-
-Good next candidates for the standard library after the first task-first wave:
-
-1. Package/release metadata enrichment: implemented in `pipeline-release-readiness` by adding `utility-package-summary` and `utility-skill-summary` between changelog extraction and validation, making release-readiness reports more evidence-rich without adding publish automation.
-2. Evidence-only release summary: implemented as `pipeline-release-summary`, which composes changelog/package/skill/validation evidence into a release summary, risk checklist, and PR body draft artifact while leaving commit, PR, merge, tag, and publish actions to explicit release gates.
-3. Artifact packaging and manifesting: implemented as `pipeline-artifact-bundle`, which composes optional validation, `pipeline-artifact-write`, `utility-artifact-manifest`, deterministic manifest writing, and final artifact evidence when the caller explicitly requests filesystem writes.
-4. Async run cleanup planning: extend async-run operations with stale-run classification and recommended `message`, `cancel`, or `kill` controls, keeping actual control execution operator-gated.
-
-Each candidate should land with the minimum missing cells rather than a broad one-shot framework. Already implemented task-first seeds include `pipeline-release-readiness`, `pipeline-release-summary`, `pipeline-repo-health`, `pipeline-async-run-ops`, `pipeline-docs-maintenance`, `pipeline-media-library`, and `pipeline-artifact-bundle`.

package/lib/runtime-notifier.ts

@@ -1,211 +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.
- */
-
-import { randomUUID } from "node:crypto";
-import {
-  appendFileSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  statSync,
-  watch,
-  type FSWatcher,
-} from "node:fs";
-import { basename, dirname, join } from "node:path";
-
-import { readJsonlFileResilient } from "./state-readers.ts";
-
-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[] {
-  return readJsonlFileResilient<Record<string, unknown>>(runtimeWakeFile(stateDir))
-    .records.map((record) => parseRuntimeWakeEventLine(JSON.stringify(record)))
-    .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 pending = "";
-      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;
-          pending = "";
-        }
-        const chunk = pending + buffer.subarray(position).toString("utf8");
-        position = buffer.length;
-        const lines = chunk.split("\n");
-        pending = chunk.endsWith("\n") ? "" : (lines.pop() ?? "");
-        for (const line of lines) {
-          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();
-        },
-      };
-    },
-  };
-}