pi-better-subagents 0.1.0

package/registry.ts

@@ -0,0 +1,236 @@
+/**
+ * Run registry — durable metadata for each spawned subagent.
+ *
+ * The authoritative record for every run is a `meta.json` sidecar on disk, so
+ * `list` / `output` / `result` keep working across foreground turns, `/reload`,
+ * and even a full pi restart. In-memory state holds only the live exit handlers
+ * for runs this process spawned.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { processExists } from "./spawn.ts";
+import type { LifecycleClassification } from "./lifecycle.ts";
+
+/**
+ * Terminal + live statuses as recorded on disk. `orphaned` is durable and
+ * NON-terminal (supervision broke, but related processes may still be alive);
+ * `lost` is durable and terminal (no related process evidence remains).
+ */
+export type RunStatus = "running" | "completed" | "failed" | "killed" | "orphaned" | "lost";
+
+export interface RunCallbackOrigin {
+    cwd: string;
+    sessionId?: string;
+}
+
+/**
+ * True when coherent child-exit evidence may finalize a run in this status.
+ * `running` is the normal path; `orphaned`/`lost` are PROVISIONAL
+ * reconciliation verdicts (a health tick can observe the just-exited pid
+ * before the close handler runs) that the real exit — the stronger evidence —
+ * supersedes. True terminal records are never overwritten: finalization is
+ * idempotent (`completed`/`failed`) and a deliberate `subagent_stop` kill
+ * (`killed`) is not undone by the resulting exit.
+ */
+export function canExitFinalize(status: RunStatus): boolean {
+    return status === "running" || status === "orphaned" || status === "lost";
+}
+
+export interface RunMeta {
+    id: string;
+    name?: string;
+    status: RunStatus;
+    /** Child process PID. */
+    pid: number;
+    /** Child's process group id, captured at spawn where available (#63). */
+    pgid?: number;
+    /**
+     * Opaque process-start identity token captured at spawn where available
+     * (#63). Only equality is meaningful: a different token means the pid was
+     * recycled by an unrelated process.
+     */
+    pidStartTime?: string;
+    /** Consecutive pid-gone health ticks with no related evidence (old metadata). */
+    probeMisses?: number;
+    /** When supervision was observed broken (transition to `orphaned`). */
+    orphanedAt?: number;
+    /** When the last related process evidence disappeared (transition to `lost`). */
+    lostAt?: number;
+    /**
+     * Durable per-status health-callback handoff markers (#65).
+     * Written only after a successful coordinator handoff (sendMessage returned,
+     * or callback:false suppressed the model path intentionally). Once set,
+     * repeated health ticks and /reload must not re-fire that status. A missing
+     * marker on orphaned/lost means recovery must still attempt delivery.
+     * Independent of completion callbacks.
+     */
+    orphanedCallbackSentAt?: number;
+    lostCallbackSentAt?: number;
+    /** PID of the pi process that launched this run (for cross-restart ownership). */
+    spawnPid: number;
+    model?: string;
+    cwd: string;
+    /** First ~200 chars of the task prompt, for listings. */
+    promptPreview: string;
+    startedAt: number;
+    endedAt?: number;
+    exitCode?: number | null;
+    /** Why an otherwise-zero exit is recorded as a non-success. */
+    failureReason?: "incomplete-stream";
+    /** Named lifecycle quality from exit/stream validation. */
+    lifecycleClassification?: LifecycleClassification;
+    logPath: string;
+    /** Child subagent session id. */
+    sessionId: string;
+    /** Foreground session that is allowed to receive unsolicited callbacks. */
+    callbackOrigin?: RunCallbackOrigin;
+    completionCallbackSuppressedAt?: number;
+    completionCallbackSuppressedReason?: string;
+    orphanedCallbackSuppressedAt?: number;
+    orphanedCallbackSuppressedReason?: string;
+    lostCallbackSuppressedAt?: number;
+    lostCallbackSuppressedReason?: string;
+    /** Writable dir the child is OS-sandboxed to, if any. */
+    sandbox?: string;
+    /** Whether completion posts the result back to the main session (default true). */
+    callback?: boolean;
+    /** Batch ID for runs launched via subagent_spawn_batch. */
+    batchId?: string;
+    /** Optional batch display name. */
+    batchName?: string;
+    /**
+     * Durable navigator-dismissal timestamp (ms since epoch). Optional and
+     * additive: pre-existing metadata without this field parses unchanged, so
+     * no migration is required. Dismissal is navigator-organization ONLY — it
+     * never deletes logs, prompt, session data, metadata, or id-based tool
+     * access (`subagent_output` / `subagent_result` / `subagent_stop` /
+     * `subagent_list` keep working for dismissed runs).
+     */
+    dismissedAt?: number;
+}
+
+/** Root runtime dir, deliberately OUTSIDE any repo. */
+export function baseDir(): string {
+    return join(tmpdir(), "pi-better-subagents");
+}
+export function sessionsDir(): string {
+    return join(baseDir(), "sessions");
+}
+export function runDir(id: string): string {
+    return join(baseDir(), "runs", id);
+}
+export function logPathFor(id: string): string {
+    return join(runDir(id), "output.log");
+}
+export function promptPathFor(id: string): string {
+    return join(runDir(id), "prompt.md");
+}
+function metaPathFor(id: string): string {
+    return join(runDir(id), "meta.json");
+}
+
+let seq = 0;
+/** Monotonic, readable, collision-free run id: `sa_<base36-time>_<seq>`. */
+export function nextRunId(): string {
+    seq += 1;
+    return `sa_${Date.now().toString(36)}_${seq}`;
+}
+
+export function writeMeta(meta: RunMeta): void {
+    mkdirSync(runDir(meta.id), { recursive: true });
+    writeFileSync(metaPathFor(meta.id), JSON.stringify(meta, null, 2));
+}
+
+export function readMeta(id: string): RunMeta | undefined {
+    try {
+        return JSON.parse(readFileSync(metaPathFor(id), "utf-8")) as RunMeta;
+    } catch {
+        return undefined;
+    }
+}
+
+/** All runs, newest first. */
+export function listMetas(): RunMeta[] {
+    let ids: string[];
+    try {
+        ids = readdirSync(join(baseDir(), "runs"));
+    } catch {
+        return [];
+    }
+    return ids
+        .map(readMeta)
+        .filter((m): m is RunMeta => m !== undefined)
+        .sort((a, b) => b.startedAt - a.startedAt);
+}
+
+/**
+ * Reconcile the recorded status with reality for display. A run marked
+ * "running" whose PID is no longer alive exited without our handler firing
+ * (foreground pi was closed / restarted) — surface that as "exited".
+ */
+export function effectiveStatus(meta: RunMeta): RunStatus | "exited" {
+    if (meta.status !== "running") return meta.status;
+    if (processExists(meta.pid)) return "running";
+    return "exited";
+}
+
+/**
+ * True when a status can yield a FINAL result: everything except `running`
+ * and the non-terminal `orphaned`. `lost` is terminal (best-available
+ * artifacts, never a completion); `exited` keeps its historic resultable
+ * treatment. Used by subagent_result's gate.
+ */
+export function isFinalResultStatus(status: RunStatus | "exited"): boolean {
+    return status !== "running" && status !== "orphaned";
+}
+
+/** True when this meta was spawned by the given parent pi PID (default: this process). */
+export function ownedByThisParent(
+    meta: Pick<RunMeta, "spawnPid">,
+    parentPid: number = process.pid,
+): boolean {
+    return meta.spawnPid === parentPid;
+}
+
+/** True when the run has been dismissed from the human navigator. */
+export function isDismissed(meta: Pick<RunMeta, "dismissedAt">): boolean {
+    return typeof meta.dismissedAt === "number";
+}
+
+/**
+ * Mark a run dismissed from the navigator, durably. Idempotent: the first
+ * dismissal timestamp wins. Returns the updated meta, or undefined for an
+ * unknown id. Only the timestamp changes — all other metadata is preserved.
+ */
+export function dismissRun(id: string, at: number = Date.now()): RunMeta | undefined {
+    const meta = readMeta(id);
+    if (!meta) return undefined;
+    if (meta.dismissedAt === undefined) {
+        meta.dismissedAt = at;
+        writeMeta(meta);
+    }
+    return meta;
+}
+
+/**
+ * Visible navigator runs: current-parent runs that are not dismissed. This is
+ * the single visibility calculation shared by the navigator list and the
+ * footer count, so they can never drift apart. `subagent_list` does NOT use
+ * this — the model-facing list keeps showing dismissed runs.
+ */
+export function navigatorVisibleRuns(
+    metas: RunMeta[],
+    parentPid: number = process.pid,
+): RunMeta[] {
+    return metas.filter((m) => ownedByThisParent(m, parentPid) && !isDismissed(m));
+}
+
+/** Footer-count seam: how many runs the navigator affordance advertises. */
+export function navigatorVisibleCount(
+    metas: RunMeta[],
+    parentPid: number = process.pid,
+): number {
+    return navigatorVisibleRuns(metas, parentPid).length;
+}

