# Changelog

## Unreleased

## 0.42.0: Automatic Recipe Evolution and Recipe-first Inspector

- `Recipe-first Inspector`: The Inspector now opens on a bounded, redacted `Recipe` document for the selected owned run, showing authored identity, resolved launch template and values, composition, policy, mailbox, and artifacts without following mutable external recipe paths. `Messages` and `Turns` remain adjacent tabs; Turns use one scrollable detail level without duplicated recipe context, and documents/timelines/details support arrows plus PageUp/PageDown. Nested values render as compact indented text with label-first, separator-aware wrapping and consistent lowercase hints. Recipe documents retain ↑-at-top/← navigation to tabs, and ← now also returns a scrolled Messages or Turns list directly to its tabs without resetting the selected row. Turns retain one cached evidence snapshot while list/detail navigation remains active, eliminating repeated full session-file parsing on every arrow key while preserving periodic refresh when focus returns to higher-level controls.
- `Pre-release Surface Compression`: Automatic-review persistence remains intentionally unversioned until a public compatibility boundary exists; transitional UUID-ledger and filename-sidecar migrations are removed. Canonical recipe names own lineage identity, hashes own content/CAS identity, revisions describe executable history, and operation-local UIDs remain confined to fencing and correlation.
- `Automatic Draft Evolution`: Twelve eligible inline-spawn drafts trigger one silent no-tools review of a value-free structural projection after the foreground turn and active actors finish; canonical names, draft basenames, raw hashes, recipe bodies, template/default values, authored prose, and filesystem paths remain in the separate trusted capture; batch-local opaque occurrence IDs and equality-only content groups preserve decision correlation without cross-batch identity disclosure. Every captured draft receives one quota-free `promote` or `discard` decision without recipe content; the deterministic executor derives promotions from exact immutable sources, rejects incomplete, stale, unsafe, secret-bearing, temporary-path, duplicate, or colliding outcomes, atomically applies the batch, preserves newer drafts, and records bounded garbage-collection evidence. `register_tool draft=...` remains the preferred fenced single-draft override, while deliberate filesystem promotion stays valid and may defer a captured batch.
- `Automatic Tool Portfolio Evolution`: Thirty-six eligible non-sensitive active recipe revisions trigger a separate no-tools review of the same value-free structural projection; `PI_ACTORS_AUTOMATIC_REVIEW=off` explicitly disables reviewer scheduling and safe-boundary activation, with the effective policy visible in runtime status. Usage, adaptability, duplication, safety, contract quality, and likely future value inform quota-free `keep`, unchanged-source rename (`evolve`), unchanged-source `demote`, or identical-source `merge` decisions; reviewers cannot return recipe content, while `replace`, `split`, and executable contract changes require explicit operator authoring. Mechanically validated immutable approval plans remain non-mutating until the next safe `session_start` activation boundary.
- `Deterministic Transactions And Recovery`: Draft and portfolio mutations use exact source/target CAS, authenticated plan-derived operation graphs, root identity and symlink/path containment, intent-before-mutation journals, source quarantine, complete recipe validation, and idempotent rollback/roll-forward recovery. Cross-session admission and activation serialize through canonical state locks; launch accounting shares the portfolio mutation fence so quarantine cannot lose usage evidence, while already-stale loaded sources reject and request reload. Malformed/missing reviewer state and processing failures stop after bounded retries, and hard crashes at every transaction/lineage transition converge without overwriting concurrent edits.
- `Recipe Lineage, Revisions, And Rollback`: Canonical name-and-priority ledgers preserve lifetime usage, launch-kind counters, former names/paths, review epochs, and transition history across rename, revision, promotion, demotion, merge, and split; replacement starts new meaning. Revision-local counters restart on executable fingerprint changes, unchanged automatic demotions remain in cooldown, and evolve/replace retain a bounded 32-slot snapshot ring. The internal rollback recovery primitive now journals exact recipe and lineage writes before mutation, CAS-validates both, and rolls post-write failures forward idempotently without resetting lifetime usage; 0.42 does not expose a public operator rollback action.
- `Review Diagnostics And Recovery`: `inspect target=recipes view=reviews` exposes bounded read-only draft/tool phases, action counts, garbage collection, lineage/revision usage, demotion and rollback provenance, transaction state, retained snapshots, and actionable failed stage/error/next-action evidence without starting reviewers or generating foreground turns. Explicit `review.retry` and safe `review.reset` messages to `tool:pi-actors` recover bounded failures while preserving approved transaction/lineage evidence that must roll forward. Draft retry with an existing journal resumes the original reviewer run and authenticated transaction decisions, preventing later reviewer output from splitting committed recipes and lineage.
- `Generation-fenced Run Control`: Every async start receives an immutable run generation. Inspector `k kill`, parent-session teardown, cancellation, and replacement-sensitive controls compare exact owner/generation inside the canonical lifecycle lock before signaling; stale, terminal, ambiguous, unsupported-proof, or replacement runs fail closed. Session shutdown discovers all readable exact-owner running actors, continues across partial failures, and persists a bounded survivor summary while descendant Pi sessions remain separately owned.
- `Lock, Watcher, And Signal Safety`: Canonical-path mutation locks use token-owned reclaim/release boundaries with deterministic sibling-process contention and dead-owner recovery, preventing stale owners or concurrent reclaimers from deleting replacement locks. Recipe watchers fence callbacks to their exact generation, and process control revalidates stable identity immediately before group signaling and after `ESRCH`; the remaining host-level PID/PGID reuse window and native Windows NTFS junction verification remain explicit platform boundaries.
- `Composition Root Compression`: Reduced `index.ts` from 389 to 118 lines by moving automatic-review scheduler/launch/control wiring, ambient run watcher/reconciliation/teardown lifecycle, and Inspector command adaptation into focused domains. The entrypoint now retains host event registration, dependency wiring, tool wrapping, and session context while low-level actor/review operations remain behind named runtime contracts.
- `Selective Recipe Installation`: Replaced bulk library-copy guidance with explicit selected-recipe or thin-wrapper installation. Internal `draft-review.json` and `tool-review.json` selectors remain runtime-owned components rather than user-installed callable tools.
- `Validation`: Primary CI release validation now includes protocol conformance, high-severity dependency audit, strict source Domain DAG, an exact temporary-index diff/secret/public-path hygiene pass, and ABCd root/routing/link checks; the local peer test lock advances Pi from `0.75.3` to `0.80.10`, clearing the prior audit findings. Passed 631 tests, 171 conformance tests, 63 packaged-recipe QA checks, a clean `npm audit`, TypeScript, extension import, package build/dry-run for `0.42.0`, and the reproducible supplemental release gates.

## 0.41.1: Actor Inspector and Delivery Hotfix

- `Terminal Delivery`: Added bounded ten-second terminal reconciliation and watcher rearm so owned terminal follow-ups converge without reload when file watching misses or fails. Delivery still uses Pi follow-ups with owner filtering, `triggerTurn`, no historical outbox replay, and the existing at-least-once handled-marker contract; routine run-directory removal stays quiet while real watcher degradation remains diagnostic.
- `Actor Inspector`: Finished the 0.41 overlay line around a compact meaning-first workflow. `/actors-inspector` now opens the latest numbered Run; Run, Message, and Turn lists show newest evidence first; bounded menus remain usable on short terminals; and humanized Turn rows lead into wrapped Evidence and a metadata-free readable transcript. Turn content now prioritizes User, Thinking, Assistant, and tool actions before Execution and Provenance, strips prompt transport wrappers in readable mode, keeps logical sections on one stripe, and removes false wraps, clipped values, redundant labels/separators, and blank rows.
- `Tool Output`: Normalized successful results and errors to contribute exactly one leading line break, preserving one empty separator row beneath Pi's rendered tool-call header without occasional double gaps.
- `Agent Guidance`: Kept Inspector behavior in user documentation and removed it from the bundled Actors skill, leaving that skill focused on agent-operational `spawn`, `message`, `inspect`, recipes, and lifecycle guidance.

## 0.41.0: Actor Inspector Overlay and Execution Observability

- `[Inspector Menu Alignment]` Shifted value submenus one cell left so adjacent levels share a border, aligned Run and tab labels to one vertical grid, and made the Run dropdown begin immediately below Run by overlaying the tab row. Impact: nested menus read as one connected hierarchy and every top-level control follows the same anchored dropdown rhythm.
- `[Inspector UX Polish]` Applied the shared focus treatment (`▶`, accent text, neutral background) to timeline rows, exposed non-default filters as compact tab-label suffixes, gave run lifecycle status semantic text color, and split true-empty from filtered-empty guidance. Impact: focus no longer changes visual language between controls and data, hidden filter state stays visible, and empty results explain whether data or the current query is absent.
- `[Inspector Detail Navigation]` Made Enter/→ open a focused timeline row and Escape/← return from detail; horizontal arrows no longer switch tabs from list focus. Updated contextual footer hints accordingly. Impact: nested list/detail navigation follows the same forward/backward key model as menus, while tab switching remains scoped to tab focus.
- `[Inspector Message Sender Filter]` Added `From: <actor>` to the Messages filter menu, populated from the selected run's roster, with `all` as the default. Impact: operators can isolate communication emitted by one actor while seeing the current sender scope before opening its values.
- `[Inspector Nested Menu Context]` Added current values to parent filter items (`Channel: value`, `State: value`, `Subagent: value`) and made unused corners between differently sized parent/value menus transparent to the striped timeline beneath. Impact: operators see filter state before opening alternatives, and nested overlays occlude only useful menu cells.
- `[Inspector Run And Filter Menus]` Added a top-level owned-run selector with live status, removed run metadata from timeline rows, and moved filters behind Enter on each tab. Filter parameters now open a second value submenu to the right while preserving the parent menu and one-level Escape navigation. Impact: run context stays explicit, the permanent filter row disappears, and Messages/Turns gain compact graphical two-level settings menus.
- `[Inspector Selection Markers]` Use stable blue brackets for selected Run/tab controls and reserve `▶` for focused menus, values, and timeline rows. Added a direct regression that verifies even timeline rows stay on the dark overlay surface while odd rows receive the neutral stripe background. Impact: selection and focus remain distinct without layout shifts or color-only meaning.
- `[Inspector List Navigation]` Restored stable even/odd striping by absolute timeline position, made Enter/→ open row detail, and made Escape/← return to the list, with contextual footer hints. Impact: row grouping remains visually stable while scrolling and horizontal navigation follows the same forward/back model as nested menus.
- `[Inspector Visual Contract]` Stabilized the dogfooded interaction model around top-bounded tabs, availability-aware filter/list navigation, blue current values, neutral focus backgrounds, key-colored footer hints, and filter-anchored nested option overlays that preserve underlying separator and timeline cells outside their rectangle. Impact: the TUI now behaves like a compact graphical tab/filter/select surface instead of a command panel.
- `[Inspector Naming]` Renamed the `Communications` tab to `Messages`. Impact: the tab now describes its concrete contents with a shorter label that balances visually with `Turns`.
- `[Inspector Filter UI]` Removed the permanent filter bar in favor of compact tab-anchored parameter/value menus that show current values, preserve the striped timeline beneath unused cells, and expose active non-default filters in the tab label. Impact: filtering stays visible and keyboard-driven without consuming a permanent content row.
- `[Inspector Turns UI]` Moved turn browsing and detail into the overlay with scrolling viewports, all/single-subagent scope, compact model/tool-count rows, and Enter-opened bounded provenance, prompt/context, user/assistant, persisted-thinking, usage/error, tool argument/result, truncation, and diagnostic evidence. Impact: operators can follow one subagent's complete persisted execution path without commands or leaving the overlay.
- `[Inspector Messages UI]` Moved message browsing into the overlay with compact striped routes/types/body previews, attention markers, unread/channel/sender filters, roster-derived From options, and bounded detail. Impact: actor communication investigation stays keyboard-driven and discoverable without consuming a row for unread dots or command grammar.
- `[Inspector Focus Navigation]` Added explicit Run/Tabs/Menu/List/Detail focus zones with availability-aware boundaries, blue selected values, brackets for top-level selection, triangles for focused rows, and contextual key hints. Impact: navigation always has one visible owner and moving focus never mutates filter state.
- `[Inspector Overlay Integrity]` Normalized persisted tabs and line breaks before every component row is handed to the overlay compositor. Impact: multiline actor messages, prompts, and turn text can no longer escape their assigned row and corrupt the underlying terminal layout during tab navigation.
- `[Inspector Overlay]` Replaced inspector subcommand handling with `/actors-inspector-toggle`, which opens a centered responsive overlay featuring Run selection, Messages/Turns tabs, nested filters, compact alternating rows, live refresh, distinct empty states, bounded detail, footer key hints, and Escape close. Removed the superseded command controller and below-editor widget lifecycle. Impact: operators can browse execution evidence without memorizing command grammar, and runtime state now has one authoritative UI path.
- `[Inspector Security]` Reset inspector selection/read state at every Pi session start, revalidate selected-run ownership before turn or roster reads, reject absolute/traversing/symlinked session evidence outside the owned run, and broaden structured/text plus communication-body redaction for common camelCase/private-key credentials. Impact: the upcoming overlay cannot inherit another session's selected evidence or escape its run boundary through mutable manifests.
- `[Coordinator Turn Provenance]` Replaced coordinator-managed room/swarm subagents' `--no-session` launches with isolated role/phase session directories under the owned run and made the inspector discover those JSONL files alongside command evidence. Impact: manual turn navigation covers coordinator-spawned participants and synthesis actors, not only direct recipe `pi -p` leaves.
- `[Inspector Turn Detail]` Added bounded manual turn detail for command/stage identity, session and prompt provenance, recipe context, user/assistant text, persisted thinking, stop reason, usage, errors, correlated tool arguments/results, unmatched results, truncation, and parse diagnostics. Impact: operators can inspect what each subagent actually received, produced, and called while missing reasoning stays explicitly unavailable and secret-bearing values remain redacted.
- `[Turn Evidence]` Added a resilient bounded reader for persisted child Pi sessions that follows the latest JSONL entry branch, groups assistant responses with correlated tool calls/results, retains model/usage/error and host-visible thinking metadata, redacts common secret-bearing fields/text, and diagnoses malformed or incomplete evidence. Impact: inspector navigation can consume one tested turn model instead of parsing raw session files or implying access to unavailable reasoning.
- `[Execution Observability]` Give every child `pi -p` command an isolated session directory under its owned run state unless the recipe already supplies explicit session policy, and record any resulting JSONL files in command events and review evidence. Impact: the inspector can attribute future turn/tool timelines to exact subagent commands without guessing from global session directories, while `--no-session`, resume, fork, and caller-owned session storage remain authoritative.
- `[Tool Output]` Separate every pi-actors tool result and thrown error from its rendered tool-call header with one blank line, including core `spawn`, `message`, `inspect`, `register_tool`, and recipe-backed tools. Impact: successful and failed calls remain visually scannable instead of running into the header.

## 0.40.1: Follow-up Delivery Hotfix

- `[Coordinator Delivery]` Queue terminal and coordinator-bound actor notifications through Pi's `followUp` delivery mode instead of `steer`, while retaining `triggerTurn: true` for idle sessions. Impact: active coordinators finish their current work before actor results arrive, and Pi can apply its configured follow-up batching policy to concurrently completed runs instead of injecting each result between tool calls.
- `[Agent Autonomy]` Clarified in the injected prompt and bundled Actors skill that command-template strings execute directly without shell evaluation, so `&&`, pipes, redirects, and `cd` do not provide shell composition. Strengthened both skill descriptions and added explicit Swarm activation for multiple parallel actors, independent artifact generation, implementation fanout, and review; the coordinator now receives a compact preflight contract for disjoint scopes, stable run ids, artifacts, launch correctness, integration, and final validation. Impact: agents avoid malformed launches such as `cd <dir> && pi ...` and autonomously load the right orchestration guidance before multi-actor work.
- `[CI Stability]` Wait for the detached runner process to exit before removing the large-review-evidence fixture directory, and wait for the terminal evidence manifest instead of racing its final write. Impact: Linux CI cleanup no longer intermittently fails with `ENOTEMPTY` after the assertions pass.

## 0.40.0: Durable Review and Runtime Hardening

