@pasko70/pibo 3.5.0 → 3.5.1

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")

package/dist/debug/output-repair.js

@@ -43,6 +43,7 @@ export function repairOutputTurn(input) {
                 actorId: "pibo-debug-repair",
                 event: current.terminalEvent,
                 createdAt,
+                persistenceProvenance: { producer: "debug-repair", projection: "product-history", phase: "operator-repair" },
             });
             const audit = data.eventLog.appendEvent({
                 sessionId: input.piboSessionId,

package/dist/debug/storage-backup.js

@@ -1,5 +1,6 @@
 import { parseArgs } from "node:util";
 import { createStorageBackup, readStorageBackupManifest, verifyStorageBackup, restoreStorageBackup } from "../data/storage-backup.js";
+import { recordStorageMaintenance } from "../data/storage-maintenance.js";
 export async function runStorageBackupCli(args) {
     const action = args[0];
     if (!action || args.includes("--help") || args.includes("-h")) {
@@ -19,12 +20,19 @@ No source deletion, vacuum, or overwrite of an existing restore destination.`);
     const required = (name) => { const value = values[name]; if (typeof value !== "string" || !value)
         throw Error(`Missing --${name}`); return value; };
     let result;
-    if (action === "create")
-        result = await createStorageBackup({ source: required("source"), payloadRoot: required("payload-root"), destination: required("destination"), resume: values.resume, maxBytes: values["max-bytes"] ? Number(values["max-bytes"]) : undefined, maxPayloads: values["max-payloads"] ? Number(values["max-payloads"]) : undefined, maxMilliseconds: values["max-ms"] ? Number(values["max-ms"]) : undefined, maxWalGrowthBytes: values["max-wal-growth"] ? Number(values["max-wal-growth"]) : undefined });
+    if (action === "create") {
+        const source = required("source");
+        result = await createStorageBackup({ source, payloadRoot: required("payload-root"), destination: required("destination"), resume: values.resume, maxBytes: values["max-bytes"] ? Number(values["max-bytes"]) : undefined, maxPayloads: values["max-payloads"] ? Number(values["max-payloads"]) : undefined, maxMilliseconds: values["max-ms"] ? Number(values["max-ms"]) : undefined, maxWalGrowthBytes: values["max-wal-growth"] ? Number(values["max-wal-growth"]) : undefined });
+        recordStorageMaintenance(source, { operation: "backup", at: new Date().toISOString(), status: result.status, destination: required("destination") });
+    }
     else if (action === "inspect")
         result = await readStorageBackupManifest(required("archive"));
-    else if (action === "verify")
-        result = await verifyStorageBackup(required("archive"), AbortSignal.timeout(60000));
+    else if (action === "verify") {
+        const archive = required("archive");
+        result = await verifyStorageBackup(archive, AbortSignal.timeout(60000));
+        const manifest = await readStorageBackupManifest(archive);
+        recordStorageMaintenance(manifest.source, { operation: "backup", at: new Date().toISOString(), status: "verified", archive });
+    }
     else if (action === "restore")
         result = await restoreStorageBackup(required("archive"), required("destination"), AbortSignal.timeout(60000));
     else

package/dist/debug/storage-maintenance.js

@@ -0,0 +1,78 @@
+import { parseArgs } from "node:util";
+import { piboHomePath } from "../core/pibo-home.js";
+import { checkpointStorage, inspectStorageStatus, maintainStorageRetention, verifyStorage } from "../data/storage-maintenance.js";
+import { resolveDebugStore } from "./stores.js";
+export async function runStorageMaintenanceCli(args) {
+    const action = args[0];
+    if (!action || args.includes("--help") || args.includes("-h")) {
+        printHelp();
+        return;
+    }
+    const { values } = parseArgs({ args: args.slice(1), strict: true, options: {
+            store: { type: "string" }, path: { type: "string" }, json: { type: "boolean" },
+            "timeout-ms": { type: "string" }, full: { type: "boolean" }, quick: { type: "boolean" },
+            apply: { type: "boolean" }, "dry-run": { type: "boolean" }, mode: { type: "string" },
+            before: { type: "string" }, limit: { type: "string" }, "payload-root": { type: "string" },
+            "database-warn-bytes": { type: "string" }, "wal-warn-bytes": { type: "string" }, "payload-warn-bytes": { type: "string" },
+        } });
+    if (values.apply && values["dry-run"])
+        throw new Error("Choose either --dry-run or --apply");
+    const path = typeof values.path === "string" ? values.path : resolveStorePath(values.store);
+    let result;
+    if (action === "status" || action === "doctor") {
+        result = inspectStorageStatus({ path, databaseWarnBytes: numberValue(values["database-warn-bytes"]), walWarnBytes: numberValue(values["wal-warn-bytes"]), payloadWarnBytes: numberValue(values["payload-warn-bytes"]) });
+    }
+    else if (action === "verify") {
+        if (values.full && values.quick)
+            throw new Error("Choose either --quick or --full");
+        result = await verifyStorage({ path, mode: values.full ? "full" : "quick", timeoutMs: numberValue(values["timeout-ms"]) });
+    }
+    else if (action === "checkpoint") {
+        const mode = values.mode ?? "passive";
+        if (!new Set(["passive", "restart", "truncate"]).has(mode))
+            throw new Error("Checkpoint --mode must be passive, restart, or truncate");
+        result = checkpointStorage({ path, mode: mode, apply: values.apply });
+    }
+    else if (action === "retention") {
+        if (typeof values.before !== "string")
+            throw new Error("Storage retention requires --before <iso-date>");
+        result = await maintainStorageRetention({ path, before: values.before, limit: numberValue(values.limit), apply: values.apply, payloadRoot: typeof values["payload-root"] === "string" ? values["payload-root"] : piboHomePath("payloads") });
+    }
+    else
+        throw new Error(`Unknown storage action "${action}"; run pibo debug storage --help`);
+    if (values.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatText(result));
+}
+function resolveStorePath(value) {
+    if (!value || value === "pibo-data")
+        return resolveDebugStore("pibo-data").path;
+    if (value === "reliability")
+        return resolveDebugStore("reliability").path;
+    throw new Error("--store must be pibo-data or reliability; use --path for another SQLite store");
+}
+function numberValue(value) { if (value === undefined)
+    return undefined; const parsed = Number(value); if (!Number.isSafeInteger(parsed) || parsed < 0)
+    throw new Error(`Invalid numeric value "${value}"`); return parsed; }
+function formatText(value) { const object = value; const lines = [`pibo debug storage ${String(object.resultType ?? "result").split(".").at(-1)}`]; for (const [key, item] of Object.entries(object)) {
+    if (key === "resultType" || typeof item === "object")
+        continue;
+    lines.push(`${key}\t${String(item)}`);
+} if (Array.isArray(object.warnings))
+    lines.push(...object.warnings.map((warning) => `warning\t${String(warning)}`)); lines.push("", "Use --json for bounded row, size, projection, and progress detail."); return lines.join("\n"); }
+function printHelp() {
+    console.log(`pibo debug storage - bounded SQLite health and maintenance
+
+Commands:
+  status [--store pibo-data|reliability | --path <sqlite>] [--json]
+  doctor [--store pibo-data|reliability | --path <sqlite>] [--json]
+  verify [--quick|--full] [--timeout-ms <n>] [--store <name>|--path <sqlite>] [--json]
+  checkpoint [--mode passive|restart|truncate] [--dry-run|--apply] [--store <name>|--path <sqlite>] [--json]
+  retention --before <iso-date> [--limit <1..10000>] [--dry-run|--apply] [--payload-root <dir>] [--store <name>|--path <sqlite>] [--json]
+
+Status is read-only and reports DB/WAL/SHM/payload size, pages/freelist, bounded row counts, payload-reference integrity, maintenance metadata, and degraded thresholds.
+Verification runs in a cancellable worker. Timeout is partial and never healthy. Quick/full checks can still be I/O intensive; use backup verification or offline checks when the online budget is insufficient.
+Checkpoint and retention default to dry-run. Apply is bounded and audited in the database maintenance sidecar. Retention deletes only eligible live_delta rows; chat messages, audit events, idempotency evidence, and referenced payloads are preserved.
+`);
+}

package/dist/gateway/cli.js

@@ -231,14 +231,40 @@ function activeRun(value) {
         piboSessionId: stringValue(obj.controllerPiboSessionId) ?? stringValue(obj.piboSessionId),
     };
 }
+function runJobReliability(value) {
+    const obj = objectValue(value);
+    if (!obj || (obj.status !== "ok" && obj.status !== "degraded")
+        || !Number.isInteger(obj.expiredOrphanRunJobs) || Number(obj.expiredOrphanRunJobs) < 0
+        || !Number.isInteger(obj.orphanRunDeadLetters) || Number(obj.orphanRunDeadLetters) < 0)
+        return undefined;
+    return {
+        status: obj.status,
+        expiredOrphanRunJobs: Number(obj.expiredOrphanRunJobs),
+        orphanRunDeadLetters: Number(obj.orphanRunDeadLetters),
+    };
+}
+function durableMessageQueueStatus(value) {
+    const obj = objectValue(value);
+    if (!obj)
+        return undefined;
+    const status = obj.status === "healthy" || obj.status === "degraded" || obj.status === "ambiguous" ? obj.status : undefined;
+    const storage = objectValue(obj.storage);
+    const counts = Array.isArray(obj.counts) ? obj.counts.flatMap(value => { const row = objectValue(value); return row ? [{ state: stringValue(row.state), delivery: stringValue(row.delivery), count: numberValue(row.count), bytes: numberValue(row.bytes) }] : []; }) : undefined;
+    const affectedScopes = Array.isArray(obj.affectedScopes) ? obj.affectedScopes.flatMap(value => { const row = objectValue(value); return row ? [{ sessionId: stringValue(row.sessionId), roomId: stringValue(row.roomId), blockingCommandId: stringValue(row.blockingCommandId), blockedSince: numberValue(row.blockedSince), blockedSuccessors: numberValue(row.blockedSuccessors) }] : []; }) : undefined;
+    return { status, storage: storage ? { available: booleanValue(storage.available), error: stringValue(storage.error) } : undefined, counts, interruptedPredecessors: numberValue(obj.interruptedPredecessors), blockedSuccessors: numberValue(obj.blockedSuccessors), expiredOwnedLeases: numberValue(obj.expiredOwnedLeases), oldestDispatchableWaitMs: numberValue(obj.oldestDispatchableWaitMs), oldestBlockedWaitMs: numberValue(obj.oldestBlockedWaitMs), affectedScopes, degradedReasons: Array.isArray(obj.degradedReasons) && obj.degradedReasons.every(v => typeof v === "string") ? obj.degradedReasons : undefined, admissionCapacity: obj.admissionCapacity, bounded: obj.bounded };
+}
 function parseGatewaySafetyPayload(payload, reachable) {
     const obj = objectValue(payload);
     const mode = obj && (obj.mode === "dev" || obj.mode === "prod" || obj.mode === "fallback") ? obj.mode : "unknown";
     const runtimeStatuses = Array.isArray(obj?.runtimeStatuses) ? obj.runtimeStatuses.map(runtimeStatus).filter((item) => Boolean(item)) : [];
     const activeRuns = Array.isArray(obj?.activeRuns) ? obj.activeRuns.map(activeRun).filter((item) => Boolean(item)) : [];
+    const reliability = obj?.reliability === undefined ? undefined : runJobReliability(obj.reliability);
+    const durableMessageQueue = durableMessageQueueStatus(obj?.durableMessageQueue);
     const incomplete = !Array.isArray(obj?.runtimeStatuses) || !Array.isArray(obj?.activeRuns)
-        || runtimeStatuses.length !== obj.runtimeStatuses.length || activeRuns.length !== obj.activeRuns.length;
-    return { reachable, mode, generation: stringValue(obj?.generation), health: obj?.health, runtimeStatuses, activeRuns, ambiguous: incomplete || booleanValue(obj?.ambiguous) };
+        || runtimeStatuses.length !== obj.runtimeStatuses.length || activeRuns.length !== obj.activeRuns.length
+        || (obj?.reliability !== undefined && !reliability)
+        || (obj?.durableMessageQueue !== undefined && !durableMessageQueue?.status);
+    return { reachable, mode, generation: stringValue(obj?.generation), health: obj?.health, runtimeStatuses, activeRuns, reliability, durableMessageQueue, ambiguous: incomplete || booleanValue(obj?.ambiguous) };
 }
 export function checkActiveWork(status, target = "web") {
     const reasons = [];
@@ -337,7 +363,8 @@ function printSafetyStatus(target, status) {
     console.log(`  mode: ${status.mode}`);
     if (status.error)
         console.log(`  status error: ${status.error}`);
-    console.log(`  runtime sessions: ${status.runtimeStatuses.length}`);
+    console.log("  runtime queue layer:");
+    console.log(`    sessions: ${status.runtimeStatuses.length}`);
     for (const session of status.runtimeStatuses) {
         console.log(`    ${session.piboSessionId ?? "unknown"}: processing=${session.processing === true} streaming=${session.streaming === true} queued=${session.queuedMessages ?? 0}`);
         if (session.activeEventId)
@@ -359,6 +386,31 @@ function printSafetyStatus(target, status) {
     console.log(`  active yielded runs: ${status.activeRuns.length}`);
     for (const run of status.activeRuns)
         console.log(`    ${run.runId ?? "unknown"}: ${run.status ?? "active"}${run.toolName ? ` (${run.toolName})` : ""} session=${run.piboSessionId ?? "unknown"}`);
+    if (status.reliability) {
+        console.log(`  run-job reliability: ${status.reliability.status}`);
+        console.log(`    expired orphan jobs: ${status.reliability.expiredOrphanRunJobs}`);
+        console.log(`    orphan DLQ records: ${status.reliability.orphanRunDeadLetters}`);
+    }
+    console.log("  durable message queue layer:");
+    const durable = status.durableMessageQueue;
+    if (!durable)
+        console.log("    status: unavailable (gateway app did not report this layer)");
+    else {
+        console.log(`    status: ${durable.status ?? "ambiguous"}`);
+        console.log(`    storage: ${durable.storage?.available === true ? "available" : "unavailable"}${durable.storage?.error ? ` (${durable.storage.error})` : ""}`);
+        for (const row of durable.counts ?? [])
+            console.log(`    ${row.delivery ?? "unknown"}.${row.state ?? "unknown"}: count=${row.count ?? 0} bytes=${row.bytes ?? 0}`);
+        console.log(`    interrupted predecessors: ${durable.interruptedPredecessors ?? 0}`);
+        console.log(`    FIFO-blocked successors: ${durable.blockedSuccessors ?? 0}`);
+        console.log(`    expired owned leases: ${durable.expiredOwnedLeases ?? 0}`);
+        console.log(`    oldest dispatchable wait: ${durable.oldestDispatchableWaitMs ?? 0}ms`);
+        console.log(`    oldest blocked wait: ${durable.oldestBlockedWaitMs ?? 0}ms`);
+        for (const scope of durable.affectedScopes ?? [])
+            console.log(`    affected session=${scope.sessionId ?? "unknown"} room=${scope.roomId ?? "unknown"} blocker=${scope.blockingCommandId ?? "unknown"} successors=${scope.blockedSuccessors ?? 0}`);
+        for (const reason of durable.degradedReasons ?? [])
+            console.log(`    degraded: ${reason}`);
+    }
+    console.log("  next: pibo debug message-queue");
 }
 function managerRequiresShell(command) {
     return process.platform === "win32" && /\.(?:cmd|bat)$/i.test(command);
@@ -385,8 +437,11 @@ async function waitForManagedGatewayHealth(target) {
 async function runManagedGatewayCommand(target, command, args, argv = process.argv) {
     if (command === "status" || command === "doctor") {
         const status = await readGatewaySafetyStatus(target);
-        printSafetyStatus(target, status);
-        if (target === "web") {
+        if (args.includes("--json"))
+            console.log(JSON.stringify({ ...status, nextCommands: [`pibo gateway ${target} doctor`, `pibo debug message-queue`] }, null, 2));
+        else
+            printSafetyStatus(target, status);
+        if (target === "web" && !args.includes("--json")) {
             const active = checkActiveWork(status, target);
             if (active.unsafe) {
                 console.log("  restart safety: blocked");
@@ -397,8 +452,16 @@ async function runManagedGatewayCommand(target, command, args, argv = process.ar
                 console.log("  restart safety: idle");
             printRestartApproval(status);
         }
-        if (command === "doctor")
-            process.exitCode = status.reachable && !status.error && status.mode === expectedMode(target) ? 0 : 1;
+        if (command === "doctor") {
+            process.exitCode = status.reachable
+                && !status.error
+                && status.mode === expectedMode(target)
+                && status.reliability?.status !== "degraded"
+                && status.durableMessageQueue?.status === "healthy"
+                && status.durableMessageQueue.storage?.available === true
+                ? 0
+                : 1;
+        }
         return true;
     }
     if (command === "start") {
@@ -730,6 +793,7 @@ Commands:
   dev doctor       Check dev gateway health
 
 Options:
+  --json         Print status or doctor output as JSON with next discovery commands
   --force --confirm <snapshot-token>
                  Restart only the work explicitly approved from web status
 

package/dist/gateway/server.js

@@ -427,6 +427,7 @@ export class PiboGatewayServer {
             listSessionRuntimeStatuses: () => this.requireRouter().listSessionRuntimeStatuses(),
             getRuntimeCapacityStatus: () => this.requireRouter().getRuntimeCapacityStatus(),
             listRuns: (options) => this.requireRouter().listRuns(options),
+            getRunJobReliabilityStatus: () => this.requireRouter().getRunJobReliabilityStatus(),
             snapshotSignalSession: (piboSessionId) => this.requireRouter().snapshotSignalSession(piboSessionId),
             snapshotSignalTree: (rootPiboSessionId) => this.requireRouter().snapshotSignalTree(rootPiboSessionId),
             snapshotSignalStatuses: () => this.requireRouter().snapshotSignalStatuses(),