@quantiya/codevibe-codex-plugin 2.0.6 → 2.0.8

package/node_modules/@quantiya/codevibe-core/dist/tool-activity/ledger.d.ts

@@ -0,0 +1,274 @@
+import { z } from 'zod';
+import type { Logger } from '../logger';
+import type { ToolActivityOutboxEnvelope } from './types';
+/** A persisted ledger mapping for one native invocation id. */
+export declare const LedgerEntrySchema: z.ZodObject<{
+    /** The window's idempotency key this occurrence sealed into. */
+    clientEventId: z.ZodString;
+    /**
+     * The occurrence's source transcript position (finding G) — a TIGHTER safe
+     * lower bound for a quarantine/missing-file rewind than session start. 0 when
+     * unknown (e.g. rebuilt from the outbox, which does not carry offsets) → the
+     * rewind falls back to session start, which is still SAFE.
+     */
+    byteOffset: z.ZodNumber;
+    state: z.ZodEnum<["durably-outboxed", "acked"]>;
+}, "strip", z.ZodTypeAny, {
+    state: "durably-outboxed" | "acked";
+    byteOffset: number;
+    clientEventId: string;
+}, {
+    state: "durably-outboxed" | "acked";
+    byteOffset: number;
+    clientEventId: string;
+}>;
+export type LedgerEntry = z.infer<typeof LedgerEntrySchema>;
+export declare const LedgerFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    /** keyed by native invocation id (`toolu_…` / `call_id`). */
+    entries: z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** The window's idempotency key this occurrence sealed into. */
+        clientEventId: z.ZodString;
+        /**
+         * The occurrence's source transcript position (finding G) — a TIGHTER safe
+         * lower bound for a quarantine/missing-file rewind than session start. 0 when
+         * unknown (e.g. rebuilt from the outbox, which does not carry offsets) → the
+         * rewind falls back to session start, which is still SAFE.
+         */
+        byteOffset: z.ZodNumber;
+        state: z.ZodEnum<["durably-outboxed", "acked"]>;
+    }, "strip", z.ZodTypeAny, {
+        state: "durably-outboxed" | "acked";
+        byteOffset: number;
+        clientEventId: string;
+    }, {
+        state: "durably-outboxed" | "acked";
+        byteOffset: number;
+        clientEventId: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    entries: Record<string, {
+        state: "durably-outboxed" | "acked";
+        byteOffset: number;
+        clientEventId: string;
+    }>;
+    version: 1;
+}, {
+    entries: Record<string, {
+        state: "durably-outboxed" | "acked";
+        byteOffset: number;
+        clientEventId: string;
+    }>;
+    version: 1;
+}>;
+export type LedgerFile = z.infer<typeof LedgerFileSchema>;
+/**
+ * The durable "legacy-owned" set (§4.8 startup-gap double-render fix). A native
+ * invocation id lands here when a tool was SUCCESSFULLY emitted on the LEGACY
+ * per-tool `TOOL_USE` path DURING the consolidator startup gap (a PostToolUse /
+ * JSONL invocation that arrived before the consolidator went active). Persisted
+ * SEPARATELY from `ledger.json` so the gap-time recorder (which has no live
+ * consolidator) never contends with the consolidator's own ledger writes, and so
+ * a crash between the legacy emit and the backstop replay still suppresses the
+ * re-derive. The backstop consults this set (via {@link ToolActivityLedger.isKnown})
+ * and SKIPS re-deriving any legacy-owned id into a duplicate `TOOL_ACTIVITY`
+ * manifest — the backend cannot join a `TOOL_USE` row with a `TOOL_ACTIVITY` row,
+ * and mobile's native-id FOLD only spans `TOOL_ACTIVITY` rows.
+ */
+export declare const LegacyOwnedFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    /** native invocation ids emitted on the legacy per-tool path during the startup gap. */
+    ids: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    ids: string[];
+}, {
+    version: 1;
+    ids: string[];
+}>;
+export type LegacyOwnedFile = z.infer<typeof LegacyOwnedFileSchema>;
+/** An observed occurrence's native id + its source transcript position. */
+export interface OccurrenceRef {
+    id: string;
+    byteOffset: number;
+}
+export interface ToolActivityLedgerOptions {
+    agent: string;
+    sessionId: string;
+    logger: Logger;
+    root?: string;
+}
+/**
+ * The durable invocation-id ledger for ONE session. In-memory map, persisted
+ * crash-atomically on every mutation. Correctness rests on: a `durably-outboxed`
+ * or `acked` id is a no-op re-observe; an unknown id is a fresh occurrence; and
+ * `invalidate` (crash-ordered repair) demotes a window's mappings so its
+ * occurrences are re-observed rather than suppressed.
+ */
+export declare class ToolActivityLedger {
+    private readonly agent;
+    private readonly sessionId;
+    private readonly logger;
+    private readonly rootDir;
+    private entries;
+    private loaded;
+    constructor(opts: ToolActivityLedgerOptions);
+    private filePath;
+    private legacyOwnedFilePath;
+    /**
+     * The PROCESS-SHARED legacy coordination for this (root, agent, session). Keyed
+     * by the durable file path so the gap-time recorder and the live consolidator's
+     * ledger — separate instances for the same session — share ONE `owned`/`inFlight`
+     * view (§4.8). See {@link LegacyCoordination}.
+     */
+    private get coord();
+    /**
+     * Load the persisted ledger. An absent / unreadable / invalid file yields an
+     * EMPTY ledger (the caller then rebuilds from the outbox via
+     * {@link rebuildFromOutbox}); losing it never skips an occurrence.
+     */
+    load(): Promise<void>;
+    /**
+     * Seed `durably-outboxed` mappings from the surviving outbox entries (§4.5
+     * rebuildability) — used after a ledger loss so a still-pending window is not
+     * re-observed as new. The outbox does not carry per-occurrence byteOffsets, so
+     * they default to 0 (rewind falls back to the safe session-start bound).
+     * Never DOWNGRADES an existing `acked` entry.
+     */
+    rebuildFromOutbox(outboxEntries: ToolActivityOutboxEnvelope[]): void;
+    /**
+     * True if the id is a no-op re-observe: either a sealed window's occurrence
+     * (`durably-outboxed`/`acked`), a durable `legacy-owned` id (a tool already
+     * emitted on the legacy per-tool path during the startup gap), OR an
+     * `in-flight` legacy id (a gap `TOOL_USE` mid-emit whose persistence is not yet
+     * decided). The backstop must NOT re-derive any of these into a duplicate
+     * `TOOL_ACTIVITY` (§4.8). An in-flight id is DEFERRED (not skipped): once its
+     * persistence resolves it is either promoted to durable-owned (stays suppressed)
+     * or cleared (the next backstop pass re-derives it → no skip).
+     */
+    isKnown(id: string): boolean;
+    /**
+     * §4.8 — true only for a DURABLY-resolved id: a sealed window occurrence
+     * (`durably-outboxed`/`acked`) OR a durable `legacy-owned` id. Excludes the
+     * TRANSIENT in-flight state. `observe()` uses this (NOT {@link isKnown}) to
+     * distinguish a PERMANENT dedup (a durably-resolved id → no-op, cursor advances)
+     * from a TRANSIENT one (an in-flight id → deferred, cursor HOLDS) in a SINGLE
+     * atomic evaluation, closing the check-then-observe TOCTOU (a mark landing between
+     * a separate pre-check and the observe dedup — Stage-2 Codex).
+     */
+    isKnownDurable(id: string): boolean;
+    /**
+     * §4.8 MED — true ONLY if the id is legacy IN-FLIGHT (transient, persistence not yet
+     * decided), as distinct from {@link isKnown} (which also covers the DURABLE
+     * `entries`/`owned` states). The transcript backstop uses this to tell WHY an
+     * occurrence was deferred: an in-flight deferral is TRANSIENT and reversible (a
+     * later `clear` makes the id re-derivable), so the backstop must NOT checkpoint the
+     * durable cursor PAST that occurrence's frame — a forward-only advance past it would
+     * skip it forever if it resolves NON-persisted (HIGH-1). A durably-resolved
+     * (`entries`/`owned`) deferral is permanent, so the cursor advances freely.
+     */
+    isLegacyInFlight(id: string): boolean;
+    getState(id: string): 'durably-outboxed' | 'acked' | undefined;
+    /**
+     * Unique `clientEventId`s still in the `durably-outboxed` state (sealed, not yet
+     * acked). The §4.5 N4 startup cross-check compares these against the surviving
+     * outbox files: a durably-outboxed id with NO outbox file is a LOST window that
+     * must be repaired (cursor rewind + invalidate) or it is silently skipped.
+     */
+    durablyOutboxedClientEventIds(): string[];
+    /** The native ids mapped to a window's `clientEventId`. */
+    idsFor(clientEventId: string): string[];
+    /**
+     * The tightest SAFE lower-bound byteOffset over a window's occurrences (finding
+     * G) — for the quarantine/missing-file rewind. `undefined` if the window has no
+     * mapping (caller falls back to session start).
+     */
+    safeRewindOffsetFor(clientEventId: string): number | undefined;
+    /**
+     * Record a sealed window's occurrences as `durably-outboxed` (§4.5). MUST be
+     * called AFTER the outbox entry is durably published — the durability ordering
+     * that makes the outbox, not the ledger, the source of truth. Persists atomically.
+     */
+    markDurablyOutboxed(occurrences: OccurrenceRef[], clientEventId: string): Promise<void>;
+    /** Mark every id of an acked window `acked` (retained for the pruning horizon). */
+    markAcked(clientEventId: string): Promise<void>;
+    /**
+     * Crash-ordered repair step (2) (§4.5 V3/W2): DEMOTE/remove every mapping
+     * referencing a quarantined or missing `clientEventId` so its occurrences are
+     * RE-OBSERVED (not suppressed as a `durably-outboxed` no-op) after the cursor
+     * rewind. Persists atomically.
+     */
+    invalidate(clientEventId: string): Promise<void>;
+    /**
+     * §4.8 startup-gap double-render fix — durably record native invocation ids
+     * that were SUCCESSFULLY (and PROVABLY persisted) emitted on the LEGACY per-tool
+     * `TOOL_USE` path while the consolidator was not yet active. Prefer
+     * {@link finalizeLegacyOwned} from the plugin emit site (it also clears the
+     * in-flight mark); a NON-persisted throttle-synthetic emit must NOT be recorded
+     * (else the backstop skips a tool mobile never saw = a SKIP — see the persistence
+     * gate at the plugin emit site). Writes ONLY `legacy-owned.json` (never
+     * `ledger.json`), so a dedicated gap-time recorder instance never contends with a
+     * live consolidator's ledger writes. SERIALIZED on the PROCESS-SHARED
+     * {@link LegacyCoordination.chain} + unions with the on-disk set each call, so
+     * concurrent gap records (multiple in-flight PostToolUse) never lose an id.
+     */
+    recordLegacyOwned(ids: string[]): Promise<void>;
+    /**
+     * §4.8 MED — register a native id as legacy IN-FLIGHT: a per-tool `TOOL_USE`
+     * that is about to be (or has just been) emitted on the legacy path but whose
+     * PERSISTENCE is not yet known. Synchronous + in-memory ONLY (no disk) — a
+     * transient intent, not durable state. Called BEFORE the createEvent so the
+     * consolidator's backstop (which may run concurrently on a Stop hook) sees the
+     * id as {@link isKnown} and DEFERS re-deriving it, closing the reload/record
+     * race. Resolve it with {@link finalizeLegacyOwned} (persisted) or
+     * {@link clearLegacyInFlight} (non-persisted / emit failed).
+     */
+    markLegacyInFlight(id: string): void;
+    /**
+     * §4.8 MED — clear a legacy in-flight id WITHOUT recording it durable-owned.
+     * Called when the legacy `TOOL_USE` was proven NON-persisted (a throttle
+     * synthetic) or its emit failed: the id becomes re-derivable so a later backstop
+     * pass emits it in a `TOOL_ACTIVITY` manifest (mobile still sees it → no skip).
+     */
+    clearLegacyInFlight(id: string): void;
+    /**
+     * §4.8 — promote in-flight legacy ids to DURABLE legacy-owned (proven persisted).
+     * Records to disk FIRST (via {@link recordLegacyOwned}, so `owned` gains the id),
+     * THEN drops the in-flight mark — the id is continuously {@link isKnown}
+     * (in-flight → owned) with no gap in which the backstop could re-derive it.
+     * BEST-EFFORT + ALWAYS-CLEAR: a `legacy-owned.json` write failure is swallowed (like
+     * the legacy per-tool recorder) so it never fails the caller's hook-event handling,
+     * and the in-flight mark is dropped in a `finally` so it can NEVER leak — a leaked
+     * in-flight id would pin the transcript backstop's cursor forever (§4.8 HIGH-1). If
+     * the durable record failed the id becomes re-derivable → at worst a cosmetic
+     * double-render (the tool WAS persisted, so mobile already saw the legacy row), never
+     * a skip.
+     */
+    finalizeLegacyOwned(ids: string[]): Promise<void>;
+    /**
+     * Release this session's PROCESS-SHARED legacy coordination (bound the module
+     * map on a long-lived daemon). Call on session end AFTER the recorder and any
+     * live consolidator for the session are torn down.
+     */
+    disposeLegacyCoordination(): void;
+    /**
+     * Re-read the durable legacy-owned set from disk and UNION it into memory. Run
+     * on {@link load} and at the top of every transcript-backstop pass, so a
+     * legacy-owned id recorded AFTER the ledger first loaded (a tool emitted in the
+     * narrow sub-window between init and the consolidator going active) is still
+     * seen before the backstop re-derives it (§4.8). An absent/invalid file is a
+     * no-op (nothing to suppress yet).
+     */
+    reloadLegacyOwned(): Promise<void>;
+    /** Test/diagnostic: a snapshot of the in-memory durable legacy-owned id set. */
+    legacyOwnedSnapshot(): string[];
+    /** Test/diagnostic: a snapshot of the in-memory legacy IN-FLIGHT id set. */
+    legacyInFlightSnapshot(): string[];
+    /**
+     * Bound ledger growth: drop `acked` entries whose source position is strictly
+     * BELOW a safe horizon (§4.5 — max(replay cursor, Stop turn-start)). Never
+     * prunes `durably-outboxed` (still pending an ack). Persists if anything changed.
+     */
+    prune(beforeByteOffset: number): Promise<void>;
+    private persist;
+}

