@pellux/goodvibes-tui 1.27.1 → 2.0.1

package/src/core/pairing-devices.ts

@@ -1,49 +0,0 @@
-/**
- * pairing-devices.ts — shared rendering for the paired-device list.
- *
- * Both the /devices command family and the settings device-management modal
- * render each per-device token the same way (name · created · last-seen · id),
- * so the two surfaces never drift. Pure over its inputs and a `now` clock, so
- * the formatting is testable without real time.
- */
-import type { PublicPairingToken } from '@pellux/goodvibes-sdk/platform/pairing';
-
-/** A short, human-quotable id prefix used to target rename/revoke. */
-export function shortTokenId(id: string): string {
-  return id.slice(0, 8);
-}
-
-/** Relative last-seen, or "never" when the device has not authenticated yet. */
-export function formatLastSeen(ms: number | undefined, now: number = Date.now()): string {
-  if (ms === undefined) return 'never';
-  const delta = Math.max(0, now - ms);
-  if (delta < 60_000) return 'just now';
-  const mins = Math.floor(delta / 60_000);
-  if (mins < 60) return `${mins}m ago`;
-  const hours = Math.floor(mins / 60);
-  if (hours < 24) return `${hours}h ago`;
-  return `${Math.floor(hours / 24)}d ago`;
-}
-
-/** Creation date as YYYY-MM-DD. */
-export function formatCreated(ms: number): string {
-  return new Date(ms).toISOString().slice(0, 10);
-}
-
-/** One device line: name · created · last-seen · short id. */
-export function formatDeviceLine(token: PublicPairingToken, now: number = Date.now()): string {
-  return `${token.name}  ·  created ${formatCreated(token.createdAt)}  ·  last seen ${formatLastSeen(token.lastSeenAt, now)}  ·  ${shortTokenId(token.id)}`;
-}
-
-/** Resolve a token by exact id or unambiguous id-prefix; returns a resolution result. */
-export function resolveTokenByIdPrefix(
-  tokens: readonly PublicPairingToken[],
-  idOrPrefix: string,
-): { readonly ok: true; readonly token: PublicPairingToken } | { readonly ok: false; readonly reason: 'not-found' | 'ambiguous' } {
-  const exact = tokens.find((t) => t.id === idOrPrefix);
-  if (exact) return { ok: true, token: exact };
-  const matches = tokens.filter((t) => t.id.startsWith(idOrPrefix));
-  if (matches.length === 1) return { ok: true, token: matches[0]! };
-  if (matches.length === 0) return { ok: false, reason: 'not-found' };
-  return { ok: false, reason: 'ambiguous' };
-}

package/src/core/pairing-handoff.ts

