@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/session/hook-sessions.js

@@ -1,32 +1,3 @@
-/**
- * Read-only view of the SessionStart hook's live-session state files.
- *
- * Two on-disk sources carry a non-Claude agent's authoritative id (whose id we
- * can't know at spawn), both read here:
- *   1. The `@agents/session-tracker` hook writes
- *      `~/.agents/.cache/terminals/sessions/<pid>.json` with the id plus the join
- *      keys `launch_id` / `terminal_id`. Rich schema, but this package is NOT
- *      deployed on the fleet — its dir is empty there. Scanned into the index by
- *      {@link loadHookSessionIndex}.
- *   2. The ACTUALLY-DEPLOYED SessionStart hook writes
- *      `~/.agents/.cache/state/sessions/<pid>.json` ({@link readStateSessionRecord})
- *      — `{session_id,cwd,pid,ts}`, keyed purely by pid. This is the real fleet id
- *      source for every agent; read targeted per-pid, never scanned (RUSH-2007).
- * Both see agents `ag run` did NOT launch (you typing `claude` in a terminal).
- *
- * This module lets `sessions --active` reconcile a `ps`-discovered pid to that
- * authoritative id. It is deliberately a small hand-rolled reader — the CLI does
- * NOT import the session-tracker package (a separate, workspace-less package;
- * see packages/session-tracker/CLAUDE.md) — mirroring AGI EXT's own
- * hand-copied reader in apps/ext/src/core/liveSession.ts. It only READS the
- * existing dir/schema. The owning launcher also records a completed launch
- * binding in that schema before returning; readers remain read-only across a
- * fleet where old hooks and a new CLI coexist.
- *
- * The whole state dir is scanned ONCE per active-scan into an index (the listing
- * path polls every ~3s), and every lookup keys the pre-built maps — never a
- * re-scan per candidate.
- */
 import fs from 'fs';
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
@@ -36,33 +7,11 @@ import path from 'path';
 import { getTerminalsDir, getRuntimeStateDir } from '../state.js';
 import { listPidSessionEntries, pidSessionEntryMatchesLiveProcess, readLivePidSessionEntry, readPidSessionEntry } from './pid-registry.js';
 function hookSessionsDir() {
-    // Sibling of the pid-registry's by-pid/ dir. The hook hardcodes this same path
-    // (packages/session-tracker/src/hook.sh); we read it, never move it.
     return path.join(getTerminalsDir(), 'sessions');
 }
-/**
- * The path the ACTUALLY-DEPLOYED SessionStart hook writes:
- * `~/.agents/.cache/state/sessions/<pid>.json`, carrying `{session_id,cwd,pid,ts}`
- * for EVERY agent (claude/codex/gemini/kimi/grok/antigravity). This is the fleet's
- * real id source; the `terminals/sessions/` path above belongs to the separate
- * `@agents/session-tracker` package, which is not deployed (its dir is empty on the
- * fleet), so a non-Claude tmux session's id resolved ONLY through the index above
- * never landed (RUSH-2007). These records are keyed purely by pid — no
- * launch_id/terminal_id/agent — so they join only on pid. The dir is an unpruned
- * graveyard (thousands of dead-pid files), so this is a TARGETED per-pid read on
- * demand, never a full-dir scan folded into {@link loadHookSessionIndex}.
- */
 function stateSessionRecordPath(pid) {
     return path.join(getRuntimeStateDir(), 'sessions', `${pid}.json`);
 }
-/**
- * Read the deployed hook's record for one specific pid, or undefined if absent /
- * corrupt / not fresh. `startedAtMs` (the live process's known start, when the
- * caller has it) rejects a stale record left by a PRIOR process at a reused pid:
- * the hook writes its record AFTER the agent boots, so a record whose `ts`
- * predates the current process's start belongs to a dead predecessor. `ts` is
- * Unix SECONDS (the hook stamps `date +%s`); `startedAtMs` is millis.
- */
 export function readStateSessionRecord(pid, startedAtMs) {
     if (!pid || pid < 1)
         return undefined;
@@ -71,16 +20,14 @@ export function readStateSessionRecord(pid, startedAtMs) {
         rec = parseRecord(fs.readFileSync(stateSessionRecordPath(pid), 'utf8'));
     }
     catch {
-        return undefined; // absent (the common case) or unreadable
+        return undefined;
     }
     if (!rec)
         return undefined;
     if (startedAtMs !== undefined && typeof rec.ts === 'number') {
-        // Allow a small skew: the hook fires just after exec, and ts is second-
-        // granular so it can floor to just before a sub-second process start.
         const SKEW_MS = 5_000;
         if (rec.ts * 1000 < startedAtMs - SKEW_MS)
-            return undefined; // reused-pid graveyard record
+            return undefined;
     }
     return rec;
 }
