@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/sessions-render.d.ts

@@ -1,8 +1,7 @@
 import type { Command } from 'commander';
-import type { SessionMeta } from '../lib/session/types.js';
+import type { SessionMeta } from '@phnx-labs/sessions-cli/reader';
 export declare const MARKDOWN_RENDER_AGENTS: readonly ["claude", "codex", "antigravity", "opencode", "grok", "rush", "hermes", "kimi", "droid", "cursor"];
 export type ReasoningMode = 'omit' | 'fold' | 'include';
-/** Build one shareable Markdown document from the canonical preview and event model. */
 export declare function renderSessionMarkdownDocument(session: SessionMeta, options?: {
     redact?: boolean;
     reasoning?: ReasoningMode;

package/dist/commands/sessions-render.js

@@ -1,13 +1,12 @@
-/** Render selected normalized session transcripts as redacted Markdown documents. */
 import * as fs from 'fs';
 import { stripVTControlCharacters } from 'node:util';
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
 import { knownSecretValuesFromEnv, redactSecrets } from '../lib/redact.js';
 import { discoverSessions } from '../lib/session/discover.js';
-import { parseSession } from '../lib/session/parse.js';
-import { extractSessionTopic, isSyntheticUserMessage } from '../lib/session/prompt.js';
-import { renderConversationMarkdown } from '../lib/session/render.js';
+import { parseSession } from '@phnx-labs/sessions-cli/reader';
+import { extractSessionTopic, isSyntheticUserMessage } from '@phnx-labs/sessions-cli/reader';
+import { renderConversationMarkdown } from '@phnx-labs/sessions-cli/reader';
 import { buildPreview } from './sessions-picker.js';
 import { parseAgentFilter } from './sessions.js';
 import { selectSessions } from './sessions-export.js';
@@ -31,13 +30,10 @@ function parseReasoning(value) {
 function quotePreview(preview) {
     return preview.split('\n').map((line) => `> ${line}`).join('\n');
 }
-/** Build one shareable Markdown document from the canonical preview and event model. */
 export function renderSessionMarkdownDocument(session, options = {}) {
     if (!MARKDOWN_RENDER_AGENTS.includes(session.agent)) {
         throw new Error(`Cannot render ${session.agent} session ${session.shortId || session.id}: Markdown rendering supports ${MARKDOWN_RENDER_AGENTS.join(', ')}.`);
     }
-    // Preserve normalized tool output here so the Markdown renderer owns the
-    // visible cap and can report exactly how much it omitted.
     const events = parseSession(session.filePath, session.agent, { maxToolOutputChars: Infinity });
     if (events.length === 0) {
         throw new Error(`Cannot render ${session.agent} session ${session.shortId || session.id}: transcript produced no normalized events.`);

package/dist/commands/sessions-resume.d.ts

@@ -1,8 +1,7 @@
 import { type Command } from 'commander';
-import { type SessionMeta } from '../lib/session/types.js';
+import { type SessionMeta } from '@phnx-labs/sessions-cli/reader';
 import { type Backend, type SurfaceItem, type EngineContext, type Packing } from '../lib/terminal/index.js';
 import { type StrictResumeOptions } from './resume.js';
-/** Opening more than this many live sessions at once asks for confirmation first. */
 export declare const CONFIRM_THRESHOLD = 5;
 interface ResumeOptions extends StrictResumeOptions {
     agent?: string;
@@ -15,50 +14,28 @@ interface ResumeOptions extends StrictResumeOptions {
     ghostty?: boolean;
     tmux?: boolean;
     vscodium?: boolean;
-    /** --terminal-app: force macOS Terminal.app. Named to avoid reading as `run --terminal`. */
     terminalApp?: boolean;
     splits?: boolean;
     attachOnly?: boolean;
     local?: boolean;
-    /** Original run argv; only the bare resume selector changes after picking. */
     runArgs?: string[];
 }
 export declare function registerSessionsResumeCommand(sessionsCmd: Command): void;
-/** Keep explicit parent options without replacing resume's own defaults. */
 export declare function resolveResumeOptions(cmd: Command, local: ResumeOptions): ResumeOptions;
 export declare function sessionsResumeAction(query: string | undefined, prompt: string | undefined, options: ResumeOptions): Promise<void>;
-/** Preserve run options and lifecycle intent when the picker opens its selected rows. */
 export declare function buildSelectedResumeArgs(id: string, prompt: string | undefined, options: ResumeOptions): string[];
-/** IDs and tmux aliases are actions, not picker search text. Human phrases keep
- * the existing pre-filtered picker, while an explicit identity resumes directly. */
 export declare function isDirectResumeSelector(query: string): boolean;
-/**
- * Local preflight cannot inspect a peer's files or index. Leave peer validation
- * to the existing origin-device recovery hop. --here without a remote surface
- * opts into local recovery and therefore uses the local transcript guard.
- */
 export declare function partitionResumableSelections(chosen: SessionMeta[], options?: Pick<ResumeOptions, 'here' | 'device'>): {
     resumable: SessionMeta[];
     skipped: SessionMeta[];
 };
-/** Direct identities use focus as the lifecycle dispatcher: it rechecks the
- * live fleet, attaches a healthy pane, and falls through to `agents resume`
- * only when the process is no longer attachable. */
-/** True when `sessions resume <id> --attach-only|--local` must go through
- *  `sessions focus` instead of `runStrictResume` (which can fork a copy). */
 export declare function resumeUsesLifecycleDispatch(query: string | undefined, prompt: string | undefined, options: Pick<ResumeOptions, 'attachOnly' | 'local' | 'mode' | 'interactive' | 'headless' | 'here'>): boolean;
 export declare function dispatchSessionLifecycleInPlace(selector: string, hosts?: string[], attachOnly?: boolean, local?: boolean): Promise<void>;
 export declare function buildSessionLifecycleArgs(selector: string, hosts?: string[], attachOnly?: boolean, local?: boolean): string[];
 export declare function resolveResumePacking(options: Pick<ResumeOptions, 'splits'>): Packing;
-/** Surface commands use shell words; spawnCliInPlace keeps the original argv. */
 export declare function buildSelectedResumeSurface(session: SessionMeta, prompt: string | undefined, options: ResumeOptions): SurfaceItem & {
     session: SessionMeta;
 };
 export declare function resumeHostMismatch(session: Pick<SessionMeta, 'shortId' | 'machine'>, requestedHost: string, self?: string): string | null;
-/**
- * Decide which backend to launch into. Returns a concrete backend, `'inplace'`
- * (resume in the current process — no GUI/tmux available), or `'cancel'` (the
- * user dismissed the chooser).
- */
 export declare function resolveBackend(options: ResumeOptions, ctx: EngineContext, count: number): Promise<Backend | 'inplace' | 'cancel'>;
 export {};

package/dist/commands/sessions-resume.js

@@ -1,21 +1,9 @@
-/**
- * `agents sessions resume` — the one resume surface.
- *
- * - Strict single-session: `sessions resume <id> [prompt]` with optional
- *   --mode/--headless/--interactive/--cwd/--quiet/--here (formerly top-level
- *   `agents resume`). Identity resolution + owner-device hop live in resume.ts.
- * - Multi-select: bare `sessions resume` opens a checkbox picker and fans each
- *   pick into a terminal tab/split via the terminal launch engine.
- * - Direct id/alias always takes the strict path; live-pane attach is
- *   `sessions focus`.
- * - `--device` opens the terminal surface on the session origin only.
- */
 import * as fs from 'fs';
 import chalk from 'chalk';
 import { Option } from 'commander';
-import { isAgentTmuxAlias } from '../lib/session/types.js';
+import { isAgentTmuxAlias } from '@phnx-labs/sessions-cli/reader';
 import { discoverSessions } from '../lib/session/discover.js';
-import { filterTeamSessions } from '../lib/session/team-filter.js';
+import { filterTeamSessions } from '@phnx-labs/sessions-cli/reader';
 import { multiItemPicker, itemPicker } from '../lib/picker.js';
 import { buildPreview } from './sessions-picker.js';
 import { formatPickerLabel, pickerColumnsFor, resolveSessionMetadataValue, parseAgentFilter, } from './sessions.js';
@@ -32,7 +20,6 @@ import { buildResumeRemoteArgs, runStrictResume, wantsStrictResume } from './res
 import { toRemotePortable } from '../lib/project-root.js';
 import { attachLocalLiveSelector } from '../lib/session/local-tmux-attach.js';
 import { sessionHeadline } from '../lib/session/title.js';
-/** Opening more than this many live sessions at once asks for confirmation first. */
 export const CONFIRM_THRESHOLD = 5;
 export function registerSessionsResumeCommand(sessionsCmd) {
     const cmd = sessionsCmd
@@ -110,11 +97,7 @@ export function registerSessionsResumeCommand(sessionsCmd) {
         await sessionsResumeAction(query, prompt, resolveResumeOptions(cmd, options));
     });
 }
-/** Flag names `sessions resume` declares that also exist on its parent `sessions`
- *  command. Booleans and strings only — `device` collides too but needs its own
- *  array-merge handling below, so it is not in this list. */
 const RESUME_PARENT_COLLISION_FLAGS = ['agent', 'all', 'teams', 'since', 'limit', 'local'];
-/** Keep explicit parent options without replacing resume's own defaults. */
 export function resolveResumeOptions(cmd, local) {
     const parent = cmd.parent;
     const { resumeDevice, ...resolved } = local;
@@ -153,19 +136,8 @@ export async function sessionsResumeAction(query, prompt, options) {
     };
     const explicitSurface = !!(options.iterm || options.ghostty || options.tmux || options.vscodium || options.terminalApp || options.device);
     const direct = !!query && (isDirectResumeSelector(query) || wantsStrictResume(prompt, strictOpts));
-    // Direct id/alias (or label with prompt/strict flags) → strict resume
-    // (former top-level `agents sessions resume`). `--attach-only` / `--local`
-    // must go through sessions focus so they cannot silently fork a copy
-    // (AGI EXT still shells `sessions resume <id> --local`).
     if (query && direct && !explicitSurface) {
         const hosts = options.device ? [options.device] : [];
-        // PHNX-3292: a live LOCAL tmux pane (the exact alias, or a unique 8-hex
-        // short id) attaches immediately, before any fleet SSH — the product rule
-        // is "first unique match wins," and a pane already on this box is the
-        // fastest possible match. This applies to bare resume too, not just
-        // `--attach-only`: a prompt/mode/headless/cwd override still means the
-        // caller wants strict resume semantics (a scripted continue), so that
-        // case is excluded via wantsStrictResume.
         if (!options.agent && !options.account && !options.model && !wantsStrictResume(prompt, strictOpts) && await attachLocalLiveSelector(query.trim(), hosts)) {
             return;
         }
@@ -224,8 +196,6 @@ export async function sessionsResumeAction(query, prompt, options) {
             console.log(chalk.gray('No sessions found. Try --all or a different --since window.'));
             return;
         }
-        // 1. Multi-select the sessions. gutter: 6 = the multi-select cursor + checkbox
-        // ('> [x] ') that multiItemPicker prepends, so rows size to fit without wrapping.
         const cols = { ...pickerColumnsFor(sessions), gutter: 6 };
         try {
             chosen = await multiItemPicker({
@@ -261,7 +231,6 @@ export async function sessionsResumeAction(query, prompt, options) {
             return;
         }
     }
-    // 2. Route every selection through the owning device's recovery resolver.
     const { resumable, skipped } = partitionResumableSelections(chosen, options);
     for (const s of skipped) {
         console.log(chalk.yellow(`Skipping ${s.shortId} — nothing to resume (no transcript was written).`));
@@ -272,12 +241,10 @@ export async function sessionsResumeAction(query, prompt, options) {
         return;
     }
     const items = resumable.map((session) => buildSelectedResumeSurface(session, prompt, options));
-    // 3. Resolve the backend (and host).
     const ctx = currentContext();
     const backend = await resolveBackend(options, ctx, items.length);
     if (backend === 'cancel')
         return;
-    // 4. Guard against opening a flood of live agents.
     if (items.length > CONFIRM_THRESHOLD) {
         const proceed = await confirm({
             message: `Open ${items.length} live sessions at once?`,
@@ -286,7 +253,6 @@ export async function sessionsResumeAction(query, prompt, options) {
         if (!proceed)
             return;
     }
-    // 5a. No tab-capable backend (off-macOS, not in tmux, local) — resume in place, sequentially.
     if (backend === 'inplace') {
         if (items.length > 1) {
             console.log(chalk.gray(`Resuming ${items.length} sessions one at a time (no tab-capable terminal detected).`));
@@ -295,19 +261,12 @@ export async function sessionsResumeAction(query, prompt, options) {
             await spawnCliInPlace(buildSelectedResumeArgs(it.session.id, prompt, options));
         return;
     }
-    // 5b. Fan out through the engine. Full-width tabs are the default for batch
-    // recovery; callers can explicitly opt into pairs of side-by-side panes.
     const packing = resolveResumePacking(options);
     const where = options.device ? `${backend} on ${options.device}` : backend;
-    // Terminal.app has no scriptable split, so its buildSplit opens a tab. Say so
-    // when the user actually asked for panes — the layout silently not happening
-    // is worse than one line of warning.
     if (backend === 'terminal' && packing === 'two-per-tab') {
         console.log(chalk.yellow('Terminal.app cannot split panes — opening one tab per session instead.'));
     }
     console.log(chalk.gray(`Opening ${items.length} session${items.length === 1 ? '' : 's'} in ${where} (${packing})…`));
-    // agent + sessionId ride the SurfaceItem into the vscodium-agent spawn URI
-    // so the extension can set the tab chip without process-tree sniffing (#2478).
     const results = await openSurfaces(items.map((it) => ({
         cwd: it.cwd,
         command: it.command,
@@ -331,7 +290,6 @@ export async function sessionsResumeAction(query, prompt, options) {
     if (opened !== items.length)
         process.exitCode = 1;
 }
-/** Preserve run options and lifecycle intent when the picker opens its selected rows. */
 export function buildSelectedResumeArgs(id, prompt, options) {
     if (options.runArgs) {
         const args = [...options.runArgs];
@@ -340,7 +298,6 @@ export function buildSelectedResumeArgs(id, prompt, options) {
         if (index < 0)
             throw new Error('The run command did not contain a bare --resume selector.');
         args.splice(index, 1, '--resume', id);
-        // The outer surface already placed this terminal on the selected device.
         if (options.device) {
             let remoteCwd;
             let localCwd;
@@ -387,17 +344,10 @@ export function buildSelectedResumeArgs(id, prompt, options) {
         args.push('--attach-only');
     return args;
 }
-/** IDs and tmux aliases are actions, not picker search text. Human phrases keep
- * the existing pre-filtered picker, while an explicit identity resumes directly. */
 export function isDirectResumeSelector(query) {
     const selector = query.trim();
     return looksLikeSessionId(selector) || isAgentTmuxAlias(selector);
 }
-/**
- * Local preflight cannot inspect a peer's files or index. Leave peer validation
- * to the existing origin-device recovery hop. --here without a remote surface
- * opts into local recovery and therefore uses the local transcript guard.
- */
 export function partitionResumableSelections(chosen, options = {}) {
     const resumable = [];
     const skipped = [];
@@ -407,11 +357,6 @@ export function partitionResumableSelections(chosen, options = {}) {
     }
     return { resumable, skipped };
 }
-/** Direct identities use focus as the lifecycle dispatcher: it rechecks the
- * live fleet, attaches a healthy pane, and falls through to `agents resume`
- * only when the process is no longer attachable. */
-/** True when `sessions resume <id> --attach-only|--local` must go through
- *  `sessions focus` instead of `runStrictResume` (which can fork a copy). */
 export function resumeUsesLifecycleDispatch(query, prompt, options) {
     if (!query || !isDirectResumeSelector(query))
         return false;
@@ -450,7 +395,6 @@ async function spawnCliInPlace(args) {
 export function resolveResumePacking(options) {
     return options.splits ? 'two-per-tab' : 'tabs';
 }
-/** Surface commands use shell words; spawnCliInPlace keeps the original argv. */
 export function buildSelectedResumeSurface(session, prompt, options) {
     const requestedCwd = options.cwd || session.cwd;
     if (options.device && !requestedCwd) {
@@ -471,11 +415,6 @@ export function resumeHostMismatch(session, requestedHost, self = machineId()) {
         ? null
         : `Session ${session.shortId} originated on ${origin}; --device ${requestedHost} cannot move recovery to another device.`;
 }
-/**
- * Decide which backend to launch into. Returns a concrete backend, `'inplace'`
- * (resume in the current process — no GUI/tmux available), or `'cancel'` (the
- * user dismissed the chooser).
- */
 export async function resolveBackend(options, ctx, count) {
     const forced = options.iterm ? 'iterm'
         : options.ghostty ? 'ghostty'
@@ -485,14 +424,12 @@ export async function resolveBackend(options, ctx, count) {
                         : undefined;
     if (forced)
         return forced;
-    // Remote defaults to tmux (headless, no GUI session assumptions); override with a backend flag.
     if (options.device)
         return 'tmux';
     const available = availableBackends(ctx);
     if (available.length === 0)
         return 'inplace';
     const detected = detectCurrentBackend(ctx);
-    // Only one option and it's where we already are → no need to ask.
     if (available.length === 1 && (!detected || detected === available[0].id))
         return available[0].id;
     const choices = available.map((b) => ({

package/dist/commands/sessions-share.d.ts

@@ -1,5 +1,5 @@
 import type { Command } from 'commander';
-import type { SessionMeta } from '../lib/session/types.js';
+import type { SessionMeta } from '@phnx-labs/sessions-cli/reader';
 interface ShareOptions {
     public?: boolean;
     slug?: string;
@@ -9,15 +9,7 @@ interface ShareOptions {
     force?: boolean;
     cover?: boolean;
 }
-/** `session-<shortId>` — stable per session, so re-sharing updates the same URL. */
 export declare function defaultSessionSlug(session: SessionMeta): string;
-/**
- * Build the `artifacts share` argv for a session publish.
- *
- * Extracted so the mapping is testable directly. The security-relevant default
- * is `--visibility unlisted` — it inverts `artifacts share`'s public default, and
- * a test that re-implements this mapping would still pass with it flipped.
- */
 export declare function buildArtifactsShareArgs(session: SessionMeta, options: Pick<ShareOptions, 'public' | 'slug' | 'label' | 'expire' | 'force' | 'cover'>, file: string): string[];
 export declare function registerSessionsShareCommand(sessionsCmd: Command): void;
 export {};

package/dist/commands/sessions-share.js

@@ -1,19 +1,3 @@
-/**
- * `agents sessions share <id>` — publish one session transcript as a link.
- *
- * Renders the session locally — `renderSessionMarkdownDocument()` (redacted
- * transcript) and `renderSessionHtmlDocument()` (self-contained branded page) —
- * then publishes it through the standalone `artifacts` CLI (`artifacts share`),
- * the single home for artifact sharing since PHNX-3992. agents-cli holds no
- * share engine of its own; this command contributes the session-specific
- * rendering and redaction, and forwards the finished page to `artifacts share`.
- *
- * Unlisted by default, unlike `artifacts share` (public by default). A transcript
- * carries file paths, command output, error text, and whatever a tool printed —
- * strictly more than a plan does — so it does not belong in the public `/<user>`
- * gallery unless the operator asks for it with `--public`. The URL itself stays
- * world-readable: unlisted is a capability URL, not a secret.
- */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -22,7 +6,7 @@ import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
 import { knownSecretValuesFromEnv, redactEmails } from '../lib/redact.js';
 import { discoverSessions } from '../lib/session/discover.js';
-import { renderSessionHtmlDocument } from '../lib/session/share-html.js';
+import { renderSessionHtmlDocument } from '@phnx-labs/sessions-cli/reader';
 import { resolveArtifactsBin, invocation, ArtifactsClientError } from '../lib/artifacts-client.js';
 import { renderSessionMarkdownDocument } from './sessions-render.js';
 import { selectSessions } from './sessions-export.js';
@@ -32,17 +16,9 @@ function parseReasoning(value) {
         return value;
     throw new Error(`Unknown reasoning mode "${value}". Expected omit, fold, or include.`);
 }
-/** `session-<shortId>` — stable per session, so re-sharing updates the same URL. */
 export function defaultSessionSlug(session) {
     return `session-${session.shortId || session.id}`;
 }
-/**
- * Build the `artifacts share` argv for a session publish.
- *
- * Extracted so the mapping is testable directly. The security-relevant default
- * is `--visibility unlisted` — it inverts `artifacts share`'s public default, and
- * a test that re-implements this mapping would still pass with it flipped.
- */
 export function buildArtifactsShareArgs(session, options, file) {
     const args = [
         'share',
@@ -122,8 +98,6 @@ Manage published sessions with 'artifacts share list' and 'artifacts share delet
             process.exitCode = 1;
             return;
         }
-        // One link per share: several sessions in one page would give the reader no
-        // way to reference just the one that matters, and the slug could only name one.
         if (sessions.length > 1) {
             process.stderr.write(chalk.yellow(`"${selector}" matched ${sessions.length} sessions. Share one at a time — pass a full or unique session id.\n`));
             process.exitCode = 1;
@@ -136,22 +110,8 @@ Manage published sessions with 'artifacts share list' and 'artifacts share delet
             reasoning,
             knownSecrets: redact ? knownSecretValuesFromEnv() : undefined,
         });
-        // Emails on top of what the renderer masks. Almost every real transcript
-        // carries a few — git author addresses, `gh api user`, a pasted log — and
-        // `artifacts share` refuses a body containing any (its own scan). Masking
-        // them means the published page genuinely does not carry them; the
-        // alternative, telling people to pass --force, trains everyone to bypass the
-        // gate that also catches real credentials.
-        //
-        // Applied to the RENDERED PAGE, not the Markdown, so the text that is masked
-        // is exactly the text the publish scan will see. Markdown escaping stands
-        // between the two: `foo\@example.com` hides from the pattern in the Markdown
-        // and reappears as a live address once marked drops the backslash.
         const page = renderSessionHtmlDocument(session, markdown, { redacted: redact });
         const html = redact ? redactEmails(page) : page;
-        // A real file on disk is what `artifacts share` takes, and its OG capturer
-        // opens it in a browser. 0600 + a per-run directory keeps the intermediate
-        // off a world-readable /tmp path while it exists.
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-session-share-'));
         const file = path.join(dir, `${defaultSessionSlug(session)}.html`);
         try {
@@ -183,10 +143,6 @@ Manage published sessions with 'artifacts share list' and 'artifacts share delet
                 result = JSON.parse(proc.stdout);
             }
             catch {
-                // A 0 exit with non-JSON stdout (a version-skewed `artifacts` that
-                // printed a banner before the JSON, or one predating `--json` here) must
-                // fail loud with the bytes it actually returned, not an uncaught parse
-                // stack trace — mirroring `secrets-client.ts`'s `parseResponse`.
                 const preview = proc.stdout.trim().slice(0, 200);
                 process.stderr.write(chalk.red(`artifacts share returned a non-JSON response${preview ? `: ${preview}` : ' (empty output)'}\n`));
                 process.exitCode = 1;

package/dist/commands/sessions-stats.d.ts

@@ -1,34 +1,10 @@
-/**
- * `agents sessions stats` — precomputed resource-usage insights.
- *
- * The read side of #12: which skills and slash-commands do you actually invoke,
- * and which installed ones are dead weight? The write side already exists —
- * every scanned transcript's skill/`Skill`-tool + slash-command tallies land in
- * `session_resource_usage` at index time — so this is a cheap SQLite rollup, no
- * re-scan of history. A both-ends view: the most-invoked resources, and the
- * installed-but-never-invoked ones.
- *
- * Signal caveat, surfaced in help and output: only EXPLICIT invocations count
- * (slash commands + `Skill` tool calls). An auto-triggered skill (loaded by
- * description match) emits no event and reads as zero — "0" means "never
- * explicitly invoked", not "never loaded". Skill invocations are recorded for
- * Claude and Kimi (the `Skill`-tool harnesses); slash-commands are Claude-only;
- * other harnesses contribute nothing.
- */
 import type { Command } from 'commander';
-/** One installed resource, keyed the same way session_resource_usage stores it. */
 interface InstalledResource {
     kind: 'skill' | 'command';
     name: string;
     plugin: string | null;
     source: string | null;
 }
-/**
- * The both-ends "dead weight" set: installed resources whose identity
- * (kind + name — name already embeds `plugin:short`, so it matches the stored
- * invoked name) never appears in the invoked rows. Sorted kind then name.
- * Pure set-difference so it is unit-testable without touching the filesystem.
- */
 export declare function diffZeroInvoked(installed: InstalledResource[], invoked: Array<{
     kind: string;
     name: string;

package/dist/commands/sessions-stats.js

@@ -6,45 +6,20 @@ import { discoverPlugins } from '../lib/plugins/plugins.js';
 import { setHelpSections } from '../lib/help.js';
 import { terminalWidth, truncateToWidth, padToWidth, stringWidth } from '../lib/session/width.js';
 const DEFAULT_TOP = 20;
-/**
- * The recorded-set the zero-counts must be read against (PHNX-2301). A resource
- * only records an EXPLICIT invocation from a harness that emits the event:
- * `Skill` tool calls come from Claude + Kimi, slash-commands from Claude only
- * (`SKILL_TOOL_NAME_BY_AGENT` in `lib/session/highlights.ts`, slash-command
- * parsing in `lib/session/parse.ts`). A session under any other harness — or an
- * auto-triggered skill, which emits no event on any harness — contributes
- * nothing, so its resources read as 0 whether or not they were used. Keep these
- * in lockstep with the writer: widening them here without a verified transcript
- * tool-name would make the caveat lie about coverage it does not have.
- */
 const RECORDING_SKILL_HARNESSES = ['claude', 'kimi'];
 const RECORDING_COMMAND_HARNESSES = ['claude'];
-/**
- * The both-ends "dead weight" set: installed resources whose identity
- * (kind + name — name already embeds `plugin:short`, so it matches the stored
- * invoked name) never appears in the invoked rows. Sorted kind then name.
- * Pure set-difference so it is unit-testable without touching the filesystem.
- */
 export function diffZeroInvoked(installed, invoked) {
     const invokedKeys = new Set(invoked.map(r => `${r.kind}:${r.name}`));
     return installed
         .filter(r => !invokedKeys.has(`${r.kind}:${r.name}`))
         .sort((a, b) => (a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind.localeCompare(b.kind)));
 }
-/**
- * Enumerate the installed resource set the invoked rows are measured against:
- * flat skills/commands from the DotAgents layers (`listResources`) plus each
- * plugin's own skills/commands as `plugin:short` (invisible to the flat scan) —
- * exactly the union `resolveResourceProvenance` reconciles against at write time.
- */
 function installedResources(kindFilter, pluginFilter, cwd) {
     const kinds = kindFilter ? [kindFilter] : ['skill', 'command'];
     const byKey = new Map();
     const plugins = discoverPlugins({ cwd });
     for (const kind of kinds) {
         const listKind = kind === 'skill' ? 'skills' : 'commands';
-        // Flat (non-namespaced) resources are plugin-less; skip them when the caller
-        // narrows to one plugin.
         if (!pluginFilter) {
             for (const r of listResources(listKind, cwd)) {
                 byKey.set(`${kind}:${r.name}`, { kind, name: r.name, plugin: null, source: r.source });
@@ -105,16 +80,10 @@ export function registerSessionsStatsCommand(sessionsCmd) {
     });
 }
 async function statsAction(cmd) {
-    // The parent `sessions` command owns --agent/--project/--plugin/--since/--json
-    // and keeps parsing them past the subcommand name (it has a positional
-    // [query]), binding them to the PARENT — so read the merged view, not the
-    // action's own options. Same reason sessions-bookmark.ts uses optsWithGlobals.
     const opts = cmd.optsWithGlobals();
     const kind = normalizeKind(opts.kind);
     const sinceMs = opts.since ? parseTimeFilter(opts.since) : undefined;
     const top = resolveTop(opts.top);
-    // Warm the incremental index (like `agents insights cost`) so recent sessions' usage is
-    // current before we read. Historical gaps still need the explicit backfill.
     await discoverSessions({ all: true, since: opts.since, limit: 1 });
     const filter = {};
     if (opts.agent)
@@ -131,8 +100,6 @@ async function statsAction(cmd) {
         pluginFilter: opts.plugin,
         order: opts.bottom ? 'bottom' : 'top',
     };
-    // Full invoked set (no limit) drives both the zero-invoked diff and the totals;
-    // the ranked view is a slice of it.
     const allInvoked = queryResourceUsageStats(statsOpts);
     const ranked = top > 0 ? allInvoked.slice(0, top) : allInvoked;
     const installed = installedResources(kind, opts.plugin, process.cwd());
@@ -155,19 +122,12 @@ async function statsAction(cmd) {
             signal: {
                 explicitOnly: true,
                 note: 'Explicit invocations only (slash commands + Skill tool calls). Auto-triggered skills emit no event and read as 0. Skill invocations are recorded for Claude and Kimi; slash-commands for Claude only.',
-                // Structured recorded-set so a machine consumer can tell a zero from a
-                // non-recording harness apart from a genuine non-use (PHNX-2301): a
-                // zeroInvoked resource may simply have been auto-triggered, or only
-                // used under a harness not in these sets.
                 recording: {
                     skills: RECORDING_SKILL_HARNESSES,
                     commands: RECORDING_COMMAND_HARNESSES,
                 },
             },
             coverage: {
-                // sessionsWithUsage/sessionsIndexed kept for the SES-IF-4b envelope
-                // contract; sessionsScanned is the honest backfill-coverage numerator
-                // (ledger rows), distinct from the absolute sessionsWithUsage count.
                 sessionsWithUsage: coverage.covered,
                 sessionsScanned: coverage.scanned,
                 sessionsIndexed: coverage.total,
@@ -235,17 +195,12 @@ function renderHuman(args) {
     out.push(chalk.bold('Resource usage') +
         chalk.gray(`  ·  ${allInvokedCount} invoked · ${totalInvocations} invocation${totalInvocations !== 1 ? 's' : ''}` +
             (scopeBits.length ? `  ·  ${scopeBits.join(' · ')}` : '')));
-    // Scan coverage (ledger) is the honest "has the backfill folded in history?"
-    // signal and drives the hint; sessionsWithUsage is an ABSOLUTE count of sessions
-    // carrying ≥1 explicit invocation, which stays small at full scan coverage
-    // because most sessions invoke nothing (PHNX-2301).
     out.push(chalk.gray(`  coverage: ${coverage.scanned}/${coverage.total} sessions scanned · ${coverage.covered} carry an explicit invocation`) +
         (coverage.total > 0 && coverage.scanned / coverage.total < 0.5
             ? chalk.yellow('  — run `agents sessions backfill resources` to fold in history')
             : ''));
     out.push(chalk.gray('  signal: explicit invocations only (slash commands + Skill tool); auto-triggered skills read as 0; skills from Claude+Kimi, slash-commands Claude-only'));
     out.push('');
-    // Ranked section (skipped by --zero).
     if (!opts.zero) {
         const heading = opts.bottom ? 'Least invoked' : 'Most invoked';
         out.push(chalk.bold(heading));
@@ -257,10 +212,6 @@ function renderHuman(args) {
         }
         out.push('');
     }
-    // Zero-invoked section (the dead weight). "Never invoked" is scoped to the
-    // recorded set: never EXPLICITLY invoked under a recording harness (skills
-    // Claude+Kimi, commands Claude-only) — it may still have been auto-triggered or
-    // used under another harness, which is why this is dead-weight EVIDENCE, not proof.
     out.push(chalk.bold('Installed but never explicitly invoked') + chalk.gray(`  (${zeroInvoked.length})`));
     if (zeroInvoked.length === 0) {
         out.push(chalk.gray('  (every installed resource has at least one explicit invocation in this window)'));

package/dist/commands/sessions-stop.d.ts

@@ -1,21 +1,2 @@
-/**
- * `agents sessions stop <id>` — end a live agent session outright: stop its
- * interactive process and tear down its tmux/mux session, so the session becomes
- * done/closed rather than an orphaned idle background process.
- *
- * The lifecycle sibling of `detach` that does NOT resume headless. `detach`
- * backgrounds a still-wanted agent (stop the terminal, keep it working); `stop`
- * is for when the work is over — the agent's editor tab was closed, or you want
- * it gone. Both reuse the same live-session resolution and the same
- * `stopInteractive` teardown (tmux `kill-session`, else SIGTERM→SIGKILL the pid),
- * so a session killed here reaps its helpers exactly as `detach` does before it
- * resumes.
- *
- * The primary caller is AGI EXT: when a user genuinely closes an agent tab
- * (Cmd+W), the extension runs this so the underlying agent + its mux are shut
- * down instead of being left running detached (the "Cmd+W orphans an idle
- * session" bug). A window RELOAD does NOT call this — the extension distinguishes
- * the two via `terminal.exitStatus.reason` and only a real user close tears down.
- */
 import type { Command } from 'commander';
-export declare function registerSessionsStopCommand(program: Command): void;
+export declare function registerSessionsStopCommand(program: Command, group?: 'sessions' | 'ps'): void;

package/dist/commands/sessions-stop.js

@@ -4,7 +4,7 @@ import { resolveDetachTarget, resolveOne } from './detach-core.js';
 import { stopInteractive } from './detach.js';
 import { runOnPeer } from '../lib/session/remote-list.js';
 import { setHelpSections } from '../lib/help.js';
-export function registerSessionsStopCommand(program) {
+export function registerSessionsStopCommand(program, group = 'sessions') {
     const cmd = program
         .command('stop')
         .argument('<id>', 'Short or full id of the live session to stop')
@@ -16,14 +16,14 @@ export function registerSessionsStopCommand(program) {
     setHelpSections(cmd, {
         examples: `
       # Stop a live session by a short id prefix
-      agents sessions stop 4b2f1a9c
+      agents ${group} stop 4b2f1a9c
 
       # Only look on this machine (skip the fleet sweep)
-      agents sessions stop 4b2f1a9c --local
+      agents ${group} stop 4b2f1a9c --local
     `,
         notes: `
       stop ENDS the session; it does not background it. To keep an agent working
-      unattended instead, use \`agents sessions detach <id>\`, and bring it back
+      unattended instead, use \`agents ${group} detach <id>\`, and bring it back
       with \`agents sessions resume <id>\`.
 
       A session that lives on another machine is stopped THERE over SSH — its pid
@@ -41,16 +41,12 @@ async function stopSessionAction(id, opts = {}) {
     }
     const s = resolved;
     const target = resolveDetachTarget(s, self);
-    // Cloud/team/id-less sessions have their own lifecycles — refuse rather than
-    // half-stopping one from here (same boundary `detach` enforces).
     if (target.kind === 'refuse') {
         console.error(chalk.red(target.reason));
         process.exitCode = 1;
         return;
     }
     const short = target.sessionId.slice(0, 8);
-    // A session on another host: its pid/tmux socket only mean something where it
-    // runs, so stop it THERE over SSH — never kill locally. Mirrors detach/focus.
     if (target.kind === 'remote') {
         console.log(chalk.gray(`${short} lives on ${target.machine} — stopping it there over SSH…`));
         const rc = await runOnPeer(['sessions', 'stop', target.sessionId, '--local'], target.machine);
@@ -60,7 +56,6 @@ async function stopSessionAction(id, opts = {}) {
         }
         return;
     }
-    // Local: end the interactive process and tear down its tmux/mux session.
     await stopInteractive(s);
     console.log(chalk.green(`■ Stopped ${s.kind} ${short}`) + chalk.gray(' — process ended, session closed.'));
 }