@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/session/tool-index.js

@@ -1,8 +1,8 @@
 import * as fs from 'fs';
 import { StringDecoder } from 'string_decoder';
 import { getDB, maintainSessionSearchIndex } from './db.js';
-import { parseSession } from './parse.js';
-import { TOOL_INDEX_VERSION, TOOL_INDEX_LIMIT_ORDINAL, ToolCallCollector, collectClaudeToolCalls, collectCodexToolCalls, toolCallEvidenceBytes, toolCallsFromEvents, } from './tool-calls.js';
+import { parseSession } from '@phnx-labs/sessions-cli/reader';
+import { TOOL_INDEX_VERSION, TOOL_INDEX_LIMIT_ORDINAL, ToolCallCollector, collectClaudeToolCalls, collectCodexToolCalls, toolCallEvidenceBytes, toolCallsFromEvents, } from '@phnx-labs/sessions-cli/reader';
 import { canonicalToolLedgerPath, persistToolCalls, purgeToolCalls, toolEvidenceSourcePath, } from './tool-store.js';
 const BACKFILL_MAX_FILES = 25;
 const BACKFILL_MAX_BYTES = 16 * 1024 * 1024;
@@ -18,7 +18,6 @@ const TOOL_QUERY_MAX_RESULT_BYTES = 8 * 1024 * 1024;
 export const TOOL_QUERY_MAX_RESULT_SESSIONS = 1_000;
 export const TOOL_QUERY_MAX_SERIALIZED_BYTES = 15 * 1024 * 1024;
 export const TOOL_QUERY_MERGE_OVERHEAD_BYTES = 64 * 1024;
