@llblab/pi-actors 0.43.1 → 0.45.0

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

package/dist/scripts/release-gates.mjs

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

package/dist/skills/actors/SKILL.md

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

package/dist/skills/swarm/SKILL.md

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

package/docs/README.md

@@ -4,7 +4,6 @@ Living index of all documentation in the `/docs` directory.
 
 ## Documents
 
-- [0.43-baseline.md](./0.43-baseline.md) — Released tree, strict shipped-line ratchet, and retained-invariant preservation evidence
 - [command-templates.md](./command-templates.md) — Portable synchronous command execution standard
 - [template-recipes.md](./template-recipes.md) — Saved JSON/Markdown recipe standard, imports, and reusable command-template graph composition
 - [async-runs.md](./async-runs.md) — Run lifecycle, state, Control, Trace, cancellation, and terminal reconciliation

package/docs/actor-inspector.md

@@ -24,7 +24,7 @@ Captured Recipe evidence belongs to the Run generation and does not change when
 
 Shows the unified bounded Trace projection. Sources include lifecycle/runtime observations, Controls, owned Pi turns, command-log tails, results, artifacts, and diagnostics. Filter by source and open a row for structured detail.
 
-Trace ordering stays deterministic and newest-first. Row numbers still read chronologically from bottom to top: the oldest visible event is `#1` and the newest carries the highest number. The projection applies path containment and redaction before rendering.
+Trace ordering stays deterministic and newest-first: timestamp descending, same-source physical ordinal descending, fixed internal source rank, then stable id. Internal ordinals are never displayed or interpreted as cross-source causality. Row numbers still read chronologically from bottom to top: the oldest visible event is `#1` and the newest carries the highest number. The summary states whether retained history is complete; `runtime.trace_compacted` means older history was discarded and shows bounded cumulative drop evidence. Terminal/result/execution/artifact evidence keeps its own authority. The projection applies path containment and redaction before rendering.
 
 ## Control
 
@@ -33,9 +33,10 @@ Shows:
 - Recipe-declared actor-local actions;
 - runtime-owned lifecycle actions;
 - generation-fenced endpoint readiness;
+- pending capacity, saturation, journal bytes, stale count, and diagnostics;
 - recent durable Control records and outcomes.
 
-A service endpoint counts as ready only when `control-endpoint.json` matches the Run's immutable `run_instance_id`. Recent Control input and errors use the same bounded structured redaction as tool inspection. The durable `controls.jsonl` journal remains raw and local; rendering never mutates it or attaches an unredacted copy.
+A service endpoint counts as ready only when `control-endpoint.json` matches the Run's immutable `run_instance_id`. Capacity reaches zero at 64 pending Controls; further requests are rejected before admission, while admitted nonterminal Controls never expire automatically. Runtime-owned kill remains available for a stuck saturated Run. Recent Control input and errors use the same bounded structured redaction as tool inspection. The durable `controls.jsonl` journal remains raw and local; rendering never mutates it or attaches an unredacted copy.
 
 ## Keys
 

package/docs/async-runs.md

