@scotthuang/agent-knock-knock 0.13.16 → 0.13.17

package/dist/src/codex-store-adapter.js

@@ -1,21 +1,17 @@
-import { spawn } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
+export { parseLsofOpenFiles, resolveCodexOpenRolloutIdentity, inspectCodexOpenRootRolloutInventory } from "./codex-open-rollout-inventory.js";
+import { inspectCodexOpenRootRolloutInventory, selectCodexOpenRolloutIdentity } from "./codex-open-rollout-inventory.js";
+export { runCodexSqliteThreadQuery, latestStateDbPath, buildThreadSelect, buildThreadByIdSelect } from "./codex-sqlite-thread-query.js";
+import { NATIVE_THREAD_ID_PATTERN, runCodexSqliteThreadQuery, validateCodexThreadQueryResult, inspectCodexSqliteFiles, assertStableCodexSqliteMain, codexSqliteQueryFailure, isSqliteCantOpen, codexSqliteQueryDiagnosticError, latestStateDbPath } from "./codex-sqlite-thread-query.js";
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { CodexTransientDuplicateOpenRootDescriptorsError } from "./agent-session-provider.js";
 import { isValidCodexAgentVersion } from "./codex-lifecycle-compatibility.js";
 import { codexThreadUsesLegacyRollout, discoverCodexProcesses } from "./codex-session-provider.js";
 import { SystemTerminalProcessSource, runProcessCommand } from "./terminal-process-source.js";
 export { parseLsofCwdMap, parsePsProcessSnapshots } from "./terminal-process-source.js";
-const NATIVE_THREAD_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
 const MAX_CODEX_SESSION_META_BYTES = 1024 * 1024;
-const MAX_SQLITE_QUERY_OUTPUT_BYTES = 10 * 1024 * 1024;
-const MAX_SQLITE_ERROR_OUTPUT_BYTES = 1024 * 1024;
-const SQLITE_QUERY_TIMEOUT_MS = 10_000;
 const DEFAULT_SQLITE_CANTOPEN_RETRY_DELAYS_MS = [25, 75, 150];
-const MAX_CODEX_OPEN_ROOT_ROLLOUTS = 128;
 const NO_FOLLOW_FLAG = typeof fs.constants.O_NOFOLLOW === "number"
     ? fs.constants.O_NOFOLLOW
     : 0;
@@ -317,796 +313,9 @@ export class CodexStoreAdapter {
         return validateCodexThreadQueryResult(materializedResult);
     }
 }
