@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/lib/routines-placement.js

@@ -0,0 +1,79 @@
+/**
+ * Runtime placement resolution for routines: local / host / fleet / cloud.
+ *
+ * The scheduler only decides *whether* this machine may fire the job
+ * (`devices` + `jobRunsOnThisDevice`). This module decides *where the job
+ * body runs* once it has been fired, using `hostStrategy`.
+ *
+ * Fleet semantics (RUSH-2035 / RUSH-1980): pick exactly one online device per
+ * fire. Cross-device double-fire is prevented by requiring a `devices` firing
+ * pin for fleet/host/cloud strategies (applied at add/sync time).
+ */
+import { resolveHostStrategy } from './routines.js';
+import { machineId, normalizeHost } from './machine-id.js';
+import { loadDevicesSync } from './devices/registry.js';
+import { planFleetTargets } from './devices/fleet.js';
+/**
+ * Pick one online fleet device for `hostStrategy: fleet`.
+ *
+ * Preference order:
+ * 1. This machine, if online and eligible (avoids needless SSH)
+ * 2. First eligible online device by name (stable / deterministic)
+ *
+ * `config.devices` is the *firing* allowlist only (which daemon may fire the
+ * job). It is intentionally NOT used as an execution pool filter — otherwise
+ * the double-fire pin (`devices: [self]`) would collapse fleet placement to
+ * always-local. Control / offline / no-address devices are never chosen.
+ */
+export function pickFleetDevice(_config) {
+    let reg;
+    try {
+        reg = loadDevicesSync();
+    }
+    catch {
+        return null;
+    }
+    const planned = planFleetTargets(reg);
+    const candidates = planned.filter((t) => !t.skip).map((t) => t.device.name);
+    if (candidates.length === 0) {
+        // No registry / nothing online: fall back to self so a single-box fleet
+        // without a registry entry still runs locally.
+        return machineId();
+    }
+    const self = machineId();
+    const selfMatch = candidates.find((n) => normalizeHost(n) === self);
+    if (selfMatch)
+        return selfMatch;
+    return [...candidates].sort((a, b) => a.localeCompare(b))[0] ?? null;
+}
+/**
+ * Resolve where a fired job's body should execute.
+ * Throws a human-readable Error when placement cannot be satisfied.
+ */
+export function resolvePlacementTarget(config) {
+    const strategy = resolveHostStrategy(config);
+    switch (strategy) {
+        case 'local':
+            return { mode: 'local' };
+        case 'host': {
+            if (!config.host || config.host.trim() === '') {
+                throw new Error(`Routine '${config.name}' has hostStrategy: host but no host: — set host: or --run-on`);
+            }
+            // host: pointing at this machine is local execution (no SSH loop).
+            if (normalizeHost(config.host) === machineId())
+                return { mode: 'local' };
+            return { mode: 'host', host: config.host };
+        }
+        case 'fleet': {
+            const picked = pickFleetDevice(config);
+            if (!picked) {
+                throw new Error(`Routine '${config.name}' hostStrategy: fleet — no eligible online device to place the run`);
+            }
+            if (normalizeHost(picked) === machineId())
+                return { mode: 'local' };
+            return { mode: 'host', host: picked };
+        }
+        case 'cloud':
+            return { mode: 'cloud' };
+    }
+}

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