@@ -55,9 +55,9 @@ Trace records strict bounded events:
 {"id":"…","ts":"…","kind":"command.done","summary":"Command completed","data":{"code":0},"level":"info","attention":"followup"}
 ```
 
-Required fields: `id`, `ts`, `kind`. Optional fields: `summary`, `data`, `level`, `attention`. Trace rejects addressed-envelope fields and malformed or oversized data. All first-party writers use the canonical append authority, which validates and size-checks inside a token-owned cross-process lock before one append-only JSONL write.
+Required fields: `id`, `ts`, `kind`. Optional fields: `summary`, `data`, `level`, `attention`. Trace rejects addressed-envelope fields and malformed or oversized data. It retains a recent suffix within 2,048 events and 4 MiB. When either bound would be exceeded, the canonical lock atomically keeps a newest suffix near the lower targets, the new event, and one cumulative warning-only `runtime.trace_compacted` marker. The marker means older history was discarded; it reports cumulative drop evidence and never requests attention.
 
-Runtime lifecycle, runner progress, command completion, cancellation, kill, parent teardown, and controlled-service observations use Trace. `inspect view=trace` projects these events with Controls, owned Pi turns, logs, results, artifacts, and diagnostics under a deterministic global bound.
+Runtime lifecycle, runner progress, command completion, cancellation, kill, parent teardown, and controlled-service observations use Trace. Bounded reads preserve complete UTF-8 lines and disclose omitted legacy prefixes. `inspect view=trace` reports retained-history completeness and projects events with Controls, owned Pi turns, logs, results, artifacts, and diagnostics newest-first. Equal timestamps use same-source physical order, then fixed source rank and stable id without claiming cross-source causality. Terminal state, `result.json`, `execution.json`, and artifacts remain authoritative even when old Trace has compacted.
 
 ## Control
 
@@ -84,13 +84,13 @@ The runtime:
 
 Unix services may publish a FIFO; native Windows services publish a Windows named pipe. Native Windows FIFO delivery fails before transport rather than degrading to another protocol. Both transports admit the same portable envelope: action is at most 64 lowercase ASCII characters, serialized JSON input is at most 380 bytes, and the newline-terminated wire record is at most 512 bytes. Invalid envelopes fail before journal admission or transport. Put larger data in a declared artifact/path and send only a bounded reference or instruction through Control.
 
-A service claims queued or transport-delivered Controls and records handled/failed outcomes under the token-owned Control journal lock. Journal snapshots replace atomically, and expected-status fencing prevents delivery failure evidence from regressing a Control already claimed or completed by a fast consumer. Terminal compaction remains bounded. Services capture their startup generation, so stale-generation Controls never execute.
+A service exact-id claims queued or transport-delivered Controls and records handled/failed outcomes through the canonical Control journal authority. Admission performs one locked read, integrity/generation check, terminal-tail compaction, capacity decision, and atomic write. The 65th pending Control and a rewrite exceeding 1 MiB fail as bounded `control_backpressure` before admission; malformed, unreadable, oversized, or stale-generation journals fail with an integrity reason and no rejected record. `inspect view=control` reports pending capacity, saturation, stale work, journal bytes, and diagnostics. Every transition uses the same lock, expected-state fence, 128-terminal compaction, and atomic bounded rewrite; persisted errors truncate inside the string at 4 KiB. Admitted nonterminal Controls never expire automatically. Delivery failure evidence cannot regress a Control already claimed or completed by a fast consumer. Services capture their startup generation, so stale-generation Controls never execute.
 
-Runtime lifecycle `kill`, retention actions, and review retry/reset remain runtime-owned rather than Recipe-declared.
+Runtime lifecycle `kill`, retention actions, and review retry/reset remain runtime-owned rather than Recipe-declared. Kill is the recovery path for a stuck saturated Run: it bypasses actor-local Control capacity and creates no synthetic Control. Same-directory restart clears all generation-local evidence before the new `run_instance_id`; archive moves the exact bounded terminal tree, while prune removes kernel state and preserves only explicitly requested artifacts.
 
 ## Execution Evidence
 
-`execution.json` stores general command/session provenance. The async runner keeps bounded stdout/stderr logs plus bounded complete captures when semantic validation requires untruncated evidence. Pi command execution also records owned session provenance for later Trace projection and review checks.
+`execution.json` stores general command/session provenance. The async runner keeps bounded stdout/stderr logs plus complete capture artifacts when semantic validation requires untruncated evidence. Pi command execution also records owned session provenance for later Trace projection and review checks. Trace and Control quotas do not constrain declared user artifacts, repositories or media sources, complete execution captures, or actor-owned queue/workload state; each remains governed by its own lifecycle and policy.
 
 Review acceptance remains a command-stage concern. General execution evidence does not imply review approval.
 
@@ -98,7 +98,7 @@ Review acceptance remains a command-stage concern. General execution evidence do
 
 Statuses include `running`, `done`, `failed`, `exited`, `cancelled`, and `killed`. Status resolution combines persisted metadata, result/terminal evidence, and verified process state.
 
-Ambient observation detects terminal transitions and Trace attention. Terminal follow-up delivery persists handled/failure evidence so reloads retry unhandled transitions without duplicating completed notifications.
+Ambient observation detects terminal transitions and retained Trace attention. Canonical attention is an in-memory wake hint, not a durable queue: observers prime retained ids at startup, deliver each later retained unseen id once, and bound memory to the current retained set across compaction. Persist durable recovery state or an artifact before emitting attention; compaction may discard older hints and its marker makes that history loss explicit. Terminal follow-up delivery persists handled/failure evidence so reloads retry unhandled transitions without duplicating completed notifications.
 
 Large semantic results stay outside compact visible follow-up text and remain available in structured details, execution captures, or artifacts.
 
@@ -124,7 +124,9 @@ Archive and prune apply only to terminal Runs and enforce path containment. Rete
 Packaged controlled services demonstrate the endpoint protocol:
 
 - `music-player` consumes playback Controls and emits playback Trace;
-- `resource-locker` consumes queue/lease actions and emits lock Trace.
+- `resource-locker` consumes queue/lease actions, emits lock Trace, and atomically retains at most 512 valid journal records within 1 MiB.
+
+Shared archive/prune evidence similarly retains at most 256 valid records within 1 MiB under its canonical lock. The obsolete advisory `wake.jsonl` notifier was removed; filesystem watchers and bounded reconciliation observe authoritative state directly.
 
 One-shot pipelines omit Control and terminate through their command graph.
 
@@ -136,4 +138,4 @@ inspect target=run:<id> view=trace source=lifecycle lines=40
 inspect target=run:<id> view=control
 ```
 
