npm - @pasko70/pibo - Versions diffs - 3.1.3 → 3.1.4 - Mend

@pasko70/pibo 3.1.3 → 3.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/dist/apps/chat/data/timeline-query-service.js +5 -2
package/dist/apps/chat/output-compactor.js +33 -30
package/dist/apps/chat/trace-v2.js +1 -0
package/dist/apps/chat/trace.js +3 -1
package/dist/apps/chat/web-app.js +106 -65
package/dist/apps/chat-ui/assets/{dist-BNzch-mL.js → dist-BOqsX6_s.js} +1 -1
package/dist/apps/chat-ui/assets/{dist-CoA9zNTP.js → dist-BcUbdOKJ.js} +1 -1
package/dist/apps/chat-ui/assets/{dist-liw1S7HS.js → dist-DkpIJ_Pp.js} +1 -1
package/dist/apps/chat-ui/assets/{dist-7DhHpLCA.js → dist-a0mykCz7.js} +1 -1
package/dist/apps/chat-ui/assets/{dist-DDRlEGPR.js → dist-qDZ-CdlK.js} +1 -1
package/dist/apps/chat-ui/assets/{index-BKp6zKIe.js → index-G2ic-FSG.js} +89 -89
package/dist/apps/chat-ui/index.html +1 -1
package/dist/apps/chat-vscode-web/assets/{index-CKC-46jZ.js → index-zQ1fNz5K.js} +1 -1
package/dist/apps/chat-vscode-web/index.html +1 -1
package/dist/cli-session/localSessionSource.js +26 -20
package/dist/core/output-persistence-retry.js +23 -1
package/dist/core/output-render-sequence.js +33 -9
package/dist/data/ingest-service.js +8 -0
package/dist/debug/index.js +294 -2
package/dist/debug/output-integrity.js +608 -0
package/dist/debug/output-repair.js +584 -0
package/dist/debug/trace.js +2 -0
package/dist/reliability/store.js +2 -2
package/dist/sessions/pibo-data-store.js +26 -20
package/dist/shared/trace-engine.js +5 -2
package/dist/shared/trace-event-projection.js +74 -0
package/dist/shared/trace-page-merge.js +31 -5
package/npm-shrinkwrap.json +2 -2
package/package.json +1 -1

package/dist/apps/chat-vscode-web/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<meta name="theme-color" content="#101d22" />
 		<title>Pibo</title>
-		<script type="module" crossorigin src="/apps/chat-vscode/assets/index-CKC-46jZ.js"></script>
+		<script type="module" crossorigin src="/apps/chat-vscode/assets/index-zQ1fNz5K.js"></script>
 		<link rel="stylesheet" crossorigin href="/apps/chat-vscode/assets/index-SluZr_-r.css">
 	</head>
 	<body>

package/dist/cli-session/localSessionSource.js CHANGED Viewed

@@ -7,7 +7,7 @@ import { OutputPersistenceRetryQueue, } from "../core/output-persistence-retry.j
 import { getDefaultPiboWorkspace } from "../core/workspace.js";
 import { buildTraceView } from "../apps/chat/trace.js";
 import { storedPiboEventFromV2Row, } from "../apps/chat/data/chat-data-mappers.js";
-import { ChatDataIngestService, outputIdempotencyKey, outputPersistenceDeliveryKey } from "../data/ingest-service.js";
+import { ChatDataIngestService, outputIdempotencyKey, outputPersistenceDeliveryKey, outputPersistenceErrorIsRetryable } from "../data/ingest-service.js";
 import { OutputCompactor } from "../apps/chat/output-compactor.js";
 import { isPiboOutputEvent } from "../apps/chat/output-event-policy.js";
 import { ChatRoomService } from "../apps/chat/data/room-service.js";
