@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/dist/runs/shared/pi-args.js

@@ -0,0 +1,310 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { encodeNestedPathEnv, parseNestedPathEnv } from "./nested-path.js";
+import { resolveMcpDirectToolNames } from "./mcp-direct-tool-allowlist.js";
+import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV } from "./structured-output.js";
+import { splitKnownThinkingSuffix } from "../../shared/model-info.js";
+import { prepareChildExecutionCwd } from "./child-execution-cwd.js";
+import { loadConfig } from "../../extension/config.js";
+// Managed macOS environments can SIGKILL Node when one argv entry reaches ~930 UTF-8 bytes.
+// Measure the full entry (including the `Task: ` prefix), not just the task body.
+const TASK_ARG_LIMIT_BYTES = 900;
+// Resolve sibling extensions in both layouts: TypeScript sources (tests, jiti) and compiled dist output.
+const MODULE_EXTENSION = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
+const SESSION_CWD_PRELOAD_URL = new URL(`session-cwd-preload${MODULE_EXTENSION}`, import.meta.url).href;
+const PROMPT_RUNTIME_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), `subagent-prompt-runtime${MODULE_EXTENSION}`);
+const FANOUT_CHILD_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "extension", `fanout-child${MODULE_EXTENSION}`);
+export const SUBAGENT_CHILD_ENV = "PI_SUBAGENT_CHILD";
+export const SUBAGENT_ORCHESTRATOR_TARGET_ENV = "PI_SUBAGENT_ORCHESTRATOR_TARGET";
+export const SUBAGENT_RUN_ID_ENV = "PI_SUBAGENT_RUN_ID";
+export const SUBAGENT_CHILD_AGENT_ENV = "PI_SUBAGENT_CHILD_AGENT";
+export const SUBAGENT_CHILD_INDEX_ENV = "PI_SUBAGENT_CHILD_INDEX";
+export const SUBAGENT_FANOUT_CHILD_ENV = "PI_SUBAGENT_FANOUT_CHILD";
+export const SUBAGENT_EAGER_TOOL_ENV = "PI_SUBAGENT_EAGER_TOOL";
+export const SUBAGENT_PARENT_EVENT_SINK_ENV = "PI_SUBAGENT_PARENT_EVENT_SINK";
+export const SUBAGENT_PARENT_CONTROL_INBOX_ENV = "PI_SUBAGENT_PARENT_CONTROL_INBOX";
+export const SUBAGENT_PARENT_ROOT_RUN_ID_ENV = "PI_SUBAGENT_PARENT_ROOT_RUN_ID";
+export const SUBAGENT_PARENT_RUN_ID_ENV = "PI_SUBAGENT_PARENT_RUN_ID";
+export const SUBAGENT_PARENT_CHILD_INDEX_ENV = "PI_SUBAGENT_PARENT_CHILD_INDEX";
+export const SUBAGENT_PARENT_DEPTH_ENV = "PI_SUBAGENT_PARENT_DEPTH";
+export const SUBAGENT_PARENT_PATH_ENV = "PI_SUBAGENT_PARENT_PATH";
+export const SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV = "PI_SUBAGENT_PARENT_CAPABILITY_TOKEN";
+export const SUBAGENT_INHERITED_EXTENSIONS_JSON_ENV = "PI_SUBAGENT_INHERITED_EXTENSIONS_JSON";
+export function applyThinkingSuffix(model, thinking) {
+    if (!model || !thinking)
+        return model;
+    if (splitKnownThinkingSuffix(model).thinkingSuffix)
+        return model;
+    return `${model}:${thinking}`;
+}
+export function normalizeChildProjectTrustPolicy(input) {
+    if (input === "approve" || input === "no-approve" || input === "inherit")
+        return input;
+    if (typeof input === "object" && input !== null && "childRuns" in input) {
+        return normalizeChildProjectTrustPolicy(input.childRuns);
+    }
+    return input === undefined ? "inherit" : "no-approve";
+}
+export function resolveConfiguredChildProjectTrustPolicy(input, argv = process.argv) {
+    const inherited = findInheritedProjectTrustFlag(argv);
+    const explicitInherit = input === "inherit" || (typeof input === "object" && input !== null && input.childRuns === "inherit");
+    if (explicitInherit)
+        return inherited ?? "inherit";
+    if (inherited === "no-approve")
+        return "no-approve";
+    if (input === undefined || (typeof input === "object" && input !== null && !("childRuns" in input)))
+        return "approve";
+    const normalized = normalizeChildProjectTrustPolicy(input);
+    return normalized === "inherit" ? "approve" : normalized;
+}
+function findInheritedProjectTrustFlag(argv) {
+    let inherited;
+    for (const arg of argv) {
+        if (arg === "--approve" || arg === "-a")
+            inherited = "approve";
+        if (arg === "--no-approve" || arg === "-na")
+            inherited = "no-approve";
+    }
+    return inherited;
+}
+export function resolveChildProjectTrustArgs(policy = "inherit", argv = process.argv) {
+    const inherited = findInheritedProjectTrustFlag(argv);
+    if (policy === "approve")
+        return inherited === "no-approve" ? ["--no-approve"] : ["--approve"];
+    if (policy === "no-approve")
+        return ["--no-approve"];
+    return inherited === "approve" ? ["--approve"] : inherited === "no-approve" ? ["--no-approve"] : [];
+}
+function inheritedRuntimeExtensionPaths(env = process.env) {
+    const raw = env[SUBAGENT_INHERITED_EXTENSIONS_JSON_ENV]?.trim();
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+// Read only through the header, not the potentially large transcript. Decode after
+// joining chunks so a UTF-8 character split across reads is preserved.
+function readSessionHeaderLine(file) {
+    let fd;
+    try {
+        fd = fs.openSync(file, "r");
+    }
+    catch (error) {
+        if (error.code === "ENOENT" && !fs.lstatSync(file, { throwIfNoEntry: false }))
+            return undefined;
+        throw error;
+    }
+    try {
+        const chunks = [];
+        const buffer = Buffer.alloc(4096);
+        while (true) {
+            const length = fs.readSync(fd, buffer, 0, buffer.length, null);
+            if (!length)
+                break;
+            const chunk = buffer.subarray(0, length);
+            const newline = chunk.indexOf(10);
+            chunks.push(Buffer.from(newline < 0 ? chunk : chunk.subarray(0, newline)));
+            if (newline >= 0)
+                break;
+        }
+        return Buffer.concat(chunks).toString("utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function buildPiArgs(input) {
+    const args = [...input.baseArgs];
+    const env = {};
+    args.push(...resolveChildProjectTrustArgs(input.projectTrust));
+    if (input.sessionFile) {
+        prepareChildExecutionCwd(input.sessionFile, input.cwd);
+        fs.mkdirSync(path.dirname(input.sessionFile), { recursive: true });
+        args.push("--session", input.sessionFile);
+        if (input.cwd) {
+            let needsOverride = true;
+            try {
+                const line = readSessionHeaderLine(input.sessionFile);
+                if (line === undefined) {
+                    // Preassigned new sessions (including acceptance) inherit the actual spawn cwd.
+                    needsOverride = false;
+                }
+                else {
+                    const header = JSON.parse(line);
+                    if (header && typeof header === "object" && "type" in header && header.type === "session"
+                        && "cwd" in header && typeof header.cwd === "string" && path.isAbsolute(header.cwd)) {
+                        needsOverride = fs.realpathSync.native(header.cwd) !== fs.realpathSync.native(input.cwd);
+                    }
+                }
+            }
+            catch { /* Unknown headers or unavailable directories still need the native override. */ }
+            // Pi's SDK supports cwdOverride; its CLI has no --session-cwd flag.
+            // Keep normal resumes untouched and supply only a needed override before startup.
+            if (needsOverride) {
+                env.PI_SUBAGENT_SESSION_CWD = JSON.stringify({
+                    sessionFile: path.resolve(input.cwd, input.sessionFile), cwd: input.cwd, nodeOptions: process.env.NODE_OPTIONS,
+                });
+                env.NODE_OPTIONS = `${process.env.NODE_OPTIONS ?? ""} --import=${SESSION_CWD_PRELOAD_URL}`.trim();
+            }
+        }
+    }
+    else {
+        if (!input.sessionEnabled) {
+            args.push("--no-session");
+        }
+        if (input.sessionDir) {
+            fs.mkdirSync(input.sessionDir, { recursive: true });
+            args.push("--session-dir", input.sessionDir);
+        }
+    }
+    const modelArg = applyThinkingSuffix(input.model, input.thinking);
+    if (modelArg) {
+        args.push("--model", modelArg);
+    }
+    const declaredBuiltinTools = input.tools?.filter((tool) => !(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) ?? [];
+    const fanoutAuthorized = input.allowSubagents === true || declaredBuiltinTools.includes("subagent");
+    const compactChildTools = fanoutAuthorized && loadConfig().compactChildTools !== false;
+    // Preserve an explicit advanced-tool policy, but never inherit it into another profile.
+    env[SUBAGENT_EAGER_TOOL_ENV] = declaredBuiltinTools.includes("subagent") ? "1" : undefined;
+    const toolExtensionPaths = [];
+    if (input.tools?.length) {
+        const builtinTools = [...declaredBuiltinTools];
+        if (fanoutAuthorized && declaredBuiltinTools.length > 0) {
+            for (const tool of compactChildTools ? ["subagent", "delegate", "agent_runs", "load_subagent"] : ["subagent"]) {
+                if (!builtinTools.includes(tool))
+                    builtinTools.push(tool);
+            }
+        }
+        if (input.structuredOutput && builtinTools.length > 0 && !builtinTools.includes("structured_output"))
+            builtinTools.push("structured_output");
+        for (const tool of input.tools) {
+            if (!declaredBuiltinTools.includes(tool) && (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) {
+                toolExtensionPaths.push(tool);
+            }
+        }
+        if (builtinTools.length > 0) {
+            if (input.mcpDirectTools?.length) {
+                builtinTools.push(...resolveMcpDirectToolNames(input.mcpDirectTools, input.cwd));
+            }
+            args.push("--tools", builtinTools.join(","));
+        }
+    }
+    const runtimeExtensions = fanoutAuthorized
+        ? [PROMPT_RUNTIME_EXTENSION_PATH, FANOUT_CHILD_EXTENSION_PATH, ...inheritedRuntimeExtensionPaths()]
+        : [PROMPT_RUNTIME_EXTENSION_PATH, ...inheritedRuntimeExtensionPaths()];
+    if (input.extensions !== undefined) {
+        args.push("--no-extensions");
+        for (const extPath of [...new Set([...runtimeExtensions, ...toolExtensionPaths, ...input.extensions])]) {
+            args.push("--extension", extPath);
+        }
+    }
+    else {
+        for (const extPath of [...new Set([...runtimeExtensions, ...toolExtensionPaths])]) {
+            args.push("--extension", extPath);
+        }
+    }
+    if (!input.inheritSkills) {
+        args.push("--no-skills");
+    }
+    if (!input.inheritProjectContext) {
+        args.push("--no-context-files");
+    }
+    let tempDir;
+    if (input.systemPrompt !== undefined && input.systemPrompt !== null) {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+        const promptPath = path.join(tempDir, "system.md");
+        fs.writeFileSync(promptPath, input.systemPrompt, { mode: 0o600 });
+        args.push(input.systemPromptMode === "replace" ? "--system-prompt" : "--append-system-prompt", promptPath);
+    }
+    const taskArg = `Task: ${input.task}`;
+    if (Buffer.byteLength(taskArg) > TASK_ARG_LIMIT_BYTES) {
+        if (!tempDir) {
+            tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+        }
+        const taskFilePath = path.join(tempDir, "task.md");
+        fs.writeFileSync(taskFilePath, taskArg, { mode: 0o600 });
+        args.push(`@${taskFilePath}`);
+    }
+    else {
+        args.push(taskArg);
+    }
+    env[SUBAGENT_CHILD_ENV] = "1";
+    env.PI_SUBAGENT_ROOT_SESSION_ID = input.rootSessionId ?? (process.env[SUBAGENT_CHILD_ENV] === "1" ? process.env.PI_SUBAGENT_ROOT_SESSION_ID : undefined);
+    env[SUBAGENT_FANOUT_CHILD_ENV] = fanoutAuthorized ? "1" : "0";
+    const inheritedNestedRoute = Boolean(process.env[SUBAGENT_PARENT_EVENT_SINK_ENV] && process.env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] && process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV]);
+    const parentRunId = input.parentRunId ?? input.runId ?? (inheritedNestedRoute ? process.env[SUBAGENT_RUN_ID_ENV] : undefined) ?? process.env[SUBAGENT_PARENT_RUN_ID_ENV] ?? "";
+    const parentChildIndex = input.parentChildIndex !== undefined
+        ? String(input.parentChildIndex)
+        : input.childIndex !== undefined
+            ? String(input.childIndex)
+            : process.env[SUBAGENT_PARENT_CHILD_INDEX_ENV] ?? "";
+    const inheritedDepth = Number(process.env[SUBAGENT_PARENT_DEPTH_ENV]);
+    const parentDepth = input.parentDepth ?? (inheritedNestedRoute && Number.isFinite(inheritedDepth) ? inheritedDepth + 1 : 1);
+    const parentPath = input.parentPath ?? [
+        ...parseNestedPathEnv(process.env[SUBAGENT_PARENT_PATH_ENV]),
+        ...(parentRunId ? [{
+                runId: parentRunId,
+                ...(parentChildIndex && /^\d+$/.test(parentChildIndex) ? { stepIndex: Number(parentChildIndex) } : {}),
+                ...(input.childAgentName ? { agent: input.childAgentName } : {}),
+            }] : []),
+    ];
+    env[SUBAGENT_PARENT_EVENT_SINK_ENV] = fanoutAuthorized
+        ? input.parentEventSink ?? process.env[SUBAGENT_PARENT_EVENT_SINK_ENV] ?? ""
+        : "";
+    env[SUBAGENT_PARENT_CONTROL_INBOX_ENV] = fanoutAuthorized
+        ? input.parentControlInbox ?? process.env[SUBAGENT_PARENT_CONTROL_INBOX_ENV] ?? ""
+        : "";
+    env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] = fanoutAuthorized
+        ? input.parentRootRunId ?? process.env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] ?? input.runId ?? ""
+        : "";
+    env[SUBAGENT_PARENT_RUN_ID_ENV] = fanoutAuthorized ? parentRunId : "";
+    env[SUBAGENT_PARENT_CHILD_INDEX_ENV] = fanoutAuthorized ? parentChildIndex : "";
+    env[SUBAGENT_PARENT_DEPTH_ENV] = fanoutAuthorized ? String(parentDepth) : "";
+    env[SUBAGENT_PARENT_PATH_ENV] = fanoutAuthorized ? encodeNestedPathEnv(parentPath) : "";
+    env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] = fanoutAuthorized
+        ? input.parentCapabilityToken ?? process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] ?? ""
+        : "";
+    env.PI_SUBAGENT_INHERIT_PROJECT_CONTEXT = input.inheritProjectContext ? "1" : "0";
+    env.PI_SUBAGENT_INHERIT_SKILLS = input.inheritSkills ? "1" : "0";
+    if (input.intercomSessionName) {
+        env.PI_SUBAGENT_INTERCOM_SESSION_NAME = input.intercomSessionName;
+    }
+    if (input.orchestratorIntercomTarget) {
+        env[SUBAGENT_ORCHESTRATOR_TARGET_ENV] = input.orchestratorIntercomTarget;
+    }
+    if (input.runId) {
+        env[SUBAGENT_RUN_ID_ENV] = input.runId;
+    }
+    if (input.childAgentName) {
+        env[SUBAGENT_CHILD_AGENT_ENV] = input.childAgentName;
+    }
+    if (input.childIndex !== undefined) {
+        env[SUBAGENT_CHILD_INDEX_ENV] = String(input.childIndex);
+    }
+    if (input.mcpDirectTools?.length) {
+        env.MCP_DIRECT_TOOLS = input.mcpDirectTools.join(",");
+    }
+    // A nested helper must never submit into its parent's capture.
+    env[STRUCTURED_OUTPUT_CAPTURE_ENV] = input.structuredOutput?.outputPath ?? "";
+    env[STRUCTURED_OUTPUT_SCHEMA_ENV] = input.structuredOutput?.schemaPath ?? "";
+    return { args, env, tempDir };
+}
+export function cleanupTempDir(tempDir) {
+    if (!tempDir)
+        return;
+    try {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+    catch {
+        // Temp cleanup is best effort.
+    }
+}

package/dist/runs/shared/pi-spawn.js

@@ -0,0 +1,52 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+export const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
+export function findPiPackageRootFromEntry(entryPoint) {
+    let dir = path.dirname(entryPoint);
+    while (dir !== path.dirname(dir)) {
+        const packageJsonPath = path.join(dir, "package.json");
+        if (fs.existsSync(packageJsonPath)) {
+            const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+            if (pkg.name === PI_CODING_AGENT_PACKAGE)
+                return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    return undefined;
+}
+export function resolveInstalledPiPackageRoot() {
+    try {
+        return findPiPackageRootFromEntry(fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PACKAGE)));
+    }
+    catch {
+        for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+            try {
+                const root = findPiPackageRootFromEntry(fs.realpathSync(path.join(dir, "pi")));
+                if (root)
+                    return root;
+            }
+            catch { /* PATH entries can disappear or be wrappers rather than Pi. */ }
+        }
+        return undefined;
+    }
+}
+export function resolvePiPackageRoot() {
+    try {
+        const entry = process.argv[1];
+        return entry ? findPiPackageRootFromEntry(fs.realpathSync(entry)) : undefined;
+    }
+    catch {
+        // process.argv[1] probing is best-effort; callers can fall back to PATH/package resolution.
+        return undefined;
+    }
+}
+export function requirePiPackageRoot() {
+    const root = process.env.PI_PACKAGE_DIR || resolvePiPackageRoot() || resolveInstalledPiPackageRoot();
+    if (!root)
+        throw new Error("Could not locate Pi runtime APIs; Pi must be installed and available on PATH.");
+    return root;
+}
+export function getPiSpawnCommand(args) {
+    return { command: "pi", args };
+}