-Use `/actor-inspector` to inspect Runs as concrete actor instances in the live TUI. Runtime, Recipe registry, and tool definitions remain separate management targets.
+Use `/actor-inspector` to inspect Runs as concrete actor instances in the live TUI. Runtime, Recipe registry, and tool definitions remain separate management targets. No public noun, tool, target, or view is added by bounded retention.

package/docs/command-templates.md

@@ -53,7 +53,7 @@ Common object fields:
 - `concurrency`: Optional positive integer cap for a `parallel: true` node. Omit it to launch all children at once.
 - `min_successful`: Optional non-negative integer evidence threshold for a `parallel: true` node. Usable branches are successful branches with non-empty stdout; joins include a `parallel_status` header when this is set.
 - `when`: Optional node guard. A false guard skips the node; strings may be `flag`, `!flag`, or `{flag?yes:no}` style expressions.
-- `args`: Optional placeholder declarations. Untyped names remain valid; compact typed forms such as `file:path`, `request_timeout:int`, `speed:number`, `dry_run:bool`, `prompts:array`, and `mode:enum(check,fix)` are valid when the host supports typed tool schemas. Defaults belong in `defaults` or inline placeholder defaults; hosts may normalize interactive shorthand such as `request_timeout:int=60000` before persistence.
+- `args`: Optional placeholder declarations. Untyped names remain valid; compact typed forms such as `file:path`, `request_timeout:int`, `speed:number`, `dry_run:bool`, `prompts:array`, and `mode:enum(check,fix)` are valid when the host supports typed tool schemas. `name:type=value` is an optional argument with an inline fallback. Hosts reject duplicate names and conflicting declared/placeholder types rather than selecting one silently.
 - `defaults`: Placeholder default values by name.
 - `timeout`: Optional execution timeout in milliseconds. Omit it, or set `0`, to leave the command unbounded. Set an explicit positive timeout when a tool must fail closed instead of waiting indefinitely. Numeric control fields may be literal numbers or placeholders such as `"{timeout_ms}"`.
 - `delay`: Optional wait in milliseconds before starting this node. Default is no delay. It may be a literal number or placeholder.
