@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/CHANGELOG.md

@@ -1,6 +1,77 @@
 # Changelog
 
-## 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
+
+- Replace the multi-profile workflow engine with one implicit native agent type and three tools: `delegate`, `agent_runs`, and `intercom`. The invoking agent supplies the entire assignment; user agent Markdown and profile/model catalogs no longer configure delegation. Remove `load_subagent`, `subagent`, `load_intercom`, `contact_supervisor`, conditional `structured_output`, chains/fanout DSL, profile administration, Claude Code backend, and durable supervisor-question revival.
+- Use one same-OS-user broker namespace, independent of project and agent directory. Main agents communicate across groups; children communicate only with their main and siblings and cannot spawn. During cutover, drain work and reload every participating Pi session onto the same approved version before resuming bridge traffic; old namespaces are not transparently joined.
+- Retire remote launch/resume/control, saved-session/transcript/catalog/group/broadcast and synchronous ask/reply routes. Grok bots retain authenticated peer discovery and durable messaging, not remote agent orchestration or observation. Replies use correlated `send`; ACK transfers complete reply duties to the consumer mailbox. Upgrade the helper and Box client/worker as a reviewed pair, including offline receipt reconciliation and saved prompt/routine migration. Preserve journals, mail, quota and reservation history for rollback.
+- Ignore the deprecated client `launch` configuration key with a metadata warning; it grants no capability. Other unknown configuration fields still fail closed and report the offending field safely. Existing credentials and settings are not automatically rewritten.
+
+### Added
+
+- Read-only TUI agent status and `/agents` list/watch, without a model turn or human dispatch controls. Watches show native published text, tool calls and results, not unpublished provider token deltas.
+- Stable paged `intercom last` reads without waking the recipient, metadata-only run inventory, and explicit per-run guidance admission, receipt-publication and process-exit facts.
+
+### Fixed
+
+- Preserve orchestration tool results in forked child context instead of filtering the coordinating agent's evidence.
+- Keep Stop commands scoped to their target actor generation; an unadmitted predecessor Stop cannot mark a successor stopped.
+- Disclose stale guidance to model-visible inspection callers; never hide rejected follow-ups only in extension details.
+- 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.
+
+Package publication, local installation and paired bridge cutover are separate operations.
 
 ## [0.49.1] - 2026-10-15
 

package/README.md

@@ -1,109 +1,134 @@
 # pi-subagents
 
