@pasko70/pibo 3.5.0 → 3.5.1

package/dist/data/storage-maintenance.js

@@ -0,0 +1,344 @@
+import { fork } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { appendFileSync, existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { fileURLToPath } from "node:url";
+const ROW_SAMPLE_LIMIT = 10_000;
+const TABLE_LIMIT = 64;
+const DEFAULT_DB_WARN_BYTES = 8 * 1024 ** 3;
+const DEFAULT_WAL_WARN_BYTES = 256 * 1024 ** 2;
+const DEFAULT_PAYLOAD_WARN_BYTES = 8 * 1024 ** 3;
+const MAINTENANCE_LOG_SUFFIX = ".maintenance.jsonl";
+export function inspectStorageStatus(input) {
+    const path = resolve(input.path);
+    const thresholds = {
+        databaseBytes: validThreshold(input.databaseWarnBytes, DEFAULT_DB_WARN_BYTES),
+        walBytes: validThreshold(input.walWarnBytes, DEFAULT_WAL_WARN_BYTES),
+        payloadBytes: validThreshold(input.payloadWarnBytes, DEFAULT_PAYLOAD_WARN_BYTES),
+    };
+    if (!existsSync(path))
+        return { resultType: "storage.status", readOnly: true, path, exists: false, health: "degraded", sizes: { database: 0, wal: 0, shm: 0, payloadStoreMetadataSample: 0, payloadStoreSampleComplete: true }, pages: { pageSize: 0, pageCount: 0, freelistCount: 0, freelistRatio: 0 }, wal: { busy: 0, logPages: 0, checkpointedPages: 0, pressure: false }, rows: [], payloads: { rows: 0, rowsComplete: true, sampledRows: 0, referencedRows: 0, metadataOrphans: 0, brokenReferences: 0, integrityComplete: true }, thresholds, last: {}, warnings: ["Database does not exist"] };
+    const db = new DatabaseSync(path, { readOnly: true });
+    try {
+        db.exec("PRAGMA busy_timeout = 50");
+        const pageSize = pragmaNumber(db, "page_size"), pageCount = pragmaNumber(db, "page_count"), freelistCount = pragmaNumber(db, "freelist_count");
+        const walRow = { busy: 0, logPages: pageSize ? Math.ceil(fileSize(`${path}-wal`) / pageSize) : 0, checkpointedPages: 0 };
+        const schemas = db.prepare("SELECT name, type FROM sqlite_schema WHERE type IN ('table','index') AND name NOT LIKE 'sqlite_%' ORDER BY CASE type WHEN 'table' THEN 0 ELSE 1 END, name LIMIT ?").all(TABLE_LIMIT);
+        const estimates = statEstimates(db);
+        const rows = schemas.map((schema) => {
+            if (schema.type === "index")
+                return { name: schema.name, kind: "index", ...(estimates.get(schema.name) !== undefined ? { estimatedRows: estimates.get(schema.name) } : {}) };
+            const count = boundedCount(db, schema.name);
+            return { name: schema.name, kind: "table", boundedCount: count.count, countComplete: count.complete, ...(estimates.get(schema.name) !== undefined ? { estimatedRows: estimates.get(schema.name) } : {}) };
+        });
+        const payload = inspectPayloadReferencesBounded(db);
+        const sizes = {
+            database: fileSize(path),
+            wal: fileSize(`${path}-wal`),
+            shm: fileSize(`${path}-shm`),
+            payloadStoreMetadataSample: payload.metadataBytes,
+            payloadStoreSampleComplete: payload.rowsComplete && payload.sampledRows === payload.rows,
+        };
+        const walPressure = sizes.wal >= thresholds.walBytes;
+        const warnings = [
+            ...(sizes.database >= thresholds.databaseBytes ? ["database_size_threshold"] : []),
+            ...(sizes.wal >= thresholds.walBytes ? ["wal_size_threshold"] : []),
+            ...(sizes.payloadStoreSampleComplete && sizes.payloadStoreMetadataSample >= thresholds.payloadBytes ? ["payload_size_threshold"] : []),
+            ...(!sizes.payloadStoreSampleComplete ? ["payload_size_threshold_indeterminate"] : []),
+            ...(walPressure ? ["wal_checkpoint_pressure"] : []),
+            ...(payload.metadataOrphans ? ["payload_metadata_orphans_sample"] : []),
+            ...(payload.brokenReferences ? ["broken_payload_references_sample"] : []),
+        ];
+        return {
+            resultType: "storage.status", readOnly: true, path, exists: true, health: warnings.length ? "degraded" : "healthy", sizes,
+            pages: { pageSize, pageCount, freelistCount, freelistRatio: pageCount ? freelistCount / pageCount : 0 },
+            wal: { ...walRow, pressure: walPressure }, rows,
+            payloads: { rows: payload.rows, rowsComplete: payload.rowsComplete, sampledRows: payload.sampledRows, referencedRows: payload.referencedRows, metadataOrphans: payload.metadataOrphans, brokenReferences: payload.brokenReferences, integrityComplete: payload.integrityComplete },
+            thresholds, last: readMaintenanceMetadata(path), warnings,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+export async function verifyStorage(input) {
+    const path = resolve(input.path), mode = input.mode ?? "quick", timeoutMs = input.timeoutMs ?? 60_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 3_600_000)
+        throw new Error("Verification timeout must be between 1 and 3600000 ms");
+    const started = Date.now(), progress = [];
+    const record = (stage, elapsedMs = Date.now() - started) => { const item = { stage, elapsedMs }; if (progress.length < 32)
+        progress.push(item); input.onProgress?.(item); };
+    const resultFor = (status, healthy, reason, messages = []) => ({ resultType: "storage.verification", path, mode, status, healthy, elapsedMs: Date.now() - started, progress, messages, ...(reason ? { reason } : {}) });
+    record("starting", 0);
+    if (input.signal?.aborted)
+        return resultFor("partial", false, "cancelled");
+    const result = await new Promise((resolveResult) => {
+        let child;
+        let settled = false;
+        let operationTimer;
+        let pendingPartialReason;
+        const startupTimer = setTimeout(() => requestStop("startup_timeout"), Math.min(5_000, Math.max(1_000, timeoutMs)));
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(startupTimer);
+            if (operationTimer)
+                clearTimeout(operationTimer);
+            input.signal?.removeEventListener("abort", cancel);
+            resolveResult(value);
+        };
+        const requestStop = (reason) => {
+            if (settled || pendingPartialReason)
+                return;
+            pendingPartialReason = reason;
+            record("terminating");
+            if (!child?.kill("SIGKILL"))
+                finish(resultFor("failed", false, "verification_process_not_terminated"));
+        };
+        const cancel = () => requestStop("cancelled");
+        input.signal?.addEventListener("abort", cancel, { once: true });
+        child = fork(fileURLToPath(new URL("./storage-verification-worker.js", import.meta.url)), [path, mode, ...(input.testNativeLongRunning ? ["native-long"] : [])], { stdio: ["ignore", "ignore", "ignore", "ipc"] });
+        child.on("message", (message) => {
+            if (!message || typeof message !== "object")
+                return;
+            const item = message;
+            if (item.type === "progress") {
+                const stage = String(item.stage);
+                record(stage, Number(item.elapsedMs));
+                if (stage.endsWith("_check") && !operationTimer) {
+                    clearTimeout(startupTimer);
+                    operationTimer = setTimeout(() => requestStop("timeout"), timeoutMs);
+                }
+                return;
+            }
+            if (item.type === "result") {
+                record("complete", Number(item.elapsedMs));
+                const messages = Array.isArray(item.messages) ? item.messages.map(String).slice(0, 100) : [];
+                finish(item.ok === true ? resultFor("complete", true, undefined, messages) : resultFor("failed", false, "integrity_errors", messages));
+            }
+            else if (item.type === "error")
+                finish(resultFor("failed", false, String(item.message ?? "verification_failed")));
+        });
+        child.on("error", (error) => finish(resultFor("failed", false, (error instanceof Error ? error.message : String(error)).slice(0, 500))));
+        child.on("exit", (code, signal) => {
+            if (pendingPartialReason) {
+                record("terminated");
+                finish(resultFor("partial", false, pendingPartialReason));
+            }
+            else if (!settled && code !== 0)
+                finish(resultFor("failed", false, `verification_process_exit_${code ?? signal ?? "unknown"}`));
+        });
+    });
+    if (result.status !== "partial") {
+        try {
+            recordMaintenance(path, { operation: "verification", at: new Date().toISOString(), mode, status: result.status, healthy: result.healthy, elapsedMs: result.elapsedMs });
+        }
+        catch { /* A read-only verification result remains valid when metadata storage is unavailable. */ }
+    }
+    return result;
+}
+export function checkpointStorage(input) {
+    const path = resolve(input.path), mode = input.mode ?? "passive";
+    if (!existsSync(path))
+        throw new Error(`Checkpoint database does not exist: ${path}`);
+    if (mode !== "passive" && mode !== "restart" && mode !== "truncate")
+        throw new Error("Checkpoint mode must be passive, restart, or truncate");
+    if (!input.apply)
+        return { resultType: "storage.checkpoint", mode: "dry-run", path, checkpointMode: mode, mutation: false };
+    const db = new DatabaseSync(path);
+    try {
+        db.exec("PRAGMA busy_timeout = 100");
+        const row = db.prepare(`PRAGMA wal_checkpoint(${mode.toUpperCase()})`).get();
+        const result = { resultType: "storage.checkpoint", mode: "apply", path, checkpointMode: mode, mutation: true, busy: Number(row.busy ?? 0), logPages: Number(row.log ?? 0), checkpointedPages: Number(row.checkpointed ?? 0), at: new Date().toISOString() };
+        recordMaintenance(path, { operation: "checkpoint", ...result });
+        return result;
+    }
+    finally {
+        db.close();
+    }
+}
+export async function maintainStorageRetention(input) {
+    const path = resolve(input.path), limit = input.limit ?? 1000;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 10_000)
+        throw new Error("Retention limit must be between 1 and 10000");
+    if (!Number.isFinite(Date.parse(input.before)))
+        throw new Error("Retention --before must be an ISO date");
+    const db = new DatabaseSync(path, { readOnly: !input.apply });
+    const target = tableExists(db, "event_log") ? { table: "event_log", time: "created_at" } : tableExists(db, "pibo_event_stream") ? { table: "pibo_event_stream", time: "created_at" } : undefined;
+    try {
+        if (!target)
+            return { resultType: "storage.retention", mode: input.apply ? "apply" : "dry-run", path, eligible: 0, deleted: 0, policy: "live_delta_only", preserved: ["chat_message", "audit_event", "idempotency_evidence", "referenced_payloads"] };
+        const eligibility = retentionEligibilitySql(target.table);
+        const eligible = Number(db.prepare(`SELECT COUNT(*) AS count FROM (SELECT 1 FROM ${target.table} WHERE ${eligibility} AND ${target.time} < ? ORDER BY ${target.time} LIMIT ?)`).get(input.before, limit).count);
+        const plan = retentionPlan(db, target.table, target.time, input.before, limit);
+        if (!input.apply)
+            return { resultType: "storage.retention", mode: "dry-run", path, eligible, deleteLimit: limit, policy: "live_delta_only", plan, preserved: ["chat_message", "audit_event", "idempotency_evidence", "referenced_payloads"] };
+        const auditId = `storage_retention_${randomUUID()}`;
+        const at = new Date().toISOString();
+        db.exec("PRAGMA busy_timeout = 100; BEGIN IMMEDIATE");
+        try {
+            db.exec(`CREATE TABLE IF NOT EXISTS storage_maintenance_audit (
+				id TEXT PRIMARY KEY,
+				operation TEXT NOT NULL,
+				status TEXT NOT NULL,
+				details_json TEXT NOT NULL,
+				created_at TEXT NOT NULL
+			)`);
+            const candidates = db.prepare(`SELECT rowid, ${target.table === "event_log" ? "payload_ref AS payloadRef" : "NULL AS payloadRef"} FROM ${target.table} WHERE ${eligibility} AND ${target.time} < ? ORDER BY ${target.time}, rowid LIMIT ?`).all(input.before, limit);
+            const deletion = db.prepare(`DELETE FROM ${target.table} WHERE rowid IN (SELECT rowid FROM ${target.table} WHERE ${eligibility} AND ${target.time} < ? ORDER BY ${target.time}, rowid LIMIT ?)`).run(input.before, limit);
+            const deleted = Number(deletion.changes);
+            if (deleted !== candidates.length)
+                throw new Error("Retention candidate/delete count changed while holding the write transaction");
+            const releasedPayloadIds = [...new Set(candidates.flatMap((row) => row.payloadRef ? [row.payloadRef] : []))];
+            const payloads = inspectReleasedPayloadsBounded(db, releasedPayloadIds);
+            const result = { resultType: "storage.retention", mode: "apply", path, eligible, deleted, deleteLimit: limit, policy: "live_delta_only", plan, payloads, auditId, preserved: ["chat_message", "audit_event", "idempotency_evidence", "referenced_payloads", "orphan_payload_files"], at };
+            db.prepare("INSERT INTO storage_maintenance_audit (id, operation, status, details_json, created_at) VALUES (?, 'retention', 'complete', ?, ?)").run(auditId, JSON.stringify(result), at);
+            db.exec("COMMIT");
+            try {
+                recordMaintenance(path, { operation: "retention", ...result });
+            }
+            catch { /* Transactional audit is authoritative. */ }
+            return result;
+        }
+        catch (error) {
+            if (db.isTransaction)
+                db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    finally {
+        db.close();
+    }
+}
+function retentionEligibilitySql(table) {
+    return table === "event_log"
+        ? "retention_class = 'live_delta' AND idempotency_key IS NULL"
+        : "retention_class = 'live_delta' AND idempotency_key IS NULL AND event_id IS NULL";
+}
+function retentionPlan(db, table, time, before, limit) {
+    const classes = ["live_delta", "trace_event", "chat_message", "audit_event"];
+    return classes.map((retentionClass) => {
+        const rows = Number(db.prepare(`SELECT COUNT(*) AS count FROM (SELECT 1 FROM ${table} WHERE retention_class=? AND ${time} < ? LIMIT ?)`).get(retentionClass, before, limit + 1).count);
+        return {
+            retentionClass,
+            rows: Math.min(rows, limit),
+            bounded: rows > limit,
+            disposition: retentionClass === "live_delta" ? "eligible" : retentionClass === "trace_event" ? "deferred_requires_policy" : "preserve",
+        };
+    });
+}
+function inspectPayloadReferencesBounded(db) {
+    if (!tableExists(db, "payloads"))
+        return { rows: 0, rowsComplete: true, sampledRows: 0, metadataBytes: 0, referencedRows: 0, metadataOrphans: 0, brokenReferences: 0, integrityComplete: true };
+    const rowCount = boundedCount(db, "payloads");
+    const payloadRows = db.prepare("SELECT id, COALESCE(compressed_byte_size, byte_size) AS bytes FROM payloads ORDER BY id LIMIT 1001").all();
+    const sample = payloadRows.slice(0, 1000);
+    const references = discoverPayloadReferenceColumns(db);
+    const sampledReferenceIds = new Set();
+    let brokenReferences = 0;
+    let referenceSamplesComplete = true;
+    for (const reference of references) {
+        const table = quoteIdentifier(reference.table), column = quoteIdentifier(reference.column);
+        // Do not filter here: LIMIT bounds rows examined even when references are sparse.
+        const rows = db.prepare(`SELECT ${column} AS id FROM ${table} LIMIT 1001`).all();
+        if (rows.length > 1000)
+            referenceSamplesComplete = false;
+        for (const row of rows.slice(0, 1000)) {
+            if (!row.id)
+                continue;
+            sampledReferenceIds.add(row.id);
+            if (!db.prepare("SELECT 1 FROM payloads WHERE id = ?").get(row.id))
+                brokenReferences += 1;
+        }
+    }
+    const referencedRows = sample.filter((payload) => sampledReferenceIds.has(payload.id)).length;
+    const integrityComplete = rowCount.complete && payloadRows.length <= 1000 && referenceSamplesComplete;
+    return {
+        rows: rowCount.count,
+        rowsComplete: rowCount.complete,
+        sampledRows: sample.length,
+        metadataBytes: sample.reduce((total, row) => total + Number(row.bytes ?? 0), 0),
+        referencedRows,
+        metadataOrphans: integrityComplete ? sample.length - referencedRows : 0,
+        brokenReferences,
+        integrityComplete,
+    };
+}
+function inspectReleasedPayloadsBounded(_db, candidateIds) {
+    const bounded = [...new Set(candidateIds)].slice(0, 1000);
+    return {
+        releasedReferenceCandidates: candidateIds.length,
+        candidatesReported: bounded.length,
+        candidatesTruncated: candidateIds.length > bounded.length,
+        referenceState: "not_scanned_online",
+        retainedMetadata: bounded.length,
+        retainedFiles: bounded.length,
+        action: "report_only",
+    };
+}
+function discoverPayloadReferenceColumns(db) {
+    const tables = db.prepare("SELECT name FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name LIMIT 128").all();
+    const references = [];
+    for (const { name } of tables) {
+        const columns = db.prepare("SELECT name FROM pragma_table_info(?) LIMIT 128").all(name);
+        for (const column of columns) {
+            if (column.name === "payload_ref" || column.name === "content_payload_ref" || column.name === "payload_preview_ref")
+                references.push({ table: name, column: column.name });
+        }
+    }
+    return references.slice(0, 64);
+}
+function quoteIdentifier(value) { return `"${value.replaceAll('"', '""')}"`; }
+function statEstimates(db) { const result = new Map(); if (!tableExists(db, "sqlite_stat1"))
+    return result; try {
+    for (const row of db.prepare("SELECT tbl, idx, stat FROM sqlite_stat1 LIMIT 256").all()) {
+        const estimate = Number.parseInt(row.stat.split(" ")[0] ?? "", 10);
+        if (Number.isFinite(estimate)) {
+            result.set(row.tbl, estimate);
+            if (row.idx)
+                result.set(row.idx, estimate);
+        }
+    }
+}
+catch { } return result; }
+function boundedCount(db, name) { const quoted = `"${name.replaceAll('"', '""')}"`; try {
+    const count = Number(db.prepare(`SELECT COUNT(*) AS count FROM (SELECT 1 FROM ${quoted} LIMIT ?)`).get(ROW_SAMPLE_LIMIT + 1).count);
+    return { count: Math.min(count, ROW_SAMPLE_LIMIT), complete: count <= ROW_SAMPLE_LIMIT };
+}
+catch {
+    return { count: 0, complete: false };
+} }
+function pragmaNumber(db, name) { return Number(Object.values(db.prepare(`PRAGMA ${name}`).get() ?? { value: 0 })[0] ?? 0); }
+function tableExists(db, table) { return Boolean(db.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name=?").get(table)); }
+function columnExists(db, table, column) { return Boolean(db.prepare(`SELECT 1 FROM pragma_table_info(?) WHERE name=?`).get(table, column)); }
+function fileSize(path) { try {
+    return statSync(path).size;
+}
+catch {
+    return 0;
+} }
+function validThreshold(value, fallback) { return Number.isSafeInteger(value) && value > 0 ? value : fallback; }
+export function recordStorageMaintenance(path, value) { appendFileSync(`${resolve(path)}${MAINTENANCE_LOG_SUFFIX}`, `${JSON.stringify(value)}\n`, { mode: 0o600 }); }
+function recordMaintenance(path, value) { recordStorageMaintenance(path, value); }
+function readMaintenanceMetadata(path) { const result = {}; try {
+    const metadataPath = `${path}${MAINTENANCE_LOG_SUFFIX}`;
+    const bytes = statSync(metadataPath).size;
+    if (bytes > 1024 * 1024)
+        return result;
+    const lines = readFileSync(metadataPath, "utf8").trim().split("\n").slice(-100);
+    for (const line of lines) {
+        const row = JSON.parse(line);
+        const operation = row.operation;
+        if (operation === "checkpoint")
+            result.checkpoint = row;
+        else if (operation === "backup")
+            result.backup = row;
+        else if (operation === "verification")
+            result.verification = row;
+        else if (operation === "retention")
+            result.retention = row;
+    }
+}
+catch { } return result; }

package/dist/data/storage-verification-worker.js

@@ -0,0 +1,25 @@
+import { DatabaseSync } from "node:sqlite";
+const [path, mode, fixture] = process.argv.slice(2);
+const started = Date.now();
+const send = (message) => process.send?.(message);
+let db;
+try {
+    send({ type: "progress", stage: "opened", elapsedMs: 0 });
+    db = new DatabaseSync(path, { readOnly: true });
+    db.exec("PRAGMA busy_timeout = 50");
+    const pragma = mode === "full" ? "integrity_check" : "quick_check";
+    send({ type: "progress", stage: pragma, elapsedMs: Date.now() - started });
+    if (fixture === "native-long") {
+        db.prepare("WITH RECURSIVE counter(value) AS (VALUES(0) UNION ALL SELECT value + 1 FROM counter WHERE value < 1000000000) SELECT SUM(value) FROM counter").get();
+    }
+    const rows = db.prepare(`PRAGMA ${pragma}`).all();
+    const messages = rows.slice(0, 100).flatMap((row) => Object.values(row).map(String));
+    send({ type: "result", ok: messages.length === 1 && messages[0] === "ok", messages, elapsedMs: Date.now() - started });
+}
+catch (error) {
+    send({ type: "error", message: error instanceof Error ? error.message.slice(0, 500) : "Verification failed", elapsedMs: Date.now() - started });
+}
+finally {
+    db?.close();
+    process.disconnect?.();
+}

package/dist/debug/index.js

@@ -13,6 +13,15 @@ export async function runDebugCli(argv = process.argv) {
             await runStorageBackupCli(args.slice(1));
             return;
         }
+        if (args[0] === "message-queue") {
+            await runDebugMessageQueue(args.slice(1));
+            return;
+        }
+        if (args[0] === "storage") {
+            const { runStorageMaintenanceCli } = await import("./storage-maintenance.js");
+            await runStorageMaintenanceCli(args.slice(1));
+            return;
+        }
         if (args[0] === "db") {
             await runDebugDb(args.slice(1));
             return;
@@ -103,6 +112,92 @@ export async function runDebugCli(argv = process.argv) {
         process.exitCode = 1;
     }
 }
+async function runDebugMessageQueue(args) {
+    if (!args.length || args[0] === "--help" || args[0] === "-h") {
+        console.log(`pibo debug message-queue - inspect and conservatively reconcile durable messages
+
+Commands:
+  inspect --session <ps_...> [--after-stream <n>] [--before-terminal-stream <n>] [--json]
+  reconcile <cmd_...> --mark-failed [--cancel-successors] [--dry-run|--apply] [--json]
+  reconcile <cmd_...> --confirm-completed [--confirm-without-evidence <cmd_...>] [--dry-run|--apply] [--json]
+
+Safety:
+  Dry-run is the default. --apply mutates the exact command transactionally.
+  Replay is unsupported: this command never executes a message or repeats side effects.
+  /clear only cancels unstarted runtime/queue work; it does not reconcile an interrupted durable predecessor.
+
+Next:
+  pibo debug message-queue inspect --session <pibo-session-id>`);
+        return;
+    }
+    const command = args[0], json = args.includes("--json");
+    const value = (flag) => { const index = args.indexOf(flag); if (index < 0)
+        return undefined; const result = args[index + 1]; if (!result || result.startsWith("--"))
+        throw new Error(`${flag} requires a value`); return result; };
+    const { PiboDataStore } = await import("../data/pibo-store.js");
+    const descriptor = resolveDebugStore("pibo-data");
+    if (!descriptor.exists)
+        throw new Error(`Pibo data store not found at ${descriptor.path}`);
+    const mutating = command === "reconcile" && args.includes("--apply");
+    const store = new PiboDataStore(descriptor.path, { readOnly: !mutating });
+    try {
+        const module = await import("./message-queue.js");
+        if (command === "inspect") {
+            const sessionId = value("--session");
+            if (!sessionId)
+                throw new Error("message-queue inspect requires --session <pibo-session-id>");
+            const parseStream = (flag) => { const raw = value(flag); if (raw === undefined)
+                return undefined; const parsed = Number(raw); if (!Number.isSafeInteger(parsed) || parsed < 1)
+                throw new Error(`${flag} requires a positive integer stream id`); return parsed; };
+            const result = module.inspectMessageQueue(store, { sessionId, afterStreamId: parseStream("--after-stream"), beforeTerminalStreamId: parseStream("--before-terminal-stream") });
+            if (json)
+                console.log(JSON.stringify(result, null, 2));
+            else
+                console.log(module.formatMessageQueueInspection(result));
+            return;
+        }
+        if (command === "reconcile") {
+            const commandId = args[1];
+            if (!commandId || commandId.startsWith("--"))
+                throw new Error("message-queue reconcile requires an exact <cmd_...> ID");
+            if (args.includes("--replay"))
+                throw new Error("Replay is unsupported because provider and tool side effects cannot be proven idempotent. Choose --mark-failed or --confirm-completed.");
+            const decisions = [args.includes("--mark-failed") ? "mark-failed" : undefined, args.includes("--confirm-completed") ? "confirm-completed" : undefined].filter(Boolean);
+            if (decisions.length !== 1)
+                throw new Error("Choose exactly one decision: --mark-failed or --confirm-completed");
+            if (args.includes("--apply") && args.includes("--dry-run"))
+                throw new Error("Choose either --dry-run or --apply");
+            const known = new Set(["--json", "--mark-failed", "--confirm-completed", "--cancel-successors", "--dry-run", "--apply", "--confirm-without-evidence", "--cancel-successor"]);
+            for (let index = 2; index < args.length; index++) {
+                const item = args[index];
+                if (!item.startsWith("--"))
+                    continue;
+                if (!known.has(item))
+                    throw new Error(`Unknown message-queue reconciliation option "${item}"`);
+                if (item === "--confirm-without-evidence" || item === "--cancel-successor")
+                    index++;
+            }
+            const cancelSuccessorIds = [];
+            for (let index = 0; index < args.length; index++)
+                if (args[index] === "--cancel-successor") {
+                    const id = args[index + 1];
+                    if (!id)
+                        throw new Error("--cancel-successor requires a command ID");
+                    cancelSuccessorIds.push(id);
+                }
+            const result = module.reconcileMessageCommand(store, { commandId, decision: decisions[0], apply: args.includes("--apply"), confirmWithoutEvidence: value("--confirm-without-evidence"), cancelSuccessors: args.includes("--cancel-successors"), cancelSuccessorIds });
+            if (json)
+                console.log(JSON.stringify({ ...result, nextCommands: [result.nextAction] }, null, 2));
+            else
+                console.log(module.formatMessageQueueReconciliation(result));
+            return;
+        }
+        throw new Error(`Unknown pibo debug message-queue command "${command}". Run pibo debug message-queue --help.`);
+    }
+    finally {
+        store.close();
+    }
+}
 async function runDebugIntegrity(args) {
     if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
         printDebugIntegrityDiscovery();
@@ -212,6 +307,31 @@ async function runDebugRepair(args) {
         printDebugRepairDiscovery();
         return;
     }
+    if (args[0] === "output-collision") {
+        if (args[1] === "--help" || args[1] === "-h") {
+            printDebugRepairDiscovery();
+            return;
+        }
+        const jobIndex = args.indexOf("--job");
+        const jobId = jobIndex >= 0 ? args[jobIndex + 1] : undefined;
+        if (!jobId || jobId.startsWith("-"))
+            throw new Error("pibo debug repair output-collision requires --job <dead-job-id>");
+        const allowed = new Set(["--job", jobId, "--json", "--dry-run", "--apply", "--keep-existing"]);
+        const unknown = args.slice(1).find((arg) => !allowed.has(arg));
+        if (unknown)
+            throw new Error(`Unknown output collision repair option "${unknown}"`);
+        if (args.includes("--apply") && args.includes("--dry-run"))
+            throw new Error("Choose either --dry-run or --apply");
+        const { repairOutputCollision } = await import("./output-collision-repair.js");
+        const result = repairOutputCollision({ dataStore: resolveDebugStore("pibo-data"), reliabilityStore: resolveDebugStore("reliability"), jobId, apply: args.includes("--apply"), keepExisting: args.includes("--keep-existing") });
+        console.log(args.includes("--json") ? JSON.stringify(result, null, 2) : [
+            "pibo debug repair output-collision", `mode\t${result.mode}`, `job\t${result.jobId}`, `decision\t${result.decision}`,
+            `applied\t${result.applied}`, `idempotent\t${result.idempotent}`, `transcript\t${result.projections.transcript}`,
+            `trace\t${result.projections.trace}`, `navigation\t${result.projections.navigation}`, `command\t${result.projections.command}`,
+            ...(result.auditStreamId ? [`audit\t${result.auditStreamId}`] : []), "", ...result.warnings.map((warning) => `warning\t${warning}`),
+        ].join("\n"));
+        return;
+    }
     if (args[0] !== "output") {
         throw new Error(`Unknown pibo debug repair command "${args[0]}". Run pibo debug repair --help.`);
     }
@@ -907,7 +1027,7 @@ async function runDebugJobs(args) {
     const reliability = new PiboReliabilityStore(store.path);
     try {
         if (command === "list") {
-            const jobs = reliability.listJobs({ queue: options.queue, limit: options.limit ? Number(options.limit) : undefined });
+            const jobs = reliability.inspectJobs({ queue: options.queue, limit: options.limit ? Number(options.limit) : undefined });
             if (options.json)
                 console.log(formatJson({ jobs: jobs.map(observableJobRow) }));
             else
@@ -933,6 +1053,27 @@ async function runDebugJobs(args) {
                 console.log(formatRows([compactJobRow(job)]));
             return;
         }
+        if (command === "reconcile-runs") {
+            if (options.apply === options.dryRun) {
+                throw new Error("pibo debug jobs reconcile-runs requires exactly one of --dry-run or --apply");
+            }
+            const result = reliability.reconcileOrphanRunJobs({ apply: options.apply });
+            const output = {
+                checkedAt: result.checkedAt,
+                mode: result.apply ? "apply" : "dry-run",
+                candidateCount: result.candidates.length,
+                moved: result.moved,
+                jobs: result.candidates.map(observableJobRow),
+            };
+            if (options.json)
+                console.log(formatJson(output));
+            else {
+                console.log(formatRows([{ checkedAt: output.checkedAt, mode: output.mode, candidateCount: output.candidateCount, moved: output.moved }]));
+                if (result.candidates.length)
+                    console.log(formatRows(result.candidates.map(compactJobRow)));
+            }
+            return;
+        }
         throw new Error(`Unknown pibo debug jobs command "${command}". Run pibo debug jobs --help.`);
     }
     finally {
@@ -1257,6 +1398,10 @@ function compactJobRow(job) {
         eventId: correlation.eventId,
         phase: correlation.phase,
         workerId: job.workerId,
+        claimExpiresAt: job.claimExpiresAt,
+        claimExpired: job.claimExpired,
+        missingRunRecord: job.missingRunRecord,
+        effectiveLiveness: job.effectiveLiveness,
         lastError: job.lastError,
     };
 }
@@ -1361,6 +1506,8 @@ function printDebugDiscovery() {
 
 Commands:
   backup   Create, verify or restore an explicit SQLite and payload snapshot
+  message-queue Inspect or reconcile interrupted durable message commands
+  storage  Bounded SQLite status, verification, checkpoint, and retention
   db       Inspect and query local SQLite stores
   session  Inspect one Pibo Session by id or Chat URL
   summary  Show compact session diagnosis and drill-down commands
@@ -1383,6 +1530,7 @@ Commands:
   pty      Run and inspect interactive CLI/TUI commands under a PTY
 
 Next:
+  pibo debug storage status --json
   pibo debug db
   pibo debug summary <pibo-session-id>
   pibo debug final <pibo-session-id>
@@ -1456,6 +1604,8 @@ function printDebugRepairDiscovery() {
 Usage:
   pibo debug repair output <pibo-session-id> <event-id> [--dry-run|--apply] [--json]
   pibo debug repair output --session <pibo-session-id> [--since <iso-date>] [--before <iso-date>] [--limit n] [--dry-run|--apply] [--json]
+  pibo debug repair output-collision --job <dead-job-id> [--dry-run] [--json]
+  pibo debug repair output-collision --job <dead-job-id> --apply --keep-existing [--json]
 
 Behavior:
   Dry-run is the default. --apply is required for every mutation.
@@ -1464,6 +1614,8 @@ Behavior:
   Repair never invents assistant content. Without an exact Reliability terminal, only a completed assistant record can justify message_finished.
   Every applied terminal writes a pibo.output.repair_applied audit event in the same transaction.
   Repair does not delete or replay pending or dead output-persistence jobs.
+  Collision dry-run reports transcript, trace, navigation, and command projection state.
+  Collision apply requires --keep-existing, records an idempotent audit, and never compares or replays conflicting bodies or side effects.
 
 Next:
   pibo debug repair output ps_... <event-id> --dry-run --json
@@ -1704,9 +1856,11 @@ Usage:
   pibo debug jobs list [--queue queue] [--limit n] [--json]
   pibo debug jobs dead [--queue queue] [--limit n] [--json]
   pibo debug jobs replay <job-id> [--json]
+  pibo debug jobs reconcile-runs (--dry-run|--apply) [--json]
 
 Next:
   pibo debug jobs list --queue runs
+  pibo debug jobs reconcile-runs --dry-run
   pibo debug jobs dead --queue runs
 `);
 }