@phnx-labs/agents-cli 1.20.92 → 1.21.0

package/dist/commands/projects.js

@@ -10,16 +10,45 @@
  */
 import chalk from 'chalk';
 import * as fs from 'fs';
+import * as path from 'path';
 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 { truncate } from '../lib/format.js';
+import { expandLocalHome, getProjectRoot, toHomeRelative } from '../lib/project-root.js';
+import { machineId } from '../lib/machine-id.js';
 import { getActiveSessions } from '../lib/session/active.js';
+import { gatherRemoteActive } from '../lib/session/remote-active.js';
+import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
 import { factoryProjectsPath } from '../lib/auto-dispatch.js';
+import { formatFleetWorkspaces, parseRemoteProbe, probeProjectWorkspaces, workspaceTargetsForDef, } from '../lib/project-probe.js';
 import { listProjectDefs, loadProjectDef, writeProjectDef, removeProjectDef, projectDefPath, isSafeProjectName, } from '../lib/projects.js';
-import { rollupSessionsByProject, planPct, enrichProjectSignals, } from '../lib/project-status.js';
+import { rollupSessionsByProject, planPct, enrichProjectSignals, formatProjectMembers, } from '../lib/project-status.js';
+import { fetchLinearProjectCounts } from '../lib/linear-project-counts.js';
+import { listLinearProjects, pickLinearProject } from '../lib/linear-projects.js';
+import { buildFactoryImportCandidates, buildLinearImportCandidates, validateImportOpts, } from '../lib/project-import.js';
+/** Recursion guard: a peer answering a probe fan-out never re-fans-out itself. */
+export const PROJECTS_NO_FANOUT_ENV = 'AGENTS_PROJECTS_LOCAL';
+/** Max peers named in the skipped note before the rest collapse to `+N`. */
+const SKIPPED_NAME_LIMIT = 4;
+/**
+ * One compact trailing note for peers that didn't answer the `--fleet`
+ * fan-out — unreachable, running an agents-cli too old to carry `projects
+ * probe`, or too slow to finish inside the 12s SSH budget. Mirrors
+ * `formatUnreachableNote` (activity) with the probe-specific reasons; empty
+ * string when everything answered.
+ */
+export function formatFleetSkippedNote(skipped) {
+    if (skipped.length === 0)
+        return '';
+    const named = skipped.slice(0, SKIPPED_NAME_LIMIT);
+    const rest = skipped.length - named.length;
+    const list = rest > 0 ? `${named.join(', ')} +${rest}` : named.join(', ');
+    const noun = skipped.length === 1 ? 'device' : 'devices';
+    return chalk.gray(`  · ${skipped.length} ${noun} didn't answer (unreachable, older agents-cli, or timed out): ${list}\n`);
+}
 /** `path:purpose` → a context anchor. Purpose may contain colons. */
 function parseContextFlag(raw) {
     const i = raw.indexOf(':');
@@ -37,6 +66,135 @@ function originSlug(cwd) {
         return undefined;
     }
 }
