@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/terminal/run-surface.d.ts

@@ -1,82 +1,26 @@
-/**
- * `agents run … --terminal` — re-open this exact run as a tab in a real terminal.
- *
- * A GUI caller (the menu bar's "New Session") cannot host a TUI, so it has to
- * hand the run to a terminal. It used to do that by hardcoding AppleScript at
- * Terminal.app; now it appends `--terminal` and the CLI decides WHICH terminal
- * from the user's own live sessions (preferred.ts) and opens the tab through the
- * launch engine — the same engine `sessions resume` and `sessions focus` use.
- *
- * The re-invocation is the caller's own argv with the `--terminal` flag removed,
- * so every other flag (`--mode`, `--cwd`, a `--` passthrough) rides along
- * untouched and there is no second place that knows how to spell a run.
- */
 import type { Backend, EngineContext } from './types.js';
 import type { ActiveSession } from '../session/active.js';
 import { type LaunchBackendChoice, type SessionHostSample } from './preferred.js';
-/** Backends a user may name in `--terminal <backend>`. */
 export declare const TERMINAL_FLAG_BACKENDS: Backend[];
-/**
- * Validate a `--terminal <value>`. Returns the backend, or an error message
- * naming the valid ids — never a silent fallback to auto-detection, which would
- * open a terminal the user did not ask for.
- */
 export declare function parseTerminalFlag(value: unknown): {
     backend?: Backend;
     error?: string;
 };
-/**
- * The argv to re-invoke, with `--terminal` (and the value commander consumed for
- * it) removed. `consumedValue` is the parsed option value when it is a string —
- * that is the only token after the flag that belongs to it, so a prompt or a
- * following flag is never eaten.
- */
 export declare function stripTerminalFlag(argv: string[], consumedValue?: string): string[];
-/** `agents run …` as a shell-safe command line for the surface to exec. */
 export declare function buildRunCommand(argv: string[]): string[];
-/**
- * Turn live sessions into the samples the resolver reads, filling in the app
- * each tmux-hosted session is currently VIEWED in.
- *
- * This step is what makes detection work for the common case: `agents run`
- * wraps interactive runs in tmux, so a session the user started in Ghostty is
- * attributed `host: 'tmux'` on the discovery path and would otherwise name no
- * terminal at all. `resolveViewingIn` walks the attached tmux client's pid up to
- * its host app — the same resolver `agents sessions` uses to print
- * "viewing in Ghostty tab 2". Sessions that are detached (no client attached)
- * legitimately have no viewer and keep their `tmux` host.
- *
- * One inherited nuance: `resolveViewingIn` labels a client whose app it cannot
- * identify `'terminal'` (viewing-in.ts:87), so a tmux session viewed from an
- * unrecognized emulator resolves to Terminal.app rather than falling through.
- * That lands on the same every-Mac floor the fallback chain ends at anyway, so
- * it costs nothing here — but it is a default, not a detection.
- *
- * Best-effort: any probe failure degrades to the plain host, never throws.
- */
 export declare function toHostSamples(sessions: ActiveSession[]): Promise<SessionHostSample[]>;
 export interface OpenRunSurfaceParams {
-    /** This process's argv after the program name (i.e. `['run','claude',…]`). */
     argv: string[];
-    /** The parsed `--terminal` value, when the user named a backend. */
     forced?: Backend;
-    /** The value commander consumed for `--terminal`, so it can be stripped. */
     consumedValue?: string;
     cwd: string;
-    /** Live sessions, used to detect the terminal the user actually works in. */
     sessions: SessionHostSample[];
     ctx: EngineContext;
 }
 export interface OpenRunSurfaceResult {
     ok: boolean;
     choice?: LaunchBackendChoice;
-    /** Human line describing the terminal that was chosen. */
     description?: string;
     error?: string;
 }
-/**
- * Open the run as a tab in the resolved terminal. Never throws — a failure comes
- * back as `ok: false` with the reason, so the caller can tell the user rather
- * than exiting silently.
- */
 export declare function openRunInTerminal(params: OpenRunSurfaceParams): Promise<OpenRunSurfaceResult>;

package/dist/lib/terminal/run-surface.js