package/dist/runs/shared/run-history-queries.js

@@ -0,0 +1,45 @@
+import { runHistoryIndex } from "./history-index.js";
+import { ownedRunView, resolveOwnedRun } from "./run-records.js";
+/** Browse observations never confer ownership or replace canonical control/receipt checks. */
+export async function ownedHistoryQuery(state, params, signal) {
+    const requested = params.id ?? params.runId;
+    const run = requested ? resolveOwnedRun(state, requested) : undefined;
+    if (requested && !run)
+        throw new Error("Run not found in this owning session.");
+    const index = await runHistoryIndex(state, true);
+    if (params.action === "history") {
+        if (!run)
+            throw new Error("History requires an owned run ID.");
+        const view = ownedRunView(run, state, { includeContinuations: false, readConfiguration: false, reconcile: false });
+        const child = params.index === undefined && view.children.length === 1 ? view.children[0] : view.children.find((child) => child.index === params.index);
+        if (!child)
+            throw new Error("Choose index for a run with multiple children.");
+        const input = { runId: run.runId, index: child.index, limit: params.limit, before: params.before, cursor: params.cursor, signal,
+            ...(child.state !== "live" ? { terminalEntryId: child.result?.terminalEntryId, endedAt: child.result?.terminalEntryId ? undefined : view.updatedAt } : {}) };
+        const page = await index.historyPage(input);
+        const earlier = page.previousCursor ? { action: "history", id: run.runId, index: child.index, limit: params.limit ?? 100, cursor: page.previousCursor } : undefined;
+        return { content: [{ type: "text", text: [
+                        `History: ${run.runId}, child ${child.index} (${child.agent}); ${page.entries.length} of ${page.count} indexed native entries.`,
+                        `Browse index: ${page.freshness.state}. These are bounded previews, not completion or delivery receipts.`,
+                        ...(page.unavailable ? [page.unavailable] : []),
+                        ...page.entries.map((entry) => `- ${entry.id} · position ${entry.sequence}\n${JSON.stringify(entry.entry)}`),
+                        ...(earlier ? [`Earlier: agent_runs(${JSON.stringify(earlier)})`] : []),
+                        ...(child.sessionFile ? [`Native source: ${child.sessionFile}. Open a selected record in Agents for validated full details.`] : []),
+                    ].join("\n") }], details: { mode: "management", results: [], runId: run.runId, history: page } };
+    }
+    if (params.action !== "search" || !params.query)
+        throw new Error("Search requires query.");
+    if (params.sort && !["relevance", "newest"].includes(params.sort))
+        throw new Error("Search sort must be relevance or newest.");
+    const input = { query: params.query, runId: run?.runId, index: params.index, limit: params.limit, cursor: params.cursor,
+        sort: params.sort, agent: params.agent, signal };
+    const page = await index.search(input);
+    const next = page.nextCursor ? { action: "search", query: params.query, ...(run ? { id: run.runId } : {}), ...(params.index !== undefined ? { index: params.index } : {}),
+        ...(params.agent ? { agent: params.agent } : {}), ...(params.sort ? { sort: params.sort } : {}), limit: params.limit ?? 20, cursor: page.nextCursor } : undefined;
+    return { content: [{ type: "text", text: [
+                    `Saved-text search: ${page.matches.length} matches in this owning session; index ${page.freshness.state}.`,
+                    "Indexed excerpts may be stale. They do not establish completion, ownership, or delivery; full selected records are validated separately.",
+                    ...page.matches.map((match) => `- ${match.runId}:${match.index} (${match.agent}) · entry ${match.entryId}\n${match.preview}\n${match.sessionFile}:${match.ref.start}`),
+                    ...(next ? [`Next: agent_runs(${JSON.stringify(next)})`] : []),
+                ].join("\n") }], details: { mode: "management", results: [], historySearch: page } };
+}

