@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/dist/shared/native-journal.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
-import { scanJournal } from "./journal-frames.js";
+import { JournalFrames } from "./journal-frames.js";
 import { nativeProjection } from "./journal-projections.js";
-import { isRecord, recordAt } from "./unknown.js";
+import { isRecord } from "./unknown.js";
 function preview(record, parent, legacy) {
     const entry = record.value;
     if (typeof entry.type !== "string") {
@@ -18,45 +18,40 @@ function preview(record, parent, legacy) {
     };
     return { value, start: record.start, end: record.end };
 }
-function configurationModel(value) {
-    const message = recordAt(value, "message");
-    const provider = value.type === "model_change" ? value.provider : message?.provider;
-    const model = value.type === "model_change" ? value.modelId : message?.model;
-    return typeof provider === "string" && typeof model === "string"
-        ? `${provider}/${model}`
-        : undefined;
-}
 export class NativeJournal {
     records = [];
     byId = new Map();
     stamp;
     end;
     file;
-    constructor(file, policy = "inspect", requireNewline = policy === "live") {
+    identity;
+    offset = 0;
+    frames;
+    constructor(file, policy = "inspect", requireNewline = policy === "live", options = {}) {
         this.file = file;
-        const fd = fs.openSync(file, "r");
+        let parent = null;
+        this.frames = new JournalFrames(options.select ?? nativeProjection, (raw) => {
+            const record = preview(raw, parent, this.records[0]?.value.version === 1);
+            if (!record) {
+                if (policy !== "inspect") {
+                    throw new SyntaxError(`Native record at byte ${raw.start} requires a type`);
+                }
+                return;
+            }
+            if (record.value.type !== "session") {
+                parent = record.value.id;
+            }
+            this.records.push(record);
+            this.byId.set(record.value.id, record);
+        }, { policy, requireNewline });
+        const fd = fs.openSync(file, fs.constants.O_RDONLY | (policy === "live" ? fs.constants.O_NOFOLLOW : 0));
         try {
             const stat = fs.fstatSync(fd, { bigint: true });
             this.stamp = journalStamp(stat);
+            this.identity = `${stat.dev}:${stat.ino}`;
             this.end = Number(stat.size);
-            let parent = null;
-            scanJournal(fd, nativeProjection, (raw) => {
-                const record = preview(raw, parent, this.records[0]?.value.version === 1);
-                if (!record) {
-                    if (policy !== "inspect") {
-                        throw new SyntaxError(`Native record at byte ${raw.start} requires a type`);
-                    }
-                    return;
-                }
-                if (record.value.type !== "session") {
-                    parent = record.value.id;
-                }
-                this.records.push(record);
-                this.byId.set(record.value.id, record);
-            }, { policy, requireNewline, end: this.end });
-            if (journalStamp(fs.fstatSync(fd, { bigint: true })) !== this.stamp) {
-                throw new Error("Journal changed while indexing; refresh history.");
-            }
+            this.index(fd, Math.min(this.end, options.readBytes ?? Infinity));
+            this.checkInitial(stat, fs.fstatSync(fd, { bigint: true }), policy);
         }
         finally {
             fs.closeSync(fd);
@@ -65,21 +60,101 @@ export class NativeJournal {
             throw new Error("Not a readable native Pi session.");
         }
     }
-    branch(leaf, endedAt) {
+    checkInitial(before, after, policy) {
+        if (journalStamp(after) !== this.stamp &&
+            (policy !== "live" ||
+                after.size < before.size ||
+                `${after.dev}:${after.ino}` !== this.identity)) {
+            throw new Error("Journal changed while indexing; refresh history.");
+        }
+    }
+    index(fd, end) {
+        const buffer = Buffer.allocUnsafe(65536);
+        while (this.offset < end) {
+            const count = fs.readSync(fd, buffer, 0, Math.min(buffer.length, end - this.offset), this.offset);
+            if (count === 0) {
+                throw new Error("Journal truncated while reading");
+            }
+            this.frames.write(buffer.subarray(0, count));
+            this.offset += count;
+        }
+        this.frames.finish();
+    }
+    get indexed() {
+        return this.offset === this.end;
+    }
+    /** Incremental, LF-published indexing. Append work is budgeted independently of paint. */
+    refresh(bytes = 256 * 1024) {
+        const fd = fs.openSync(this.file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            const stat = fs.fstatSync(fd, { bigint: true });
+            if (`${stat.dev}:${stat.ino}` !== this.identity || Number(stat.size) < this.offset) {
+                throw new Error("Native journal was replaced or truncated; reopen this conversation.");
+            }
+            if (journalStamp(stat) === this.stamp && this.indexed) {
+                return false;
+            }
+            const previous = this.records.length;
+            this.end = Number(stat.size);
+            this.index(fd, Math.min(this.end, this.offset + bytes));
+            this.stamp = journalStamp(stat);
+            return previous !== this.records.length;
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    /** Project one immutable, published record, including bounded slices of very large strings. */
+    async project(record, select, stringChunk, signal) {
+        const fd = fs.openSync(this.file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        let stream;
+        try {
+            const stat = fs.fstatSync(fd, { bigint: true });
+            if (`${stat.dev}:${stat.ino}` !== this.identity || Number(stat.size) < record.end) {
+                throw new Error("Native journal was replaced or truncated.");
+            }
+            let value;
+            const frames = new JournalFrames(select, (entry) => {
+                value = entry.value;
+            }, { policy: "live", start: record.start, stringChunk });
+            stream = fs.createReadStream(this.file, {
+                fd,
+                start: record.start,
+                end: record.end - 1,
+                highWaterMark: 65536,
+                signal,
+            });
+            for await (const chunk of stream) {
+                if (!Buffer.isBuffer(chunk)) {
+                    throw new TypeError("Native journal reads require bytes.");
+                }
+                frames.write(chunk);
+            }
+            frames.finish();
+            if (!value) {
+                throw new Error("Native entry is not published.");
+            }
+            return value;
+        }
+        finally {
+            if (stream) {
+                stream.destroy();
+            }
+            else {
+                fs.closeSync(fd);
+            }
+        }
+    }
+    branch(leaf) {
         if (leaf === null) {
             return [];
         }
-        const eligible = endedAt === undefined
-            ? this.records
-            : this.records.filter((record) => record.value.type === "session" ||
-                Date.parse(record.value.timestamp ?? "") <= endedAt);
         let current = leaf !== undefined && leaf !== ""
             ? this.byId.get(leaf)
-            : eligible.findLast((record) => record.value.type !== "session");
+            : this.records.findLast((record) => record.value.type !== "session");
         const path = [];
         const seen = new Set();
-        const allowed = new Set(eligible.map((record) => record.value.id));
-        while (current && current.value.type !== "session" && allowed.has(current.value.id)) {
+        while (current && current.value.type !== "session") {
             if (seen.has(current.value.id)) {
                 throw new Error("Cyclic journal ancestry");
             }
@@ -116,24 +191,16 @@ export class NativeJournal {
             fs.closeSync(fd);
         }
     }
-    configuration(endedAt, leaf) {
-        const result = {};
-        let model;
-        for (const { value } of this.branch(leaf, endedAt)) {
-            if (value.type === "thinking_level_change" && typeof value.thinkingLevel === "string") {
-                result.thinking = value.thinkingLevel;
-            }
-            if (value.type === "model_change" ||
-                (value.type === "message" && recordAt(value, "message")?.role === "assistant")) {
-                model = value;
-            }
-        }
-        if (model) {
-            result.model = configurationModel(model);
-            result.modelRecordedAt = Date.parse(model.timestamp ?? "");
-        }
-        return result;
-    }
+}
+/** Native v3 writers append after attachment; loading older formats can rewrite in place.
+ * Outside prefix edits followed by same-inode growth are not an append-only operation.
+ */
+export function nativeAppend(before, after, header) {
+    return (header?.type === "session" &&
+        header.version === 3 &&
+        before.dev === after.dev &&
+        before.ino === after.ino &&
+        after.size > before.size);
 }
 export function journalStamp(stat) {
     return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;

package/dist/shared/parking.js

@@ -0,0 +1,12 @@
+import { isRecord } from "./unknown.js";
+/** A child actor asks its intercom to fence broker input before parking, or to release it. */
+export const PARK = "pi-subagents:park";
+/** A main intercom wakes or reads an exited parked child through the agent runtime. */
+export const WAKE = "pi-subagents:wake";
+export const PARKED_HISTORY = "pi-subagents:parked-history";
+export function isParkRequest(value) {
+    return isRecord(value) && typeof value.park === "boolean" && typeof value.reply === "function";
+}
+export function isHistoryRequest(value) {
+    return isRecord(value) && typeof value.peer === "string" && typeof value.reply === "function";
+}

package/dist/shared/post-exit-stdio-guard.js

@@ -1,6 +1,27 @@
-import { execFileSync } from "node:child_process";
-import { readLinuxProcess } from "../pi-intercom/broker/pid.js";
+import { execFile, execFileSync } from "node:child_process";
+import { readFileSync, readlinkSync } from "node:fs";
+import { isLinuxProcessReplaced, readLinuxProcess } from "../pi-intercom/broker/pid.js";
 import { hasErrorCode } from "./unknown.js";
+const BIRTH_FIELDS = ["lstart=", "pgid="];
+/** Capture only a real, cross-process clock context; unavailable context proves nothing. */
+export function readProcessClock() {
+    if (process.platform !== "android") {
+        return undefined;
+    }
+    try {
+        const boot = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+        const namespace = readlinkSync("/proc/self/ns/time");
+        const at = process.hrtime.bigint();
+        return at > 0n &&
+            /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/.test(boot) &&
+            /^time:\[\d+\]$/.test(namespace)
+            ? { boot, namespace, at: at.toString() }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Capture the detached group leader's birth identity; Pi may replace its command-line title. */
 export function readChildProcessIdentity(pid) {
     if (!Number.isSafeInteger(pid) || pid <= 0) {
@@ -9,21 +30,113 @@ export function readChildProcessIdentity(pid) {
     if (process.platform === "linux") {
         return readLinuxProcess(pid)?.identity;
     }
+    return groupLeader(pid, readPsFields(pid, BIRTH_FIELDS));
+}
+function groupLeader(pid, birth) {
+    return Number(birth?.split(" ").at(-1)) === pid ? birth : undefined;
+}
+// Always one PID: Darwin ps given several PIDs scans every process at many times the cost.
+function psArguments(pid, fields) {
+    return ["-p", String(pid), ...fields.flatMap((field) => ["-o", field])];
+}
+function psOptions(zone) {
+    const env = { ...process.env, LC_ALL: "C", ...(zone === undefined ? {} : { TZ: zone }) };
+    return { encoding: "utf8", timeout: 1000, env };
+}
+function readPsFields(pid, fields, zone) {
     try {
-        const identity = execFileSync("ps", ["-p", String(pid), "-o", "lstart=", "-o", "pgid="], {
-            encoding: "utf8",
-            timeout: 1000,
+        return execFileSync("ps", psArguments(pid, fields), {
+            ...psOptions(zone),
             stdio: ["ignore", "pipe", "ignore"],
-            env: { ...process.env, LC_ALL: "C" },
         })
             .trim()
             .replace(/\s+/g, " ");
-        return Number(identity.split(" ").at(-1)) === pid ? identity : undefined;
     }
     catch {
         return undefined;
     }
 }
+/** Nonblocking `readPsFields`; a failed run likewise observes nothing. */
+function observePsFields(pid, fields, zone) {
+    return new Promise((resolve) => {
+        execFile("ps", psArguments(pid, fields), psOptions(zone), (error, stdout) => {
+            resolve(error ? undefined : stdout.trim().replace(/\s+/g, " "));
+        });
+    });
+}
+// C-locale ps lstart (whole-second birth, in the reader's zone), then the process group.
+const PS_IDENTITY = /^[A-Z][a-z]{2} ([A-Z][a-z]{2}) (\d{1,2}) (\d{2}):(\d{2}):(\d{2}) (\d{4}) \d+$/;
+const MONTHS = "JanFebMarAprMayJunJulAugSepOctNovDec";
+/** Parses a birth observed with TZ=UTC0. */
+function utcBirth(birth) {
+    const [, month = "", day, hours, minutes, seconds, year] = PS_IDENTITY.exec(birth ?? "") ?? [];
+    const index = MONTHS.indexOf(month);
+    // Unreadable or malformed observations yield NaN, which never proves a later birth.
+    return month.length === 3 && index % 3 === 0
+        ? Date.UTC(Number(year), index / 3, Number(day), Number(hours), Number(minutes), Number(seconds))
+        : Number.NaN;
+}
+function sameClock(left, right) {
+    return left.boot === right.boot && left.namespace === right.namespace;
+}
+/** Android's elapsed age bounds birth in the saved monotonic clock, never wall time. */
+function clockBound(clock) {
+    const before = readProcessClock();
+    return clock !== undefined && before !== undefined && sameClock(clock, before)
+        ? { clock, before }
+        : undefined;
+}
+/** `elapsed` is observed after the bound's `before` read; the closing clock read follows both. */
+function bornAfter({ clock, before }, elapsed = "") {
+    const after = readProcessClock();
+    if (after === undefined || !sameClock(before, after) || !/^\d+$/.test(elapsed)) {
+        return false;
+    }
+    // Include displayed-second and native tick uncertainty. BOOTTIME age includes suspend,
+    // unlike hrtime's MONOTONIC clock, so suspend only moves this lower bound earlier.
+    const birth = BigInt(before.at) - (BigInt(elapsed) + 2n) * 1000000000n;
+    return BigInt(after.at) >= BigInt(before.at) && birth > BigInt(clock.at);
+}
+/**
+ * True only when a live PID provably names a different process than an owner-published record.
+ * Darwin identities are unzoned local times, so they are never compared across zones; only a
+ * UTC-observed birth strictly after the record's publication proves replacement. Android uses
+ * a conservative elapsed-age bound against its recorded boot-qualified monotonic clock.
+ */
+export function isChildProcessReplaced(pid, recorded, published, clock) {
+    if (process.platform === "linux") {
+        return isLinuxProcessReplaced(pid, recorded);
+    }
+    if (!PS_IDENTITY.test(recorded)) {
+        return false;
+    }
+    if (process.platform === "android") {
+        const bound = clockBound(clock);
+        return bound !== undefined && bornAfter(bound, readPsFields(pid, ["etimes="]));
+    }
+    return published !== undefined && utcBirth(readPsFields(pid, BIRTH_FIELDS, "UTC0")) > published;
+}
+/**
+ * Nonblocking `readChildProcessIdentity(pid) !== recorded && isChildProcessReplaced(...)` for
+ * routine liveness. Signals still need the fresh synchronous proof.
+ */
+export async function observeChildProcessReplaced(pid, recorded, published, clock) {
+    if (process.platform === "linux") {
+        return readChildProcessIdentity(pid) !== recorded && isLinuxProcessReplaced(pid, recorded);
+    }
+    if (!PS_IDENTITY.test(recorded) ||
+        groupLeader(pid, await observePsFields(pid, BIRTH_FIELDS)) === recorded) {
+        return false;
+    }
+    if (process.platform === "android") {
+        const bound = clockBound(clock);
+        return bound !== undefined && bornAfter(bound, await observePsFields(pid, ["etimes="]));
+    }
+    if (published === undefined) {
+        return false;
+    }
+    return utcBirth(await observePsFields(pid, BIRTH_FIELDS, "UTC0")) > published;
+}
 function trySignalChild(child, signal) {
     try {
         return child.kill(signal);

package/dist/shared/tui-action.js

@@ -0,0 +1,29 @@
+import { MouseRegion, TruncatedText, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
+export function actionText(text, action) {
+    const component = new TruncatedText(text, 0, 0);
+    return new MouseRegion(component, (event) => {
+        if ((event.type !== "press" && event.type !== "click") ||
+            event.button !== "left" ||
+            event.x >= visibleWidth(truncateToWidth(text, event.width))) {
+            return;
+        }
+        if (event.type === "click") {
+            action(event.x);
+        }
+        return { handled: true, render: event.type === "click" };
+    });
+}
+/** Each visible hint dispatches the same action as its corresponding keyboard binding. */
+export function actionHints(hints) {
+    return actionText(hints.map((hint) => hint.text).join(" · "), (column) => {
+        let start = 0;
+        for (const hint of hints) {
+            const end = start + visibleWidth(hint.text);
+            if (column >= start && column < end) {
+                hint.action();
+                return;
+            }
+            start = end + 3;
+        }
+    });
+}

package/dist/shared/unknown.d.ts

@@ -0,0 +1,9 @@
+/** JSON and caught failures cross the process/filesystem boundary as unknown values. */
+export type UnknownRecord = Readonly<Record<string, unknown>>;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isUnknownArray(value: unknown): value is readonly unknown[];
+export declare function recordAt(value: unknown, key: string | number): UnknownRecord | undefined;
+export declare function errorMessage(error: unknown): string;
+export declare function hasErrorCode(error: unknown, code: string): boolean;
+/** Retain native error names without letting a broken stringifier replace the caught failure. */
+export declare function errorDescription(error: unknown): string;

package/docs/code-quality.md

@@ -34,6 +34,8 @@ tests. CI separately qualifies the latest official Pi on GitHub-hosted Linux and
 the maintained fork on Linux and macOS. There is no custom checker build, probe
 suite or self-hosted runner requirement.
 
-CI's lint job also enforces the production line/byte shrink budget before
-qualification substitutes the selected host graph. The retired workflow schema
-generator and its patching dependency are not part of the new runtime.
+CI's lint job also enforces the production byte ceiling before qualification
+substitutes the selected host graph. The retired workflow schema generator and
+its patching dependency are not part of the new runtime. `npm run check:size`
+still reports source and production line counts for visibility; no line count
+is mandated. The 1 MiB byte ceiling and all lint limits stay unchanged.

package/docs/development.md

@@ -1,5 +1,10 @@
 # Development
 
+The supported Intercom client's package export uses emitted declarations for consumers.
+The repository's native `development` type condition points at its TypeScript source so
+cold lint and type checks do not require a prior build. Packed-consumer checks compile
+against the default declaration export without that condition or private path aliases.
+
 Use a dedicated worktree, the committed npm lockfile, and a ready-for-review PR.
 Never edit source or tests while checks run in that checkout. Do not modify an
 active installed copy or reload the user's sessions to test a candidate.
@@ -16,8 +21,42 @@ Run narrow owner-boundary tests locally through `scripts/run-tests.mjs`. Full
 `npm run ci` belongs in hosted CI and includes package/install smokes and the
 complete suites. Keep the strict Oxlint/Oxfmt rules; see [code quality](code-quality.md).
 
+## Native Android/Termux
+
+Use app-private storage, not Android's shared `/sdcard` filesystem. No Termux app
+patch, privileged access, or Android security-policy change is required.
+
+TypeScript 7.0.2 does not publish its Android ARM64 npm compiler package. Source
+installs, `build`, and `typecheck` therefore use an Android-native `tsgo` on PATH;
+other platforms keep using the committed npm TypeScript version. Install a native
+build from Microsoft's maintained [TypeScript source](https://github.com/microsoft/typescript-go)
+with Android support. A Linux ARM64 binary is not an Android substitute. The
+prebuilt npm package needs no compiler.
+
+The package uses Termux's shared `$PREFIX/tmp` for its default broker and
+observation endpoints, independently of individual sessions' HOME or TMPDIR.
+Other Android environments without PREFIX use Node's native temporary directory.
+Tests keep their isolated sockets short enough for the same 100-byte path limit.
+
+Android process-reuse checks compare native elapsed age with a saved monotonic
+bound, qualified by the real boot ID and time namespace, rather than wall clocks
+or `ps` boot-epoch dates. Keep the conservative second/tick allowance and reject
+missing or incomparable clock evidence. Legacy records without that evidence
+retain fail-closed identity checks; do not bypass unavailable procfs PID-namespace
+guards or invent a namespace.
+
+The published Oxlint type-aware backend currently has no Android package. Keep
+the canonical lint command and rules intact and obtain its passing evidence in
+hosted CI; do not substitute a weakened checker or incompatible Linux executable.
+
 ## Runtime qualification
 
+The official development SDK 1.4.0 pins Undici 8.10.2 exactly. A parent-scoped
+override selects 8.12.3 for that development graph to fix GHSA-4qv8-2p9j-2685,
+GHSA-f72v-6w45-q472 and GHSA-xjj6-f33q-929c. Remove the override when an official
+SDK release supplies a fixed version. It does not replace a consumer's host SDK
+or Node's built-in fetch.
+
 Qualify the latest stable official Pi and the intended fork revision separately.
 Record the exact package root, revision/build, Node binary, and executed test
 commands. Matching versions do not establish matching runtime behavior.
@@ -52,9 +91,9 @@ negative assertions. A sleep does not prove an owner processed its input.
 
 `scripts/measure-size.mjs` counts source, production scripts, generated code and
 schemas, including new untracked files. `--report` prints without enforcing.
-The ceilings are 16,000 source TypeScript lines, 20,000 total production lines,
-and 1 MiB total production bytes. Tests have no deletion quota. Moving machinery
-into generated/minified output does not evade the gate.
+The only enforced ceiling is 1 MiB total production bytes; source and production
+line counts are reported for visibility, not mandated. Tests have no deletion
+quota. Moving machinery into generated/minified output does not evade the gate.
 
 [The rebuild evidence](single-agent-rebuild.md) records the baseline, confirmed
 design, test-transfer obligations, and exact selected host identities. Update it

package/docs/intercom-bridge.md

@@ -122,10 +122,15 @@ retries. A lost response is **UNKNOWN**, not proof that a message was unsent.
 | `POST /v1/ack`      | `{ids}` (at most 256)                                     | `acked`; durable intake ownership transferred              |
 
 `to` uses the existing exact-ID/name resolver; ambiguity never selects a peer.
-Explicit message IDs survive byte-for-byte. `passive:true` is mailbox-only and
-never wakes. Acceptance means transport/broker admission, not native journal
-persistence, model start, reply completion or task completion. A bare `ok:true`
-is not an acceptance receipt.
+Explicit message IDs survive byte-for-byte. Use a fresh `--id` / `messageId` for
+each new logical message; reuse it only to retry that same message. Updated native
+recipients ignore an already-admitted ID even if a retry changes its payload,
+while the broker can still report transport acceptance. Do not reuse a previous
+ID to send a different instruction.
+
+`passive:true` is mailbox-only and never wakes. Acceptance means transport/broker
+admission, not native journal persistence, model start, reply completion or task
+completion. A bare `ok:true` is not an acceptance receipt.
 
 The maintained client is `scripts/intercom-remote.mjs`. Copy it unchanged with
 only the CA, client certificate and private key to a private remote directory.