-`pi-subagents` lets [Pi](https://github.com/earendil-works/pi/tree/main/packages/coding-agent) delegate tasks to child sessions. Use it for code review, research, or implementation while you continue in the parent session.
-
-![A Pi parent session delegates independent tasks to scout and reviewer children, then receives their saved results.](.github/readme/delegation.png)
-
-## Install and start
-
-Requires **Pi 1.0.0+** and **Node 24.21.0+**. Use macOS or Linux. Windows is not supported.
+One Pi extension for delegation and local agent communication. Three tools, one
+agent type, no profile bodies.
 
 ```bash
 pi install npm:@fitchmultz/pi-subagents
-pi
 ```
 
-Enter a task in Pi:
+A main session supplies the child's complete assignment:
 
-```text
-Use scout to explain the authentication code in this project.
+```js
+delegate({
+  prompt:
+    "Inspect the authentication changes. Return concrete defects with file and line evidence. Do not edit files.",
+  name: "auth-review",
+});
 ```
 
-The built-in agents are ready to use. See the [installation reference](docs/reference.md#installation) for Git installs and local checkouts.
-
-## Run tasks
-
-Ask Pi for a child by role and task:
-
-```text
-Have worker implement this approved plan, then ask reviewer to check the changes.
+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.
+
+```js
+agent_runs({ action: "list" });
+agent_runs({ action: "inspect", id: "<run-id>" });
+agent_runs({
+  action: "continue",
+  id: "<run-id>",
+  prompt: "Now inspect the refresh-token path. Do not edit.",
+});
+agent_runs({ action: "stop", id: "<run-id>" });
 ```
 
-Children run in the background by default. You can also use commands:
-
-| Task                 | Command                                                         |
-| -------------------- | --------------------------------------------------------------- |
-| Review a diff        | `/run reviewer "Review this diff"`                              |
-| Run parallel tasks   | `/parallel scout "Inspect frontend" -> scout "Inspect backend"` |
-| Run a sequence       | `/chain scout "Map auth" -> planner "Plan a refactor"`          |
-| Run a saved workflow | `/run-chain scout-planner -- refactor authentication`           |
-
-Add `--fg` to wait for the result. The [`forceTopLevelAsync` setting](docs/reference.md#forcetoplevelasync) disables waits when enabled.
-
-The saved workflow example requires a [chain file](docs/reference.md#chain-files) named `scout-planner`. See the [command reference](docs/reference.md#direct-commands) for all options.
-
-## Choose a role and model
-
-| Task                         | Built-in agents                                                                         |
-| ---------------------------- | --------------------------------------------------------------------------------------- |
-| Read code or gather evidence | `scout`, `context-builder`, `researcher`                                                |
-| Plan or check a decision     | `planner`, `oracle`                                                                     |
-| Implement or repair a change | `worker`, `debugger`, `fixer`, `delegate`                                               |
-| Review a change              | `reviewer`, `reviewer-gpt`, `reviewer-claude`, `reviewer-security`, `reviewer-ponytail` |
-| Design, write or monitor     | `ui-designer`, `writer`, `watcher`                                                      |
-
-Ask Pi to show the effective profiles. Select an available model if a profile default is unavailable.
-
-[Model settings](docs/reference.md#changing-a-builtin-agents-model) let you change a role without a copy of its agent file. Custom agents use `~/.pi/agent/agents/` or your project's `.pi/agents/`.
-
-## Read results and continue work
-
-The **Agents** area shows active tasks and tasks that need attention. Open `/agents` to browse active and finished conversations.
-
-The shortcut is **Option+Shift+M** on macOS and **Alt+Shift+M** elsewhere.
-
-- Open a conversation to read the child's report or send a message.
-- Press F2 to inspect details or request cancellation with Stop.
-- Select Continue to start follow-up work from a saved child session.
-- Press Esc to return to the parent session.
+## Talk to agents
 
-Resume the same saved parent session with `pi --session /path/to/parent.jsonl` to recover runs and questions.
-
-See the [conversation reference](docs/reference.md#try-this-first) for shortcuts, drafts and history search.
-
-## Limits and warnings
-
-Each child uses your provider account and can spend tokens. See [usage accounting](docs/reference.md#usage-accounting) for details.
-
-Children normally inherit Pi's tools, extensions, project instructions and skills. Restrict [tools](docs/reference.md#tool-and-extension-selection) and [project trust](docs/reference.md#projecttrust) when a child must have limited access.
-
-Intercom is included. It lets Pi sessions exchange messages and lets a child ask its parent for a decision.
-
-Read the [Intercom guide](docs/intercom.md) for setup and host limits. The [secure bridge](docs/intercom-bridge.md) adds unattended remote messaging, durable inboxes, groups, live/saved session discovery, spawn/resume and native controls for an authenticated remote agent.
-
-Indexed history requires SQLite 3.53.4 through Node's built-in `node:sqlite` binding. Other SQLite versions fail. See the [storage requirements](docs/performance.md#storage-budgets-and-recovery) and [host startup costs](docs/performance.md#necessary-costs-and-limits).
-
-## Update and troubleshoot
-
-An update can leave active sessions on old code. Close all Pi sessions that use this installation before an update.
-
-Run this command from a separate terminal:
-
-```bash
-pi update --extension npm:@fitchmultz/pi-subagents
+```js
+intercom({ action: "list" });
+intercom({ action: "send", to: "auth-review", message: "Focus on token rotation." });
+intercom({ action: "last", to: "auth-review" });
 ```
 
-Start new Pi processes after the update. `/reload` does not reliably activate changed JavaScript.
-
-Run `/subagents-doctor` to check delegation and Intercom setup. See the [installation reference](docs/reference.md#installation) for Git updates, local rebuilds and broker restarts.
-
-## Documentation
-
-- [Full reference](docs/reference.md): profiles, commands, configuration, workflows and saved run records.
-- [Development](docs/development.md): builds, CI, compatibility checks and optional model smoke tests.
-- [Example prompts](prompts/): saved examples for common tasks.
-- [Changelog](CHANGELOG.md): changes by version.
-
-## License
-
-[MIT](LICENSE).
+`send` steers by default. `last` reads the peer's last completed assistant response
+without waking it; large responses are paged, not silently truncated. Discovery
+works across project directories and Pi agent directories under the same OS user.
+
+A main and its children form one group:
+
+- Every pair within that group can discover and communicate with each other.
+- Main sessions can discover, message, and read other mains.
+- Children cannot discover or address another group's agents—even by exact ID.
+- Only mains can delegate. There is one child level, not recursive spawning.
+
+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, 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
+result when a process disappears.
+
+Children use native Pi sessions and the selected host's SDK, resources, tools,
+project instructions, and model configuration. Optional `cwd` and `model`
+overrides belong to a launch; ordinary continuation reuses its saved conversation
+and launch configuration. No user agent Markdown files are edited or consulted
+as profiles.
+
+## Migration and documentation
+
+This rebuild deliberately removes the profile editor, workflow/chain/fanout DSL,
+Claude Code backend, custom agent overlays, supervisor-question revival protocol,
+and remote launch/control/catalog APIs. Grok bots retain messaging but lose remote
+spawn/resume/session/transcript/group/broadcast access; those retired commands are
+not bridge-outage symptoms. Update saved bot prompts/routines to correlated
+`send` before cutover.
+
+Existing installations must finish in-flight work and reload **every participating
+Pi session** onto the same approved version before resuming remote traffic. Old
+and new brokers do not forward across namespaces. Keep the prior package and saved
+state for rollback; qualify the helper and Box client/worker as an immutable pair,
+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)
+- [Development and qualification](docs/development.md)
+- [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, 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

@@ -0,0 +1,104 @@
+import { Type } from "./typebox.js";
+export const thinkingSchema = Type.Union([
+    Type.Literal("off"),
+    Type.Literal("minimal"),
+    Type.Literal("low"),
+    Type.Literal("medium"),
+    Type.Literal("high"),
+    Type.Literal("xhigh"),
+    Type.Literal("max"),
+]);
+export const launchSchema = Type.Object({
+    version: Type.Literal(1),
+    id: Type.String(),
+    rootId: Type.String(),
+    predecessor: Type.Optional(Type.String()),
+    owner: Type.String(),
+    cwd: Type.String(),
+    agentDir: Type.String(),
+    sdk: Type.String(),
+    entry: Type.String(),
+    sessionFile: Type.String(),
+    sessionId: Type.String(),
+    prompt: Type.String(),
+    context: Type.Union([Type.Literal("fresh"), Type.Literal("fork")]),
+    provider: Type.String(),
+    model: Type.String(),
+    thinking: thinkingSchema,
+    trusted: Type.Boolean(),
+    name: Type.Optional(Type.String()),
+    createdAt: Type.Number(),
+});
+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({
+    ...Type.Pick(processSchema, ["pid", "identity", "clock"]).properties,
+    generation: Type.String(),
+    attached: Type.Boolean(),
+});
+export const usageSchema = Type.Object({
+    input: Type.Number({ minimum: 0 }),
+    output: Type.Number({ minimum: 0 }),
+    cacheRead: Type.Number({ minimum: 0 }),
+    cacheWrite: Type.Number({ minimum: 0 }),
+    totalTokens: Type.Number({ minimum: 0 }),
+    reasoning: Type.Optional(Type.Number({ minimum: 0 })),
+    cacheWrite1h: Type.Optional(Type.Number({ minimum: 0 })),
+    cost: Type.Object({
+        input: Type.Number({ minimum: 0 }),
+        output: Type.Number({ minimum: 0 }),
+        cacheRead: Type.Number({ minimum: 0 }),
+        cacheWrite: Type.Number({ minimum: 0 }),
+        total: Type.Number({ minimum: 0 }),
+    }),
+});
+export const contributionsSchema = Type.Array(Type.Object({
+    id: Type.String({ minLength: 1 }),
+    provider: Type.String(),
+    model: Type.String(),
+    usage: usageSchema,
+}));
+export const resultSchema = Type.Object({
+    id: Type.String(),
+    owner: Type.String(),
+    status: Type.Union([Type.Literal("completed"), Type.Literal("failed"), Type.Literal("stopped")]),
+    endedAt: Type.Number(),
+    terminalEntryId: Type.Optional(Type.String()),
+    error: Type.Optional(Type.String()),
+    contributions: Type.Optional(contributionsSchema),
+    accountingError: Type.Optional(Type.String()),
+    accountingPending: Type.Optional(Type.Object({
+        terminalCandidate: Type.String(),
+        baseline: Type.Array(Type.String()),
+    })),
+});
+export const commandSchema = Type.Object({
+    id: Type.String(),
+    runId: Type.String(),
+    action: Type.Union([Type.Literal("run"), Type.Literal("steer"), Type.Literal("stop")]),
+    prompt: Type.Optional(Type.String()),
+    actorToken: Type.Optional(Type.String()),
+    createdAt: Type.Number(),
+});
+export const successorSchema = Type.Object({ id: Type.String() });
+export const exitSchema = Type.Object({
+    pid: Type.Integer(),
+    code: Type.Union([Type.Integer(), Type.Null()]),
+    signal: Type.Union([Type.String(), Type.Null()]),
+    at: Type.Number(),
+});
+export const admissionSchema = Type.Object({
+    id: Type.String(),
+    action: Type.String(),
+    runId: Type.Optional(Type.String()),
+    state: Type.Optional(Type.Union([Type.Literal("accepted"), Type.Literal("stale")])),
+    at: Type.Number(),
+});

package/dist/agent/cwd.js

@@ -0,0 +1,51 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { write } from "./storage.js";
+export function localCwdOwner(source) {
+    return /(?:^|[/\\:@])(?:pi-)?change-working-dir(?:[/\\@:.>]|$)/.test(`${source.source}/${source.path}`);
+}
+function hasOwner(pi) {
+    return (pi.getAllTools().some((tool) => tool.name === "change_dir" || localCwdOwner(tool.sourceInfo)) ||
+        pi
+            .getCommands()
+            .some((command) => command.source === "extension" &&
+            (/^cwd(?::\d+)?$/.test(command.name) || localCwdOwner(command.sourceInfo))));
+}
+function reply(request) {
+    if (request.result?.error !== undefined && request.result.error !== "") {
+        throw new Error(request.result.error);
+    }
+    if (request.result && (request.result.cwd === undefined || request.result.cwd === "")) {
+        throw new Error("Directory owner returned no execution directory.");
+    }
+    return request.result?.cwd;
+}
+export function executionCwd(pi, ctx) {
+    const request = { sessionManager: ctx.sessionManager };
+    pi.events.emit("pi-change-working-dir:resolve-execution-cwd", request);
+    const cwd = reply(request);
+    if (cwd === undefined && hasOwner(pi)) {
+        throw new Error("Loaded directory owner did not resolve cwd; update pi-change-working-dir.");
+    }
+    return cwd ?? ctx.cwd;
+}
+export function initializeCwd(pi, ctx, cwd, directory) {
+    // A saved continuation restores its owner's latest selection, not its frozen launch directory.
+    const current = executionCwd(pi, ctx);
+    const marker = path.join(directory, "cwd-initialized.json");
+    if (fs.existsSync(marker)) {
+        return;
+    }
+    if (hasOwner(pi) || fs.realpathSync(current) !== fs.realpathSync(ctx.cwd)) {
+        const request = { sessionManager: ctx.sessionManager, path: cwd };
+        pi.events.emit("pi-change-working-dir:set-execution-cwd", request);
+        const selected = reply(request);
+        if (selected === undefined || fs.realpathSync(selected) !== fs.realpathSync(cwd)) {
+            throw new Error("Directory owner did not initialize the requested child cwd.");
+        }
+    }
+    else if (fs.realpathSync(ctx.cwd) !== fs.realpathSync(cwd)) {
+        throw new Error("Native child directory does not match launch cwd.");
+    }
+    write(marker, { cwd }, true);
+}

package/dist/agent/host.js

@@ -0,0 +1,69 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+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)) {
+        return false;
+    }
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    return (typeof value === "object" &&
+        value !== null &&
+        "name" in value &&
+        value.name === "@earendil-works/pi-coding-agent");
+}
+function launcherPackage() {
+    const entry = process.argv.at(1);
+    if (entry === undefined) {
+        return;
+    }
+    let directory = path.dirname(fs.realpathSync(entry));
+    while (directory !== path.dirname(directory)) {
+        if (isPackage(directory)) {
+            return directory;
+        }
+        directory = path.dirname(directory);
+    }
+    return undefined;
+}
+export function packageRoot() {
+    const configured = process.env.PI_PACKAGE_DIR;
+    if (configured !== undefined && configured.length > 0) {
+        if (!isPackage(configured)) {
+            throw new Error("PI_PACKAGE_DIR is not a Pi SDK.");
+        }
+        return configured;
+    }
+    const launcher = launcherPackage();
+    if (launcher !== undefined) {
+        return launcher;
+    }
+    const manifest = findPackageJSON("@earendil-works/pi-coding-agent", import.meta.url);
+    if (manifest === undefined) {
+        throw new Error("Cannot locate the native Pi SDK.");
+    }
+    return path.dirname(manifest);
+}
+export async function loadSDK(root) {
+    // Selected host SDK, not a second package-local runtime hidden behind Jiti aliases.
+    // oxlint-disable-next-line typescript/no-unsafe-assignment
+    const sdk = await import(__rewriteRelativeImportExtension(pathToFileURL(path.join(root, "dist/index.js")).href));
+    return sdk;
+}
+export function runtimeEntry() {
+    return fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "../index.ts" : "../index.js", import.meta.url));
+}
+export function isChild() {
+    return readIntercomLineage() !== undefined;
+}