@scotthuang/agent-knock-knock 0.11.0 → 0.11.2

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

@@ -1,41 +1,56 @@
-import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 import { codexLifecycleBehaviorProfile, supportedCodexLifecycleVersions } from "./codex-lifecycle-compatibility.js";
 import { 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 NO_FOLLOW_FLAG = typeof fs.constants.O_NOFOLLOW === "number"
     ? fs.constants.O_NOFOLLOW
     : 0;
 export class CodexStoreAdapter {
     codexHome;
     runCommand;
+    runSqliteThreadQuery;
+    sqliteCantOpenRetryDelaysMs;
+    sleep;
     maxSessions;
     constructor(options = {}) {
         this.codexHome = options.codexHome ?? path.join(os.homedir(), ".codex");
         this.runCommand = options.runCommand ?? runProcessCommand;
+        this.runSqliteThreadQuery = options.runSqliteThreadQuery ??
+            runCodexSqliteThreadQuery;
+        this.sqliteCantOpenRetryDelaysMs =
+            options.sqliteCantOpenRetryDelaysMs ??
+                DEFAULT_SQLITE_CANTOPEN_RETRY_DELAYS_MS;
+        this.sleep = options.sleep ?? waitForMilliseconds;
         this.maxSessions = options.maxSessions ?? 100;
     }
     async listThreadRows() {
-        const dbPath = latestStateDbPath(this.codexHome);
-        if (!dbPath) {
-            throw new Error("no Codex state sqlite database found");
-        }
-        const columns = this.queryJson(dbPath, "pragma table_info(threads)")
-            .map((column) => column.name);
-        if (!columns.includes("id") || !columns.includes("cwd")) {
-            throw new Error("Codex threads table is missing required id or cwd columns");
-        }
-        return this.queryJson(dbPath, buildThreadSelect(columns, this.maxSessions));
+        return this.queryThreadRows({ maxSessions: this.maxSessions });
     }
     async listThreadLifecycleCandidates(request) {
         assertCodexLifecycleCandidateRequest(request);
         const candidates = [];
-        for (const row of await this.listThreadRows()) {
+        const rows = await this.queryThreadRows({
+            maxSessions: this.maxSessions,
+            filters: {
+                cwd: path.resolve(request.cwd),
+                source: "cli",
+                archived: false,
+                modelProvider: request.modelProvider
+            }
+        });
+        for (const row of rows) {
             try {
                 const candidate = codexLifecycleCandidateFromRow({
                     row,
@@ -60,7 +75,11 @@ export class CodexStoreAdapter {
                 ? candidate.candidateToken
                 : candidate;
             if (token.schema !== "agent-knock-knock/thread-candidate-token" ||
-                token.version !== 1 ||
+                ![1, 2].includes(token.version) ||
+                (token.version === 1
+                    ? "sourceAgentVersion" in token
+                    : (!stringField(token.sourceAgentVersion) ||
+                        token.sourceAgentVersion === token.agentVersion)) ||
                 token.agent !== "codex" ||
                 token.source !== "codex_rollout" ||
                 token.agentVersion !== request.agentVersion ||
@@ -92,6 +111,7 @@ export class CodexStoreAdapter {
             }
             if (!sameThreadFileToken(current.fileToken, token.fileToken) ||
                 current.metadataFingerprint !== token.metadataFingerprint ||
+                current.sourceAgentVersion !== candidateSourceAgentVersion(token) ||
                 current.modelProvider !== token.modelProvider) {
                 return {
                     status: "changed",
@@ -112,15 +132,10 @@ export class CodexStoreAdapter {
         if (!NATIVE_THREAD_ID_PATTERN.test(nativeThreadId)) {
             throw new Error("Codex thread lookup requires an exact UUID");
         }
-        const dbPath = latestStateDbPath(this.codexHome);
-        if (!dbPath) {
-            return undefined;
-        }
-        const columns = this.queryJson(dbPath, "pragma table_info(threads)").map((column) => column.name);
-        if (!columns.includes("id") || !columns.includes("cwd")) {
-            throw new Error("Codex threads table is missing required id or cwd columns");
-        }
-        return this.queryJson(dbPath, buildThreadByIdSelect(columns, nativeThreadId))[0];
+        return (await this.queryThreadRows({
+            maxSessions: 1,
+            nativeThreadId
+        }))[0];
     }
     async readRollout(rolloutPath) {
         if (!fs.existsSync(rolloutPath)) {
@@ -163,14 +178,438 @@ export class CodexStoreAdapter {
             lsofOutput: result.stdout
         });
     }
-    queryJson(dbPath, sql) {
-        const result = this.runCommand("sqlite3", ["-readonly", "-json", dbPath, sql]);
-        if (result.status !== 0) {
-            throw new Error(result.stderr || result.error?.message || "sqlite3 query failed");
+    async queryThreadRows({ maxSessions, nativeThreadId, filters }) {
+        const dbPath = latestStateDbPath(this.codexHome);
+        if (!dbPath) {
+            throw new Error("no Codex state sqlite database found");
+        }
+        const baseline = inspectCodexSqliteFiles(dbPath);
+        assertStableCodexSqliteMain({
+            baseline,
+            current: baseline,
+            stage: "initial"
+        });
+        let lastFailure;
+        const attempts = this.sqliteCantOpenRetryDelaysMs.length + 1;
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+            if (attempt > 0) {
+                await this.sleep(this.sqliteCantOpenRetryDelaysMs[attempt - 1]);
+            }
+            const currentPath = latestStateDbPath(this.codexHome);
+            const before = inspectCodexSqliteFiles(currentPath ?? dbPath);
+            assertStableCodexSqliteMain({
+                baseline,
+                current: before,
+                stage: `readonly_attempt_${attempt + 1}`,
+                selectedPath: currentPath
+            });
+            let result;
+            try {
+                result = await this.runSqliteThreadQuery({
+                    dbPath,
+                    openMode: "readonly",
+                    maxSessions,
+                    nativeThreadId,
+                    filters
+                });
+            }
+            catch (error) {
+                const failedPath = latestStateDbPath(this.codexHome);
+                const failedFiles = inspectCodexSqliteFiles(failedPath ?? dbPath);
+                assertStableCodexSqliteMain({
+                    baseline,
+                    current: failedFiles,
+                    stage: `readonly_attempt_${attempt + 1}_failed`,
+                    selectedPath: failedPath
+                });
+                const failure = codexSqliteQueryFailure(error, {
+                    dbPath,
+                    stage: `readonly_attempt_${attempt + 1}`,
+                    files: failedFiles
+                });
+                if (!isSqliteCantOpen(failure)) {
+                    throw codexSqliteQueryDiagnosticError(failure);
+                }
+                lastFailure = failure;
+                continue;
+            }
+            const completedPath = latestStateDbPath(this.codexHome);
+            assertStableCodexSqliteMain({
+                baseline,
+                current: inspectCodexSqliteFiles(completedPath ?? dbPath),
+                stage: `readonly_attempt_${attempt + 1}_complete`,
+                selectedPath: completedPath
+            });
+            return validateCodexThreadQueryResult(result);
+        }
+        const currentPath = latestStateDbPath(this.codexHome);
+        const beforeMaterialization = inspectCodexSqliteFiles(currentPath ?? dbPath);
+        assertStableCodexSqliteMain({
+            baseline,
+            current: beforeMaterialization,
+            stage: "query_only_materialization",
+            selectedPath: currentPath
+        });
+        let materializedResult;
+        try {
+            materializedResult = await this.runSqliteThreadQuery({
+                dbPath,
+                openMode: "query_only",
+                maxSessions,
+                nativeThreadId,
+                filters
+            });
         }
-        return JSON.parse(result.stdout || "[]");
+        catch (error) {
+            const failedPath = latestStateDbPath(this.codexHome);
+            const failedFiles = inspectCodexSqliteFiles(failedPath ?? dbPath);
+            assertStableCodexSqliteMain({
+                baseline,
+                current: failedFiles,
+                stage: "query_only_materialization_failed",
+                selectedPath: failedPath
+            });
+            throw codexSqliteQueryDiagnosticError(codexSqliteQueryFailure(error, {
+                dbPath,
+                stage: "query_only_materialization",
+                files: failedFiles,
+                previousFailure: lastFailure
+            }));
+        }
+        const completedPath = latestStateDbPath(this.codexHome);
+        assertStableCodexSqliteMain({
+            baseline,
+            current: inspectCodexSqliteFiles(completedPath ?? dbPath),
+            stage: "query_only_materialization_complete",
+            selectedPath: completedPath
+        });
+        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.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;
@@ -178,7 +617,18 @@ export function latestStateDbPath(codexHome) {
     return fs.readdirSync(codexHome)
         .filter((entry) => /^state_\d+\.sqlite$/u.test(entry))
         .map((entry) => path.join(codexHome, entry))
-        .sort((left, right) => fs.statSync(right).mtimeMs - fs.statSync(left).mtimeMs)[0];
+        .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 = [];
@@ -420,7 +870,7 @@ function readCodexSessionMetadata(filePath, expectedDevice, expectedInode, pid)
         fs.closeSync(fd);
     }
 }
-export function buildThreadSelect(columns, limit) {
+export function buildThreadSelect(columns, limit, filters = {}) {
     const columnSet = new Set(columns);
     const updatedAtExpression = columnSet.has("updated_at_ms")
         ? "updated_at_ms"
@@ -441,7 +891,54 @@ export function buildThreadSelect(columns, limit) {
         columnSet.has("cli_version") ? "cli_version" : "null as cli_version",
         columnSet.has("name") ? "name" : "null as name"
     ].join(", ");
-    return `select ${select} from threads order by ${updatedAtExpression} desc limit ${Math.max(1, Math.floor(limit))}`;
+    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");
+    }
+    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]
+    ];
+    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)) {
@@ -473,9 +970,10 @@ function codexLifecycleCandidateFromRow({ row, codexHome, request }) {
         !path.isAbsolute(rowCwd) ||
         !path.isAbsolute(rolloutPath) ||
         rowSource !== "cli" ||
-        rowVersion !== request.agentVersion ||
-        row.archived === true ||
-        row.archived === 1 ||
+        !rowVersion ||
+        !(row.archived === undefined ||
+            row.archived === false ||
+            row.archived === 0) ||
         path.resolve(rowCwd) !== path.resolve(request.cwd) ||
         (request.modelProvider !== undefined &&
             rowModelProvider !== request.modelProvider)) {
@@ -491,7 +989,7 @@ function codexLifecycleCandidateFromRow({ row, codexHome, request }) {
         path.resolve(opened.metadata.cwd) !== path.resolve(request.cwd) ||
         opened.metadata.originator !== "codex-tui" ||
         opened.metadata.source !== "cli" ||
-        opened.metadata.cliVersion !== request.agentVersion ||
+        opened.metadata.cliVersion !== rowVersion ||
         (rowModelProvider !== undefined &&
             opened.metadata.modelProvider !== rowModelProvider) ||
         (request.modelProvider !== undefined &&
@@ -513,9 +1011,7 @@ function codexLifecycleCandidateFromRow({ row, codexHome, request }) {
         rolloutPath: opened.fileToken.path
     }))
         .digest("hex");
-    const candidateToken = {
-        schema: "agent-knock-knock/thread-candidate-token",
-        version: 1,
+    const tokenFields = {
         agent: "codex",
         nativeThreadId,
         cwd: path.resolve(request.cwd),
@@ -525,6 +1021,18 @@ function codexLifecycleCandidateFromRow({ row, codexHome, request }) {
         metadataFingerprint,
         modelProvider: opened.metadata.modelProvider
     };
+    const candidateToken = opened.metadata.cliVersion === request.agentVersion
+        ? {
+            schema: "agent-knock-knock/thread-candidate-token",
+            version: 1,
+            ...tokenFields
+        }
+        : {
+            schema: "agent-knock-knock/thread-candidate-token",
+            version: 2,
+            ...tokenFields,
+            sourceAgentVersion: opened.metadata.cliVersion
+        };
     return {
         agent: "codex",
         nativeThreadId,
@@ -533,6 +1041,7 @@ function codexLifecycleCandidateFromRow({ row, codexHome, request }) {
         rootInteractive: true,
         fileToken: opened.fileToken,
         agentVersion: request.agentVersion,
+        sourceAgentVersion: opened.metadata.cliVersion,
         title,
         preview,
         updatedAtMs,
@@ -541,6 +1050,9 @@ function codexLifecycleCandidateFromRow({ row, codexHome, request }) {
         candidateToken
     };
 }
+function candidateSourceAgentVersion(token) {
+    return token.version === 2 ? token.sourceAgentVersion : token.agentVersion;
+}
 function readCodexLifecycleMetadata({ codexHome, rolloutPath, nativeThreadId }) {
     const configuredRoot = path.resolve(codexHome, "sessions");
     const lexicalRelative = path.relative(configuredRoot, path.resolve(rolloutPath));