@phnx-labs/agents-cli 1.22.65 → 1.22.68

package/dist/lib/fleet-shared-repo-sync.js

@@ -0,0 +1,333 @@
+/**
+ * Automatic transport for the non-secret fleet state stored in the user repo.
+ *
+ * Usage/auth services publish only their own conflict-free
+ * `devices/<device>/daemon-state.json` file. This module commits that one path,
+ * rebases the user repo, and pushes it so peer daemons can read the snapshot
+ * after their own fetch/rebase. Git runs asynchronously under one cross-process
+ * lock; every invocation has a wall-clock deadline and a timed-out process tree
+ * is terminated, including git's ssh child and its remote channel.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import lockfile from 'proper-lockfile';
+import { fleetSharedStatePath } from './fleet-shared-state.js';
+import { ensureLockTarget } from './fs-atomic.js';
+import { logAndContinueOnLockCompromised } from './lock-compromise.js';
+import { machineId } from './session/sync/config.js';
+import { getDaemonDir, getUserAgentsDir } from './state.js';
+export const FLEET_SHARED_REPO_SYNC_DEADLINE_MS = 45_000;
+export const FLEET_SHARED_REPO_KILL_GRACE_MS = 250;
+const FLEET_SHARED_REPO_OUTPUT_MAX_BYTES = 1024 * 1024;
+const FLEET_SHARED_REPO_PUSH_ATTEMPTS = 3;
+const FLEET_SHARED_REPO_REBASE_CLEANUP_RESERVE_MS = 5_000;
+function signalProcessTree(child, signal) {
+    const pid = child.pid;
+    if (!pid)
+        return;
+    if (process.platform === 'win32') {
+        // Windows has no process-group signal. taskkill is asynchronous here so a
+        // timeout path cannot replace one event-loop stall with another.
+        const killer = spawn('taskkill', ['/F', '/T', '/PID', String(pid)], {
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        killer.unref();
+        return;
+    }
+    try {
+        // The child is spawned detached on POSIX, so -pid reaches git plus ssh.
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch { /* already gone */ }
+    }
+}
+/** Run one real process asynchronously with a hard wall-clock/process-tree bound. */
+export function runBoundedProcess(command, args, options) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+            detached: process.platform !== 'win32',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let timedOut = false;
+        let overflow = false;
+        let killTimer = null;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            resolve({ code, stdout, stderr, timedOut });
+        };
+        const hardKill = () => {
+            signalProcessTree(child, 'SIGKILL');
+            if (process.platform === 'win32' && !killTimer) {
+                // taskkill owns the descendant cleanup; this fallback only guarantees
+                // the direct child's Promise settles if taskkill itself cannot run.
+                killTimer = setTimeout(() => {
+                    if (!settled) {
+                        try {
+                            child.kill('SIGKILL');
+                        }
+                        catch { /* already gone */ }
+                    }
+                }, FLEET_SHARED_REPO_KILL_GRACE_MS);
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            if (process.platform === 'win32') {
+                hardKill();
+                return;
+            }
+            signalProcessTree(child, 'SIGTERM');
+            killTimer = setTimeout(() => {
+                if (!settled)
+                    hardKill();
+            }, FLEET_SHARED_REPO_KILL_GRACE_MS);
+        }, Math.max(1, options.timeoutMs));
+        const append = (stream, chunk) => {
+            if (overflow)
+                return;
+            const value = String(chunk);
+            if (Buffer.byteLength(stdout) + Buffer.byteLength(stderr) + Buffer.byteLength(value) > FLEET_SHARED_REPO_OUTPUT_MAX_BYTES) {
+                overflow = true;
+                stderr += '\ngit output exceeded 1 MiB';
+                hardKill();
+                return;
+            }
+            if (stream === 'stdout')
+                stdout += value;
+            else
+                stderr += value;
+        };
+        child.stdout?.on('data', (chunk) => append('stdout', chunk));
+        child.stderr?.on('data', (chunk) => append('stderr', chunk));
+        child.on('error', (err) => {
+            stderr += err.message;
+            finish(null);
+        });
+        child.on('close', (code) => finish(code));
+    });
+}
+function failure(command, result) {
+    const detail = result.timedOut
+        ? `${command} timed out`
+        : result.stderr.trim() || result.stdout.trim() || `${command} exited ${result.code ?? 'without a status'}`;
+    return {
+        success: false,
+        committed: false,
+        pushed: false,
+        commit: null,
+        timedOut: result.timedOut,
+        skipped: null,
+        error: detail,
+    };
+}
+function isPushRace(result) {
+    const text = `${result.stdout}\n${result.stderr}`.toLowerCase();
+    return text.includes('non-fast-forward') || text.includes('fetch first') || text.includes('[rejected]');
+}
+function createdAutostashObject(result) {
+    return `${result.stdout}\n${result.stderr}`.match(/created autostash:\s*([0-9a-f]+)/i)?.[1] ?? null;
+}
+function retainedAutostash(stashList, objectId) {
+    if (stashList.code === 0) {
+        const entries = stashList.stdout.trim().split('\n').filter(Boolean).map((line) => {
+            const [ref = '', hash = '', ...subject] = line.split('\t');
+            return { ref, hash, subject: subject.join('\t') };
+        });
+        const matched = objectId
+            ? entries.find((entry) => entry.hash.startsWith(objectId) || objectId.startsWith(entry.hash))
+            : entries.find((entry) => /autostash/i.test(entry.subject));
+        if (matched?.ref)
+            return { label: `${matched.ref} (${matched.hash.slice(0, 8)})`, ref: matched.ref };
+    }
+    return {
+        label: objectId ? `autostash object ${objectId}` : 'the retained autostash',
+        ref: null,
+    };
+}
+async function performFleetSharedRepoSync(root, device, timeoutMs) {
+    if (!fs.existsSync(path.join(root, '.git'))) {
+        return {
+            success: false,
+            committed: false,
+            pushed: false,
+            commit: null,
+            timedOut: false,
+            skipped: `user store is not git-backed: ${root}`,
+            error: null,
+        };
+    }
+    const deadline = Date.now() + timeoutMs;
+    const git = async (args, reserveMs = 0) => {
+        const remaining = deadline - Date.now() - reserveMs;
+        if (remaining <= 0)
+            return { code: null, stdout: '', stderr: '', timedOut: true };
+        return runBoundedProcess('git', args, {
+            cwd: root,
+            timeoutMs: remaining,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        });
+    };
+    const branchResult = await git(['branch', '--show-current']);
+    if (branchResult.code !== 0)
+        return failure('git branch --show-current', branchResult);
+    const branch = branchResult.stdout.trim();
+    if (!branch) {
+        return {
+            success: false,
+            committed: false,
+            pushed: false,
+            commit: null,
+            timedOut: false,
+            skipped: null,
+            error: 'user store is on a detached HEAD',
+        };
+    }
+    const ownedFile = fleetSharedStatePath(device, root);
+    const relativeOwnedFile = path.relative(root, ownedFile).split(path.sep).join('/');
+    let committed = false;
+    if (fs.existsSync(ownedFile)) {
+        const status = await git(['status', '--porcelain=v1', '--', relativeOwnedFile]);
+        if (status.code !== 0)
+            return failure('git status', status);
+        if (status.stdout.trim()) {
+            const add = await git(['add', '--', relativeOwnedFile]);
+            if (add.code !== 0)
+                return failure('git add', add);
+            const commit = await git([
+                '-c', 'commit.gpgsign=false',
+                'commit', '--no-verify', '-m', `chore(devices): publish ${device} daemon state`,
+                '--', relativeOwnedFile,
+            ]);
+            if (commit.code !== 0)
+                return failure('git commit', commit);
+            committed = true;
+        }
+    }
+    for (let attempt = 1; attempt <= FLEET_SHARED_REPO_PUSH_ATTEMPTS; attempt++) {
+        const fetch = await git(['fetch', 'origin']);
+        if (fetch.code !== 0)
+            return { ...failure('git fetch', fetch), committed };
+        // Keep enough of the same wall-clock bound available to remove a botched
+        // autostash pop from the operator's live checkout before returning.
+        const rebase = await git(['rebase', '--autostash', `origin/${branch}`], FLEET_SHARED_REPO_REBASE_CLEANUP_RESERVE_MS);
+        if (rebase.code !== 0) {
+            // Rebase can leave control files behind even when the child was killed.
+            // Abort is bounded by the same overall deadline and never hides the cause.
+            await git(['rebase', '--abort']);
+            return { ...failure('git rebase', rebase), committed };
+        }
+        // `git rebase --autostash` exits zero when the rebase succeeds but applying
+        // the autostash conflicts. Never push or leave those conflict markers in
+        // the operator's real ~/.agents checkout. Git retains the original changes
+        // in the stash on this path, so reset only the failed pop to rebased HEAD.
+        const unmerged = await git(['ls-files', '--unmerged']);
+        if (unmerged.code !== 0)
+            return { ...failure('git ls-files --unmerged', unmerged), committed };
+        if (unmerged.stdout.trim()) {
+            const autostashObject = createdAutostashObject(rebase);
+            const reset = await git(['reset', '--hard', 'HEAD']);
+            const cleaned = await git(['ls-files', '--unmerged']);
+            const stashList = await git(['stash', 'list', '--format=%gd%x09%H%x09%gs']);
+            const stash = retainedAutostash(stashList, autostashObject);
+            if (reset.code !== 0 || cleaned.code !== 0 || cleaned.stdout.trim()) {
+                const cleanup = reset.code !== 0
+                    ? failure('git reset --hard HEAD', reset).error
+                    : cleaned.code !== 0
+                        ? failure('git ls-files --unmerged', cleaned).error
+                        : 'unmerged index entries remain after git reset --hard HEAD';
+                return {
+                    success: false,
+                    committed,
+                    pushed: false,
+                    commit: null,
+                    timedOut: reset.timedOut || cleaned.timedOut,
+                    skipped: null,
+                    error: `autostash pop conflicted; push refused, but cleanup failed: ${cleanup}. Original tracked changes remain safe in ${stash.label}`,
+                };
+            }
+            return {
+                success: false,
+                committed,
+                pushed: false,
+                commit: null,
+                timedOut: false,
+                skipped: null,
+                error: `autostash pop conflicted; push refused and the worktree was reset to rebased HEAD without conflict markers. Original tracked changes remain safe in ${stash.label}; inspect with ${stash.ref ? `git stash show -p ${stash.ref}` : 'git stash list'}`,
+            };
+        }
+        const push = await git(['push', '--', 'origin', branch]);
+        if (push.code === 0) {
+            const head = await git(['rev-parse', '--short=8', 'HEAD']);
+            return {
+                success: true,
+                committed,
+                pushed: committed || push.stdout.trim().length > 0 || push.stderr.includes('->'),
+                commit: head.code === 0 ? head.stdout.trim() : null,
+                timedOut: false,
+                skipped: null,
+                error: null,
+            };
+        }
+        if (attempt === FLEET_SHARED_REPO_PUSH_ATTEMPTS || !isPushRace(push)) {
+            return { ...failure('git push', push), committed };
+        }
+    }
+    throw new Error('unreachable fleet shared repo push loop');
+}
+/**
+ * Commit/pull/push this device's shared state under one cross-process lock.
+ * Callers publish their local fields first and consume peer fields only after
+ * this resolves successfully.
+ */
+export async function syncFleetSharedStateRepo(options = {}) {
+    const root = options.userAgentsDir ?? getUserAgentsDir();
+    const device = options.device ?? machineId();
+    const timeoutMs = options.timeoutMs ?? FLEET_SHARED_REPO_SYNC_DEADLINE_MS;
+    const lockPath = options.lockPath ?? path.join(getDaemonDir(), 'fleet-shared-repo-sync');
+    ensureLockTarget(lockPath, '');
+    let release = null;
+    try {
+        release = await lockfile.lock(lockPath, {
+            stale: Math.max(10_000, timeoutMs + 5_000),
+            retries: { retries: 20, factor: 1, minTimeout: 100, maxTimeout: 100 },
+            onCompromised: logAndContinueOnLockCompromised('fleet shared repo sync'),
+        });
+        return await performFleetSharedRepoSync(root, device, timeoutMs);
+    }
+    catch (err) {
+        return {
+            success: false,
+            committed: false,
+            pushed: false,
+            commit: null,
+            timedOut: false,
+            skipped: null,
+            error: err.message,
+        };
+    }
+    finally {
+        if (release) {
+            try {
+                await release();
+            }
+            catch { /* compromised/already released */ }
+        }
+    }
+}