package/sandbox.ts

@@ -0,0 +1,164 @@
+/**
+ * OS-level write sandbox for subagent children.
+ *
+ * Kernel-enforced confinement: the child may READ anywhere and use the network
+ * (so web_fetch and the model API keep working), but may only WRITE under a
+ * single directory plus the system paths pi itself needs to function. Unlike the
+ * cooperative guardrails layer (which pattern-matches tool inputs), this cannot
+ * be evaded by a crafted bash command — the write syscall itself is denied.
+ *
+ * Backends are selected here so callers retain a platform-neutral support query
+ * and command-wrapper contract. Linux support adds a backend without changing
+ * detached spawning policy in the extension.
+ */
+
+import { platform } from "node:os";
+import { accessSync, constants, realpathSync, statSync, writeFileSync } from "node:fs";
+import { delimiter, resolve } from "node:path";
+
+type SandboxCommandArgs = {
+    profilePath: string;
+    writableDir: string;
+    home: string;
+    piBin: string;
+    piArgs: string[];
+};
+
+type SandboxCommand = { file: string; fileArgs: string[] };
+
+type SandboxBackend = {
+    buildCommand(args: SandboxCommandArgs): SandboxCommand;
+};
+
+type SandboxRequest = {
+    sandboxEnabled: boolean;
+    explicitSandbox: boolean;
+};
+
+/** Quote a path as an SBPL string literal. */
+function sbpl(path: string): string {
+    return `"${path.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/** Build the existing macOS sandbox-exec wrapper and SBPL profile. */
+function buildMacOSSandboxCommand(args: SandboxCommandArgs): SandboxCommand {
+    // Match on the real (symlink-resolved) path — sandbox-exec evaluates the
+    // canonical path, so /tmp/x must be written as /private/tmp/x.
+    let dir = args.writableDir;
+    try { dir = realpathSync(dir); } catch { /* not yet created; use as given */ }
+
+    const profile = [
+        "(version 1)",
+        "(allow default)",          // permissive base: reads, exec, network
+        "(deny file-write*)",       // ...then deny all writes...
+        `(allow file-write* (subpath ${sbpl(dir)}))`,               // ...except here
+        `(allow file-write* (subpath ${sbpl(`${args.home}/.pi`)}))`, // pi state
+        '(allow file-write* (subpath "/private/var/folders"))',      // macOS temp / our runtime
+        '(allow file-write* (subpath "/private/tmp"))',
+        '(allow file-write* (subpath "/dev"))',                      // /dev/null etc.
+        "",
+    ].join("\n");
+    writeFileSync(args.profilePath, profile);
+
+    return {
+        file: "/usr/bin/sandbox-exec",
+        fileArgs: ["-f", args.profilePath, args.piBin, ...args.piArgs],
+    };
+}
+
+const macOSSandboxBackend: SandboxBackend = {
+    buildCommand: buildMacOSSandboxCommand,
+};
+
+/** Resolve an executable from PATH without starting it or probing namespaces. */
+function executableFromPath(name: string): string | undefined {
+    const path = process.env.PATH;
+    if (!path) return undefined;
+
+    for (const entry of path.split(delimiter)) {
+        const candidate = resolve(entry || ".", name);
+        try {
+            if (!statSync(candidate).isFile()) continue;
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        } catch {
+            // A PATH entry may disappear or be inaccessible between lookup and use.
+        }
+    }
+    return undefined;
+}
+
+function buildLinuxSandboxCommand(bwrap: string, args: SandboxCommandArgs): SandboxCommand {
+    // The caller creates the selected work directory before it reaches this
+    // boundary. Canonicalizing it before bind-mounting keeps symlink aliases from
+    // widening the writable root.
+    const dir = realpathSync(args.writableDir);
+    return {
+        file: bwrap,
+        fileArgs: [
+            "--ro-bind", "/", "/",
+            "--bind", dir, dir,
+            "--bind", "/tmp", "/tmp",
+            "--dev", "/dev",
+            "--",
+            args.piBin, ...args.piArgs,
+        ],
+    };
+}
+
+function linuxSandboxBackend(): SandboxBackend | undefined {
+    const bwrap = executableFromPath("bwrap");
+    if (!bwrap) return undefined;
+    return { buildCommand: (args) => buildLinuxSandboxCommand(bwrap, args) };
+}
+
+function selectedSandboxBackend(): SandboxBackend | undefined {
+    const currentPlatform = platform();
+    if (currentPlatform === "darwin") return macOSSandboxBackend;
+    if (currentPlatform === "linux") return linuxSandboxBackend();
+    return undefined;
+}
+
+function sandboxUnavailableMessage(): string {
+    const currentPlatform = platform();
+    if (currentPlatform === "linux") {
+        return "Linux sandbox requires executable bubblewrap (bwrap) on PATH. Install bubblewrap or pass sandbox:false.";
+    }
+    if (currentPlatform === "darwin") {
+        return "macOS sandbox requires /usr/bin/sandbox-exec. Pass sandbox:false if it is unavailable.";
+    }
+    return `sandbox is unsupported on ${currentPlatform}. Pass sandbox:false on this platform.`;
+}
+
+/** True when an OS write-sandbox backend can be applied on this platform. */
+export function sandboxSupported(): boolean {
+    return selectedSandboxBackend() !== undefined;
+}
+
+/**
+ * Resolve the caller's default-on, explicit-request, and opt-out policy before
+ * spawning. A selected backend always returns its wrapper; callers never retry
+ * the child directly when that wrapper exits or cannot initialize.
+ */
+export function maybeBuildSandboxCommand(
+    args: SandboxCommandArgs,
+    request: SandboxRequest,
+): SandboxCommand | undefined {
+    if (!request.sandboxEnabled) return undefined;
+
+    const backend = selectedSandboxBackend();
+    if (!backend) {
+        if (request.explicitSandbox) throw new Error(sandboxUnavailableMessage());
+        return undefined;
+    }
+    return backend.buildCommand(args);
+}
+
+/**
+ * Return the selected backend's executable and ordered argv wrapper around pi.
+ * The fallback preserves the pre-existing direct-call result for callers that
+ * bypass the request-policy helper above.
+ */
+export function buildSandboxCommand(args: SandboxCommandArgs): SandboxCommand {
+    return (selectedSandboxBackend() ?? macOSSandboxBackend).buildCommand(args);
+}

package/spawn.ts

@@ -0,0 +1,78 @@
+/**
+ * Detached child-process spawn with file-backed output.
+ *
+ * Self-contained (adapted from the pi-patty-bg-tasks process model): the kernel
+ * writes the child's stdout+stderr straight to a log file with zero JS in the
+ * data path, and the child is `detached` + `unref`'d so it is fully isolated
+ * from the foreground pi turn. Progress is read back later by tailing the file.
+ */
+
+import { spawn } from "node:child_process";
+import { closeSync, mkdirSync, openSync, unlinkSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface SpawnResult {
+    pid: number;
+    /** Resolves with the child's exit code (null on signal exit). Never rejects. */
+    exit: Promise<number | null>;
+}
+
+/** Spawn `file fileArgs`, streaming stdout+stderr to `logPath`. Detached. */
+export function spawnDetached(args: {
+    file: string;
+    fileArgs: string[];
+    cwd: string;
+    logPath: string;
+}): SpawnResult {
+    mkdirSync(dirname(args.logPath), { recursive: true });
+    const outFd = openSync(args.logPath, "w");
+
+    let proc;
+    try {
+        proc = spawn(args.file, args.fileArgs, {
+            stdio: ["ignore", outFd, outFd],
+            cwd: args.cwd,
+            detached: true,
+            env: { ...process.env },
+        });
+    } finally {
+        closeSync(outFd);
+    }
+
+    // Build the exit promise and attach the 'error' listener BEFORE any throw,
+    // so an async spawn failure (ENOENT / EMFILE / EAGAIN) can never surface as
+    // an uncaught exception that takes the foreground pi down.
+    const exit = new Promise<number | null>((resolve) => {
+        proc.on("close", (code) => resolve(code));
+        proc.on("error", () => resolve(1));
+    });
+
+    if (!proc.pid) {
+        try { unlinkSync(args.logPath); } catch { /* best-effort */ }
+        throw new Error("Failed to spawn subagent process");
+    }
+    const pid = proc.pid;
+    proc.unref();
+    return { pid, exit };
+}
+
+/** Kill an entire process group via negative-PID signal; fall back to the PID. */
+export function killProcessTree(pid: number | undefined, signal: NodeJS.Signals = "SIGTERM"): void {
+    if (typeof pid !== "number" || pid <= 0) return;
+    try {
+        process.kill(-pid, signal);
+    } catch {
+        try { process.kill(pid, signal); } catch { /* already dead */ }
+    }
+}
+
+/** Cheap liveness probe via signal 0. */
+export function processExists(pid: number | undefined): boolean {
+    if (typeof pid !== "number" || pid <= 0) return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (err) {
+        return (err as NodeJS.ErrnoException).code === "EPERM";
+    }
+}

package/stop.ts

@@ -0,0 +1,155 @@
+/**
+ * Shared stop / orphaned-cleanup semantics for subagent runs.
+ *
+ * `stopRun` is the single stop path used by BOTH the model-facing
+ * `subagent_stop` tool and the TUI navigator close action (issues #44/#47/#68),
+ * so process-group termination and terminal-status recording can never diverge
+ * between the two surfaces.
+ *
+ * Race safety: the run's metadata and effective status are re-read from disk
+ * at call time, never taken from a caller's cached copy. A run that finished
+ * while a confirmation was pending is reported as not-running instead of
+ * being "terminated" against stale state.
+ *
+ * Orphaned cleanup (#68): when related process-group work is still alive,
+ * SIGTERM the recorded group and record durable `killed`. When no related
+ * process-group evidence remains, reread the child log and finalize from
+ * coherent terminal evidence (`completed` / `failed`) or record `lost`.
+ *
+ * Process-group-only contract (ADR 0002): related work is the captured
+ * process group (pgid, falling back to pid for old metadata). Escaped /
+ * reparented descendants outside that group are out of contract and are
+ * never scanned for.
+ */
+
+import { realProcessProbe, type ProcessProbe } from "./health.ts";
+import { parseRunForLifecycle } from "./parse.ts";
+import {
+    effectiveStatus,
+    readMeta,
+    writeMeta,
+    type RunMeta,
+} from "./registry.ts";
+import { killProcessTree } from "./spawn.ts";
+
+export type StopOutcome =
+    | { action: "stopped"; id: string }
+    | { action: "finalized"; id: string; status: "completed" | "failed" | "lost" }
+    | { action: "not-running"; id: string; status: string };
+
+export interface StopDeps {
+    /** OS process probe; defaults to the real probe. Tests inject fakes. */
+    probe?: ProcessProbe;
+    /** Clock seam for durable timestamps. */
+    now?: () => number;
+}
+
+/** Recorded process group for related-work signals (ADR 0002). */
+export function relatedProcessGroupId(meta: Pick<RunMeta, "pid" | "pgid">): number | undefined {
+    const pgid = meta.pgid ?? meta.pid;
+    return typeof pgid === "number" && pgid > 0 ? pgid : undefined;
+}
+
+/**
+ * True when stop/close may still act on this effective status.
+ * `running` is the supervised path; `orphaned` is the #68 cleanup path.
+ */
+export function isStoppableStatus(status: string): boolean {
+    return status === "running" || status === "orphaned";
+}
+
+/** SIGTERM the run's related process group. Returns whether a group target existed. */
+function terminateRelatedWork(meta: Pick<RunMeta, "pid" | "pgid">): number | undefined {
+    const pgid = relatedProcessGroupId(meta);
+    if (pgid === undefined) return undefined;
+    killProcessTree(pgid, "SIGTERM");
+    return pgid;
+}
+
+function recordKilled(meta: RunMeta, now: number): StopOutcome {
+    meta.status = "killed";
+    meta.lifecycleClassification = "killed";
+    meta.endedAt = now;
+    writeMeta(meta);
+    return { action: "stopped", id: meta.id };
+}
+
+/**
+ * No related process-group evidence remains. Reread logs, then finalize from
+ * coherent terminal stream evidence or record durable `lost`.
+ */
+function finalizeOrphanedWithoutProcess(meta: RunMeta, now: number): StopOutcome {
+    // Log authority is reread at cleanup time — never trust a cached parse.
+    const run = parseRunForLifecycle(meta.id);
+
+    if (run.sawEnd && run.unmatchedToolCalls.length === 0) {
+        meta.status = "completed";
+        meta.lifecycleClassification = "complete";
+        if (meta.exitCode === undefined) meta.exitCode = 0;
+        meta.endedAt = now;
+        writeMeta(meta);
+        return { action: "finalized", id: meta.id, status: "completed" };
+    }
+
+    if (run.sawEnd && run.unmatchedToolCalls.length > 0) {
+        meta.status = "failed";
+        meta.lifecycleClassification = "incomplete_open_tools";
+        meta.failureReason = "incomplete-stream";
+        meta.endedAt = now;
+        writeMeta(meta);
+        return { action: "finalized", id: meta.id, status: "failed" };
+    }
+
+    // No coherent terminal completion evidence and no related process remains.
+    meta.status = "lost";
+    meta.lifecycleClassification = "lost";
+    meta.lostAt = now;
+    meta.endedAt = now;
+    writeMeta(meta);
+    return { action: "finalized", id: meta.id, status: "lost" };
+}
+
+/**
+ * Cleanup path for a durable orphaned run (#68).
+ * Shares kill + killed recording with the running-run stop path when the
+ * captured process group is still alive; otherwise finalizes from logs.
+ */
+function cleanupOrphanedRun(meta: RunMeta, probe: ProcessProbe, now: number): StopOutcome {
+    const pgid = relatedProcessGroupId(meta);
+    if (pgid !== undefined && probe.groupAlive(pgid)) {
+        terminateRelatedWork(meta);
+        return recordKilled(meta, now);
+    }
+    return finalizeOrphanedWithoutProcess(meta, now);
+}
+
+/**
+ * Stop or resolve a run by id.
+ *
+ * - `running` → SIGTERM related process group, durable `killed`.
+ * - `orphaned` → terminate identifiable process-group members when alive;
+ *   otherwise reread logs and finalize completed/failed/lost.
+ * - other statuses → not-running (on-disk record untouched).
+ *
+ * Throws on an unknown id (same contract as the stop tool).
+ */
+export function stopRun(id: string, deps: StopDeps = {}): StopOutcome {
+    const meta = readMeta(id);
+    if (!meta) throw new Error(`Unknown run id: ${id}`);
+    const probe = deps.probe ?? realProcessProbe;
+    const now = typeof deps.now === "function" ? deps.now() : Date.now();
+    const status = effectiveStatus(meta);
+
+    if (status === "running") {
+        // Supervised path: same process-group kill + killed write as before.
+        // Prefer recorded pgid so running and orphaned share one target rule.
+        terminateRelatedWork(meta);
+        return recordKilled(meta, now);
+    }
+
+    if (status === "orphaned") {
+        return cleanupOrphanedRun(meta, probe, now);
+    }
+
+    return { action: "not-running", id, status };
+}