@phnx-labs/agents-cli 1.22.31 → 1.22.32

package/dist/lib/installations/update.d.ts

@@ -0,0 +1,40 @@
+import { type UpdateStrategy } from './strategies.js';
+import type { Installation, UpdateOutcome } from './types.js';
+export interface UpdateInstallationOptions {
+    /** `latest` (default), `oldest`, or a concrete release. */
+    to?: string;
+    onProgress?: (message: string) => void;
+    /**
+     * Replace the registry-selected strategy. The seam exists so the transaction
+     * below can be exercised against a real filesystem without a vendor fetch, and
+     * so a track that installs a harness differently (per-installation Cursor
+     * isolation) can reuse this orchestration instead of re-implementing it.
+     * Omitted in every normal call — `selectUpdateStrategy` is the default.
+     */
+    strategy?: UpdateStrategy;
+}
+/**
+ * Move one frozen installation to a new vendor release, preserving its identity.
+ *
+ * The transaction is stage → verify → commit → record, with rollback on any
+ * failure after the swap:
+ *
+ *   1. **stage**   — fetch the target release somewhere that is not yet live.
+ *   2. **verify**  — launch the STAGED binary. This is the gate that makes the
+ *                    update safe: a release that cannot start is discarded while
+ *                    the working one is still in place, so the failure mode is
+ *                    "nothing changed", not "the agent no longer runs".
+ *   3. **commit**  — swap it in, keeping the displaced release until step 4.
+ *   4. **record**  — re-verify in place, then write the new release into the
+ *                    installation record and drop the rollback material.
+ *
+ * The installation's `id` and `label` are never touched, so the global default,
+ * an isolated default, a project pin, a routine's `version:`, and a profile's
+ * `host.version` all keep resolving to this installation across the update —
+ * that reference preservation is the whole point of freezing the label.
+ *
+ * Strategies whose vendor artifact is global (a self-updating binary) report
+ * `transactional: false`; for those, step 3 is a no-op and a failed verify is
+ * surfaced as a failed update rather than pretended to be reversible.
+ */
+export declare function updateInstallation(installation: Installation, options?: UpdateInstallationOptions): Promise<UpdateOutcome>;

package/dist/lib/installations/update.js

