@fitchmultz/pi-subagents 0.50.0 → 0.51.0

package/CHANGELOG.md

@@ -1,6 +1,55 @@
 # Changelog
 
-## [0.50.0] - Unreleased
+## [0.51.0] - 2026-10-26
+
+### Added
+
+- Publish `@fitchmultz/pi-subagents/intercom-client`, a typed non-model client for the existing native broker. Require `spawn:false`, preserve caller-recorded guarded message IDs, and expose discovery, non-waking pinned last pages, original-ID receipts and explicit socket cleanup without loading Pi, a model or another journal. Reject overlapping sends with one pending ID instead of replacing its acknowledgement waiter.
+
+- Read non-waking native receipts by original message ID and expose version-1 process-local provenance from the loaded journal owner. Preserve exact root and departed-sender binding, independently hash the raw sender text, and return selected publication metadata without input text or a public parser. Keep append, staging, handoff and actual placement observations separate from fsync and provider/model consumption. Ordinary active-branch `last` paging is unchanged.
+- Negotiate conditional Intercom commands bound to one exact native main, peer, context incarnation and companion-owned application revision. Check the binding at broker routing and native admission, expose the original lifecycle snapshot through a versioned process-local event handshake, and render generic correlated-publication hints without creating ordinary asks. Startup, reload and session replacement invalidate old handles; transport reconnect preserves the context. Ordinary local names, asks and main/child topology are unchanged. This does not install an external client, export native work or strengthen broker acceptance into a recipient receipt.
+
+### Breaking
+
+- Make child execution asynchronous-only. `delegate` and `agent_runs` no longer accept `async`, and `agent_runs` no longer has `wait`; launches, continuations and guidance return honest receipts, and existing completion notifications resume the parent. A blocking wait held the parent's tool batch open, so admitted Intercom steering could not reach it until the child finished. Aborting a parent turn no longer stops children; use `stop`. New calls no longer attribute child usage to the parent; child results keep exactly-once native contributions, and historical parent charges remain unchanged. The opt-in `smoke:real-pi -- --llm`/`--llm-full` prompts now keep a persistent RPC main open until each launch or continuation receipt's completion notification resumes it, then close it and confirm the delegated actor exits.
+- Remove the Intercom busy-recipient detach probe and its timer. Steers go straight to Pi's native queue for the next tool boundary.
+- Stop child actors and verified owned native shells when their parent exits, including active work and asynchronous delegation from one-shot callers. Keep saved conversations for explicit continuation after parent resume; do not replay interrupted tools. Ordinary extension reload keeps children alive.
+
+### Fixed
+
+- Keep the parent and child event loops responsive while they check whether children and parents are still alive. On macOS each check waited on a `ps` run; `/agents`, `agent_runs` lists and each child's parent check now wait on it in the background, and a list checks each saved conversation once instead of once per run. Stop and continuation still prove the process birth synchronously right before signaling.
+- Validate large child journals with an incremental scanner that decodes selected or observed string chunks, replacing stream-json's tokenizer. The package no longer depends on stream-json or stream-chain.
+- Let Stop and continuation release a saved actor or native-shell PID that another user's process now holds, when its native birth proves replacement. Permission-denied probes previously blocked that existing proof, stranding children after a reboot. Unverified identities, unreadable births and claims written after the current process still refuse without signaling.
+- Keep `/agents` working after a live install refresh removes package-local development copies of Pi. Lazy-only viewer modules now resolve UI and SDK values through the selected host. Sessions already using the current viewer API recover on their next `/agents` after installing the fix. Sessions started from the published v0.50.0 package need to restart Pi.
+- Report `reply_failed` with pending/list recovery when an Intercom reply's `to` names a different sender than its `replyTo` ask. A `to` containing "too short" was previously misreported as an ambiguous reply target; recovery codes now come from the failing owner, not message wording.
+- Add an opt-in offline archive command for the retired SQLite history index, with private inventory, whole-set identity checks and prepared/completed retry reconciliation. Refuse unsafe entries, links, foreign ownership, active handles and cross-filesystem moves. Upgrades leave the directory untouched; archiving never deletes or reclaims file allocations. Releases v0.44.0–v0.49.1 can still reopen the data, so owner-enforced quiescence remains required. See the [maintenance guide](docs/retired-history-maintenance.md).
+- Keep the last-good `dist/` when the build fails after compiling. The build now moves the previous tree aside and renames it back if publication fails, instead of deleting it first. Replacement is two renames, not an atomic exchange: a concurrent reader can briefly find no `dist/`, but never a partial tree. A build killed between the two renames can still leave `dist/` absent until the next successful build.
+- Parse child launch lineage once, exactly. Absent root and parent IDs mean a main; otherwise both must be identical, nonempty and unpadded, or the package refuses to load. Padded IDs are no longer trimmed into a different Intercom identity.
+- Keep children running across a managed fork `pi restart` or `/restart` and publish their completions once from the ready replacement. With the fork's `ctx.managedHost`, the launcher owns child liveness; an unready replacement neither adopts children nor publishes, a committed restart or startup rollback keeps them, and parent exit (including quitting an unready replacement) still stops them. Official Pi and older fork launchers keep process-lifetime ownership.
+- Restore native Android/Termux source builds and typechecking with installed Android `tsgo`, place shared sockets under the writable Termux prefix, publish exclusive records atomically without denied hard links, and verify reused PIDs with a boot-qualified monotonic elapsed-age bound that survives controller clock changes. Preserve no-clobber claims, private complete records, existing macOS/Linux namespaces, and native continuation/stop/recovery contracts.
+- Stop idle mains and child actors from rescanning saved runs and commands several times a second. Mains reconcile when a run, child journal or legacy result changes, and after settlement or controls; actors scan commands on change, stop or a deferred run. A one-second stat check of the same inputs recovers change notifications the OS drops. Canonical results, admissions and journal receipts still decide delivery; unwatchable directories keep the previous polling.
+- Stop reparsing unchanged completed child results and searching historical receipts on every completion poll. Keep physical journal validation, chronological delivery and pending-accounting repair.
+- Preserve native Markdown formatting in collapsed message cards, including legacy human relays, and show clickable expansion hints only when content is hidden.
+- Skip provably reused child and native-shell PIDs during Stop, continuation and parent shutdown, including unrelated non-group-leaders. Keep genuine identity uncertainty visible and verified orphan cleanup intact; timezone differences alone never prove replacement.
+- List only active (and unreadable) child runs in the above-editor widget and remove it once a complete scan finds no active work. Stopped, failed and interrupted history stays in `/agents`, direct watch and saved run records.
+- Resolve explicit child `provider/model:thinking` overrides with Pi's native model-reference API when available. Preserve literal colon IDs and inherited thinking, reject fuzzy/fallback selection, and explain the host API requirement on older runtimes.
+- Restore fullscreen click-to-watch on named child rows and clickable `/agents` navigation. Keep regular-mode keyboard controls and read-only observation.
+- Collapse lengthy agent/Intercom result and notification cards by visual lines, reusing Pi's native expansion state and keybindings without truncating saved or model-visible content.
+- Restore default steering for incoming Intercom asks in interactive and print modes; keep explicit queue/passive behavior and sender-side busy capability reporting.
+- Preserve non-passive recovery order and suppress repeated message/reply IDs without reviving answered or superseded work.
+- Restore circle indicators and hide completed runs from the above-editor widget and `/agents` picker. Saved run IDs and already-open read-only watches remain available; failed, stopped, interrupted, and unavailable runs stay visible.
+- Restore steering delivery for new and legacy child completions. Publish an idle backlog before a single native wakeup, preventing separately deferred settlement turns from requeueing the same results.
+- Log and skip a malformed legacy result file instead of dropping every other legacy completion on each scan.
+- Reconcile new-runtime completion backlogs in completion/launch order instead of UUID directory order; preserve published receipts and recovery of genuinely dropped queues.
+- Reuse a bounded physical-receipt index instead of repeatedly parsing unchanged parent journals. Validate changed prefixes and retain newline, replacement, truncation, corruption and owner checks.
+- Restore the above-editor named running-agent widget, active-first status rows and expansion, while retaining read-only `/agents` watching. No live runtime, broker, bridge, model or auth changes.
+
+### Changed
+
+- Shorten the `delegate`, `agent_runs` and `intercom` tool descriptions and use Pi's `StringEnum` for `delegate.context` and `agent_runs.action`. Their added active-declaration JSON drops from 4,363 to 2,984 bytes on official Pi 1.4.0 and the fork. Accepted and rejected arguments, actions and results are unchanged; an invalid `context` or `action` now gets Pi's single "allowed values" error instead of one line per union member.
+- Update development tooling to oxlint 1.89.0 with tsgolint 7.0.2005, oxfmt 0.74.0, TypeBox 1.4.3, and Node 24.19.2 and Sinon 22.0.2 typings, with a regenerated lockfile. Runtime dependencies, optional host-provided Pi and TypeBox peers, and the Node 24.21 floor are unchanged.
+
+## [0.50.0] - 2026-10-21
 
 ### Breaking
 
