@pasko70/pibo 3.5.0 → 3.6.0

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;
@@ -25,6 +34,10 @@ export async function runDebugCli(argv = process.argv) {
             await runDebugTrace(args.slice(1));
             return;
         }
+        if (args[0] === "cache") {
+            await runDebugCache(args.slice(1));
+            return;
+        }
         if (args[0] === "summary") {
             await runDebugSummary(args.slice(1));
             return;
@@ -103,6 +116,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 +311,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.`);
     }
@@ -695,6 +819,29 @@ async function runDebugTelemetry(args) {
     }
     throw new Error(`Unknown pibo debug telemetry command "${command}". Run pibo debug telemetry --help.`);
 }
+async function runDebugCache(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printDebugCacheDiscovery();
+        return;
+    }
+    const options = parseOptions(args);
+    const piboSessionId = options.positionals[0];
+    if (!piboSessionId)
+        throw new Error("pibo debug cache requires <pibo-session-id>");
+    if (options.positionals.length > 1)
+        throw new Error("pibo debug cache accepts one <pibo-session-id>. Run pibo debug cache --help.");
+    const limit = options.limit === undefined ? undefined : Number(options.limit);
+    if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1 || limit > 200))
+        throw new Error("--limit must be an integer from 1 to 200");
+    const stores = { sessions: resolveDebugStore("sessions"), chat: resolveDebugStore("chat") };
+    const { formatJson } = await import("./sql.js");
+    const { formatDebugCache, inspectDebugCache } = await import("./cache.js");
+    const result = await inspectDebugCache(piboSessionId, stores, { limit });
+    if (options.json)
+        console.log(formatJson(result));
+    else
+        console.log(formatDebugCache(result));
+}
 async function runDebugTrace(args) {
     if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
         printDebugTraceDiscovery();
@@ -907,7 +1054,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 +1080,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 +1425,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,12 +1533,15 @@ 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
   messages List or show stored user/assistant messages
   final    Show the latest assistant message
   trace    Rebuild the Chat Web trace view for one Pibo Session
+  cache    Summarize provider-reported cache usage for one Pibo Session
   events   Inspect compact event payload fields for one Pibo Session
   agents   Inspect delegated child agents and their persisted activity
   tool     Inspect one grouped tool call
@@ -1383,11 +1558,13 @@ 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>
   pibo debug messages <pibo-session-id> list
   pibo debug trace <pibo-session-id> --running-only
+  pibo debug cache <pibo-session-id>
   pibo debug events stream --topic pibo.output
   pibo debug persistence
   pibo debug repair output <pibo-session-id> <event-id> --dry-run
@@ -1456,6 +1633,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 +1643,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
@@ -1655,6 +1836,23 @@ Next:
   pibo debug tool ps_... <tool-call-id> --output
 `);
 }
+function printDebugCacheDiscovery() {
+    console.log(`pibo debug cache - summarize provider-reported cache usage
+
+Usage:
+  pibo debug cache <pibo-session-id> [--limit n] [--json]
+
+Reports:
+  Per-inference input, cache-read, cache-write and uncached token counts.
+  Warns when large consecutive requests move from mostly cached to mostly uncached input.
+  Provider metrics cannot identify the cause of a cache-read drop.
+
+Next:
+  pibo debug cache ps_... --json
+  pibo debug trace ps_... --medium
+  pibo debug events ps_... --type assistant_usage --fields inputTokens,cacheReadTokens,cacheWriteTokens,totalTokens
+`);
+}
 function printDebugTraceDiscovery() {
     console.log(`pibo debug trace - rebuild one Chat Web trace view
 
@@ -1704,9 +1902,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
 `);
 }

package/dist/debug/message-queue.js