package/node_modules/@quantiya/codevibe-core/dist/tool-activity/outbox.d.ts

@@ -0,0 +1,60 @@
+import type { Logger } from '../logger';
+import { ToolActivityOutboxEnvelope } from './types';
+export interface ToolActivityOutboxOptions {
+    /** Plugin agent slug — `claude` | `codex` (the on-disk namespace). */
+    agent: string;
+    logger: Logger;
+    /** Override the root for tests; defaults to `~/.codevibe/<agent>/tool-activity-outbox`. */
+    root?: string;
+}
+/** Result of a restart-time scan of one session's outbox directory. */
+export interface ListPendingResult {
+    /** Schema-valid `pending` entries recoverable for send/drain. */
+    valid: ToolActivityOutboxEnvelope[];
+    /** Filenames quarantined (unreadable/invalid/mismatched) — occurrences to re-derive from transcript. */
+    quarantined: string[];
+}
+/**
+ * The durable outbox for ONE consolidated plugin (claude / codex). A pure
+ * durability primitive: persist / list-and-validate / prune / enumerate. The
+ * send orchestration (encrypt-at-send, retry, back-pressure, ack) lives in the
+ * consolidator that owns this outbox.
+ */
+export declare class ToolActivityOutbox {
+    private readonly agent;
+    private readonly logger;
+    private readonly rootDir;
+    constructor(opts: ToolActivityOutboxOptions);
+    /** The per-session directory holding one file per sealed window. */
+    sessionDir(sessionId: string): string;
+    private entryPath;
+    /**
+     * Durably persist a sealed window `pending`, BEFORE any send (§4.5 lifecycle
+     * step 1). Schema-validates the envelope first (never persist a malformed
+     * entry) and writes via the crash-atomic temp→fsync→rename→dir-fsync sequence.
+     */
+    persist(sessionId: string, envelope: ToolActivityOutboxEnvelope): Promise<void>;
+    /**
+     * List a session's recoverable `pending` entries (§4.5 restart validation).
+     * Deletes any leftover `.tmp.` (interrupted write), schema-validates each
+     * `<id>.json`, and QUARANTINES (renames aside, logged) any file that is
+     * unreadable, schema-invalid, or whose filename does not match its own
+     * `clientEventId`. Quarantined occurrences are recovered by the caller's
+     * transcript rescan — NEVER dead-lettered.
+     */
+    listPending(sessionId: string): Promise<ListPendingResult>;
+    /** Prune a delivered entry on ack — a single idempotent `unlink` (§4.5). */
+    prune(sessionId: string, clientEventId: string): Promise<void>;
+    /**
+     * Enumerate the session ids with a durable outbox directory (§4.5 startup
+     * drain — resume EACH session's send-drain independent of which session's
+     * next hook fires).
+     */
+    enumerateSessions(): Promise<string[]>;
+    /**
+     * Rename a bad entry aside (preserved for forensics, never re-listed). Logged
+     * CRITICAL because a quarantine means the durable transcript rescan must
+     * recover those occurrences.
+     */
+    private quarantine;
+}