@@ -92,22 +39,15 @@ function parseRecord(raw) {
         }
     }
     catch {
-        /* unparseable — treat as absent */
     }
     return undefined;
 }
-/** Keep the newest record (by `ts`) when two collide on the same key. Uses the
- *  same strict `>` tie-break as the session-tracker's own reader (reader.ts). */
 function keepNewest(map, key, rec) {
     const prev = map.get(key);
     if (!prev || (rec.ts ?? 0) > (prev.ts ?? 0))
         map.set(key, rec);
 }
 let clockTicks;
-/** Recover an already-running launch after an old reader removed its registry.
- * Enumerate live PIDs, not the hook's unbounded graveyard. Only decode the one
- * allowed environment key; no unrelated environment value escapes this reader.
- * Kernel incarnation and namespace are checked on both sides of the reads. */
 function liveUnregisteredHookRecords() {
     const scope = hostProcessView();
     if (process.platform !== 'linux' || !scope?.pidNamespace)
@@ -159,7 +99,7 @@ function liveUnregisteredHookRecords() {
                     continue;
                 result.push({ ...rec, launch_id: launchId });
             }
-            catch { /* exited, inaccessible, or procfs raced: unknown, never prune */ }
+            catch { }
         }
         return result;
     }
@@ -167,18 +107,12 @@ function liveUnregisteredHookRecords() {
         return [];
     }
 }
-/** Capture ownership while the launched wrapper is alive. The deployed hook
- * walks ancestors to this registry entry and preserves these launcher fields. */
 export function captureLaunchBinding(pid, launchId) {
     if (!pid)
         return undefined;
     const entry = readLivePidSessionEntry(pid);
     return entry?.launchId === launchId ? structuredClone(entry) : undefined;
 }
-/** Completion consumes the hook's launcher-keyed registry update, never a
- * numeric-PID metadata guess. The hook PID can be any descendant of the wrapper.
- * Ownership was measured before exit; matching the unique launch and preserved
- * start timestamp prevents a reused slot from supplying another run's id. */
 export function recordCompletedLaunch(binding) {
     if (!binding?.launchId || !hostProcessView())
         return;
@@ -193,13 +127,8 @@ export function recordCompletedLaunch(binding) {
         const name = createHash('sha256').update(binding.launchId).digest('hex');
         atomicWriteFileSync(path.join(hookSessionsDir(), `launch-${name}.json`), JSON.stringify(rec), 'utf8');
     }
-    catch { /* completion must preserve the child exit status */ }
+    catch { }
 }
