@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/commands/watchdog.js

@@ -0,0 +1,238 @@
+/**
+ * `agents watchdog` — the watchdog CONSUMER (RUSH-1415).
+ *
+ * Runs the tick loop that ties the merged pieces together: list active sessions,
+ * classify stalls, read the tail, decide (deterministic promise-without-toolcall
+ * by default), run the resolver safety gate, and inject "Continue." into the EXACT
+ * split — all without the Swift menu-bar. See src/lib/watchdog/runner.ts.
+ *
+ *   agents watchdog                    one tick, dry — prints what it WOULD nudge/skip and why
+ *   agents watchdog --nudge            one tick, actually injects (explicit opt-in)
+ *   agents watchdog --watch            daemon loop (poll every --interval)
+ *   agents watchdog --json             machine-readable tick output (for the menu-bar)
+ *   agents watchdog enable|disable     flip the global auto-nudge sentinel (default OFF)
+ *   agents watchdog policy <id> <p>    per-session policy: off | keep | handsoff
+ */
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+import { setHelpSections } from '../lib/help.js';
+import { parseDuration } from '../lib/hooks/cache.js';
+import { getRuntimeStateDir } from '../lib/state.js';
+import { runWatchdogTick, writePolicySentinel, DEFAULT_THRESHOLDS, } from '../lib/watchdog/runner.js';
+/** Default state dir the runner and these subcommands share. */
+function stateDir() {
+    return path.join(getRuntimeStateDir(), 'watchdog');
+}
+/** Global auto-nudge sentinel — present = enabled. Default OFF (opt-in). */
+function enabledSentinelPath() {
+    return path.join(stateDir(), 'enabled');
+}
+function isGloballyEnabled() {
+    return fs.existsSync(enabledSentinelPath());
+}
+function setGloballyEnabled(on) {
+    const p = enabledSentinelPath();
+    if (on) {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, 'enabled\n');
+    }
+    else {
+        try {
+            fs.rmSync(p);
+        }
+        catch { /* already off */ }
+    }
+}
+/** Parse a duration flag ("60s", "5m", "1h") to ms, or fall back to `fallbackMs`. */
+function durationMsOr(raw, fallbackMs) {
+    if (raw === undefined)
+        return fallbackMs;
+    const secs = parseDuration(raw);
+    return secs === null ? fallbackMs : secs * 1000;
+}
+function humanMs(ms) {
+    if (ms >= 3600_000)
+        return `${Math.round(ms / 3600_000)}h`;
+    if (ms >= 60_000)
+        return `${Math.round(ms / 60_000)}m`;
+    return `${Math.round(ms / 1000)}s`;
+}
+function colorForOutcome(o) {
+    if (o.injected)
+        return chalk.green;
+    if (o.addressable === false)
+        return chalk.yellow;
+    if (o.stall === 'stalled' && o.decision === 'nudge')
+        return chalk.cyan;
+    return chalk.dim;
+}
+/** Render one tick's outcomes as a human status block. */
+function printTick(result, willInject) {
+    const { counts } = result;
+    const mode = willInject ? chalk.green('nudge') : chalk.dim('dry');
+    console.log(`${chalk.bold('watchdog')} ${mode}  ` +
+        `${counts.total} live · ${counts.stalled} stalled · ` +
+        `${chalk.green(String(counts.nudged))} nudged · ` +
+        `${chalk.yellow(String(counts.unaddressable))} un-addressable`);
+    for (const o of result.outcomes) {
+        const tag = o.injected ? 'NUDGED'
+            : o.addressable === false ? 'FLAGGED'
+                : o.decision === 'nudge' ? 'WOULD-NUDGE'
+                    : 'skip';
+        const c = colorForOutcome(o);
+        const who = o.label || o.sessionId?.slice(0, 8) || o.kind;
+        const where = o.host ? chalk.dim(`[${o.host}]`) : '';
+        const rail = o.rail ? chalk.dim(`→${o.rail}`) : '';
+        console.log(`  ${c(tag.padEnd(11))} ${chalk.bold(who)} ${where} ${rail}`);
+        console.log(`    ${chalk.dim(o.reason)}`);
+    }
+}
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Register the `agents watchdog` command tree. */
+export function registerWatchdogCommand(program) {
+    const cmd = program
+        .command('watchdog')
+        .description('Auto-nudge stalled agent terminals: detect stalls, resolve the exact split, inject "Continue." — no menu-bar needed.')
+        .option('--nudge', 'Actually inject (default is a dry run that only reports what it would do)')
+        .option('--watch', 'Daemon loop: run a tick every --interval until interrupted')
+        .option('--interval <dur>', 'Poll interval in --watch mode (e.g. 30s, 1m)', '30s')
+        .option('--stall <dur>', 'Idle time before a session counts as stalled', humanMs(DEFAULT_THRESHOLDS.stallMs))
+        .option('--cooldown <dur>', 'Minimum time between nudges to the same session', humanMs(DEFAULT_THRESHOLDS.cooldownMs))
+        .option('--dormant <dur>', 'Idle time after which a session is left alone (dormant)', humanMs(DEFAULT_THRESHOLDS.dormantMs))
+        .option('--text <text>', 'Nudge text delivered into the terminal', 'Continue.')
+        .option('--smart', 'Use the LLM decider (agents run) instead of the deterministic path (non-reproducible)')
+        .option('--smart-agent <agent>', 'Agent the --smart decider runs as', 'claude')
+        .option('--allow-ghostty-focus', 'Permit the coarse, focus-stealing Ghostty path (off by default)')
+        .option('--json', 'Emit the tick result as JSON (for the menu-bar / scripts)')
+        .action(async (opts) => {
+        const thresholds = {
+            stallMs: durationMsOr(opts.stall, DEFAULT_THRESHOLDS.stallMs),
+            cooldownMs: durationMsOr(opts.cooldown, DEFAULT_THRESHOLDS.cooldownMs),
+            dormantMs: durationMsOr(opts.dormant, DEFAULT_THRESHOLDS.dormantMs),
+        };
+        // Injection gate: --nudge is the explicit per-run opt-in; the global sentinel
+        // enables the automatic daemon. Default OFF: bare `agents watchdog` is dry.
+        // Re-read the sentinel every tick so a running `--watch` daemon reflects a
+        // later `agents watchdog enable`/`disable` (or the Swift menu-bar toggle)
+        // from another shell without a restart.
+        const computeWillInject = () => opts.nudge === true || (opts.watch === true && isGloballyEnabled());
+        const tickOnce = async (willInject) => runWatchdogTick({
+            nudge: willInject,
+            nudgeText: opts.text,
+            smart: opts.smart === true,
+            smartAgent: opts.smartAgent,
+            thresholds,
+            allowGhosttyFocus: opts.allowGhosttyFocus === true,
+            stateDir: stateDir(),
+        });
+        if (!opts.watch) {
+            const willInject = computeWillInject();
+            const result = await tickOnce(willInject);
+            if (opts.json)
+                console.log(JSON.stringify(result, null, 2));
+            else
+                printTick(result, willInject);
+            return;
+        }
+        // Daemon loop.
+        const intervalMs = durationMsOr(opts.interval, 30_000);
+        if (!computeWillInject() && !opts.json) {
+            console.log(chalk.yellow(`watchdog --watch is DETECT-ONLY (global auto-nudge is ${isGloballyEnabled() ? 'on' : 'off'}). ` +
+                `Pass --nudge or run 'agents watchdog enable' to inject.`));
+        }
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            // Re-evaluated each tick: picks up enable/disable flips mid-run.
+            const willInject = computeWillInject();
+            const result = await tickOnce(willInject);
+            if (opts.json)
+                console.log(JSON.stringify(result));
+            else
+                printTick(result, willInject);
+            await sleep(intervalMs);
+        }
+    });
+    setHelpSections(cmd, {
+        examples: `
+      # One tick, dry — see what it WOULD nudge and why (safe, no injection)
+      agents watchdog
+
+      # One tick, actually inject "Continue." into stalled+addressable splits
+      agents watchdog --nudge
+
+      # Watch loop every 30s, tighter stall threshold
+      agents watchdog --watch --interval 30s --stall 60s --cooldown 5m
+
+      # Machine-readable for the menu-bar
+      agents watchdog --json
+
+      # Turn on the global auto-nudge (so --watch injects without --nudge)
+      agents watchdog enable
+
+      # Leave one session detected-but-untouched
+      agents watchdog policy <sessionId> handsoff
+    `,
+        notes: `
+      Decision path (default, deterministic): a session is nudged only when its
+      transcript tail shows it ANNOUNCED an action but no tool call followed
+      (promise-without-toolcall) AND it is not waiting on the user. Completions and
+      open questions are skipped.
+
+      Safety gate: a nudge is delivered ONLY when the resolver can name the EXACT
+      split the agent lives in (tmux / iTerm / IDE terminal). Un-addressable stalls
+      (e.g. Ghostty with no tmux) are flagged for the menu-bar and SKIPPED — never
+      a guessed or frontmost target.
+
+      Policy: global auto-nudge defaults OFF (opt-in via 'enable' or --nudge).
+      Per-session: off (ignore), keep (default), handsoff (detect + flag, never inject).
+
+      State (tray-readable): ${path.join('~/.agents/.cache/state/watchdog', '{nudges,flags,last-tick}.json')}
+    `,
+    });
+    // --- global enable/disable/status -----------------------------------------
+    cmd.command('enable')
+        .description('Turn ON global auto-nudge (so `agents watchdog --watch` injects without --nudge).')
+        .action(() => {
+        setGloballyEnabled(true);
+        console.log(chalk.green('watchdog: global auto-nudge ENABLED'));
+    });
+    cmd.command('disable')
+        .description('Turn OFF global auto-nudge (back to detect-only unless --nudge is passed).')
+        .action(() => {
+        setGloballyEnabled(false);
+        console.log(chalk.yellow('watchdog: global auto-nudge DISABLED'));
+    });
+    cmd.command('status')
+        .description('Show whether global auto-nudge is on and where state is written.')
+        .option('--json', 'Emit status as JSON (for the menu-bar / scripts)')
+        .action((_opts, command) => {
+        // The parent `watchdog` command also declares --json and greedily parses it
+        // before dispatching here, so `watchdog status --json` lands the flag on the
+        // parent, not this subcommand. optsWithGlobals() merges both levels, so we
+        // read it correctly regardless of which command commander bound it to.
+        const json = command.optsWithGlobals().json === true;
+        const on = isGloballyEnabled();
+        if (json) {
+            console.log(JSON.stringify({ enabled: on, stateDir: stateDir() }));
+            return;
+        }
+        console.log(`global auto-nudge: ${on ? chalk.green('ON') : chalk.dim('off')}`);
+        console.log(`state dir: ${chalk.dim(stateDir())}`);
+    });
+    // --- per-session policy ----------------------------------------------------
+    cmd.command('policy <sessionId> <policy>')
+        .description('Set per-session policy: off (ignore) | keep (default) | handsoff (detect + flag, never inject).')
+        .action((sessionId, policy) => {
+        const p = policy.toLowerCase();
+        if (p !== 'off' && p !== 'keep' && p !== 'handsoff') {
+            console.error(chalk.red(`invalid policy '${policy}'. Use: off | keep | handsoff`));
+            process.exitCode = 1;
+            return;
+        }
+        writePolicySentinel(stateDir(), sessionId, p);
+        console.log(`watchdog: session ${chalk.bold(sessionId.slice(0, 8))} policy = ${chalk.cyan(p)}`);
+    });
+}