- `[Runtime]` Collapsed every natural-language positional fragment in child `pi -p` launches into one inspectable prompt file while preserving Pi options and intentional `@file` attachments, so review stages receive one authoritative user turn and preflight diagnostics resolve the concrete stage.
- `[Tests]` Made the packaged review-readiness dogfood fake Pi reject fragmented prompt argv, covering preflight, reviewer, verifier, merger, judge, and normalizer transport through the real detached runner.
- `[Reviews]` Added opt-in `accept_output: review_evidence` semantics and marked packaged reviewer, verifier, merger, judge, and normalizer outputs with `ACTOR_REVIEW_RESULT`, so code-zero format acknowledgements or input requests fail closed instead of satisfying quorum or reaching later stages.
- `[Diagnostics]` Preserved rejected parallel stdout alongside its semantic rejection reason, allowing degraded review runs to retain accepted and rejected branch evidence without counting placeholders as usable.
- `[Breaking]` Removed public `spawn.state_dir` overrides and reject direct attempts with a retention-safety diagnostic, keeping every public `run:<id>` actor under the runtime-owned addressable run root.
- `[Safety]` Added canonical run-state ownership markers and require them before launch reuse, archive, or prune; existing non-run directories, forged metadata, mismatched run ids, and symlink aliases now fail closed before destructive retention.
- `[Safety]` Added and persisted Linux, macOS, and Windows process-identity proofs with start-time, command, and available cwd evidence; status, state reuse, message delivery, cancellation, kill, and retirement now distinguish dead pids, owner mismatches, unsupported proofs, and valid ownership instead of degrading to liveness alone.
- `[Execution]` Bounded stdout and stderr tails while child commands are running, spilling complete high-volume streams independently with total byte counts, truncation flags, and diagnostic file paths instead of accumulating unbounded strings in memory.
- `[Execution]` Propagated capture metadata through foreground results, retries, parallel branch diagnostics, and async run events; sequence and parallel pipelines now fail closed with `incomplete pipeline stdin` instead of feeding truncated tails downstream.
- `[Registry]` Added cross-process file mutation locks keyed by canonical recipe path and wrapped register, update, delete, and draft-promotion windows; concurrent same-name registrations now have one explicit winner.
- `[Registry]` Moved user-recipe usage telemetry into locked `.usage/<recipe-filename>.json` sidecars and merge it during discovery, so sibling-process counters remain monotonic while external recipe edits and file-watcher refreshes cannot be overwritten by metadata writes.
- `[Routing]` Made `message to=tool:<name>` and `inspect tool:<name>` resolve definitions only when the current runtime recipe registry still marks the tool active; deleted/external-removed recipes are revoked immediately and updates route only to the newest extension-local definition despite host-level unregister limitations.
- `[Retention]` Made pruned artifact preservation collision-safe with readable artifact-name/hash/basename targets and timestamp preservation; duplicate basenames remain distinct, missing optional artifacts stay skipped, and any copy failure aborts before source run state is deleted.
- `[Registry]` Rearmed recipe live reload through an advisory parent watcher when `~/.pi/agent/recipes` is absent or renamed, switching back to the root watcher on creation and reloading on deletion; first-run creation, recreation, and idempotent shutdown now work without polling or session restart.
- `[Backlog]` Rewrote the remaining packaged hardening review milestone as ordered open-checkbox tasks with decision-grade evidence, finding classification, reconciliation, and validation exit criteria.
- `[Review]` Completed the six-lens packaged hardening pipeline above quorum. The normalized verdict was blocked by a reproduced UTF-8 capture defect; other reported concerns remained hypotheses because raw stage outputs were not retained for independent audit. Re-curated the backlog around durable per-stage review evidence before the next release-readiness run.
- `[Execution]` Preserved raw command bytes across stream chunk boundaries and aligned bounded tails to UTF-8 code-point boundaries, preventing split multibyte output from becoming replacement characters while keeping complete spill files byte-exact.
- `[Actors]` Added an async-patience invariant to the runtime prompt, project context, and bundled actors skill: when deferred actor output gates the next step, wait for the terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the reviewed scope.
- `[Backlog]` Decomposed durable review provenance into nine ordered open tasks covering byte-exact stage output, evidence manifests, bounded inspection, report references, regression proof, re-review, finding classification, and final context validation.
- `[Evidence]` Persisted complete stdout and stderr for every async command, including small streams, under collision-safe `captures/command-NNN/attempt-NNN/{stdout,stderr}.log` identities; retries remain distinct while bounded result tails and complete pipeline stdin behavior stay unchanged.
- `[Evidence]` Added terminal `review-evidence.json` manifests mapping stable command/stage occurrences and repeated branches to prompts, byte-exact attempt files, byte counts, truncation, exit state, semantic marker acceptance, recipe context, and inherited/explicit model policy; manifests update during execution and finish with aligned `done`/`failed` status.
- `[Inspector]` Exposed owned review-evidence manifests and referenced capture paths through existing `inspect run:<id> view=files|artifacts` responses, bounding command entries by `lines` and reporting total/truncated counts without adding a public verb or bypassing session ownership checks.
- `[Review Evidence]` Injected stable prior-stage `ACTOR_EVIDENCE_REF` entries into verifier, merger, judge, and normalizer prompts; normalized reports now retain auditable reviewer/downstream references, terminal manifests record cited and missing sources, and a report claiming `complete` fails closed when any required reviewer, verifier, merger, or judge reference is absent.
- `[Review Dogfood]` Expanded deterministic provenance coverage across small, spilled, UTF-8, retry, parallel, semantic-marker rejection, partial-quorum, and terminal paths; the packaged review fixture now reconstructs reviewer branch identity, accepted/rejected counts, rejected raw output, downstream source references, final degraded status, and exactly-once capture files solely from retained run state.
- `[Review]` Completed the auditable six-lens `hardening-review-040` run with all 14 stages accepted and every required evidence reference retained. Re-curated confirmed release blockers covering canonical alias locks, live owner-mismatch reuse, symlink-cwd identity, public custom state directories, complete large-pipeline stdin, exact evidence markers, semantic notification alignment, interrupted evidence finalization, and missed terminal replay; kept the cancellation timing race and native platform gaps explicitly unconfirmed.
- `[Locking]` Keyed mutation locks by filesystem identity: existing targets or nearest existing ancestors are resolved through native `realpath`, nonexistent suffixes are preserved, Windows identities are case-normalized, and stale lock directories are reclaimed only after their persisted owner PID is proven dead. Added a cross-process real-parent/symlink-parent serialization regression.
- `[Run Safety]` Made live `owner_mismatch` state reuse fail closed in both preflight and state-directory preparation, including terminal-result timing windows; tampered process identity can no longer clear/reuse an occupied run directory while its original runner remains alive.
- `[Process Identity]` Canonicalized existing launch cwd paths through native `realpath` before matching the runner's process proof, with Windows case normalization; Linux integration now proves a symlinked launch cwd retains a valid, controllable process identity while injected Darwin/Windows contracts remain intact.
- `[Public Boundary]` Removed lifecycle `state_dir` from `register_tool`, persisted/co-located recipe normalization, generated schemas, result details, serialization, recipe-reference resolution, and prompt copy. Legacy stored values are ignored, and registered async tools now always launch under the runtime-owned run root where `run:<id>` inspection, messaging, indexing, and retention agree.
- `[Pipeline Dataflow]` Downstream sequence commands now receive complete spilled stdout from sequential and parallel producers while model-facing output, branch reports, and diagnostics remain bounded. Missing or unreadable spill files still fail closed; exact >1 MiB consumer-count regressions cover both composition shapes.
- `[Review Evidence]` Tightened semantic acceptance to require `ACTOR_REVIEW_RESULT` as the exact first non-whitespace line in both execution policy and persisted evidence manifests; prefixed markers such as `ACTOR_REVIEW_RESULT_BOGUS` now fail with code 65 and remain rejected evidence.
- `[Review Notifications]` Applied semantic output acceptance before async command accounting, so rejected code-zero review output is consistently recorded as code 65 in `command.done`, terminal progress failures, evidence, and outbox summaries, with follow-up delivery and error severity instead of a false success notification.
- `[Interrupted Evidence]` Review evidence records now exist before command launch and are finalized as `cancelled` or `killed` by lifecycle control even when the command never returns. Async captures create byte-exact stdout/stderr files at attempt start, preserving small partial streams as well as spills; manifests retain interruption status, signal-derived effective exit code, capture bytes, and semantic interruption state.
- `[Terminal Delivery]` Terminal actor notifications now use Pi steering with `triggerTurn: true`: busy agents receive completion at the next safe tool boundary and idle agents start a normal turn without a racy manual idle check. Unhandled owned terminal runs retry during same-runtime and replacement reconciliation until `terminal-handled.json` is written after a successful send, without replaying historical outbox traffic. Delivery is honestly at-least-once: a process crash between send and marker persistence may duplicate a notification.
- `[Cancel Race]` Authoritative terminal result/control state now short-circuits cancel/kill before process-identity probing because no signal will be sent. This removes transient `unsupported proof` classifications while preserving fail-closed identity checks for running processes and derived `exited` states; a 30-run completion/cancel stress regression consistently returns `not running`.
- `[Release Review]` Completed the final six-lens hardening review with all branches and downstream stages successful and durable evidence under `hardening-review-040-final`. The review blocked release on five bounded correctness findings: large marked-output acceptance, cross-process registry collision state, live aged start locks, same-runtime terminal-delivery retry, and disappearing-run inspection tolerance. Per operator direction, no further reviewer runs are required before release; fixes use local regressions and validation.
- `[Large Review Output]` Semantic marker acceptance now reads byte-complete captured stdout when the bounded tail is truncated, while returned model-facing output remains bounded. Foreground and async regressions prove valid `ACTOR_REVIEW_RESULT` output above 1 MiB succeeds and persists accepted evidence metadata.
- `[Registry Collision]` Same-name registration now rereads authoritative recipe state while holding the canonical cross-process mutation lock instead of trusting a process-local tool map. A sibling-process regression proves exactly one create wins and the loser receives the explicit `update=true` collision error without overwriting the recipe.
- `[Start Lock Ownership]` Run-start locks now persist the starter's process identity and aged locks are reclaimed only when the recorded PID is proven dead. Live, mismatched, unavailable, and malformed ownership proofs remain protected regardless of age; regressions cover both live-owner retention and dead-owner recovery.
- `[Inspection TOCTOU]` Runtime triage now treats a run that disappears between inventory and status read as a skipped stale entry instead of failing the entire inspection. Injectable inventory/status ports provide a deterministic disappearance regression without weakening ownership filtering for surviving runs.
- `[Package Entrypoint]` Added a named compiled wrapper at `dist/pi-actors/index.js` and pointed package metadata to it, preserving the compiled runtime while making Pi's extension list identify `pi-actors` instead of the anonymous parent label `dist`.
- `[Release]` Updated package, lockfile, bundled skill metadata, compiled assets, and changelog identity for the release candidate; validation, conformance, package dry-run, diff checks, and context reconciliation are green.

## 0.39.0: Actor Kernel Welcome Refresh

- `[Docs]` Reworked the root README as a product/onboarding entrypoint for the local actor kernel, with clearer positioning, first-run path, feature showcase, recipe-memory model, address/message examples, and practical surface-selection guidance. Impact: new operators can understand when to use `spawn`, `message`, `inspect`, recipes, rooms, and artifacts without reading deep implementation docs first.
- `[Context]` Added a durable README standard to `AGENTS.md` so future edits preserve the RhythmE/product entrypoint shape while keeping the practical capability catalogue visible.
- `[Release]` Bumped package metadata to `0.39.0` for the onboarding refresh minor release.

## 0.38.1: Windows Recipe ACL Hotfix

- `[Registry]` Replaced POSIX mode-bit recipe-root writability checks on Windows with ACL-aware diagnostics, avoiding false `world-writable` and `group-writable` startup warnings from Node's NTFS mode emulation while still flagging broad Windows write grants.
- `[Tests]` Added portable coverage for broad Windows ACL parsing and skipped the POSIX chmod diagnostic regression on Windows.

## 0.38.0: Review Swarm Pipeline Hardening

- `[Recipes]` Added current model/thinking inheritance for packaged review/lens-swarm recipes through `{current_model}` and `{current_thinking}`, so normal subagent review swarms use the selected Pi session policy by default while explicit args still override it.
- `[Runtime]` Injected the current Pi model and thinking level into spawn/runtime tool recipe values and fail fast before async fanout when a current placeholder cannot be resolved.
- `[Runtime]` Persisted `model_policy` provenance in async run status, progress, terminal results, compact status text, and terminal follow-ups so operators can distinguish inherited, explicit, mixed, and unresolved model/thinking policy.
- `[Runtime]` Materialized child `pi -p` prompts into run-local `prompts/command-NNN.md` files and invoked Pi with `@file` arguments, preserving long quoted prompts and recipe context without fragile inline argv transport.
- `[Runtime]` Expanded parallel branch diagnostics with stdout/stderr byte counts, tail previews, failure reasons, prompt-file paths, soft-quorum usability, and failed-run result/progress details; branch-failure fanouts now fail when every branch fails or emits empty output.
- `[Recipes]` Added `subagent-preflight` and wired the review coordinator to run stage model/thinking/tool smoke checks before reviewer fanout, so unavailable providers fail before expensive reviewer branches launch.
- `[Recipes]` Made review pipelines quorum-aware with `subagent_ttl_ms`, `reviewer_concurrency`, `min_successful_reviewers`, and `merge_policy` knobs; partial reviewer evidence is preserved, verifier/merger stages run only after the evidence threshold is met, and normalized reports must mark `complete`, `degraded`, or `insufficient_data`.
- `[Diagnostics]` Preflight command failures now emit `ACTOR_PREFLIGHT_FAILED` diagnostics with stage, selected model/thinking, provider error class, prompt file, and suggested override args; fake-`pi` coverage proves reviewer fanout starts only after preflight passes.
- `[Tests]` Added a deterministic packaged review-readiness dogfood fixture to `npm run conformance`, using a fake local `pi` executable to verify preflight, degraded reviewer fanout, prompt-file artifacts, branch failure capture, merge gating, and terminal status without external model APIs.
- `[Guidance]` Updated README, actor/swarm skills, recipe docs, async-run docs, and onboarding copy to steer review swarms away from `models.json` rediscovery and toward maintained recipes with current model/thinking inheritance, policy provenance, prompt-file transport, preflight, quorum controls, and inspectable branch diagnostics.
- `[Backlog]` Captured the remaining `pi-telegram` review-swarm dogfood lessons as concrete `pi-actors` hardening work: review-pipeline preflight/quorum resilience, model-provenance visibility, and a deterministic review-swarm fixture.

## 0.37.1: Subagent Recipe Prompt Injection Hotfix

- `[Recipes]` Fixed actor recipe context injection for child `pi -p` launches with options after the print flag, so packaged subagent recipes such as `subagent-review` and `pipeline-review-readiness` append context to the actual prompt instead of corrupting `--model` or other option values.
- `[Guidance]` Tightened onboarding, actor-skill, and recipe-library guidance so agents prefer maintained packaged review recipes via `spawn file=<recipe>` before rebuilding script commands or creating unnecessary wrappers.

## 0.37.0: Direct Recipe Delegation And Quiet Overrides

- `[Recipes]` Added direct recipe delegation from `template` strings so thin wrappers can point at ready recipe names/paths while preserving priority resolution, inherited metadata, and import-based composition for richer graphs.
- `[Command Templates]` Fixed inherited/default placeholder resolution for arrays and repeat-indexed values, unblocking lens-swarm recipes that pass `lenses` through wrapper defaults into `{lenses.length}` and `{lenses[index]}`.
- `[Registry]` Stopped treating same-name recipe/tool registration as a startup warning: higher-priority user recipes now quietly override lower-priority recipe/tool definitions as normal composition behavior, while reserved core tool names remain protected.

## 0.36.0: Recipe Diagnostics And Runtime Triage

- `[Recipe Doctor]` Added deterministic advisory risk labels for discovered recipes, including shell, eval, filesystem mutation, network, external side effect, long-running, platform-specific, and secret-touching signals in verbose recipe inspection plus compact doctor risk counts.
- `[Runtime]` Added `inspect target=tool:pi-actors view=triage` as a compact read-only operator attention surface covering runtime mode, active and other-session runs, invalid or blocking recipes, exposed tool recipes with non-lifecycle risk labels, drafts, stale claims, failed runs, attention messages, and next inspect actions.
- `[Recipes]` Added packaged recipe QA through `validate-recipe.mjs --qa` and `npm run recipes:qa`, with exact diagnostics for async mailbox contracts, termination vocabulary, artifact paths, platform scope, installed-package-safe helper paths, and missing helper scripts.
- `[Runtime]` Hardened wake/watch chaos behavior with deterministic coverage for watcher restarts, partial wake records before file catch-up, corrupt wake JSONL with later valid records, missing wake records with durable inbox work, and killed runs with stale progress state.
- `[Docs]` Documented recipe-doctor risk labels, runtime triage, packaged recipe QA, and import-first ready-recipe registration as operator review aids and source-of-truth preservation, not sandbox, repair, or security-boundary claims.

## 0.35.0: Draft Recipe Promotion UX

- `[Recipes]` Added draft recipe promotion UX: `inspect target=recipes view=summary verbose=true` now exposes draft timestamps, fingerprints, validation state, source run when known, and template previews, while `register_tool name=<tool> draft=<path>` promotes a validated draft into active recipe memory without deleting the draft and rejects collisions unless `update=true` is explicit.

## 0.34.1: Message Delivery Outcome Hotfix

- `[Dogfood]` Added a deterministic actor-worker stale-claim smoke covering an intentionally claimed branch inbox record; the worker now reports stale claim counts in both `worker-status.json` and its awaiting-assignment room event without adding auto-recovery or scheduler policy.
- `[Messages]` Normalized public message results with `delivered`, `persisted`, `queued`, `forwarded`, `consumer`, and `reason` fields across run, branch, room, coordinator, session, and tool destinations; room multicast now also exposes per-recipient branch delivery outcomes.
- `[Backlog]` Closed the worker stale-claim dogfood and message delivery outcome work after adding delivery-result coverage for run, branch, room, coordinator, session, tool, and ownership-denied paths.

