@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/rotate.d.ts

@@ -1,10 +1,18 @@
-import type { AgentId } from './types.js';
+/**
+ * Account rotation across agent versions.
+ *
+ * Detects which installed versions have expired credentials and rotates
+ * authentication tokens so users maintain active sessions across version switches.
+ */
+import type { AgentId, RunStrategy } from './types.js';
 import { type AccountInfo } from './agents.js';
+import { type UsageSnapshot } from './usage.js';
 export interface RotateCandidate {
     agent: AgentId;
     version: string;
     email: string | null;
     usageStatus: AccountInfo['usageStatus'];
+    usageSnapshot: UsageSnapshot | null;
     authValid: boolean;
     lastActive: Date | null;
 }
@@ -16,19 +24,43 @@ export interface RotateResult {
     /** Candidates excluded (not signed in, or out of credits). */
     excluded: RotateCandidate[];
 }
+export declare const RUN_STRATEGIES: RunStrategy[];
+/** Return a run strategy when the input is valid, otherwise null. */
+export declare function normalizeRunStrategy(value: unknown): RunStrategy | null;
+/** Read project-local run strategy from the nearest agents.yaml, if present. */
+export declare function getProjectRunStrategy(agent: AgentId, startPath: string): RunStrategy | null;
+/** Resolve the configured strategy: project agents.yaml, then ~/.agents-system/agents.yaml, then pinned. */
+export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: string): RunStrategy;
+/** Persist the global run strategy used by bare `agents run <agent>`. */
+export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrategy): void;
 /**
  * Pure selection: given a set of candidates, return the best one for the
  * next run. Kept separate from I/O so it can be unit-tested with fixtures.
  *
  * Eligibility: signed in (email present) and not out of credits.
- * Tie-break: least-recently-active wins. Never-used versions sort oldest
- * so fresh installs are tried before recently-used ones.
+ * Dedupe: when multiple versions share an email (same Anthropic account
+ * installed under several agent versions), collapse to one candidate per
+ * email — the least-recently-active version. Without this, two parallel
+ * pods could "rotate" to different versions but hit the same account and
+ * both 429 against the same Anthropic quota.
+ * Primary order: lowest live usage utilization wins. Least-recently-active is
+ * the tie-breaker when usage is equal or unavailable. Never-used versions sort
+ * oldest so fresh installs are tried before recently-used ones.
+ * Tie-break: random — when two candidates share a `lastActive` timestamp
+ * (common when N pods read the same snapshot), distribute across them so
+ * parallel callers fan out instead of all picking the same version.
  */
 export declare function pickRotateCandidate(candidates: RotateCandidate[]): RotateResult | null;
+/**
+ * Pick an available candidate. Prefers the configured pinned version when that
+ * version has usage available; otherwise routes to the candidate with the most
+ * usage headroom.
+ */
+export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null): RotateResult | null;
 /**
  * Rotate across installed versions of an agent and pick the best one for the
- * next run. "Best" means: signed in, not out of credits, and least-recently-
- * active (so two back-to-back runs hit different accounts automatically).
+ * next run. "Best" means: signed in, usage available, and lowest usage
+ * utilization, with least-recently-active as a tie-breaker.
  *
  * No external state: rotation and health are both read off per-version
  * AccountInfo — the same data `agents view` already surfaces. `lastActive`
@@ -39,14 +71,9 @@ export declare function pickRotateCandidate(candidates: RotateCandidate[]): Rota
  * global default so behavior stays predictable — we never refuse to run.
  */
 export declare function selectRotateVersion(agent: AgentId): Promise<RotateResult | null>;
-/**
- * Resolve the version `agents run` should use when the caller did not pin
- * one with `@version`. Rotation is the default; falls back to the global
- * default if no version is healthy, and to null if the agent isn't installed
- * under agents-cli at all (let exec surface its own error).
- */
-export declare function resolveRunVersion(agent: AgentId): Promise<{
+/** Select the configured version if available, otherwise another available version. */
+export declare function selectAvailableVersion(agent: AgentId, preferredVersion?: string | null): Promise<RotateResult | null>;
+export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy, cwd?: string): Promise<{
     version: string | null;
     rotation: RotateResult | null;
 }>;