package/dist/index.js

@@ -51,7 +51,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadSsh, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadSsh, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { IS_WINDOWS } from './lib/platform/index.js';
@@ -183,6 +183,7 @@ Credentials and profiles:
 
 Diagnostics:
   doctor [agent[@version]]        Diagnose CLI availability, sync status, and resource divergence
+  check                           CI drift gate: exit non-zero when resources are out of sync
   usage [agent]                   Show rate-limit and quota usage per agent
 
 Config sync:
@@ -190,6 +191,7 @@ Config sync:
   pull                            Clone or pull the system repo at ~/.agents/.system/
   repo init --path <dir>          Scaffold your own editable repo from a template
   repo add <path|gh:user/repo>    Merge an extra repo after the system repo
+  lock [--frozen]                 Write/verify agents.lock (SHA-256 of resolved resources); --frozen fails on drift
 
 Beta features:
   beta                            Enable preview features (factory, drive, and more)
@@ -789,6 +791,7 @@ async function registerAllEagerCommands() {
     await reg(loadTrash);
     await reg(loadRestore);
     await reg(loadDoctor);
+    await reg(loadCheck);
     await reg(loadStatus);
     registerExecAliasCommand(program);
     await reg(loadProfiles);
@@ -798,6 +801,7 @@ async function registerAllEagerCommands() {
     await reg(loadMenubar);
     await reg(loadBeta);
     await reg(loadSync);
+    await reg(loadLock);
     await reg(loadRefreshRules);
     await reg(loadDrive);
     await reg(loadFactory);
@@ -807,11 +811,13 @@ async function registerAllEagerCommands() {
     await reg(loadAlias);
     await reg(loadPty);
     await reg(loadTmux);
+    await reg(loadWatchdog);
     await reg(loadBrowser);
     await reg(loadComputer);
     await reg(loadHosts);
     await reg(loadLogs);
     await reg(loadEvents);
+    await reg(loadAudit);
     await reg(loadSsh);
     registerJobsCronAliasCommand(program, 'jobs');
     registerJobsCronAliasCommand(program, 'cron');
@@ -983,7 +989,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
         // Bumping the suffix re-runs migrations for every user; binary releases that
         // don't change the schema must NOT re-run (they would destroy user content
         // when migration steps overlap with user-authored paths). See issue #20.
-        const sentinelValue = 'v10';
+        const sentinelValue = 'v11';
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {
@@ -1016,6 +1022,15 @@ if (process.platform === 'darwin' && process.env.AGENTS_SKIP_MIGRATION !== '1')
     }
     catch { /* never block CLI startup on the menu bar */ }
 }
+// Bare invocation prints the root help. Commander only auto-displays help on
+// an empty parse when subcommands are registered, and the lazy-startup path
+// registers none for a bare call — without this branch, `agents` exits
+// silently. Runs after first-run setup and migrations so those still fire;
+// exits 0 to match `agents --help` (and the pre-fix exit code).
+if (passedArgs.length === 0) {
+    program.outputHelp();
+    process.exit(0);
+}
 try {
     await maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequested);
     await program.parseAsync();
@@ -1036,6 +1051,14 @@ catch (err) {
             console.error(err.message);
             process.exit(1);
         }
+        // A --host targeting a password-auth device throws this from resolveHost.
+        // It carries an actionable message (switch to key auth / enroll as a host);
+        // handling it here covers every resolveHost caller (run, hosts check/rm,
+        // secrets --host) at the source instead of a catch at each call site.
+        if (err.name === 'DeviceOffloadUnsupportedError') {
+            console.error(err.message);
+            process.exit(1);
+        }
     }
     throw err;
 }