## 0.34.0: Actor Kernel Domain Compression

- `[Domains]` Compressed the actor kernel into explicit domain families: `tools.ts` remains the public tool-family owner while `tools-*` owns message, inspect, spawn, register, local execution, response, access, and mailbox-contract behavior; `async-runs.ts` remains the lifecycle facade while `runs-*` owns artifacts, mailbox, process control, delivery, outbox, index, retention, status, start guards, and identity internals.
- `[Domains]` Removed redundant internal `actor-` prefixes and renamed the recipe family to plural `recipes-*`, leaving public actor-named recipe/script/docs surfaces intact while making core library ownership match the `tools-*` and `runs-*` convention.
- `[Scripts]` Collapsed script-only runner, worker, validator, recipe-utils, locker, and coordinator library shims back into their owning `scripts/*.mjs` entrypoints; reusable lifecycle, room, mailbox-loop, command-template, and recipe-reference primitives remain in `lib/`.
- `[Context]` Reversed the thin-script default, polished ownership headers, and kept completed script-autonomy/domain-compression work in the changelog instead of the backlog.
- `[Tests]` Mirrored renamed domains in test filenames and extended installed-package contract coverage to ensure stale renamed lib domains are absent from `dist/lib` while packaged JS-only script execution still works.

## 0.33.0: Signal-First Compatibility Pruning

- `[Breaking]` Removed pre-1.x compatibility shims for draft recipe terminology: draft captures now live under `~/.pi/agent/recipes/drafts`, recipe inspection no longer emits `candidates`, spawn details no longer emit `candidate_recipe`, and shadow diagnostics use `blocked_fallback` instead of `blocked_candidate`.
- `[Context]` Documented the pre-stable policy that context compression wins over compatibility aliases until after a stable release greater than `1.x.x`; rename slices should remove legacy actor-facing names, fields, env vars, paths, and docs instead of carrying shims.
- `[Breaking]` Renamed retained registry storage from `legacy-tool-registry.json` to `tool-registry.json`, removing the stale compatibility noun from runtime path helpers and tests.
- `[Types]` Added a narrow actor tool-definition type and removed the remaining `Map<string, any>` from the composition root without expanding SDK type exposure.
- `[Scripts]` Collapsed the conformance runner back into a standalone script and removed its one-off lib domain, documenting that script-only glue should stay self-contained unless reuse or packaged runtime constraints justify a domain.

## 0.32.0: Actor Surface Minimization

- `[Context]` Added durable signal/noise guidance for actor-facing surfaces: keep the model-facing concept ladder minimal, make feedback hints state-backed and action-shaped, and avoid speculative advisory prose.
- `[Backlog]` Added critical concept-surface compression and actor feedback-loop strengthening tracks to guide the next minimization-focused development cycle.
- `[Concepts]` Compressed model-facing language by presenting captured inline-spawn recipes as drafts, treating `room:<run>` as advanced group messaging plus roster, demoting coordinator/session/debug views from golden-path guidance, and keeping compatibility names/paths as storage details rather than core onboarding nouns.
- `[Feedback]` Added bounded next-action hints to recipe registry/doctor inspection, artifact inspection, delivery-fallback message results, and terminal run follow-ups so state-backed surfaces point back to `inspect`, `message`, `spawn`, or draft promotion without polling or auto-repair.
- `[Sessions]` Normalized session-directed message ownership failures onto the same structured `reason=session_mismatch`, owner/current session, and inspect-session hint shape used by run, branch, room, and coordinator ownership denials.

## 0.31.0: Agent Adoption Ergonomics

- `[Adoption]` Added a compact actor-mode trigger rule to the injected prompt, actors skill, README, and async-run docs so models prefer `spawn → message → inspect` for long-lived, stateful, follow-up, artifact, service, fanout, and resumable work while keeping short foreground checks as ordinary tools.
- `[Skills]` Reframed the bundled actors skill as required practical guidance for non-trivial actor use or pi-actors changes, and made the injected prompt route agents to it before improvising actor workflows.
- `[Tools]` Strengthened `spawn`, `message`, and `inspect` descriptions with adoption cues that steer models away from ad hoc shell backgrounding, actor restarts, and polling loops.
- `[Spawn]` Added explicit next-action feedback to spawn results so newly created actors immediately suggest inspect/message chains instead of leaving agents to infer the next step.
- `[Docs]` Added a task-first “when to use actors” golden path to the README without adding public verbs or scheduler/service-manager concepts.

## 0.30.2: Music Player Kill Hotfix

- `[Music Player]` Kept backend player processes inside the async run process group so `control.kill` can terminate an active music-player run without leaving detached `cvlc`/player children alive.
- `[Docs]` Updated durable project guidance, actor skill guidance, async-run ownership docs, and recipe-library music-player notes to preserve the run-owned process-tree invariant while still allowing true daemon recipes through explicit termination bridges.

## 0.30.1: Backlog Curation Hotfix

- `[Backlog]` Added curation rules clarifying that completed work belongs only in the changelog, that cohesive ~1000-line domain files are acceptable, and that file splitting should follow real ownership boundaries rather than line count alone.
- `[Backlog]` Added small cleanup candidates for typed tool-boundary tightening and retained registry-path naming clarity without expanding the public actor surface.

## 0.30.0: Composition Root Compression

- `[Entrypoint]` Added a narrow Pi SDK adapter domain, moved recipe live-reload mechanics into the runtime domain, moved run-state watcher, run UI observation state, and run notification formatting into observability, moved runtime path constants and co-located skill path discovery to the paths domain, grouped core actor tool definitions in the tools domain, and shifted actor-inspector command state/parsing/render selection into the actor-inspector domain so `index.ts` keeps only live Pi wiring.
- `[Backlog]` Added focused next-minor candidates for message delivery outcomes, candidate recipe promotion, recipe risk labels, runtime triage, packaged recipe QA, and wake/watcher chaos fixtures while deferring broader golden-flow documentation until the core diagnostic surfaces settle.

## 0.29.3: Actor Skill Context Hotfix

- `[Skills]` Reconciled knowledge-surface layering across project and actor guidance, added a project topology map, moved multi-agent methodology from the actors runtime skill into the swarm skill, and split actor quick-start guidance from a deeper recipe/operating-pattern reference.

## 0.29.2: Legacy Migration Removal Hotfix

- `[Registry]` Removed the old legacy tool-registry migration path now that recipe-file storage is the only maintained persistence surface.

## 0.29.1: Subagent TTL Kill Hotfix

- `[Coordinator]` Added `subagent_ttl_ms` / `--subagent-ttl-ms` to the room-swarm adapter so timed-out subagent `pi -p` processes are terminated instead of only awaited.

## 0.29.0: Candidate Recipe Memory

- `[Spawn]` Capture inline spawn templates as non-registered candidate recipes under `~/.pi/agent/recipes/candidates`, making successful ad hoc actor patterns easy to replay by explicit path and promote manually.
- `[Inspect]` Add candidate recipe counts and verbose candidate metadata to recipe registry inspection without registering candidates as tools.
- `[Skills]` Documented the two-layer executable memory model: candidate recipes as a proving ground and root recipes as active tool memory.

## 0.28.1: Portable Agent Protocol Hotfix

- `[Docs]` Removed a machine-local private validation skill reference from the repository agent protocol so extension guidance stays portable.

## 0.28.0: Shadowed Recipe Launch Diagnostics

- `[Spawn]` Added minimal shadowed-recipe diagnostics when a bare recipe launch already fails because an invalid or disabled higher-priority recipe blocks a lower-priority fallback; healthy recipe overrides remain silent.
- `[Async Runs]` Treat disabled template recipes as non-launchable so disabled shadowing fails consistently instead of silently executing.
- `[Docs]` Clarified the quiet shadowing contract, disabled recipe launch behavior, and recipe-doctor hint path.
- `[Backlog]` Reframed shadowed recipe launch diagnostics as diagnostic-on-failure only, preserving shadowing as an intentional user override mechanism without startup warnings or automatic remediation.

## 0.27.1: Changelog and Backlog Hotfix

- `[Changelog]` Moved the 0.27.0 runtime/session observability notes out of `Unreleased` into a proper release section so published package history matches the npm/tag release.
- `[Backlog]` Marked runtime/session observability complete and added the next evidence-backed candidates for shadowed recipe launch UX, session mismatch follow-through, and worker stale-claim dogfood.

## 0.27.0: Runtime and Session Observability UX

- `[Inspect]` Added `inspect target=tool:pi-actors view=status` as a runtime verification surface with loaded version, package root, source/dist mode, entrypoint path, recipe roots, and git commit when available.
- `[Sessions]` Started structured session mismatch diagnostics with `reason=session_mismatch`, owner/current session fields, and compact inspect-session hints while preserving current ownership gates.
- `[Sessions]` Added other-session run counts to coordinator/session status summaries so reload/resume states do not misleadingly report only `runs=0` without nearby context.

## 0.26.3: Branch Message Delivery UX Hotfix

- `[Actor Messages]` Treat branch mailbox persistence as a successful queued outcome even when the parent run control endpoint is unavailable, returning compact `queued=true` delivery diagnostics instead of throwing an unframed tool error.
- `[UX]` Preserve the compact action-output contract for branch `message` calls by keeping delivery diagnostics in the normal result formatter, including the leading blank-line separation used by other tool actions.

## 0.26.2: Terminal Progress Hotfix

- `[Async Runs]` Keep `progress.json` aligned with terminal kill/cancel handling by writing `phase=killed` or `phase=cancelled` and clearing active subagent counts when a run is stopped by runtime control.
- `[Inspector]` Prevent killed runs from showing contradictory `status=killed` with `progress.phase=running`, preserving compact operator status trust after `control.kill`.

## 0.26.1: Coordinator Empty-Synthesis Hotfix

- `[Coordinator]` Treat all-failed participant rounds and empty synthesis as a failed coordinator run instead of a clean success, preserving operator trust when swarm branches all exit non-zero.
- `[Artifacts]` Write compact diagnostics into empty synthesis artifacts, including participant attempt/success/failure counts and transcript size, so failed swarms leave actionable evidence instead of only `No synthesis output`.

## 0.26.0: Actor Worker v2 and Package Contract Hardening

- `[Actor Worker]` Promoted the packaged `actor-worker` into a v2 reference pattern with compact `worker-status.json`, optional per-task result artifacts under `worker-artifacts/`, stale-claim surfacing through status, and artifact metadata on `task.result` room messages.
- `[Recipes]` Audited packaged async recipe mailbox contracts so `control.stop` and `control.cancel` remain declared only for actor-domain handlers such as locker/coordinator/music control, while generic async recipes expose `control.kill` for runtime termination.
- `[Packaging]` Hardened dist package regressions with mirrored asset checks for `dist/scripts`, `dist/recipes`, `dist/fixtures`, and `dist/skills`, plus negative checks for stale dist files and source-only runtime imports in built script shims.
- `[Skills]` Updated the actors skill recipe navigator to document the v2 worker pattern and its `control.kill` termination contract.

## 0.25.0: Recipe Doctor Remediation UX

- `[Recipe Doctor]` Added prioritized advisory remediations to recipe doctor output, including a compact top action, structured verbose remediation entries, blocked lower-priority candidates for invalid/disabled overrides, and ordered coverage for invalid, disabled, shadowed, and risky shell-boundary recipes.
- `[Docs]` Documented the recipe doctor remediation surface in the tool registry guide.

## 0.24.8: Mailbox Loop Kill Contract Hotfix

- `[Mailbox Loop]` Aligned generic mailbox-loop termination with the actor-message kill contract: only `control.kill` stops generic loop drains; `control.stop` and `control.cancel` remain actor-domain messages unless a recipe handles them explicitly.
- `[Docs]` Updated worker and recipe guidance so backlog implementer shutdown examples use `control.kill` for runtime termination and describe `control.stop` as domain-local vocabulary.

## 0.24.7: Actor Message Kill Contract Hotfix

- `[Actor Messages]` Narrowed runtime termination by actor message to `control.kill` only; `control.stop` and `control.cancel` now remain recipe-local mailbox vocabulary instead of aliases for killing/cancelling a run.
- `[Docs]` Updated actor-message, async-run, and actor-skill guidance so only `control.kill` is documented as the action that kills an actor run.

## 0.24.6: Async Run Restart Status Hotfix

- `[Async Runs]` Treat freshly spawned runner PIDs as running during a short Linux `/proc` identity grace window, preventing restart status checks and immediate run messages from misclassifying a new run as `exited` before its command line is observable.

## 0.24.5: Auto-Discovered Skills Hotfix

- `[Skills]` Auto-discovered source checkouts now contribute their co-located `skills/` directory through Pi resource discovery, so extension-local actors/swarm skills load even when `pi-actors` is used directly from `~/.pi/agent/extensions` instead of installed as a package.
- `[Packaging]` Kept package skill metadata directory-based for both `dist/skills` and source `skills`, preserving bundled skill discovery through package installs while the extension also contributes co-located skills at runtime.

## 0.24.4: Music Player Message Control Hotfix

- `[Music Player]` Preserve typed actor-message envelopes for run-mailbox delivery so `player.<action>` messages dispatch by message type instead of relying on body payload text.
- `[Music Player]` Emit `player.stopped` when playback stops so actor inspector and run messages show an explicit domain stop event before terminal completion.

## 0.24.3: Actor Inspector Body Field Hotfix

- `[Inspector]` Removed the selected-item key-label shim by projecting actor-message detail rows with a real `body` field instead of rendering `body_preview` under an alias.

## 0.24.2: Actor Inspector Item View Hotfix

- `[Inspector]` Removed the roster panel from selected actor-message item inspection, kept the compact route header styling, added the same left/right gutter used by inspector rows, and renamed the selected-item `body_preview` label to `body`.

## 0.24.1: Build Script Package Hygiene Hotfix

- `[Backlog]` Added the next focused backlog set for recipe doctor remediation UX, actor worker v2, and dist package contract hardening.
- `[Skills]` Clarified agent-governed promotion of successful transient actor patterns into durable local tools via `register_tool`, without UI buttons or automatic registration.

## 0.24.0: Reliability, Mailbox Workers, and Dist-First Packaging

- `[Prompts]` Clarified that recipe registry warnings are actionable maintenance: invalid or blocking recipes should be fixed, removed, or disabled rather than ignored.
- `[Backlog]` Pruned and refocused the backlog around reliability, mailbox-loop consolidation, protocol fixtures, follow-up deduplication, and portability reality checks.
- `[State]` Added resilient JSON/JSONL state reader helpers and routed room, inspector, runtime wake, run inbox, and observability outbox reads through them so malformed state records degrade instead of breaking previews; room status now reports state diagnostic counts and reader degradation behavior has direct regression coverage.
- `[Observability]` Deduplicated run outbox events by stable event id so line-counter resets do not replay already-seen follow-ups; stale dedupe state is pruned with terminal and missing runs.
- `[Mailbox Loop]` Added initial run/branch mailbox claim-and-handle helpers plus branch inbox claiming support, failed-handler transitions, standard stop-message detection, bounded message drains, duplicate-claim coverage, and a packaged `actor-worker` demo recipe for canonical mailbox loops.
- `[Scripts]` Added installed-package coverage proving the packaged `actor-worker` script uses compiled `dist` runtime modules instead of importing TypeScript from `node_modules`; `npm run build` now cleans stale `dist` output, mirrors packaged `scripts/`, `recipes/`, and `fixtures/` into `dist/`, and syntax-checks the built script entrypoints. The `actor-worker`, `async-runner`, `validate-recipe`, and `conformance` executables are now thin shims over compiled TypeScript entrypoint logic in `lib/actor-worker.ts`, `lib/async-runner.ts`, `lib/validate-recipe.ts`, and `lib/conformance.ts`, with build-output regressions for the compiled shim modules.
- `[Packaging]` Exposed optional `pi.sourceExtensions` metadata pointing at the root TypeScript entrypoint while keeping Node-compatible `pi.extensions` on compiled `dist` output.
- `[Context]` Clarified the project frame as an experimental self-evolution membrane for local agent capabilities, grounded in explicit actors, recipes, fixtures, skills, and inspectable state.
- `[Protocol]` Clarified dotted `channel.action` message types as the minimal action surface: scripts can often dispatch from `type` alone while agents may use `body` for free-form prompts.
- `[Recipes]` Fixed `pipeline-quorum-review` registry loading by inlining the quorum fanout over its `models` array instead of importing a nested repeated recipe with unresolved runtime values.
- `[Recipes]` Made Markdown recipe frontmatter more forgiving: `args` can be a comma-separated scalar and `defaults` can be a list of `key: value` entries, both normalizing to the canonical JSON recipe shape.
- `[Packaging]` Build output now mirrors packaged `skills/` into `dist/` alongside scripts, recipes, and fixtures so the JS-only distributive tree carries the project skills; package skill metadata now points at `dist/skills` with `pi.sourceSkills` preserving root TypeScript/source-tree paths, and README now documents the dist-first/source-optional package shape. The dist build pipeline now lives in `scripts/build-dist.mjs` instead of an inline package script, completing the compiled script entrypoint backlog slice.
- `[Docs]` Added a platform support matrix for mailbox-only, FIFO, named-pipe, and process-control behavior across Linux/macOS/WSL and native Windows, with regressions proving native Windows FIFO limits remain visible and the canonical worker recipe stays mailbox-only.
- `[Backlog]` Marked the reliability, mailbox loop, protocol fixture, portability, and compiled-entrypoint milestone set complete; future backlog additions should come from concrete actor workflow evidence.
- `[Scripts]` Migrated `recipe-utils`, `locker`, `coordinator`, and `validate-recipe` command logic behind compiled TypeScript domain modules while preserving the stable `scripts/*.mjs` shim paths; project guidance frames this as deliberate standard-library growth with clear domain boundaries while keeping self-contained application/build scripts such as `music-player.mjs` and `build-dist.mjs` standalone.
- `[Protocol]` Added compact protocol fixtures for actor messages, mailbox contracts, run inbox/outbox records, room messages/rosters, run state, recipe summaries, and artifact manifests with regression coverage.
- `[Skills]` Documented the passive-active skill evolution discipline: `actors` tracks extension mechanics while `swarm` tracks orchestration standards and lessons.