-/** Serialize once and enforce headroom below the fleet transport's 16 MiB cap. */
 export function serializeToolSearchEnvelope(envelope) {
     const rendered = JSON.stringify(envelope, null, 2) + '\n';
     if (Buffer.byteLength(rendered) > TOOL_QUERY_MAX_SERIALIZED_BYTES) {
@@ -26,25 +25,13 @@ export function serializeToolSearchEnvelope(envelope) {
     }
     return rendered;
 }
-/** Exact UTF-8 size of the public pretty-JSON envelope. */
 export function serializedToolSearchEnvelopeBytes(envelope) {
     return Buffer.byteLength(JSON.stringify(envelope, null, 2) + '\n');
 }
-/**
- * Reserve the exact local JSON plus coordinator headroom before retaining peer
- * stdout. Peer envelopes repeat metadata that disappears during merge, so
- * charging their full wire bytes against the remainder is conservative.
- */
 export function toolSearchRemoteReceiveBudget(envelope) {
     const localBytes = serializedToolSearchEnvelopeBytes(envelope);
     return Math.max(0, TOOL_QUERY_MAX_SERIALIZED_BYTES - TOOL_QUERY_MERGE_OVERHEAD_BYTES - localBytes);
 }
-/**
- * The ledger columns every candidate session is judged on. Deliberately NOT
- * `parser_state`: this runs once per session in the scan's warm path, and that
- * column holds a serialized collector snapshot that can reach a megabyte. It is
- * read separately, only for the sessions that turn out to need indexing.
- */
 function readToolLedger(db, sessionId) {
     return db.prepare(`
     SELECT file_path, file_mtime_ms, file_size, extractor_version, parsed_offset
@@ -62,22 +49,6 @@ function needsIndex(row, stamp) {
         || row.file_size !== stamp.fileSize
         || row.extractor_version !== TOOL_INDEX_VERSION;
 }
-/**
- * Where to start reading a session whose transcript changed.
- *
- * A live session's transcript is append-only, so re-reading it from byte 0 on
- * every scan re-parses the entire history to discover the handful of records
- * that are new — the cost that makes a large session's tool index quadratic in
- * the number of scans. When the ledger carries a resume point that the current
- * file still agrees with, the scan reads only the appended bytes and merges the
- * result (`append`); anything else re-reads the whole file (`replace`).
- *
- * Each check below rejects a case where the stored prefix may no longer describe
- * the file: a harness the streaming parser cannot resume, a different extractor,
- * no recorded resume point, a source path the ledger row does not describe, a
- * file that shrank below what was already parsed (a rewrite or truncation, not
- * an append), or a snapshot that does not read back.
- */
 function planToolScan(db, sessionId, row, sourcePath, stamp, resumable) {
     const full = { mode: 'replace', startOffset: 0 };
     if (!resumable || !row)
@@ -104,7 +75,6 @@ function planToolScan(db, sessionId, row, sourcePath, stamp, resumable) {
         return full;
     return { mode: 'append', startOffset: row.parsed_offset, snapshot };
 }
-/** Read index completeness from SQLite only; never stat or parse transcripts. */
 export function readToolIndexCoverage(sessions) {
     const db = getDB();
     const sessionIds = [...new Set(sessions
@@ -144,7 +114,6 @@ function backfillLimitCall(session, reason) {
         parseError: 'Additional tool calls were not indexed for this session.',
     };
 }
-/** Stream Claude/Codex JSONL without ever retaining an oversized record. */
 async function streamJsonlToolCalls(session, from = { startOffset: 0 }) {
     const collector = new ToolCallCollector(from.snapshot);
     const stream = fs.createReadStream(session.filePath, {
@@ -156,11 +125,7 @@ async function streamJsonlToolCalls(session, from = { startOffset: 0 }) {
     let pendingBytes = 0;
     let droppingOversizedLine = false;
     let skippedOversizedLine = false;
-    // Byte offset just past the last complete record applied. Only a complete,
-    // newline-terminated record advances it, so resuming here can never re-apply a
-    // record (which would mint a second ordinal for it) nor skip a partial tail.
     let parsedOffset = from.startOffset;
-    /** Bytes of the record currently being assembled, across chunk boundaries. */
     let lineBytes = 0;
     const applyLine = (line) => {
         if (!line.trim())
@@ -184,11 +149,6 @@ async function streamJsonlToolCalls(session, from = { startOffset: 0 }) {
             const end = newline >= 0 ? newline : text.length;
             const segment = text.slice(start, end);
             const segmentBytes = Buffer.byteLength(segment);
-            // Counted outside the drop guard and across chunk boundaries: this is the
-            // record's true size on disk, which is what the resume offset is measured
-            // in. `pendingBytes` cannot stand in for it — that one resets when an
-            // oversized record is dropped, and a record split over two 64 KiB reads
-            // would lose the part carried in from the previous chunk.
             lineBytes += segmentBytes;
             if (!droppingOversizedLine) {
                 if (pendingBytes + segmentBytes <= BACKFILL_MAX_JSONL_RECORD_BYTES) {
@@ -206,7 +166,7 @@ async function streamJsonlToolCalls(session, from = { startOffset: 0 }) {
                 break;
             if (!droppingOversizedLine)
                 applyLine(pending);
-            parsedOffset += lineBytes + 1; // + the newline itself
+            parsedOffset += lineBytes + 1;
             lineBytes = 0;
             pending = '';
             pendingBytes = 0;
@@ -217,14 +177,7 @@ async function streamJsonlToolCalls(session, from = { startOffset: 0 }) {
     for await (const chunk of stream)
         consume(decoder.write(chunk));
     consume(decoder.end());
-    // Snapshot BEFORE the unterminated trailing record, and pair it with an offset
-    // that stops short of that record. The writer may be mid-append, so the record
-    // is indexed now (its evidence is real) but is re-read by the next scan — which
-    // resumes with the same next-ordinal and so re-derives the same ordinals,
-    // making the re-read an idempotent upsert rather than a duplicate.
     const resume = skippedOversizedLine
-        // A dropped oversized record left the ordinals and the pending map out of
-        // step with the file; nothing here can be resumed from.
         ? null
         : { parserState: JSON.stringify(collector.snapshot()), parsedOffset };
     if (!droppingOversizedLine && pending.length > 0)
@@ -235,7 +188,6 @@ async function streamJsonlToolCalls(session, from = { startOffset: 0 }) {
     }
     return { calls, resume };
 }
-/** True for the harnesses whose transcript the streaming parser can resume. */
 function isResumableToolSource(agent) {
     return agent === 'claude' || agent === 'codex';
 }
@@ -255,15 +207,8 @@ async function toolCallsForBackfill(session, sourceBytes, from = { startOffset:
             resume: null,
         };
     }
-    // Every other harness is parsed whole into memory by parseSession, which
-    // exposes no byte offset to resume from — so these stay full replaces and
-    // record no resume point, rather than storing one this path cannot honour.
     return { calls: toolCallsFromEvents(parseSession(session.filePath, session.agent)), resume: null };
 }
-/**
- * Fill one bounded chunk of the independent tool index. A warm call performs
- * only stat + ledger checks; it never opens or parses unchanged transcripts.
- */
 export async function ensureToolIndex(sessions, limits = {}) {
     const maxFiles = limits.maxFiles ?? BACKFILL_MAX_FILES;
     const maxBytes = limits.maxBytes ?? BACKFILL_MAX_BYTES;
@@ -312,12 +257,6 @@ export async function ensureToolIndex(sessions, limits = {}) {
     for (const item of pending) {
         if (attemptedFiles >= maxFiles)
             break;
-        // The byte budget is a batch boundary, not a correctness boundary. Admit
-        // one oversized transcript by itself so it can never wedge the ledger or
-        // silently disappear from results; the next invocation resumes afterward.
-        // Budgeted on the bytes this scan reads, not the file's size: a resumed
-        // session costs only its appended tail, so a batch can cover far more
-        // growing sessions than it could when every one was re-read whole.
         if (attemptedFiles > 0 && consumedBytes + item.readBytes > maxBytes)
             break;
         attemptedFiles++;
@@ -332,9 +271,6 @@ export async function ensureToolIndex(sessions, limits = {}) {
             skippedFiles++;
         }
     }
-    // The scan just wrote a batch of FTS segments; pay a bounded slice of the
-    // merge they need so the index converges here instead of degrading until
-    // someone runs `agents sessions optimize` by hand (RUSH-2208).
     if (indexedFiles > 0)
         maintainSessionSearchIndex(db);
     const remainingFiles = Math.max(0, pending.length - attemptedFiles);
@@ -399,7 +335,6 @@ function tokenizeClause(source) {
         tokens.push(token);
     return tokens;
 }
-/** Parse one same-call clause. Unprefixed terms search every evidence field. */
 function parseToolQueryClause(source) {
     const fields = new Set(['tool', 'program', 'input', 'output', 'status', 'exit', 'error']);
     return tokenizeClause(source).map((token) => {
@@ -413,7 +348,6 @@ function parseToolQueryClause(source) {
         return { value: token };
     }).filter((term) => term.value.length > 0);
 }
-/** A count has one unambiguous subject: one exact `program:<name>` term. */
 export function parseToolProgramCountClause(source) {
     const terms = parseToolQueryClause(source);
     if (terms.length !== 1 || terms[0].field !== 'program') {
@@ -430,9 +364,6 @@ function matchesTerm(call, term) {
         case 'tool': return includes(call.tool, value);
         case 'program': return call.programs.some((program) => program.toLocaleLowerCase() === value);
         case 'input': return includes(call.input, value);
-        // A harness can mark the returned bytes as an error while they are still
-        // the command's output. Keep `error:` available for explicit diagnostics,
-        // but let `output:` match either bounded result channel.
         case 'output': return includes(call.output, value) || includes(call.error, value);
         case 'status': return call.outcome === value || String(call.statusCode ?? '') === value;
         case 'exit': return String(call.exitCode ?? '') === value;
@@ -493,7 +424,6 @@ function ftsCandidateRows(db, sessionIds, expression) {
     LIMIT ?
   `).all(JSON.stringify(sessionIds), expression, TOOL_QUERY_MAX_CALL_ROWS + 1);
 }
-/** Use indexed typed columns and trigram FTS; final matching remains exact in JS. */
 function candidateKeysForClause(db, sessionIds, clause) {
     let candidates;
     const scope = JSON.stringify(sessionIds);
@@ -720,7 +650,6 @@ function readCallsByKeys(db, keys) {
     loadedBytes = appendStoredRows(out, rows, programsForRows(db, rows), occurrencesForRows(db, rows), loadedBytes);
     return out;
 }
-/** Count exact, pre-indexed static program sites without reading transcripts. */
 export function countToolProgramOccurrences(sessions, program, coverage, machine) {
     const normalized = program.trim();
     if (!normalized || Buffer.byteLength(normalized) > 512) {
@@ -814,7 +743,6 @@ export function countToolProgramOccurrences(sessions, program, coverage, machine
         machines,
     };
 }
-/** Query cached evidence; every repeated clause must select a distinct call. */
 export function searchToolCalls(sessions, clauseSources, coverage, resultLimit = sessions.length) {
     if (!Number.isSafeInteger(resultLimit) || resultLimit < 1 || resultLimit > TOOL_QUERY_MAX_RESULT_SESSIONS) {
         throw new Error(`Tool search --limit must be from 1 to ${TOOL_QUERY_MAX_RESULT_SESSIONS}.`);

package/dist/lib/session/tool-store.d.ts

@@ -1,69 +1,23 @@
 import type Database from '../sqlite.js';
-import { type IndexedToolCall, type EventToolScanResumePoint } from './tool-calls.js';
-import type { SessionMeta } from './types.js';
+import { type IndexedToolCall, type EventToolScanResumePoint } from '@phnx-labs/sessions-cli/reader';
+import type { SessionMeta } from '@phnx-labs/sessions-cli/reader';
 export declare function canonicalToolLedgerPath(filePath: string): string;
-/** Resolve the transcript that actually carries tool events for split-file harnesses. */
 export declare function toolEvidenceSourcePath(filePath: string, agent: string): string;
-/** Remove cached tool evidence when its source transcript no longer exists. */
 export declare function purgeToolCalls(db: Database.Database, sessionId: string): void;
-/** Purge deleted direct children when a transcript directory's stamp changes. */
 export declare function purgeMissingToolCallsInDirectory(db: Database.Database, dirPath: string, currentFilePaths: string[]): number;
-/** The resume point a later incremental scan starts from. */
 export interface ToolScanResumePoint {
-    /** Serialized ToolCallCollector snapshot at `parsedOffset`. */
     parserState: string;
-    /**
-     * Where a later scan may resume. For the streaming (claude/codex) path this is
-     * a BYTE offset just past the last complete record consumed. For the full-file
-     * harness path (`planEventToolResume`) it is instead the COUNT of normalized
-     * events already folded — the two never share a session (a session is one
-     * agent, and the streaming path is claude/codex only), so the column carries
-     * whichever meaning that agent's resumer wrote.
-     */
     parsedOffset: number;
 }
 interface PersistToolCallsOptions {
-    /**
-     * `replace` drops the session's stored evidence first — correct for a parse
-     * that started at byte 0. `append` merges the batch into what is already
-     * stored and requires an existing ledger row; use it only for a parse that
-     * resumed from that row's `parsedOffset`.
-     */
     mode?: 'replace' | 'append';
-    /**
-     * Where a later scan may resume. Omitted (or null) clears any stored resume
-     * point, which forces the next scan of this session to re-read from byte 0 —
-     * the correct outcome whenever the parse could not cover the whole prefix
-     * (an oversized record, a size-capped transcript, a non-streaming harness).
-     */
     resume?: ToolScanResumePoint | null;
     maxSessionBytes?: number;
 }
-/** Persist one parser batch, its file stamp, and its resume point atomically. */
 export declare function persistToolCalls(db: Database.Database, session: SessionMeta, calls: IndexedToolCall[], sourceStamp: {
     fileMtimeMs: number;
     fileSize: number;
 }, options?: PersistToolCallsOptions): void;
-/**
- * Decide whether a changed full-file-harness session can RESUME its tool index
- * from the last scan instead of re-deriving every call (PHNX-3411).
- *
- * The warm-tick indexer re-derives tool calls for a changed session on every
- * tick, and for an ACTIVE large session that means re-sanitizing tens of
- * thousands of calls each time — the synchronous work that wedged the daemon
- * event loop. Streaming harnesses (claude/codex) already resume from a byte
- * offset; every other harness re-parses the whole file, so this brings them the
- * same benefit at the EVENT level: the ledger stores how many events were folded
- * (`parsed_offset`) plus the collector snapshot (`parser_state`), and a later
- * scan folds only the newly appended events.
- *
- * Returns the prior resume point when it is safe to append, or `null` (full
- * re-scan) whenever the stored prefix may no longer describe the current file:
- * a different extractor, no recorded resume point, a source the ledger row does
- * not describe, a transcript that shrank below what was already parsed (a
- * truncation/rewrite, not an append), more events already folded than the file
- * now yields, or a snapshot that does not read back.
- */
 export declare function planEventToolResume(db: Database.Database, sessionId: string, sourcePath: string, stamp: {
     fileMtimeMs: number;
     fileSize: number;

package/dist/lib/session/tool-store.js

@@ -1,6 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { TOOL_INDEX_VERSION, TOOL_INDEX_LIMIT_ORDINAL, TOOL_SESSION_EVIDENCE_MAX_BYTES, toolCallEvidenceBytes, toolCallKey, } from './tool-calls.js';
+import { TOOL_INDEX_VERSION, TOOL_INDEX_LIMIT_ORDINAL, TOOL_SESSION_EVIDENCE_MAX_BYTES, toolCallEvidenceBytes, toolCallKey, } from '@phnx-labs/sessions-cli/reader';
 export function canonicalToolLedgerPath(filePath) {
     let probe = path.resolve(filePath);
     const suffix = [];
@@ -17,7 +17,6 @@ export function canonicalToolLedgerPath(filePath) {
         }
     }
 }
-/** Resolve the transcript that actually carries tool events for split-file harnesses. */
 export function toolEvidenceSourcePath(filePath, agent) {
     if (agent === 'kimi' && path.basename(filePath) === 'state.json') {
         return path.join(path.dirname(filePath), 'agents', 'main', 'wire.jsonl');
@@ -32,8 +31,6 @@ function deleteSessionCalls(db, sessionId) {
         .all(sessionId);
     const deletePrograms = db.prepare(`DELETE FROM tool_call_programs WHERE call_key = ?`);
     const deleteOccurrences = db.prepare(`DELETE FROM tool_program_occurrences WHERE call_key = ?`);
-    // Addressed by rowid, never by the UNINDEXED call_key — see the tool_call_text
-    // schema comment in db.ts. A call_key predicate scans the whole FTS index.
     const deleteText = db.prepare(`DELETE FROM tool_call_text WHERE rowid = ?`);
     for (const { rowid, call_key } of rows) {
         deletePrograms.run(call_key);
@@ -42,12 +39,10 @@ function deleteSessionCalls(db, sessionId) {
     }
     db.prepare(`DELETE FROM tool_calls WHERE session_id = ?`).run(sessionId);
 }
-/** Remove cached tool evidence when its source transcript no longer exists. */
 export function purgeToolCalls(db, sessionId) {
     deleteSessionCalls(db, sessionId);
     db.prepare(`DELETE FROM tool_scan_ledger WHERE session_id = ?`).run(sessionId);
 }
-/** Purge deleted direct children when a transcript directory's stamp changes. */
 export function purgeMissingToolCallsInDirectory(db, dirPath, currentFilePaths) {
     const normalizedDir = path.normalize(dirPath);
     const prefix = normalizedDir.endsWith(path.sep) ? normalizedDir : normalizedDir + path.sep;
@@ -67,7 +62,6 @@ export function purgeMissingToolCallsInDirectory(db, dirPath, currentFilePaths)
     }
     return purged;
 }
-/** Persist one parser batch, its file stamp, and its resume point atomically. */
 export function persistToolCalls(db, session, calls, sourceStamp, options = {}) {
     const mode = options.mode ?? 'replace';
     const maxSessionBytes = options.maxSessionBytes ?? TOOL_SESSION_EVIDENCE_MAX_BYTES;
@@ -99,8 +93,6 @@ export function persistToolCalls(db, session, calls, sourceStamp, options = {})
     INSERT INTO tool_program_occurrences (call_key, occurrence_ordinal, program, role)
     VALUES (?, ?, ?, ?)
   `);
-    // tool_call_text rows are addressed by the rowid of the tool_calls row they
-    // describe (db.ts schema comment): its UNINDEXED call_key cannot be seeked.
     const insertText = db.prepare(`INSERT INTO tool_call_text (rowid, call_key, tool, input, output, error) VALUES (?, ?, ?, ?, ?, ?)`);
     const callRowid = db.prepare(`SELECT rowid FROM tool_calls WHERE call_key = ?`);
     const deletePrograms = db.prepare(`DELETE FROM tool_call_programs WHERE call_key = ?`);
@@ -199,8 +191,6 @@ export function persistToolCalls(db, session, calls, sourceStamp, options = {})
         for (const call of accepted) {
             const key = toolCallKey(session.id, call.ordinal);
             insertCall.run(key, session.id, call.ordinal, call.sourceCallId ?? null, call.timestamp, call.endTimestamp ?? null, call.tool, call.input, call.outcome, call.exitCode ?? null, call.statusCode ?? null, call.errorCode ?? null, call.output ?? null, call.error ?? null, call.parseError ?? null, toolCallEvidenceBytes(call));
-            // The upsert above preserves the rowid of a call it updated, so this is
-            // the same rowid the existing text row (if any) was written under.
             const { rowid } = callRowid.get(key);
             deletePrograms.run(key);
             deleteOccurrences.run(key);
@@ -216,26 +206,6 @@ export function persistToolCalls(db, session, calls, sourceStamp, options = {})
     });
     txn();
 }
-/**
- * Decide whether a changed full-file-harness session can RESUME its tool index
- * from the last scan instead of re-deriving every call (PHNX-3411).
- *
- * The warm-tick indexer re-derives tool calls for a changed session on every
- * tick, and for an ACTIVE large session that means re-sanitizing tens of
- * thousands of calls each time — the synchronous work that wedged the daemon
- * event loop. Streaming harnesses (claude/codex) already resume from a byte
- * offset; every other harness re-parses the whole file, so this brings them the
- * same benefit at the EVENT level: the ledger stores how many events were folded
- * (`parsed_offset`) plus the collector snapshot (`parser_state`), and a later
- * scan folds only the newly appended events.
- *
- * Returns the prior resume point when it is safe to append, or `null` (full
- * re-scan) whenever the stored prefix may no longer describe the current file:
- * a different extractor, no recorded resume point, a source the ledger row does
- * not describe, a transcript that shrank below what was already parsed (a
- * truncation/rewrite, not an append), more events already folded than the file
- * now yields, or a snapshot that does not read back.
- */
 export function planEventToolResume(db, sessionId, sourcePath, stamp, currentEventCount) {
     const row = db.prepare(`
     SELECT file_path, file_size, extractor_version, parsed_offset, parser_state
@@ -251,8 +221,6 @@ export function planEventToolResume(db, sessionId, sourcePath, stamp, currentEve
         return null;
     if (stamp.fileSize < row.file_size)
         return null;
-    // The file grew but reports fewer events than were already folded — the prefix
-    // was rewritten, not appended to. Re-scan from scratch.
     if (row.parsed_offset > currentEventCount)
         return null;
     if (row.parser_state === null)

package/dist/lib/session/viewing-in.d.ts

@@ -1,86 +1,19 @@
-/**
- * "Viewing in <app> tab N" for tmux-hosted agent sessions.
- *
- * A tmux-wrapped agent (see src/lib/exec.ts `runInTmux`) runs detached on the
- * shared socket; a terminal only *displays* it while a client is attached. This
- * resolver answers "which app + tab is looking at this session right now" by
- * matching the session to its attached tmux client(s) and reusing the app/tab
- * resolvers we already have:
- *
- *   - app  — the client's terminal PID walked up the process ancestry via the
- *            shared HOST_MATCHERS logic (`hostFromPid`).
- *   - tab  — per app: Ghostty via `assignGhosttyTabs` (cwd + title match), iTerm
- *            via the `t<n>` field of the client's `$ITERM_SESSION_ID`, and
- *            VS Code / Cursor / Codium via the extension-published `tabIndex` in
- *            live-terminals.json (keyed by session id).
- *
- * No client attached => `undefined` (the session is running detached). Every
- * lookup is best-effort; a miss degrades to `{ app }` with no tab, never throws.
- */
 import type { TmuxClient } from '../tmux/session.js';
 import type { ActiveSession } from './active.js';
 import { type GhosttySurface } from './ghostty-tabs.js';
-/** Where a tmux-hosted session is currently displayed. */
 interface ViewingIn {
-    /** Host app of the attached client — 'ghostty', 'iterm', 'code', 'codium', … */
     app: string;
-    /** 1-based tab number within that app, when it can be resolved. */
     tab?: number;
 }
-/**
- * The one display form of "where is this session being watched" — `'codium tab 3'`
- * when a client is attached, the bare app name when the tab can't be resolved, and
- * `'detached'` when the pane is live but nobody is looking at it (the terminal that
- * displayed it was closed or crashed).
- *
- * `undefined` means **we do not know**, and it covers two different situations that
- * must not be confused with `'detached'`: a session that isn't tmux-hosted (no pane
- * to attach to, so it isn't on this axis at all), and a tmux session whose pane the
- * locator could not resolve (`mapPanesToTargets` returned nothing for this socket,
- * or the row was never enriched). {@link resolveViewingIn} answers `undefined` for
- * BOTH "no client attached" and "could not locate the pane", so the pane's resolved
- * `tmuxTarget` is what separates them: without it there is no evidence of absence,
- * only absence of evidence. Claiming `'detached'` there would invent an orphaned
- * session — and a consumer acts on that claim (the ext's picker pre-ticks every
- * detached row for rescue), so the wrong answer resumes a session nobody asked for.
- *
- * Shared by the `--active` row renderer and the `--json` serializer so a machine
- * consumer reads exactly the string a human sees, instead of re-deriving "detached"
- * from an absent field.
- */
 export declare function viewingInLabel(s: Pick<ActiveSession, 'provenance' | 'viewingIn' | 'tmuxTarget'>): string | undefined;
-/**
- * Wire form -> internal form for a row arriving from another machine's
- * `--active --json`. The fan-out reaches peers whose CLI may predate
- * {@link viewingInLabel} and still emit the `{app, tab}` object, so this boundary
- * normalizes both shapes into one — the ONLY place either shape is accepted.
- * `'detached'` maps to undefined, which is what "no attached client" means
- * internally; {@link viewingInLabel} regenerates the word from the pane.
- */
 export declare function parseViewingIn(raw: unknown): ViewingIn | undefined;
-/** Injection seams so `resolveViewingIn` is unit-testable without a live tmux/ps/osascript. */
 export interface ViewingInDeps {
-    /** Ghostty surfaces (window/tab/cwd/title). Enumerated once by the caller and shared. */
     ghosttySurfaces?: GhosttySurface[];
-    /** pane id -> `session:window.pane`, from `mapPanesToTargets`. Used to find the session name. */
     paneToTarget?: Map<string, string>;
-    /** client pid -> host app. Defaults to the real `hostFromPid`. */
     resolveApp?: (pid: number) => Promise<string | undefined>;
-    /** client pid -> raw env. Defaults to reading /proc (Linux) or `ps eww` (macOS). */
     readClientEnv?: (pid: number) => Promise<Record<string, string> | undefined>;
-    /** session id -> VS Code editor-tab index, from live-terminals.json. Defaults to the real read. */
     tabIndexForSession?: (sessionId: string | undefined) => number | undefined;
 }
-/**
- * Resolve where a single tmux-hosted session is being viewed. Returns undefined
- * when the session isn't tmux-hosted, can't be located, or has no client
- * attached (detached). Pure aside from the injected (defaulted) probes.
- */
 export declare function resolveViewingIn(session: ActiveSession, clients: TmuxClient[], deps?: ViewingInDeps): Promise<ViewingIn | undefined>;
-/**
- * iTerm tab from the attaching client's `$ITERM_SESSION_ID` (`w<n>t<n>p<n>:UUID`).
- * The `t<n>` field is iTerm2's 0-based tab index; we present it 1-based to match
- * Ghostty's `index of tab`. Exported for the parser test.
- */
 export declare function itermTabFromSessionId(value: string | undefined): number | undefined;
 export {};

package/dist/lib/session/viewing-in.js

@@ -1,22 +1,3 @@
-/**
- * "Viewing in <app> tab N" for tmux-hosted agent sessions.
- *
- * A tmux-wrapped agent (see src/lib/exec.ts `runInTmux`) runs detached on the
- * shared socket; a terminal only *displays* it while a client is attached. This
- * resolver answers "which app + tab is looking at this session right now" by
- * matching the session to its attached tmux client(s) and reusing the app/tab
- * resolvers we already have:
- *
- *   - app  — the client's terminal PID walked up the process ancestry via the
- *            shared HOST_MATCHERS logic (`hostFromPid`).
- *   - tab  — per app: Ghostty via `assignGhosttyTabs` (cwd + title match), iTerm
- *            via the `t<n>` field of the client's `$ITERM_SESSION_ID`, and
- *            VS Code / Cursor / Codium via the extension-published `tabIndex` in
- *            live-terminals.json (keyed by session id).
- *
- * No client attached => `undefined` (the session is running detached). Every
- * lookup is best-effort; a miss degrades to `{ app }` with no tab, never throws.
- */
 import * as path from 'path';
 import * as fs from 'fs';
 import { execFile } from 'child_process';
@@ -26,27 +7,6 @@ import { hostFromPid } from './active.js';
 import { enumerateGhosttyTabs, assignGhosttyTabs } from './ghostty-tabs.js';
 import { getTerminalsDir } from '../state.js';
 const execFileAsync = promisify(execFile);
-/**
- * The one display form of "where is this session being watched" — `'codium tab 3'`
- * when a client is attached, the bare app name when the tab can't be resolved, and
- * `'detached'` when the pane is live but nobody is looking at it (the terminal that
- * displayed it was closed or crashed).
- *
- * `undefined` means **we do not know**, and it covers two different situations that
- * must not be confused with `'detached'`: a session that isn't tmux-hosted (no pane
- * to attach to, so it isn't on this axis at all), and a tmux session whose pane the
- * locator could not resolve (`mapPanesToTargets` returned nothing for this socket,
- * or the row was never enriched). {@link resolveViewingIn} answers `undefined` for
- * BOTH "no client attached" and "could not locate the pane", so the pane's resolved
- * `tmuxTarget` is what separates them: without it there is no evidence of absence,
- * only absence of evidence. Claiming `'detached'` there would invent an orphaned
- * session — and a consumer acts on that claim (the ext's picker pre-ticks every
- * detached row for rescue), so the wrong answer resumes a session nobody asked for.
- *
- * Shared by the `--active` row renderer and the `--json` serializer so a machine
- * consumer reads exactly the string a human sees, instead of re-deriving "detached"
- * from an absent field.
- */
 export function viewingInLabel(s) {
     if (s.provenance?.mux?.kind !== 'tmux' || !s.provenance.mux.pane)
         return undefined;
@@ -54,14 +14,6 @@ export function viewingInLabel(s) {
         return s.tmuxTarget ? 'detached' : undefined;
     return s.viewingIn.tab != null ? `${s.viewingIn.app} tab ${s.viewingIn.tab}` : s.viewingIn.app;
 }
-/**
- * Wire form -> internal form for a row arriving from another machine's
- * `--active --json`. The fan-out reaches peers whose CLI may predate
- * {@link viewingInLabel} and still emit the `{app, tab}` object, so this boundary
- * normalizes both shapes into one — the ONLY place either shape is accepted.
- * `'detached'` maps to undefined, which is what "no attached client" means
- * internally; {@link viewingInLabel} regenerates the word from the pane.
- */
 export function parseViewingIn(raw) {
     if (raw && typeof raw === 'object') {
         const app = raw.app;
@@ -73,9 +25,7 @@ export function parseViewingIn(raw) {
     const m = raw.match(/^(.+?) tab (\d+)$/);
     return m ? { app: m[1], tab: parseInt(m[2], 10) } : { app: raw };
 }
-/** Apps whose tab index is published by the extension via live-terminals.json. */
 const EDITOR_APPS = new Set(['code', 'cursor', 'codium', 'windsurf']);
-/** The tmux session name a session's pane belongs to, from `session:window.pane`. */
 function sessionNameFor(session, paneToTarget) {
     const pane = session.provenance?.mux?.pane;
     const target = (pane && paneToTarget?.get(pane)) ?? session.tmuxTarget;
@@ -84,11 +34,6 @@ function sessionNameFor(session, paneToTarget) {
     const name = target.split(':')[0];
     return name || undefined;
 }
-/**
- * Resolve where a single tmux-hosted session is being viewed. Returns undefined
- * when the session isn't tmux-hosted, can't be located, or has no client
- * attached (detached). Pure aside from the injected (defaulted) probes.
- */
 export async function resolveViewingIn(session, clients, deps = {}) {
     if (session.provenance?.mux?.kind !== 'tmux' || !session.provenance.mux.pane)
         return undefined;
@@ -97,7 +42,7 @@ export async function resolveViewingIn(session, clients, deps = {}) {
         return undefined;
     const attached = clients.filter((c) => c.target.split(':')[0] === sessName);
     if (attached.length === 0)
-        return undefined; // running detached — no viewer
+        return undefined;
     const client = attached[0];
     const resolveApp = deps.resolveApp ?? hostFromPid;
     const app = (await resolveApp(client.pid)) ?? 'terminal';
@@ -114,21 +59,13 @@ export async function resolveViewingIn(session, clients, deps = {}) {
     }
     return { app, tab };
 }
-/** Ghostty tab via the existing cwd+title matcher, reusing shared surfaces when provided. */
 async function ghosttyTab(session, surfaces) {
     const s = surfaces ?? (await enumerateGhosttyTabs());
     if (s.length === 0)
         return undefined;
-    // assignGhosttyTabs only considers host === 'ghostty' sessions; use a probe
-    // clone so we don't mutate the real row's host.
     const probe = { ...session, host: 'ghostty' };
     return assignGhosttyTabs([probe], s).get(probe);
 }
-/**
- * iTerm tab from the attaching client's `$ITERM_SESSION_ID` (`w<n>t<n>p<n>:UUID`).
- * The `t<n>` field is iTerm2's 0-based tab index; we present it 1-based to match
- * Ghostty's `index of tab`. Exported for the parser test.
- */
 export function itermTabFromSessionId(value) {
     if (!value)
         return undefined;
@@ -142,7 +79,6 @@ async function itermTab(pid, readEnv) {
     const env = await readEnv(pid);
     return itermTabFromSessionId(env?.ITERM_SESSION_ID);
 }
-/** Read a process's env (best-effort): /proc on Linux, `ps eww` on macOS. */
 async function readClientEnv(pid) {
     if (process.platform === 'linux') {
         try {
@@ -165,7 +101,6 @@ async function readClientEnv(pid) {
                 encoding: 'utf8',
                 maxBuffer: 1024 * 1024,
             });
-            // ITERM_SESSION_ID is a single token (no spaces): grab it out of the flat line.
             const m = stdout.match(/(?:^|\s)ITERM_SESSION_ID=(\S+)/);
             return m ? { ITERM_SESSION_ID: m[1] } : {};
         }
@@ -175,11 +110,6 @@ async function readClientEnv(pid) {
     }
     return undefined;
 }
-/**
- * VS Code editor-tab index for a session, from the extension's live-terminals.json
- * (`tabIndex` per entry — the DATA CONTRACT with the extension teammate). Read
- * directly (not via active.ts's readLiveTerminals, which strips tabIndex).
- */
 function tabIndexFromLiveTerminals(sessionId) {
     if (!sessionId)
         return undefined;

package/dist/lib/session/watch.js

@@ -1,3 +1 @@
-// Moved to ./remote/watch.ts (move 4 of the core-module refactor).
-// Kept as a re-export shim so existing importers don't break.
 export * from './remote/watch.js';

package/dist/lib/session/width.js

@@ -1,4 +1 @@
-// Moved to ../text/width.ts (move 1 of the core-module refactor — see
-// .agents/artifacts/2026-08-20/plan-*.md). Kept as a re-export shim so
-// existing importers don't break.
 export * from '../text/width.js';