package/node_modules/@quantiya/codevibe-core/dist/tool-activity/replay-cursor.d.ts

@@ -0,0 +1,190 @@
+import { z } from 'zod';
+import type { Logger } from '../logger';
+/** Keep every ordinary replay read comfortably below Node/Buffer's platform limits. */
+export declare const DEFAULT_REPLAY_READ_BYTES: number;
+/**
+ * A JSONL record may be larger than the ordinary batch, so the reader extends in
+ * fixed-size chunks until it finds the terminating newline. This cap bounds the
+ * one-record memory cost without imposing any limit on the transcript FILE size.
+ */
+export declare const DEFAULT_REPLAY_MAX_FRAME_BYTES: number;
+export declare class ReplayFrameTooLargeError extends Error {
+    readonly startOffset: number;
+    readonly maxFrameBytes: number;
+    readonly code = "REPLAY_FRAME_TOO_LARGE";
+    constructor(startOffset: number, maxFrameBytes: number);
+}
+export declare const ReplayCursorStateSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    /** The transcript path this cursor tracks (a change ⇒ rescan from 0). */
+    canonicalPath: z.ZodString;
+    /** st_dev / st_ino — a change ⇒ the file rotated ⇒ rescan from 0. */
+    fileIdentity: z.ZodObject<{
+        dev: z.ZodNumber;
+        ino: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        dev: number;
+        ino: number;
+    }, {
+        dev: number;
+        ino: number;
+    }>;
+    /** DURABLE complete-line boundary — the only correctness authority. */
+    byteOffset: z.ZodNumber;
+    /** Last-observed file size — a smaller current size ⇒ truncation ⇒ rescan from 0. */
+    lastKnownSize: z.ZodNumber;
+    /** Partial trailing line as of the last checkpoint (diagnostic; re-derived on read). */
+    carryover: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    canonicalPath: string;
+    byteOffset: number;
+    fileIdentity: {
+        dev: number;
+        ino: number;
+    };
+    lastKnownSize: number;
+    carryover: string;
+}, {
+    version: 1;
+    canonicalPath: string;
+    byteOffset: number;
+    fileIdentity: {
+        dev: number;
+        ino: number;
+    };
+    lastKnownSize: number;
+    carryover: string;
+}>;
+export type ReplayCursorState = z.infer<typeof ReplayCursorStateSchema>;
+/** One framed transcript line with its byte span. */
+export interface ReplayFrame {
+    line: string;
+    /**
+     * Byte offset of the line's FIRST byte (§4.5 finding G). This is the SAFE rewind
+     * lower bound for an occurrence on this line — rewinding here RE-READS the line;
+     * rewinding to `endOffset` would land on the NEXT line and skip this occurrence.
+     */
+    startOffset: number;
+    /** Byte offset just past the line's trailing `\n` (the checkpoint-advance candidate). */
+    endOffset: number;
+}
+/** A pure read snapshot — no persisted state is mutated by {@link ToolReplayCursor.readFrames}. */
+export interface ReadFramesResult {
+    /** Complete lines in this bounded batch from the checkpoint (or 0 after a rotation). */
+    frames: ReplayFrame[];
+    /** True when the file rotated/truncated and was rescanned from 0. */
+    rotated: boolean;
+    /** True when the transcript file is ABSENT (N4 missing-file — caller repairs). */
+    missing: boolean;
+    /** Partial trailing bytes with no terminating newline yet (may be ''). */
+    carryover: string;
+    /** Byte offset just past the last COMPLETE line — the max checkpoint candidate. */
+    endOfComplete: number;
+    /**
+     * True when this stat snapshot contains bytes beyond the bounded read. The
+     * caller may immediately run another batch after checkpointing this one.
+     * False at the snapshot EOF, including when EOF is an incomplete trailing line.
+     */
+    hasMore: boolean;
+    /** Bytes actually read from disk for this batch (diagnostics/tests). */
+    bytesRead: number;
+    /** The identity + size captured AT read time — pass to {@link ToolReplayCursor.checkpoint} for a consistent snapshot. */
+    fileIdentity: {
+        dev: number;
+        ino: number;
+    };
+    size: number;
+}
+export interface ToolReplayCursorOptions {
+    agent: string;
+    sessionId: string;
+    /** Absolute path of the transcript this cursor rescans. */
+    canonicalPath: string;
+    logger: Logger;
+    root?: string;
+    /** Ordinary bounded batch size. Defaults to 4 MiB. */
+    readBytes?: number;
+    /** Maximum bytes allowed in one unterminated JSONL record. Defaults to 64 MiB. */
+    maxFrameBytes?: number;
+}
+/**
+ * The durable tool-replay cursor for ONE session's transcript. Split into a PURE
+ * read ({@link readFrames}) and an explicit durable advance ({@link checkpoint}):
+ * the consolidator frames + observes, durably outboxes the contiguous prefix,
+ * then checkpoints — so the persisted `byteOffset` never runs ahead of durability.
+ */
+export declare class ToolReplayCursor {
+    private readonly agent;
+    private readonly sessionId;
+    private readonly canonicalPath;
+    private readonly logger;
+    private readonly rootDir;
+    private readonly readBytes;
+    private readonly maxFrameBytes;
+    private state;
+    constructor(opts: ToolReplayCursorOptions);
+    private filePath;
+    /**
+     * Load the persisted cursor. An absent / unreadable / invalid file yields a
+     * FRESH cursor (rescan from 0) — losing it never skips an occurrence.
+     */
+    load(): Promise<void>;
+    /** The current durable checkpoint (0 when fresh). */
+    byteOffset(): number;
+    /**
+     * Read + byte-frame ONE BOUNDED transcript batch from the durable checkpoint
+     * (or 0 after a rotation). PURE — persists nothing. File positions are ordinary
+     * safe JS integers, so offsets above Node's signed 32-bit Buffer length remain
+     * valid; no allocation is based on `(fileSize - checkpoint)`.
+     *
+     * Frames on `\n` (0x0A), an ASCII byte that never appears mid-UTF-8-char, so
+     * every complete-line boundary is a safe UTF-8 (and byte-offset) boundary. If
+     * the ordinary batch contains no newline, fixed-size reads extend only until
+     * the first record terminator or `maxFrameBytes`. Thus transcript FILE size is
+     * unbounded while one malformed/huge JSONL RECORD has a controlled bound.
+     * The trailing partial is returned as `carryover` and re-read next cycle.
+     */
+    readFrames(): Promise<ReadFramesResult>;
+    /**
+     * Advance the durable checkpoint over a contiguous durably-outboxed prefix
+     * (§4.5) and persist atomically. FORWARD-ONLY **within the same file**: a
+     * `newByteOffset` at or below the current checkpoint is ignored (a stale/duplicate
+     * advance never regresses the cursor — use {@link rewindTo} for the deliberate
+     * repair rewind). The snapshot (`fileIdentity`, `size`, `carryover`) MUST come from
+     * the {@link readFrames} result that produced this offset, so identity + offset stay
+     * consistent.
+     *
+     * ROTATION/TRUNCATION EXCEPTION: when the snapshot's canonical PATH differs from the
+     * stored one (rebound to a new transcript), OR its file identity differs (inode/dev
+     * change), OR the file shrank below the current offset (truncation), the old offset
+     * addresses a file that no longer exists — the forward-only guard would reject EVERY
+     * checkpoint on the (smaller) replacement, so `readFrames` would re-detect rotation and
+     * re-read the whole replacement forever (unbounded re-read). In that case the checkpoint
+     * RESETS the baseline to track the replacement. The predicate MIRRORS `readFrames`' own
+     * `rotated` detection EXACTLY (path + identity + shrink) so the two never disagree — a
+     * rename to a new canonical path that keeps the same inode + size would otherwise be
+     * rotation to `readFrames` but not to `checkpoint`, wedging the cursor (Stage-2 Codex).
+     */
+    checkpoint(newByteOffset: number, snapshot: {
+        fileIdentity: {
+            dev: number;
+            ino: number;
+        };
+        size: number;
+        carryover: string;
+    }): Promise<void>;
+    /**
+     * Crash-ordered repair step (1) (§4.5 V3/N4): REWIND the checkpoint to a safe
+     * lower bound so a quarantined/missing window's occurrences are re-observed.
+     * MUST run BEFORE the ledger `invalidate` (step 2) and the re-observe (step 3).
+     * BACKWARD-ONLY: clamped to `min(current, requested)` and ≥ 0, so it can never
+     * ADVANCE the cursor past unread bytes (a repair target below the current cursor
+     * moves back to re-read; a target at/above it is a no-op — the frames are already
+     * unread). carryover is cleared (re-derived on the next read).
+     */
+    rewindTo(byteOffset: number): Promise<void>;
+    /** Clear the cursor to a full rescan-from-0 (e.g. a hard reset). Persists. */
+    reset(): Promise<void>;
+    private persist;
+}