-/**
- * Scan the hook state dir once and index every record by launch_id, terminal_id,
- * and pid. Returns empty maps if the dir is absent. Newest-by-`ts` wins a key
- * collision (pid reuse, or a launch id lingering from a since-dead process).
- */
 export function loadHookSessionIndex() {
     const byLaunchId = new Map();
     const byTerminalId = new Map();
@@ -217,7 +146,6 @@ export function loadHookSessionIndex() {
             rec = parseRecord(fs.readFileSync(path.join(hookSessionsDir(), f), 'utf8'));
         }
         catch {
-            /* raced with the hook / pruner — skip */
         }
         if (!rec)
             continue;
@@ -228,9 +156,6 @@ export function loadHookSessionIndex() {
         if (!rec.completed && rec.terminal_id)
             keepNewest(byTerminalId, rec.terminal_id, rec);
     }
-    // Deployed legacy hooks contain only a pid/session id. Join their targeted
-    // records with launch facts instead of requiring a terminal_id they never
-    // wrote. This is read-only: an observer cannot infer host PID liveness.
     for (const entry of listPidSessionEntries()) {
         if (!entry.launchId || pidSessionEntryMatchesLiveProcess(entry) !== true)
             continue;
@@ -254,8 +179,6 @@ export function loadHookSessionIndex() {
         if (!byPid.has(rec.pid))
             byPid.set(rec.pid, rec);
         const previous = recovered.get(rec.launch_id);
-        // Inherited launch metadata cannot disambiguate two different native
-        // sessions. Keep their exact PID identities but refuse the ambiguous join.
         recovered.set(rec.launch_id, previous === null || (previous && previous.session_id !== rec.session_id) ? null : rec);
     }
     for (const [launchId, rec] of recovered) {
@@ -264,28 +187,12 @@ export function loadHookSessionIndex() {
     }
     return { byLaunchId, byTerminalId, byPid };
 }
-/**
- * True if a hook record's `agent` is compatible with a `ps`-detected kind. Guards
- * the weak pid/children lookups against a STALE file at a reused pid (a dead
- * hooked agent's `<pid>.json` inherited by a live hookless agent at the same pid).
- * Permissive when the record's agent is absent/legacy-`unknown` (never reject on
- * missing metadata). Normalizes the one known naming gap: `ps` reports Cursor as
- * `cursor-agent`, the hook records it as `cursor`.
- */
 function kindMatches(recordAgent, kind) {
     if (!recordAgent || recordAgent === 'unknown')
         return true;
     const norm = (k) => (k === 'cursor-agent' ? 'cursor' : k);
     return norm(recordAgent) === norm(kind);
 }
-/**
- * Resolve an agent's OWN authoritative session id from the hook index. Priority
- * mirrors the session-tracker's getLiveSession: launchId join (survives pid
- * divergence — the hook runs under the agent pid, our registry entry may sit on a
- * tmux pane leaf or cmd.exe wrapper) → terminalId join → direct pid → children.
- * Every hit is kind-guarded so a stale file at a reused pid can't cross agents.
- * Undefined until the hook lands (it can lag the spawn) or for hookless harnesses.
- */
 export function resolveHookSessionRecord(index, opts) {
     const { pid, kind, launchId, terminalId, childPids } = opts;
     const take = (rec) => rec?.session_id && kindMatches(rec.agent, kind)
@@ -310,8 +217,6 @@ export function resolveHookSessionRecord(index, opts) {
     }
     return undefined;
 }
-/** The session id alone — see {@link resolveHookSessionRecord} for the full record
- *  (which also carries the SessionStart `ts` used to stamp `startedAtMs`). */
 export function resolveHookSessionId(index, opts) {
     return resolveHookSessionRecord(index, opts)?.session_id;
 }

package/dist/lib/session/host-link.d.ts

@@ -1,105 +1,12 @@
-/**
- * Host link — whether anything is still on the other end of a live session.
- *
- * Every liveness signal the scan already has answers "is the AGENT process
- * alive". None of them answer "is anyone still driving it", and those come apart
- * in exactly the two ways a user notices:
- *
- *   - **The host program died and took the agent with it.** VS Code / the editor
- *     window crashes or the SSH connection drops, so the agent process dies with
- *     its parent, but the window never got to run its teardown — its slice of
- *     `live-terminals.json` is left behind, stale, still naming a dead pid. Today
- *     that entry is filtered out at read time, so the session simply VANISHES
- *     from `--active` instead of reporting that it fell over. That is `host-gone`.
- *
- *   - **The host program died and the agent survived it.** The agent was hosted
- *     in tmux (or otherwise reparented), so it keeps running with zero clients
- *     attached: still burning tokens, or sitting on a question nobody will ever
- *     answer, with no window anywhere showing it. That is `no-client`.
- *
- * Both are DERIVED, never asserted — from the agent pid, the owning window's
- * keepalive, and tmux's own attached-client count. A deliberately backgrounded
- * session (`agents sessions detach`) is excluded by construction: it is supposed
- * to have no client, so calling it orphaned would be a false alarm on the one
- * case the user asked for.
- */
-/** How a session is connected to the client that should be driving it. */
-export type HostLink = 
-/** A client is attached — positively established, not assumed. */
-'connected'
-/** Alive, but nothing is viewing it — the host window is gone and the agent outlived it. */
- | 'no-client'
-/** The host window is gone AND the agent process died with it — an unclean exit. */
- | 'host-gone'
-/**
- * Alive, and we have NO usable signal either way — no window owns it and it is
- * not tmux-hosted, so neither input this function keys on exists.
- *
- * This case used to return `connected`, which reads as "verified fine" when the
- * truth is "nobody looked". That is the wrong default for a detector: the rows
- * it silently blesses are precisely the ones with no observer — a bare terminal,
- * a team spawn, a cloud task, or any session whose pane lives on another
- * machine (this function's inputs are all local, so a `--device` session is
- * structurally unobservable from the launching box).
- *
- * Callers MUST NOT render this as healthy. It means the question is open.
- */
- | 'unknown';
-/**
- * How long an IDE window's registry slice may go without a refresh before we
- * treat that window as gone. AGI EXT force-republishes its slice
- * every 4 minutes (`KEEPALIVE_FORCE_MS` in `apps/ext/src/vscode/foreman.registry.ts`)
- * and on every terminal open/close, so a slice this old means the window is no
- * longer running — it is not merely quiet. Deliberately the same 10 minutes the
- * extension itself uses to garbage-collect a peer window's slice, so the CLI and
- * the extension agree on when a window is dead.
- */
+export type HostLink = 'connected' | 'no-client' | 'host-gone' | 'unknown';
 export declare const HOST_HEARTBEAT_STALE_MS: number;
 interface HostLinkInput {
-    /** The agent process is still alive (already pid-reuse-checked by the caller). */
     pidAlive: boolean;
-    /**
-     * When the owning IDE window last refreshed its slice of the live-terminals
-     * registry. Absent for a session no IDE window owns (a bare terminal, a team
-     * spawn, a cloud task) — those have no window whose death we could observe.
-     */
     windowHeartbeatMs?: number;
-    /**
-     * Clients attached to this session's tmux session (`#{session_attached}`).
-     * Absent when the session is not tmux-hosted, which is NOT the same as zero:
-     * zero is a positive "nobody is looking", absent is "we cannot tell".
-     */
     tmuxClients?: number;
-    /** The session was deliberately backgrounded — `presence` is `background`/`parked`. */
     deliberatelyDetached?: boolean;
     nowMs?: number;
 }
-/**
- * Classify a live row's host link. Pure — every signal is passed in, so the
- * whole decision table is unit-testable without a process table, a tmux server,
- * or a running editor.
- */
 export declare function classifyHostLink(input: HostLinkInput): HostLink;
-/**
- * Did the owning IDE window die while the agent kept RUNNING? This is the ONE
- * host-link loss that promotes a still-`running` session to `orphaned`
- * (PHNX-3183): a window that WAS republishing its heartbeat every 4 min went
- * stale for {@link HOST_HEARTBEAT_STALE_MS}, so it died uncleanly (a crash,
- * reboot, or dropped SSH) and the agent it hosted outlived it — genuinely
- * stranded, the "my remote agent is still alive after the laptop rebooted" case.
- *
- * Deliberately NARROWER than `no-client`. A tmux attached-client count of zero
- * is also `no-client`, but for a detached remote pane (`agents run --device`,
- * which RUSH-3125 wraps in a detached tmux session) that is the NORMAL steady
- * state between check-ins — launch, detach, return with `agents focus` — not a
- * loss. Promoting on it would relabel every unattended remote agent as
- * `orphaned`, the over-reporting that makes the word worthless. Only a lost
- * WINDOW is a positive "a client was expected and is now gone" for a running
- * agent; mere absence is not.
- *
- * A deliberately-backgrounded session is excluded exactly as
- * {@link classifyHostLink} excludes it: no client is the point of detaching.
- * Pure — same injected signals as the classifier.
- */
 export declare function hostWindowLost(input: HostLinkInput): boolean;
 export {};

package/dist/lib/session/host-link.js

@@ -1,104 +1,24 @@
-/**
- * Host link — whether anything is still on the other end of a live session.
- *
- * Every liveness signal the scan already has answers "is the AGENT process
- * alive". None of them answer "is anyone still driving it", and those come apart
- * in exactly the two ways a user notices:
- *
- *   - **The host program died and took the agent with it.** VS Code / the editor
- *     window crashes or the SSH connection drops, so the agent process dies with
- *     its parent, but the window never got to run its teardown — its slice of
- *     `live-terminals.json` is left behind, stale, still naming a dead pid. Today
- *     that entry is filtered out at read time, so the session simply VANISHES
- *     from `--active` instead of reporting that it fell over. That is `host-gone`.
- *
- *   - **The host program died and the agent survived it.** The agent was hosted
- *     in tmux (or otherwise reparented), so it keeps running with zero clients
- *     attached: still burning tokens, or sitting on a question nobody will ever
- *     answer, with no window anywhere showing it. That is `no-client`.
- *
- * Both are DERIVED, never asserted — from the agent pid, the owning window's
- * keepalive, and tmux's own attached-client count. A deliberately backgrounded
- * session (`agents sessions detach`) is excluded by construction: it is supposed
- * to have no client, so calling it orphaned would be a false alarm on the one
- * case the user asked for.
- */
-/**
- * How long an IDE window's registry slice may go without a refresh before we
- * treat that window as gone. AGI EXT force-republishes its slice
- * every 4 minutes (`KEEPALIVE_FORCE_MS` in `apps/ext/src/vscode/foreman.registry.ts`)
- * and on every terminal open/close, so a slice this old means the window is no
- * longer running — it is not merely quiet. Deliberately the same 10 minutes the
- * extension itself uses to garbage-collect a peer window's slice, so the CLI and
- * the extension agree on when a window is dead.
- */
 export const HOST_HEARTBEAT_STALE_MS = 10 * 60_000;
-/**
- * Did the session's owning IDE window stop republishing its registry slice? A
- * window republishes every 4 minutes (`HOST_HEARTBEAT_STALE_MS` is 10), so a
- * slice this old means the window is gone, not merely quiet. Shared by
- * {@link classifyHostLink} and {@link hostWindowLost} so the staleness rule has
- * exactly one definition.
- */
 function windowGone(input) {
     const now = input.nowMs ?? Date.now();
     return input.windowHeartbeatMs !== undefined && now - input.windowHeartbeatMs >= HOST_HEARTBEAT_STALE_MS;
 }
-/**
- * Classify a live row's host link. Pure — every signal is passed in, so the
- * whole decision table is unit-testable without a process table, a tmux server,
- * or a running editor.
- */
 export function classifyHostLink(input) {
-    // A session detached on purpose has no client BY DESIGN. It is the one case
-    // that looks identical to an orphan from the outside, so it is excluded first —
-    // otherwise every `agents sessions detach` would raise a false alarm.
     if (input.deliberatelyDetached)
         return 'connected';
     const stale = windowGone(input);
-    // The host window stopped keeping its registry slice alive AND the agent it
-    // owned is dead: the pair went down together without teardown.
     if (stale && !input.pidAlive)
         return 'host-gone';
     if (!input.pidAlive)
-        return 'connected'; // a plain dead pid is `closed`, not an orphan
-    // Alive with tmux reporting zero attached clients: nobody is watching it. This
-    // is the authoritative signal — tmux knows exactly how many clients it has.
+        return 'connected';
     if (input.tmuxClients === 0)
         return 'no-client';
-    // Alive, not tmux-hosted (or tmux says someone is attached), but the window
-    // that owned it is gone. The agent outlived its editor.
     if (stale)
         return 'no-client';
-    // Positive evidence of a client: tmux counted at least one attached client, or
-    // a window is refreshing its registry slice. Either is a real observation.
     if (input.tmuxClients !== undefined || input.windowHeartbeatMs !== undefined)
         return 'connected';
-    // Neither input exists, so nothing here observed anything. Say so rather than
-    // reporting the healthy answer by default — see {@link HostLink}'s `unknown`.
     return 'unknown';
 }
-/**
- * Did the owning IDE window die while the agent kept RUNNING? This is the ONE
- * host-link loss that promotes a still-`running` session to `orphaned`
- * (PHNX-3183): a window that WAS republishing its heartbeat every 4 min went
- * stale for {@link HOST_HEARTBEAT_STALE_MS}, so it died uncleanly (a crash,
- * reboot, or dropped SSH) and the agent it hosted outlived it — genuinely
- * stranded, the "my remote agent is still alive after the laptop rebooted" case.
- *
- * Deliberately NARROWER than `no-client`. A tmux attached-client count of zero
- * is also `no-client`, but for a detached remote pane (`agents run --device`,
- * which RUSH-3125 wraps in a detached tmux session) that is the NORMAL steady
- * state between check-ins — launch, detach, return with `agents focus` — not a
- * loss. Promoting on it would relabel every unattended remote agent as
- * `orphaned`, the over-reporting that makes the word worthless. Only a lost
- * WINDOW is a positive "a client was expected and is now gone" for a running
- * agent; mere absence is not.
- *
- * A deliberately-backgrounded session is excluded exactly as
- * {@link classifyHostLink} excludes it: no client is the point of detaching.
- * Pure — same injected signals as the classifier.
- */
 export function hostWindowLost(input) {
     if (input.deliberatelyDetached)
         return false;

package/dist/lib/session/inject-target.d.ts

@@ -0,0 +1,8 @@
+import { type ActiveSession } from './active.js';
+import { type InjectTarget } from '../terminal/index.js';
+export declare function matchInjectSelector(session: ActiveSession, token: string): boolean;
+export declare function resolveLiveInjectTarget(selector: string): Promise<{
+    target: InjectTarget | null;
+    reason?: string;
+    hint?: string;
+}>;

package/dist/lib/session/inject-target.js

@@ -0,0 +1,32 @@
+import { getActiveSessions, shortIdFromName } from './active.js';
+import { resolveInjectTargetForSession } from '../terminal/index.js';
+export function matchInjectSelector(session, token) {
+    if (!token)
+        return false;
+    const sid = session.sessionId;
+    if (sid && (sid === token || sid.startsWith(token)))
+        return true;
+    const short = session.tmuxName ? shortIdFromName(session.tmuxName) : undefined;
+    if (short && (short === token || short.startsWith(token)))
+        return true;
+    if (session.tmuxName && session.tmuxName === token)
+        return true;
+    if (session.paneId && session.paneId === token)
+        return true;
+    return false;
+}
+export async function resolveLiveInjectTarget(selector) {
+    const sessions = await getActiveSessions();
+    const match = sessions.find((s) => matchInjectSelector(s, selector));
+    if (!match)
+        return { target: null, reason: `No active session matches "${selector}".` };
+    const resolution = resolveInjectTargetForSession(match);
+    if (!resolution.addressable) {
+        return {
+            target: null,
+            reason: `Session "${selector}": ${resolution.reason}`,
+            hint: resolution.hint,
+        };
+    }
+    return { target: resolution.target };
+}

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

@@ -1,18 +1,3 @@
-/**
- * Session → Terminal-Engine injection adapter.
- *
- * The Terminal Engine owns the injection primitive (`injectIntoTerminal`,
- * src/lib/terminal/inject.ts). This thin adapter maps a session's provenance
- * `ReplyRail` (the addressable terminal the feed already derives — provenance.ts:47)
- * to the engine's `InjectTarget`, so a caller can go session → keystrokes in one
- * hop. Kept on the session side because `ReplyRail` is a session concept; the
- * engine stays agnostic of how a target was discovered.
- */
 import type { ReplyRail } from './provenance.js';
 import type { InjectTarget } from '../terminal/index.js';
-/**
- * Map a session's `ReplyRail` to an engine `InjectTarget`. Today only tmux rails
- * are externally addressable (provenance.ts:143-149); a null rail yields null and
- * the caller must supply a target another way (a macOS window).
- */
 export declare function injectTargetFromReplyRail(rail: ReplyRail): InjectTarget | null;

package/dist/lib/session/inject.js

@@ -1,18 +1,3 @@
-/**
- * Session → Terminal-Engine injection adapter.
- *
- * The Terminal Engine owns the injection primitive (`injectIntoTerminal`,
- * src/lib/terminal/inject.ts). This thin adapter maps a session's provenance
- * `ReplyRail` (the addressable terminal the feed already derives — provenance.ts:47)
- * to the engine's `InjectTarget`, so a caller can go session → keystrokes in one
- * hop. Kept on the session side because `ReplyRail` is a session concept; the
- * engine stays agnostic of how a target was discovered.
- */
-/**
- * Map a session's `ReplyRail` to an engine `InjectTarget`. Today only tmux rails
- * are externally addressable (provenance.ts:143-149); a null rail yields null and
- * the caller must supply a target another way (a macOS window).
- */
 export function injectTargetFromReplyRail(rail) {
     if (rail && rail.rail === 'tmux') {
         return { backend: 'tmux', pane: rail.target, socket: rail.socket };

package/dist/lib/session/live-metadata.d.ts

@@ -1,39 +1,6 @@
-import { type SessionMeta } from './types.js';
+import { type SessionMeta } from '@phnx-labs/sessions-cli/reader';
 import type { ActiveSession } from './active.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.
- */
 export declare function activeSessionToSessionMeta(active: ActiveSession, self: string, nowMs: number): SessionMeta | null;
-/**
- * Map every eligible live session to a `SessionMeta` candidate. Ineligible rows
- * (no id, non-agent kind) are dropped. Order follows the input.
- */
 export declare function liveSessionMetas(active: ActiveSession[], self: string, nowMs: number): SessionMeta[];
-/**
- * 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 declare function fleetExecutionMachineById(fleet: ActiveSession[]): Map<string, string>;
-/**
- * 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 declare function reconcileLiveMetaMachine(metas: SessionMeta[], fleetExecutionMachine: Map<string, string>, self: string): SessionMeta[];