@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/docs/reference.md

@@ -13,7 +13,6 @@ delegate({
   cwd: "/optional/working/directory",
   model: "provider/model",
   context: "fresh",
-  async: true,
 });
 ```
 
@@ -22,15 +21,35 @@ canned profile. `name` is an optional display name, not a unique identity or rol
 Omitted cwd/model inherit the invoking session's effective selection. A supplied
 model must be available; there is no hidden alternate-model retry catalog.
 
+On hosts exporting Pi's native `resolveModelReference`, `model` also accepts
+`provider/model:thinking` (for example `provider/model:low` or `provider/model:off`).
+The explicit suffix overrides inherited thinking for that child only. Literal
+model IDs take precedence, including IDs containing colons or additional slashes;
+unknown IDs and invalid suffixes fail without fuzzy matching or another provider.
+Native resolution follows Pi's case-insensitive ID matching. Pi still applies the
+selected model's native thinking capabilities.
+
+Official Pi 1.3.0 and 1.4.0 do not export that resolver. Older fork runtimes also
+lack the export. Those hosts retain
+case-sensitive literal-ID overrides and inherited thinking; suffix requests fail with an upgrade
+message rather than being parsed by an extension-side replacement. This requires
+a host with the public resolver export, not merely a matching version number.
+
 Fresh context is the default. Fork uses the native conversation, including
 historical tool calls and results; restricting a child's authority does not erase
 the parent's evidence. Native Pi system/tool instructions and applicable project
 resources still apply. Forking does not authorize nested delegation.
 
-The default response acknowledges launch. It does not claim a model response or
-completion. `async:false` waits for this new work. Cancelling that owned foreground
-invocation requests stop; disposing the parent runtime detaches the observer
-without implicitly stopping accepted background work.
+The response acknowledges launch only. It does not claim a model response or
+completion, and no tool waits for child completion: the parent continues other
+work or ends its turn, and the completion notice resumes it. Aborting a parent reply
+with Escape does not stop already-launched children; use `stop` for one run. Exiting
+or replacing the parent session stops its children, including active work, and
+preserves their saved conversations.
+
+Completion notifications need a running main session. Ending a turn in a persistent
+TUI, RPC or SDK session is not parent exit. A one-shot print invocation exits after
+its final turn and stops any remaining children; it does not wait for their results.
 
 Only a main may delegate. Children cannot bypass the restriction through a hidden
 tool or programmatic invocation of `delegate` or `agent_runs`.
@@ -43,9 +62,8 @@ project, display name, or a different session forked from its history.
 | Action     | Purpose                                                                              |
 | ---------- | ------------------------------------------------------------------------------------ |
 | `list`     | Page through the current native owner's saved-run metadata, without output previews. |
-| `inspect`  | Read one run's immutable result and process/publication facts.                       |
+| `inspect`  | Read one run's result and process/publication facts without waiting or interrupting. |
 | `continue` | Supply a complete follow-up prompt using the saved child conversation.               |
-| `wait`     | Wait for an existing run; cancelling this observer does not stop its producer.       |
 | `stop`     | Request termination; inspect the actual process outcome afterward.                   |
 
 All actions except `list` require `id`. Use IDs returned by the tools rather than
@@ -63,7 +81,8 @@ missing session state is an error, not permission to start a different chat.
 If a handoff saved a run but failed before admission, retry `continue` with the
 exact same prompt after its actor and owned shells have exited. This resumes the
 saved run and queued command, not another successor. A different prompt is refused
-until admission or a canonical result. A missing queued command or ambiguous
+until admission or a canonical result; end the turn or do other work until the
+completion notice rather than polling. A missing queued command or ambiguous
 process claim requires inspection rather than automatic replay. If the prompt
 was lost from context, read its exact value from `launch.json` beside the run's
 reported `outputFile`; do not reconstruct or paraphrase it. For adopted legacy
@@ -72,13 +91,40 @@ not the retired legacy handle.
 Guidance that arrives after its run settles is reported as stale rather than
 starting untracked work. Inspection text exposes the guidance command IDs and
 admission states, native receipt publication and separately known process exit.
-Pending admission is not consumption. Inspect the result and send a new continuation
+Continuing active work returns a guidance receipt with the command ID; queue
+acceptance is not admission, and admission is not model consumption. Inspect the result and send a new continuation
 if guidance became stale; do not infer acceptance from the old completed output.
 
 A completed child can remain alive and messageable while its main remains
-attached. Once the main detaches or is proven absent, idle actors exit and active
-accepted work can finish before exit. Reload/resume uses saved state. There is no
-arbitrary idle lease that silently expires a child while the main is still live.
+attached. On a Pi fork with native working-session capture, a child that stays
+idle for five minutes (no run, turn, journal change, live viewer or owned shell)
+parks: it saves its exact working state and its process exits, while its intercom
+identity stays listed with no departure. Passive messages, topic updates and
+`last` reads do not wake it; the main answers `last` from the saved history, and
+without its main the read reports that history unavailable. Receipt reads also do
+not wake it and report `publication_unavailable`. A
+normal message, ask or continuation restores the exact saved state into a new
+process, which then receives retained messages in order. If the final save
+fails, the child records `park-failed.json` and nothing restarts implicitly;
+retained messages stay queued and continuing reports the failure. Official Pi
+keeps idle children resident. Parent exit or session replacement stops its actors and verified owned
+native shells, allowing native abort a short grace period before escalation.
+Actors also watch for parent death, including a hard kill. Ordinary extension
+reload keeps children alive because the parent has not exited.
+
+Under a fitchmultz/pi fork launcher that provides `ctx.managedHost`, the launcher
+that survives `pi restart` and `/restart` owns child lifetime instead of the worker
+process. A restart keeps children running; the replacement attaches and delivers
+their completions only after it becomes ready, and startup rollback keeps them too.
+Quitting, including quitting a replacement before it is ready, still stops them.
+After upgrading, relaunch the full CLI once: a worker started by an already-running
+older launcher has no `managedHost`, so restart still stops children with the old
+worker. Official Pi, SDK, print and RPC sessions keep worker-lifetime ownership.
+
+Resume the same parent and use `continue` with a new prompt to resume a saved
+child conversation. This does not replay interrupted tool calls or reconstruct
+an execution checkpoint: the child inspects the current work state. Saved
+journals and results are retained whether the child was active, stopped or done.
 
 ### Evidence levels
 
@@ -102,6 +148,27 @@ replacing its cwd/environment behavior. Arbitrary custom or remote bash tools
 remain owned by their extensions; the package does not claim cold-crash cleanup
 of those external processes.
 
+Stop and shutdown skip a saved PID only when it has exited or replacement is
+proven; uncertain ownership still reports a diagnostic without signaling it.
+A PID now owned by another user (permission denied) needs the same proof; it is
+never treated as exited. Linux cannot read another user's namespace identity,
+so such a PID stays uncertain there.
+On macOS, a UTC-observed process birth strictly after its record's write time
+disproves ownership even when the reused PID is no longer a group leader. This
+assumes native record timestamps have not been backdated and the clock did not
+move backward between process birth and publication. Missing timestamps,
+same-second uncertainty and timezone differences alone do not prove replacement.
+Linux uses its native process-clock and namespace identity instead.
+New Android actor and shell records also save a native monotonic-clock bound
+after process birth, qualified by the real boot ID and reader's time namespace.
+Only a conservative birth lower bound from native process elapsed age, in that
+same clock context, can disprove ownership. This survives controller clock and
+timezone changes without comparing `ps` boot-epoch dates with record timestamps.
+Unreadable ages, missing legacy clock bounds, different clock contexts and
+whole-second/tick uncertainty do not prove replacement; identity checks still
+fail closed rather than signal an unverified PID. An existing record without a
+clock bound remains usable when its original process identity is verifiable.
+
 ## `intercom`
 
 Use `list`, `send`, and `last` for normal coordination. `ask`, `reply`, `pending`,
@@ -110,17 +177,81 @@ for topology, target resolution, native replay, and delivery distinctions.
 
 ### Usage accounting
 
-The parent's token/cost totals are not automatically the entire workflow's spend.
-An asynchronous completion notice does not charge child usage to the parent.
-Finalized foreground or `wait` collection owns that accounting; repeated collection
-does not double-charge the same native contribution. Child journals retain their
-own usage. Metadata inventory and the human observer do not repair or collect
-accounting; explicit inspection can reconcile pending accounting without itself
-charging the parent.
+New calls do not attribute child usage to the parent's token/cost totals. Each
+child result records its own native contributions exactly once, and continuations
+add only newly published entries. Completion notices, inspection, reload and
+metadata inventory do not charge the parent. Explicit inspection can reconcile
+pending child accounting. Per-entry `result.contributions` remain in canonical
+results and native tool details. JSON receipt text (including `stop`) selects
+execution and accounting-status metadata; it does not automatically serialize
+per-entry contributions or additional saved diagnostics. Process/stop evidence
+and output/paging fields remain available in the text. Inventory, receipts,
+inspection and completion notices each have an explicit model-facing renderer.
+
+Historical foreground and `wait` charges already recorded in a parent's journal
+remain in its native totals. For workflow totals, count shared continuation
+journals once and do not count child contributions again when an older parent
+tool result already includes them.
+
+## Completion delivery
+
+Attachment publishes durable ownership before ordinary session startup returns.
+Retained completion recovery runs about 200 ms later or on an explicit
+reconciliation, not on the awaited startup path. That delay is not a delivery
+deadline. A short-lived main may exit before recovery, and a prompt started
+immediately after startup may receive the recovered backlog as steering input.
+Managed launchers still gate attachment on accepted host readiness.
+
+After that, the main reconciles when its owner directory, an unfinished run's
+`result.json`, a pending-accounting child journal or the retired legacy result
+directory changes, and after settlement or `agent_runs` controls. A change only
+starts reconciliation; canonical results, admissions and journal receipts still
+decide delivery. Directories the platform cannot watch, and failed reconciliations,
+fall back to the previous 200 ms polling. An idle main does no recurring scan.
+Instead, once a second it stats the inputs the last reconciliation read (the owner
+and legacy directories and each awaited file) and reconciles if any changed. A
+change notification the OS drops, or a legacy directory created after attachment,
+therefore delays delivery by at most about a second.
+
+Actors admit durable commands the same way: a change to their `commands`
+directory, a stop or a deferred run starts a scan. Their one-second parent
+liveness check also rechecks the directory for changes, so a dropped notification
+delays admission by at most that check. Without a watch, actors poll every 100 ms
+as before.
+
+Completion notices use steering, not follow-up delivery. A busy parent receives
+results at the next native tool boundary; it need not finish its task first.
+An idle backlog, including retained legacy results, is published before one wakeup.
+This avoids separately deferred settlement wakeups replaying the same result.
+New-runtime backlogs are sorted by completion time, then launch time and ID—not
+directory order. A later scan cannot reorder messages already admitted to Pi.
+
+Admission is still not publication or model consumption. Native physical receipts
+suppress redelivery across reload/resume, and dropped queues can recover. Receipt
+polling reuses unchanged verified journal metadata; changed files validate the
+committed prefix before parsing appended records. Replacement, truncation, changed
+prefixes, malformed records, and missing final newlines do not fabricate receipts.
+Completion delivery appends context; it does not replace prior prompts, tools,
+model settings, or the active conversation.
 
 ## Read-only human observation
 
-Interactive main sessions expose an agent status line and `/agents` list/watch.
+Interactive main sessions expose an above-editor widget and `/agents` list/watch.
+The widget shows up to five active runs with circle indicators, status and short ID;
+unreadable (unavailable) runs also stay listed. The default picker hides completed
+runs; failed, stopped, interrupted, and unavailable runs remain visible there.
+The header total counts all saved runs; the widget rows and overflow count include
+only active work and unreadable runs.
+`/agents <run-id>` still opens
+saved completed runs, and an already-open watch stays open through completion.
+An empty partial inventory says it is checking saved runs, not that no runs exist.
+In fullscreen mode, click a named row to watch that child; click the header or
+overflow count to open `/agents`. Picker rows and selection/Back/Close hints are
+clickable too. Regular mode retains the keyboard path because Pi leaves mouse
+input to the terminal there. Ctrl+O expands model/cwd details. The widget
+clears once a complete error-free scan finds no active or unreadable runs, or when
+the native parent is replaced; it stays while saved runs are still being checked. It is not
+a footer-only count.
 Use Up/Down to select, Enter to watch, and Escape to return/close (the displayed
 hints follow Pi's configured selection keys). `/agents <exact-run-id>` opens that
 run directly. Children and print/RPC modes do not install a watcher.
@@ -132,6 +263,13 @@ journal records and unpublished provider token deltas are not presented as compl
 entries. Agent tools remain the orchestration surface; this does not restore the
 retired workflow UI or remote transcript APIs.
 
+Long `delegate`, `agent_runs`, and `intercom` result cards start with a four-visual-line
+preview, including output that wraps from one long logical line. Pi's native card
+click and configured expand-tools key (Ctrl+O by default) reveal the full output.
+Child completion and Intercom message cards use the same native expansion state;
+their clickable header hints toggle the global tools-expanded view, just like
+Ctrl+O. Full saved and model-visible content is unchanged.
+
 ## Installation and upgrade
 
 ```bash