package/dist/lib/audit/log.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Cross-agent, tamper-evident audit log of every dispatched run (issue #347).
+ *
+ * Every run that reaches the single dispatch chokepoint in `agents run`
+ * (src/commands/exec.ts) appends ONE record here. Records form a hash chain:
+ * each record embeds the previous record's `hash` as `prevHash`, and its own
+ * `hash` is `sha256(canonicalJSON(record-without-hash))`. Because `prevHash`
+ * is part of the hashed payload, rewriting or reordering any record breaks the
+ * chain from that point forward — `verifyAuditChain()` reports the first index
+ * that fails to reproduce.
+ *
+ * Storage is append-only JSONL under the durable-runtime bucket
+ * (`~/.agents/.history/audit/log.jsonl`), one record per line. `.history/` is
+ * machine-local, gitignored, and NEVER synced by `agents repo push/pull` — so
+ * the `repo` field (a git remote url that can embed an access token) never
+ * lands in a version-controlled DotAgents repo, and a cross-machine pull can't
+ * splice a foreign chain into this one. The write path is deliberately cheap
+ * and non-fatal: a logging failure must never crash a run (see
+ * `recordDispatchedRun`). Concurrent writers (parallel teams/routines dispatch)
+ * are serialized by an advisory lock file so the chain never forks — see
+ * `appendAuditRecord`.
+ *
+ * Governance context: this is the evidence trail an operator needs to answer
+ * "which agent, at which version, ran against which repo, and did it succeed?"
+ * — the kind of automated-decision logging the EU AI Act (Art. 12) expects of
+ * high-risk systems, kept tamper-evident so the log itself can be trusted.
+ */
+/** First record's `prevHash` — a fixed anchor so the chain has a root. */
+export declare const GENESIS_HASH = "GENESIS";
+/** A run's outcome, derived from its process exit code. */
+export type AuditOutcome = 'ok' | 'fail';
+/** One immutable audit record. `hash` seals every other field, `prevHash` included. */
+export interface AuditRecord {
+    ts: string;
+    agent: string;
+    version: string;
+    repo: string;
+    mode: string;
+    outcome: AuditOutcome;
+    exit: number;
+    prevHash: string;
+    hash: string;
+}
+/** The caller-supplied fields — the chain fields (`prevHash`/`hash`) are computed here. */
+export type AuditEntry = Omit<AuditRecord, 'prevHash' | 'hash'>;
+/**
+ * Absolute path to the append-only audit log. Lives under `.history/` — the
+ * durable-but-machine-local runtime bucket that is gitignored and never synced
+ * by `agents repo push/pull`. Keeping it here (not under a top-level, tracked
+ * `~/.agents/` path) means the token-bearing `repo` field can never leak into a
+ * version-controlled DotAgents repo, and no cross-machine pull can fork the chain.
+ */
+export declare function getAuditLogPath(): string;
+/**
+ * Append one record to the hash chain and return it. Links to the previous
+ * record's `hash` (or `GENESIS_HASH` for the first), computes the sealing
+ * hash, and writes a single JSONL line. Synchronous so the record is durable
+ * before the caller proceeds.
+ *
+ * Read-last-hash + append run under the canonical advisory file lock
+ * (`withFileLock`, backed by proper-lockfile). Without it, two concurrent
+ * writers — the norm under parallel teams/routines dispatch — both read the
+ * same last hash and both write `prevHash=H`, forking the chain into a false
+ * "tampered" verdict. The lock forces a total order so every record links off
+ * the genuinely-previous one. `ensureLockTarget` creates the file first because
+ * proper-lockfile locks an existing path.
+ */
+export declare function appendAuditRecord(entry: AuditEntry, logPath?: string): AuditRecord;
+/**
+ * Walk the chain and confirm every record reproduces. A record is valid when
+ * (a) its `prevHash` matches the prior record's `hash` (GENESIS for the first)
+ * AND (b) recomputing its sealing hash from its own fields reproduces the
+ * stored `hash`. Returns the first failing index in `brokenAt`.
+ */
+export declare function verifyAuditChain(logPath?: string): {
+    ok: boolean;
+    brokenAt?: number;
+};
+/** Read the whole chain, oldest-first. Exposed for `agents audit list`. */
+export declare function readAuditLog(logPath?: string): AuditRecord[];
+/**
+ * Record ONE dispatched run at the single exec chokepoint. Non-fatal by
+ * contract: any failure is caught and warned, never thrown — an audit-log
+ * hiccup must not crash a run that already finished.
+ */
+export declare function recordDispatchedRun(run: {
+    agent: string;
+    version: string;
+    mode: string;
+    cwd: string;
+    exitCode: number;
+}): void;

package/dist/lib/audit/log.js

@@ -0,0 +1,177 @@
+/**
+ * Cross-agent, tamper-evident audit log of every dispatched run (issue #347).
+ *
+ * Every run that reaches the single dispatch chokepoint in `agents run`
+ * (src/commands/exec.ts) appends ONE record here. Records form a hash chain:
+ * each record embeds the previous record's `hash` as `prevHash`, and its own
+ * `hash` is `sha256(canonicalJSON(record-without-hash))`. Because `prevHash`
+ * is part of the hashed payload, rewriting or reordering any record breaks the
+ * chain from that point forward — `verifyAuditChain()` reports the first index
+ * that fails to reproduce.
+ *
+ * Storage is append-only JSONL under the durable-runtime bucket
+ * (`~/.agents/.history/audit/log.jsonl`), one record per line. `.history/` is
+ * machine-local, gitignored, and NEVER synced by `agents repo push/pull` — so
+ * the `repo` field (a git remote url that can embed an access token) never
+ * lands in a version-controlled DotAgents repo, and a cross-machine pull can't
+ * splice a foreign chain into this one. The write path is deliberately cheap
+ * and non-fatal: a logging failure must never crash a run (see
+ * `recordDispatchedRun`). Concurrent writers (parallel teams/routines dispatch)
+ * are serialized by an advisory lock file so the chain never forks — see
+ * `appendAuditRecord`.
+ *
+ * Governance context: this is the evidence trail an operator needs to answer
+ * "which agent, at which version, ran against which repo, and did it succeed?"
+ * — the kind of automated-decision logging the EU AI Act (Art. 12) expects of
+ * high-risk systems, kept tamper-evident so the log itself can be trusted.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { sha256 } from '../staleness/fingerprint.js';
+import { getHistoryDir } from '../state.js';
+import { ensureLockTarget, withFileLock } from '../fs-atomic.js';
+/** First record's `prevHash` — a fixed anchor so the chain has a root. */
+export const GENESIS_HASH = 'GENESIS';
+/**
+ * Absolute path to the append-only audit log. Lives under `.history/` — the
+ * durable-but-machine-local runtime bucket that is gitignored and never synced
+ * by `agents repo push/pull`. Keeping it here (not under a top-level, tracked
+ * `~/.agents/` path) means the token-bearing `repo` field can never leak into a
+ * version-controlled DotAgents repo, and no cross-machine pull can fork the chain.
+ */
+export function getAuditLogPath() {
+    return path.join(getHistoryDir(), 'audit', 'log.jsonl');
+}
+/**
+ * Deterministic JSON: object keys sorted recursively so the same logical
+ * record always serializes to the same bytes (hashing must be reproducible
+ * across processes and machines). Values here are all primitives, but the
+ * recursion keeps it correct if the record ever nests.
+ */
+function canonicalJSON(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonicalJSON).join(',') + ']';
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalJSON(obj[k])).join(',') + '}';
+}
+/** Compute the sealing hash for a record whose `prevHash` is already set. */
+function hashRecord(record) {
+    return sha256(canonicalJSON(record));
+}
+/** Read + parse every record in the log, oldest-first. Missing file → []. */
+function readRecords(logPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(logPath, 'utf-8');
+    }
+    catch {
+        return []; // no log yet
+    }
+    const records = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        records.push(JSON.parse(trimmed));
+    }
+    return records;
+}
+/**
+ * Append one record to the hash chain and return it. Links to the previous
+ * record's `hash` (or `GENESIS_HASH` for the first), computes the sealing
+ * hash, and writes a single JSONL line. Synchronous so the record is durable
+ * before the caller proceeds.
+ *
+ * Read-last-hash + append run under the canonical advisory file lock
+ * (`withFileLock`, backed by proper-lockfile). Without it, two concurrent
+ * writers — the norm under parallel teams/routines dispatch — both read the
+ * same last hash and both write `prevHash=H`, forking the chain into a false
+ * "tampered" verdict. The lock forces a total order so every record links off
+ * the genuinely-previous one. `ensureLockTarget` creates the file first because
+ * proper-lockfile locks an existing path.
+ */
+export function appendAuditRecord(entry, logPath = getAuditLogPath()) {
+    ensureLockTarget(logPath);
+    return withFileLock(logPath, () => {
+        const existing = readRecords(logPath);
+        const prevHash = existing.length ? existing[existing.length - 1].hash : GENESIS_HASH;
+        const unsealed = { ...entry, prevHash };
+        const record = { ...unsealed, hash: hashRecord(unsealed) };
+        fs.appendFileSync(logPath, JSON.stringify(record) + '\n');
+        return record;
+    });
+}
+/**
+ * Walk the chain and confirm every record reproduces. A record is valid when
+ * (a) its `prevHash` matches the prior record's `hash` (GENESIS for the first)
+ * AND (b) recomputing its sealing hash from its own fields reproduces the
+ * stored `hash`. Returns the first failing index in `brokenAt`.
+ */
+export function verifyAuditChain(logPath = getAuditLogPath()) {
+    let records;
+    try {
+        records = readRecords(logPath);
+    }
+    catch (err) {
+        // A line that won't even parse is itself tamper evidence — the log is corrupt.
+        return { ok: false, brokenAt: 0 };
+    }
+    let expectedPrev = GENESIS_HASH;
+    for (let i = 0; i < records.length; i++) {
+        const r = records[i];
+        if (r.prevHash !== expectedPrev)
+            return { ok: false, brokenAt: i };
+        const { hash, ...unsealed } = r;
+        if (hashRecord(unsealed) !== hash)
+            return { ok: false, brokenAt: i };
+        expectedPrev = r.hash;
+    }
+    return { ok: true };
+}
+/** Read the whole chain, oldest-first. Exposed for `agents audit list`. */
+export function readAuditLog(logPath = getAuditLogPath()) {
+    return readRecords(logPath);
+}
+/**
+ * Resolve a stable repo label for a run: the git remote origin url when the
+ * cwd is inside a repo with one, otherwise the cwd itself. Best-effort — any
+ * failure falls back to the cwd.
+ */
+function repoLabel(cwd) {
+    try {
+        const res = spawnSync('git', ['-C', cwd, 'config', '--get', 'remote.origin.url'], {
+            encoding: 'utf-8',
+            timeout: 2000,
+        });
+        const url = res.status === 0 ? res.stdout.trim() : '';
+        return url || cwd;
+    }
+    catch {
+        return cwd;
+    }
+}
+/**
+ * Record ONE dispatched run at the single exec chokepoint. Non-fatal by
+ * contract: any failure is caught and warned, never thrown — an audit-log
+ * hiccup must not crash a run that already finished.
+ */
+export function recordDispatchedRun(run) {
+    try {
+        appendAuditRecord({
+            ts: new Date().toISOString(),
+            agent: run.agent,
+            version: run.version,
+            repo: repoLabel(run.cwd),
+            mode: run.mode,
+            outcome: run.exitCode === 0 ? 'ok' : 'fail',
+            exit: run.exitCode,
+        });
+    }
+    catch (err) {
+        process.stderr.write(`[agents] audit log write failed: ${err.message}\n`);
+    }
+}