@@ -104,7 +104,7 @@ With runtime values `{ "text": "hello" }`, argv is:
 ["--text", "hello", "--lang", "ru", "--rate", "+30%"]
 ```
 
-Use `defaults` for visible configuration data; use inline defaults for compact local literals. Prefer flag-style examples such as `/path/to/tool --file {file} --lang {lang=ru}` for readability, but positional forms such as `/path/to/tool {file} {lang=ru}` are valid when the invoked script defines that CLI contract.
+Use `defaults` for visible fallback configuration, `values` for composition binding, and inline defaults for compact local literals. Named resolution uses caller values before composition values, explicit defaults, and inline defaults; the final selected value is type/enum validated. Prefer flag-style examples such as `/path/to/tool --file {file} --lang {lang=ru}` for readability, but positional forms such as `/path/to/tool {file} {lang=ru}` are valid when the invoked script defines that CLI contract.
 
 Use `{env??dev}` for fallback values and `{all?--all:}` to map boolean args to optional text.
 

package/docs/recipe-library.md

@@ -35,7 +35,7 @@ Artifact pipelines terminate in files/manifests and result evidence; they do not
 ### Controlled services
 
 - `music-player.json` — playback service with declared playback actions, `controls.jsonl`, generation-fenced endpoint readiness, state artifact, and playback Trace. Player selection is `player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto`.
-- `resource-locker.json` — optional queue/lease-lock service with explicit owner/resource input and lock Trace.
+- `resource-locker.json` — optional queue/lease-lock service with explicit owner/resource input, lock Trace, and a 512-record/1 MiB atomically retained journal.
 
 These are the packaged Recipes that declare actor-local Control. Ordinary one-shot Recipes omit it. Helper-backed packaged Recipes self-locate their installed package root when `repo` is omitted; an explicit caller value still wins for development or custom layouts.
 
@@ -45,6 +45,8 @@ Subagent components provide reusable command-template cells for normalization, p
 
 Imports compose these definitions inside one parent Run. They are not independently addressable peers. Parent template flags control sequencing, parallelism, retries, failure scope, recovery, and repeated execution.
 
+Packaged components can be selected exactly as `std:<recipe-name>`. Recipes bundled under a Pi-active Skill are selected as `skill:<skill-name>/<recipe-path>` and receive runtime-owned `{skill_dir}` plus `{recipe_dir}`. Active Skill components are namespaced library entries, never automatic tools; expose one intentionally through a user Recipe wrapper when a direct tool is desired.
+
 ## Utility Recipes
 
 Utilities wrap deterministic local capabilities such as:
@@ -64,7 +66,7 @@ Use utilities as imported cells or registered tools where their contract fits.
 3. Use inline templates for genuinely one-off trusted work.
 4. Declare artifacts for outputs that callers must retain.
 5. Declare Control only when a service process actually consumes it.
-6. Keep large semantic evidence in artifacts or execution captures, not Trace summaries.
+6. Keep large semantic evidence in artifacts or execution captures, not Trace summaries; Trace/Control quotas do not bound user artifacts or actor-owned workload state.
 
 ## Installation Safety
 

package/docs/template-recipes.md

@@ -44,7 +44,7 @@ Fences marked `template`, `command-template`, `json`, or `recipe` can define exe
 Common Recipe fields:
 
 - `name`, `description`, `disabled`;
-- `args`, typed arg declarations, and `defaults`;
+- `args`, typed arg declarations, inline defaults, `defaults`, and composition `values`;
 - `imports` with optional binding defaults/values;
 - `template`;
 - `async`;
@@ -71,7 +71,9 @@ Common Recipe fields:
 }
 ```
 
-Imports are local definitions. Named nodes call imported templates inside the same execution graph and Run. Resolution enforces Recipe-root priority, file-size/depth bounds, and cycle rejection.
+Imports are local definitions. Named nodes call imported templates inside the same execution graph and Run. Effective values follow `caller > node/import/Recipe values > defaults > inline arg default > missing-value error`, then the selected value is checked against its declared type or enum.
+
+Bare references preserve user → adjacent → packaged resolution. `std:<name>` selects a packaged Recipe exactly. `skill:<skill-name>/<recipe-path>` selects a component under the `recipes/` tree of a Skill currently active through Pi resource discovery. Skill Recipes never become tools merely by existing, and duplicate active Skill names fail as ambiguous rather than shadowing silently.
 
 Direct delegation can use another Recipe as the entire template. The delegated Recipe remains the source of truth while the wrapper may narrow args/defaults or override selected lifecycle metadata.
 