@@ -3,23 +3,13 @@ import { openSurface } from './engine.js';
 import { getCliLaunch } from '../cli-entry.js';
 import { shellQuote } from './quote.js';
 import { resolveLaunchBackend, describeBackendChoice, } from './preferred.js';
-/** Backends a user may name in `--terminal <backend>`. */
 export const TERMINAL_FLAG_BACKENDS = Object.keys(BACKENDS);
-/**
- * Validate a `--terminal <value>`. Returns the backend, or an error message
- * naming the valid ids — never a silent fallback to auto-detection, which would
- * open a terminal the user did not ask for.
- */
 export function parseTerminalFlag(value) {
     if (value === undefined || value === true || value === '')
         return {};
     const raw = String(value);
     if (TERMINAL_FLAG_BACKENDS.includes(raw))
         return { backend: raw };
-    // `--terminal [backend]` takes an OPTIONAL value, and commander assigns the
-    // next non-option token to it — so `agents run claude --terminal "fix the bug"`
-    // lands the prompt here. Say that, or the user just sees their prompt called a
-    // bad backend name and has no idea why.
     const looksLikeAPrompt = /\s/.test(raw) || raw.length > 24;
     const hint = looksLikeAPrompt
         ? ` That looks like a prompt: put it BEFORE the flag — agents run <agent> "${raw.length > 40 ? `${raw.slice(0, 40)}…` : raw}" --terminal.`
@@ -28,18 +18,10 @@ export function parseTerminalFlag(value) {
         error: `Unknown --terminal backend '${raw}'. Use one of: ${TERMINAL_FLAG_BACKENDS.join(', ')} (or pass --terminal alone to auto-detect).${hint}`,
     };
 }
