@phnx-labs/agents-cli 1.20.91 → 1.20.92

package/dist/commands/doctor.js

@@ -12,7 +12,7 @@ import { getCliVersion } from '../lib/version.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { sshExecAsync } from '../lib/ssh-exec.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
-import { machineId } from '../lib/session/sync/config.js';
+import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import chalk from 'chalk';
 import { checkAllClis, collectTeamsDoctorData } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, getAccountInfo } from '../lib/agents.js';
@@ -101,7 +101,9 @@ async function resolveFleetTargets(opts) {
     const registry = await loadDevices();
     const localName = machineId();
     return Object.values(registry)
-        .filter((d) => d.name.toLowerCase() !== localName)
+        // Normalize names so zion/ZION/zion.local all match machineId() and we never
+        // self-SSH the local box during fleet probes (RUSH-2114).
+        .filter((d) => normalizeHost(d.name) !== localName)
         // Control devices (a cockpit) never run agents — skip them in the fleet
         // fan-out (an explicit --device <name> still resolves above).
         .filter((d) => !isControlDevice(d))

package/dist/commands/exec.d.ts

@@ -16,6 +16,20 @@ export interface RunAccountPickerRequest {
 /** Distinguish a terminal account-picker marker from an explicit @version pin. */
 export declare function parseRunAccountPickerRequest(agentSpec: string): RunAccountPickerRequest;
 /** Return every option whose routing semantics conflict with a local account choice. */
+/**
+ * The `--host` alias family — the flags that mean "dispatch this run to another
+ * machine over SSH". `--host` is canonical; `--device`/`--on`/`--computer` are
+ * aliases. Returns the values actually given (so callers can both test presence
+ * and read the target). Kept in ONE place because a guard that listed only a
+ * subset silently let `--terminal --device` open a local tab and drop the remote
+ * target — the drift this predicate exists to prevent.
+ */
+export declare function hostTargetGiven(options: {
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+}): string[];
 export declare function runAccountPickerConflicts(options: {
     resume?: string | boolean;
     strategy?: string;

package/dist/commands/exec.js

@@ -34,6 +34,17 @@ export function parseRunAccountPickerRequest(agentSpec) {
     };
 }
 /** Return every option whose routing semantics conflict with a local account choice. */
+/**
+ * The `--host` alias family — the flags that mean "dispatch this run to another
+ * machine over SSH". `--host` is canonical; `--device`/`--on`/`--computer` are
+ * aliases. Returns the values actually given (so callers can both test presence
+ * and read the target). Kept in ONE place because a guard that listed only a
+ * subset silently let `--terminal --device` open a local tab and drop the remote
+ * target — the drift this predicate exists to prevent.
+ */
+export function hostTargetGiven(options) {
+    return [options.host, options.device, options.on, options.computer].filter((v) => !!v);
+}
 export function runAccountPickerConflicts(options) {
     const conflicts = [];
     if (options.resume !== undefined)
@@ -46,7 +57,7 @@ export function runAccountPickerConflicts(options) {
         conflicts.push('--lease');
     if (options.box)
         conflicts.push('--box');
-    if (options.host || options.device || options.on || options.computer)
+    if (hostTargetGiven(options).length)
         conflicts.push('--host/--device');
     return conflicts;
 }
@@ -349,6 +360,121 @@ export async function runWorkflowForEach(spec, opts) {
     process.stderr.write(chalk.yellow(`[for_each] stopped by ${result.stoppedBy} after ${result.waves} waves. Team: ${team}\n`));
     return 1;
 }
+/**
+ * The run's working directory from `--cwd` / `--project`. `--project <slug>` owns
+ * the directory and is mutually exclusive with `--cwd`/`--remote-cwd`; both the
+ * main dispatch and the `--terminal` handoff need the same answer, so the rule
+ * and its error live here once instead of in two places that can drift.
+ */
+async function resolveRunCwd(options, opts) {
+    if (!options.project)
+        return options.cwd;
+    if (options.cwd || options.remoteCwd) {
+        console.error(chalk.red('Pass --project alone — not with --cwd or --remote-cwd.'));
+        process.exit(1);
+    }
+    const { resolveProjectRef } = await import('../lib/project-root.js');
+    try {
+        return await resolveProjectRef(options.project, { forRemote: opts.forRemote });
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+}
+/**
+ * `--terminal`: hand this run to a real terminal tab and exit.
+ *
+ * The terminal is detected from the user's live sessions, so a run started from
+ * a surface that cannot host a TUI (the menu bar's "New Session", a script) lands
+ * in the terminal they actually work in instead of a hardcoded Terminal.app.
+ * Exits non-zero when no terminal could be opened — the caller must not believe
+ * a session started when none did.
+ */
+async function handleTerminalHandoff(agentSpec, options, prompt) {
+    const { parseTerminalFlag, openRunInTerminal, toHostSamples } = await import('../lib/terminal/run-surface.js');
+    const { currentContext } = await import('../lib/terminal/index.js');
+    const parsed = parseTerminalFlag(options.terminal);
+    if (parsed.error) {
+        console.error(chalk.red(parsed.error));
+        process.exit(1);
+    }
+    // Reject an unrunnable target HERE, where the person can read it. The tab would
+    // otherwise open, print the same error, and close — the failure lands in a
+    // window that is gone before it can be read, which reads as "nothing happened".
+    //
+    // `agents run <thing>` takes an agent id, a PROFILE, or a WORKFLOW (see the
+    // isValidAgent / profileExists / resolveWorkflowRef chain below), so this must
+    // accept all three. Gating on the agent table alone rejected every profile —
+    // the whole Kimi/DeepSeek/Qwen/GLM path — for `--terminal` runs only.
+    const rawTarget = parseRunAccountPickerRequest(agentSpec).normalizedAgentSpec.split('@')[0];
+    const knownAgent = resolveAgentName(rawTarget);
+    if (knownAgent && isAgentHardDeprecated(knownAgent)) {
+        console.error(chalk.red(hardDeprecationError(knownAgent)));
+        process.exit(1);
+    }
+    if (!knownAgent) {
+        const [{ profileExists }, { resolveWorkflowRef }] = await Promise.all([
+            import('../lib/profiles.js'),
+            import('../lib/workflows.js'),
+        ]);
+        const probeCwd = options.cwd ?? process.cwd();
+        if (!profileExists(rawTarget) && !resolveWorkflowRef(rawTarget, probeCwd)) {
+            console.error(chalk.red(`Unknown agent, profile, or workflow: ${rawTarget}. See \`agents list\` for the installed harnesses.`));
+            process.exit(1);
+        }
+    }
+    // --host and its aliases (--device/--on/--computer) all mean "dispatch this
+    // run to another machine over SSH", which is incompatible with opening a
+    // terminal tab on THIS machine — so reject the whole alias family, not just
+    // the canonical flag. The rule and its wording live once, in the --host
+    // forwarding table, so the classification a reviewer reads and the error a
+    // user sees can't drift.
+    if (hostTargetGiven(options).length) {
+        const { RUN_OPTION_REJECT_MESSAGES } = await import('../lib/hosts/remote-cmd.js');
+        console.error(chalk.red(RUN_OPTION_REJECT_MESSAGES.terminal));
+        process.exit(1);
+    }
+    // Machine-readable output would land in the tab, where the caller that asked
+    // for it can never read it. Same class of failure as --host: refuse, don't
+    // hand back a stream that goes nowhere.
+    const streamFlag = options.json ? '--json' : options.emitSessionId ? '--emit-session-id' : undefined;
+    if (streamFlag) {
+        console.error(chalk.red(`${streamFlag} streams to stdout, but --terminal moves the run into a tab where you cannot read it. Drop one.`));
+        process.exit(1);
+    }
+    // `--project` owns the working directory, but the main action resolves it far
+    // below this handoff — so without this the tab would open in THIS process's
+    // cwd (launchd's `/` for a menu-bar click) while the run inside it moved to
+    // the project. `forRemote: false` because --terminal is always local (--host
+    // is rejected above).
+    const cwd = await resolveRunCwd(options, { forRemote: false });
+    const { getActiveSessions } = await import('../lib/session/active.js');
+    let sessions = [];
+    try {
+        sessions = await toHostSamples(await getActiveSessions());
+    }
+    catch {
+        // Detection is best-effort — an unreadable session index must not block the
+        // launch; resolution falls through to the available-backend floor.
+    }
+    const result = await openRunInTerminal({
+        argv: process.argv.slice(2),
+        forced: parsed.backend,
+        consumedValue: typeof options.terminal === 'string' ? options.terminal : undefined,
+        cwd: cwd ?? process.cwd(),
+        sessions,
+        ctx: currentContext(),
+    });
+    if (!result.ok) {
+        console.error(chalk.red(`Could not open a terminal: ${result.error ?? 'unknown error'}`));
+        process.exit(1);
+    }
+    if (!options.quiet) {
+        const what = prompt === undefined ? 'session' : 'run';
+        console.log(chalk.gray(`Opened the ${what} in ${result.description}.`));
+    }
+}
 /** Register the `agents run <agent> [prompt]` command. */
 export function registerRunCommand(program) {
     const runCmd = program
@@ -374,6 +500,7 @@ export function registerRunCommand(program) {
         .option('--session-id <id>', 'Force a NEW conversation to use this exact session UUID (Claude only). This CREATES a session — to resume an existing one, use --resume.')
         .option('--name <slug>', 'Name the run — seeds the session label so it shows up as `<name>` in `agents sessions` and resolves by it (and `agents hosts logs <name>` for --host runs) instead of an opaque id. An agent-generated title later refines the label; your name shows until then. Optional.')
         .option('--notify', 'Post a desktop notification when a headless run finishes. Fired by this process on exit, so it survives whatever launched the run (the menu bar dispatching it, a terminal you closed).')
+        .option('--terminal [backend]', "Open this run in a real terminal tab instead of here. Without a value the terminal is detected from your live sessions (`agents sessions --active` host), so it lands where you already work — Ghostty for a Ghostty user, iTerm for an iTerm user. Name one to force it: iterm | ghostty | terminal | tmux | vscodium-agent. This is how the menu bar's New Session opens.")
         .option('--verbose', 'Show detailed execution logs')
         .option('--raw', 'Interactive runs on macOS/Linux launch inside a shared tmux session (for %pane addressing + re-attach). Pass --raw to spawn the agent directly instead. Also disabled by AGENTS_NO_TMUX=1.')
         .option('--no-tmux', 'Spawn the agent directly instead of wrapping it in the shared tmux session. Same effect as --raw / AGENTS_NO_TMUX=1. Use this to see the agent\'s full startup output when a launch is failing.')
@@ -433,6 +560,11 @@ export function registerRunCommand(program) {
       # Pick a signed-in account/version for only this run
       agents run claude@
 
+      # Open the session in a terminal tab — detected from where your sessions
+      # already run (Ghostty / iTerm / Terminal.app); force one with a value
+      agents run claude --terminal
+      agents run claude --terminal ghostty
+
       # Pipe JSON events to a parser (--quiet drops the preamble)
       agents run claude "..." --json --quiet | jq
 
@@ -499,6 +631,15 @@ export function registerRunCommand(program) {
             // a native flag, not a prompt. Run interactively.
             prompt = undefined;
         }
+        // --terminal: this process can't host the TUI (a menu-bar click, a script),
+        // so hand the run to a real terminal and exit. Resolved from the user's own
+        // live sessions, so it opens where they already work. Done before every
+        // other dispatch path because the tab re-runs this same argv without the
+        // flag — arming --notify or picking a version here would happen twice.
+        if (options.terminal) {
+            await handleTerminalHandoff(agentSpec, options, prompt);
+            return;
+        }
         // --notify: post a desktop notification when this run finishes. Armed on
         // process exit so it covers EVERY dispatch path below (local, --host,
         // --lease, the error path) instead of one branch. Only for headless runs
@@ -906,24 +1047,13 @@ export function registerRunCommand(program) {
         }
         // --host/--on/--computer: offload this run onto a registered agent host
         // over SSH instead of running locally. The three flags are aliases.
-        const hostGiven = [options.host, options.device, options.on, options.computer].filter((v) => !!v);
+        const hostGiven = hostTargetGiven(options);
         // --project <slug>[@worktree]: resolve the projects-root shorthand into a
         // cwd. On a host run it resolves home-relative (`~/…`, so the host expands
         // it); locally it becomes an absolute path. It owns the working directory,
         // so it is mutually exclusive with both --cwd and --remote-cwd.
         if (options.project) {
-            if (options.cwd || options.remoteCwd) {
-                console.error(chalk.red('Pass --project alone — not with --cwd or --remote-cwd.'));
-                process.exit(1);
-            }
-            const { resolveProjectRef } = await import('../lib/project-root.js');
-            try {
-                options.cwd = await resolveProjectRef(options.project, { forRemote: hostGiven.length > 0 });
-            }
-            catch (err) {
-                console.error(chalk.red(err.message));
-                process.exit(1);
-            }
+            options.cwd = await resolveRunCwd(options, { forRemote: hostGiven.length > 0 });
         }
         if (hostGiven.length > 0) {
             if (new Set(hostGiven).size > 1) {

package/dist/commands/projects.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agents projects` — named, multi-repo projects and the progress
+ * rollup. Definitions live in `~/.agents/projects/<name>.yaml` (see
+ * `lib/projects.ts`); this registers the command tree over them. Beta-gated on
+ * `isBetaEnabled('projects')`, mirroring `agents factory`.
+ *
+ * The headline is `status`: instead of the vague per-agent activity line, it
+ * rolls every session up by project (matched on cwd) into one card — agents by
+ * lifecycle state, plan completion, open PRs, and tickets in flight.
+ */
+import type { Command } from 'commander';
+export declare function registerProjectsCommands(program: Command): void;

package/dist/commands/projects.js

@@ -0,0 +1,358 @@
+/**
+ * `agents projects` — named, multi-repo projects and the progress
+ * rollup. Definitions live in `~/.agents/projects/<name>.yaml` (see
+ * `lib/projects.ts`); this registers the command tree over them. Beta-gated on
+ * `isBetaEnabled('projects')`, mirroring `agents factory`.
+ *
+ * The headline is `status`: instead of the vague per-agent activity line, it
+ * rolls every session up by project (matched on cwd) into one card — agents by
+ * lifecycle state, plan completion, open PRs, and tickets in flight.
+ */
+import chalk from 'chalk';
+import * as fs from 'fs';
+import { execFileSync, spawnSync } from 'child_process';
+import { betaEnableHint, isBetaEnabled } from '../lib/beta.js';
+import { setHelpSections } from '../lib/help.js';
+import { getMainRepoRoot } from '../lib/git.js';
+import { parseOwnerRepoFromRemote } from '../lib/registry.js';
+import { toHomeRelative } from '../lib/project-root.js';
+import { getActiveSessions } from '../lib/session/active.js';
+import { factoryProjectsPath } from '../lib/auto-dispatch.js';
+import { listProjectDefs, loadProjectDef, writeProjectDef, removeProjectDef, projectDefPath, isSafeProjectName, } from '../lib/projects.js';
+import { rollupSessionsByProject, planPct, enrichProjectSignals, } from '../lib/project-status.js';
+/** `path:purpose` → a context anchor. Purpose may contain colons. */
+function parseContextFlag(raw) {
+    const i = raw.indexOf(':');
+    if (i === -1)
+        return { path: raw.trim(), purpose: '' };
+    return { path: raw.slice(0, i).trim(), purpose: raw.slice(i + 1).trim() };
+}
+/** Best-effort `owner/repo` from a repo's origin remote. */
+function originSlug(cwd) {
+    try {
+        const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd, encoding: 'utf8' }).trim();
+        return parseOwnerRepoFromRemote(url) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function statusBar(r) {
+    const parts = [];
+    const push = (n, label, color) => {
+        if (n && n > 0)
+            parts.push(color(`${n} ${label}`));
+    };
+    push(r.byStatus.running, 'running', chalk.green);
+    push(r.byStatus.idle, 'idle', chalk.gray);
+    push(r.byStatus.input_required, 'need-input', chalk.yellow);
+    push(r.byStatus.queued, 'queued', chalk.gray);
+    const shown = (r.byStatus.running ?? 0) + (r.byStatus.idle ?? 0) + (r.byStatus.input_required ?? 0) + (r.byStatus.queued ?? 0);
+    // Sessions in a non-live state (orphaned/crashed/unknown) count toward the
+    // headline — render the remainder so the bar never sums to less than it.
+    if (r.agents > shown)
+        parts.push(chalk.gray(`+${r.agents - shown} other`));
+    return parts.join(' · ') || chalk.gray('no live agents');
+}
+function renderCard(def, r, remote) {
+    const agents = r?.agents ?? 0;
+    const pct = r ? planPct(r.plan) : undefined;
+    const planStr = pct === undefined ? '' : `  ·  ${chalk.cyan(`${pct}% plan`)}`;
+    console.log(`${chalk.bold(def.name)}  ${chalk.dim('·')}  ${chalk.bold(`${agents} agents`)}${planStr}`);
+    if (def.description)
+        console.log(`  ${chalk.dim(def.description)}`);
+    console.log(`  ${chalk.dim('live')}     ${r ? statusBar(r) : chalk.gray('no live agents')}`);
+    const ships = [];
+    if (remote?.mergedPrs)
+        ships.push(chalk.green(`${remote.mergedPrs} merged (${remote.windowDays}d)`));
+    if (r?.openPrs.length)
+        ships.push(`${r.openPrs.length} open PR${r.openPrs.length === 1 ? '' : 's'}`);
+    if (r?.worktrees)
+        ships.push(`${r.worktrees} worktree${r.worktrees === 1 ? '' : 's'}`);
+    if (ships.length)
+        console.log(`  ${chalk.dim('ships')}    ${ships.join(' · ')}`);
+    if (r && r.tickets.length) {
+        console.log(`  ${chalk.dim('tickets')}  ${r.tickets.slice(0, 8).join(' · ')}${r.tickets.length > 8 ? ' …' : ''}`);
+    }
+    if (remote?.artifacts) {
+        const last = remote.lastArtifact ? `  ${chalk.dim(`· last: ${remote.lastArtifact}`)}` : '';
+        console.log(`  ${chalk.dim('proof')}    ${remote.artifacts} artifact${remote.artifacts === 1 ? '' : 's'} (${remote.windowDays}d)${last}`);
+    }
+    const repos = [def.repo, ...(def.repos ?? []).map((x) => x.slug)].filter(Boolean);
+    if (repos.length)
+        console.log(`  ${chalk.dim('repos')}    ${[...new Set(repos)].join(' · ')}`);
+    if (def.contexts?.length) {
+        console.log(`  ${chalk.dim('context')}  ${def.contexts.map((c) => c.path).join(' · ')}`);
+    }
+    if (def.integrations?.length) {
+        console.log(`  ${chalk.dim('links')}    ${def.integrations.map((i) => i.label ?? i.kind).join(' · ')}`);
+    }
+    console.log('');
+}
+export function registerProjectsCommands(program) {
+    const enabled = isBetaEnabled('projects');
+    const projects = program
+        .command('projects', { hidden: !enabled })
+        .description('Named multi-repo projects with a progress rollup.');
+    setHelpSections(projects, {
+        examples: `
+      agents projects add rush --repo phnx-labs/rush --path apps/web
+      agents projects list
+      agents projects status              # progress card for every project
+      agents projects status rush --json  # one project, machine-readable
+      agents run --project rush           # land an agent in the project
+    `,
+        notes: `
+      Definitions are hand-editable YAML in ~/.agents/projects/ and sync across
+      machines with 'agents push/pull'. Enable with: agents beta enable projects.
+    `,
+    });
+    projects.hook('preAction', () => {
+        if (enabled)
+            return;
+        console.error(chalk.red('agents projects is in beta.'));
+        console.error(chalk.gray(betaEnableHint('projects')));
+        process.exit(1);
+    });
+    // ---- list ----
+    projects
+        .command('list')
+        .description('List defined projects with their root, repo, and live agent count.')
+        .option('--json', 'Machine-readable output')
+        .action(async (opts) => {
+        const defs = listProjectDefs();
+        if (opts.json) {
+            const roll = rollupSessionsByProject(defs, await getActiveSessions());
+            console.log(JSON.stringify(defs.map((d) => ({ ...d, agents: roll.get(d.name)?.agents ?? 0 })), null, 2));
+            return;
+        }
+        if (!defs.length) {
+            console.log(chalk.gray('No projects defined. Add one: agents projects add <name>'));
+            return;
+        }
+        const roll = rollupSessionsByProject(defs, await getActiveSessions());
+        for (const d of defs) {
+            const agents = roll.get(d.name)?.agents ?? 0;
+            const repo = d.repo ?? d.repos?.[0]?.slug ?? '';
+            console.log(`  ${chalk.bold(d.name.padEnd(16))} ${chalk.dim((d.root ?? d.defaultPath ?? '').padEnd(32))} ${chalk.cyan(repo.padEnd(24))} ${agents} agents`);
+        }
+    });
+    // ---- add ----
+    projects
+        .command('add <name>')
+        .description('Define a project. Infers root and repo from the current git repo when not given.')
+        .option('--root <path>', 'Repo / monorepo root (defaults to the current git repo root)')
+        .option('--path <subdir>', 'Default cwd for agents (a monorepo subdir)')
+        .option('--repo <owner/repo>', 'Primary GitHub slug (defaults to the origin remote)')
+        .option('--context <path:purpose...>', 'A described starting point; repeatable')
+        .option('--linear <url-or-id>', 'Linear project URL or id')
+        .option('--force', 'Overwrite an existing definition')
+        .action(async (name, opts) => {
+        if (!isSafeProjectName(name)) {
+            console.error(chalk.red(`Invalid project name: "${name}" (letters, digits, ., _, - only)`));
+            process.exit(1);
+        }
+        if (loadProjectDef(name) && !opts.force) {
+            console.error(chalk.red(`Project "${name}" already exists. Use --force to overwrite, or 'agents projects edit ${name}'.`));
+            process.exit(1);
+        }
+        const cwd = process.cwd();
+        let root = opts.root;
+        if (!root) {
+            try {
+                root = toHomeRelative(await getMainRepoRoot(cwd));
+            }
+            catch {
+                console.error(chalk.red('Not inside a git repo — pass --root <path> explicitly.'));
+                process.exit(1);
+            }
+        }
+        const repo = opts.repo ?? originSlug(cwd);
+        const def = { name, root };
+        if (opts.path)
+            def.defaultPath = `${root.replace(/\/$/, '')}/${opts.path.replace(/^\//, '')}`;
+        if (repo)
+            def.repo = repo;
+        if (opts.context?.length)
+            def.contexts = opts.context.map(parseContextFlag);
+        if (opts.linear) {
+            def.linear = /^https?:/.test(opts.linear) ? { url: opts.linear } : { projectId: opts.linear };
+        }
+        const target = writeProjectDef(def);
+        console.log(chalk.green(`Defined project "${name}"`));
+        console.log(chalk.gray(`  ${target}`));
+        console.log(chalk.gray(`  root ${def.root}${def.repo ? `  ·  repo ${def.repo}` : ''}`));
+    });
+    // ---- show ----
+    projects
+        .command('show <name>')
+        .description('Show a project definition, resolved paths, repos, contexts, and links.')
+        .option('--json', 'Machine-readable output')
+        .action((name, opts) => {
+        const def = loadProjectDef(name);
+        if (!def) {
+            console.error(chalk.red(`No project named "${name}". List them: agents projects list`));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(def, null, 2));
+            return;
+        }
+        console.log(chalk.bold(def.name) + (def.description ? chalk.dim(`  — ${def.description}`) : ''));
+        if (def.root)
+            console.log(`  root         ${def.root}`);
+        if (def.defaultPath)
+            console.log(`  defaultPath  ${def.defaultPath}`);
+        const repos = [def.repo, ...(def.repos ?? []).map((r) => (r.subpath ? `${r.slug} (${r.subpath})` : r.slug))].filter(Boolean);
+        if (repos.length)
+            console.log(`  repos        ${repos.join(', ')}`);
+        for (const c of def.contexts ?? [])
+            console.log(`  context      ${chalk.cyan(c.path)} — ${c.purpose}`);
+        for (const i of def.integrations ?? [])
+            console.log(`  ${i.kind.padEnd(12)} ${i.url}${i.label ? chalk.dim(`  (${i.label})`) : ''}`);
+        if (def.linear?.url || def.linear?.projectId)
+            console.log(`  linear       ${def.linear.url ?? def.linear.projectId}`);
+        for (const d of def.docs ?? [])
+            console.log(`  doc          ${d}`);
+        console.log(chalk.gray(`  ${projectDefPath(name)}`));
+    });
+    // ---- edit ----
+    projects
+        .command('edit <name>')
+        .description('Open the project YAML in $EDITOR (it is hand-editable regardless).')
+        .action((name) => {
+        const target = projectDefPath(name);
+        if (!fs.existsSync(target)) {
+            console.error(chalk.red(`No project named "${name}". Create it: agents projects add ${name}`));
+            process.exit(1);
+        }
+        const editor = process.env.VISUAL || process.env.EDITOR || 'vi';
+        // $EDITOR commonly carries args ("code --wait") — split like monitors/routines do.
+        const parts = editor.split(/\s+/).filter(Boolean);
+        const res = spawnSync(parts[0], [...parts.slice(1), target], { stdio: 'inherit' });
+        process.exit(res.status ?? 0);
+    });
+    // ---- status ----
+    projects
+        .command('status [name]')
+        .description('Progress rollup: agents, plan %, merged/open PRs, tickets, and artifacts per project.')
+        .option('--json', 'Machine-readable output')
+        .option('--window <days>', 'Window for merged PRs and artifacts', '7')
+        .option('--no-remote', 'Skip the GitHub lookup (merged-PR count); faster, offline')
+        .action(async (name, opts) => {
+        const all = listProjectDefs();
+        // Named lookup goes through the strict single-def loader so a broken
+        // <name>.yaml surfaces its validation error instead of "No project named".
+        const defs = name ? [loadProjectDef(name)].filter((d) => d !== undefined) : all;
+        if (name && !defs.length) {
+            console.error(chalk.red(`No project named "${name}".`));
+            process.exit(1);
+        }
+        if (!defs.length) {
+            if (opts.json)
+                console.log('[]');
+            else
+                console.log(chalk.gray('No projects defined. Add one: agents projects add <name>'));
+            return;
+        }
+        const windowDays = Math.max(1, Number.parseInt(opts.window ?? '7', 10) || 7);
+        const nowMs = Date.now();
+        const roll = rollupSessionsByProject(all, await getActiveSessions());
+        // Enrich only the shown projects. --no-remote still reads the local artifact
+        // log but skips the gh call (def.repo left unused → mergedPrs stays 0).
+        const remote = new Map();
+        await Promise.all(defs.map(async (d) => {
+            remote.set(d.name, await enrichProjectSignals(d, windowDays, nowMs, { skipRemote: opts.remote === false }));
+        }));
+        if (opts.json) {
+            console.log(JSON.stringify(defs.map((d) => {
+                const r = roll.get(d.name);
+                const rem = remote.get(d.name);
+                return {
+                    name: d.name,
+                    agents: r?.agents ?? 0,
+                    byStatus: r?.byStatus ?? {},
+                    plan: r?.plan ?? { done: 0, total: 0 },
+                    planPct: r ? planPct(r.plan) ?? null : null,
+                    openPrs: r?.openPrs ?? [],
+                    mergedPrs: rem?.mergedPrs ?? 0,
+                    tickets: r?.tickets ?? [],
+                    worktrees: r?.worktrees ?? 0,
+                    artifacts: rem?.artifacts ?? 0,
+                    lastArtifact: rem?.lastArtifact ?? null,
+                    windowDays,
+                    repos: [d.repo, ...(d.repos ?? []).map((r2) => r2.slug)].filter(Boolean),
+                };
+            }), null, 2));
+            return;
+        }
+        for (const d of defs)
+            renderCard(d, roll.get(d.name), remote.get(d.name));
+    });
+    // ---- import ----
+    projects
+        .command('import')
+        .description('Absorb the Factory project registry (~/.agents/factory/projects.json) into YAML definitions.')
+        .requiredOption('--from-factory', 'Import from the Factory projects.json registry')
+        .option('--force', 'Overwrite existing definitions')
+        .action((opts) => {
+        const src = factoryProjectsPath();
+        let rawText;
+        try {
+            rawText = fs.readFileSync(src, 'utf8');
+        }
+        catch {
+            console.error(chalk.red(`No Factory registry at ${src}`));
+            process.exit(1);
+        }
+        let rows;
+        try {
+            rows = JSON.parse(rawText);
+        }
+        catch {
+            console.error(chalk.red(`Factory registry at ${src} is not valid JSON`));
+            process.exit(1);
+        }
+        const list = Array.isArray(rows) ? rows : Array.isArray(rows.projects) ? rows.projects : [];
+        let created = 0;
+        let skipped = 0;
+        for (const raw of list) {
+            if (!raw || typeof raw !== 'object')
+                continue;
+            const o = raw;
+            const name = typeof o.name === 'string' ? o.name : undefined;
+            if (!name || !isSafeProjectName(name)) {
+                skipped++;
+                continue;
+            }
+            if (loadProjectDef(name) && !opts.force) {
+                skipped++;
+                continue;
+            }
+            const def = { name };
+            if (typeof o.path === 'string')
+                def.root = toHomeRelative(o.path);
+            if (typeof o.repoSlug === 'string')
+                def.repo = o.repoSlug;
+            if (typeof o.linearProjectId === 'string')
+                def.linear = { projectId: o.linearProjectId };
+            writeProjectDef(def);
+            created++;
+        }
+        console.log(chalk.green(`Imported ${created} project${created === 1 ? '' : 's'}${skipped ? chalk.gray(` (${skipped} skipped)`) : ''}`));
+    });
+    // ---- rm ----
+    projects
+        .command('rm <name>')
+        .alias('remove')
+        .description('Delete a project definition. Never touches the repo.')
+        .action((name) => {
+        if (removeProjectDef(name)) {
+            console.log(chalk.green(`Removed project "${name}"`));
+        }
+        else {
+            console.error(chalk.red(`No project named "${name}".`));
+            process.exit(1);
+        }
+    });
+}

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

@@ -48,6 +48,21 @@ export declare function buildPreview(session: SessionMeta): string;
  * names the command that does report them instead.
  */
 export declare function formatTeamLineage(session: SessionMeta): string;
+/**
+ * The three timing facts the header reports: when the session was created, when
+ * it was last active, and how long it ran. Reads the parsed transcript when
+ * there is one and otherwise the indexed `SessionMeta`, so a remote or
+ * unindexed session — which has no local transcript to parse — still reports
+ * them instead of silently dropping the whole line.
+ *
+ * `lastActive` and `lasted` are omitted for a session whose whole life was under
+ * a minute: there they just restate `created`.
+ */
+export declare function extractTiming(session: Pick<SessionMeta, 'timestamp' | 'lastActivity' | 'durationMs'>, events: SessionEvent[]): {
+    createdAgo?: string;
+    lastActiveAgo?: string;
+    duration?: string;
+};
 /**
  * Unique directories the session touched, compact and human-readable.
  * Prefer `session.recentDirectoriesTouched` — the scan records it on the row, so