@phnx-labs/agents-cli 1.12.0 → 1.14.1

package/dist/lib/rotate.js

@@ -0,0 +1,285 @@
+/**
+ * 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 { 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.
+ * 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 (!isRotationEligible(c)) {
+            excluded.push(c);
+            continue;
+        }
+        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);
+    }
+    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;
+        }
+        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);
+    }
+    const preferred = preferredVersion
+        ? sorted.find((candidate) => candidate.version === preferredVersion)
+        : undefined;
+    return { picked: preferred ?? sorted[0], healthy: sorted, excluded };
+}
+async function collectRunCandidates(agent) {
+    const versions = listInstalledVersions(agent);
+    const rows = await Promise.all(versions.map(async (version) => {
+        const home = getVersionHomePath(agent, version);
+        const info = await getAccountInfo(agent, home);
+        const authValid = info.email
+            ? agent === 'claude' ? await isClaudeAuthValid(home) : true
+            : false;
+        return {
+            agent,
+            version,
+            home,
+            info,
+            email: info.email,
+            usageStatus: info.usageStatus,
+            authValid,
+            lastActive: info.lastActive,
+        };
+    }));
+    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`. The caller supplies the effective strategy; if that
+ * strategy cannot find a usable candidate, fall back to the pinned
+ * workspace/global version.
+ */
+/**
+ * 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 };
+    }
+    return { version: fallback, rotation: null };
+}

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

package/dist/lib/runner.d.ts

@@ -1,12 +1,25 @@
+/**
+ * Job execution engine for routines.
+ *
+ * Builds agent-specific CLI commands from job configs, spawns them with
+ * sandboxed or unsandboxed environments, captures stdout to log files,
+ * enforces timeouts, and extracts the final assistant report from the
+ * agent's stream-JSON output.
+ */
 import type { JobConfig, RunMeta } from './routines.js';
 import type { AgentId } from './types.js';
+/** Result of a completed job execution, including metadata and optional report. */
 export interface RunResult {
     meta: RunMeta;
     reportPath: string | null;
 }
+/** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export declare function buildJobCommand(config: JobConfig, resolvedPrompt: string): string[];
+/** Execute a job synchronously (waits for completion or timeout before resolving). */
 export declare function executeJob(config: JobConfig): Promise<RunResult>;
+/** Spawn a job as a detached process and return immediately with run metadata. */
 export declare function executeJobDetached(config: JobConfig): 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;
+/** Scan all runs marked "running" and finalize any whose process has exited. */
 export declare function monitorRunningJobs(): void;
-//# sourceMappingURL=runner.d.ts.map

package/dist/lib/runner.js

@@ -1,3 +1,11 @@
+/**
+ * Job execution engine for routines.
+ *
+ * Builds agent-specific CLI commands from job configs, spawns them with
+ * sandboxed or unsandboxed environments, captures stdout to log files,
+ * enforces timeouts, and extracts the final assistant report from the
+ * agent's stream-JSON output.
+ */
 import { spawn } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -6,11 +14,13 @@ import { resolveJobPrompt, parseTimeout, writeRunMeta, getRunDir, } from './rout
 import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
+/** CLI command templates per agent, with {prompt} as a placeholder. */
 const AGENT_COMMANDS = {
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
     codex: ['codex', 'exec', '--sandbox', 'workspace-write', '{prompt}', '--json'],
     gemini: ['gemini', '{prompt}', '--output-format', 'stream-json'],
 };
