@phnx-labs/agents-cli 1.20.93 → 1.21.0

package/dist/lib/menubar/install-menubar.js

@@ -25,6 +25,21 @@ import { getCliVersion, resolveAgentsBin, resolveInstalledLayout } from '../vers
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 const SERVICE_LABEL = 'com.phnx-labs.agents-menubar';
+/**
+ * Minimum seconds between launchd restarts of the helper (`ThrottleInterval`).
+ *
+ * The helper can crash at startup on a loaded machine: `NSApplication.shared`
+ * segfaults inside `SLSNewConnection` when WindowServer is too starved to hand
+ * out a connection. With `KeepAlive` and no throttle, launchd relaunches on its
+ * 10s default, and each attempt spawns a fresh `agents doctor --json` before
+ * dying — so a starved box gets hit harder the worse it gets. 30s bounds that
+ * respawn rate while staying well inside "the menu bar came back on its own".
+ *
+ * This only paces the restarts. What actually stops the pile-up is the helper
+ * bounding and group-killing its own children (menubar/Sources/MenubarHelper/
+ * ChildProcess.swift); the two are complementary, not alternatives.
+ */
+const MENUBAR_THROTTLE_SECONDS = 30;
 function onDarwin() {
     return process.platform === 'darwin';
 }
@@ -181,41 +196,15 @@ export function codesignVerifies(appPath) {
  * A Developer-ID-signed but un-notarized app is rejected by `spctl --assess`,
  * which macOS surfaces as "the app is damaged" and can crash AppKit during
  * launch. This is separate from `codesign --verify`: a signature can be valid
- * while Gatekeeper still refuses to run it.
+ * while Gatekeeper still refuses to run it. The release notarizes + staples the
+ * helper (menubar/scripts/build.sh, gated by verify-menubar-helper.sh), so a
+ * shipped bundle passes this; the launch guards use it to fail loud rather than
+ * bootstrap a helper macOS would reject.
  */
 export function gatekeeperAssesses(appPath) {
     const r = spawnSync('spctl', ['--assess', '--type', 'exec', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
     return r.status === 0;
 }
-/**
- * Guarantee the installed bundle has a signature Gatekeeper will accept on THIS
- * machine.
- *
- * npm's pack/extract strips the ad-hoc/linker signature the release baked into
- * the helper, leaving `code object is not signed at all`. On macOS 26+ the
- * kernel's code-signing monitor SIGKILLs an unsigned/invalid binary at launch
- * (`SIGKILL (Code Signature Invalid)`), so under the launchd `KeepAlive` service
- * an ad-hoc release helper crash-loops forever and its unstable identity makes
- * the Accessibility grant (needed for the clip→paste keystroke in Clip.swift)
- * re-prompt every time. A fresh ad-hoc re-sign gives the on-disk bytes a
- * matching cdhash, which the kernel accepts.
- *
- * A Developer-ID-signed helper survives npm untouched — its embedded signature
- * still verifies — but if the release was not notarized, Gatekeeper rejects it.
- * In that case we strip the quarantine xattr and re-sign ad-hoc so the helper
- * can launch locally. The stable fix is to notarize the release build; this
- * fallback just prevents a crash-loop while the user is on an un-notarized cut.
- */
-export function ensureValidSignature(appPath) {
-    if (codesignVerifies(appPath) && gatekeeperAssesses(appPath))
-        return true;
-    // Drop any quarantine/xattrs the tarball round-trip added (they can break
-    // both codesign and Gatekeeper), then re-sign ad-hoc under the helper's
-    // stable bundle identifier.
-    spawnSync('xattr', ['-cr', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
-    spawnSync('codesign', ['--force', '--sign', '-', '--identifier', SERVICE_LABEL, appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
-    return codesignVerifies(appPath);
-}
 /**
  * Copy the bundled `.app` to the stable user path (idempotent unless forced).
  * Returns the installed executable path, or null if no source bundle ships
@@ -229,13 +218,9 @@ export function ensureMenubarAppInstalled(opts = {}) {
         return null;
     const dest = installedAppPath();
     if (!opts.forceReinstall && fs.existsSync(dest)) {
-        // Self-heal an already-installed bundle whose signature npm stripped on a
-        // prior upgrade (macOS 26+ SIGKILLs it otherwise) without a forced recopy.
-        ensureValidSignature(dest);
         return installedExecutablePath();
     }
     copyAppBundle(src, dest);
-    ensureValidSignature(dest);
     // A fresh copy is exactly when the bundle's icon can be new (first install) or
     // superseded (upgrade) — register it so LaunchServices knows the bundle and can
     // resolve its AppIcon for the left-hand slot of daemon notifications.
@@ -245,7 +230,7 @@ export function ensureMenubarAppInstalled(opts = {}) {
 function xmlEscape(s) {
     return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
-function generateServicePlist(execPath) {
+export function generateServicePlist(execPath) {
     const home = os.homedir();
     const logPath = path.join(getHelpersDir(), 'menubar', 'menubar.log');
     fs.mkdirSync(path.dirname(logPath), { recursive: true });
@@ -281,6 +266,8 @@ function generateServicePlist(execPath) {
   <true/>
   <key>KeepAlive</key>
   <true/>
+  <key>ThrottleInterval</key>
+  <integer>${MENUBAR_THROTTLE_SECONDS}</integer>
   <key>ProcessType</key>
   <string>Interactive</string>
   <key>StandardOutPath</key>
@@ -331,12 +318,15 @@ export function enableMenubarService(opts = { clearOptOut: true }) {
     const exec = ensureMenubarAppInstalled({ forceReinstall: true });
     if (!exec)
         return false;
-    // Never bootstrap a helper the kernel will kill on launch: an invalid
-    // signature under launchd KeepAlive is an infinite crash loop. If the bundle
-    // can't be made valid (re-sign already attempted in ensureMenubarAppInstalled),
-    // skip the service rather than spin the loop.
-    if (!codesignVerifies(installedAppPath())) {
-        process.stderr.write('agents: menu-bar helper has no valid code signature; skipping launch to avoid a crash loop.\n');
+    // Never bootstrap a helper macOS will reject at launch: an invalid signature
+    // under launchd KeepAlive crash-loops forever, and an un-notarized bundle is
+    // rejected by Gatekeeper as "damaged". A shipped helper is Developer-ID signed
+    // AND notarized (release build + the verify-menubar-helper.sh prepack gate), so
+    // this passes; if it ever doesn't, skip the service and point at the upgrade
+    // rather than re-signing over it (an ad-hoc re-sign never satisfies Gatekeeper).
+    if (!(codesignVerifies(installedAppPath()) && gatekeeperAssesses(installedAppPath()))) {
+        process.stderr.write('agents: menu-bar helper is not notarized/valid on this machine; skipping launch. ' +
+            'Upgrade to a notarized build (npm i -g @phnx-labs/agents-cli), then `agents menubar setup`.\n');
         return false;
     }
     if (opts.clearOptOut)
@@ -560,11 +550,12 @@ export function runMenubarSetup() {
         return { steps, configured: false, status: getMenubarStatus() };
     }
     step('bundle', before.installedVersion === getCliVersion() ? 'ok' : 'changed', `${installedAppPath()} (${getCliVersion()})`);
-    if (!codesignVerifies(installedAppPath())) {
-        step('signature', 'failed', 'no valid code signature — refusing to start it (launchd KeepAlive would crash-loop)');
+    if (!(codesignVerifies(installedAppPath()) && gatekeeperAssesses(installedAppPath()))) {
+        step('signature', 'failed', 'not notarized/valid on this machine — refusing to start it (Gatekeeper rejects an ' +
+            'un-notarized helper as "damaged"). Upgrade to a notarized build of agents-cli.');
         return { steps, configured: false, status: getMenubarStatus() };
     }
-    step('signature', 'ok', 'valid');
+    step('signature', 'ok', 'valid + notarized');
     // Clear the sticky opt-out: running `setup` is an explicit request for the
     // menu bar, so a stale `menubar disable` must not silently win.
     clearMenubarOptOut();

package/dist/lib/migrate.js

@@ -1708,7 +1708,7 @@ function migrateVersionResourcesToPatterns() {
         }
     }
     if (changed) {
-        const META_HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n\n';
+        const META_HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json\n\n';
         fs.writeFileSync(metaFile, META_HEADER + yaml.stringify(meta), 'utf-8');
         console.error('Migrated agents.yaml versions: entries to pattern format');
     }

package/dist/lib/models.js

@@ -20,7 +20,14 @@ const CACHE_PATH = getModelsCachePath();
  * Bump when the extractor logic changes shape in an incompatible way so cached
  * catalogs from older agents-cli builds are re-extracted.
  */
-const CACHE_SCHEMA_VERSION = 2;
+const CACHE_SCHEMA_VERSION = 3;
+/**
+ * How long a cached 0-model extraction is trusted before we retry it. Bounds
+ * the self-healing window for a transient failure (mid-install, a broken
+ * extractor regex fixed in a later agents-cli release) without falling back
+ * to re-extracting -- and re-scanning the whole binary -- on every call.
+ */
+const EMPTY_CATALOG_RETRY_MS = 24 * 60 * 60 * 1000;
 let memoryCache = null;
 function cacheKey(agent, version) {
     return `${agent}@${version}`;
@@ -884,7 +891,10 @@ export function getModelCatalog(agent, version) {
     const key = cacheKey(agent, version);
     const cached = cache.entries[key];
     if (cached && cached.sourcePath === src.path && cached.mtime === mtime) {
-        return cached.catalog;
+        const isFresh = cached.catalog.models.length > 0 ||
+            Date.now() - (cached.attemptedAt ?? 0) < EMPTY_CATALOG_RETRY_MS;
+        if (isFresh)
+            return cached.catalog;
     }
     let models = [];
     let aliases = {};
@@ -927,15 +937,15 @@ export function getModelCatalog(agent, version) {
         models,
         aliases,
     };
-    // Never cache an empty extraction, regardless of source kind. A 0-model
-    // result is always suspect: the CLI may have been mid-install, network-
-    // dependent, or transiently failing, and a js/bundle/binary extractor that
-    // regex-misses would otherwise pin an empty catalog forever (mtime won't
-    // change until the source file does). Only persist a non-empty catalog.
-    if (models.length > 0) {
-        cache.entries[key] = { sourcePath: src.path, mtime, catalog };
-        saveCache();
-    }
+    // Cache a 0-model extraction too, stamped with when it was attempted, so a
+    // broken/mid-install extractor doesn't force a full re-scan of the source
+    // binary (up to ~1.85s each for a 230-270MB Claude binary) on every call --
+    // `getModelCatalog` runs once per installed version per invocation of
+    // commands like `agents view`. It self-heals: the read site above re-tries
+    // extraction once EMPTY_CATALOG_RETRY_MS has elapsed, or immediately once
+    // the source file's mtime changes (an upgrade/reinstall).
+    cache.entries[key] = { sourcePath: src.path, mtime, catalog, attemptedAt: Date.now() };
+    saveCache();
     return catalog;
 }
 /**

package/dist/lib/overdue.d.ts

@@ -31,7 +31,7 @@ export interface OverdueJob {
  * Returns null when neither is available, which leaves the routine unfloored
  * (previous behaviour) rather than silently skipping it.
  */
-export declare function routineEffectiveStart(job: JobConfig): Date | null;
+export declare function routineEffectiveStart(job: JobConfig, now?: Date): Date | null;
 /** Return every enabled, recurring job whose most recent expected fire was
  *  missed. One-shot jobs are excluded — they fire at most once. */
 export declare function detectOverdueJobs(now?: Date): OverdueJob[];

package/dist/lib/overdue.js

@@ -13,29 +13,48 @@
  */
 import * as fs from 'fs';
 import { Cron } from 'croner';
-import { listJobs, getLatestRun, getJobPath, jobRunsOnThisDevice } from './routines.js';
+import { listJobs, getLatestRun, resolveJobFilePath, isPastEndAt, isOneShotRoutine, jobRunsOnThisDevice } from './routines.js';
 import { notifyDesktop } from './menubar/notify-desktop.js';
 // Tolerance between "expected fire" and "recorded run start" — accounts for
 // the small gap between the cron tick and when the runner writes meta.json.
 const GRACE_MS = 60_000;
-const ONE_WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Lookback windows, narrowest first. A fixed one-week window silently blinded
+ * detection to any cron whose gap exceeds it: `0 9 1,13,25 * *` has 12-day gaps,
+ * so `nextRun(now - 7d)` jumped past `now`, the walk returned null, and the
+ * routine was never flagged overdue on any device — no missed record, no
+ * catch-up, permanently. Monthly, quarterly and annual routines were all in that
+ * class.
+ *
+ * A wider window is only tried when the narrower one found nothing, so a dense
+ * schedule (every minute, hourly, daily) never walks more than a week of
+ * occurrences. A sparse schedule has few occurrences to walk by definition.
+ */
+const LOOKBACK_WINDOWS_MS = [7 * DAY_MS, 32 * DAY_MS, 93 * DAY_MS, 400 * DAY_MS];
 /** Compute the most recent fire of `pattern` at or before `now`. Croner's
  *  `previousRun()` returns the cron instance's own last fire, which is null
  *  on a freshly-constructed instance — so we walk `nextRun(cursor)` forward
  *  from a week ago and keep the last fire still ≤ now. */
 function previousExpectedFire(cron, now) {
-    let cursor = new Date(now.getTime() - ONE_WEEK_MS);
-    let last = null;
-    // Cap iterations: even an every-minute schedule yields ≤ 10080 steps over a
-    // week; we cap at 20k as a paranoia bound against pathological patterns.
-    for (let i = 0; i < 20000; i++) {
-        const next = cron.nextRun(cursor);
-        if (!next || next.getTime() > now.getTime())
-            break;
-        last = next;
-        cursor = next;
+    for (const window of LOOKBACK_WINDOWS_MS) {
+        let cursor = new Date(now.getTime() - window);
+        let last = null;
+        // Cap iterations: an every-minute schedule yields ≤ 10080 steps over a week;
+        // 20k is a paranoia bound against pathological patterns. Only a schedule
+        // that found nothing in the narrower window reaches a wider one, and such a
+        // schedule is sparse, so the cap is never the binding constraint.
+        for (let i = 0; i < 20000; i++) {
+            const next = cron.nextRun(cursor);
+            if (!next || next.getTime() > now.getTime())
+                break;
+            last = next;
+            cursor = next;
+        }
+        if (last)
+            return last;
     }
-    return last;
+    return null;
 }
 /**
  * When a routine started existing, and therefore the earliest fire it can
@@ -49,13 +68,17 @@ function previousExpectedFire(cron, now) {
  * Returns null when neither is available, which leaves the routine unfloored
  * (previous behaviour) rather than silently skipping it.
  */
-export function routineEffectiveStart(job) {
+export function routineEffectiveStart(job, now = new Date()) {
     if (job.createdAt) {
         const stamped = new Date(job.createdAt);
-        if (!isNaN(stamped.getTime()))
-            return stamped;
+        // Clamp a future stamp (clock skew, a hand-edited year) to now. Left
+        // unclamped it sits after every possible expected fire, so the routine can
+        // never be flagged overdue until wall-clock time catches up.
+        if (!isNaN(stamped.getTime())) {
+            return stamped.getTime() > now.getTime() ? now : stamped;
+        }
     }
-    const path = getJobPath(job.name);
+    const path = resolveJobFilePath(job.name);
     if (!path)
         return null;
     try {
@@ -70,7 +93,19 @@ export function routineEffectiveStart(job) {
 export function detectOverdueJobs(now = new Date()) {
     const overdue = [];
     for (const job of listJobs()) {
-        if (!job.enabled || job.runOnce)
+        if (!job.enabled)
+            continue;
+        // One-shot: fires at most once, so a missed slot is not a backlog to replay.
+        // Use the same predicate the scheduler does — the raw `runOnce` flag alone
+        // missed a one-shot-LIKE schedule (a fixed minute/hour/day/month) that never
+        // carried the flag.
+        if (isOneShotRoutine(job))
+            continue;
+        // Past its configured end: catch-up must not resurrect a routine the author
+        // already retired. The scheduler only auto-disables lazily, inside a live
+        // cron tick, so a routine whose endAt elapsed while the daemon was down is
+        // still enabled on disk when the catch-up pass runs.
+        if (isPastEndAt(job, now))
             continue;
         // Trigger-only jobs (no cron schedule) never have an expected fire time.
         if (!job.schedule)
@@ -99,7 +134,7 @@ export function detectOverdueJobs(now = new Date()) {
         // a miss. Without this, any newly created routine on a daily/weekly cron is
         // instantly "overdue" for the previous occurrence — and with auto-catchup
         // that means `agents routines add` runs the routine once, immediately.
-        const start = routineEffectiveStart(job);
+        const start = routineEffectiveStart(job, now);
         if (start && expected.getTime() < start.getTime())
             continue;
         const latest = getLatestRun(job.name);

package/dist/lib/project-import.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Pure builders behind `agents projects import`.
+ *
+ * Two sources feed the one `ProjectDef` schema: **Linear** (the preferred one —
+ * a project someone deliberately created on the board) and the **Factory
+ * registry** (`~/.agents/factory/projects.json`, an auto-detection that guesses
+ * from checkouts on disk). Both funnel through `writeProjectDef`.
+ *
+ * The Factory registry stamps each row with a `confidence` — and importing every
+ * row regardless is what buried the real projects under a dozen guesses
+ * (`agents-cleaned-stale2`, a repo cloned from someone else's org, …). So the
+ * import is gated on that field, `high` by default.
+ *
+ * Everything here is a pure function of its arguments — no fs, no shell, no
+ * process env. The command layer reads the registry / shells out to `linear` and
+ * hands the rows in; that's what makes these testable against plain fixtures
+ * with no mocking. The one exception is `toHomeRelative`, a string rewrite
+ * against `$HOME`.
+ */
+import { type ProjectDef } from './projects.js';
+import { type LinearProjectLite } from './linear-projects.js';
+/** Factory's per-row detection confidence, weakest first. */
+export type ImportConfidence = 'low' | 'medium' | 'high';
+/**
+ * The floor an import runs at. `any` is what `--all` means — it takes rows that
+ * state no confidence at all, which rank below even `low`; without it "import
+ * every row regardless of confidence" would quietly drop the unranked ones.
+ */
+export type ImportFloor = ImportConfidence | 'any';
+/** A row the import declined to write, with the reason to print. */
+export interface ImportSkip {
+    name: string;
+    reason: string;
+}
+/** What an import would write, and what it declined. */
+export interface ImportPlan {
+    defs: ProjectDef[];
+    skipped: ImportSkip[];
+}
+/** The validated shape of the `import` flags. */
+export interface ImportOptions {
+    source: 'factory' | 'linear';
+    /** Factory only: the lowest confidence that still imports. */
+    minConfidence: ImportFloor;
+    force: boolean;
+}
+/** The raw commander flags, before validation. */
+export interface RawImportFlags {
+    fromFactory?: boolean;
+    fromLinear?: boolean;
+    minConfidence?: string;
+    all?: boolean;
+    force?: boolean;
+}
+/**
+ * Validate the flag combination, throwing a user-facing message on the first
+ * problem. Every rejection is loud: an unrecognized `--min-confidence` is an
+ * error, never a silent fall back to the default floor.
+ */
+export declare function validateImportOpts(flags: RawImportFlags): ImportOptions;
+/**
+ * Plan the Factory import: same field mapping as before (`path`→`root`,
+ * `repoSlug`→`repo`, `linearProjectId`→`linear.projectId`), now gated on the
+ * row's `confidence`. A row with no confidence field is a guess with no stated
+ * strength, so it ranks below every floor and only `--all` takes it.
+ */
+export declare function buildFactoryImportCandidates(rows: unknown[], existing: Map<string, ProjectDef>, opts: Pick<ImportOptions, 'minConfidence' | 'force'>): ImportPlan;
+/**
+ * Turn a Linear project name into a definition slug: lowercase, every run of
+ * unusable characters collapsed to one `-`, trimmed of leading/trailing
+ * punctuation, capped at the 64 chars `isSafeProjectName` allows. Returns `''`
+ * when nothing usable survives — the caller skips those loudly.
+ */
+export declare function slugifyProjectName(name: string): string;
+/** The local-checkout lookups the Linear builder needs, injected so it stays pure. */
+export interface LinearImportDeps {
+    /** Directory names directly under the configured projects root. */
+    localDirs: string[];
+    /** Home-relative root path for one of `localDirs`. */
+    resolveRoot: (dir: string) => string | undefined;
+    /** `owner/repo` from that checkout's origin remote, when it has one. */
+    resolveOrigin: (dir: string) => string | undefined;
+}
+/**
+ * Plan the Linear import. Every project becomes a def carrying its `linear`
+ * link; the local checkout is bound **only on an exact normalized-name match**
+ * (`matchLocalCheckoutExact`). The containment fallback that powers the `link`
+ * suggestion is deliberately not used here — "Agents CLI" containing
+ * "agents-cli-web" is a fine hint for a human to confirm, and a silently wrong
+ * `root` on a write path.
+ *
+ * An existing def is preserved field-for-field; only `name` and `linear` are
+ * overwritten, so a hand-set `description`/`contexts`/`integrations` survives a
+ * re-import.
+ */
+export declare function buildLinearImportCandidates(projects: LinearProjectLite[], existing: Map<string, ProjectDef>, deps: LinearImportDeps, opts: Pick<ImportOptions, 'force'>): ImportPlan;

package/dist/lib/project-import.js

@@ -0,0 +1,171 @@
+/**
+ * Pure builders behind `agents projects import`.
+ *
+ * Two sources feed the one `ProjectDef` schema: **Linear** (the preferred one —
+ * a project someone deliberately created on the board) and the **Factory
+ * registry** (`~/.agents/factory/projects.json`, an auto-detection that guesses
+ * from checkouts on disk). Both funnel through `writeProjectDef`.
+ *
+ * The Factory registry stamps each row with a `confidence` — and importing every
+ * row regardless is what buried the real projects under a dozen guesses
+ * (`agents-cleaned-stale2`, a repo cloned from someone else's org, …). So the
+ * import is gated on that field, `high` by default.
+ *
+ * Everything here is a pure function of its arguments — no fs, no shell, no
+ * process env. The command layer reads the registry / shells out to `linear` and
+ * hands the rows in; that's what makes these testable against plain fixtures
+ * with no mocking. The one exception is `toHomeRelative`, a string rewrite
+ * against `$HOME`.
+ */
+import { toHomeRelative } from './project-root.js';
+import { isSafeProjectName } from './projects.js';
+import { matchLocalCheckoutExact } from './linear-projects.js';
+const CONFIDENCE_RANK = { any: 0, low: 1, medium: 2, high: 3 };
+/** Rank a raw `confidence` value; anything absent or unrecognized ranks 0 (below every floor). */
+function confidenceRank(raw) {
+    return typeof raw === 'string' ? (CONFIDENCE_RANK[raw] ?? 0) : 0;
+}
+/**
+ * Validate the flag combination, throwing a user-facing message on the first
+ * problem. Every rejection is loud: an unrecognized `--min-confidence` is an
+ * error, never a silent fall back to the default floor.
+ */
+export function validateImportOpts(flags) {
+    const sources = [flags.fromFactory && 'factory', flags.fromLinear && 'linear'].filter(Boolean);
+    if (sources.length === 0)
+        throw new Error('Pick an import source: --from-linear or --from-factory.');
+    if (sources.length > 1)
+        throw new Error('--from-linear and --from-factory are mutually exclusive — pick one.');
+    const source = sources[0];
+    if (source === 'linear' && (flags.all || flags.minConfidence !== undefined)) {
+        throw new Error('--all and --min-confidence apply to --from-factory only (Linear rows carry no confidence).');
+    }
+    if (flags.all && flags.minConfidence !== undefined) {
+        throw new Error('--all and --min-confidence are mutually exclusive (--all means --min-confidence low).');
+    }
+    let minConfidence = 'high';
+    if (flags.all)
+        minConfidence = 'any';
+    else if (flags.minConfidence !== undefined) {
+        const v = flags.minConfidence.trim().toLowerCase();
+        if (v !== 'low' && v !== 'medium' && v !== 'high') {
+            throw new Error(`Invalid --min-confidence "${flags.minConfidence}" (expected low, medium, or high).`);
+        }
+        minConfidence = v;
+    }
+    return { source, minConfidence, force: flags.force === true };
+}
+/**
+ * Plan the Factory import: same field mapping as before (`path`→`root`,
+ * `repoSlug`→`repo`, `linearProjectId`→`linear.projectId`), now gated on the
+ * row's `confidence`. A row with no confidence field is a guess with no stated
+ * strength, so it ranks below every floor and only `--all` takes it.
+ */
+export function buildFactoryImportCandidates(rows, existing, opts) {
+    const floor = CONFIDENCE_RANK[opts.minConfidence];
+    const defs = [];
+    const skipped = [];
+    // The registry keys rows by `owner/repo` but names them by basename, so two
+    // repos with the same basename in different orgs (grinich/inflow, me/inflow)
+    // arrive as two rows called `inflow`. Without this the second silently
+    // overwrote the first on disk and the run still reported both as imported.
+    const seen = new Set();
+    for (const raw of rows) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const o = raw;
+        const name = typeof o.name === 'string' ? o.name : undefined;
+        if (!name || !isSafeProjectName(name)) {
+            skipped.push({ name: name || '(unnamed)', reason: 'not a usable project name' });
+            continue;
+        }
+        const rank = confidenceRank(o.confidence);
+        if (rank < floor) {
+            const stated = typeof o.confidence === 'string' && o.confidence ? `confidence "${o.confidence}"` : 'no confidence field';
+            skipped.push({ name, reason: `${stated} is below the "${opts.minConfidence}" floor` });
+            continue;
+        }
+        if (seen.has(name)) {
+            skipped.push({ name, reason: 'another row in this registry already claimed the name' });
+            continue;
+        }
+        if (existing.has(name) && !opts.force) {
+            skipped.push({ name, reason: 'already defined — pass --force to overwrite' });
+            continue;
+        }
+        seen.add(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 };
+        defs.push(def);
+    }
+    return { defs, skipped };
+}
+/**
+ * Turn a Linear project name into a definition slug: lowercase, every run of
+ * unusable characters collapsed to one `-`, trimmed of leading/trailing
+ * punctuation, capped at the 64 chars `isSafeProjectName` allows. Returns `''`
+ * when nothing usable survives — the caller skips those loudly.
+ */
+export function slugifyProjectName(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^[-._]+|[-._]+$/g, '')
+        .slice(0, 64)
+        .replace(/[-._]+$/g, '');
+    return isSafeProjectName(slug) ? slug : '';
+}
+/**
+ * Plan the Linear import. Every project becomes a def carrying its `linear`
+ * link; the local checkout is bound **only on an exact normalized-name match**
+ * (`matchLocalCheckoutExact`). The containment fallback that powers the `link`
+ * suggestion is deliberately not used here — "Agents CLI" containing
+ * "agents-cli-web" is a fine hint for a human to confirm, and a silently wrong
+ * `root` on a write path.
+ *
+ * An existing def is preserved field-for-field; only `name` and `linear` are
+ * overwritten, so a hand-set `description`/`contexts`/`integrations` survives a
+ * re-import.
+ */
+export function buildLinearImportCandidates(projects, existing, deps, opts) {
+    const defs = [];
+    const skipped = [];
+    const seen = new Set();
+    for (const p of projects) {
+        const name = slugifyProjectName(p.name);
+        if (!name) {
+            skipped.push({ name: p.name, reason: 'no usable project name (letters, digits, ., _, - only)' });
+            continue;
+        }
+        if (seen.has(name)) {
+            skipped.push({ name: p.name, reason: `another Linear project already claimed the name "${name}"` });
+            continue;
+        }
+        const prior = existing.get(name);
+        if (prior && (prior.root || prior.repo) && !opts.force) {
+            skipped.push({ name, reason: 'existing def already has root/repo — pass --force to relink' });
+            continue;
+        }
+        seen.add(name);
+        const def = { ...prior, name, linear: { projectId: p.id } };
+        if (p.url)
+            def.linear.url = p.url;
+        const dir = matchLocalCheckoutExact(p.name, deps.localDirs);
+        if (dir) {
+            const root = deps.resolveRoot(dir);
+            if (root)
+                def.root = root;
+            const repo = deps.resolveOrigin(dir);
+            if (repo)
+                def.repo = repo;
+        }
+        defs.push(def);
+    }
+    return { defs, skipped };
+}

package/dist/lib/remote-agents-json.d.ts

@@ -2,7 +2,7 @@ export interface RemoteAgentsJsonOptions<T> {
     args: string[];
     noFanoutEnv: string;
     hosts?: string[];
-    parse: (stdout: string, machine: string) => T[];
+    parse: (stdout: string, machine: string) => T[] | RemoteAgentsJsonParseResult<T>;
     /**
      * Suppress the per-device "unreachable — skipped" stderr line. The skipped
      * names still come back in {@link RemoteAgentsJsonResult.skipped}, so a caller
@@ -11,12 +11,25 @@ export interface RemoteAgentsJsonOptions<T> {
      */
     quiet?: boolean;
 }
+export interface RemoteAgentsJsonParseResult<T> {
+    items: T[];
+    valid: boolean;
+}
 export interface RemoteAgentsJsonResult<T> {
     items: T[];
     deviceCount: number;
     /** Devices that were dialed but answered with an error / no CLI / a timeout. */
     skipped: string[];
+    /** Devices that exited successfully but returned invalid JSON for this command. */
+    parseFailed: string[];
+    /** Whether automatic target discovery failed before any peer could be dialed. */
+    discoveryFailed: boolean;
 }
+export declare function normalizeRemoteAgentsJsonParse<T>(parsed: T[] | RemoteAgentsJsonParseResult<T>): RemoteAgentsJsonParseResult<T>;
+export declare function parseRemoteAgentsJsonPayload<T>(stdout: string, machine: string, parse: RemoteAgentsJsonOptions<T>['parse']): {
+    items: T[];
+    parseFailed: boolean;
+};
 /** Build the command one peer runs, with a guard that prevents recursive fan-out. */
 export declare function remoteAgentsJsonCommand(args: string[], noFanoutEnv: string, os?: string): string;
 /** Query explicit hosts, or every registered online peer when hosts is omitted. */