@llblab/pi-actors 0.43.0 → 0.44.0

package/dist/scripts/locker.mjs

@@ -9,13 +9,11 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
 import {
-  appendFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
-  rmSync,
 } from "node:fs";
 import { createServer } from "node:net";
 import { dirname, join, resolve } from "node:path";
@@ -33,8 +31,13 @@ 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) {
   const args = { mode: "serve", stateDir: "", leaseMs: 600000, lines: 20 };
@@ -59,8 +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 tracePath = join(stateDir, "trace.jsonl");
-  const controlsPath = join(stateDir, "controls.jsonl");
   const controlPath = join(stateDir, "control.fifo");
   let runInstanceId;
   mkdirSync(stateDir, { recursive: true });
@@ -97,25 +98,32 @@ 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") {
-    appendFileSync(
-      tracePath,
-      `${JSON.stringify({
-        attention: "followup",
-        data,
-        id: randomUUID(),
-        kind,
-        level,
-        summary,
-        ts: new Date().toISOString(),
-      })}\n`,
-    );
+    appendRunTraceEvent(stateDir, {
+      attention: "followup",
+      data,
+      kind,
+      level,
+      summary,
+    });
   }
 
   function now() {
@@ -153,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 [];
@@ -403,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",
@@ -415,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;
@@ -454,7 +405,6 @@ async function runLocker(argv = process.argv.slice(2)) {
   }
 
   async function serveNamedPipe(endpoint) {
-    rmSync(endpoint.path, { force: true });
     let resolveStopped;
     const stopped = new Promise((resolve) => {
       resolveStopped = resolve;

package/dist/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,9 @@ 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([
   ".aac",
@@ -407,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) {
@@ -420,18 +420,12 @@ function readText(path) {
 }
 
 function emitPlayerEvent(ctx, kind, summary, data = {}) {
-  writeText(
-    ctx.eventFile,
-    `${JSON.stringify({
-      data,
-      id: randomUUID(),
-      kind,
-      level: "info",
-      summary,
-      ts: new Date().toISOString(),
-    })}\n`,
-    "a",
-  );
+  appendRunTraceEvent(ctx.stateDir, {
+    data,
+    kind,
+    level: "info",
+    summary,
+  });
 }
 
 function emitTrackEvent(ctx, index, count, track, player) {
@@ -589,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) => {
@@ -611,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) {
@@ -759,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;
         }
@@ -779,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;
       }
@@ -859,7 +766,6 @@ async function playMain(args) {
   const ctx = {
     commandFile: join(stateDir, "command.txt"),
     current: undefined,
-    eventFile: join(stateDir, "trace.jsonl"),
     controlsFile: join(stateDir, "controls.jsonl"),
     pidFile: join(stateDir, "current.pid"),
     playerControlFile: join(stateDir, "player-control.txt"),

package/dist/scripts/release-gates.mjs

@@ -145,13 +145,66 @@ try {
   }
   console.log("[release] removed-surface and legacy-fallback allowlists checked");
 
-  const baselineShippedLines = 35_077;
+  const directTraceWrite = /(?:appendFileSync|writeFileSync|writeText(?:Atomic)?)\s*\(\s*[A-Za-z0-9_.]*?(?:trace|event)(?:Path|File)/iu;
+  for (const path of files.filter((candidate) =>
+    (candidate.startsWith("lib/") && candidate.endsWith(".ts")) ||
+    (candidate.startsWith("scripts/") && candidate.endsWith(".mjs"))
+  )) {
+    if (path === "lib/runs-trace.ts") continue;
+    check(!directTraceWrite.test(stagedText(path) ?? ""), `direct Trace writer outside canonical authority: ${path}`);
+  }
+  const canonicalTrace = stagedText("lib/runs-trace.ts") ?? "";
+  check(/withFileMutationLock\(path/u.test(canonicalTrace), "canonical Trace append lacks mutation lock");
+  for (const path of [
+    "scripts/async-runner.mjs",
+    "scripts/locker.mjs",
+    "scripts/music-player.mjs",
+  ]) {
+    const text = stagedText(path) ?? "";
+    check(
+      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 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(
+      "qaReport.diagnostics.length === 0 && qaReport.warnings.length === 0",
+    ),
+    "Recipe QA warnings are not release-blocking",
+  );
+  console.log("[release] zero-warning Recipe QA gate checked");
+
+  const maximumShippedLines = 29_598;
   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} < frozen 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/dist/scripts/validate-recipe.mjs

@@ -29,7 +29,7 @@ export function validateRecipeUsage() {
   return `Usage:
   validate-recipe.mjs <recipe-file-or-dir> [--all] [--qa] [--summary]
 
-Validates one template recipe file, or all *.json/*.md files in a directory when --all is set. Add --qa for packaged-recipe quality checks. Add --summary for compact CLI output.`;
+Validates one template recipe file, or all *.json/*.md files in a directory when --all is set. Add --qa for packaged-recipe quality checks, where diagnostics and warnings fail validation. Add --summary for compact CLI output.`;
 }
 
 function expandPath(value) {
@@ -120,8 +120,6 @@ function validateHelperPaths(file, config) {
 function qaDiagnostics(file, config) {
   const diagnostics = [];
   const warnings = [];
-  if (typeof config.description !== "string" || !config.description.trim())
-    warnings.push("description: missing or empty");
   if (config.mailbox !== undefined)
     diagnostics.push("recipe.mailbox was removed; use control actions and Trace events");
   diagnostics.push(...validateArtifactDeclarations(config));
@@ -138,7 +136,7 @@ function qaDiagnostics(file, config) {
 }
 
 function qaOk(qaReport) {
-  return qaReport.diagnostics.length === 0;
+  return qaReport.diagnostics.length === 0 && qaReport.warnings.length === 0;
 }
 
 function validateFile(file, qa = false) {
@@ -225,6 +223,9 @@ function summarizeReport(report) {
         ...(result.qa?.diagnostics?.length
           ? { diagnostics: result.qa.diagnostics }
           : {}),
+        ...(result.qa?.warnings?.length
+          ? { warnings: result.qa.warnings }
+          : {}),
       })),
   };
 }

package/dist/skills/actors/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: actors
 description: Required practical guide for non-trivial pi-actors use and Run-kernel work. Read before using or changing spawn, message, inspect, Runs, tools, Recipes, command templates, Control, Trace, artifacts, or lifecycle mechanics.
-metadata:
-  version: 0.43.0
 ---
 
 # Actors (pi-actors)
@@ -38,22 +36,30 @@ Prefer maintained packaged Recipes over ad hoc wrappers. Keep model, thinking, m
 Trace records bounded structured observations in `trace.jsonl`:
 
 ```json
-{"id":"…","ts":"…","kind":"progress.update","summary":"…","data":{},"level":"info","attention":"notify"}
+{
+  "id": "…",
+  "ts": "…",
+  "kind": "progress.update",
+  "summary": "…",
+  "data": {},
+  "level": "info",
+  "attention": "notify"
+}
 ```
 
-Trace never carries sender, recipient, route, reply, or message-envelope fields. 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
 
 The public Control request is exact:
 
 ```json
-{"target":"run:<id>","action":"pause","input":{},"verbose":false}
+{ "target": "run:<id>", "action": "pause", "input": {}, "verbose": false }
 ```
 
-Controls persist in `controls.jsonl` before delivery. 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. Expected-status-fenced transitions remain monotonic when a fast consumer completes before sender delivery evidence. FIFO documents must fit the portable 512-byte atomic-write bound, partial writes fail, and controlled FIFO readers remain gap-free across writers. 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
 
@@ -66,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
@@ -73,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.
 
@@ -90,9 +98,7 @@ If work may outlive the current turn, needs steering, produces artifacts, fans o
 
 ## Deep References
 
-- [Actors deep reference](../../docs/actors-deep-reference.md)
 - [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/dist/skills/swarm/SKILL.md

@@ -1,8 +1,6 @@
 ---
 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.43.0
 ---
 
 # Swarm
@@ -267,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.