@@ -597,7 +597,9 @@ export class LocalCliSessionSource {
         const session = this.sessionStore.get(event.piboSessionId);
         if (!session)
             return;
-        const positionedEvent = this.outputRenderSequencer.position(event);
+        const positionedEvent = validRenderSequence(event.renderSequence)
+            ? event
+            : this.outputRenderSequencer.position(event);
         const compacted = this.outputCompactor.prepare(positionedEvent);
         if (compacted.persistedEvents.length === 0) {
             compacted.ack();
@@ -608,7 +610,7 @@ export class LocalCliSessionSource {
                 piboSessionId: session.id,
                 deliveries: compacted.persistedEvents.map((persistedEvent) => ({ event: persistedEvent })),
             };
-            this.outputPersistenceRetries.enqueue(this.createOutputPersistenceJob(persistenceState, () => compacted.ack(), () => compacted.rollback()));
+            this.outputPersistenceRetries.enqueue(this.createOutputPersistenceJob(persistenceState, () => compacted.ack(), () => compacted.discard()));
         }
         for (const liveEvent of compacted.liveEvents)
             this.recordOutputEvent(liveEvent);
@@ -621,6 +623,7 @@ export class LocalCliSessionSource {
             eventId: firstEvent ? outputPersistenceDeliveryKey(firstEvent) : undefined,
             payload: persistenceState,
             run: (retryContext) => this.deliverOutputPersistenceState(retryContext),
+            isRetryable: outputPersistenceErrorIsRetryable,
             onSuccess,
             onDeadLetter,
         };
@@ -632,15 +635,25 @@ export class LocalCliSessionSource {
         const session = this.sessionStore.get(persistenceState.piboSessionId);
         if (!session)
             throw new Error(`No session available for ${persistenceState.piboSessionId}`);
+        const errors = [];
         for (const delivery of persistenceState.deliveries) {
             if (delivery.persisted)
                 continue;
-            if (!this.ingestOutputEvent(session, delivery.event)) {
-                throw new Error(`Failed to persist ${outputPersistenceDeliveryKey(delivery.event)}`);
+            try {
+                this.ingestOutputEvent(session, delivery.event);
+            }
+            catch (error) {
+                errors.push(error instanceof Error ? error : new Error(String(error)));
+                continue;
             }
             delivery.persisted = true;
             retryContext.updatePayload(persistenceState);
         }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1) {
+            throw new AggregateError(errors, `Failed to persist one or more output deliveries: ${errors.map((error) => error.message).join("; ")}`);
+        }
     }
     recordOutputEvent(event) {
         const positionedEvent = validRenderSequence(event.renderSequence)
@@ -741,21 +754,14 @@ export class LocalCliSessionSource {
     }
     ingestOutputEvent(session, event) {
         if (!this.ingestService)
-            return true;
-        try {
-            this.ingestService.ingestOutputEvent({
-                session,
-                roomId: roomIdFromSession(session),
-                actorId: session.profile,
-                event,
-                createdAt: this.now(),
-            });
-            return true;
-        }
-        catch {
-            // The caller retains the prepared compaction and retries this exact event identity.
-            return false;
-        }
+            return;
+        this.ingestService.ingestOutputEvent({
+            session,
+            roomId: roomIdFromSession(session),
+            actorId: session.profile,
+            event,
+            createdAt: this.now(),
+        });
     }
     buildStatus(session) {
         const runtime = this.router?.getSessionRuntimeStatus?.(session.id);

package/dist/core/output-persistence-retry.js CHANGED Viewed

@@ -20,6 +20,7 @@ class LostOutputPersistenceClaimError extends Error {
 export class OutputPersistenceRetryQueue {
     pending = new Map();
     deadLetters = [];
+    counters = { retriable: 0, permanent: 0, quarantined: 0 };
     maxPending;
     maxAttempts;
     baseDelayMs;
@@ -96,6 +97,7 @@ export class OutputPersistenceRetryQueue {
     quarantine(reasonCode) {
         if (this.disposed)
             return;
+        this.counters.quarantined += 1;
         this.recordDeadLetter({ key: `quarantine:${randomUUID()}`, payload: null, run() { } }, new Error(reasonCode), 0, reasonCode, true);
     }
     recover(factory) {
@@ -164,6 +166,7 @@ export class OutputPersistenceRetryQueue {
             pending: this.pending.size,
             activeHeartbeats: [...this.pending.values()].filter((job) => job.heartbeatTimer !== undefined).length,
             deadLetters: this.deadLetters.map((entry) => ({ ...entry })),
+            counters: { ...this.counters },
         };
     }
     startAttempt(job, forcePending) {
@@ -209,6 +212,7 @@ export class OutputPersistenceRetryQueue {
             const parsed = parseDurableEnvelope(claimed.payload);
             if (!parsed.envelope) {
                 this.durableStore?.quarantineJob(claimed.jobId, parsed.reason, correlationFields(job));
+                this.counters.quarantined += 1;
                 this.pending.delete(job.key);
                 return;
             }
@@ -253,8 +257,24 @@ export class OutputPersistenceRetryQueue {
             if (this.disposed)
                 return;
             job.durableClaimed = false;
+            if (error instanceof LostOutputPersistenceClaimError) {
+                this.reconcileClaimMiss(job);
+                return;
+            }
+            const retryable = job.isRetryable?.(error) ?? true;
+            if (!retryable) {
+                if (job.durableJobId && !this.durableStore?.fail(job.durableJobId, this.workerId, errorMessage(error), job.durableClaimToken, "permanent")) {
+                    this.reconcileClaimMiss(job);
+                    return;
+                }
+                this.counters.permanent += 1;
+                this.pending.delete(job.key);
+                this.recordDeadLetter(job, error, job.attempts, "permanent", false);
+                return;
+            }
+            this.counters.retriable += 1;
             if (job.durableJobId) {
-                const retried = error instanceof LostOutputPersistenceClaimError ? false : this.durableStore?.retry(job.durableJobId, this.workerId, {
+                const retried = this.durableStore?.retry(job.durableJobId, this.workerId, {
                     error: errorMessage(error),
                     delayMs: retryDelay(job.attempts, this.baseDelayMs, this.maxDelayMs),
                     claimToken: job.durableClaimToken,
@@ -346,6 +366,7 @@ export class OutputPersistenceRetryQueue {
                 const parsed = parseDurableEnvelope(durableJob.payload);
                 if (!parsed.envelope) {
                     this.durableStore.quarantineJob(durableJob.jobId, parsed.reason);
+                    this.counters.quarantined += 1;
                     continue;
                 }
                 const envelope = parsed.envelope;
@@ -364,6 +385,7 @@ export class OutputPersistenceRetryQueue {
                 }
                 catch {
                     this.durableStore.quarantineJob(durableJob.jobId, "payload_invalid");
+                    this.counters.quarantined += 1;
                     continue;
                 }
                 const pending = {

package/dist/core/output-render-sequence.js CHANGED Viewed

@@ -106,25 +106,34 @@ export class OutputRenderSequencer {
         const parts = state.outputParts.get(key) ?? [];
         if (!state.outputParts.has(key))
             state.outputParts.set(key, parts);
-        const exact = parts.find((part) => part.fingerprints.has(transition.fingerprint));
+        const suppliedPart = transition.suppliedIndex === undefined
+            ? undefined
+            : parts.find((part) => part.index === transition.suppliedIndex);
+        if (transition.suppliedIndex !== undefined && (transition.canonicalIndex || suppliedPart)) {
+            this.highWaterStore?.observeOutputPart?.({ ...transition, index: transition.suppliedIndex });
+            this.recordOutputPart(parts, transition.suppliedIndex, transition.terminal);
+            this.trimOutputParts(state);
+            return event;
+        }
         const latestOpen = [...parts].reverse().find((part) => !part.closed);
         const localMaximum = parts.reduce((maximum, part) => Math.max(maximum, part.index), -1);
-        const localIndex = exact?.index
-            ?? latestOpen?.index
+        const localIndex = latestOpen?.index
             ?? (transition.proposedIndex > localMaximum ? transition.proposedIndex : localMaximum + 1);
-        const index = validRenderSequence(event.renderSequence) || exact || latestOpen
+        const index = latestOpen
             ? localIndex
             : this.highWaterStore?.claimOrAttachOutputPart?.({ ...transition, proposedIndex: localIndex }) ?? localIndex;
+        this.recordOutputPart(parts, index, transition.terminal);
+        this.trimOutputParts(state);
+        return withOutputPartIndex(event, transition.kind, index);
+    }
+    recordOutputPart(parts, index, terminal) {
         let part = parts.find((candidate) => candidate.index === index);
         if (!part) {
-            part = { index, fingerprints: new Set(), closed: false };
+            part = { index, closed: false };
             parts.push(part);
         }
-        part.fingerprints.add(transition.fingerprint);
-        if (transition.terminal)
+        if (terminal)
             part.closed = true;
-        this.trimOutputParts(state);
-        return withOutputPartIndex(event, transition.kind, index);
     }
     trimOutputParts(state) {
         let total = 0;
@@ -316,6 +325,9 @@ function outputPartTransition(event, activeEventId) {
             eventId,
             kind: "assistant",
             proposedIndex: event.assistantIndex ?? event.contentIndex ?? 0,
+            ...(validOutputPartIndex(event.assistantIndex)
+                ? { suppliedIndex: event.assistantIndex, canonicalIndex: validRenderSequence(event.renderSequence) }
+                : {}),
             fingerprint: outputPartFingerprint(event),
             identityFingerprint: outputIdentityFingerprint(event),
             terminal: event.type === "assistant_message",
@@ -327,6 +339,9 @@ function outputPartTransition(event, activeEventId) {
             eventId,
             kind: "thinking",
             proposedIndex: event.thinkingIndex ?? event.contentIndex ?? 0,
+            ...(validOutputPartIndex(event.thinkingIndex)
+                ? { suppliedIndex: event.thinkingIndex, canonicalIndex: validRenderSequence(event.renderSequence) }
+                : {}),
             fingerprint: outputPartFingerprint(event),
             identityFingerprint: outputIdentityFingerprint(event),
             terminal: event.type === "thinking_finished",
@@ -338,6 +353,9 @@ function outputPartTransition(event, activeEventId) {
             eventId,
             kind: "usage",
             proposedIndex: event.usageIndex ?? 0,
+            ...(validOutputPartIndex(event.usageIndex)
+                ? { suppliedIndex: event.usageIndex, canonicalIndex: validRenderSequence(event.renderSequence) }
+                : {}),
             fingerprint: outputPartFingerprint(event),
             identityFingerprint: outputIdentityFingerprint(event),
             terminal: true,
@@ -349,6 +367,9 @@ function outputPartTransition(event, activeEventId) {
             eventId,
             kind: "compaction",
             proposedIndex: event.compactionIndex ?? 0,
+            ...(validOutputPartIndex(event.compactionIndex)
+                ? { suppliedIndex: event.compactionIndex, canonicalIndex: validRenderSequence(event.renderSequence) }
+                : {}),
             fingerprint: outputPartFingerprint(event),
             identityFingerprint: outputIdentityFingerprint(event),
             terminal: event.type === "compaction_end",
@@ -356,6 +377,9 @@ function outputPartTransition(event, activeEventId) {
     }
     return undefined;
 }
+function validOutputPartIndex(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
 export function outputIdentityFingerprint(event) {
     const payload = { ...event };
     delete payload.renderSequence;

package/dist/data/ingest-service.js CHANGED Viewed

@@ -14,6 +14,14 @@ export class PiboOutputIdentityCollisionError extends Error {
         this.name = "PiboOutputIdentityCollisionError";
     }
 }
+export function outputPersistenceErrorIsRetryable(error) {
+    if (error instanceof PiboOutputIdentityCollisionError)
+        return false;
+    if (error instanceof AggregateError) {
+        return error.errors.length === 0 || error.errors.some(outputPersistenceErrorIsRetryable);
+    }
+    return true;
+}
 const INLINE_MESSAGE_PAYLOAD_THRESHOLD_BYTES = 16 * 1024;
 const INLINE_JSON_PAYLOAD_THRESHOLD_BYTES = 16 * 1024;
 export class ChatDataIngestService {

package/dist/debug/index.js CHANGED Viewed

@@ -53,6 +53,18 @@ export async function runDebugCli(argv = process.argv) {
             await runDebugJobs(args.slice(1));
             return;
         }
+        if (args[0] === "integrity") {
+            await runDebugIntegrity(args.slice(1));
+            return;
+        }
+        if (args[0] === "persistence") {
+            await runDebugPersistence(args.slice(1));
+            return;
+        }
+        if (args[0] === "repair") {
+            await runDebugRepair(args.slice(1));
+            return;
+        }
         if (args[0] === "runs") {
             await runDebugRuns(args.slice(1));
             return;
@@ -86,6 +98,208 @@ export async function runDebugCli(argv = process.argv) {
         process.exitCode = 1;
     }
 }
+async function runDebugIntegrity(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printDebugIntegrityDiscovery();
+        return;
+    }
+    if (args[0] !== "output") {
+        throw new Error(`Unknown pibo debug integrity command "${args[0]}". Run pibo debug integrity --help.`);
+    }
+    if (args[1] === "--help" || args[1] === "-h") {
+        printDebugIntegrityDiscovery();
+        return;
+    }
+    await runOutputPersistenceInspection(args.slice(1), { allowPositionalSession: true, deadLettersOnly: false });
+}
+async function runDebugPersistence(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printDebugPersistenceDiscovery();
+        return;
+    }
+    const command = args[0];
+    if (command !== "audit" && command !== "dead-letters") {
+        throw new Error(`Unknown pibo debug persistence command "${command}". Run pibo debug persistence --help.`);
+    }
+    if (args[1] === "--help" || args[1] === "-h") {
+        if (command === "audit")
+            printDebugPersistenceAuditHelp();
+        else
+            printDebugPersistenceDeadLettersHelp();
+        return;
+    }
+    await runOutputPersistenceInspection(args.slice(1), {
+        allowPositionalSession: false,
+        deadLettersOnly: command === "dead-letters",
+    });
+}
+async function runOutputPersistenceInspection(args, mode) {
+    validateOutputPersistenceInspectionArgs(args, mode.allowPositionalSession);
+    const options = parseOptions(args);
+    if (options.after && !Number.isFinite(Date.parse(options.after)))
+        throw new Error("--since must be an ISO date");
+    if (options.before && !Number.isFinite(Date.parse(options.before)))
+        throw new Error("--before must be an ISO date");
+    if (options.after && options.before && Date.parse(options.after) >= Date.parse(options.before)) {
+        throw new Error("--since must be earlier than --before");
+    }
+    const { formatJson } = await import("./sql.js");
+    const { formatOutputIntegrityAudit, formatOutputPersistenceDeadLetters, inspectOutputIntegrity, outputPersistenceDeadLettersFromAudit, } = await import("./output-integrity.js");
+    const audit = inspectOutputIntegrity({
+        dataStore: resolveDebugStore("pibo-data"),
+        reliabilityStore: resolveDebugStore("reliability"),
+        piboSessionId: options.key ?? (mode.allowPositionalSession ? options.positionals[0] : undefined),
+        since: options.after,
+        before: options.before,
+        limit: options.limit,
+        findingMode: mode.deadLettersOnly ? "dead_letters" : "all",
+    });
+    if (mode.deadLettersOnly) {
+        const result = outputPersistenceDeadLettersFromAudit(audit);
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatOutputPersistenceDeadLetters(result));
+        return;
+    }
+    if (options.json)
+        console.log(formatJson(audit));
+    else
+        console.log(formatOutputIntegrityAudit(audit));
+}
+function validateOutputPersistenceInspectionArgs(args, allowPositionalSession) {
+    const valueOptions = new Set(["--session", "--since", "--before", "--limit"]);
+    let positionalCount = 0;
+    let hasSessionOption = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--json")
+            continue;
+        if (arg === "--apply" || arg === "--dry-run") {
+            throw new Error(`Output persistence inspection is read-only; ${arg} is not supported`);
+        }
+        if (valueOptions.has(arg)) {
+            const value = args[index + 1];
+            if (!value || value.startsWith("-"))
+                throw new Error(`${arg} requires a value`);
+            if (arg === "--session")
+                hasSessionOption = true;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            throw new Error(`Unknown output persistence inspection option "${arg}"`);
+        }
+        positionalCount += 1;
+    }
+    if (!allowPositionalSession && positionalCount > 0) {
+        throw new Error("Use --session <pibo-session-id> to scope persistence inspection");
+    }
+    if (allowPositionalSession && positionalCount > 1) {
+        throw new Error("Use at most one positional Pibo Session ID");
+    }
+    if (allowPositionalSession && hasSessionOption && positionalCount > 0) {
+        throw new Error("Use either a positional Pibo Session ID or --session, not both");
+    }
+}
+async function runDebugRepair(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printDebugRepairDiscovery();
+        return;
+    }
+    if (args[0] !== "output") {
+        throw new Error(`Unknown pibo debug repair command "${args[0]}". Run pibo debug repair --help.`);
+    }
+    if (args[1] === "--help" || args[1] === "-h") {
+        printDebugRepairDiscovery();
+        return;
+    }
+    const repairArgs = args.slice(1);
+    validateOutputRepairArgs(repairArgs);
+    const options = parseOptions(repairArgs);
+    if (options.apply && options.dryRun)
+        throw new Error("Choose either --dry-run or --apply");
+    if (options.destructive)
+        throw new Error("Use --apply for output repair; --destructive is not supported");
+    if (options.after && !Number.isFinite(Date.parse(options.after)))
+        throw new Error("--since must be an ISO date");
+    if (options.before && !Number.isFinite(Date.parse(options.before)))
+        throw new Error("--before must be an ISO date");
+    if (options.after && options.before && Date.parse(options.after) >= Date.parse(options.before)) {
+        throw new Error("--since must be earlier than --before");
+    }
+    if (options.key && options.positionals.length > 1)
+        throw new Error("With --session, provide at most one positional <event-id>");
+    const piboSessionId = options.key ?? options.positionals[0];
+    const eventId = options.key ? options.positionals[0] : options.positionals[1];
+    if (!piboSessionId)
+        throw new Error("pibo debug repair output requires a session id or --session <pibo-session-id>");
+    const { formatJson } = await import("./sql.js");
+    const { formatOutputTurnRepair, readOutputRepairAdapterEvidence, repairOutputTurn, repairOutputTurns, } = await import("./output-repair.js");
+    const store = resolveDebugStore("pibo-data");
+    const reliabilityStore = resolveDebugStore("reliability");
+    const adapterEvidence = await readOutputRepairAdapterEvidence({ store, piboSessionId });
+    const result = eventId
+        ? repairOutputTurn({ store, reliabilityStore, piboSessionId, eventId, adapterEvidence, apply: options.apply })
+        : repairOutputTurns({
+            store,
+            reliabilityStore,
+            piboSessionId,
+            since: options.after,
+            before: options.before,
+            limit: options.limit,
+            adapterEvidence,
+            apply: options.apply,
+        });
+    if (options.json)
+        console.log(formatJson(result));
+    else
+        console.log(formatOutputTurnRepair(result));
+}
+function validateOutputRepairArgs(args) {
+    const valueOptions = new Set(["--session", "--since", "--before", "--limit"]);
+    const flagOptions = new Set(["--json", "--dry-run", "--apply", "--destructive"]);
+    const seen = new Set();
+    const positionals = [];
+    let hasSessionOption = false;
+    let hasScopeOption = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (flagOptions.has(arg)) {
+            if (seen.has(arg))
+                throw new Error(`Output repair option ${arg} may only be provided once`);
+            seen.add(arg);
+            continue;
+        }
+        if (valueOptions.has(arg)) {
+            if (seen.has(arg))
+                throw new Error(`Output repair option ${arg} may only be provided once`);
+            const value = args[index + 1];
+            if (!value || value.startsWith("-"))
+                throw new Error(`${arg} requires a value`);
+            seen.add(arg);
+            if (arg === "--session")
+                hasSessionOption = true;
+            else
+                hasScopeOption = true;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("-"))
+            throw new Error(`Unknown output repair option "${arg}"`);
+        positionals.push(arg);
+    }
+    if (hasSessionOption) {
+        if (positionals.length > 1)
+            throw new Error("With --session, provide at most one positional <event-id>");
+    }
+    else if (positionals.length !== 2) {
+        throw new Error("Exact output repair requires <pibo-session-id> <event-id>; use --session for scoped repair");
+    }
+    if (hasScopeOption && positionals.length > 0) {
+        throw new Error("--since, --before, and --limit are only supported for scoped repair without an <event-id>");
+    }
+}
 async function runDebugResources(args) {
     if (args[0] === "--help" || args[0] === "-h") {
         printDebugResourcesDiscovery();
@@ -853,10 +1067,10 @@ function parseOptions(args) {
             index += 1;
             continue;
         }
-        if (arg === "--after") {
+        if (arg === "--after" || arg === "--since") {
             const value = args[index + 1];
             if (!value)
-                throw new Error("--after requires a value");
+                throw new Error(`${arg} requires a value`);
             parsed.after = value;
             index += 1;
             continue;
@@ -1103,6 +1317,9 @@ Commands:
   tool     Inspect one grouped tool call
   failures List failed tool calls and trace/session errors
   jobs     Inspect durable Pibo jobs and DLQ
+  persistence Audit output persistence and related dead letters
+  integrity Compatibility alias for output persistence audit
+  repair   Dry-run or apply explicit persisted-output repairs
   runs     Inspect durable yielded runs
   resources Show gateway memory reserve, related child processes, and heavy daemons
   signals  Inspect live session signal snapshots through Chat Web APIs
@@ -1117,6 +1334,8 @@ Next:
   pibo debug messages <pibo-session-id> list
   pibo debug trace <pibo-session-id> --running-only
   pibo debug events stream --topic pibo.output
+  pibo debug persistence
+  pibo debug repair output <pibo-session-id> <event-id> --dry-run
   pibo debug agents <parent-session-id> list
   pibo debug resources --json
   pibo debug signals tree ps_...
@@ -1125,6 +1344,79 @@ Next:
   pibo debug pty run -- pibo tui:sessions --demo
 `);
 }
+function printDebugIntegrityDiscovery() {
+    console.log(`pibo debug integrity - compatibility alias for output persistence audit
+Usage:
+  pibo debug integrity output [<pibo-session-id>] [--since <iso-date>] [--before <iso-date>] [--limit n] [--json]
+Next:
+  pibo debug persistence audit --help
+`);
+}
+function printDebugPersistenceDiscovery() {
+    console.log(`pibo debug persistence - inspect persisted output without changing it
+Commands:
+  audit         Audit output lifecycle, identity, queue, and trace-status integrity
+  dead-letters  List output-persistence dead letters with collision relationships
+Next:
+  pibo debug persistence audit --help
+  pibo debug persistence dead-letters --help
+`);
+}
+function printDebugPersistenceAuditHelp() {
+    console.log(`pibo debug persistence audit - read-only output integrity audit
+Usage:
+  pibo debug persistence audit [--session <pibo-session-id>] [--since <iso-date>] [--before <iso-date>] [--limit n] [--json]
+Reports:
+  Incomplete or invalid turn, reasoning, and tool lifecycles; identity collisions; reused output keys; session/trace-status mismatches; and pending or dead output-persistence jobs.
+Next:
+  pibo debug persistence audit --json
+  pibo debug persistence audit --session ps_... --since 2026-08-01T00:00:00Z --json
+  pibo debug persistence dead-letters
+`);
+}
+function printDebugPersistenceDeadLettersHelp() {
+    console.log(`pibo debug persistence dead-letters - read-only output dead-letter inspection
+Usage:
+  pibo debug persistence dead-letters [--session <pibo-session-id>] [--since <iso-date>] [--before <iso-date>] [--limit n] [--json]
+Reports:
+  Output-persistence dead letters, permanent collision failures, and dead letters related to persisted collision diagnostics.
+Next:
+  pibo debug persistence dead-letters --json
+  pibo debug persistence audit --json
+`);
+}
+function printDebugRepairDiscovery() {
+    console.log(`pibo debug repair - explicitly repair persisted output
+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]
+Behavior:
+  Dry-run is the default. --apply is required for every mutation.
+  Repair requires exactly one persisted message start, an inactive turn, no terminal event, and unambiguous evidence.
+  Evidence is limited to Reliability payloads, Pibo Product History, and exact adapter-history turn matches.
+  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.
+Next:
+  pibo debug repair output ps_... <event-id> --dry-run --json
+  pibo debug repair output --session ps_... --before 2026-08-31T00:00:00Z --dry-run --json
+  pibo debug repair output ps_... <event-id> --apply --json
+  pibo debug jobs dead --queue output-persistence
+`);
+}
 function printDebugResourcesDiscovery() {
     console.log(`pibo debug resources - inspect gateway resource guard state