@@ -1,101 +0,0 @@
-/**
- * pairing-handoff.ts — the one place a TUI pairing producer mints a link.
- *
- * Every producer (the `gv pair` CLI block, the pairing modal QR, the /qrcode
- * flow) routes through mintPairingHandoff, which mints a fresh per-device token
- * and encodes the SDK's canonical `#pair=<token>` deep link — the exact shape
- * the web app consumes, byte-for-byte the same as the `pairing.handoff.create`
- * gateway verb's handler (mint + buildPairingHandoffLink). No producer encodes a
- * raw JSON connection blob any more: a camera scan of the QR opens the web app
- * already carrying the one-time token, so the device lands signed in.
- *
- * The token rides in the URL fragment, never the query, so it is never sent to a
- * server (no access-log / Referer exposure). The offer set rides alongside so a
- * bundle-aware surface can present the notifications/relay/passkey steps.
- */
-import {
-  buildPairingHandoffFragment,
-  buildPairingHandoffLink,
-  describeOriginPosture,
-  type MintedPairingToken,
-  type OriginPosture,
-  type PairingHandoffOfferKind,
-} from '@pellux/goodvibes-sdk/platform/pairing';
-
-/** The token-minting surface a handoff needs — satisfied by the SDK's PairingTokenManager. */
-export interface PairingTokenMinter {
-  mint(input: { readonly name: string }): MintedPairingToken;
-}
-
-export interface PairingHandoff {
-  readonly token: MintedPairingToken;
-  readonly offers: readonly PairingHandoffOfferKind[];
-  /** `#pair=<token>` (with an `offers=` key when offers are present). */
-  readonly fragment: string;
-  /** `<webOrigin>/#pair=<token>` — present only when a web origin is known. */
-  readonly deepLink?: string | undefined;
-  /**
-   * The honest TLS/capability posture of the web origin the deep link opens —
-   * the same field the `pairing.handoff.create` gateway verb carries (both
-   * computed by the SDK's describeOriginPosture). Present only when a web origin
-   * is known; a surface renders its one honest LAN line and its labeled
-   * capability list from here, never from a locally-authored string.
-   */
-  readonly posture?: OriginPosture | undefined;
-}
-
-export interface MintPairingHandoffInput {
-  readonly pairingTokens: PairingTokenMinter;
-  /** The device/token name shown to the user and stored on the token; editable later. */
-  readonly name: string;
-  readonly offers: readonly PairingHandoffOfferKind[];
-  /** The web-app origin the deep link points at; absent ⇒ fragment-only. */
-  readonly webOrigin?: string | undefined;
-}
-
-/**
- * A default name for a freshly-minted pairing token when the user did not supply
- * one. Names are shown and editable later in the device management surface, so a
- * date-stamped default is enough to tell two devices apart at a glance.
- */
-export function defaultPairingTokenName(now: Date = new Date()): string {
-  const stamp = now.toISOString().slice(0, 16).replace('T', ' ');
-  return `paired device (${stamp})`;
-}
-
-export function mintPairingHandoff(input: MintPairingHandoffInput): PairingHandoff {
-  const token = input.pairingTokens.mint({ name: input.name });
-  const fragment = buildPairingHandoffFragment({ token: token.token, offers: input.offers });
-  const deepLink = input.webOrigin
-    ? buildPairingHandoffLink({ webOrigin: input.webOrigin, token: token.token, offers: input.offers })
-    : undefined;
-  // The posture is described from the SAME web origin the deep link opens — the
-  // identical computation the gateway verb performs — so a locally-minted handoff
-  // carries the same honest posture as one minted over the wire.
-  const posture = input.webOrigin ? describeOriginPosture(input.webOrigin) : undefined;
-  return { token, offers: input.offers, fragment, ...(deepLink ? { deepLink } : {}), ...(posture ? { posture } : {}) };
-}
-
-/** The link content a QR should encode: the full deep link when known, else the fragment. */
-export function pairingQrContent(handoff: PairingHandoff): string {
-  return handoff.deepLink ?? handoff.fragment;
-}
-
-export interface PairingOfferAvailability {
-  /** Whether the rendezvous relay is configured ⇒ the relay offer is presentable. */
-  readonly relayEnabled: boolean;
-  /** Whether a step-up (passkey) ceremony is wired ⇒ the passkey offer is presentable. */
-  readonly stepUpAvailable: boolean;
-}
-
-/**
- * The offers this daemon can satisfy right now, in canonical order. Notifications
- * are always available (browser push needs no server-side prerequisite beyond
- * the VAPID key the daemon mints on demand); relay and passkey are gated.
- */
-export function availablePairingOffers(availability: PairingOfferAvailability): PairingHandoffOfferKind[] {
-  const offers: PairingHandoffOfferKind[] = ['notifications'];
-  if (availability.relayEnabled) offers.push('relay');
-  if (availability.stepUpAvailable) offers.push('passkey');
-  return offers;
-}

package/src/core/pairing-offers.ts