-class CodexSqliteSessionError extends Error {
-    status;
-    stage;
-    constructor({ message, status, stage }) {
-        super(message);
-        this.name = "CodexSqliteSessionError";
-        this.status = status;
-        this.stage = stage;
-    }
-}
-export async function runCodexSqliteThreadQuery(request) {
-    if (request.nativeThreadId && request.filters) {
-        throw new Error("Codex thread query cannot combine an exact UUID with lifecycle filters");
-    }
-    if (request.nativeThreadId &&
-        !NATIVE_THREAD_ID_PATTERN.test(request.nativeThreadId)) {
-        throw new Error("Codex thread lookup requires an exact UUID");
-    }
-    if (request.filters?.cwd && !path.isAbsolute(request.filters.cwd)) {
-        throw new Error("Codex lifecycle thread query requires an absolute cwd");
-    }
-    const nonce = randomUUID();
-    const controlColumn = "__akk_sqlite_control";
-    const schemaControl = `schema:${nonce}`;
-    const rowsControl = `rows:${nonce}`;
-    const schemaMarker = JSON.stringify([{ [controlColumn]: schemaControl }]);
-    const rowsMarker = JSON.stringify([{ [controlColumn]: rowsControl }]);
-    const databaseArgument = request.openMode === "query_only"
-        ? sqliteReadWriteUri(request.dbPath)
-        : request.dbPath;
-    const args = ["-batch", "-bail", "-json"];
-    if (request.openMode === "readonly") {
-        args.push("-readonly");
-    }
-    const parameterCommands = sqliteThreadFilterParameterCommands(request.filters);
-    for (const command of parameterCommands) {
-        args.push("-cmd", command);
-    }
-    if (request.openMode === "query_only") {
-        // SQLite may materialize WAL/SHM bookkeeping on this mode=rw connection,
-        // while query_only forbids business SQL writes for the AKK session.
-        // Parameter initialization, when needed, only creates a TEMP table and
-        // must precede query_only because SQLite also applies it to TEMP writes.
-        args.push("-cmd", "PRAGMA query_only=ON");
-    }
-    args.push(databaseArgument);
-    return new Promise((resolve, reject) => {
-        const child = spawn("sqlite3", args, {
-            stdio: ["pipe", "pipe", "pipe"]
-        });
-        let phase = "schema";
-        let output = "";
-        let stderr = "";
-        let result;
-        let authoritativeColumns = [];
-        let terminalError;
-        let settled = false;
-        const timeout = setTimeout(() => {
-            if (!terminalError) {
-                terminalError = new CodexSqliteSessionError({
-                    message: `sqlite3 thread query timed out after ${SQLITE_QUERY_TIMEOUT_MS}ms`,
-                    status: null,
-                    stage: phase
-                });
-            }
-            child.kill("SIGKILL");
-        }, SQLITE_QUERY_TIMEOUT_MS);
-        const stopWithError = (error) => {
-            if (!terminalError) {
-                terminalError = error instanceof CodexSqliteSessionError
-                    ? error
-                    : new CodexSqliteSessionError({
-                        message: error.message,
-                        status: null,
-                        stage: phase
-                    });
-            }
-            child.kill("SIGKILL");
-        };
-        const appendOutput = (current, chunk, limit) => {
-            const next = current + chunk;
-            if (Buffer.byteLength(next, "utf8") > limit) {
-                throw new Error(`sqlite3 ${phase} output exceeded ${limit} bytes`);
-            }
-            return next;
-        };
-        const parseArray = (text, label) => {
-            if (!text.trim()) {
-                return [];
-            }
-            const parsed = JSON.parse(text);
-            if (!Array.isArray(parsed)) {
-                throw new Error(`sqlite3 ${label} output was not a JSON array`);
-            }
-            return parsed;
-        };
-        const writeRowsQuery = (columns) => {
-            validateCodexThreadColumns(columns);
-            authoritativeColumns = columns;
-            const sql = request.nativeThreadId
-                ? buildThreadByIdSelect(columns, request.nativeThreadId)
-                : buildThreadSelect(columns, request.maxSessions, request.filters);
-            phase = "rows";
-            child.stdin.write(`${sql};\nselect '${rowsControl}' as "${controlColumn}";\n`);
-        };
-        const consumeOutput = () => {
-            if (phase === "schema") {
-                const markerIndex = output.indexOf(schemaMarker);
-                if (markerIndex < 0) {
-                    return;
-                }
-                const schema = parseArray(output.slice(0, markerIndex).trim(), "schema");
-                const columns = schema
-                    .map((column) => typeof column.name === "string" ? column.name : "")
-                    .filter(Boolean);
-                output = output.slice(markerIndex + schemaMarker.length).trimStart();
-                phase = "schema_hook";
-                void Promise.resolve(request.afterSchema?.(columns))
-                    .then(() => writeRowsQuery(columns))
-                    .catch((error) => stopWithError(error instanceof Error ? error : new Error(String(error))));
-            }
-            if (phase === "rows") {
-                const markerIndex = output.indexOf(rowsMarker);
-                if (markerIndex < 0) {
-                    return;
-                }
-                const rows = parseArray(output.slice(0, markerIndex).trim(), "rows");
-                result = {
-                    columns: authoritativeColumns,
-                    rows
-                };
-                phase = "complete";
-                child.stdin.end("COMMIT;\n.quit\n");
-            }
-        };
-        child.stdout.setEncoding("utf8");
-        child.stderr.setEncoding("utf8");
-        child.stdout.on("data", (chunk) => {
-            try {
-                output = appendOutput(output, chunk, MAX_SQLITE_QUERY_OUTPUT_BYTES);
-                consumeOutput();
-            }
-            catch (error) {
-                stopWithError(error instanceof Error ? error : new Error(String(error)));
-            }
-        });
-        child.stderr.on("data", (chunk) => {
-            try {
-                stderr = appendOutput(stderr, chunk, MAX_SQLITE_ERROR_OUTPUT_BYTES);
-            }
-            catch (error) {
-                stopWithError(error instanceof Error ? error : new Error(String(error)));
-            }
-        });
-        child.on("error", (error) => {
-            if (!terminalError) {
-                terminalError = new CodexSqliteSessionError({
-                    message: error.message,
-                    status: null,
-                    stage: phase
-                });
-            }
-        });
-        child.stdin.on("error", (error) => {
-            if (!terminalError && phase !== "complete") {
-                terminalError = error;
-            }
-        });
-        child.on("close", (status) => {
-            clearTimeout(timeout);
-            if (settled) {
-                return;
-            }
-            settled = true;
-            if (terminalError) {
-                reject(terminalError);
-                return;
-            }
-            if (status !== 0) {
-                reject(new CodexSqliteSessionError({
-                    message: stderr.trim() || `sqlite3 exited with status ${status ?? "unknown"}`,
-                    status,
-                    stage: phase
-                }));
-                return;
-            }
-            if (!result || phase !== "complete") {
-                reject(new CodexSqliteSessionError({
-                    message: "sqlite3 exited before the thread query protocol completed",
-                    status,
-                    stage: phase
-                }));
-                return;
-            }
-            resolve(result);
-        });
-        child.stdin.write(`BEGIN;\npragma table_info(threads);\n` +
-            `select '${schemaControl}' as "${controlColumn}";\n`);
-    });
-}
-function validateCodexThreadQueryResult(result) {
-    validateCodexThreadColumns(result.columns);
-    return result.columns.includes("history_mode")
-        ? result.rows.map((row) => ({ ...row, history_mode: row.history_mode ?? null }))
-        : result.rows;
-}
-function validateCodexThreadColumns(columns) {
-    if (!columns.includes("id") || !columns.includes("cwd")) {
-        throw new Error("Codex threads table is missing required id or cwd columns");
-    }
-}
-function sqliteReadWriteUri(dbPath) {
-    const uri = pathToFileURL(path.resolve(dbPath));
-    uri.searchParams.set("mode", "rw");
-    return uri.href;
-}
 function waitForMilliseconds(milliseconds) {
     return new Promise((resolve) => setTimeout(resolve, Math.max(0, milliseconds)));
 }