## 0.23.0: Actor Manifests, Inspection, and Runtime Hygiene

- `[Tools]` Unified branch-envelope routing for direct branch messages and selected-recipient room multicast so both paths persist the same branch-local inbox shape before dispatching through the parent run mailbox.
- `[Async Runs]` Added attention semantics for coordinator-bound actor messages: `metadata.requires_response=true` now produces a follow-up while ordinary coordinator progress messages default to notification-level delivery.
- `[Registry]` Added `inspect target=recipes view=doctor` as an intentional recipe health surface with compact severity/action counts and structured verbose diagnostics.
- `[Async Runs]` Added artifact manifest resolution for string and object artifact declarations, including `exists`, `size`, `sha256`, and missing required artifact visibility in artifact inspection.
- `[Async Runs]` Added explicit terminal run retention controls via `control.archive` and `control.prune`, with active-run fail-closed behavior and optional artifact preservation during prune.
- `[Inspector]` Added stable event ids, needs-response markers, and session-local read markers to actor inspector previews and selected-item details.
- `[Registry]` Suppressed routine trusted `bash` wrapper diagnostics from startup warning notifications while keeping them available through recipe diagnostics surfaces.
- `[Async Runs]` Added a rebuildable run-state index for run listing and observability discovery, with corrupt-index fallback to recursive scan and nested-run-safe state directory entries.
- `[Testing]` Added `npm run conformance` for a compact CI-ready protocol conformance runner covering recipes, registry, spawn lifecycle, messaging, rooms, branch inboxes, ownership, artifacts, and attention semantics.
- `[Mailbox]` Added backward-compatible typed mailbox contracts with normalized inspection and advisory warnings for undeclared run message types.
- `[Output]` Centralized inspect, preview, and tool-output size limits so bounded output governance is shared across tools, room previews, and the actor inspector.
- `[Registry]` Added explicit mitigation guidance to command-template trust-boundary warnings for shells, eval modes, and broad filesystem mutation.
- `[Scripts]` Added top-of-file descriptions to packaged helper scripts so their purpose, boundaries, and policy ownership are clear when opened directly.
- `[Rooms]` Added room compaction metadata with dropped count, configured maximum, and first/last kept timestamps exposed through room status inspection.
- `[Recipes]` Improved usage telemetry with launch-kind counters (`tool`, `spawn`, `direct`) and explicit reset reasons when recipe content fingerprints change.
- `[Inspect]` Added `inspect target=recipes view=imports` to summarize recipe import aliases and source references for debugging recipe composition.

## 0.22.5: CI Stability Hotfix

- `[Tests]` Stabilized the Windows named-pipe control endpoint regression by keeping its synthetic run alive longer under slower full-suite CI scheduling.
- `[Tests]` Stabilized the coordinator-locker queue/lock smoke by waiting for assignment, renewal, and denial actor messages before stopping the helper, removing a FIFO processing race from main-branch validation.

## 0.22.4: Actor Isolation and Registry Diagnostics Hotfix

- `[Tests]` Added explicit regression coverage that ad hoc recipe files outside the user recipe root remain recipe components rather than automatically exposed tools, reinforcing the location-based tool exposure invariant.
- `[Registry]` Improved invalid recipe diagnostics for discovery summaries so JSON parse failures, missing templates, and malformed Markdown recipes keep actionable causes, structured severity, and suggested actions instead of collapsing to a generic invalid recipe message.
- `[Observability]` Keyed run transition observation by state directory instead of display run id so nested child runs or reused run names do not collide in terminal follow-ups and pruning state.
- `[Async Runs]` Normalized run-message delivery failures after durable inbox append: failures now preserve queued state details such as `queued`, `inbox_id`, and `delivery_error`, while successful FIFO, named-pipe, and mailbox-only deliveries also expose the inbox id.
- `[Tests]` Added explicit cross-session kill-control regression coverage so run ownership boundaries stay fail-closed for destructive actor controls as well as ordinary messages and inspection.
- `[Tests]` Added branch and room routing safety regressions for cross-run senders and invalid multicast recipients, including assertions that failed validation does not create branch inbox or room timeline records.
- `[Actor Rooms]` Hardened branch inbox reads and status rewrites against malformed JSONL lines; valid messages continue to update while corrupted record counts surface through branch mailbox inspection.
- `[Tests]` Added async lifecycle regression coverage for missing-result terminal status inference, preserving `cancelled`/`killed` over generic `exited`, and tail behavior when only event logs exist.
- `[Registry]` Allowed `register_tool` to persist object command-template configs with composition flags, aligning it with recipes and `spawn`, while preserving precise validation errors for invalid object templates.
- `[Registry]` Added deterministic live-reload regressions for invalid user updates blocking lower-priority fallback recipes and valid recovery refreshing the active tool schema without restart.
- `[Tools]` Preserved target tool failure shape through `message to=tool:<name>` by including the tool name, message type, bounded params preview, and original error on routed failures.
- `[Actors]` Tightened branch and room routing isolation so session-owned runs reject branch/room messages from a different current Pi session, keeping room state scoped to the owning actor tree.
- `[Tests]` Added executable protocol-example coverage for public actor-message, room join/leave, mailbox, spawn, and inspect examples so documentation drift fails in CI.

## 0.22.3: Idempotent GitHub Release Workflow Hotfix

- `[Release]` Made the tag-triggered GitHub Release workflow idempotent: existing releases are edited with the generated title and notes instead of failing when an operator already created the release for the tag.
- `[Context]` Added a changelog signal rule to project context and removed release-bookkeeping-only bullets from changelog history so future entries describe meaningful behavior rather than package-version metadata.

## 0.22.2: Portable Recipe Tool Exposure Hotfix

- `[Registry]` Stopped writing redundant exposure metadata during registration and aligned docs/tests around location-based tool exposure so recipes remain portable between user, ad hoc, and packaged roots.
- `[Skills]` Generalized the actors-skill tool-registration lenses and added existing recipe surfaces, including skill-local recipes, as first candidates for promotion into durable tools.

## 0.22.1: Tool Registration Lens Hotfix

- `[Skills]` Added tool-registration lenses to the packaged actors skill so agents prefer persistent tools for error-prone workflows, safe preflights around dangerous operations, and context-affordance shortcuts that should be visible in future sessions.

## 0.22.0: Cross-Platform Runtime Notification Layer

- `[Runtime]` Started the cross-platform notification layer with a file-backed advisory wake notifier (`wake.jsonl`), explicit initial/wake/poll reconciliation callbacks, periodic reconciliation fallback, and run-message/room-message/branch-inbox wake records. Run messages now persist a canonical inbox record before optional endpoint delivery, can accept mailbox-only control endpoints without FIFO/named-pipe transport, mark delivered endpoint messages `sent`, expose recent run inbox entries through `inspect view=mailbox`, and provide locked run-inbox claim/handle/fail helpers for runtime reconciliation loops. Files remain the canonical mailbox/event state for inspection and crash recovery.
- `[Docs/Tests]` Documented the "wake, not queue" runtime model, added cross-platform music-player smoke guidance, and added coverage for persisted wake events, missed `fs.watch` recovery through polling, and Windows named-pipe message wakes.
- `[Packaging]` Removed the root JavaScript entrypoint wrapper from packaged files and pointed extension metadata directly at the compiled `dist/index.js` output. Source checkouts keep `index.ts` as the only root entrypoint while installed packages load compiled JavaScript from `dist`.
- `[Docs/Prompts]` Removed stale FIFO-queue wording from branch-direct message docs and coordinator prompt injection so queued mailbox work is described consistently with the notification/runtime model. Clarified that worker-backed direct branch messages are runner-owned prompt steering, not coordinator follow-ups, while one-shot prompt children do not consume branch inbox records automatically.
- `[Recipes]` Migrated the packaged music-player control path from Unix FIFO commands to queued mailbox commands, preserving addressed `message` control while making the script align with mailbox-only runtime endpoints.
- `[Recipes]` Added a native Windows `wmp` music-player backend that drives legacy Windows Media Player through `powershell.exe`/COM, verifies `wmplayer.exe` in the standard Program Files locations, and includes mailbox-backed play, pause, next, previous, and stop controls.
- `[Recipes]` Reduced music-player mailbox overhead by using advisory wake records, `fs.watch` where available, and inbox file signatures so the loop avoids repeatedly locking and rereading an unchanged mailbox.
- `[Recipes]` Improved Unix-like playback by adding the macOS-native `afplay` backend, scanning additional common audio extensions, and running child players in their own process group so controls can signal the playback subtree directly.

## 0.21.0: Native Windows Actor Control and Literate Recipes

- `[Async Runs]` Added a platform-adapted run-control path: Unix FIFO behavior remains backward-compatible, native Windows can target named-pipe run-control endpoints recorded in run state, and run message receipts still update events and inbox state through the same actor-message path.
- `[Async Runs]` Added Windows process-tree termination planning for cancel/kill through `taskkill`, while preserving Unix process-group signaling semantics.
- `[Scripts]` Migrated `locker.mjs` and coordinator locker calls to platform-adapted control metadata: Unix still uses `control.fifo`, while native Windows can use a deterministic named-pipe endpoint with the same message protocol.
- `[Branch Messages]` Added bounded branch-inbox terminal retention during status transitions, preserving active queued/claimed work while compacting older handled/failed records for long-lived branch runners.
- `[Recipe Discovery]` Tightened trust-boundary diagnostics so combined short shell/eval flags such as `bash -lc` and nested recipe command-template objects are surfaced, including the packaged validation wrapper's trusted shell boundary.
- `[Rooms]` Recorded the backend decision to keep the current file-backed room adapter until real workflows need live subscriptions/fanout or shared mutable state, backed by a mixed room/direct-branch workload regression.
- `[Recipes]` Added Markdown-authored recipe loading for `.md` files with frontmatter metadata and fenced executable recipe/template blocks, with same-id JSON shadowing Markdown in the same priority layer.
- `[Retirement]` Extended run summaries to discover nested child async-run state dirs, blocks opt-in retirement while nested children are still running, surfaces child/terminal child counts on candidates, and has the session watcher retire ready candidates with one graceful stop attempt plus owned cancellation fallback. Added an integration smoke where an idle supervisor stops after its nested child is terminal while a non-opt-in service remains running.
- `[Coordinator]` Consolidated direct branch inbox claim/finalize rewrites behind one locked mutation helper and moved room-swarm mode dispatch behind an explicit mode registry. Unknown coordinator modes now fail closed, and `pipeline-room-swarm` exposes the supported mode enum.
- `[Docs]` Documented the local Actor OS smoke matrix covered by `npm test`, spanning room coordination, direct branch delivery, inbox claim/handle transitions, inspector navigation, recipe context injection, persistence suggestions, and opt-in retirement smoke.
- `[Docs/Tests]` Documented native Windows support scope and added regression coverage for Windows endpoint metadata, mocked named-pipe sends, Windows process-control planning, unchanged Unix FIFO behavior, locker control metadata, branch inbox compaction, mixed room/direct workloads, Markdown recipe loading/discovery/validation, nested child-run retirement gating, and packaged recipe trust diagnostics.

## 0.20.2: Installed Extension Entrypoint Hotfix

- `[Packaging]` Added a JavaScript extension entrypoint wrapper and changed package metadata to load `./index.js`, so npm-installed packages import compiled `dist/index.js` instead of asking Node to strip `index.ts` under `node_modules`. Source checkouts still fall back to `index.ts` before a local build exists.
- `[Build]` Extended the compiled runtime build to emit `dist/index.js` alongside `dist/lib/*.js`, keeping extension entrypoint imports and script runtime imports on the same installed-package path model.
- `[Rooms]` Fixed immediate room append results to report the true persisted room message count after long timelines instead of the default 40-message preview length; `appendRoomMessage`, existing-member room joins, and `getRoomStatus()` now share the same line-count helper.
- `[Tests]` Added installed-package coverage that imports the extension entrypoint from package metadata without TypeScript stripping, plus room-count regression coverage beyond the default preview limit.

## 0.20.1: Installed Packaged Recipe Root Hotfix

- `[Recipe Imports]` Fixed installed compiled runtime path resolution so bare user recipe imports can fall back to the packaged standard-library `recipes/` directory instead of looking for a non-existent `dist/recipes` directory.
- `[Tests]` Added installed-package validation coverage for a user recipe that imports a packaged recipe by bare name, preserving the documented priority order for user, adjacent, and packaged recipes.

## 0.20.0: Compiled Runtime Entrypoints

- `[Packaging]` Added a build step that emits compiled `dist/lib/*.js` and declaration files from the TypeScript runtime modules, with relative `.ts` imports rewritten to `.js` for installed package execution.
- `[Async Runs]` Replaced the emergency installed-package copy workaround in `scripts/async-runner.mjs` with dist-first imports. Installed npm packages now execute the async runner against compiled JS without relying on Node native type stripping for `.ts` files under `node_modules`; source checkouts still fall back to TypeScript imports for local development.
- `[Scripts]` Updated `scripts/validate-recipe.mjs` to use the same dist-first import path, so packaged recipe validation also runs from compiled JS when installed from npm.
- `[Tests]` Updated installed-package smoke coverage to simulate `node_modules/@llblab/pi-actors` with `dist`, execute scripts without `--experimental-strip-types`, and assert the old `.type-strip-lib` workaround is not used.
- `[Package]` Changed the package description to `Local Actor Kernel for Pi`, added `tsconfig.build.json`, and included `dist` in the published package.

## 0.19.11: Installed Async Runner Hotfix

- `[Async Runs]` Fixed installed npm package async recipe launches on Node 22 by avoiding direct runtime imports of raw `.ts` files from under `node_modules` in `scripts/async-runner.mjs`. Installed runners now copy the package `lib` sources into the run state before importing them, keeping Node native type stripping outside the blocked `node_modules` path.
- `[Scripts]` Applied the same installed-package import guard to `scripts/validate-recipe.mjs`, so the packaged recipe validator works when invoked from an installed `@llblab/pi-actors` package.
- `[Tests]` Added installed-package script smoke coverage that copies `lib`/`scripts` under a temporary `node_modules/@llblab/pi-actors` path and verifies both async runner execution and recipe validation avoid `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`.

## 0.19.10: Legacy Branch Message Claim IDs

- `[Branch Messages]` Coordinator claim handling now assigns IDs to older/manual queued branch inbox entries that lack `id`, so injected direct messages can still transition to `handled` or `failed` and do not repeat forever.
- `[Tests]` Extended direct branch inbox coordinator coverage to include a legacy no-ID message and assert both claimed/handled timestamps are recorded.
- `[Docs/Context]` Updated actor-message docs and durable project context for legacy branch message claim IDs.

## 0.19.9: Locked Branch Inbox Mutations

- `[Branch Messages]` Added lock-guarded append and status rewrites for branch-local direct-message inbox files so concurrent direct delivery and coordinator claim/handle transitions do not overwrite each other.
- `[Coordinator]` Made room-swarm branch prompt execution atomically claim queued direct messages before injection, then mark claimed messages as `handled` or `failed` after the child prompt exits.
- `[Tests]` Added concurrent branch inbox append coverage and asserted coordinator direct-message handling records both `claimed_at` and `handled_at`.
- `[Docs/Context]` Updated actor-message docs, project context, and backlog safeguards for locked branch inbox mutations.

## 0.19.8: Efficient Room Status Reads

- `[Rooms]` Changed room status inspection to count JSONL entries and read only the last timeline record instead of parsing the full room timeline into actor-envelope objects.
- `[Inspector]` Preserved the existing `inspect room:<run> view=status` shape while reducing storage/read amplification for large room transcripts.
- `[Docs/Context]` Updated actor-message docs, backlog safeguards, and project context for efficient room status reads.
- `[Tests]` Added regression coverage that room status preserves message count and last-message metadata across longer timelines.

## 0.19.7: Burst-Safe Roster Writes