@@ -22,7 +71,7 @@
 - Require a concrete resolved recipient for asks before sending; retain exact reply-sender identity checks across peer registration races.
 - Include length-ended completed responses in `last`; ignore unpublished launch directories during listing/reconciliation while retaining their native session evidence. Preserve published uncertain launch claims, visible corruption errors and conservative cold-Stop process identity checks.
 
-This is an unpublished breaking-release candidate. Merge, publication, installation and paired bridge cutover remain separate approval gates; no live runtime is changed by this PR.
+Package publication, local installation and paired bridge cutover are separate operations.
 
 ## [0.49.1] - 2026-10-15
 

package/README.md

@@ -17,7 +17,8 @@ delegate({
 });
 ```
 
-Delegation is asynchronous by default. `async: false` waits for the result.
+Delegation is always asynchronous: tools return a receipt and the completion
+arrives later as a notification. Do other work or end the turn; do not poll.
 `context: "fresh"` is the default; `context: "fork"` preserves the native
 conversation, including prior tool results. There is no hidden role prompt,
 report-writing suffix, profile selection, or model fallback catalog.
@@ -30,7 +31,6 @@ agent_runs({
   id: "<run-id>",
   prompt: "Now inspect the refresh-token path. Do not edit.",
 });
-agent_runs({ action: "wait", id: "<run-id>" });
 agent_runs({ action: "stop", id: "<run-id>" });
 ```
 
