@sovovs/bycli 1.8.0 → 2.1.0

package/dist/src/recorder/http/wrapper-server.d.ts

@@ -0,0 +1,59 @@
+import { createServer } from 'node:http';
+import { type WrapperConfig } from './wrapper-config.js';
+import { WrapperRegistry } from './wrapper-registry.js';
+import { type Metrics } from './wrapper-metrics.js';
+import { type AnalyzeRunner } from './analyze-runner.js';
+import { createAdapterDraft } from '../highlevel/init.js';
+import { type RunnerPortWithLifecycle } from '../runner/runner-port.js';
+/** 结构化日志允许字段(09;forbidden=token/body/seed 类型上就进不来)。 */
+interface LogFields {
+    status: string;
+    errorCode?: string;
+    durationMs?: number;
+    requestId?: string;
+}
+export interface WrapperDeps {
+    /** 注入时钟(测试 TTL)。 */
+    now?: () => number;
+    /** 注入 init 实现(测试无需写盘)。默认真实 createAdapterDraft。 */
+    createDraft?: typeof createAdapterDraft;
+    /** 结构化日志 sink(默认 stderr 单行 JSON)。 */
+    logSink?: (line: string) => void;
+    /** 注入 metrics(测试断言)。默认 createMetrics()。 */
+    metrics?: Metrics;
+    /** 注入 verify runner(测试 fake;production = defaultRunnerPort,连回 daemon 拿 Page 跑 browser adapter)。 */
+    runner?: RunnerPortWithLifecycle;
+    /** 注入 sessionId→HMAC key(测试)。默认进程级 defaultSessionKeyRegistry。 */
+    sessionKeyFor?: (sessionId?: string) => string;
+    /** 注入 analyze runner(测试 fake;production = daemon-backed Page)。 */
+    analyzeRunner?: AnalyzeRunner;
+}
+export interface WrapperCtx {
+    cfg: WrapperConfig;
+    registry: WrapperRegistry;
+    createDraft: typeof createAdapterDraft;
+    runner: RunnerPortWithLifecycle;
+    sessionKeyFor?: (sessionId?: string) => string;
+    analyzeRunner: AnalyzeRunner;
+    /** 在飞后台作业(analyze in-process Page);shutdown drain 用(Codex M9 Med)。 */
+    inflight: Set<Promise<unknown>>;
+    log: (operation: string, fields: LogFields) => void;
+    metrics: Metrics;
+}
+/** Shutdown 时等在飞作业跑完(其 finally 释放 Page lease),最多 graceMs;超时则放弃(lease 靠 daemon
+ * idle-expire 兜底)。返回时 inflight 要么空、要么已超 grace。 */
+export declare function drainInflight(inflight: Set<Promise<unknown>>, graceMs: number): Promise<void>;
+/**
+ * 装配 wrapper app(工厂 + 可注入 deps 供测试)。返回 { server, ctx };调用方负责 server.listen。
+ */
+export declare function createWrapperApp(cfg: WrapperConfig, deps?: WrapperDeps): {
+    server: ReturnType<typeof createServer>;
+    ctx: WrapperCtx;
+};
+/**
+ * `bycli internal highlevel-http` 入口:load config → 装配 → bind 127.0.0.1。默认关闭(opt-in)。
+ * 绝不打印 token(只打印 listening 行)。**在 server 存活期间不 resolve**(等 'close'),这样 main.ts
+ * 的 `await runWrapperCli()` 会一直挂起、绝不 fall-through 到完整 CLI discovery。
+ */
+export declare function runWrapperCli(): Promise<void>;
+export {};

package/dist/src/recorder/http/wrapper-server.js