@@ -1,83 +0,0 @@
-/**
- * pairing-offers.ts — plain-language copy for the pairing offer set, the one
- * honest LAN-posture line, and the labeled browser-capability list.
- *
- * Each offer names, in plain terms, what accepting it does and what declining it
- * costs — no security jargon, just the concrete consequence. Every offer is
- * independently declinable; a pairing without any accepted offer still pairs the
- * device (it just signs in with none of the extras).
- *
- * The one honest LAN line and the per-capability availability both come from the
- * SDK posture (describeOriginPosture / the `posture` field on a handoff), so
- * every surface renders the SAME truth: the exact LAN_PLAIN_HTTP_NOTICE wording
- * only when the posture carries it, and each browser-gated capability labeled
- * with whether the paired device gets it (and why not, when it does not).
- */
-import type {
-  BrowserGatedCapability,
-  OriginPosture,
-  PairingHandoffOfferKind,
-} from '@pellux/goodvibes-sdk/platform/pairing';
-
-export interface PairingOfferCopy {
-  readonly title: string;
-  /** One plain-language line: what accepting does, and what declining leaves you with. */
-  readonly consequence: string;
-}
-
-export const PAIRING_OFFER_COPY: Record<PairingHandoffOfferKind, PairingOfferCopy> = {
-  notifications: {
-    title: 'Notifications',
-    consequence: 'This device gets a push when an agent needs your input or a run finishes. Decline and it pairs without push.',
-  },
-  relay: {
-    title: 'Relay',
-    consequence: 'Reach this daemon from off the LAN through the rendezvous relay, which sees only ciphertext and connection metadata. Decline to stay LAN-only.',
-  },
-  passkey: {
-    title: 'Passkey',
-    consequence: 'Register a passkey on this device to confirm sensitive actions with a tap. Decline and sensitive actions ask another way.',
-  },
-};
-
-/** The offer set as `label — consequence` lines, in the given order. */
-export function formatPairingOffers(offers: readonly PairingHandoffOfferKind[]): string[] {
-  return offers.map((kind) => {
-    const copy = PAIRING_OFFER_COPY[kind];
-    return `  ${copy.title} — ${copy.consequence}`;
-  });
-}
-
-/**
- * Plain-language label for each browser-gated capability the posture reports —
- * what the paired device would actually get, named without jargon.
- */
-export const POSTURE_CAPABILITY_LABEL: Record<BrowserGatedCapability, string> = {
-  'service-worker': 'Offline app (installable / background sync)',
-  push: 'Push notifications',
-  microphone: 'Voice input (microphone)',
-};
-
-/**
- * The one honest LAN line to render, or null. This is the SDK posture's own
- * `notice` field verbatim (LAN_PLAIN_HTTP_NOTICE) — present ONLY for the
- * plain-http-on-LAN posture, absent (and so never a nag) everywhere else.
- */
-export function pairingPostureNotice(posture: OriginPosture | undefined): string | null {
-  return posture?.notice ?? null;
-}
-
-/**
- * The labeled capability list from the posture: each browser-gated capability as
- * a `Label — available` / `Label — <reason>` line, so the pairing surface lists
- * what the paired device will get instead of hiding a dead button. Empty when no
- * posture is known.
- */
-export function formatPostureCapabilities(posture: OriginPosture | undefined): string[] {
-  if (!posture) return [];
-  return posture.capabilities.map((cap) => {
-    const label = POSTURE_CAPABILITY_LABEL[cap.capability as BrowserGatedCapability] ?? cap.capability;
-    const status = cap.available ? 'available' : (cap.reason ?? 'unavailable');
-    return `  ${label} — ${status}`;
-  });
-}

package/src/core/pairing-origin.ts

