@llblab/pi-actors 0.43.0 → 0.43.1

package/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,20 +36,28 @@ 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. 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.
 
 ## 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 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.
 
 `kill` remains a runtime lifecycle action. Use an actor-local action such as `stop` only when the Recipe declares and implements it.
 
@@ -90,7 +96,6 @@ 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)

package/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

package/docs/actors-deep-reference.md

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

package/docs/component-recipes.md

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

package/docs/task-first-recipes.md

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