pi-better-subagents 0.1.0

package/health-surface.mjs

@@ -0,0 +1,276 @@
+/**
+ * Pure helpers that surface #66 health observations on existing list / output /
+ * widget text without inventing a parallel health model (issue #67).
+ *
+ * Healthy/quiet stays low-noise. Degraded/actionable compact facts and durable
+ * orphaned/lost statuses are the only additions.
+ */
+
+/** Statuses that are always actionable on list/output surfaces. */
+const ACTIONABLE_STATUSES = new Set(["orphaned", "lost"]);
+
+/** Age suffix from health-observation fmtAge: `10s`, `2m`, `1h5m`. */
+const ORDINARY_TOOL_AGE = /^(?:\d+s|\d+m|\d+h\d+m)$/;
+
+/**
+ * Ordinary short-running open-tool label from #66: bare tool name, or name plus
+ * a fmtAge duration. Degraded facts that merely share the tool-name prefix
+ * (e.g. `model error` while a tool named `model` is running) must be kept.
+ *
+ * @param {string} fact
+ * @param {string} toolName
+ */
+function isOrdinaryRunningToolFact(fact, toolName) {
+    if (fact === toolName) return true;
+    const prefix = `${toolName} `;
+    if (!fact.startsWith(prefix)) return false;
+    return ORDINARY_TOOL_AGE.test(fact.slice(prefix.length));
+}
+
+/**
+ * #66 emits ordinary open-tool labels (e.g. `bash 10s`) in compactFacts before
+ * long_running. Those are not degraded health for #67 surfaces — the widget
+ * already shows the active tool via its normal label. Keep long_running and
+ * every other compact fact.
+ *
+ * @param {{ compactFacts?: string[], tool?: { state?: string, active?: { toolName?: string } } }|null|undefined} obs
+ * @returns {string[]}
+ */
+export function surfaceableCompactFacts(obs) {
+    const facts = Array.isArray(obs?.compactFacts) ? obs.compactFacts : [];
+    if (!obs || obs.tool?.state !== "running") {
+        return facts.filter(Boolean);
+    }
+    const name = obs.tool?.active?.toolName;
+    if (!name) return facts.filter(Boolean);
+    // Drop only the ordinary running duration fact (`${name}` / `${name} 10s`).
+    // Prefix-sharing degraded facts (`model error`, `model retrying`, …) stay.
+    // long_running (`long ${name}…`) is retained because tool.state !== "running".
+    return facts.filter((f) => f && !isOrdinaryRunningToolFact(f, name));
+}
+
+/**
+ * True when the observation should add diagnostics beyond the compact baseline.
+ * Quiet is intentionally silent — residual silence without residual stale /
+ * phase warnings is not actionable noise for list/widget.
+ * Ordinary tool.state === "running" compact facts are not actionable (#67).
+ *
+ * @param {{ status?: string, activity?: string, compactFacts?: string[], tool?: { state?: string, active?: { toolName?: string } } }|null|undefined} obs
+ */
+export function isActionableHealth(obs) {
+    if (!obs) return false;
+    if (ACTIONABLE_STATUSES.has(obs.status)) return true;
+    if (obs.activity === "stale") return true;
+    return surfaceableCompactFacts(obs).length > 0;
+}
+
+/**
+ * Compact fact labels for degraded/actionable health, including process
+ * liveness labels for orphaned/lost when compactFacts alone are empty.
+ * Ordinary short-running tool labels are omitted (degraded-only contract).
+ *
+ * @param {{ status?: string, activity?: string, compactFacts?: string[], process?: { liveness?: string }, tool?: { state?: string, active?: { toolName?: string } } }|null|undefined} obs
+ * @returns {string[]}
+ */
+export function healthSurfaceFacts(obs) {
+    if (!obs) return [];
+    const facts = [];
+    if (obs.status === "orphaned") facts.push("orphaned");
+    else if (obs.status === "lost") facts.push("lost");
+    for (const f of surfaceableCompactFacts(obs)) {
+        if (f && !facts.includes(f)) facts.push(f);
+    }
+    // Residual stale may already be in compactFacts; ensure it appears when
+    // activity is stale and nothing more specific was listed.
+    if (obs.activity === "stale" && !facts.some((f) => /\bstale\b/i.test(f))) {
+        facts.push("stale");
+    }
+    return facts.slice(0, 3);
+}
+
+/**
+ * Format list-row health suffix. Empty string when healthy/quiet so the row
+ * stays on today's compact format.
+ *
+ * @param {{ status?: string, activity?: string, compactFacts?: string[] }|null|undefined} obs
+ */
+export function formatListHealthSuffix(obs) {
+    if (!isActionableHealth(obs)) return "";
+    const facts = healthSurfaceFacts(obs);
+    // Orphaned/lost already appear in the status bracket; prefer remaining facts.
+    const rest = facts.filter((f) => f !== obs.status);
+    if (rest.length === 0) {
+        // Still actionable via status alone — no extra suffix needed.
+        return "";
+    }
+    return ` · ${rest.join(", ")}`;
+}
+
+/**
+ * One-line health diagnostic for subagent_output / result heads.
+ * Empty when healthy/quiet running.
+ *
+ * @param {{ status?: string, activity?: string, compactFacts?: string[] }|null|undefined} obs
+ */
+export function formatHealthDiagnosticLine(obs) {
+    if (!isActionableHealth(obs)) return "";
+    const facts = healthSurfaceFacts(obs);
+    if (facts.length === 0) return "";
+    return `[health: ${facts.join(", ")}]`;
+}
+
+/**
+ * Short suffix for a passive widget run line. Empty for healthy/quiet so
+ * geometry and text stay unchanged for quiet runs.
+ *
+ * @param {{ status?: string, activity?: string, compactFacts?: string[] }|null|undefined} obs
+ */
+export function formatWidgetHealthSuffix(obs) {
+    if (!isActionableHealth(obs)) return "";
+    const facts = healthSurfaceFacts(obs)
+        // Widget already implies "running"; skip redundant process labels when
+        // a more specific compact fact exists, but keep orphaned/lost alone.
+        .filter((f) => f !== "running");
+    if (facts.length === 0) return "";
+    // Keep widget geometry mostly stable: at most two short tokens.
+    return ` · ${facts.slice(0, 2).join(", ")}`;
+}
+
+/**
+ * Append a health diagnostic line to an existing tool body when present.
+ *
+ * @param {string} body
+ * @param {string} healthLine
+ */
+export function appendHealthDiagnostic(body, healthLine) {
+    if (!healthLine) return body;
+    // Place diagnostic just under the head line when body starts with `[id ·`.
+    const nl = body.indexOf("\n");
+    if (nl === -1) return `${body}\n${healthLine}`;
+    return `${body.slice(0, nl)}\n${healthLine}${body.slice(nl)}`;
+}
+
+/**
+ * Compact health facts for TUI navigator rows (#69).
+ * Healthy/quiet stays empty. Durable status is rendered separately, so
+ * orphaned/lost labels are not repeated as facts. Cap is two facts.
+ *
+ * @param {{ status?: string, activity?: string, compactFacts?: string[], tool?: { state?: string, active?: { toolName?: string } } }|null|undefined} obs
+ * @returns {string[]}
+ */
+export function formatNavigatorHealthFacts(obs) {
+    if (!obs || !isActionableHealth(obs)) return [];
+    const facts = [];
+    for (const f of surfaceableCompactFacts(obs)) {
+        if (f && f !== obs.status && !facts.includes(f)) facts.push(f);
+    }
+    if (obs.activity === "stale" && !facts.some((f) => /\bstale\b/i.test(f))) {
+        facts.push("stale");
+    }
+    // Process-group / log diagnostics when orphaned/lost and no phase facts.
+    if (facts.length === 0 && (obs.status === "orphaned" || obs.status === "lost")) {
+        const live = obs.process?.liveness;
+        if (live && live !== obs.status) facts.push(live);
+        const logAge = obs.rawLog?.mtimeMs;
+        // raw age is computed by callers into compactFacts when needed; skip here.
+        void logAge;
+    }
+    return facts.slice(0, 2);
+}
+
+/**
+ * Semantic theme color for a durable/effective run status in the TUI.
+ * completed → success; failed/lost → error; killed/orphaned → warning;
+ * running → accent; anything else → dim.
+ *
+ * @param {string|undefined|null} status
+ * @returns {string}
+ */
+export function statusThemeColor(status) {
+    switch (String(status ?? "").toLowerCase()) {
+        case "completed":
+            return "success";
+        case "failed":
+        case "lost":
+            return "error";
+        case "killed":
+        case "orphaned":
+            return "warning";
+        case "running":
+            return "accent";
+        default:
+            return "dim";
+    }
+}
+
+/** Strip CSI / OSC ANSI sequences for visible-width measurement. */
+const ANSI_RE = new RegExp(
+    // eslint-disable-next-line no-control-regex
+    "[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:[a-zA-Z\\d]*(?:;[a-zA-Z\\d]*)*)?\\u0007)|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))",
+    "g",
+);
+
+/**
+ * Visible (cell) width of a string, ignoring ANSI styling sequences.
+ * Also strips the lightweight `<color>…</>` test theme markers used in unit stubs.
+ *
+ * @param {string} s
+ * @returns {number}
+ */
+export function visibleWidth(s) {
+    const plain = String(s ?? "")
+        .replace(ANSI_RE, "")
+        // Theme stub markers from unit tests: <accent>…</> (closing tag is bare </>).
+        .replace(/<\/?[a-zA-Z][\w-]*>/g, "")
+        .replace(/<\/>/g, "");
+    // Treat combining marks / wide chars as single cells — sufficient for our
+    // ASCII status tokens and English labels; pi-tui handles full East-Asian.
+    return plain.length;
+}
+
+/**
+ * Truncate to a maximum visible width while preserving ANSI / theme markers.
+ * Prefer the host's `truncateToWidth` when available (index.ts injects pi-tui);
+ * this fallback keeps unit tests width-safe when color escapes are present.
+ *
+ * @param {string} s
+ * @param {number} width
+ * @returns {string}
+ */
+export function truncateToVisibleWidth(s, width) {
+    const str = String(s ?? "");
+    const max = Math.max(0, Number(width) || 0);
+    if (visibleWidth(str) <= max) return str;
+
+    // Walk code units, skipping ANSI and <tag> markers for the budget.
+    let out = "";
+    let vis = 0;
+    let i = 0;
+    while (i < str.length && vis < max) {
+        // ANSI CSI/OSC
+        if (str[i] === "\u001b" || str[i] === "\u009b") {
+            const m = str.slice(i).match(ANSI_RE);
+            if (m && m.index === 0) {
+                out += m[0];
+                i += m[0].length;
+                continue;
+            }
+        }
+        // Lightweight theme markers from test stubs: <accent>…</>
+        if (str[i] === "<") {
+            const close = str.indexOf(">", i);
+            if (close !== -1) {
+                const tag = str.slice(i, close + 1);
+                if (/^<\/?[a-zA-Z][\w-]*>$/.test(tag) || tag === "</>") {
+                    out += tag;
+                    i = close + 1;
+                    continue;
+                }
+            }
+        }
+        out += str[i];
+        vis += 1;
+        i += 1;
+    }
+    return out;
+}