- `[Rooms]` Debounced room roster rewrites when a burst only changes a member's `last_seen`, while still writing semantic roster changes such as role, status, display, caps, claim, or parent immediately.
- `[Runtime IO]` Added `PI_ACTORS_ROOM_ROSTER_MIN_MS` as the roster-only debounce interval, mirroring the existing communication snapshot debounce approach without changing public `room:<run>` message or inspect semantics.
- `[Docs/Context]` Updated actor-message docs, project context, and the remaining rooms backlog scope to preserve the new burst-safe roster invariant during future storage/backend changes.
- `[Tests]` Added regression coverage for roster rewrite debounce and immediate semantic roster updates.

## 0.19.6: Conservative Retirement Candidates

- `[Observability]` Added per-run descendant `pi -p` worker counting and exposes `descendantSubagents` on run observations. Ambient run status still counts active descendant workers, but now retains the per-run attribution needed for supervisor lifecycle decisions.
- `[Retirement]` Tightened opt-in `retire_when: "children_terminal"` candidate detection so supervisors are not considered retirement-ready while command-template progress or descendant `pi -p` workers are still active.
- `[Docs/Context]` Updated async-run docs, project context, and the remaining retirement backlog scope to reflect the conservative candidate baseline and the remaining child async-run/output-flush work.
- `[Tests]` Added regression coverage that blocks retirement candidates with descendant subagents.

## 0.19.5: Branch Inbox Inspector Filters

- `[Actor Inspector]` Added branch-local inbox previews to the compact actor communication table, so queued direct `branch:<run>/<branch>` work is visible alongside room, run inbox, and outbox messages.
- `[Actor Inspector]` Added `/actors-inspector-filter unread`, `/actors-inspector-filter branch <name>`, and `/actors-inspector-filter current-branch <name>` to focus queued branch inbox work and one branch's room/direct/inbox traffic without exposing full payloads by default.
- `[Docs/Skills]` Updated README and the packaged actors skill with the new inspector filters and branch-inbox preview behavior.
- `[Backlog]` Closed the high-priority actor communication TUI preview item now that unread/current-branch navigation is implemented with branch read-state semantics.

## 0.19.4: User Recipe Collection Suggestions

- `[Observability]` Broadened recipe persistence suggestions from direct inline spawns to the normal user workflow: any successful actor run backed by a recipe outside `~/.pi/agent/recipes` now asks the launching agent to offer copying/registering it into the user recipe root when it fits this machine's recurring workflow.
- `[Runtime]` Preserved the ask-first boundary and suppression for recipes already in the user recipe root, so pi-actors grows operator muscle memory without silently writing user recipe files.
- `[Docs/Prompt]` Updated README, async-run docs, actors skill, onboarding prompt, and project context to frame `~/.pi/agent/recipes` as the everyday per-machine collection of reusable actor recipes/tools.
- `[Tests]` Added coverage for successful external recipe suggestions, while keeping user-owned recipe suppression covered.

## 0.19.3: Spawn Recipe Persistence Suggestions

- `[Observability]` Added semi-active recipe persistence suggestions for successful direct `spawn` runs. Inline/ad hoc spawned actors now record `launch_source: "spawn"`, and their successful terminal follow-up asks the agent to offer saving the reusable pattern as a durable recipe/tool under `~/.pi/agent/recipes` without auto-saving.
- `[Runtime]` Recorded `launch_source` metadata for actor starts so observability can distinguish direct spawns from registered recipe-tool runs and avoid prompting for actors already backed by user-owned recipes.
- `[Docs/Prompt]` Updated onboarding prompt guidance, README, async-run docs, and project context around ask-first recipe persistence after successful transient actors.
- `[Tests]` Added regression coverage for successful transient spawn suggestions and suppression when the run already came from a saved user recipe.

## 0.19.2: Actor Recipe Context Bundle

- `[Actor Context]` Added a recipe context bundle for file-backed async recipes. The runtime now collects the raw authored entry recipe and resolved imports into deterministic JSONL records with filename-derived `name`, import alias/path metadata, role/depth, and raw recipe JSON so spawned LLM actors can understand the workflow composition behind their prompt.
- `[Actor Context]` Annotated command-template leaves with actor recipe context and appends the JSONL bundle to child `pi -p` prompts. The recipe record that launched the current child receives `"you_are_here": true` plus path metadata, enabling actors to give advisory feedback on their own recipe/composition fit; recipes can opt out with `"actor_context": false` / `"off"` when a minimal prompt is required.
- `[Tests]` Added coverage for raw recipe context record generation, import identity, `you_are_here` JSONL marking, prompt injection for `pi -p`, execution-time context propagation, async-run persistence, and recipe opt-out behavior.

## 0.19.1: Actor Inspector Hotfix

- `[Actor Inspector]` Fixed the live communications roster and row numbering controls after real swarm usage. `/actors-inspector-toggle <rows>` now keeps the room preview cap aligned with the requested row count, current-run sequence numbers are assigned before row limiting so the visible tail keeps its full-log positions, and roster role labels use concise `name/role` text instead of slugifying full role descriptions.
- `[Coordinator]` Preserved explicit `--thinking off` forwarding in `scripts/coordinator.mjs` so packaged room-swarm launches keep caller-selected thinking policy instead of silently relying on CLI defaults.

## 0.19.0: Modular Coordination And Active Mailboxes

- `[Coordination]` Decoupled the overloaded `coordinator-locker.mjs` script into two completely independent, single-purpose components: a dedicated stateful `locker.mjs` (recipes `locker.json` and `coordinator-locker.json`) that manages resource locking, task queueing, and lease expirations; and a powerful, modular `coordinator.mjs` orchestrator. The coordinator manages execution lifecycles and process pools, supporting four distinct pluggable strategies via `--mode`: `consensus` (chat-swarm), `pipeline` (sequential), `fanout` (parallel review), and `pool` (worker pool pulling from locker).
- `[Actor Messages]` Implemented active direct actor inbox queue semantics. The modular coordinator now automatically inspects, claims (`claimed`), injects into prompt context, and finalizes (`handled` or `failed`) any queued direct branch messages (`branches/<branch>/inbox.jsonl`) during subagent executions, making direct messages active initiating work items. Backed by complete regression test coverage.

## 0.18.0: Actor Runtime Hardening And Recipe Guardrails

- `[Async Runs]` Made actor starts safer under concurrency and stale state. Duplicate active `run_id` / `state_dir` launches now fail before state is cleared, concurrent starts are serialized by a start lock, stale terminal run directories are cleaned automatically, and atomic JSON writes use collision-resistant temp names. Impact: restarts and concurrent launches no longer orphan active processes or overwrite logs, messages, progress, and control metadata.
- `[Command Templates]` Added a default parallel fanout cap of 64 branches, configurable with `PI_ACTORS_MAX_PARALLEL_BRANCHES`. Impact: accidental huge repeat/parallel expansions fail early instead of spawning unbounded child processes.
- `[Rooms & Messages]` Hardened room communication while preserving the single public actor-message model. Room timeline/roster/snapshot writes are serialized, branch direct messages are also persisted as queued per-branch inbox entries with IDs and internal claimed/handled/failed state transitions, bursty branch communication snapshot rewrites are debounced while root snapshots stay current, room reads use bounded tails, room timelines compact to a bounded retained tail, and `room:<run>` supports selected-recipient multicast via `metadata.recipients` while keeping one room-visible transcript entry. Impact: long-lived swarms can address subsets of same-run branches without subrooms, lost concurrent writes, unbounded room logs, repeated burst branch-snapshot rewrites, or expensive full-log reads.
- `[Actor Inspector]` Turned the inspector into a compact operator view for active actor coordination. It now has channel/mention filters, bounded body previews, default noisy-room row caps, an inline wrapping `role/name` roster summary with inactive departed participants muted, stable narrow-row rendering, plain name-driven actor identity, and bounded wide-character layout. Impact: operators can follow busy rooms, distinguish current and completed participants, and inspect selected messages without flooding the terminal, expanding roster dashboards, or adding extra preview-mode commands.
- `[Observability]` Reduced long-session overhead by pruning stale run observation state, caching active-subagent process scans, and expanding ambient run triangles with descendant `pi -p` workers launched by coordinators. Impact: terminal status remains useful during long actor sessions without retaining completed-run bookkeeping, repeatedly scanning `/proc` on every refresh, or showing one coordinator triangle when a visible worker tree is still running.
- `[Recipes]` Strengthened the recipe registry as a local capability surface. Recipe loading now rejects oversized files and excessive import depth, reports risky executable shapes and unsafe recipe-root permissions, exposes an integrity manifest, warns when the recipe-root watcher fails, derives recipe identity from filenames, resolves bare import names by recipe-root priority, and makes tool exposure location-derived: user recipe-root files are tools, packaged/ad hoc recipes are components. Impact: recipes are easier to audit, easier to compose from the standard library, harder to misuse accidentally, and no longer depend on redundant `name` / `tool` JSON fields for identity or exposure.
- `[Docs/Skills/Context]` Updated the README, actor-message/template-recipe/command-template docs, recipe-library/task-first docs, actors/swarm skills, onboarding prompt, and project context to reflect the hardened runtime, room/inspector controls, filename-derived recipes, location-derived tools, consensus-first build orchestration, shell-placeholder boundaries, and the rule that recurring multi-agent scenarios should grow packaged recipes/pipelines instead of task-local orchestration scripts. `BACKLOG.md` now stays focused on completable future work while durable operating principles live in project context.

## 0.17.1: Inspector Hotfix And Room Swarm Hardening

- `[TUI]` Fixed actor inspector line bounding to use `visibleWidth()` for direction/type/summary/body width math, replaced the verbose two-line preview with a hidden-by-default numbered table, made bare `/actors-inspector-toggle` open 12 rows from closed state, removed the verbosity toggle, made `/actors-inspector-toggle <rows>` update the live row count, upgraded `/actors-inspect <number>` to show a separated two-column header plus all preview-object properties as aligned two-space key/value columns, and added a styled wide-character regression. Impact: room previews with wide text no longer crash Pi, actor logs stay dense while preserving message type visibility, operators can tune visible row count without persistent inspector settings, and they can drill into one visible row then toggle back to the table.
- `[Recipe Library]` Added `pipeline-room-swarm` backed by `scripts/room-swarm.mjs`: repeated room-aware participants join `room:<run>`, coordinate over multiple room-visible rounds, leave cleanly, and synthesize the room transcript into a Markdown artifact. Roles can be supplied via `roles_path` to avoid raw JSON placeholders, default roles use plain actor names, room rosters preserve display metadata, and `locker=true` composes a local coordinator-locker cell for artifact locks and decision journaling with regression coverage. Direct branch delivery remains available for worker protocols that consume parent-run branch envelopes, but the packaged swarm no longer relies on it for peer coordination. Impact: the DeepSeek room-swarm experiment is now represented as a policy-light packaged scenario while concrete model choice remains caller/operator policy.
- `[Docs]` Reconciled `BACKLOG.md` back to future-only open work, removing completed hotfix implementation notes and version-scoped backlog language now captured in this changelog. Refreshed README and project context around the packaged room-swarm/coordinator-locker library surface and actor-inspector TUI ownership.

## 0.17.0: Actor Rooms And Inspector

- `[Actor Messages]` Added the 0.17 actor-room communication slice: `room:<run>` task rooms, append-only room timelines, room rosters, join/leave handling, same-run room/direct provenance checks, branch/run communication snapshots, `inspect room:<run> view=status|messages|previews|roster|contacts`, and `inspect run:<id> view=communication`. Impact: run actors and contacted branches can discover peers, post shared task messages, and inspect communication state through the same `spawn` / `message` / `inspect` actor model.
- `[TUI]` Added the hidden-by-default actor inspector widget with `/actors-inspector-toggle` and `/actors-inspector-verbosity-toggle`, compact and verbose layouts, current-run scoping, chronological sequence numbers, owner filtering, JSONL-tolerant preview reads, mobile-width and wide-character-aware truncation, and transparent/dark row striping. Impact: operators can see the current actor conversation at a glance without flooding the prompt or leaking unrelated session previews.
- `[Registry]` Added usage metadata and operator-gated cleanup recommendations to recipe registry summaries, removed stale public references to the old tool config filename, removed recipe content exposure markers from repository recipes/docs/fixtures, and fixed the 0.17 registry model around location-derived tool exposure: every recipe in `~/.pi/agent/recipes/*.json` is an agent tool, `register_tool` creates recipe files there under the hood, and packaged/ad hoc recipes outside that root are components. Impact: the sticky agent tool surface is explicit executable muscle memory, maintained like capability state rather than configured through per-recipe exposure flags.
- `[Docs]` Updated README, actor-message docs, async-run docs, recipe-library docs, actors skill, backlog, and project context around the room/roster protocol, inspector behavior, release-artifact hygiene, and the persistent-backlog-implementer protocol. The implementer workflow remains future recipe-composition work around reusable cells such as `coordinator-locker`, not bespoke release scripts.

## 0.16.4: Recipe Usage Fingerprints

- `[Recipe Usage]` Added content fingerprints to user recipe usage metadata. Impact: when a recipe file is edited and its authored meaning changes, the next launch resets `usage.calls`, records `usage.reset_at`, and starts counting usage for the current recipe content.
- `[Docs]` Documented fingerprint-backed usage reset semantics in the template recipe and tool registry docs.

## 0.16.3: Recipe Import Path Placeholders

- `[Template Recipes]` Added static `{repo}` and `{agent}` expansion for recipe paths, including `imports` and `from` bindings. Impact: recipes can import sibling packaged/user recipes without hard-coded absolute paths while keeping imports load-time deterministic.
- `[Docs]` Documented `{repo}` and `{agent}` import path placeholders in the template recipe standard.

## 0.16.2: Recipe Registry Diagnostics Hotfix

- `[Schema]` Derived recipe tool arguments without expanding runtime-dependent repeat nodes. Impact: valid recipes using repeat expressions such as `{lenses.length}` can be exposed as tools instead of being skipped during startup schema generation.
- `[Runtime]` Replaced the dense semicolon warning with grouped recipe registry diagnostics and explicit spacing. Impact: startup diagnostics are easier to scan and do not visually run into adjacent text.
- `[Recipes]` Added a packaged `lens-swarm` recipe that composes the review coordinator without concrete model-version defaults. Impact: the standard library includes the general multi-lens review launcher instead of relying only on operator-local copies.

## 0.16.1: Recipe Registry Hotfix

- `[Runtime]` Prevented invalid user recipe files from aborting extension startup when tool-schema generation fails, surfacing a warning and skipping the offending tool instead. Impact: one bad recipe in `~/.pi/agent/recipes` no longer takes down the pi-actors extension.
- `[Recipe Discovery]` Excluded the legacy migration report file from recipe discovery. Impact: legacy migration reports no longer appear as broken recipe/tool candidates after migration.

## 0.16.0: File-Discovered Recipe Registry Migration

- `[Version]` Began the `0.16.0` breaking-change cycle and captured the file-discovered recipe registry migration plan in `BACKLOG.md`. Impact: the next release target is now explicit: replace the legacy live registry with validated recipe files, filename identity, location-based exposure, override/disable semantics, migration reporting, registry inspection, and usage-informed cleanup.
- `[Recipe References]` Started filename-identity support for recipes by deriving the recipe id from the JSON filename when `name` is omitted, while preserving optional disabled and description metadata through recipe resolution. Impact: new recipe files can move toward filename-as-identity without losing human-readable descriptions.
- `[Recipe Discovery]` Added an initial file-discovered recipe registry domain with flat root scanning, filename ids, priority shadowing, invalid high-priority recipe blocking, disabled overrides, and exposure detection. Impact: the 0.16 registry migration now has a tested discovery core before wiring it into runtime loading.
- `[Recipe Migration]` Added a legacy registry migration domain that converts old registry entries into user recipe files, preserves descriptions/args/defaults/templates, refuses to overwrite existing recipe files, writes a migration report, and archives the source only when migration has no conflicts or invalid entries. Impact: the breaking registry transition now has a tested compatibility path from the old live registry.
- `[Recipe Discovery]` Captured the priority model that treats packaged pi-actors recipes as a standard library below ad hoc user-selected recipe files and below `~/.pi/agent/recipes/*.json`, with priority applying only to matching filename ids. Impact: override behavior now has a documented lens and a regression for standard-library versus user recipe precedence.
- `[Recipe Discovery]` Added source-level default tool exposure so the high-priority user recipe root can behave as the operator-managed tool set by default, while packaged/ad hoc recipes stay component-like. Impact: 0.16 keeps the discoverability advantage of the old tool-only registry without forcing a separate live tool config.
- `[Runtime]` Wired session-start tool loading to migrate the legacy registry, discover recipe-file tools from `~/.pi/agent/recipes` and packaged recipes, and register only active exposed recipes as runtime tools. Impact: the new recipe-discovered registry path is now active in runtime loading instead of only existing as standalone discovery/migration helpers.
- `[Registry]` Changed `register_tool` persistence to write/update/delete user recipe files under the recipe root instead of mutating the legacy JSON registry, while still activating the tool in the current session. Impact: newly registered tools now enter the 0.16 recipe-discovered registry directly.
- `[Docs]` Reworked tool-registry documentation, README examples, recipe docs, actor skill guidance, and prompt copy around recipe-file persistence, the user recipe directory as the default tool set, packaged recipes as standard-library components, and recipe files as the persistent tool surface. Impact: public guidance now matches the 0.16 runtime path instead of the old live JSON registry.
- `[Skill]` Added actors-skill guidance for same-name recipe priority, recipe-root-as-muscle-memory, usage counters, and an explicit cleanup rule for stale/default tools without automatic deletion or demotion. Impact: agents get the override model, sticky-tool tradeoff, and cleanup heuristic directly in the compact operational reference.
- `[Recipe Usage]` Added extension-maintained recipe launch metadata updates for user-owned runtime tools and direct async recipe starts, tracking `usage.calls` and `usage.last_called` without failure counters while leaving packaged standard-library recipes immutable, then documented the cleanup interpretation in recipe and tool-registry docs. Impact: the operator-managed recipe/tool set now accrues cleanup evidence for muscle-memory review from actual extension launches rather than manual agent bookkeeping.
- `[Runtime]` Added a best-effort user recipe-root watcher that debounces file changes and reloads recipe-backed tools during the active session, plus runtime-tool fingerprinting so repeated reloads do not re-register unchanged tools while changed definitions refresh, and stale recipe tools are removed from the active tool set on reload when their recipe disappears. Impact: newly created or edited valid recipe files can be connected without a full restart, without duplicate registration churn for unchanged recipes, while deleted recipe tools are deactivated even though host-level unregistration is still not available.
- `[Recipe Discovery]` Added a discovery summary helper and wired/documented `inspect target=recipes view=status|summary` to report active, shadowed, invalid, disabled, and diagnostic recipe entries. Impact: the registry inspection surface can explain why tools are present, hidden, broken, or disabled from the normal actor inspection tool.
- `[Backlog]` Reconciled 0.16 planning state after implementation of the core runtime path, usage counters, and reactive recipe reload behavior. Impact: remaining open work is now framed as hardening, inspection UX, and release validation instead of rediscovering already implemented pieces.
- `[Docs]` Normalized registry examples toward filename/tool ids that match the snake_case tool naming convention, avoiding mixed hyphen/underscore examples around `docs_review`, and aligned package image metadata with the local pi-actors banner. Impact: recipe identity, generated tool naming, and package presentation are less ambiguous in 0.16 guidance.
- `[Backlog]` Reconciled the recipe registry inspection surface after wiring the initial `inspect target=recipes` summary, then closed the active `0.16.0` release backlog by moving remaining non-blocking ideas to future curation, host-unregistration, discovery expansion, telemetry evolution, and opportunistic recipe-library sections. Impact: the backlog now distinguishes completed release scope from future follow-up work.