@@ -0,0 +1,97 @@
+/**
+ * Project-level routine opt-in, source tracking, and user-layer sync.
+ *
+ * Project YAML under `<project>/.agents/routines/*.yml` is inspection-only by
+ * default (a cloned public repo must never auto-fire agent prompts). After an
+ * explicit opt-in, routines are materialised into `~/.agents/routines/` with
+ * `source:` provenance so the daemon — which only loads user + system layers —
+ * can fire them. `syncProjectRoutines` refreshes the user-layer copies when
+ * project YAML changes (also invoked on daemon SIGHUP).
+ */
+import { type JobSource } from './routines.js';
+/** Expand `~/…` and resolve to an absolute path. */
+export declare function expandProjectPath(p: string): string;
+/** Store paths home-relative when under $HOME so they travel across machines. */
+export declare function displayProjectPath(abs: string): string;
+/** Project roots currently opted into daemon firing (absolute paths). */
+export declare function listEnabledProjectRoots(): string[];
+/** True when this project root is on the opt-in allowlist. */
+export declare function isProjectRoutinesEnabled(projectRoot: string): boolean;
+/**
+ * True when the project's own `agents.yaml` opts into project routines:
+ * `routines: { enable: true }`. This is an additional source of opt-in that
+ * still requires the project to be present on disk; it does not auto-enable
+ * every clone — the project must declare it, and `sync` / `enable-project`
+ * still materialises consent into the user layer.
+ */
+export declare function projectAgentsYamlEnablesRoutines(projectRoot: string): boolean;
+/** Resolve the project root (parent of `.agents/`) from a cwd, or null. */
+export declare function resolveProjectRoot(cwd?: string): string | null;
+/**
+ * Opt a project root into daemon firing. Returns true when newly added,
+ * false when it was already enabled.
+ */
+export declare function enableProjectRoutines(projectRoot: string): boolean;
+/**
+ * Remove a project root from the opt-in allowlist. Optionally deletes the
+ * user-layer copies that were materialised from it.
+ */
+export declare function disableProjectRoutines(projectRoot: string, opts?: {
+    removeSynced?: boolean;
+}): {
+    removed: boolean;
+    deletedJobs: string[];
+};
+/** Git provenance for a project root (best-effort; never throws). */
+export declare function readProjectGitSource(projectRoot: string): Pick<JobSource, 'repo' | 'branch' | 'commit'>;
+/** List project routine YAML files (name + absolute path). */
+export declare function listProjectRoutineFiles(projectRoot: string): Array<{
+    name: string;
+    path: string;
+}>;
+export interface SyncProjectResult {
+    projectRoot: string;
+    synced: string[];
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+    removed: string[];
+    errors: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/**
+ * Materialise one project's routines into the user layer.
+ * - Overwrites user copies that already carry matching `source.projectPath`
+ * - Never clobbers a hand-authored user routine (no source / different source)
+ * - Removes user copies from this project whose YAML disappeared
+ * - Auto-pins `devices` for host/fleet/cloud placement when unset
+ */
+export declare function syncProjectRoutines(projectRoot: string): SyncProjectResult;
+export interface SyncAllResult {
+    projects: SyncProjectResult[];
+    /** Project roots that were listed but missing on disk. */
+    missing: string[];
+}
+/**
+ * Sync every project root on the user allowlist (`meta.routines.projects`),
+ * plus any explicit `extraRoots`. Project `agents.yaml` `routines.enable`
+ * alone never opts a path in — enable-project is required.
+ */
+export declare function syncAllProjectRoutines(opts?: {
+    extraRoots?: string[];
+}): SyncAllResult;
+/**
+ * Discover project routines at cwd for the setup UX. Returns null when no
+ * project `.agents/routines` dir exists.
+ */
+export declare function discoverProjectRoutinesAt(cwd?: string): {
+    projectRoot: string;
+    files: Array<{
+        name: string;
+        path: string;
+    }>;
+    enabled: boolean;
+} | null;

package/dist/lib/routines-project.js

@@ -0,0 +1,349 @@
+/**
+ * Project-level routine opt-in, source tracking, and user-layer sync.
+ *
+ * Project YAML under `<project>/.agents/routines/*.yml` is inspection-only by
+ * default (a cloned public repo must never auto-fire agent prompts). After an
+ * explicit opt-in, routines are materialised into `~/.agents/routines/` with
+ * `source:` provenance so the daemon — which only loads user + system layers —
+ * can fire them. `syncProjectRoutines` refreshes the user-layer copies when
+ * project YAML changes (also invoked on daemon SIGHUP).
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { execFileSync } from 'child_process';
+import { getProjectAgentsDir, getProjectRoutinesDir, readMeta, updateMeta, ensureAgentsDir, } from './state.js';
+import { readJob, writeJob, deleteJob, listJobs, validateJob, resolveHostStrategy, placementRequiresFiringPin, } from './routines.js';
+import { parseOwnerRepoFromRemote } from './registry.js';
+import { machineId } from './machine-id.js';
+import { isSafeSegmentName } from './paths.js';
+/** Expand `~/…` and resolve to an absolute path. */
+export function expandProjectPath(p) {
+    const trimmed = p.trim();
+    if (trimmed.startsWith('~/') || trimmed === '~') {
+        return path.resolve(trimmed.replace(/^~(?=$|[/\\])/, os.homedir()));
+    }
+    return path.resolve(trimmed);
+}
+/** Store paths home-relative when under $HOME so they travel across machines. */
+export function displayProjectPath(abs) {
+    const home = os.homedir();
+    const resolved = path.resolve(abs);
+    if (resolved === home)
+        return '~';
+    if (resolved.startsWith(home + path.sep)) {
+        return '~' + resolved.slice(home.length);
+    }
+    return resolved;
+}
+/** Project roots currently opted into daemon firing (absolute paths). */
+export function listEnabledProjectRoots() {
+    const meta = readMeta();
+    const raw = meta.routines?.projects ?? [];
+    const out = [];
+    const seen = new Set();
+    for (const p of raw) {
+        if (typeof p !== 'string' || p.trim() === '')
+            continue;
+        const abs = expandProjectPath(p);
+        if (seen.has(abs))
+            continue;
+        seen.add(abs);
+        out.push(abs);
+    }
+    return out;
+}
+/** True when this project root is on the opt-in allowlist. */
+export function isProjectRoutinesEnabled(projectRoot) {
+    const abs = expandProjectPath(projectRoot);
+    return listEnabledProjectRoots().some((p) => p === abs);
+}
+/**
+ * True when the project's own `agents.yaml` opts into project routines:
+ * `routines: { enable: true }`. This is an additional source of opt-in that
+ * still requires the project to be present on disk; it does not auto-enable
+ * every clone — the project must declare it, and `sync` / `enable-project`
+ * still materialises consent into the user layer.
+ */
+export function projectAgentsYamlEnablesRoutines(projectRoot) {
+    const agentsYaml = path.join(expandProjectPath(projectRoot), 'agents.yaml');
+    if (!fs.existsSync(agentsYaml))
+        return false;
+    try {
+        const parsed = yaml.parse(fs.readFileSync(agentsYaml, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return false;
+        const routines = parsed.routines;
+        if (!routines || typeof routines !== 'object')
+            return false;
+        return routines.enable === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve the project root (parent of `.agents/`) from a cwd, or null. */
+export function resolveProjectRoot(cwd = process.cwd()) {
+    const agentsDir = getProjectAgentsDir(cwd);
+    if (!agentsDir)
+        return null;
+    return path.dirname(agentsDir);
+}
+/**
+ * Opt a project root into daemon firing. Returns true when newly added,
+ * false when it was already enabled.
+ */
+export function enableProjectRoutines(projectRoot) {
+    const abs = expandProjectPath(projectRoot);
+    const stored = displayProjectPath(abs);
+    let added = false;
+    updateMeta((meta) => {
+        const projects = [...(meta.routines?.projects ?? [])];
+        const already = projects.some((p) => expandProjectPath(p) === abs);
+        if (already)
+            return meta;
+        projects.push(stored);
+        added = true;
+        return {
+            ...meta,
+            routines: {
+                ...(meta.routines ?? {}),
+                projects,
+            },
+        };
+    });
+    return added;
+}
+/**
+ * Remove a project root from the opt-in allowlist. Optionally deletes the
+ * user-layer copies that were materialised from it.
+ */
+export function disableProjectRoutines(projectRoot, opts = {}) {
+    const abs = expandProjectPath(projectRoot);
+    let removed = false;
+    updateMeta((meta) => {
+        const projects = meta.routines?.projects ?? [];
+        const next = projects.filter((p) => expandProjectPath(p) !== abs);
+        if (next.length === projects.length)
+            return meta;
+        removed = true;
+        return {
+            ...meta,
+            routines: {
+                ...(meta.routines ?? {}),
+                projects: next,
+            },
+        };
+    });
+    const deletedJobs = [];
+    if (opts.removeSynced) {
+        for (const job of listJobs()) {
+            if (job.source?.kind === 'project' && expandProjectPath(job.source.projectPath) === abs) {
+                if (deleteJob(job.name))
+                    deletedJobs.push(job.name);
+            }
+        }
+    }
+    return { removed, deletedJobs };
+}
+/** Git provenance for a project root (best-effort; never throws). */
+export function readProjectGitSource(projectRoot) {
+    const abs = expandProjectPath(projectRoot);
+    const out = {};
+    try {
+        const remote = execFileSync('git', ['-C', abs, 'remote', 'get-url', 'origin'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5_000,
+        }).trim();
+        const repo = parseOwnerRepoFromRemote(remote);
+        if (repo)
+            out.repo = repo;
+    }
+    catch { /* no origin */ }
+    try {
+        out.branch = execFileSync('git', ['-C', abs, 'rev-parse', '--abbrev-ref', 'HEAD'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5_000,
+        }).trim();
+        if (out.branch === 'HEAD')
+            delete out.branch; // detached
+    }
+    catch { /* not a git repo */ }
+    try {
+        out.commit = execFileSync('git', ['-C', abs, 'rev-parse', '--short', 'HEAD'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5_000,
+        }).trim();
+    }
+    catch { /* ignore */ }
+    return out;
+}
+/** List project routine YAML files (name + absolute path). */
+export function listProjectRoutineFiles(projectRoot) {
+    const routinesDir = getProjectRoutinesDir(expandProjectPath(projectRoot));
+    if (!routinesDir || !fs.existsSync(routinesDir))
+        return [];
+    return fs.readdirSync(routinesDir)
+        .filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'))
+        .map((f) => ({
+        name: f.replace(/\.ya?ml$/, ''),
+        path: path.join(routinesDir, f),
+    }))
+        .filter((e) => isSafeSegmentName(e.name));
+}
+function readProjectJobFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const parsed = yaml.parse(content);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (Object.prototype.hasOwnProperty.call(parsed, 'device'))
+            return null;
+        return {
+            mode: 'auto',
+            effort: 'auto',
+            timeout: '10m',
+            enabled: true,
+            ...parsed,
+            name: parsed.name || path.basename(filePath).replace(/\.ya?ml$/, ''),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Materialise one project's routines into the user layer.
+ * - Overwrites user copies that already carry matching `source.projectPath`
+ * - Never clobbers a hand-authored user routine (no source / different source)
+ * - Removes user copies from this project whose YAML disappeared
+ * - Auto-pins `devices` for host/fleet/cloud placement when unset
+ */
+export function syncProjectRoutines(projectRoot) {
+    ensureAgentsDir();
+    const abs = expandProjectPath(projectRoot);
+    const git = readProjectGitSource(abs);
+    const source = {
+        kind: 'project',
+        projectPath: abs,
+        ...(git.repo ? { repo: git.repo } : {}),
+        ...(git.branch ? { branch: git.branch } : {}),
+        ...(git.commit ? { commit: git.commit } : {}),
+    };
+    const result = {
+        projectRoot: abs,
+        synced: [],
+        skipped: [],
+        removed: [],
+        errors: [],
+    };
+    const files = listProjectRoutineFiles(abs);
+    const seenNames = new Set();
+    for (const file of files) {
+        seenNames.add(file.name);
+        const job = readProjectJobFile(file.path);
+        if (!job) {
+            result.errors.push({ name: file.name, error: 'unreadable or invalid YAML' });
+            continue;
+        }
+        const existing = readJob(file.name);
+        if (existing) {
+            const existingSource = existing.source;
+            const fromThisProject = existingSource?.kind === 'project'
+                && expandProjectPath(existingSource.projectPath) === abs;
+            if (!fromThisProject) {
+                result.skipped.push({
+                    name: file.name,
+                    reason: existingSource
+                        ? `user-layer routine already exists from another source (${existingSource.projectPath})`
+                        : 'user-layer routine already exists (hand-authored); not overwriting without source match',
+                });
+                continue;
+            }
+            // Preserve user-layer devices pin when project YAML omits it (same overlay
+            // semantics as listJobs project discovery).
+            if (job.devices === undefined && existing.devices && existing.devices.length > 0) {
+                job.devices = existing.devices;
+            }
+        }
+        // Placement that leaves the firing machine must pin devices to avoid
+        // every fleet daemon dispatching once.
+        const strategy = resolveHostStrategy(job);
+        if (placementRequiresFiringPin(strategy) && (!job.devices || job.devices.length === 0)) {
+            job.devices = [machineId()];
+        }
+        // Surface repo for list/display when project has a GitHub origin.
+        if (git.repo && !job.repo)
+            job.repo = git.repo;
+        job.source = source;
+        job.name = file.name;
+        const errors = validateJob(job);
+        if (errors.length > 0) {
+            result.errors.push({ name: file.name, error: errors.join('; ') });
+            continue;
+        }
+        try {
+            writeJob(job);
+            result.synced.push(file.name);
+        }
+        catch (err) {
+            result.errors.push({ name: file.name, error: err.message });
+        }
+    }
+    // Drop user-layer copies from this project that no longer exist in project YAML.
+    for (const job of listJobs()) {
+        if (job.source?.kind !== 'project')
+            continue;
+        if (expandProjectPath(job.source.projectPath) !== abs)
+            continue;
+        if (seenNames.has(job.name))
+            continue;
+        if (deleteJob(job.name))
+            result.removed.push(job.name);
+    }
+    return result;
+}
+/**
+ * Sync every project root on the user allowlist (`meta.routines.projects`),
+ * plus any explicit `extraRoots`. Project `agents.yaml` `routines.enable`
+ * alone never opts a path in — enable-project is required.
+ */
+export function syncAllProjectRoutines(opts = {}) {
+    const roots = new Set(listEnabledProjectRoots());
+    for (const r of opts.extraRoots ?? [])
+        roots.add(expandProjectPath(r));
+    const projects = [];
+    const missing = [];
+    for (const root of roots) {
+        if (!fs.existsSync(root)) {
+            missing.push(root);
+            continue;
+        }
+        projects.push(syncProjectRoutines(root));
+    }
+    return { projects, missing };
+}
+/**
+ * Discover project routines at cwd for the setup UX. Returns null when no
+ * project `.agents/routines` dir exists.
+ */
+export function discoverProjectRoutinesAt(cwd = process.cwd()) {
+    const projectRoot = resolveProjectRoot(cwd);
+    if (!projectRoot)
+        return null;
+    const routinesDir = getProjectRoutinesDir(projectRoot);
+    if (!routinesDir || !fs.existsSync(routinesDir))
+        return null;
+    const files = listProjectRoutineFiles(projectRoot);
+    if (files.length === 0)
+        return null;
+    return {
+        projectRoot,
+        files,
+        enabled: isProjectRoutinesEnabled(projectRoot) || projectAgentsYamlEnablesRoutines(projectRoot),
+    };
+}

package/dist/lib/routines.d.ts

@@ -14,6 +14,29 @@ export interface JobAllowConfig {
     sites?: string[];
     dirs?: string[];
 }
+/**
+ * Where a routine's job body executes when the daemon fires it.
+ * Distinct from `devices` (which daemon may *fire*) and from the CLI `--host`
+ * remote-management passthrough (manage routines *on* another machine).
+ */
+export type HostStrategy = 'local' | 'host' | 'fleet' | 'cloud';
+export declare const HOST_STRATEGIES: readonly HostStrategy[];
+/**
+ * Provenance for a routine that was materialised from a project
+ * (`.agents/routines/*.yml` synced into the user layer after opt-in).
+ */
+export interface JobSource {
+    /** Always `project` today; reserved for future layers. */
+    kind: 'project';
+    /** Absolute path to the project root that owns the YAML. */
+    projectPath: string;
+    /** GitHub `owner/repo` when the project has a GitHub origin remote. */
+    repo?: string;
+    /** Branch at last sync (when known). */
+    branch?: string;
+    /** Short commit SHA at last sync (when known). */
+    commit?: string;
+}
 /** GitHub webhook events a routine can be triggered by. */
 export type GithubTriggerEvent = 'pull_request' | 'push' | 'issue_comment' | 'workflow_run';
 /** Canonical set of accepted GitHub trigger events — single source for validation. */
@@ -102,15 +125,57 @@ export interface JobConfig {
      * `host` says where the dispatched run EXECUTES. CLI flag: `--run-on`
      * (`--host` on routines commands already means "manage routines on that
      * machine" via the remote passthrough).
+     *
+     * When `hostStrategy` is set, it owns placement semantics; `host` is then
+     * only required for `hostStrategy: host` (or when strategy is inferred from
+     * a bare `host:` field for back-compat).
      */
     host?: string;
+    /**
+     * Where the job body should run when the daemon fires it.
+     * - `local`  — on the firing machine (default / current behavior)
+     * - `host`   — on the named `host` over SSH (maps to `--run-on`)
+     * - `fleet`  — pick one online registered device per run (no cross-device
+     *              double-fire; the firing pin stays on `devices`)
+     * - `cloud`  — dispatch via the agent's native cloud provider
+     *
+     * CLI flag: `--placement` (not `--host`, which is the remote-management
+     * passthrough). Omitted strategy falls back to `host` when `host:` is set,
+     * otherwise `local`.
+     */
+    hostStrategy?: HostStrategy;
     /** Working directory on the host for `host:`-placed runs. */
     remoteCwd?: string;
+    /**
+     * Provenance for routines materialised from a project
+     * (`<project>/.agents/routines/*.yml` → user-layer copy after opt-in).
+     * Absent for hand-authored user/system routines.
+     */
+    source?: JobSource;
     variables?: Record<string, string>;
     sandbox?: boolean;
     allow?: JobAllowConfig;
     config?: Record<string, unknown>;
     version?: string;
+    /**
+     * Pin this routine to a signed-in account by identity (its login email, or its
+     * account key) instead of rotating. At launch it resolves to whichever
+     * installed version currently holds that account and runs pinned — no
+     * `balanced` rotation, no usage-read refresh, no failover onto other accounts.
+     *
+     * This is the durable way to keep concurrent unattended routines off a *shared*
+     * Claude OAuth credential: the refresh token is single-use and rotates
+     * server-side on every refresh, so two routines running the same account
+     * concurrently (on one box or across the fleet) mutually revoke each other —
+     * the `401 OAuth access token has been revoked` storm (RUSH-1957). Give each
+     * routine (or each device's routines) a distinct account and no run rotates a
+     * credential out from under another.
+     *
+     * Prefer this over `version:`, which pins a version *number* that is GC'd on
+     * the next agent upgrade — when the pinned version disappears the routine
+     * silently falls back to `balanced` and the stampede returns.
+     */
+    account?: string;
     runOnce?: boolean;
     endAt?: string;
     /**
@@ -147,6 +212,10 @@ export interface RunMeta {
     /** The host-task sidecar id backing a `host:` run; the daemon monitor
      *  finalizes the run by reconciling it against the remote `.exit`. */
     hostTaskId?: string;
+    /** Cloud provider task id when `hostStrategy: cloud` dispatched the run. */
+    cloudTaskId?: string;
+    /** Cloud provider id when the run was cloud-dispatched. */
+    cloudProvider?: string;
 }
 /**
  * Finalize a run record with a terminal status, computing `duration` from
@@ -165,6 +234,24 @@ export declare function finalizeRunMeta(meta: RunMeta, status: RunMeta['status']
  * catchup/overdue, manual run) gates on this.
  */
 export declare function jobRunsOnThisDevice(config: Pick<JobConfig, 'devices'>): boolean;
+/**
+ * Resolve the effective host strategy for a job.
+ * Bare `host:` without an explicit strategy implies `host` (back-compat with
+ * pre-hostStrategy YAML). Otherwise default to `local`.
+ */
+export declare function resolveHostStrategy(config: Pick<JobConfig, 'hostStrategy' | 'host'>): HostStrategy;
+/**
+ * Parse a CLI `--placement` value into a HostStrategy, or null when empty.
+ * Throws a human-readable Error for unknown values.
+ */
+export declare function parseHostStrategy(raw: string | undefined | null): HostStrategy | null;
+/**
+ * Strategies that dispatch the job body off the firing machine. Without a
+ * `devices` pin every daemon in the fleet would fire and each would dispatch
+ * once — N× duplicate runs. Callers pin to this machine when the user did not
+ * set an explicit allowlist.
+ */
+export declare function placementRequiresFiringPin(strategy: HostStrategy): boolean;
 /** Human presentation of a device-affinity mismatch for commands and runner. */
 export interface JobEligibilityResult {
     /** Full human message, e.g. "Job 'NAME' can only run on: a, b". */
@@ -251,6 +338,13 @@ export declare function parseTimeout(timeout: string): number | null;
 export declare function listRuns(jobName: string): RunMeta[];
 /** Get the most recent run for a job, or null if never run. */
 export declare function getLatestRun(jobName: string): RunMeta | null;
+/**
+ * Get the most recent COMPLETED run for a job, or null if none has completed.
+ * Used to resolve `{last_report}` so a failed run's error text (e.g. an auth
+ * login prompt written into report.md) can never be injected into the next
+ * run's prompt.
+ */
+export declare function getLatestCompletedRun(jobName: string): RunMeta | null;
 /** Persist run metadata to its run directory as meta.json. */
 export declare function writeRunMeta(meta: RunMeta): void;
 /** Read run metadata from disk. Returns null if missing or corrupt. */