@@ -1,78 +0,0 @@
-/**
- * pairing-origin.ts — the web-app origin a pairing deep link points at, and the
- * one-time write of web.publicBaseUrl from the stable-name resolution.
- *
- * The origin is the WEB endpoint's public URL (the surface the `#pair=<token>`
- * link opens), not the control-plane daemon URL. A user-set web.publicBaseUrl is
- * authoritative and is never re-derived or clobbered; only when it is empty do
- * we fall back to `http://<stable-host>:<web-port>` using the same ladder the
- * printed/QR link uses, so the link and the persisted origin always agree.
- */
-import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
-import { resolveRuntimeEndpointBinding } from '../cli/endpoints.ts';
-import { stableUrlHostForBindHost, type ResolvedStableHost, type StableHostInputs } from './stable-host.ts';
-
-export interface PairingWebOrigin {
-  readonly origin: string;
-  readonly resolvedHost: ResolvedStableHost;
-  /** True when the origin is http:// on a non-loopback host — the honest LAN-posture case. */
-  readonly httpOnLan: boolean;
-  /** True when the origin came verbatim from a user-set web.publicBaseUrl. */
-  readonly fromPublicBaseUrl: boolean;
-}
-
-function trimTrailingSlash(value: string): string {
-  return value.replace(/\/+$/, '');
-}
-
-/** http:// on anything other than loopback is served in the clear on the LAN. */
-export function isHttpOnLan(origin: string): boolean {
-  if (!origin.startsWith('http://')) return false;
-  let host: string;
-  try {
-    host = new URL(origin).hostname;
-  } catch {
-    return false;
-  }
-  return host !== '127.0.0.1' && host !== 'localhost' && host !== '::1';
-}
-
-export function resolvePairingWebOrigin(
-  configManager: Pick<ConfigManager, 'get'>,
-  probe?: () => StableHostInputs,
-): PairingWebOrigin {
-  const publicBaseUrl = trimTrailingSlash(String(configManager.get('web.publicBaseUrl') ?? '').trim());
-  if (publicBaseUrl) {
-    return { origin: publicBaseUrl, resolvedHost: { host: hostnameOf(publicBaseUrl), kind: 'gateway-interface', stable: true }, httpOnLan: isHttpOnLan(publicBaseUrl), fromPublicBaseUrl: true };
-  }
-  const binding = resolveRuntimeEndpointBinding(configManager, 'web');
-  const resolvedHost = stableUrlHostForBindHost(binding.host, probe);
-  const origin = `http://${resolvedHost.host}:${binding.port}`;
-  return { origin, resolvedHost, httpOnLan: isHttpOnLan(origin), fromPublicBaseUrl: false };
-}
-
-function hostnameOf(origin: string): string {
-  try {
-    return new URL(origin).hostname;
-  } catch {
-    return origin;
-  }
-}
-
-/**
- * Persist web.publicBaseUrl once, from the stable-name resolution, and only when
- * it is empty AND the resolution produced a stable name (a DHCP-bound address is
- * not worth freezing into config). Returns the resolved origin either way. Never
- * overwrites a user-set value.
- */
-export function ensurePublicBaseUrl(
-  configManager: Pick<ConfigManager, 'get' | 'setDynamic'>,
-  probe?: () => StableHostInputs,
-): PairingWebOrigin {
-  const resolved = resolvePairingWebOrigin(configManager, probe);
-  if (!resolved.fromPublicBaseUrl && resolved.resolvedHost.stable) {
-    configManager.setDynamic('web.publicBaseUrl', resolved.origin);
-    return { ...resolved, fromPublicBaseUrl: true };
-  }
-  return resolved;
-}

package/src/core/rewind-turn-anchors.ts