+/** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export function buildJobCommand(config, resolvedPrompt) {
     const template = AGENT_COMMANDS[config.agent];
     if (!template) {
@@ -31,6 +41,12 @@ export function buildJobCommand(config, resolvedPrompt) {
         }
         if (config.allow?.dirs) {
             for (const dir of config.allow.dirs) {
+                // Reject leading '-' so a routine YAML can't smuggle an argv flag like
+                // `--dangerously-skip-permissions` past the sandbox by hiding it as an
+                // allow.dirs entry.
+                if (dir.startsWith('-')) {
+                    throw new Error(`allow.dirs entries must not start with '-': ${JSON.stringify(dir)}`);
+                }
                 const resolved = dir.replace(/^~/, os.homedir());
                 cmd.push('--add-dir', resolved);
             }
@@ -89,6 +105,7 @@ function appendModelAndReasoning(cmd, config) {
 function generateRunId() {
     return new Date().toISOString().replace(/[:.]/g, '-');
 }
+/** Execute a job synchronously (waits for completion or timeout before resolving). */
 export async function executeJob(config) {
     const resolvedPrompt = resolveJobPrompt(config);
     const cmd = buildJobCommand(config, resolvedPrompt);
@@ -98,7 +115,7 @@ export async function executeJob(config) {
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
     const stdoutPath = path.join(runDir, 'stdout.log');
-    const stdoutFd = fs.openSync(stdoutPath, 'w');
+    const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
     let spawnEnv = useSandbox ? buildSpawnEnv(overlayHome) : { ...process.env };
     if (config.timezone) {
         spawnEnv.TZ = config.timezone;
@@ -179,6 +196,7 @@ export async function executeJob(config) {
         child.unref();
     });
 }
+/** Spawn a job as a detached process and return immediately with run metadata. */
 export async function executeJobDetached(config) {
     const resolvedPrompt = resolveJobPrompt(config);
     const cmd = buildJobCommand(config, resolvedPrompt);
@@ -188,7 +206,7 @@ export async function executeJobDetached(config) {
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
     const stdoutPath = path.join(runDir, 'stdout.log');
-    const stdoutFd = fs.openSync(stdoutPath, 'w');
+    const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
     let spawnEnv = useSandbox ? buildSpawnEnv(overlayHome) : { ...process.env };
     if (config.timezone) {
         spawnEnv.TZ = config.timezone;
@@ -233,6 +251,7 @@ function extractAndSaveReport(stdoutPath, agentType, runDir) {
     }
     return null;
 }
+/** Extract the final assistant message from a stream-JSON log file as a markdown report. */
 export function extractReport(stdoutPath, agentType) {
     if (!fs.existsSync(stdoutPath))
         return null;
@@ -273,6 +292,7 @@ export function extractReport(stdoutPath, agentType) {
         return null;
     }
 }
+/** Scan all runs marked "running" and finalize any whose process has exited. */
 export function monitorRunningJobs() {
     const runsDir = getRunsDir();
     if (!fs.existsSync(runsDir))
@@ -308,4 +328,3 @@ export function monitorRunningJobs() {
         }
     }
 }
-//# sourceMappingURL=runner.js.map

package/dist/lib/sandbox.d.ts

@@ -1,10 +1,25 @@
+/**
+ * Sandbox environment for routine job execution.
+ *
+ * Creates an overlay HOME directory per job with symlinked allowed
+ * directories and agent-specific config files (permissions, settings).
+ * The spawned agent process sees only the overlay, limiting filesystem
+ * access to explicitly allowed paths.
+ */
 import type { JobConfig } from './routines.js';
+/** Build a restricted environment for a sandboxed process, setting HOME to the overlay. */
 export declare function buildSpawnEnv(overlayHome: string, extraEnv?: Record<string, string>): Record<string, string>;
+/** Get the overlay HOME directory path for a named job. */
 export declare function getJobHomePath(name: string): string;
+/** Create a fresh overlay HOME for a job, including agent config and allowed-dir symlinks. */
 export declare function prepareJobHome(config: JobConfig): string;
+/** Remove a job's overlay HOME directory entirely. */
 export declare function cleanJobHome(name: string): void;
+/** Symlink allowed directories into the overlay HOME, skipping paths outside the real HOME. */
 export declare function symlinkAllowedDirs(overlayHome: string, dirs: string[]): void;
+/** Generate a Claude settings.json in the overlay with scoped permissions from the job config. */
 export declare function generateClaudeConfig(overlayHome: string, config: JobConfig): void;
+/** Generate a Codex config.toml in the overlay with model and approval-mode settings. */
 export declare function generateCodexConfig(overlayHome: string, config: JobConfig): void;
+/** Generate a Gemini settings.json in the overlay from the job's config block. */
 export declare function generateGeminiConfig(overlayHome: string, config: JobConfig): void;
-//# sourceMappingURL=sandbox.d.ts.map