@llblab/pi-actors 0.41.1 → 0.42.1

package/scripts/async-runner.mjs

@@ -135,7 +135,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
     try {
       return readdirSync(sessionDir, { withFileTypes: true })
         .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
-        .map((entry) => relative(stateDir, join(sessionDir, entry.name)))
+        .map((entry) => relative(stateDir, join(sessionDir, entry.name)).replaceAll("\\", "/"))
         .sort();
     } catch {
       return [];
@@ -167,12 +167,12 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...(recipeContext ? { recipe_context: recipeContext } : {}),
       command: commandDetail,
       ...(materialized.promptFile
-        ? { prompt_file: relative(stateDir, materialized.promptFile) }
+        ? { prompt_file: relative(stateDir, materialized.promptFile).replaceAll("\\", "/") }
         : {}),
       ...(materialized.promptBytes
         ? { prompt_bytes: materialized.promptBytes }
         : {}),
-      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir) } : {}),
+      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir).replaceAll("\\", "/") } : {}),
       attempts: [],
       semantic_acceptance:
         options?.evidenceContext?.acceptOutput === "review_evidence" ||
@@ -209,11 +209,11 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       attempts.push({
         attempt,
         stdout: {
-          path: relative(stateDir, stdoutFile),
+          path: relative(stateDir, stdoutFile).replaceAll("\\", "/"),
           bytes: existsSync(stdoutFile) ? statSync(stdoutFile).size : 0,
         },
         stderr: {
-          path: relative(stateDir, stderrFile),
+          path: relative(stateDir, stderrFile).replaceAll("\\", "/"),
           bytes: existsSync(stderrFile) ? statSync(stderrFile).size : 0,
         },
       });
@@ -248,12 +248,12 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...(recipeContext ? { recipe_context: recipeContext } : {}),
       command: commandDetail,
       ...(materialized.promptFile
-        ? { prompt_file: relative(stateDir, materialized.promptFile) }
+        ? { prompt_file: relative(stateDir, materialized.promptFile).replaceAll("\\", "/") }
         : {}),
       ...(materialized.promptBytes
         ? { prompt_bytes: materialized.promptBytes }
         : {}),
-      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir) } : {}),
+      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir).replaceAll("\\", "/") } : {}),
       ...(commandSessionFiles(sessionDir).length > 0
         ? { session_files: commandSessionFiles(sessionDir) }
         : {}),
@@ -386,7 +386,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       command: commandDetail,
       ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
       ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
-      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir) } : {}),
+      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir).replaceAll("\\", "/") } : {}),
     });
     progressRunning();
     const captureDir = join(stateDir, "captures", commandId);
@@ -457,7 +457,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...captureDetails(result),
       ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
       ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
-      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir) } : {}),
+      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir).replaceAll("\\", "/") } : {}),
       ...(commandSessionFiles(session.sessionDir).length > 0
         ? { session_files: commandSessionFiles(session.sessionDir) }
         : {}),

package/scripts/build-dist.mjs

@@ -20,13 +20,18 @@ import { join } from "node:path";
 
 function run(command, args) {
   const result = spawnSync(command, args, { stdio: "inherit" });
+  if (result.error) throw result.error;
   if (result.status !== 0) process.exit(result.status ?? 1);
 }
 
 rmSync("dist", { recursive: true, force: true });
 mkdirSync("dist", { recursive: true });
 
