@pellux/goodvibes-tui 1.27.0 → 2.0.1

package/src/core/session-recovery.ts

@@ -1,210 +0,0 @@
-/**
- * session-recovery.ts — Journal replay at session resume.
- *
- * Purpose
- * ───────
- * When a session is resumed, this module checks whether a transcript journal
- * exists for that session whose records post-date the loaded snapshot. If so,
- * it replays those records onto the live conversation and writes a fresh
- * snapshot so the gap is permanently closed.
- *
- * Seams (both must call replayJournalForSession)
- * ───────────────────────────────────────────────
- * 1. CLI / command resume — session-workflow.ts, after `fromJSON` +
- *    `rebuildHistory` complete. Handles --continue, --resume, /session resume,
- *    and --fork.
- * 2. In-TUI panel resume — bootstrap-hook-bridge.ts
- *    `createResumeSessionHandler`, after `options.runtime.sessionId` is
- *    assigned. Handles the session browser / panel-driven resume.
- *
- * Recovery protocol
- * ─────────────────
- * 1. Call replayJournal() with the journal path and the snapshot timestamp.
- * 2. If no records are newer than the snapshot, rotate the (now-stale)
- *    journal silently and return.
- * 3. If records are found, apply the final record's messages — each journal
- *    record carries the full conversation snapshot at that moment, so the
- *    record with the newest timestamp is the authoritative post-crash state
- *    (resilient to seq collisions across re-inits onto a stale journal file).
- * 4. Rebuild the conversation history and call the snapshot writer so the
- *    gap is durably closed before the user sees the restored conversation.
- * 5. Rotate the journal (it is no longer needed as a gap-filler).
- * 6. Return a result so the caller can emit an honest notice.
- */
-
-import { journalPathFor, openTranscriptJournal, replayJournal } from './transcript-journal.ts';
-import type { ConversationManager } from './conversation.ts';
-import type { ConversationMessageSnapshot } from '@pellux/goodvibes-sdk/platform/core';
-import type { SessionSurface } from '@/runtime/index.ts';
-
-// ─── Types ──────────────────────────────────────────────────────────────────
-
-export interface ReplayIntoConversationOptions {
-  /** Absolute path to the journal file for this session. */
-  readonly journalPath: string;
-  /**
-   * The `timestamp` field from the loaded session snapshot (SessionMeta).
-   * Only journal records with ts > snapshotTimestamp are replayed.
-   */
-  readonly snapshotTimestamp: number;
-  /** The live conversation manager to mutate with replayed messages. */
-  readonly conversation: ConversationManager;
-  /** Session ID — used when creating the post-replay journal instance for rotate(). */
-  readonly sessionId: string;
-  /**
-   * Persist the restored conversation so the gap is durably closed.
-   * Called with the final replayed message list. Best-effort — failures
-   * are swallowed so recovery never hard-fails a resume.
-   */
-  readonly persistSnapshot: (messages: ConversationMessageSnapshot[]) => void;
-}
-
-export interface ReplayIntoConversationResult {
-  /** Number of journal records that post-dated the snapshot. 0 if nothing to replay. */
-  readonly replayed: number;
-  /** True if the journal tail was corrupt (quarantined). */
-  readonly hadCorruptTail: boolean;
-}
-
-// ─── Public API ─────────────────────────────────────────────────────────────
-
-/**
- * Replay journal records newer than `snapshotTimestamp` onto `conversation`.
- *
- * Returns a result object so the caller can emit an appropriate notice.
- * Never throws — all errors are swallowed to preserve the "best-effort"
- * recovery contract.
- */
-export function replayJournalIntoConversation(
-  options: ReplayIntoConversationOptions,
-): ReplayIntoConversationResult {
-  const { journalPath, snapshotTimestamp, conversation, sessionId, persistSnapshot } = options;
-
-  try {
-    const { records, hadCorruptTail } = replayJournal(journalPath, snapshotTimestamp);
-
-    const journal = openTranscriptJournal(journalPath, sessionId);
-
-    if (records.length === 0) {
-      // Nothing to replay — rotate the (now-stale) journal silently.
-      journal.rotate();
-      return { replayed: 0, hadCorruptTail };
-    }
-
-    // Select the authoritative record by newest wall-clock timestamp (tie-broken
-    // by highest seq). Each record carries the full conversation snapshot at its
-    // moment, so the newest ts is by definition the most recent state. This is
-    // resilient to seq collisions that arise when a fresh process appends to a
-    // pre-existing, non-rotated journal: its records restart at seq 0 after the
-    // surviving old records, so "last by seq" could otherwise pick a stale one.
-    const lastRecord = records.reduce((newest, candidate) =>
-      candidate.ts > newest.ts ||
-      (candidate.ts === newest.ts && candidate.seq > newest.seq)
-        ? candidate
-        : newest,
-    );
-    const replayedMessages = lastRecord.messages as ConversationMessageSnapshot[];
-
-    // Preserve the session identity (title/titleSource/branches/currentBranch)
-    // that the resume seam already hydrated onto the live conversation. Journal
-    // records carry only messages, so a bare fromJSON would blank the title and
-    // reset titleSource to the system default — and the next TURN_COMPLETED
-    // snapshot would then persist the empty title, making the loss permanent.
-    const preserved = conversation.toJSON();
-    conversation.fromJSON({
-      ...preserved,
-      messages: replayedMessages as never[],
-      title: conversation.title,
-      titleSource: conversation.getTitleSource(),
-    });
-    conversation.rebuildHistory();
-
-    // Write a fresh snapshot so the gap is durably closed even if the
-    // process is killed again before the next turn-complete snapshot.
-    try {
-      persistSnapshot(replayedMessages);
-    } catch {
-      // Best-effort — never hard-fail recovery due to snapshot write failure.
-    }
-
-    // Rotate the journal — it is no longer needed as a gap-filler.
-    journal.rotate();
-
-    return { replayed: records.length, hadCorruptTail };
-  } catch {
-    // Absolute last-resort guard — recovery must never crash a resume.
-    return { replayed: 0, hadCorruptTail: false };
-  }
-}
-
-/**
- * Build the journal path for a given session and home directory, then call
- * replayJournalIntoConversation().
- *
- * Convenience wrapper used by session-workflow.ts so it does not need to
- * import journalPathFor directly.
- */
-export function replayJournalForSession(
-  options: Omit<ReplayIntoConversationOptions, 'journalPath'> & {
-    readonly surface: SessionSurface;
-  },
-): ReplayIntoConversationResult {
-  const journalPath = journalPathFor(options.surface, options.sessionId);
-  return replayJournalIntoConversation({ ...options, journalPath });
-}
-
-// ─── Prompted crash-snapshot restore ────────────────────────────────────────
-
-/** What a crash-recovery snapshot carries back from disk. */
-export interface RecoverySnapshotPayload {
-  readonly messages: Array<Record<string, unknown>>;
-  readonly title?: string | undefined;
-  readonly titleSource?: string | undefined;
-  readonly timestamp?: number | undefined;
-}
-
-export interface ApplyRecoverySnapshotResult {
-  /** Messages the conversation holds once the snapshot (plus any journal tail) is in place. */
-  readonly messageCount: number;
-  /** Journal records that post-dated the snapshot and were folded in on top of it. */
-  readonly journalReplay: ReplayIntoConversationResult;
-}
-
-/**
- * Apply a crash-recovery snapshot the user explicitly asked to resume.
- *
- * This is deliberately the same sequence `resumeSessionCore` runs for a saved
- * session — reset, fromJSON, rebuildHistory, then fold in any journal records
- * newer than the snapshot — with one difference: the messages come from the
- * recovery file the SDK just handed back (`consumeRecovery`) instead of the
- * session store, because a session that crashed before its first clean save
- * has no entry in the store to load. Nothing here decides WHETHER to restore;
- * the caller has already asked the user (see runtime/recovery-prompt.ts).
- */
-export function applyRecoverySnapshot(options: {
-  readonly snapshot: RecoverySnapshotPayload;
-  readonly sessionId: string;
-  readonly conversation: ConversationManager;
-  readonly surface: SessionSurface;
-  readonly persistSnapshot: (messages: ConversationMessageSnapshot[]) => void;
-}): ApplyRecoverySnapshotResult {
-  const { snapshot, sessionId, conversation, surface, persistSnapshot } = options;
-
-  conversation.resetAll();
-  conversation.fromJSON({
-    messages: snapshot.messages as never[],
-    title: snapshot.title,
-    titleSource: snapshot.titleSource as never,
-  });
-  conversation.rebuildHistory();
-
-  const journalReplay = replayJournalForSession({
-    surface,
-    sessionId,
-    snapshotTimestamp: snapshot.timestamp ?? 0,
-    conversation,
-    persistSnapshot,
-  });
-
-  return { messageCount: conversation.getMessageCount(), journalReplay };
-}

