@phnx-labs/agents-cli 1.22.31 → 1.22.32

package/dist/lib/runner.js

@@ -17,7 +17,7 @@ import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { resolveJobPrompt, parseTimeout, writeRunMeta, listRuns, getJobRunsDir, getRunDir, checkJobDeviceEligibility, finalizeRunMeta, } from './routines.js';
+import { resolveJobPrompt, parseTimeout, writeRunMeta, listRuns, getJobRunsDir, getRunDir, checkJobDeviceEligibility, finalizeRunMeta, resolveJobExecutionContext, slotRunId, claimRunSlot, readRunMeta, resolveHostStrategy, } from './routines.js';
 import { getRunsDir, getUserAgentsDir } from './state.js';
 import { shortCodexHome } from './codex-home.js';
 import { prepareJobHome, buildSpawnEnv, getJobHomePath } from './sandbox.js';
@@ -38,7 +38,6 @@ import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rot
 import { readAuthHealth, isDeadVerdict } from './auth-health.js';
 import { machineId } from './machine-id.js';
 import { isSelfUpdatingAgent, ROUTINE_AGENT_COMMANDS as AGENT_COMMANDS, ROUTINE_AGENT_IDS, isAgentHardDeprecated, hardDeprecationError } from './agents.js';
-import { expandLocalHome, getProjectRoot } from './project-root.js';
 export class RoutineAlreadyRunningError extends Error {
     constructor(jobName, runId) {
         super(`Routine '${jobName}' already has a running execution (${runId})`);
@@ -65,7 +64,10 @@ function activeRoutineRun(config) {
     }
     return null;
 }
-async function withRoutineLaunchClaim(config, launch) {
+/** Serialize concurrent launches of one routine on this box (the on-disk claim
+ *  primitive `claimRunSlot` is what holds across processes; this lock only makes
+ *  the allocate→spawn window atomic within this process's launch paths). */
+async function withRoutineLock(config, launch) {
     const target = path.join(getJobRunsDir(config.name), '.launch-claim');
     ensureLockTarget(target, '', 0o700);
     const release = await lockfile.lock(target, {
@@ -78,15 +80,237 @@ async function withRoutineLaunchClaim(config, launch) {
         },
     });
     try {
-        const active = activeRoutineRun(config);
-        if (active)
-            throw new RoutineAlreadyRunningError(config.name, active.runId);
         return await launch();
     }
     finally {
         await release();
     }
 }
+/**
+ * Reject placement/body combinations the runner cannot execute — before the
+ * attempt is allocated, so an invalid config (host+workflow, cloud+command, …)
+ * throws cleanly rather than allocating a run record it can never satisfy. These
+ * mirror the defensive guards inside `executeJobOnHost`/`executeJobOnCloud`;
+ * `validateJob` already rejects the same combinations at add/edit time.
+ */
+function assertRunnablePlacement(config) {
+    const strategy = resolveHostStrategy(config);
+    if (strategy === 'host' || strategy === 'fleet') {
+        if (config.workflow)
+            throw new Error(`Routine '${config.name}' runs a workflow bundle, which can't execute on a host yet — remove 'host:' or 'workflow:'.`);
+        if (config.loop)
+            throw new Error(`Routine '${config.name}' uses 'loop:', which can't execute on a host yet — remove 'host:' or 'loop:'.`);
+        if (config.command)
+            throw new Error(`Routine '${config.name}' uses 'command:', which can't execute on a host yet — remove 'host:' or 'command:'.`);
+    }
+    if (strategy === 'cloud') {
+        if (config.workflow)
+            throw new Error(`Routine '${config.name}' runs a workflow bundle, which can't execute in the cloud yet — remove 'hostStrategy: cloud' or 'workflow:'.`);
+        if (config.loop)
+            throw new Error(`Routine '${config.name}' uses 'loop:', which can't execute in the cloud yet — remove 'hostStrategy: cloud' or 'loop:'.`);
+        if (config.command)
+            throw new Error(`Routine '${config.name}' uses 'command:', which can't execute in the cloud yet — remove 'hostStrategy: cloud' or 'command:'.`);
+    }
+}
+/** Write a pre-execution terminal record (blocked/skipped) that spawns nothing. */
+function writeTerminalRecord(config, runId, status, trigger, extra) {
+    fs.mkdirSync(getRunDir(config.name, runId), { recursive: true });
+    const now = new Date().toISOString();
+    const scheduledForIso = trigger.scheduledFor
+        ? (typeof trigger.scheduledFor === 'string' ? trigger.scheduledFor : trigger.scheduledFor.toISOString())
+        : undefined;
+    const meta = {
+        jobName: config.name,
+        runId,
+        ...runProvenance(config),
+        ...(config.workflow ? { workflow: config.workflow } : config.command ? { command: config.command } : config.agent ? { agent: config.agent } : {}),
+        triggerKind: trigger.kind,
+        ...(scheduledForIso ? { scheduledFor: scheduledForIso } : {}),
+        pid: null,
+        spawnedAt: Date.now(),
+        status,
+        startedAt: now,
+        completedAt: now,
+        exitCode: null,
+        duration: 0,
+        ...extra,
+    };
+    writeRunMeta(meta);
+    return meta;
+}
+/** Persist the cross-entry-point active claim before releasing the launch lock. */
+function writeActiveClaim(config, attempt) {
+    const now = new Date().toISOString();
+    const meta = {
+        jobName: config.name,
+        runId: attempt.runId,
+        ...runProvenance(config),
+        ...attempt.stamp,
+        ...(config.workflow ? { workflow: config.workflow } : config.command ? { command: config.command } : config.agent ? { agent: config.agent } : {}),
+        // The launcher owns this provisional claim until the command/agent child
+        // replaces it with its own pid. Recording the owner makes a crash between
+        // lock release and child spawn recoverable instead of wedging the routine
+        // for its full configured timeout.
+        pid: process.pid,
+        // `isPidOurs` compares this value with the OS process birth time. The
+        // daemon may have been alive for days before claiming a routine, so the
+        // claim must carry the launcher's birth, not the claim timestamp.
+        spawnedAt: Date.now() - process.uptime() * 1000,
+        status: 'running',
+        startedAt: now,
+        completedAt: null,
+        exitCode: null,
+        timeoutMs: parseTimeout(config.timeout) || 10 * 60 * 1000,
+    };
+    writeRunMeta(meta);
+    return meta;
+}
+/**
+ * Allocate a routine attempt BEFORE any placement / version / sandbox / preflight
+ * / dispatch work, so every rejected, skipped, or blocked fire leaves exactly one
+ * visible terminal record. Runs inside {@link withRoutineLock}. Enforces, in order:
+ *
+ *  1. single-fire — a scheduled slot atomically claims its (routine, UTC) run
+ *     directory; a duplicate cron delivery for the same slot returns the original
+ *     attempt and spawns nothing.
+ *  2. non-overlap — a prior run of this routine that is still active makes this
+ *     attempt a `skipped`/`active_run` record linking the live run.
+ *  3. readiness — an unresolved/blocked execution context (bad cwd, non-portable
+ *     path, missing project base, …) makes this a `blocked` record.
+ */
+function allocateRoutineAttempt(config, trigger) {
+    const scheduledForIso = trigger.scheduledFor
+        ? (typeof trigger.scheduledFor === 'string' ? trigger.scheduledFor : trigger.scheduledFor.toISOString())
+        : undefined;
+    // 1. Slot claim (schedule/catchup). Manual/webhook/event fires get a fresh id.
+    let runId;
+    if (scheduledForIso) {
+        runId = slotRunId(scheduledForIso);
+        if (!claimRunSlot(config.name, runId)) {
+            const existing = readRunMeta(config.name, runId);
+            if (existing)
+                return { proceed: false, terminal: existing };
+            return {
+                proceed: false,
+                terminal: writeTerminalRecord(config, generateRunId(), 'skipped', trigger, {
+                    skipReason: 'duplicate_slot',
+                    activeRunId: runId,
+                    errorMessage: 'duplicate schedule-slot delivery — the slot is already claimed',
+                }),
+            };
+        }
+    }
+    else {
+        runId = generateRunId();
+        fs.mkdirSync(getRunDir(config.name, runId), { recursive: true });
+    }
+    // 2. Non-overlap: a prior run of THIS routine is still live.
+    const active = activeRoutineRun(config);
+    if (active && active.runId !== runId) {
+        return {
+            proceed: false,
+            terminal: writeTerminalRecord(config, runId, 'skipped', trigger, {
+                skipReason: 'active_run',
+                activeRunId: active.runId,
+                errorMessage: `skipped — '${config.name}' already has an active run (${active.runId})`,
+            }),
+        };
+    }
+    const eligibility = checkJobDeviceEligibility(config);
+    if (eligibility) {
+        return {
+            proceed: false,
+            terminal: writeTerminalRecord(config, runId, 'skipped', trigger, {
+                skipReason: 'wrong_owner',
+                errorMessage: eligibility.message,
+            }),
+        };
+    }
+    if (!config.workflow && config.agent && ROUTINE_AGENT_IDS.includes(config.agent) && isAgentHardDeprecated(config.agent)) {
+        const reason = hardDeprecationError(config.agent);
+        return {
+            proceed: false,
+            terminal: writeTerminalRecord(config, runId, 'blocked', trigger, {
+                readiness: { code: 'agent_unavailable', message: reason },
+                errorMessage: reason,
+            }),
+        };
+    }
+    try {
+        assertRunnablePlacement(config);
+    }
+    catch (err) {
+        const message = err.message;
+        return {
+            proceed: false,
+            terminal: writeTerminalRecord(config, runId, 'blocked', trigger, {
+                readiness: { code: 'placement_unsupported', message },
+                errorMessage: message,
+            }),
+        };
+    }
+    // 3. Readiness: resolve the execution context for the routine's placement.
+    //    Local placement inspects this box's filesystem; host/fleet/cloud defer
+    //    existence (the remote fs is unreachable here) and enforce portability only.
+    const mode = resolveHostStrategy(config);
+    const ctx = resolveJobExecutionContext(config, {
+        mode,
+        probe: mode === 'local' ? undefined : null,
+    });
+    const stamp = {
+        triggerKind: trigger.kind,
+        ...(scheduledForIso ? { scheduledFor: scheduledForIso } : {}),
+        ...(config.project ? { project: config.project } : {}),
+        ...(config.cwd ? { requestedCwd: config.cwd } : {}),
+        ...(ctx.resolvedCwd ? { resolvedCwd: ctx.resolvedCwd } : {}),
+    };
+    if (!ctx.ready) {
+        return {
+            proceed: false,
+            terminal: writeTerminalRecord(config, runId, 'blocked', trigger, {
+                ...stamp,
+                readiness: ctx.readiness,
+                errorMessage: `blocked: ${ctx.readiness?.code ?? 'not_ready'}${ctx.readiness?.message ? ` — ${ctx.readiness.message}` : ''}`,
+            }),
+        };
+    }
+    return { proceed: true, attempt: { runId, stamp } };
+}
+/**
+ * Claim one routine attempt under the short launch lock, then execute after
+ * releasing it. The persisted `running` claim makes a concurrent entry point
+ * skip immediately instead of waiting for a foreground run to finish. `run` is
+ * the placement/command/agent dispatch, invoked only when the attempt proceeds;
+ * `wrapTerminal` adapts a pre-spawn terminal record into the caller's return type.
+ */
+async function runWithAttempt(config, trigger, run, wrapTerminal) {
+    const claimed = await withRoutineLock(config, async () => {
+        const alloc = allocateRoutineAttempt(config, trigger);
+        if (!alloc.proceed)
+            return { terminal: alloc.terminal };
+        writeActiveClaim(config, alloc.attempt);
+        return { attempt: alloc.attempt };
+    });
+    if ('terminal' in claimed)
+        return wrapTerminal(claimed.terminal);
+    try {
+        return await run(claimed.attempt);
+    }
+    catch (err) {
+        const message = err.message;
+        const existing = readRunMeta(config.name, claimed.attempt.runId);
+        if (existing) {
+            finalizeRunMeta(existing, 'failed', 1, { errorMessage: message });
+            writeRunMeta(existing);
+            return wrapTerminal(existing);
+        }
+        return wrapTerminal(writeTerminalRecord(config, claimed.attempt.runId, 'blocked', trigger, {
+            ...claimed.attempt.stamp,
+            readiness: { code: 'target_unreachable', message },
+            errorMessage: message,
+        }));
+    }
+}
 function terminateRoutineTree(pid) {
     if (!pid)
         return;
@@ -131,17 +355,18 @@ const ROUTINE_TRANSCRIPT_SPECS = {
     // Muse: ~/.local/share/muse/sessions/YYYY/MM/DD/<uuid>/session.jsonl
     muse: [{ root: ['.local', 'share', 'muse', 'sessions'], ext: '.jsonl' }],
 };
-/** Stable working directory for routine children, independent of the daemon's launch cwd. */
-export function routineSpawnCwd(config, configuredRoot = getProjectRoot()) {
-    if (!config.repo)
-        return os.homedir();
-    const [owner, repo] = config.repo.split('/');
-    if (configuredRoot) {
-        const root = path.resolve(expandLocalHome(configuredRoot));
-        if (path.basename(root) === owner)
-            return path.join(root, repo);
-    }
-    return path.join(os.homedir(), 'src', 'github.com', owner, repo);
+/**
+ * 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 function routineSpawnCwd(config) {
+    const ctx = resolveJobExecutionContext(config, { mode: 'local' });
+    return ctx.absoluteCwd ?? os.homedir();
 }
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export function buildJobCommand(config, resolvedPrompt) {
@@ -772,53 +997,13 @@ function injectRoutineActor(env, config) {
         env.AGENTS_ACTOR = config.actor;
     return env;
 }
-/**
- * `routines add`/`routines edit` refuse to create a routine pinned to a
- * hard-deprecated harness (commands/routines.ts), but that check runs only at
- * CLI-write time. A routine YAML written before the harness was deprecated, or
- * edited directly on disk / synced from another device, has no equivalent gate
- * at fire time — the daemon would happily build and spawn `gemini …` against a
- * backend Google retired. Fail loud here, before any version/account
- * resolution or sandbox prep, so a legacy routine skips with the same message
- * every other entry point (`sync`, `exec`, `import`, `run-cloud`, `versions`)
- * already shows instead of a doomed, confusing spawn failure.
- */
-function hardDeprecationRunFailure(config, agent) {
-    const runId = generateRunId();
-    const runDir = getRunDir(config.name, runId);
-    fs.mkdirSync(runDir, { recursive: true });
-    const reason = hardDeprecationError(agent);
-    const meta = {
-        jobName: config.name,
-        runId,
-        ...runProvenance(config),
-        agent,
-        pid: null,
-        spawnedAt: Date.now(),
-        status: 'running',
-        startedAt: new Date().toISOString(),
-        completedAt: null,
-        exitCode: null,
-    };
-    writeRunMeta(meta);
-    process.stderr.write(`[agents] routine ${config.name}: ${reason}\n`);
-    finalizeRunMeta(meta, 'failed', 1, { errorMessage: reason });
-    writeRunMeta(meta);
-    return meta;
+export async function executeJob(config, deps, trigger = { kind: 'manual' }) {
+    // Unified attempt: allocate + persist the run record (or a terminal blocked/
+    // skipped record) BEFORE placement, version selection, sandbox, or preflight —
+    // and hold the active-run claim so a manual run cannot overlap a scheduled one.
+    return runWithAttempt(config, trigger, (attempt) => executeJobPlaced(config, deps, attempt), (meta) => ({ meta, reportPath: null }));
 }
-export async function executeJob(config, deps) {
-    const eligibility = checkJobDeviceEligibility(config);
-    if (eligibility) {
-        throw new Error(eligibility.message);
-    }
-    // Hard-deprecated harness (e.g. gemini): fail loud before placement, version/
-    // account resolution, or sandbox prep — local, host, AND cloud placement all
-    // share this one gate (a hard-deprecated agent has no `cloudProvider` entry,
-    // so cloud placement would otherwise silently fall back to the default
-    // provider instead of refusing). See hardDeprecationRunFailure.
-    if (!config.workflow && config.agent && ROUTINE_AGENT_IDS.includes(config.agent) && isAgentHardDeprecated(config.agent)) {
-        return { meta: hardDeprecationRunFailure(config, config.agent), reportPath: null };
-    }
+async function executeJobPlaced(config, deps, attempt) {
     // Placement (hostStrategy / bare host:) — body may run on another machine
     // over SSH or in the cloud; local version selection / sandbox / spawn then
     // do not apply. Sync callers (manual `routines run`, catchup) follow the
@@ -827,17 +1012,17 @@ export async function executeJob(config, deps) {
         const { resolvePlacementTarget } = await import('./routines-placement.js');
         const target = resolvePlacementTarget(config);
         if (target.mode === 'host') {
-            return executeJobOnHost({ ...config, host: target.host }, { detached: false });
+            return executeJobOnHost({ ...config, host: target.host }, { detached: false }, attempt);
         }
         if (target.mode === 'cloud') {
-            return executeJobOnCloud(config, { detached: false });
+            return executeJobOnCloud(config, { detached: false }, attempt);
         }
     }
     // Command-mode: run a plain shell command directly (no agent, no rotation,
     // no pinning, no sandbox overlay). Reuses the run-record machinery so
     // list/runs/overdue keep working.
     if (config.command) {
-        return executeCommandJobForeground(config);
+        return executeCommandJobForeground(config, attempt);
     }
     const launch = await resolveRoutineLaunch(config);
     const primaryVersion = launch.chain[0]?.version ?? config.version;
@@ -856,7 +1041,7 @@ export async function executeJob(config, deps) {
     // `config.sandbox` (see the resume branch in buildJobCommand).
     const useSandbox = config.sandbox !== false && !config.resume;
     const overlayHome = useSandbox ? prepareJobHome(config) : undefined;
-    const runId = generateRunId();
+    const runId = attempt.runId;
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
     const baseEnv = injectRoutineActor(useSandbox
@@ -870,6 +1055,7 @@ export async function executeJob(config, deps) {
         jobName: config.name,
         runId,
         ...runProvenance(config),
+        ...attempt.stamp,
         agent: effectiveAgent,
         version: primaryVersion,
         ...(config.workflow ? { workflow: config.workflow } : {}),
@@ -1070,7 +1256,7 @@ export async function executeJob(config, deps) {
  * default). Writes a local run record with `cloudTaskId` so list/runs still
  * work; does not wait for cloud completion on the detached path.
  */
-async function executeJobOnCloud(config, opts) {
+async function executeJobOnCloud(config, opts, attempt) {
     if (config.workflow) {
         throw new Error(`Routine '${config.name}' runs a workflow bundle, which can't execute in the cloud yet — remove 'hostStrategy: cloud' or 'workflow:'.`);
     }
@@ -1094,13 +1280,14 @@ async function executeJobOnCloud(config, opts) {
         ...redactPrompt(config.prompt),
         schedule: config.schedule,
     });
-    const runId = generateRunId();
+    const runId = attempt.runId;
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
     const meta = {
         jobName: config.name,
         runId,
         ...runProvenance(config),
+        ...attempt.stamp,
         agent: config.agent,
         pid: null,
         spawnedAt: Date.now(),
@@ -1146,7 +1333,7 @@ async function executeJobOnCloud(config, opts) {
         throw err;
     }
 }
-async function executeJobOnHost(config, opts) {
+async function executeJobOnHost(config, opts, attempt) {
     if (config.workflow) {
         throw new Error(`Routine '${config.name}' runs a workflow bundle, which can't execute on a host yet — remove 'host:' or 'workflow:'.`);
     }
@@ -1158,6 +1345,11 @@ async function executeJobOnHost(config, opts) {
     }
     const { resolveHostRunTarget, dispatchPromptToHost } = await import('./hosts/run-target.js');
     const host = await resolveHostRunTarget(config.host);
+    const { evaluateHostActivationReadiness } = await import('./routine-readiness.js');
+    const readiness = await evaluateHostActivationReadiness(config);
+    if (!readiness.ready)
+        throw new Error(`${readiness.readiness?.code ?? 'not_ready'}: ${readiness.readiness?.message ?? 'target is not ready'}`);
+    const remoteCwd = readiness.context.resolvedCwd;
     const timer = createTimer('agent.run', {
         agent: config.agent,
         jobName: config.name,
@@ -1166,13 +1358,14 @@ async function executeJobOnHost(config, opts) {
         ...redactPrompt(config.prompt),
         schedule: config.schedule,
     });
-    const runId = generateRunId();
+    const runId = attempt.runId;
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
     const meta = {
         jobName: config.name,
         runId,
         ...runProvenance(config),
+        ...attempt.stamp,
         agent: config.agent,
         pid: null, // no local process — the run lives on the host
         spawnedAt: Date.now(),
@@ -1190,7 +1383,7 @@ async function executeJobOnHost(config, opts) {
         effort: config.effort,
         model: config.config?.model,
         timeout: config.timeout, // enforced by the REMOTE agents run
-        remoteCwd: config.remoteCwd,
+        remoteCwd,
         name: config.name,
         cwd: runDir,
         follow: !opts.detached,
@@ -1206,13 +1399,13 @@ async function executeJobOnHost(config, opts) {
     return { meta, reportPath: null };
 }
 /** Spawn a job as a detached process and return immediately with run metadata. */
-async function executeCommandJobForeground(config) {
+async function executeCommandJobForeground(config, attempt) {
     const timer = createTimer('agent.run', {
         jobName: config.name,
         mode: config.mode,
         schedule: config.schedule,
     });
-    const runId = generateRunId();
+    const runId = attempt.runId;
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
     const stdoutPath = path.join(runDir, 'stdout.log');
@@ -1221,6 +1414,7 @@ async function executeCommandJobForeground(config) {
         jobName: config.name,
         runId,
         ...runProvenance(config),
+        ...attempt.stamp,
         command: config.command,
         pid: null,
         spawnedAt: Date.now(),
@@ -1300,23 +1494,10 @@ function safeHook(fn) {
     catch { /* hooks are best-effort */ }
 }
 /** Spawn a job as a detached process and return immediately with run metadata. */
-export async function executeJobDetached(config, hooks) {
-    const eligibility = checkJobDeviceEligibility(config);
-    if (eligibility) {
-        process.stderr.write(`[agents] daemon: skipping '${config.name}' — ${eligibility.message}\n`);
-        throw new Error(eligibility.message);
-    }
-    return withRoutineLaunchClaim(config, () => executeJobDetachedClaimed(config, hooks));
+export async function executeJobDetached(config, hooks, trigger = { kind: 'manual' }) {
+    return runWithAttempt(config, trigger, (attempt) => executeJobDetachedClaimed(config, attempt, hooks), (meta) => meta);
 }
-async function executeJobDetachedClaimed(config, hooks) {
-    // Hard-deprecated harness (e.g. gemini): fail loud before placement, version/
-    // account resolution, or sandbox prep — local, host, AND cloud placement all
-    // share this one gate (a hard-deprecated agent has no `cloudProvider` entry,
-    // so cloud placement would otherwise silently fall back to the default
-    // provider instead of refusing). See hardDeprecationRunFailure.
-    if (!config.workflow && config.agent && ROUTINE_AGENT_IDS.includes(config.agent) && isAgentHardDeprecated(config.agent)) {
-        return hardDeprecationRunFailure(config, config.agent);
-    }
+async function executeJobDetachedClaimed(config, attempt, hooks) {
     // Placement (hostStrategy / bare host:) — dispatch off-box and return; the
     // monitor finalizes host: runs, cloud runs stay terminal when dispatch ends.
     // Either way the in-process onFinish hook does not fire for off-box routines
@@ -1326,11 +1507,11 @@ async function executeJobDetachedClaimed(config, hooks) {
         const { resolvePlacementTarget } = await import('./routines-placement.js');
         const target = resolvePlacementTarget(config);
         if (target.mode === 'host') {
-            const { meta } = await executeJobOnHost({ ...config, host: target.host }, { detached: true });
+            const { meta } = await executeJobOnHost({ ...config, host: target.host }, { detached: true }, attempt);
             return meta;
         }
         if (target.mode === 'cloud') {
-            const { meta } = await executeJobOnCloud(config, { detached: true });
+            const { meta } = await executeJobOnCloud(config, { detached: true }, attempt);
             return meta;
         }
     }
@@ -1338,7 +1519,7 @@ async function executeJobDetachedClaimed(config, hooks) {
     // no pinning, no sandbox overlay). Still writes a run record so the daemon,
     // list/runs, and overdue tracking keep working.
     if (config.command) {
-        return executeCommandJobDetached(config, hooks);
+        return executeCommandJobDetached(config, attempt, hooks);
     }
     // Pre-flight: pick a healthy version/account so the daemon does not launch
     // into a credit-exhausted install. Detached cannot mid-run failover (no exit
@@ -1366,7 +1547,7 @@ async function executeJobDetachedClaimed(config, hooks) {
     // `config.sandbox` (see the resume branch in buildJobCommand).
     const useSandbox = config.sandbox !== false && !config.resume;
     const overlayHome = useSandbox ? prepareJobHome(config) : undefined;
-    const runId = generateRunId();
+    const runId = attempt.runId;
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
     const stdoutPath = path.join(runDir, 'stdout.log');
@@ -1388,6 +1569,7 @@ async function executeJobDetachedClaimed(config, hooks) {
         jobName: config.name,
         runId,
         ...runProvenance(config),
+        ...attempt.stamp,
         agent: effectiveAgent,
         version,
         ...(config.workflow ? { workflow: config.workflow } : {}),
@@ -1500,13 +1682,13 @@ async function executeJobDetachedClaimed(config, hooks) {
  * un-sandboxed, unref, then record the pid. The daemon does not wait for exit;
  * `monitorRunningJobs` reaps the record on the next tick.
  */
-function executeCommandJobDetached(config, hooks) {
+function executeCommandJobDetached(config, attempt, hooks) {
     const timer = createTimer('agent.run', {
         jobName: config.name,
         mode: config.mode,
         schedule: config.schedule,
     });
-    const runId = generateRunId();
+    const runId = attempt.runId;
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
     const stdoutPath = path.join(runDir, 'stdout.log');
@@ -1528,6 +1710,7 @@ function executeCommandJobDetached(config, hooks) {
         jobName: config.name,
         runId,
         ...runProvenance(config),
+        ...attempt.stamp,
         command: config.command,
         pid: null,
         spawnedAt: Date.now(),
@@ -1781,8 +1964,18 @@ export function monitorRunningJobs() {
         .filter((e) => e.isDirectory());
     for (const jobDir of jobDirs) {
         const jobRunsPath = path.join(runsDir, jobDir.name);
-        const runDirs = fs.readdirSync(jobRunsPath, { withFileTypes: true })
-            .filter((e) => e.isDirectory());
+        let runDirs;
+        try {
+            runDirs = fs.readdirSync(jobRunsPath, { withFileTypes: true })
+                .filter((e) => e.isDirectory());
+        }
+        catch (err) {
+            // A retention/cleanup pass may remove a job directory after the root
+            // snapshot. The next monitor sweep observes the remaining state.
+            if (err.code === 'ENOENT')
+                continue;
+            throw err;
+        }
         for (const runDirEntry of runDirs) {
             const metaPath = path.join(jobRunsPath, runDirEntry.name, 'meta.json');
             if (!fs.existsSync(metaPath))

package/dist/lib/scheduler.d.ts

@@ -6,11 +6,17 @@
  * on startup and reloads them on SIGHUP.
  */
 import type { JobConfig } from './routines.js';
+/** How a fire was triggered, carrying the scheduler's intended UTC slot time. */
+export interface TriggerContext {
+    /** The cron slot this callback fires for (croner `currentRun()`), for the
+     *  single-fire claim keyed on (routine, scheduledFor). */
+    scheduledFor?: Date;
+}
 /** In-memory cron scheduler that triggers a callback when jobs fire. */
 export declare class JobScheduler {
     private jobs;
     private onTrigger;
-    constructor(onTrigger: (config: JobConfig) => Promise<void>);
+    constructor(onTrigger: (config: JobConfig, ctx?: TriggerContext) => Promise<void>);
     loadAll(): void;
     schedule(config: JobConfig): void;
     unschedule(name: string): void;

package/dist/lib/scheduler.js

@@ -59,7 +59,7 @@ export class JobScheduler {
         const cronOptions = { catch: true };
         if (config.timezone)
             cronOptions.timezone = config.timezone;
-        const cron = new Cron(config.schedule, cronOptions, async () => {
+        const cron = new Cron(config.schedule, cronOptions, async (self) => {
             // endAt: once the configured end time has passed, auto-disable and stop
             // firing. We persist enabled=false to disk so the next daemon reload
             // doesn't re-schedule, and unschedule in-memory so this cron stops.
@@ -75,7 +75,10 @@ export class JobScheduler {
                 return;
             }
             try {
-                await this.onTrigger(config);
+                // croner hands the callback its own Cron instance; `currentRun()` is the
+                // UTC time THIS invocation was scheduled for — the single-fire slot key.
+                // A duplicate delivery for the same slot resolves to one run downstream.
+                await this.onTrigger(config, { scheduledFor: self.currentRun() ?? undefined });
             }
             catch (err) {
                 console.error(`Job '${config.name}' failed:`, err.message);

package/dist/lib/self-heal/checks/hook-runtime.d.ts

@@ -0,0 +1,2 @@
+import type { HealCheck } from '../types.js';
+export declare const hookRuntimeCheck: HealCheck;

package/dist/lib/self-heal/checks/hook-runtime.js

@@ -0,0 +1,16 @@
+// hook-runtime check — detects and bounded-repairs agents-managed generated
+// hook shims (~/.agents/.cache/shims/hooks/<name>.sh). A native hook command can
+// look wired while its generated wrapper is missing, non-executable, non-file,
+// or broken — silent breakage. Repair runs at most once per unique path per
+// pass (no retry, no sync recursion); unresolved findings stay needsAttention.
+import { resultOf } from '../types.js';
+import { repairManagedHookRuntimeArtifacts } from '../../hooks.js';
+export const hookRuntimeCheck = {
+    id: 'hook-runtime',
+    title: 'Generated hook runtime shims',
+    cadence: 'frequent',
+    async run(ctx) {
+        const report = repairManagedHookRuntimeArtifacts({ dryRun: ctx.dryRun });
+        return resultOf(report.fixed, report.needsAttention);
+    },
+};