@sovovs/bycli 1.8.0 → 2.0.0

package/dist/src/recorder/runner/reap.js

@@ -0,0 +1,230 @@
+/**
+ * Startup reap (08:37) + age-based TTL sweep (M7b). On daemon (Local Service) restart, a
+ * verify-runner child and its temp dir can outlive the parent that spawned it (the parent crashed
+ * before cleanup). On startup — and periodically while running — we scan os.tmpdir() for
+ * `bycli-verify-*` dirs and clean up two classes:
+ *   1. TRUE orphans: runs whose `ownerPid` (the spawning daemon/CLI) is no longer alive.
+ *   2. AGED-OUT leaks (M7b): dirs older than the EFFECTIVE threshold, regardless of owner liveness.
+ *      The caller floors that threshold at the run's hard deadline (`minLeakAgeMs` = timeoutMs +
+ *      killGraceMs) — a verify cannot legitimately outlive its own kill deadline, and the runner-port
+ *      deletes the temp dir on settle, so a dir still present past the deadline is a definite leak
+ *      (the owning process died mid-run), never a live run. NOTE: the raw configured TTL alone is NOT
+ *      safe — RECORDER_TEMP_TTL_MS can be set as low as 60000ms while timeoutMs reaches 600000ms, so
+ *      without the floor the periodic sweep could kill a still-running verify.
+ * A run that is neither an orphan nor aged-out is left untouched, so a sibling process's in-flight
+ * verify is never disturbed.
+ *
+ * For a confirmed reap target whose child pid is still alive AND whose live cmdline matches
+ * (`verify-runner` + the marker requestId — a pid-reuse guard), we SIGTERM then SIGKILL. The
+ * temp dir (which holds input.json with raw seed args) is always deleted for a confirmed target.
+ *
+ * Pure helpers (parse / match / orphan / aged-out decision) are exported for unit testing; the IO
+ * entry point takes an injectable ProcProbe + clock so tests never read /proc, run `ps`, or kill.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+/** Parse + validate marker.json. Returns null unless it is a well-formed verify marker. */
+export function parseVerifyMarker(raw) {
+    let m;
+    try {
+        m = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!m || typeof m !== 'object')
+        return null;
+    const o = m;
+    if (o.operation !== 'verify')
+        return null;
+    if (typeof o.requestId !== 'string' || !o.requestId)
+        return null;
+    if (typeof o.tempRoot !== 'string' || !o.tempRoot)
+        return null;
+    const intOrNull = (v) => (typeof v === 'number' && Number.isInteger(v) && v > 0 ? v : null);
+    return {
+        requestId: o.requestId,
+        pid: intOrNull(o.pid),
+        ownerPid: intOrNull(o.ownerPid),
+        startedAt: typeof o.startedAt === 'number' ? o.startedAt : 0,
+        tempRoot: o.tempRoot,
+        operation: 'verify',
+    };
+}
+/** Does a live process's command line belong to THIS marker's runner? (pid-reuse guard) */
+export function cmdlineMatchesMarker(cmdline, marker) {
+    return cmdline.includes('verify-runner') && cmdline.includes(marker.requestId);
+}
+/** Containment: the dir must sit directly under tmpRoot and carry our prefix. */
+export function isReapableTempDir(dir, tmpRoot) {
+    const resolved = path.resolve(dir);
+    return path.dirname(resolved) === path.resolve(tmpRoot) && path.basename(resolved).startsWith('bycli-verify-');
+}
+/**
+ * True orphan iff the spawning owner is gone. An unknown ownerPid (legacy marker without the
+ * field) is treated as live → skipped, so we never kill a run we cannot attribute to a dead owner.
+ */
+export function isOrphan(marker, ownerAlive) {
+    return marker.ownerPid !== null && !ownerAlive;
+}
+/**
+ * Aged-out leak (M7b · RECORDER_TEMP_TTL_MS / RECORDER_STARTUP_REAP_MAX_AGE_MS, 09:27-28):
+ * a temp dir older than `maxAgeMs` is reaped regardless of owner liveness. CALLERS MUST pass the
+ * floored threshold from `effectiveLeakThresholdMs` (never the raw config) — `maxAgeMs` here is
+ * assumed to already exceed the run's hard deadline, so a dir older than it is a definite leak,
+ * never a live run. An undatable legacy marker (startedAt<=0) is never aged-out (we cannot
+ * attribute its age). maxAgeMs<=0 disables age-based reaping (orphan-only, the pre-M7b behavior).
+ */
+export function isAgedOut(marker, now, maxAgeMs) {
+    return maxAgeMs > 0 && marker.startedAt > 0 && now - marker.startedAt > maxAgeMs;
+}
+/**
+ * Effective age-reap threshold: the configured `maxAgeMs` floored at the run's hard deadline
+ * (`minLeakAgeMs` = timeoutMs + killGraceMs). A threshold below the max legitimate run lifetime would
+ * let the sweep kill a still-running verify — a live run can outlive a short TTL but never its own
+ * kill deadline, so flooring closes that hole. A 0/negative configured value keeps age-reaping
+ * disabled (orphan-only).
+ */
+export function effectiveLeakThresholdMs(maxAgeMs, minLeakAgeMs) {
+    return maxAgeMs > 0 ? Math.max(maxAgeMs, minLeakAgeMs) : 0;
+}
+function defaultIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultCmdline(pid) {
+    if (process.platform === 'win32')
+        return null; // no portable cmdline probe → don't kill on win32
+    try {
+        return execFileSync('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf8', timeout: 2000 }).trim();
+    }
+    catch {
+        return null;
+    } // ps non-zero → pid not alive
+}
+function defaultStartTime(pid) {
+    if (process.platform === 'win32')
+        return null; // no portable start-time probe on win32
+    try {
+        const out = execFileSync('ps', ['-p', String(pid), '-o', 'lstart='], { encoding: 'utf8', timeout: 2000 }).trim();
+        if (!out)
+            return null;
+        const t = new Date(out).getTime(); // `ps -o lstart` is an absolute local-time stamp Date can parse
+        return Number.isNaN(t) ? null : t;
+    }
+    catch {
+        return null;
+    }
+}
+const defaultProbe = {
+    isAlive: defaultIsAlive,
+    cmdline: defaultCmdline,
+    startTime: defaultStartTime,
+    kill: (pid, signal) => { process.kill(pid, signal); },
+};
+/** Tolerance (ms) absorbing start-time measurement granularity (`ps lstart` is second-resolution). */
+const OWNER_PID_REUSE_TOLERANCE_MS = 60_000;
+/**
+ * Owner pid-reuse guard (#6): the spawning owner necessarily started BEFORE it created this run, so a
+ * process now occupying `ownerPid` whose start time is meaningfully AFTER the run was created cannot be
+ * that owner — the real owner died and the pid was recycled, making this a true orphan. Undeterminable
+ * start time (win32 / ps failure → null) → NOT reused: we never escalate to a kill on a guess, so a
+ * live owner is never misclassified (its start time is ≤ runStartedAt, far below the threshold).
+ */
+export function isOwnerPidReused(liveStartTime, runStartedAt, toleranceMs) {
+    if (liveStartTime === null || runStartedAt <= 0)
+        return false;
+    return liveStartTime > runStartedAt + toleranceMs;
+}
+/**
+ * Scan tmpRoot for orphaned / aged-out verify temp dirs and clean them up. Synchronous (runs at
+ * daemon startup and on a periodic sweep); the SIGKILL backstop is scheduled async + unref'd so it
+ * never blocks. `maxAgeMs` (M7b) enables age-based reaping; 0/undefined keeps orphan-only behavior.
+ */
+export function reapOrphanedVerifyRuns(opts = {}) {
+    const tmpRoot = opts.tmpRoot ?? os.tmpdir();
+    const log = opts.log ?? (() => { });
+    const probe = opts.probe ?? defaultProbe;
+    const graceMs = opts.graceMs ?? 2000;
+    const maxAgeMs = effectiveLeakThresholdMs(opts.maxAgeMs ?? 0, opts.minLeakAgeMs ?? 0);
+    const now = opts.now ?? Date.now();
+    const result = { scanned: 0, orphans: 0, agedOut: 0, killed: 0, deleted: 0 };
+    let entries;
+    try {
+        entries = fs.readdirSync(tmpRoot);
+    }
+    catch {
+        return result;
+    }
+    for (const entry of entries) {
+        if (!entry.startsWith('bycli-verify-'))
+            continue;
+        const dir = path.join(tmpRoot, entry);
+        if (!isReapableTempDir(dir, tmpRoot))
+            continue;
+        result.scanned++;
+        let marker = null;
+        try {
+            const st = fs.lstatSync(dir);
+            if (!st.isDirectory() || st.isSymbolicLink())
+                continue; // skip non-dirs / symlinks
+            if (typeof process.getuid === 'function' && st.uid !== process.getuid())
+                continue; // not ours
+            marker = parseVerifyMarker(fs.readFileSync(path.join(dir, 'marker.json'), 'utf8'));
+        }
+        catch {
+            continue;
+        } // unreadable / missing marker → leave it (can't attribute ownership)
+        if (!marker)
+            continue;
+        let ownerAlive = marker.ownerPid !== null ? probe.isAlive(marker.ownerPid) : true;
+        if (ownerAlive && marker.ownerPid !== null) {
+            // pid-reuse guard (#6): an "alive" ownerPid that started after this run was created is a
+            // recycled pid, not the original owner → the real owner is dead → orphan.
+            const liveStart = probe.startTime ? probe.startTime(marker.ownerPid) : null;
+            if (isOwnerPidReused(liveStart, marker.startedAt, OWNER_PID_REUSE_TOLERANCE_MS))
+                ownerAlive = false;
+        }
+        const orphan = isOrphan(marker, ownerAlive);
+        const aged = isAgedOut(marker, now, maxAgeMs);
+        if (!orphan && !aged)
+            continue; // live owner + within TTL → still an active/managed run
+        if (orphan)
+            result.orphans++;
+        if (aged)
+            result.agedOut++;
+        // Confirmed target: terminate the child only if it is still alive AND identifiably ours.
+        if (marker.pid !== null && probe.isAlive(marker.pid)) {
+            const cmdline = probe.cmdline(marker.pid);
+            if (cmdline && cmdlineMatchesMarker(cmdline, marker)) {
+                const pid = marker.pid;
+                try {
+                    probe.kill(pid, 'SIGTERM');
+                }
+                catch { /* already gone */ }
+                setTimeout(() => { try {
+                    probe.kill(pid, 'SIGKILL');
+                }
+                catch { /* gone */ } }, graceMs).unref?.();
+                result.killed++;
+                log(`[reap] terminated verify runner pid=${pid} req=${marker.requestId}`);
+            }
+        }
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+            result.deleted++;
+        }
+        catch { /* best-effort */ }
+    }
+    if (result.scanned > 0) {
+        log(`[reap] verify temp: scanned=${result.scanned} orphans=${result.orphans} agedOut=${result.agedOut} killed=${result.killed} deleted=${result.deleted}`);
+    }
+    return result;
+}

