@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/lib/daemon.js

@@ -11,7 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { getDaemonDir as getDaemonDirRoot } from './state.js';
-import { isAlive, killTree } from './platform/index.js';
+import { isAlive, killTree, backgroundSpawnOptions } from './platform/index.js';
 import { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
@@ -127,6 +127,86 @@ export function isDaemonRunning() {
     removeDaemonPid();
     return false;
 }
+/**
+ * Single-instance claim for the daemon `_run` entrypoint.
+ *
+ * `agents daemon _run` is reachable directly — a manual invocation, or a
+ * service-manager restart that races a still-alive predecessor — bypassing the
+ * start lock in startDaemon(). Without this guard runDaemon() would call
+ * writeDaemonPid() unconditionally, clobber a live daemon's recorded PID, and
+ * run a second JobScheduler concurrently, so every cron routine fires twice.
+ *
+ * Returns true and records our PID when no other live daemon owns the pid file;
+ * returns false when a live daemon already holds it (the caller must exit
+ * without touching any further state). The read-decide-write is serialized
+ * behind the same O_EXCL start lock startDaemon() uses, so two _run processes
+ * can't both claim in the window between the liveness check and the write.
+ */
+export function claimDaemonInstance() {
+    const release = acquireStartLock();
+    try {
+        const existing = readDaemonPid();
+        if (existing !== null && existing !== process.pid && isAlive(existing)) {
+            return false; // another live daemon already owns the pid file
+        }
+        writeDaemonPid(process.pid);
+        return true;
+    }
+    finally {
+        release?.();
+    }
+}
+/**
+ * Reap stray duplicate daemon processes — a `daemon _run` of THIS install that
+ * isn't this process and isn't the pid-file owner. Mirrors the browser orphan
+ * reaper (below): a predecessor that was SIGKILLed/OOM-ed without cleaning up,
+ * or a duplicate that lost the pid-file write race, would otherwise keep a
+ * second scheduler alive and double-fire jobs even after claimDaemonInstance()
+ * hands the pid file to the survivor.
+ *
+ * Scoped to our own launch entry (process.argv[1]) so it only ever targets
+ * daemons of the same installation — a daemon from a different install / home
+ * (e.g. a side-by-side dev build, or a test fixture) is a legitimately separate
+ * instance and is left untouched. POSIX-only (uses `ps`); a no-op on Windows.
+ */
+export function reapStrayDaemons(keepPid = process.pid) {
+    const details = [];
+    let reaped = 0;
+    if (process.platform === 'win32')
+        return { reaped, details };
+    const selfEntry = process.argv[1];
+    if (!selfEntry)
+        return { reaped, details };
+    let out;
+    try {
+        out = execFileSync('ps', ['-eo', 'pid=,args='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    }
+    catch {
+        return { reaped, details }; // no `ps` — best effort
+    }
+    const ownerPid = readDaemonPid();
+    for (const line of out.split('\n')) {
+        const m = line.trim().match(/^(\d+)\s+(.*)$/);
+        if (!m)
+            continue;
+        const pid = parseInt(m[1], 10);
+        const args = m[2];
+        if (isNaN(pid) || pid === keepPid || pid === process.pid || pid === ownerPid)
+            continue;
+        // Same install (same launch entry) AND a `daemon _run` command line.
+        if (!args.includes(selfEntry))
+            continue;
+        if (!/\bdaemon\b.*\b_run\b/.test(args))
+            continue;
+        try {
+            process.kill(pid, 'SIGTERM');
+            reaped++;
+            details.push(`reaped stray daemon pid ${pid}`);
+        }
+        catch { /* already gone */ }
+    }
+    return { reaped, details };
+}
 /** Redact values that look like tokens or credentials in a log message. */
 function redactSecrets(message) {
     let safe = message;
@@ -165,8 +245,30 @@ export function log(level, message) {
 }
 /** Main daemon loop: load jobs, schedule crons, monitor runs, and handle signals. */
 export async function runDaemon() {
-    writeDaemonPid(process.pid);
+    // Single-instance guard: a direct `agents daemon _run` (manual, or a
+    // service-manager restart racing a live predecessor) must not clobber a
+    // running daemon's pid file and start a second scheduler.
+    if (!claimDaemonInstance()) {
+        const owner = readDaemonPid();
+        log('WARN', `Another daemon already owns the pid file (PID: ${owner}); this instance (PID ${process.pid}) is exiting`);
+        // Exit cleanly (0) so a service manager treats it as an orderly no-op
+        // rather than a failure to restart-flap on.
+        process.exit(0);
+    }
     log('INFO', `Daemon started (PID: ${process.pid})`);
+    // Reap any stray duplicate daemon of this install that slipped past the start
+    // lock or was orphaned by a hard-crash — before it can double-fire jobs.
+    try {
+        const strays = reapStrayDaemons();
+        if (strays.reaped > 0) {
+            log('WARN', `Reaped ${strays.reaped} stray daemon process(es)`);
+            for (const d of strays.details)
+                log('WARN', `  ${d}`);
+        }
+    }
+    catch (err) {
+        log('ERROR', `Stray daemon reaper failed: ${err.message}`);
+    }
     const scheduler = new JobScheduler(async (config) => {
         log('INFO', `Triggering job '${config.name}' (agent: ${config.agent})`);
         try {
@@ -373,6 +475,23 @@ function xmlEscape(s) {
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;');
 }
+/**
+ * Write a launchd plist or systemd unit with owner-only permissions atomically.
+ *
+ * `writeFileSync`'s `mode` is honored only when the file is *created*, so we
+ * unlink any pre-existing manifest first. That guarantees every write is a
+ * fresh 0600 create — closing the TOCTOU window on new files AND re-locking a
+ * stale world-readable manifest left by an older install — since these files
+ * embed long-lived credentials.
+ */
+export function writeOwnerOnlyServiceManifest(filePath, content) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.rmSync(filePath, { force: true });
+    fs.writeFileSync(filePath, content, { encoding: 'utf-8', mode: 0o600 });
+}
 /** Generate a macOS launchd plist for auto-starting the daemon. */
 export function generateLaunchdPlist() {
     const agentsBin = getAgentsBinPath();
@@ -448,6 +567,31 @@ function getAgentsBinPath() {
         return 'agents';
     }
 }
+/**
+ * Ask the service manager for the daemon's live PID. Used as a fallback when
+ * the daemon hasn't yet written its pid file but launchd/systemd already report
+ * it running — so a start never has to surface a null PID for a daemon that is
+ * in fact up. Returns null when the service isn't running or the query fails.
+ */
+function readServiceManagerPid(platform = os.platform()) {
+    try {
+        if (platform === 'linux') {
+            const out = execFileSync('systemctl', ['--user', 'show', '-p', 'MainPID', '--value', SYSTEMD_UNIT], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+            const pid = parseInt(out, 10);
+            return !isNaN(pid) && pid > 0 ? pid : null;
+        }
+        if (platform === 'darwin') {
+            const out = execFileSync('launchctl', ['list', PLIST_NAME], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+            const m = out.match(/"PID"\s*=\s*(\d+)/);
+            if (m) {
+                const pid = parseInt(m[1], 10);
+                return pid > 0 ? pid : null;
+            }
+        }
+    }
+    catch { /* not running / manager unavailable */ }
+    return null;
+}
 /** Start the daemon via launchd, systemd, or as a detached process. */
 export function startDaemon() {
     if (isDaemonRunning()) {
@@ -467,6 +611,24 @@ export function startDaemon() {
         releaseLock();
     }
 }
+/**
+ * Bring the always-on daemon up as a side effect of a background-adjacent
+ * command (secrets unlock, browser start, ...), not only from `routines add`.
+ *
+ * Delegates to the single `startDaemon` entrypoint, so it honors the
+ * single-instance start lock and is a no-op when a daemon is already running
+ * (returns `already-running`). Best-effort: any failure is swallowed and null
+ * returned, so ensuring the daemon can never break the foreground command that
+ * happened to bring it up. See issue #415.
+ */
+export function ensureDaemonStarted() {
+    try {
+        return startDaemon();
+    }
+    catch {
+        return null;
+    }
+}
 function startDaemonLocked() {
     const platform = os.platform();
     if (platform === 'darwin') {
@@ -476,10 +638,9 @@ function startDaemonLocked() {
             if (!fs.existsSync(plistDir)) {
                 fs.mkdirSync(plistDir, { recursive: true });
             }
-            fs.writeFileSync(plistPath, generateLaunchdPlist(), 'utf-8');
             // The plist may embed a long-lived OAuth token in EnvironmentVariables;
-            // keep it owner-only so it isn't world/group readable on disk.
-            fs.chmodSync(plistPath, 0o600);
+            // create owner-only atomically (no world-readable window before chmod).
+            writeOwnerOnlyServiceManifest(plistPath, generateLaunchdPlist());
             try {
                 execFileSync('launchctl', ['unload', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
             }
@@ -489,7 +650,7 @@ function startDaemonLocked() {
             // of success. If no pid materializes within the window, give up on
             // launchd and fall through to a plain detached spawn.
             execFileSync('launchctl', ['load', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
-            const pid = waitForPid(3000);
+            const pid = waitForPid(3000) ?? readServiceManagerPid();
             if (pid)
                 return { pid, method: 'launchd' };
             // launchctl claimed success but nothing ran. Fall through.
@@ -506,18 +667,21 @@ function startDaemonLocked() {
             if (!fs.existsSync(unitDir)) {
                 fs.mkdirSync(unitDir, { recursive: true });
             }
-            fs.writeFileSync(unitPath, generateSystemdUnit(), 'utf-8');
             // May embed a long-lived OAuth token in an Environment= line; owner-only.
-            fs.chmodSync(unitPath, 0o600);
+            writeOwnerOnlyServiceManifest(unitPath, generateSystemdUnit());
             execFileSync('systemctl', ['--user', 'daemon-reload'], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'enable', SYSTEMD_UNIT], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'start', SYSTEMD_UNIT], { encoding: 'utf-8' });
-            const pid = waitForPid(3000);
-            return { pid, method: 'systemd' };
+            const pid = waitForPid(3000) ?? readServiceManagerPid();
+            if (pid)
+                return { pid, method: 'systemd' };
+            // systemctl returned success but no PID surfaced — fall through to a
+            // plain detached spawn rather than reporting a null PID.
         }
         catch {
-            return startDetached();
+            // start threw — fall through to detached spawn
         }
+        return startDetached();
     }
     return startDetached();
 }
@@ -567,17 +731,29 @@ export function startDetached(opts = {}) {
     const logPath = opts.logPath ?? getLogPath();
     const logFd = fs.openSync(logPath, 'a');
     const { command, args } = getDaemonLaunch(agentsBin);
+    // fdStdio: the log-file fds make windowsHide inert (libuv skips
+    // CREATE_NO_WINDOW when a stdio fd is inherited), so on Windows the daemon
+    // must DETACH to own no console — otherwise it shares the launcher's console
+    // and a console-close event tears it down when the launcher exits (#556).
     const child = spawn(command, args, {
         stdio: ['ignore', logFd, logFd],
-        detached: true,
-        // No console window on Windows — a hidden, consoleless process can't be
-        // torn down by a console-close event when its launcher exits (#556).
-        windowsHide: true,
+        ...backgroundSpawnOptions({ fdStdio: true }),
         env: opts.env ?? buildDetachedDaemonEnv(),
     });
+    // A failed spawn (ENOENT/EACCES) emits 'error' asynchronously; without a
+    // listener that would crash the parent as an unhandled EventEmitter error.
+    // The synchronous `!child.pid` guard below is what reports the failure loudly.
+    child.on('error', () => { });
     child.unref();
     fs.closeSync(logFd);
-    return { pid: child.pid || null, method: 'detached' };
+    // `spawn` leaves `pid` undefined only when the process could not be created.
+    // Returning null here (the old `child.pid || null`) let callers report
+    // "PID: null" as if the daemon had started — a start with no PID is a failed
+    // start, so fail loudly instead of manufacturing a phantom success.
+    if (!child.pid) {
+        throw new Error(`Failed to start daemon: spawning '${command}' produced no PID (binary missing or not executable?)`);
+    }
+    return { pid: child.pid, method: 'detached' };
 }
 function waitForPid(timeoutMs) {
     const start = Date.now();

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

@@ -58,6 +58,13 @@ export declare function shellForPlatform(platform: DevicePlatform): DeviceShell;
  * returning {} would let the next write wipe the user's device list.
  */
 export declare function loadDevices(): Promise<DeviceRegistry>;
+/**
+ * Synchronous {@link loadDevices} for callers already on a sync path (e.g. the
+ * `agents sessions --host` fan-out builds its ssh command strings synchronously
+ * and only needs the target's platform to pick POSIX vs PowerShell). Same
+ * missing-file/corruption contract as {@link loadDevices}.
+ */
+export declare function loadDevicesSync(): DeviceRegistry;
 /** Get a single device profile, or null if it is not registered. */
 export declare function getDevice(name: string): Promise<DeviceProfile | null>;
 /** Fields a caller may supply when creating or updating a device. */

package/dist/lib/devices/registry.js

@@ -117,6 +117,30 @@ export async function loadDevices() {
         throw new Error(`Device registry corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
     }
 }
+/**
+ * Synchronous {@link loadDevices} for callers already on a sync path (e.g. the
+ * `agents sessions --host` fan-out builds its ssh command strings synchronously
+ * and only needs the target's platform to pick POSIX vs PowerShell). Same
+ * missing-file/corruption contract as {@link loadDevices}.
+ */
+export function loadDevicesSync() {
+    const p = registryPath();
+    let raw;
+    try {
+        raw = fsSync.readFileSync(p, 'utf-8');
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT')
+            return {};
+        throw err;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Device registry corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
+    }
+}
 async function saveDevices(reg) {
     await atomicWriteJson(registryPath(), reg);
 }

package/dist/lib/devices/tailscale.js

@@ -115,7 +115,7 @@ export function nodeToDeviceInput(node) {
  * error when the binary is missing or the daemon is not reachable.
  */
 export function tailscaleStatusJson() {
-    const res = spawnSync('tailscale', ['status', '--json'], { encoding: 'utf-8' });
+    const res = spawnSync('tailscale', ['status', '--json'], { encoding: 'utf-8', windowsHide: true });
     if (res.error && res.error.code === 'ENOENT') {
         throw new Error('tailscale not found on PATH. Install Tailscale, or add devices manually with `agents devices add`.');
     }

package/dist/lib/drift.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared drift-detection internals for `agents doctor` (overview mode) and
+ * `agents check` (the scriptable, CI-friendly gate).
+ *
+ * This is the single source of truth for "is the install out of sync?": the
+ * per-version sync status (fresh / stale / never-synced) and the orphan census.
+ * `agents doctor` renders it as a human report; `agents check` reduces it to an
+ * exit code. Neither reimplements the diagnostic — both call `computeDrift`.
+ */
+import type { AgentId } from './types.js';
+import { type VersionResourceReport } from './doctor-diff.js';
+export interface SyncStatusRow {
+    agent: AgentId;
+    version: string;
+    status: 'fresh' | 'stale' | 'never-synced';
+    isDefault: boolean;
+    /** For stale rows: prioritized lines naming exactly what diverged (plugins first). */
+    divergence?: string[];
+}
+export interface OrphanRow {
+    agent: AgentId;
+    version: string;
+    commands: number;
+    skills: number;
+    hooks: number;
+}
+export declare function divergenceLines(report: VersionResourceReport): string[];
+export declare function checkSyncStatus(cwd: string): SyncStatusRow[];
+export declare function countOrphans(): OrphanRow[];
+export interface DriftSummary {
+    syncRows: SyncStatusRow[];
+    orphanRows: OrphanRow[];
+    /** Versions whose sources changed since last sync. */
+    staleCount: number;
+    /** Versions installed but never synced. */
+    neverSyncedCount: number;
+    /** Versions carrying orphan resources (informational — not a drift signal). */
+    orphanVersionCount: number;
+    /**
+     * True when any installed version is stale or never-synced — the exact signal
+     * `agents doctor` surfaces as "run `agents status` to review what has drifted".
+     * Orphans are a `prune` concern, not sync drift, so they do NOT set this flag
+     * (mirrors the sync-status engine: an orphan alone never flags needsSync).
+     */
+    hasDrift: boolean;
+}
+/**
+ * Compute the same drift/divergence diagnostic `agents doctor` prints, reduced
+ * to a summary with a single `hasDrift` boolean. The gate `agents check` maps
+ * to an exit code; the readout `agents doctor` renders in full.
+ */
+export declare function computeDrift(cwd: string): DriftSummary;

package/dist/lib/drift.js

@@ -0,0 +1,112 @@
+import { ALL_AGENT_IDS } from './agents.js';
+import { getGlobalDefault, listInstalledVersions } from './versions.js';
+import { loadManifest, isStale } from './staleness/index.js';
+import { diffVersionResources } from './doctor-diff.js';
+import { diffVersionCommands, iterCommandsCapableVersions } from './commands.js';
+import { diffVersionSkills, iterSkillsCapableVersions } from './skills.js';
+import { iterHooksCapableVersions, listUnmanagedHooksInVersionHome } from './hooks.js';
+// Lines naming exactly what's out of sync for a version, plugins prioritized:
+// each divergent plugin gets its own line with specifics (stale mirror version,
+// invalid manifest, or the bundled skills/commands missing from the mirror —
+// the system-repo plugin content that matters most). Other kinds collapse to
+// compact counts so the readout stays scannable.
+export function divergenceLines(report) {
+    const lines = [];
+    for (const p of report.kinds.plugins) {
+        if (p.status === 'missing')
+            lines.push(`plugin ${p.name} — not installed`);
+        else if (p.status === 'diff')
+            lines.push(`plugin ${p.name} — ${p.detail ?? 'mirror drifted'}`);
+    }
+    for (const kind of ['commands', 'skills', 'hooks', 'rules', 'mcp', 'permissions', 'subagents']) {
+        const rows = report.kinds[kind];
+        const miss = rows.filter((r) => r.status === 'missing').length;
+        const dif = rows.filter((r) => r.status === 'diff').length;
+        const bits = [];
+        if (miss)
+            bits.push(`${miss} missing`);
+        if (dif)
+            bits.push(`${dif} drifted`);
+        if (bits.length)
+            lines.push(`${kind.padEnd(11)} ${bits.join(' · ')}`);
+    }
+    return lines;
+}
+export function checkSyncStatus(cwd) {
+    const rows = [];
+    // Every installed version, not just the default — a stale NON-default version
+    // (e.g. one you launched from yesterday) is exactly the rot that silently
+    // serves outdated/invalid resources and that `--fix` now heals. Hiding it here
+    // is why that class of bug went unnoticed.
+    for (const agent of ALL_AGENT_IDS) {
+        const def = getGlobalDefault(agent);
+        for (const version of listInstalledVersions(agent)) {
+            const manifest = loadManifest(agent, version);
+            const status = !manifest
+                ? 'never-synced'
+                : isStale(manifest, agent, version, cwd) ? 'stale' : 'fresh';
+            const row = { agent, version, status, isDefault: version === def };
+            if (status === 'stale') {
+                // Resolve the specifics against non-project layers (the global home is
+                // never reconciled against per-cwd project resources).
+                const report = diffVersionResources(agent, version, { cwd, excludeProject: true });
+                const lines = divergenceLines(report);
+                if (lines.length)
+                    row.divergence = lines;
+            }
+            rows.push(row);
+        }
+    }
+    return rows;
+}
+export function countOrphans() {
+    const byKey = new Map();
+    const ensure = (agent, version) => {
+        const key = `${agent}@${version}`;
+        let row = byKey.get(key);
+        if (!row) {
+            row = { agent, version, commands: 0, skills: 0, hooks: 0 };
+            byKey.set(key, row);
+        }
+        return row;
+    };
+    for (const { agent, version } of iterCommandsCapableVersions()) {
+        const diff = diffVersionCommands(agent, version);
+        if (diff.orphans.length > 0)
+            ensure(agent, version).commands = diff.orphans.length;
+    }
+    for (const { agent, version } of iterSkillsCapableVersions()) {
+        const diff = diffVersionSkills(agent, version);
+        if (diff.orphans.length > 0)
+            ensure(agent, version).skills = diff.orphans.length;
+    }
+    // Orphan hooks are scripts in the version home that no agents.yaml/hooks.yaml
+    // entry registers — so the registrar never wires them to an event and they
+    // never fire. (Distinct from the source-diff `diffVersionHooks().orphans`,
+    // which false-flags valid system-sourced registered hooks.)
+    for (const { agent, version } of iterHooksCapableVersions()) {
+        const dead = listUnmanagedHooksInVersionHome(agent, version);
+        if (dead.length > 0)
+            ensure(agent, version).hooks = dead.length;
+    }
+    return Array.from(byKey.values()).filter((r) => r.commands + r.skills + r.hooks > 0);
+}
+/**
+ * Compute the same drift/divergence diagnostic `agents doctor` prints, reduced
+ * to a summary with a single `hasDrift` boolean. The gate `agents check` maps
+ * to an exit code; the readout `agents doctor` renders in full.
+ */
+export function computeDrift(cwd) {
+    const syncRows = checkSyncStatus(cwd);
+    const orphanRows = countOrphans();
+    const staleCount = syncRows.filter((r) => r.status === 'stale').length;
+    const neverSyncedCount = syncRows.filter((r) => r.status === 'never-synced').length;
+    return {
+        syncRows,
+        orphanRows,
+        staleCount,
+        neverSyncedCount,
+        orphanVersionCount: orphanRows.length,
+        hasDrift: syncRows.some((r) => r.status !== 'fresh'),
+    };
+}

package/dist/lib/events.d.ts

@@ -177,4 +177,4 @@ export declare function getTimingStats(label: string, options?: {
     p50Ms: number;
     p95Ms: number;
 } | null;
-export declare const LOGS_PATH: string;
+export declare function getLogsPath(): string;

package/dist/lib/events.js

@@ -16,9 +16,25 @@ import * as path from 'path';
 import * as os from 'os';
 import { createHash } from 'node:crypto';
 import { parseSshConnection } from './session/provenance.js';
+import { getLogsDir } from './state.js';
 // ─── Constants ────────────────────────────────────────────────────────────────
-// Logs live under the cache bucket — they're regenerable telemetry.
-const LOGS_DIR = path.join(os.homedir(), '.agents', '.cache', 'logs');
+// Logs live under the cache bucket — they're regenerable telemetry. Route
+// through state's canonical home anchor (HOME override → os.homedir()) rather
+// than a bare os.homedir(): on Windows os.homedir() reads USERPROFILE and
+// ignores a HOME override, so a test (or any caller) that redirects HOME would
+// have its events silently written to the real profile instead. state.getLogsDir()
+// honors the HOME override on every platform while falling back to os.homedir()
+// (== USERPROFILE on Windows) in production where HOME is unset.
+//
+// Resolved lazily + memoized: importing this module must NOT call getLogsDir()
+// at eval time. events.ts is pulled in transitively (skills/versions/exec/
+// runner), and several tests mock './state.js' with partial factories that omit
+// getLogsDir — an eager call would crash those on import. Deferring to first use
+// keeps a bare import side-effect-free while staying a one-time resolution.
+let _logsDir;
+function logsDir() {
+    return (_logsDir ??= getLogsDir());
+}
 /** Default retention period in days. */
 const DEFAULT_RETENTION_DAYS = 7;
 /** Default max length for truncated strings. */
@@ -54,16 +70,16 @@ function getLogFilePath(date = new Date()) {
     const yyyy = date.getFullYear();
     const mm = String(date.getMonth() + 1).padStart(2, '0');
     const dd = String(date.getDate()).padStart(2, '0');
-    return path.join(LOGS_DIR, `events-${yyyy}-${mm}-${dd}.jsonl`);
+    return path.join(logsDir(), `events-${yyyy}-${mm}-${dd}.jsonl`);
 }
 function ensureLogsDir() {
-    if (!fs.existsSync(LOGS_DIR)) {
-        fs.mkdirSync(LOGS_DIR, { recursive: true, mode: DIR_MODE });
+    if (!fs.existsSync(logsDir())) {
+        fs.mkdirSync(logsDir(), { recursive: true, mode: DIR_MODE });
     }
     else {
         // Ensure permissions are correct on existing dir
         try {
-            fs.chmodSync(LOGS_DIR, DIR_MODE);
+            fs.chmodSync(logsDir(), DIR_MODE);
         }
         catch {
             // May fail if not owner
@@ -395,10 +411,10 @@ export function emitError(err, payload = {}) {
  */
 export function rotate(retentionDays = DEFAULT_RETENTION_DAYS) {
     try {
-        if (!fs.existsSync(LOGS_DIR))
+        if (!fs.existsSync(logsDir()))
             return 0;
         const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
-        const files = fs.readdirSync(LOGS_DIR).filter(f => f.startsWith('events-') && f.endsWith('.jsonl'));
+        const files = fs.readdirSync(logsDir()).filter(f => f.startsWith('events-') && f.endsWith('.jsonl'));
         let removed = 0;
         for (const file of files) {
             const match = file.match(/^events-(\d{4})-(\d{2})-(\d{2})\.jsonl$/);
@@ -407,7 +423,7 @@ export function rotate(retentionDays = DEFAULT_RETENTION_DAYS) {
             const [, yyyy, mm, dd] = match;
             const fileDate = new Date(parseInt(yyyy), parseInt(mm) - 1, parseInt(dd));
             if (fileDate.getTime() < cutoff) {
-                fs.unlinkSync(path.join(LOGS_DIR, file));
+                fs.unlinkSync(path.join(logsDir(), file));
                 removed++;
             }
         }
@@ -439,9 +455,9 @@ export function maybeRotate() {
 export function query(options) {
     const { startDate, endDate = new Date(), eventTypes, agent, command, module, limit } = options;
     const results = [];
-    if (!fs.existsSync(LOGS_DIR))
+    if (!fs.existsSync(logsDir()))
         return results;
-    const files = fs.readdirSync(LOGS_DIR)
+    const files = fs.readdirSync(logsDir())
         .filter(f => f.startsWith('events-') && f.endsWith('.jsonl'))
         .sort()
         .reverse();
@@ -467,7 +483,7 @@ export function query(options) {
             continue;
         if (endDay && fileDate > endDay)
             continue;
-        const content = fs.readFileSync(path.join(LOGS_DIR, file), 'utf-8');
+        const content = fs.readFileSync(path.join(logsDir(), file), 'utf-8');
         const lines = content.trim().split('\n').filter(Boolean);
         for (const line of lines.reverse()) {
             try {
@@ -528,4 +544,6 @@ export function getTimingStats(label, options = {}) {
     };
 }
 // ─── Exports ──────────────────────────────────────────────────────────────────
-export const LOGS_PATH = LOGS_DIR;
+export function getLogsPath() {
+    return logsDir();
+}

package/dist/lib/exec.d.ts

@@ -230,6 +230,12 @@ export interface FallbackEntry {
     agent: AgentId;
     /** Optional pinned version (e.g. '0.116.0'). When set, takes precedence over the active default. */
     version?: string;
+    /**
+     * Env vars merged over options.env for THIS attempt only. Used by profiles
+     * with `fallback_model` to swap the model env key (e.g. ANTHROPIC_MODEL) on
+     * a same-agent retry without touching auth or base URL.
+     */
+    envOverride?: Record<string, string>;
 }
 /** ExecOptions extended with a fallback chain for rate-limit cascading. */
 export interface FallbackOptions extends ExecOptions {
@@ -237,6 +243,17 @@ export interface FallbackOptions extends ExecOptions {
     fallback: FallbackEntry[];
     /** Fallback requires a prompt -- chain handoff doesn't apply to interactive sessions. */
     prompt: string;
+    /**
+     * Optional out-param the caller reads AFTER the call to learn which chain
+     * entry actually executed — updated to each entry as it is attempted, so on
+     * return it holds the agent+version whose exit code is returned. Lets the
+     * audit log record the fallback that really ran, not always the primary
+     * (issue #347).
+     */
+    dispatchSink?: {
+        agent?: AgentId;
+        version?: string;
+    };
 }
 /**
  * Build the prompt handed to the fallback agent when the primary was stopped