package/dist/lib/fleet-shared-state.d.ts

@@ -0,0 +1,38 @@
+import type { CachedUsageSnapshot } from './accounting/usage.js';
+export declare const FLEET_SHARED_STATE_VERSION = 1;
+export declare const FLEET_SHARED_STATE_FILE = "daemon-state.json";
+export type SharedAuthStatus = 'ready' | 'missing' | 'invalid';
+export interface FleetSharedDeviceState {
+    version: typeof FLEET_SHARED_STATE_VERSION;
+    device: string;
+    usage?: {
+        rows: Record<string, CachedUsageSnapshot>;
+    };
+    auth?: {
+        status: SharedAuthStatus;
+    };
+}
+export interface FleetSharedStatePatch {
+    usage?: FleetSharedDeviceState['usage'];
+    auth?: FleetSharedDeviceState['auth'];
+}
+export interface FleetSharedStateReadResult {
+    states: FleetSharedDeviceState[];
+    errors: Array<{
+        device: string;
+        message: string;
+    }>;
+}
+/** Path owned by one device in the conflict-free tracked device-doc tree. */
+export declare function fleetSharedStatePath(device: string, userAgentsDir?: string): string;
+/**
+ * Merge one daemon-owned field into this device's shared file under a real
+ * inter-process lock. Stable serialization avoids dirtying the user repo when
+ * neither usage nor auth state changed.
+ */
+export declare function updateFleetSharedDeviceState(device: string, patch: FleetSharedStatePatch, userAgentsDir?: string): {
+    changed: boolean;
+    path: string;
+};
+/** Read every valid peer-owned state file; malformed peers fail separately. */
+export declare function readFleetSharedDeviceStates(userAgentsDir?: string): FleetSharedStateReadResult;