@@ -102,9 +104,13 @@ Actions must be lowercase ASCII, unique, non-reserved, and at most 64 characters
 
 Artifact paths resolve under containment policy and appear in Run inspection. Recipes should write declared artifacts deterministically and fail when the requested write policy cannot be honored.
 
+## File Origins
+
+Every file-backed Recipe receives immutable `{recipe_dir}`. A Recipe under an active Skill also receives `{skill_dir}`, resolved to the directory containing that Skill's `SKILL.md`; using `{skill_dir}` elsewhere fails clearly. These runtime values cannot be declared in `args`, `defaults`, or `values`, and caller input cannot override them. They expand in templates, recursive defaults/values, imports, and artifacts while existing `./` executable behavior remains relative to invocation `cwd`.
+
 ## Context and Provenance
 
-File-backed Runs capture Recipe context records for the entry and imports. The captured bundle explains composition identity and remains generation-local evidence. It does not override the authored task prompt.
+File-backed Runs capture Recipe context records for the entry and imports, including qualified `std:` or `skill:` identity when applicable. The captured bundle explains composition identity and remains generation-local evidence. Runtime origin paths remain in local Run provenance but are omitted from model-facing launch values. It does not override the authored task prompt.
 
 Recipes that need a minimal child prompt may opt out of injected Recipe context through the documented `actor_context` launch option.
 
@@ -125,7 +131,7 @@ Resolution fails before launch when required current policy is unavailable. The
 
 ## Resolution and Shadowing
 
-User Recipes under `~/.pi/agent/recipes` take priority over packaged Recipes. An invalid active file blocks fallback and reports both paths. Disabled Recipes cannot launch. Registry watchers converge after atomic changes without executing partial definitions.
+User Recipes under `~/.pi/agent/recipes` take priority over adjacent and packaged Recipes for compatible bare lookup. Exact `std:` and `skill:` references bypass that ambiguous space. The active Skill namespace converges from Pi's loaded Skill metadata on startup/reload; pi-actors does not scan ambient Skill roots independently. An invalid active file blocks fallback and reports both paths. Disabled Recipes cannot launch. Registry watchers converge after atomic changes without executing partial definitions.
 
 ## Validation
 

package/docs/tool-registry.md

@@ -61,7 +61,7 @@ Usage and lineage live in locked metadata ledgers rather than authored Recipe fi
 
 ## Wrapping Existing Recipes
 
-Prefer a small user-root wrapper that imports a maintained packaged or skill-owned Recipe by path and delegates by alias. Do not duplicate its executable template, defaults, Control declaration, or artifacts. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
+Prefer a small user-root wrapper that imports a maintained Recipe by exact `std:<recipe>` or `skill:<skill>/<recipe-path>` identity and delegates by alias. Skill Recipes remain components and are never exposed merely because their Skill is active. Do not duplicate executable templates, defaults, Control declarations, artifacts, or runtime-owned `{recipe_dir}`/`{skill_dir}`. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
 
 ## Safety
 

package/index.ts

@@ -11,6 +11,7 @@ import * as InspectorCommand from "./lib/inspector-command.ts";
 import * as Paths from "./lib/paths.ts";
 import * as Pi from "./lib/pi.ts";
 import * as Prompts from "./lib/prompts.ts";
+import * as RecipesReferences from "./lib/recipes-references.ts";
 import * as RunUiRuntime from "./lib/run-ui-runtime.ts";
 import * as Runtime from "./lib/runtime.ts";
 import * as Temp from "./lib/temp.ts";
@@ -98,9 +99,14 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     runUiRuntime.shutdown(event.reason, ctx);
   });
   InspectorCommand.registerActorInspectorCommand(pi, getRunOwnerId);
-  pi.on("before_agent_start", async (event) => ({
-    systemPrompt: `${event.systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
-  }));
+  pi.on("before_agent_start", async (event) => {
+    RecipesReferences.setActiveSkillRecipeSources(
+      event.systemPromptOptions.skills ?? [],
+    );
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
+    };
+  });
   Pi.registerToolDefinitions(
     pi,
     Tools.createCoreActorToolDefinitions<Pi.ExtensionContext>({