-//# sourceMappingURL=rotate.d.ts.map

package/dist/lib/rotate.js

@@ -1,27 +1,163 @@
+/**
+ * Account rotation across agent versions.
+ *
+ * Detects which installed versions have expired credentials and rotates
+ * authentication tokens so users maintain active sessions across version switches.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
 import { getAccountInfo } from './agents.js';
-import { listInstalledVersions, getVersionHomePath, getGlobalDefault } from './versions.js';
-import { isClaudeAuthValid } from './usage.js';
+import { readMeta, writeMeta, getAgentsDir } from './state.js';
+import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
+import { getUsageInfoByIdentity, getUsageLookupKey, isClaudeAuthValid, } from './usage.js';
+export const RUN_STRATEGIES = ['pinned', 'available', 'rotate'];
+/** Return a run strategy when the input is valid, otherwise null. */
+export function normalizeRunStrategy(value) {
+    return typeof value === 'string' && RUN_STRATEGIES.includes(value)
+        ? value
+        : null;
+}
+/** Read project-local run strategy from the nearest agents.yaml, if present. */
+export function getProjectRunStrategy(agent, startPath) {
+    let dir = path.resolve(startPath);
+    const userAgentsYaml = path.join(getAgentsDir(), 'agents.yaml');
+    while (dir !== path.dirname(dir)) {
+        const manifestPath = path.join(dir, 'agents.yaml');
+        if (manifestPath !== userAgentsYaml && fs.existsSync(manifestPath)) {
+            try {
+                const parsed = yaml.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                const strategy = normalizeRunStrategy(parsed?.run?.[agent]?.strategy);
+                if (strategy)
+                    return strategy;
+            }
+            catch {
+                // Ignore malformed project config and keep walking, matching version resolution.
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    return null;
+}
+/** Resolve the configured strategy: project agents.yaml, then ~/.agents-system/agents.yaml, then pinned. */
+export function getConfiguredRunStrategy(agent, startPath = process.cwd()) {
+    return getProjectRunStrategy(agent, startPath)
+        ?? normalizeRunStrategy(readMeta().run?.[agent]?.strategy)
+        ?? 'pinned';
+}
+/** Persist the global run strategy used by bare `agents run <agent>`. */
+export function setGlobalRunStrategy(agent, strategy) {
+    const meta = readMeta();
+    if (!meta.run)
+        meta.run = {};
+    meta.run[agent] = { ...(meta.run[agent] ?? {}), strategy };
+    writeMeta(meta);
+}
+function isRotationEligible(candidate) {
+    return !!candidate.email
+        && candidate.authValid
+        && hasUsageAvailable(candidate);
+}
+function isAvailableEligible(candidate) {
+    return !!candidate.email
+        && candidate.authValid
+        && hasUsageAvailable(candidate);
+}
+function hasUsageAvailable(candidate) {
+    const usedPercent = getRoutingUsedPercent(candidate.usageSnapshot);
+    if (usedPercent !== null) {
+        return usedPercent < 100;
+    }
+    if (candidate.usageStatus === 'out_of_credits' || candidate.usageStatus === 'rate_limited') {
+        return false;
+    }
+    return true;
+}
+function getRoutingUsedPercent(snapshot) {
+    if (!snapshot || snapshot.windows.length === 0)
+        return null;
+    const routingWindows = snapshot.windows.filter((window) => window.key !== 'session');
+    const windows = routingWindows.length > 0 ? routingWindows : snapshot.windows;
+    return Math.max(...windows.map((window) => window.usedPercent));
+}
+function compareCandidates(a, b) {
+    const au = getRoutingUsedPercent(a.usageSnapshot);
+    const bu = getRoutingUsedPercent(b.usageSnapshot);
+    if (au !== null || bu !== null) {
+        if (au === null)
+            return 1;
+        if (bu === null)
+            return -1;
+        if (au !== bu)
+            return au - bu;
+    }
+    const ta = a.lastActive ? a.lastActive.getTime() : 0;
+    const tb = b.lastActive ? b.lastActive.getTime() : 0;
+    if (ta !== tb)
+        return ta - tb;
+    return Math.random() - 0.5;
+}
+function dedupeAndSortCandidates(candidates) {
+    const byEmail = new Map();
+    for (const c of candidates) {
+        const email = c.email;
+        const existing = byEmail.get(email);
+        if (!existing) {
+            byEmail.set(email, c);
+            continue;
+        }
+        if (compareCandidates(c, existing) < 0)
+            byEmail.set(email, c);
+    }
+    return [...byEmail.values()].sort(compareCandidates);
+}
 /**
  * Pure selection: given a set of candidates, return the best one for the
  * next run. Kept separate from I/O so it can be unit-tested with fixtures.
  *
  * Eligibility: signed in (email present) and not out of credits.
- * Tie-break: least-recently-active wins. Never-used versions sort oldest
- * so fresh installs are tried before recently-used ones.
+ * Dedupe: when multiple versions share an email (same Anthropic account
+ * installed under several agent versions), collapse to one candidate per
+ * email — the least-recently-active version. Without this, two parallel
+ * pods could "rotate" to different versions but hit the same account and
+ * both 429 against the same Anthropic quota.
+ * Primary order: lowest live usage utilization wins. Least-recently-active is
+ * the tie-breaker when usage is equal or unavailable. Never-used versions sort
+ * oldest so fresh installs are tried before recently-used ones.
+ * Tie-break: random — when two candidates share a `lastActive` timestamp
+ * (common when N pods read the same snapshot), distribute across them so
+ * parallel callers fan out instead of all picking the same version.
  */
 export function pickRotateCandidate(candidates) {
     const healthy = [];
     const excluded = [];
     for (const c of candidates) {
-        if (!c.email) {
+        if (!isRotationEligible(c)) {
             excluded.push(c);
             continue;
         }
-        if (c.usageStatus === 'out_of_credits') {
+        healthy.push(c);
+    }
+    if (healthy.length === 0)
+        return null;
+    const sorted = dedupeAndSortCandidates(healthy);
+    const deduped = new Set(sorted);
+    for (const c of healthy) {
+        if (!deduped.has(c))
             excluded.push(c);
-            continue;
-        }
-        if (!c.authValid) {
+    }
+    return { picked: sorted[0], healthy: sorted, excluded };
+}
+/**
+ * Pick an available candidate. Prefers the configured pinned version when that
+ * version has usage available; otherwise routes to the candidate with the most
+ * usage headroom.
+ */
+export function pickAvailableCandidate(candidates, preferredVersion) {
+    const healthy = [];
+    const excluded = [];
+    for (const c of candidates) {
+        if (!isAvailableEligible(c)) {
             excluded.push(c);
             continue;
         }
@@ -29,31 +165,20 @@ export function pickRotateCandidate(candidates) {
     }
     if (healthy.length === 0)
         return null;
-    const sorted = [...healthy].sort((a, b) => {
-        const ta = a.lastActive ? a.lastActive.getTime() : 0;
-        const tb = b.lastActive ? b.lastActive.getTime() : 0;
-        return ta - tb;
-    });
-    return { picked: sorted[0], healthy: sorted, excluded };
+    const sorted = dedupeAndSortCandidates(healthy);
+    const deduped = new Set(sorted);
+    for (const c of healthy) {
+        if (!deduped.has(c))
+            excluded.push(c);
+    }
+    const preferred = preferredVersion
+        ? sorted.find((candidate) => candidate.version === preferredVersion)
+        : undefined;
+    return { picked: preferred ?? sorted[0], healthy: sorted, excluded };
 }
-/**
- * Rotate across installed versions of an agent and pick the best one for the
- * next run. "Best" means: signed in, not out of credits, and least-recently-
- * active (so two back-to-back runs hit different accounts automatically).
- *
- * No external state: rotation and health are both read off per-version
- * AccountInfo — the same data `agents view` already surfaces. `lastActive`
- * advances naturally after each run, so the cursor is self-maintaining.
- *
- * Returns null if no installed version is eligible (either nothing installed
- * or every account is exhausted / not signed in). Callers fall back to the
- * global default so behavior stays predictable — we never refuse to run.
- */
-export async function selectRotateVersion(agent) {
+async function collectRunCandidates(agent) {
     const versions = listInstalledVersions(agent);
-    if (versions.length === 0)
-        return null;
-    const candidates = await Promise.all(versions.map(async (version) => {
+    const rows = await Promise.all(versions.map(async (version) => {
         const home = getVersionHomePath(agent, version);
         const info = await getAccountInfo(agent, home);
         const authValid = info.email
@@ -62,26 +187,99 @@ export async function selectRotateVersion(agent) {
         return {
             agent,
             version,
+            home,
+            info,
             email: info.email,
             usageStatus: info.usageStatus,
             authValid,
             lastActive: info.lastActive,
         };
     }));
-    return pickRotateCandidate(candidates);
+    const { usageByKey } = await getUsageInfoByIdentity(rows.map(({ home, info, version }) => ({
+        agentId: agent,
+        home,
+        cliVersion: version,
+        info,
+    })));
+    return rows.map(({ home: _home, info, ...candidate }) => {
+        const usageKey = getUsageLookupKey(info);
+        const usageSnapshot = usageKey
+            ? usageByKey.get(usageKey)?.snapshot ?? null
+            : null;
+        return { ...candidate, usageSnapshot };
+    });
+}
+/**
+ * Rotate across installed versions of an agent and pick the best one for the
+ * next run. "Best" means: signed in, usage available, and lowest usage
+ * utilization, with least-recently-active as a tie-breaker.
+ *
+ * No external state: rotation and health are both read off per-version
+ * AccountInfo — the same data `agents view` already surfaces. `lastActive`
+ * advances naturally after each run, so the cursor is self-maintaining.
+ *
+ * Returns null if no installed version is eligible (either nothing installed
+ * or every account is exhausted / not signed in). Callers fall back to the
+ * global default so behavior stays predictable — we never refuse to run.
+ */
+export async function selectRotateVersion(agent) {
+    return pickRotateCandidate(await collectRunCandidates(agent));
+}
+/** Select the configured version if available, otherwise another available version. */
+export async function selectAvailableVersion(agent, preferredVersion) {
+    return pickAvailableCandidate(await collectRunCandidates(agent), preferredVersion);
 }
 /**
  * Resolve the version `agents run` should use when the caller did not pin
- * one with `@version`. Rotation is the default; falls back to the global
- * default if no version is healthy, and to null if the agent isn't installed
- * under agents-cli at all (let exec surface its own error).
+ * one with `@version`. The caller supplies the effective strategy; if that
+ * strategy cannot find a usable candidate, fall back to the pinned
+ * workspace/global version.
  */
-export async function resolveRunVersion(agent) {
-    const rotation = await selectRotateVersion(agent);
+/**
+ * Record a rotation pick so parallel callers see it as recently-used.
+ * Writes a stamp file per agent — lightweight, no locking needed since
+ * a torn write just means the next reader sees a stale timestamp (harmless).
+ */
+function recordRotationPick(agent, version) {
+    const stampPath = path.join(getAgentsDir(), `rotate-stamp-${agent}.json`);
+    try {
+        fs.writeFileSync(stampPath, JSON.stringify({ version, ts: Date.now() }), 'utf-8');
+    }
+    catch { /* best effort — doesn't block the run */ }
+}
+/**
+ * Read the most recent rotation pick for an agent. Returns null if no stamp
+ * or stamp is older than 60 seconds (stale).
+ */
+function readRotationStamp(agent) {
+    const stampPath = path.join(getAgentsDir(), `rotate-stamp-${agent}.json`);
+    try {
+        const raw = JSON.parse(fs.readFileSync(stampPath, 'utf-8'));
+        if (Date.now() - raw.ts < 60_000)
+            return raw.version;
+    }
+    catch { /* missing or corrupt — treat as no stamp */ }
+    return null;
+}
+export async function resolveRunVersion(agent, strategy, cwd = process.cwd()) {
+    const fallback = resolveVersion(agent, cwd);
+    if (strategy === 'pinned') {
+        return { version: fallback, rotation: null };
+    }
+    const rotation = strategy === 'available'
+        ? await selectAvailableVersion(agent, fallback)
+        : await selectRotateVersion(agent);
     if (rotation) {
+        // If another process just picked the same version (within 60s), try the
+        // next healthy candidate to distribute load across accounts.
+        const recentPick = readRotationStamp(agent);
+        if (recentPick === rotation.picked.version && rotation.healthy.length > 1) {
+            const alt = rotation.healthy.find(c => c.version !== recentPick);
+            if (alt)
+                rotation.picked = alt;
+        }
+        recordRotationPick(agent, rotation.picked.version);
         return { version: rotation.picked.version, rotation };
     }
-    const fallback = getGlobalDefault(agent);
     return { version: fallback, rotation: null };
 }
-//# sourceMappingURL=rotate.js.map

package/dist/lib/routines.d.ts

@@ -1,9 +1,19 @@
+/**
+ * Scheduled job (routine) configuration and run history management.
+ *
+ * Routines are YAML files in ~/.agents/routines/ that define recurring or
+ * one-shot agent tasks. This module handles CRUD operations on job configs,
+ * run metadata persistence, prompt variable expansion, and one-shot "at" time
+ * scheduling.
+ */
 import type { AgentId } from './types.js';
+/** Tool/site/directory allow-list for sandboxed job execution. */
 export interface JobAllowConfig {
     tools?: string[];
     sites?: string[];
     dirs?: string[];
 }
+/** Full configuration for a scheduled routine (persisted as YAML). */
 export interface JobConfig {
     name: string;
     schedule: string;
@@ -21,6 +31,7 @@ export interface JobConfig {
     version?: string;
     runOnce?: boolean;
 }
+/** Metadata for a single job execution, persisted as JSON in the run directory. */
 export interface RunMeta {
     jobName: string;
     runId: string;
@@ -31,24 +42,40 @@ export interface RunMeta {
     completedAt: string | null;
     exitCode: number | null;
 }
+/** List all job configs from ~/.agents/routines/. */
 export declare function listJobs(): JobConfig[];
+/** Read a single job config by name. Returns null if not found. */
 export declare function readJob(name: string): JobConfig | null;
+/** Write a job config to disk, omitting fields that match defaults. */
 export declare function writeJob(config: JobConfig): void;
+/** Delete a job config file by name. Returns true if the file existed. */
 export declare function deleteJob(name: string): boolean;
+/** Enable or disable a job by name. */
 export declare function setJobEnabled(name: string, enabled: boolean): void;
+/** Validate a partial job config, returning a list of human-readable errors. */
 export declare function validateJob(config: Partial<JobConfig>): string[];
+/** Expand built-in and user-defined template variables in a job's prompt string. */
 export declare function resolveJobPrompt(config: JobConfig): string;
+/** Parse a human-readable timeout string (e.g. "30m", "2h", "1h30m") into milliseconds. */
 export declare function parseTimeout(timeout: string): number | null;
+/** List all run metadata entries for a job, sorted chronologically. */
 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;
+/** 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. */
 export declare function readRunMeta(jobName: string, runId: string): RunMeta | null;
+/** 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. */
 export declare function discoverJobsFromRepo(repoPath: string): Array<{
     name: string;
     path: string;
 }>;
+/** Check whether a job with the given name exists on disk. */
 export declare function jobExists(name: string): boolean;
+/** Get the filesystem path of a job's YAML config file, or null if not found. */
 export declare function getJobPath(name: string): string | null;
 /**
  * Parse an "at" time string into a one-shot cron expression.
@@ -62,9 +89,10 @@ export declare function parseAtTime(atTime: string): {
     schedule: string;
     runOnce: boolean;
 } | null;
+/** Check if an installed job's normalized YAML matches the source file. */
 export declare function jobContentMatches(name: string, sourcePath: string): boolean;
+/** Install a job by reading and validating a YAML source file. */
 export declare function installJobFromSource(sourcePath: string, name: string): {
     success: boolean;
     error?: string;
 };
-//# sourceMappingURL=routines.d.ts.map

package/dist/lib/routines.js

@@ -1,15 +1,26 @@
+/**
+ * Scheduled job (routine) configuration and run history management.
+ *
+ * Routines are YAML files in ~/.agents/routines/ that define recurring or
+ * one-shot agent tasks. This module handles CRUD operations on job configs,
+ * run metadata persistence, prompt variable expansion, and one-shot "at" time
+ * scheduling.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { Cron } from 'croner';
 import { getRoutinesDir, getRunsDir, ensureAgentsDir } from './state.js';
+import { safeJoin } from './paths.js';
 import { ALL_AGENT_IDS } from './agents.js';
+/** Default values applied to every job config when fields are omitted. */
 const JOB_DEFAULTS = {
     mode: 'plan',
     effort: 'auto',
     timeout: '30m',
     enabled: true,
 };
+/** List all job configs from ~/.agents/routines/. */
 export function listJobs() {
     ensureAgentsDir();
     const jobsDir = getRoutinesDir();
@@ -24,11 +35,12 @@ export function listJobs() {
     }
     return jobs;
 }
+/** Read a single job config by name. Returns null if not found. */
 export function readJob(name) {
     ensureAgentsDir();
     const jobsDir = getRoutinesDir();
     for (const ext of ['.yml', '.yaml']) {
-        const filePath = path.join(jobsDir, name + ext);
+        const filePath = safeJoin(jobsDir, name + ext);
         if (fs.existsSync(filePath)) {
             return readJobFile(filePath);
         }
@@ -51,10 +63,11 @@ function readJobFile(filePath) {
         return null;
     }
 }
+/** Write a job config to disk, omitting fields that match defaults. */
 export function writeJob(config) {
     ensureAgentsDir();
     const jobsDir = getRoutinesDir();
-    const filePath = path.join(jobsDir, config.name + '.yml');
+    const filePath = safeJoin(jobsDir, config.name + '.yml');
     const output = { ...config };
     if (output.mode === 'plan')
         delete output.mode;
@@ -68,10 +81,11 @@ export function writeJob(config) {
         delete output.runOnce;
     fs.writeFileSync(filePath, yaml.stringify(output), 'utf-8');
 }
+/** Delete a job config file by name. Returns true if the file existed. */
 export function deleteJob(name) {
     const jobsDir = getRoutinesDir();
     for (const ext of ['.yml', '.yaml']) {
-        const filePath = path.join(jobsDir, name + ext);
+        const filePath = safeJoin(jobsDir, name + ext);
         if (fs.existsSync(filePath)) {
             fs.unlinkSync(filePath);
             return true;
@@ -79,6 +93,7 @@ export function deleteJob(name) {
     }
     return false;
 }
+/** Enable or disable a job by name. */
 export function setJobEnabled(name, enabled) {
     const job = readJob(name);
     if (!job)
@@ -86,6 +101,7 @@ export function setJobEnabled(name, enabled) {
     job.enabled = enabled;
     writeJob(job);
 }
+/** Validate a partial job config, returning a list of human-readable errors. */
 export function validateJob(config) {
     const errors = [];
     if (!config.name || typeof config.name !== 'string') {
@@ -123,6 +139,7 @@ export function validateJob(config) {
     }
     return errors;
 }
+/** Expand built-in and user-defined template variables in a job's prompt string. */
 export function resolveJobPrompt(config) {
     const now = new Date();
     const tz = config.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -162,6 +179,7 @@ export function resolveJobPrompt(config) {
     }
     return prompt;
 }
+/** Parse a human-readable timeout string (e.g. "30m", "2h", "1h30m") into milliseconds. */
 export function parseTimeout(timeout) {
     const match = timeout.match(/^(?:(\d+)h)?(?:(\d+)m)?$/);
     if (!match)
@@ -171,6 +189,7 @@ export function parseTimeout(timeout) {
     const ms = (hours * 60 + minutes) * 60 * 1000;
     return ms > 0 ? ms : null;
 }
+/** List all run metadata entries for a job, sorted chronologically. */
 export function listRuns(jobName) {
     const runsDir = getRunsDir();
     const jobRunsDir = path.join(runsDir, jobName);
@@ -188,16 +207,19 @@ export function listRuns(jobName) {
     }
     return runs;
 }
+/** Get the most recent run for a job, or null if never run. */
 export function getLatestRun(jobName) {
     const runs = listRuns(jobName);
     return runs.length > 0 ? runs[runs.length - 1] : null;
 }
+/** Persist run metadata to its run directory as meta.json. */
 export function writeRunMeta(meta) {
     ensureAgentsDir();
     const runDir = path.join(getRunsDir(), meta.jobName, meta.runId);
     fs.mkdirSync(runDir, { recursive: true });
     fs.writeFileSync(path.join(runDir, 'meta.json'), JSON.stringify(meta, null, 2), 'utf-8');
 }
+/** Read run metadata from disk. Returns null if missing or corrupt. */
 export function readRunMeta(jobName, runId) {
     const metaPath = path.join(getRunsDir(), jobName, runId, 'meta.json');
     if (!fs.existsSync(metaPath))
@@ -209,9 +231,11 @@ export function readRunMeta(jobName, runId) {
         return null;
     }
 }
+/** Get the filesystem path for a specific run's directory. */
 export function getRunDir(jobName, runId) {
     return path.join(getRunsDir(), jobName, runId);
 }
+/** Discover routine YAML files in a repository's routines/ directory. */
 export function discoverJobsFromRepo(repoPath) {
     const jobsPath = path.join(repoPath, 'routines');
     if (!fs.existsSync(jobsPath))
@@ -223,13 +247,15 @@ export function discoverJobsFromRepo(repoPath) {
         path: path.join(jobsPath, f),
     }));
 }
+/** Check whether a job with the given name exists on disk. */
 export function jobExists(name) {
     return readJob(name) !== null;
 }
+/** Get the filesystem path of a job's YAML config file, or null if not found. */
 export function getJobPath(name) {
     const jobsDir = getRoutinesDir();
     for (const ext of ['.yml', '.yaml']) {
-        const filePath = path.join(jobsDir, name + ext);
+        const filePath = safeJoin(jobsDir, name + ext);
         if (fs.existsSync(filePath)) {
             return filePath;
         }
@@ -282,6 +308,7 @@ export function parseAtTime(atTime) {
     }
     return null;
 }
+/** Check if an installed job's normalized YAML matches the source file. */
 export function jobContentMatches(name, sourcePath) {
     const existing = readJob(name);
     if (!existing)
@@ -300,6 +327,7 @@ export function jobContentMatches(name, sourcePath) {
         return false;
     }
 }
+/** Install a job by reading and validating a YAML source file. */
 export function installJobFromSource(sourcePath, name) {
     try {
         const content = fs.readFileSync(sourcePath, 'utf-8');
@@ -322,4 +350,3 @@ export function installJobFromSource(sourcePath, name) {
         return { success: false, error: err.message };
     }
 }
-//# sourceMappingURL=routines.js.map