-function inspectCodexSqliteFiles(dbPath) {
-    return {
-        dbPath: path.resolve(dbPath),
-        main: inspectCodexSqliteFile(dbPath),
-        wal: inspectCodexSqliteFile(`${dbPath}-wal`),
-        shm: inspectCodexSqliteFile(`${dbPath}-shm`)
-    };
-}
-function inspectCodexSqliteFile(filePath) {
-    try {
-        const stat = fs.statSync(filePath);
-        return {
-            path: path.resolve(filePath),
-            exists: true,
-            kind: stat.isFile()
-                ? "file"
-                : stat.isDirectory()
-                    ? "directory"
-                    : "other",
-            device: String(stat.dev),
-            inode: String(stat.ino),
-            size: stat.size,
-            mtimeMs: stat.mtimeMs
-        };
-    }
-    catch (error) {
-        const code = typeof error === "object" && error !== null && "code" in error
-            ? String(error.code)
-            : undefined;
-        return {
-            path: path.resolve(filePath),
-            exists: false,
-            ...(code ? { errorCode: code } : {})
-        };
-    }
-}
-function assertStableCodexSqliteMain({ baseline, current, stage, selectedPath = current.dbPath }) {
-    const samePath = Boolean(selectedPath &&
-        path.resolve(selectedPath) === baseline.dbPath &&
-        current.dbPath === baseline.dbPath);
-    const sameFile = Boolean(baseline.main.exists &&
-        baseline.main.kind === "file" &&
-        current.main.exists &&
-        current.main.kind === "file" &&
-        baseline.main.device === current.main.device &&
-        baseline.main.inode === current.main.inode);
-    if (samePath && sameFile) {
-        return;
-    }
-    throw new Error(`Codex SQLite main database changed during ${stage}; refusing stale ` +
-        `thread discovery (selected_db=${selectedPath ?? "missing"}, ` +
-        `baseline_db=${baseline.dbPath}, current_db=${current.dbPath}; ` +
-        `${formatCodexSqliteFiles(current)})`);
-}
-function codexSqliteQueryFailure(error, context) {
-    const errorRecord = typeof error === "object" && error !== null
-        ? error
-        : undefined;
-    const reportedStatus = typeof errorRecord?.status === "number"
-        ? errorRecord.status
-        : null;
-    const reportedStage = typeof errorRecord?.stage === "string"
-        ? errorRecord.stage
-        : undefined;
-    return {
-        dbPath: path.resolve(context.dbPath),
-        stage: reportedStage
-            ? `${context.stage}:${reportedStage}`
-            : context.stage,
-        status: reportedStatus !== null && Number.isInteger(reportedStatus)
-            ? reportedStatus
-            : null,
-        detail: error instanceof Error ? error.message : String(error),
-        files: context.files,
-        previousFailure: context.previousFailure
-    };
-}
-function isSqliteCantOpen(failure) {
-    return failure.status === 14 ||
-        /(?:SQLITE_CANTOPEN|unable to open database file|\(14\))/iu.test(failure.detail);
-}
-function codexSqliteQueryDiagnosticError(failure) {
-    const prior = failure.previousFailure
-        ? `; previous=[stage=${failure.previousFailure.stage},status=` +
-            `${failure.previousFailure.status ?? "unknown"},` +
-            `${formatCodexSqliteFiles(failure.previousFailure.files)}]`
-        : "";
-    return new Error(`Codex SQLite thread query failed ` +
-        `(stage=${failure.stage}, db=${failure.dbPath}, ` +
-        `status=${failure.status ?? "unknown"}${prior}; ` +
-        `${formatCodexSqliteFiles(failure.files)}): ` +
-        failure.detail.replace(/\s+/gu, " ").trim());
-}
-function formatCodexSqliteFiles(snapshot) {
-    return [
-        ["main", snapshot.main],
-        ["wal", snapshot.wal],
-        ["shm", snapshot.shm]
-    ].map(([label, value]) => {
-        const file = value;
-        if (!file.exists) {
-            return `${label}=missing${file.errorCode ? `(${file.errorCode})` : ""}`;
-        }
-        return `${label}=${file.kind}(dev=${file.device},ino=${file.inode},` +
-            `size=${file.size},mtime_ms=${Math.trunc(file.mtimeMs ?? 0)})`;
-    }).join(" ");
-}
-export function latestStateDbPath(codexHome) {
-    if (!fs.existsSync(codexHome)) {
-        return undefined;
-    }
-    return fs.readdirSync(codexHome)
-        .filter((entry) => /^state_\d+\.sqlite$/u.test(entry))
-        .map((entry) => path.join(codexHome, entry))
-        .flatMap((filePath) => {
-        try {
-            const stat = fs.statSync(filePath);
-            return stat.isFile() ? [{ filePath, mtimeMs: stat.mtimeMs }] : [];
-        }
-        catch {
-            // Codex may rotate a versioned state database while discovery is
-            // enumerating it. The caller will re-resolve and validate identity.
-            return [];
-        }
-    })
-        .sort((left, right) => right.mtimeMs - left.mtimeMs)[0]?.filePath;
-}
-export function parseLsofOpenFiles(text) {
-    const records = [];
-    let current;
-    const flush = () => {
-        if (current) {
-            records.push(current);
-        }
-    };
-    for (const line of text.split(/\r?\n/u)) {
-        if (line.startsWith("f")) {
-            flush();
-            current = { fd: line.slice(1) };
-        }
-        else if (current && line.startsWith("t")) {
-            current.type = line.slice(1);
-        }
-        else if (current && line.startsWith("D")) {
-            current.device = line.slice(1);
-        }
-        else if (current && line.startsWith("i")) {
-            current.inode = line.slice(1);
-        }
-        else if (current && line.startsWith("n")) {
-            current.path = line.slice(1);
-        }
-    }
-    flush();
-    return records;
-}
-export function resolveCodexOpenRolloutIdentity({ codexHome, pid, cwd, preferredSessionId, allowedCompanionIdentity, allowedAdditionalIdentities, processBirth, lsofOutput }) {
-    const inventory = inspectCodexOpenRootRolloutInventory({
-        codexHome,
-        pid,
-        cwd,
-        processBirth,
-        lsofOutput
-    });
-    return selectCodexOpenRolloutIdentity({
-        inventory,
-        preferredSessionId,
-        allowedCompanionIdentity,
-        allowedAdditionalIdentities
-    });
-}
-export function inspectCodexOpenRootRolloutInventory({ codexHome, pid, cwd, processBirth, lsofOutput }) {
-    if (!Number.isSafeInteger(pid) || pid <= 1 || !processBirth.trim()) {
-        throw new Error("Codex rollout inventory requires an exact process incarnation");
-    }
-    const rolloutFiles = parseLsofOpenFiles(lsofOutput).filter((openFile) => {
-        if (!openFile.path) {
-            return false;
-        }
-        const openPath = openFile.path.replace(/\s+\(deleted\)$/u, "");
-        return /^rollout-.*\.jsonl$/u.test(path.basename(openPath));
-    });
-    if (rolloutFiles.length > MAX_CODEX_OPEN_ROOT_ROLLOUTS) {
-        throw new Error(`Codex process ${pid} has too many open rollout files to inspect safely`);
-    }
-    const processUuid = `codex-pid:${pid}:birth:${processBirth}`;
-    const expectedCwd = cwd ? path.resolve(cwd) : undefined;
-    // An absent sessions directory is only evidence of a virgin process when
-    // lsof also reported no rollout descriptor at all. Once a rollout FD exists,
-    // every descriptor and every root/subagent classification must be verified.
-    if (rolloutFiles.length === 0) {
-        return codexOpenRootRolloutInventoryResult({
-            pid,
-            processUuid,
-            processBirth,
-            cwd: expectedCwd,
-            roots: []
-        });
-    }
-    const configuredSessionsRoot = path.join(codexHome, "sessions");
-    let sessionsRoot;
-    try {
-        sessionsRoot = fs.realpathSync(configuredSessionsRoot);
-    }
-    catch {
-        throw new Error(`Codex process ${pid} has open rollout files but CODEX_HOME/sessions is unavailable`);
-    }
-    const identities = [];
-    for (const openFile of rolloutFiles) {
-        const openPath = openFile.path;
-        const descriptorPath = openPath.replace(/\s+\(deleted\)$/u, "");
-        const lexicalRelative = path.relative(path.resolve(configuredSessionsRoot), path.resolve(descriptorPath));
-        if (!lexicalRelative ||
-            lexicalRelative.startsWith("..") ||
-            path.isAbsolute(lexicalRelative)) {
-            throw new Error(`Codex process ${pid} has an open rollout outside CODEX_HOME/sessions`);
-        }
-        if (openFile.type !== "REG" ||
-            !openFile.fd ||
-            !openFile.device ||
-            !openFile.inode ||
-            /\s+\(deleted\)$/u.test(openPath)) {
-            throw new Error(`Codex process ${pid} has an unverifiable open rollout descriptor`);
-        }
-        let realPath;
-        try {
-            realPath = fs.realpathSync(descriptorPath);
-        }
-        catch {
-            throw new Error(`Codex process ${pid} has an unreadable open rollout descriptor`);
-        }
-        const relative = path.relative(sessionsRoot, realPath);
-        if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-            throw new Error(`Codex process ${pid} has an open rollout outside CODEX_HOME/sessions`);
-        }
-        const expectedDevice = parseLsofInteger(openFile.device);
-        const expectedInode = parseLsofInteger(openFile.inode);
-        const metadata = readCodexSessionMetadata(descriptorPath, expectedDevice, expectedInode, pid);
-        let confirmedRealPath;
-        try {
-            confirmedRealPath = fs.realpathSync(descriptorPath);
-        }
-        catch {
-            throw new Error(`Codex process ${pid} has an unreadable open rollout descriptor`);
-        }
-        if (confirmedRealPath !== realPath) {
-            throw new Error(`Codex process ${pid} rollout path changed while it was being verified`);
-        }
-        const filenameSessionId = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/iu
-            .exec(path.basename(descriptorPath))?.[1];
-        if (!metadata || metadata.id !== filenameSessionId) {
-            throw new Error(`Codex process ${pid} has invalid rollout session metadata`);
-        }
-        if (typeof metadata.source === "object" &&
-            metadata.source !== null &&
-            "subagent" in metadata.source) {
-            continue;
-        }
-        if (metadata.originator !== "codex-tui" ||
-            metadata.source !== "cli" ||
-            (expectedCwd && path.resolve(metadata.cwd) !== expectedCwd)) {
-            throw new Error(`Codex process ${pid} has an indeterminate open root rollout`);
-        }
-        identities.push({
-            sessionId: metadata.id,
-            processUuid,
-            processBirth,
-            rollout: {
-                fd: openFile.fd,
-                device: openFile.device,
-                inode: openFile.inode,
-                path: confirmedRealPath
-            },
-            evidence: "codex_open_root_rollout"
-        });
-    }
-    if (identities.length === 0) {
-        throw new Error(`Codex process ${pid} has open rollout files but no exact TUI root identity`);
-    }
-    identities.sort((left, right) => left.sessionId.localeCompare(right.sessionId) ||
-        left.rollout.path.localeCompare(right.rollout.path) ||
-        left.rollout.fd.localeCompare(right.rollout.fd));
-    const duplicateDisposition = classifyCodexOpenRootDuplicates(identities);
-    if (duplicateDisposition === "transient_exact_descriptor_duplicate") {
-        throw new CodexTransientDuplicateOpenRootDescriptorsError(pid);
-    }
-    if (duplicateDisposition === "conflicting_identity") {
-        throw new Error(`Codex process ${pid} has duplicate open root rollout identities`);
-    }
-    return codexOpenRootRolloutInventoryResult({
-        pid,
-        processUuid,
-        processBirth,
-        cwd: expectedCwd,
-        roots: identities
-    });
-}
-function classifyCodexOpenRootDuplicates(identities) {
-    let exactDescriptorDuplicate = false;
-    for (let leftIndex = 0; leftIndex < identities.length; leftIndex += 1) {
-        const left = identities[leftIndex];
-        for (let rightIndex = leftIndex + 1; rightIndex < identities.length; rightIndex += 1) {
-            const right = identities[rightIndex];
-            const sameSession = left.sessionId === right.sessionId;
-            const sameFile = left.rollout.device === right.rollout.device &&
-                left.rollout.inode === right.rollout.inode;
-            if (!sameSession && !sameFile) {
-                continue;
-            }
-            const exactRolloutWithDistinctDescriptors = sameSession &&
-                sameFile &&
-                left.processUuid === right.processUuid &&
-                left.processBirth === right.processBirth &&
-                left.rollout.path === right.rollout.path &&
-                left.rollout.fd !== right.rollout.fd;
-            if (!exactRolloutWithDistinctDescriptors) {
-                return "conflicting_identity";
-            }
-            exactDescriptorDuplicate = true;
-        }
-    }
-    return exactDescriptorDuplicate
-        ? "transient_exact_descriptor_duplicate"
-        : "none";
-}
-function codexOpenRootRolloutInventoryResult({ pid, processUuid, processBirth, cwd, roots }) {
-    const authority = {
-        schema: "agent-knock-knock/codex-open-root-rollout-inventory",
-        version: 1,
-        pid,
-        processUuid,
-        processBirth,
-        ...(cwd ? { cwd } : {}),
-        roots
-    };
-    const inventoryFingerprint = createHash("sha256")
-        .update(JSON.stringify(authority))
-        .digest("hex");
-    if (roots.length === 0) {
-        return {
-            ...authority,
-            status: "verified_absent",
-            roots: [],
-            inventoryFingerprint
-        };
-    }
-    if (roots.length === 1) {
-        return {
-            ...authority,
-            status: "resolved",
-            roots: [roots[0]],
-            inventoryFingerprint
-        };
-    }
-    return {
-        ...authority,
-        status: "unbound",
-        reason: "multiple_open_root_rollouts",
-        inventoryFingerprint
-    };
-}
-function selectCodexOpenRolloutIdentity({ inventory, preferredSessionId, allowedCompanionIdentity, allowedAdditionalIdentities }) {
-    const pid = inventory.pid;
-    const identities = inventory.roots;
-    if (identities.length === 0) {
-        return undefined;
-    }
-    if (preferredSessionId) {
-        const preferred = identities.filter((identity) => identity.sessionId === preferredSessionId);
-        if (preferred.length > 1) {
-            throw new Error(`Codex process ${pid} has multiple open root rollouts for preferred ` +
-                `session ${preferredSessionId}`);
-        }
-        if (allowedCompanionIdentity) {
-            const allowedConstraints = [
-                allowedCompanionIdentity,
-                ...(allowedAdditionalIdentities ?? [])
-            ];
-            const allowedMatches = [];
-            for (const constraint of allowedConstraints) {
-                const matches = identities.filter((identity) => sameActiveCodexIdentity(identity, constraint));
-                if (matches.length > 1) {
-                    throw new Error(`Codex process ${pid} has multiple open root rollouts for an ` +
-                        "allowed companion session");
-                }
-                if (matches[0] && !allowedMatches.includes(matches[0])) {
-                    allowedMatches.push(matches[0]);
-                }
-            }
-            const unexpected = identities.filter((identity) => identity !== preferred[0] && !allowedMatches.includes(identity));
-            if (unexpected.length > 0) {
-                throw new Error(`Codex process ${pid} has an unexpected open root rollout outside ` +
-                    "the preferred and exact companion identities");
-            }
-            if (preferred.length === 1) {
-                return preferred[0];
-            }
-            const primaryCompanion = identities.find((identity) => sameActiveCodexIdentity(identity, allowedCompanionIdentity));
-            if (primaryCompanion) {
-                return primaryCompanion;
-            }
-            if (allowedMatches.length > 0) {
-                // The immediately preceding rollout can close while an older,
-                // independently verified managed ancestor remains open. Constraint
-                // order is authoritative and deterministic; unknown roots were
-                // rejected above, so the first surviving exact companion is safe
-                // process-incarnation evidence for a fresh status-card proof.
-                return allowedMatches[0];
-            }
-            throw new Error(`Codex process ${pid} has neither the preferred session nor an ` +
-                "exact managed companion rollout open");
-        }
-        else if (preferred.length === 1 && identities.length === 1) {
-            return preferred[0];
-        }
-        else {
-            throw new Error(`Codex process ${pid} does not have the preferred session as its ` +
-                "sole open root rollout");
-        }
-    }
-    if (identities.length !== 1) {
-        throw new Error(`Codex process ${pid} has ${identities.length} open root rollout files; ` +
-            "the foreground native session is ambiguous");
-    }
-    return identities[0];
-}
-function sameActiveCodexIdentity(left, right) {
-    return Boolean(left.sessionId === right.sessionId &&
-        left.processUuid === right.processUuid &&
-        left.processBirth === right.processBirth &&
-        left.rollout?.fd === right.rollout?.fd &&
-        left.rollout?.device === right.rollout?.device &&
-        left.rollout?.inode === right.rollout?.inode &&
-        left.rollout?.path === right.rollout?.path);
-}
-function parseLsofInteger(value) {
-    try {
-        return BigInt(value);
-    }
-    catch {
-        return -1n;
-    }
-}
-function readCodexSessionMetadata(filePath, expectedDevice, expectedInode, pid) {
-    let fd;
-    try {
-        fd = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
-    }
-    catch {
-        throw new Error(`Codex process ${pid} has an unreadable open rollout descriptor`);
-    }
-    try {
-        const stat = fs.fstatSync(fd, { bigint: true });
-        if (!stat.isFile() ||
-            stat.dev !== expectedDevice ||
-            stat.ino !== expectedInode) {
-            throw new Error(`Codex process ${pid} rollout descriptor no longer matches its file`);
-        }
-        const buffer = Buffer.alloc(1024 * 1024);
-        const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, 0);
-        const text = buffer.subarray(0, bytesRead).toString("utf8");
-        const newline = text.indexOf("\n");
-        if (newline < 0 && bytesRead === buffer.length) {
-            throw new Error(`Codex session metadata line is too large: ${filePath}`);
-        }
-        const parsed = JSON.parse(newline >= 0 ? text.slice(0, newline) : text);
-        const payload = parsed?.type === "session_meta" ? parsed.payload : undefined;
-        if (typeof payload?.id !== "string" ||
-            typeof payload?.cwd !== "string" ||
-            typeof payload?.originator !== "string" ||
-            !codexThreadUsesLegacyRollout(payload)) {
-            return undefined;
-        }
-        return {
-            id: payload.id,
-            cwd: payload.cwd,
-            originator: payload.originator,
-            source: payload.source
-        };
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-}
-export function buildThreadSelect(columns, limit, filters = {}) {
-    const columnSet = new Set(columns);
-    const updatedAtExpression = columnSet.has("updated_at_ms")
-        ? "updated_at_ms"
-        : columnSet.has("updated_at")
-            ? "updated_at * 1000"
-            : "0";
-    const select = [
-        "id",
-        "cwd",
-        columnSet.has("rollout_path") ? "rollout_path" : "null as rollout_path",
-        columnSet.has("title") ? "title" : "null as title",
-        columnSet.has("preview") ? "preview" : "null as preview",
-        columnSet.has("first_user_message") ? "first_user_message" : "null as first_user_message",
-        columnSet.has("updated_at_ms") ? "updated_at_ms" : columnSet.has("updated_at") ? "updated_at * 1000 as updated_at_ms" : "null as updated_at_ms",
-        columnSet.has("archived") ? "archived" : "0 as archived",
-        columnSet.has("source") ? "source" : "null as source",
-        columnSet.has("model_provider") ? "model_provider" : "null as model_provider",
-        columnSet.has("cli_version") ? "cli_version" : "null as cli_version",
-        columnSet.has("name") ? "name" : "null as name",
-        columnSet.has("history_mode") ? "history_mode" : "'legacy' as history_mode"
-    ].join(", ");
-    const predicates = [];
-    if (filters.cwd !== undefined) {
-        predicates.push("cwd collate binary = :akk_cwd");
-    }
-    if (filters.source !== undefined) {
-        predicates.push(columnSet.has("source")
-            ? "source collate binary = :akk_source"
-            : "0 = 1");
-    }
-    if (filters.archived !== undefined) {
-        if (columnSet.has("archived")) {
-            predicates.push(`archived = ${filters.archived ? "1" : "0"}`);
-        }
-        else if (filters.archived) {
-            predicates.push("0 = 1");
-        }
-    }
-    if (filters.modelProvider !== undefined) {
-        predicates.push(columnSet.has("model_provider")
-            ? "model_provider collate binary = :akk_model_provider"
-            : "0 = 1");
-    }
-    if (filters.historyMode !== undefined) {
-        if (columnSet.has("history_mode")) {
-            predicates.push("history_mode collate binary = :akk_history_mode");
-        }
-        else if (filters.historyMode !== "legacy") {
-            predicates.push("0 = 1");
-        }
-    }
-    const where = predicates.length > 0
-        ? ` where ${predicates.join(" and ")}`
-        : "";
-    const deterministicTieBreak = predicates.length > 0 ? ", id desc" : "";
-    return `select ${select} from threads${where} order by ${updatedAtExpression} desc${deterministicTieBreak} limit ${Math.max(1, Math.floor(limit))}`;
-}
-function sqliteThreadFilterParameterCommands(filters) {
-    if (!filters) {
-        return [];
-    }
-    const values = [
-        ["akk_cwd", filters.cwd],
-        ["akk_source", filters.source],
-        ["akk_model_provider", filters.modelProvider],
-        ["akk_history_mode", filters.historyMode]
-    ];
-    const present = values.filter((entry) => entry[1] !== undefined);
-    if (present.length === 0) {
-        return [];
-    }
-    return [
-        ".parameter init",
-        ...present.map(([name, value]) => {
-            const hex = Buffer.from(value, "utf8").toString("hex");
-            return `.parameter set :${name} "CAST(X'${hex}' AS TEXT)"`;
-        })
-    ];
-}
-export function buildThreadByIdSelect(columns, nativeThreadId) {
-    if (!NATIVE_THREAD_ID_PATTERN.test(nativeThreadId)) {
-        throw new Error("Codex thread lookup requires an exact UUID");
-    }
-    const base = buildThreadSelect(columns, 1);
-    return base.replace(" from threads order by ", ` from threads where id = '${nativeThreadId.toLowerCase()}' order by `);
-}
 function assertCodexLifecycleCandidateRequest(request) {
     if (!isValidCodexAgentVersion(request.agentVersion)) {
         throw new Error("Codex lifecycle candidate discovery requires a complete x.y.z agent version");