@quantiya/codevibe-codex-plugin 2.0.6 → 2.0.8

package/node_modules/@quantiya/codevibe-core/dist/substrate-launch/reviewer-credential-preflight.d.ts

@@ -0,0 +1,50 @@
+import type { VendorProvider } from "../credential-broker";
+/**
+ * Typed marker for the missing-credential failure so the loop can surface the
+ * remediation on the user-facing NOTIFICATION channel (Stage-2 r2 Codex MED-1)
+ * without string-matching. Identified by `name` (survives bundling) — callers
+ * check `err.name === REVIEWER_CREDENTIAL_MISSING` rather than instanceof.
+ */
+export declare const REVIEWER_CREDENTIAL_MISSING = "ReviewerCredentialMissingError";
+export declare class ReviewerCredentialMissingError extends Error {
+    name: string;
+}
+/**
+ * The minimal store surface the preflight needs (structurally satisfied by
+ * `KeychainVendorKeyStore`); narrow so tests can stub it without keychain IO.
+ */
+export interface ReviewerCredentialStore {
+    getVendorKey(provider: VendorProvider): Promise<string | null>;
+    getVendorOAuthBundle(provider: VendorProvider): Promise<unknown | null>;
+}
+/**
+ * Map a reviewer agent kind (lowercase, as the loop's engager input carries it)
+ * to its broker vendor provider. Non-Trusted agents (gemini/antigravity) have
+ * no broker provider — they never sandbox, so the preflight is a no-op for
+ * them (the loop pre-routes them to legacy+badge before engaging anyway).
+ */
+export declare function reviewerProviderFor(agent: string): VendorProvider | null;
+/**
+ * Throw (fail-closed) when a Trusted reviewer is about to substrate-engage but
+ * no vendor credential exists for its provider. The message is the user-facing
+ * remediation — it propagates verbatim through the loop's engage-failure
+ * ESCALATE (`spawnOneSeat`) and the Wave-B fall-through WARN.
+ */
+export declare function assertReviewerVendorCredential(agent: string, store: ReviewerCredentialStore): Promise<void>;
+/**
+ * Wrap a reviewer substrate engager with the credential preflight, ordered
+ * AFTER tier selection (Stage-2 r2 Codex MED-2): the underlying engage runs
+ * first, and the credential check applies ONLY when the ladder actually chose
+ * the `substrate` (broker) mode — a `reduced_trust` selection never consults
+ * credentials, preserving the pre-flip legacy-plus-badge fallback on hosts
+ * with no establishable sandbox tier. On substrate + missing credential the
+ * engaged substrate is torn down and the actionable
+ * `ReviewerCredentialMissingError` propagates (fail-closed, no ambient
+ * fallback).
+ */
+export declare function withReviewerCredentialPreflight<I extends {
+    agent: string;
+}, R extends {
+    mode: string;
+    teardown: () => Promise<void>;
+}>(engage: (input: I) => Promise<R>, store: ReviewerCredentialStore): (input: I) => Promise<R>;

package/node_modules/@quantiya/codevibe-core/dist/substrate-launch/sanitized-env.d.ts

