@phnx-labs/agents-cli 1.22.35 → 1.22.37

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

@@ -1,47 +1,24 @@
 /**
- * Project-level routine opt-in, source tracking, and user-layer sync.
+ * Project routine discovery, source tracking, and user-layer sync.
  *
- * Project YAML under `<project>/.agents/routines/*.yml` is inspection-only by
- * default (a cloned public repo must never auto-fire agent prompts). After an
- * explicit opt-in, routines are materialised into `~/.agents/routines/` with
- * `source:` provenance so the daemon — which only loads user + system layers —
- * can fire them. `syncProjectRoutines` refreshes the user-layer copies when
- * project YAML changes (also invoked on daemon SIGHUP).
+ * Project YAML under `<project>/.agents/routines/*.yml` never fires on its own
+ * (a cloned repo must not auto-run agent prompts). A routine has exactly one
+ * state — enabled or disabled — owned by this device's `meta.deviceRoutines`
+ * list, never by the project YAML's own `enabled:` field. `agents routines
+ * enable <name>` materialises the routine into `~/.agents/routines/` with
+ * `source:` provenance (so the daemon, which loads only user + system layers,
+ * can see it) and flips the device flag on — one action. `discoverProjectRoutines`
+ * surfaces not-yet-materialised routines from the user's registered projects so
+ * `list` shows them as disabled. `syncProjectRoutines` refreshes materialised
+ * copies from their source YAML (also invoked on daemon SIGHUP).
  */
-import { type JobSource } from './routines.js';
+import { type JobConfig, type JobSource } from './routines.js';
 /** Expand `~/…` and resolve to an absolute path. */
 export declare function expandProjectPath(p: string): string;
 /** Store paths home-relative when under $HOME so they travel across machines. */
 export declare function displayProjectPath(abs: string): string;
-/** Project roots currently opted into daemon firing (absolute paths). */
-export declare function listEnabledProjectRoots(): string[];
-/** True when this project root is on the opt-in allowlist. */
-export declare function isProjectRoutinesEnabled(projectRoot: string): boolean;
-/**
- * True when the project's own `agents.yaml` opts into project routines:
- * `routines: { enable: true }`. This is an additional source of opt-in that
- * still requires the project to be present on disk; it does not auto-enable
- * every clone — the project must declare it, and `sync` / `enable-project`
- * still materialises consent into the user layer.
- */
-export declare function projectAgentsYamlEnablesRoutines(projectRoot: string): boolean;
 /** Resolve the project root (parent of `.agents/`) from a cwd, or null. */
 export declare function resolveProjectRoot(cwd?: string): string | null;
-/**
- * Opt a project root into daemon firing. Returns true when newly added,
- * false when it was already enabled.
- */
-export declare function enableProjectRoutines(projectRoot: string): boolean;
-/**
- * Remove a project root from the opt-in allowlist. Optionally deletes the
- * user-layer copies that were materialised from it.
- */
-export declare function disableProjectRoutines(projectRoot: string, opts?: {
-    removeSynced?: boolean;
-}): {
-    removed: boolean;
-    deletedJobs: string[];
-};
 /** Git provenance for a project root (best-effort; never throws). */
 export declare function readProjectGitSource(projectRoot: string): Pick<JobSource, 'repo' | 'branch' | 'commit'>;
 /** List project routine YAML files (name + absolute path). */
