xcoder-dna 0.0.0-stage → 1.3.1

package/dist/util/logs.js

@@ -0,0 +1,88 @@
+// xcoder:version 2 | xcoder:task task-ebf4f7 | xcoder:updated 2026-10-17T12:16:50.555Z | xcoder:subtask test-st-f454da
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { redactSecrets } from "./redact.js";
+export { redactSecrets, REDACTED } from "./redact.js";
+const MAX_BYTES = 1_000_000; // 1MB, per the brief
+function logDir(root, taskId) {
+    return path.join(root, ".xcoder", "logs", taskId);
+}
+function logFile(root, taskId, name) {
+    return path.join(logDir(root, taskId), name);
+}
+/**
+ * Single-generation size-based rollover: once appending would push a log
+ * file past 1MB, the current file is renamed to `<name>.1` (clobbering
+ * whatever was there before) and a fresh file is started. Simple and
+ * bounded — never accumulates unbounded history, never grows past ~2MB
+ * per log per task.
+ */
+async function appendWithRollover(filePath, line) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const entry = line.endsWith("\n") ? line : line + "\n";
+    let currentSize = 0;
+    try {
+        currentSize = (await fs.stat(filePath)).size;
+    }
+    catch {
+        currentSize = 0;
+    }
+    if (currentSize + Buffer.byteLength(entry, "utf8") > MAX_BYTES) {
+        const rolled = filePath.replace(/(\.[^.]+)$/, ".1$1");
+        try {
+            await fs.rm(rolled, { force: true });
+            await fs.rename(filePath, rolled);
+        }
+        catch {
+            // best-effort; if the rename fails just keep appending to the current file
+        }
+    }
+    await fs.appendFile(filePath, entry, "utf8");
+}
+function ts() {
+    return new Date().toISOString();
+}
+/** Reason (Thought) → Action → Observation trace, one line per step, human-readable. */
+export async function appendThink(root, taskId, subtaskId, line) {
+    await appendWithRollover(logFile(root, taskId, "think.log"), `[${ts()}] [${subtaskId}] ${line}`);
+}
+/** System-level errors: crashes, tool exceptions, anything that would otherwise vanish silently. */
+export async function appendSys(root, taskId, line) {
+    await appendWithRollover(logFile(root, taskId, "sys.log"), `[${ts()}] ${line}`);
+}
+/** Raw LLM request/response pairs, one JSON line each. */
+export async function appendLlm(root, taskId, subtaskId, entry) {
+    const stopSeg = entry.stopReason ? ` [stop=${entry.stopReason}]` : "";
+    // C7: redact before the line reaches disk — a key pasted into a prompt or
+    // echoed by a model must never land in llm.log.
+    const { text: safeContent } = redactSecrets(entry.content);
+    await appendWithRollover(logFile(root, taskId, "llm.log"), `[${ts()}] [${subtaskId}]${stopSeg} [${entry.direction}] ${safeContent.replace(/\n/g, "\\n")}`);
+}
+/** Token usage per LLM call, plus running totals — one line per call. */
+export async function appendToken(root, taskId, subtaskId, usage) {
+    await appendWithRollover(logFile(root, taskId, "token.log"), `[${ts()}] [${subtaskId}] in=${usage.inputTokens} out=${usage.outputTokens} ` +
+        `(task-cumulative in=${usage.cumulativeInput} out=${usage.cumulativeOutput})`);
+}
+/** Reasoning-effectiveness score per subtask attempt, with its full breakdown — see orchestrator/reasoning-score.ts for what this is and isn't. */
+export async function appendScore(root, taskId, subtaskId, score) {
+    await appendWithRollover(logFile(root, taskId, "score.log"), `[${ts()}] [${subtaskId}] score=${score.score}/100\n  ` + score.breakdown.join("\n  "));
+}
+/**
+ * Every file (or shell command) any tool touched: one line per access,
+ * `[ts] [subtask] tool=… op=… ok=… path=…` (or `cmd=…` for shell commands).
+ * Same 1 MB single-generation rollover (`files.log` → `files.1.log`) as the
+ * other logs. Writes are serialised so parallel agents can't race the
+ * stat/rename in `appendWithRollover`.
+ */
+let filesChain = Promise.resolve();
+export function appendFiles(root, taskId, subtaskId, line) {
+    filesChain = filesChain
+        .then(() => appendWithRollover(logFile(root, taskId, "files.log"), `[${ts()}] [${subtaskId}] ${line}`))
+        .catch(() => {
+        // logging must never break a tool call
+    });
+    return filesChain;
+}
+export function taskLogDir(root, taskId) {
+    return logDir(root, taskId);
+}

