@phnx-labs/agents-cli 1.20.93 → 1.21.1

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. */

package/dist/lib/remote-agents-json.js

@@ -15,6 +15,15 @@ import { loadDevices, isControlDevice, isDialableDevice } from './devices/regist
 import { remoteShellFor, buildWindowsAgentsCommand } from './hosts/remote-cmd.js';
 import { machineId, normalizeHost } from './machine-id.js';
 const REMOTE_TIMEOUT_MS = 12_000;
+export function normalizeRemoteAgentsJsonParse(parsed) {
+    return Array.isArray(parsed) ? { items: parsed, valid: true } : parsed;
+}
+export function parseRemoteAgentsJsonPayload(stdout, machine, parse) {
+    const parsed = normalizeRemoteAgentsJsonParse(parse(stdout, machine));
+    return parsed.valid
+        ? { items: parsed.items, parseFailed: false }
+        : { items: [], parseFailed: true };
+}
 /** Build the command one peer runs, with a guard that prevents recursive fan-out. */
 export function remoteAgentsJsonCommand(args, noFanoutEnv, os) {
     if (remoteShellFor(os) === 'powershell') {
@@ -59,7 +68,7 @@ export async function gatherRemoteAgentsJson(options) {
             devices = await loadDevices();
         }
         catch {
-            return { items: [], deviceCount: 0, skipped: [] };
+            return { items: [], deviceCount: 0, skipped: [], parseFailed: [], discoveryFailed: true };
         }
         for (const device of Object.values(devices)) {
             // Live SSH-probe verdict first, cached tailscale snapshot only as a
@@ -90,6 +99,7 @@ export async function gatherRemoteAgentsJson(options) {
         }
     }
     const skipped = [];
+    const parseFailed = [];
     const results = await Promise.all(targets.map(async (target) => {
         const command = remoteAgentsJsonCommand(options.args, options.noFanoutEnv, target.os);
         const result = await sshCapture(target.target, command);
@@ -100,7 +110,15 @@ export async function gatherRemoteAgentsJson(options) {
             }
             return [];
         }
-        return options.parse(result.stdout, target.machine);
+        const parsed = parseRemoteAgentsJsonPayload(result.stdout, target.machine, options.parse);
+        if (parsed.parseFailed) {
+            parseFailed.push(target.name);
+            if (!options.quiet) {
+                process.stderr.write(chalk.gray(`  ${target.name}: unreachable or no agents CLI — skipped\n`));
+            }
+            return [];
+        }
+        return parsed.items;
     }));
-    return { items: results.flat(), deviceCount: targets.length, skipped };
+    return { items: results.flat(), deviceCount: targets.length, skipped, parseFailed, discoveryFailed: false };
 }

package/dist/lib/routines.d.ts

@@ -293,6 +293,47 @@ export declare function finalizeRunMeta(meta: RunMeta, status: RunMeta['status']
  * catchup/overdue, manual run) gates on this.
  */
 export declare function jobRunsOnThisDevice(config: Pick<JobConfig, 'devices'>): boolean;
+/**
+ * The ONE device that owns a routine — the single daemon allowed to fire it.
+ *
+ * `devices` is an allowlist, and every listed device used to fire
+ * independently, so a routine pinned to two boxes ran **twice** per schedule:
+ * two full agent sessions doing identical work, burning double the quota. On
+ * this fleet seven routines were in that state, e.g. `security-sweep` running
+ * at 15:30:02 on one box and 15:30:03 on the other, both completing.
+ *
+ * Ownership is a pure function of the config — the first entry in normalized
+ * sort order — so every daemon independently reaches the same answer with no
+ * lease, no cross-device coordination, and no split brain when the fleet
+ * partitions. A multi-entry pin is a misconfiguration
+ * ({@link hasAmbiguousDevicePin}); this keeps such a routine running exactly
+ * once instead of silently dropping it, while `validateJob` refuses to create
+ * a new one and `agents doctor` surfaces the existing ones.
+ *
+ * Returns null when the routine is unrestricted (empty or omitted `devices`).
+ */
+export declare function routineOwnerDevice(config: Pick<JobConfig, 'devices'>): string | null;
+/**
+ * Does this routine name more than one distinct device? Such a pin used to mean
+ * "fire on each of them"; it now means "fire only on the first", which is
+ * almost certainly not what the author intended either way — so it is reported
+ * as a misconfiguration rather than silently reinterpreted.
+ */
+export declare function hasAmbiguousDevicePin(config: Pick<JobConfig, 'devices'>): boolean;
+/** One routine whose `devices` names more than one machine, with its resolved owner. */
+export interface AmbiguousDevicePin {
+    name: string;
+    devices: string[];
+    /** The device that now fires it — the rest are inert. */
+    owner: string;
+}
+/**
+ * Every routine carrying a multi-device pin. Surfaced by `agents doctor` and
+ * `agents routines list` so an existing misconfiguration is visible rather than
+ * silently reinterpreted: before ownership became singular each of these fired
+ * once per listed device, doubling the work and the agent spend.
+ */
+export declare function findAmbiguousDevicePins(cwd?: string): AmbiguousDevicePin[];
 /**
  * Resolve the effective host strategy for a job.
  * Bare `host:` without an explicit strategy implies `host` (back-compat with
@@ -487,6 +528,18 @@ export declare function discoverJobsFromRepo(repoPath: string): Array<{
 export declare function jobExists(name: string): boolean;
 /** Get the filesystem path of a job's YAML config file, or null if not found. */
 export declare function getJobPath(name: string): string | null;