@@ -0,0 +1,240 @@
+// M9 High-Level HTTP wrapper —— 独立 loopback HTTP server(07 · Optional HTTP Wrapper)。
+// 形态镜像 dashboard-be/src/server.ts 的 createApp/createServer/finish-logger,但**主仓侧**(直调
+// high-level 模块,不经 daemon bridge,不 import be)。与 daemon 的 /v1/*(daemon-high-level.v1)是
+// 独立 server / 独立路由族(ADR-0007,严禁混淆)。默认关闭,经 `bycli internal highlevel-http` 启动。
+import { createServer } from 'node:http';
+import { loadWrapperConfig } from './wrapper-config.js';
+import { WrapperRegistry } from './wrapper-registry.js';
+import { checkWrapperGates } from './wrapper-gates.js';
+import { errorBody } from './wrapper-envelope.js';
+import { handleHealth, handleInit, handleVerify, handleAnalyze, handleRequestStatus, } from './handlers.js';
+import { createMetrics } from './wrapper-metrics.js';
+import { createAnalyzeRunner } from './analyze-runner.js';
+import { createAdapterDraft } from '../highlevel/init.js';
+import { defaultRunnerPort, setDefaultRunnerDaemonPort, } from '../runner/runner-port.js';
+/** Shutdown 时等在飞作业跑完(其 finally 释放 Page lease),最多 graceMs;超时则放弃(lease 靠 daemon
+ * idle-expire 兜底)。返回时 inflight 要么空、要么已超 grace。 */
+export async function drainInflight(inflight, graceMs) {
+    if (inflight.size === 0)
+        return;
+    let timer;
+    const deadline = new Promise((r) => { timer = setTimeout(r, graceMs); });
+    try {
+        await Promise.race([Promise.allSettled([...inflight]).then(() => undefined), deadline]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+const REQUESTS_PREFIX = '/v1/requests/';
+/** Shutdown 时等在飞 analyze 释放 Page lease 的最长宽限(Codex M9 Med)。 */
+const SHUTDOWN_GRACE_MS = 5000;
+function sendOutcome(res, outcome) {
+    if (outcome.errorCode)
+        res.__errorCode = outcome.errorCode;
+    const payload = JSON.stringify(outcome.body);
+    // 04 章:不回 CORS 头(no-CORS);nosniff。
+    res.writeHead(outcome.status, { 'Content-Type': 'application/json', 'X-Content-Type-Options': 'nosniff' });
+    res.end(payload);
+}
+async function readJson(req, maxBytes) {
+    const chunks = [];
+    let size = 0;
+    for await (const c of req) {
+        size += c.length;
+        if (size > maxBytes)
+            throw new Error('payload too large');
+        chunks.push(c);
+    }
+    if (!chunks.length)
+        return {};
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+function clampWaitMs(raw, max) {
+    if (!raw)
+        return 0;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    return Math.min(Math.floor(n), max);
+}
+/** 路由分发:gate(全端点)→ 已注册端点;未匹配 404。 */
+async function route(ctx, req, res) {
+    const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+    const pathname = url.pathname;
+    const method = req.method ?? 'GET';
+    // 门禁:所有端点(含 /health)统一过 X-byCLI + Origin + token。
+    const gate = checkWrapperGates(req, { allowedOrigins: ctx.cfg.ALLOWED_ORIGINS, token: ctx.cfg.TOKEN });
+    if (!gate.ok) {
+        sendOutcome(res, {
+            status: 403,
+            body: { error: errorBody(gate.code ?? 'auth_failed', gate.message ?? 'forbidden') },
+            errorCode: gate.code ?? 'auth_failed',
+        });
+        return;
+    }
+    if (method === 'GET' && pathname === '/health') {
+        sendOutcome(res, handleHealth());
+        return;
+    }
+    // GET /metrics —— loopback metrics scrape(09 · M8 复审遗留,gated 同其它端点)。返回 snapshot JSON
+    // (counters/histograms,标签只非敏感 enum)。不入 finish-logger 计数(避免 scrape 自计/噪声)。
+    if (method === 'GET' && pathname === '/metrics') {
+        sendOutcome(res, { status: 200, body: ctx.metrics.snapshot() });
+        return;
+    }
+    if (method === 'POST' && pathname === '/v1/adapters/init') {
+        let body;
+        try {
+            body = await readJson(req, ctx.cfg.BODY_LIMIT_BYTES);
+        }
+        catch {
+            sendOutcome(res, {
+                status: 400,
+                body: { error: errorBody('validation_failed', 'request body too large or invalid JSON') },
+                errorCode: 'validation_failed',
+            });
+            return;
+        }
+        sendOutcome(res, handleInit(ctx, body));
+        return;
+    }
+    if (method === 'POST' && pathname === '/v1/adapters/verify') {
+        let body;
+        try {
+            body = await readJson(req, ctx.cfg.BODY_LIMIT_BYTES);
+        }
+        catch {
+            sendOutcome(res, {
+                status: 400,
+                body: { error: errorBody('validation_failed', 'request body too large or invalid JSON') },
+                errorCode: 'validation_failed',
+            });
+            return;
+        }
+        sendOutcome(res, await handleVerify(ctx, body));
+        return;
+    }
+    if (method === 'POST' && pathname === '/v1/browser/analyze') {
+        let body;
+        try {
+            body = await readJson(req, ctx.cfg.BODY_LIMIT_BYTES);
+        }
+        catch {
+            sendOutcome(res, {
+                status: 400,
+                body: { error: errorBody('validation_failed', 'request body too large or invalid JSON') },
+                errorCode: 'validation_failed',
+            });
+            return;
+        }
+        sendOutcome(res, handleAnalyze(ctx, body));
+        return;
+    }
+    if (method === 'GET' && pathname.startsWith(REQUESTS_PREFIX)) {
+        const requestId = pathname.slice(REQUESTS_PREFIX.length);
+        const waitMs = clampWaitMs(url.searchParams.get('waitMs'), ctx.cfg.REQUEST_WAIT_MS_MAX);
+        sendOutcome(res, await handleRequestStatus(ctx, requestId, waitMs));
+        return;
+    }
+    // 未注册路由(含 M9b/c 待接的 verify/analyze)→ 404。
+    sendOutcome(res, { status: 404, body: { error: { code: 'request_not_found', message: 'not found' } } });
+}
+/**
+ * 装配 wrapper app(工厂 + 可注入 deps 供测试)。返回 { server, ctx };调用方负责 server.listen。
+ */
+export function createWrapperApp(cfg, deps = {}) {
+    const logSink = deps.logSink ?? ((line) => process.stderr.write(line + '\n'));
+    // production runner = defaultRunnerPort();browser-verify 子进程经 BYCLI_DAEMON_PORT 连回 daemon 拿 Page,
+    // 故必须在首次 defaultRunnerPort() 前注入 daemon 端口(同 daemon.ts:49)。测试注入 deps.runner 绕开全局单例。
+    if (!deps.runner)
+        setDefaultRunnerDaemonPort(cfg.DAEMON_PORT);
+    const ctx = {
+        cfg,
+        registry: new WrapperRegistry({
+            terminalTtlMs: cfg.REQUEST_TERMINAL_STATUS_TTL_MS,
+            pollAfterMs: cfg.REQUEST_POLL_AFTER_MS,
+            now: deps.now,
+        }),
+        createDraft: deps.createDraft ?? createAdapterDraft,
+        runner: deps.runner ?? defaultRunnerPort(),
+        sessionKeyFor: deps.sessionKeyFor,
+        analyzeRunner: deps.analyzeRunner ?? createAnalyzeRunner({ timeoutMs: cfg.ANALYZE_TIMEOUT_MS }),
+        inflight: new Set(),
+        log: (operation, fields) => {
+            if (cfg.LOG_LEVEL === 'error' && fields.status === 'ok')
+                return; // 静音成功日志(error level)
+            logSink(JSON.stringify({ time: Date.now(), level: 'info', operation, ...fields }));
+        },
+        metrics: deps.metrics ?? createMetrics(),
+    };
+    const server = createServer((req, res) => {
+        // 单点 finish-logger + metrics(09 Structured Logging/Metrics):operation + outcome + latency。只
+        // path/method/status/errorCode/durationMs —— 永不含 header/token/body/seed。
+        const started = Date.now();
+        res.on('finish', () => {
+            const path = (req.url ?? '/').split('?')[0] ?? '/';
+            if (path === '/metrics')
+                return; // 不给 /metrics scrape 自计/记日志
+            // 把唯一动态段(GET /v1/requests/{id})collapse 成稳定模板,operation 基数有界。
+            const operation = path.startsWith(REQUESTS_PREFIX)
+                ? 'highlevel.requests'
+                : `highlevel.${path.replace(/^\/+/, '').replace(/\//g, '.') || 'root'}`;
+            const status = res.statusCode < 400 ? 'ok' : 'failed';
+            const errorCode = res.__errorCode;
+            const durationMs = Date.now() - started;
+            ctx.log(operation, { status, errorCode, durationMs });
+            ctx.metrics.inc('highlevel_requests_total', { operation, status, errorCode });
+            ctx.metrics.observe('highlevel_request_duration_ms', durationMs);
+        });
+        route(ctx, req, res).catch(() => {
+            if (!res.headersSent) {
+                sendOutcome(res, {
+                    status: 500,
+                    body: { error: errorBody('network_error', 'internal error') },
+                    errorCode: 'network_error',
+                });
+            }
+        });
+    });
+    // 周期 sweep:回收已过 TTL 的终态记录(getRecord 只在访问时删,abandoned 终态否则常驻内存)。
+    // 间隔绑 TTL(Codex M9 Low:固定 5min 对 1min TTL 会多滞留 ~4min)——取 min(5min, max(30s, TTL/2))。
+    // unref → 不吊住进程;server 'close' 清掉(测试关 server 即停 timer,不泄漏)。
+    const sweepMs = Math.min(300_000, Math.max(30_000, Math.floor(cfg.REQUEST_TERMINAL_STATUS_TTL_MS / 2)));
+    const sweepTimer = setInterval(() => ctx.registry.sweepExpired(), sweepMs);
+    sweepTimer.unref?.();
+    server.on('close', () => clearInterval(sweepTimer));
+    return { server, ctx };
+}
+/**
+ * `bycli internal highlevel-http` 入口:load config → 装配 → bind 127.0.0.1。默认关闭(opt-in)。
+ * 绝不打印 token(只打印 listening 行)。**在 server 存活期间不 resolve**(等 'close'),这样 main.ts
+ * 的 `await runWrapperCli()` 会一直挂起、绝不 fall-through 到完整 CLI discovery。
+ */
+export async function runWrapperCli() {
+    const cfg = loadWrapperConfig();
+    // analyze 的 daemon-backed Page 经 daemon-client(模块加载时读 process.env.BYCLI_DAEMON_PORT)连回 daemon;
+    // 显式钉到 cfg.DAEMON_PORT,保证 Page 连的是 wrapper 配置的同一 daemon(Page 在首次 analyze 才懒加载)。
+    process.env.BYCLI_DAEMON_PORT = String(cfg.DAEMON_PORT);
+    const { server, ctx } = createWrapperApp(cfg);
+    // 在 server 存活期间不 resolve(阻止 main.ts fall-through);仅在 SIGTERM/SIGINT 优雅关闭后 resolve。
+    await new Promise((resolve, reject) => {
+        let closing = false;
+        const shutdown = () => {
+            if (closing)
+                return;
+            closing = true;
+            server.close(); // 停止接新连接
+            // 先 drain 在飞 analyze(其 finally closeWindow 释放 daemon Page lease),最多 SHUTDOWN_GRACE_MS,
+            // 再 resolve → main.ts process.exit;不再被硬切(Codex M9 Med)。超 grace 则放弃,靠 lease idle-expire。
+            void drainInflight(ctx.inflight, SHUTDOWN_GRACE_MS).finally(() => resolve());
+        };
+        server.once('error', reject);
+        process.once('SIGTERM', shutdown);
+        process.once('SIGINT', shutdown);
+        server.listen(cfg.PORT, cfg.HOST, () => {
+            process.stderr.write(JSON.stringify({ time: Date.now(), level: 'info', operation: 'highlevel.listening', status: 'ok', port: cfg.PORT }) + '\n');
+        });
+    });
+}

package/dist/src/recorder/http/wrapper.test.d.ts

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

package/dist/src/recorder/observability/logger.d.ts

@@ -0,0 +1,5 @@
+import { type Logger, type LogLevel } from '@sovovs/bycli-recorder-core';
+export type { Logger, LogLevel } from '@sovovs/bycli-recorder-core';
+export type { LogFields } from '@sovovs/bycli-recorder-core';
+/** daemon/runner structured logger: single-line JSON to stderr. Inject `sink` in tests. */
+export declare function createRecorderLogger(level: LogLevel, sink?: (line: string) => void): Logger;

package/dist/src/recorder/observability/logger.js

@@ -0,0 +1,13 @@
+// Structured logger for the daemon/runner recording path (#1a · 09 Structured Logging).
+//
+// The main repo keeps TWO loggers on purpose: `src/logger.ts` (human-facing emoji singleton,
+// 17 CLI consumers, unchanged) and THIS one — single-line JSON for the daemon/runner SERVICE path,
+// whose output goes to a detached process's stderr captured to daemon logs, never to an interactive
+// user. The formatter + by-construction redaction (LogFields = only 09 allowed fields) live in
+// recorder-core; this thin factory supplies the stderr sink that core deliberately omits to stay
+// IO-free. Reuses the exact same engine as dashboard-be's logger so daemon/be log shapes match.
+import { createLogger as createCoreLogger } from '@sovovs/bycli-recorder-core';
+/** daemon/runner structured logger: single-line JSON to stderr. Inject `sink` in tests. */
+export function createRecorderLogger(level, sink = (line) => process.stderr.write(line + '\n')) {
+    return createCoreLogger(level, { sink });
+}

package/dist/src/recorder/runner/config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Verify-runner config — read VERIFY_RUNNER_* from the environment (09 HighLevelConfig).
+ *
+ * The static range validation is the pure `validateRunnerConfig` in recorder-core (no
+ * process.env access, unit-tested there). This thin wrapper reads the env keys and applies
+ * the one env-side rule the pure layer can't: clamp `maxConcurrency` to the CPU count
+ * (09: "int, 1-CPU count"). A range error is surfaced as a thrown ConfigError (fail closed,
+ * 08: unsupported config fails before launch).
+ */
+import { type RunnerConfig, type TempCapacity } from '@sovovs/bycli-recorder-core';
+/**
+ * Resolve the verify-runner config from `env` (defaults to process.env). Missing/empty →
+ * default; out-of-range/non-integer → ConfigError. `maxConcurrency` is additionally clamped
+ * down to the CPU count (never below 1).
+ */
+export declare function resolveRunnerConfig(env?: NodeJS.ProcessEnv): RunnerConfig;
+/**
+ * Temp-store reap policy (M7b · 09:27-29 RecorderConfig). Read on the daemon side (the process
+ * that owns verify temp dirs) to drive startup reap + the periodic TTL sweep.
+ */
+export interface TempPolicy {
+    /** Periodic sweep threshold: a temp dir older than this is a leak (09: default 1h). */
+    tempTtlMs: number;
+    /** Startup reap age backstop: clean dirs older than this regardless of owner (09: default 24h). */
+    startupReapMaxAgeMs: number;
+    /** SIGTERM→SIGKILL grace when terminating a reaped child (09: default 1500ms). */
+    orphanKillGraceMs: number;
+}
+export declare function resolveTempCapacity(env?: NodeJS.ProcessEnv): TempCapacity;
+/**
+ * Resolve the temp-store reap policy from `env` (defaults to process.env). Missing/empty → default;
+ * out-of-range / non-integer → ConfigError (fail closed, consistent with resolveRunnerConfig).
+ */
+export declare function resolveTempPolicy(env?: NodeJS.ProcessEnv): TempPolicy;

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

@@ -0,0 +1,84 @@
+/**
+ * Verify-runner config — read VERIFY_RUNNER_* from the environment (09 HighLevelConfig).
+ *
+ * The static range validation is the pure `validateRunnerConfig` in recorder-core (no
+ * process.env access, unit-tested there). This thin wrapper reads the env keys and applies
+ * the one env-side rule the pure layer can't: clamp `maxConcurrency` to the CPU count
+ * (09: "int, 1-CPU count"). A range error is surfaced as a thrown ConfigError (fail closed,
+ * 08: unsupported config fails before launch).
+ */
+import * as os from 'node:os';
+import { validateRunnerConfig, validateTempCapacity } from '@sovovs/bycli-recorder-core';
+import { ConfigError } from '../../errors.js';
+const ENV_KEYS = {
+    maxConcurrency: 'VERIFY_RUNNER_MAX_CONCURRENCY',
+    queueLimit: 'HIGH_LEVEL_QUEUE_LIMIT',
+    stdoutLimitBytes: 'VERIFY_RUNNER_STDOUT_LIMIT_BYTES',
+    stderrLimitBytes: 'VERIFY_RUNNER_STDERR_LIMIT_BYTES',
+    jsonlLineLimit: 'VERIFY_RUNNER_JSONL_LINE_LIMIT',
+    timeoutMs: 'VERIFY_RUNNER_TIMEOUT_MS',
+    killGraceMs: 'VERIFY_RUNNER_KILL_GRACE_MS',
+};
+/**
+ * Resolve the verify-runner config from `env` (defaults to process.env). Missing/empty →
+ * default; out-of-range/non-integer → ConfigError. `maxConcurrency` is additionally clamped
+ * down to the CPU count (never below 1).
+ */
+export function resolveRunnerConfig(env = process.env) {
+    const raw = {};
+    for (const key of Object.keys(ENV_KEYS)) {
+        raw[key] = env[ENV_KEYS[key]];
+    }
+    const r = validateRunnerConfig(raw);
+    if (!r.ok)
+        throw new ConfigError(r.reason, 'Fix the VERIFY_RUNNER_* environment variable and retry.');
+    const cpus = Math.max(1, os.cpus().length || 1);
+    return { ...r.config, maxConcurrency: Math.min(r.config.maxConcurrency, cpus) };
+}
+const TEMP_POLICY_FIELDS = {
+    tempTtlMs: { key: 'RECORDER_TEMP_TTL_MS', def: 3_600_000, min: 60_000, max: 86_400_000 },
+    startupReapMaxAgeMs: { key: 'RECORDER_STARTUP_REAP_MAX_AGE_MS', def: 86_400_000, min: 60_000, max: 86_400_000 },
+    orphanKillGraceMs: { key: 'RECORDER_ORPHAN_KILL_GRACE_MS', def: 1_500, min: 100, max: 30_000 },
+};
+/**
+ * Temp-store capacity env keys (#1d · 09:33-36). The pure range/band-order validation is
+ * `validateTempCapacity` in recorder-core; this maps env key names → field names (mirroring
+ * resolveRunnerConfig) and fail-closes via ConfigError. The temp ROOT is restart-only (09:182):
+ * these are read at daemon startup, not hot-reloaded.
+ */
+const TEMP_CAPACITY_ENV_KEYS = {
+    maxBytes: 'RECORDER_TEMP_MAX_BYTES',
+    highWatermarkRatio: 'RECORDER_TEMP_HIGH_WATERMARK_RATIO',
+    lowWatermarkRatio: 'RECORDER_TEMP_LOW_WATERMARK_RATIO',
+};
+export function resolveTempCapacity(env = process.env) {
+    const raw = {};
+    for (const k of Object.keys(TEMP_CAPACITY_ENV_KEYS)) {
+        raw[k] = env[TEMP_CAPACITY_ENV_KEYS[k]];
+    }
+    const r = validateTempCapacity(raw);
+    if (!r.ok)
+        throw new ConfigError(r.reason, 'Fix the RECORDER_TEMP_* environment variable and retry.');
+    return r.capacity;
+}
+/**
+ * Resolve the temp-store reap policy from `env` (defaults to process.env). Missing/empty → default;
+ * out-of-range / non-integer → ConfigError (fail closed, consistent with resolveRunnerConfig).
+ */
+export function resolveTempPolicy(env = process.env) {
+    const out = {};
+    for (const k of Object.keys(TEMP_POLICY_FIELDS)) {
+        const f = TEMP_POLICY_FIELDS[k];
+        const raw = env[f.key];
+        if (raw === undefined || raw === '') {
+            out[k] = f.def;
+            continue;
+        }
+        const n = Number(raw);
+        if (!Number.isInteger(n) || n < f.min || n > f.max) {
+            throw new ConfigError(`${f.key}=${raw} is out of range [${f.min}, ${f.max}]`, `Fix the ${f.key} environment variable and retry.`);
+        }
+        out[k] = n;
+    }
+    return out;
+}

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

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

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

@@ -0,0 +1,79 @@
+export interface VerifyMarker {
+    requestId: string;
+    /** The runner child pid (backfilled into marker.json after spawn). */
+    pid: number | null;
+    /** The process that spawned the runner (daemon/CLI); stands in for 08's localServiceRunId. */
+    ownerPid: number | null;
+    startedAt: number;
+    tempRoot: string;
+    operation: 'verify';
+}
+/** Parse + validate marker.json. Returns null unless it is a well-formed verify marker. */
+export declare function parseVerifyMarker(raw: string): VerifyMarker | null;
+/** Does a live process's command line belong to THIS marker's runner? (pid-reuse guard) */
+export declare function cmdlineMatchesMarker(cmdline: string, marker: VerifyMarker): boolean;
+/** Containment: the dir must sit directly under tmpRoot and carry our prefix. */
+export declare function isReapableTempDir(dir: string, tmpRoot: string): boolean;
+/**
+ * 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 declare function isOrphan(marker: VerifyMarker, ownerAlive: boolean): boolean;
+/**
+ * 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 declare function isAgedOut(marker: VerifyMarker, now: number, maxAgeMs: number): boolean;
+/**
+ * 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 declare function effectiveLeakThresholdMs(maxAgeMs: number, minLeakAgeMs: number): number;
+export interface ProcProbe {
+    isAlive(pid: number): boolean;
+    cmdline(pid: number): string | null;
+    /** Process start time (epoch ms) for the live pid, or null if undeterminable (win32 / ps failure).
+     * Used for the owner pid-reuse guard (#6); optional so injected test probes need not implement it. */
+    startTime?(pid: number): number | null;
+    kill(pid: number, signal: NodeJS.Signals): void;
+}
+/**
+ * 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 declare function isOwnerPidReused(liveStartTime: number | null, runStartedAt: number, toleranceMs: number): boolean;
+export interface ReapResult {
+    scanned: number;
+    orphans: number;
+    agedOut: number;
+    killed: number;
+    deleted: number;
+}
+/**
+ * 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 declare function reapOrphanedVerifyRuns(opts?: {
+    tmpRoot?: string;
+    log?: (msg: string) => void;
+    graceMs?: number;
+    /** Age-based leak threshold (M7b). 0/undefined → orphan-only (pre-M7b behavior). */
+    maxAgeMs?: number;
+    /** Run hard-deadline floor (timeoutMs + killGraceMs); the age threshold is never lower than this
+     * so a still-running verify is never age-reaped (08 / M7b safety floor). */
+    minLeakAgeMs?: number;
+    /** Injectable clock (tests). */
+    now?: number;
+    probe?: ProcProbe;
+}): ReapResult;