@phnx-labs/agents-cli 1.22.31 → 1.22.32

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 {};

package/dist/lib/routine-readiness.js

@@ -0,0 +1,239 @@
+/**
+ * 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 * as fs from 'fs';
+import * as path from 'path';
+import * as TOML from 'smol-toml';
+import { resolveJobExecutionContext, resolveHostStrategy } from './routines.js';
+import { evaluateRoutineReadiness } from './routine-context.js';
+import { getVersionHomePath, resolveVersion } from './versions.js';
+import { probeLocalFleetAuth } from './auth-health.js';
+import { resolveHostRunTarget } from './hosts/run-target.js';
+import { hostIdentityArgs, sshTargetFor } from './hosts/types.js';
+import { probeHost } from './hosts/ready.js';
+import { sshExec, shellQuote } from './ssh-exec.js';
+import { encodePowershell, powershellQuote, POWERSHELL_PROGRESS_SILENCE } from './hosts/remote-cmd.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 function evaluateActivationReadiness(config, deps = {}) {
+    const strategy = resolveHostStrategy(config);
+    const mode = strategy;
+    // Local placement inspects this box's filesystem; a remote/cloud target defers
+    // existence (its filesystem is unreachable here) and checks portability only.
+    const context = resolveJobExecutionContext(config, {
+        mode,
+        probe: mode === 'local' ? undefined : null,
+    });
+    const probeAgent = deps.probeAgent ?? ((agent) => 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 });
+}
+/** One-line human summary of a blocked readiness result, with its repair. */
+export function formatReadinessBlocker(result) {
+    if (result.ready || !result.readiness)
+        return 'ready';
+    const { code, message, repair } = result.readiness;
+    return `${code}: ${message}${repair ? `\n  repair: ${repair}` : ''}`;
+}
+/** Parse the target HOME sentinel and the project catalog returned by one SSH call. */
+export function parseRemoteProjectSnapshot(stdout) {
+    const lines = stdout.split(/\r?\n/);
+    const homeLine = lines.shift();
+    if (!homeLine?.startsWith('__HOME__'))
+        return undefined;
+    const home = homeLine.slice('__HOME__'.length);
+    if (!home)
+        return undefined;
+    try {
+        const projects = JSON.parse(lines.join('\n'));
+        if (!Array.isArray(projects))
+            return undefined;
+        if (!projects.every((entry) => entry && typeof entry === 'object' && typeof entry.name === 'string')) {
+            return undefined;
+        }
+        return { home, projects: projects };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Build a target-native probe that creates and removes a file in the workspace. */
+export function buildRemoteWorkspaceProbe(cwd, windows) {
+    if (windows) {
+        return `powershell -NoProfile -EncodedCommand ${encodePowershell(`$d=${powershellQuote(cwd)}; if (-not (Test-Path -LiteralPath $d -PathType Container)) { exit 1 }; $p=Join-Path $d ([IO.Path]::GetRandomFileName()); try { New-Item -ItemType File -Path $p -ErrorAction Stop | Out-Null; Remove-Item -LiteralPath $p -Force -ErrorAction Stop; exit 0 } catch { exit 1 }`)}`;
+    }
+    const pattern = path.posix.join(cwd, '.agents-routine-readiness.XXXXXX');
+    return `probe_path=$(mktemp ${shellQuote(pattern)}) && rm -f "$probe_path"`;
+}
+/** A successful probe must contain the exact requested postcondition, not merely exit zero. */
+export function probeOutputHasSentinel(stdout, sentinel) {
+    const containsExact = (value) => {
+        if (value === sentinel)
+            return true;
+        if (Array.isArray(value))
+            return value.some(containsExact);
+        if (value && typeof value === 'object')
+            return Object.values(value).some(containsExact);
+        return false;
+    };
+    return stdout.split(/\r?\n/).some((line) => {
+        const trimmed = line.trim();
+        if (trimmed === sentinel)
+            return true;
+        try {
+            return containsExact(JSON.parse(trimmed));
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function codexWorkspaceTrusted(version, cwd) {
+    try {
+        const configPath = path.join(getVersionHomePath('codex', version), '.codex', 'config.toml');
+        const parsed = TOML.parse(fs.readFileSync(configPath, 'utf-8'));
+        const projects = parsed.projects;
+        return Object.entries(projects ?? {}).some(([root, project]) => {
+            if (project.trust_level !== 'trusted')
+                return false;
+            const relative = path.relative(root, cwd);
+            return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 async function evaluateActivationReadinessLive(config) {
+    const structural = evaluateActivationReadiness(config);
+    if (!structural.ready)
+        return structural;
+    const mode = resolveHostStrategy(config);
+    if (mode === 'host' && config.host)
+        return evaluateHostActivationReadiness(config);
+    if (mode !== 'local' || !config.agent || config.workflow || config.command)
+        return structural;
+    const version = resolveVersion(config.agent);
+    if (!version)
+        return structural;
+    const context = resolveJobExecutionContext(config, { mode: 'local' });
+    let authVerdict;
+    const rows = await probeLocalFleetAuth({ agents: [config.agent] });
+    const row = rows.find((candidate) => candidate.version === version);
+    const accepted = new Set(['live', 'rate_limited', 'unverified']);
+    authVerdict = row && accepted.has(row.health.verdict)
+        ? { ok: true }
+        : { ok: false, reason: row?.health.verdict ?? 'unconfigured' };
+    return evaluateRoutineReadiness(context, {
+        agentInstalled: () => true,
+        ...(config.agent === 'codex' && context.absoluteCwd
+            ? { codexTrusted: () => codexWorkspaceTrusted(version, context.absoluteCwd) }
+            : {}),
+        authOk: () => authVerdict,
+    }, { agent: config.agent });
+}
+/** Resolve and probe the actual SSH target used by a host-placed routine. */
+export async function evaluateHostActivationReadiness(config) {
+    const host = await resolveHostRunTarget(config.host);
+    const target = sshTargetFor(host);
+    const identity = hostIdentityArgs(host);
+    if (!probeHost(target, host.os, identity).reachable) {
+        return evaluateRoutineReadiness(resolveJobExecutionContext(config, { mode: 'host', probe: null }), {
+            targetReachable: () => false,
+        }, { agent: config.agent });
+    }
+    const windows = host.os?.toLowerCase().includes('win') ?? false;
+    const homeCommand = windows
+        ? `powershell -NoProfile -EncodedCommand ${encodePowershell(`${POWERSHELL_PROGRESS_SILENCE}; Write-Output ("__HOME__" + $HOME); & agents projects list --json`)}`
+        : `bash -lc ${shellQuote('printf "__HOME__%s\\n" "$HOME"; agents projects list --json')}`;
+    const projectResult = sshExec(target, homeCommand, { timeoutMs: 20_000, extraSshArgs: identity });
+    if (projectResult.code !== 0) {
+        return evaluateRoutineReadiness(resolveJobExecutionContext(config, { mode: 'host', probe: null }), {
+            targetReachable: () => false,
+        }, { agent: config.agent });
+    }
+    const snapshot = parseRemoteProjectSnapshot(projectResult.stdout);
+    if (!snapshot) {
+        return evaluateRoutineReadiness(resolveJobExecutionContext(config, { mode: 'host', probe: null }), {
+            targetReachable: () => false,
+        }, { agent: config.agent });
+    }
+    const targetHome = snapshot.home;
+    const defs = snapshot.projects;
+    const def = config.project ? defs.find((candidate) => candidate.name === config.project) : undefined;
+    const projectResolution = config.project
+        ? (def ? { defined: true, base: def.defaultPath ?? def.root } : { defined: false })
+        : undefined;
+    const unprobed = resolveJobExecutionContext(config, { mode: 'host', targetHome, probe: null, projectResolution });
+    if (!unprobed.ready || !unprobed.absoluteCwd)
+        return { context: unprobed, ready: false, readiness: unprobed.readiness };
+    const check = buildRemoteWorkspaceProbe(unprobed.absoluteCwd, windows);
+    const fsResult = sshExec(target, check, { timeoutMs: 12_000, extraSshArgs: identity });
+    if (fsResult.code !== 0) {
+        return evaluateRoutineReadiness({ ...unprobed, ready: false, readiness: {
+                code: 'workspace_not_writable',
+                message: `the execution directory is missing or not writable on ${host.name}: ${unprobed.resolvedCwd}`,
+            } });
+    }
+    if (config.agent && !config.workflow && !config.command) {
+        if (config.agent === 'codex') {
+            const args = ['run', 'codex', 'Reply with exactly ROUTINE_READY', '--mode', 'plan', '--timeout', '45s', '--json'];
+            const command = windows
+                ? `powershell -NoProfile -EncodedCommand ${encodePowershell(`${POWERSHELL_PROGRESS_SILENCE}; Set-Location -LiteralPath ${powershellQuote(unprobed.absoluteCwd)}; & agents ${args.map(powershellQuote).join(' ')}`)}`
+                : `cd ${shellQuote(unprobed.absoluteCwd)} && agents ${args.map(shellQuote).join(' ')}`;
+            const probe = sshExec(target, command, { timeoutMs: 60_000, extraSshArgs: identity });
+            if (probe.code !== 0 || !probeOutputHasSentinel(probe.stdout, 'ROUTINE_READY')) {
+                const detail = `${probe.stderr}\n${probe.stdout}`.trim();
+                const untrusted = detail.includes('trusted directory') || detail.includes('trusted workspace');
+                return evaluateRoutineReadiness(unprobed, {
+                    ...(untrusted ? { codexTrusted: () => false } : { authOk: () => ({ ok: false, reason: detail || 'probe failed' }) }),
+                }, { agent: config.agent });
+            }
+        }
+        else {
+            const pingArgs = ['devices', 'ping', '--local', '--json'];
+            const command = windows
+                ? `powershell -NoProfile -EncodedCommand ${encodePowershell(`${POWERSHELL_PROGRESS_SILENCE}; & agents ${pingArgs.map(powershellQuote).join(' ')}`)}`
+                : `agents ${pingArgs.map(shellQuote).join(' ')}`;
+            const probe = sshExec(target, command, { timeoutMs: 30_000, extraSshArgs: identity });
+            let verdict = 'error';
+            if (probe.code === 0) {
+                try {
+                    const payload = JSON.parse(probe.stdout);
+                    verdict = payload.rows?.find((row) => row.agent === config.agent)?.health.verdict ?? 'unconfigured';
+                }
+                catch {
+                    verdict = 'error';
+                }
+            }
+            if (!new Set(['live', 'rate_limited', 'unverified']).has(verdict)) {
+                return evaluateRoutineReadiness(unprobed, {
+                    authOk: () => ({ ok: false, reason: verdict }),
+                }, { agent: config.agent });
+            }
+        }
+    }
+    return { context: unprobed, ready: true };
+}