@@ -146,6 +284,16 @@ committed npm lockfile. The build publishes a complete staged `dist/`; failed
 compilation does not destroy the previous working tree. Do not rebuild a checkout
 while active sessions load its files.
 
+On native Android, source installation and verification require an Android build
+of `tsgo` on PATH. The prebuilt npm installation needs no compiler. See
+[Android development](development.md#native-androidtermux).
+
+Where the filesystem denies hard links, exclusive saved-run records are atomic
+relative symlinks to complete, private `.data` files beside them. Keep the entire
+run directory, including those backing files and relative links, when backing up
+or moving saved state; they are not disposable staging files. Existing regular
+records remain readable and are never replaced by a competing exclusive writer.
+
 Finish in-flight work before migrating from the old workflow engine. Preserve the
 prior package, native sessions, and durable state for rollback. Old profile files
 are left untouched but no longer configure delegation. Chain/fanout orchestration,

package/docs/retired-history-maintenance.md

@@ -0,0 +1,252 @@
+# Archive the retired SQLite history index
+
+Public tagged releases **v0.44.0 through v0.49.1** can open `history-index`.
+**v0.50.0** first carries removal commit
+[`7b721902`](https://github.com/fitchmultz/pi-subagents/commit/7b721902fb28c31e15757b3dc3dbe1b42b1a06c9).
+Upgrades leave that directory untouched. There is no startup cleanup, deletion
+prompt, or success marker. An older installation can still reopen or recreate it.
+
+The packaged `scripts/archive-retired-history.mjs` command is an **opt-in,
+offline-only archive route**, never an extension startup or installation hook.
+It preserves the whole recovery set; it never deletes, opens a database through
+SQLite, checkpoints originals, or copies across filesystems. A same-filesystem
+archive **reclaims zero file allocations**. A later purge needs separate approval.
+This guide is not permission to inspect or change a live installation.
+
+## Establish the maintenance boundary
+
+1. Obtain the machine owner's approval for the exact storage, archive location
+   and maintenance window. Inventory every installation from the affected range,
+   bridge, launcher, detached runner, service, scheduler and other client that can
+   access the volume, including packages that can be launched again.
+2. Stop **all readers and writers** and disable their launch/relaunch paths for
+   the entire window, verification and any rollback. Include old detached timing
+   writers and other machines or namespaces that can reach the storage. Keep
+   another operator from starting maintenance against the same paths.
+3. Establish that boundary through the owner's actual service/launcher controls.
+   A separately booted OS is not mandatory. If stopped/disabled applications and
+   access controls cannot establish quiescence, use an isolated maintenance
+   environment, for example a separate boot with the application volume mounted
+   locally and no application services or other clients. Otherwise stop untouched.
+
+The command's `--quiesced` flag acknowledges these conditions; it cannot enforce
+or verify them. Privileged native `lsof` checks detect observable open handles,
+not a stopped program's next launch, another client, or an inaccessible namespace.
+Root visibility is necessary, not a universal completeness guarantee. A rename,
+one empty `lsof` result, a SQLite lock, a new marker or unchanged hashes do not
+prove exclusion. Rechecks detect some changes but do **not** remove all races.
+Privileged or same-account interference remains outside the enforced boundary.
+Do not use the command if that boundary is uncertain.
+
+## Select and validate the owned set
+
+Resolve the retired installation's agent directory. Its default was `~/.pi/agent`;
+`PI_CODING_AGENT_DIR` could select another. In a separate maintenance environment,
+use the mounted application account's paths, not the maintenance user's home.
+Select **only** its `history-index` child, never the agent directory itself.
+
+Establish provenance from the retired installation and the owner's private
+inventory. Familiar names and schema matches do not authenticate ownership.
+The command accepts only these historical flat-file names:
+
+- SHA-256 owner manifests: `<64 lowercase hex digits>.json`.
+- UUID generation databases: `<uuid>.sqlite`, including unselected generations.
+- Ingest databases: `<uuid>.sqlite.ingest.sqlite`.
+- Timing database: `run-timing.sqlite`.
+- Matching SQLite `-wal` and `-shm` companions.
+
+A manifest must select an included generation. An ingest database must have its
+generation; sidecars must have their database and a complete WAL/SHM pair.
+Missing/unexplained companions require investigation, not automatic repair.
+Unknown entries, temporary manifests, rollback journals, nested directories,
+special files, symbolic/hard links, foreign UID or writable-to-others state stop
+the command. It never fixes owners or permissions on the original set. Canonical
+paths must have no symbolic-link components. The filesystem root itself must be
+owned by administrative UID 0. Every other ancestor must be controlled by root
+or the retired account and not writable to unrelated accounts; the sole
+writable-ancestor exception is a root-owned sticky directory such as `/tmp`,
+whose selected child must still have trusted ownership. Private leaf directories
+under an unsafe ancestor are not sufficient. Audit ACLs and mount/user-ID mappings
+as well: POSIX mode checks do not certify those. Extra write grants to other
+principals are unsupported; stop unless you can exclude them before invocation.
+
+**Exclude all native Pi JSONL files, `run-history.jsonl`, current `agent-runs`,
+legacy completion inputs and Intercom storage.** Current Intercom still owns
+SQLite. Timing samples may not be reconstructible from another file. Do not open
+original databases to identify schemas: SQLite can recover or create sidecars.
+Inspect and recover a complete disposable copy instead.
+
+## Run the packaged route
+
+The command supports Linux and macOS with Node at the package's supported floor.
+It requires administrative native `lsof` visibility. Linux needs `/usr/bin/lsof`
+and effective `CAP_SYS_PTRACE` for cross-account process inspection; root inside
+a restricted container is not sufficient. macOS uses `/usr/sbin/lsof`. Missing
+tools, warnings, incomplete inspection, interruption or unexpected results stop
+the command. There is no unprivileged,
+forced or best-effort bypass. This optional command does not change the extension's
+host support or require `lsof` during normal runtime/install.
+
+Use a reviewed, trusted package and Node executable when running with privilege.
+Run from outside the selected source/container so your shell is not an open
+reader of the directory. Create private record and archive **parents** under trusted ancestors, owned by
+the retired account, before invoking the command. Use normalized canonical paths
+without trailing slashes. Select a new, unique container name and external record
+file, both outside the recovery set; the record must also be outside the archive
+container. Keep the record and all command results private. Do not upload caches,
+record contents, names, paths or hashes to issues or PRs.
+
+The following placeholders must be replaced locally after owner approval. These
+are commands for the authorized maintenance window, not ordinary upgrade steps:
+
+```sh
+# Set explicit canonical paths and the retired account's numeric UID.
+NODE=/absolute/trusted/path/to/node
+SCRIPT=/absolute/trusted/package/scripts/archive-retired-history.mjs
+SOURCE=/canonical/agent/history-index
+CONTAINER=/private/archive-parent/unique-container
+RECORD=/private/record-parent/unique-inventory.json
+OWNER_UID=1234
+
+# Phase 1: inspect, reserve the container exclusively, and write the external plan.
+sudo "$NODE" "$SCRIPT" prepare --source "$SOURCE" --archive "$CONTAINER" \
+  --record "$RECORD" --owner-uid "$OWNER_UID" --quiesced
+
+# Read-only reconciliation before the move or any retry.
+sudo "$NODE" "$SCRIPT" inspect --record "$RECORD" --owner-uid "$OWNER_UID"
+
+# Phase 2: recheck the plan and handles, then rename the complete directory once.
+sudo "$NODE" "$SCRIPT" archive --record "$RECORD" \
+  --owner-uid "$OWNER_UID" --quiesced
+```
+
+`prepare` creates a new `0700` container with exclusive `mkdir` and an external
+`0600` record with exclusive no-follow creation. It records source, parent and
+container identities plus every member's device/inode, ownership, mode, link
+count, size, modification/change timestamps and SHA-256. Raw hash reads can update
+access time; they do not recover SQLite or change file contents. All generations
+and available companions stay together. The command does not alter the record afterward; it is not
+OS-enforced immutable storage and is **not** a cleanup-success marker. An
+interruption before record publication can leave an unrecorded empty container;
+stop and investigate rather than adopt or remove it automatically.
+
+`archive` checks the real state, identities, entire inventory and open handles
+again. It uses a native same-filesystem directory rename, with **no** copy/delete
+fallback. The exclusively reserved private container must have no unexpected
+contents or existing destination. This is not an atomic no-clobber guarantee
+against a competing root/same-account process; the enforced quiescent boundary
+remains mandatory. After the move, the command checks the archive against the
+record. Any failure preserves the observed locations and record for investigation;
+it does not roll back automatically, merge trees, or conceal ambiguity. Directory
+and record sync calls do not establish a tested power-loss durability guarantee.
+
+Public failure output is a controlled refusal ID, not a dump of paths, hashes,
+JSON or `lsof` output. `E_OPEN_HANDLES` means a reader/writer is still observable;
+`E_LSOF_*` means inspection could not be accepted. `E_PROCESS_VISIBILITY` means
+Linux cannot establish the required administrative inspection capability. `E_UNKNOWN_MEMBER`,
+`E_MEMBER_TYPE`, `E_FOREIGN_OWNER`, `E_UNSAFE_MODE` and `E_ANCESTOR_*` require
+provenance/path investigation. `E_CROSS_DEVICE` prohibits the move.
+`E_INVENTORY_CHANGED`, identity-change IDs and `E_AMBIGUOUS_PATHS` mean stop and
+preserve both trees. `E_INSPECTION_FAILED` covers other filesystem/JSON failures;
+inspect the private inputs locally rather than posting their contents.
+
+## Reconcile interruption and rerun
+
+Run `inspect` against the **same external record** before retrying. Do not infer
+state from a prior console line or create a replacement record to bypass drift.
+
+- Source has the recorded directory/inventory; archive child is absent and its
+  reserved container is unchanged: **prepared**, no move yet. Re-establish all
+  prerequisites before `archive`. Repeating matching `prepare` also inspects it.
+- Source is absent; the archive child has the recorded identity/inventory:
+  **archived**. Repeating `archive` verifies this state without moving anything.
+- Both or neither paths exist, an identity/member changed, the record is unsafe,
+  or an unrecorded destination already exists: **stop**. Preserve both trees and
+  the record. A recreated source can belong to a relaunched old release; do not
+  merge it, overwrite either location, or call it another stale cache.
+
+Under the same offline boundary, recover **only a complete disposable copy** of
+the archive with a compatible SQLite implementation. Run `PRAGMA integrity_check`
+and inspect expected committed data on that copy. Do not use `immutable=1` to
+bypass WAL recovery. Recovery can change its copy; retained archive bytes must
+still match the external record. Historical generation schema `user_version=5`
+and `meta`, and timing tables `timing_meta`/`samples`, corroborate format only.
+
+For rollback, keep quiescence, verify the complete recorded archive again, and
+restore the whole recovery set **only when the original path is absent**. Never
+overwrite a recreated source or restore individual sidecars. Restoring the data
+does not restore a package version or authorize restarting a live application.
+
+## Later space reclamation: a separate owner decision
+
+The archive command never purges and never reports disk cleanup completed.
+A successful same-filesystem move frees no file allocations and can consume
+additional metadata space. Do not purge as part of an upgrade or this procedure.
+
+1. Keep the verified archive for the owner's retention/rollback period. Obtain
+   approval for a private, encrypted **off-device** backup destination. Record its
+   physical device/storage identity, not just another directory or partition on
+   the source disk. Use the storage system's documented durable backup procedure
+   to copy the **whole container**, preserving basenames/companions, and retain
+   the external inventory separately. Do not recover the retained archive.
+2. Test a restore into a new, exclusively reserved private **disposable** directory.
+   Compare the exact flat member-name set, file sizes and per-file SHA-256 against
+   `members` in the external JSON record; reject extra files, links or missing
+   members. Native `sha256sum -c` on Linux or `shasum -a 256 -c` on macOS can check
+   a private checksum list made from each `sha256` and `name`. A checksum pass
+   alone does not detect extra members, so compare the name set separately.
+   Recover that complete restored copy and check integrity/expected committed
+   contents. Record the verified backup object identity/checksum and successful
+   restore checks. Merely copying a file or seeing it on another volume is not
+   backup verification.
+3. Ask the owner for a **new purge authorization** naming only the recorded
+   canonical archive container, its filesystem/volume identity, device/inode,
+   owner/mode, the external record's checksum and the verified backup identity.
+   Explicitly exclude the original `history-index` path, all journals/current
+   state, other archives, the external record and the backup. Approval for the
+   earlier archive or backup is not purge approval.
+4. During a separately enforced maintenance window, run the command's `inspect`
+   again. Compare the actual container, parents and members with the original
+   record, and corroborate the source-volume identity with the OS storage tool.
+   Reject symlink/mount substitutions, new source data or any ambiguity. The
+   separately approved purge tool/operator must recheck that **exact container**
+   immediately before deletion and must not follow links, cross mounts, expand a
+   wildcard or fall back to deleting the original path. This archive-only command
+   intentionally supplies no purge action or original-path deletion command.
+5. Record allocation **before** that authorized purge using `du -sk` on the exact
+   container and `df -k` on its trusted parent. These report allocated KiB and
+   filesystem capacity, not logical database lengths. After the authorized tool
+   has removed only that container, verify that identity is gone, the backup and
+   excluded paths remain, and repeat `df -k` on the same filesystem. Preserve the
+   records. Snapshots, clones, compression, open handles, background writes and
+   delayed filesystem reclamation can make free-space changes differ from `du`;
+   report actual observations rather than claiming the archive size was freed.
+
+No backup, purge, real-data inspection, install or restart is run by repository
+verification. Synthetic command tests exercise these archive/retry guards and
+recover disposable copies; they do not certify operator quiescence, private-data
+provenance, off-device durability or permission to purge.
+
+## Historical source inventory
+
+All 16 public tags from v0.44.0 through v0.49.1 retain generation, ingest and timing
+owners. The earliest tagged owner is
+[`v0.44.0` at `4f288484`](https://github.com/fitchmultz/pi-subagents/tree/4f288484d98488286fe137604c45ed49ac6b995d):
+[database](https://github.com/fitchmultz/pi-subagents/blob/4f288484d98488286fe137604c45ed49ac6b995d/src/history/database.ts#L6-L28),
+[manifest/generation/ingest store](https://github.com/fitchmultz/pi-subagents/blob/4f288484d98488286fe137604c45ed49ac6b995d/src/history/store.ts#L43-L78),
+and [timing writer](https://github.com/fitchmultz/pi-subagents/blob/4f288484d98488286fe137604c45ed49ac6b995d/src/runs/shared/run-history.ts#L58-L80).
+The last is
+[`v0.49.1` at `f757ed05`](https://github.com/fitchmultz/pi-subagents/tree/f757ed054e7d819fd590a3da346be8a03aefe2d4):
+[generation](https://github.com/fitchmultz/pi-subagents/blob/f757ed054e7d819fd590a3da346be8a03aefe2d4/src/history/database-generation.ts#L52-L80),
+[ingest](https://github.com/fitchmultz/pi-subagents/blob/f757ed054e7d819fd590a3da346be8a03aefe2d4/src/history/store.ts#L275-L299),
+[detached timing writer](https://github.com/fitchmultz/pi-subagents/blob/f757ed054e7d819fd590a3da346be8a03aefe2d4/src/runs/background/runner-step.ts#L143-L149),
+and [history worker](https://github.com/fitchmultz/pi-subagents/blob/f757ed054e7d819fd590a3da346be8a03aefe2d4/src/history/index.ts#L112-L127).
+These old owners do not honor a new maintenance marker.
+
+The earlier execution sample remains specifically **v0.48.0 at
+`d4caa1351c6dbc181276860123b5b00c969de56b`**, not a runtime test of all releases.
+The maintained main baseline for this source candidate is
+`64f7e91d278006622dd2d7f12fc81271a1caffb2`;
+its runtime/startup/install paths have no retired history owner. The original
+measurements remain bound to admitted baseline `4906e67e3a6701a753df3af112304dea2246aeb1`
+and original PR head, not relabeled as measurements after integration.

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.50.0",
+  "version": "0.52.0",
   "description": "Pi extension for subagent orchestration and local session coordination",
   "license": "MIT",
   "type": "module",
+  "exports": {
+    "./intercom-client": {
+      "types": {
+        "development": "./src/intercom-client.ts",
+        "default": "./dist/intercom-client.d.ts"
+      },
+      "import": "./dist/intercom-client.js"
+    },
+    "./package.json": "./package.json"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fitchmultz/pi-subagents.git"
@@ -27,6 +37,7 @@
     "dist",
     "src/**/*.ts",
     "tsconfig.build.json",
+    "tsconfig.client.json",
     "tsconfig.json",
     "scripts/",
     "skills/**/*",
@@ -36,6 +47,7 @@
     "docs/intercom.md",
     "docs/intercom-bridge.md",
     "docs/performance.md",
+    "docs/retired-history-maintenance.md",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -47,7 +59,7 @@
     "test:integration": "node scripts/run-tests.mjs integration",
     "test:all": "node scripts/run-tests.mjs all",
     "check:compat": "node scripts/check-compat.mjs",
-    "typecheck": "node node_modules/typescript/bin/tsc --noEmit",
+    "typecheck": "node scripts/typescript.mjs --noEmit",
     "smoke:package": "node scripts/package-smoke.mjs",
     "smoke:install": "node scripts/local-install-smoke.mjs",
     "check:size": "node scripts/measure-size.mjs",
@@ -91,18 +103,18 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "1.3.0",
-    "@earendil-works/pi-ai": "1.3.0",
-    "@earendil-works/pi-coding-agent": "1.3.0",
-    "@earendil-works/pi-tui": "1.3.0",
-    "@types/node": "24.19.1",
-    "@types/sinon": "22.0.0",
-    "oxfmt": "0.72.0",
-    "oxlint": "1.87.0",
-    "oxlint-tsgolint": "7.0.2003",
+    "@earendil-works/pi-agent-core": "1.4.0",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
+    "@types/node": "24.19.2",
+    "@types/sinon": "22.0.2",
+    "oxfmt": "0.74.0",
+    "oxlint": "1.89.0",
+    "oxlint-tsgolint": "7.0.2005",
     "sinon": "22.1.0",
     "type-fest": "5.10.0",
-    "typebox": "1.3.34",
+    "typebox": "1.4.3",
     "typescript": "7.0.2"
   },
   "publishConfig": {
@@ -111,8 +123,9 @@
   "engines": {
     "node": ">=24.21.0"
   },
-  "dependencies": {
-    "stream-chain": "4.2.6",
-    "stream-json": "3.7.0"
+  "overrides": {
+    "@earendil-works/pi-coding-agent": {
+      "undici": "8.12.3"
+    }
   }
 }