package/dist/lib/fleet-shared-state.js

@@ -0,0 +1,105 @@
+/**
+ * Non-secret daemon state exchanged through the already fleet-synced user repo.
+ *
+ * Each device owns exactly one file under `~/.agents/devices/<device>/`, so
+ * normal `agents repo push/pull user` merges the fleet without devices dialing
+ * one another on every daemon tick. OAuth/setup-token values never belong here:
+ * auth publishes only a readiness verdict; the existing encrypted SSH transport
+ * remains the one path that may carry secret material.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { assertValidDeviceName } from './devices/registry.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
+import { getUserAgentsDir } from './state.js';
+export const FLEET_SHARED_STATE_VERSION = 1;
+export const FLEET_SHARED_STATE_FILE = 'daemon-state.json';
+/** Path owned by one device in the conflict-free tracked device-doc tree. */
+export function fleetSharedStatePath(device, userAgentsDir = getUserAgentsDir()) {
+    assertValidDeviceName(device);
+    return path.join(userAgentsDir, 'devices', device, FLEET_SHARED_STATE_FILE);
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function parseFleetSharedDeviceState(raw, owner) {
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed) || parsed.version !== FLEET_SHARED_STATE_VERSION || parsed.device !== owner) {
+        throw new Error('unrecognized shared-state envelope');
+    }
+    const usage = parsed.usage;
+    if (usage !== undefined && (!isRecord(usage) || !isRecord(usage.rows))) {
+        throw new Error('unrecognized usage snapshot');
+    }
+    const auth = parsed.auth;
+    if (auth !== undefined &&
+        (!isRecord(auth) || !['ready', 'missing', 'invalid'].includes(String(auth.status)))) {
+        throw new Error('unrecognized auth verdict');
+    }
+    return parsed;
+}
+/**
+ * Merge one daemon-owned field into this device's shared file under a real
+ * inter-process lock. Stable serialization avoids dirtying the user repo when
+ * neither usage nor auth state changed.
+ */
+export function updateFleetSharedDeviceState(device, patch, userAgentsDir = getUserAgentsDir()) {
+    const file = fleetSharedStatePath(device, userAgentsDir);
+    ensureLockTarget(file, '');
+    return withFileLock(file, () => {
+        let current = {
+            version: FLEET_SHARED_STATE_VERSION,
+            device,
+        };
+        try {
+            const raw = fs.readFileSync(file, 'utf-8').trim();
+            if (raw)
+                current = parseFleetSharedDeviceState(raw, device);
+        }
+        catch {
+            // The owning device repairs its own malformed file from authoritative
+            // local state. Peer files are never repaired by this writer.
+        }
+        const next = {
+            ...current,
+            ...(patch.usage !== undefined ? { usage: patch.usage } : {}),
+            ...(patch.auth !== undefined ? { auth: patch.auth } : {}),
+            version: FLEET_SHARED_STATE_VERSION,
+            device,
+        };
+        const serialized = `${JSON.stringify(next, null, 2)}\n`;
+        if (fs.readFileSync(file, 'utf-8') === serialized)
+            return { changed: false, path: file };
+        atomicWriteFileSync(file, serialized, 'utf-8');
+        return { changed: true, path: file };
+    });
+}
+/** Read every valid peer-owned state file; malformed peers fail separately. */
+export function readFleetSharedDeviceStates(userAgentsDir = getUserAgentsDir()) {
+    const devicesDir = path.join(userAgentsDir, 'devices');
+    let entries;
+    try {
+        entries = fs.readdirSync(devicesDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { states: [], errors: [] };
+        return { states: [], errors: [{ device: '*', message: err.message }] };
+    }
+    const states = [];
+    const errors = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory())
+            continue;
+        const file = path.join(devicesDir, entry.name, FLEET_SHARED_STATE_FILE);
+        if (!fs.existsSync(file))
+            continue;
+        try {
+            states.push(parseFleetSharedDeviceState(fs.readFileSync(file, 'utf-8'), entry.name));
+        }
+        catch (err) {
+            errors.push({ device: entry.name, message: err.message });
+        }
+    }
+    return { states, errors };
+}

