@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/fleet-capture.js

@@ -1,14 +1,3 @@
-/**
- * `agents fleet capture` (alias surface of `agents devices capture`) — snapshot
- * the live environment into the `fleet:` block of `agents.yaml` so a fresh
- * machine can reconstruct it with `agents fleet apply`.
- *
- * Local-read + local-write, zero SSH. Records device NAMES only (never IPs or
- * usernames — those are re-resolved live from Tailscale at apply-time), plus the
- * source's own agents as defaults, browser profiles, secrets-bundle names, and
- * routine names. The heavy lifting is the pure `captureFleet` builder; this
- * command just gathers inputs and persists via `updateMeta`.
- */
 import * as fs from 'fs';
 import chalk from 'chalk';
 import * as yaml from 'yaml';
@@ -18,11 +7,6 @@ import { machineId } from '../lib/machine-id.js';
 import { listBundles, SecretsClientError } from '../lib/secrets-client.js';
 import { listJobs } from '../lib/scheduling/routines.js';
 import { captureFleet } from '../lib/fleet/capture.js';
-/** Read THIS machine's pins file into `name -> [id@latest]`. Only used with
- * `--from-pins`; keeps capture zero-SSH by reading local state. Pins are
- * machine-local runtime state (`.history/devices/pins-<host>.json`, untracked)
- * — peer pins never sync, so only this machine contributes; peers inherit the
- * captured fleet defaults. */
 function agentsFromPins(names) {
     const self = machineId();
     if (!names.includes(self))
@@ -32,18 +16,11 @@ function agentsFromPins(names) {
         pins = JSON.parse(fs.readFileSync(getDevicePinsPath(), 'utf-8'));
     }
     catch {
-        return {}; // no pins file (or unparsable) — capture is best-effort
+        return {};
     }
     const ids = pins?.agents ? Object.keys(pins.agents) : [];
     return ids.length > 0 ? { [self]: ids.map((id) => `${id}@latest`) } : {};
 }
