@phnx-labs/agents-cli 1.20.63 → 1.20.64

package/dist/lib/crabbox/runtimes.js

@@ -79,6 +79,30 @@ export async function pickRuntimes(detected, prompt) {
     const { checkbox } = await import('@inquirer/prompts');
     return checkbox({ message: 'Provision which runtime(s) on the leased box?', choices });
 }
+/**
+ * The lease runtime to provision for a headless run of `agentName`.
+ *
+ * When the agent is itself a lease-capable runtime (claude/codex/gemini/grok)
+ * that IS the runtime to install. Otherwise fall back to the single signed-in
+ * lease runtime (preferring claude), or null when none is signed in. This is the
+ * non-interactive replacement for the runtime checkbox picker: `--lease` requires
+ * a prompt, so it is headless by contract and must never block on a TTY.
+ *
+ * Profile-dispatch agents (kimi/deepseek) and custom workflow agents that run
+ * under a non-obvious runtime are resolved separately — see RUSH-1725.
+ */
+export function inferLeaseRuntime(agentName, detected) {
+    const signedIn = detected.filter((d) => d.signedIn && d.credPath);
+    // The agent names a lease runtime directly: require that runtime to be signed
+    // in — never silently substitute a different one for an explicit `run <runtime>`
+    // (that would lease a billable box only to boot it "Not logged in"). Not signed
+    // in → null, so the caller exits with "sign into it locally first".
+    if (LEASE_RUNTIMES.some((c) => c.id === agentName)) {
+        return signedIn.find((d) => d.id === agentName)?.id ?? null;
+    }
+    // Custom/workflow agent: fall back to the signed-in runtime (preferring claude).
+    return signedIn.find((d) => d.id === 'claude')?.id ?? signedIn[0]?.id ?? null;
+}
 // A long random sentinel makes an accidental (or malicious) collision with a
 // token's contents effectively impossible, so the quoted heredoc can never be
 // closed early by the credential body.

package/dist/lib/daemon.js