package/health.ts

@@ -0,0 +1,303 @@
+/**
+ * Subagent health reconciliation (issue #63) — durable supervision statuses.
+ *
+ * Process-group-only contract (ADR 0002): `reconcileRun` takes run metadata
+ * plus a `ProcessProbe` and decides the next durable status. A supervised run
+ * stays `running`; a run whose recorded child is gone but whose captured
+ * process group still has live members becomes durable non-terminal
+ * `orphaned`; a run with no credible process-group evidence becomes durable
+ * terminal `lost`. Escaped/reparented descendants are out of contract — this
+ * slice never scans the process tree for related work. Nothing here kills
+ * processes — reconciliation only writes truth.
+ *
+ * `realProcessProbe` is the OS-backed probe used in production; unit tests
+ * inject fakes so supervised/orphaned/lost/recycled cases are deterministic.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { processExists } from "./spawn.ts";
+import { ownedByThisParent, type RunMeta, type RunStatus } from "./registry.ts";
+
+/** Consecutive pid-gone ticks required before OLD metadata may be written `lost`. */
+export const OLD_METADATA_LOST_CONFIRM_TICKS = 2;
+
+/**
+ * Process evidence probe. Every method is best-effort and never throws.
+ *
+ * #63 deliberately exposes only process-group evidence. There is no
+ * `descendants` method: escaped/reparented children are not related work for
+ * this slice (see docs/adr/0002-process-group-only-subagent-health.md).
+ */
+export interface ProcessProbe {
+    /** The pid currently exists (signal 0; EPERM counts as existing). */
+    pidExists(pid: number): boolean;
+    /**
+     * Opaque process-start identity token for a live pid, or undefined when
+     * unavailable. Equality is the only supported operation: a DIFFERENT token
+     * proves the pid was recycled; an unavailable token proves nothing.
+     */
+    startToken(pid: number): string | undefined;
+    /** Process group id of a live pid, or undefined when unavailable. */
+    groupId(pid: number): number | undefined;
+    /** Any member of process group `pgid` is alive (EPERM counts as alive). */
+    groupAlive(pgid: number): boolean;
+}
+
+/** Process identity recorded on a new run's metadata (all best-effort). */
+export interface ProcessIdentity {
+    pgid?: number;
+    pidStartTime?: string;
+}
+
+/** Capture process identity for a freshly spawned child. Never throws. */
+export function captureProcessIdentity(pid: number, probe: ProcessProbe = realProcessProbe): ProcessIdentity {
+    const identity: ProcessIdentity = {};
+    try {
+        const pgid = probe.groupId(pid);
+        if (typeof pgid === "number" && pgid > 0) identity.pgid = pgid;
+    } catch { /* unavailable */ }
+    try {
+        const token = probe.startToken(pid);
+        if (typeof token === "string" && token !== "") identity.pidStartTime = token;
+    } catch { /* unavailable */ }
+    return identity;
+}
+
+/** The subset of run metadata reconciliation reads and writes. */
+export type ReconcileInput = Pick<
+    RunMeta,
+    "status" | "pid" | "pgid" | "pidStartTime" | "probeMisses"
+>;
+
+export interface ReconcileResult {
+    /** Next durable status (unchanged unless `transition`). */
+    status: RunStatus;
+    /** Meta must be rewritten (status and/or patch fields changed). */
+    changed: boolean;
+    /** Durable status transitioned (notify-worthy). */
+    transition: boolean;
+    /** Fields to merge into the persisted meta. */
+    patch: Partial<Pick<RunMeta, "probeMisses" | "orphanedAt" | "lostAt" | "endedAt">>;
+    /** Machine-readable reason, for diagnostics and tests. */
+    reason:
+        | "terminal-untouched"
+        | "supervised"
+        | "orphaned-group-alive"
+        | "orphaned-kept"
+        | "lost-no-evidence"
+        | "lost-confirmed-old-metadata"
+        | "lost-suspected-old-metadata";
+}
+
+/**
+ * Supervised ⇔ the recorded pid exists AND its start-time identity still
+ * matches when both sides of the comparison are available. A missing recorded
+ * token (old metadata) or an unavailable probe token can disprove nothing.
+ */
+function isSupervised(meta: ReconcileInput, probe: ProcessProbe): boolean {
+    if (!probe.pidExists(meta.pid)) return false;
+    if (meta.pidStartTime === undefined) return true;
+    const token = probe.startToken(meta.pid);
+    if (token === undefined) return true;
+    return token === meta.pidStartTime;
+}
+
+/**
+ * Related work for #63 is live process-group evidence only.
+ *
+ * Uses the recorded pgid, falling back to the pid itself — detached children
+ * are expected to be process-group leaders (pgid == pid), so the fallback is
+ * valid for old metadata too. That inference is conservative: it may delay
+ * `lost`, but it never manufactures completion or failure. No process-tree /
+ * descendant scan is consulted.
+ */
+function hasProcessGroupEvidence(meta: ReconcileInput, probe: ProcessProbe): boolean {
+    const pgid = meta.pgid ?? meta.pid;
+    return typeof pgid === "number" && pgid > 0 && probe.groupAlive(pgid);
+}
+
+/**
+ * Reconcile one run's durable status against process reality. Pure: the
+ * caller persists. Only `running` and `orphaned` are reconciled — `lost`,
+ * `completed`, `failed`, and `killed` are durable terminal and never revert.
+ */
+export function reconcileRun(meta: ReconcileInput, probe: ProcessProbe, now: number): ReconcileResult {
+    const stay = (reason: ReconcileResult["reason"]): ReconcileResult =>
+        ({ status: meta.status, changed: false, transition: false, patch: {}, reason });
+
+    if (meta.status !== "running" && meta.status !== "orphaned") {
+        return stay("terminal-untouched");
+    }
+
+    // Orphaned is durable non-terminal: it never auto-reverts to running. It
+    // only advances to lost when the last process-group evidence disappears.
+    // A live, identity-matched child is itself conclusive related evidence —
+    // an earlier orphaned write based on a transient probe failure must never
+    // degrade a supervised-alive child to lost.
+    if (meta.status === "orphaned") {
+        if (isSupervised(meta, probe) || hasProcessGroupEvidence(meta, probe)) {
+            return stay("orphaned-kept");
+        }
+        return {
+            status: "lost", changed: true, transition: true,
+            patch: { lostAt: now, endedAt: now, probeMisses: 0 },
+            reason: "lost-no-evidence",
+        };
+    }
+
+    if (isSupervised(meta, probe)) {
+        if ((meta.probeMisses ?? 0) > 0) {
+            return {
+                status: "running", changed: true, transition: false,
+                patch: { probeMisses: 0 }, reason: "supervised",
+            };
+        }
+        return stay("supervised");
+    }
+
+    if (hasProcessGroupEvidence(meta, probe)) {
+        return {
+            status: "orphaned", changed: true, transition: true,
+            patch: { orphanedAt: now, probeMisses: 0 },
+            reason: "orphaned-group-alive",
+        };
+    }
+
+    // No process-group evidence. Metadata WITH recorded process identity is
+    // conclusive on its own; OLD metadata (no pgid, no start token) must
+    // confirm the loss across health ticks before the terminal write.
+    // Evidence quality — not file age — drives that confirmation.
+    const hasIdentity = meta.pgid !== undefined || meta.pidStartTime !== undefined;
+    if (hasIdentity) {
+        return {
+            status: "lost", changed: true, transition: true,
+            patch: { lostAt: now, endedAt: now, probeMisses: 0 },
+            reason: "lost-no-evidence",
+        };
+    }
+    const misses = (meta.probeMisses ?? 0) + 1;
+    if (misses >= OLD_METADATA_LOST_CONFIRM_TICKS) {
+        return {
+            status: "lost", changed: true, transition: true,
+            patch: { lostAt: now, endedAt: now, probeMisses: misses },
+            reason: "lost-confirmed-old-metadata",
+        };
+    }
+    return {
+        status: "running", changed: true, transition: false,
+        patch: { probeMisses: misses },
+        reason: "lost-suspected-old-metadata",
+    };
+}
+
+/**
+ * True while any current-parent run still needs the health ticker:
+ * - `running` / `orphaned` for process-group reconciliation (#63), or
+ * - `lost` without a successful health-callback handoff marker, so durable
+ *   coordinator recovery can still fire after reload (#65).
+ * The scheduler stops when false.
+ */
+export function needsMonitoring(
+    metas: ReadonlyArray<Pick<RunMeta, "spawnPid" | "status" | "lostCallbackSentAt" | "lostCallbackSuppressedAt">>,
+    parentPid: number = process.pid,
+): boolean {
+    return metas.some(
+        (m) => ownedByThisParent(m, parentPid) && (
+            m.status === "running"
+            || m.status === "orphaned"
+            || (m.status === "lost" && m.lostCallbackSentAt === undefined && m.lostCallbackSuppressedAt === undefined)
+        ),
+    );
+}
+
+// ---- real OS-backed probe -------------------------------------------------
+
+/** Linux: start-time identity from /proc/<pid>/stat field 22 (jiffies since boot). */
+function linuxStartToken(pid: number): string | undefined {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+        // comm (field 2) may contain spaces/parens; fields resume after ") ".
+        const close = stat.lastIndexOf(") ");
+        if (close < 0) return undefined;
+        const rest = stat.slice(close + 2).split(" ");
+        // rest[0] is field 3 (state); field 22 (starttime) is index 19.
+        const starttime = rest[19];
+        return starttime && /^\d+$/.test(starttime) ? starttime : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+/** Portable fallback: `ps -o lstart=` (locale-pinned, whitespace-normalized). */
+function psStartToken(pid: number): string | undefined {
+    try {
+        const out = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+            encoding: "utf-8",
+            timeout: 3000,
+            env: { ...process.env, LC_ALL: "C" },
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim().replace(/\s+/g, " ");
+        return out === "" ? undefined : out;
+    } catch {
+        return undefined;
+    }
+}
+
+/** Run `ps <args>` and parse a single integer from stdout. undefined on failure. */
+function psNumber(args: string[]): number | undefined {
+    try {
+        const out = execFileSync("ps", args, {
+            encoding: "utf-8",
+            timeout: 3000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        const n = Number(out);
+        return Number.isInteger(n) && n > 0 ? n : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+// Re-export observation seam so health consumers can import from one module.
+export {
+    DEFAULT_HEALTH_THRESHOLDS,
+    extractChildEventFacts,
+    extractChildEventFactsFromLog,
+    loadHealthThresholdsFromConfig,
+    observeRunHealth,
+    resolveHealthThresholds,
+} from "./health-observation.ts";
+export type {
+    ActivityHealth,
+    ChildEventFacts,
+    HealthObservation,
+    HealthThresholds,
+    ObserveRunHealthInput,
+    RawLogDiagnostic,
+} from "./health-observation.ts";
+
+export const realProcessProbe: ProcessProbe = {
+    pidExists: (pid) => processExists(pid),
+    startToken: (pid) => linuxStartToken(pid) ?? psStartToken(pid),
+    groupId: (pid) => {
+        try {
+            if (typeof process.getpgid === "function") return process.getpgid(pid);
+        } catch {
+            return undefined;
+        }
+        // process.getpgid is missing on some builds (e.g. macOS); fall back to ps.
+        return psNumber(["-o", "pgid=", "-p", String(pid)]);
+    },
+    groupAlive: (pgid) => {
+        if (typeof pgid !== "number" || pgid <= 0) return false;
+        try {
+            process.kill(-pgid, 0);
+            return true;
+        } catch (err) {
+            // EPERM: the group exists but is not ours to signal — still alive,
+            // and "alive" is the safe direction (it can only delay `lost`).
+            return (err as NodeJS.ErrnoException).code === "EPERM";
+        }
+    },
+};