+/**
+ * Resolve a routine's YAML across EVERY layer `listJobs`/`readJob` read — user
+ * then system — not just the user dir.
+ *
+ * `getJobPath` is user-layer only because its callers write there. Read paths
+ * that ask "when did this routine come to exist" need the system layer too:
+ * a built-in shipped in the system repo has no user-layer file and no
+ * `createdAt`, so a user-layer-only lookup returns null, the overdue floor is
+ * skipped, and the routine reads as instantly overdue on first daemon start —
+ * exactly the case the floor exists to prevent.
+ */
+export declare function resolveJobFilePath(name: string): string | null;
 /**
  * Parse an "at" time string into a one-shot cron expression.
  * Supports formats like:

package/dist/lib/routines.js

@@ -81,10 +81,67 @@ export function finalizeRunMeta(meta, status, exitCode, opts) {
  * catchup/overdue, manual run) gates on this.
  */
 export function jobRunsOnThisDevice(config) {
-    if (!config.devices || config.devices.length === 0)
+    const owner = routineOwnerDevice(config);
+    // Unrestricted: no pin means fleet-wide by design (`watchdog`, `check-updates`).
+    if (owner === null)
         return true;
-    const self = machineId();
-    return config.devices.some((d) => normalizeHost(d) === self);
+    return owner === machineId();
+}
+/**
+ * The ONE device that owns a routine — the single daemon allowed to fire it.
+ *
+ * `devices` is an allowlist, and every listed device used to fire
+ * independently, so a routine pinned to two boxes ran **twice** per schedule:
+ * two full agent sessions doing identical work, burning double the quota. On
+ * this fleet seven routines were in that state, e.g. `security-sweep` running
+ * at 15:30:02 on one box and 15:30:03 on the other, both completing.
+ *
+ * Ownership is a pure function of the config — the first entry in normalized
+ * sort order — so every daemon independently reaches the same answer with no
+ * lease, no cross-device coordination, and no split brain when the fleet
+ * partitions. A multi-entry pin is a misconfiguration
+ * ({@link hasAmbiguousDevicePin}); this keeps such a routine running exactly
+ * once instead of silently dropping it, while `validateJob` refuses to create
+ * a new one and `agents doctor` surfaces the existing ones.
+ *
+ * Returns null when the routine is unrestricted (empty or omitted `devices`).
+ */
+export function routineOwnerDevice(config) {
+    // A non-array `devices` is a separate validation error; don't throw here and
+    // don't double-report it.
+    if (!Array.isArray(config.devices))
+        return null;
+    const devices = config.devices.map((d) => normalizeHost(String(d))).filter(Boolean);
+    if (devices.length === 0)
+        return null;
+    return [...devices].sort()[0];
+}
+/**
+ * Does this routine name more than one distinct device? Such a pin used to mean
+ * "fire on each of them"; it now means "fire only on the first", which is
+ * almost certainly not what the author intended either way — so it is reported
+ * as a misconfiguration rather than silently reinterpreted.
+ */
+export function hasAmbiguousDevicePin(config) {
+    if (!Array.isArray(config.devices))
+        return false;
+    const devices = new Set(config.devices.map((d) => normalizeHost(String(d))).filter(Boolean));
+    return devices.size > 1;
+}
+/**
+ * Every routine carrying a multi-device pin. Surfaced by `agents doctor` and
+ * `agents routines list` so an existing misconfiguration is visible rather than
+ * silently reinterpreted: before ownership became singular each of these fired
+ * once per listed device, doubling the work and the agent spend.
+ */
+export function findAmbiguousDevicePins(cwd) {
+    return listJobs(cwd)
+        .filter((job) => job.enabled && hasAmbiguousDevicePin(job))
+        .map((job) => ({
+        name: job.name,
+        devices: (job.devices ?? []).map((d) => normalizeHost(d)),
+        owner: routineOwnerDevice(job) ?? '',
+    }));
 }
 /**
  * Resolve the effective host strategy for a job.
@@ -130,7 +187,10 @@ export function checkJobDeviceEligibility(config) {
         return null;
     const allowed = (config.devices ?? []).map((d) => normalizeHost(d));
     const allowedLabel = allowed.join(', ');
-    const firstHost = allowed[0] ?? 'HOST';
+    // The owner is the lowest normalized name, not the first entry as written —
+    // suggesting allowed[0] on an unsorted list points at a device that will
+    // refuse the run for exactly the same reason.
+    const firstHost = routineOwnerDevice(config) ?? allowed[0] ?? 'HOST';
     const message = `Job '${config.name}' can only run on: ${allowedLabel}`;
     const suggestion = `agents routines run ${config.name} --host ${firstHost}`;
     return { message, suggestion, allowedLabel, firstHost };
@@ -251,6 +311,17 @@ function readJobFile(filePath) {
         // treated as unavailable/inert rather than unrestricted.
         if (Object.prototype.hasOwnProperty.call(parsed, 'device'))
             return null;
+        // Fail closed on a malformed `devices` too. Ownership treats a non-array as
+        // "no pin", and the daemon's load path never calls validateJob — so a YAML
+        // typo (`devices: yosemite-s0` instead of a list) would silently promote the
+        // routine to fleet-wide and fire it on EVERY box. Inert-and-loud beats
+        // unrestricted-and-silent.
+        if (Object.prototype.hasOwnProperty.call(parsed, 'devices')
+            && parsed.devices !== undefined
+            && parsed.devices !== null
+            && !Array.isArray(parsed.devices)) {
+            return null;
+        }
         return {
             ...JOB_DEFAULTS,
             ...parsed,
@@ -523,6 +594,14 @@ export function validateJob(config) {
             }
         }
     }
+    // A routine belongs to exactly one device. Listing several used to fire it
+    // once per device — duplicate work, duplicate spend — and making them elect
+    // one owner at runtime would need cross-device coordination nobody wants.
+    if (hasAmbiguousDevicePin(config)) {
+        errors.push(`devices lists ${new Set(config.devices.map((d) => normalizeHost(String(d)))).size} devices; a routine runs on exactly one. ` +
+            'Pin the single device that should own it, e.g. devices: [yosemite-s0]. ' +
+            'Omit devices entirely for a routine that genuinely belongs on every machine.');
+    }
     if (config.catchup !== undefined && typeof config.catchup !== 'boolean') {
         errors.push('catchup must be a boolean (false to skip running a missed fire late)');
     }
@@ -946,6 +1025,28 @@ export function getJobPath(name) {
     }
     return null;
 }
+/**
+ * Resolve a routine's YAML across EVERY layer `listJobs`/`readJob` read — user
+ * then system — not just the user dir.
+ *
+ * `getJobPath` is user-layer only because its callers write there. Read paths
+ * that ask "when did this routine come to exist" need the system layer too:
+ * a built-in shipped in the system repo has no user-layer file and no
+ * `createdAt`, so a user-layer-only lookup returns null, the overdue floor is
+ * skipped, and the routine reads as instantly overdue on first daemon start —
+ * exactly the case the floor exists to prevent.
+ */
+export function resolveJobFilePath(name) {
+    const userPath = getJobPath(name);
+    if (userPath)
+        return userPath;
+    for (const ext of ['.yml', '.yaml']) {
+        const filePath = safeJoin(getSystemRoutinesDir(), name + ext);
+        if (fs.existsSync(filePath))
+            return filePath;
+    }
+    return null;
+}
 /**
  * Parse an "at" time string into a one-shot cron expression.
  * Supports formats like:

package/dist/lib/rules/run-sync.d.ts

@@ -0,0 +1,18 @@
+import type { AgentId } from '../types.js';
+/**
+ * Re-apply the active rules preset for (agent, version) into its version
+ * home when the composed source set has drifted since the last time this ran.
+ * Returns true when the version-home rules file was (re)written.
+ *
+ * No-cwd fingerprint on purpose: the version-home rules file never includes
+ * the project layer (see `staleness/writers/rules.ts` — project rules are
+ * resolved separately, at launch, into the workspace `AGENTS.md` by
+ * `compileRulesForProject`). Fingerprinting with a cwd would pull the project
+ * layer's subrules into the comparison and trigger a pointless version-home
+ * rewrite every time a project's own `.agents/rules/` changes.
+ *
+ * Silent on any failure (no rules.yaml, unknown preset, unsupported agent) —
+ * mirrors `syncResourcesToVersion`'s own catch-and-skip for rules: a bad
+ * preset must never block a launch, and this now also runs on the hot path.
+ */
+export declare function applyActiveRulesPresetAtRun(agent: AgentId, version: string, versionHome: string): boolean;