@@ -63,11 +40,15 @@ export interface SyncProjectResult {
     }>;
 }
 /**
- * Materialise one project's routines into the user layer.
+ * Refresh one project's already-materialised routines from its source YAML.
  * - Overwrites user copies that already carry matching `source.projectPath`
  * - Never clobbers a hand-authored user routine (no source / different source)
  * - Removes user copies from this project whose YAML disappeared
- * - Activates materialized routines on this device without mutating definitions
+ *
+ * Sync NEVER touches the device enable flag: a routine's enabled/disabled state
+ * is owned solely by `meta.deviceRoutines` (via `agents routines enable/disable`),
+ * never by the project YAML's own `enabled:` field. That is what keeps a cloned
+ * repo from auto-firing — refreshing a definition can never turn it on.
  */
 export declare function syncProjectRoutines(projectRoot: string): SyncProjectResult;
 export interface SyncAllResult {
@@ -75,23 +56,52 @@ export interface SyncAllResult {
     /** Project roots that were listed but missing on disk. */
     missing: string[];
 }
+/** Distinct project roots that already have at least one materialised routine. */
+export declare function materialisedProjectRoots(): string[];
 /**
- * Sync every project root on the user allowlist (`meta.routines.projects`),
- * plus any explicit `extraRoots`. Project `agents.yaml` `routines.enable`
- * alone never opts a path in — enable-project is required.
+ * Refresh every materialised project routine from its source YAML. The set of
+ * roots is derived from what the user has already enabled/materialised (their
+ * `source.projectPath`), not from any allowlist — enabling a routine is the only
+ * thing that brings its project into the refresh set. Also runs on daemon SIGHUP.
  */
 export declare function syncAllProjectRoutines(opts?: {
     extraRoots?: string[];
 }): SyncAllResult;
+/** A project routine available to enable, not yet materialised on this device. */
+export interface DiscoveredProjectRoutine {
+    name: string;
+    projectRoot: string;
+    file: string;
+    /** Display config for `list` (always disabled — enablement is a local act). */
+    config: JobConfig;
+}
 /**
- * Discover project routines at cwd for the setup UX. Returns null when no
- * project `.agents/routines` dir exists.
+ * Project routines from registered projects that are NOT already materialised
+ * in the user layer. These surface in `agents routines list` as disabled rows so
+ * the single enabled/disabled model is visible, and `enable <name>` resolves a
+ * name against them. A routine whose name already exists as a user/system
+ * routine is omitted (that materialised copy is the live one).
  */
-export declare function discoverProjectRoutinesAt(cwd?: string): {
+export declare function discoverProjectRoutines(): DiscoveredProjectRoutine[];
+/**
+ * Resolve a routine name to a project source for `enable <name>`: first the cwd
+ * project, then registered projects. Returns null when the name matches no
+ * project routine, or throws-by-return when it is ambiguous across projects.
+ */
+export declare function findProjectRoutine(name: string, cwd?: string): {
     projectRoot: string;
-    files: Array<{
-        name: string;
-        path: string;
-    }>;
-    enabled: boolean;
+    file: string;
+} | {
+    ambiguous: string[];
 } | null;
+/**
+ * Materialise one project routine into the user layer WITHOUT enabling it. The
+ * caller (`agents routines enable`) flips the device flag separately, so a
+ * materialise can never by itself make a routine fire. Returns the written
+ * config, or an error string.
+ */
+export declare function materialiseProjectRoutine(projectRoot: string, name: string): {
+    job: JobConfig;
+} | {
+    error: string;
+};

package/dist/lib/routines-project.js

@@ -1,21 +1,26 @@
 /**
- * Project-level routine opt-in, source tracking, and user-layer sync.
+ * Project routine discovery, source tracking, and user-layer sync.
  *
- * Project YAML under `<project>/.agents/routines/*.yml` is inspection-only by
- * default (a cloned public repo must never auto-fire agent prompts). After an
- * explicit opt-in, routines are materialised into `~/.agents/routines/` with
- * `source:` provenance so the daemon — which only loads user + system layers —
- * can fire them. `syncProjectRoutines` refreshes the user-layer copies when
- * project YAML changes (also invoked on daemon SIGHUP).
+ * Project YAML under `<project>/.agents/routines/*.yml` never fires on its own
+ * (a cloned repo must not auto-run agent prompts). A routine has exactly one
+ * state — enabled or disabled — owned by this device's `meta.deviceRoutines`
+ * list, never by the project YAML's own `enabled:` field. `agents routines
+ * enable <name>` materialises the routine into `~/.agents/routines/` with
+ * `source:` provenance (so the daemon, which loads only user + system layers,
+ * can see it) and flips the device flag on — one action. `discoverProjectRoutines`
+ * surfaces not-yet-materialised routines from the user's registered projects so
+ * `list` shows them as disabled. `syncProjectRoutines` refreshes materialised
+ * copies from their source YAML (also invoked on daemon SIGHUP).
  */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { execFileSync } from 'child_process';
-import { getProjectAgentsDir, getProjectRoutinesDir, readMeta, updateMeta, ensureAgentsDir, } from './state.js';
-import { readJob, writeJob, setJobEnabled, deleteJob, listJobs, validateJob, } from './routines.js';
+import { getProjectAgentsDir, getProjectRoutinesDir, ensureAgentsDir, } from './state.js';
+import { readJob, writeJob, deleteJob, listJobs, validateJob, } from './routines.js';
 import { parseOwnerRepoFromRemote } from './registry.js';
+import { listProjectDefs, projectDirsAbs } from './projects.js';
 import { isSafeSegmentName } from './paths.js';
 /** Expand `~/…` and resolve to an absolute path. */
 export function expandProjectPath(p) {
@@ -36,52 +41,6 @@ export function displayProjectPath(abs) {
     }
     return resolved;
 }
-/** Project roots currently opted into daemon firing (absolute paths). */
-export function listEnabledProjectRoots() {
-    const meta = readMeta();
-    const raw = meta.routines?.projects ?? [];
-    const out = [];
-    const seen = new Set();
-    for (const p of raw) {
-        if (typeof p !== 'string' || p.trim() === '')
-            continue;
-        const abs = expandProjectPath(p);
-        if (seen.has(abs))
-            continue;
-        seen.add(abs);
-        out.push(abs);
-    }
-    return out;
-}
-/** True when this project root is on the opt-in allowlist. */
-export function isProjectRoutinesEnabled(projectRoot) {
-    const abs = expandProjectPath(projectRoot);
-    return listEnabledProjectRoots().some((p) => p === abs);
-}
-/**
- * True when the project's own `agents.yaml` opts into project routines:
- * `routines: { enable: true }`. This is an additional source of opt-in that
- * still requires the project to be present on disk; it does not auto-enable
- * every clone — the project must declare it, and `sync` / `enable-project`
- * still materialises consent into the user layer.
- */
-export function projectAgentsYamlEnablesRoutines(projectRoot) {
-    const agentsYaml = path.join(expandProjectPath(projectRoot), 'agents.yaml');
-    if (!fs.existsSync(agentsYaml))
-        return false;
-    try {
-        const parsed = yaml.parse(fs.readFileSync(agentsYaml, 'utf-8'));
-        if (!parsed || typeof parsed !== 'object')
-            return false;
-        const routines = parsed.routines;
-        if (!routines || typeof routines !== 'object')
-            return false;
-        return routines.enable === true;
-    }
-    catch {
-        return false;
-    }
-}
 /** Resolve the project root (parent of `.agents/`) from a cwd, or null. */
 export function resolveProjectRoot(cwd = process.cwd()) {
     const agentsDir = getProjectAgentsDir(cwd);
@@ -89,63 +48,6 @@ export function resolveProjectRoot(cwd = process.cwd()) {
         return null;
     return path.dirname(agentsDir);
 }
-/**
- * Opt a project root into daemon firing. Returns true when newly added,
- * false when it was already enabled.
- */
-export function enableProjectRoutines(projectRoot) {
-    const abs = expandProjectPath(projectRoot);
-    const stored = displayProjectPath(abs);
-    let added = false;
-    updateMeta((meta) => {
-        const projects = [...(meta.routines?.projects ?? [])];
-        const already = projects.some((p) => expandProjectPath(p) === abs);
-        if (already)
-            return meta;
-        projects.push(stored);
-        added = true;
-        return {
-            ...meta,
-            routines: {
-                ...(meta.routines ?? {}),
-                projects,
-            },
-        };
-    });
-    return added;
-}
-/**
- * Remove a project root from the opt-in allowlist. Optionally deletes the
- * user-layer copies that were materialised from it.
- */
-export function disableProjectRoutines(projectRoot, opts = {}) {
-    const abs = expandProjectPath(projectRoot);
-    let removed = false;
-    updateMeta((meta) => {
-        const projects = meta.routines?.projects ?? [];
-        const next = projects.filter((p) => expandProjectPath(p) !== abs);
-        if (next.length === projects.length)
-            return meta;
-        removed = true;
-        return {
-            ...meta,
-            routines: {
-                ...(meta.routines ?? {}),
-                projects: next,
-            },
-        };
-    });
-    const deletedJobs = [];
-    if (opts.removeSynced) {
-        for (const job of listJobs()) {
-            if (job.source?.kind === 'project' && expandProjectPath(job.source.projectPath) === abs) {
-                if (deleteJob(job.name))
-                    deletedJobs.push(job.name);
-            }
-        }
-    }
-    return { removed, deletedJobs };
-}
 /** Git provenance for a project root (best-effort; never throws). */
 export function readProjectGitSource(projectRoot) {
     const abs = expandProjectPath(projectRoot);
@@ -216,11 +118,15 @@ function readProjectJobFile(filePath) {
     }
 }
 /**
- * Materialise one project's routines into the user layer.
+ * Refresh one project's already-materialised routines from its source YAML.
  * - Overwrites user copies that already carry matching `source.projectPath`
  * - Never clobbers a hand-authored user routine (no source / different source)
  * - Removes user copies from this project whose YAML disappeared
- * - Activates materialized routines on this device without mutating definitions
+ *
+ * Sync NEVER touches the device enable flag: a routine's enabled/disabled state
+ * is owned solely by `meta.deviceRoutines` (via `agents routines enable/disable`),
+ * never by the project YAML's own `enabled:` field. That is what keeps a cloned
+ * repo from auto-firing — refreshing a definition can never turn it on.
  */
 export function syncProjectRoutines(projectRoot) {
     ensureAgentsDir();
@@ -244,37 +150,41 @@ export function syncProjectRoutines(projectRoot) {
     const seenNames = new Set();
     for (const file of files) {
         seenNames.add(file.name);
+        // Refresh only routines the user already materialised from THIS project.
+        // A project file with no existing user-layer copy is "available, not
+        // enabled" — it surfaces via `discoverProjectRoutines` and is materialised
+        // by `agents routines enable <name>`, never auto-pulled by a refresh.
+        const existing = readJob(file.name);
+        if (!existing)
+            continue;
+        const existingSource = existing.source;
+        const fromThisProject = existingSource?.kind === 'project'
+            && expandProjectPath(existingSource.projectPath) === abs;
+        if (!fromThisProject) {
+            result.skipped.push({
+                name: file.name,
+                reason: existingSource
+                    ? `user-layer routine already exists from another source (${existingSource.projectPath})`
+                    : 'user-layer routine already exists (hand-authored); not overwriting without source match',
+            });
+            continue;
+        }
         const job = readProjectJobFile(file.path);
         if (!job) {
             result.errors.push({ name: file.name, error: 'unreadable or invalid YAML' });
             continue;
         }
-        const existing = readJob(file.name);
-        if (existing) {
-            const existingSource = existing.source;
-            const fromThisProject = existingSource?.kind === 'project'
-                && expandProjectPath(existingSource.projectPath) === abs;
-            if (!fromThisProject) {
-                result.skipped.push({
-                    name: file.name,
-                    reason: existingSource
-                        ? `user-layer routine already exists from another source (${existingSource.projectPath})`
-                        : 'user-layer routine already exists (hand-authored); not overwriting without source match',
-                });
-                continue;
-            }
-            // Preserve user-layer devices pin when project YAML omits it (same overlay
-            // semantics as listJobs project discovery).
-            if (job.devices === undefined && existing.devices && existing.devices.length > 0) {
-                job.devices = existing.devices;
-            }
-            // Carry the original creation stamp across. A sync rebuilds the config
-            // from the PROJECT yaml, which never carries `createdAt`, so without this
-            // every `agents routines sync` would re-stamp it to now — walking the
-            // overdue floor forward and hiding real missed fires for project routines.
-            if (existing.createdAt)
-                job.createdAt = existing.createdAt;
+        // Preserve user-layer devices pin when project YAML omits it (same overlay
+        // semantics as listJobs project discovery).
+        if (job.devices === undefined && existing.devices && existing.devices.length > 0) {
+            job.devices = existing.devices;
         }
+        // Carry the original creation stamp across. A sync rebuilds the config
+        // from the PROJECT yaml, which never carries `createdAt`, so without this
+        // every `agents routines sync` would re-stamp it to now — walking the
+        // overdue floor forward and hiding real missed fires for project routines.
+        if (existing.createdAt)
+            job.createdAt = existing.createdAt;
         // Surface repo for list/display when project has a GitHub origin.
         if (git.repo && !job.repo)
             job.repo = git.repo;
@@ -286,8 +196,9 @@ export function syncProjectRoutines(projectRoot) {
             continue;
         }
         try {
+            // Refresh the definition only. Enablement lives in meta.deviceRoutines and
+            // is never derived from the project YAML here.
             writeJob(job);
-            setJobEnabled(job.name, job.enabled);
             result.synced.push(file.name);
         }
         catch (err) {
@@ -307,13 +218,23 @@ export function syncProjectRoutines(projectRoot) {
     }
     return result;
 }
+/** Distinct project roots that already have at least one materialised routine. */
+export function materialisedProjectRoots() {
+    const roots = new Set();
+    for (const job of listJobs()) {
+        if (job.source?.kind === 'project')
+            roots.add(expandProjectPath(job.source.projectPath));
+    }
+    return [...roots];
+}
 /**
- * Sync every project root on the user allowlist (`meta.routines.projects`),
- * plus any explicit `extraRoots`. Project `agents.yaml` `routines.enable`
- * alone never opts a path in — enable-project is required.
+ * Refresh every materialised project routine from its source YAML. The set of
+ * roots is derived from what the user has already enabled/materialised (their
+ * `source.projectPath`), not from any allowlist — enabling a routine is the only
+ * thing that brings its project into the refresh set. Also runs on daemon SIGHUP.
  */
 export function syncAllProjectRoutines(opts = {}) {
-    const roots = new Set(listEnabledProjectRoots());
+    const roots = new Set(materialisedProjectRoots());
     for (const r of opts.extraRoots ?? [])
         roots.add(expandProjectPath(r));
     const projects = [];
@@ -328,22 +249,132 @@ export function syncAllProjectRoutines(opts = {}) {
     return { projects, missing };
 }
 /**
- * Discover project routines at cwd for the setup UX. Returns null when no
- * project `.agents/routines` dir exists.
+ * Absolute local checkout roots for every registered project, deduped. This is
+ * the discovery universe for project routines: bounded to projects the user
+ * registered (`agents projects`), never an arbitrary filesystem scan.
  */
-export function discoverProjectRoutinesAt(cwd = process.cwd()) {
-    const projectRoot = resolveProjectRoot(cwd);
-    if (!projectRoot)
-        return null;
-    const routinesDir = getProjectRoutinesDir(projectRoot);
-    if (!routinesDir || !fs.existsSync(routinesDir))
-        return null;
-    const files = listProjectRoutineFiles(projectRoot);
-    if (files.length === 0)
+function registeredProjectRoots() {
+    const roots = new Set();
+    for (const def of listProjectDefs()) {
+        for (const dir of projectDirsAbs(def, { forRemote: false })) {
+            if (dir)
+                roots.add(path.resolve(dir));
+        }
+    }
+    return [...roots];
+}
+/**
+ * Project routines from registered projects that are NOT already materialised
+ * in the user layer. These surface in `agents routines list` as disabled rows so
+ * the single enabled/disabled model is visible, and `enable <name>` resolves a
+ * name against them. A routine whose name already exists as a user/system
+ * routine is omitted (that materialised copy is the live one).
+ */
+export function discoverProjectRoutines() {
+    const materialisedNames = new Set(listJobs().map((j) => j.name));
+    const out = [];
+    const seen = new Set();
+    for (const root of registeredProjectRoots()) {
+        const files = listProjectRoutineFiles(root).filter((f) => !materialisedNames.has(f.name) && !seen.has(f.name));
+        if (files.length === 0)
+            continue;
+        const git = readProjectGitSource(root); // once per root, not per routine
+        for (const file of files) {
+            const job = readProjectJobFile(file.path);
+            if (!job)
+                continue;
+            seen.add(file.name);
+            job.name = file.name;
+            job.source = {
+                kind: 'project',
+                projectPath: expandProjectPath(root),
+                ...(git.repo ? { repo: git.repo } : {}),
+                ...(git.branch ? { branch: git.branch } : {}),
+                ...(git.commit ? { commit: git.commit } : {}),
+            };
+            if (git.repo && !job.repo)
+                job.repo = git.repo;
+            job.enabled = false; // available, not enabled — never inferred from the repo YAML
+            out.push({ name: file.name, projectRoot: expandProjectPath(root), file: file.path, config: job });
+        }
+    }
+    return out;
+}
+/**
+ * Resolve a routine name to a project source for `enable <name>`: first the cwd
+ * project, then registered projects. Returns null when the name matches no
+ * project routine, or throws-by-return when it is ambiguous across projects.
+ */
+export function findProjectRoutine(name, cwd = process.cwd()) {
+    const cwdRoot = resolveProjectRoot(cwd);
+    if (cwdRoot) {
+        const match = listProjectRoutineFiles(cwdRoot).find((f) => f.name === name);
+        if (match)
+            return { projectRoot: expandProjectPath(cwdRoot), file: match.path };
+    }
+    const hits = [];
+    const seenRoots = new Set();
+    for (const root of registeredProjectRoots()) {
+        const abs = expandProjectPath(root);
+        if (seenRoots.has(abs))
+            continue;
+        seenRoots.add(abs);
+        const match = listProjectRoutineFiles(abs).find((f) => f.name === name);
+        if (match)
+            hits.push({ projectRoot: abs, file: match.path });
+    }
+    if (hits.length === 0)
         return null;
-    return {
-        projectRoot,
-        files,
-        enabled: isProjectRoutinesEnabled(projectRoot) || projectAgentsYamlEnablesRoutines(projectRoot),
+    if (hits.length > 1)
+        return { ambiguous: hits.map((h) => displayProjectPath(h.projectRoot)) };
+    return hits[0];
+}
+/**
+ * Materialise one project routine into the user layer WITHOUT enabling it. The
+ * caller (`agents routines enable`) flips the device flag separately, so a
+ * materialise can never by itself make a routine fire. Returns the written
+ * config, or an error string.
+ */
+export function materialiseProjectRoutine(projectRoot, name) {
+    ensureAgentsDir();
+    const abs = expandProjectPath(projectRoot);
+    const match = listProjectRoutineFiles(abs).find((f) => f.name === name);
+    if (!match)
+        return { error: `no routine '${name}' under ${displayProjectPath(abs)}/.agents/routines` };
+    const job = readProjectJobFile(match.path);
+    if (!job)
+        return { error: `routine '${name}' is unreadable or invalid YAML` };
+    const existing = readJob(name);
+    if (existing) {
+        const src = existing.source;
+        const fromThisProject = src?.kind === 'project' && expandProjectPath(src.projectPath) === abs;
+        if (!fromThisProject) {
+            return {
+                error: src
+                    ? `a routine named '${name}' already exists from another source (${src.projectPath})`
+                    : `a hand-authored routine named '${name}' already exists; rename one before enabling`,
+            };
+        }
+        if (existing.createdAt)
+            job.createdAt = existing.createdAt;
+        if (job.devices === undefined && existing.devices && existing.devices.length > 0) {
+            job.devices = existing.devices;
+        }
+    }
+    const git = readProjectGitSource(abs);
+    job.name = name;
+    job.source = {
+        kind: 'project',
+        projectPath: abs,
+        ...(git.repo ? { repo: git.repo } : {}),
+        ...(git.branch ? { branch: git.branch } : {}),
+        ...(git.commit ? { commit: git.commit } : {}),
     };
+    if (git.repo && !job.repo)
+        job.repo = git.repo;
+    const errors = validateJob(job);
+    if (errors.length > 0)
+        return { error: errors.join('; ') };
+    writeJob(job);
+    return { job };
 }

package/dist/lib/routines.d.ts

@@ -543,15 +543,14 @@ export declare function checkJobDeviceEligibility(config: Pick<JobConfig, 'name'
 /**
  * List all job configs, scanning project > user > system routine dirs.
  * Higher layers shadow lower ones of the same name (first-seen wins): a project
- * routine shadows a user routine, and a user routine shadows a built-in system
- * routine (`~/.agents/.system/routines/`, shipped via gh:phnx-labs/.agents-system).
+ * routine shadows a user routine, and a user routine shadows a system routine
+ * (`~/.agents/.system/routines/`, shipped via gh:phnx-labs/.agents-system).
  * When a same-name project routine wins for inspection, the user-layer
  * `devices` allowlist is overlaid only if the project routine does not declare
  * its own allowlist, so CWD project discovery cannot hide an operational fleet
  * pin or erase a project-authored one.
  * Project discovery is opt-in via `cwd`; the daemon (which calls `listJobs()`
- * with no argument) sees user + system routines, so a built-in routine fires for
- * every install unless the user overrides or disables it by name.
+ * with no argument) sees user + system routines.
  */
 export declare function listJobs(cwd?: string): JobConfig[];
 /**
@@ -560,10 +559,29 @@ export declare function listJobs(cwd?: string): JobConfig[];
  * the project routine does not declare its own allowlist, for the same reason
  * as listJobs().
  * Project discovery is opt-in via `cwd`; daemon callers pass no argument and
- * resolve user + system routines (a user routine of the same name shadows a
- * built-in system routine).
+ * resolve user + system routines.
  */
 export declare function readJob(name: string, cwd?: string): JobConfig | null;
+/**
+ * The outcome of reading one routine file: a config, or the reason it is inert.
+ * Every `problem` here means the daemon will not run the routine.
+ */
+export type RoutineReadResult = {
+    config: JobConfig;
+    problem: null;
+} | {
+    config: null;
+    problem: string;
+};
+/**
+ * Read one routine file, preserving WHY it failed.
+ *
+ * `readJobFile` collapses all four fail-closed paths to `null`, which is right
+ * for the loaders (an inert routine must not run) but leaves a broken routine
+ * invisible in every view — the one routine an operator most needs to see. Same
+ * reading, reason kept, for diagnostic surfaces like `agents inspect --routines`.
+ */
+export declare function readJobFileResult(filePath: string): RoutineReadResult;
 /** Write a job config to disk, omitting fields that match defaults.
  *
  * Updates the one existing supported extension (.yml or .yaml) atomically.
@@ -732,6 +750,23 @@ export declare function discoverJobsFromRepo(repoPath: string): Array<{
 }>;
 /** Check whether a job with the given name exists on disk. */
 export declare function jobExists(name: string): boolean;
+/**
+ * True when `sourcePath` already IS the canonical user-layer file for `name`.
+ *
+ * `agents routines add <file>` copies a definition into the routines dir, but
+ * users routinely point it at the file that already lives there — the release
+ * train's own `~/.agents/routines/release-train.yml`. `writeJob` would then
+ * re-serialize that file in place and, per {@link serializeJob}, delete every
+ * key absent from the canonical output — silently dropping the legacy
+ * `devices:` pin from config tracked in the git-backed `~/.agents` repo
+ * (RUSH-2517). Callers use this to skip the write when there is nothing to
+ * copy.
+ *
+ * Compares real paths so a symlinked `~/.agents` (the normal layout) still
+ * matches, and falls back to a resolved-path compare when either side cannot be
+ * realpath'd.
+ */
+export declare function isCanonicalRoutineSource(sourcePath: string, 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;
 /**