@llblab/pi-actors 0.58.0 → 0.58.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/AGENTS.md +5 -5
  2. package/BACKLOG.md +1 -1
  3. package/CHANGELOG.md +12 -1
  4. package/README.md +37 -35
  5. package/dist/lib/draft-sleep.js +3 -3
  6. package/dist/lib/extension-runtime.js +7 -2
  7. package/dist/lib/pi.js +1 -1
  8. package/dist/lib/prompts.d.ts +3 -3
  9. package/dist/lib/prompts.js +10 -9
  10. package/dist/lib/recipes-references.js +7 -7
  11. package/dist/lib/registry.js +27 -24
  12. package/dist/lib/review-control.js +1 -1
  13. package/dist/lib/run-delivery.d.ts +1 -1
  14. package/dist/lib/run-delivery.js +19 -9
  15. package/dist/lib/run-evidence-policy.js +2 -2
  16. package/dist/lib/runtime.d.ts +3 -0
  17. package/dist/lib/runtime.js +24 -10
  18. package/dist/lib/tool-review-scheduler.js +7 -7
  19. package/dist/lib/tools-access.js +1 -1
  20. package/dist/lib/tools-inspect.js +10 -10
  21. package/dist/lib/tools-message.d.ts +1 -1
  22. package/dist/lib/tools-message.js +10 -10
  23. package/dist/lib/tools-register.d.ts +3 -3
  24. package/dist/lib/tools-register.js +4 -4
  25. package/dist/lib/tools-response.d.ts +1 -1
  26. package/dist/lib/tools-response.js +27 -28
  27. package/dist/lib/tools-spawn.js +1 -1
  28. package/dist/lib/tools.d.ts +7 -0
  29. package/dist/lib/tools.js +25 -0
  30. package/dist/skills/actors/SKILL.md +29 -21
  31. package/dist/skills/actors/references/diagnostics.md +11 -11
  32. package/dist/skills/actors/references/persistent-tools.md +19 -15
  33. package/dist/skills/actors/references/recipes.md +1 -1
  34. package/dist/skills/actors/references/runs.md +8 -8
  35. package/dist/skills/music-player/SKILL.md +4 -4
  36. package/dist/skills/music-player/scripts/playback.mjs +1 -1
  37. package/dist/skills/recipe-memory/SKILL.md +7 -7
  38. package/docs/README.md +2 -2
  39. package/docs/actor-inspector.md +1 -1
  40. package/docs/agent-experience.md +5 -6
  41. package/docs/async-runs.md +13 -13
  42. package/docs/capability-memory.md +11 -56
  43. package/docs/coordinator-delivery.md +2 -2
  44. package/docs/inspection.md +21 -21
  45. package/docs/output-projection-map.md +1 -1
  46. package/docs/releasing.md +1 -1
  47. package/docs/run-supervision.md +21 -21
  48. package/docs/tool-registry.md +46 -21
  49. package/docs/windows-process-observation.md +1 -1
  50. package/lib/draft-sleep.ts +3 -3
  51. package/lib/extension-runtime.ts +7 -5
  52. package/lib/pi.ts +1 -1
  53. package/lib/prompts.ts +10 -9
  54. package/lib/recipes-references.ts +7 -7
  55. package/lib/registry.ts +26 -24
  56. package/lib/review-control.ts +1 -1
  57. package/lib/run-delivery.ts +22 -11
  58. package/lib/run-evidence-policy.ts +2 -2
  59. package/lib/runtime.ts +26 -11
  60. package/lib/tool-review-scheduler.ts +7 -7
  61. package/lib/tools-access.ts +1 -1
  62. package/lib/tools-inspect.ts +10 -10
  63. package/lib/tools-message.ts +10 -10
  64. package/lib/tools-register.ts +4 -4
  65. package/lib/tools-response.ts +25 -25
  66. package/lib/tools-spawn.ts +1 -1
  67. package/lib/tools.ts +28 -0
  68. package/package.json +1 -1
  69. package/skills/actors/SKILL.md +29 -21
  70. package/skills/actors/references/diagnostics.md +11 -11
  71. package/skills/actors/references/persistent-tools.md +19 -15
  72. package/skills/actors/references/recipes.md +1 -1
  73. package/skills/actors/references/runs.md +8 -8
  74. package/skills/music-player/SKILL.md +4 -4
  75. package/skills/music-player/scripts/playback.mjs +1 -1
  76. package/skills/recipe-memory/SKILL.md +7 -7
@@ -18,74 +18,29 @@ The product goal is useful procedural memory with a selective tool interface, no
18
18
 
19
19
  ## Current Baseline and Its Limits
20
20
 
21
- - `lib/tools-local.ts` awaits synchronous Recipe execution, but an async tool calls `startRun` and returns launch metadata. The eventual Actor result is separate; tool registration does not itself launch an Actor.
22
- - `lib/async-runs.ts` also permits ordinary non-singleton Recipes without `async: true` through the public `spawn` path. The flag does not divide all capabilities into foreground-only and background-only classes.
23
- - `lib/tools-spawn.ts` captures inline-template launches as drafts with `async: true`. It does not capture maintained/file Recipe launches through that draft path. Filtering automatic tool promotion to sync alone would exclude this existing capture stream; ordinary foreground commands are not automatically captured by that mechanism.
24
- - `lib/runtime.ts` discovers the user Recipe root with `defaultTool: true`; `lib/recipes-discovery.ts` exposes valid enabled entries by location, not by sync/async. Active Skill components already demonstrate reusable Recipes without automatic tool exposure.
25
- - `lib/draft-review.ts` admits only promote/discard decisions. `lib/draft-sleep.ts` derives promotion from unchanged immutable captured Recipe content. Review does not generalize a hard-coded mission into a new parameterized capability.
26
- - `lib/review-projection.ts` gives automatic reviewers value-free contract shape, risk labels, usage counts, and batch-local content-equality groups. It excludes commands, descriptions, argument names/values, canonical names, and paths. Those observations cannot by themselves establish a capability's purpose, a meaningful semantic name, or future task usefulness.
27
- - `lib/recipes-usage.ts` records launches and lineage, not successful task completion or the coordinator's acceptance of a useful result. A launch count is not outcome evidence; a command exit code alone would not prove task success either.
21
+ Current user-root discovery exposes valid enabled direct Recipes by location, while active Skill components already provide reusable capabilities without automatic tool exposure. Ordinary registration supports both execution modes, and public `actors_run_spawn` accepts ordinary non-singleton Recipes without `async: true`; the flag is not a foreground-only restriction. Inline-template `actors_run_spawn` capture produces async drafts rather than capturing maintained/file Recipe launches, so a sync-only promotion rule would exclude that capture stream.
28
22
 
29
- These are limits on the conclusions the current mechanism supports, not permission to bypass its confidentiality projection or discard its transaction protections.
23
+ Automatic review sees value-free shape, risk labels, launch counts and batch-local content-equality groups, not commands, descriptions, argument names/values, canonical names/paths or accepted outcomes. Its current promote/discard executor preserves captured executable content rather than generalizing a mission. Usage records launches and lineage, not successful task completion. These limits neither authorize bypassing confidentiality nor justify discarding a capability whose usefulness remains unknown.
30
24
 
31
25
  ## Read-Only Inventory Checkpoint
32
26
 
33
- Retained definitions belong under `~/.pi/agent/recipes/library`; the tool root remains its existing direct `.json`/`.md` files. This separation also fails safely on older hosts whose nonrecursive tool discovery ignores the library directory, unlike an unknown opt-out field that an older host could ignore. No new Recipe field or logical-reference namespace is introduced.
27
+ The retained library stays outside nonrecursive tool-root discovery, including on older hosts. Directory separation fails safely where an unknown Recipe opt-out field could be ignored. No new Recipe field or logical-reference namespace is introduced.
34
28
 