package/node_modules/@quantiya/codevibe-core/dist/tool-activity/session-map.d.ts

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+import type { Logger } from '../logger';
+/** An acquired exclusive ownership of a rollout `R`, held until {@link release}. */
+export interface RolloutOwnership {
+    readonly rollout: string;
+    release(): Promise<void>;
+}
+/**
+ * A cross-process single-writer lock over a rollout id (§4.5 X3). The production
+ * backend acquires a REAL OS advisory lock (auto-released on process death) on a
+ * stable per-`R` lockfile; {@link InProcessRolloutLock} is the intra-process
+ * backend for claude's degenerate 1:1 + tests. The backend owns mutual exclusion
+ * + stale-owner breaking; the session-map owns the durable record.
+ */
+export interface RolloutLock {
+    /** Blocks until this process holds `rollout` exclusively; released via the handle. */
+    acquireOwnership(rollout: string): Promise<RolloutOwnership>;
+}
+/**
+ * In-process rollout lock: a per-key async mutex. Correct for claude (each
+ * `claude-<UUID>` is process-unique, so there is no cross-PROCESS contention to
+ * serialize) and for unit tests. NOT sufficient for codex's cross-process resume
+ * (that needs the injected OS-advisory backend).
+ */
+export declare class InProcessRolloutLock implements RolloutLock {
+    private tails;
+    acquireOwnership(rollout: string): Promise<RolloutOwnership>;
+}
+export declare const SessionMapRecordSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    /** The native rollout id `R` (codex `call_id` rollout) / `claude-<UUID>`. */
+    rollout: z.ZodString;
+    /** Pid of the current owner — informational + usable by a lockfile backend for stale detection. */
+    ownerPid: z.ZodNumber;
+    /** The owner's backend session id — every binding attributes to THIS (S2 single-owner). */
+    ownerBackendSessionId: z.ZodString;
+    /** `call_id → backendSessionId` (always the owner's — S2). */
+    bindings: z.ZodRecord<z.ZodString, z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    rollout: string;
+    ownerPid: number;
+    ownerBackendSessionId: string;
+    bindings: Record<string, string>;
+}, {
+    version: 1;
+    rollout: string;
+    ownerPid: number;
+    ownerBackendSessionId: string;
+    bindings: Record<string, string>;
+}>;
+export type SessionMapRecord = z.infer<typeof SessionMapRecordSchema>;
+export interface ToolActivitySessionMapOptions {
+    agent: string;
+    logger: Logger;
+    lock: RolloutLock;
+    root?: string;
+    /** Overridable for tests. */
+    pid?: number;
+}
+/**
+ * The durable session-map for ONE consolidated agent. Every mutation is
+ * crash-atomic (temp→fsync→rename→dir-fsync via {@link atomicWriteJson}); the
+ * per-call binding write IS the §4.5 per-call durable-binding barrier every
+ * observer awaits BEFORE it observes/seals/outboxes a call.
+ */
+export declare class ToolActivitySessionMap {
+    private readonly agent;
+    private readonly logger;
+    private readonly lock;
+    private readonly rootDir;
+    private readonly pid;
+    /** Per-rollout in-process mutation chain — serializes every record read-modify-write. */
+    private readonly recordChains;
+    constructor(opts: ToolActivitySessionMapOptions);
+    /**
+     * Serialize a record read-modify-write against all other mutations of the SAME
+     * rollout IN THIS PROCESS. The cross-process rollout lock (X3) makes ONE process
+     * the single writer of `R`; this chain closes the remaining IN-PROCESS hazard —
+     * concurrent {@link claimOwnership}/{@link bindCall} calls interleaving their
+     * read→write and last-writer-wins silently dropping a binding (Stage-2 iter-3 MED).
+     * The chain waits for the prior mutation regardless of its outcome (a failed write
+     * must not wedge `R`), and self-prunes when it becomes the idle tail.
+     */
+    private mutateRecord;
+    /**
+     * S1 — a GLOBALLY-UNIQUE codex backend session id `codex-<hostRandom>-<pid>-<launchNonce>`
+     * that NEVER recurs (a resume mints a NEW one), so `R → backendId` divergence is
+     * always detectable and a resumed conversation is a distinct backend session.
+     */
+    static mintCodexBackendSessionId(pid?: number): string;
+    /** The stable per-`R` lockfile path a production backend locks (created once, never renamed). */
+    lockPath(rollout: string): string;
+    private recordPath;
+    /** Filesystem-safe encoding of a rollout id (native ids can contain path-hostile chars). */
+    private encode;
+    private decode;
+    /**
+     * Acquire single-writer ownership of `R` and record this process's backend
+     * session as its owner (KEEPING any prior bindings — a reclaim never drops the
+     * `call_id` history). Holding the lock IS ownership; the backend already broke
+     * any stale prior holder. Returns the held ownership handle (release on session
+     * end / process exit).
+     */
+    claimOwnership(rollout: string, backendSessionId: string): Promise<RolloutOwnership>;
+    /**
+     * The §4.5 PER-CALL durable-binding barrier: durably bind `call_id` to the
+     * owner's backend session and fsync BEFORE the caller observes/seals/outboxes
+     * the call. Requires the held ownership handle (proves single-writer). All of
+     * `R`'s calls attribute to the ONE owner (S2).
+     */
+    bindCall(ownership: RolloutOwnership, callId: string): Promise<void>;
+    /**
+     * Route a transcript occurrence: the backend session bound to `(R, call_id)`,
+     * or `null` if unbound (the caller applies the X2b {@link ownerBackendSessionId}
+     * fallback ONLY when it holds `R`'s ownership).
+     */
+    resolveCall(rollout: string, callId: string): Promise<string | null>;
+    /**
+     * X2b fallback source — the CURRENT owner's backend session for `R`. A caller
+     * uses this to attribute a map-lost re-observed occurrence ONLY for a rollout it
+     * ACTUALLY OWNS (holds `R`'s lock); never to cross-attribute a foreign rollout.
+     */
+    ownerBackendSessionId(rollout: string): Promise<string | null>;
+    /**
+     * Startup enumeration (§4.5): the rollout ids with a durable session-map record,
+     * so a transcript recovered by the transcript-root pass routes even if its
+     * outbox subdir was lost.
+     */
+    enumerateRollouts(): Promise<string[]>;
+    private readRecord;
+    private writeRecord;
+}