@phnx-labs/agents-cli 1.22.114 → 1.22.116

package/dist/lib/session/db.d.ts

@@ -31,8 +31,13 @@ export declare const SCHEMA_VERSION = 50;
  * v4 (PHNX-3621 leftover) invalidates Grok rows stamped before the bounded
  * chat_history.jsonl prefix read filled firstUserMessage.
  * v5 (PHNX-3939) restores first-meta Codex fork ownership, including cold files.
+ * v6 (PHNX-3999) invalidates rows whose stored `label` is harness scaffolding — a
+ * `<bash-input>` shell echo, a `<command-name>` wrapper, a bare `/clear` — which
+ * `cleanGeneratedSessionLabel` now rejects. The label is written at index time, so
+ * without this bump every already-indexed session keeps showing the junk title
+ * until its transcript happens to change.
  */
-export declare const CONTENT_INDEX_VERSION = 5;
+export declare const CONTENT_INDEX_VERSION = 6;
 /**
  * Bumping this invalidates every cached facet row without touching the schema
  * version, so a change to the extraction logic (a new metric, a corrected bucket)
@@ -106,7 +111,9 @@ export interface QueryOptions {
     plugin?: string;
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
-export declare function getDB(): Database.Database;
+export declare function getDB(initialBusyTimeoutMs?: number): Database.Database;
+/** Bound synchronous cache contention without changing other database callers. */
+export declare function withSessionDBTimeout<T>(timeoutMs: number, operation: () => T): T;
 /** Close the cached database connection. */
 export declare function closeDB(): void;
 interface FtsOptimizeResult {
@@ -428,6 +435,60 @@ export declare function writeSessionPreviewCache<T>(entry: {
     fileSize: number | null;
     preview: T;
 }): void;
+/** Bump when the cached remote preview envelope shape changes so cached rows recompute (PHNX-3999 v1). */
+export declare const REMOTE_PREVIEW_SCHEMA_VERSION = 1;
+/**
+ * Per-envelope cache-write cap. The bounded fields above make a well-formed
+ * envelope small; this exists to refuse an outlier (a version-skewed peer, or
+ * a future field that forgets to bound itself) rather than let ONE session
+ * blow the total budget. A refused write is NOT an error — the caller still
+ * gets the live envelope for this call, it simply is not persisted, so the
+ * next call re-fetches instead of silently caching a giant blob.
+ */
+export declare const REMOTE_PREVIEW_ENVELOPE_MAX_BYTES: number;
+export interface RemotePreviewCacheRow {
+    /** When the envelope currently stored here (if `ok`) was fetched. */
+    fetchedAt: number;
+    /** Whether `envelope` is a real, successfully-fetched payload. */
+    ok: boolean;
+    envelope?: unknown;
+    failureReason?: string;
+    consecutiveFailures: number;
+    /** Epoch ms before which a fresh fetch attempt should be skipped (negative backoff). */
+    nextAttemptAt: number;
+    /** The caller's own last-observed `--revision` cursor, or undefined if no
+     * caller has ever supplied one for this (device, sessionId) pair. */
+    lastCallerRevision?: string;
+}
+/** Read the durable cached remote preview row for one (device, sessionId) pair,
+ * regardless of whether it currently holds a successful envelope. Undefined
+ * means this box has never attempted (or recorded) a fetch for that pair. */
+export declare function readRemotePreviewCache(device: string, sessionId: string): RemotePreviewCacheRow | undefined;
+/**
+ * Record the caller's own `--revision` cursor for one (device, sessionId)
+ * pair, independent of any fetch. A no-op if no row exists yet (nothing to
+ * compare against on a session this box has never fetched). This is what lets
+ * "same revision as last time" serve the durable cache with zero SSH
+ * indefinitely — the comparison is against THIS value, never against the
+ * envelope's own `details.sourceRevision` (which may be a different format).
+ */
+export declare function writeRemotePreviewCallerRevision(device: string, sessionId: string, revision: string): void;
+/**
+ * Record a successful remote fetch: replaces the payload and resets backoff.
+ * An envelope over {@link REMOTE_PREVIEW_ENVELOPE_MAX_BYTES} is refused —
+ * this is a write-path bound, not a request failure: the caller already has
+ * the live envelope for this call from the fetch that produced it, this only
+ * decides whether it is worth persisting.
+ */
+export declare function writeRemotePreviewCacheSuccess(device: string, sessionId: string, envelope: unknown, fetchedAt?: number, revision?: string): void;
+/**
+ * Record a failed remote fetch attempt with exponential backoff, WITHOUT
+ * discarding a prior good envelope — a session that answered once and is now
+ * offline still degrades to that last-good payload (read back via
+ * {@link readRemotePreviewCache}'s `ok`/`envelope`), annotated stale by the
+ * caller, rather than losing it the moment one attempt fails.
+ */
+export declare function writeRemotePreviewCacheFailure(device: string, sessionId: string, reason: string, backoffMs: (consecutiveFailures: number) => number, now?: number): void;
 /**
  * The session's durable user-turn text, as stored in the `session_text` FTS
  * `content` column at scan time (all harnesses, keyed by session_id). This is
@@ -510,7 +571,10 @@ export declare function readSessionTimelineEntry(id: string): SessionTimelineCac
  * read path. Deliberately does NOT parse the resume state: a live row needs the
  * 8 steps and the request, never the fold's bookkeeping.
  */
-export declare function readSessionTimelineAny(id: string): SessionTimelineProjection | undefined;
+export declare function readSessionTimelineAny(id: string, stamp?: {
+    fileMtimeMs: number;
+    fileSize: number;
+}): SessionTimelineProjection | undefined;
 /** Persist a folded timeline against the exact transcript bytes it was folded to. */
 export declare function writeSessionTimeline(entry: {
     id: string;