@@ -29,12 +29,12 @@ export interface SanitizedEnvInput {
      */
     sandboxHome: string;
     /**
-     * The IN-SANDBOX path of the apiKeyHelper bootstrap dir (PART D). The agent
+     * The IN-SANDBOX path of the mutable agent config dir (PART D). The agent
      * config (`settings.json` for Claude / `config.toml` for Codex) lives HERE,
-     * and that config is what points the CLI at the broker apiKeyHelper / `[auth]
-     * command`. We MUST point the agent at this dir via the CLI's native config-
-     * discovery env, or the agent never reads the helper and the "creditless"
-     * loop is fake (Stage-2 M-1):
+     * while the broker-token helper it references lives in the separate read-only
+     * bootstrap dir. We MUST point the agent at this dir via the CLI's native
+     * config-discovery env, or the agent never reads the helper and the
+     * "creditless" loop is fake (Stage-2 M-1):
      *   - Claude → `CLAUDE_CONFIG_DIR` (SPIKE-FINDINGS §1 method: isolated
      *     `HOME` + `CLAUDE_CONFIG_DIR` is the discovery path the spike used).
      *   - Codex  → `CODEX_HOME` (SPIKE-FINDINGS §2 empirical: clean `HOME` +

package/node_modules/@quantiya/codevibe-core/dist/test-publication-authority-setup.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@quantiya/codevibe-core/dist/tool-activity/__tests__/consolidator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@quantiya/codevibe-core/dist/tool-activity/__tests__/digest.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@quantiya/codevibe-core/dist/tool-activity/__tests__/flock-rollout-lock.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

package/node_modules/@quantiya/codevibe-core/dist/tool-activity/__tests__/socket-rollout-lock.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,27 @@
+import type { z } from 'zod';
+/** Marker infix used by every temp file so restart sweeps can find them. */
+export declare const TEMP_INFIX = ".tmp.";
+/**
+ * fsync a directory so a preceding `rename` into it is durable across a crash.
+ * Best-effort (skipped on Windows / filesystems that reject a dir fsync).
+ */
+export declare function fsyncDir(dir: string): Promise<void>;
+/**
+ * Crash-atomic write of one file: temp(`O_EXCL`) → write → fsync → chmod 0600 →
+ * atomic `rename` → dir-fsync (§4.5 — Stage-2 Codex H2). `rename` provides
+ * atomicity; it needs no no-replace semantics (a verbatim re-write of the same
+ * content is a harmless self-replace). The temp lives in the SAME directory so
+ * the rename is intra-filesystem, and carries the `.tmp.` infix + pid + random
+ * suffix so a restart sweep recognizes an interrupted write.
+ */
+export declare function atomicWriteFileSync(finalPath: string, bytes: string): Promise<void>;
+/** Crash-atomic write of a JSON value (schema-validated before writing). */
+export declare function atomicWriteJson<T>(finalPath: string, schema: z.ZodType<T>, value: T): Promise<void>;
+/**
+ * Read + schema-validate a crash-atomic JSON state file. Returns `null` when the
+ * file is ABSENT, unreadable, non-JSON, or fails the schema — the caller then
+ * reconstructs from the transcript (the file is a rebuildable cache, never a
+ * uniqueness authority; §4.5). `onInvalid` fires (for a CRITICAL log) only when a
+ * PRESENT file failed to parse/validate, distinguishing corruption from absence.
+ */
+export declare function readValidatedJson<T>(filePath: string, schema: z.ZodType<T>, onInvalid?: (reason: string) => void): Promise<T | null>;

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

@@ -0,0 +1,253 @@
+import type { Logger } from '../logger';
+import type { ToolActivityOutbox } from './outbox';
+import type { ToolActivityLedger } from './ledger';
+import type { ToolActivityOutboxEnvelope } from './types';
+/** An observed tool occurrence handed to {@link ToolActivityConsolidator.observe}. */
+/**
+ * The ATOMIC (under-lock) outcome of {@link ToolActivityConsolidator.observe}, so the
+ * transcript backstop's cursor-hold decision uses the SAME dedup evaluation that
+ * decided the no-op (closing the check-then-observe TOCTOU, Stage-2 Codex):
+ *   - `observed`           — appended to the open window (fresh occurrence).
+ *   - `known-durable`      — a sealed/acked/legacy-owned id (permanent no-op → advance).
+ *   - `deferred-in-flight` — a TRANSIENT legacy in-flight id (no-op → the cursor HOLDS).
+ *   - `live-open-dup`      — already in the current open window (no-op → advance).
+ *   - `sealed-terminal`    — a post-shutdown late occurrence DURABLY captured to the outbox
+ *                            by {@link ToolActivityConsolidator.captureTerminal} (no-op for
+ *                            the cursor → advance; the caller SUPPRESSES the legacy row).
+ *   - `closed`             — the consolidator has shut down AND terminal capture was not
+ *                            done / failed (no-op; the caller may best-effort legacy-emit).
+ * Only `deferred-in-flight` holds the cursor; everything else advances.
+ */
+export type ObserveDisposition = 'observed' | 'known-durable' | 'deferred-in-flight' | 'live-open-dup' | 'sealed-terminal' | 'closed';
+export interface ObservedOccurrence {
+    /** Native reproducible id (claude `toolu_…`, codex `call_id`) — the dedup key. */
+    id: string;
+    tool: string;
+    /** Optional grouping key within the window (e.g. a normalized file path). */
+    normalizedTarget?: string;
+    /** Best-available occurrence time (display fidelity; ISO-8601). */
+    ts: string;
+    /** Source transcript position (finding G) — stored in the ledger for a rewind. */
+    byteOffset: number;
+    /** `digestOf(toolInput)` (§0) — becomes the group's `detail[].digest`. Omit if no input. */
+    digest?: string;
+}
+/** Encrypt-at-send transport — throws on a retryable failure; returns on ack. */
+export interface ToolActivityTransport {
+    send(sessionId: string, envelope: ToolActivityOutboxEnvelope): Promise<void>;
+}
+/**
+ * True when a failed TOOL_ACTIVITY `createEvent` is the backend's TYPED
+ * `SessionKeyStale` rejection (§4.5 step 4 — the session's `sessionKeyGen`
+ * ConditionCheck failed because the session was RECREATED under a new generation,
+ * so the manifest was encrypted + stamped with a now-stale key/generation).
+ * Surfaces as `AppSyncGraphQLError.errorType === 'SessionKeyStale'`; the message
+ * fallback (`SESSION_KEY_STALE`) covers any transport that drops `errorType`. The
+ * plugin transport catches this to REFRESH the session key + generation,
+ * RE-ENCRYPT under the fresh key, and retry — instead of re-sending the same
+ * undecryptable generation forever (a liveness/G2 failure on key rotation).
+ */
+export declare function isSessionKeyStaleError(err: unknown): boolean;
+export interface ToolActivityConsolidatorOptions {
+    agent: string;
+    /** The backend session id bound into each window's envelope (X2a routing). */
+    sessionId: string;
+    logger: Logger;
+    outbox: ToolActivityOutbox;
+    ledger: ToolActivityLedger;
+    transport: ToolActivityTransport;
+    /** Seal the open window after this much wall-clock (default 3000ms). */
+    windowMs?: number;
+    /** Seal (with `continues`) once the open window reaches this many occurrences (default 50). */
+    maxOccurrences?: number;
+    /** Max windows in flight to the transport at once — back-pressure (default 4). */
+    maxInFlight?: number;
+    /** Retry backoff ceiling for a failed send (default 30000ms). */
+    maxBackoffMs?: number;
+    /** Injectable clock (default Date.now). */
+    now?: () => number;
+    /** Injectable timer (default setTimeout) — tests pass a controllable fake. */
+    scheduleTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (t: ReturnType<typeof setTimeout>) => void;
+    /** Injectable window-id minter (default ulid) — the clientEventId. */
+    mintClientEventId?: () => string;
+}
+/**
+ * Clamp a DISPLAY-only string to a UTF-8 byte budget, appending an ellipsis marker when it
+ * had to be cut. Binary-searches the longest char prefix that fits `maxBytes` (accounting for
+ * the marker) so the result is always ≤ `maxBytes` and never splits a multi-byte codepoint at
+ * the budget boundary in a way that inflates the byte count. Display-only: truncating here
+ * never drops a tool invocation (the occurrence id/ts/count are separate + preserved).
+ */
+export declare function clampDisplayBytes(s: string, maxBytes: number): string;
+export declare class ToolActivityConsolidator {
+    private readonly agent;
+    private readonly sessionId;
+    private readonly logger;
+    private readonly outbox;
+    private readonly ledger;
+    private readonly transport;
+    private readonly windowMs;
+    private readonly maxOccurrences;
+    private readonly maxInFlight;
+    private readonly maxBackoffMs;
+    private readonly now;
+    private readonly scheduleTimer;
+    private readonly clearTimer;
+    private readonly mintClientEventId;
+    private open;
+    private sealTimer;
+    /** FIFO of windows awaiting delivery, keyed by clientEventId for dedup. */
+    private readonly queue;
+    private readonly queued;
+    private inFlight;
+    /** Windows currently in backoff-limbo (neither queued nor in flight). */
+    private retrying;
+    private closed;
+    /**
+     * §4.5(b)/#232 — waiters woken by {@link deliver}'s finally so a bounded drain
+     * ({@link drainSends} at session end, {@link captureTerminal} for a post-shutdown late
+     * tool) resolves once the queue empties. A SET (not a single slot) so concurrent late-tool
+     * terminal captures each get their own wake-up instead of clobbering one another.
+     */
+    private readonly drainWaiters;
+    /**
+     * Single-flight lock serializing every OPEN-WINDOW mutation — observe, the seal
+     * timer, boundary/backstop flush, and shutdown. Without it, an observe() appending
+     * to the window while a seal() awaits `outbox.persist` would be marked
+     * durably-outboxed in the ledger yet be ABSENT from the persisted manifest → a
+     * permanent skip (Stage-2 H2). All mutators route through {@link runExclusive}, so a
+     * window is snapshot + sealed atomically w.r.t. any concurrent append.
+     */
+    private mutationChain;
+    constructor(opts: ToolActivityConsolidatorOptions);
+    /**
+     * Load the ledger, rebuild its durably-outboxed mappings from the surviving
+     * outbox (a lost ledger never skips), and re-enqueue every still-`pending`
+     * outbox entry for delivery. Quarantined entries are left for the caller's
+     * transcript rescan to re-observe.
+     */
+    init(): Promise<void>;
+    /**
+     * §4.5 N4 startup cross-check + crash-ordered repair (V3/W2). A window the ledger
+     * records as `durably-outboxed` but whose outbox file did NOT survive (lost or
+     * quarantined) is a SKIP hazard: it will never be re-sent (no pending file) and
+     * never be re-observed (the ledger suppresses its native ids as durably-outboxed
+     * no-ops). Detect every such lost window by cross-checking the ledger's
+     * durably-outboxed clientEventIds against the surviving valid outbox files, then
+     * repair in the load-bearing order:
+     *   (1) rewind the replay cursor to the safe lower bound over the lost windows —
+     *       BEFORE invalidation, so the transcript rescan re-reads their frames;
+     *   (2) invalidate the lost windows' ledger mappings, so the re-read occurrences
+     *       are RE-OBSERVED (not suppressed) and re-sealed into fresh windows.
+     * A crash between (1) and (2) rescans-but-suppresses (harmless, repaired next
+     * start); the reverse order would strand the window past the advanced cursor.
+     *
+     * The replay cursor is OWNED by the plugin integration (the core stays transcript-
+     * agnostic), so it is injected here and this runs once the cursor is loaded — in
+     * the integration's start()/transcript-bind, AFTER {@link init}. gemini + agy are
+     * EXEMPT (no cursor, no ledger) and never call this.
+     */
+    repairLostWindows(cursor: {
+        rewindTo(byteOffset: number): Promise<void>;
+    }): Promise<void>;
+    /**
+     * Observe one tool occurrence. Deduped against the OPEN window (live-open) and
+     * the ledger (durably-outboxed / acked / legacy-owned / in-flight) by native id —
+     * a re-observe of an already-seen occurrence is a no-op (the mobile still
+     * render-dedups as the ultimate authority). A fresh occurrence joins the open
+     * window and (re)arms the seal timer / triggers an overflow seal.
+     *
+     * RETURNS a {@link ObserveDisposition} decided ATOMICALLY (under the lock) with the
+     * dedup — the transcript backstop uses it to decide the cursor HOLD: a
+     * `deferred-in-flight` occurrence must NOT be checkpointed past (its persistence is
+     * undecided; if it clears it must be re-derivable), whereas `known-durable` /
+     * `observed` / `live-open-dup` advance freely. Returning the disposition (instead of
+     * the backstop doing its OWN pre-check) closes the check-then-observe TOCTOU: a mark
+     * landing between a separate pre-check and this dedup would otherwise leave the
+     * occurrence neither held nor sealed → a skip (Stage-2 Codex).
+     *
+     * `opts.includeInFlight` (the session-end FINAL sweep) treats an in-flight id as
+     * OBSERVABLE (seals it) so a late mark can't defer a tool that has no later pass to
+     * re-read it — trading a possible cosmetic double-render for a skip (§4.8).
+     */
+    observe(occ: ObservedOccurrence, opts?: {
+        includeInFlight?: boolean;
+    }): Promise<ObserveDisposition>;
+    /** Seal the open window immediately (session end / turn boundary / explicit flush). */
+    flush(): Promise<void>;
+    /** Flush + stop timers (session end). Does NOT drain in-flight sends synchronously. */
+    shutdown(): Promise<void>;
+    /**
+     * §4.5(b)/#232 — BOUNDED session-end send drain. Seal the open window, then deliver
+     * every pending window (with retries armed — MUST be called BEFORE {@link shutdown}
+     * sets `closed`) until the queue empties OR `timeoutMs` elapses. A force-sealed
+     * session-end window (§4.8) is otherwise only delivered on the NEXT daemon start's
+     * re-drain — fine for claude (same backend id on resume) but NOT for codex (fresh id
+     * per start → its outbox is never re-scanned), so it would strand. Draining here
+     * delivers it while the session key is still live. Bounded so a persistently-failing
+     * network can't hang shutdown; a window that misses the deadline stays DURABLE in the
+     * outbox (recovered on resume for claude; the codex cross-restart strand is the
+     * documented #232 residual — never a data loss, only a delayed/absent manifest).
+     */
+    drainSends(timeoutMs: number): Promise<void>;
+    /**
+     * Await the send queue emptying OR `timeoutMs` elapsing — whichever first (BOUNDED, never
+     * hangs). Each caller registers its own waiter in {@link drainWaiters} (woken by
+     * {@link deliver}'s finally) and its own timer, and settles exactly once. A window that
+     * misses the deadline stays DURABLE in the outbox (recovered on the next start), never lost.
+     */
+    private awaitDrain;
+    /**
+     * §4.8 shutdown-boundary TERMINAL capture + DELIVER. A tool occurrence observed AFTER
+     * {@link shutdown} (a hook/JSONL line landing in the window between shutdown() completing
+     * and the plugin nulling the integration) makes {@link observe} return `'closed'` and be
+     * DROPPED — and routing it to the plugin's fire-and-forget legacy `createEvent` is unsafe:
+     * a per-session/account throttle SYNTHETIC (non-persisted) or a network throw loses it
+     * with NO later backstop pass, a permanent G2 skip (Stage-2 Codex). Instead: durably SEAL
+     * a ONE-occurrence manifest to the outbox, then ENQUEUE + PUMP + await a BOUNDED
+     * {@link awaitDrain} so it is actually DELIVERED THIS process while the session key is still
+     * live. Persist-only would strand it — a closed send loop never runs, codex mints a fresh
+     * id per start so its outbox is never re-scanned, and claude only re-drains on resume — so
+     * on a HEALTHY network the tool would reach mobile only on a later resume that may never
+     * happen (Stage-2 Codex HIGH). A single send attempt: on success the window is acked +
+     * pruned; on a transient failure a closed consolidator does NOT re-arm retries, so the
+     * window stays DURABLE in the outbox for the next start's re-drain (claude same-id; the
+     * codex fresh-id strand is the documented #232 residual) — never a silent hard loss. The
+     * persist + enqueue run under the mutation lock; the drain awaits outside it. Idempotent: a
+     * `known-durable` id enqueues nothing new (claude's two sources / codex hook+JSONL both
+     * landing post-close capture it ONCE). Returns true when durably captured (caller SUPPRESSES
+     * the legacy row), false when the outbox write itself failed (caller may best-effort
+     * legacy-emit as a last resort).
+     */
+    captureTerminal(occ: ObservedOccurrence, drainTimeoutMs: number): Promise<boolean>;
+    /**
+     * Serialize a window mutation behind every prior one (success OR failure), and
+     * return this op's own result. The chain is the single writer of `this.open`.
+     */
+    private runExclusive;
+    private armSealTimer;
+    /**
+     * Turn the open window into a durable outbox entry, in the load-bearing order:
+     * build manifest → outbox.persist (DURABLE) → ledger.markDurablyOutboxed (AFTER
+     * the outbox) → enqueue for send. MUST be called ONLY under {@link runExclusive}
+     * (name suffix `Locked`): it DETACHES `this.open` and snapshots every field BEFORE
+     * the first `await`, so no concurrent observe can append to the window being sealed
+     * (a late append would be ledger-mapped durably-outboxed yet absent from the
+     * persisted manifest = a skip, Stage-2 H2). A post-seal observe opens a FRESH window.
+     */
+    private sealLocked;
+    /**
+     * Group occurrences by `(tool, target)`, preserving first-seen order (§4.1).
+     * `occurrences[]` stays the minimal `{ts,id}` dedup shape; a per-occurrence
+     * `digestOf(toolInput)` (when the observer supplied one) becomes an entry in the
+     * group's `detail[]`, indexed by position into that group's `occurrences[]`.
+     */
+    private buildGroups;
+    private enqueue;
+    /** Start as many sends as back-pressure allows. */
+    private pump;
+    private deliver;
+    /** Test/diagnostic: windows still awaiting delivery (queued + in flight + backoff-limbo). */
+    pendingCount(): number;
+}

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

@@ -0,0 +1,4 @@
+/** Stable stringify — sort object keys at every depth (arrays keep order). */
+export declare function stableStringify(value: unknown): string;
+/** `sha256:` + hex(sha256(stableStringify(toolInput))) — matches hook-bridge.ts (§0). */
+export declare function digestOf(toolInput: unknown): string;

package/node_modules/@quantiya/codevibe-core/dist/tool-activity/flock-rollout-lock.d.ts

@@ -0,0 +1,68 @@
+import type { Logger } from '../logger';
+import type { RolloutLock, RolloutOwnership } from './session-map';
+/** `flock(2)` flags as accepted by `fs-ext.flockSync`. */
+export type FlockFlag = 'ex' | 'exnb' | 'sh' | 'shnb' | 'un';
+/** The one `fs-ext` primitive this backend needs: a synchronous `flock(fd, flag)`. */
+export type FlockSyncFn = (fd: number, flag: FlockFlag) => void;
+export interface FlockRolloutLockOptions {
+    agent: string;
+    logger: Logger;
+    /** Injected synchronous `flock` (production: `fs-ext`; tests: a controllable fake). */
+    flockSync: FlockSyncFn;
+    /** Session-map root; the lockfile is `<root>/<encode(R)>.lock` (matches session-map.lockPath). */
+    root?: string;
+    /** Base retry backoff while a LIVE owner holds `R` (default 25ms, capped 1s). */
+    backoffMs?: number;
+    /** Max total wait before {@link acquireOwnership} throws (default 60000ms) — a RETRYABLE re-observe, never a skip. */
+    maxWaitMs?: number;
+    /** Injectable clock (default Date.now). */
+    now?: () => number;
+    /** Injectable delay (default setTimeout). */
+    delay?: (ms: number) => Promise<void>;
+}
+export declare class FlockRolloutLock implements RolloutLock {
+    private readonly agent;
+    private readonly logger;
+    private readonly flockSync;
+    private readonly rootDir;
+    private readonly backoffMs;
+    private readonly maxWaitMs;
+    private readonly now;
+    private readonly delayFn;
+    constructor(opts: FlockRolloutLockOptions);
+    /** The stable, never-unlinked lockfile for `R` — identical to session-map.lockPath. */
+    lockPath(rollout: string): string;
+    /**
+     * Block (bounded) until this process holds an exclusive `flock` on `R`'s stable
+     * lockfile, then return an ownership handle whose {@link RolloutOwnership.release}
+     * drops the `flock` and closes the fd. Throws after maxWaitMs if a LIVE owner keeps
+     * `R` — the caller's per-call barrier then throws, a RETRYABLE re-observe (§4.5 ①).
+     */
+    acquireOwnership(rollout: string): Promise<RolloutOwnership>;
+}
+export interface CreateRolloutLockOptions {
+    agent: string;
+    logger: Logger;
+    /** Session-map root (shared with the injected {@link ToolActivitySessionMap}). */
+    root?: string;
+    /** Filesystem-socket dir for the fallback backend (tests). */
+    socketDir?: string;
+    /**
+     * Test seam: force a backend. `'flock'` requires a loadable binding; `'socket'`
+     * forces the fallback even where `fs-ext` would load. Default: auto-detect `fs-ext`.
+     */
+    prefer?: 'auto' | 'flock' | 'socket';
+    /**
+     * Test seam: replace the `fs-ext` loader entirely so tests do NOT depend on whether the
+     * optional native dep is installed on the host. Return a fake `flockSync` to exercise the
+     * flock backend, or `null` to deterministically force the no-binding path.
+     */
+    loaderForTest?: () => FlockSyncFn | null;
+}
+/**
+ * Resolve the codex rollout-lock backend (§4.5 X3-AMEND-1 HYBRID): the real
+ * `flock` backend when the OPTIONAL native `fs-ext` binding loads, else the
+ * pure-Node socket fallback. A failed optional build NEVER breaks install — it
+ * degrades to the fallback (logged once so the residual is observable).
+ */
+export declare function createRolloutLock(opts: CreateRolloutLockOptions): RolloutLock;

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

@@ -0,0 +1,9 @@
+export * from './types';
+export * from './digest';
+export * from './outbox';
+export * from './ledger';
+export * from './replay-cursor';
+export * from './session-map';
+export * from './socket-rollout-lock';
+export * from './flock-rollout-lock';
+export * from './consolidator';