@@ -0,0 +1,108 @@
+import { MessageCommandStore } from "../data/message-command-store.js";
+const ACTIVE_STATES = new Set(["accepted", "waiting_slot", "initializing", "session_queue", "running"]);
+const commandColumns = "id,request_key,session_id,room_id,event_id,stream_id,delivery,state,owner,token,lease_until,created_at,updated_at,error";
+export function inspectMessageQueue(store, input = {}) {
+    const now = input.now ?? Date.now(), activeLimit = Math.max(1, Math.min(500, input.limit ?? 200)), terminalLimit = Math.min(20, activeLimit), after = Math.max(0, Math.trunc(input.afterStreamId ?? 0));
+    const activeRows = (input.sessionId
+        ? store.db.prepare(`SELECT ${commandColumns} FROM message_commands WHERE session_id=? AND state IN ('accepted','waiting_slot','initializing','session_queue','running','interrupted') AND stream_id>? ORDER BY stream_id LIMIT ?`).all(input.sessionId, after, activeLimit + 1)
+        : store.db.prepare(`SELECT ${commandColumns} FROM message_commands WHERE state IN ('accepted','waiting_slot','initializing','session_queue','running','interrupted') AND stream_id>? ORDER BY stream_id LIMIT ?`).all(after, activeLimit + 1));
+    const terminalBefore = input.beforeTerminalStreamId;
+    const terminalRows = (input.sessionId
+        ? terminalBefore === undefined
+            ? store.db.prepare(`SELECT ${commandColumns} FROM message_commands WHERE session_id=? AND state IN ('completed','failed') ORDER BY stream_id DESC LIMIT ?`).all(input.sessionId, terminalLimit + 1)
+            : store.db.prepare(`SELECT ${commandColumns} FROM message_commands WHERE session_id=? AND state IN ('completed','failed') AND stream_id<? ORDER BY stream_id DESC LIMIT ?`).all(input.sessionId, terminalBefore, terminalLimit + 1)
+        : terminalBefore === undefined
+            ? store.db.prepare(`SELECT ${commandColumns} FROM message_commands WHERE state IN ('completed','failed') ORDER BY stream_id DESC LIMIT ?`).all(terminalLimit + 1)
+            : store.db.prepare(`SELECT ${commandColumns} FROM message_commands WHERE state IN ('completed','failed') AND stream_id<? ORDER BY stream_id DESC LIMIT ?`).all(terminalBefore, terminalLimit + 1));
+    const activeTruncated = activeRows.length > activeLimit, terminalTruncated = terminalRows.length > terminalLimit, active = activeRows.slice(0, activeLimit), terminal = terminalRows.slice(0, terminalLimit);
+    const contextById = new Map([...terminal.map(row => [row.id, "recent_terminal"]), ...active.map(row => [row.id, "active"])]);
+    const selected = [...new Map([...terminal, ...active].map(row => [row.id, row])).values()].sort((a, b) => a.stream_id - b.stream_id), commands = new MessageCommandStore(store);
+    const projected = selected.map(row => {
+        const previous = store.db.prepare("SELECT id FROM message_commands WHERE session_id=? AND stream_id<? ORDER BY stream_id DESC LIMIT 1").get(row.session_id, row.stream_id);
+        const next = store.db.prepare("SELECT id FROM message_commands WHERE session_id=? AND stream_id>? ORDER BY stream_id LIMIT 1").get(row.session_id, row.stream_id);
+        const blocker = ACTIVE_STATES.has(row.state) || row.state === "interrupted" ? store.db.prepare(`SELECT id FROM message_commands WHERE session_id=? AND stream_id<? AND state IN ('accepted','waiting_slot','initializing','session_queue','running','interrupted') AND (?='queue' OR delivery='steer') ORDER BY stream_id LIMIT 1`).get(row.session_id, row.stream_id, row.delivery) : undefined;
+        const blockingRows = row.state === "interrupted" ? store.db.prepare(`SELECT id FROM message_commands WHERE session_id=? AND stream_id>? AND state IN ('accepted','waiting_slot','initializing','session_queue','running') AND (delivery='queue' OR ?='steer') ORDER BY stream_id LIMIT 201`).all(row.session_id, row.stream_id, row.delivery) : [];
+        return { id: row.id, context: contextById.get(row.id) ?? "recent_terminal", sessionId: row.session_id, roomId: row.room_id, eventId: row.event_id, streamId: row.stream_id, delivery: row.delivery, state: row.state, ...(row.owner ? { owner: row.owner } : {}), lease: { until: row.lease_until, fresh: Boolean(row.owner && row.lease_until > now) }, createdAt: row.created_at, updatedAt: row.updated_at, ...(row.error ? { error: row.error } : {}), ...(previous ? { previousCommandId: previous.id } : {}), ...(next ? { nextCommandId: next.id } : {}), ...(blocker && blocker.id !== row.id ? { blockedBy: blocker.id } : {}), blocks: blockingRows.slice(0, 200).map(item => item.id), blocksTruncated: blockingRows.length > 200, terminalOutcome: commands.terminalOutcome(row.session_id, row.event_id) ?? "ambiguous", terminalEvidence: commands.terminalEvidence(row.session_id, row.event_id) };
+    });
+    const nextCommands = input.sessionId ? [`pibo debug message-queue reconcile <command-id> --mark-failed --dry-run`, `pibo debug message-queue reconcile <command-id> --mark-failed --apply`] : ["pibo debug message-queue inspect --session <pibo-session-id>"];
+    if (activeTruncated && active.length)
+        nextCommands.push(`pibo debug message-queue inspect --session ${input.sessionId ?? "<pibo-session-id>"} --after-stream ${active.at(-1).stream_id}`);
+    if (terminalTruncated && terminal.length)
+        nextCommands.push(`pibo debug message-queue inspect --session ${input.sessionId ?? "<pibo-session-id>"} --before-terminal-stream ${Math.min(...terminal.map(row => row.stream_id))}`);
+    return { generatedAt: new Date(now).toISOString(), sessionId: input.sessionId, commands: projected, health: commands.health(now), truncated: activeTruncated || terminalTruncated, pagination: { active: { returned: active.length, truncated: activeTruncated, afterStreamId: after, ...(activeTruncated && active.length ? { nextAfterStreamId: active.at(-1).stream_id } : {}) }, terminalContext: { returned: terminal.length, truncated: terminalTruncated, ...(terminalBefore !== undefined ? { beforeStreamId: terminalBefore } : {}), ...(terminalTruncated && terminal.length ? { nextBeforeStreamId: Math.min(...terminal.map(row => row.stream_id)) } : {}) } }, nextCommands };
+}
+function readCommand(store, id) {
+    return store.db.prepare("SELECT id,request_key,session_id,room_id,event_id,stream_id,delivery,state,owner,token,lease_until,created_at,updated_at,error FROM message_commands WHERE id=?").get(id);
+}
+function successorRows(store, row) {
+    return store.db.prepare("SELECT id,request_key,session_id,room_id,event_id,stream_id,delivery,state,owner,token,lease_until,created_at,updated_at,error FROM message_commands WHERE session_id=? AND stream_id>? AND state IN ('accepted','waiting_slot') ORDER BY stream_id LIMIT 200").all(row.session_id, row.stream_id);
+}
+function projection(row, state, error) { return { id: row.id, sessionId: row.session_id, eventId: row.event_id, priorState: row.state, resultingState: state, error: error ?? undefined, token: row.token, updatedAt: row.updated_at }; }
+export function reconcileMessageCommand(store, options) {
+    if (!/^cmd_[A-Za-z0-9-]+$/.test(options.commandId))
+        throw new Error("Reconciliation requires one exact command ID (cmd_...).");
+    const now = options.now ?? Date.now(), commands = new MessageCommandStore(store);
+    const action = () => {
+        const row = readCommand(store, options.commandId);
+        if (!row)
+            throw new Error(`Unknown durable message command "${options.commandId}".`);
+        const desired = options.decision === "mark-failed" ? "failed" : "completed";
+        if (row.state === desired) {
+            const priorAudit = store.eventLog.findByIdempotencyKey(`message-command-reconcile:${row.id}:${options.decision}`);
+            if (!priorAudit)
+                throw new Error(`Command ${row.id} is already ${row.state}, but no matching reconciliation audit exists; inspect the current state.`);
+            return { applied: false, alreadyApplied: true, decision: options.decision, command: projection(row, desired, row.error), successors: [], auditEventId: priorAudit.eventId, health: commands.health(now), nextAction: `pibo debug message-queue inspect --session ${row.session_id}` };
+        }
+        if (options.expected && (row.state !== options.expected.state || row.token !== options.expected.token || row.updated_at !== options.expected.updatedAt))
+            throw Object.assign(new Error("Command changed after inspection; inspect again before applying."), { code: "command_snapshot_changed" });
+        if (row.state !== "interrupted")
+            throw new Error(`Command ${row.id} is ${row.state}; only an interrupted command may be reconciled.`);
+        if (row.owner && row.lease_until > now)
+            throw Object.assign(new Error(`Command ${row.id} still has a live owner lease; reconciliation refused.`), { code: "command_live_lease" });
+        const evidence = commands.terminalEvidence(row.session_id, row.event_id), authoritativeCompleted = commands.terminalOutcome(row.session_id, row.event_id) === "completed";
+        if (options.decision === "confirm-completed" && !authoritativeCompleted && options.confirmWithoutEvidence !== row.id)
+            throw new Error(`No unambiguous completed terminal evidence exists. To explicitly confirm side effects, add --confirm-without-evidence ${row.id}.`);
+        const candidates = successorRows(store, row), selected = options.cancelSuccessors ? candidates : options.cancelSuccessorIds?.length ? options.cancelSuccessorIds.map(id => { const found = candidates.find(item => item.id === id); if (!found)
+            throw new Error(`Successor ${id} is not an unstarted FIFO successor of ${row.id}.`); return found; }) : [];
+        const liveSuccessor = selected.find(item => Boolean(item.owner && item.lease_until > now));
+        if (liveSuccessor)
+            throw Object.assign(new Error(`Selected successor ${liveSuccessor.id} still has a live owner lease; the entire reconciliation was refused.`), { code: "command_successor_live_lease", blockingCommandId: liveSuccessor.id, leaseUntil: liveSuccessor.lease_until });
+        const resultError = desired === "failed" ? "Operator marked interrupted durable message failed; command was not replayed." : null;
+        const plan = { applied: false, alreadyApplied: false, decision: options.decision, command: projection(row, desired, resultError), successors: selected.map(item => projection(item, "failed", "Cancelled during explicit predecessor reconciliation; command was never dispatched.")), evidence, healthBefore: commands.health(now), nextAction: `pibo debug message-queue inspect --session ${row.session_id}` };
+        if (!options.apply)
+            return plan;
+        const changed = Number(store.db.prepare("UPDATE message_commands SET state=?,error=?,owner=NULL,lease_until=0,updated_at=? WHERE id=? AND state='interrupted' AND token=? AND updated_at=?").run(desired, resultError, now, row.id, row.token, row.updated_at).changes);
+        if (changed !== 1)
+            throw Object.assign(new Error("Command changed during reconciliation; transaction rolled back."), { code: "command_snapshot_changed" });
+        for (const item of selected) {
+            const successorChanged = Number(store.db.prepare("UPDATE message_commands SET state='failed',error='Cancelled during explicit predecessor reconciliation; command was never dispatched.',owner=NULL,lease_until=0,updated_at=? WHERE id=? AND state IN ('accepted','waiting_slot') AND token=? AND updated_at=?").run(now, item.id, item.token, item.updated_at).changes);
+            if (successorChanged !== 1)
+                throw Object.assign(new Error(`Successor ${item.id} changed during reconciliation; transaction rolled back.`), { code: "command_snapshot_changed" });
+        }
+        const iso = new Date(now).toISOString();
+        // Session/navigation status is owned by current runtime and terminal product output.
+        // Reconciling a historical receipt must not overwrite a newer turn or live steer.
+        store.db.prepare("UPDATE telemetry_turns SET status=?,current_phase='reconciled',completed_at=COALESCE(completed_at,?),last_progress_at=?,updated_at=? WHERE pibo_session_id=? AND event_id=? AND status NOT IN ('completed','failed')").run(desired, iso, iso, iso, row.session_id, row.event_id);
+        options.beforeAudit?.();
+        const actor = (options.actor ?? process.env.USER ?? "operator").replace(/[^A-Za-z0-9_.@-]/g, "_").slice(0, 100) || "operator";
+        const audit = store.eventLog.appendEvent({ sessionId: row.session_id, roomId: row.room_id, topic: "pibo.audit", type: "durable_message_command.reconciled", source: "pibo-debug-cli", actorType: "operator", actorId: actor, eventId: `reconcile:${row.id}:${options.decision}`, idempotencyKey: `message-command-reconcile:${row.id}:${options.decision}`, retentionClass: "audit_event", previewText: `Durable command ${options.decision}`, attributes: { commandId: row.id, eventId: row.event_id, decision: options.decision, priorState: row.state, resultingState: desired, evidenceStreamIds: evidence.map(item => item.streamId), affectedSuccessorIds: selected.map(item => item.id), actor, source: "pibo-debug-cli", occurredAt: iso, replay: false } });
+        return { ...plan, applied: true, auditEventId: audit.eventId, health: commands.health(now) };
+    };
+    return options.apply ? store.transaction(action) : action();
+}
+export function formatMessageQueueInspection(result) {
+    const lines = ["Durable message queue", `  status: ${result.health.status}`, `  interrupted: ${result.health.interruptedPredecessors}`, `  FIFO blocked: ${result.health.blockedSuccessors}`, `  expired leases: ${result.health.expiredOwnedLeases}`];
+    for (const row of result.commands) {
+        lines.push(`  stream=${row.streamId} ${row.id} context=${row.context} state=${row.state} delivery=${row.delivery} session=${row.sessionId} event=${row.eventId} owner=${row.owner ?? "-"} lease=${row.lease.fresh ? "fresh" : "stale/none"}${row.previousCommandId ? ` previous=${row.previousCommandId}` : ""}${row.nextCommandId ? ` next=${row.nextCommandId}` : ""}${row.blockedBy ? ` blockedBy=${row.blockedBy}` : ""}`);
+        if (row.terminalEvidence.length)
+            lines.push(`     evidence: outcome=${row.terminalOutcome ?? "ambiguous"} ${row.terminalEvidence.map(item => `${item.type}@${item.streamId}`).join(", ")}`);
+        if (row.blocks.length)
+            lines.push(`     blocks: ${row.blocks.join(", ")}`);
+    }
+    lines.push("Next:", ...result.nextCommands.map(command => `  ${command}`));
+    return lines.join("\n");
+}
+export function formatMessageQueueReconciliation(result) {
+    const mode = "alreadyApplied" in result && result.alreadyApplied ? "already applied" : result.applied ? "applied" : "dry-run";
+    return [`Durable message reconciliation (${mode})`, `  command: ${result.command.id}`, `  transition: ${result.command.priorState} -> ${result.command.resultingState}`, `  successors: ${result.successors.map(item => item.id).join(", ") || "none"}`, `  replay: never`, ...("auditEventId" in result && result.auditEventId ? [`  audit event: ${result.auditEventId}`] : []), `  next: ${result.nextAction}`].join("\n");
+}