@@ -56,16 +56,39 @@ A main and its children form one group:
 These are coordination rules, not an OS sandbox against same-user code. A peer
 list contains connected, eligible sessions, not every Pi process on the machine.
 
+Non-model Node.js companions can import
+`@fitchmultz/pi-subagents/intercom-client` for discovery, exact guarded sends,
+pinned last-response pages and original-message receipts. The
+[supported client API](docs/intercom.md#supported-non-model-client) connects only
+to an existing broker; it loads no Pi SDK, model, TUI or conversation journal.
+
+## Bundled skills
+
+The package ships two skills that match tool availability.
+[`pi-subagents`](skills/pi-subagents/SKILL.md) covers `delegate` and `agent_runs`,
+which only main sessions receive. [`pi-intercom`](skills/pi-intercom/SKILL.md)
+covers `intercom`, which every session has, including children and mains that
+never delegate. Load either with `/skill:pi-subagents` or `/skill:pi-intercom`.
+
 ## Watch agents without prompting them
 
-In interactive Pi, the agent status line reports active children. Open `/agents`
-to list runs and watch a child's native published text, tool calls and results.
+In interactive Pi, an above-editor widget names individual children with circle
+indicators. The widget lists active work (and unreadable runs) only and disappears
+once a full scan finds none. The `/agents` picker hides completed runs; failed,
+stopped, interrupted, and unavailable runs remain visible there.
+Click a named row in fullscreen mode to watch it; `/agents` remains the keyboard
+path. Long result/message cards are collapsed and use Pi's native expansion
+(Ctrl+O by default). Ctrl+O also expands model/cwd details. Use `/agents <run-id>` to watch
+any saved run, including a completed child's native published text, tool calls and results.
 This is read-only: it neither spends a model turn nor dispatches, steers or stops
 work. Unpublished provider token deltas are not a journal stream. Agents still
 own delegation and communication; human observation is not a second workflow UI.
 
 ## What stays explicit
 
+Completions steer an active parent at the next tool boundary. An idle completion
+backlog is published in order and starts one parent turn, not one turn per result.
+
 Launch acceptance is not completion. Broker acceptance is not recipient journal
 persistence or a reply. A stop request is not proof of process exit. Saved run
 inspection reports these states separately, and does not invent a successful
@@ -93,6 +116,11 @@ state for rollback; qualify the helper and Box client/worker as an immutable pai
 with the companion's offline receipt-reconciliation gate. This repository change
 does not deploy or restart anything.
 
+Upgrades leave the retired SQLite history index in place. The packaged opt-in
+[offline archive command](docs/retired-history-maintenance.md) preserves its complete
+recovery set after owner-enforced quiescence and observable safety checks.
+It never runs during startup/install, deletes data, or reclaims disk space.
+
 - [Tools and lifecycle](docs/reference.md)
 - [Local messaging and broker migration](docs/intercom.md)
 - [Authenticated remote messaging / Grok companion](docs/intercom-bridge.md)
@@ -100,4 +128,7 @@ does not deploy or restart anything.
 - [Diagnosis, baseline, and measurable rebuild gates](docs/single-agent-rebuild.md)
 
 Supports official Pi and the maintained `fitchmultz/pi` fork; the two hosts are
-qualified separately. Node.js 24.21 or newer is required. MIT licensed.
+qualified separately, including native Android/Termux. Node.js 24.21 or newer is
+required. Source installs on Android also need an Android-native `tsgo` on PATH;
+the prebuilt npm package does not need a compiler. See
+[development prerequisites](docs/development.md#native-androidtermux). MIT licensed.

package/dist/agent/contracts.js

@@ -33,10 +33,14 @@ export const processSchema = Type.Object({
     pid: Type.Integer({ minimum: 1 }),
     identity: Type.String(),
     token: Type.String(),
+    clock: Type.Optional(Type.Object({
+        boot: Type.String(),
+        namespace: Type.String(),
+        at: Type.String({ pattern: "^[1-9][0-9]*$", maxLength: 20 }),
+    })),
 });
 export const attachmentSchema = Type.Object({
-    pid: Type.Integer({ minimum: 1 }),
-    identity: Type.String(),
+    ...Type.Pick(processSchema, ["pid", "identity", "clock"]).properties,
     generation: Type.String(),
     attached: Type.Boolean(),
 });
@@ -98,25 +102,3 @@ export const admissionSchema = Type.Object({
     state: Type.Optional(Type.Union([Type.Literal("accepted"), Type.Literal("stale")])),
     at: Type.Number(),
 });
-export const delegateSchema = Type.Object({
-    prompt: Type.String({ minLength: 1 }),
-    name: Type.Optional(Type.String({ minLength: 1 })),
-    cwd: Type.Optional(Type.String({ minLength: 1 })),
-    model: Type.Optional(Type.String({ minLength: 1, description: "Exact provider/model ID; no fallback." })),
-    context: Type.Optional(Type.Union([Type.Literal("fresh"), Type.Literal("fork")])),
-    async: Type.Optional(Type.Boolean({ default: true })),
-}, { additionalProperties: false });
-export const runsSchema = Type.Object({
-    action: Type.Union([
-        Type.Literal("list"),
-        Type.Literal("inspect"),
-        Type.Literal("continue"),
-        Type.Literal("stop"),
-        Type.Literal("wait"),
-    ]),
-    id: Type.Optional(Type.String()),
-    prompt: Type.Optional(Type.String({ minLength: 1 })),
-    async: Type.Optional(Type.Boolean({ default: true })),
-    offset: Type.Optional(Type.Integer({ minimum: 0 })),
-    length: Type.Optional(Type.Integer({ minimum: 4, maximum: 262144 })),
-}, { additionalProperties: false });

package/dist/agent/host.js

@@ -10,6 +10,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { findPackageJSON } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { readIntercomLineage } from "../pi-intercom/identity.js";
+export { errorMessage as errorText } from "../shared/unknown.js";
 function isPackage(root) {
     const file = path.join(root, "package.json");
     if (!fs.existsSync(file)) {
@@ -63,20 +65,5 @@ export function runtimeEntry() {
     return fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "../index.ts" : "../index.js", import.meta.url));
 }
 export function isChild() {
-    const root = process.env.PI_INTERCOM_ROOT_SESSION_ID;
-    const parent = process.env.PI_INTERCOM_PARENT_SESSION_ID;
-    if (root === undefined && parent === undefined) {
-        return false;
-    }
-    if (root === undefined ||
-        parent === undefined ||
-        root.length === 0 ||
-        parent.length === 0 ||
-        root !== parent) {
-        throw new Error("Malformed child identity; delegation is disabled.");
-    }
-    return true;
-}
-export function errorText(error) {
-    return error instanceof Error ? error.message : JSON.stringify(error);
+    return readIntercomLineage() !== undefined;
 }