package/dist/util/output-handler.d.ts

@@ -0,0 +1,89 @@
+/**
+ * OutputHandler — centralized output sink for ReAct signals.
+ *
+ * Provides flag-gated terminal output and optional SQLite persistence
+ * for Thought, Reason, Action, Observation, and raw/error signals.
+ *
+ * Singleton pattern: use getOutputHandler() to obtain the instance.
+ * Call reset() in tests to clear the singleton between test cases.
+ *
+ * SQLite support is via sql.js (wasm-based, zero native deps) as an
+ * optional dependency. It is lazy-loaded on first logToSqlite:true call
+ * and falls back gracefully if the package is not installed.
+ */
+export interface OutputHandlerOptions {
+    /** Whether to print signals to stdout (default: true). */
+    printToTerminal: boolean;
+    /** Whether to persist signals to SQLite (default: false). */
+    logToSqlite?: boolean;
+    /** Path to the SQLite database file (default: ".xcoder/output.db"). */
+    dbPath?: string;
+}
+/**
+ * Obtain the singleton OutputHandler instance.
+ * On first call, the instance is created with the provided options.
+ * Subsequent calls return the same instance (options are ignored).
+ */
+export declare function getOutputHandler(opts?: OutputHandlerOptions): OutputHandler;
+/**
+ * Reset the singleton instance — for test use only.
+ */
+export declare function resetOutputHandler(): void;
+export declare class OutputHandler {
+    private printToTerminal;
+    private logToSqlite;
+    private dbPath;
+    private db;
+    private initPromise;
+    constructor(opts: OutputHandlerOptions);
+    /**
+     * Lazy-initialize the SQLite database.
+     * Uses sql.js (wasm-based, zero native deps).
+     * Falls back gracefully if sql.js is not installed.
+     */
+    private ensureDb;
+    private _initDb;
+    /**
+     * Emit a thought signal.
+     */
+    thought(msg: string): void;
+    /**
+     * Emit a reasoning step.
+     */
+    reason(msg: string): void;
+    /**
+     * Emit an action invocation.
+     */
+    action(tool: string, input: unknown): void;
+    /**
+     * Emit a tool observation.
+     */
+    observation(msg: string): void;
+    /**
+     * Generic fallback output.
+     */
+    raw(msg: string): void;
+    /**
+     * Emit an error signal.
+     */
+    error(msg: string): void;
+    /**
+     * Core emit logic — prints to terminal if flag is on,
+     * and persists to SQLite if enabled.
+     */
+    private emit;
+    /**
+     * Print a formatted signal to stdout.
+     */
+    private printSignal;
+    /**
+     * Persist a signal to the SQLite database.
+     * Fire-and-forget — does not throw on failure.
+     */
+    private persistSignal;
+    /**
+     * Close the SQLite database connection.
+     * Call on process exit or when the handler is no longer needed.
+     */
+    close(): void;
+}

package/dist/util/output-handler.js