-/**
- * The names to snapshot into `fleet.secretsBundles` — best-effort. Capture's
- * primary job (device/agent/routine snapshot) is unrelated to secrets, so a
- * missing standalone `secrets` install (DIST-1: no fallback engine) degrades
- * this ONE optional field to empty with a warning rather than failing the
- * whole capture. A real store error still surfaces.
- */
 async function captureSecretsBundleNames() {
     try {
         return (await listBundles()).map((b) => b.name);
@@ -58,7 +35,6 @@ async function captureSecretsBundleNames() {
 }
 async function runCapture(opts) {
     const meta = readMeta();
-    // Roster: every registered device name.
     const registry = await loadDevices();
     let names = Object.values(registry)
         .map((d) => d.name)
@@ -67,13 +43,10 @@ async function runCapture(opts) {
         names = names.filter((n) => n === opts.device);
         if (names.length === 0)
             throw new Error(`Device '${opts.device}' is not a registered device.`);
-        // --from-pins reads the LOCAL pins file only (peer pins are machine-local
-        // runtime state and never sync), so targeting a peer would record nothing.
         if (opts.fromPins && opts.device !== machineId()) {
             throw new Error(`--from-pins can only read THIS machine's pins ('${machineId()}') — peer pins are machine-local and never sync. Run it on '${opts.device}' itself, or drop --device.`);
         }
     }
-    // Defaults seeded from the source machine's own installed agents.
     const sourceAgents = Object.keys(meta.agents ?? {}).sort();
     const defaults = {
         agents: sourceAgents.map((id) => `${id}@latest`),
@@ -84,19 +57,9 @@ async function runCapture(opts) {
         devices: names,
         defaults,
         agentsByDevice: opts.fromPins ? agentsFromPins(names) : undefined,
-        // Browser profiles are intentionally NOT captured — the central `browser:`
-        // block already syncs via the repo, and its ssh:// endpoints can carry
-        // `user@host`, which must never be copied into the fleet: block.
         secretsBundles: await captureSecretsBundleNames(),
         routines: listJobs().map((j) => j.name),
     };
-    // Discovery decisions and dismissals are device-scoped now (PHNX-3315): they
-    // live in each box's device doc and sync via the repo, so `capture` must NOT
-    // hoist the cross-box union back into the shared `agents.yaml` `fleet:` block
-    // (that would recreate the N-boxes-rewrite-one-map conflict Task A removed and
-    // re-arm the fold-then-delete migration on every capture). `meta.fleet` carries
-    // only the roster/defaults; any lingering central-legacy discovery/ignored is
-    // carried forward verbatim and drained by the migration.
     const next = captureFleet(meta.fleet, inputs);
     if (opts.dryRun) {
         console.log(chalk.gray('# agents.yaml fleet: block (dry run — not written)'));
@@ -110,7 +73,6 @@ async function runCapture(opts) {
             `${inputs.secretsBundles?.length ?? 0} secret bundle(s), ${inputs.routines?.length ?? 0} routine(s).`));
     console.log(chalk.gray('  Wrote agents.yaml → fleet:. Push it (`agents repo push`) and run `agents fleet apply` on any machine.'));
 }
-/** Attach `capture` to the `devices`/`fleet` command tree. */
 export function registerFleetCaptureCommand(devicesCmd) {
     devicesCmd
         .command('capture')

package/dist/commands/focus.d.ts

@@ -1,38 +1,11 @@
-/**
- * `agents sessions focus [id]` — take me to a live session, however it's reachable.
- *
- * Same detection as `go`, but where `go` *refuses* an un-attachable session,
- * `focus` **opens a new tab and resumes it** — locally, or on the remote over SSH
- * (via the terminal launch engine's `openSurfaces`, `host` = the peer). So:
- *   - in tmux (local/remote)   -> attach the live pane (join it, no fork)
- *   - in Ghostty               -> focus its tab
- *   - headless / plain / etc.  -> new tab + `resume` (a copy if it's mid-run — the
- *                                  original keeps going; a clean continue if it's idle)
- *
- * NOTE: joining a live process without forking is only possible via tmux — that's
- * why `--tmux`-wrapped launches are worth it for sessions you'll want back live.
- */
 import type { Command } from 'commander';
 import { probeAttachRail, type AttachRailLiveness, type UnreachableFallback } from './go.js';
 import { type ActiveSession } from '../lib/session/active.js';
-import { type SessionMeta } from '../lib/session/types.js';
+import { type SessionMeta } from '@phnx-labs/sessions-cli/reader';
 export { looksLikeTmuxAlias, resolveTmuxAliasState, shouldAttachLocalTmuxAliasBeforeFleet, type TmuxAliasState } from '../lib/session/local-tmux-attach.js';
-import { type LiveStatusFilter } from './sessions.js';
+import { type LiveStatusFilter } from './ps-roster.js';
 import { openSurfaces, type Backend } from '../lib/terminal/index.js';
-/** Options for `sessions focus` — device scope + the `--active` live-state filters. */
 interface FocusOptions {
-    /**
-     * Resolve the target from the launcher's AGENT_LAUNCH_ID instead of a session
-     * id (RUSH-3125).
-     *
-     * A `--device` launcher mints this id BEFORE it opens the connection and
-     * forwards it, so it is the one handle that is still known after the link
-     * dies. A session id is not: only Claude is handed one up front, and every
-     * other harness's real id had to be read back off the peer — over the very
-     * link that just dropped — which is why a blink left a Grok or Codex tab with
-     * nothing to reconnect to. The lookup runs HERE, on the box that owns the hook
-     * records, so it needs no network at the moment it is needed most.
-     */
     launchId?: string;
     local?: boolean;
     attachOnly?: boolean;
@@ -70,59 +43,20 @@ interface FocusOptions {
     unknown?: boolean;
     reconnectReattach?: boolean;
 }
-/** Commander gives overlapping `sessions` flags to the parent command, even
- * when they appear after `focus`. Fold only values explicitly provided there
- * into the child options; child defaults (limit/sort) otherwise stay intact. */
 export declare function inheritFocusOptions(child: FocusOptions, parent?: Command): FocusOptions;
-/** Collect device targets from `--device`; repeatable. Returns a host list. */
 export declare function mergeFocusHosts(opts: FocusOptions): string[];
-/** Picker header that reflects the active filter + device, e.g. "Focus orphaned sessions on yosemite-s0:". */
 export declare function focusHeader(statuses: LiveStatusFilter[], hosts: string[]): string;
-export declare function registerFocusCommand(program: Command): void;
-/**
- * Which fallback fires when a session has no attach rail. `--attach-only` (the old
- * `go`) refuses; the default opens a new tab and resumes a copy. Pure so it's testable
- * without touching `jumpTo`'s side effects.
- */
+export declare function registerFocusCommand(program: Command, opts?: {
+    group?: 'sessions' | 'ps';
+    hidden?: boolean;
+}): void;
 export declare function selectFallback(attachOnly: boolean | undefined): UnreachableFallback;
 export declare function focusAction(id: string | undefined, opts: FocusOptions): Promise<void>;
-/** A retained pane is not attachable merely because tmux can still display it. */
 export declare function isAttachableLiveSession(session: ActiveSession): boolean;
-/**
- * Collapse rows that are the SAME logical session.
- *
- * A transcript syncs across the fleet, so one session appears once per machine
- * holding a copy. SES-IF-2a: "Synced copies sharing the same full id MUST count
- * as one logical session." `fleetCandidatesByQuery` already groups this way, but
- * this path filtered raw rows instead — so `focus <full-uuid>` answered
- * "is ambiguous (2 sessions). Use more of the id." with no longer id to give.
- * Measured on zion: one of the two rows had no transcript at all
- * ("Session transcript not available (file no longer exists). Path: ").
- */
 export declare function dedupeSessionsByLogicalId(rows: SessionMeta[], self?: string): SessionMeta[];
-/**
- * The session to focus once an id/identity selector has resolved across the
- * fleet. Prefer the already-gathered candidate-pool row (it carries the live
- * status collected for the picker), but fall back to the resolver's own metadata
- * when the resolved session is not in the filtered pool — a peer-owned, older, or
- * other-project session that the display filters excluded. Returning the resolved
- * session there (instead of rejecting it) is what lets `focus <id>` reach a
- * peer-owned session without `--device`, matching `resume`/`preview`.
- */
 export declare function focusTargetForResolved(poolMatch: SessionMeta | undefined, resolved: SessionMeta): SessionMeta;
 export declare function focusResolvedSession(meta: SessionMeta, liveById: Map<string, ActiveSession>, self: string, fallback: UnreachableFallback, attachOnly: boolean, reconnectReattach?: boolean): Promise<void>;
-/** Focus one row selected by the shared session browser through the same
- * attach/recover decision as `agents sessions focus <id>`. */
 export declare function focusSelectedSession(meta: SessionMeta, active: ActiveSession | undefined, self: string): Promise<void>;
-/**
- * How a single selected live session opens in its new tab.
- *  - `attach` — a live tmux pane joined in the tab (a second client, no fork),
- *    local (`sh -c`) or remote (`ssh -tt`). tmux is the only rail that can be
- *    *joined* without forking (see the file header).
- *  - `resume` — no attach rail, so resume a copy in the tab (the original keeps
- *    running); never a silent drop.
- *  - `skip` — not resumable AND no rail: reported, not dropped.
- */
 type FocusSurfacePlan = {
     kind: 'attach';
     command: string[];
@@ -135,40 +69,18 @@ type FocusSurfacePlan = {
     kind: 'skip';
     note: string;
 };
-/**
- * Shell that resolves a tmux pane to its session and attaches it — the exact form
- * `jumpTo` uses, minus the pre-select-window nicety, so a batch tab joins the live
- * session (a second client) without forking. Reused for local and (wrapped in ssh)
- * remote panes.
- */
 export declare function tmuxAttachScript(mux: {
     socket?: string;
     pane: string;
 }): string;
-/**
- * Decide how one live session opens as a tab. Pure over the session + a
- * `resumeCommandFor` resolver (injected so the local version-pinned resume command
- * and the tests stay decoupled from `discoverSessions`).
- */
 export declare function planFocusSurface(s: ActiveSession, self: string, resumeCommandFor: (s: ActiveSession) => string[] | null, rail?: AttachRailLiveness): FocusSurfacePlan;
-/** The engine seam — real `openSurfaces`, overridable in tests to assert the tab requests. */
 type OpenSurfacesFn = typeof openSurfaces;
-/** Test seams for `openFocusTabs`: inject the engine boundary + force a backend. */
 interface OpenFocusTabsDeps {
     open?: OpenSurfacesFn;
-    /** Skip `resolveBackend` (which needs a live terminal) when set — tests pass 'tmux'. */
     backend?: Backend | 'inplace';
-    /** Rich rows selected by the shared browser pipeline (including remote history). */
     metas?: SessionMeta[];
-    /** Liveness boundary; production probes tmux, tests exercise planning deterministically. */
     probe?: typeof probeAttachRail;
-    /** Strict focus mode: open living attach rails only; never recover a copy. */
     attachOnly?: boolean;
 }
-/**
- * Open each selected live session as a tab: attach its live pane where one exists,
- * else resume a copy. Reuses `resume`'s backend resolution + flood guard.
- */
 export declare function openFocusTabs(targets: ActiveSession[], self: string, deps?: OpenFocusTabsDeps): Promise<void>;
-/** Minimal SessionMeta for a live session, enough for `buildResumeCommand` + placement. */
 export declare function metaFromActive(s: ActiveSession): SessionMeta;