package/dist/runs/shared/run-history.js

@@ -0,0 +1,110 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { historyDirectory, historyTransaction, openHistoryDatabase } from "../../history/database.js";
+import { getAgentDir } from "../../shared/utils.js";
+const MAX_AGENT_SAMPLES = 1000;
+const MAX_LEGACY_BYTES = 1024 * 1024;
+const TIMING_DATABASE = "run-timing.sqlite";
+function validEntry(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const entry = value;
+    return typeof entry.agent === "string" && entry.agent.length > 0 && entry.agent.length <= 256
+        && typeof entry.task === "string" && Number.isSafeInteger(entry.ts) && entry.ts >= 0
+        && (entry.status === "ok" || entry.status === "error") && Number.isFinite(entry.duration) && entry.duration >= 0
+        && (entry.exit === undefined || Number.isSafeInteger(entry.exit));
+}
+/** Legacy samples are read-only, complete LF records from a bounded tail. */
+function legacySamples(agentDir, agent) {
+    let fd;
+    try {
+        fd = fs.openSync(path.join(agentDir, "run-history.jsonl"), "r");
+        const size = fs.fstatSync(fd).size, start = Math.max(0, size - MAX_LEGACY_BYTES);
+        const bytes = Buffer.alloc(size - start);
+        let count = 0;
+        while (count < bytes.length) {
+            const read = fs.readSync(fd, bytes, count, bytes.length - count, start + count);
+            if (!read)
+                break;
+            count += read;
+        }
+        const complete = bytes.subarray(0, count), first = start ? complete.indexOf(10) + 1 : 0, last = complete.lastIndexOf(10);
+        if (last < first || start && !first)
+            return [];
+        const samples = [], retained = new Map();
+        for (const line of complete.subarray(first, last).toString("utf8").split("\n").reverse()) {
+            try {
+                const entry = JSON.parse(line);
+                if (!validEntry(entry) || agent !== undefined && entry.agent !== agent || (retained.get(entry.agent) ?? 0) >= MAX_AGENT_SAMPLES)
+                    continue;
+                samples.push({ ...entry, task: entry.task.slice(0, 200) });
+                retained.set(entry.agent, (retained.get(entry.agent) ?? 0) + 1);
+                if (agent !== undefined && samples.length === MAX_AGENT_SAMPLES)
+                    break;
+            }
+            catch { /* Incomplete or invalid timing samples are not evidence. */ }
+        }
+        return samples;
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+export function recordRun(agent, task, exitCode, durationMs) {
+    const entry = { agent, task: task.slice(0, 200), ts: Math.floor(Date.now() / 1000), status: exitCode === 0 ? "ok" : "error", duration: durationMs, ...(exitCode !== 0 ? { exit: exitCode } : {}) };
+    if (!validEntry(entry))
+        return;
+    let db;
+    try {
+        const agentDir = getAgentDir();
+        fs.mkdirSync(agentDir, { recursive: true });
+        db = openHistoryDatabase(path.join(historyDirectory(agentDir), TIMING_DATABASE));
+        const connection = db;
+        const imported = connection.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='timing_meta'").get()
+            && connection.prepare("SELECT key FROM timing_meta WHERE key='legacy-imported'").get();
+        // Filesystem reads and JSON parsing must not consume another writer's admission budget.
+        const legacy = imported ? [] : legacySamples(agentDir).reverse();
+        // Allow brief native writer overlap; three attempts still bound best-effort admission.
+        connection.exec("PRAGMA busy_timeout=1000");
+        historyTransaction(connection, () => {
+            connection.exec(`CREATE TABLE IF NOT EXISTS timing_meta(key TEXT PRIMARY KEY);
+				CREATE TABLE IF NOT EXISTS samples(sequence INTEGER PRIMARY KEY,agent TEXT NOT NULL,task TEXT NOT NULL,ts INTEGER NOT NULL,status TEXT NOT NULL,duration REAL NOT NULL,exit INTEGER);
+				CREATE INDEX IF NOT EXISTS samples_agent ON samples(agent,sequence DESC);`);
+            const insert = connection.prepare("INSERT INTO samples(agent,task,ts,status,duration,exit) VALUES (?,?,?,?,?,?)");
+            const save = (sample) => insert.run(sample.agent, sample.task, sample.ts, sample.status, sample.duration, sample.exit ?? null);
+            if (!connection.prepare("SELECT key FROM timing_meta WHERE key='legacy-imported'").get()) {
+                // Another writer may have imported while this snapshot was being read.
+                for (const sample of legacy)
+                    save(sample);
+                connection.exec("INSERT INTO timing_meta VALUES ('legacy-imported')");
+            }
+            save(entry);
+            connection.prepare("DELETE FROM samples WHERE agent=? AND sequence NOT IN (SELECT sequence FROM samples WHERE agent=? ORDER BY sequence DESC LIMIT ?)").run(agent, agent, MAX_AGENT_SAMPLES);
+        });
+    }
+    catch { /* Best-effort timing metadata must never interrupt a run. */ }
+    finally {
+        db?.close();
+    }
+}
+export function loadRunsForAgent(agent) {
+    const agentDir = getAgentDir(), file = path.join(agentDir, "history-index", TIMING_DATABASE);
+    if (!fs.existsSync(file))
+        return legacySamples(agentDir, agent);
+    let db;
+    try {
+        db = openHistoryDatabase(path.join(historyDirectory(agentDir, false), TIMING_DATABASE), true);
+        return db.prepare("SELECT agent,task,ts,status,duration,exit FROM samples WHERE agent=? ORDER BY sequence DESC LIMIT ?").all(agent, MAX_AGENT_SAMPLES)
+            .map((row) => ({ agent: String(row.agent), task: String(row.task), ts: Number(row.ts), status: row.status, duration: Number(row.duration), ...(row.exit === null ? {} : { exit: Number(row.exit) }) }));
+    }
+    catch {
+        return [];
+    }
+    finally {
+        db?.close();
+    }
+}

package/dist/runs/shared/run-id-ambiguity.js

@@ -0,0 +1,4 @@
+export function formatRunIdAmbiguity(kind, prefix, candidates) {
+    const preview = candidates.slice(0, 5);
+    return `Ambiguous ${kind} run id prefix '${prefix}' matched: ${preview.join(", ")}. ${candidates.length} matches (showing ${preview.length}). Provide a longer prefix or full run id.`;
+}