@phnx-labs/agents-cli 1.22.31 → 1.22.33

package/dist/lib/migrate.js

@@ -13,8 +13,9 @@ import { atomicWriteFileSync } from './fs-atomic.js';
 import { machineId } from './machine-id.js';
 import { AGENTS, agentConfigDirName, findInPath } from './agents.js';
 import { createLink } from './platform/index.js';
-import { migrateLegacyRoutineActivation, setJobEnabled } from './routines.js';
-import { addEnabledRoutinesOnUpgrade } from './routine-activation.js';
+import { migrateLegacyRoutineActivation, setJobEnabled, listJobs, validateJob } from './routines.js';
+import { addEnabledRoutinesOnUpgrade, enabledRoutineNames, replaceEnabledRoutines } from './routine-activation.js';
+import { evaluateActivationReadiness } from './routine-readiness.js';
 import { DAEMON_TICK_ROUTINE_NAMES } from './daemon-ticks.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
@@ -1987,6 +1988,108 @@ export function migrateRoutineDeviceToDevices(routinesDir) {
         console.error(`Migrated ${migrated} routine${migrated === 1 ? '' : 's'}: device → devices`);
     }
 }
+/**
+ * Fold the legacy host-placement `remoteCwd` field into the canonical portable
+ * `cwd` (RUSH-2290). Host dispatch used to read `remoteCwd` while a local run
+ * inferred its cwd from `repo` — two path semantics for one concept. The runner
+ * now resolves every placement from `cwd`, so this idempotently rewrites the
+ * field:
+ *
+ * - `remoteCwd` present, no `cwd`  → rename to `cwd`.
+ * - both present and equal          → drop the duplicate `remoteCwd`.
+ * - both present and DIFFERENT       → conflict: leave BOTH fields untouched so
+ *   the migration never silently chooses one; `validateJob`/`doctor` then flag the
+ *   pair and the routine stays paused rather than running against a guessed path.
+ *
+ * Idempotent: a file with only `cwd` (already migrated) is skipped.
+ */
+export function migrateRoutineRemoteCwdToCwd(routinesDir) {
+    const dir = routinesDir ?? path.join(USER_DIR, 'routines');
+    if (!fs.existsSync(dir))
+        return;
+    const files = fs.readdirSync(dir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+    let migrated = 0;
+    let conflicts = 0;
+    for (const file of files) {
+        const filePath = path.join(dir, file);
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        let doc;
+        try {
+            doc = yaml.parse(raw);
+            if (!doc || typeof doc !== 'object')
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (!('remoteCwd' in doc))
+            continue;
+        const remote = doc.remoteCwd;
+        if (typeof remote !== 'string' || !remote.trim()) {
+            // A malformed legacy value is not something to fold — drop it and move on.
+            delete doc.remoteCwd;
+            atomicWriteFileSync(filePath, yaml.stringify(doc));
+            continue;
+        }
+        if ('cwd' in doc) {
+            if (doc.cwd === remote) {
+                delete doc.remoteCwd; // duplicate — dedupe to the canonical field
+                atomicWriteFileSync(filePath, yaml.stringify(doc));
+                migrated++;
+            }
+            else {
+                conflicts++; // leave both fields; validateJob/doctor pause the conflict
+            }
+            continue;
+        }
+        delete doc.remoteCwd;
+        doc.cwd = remote;
+        atomicWriteFileSync(filePath, yaml.stringify(doc));
+        migrated++;
+    }
+    if (migrated > 0) {
+        console.error(`Migrated ${migrated} routine${migrated === 1 ? '' : 's'}: remoteCwd → cwd`);
+    }
+    if (conflicts > 0) {
+        console.error(`${conflicts} routine${conflicts === 1 ? '' : 's'} have conflicting remoteCwd/cwd — left paused for manual repair (migration_conflict)`);
+    }
+}
+/**
+ * Pause every currently-active routine whose execution context no longer
+ * resolves ready (RUSH-2290). An agent/workflow routine with no project/cwd, a
+ * missing directory, or a non-portable path used to fire and fail every tick —
+ * the mass auth_failed / untrusted-home storm this ticket exists to stop. After
+ * the fold, such a routine is deactivated on THIS device (only), preventing it
+ * from being scheduled until `agents routines doctor --all --fix` (or a repair +
+ * `resume`) makes it ready. Never materializes a device manifest that does not
+ * yet exist, and never touches command routines (they run in the target home).
+ */
+export function pauseUnreadyEnabledRoutines() {
+    const enabled = enabledRoutineNames();
+    if (enabled === null)
+        return; // no manifest yet — nothing activated to pause
+    const enabledSet = new Set(enabled);
+    const paused = [];
+    for (const job of listJobs()) {
+        if (!enabledSet.has(job.name))
+            continue;
+        let ready = true;
+        try {
+            ready = validateJob(job).length === 0 && evaluateActivationReadiness(job).ready;
+        }
+        catch {
+            ready = true; // never pause a routine because readiness itself threw
+        }
+        if (!ready)
+            paused.push(job.name);
+    }
+    if (paused.length === 0)
+        return;
+    const pausedSet = new Set(paused);
+    replaceEnabledRoutines(enabled.filter((name) => !pausedSet.has(name)));
+    console.error(`Paused ${paused.length} routine${paused.length === 1 ? '' : 's'} with an unresolved execution context ` +
+        `(run 'agents routines doctor --all' to see why): ${paused.join(', ')}`);
+}
 /**
  * Fold the legacy watchdog enable sentinel into the watchdog routine.
  *
@@ -2212,6 +2315,8 @@ export async function runMigration() {
     migrateExtrasExtrasToAgentsExtras();
     // Rewrite routine YAML files: singular `device:` -> plural `devices: []`.
     migrateRoutineDeviceToDevices();
+    // Fold legacy host-placement `remoteCwd` into the canonical portable `cwd`.
+    migrateRoutineRemoteCwdToCwd();
     migrateLegacyRoutineActivation();
     // These routines replace daemon timers that were always active. Devices with
     // an existing activation manifest must retain that behavior after upgrade.
@@ -2220,6 +2325,11 @@ export async function runMigration() {
     // who opted in under the old build stays opted in after upgrading. After the
     // routine rewrites above so the routines dir is in its canonical shape.
     migrateWatchdogSentinelToRoutine();
+    // Deactivate any routine whose execution context no longer resolves ready, so
+    // an anchor-less agent/workflow routine cannot keep firing-and-failing after the
+    // fold (RUSH-2290). Runs AFTER the tick/watchdog routines are added so those
+    // (command/home) routines are evaluated in their final shape.
+    pauseUnreadyEnabledRoutines();
     // Symlink repair runs LAST so it can find the post-move version homes.
     repairAgentConfigSymlinks();
     // Repair self-referential node_modules/.bin/<cli> symlinks (the droid

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

@@ -0,0 +1,144 @@
+/**
+ * Routine execution context + readiness resolution.
+ *
+ * A scheduled routine has to run *somewhere*. This module is the single,
+ * target-aware answer to "which directory does this routine's run land in, and
+ * is the chosen harness able to start there?" — computed for the eventual
+ * execution TARGET, never from the daemon process's own cwd.
+ *
+ * Two layers, both pure of global state (every input is injected, so a test
+ * exercises the real code path against real temp directories rather than a mock):
+ *
+ *  - {@link resolveRoutineExecutionContext} — resolve the working directory from
+ *    the routine's singular `project` anchor and/or portable `cwd`, following the
+ *    locked resolution table (see below), and verify the structural + filesystem
+ *    readiness of that directory (existence, portability, writability, cloud
+ *    portability). This layer owns the *context* readiness codes.
+ *  - {@link evaluateRoutineReadiness} — take a resolved context and layer the
+ *    *harness/target* readiness codes (agent installed, Codex workspace trust,
+ *    live auth, target reachability) via injected probes.
+ *
+ * Resolution table (target `$HOME` = the execution device's home):
+ *
+ *  | project | cwd            | resolved dir            | readiness |
+ *  |---------|----------------|-------------------------|-----------|
+ *  | usable  | —              | project base            | continue  |
+ *  | usable  | relative       | base + cwd (inside base)| continue if inside base + exists |
+ *  | rootless| relative       | $HOME + cwd             | continue if exists |
+ *  | —       | relative       | $HOME + cwd             | continue if exists |
+ *  | —       | ~/…            | $HOME-relative          | continue if exists |
+ *  | —       | abs under home | normalized to ~/…       | continue  |
+ *  | —       | abs outside home| local-pinned only      | pause (cwd_not_portable) for host/fleet/cloud |
+ *  | named+unusable | —       | no fallback             | pause (project_path_missing) |
+ *  | —       | — (agent/workflow) | no implicit home     | pause (execution_context_missing) |
+ *  | —       | — (command)    | $HOME                   | continue (housekeeping) |
+ */
+/** Stable, machine-readable readiness codes. A routine is activated only when ready. */
+export type RoutineReadinessCode = 'project_not_found' | 'project_path_missing' | 'cwd_missing' | 'cwd_not_directory' | 'cwd_not_portable' | 'execution_context_missing' | 'cloud_context_unsupported' | 'workspace_not_writable' | 'codex_workspace_untrusted' | 'agent_unavailable' | 'agent_auth_failed' | 'target_unreachable' | 'placement_unsupported' | 'migration_conflict';
+export interface RoutineReadiness {
+    code: RoutineReadinessCode;
+    /** Human-readable one-line explanation of the failing check. */
+    message: string;
+    /** A single safe command that repairs the blocker, when one exists. */
+    repair?: string;
+}
+/** Where the routine body executes — mirrors {@link HostStrategy} placement. */
+export type PlacementMode = 'local' | 'host' | 'fleet' | 'cloud';
+/**
+ * What the caller resolved about the routine's singular `project` anchor.
+ * `undefined` (the field on the input) means the routine names no project.
+ */
+export type ProjectResolution = {
+    defined: false;
+}
+/** Defined project; `base` is its portable base dir (`~/…` or absolute), or
+ *  undefined for a rootless Linear-imported project with no checkout. */
+ | {
+    defined: true;
+    base?: string;
+};
+export type RoutineKind = 'agent' | 'workflow' | 'command';
+/** A filesystem probe against the execution TARGET. */
+export interface ContextFsProbe {
+    exists(absPath: string): boolean;
+    isDirectory(absPath: string): boolean;
+    isWritable(absPath: string): boolean;
+}
+export interface ExecutionContextInput {
+    /** Routine name (for messages only). */
+    name?: string;
+    /** Singular execution anchor (`JobConfig.project`). */
+    project?: string;
+    /** Portable execution directory (`JobConfig.cwd`). */
+    cwd?: string;
+    /** Exactly one of agent/workflow/command determines the fallback rules. */
+    kind: RoutineKind;
+    /** Placement of the run — governs portability enforcement and cloud rules. */
+    mode: PlacementMode;
+    /** Execution target's absolute `$HOME`. Local: `os.homedir()`; remote: the target home. */
+    targetHome: string;
+    /** Resolution of the `project` anchor; omit when the routine names no project. */
+    projectResolution?: ProjectResolution;
+    /**
+     * Filesystem probe for the target, present only when this process can inspect
+     * it (a local run, or add/edit/doctor invoked on the target box). Absent for a
+     * remote/cloud target we cannot reach — then only structural + portability
+     * checks run (existence is deferred, never assumed).
+     */
+    probe?: ContextFsProbe;
+}
+export interface ResolvedExecutionContext {
+    project?: string;
+    /** `config.cwd` echoed for the run record. */
+    requestedCwd?: string;
+    /** Portable resolved cwd for the run record: `~/…` when under target home, else absolute. */
+    resolvedCwd?: string;
+    /** The resolved cwd expanded to an absolute path on the target. Undefined when unresolved. */
+    absoluteCwd?: string;
+    targetHome: string;
+    ready: boolean;
+    /** Present when `ready` is false. */
+    readiness?: RoutineReadiness;
+}
+/** Expand a leading `~`/`$HOME` against the target home; pass other values through. */
+export declare function expandTargetHome(home: string, p: string): string;
+/** Rewrite an absolute path under the target home to its portable `~/…` form; pass others through. */
+export declare function toTargetPortable(home: string, abs: string): string;
+/** True for a bare relative path (not absolute, not home-anchored). */
+export declare function isBareRelative(p: string): boolean;
+/**
+ * Resolve the working directory a routine's run lands in and verify its
+ * structural + filesystem readiness for the given placement. Pure of global
+ * state — every dependency (target home, project resolution, filesystem probe)
+ * is injected.
+ */
+export declare function resolveRoutineExecutionContext(input: ExecutionContextInput): ResolvedExecutionContext;
+/** Injected harness/target probes for {@link evaluateRoutineReadiness}. */
+export interface HarnessReadinessProbes {
+    /** Is the resolved agent+version installed on the target? */
+    agentInstalled?(): boolean;
+    /** Is the absolute execution dir a trusted Codex workspace? (Codex agent only.) */
+    codexTrusted?(absoluteCwd: string): boolean;
+    /** Live auth verdict for the resolved account/version. `ok:false` → agent_auth_failed. */
+    authOk?(): {
+        ok: boolean;
+        reason?: string;
+    };
+    /** Is the execution target reachable? (host/fleet/cloud placement only.) */
+    targetReachable?(): boolean;
+}
+export interface RoutineReadinessResult {
+    context: ResolvedExecutionContext;
+    ready: boolean;
+    readiness?: RoutineReadiness;
+}
+/**
+ * Layer the harness/target readiness codes onto a resolved execution context.
+ * Context blockers short-circuit (no point probing auth for a routine that has
+ * no directory to run in). Every probe is optional and injected; an omitted
+ * probe is treated as "not applicable / passes" so a caller only pays for the
+ * checks it wires up.
+ */
+export declare function evaluateRoutineReadiness(context: ResolvedExecutionContext, probes?: HarnessReadinessProbes, opts?: {
+    agent?: string;
+}): RoutineReadinessResult;

package/dist/lib/routine-context.js

@@ -0,0 +1,268 @@
+/**
+ * Routine execution context + readiness resolution.
+ *
+ * A scheduled routine has to run *somewhere*. This module is the single,
+ * target-aware answer to "which directory does this routine's run land in, and
+ * is the chosen harness able to start there?" — computed for the eventual
+ * execution TARGET, never from the daemon process's own cwd.
+ *
+ * Two layers, both pure of global state (every input is injected, so a test
+ * exercises the real code path against real temp directories rather than a mock):
+ *
+ *  - {@link resolveRoutineExecutionContext} — resolve the working directory from
+ *    the routine's singular `project` anchor and/or portable `cwd`, following the
+ *    locked resolution table (see below), and verify the structural + filesystem
+ *    readiness of that directory (existence, portability, writability, cloud
+ *    portability). This layer owns the *context* readiness codes.
+ *  - {@link evaluateRoutineReadiness} — take a resolved context and layer the
+ *    *harness/target* readiness codes (agent installed, Codex workspace trust,
+ *    live auth, target reachability) via injected probes.
+ *
+ * Resolution table (target `$HOME` = the execution device's home):
+ *
+ *  | project | cwd            | resolved dir            | readiness |
+ *  |---------|----------------|-------------------------|-----------|
+ *  | usable  | —              | project base            | continue  |
+ *  | usable  | relative       | base + cwd (inside base)| continue if inside base + exists |
+ *  | rootless| relative       | $HOME + cwd             | continue if exists |
+ *  | —       | relative       | $HOME + cwd             | continue if exists |
+ *  | —       | ~/…            | $HOME-relative          | continue if exists |
+ *  | —       | abs under home | normalized to ~/…       | continue  |
+ *  | —       | abs outside home| local-pinned only      | pause (cwd_not_portable) for host/fleet/cloud |
+ *  | named+unusable | —       | no fallback             | pause (project_path_missing) |
+ *  | —       | — (agent/workflow) | no implicit home     | pause (execution_context_missing) |
+ *  | —       | — (command)    | $HOME                   | continue (housekeeping) |
+ */
+import * as path from 'path';
+// --- target-aware path helpers (do NOT use project-root.ts's local-HOME-bound
+// forms: resolution must root at the execution target's home, not this box's) ---
+/**
+ * Path flavour of the EXECUTION TARGET, inferred from its own home string.
+ *
+ * The target home belongs to whichever machine will run the routine, which need
+ * not be this one — a Windows box can schedule onto a Linux target. Joining with
+ * the LOCAL separator therefore built `\home\user\svc` for a POSIX target (and
+ * would build `C:/Users/x/svc` the other way), so these helpers key off the home
+ * path's shape instead of `process.platform`. Same-platform behaviour is
+ * unchanged; only the cross-platform case is fixed.
+ */
+function targetPath(home) {
+    return /^[A-Za-z]:[\\/]/.test(home) || home.includes('\\') ? path.win32 : path.posix;
+}
+/** Expand a leading `~`/`$HOME` against the target home; pass other values through. */
+export function expandTargetHome(home, p) {
+    if (p === '~' || p === '$HOME')
+        return home;
+    const tp = targetPath(home);
+    if (p.startsWith('~/'))
+        return tp.join(home, p.slice(2));
+    if (p.startsWith('$HOME/'))
+        return tp.join(home, p.slice('$HOME/'.length));
+    return p;
+}
+/** Rewrite an absolute path under the target home to its portable `~/…` form; pass others through. */
+export function toTargetPortable(home, abs) {
+    const tp = targetPath(home);
+    const rel = tp.relative(home, abs);
+    if (rel === '')
+        return '~';
+    if (!rel.startsWith('..') && !tp.isAbsolute(rel))
+        return '~/' + rel.split(tp.sep).join('/');
+    return abs;
+}
+/** True for a bare relative path (not absolute, not home-anchored). */
+export function isBareRelative(p) {
+    return !path.isAbsolute(p) && !p.startsWith('~') && !p.startsWith('$HOME');
+}
+/**
+ * True when `child` is `base` or strictly beneath it (no `..` escape).
+ *
+ * Compares in the BASE's own path flavour (see {@link targetPath}) — both
+ * arguments are target-side paths, and comparing a POSIX pair with Windows
+ * semantics (or the reverse) answers about the wrong filesystem.
+ */
+function isInside(baseAbs, childAbs) {
+    const tp = targetPath(baseAbs);
+    const rel = tp.relative(baseAbs, childAbs);
+    return rel === '' || (!rel.startsWith('..') && !tp.isAbsolute(rel));
+}
+function pause(ctx, readiness) {
+    return { ...ctx, ready: false, readiness };
+}
+/**
+ * Resolve the working directory a routine's run lands in and verify its
+ * structural + filesystem readiness for the given placement. Pure of global
+ * state — every dependency (target home, project resolution, filesystem probe)
+ * is injected.
+ */
+export function resolveRoutineExecutionContext(input) {
+    const { project, cwd, kind, mode, targetHome, projectResolution, probe } = input;
+    const requestedCwd = cwd;
+    const base = { project, requestedCwd, targetHome };
+    const hasProjectBinding = projectResolution?.defined === true;
+    // Finalize a resolved portable dir: run the cloud/portability/filesystem gates
+    // and return either a ready context or a paused one.
+    const finalize = (portable, missingCode) => {
+        const absoluteCwd = expandTargetHome(targetHome, portable);
+        const ctx = { ...base, resolvedCwd: portable, absoluteCwd };
+        // Cloud: a filesystem-only cwd (no project/repo binding) has no provider
+        // repository to map onto. A project binding selects the provider repo.
+        if (mode === 'cloud' && !hasProjectBinding) {
+            return pause(ctx, {
+                code: 'cloud_context_unsupported',
+                message: `a bare cwd has no cloud repository to run in — bind a project/repo or run '${input.name ?? 'this routine'}' locally`,
+                repair: `agents routines edit ${input.name ?? '<name>'} --project-anchor <name>`,
+            });
+        }
+        if (probe) {
+            if (!probe.exists(absoluteCwd)) {
+                return pause(ctx, {
+                    code: missingCode,
+                    message: missingCode === 'project_path_missing'
+                        ? `project base directory does not exist on the target: ${portable}`
+                        : `execution directory does not exist on the target: ${portable}`,
+                    repair: `mkdir -p ${portable}`,
+                });
+            }
+            if (!probe.isDirectory(absoluteCwd)) {
+                return pause(ctx, {
+                    code: 'cwd_not_directory',
+                    message: `execution path is not a directory: ${portable}`,
+                });
+            }
+            if (!probe.isWritable(absoluteCwd)) {
+                return pause(ctx, {
+                    code: 'workspace_not_writable',
+                    message: `execution directory is not writable: ${portable}`,
+                });
+            }
+        }
+        return { ...ctx, ready: true };
+    };
+    // 1. Explicit project anchor.
+    if (project !== undefined) {
+        if (!projectResolution || projectResolution.defined === false) {
+            return pause(base, {
+                code: 'project_not_found',
+                message: `project '${project}' is not defined`,
+                repair: `agents projects add ${project} --root <path>`,
+            });
+        }
+        const projBase = projectResolution.base;
+        if (projBase) {
+            // Usable base path.
+            if (cwd === undefined) {
+                return finalize(projBase, 'project_path_missing');
+            }
+            if (isBareRelative(cwd)) {
+                const baseAbs = expandTargetHome(targetHome, projBase);
+                // Target-side join: `path.resolve` would use this host's separator and,
+                // for a target home this host does not consider absolute, prepend the
+                // local process cwd.
+                const joinedAbs = targetPath(targetHome).resolve(baseAbs, cwd);
+                if (!isInside(baseAbs, joinedAbs)) {
+                    return pause(base, {
+                        code: 'cwd_not_portable',
+                        message: `cwd '${cwd}' escapes the project base '${projBase}' — a project-relative cwd must stay inside it`,
+                    });
+                }
+                return finalize(toTargetPortable(targetHome, joinedAbs), 'cwd_missing');
+            }
+            // Absolute or home-anchored cwd alongside a project: fall through to the
+            // cwd-first handling below (the project base is not the anchor then).
+        }
+        else if (cwd === undefined) {
+            // Rootless project (Linear import), no cwd: there is nothing to run in.
+            return pause(base, {
+                code: 'project_path_missing',
+                message: `project '${project}' has no checkout path — give it a cwd (anchored at the target home) or set the project's root`,
+                repair: `agents routines edit ${input.name ?? '<name>'} --cwd <path>`,
+            });
+        }
+        // Rootless project + a cwd, or usable project + a non-relative cwd: the cwd
+        // itself is the anchor. A bare relative cwd anchors at the target home.
+    }
+    // 2. cwd without a (usable relative-anchoring) project.
+    if (cwd !== undefined) {
+        if (cwd.startsWith('~') || cwd.startsWith('$HOME')) {
+            const abs = expandTargetHome(targetHome, cwd);
+            return finalize(toTargetPortable(targetHome, abs), 'cwd_missing');
+        }
+        if (path.isAbsolute(cwd)) {
+            const resolved = path.resolve(cwd);
+            if (isInside(targetHome, resolved)) {
+                // Normalize an absolute-under-home path to its portable form on save.
+                return finalize(toTargetPortable(targetHome, resolved), 'cwd_missing');
+            }
+            // Absolute path outside the target home: only a local-pinned routine can
+            // use it; host/fleet/cloud placement cannot carry a non-portable path.
+            if (mode === 'local') {
+                return finalize(resolved, 'cwd_missing');
+            }
+            return pause(base, {
+                code: 'cwd_not_portable',
+                message: `absolute cwd '${cwd}' is outside the target home and cannot travel to ${mode} placement — use a home-relative path`,
+            });
+        }
+        // Bare relative cwd (no usable project base): anchor at the target home,
+        // in the target's own path flavour (see the joinedAbs note above).
+        return finalize(toTargetPortable(targetHome, targetPath(targetHome).resolve(targetHome, cwd)), 'cwd_missing');
+    }
+    // 3. Neither field.
+    if (kind === 'command') {
+        // Command routines are deterministic housekeeping — the target home is a
+        // safe implicit cwd, so a version-check / notify routine keeps working.
+        return finalize(toTargetPortable(targetHome, targetHome), 'cwd_missing');
+    }
+    return pause(base, {
+        code: 'execution_context_missing',
+        message: `routine '${input.name ?? ''}' has no project or cwd — an agent/workflow routine needs an explicit execution directory`,
+        repair: `agents routines edit ${input.name ?? '<name>'} --project-anchor <name>  # or --cwd <path>`,
+    });
+}
+/**
+ * Layer the harness/target readiness codes onto a resolved execution context.
+ * Context blockers short-circuit (no point probing auth for a routine that has
+ * no directory to run in). Every probe is optional and injected; an omitted
+ * probe is treated as "not applicable / passes" so a caller only pays for the
+ * checks it wires up.
+ */
+export function evaluateRoutineReadiness(context, probes = {}, opts = {}) {
+    if (!context.ready) {
+        return { context, ready: false, readiness: context.readiness };
+    }
+    if (probes.targetReachable && !probes.targetReachable()) {
+        return withBlocker(context, {
+            code: 'target_unreachable',
+            message: 'the execution target is not reachable',
+        });
+    }
+    if (probes.agentInstalled && !probes.agentInstalled()) {
+        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,
+        });
+    }
+    if (probes.codexTrusted && context.absoluteCwd && !probes.codexTrusted(context.absoluteCwd)) {
+        return withBlocker(context, {
+            code: 'codex_workspace_untrusted',
+            message: `Codex will not start in an untrusted workspace: ${context.resolvedCwd}`,
+            repair: `trust the workspace (add it to Codex's trusted projects) — the routine never uses --skip-git-repo-check`,
+        });
+    }
+    if (probes.authOk) {
+        const verdict = probes.authOk();
+        if (!verdict.ok) {
+            return withBlocker(context, {
+                code: 'agent_auth_failed',
+                message: `the selected account failed a live auth check${verdict.reason ? `: ${verdict.reason}` : ''}`,
+                repair: opts.agent ? `agents run ${opts.agent} -- login` : 'log the account back in',
+            });
+        }
+    }
+    return { context, ready: true };
+}
+function withBlocker(context, readiness) {
+    return { context: { ...context, ready: false, readiness }, ready: false, readiness };
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Activation readiness for a routine, composed from the target-aware execution
+ * context ({@link resolveJobExecutionContext}) plus the harness/target checks a
+ * caller can perform on this box (agent installed). This is the gate `add`,
+ * `edit`, `doctor`, and `resume` all run before activating a routine: ready →
+ * active, any proven blocker → saved paused with a stable code + repair command.
+ *
+ * Structural context readiness is synchronous for the scheduler. Interactive
+ * 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 RoutineReadinessResult } from './routine-context.js';
+/**
+ * Evaluate whether a routine is ready to activate on this box. `probeAgent`
+ * defaults to "is a version of the routine's agent resolvable" via
+ * {@link resolveVersion}; pass a stub in tests to exercise the availability path
+ * without an installed harness.
+ */
+export declare function evaluateActivationReadiness(config: JobConfig, deps?: {
+    probeAgent?: (agent: string) => boolean;
+}): RoutineReadinessResult;
+/** One-line human summary of a blocked readiness result, with its repair. */
+export declare function formatReadinessBlocker(result: RoutineReadinessResult): string;
+interface RemoteProjectDefinition {
+    name: string;
+    root?: string;
+    defaultPath?: string;
+}
+/** Parse the target HOME sentinel and the project catalog returned by one SSH call. */
+export declare function parseRemoteProjectSnapshot(stdout: string): {
+    home: string;
+    projects: RemoteProjectDefinition[];
+} | undefined;
+/** Build a target-native probe that creates and removes a file in the workspace. */
+export declare function buildRemoteWorkspaceProbe(cwd: string, windows: boolean): string;
+/** A successful probe must contain the exact requested postcondition, not merely exit zero. */
+export declare function probeOutputHasSentinel(stdout: string, sentinel: string): boolean;
+/**
+ * Interactive setup/repair readiness. Unlike the scheduler's deterministic
+ * structural gate, this completes a real local auth request and reads Codex's
+ * native trust record before add/edit/resume can activate the definition.
+ */
+export declare function evaluateActivationReadinessLive(config: JobConfig): Promise<RoutineReadinessResult>;
+/** Resolve and probe the actual SSH target used by a host-placed routine. */
+export declare function evaluateHostActivationReadiness(config: JobConfig): Promise<RoutineReadinessResult>;
+export {};