## 0.15.0: Packaged Actors Skill And Actor Vocabulary Cleanup

- `[Skill]` Reworked the packaged `actors` skill as a dense self-contained extension reference rather than a scenario catalog or changelog narrative, bundled the `swarm` methodology skill alongside it, synchronized packaged skill metadata versions with the package version, included `skills/` in the npm package contents, registered both skills in package metadata, and linked them from the README start points. Impact: fresh agents get compact practical coverage of pi-actors operation plus complementary multi-agent methodology without duplicating the two roles.
- `[Prompts]` Tightened the injected onboarding prompt into a shorter runtime bootstrap/reminder that avoids duplicating the skill and notes that README/docs are not automatically in context. Impact: session context stays compact while preserving operational lookup paths.
- `[Context]` Added a durable knowledge-surface separation convention for prompt, skill header/body, README, docs, and `AGENTS.md`. Impact: future edits have a clear role model for where each kind of pi-actors knowledge belongs and how it reaches the agent context.
- `[Backlog]` Reconciled task-first pipeline notes with the release-summary/review pipeline candidate in abstract terms. Impact: future pi-actors work can explore evidence preparation without tying the backlog to one completed release pass.
- `[Actor Tools]` Changed compact `inspect view=messages` and `message` tool output to use actor-message wording instead of public `event`/`delivery`/`outbox` labels. Impact: default tool output now reinforces the actor vocabulary while verbose JSON still exposes implementation details for diagnostics.
- `[Skill]` Reworded the packaged skill description to avoid extra frontmatter colons and replaced the compact two-branch Core Nouns sketch with an explicit two-path flow. Impact: skill metadata stays formatter-safe and the template→recipe→run versus template/recipe→tool relationship is easier to read.
- `[Recipe Library]` Added `utility-skill-summary` and routed `pipeline-release-readiness` through packaged skill evidence between package summary and validation. Impact: release readiness reports can verify skill metadata/package-version alignment, formatter-safe frontmatter, body size, and heading shape alongside changelog/package/validation evidence.
- `[Recipe Library]` Changed async-run operations recipes from public `message_file` inputs to `run_id` inputs, with the helper resolving implementation storage internally. Impact: packaged recipes no longer expose outbox paths as part of their public actor-operations surface.
- `[Recipe Library]` Added `coordinator-locker`, a long-lived actor recipe backed by `scripts/coordinator-locker.mjs` that manages a FIFO work queue, acquire/renew/release resource lease locks, a journal, and coordinator-directed actor messages, plus `utility-coordinator-lock-snapshot` for state inspection. Impact: future coordinated fanout recipes have a small local coordination cell instead of baking ad hoc queue/lock mechanics into each pipeline.
- `[Skill]` Clarified the actors skill's relationship to methodology skills and expanded it with a linked Recipe Navigator covering bundled coordination/service recipes, subagent atoms, pipelines, and utilities. Impact: the actors skill is now both the extension operation reference and the shortest agent-facing path to concrete packaged recipe files.
- `[Recipe Library]` Standardized all packaged async recipes to advertise `control.stop`, `control.cancel`, and `control.kill` in mailbox accepts. Impact: `inspect view=mailbox` now exposes the actor-native termination contract consistently across subagent atoms, coordinator cells, music, and pipelines.
- `[Recipe Library]` Removed concrete model-version defaults from packaged recipes, removed stale concrete model aliases from operator/docs examples, and added regressions that reject model-like defaults or provider/version aliases in recipe defaults and stale concrete model aliases in public guidance. Impact: reusable components stay policy-light and force the caller/agent to choose current model policy at launch instead of inheriting stale packaged aliases.
- `[Context]` Recompressed `BACKLOG.md` around current/future work only, added an 80/20 focus section for the remaining actor-vocabulary, recipe-policy, release-evidence pipeline, and utility-growth work, and promoted the backlog-is-planning rule into `AGENTS.md`. Impact: completed history stays in the changelog/docs while the backlog remains an actionable planning surface.
- `[Recipe Library]` Added `pipeline-release-summary`, an evidence-only release preparation pipeline that composes changelog, package, skill, and validation evidence into a release summary, risk checklist, and PR body draft artifact without commit, PR, merge, tag, publish, or other external release side effects. Impact: release-prep artifacts can be produced under pi-actors while gated release actions remain owned by release workflows.
- `[Docs]` Reworded remaining public README examples and the async-run operations pipeline prompt toward run-actor vocabulary instead of presenting async-run lifecycle wording as the primary operator concept. Impact: public guidance continues converging on `spawn`, `message`, `inspect`, and actor runs while low-level lifecycle language stays in implementation docs.
- `[Context]` Closed the active `0.15.0` backlog by moving completed actor-communication, component-policy, and utility-surface work out of open planning, leaving only future opportunistic work and the blocked branch-runner experiment. Impact: the release backlog now reflects no open release-blocking work.
- `[Skill]` Consolidated the bundled `swarm` methodology skill boundary by removing concrete pi-actors adapter examples and duplicate adapter/component docs from Swarm, keeping detailed MAWP mechanics in the dedicated reference instead of duplicating them in the general skill, and adding regressions that packaged Swarm markdown must not mention pi-actors runtime identifiers, package metadata must register every packaged skill, packaged skill markdown links must resolve, and the actors Recipe Navigator must link every bundled recipe file. Impact: Swarm can live inside this package while remaining portable methodology, and actors remains the shortest concrete path to packaged recipes.

## 0.14.3: Pipeline Termination Mailbox Consistency

- `[Recipe Library]` Added `control.cancel` and `control.kill` mailbox accepts to packaged async pipeline recipes that previously advertised only `control.stop`. Impact: `inspect view=mailbox` now exposes the full actor-native termination set consistently across high-level pipeline actors.
- `[Tests]` Expanded packaged recipe coverage so all async `pipeline-*` recipes must expose `control.stop`, `control.cancel`, and `control.kill`. Impact: future pipeline recipes cannot silently regress to partial termination mailbox contracts.

## 0.14.2: Release Readiness Package Evidence

- `[Recipe Library]` Added `utility-package-summary` evidence to `pipeline-release-readiness` between changelog extraction and validation. Impact: release readiness reports can consider package metadata and package contents summary without adding publish automation.
- `[Docs]` Updated task-first and recipe-library docs to describe the enriched release-readiness pipeline. Impact: the documented task-first candidate map now matches the implemented recipe composition.

## 0.14.1: Backlog Vocabulary Reconciliation

- `[Docs]` Reconciled backlog status text after the message-only inspection release. Impact: project context no longer claims `inspect view=events` is retained and describes operations snapshots as actor-message tails instead of event tails.

## 0.14.0: Message-Only Run Inspection

- `[Actor Tools]` Removed `inspect view=events` as a public compatibility alias. Impact: run actor message streams are inspected only with `inspect view=messages`, keeping the public observation vocabulary aligned with actor messages.
- `[Docs]` Updated README and async-run/actor-message docs to remove the events inspection view and point operators to `inspect view=messages`. Impact: examples and tool descriptions no longer teach the transitional events alias.

## 0.13.5: Actor Message Snapshot Wording

- `[Docs]` Replaced remaining task-first and recipe-library event-tail wording for async-run operations with actor-message tail terminology. Impact: operations guidance now matches the `message_file` recipe surface and `inspect view=messages` actor vocabulary.
- `[Utilities]` Updated the `recipe-utils.mjs run-ops-snapshot` usage text from `<event-file>` to `<message-file>`. Impact: helper diagnostics no longer teach the old public noun.

## 0.13.4: Interactive Recipe Termination Contracts

- `[Recipe Library]` Added actor-native `control.stop`, `control.cancel`, and `control.kill` mailbox accepts to interactive artifact/message/fanout recipes and the music player recipe. Impact: `inspect view=mailbox` now advertises the run termination messages that the actor runtime supports for these long-lived recipe actors.

## 0.13.3: Actor Vocabulary Cleanup

- `[Docs]` Removed remaining public FIFO/outbox phrasing from actor-message/template-recipe docs and runtime prompt guidance. Impact: agent and operator guidance now consistently describes `spawn`, `message`, and `inspect` without transport-specific vocabulary.
- `[Recipe Library]` Removed the legacy `event_file` default from async-run operations recipes. Impact: the recipe surface now uses only `message_file` for run actor-message inputs.

## 0.13.2: Async Run Actor Vocabulary Docs

- `[Docs]` Reframed `docs/async-runs.md` around actor messages and run-local control channels, keeping file names and transport details in implementation sections. Impact: the async-run standard now separates public `spawn`/`message`/`inspect` behavior from storage/transport mechanics more clearly.

## 0.13.1: Public Actor Vocabulary Docs

- `[Docs]` Replaced remaining public README and recipe-library wording that described run coordination as events, FIFO, or outbox paths with actor-message and run-local control-channel terminology. Impact: operator-facing docs now teach the actor vocabulary first while keeping transport details in the async-run implementation reference.

## 0.13.0: Actor-Native Control Surface

- `[Actor Messages]` Removed `runtime.cancel` and `runtime.kill` termination aliases from `message to=run:<id>`. Impact: run termination now uses only actor-native `control.stop`, `control.cancel`, and `control.kill`; runtime-prefixed control names are no longer treated as public API.

## 0.12.15: Run Operations Message File Vocabulary

- `[Recipe Library]` Renamed async-run operations recipe inputs from `event_file` to `message_file`, with legacy `event_file` retained only as an internal default fallback. Impact: public recipe args align with the actor-message vocabulary while existing value-based launches can still supply the old key.
- `[Recipe Utilities]` Renamed `run-ops-snapshot` output from `events` to `messages`. Impact: operations reports now describe run outbox records as actor messages instead of runtime events.

## 0.12.14: Actor Message Inspection Alias

- `[Actor Messages]` Added `inspect view=messages` for run actors, with `events` retained as a compatibility alias for the same outbox-backed actor messages. Impact: the public inspection vocabulary now matches the actor/message model while preserving existing event-oriented diagnostics.

## 0.12.13: Structured Run Operations Recommendations

- `[Recipe Utilities]` Changed `utility-run-ops-snapshot` recommendations from shell-like suggestion strings to structured `message` and `inspect` call objects. Impact: async-run operations reports now preserve the actor API shape directly and avoid reintroducing command-string parsing into coordinator handoffs.

## 0.12.12: Async Command Summary Hygiene

- `[Observability]` Kept async `command.done` summaries bounded while preserving full argv-shaped command details in event payloads. Impact: long prompted fanouts keep diagnostic fidelity without flooding coordinator follow-ups with huge command lines.

## 0.12.11: Recipe Import Diagnostics Hotfix

- `[Template Recipes]` Added regression coverage proving imported recipe nodes execute correctly under a repeated parallel parent (`imports` + `repeat` + object `template`). Impact: the suspected composition blocker is now guarded as supported behavior instead of relying on manual smoke interpretation.
- `[Observability]` Expanded command details in foreground execution results and async `command.start`/`command.done` events from executable-only labels to full argv-shaped launch strings. Impact: failed fanout branches no longer appear as misleading `pi && pi && ...` summaries when the real command was `pi -p --model ...` with a long prompt.
- `[Spawn]` Allowed the public `spawn` schema to accept inline object command-template configs, not only strings and arrays. Impact: agents can launch object-form templates with `parallel`, `repeat`, `failure`, and nested `template` directly through `spawn` as documented.

## 0.12.10: Actor Ownership and Recipe Operations

- `[Actor Messages]` Added actor-native `control.stop`, `control.cancel`, and `control.kill` handling for run termination while retaining `runtime.cancel` and `runtime.kill` as compatibility aliases. Impact: public examples can use the same control-message vocabulary declared by recipe mailboxes instead of preserving runtime action names.
- `[Actor Messages]` Added `inspect target=tool:<name>` support for registered tool actor status/schema contracts. Impact: tool actors can now be intentionally observed through the same actor vocabulary used to invoke them with `message to=tool:<name>`.
- `[Recipe Library]` Added `pipeline-artifact-bundle`, a task-first handoff pipeline that composes optional validation, deterministic artifact writing, machine-readable manifest generation, deterministic manifest writing, and an actor-message handoff. Impact: callers who explicitly want filesystem writes can produce paired artifact and manifest paths as one reusable bundle workflow.
- `[Component Recipes]` Aligned `subagent-tools` and `subagents-prompts` with the common subagent policy knobs for `model`, `thinking`, `tools`, and `output_format`. Impact: prompt launchers and prompt fanout can be tuned through the same public controls as the richer subagent atoms.
- `[Recipe Library]` Added `utility-run-ops-snapshot` and routed `pipeline-async-run-ops` through it so run summaries, event tails, and stale/terminal recommendations stay in one structured input. Impact: async-run operations reports no longer lose summary context before normalization and can suggest `inspect` or `control.stop` messages without executing them.
- `[Actor Messages]` Added `inspect target=coordinator` support for current-session run inventory. Impact: the coordinator actor can now be intentionally observed without spelling out the session id.
- `[Actor Messages]` Added `message to=session:<id>` support for run-owned session-directed follow-ups. Impact: explicit session checkpoints now use the same actor envelope as coordinator follow-ups while preserving run-owner checks.
- `[Actor Messages]` Hardened `message to=session:<id>` routing to require an owned sender run. Impact: unowned or cross-session runs cannot synthesize session-directed follow-ups.
- `[Actor Messages]` Applied coordinator-session ownership checks to addressed run, branch, and coordinator message routes when a session context is available. Impact: actor messages now fail closed before controlling or emitting from runs owned by another coordinator session.
- `[Actor Messages]` Applied the same coordinator-session ownership gate to direct `inspect target=run:<id>` views. Impact: explicit run inspection no longer leaks cross-session run details when the current session is known.
- `[Actor Messages]` Tightened `inspect target=coordinator` to require a current coordinator session instead of falling back to all runs. Impact: callers without session context must use explicit `session:<id>` or `session:all` inventory.

## 0.12.9: Actor Runtime Hotfix

- `[Async Runs]` Protected the `runs` state root from session-start temp pruning, tightened live-run status around owned runner processes, and kept non-Linux FIFO control usable without `/proc`-only checks. Impact: long-lived actors are less likely to disappear or be misclassified during startup and stale PID reuse is reduced on Linux.
- `[Actor Messages]` Preserved coordinator-bound actor message `body` and `metadata` through outbox parsing and follow-up formatting, with bounded body previews. Impact: checkpoint and decision messages reach the coordinator with the useful payload instead of only the summary line.
- `[Observability]` Reduced generic `command.done` follow-up noise by keeping successful final leaf completions diagnostic while still bubbling failures and in-flight parallel branch completions. Impact: long sequential pipelines no longer flood the launching coordinator with low-value leaf-completion messages.
- `[Output]` Moved truncated full-output files under `~/.pi/agent/tmp/pi-actors/outputs`. Impact: oversized tool output now follows the extension temp-directory contract instead of using system temp.

