@phnx-labs/agents-cli 1.22.31 → 1.22.33

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

package/dist/lib/routines.d.ts

@@ -6,6 +6,7 @@
  * run metadata persistence, prompt variable expansion, and one-shot "at" time
  * scheduling.
  */
+import { type ResolvedExecutionContext, type ProjectResolution, type PlacementMode, type RoutineKind, type ContextFsProbe } from './routine-context.js';
 import type { AgentId } from './types.js';
 import type { LoopConfig } from './loop.js';
 /** Tool/site/directory allow-list for sandboxed job execution. */
@@ -114,6 +115,32 @@ export interface JobConfig {
     prompt: string;
     timezone?: string;
     repo?: string;
+    /**
+     * Singular execution anchor: the named project (`agents projects`) whose base
+     * directory the routine's run lands in. Optional. Metadata-only `projects[]`
+     * (below) is NEVER used for execution — this field is. Resolution happens on
+     * the execution TARGET (`resolveRoutineExecutionContext`, routine-context.ts),
+     * never from the daemon's own cwd: a project with a usable `defaultPath`/`root`
+     * gives the base directory; a rootless Linear-imported project gives no base,
+     * so a bare relative `cwd` then anchors at the target user's `$HOME`.
+     *
+     * CLI flag is `--project-anchor` (not `--project`, which is the repeatable
+     * grouping-metadata flag that writes `projects[]`). The YAML key is the shorter
+     * singular `project` because it is unambiguous there.
+     */
+    project?: string;
+    /**
+     * Portable execution directory for the routine's run. Optional. A relative
+     * value resolves under the `project` base when that base is usable, otherwise
+     * under the execution target's `$HOME` (so a Linear-imported rootless project
+     * can still name `cwd: src/github.com/acme/app`). A `~/`-anchored value is the
+     * target's home-relative path; an absolute path under the target home is
+     * normalized to the portable `~/…` form on save. An absolute path outside the
+     * home is only allowed for local-pinned routines — host/fleet/cloud placement
+     * pauses it as non-portable. Supersedes the legacy `remoteCwd`, which the
+     * one-shot migration folds into this field.
+     */
+    cwd?: string;
     /**
      * Fleet allowlist — restrict this routine to specific devices. When omitted
      * or empty, the routine is unrestricted and fires on every device running the
@@ -308,6 +335,24 @@ export declare function projectGroupOrder(group: ProjectGroup): number;
  * - `"Unknown projects"` — when any entry is no longer a defined project (stale).
  */
 export declare function computeProjectGroup(projects: string[] | undefined, knownProjectNames: Set<string>): string;
+/** A real-filesystem {@link ContextFsProbe} for readiness checks on this machine. */
+export declare function realFsProbe(): ContextFsProbe;
+/** Classify a routine by its body kind — governs the execution-context fallback rules. */
+export declare function jobRoutineKind(config: Pick<JobConfig, 'agent' | 'workflow' | 'command'>): RoutineKind;
+/**
+ * Resolve a routine's execution context (working directory + structural/fs
+ * readiness) by bridging its `project`/`cwd` fields into the pure
+ * {@link resolveRoutineExecutionContext} resolver. Local placement resolves
+ * against this machine's `$HOME` with a real filesystem probe; a caller may
+ * inject a different target home / probe (e.g. `null` to defer existence for a
+ * remote target).
+ */
+export declare function resolveJobExecutionContext(config: Pick<JobConfig, 'name' | 'project' | 'cwd' | 'agent' | 'workflow' | 'command'>, opts?: {
+    targetHome?: string;
+    mode?: PlacementMode;
+    probe?: ContextFsProbe | null;
+    projectResolution?: ProjectResolution;
+}): ResolvedExecutionContext;
 /** Metadata for a single job execution, persisted as JSON in the run directory. */
 export interface RunMeta {
     jobName: string;
@@ -337,8 +382,41 @@ export interface RunMeta {
      * due). Without it a miss leaves no trace at all and the listing keeps
      * showing the previous run's status as if it were current. Written by
      * `claimMissedFire` (catchup.ts), never by the runner.
+     *
+     * `blocked` and `skipped` are pre-execution terminals that leave a visible
+     * record even though no agent process ran (the plan's history contract):
+     * - `blocked` — a fire-time readiness rejection (bad context, dead auth,
+     *   untrusted workspace). No agent process was spawned. Distinct from `failed`,
+     *   which means a process started and failed.
+     * - `skipped` — the attempt lost a claim (`skipReason`): a duplicate schedule
+     *   slot, an already-active run it would overlap, or a wrong device owner.
+     */
+    status: 'running' | 'completed' | 'failed' | 'timeout' | 'missed' | 'blocked' | 'skipped';
+    /**
+     * How this attempt was triggered. Answers "why did this run exist" for a
+     * record that may have no transcript (a blocked/skipped attempt).
+     */
+    triggerKind?: 'schedule' | 'catchup' | 'manual' | 'webhook' | 'event';
+    /**
+     * The scheduler's intended UTC fire time (ISO), for a `schedule`/`catchup`
+     * attempt. The atomic single-fire claim keys on (routine, scheduledFor): a
+     * duplicate cron delivery for the same slot resolves to this same run rather
+     * than launching a second time.
      */
-    status: 'running' | 'completed' | 'failed' | 'timeout' | 'missed';
+    scheduledFor?: string;
+    /** Resolved execution context (routine-context.ts), recorded before preflight. */
+    project?: string;
+    requestedCwd?: string;
+    resolvedCwd?: string;
+    readiness?: {
+        code: string;
+        message: string;
+        repair?: string;
+    };
+    /** Why a `skipped` attempt launched nothing. */
+    skipReason?: 'duplicate_slot' | 'active_run' | 'wrong_owner';
+    /** The run this attempt deferred to (the winning duplicate slot / active run). */
+    activeRunId?: string;
     startedAt: string;
     completedAt: string | null;
     exitCode: number | null;
@@ -629,6 +707,24 @@ export declare function readRunMeta(jobName: string, runId: string): RunMeta | n
 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;
+/**
+ * The run id a scheduled fire is recorded under — derived from its intended UTC
+ * fire time so the SAME slot always maps to the SAME run directory. This is what
+ * makes the single-fire claim meaningful: a duplicate cron delivery for one slot
+ * computes the same id and loses the atomic `mkdir` claim. Shares the derivation
+ * with `missedRunId` (catchup.ts) so a missed-then-caught-up fire and a live fire
+ * for the same UTC slot are one record.
+ */
+export declare function slotRunId(scheduledFor: Date | string): string;
+/**
+ * Atomically CLAIM a run directory. Returns true on a successful claim, false
+ * when the directory already exists (another caller — even in a separate process
+ * — owns this (routine, slot) pair). The non-recursive `mkdir` is a single
+ * filesystem test-and-set on every POSIX filesystem, the same primitive
+ * `claimMissedFire` relies on; it holds across processes where an in-process flag
+ * or a released lock cannot.
+ */
+export declare function claimRunSlot(jobName: string, runId: string): boolean;
 /** Discover routine YAML files in a repository's routines/ directory. */
 export declare function discoverJobsFromRepo(repoPath: string): Array<{
     name: string;

package/dist/lib/routines.js

@@ -11,8 +11,10 @@ import * as path from 'path';
 import * as yaml from 'yaml';
 import { Cron } from 'croner';
 import { getRoutinesDir, getSystemRoutinesDir, getRunsDir, ensureAgentsDir, getProjectRoutinesDir } from './state.js';
+import * as os from 'os';
 import { safeJoin, isSafeSegmentName } from './paths.js';
-import { isSafeProjectName } from './projects.js';
+import { isSafeProjectName, loadProjectDef, projectBasePath } from './projects.js';
+import { resolveRoutineExecutionContext, } from './routine-context.js';
 import { atomicWriteFileSync } from './fs-atomic.js';
 import { ALL_AGENT_IDS, ROUTINE_AGENT_IDS } from './agents.js';
 import { machineId, normalizeHost } from './machine-id.js';
@@ -142,6 +144,65 @@ export function projectGroupOrder(group) {
 export function computeProjectGroup(projects, knownProjectNames) {
     return projectGroupTitle(computeProjectGroupKind(projects, knownProjectNames));
 }
+/** A real-filesystem {@link ContextFsProbe} for readiness checks on this machine. */
+export function realFsProbe() {
+    return {
+        exists: (p) => fs.existsSync(p),
+        isDirectory: (p) => { try {
+            return fs.statSync(p).isDirectory();
+        }
+        catch {
+            return false;
+        } },
+        isWritable: (p) => { try {
+            fs.accessSync(p, fs.constants.W_OK);
+            return true;
+        }
+        catch {
+            return false;
+        } },
+    };
+}
+/** Classify a routine by its body kind — governs the execution-context fallback rules. */
+export function jobRoutineKind(config) {
+    if (config.command)
+        return 'command';
+    if (config.workflow)
+        return 'workflow';
+    return 'agent';
+}
+/**
+ * Resolve a routine's execution context (working directory + structural/fs
+ * readiness) by bridging its `project`/`cwd` fields into the pure
+ * {@link resolveRoutineExecutionContext} resolver. Local placement resolves
+ * against this machine's `$HOME` with a real filesystem probe; a caller may
+ * inject a different target home / probe (e.g. `null` to defer existence for a
+ * remote target).
+ */
+export function resolveJobExecutionContext(config, opts = {}) {
+    const targetHome = opts.targetHome ?? os.homedir();
+    const mode = opts.mode ?? 'local';
+    const probe = opts.probe === null
+        ? undefined
+        : (opts.probe ?? (mode === 'local' ? realFsProbe() : undefined));
+    let projectResolution = opts.projectResolution;
+    if (config.project !== undefined && projectResolution === undefined) {
+        const def = loadProjectDef(config.project);
+        projectResolution = def
+            ? { defined: true, base: projectBasePath(def, true) } // portable (~/) base form
+            : { defined: false };
+    }
+    return resolveRoutineExecutionContext({
+        name: config.name,
+        project: config.project,
+        cwd: config.cwd,
+        kind: jobRoutineKind(config),
+        mode,
+        targetHome,
+        projectResolution,
+        probe,
+    });
+}
 /**
  * Finalize a run record with a terminal status, computing `duration` from
  * `startedAt` and the completion timestamp. Keeps failure-reason population
@@ -699,6 +760,18 @@ export function validateJob(config) {
     if (config.remoteCwd !== undefined && strategy !== 'host' && strategy !== 'fleet') {
         errors.push('remoteCwd only applies to host/fleet-placed routines — set hostStrategy: host|fleet, or drop it');
     }
+    if (config.project !== undefined && (typeof config.project !== 'string' || config.project.trim() === '')) {
+        errors.push('project (the singular execution anchor) must be a non-empty project name');
+    }
+    if (config.cwd !== undefined && (typeof config.cwd !== 'string' || config.cwd.trim() === '')) {
+        errors.push('cwd (the portable execution directory) must be a non-empty path string');
+    }
+    // `remoteCwd` is the legacy host-placement path; `cwd` is its canonical
+    // replacement. The two split path semantics, so they must never coexist — the
+    // one-shot migration folds remoteCwd into cwd, and a conflicting pair pauses.
+    if (config.cwd !== undefined && config.remoteCwd !== undefined) {
+        errors.push('cwd and remoteCwd both set — remoteCwd is the legacy form of cwd; keep only cwd');
+    }
     if (config.source !== undefined) {
         if (!config.source || typeof config.source !== 'object') {
             errors.push('source must be an object');
@@ -1168,6 +1241,39 @@ export function getJobRunsDir(jobName) {
 export function getRunDir(jobName, runId) {
     return path.join(getJobRunsDir(jobName), runId);
 }
+/**
+ * The run id a scheduled fire is recorded under — derived from its intended UTC
+ * fire time so the SAME slot always maps to the SAME run directory. This is what
+ * makes the single-fire claim meaningful: a duplicate cron delivery for one slot
+ * computes the same id and loses the atomic `mkdir` claim. Shares the derivation
+ * with `missedRunId` (catchup.ts) so a missed-then-caught-up fire and a live fire
+ * for the same UTC slot are one record.
+ */
+export function slotRunId(scheduledFor) {
+    const iso = typeof scheduledFor === 'string' ? scheduledFor : scheduledFor.toISOString();
+    return iso.replace(/[:.]/g, '-');
+}
+/**
+ * Atomically CLAIM a run directory. Returns true on a successful claim, false
+ * when the directory already exists (another caller — even in a separate process
+ * — owns this (routine, slot) pair). The non-recursive `mkdir` is a single
+ * filesystem test-and-set on every POSIX filesystem, the same primitive
+ * `claimMissedFire` relies on; it holds across processes where an in-process flag
+ * or a released lock cannot.
+ */
+export function claimRunSlot(jobName, runId) {
+    const runDir = getRunDir(jobName, runId);
+    fs.mkdirSync(path.dirname(runDir), { recursive: true });
+    try {
+        fs.mkdirSync(runDir); // non-recursive: throws EEXIST if already claimed
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return false;
+        throw err;
+    }
+}
 /** Discover routine YAML files in a repository's routines/ directory. */
 export function discoverJobsFromRepo(repoPath) {
     const jobsPath = path.join(repoPath, 'routines');

package/dist/lib/runner.d.ts

@@ -26,8 +26,22 @@ export interface RunResult {
 export declare class RoutineAlreadyRunningError extends Error {
     constructor(jobName: string, runId: string);
 }
-/** Stable working directory for routine children, independent of the daemon's launch cwd. */
-export declare function routineSpawnCwd(config: Pick<JobConfig, 'repo'>, configuredRoot?: string | undefined): string;
+/** How a routine attempt was triggered, plus the schedule slot it belongs to. */
+export interface RoutineTrigger {
+    kind: NonNullable<RunMeta['triggerKind']>;
+    /** UTC fire time for a schedule/catchup attempt; keys the single-fire slot claim. */
+    scheduledFor?: Date | string;
+}
+/**
+ * Working directory for a routine's LOCAL child, resolved from its explicit
+ * `project`/`cwd` execution anchor via {@link resolveJobExecutionContext} — never
+ * inferred from `repo` (which is external repository identity only) and never the
+ * daemon's launch cwd. A command routine with neither field lands in `$HOME`
+ * (housekeeping); an unresolved/blocked agent context also falls back to `$HOME`
+ * so a caller that reaches this (past the readiness gate) has a valid directory,
+ * but the gate should have paused such a routine before it ever spawned.
+ */
+export declare function routineSpawnCwd(config: Pick<JobConfig, 'name' | 'project' | 'cwd' | 'agent' | 'workflow' | 'command'>): string;
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export declare function buildJobCommand(config: JobConfig, resolvedPrompt: string): string[];
 /**
@@ -86,7 +100,7 @@ export declare function dispatchesViaAgentsRun(config: Pick<JobConfig, 'workflow
  * with `agents run`.
  */
 export declare function buildRoutineSpawnEnv(baseEnv: Record<string, string>, agent: AgentId, version: string | undefined, timezone?: string, overlayHome?: string): Record<string, string>;
-export declare function executeJob(config: JobConfig, deps?: LoopDeps): Promise<RunResult>;
+export declare function executeJob(config: JobConfig, deps?: LoopDeps, trigger?: RoutineTrigger): Promise<RunResult>;
 /**
  * Optional lifecycle callbacks for a detached routine run. The daemon passes an
  * `onFinish` that fires the branded finish/output notification (RUSH-2030) — it
@@ -99,7 +113,7 @@ export interface RoutineHooks {
     onFinish?: (meta: RunMeta) => void;
 }
 /** Spawn a job as a detached process and return immediately with run metadata. */
-export declare function executeJobDetached(config: JobConfig, hooks?: RoutineHooks): Promise<RunMeta>;
+export declare function executeJobDetached(config: JobConfig, hooks?: RoutineHooks, trigger?: RoutineTrigger): Promise<RunMeta>;
 /** Extract the final assistant message from a stream-JSON log file as a markdown report. */
 export declare function extractReport(stdoutPath: string, agentType: AgentId): string | null;
 /** Derive the final status of a detached run by reading the agent's stream-json