@@ -0,0 +1,131 @@
+import * as fs from 'fs';
+import { AGENTS, isAgentHardDeprecated, hardDeprecationError } from '../agents.js';
+import { emit } from '../events.js';
+import { getBinaryPath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, verifyBinaryLaunches, } from '../versions.js';
+import { assertValidRelease, selectUpdateStrategy, } from './strategies.js';
+import { listInstallations, recordRelease } from './store.js';
+/**
+ * Move one frozen installation to a new vendor release, preserving its identity.
+ *
+ * The transaction is stage → verify → commit → record, with rollback on any
+ * failure after the swap:
+ *
+ *   1. **stage**   — fetch the target release somewhere that is not yet live.
+ *   2. **verify**  — launch the STAGED binary. This is the gate that makes the
+ *                    update safe: a release that cannot start is discarded while
+ *                    the working one is still in place, so the failure mode is
+ *                    "nothing changed", not "the agent no longer runs".
+ *   3. **commit**  — swap it in, keeping the displaced release until step 4.
+ *   4. **record**  — re-verify in place, then write the new release into the
+ *                    installation record and drop the rollback material.
+ *
+ * The installation's `id` and `label` are never touched, so the global default,
+ * an isolated default, a project pin, a routine's `version:`, and a profile's
+ * `host.version` all keep resolving to this installation across the update —
+ * that reference preservation is the whole point of freezing the label.
+ *
+ * Strategies whose vendor artifact is global (a self-updating binary) report
+ * `transactional: false`; for those, step 3 is a no-op and a failed verify is
+ * surfaced as a failed update rather than pretended to be reversible.
+ */
+export async function updateInstallation(installation, options = {}) {
+    const agent = installation.agent;
+    if (isAgentHardDeprecated(agent))
+        throw new Error(hardDeprecationError(agent));
+    const requested = options.to ?? 'latest';
+    assertValidRelease(requested);
+    const strategy = options.strategy ?? selectUpdateStrategy(agent);
+    const ctx = { agent, installation, requested, onProgress: options.onProgress };
+    const target = await strategy.resolveTarget(ctx);
+    if (target === installation.releaseVersion) {
+        options.onProgress?.(`${AGENTS[agent].name}@${installation.label} is already on release ${target}; nothing to update.`);
+        return {
+            installation,
+            strategy: strategy.id,
+            fromRelease: installation.releaseVersion,
+            toRelease: target,
+            unchanged: true,
+            alsoUpdated: [],
+        };
+    }
+    let staged = null;
+    try {
+        staged = await strategy.stage(ctx, target);
+        const stagedHealth = await verifyBinaryLaunches(staged.binary, staged.home);
+        if (!stagedHealth.ok) {
+            throw new Error(`${AGENTS[agent].name} release ${staged.release} was fetched but its binary failed to launch`
+                + `${stagedHealth.detail ? ` (${stagedHealth.detail})` : ''}. `
+                + `${installation.label} is unchanged and still on ${installation.releaseVersion}.`);
+        }
+        // The installer may have reported a release the installation already has
+        // (a self-updating binary that was already current). Recording it would
+        // claim a change that did not happen and append a bogus history entry.
+        if (staged.release === installation.releaseVersion) {
+            options.onProgress?.(`${AGENTS[agent].name}@${installation.label} is already on release ${staged.release}; nothing to update.`);
+            // Deliberately NOT committed: there is no new release to make live, and
+            // for a strategy that swaps the version dir a commit here would displace
+            // a working tree, discard its rollback material, and skip the live probe —
+            // all while reporting that nothing changed. The `finally` clears staging.
+            return {
+                installation,
+                strategy: strategy.id,
+                fromRelease: installation.releaseVersion,
+                toRelease: staged.release,
+                unchanged: true,
+                alsoUpdated: [],
+            };
+        }
+        const handles = await strategy.commit(ctx, staged);
+        try {
+            // Probe what will actually execute — `getBinaryPath` is the same resolver
+            // the shims and `agents run` use — not the staging copy probed above.
+            const liveBinary = getBinaryPath(agent, installation.label);
+            const liveHealth = await verifyBinaryLaunches(liveBinary, staged.home);
+            if (!liveHealth.ok) {
+                throw new Error(`${AGENTS[agent].name} release ${staged.release} failed to launch after being installed`
+                    + `${liveHealth.detail ? ` (${liveHealth.detail})` : ''}.`);
+            }
+        }
+        catch (err) {
+            // Undo unconditionally. `transactional` describes whether the VENDOR
+            // artifact can be put back, not whether this directory can — gating the
+            // undo on it left an installer-driven harness with the broken tree live
+            // AND the previous one orphaned in rollback material nothing deletes.
+            // A strategy with nothing to restore returns a no-op undo.
+            handles.undo();
+            throw new Error(strategy.transactional
+                ? `${err.message} Rolled back to ${installation.releaseVersion}.`
+                : `${err.message} The version directory was restored, but ${AGENTS[agent].name}'s installer `
+                    + `had already replaced the binary it manages globally — repair it with: agents add ${agent}@latest`);
+        }
+        handles.finalize();
+        const updated = recordRelease(installation, staged.release);
+        // Several installations of a global-binary harness point at the same file,
+        // so the one we just replaced is live for all of them. Recording the release
+        // only on the target would leave the others claiming a release that is no
+        // longer on disk.
+        const alsoUpdated = strategy.sharedBinary
+            ? listInstallations(agent)
+                .filter((other) => other.label !== installation.label && other.releaseVersion !== staged.release)
+                .map((other) => recordRelease(other, staged.release))
+            : [];
+        invalidateInstalledVersionsCache(agent);
+        invalidateLiveVersionCache(agent);
+        // A release really was installed, so this is the right event; `installation`
+        // says WHICH frozen install received it, since the label no longer equals
+        // the release.
+        emit('version.install', { agent, version: staged.release, installation: installation.label });
+        return {
+            installation: updated,
+            strategy: strategy.id,
+            fromRelease: installation.releaseVersion,
+            toRelease: staged.release,
+            unchanged: false,
+            alsoUpdated,
+        };
+    }
+    finally {
+        if (staged?.stagingDir)
+            fs.rmSync(staged.stagingDir, { recursive: true, force: true });
+    }
+}

package/dist/lib/migrate.d.ts

@@ -117,6 +117,33 @@ export declare function migrateExtrasExtrasToAgentsExtras(historyDir?: string):
  * Params default to the real routines dir; injectable for tests.
  */
 export declare function migrateRoutineDeviceToDevices(routinesDir?: string): void;
+/**
+ * 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 declare function migrateRoutineRemoteCwdToCwd(routinesDir?: string): void;
+/**
+ * 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 declare function pauseUnreadyEnabledRoutines(): void;
 /**
  * Fold the legacy watchdog enable sentinel into the watchdog routine.
  *

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;