@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/commands/watchdog.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `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 type { Command } from 'commander';
+/** Register the `agents watchdog` command tree. */
+export declare function registerWatchdogCommand(program: Command): void;

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,9 +51,11 @@ 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, 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';
+import { emit, redactArgs } from './lib/events.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
 // `agents __shim <agent>[@version] <raw args>`. Intercept here, before commander
 // parses anything, so the agent's own flags (`--help`, `--version`, etc.) pass
@@ -75,6 +77,56 @@ program
     .version(VERSION)
     .helpOption('-h, --help', 'Show help')
     .addHelpCommand(false);
+// ─── Audit backbone ────────────────────────────────────────────────────────────
+// One choke point logs every `agents <module> <cmd>` invocation to the structured
+// event log — so team create/disband, agent run, secrets access, and everything
+// else is captured generically (with SSH/remote-user attribution added in emit()),
+// no per-command wiring. `agents events` reads it back. Attached to the root
+// program, so it's inherited by every subcommand regardless of lazy registration.
+/** Command path from the acting command up to (but excluding) the `agents` root. */
+function auditCommandPath(cmd) {
+    const parts = [];
+    let c = cmd;
+    while (c && c.name() && c.name() !== 'agents') {
+        parts.unshift(c.name());
+        c = c.parent;
+    }
+    return parts;
+}
+const auditStarts = new WeakMap();
+program.hook('preAction', (_thisCommand, actionCommand) => {
+    try {
+        const parts = auditCommandPath(actionCommand);
+        if (parts.length === 0)
+            return;
+        auditStarts.set(actionCommand, Date.now());
+        emit('command.start', {
+            module: parts[0],
+            command: parts.join(' '),
+            args: redactArgs(actionCommand.args),
+            cwd: process.cwd(),
+        });
+    }
+    catch {
+        // Audit logging must never break command dispatch.
+    }
+});
+program.hook('postAction', (_thisCommand, actionCommand) => {
+    try {
+        const parts = auditCommandPath(actionCommand);
+        if (parts.length === 0)
+            return;
+        const started = auditStarts.get(actionCommand);
+        emit('command.end', {
+            module: parts[0],
+            command: parts.join(' '),
+            ...(started !== undefined ? { durationMs: Date.now() - started } : {}),
+        });
+    }
+    catch {
+        // Best-effort completion record; the start line is the durable audit fact.
+    }
+});
 // Custom help for the main program only
 const originalHelpInformation = program.helpInformation.bind(program);
 program.helpInformation = function () {
@@ -121,6 +173,7 @@ Run and dispatch:
   teams                           Coordinate multiple agents on shared work
   routines                        Run agents on a cron schedule (scheduler auto-starts)
   sessions                        Browse, search, and replay past runs (live-search in TTY; grouped by workspace)
+  logs [id]                       Show a run's log — host-dispatch task or session; -f to follow
   browser                         Automate a browser — navigate, click, screenshot, console, network
   pty                             Drive interactive terminal programs (REPLs, TUIs) via a persistent PTY session
 
@@ -130,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:
@@ -137,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)
@@ -175,41 +230,13 @@ async function showWhatsNew(fromVersion, toVersion) {
         const response = await fetch(`https://unpkg.com/@phnx-labs/agents-cli@${toVersion}/CHANGELOG.md`);
         if (!response.ok)
             return;
-        const changelog = await response.text();
-        const lines = changelog.split('\n');
-        const relevantChanges = [];
-        let inRelevantSection = false;
-        let currentVersion = '';
-        for (const line of lines) {
-            const versionMatch = line.match(/^## (\d+\.\d+\.\d+)/);
-            if (versionMatch) {
-                currentVersion = versionMatch[1];
-                // Only the range the user actually moved through: (fromVersion, toVersion].
-                // Bounding the top end matters when upgrading to a specific older
-                // version, and guards against a changelog that lists unreleased entries.
-                const inRange = compareVersions(currentVersion, fromVersion) > 0 &&
-                    compareVersions(currentVersion, toVersion) <= 0;
-                inRelevantSection = inRange;
-                if (inRelevantSection) {
-                    relevantChanges.push('');
-                    relevantChanges.push(chalk.bold(`v${currentVersion}`));
-                }
-                continue;
-            }
-            if (inRelevantSection && line.trim()) {
-                if (line.startsWith('**') && line.endsWith('**')) {
-                    relevantChanges.push(chalk.cyan(line.replace(/\*\*/g, '')));
-                }
-                else if (line.startsWith('- ')) {
-                    relevantChanges.push(chalk.gray(`  ${line}`));
-                }
-            }
-        }
+        const relevantChanges = renderWhatsNew(await response.text(), fromVersion, toVersion);
         if (relevantChanges.length > 0) {
             console.log(chalk.bold("\nWhat's new:\n"));
             for (const line of relevantChanges) {
                 console.log(line);
             }
+            console.log(chalk.gray('\nFull notes: https://github.com/phnx-labs/agents-cli/blob/main/CHANGELOG.md'));
             console.log();
         }
     }