package/dist/src/recorder/runner/reap.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/recorder/runner/runner-port.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Real RunnerPort (M6a · 08) — the child-process verify runner mechanism.
+ *
+ * Replaces M5c's stubRunnerPort. Responsibilities (08 Process Rules):
+ *  - create requestId BEFORE launch; async registry of in-flight runs
+ *  - write input.json securely: per-request `0700` temp dir (owner/mode/realpath/lstat
+ *    checked), exclusive `0600` file; raw seed args live here only, never in status/log
+ *  - spawn `bycli internal verify-runner --jsonl …` with an args array (no shell), minimal env
+ *  - parse stdout JSONL via the pure parseRunnerEvent; one and only one terminal `result`
+ *  - hard timeout → SIGTERM (graceful) → SIGKILL; stdout/stderr byte caps
+ *  - cancel is idempotent; temp dir is always cleaned on done/cancel/timeout
+ *
+ * M6a does NOT implement: startup reap, browser-adapter execution (needs a daemon Page),
+ * concurrency-queue refinement — those are M6b/c. Browser adapters report not-yet from the
+ * runner itself (see verify-runner-main.ts).
+ *
+ * SECURITY: `rawSeedArgs` go into input.json (0600) only. getVerifyStatus returns a
+ * summary-only VerifySummary (normalizeRunnerResult) — raw values never reach it.
+ */
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+import { type VerifySummary, type RunnerConfig, type Metrics, type TempCapacity } from '@sovovs/bycli-recorder-core';
+import type { RunnerPort } from '../highlevel/verify.js';
+import { type Logger } from '../observability/logger.js';
+type RunStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timeout' | 'cancelled';
+type SpawnFn = (command: string, args: string[], options: SpawnOptions) => ChildProcess;
+export interface RunnerPortOptions {
+    /** Range-validated config (09). Defaults to env (resolveRunnerConfig). */
+    config?: RunnerConfig;
+    /** What to launch: command + the args placed BEFORE the `internal verify-runner …` argv.
+     * Default: this node binary + the main entry, i.e. `node <main.js> internal verify-runner …`.
+     * Tests inject a fixture runner script here. */
+    launcher?: {
+        command: string;
+        prefixArgs: string[];
+    };
+    /** site/command → adapter module path. Default: ~/.bycli/clis/<site>/<command>.js. */
+    resolveAdapterPath?: (name: string) => string;
+    /** Injectable spawn (tests). Default node:child_process.spawn. */
+    spawnImpl?: SpawnFn;
+    /** Daemon port handed to the child (BYCLI_DAEMON_PORT) so M6b adapters can reach the Page. */
+    daemonPort?: number;
+    /** How long a terminal run lingers in `runs` for status reads before GC (default 5min). */
+    terminalRetentionMs?: number;
+    /** Observability (#1c · 09). The daemon injects its process singletons (shared with GET /metrics)
+     *  via setDefaultRunnerObservability; standalone/tests get a throwaway registry + silent logger. */
+    metrics?: Metrics;
+    logger?: Logger;
+    /** Temp-store capacity guard (#1d · 09). When set, the runner measures verify temp usage before
+     *  writing a new run and refuses (temp_store_full) past the high watermark. Undefined → no guard
+     *  (one-shot CLI verify; only the long-running daemon enforces). */
+    tempCapacity?: TempCapacity;
+    /** Injectable temp-usage measurement (bytes). Default scans os.tmpdir() bycli-verify-* dirs.
+     *  A throw is treated as over-capacity (fail-closed). Tests inject to force pressure without IO. */
+    measureTempBytes?: () => number;
+    /** Best-effort on-pressure sweep (shed orphan/aged temp dirs before re-measuring). The daemon
+     *  passes its reap; default no-op (the periodic daemon sweep is the backstop). */
+    sweepTemp?: () => void;
+}
+/** The default runner port also exposes test/lifecycle helpers beyond the RunnerPort seam. */
+export interface RunnerPortWithLifecycle extends RunnerPort {
+    /** Resolve when the run reaches a terminal state (test hook / status await). */
+    whenSettled(requestId: string): Promise<VerifySummary> | null;
+    /** Count of runs currently in the `running` state. */
+    activeCount(): number;
+    /** Count of runs waiting in the queue (status `queued`, not yet launched). */
+    queuedCount(): number;
+    /** Status + summary for an in-flight or settled run (daemon GET /v1/requests). null = unknown id. */
+    getRunStatus(requestId: string): {
+        status: RunStatus;
+        summary: VerifySummary | null;
+    } | null;
+}
+export declare function createRunnerPort(opts?: RunnerPortOptions): RunnerPortWithLifecycle;
+/**
+ * Configure the daemon port the default runner hands to child processes via
+ * BYCLI_DAEMON_PORT (M6b: browser adapters connect back to this daemon for a Page).
+ * The daemon calls this at startup BEFORE the first defaultRunnerPort() use; calling it
+ * after the singleton is built is a no-op (the port is fixed at construction).
+ */
+export declare function setDefaultRunnerDaemonPort(port: number): void;
+/**
+ * Share the daemon's metrics + structured logger with the default runner (#1c), so runner counters
+ * (timeout / queue depth / protocol error / verify duration) surface on the daemon's GET /metrics and
+ * runner verify logs share the daemon's level. Same injection contract as setDefaultRunnerDaemonPort:
+ * the daemon calls this at startup BEFORE the first defaultRunnerPort() use; later calls are no-ops.
+ */
+export declare function setDefaultRunnerObservability(metrics: Metrics, logger: Logger): void;
+/**
+ * Enable the temp-store capacity guard on the default runner (#1d). Only the daemon (the long-running
+ * owner of verify temp dirs) calls this; one-shot CLI verify leaves it off. `sweepTemp` is the daemon's
+ * on-pressure shed (its reap). Same injection contract: call BEFORE the first defaultRunnerPort() use.
+ */
+export declare function setDefaultRunnerTempGuard(capacity: TempCapacity, sweepTemp?: () => void): void;
+export declare function defaultRunnerPort(): RunnerPortWithLifecycle;
+export {};