@phnx-labs/agents-cli 1.22.39 → 1.22.41

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

@@ -7,7 +7,7 @@
  * launch inside (the directory ABOVE the git root) and cached in `agents.yaml`
  * so later runs resolve a bare slug from anywhere. It is stored home-relative
  * (`~/…`) when it sits under `$HOME`, so the SAME value resolves on a remote
- * host whose home differs (`/home/<user>` vs `/Users/<user>`): a `--host` run
+ * host whose home differs (`/home/<user>` vs `/Users/<user>`): a `--device` run
  * keeps the `~` and lets the remote login shell expand it (see `remoteCdPrefix`
  * in `hosts/dispatch.ts`), while a local run expands `~` against the local home.
  */
@@ -42,7 +42,7 @@ export declare function homeRemainder(p: string): string | null;
  * caller gave no `--cwd`/`--remote-cwd` (and for an interactive `agents ssh`
  * login with no command).
  *
- * Without this a `--host` run — or an `agents ssh <device>` login — lands in the
+ * Without this a `--device` run — or an `agents ssh <device>` login — lands in the
  * remote `$HOME`, so an agent launched from a repo starts with no project
  * context and the user has to `cd` by hand. Only a cwd under the LOCAL home is
  * mirrored — that is the part with a meaningful remote analogue (`~/src/x`

package/dist/lib/project-root.js

@@ -7,7 +7,7 @@
  * launch inside (the directory ABOVE the git root) and cached in `agents.yaml`
  * so later runs resolve a bare slug from anywhere. It is stored home-relative
  * (`~/…`) when it sits under `$HOME`, so the SAME value resolves on a remote
- * host whose home differs (`/home/<user>` vs `/Users/<user>`): a `--host` run
+ * host whose home differs (`/home/<user>` vs `/Users/<user>`): a `--device` run
  * keeps the `~` and lets the remote login shell expand it (see `remoteCdPrefix`
  * in `hosts/dispatch.ts`), while a local run expands `~` against the local home.
  */
@@ -80,7 +80,7 @@ export function homeRemainder(p) {
  * caller gave no `--cwd`/`--remote-cwd` (and for an interactive `agents ssh`
  * login with no command).
  *
- * Without this a `--host` run — or an `agents ssh <device>` login — lands in the
+ * Without this a `--device` run — or an `agents ssh <device>` login — lands in the
  * remote `$HOME`, so an agent launched from a repo starts with no project
  * context and the user has to `cd` by hand. Only a cwd under the LOCAL home is
  * mirrored — that is the part with a meaningful remote analogue (`~/src/x`

package/dist/lib/project-status.js

@@ -15,7 +15,7 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import chalk from 'chalk';
 import { projectNameForCwd } from './projects.js';
-import { readRecentActivity } from './activity.js';
+import { readRecentActivity } from './feed/activity.js';
 const execFileAsync = promisify(execFile);
 /**
  * How many recent merges `gh` is asked for. A repo busy enough that all of them

package/dist/lib/projects.d.ts

@@ -40,6 +40,18 @@ export interface ProjectRepo {
      */
     path?: string;
 }
+/**
+ * One checkout target for `projects pull`: a home-relative path plus the
+ * expected GitHub slug so the pull step can verify the remote matches before
+ * fast-forwarding. `expectedSlug` is absent when a bound dir has no declared
+ * slug (the pull still fast-forwards; it just skips the slug check).
+ */
+export interface ProjectRepoTarget {
+    /** Home-relative path — re-roots on each fleet device. */
+    path: string;
+    /** Expected GitHub slug (`owner/repo`) for the remote; absent = unchecked. */
+    expectedSlug?: string;
+}
 /**
  * A described context anchor: a subdirectory plus what it is. Agents starting on
  * the project read `purpose` to know where to look — an indexed starting point,
@@ -151,6 +163,17 @@ export declare function removeProjectDef(name: string): boolean;
  * expanded against the local home. Returns undefined when neither is set.
  */
 export declare function projectBasePath(def: ProjectDef, forRemote: boolean): string | undefined;
+/**
+ * All checkout targets for a project definition, each tagged with its expected
+ * GitHub slug. The primary root carries `def.repo`; each `repos[i].path`
+ * carries `repos[i].slug`. Paths are home-relative (re-root per fleet device)
+ * and include missing checkouts so a remote peer can answer `missing` for them.
+ *
+ * This is the single authoritative expansion for both `projects status` (via
+ * {@link projectProbeTargets}) and `projects pull`, so the two commands always
+ * operate on exactly the same set of directories.
+ */
+export declare function projectRepoTargetsForDef(def: ProjectDef): ProjectRepoTarget[];
 /**
  * The directories `projects status` probes across the fleet: the repo root plus
  * every bound checkout, home-relative so each host re-roots them, and including

package/dist/lib/projects.js

@@ -317,18 +317,41 @@ function projectDirList(def, opts) {
     }
     return out;
 }
+/**
+ * All checkout targets for a project definition, each tagged with its expected
+ * GitHub slug. The primary root carries `def.repo`; each `repos[i].path`
+ * carries `repos[i].slug`. Paths are home-relative (re-root per fleet device)
+ * and include missing checkouts so a remote peer can answer `missing` for them.
+ *
+ * This is the single authoritative expansion for both `projects status` (via
+ * {@link projectProbeTargets}) and `projects pull`, so the two commands always
+ * operate on exactly the same set of directories.
+ */
+export function projectRepoTargetsForDef(def) {
+    const targets = [];
+    const seen = new Set();
+    const addTarget = (rawPath, expectedSlug) => {
+        const abs = path.resolve(expandLocalHome(rawPath));
+        if (seen.has(abs))
+            return;
+        seen.add(abs);
+        targets.push({ path: toHomeRelative(abs), expectedSlug });
+    };
+    if (def.root && def.root.length > 0)
+        addTarget(def.root, def.repo);
+    for (const r of def.repos ?? []) {
+        if (r.path && r.path.length > 0)
+            addTarget(r.path, r.slug);
+    }
+    return targets;
+}
 /**
  * The directories `projects status` probes across the fleet: the repo root plus
  * every bound checkout, home-relative so each host re-roots them, and including
  * directories absent here so a peer can still answer `✗ missing` for them.
  */
 export function projectProbeTargets(def) {
-    return projectDirList(def, {
-        primary: def.root,
-        forRemote: true,
-        keepMissing: true,
-        joinSubpath: false,
-    });
+    return projectRepoTargetsForDef(def).map((t) => t.path);
 }
 /**
  * The directories an agent spawned on this project should reach: the cwd first

package/dist/lib/refresh.d.ts

@@ -30,4 +30,15 @@ export interface RefreshOptions {
  *
  * Idempotent — safe to run repeatedly. No network operations.
  */
-export declare function refresh(options?: RefreshOptions): Promise<void>;
+/**
+ * What a reconcile pass refused to write, so callers can report it.
+ *
+ * `refresh` used to return void, so a resource agents-cli declined to write was
+ * visible only on the interactive path — `agents sync --yes` and the
+ * `--device all` fan-out reported a clean sync (RUSH-2700).
+ */
+export interface RefreshResult {
+    /** User-facing sentences, one per refused resource, prefixed with the agent. */
+    declined: string[];
+}
+export declare function refresh(options?: RefreshOptions): Promise<RefreshResult>;

package/dist/lib/refresh.js

@@ -18,11 +18,11 @@ import { capableAgents } from './capabilities.js';
 import { AGENTS, MANAGED_AGENT_IDS, getAllCliStates, registerMcpToTargets, agentLabel, } from './agents.js';
 import { readManifest, MANIFEST_FILENAME } from './manifest.js';
 import { getUserAgentsDir } from './state.js';
-import { installVersion, listInstalledVersions, isVersionIsolated, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from './versions.js';
+import { installVersion, listInstalledVersions, isVersionIsolated, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from './installations/versions.js';
 import { listCliStatus, installCli, describeMethod, describeCheck, selectInstallMethod, } from './cli-resources.js';
 import { ensureShimCurrent, isShimsInPath, addShimsToPath, getPathSetupInstructions, switchConfigSymlink, switchHomeFileSymlinks, } from './shims.js';
 import { parseHookManifest, registerHooksToSettings } from './hooks.js';
-import { isPromptCancelled } from '../commands/utils.js';
+import { isPromptCancelled } from './format.js';
 /**
  * Old repo layout stored promptcuts under claude/promptcuts.yaml (agent-scoped).
  * The new layout is `~/.agents/.system/promptcuts.yaml` at the repo root — the
@@ -49,19 +49,15 @@ function migratePromptcutsToRoot(agentsDir, quiet = false) {
         }
     }
 }
-/**
- * Re-materialize local state from declared configuration: install CLI versions,
- * register MCP servers, sync resources to version homes, register hooks, add
- * shims to PATH, prompt for missing defaults, install declared host-CLIs.
- *
- * Idempotent — safe to run repeatedly. No network operations.
- */
 export async function refresh(options = {}) {
     const { agentFilter, skipPrompts = false, skipClis = false, quiet = false } = options;
     const agentsDir = getUserAgentsDir();
     // Gate every human progress line so --json / fleet fan-out can parse stdout.
     const log = (...args) => { if (!quiet)
         console.log(...args); };
+    // Resources this pass refused to write, surfaced by the caller. An empty
+    // synced list cannot also mean "declined and here is why" (RUSH-2700).
+    const declined = [];
     migratePromptcutsToRoot(agentsDir, quiet);
     const manifest = readManifest(agentsDir);
     if (!manifest) {
@@ -194,6 +190,9 @@ export async function refresh(options = {}) {
                         kinds.add('mcp');
                     if (syncResult.plugins.length > 0)
                         kinds.add('plugins');
+                    for (const reason of syncResult.declined) {
+                        declined.push(`${agentLabel(agentId)}@${ver}: ${reason}`);
+                    }
                 }
                 if (kinds.size > 0) {
                     const verNote = versionsToSync.length > 1
@@ -347,4 +346,12 @@ export async function refresh(options = {}) {
             log(chalk.yellow(`CLI install skipped: ${err.message}`));
         }
     }
+    // A resource agents-cli refused to write is reported, never swallowed —
+    // an empty synced list on its own reads as "nothing to do" (RUSH-2700).
+    if (declined.length > 0) {
+        log(chalk.yellow('Not written:'));
+        for (const reason of declined)
+            log(`  ${chalk.yellow(reason)}`);
+    }
+    return { declined };
 }

package/dist/lib/registry.d.ts

@@ -93,8 +93,15 @@ export declare function resolvePackage(identifier: string): Promise<ResolvedPack
 /** Lowercase hex sha256 of a file's bytes. Small files only (SKILL.md). */
 export declare function sha256OfFile(file: string): string;
 /**
- * Parse an 'owner/repo' slug from a git remote URL (https or scp-style ssh).
- * Returns null if the URL is not a recognizable GitHub-style remote.
+ * Parse an 'owner/repo' slug from a git remote URL (https or scp-style ssh) or
+ * a filesystem-path remote whose path is slug-shaped (`…/github.com/owner/repo`).
+ * Returns null if the remote is not a recognizable GitHub-style shape.
+ *
+ * Backslashes are folded to forward slashes first: a real git URL never
+ * contains one, but a local-path remote on Windows does
+ * (`C:\…\github.com\org\a.git`), and without the fold the same remote that
+ * parses as `org/a` on POSIX returns null on win32 — which made the
+ * projects-pull slug verification fail closed as `blocked` there (RUSH-2694).
  */
 export declare function parseOwnerRepoFromRemote(remoteUrl: string): string | null;
 /**

package/dist/lib/registry.js

@@ -10,7 +10,7 @@ import * as path from 'path';
 import { createHash } from 'crypto';
 import { DEFAULT_REGISTRIES, SEEDED_REGISTRIES } from './types.js';
 import { readMeta, writeMeta } from './state.js';
-import { discoverSkillsFromRepo } from './skills.js';
+import { discoverSkillsFromRepo } from './plugins/skills.js';
 const UNSAFE_PACKAGE_SPEC_CHARS = /[;&|`$\s\x00-\x1f\x7f]/;
 const NPM_SPEC_PATTERN = /^(@[a-z0-9][a-z0-9-_.]*\/)?[a-z0-9][a-z0-9-_.]*(@[A-Za-z0-9._+-]+)?$/;
 const PYPI_SPEC_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*(\[[A-Za-z0-9,_-]+\])?(==[A-Za-z0-9._-]+)?$/;
@@ -481,11 +481,18 @@ export function sha256OfFile(file) {
     return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
 }
 /**
- * Parse an 'owner/repo' slug from a git remote URL (https or scp-style ssh).
- * Returns null if the URL is not a recognizable GitHub-style remote.
+ * Parse an 'owner/repo' slug from a git remote URL (https or scp-style ssh) or
+ * a filesystem-path remote whose path is slug-shaped (`…/github.com/owner/repo`).
+ * Returns null if the remote is not a recognizable GitHub-style shape.
+ *
+ * Backslashes are folded to forward slashes first: a real git URL never
+ * contains one, but a local-path remote on Windows does
+ * (`C:\…\github.com\org\a.git`), and without the fold the same remote that
+ * parses as `org/a` on POSIX returns null on win32 — which made the
+ * projects-pull slug verification fail closed as `blocked` there (RUSH-2694).
  */
 export function parseOwnerRepoFromRemote(remoteUrl) {
-    const s = remoteUrl.trim().replace(/\.git$/, '');
+    const s = remoteUrl.trim().replace(/\\/g, '/').replace(/\.git$/, '');
     // https://github.com/owner/repo  or  git@github.com:owner/repo
     const m = s.match(/github\.com[/:]([^/]+\/[^/]+)$/);
     return m ? m[1] : null;

package/dist/lib/resources.d.ts

@@ -3,9 +3,9 @@
  * Scans filesystem (source of truth) to find all installed resources for an agent.
  */
 import type { AgentId } from './types.js';
-import { type SkillParseError } from './skills.js';
+import { type SkillParseError } from './plugins/skills.js';
 /** Resource kind — matches the subdirectory name under each repo root. */
-export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'clis' | 'permissions' | 'subagents' | 'workflows' | 'profiles' | 'secrets';
+export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'clis' | 'permissions' | 'subagents' | 'workflows' | 'profiles' | 'routers' | 'secrets';
 /** A resource resolved with its origin. */
 export interface ResolvedResource {
     name: string;

package/dist/lib/resources.js

@@ -6,10 +6,10 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, listInstalledMcpsWithScope } from './agents.js';
 import { listInstalledCommandsWithScope, parseCommandMetadata } from './commands.js';
-import { listInstalledSkillsWithScope, parseSkillMetadata } from './skills.js';
+import { listInstalledSkillsWithScope, parseSkillMetadata } from './plugins/skills.js';
 import { listOnDiskHooks } from './resource-inventory.js';
 import { listInstalledInstructionsWithScope } from './rules/rules.js';
-import { getEffectiveHome } from './versions.js';
+import { getEffectiveHome } from './installations/versions.js';
 import { listMcpServerConfigs } from './mcp.js';
 import { WorkflowsHandler } from './resources/workflows.js';
 import { isCapable } from './capabilities.js';

package/dist/lib/routers.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Router management -- named, task-typed allowlists of (harness, model/tier,
+ * account) that constrain an Agent Router decision. A router is a
+ * generalization of a profile (a profile ≡ a router pinned to one harness and
+ * one account). Stored as YAML files under ~/.agents/routers/.
+ *
+ * Routers resolve as a layered resource (project > user > system, like other
+ * resources -- see resources.ts) but are always CREATED in the user layer,
+ * mirroring profiles.ts.
+ */
+/** Per-harness allowlist inside a router: eligible models/tiers + linked accounts. */
+export interface RouterHarnessAllowlist {
+    /** Concrete model ids and/or tier tokens (cheap|default|best|ultra) eligible under this router. */
+    models: string[];
+    /** Durable credential accounts eligible under this router. Routing is limited to these. */
+    accounts?: string[];
+}
+/** A named router: a reusable, task-typed allowlist of harnesses x models/tiers x accounts. */
+export interface Router {
+    name: string;
+    /** Free-text task type this router serves (e.g. "research", "prod-refactor"). */
+    task?: string;
+    /** Allowlist -- only these harness x model/tier x account combos are eligible under this router. */
+    harnesses: Record<string, RouterHarnessAllowlist>;
+    /** Scoped policy weights, applied within the router (consumed by routing, a later ticket). */
+    weights?: {
+        cost?: number;
+        success?: number;
+        headroom?: number;
+    };
+    /** Opt-in re-route of a pinned target when it's exhausted (consumed by routing, a later ticket). */
+    hijack?: boolean;
+}
+/** Directory this machine writes router YAML files to (user layer). */
+export declare function routersDir(): string;
+/** Validate a router name against the allowed pattern. Throws on invalid input. */
+export declare function validateRouterName(name: string): void;
+/** Check whether a router resolves, project > user > system (like other resources). */
+export declare function routerExists(name: string, cwd?: string): boolean;
+/**
+ * The layer a router currently resolves from ('project' | 'user' | 'system' |
+ * an extra-repo alias), or null if it doesn't resolve. `writeRouter` and
+ * `deleteRouter` only ever touch the user layer, so a caller that edits or
+ * removes a router MUST check this first -- editing a router that resolves
+ * from a non-user layer would silently write to a user-layer file that stays
+ * permanently shadowed (the edit "succeeds" but is never read back).
+ */
+export declare function routerSource(name: string, cwd?: string): string | null;
+/** Read a router, resolved project > user > system. Throws if not found or malformed. */
+export declare function readRouter(name: string, cwd?: string): Router;
+/** Write a router to disk atomically (write-to-tmp then rename). Always writes the user layer. */
+export declare function writeRouter(router: Router): void;
+/** Delete a router from the user layer. Returns false if it did not exist there. */
+export declare function deleteRouter(name: string): boolean;
+/**
+ * Fail-loud token validation (E1 of the Agent Router spec): a router MUST NOT
+ * persist a harness id or model/tier token this machine cannot vouch for.
+ * Throws naming the first invalid token found; the caller (route.ts) never
+ * calls {@link writeRouter} when this throws, so an invalid `create`/`allow`
+ * writes nothing.
+ *
+ * A harness id must be a real, registered agent (`AGENTS` in agents.ts) --
+ * checked regardless of whether that harness is installed on this machine,
+ * since a router is fleet-wide config and the harness may only run
+ * elsewhere. A model/tier token is valid when it is one of the four
+ * cross-harness tier tokens (cheap|default|best|ultra, always installable-
+ * agnostic), OR a concrete model id this machine can actually verify: either
+ * one of the harness's resolved tier rungs (`resolveTierMap` -- covers
+ * curated/no-catalog harnesses like Droid with zero install required) or a
+ * member of its extracted catalog (`getModelCatalog`, when a version of that
+ * harness is installed here). A concrete id for a harness with neither --
+ * not installed here, no curated ladder -- cannot be verified and is
+ * rejected rather than accepted unverified.
+ */
+export declare function validateRouter(router: Router): void;
+/**
+ * List every router resolved project > user > system (deduplicated union,
+ * project wins on a name collision -- same precedence as {@link resolveResource}).
+ * Malformed files are silently skipped, surfaced via `agents route show <name>`.
+ */
+export declare function listRouters(cwd?: string): Router[];

package/dist/lib/routers.js

@@ -0,0 +1,153 @@
+/**
+ * Router management -- named, task-typed allowlists of (harness, model/tier,
+ * account) that constrain an Agent Router decision. A router is a
+ * generalization of a profile (a profile ≡ a router pinned to one harness and
+ * one account). Stored as YAML files under ~/.agents/routers/.
+ *
+ * Routers resolve as a layered resource (project > user > system, like other
+ * resources -- see resources.ts) but are always CREATED in the user layer,
+ * mirroring profiles.ts.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getUserAgentsDir } from './state.js';
+import { resolveResource, listResources } from './resources.js';
+import { ALL_AGENT_IDS } from './agents.js';
+import { isTierToken, resolveTierMap, MODEL_TIERS } from './model-tiers.js';
+import { getModelCatalog } from './models.js';
+import { resolveVersion } from './installations/versions.js';
+const ROUTER_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]{0,48}$/i;
+/** Directory this machine writes router YAML files to (user layer). */
+export function routersDir() {
+    return path.join(getUserAgentsDir(), 'routers');
+}
+function routerPath(name) {
+    return path.join(routersDir(), `${name}.yml`);
+}
+/** Validate a router name against the allowed pattern. Throws on invalid input. */
+export function validateRouterName(name) {
+    if (!ROUTER_NAME_PATTERN.test(name)) {
+        throw new Error(`Invalid router name '${name}'. Use letters, digits, dash, underscore (max 48 chars).`);
+    }
+}
+/** Check whether a router resolves, project > user > system (like other resources). */
+export function routerExists(name, cwd) {
+    validateRouterName(name);
+    return resolveResource('routers', name, cwd) !== null;
+}
+/**
+ * The layer a router currently resolves from ('project' | 'user' | 'system' |
+ * an extra-repo alias), or null if it doesn't resolve. `writeRouter` and
+ * `deleteRouter` only ever touch the user layer, so a caller that edits or
+ * removes a router MUST check this first -- editing a router that resolves
+ * from a non-user layer would silently write to a user-layer file that stays
+ * permanently shadowed (the edit "succeeds" but is never read back).
+ */
+export function routerSource(name, cwd) {
+    validateRouterName(name);
+    return resolveResource('routers', name, cwd)?.source ?? null;
+}
+function parseRouterFile(file, name) {
+    const raw = fs.readFileSync(file, 'utf-8');
+    const parsed = yaml.parse(raw);
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error(`Router '${name}' is malformed.`);
+    }
+    if (!parsed.name)
+        parsed.name = name;
+    if (!parsed.harnesses || typeof parsed.harnesses !== 'object')
+        parsed.harnesses = {};
+    return parsed;
+}
+/** Read a router, resolved project > user > system. Throws if not found or malformed. */
+export function readRouter(name, cwd) {
+    validateRouterName(name);
+    const resolved = resolveResource('routers', name, cwd);
+    if (!resolved) {
+        throw new Error(`Router '${name}' not found.`);
+    }
+    return parseRouterFile(resolved.path, name);
+}
+/** Write a router to disk atomically (write-to-tmp then rename). Always writes the user layer. */
+export function writeRouter(router) {
+    validateRouterName(router.name);
+    const dir = routersDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const body = yaml.stringify(router);
+    const file = routerPath(router.name);
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, body, 'utf-8');
+    fs.renameSync(tmp, file);
+}
+/** Delete a router from the user layer. Returns false if it did not exist there. */
+export function deleteRouter(name) {
+    validateRouterName(name);
+    const file = routerPath(name);
+    if (!fs.existsSync(file))
+        return false;
+    fs.unlinkSync(file);
+    return true;
+}
+/**
+ * Fail-loud token validation (E1 of the Agent Router spec): a router MUST NOT
+ * persist a harness id or model/tier token this machine cannot vouch for.
+ * Throws naming the first invalid token found; the caller (route.ts) never
+ * calls {@link writeRouter} when this throws, so an invalid `create`/`allow`
+ * writes nothing.
+ *
+ * A harness id must be a real, registered agent (`AGENTS` in agents.ts) --
+ * checked regardless of whether that harness is installed on this machine,
+ * since a router is fleet-wide config and the harness may only run
+ * elsewhere. A model/tier token is valid when it is one of the four
+ * cross-harness tier tokens (cheap|default|best|ultra, always installable-
+ * agnostic), OR a concrete model id this machine can actually verify: either
+ * one of the harness's resolved tier rungs (`resolveTierMap` -- covers
+ * curated/no-catalog harnesses like Droid with zero install required) or a
+ * member of its extracted catalog (`getModelCatalog`, when a version of that
+ * harness is installed here). A concrete id for a harness with neither --
+ * not installed here, no curated ladder -- cannot be verified and is
+ * rejected rather than accepted unverified.
+ */
+export function validateRouter(router) {
+    for (const [harness, allowlist] of Object.entries(router.harnesses)) {
+        if (!ALL_AGENT_IDS.includes(harness)) {
+            throw new Error(`router '${router.name}': unknown harness '${harness}'. Known harnesses: ${ALL_AGENT_IDS.join(', ')}.`);
+        }
+        const agent = harness;
+        for (const token of allowlist.models) {
+            if (isTierToken(token))
+                continue;
+            const version = resolveVersion(agent) ?? '0.0.0';
+            const tierMap = resolveTierMap(agent, version);
+            const tierRungIds = new Set(MODEL_TIERS.map((t) => tierMap[t].model).filter((m) => m !== null));
+            if (tierRungIds.has(token))
+                continue;
+            const catalog = getModelCatalog(agent, version);
+            const inCatalog = catalog
+                ? catalog.models.some((m) => m.id === token) || Boolean(catalog.aliases[token])
+                : false;
+            if (inCatalog)
+                continue;
+            throw new Error(`router '${router.name}': unknown model '${token}' for harness '${harness}'. ` +
+                `Use a tier token (${MODEL_TIERS.join('|')}) or a model id '${harness}' actually ships.`);
+        }
+    }
+}
+/**
+ * List every router resolved project > user > system (deduplicated union,
+ * project wins on a name collision -- same precedence as {@link resolveResource}).
+ * Malformed files are silently skipped, surfaced via `agents route show <name>`.
+ */
+export function listRouters(cwd) {
+    const routers = [];
+    for (const resolved of listResources('routers', cwd)) {
+        try {
+            routers.push(parseRouterFile(resolved.path, resolved.name));
+        }
+        catch {
+            // Skip malformed router files.
+        }
+    }
+    return routers.sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/lib/routine-context.d.ts

@@ -148,4 +148,5 @@ export interface RoutineReadinessResult {
  */
 export declare function evaluateRoutineReadiness(context: ResolvedExecutionContext, probes?: HarnessReadinessProbes, opts?: {
     agent?: string;
+    version?: string;
 }): RoutineReadinessResult;

package/dist/lib/routine-context.js

@@ -253,10 +253,15 @@ export function evaluateRoutineReadiness(context, probes = {}, opts = {}) {
         });
     }
     if (probes.agentInstalled && !probes.agentInstalled()) {
+        // A pinned version names its exact miss — "no usable version" would send the
+        // operator hunting for a harness that IS installed, just not at the pin.
+        const pinned = opts.version && opts.agent ? `${opts.agent}@${opts.version}` : undefined;
         return withBlocker(context, {
             code: 'agent_unavailable',
-            message: `no usable version of ${opts.agent ?? 'the agent'} is installed on the target`,
-            repair: opts.agent ? `agents add ${opts.agent}@<version>` : undefined,
+            message: pinned
+                ? `pinned ${pinned} is not installed on the target`
+                : `no usable version of ${opts.agent ?? 'the agent'} is installed on the target`,
+            repair: pinned ? `agents add ${pinned}` : (opts.agent ? `agents add ${opts.agent}@<version>` : undefined),
         });
     }
     if (probes.codexTrusted && context.absoluteCwd && !probes.codexTrusted(context.absoluteCwd)) {

package/dist/lib/routine-notify-owner.d.ts

@@ -26,7 +26,7 @@
  * delivers.
  */
 import type { Meta } from './types.js';
-import type { JobConfig, RunMeta } from './routines.js';
+import type { JobConfig, RunMeta } from './scheduling/routines.js';
 /**
  * Owner-phone text for a routine FINISH, or null when the run did NOT fail. Only
  * `failed` and `timeout` are failures worth an owner ping — a `completed` run

package/dist/lib/routine-notify.d.ts

@@ -21,7 +21,7 @@
  * return `null` when the threshold says "don't notify", and are unit-tested; the
  * `notifyRoutine*` wrappers do the filesystem read + dispatch for the daemon.
  */
-import type { JobConfig, RunMeta } from './routines.js';
+import type { JobConfig, RunMeta } from './scheduling/routines.js';
 import { type DesktopNotification } from './menubar/notify-desktop.js';
 type RoutineKind = 'agent' | 'workflow' | 'command';
 /** Which flavor of routine a config/meta describes — drives the notify threshold. */

package/dist/lib/routine-notify.js

@@ -23,7 +23,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { getRunDir } from './routines.js';
+import { getRunDir } from './scheduling/routines.js';
 import { notifyDesktop } from './menubar/notify-desktop.js';
 /** Which flavor of routine a config/meta describes — drives the notify threshold. */
 export function routineKind(r) {

package/dist/lib/routine-process-cleanup.d.ts

@@ -1,4 +1,4 @@
-import type { RunMeta } from './routines.js';
+import type { RunMeta } from './scheduling/routines.js';
 export interface RoutineProcessCleanupOptions {
     runsDir?: string;
     alive?: (pid: number) => boolean;

package/dist/lib/routine-readiness.d.ts

@@ -9,7 +9,7 @@
  * add/edit/doctor/resume additionally call the live variant below, which probes
  * authentication and Codex's native workspace-trust record before activation.
  */
-import type { JobConfig } from './routines.js';
+import type { JobConfig } from './scheduling/routines.js';
 import { type RoutineReadinessResult } from './routine-context.js';
 /**
  * Evaluate whether a routine is ready to activate on this box. `probeAgent`

package/dist/lib/routine-readiness.js

@@ -12,9 +12,9 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as TOML from 'smol-toml';
-import { resolveJobExecutionContext, resolveHostStrategy } from './routines.js';
+import { resolveJobExecutionContext, resolveHostStrategy } from './scheduling/routines.js';
 import { evaluateRoutineReadiness } from './routine-context.js';
-import { getVersionHomePath, resolveVersion } from './versions.js';
+import { getVersionHomePath, isVersionInstalled, resolveVersion } from './installations/versions.js';
 import { probeLocalFleetAuth } from './auth-health.js';
 import { resolveHostRunTarget } from './hosts/run-target.js';
 import { hostIdentityArgs, sshTargetFor } from './hosts/types.js';
@@ -36,14 +36,21 @@ export function evaluateActivationReadiness(config, deps = {}) {
         mode,
         probe: mode === 'local' ? undefined : null,
     });
-    const probeAgent = deps.probeAgent ?? ((agent) => resolveVersion(agent) !== undefined);
+    // A pinned version on LOCAL placement must exist here — accepting a routine
+    // whose exact pin is absent just moves the failure to fire time (RUSH-2719).
+    // Remote host/fleet targets defer the check: their installs are unreachable
+    // from this box until the RUSH-2290 execution-context-on-target resolver.
+    const pinnedLocally = mode === 'local' ? config.version : undefined;
+    const probeAgent = deps.probeAgent ?? ((agent) => pinnedLocally
+        ? isVersionInstalled(agent, pinnedLocally)
+        : resolveVersion(agent) !== undefined);
     return evaluateRoutineReadiness(context, {
         // Command routines have no agent to install; workflow routines dispatch
         // through `agents run` (claude under the hood) and are checked at run time.
         agentInstalled: config.agent && !config.workflow && !config.command
             ? () => probeAgent(config.agent)
             : undefined,
-    }, { agent: config.agent });
+    }, { agent: config.agent, version: pinnedLocally });
 }
 /** One-line human summary of a blocked readiness result, with its repair. */
 export function formatReadinessBlocker(result) {