@@ -764,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);
@@ -773,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);
@@ -782,9 +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');
@@ -956,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) {
@@ -989,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();
@@ -1009,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/agents.js

@@ -327,11 +327,16 @@ export const AGENTS = {
         commandsSubdir: 'commands',
         skillsDir: path.join(HOME, '.copilot', 'skills'),
         hooksDir: 'hooks',
+        // Copilot reads a plugin's manifest from the plugin ROOT (plugin.json),
+        // not `.claude-plugin/plugin.json`. Mirror it there. Verified against the
+        // GitHub Copilot CLI (1.0.56): `copilot plugin install` produces an
+        // installed plugin dir whose manifest sits at the root.
+        pluginManifestDir: '.',
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'auto', 'skip'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: true, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'auto', 'skip'] },
     },
     amp: {
         id: 'amp',
@@ -491,11 +496,26 @@ export const AGENTS = {
     // Install: `curl -fsSL https://app.factory.ai/cli | sh` (no npm package).
     // Binary is NOT in node_modules/.bin — the shim resolves the fixed install
     // path ~/.local/bin/droid directly (see the droid branch in shims.ts).
-    // Config: `~/.factory/` (settings.json, mcp.json, droids/, commands/).
-    // Memory: native AGENTS.md. Subagents = custom droids (top-level .md files
-    // in ~/.factory/droids/). Config isolation rides the ~/.factory symlink
-    // switch (no FACTORY_HOME env var exists). Headless: `droid exec "<prompt>"`
-    // with --auto low|medium|high, -o stream-json, -m <model>, -r <effort>.
+    // Config: `~/.factory/` (settings.json, mcp.json, droids/, commands/, hooks/,
+    // plugins/). Memory: native AGENTS.md. Subagents = custom droids (top-level
+    // .md files in ~/.factory/droids/). Config isolation rides the ~/.factory
+    // symlink switch (no FACTORY_HOME env var exists). Headless:
+    // `droid exec "<prompt>"` with --auto low|medium|high, -o stream-json,
+    // -m <model>, -r <effort>.
+    //
+    // Hooks: Claude-shaped. settings.json carries a top-level `hooks` object keyed
+    // by event (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart,
+    // SessionEnd, Stop, SubagentStop, Notification, PreCompact), each an array of
+    // `{ matcher?, hooks: [{ type: "command", command, timeout? }] }` matcher
+    // groups — verified against the droid binary's zod schema. So the Claude
+    // registrar is reused verbatim, just targeting `.factory/settings.json`.
+    //
+    // Plugins: native `droid plugin` command group + ~/.factory/plugins/ with the
+    // same marketplace layout Claude uses (known_marketplaces.json +
+    // marketplaces/<name>/plugins/<plugin>/). Droid's plugin manifest dir is
+    // `.factory-plugin/` (it also reads `.claude-plugin/` for compatibility) — set
+    // pluginManifestDir so syncPluginToVersion mirrors the manifest into it, the
+    // same pattern codex uses with `.codex-plugin`.
     droid: {
         id: 'droid',
         name: 'Droid',
@@ -509,20 +529,21 @@ export const AGENTS = {
         commandsSubdir: 'commands',
         skillsDir: '', // no skills concept
         hooksDir: 'hooks',
+        pluginManifestDir: '.factory-plugin',
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
-        supportsHooks: false,
+        supportsHooks: true,
         // Factory Droid Computers (cloud VMs) reached via `droid computer ssh` +
         // remote headless `droid exec`.
         cloudProvider: 'factory',
         capabilities: {
-            hooks: false,
+            hooks: true,
             mcp: true,
             allowlist: false,
             skills: false,
             commands: true,
-            plugins: false,
+            plugins: true,
             subagents: true,
             rules: { file: 'AGENTS.md' },
             workflows: false,

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;