package/dist/debug/output-collision-repair.js

@@ -0,0 +1,140 @@
+import { DatabaseSync } from "node:sqlite";
+import { legacyOutputIdempotencyKey, outputPersistenceDeliveryKey } from "../data/ingest-service.js";
+import { PiboDataStore } from "../data/pibo-store.js";
+export function repairOutputCollision(input) {
+    if (!input.dataStore.exists)
+        throw new Error(`Debug store "pibo-data" not found at ${input.dataStore.path}`);
+    if (!input.reliabilityStore.exists)
+        throw new Error(`Debug store "reliability" not found at ${input.reliabilityStore.path}`);
+    if (input.apply && !input.keepExisting)
+        throw new Error("Collision apply requires --keep-existing; conflicting bodies are never selected automatically");
+    const reliability = new DatabaseSync(input.reliabilityStore.path, { readOnly: true });
+    let dead;
+    try {
+        dead = reliability.prepare("SELECT job_id AS jobId, payload_json AS payloadJson, last_error AS lastError, dead_at AS deadAt FROM pibo_dead_jobs WHERE job_id = ? AND queue IN ('output-persistence', 'output-persistence-cli')").get(input.jobId);
+    }
+    finally {
+        reliability.close();
+    }
+    if (!dead)
+        throw new Error(`Output-persistence dead letter "${input.jobId}" was not found`);
+    const collision = findCollisionEvent(dead.payloadJson, dead.lastError);
+    if (!collision)
+        throw new Error(`Dead letter "${input.jobId}" does not contain a bounded, valid collision delivery`);
+    const { event: incoming, key } = collision;
+    const data = new PiboDataStore(input.dataStore.path, { readOnly: !input.apply });
+    try {
+        const existing = data.db.prepare("SELECT stream_id AS streamId, session_id AS sessionId, event_id AS eventId, type, attributes_json AS attributesJson FROM event_log WHERE idempotency_key = ?").get(key);
+        if (!existing)
+            throw new Error(`Canonical output for collision key "${key}" was not found`);
+        const attrs = parseObject(existing.attributesJson);
+        const projections = inspectProjections(data.db, existing, incoming);
+        let auditStreamId;
+        let idempotent = false;
+        if (input.apply) {
+            const auditKey = `pibo.output.collision.reconcile:${input.jobId}:keep-existing`;
+            const prior = data.eventLog.findByIdempotencyKey(auditKey);
+            if (prior) {
+                auditStreamId = prior.streamId;
+                idempotent = true;
+            }
+            else {
+                const at = input.now?.() ?? new Date().toISOString();
+                const sequence = Number(data.db.prepare("SELECT COALESCE(MAX(session_sequence), 0) + 1 AS value FROM event_log WHERE session_id = ?").get(existing.sessionId).value);
+                auditStreamId = data.eventLog.appendEvent({
+                    sessionId: existing.sessionId, sessionSequence: sequence, topic: "pibo.audit", type: "pibo.output.collision_reconciled",
+                    source: "pibo-debug-repair", actorType: "system", actorId: "pibo-debug-repair", eventId: existing.eventId ?? undefined,
+                    idempotencyKey: auditKey, retentionClass: "audit_event", previewText: "Output collision reconciled by keeping existing canonical output",
+                    attributes: { repairVersion: 1, deadJobId: input.jobId, outputIdempotencyKey: key, decision: "keep-existing", projections, sideEffectsReplayed: false },
+                    createdAt: at, indexedAt: at,
+                }).streamId;
+            }
+        }
+        return {
+            resultType: "debug.repair.output-collision", mode: input.apply ? "apply" : "dry-run", jobId: input.jobId,
+            collisionKey: key, decision: "keep-existing", applied: Boolean(input.apply), idempotent,
+            conflict: {
+                ...(typeof attrs.identityFingerprint === "string" ? { existingFingerprint: attrs.identityFingerprint } : {}),
+                ...(collisionFingerprint(data.db, existing.sessionId, key) ? { incomingFingerprint: collisionFingerprint(data.db, existing.sessionId, key) } : {}),
+                bodyCompared: false,
+            },
+            projections, ...(auditStreamId !== undefined ? { auditStreamId } : {}),
+            warnings: [
+                "The incoming body is never compared, copied, or replayed by this repair.",
+                "Apply records an idempotent keep-existing decision and does not delete the dead letter or replay side effects.",
+            ],
+        };
+    }
+    finally {
+        data.close();
+    }
+}
+function inspectProjections(db, existing, incoming) {
+    const transcriptCount = incoming.type === "assistant_message" ? projectionCount(db, "SELECT COUNT(*) AS count FROM chat_messages WHERE session_id = ? AND source_stream_id = ? AND role = 'assistant'", existing.sessionId, existing.streamId) : 0;
+    const traceCount = projectionCount(db, "SELECT COUNT(*) AS count FROM observations WHERE session_id = ? AND event_stream_id = ?", existing.sessionId, existing.streamId);
+    const session = db.prepare("SELECT room_id AS roomId FROM sessions WHERE id = ?").get(existing.sessionId);
+    const navigationCount = session?.roomId ? projectionCount(db, "SELECT COUNT(*) AS count FROM session_navigation WHERE session_id = ? AND room_id = ?", existing.sessionId, session.roomId) : 0;
+    return {
+        transcript: incoming.type !== "assistant_message" ? "not_applicable" : projectionState(transcriptCount),
+        trace: projectionState(traceCount),
+        navigation: !session?.roomId ? "not_applicable" : projectionState(navigationCount),
+        command: "not_applicable",
+    };
+}
+function projectionState(count) { return count === 1 ? "complete" : count === 0 ? "missing" : "inconsistent"; }
+function projectionCount(db, sql, ...values) {
+    try {
+        return Number(db.prepare(sql).get(...values).count);
+    }
+    catch {
+        return 0;
+    }
+}
+function collisionFingerprint(db, sessionId, key) {
+    const row = db.prepare("SELECT json_extract(attributes_json, '$.incomingFingerprint') AS value FROM event_log WHERE session_id = ? AND type = 'pibo.output.identity_collision' AND json_extract(attributes_json, '$.outputIdempotencyKey') = ? ORDER BY stream_id DESC LIMIT 1").get(sessionId, key);
+    return row?.value ?? undefined;
+}
+function findCollisionEvent(payloadJson, lastError) {
+    let value;
+    try {
+        value = JSON.parse(payloadJson);
+    }
+    catch {
+        return undefined;
+    }
+    const key = lastError?.match(/Pibo output identity collision for "([^"]+)"/)?.[1];
+    const candidates = [];
+    const visit = (item, depth) => {
+        if (depth > 6 || candidates.length > 200 || !item || typeof item !== "object")
+            return;
+        if (!Array.isArray(item) && "type" in item && "piboSessionId" in item)
+            candidates.push(item);
+        if (Array.isArray(item))
+            for (const child of item.slice(0, 100))
+                visit(child, depth + 1);
+        else
+            for (const field of ["state", "deliveries", "event", "payload"])
+                visit(item[field], depth + 1);
+    };
+    visit(value, 0);
+    if (!key)
+        return undefined;
+    const event = candidates.find((item) => {
+        try {
+            return outputPersistenceDeliveryKey(item) === key || legacyOutputIdempotencyKey(item) === key;
+        }
+        catch {
+            return false;
+        }
+    });
+    return event ? { event, key } : undefined;
+}
+function parseObject(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/debug/output-integrity.js

@@ -188,7 +188,10 @@ export function inspectOutputIntegrity(input) {
                 findings.push(...queryRows(db, `
 					SELECT session_id AS sessionId, event_id AS eventId, stream_id AS streamId,
 						created_at AS createdAt,
-						${COLLISION_KEY_SQL} AS idempotencyKey
+						${COLLISION_KEY_SQL} AS idempotencyKey,
+						json_extract(attributes_json, '$.existingProvenance') AS existingProvenance,
+						json_extract(attributes_json, '$.incomingProvenance') AS incomingProvenance,
+						json_extract(attributes_json, '$.fieldDifferences') AS fieldDifferences
 					FROM event_log
 					WHERE type = 'pibo.output.identity_collision' ${scope.sql}
 					ORDER BY stream_id DESC
@@ -200,6 +203,9 @@ export function inspectOutputIntegrity(input) {
                     streamId: row.streamId,
                     lastAt: row.createdAt,
                     ...(row.idempotencyKey ? { idempotencyKey: row.idempotencyKey } : {}),
+                    ...(parseRecord(row.existingProvenance) ? { existingProvenance: parseRecord(row.existingProvenance) } : {}),
+                    ...(parseDifferences(row.fieldDifferences).length ? { fieldDifferences: parseDifferences(row.fieldDifferences) } : {}),
+                    ...(parseRecord(row.incomingProvenance) ? { incomingProvenance: parseRecord(row.incomingProvenance) } : {}),
                 })));
                 findings.push(...queryRows(db, `
 					WITH output_keys AS (
@@ -332,6 +338,7 @@ export function inspectOutputIntegrity(input) {
     return {
         resultType: "debug.integrity.output",
         readOnly: true,
+        health: { status: Math.max(identityCollisions, deadIdentityCollisions) >= 1 ? "degraded" : "healthy", threshold: 1, observedCollisions: Math.max(identityCollisions, deadIdentityCollisions) },
         scope: {
             ...(input.piboSessionId ? { piboSessionId: input.piboSessionId } : {}),
             ...(input.since ? { since: input.since } : {}),
@@ -411,6 +418,8 @@ export function formatOutputIntegrityAudit(audit) {
     const lines = [
         `pibo debug integrity output`,
         `readOnly\t${audit.readOnly}`,
+        `health\t${audit.health.status}`,
+        `collisionThreshold\t${audit.health.threshold}`,
         `session\t${scope}`,
         ...(audit.scope.since ? [`since\t${audit.scope.since}`] : []),
         ...(audit.scope.before ? [`before\t${audit.scope.before}`] : []),
@@ -560,6 +569,33 @@ function countRows(db, sql, params) {
 function tableExists(db, table) {
     return Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table));
 }
+function parseRecord(value) {
+    if (!value)
+        return undefined;
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseDifferences(value) {
+    if (!value)
+        return [];
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((item) => Boolean(item) && typeof item === "object" && typeof item.field === "string" && typeof item.change === "string").slice(0, 24);
+    }
+    catch {
+        return [];
+    }
+}
+function provenanceLabel(value) {
+    return value ? `${String(value.producer ?? "unknown")}/${String(value.projection ?? "unknown")}/${String(value.phase ?? "unknown")}` : "unknown";
+}
 function pendingJobFinding(row) {
     return {
         kind: "pending_output_job",
@@ -597,7 +633,7 @@ function findingDetail(finding) {
     if (finding.kind === "tool_lifecycle")
         return `tool=${finding.toolCallId ?? "-"},ordinal=${finding.toolInvocationOrdinal ?? 0},called=${finding.called ?? 0},started=${finding.started ?? 0},finished=${finding.finished ?? 0}`;
     if (finding.kind === "identity_collision")
-        return finding.idempotencyKey ?? `stream=${finding.streamId ?? "-"}`;
+        return `${finding.idempotencyKey ?? `stream=${finding.streamId ?? "-"}`},existing=${provenanceLabel(finding.existingProvenance)},incoming=${provenanceLabel(finding.incomingProvenance)},fields=${finding.fieldDifferences?.map((item) => `${item.field}:${item.change}`).join("|") ?? "unknown"}`;
     if (finding.kind === "output_key_reuse")
         return `uses=${finding.uses ?? 0},key=${finding.idempotencyKey ?? "-"}`;
     if (finding.kind === "session_trace_status")