-/**
- * The argv to re-invoke, with `--terminal` (and the value commander consumed for
- * it) removed. `consumedValue` is the parsed option value when it is a string —
- * that is the only token after the flag that belongs to it, so a prompt or a
- * following flag is never eaten.
- */
 export function stripTerminalFlag(argv, consumedValue) {
     const out = [];
     for (let i = 0; i < argv.length; i++) {
         const tok = argv[i];
-        // Everything past a bare `--` is forwarded verbatim to the agent's own CLI
-        // (`agents run kimi -- --terminal`), so it is not ours to rewrite.
         if (tok === '--') {
             out.push(...argv.slice(i));
             break;
@@ -55,31 +37,10 @@ export function stripTerminalFlag(argv, consumedValue) {
     }
     return out;
 }
-/** `agents run …` as a shell-safe command line for the surface to exec. */
 export function buildRunCommand(argv) {
     const { command, args } = getCliLaunch(argv);
     return [command, ...args].map(shellQuote);
 }
-/**
- * Turn live sessions into the samples the resolver reads, filling in the app
- * each tmux-hosted session is currently VIEWED in.
- *
- * This step is what makes detection work for the common case: `agents run`
- * wraps interactive runs in tmux, so a session the user started in Ghostty is
- * attributed `host: 'tmux'` on the discovery path and would otherwise name no
- * terminal at all. `resolveViewingIn` walks the attached tmux client's pid up to
- * its host app — the same resolver `agents sessions` uses to print
- * "viewing in Ghostty tab 2". Sessions that are detached (no client attached)
- * legitimately have no viewer and keep their `tmux` host.
- *
- * One inherited nuance: `resolveViewingIn` labels a client whose app it cannot
- * identify `'terminal'` (viewing-in.ts:87), so a tmux session viewed from an
- * unrecognized emulator resolves to Terminal.app rather than falling through.
- * That lands on the same every-Mac floor the fallback chain ends at anyway, so
- * it costs nothing here — but it is a default, not a detection.
- *
- * Best-effort: any probe failure degrades to the plain host, never throws.
- */
 export async function toHostSamples(sessions) {
     const samples = sessions.map((s) => ({
         host: s.host,
@@ -95,7 +56,6 @@ export async function toHostSamples(sessions) {
         const { enumerateGhosttyTabs } = await import('../session/ghostty-tabs.js');
         const { mapPanesToTargets, listClients } = await import('../tmux/session.js');
         const { resolveViewingIn } = await import('../session/viewing-in.js');
-        // One Ghostty enumeration shared across sockets, as the sessions renderer does.
         const ghosttySurfaces = await enumerateGhosttyTabs();
         const sockets = new Set(tmuxIdx.map(({ s }) => s.provenance.mux.socket));
         for (const socket of sockets) {
@@ -113,15 +73,9 @@ export async function toHostSamples(sessions) {
         }
     }
     catch {
-        // tmux/Ghostty probes are best-effort; fall back to the plain host values.
     }
     return samples;
 }
-/**
- * Open the run as a tab in the resolved terminal. Never throws — a failure comes
- * back as `ok: false` with the reason, so the caller can tell the user rather
- * than exiting silently.
- */
 export async function openRunInTerminal(params) {
     const choice = params.forced
         ? { backend: params.forced, source: 'forced' }

package/dist/lib/terminal/shell.d.ts

@@ -1,6 +1,3 @@
-/** `cd <cwd> && exec <command>` — for backends that don't set cwd natively. */
 export declare function loginExec(cwd: string, command: string[]): string;
-/** `exec <command>` — for backends that set the working directory natively. */
 export declare function execOnly(command: string[]): string;
-/** Wrap an inner shell script in an interactive login zsh: `zsh -ilc '<inner>'`. */
 export declare function iLoginShell(inner: string): string;

package/dist/lib/terminal/shell.js

@@ -1,23 +1,10 @@
-/**
- * Interactive-login-shell wrappers shared by every backend.
- *
- * `-i` is load-bearing, not cosmetic: the version-pinned shims (e.g.
- * `claude@2.1.187`) live in `~/.agents/.cache/shims`, which `.zshrc` puts on
- * PATH for *interactive* shells only. A plain `zsh -lc` (login, non-interactive)
- * skips `.zshrc`, so the shim isn't found and the surface dies with "command not
- * found". Every backend wraps its command in `zsh -ilc` for this reason — do not
- * drop the `-i`.
- */
 import { shellQuote } from './quote.js';
-/** `cd <cwd> && exec <command>` — for backends that don't set cwd natively. */
 export function loginExec(cwd, command) {
     return `cd ${shellQuote(cwd)} && exec ${command.join(' ')}`;
 }
-/** `exec <command>` — for backends that set the working directory natively. */
 export function execOnly(command) {
     return `exec ${command.join(' ')}`;
 }
-/** Wrap an inner shell script in an interactive login zsh: `zsh -ilc '<inner>'`. */
 export function iLoginShell(inner) {
     return `zsh -ilc ${shellQuote(inner)}`;
 }

package/dist/lib/terminal/transport.d.ts

@@ -1,25 +1,11 @@
 import type { LaunchSpec } from './types.js';
-/** Resolve a host alias to an ssh target. Default: identity (ssh_config resolves it). */
 export type HostResolver = (alias: string) => string;
 export interface RunResult {
     ok: boolean;
     error?: string;
 }
-/** Grace between SIGTERM and SIGKILL when a deadline cancels a launcher. */
 export declare const SPEC_KILL_GRACE_MS = 250;
-/**
- * Run the spec on this machine: spawn the launcher, resolve when it exits.
- *
- * `timeoutMs` makes the call genuinely bounded rather than merely raced: the
- * child is spawned in its OWN process group (`detached`) and the whole group is
- * signalled on expiry, so a launcher that itself spawned something (osascript →
- * the app, tmux → the server) cannot keep running after the caller has given up.
- * Racing the promise alone leaves the process behind (PHNX-3999).
- */
 export declare function runLocal(spec: LaunchSpec, timeoutMs?: number): Promise<RunResult>;
-/** Serialize a launch argv into a single POSIX-quoted shell command string. */
 export declare function remoteCommand(spec: LaunchSpec): string;
-/** Run the spec on a remote host over SSH. `timeoutMs` bounds the ssh client. */
 export declare function runRemote(spec: LaunchSpec, target: string, timeoutMs?: number): RunResult;
-/** Run a spec locally (no host / 'local') or on a resolved remote host. */
 export declare function runSpec(spec: LaunchSpec, host?: string, resolveHost?: HostResolver, timeoutMs?: number): Promise<RunResult>;

package/dist/lib/terminal/transport.js

@@ -1,37 +1,12 @@
-/**
- * Transport — runs a LaunchSpec locally or on a remote host.
- *
- * Local: spawn the launcher (osascript / tmux) and wait for it to exit — these
- * are short-lived commands that create the surface and return, so waiting gives
- * a real success/failure. Remote: serialize the argv into one shell string and
- * hand it to `sshExec` — the same hardened SSH primitive `agents sessions
- * --device` and the browser driver use (target-injection guard, POSIX quoting,
- * connection multiplexing).
- */
 import { spawn } from 'child_process';
 import { sshExec } from '../ssh-exec.js';
 import { shellQuote } from './quote.js';
-/** Grace between SIGTERM and SIGKILL when a deadline cancels a launcher. */
 export const SPEC_KILL_GRACE_MS = 250;
-/**
- * Run the spec on this machine: spawn the launcher, resolve when it exits.
- *
- * `timeoutMs` makes the call genuinely bounded rather than merely raced: the
- * child is spawned in its OWN process group (`detached`) and the whole group is
- * signalled on expiry, so a launcher that itself spawned something (osascript →
- * the app, tmux → the server) cannot keep running after the caller has given up.
- * Racing the promise alone leaves the process behind (PHNX-3999).
- */
 export function runLocal(spec, timeoutMs) {
     return new Promise((resolve) => {
         const child = spawn(spec.argv[0], spec.argv.slice(1), { stdio: 'ignore', detached: !!timeoutMs });
         let settled = false;
         let killTimer = null;
-        // NOTE: the pending SIGKILL is deliberately NOT cancelled here. Resolving
-        // the promise is the CALLER giving up; it is not the child exiting. Clearing
-        // the kill timer on the timeout path (which resolves immediately after
-        // arming it) meant a SIGTERM-ignoring child was never killed and simply
-        // survived the bound this function exists to enforce.
         const done = (result) => {
             if (settled)
                 return;
@@ -45,7 +20,7 @@ export function runLocal(spec, timeoutMs) {
                 if (child.pid)
                     process.kill(timeoutMs ? -child.pid : child.pid, signal);
             }
-            catch { /* already gone */ }
+            catch { }
         };
         const timer = timeoutMs
             ? setTimeout(() => {
@@ -55,7 +30,6 @@ export function runLocal(spec, timeoutMs) {
                 done({ ok: false, error: `${spec.argv[0]} did not finish in ${timeoutMs}ms` });
             }, timeoutMs)
             : null;
-        // Only the child ACTUALLY exiting retires the pending SIGKILL.
         const childGone = () => { if (killTimer) {
             clearTimeout(killTimer);
             killTimer = null;
@@ -67,11 +41,9 @@ export function runLocal(spec, timeoutMs) {
         });
     });
 }
-/** Serialize a launch argv into a single POSIX-quoted shell command string. */
 export function remoteCommand(spec) {
     return spec.argv.map(shellQuote).join(' ');
 }
-/** Run the spec on a remote host over SSH. `timeoutMs` bounds the ssh client. */
 export function runRemote(spec, target, timeoutMs) {
     const res = sshExec(target, remoteCommand(spec), { multiplex: !timeoutMs, timeoutMs });
     if (res.timedOut)
@@ -81,7 +53,6 @@ export function runRemote(spec, target, timeoutMs) {
     const err = (res.stderr || '').trim();
     return { ok: false, error: err || `ssh exited with code ${res.code}` };
 }
-/** Run a spec locally (no host / 'local') or on a resolved remote host. */
 export async function runSpec(spec, host, resolveHost, timeoutMs) {
     if (!host || host === 'local')
         return runLocal(spec, timeoutMs);

package/dist/lib/terminal/types.d.ts

@@ -1,78 +1,38 @@
-/**
- * Core types for the terminal launch engine.
- *
- * The engine opens an *interactive* surface — a tab or a split pane — running a
- * command, in a chosen terminal backend (iTerm / Ghostty / tmux), on this
- * machine or a remote host. This is distinct from cloud providers
- * (src/lib/cloud), which dispatch autonomous headless tasks; a terminal surface
- * is attended and live. See docs/interfaces.md.
- */
-/** An interactive terminal backend the engine can drive. */
 export type Backend = 'iterm' | 'ghostty' | 'tmux' | 'vscodium-agent' | 'terminal';
-/** Which way a split pane grows. `right` = side-by-side; `down` = stacked. */
 export type SplitDirection = 'right' | 'down';
-/** Where a surface lands: a new tab, or a split of the current pane. */
 export type Layout = 'tab' | 'split-right' | 'split-down';
-/** Ambient facts a backend needs to decide availability and detection. */
 export interface EngineContext {
     platform: NodeJS.Platform;
     env: NodeJS.ProcessEnv;
 }
-/** Snapshot the live process context. */
 export declare function currentContext(): EngineContext;
-/** The concrete OS command that opens a surface — the pure output of a backend. */
 export interface LaunchSpec {
-    /** argv to run (e.g. `['osascript','-e',script]` or `['tmux','split-window',…]`). */
     argv: string[];
 }
-/**
- * Optional identity the caller already knows about the surface. The
- * vscodium-agent backend forwards these into the swarm-ext `/spawn` URI so the
- * extension can set the tab chip/name/session without sniffing the local
- * process tree (required for remote `ssh … tmux attach` resumes — #2478).
- * Other backends ignore them.
- */
 export interface SurfaceMeta {
-    /** Harness id: claude, codex, grok, … */
     agent?: string;
-    /** Canonical session id. */
     sessionId?: string;
-    /** Optional pre-baked tab title. */
     title?: string;
 }
-/** A single "open this command as this surface" instruction. */
 export interface LaunchRequest {
     backend: Backend;
     layout: Layout;
-    /** Working directory the command runs in. */
     cwd: string;
-    /** argv to exec in the surface (e.g. a resume command). */
     command: string[];
-    /** undefined / 'local' = this machine; otherwise a resolvable host alias. */
     host?: string;
-    /** Optional agent identity for editor-backed backends. */
     agent?: string;
     sessionId?: string;
     title?: string;
 }
-/** Outcome of opening one surface. Never throws for launch failures — reports them. */
 export interface LaunchResult {
     ok: boolean;
     request: LaunchRequest;
     error?: string;
 }
-/**
- * A terminal backend: pure builders + an availability check. No side effects —
- * building a spec never opens anything, so every backend is unit-testable
- * without a display. The engine's transport is what actually runs the spec.
- */
 export interface TerminalBackend {
     readonly id: Backend;
     readonly label: string;
-    /** Can this backend be driven here? (platform + app installed / inside tmux). */
     isAvailable(ctx: EngineContext): boolean;
-    /** Command that opens a new tab running `command` in `cwd`. */
     buildTab(cwd: string, command: string[], meta?: SurfaceMeta): LaunchSpec;
-    /** Command that splits the current surface, running `command` in `cwd`. */
     buildSplit(cwd: string, command: string[], direction: SplitDirection, meta?: SurfaceMeta): LaunchSpec;
 }

package/dist/lib/terminal/types.js

@@ -1,13 +1,3 @@
-/**
- * Core types for the terminal launch engine.
- *
- * The engine opens an *interactive* surface — a tab or a split pane — running a
- * command, in a chosen terminal backend (iTerm / Ghostty / tmux), on this
- * machine or a remote host. This is distinct from cloud providers
- * (src/lib/cloud), which dispatch autonomous headless tasks; a terminal surface
- * is attended and live. See docs/interfaces.md.
- */
-/** Snapshot the live process context. */
 export function currentContext() {
     return { platform: process.platform, env: process.env };
 }

package/dist/lib/text/relative-time.d.ts

@@ -1,44 +1,8 @@
-/**
- * Human-readable "time since" formatting for session timestamps. Lives here (not
- * inline in `sessions.ts`) so both the session list renderer and the remote
- * offline-cache banner (`remote.ts`) share one formatter — `sessions.ts` imports
- * `remote.ts`, so a back-import would cycle.
- */
 export declare function formatRelativeTime(isoTimestamp: string): string;
-/**
- * Compact age — `now`, `45m`, `3h`, `2d`, then the calendar date. This is the
- * *creation* half of a session's time cell: it renders right next to the long
- * last-activity label, and one row can afford one long form, not two.
- */
 export declare function formatCompactAge(isoTimestamp: string): string;
-/** The two time fields a session listing shows for one row. */
 export interface SessionAgeParts {
-    /**
-     * Compact age of the session's creation, set only when the session ran long
-     * enough (>= a minute) for it to say something `last` does not.
-     */
     created?: string;
-    /** Last-activity label — the long relative form the listing sorts by. */
     last: string;
 }
-/**
- * Split a session's timestamps into the two fields a listing renders: when it
- * was created and when it was last active. One last-activity label answers
- * neither "is this the old session I'm looking for" nor "how long did it run" —
- * a session touched an hour ago may have started last week.
- */
 export declare function sessionAgeParts(createdIso: string, lastActivityIso?: string): SessionAgeParts;
-/**
- * Parse a time filter string (relative like '7d' or an ISO timestamp) into epoch
- * milliseconds. Backs `--since` on `sessions`, `cost`, `teams`, and `output`, and
- * `--unused` on `secrets list`.
- *
- * It lives here, in a module with no imports, rather than in `discover.ts` where
- * it started: `discover.ts` loads `../sqlite.js`, so importing this one function
- * from there pulls `node:sqlite` into the caller's module graph and Node prints
- * `ExperimentalWarning: SQLite …` on stderr. That is invisible in a command that
- * already touches the session DB, and a broken contract in one that doesn't —
- * `monitors --json` asserts a clean stderr. `discover.ts` re-exports it, so
- * existing importers are unaffected.
- */
 export declare function parseTimeFilter(input: string): number;

package/dist/lib/text/relative-time.js

@@ -1,15 +1,4 @@
-/**
- * Human-readable "time since" formatting for session timestamps. Lives here (not
- * inline in `sessions.ts`) so both the session list renderer and the remote
- * offline-cache banner (`remote.ts`) share one formatter — `sessions.ts` imports
- * `remote.ts`, so a back-import would cycle.
- */
 const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
-/**
- * Calendar label for a timestamp older than the relative window. A 2-digit year
- * is appended outside the current year so "Jun 28" is never ambiguous across
- * years (e.g. "Jun 28 '25").
- */
 function calendarLabel(thenMs, nowMs) {
     const d = new Date(thenMs);
     const label = `${MONTHS[d.getMonth()]} ${d.getDate()}`;
@@ -34,14 +23,8 @@ export function formatRelativeTime(isoTimestamp) {
         return `${diffHrs} hour${diffHrs === 1 ? '' : 's'} ago`;
     if (diffDays < 7)
         return `${diffDays} day${diffDays === 1 ? '' : 's'} ago`;
-    // Older: show the date.
     return calendarLabel(then, now);
 }
-/**
- * Compact age — `now`, `45m`, `3h`, `2d`, then the calendar date. This is the
- * *creation* half of a session's time cell: it renders right next to the long
- * last-activity label, and one row can afford one long form, not two.
- */
 export function formatCompactAge(isoTimestamp) {
     const now = Date.now();
     const then = new Date(isoTimestamp).getTime();
@@ -61,18 +44,7 @@ export function formatCompactAge(isoTimestamp) {
         return `${diffDays}d`;
     return calendarLabel(then, now);
 }
-/**
- * Shortest creation→last-activity gap worth rendering as two fields. Below it
- * both halves name the same minute, so the row would carry a duplicate instead
- * of information.
- */
 const SPAN_MIN_MS = 60_000;
-/**
- * Split a session's timestamps into the two fields a listing renders: when it
- * was created and when it was last active. One last-activity label answers
- * neither "is this the old session I'm looking for" nor "how long did it run" —
- * a session touched an hour ago may have started last week.
- */
 export function sessionAgeParts(createdIso, lastActivityIso) {
     const lastIso = lastActivityIso ?? createdIso;
     const last = formatRelativeTime(lastIso);
@@ -82,22 +54,7 @@ export function sessionAgeParts(createdIso, lastActivityIso) {
         return { last };
     return { created: formatCompactAge(createdIso), last };
 }
-/**
- * Parse a time filter string (relative like '7d' or an ISO timestamp) into epoch
- * milliseconds. Backs `--since` on `sessions`, `cost`, `teams`, and `output`, and
- * `--unused` on `secrets list`.
- *
- * It lives here, in a module with no imports, rather than in `discover.ts` where
- * it started: `discover.ts` loads `../sqlite.js`, so importing this one function
- * from there pulls `node:sqlite` into the caller's module graph and Node prints
- * `ExperimentalWarning: SQLite …` on stderr. That is invisible in a command that
- * already touches the session DB, and a broken contract in one that doesn't —
- * `monitors --json` asserts a clean stderr. `discover.ts` re-exports it, so
- * existing importers are unaffected.
- */
 export function parseTimeFilter(input) {
-    // Units: m=minute, h=hour, d=day, w=week, mo=month(30d), y=year(365d). `mo`
-    // must precede the single-letter alternatives so "1mo" isn't read as "1m"+"o".
     const relativeMatch = input.match(/^(\d+)(mo|[mhdwy])$/i);
     if (relativeMatch) {
         const value = parseInt(relativeMatch[1], 10);

package/dist/lib/text/short-id.d.ts

@@ -1,17 +1 @@
-/**
- * Canonical derivation of a session's 8-char `shortId`.
- *
- * Every session parser used to inline `id.slice(0, 8)` — some with a
- * `.replace(prefix, '')` strip first (`session_`, `api-`, `ses_`). That strip is
- * the bug: an id that is *only* its prefix (a bare `session_` directory, an id of
- * exactly `api-`) strips to `''`, and `''.slice(0, 8)` is still `''`. An empty
- * shortId then passes the `short_id TEXT NOT NULL` constraint (empty string is not
- * NULL) yet matches nothing in the `short_id LIKE ?` picker lookups — a silently
- * corrupt index row.
- *
- * This helper is the single source of truth: it strips the optional prefix, takes
- * the first 8 chars, and — the whole point — guarantees a NON-EMPTY result by
- * falling back to the unstripped id when the strip empties it, so a row always
- * stays addressable by its shortId.
- */
 export declare function deriveShortId(id: string, stripPrefix?: RegExp): string;

package/dist/lib/text/short-id.js

@@ -1,19 +1,3 @@
-/**
- * Canonical derivation of a session's 8-char `shortId`.
- *
- * Every session parser used to inline `id.slice(0, 8)` — some with a
- * `.replace(prefix, '')` strip first (`session_`, `api-`, `ses_`). That strip is
- * the bug: an id that is *only* its prefix (a bare `session_` directory, an id of
- * exactly `api-`) strips to `''`, and `''.slice(0, 8)` is still `''`. An empty
- * shortId then passes the `short_id TEXT NOT NULL` constraint (empty string is not
- * NULL) yet matches nothing in the `short_id LIKE ?` picker lookups — a silently
- * corrupt index row.
- *
- * This helper is the single source of truth: it strips the optional prefix, takes
- * the first 8 chars, and — the whole point — guarantees a NON-EMPTY result by
- * falling back to the unstripped id when the strip empties it, so a row always
- * stays addressable by its shortId.
- */
 export function deriveShortId(id, stripPrefix) {
     const stripped = stripPrefix ? id.replace(stripPrefix, '') : id;
     return stripped.slice(0, 8) || id.slice(0, 8) || id;

package/dist/lib/text/width.d.ts

@@ -1,29 +1,5 @@
-/**
- * Terminal display-width helpers.
- *
- * `String.length` is the wrong ruler for a terminal: it over-counts ANSI colour
- * escapes (chalk output) and under-counts wide glyphs (CJK, emoji) which occupy
- * two cells. The result is the drifting, wrapping session-table line users see
- * under tmux and over `--device` SSH. Every renderer that sizes a session-table
- * cell measures and truncates through this module so alignment is computed once,
- * correctly, from the same source of truth.
- */
-/** Strip SGR colour + OSC-8 hyperlink escapes so width is measured on visible characters only. */
 export declare function stripAnsi(s: string): string;
-/** Visible display width of a string, ANSI-aware and wide-char-aware. */
 export declare function stringWidth(s: string): number;
-/**
- * Truncate to a target display width, appending '…' when shortened. Operates on
- * the visible (ANSI-stripped) string; callers colour the result afterwards so
- * the ellipsis is never inserted mid-escape.
- */
 export declare function truncateToWidth(s: string, max: number): string;
-/** Right-pad with spaces to a target display width. Never truncates. */
 export declare function padToWidth(s: string, width: number): string;
-/**
- * Effective terminal width. Reads `$COLUMNS` first so it survives tmux and
- * `--device` SSH (where `process.stdout.columns` is unset or wrong), falls back to
- * the TTY's reported width, then to `fallback`. Clamped to a sane band so a
- * bogus value can't produce a 0-wide or absurdly long table.
- */
 export declare function terminalWidth(fallback?: number): number;