+/**
+ * Read the Factory registry off disk and plan its import. Every read failure is
+ * fatal and named — an unreadable or malformed registry must not read as "0
+ * projects to import".
+ */
+function runFactoryImport(existing, 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 parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch {
+        console.error(chalk.red(`Factory registry at ${src} is not valid JSON`));
+        process.exit(1);
+    }
+    const rows = Array.isArray(parsed)
+        ? parsed
+        : Array.isArray(parsed?.projects)
+            ? parsed.projects
+            : [];
+    return buildFactoryImportCandidates(rows, existing, opts);
+}
+/**
+ * List the workspace's Linear projects and plan their import, binding each to a
+ * local checkout under the configured projects root when the names match
+ * exactly. A missing / logged-out `linear` CLI is loud (this is an explicit user
+ * command), and nothing is written before the whole plan is built.
+ */
+function runLinearImport(existing, opts) {
+    let list;
+    try {
+        list = listLinearProjects();
+    }
+    catch (e) {
+        console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+        process.exit(1);
+    }
+    // No projects root configured (or unreadable) → no local matching; every def
+    // still imports, carrying its Linear link and nothing it can't prove.
+    const rootAbs = getProjectRoot() ? expandLocalHome(getProjectRoot()) : undefined;
+    let localDirs = [];
+    if (rootAbs) {
+        try {
+            localDirs = fs
+                .readdirSync(rootAbs, { withFileTypes: true })
+                .filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+                .map((d) => d.name);
+        }
+        catch {
+            localDirs = [];
+        }
+    }
+    return buildLinearImportCandidates(list, existing, {
+        localDirs,
+        resolveRoot: (dir) => (rootAbs ? toHomeRelative(path.join(rootAbs, dir)) : undefined),
+        resolveOrigin: (dir) => (rootAbs ? originSlug(path.join(rootAbs, dir)) : undefined),
+    }, opts);
+}
+/** Longest path a `list` row shows before it truncates. */
+const LIST_PATH_MAX = 48;
+/**
+ * Column widths for `projects list`, sized to the rows actually being printed.
+ * Fixed padding was the bug: home-relative roots run past 50 characters, so a
+ * hardcoded 32 pushed the repo column off its gridline on every long path.
+ * Paths longer than {@link LIST_PATH_MAX} truncate rather than widen the table.
+ */
+export function computeProjectListWidths(rows) {
+    const widest = (pick, cap) => Math.min(cap, rows.reduce((w, r) => Math.max(w, pick(r).length), 0));
+    return {
+        name: widest((r) => r.name, 64),
+        path: widest((r) => r.path, LIST_PATH_MAX),
+        repo: widest((r) => r.repo, 64),
+    };
+}
+/**
+ * A milestone's target date as a person would say it — "due tomorrow",
+ * "overdue by 3 days", "due Aug 21" — never a raw `2026-08-21` or a duration in
+ * hours. Linear stores a calendar date with no timezone, so both sides are
+ * compared at LOCAL midnight; parsing `YYYY-MM-DD` with `new Date(str)` would
+ * read it as UTC and shift the answer by a day for anyone west of Greenwich.
+ */
+export function formatMilestoneDue(targetDate, nowMs) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(targetDate.trim());
+    if (!m)
+        return undefined;
+    const due = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    if (Number.isNaN(due.getTime()))
+        return undefined;
+    const now = new Date(nowMs);
+    const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const days = Math.round((due.getTime() - today.getTime()) / 86_400_000);
+    if (days === 0)
+        return 'due today';
+    if (days === 1)
+        return 'due tomorrow';
+    if (days === -1)
+        return 'overdue by a day';
+    if (days < 0)
+        return `overdue by ${-days} days`;
+    if (days <= 14)
+        return `due in ${days} days`;
+    const sameYear = due.getFullYear() === today.getFullYear();
+    const label = due.toLocaleDateString('en-US', {
+        month: 'short',
+        day: 'numeric',
+        ...(sameYear ? {} : { year: 'numeric' }),
+    });
+    return `due ${label}`;
+}
+/** The `next` card line: what this project is due to hit, and how far along it is. */
+export function formatNextMilestone(ms, nowMs) {
+    const parts = [chalk.bold(ms.name)];
+    // A milestone with nothing filed under it yet has no progress to report —
+    // `0/0` is noise, not information.
+    if (ms.total > 0)
+        parts.push(`${ms.done}/${ms.total}`);
+    const due = ms.targetDate ? formatMilestoneDue(ms.targetDate, nowMs) : undefined;
+    if (due)
+        parts.push(due.startsWith('overdue') ? chalk.yellow(due) : chalk.dim(due));
+    return parts.join(chalk.dim('  ·  '));
+}
 function statusBar(r) {
     const parts = [];
     const push = (n, label, color) => {
@@ -54,7 +212,7 @@ function statusBar(r) {
         parts.push(chalk.gray(`+${r.agents - shown} other`));
     return parts.join(' · ') || chalk.gray('no live agents');
 }
-function renderCard(def, r, remote) {
+function renderCard(def, r, remote, fleet, linear, nowMs = Date.now()) {
     const agents = r?.agents ?? 0;
     const pct = r ? planPct(r.plan) : undefined;
     const planStr = pct === undefined ? '' : `  ·  ${chalk.cyan(`${pct}% plan`)}`;
@@ -62,6 +220,8 @@ function renderCard(def, r, remote) {
     if (def.description)
         console.log(`  ${chalk.dim(def.description)}`);
     console.log(`  ${chalk.dim('live')}     ${r ? statusBar(r) : chalk.gray('no live agents')}`);
+    if (r && r.members.length)
+        console.log(`  ${chalk.dim('agents')}   ${formatProjectMembers(r.members)}`);
     const ships = [];
     if (remote?.mergedPrs)
         ships.push(chalk.green(`${remote.mergedPrs} merged (${remote.windowDays}d)`));
@@ -69,11 +229,28 @@ function renderCard(def, r, remote) {
         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 (remote?.latestRelease)
+        ships.push(remote.latestRelease.tag);
     if (ships.length)
         console.log(`  ${chalk.dim('ships')}    ${ships.join(' · ')}`);
+    if (linear) {
+        console.log(`  ${chalk.dim('linear')}   ${linear.done}/${linear.total}${linear.truncated ? '+' : ''} done · ${linear.inProgress} in progress`);
+    }
+    if (linear?.nextMilestone) {
+        console.log(`  ${chalk.dim('next')}     ${formatNextMilestone(linear.nextMilestone, nowMs)}`);
+    }
     if (r && r.tickets.length) {
         console.log(`  ${chalk.dim('tickets')}  ${r.tickets.slice(0, 8).join(' · ')}${r.tickets.length > 8 ? ' …' : ''}`);
     }
+    if (fleet) {
+        const lines = formatFleetWorkspaces(fleet);
+        if (lines.length === 0) {
+            console.log(`  ${chalk.dim('fleet')}    ${chalk.gray('no workspace paths (set root or repos[].path)')}`);
+        }
+        lines.forEach((line, i) => {
+            console.log(`  ${chalk.dim((i === 0 ? 'fleet' : '').padEnd(5))}    ${line}`);
+        });
+    }
     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}`);
@@ -96,20 +273,33 @@ export function registerProjectsCommands(program) {
         .description('Named multi-repo projects with a progress rollup.');
     setHelpSections(projects, {
         examples: `
+      agents projects import --from-linear  # the projects you actually track
       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 projects status --fleet      # + per-device workspace drift over SSH
+      agents projects link rush --linear  # bind the Linear project (auto-suggest)
       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.
+
+      'import --from-factory' reads Factory's auto-detected registry, which
+      guesses from checkouts on disk — it imports only 'high' confidence rows by
+      default. Widen with --min-confidence medium or --all, and drop a bad guess
+      with 'agents projects rm <name>'.
     `,
     });
-    projects.hook('preAction', () => {
+    projects.hook('preAction', (_thisCommand, actionCommand) => {
         if (enabled)
             return;
+        // `probe` is the peer half of `status --fleet`: it must answer whenever the
+        // binary carries it, even where the beta flag is off — a gated peer would
+        // look unreachable to every fleet member on a newer CLI.
+        if (actionCommand.name() === 'probe')
+            return;
         console.error(chalk.red('agents projects is in beta.'));
         console.error(chalk.gray(betaEnableHint('projects')));
         process.exit(1);
@@ -131,10 +321,16 @@ export function registerProjectsCommands(program) {
             return;
         }
         const roll = rollupSessionsByProject(defs, await getActiveSessions());
-        for (const d of defs) {
+        const rows = defs.map((d) => ({
+            name: d.name,
+            path: truncate(d.root ?? d.defaultPath ?? '', LIST_PATH_MAX),
+            repo: d.repo ?? d.repos?.[0]?.slug ?? '',
+        }));
+        const w = computeProjectListWidths(rows);
+        for (const [i, d] of defs.entries()) {
             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`);
+            const row = rows[i];
+            console.log(`  ${chalk.bold(row.name.padEnd(w.name))} ${chalk.dim(row.path.padEnd(w.path))} ${chalk.cyan(row.repo.padEnd(w.repo))} ${agents} agents`);
         }
     });
     // ---- add ----
@@ -239,6 +435,7 @@ export function registerProjectsCommands(program) {
         .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')
+        .option('--fleet', 'Also dial every fleet device for workspace presence, branch, and drift (one SSH per peer)')
         .action(async (name, opts) => {
         const all = listProjectDefs();
         // Named lookup goes through the strict single-def loader so a broken
@@ -257,14 +454,57 @@ export function registerProjectsCommands(program) {
         }
         const windowDays = Math.max(1, Number.parseInt(opts.window ?? '7', 10) || 7);
         const nowMs = Date.now();
-        const roll = rollupSessionsByProject(all, await getActiveSessions());
+        // --fleet: probe each shown def's workspace paths (root + repos[].path)
+        // locally and on every peer in one parallel SSH round, and widen the
+        // live-session rollup to the whole fleet via the existing sessions
+        // fan-out. Both are opt-in — they dial the fleet.
+        const fleetTargets = opts.fleet ? [...new Set(defs.flatMap(workspaceTargetsForDef))] : [];
+        let fleetWs = [];
+        let fleetSkipped = [];
+        let fleetSessions = [];
+        if (opts.fleet) {
+            const self = machineId();
+            fleetWs.push(...probeProjectWorkspaces(fleetTargets).map((s) => ({ ...s, host: self })));
+            const [probeRes, activeRes] = await Promise.all([
+                fleetTargets.length > 0
+                    ? gatherRemoteAgentsJson({
+                        args: ['projects', 'probe', '--json', ...fleetTargets],
+                        noFanoutEnv: PROJECTS_NO_FANOUT_ENV,
+                        parse: parseRemoteProbe,
+                        quiet: true,
+                    })
+                    : Promise.resolve({ items: [], deviceCount: 0, skipped: [] }),
+                gatherRemoteActive(undefined, { quiet: true }),
+            ]);
+            fleetWs.push(...probeRes.items);
+            fleetSkipped = probeRes.skipped;
+            fleetSessions = activeRes.sessions;
+        }
+        const roll = rollupSessionsByProject(all, [...await getActiveSessions(), ...fleetSessions]);
         // 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).
+        // log but skips the gh calls + Linear counts (both are network).
         const remote = new Map();
+        const linear = new Map();
         await Promise.all(defs.map(async (d) => {
-            remote.set(d.name, await enrichProjectSignals(d, windowDays, nowMs, { skipRemote: opts.remote === false }));
+            const skipRemote = opts.remote === false;
+            const [sig, counts] = await Promise.all([
+                enrichProjectSignals(d, windowDays, nowMs, { skipRemote }),
+                !skipRemote && d.linear?.projectId
+                    ? fetchLinearProjectCounts(d.linear.projectId)
+                    : Promise.resolve(undefined),
+            ]);
+            remote.set(d.name, sig);
+            if (counts)
+                linear.set(d.name, counts);
         }));
+        /** This def's slice of the fleet probe, in its own target order. */
+        const fleetFor = (d) => {
+            const targets = new Set(workspaceTargetsForDef(d));
+            return fleetWs.filter((s) => targets.has(s.path));
+        };
         if (opts.json) {
+            if (fleetSkipped.length > 0)
+                process.stderr.write(formatFleetSkippedNote(fleetSkipped));
             console.log(JSON.stringify(defs.map((d) => {
                 const r = roll.get(d.name);
                 const rem = remote.get(d.name);
@@ -272,74 +512,141 @@ export function registerProjectsCommands(program) {
                     name: d.name,
                     agents: r?.agents ?? 0,
                     byStatus: r?.byStatus ?? {},
+                    members: r?.members ?? [],
                     plan: r?.plan ?? { done: 0, total: 0 },
                     planPct: r ? planPct(r.plan) ?? null : null,
                     openPrs: r?.openPrs ?? [],
                     mergedPrs: rem?.mergedPrs ?? 0,
+                    latestRelease: rem?.latestRelease ?? null,
+                    linear: linear.get(d.name) ?? null,
                     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),
+                    ...(opts.fleet ? { workspaces: fleetFor(d) } : {}),
                 };
             }), null, 2));
             return;
         }
-        for (const d of defs)
-            renderCard(d, roll.get(d.name), remote.get(d.name));
+        for (const d of defs) {
+            renderCard(d, roll.get(d.name), remote.get(d.name), opts.fleet ? fleetFor(d) : undefined, linear.get(d.name), nowMs);
+        }
+        if (fleetSkipped.length > 0)
+            process.stdout.write(formatFleetSkippedNote(fleetSkipped));
+    });
+    // ---- probe (hidden; the peer half of `status --fleet`) ----
+    projects
+        .command('probe [paths...]', { hidden: true })
+        .description('Probe workspace repos (presence, branch, drift, dirtiness) and print JSON. Answers for this machine only.')
+        .option('--json', 'Machine-readable output (the only output format)')
+        .action((paths) => {
+        // Never fans out — the recursion guard env is set by the parent fan-out,
+        // and this command has no remote code path either way.
+        console.log(JSON.stringify(probeProjectWorkspaces(paths ?? []), null, 2));
     });
     // ---- 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')
+        .description('Import project definitions from Linear (preferred) or the Factory auto-detection registry.')
+        .option('--from-linear', 'Import the workspace\'s Linear projects (via the `linear` CLI)')
+        .option('--from-factory', 'Import the Factory registry (~/.agents/factory/projects.json)')
+        .option('--min-confidence <level>', '--from-factory only: lowest detection confidence to import — low|medium|high (default: high)')
+        .option('--all', '--from-factory only: import every row regardless of confidence')
         .option('--force', 'Overwrite existing definitions')
-        .action((opts) => {
-        const src = factoryProjectsPath();
-        let rawText;
+        .action((raw) => {
+        let opts;
         try {
-            rawText = fs.readFileSync(src, 'utf8');
+            opts = validateImportOpts(raw);
         }
-        catch {
-            console.error(chalk.red(`No Factory registry at ${src}`));
+        catch (e) {
+            console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+            process.exit(1);
+        }
+        const existing = new Map(listProjectDefs().map((d) => [d.name, d]));
+        const result = opts.source === 'linear' ? runLinearImport(existing, opts) : runFactoryImport(existing, opts);
+        for (const def of result.defs)
+            writeProjectDef(def);
+        const n = result.defs.length;
+        const s = result.skipped.length;
+        console.log(chalk.green(`Imported ${n} project${n === 1 ? '' : 's'}${s ? chalk.gray(` (${s} skipped)`) : ''}`));
+        for (const skip of result.skipped)
+            console.log(chalk.gray(`  skip ${skip.name}: ${skip.reason}`));
+        if (opts.source === 'factory' && s > 0 && opts.minConfidence === 'high') {
+            console.log(chalk.gray('  (widen with --min-confidence medium or --all)'));
+        }
+    });
+    // ---- link ----
+    projects
+        .command('link <name>')
+        .description('Attach an external tracker to a project definition (writes linear.projectId into the YAML).')
+        .option('--linear [query]', 'Bind a Linear project by exact name or id; no value auto-suggests from the def name + repo')
+        .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.linear === undefined) {
+            console.error(chalk.red('Nothing to link. Pass a tracker flag, e.g. --linear [query].'));
             process.exit(1);
         }
-        let rows;
+        // Explicit user command — a missing/unauthenticated `linear` CLI is loud,
+        // unlike the best-effort card enrichment.
+        let list;
         try {
-            rows = JSON.parse(rawText);
+            list = listLinearProjects();
         }
-        catch {
-            console.error(chalk.red(`Factory registry at ${src} is not valid JSON`));
+        catch (e) {
+            console.error(chalk.red(e instanceof Error ? e.message : String(e)));
             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;
+        const query = typeof opts.linear === 'string' ? opts.linear.trim() : '';
+        let pick;
+        if (query) {
+            pick = pickLinearProject(query, list);
+        }
+        else {
+            // Auto-suggest from the def's own identity — the primary repo slug is
+            // the sharpest key, then the def name. Only an exact normalized match
+            // writes itself; anything weaker asks the user to disambiguate.
+            pick = { kind: 'none' };
+            for (const hint of [def.repo, def.name].filter((h) => typeof h === 'string' && h.length > 0)) {
+                const d = pickLinearProject(hint, list);
+                if (d.kind === 'match') {
+                    pick = d;
+                    break;
+                }
+                if (pick.kind === 'none')
+                    pick = d;
             }
-            if (loadProjectDef(name) && !opts.force) {
-                skipped++;
-                continue;
+        }
+        if (pick.kind !== 'match') {
+            if (pick.kind === 'candidates') {
+                console.error(chalk.yellow(`No confident Linear match${query ? ` for "${query}"` : ` for "${def.name}"`}. Candidates:`));
+                for (const c of pick.projects)
+                    console.error(`  ${chalk.cyan(c.id)}  ${c.name}`);
             }
-            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++;
+            else {
+                console.error(chalk.yellow(`No Linear project matches${query ? ` "${query}"` : ` "${def.name}"`}. Available:`));
+                for (const c of list)
+                    console.error(`  ${chalk.cyan(c.id)}  ${c.name}`);
+            }
+            console.error(chalk.gray(`Re-run with an explicit name or id: agents projects link ${name} --linear "<name-or-id>"`));
+            process.exit(1);
+        }
+        const p = pick.project;
+        // Preserve every other field — load, set linear, write back. Keep a
+        // previously linked url when the new CLI row carries none.
+        if (def.linear?.projectId && def.linear.projectId !== p.id) {
+            console.log(chalk.gray(`  replacing previous Linear link (${def.linear.projectId})`));
         }
-        console.log(chalk.green(`Imported ${created} project${created === 1 ? '' : 's'}${skipped ? chalk.gray(` (${skipped} skipped)`) : ''}`));
+        def.linear = { ...def.linear, projectId: p.id };
+        if (p.url)
+            def.linear.url = p.url;
+        writeProjectDef(def);
+        console.log(chalk.green(`${def.name} → Linear project "${p.name}" (${p.id})${p.url ? ` ${p.url}` : ''}`));
     });
     // ---- rm ----
     projects

package/dist/commands/routines.js

@@ -11,6 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, } from '../lib/daemon.js';
+import { assertSchedulerEnabled } from '../lib/device-config.js';
 import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
 import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, placementRequiresFiringPin, HOST_STRATEGIES, } from '../lib/routines.js';
@@ -295,9 +296,21 @@ function parseRoutineTrigger(options) {
 /**
  * Start or reload the background scheduler so newly-added jobs fire on time.
  * `quiet` suppresses human status lines for JSON callers.
+ *
+ * When this device has `scheduler.enabled=false` the auto-start is skipped with
+ * the stated reason (the add itself already succeeded — the job is config and
+ * stays valid fleet-wide); the refusal message names the setting and the fix.
  */
 function ensureSchedulerRunning(opts = {}) {
     const log = opts.stderr ? console.error : console.log;
+    try {
+        assertSchedulerEnabled();
+    }
+    catch (err) {
+        // Loud stated skip, on stderr so --json stdout stays clean.
+        console.error(chalk.yellow(err.message));
+        return;
+    }
     if (isDaemonRunning()) {
         signalDaemonReload();
         if (!opts.quiet)
@@ -1480,9 +1493,22 @@ export function registerRoutinesCommands(program) {
         .command('start')
         .description('Start the background scheduler. Usually unnecessary — it auto-starts when you add your first routine.')
         .action(() => {
+        try {
+            // A manual start on a scheduler-disabled device refuses with the same
+            // message the auto-start surfaces give.
+            assertSchedulerEnabled();
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
         const result = startDaemon();
         if (result.method === 'already-running') {
-            console.log(chalk.yellow(`Scheduler already running (PID: ${result.pid})`));
+            // Signal a reload even here: if the daemon booted while this device had
+            // scheduler.enabled=false, the reload re-evaluates the gate and boots
+            // the scheduler — a manual start heals a scheduler-less daemon.
+            signalDaemonReload();
+            console.log(chalk.yellow(`Scheduler already running (PID: ${result.pid}) — reloaded`));
         }
         else if (result.pid) {
             console.log(chalk.green(`Scheduler started (PID: ${result.pid})`));

package/dist/commands/rules.js

@@ -512,6 +512,12 @@ Examples:
         .addHelpText('after', `
 Targets are <agent>@<version>. Use 'default' for the alias of the global default version.
 
+This re-syncs the version home immediately, AND the choice sticks: every later
+'agents run' for this agent+version re-applies the active preset before launch
+(skip-fast when nothing changed), so a preset set here never goes stale even if
+something changes it again without running 'switch' — you don't need to re-run
+'switch' or 'sync' by hand before the next launch.
+
 Examples:
   # Persist the cautious preset for claude 2.1.111
   agents rules switch claude@2.1.111 --preset cautious

package/dist/commands/secrets.d.ts

@@ -10,6 +10,7 @@ import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg } from '../lib/platform/index.js';
 import { type SecretsBackend, type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
 import { type SecretsListFilterOpts } from '../lib/secrets/list-filter.js';
+import { type BundleUsageSummary } from '../lib/secrets/usage-db.js';
 /** Read all available data from stdin synchronously, trimmed. */
 /**
  * Read the raw `.env` text for `import --from <path|->`. A `-` reads the .env
@@ -125,6 +126,22 @@ export declare function formatHoldWindow(ms: number): string;
  * shared by the POLICY column, the `--held` filter, and the JSON payload, so the
  * three can never disagree about the same bundle. */
 export declare function liveHold(expiresAt: number | undefined, now?: number): number | null;
+/**
+ * Compact one-line usage summary for `secrets view` — each recorded event with
+ * its count and how long ago it last happened ("accessed 42× (last 2h ago) ·
+ * exported 3× (last 1d ago)"). Empty string when nothing has been recorded yet.
+ * Pure — unit-tested.
+ */
+export declare function formatUsageLine(summary: BundleUsageSummary | undefined): string;
+/**
+ * The held-state line for `secrets view`: whether the secrets-agent currently
+ * holds this bundle (so reads are prompt-free) and for how long, or that Touch
+ * ID is required on the next read. Only meaningful for keychain bundles on macOS
+ * — file/vault backends have no broker to hold, and a `never`-policy bundle is
+ * always readable — so both return an empty line and the caller skips it.
+ * `heldExpiresAt` is the max expiry across every held scope.
+ */
+export declare function renderViewStatusLine(b: SecretsBundle, heldExpiresAt: number | null): string;
 /**
  * The EXPIRING cell. Counts keys needing attention — already expired plus due
  * within 30 days — and colours by the worst of the two: red once anything has