@@ -0,0 +1,193 @@
+// xcoder:version 10 | xcoder:task task-7f2823 | xcoder:updated 2026-08-03T09:31:58.357Z | xcoder:subtask code-st-e8e2bf
+/**
+ * OutputHandler — centralized output sink for ReAct signals.
+ *
+ * Provides flag-gated terminal output and optional SQLite persistence
+ * for Thought, Reason, Action, Observation, and raw/error signals.
+ *
+ * Singleton pattern: use getOutputHandler() to obtain the instance.
+ * Call reset() in tests to clear the singleton between test cases.
+ *
+ * SQLite support is via sql.js (wasm-based, zero native deps) as an
+ * optional dependency. It is lazy-loaded on first logToSqlite:true call
+ * and falls back gracefully if the package is not installed.
+ */
+/**
+ * Mutable singleton reference — reset between tests via reset().
+ */
+let _instance = null;
+/**
+ * Obtain the singleton OutputHandler instance.
+ * On first call, the instance is created with the provided options.
+ * Subsequent calls return the same instance (options are ignored).
+ */
+export function getOutputHandler(opts) {
+    if (!_instance) {
+        _instance = new OutputHandler(opts ?? { printToTerminal: true });
+    }
+    return _instance;
+}
+/**
+ * Reset the singleton instance — for test use only.
+ */
+export function resetOutputHandler() {
+    if (_instance) {
+        _instance.close();
+        _instance = null;
+    }
+}
+export class OutputHandler {
+    printToTerminal;
+    logToSqlite;
+    dbPath;
+    db = null; // sql.js Database | null
+    initPromise = null;
+    constructor(opts) {
+        this.printToTerminal = opts.printToTerminal;
+        this.logToSqlite = opts.logToSqlite ?? false;
+        this.dbPath = opts.dbPath ?? ".xcoder/output.db";
+    }
+    /**
+     * Lazy-initialize the SQLite database.
+     * Uses sql.js (wasm-based, zero native deps).
+     * Falls back gracefully if sql.js is not installed.
+     */
+    async ensureDb() {
+        if (this.db !== null)
+            return this.db;
+        if (!this.initPromise) {
+            this.initPromise = this._initDb();
+        }
+        const db = await this.initPromise;
+        this.db = db;
+        this.initPromise = null;
+        return db;
+    }
+    async _initDb() {
+        try {
+            // Dynamic import — sql.js is an optionalDependency.
+            // Falls back gracefully if not installed.
+            const initSqlJs = (await import("sql.js")).default;
+            const SQL = await initSqlJs();
+            const db = new SQL.Database();
+            // Create schema
+            db.run(`
+        CREATE TABLE IF NOT EXISTS output_log (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          ts TEXT NOT NULL DEFAULT (datetime('now')),
+          level TEXT NOT NULL CHECK(level IN ('thought','reason','action','observation','raw','error')),
+          content TEXT NOT NULL,
+          metadata TEXT
+        )
+      `);
+            return db;
+        }
+        catch (err) {
+            // sql.js not installed — emit a warning once and fall back
+            console.warn("[output-handler] sql.js not available — SQLite logging disabled. " +
+                "Install with: npm install sql.js");
+            return null;
+        }
+    }
+    /**
+     * Emit a thought signal.
+     */
+    thought(msg) {
+        this.emit("thought", msg);
+    }
+    /**
+     * Emit a reasoning step.
+     */
+    reason(msg) {
+        this.emit("reason", msg);
+    }
+    /**
+     * Emit an action invocation.
+     */
+    action(tool, input) {
+        const meta = input !== undefined
+            ? JSON.stringify(typeof input === "string" ? input.slice(0, 200) : input).slice(0, 500)
+            : undefined;
+        this.emit("action", tool, meta);
+    }
+    /**
+     * Emit a tool observation.
+     */
+    observation(msg) {
+        this.emit("observation", msg);
+    }
+    /**
+     * Generic fallback output.
+     */
+    raw(msg) {
+        this.emit("raw", msg);
+    }
+    /**
+     * Emit an error signal.
+     */
+    error(msg) {
+        this.emit("error", msg);
+    }
+    /**
+     * Core emit logic — prints to terminal if flag is on,
+     * and persists to SQLite if enabled.
+     */
+    emit(level, content, metadata) {
+        if (this.printToTerminal) {
+            this.printSignal(level, content, metadata);
+        }
+        if (this.logToSqlite) {
+            this.persistSignal(level, content, metadata);
+        }
+    }
+    /**
+     * Print a formatted signal to stdout.
+     */
+    printSignal(level, content, metadata) {
+        const now = new Date().toISOString();
+        const metaStr = metadata ? ` | ${metadata}` : "";
+        console.log(`[${now}] [${level.toUpperCase()}] ${content}${metaStr}`);
+    }
+    /**
+     * Persist a signal to the SQLite database.
+     * Fire-and-forget — does not throw on failure.
+     */
+    persistSignal(level, content, metadata) {
+        this.ensureDb()
+            .then((db) => {
+            if (!db)
+                return;
+            const stmt = db.run.bind(db);
+            // Build INSERT via raw SQL to avoid prepared-statement API differences
+            const safeContent = content.replace(/'/g, "''");
+            const safeMeta = metadata ? metadata.replace(/'/g, "''") : "";
+            const sql = safeMeta
+                ? `INSERT INTO output_log (level, content, metadata) VALUES ('${level}', '${safeContent}', '${safeMeta}')`
+                : `INSERT INTO output_log (level, content) VALUES ('${level}', '${safeContent}')`;
+            try {
+                db.run(sql);
+            }
+            catch {
+                // Silently ignore DB write errors — log persistence is best-effort
+            }
+        })
+            .catch(() => {
+            // Silently ignore — sql.js load failed (already warned)
+        });
+    }
+    /**
+     * Close the SQLite database connection.
+     * Call on process exit or when the handler is no longer needed.
+     */
+    close() {
+        if (this.db) {
+            try {
+                this.db.close();
+            }
+            catch {
+                // Ignore
+            }
+            this.db = null;
+        }
+    }
+}

package/dist/util/output-interceptor.d.ts

@@ -0,0 +1,18 @@
+import type { ScrollRegionGuard } from "./scroll-region-guard.js";
+/**
+ * OutputInterceptor — monkey-patches `process.stdout.write` during the
+ * footer's active lifetime to route ALL writes through the ScrollRegionGuard.
+ *
+ * This is the "nuclear option" that guarantees no write can break the
+ * scroll region, even from third-party code or libraries we don't control
+ * (ora, clack, etc.).
+ *
+ * Activated via XCODER_INTERCEPT_STDOUT=1 feature flag. Not enabled by
+ * default because monkey-patching process.stdout.write is fragile and
+ * can interfere with cursor-positioning ANSI sequences that clack/ora
+ * rely on.
+ *
+ * @param guard - The ScrollRegionGuard to route writes through.
+ * @returns A restore function that undoes the monkey-patch.
+ */
+export declare function interceptStdout(guard: ScrollRegionGuard): () => void;

package/dist/util/output-interceptor.js

@@ -0,0 +1,49 @@
+/**
+ * OutputInterceptor — monkey-patches `process.stdout.write` during the
+ * footer's active lifetime to route ALL writes through the ScrollRegionGuard.
+ *
+ * This is the "nuclear option" that guarantees no write can break the
+ * scroll region, even from third-party code or libraries we don't control
+ * (ora, clack, etc.).
+ *
+ * Activated via XCODER_INTERCEPT_STDOUT=1 feature flag. Not enabled by
+ * default because monkey-patching process.stdout.write is fragile and
+ * can interfere with cursor-positioning ANSI sequences that clack/ora
+ * rely on.
+ *
+ * @param guard - The ScrollRegionGuard to route writes through.
+ * @returns A restore function that undoes the monkey-patch.
+ */
+export function interceptStdout(guard) {
+    const originalWrite = process.stdout.write.bind(process.stdout);
+    // Prevent double-patching
+    if (process.stdout.write._intercepted) {
+        return () => { };
+    }
+    process.stdout.write._intercepted = true;
+    process.stdout.write = function (chunk, encodingOrCb, cb) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const text = typeof chunk === "string" ? chunk : chunk.toString();
+        // Resolve callback arguments
+        let callback;
+        let encoding;
+        if (typeof encodingOrCb === "function") {
+            callback = encodingOrCb;
+        }
+        else if (encodingOrCb) {
+            encoding = encodingOrCb;
+            callback = cb;
+        }
+        // Guard: write safely through the scroll region
+        guard.write(text);
+        // Fire callback if provided
+        if (callback) {
+            callback();
+        }
+        return true;
+    };
+    return () => {
+        process.stdout.write._intercepted = false;
+        process.stdout.write = originalWrite;
+    };
+}

package/dist/util/output-paths.d.ts

@@ -0,0 +1,43 @@
+export interface OutputPathsConfig {
+    /** Base directory for all reports. Defaults to ".reports". */
+    reportsDir?: string;
+    /** Base directory for all temporary files. Defaults to ".tmp". */
+    tmpDir?: string;
+    /** Working directory root. Defaults to process.cwd(). */
+    cwd?: string;
+}
+export interface OutputPaths {
+    readonly reportsDir: string;
+    readonly tmpDir: string;
+    /** Sprint gate rejection + retro reports → <reportsDir>/sprint/ */
+    sprintReportsDir(): string;
+    /** AI chat debate reports → <reportsDir>/ai-chat/ */
+    aiChatReportsDir(): string;
+    /** Bench reports → <reportsDir>/bench/ */
+    benchReportsDir(): string;
+    /** Regression output → <reportsDir>/regression/ */
+    regressionDir(): string;
+    /** Instance swarm output → <reportsDir>/instance-swarms/ */
+    instanceSwarmDir(instanceId: string): string;
+    /** Atomic-write staging → <tmpDir>/atomic/ */
+    atomicDir(): string;
+    /** Protocol error log path → <reportsDir>/protocol_error.log */
+    protocolErrorLogPath(): string;
+    /** Bench report file path → <reportsDir>/bench/report-<ts>.json */
+    benchReportPath(ts?: string): string;
+    /**
+     * Ensures .gitignore contains entries for .reports/ and .tmp/.
+     * Lazily called on first write — fire-and-forget, never throws.
+     */
+    ensureGitignore(): void;
+}
+/**
+ * Returns the singleton OutputPaths instance. On first call, the optional
+ * config is applied; subsequent calls ignore the config (singleton pattern).
+ */
+export declare function getOutputPaths(config?: OutputPathsConfig): OutputPaths;
+/**
+ * Resets the singleton. Primarily for test isolation — call in afterEach.
+ * After reset, the next getOutputPaths() call creates a fresh instance.
+ */
+export declare function resetOutputPaths(): void;

package/dist/util/output-paths.js

@@ -0,0 +1,121 @@
+// xcoder:version 1 | xcoder:task swarm-swarm-is-b22287 | xcoder:updated 2026-08-04T12:11:06.168Z | xcoder:subtask swarm-swarm-is-b22287/1
+import fs from "node:fs";
+import path from "node:path";
+// ---------------------------------------------------------------------------
+// Singleton state
+// ---------------------------------------------------------------------------
+let _instance = null;
+let _config;
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const GITIGNORE_ENTRIES = [
+    "# Xcoder SDLC generated artifacts (managed by src/util/output-paths.ts)",
+    ".reports/",
+    ".tmp/",
+    ".xcoder/",
+    "!.xcoder/blueprint.md",
+];
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class OutputPathsImpl {
+    reportsDir;
+    tmpDir;
+    cwd;
+    _gitignoreEnsured = false;
+    constructor(config) {
+        this.cwd = config?.cwd ?? process.cwd();
+        this.reportsDir = path.resolve(this.cwd, config?.reportsDir ?? ".reports");
+        this.tmpDir = path.resolve(this.cwd, config?.tmpDir ?? ".tmp");
+    }
+    sprintReportsDir() {
+        return path.join(this.reportsDir, "sprint");
+    }
+    aiChatReportsDir() {
+        return path.join(this.reportsDir, "ai-chat");
+    }
+    benchReportsDir() {
+        return path.join(this.reportsDir, "bench");
+    }
+    regressionDir() {
+        return path.join(this.reportsDir, "regression");
+    }
+    instanceSwarmDir(instanceId) {
+        return path.join(this.reportsDir, "instance-swarms", instanceId);
+    }
+    atomicDir() {
+        return path.join(this.tmpDir, "atomic");
+    }
+    protocolErrorLogPath() {
+        return path.join(this.reportsDir, "protocol_error.log");
+    }
+    benchReportPath(ts) {
+        const timestamp = ts ?? new Date().toISOString().replace(/[:.]/g, "-");
+        return path.join(this.reportsDir, "bench", `report-${timestamp}.json`);
+    }
+    ensureGitignore() {
+        if (this._gitignoreEnsured)
+            return;
+        this._gitignoreEnsured = true;
+        try {
+            const gitignorePath = path.join(this.cwd, ".gitignore");
+            let existing = "";
+            let existingExists = false;
+            try {
+                existing = fs.readFileSync(gitignorePath, "utf-8");
+                existingExists = true;
+            }
+            catch {
+                // File doesn't exist — that's fine, we'll create it.
+            }
+            const existingLines = existingExists
+                ? existing.split("\n")
+                : [];
+            // Determine which entries are already present (exact match).
+            const missingEntries = GITIGNORE_ENTRIES.filter((entry) => {
+                // For the comment line, check if ANY comment about xcoder-managed is present.
+                if (entry.startsWith("# Xcoder SDLC")) {
+                    return !existingLines.some((line) => line.startsWith("# Xcoder SDLC generated artifacts"));
+                }
+                // For dir entries, check exact match.
+                return !existingLines.some((line) => line.trim() === entry);
+            });
+            if (missingEntries.length === 0)
+                return;
+            const block = [
+                ...(existingExists && existing.length > 0 && !existing.endsWith("\n")
+                    ? [""]
+                    : []),
+                ...missingEntries,
+                "",
+            ].join("\n");
+            fs.appendFileSync(gitignorePath, block, "utf-8");
+        }
+        catch {
+            // Silently swallow — gitignore management is best-effort.
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Returns the singleton OutputPaths instance. On first call, the optional
+ * config is applied; subsequent calls ignore the config (singleton pattern).
+ */
+export function getOutputPaths(config) {
+    if (!_instance) {
+        _config = config;
+        _instance = new OutputPathsImpl(config);
+    }
+    return _instance;
+}
+/**
+ * Resets the singleton. Primarily for test isolation — call in afterEach.
+ * After reset, the next getOutputPaths() call creates a fresh instance.
+ */
+export function resetOutputPaths() {
+    _instance = null;
+    _config = undefined;
+}

package/dist/util/package-json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Read package.json from workspace root if present, extract name/version/
+ * scripts/dependencies, and format as a context block injected into the
+ * system prompt. Non-fatal if absent.
+ */
+export declare function readPackageJsonContext(root: string): Promise<string | null>;

package/dist/util/package-json.js

@@ -0,0 +1,36 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/**
+ * Read package.json from workspace root if present, extract name/version/
+ * scripts/dependencies, and format as a context block injected into the
+ * system prompt. Non-fatal if absent.
+ */
+export async function readPackageJsonContext(root) {
+    try {
+        const raw = await fs.readFile(path.join(root, "package.json"), "utf8");
+        const pkg = JSON.parse(raw);
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        const depNames = Object.keys(deps).sort();
+        const depLines = depNames.length
+            ? depNames.map((n) => `  ${n}: ${deps[n]}`).join("\n")
+            : "  (none)";
+        const scriptLines = pkg.scripts
+            ? Object.entries(pkg.scripts)
+                .map(([k, v]) => `  ${k}: ${v}`)
+                .join("\n")
+            : "  (none)";
+        return `
+## Project package.json
+- name: ${pkg.name ?? "(not set)"}
+- version: ${pkg.version ?? "(not set)"}
+- description: ${pkg.description ?? "(not set)"}
+- scripts:
+${scriptLines}
+- dependencies:
+${depLines}
+`.trim();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/util/process-kill.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Kill a process and all of its descendants.
+ *
+ * @param rootPid - The PID of the root process to kill.
+ * @param signal - 'SIGTERM' for graceful, 'SIGKILL' for force.
+ * @returns Promise that resolves when all descendants are confirmed dead or after 3s timeout.
+ */
+export declare function killProcessTree(rootPid: number, signal?: "SIGTERM" | "SIGKILL"): Promise<void>;
+/**
+ * A Set of tracked child process PIDs. Used by the signal handler to
+ * kill any surviving child processes on forced exit.
+ */
+export declare const trackedPids: Set<number>;
+/**
+ * Register a pid for cleanup tracking. Safe to call multiple times
+ * (Set deduplicates).
+ */
+export declare function trackPid(pid: number): void;
+/**
+ * Remove a pid from tracking (called when process exits normally).
+ */
+export declare function untrackPid(pid: number): void;
+/**
+ * Kill all tracked PIDs and clear the set. Used in process 'exit'
+ * handler as a safety net to prevent orphaned processes.
+ */
+export declare function killTrackedPids(): Promise<void>;