## 0.12.8: Usage Hint Documentation

- `[Docs]` Documented runtime actor-tool argument usage hints in README and tool-registry docs, and covered missing template-value hints separately from typed value errors. Impact: users and agents can discover the self-correction behavior without reading tests.

## 0.12.7: Tool Argument Usage Hints

- `[Tools]` Added compact usage hints to runtime actor-tool argument errors when typed normalization or placeholder resolution fails. Impact: if an agent supplies a wrong enum/type value or misses a required template value after schema validation, the error now shows the expected call shape with required and optional fields.

## 0.12.6: Documentation Example Alignment

- `[Docs]` Replaced remaining shader-ring recipe examples in registry and template-recipe docs with the concrete docs-review actor recipe example, aligned test fixtures, and changed async-run outbox docs to show actor message envelopes without public delivery knobs. Impact: public docs now consistently demonstrate useful actor wrapping and keep coordinator attention policy out of recipe-authored message examples.

## 0.12.5: README Actor Recipe Example

- `[Docs]` Replaced the placeholder shader-ring onboarding recipe with a concrete async docs-review actor recipe that includes typed args, mailbox metadata, and a real launch template. Impact: README onboarding now demonstrates actor wrapping instead of an abstract placeholder.

## 0.12.4: Actor Runtime Positioning

- `[Docs]` Reframed README and package metadata around `pi-actors` as an actor runtime and orchestrator for agent-managed local processes, while preserving the persistent actor-tool registry as one capability. Impact: new readers see how templates, recipes, mailboxes, messages, artifacts, and run state turn any trusted local process into an agent-controllable actor.

## 0.12.3: Package Metadata Hygiene

- `[Package]` Normalized npm repository metadata to the canonical `git+https://` URL form. Impact: npm publish no longer needs to auto-correct package metadata.

## 0.12.2: Registry Migration Notes

## 0.12.1: Actor Tool Registry Name

## 0.12.0: Rename to pi-actors

- `[Rename]` Renamed the package and current public surface from `@llblab/pi-auto-tools` / `pi-auto-tools` to `@llblab/pi-actors` / `pi-actors`, moved the persistent registry filename from `auto-tools.json` to `tools.json`, and moved runtime state defaults from `~/.pi/agent/tmp/pi-auto-tools` to `~/.pi/agent/tmp/pi-actors`. Impact: the package name now matches the actor API model introduced in 0.10-0.11, while the durable registry becomes the generic pi agent tools config.

## 0.11.0: Actor API Compression

- `[Actor Messages]` Added `tool:<name>` message routing to invoke executable pi tools through the same addressed envelope used for run, branch, and coordinator actors, added validated deterministic `utility-actor-message` wrapping for recipe-authored actor-message records with envelope-shaped public args and correlation/reply metadata, renamed the prompted message-producing recipe to `subagent-message`, aligned it with the same public field names, migrated artifact pipelines to use deterministic envelopes, and updated README/async/component/command-template docs, runtime prompt guidance, and music-player usage text to prefer actor `message`/`spawn`/`inspect` vocabulary for coordination examples. Removed recipe-level `events` delivery policy, recipe-authored delivery knobs, the public message-envelope `delivery` field, the duplicate recipe-authored `event` alias, stale `event` import aliases, the public `async_run` tool registration, and the music-player `event_delivery` recipe arg from the public surface so `mailbox` remains the single recipe message contract and runtime routing owns coordinator attention policy. Split generic atomic JSON persistence out of registry config so async-run state no longer depends on the registry-config domain. Impact: tool calls, diagnostics, runtime stop/kill, and recipe-authored message records participate in the actor/message protocol without adding another durable verb or relying on prompted JSON shape for deterministic pipelines, while local domain ownership stays clearer.
- `[Recipe Library]` Added mailbox metadata to all async packaged recipes, including prompt launchers, quorum, core subagent atoms, the review coordinator, and pipelines, with regression coverage requiring mailbox declarations for async packaged recipes. Impact: async subagent launchers and composed pipelines now advertise their basic control, completion, artifact, and domain-result message surface to `inspect view=mailbox`.

## 0.10.0: Actor Orchestration and Artifact Pipelines

- `[Actor Messages]` Began the 0.10 communication convergence with a draft actor/message protocol, pure address/envelope normalization helpers, recipe `mailbox` metadata, public `spawn`, `message`, and `inspect` tools for `run:<id>` actors as high-level adapters over async start/send/status/tail/events/artifacts/files, actor envelope fields on generic `command.done` and music-player track outbox events, coordinator-bound `message` routing through run outboxes, branch-addressed `message` routing through parent run mailboxes, and async-run docs/prompt guidance centered on `spawn`/`message`/`inspect`, mailbox preservation coverage, recipe validation summaries for mailbox declarations, and mailbox metadata on checkpoint/follow-up/event recipes, mailbox persistence in async run metadata, `inspect view=mailbox`, and route-aware default message delivery, artifact recipe mailbox metadata, and clarified prepared-vs-written artifact-report semantics, and deterministic `utility-artifact-write` support for accepted prepared artifacts, and an opt-in `pipeline-artifact-write` recipe for write-capable artifact flows, a successful `pipeline-artifact-write` smoke (`artifact-write-smoke-010`), `inspect` support for `session:<id>` run status, and `spawn` support for state/artifact metadata. Impact: the next API can consolidate actor creation, upward events, downward commands, and intentional inspection around addressed endpoints while existing async run transports remain implementation details.

## 0.9.0: Async Observability Polish

- `[Async Observability]` Ambient triangles now reflect active parallel branches inside a running async recipe, while still showing at least one triangle per active run. Impact: multi-agent fanout such as one run with three parallel subagents is visible as three active triangles instead of one.
- `[Async Observability]` Terminal `done` and `failed` transitions now send compact Markdown follow-up context with compressed artifact/run-file paths to the launching coordinator, while intentional `cancel`, `kill`, and control-stop completions remain synchronous-only. Documentation now centers the reactive control loop where upward outbox/follow-up events pair with explicit `async_run action=send` commands downward. Impact: successful async recipes bubble a top-level completion event back into the initiating agent turn without flooding context with repeated state-dir prefixes or duplicate stop notifications, and coordinators have a clear alternative to sleep-poll loops, and examples avoid sleep-then-status smoke patterns.
- `[Async Observability]` The generic async runner now emits `command.done` outbox events for leaf commands, with explicit recipe-level `events.command.done.delivery` controlling whether branch completions are stored, notified, or sent as follow-up context; packaged multi-agent fanout recipes default branch completion to `followup`. Impact: parallel subtask completion bubbles through the run outbox for multi-agent recipes without hardcoding transport calls or relying on hidden reserved args.
- `[Template Recipes]` Added recipe-level named `artifacts` for ordered artifact manifests, distinct from command-template `output` and default stdout. Impact: async completion and bubbled subtask events can report stable paths such as `report` and `summary`, including placeholder-derived artifact paths.

## 0.8.0: Semantic Recipe API

- `[Release]` Reframed the 0.8 line around semantic recipe inputs instead of leaking CLI fragments or historical node shapes. Impact: current docs focus on `async`, `parallel`, `when`, typed args, and recipe imports as the active API.
- `[Command Templates]` Replaced public execution `mode: "parallel"` with boolean `parallel: true` for command-template and recipe fanout. Impact: the execution API now matches `async: true` style boolean modifiers, and packaged recipes/docs/tests no longer use enum-like execution mode for a two-state choice.
- `[Recipe Design]` Reviewed remaining `mode`-named surfaces after the migration and removed the unused `utility-jsonl-tail` mode arg. Impact: execution mode became boolean, while multi-value user policy knobs such as merge mode, continuation mode, playlist output mode, and CLI `mode:enum(...)` examples remain enums because they are not reducible to true/false without losing names.
- `[Command Templates]` Added `{name??fallback}` nullish coalescing and `{name?truthy:falsy}` ternary placeholder selection, then migrated `utility-validate-recipe` from `all_flag:string` to `all:bool`. Impact: recipes can expose semantic values while mapping empty fallbacks or optional CLI strings without leaking raw flag fragments into public args.
- `[Command Templates]` Allowed numeric node control fields such as `timeout`, `delay`, and `retry` to read placeholder values, for example `timeout: "{timeout_ms}"`. Impact: recipes can expose configurable execution policy while keeping public arg names distinct from node field names.
- `[Docs]` Added explicit layer-ownership sections to command-template, template-recipe, and async-run standards. Impact: portable execution syntax, saved recipe configuration, and detached lifecycle primitives are now documented as separate layers with clear non-goals.
- `[Command Templates]` Added node-level `when` guards for conditional template execution. Impact: recipes can branch optional steps with semantic boolean inputs while skipped sequence nodes preserve stdin flow.
- `[Component Recipes]` Replaced raw `tool_args` CLI fragments with semantic `tools` inputs mapped through ternary placeholders. Impact: subagent component recipes expose tool access policy without making callers assemble `pi` CLI flag strings.
- `[Command Templates]` Removed the public `critical` alias in favor of `failure: "root"`. Impact: failure handling now has one explicit strategy surface instead of a boolean alias plus enum.
- `[Recipe Library]` Replaced the public `timeout` arg in `utility-validation-wrapper` with `timeout_ms:int`, then feeds it into node-level `timeout`. Impact: callers can configure execution bounds without reusing command-template control-field names as public args.

## 0.7.1: Recipe Library Hotfix

- `[Component Recipes]` Added `docs/component-recipes.md`, seed subagent component examples for review, verification, merge, quorum, checkpoint, follow-up, normalization, and one composed review coordinator. Impact: pi-auto-tools now has an explicit weak component-recipe contract for composing higher-level subagent coordinators without introducing a monolithic swarm DSL.
- `[Template Recipes]` Allowed recipe-envelope sequence templates to contain recipe import nodes and added packaged-example import resolution coverage. Impact: composed recipes can keep public args/defaults at the recipe envelope while sequencing imported component recipes.
- `[Component Recipes]` Expanded seed components with model/thinking/tool/output/evidence/risk policy knobs, added critic and judge atoms, and added review-readiness, quorum-review, and architect-coordinator pipeline examples. Impact: the toolkit now demonstrates both flexible atoms and second-order coordinator recipes.
- `[Component Recipes]` Added planner, evidence-map, contradiction-map, task-card, and conflict-report atoms; strengthened checkpoint/follow-up parameterization with resume and continuity policies; and added research-synthesis, checkpoint-continuation, and development-tasking pipelines. Impact: component composition now covers research, resumable/degraded handoff, and bounded implementation planning patterns.
- `[Recipe Library]` Promoted packaged recipes from `examples/recipes` to root `recipes`, moved the music-player helper to `scripts/music-player.mjs`, renamed the music recipe to `music-player.json`, and removed the parallel shell-wrapper variant. Impact: recipes are now treated as the standard library surface instead of isolated experiments, with one maintained Node.js music-player wrapper.
- `[Component Recipes]` Added artifact and event atoms plus `pipeline-artifact-report`. Impact: component pipelines now demonstrate durable artifact-shaped output and outbox-event-shaped handoff without requiring a live subagent smoke run.
- `[Recipe Library]` Added utility recipes for Markdown index listing, JSONL/event tailing, scoped validation commands, run-state file listing, changelog-head reading, and playlist scanning. Impact: the standard library now includes non-subagent operator utilities alongside coordinator components and pipelines.
- `[Recipe Library]` Added `scripts/recipe-utils.mjs` plus helper-backed utilities for run summaries, playlist building, and changelog section extraction. Impact: repeated utility parsing/listing logic now has one small maintained helper family instead of growing opaque recipe command strings.
- `[Recipe Design]` Added `docs/task-first-recipes.md` to derive high-level recipes from operator/coordinator tasks before filling missing atoms. Impact: standard-library growth now has a top-down design map alongside atom-first component expansion.
- `[Recipe Library]` Added `pipeline-release-readiness`, the first task-first high-level pipeline, composed from changelog extraction, validation wrapping, release review, and artifact reporting. Impact: release prep now demonstrates deriving a coordinator recipe from an operator task and reusing existing cells.
- `[Recipe Library]` Added git status/log utilities and `pipeline-repo-health`. Impact: repository-health reporting now has a task-first pipeline composed from local utilities, validation, normalization, and artifact reporting.
- `[Recipe Library]` Added `pipeline-async-run-ops`, composed from run summary, event tail, normalization, and artifact reporting cells. Impact: async run inspection now has a task-first operations pipeline without needing live subagent execution.
- `[Recipe Library]` Added `pipeline-docs-maintenance` and expanded `subagent-artifact` with a validation policy knob. Impact: documentation maintenance now has a task-first pipeline, and artifact-producing components can declare acceptance checks.
- `[Recipe Library]` Expanded playlist building with `paths|m3u|inline` output modes and added `pipeline-media-library`. Impact: media-library workflows now have a task-first pipeline and playlist utilities are more parameterized for playback or artifact use.
- `[Recipe Library]` Added `utility-artifact-manifest` backed by `scripts/recipe-utils.mjs`. Impact: utility recipes now include a safer structured transform that turns artifact paths into machine-readable JSON metadata.
- `[Recipe Library]` Updated `utility-run-summary` to derive live status from async-run `progress.json` and `result.json` instead of only static `run.json` metadata. Impact: operations and parallel utility smokes report completed and failed runs accurately after runner exit.
- `[Recipe Library]` Added `utility-package-summary` backed by `scripts/recipe-utils.mjs`. Impact: release-readiness and repository-health recipes can consume bounded package metadata without hand-written JSON parsing in recipe command strings.
- `[Command Templates]` Allowed object-valued nested templates to execute as nested command-template configs, including repeated imported recipe nodes. Impact: packaged coordinator recipes such as `subagent-review-coordinator` can fan out imported subagent components in parallel and continue through verifier, merger, judge, and normalizer stages.
- `[Recipe Library]` Added `scripts/validate-recipe.mjs` plus `utility-validate-recipe`. Impact: operators and agents can validate one saved template recipe or a directory of packaged recipes through the same recipe/run layer they use for other utility workflows.
- `[Async Runs]` Changed coordinator notifications to be driven by run-state file watcher events instead of a fast polling loop, while suppressing duplicate async notifications for already-handled `failed` and `cancelled` terminal states. Ambient run triangles now count unfinished async run instances rather than internal command-template branches; reload smoke confirmed concurrently started independent subagent runs show simultaneous triangles when held open. Impact: coordinators can start multi-agent runs, continue other work, and rely on exceptional terminal/outbox events to initiate follow-up rather than manually polling status in a loop.

## 0.7.0: Command Template Checkpoints

