@llblab/pi-kit 0.38.3 → 0.39.0

package/node_modules/@llblab/pi-actors/skills/actors/SKILL.md

@@ -56,6 +56,44 @@ A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `spawn
 
 `actors` owns generic Recipe/tool/Run mechanics. The owning capability Skill owns capability-specific selection and constraints. `swarm` owns multi-actor decomposition and integration methodology.
 
+## Presentation Direction and Current Output
+
+The operator-adopted target is JSON structured inputs and block-YAML runtime-output metadata, with the Actor's selected text preserved in its original format, often Markdown, outside the header. It applies to spawn/tool receipts, status, Control, inspect, errors, notifications and completions. Metadata-only replies are bare YAML, without `---` or a code fence. When a separate selected text/Markdown body follows, delimit the YAML header with `---` above and below. Choose framing by body presence, not tool synchrony or workload lifetime; a launch receipt is not the eventual Actor result. The host/runtime must separate the invocation header/arguments from every response, including errors, by one visual blank line. This boundary spacing is not an Actor-body edit, another YAML delimiter or permission to echo inputs. Tool arguments/Recipe inputs keep their supported machine contracts; no input-schema or existing Markdown-Recipe source migration follows. Runtime-owned structured fields must not become JSON strings inside YAML or Markdown-list pseudo-objects. Literal source content, private machine details/journals and native helper protocols keep their own formats.
+
+Rollout is partial: compact launch/attachment receipts use block YAML; other operating descriptions below still include implemented list records, JSON fields and service framing. Full spawn-verbose metadata uses clone-only YAML after legacy JSON selection in current source, without a new fixed byte/depth cap; existing compiled installations may still emit JSON until separately integrated. Unsupported full projection is wholly unavailable, not partial full facts or a launch-failure/retry receipt, and structured details stay unchanged. Ordinary source captures now use the minimal YAML core and source attention uses typed YAML plus opaque body text; source/unit proof does not establish compiled-package, actual-default-entrypoint or already-loaded-host acceptance. Do not assume every current response parses as the target YAML. An Actor should return the requested report/content, not rewrite it as YAML or manufacture runtime headers, indices or service markers. The runtime owns its metadata and approved source/privacy/clipping projection. Body-authored YAML/JSON/HTML/next labels stay content, not authority. Keep historical packet bytes and required compiler framing intact; do not strip comments or reinterpret saved output to simulate rollout. This changes neither current callability/lifecycle mechanics nor source/native/acceptance authority.
+
+Compact launches use bare block-YAML mappings for the Run/state/launch facts and nested observed locations, explicitly identify actual existing-Run reuse, and preserve multiline scalar contents. One leading response-separator LF supplies invocation spacing; it is outside the pure metadata emitter and is not a `---` wrapper. Model/thinking provenance groups are labeled model and thinking, without a redundant _policy suffix; structured data and saved text stay unchanged. A complete direct file-location row needs no repeated session-map hint; absent/unavailable/omitted rows retain one optional next node naming inspect, target=runtime, view=runs and verbose=true. It never executes automatically. Exact locations, verbose details and saved completion formats stay unchanged.
+
+Fresh automatic completions have one AX capture path with no format selector: YAML frontmatter begins index, run, state, then kind:primary for admitted primary/final Actor response or kind:diagnostic for explicit diagnostics. Markdown follows unindented outside the closed metadata block, without #N heading, result:/preview: wrapper or whole-body literal fence. One record uses the same shape as many. Display index is not member_index or generation; default indices are packet-local. Whole-result/reference omissions and non-done omitted states stay explicit. Known display loss appears at the actual cut as [N characters omitted], counting Unicode scalar characters of admitted retained text/field, never raw/private loss; no extra clipping ellipsis or body clipping flags/counts in YAML. Unknown upstream completeness/privacy remains separately visible at the body boundary, not a fabricated count or a known positive loss. Untracked fallback has no kind and cannot become primary. Full text fitting its share has no display-cut marker; upstream uncertainty still prevents a completeness claim. New packets share48KiB UTF-8 including references/framing across at most64candidate rows, with frozen equal shares and no unused-share redistribution or fixed16KiB result/2KiB preview cap. Captured members remain bounded at256. Text is admitted work output/final response or explicit error/failure diagnostics, never launch commands. Successful composition/retry/Pi text-print can retain text_basis:actor_response; scope and exact references remain technical, while original coverage facts remain structured retained data. The model receives one complete content with whole source/generation/location references or truthful omission/inventory, not a standing full-map instruction. The TUI renders compiler headers/markers as Text and each body as independent native Markdown; only whole validated header reference/location rows and framing disappear in compact view. Body-authored YAML, next/tool/batch and omission lookalikes remain content. Content-bound hashes/ranges/blocks are display consistency, not authentication, source/read/action or acceptance authority. Invalid/missing hints and expansion reveal full original text, without Run-source IO. Old saved codecs, budgets, labels, excerpts, counts and hints replay exactly with no refresh, repair, ACK/resend or restyling—including earlier #N packets and the first frontmatter encoding. Fresh unavailable indices use quoted YAML "?"; an old saved unquoted value is not silently corrected. Routine successful delivery adds no separate completions/delivery-accepted toast; actual failures and handled-generation fences remain. These source/package rules do not prove that an already loaded session was reloaded. Fresh explicit agent Trace previews append boundary … and [omitted: N chars] from normalized retained turn, with a separate upstream [omitted: unknown]. N counts only display loss after existing session privacy, not discarded original/source text. Short well-formed summaries stay unchanged, including authored older-looking markers; malformed retained text yields Agent turn [omitted: unknown] (malformed retained text), never a guessed count or repaired scalar. This is read-time display only, not a rewrite/version of saved packets or sources. Other legacy clipping is not yet uniformly covered. Follow retained references selectively without inventing completeness or permission. Agent Trace ids reference recorded entry provenance, not aggregate traversal order or chronological event numbers. Native entry keys survive sibling growth; bounded legacy/ambiguous/private-metadata fallbacks are not permanent identities, source immutability or new read/work permission.
+
+Current completion index fields are packet-local, not persistent historical indices; earlier saved #N headings keep their original meaning. Session completion streams are adopted work in progress, not an available action; do not invent a start-stream command, initialize a missing counter or reinterpret old headings. A kernel-only path commits numbered snapshots/counters/activation atomically. Its internal runtime bridge requires trusted fresh-session opt-in plus current manager/generation binding; the default entrypoint does not opt in and no public tool/command exposes it. Unknown state does not fall back to local numbering on that path. Startup/reload/resume, including ambiguous imports, cannot resume a stream automatically; stored numbers remain data, not a new session grant. A pending target or projected scope is not an active stream. Missing state never authorizes bootstrap, and unknown/conflicting delivery never authorizes bypass or reallocation. Saved numbers stay exact; an admitted unavailable counter or unfitting whole range freezes an unknown index (quoted "?" in fresh YAML, #? in older layouts) rather than resetting or partially numbering a packet.
+
+Fresh compact Run/tool/Recipe inspect text uses flat AX records. Run views still show only their run/view header; choose verbose for the existing structured evidence, not a newly available snapshot. Tool status preserves callability/activation/source/usage facts and lists required/optional arguments; schema stays JSON. Recipe registry/focused doctor preserve counts, partiality, portable source and rejection. At most one known read-only Recipe inspect hint becomes typed next; other advice is opaque instruction content, not a parsed/executable command or permission to spawn/update a tool. All next_actions remain in details. These are read-time projections; saved history and machine payloads are not restyled. Runtime status/runs/triage now also uses flat runtime/view records for exactly the existing package/review facts, full owned inventory count and existing pressure/attention counts. It adds no snapshot, duration, default status integration or new read; verbose navigation stays independently bounded. Successful automatic completion delivery is silent outside the result records: no separate completions/delivery-accepted receipt or UI toast. Durable acceptance and handled-generation fencing remain; real callback, delivery, recovery and teardown failures stay reportable in the same field style without changing effects or closure authority. Fresh watcher diagnostics now use watcher/scope/path/diagnostic/recovery fields with whole literal paths; rearm restores watch acceleration, not new terminal/native authority. Automatic retirement notices distinguish a returned stop request, reported cancellation, skipped or failed stop path, always with closure unconfirmed. The stop path includes notification callbacks, so a fallback may follow effects already performed; do not infer an effect-free graceful-stop failure or replay work. Existing attempted/result/error behavior remains, and no discarded lower cause is reconstructed. Inspector layouts remain separate.
+
+Locally authored inspect refusals now use AX records with target_kind/target/tool, result and actual supported-value lists. target_kind names a selector family, not ownership. Only missing registered-tool/schema errors retain one known read-only inspection next; missing tools still forbid substituting spawn for tool invocation. Whole variable fields and next actions fit the shared16KiB text allowance or show explicit field/action omission counts, never shortened targets or inferred character loss. Body-authored labels stay content. Dependency/authorization/session failures keep their owning behavior, without a blanket wrapper or new private-cause disclosure. Discovery/status hooks may already have run before a local refusal; it is not a no-effects receipt or authority to replay.
+
+Runtime validation guidance is limited to pre-dispatch failures. An executor/launcher failure can retain partial effects; matching argument-like wording is not a reason to repeat the invocation. Preserve the original cause and diagnose it instead; this adds no retry or closure guarantee.
+
+Four locally authored Control guard errors use caller target/action/result records and real supported_actions/available_actions sequences. Those lists are diagnostic data, not automatic instructions or readiness/actuation permission. Targets and whole selected lists fit16KiB or show explicit field/entry omissions; malformed selected text is unavailable, not repaired. Omission counts are not private/upstream character counts. Normalizer/session/dependency and actual dispatch failures keep their owning behavior; a guard is no global no-effects receipt or permission to retry.
+
+Local spawn guards identify unsupported state_dir or invalid as with field/result and the selected caller value, not an admitted Run. Whole values fit16KiB or show field omission; malformed text is unavailable, not repaired. The host may reject unsupported state_dir by its own schema before the facade, so not every SDK validation error has AX text. This adds no launch, no-effects receipt, retry permission, generated identity or change to Recipe/session/post-launch failures.
+
+Successful normal register_tool receipts now use flat tool/result/source/callable_now fields and actual argument/warning sequences. A non-template source stays one exact literal; complete warnings take priority under16KiB, and whole-field/list omissions count only selected metadata, not hidden chars. Call advice remains opaque instruction, not automatic invocation; an unverified registration keeps its existing read-only tool-status next. Persistence is not callability: rely on the existing activation evidence, never substitute spawn or infer fresh host readiness from this layout. Transaction/errors/list/delete/draft and saved messages are not restyled by this slice.
+
+Registry name listings now show the same selected sorted names as one list with coverage; an overlarge whole group is omitted rather than mislabeled empty, and malformed text is unavailable without repair. Counts describe selected names, not active/callable or the complete loaded-host registry. Deletion returns tool/result and preserves the manual reload note as opaque instruction: neither a current-map miss nor returned deletion proves full host removal or authorizes automatic reload/retry. Existing partial-effect exceptions and machine details remain unchanged.
+
+Draft-promotion success uses the same field grammar only for its original selected name/new-update/source=draft/callable display and one prior hint. It adds no default/body/argument/path or activation facts and does not become an ordinary registration transaction. A zero, opaque legacy display or unavailable field is not permission to infer readiness or repair callability. Whole scalar/action omissions stay explicit; invocation advice is content and only the existing read-only status hint may be typed. Promotion callbacks/display can still fail after writes with original errors; no automatic rollback/retry/reload follows.
+
+Local register_tool source-mode refusals now identify field/result and actual replacement/reference/source-mode/inherited-field choices. Existing correction advice is instruction content, not automatic retry/update or a no-effects receipt. Supplied values are not echoed. The host owns clone/coercion/schema behavior before the facade, so use the actual outcome rather than assuming every wrong-typed request reaches a local AX guard. Other registry errors and all existing activation/transaction contracts remain unchanged.
+
+Ordinary invalid/reserved-name and new-registration missing-source errors now use AX fields. Reserved-name display is only the old selected value, not ownership or tool-invocation permission; an unfit/malformed value is wholly omitted/unavailable, not repaired. Missing-source choices and prior correction advice do not impose a new source rule on listing or existing-tool updates. Dependency/normalizer/blocker errors keep their own behavior; no retry, overwrite or no-effects authority follows from these records. Ordinary/draft already-registered refusals likewise identify only the original selected name and preserve Use update=true to overwrite as opaque instruction. This layout neither merges their admission policies nor authorizes overwriting, automatic retry or invocation; unfit/malformed name display stays explicitly omitted/unavailable under16KiB. Local template-shape errors now identify nested Recipe-shaped template, empty sequence or unsupported type, with actual string/object/sequence choices and old repair advice as opaque instruction. Supplied values are not echoed; this adds no source mode, global null/undefined rule, retry permission or change to host validation/coercion and dependency errors. Four later authored-Recipe validation errors now likewise identify defaults, description or template with fixed field/result. Their original stages remain: front null can delete, existing source can be inherited, and host schema/earlier source checks may reject or route a request before these local errors. No new value echo, automatic correction, activation or no-effects authority follows. A delegated-source runtime-owned-default refusal now names only its existing first selected key under defaults/key/result with prior advice as opaque instruction. It neither displays supplied values/all reserved keys nor authorizes retry or changes command-template/default admission behavior; original copy faults can still precede the refusal. Draft-path refusals now identify the allowed-root or resolved-path reference as a whole literal, or explicit omission/unavailability when unfit/malformed. Old summary-inspection advice remains opaque instruction, not automatic action or a new guarantee that a summary lists every draft. Existing root/exists checks and unowned faults keep their semantics; this is not filesystem absence, no-effects or native proof. Public from-normalization failures now show the prior displayed source, reason, legacy active-skill summary and doctor advice as AX. Source stays a whole literal or explicit field omission/unavailability; reason/summary/body labels are opaque, and advice remains instruction rather than an automatic call. The legacy summary is not a complete Skill inventory, display is not freshly normalized ownership, and a failure does not grant retry, broader source/cause access or host readiness. Normal candidate-admission refusals now likewise report selected joined diagnostics and, only on the existing source branch, prior displayed source/legacy summary/doctor advice. Diagnostics/summary are opaque values, not complete lists or raw causes; upstream diagnostic clipping remains legacy/unproven. Full fields fit16KiB or have explicit omission/unavailability without repair. This does not alter admission, make failures effect-free/transactional, or authorize automatic correction, retry or invocation. Draft invalid-Recipe refusals now similarly show only the previously selected optional reason or joined diagnostics with draft/result. They add no path/body, source permission, raw cause or rollback guarantee; read/diagnose/admission behavior and legacy upstream limits remain. Whole values fit16KiB or show omission/unavailability without repair, and absent reason is not synthesized. Outer registration transaction failure now also separates old stage, resolution_generation, legacy summary and surfaced error as AX after the original cleanup path. That generation identifies resolution context, not fresh Run identity/epoch. Inner rollback/advice wording remains opaque error content, not proof of complete host rollback/removal or permission to repeat. Original cleanup/formatting faults and partial effects remain; no new cause/source access or transaction guarantee. Registry activation/promotion/deletion UI notices now use report/tool fields with only old selected display. A report is not callable or complete-host-removal proof; original hasUI/callback/post-effect failures remain. Whole well-formed notifier values are not subject to the model16KiB cap, malformed selected name is unavailable without repair, and RPC forwarding is not client handling/visibility proof. Recipe registry watcher warning/refresh reports use AX fields too; their old default-root wording is not a freshly verified actual path, and restart/register_tool advice is only opaque instruction, never automatic action. Startup registry warnings use category sequences with whole opaque selected diagnostics; authored next/tool labels are content, malformed selected text unavailable and old doctor advice only opaque instruction. The reports do not establish callability, full upstream diagnostics or new source permission.
+
+Compact Control receipts now use flat Markdown-list key/value records: run names have no duplicated namespace, action/result/delivery/handling remain distinct, and an optional next node names the inspect tool and its target/view. Multiline values retain their internal Markdown under an outer indentation; they are not extra status fields. This is a presentation of existing facts, not a raw dump or proof of completion. Delivery is not handling; a legacy kill attempt is not full termination. Changed-owner/generation refusals withhold replacement status even in verbose/detail output. Kernel delivery exceptions retain original/later causes and genuinely admitted correlation, but raw cause chains are not a new public message schema or proof that handling failed. Actor-local dispatch exceptions stay errors and report delivery/handling/effects uncertainty with a fresh-owned-inventory hint; they intentionally withhold saved correlation, including verbose, because an admission-era context does not prove current reply scope. Do not interpret this as a handling receipt or no-effect refusal. Do not repeat destructive actions to obtain verbose detail or follow a changed owner/generation blindly. See the Runs reference for this boundary.
+
+The awaited Control facade also preserves its surfaced request failure if lifecycle release subsequently throws, keeping ordered private original/release causes without coercion or flattening. A single request or release-only rejection stays exact; existing handled/delivered facts are not rolled back. This does not unlock transport early, prove release/native closure, expose saved correlation or authorize automatic retry. Generic mutation/replacement paths likewise retain original/later faults without making failed operations effect-free, transactional or safe to repeat. Existing bounded platform write retries do not rerun preparation callbacks.
+
+Manual archive/prune exceptions can follow moved/copied/removed data. A single surfaced rejection stays exact; multiple original, diagnostic-recording and release faults retain ordered private causes without rollback or automatic replay. A queued record alone does not prove retirement ran, and a later failure does not undo an admitted filesystem effect. Cause chains are not a new public receipt or native closure proof; do not assume a pruned Run-local Trace remains readable.
+
 ## Persistent capability workflow
 
 To make `music-player/playback` callable as `music_player` with a default source:
@@ -95,7 +133,7 @@ Use the `actors/*` helpers only for their narrow requested result or intentional
 
 The current Pi instance owns user authority and the final result; pi-actors creates explicit local Runs, while companion transports provide presence rather than hidden instance creation. Keep short single-boundary work inline when delegation adds no value. For several participants, reasoning allocation, quorum, or integration methodology, read `swarm`.
 
-Treat `attention: "steer"` as an actor-authored urgent semantic checkpoint at Pi's next safe boundary, never as a status-derived completion signal; the later root terminal still arrives through its ordinary completion batch.
+Treat `attention: "steer"` as an actor-authored urgent semantic checkpoint at Pi's next safe boundary, never as a status-derived completion signal; the later root terminal still arrives through its ordinary completion batch. Fresh source steers use block-YAML run/checkpoint metadata and typed artifacts/run_files groups with shown/omitted/total path sequences. Metadata-only output is bare; an actual selected body follows a closed YAML header without added outer indentation or compiler fences. Body-authored next/tool labels remain content, not actions. The complete serialized message, whole references and later-group omission coverage fit the unchanged16KiB cap; unknown legacy body loss uses [omitted: unknown], never inferred private-tail lengths. Saved envelopes keep their exact earlier text, not a refreshed/reformatted checkpoint. Unfit essential text is retryable pre-admission unavailability, not partial delivery. Fresh source notify/followup uses the same selected metadata/raw-body and first-eight-slot reference coverage, without a new shared16KiB/48KiB cap. Raw malformed/oversize urgent essentials still refuse before reference reads; YAML escaping does not grant admission. Notify remains visible status only; followup alone adds non-displayed checkpoint context, with unchanged event details/order/seen-id/wake policy. New legacy body clips use [omitted: unknown]; compatibility formatter text keeps its older spelling. Fresh urgent diagnostics are AX event/attention/stage records: retryable admission is not a no-effect receipt, failed send leaves delivery/presentation unconfirmed, and unknown/conflicting recovery evidence leaves the envelope queued. Diagnostic values preserve their inner Markdown under240UTF-16 source units; clipped/malformed text has [omitted: unknown], not a private-tail count. Saved diagnostic evidence/envelope content and original Error/cause are not rewritten. Neither inferred private-tail counts nor new body/privacy permission follows. See Runs for limits.
 
 ## Run workflow
 
@@ -111,7 +149,13 @@ Run = Recipe + Trace + Control
 3. Inspect `view=trace` when retained observations or attention matter.
 4. Inspect `view=control` before diagnosing service readiness, stale work, or saturation.
 5. Send `message` only for an action declared and consumed by that controlled Recipe.
-6. Use terminal state, result, declared artifacts, and execution evidence to prove completion.
+6. Use terminal state, result, declared artifacts, and execution evidence to prove completion. When an outcome includes a retained primary-source, declaration-inventory or diagnostic-metadata reference, use that exact reference for further reading, not guessed captures or sibling files. Literal previews may be clipped; their field/range/counts describe what was shown. Diagnostic sources contain recorded command/error/failure-reason metadata only, not complete primary output; other recorded fields may be referenced without being shown. Artifact inventories list declarations only: they do not assert that target files exist or were produced, or grant body-read permission. Explicit unavailability has no guessed legacy body/path fallback.
+
+Compact launch receipts include `run_files` as nested block YAML containing the exact selected observed location values, labeled observed locations/mutable for the exact launched Run generation when the current session and physical identity agree; otherwise they report unavailability or whole-row omission. Machine `file_navigation` details stay JSON-compatible; saved terminal messages retain their own original encodings. Selectively ordinary-read those starting locations when needed; layout/size hints are not body, privacy, terminal or native proof. No evidence bodies or session-wide catalog map are read to build this row. New terminal packets also freeze bounded location rows for captured completion members at fresh current-session admission. Each shown result keeps its whole Run-file row or explicit per-record omission; wholly omitted results stay covered by result omission/inventory. This describes Run-row coverage, not a complete file/tree inventory. Older captured formats retain their original shown/omitted/total counters; unavailability remains explicit. Ordinary-read selected paths only when needed. Packet reload/render never refreshes sources, and old absent/request-only formats keep their text. Source/npm SDK verifies an explicitly requested ordinary read from a delivered terminal result path; this is research, never routine completion polling or new primary/privacy/clock/native authority. Use the request only for file investigation, not routine completion/status polling. Copied locations/hints remain data, never transferred scope; older batches keep their original text.
+
+For selective investigation of already cataloged files, use `inspect target=runtime view=runs verbose=true`, then ordinary file tools on its current-session root-first navigation. Ordinary maps keep latest-registration order between roots and prioritize known failed subtrees within each root. For a failed investigation add status=failed: inventory is filtered, while the full owned map prioritizes observed failed subtrees across roots, always ancestors first. Priority uses only exact-generation matched inventory observations, not complete terminal truth. Launches and compatible singleton attachments populate the catalog; reads do not backfill missing locations. A `catalog: unavailable` launch warning is not workload failure: do not spawn again merely to repair navigation. The starting map's format hints do not certify syntax, encoding or complete output. See [Runs](./references/runs.md) for selective recorded-capture research and resume boundaries.
+
+Trusted parent-session shutdown keeps the existing Kill attempts for quit/reload/new/resume/fork; a Run is not promised to survive session replacement. This is logical-session ownership, not independent PID-bound ownership for parallel hosts with the same ID. A teardown report is not scope closure or crash/hung-host cleanup, and bare AgentSession.dispose alone emits no shutdown. See the Runs reference for the boundary.
 
 A Run exposes only `recipe`, `trace`, and `control` views. Control is bounded actor-local input, not peer messaging or chat. See [Runs](./references/runs.md).
 

package/node_modules/@llblab/pi-actors/skills/actors/references/diagnostics.md

@@ -9,8 +9,28 @@ inspect target=recipes view=status
 inspect target=recipes view=doctor identity=<skill>/<recipe>
 ```
 
+Compact Recipe/Run/tool replies use flat AX fields without changing their existing evidence or authorization. Required/optional tool arguments are sequences, with none distinct from unknown. Focused source_location remains one exact literal value. Run compact replies still identify only run/view: request verbose for structured evidence, and tool schema remains structured even without verbose. Compact text selects at most one existing hint; only exact read-only recipes doctor/imports/summary inspection literals become typed next nodes. Other advice stays instruction content with its original Markdown, never executable metadata or authority to rerun work/register a tool. The full original next_actions array remains in details; do not infer callability from an advisory string.
+
 Use the focused doctor form for one intended identity. It reports active-Skill ownership, exact resolvability, partial-catalog state, component status, portable source location, resolution generation, any rejection, and bounded next actions. Use the unfiltered doctor only for catalog-wide diagnosis. A partial catalog does not imply every exact component is unavailable. If the owning Skill is inactive, report that blocker rather than locating and running its helper manually.
 
+## Inspection request refusals
+
+Locally authored target/view/identity/source/tool/schema refusals now show AX fields and actual supported-value lists. target_kind identifies only the selector family; no ownership, no-effects or native claim follows. A missing tool retains the no-spawn-substitution safety note and a read-only Recipe doctor next. Unavailable callable schema preserves selected callability/activation facts and one read-only tool-status next. Generic syntax/view guards add no routine action. An oversized selected scalar/action is omitted whole with shown/omitted/total counts under the shared16KiB text bound; those counts cover fields/actions, not hidden text length. A next_action omission record is not an executable next node. Opaque multiline labels are not parsed into commands.
+
+This applies only to errors authored by inspect itself. Session/scope/source/dependency errors retain their owning contract and original propagated values/causes; existing fail-soft catches are unchanged. Discovery/status callbacks may already have run before a refusal. Diagnose through the original owning surface rather than treating an error as proof of no effects or retry permission.
+
+## Control request guards
+
+Locally authored unsupported runtime action, unavailable runtime port, unavailable Run generation and undeclared actor-local action errors now identify caller target/action/result and actual supported_actions/available_actions lists. A singleton remains a list; none differs from an explicitly omitted group. These are diagnostic options, not a command, readiness proof, native receipt or automatic replay instruction. Whole target/list groups fit16KiB including public spacing or have explicit selected-field/entry omission coverage; malformed selected text is unavailable without source repair or hidden character counts.
+
+This does not restyle normalizer/session/scope/dependency failures, expose status/input/owner/generation/correlation or change the existing actor-local awaited-send error boundary. Status/getter/legacy join observations can fail before a local diagnostic; runtime callbacks can throw after effects. Preserve those original exceptions and diagnose the existing owner rather than broadening a catch or assuming no effects.
+
+## Spawn request guards
+
+The facade's own unsupported state_dir and invalid as errors use field/result records; as is selected caller input, not an admitted Run or generation. Namespace/id refusals show accepted_format and, for invalid ids, the existing ASCII character rule. Whole values fit16KiB including spacing or are explicitly omitted; malformed selected text is unavailable without repair or hidden character counts. Opaque multiline value labels are not actions, and no routine next/retry/no-effects receipt follows.
+
+The actual host clones/validates public arguments first. Its unchanged schema rejects unsupported state_dir before the facade and keeps the SDK's own validation text; do not bypass that boundary to obtain AX. Direct facade getter/method/coercion failures, Recipe/session/launch/draft errors and post-launch effects keep their original owners and behavior.
+
 ## Persistent tool failure
 
 ```text
@@ -18,6 +38,18 @@ inspect target=tool:<name> view=status
 inspect target=tool:<name> view=schema
 ```
 
+Successful normal register/update-or-persisted text now separates tool/result/source/callable_now, lists required/optional args and warnings, and keeps one prior hint. Non-template source references are whole literals; safety warnings take budget priority. Whole selected fields/groups/actions fit16KiB or carry omission counts; malformed selections are unavailable without repair or hidden character counts. Invocation advice is opaque instruction rather than an automatic call. The unverified branch retains one typed read-only tool-status next; all existing next_actions/details remain. Post-persistence callbacks/formatting can still fail with their original values, so text does not add rollback, fresh activation or retry guarantees. List/delete/draft/transaction errors and notices remain separate.
+
+Listing returns the original current Map's sorted names with selected-name coverage. The entire selected group is shown or explicitly omitted/unavailable within16KiB; none means the selected list is actually empty. This is not active-tool/callability, complete-host or lifetime inventory evidence. Delete returns tool/result with the original manual reload note as opaque instruction. A missing current-map entry does not delete an orphan recipe file or prove no effects; a returned deletion is not complete loaded-registry removal. Do not reload or repeat automatically to change that presentation. Errors after unlink/map/active-set/notify effects keep their original values, without a new wrapper/rollback.
+
+Draft-promotion success now uses selected tool/result/source=draft/callable display and the first prior hint, without adding undisplayed args/defaults/path/body or activation-boundary facts. Existing zero/opaque display and later getter disagreement are not repaired into a new Boolean/readiness claim. Scalar/action fields are whole within16KiB or explicitly omitted/unavailable. Only the producer's exact canonical tool-status hint is typed read-only; invocation advice stays instruction. Original display conversion may still fail after persistence/map/activation/notify effects, including Symbol or unprintable values; preserve that failure rather than replaying or importing normal-registration rollback behavior.
+
+Four local source-mode refusals now show field/result plus replacement fields, accepted reference forms, mutually exclusive source modes or inherited args/async fields. Previous repair advice remains opaque instruction; it is not a typed mutating retry/update or no-effects proof. These fixed diagnostics neither echo source values nor restyle normalization/resolution/admission/transaction failures. Outer name locks may already have observations before a local error.
+
+The host first clones/coerces/validates args. It rejects unsupported values/object-valued from before execute, but numeric from can normalize to a string; an unnamed valid request can still return the existing name list. Direct getter/descriptor/trim probes are not SDK-cloned DTOs. Do not override schema or force a public error solely to obtain AX text, and do not infer the caller's original type from post-validation data.
+
+Ordinary invalid-name, reserved-name and new-registration missing-source errors now use field/value/result or a real source-mode sequence with prior opaque repair advice. No raw caller name/source/body is newly exposed. Reserved selected display fits whole16KiB including spacing or has scalar omission/unavailability; this is not hidden character loss or ownership/invocation proof. Empty-name listing and existing-tool update reusing source remain unchanged. Normalizer/reserved-set/resolution/authoritative/blocker exceptions retain original behavior; a dependency blocker is not reformatted as an owned refusal. SDK numeric name coercion may reach a different local guard than the direct request, while object-type schema rejection stays outside execute. Both ordinary and draft already-registered errors now use field/value/result with exact Use update=true to overwrite instruction content. Distinct Map/authoritative-file/exists/blocker/update checks remain; the selected display does not disclose source/recipe bytes or certify no effects, rollback, fresh host membership or overwrite permission. Whole scalar omission/unavailability and raw observation/coercion failures remain explicit and unchanged, respectively. Nested Recipe-shaped template, empty sequence and unsupported template type now have fixed template/result AX errors and real supported-type choices, retaining prior correction as opaque instruction without supplied body/source echo. External expansion/getter failures stay raw. Front null/empty deletion, undefined/inherited source and later authoring errors are not reclassified; a numeric SDK template may be coerced to a command string rather than reaching the direct unsupported-type refusal. Later non-object defaults, missing command description, authoring-stage null and missing final template now use fixed field/result without supplied values. Preserve the error's actual stage rather than treating null globally invalid or every missing source as a late template failure: host defaults schema rejection, front deletion and earlier missing-source refusal still precede or bypass these guards. Schema argument/description/default/retained-template observation faults keep their original owner and values. The delegated-source runtime-owned-default-key refusal now names the old first selected key only with fixed defaults/result and opaque remove-default/retry advice. Key order and complete prior default copy remain; do not infer a complete key listing, supplied values, early effect-free rejection, global command-template ban or permission to repeat. Host SDK preserves selected-key error normalization without granting readiness or overwrite authority. Draft outside-root/current-not-found diagnostics now identify field draft and only the original allowed-root/resolved-path literal; root refusal does not add the refused caller path. Whole references fit16KiB or are explicitly omitted/unavailable without repair/private counts. Old summary hint stays instruction content, not an automatic call/listing guarantee. Getter/resolve/relative/dot-prefix/exists behavior and raw faults remain; not-found text is not stronger absence/native/host proof. Public from-normalization wrapper now reports only original displayed source/reason/legacy active_skills_summary and opaque doctor instruction, with whole-field omissions/unavailability under16KiB. Inner normalizer errors, Error.message.trim/String and old display/summary/doctor observation order remain. Do not parse comma summary/body Next labels, infer discarded counts/private causes, fix undefined/source-hint disagreement or automatically execute advice; other validation/transaction errors stay separate. Normal candidate-admission refusal now uses field recipe/result and opaque diagnostics_summary, plus old displayed source/legacy summary/instruction only when the old requestedSource branch is truthy. Preserve pre-Error diagnostic join/String ordering and original bounded upstream diagnostic text, including explicit unavailability for malformed selected clipping; do not reconstruct a full list/body/cause or infer no effects, rollback, current readiness or retry permission. Draft invalid-Recipe raw/candidate refusals now likewise use fixed draft/result plus old optional reason or joined diagnostics only, not new paths/bodies/causes. Separate raw read/diagnose calls, reason truthiness, original draft Error-before-join timing and upstream4096UTF16 candidate cap stay unchanged; malformed selected text is unavailable without repair. This neither merges normal/draft policy nor proves no effects/rollback or authorizes retry. Outer registration transaction-failure text now identifies old stage/resolution_generation/legacy summary/error only after existing cleanup. That generation is resolution-context display, not Run scope/current host epoch. Error.message/String behavior and all restoration/unlink/Map/reactivation/setActive faults remain exact; a formatting error can follow cleanup, and legacy inner rollback/advice text is not authoritative rollback/readiness or retry permission. Whole selected fields fit16KiB or show omission/unavailability without repairing private data. Inner activation/persisted-admission errors and receipts stay separate. Registry activation/promotion/deletion notifier text now uses old report identity/tool display only, not new readiness/removal evidence. Original info type/positions/hasUI gate/callback exceptions remain; ordinary UI has no borrowed model16KiB limit. Multiline text stays literal/native-wrapped, malformed selected name is explicitly unavailable, and RPC message forwarding does not certify display or handling. Loaded terminal/phone remains separately gated. Recipe registry watcher warning/refresh notices now use AX report plus original opaque repair instruction, without changing direct ctx.ui.notify, pending/dedup/load/callback failures. The old ~/.pi/agent/recipes report is not freshly verified root metadata; it does not authorize restart, register_tool replay or reload. Startup registry warnings now expose category sequences including singletons, preserving original selected diagnostics and existing shadow/bash suppression. Authored labels stay inside values; malformed selected text is unavailable, no borrowed model cap or recovered private tail. Doctor advice stays opaque instruction, not automatic inspection. Formatting still precedes runtime.notify/hasUI; a report/fault does not undo prior scan/registry effects.
+
 Distinguish persistence, registry admission, host registration, active-tool membership, and `callable_now`. Confirm the source identity, effective caller schema, separate tool/spawn usage, and last launch kind when exposed.
 
 If persistence succeeded but callability is false, do not use `spawn` and claim the tool worked. Follow the reported activation boundary or stop.
@@ -33,6 +65,14 @@ inspect target=runtime view=status
 
 Use Recipe view for captured identity/launch evidence, Trace for bounded observations, Control for readiness/capacity/stale work, and runtime status for kernel-level health. Treat retained-history completeness honestly.
 
+Compact runtime replies now use flat runtime/status, runtime/runs or runtime/triage records from the same existing facts. runs counts the full current-owner inventory, not a display page; verbose file navigation has its own independent bounds. Triage scalar counts need not equal its40displayed detail rows. This is not a new Run status/snapshot, duration, body source or routine polling route. Core callback errors keep their diagnostic content and original error forwarding. Completion recovery reports the original pending/evidence/reason without forcing resend; an idle batch shows delivery accepted only after durable acceptance, not as proof of model handling. Teardown killed/failed/skipped/discovery counts and a whole literal summary path are a teardown report, not whole-scope closure. Stored packet/history text is not regenerated.
+
+## Watcher and automatic retirement notices
+
+Watcher diagnostics use watcher/scope/path/diagnostic/recovery records. Exact paths are literal values, not commands or body permission. Degradation preserves the existing reconciliation/rearm guidance; rearmed reports restored acceleration only. IDs/timestamps/code/scope and bounded history are unchanged, not complete lifetime evidence. Diagnostic bodies are opaque, including apparent next/tool labels.
+
+Automatic retirement reports stop request returned, cancellation reported, skip or failure, with closure unconfirmed. Neither a returned callback nor a truthy cancellation report proves owned-scope termination. stop path failed includes notification failure after earlier stop/cancel effects; do not blindly replay work or infer no actuation. Candidate/attempt/callback/result/error behavior and lower-layer information loss remain unchanged. This is separate from manual archive/prune, native closure and actual lifecycle receipts.
+
 ## Safe failure protocol
 
 1. Keep the exact intended Recipe/tool/Run identity.

package/node_modules/@llblab/pi-actors/skills/actors/references/runs.md

@@ -10,7 +10,9 @@ spawn recipe=<skill>/<recipe> values={...} as=run:<id>
 
 Use the owning capability Skill to choose the Recipe and capability-specific values. Retain the returned Run id. A spawn result reports `launch_kind: "spawn"`; it is never evidence of registered-tool invocation.
 
-A rare Skill Recipe may declare `singleton: true`. Do not pass `as`: the runtime derives `run:<skill>` plus the canonical `<skill>/<recipe>` identity, allows at most one singleton Recipe per Skill, and returns the same compatible healthy active Run instead of launching a duplicate. Contradictory Recipe identity, startup values, Control, or ownership fails closed. Delegation inherits both singleton identities instead of retargeting them. A terminal result is never reused; after its runner exits, restart keeps the logical Run id but creates a new fenced generation. Continuity still depends on actor-owned validated state, not the Run id alone.
+A rare Skill Recipe may declare `singleton: true`. Do not pass `as`: the runtime derives `run:<skill>` plus the canonical `<skill>/<recipe>` identity, allows at most one singleton Recipe per Skill, and returns the same compatible healthy active Run instead of launching a duplicate. Contradictory Recipe identity, startup values, Control, or ownership fails closed. Delegation inherits both singleton identities instead of retargeting them. Runtime tool failures after executor entry or async launcher handoff retain their original error/cause/details instead of guessed argument-repair guidance. A later missing-value failure can follow partial work; inspect the existing evidence rather than blindly replaying the invocation. Pre-dispatch argument guidance is not proof that no preparation effect occurred, and dispatch is not actuation or closure. Configured retry policies remain unchanged.
+
+Compact spawn/async-tool receipts use flat Markdown-list fields: run, state, launch_kind and admitted optional facts; model/thinking policy source-value relationships may nest. The displayed Run key has no duplicated namespace. Multiline values preserve their Markdown content, and structured/verbose data remains unchanged. A compact attachment receipt explicitly says existing Run reused; that reports the backend's reuse fact, not another generation, readiness promise or scope proof. A terminal result is never reused; after its runner exits, restart keeps the logical Run id but creates a new fenced generation. Continuity still depends on actor-owned validated state, not the Run id alone.
 
 ## Observe
 
@@ -22,8 +24,50 @@ inspect target=run:<id> view=trace
 inspect target=run:<id> view=control
 ```
 
+Fresh root completions use index-first YAML frontmatter (index, run, state, admitted kind), followed by raw left-edge Markdown. No external #N heading, result:/preview: wrapper, list nesting, whole-body fence, Batch caption, members wrapper or routine outer counter is added. Primary/final Actor response uses kind:primary; explicit error/failure diagnostic text uses kind:diagnostic, never a launch command. Untracked fallback has no kind and keeps unknown original completeness/privacy explicit outside YAML. Known cut loss is [N characters omitted] at the cut, with no extra ellipsis or body clipping counters/flags in metadata. Unknown upstream loss remains separately unknown and does not assert a known positive omission. Exact source/generation/parent/location references remain in complete model content, with whole references or explicit omission, captured inventory recovery and non-done omitted states. The compact TUI independently renders literal headers/markers and native Markdown bodies from validated content-bound blocks; only whole header reference/location rows and framing are hidden. Expansion and invalid/missing hints reveal original text. Hashes/layout/markers establish consistency/correlation only, never authentication, read/action permission, acceptance or native truth. Authored YAML/next/tool/batch/omission lookalikes stay body content. Fresh packets share48KiB UTF-8 including service data, equally between up to64candidate rows, with256captured members and no redistribution of unused shares or fixed16KiB/2KiB text cap. Full admitted text fitting its share without upstream uncertainty has no cut marker; otherwise use the scalar/CRLF-safe prefix and exact retained-source loss. Allocation/text is frozen at admission; rendering/recovery does not reread sources or reallocate. Unsupported Pi event/control output is withheld. Source basis stays in reference metadata; retained structured coverage facts are not exposed as YAML clipping fields. Pending/queued/presented older formats—including #N records and the first frontmatter draft—keep exact bytes, hints and budgets. Encoding names are storage replay data, not public product choices, source permissions or work authority. No standing full-map instruction or automatic research/read follows; use selective same-session investigation when needed.
+
+Current completion index values restart within each packet; they are not session-wide historical references. Completion streams are adopted but not enabled, and no start-stream command is available yet. Do not infer an active stream or reset a counter from missing metadata or a pending target, and never relabel older saved packets. The kernel-only allocator now commits fixed scope/order/indices, the counter and first-packet target activation together, and an internal fresh-session bridge can use it after current manager/generation admission. The default runtime does not opt in; no public action exposes it. Event reason or a matching ID alone is insufficient. Old callbacks/wrappers cannot act after replacement; fresh wrappers must belong to the current original manager. Startup/reload/resume and ambiguous imports remain closed to stream capture/ACK, without changing saved packets or inferring a counter from history. Its whole-range exhaustion or admitted counter unavailability yields a frozen unknown index (quoted "?" in fresh YAML; #? in older saved layouts), never partial indices or an automatic fresh stream. Old packets retain their original scope while a pending switch waits; uncertainty does not permit reallocation. Stream state outlives packet cleanup/receipt rotation. Malformed/missing state remains refused, not a zero counter or proof of non-connection.
+
+Fresh explicit agent Trace summary clips use prefix… [omitted: N chars] from normalized retained turn; upstream [omitted: unknown]. The prefix is at most160UTF-16 source units, shortened by one only to keep an original surrogate pair intact. N counts Unicode code points removed from the normalized already-redacted retained turn, not its earlier4000-unit/session loss or a complete Actor answer. Malformed retained text has only [omitted: unknown], not a repaired prefix or invented gap. This read-time projection leaves original detail/source/history and short valid summaries unchanged; authored marker-looking text does not become metadata or refreshed saved content.
+
+Agent Trace ids are opaque recorded-entry references within the current Run's command/file/session namespace, not chronological numbers. Native keys retain the same entry across sibling-session growth and manifest reorder; changed admitted entry/session identifiers change the key, without certifying arbitrary file edits. Ambiguous/private/degraded metadata has only bounded record/read-local fallback, and missing-id or oversized source behavior is unchanged. Do not parse an id as a path, treat it as original privacy/immutability or use it to recreate live authority.
+
 Trace is bounded retained observation, so read its completeness summary. Prove final outcomes with terminal status, result, declared artifacts, and execution evidence rather than assuming retained Trace is exhaustive.
 
+## Attention Reference Bounds
+
+Fresh source notify/followup and explicit steers use block-YAML metadata with opaque selected body text. Metadata-only output is bare; an actual body follows opening/closing `---` with no added outer indentation or compiler fence. Artifacts precede Run files as typed shown/omitted/total mappings with whole path sequences. Counts describe unshown declared unique paths, not characters, missing files, production or body permission. Consider only the first eight unique nonempty declarations per group before filtering malformed Unicode; do not repair a path or fill its slot from a later declaration. No target existence/body is inspected. Steers alone share16KiB UTF-8 across the complete serialized metadata, delimiters, body and minimum later-group coverage; raw malformed/oversize essentials refuse before reference reads; unfit essential text/coverage remains retryable pre-admission unavailability, never a partial checkpoint. Ordinary notify/followup keeps its existing independent field/slot limits without a new shared16KiB/48KiB cap or path shortening. Source/unit proof is not compiled/actual-default-entrypoint or loaded-host acceptance.
+
+A legacy body keeps at most500UTF-16 source units with surrogate alignment and no whitespace/Markdown normalization. A clipped value ends with U+2026 outside its source literal when literal rendering is used and has [omitted: unknown]; malformed visible text is unavailable rather than repaired. A separate body-basis/upstream note means original completeness/privacy is unproven, not necessarily positive loss. Canonical Trace still has no body payload. Saved envelopes retain their exact content through pending/queued/presented recovery; an admitted event is reused before any new formatting, even if its current source would now be malformed. Neither restyle nor blindly replay work.
+
+Ordinary notify/followup selects this AX layout only for new sink delivery. Notify stays visible status without waking a model; followup alone adds ordinary non-displayed pi-actors-run-trace context with the same content and original event details. Physical order, seen-id handling, startup priming, sink failure/effect semantics and wake policy are unchanged. Committed strings are never regenerated. There is no format-selection option or alternate new-message layout; saved envelope content remains exact without passing through these formatters. Fresh urgent diagnostics use AX event/attention/stage records. Admission reports remains retryable, not no effects or a new workload retry instruction. A failed send is request failed with delivery/presentation unconfirmed; it does not prove the model received nothing. Unknown/conflicting recovery retains phase queued with the observed evidence status/reason and does not force resend. Diagnostic values preserve raw inner Markdown/CRLF under240UTF-16 units, aligning an original pair; clipping uses boundary … and [omitted: unknown], while malformed visible text is unavailable without an invented gap/count. This is current UI presentation only. The journal last_error keeps its earlier whitespace normalization/trim and4096-unit message-only retention, not a full original Error/cause or authoritative count. This creates no new source, native authority or retry service.
+
+## Investigate Known Files
+
+Compact spawn/async-tool receipts now carry `file_navigation`: observed canonical starting locations for that exact generation, admitted against the current session before and after observation. It needs no catalog/body read or original producer key; missing/stale/foreign locations stay unavailable, and oversize rows are omitted whole within the compact card budget. Locations are mutable research data, not body/privacy/terminal/native proof. The compact run_files value keeps the whole selected observed location data in nested block YAML or reports a whole Run-row omission with shown/omitted/total counts, within the shared16KiB bound including response spacing. JSON-compatible details and saved terminal-packet encodings are unchanged. The optional current-session full-map command remains available but is not repeated when a complete direct location row is actually shown; absent/unavailable/omitted rows retain one next node naming tool=inspect, target=runtime, view=runs, verbose=true rather than disguising a command as observed data. It never executes automatically. New completion packets also capture bounded member location rows once, in root-first order with observed failed subtrees before peer children. They use only the remaining shared model budget after outcomes, with separate honest Run-row counts. Reload/render never reads sources or refreshes that data. Old absent/request-only packet formats keep their earlier text; source/npm SDK verifies an explicitly requested result read from a terminal row, without routine polling or original producer keys. Inherited locations/hints never transfer ownership.
+
+For an explicit file investigation, request the existing management route:
+
+```text
+inspect target=runtime view=runs verbose=true
+```
+
+Its `navigation` selects only the actual current logical session's already cataloged, generation-checked directories. Start at the root's context index/result, then follow selected locations with ordinary file tools; no original producer key is needed. Resuming the same saved session after restart retains this research scope; a new/forked/cloned session does not inherit it through copied history or paths.
+
+The ordinary map keeps independent roots latest-registration-first and puts known failed child subtrees before other siblings without moving a descendant ahead of its ancestors. For an explicit failed investigation use inspect target=runtime view=runs status=failed verbose=true. This filters inventory, not navigation: the full owned map then puts observed failed root subtrees first, with recency as the stable peer tie-break. Its priority.root_order is latest_registration or failed_subtrees_first and priority.basis=observed_failed_rows; missing/unmatched observations remain unranked, not proof of success. Ordering grants no ownership/terminal/native authority and does not read extra evidence or rewrite the catalog.
+
+This bounded map marks file_inventory_scope=canonical_starting_locations and reports file locations, observed sizes and format_hint (json/jsonl/text). Hints describe the expected layout, not validated syntax/UTF-8 or complete output; it is not a full file inventory, body, original privacy, terminal/clock/native truth or authority to change state. Missing/nonregular/stale locations stay unavailable, whole-row omission counts are explicit, and corrupt/missing catalogs report `catalog_unavailable` without repair or turning healthy Runs into failures. New launches and explicit compatible singleton attachments register their exact existing generation; reads never scan/backfill missing entries. A `catalog: unavailable` launch warning means that separate registration attempt did not complete, not that the work failed. Do not relaunch merely to repair the map; even failed publication can leave committed catalog bytes. Current ordering covers directly owned rows and their exact same-session parent links, not a complete cross-session descendant tree. Compact/default inspection still does not build a map. Launch text offers that request as a fallback when no complete direct row is shown; existing new-outcome formats retain their optional request. Neither embeds a session-wide map or file bodies.
+
+The published_sessions link, when physically present, locates the fixed session catalog under the owned Run root. No semantic index or original producer is required for this location or ordinary read. Presence is not certified catalog content/privacy/publication, and it does not enumerate raw session directories or automatically read nested previews. Missing/nonregular/symlinked locations have no usable path; never guess another location from that refusal.
+
+For explicit recorded-capture research, read the mapped execution manifest, select the recorded command/attempt/stream reference and use ordinary file tools selectively. Keep the canonical capture layout under the mapped owned Run root; recorded strings are not permission to follow arbitrary declarations or leave that root. Distinguish reported saved/observed bytes and incomplete persistence from the current file size; reading a file does not certify complete primary output or original curated privacy. This is an explicit research choice, not an automatic fallback when an outcome's retained primary source is unavailable.
+
+## Parent Shutdown
+
+Existing parent-session teardown applies at trusted SDK quit/reload/new/resume/fork, including session replacement rather than only process exit. The current lifetime accepts fresh matching SDK context wrappers once; stale/replaced callbacks cannot act merely because a logical ID matches again. This uses existing exact-session-owner and Run-generation Kill guards, not delivery ancestry or a global PID scan. UI callback failure does not itself kill Runs or remove their parent shutdown binding.
+
+Do not infer successful native closure from a teardown count, signal attempt or status. Abrupt Pi death, hung shutdown and bare AgentSession.dispose without the trusted event remain outside this repair. Logical-session ownership also does not isolate parallel Pi hosts reopening the same ID; no host-instance ownership or new native supervisor is introduced. Do not repeat destructive work from a missing report or assume stream/timing authority from shutdown binding.
+
 ## Control
 
 Send an actor-local action only when the root Recipe declares and implements it:
@@ -34,8 +78,18 @@ message target=run:<id> action=<declared-action> input={...}
 
 Inspect Control when readiness, capacity, stale work, or saturation matters. Put large data in an artifact and send only a bounded reference or instruction. Use runtime-owned termination for a stuck Run rather than inventing undeclared service actions.
 
+Read a compact Control receipt as a flat Markdown-list record, not a raw state dump: run/action identify the request; result, delivery and handling keep their stage meanings. Queued/delivered leaves handling unconfirmed rather than guessing the current journal state. The displayed run name omits its redundant run: prefix; actual next-action targets retain canonical run:<id> syntax. Multiline Markdown values are indented without injecting record nodes into their content. At most one next node describes an inspect tool/target/view; an unrecognized advisory is kept as instruction text, not guessed tool arguments or automatic execution. A kill attempt leaves full termination unconfirmed, regardless of legacy stopped/killed flags; Trace can record the attempt but cannot prove full-scope closure. Use the one contextual next action only when deeper evidence is needed; changed ownership/generation requires fresh owned inventory, never a blind retry. Request verbose JSON on the original action when full detail is needed, not by repeating a destructive action. An error after actuation can retain partial effects. Even delivery_failed can coexist with a recorded handled Control; use its existing admitted correlation and owned Control inspection when available, not automatic replay. Kernel exceptions retain the original transport value and later failed-status-recording errors, including separate FIFO write/close faults, without erasing partial effects. Their cause/errors chains are private diagnostic evidence, not a newly exposed tool schema or handling/closure receipt. Public actor-local dispatch exceptions remain failures, with a compact conservative message: delivery and handling unconfirmed, effects may already exist, do not repeat automatically. Use its fresh-owned-inventory hint only when investigation is needed, then select currently owned evidence; it is not routine polling. Saved ids/generation and raw causes are withheld even in verbose because admission-time scope does not prove reply-time scope. A long request target is wholly omitted with a separate run_omission reason/shown/omitted/total record under 16 KiB, never cut into a misleading reference. Public errors remain failures and use the same flat AX record with a multiline warning and an owned-inventory next action; saved ids/generation/raw causes are still not exposed. Missing admission correlation is never guessed. The awaited sendRunControl facade now retains its surfaced admission/delivery rejection plus a later lifecycle-release fault as ordered private AggregateError errors/cause, without flattening or coercing the original. A sole request/release error remains exact, including undefined, and handled/delivered facts are not rolled back. The existing await/lock interval is unchanged: no kill-independence, exhaustive release/native closure, current reply-scope or lower-layer already-masked cause is recovered. A missing Trace or correlation does not prove no action occurred, and archive/prune failure can follow a move/removal. Verbosity never grants ownership of replacement/foreign state: changed-owner/generation refusals omit that replacement status in public details/JSON as well as compact text, retaining the refusal and its safe inventory follow-up.
+
+Manual archive/prune keeps its existing terminal/owner/generation/scope checks. Errors can follow an archive move, preserved artifact copy or completed directory removal. Kernel preserves a single surfaced rejection exactly, including primitive/undefined/original AggregateError; if later failure-text formatting, failed-record persistence or lock release also fails, ordered private cause/errors retain the original plus those later failures. Journal append/release has its own nested boundary; original aggregates are not flattened. A committed queued row may fail release before operation admission, while handled bytes/effects may exist before a later recording/release error. These are separate facts, not rollback, an atomic receipt or permission to repeat retirement. Inspect only available owned evidence selectively; no Run-local Trace after prune, missing correlation or exhaustive cleanup/native closure is promised. Automatic age cleanup remains its existing best-effort policy, not a new public error archive. Underlying synchronous locked mutations also retain exact callback/release failures in a private ordered aggregate without coercion/flattening or re-execution; callback-written bytes may already exist. A normal return, sole callback failure or sole release failure stays unchanged. This is neither asynchronous lock semantics nor successful-release/native proof, a new public receipt or recovery of an already-masked lower error. Atomic JSON/text replacement also keeps its exact surfaced rejection; a later retry-code accessor fault is retained privately after the original rather than replacing it. Existing bounded platform replacement retries remain unchanged and rerun neither preparation callbacks nor the containing operation. Replacement errors may follow committed bytes; no rollback, exhaustive cleanup or power-loss guarantee follows.
+
 Control is not actor chat, peer routing, or a task inbox. A Recipe import does not create a peer actor. Several actors/subagents require the `swarm` methodology in addition to these Run mechanics.
 
+## Tracked Completion Excerpts
+
+Fresh completion bodies place [N characters omitted] directly at a known display cut, outside YAML and without an extra ellipsis. N counts Unicode code points of already-admitted postprivacy text: the exported primary source, retained Actor response or named diagnostic field, not complete native stderr or discarded private output. Original source totals/ranges remain in structured retained bindings; they are not metadata flags claiming full output. Upstream/legacy completeness/privacy may remain explicitly unknown even when the retained text fits. Source references stay exact; whole unfit references are explicitly omitted, never clipped. Saved packets preserve their original text/count grammar, including old direct omitted:N chars fields. Do not infer missing original lengths, widen source retention or treat an ellipsis as completeness; capture/layout identifiers are not tool arguments or read/work authority.
+
+For an explicitly requested agent Trace view, clipped summaries show `[N characters omitted from retained turn; upstream count unknown]`. N counts only local display loss from the existing privacy-projected, whitespace-normalized retained turn; it is not a complete answer/session length. The source preview remains at most 160 UTF-16 units, aligned to full Unicode scalars. Malformed retained text reports `[omitted count unknown: malformed retained text]` instead; details/sources are not repaired. Short valid summaries and all previously saved completion/steer messages remain unchanged. This adds no automatic polling, retained body source or original-private-projection guarantee.
+
 ## Safety
 
 Operate only on owned Runs and their active generation. Never edit Run state to force an outcome, bypass process identity checks, or signal processes directly from UI/instruction code. Restart creates new generation-local evidence; inspect the exact generation before destructive lifecycle action.

package/node_modules/@llblab/pi-codex-usage/AGENTS.md

@@ -2,11 +2,11 @@
 
 - `Registry dependency`: Use published `@llblab/pi-command-fast@^0.1.0` with aligned registry lock metadata. Local folder links are only for explicitly requested development tests; rebuild the library's `dist/` after source edits and restore registry dependency/locks before consumer publication.
 - `Pi baseline`: Every declared `@earendil-works/*` peer requires ≥1.0.0. Keep Pi peer lock identities aligned and validate against that host generation.
-- `Domain DAG`: `index.ts` only re-exports the extension and public contracts; `lib/extension.ts` composes the Pi extension. `lib/usage-store.ts` owns persistence/leadership, `lib/query.ts` owns quota I/O, `lib/usage.ts` owns normalized reports, `lib/status.ts` and `lib/status-format.ts` own local UI orchestration and formatting, `lib/telegram.ts` owns optional registration, and `lib/fast.ts` owns Codex Fast semantics/request adaptation. `@llblab/pi-command-fast` owns command arbitration and generic JSONC override editing. Keep dependency direction acyclic; do not import `index.ts` from `lib/` or mix Fast persistence into quota coordination. Place domain tests in `tests/<domain>.test.ts` (or a domain-prefixed focused integration test); use independent names such as `invariants.test.ts` only for cross-domain invariants.
+- `Domain DAG`: `index.ts` only re-exports the extension and public contracts; `lib/extension.ts` composes the Pi extension. `lib/usage-store.ts` owns persistence/leadership, `lib/query.ts` owns auth candidate discovery and quota I/O, `lib/usage.ts` owns normalized reports, `lib/status.ts` and `lib/status-format.ts` own local UI orchestration and formatting, `lib/telegram.ts` owns optional registration, and `lib/fast.ts` owns Codex Fast semantics/request adaptation. `@llblab/pi-command-fast` owns command arbitration and generic JSONC override editing. Keep dependency direction acyclic; do not import `index.ts` from `lib/` or mix Fast persistence into quota coordination. Place domain tests in `tests/<domain>.test.ts` (or a domain-prefixed focused integration test); use independent names such as `invariants.test.ts` only for cross-domain invariants.
 - `Statusline-first scope`: Own usage state + usage mode: keep quota reporting zero-configuration and the optional Fast toggle focused on the existing terminal status.
   - Trigger: Considering new commands, menus, persisted settings, or notification output.
   - Action: Prefer deleting the surface unless it is required for the optimistic TUI status widget, the optional `pi-telegram` `/start` status-line mirror, or the existing argument-free `/fast` command. Register both `openai-codex` and `openai` provider handlers through `registerFastProvider` on session_start and release both on session_shutdown; never register `/fast` directly or filter Fast by model ID/auth. Fast persists solely as `serviceTier: "priority"` in the current provider/model override (never share preferences across providers with the same model ID); OFF deletes only that property. Preserve JSONC/unrelated settings, existing wire tiers, and usage refresh/Telegram. Apply lowercase ` fast` through the final terminal boundary; the optional Telegram row reads the active model's Fast preference at render time and appends plain-text ` fast` (or shows `fast` alone without quota). Toggle redraws without quota fetch or success notification. The library owns session WeakMap/reload arbitration, not Fast state. A Fast config read failure must not block usage status.
-- `OpenAI provider support`: Show the same Codex subscription quota for active `openai-codex` and `openai` models. Quota transport accepts `openai` subscription OAuth (guarded by `modelRegistry.isUsingOAuth`) and legacy `openai-codex` auth, with the Codex CLI fallback; never send `openai` API-key credentials to the ChatGPT quota endpoint or label Codex quotas as API billing limits.
+- `OpenAI provider support`: Show the same Codex subscription quota for active `openai-codex` and `openai` models. Recognize both Pi OAuth methods: legacy `openai-codex` credentials and compatible `openai` Sign in with ChatGPT tokens (guarded by `modelRegistry.isUsingOAuth` and a `chatgpt_account_id` claim/header). The newer `openai` token is scoped for `api.openai.com/v1` and rejected by `/wham/usage`, so record it as unavailable instead of sending it. Try legacy Pi auth, compatible new Pi auth, then the local Codex CLI `auth.json` directly before the preserved app-server fallback; never send `openai` API-key credentials to the ChatGPT quota endpoint or label Codex quotas as API billing limits.
 - `Optimistic refresh`: Preserve the last good statusline bar during refresh and transient failures.
   - Trigger: Updating quota polling or error handling.
   - Action: Do not collapse the bar while a request is in flight; only show `n/a` or `error` after repeated failures or no usable quota.

package/node_modules/@llblab/pi-codex-usage/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.13.4: Direct Pi/Codex Auth Hotfix
+
+- Fixed the primary quota request falling back to Codex CLI app-server when Pi uses the newer `openai` Sign in with ChatGPT login. The extension recognizes both Pi OpenAI OAuth methods, records the newer API-scoped token as unavailable for `/wham/usage`, and uses legacy-compatible Pi or local Codex CLI credentials for the direct request before the preserved app-server fallback.
+- Compatible credentials now supply `ChatGPT-Account-Id` from Pi headers or the token claim; API keys, non-ChatGPT CLI credentials, and expired tokens are skipped, and JWTs in endpoint error bodies are redacted. The app-server fallback and Windows executable resolution are unchanged.
+- No configuration changes or cache migration are required; restart Pi to load the updated extension.
+
 ## 0.13.2: Empty Quota Bar Hotfix
 
 - Aligned quota bars with rounded remaining percentages: when either window rounds to `0%`, its final segment disappears and the whole dual bar uses the error background, while the other half retains its quota. The 5-hour reset countdown follows the same zero boundary; near-full quota still rounds to the nearest 5% step.

package/node_modules/@llblab/pi-codex-usage/README.md

@@ -22,7 +22,7 @@ This repository is a minimal fork of [`narumiruna/pi-extensions/extensions/pi-co
 - Models under either `openai-codex` or `openai` show the same primary Codex subscription quota and `codex` status label (not OpenAI API billing limits)
 - When `pi-telegram` is available, the same compact value appears as `codex: <value>` in the `/start` menu status text for either supported provider
 - Additional returned quota buckets are ignored
-- Pi subscription auth from `openai` or legacy `openai-codex` is used first
+- Both Pi OpenAI OAuth methods are detected; legacy-compatible Pi/Codex CLI credentials are used for the direct quota request
 - Codex CLI app-server remains available as a fallback
 - Missing auth, subscription, plan, or quota windows are shown as `n/a`, not as an error
 - Successful updates briefly redraw the bar only when a 5% segment changes
@@ -137,7 +137,7 @@ codex error
 
 ## Shared Refresh
 
-[`index.ts`](./index.ts) is a re-export-only Pi entrypoint; [`lib/extension.ts`](./lib/extension.ts) composes the live extension. [`lib/usage-store.ts`](./lib/usage-store.ts) owns cross-instance quota coordination, [`lib/query.ts`](./lib/query.ts) owns provider requests, [`lib/usage.ts`](./lib/usage.ts) owns quota normalization, [`lib/status.ts`](./lib/status.ts) and [`lib/status-format.ts`](./lib/status-format.ts) own lifecycle and terminal display, [`lib/telegram.ts`](./lib/telegram.ts) adapts the optional Telegram row, and [`lib/fast.ts`](./lib/fast.ts) owns Codex Fast semantics and the native payload bridge; the shared library owns JSONC and command arbitration. Domain tests live under [`tests/`](./tests/) with matching names; integration tests name the domain whose boundary they exercise.
+[`index.ts`](./index.ts) is a re-export-only Pi entrypoint; [`lib/extension.ts`](./lib/extension.ts) composes the live extension. [`lib/usage-store.ts`](./lib/usage-store.ts) owns cross-instance quota coordination, [`lib/query.ts`](./lib/query.ts) owns auth candidate discovery and provider requests, [`lib/usage.ts`](./lib/usage.ts) owns quota normalization, [`lib/status.ts`](./lib/status.ts) and [`lib/status-format.ts`](./lib/status-format.ts) own lifecycle and terminal display, [`lib/telegram.ts`](./lib/telegram.ts) adapts the optional Telegram row, and [`lib/fast.ts`](./lib/fast.ts) owns Codex Fast semantics and the native payload bridge; the shared library owns JSONC and command arbitration. Domain tests live under [`tests/`](./tests/) with matching names; integration tests name the domain whose boundary they exercise.
 
 All Codex models and instances coordinate through `~/.pi/agent/tmp/pi-codex-usage/usage.json` (quota percentages and timestamps only, no tokens). The Claude extension uses its own independent file at `~/.pi/agent/tmp/pi-claude-usage/usage.json`.
 
@@ -169,12 +169,16 @@ The value is the same compact quota bar plus weekly reset countdown used by the
 
 The extension tries usage sources in this order:
 
-1. Pi's subscription auth from `openai` or legacy `openai-codex` (active model first)
-2. `codex app-server --listen stdio://`
+1. Pi's legacy `openai-codex` subscription OAuth, resolved through `modelRegistry.getApiKeyAndHeaders()`
+2. Pi's newer `openai` Sign in with ChatGPT OAuth, when its token carries a Codex account claim
+3. The local Codex CLI `auth.json` ChatGPT credential, read directly without spawning a process
+4. `codex app-server --listen stdio://`
+
+The `/wham/usage` endpoint accepts legacy Codex-shaped OAuth tokens and rejects the newer `openai` Sign in with ChatGPT token: it is scoped for `api.openai.com/v1`, has no `chatgpt_account_id` claim, and returns 401 even when an account header is supplied. The extension detects that token, records it as unavailable, and does not send it to the quota endpoint. Both Pi login methods are recognized; use `/login openai-codex` for a directly usable Pi credential, or keep the Codex CLI logged in for the direct local auth source. Compatible tokens get `ChatGPT-Account-Id` from Pi headers or the token's `https://api.openai.com/auth` claim. The Codex CLI source reads `$CODEX_HOME/auth.json` (default `~/.codex/auth.json`), accepts ChatGPT-mode credentials (`auth_mode: "chatgpt"` or legacy files without a mode), skips expired tokens, and never persists tokens.
 
 On Windows, the fallback resolves the native `codex.exe` from PATH or from the npm platform package behind a `codex.cmd` shim, then launches it directly without a shell. If Codex is missing, install it with `npm install -g @openai/codex@latest` and restart Pi so it inherits the updated PATH.
 
-Selecting an `openai` model enables the status and Fast toggle, and its ChatGPT subscription OAuth credentials can fetch the quota directly; a legacy `openai-codex` provider is not required. The extension uses Pi's resolved auth headers/token, checks `modelRegistry.isUsingOAuth` before using `openai` credentials, and keeps the Codex CLI fallback. OpenAI API keys are not ChatGPT subscription auth and do not expose these quotas; `openai` API-key credentials are skipped, not sent to the ChatGPT quota endpoint. Without subscription auth/quota, the quota status is `n/a` when both sources report an unavailable state. Fast works independently of subscription auth.
+Selecting an `openai` model enables the status and Fast toggle. The extension uses Pi's resolved auth headers/token, checks `modelRegistry.isUsingOAuth` before using `openai` credentials, and keeps the Codex CLI fallback. OpenAI API keys are not ChatGPT subscription auth and do not expose these quotas; `openai` API-key credentials are skipped, not sent to the ChatGPT quota endpoint. Without subscription auth/quota, the quota status is `n/a` when all sources report an unavailable state. Fast works independently of subscription auth.
 
 ## License