@@ -1,311 +0,0 @@
-/**
- * rewind-turn-anchors.ts — the session-scoped join key between the conversation
- * and the workspace-checkpoint store, for message-anchored rewind.
- *
- * The unified rewind service (SDK platform/rewind) anchors a rewind to a
- * `{ sessionId, turnId }`. Files-scope resolves that turnId against the
- * workspace checkpoints the turn engine already stamps with the same turnId.
- * Conversation-scope, however, needs to know HOW MANY conversation messages
- * existed at that turn boundary — a mapping the SDK's checkpoint store does not
- * carry (TUI turn-checkpoints are not stamped with a conversation-message
- * count). This registry supplies exactly that mapping: at every TURN_COMPLETED
- * the TUI records the turnId together with the live `conversation.getMessageCount()`,
- * so a later rewind to that turnId can truncate the conversation to precisely
- * the boundary the files checkpoint captured.
- *
- * Scope + lifetime: in-memory, keyed by sessionId. The registry is the live
- * working copy; it is mirrored to a small per-session sidecar file next to the
- * session's JSONL (`<sessionsDir>/<sessionId>.anchors.json`) at every turn, and
- * `restoreTurnAnchors` reloads that sidecar on resume so message-anchored
- * /rewind works identically before and after a resume. The sidecar's
- * `messageCount` boundaries stay valid because a resume rehydrates the same
- * message history the anchors were recorded against.
- */
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import type { SessionSurface } from '@/runtime/index.ts';
-
-
-/** One recorded turn boundary — the rewind coordinator's per-turn anchor. */
-export interface TurnAnchor {
-  /** The turn engine's turn id, shared with the workspace checkpoint's `turnId`. */
-  readonly turnId: string;
-  /** A short human label (the truncated user prompt) for the recent-turns picker. */
-  readonly label: string;
-  /** `conversation.getMessageCount()` captured at this turn's completion — the conversation truncation boundary. */
-  readonly messageCount: number;
-  /** Wall-clock ms at capture, for ordering + age display. */
-  readonly at: number;
-}
-
-/** Hard cap so a very long session cannot grow this registry without bound. */
-const MAX_ANCHORS_PER_SESSION = 500;
-
-const registry = new Map<string, TurnAnchor[]>();
-
-/** Trim a user prompt to a single compact line for the picker. */
-export function summarizeTurnLabel(text: string | null | undefined, max = 72): string {
-  const oneLine = (text ?? '').replace(/\s+/g, ' ').trim();
-  if (oneLine.length === 0) return '(no prompt text)';
-  return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
-}
-
-/**
- * Record a completed turn's anchor. Idempotent per turnId: a repeated turnId
- * updates the existing entry in place (the checkpoint engine can re-snapshot a
- * turn) rather than duplicating it.
- */
-export function recordTurnAnchor(sessionId: string, anchor: TurnAnchor): void {
-  if (!sessionId || !anchor.turnId) return;
-  const list = registry.get(sessionId) ?? [];
-  const existingIndex = list.findIndex((a) => a.turnId === anchor.turnId);
-  if (existingIndex >= 0) {
-    list[existingIndex] = anchor;
-  } else {
-    list.push(anchor);
-    if (list.length > MAX_ANCHORS_PER_SESSION) list.splice(0, list.length - MAX_ANCHORS_PER_SESSION);
-  }
-  registry.set(sessionId, list);
-}
-
-/** All recorded anchors for a session, oldest first (chronological). */
-export function getTurnAnchors(sessionId: string): readonly TurnAnchor[] {
-  return registry.get(sessionId) ?? [];
-}
-
-/** Resolve an anchor by exact turnId, or null when this run never recorded it. */
-export function resolveTurnAnchor(sessionId: string, turnId: string): TurnAnchor | null {
-  return registry.get(sessionId)?.find((a) => a.turnId === turnId) ?? null;
-}
-
-/** Drop a session's anchors. Exposed for tests and session reset. */
-export function clearTurnAnchors(sessionId: string): void {
-  registry.delete(sessionId);
-}
-
-// --- Cross-resume persistence -------------------------------------------------
-//
-// The TUI mirrors the in-memory registry to a sidecar next to the session file.
-// The directory comes off the caller's SessionSurface (`surface.sessionsDir`),
-// the same handle the session JSONL itself is written through — so the sidecar
-// and its session can never end up in different directories.
-const ANCHOR_SIDECAR_VERSION = 1;
-
-/** Absolute path to a session's anchor sidecar, or null when inputs are unusable. */
-const ANCHOR_SIDECAR_SUFFIX = '.anchors.json';
-
-function anchorSidecarPath(sessionId: string, surface: SessionSurface): string | null {
-  if (!sessionId || !surface.sessionsDir) return null;
-  // A sessionId is a filename component; refuse anything with path separators so
-  // a malformed id can never escape the sessions directory.
-  if (/[\\/]/.test(sessionId)) return null;
-  return join(surface.sessionsDir, `${sessionId}${ANCHOR_SIDECAR_SUFFIX}`);
-}
-
-function isTurnAnchor(value: unknown): value is TurnAnchor {
-  if (typeof value !== 'object' || value === null) return false;
-  const a = value as Record<string, unknown>;
-  return (
-    typeof a.turnId === 'string' && a.turnId.length > 0 &&
-    typeof a.label === 'string' &&
-    typeof a.messageCount === 'number' && Number.isFinite(a.messageCount) &&
-    typeof a.at === 'number' && Number.isFinite(a.at)
-  );
-}
-
-/**
- * Write the current in-memory anchors for a session to its sidecar so they
- * survive a resume. Best-effort and atomic (temp file + rename): a failed or
- * torn write must never break the turn that triggered it. Called after each
- * `recordTurnAnchor` at TURN_COMPLETED.
- */
-export function persistTurnAnchors(sessionId: string, surface: SessionSurface): void {
-  const path = anchorSidecarPath(sessionId, surface);
-  if (!path) return;
-  const list = registry.get(sessionId) ?? [];
-  if (list.length === 0) return; // nothing to mirror yet
-  try {
-    mkdirSync(surface.sessionsDir, { recursive: true });
-    const payload = JSON.stringify({ version: ANCHOR_SIDECAR_VERSION, sessionId, anchors: list });
-    const tmp = `${path}${ANCHOR_SIDECAR_TMP_MARKER}${process.pid}`;
-    writeFileSync(tmp, payload);
-    renameSync(tmp, path);
-  } catch {
-    /* best-effort; a rewind-anchor persist miss must never break the turn */
-  }
-}
-
-/**
- * Reload a session's persisted anchors into the in-memory registry on resume.
- * Returns the number of anchors restored (0 when no sidecar exists or it is
- * unreadable). Idempotent via `recordTurnAnchor`'s per-turnId dedup, so a resume
- * that later re-records the same turn keeps a single entry.
- */
-export function restoreTurnAnchors(sessionId: string, surface: SessionSurface): number {
-  const path = anchorSidecarPath(sessionId, surface);
-  if (!path || !existsSync(path)) return 0;
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf8')) as { anchors?: unknown };
-    if (!parsed || !Array.isArray(parsed.anchors)) return 0;
-    let restored = 0;
-    for (const candidate of parsed.anchors) {
-      if (isTurnAnchor(candidate)) {
-        recordTurnAnchor(sessionId, candidate);
-        restored++;
-      }
-    }
-    return restored;
-  } catch {
-    return 0;
-  }
-}
-
-// ─── Reaping orphaned sidecars ────────────────────────────────────────────────
-//
-// A sidecar's OWNER is the session JSONL it sits beside. Deleting a session
-// removes the JSONL but nothing ever removed the sidecar, so anchors for
-// sessions that no longer exist accumulate in the sessions directory forever.
-// The sweep below reclaims them, plus the `.tmp-<pid>` staging files a crash
-// between write and rename leaves behind.
-
-/** Infix for the atomic-write staging file, before the writing process's pid. */
-const ANCHOR_SIDECAR_TMP_MARKER = '.tmp-';
-
-/**
- * How long a staging file is tolerated before it is treated as crash residue:
- * 1 hour. `persistTurnAnchors` renames within microseconds of writing, so
- * anything this old was interrupted, and the completed sidecar (if the write
- * ever finished) is a separate file.
- */
-export const ANCHOR_TMP_MAX_AGE_MS = 60 * 60 * 1000;
-
-/**
- * How settled a sidecar must be before this sweep will delete it: 1 hour.
- *
- * Another instance can be persisting anchors for a session this process knows
- * nothing about, and the window between reading a sidecar's content and
- * unlinking it is not atomic. Requiring the file to have been untouched for an
- * hour means a sidecar that some other instance is actively rewriting is never
- * a candidate, while genuine residue — whose writer is long gone — always is.
- * The sweep repeats, so the delay costs nothing.
- */
-export const ANCHOR_SIDECAR_SETTLE_MS = 60 * 60 * 1000;
-
-export interface AnchorSidecarReapResult {
-  /** Sidecar and staging files examined this sweep. */
-  readonly scanned: number;
-  /** Files deleted this sweep. */
-  readonly reaped: number;
-}
-
-export interface AnchorSidecarReapOptions {
-  /** The session this process is using right now; its sidecar is never reaped. */
-  readonly currentSessionId?: string | null;
-  readonly now?: () => number;
-  /** Override the staging-file age window (tests). */
-  readonly tmpMaxAgeMs?: number;
-  /** Override how long a sidecar must be untouched before it can be reaped (tests). */
-  readonly settleMs?: number;
-}
-
-/**
- * Delete anchor sidecars whose owning session file is gone, sidecars that hold
- * nothing readable, and abandoned staging files.
- *
- * A sidecar survives when `<sessionsDir>/<sessionId>.jsonl` still exists AND
- * the sidecar itself parses into at least one usable anchor — content, not
- * mere existence, because a sidecar truncated by a crash restores nothing and
- * would otherwise sit there indefinitely looking like valid state. It also
- * survives while it is still fresh (see `ANCHOR_SIDECAR_SETTLE_MS`), which
- * keeps a sidecar another instance is mid-rewrite out of reach.
- *
- * The current session's sidecar is never touched, and an unreadable or absent
- * sessions directory simply reclaims nothing. Idempotent and concurrency-safe:
- * a file another sweeper unlinked first (ENOENT) counts as reaped.
- */
-export function reapOrphanedAnchorSidecars(
-  surface: SessionSurface,
-  options: AnchorSidecarReapOptions = {},
-): AnchorSidecarReapResult {
-  const dir = surface.sessionsDir;
-  if (!dir) return { scanned: 0, reaped: 0 };
-
-  let names: string[];
-  try {
-    names = readdirSync(dir).filter(
-      (n) => n.endsWith(ANCHOR_SIDECAR_SUFFIX) || n.includes(`${ANCHOR_SIDECAR_SUFFIX}${ANCHOR_SIDECAR_TMP_MARKER}`),
-    );
-  } catch {
-    return { scanned: 0, reaped: 0 };
-  }
-
-  const now = options.now?.() ?? Date.now();
-  const tmpMaxAgeMs = options.tmpMaxAgeMs ?? ANCHOR_TMP_MAX_AGE_MS;
-  const settleMs = options.settleMs ?? ANCHOR_SIDECAR_SETTLE_MS;
-  let reaped = 0;
-
-  for (const name of names) {
-    const path = join(dir, name);
-
-    if (!name.endsWith(ANCHOR_SIDECAR_SUFFIX)) {
-      // A `<sessionId>.anchors.json.tmp-<pid>` staging file. Age alone decides:
-      // a young one may belong to another instance's in-flight write.
-      let mtimeMs: number;
-      try {
-        mtimeMs = statSync(path).mtimeMs;
-      } catch {
-        continue;
-      }
-      if (now - mtimeMs > tmpMaxAgeMs && unlinkAnchorFile(path)) reaped++;
-      continue;
-    }
-
-    const sessionId = name.slice(0, name.length - ANCHOR_SIDECAR_SUFFIX.length);
-    if (sessionId.length === 0) continue;
-    if (options.currentSessionId && sessionId === options.currentSessionId) continue;
-
-    // A sidecar written moments ago belongs to a writer that is still around —
-    // possibly another instance whose session this process cannot see.
-    let sidecarMtimeMs: number;
-    try {
-      sidecarMtimeMs = statSync(path).mtimeMs;
-    } catch {
-      continue;
-    }
-    if (now - sidecarMtimeMs <= settleMs) continue;
-
-    if (!existsSync(join(dir, `${sessionId}.jsonl`))) {
-      // The owning session is gone — this sidecar can never be used again.
-      if (unlinkAnchorFile(path)) reaped++;
-      continue;
-    }
-    if (!sidecarHoldsAnchors(path)) {
-      // The session survives but the sidecar is empty or torn: it restores
-      // nothing, so keeping it only hides the loss.
-      if (unlinkAnchorFile(path)) reaped++;
-    }
-  }
-
-  return { scanned: names.length, reaped };
-}
-
-/** Content check: does this sidecar parse into at least one usable anchor? */
-function sidecarHoldsAnchors(path: string): boolean {
-  try {
-    const text = readFileSync(path, 'utf8');
-    if (text.trim().length === 0) return false;
-    const parsed = JSON.parse(text) as { anchors?: unknown };
-    return Array.isArray(parsed?.anchors) && parsed.anchors.some(isTurnAnchor);
-  } catch {
-    return false;
-  }
-}
-
-function unlinkAnchorFile(path: string): boolean {
-  try {
-    unlinkSync(path);
-    return true;
-  } catch (err) {
-    return (err as NodeJS.ErrnoException | undefined)?.code === 'ENOENT';
-  }
-}