package/dist/lib/auto-pull.js

@@ -14,6 +14,7 @@ import * as path from 'path';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { getFetchCacheDir } from './state.js';
+import { backgroundSpawnOptions } from './platform/process.js';
 /** Where lock files and per-repo status markers live. */
 function fetchStateDir() {
     return getFetchCacheDir();
@@ -38,7 +39,7 @@ export function spawnDetachedSync() {
         return;
     try {
         const child = spawn(process.execPath, [workerPath], {
-            detached: true,
+            ...backgroundSpawnOptions(),
             stdio: 'ignore',
             env: process.env,
         });

package/dist/lib/browser/chrome.d.ts

@@ -36,6 +36,16 @@ export declare function getRunningChromeInfo(profileName: string): {
     pid: number;
     port: number;
 } | null;
+/**
+ * Is a TCP port currently bound? `lsof` on POSIX, `netstat -ano` on Windows
+ * (lsof doesn't exist there). Returns false on any tooling error so port
+ * allocation degrades to "assume free" rather than throwing.
+ *
+ * Exported as the canonical cross-platform probe — `findFreeProfilePort`
+ * (profiles.ts) must use this rather than shelling out to lsof directly,
+ * or every port scans as free on Windows.
+ */
+export declare function isPortInUse(port: number): boolean;
 export declare function allocatePort(): number;
 export interface PortOccupant {
     pid: number;