35
- Use the same management surface:
36
-
37
- ```text
38
- inspect target=recipes view=summary
39
- inspect target=recipes view=summary verbose=true
40
- ```
41
-
42
- Compact output adds `retained` separately from root `active` candidates and drafts. Verbose/details contains `retained` rows with exact file paths, execution mode when the definition resolves, invalid/disabled state and diagnostics, plus `retained_diagnostics`. Root and retained definitions resolve in the same active Skill context. This read does not create directories, mutate Recipes/usage, register tools, or launch Actors. A stored row is not evidence of review, a callable tool, or a running Actor. Empty/missing library is an empty inventory, not an instruction to initialize one.
43
-
44
- A valid enabled row's exact file path can be reused through existing `spawn recipe=<path>` with its required caller values, or explicitly specialized through existing `register_tool from=<path>`. Invalid/disabled entries remain visible for diagnosis, not recommended for execution. Running instances remain under `inspect target=runtime view=runs` and `run:<id>`; tool activation/schema remains under `tool:<name>`. The inventory is not an alternate Run or activation registry.
45
-
46
- Use the explicit retention operation below rather than hand-populating the live registry or moving existing tools. Source/packed acceptance is separate from reloading an already running host; a loaded older tool schema does not acquire the new input automatically.
29
+ Use `actors_inspect target=recipes view=summary` and `verbose=true` for retained paths and diagnostics. The [inspection contract](./inspection.md) owns views and coverage; the [tool registry](./tool-registry.md#retain-a-new-capability-without-tool-exposure) owns the current save/discover/reuse workflow. Inventory is storage evidence, not review, callability or a running Actor, and never initializes an absent library.
47
30
 
48
31
  ## Explicit Persistence Contract
49
32
 
50
- Status: Implemented for explicit create-only retention; automatic lifecycle remains separate.
51
-
52
- The existing `register_tool` persistence owner accepts an optional Boolean **input** `expose`. This is not a Recipe field or a new tool/registry. `kind: retained_recipe` and `activation: not_requested` distinguish successful retention from failed tool activation.
53
-
54
- - **Omitted or true:** Preserve current tool-root persistence, source modes, update/delete behavior, activation and callability proof.
55
- - **False:** Save a new named definition under `recipes/library/<name>.json` without requesting host registration, changing the active-tool set, or launching work. A name and exactly one `template` or `from` source are required. Apply existing name/reserved-name and effective typed-argument/default admission; sync/async is not a selection filter.
56
- - **References, not relocation:** `from` persists the existing compact logical/file delegation, retaining the source's origins, imports, async, artifacts and Control. A retained wrapper is not a self-contained backup of its source. Reject direct references whose selected source is in managed disposable drafts rather than create an entry knowingly dependent on draft disposal. Apply the same owning resolver/lifetime check to Recipe-valued leaves in authored template graphs, not just the `from` spelling. This is not a transitive lifetime guarantee for arbitrary external files or their dependencies. `template` authors new content at its final library location. No existing Recipe is moved, rewritten or generalized.
57
- - **Create-only first slice:** Retained `update=true`, null/empty-template deletion, and `draft` source mode fail before persistence. They need explicit source-preservation, CAS/recovery and dependency contracts before becoming supported; do not fall back to active-tool mutation. A duplicate retained stem in either JSON or Markdown is a conflict, not permission to shadow or overwrite it. A tool-root entry with the same stem remains a distinct entrypoint and is not modified.
58
-
59
- Explicit flow (supply the capability's required caller values):
33
+ The implemented create-only operation is `actors_tool_register expose=false` with a new name and one template/from source. Omitted/true keeps ordinary registration. The [tool registry](./tool-registry.md#retain-a-new-capability-without-tool-exposure) owns supported inputs, source preservation, conflicts, mutation fences and withdrawal limits; this design does not define a second persistence path.
60
34
 
61
- ```text
62
- register_tool name=changes_review from=swarm/lens-review expose=false
63
- inspect target=recipes view=summary verbose=true
64
- spawn recipe=<exact retained path> values=<caller-owned inputs>
65
- register_tool name=changes_review from=<exact retained path>
66
- ```
67
-
68
- The last step deliberately creates a compact wrapper in the ordinary tool root. It does not copy the executable graph or move the retained definition. `callable_now` and actual tool invocation still need the existing proof. Removing an admitted exposed wrapper through the existing deletion path leaves the retained source intact; this does not turn deletion of an old standalone tool into safe retention. Active Runs retain their original execution contract and are not stopped by wrapper withdrawal.
35
+ The management path is **save deliberately → find through Recipe inspection → reuse the exact Recipe reference → expose explicitly when useful → withdraw only the wrapper when appropriate**. Moving executable sources, converting existing tools/drafts, retained updates/deletion and automatic transitions require separately admitted contracts. Source/package acceptance does not reload an older host or authorize live portfolio changes.
69
36
 
70
37
  ### Receipt and Failure Truth
71
38
 
72
- A successful retain receipt must distinguish **retention** from failed activation: `kind: retained_recipe`, `result: retained`, `persisted: true`, `resolved: true`, `validated: true`, and `activation: not_requested`, plus the exact retained Recipe path and effective required/optional argument names. It must not claim a global `callable_now: false` or `active_tool: false`: a separately exposed tool with the same name may already be callable. The retained branch never calls the host registration/activation ports, and the receipt's next action is read-only Recipe inspection rather than repair/reload advice. This is an extension of the receipt contract, not reconstruction of missing host state.
73
-
74
- Exact paths and selected metadata must use the existing whole-value YAML/omission budget, with full structured details preserved. No executable body, secret-bearing defaults, source installation root or invented semantic assessment is added to the receipt. Storage/validation do not prove review or useful task completion.
75
-
76
- Preflight validates mode/type/source/size and resolves the effective contract before creating library state. The serialized candidate obeys the existing 1 MiB per-Recipe bound even when admission uses an in-memory authored candidate. Operation selection preserves the existing name/source guard order and releases its tool-name reservation before retention locks are acquired. Persistence uses the existing canonical mutation-lock/atomic-write owner, with root → library → target ordering, regular non-symlink files, root identity/containment rechecks and JSON/Markdown conflict detection at the commit boundary. Exclusive publication links complete staged bytes without overwriting a competing creator; an unsupported filesystem refuses without a replacement fallback. Do not infer filesystem sandboxing or hostile-writer exclusion from cooperative locks.
77
-
78
- The first slice has no prior retained bytes to overwrite. It must preserve any competing/pre-existing entry and re-admit its own exact persisted candidate before returning success. Rollback may remove only its own proven unchanged candidate under the original root/target fences; an uncertain replacement, release or notification failure preserves effect uncertainty and original causes rather than blindly deleting or replaying. The retained failure boundary encloses the whole root-lock operation, including post-publication release; exact original or aggregate rejections remain its private cause. Ordinary registration keeps its existing rollback and callback behavior; the retained branch is not a reason to restyle or reorder unrelated guards.
79
-
80
- Retention itself records no launch, success, review or fabricated usage. There is no automatic expiry, background retention loop or live portfolio migration in this slice. Aggregate retention bounds and expiry/disposal remain required before future automatic retention, not a reason to impose an arbitrary new tool-count quota now.
39
+ Retention must be distinguishable from failed activation: `kind: retained_recipe`, `activation: not_requested`, and an exact reusable Recipe path, without global callability claims about a same-named tool. The [current receipt and storage contract](./tool-registry.md#retention-safety-and-accounting) owns fields, budgets, original causes and partial-effect handling. Unknown effects require inspection, not automatic retry or deletion.
81
40
 
82
41
  ### One Usage Owner, Distinct Entrypoints
83
42
 
84
- Library launches use the existing `.usage` owner under the parent Recipe root, not a second ledger root inside `library`. Private ledger identity is `library/<stem>` for retained entries and the existing stem for tool-root entries; this is not a new Recipe name or public `<skill>/<recipe>` reference. A root wrapper and retained definition may share a filename without merging their launch counters or rewriting each other's revision history. JSON/Markdown representations follow the same rule. Neither creating a definition nor exposing its wrapper is a launch.
85
-
86
- Automatic same-source rename inference stays within the retained namespace or within the existing root/draft namespace; disappearance plus matching content cannot silently transfer lineage across the new boundary. Any future deliberate transition must use the existing explicit lineage move/transaction owner. Do not migrate pre-existing nested/legacy ledgers by guessing their ownership or manufacture missing counts; preserve them for separately admitted diagnosis/migration.
87
-
88
- The management result is one coherent path: **save deliberately → find through existing Recipe inspection → reuse the exact Recipe reference → expose explicitly when useful → withdraw only the wrapper when appropriate**. This first contract does not adopt automatic retention/exposure, semantic review, retained updates/deletion, or conversion of existing tools/drafts.
43
+ Reuse the parent's existing usage owner rather than create a library ledger system. Retention, exposure and withdrawal must preserve distinct entrypoint history without inventing accepted outcomes; the [usage/lineage contract](./tool-registry.md#usage-and-lineage) owns the implemented namespace and move rules. Aggregate retention bounds, expiry/disposal and semantic evidence remain prerequisites for future automatic retention, not new tool-count quotas for the manual slice.
89
44
 
90
45
  ## Adopted Lifecycle Direction
91
46
 
@@ -115,7 +70,7 @@ Tool exposure is justified by a stable agent-facing contract, not workload durat
115
70
  - **Inputs:** Caller-owned typed arguments and useful parameterization; no accidental commitment to a single captured prompt, temporary file, credential, installation path, or operator-specific mission.
116
71
  - **Result:** A clear deliverable and acceptance boundary. For async tools, explicitly distinguish the launch receipt from terminal completion and the requested result.
117
72
  - **Effects:** Understandable filesystem/network/service effects, authority requirements, and failure or cancellation limits. Registration does not grant new permissions; launch failure may leave effects, and a stop request is not proof of scope closure.
118
- - **Leverage:** Meaningful reduction in repeated planning or orchestration compared with existing tools and ordinary Recipe spawning. A generic arbitrary-prompt launcher that merely aliases `spawn` usually adds little.
73
+ - **Leverage:** Meaningful reduction in repeated planning or orchestration compared with existing tools and ordinary Recipe spawning. A generic arbitrary-prompt launcher that merely aliases `actors_run_spawn` usually adds little.
119
74
  - **Evidence:** Available validation, actual reuse, outcome acceptance, and uncertainty appropriate to the capability. Do not invent a universal call-count threshold or equate repeated launch attempts with successful reuse.
120
75
 
121
76
  Examples are illustrative, not new registered tools:
@@ -140,7 +95,7 @@ Evaluate memory quality by useful accepted reuse and reduced reconstruction cost
140
95
  Extend existing owners instead of creating a second execution kernel, tool registry, Recipe resolver, or parallel task list:
141
96
 
142
97
  - **Recipe resolution/discovery:** Preserve exact Skill/file identity, imports, runtime-owned origins, validation, and the distinction between retained definitions and tool candidates. A non-tool library must remain reachable through an admitted existing Recipe execution path.
143
- - **Registry/runtime:** Own explicit exposure, host activation, withdrawal limitations, and `callable_now` evidence. Existing explicit `register_tool` intent remains valid for sync and async Recipes; the target policy does not silently prohibit either.
98
+ - **Registry/runtime:** Own explicit exposure, host activation, withdrawal limitations, and `callable_now` evidence. Existing explicit `actors_tool_register` intent remains valid for sync and async Recipes; the target policy does not silently prohibit either.
144
99
  - **Draft/tool review and transactions:** Own evidence-limited recommendations, immutable captures, CAS, quarantine, journals, recovery, and admission of unchanged content. Retain/defer and withdrawal need explicit replay-safe transitions before changing automatic policy.
145
100
  - **Usage/lineage:** Preserve revision and lifetime evidence across retention, exposure, withdrawal, and rollback without counting a migration as a launch or inventing successful outcomes.
146
101
  - **Owning Skills:** Explain only implemented operations and approved selection guidance. Do not tell an agent to use a future library path, metadata flag, review action, or public command.
@@ -154,7 +109,7 @@ Existing user tools must not be silently demoted, deleted, renamed, generalized,
154
109
  - **Orthogonality:** A useful async capability can be exposed; an unsuitable sync capture is not automatically exposed. Either mode can be retained without becoming a tool.
155
110
  - **Evidence limits:** Structurally similar but semantically different Recipes cannot acquire an asserted purpose/usefulness solely from the same review shape. Unavailable semantic evidence stays explicit and can defer a decision without destructive loss.
156
111
  - **Identity and replay:** Retain/expose/withdraw/recover preserve source and lineage, reject stale/conflicting plans, and do not create promotion/demotion churn or duplicate executable copies as new capabilities.
157
- - **Invocation truth:** Explicit sync and async registration still works. Actual tool calls remain distinct from `spawn`; launch, eventual result, singleton attachment, and current callability retain their original meanings.
112
+ - **Invocation truth:** Explicit sync and async registration still works. Actual tool calls remain distinct from `actors_run_spawn`; launch, eventual result, singleton attachment, and current callability retain their original meanings.
158
113
  - **Compatibility:** Source and packed-package journeys preserve existing safety and explicit-registration behavior before any automatic-policy migration. No test writes into the operator's registry.
159
114
  - **Product evidence:** Controlled evaluation must distinguish accepted useful reuse and selection cost from mere growth in Recipe/tool counts. Until measured, improved "muscle memory" remains a design hypothesis, not a shipped performance claim.
160
115
 
@@ -113,7 +113,7 @@ Phases are monotonic:
113
113
 
114
114
  Every journal mutation uses the canonical token-owned lock, expected-phase fencing, owner and generation validation, and atomic replacement. Repeated transitions are idempotent. Corrupt, oversized, foreign-owner, or stale-generation state fails closed with bounded diagnostics.
115
115
 
116
- Ordinary source completion admission has one fresh path: presentation_format=ax_records, private result_layout=completion_yaml_files_v1 and frozen text_budget, without excerpt_format or a public selector. The inactive numbered-stream kernel path keeps its separate frontmatter_v2 default. Bounded source/compiled and actual-default source/packed acceptance observes the normal index path and in-memory entry/context/provider/hint tuple. Unchanged storage/registered-renderer/accepted-history-reopen facts transfer only on the successful original-current-manager path; this is neither fresh default-disk observation nor global lifetime-policy, native-scope or loaded-host acceptance. Direct admission and ordinary run-ui-runtime use it after unchanged owner/location checks; an existing batch stays untouched. Each shown record begins YAML frontmatter with index, run, state, then kind:primary for admitted primary/final Actor response or kind:diagnostic for explicit error/failure excerpts. Untracked fallback has no kind and retains unknown completeness/privacy outside YAML. The closed header is followed by raw, unindented Markdown, with no #N heading, result:/preview: wrapper or compiler literal fence around the body. Known local loss is [N characters omitted] at the cut, not a YAML flag/count or extra ellipsis; N counts the admitted postprivacy source prefix loss, not private/native output. Unknown upstream loss remains separate. Original coverage remains structured member data; exact source/generation/location references remain whole typed nested YAML values. Routine summaries/windows/status copies/standing map instructions remain journal facts, not duplicated model content. Material omitted_results, non-done omitted_states and whole result_inventory recovery stay explicit. Each shown record has a whole run_files row or explicit omission, with unavailable reasons retained; omitted records do not leave orphan location rows. Outcomes precede lower-priority references under the total48KiB UTF-8/64candidate-row bound including framing. Prefix admission considers full-list and decimal-count discontinuities, freezes equal scalar/CRLF-safe shares without unused-share redistribution, and never clips references or rewrites a retained excerpt. Older captures retain their original16KiB/48KiB budgets.
116
+ Ordinary source completion admission has one fresh path: presentation_format=ax_records, private result_layout=completion_yaml_files_v2 and frozen text_budget, without excerpt_format or a public selector. The inactive numbered-stream kernel path keeps its separate frontmatter_v2 default. Bounded source/compiled and actual-default source/packed acceptance observes the normal index path and in-memory entry/context/provider/hint tuple. Unchanged storage/registered-renderer/accepted-history-reopen facts transfer only on the successful original-current-manager path; this is neither fresh default-disk observation nor global lifetime-policy, native-scope or loaded-host acceptance. Direct admission and ordinary run-ui-runtime use it after unchanged owner/location checks; an existing batch stays untouched. Each shown record begins YAML frontmatter with run, state, then kind:primary for admitted primary/final Actor response or kind:diagnostic for explicit error/failure excerpts. Untracked fallback has no kind and retains unknown completeness/privacy outside YAML. The closed header is followed by raw, unindented Markdown, with no #N heading, result:/preview: wrapper or compiler literal fence around the body. Known local loss is [N characters omitted] at the cut, not a YAML flag/count or extra ellipsis; N counts the admitted postprivacy source prefix loss, not private/native output. Unknown upstream loss remains separate. Original coverage remains structured member data; exact source/generation/location references remain whole typed nested YAML values. Routine summaries/windows/status copies/standing map instructions remain journal facts, not duplicated model content. Prepend a packet-local index only when two or more results are shown; exactly one shown result omits only that display field even if other results were omitted. Internal member_index, generation and correlation remain unchanged; the rooted_files_v2 discriminator gates this rule, not member count in an older snapshot or numbered-stream scope. Material omitted_results, non-done omitted_states and whole result_inventory recovery stay explicit. Each shown record has a whole run_files row or explicit omission, with unavailable reasons retained; omitted records do not leave orphan location rows. Outcomes precede lower-priority references under the total48KiB UTF-8/64candidate-row bound including framing. Prefix admission considers full-list and decimal-count discontinuities, freezes equal scalar/CRLF-safe shares without unused-share redistribution, and never clips references or rewrites a retained excerpt. Older captures retain their original16KiB/48KiB budgets.
117
117
 
118
118
  Fresh ordinary source hints carry the core format and whole-content digest; the validated YAML core carries only packet identity and relative body/marker lengths, from which boundaries are derived. It adds no fresh HTML tail or duplicate coordinate table. These are consistency facts, not source or acceptance authority.
119
119
 
@@ -131,7 +131,7 @@ Removing fresh collection of untracked bodies would leave affected old/intermedi
131
131
 
132
132
  ### Retained capture compatibility
133
133
 
134
- The numbered wire strings ax_records_v1/v2/v3, old indexed/single_result captures and result_layout records/run_headers/headings/headings_flat_omissions/headings_outcomes/headings_shared_results/headings_shared_kinds/frontmatter_v1/frontmatter_v2 are retained storage encodings, not public alternatives. Fresh ordinary source admission chooses own-data completion_yaml_files_v1 with canonical ax_records and text_budget (over the unchanged completion_yaml_core_v1 carrier); earlier completion_yaml_core_v1 snapshots retain their old layout, never single_result. Absence preserves its original indexed/singleton codec; inherited aspects never restyle data and accessors are refused without invocation. Earlier record/header/count/kind grammar and each captured16KiB/48KiB share remain exact. The first frontmatter draft retains its original bytes and hints, including unquoted unknown index ?. Retained v2 fixed that one YAML case by writing index: "?"; numeric indices and other fields/body bytes are unchanged, and the presentation-hint schema remains completion_frontmatter_v1 because its block structure is unchanged. Preserve the frozen v1 unknown-content fingerprint90e29fb36087e2620fe0cf150b4238bce8a6d1dcc68ee922a1cf71ee8604610e and prior shared-result fingerprint4428de318b8ebaa029d3588ab7e8e705b9a80fa5cf08b6a2cc7151916207e266. Journals store snapshots rather than complete text: neither an unreleased product, a YAML correction nor member count permits relabeling/migration. Pending/queued/presented replay must reproduce original model bytes and hints without operator journal scans, source refresh or message rewrites. Removing compatibility requires a separate history-lifetime decision.
134
+ The numbered wire strings ax_records_v1/v2/v3, old indexed/single_result captures and result_layout records/run_headers/headings/headings_flat_omissions/headings_outcomes/headings_shared_results/headings_shared_kinds/frontmatter_v1/frontmatter_v2 are retained storage encodings, not public alternatives. Fresh ordinary source admission chooses own-data completion_yaml_files_v2 with canonical ax_records and text_budget (over the unchanged completion_yaml_core_v1 carrier); earlier completion_yaml_core_v1 and completion_yaml_files_v1 snapshots retain their old layout and singleton indices, never single_result. Absence preserves its original indexed/singleton codec; inherited aspects never restyle data and accessors are refused without invocation. Earlier record/header/count/kind grammar and each captured16KiB/48KiB share remain exact. The first frontmatter draft retains its original bytes and hints, including unquoted unknown index ?. Retained v2 fixed that one YAML case by writing index: "?"; numeric indices and other fields/body bytes are unchanged, and the presentation-hint schema remains completion_frontmatter_v1 because its block structure is unchanged. Preserve the frozen v1 unknown-content fingerprint90e29fb36087e2620fe0cf150b4238bce8a6d1dcc68ee922a1cf71ee8604610e and prior shared-result fingerprint4428de318b8ebaa029d3588ab7e8e705b9a80fa5cf08b6a2cc7151916207e266. Journals store snapshots rather than complete text: neither an unreleased product, a YAML correction nor member count permits relabeling/migration. Pending/queued/presented replay must reproduce original model bytes and hints without operator journal scans, source refresh or message rewrites. Removing compatibility requires a separate history-lifetime decision.
135
135
 
136
136
  Steer envelopes already store complete content. Both attention and steer now have one canonical new-message formatter with no presentation selector; the redundant legacy formatting branches/path/body helpers are removed where no retained-data consumer needs them. Existing steer identity is reused before formatting and saved content bypasses the formatter in every pending/queued/presented recovery path. Removing stored Batch codecs later requires a separate retention/data-lifetime decision; an unreleased product is not permission to change previously captured delivery bytes.
137
137
 
@@ -1,6 +1,6 @@
1
1
  # Management Inspection
2
2
 
3
- The public `inspect` tool exposes four exact target families. Targets are management projections, not interchangeable aliases.
3
+ The public `actors_inspect` tool exposes four exact target families. Targets are management projections, not interchangeable aliases.
4
4
 
5
5
  The project-wide [Agent Experience (AX) standard](./agent-experience.md) governs the direction of readable inspection text and its relationship to Inspector/agent context. Adoption does not mean current formatters already conform: rollout belongs to BACKLOG. Keep the exact target/view matrix, authorization and structured/verbose machine payloads unchanged; a new list/key-value presentation does not add fields, bodies or permission.
6
6
 
@@ -32,9 +32,9 @@ Refusal validation order, callbacks/getters/String observations and basic Error
32
32
  ## Run Targets
33
33
 
34
34
  ```text
35
- inspect target=run:demo view=recipe
36
- inspect target=run:demo view=trace source=lifecycle lines=40
37
- inspect target=run:demo view=control lines=20
35
+ actors_inspect target=run:demo view=recipe
36
+ actors_inspect target=run:demo view=trace source=lifecycle lines=40
37
+ actors_inspect target=run:demo view=control lines=20
38
38
  ```
39
39
 
40
40
  Run views require a current coordinator session and an exact, non-empty match between that session id and the Run's persisted owner. Possessing a `run:<id>` is not authorization. Missing coordinator identity, ownerless state, and cross-owner state fail closed.
@@ -52,10 +52,10 @@ inspect target=runtime view=runs
52
52
  ## Runtime Targets
53
53
 
54
54
  ```text
55
- inspect target=runtime view=status
56
- inspect target=runtime view=runs
57
- inspect target=runtime view=runs status=failed
58
- inspect target=runtime view=triage
55
+ actors_inspect target=runtime view=status
56
+ actors_inspect target=runtime view=runs
57
+ actors_inspect target=runtime view=runs status=failed
58
+ actors_inspect target=runtime view=triage
59
59
  ```
60
60
 
61
61
  - `status` reports immutable package/runtime identity, state schema, and current automatic-review policy.
@@ -68,11 +68,11 @@ Runtime inventory never broadens authorization and never returns ownerless or fo
68
68
 
69
69
  Compact spawn/async-tool receipts include a selected-Run `file_navigation` row: the actual directory/generation and the same nine observed canonical starting slots, without reading a catalog or evidence bodies. Kernel checks current logical session and exact physical identity before projecting files and rechecks the recipient before return. Missing/foreign/changed scope yields bounded unavailability without failing an already committed launch; unavailable slots have no path. Complete rows fit inside the remaining shared 16-KiB compact-card budget or are explicitly omitted, never path-truncated; oversized optional launch fields are labeled omitted while bounded core facts/full expert details are preserved. These are mutable location hints, not a body/privacy/terminal certificate, full session tree or filesystem sandbox. Actual source/npm public launch fixtures check reference identity and visible compact/verbose transport. Two existing real-entrypoint research journeys per layout now ordinary-read metadata selected from actual saved public-spawn and uncataloged SDK async-tool receipts before requesting any fresh map, after the producer host/runners/workloads have exited and the same saved session reopens. Actual bounded read arguments and parsed JSON digests match independent parent metadata; this is ordinary raw-file research, not original publication/privacy certification. Four fork/clone histories retain the locations as data but get no fresh owned branch or metadata selection. The async launch uses the existing controlled Kernel composition, not a claim of root-entrypoint async launching. New terminal packets now freeze current-session exact-generation member location rows before journal admission; source/npm SDK now performs an explicitly requested actual result read selected from that terminal row, with independent generation/owner/parsed-JSON checks and unchanged frozen message across continuation.
70
70
 
71
- Compact launch receipts use bare block-YAML fields and a nested `run_files` value for whole selected observed locations, not a fenced object-JSON dump. Machine details retain their original JSON-compatible values and full spawn-verbose is still JSON. A single leading response LF supplies invocation spacing. A full available row suppresses the redundant map request; otherwise one `next` names tool=inspect, target=runtime, view=runs and verbose=true, with optional current-session investigation intent. This request is neither polling nor a read capability. Older terminal packet versions retain `Files (optional; current session)` followed by `inspect target=runtime view=runs verbose=true`. Fresh AX completion captures use a typed next node without reinterpreting that older handoff grammar; saved versions keep their exact text. Separately, new terminal packets use navigation_handoff=captured_file_locations and freeze a bounded prefix of location observations for their captured completion members, ordered roots before descendants with observed failed child-subtrees first. This is not the complete session map. Whole outcome rows retain precedence in the shared16KiBmessage; references then fit whole or are counted omitted, including uncaptured suffixes. Schema decoding and rendering are source/clock/native-free, and never refresh historical availability. Invoking it admits the actual current logical session at that time. Older absent/current_session_request packet versions retain their exact pending/queued/presented text rather than acquiring references on reload. The new reference marker/data are admitted only for new packets after actual current logical-session checks, never by saved DTOs as authority. The single per-batch hint consumes the shared 16-KiB model budget, not a separate allowance.
71
+ Compact launch receipts use bare block-YAML fields and a nested `run_files` value for whole selected observed locations, not a fenced object-JSON dump. Machine details retain their original JSON-compatible values and full spawn-verbose is still JSON. A single leading response LF supplies invocation spacing. A full available row suppresses the redundant map request; otherwise one `next` names tool=inspect, target=runtime, view=runs and verbose=true, with optional current-session investigation intent. This request is neither polling nor a read capability. Older terminal packet versions retain `Files (optional; current session)` followed by `actors_inspect target=runtime view=runs verbose=true`. Fresh AX completion captures use a typed next node without reinterpreting that older handoff grammar; saved versions keep their exact text. Separately, new terminal packets use navigation_handoff=captured_file_locations and freeze a bounded prefix of location observations for their captured completion members, ordered roots before descendants with observed failed child-subtrees first. This is not the complete session map. Whole outcome rows retain precedence in the shared16KiBmessage; references then fit whole or are counted omitted, including uncaptured suffixes. Schema decoding and rendering are source/clock/native-free, and never refresh historical availability. Invoking it admits the actual current logical session at that time. Older absent/current_session_request packet versions retain their exact pending/queued/presented text rather than acquiring references on reload. The new reference marker/data are admitted only for new packets after actual current logical-session checks, never by saved DTOs as authority. The single per-batch hint consumes the shared 16-KiB model budget, not a separate allowance.
72
72
 
73
- `inspect target=runtime view=runs verbose=true` adds `navigation` alongside the existing `runs`. Kernel uses the actual current logical Pi session, rechecks it before return, and selects only already registered exact-generation directories. The map orders roots before their directly same-session-owned children; it does not follow a foreign-session parent or claim a complete descendant tree. Each row offers the canonical context index/result first, then selected metadata/execution/published-session-catalog/Trace/Control/stream locations with observed sizes and format_hint=json/jsonl/text. The file_inventory_scope=canonical_starting_locations label means these are starting points, not an exhaustive file list. Format hints describe expected layout, not validated syntax/UTF-8 or output completeness; even binary or malformed current bytes can retain a layout hint. Present files remain mutable; missing, nonregular or stale files have no usable location. Whole rows, not path strings, are omitted under the independent 16-KiB map bound, with shown/omitted/total Run-row counts, not file counts. The legacy inventory envelope keeps its existing bounds and behavior; `status` filters inventory, not the navigation branch.
73
+ `actors_inspect target=runtime view=runs verbose=true` adds `navigation` alongside the existing `runs`. Kernel uses the actual current logical Pi session, rechecks it before return, and selects only already registered exact-generation directories. The map orders roots before their directly same-session-owned children; it does not follow a foreign-session parent or claim a complete descendant tree. Each row offers the canonical context index/result first, then selected metadata/execution/published-session-catalog/Trace/Control/stream locations with observed sizes and format_hint=json/jsonl/text. The file_inventory_scope=canonical_starting_locations label means these are starting points, not an exhaustive file list. Format hints describe expected layout, not validated syntax/UTF-8 or output completeness; even binary or malformed current bytes can retain a layout hint. Present files remain mutable; missing, nonregular or stale files have no usable location. Whole rows, not path strings, are omitted under the independent 16-KiB map bound, with shown/omitted/total Run-row counts, not file counts. The legacy inventory envelope keeps its existing bounds and behavior; `status` filters inventory, not the navigation branch.
74
74
 
75
- Both priority orders use only failed rows already observed for that inspection and matching the independently admitted map's exact owner/run/generation/directory. Ordinary inspection preserves latest-registration-first independent roots, while failed subtrees precede healthy/unknown siblings within each root. For a failed investigation use `inspect target=runtime view=runs status=failed verbose=true`: known failed root-subtrees are also stable-partitioned first, preserving recency among peers and always ancestors before descendants. `navigation.priority` reports `root_order=latest_registration|failed_subtrees_first` and `basis=observed_failed_rows`. Missing, stale or unmatched observations remain unranked, not certified successful; no complete failure inventory, terminal/native authority or cross-file atomicity is claimed. Ranking performs no additional status/body/native reads, does not filter map rows, repair/reorder catalog bytes or activate compact/default/automatic maps.
75
+ Both priority orders use only failed rows already observed for that inspection and matching the independently admitted map's exact owner/run/generation/directory. Ordinary inspection preserves latest-registration-first independent roots, while failed subtrees precede healthy/unknown siblings within each root. For a failed investigation use `actors_inspect target=runtime view=runs status=failed verbose=true`: known failed root-subtrees are also stable-partitioned first, preserving recency among peers and always ancestors before descendants. `navigation.priority` reports `root_order=latest_registration|failed_subtrees_first` and `basis=observed_failed_rows`. Missing, stale or unmatched observations remain unranked, not certified successful; no complete failure inventory, terminal/native authority or cross-file atomicity is claimed. Ranking performs no additional status/body/native reads, does not filter map rows, repair/reorder catalog bytes or activate compact/default/automatic maps.
76
76
 
77
77
  The published_sessions location is the compiler-owned evidence/sessions.json file. Kernel stats its real evidence directory and regular leaf under the admitted Run root, retaining parent/leaf/owner fences; a symlink, nonregular or unrepresentable location has no usable path. This physical location needs no producer key or context-index.json: missing/corrupt/foreign-generation or pending/unavailable semantic-index claims do not gate ordinary research. A present location does not certify catalog schema, body generation, original privacy or historical publication. The map reads neither catalog bodies nor raw session directories.
78
78
 
@@ -87,12 +87,12 @@ Controlled partial-preview/Unicode and genuine-private-writer-from-controlled-re
87
87
  ## Recipe Targets
88
88
 
89
89
  ```text
90
- inspect target=recipes view=status
91
- inspect target=recipes view=summary
92
- inspect target=recipes view=registry
93
- inspect target=recipes view=doctor identity=music-player/playback
94
- inspect target=recipes view=imports verbose=true
95
- inspect target=recipes view=reviews verbose=true
90
+ actors_inspect target=recipes view=status
91
+ actors_inspect target=recipes view=summary
92
+ actors_inspect target=recipes view=registry
93
+ actors_inspect target=recipes view=doctor identity=music-player/playback
94
+ actors_inspect target=recipes view=imports verbose=true
95
+ actors_inspect target=recipes view=reviews verbose=true
96
96
  ```
97
97
 
98
98
  - `status` reports registry/watch state, active/shadowed/invalid/disabled user Recipes, active Skill components, drafts, retained-library definitions, usage, and diagnostics.
@@ -101,15 +101,15 @@ inspect target=recipes view=reviews verbose=true
101
101
  - `imports` exposes active Skill namespaces and component import inventory for resolution diagnosis.
102
102
  - `reviews` exposes bounded automatic draft/tool review state and recovery guidance.
103
103
 
104
- The compact Recipe catalog adds `retained` as a separate count for direct `.json`/`.md` definitions under `recipes/library`. Details/verbose includes `retained` rows (exact path, source_kind=user_retained_recipe, tool=false, resolved async mode, invalid/disabled state and diagnostics) and `retained_diagnostics`. Both root and library use the active session Skill context. Storage placement does not certify review, current callability or Run state; invalid/disabled definitions remain diagnostic. The missing library is empty, without initialization. Inspection performs no retention write, activation or launch. Valid enabled exact paths remain ordinary explicit-file references for `spawn` or deliberate `register_tool from` specialization. Inspection adds no mutation or logical-reference syntax; use explicit `register_tool expose=false` for supported create-only retention, and see [capability memory](./capability-memory.md#read-only-inventory-checkpoint).
104
+ The compact Recipe catalog adds `retained` as a separate count for direct `.json`/`.md` definitions under `recipes/library`. Details/verbose includes `retained` rows (exact path, source_kind=user_retained_recipe, tool=false, resolved async mode, invalid/disabled state and diagnostics) and `retained_diagnostics`. Both root and library use the active session Skill context. Storage placement does not certify review, current callability or Run state; invalid/disabled definitions remain diagnostic. The missing library is empty, without initialization. Inspection performs no retention write, activation or launch. Valid enabled exact paths remain ordinary explicit-file references for `actors_run_spawn` or deliberate `actors_tool_register from` specialization. Inspection adds no mutation or logical-reference syntax; use explicit `actors_tool_register expose=false` for supported create-only retention, and see [capability memory](./capability-memory.md#read-only-inventory-checkpoint).
105
105
 
106
106
  `identity` is accepted only with `view=doctor`. Skill inventory is fail-soft diagnostic evidence; exact launch and registration still resolve against the immutable active-session context.
107
107
 
108
108
  ## Tool Targets
109
109
 
110
110
  ```text
111
- inspect target=tool:music_player view=status
112
- inspect target=tool:music_player view=schema
111
+ actors_inspect target=tool:music_player view=status
112
+ actors_inspect target=tool:music_player view=schema
113
113
  ```
114
114
 
115
115
  - `status` separates persistence, registry admission, host registration, `callable_now`, activation boundary, source identity, and `tool_calls` versus `spawn_calls`.
@@ -119,4 +119,4 @@ A registered tool is a capability definition, not a Run. Tool status cannot subs
119
119
 
120
120
  ## Boundaries
121
121
 
122
- Inspection is read-only, owner-filtered where Run state is involved, and redacted. Evidence-heavy Run, review, diagnostic, and text projections apply their documented bounds; `runtime view=runs` deliberately returns the complete matching exact-owner inventory. Inspection does not mutate journals, infer authority from displayed data, expose private active-Skill installation paths, or turn retained Trace into an audit archive. Use `message` for admitted runtime or actor-local actions.
122
+ Inspection is read-only, owner-filtered where Run state is involved, and redacted. Evidence-heavy Run, review, diagnostic, and text projections apply their documented bounds; `runtime view=runs` deliberately returns the complete matching exact-owner inventory. Inspection does not mutate journals, infer authority from displayed data, expose private active-Skill installation paths, or turn retained Trace into an audit archive. Use `actors_control_apply` for admitted runtime or actor-local actions.
@@ -91,7 +91,7 @@ F1.6 source-audit correction: Pi 1.0 native custom-message storage, session reco
91
91
  ### 10. Completion Projection, Compiler Frame and Native Renderer
92
92
 
93
93
  - **Owners:** `run-delivery.ts:1510` `completionRecordRow`, `:1683` `assembleFrontmatter`, `:1886` `projectCompletionRecords`, `:2110` `projectRunCompletionBatchPresentation`, `:2233` `readRunCompletionPresentation`, `:2283` retained projection, `:2328` message formatting. `run-ui-runtime.ts:68` `registerRunCompletionRenderer` is wired at `extension-runtime.ts:122`.
94
- - **Current:** Fresh ordinary `completion_yaml_files_v1` snapshots use the unchanged strict YAML-core carrier. Header files.groups stores literal roots with relative entries, source bindings and English purposes; read_first is a group/entry pointer. Unknown-base paths stay explicitly as recorded. Native compact presentation exposes those file groups and places omission/inventory facts in the first header, never after the Markdown. Only known character-cut markers remain beside a truncated body. Earlier core-v1 and historical layouts keep their exact projection and hiding/footer behavior.
94
+ - **Current:** Fresh ordinary `completion_yaml_files_v2` snapshots use the unchanged strict YAML-core carrier. Header files.groups stores literal roots with relative entries, source bindings and English purposes; read_first is a group/entry pointer. Unknown-base paths stay explicitly as recorded. Native compact presentation exposes those file groups and places omission/inventory facts in the first header, never after the Markdown. Only known character-cut markers remain beside a truncated body. Exactly one shown result omits its packet-local display index, including with omissions; multiple shown results retain indices. Internal member/generation/correlation and omission/inventory facts stay unchanged. Earlier rooted-v1, core-v1 and historical layouts keep their exact indices, projection and hiding/footer behavior; numbered streams are separate.
95
95
  - **Prepared wire core:** `run-delivery.ts` `encodeCompletionYamlCarrier` / `readCompletionYamlCarrier` provide the accepted pure/nondefault mechanics; the prototype encodes and typed native view decodes them. Ordinary source/default capture uses the rooted snapshot layout; the earlier core-v1 snapshot and inactive numbered-stream frontmatter_v2 remain separate replay/gated paths. Strict-core Pi correlation and source/packed SDK evidence bind the selected content without granting native or read authority. They encode one `_completion` packet ID/codec and relative body/marker lengths, then derive dense ranges while decoding. Canonical bare headers are independent YAML fragments separated by codec-owned blank lines, not one mapping or a standard YAML multi-document stream; body-present headers are delimited and raw parts remain opaque. All-omitted is bare service metadata, not a fake Run. Empty selected bodies are distinct from absent bodies; empty-marker-only wrappers are refused. Input uses named top-level result keys with explicit depth/work bounds; loaded-host acceptance remains F1.7/U1-gated, and meaningful service warnings must not be hidden wholesale.
96
96
  - **Prepared source projection (nondefault):** `projectRunCompletionYamlPrototype` projects current AX/frontmatter selected snapshots through one shared private fitter; it returns content, a format/digest-only hint and fitting facts, not a newly admitted or relabeled Batch. Frozen budgets/prefixes remain immutable. Canonical header/raw-part costs are measured additively, with unsupported data distinct from byte overflow; final content must agree with the unchanged core encoder/decoder. This prototype API remains data-only and source-class restricted. The ordinary rooted capture reuses internal YAML assembly and the same independently measured quotas/inventory rather than relabeling an old frozen snapshot. Native renderer support is prepared below; actual carrier acceptance remains a separate gate.
97
97
  - **Native view:** `readRunCompletionPresentation` derives frozen typed segments from the strict core and exact minimal format/digest hint; the registered renderer keeps new rooted file groups and all meaningful service facts in headers, then renders each body as independent native Markdown with literal Text metadata/markers. Retained core-v1 captures keep their earlier reference hiding and service placement. Valid-core missing/invalid hints and declared-new malformed content expose original full Text; expansion keeps that same source. Malformed content without a safely readable own new-format declaration retains historical dispatch, not a body-scanning heuristic. Headless widths/padding and old-history preservation are proved. Repo SDK 1.0.0's public `CustomMessageComponent` falls back to one Markdown component when a renderer is absent, returns undefined or throws, joining text-block arrays; a fresh component probe confirms this boundary, not session/interactive dispatch. Preserve that fallback unchanged: full content supplied to Markdown is neither independent-body rendering nor literal-visibility proof. Independent Markdown belongs only to the validated registered compact branch; registered degraded/expanded views keep original Text. Actual source-admitted native storage/context/provider/reopen and loaded terminal/phone behavior remain separate acceptance.
package/docs/releasing.md CHANGED
@@ -15,7 +15,7 @@ The adopted CI layout has three isolated test jobs on each supported OS: `instal
15
15
 
16
16
  Each job uses a separate checkout and test-agent state, Node24 and the existing single-worker/preload flags. Package validation (types, Recipe QA, committed build parity and extension import) plus dry-pack runs once per OS on `installed`, not on every shard. Local `npm test` and `npm run validate` remain complete unsharded entrypoints. The reusable workflow must wait for all nine test jobs and the single dependency audit before release publication; one successful shard never substitutes for the full gate. This layout reduces aggregate critical-path pressure, not the cost or correctness obligations of an individual native test.
17
17
 
18
- Simple tools/registration fixtures bind original runner births and actual `close`, then validate canonical success and fresh ESRCH again at deletion. Their joint acceptance phase has one10-second watchdog, replacing the old approximately2-second result/exit polling assumption; this is a fixture allowance, not a product/SDK/workload deadline. Missing post-close results fail promptly; uncertainty retains roots without signals or automatic wait inflation.
18
+ Simple tools/registration and installed-runner fixtures bind original runner births and actual `close`, then validate canonical success and fresh ESRCH again at deletion. Their joint acceptance phase has one10-second watchdog, replacing the old short result/exit polling assumptions; this is a fixture allowance, not a product/SDK/workload deadline. Missing post-close results fail promptly; uncertainty retains roots without signals or automatic wait inflation.
19
19
 
20
20
  Implementation and native CI acceptance are tracked in BACKLOG until the complete sharded candidate passes.
21
21
 
@@ -1,12 +1,12 @@
1
1
  # Run Supervision and Self-Contained Outcomes
2
2
 
3
- Status: Accepted future supervision contract with separately identified implemented AX/evidence slices; full supervision is not released. Proposed supervision API/policy additions and their examples are not supported by the current release. [BACKLOG.md](../BACKLOG.md) owns the next selective AX/navigation/existing-runtime release and the remaining future work; this document owns behavior and evidence boundaries. The selective release does not activate independent owner-loss supervision, execution deadlines, public completion streams or unapproved source/retention expansion. Native authority, unchanged credentials, the agreed three-platform scope and positive closure requirements remain mandatory for the future feature. MPRIS and removal of `inspect` stay excluded.
3
+ Status: Accepted future supervision contract with separately identified implemented AX/evidence slices; full supervision is not released. Proposed supervision API/policy additions and their examples are not supported by the current release. [BACKLOG.md](../BACKLOG.md) owns the next selective AX/navigation/existing-runtime release and the remaining future work; this document owns behavior and evidence boundaries. The selective release does not activate independent owner-loss supervision, execution deadlines, public completion streams or unapproved source/retention expansion. Native authority, unchanged credentials, the agreed three-platform scope and positive closure requirements remain mandatory for the future feature. MPRIS and removal of `actors_inspect` stay excluded.
4
4
 
5
5
  ## Goal and Boundaries
6
6
 
7
7
  A coordinator should receive a finite Run's outcome without polling. Optional periodic diagnostics make overdue work discoverable, and an independent execution deadline can terminate an owned generation. Neither policy is required for ordinary jobs or controlled services.
8
8
 
9
- - Preserve `spawn`, `message`, and `inspect`. Ordinary Run inspection is a manual request for the same compact snapshot used by timed diagnostics, with a readable context index for selective investigation. Retain resolution, activation, Control, and runtime diagnosis; do not remove existing expert routes implicitly.
9
+ - Preserve `actors_run_spawn`, `actors_control_apply`, and `actors_inspect`. Ordinary Run inspection is a manual request for the same compact snapshot used by timed diagnostics, with a readable context index for selective investigation. Retain resolution, activation, Control, and runtime diagnosis; do not remove existing expert routes implicitly.
10
10
  - Do not add resumable suspension, checkpoints, automatic restarts/retries, a synchronous wait budget, global supervision defaults, or a new actor type.
11
11
  - Do not treat a diagnostic heartbeat as progress, semantic attention, or evidence that a task is healthy.
12
12
  - Preserve owner filtering, process-identity proof, lifecycle locks, parent/root delivery lineage, redaction, retention boundaries, and native Pi history.
@@ -148,7 +148,7 @@ Two independent old-layout reds then green properties cover literal/native Text2
148
148
 
149
149
  ### Recipe Registry Watcher Notification Constants
150
150
 
151
- Only two literal arguments in runtime.ts changed: notifyFailure warning now uses report plus original restart/register_tool advice as opaque instruction; scheduleReload info uses report containing the whole old Recipe tools refreshed from ~/.pi/agent/recipes text. No helper/import/domain/budget, root/state/activation read, automatic action or new actual-root/readiness/closure fact. Watcher calls ctx.ui.notify directly, unlike runtime.notify's hasUI gate; caller/port behavior remains distinct, including hasUI=false with an explicit callback. Parent/root admission, failureNotified/setWatchStatus, notifyAfterReload/latest pending state, timer/unref/load/getResolutionContext, stale-event checks, close/rearm and catch/reportCallbackError/no-throw containment are byte-unchanged outside those constants. A success-notifier fault can leave pending info for a later real event exactly as before; no automatic replay is introduced.
151
+ Only two literal arguments in runtime.ts changed: notifyFailure warning now uses report plus original restart/actors_tool_register advice as opaque instruction; scheduleReload info uses report containing the whole old Recipe tools refreshed from ~/.pi/agent/recipes text. No helper/import/domain/budget, root/state/activation read, automatic action or new actual-root/readiness/closure fact. Watcher calls ctx.ui.notify directly, unlike runtime.notify's hasUI gate; caller/port behavior remains distinct, including hasUI=false with an explicit callback. Parent/root admission, failureNotified/setWatchStatus, notifyAfterReload/latest pending state, timer/unref/load/getResolutionContext, stale-event checks, close/rearm and catch/reportCallbackError/no-throw containment are byte-unchanged outside those constants. A success-notifier fault can leave pending info for a later real event exactly as before; no automatic replay is introduced.
152
152
 
153
153
  Two independent old-layout reds then greens in tests/runtime.test.ts retain all nine prior cases unchanged. Warning property covers missing parent/root open failure/root or parent error, failed-before-UI dedup, direct UI with either hasUI value, UI/notify-getter/callback faults with exact opaque/undefined/primitive causes, contained secondary observer throws and rearm reset. Refresh property covers active/draft/POSIX-Windows separator/null/mixed latest-pending events, original ctx/resolution and load-before-notify, closed stale callbacks, load/info failures with original secondary-before-primary reporting, and pending info on a later controlled draft event. Native Text checks24/52/90/140 widths; no model16KiB cap or actual root certification. Injected documented watchPath/exists/load/UI ports and real timers are deterministic fixture infrastructure, not independent/native/loaded-host review. Existing real filesystem rearm scenario remains whole and platform-skipped as before.
154
154
 
@@ -278,7 +278,7 @@ No transaction, rollback, callback, notifier, source read, lifecycle policy or d
278
278
 
279
279
  Text remains within16KiB including the existing formatter's leading LF. Whole field/list/action representations start from shorter full-or-omitted seeds and only grow. Fitting complete safety warnings have first priority before name/source/hint and large argument groups. No partial argument/path, fabricated char count, input/work quota or loss repair. Whole-group omission counts selected list entries, including complete large warning labels; malformed/non-text selections are unavailable without another coercion or new source permission. Machine args/defaults/warnings remain unchanged even when compact text omits them.
280
280
 
281
- All14original registry declarations/scenarios/fixtures/assertions/cleanup remain, with only the first approved success-layout assertion changed and the test environment explicitly imported before production. Two new properties first fail on old prose/unbounded group text, then cover unverified/callable/toggling activation×new/update, exact cfg/activation/notify observation order, opaque Unicode/CRLF warning labels and unchanged persisted bytes/details/next_actions. Opaque/undefined/primitive failures from notify, warning read, required-argument Array-subclass join and late activation getter occur after retained persistence with one activation and no new rollback/retry. Exact16384/one-over required and optional groups, non-disclosure of actual default values, warning priority/oversized warning coverage, malformed selected args, dynamically fenced real backtick-bearing source and actual SDK register_tool success normalization are covered. These fixtures register only in temporary recipe roots; they do not invoke a tool or prove real host activation.
281
+ All14original registry declarations/scenarios/fixtures/assertions/cleanup remain, with only the first approved success-layout assertion changed and the test environment explicitly imported before production. Two new properties first fail on old prose/unbounded group text, then cover unverified/callable/toggling activation×new/update, exact cfg/activation/notify observation order, opaque Unicode/CRLF warning labels and unchanged persisted bytes/details/next_actions. Opaque/undefined/primitive failures from notify, warning read, required-argument Array-subclass join and late activation getter occur after retained persistence with one activation and no new rollback/retry. Exact16384/one-over required and optional groups, non-disclosure of actual default values, warning priority/oversized warning coverage, malformed selected args, dynamically fenced real backtick-bearing source and actual SDK actors_tool_register success normalization are covered. These fixtures register only in temporary recipe roots; they do not invoke a tool or prove real host activation.
282
282
 
283
283
  Actual installed replay now includes the whole16registry owner. Its original sibling-process lock-collision fixture resolves one production module via new URL rather than import syntax; the existing production-only remap now covers that exact reference as well, without copying scenarios or changing child code/assertions/cleanup. This process-lock comparison grants no new Actor/native readiness/exit claim. Original registration-truth/SDK/native fixtures remain intact. Earlier whole2spawn/16Control/21inspection/8response/21overlay/16Inspector and prior owners remain. The source, matrix, SDK and compiled replays are nonadditive. Independent review, loaded terminal/phone, source/recipient/native/clock/default/integrated release gates remain separate.
284
284
 
@@ -327,7 +327,7 @@ The exact remaining gate is a reviewed trusted host/recipient-publication contra
327
327
 
328
328
  ## Exact Launch API
329
329
 
330
- Add two independent optional fields to the root JSON/Markdown Recipe contract and the public `spawn` request:
330
+ Add two independent optional fields to the root JSON/Markdown Recipe contract and the public `actors_run_spawn` request:
331
331
 
332
332
  - `report_every: Duration | null`: Optional minimum interval between eligible diagnostic deliveries for this generation; at least `1m` (`60000ms`) when enabled. It is disabled by default.
333
333
  - `max_runtime: Duration | null`: Maximum admitted execution duration for this generation, followed by runtime-owned termination.
@@ -359,7 +359,7 @@ Planned launch override:
359
359
 
360
360
  Resolve each field independently: explicit launch value, including `null`, overrides the effective root Recipe; an omitted Recipe field inherits through direct delegation; an unresolved field is disabled. A derived root Recipe's explicit value or `null` overrides the delegated source. There is no implicit interval or deadline.
361
361
 
362
- These are literal Run policy fields, not template flags or inferred placeholders. Do not interpret `values.report_every`, `values.max_runtime`, or similarly named actor arguments as supervision. Do not add reserved arguments to every registered tool. Async registered tools inherit their effective root Recipe policies; per-launch overrides in this increment are exposed through `spawn`. An inline synchronous execution path must reject root supervision fields as `run_supervision_requires_run`, not silently ignore an apparent execution limit. `spawn` always creates a Run and can therefore honor the fields even when the source Recipe is not marked async.
362
+ These are literal Run policy fields, not template flags or inferred placeholders. Do not interpret `values.report_every`, `values.max_runtime`, or similarly named actor arguments as supervision. Do not add reserved arguments to every registered tool. Async registered tools inherit their effective root Recipe policies; per-launch overrides in this increment are exposed through `actors_run_spawn`. An inline synchronous execution path must reject root supervision fields as `run_supervision_requires_run`, not silently ignore an apparent execution limit. `actors_run_spawn` always creates a Run and can therefore honor the fields even when the source Recipe is not marked async.
363
363
 
364
364
  Named imports and command graph nodes are not Runs: their Recipe-level policies do not establish or reset the enclosing Run's timers. Separately spawned children have independent policies, while an expired parent's owned-tree teardown still applies. Direct Recipe/tool specialization must retain the resolved policy through the existing contract resolver rather than copying its template or rediscovering a different source.
365
365
 
@@ -410,7 +410,7 @@ A separate source/packed fixture now composes this private kernel through real p
410
410
 
411
411
  Participating owners sharing one exact genuine origin in this module/runtime now coordinate through a private weak claim. Activation reserves it before canonical assembly; a contender receives `controller_claimed` while another owner's controller or provisional assembly holds it. Stop alone does not transfer an allocated controller's claim: explicit release/close revokes its callbacks before handover. Failed assembly drops only its own reservation; a late nonholder cleanup cannot erase another owner's claim. The origin's first identity/state/frame binding persists across owner release, preventing copied-state adoption. Handover observes the original elapsed allowance, never a new current-time budget. This is cooperative logical ownership, not proof that an old physical timer was removed, exactly-once due notification across successive controllers or global scope authority. Distinct origins, module instances, processes and unregistered low-level controller constructors are outside that claim. Real launch handoff and controlled assembly/handover witnesses cover this boundary; cross-runtime authority, independent supervision/recovery, ordinary detached-runner frozen timing and public/native acceptance remain open.
412
412
 
413
- A compatible singleton reuse retains its original anchor, deadline, and report schedule. Compare normalized effective policies, so `60s` and `1m` are equivalent; conflicting policies fail closed instead of retiming a live singleton. A genuinely new generation receives new clocks. Running policies are not mutable through `message` in this increment.
413
+ A compatible singleton reuse retains its original anchor, deadline, and report schedule. Compare normalized effective policies, so `60s` and `1m` are equivalent; conflicting policies fail closed instead of retiming a live singleton. A genuinely new generation receives new clocks. Running policies are not mutable through `actors_control_apply` in this increment.
414
414
 
415
415
  New metadata records `createdAt` and `started_at` from the same generation-admission anchor. The stored supervision fields form a coherent cohort: positive integer milliseconds or explicit null, a canonical ISO start, and exactly the deadline implied by that start and ceiling. Partial, coercible, or contradictory clocks fail closed rather than being repaired. A pre-supervision generation with wholly absent clock fields stays explicitly unconfigured; it can be reused under disabled policies without rewriting its metadata, but cannot acquire a new allowance or today's Recipe policy merely by reattachment.
416
416
 
@@ -422,7 +422,7 @@ Intervals are eligibility thresholds, not hard-real-time delivery promises. The
422
422
 
423
423
  In addition to each Run's interval, the exact top-level coordinator session admits routine diagnostic batches no more often than once per `60000ms`. This is one shared gate for all its Runs and containing trees, not a separate allowance for every Run, child session, or staggered timer. Both floors use `RUN_DIAGNOSTIC_MIN_INTERVAL_MS` from the policy owner; the gate is a delivery ceiling, not an implicit reporting default. It may postpone diagnostics further than their per-Run eligibility.
424
424
 
425
- Advance the shared cooldown only from accepted routine diagnostic delivery, not a proposed packet, ordinary completion, explicit urgent `steer`, or manual `inspect`. An admitted packet with unresolved acceptance retains its one diagnostic admission slot without spawning additional diagnostic packets. Preserve/recover the gate with exact owner and acceptance evidence across busy/idle transitions and reattachment; uncertain timing/acceptance defers routine diagnostics rather than inventing a fresh slot. At the next eligible boundary, merge the latest due snapshots fairly instead of replaying missed intervals. Independent top-level sessions retain independent gates.
425
+ Advance the shared cooldown only from accepted routine diagnostic delivery, not a proposed packet, ordinary completion, explicit urgent `steer`, or manual `actors_inspect`. An admitted packet with unresolved acceptance retains its one diagnostic admission slot without spawning additional diagnostic packets. Preserve/recover the gate with exact owner and acceptance evidence across busy/idle transitions and reattachment; uncertain timing/acceptance defers routine diagnostics rather than inventing a fresh slot. At the next eligible boundary, merge the latest due snapshots fairly instead of replaying missed intervals. Independent top-level sessions retain independent gates.
426
426
 
427
427
  Terminal outcomes and explicit urgent semantic attention bypass the routine diagnostic cooldown, while retaining their existing safe-boundary, budget, lineage, and exact-acceptance rules. An execution deadline never waits for this gate. Manual inspection neither consumes nor resets it, and ordinary completion delivery never depends on enabling periodic diagnostics or execution limits.
428
428
 
@@ -756,7 +756,7 @@ Add a Run-only `status` view and make it the default when `view` is omitted:
756
756
  {"target":"run:review"}
757
757
  ```
758
758
 
759
- `inspect target=run:review view=status` is equivalent. Compact text is the default; `verbose: true` returns the same bounded snapshot as JSON, not extra logs or a complete raw Run dump in content/details. Snapshot view rejects inapplicable `lines`, `source`, `identity`, and runtime inventory `status` filters instead of silently ignoring them. Other target families still require their existing explicit views. Existing explicit expert Run views remain available in this increment; they are not the ordinary status path and must not be invoked automatically to expand a compact snapshot.
759
+ `actors_inspect target=run:review view=status` is equivalent. Compact text is the default; `verbose: true` returns the same bounded snapshot as JSON, not extra logs or a complete raw Run dump in content/details. Snapshot view rejects inapplicable `lines`, `source`, `identity`, and runtime inventory `status` filters instead of silently ignoring them. Other target families still require their existing explicit views. Existing explicit expert Run views remain available in this increment; they are not the ordinary status path and must not be invoked automatically to expand a compact snapshot.
760
760
 
761
761
  Snapshot inspection is read-only: it cannot reset clocks, change report eligibility, acknowledge a pending automatic diagnostic/completion, signal processes, scan directories, or load role bodies beyond bounded identity/index metadata. The payload is refreshed for the manual call; equality with a timed report means the same schema and authoritative facts at the same observation, not reuse of a stale cached heartbeat. Manual responses remain ordinary tool evidence; latest-only folding applies to the separate automatic diagnostic stream, not to arbitrary tool results.
762
762
 
@@ -836,7 +836,7 @@ This proves explicit SDK research after actual producer/holder loss through both
836
836
 
837
837
  The published_sessions starting link uses observeRunContextExportLocation in the existing runs-context-index owner. It resolves only the fixed compiler role through runContextExportPath, independently admits exact Run/generation/root/owner, stats the real evidence directory and regular leaf without opening/reading the role body or semantic index, and retains owner/parent/leaf change checks through final map return. Missing parents/leaves are missing; symlinks/nonregular/unrepresentable locations stay unavailable without usable paths. A changed available role fence refuses the map. Semantic-index absence/corruption/foreign generation or pending/unavailable/publication flags cannot become an original-producer gate for ordinary physical-file research. Presence is not role-schema/body-generation, privacy, historical-publication or completeness certification. The private issuer/body/privacy/publication requirements remain separate and unchanged. Their shared directory-change predicate now also rechecks real-directory/non-symlink type rather than relying on dev/ino agreement alone; a deterministic reused-id/changed-type metadata counterexample failed before this correction. This is a checked-boundary witness, not a reproduced public OS escape. No raw-session scan, eager nested preview read or arbitrary reference follow is introduced.
838
838
 
839
- Only inspect target=runtime view=runs verbose=true adds this map. The adapter obtains and rechecks the real current Pi session; caller owner fields do not select it. Missing/corrupt catalogs return explicit catalog_unavailable while preserving catalog bytes and independent legacy inventory. Compact/default/automatic map delivery remains unchanged; the separate launch-registration effect above is now active. Legacy inventory/status keeps its separate scans/probes; the new map itself performs neither. Source/npm-packed SDK tool-adapter fixtures load/read the active Actors Skill, receive the map in model context and use ordinary read on its first result. A second captured host opens the same saved session after the first host closes and is freshly ESRCH-confirmed; a new session sees only its own branch, and corruption remains unavailable without repair. Two layouts use four fixture hosts, eight SDK journeys, six ordinary mapped-result reads, four ordinary controlled session-catalog reads and four selected controlled-preview reads, with zero Actor workloads or original producer keys. The fixture catalog and two preview files follow the existing publication layouts but contain explicit controlled assistant-text markers; they are not real publisher/issuer output. Each positive journey selects only the first available preview through its known contained relative path, checks the saved Run/generation/command/id and partial coverage, compares exact UTF-8 byte count and Unicode point/count/omission data, and keeps primary_text=not_exported and history_complete=false as recorded labels rather than certification. Real SDK read-start events match the expected exact path sequence; no unselected preview/raw Actor transcript is requested, and its body marker stays out of model context. Parent validation reads both fixture preview files only to compare snapshots and metadata; catalog/selected/unselected bytes remain unchanged and the semantic index stays absent. This proves a controlled-layout ordinary selected-read journey, not original privacy/publication, source clipping behavior or a filesystem sandbox. The fixture deliberately retains running registration/metadata status while recording controlled code0/code7 results; done/failed inventory filters must use the current status owner in both indexed and corrupt-index fallback paths, without changing catalog bytes. Metadata directories/results are controlled fixtures, not genuine launched Runs or producer-exit/terminal/native truth. Parent/child frames, full stdio/actual close and fresh ESRCH before successful deletion are checked; failures retain state.
839
+ Only actors_inspect target=runtime view=runs verbose=true adds this map. The adapter obtains and rechecks the real current Pi session; caller owner fields do not select it. Missing/corrupt catalogs return explicit catalog_unavailable while preserving catalog bytes and independent legacy inventory. Compact/default/automatic map delivery remains unchanged; the separate launch-registration effect above is now active. Legacy inventory/status keeps its separate scans/probes; the new map itself performs neither. Source/npm-packed SDK tool-adapter fixtures load/read the active Actors Skill, receive the map in model context and use ordinary read on its first result. A second captured host opens the same saved session after the first host closes and is freshly ESRCH-confirmed; a new session sees only its own branch, and corruption remains unavailable without repair. Two layouts use four fixture hosts, eight SDK journeys, six ordinary mapped-result reads, four ordinary controlled session-catalog reads and four selected controlled-preview reads, with zero Actor workloads or original producer keys. The fixture catalog and two preview files follow the existing publication layouts but contain explicit controlled assistant-text markers; they are not real publisher/issuer output. Each positive journey selects only the first available preview through its known contained relative path, checks the saved Run/generation/command/id and partial coverage, compares exact UTF-8 byte count and Unicode point/count/omission data, and keeps primary_text=not_exported and history_complete=false as recorded labels rather than certification. Real SDK read-start events match the expected exact path sequence; no unselected preview/raw Actor transcript is requested, and its body marker stays out of model context. Parent validation reads both fixture preview files only to compare snapshots and metadata; catalog/selected/unselected bytes remain unchanged and the semantic index stays absent. This proves a controlled-layout ordinary selected-read journey, not original privacy/publication, source clipping behavior or a filesystem sandbox. The fixture deliberately retains running registration/metadata status while recording controlled code0/code7 results; done/failed inventory filters must use the current status owner in both indexed and corrupt-index fallback paths, without changing catalog bytes. Metadata directories/results are controlled fixtures, not genuine launched Runs or producer-exit/terminal/native truth. Parent/child frames, full stdio/actual close and fresh ESRCH before successful deletion are checked; failures retain state.
840
840
 
841
841
  **Private-publication saved-session handoff and restart acceptance.** The existing source/npm-packed context-private-evidence fixture now creates a real saved SDK SessionManager identity before Kernel producer admission, persists its actual id/file/cwd before assertions/conversation writes, and stores one explicit controlled bootstrap user message. This is not an original prompted AgentSession/Actor workload. Its already exercised genuine private session writer publishes the existing controlled recorded-session preview; the fixture immediately retains catalog/preview id/path/byte/SHA-256 data bound to its captured producer frame and checks unchanged bytes after later privacy/index-refusal cases. Those data cannot recreate issuer/privacy/native authority. It explicitly registers that exact metadata root before exit with cached status=unknown (not work/native truth), and confirms one visible starting-map row even with the existing long generation. This is fixture preparation, not ordinary read backfill or a real public Run launch. Parent capture now writes the exact positive producer frame before assertions/await and stores Buffer/base64 stdout/stderr plus actual close/completeness as context-private-stdio-v2 before decoding. It checks parent/child/raw frames, real main/ten case metadata files, saved SDK header/message, catalog row and published file hashes before fresh captured-host ESRCH admits successful cleanup. Failures retain state and preserve primary/persistence/proof errors. Per layout there remain 15 genuine private issuer admissions, 10 controlled identity frames, 12 controlled session selections and zero Actor workloads; a saved session identity is not a native member. The fresh-process phase below now consumes this handoff after holder exit. Historical v1 stdio evidence is neither rewritten nor promoted to v2 proof.
842
842
 
@@ -846,7 +846,7 @@ Source assessment keeps genuine Actor-session ordinary research independent from
846
846
 
847
847
  **Genuine Actor-session recorded-source acceptance.** The existing source/npm coordinator fixture adds one public Run through the real package entrypoint and the SDK1.0 installed pi executable, not a renamed script. Its explicitly loaded finite deterministic provider emits one assistant response without network/model judgment or tools. The normal runner supplies the managed session directory and records the actual JSONL reference in execution.json; command/native/root code0 and natural acceptance are checked separately from process exit. A distinct real saved coordinator owns this Run, preserving the original eight-row research map: the first combined nine-row attempt exposed honest 16-KiB omission rather than a product failure. The CLI session has its own distinct v3 id; parent independently verifies header/cwd, actual startup session-file/PID frame, user prompt, assistant row and exact recorded path/UTF-8 bytes. Readiness is recorded by the controlled provider after CLI imports and before its gated response, not authenticated spawning-member evidence. After holder and all25captured runner/workload PIDs are freshly ESRCH-confirmed, a separate SDK host reopens that owning saved coordinator. Real entrypoint inspection yields only its owned Run; ordinary read paths are exactly Skill/result/execution/recorded-session, with the last read selecting one actual assistant JSONL line by offset/limit1. SDK read-start arguments and the independently captured raw line/hash correspond. Existing other-session/fork/clone/live-switch maps exclude this foreign-owned root. All103known catalog/Run/source/catalog-absence snapshots per layout match after research. No session preview catalog is created, and canonical primary text remains selection_not_supported. Fresh ESRCH for all27captured PIDs immediately precedes successful cleanup; failed evidence stays retained. The complete current two-layout composition has20Runs/20runners/30finite workloads/two holders/two fresh readers,42research journeys (16adapter/26actual-entrypoint),28mapped-result reads,26selected command captures and two bounded raw-session-row reads. Counts describe one accepted invocation, not sums across red/focused/final runs. This proves genuine Pi-recorded source investigation, not curated original privacy, authenticated membership, exhaustive closure or automatic publication.
848
848
 
849
- **Earlier approved request-only navigation handoff (owner decision, 2026-10-25).** This remains the discovery aid and older formatting version; the actual-reference implementation and A2 exit above supersede treating this hint alone as completion. Compact spawn/async-tool receipts and newly admitted completion batches offer one optional current-session file-map command: inspect target=runtime view=runs verbose=true. This is the adopted minimal handoff, not an automatically embedded path map or a new mandatory reader. Existing expert launch next_actions remain and gain the same navigation request. A shared pure formatter emits compiler-owned text only; it reads no Run files, catalog, clock or Pi context and cannot grant another logical session's scope. Actual invocation remains the existing Kernel route, which rechecks the live logical session and exact admitted roots/generations. The request is not routine completion/status polling and does not auto-run. New completion batches record navigation_handoff=current_session_request as formatting data only, with strict decoding; legacy absence stays absent across pending/queued/presented reload and phases so prior accepted/proposed message text is not retrofitted or replayed. In those retained handoff packets, the one per-batch request consumes their original shared16KiB render budget and inventory/omission selection; no separate allowance, member-path disclosure or capability reconstruction is introduced. Current explicit-manual result/capture/recorded-session/published-preview, partial coverage/Unicode, containment/source-loss, dual-order/whole-row omission and restart/replacement/isolation evidence remains separate. Reference-only navigation needs no elapsed time/native authority; snapshot/status/timed joins still retain A1/B1's clock/lifetime gates, enforcement retains C and release retains D. Full-map embedding, body publication, periodic reporting and default snapshot switching are not adopted by this handoff.
849
+ **Earlier approved request-only navigation handoff (owner decision, 2026-10-25).** This remains the discovery aid and older formatting version; the actual-reference implementation and A2 exit above supersede treating this hint alone as completion. Compact spawn/async-tool receipts and newly admitted completion batches offer one optional current-session file-map command: actors_inspect target=runtime view=runs verbose=true. This is the adopted minimal handoff, not an automatically embedded path map or a new mandatory reader. Existing expert launch next_actions remain and gain the same navigation request. A shared pure formatter emits compiler-owned text only; it reads no Run files, catalog, clock or Pi context and cannot grant another logical session's scope. Actual invocation remains the existing Kernel route, which rechecks the live logical session and exact admitted roots/generations. The request is not routine completion/status polling and does not auto-run. New completion batches record navigation_handoff=current_session_request as formatting data only, with strict decoding; legacy absence stays absent across pending/queued/presented reload and phases so prior accepted/proposed message text is not retrofitted or replayed. In those retained handoff packets, the one per-batch request consumes their original shared16KiB render budget and inventory/omission selection; no separate allowance, member-path disclosure or capability reconstruction is introduced. Current explicit-manual result/capture/recorded-session/published-preview, partial coverage/Unicode, containment/source-loss, dual-order/whole-row omission and restart/replacement/isolation evidence remains separate. Reference-only navigation needs no elapsed time/native authority; snapshot/status/timed joins still retain A1/B1's clock/lifetime gates, enforcement retains C and release retains D. Full-map embedding, body publication, periodic reporting and default snapshot switching are not adopted by this handoff.
850
850
 
851
851
  #### Existing Derived Role Exports
852
852
 
@@ -1296,7 +1296,7 @@ Private readonly `readRunSessionContextPreview(stateDir, expected, exportId)` no
1296
1296
 
1297
1297
  Private `readRunStreamSource(stateDir, expected, stream)` now admits one fixed canonical runner `stdout` or `stderr` as **kernel-only projection input**, not a readable/model-facing context view. It freshly admits exact published Run/generation/optional owner through the context-identity owner, then uses `readExecutionRunnerStreamText` over the same checked regular-file descriptor machinery as session input. The lower layout owner accepts only root `stdout.log`/`stderr.log` for `runner_stream`, never a capture/session/evidence path; metadata observation stays body-free and file-size-quota-free. The separate text input is capped at 4 MiB, refuses known oversize before opening/allocation/body read, strictly rejects malformed UTF-8, preserves an actual runner-stream BOM and closes the descriptor before returning. Existing session decoding remains unchanged. Empty existing text is distinguishable from missing/unreadable/nonregular source; denied or failed cleanup never yields success or a read retry. Root/marker/Run metadata and source descriptor/path changes invalidate the entire input, including through its returned `unchanged()` callback, without adopting a newer generation. Returned `bytes_total` is current physical source size, not saved/observed command-capture agreement or completeness proof. The raw text is deliberately labeled `visibility: "kernel_only"`, `source_scope: "canonical_runner_stream"`, `capture_completeness: "not_asserted"`; these labels are not visibility permissions or body-authenticity certificates. Do not serialize this input as model/tool evidence: a separately owned fixed privacy/visibility projection must precede any view publication. The canonical runner stdout is already formatted by `executeRegisteredTool` and may be clipped; stderr also carries runner error/log text. Neither is an authoritative complete accepted answer or primary-result capture, nor a safe shortcut to raw Pi JSONL/provider payloads. This input port performs no export/index/status/ACK/clock mutation, directory discovery, process probe, producer reconstruction or native actuation. The input allowance is observational, not a workload/file-content quota or a model-output budget. Stronger curated stream privacy/view/index publication and runtime refresh remain separate unadopted integration work, not prerequisites for accepted A2 ordinary research or a mandatory custom reader. A3 must independently retain authorized complete primary sources before formatting.
1298
1298
 
1299
- The runtime/export owner prepares authorized views and atomically replaces each file and the bounded index independently of inspection; publish a reference only after its export is readable. This is not a cross-file atomic snapshot: mutable live views can advance between index and file reads, and historical excerpts still require stable captures. A missing view is marked unavailable/pending/not-applicable, not fabricated as an empty file. Before following a role, verify the index and evidence generation against the snapshot; replacement/pruning is unavailable evidence, never permission to inspect a newer generation. Context means retained authorized evidence, not a promise to reconstruct discarded history. Manual reads select a role and a bounded range using its format/size/coverage metadata; they do not require `inspect` to return the value or load every role.
1299
+ The runtime/export owner prepares authorized views and atomically replaces each file and the bounded index independently of inspection; publish a reference only after its export is readable. This is not a cross-file atomic snapshot: mutable live views can advance between index and file reads, and historical excerpts still require stable captures. A missing view is marked unavailable/pending/not-applicable, not fabricated as an empty file. Before following a role, verify the index and evidence generation against the snapshot; replacement/pruning is unavailable evidence, never permission to inspect a newer generation. Context means retained authorized evidence, not a promise to reconstruct discarded history. Manual reads select a role and a bounded range using its format/size/coverage metadata; they do not require `actors_inspect` to return the value or load every role.
1300
1300
 
1301
1301
  ## Latest-Only Delivery and Context
1302
1302
 
@@ -1315,7 +1315,7 @@ Snapshot production, packet acceptance, and model projection are separate respon
1315
1315
 
1316
1316
  ## Generation-Fenced Manual Kill
1317
1317
 
1318
- Extend the public `message` envelope with top-level `run_instance_id`. It is required for `action: "kill"`; the launch response, compact inspection, or diagnostic supplies it:
1318
+ Extend the public `actors_control_apply` envelope with top-level `run_instance_id`. It is required for `action: "kill"`; the launch response, compact inspection, or diagnostic supplies it:
1319
1319
 
1320
1320
  ```json
1321
1321
  {
@@ -1335,9 +1335,9 @@ A winning manual stop claim produces terminal status `killed` with reason `manua
1335
1335
 
1336
1336
  ## Self-Contained Automatic Outcomes
1337
1337
 
1338
- Normal finite roots deliver their outcome through the existing active/idle completion path without an `inspect` round trip. Services need not terminate to stay usable; periodic diagnostics are optional, and normal service Control semantics remain unchanged. Existing silent policies, exact root ownership, and containing-tree eligibility remain authoritative.
1338
+ Normal finite roots deliver their outcome through the existing active/idle completion path without an `actors_inspect` round trip. Services need not terminate to stay usable; periodic diagnostics are optional, and normal service Control semantics remain unchanged. Existing silent policies, exact root ownership, and containing-tree eligibility remain authoritative.
1339
1339
 
1340
- Keep generation, terminal status, compact summary, and declared artifacts. Add the distinct `timed_out` reason/deadline evidence and label output from interrupted work `partial: true`. Display clipping is not task partiality. Compact public-spawn and asynchronous registered-tool launch receipts now omit the three generic `inspect` calls while preserving launch facts. Explicit verbose public spawn retains existing full JSON metadata, including expert `next_actions`; meaningful diagnosis may still recommend the appropriate public inspection route. Quiet compact text adds no unconditional completion/readiness promise and does not change silent or service policy.
1340
+ Keep generation, terminal status, compact summary, and declared artifacts. Add the distinct `timed_out` reason/deadline evidence and label output from interrupted work `partial: true`. Display clipping is not task partiality. Compact public-spawn and asynchronous registered-tool launch receipts now omit the three generic `actors_inspect` calls while preserving launch facts. Explicit verbose public spawn retains existing full JSON metadata, including expert `next_actions`; meaningful diagnosis may still recommend the appropriate public inspection route. Quiet compact text adds no unconditional completion/readiness promise and does not change silent or service policy.
1341
1341
 
1342
1342
  ### Private Kernel Contract: Primary Command Text Publication
1343
1343
 
@@ -1458,11 +1458,11 @@ Packet admission curates and copies the binding, freezes its nested source/range
1458
1458
 
1459
1459
  The shared operator/model Markdown projection uses literal dynamically fenced previews without whitespace, CRLF, BOM or backtick normalization. It keeps exact shown/total/omitted code-point counts, the half-open UTF-8 range, redaction/clipping distinction and full source/generation/digest reference. Markup delimiters are presentation, not source code points. Existing 64-row/16-KiB model and 256-member/1-MiB journal bounds remain; overflow omits whole rendered rows with explicit retained-member counts, not untracked edits inside excerpts or source paths. Newly admitted row-overflow packets also retain a [scoped captured-member inventory](coordinator-delivery.md#captured-member-inventory) and budget its complete reference before rows. That source lists all captured identities/statuses/lineage and existing primary bindings only; private locations, diagnostics and artifact inventories are not included. Source/journal publication remain separate effects, and phase transitions/rendering never reread or repair the source. Legacy missing references are explicit. Owning properties and a bounded linked source/packed six-composition byte-overflow witness are verified; broader omitted-available-primary/row-limit journeys and artifact/summary/error inventories remain open. Schema parsing and rendering rely only on admitted packet data; they do not authorize new publication or raw/sibling discovery.
1460
1460
 
1461
- The source and installed-tarball SDK fixture now joins the initial case in one chain: a model-issued public `spawn` launches a real bare Node command, the runner publishes its first canonical binding, the root coordinator supplies one automatic batch to the next model context, and ordinary bounded file reads recover the complete exported 128-KiB memory-input or 2-MiB capture-input source from the **reference parsed from that model context**. Tools mode proves actual `stdout_truncated` execution metadata, complete source recovery and redaction in the prefix no longer held in memory; final-answer mode retains complete-memory coverage. It checks the source/generation/hash against the accepted binding, exact preview/range/count agreement, strict UTF-8 and redaction. The fixture uses no private kernel publication, producer admission, source-reader or SDK helper API and invokes no status-polling tool or native completion-send queue.
1461
+ The source and installed-tarball SDK fixture now joins the initial case in one chain: a model-issued public `actors_run_spawn` launches a real bare Node command, the runner publishes its first canonical binding, the root coordinator supplies one automatic batch to the next model context, and ordinary bounded file reads recover the complete exported 128-KiB memory-input or 2-MiB capture-input source from the **reference parsed from that model context**. Tools mode proves actual `stdout_truncated` execution metadata, complete source recovery and redaction in the prefix no longer held in memory; final-answer mode retains complete-memory coverage. It checks the source/generation/hash against the accepted binding, exact preview/range/count agreement, strict UTF-8 and redaction. The fixture uses no private kernel publication, producer admission, source-reader or SDK helper API and invokes no status-polling tool or native completion-send queue.
1462
1462
 
1463
1463
  Both layouts exercise a complete tool batch and completion during a final-answer request. Tools mode uses a fixture-only producer-exit barrier before returning the unchanged public reply; final mode returns that reply immediately, holds the command behind a bounded fixture gate until the next model request, and then verifies the completion continuation after that final answer. Both retain one agent run/one accepted batch; requests are respectively two and three. Capture the public receipt's PID/state/generation immediately, require fresh ESRCH for producer exit before cleanup, and retain durable launch/capture uncertainty if exit cannot be proved. These fixture gates/waits are not product deadlines, independent supervision or whole-scope closure proof.
1464
1464
 
1465
- A third source/packed SDK mode proves bounded captured-member overflow recovery through six real public `spawn` calls, one per model request. A shared fixture gate holds output until all PID/state/generation receipts are durably captured; release on the final-answer request produces one automatic batch and one continuation in the same agent run, without status-tool polling or native send queues. Six literal Unicode command-metadata rows exceed 16 KiB, so the model context carries the exact inventory reference and omission count. Ordinary bounded file reads verify the inventory's full hash/bytes, all six natural Run identities/generations/statuses, captured order and exclusion of private locations/diagnostic excerpts/bodies. Captured diagnostic references are retained separately and recovered in full, even for omitted rows. These compositions keep explicit `not_selected` primary bindings: this is not primary-source authorization for composition outputs. Each layout uses eight model requests, six public spawn calls and one accepted batch; fresh producer ESRCH remains mandatory before fixture cleanup. Completion order is not launch order. This witness covers byte-budget member omission with composition primary explicitly unavailable, not all row-limit/primary/artifact/summary/error cases.
1465
+ A third source/packed SDK mode proves bounded captured-member overflow recovery through six real public `actors_run_spawn` calls, one per model request. A shared fixture gate holds output until all PID/state/generation receipts are durably captured; release on the final-answer request produces one automatic batch and one continuation in the same agent run, without status-tool polling or native send queues. Six literal Unicode command-metadata rows exceed 16 KiB, so the model context carries the exact inventory reference and omission count. Ordinary bounded file reads verify the inventory's full hash/bytes, all six natural Run identities/generations/statuses, captured order and exclusion of private locations/diagnostic excerpts/bodies. Captured diagnostic references are retained separately and recovered in full, even for omitted rows. These compositions keep explicit `not_selected` primary bindings: this is not primary-source authorization for composition outputs. Each layout uses eight model requests, six public spawn calls and one accepted batch; fresh producer ESRCH remains mandatory before fixture cleanup. Completion order is not launch order. This witness covers byte-budget member omission with composition primary explicitly unavailable, not all row-limit/primary/artifact/summary/error cases.
1466
1466
 
1467
1467
  A fourth source/packed SDK mode now proves **omitted available primary** recovery with six real bare one-attempt command launches, eight model requests, one accepted automatic batch and no status-polling tools/native send queue. Each emits >2 MiB of strictly valid UTF-8; actual execution metadata confirms memory-tail truncation, while the genuine observed-stream/durable-capture path retains the complete fixed-privacy source within the unchanged 4-MiB allowance. Long Unicode positional command metadata forces the shared projected-row byte budget independently of full-output size; compact primary previews stay 160 code points. One inventory reference parsed from actual model context fixes all six captured identities/generations/statuses/primary bindings. Ordinary <=8192-byte reads validate full source SHA-256/UTF-8 bytes/code-point totals/preview ranges/shown-omitted counts, BOM/CRLF/backticks/Unicode tail and full prefix/tail secret redaction. Every source is recovered, including positively counted omitted members; displayed primary refs agree with displayed rows. Identical content hashes across Runs do not collapse source/generation identity. Metadata references remain separately verified and no unsupported composition scope is added. Those four modes cover eight layout scenarios/28 real public producers with the same immediate durable PID/state/generation capture and fresh ESRCH cleanup proof. This closes that bounded byte-overflow witness only, not all selection/failure/summary/artifact cases, manual visual/external-model/native or integrated release acceptance.
1468
1468
 
@@ -1526,7 +1526,7 @@ The source must exist and retain the complete exported result before clipping. I
1526
1526
 
1527
1527
  Artifact bodies are not automatically all inlined. Export a bounded manifest of names, authorized source references, media types, availability, and byte sizes where known; optional text previews use the same descriptor. Binary files remain references. Reuse existing digests when available rather than requiring an implicit full scan of every large artifact. Any mutable external artifact reference must be identified as mutable and cannot serve as the retained original of an embedded excerpt without an owned stable capture.
1528
1528
 
1529
- The shared packet budget covers metadata and previews together. If artifact entries, summaries/errors, or terminal rows are omitted, disclose counts and a readable generation-bound manifest/result-index source for the omitted evidence. Summary/error clipping must likewise retain a source. Every overflow path must be usable with normal authorized file-reading tools; `inspect` cannot be the only way to recover an automatically omitted result.
1529
+ The shared packet budget covers metadata and previews together. If artifact entries, summaries/errors, or terminal rows are omitted, disclose counts and a readable generation-bound manifest/result-index source for the omitted evidence. Summary/error clipping must likewise retain a source. Every overflow path must be usable with normal authorized file-reading tools; `actors_inspect` cannot be the only way to recover an automatically omitted result.
1530
1530
 
1531
1531
  ### Visible Truncation Contract (UX/AX)
1532
1532
 
@@ -1553,7 +1553,7 @@ Full text: <readable retained exported result>
1553
1553
 
1554
1554
  - Recipe resolution owns literal-field validation, direct-delegation inheritance, normalization, and effective-policy capture. Run creation owns the start anchor and singleton comparison.
1555
1555
  - Runtime lifecycle supervision owns due times, exact-generation stop claims, process/tree proof, and terminal truth. Presentation code must not signal processes directly.
1556
- - Observation owns the shared manual/timed snapshot and declared result/capture evidence. The export owner publishes the readable context index through existing privacy/ownership projections; `inspect` only reads it. Delivery owns frozen packets, bounds, acceptance, and recovery; context projection owns automatic diagnostic supersession only.
1556
+ - Observation owns the shared manual/timed snapshot and declared result/capture evidence. The export owner publishes the readable context index through existing privacy/ownership projections; `actors_inspect` only reads it. Delivery owns frozen packets, bounds, acceptance, and recovery; context projection owns automatic diagnostic supersession only.
1557
1557
  - `index.ts` remains wiring. Reuse canonical locks, process verification, journal/capture authorities, and public Pi ports; keep the local module graph acyclic.
1558
1558
  - Implementation must update owning Skills, current API references, source/packed contracts, and error guidance when the new behavior actually exists. Do not present unsupported additions as current behavior or use live stores as validation fixtures.
1559
1559
 
@@ -1600,7 +1600,7 @@ The [canonical backlog](../BACKLOG.md) keeps A/B/C independently actionable wher
1600
1600
  - **SUP-11 — Honest excerpts:** Verify UTF-8 ranges, full/empty/large results, byte and Unicode code-point counts, redaction-relative metadata, missing/incomplete captures, unavailable old generations, and independent task partiality. Never substitute newer bytes or invent source availability.
1601
1601
  - Evidence: U/I/P UTF-8/Unicode/redaction properties, full/empty/large inputs, multistage previews and unavailable generations/captures.
1602
1602
  - Publication blocker: Wrong accounting, newer-byte substitution, an unreadable/unretained promised source or incomplete capture presented as complete.
1603
- - **SUP-12 — Recoverable overflow:** Large/binary/many artifacts and omitted terminal rows retain a readable manifest/index with omission counts under the shared context budget. Reading published evidence does not require `inspect` or raw-registry access.
1603
+ - **SUP-12 — Recoverable overflow:** Large/binary/many artifacts and omitted terminal rows retain a readable manifest/index with omission counts under the shared context budget. Reading published evidence does not require `actors_inspect` or raw-registry access.
1604
1604
  - Evidence: U/I/P many outcomes/artifacts, large/binary references and bounded packet overflow with selective readable recovery.
1605
1605
  - Publication blocker: Silent omissions, unrecoverable entries, raw-registry dependence or unbounded/binary bodies in model context.
1606
1606
  - **SUP-13 — Public delivery journey:** Real source and packed SDK fixtures prove one active-boundary update after the entire tool batch, idle batching, root/child lineage, silent-policy preservation, no periodic wakeup when disabled, no native-steer synthesis, and independent urgent semantic attention. Assertions must witness provider callback completion outside the callback.
@@ -1619,4 +1619,4 @@ The [canonical backlog](../BACKLOG.md) keeps A/B/C independently actionable wher
1619
1619
  - Evidence: U/I/P staggered due times, exact floor, unresolved acceptance, busy/idle/recovery, independent roots and bypass neutrality.
1620
1620
  - Publication blocker: Per-Run frequency bypass, cooldown from proposals, manual/terminal/urgent gate changes, catch-up bursts or diagnostic wakeups while disabled.
1621
1621
 
1622
- Use existing Recipe/reference, tool/Control, async-run, observability, delivery, session-evidence, inspect/security, and agent-journey test families. Runtime implementation closes only after focused witnesses plus the normal product validation, source/packed parity, and canonical ABCd context checks. Version preparation and external publication belong to the applicable scoped candidate checkpoint in BACKLOG.md, not implementation progress alone; follow the [release contract](./releasing.md). Removing `inspect` and implementing MPRIS remain outside the authorized scope.
1622
+ Use existing Recipe/reference, tool/Control, async-run, observability, delivery, session-evidence, inspect/security, and agent-journey test families. Runtime implementation closes only after focused witnesses plus the normal product validation, source/packed parity, and canonical ABCd context checks. Version preparation and external publication belong to the applicable scoped candidate checkpoint in BACKLOG.md, not implementation progress alone; follow the [release contract](./releasing.md). Removing `actors_inspect` and implementing MPRIS remain outside the authorized scope.