package/dist/lib/hosts/remote-cmd.d.ts

@@ -118,6 +118,8 @@ export interface WindowsAgentsCommand {
      * pass false for probes whose reachability keys off a sentinel, not the code.
      */
     propagateExit?: boolean;
+    /** Remap a reached peer command's 255 to 254 so SSH's own 255 stays unambiguous. */
+    remapExit255?: boolean;
 }
 /**
  * The PowerShell script (pre-encoding) that {@link buildWindowsAgentsCommand}

package/dist/lib/hosts/remote-cmd.js

@@ -131,6 +131,11 @@ export const RUN_OPTION_FORWARDING = {
     // process follows the remote run to completion, so its exit handler fires at
     // the right moment anyway.
     notify: 'local-only',
+    // --no-trace-sync (traceSync=false) gates the LOCAL run-exit trace auto-sync,
+    // which only arms for local runs anyway (exec.ts skips it for --device/--lease).
+    // On a --device dispatch the remote box runs its own run-exit sync, so this
+    // flag is never forwarded — it is a local-exit-behavior toggle, not remote.
+    traceSync: 'local-only',
     // Deprecated alias for --device auto; resolved on the launching box before SSH.
     smart: 'local-only',
     // Broadcast mode (agents run --broadcast) is its own fan-out dispatch — mutually
@@ -289,7 +294,7 @@ export function stripClixml(stdout) {
         .trim();
 }
 export function windowsAgentsScript(cmd) {
-    const { args, env, cwd, propagateExit = true } = cmd;
+    const { args, env, cwd, propagateExit = true, remapExit255 = false } = cmd;
     const parts = [POWERSHELL_PROGRESS_SILENCE];
     if (env)
         for (const [k, v] of Object.entries(env))
@@ -297,8 +302,12 @@ export function windowsAgentsScript(cmd) {
     if (cwd)
         parts.push(`Set-Location -LiteralPath ${powershellQuote(cwd)}`);
     parts.push(`& ${['agents', ...args].map(powershellQuote).join(' ')}`);
-    if (propagateExit)
-        parts.push('exit $LASTEXITCODE');
+    if (propagateExit) {
+        if (remapExit255)
+            parts.push('$agentsExit = $LASTEXITCODE', 'if ($agentsExit -eq 255) { exit 254 }', 'exit $agentsExit');
+        else
+            parts.push('exit $LASTEXITCODE');
+    }
     return parts.join('; ');
 }
 /**

package/dist/lib/lock-compromise.d.ts

@@ -0,0 +1,8 @@
+/**
+ * proper-lockfile invokes this callback from its background refresh timer.
+ * Its default is to throw there, outside the caller's promise chain, which can
+ * terminate the daemon. These leases are advisory serialization barriers: log
+ * a broken lease and let the owning operation finish instead of crashing the
+ * shared process.
+ */
+export declare function logAndContinueOnLockCompromised(scope: string): (err: Error) => void;