-run("tsc", ["-p", "tsconfig.build.json"]);
+run(process.execPath, [
+  join("node_modules", "typescript", "bin", "tsc"),
+  "-p",
+  "tsconfig.build.json",
+]);
 
 mkdirSync(join("dist", "pi-actors"), { recursive: true });
 writeFileSync(

package/scripts/conformance.mjs

@@ -28,7 +28,12 @@ function packageRoot() {
 
 const result = spawnSync(
   process.execPath,
-  ["--experimental-strip-types", "--test", ...conformanceSuites],
+  [
+    "--experimental-strip-types",
+    "--test",
+    "--test-concurrency=1",
+    ...conformanceSuites,
+  ],
   { cwd: packageRoot(), encoding: "utf8", stdio: "pipe" },
 );
 

package/scripts/recipe-utils.mjs

@@ -16,7 +16,7 @@ import {
   statSync,
   writeFileSync,
 } from "node:fs";
-import { dirname, extname, join, relative, resolve } from "node:path";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 
 function usage() {
   console.error(`Usage:
@@ -101,7 +101,7 @@ function collectRunSummary(rootValue) {
   const root = resolve(
     rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
   );
-  const files = walkFiles(root, 2).filter((file) => file.endsWith("/run.json"));
+  const files = walkFiles(root, 2).filter((file) => basename(file) === "run.json");
   const rows = [];
   for (const file of files) {
     const run = readJson(file);
@@ -118,7 +118,7 @@ function collectRunSummary(rootValue) {
     const progress = readJson(join(runDir, "progress.json"));
     const result = readJson(join(runDir, "result.json"));
     rows.push({
-      run: run.run_id ?? run.run ?? relative(root, file).split("/")[0],
+      run: run.run_id ?? run.run ?? relative(root, file).split(sep)[0],
       status: getRunStatus(run, progress, result),
       recipe: run.recipe ?? run.recipe_file ?? "",
       updated:

package/scripts/release-gates.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/** Reproducible exact-tree, Domain DAG, secret-hygiene, and ABCd release gates. */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, extname, join, normalize, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const temp = mkdtempSync(join(tmpdir(), "pi-actors-release-index-"));
+const indexPath = join(temp, "index");
+const gitEnv = { ...process.env, GIT_INDEX_FILE: indexPath };
+const failures = [];
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+    ...options,
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      `${command} ${args.join(" ")} failed (${result.status}): ${(result.stderr || result.stdout || "no output").trim()}`,
+    );
+  }
+  return result.stdout;
+}
+
+function check(condition, message) {
+  if (!condition) failures.push(message);
+}
+
+function stagedText(path) {
+  const result = spawnSync("git", ["show", `:${path}`], {
+    cwd: root,
+    env: gitEnv,
+    encoding: "buffer",
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.status !== 0) {
+    failures.push(`could not read staged file: ${path}`);
+    return undefined;
+  }
+  const bytes = result.stdout;
+  if (bytes.includes(0)) return undefined;
+  return bytes.toString("utf8");
+}
+
+function sourceImports(source) {
+  return [...source.matchAll(/^import(?:\s+type)?\s+(?:[^"']+?\s+from\s+)?["']([^"']+)["'];?$/gmu)]
+    .map((match) => match[1]);
+}
+
+function resolveLocalImport(from, specifier, sourceSet) {
+  if (!specifier.startsWith(".")) return undefined;
+  const base = normalize(join(dirname(from), specifier)).replaceAll("\\", "/");
+  const candidates = extname(base)
+    ? [base.replace(/\.js$/u, ".ts")]
+    : [`${base}.ts`, `${base}/index.ts`];
+  return candidates.find((candidate) => sourceSet.has(candidate));
+}
+
+try {
+  run("git", ["read-tree", "HEAD"], { env: gitEnv });
+  run("git", ["add", "-A"], { env: gitEnv });
+  run("git", ["diff", "--cached", "--check"], { env: gitEnv });
+  const files = run("git", ["ls-files", "-z"], { env: gitEnv })
+    .split("\0")
+    .filter(Boolean);
+  const fileSet = new Set(files);
+  console.log(`[release] exact temporary index: ${files.length} files`);
+
+  const secretPatterns = [
+    [/-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----[\s\S]{80,}?-----END(?: [A-Z0-9]+)? PRIVATE KEY-----/u, "private-key block"],
+    [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/u, "AWS access key"],
+    [/\bgithub_pat_[A-Za-z0-9_]{20,}\b|\bgh[pousr]_[A-Za-z0-9]{20,}\b/u, "GitHub token"],
+    [/\bglpat-[A-Za-z0-9_-]{20,}\b|\bnpm_[A-Za-z0-9]{20,}\b|\bxox[baprs]-[A-Za-z0-9-]{10,}\b/u, "service token"],
+  ];
+  const publicPath = /^(?:README\.md|AGENTS\.md|BACKLOG\.md|CHANGELOG\.md|docs\/|skills\/|recipes\/)/u;
+  for (const path of files) {
+    const text = stagedText(path);
+    if (text === undefined) continue;
+    if (!path.startsWith("tests/") && !path.startsWith("fixtures/")) {
+      for (const [pattern, label] of secretPatterns) {
+        check(!pattern.test(text), `${label} detected in ${path}`);
+      }
+    }
+    if (publicPath.test(path)) {
+      check(!/(?:^|[\s"'`])\/home\/[A-Za-z0-9._-]+\//u.test(text), `machine-local path in ${path}`);
+    }
+  }
+  console.log("[release] bounded secret and public-path hygiene checked");
+
+  const sources = files.filter((path) => path === "index.ts" || (path.startsWith("lib/") && path.endsWith(".ts")));
+  const sourceSet = new Set(sources);
+  const graph = new Map();
+  for (const path of sources) {
+    const text = stagedText(path) ?? "";
+    const headerEnd = text.indexOf("*/");
+    const header = headerEnd >= 0 ? text.slice(0, headerEnd + 2) : "";
+    check(
+      header.startsWith("/**") && (header.includes("Zones:") || header.includes("Owns:")),
+      `missing domain header: ${path}`,
+    );
+    const edges = sourceImports(text)
+      .map((specifier) => resolveLocalImport(path, specifier, sourceSet))
+      .filter(Boolean);
+    graph.set(path, edges);
+    if (path.startsWith("lib/")) {
+      check(!edges.includes("index.ts"), `domain imports entrypoint: ${path}`);
+    }
+  }
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(path, stack = []) {
+    if (visiting.has(path)) {
+      failures.push(`Domain DAG cycle: ${[...stack, path].join(" -> ")}`);
+      return;
+    }
+    if (visited.has(path)) return;
+    visiting.add(path);
+    for (const next of graph.get(path) ?? []) visit(next, [...stack, path]);
+    visiting.delete(path);
+    visited.add(path);
+  }
+  for (const path of sources) visit(path);
+  console.log(`[release] strict Domain DAG: ${sources.length} sources, acyclic`);
+
+  for (const path of ["README.md", "AGENTS.md", "BACKLOG.md", "CHANGELOG.md", "docs/README.md"]) {
+    check(fileSet.has(path), `missing ABCd root/context file: ${path}`);
+  }
+  const readStaged = (path) => stagedText(path) ?? "";
+  const readme = readStaged("README.md");
+  for (const path of ["AGENTS.md", "BACKLOG.md", "CHANGELOG.md", "docs/README.md"]) {
+    check(readme.includes(path), `README.md does not route to ${path}`);
+  }
+  for (const path of files.filter((candidate) => candidate.endsWith(".md"))) {
+    const text = readStaged(path);
+    for (const match of text.matchAll(/\[[^\]]*\]\(([^)]+)\)/gu)) {
+      const target = match[1].split("#", 1)[0];
+      if (!target || /^(?:https?:|mailto:)/u.test(target)) continue;
+      const resolved = normalize(join(dirname(path), decodeURIComponent(target))).replaceAll("\\", "/");
+      check(fileSet.has(resolved), `broken Markdown link: ${path} -> ${target}`);
+    }
+  }
+  const docsIndex = readStaged("docs/README.md");
+  for (const path of files.filter((candidate) => candidate.startsWith("docs/") && candidate.endsWith(".md") && candidate !== "docs/README.md")) {
+    check(docsIndex.includes(relative("docs", path).replaceAll("\\", "/")), `docs/README.md omits ${path}`);
+  }
+  console.log("[release] ABCd context roots, routing, and Markdown links checked");
+
+  if (failures.length > 0) {
+    for (const failure of failures) console.error(`[FAIL] ${failure}`);
+    process.exitCode = 1;
+  } else {
+    console.log("[release] all supplemental release gates passed");
+  }
+} catch (error) {
+  console.error(`[FAIL] ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+} finally {
+  rmSync(temp, { recursive: true, force: true });
+}

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use, including parallel actor launches, subagent fanout, and autonomous coordinator workflows. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.41.1
+  version: 0.42.1
 ---
 
 # Actors (pi-actors)
@@ -40,7 +40,7 @@ Trusted local capability
 - **Command template**: portable execution graph. String leaf, sequence array, or object node with controls.
 - **Recipe**: saved JSON definition wrapping a template with args, defaults, imports, mailbox, artifacts, metadata, and optional `async: true`.
 - **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, and artifacts.
-- **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`. `tool:pi-actors` is reserved for runtime/status inspection.
+- **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`. `tool:pi-actors` is reserved for runtime status and explicit automatic-review retry/reset control.
 - **Artifact**: named durable output path declared by a recipe/run.
 - **Mailbox**: interaction contract: message types the actor accepts/emits.
 - **Advanced group/coordination surfaces**: `branch:<run>/<branch>`, `room:<run>`, `coordinator`, `session:<id>`, and communication snapshots exist for multi-actor workflows and diagnostics; do not make them the default mental model.
@@ -94,7 +94,8 @@ Envelope fields:
 - Group posts to `room:<run>` require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
 - Runtime termination message: `control.kill` is the only documented actor message that kills a run. `control.stop` and `control.cancel` are actor-local mailbox vocabulary only when a recipe declares and handles them. Terminal retention messages: `control.archive`, `control.prune`.
 - Long-lived child processes should remain in the run-owned process group unless the recipe implements an explicit daemon termination bridge; do not leave unowned detached services behind `control.kill`.
-- Run controls revalidate a persisted cross-platform process identity proof before delivery or signaling. Treat `dead pid`, `owner mismatch`, and `unsupported proof` as distinct fail-closed states; never bypass them with direct pid signals.
+- Run controls revalidate a persisted cross-platform process identity proof at authorization and again immediately before signaling. Treat `dead pid`, `owner mismatch`, and `unsupported proof` as distinct fail-closed states; on Unix, only process-group `ESRCH` plus one more matching identity check permits exact-pid fallback, while permission/authorization errors remain terminal. Node exposes no portable pidfd/process-group handle, so retain the documented residual exit/reuse window instead of claiming atomic signaling or bypassing control with direct pid signals.
+- Detached actors survive ordinary agent turns. On `session_shutdown` (quit, reload, or session replacement), pi-actors attempts canonical `control.kill` for each discovered readable still-running exact-owner run. Control compares immutable run generation inside the canonical boundary and serializes against same-directory restart; terminal, ambiguous, changed-generation, and other-session runs remain untouched. Teardown scans without the ordinary index depth cap, reports unreadable/corrupt state as failures, and persists a bounded summary under the run root. Descendant Pi sessions remain separate owners and rely on their own shutdown hooks; hard host termination can still leave an orphan requiring summary-guided OS/manual recovery, so never describe teardown as an absolute no-survivor guarantee.
 
 Check `inspect view=mailbox` before domain-specific messages.
 
@@ -216,15 +217,15 @@ Only matching filename ids compete. Higher priority shadows lower priority; with
 Muscle-memory lens: pi-actors has two durable executable-memory layers.
 
 1. `~/.pi/agent/recipes/*.json` and `*.md` are the agent's active capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Descriptions matter here because they become the tool's operator-facing title/context.
-2. `~/.pi/agent/recipes/drafts/*.json` is draft memory captured from successful inline `spawn template=...` runs. Drafts do not enter the injected tool surface. They remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/drafts/<name>.json"`, and can be promoted by moving or copying one level up into `~/.pi/agent/recipes`.
+2. `~/.pi/agent/recipes/drafts/*.json` is draft memory captured from successful inline `spawn template=...` runs. Drafts do not enter the injected tool surface and remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/drafts/<name>.json"`.
 
-Agents grow active memory by calling `register_tool` or by deliberate recipe-file edits. They grow draft memory by trying ad hoc actors successfully. Treat both as executable habits: drafts are the workbench/proving ground; root recipes are promoted muscle memory.
+Agents grow draft memory by trying ad hoc actors successfully. Active memory grows through explicit `register_tool`, deliberate operator recipe edits, or the bounded automatic review cycle. Treat drafts as the workbench and root recipes as active muscle memory.
 
-Usage lens: user recipe launches update extension-maintained `.usage/<recipe-filename>.json` sidecars with fields such as `usage.calls` and `usage.last_called`; authored recipe files are not rewritten for telemetry. Discovery merges the sidecar into inspection. Agents should not hand-edit counters as part of normal recipe maintenance. Treat usage as evidence for usefulness analysis: heavily used recipes are good candidates for promotion, documentation, or stronger tests; unused recipes are cleanup candidates. Do not use failure counts as a primary usefulness signal because failures may reflect bad caller judgment rather than bad recipes. Do not delete or demote solely from counters without operator approval.
+Usage lens: user recipe launches update an extension-maintained canonical name-and-priority lineage ledger under `.usage/recipes/<recipe-name>.json`; authored recipe files are not rewritten for telemetry. Accounting briefly shares the portfolio mutation fence so source quarantine cannot erase an authorized launch; if another session already changed the source, the stale invocation rejects and requests reload rather than executing without evidence. Lifetime calls survive rename, revision, promotion, and demotion, while revision-local calls restart when executable content changes. The bounded unversioned ledger retains former names/paths, revision ancestry, transition events, and review epochs. Discovery merges lineage usage into inspection. Agents should not hand-edit counters; usage remains evidence rather than a sufficient usefulness verdict.
 
-Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. Inline spawns leave draft recipes as replayable evidence, not active tools. If a draft is repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by moving/copying it into `~/.pi/agent/recipes` or by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not auto-register every success; do not promote temp paths, secrets, one-off prompts, or project-private assumptions without normalization and approval.
+Automatic review lens: successful transient/ad hoc actor runs leave replayable drafts rather than active tools. At twelve eligible drafts, pi-actors captures one exact trusted batch and attaches only its identity-opaque value-free structural projection to a silent no-tools reviewer after the foreground turn and active actors finish. Its complete quota-free `promote`/`discard` result contains no recipe content: the deterministic executor derives promotions from exact captured sources and revalidates source/target CAS, complete recipes, root identity, quarantine hashes, and recovery state before commit. Newer drafts remain for a later batch; malformed, stale, unsafe, or incomplete decisions fail closed. Unchanged automatic demotions remain in cooldown until their executable fingerprint changes. Prefer fenced `register_tool draft=...` for an explicit single-draft promotion. A deliberate move/copy into the recipe root also remains valid, but may invalidate and defer an already captured batch; do not reconstruct removed batch commands or ask the operator to drive an automatic batch.
 
-Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memory set. For each stale, duplicate, too-specific, or low-value recipe, choose one explicit action: keep as a tool, move it out of the agent recipe root to retain recipe-only memory, merge into a better recipe, or delete/archive the file. Prefer moving over deletion when the recipe may still be useful as a component. Never silently remove tools during unrelated work.
+Portfolio lens: thirty-six eligible non-sensitive active revisions trigger a no-tools review of an attached value-free structural projection; canonical names, draft basenames, raw hashes, recipe bodies, template/default values, authored prose, and filesystem paths remain in the separate trusted capture; batch-local occurrence IDs and equality-only content groups preserve correlation and deduplication. Set `PI_ACTORS_AUTOMATIC_REVIEW=off` before Pi starts to disable both reviewer scheduling and safe-boundary portfolio activation; verify the effective value with `inspect target=tool:pi-actors view=status`. The reviewer may select keep, unchanged-source rename, unchanged-source demotion, or deduplication of canonically identical captured recipes; it cannot return recipe content. Replacement, split, and executable contract changes require explicit operator authoring. Approval remains immutable until the next safe session boundary, where journaled filesystem and lineage executors apply only the captured recipe bytes. Use `inspect target=recipes view=reviews` for bounded evidence including failed stage/error/next action. Recover a failed cycle through `message to=tool:pi-actors type=review.retry body={"scope":"draft"|"tool"}`. Draft retry resumes an existing authenticated transaction plan and original reviewer run rather than generating decisions after filesystem commit; `review.reset` clears only disposable terminal admission state and rejects tool recovery evidence that must roll forward.
 
 ## Registered Tools
 

package/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent and actor orchestration with scoped locks, fanout, and quorum consensus. Use before launching multiple parallel actors or subagents for independent implementation, artifact generation, review, delegated audit, coordinated execution, or any workflow that needs autonomous coordinator decomposition and integration.
 metadata:
-  version: 0.41.1
+  version: 0.42.1
 ---
 
 # Swarm