@@ -329,7 +329,12 @@ export async function runDaemon() {
         log('WARN', `Secrets broker host skipped: ${err.message}`);
     }
     const scheduler = new JobScheduler(async (config) => {
-        log('INFO', `Triggering job '${config.name}' (agent: ${config.agent})`);
+        const jobLabel = config.command
+            ? 'command'
+            : config.workflow
+                ? `workflow: ${config.workflow}`
+                : `agent: ${config.agent}`;
+        log('INFO', `Triggering job '${config.name}' (${jobLabel})`);
         try {
             const meta = await executeJobDetached(config);
             log('INFO', `Job '${config.name}' spawned (run: ${meta.runId}, PID: ${meta.pid})`);

package/dist/lib/devices/health.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Device resource probing for `agents devices list`.
+ *
+ * One SSH round-trip per device gathers load average, memory pressure, and core
+ * count (mac + linux), parsed into a {@link DeviceStats}. Probes run in parallel
+ * with a bounded timeout so the list stays responsive — a slow or hung box
+ * degrades to "no stats" instead of blocking the whole table.
+ *
+ * The parsers are pure and unit-tested (health.test.ts). They mirror the ones in
+ * the Factory extension (apps/factory/src/core/deviceHealth.ts) — kept as a
+ * separate copy on purpose: the CLI does not import across packages.
+ */
+import type { DeviceProfile } from './registry.js';
+/** Default per-device probe budget. Short enough that the list never hangs on a
+ * wedged box, long enough for a cold relayed SSH handshake. */
+export declare const PROBE_TIMEOUT_MS = 2500;
+export interface DeviceStats {
+    host: string;
+    reachable: boolean;
+    loadAvg1?: number;
+    ncpu?: number;
+    /** loadAvg1 / ncpu * 100 — load normalized to core count (the "has room" number). */
+    loadPercent?: number;
+    memPercent?: number;
+    memTotalBytes?: number;
+    memFreeBytes?: number;
+    fetchedAt: number;
+}
+/** Compact human byte size: 512M, 64G, 1.5T (binary units, ≤1 decimal). */
+export declare function fmtBytes(bytes: number | undefined): string;
+export declare function parseUptime(out: string): {
+    loadAvg1?: number;
+};
+interface MemStats {
+    memPercent?: number;
+    memTotalBytes?: number;
+    memFreeBytes?: number;
+}
+export declare function parseVmStat(out: string): MemStats;
+export declare function parseLinuxMemInfo(out: string): MemStats;
+export declare function parseNcpu(out: string): {
+    ncpu?: number;
+};
+/** Assemble a DeviceStats from the three snippet sections. */
+export declare function parseProbeOutput(host: string, stdout: string, fetchedAt: number): DeviceStats;
+export interface FleetCapacity {
+    reachable: number;
+    cores: number;
+    memTotalBytes: number;
+    memFreeBytes: number;
+}
+/** Sum cores and memory across reachable devices for the summary footer. */
+export declare function fleetCapacity(statsList: Iterable<DeviceStats>): FleetCapacity;
+/** Headroom bucket from the worst of normalized-load and memory. */
+export type Headroom = 'idle' | 'light' | 'busy' | 'loaded' | 'unknown';
+export declare function headroom(stats: DeviceStats | undefined): Headroom;
+/** Probe one device over the same ssh path as `agents ssh <name>`. Never throws;
+ * an unreachable/slow/misconfigured device resolves to `reachable: false`. */
+export declare function probeDeviceStats(device: DeviceProfile, opts?: {
+    timeoutMs?: number;
+    now?: number;
+}): Promise<DeviceStats>;
+/** Probe the local machine directly (no ssh round-trip) — used for the "this
+ * machine" row so it always shows real numbers even if it isn't ssh-reachable
+ * from itself. */
+export declare function probeLocalStats(host: string, opts?: {
+    timeoutMs?: number;
+    now?: number;
+}): Promise<DeviceStats>;
+/** Probe many devices concurrently; returns a name→stats map. Bounded by the
+ * per-probe timeout, so total wall time ≈ the slowest single probe. The device
+ * named `selfName` is probed locally instead of over ssh. */
+export declare function probeFleetStats(devices: DeviceProfile[], opts?: {
+    timeoutMs?: number;
+    selfName?: string;
+}): Promise<Map<string, DeviceStats>>;
+export {};

package/dist/lib/devices/health.js

@@ -0,0 +1,186 @@
+/**
+ * Device resource probing for `agents devices list`.
+ *
+ * One SSH round-trip per device gathers load average, memory pressure, and core
+ * count (mac + linux), parsed into a {@link DeviceStats}. Probes run in parallel
+ * with a bounded timeout so the list stays responsive — a slow or hung box
+ * degrades to "no stats" instead of blocking the whole table.
+ *
+ * The parsers are pure and unit-tested (health.test.ts). They mirror the ones in
+ * the Factory extension (apps/factory/src/core/deviceHealth.ts) — kept as a
+ * separate copy on purpose: the CLI does not import across packages.
+ */
+import { execFile } from 'child_process';
+import { buildSshInvocation, writeAskpassShim } from './connect.js';
+/** Default per-device probe budget. Short enough that the list never hangs on a
+ * wedged box, long enough for a cold relayed SSH handshake. */
+export const PROBE_TIMEOUT_MS = 2_500;
+const SEP = '---AGSTAT---';
+/** One-shot remote snapshot: load, then memory (mac vm_stat else linux
+ * meminfo), then core count (linux nproc else mac hw.ncpu). */
+const PROBE_SNIPPET = `uptime; echo ${SEP}; (vm_stat 2>/dev/null || cat /proc/meminfo 2>/dev/null); echo ${SEP}; (nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null)`;
+/** Compact human byte size: 512M, 64G, 1.5T (binary units, ≤1 decimal). */
+export function fmtBytes(bytes) {
+    if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0)
+        return '—';
+    const units = ['B', 'K', 'M', 'G', 'T', 'P'];
+    let v = bytes;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    const s = v >= 100 || i <= 1 ? Math.round(v).toString() : v.toFixed(1).replace(/\.0$/, '');
+    return `${s}${units[i]}`;
+}
+export function parseUptime(out) {
+    const m = out.match(/load average[s]?:\s*([0-9]+[.,][0-9]+|[0-9]+)/i);
+    if (!m)
+        return {};
+    const v = parseFloat(m[1].replace(',', '.'));
+    if (!Number.isFinite(v))
+        return {};
+    return { loadAvg1: v };
+}
+export function parseVmStat(out) {
+    const pageSize = parseInt(out.match(/page size of\s+([0-9]+)\s+bytes/)?.[1] ?? '4096', 10);
+    const active = out.match(/Pages active:\s+([0-9]+)/);
+    const wired = out.match(/Pages wired down:\s+([0-9]+)/);
+    const compressed = out.match(/Pages occupied by compressor:\s+([0-9]+)/);
+    const free = out.match(/Pages free:\s+([0-9]+)/);
+    if (!active || !wired || !compressed || !free)
+        return {};
+    // macOS reclaims inactive + speculative pages on demand, so they count as
+    // available — folding them into "free" (as Activity Monitor / vm_pressure do)
+    // rather than "used" keeps the headroom bucket honest on a Mac.
+    const inactive = out.match(/Pages inactive:\s+([0-9]+)/);
+    const speculative = out.match(/Pages speculative:\s+([0-9]+)/);
+    const usedPages = parseInt(active[1], 10) + parseInt(wired[1], 10) + parseInt(compressed[1], 10);
+    const freePages = parseInt(free[1], 10) +
+        parseInt(inactive?.[1] ?? '0', 10) +
+        parseInt(speculative?.[1] ?? '0', 10);
+    const totalPages = usedPages + freePages;
+    if (totalPages <= 0)
+        return {};
+    return {
+        memPercent: (usedPages / totalPages) * 100,
+        memTotalBytes: totalPages * pageSize,
+        memFreeBytes: freePages * pageSize,
+    };
+}
+export function parseLinuxMemInfo(out) {
+    const total = out.match(/^MemTotal:\s+([0-9]+)/im);
+    const available = out.match(/^MemAvailable:\s+([0-9]+)/im);
+    if (!total || !available)
+        return {};
+    const tKb = parseInt(total[1], 10);
+    const aKb = parseInt(available[1], 10);
+    if (tKb <= 0)
+        return {};
+    return {
+        memPercent: Math.max(0, Math.min(100, ((tKb - aKb) / tKb) * 100)),
+        memTotalBytes: tKb * 1024,
+        memFreeBytes: aKb * 1024,
+    };
+}
+export function parseNcpu(out) {
+    const n = parseInt(out.trim().split(/\s+/)[0] ?? '', 10);
+    return Number.isFinite(n) && n > 0 ? { ncpu: n } : {};
+}
+/** Assemble a DeviceStats from the three snippet sections. */
+export function parseProbeOutput(host, stdout, fetchedAt) {
+    const [uptimePart = '', memPart = '', ncpuPart = ''] = stdout.split(SEP);
+    const { loadAvg1 } = parseUptime(uptimePart);
+    const mem = memPart.includes('MemTotal') ? parseLinuxMemInfo(memPart) : parseVmStat(memPart);
+    const { ncpu } = parseNcpu(ncpuPart);
+    const loadPercent = loadAvg1 !== undefined && ncpu ? (loadAvg1 / ncpu) * 100 : undefined;
+    return {
+        host,
+        reachable: true,
+        loadAvg1,
+        ncpu,
+        loadPercent,
+        memPercent: mem.memPercent,
+        memTotalBytes: mem.memTotalBytes,
+        memFreeBytes: mem.memFreeBytes,
+        fetchedAt,
+    };
+}
+/** Sum cores and memory across reachable devices for the summary footer. */
+export function fleetCapacity(statsList) {
+    const cap = { reachable: 0, cores: 0, memTotalBytes: 0, memFreeBytes: 0 };
+    for (const s of statsList) {
+        if (!s.reachable)
+            continue;
+        cap.reachable++;
+        cap.cores += s.ncpu ?? 0;
+        cap.memTotalBytes += s.memTotalBytes ?? 0;
+        cap.memFreeBytes += s.memFreeBytes ?? 0;
+    }
+    return cap;
+}
+export function headroom(stats) {
+    if (!stats || !stats.reachable)
+        return 'unknown';
+    const signals = [stats.loadPercent, stats.memPercent].filter((v) => typeof v === 'number');
+    if (signals.length === 0)
+        return 'unknown';
+    const worst = Math.max(...signals);
+    if (worst < 15)
+        return 'idle';
+    if (worst < 40)
+        return 'light';
+    if (worst < 75)
+        return 'busy';
+    return 'loaded';
+}
+/** Probe one device over the same ssh path as `agents ssh <name>`. Never throws;
+ * an unreachable/slow/misconfigured device resolves to `reachable: false`. */
+export function probeDeviceStats(device, opts = {}) {
+    const host = device.name;
+    const fetchedAt = opts.now ?? Date.now();
+    let args;
+    let env;
+    try {
+        const shim = writeAskpassShim();
+        // buildSshInvocation joins the cmd with spaces and hands the string to the
+        // remote login shell, which evaluates the snippet's `;`/`||` directly — no
+        // `sh -c` wrapper needed (and a wrapper would only re-quote the first token).
+        ({ args, env } = buildSshInvocation(device, [PROBE_SNIPPET], shim));
+    }
+    catch {
+        return Promise.resolve({ host, reachable: false, fetchedAt });
+    }
+    return new Promise((resolve) => {
+        execFile('ssh', args, { encoding: 'utf-8', env: { ...process.env, ...env }, timeout: opts.timeoutMs ?? PROBE_TIMEOUT_MS }, (err, stdout) => {
+            if (err || !stdout)
+                return resolve({ host, reachable: false, fetchedAt });
+            resolve(parseProbeOutput(host, stdout, fetchedAt));
+        });
+    });
+}
+/** Probe the local machine directly (no ssh round-trip) — used for the "this
+ * machine" row so it always shows real numbers even if it isn't ssh-reachable
+ * from itself. */
+export function probeLocalStats(host, opts = {}) {
+    const fetchedAt = opts.now ?? Date.now();
+    return new Promise((resolve) => {
+        execFile('sh', ['-c', PROBE_SNIPPET], { encoding: 'utf-8', timeout: opts.timeoutMs ?? PROBE_TIMEOUT_MS }, (err, stdout) => {
+            if (err || !stdout)
+                return resolve({ host, reachable: false, fetchedAt });
+            resolve(parseProbeOutput(host, stdout, fetchedAt));
+        });
+    });
+}
+/** Probe many devices concurrently; returns a name→stats map. Bounded by the
+ * per-probe timeout, so total wall time ≈ the slowest single probe. The device
+ * named `selfName` is probed locally instead of over ssh. */
+export async function probeFleetStats(devices, opts = {}) {
+    const entries = await Promise.all(devices.map(async (d) => {
+        const stats = d.name === opts.selfName
+            ? await probeLocalStats(d.name, opts)
+            : await probeDeviceStats(d, opts);
+        return [d.name, stats];
+    }));
+    return new Map(entries);
+}

package/dist/lib/mailbox.d.ts

@@ -69,3 +69,42 @@ export declare function drain(boxDir: string, boxId?: string, now?: Date): Mailb
 export declare function peek(boxDir: string, boxId?: string, now?: Date): MailboxMessage[];
 /** Delete pending (not-yet-claimed) inbox messages. Returns the count removed. */
 export declare function clear(boxDir: string): number;
+/** Which bucket a stored message currently sits in. */
+export type MailboxState = 'inbox' | 'processing' | 'consumed';
+/** A message read back from a box, tagged with the bucket it was found in. */
+export interface StoredMessage extends MailboxMessage {
+    state: MailboxState;
+}
+/** A stored message enriched with the mailbox identity used by comms renderers. */
+export interface CommsMsg {
+    from: string;
+    to: string;
+    toLabel: string;
+    ts: string;
+    text: string;
+    state: MailboxState;
+    box: string;
+}
+/**
+ * Enumerate the box ids under `root` (directory names that are valid mailbox
+ * ids). Read-only; does not create the root. Sorted for stable output.
+ */
+export declare function listBoxes(root?: string): string[];
+/**
+ * Read every message in a box across all three buckets (inbox, processing,
+ * consumed) WITHOUT consuming, sweeping, or archiving anything. Unlike `peek`,
+ * this includes `consumed/` — the delivered history — so callers can surface a
+ * communication log. Each row is tagged with its bucket. Sorted FIFO by msgId
+ * (which is time-sortable), oldest first.
+ */
+export declare function readBox(boxDir: string): StoredMessage[];
+/**
+ * Poll the complete spool and yield each message once when its box/msgId pair
+ * first appears. Existing messages establish the initial baseline unless
+ * `backfill` is requested; moving a message between buckets does not re-emit it.
+ */
+export declare function watchMessages(root: string, opts: {
+    signal?: AbortSignal;
+    intervalMs?: number;
+    backfill?: boolean;
+}): AsyncGenerator<CommsMsg>;

package/dist/lib/mailbox.js

@@ -267,3 +267,115 @@ export function clear(boxDir) {
     }
     return n;
 }
+/**
+ * Enumerate the box ids under `root` (directory names that are valid mailbox
+ * ids). Read-only; does not create the root. Sorted for stable output.
+ */
+export function listBoxes(root = getMailboxRootDir()) {
+    let names;
+    try {
+        names = fs.readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+    return names.filter((n) => isValidMailboxId(n) && fs.statSync(path.join(root, n)).isDirectory()).sort();
+}
+/**
+ * Read every message in a box across all three buckets (inbox, processing,
+ * consumed) WITHOUT consuming, sweeping, or archiving anything. Unlike `peek`,
+ * this includes `consumed/` — the delivered history — so callers can surface a
+ * communication log. Each row is tagged with its bucket. Sorted FIFO by msgId
+ * (which is time-sortable), oldest first.
+ */
+export function readBox(boxDir) {
+    const out = [];
+    const buckets = [
+        [inboxDir(boxDir), 'inbox'],
+        [processingDir(boxDir), 'processing'],
+        [consumedDir(boxDir), 'consumed'],
+    ];
+    for (const [dir, state] of buckets) {
+        for (const name of jsonFiles(dir)) {
+            const msg = readMessage(path.join(dir, name));
+            if (msg)
+                out.push({ ...msg, state });
+        }
+    }
+    out.sort((a, b) => (a.msgId < b.msgId ? -1 : a.msgId > b.msgId ? 1 : 0));
+    return out;
+}
+/**
+ * Poll the complete spool and yield each message once when its box/msgId pair
+ * first appears. Existing messages establish the initial baseline unless
+ * `backfill` is requested; moving a message between buckets does not re-emit it.
+ */
+export async function* watchMessages(root, opts) {
+    const seen = new Set();
+    const requestedInterval = opts.intervalMs ?? 500;
+    const intervalMs = Number.isFinite(requestedInterval) ? Math.max(1, requestedInterval) : 500;
+    let firstPoll = true;
+    while (!opts.signal?.aborted) {
+        const fresh = [];
+        for (const box of listBoxes(root)) {
+            for (const stored of readBox(mailboxDir(box, root))) {
+                const key = `${box}\0${stored.msgId}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                if (firstPoll && !opts.backfill)
+                    continue;
+                fresh.push({
+                    key,
+                    message: {
+                        from: stored.from || 'operator',
+                        to: stored.to,
+                        toLabel: box.slice(0, 8),
+                        ts: stored.ts,
+                        text: stored.text,
+                        state: stored.state,
+                        box,
+                    },
+                });
+            }
+        }
+        firstPoll = false;
+        fresh.sort((a, b) => compareWatched(a.message.ts, b.message.ts) ||
+            compareWatched(a.key, b.key));
+        for (const { message } of fresh) {
+            if (opts.signal?.aborted)
+                return;
+            yield message;
+        }
+        if (!await waitForMailboxPoll(intervalMs, opts.signal))
+            return;
+    }
+}
+function compareWatched(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Wait for the next poll, resolving immediately when the watcher is aborted. */
+function waitForMailboxPoll(intervalMs, signal) {
+    if (signal?.aborted)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        let timer;
+        let settled = false;
+        const finish = (keepWatching) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            resolve(keepWatching);
+        };
+        const onAbort = () => finish(false);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted) {
+            finish(false);
+            return;
+        }
+        timer = setTimeout(() => finish(true), intervalMs);
+    });
+}

package/dist/lib/paths.d.ts

@@ -1,3 +1,9 @@
+/**
+ * True when `name` is a safe single path segment: non-empty, not '.'/'..',
+ * free of path separators and null bytes, and within the filename length limit.
+ * Dot-prefixed names like '.env.example' are allowed.
+ */
+export declare function isSafeSegmentName(name: string): boolean;
 /**
  * Resolve base + name while preventing path-traversal attacks.
  * Rejects path separators, null bytes, '.' and '..', and any resolved path
@@ -6,3 +12,10 @@
  * Allows spaces, unicode, and other common filename characters.
  */
 export declare function safeJoin(base: string, name: string): string;
+/**
+ * Assert that `target` (which may legitimately contain path separators, e.g. a
+ * multi-segment relative key) stays within `root` after normalization. Use this
+ * where a caller must accept nested relative paths but the input is untrusted —
+ * `safeJoin` is stricter and only allows single segments.
+ */
+export declare function assertWithin(root: string, target: string): string;

package/dist/lib/paths.js

@@ -1,4 +1,15 @@
 import * as path from 'path';
+/**
+ * True when `name` is a safe single path segment: non-empty, not '.'/'..',
+ * free of path separators and null bytes, and within the filename length limit.
+ * Dot-prefixed names like '.env.example' are allowed.
+ */
+export function isSafeSegmentName(name) {
+    return (!!name &&
+        name !== '.' && name !== '..' &&
+        !/[\/\\\x00]/.test(name) &&
+        name.length <= 255);
+}
 /**
  * Resolve base + name while preventing path-traversal attacks.
  * Rejects path separators, null bytes, '.' and '..', and any resolved path
@@ -7,10 +18,7 @@ import * as path from 'path';
  * Allows spaces, unicode, and other common filename characters.
  */
 export function safeJoin(base, name) {
-    if (!name ||
-        name === '.' || name === '..' ||
-        /[\/\\\x00]/.test(name) ||
-        name.length > 255) {
+    if (!isSafeSegmentName(name)) {
         throw new Error(`Invalid name: ${name}`);
     }
     const resolved = path.resolve(base, name);
@@ -18,3 +26,17 @@ export function safeJoin(base, name) {
         throw new Error(`Path escape: ${name}`);
     return resolved;
 }
+/**
+ * Assert that `target` (which may legitimately contain path separators, e.g. a
+ * multi-segment relative key) stays within `root` after normalization. Use this
+ * where a caller must accept nested relative paths but the input is untrusted —
+ * `safeJoin` is stricter and only allows single segments.
+ */
+export function assertWithin(root, target) {
+    const base = path.resolve(root);
+    const resolved = path.resolve(target);
+    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+        throw new Error(`Path escape: ${target}`);
+    }
+    return resolved;
+}

package/dist/lib/routines.d.ts

@@ -66,8 +66,16 @@ export interface JobConfig {
     schedule?: string;
     /** Event/webhook fire condition. Optional when `schedule` is set. */
     trigger?: JobTrigger;
-    agent: AgentId;
+    /** Which agent runs the routine. Optional — omitted for `workflow`/`command` routines. Exactly one of agent/workflow/command must be set. */
+    agent?: AgentId;
     workflow?: string;
+    /**
+     * A plain shell command run directly instead of an agent/workflow — no LLM,
+     * no auth, no rotation, no tokens, no sandbox overlay. For deterministic
+     * housekeeping routines (version-check, `npm i -g`, `git pull`, notify).
+     * Mutually exclusive with `agent` and `workflow`.
+     */
+    command?: string;
     mode: 'plan' | 'edit' | 'auto' | 'skip' | 'full';
     effort: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
     timeout: string;
@@ -104,8 +112,10 @@ export interface JobConfig {
 export interface RunMeta {
     jobName: string;
     runId: string;
-    agent: AgentId;
+    agent?: AgentId;
     workflow?: string;
+    /** The shell command that ran, for command-mode routines (no agent). */
+    command?: string;
     pid: number | null;
     /** Process birth time (epoch ms) recorded at spawn for pid-reuse detection. */
     spawnedAt?: number;
@@ -205,6 +215,15 @@ export declare function getLatestRun(jobName: string): RunMeta | null;
 export declare function writeRunMeta(meta: RunMeta): void;
 /** Read run metadata from disk. Returns null if missing or corrupt. */
 export declare function readRunMeta(jobName: string, runId: string): RunMeta | null;
+/**
+ * Runs directory for a single job, with the (untrusted) job name contained to a
+ * single segment beneath the runs dir — same guard as `getJobHomePath`. The name
+ * comes from routine YAML and can arrive via a synced config repo; every runs-dir
+ * sink (run dir, meta read/write, last-report read) routes through here so a
+ * crafted `name` like `../../../../tmp/x` can't `mkdirSync`/write `stdout.log`,
+ * `meta.json`, or `report.md` outside `~/.agents/.history/runs`.
+ */
+export declare function getJobRunsDir(jobName: string): string;
 /** Get the filesystem path for a specific run's directory. */
 export declare function getRunDir(jobName: string, runId: string): string;
 /** Discover routine YAML files in a repository's routines/ directory. */