package/dist/lib/lock-compromise.js

@@ -0,0 +1,12 @@
+/**
+ * proper-lockfile invokes this callback from its background refresh timer.
+ * Its default is to throw there, outside the caller's promise chain, which can
+ * terminate the daemon. These leases are advisory serialization barriers: log
+ * a broken lease and let the owning operation finish instead of crashing the
+ * shared process.
+ */
+export function logAndContinueOnLockCompromised(scope) {
+    return (err) => {
+        console.warn(`[agents ${scope}] Lock was compromised; continuing without crashing: ${err.message}`);
+    };
+}

package/dist/lib/monitors/engine.d.ts

@@ -58,6 +58,7 @@ export declare class MonitorEngine {
     private monitors;
     private lastEval;
     private ticking;
+    private running;
     constructor(logFn?: LogFn);
     /** Load owned+enabled monitors and start the tick loop. */
     start(options?: {
@@ -65,7 +66,7 @@ export declare class MonitorEngine {
     }): void;
     /** Reload monitor configs (SIGHUP). */
     reload(): void;
-    /** Stop the tick loop. */
+    /** Stop the tick loop. No monitor dispatches after this until `start()`. */
     stop(): void;
     private loadAll;
     private intervalMs;

package/dist/lib/monitors/engine.js

@@ -122,11 +122,13 @@ export class MonitorEngine {
     monitors = [];
     lastEval = new Map();
     ticking = false;
+    running = false;
     constructor(logFn = () => { }) {
         this.logFn = logFn;
     }
     /** Load owned+enabled monitors and start the tick loop. */
     start(options = {}) {
+        this.running = true;
         this.loadAll();
         this.logFn('INFO', `Monitor engine started (${this.monitors.length} monitor(s) on this device)`);
         if (!options.externalScheduler) {
@@ -138,8 +140,9 @@ export class MonitorEngine {
         this.loadAll();
         this.logFn('INFO', `Monitor engine reloaded (${this.monitors.length} monitor(s) on this device)`);
     }
-    /** Stop the tick loop. */
+    /** Stop the tick loop. No monitor dispatches after this until `start()`. */
     stop() {
+        this.running = false;
         if (this.timer) {
             clearInterval(this.timer);
             this.timer = null;
@@ -159,7 +162,11 @@ export class MonitorEngine {
     }
     /** Evaluate every due monitor once. Overlap-guarded so a slow cycle never stacks. */
     async tick() {
-        if (this.ticking)
+        // A stopped engine dispatches nothing (PHNX-3608): under the external
+        // scheduler the supervisor owns the timer, so a `stop()` (monitors service
+        // disabled) must be honoured HERE — otherwise the next supervised tick would
+        // still fire the last-loaded monitors even though the engine is stopped.
+        if (!this.running || this.ticking)
             return;
         this.ticking = true;
         try {

package/dist/lib/refresh-coordinator.js

@@ -3,6 +3,7 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import lockfile from 'proper-lockfile';
 import { getCacheDir } from './state.js';
+import { logAndContinueOnLockCompromised } from './lock-compromise.js';
 const REFRESH_LOCK_STALE_MS = 2 * 60_000;
 let refreshLockRootOverride = null;
 export function setRefreshLockRootForTest(root) {
@@ -39,6 +40,7 @@ export async function withRefreshLease(options) {
         stale: REFRESH_LOCK_STALE_MS,
         update: REFRESH_LOCK_STALE_MS / 4,
         retries: { retries: 240, minTimeout: 25, maxTimeout: 500, factor: 1.2 },
+        onCompromised: logAndContinueOnLockCompromised('refresh lease'),
     });
     try {
         const completed = options.readCompleted();

package/dist/lib/run-trace-sync.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The policy gate, pure and unit-testable. `disabled` is the resolved
+ * `--no-trace-sync` (commander maps it to `traceSync === false`).
+ */
+export declare function shouldAutoSyncTraces(disabled: boolean): boolean;
+/**
+ * Arm a fire-and-forget `agents traces sync` for when this process exits.
+ * No-op unless {@link shouldAutoSyncTraces} passes. Best-effort by
+ * construction: a missing binary or a stalled child never affects the run.
+ */
+export declare function armRunFinishTraceSync(opts?: {
+    disabled?: boolean;
+}): void;