@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/session/live-metadata.js

@@ -1,31 +1,5 @@
-// ---------------------------------------------------------------------------
-// Live-registry → SessionMeta bridge (RUSH-2682)
-// ---------------------------------------------------------------------------
-//
-// A session the live registry (`getActiveSessions`) already knows about can be
-// minutes ahead of the transcript index on the SAME box: indexing is lazy and
-// only runs inside `discoverSessions`, so a session this machine JUST started is
-// "running" in `agents sessions --active` while `agents sessions preview <id>`
-// answers "No session matching" until an unrelated `agents sessions*` call
-// happens to scan (measured 7.6 min blind on zion, agents-cli 1.22.39).
-//
-// This module converts a running `ActiveSession` into a `SessionMeta` candidate
-// so the id resolver behind `preview` / `resume` / `focus` can resolve and render
-// a running session with no transcript row yet, instead of claiming it does not
-// exist. It parses no transcript and renders nothing — it only reshapes process
-// state the live registry already computed. When the transcript IS on disk, the
-// synthesized row carries its path, so the downstream `buildPreview` renders the
-// real digest. Without a path, a peer-owned row fetches its digest from that peer;
-// a genuinely local row renders the header + a "not indexed here" note.
 import { deriveShortId } from '../text/short-id.js';
-import { isSessionTrackedAgent } from './types.js';
-/**
- * Reshape one live `ActiveSession` into a `SessionMeta` candidate for the id
- * resolver. Returns `null` for a row that cannot back a durable session — no
- * `sessionId`, or a `kind` that is not a session-tracked harness (cloud/team
- * rows without a real agent transcript). Pure: the caller supplies `self` (the
- * local machine id) and `nowMs` so the row is deterministic and testable.
- */
+import { isSessionTrackedAgent } from '@phnx-labs/sessions-cli/reader';
 export function activeSessionToSessionMeta(active, self, nowMs) {
     const id = active.sessionId;
     if (!id)
@@ -41,18 +15,10 @@ export function activeSessionToSessionMeta(active, self, nowMs) {
         harness: active.harness,
         timestamp: new Date(startedMs).toISOString(),
         lastActivity: new Date(lastMs).toISOString(),
-        // An empty file path is honest — a just-created session may have no
-        // transcript on disk yet, and `buildPreview` renders the header + a live
-        // note for that case rather than trying to parse a missing file.
         filePath: active.sessionFile ?? '',
         cwd: active.cwd,
         project: active.project ?? undefined,
         label: active.label,
-        // Carried even though this projection only runs for a session with NO indexed
-        // row (so the value is `undefined` today): a hand-built SessionMeta that
-        // omits the rung is exactly the shape that silently degrades the headline the
-        // moment its reachability changes (PHNX-3797). Neither guard can see it here
-        // — it calls no ladder, and its fields sit on separate lines.
         generatedTitle: active.generatedTitle,
         topic: active.topic,
         firstUserMessage: active.firstUserMessage,
@@ -69,10 +35,6 @@ export function activeSessionToSessionMeta(active, self, nowMs) {
         routineName: active.routineName,
     };
 }
-/**
- * Map every eligible live session to a `SessionMeta` candidate. Ineligible rows
- * (no id, non-agent kind) are dropped. Order follows the input.
- */
 export function liveSessionMetas(active, self, nowMs) {
     const out = [];
     for (const a of active) {
@@ -82,56 +44,22 @@ export function liveSessionMetas(active, self, nowMs) {
     }
     return out;
 }
-/**
- * Which box the AGENT of each live session executes on, keyed by lowercased id,
- * as recovered from the fleet-active snapshot (`agents sessions --active`'s
- * cross-machine merge). A dispatcher that launched a session running on a peer
- * has a live shim row locally whose `machine` self-defaulted to itself — the
- * launch process IS here, the agent is not (PHNX-3890). The fleet snapshot
- * already reconciled that against the peer's own self-report, so it is the one
- * place that knows the true execution host without a synced index row (which is
- * why `foldExecutionMachine` can't recover it: there is no local index row to
- * join). Only rows the fleet attributes to a real machine are included.
- */
 export function fleetExecutionMachineById(fleet) {
     const byId = new Map();
     for (const s of fleet) {
-        // The AGENT machine is `machine` (where the transcript/harness lives), NOT
-        // `offloadedFrom` (where the launcher shim runs) — reading follows the
-        // transcript owner, so a would-be reader must reach `machine`.
         if (!s.sessionId || !s.machine)
             continue;
         byId.set(s.sessionId.toLowerCase(), s.machine);
     }
     return byId;
 }
-/**
- * Correct a live `SessionMeta` candidate's machine to its true EXECUTION host
- * using the fleet-active attribution (PHNX-3890). Only a **self-attributed,
- * transcript-less** row is a candidate for correction — the launcher-shim shape
- * a dispatcher holds for a session whose agent runs on a peer, which is
- * indistinguishable from a genuinely-local just-started session by its local
- * fields alone. A row already attributed to another box, or one carrying a
- * transcript path, is left untouched. A corrected row is stamped `_remote` so
- * the read-vs-resume router (`transcriptOnPeerOf`) sends the preview to the
- * owning peer instead of dead-ending on the local "not indexed here" stub.
- */
 export function reconcileLiveMetaMachine(metas, fleetExecutionMachine, self) {
     return metas.map(meta => {
-        // Already attributed elsewhere, or locally readable — not a self-default.
         if (meta.machine && meta.machine !== self)
             return meta;
         if (meta.filePath)
             return meta;
         const exec = fleetExecutionMachine.get(meta.id.toLowerCase());
-        // Only a PEER attribution is positive information. A snapshot entry that
-        // names THIS box cannot be trusted as confirmation, because the snapshot is
-        // a merge that INCLUDES this box's own rows — so for exactly the session
-        // shape being corrected here (no index row to fold from), a `self` entry may
-        // be nothing but an echo of the self-default above, recorded while the
-        // owning peer had not reported yet or was unreachable during that gather.
-        // Treating it as proof would skip the fan-out and dead-end on the local stub
-        // for a session genuinely running elsewhere — the PHNX-3890 bug itself.
         if (!exec || exec === self)
             return meta;
         return { ...meta, machine: exec, _remote: true };

package/dist/lib/session/local-tmux-attach.d.ts

@@ -1,18 +1,6 @@
 export type TmuxAliasState = 'not-an-alias' | 'no-server' | 'absent' | 'dead' | 'live';
-/** Shape of the tmux alias the CLI mints for an agent session: `ag-<agent>-<shortid>`.
- * Delegates to the one canonical matcher beside the name parsers in active.ts. */
 export declare function looksLikeTmuxAlias(selector: string): boolean;
-/**
- * Classify a selector against the live tmux server. Split from the attach so the
- * decision is testable against a real tmux server without replacing the caller's
- * shell (attaching is not something a test can undo).
- */
 export declare function resolveTmuxAliasState(selector: string, socket?: string): Promise<TmuxAliasState>;
-/**
- * A local `ag-<agent>-<8hex>` alias names a pane on THIS box. Attach it
- * without any fleet SSH. `--device` keeps the sweep: the caller scoped
- * identity to another machine.
- */
 export declare function shouldAttachLocalTmuxAliasBeforeFleet(selector: string | undefined, hosts: string[]): selector is string;
 type LocalAliasBySuffix = {
     kind: 'alias';
@@ -23,31 +11,6 @@ type LocalAliasBySuffix = {
 } | {
     kind: 'none';
 };
-/**
- * Resolve a bare 8-hex selector (`agents tmux ls`'s hex column, typed without
- * the `ag-<agent>-` prefix) against LIVE local panes only. Dead panes matching
- * the suffix are excluded before the uniqueness check — a retained, exited pane
- * must never compete with (or block) a live one for the same short id.
- *
- * Exported for direct testing: `attachLocalLiveSelector` composes this with a
- * real `attachTmux()` call, which a unit test cannot safely invoke (it takes
- * over the terminal).
- */
 export declare function resolveUniqueLocalLiveAliasBySuffix(shortId: string, socket?: string): Promise<LocalAliasBySuffix>;
-/**
- * The full local gate (PHNX-3292 rule 1): a selector that is either a live
- * local tmux alias, or a bare 8-hex short id that names exactly one live local
- * pane, attaches immediately — zero SSH. `--device`/`hosts` scopes identity to
- * another machine and disables this gate entirely (rule 4).
- *
- * Two LIVE local panes matching the same 8-hex suffix fail closed (rule 5): a
- * collision is reported with both names rather than guessing, and the caller
- * must not fall through to fleet resolution for a selector that is genuinely
- * ambiguous ON THIS BOX.
- *
- * Returns `false` (never attached, never reported) when the selector does not
- * name a live local pane at all, so the caller can continue to session-id
- * resolution / the fleet race.
- */
 export declare function attachLocalLiveSelector(selector: string | undefined, hosts: string[]): Promise<boolean>;
 export {};

package/dist/lib/session/local-tmux-attach.js

@@ -1,33 +1,11 @@
-/**
- * Attach a LIVE tmux pane on THIS box, with zero SSH — the local half of the
- * PHNX-3292 product rule: "first unique match wins, local before fleet."
- *
- * `agents tmux ls` prints `ag-<agent>-<8hex>` names. A selector that already
- * names one of those panes (the full alias, or its bare 8-hex suffix when it
- * is unique among LIVE local panes) is attached directly — no session index
- * lookup, no fleet SSH fan-out. `sessions resume`, the deprecated `sessions
- * attach`, and `sessions focus` all take this gate before anything else.
- *
- * Lives outside `commands/` (not in focus.ts) so `sessions-resume.ts` and
- * `attach.ts` can both import it without a focus.ts <-> sessions-resume.ts
- * import cycle (focus.ts already imports from sessions-resume.ts).
- */
 import fs from 'node:fs';
 import chalk from 'chalk';
 import { attachTmux, ensureSessionHookRepaired, getDefaultSocketPath, hasSession, listSessions, runTmux, teardownIfAgentExited } from '../tmux/index.js';
-import { isAgentTmuxAlias } from './types.js';
-/** Width of `SessionMeta.shortId` / the hex an `ag-<agent>-<8hex>` alias embeds. */
+import { isAgentTmuxAlias } from '@phnx-labs/sessions-cli/reader';
 const SHORT_SESSION_ID_RE = /^[0-9a-f]{8}$/i;
-/** Shape of the tmux alias the CLI mints for an agent session: `ag-<agent>-<shortid>`.
- * Delegates to the one canonical matcher beside the name parsers in active.ts. */
 export function looksLikeTmuxAlias(selector) {
     return isAgentTmuxAlias(selector);
 }
-/**
- * Classify a selector against the live tmux server. Split from the attach so the
- * decision is testable against a real tmux server without replacing the caller's
- * shell (attaching is not something a test can undo).
- */
 export async function resolveTmuxAliasState(selector, socket) {
     if (!looksLikeTmuxAlias(selector))
         return 'not-an-alias';
@@ -43,30 +21,9 @@ export async function resolveTmuxAliasState(selector, socket) {
     const states = (panes?.stdout ?? '').split('\n').map(s => s.trim()).filter(Boolean);
     return states.some(d => d === '0') ? 'live' : 'dead';
 }
-/**
- * A local `ag-<agent>-<8hex>` alias names a pane on THIS box. Attach it
- * without any fleet SSH. `--device` keeps the sweep: the caller scoped
- * identity to another machine.
- */
 export function shouldAttachLocalTmuxAliasBeforeFleet(selector, hosts) {
     return !!selector && hosts.length === 0 && isAgentTmuxAlias(selector);
 }
-/**
- * Attach a live tmux session named exactly as the selector, without needing the
- * session index to know anything about it.
- *
- * SES-41 requires a `ag-<agent>-<8hex>` tmux alias to resolve, but the alias's
- * hex is the LAUNCH id, not the harness session id, and for a harness that
- * writes no `state/sessions/<pid>.json` record there is no mapping back to a
- * SessionMeta at all. The pane is the thing the user asked for, and its NAME is
- * sufficient to attach it — so an unattributable session is still reachable
- * instead of being a dead end that forces raw `tmux -S … attach`.
- *
- * Returns false when this is not an alias, the server/session is absent, or
- * every pane is dead — the caller then continues to normal id resolution.
- * SES-39's "re-read `pane_dead` immediately before attach" is honoured here:
- * liveness is queried at attach time, not read from a roster.
- */
 async function attachLiveTmuxAlias(selector) {
     const socket = getDefaultSocketPath();
     if (await resolveTmuxAliasState(selector, socket) !== 'live')
@@ -77,35 +34,18 @@ async function attachLiveTmuxAlias(selector) {
         process.exitCode = 1;
         return true;
     }
-    // Already inside a tmux client on this socket — which is the normal state for
-    // an interactive agent session here — MOVE that client instead of nesting a
-    // second one. jumpTo (go.ts) does the same; attaching from inside tmux
-    // otherwise stacks clients rather than taking you to the session.
     if (process.env.TMUX) {
         await runTmux({ socket, args: ['switch-client', '-t', `=${selector}`], throwOnError: false }).catch(() => { });
         console.log(chalk.gray(`Switched this tmux client to ${selector}.`));
         return true;
     }
     console.log(chalk.gray(`Attaching ${selector} — Ctrl-b d to detach.`));
-    // Repair a legacy/stale pane-died hook before handing the session to an
-    // attach client — the 5-min daemon reconcile that used to cover this was
-    // deleted; attach-time repair is what closes the gap now (RUSH-2435).
     await ensureSessionHookRepaired(selector, socket);
     const code = await attachTmux({ socket, args: ['attach-session', '-t', `=${selector}`] });
     await teardownIfAgentExited(selector, socket);
     process.exitCode = code;
     return true;
 }
-/**
- * Resolve a bare 8-hex selector (`agents tmux ls`'s hex column, typed without
- * the `ag-<agent>-` prefix) against LIVE local panes only. Dead panes matching
- * the suffix are excluded before the uniqueness check — a retained, exited pane
- * must never compete with (or block) a live one for the same short id.
- *
- * Exported for direct testing: `attachLocalLiveSelector` composes this with a
- * real `attachTmux()` call, which a unit test cannot safely invoke (it takes
- * over the terminal).
- */
 export async function resolveUniqueLocalLiveAliasBySuffix(shortId, socket) {
     const sock = socket ?? getDefaultSocketPath();
     if (!fs.existsSync(sock))
@@ -130,21 +70,6 @@ export async function resolveUniqueLocalLiveAliasBySuffix(shortId, socket) {
         return { kind: 'collision', aliases: live };
     return { kind: 'alias', alias: live[0] };
 }
-/**
- * The full local gate (PHNX-3292 rule 1): a selector that is either a live
- * local tmux alias, or a bare 8-hex short id that names exactly one live local
- * pane, attaches immediately — zero SSH. `--device`/`hosts` scopes identity to
- * another machine and disables this gate entirely (rule 4).
- *
- * Two LIVE local panes matching the same 8-hex suffix fail closed (rule 5): a
- * collision is reported with both names rather than guessing, and the caller
- * must not fall through to fleet resolution for a selector that is genuinely
- * ambiguous ON THIS BOX.
- *
- * Returns `false` (never attached, never reported) when the selector does not
- * name a live local pane at all, so the caller can continue to session-id
- * resolution / the fleet race.
- */
 export async function attachLocalLiveSelector(selector, hosts) {
     if (shouldAttachLocalTmuxAliasBeforeFleet(selector, hosts)) {
         return attachLiveTmuxAlias(selector);

package/dist/lib/session/migrate-targets.d.ts

@@ -1,65 +1,19 @@
-/**
- * Target enumeration + `--auto` scorer for `agents sessions migrate` (RUSH-1977).
- *
- * `sessions migrate` relocates a running session onto another machine. This
- * module is the pure decision layer: given the fleet (enrolled hosts + devices
- * from `listAllHosts()`), their live headroom ({@link Headroom} buckets derived
- * from `probeFleetStats()` / the disk stats-cache), and the reusable ephemeral
- * crabbox boxes (`reusableBoxes()`), it enumerates eligible {@link MigrateTarget}s
- * and ranks them for `--auto`.
- *
- * Kept side-effect-free (no ssh, no disk, no clock) so the ranking is a unit test
- * against synthetic Host[]/DeviceStats — the command layer does the probing and
- * hands the results in. The one genuine-bug guard the test pins: the source and
- * the interactive machine (os.hostname()) are never offered as targets.
- */
 import type { Host } from '../hosts/types.js';
 import type { DeviceStats, Headroom } from '../devices/health.js';
 import type { CrabboxBox } from '../crabbox/cli.js';
-/** A machine the current session could be relocated onto. */
 export interface MigrateTarget {
-    /** The `--device` value: a host/device name, or a warm box slug for ephemeral. */
     name: string;
-    /** Where the target comes from — a fleet host/device, or a warm crabbox box. */
     kind: 'fleet' | 'ephemeral';
-    /** Captured OS string ('darwin'/'linux'/'windows'/…) when known, for platform-match ranking. */
     os?: string;
-    /** Live headroom bucket ('idle' is best); 'unknown' when no stats resolved. */
     headroom: Headroom;
-    /** The underlying host (fleet targets only). */
     host?: Host;
-    /** The underlying warm box (ephemeral targets only). */
     box?: CrabboxBox;
 }
-/** Inputs the scorer needs about the session being moved and this machine. */
 export interface MigrateContext {
-    /** os.hostname() of the interactive machine — never a valid target. */
     selfHostname: string;
-    /** The source session's host (machine it currently runs on) — never a valid target. */
     sourceHostname?: string;
-    /** The source session's OS, for the platform-match bonus. */
     sourceOs?: string;
 }
-/**
- * Enumerate the fleet + ephemeral targets a session could move to, excluding the
- * interactive machine and the source. A fleet host is eligible only when it is
- * dispatchable and not obviously offline; ephemeral (warm) boxes are always
- * eligible (already provisioned and reachable). `statsByName` supplies live
- * headroom — a missing entry yields 'unknown' (still eligible, just ranked lower).
- */
 export declare function enumerateTargets(hosts: Host[], warmBoxes: CrabboxBox[], statsByName: Map<string, DeviceStats>, ctx: MigrateContext): MigrateTarget[];
-/**
- * Rank targets for `--auto`. Order:
- *   1. Platform match with the source (a faithful --resume wants the same OS family).
- *   2. Fleet before ephemeral (prefer a warm worker over spinning a box).
- *   3. Headroom (idle > light > busy > loaded > unknown).
- *   4. Name, for a stable tie-break.
- * Returns a new sorted array; does not mutate the input.
- */
 export declare function rankTargets(targets: MigrateTarget[], ctx: MigrateContext): MigrateTarget[];
-/**
- * Pick the single best `--auto` target, or null when nothing is eligible. A
- * fully-loaded ('loaded') fleet is still returned (better than failing the
- * migrate); the command layer can offer `--lease` when this is null.
- */
 export declare function pickBestTarget(hosts: Host[], warmBoxes: CrabboxBox[], statsByName: Map<string, DeviceStats>, ctx: MigrateContext): MigrateTarget | null;

package/dist/lib/session/migrate-targets.js

@@ -1,5 +1,4 @@
 import { headroom } from '../devices/health.js';
-/** Headroom rank: lower is better (idle preferred). 'unknown' sorts last among reachable. */
 const HEADROOM_ORDER = {
     idle: 0,
     light: 1,
@@ -7,7 +6,6 @@ const HEADROOM_ORDER = {
     loaded: 3,
     unknown: 4,
 };
-/** Normalize an os string to a coarse platform token for match comparison. */
 function platformOf(os) {
     if (!os)
         return undefined;
@@ -20,20 +18,12 @@ function platformOf(os) {
         return 'linux';
     return s;
 }
-/**
- * Enumerate the fleet + ephemeral targets a session could move to, excluding the
- * interactive machine and the source. A fleet host is eligible only when it is
- * dispatchable and not obviously offline; ephemeral (warm) boxes are always
- * eligible (already provisioned and reachable). `statsByName` supplies live
- * headroom — a missing entry yields 'unknown' (still eligible, just ranked lower).
- */
 export function enumerateTargets(hosts, warmBoxes, statsByName, ctx) {
     const excluded = new Set([ctx.selfHostname, ctx.sourceHostname].filter((n) => !!n).map((n) => n.toLowerCase()));
     const fleet = [];
     for (const host of hosts) {
         if (excluded.has(host.name.toLowerCase()))
             continue;
-        // dispatchable is absent-means-yes; only an explicit false is disqualifying.
         if (host.dispatchable === false)
             continue;
         if (host.status === 'offline')
@@ -49,21 +39,12 @@ export function enumerateTargets(hosts, warmBoxes, statsByName, ctx) {
     const ephemeral = warmBoxes.map((box) => ({
         name: box.slug,
         kind: 'ephemeral',
-        // crabbox boxes are Linux; the address is resolved at use time.
         os: 'linux',
         headroom: headroom(statsByName.get(box.slug)),
         box,
     }));
     return [...fleet, ...ephemeral];
 }
-/**
- * Rank targets for `--auto`. Order:
- *   1. Platform match with the source (a faithful --resume wants the same OS family).
- *   2. Fleet before ephemeral (prefer a warm worker over spinning a box).
- *   3. Headroom (idle > light > busy > loaded > unknown).
- *   4. Name, for a stable tie-break.
- * Returns a new sorted array; does not mutate the input.
- */
 export function rankTargets(targets, ctx) {
     const srcPlatform = platformOf(ctx.sourceOs);
     const score = (t) => {
@@ -83,11 +64,6 @@ export function rankTargets(targets, ctx) {
         return sa.name.localeCompare(sb.name);
     });
 }
-/**
- * Pick the single best `--auto` target, or null when nothing is eligible. A
- * fully-loaded ('loaded') fleet is still returned (better than failing the
- * migrate); the command layer can offer `--lease` when this is null.
- */
 export function pickBestTarget(hosts, warmBoxes, statsByName, ctx) {
     const ranked = rankTargets(enumerateTargets(hosts, warmBoxes, statsByName, ctx), ctx);
     return ranked[0] ?? null;

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

@@ -2,7 +2,6 @@ export type MigrationMode = 'resume' | 'rehydrate';
 export interface MigrationEndpoint {
     host: string;
     cwd?: string;
-    /** tmux pane on the source; ephemeral box slug on the target. */
     pane?: string;
     box?: string;
 }
@@ -11,26 +10,15 @@ export interface MigrationRecord {
     shortId: string;
     agent: string;
     mode: MigrationMode;
-    /** true = move (the source was stopped); false = copy (--keep). */
     move: boolean;
     from: MigrationEndpoint;
     to: MigrationEndpoint;
-    /** WIP branch the working tree was committed to before the move, if any. */
     branch?: string;
-    /** Draft PR opened for that branch, if any. */
     wipPr?: string;
-    /** ISO timestamp — passed in by the caller (the CLI has a real clock). */
     at: string;
     status: 'completed' | 'failed';
     error?: string;
 }
-/**
- * Append one migration event. A ledger write must never break a migration that
- * otherwise succeeded, so a write failure is a visible warning, not a throw.
- * `file` is injectable for tests; production uses the default ledger path.
- */
 export declare function recordMigration(rec: MigrationRecord, file?: string): void;
-/** Read the whole ledger, oldest first. Blank/corrupt JSONL lines are skipped. */
 export declare function readMigrations(file?: string): MigrationRecord[];
-/** The most recent completed migration for a session id, or undefined. */
 export declare function latestForSession(sessionId: string, file?: string): MigrationRecord | undefined;

package/dist/lib/session/migrations.js

@@ -1,14 +1,3 @@
-/**
- * Migration ledger (RUSH-1977) — an append-only record of every
- * `agents sessions migrate`, so a session handed off to another machine stays
- * trackable: where it went, when, in which mode, move vs copy, and the WIP
- * branch/PR its working tree was parked on.
- *
- * Append-only JSONL under the already-synced `~/.agents/.history`, so the source
- * and target machines converge on the same trail. One line per event; a session
- * that hops A→B→C leaves three lines — that ordered history IS the lineage, which
- * is why this is an event log, not a mutable field on the session.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
@@ -16,11 +5,6 @@ import { homeDir } from '../platform/paths.js';
 function migrationsLedgerPath() {
     return path.join(homeDir(), '.agents', '.history', 'migrations.jsonl');
 }
-/**
- * Append one migration event. A ledger write must never break a migration that
- * otherwise succeeded, so a write failure is a visible warning, not a throw.
- * `file` is injectable for tests; production uses the default ledger path.
- */
 export function recordMigration(rec, file = migrationsLedgerPath()) {
     try {
         fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -30,14 +14,13 @@ export function recordMigration(rec, file = migrationsLedgerPath()) {
         console.error(chalk.yellow(`  Could not write the migration ledger (${err.message}).`));
     }
 }
-/** Read the whole ledger, oldest first. Blank/corrupt JSONL lines are skipped. */
 export function readMigrations(file = migrationsLedgerPath()) {
     let raw;
     try {
         raw = fs.readFileSync(file, 'utf8');
     }
     catch {
-        return []; // no ledger yet
+        return [];
     }
     const out = [];
     for (const line of raw.split('\n')) {
@@ -48,12 +31,10 @@ export function readMigrations(file = migrationsLedgerPath()) {
             out.push(JSON.parse(s));
         }
         catch {
-            // A single partial line (interrupted append) must not sink the whole read.
         }
     }
     return out;
 }
-/** The most recent completed migration for a session id, or undefined. */
 export function latestForSession(sessionId, file = migrationsLedgerPath()) {
     const recs = readMigrations(file).filter((r) => r.sessionId === sessionId && r.status === 'completed');
     return recs.length ? recs[recs.length - 1] : undefined;

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

@@ -1,30 +1,5 @@
-/**
- * Fleet distribution of lightweight per-session preview/metadata (PHNX-3792).
- *
- * On the interactive/personal device, a session that originated on another host
- * used to render as a bare `[host/<peer>]` row with no topic, and its preview
- * pane fetched the peer's digest LIVE over SSH per row — slow, and blank when
- * the peer is asleep. This module mirrors each box's own session digests into
- * its own `~/.agents/devices/<device>/daemon-state.json`, which the usage-sync
- * SSH exchange (`accounting/usage-sync.ts`, PHNX-4116) carries to every peer:
- * a headed box's tick sends its envelope and stores each peer's reply, so both
- * directions land with no operator step and nothing rides the user repo. The consuming device folds peer
- * digests into its local `sessions` index as mirror rows, so the picker/list/
- * focus read a LOCAL row instead of dialing the peer. No transcript is shipped —
- * only topic/label, the peer's daemon-generated title (PHNX-3797), a
- * first-user-message snippet, last-activity, agent+version, cwd, ticket, and
- * PR — and the mirror is bounded and pruned by age.
- *
- * Direction is deliberately the inverse of usage-sync: EVERY box publishes its
- * own local sessions (workers are exactly where the remote sessions the personal
- * box lacks previews for are created), and every box EXCEPT a marked worker folds
- * peers' digests in (the picker is an interactive surface). A worker skips the
- * consume so its DB is not written with rows it never renders.
- */
 import { type ConfiguredDeviceRole } from '../device-config.js';
-/** Mirror rows older than this since their last sync are pruned (staleness/size ceiling). */
 export declare const SESSION_MIRROR_MAX_AGE_MS: number;
-/** Caps for the timeline block on a published mirror row. */
 export declare const SESSION_MIRROR_MAX_STEPS = 8;
 export declare const SESSION_MIRROR_STEP_TEXT_MAX = 160;
 export declare const SESSION_MIRROR_REQUEST_MAX = 2000;
@@ -42,7 +17,6 @@ interface PublishSessionMirrorResult {
     error: string | null;
     path: string | null;
 }
-/** Publish this device's most-recent local sessions into its owned shared-state file. */
 export declare function publishSessionMirrorToSharedStore(options?: PublishSessionMirrorOptions): Promise<PublishSessionMirrorResult>;
 interface ConsumeSessionMirrorOptions {
     userAgentsDir?: string;
@@ -61,11 +35,5 @@ interface ConsumeSessionMirrorResult {
         message: string;
     }>;
 }
-/**
- * Fold peers' published session digests into this box's local `sessions` index
- * as mirror rows, then prune stale ones. Reads only the local user-repo checkout
- * (the daemon's Git transport already delivered peers' files) — no network. A
- * marked worker skips: the mirror feeds an interactive picker it never renders.
- */
 export declare function consumeSessionMirrorFromSharedStore(options?: ConsumeSessionMirrorOptions): ConsumeSessionMirrorResult;
 export {};