package/src/core/stable-host.ts

@@ -1,171 +0,0 @@
-/**
- * stable-host.ts — a stable name for printed/QR pairing links.
- *
- * The legacy resolution used the first non-internal IPv4 in enumeration order
- * (see getLocalNetworkIp in management-utils.ts). That address is bound to the
- * current DHCP lease: when the lease changes, every printed link and every QR
- * that encoded it stops resolving. This module resolves a name that survives a
- * lease change where one exists, and only falls back to a routable address when
- * no stable name is available.
- *
- * Resolution ladder (highest preference first):
- *   1. Tailscale MagicDNS name — preferred when tailscale is up. It resolves on
- *      and off the LAN and is never bound to a DHCP lease.
- *   2. mDNS `<hostname>.local` — a LAN name a DHCP change does not break.
- *   3. Gateway-routed interface address — the IPv4 on the default-route
- *      interface (not merely the first non-internal one, which can land on a
- *      bridge/VPN). The last resort; DHCP-bound.
- *   4. Loopback — nothing routable enumerated.
- *
- * The resolver (resolveStableHost) is a pure function of injected inputs so the
- * ladder is testable under mocked interface / tailscale states; the probes that
- * gather those inputs are impure and bounded, and degrade to undefined rather
- * than throw when a tool is missing or slow.
- */
-import { execFileSync } from 'node:child_process';
-import { hostname as osHostname, networkInterfaces } from 'node:os';
-
-export type StableHostKind = 'tailscale-magicdns' | 'mdns-local' | 'gateway-interface' | 'loopback';
-
-export interface TailscaleState {
-  /** BackendState === 'Running'. */
-  readonly up: boolean;
-  /** Self.DNSName from `tailscale status --json`, trailing dot stripped. */
-  readonly magicDnsName?: string | undefined;
-}
-
-export interface StableHostInputs {
-  /** os.hostname(), possibly an FQDN — the `.local` name derives from its first label. */
-  readonly hostname: string;
-  /** The routable IPv4 on the default-route interface, when known. */
-  readonly gatewayInterfaceIp?: string | undefined;
-  /** First non-internal IPv4 in enumeration order — the legacy fallback address. */
-  readonly firstNonInternalIp?: string | undefined;
-  /** Tailscale state, when the CLI is present and answered in time. */
-  readonly tailscale?: TailscaleState | undefined;
-}
-
-export interface ResolvedStableHost {
-  readonly host: string;
-  readonly kind: StableHostKind;
-  /** True when `host` is a name that survives a DHCP lease change. */
-  readonly stable: boolean;
-}
-
-function stripTrailingDot(name: string): string {
-  return name.replace(/\.+$/, '');
-}
-
-/** `<hostname>.local` from the first label of a hostname, or null when there is no usable label. */
-export function mdnsLocalName(host: string): string | null {
-  const label = (host ?? '').trim().split('.')[0]?.trim();
-  if (!label || label.toLowerCase() === 'localhost') return null;
-  // Already a `.local` name (hostname was set to the mDNS form): keep it as-is.
-  if (host.trim().toLowerCase().endsWith('.local')) return stripTrailingDot(host.trim());
-  return `${label}.local`;
-}
-
-/**
- * Resolve the stable host from injected inputs. Pure — no I/O — so the ladder is
- * exercised directly under mocked interface / tailscale states.
- */
-export function resolveStableHost(inputs: StableHostInputs): ResolvedStableHost {
-  const magic = inputs.tailscale?.up ? inputs.tailscale.magicDnsName?.trim() : undefined;
-  if (magic) return { host: stripTrailingDot(magic), kind: 'tailscale-magicdns', stable: true };
-
-  const local = mdnsLocalName(inputs.hostname);
-  if (local) return { host: local, kind: 'mdns-local', stable: true };
-
-  const routed = inputs.gatewayInterfaceIp?.trim() || inputs.firstNonInternalIp?.trim();
-  if (routed) return { host: routed, kind: 'gateway-interface', stable: false };
-
-  return { host: '127.0.0.1', kind: 'loopback', stable: false };
-}
-
-/** First non-internal IPv4 in enumeration order (the legacy fallback address). */
-export function firstNonInternalIpv4(nets: ReturnType<typeof networkInterfaces>): string | undefined {
-  for (const name of Object.keys(nets)) {
-    for (const netInfo of nets[name] ?? []) {
-      if (netInfo.family === 'IPv4' && !netInfo.internal) return netInfo.address;
-    }
-  }
-  return undefined;
-}
-
-/** Parse the `src <ip>` field out of a Linux `ip route get` line. */
-export function parseIpRouteSrc(output: string): string | undefined {
-  const match = /\bsrc\s+(\d+\.\d+\.\d+\.\d+)/.exec(output);
-  return match?.[1];
-}
-
-/** Parse `Self.DNSName` + running state out of `tailscale status --json` output. */
-export function parseTailscaleStatus(json: string): TailscaleState | undefined {
-  try {
-    const parsed = JSON.parse(json) as { BackendState?: unknown; Self?: { DNSName?: unknown } };
-    const up = parsed.BackendState === 'Running';
-    const dnsName = typeof parsed.Self?.DNSName === 'string' ? stripTrailingDot(parsed.Self.DNSName) : undefined;
-    return { up, ...(dnsName ? { magicDnsName: dnsName } : {}) };
-  } catch {
-    return undefined;
-  }
-}
-
-function probeGatewayInterfaceIp(): string | undefined {
-  try {
-    const out = execFileSync('ip', ['route', 'get', '1.1.1.1'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500 });
-    return parseIpRouteSrc(out);
-  } catch {
-    return undefined;
-  }
-}
-
-function probeTailscaleState(): TailscaleState | undefined {
-  try {
-    const out = execFileSync('tailscale', ['status', '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500 });
-    return parseTailscaleStatus(out);
-  } catch {
-    return undefined;
-  }
-}
-
-/** Gather the impure inputs the resolver needs, each bounded and failure-tolerant. */
-export function probeStableHostInputs(): StableHostInputs {
-  let nets: ReturnType<typeof networkInterfaces> = {};
-  try {
-    nets = networkInterfaces();
-  } catch {
-    nets = {};
-  }
-  const first = firstNonInternalIpv4(nets);
-  const gateway = probeGatewayInterfaceIp();
-  const tailscale = probeTailscaleState();
-  return {
-    hostname: safeHostname(),
-    ...(gateway ? { gatewayInterfaceIp: gateway } : {}),
-    ...(first ? { firstNonInternalIp: first } : {}),
-    ...(tailscale ? { tailscale } : {}),
-  };
-}
-
-function safeHostname(): string {
-  try {
-    return osHostname();
-  } catch {
-    return '';
-  }
-}
-
-/**
- * The stable host for a printed/QR link given the endpoint's bind host. A
- * wildcard bind (0.0.0.0 / ::) resolves through the ladder; an explicit bind
- * host is honored as-is (loopback stays loopback). `probe` is injectable for
- * tests.
- */
-export function stableUrlHostForBindHost(
-  host: string,
-  probe: () => StableHostInputs = probeStableHostInputs,
-): ResolvedStableHost {
-  if (host === '0.0.0.0' || host === '::') return resolveStableHost(probe());
-  const bound = host || '127.0.0.1';
-  return { host: bound, kind: bound === '127.0.0.1' ? 'loopback' : 'gateway-interface', stable: false };
-}