- `[Command Templates]` Added `failure: "continue|branch|root"` propagation, with `critical: true` retained as a backward-compatible root-abort alias. Impact: templates can stop only the current branch, keep sibling parallel branches alive, or abort the root explicitly.
- `[Command Templates]` Extended `retry` from leaf commands to sequence and parallel nodes. Impact: validator groups can retry as one bounded unit instead of requiring wrapper scripts for simple checkpoint loops.
- `[Command Templates]` Added `recover` cleanup templates between failed retry attempts, with fail-closed recovery semantics. Impact: retried groups can reset worktrees, clear generated files, or release local state before the next attempt without adding arbitrary loops or goto-style control flow.
- `[Command Templates]` Changed the default command timeout from 30 seconds to disabled. Impact: long-running templates no longer need `timeout: 0`; bounded commands should set an explicit positive `timeout` when they must fail closed.
- `[Command Templates]` Added typed `array` args, `{items[index]}` placeholder selection, `repeat: "{items.length}"`, and recursive placeholder resolution for defaults. Impact: repeated template nodes can derive fanout width and per-branch values from an agent-supplied array, enabling compact subagent fanout recipes.
- `[Template Recipes]` Split saved JSON definitions from async execution by adding explicit `name` and `async: true` semantics. Impact: recipe files can run foreground or detached, while async runs keep lifecycle/state/logs; file-backed recipes may rely on the filename as their canonical id.
- `[Async Runs]` Renamed the public async adapter from `template_job` to `async_run`, renamed public run selection to `run_id`, moved recipe lookup to `~/.pi/agent/recipes`, moved runtime state to `~/.pi/agent/tmp/pi-auto-tools/runs`, and renamed internal job modules/files to recipe/async-run language. Impact: the 0.7 API is intentionally breaking but now matches the template/recipe/run model before release.
- `[Tool Registry]` Removed legacy raw `job`/`recipe` launcher fields from registry loading; use `template` with optional `name` and `async` for co-located recipes. Impact: stale pre-0.7 launcher configs fail loudly instead of being silently normalized into the new API.
- `[Docs]` Split the old template-jobs umbrella into separate command-template, template-recipe, async-run, tool-registry, and experimental-recipe documents, then removed the obsolete compatibility page before release. Impact: each standard now has a dedicated reference instead of preserving stale umbrella terminology.
- `[Async Runs]` Allowed `failure` and `recover` as recipe envelope flags for inline or file-backed async runs, including placeholder derivation from recipe-level recovery templates. Impact: detached runs and async recipe tools can use the same checkpoint semantics as foreground registered tools.
- `[Async Runs]` Changed cancel/kill to signal the owned runner process group when available, with a pid fallback. Impact: background child processes such as audio players stop with the async run instead of being orphaned.
- `[Async Runs]` Classify stopped runs as `cancelled` or `killed` after the runner exits, and tailor terminal follow-up text for those statuses. Impact: operator-requested stops no longer look like unexplained `exited` runs.
- `[Async Runs]` Changed async management tool output from full JSON to compact text by default, with `verbose: true` preserving full JSON for diagnostics. Impact: start/status/cancel/list calls no longer flood agent context with internal runner metadata.
- `[Async Runs]` Added source metadata (`tool`, `recipe`, `recipe_file`) to run state and a `status` filter for `async_run action=list`. Impact: operators can distinguish music, timers, subagents, and other run categories in one shared async state root.
- `[Async Runs]` Downgraded cancelled-run terminal notifications from error to info and suppressed follow-up context for successful `done` and intentional `cancelled` transitions. Impact: happy-path async completions no longer interrupt the agent flow.
- `[Async Runs]` Ensured ambient status always shows at least one triangle per running async run, with additional triangles for reported active parallel branches. Impact: the footer reflects currently active run trees even while a runner has not reported branch-level activity yet.
- `[Async Runs]` Added `async_run action=send` for newline-delimited messages to a running recipe's Unix FIFO at `<state_dir>/control.fifo`. Impact: tool calls can control long-running scripts through a simple recipe-local IPC endpoint on Linux, macOS, or WSL without adding a second recipe or a workflow engine.
- `[Async Runs]` Added script-authored outbox events through `<state_dir>/outbox.jsonl`, `async_run action=events`, and optional coordinator-scoped `notify`/`followup` delivery. Impact: async recipes can report state changes back to the launching agent without hidden tool calls, schedulers, or a second execution language.
- `[Template Recipes]` Added recipe-layer `imports` with cycle checks, `{ "name": "alias" }` template nodes, `{alias.defaults.key}` / `{alias.values.key}` references, missing-value fallbacks, small ternaries, and command-template-shaped imported recipe typing. Impact: file-backed recipes can compose other recipes and reuse their value containers without making command-template core depend on the recipe registry or async-run lifecycle state.
- `[Experimental Recipes]` Replaced the packaged background music example with paired controllable music player recipes for shell and Node.js wrappers. Impact: operators can register async `music_player_sh` or `music_player_mjs` playback for files, URLs, directories, and playlists, then control play, pause, next, previous, status, and stop by run id through `async_run action=send`.
- `[Experimental Recipes]` Added `music-player.mjs` as a Node.js alternative to the shell music-player wrapper with the same CLI, playlist expansion, state files, and FIFO control contract. Impact: the paired recipe files differ only by executable wrapper and show that recipes can point directly at shell scripts or Node.js scripts.
- `[Experimental Recipes]` Added direct first-argument control commands (`pause`, `resume`, `toggle`, `next`, `previous`, `stop`, `status`) to both music-player wrappers. Impact: scripts can be driven as `music-player.sh next <state-dir>` while the recipe still uses `play` explicitly to start playback.
- `[Experimental Recipes]` Renamed the public music-player input from `playlist` to typed `source:string` and documented directory scanning. Impact: callers can pass `source="~/Music"`, a file, URL, playlist file, or inline list without creating a playlist first.
- `[Experimental Recipes]` Declared the music-player `command` as a typed enum recipe arg and moved its default `play` into recipe `defaults`. Impact: the recipe metadata now keeps command type/defaults with the rest of the public template contract while the recommended registered tool can still expose the narrower playback surface.
- `[Experimental Recipes]` Added music-player track-change outbox events with configurable `event_delivery` defaulting to `log`. Impact: agents can inspect current/previous track changes with `async_run action=events` and opt into live notifications or follow-up context only when desired.
- `[Experimental Recipes]` Added `subagent-prompt.json`, an async no-tools pi subagent recipe with explicit string args. Impact: operators have a packaged example for starting a non-interactive subagent as a detached run and inspecting it through normal async-run lifecycle tools.
- `[Experimental Recipes]` Added `subagent-tools.json`, an async pi subagent recipe with a required explicit `tools:string` allowlist. Impact: operators can start tool-enabled subagents without weakening the safer no-tools default example.
- `[Experimental Recipes]` Added `subagents-prompts.json`, an async parent recipe that repeats one imported `subagent-prompt.json` node over a public `prompts:array` input. Impact: the release package includes a concrete example of recipe import composition that runs parallel subagents as one async run while keeping concrete prompts configurable at tool call time.
- `[Safety]` Added lightweight high-risk template warnings for shell interpreters, eval modes, destructive removal, and broad filesystem mutation. Impact: operators see trust-boundary warnings in registration/runtime details without blocking existing trusted tools.
- `[Docs]` Folded legacy job-primitives notes into async-run and template-recipe docs and removed the internal Russian collaborative-subagents research brief from the release package. Impact: release docs have clear async/recipe sources of truth and only polished English public documentation.
- `[Docs]` Added a collaborative subagent branch adapter pattern for async runs, including scope-file handoff, parallel runner recipe shape, coordinator responsibilities, degraded partial success, and the boundary between pi-auto-tools runtime state and swarm/project policy. Impact: operators can prototype isolated branch subagent runs without turning pi-auto-tools into a swarm orchestrator.
- `[Docs]` Polished release onboarding around the template/recipe/run layering and added an async parent recipe example composed from imported recipe definitions. Impact: new operators can see how imports compose reusable recipes without implying nested async runs or a workflow engine.
- `[Prompts]` Reworked the onboarding system prompt to teach the local-first cybernetic tool-memory lens, template/recipe/run layers, recipe imports, async fanout, tool registration, and first docs/examples to inspect. Impact: agents with the extension loaded can discover the format and start using async recipes/subagents with less repository-specific prompting.

## 0.6.1: Pi SDK Scope Hotfix

- `[Packaging]` Migrated the pi SDK peer dependency and extension type imports from the legacy `@mariozechner/pi-coding-agent` scope to `@earendil-works/pi-coding-agent`. Impact: package metadata matches the current Endrilla/Earendil pi package namespace.

## 0.6.0

- `[Typed Args]` Added progressive typed command-template argument declarations for `string`, `path`, `int`, `number`, `bool`, and `enum(...)` compact forms in both `args` and inline template placeholders. Impact: registered tools can expose narrower generated schemas and validate/normalize runtime values without requiring JSON Schema authoring or separate `args` metadata for simple templates.
- `[Compatibility]` Kept existing untyped `args` and shorthand defaults fully compatible while normalizing typed shorthand such as `timeout:int=60000` into canonical stored declarations plus `defaults`. Impact: existing `auto-tools.json` entries continue to load unchanged.
- `[Docs]` Documented typed args in the command-template standard, tool registry guide, README, and backlog state, including metadata-first and inline-first authoring styles. Impact: operators can adopt typed declarations incrementally while choosing the most readable shape for each tool.

## 0.5.6: Coordinator-Scoped Job Notifications Hotfix

- `[Job Observability]` Scoped async job ambient status and terminal follow-up context to the agent session that started the job. Impact: multiple pi agents sharing the same job state root can run independent async jobs without receiving each other's completion messages or sub-agent indicators, while explicit `status`/`tail` inspection by job id remains available.
- `[Template Jobs]` Added `template_job action=kill` as a forceful `SIGKILL` escape hatch for stuck owned job runners, with the same cwd/runner ownership checks as graceful `cancel`. Impact: operators can recover from unresponsive detached jobs without unsafe broad process killing.
- `[Release]` Added a tag-triggered GitHub Actions release workflow that verifies the `vX.Y.Z` tag matches `package.json`, extracts the matching `CHANGELOG.md` section, and publishes a GitHub Release automatically.
- `[Backlog]` Clarified that typed command-template argument declarations must be progressive: current untyped `args` declarations continue to work unchanged while typed forms are added.

## 0.5.5

- `[Template Job Shape]` Allowed job recipe files to place command-template node flags such as `mode`, `timeout`, `retry`, `critical`, `args`, and `defaults` at the job top level beside `job`. Impact: parallel jobs can use the compact shape `{ "job": "name", "mode": "parallel", "template": [...] }` without an unnecessary nested template wrapper.
- `[Template Job Defaults]` Clarified that `state_dir` is optional and defaults to the extension job-state directory derived from the job id. Impact: recipe files only need `job` and `template` unless they intentionally override state placement.
- `[Command Template Repeat]` Added `repeat` expansion with zero-based `{index}`, wrapped zero-based `{prev}`/`{next}`, `{repeat}`, underscore-padded forms such as `{_index}`, and limited arithmetic expressions such as `{_(index+1)}`. Impact: repeated parallel or sequence templates can be written once instead of copy-pasting near-identical branches while keeping human numbering explicit.

## 0.5.4

- `[Co-located Job Recipes]` Allowed registered tool entries to include job envelope fields directly when they also define `template`. Impact: operators can keep small or local job recipes in `auto-tools.json` without introducing `job.tool` cycles or a separate recipe file.
- `[Job Recipe Args]` Derived tool args from available file-backed and co-located job recipe templates when `args` is omitted. Impact: job recipes keep the same optional `args`/`defaults` behavior as command templates while explicit `args` remains an override.
- `[Docs]` Split the synchronous Command Template Standard from the async Template Job Standard. Impact: command templates remain portable and backwards-compatible across extensions, while jobs are documented as an optional async extension.

## 0.5.3

- `[Job Recipe References]` Replaced registered-tool `job` bindings with `template` job recipe references. Impact: the registry has one executable binding field, job files must own a `template`, and job recipes can no longer point back to tools.
- `[Runtime Boundary]` Enforced the `tool → template → job → template` graph across runtime, docs, and tests. Impact: jobs stay lightweight async envelopes, cyclic shortcuts such as `tool.job` and `job.tool` are rejected, and job recipe tools keep their public args explicit.

## 0.5.2

- `[Job Launch Tools]` Added job-backed registered tools. A tool may now define `job` instead of `template`; calling it starts the named template-job recipe asynchronously and returns job metadata. Impact: heavyweight agent fanout can keep `template(mode: "parallel")` inside `~/.pi/agent/jobs/*.json` while exposing a compact callable tool.
- `[Docs]` Documented the `tool → job recipe → template(mode: "parallel")` model across README and adapter docs. Added compact operator onboarding and the `task` vs `template` vs `job` distinction. Impact: job recipes can become the source of truth for async agent scenarios instead of duplicating large templates in tool definitions, and new operators get the job mental model without reading every subsystem note.

## 0.5.1

- `[Job Observability]` Made detached job status triangles use runner-reported active command counts across all running jobs instead of only process-tree probing. Impact: async parallel jobs keep stable per-sub-agent indicators while work is active, with the animation wave moving across the current aggregate set.
- `[Docs]` Clarified that template jobs own async lifecycle and ambient sub-agent visibility, while command templates still own sequence and parallel execution shape. Impact: agentic fanout should use `job(template(mode: "parallel"))` instead of blocking foreground orchestration.

## 0.5.0

- `[Command Templates]` Added `mode` for template object nodes, with `sequence` as the default and `parallel` for concurrent child execution. Object-form examples and persisted tool entries now keep `template` last, with regression coverage for serialization order. Parallel nodes now expose soft-quorum branch labels, statuses, and coverage details. Added compact per-node `delay` in milliseconds for launch pacing without scheduler semantics. Impact: one `template` property now describes sequential and parallel command trees with stable flag-first reading, graceful degradation, optional staged launch, and no separate workflow DSL.
- `[Template Jobs]` Added the unified `template_job` action tool for detached template job lifecycle: start, status, tail, list, and cancel. Jobs use state files, log files, a thin runner process, and stale-state cancellation guardrails. `template_job action=start` can start from a template job JSON file, an inline command template, or a registered auto-tool name. Job state now defaults to `~/.pi/agent/tmp/pi-auto-tools/jobs` and stale temp entries are pruned on session start. Impact: Swarm-style async orchestration can move generic process observation into pi-auto-tools while domain quorum semantics stay in Swarm.
- `[Job Observability]` Added ambient interactive UI status for active sub-agent count and compact completion events for detached jobs. Removed persistent prompt-area widgets and done/exited counters. The running indicator now shows one `▷` per concrete sub-agent with a faster moving dim `▶` wave, single-subagent blink, and a late-sorting status key. Impact: long-running swarms are visible while active, then become actionable context only when they finish.
- `[Command Template Standard]` Folded template job and temp-directory primitives into `docs/command-templates.md`; `docs/job-primitives.md` is now the pi-auto-tools adapter note. Impact: the portable standard is self-contained and consumers point inward instead of chaining across external standards.
- `[Template Job Library]` Added `~/.pi/agent/jobs/*.json` as the reusable template job library. Kept reusable recipes as documentation guidance instead of packaged root files because model and tool names are local policy. Impact: async recipes can be reused compactly without expanding tool config or shipping operator-specific examples.
- `[Registry Tools]` Made `register_tool` callable without args to return a compact list of registered auto-tools. Impact: agents can inspect the extension registry without reading `auto-tools.json` directly.
- `[Registry Activation]` Made every successful `register_tool` call activate all registered auto-tools in the current session. Impact: registered tools stay fresh and callable immediately after list, register, update, or delete operations.
- `[Release Validation]` Added `npm run validate` for CI and release checks. Impact: TypeScript, extension import, tests, and dry-run packing are available through one command.
- `[Docs]` Reworked README and job docs around a compact mental model: command, command template, registered tool, template job. Impact: the new async job concept is easier to explain without implying a scheduler or second workflow language.

## 0.4.0

- `[Command Templates]` Prepared the 0.4.0 runtime profile for the current portable command-template contract: default 30s command timeout, per-step retry propagation, fail-open composition for non-critical failures, and `critical: true` abort semantics. Impact: registered auto-tools now follow the portable command-template runtime profile.
- `[Docs]` Cleaned the backlog and synchronized README plus command-template docs with the strengthened 0.4.0 contract. Impact: release notes, open work, and user-facing runtime semantics now describe the same behavior.

## 0.3.0

- `[Architecture]` Renamed the command-template domain from `lib/templates.ts` to `lib/command-templates.ts` and moved auto-tools-specific arg/schema helpers into `lib/schema.ts`. Impact: the portable standard stays copyable while registry-specific schema derivation remains local.
- `[Command Templates]` Migrated runtime helpers to the current shared command-template standard: string shorthand configs, inline `{arg=default}` defaults, derived tool args, missing-value errors, relative executable expansion, sequence expansion, direct execution with stdin, and timeout escalation. Impact: `pi-auto-tools` now follows the portable command-template regression surface, loads current inline-default `auto-tools.json` entries without `name`/`label`/`args`/`defaults`, and can run multi-step template-backed tools.
- `[Registry]` Canonical persisted object entries now omit redundant `name` and `label`; object keys supply tool names, and runtime labels derive from tool names. Impact: `auto-tools.json` follows the command-template standard more closely while legacy `name`/`label` fields are accepted and normalized away.
- `[Docs]` Harmonized the portable command-template standard wording, using `template`/`args`/`defaults`, command-arg terminology, and `{file}` as the canonical local file path arg. Impact: the docs describe the integration contract without `argv`, `command`, or `{filename}` ambiguity.

## 0.2.1

- `[Docs]` Split command-template documentation into a portable standard core (`docs/command-templates.md`) and local registry adaptation (`docs/tool-registry.md`). Impact: the shared command-template contract can be copied across extensions without coupling their internals, while `pi-auto-tools` keeps its registry storage shape documented separately.

## 0.2.0

- `[Breaking Registry]` Replaced script-backed persistent tools with template-backed command registration. Tools now store `template`, named `args`, and optional `defaults`; legacy stored `script` entries are rejected with explicit migration guidance.
- `[Command Templates]` Standardized split-first invocation: templates are split into shell-like argv tokens before placeholder substitution, then executed through `pi.exec` without shell evaluation. Placeholder values containing spaces remain single argv values.
- `[Register Tool]` Updated `register_tool` to create, update, and delete template-backed tools, preserve existing templates on metadata/default updates, block reserved/external conflicts, persist atomically, and register tools immediately for the active session.
- `[Runtime Output]` Preserved bounded context output for registered tools: stdout is formatted for the agent, large outputs are tail-truncated, full output is saved to temp files, and command failures include useful stderr/stdout sections.
- `[Architecture]` Refactored the extension into a flat `/lib` Domain DAG with `index.ts` as a small namespace-domain composition root. Core domains now cover templates, args/identity, config, registry mutations, runtime coordination, tool definitions, output, prompts, paths, and execution.
- `[Packaging & Validation]` Removed the runtime `typebox` dependency from schema assembly, made `npm run check` import the extension entrypoint, added focused domain and architecture-guard tests, and verified package contents with dry-run packing plus live post-reload smoke.
- `[Docs]` Added command-template documentation as a portable standard, condensed README into a feature/usage format, documented skill-script and sub-agent registration examples alongside their resulting `auto-tools.json` state, documented `{file}` as the canonical local file path placeholder, and reset `BACKLOG.md` after all open work reached validated stop conditions.

## 0.1.1

- `[Registry]` Shipped the script-backed persistent tool registry. Impact: pi can register, update, delete, persist, and auto-load trusted local script tools from `~/.pi/agent/auto-tools.json`.