@phnx-labs/agents-cli 1.20.5 → 1.20.7

package/dist/lib/pty-server.js

@@ -15,6 +15,7 @@ import * as crypto from 'crypto';
 import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { getPtyDir as getPtyDirRoot } from './state.js';
+import { isAlive } from './platform/index.js';
 /**
  * Capture a stable identifier for a process at the moment it was started.
  * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
@@ -52,6 +53,7 @@ export function captureProcessStartTime(pid) {
     }
 }
 // --- Constants ---
+const IS_WINDOWS = process.platform === 'win32';
 const SENTINEL = '__AGENTS_PTY_DONE__';
 const SOCKET_NAME = 'pty.sock';
 const PID_FILE = 'pty.pid';
@@ -72,24 +74,81 @@ const PTY_ENV_ALLOWLIST = [
     'EDITOR', 'VISUAL', 'PAGER', 'LESS',
     'NO_COLOR', 'FORCE_COLOR',
 ];
+/**
+ * Windows allowlist. cmd.exe / PowerShell refuse to start (or misbehave) without
+ * SystemRoot, ComSpec, PATHEXT and the USERPROFILE/APPDATA family, so a Unix-style
+ * allowlist would spawn a broken shell. PATH/TERM/color/NODE vars are shared with
+ * the Unix list; the rest are Windows-specific.
+ */
+const PTY_ENV_ALLOWLIST_WIN = [
+    'SystemRoot', 'SystemDrive', 'windir', 'ComSpec', 'PATH', 'PATHEXT',
+    'TEMP', 'TMP', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'HOME',
+    'APPDATA', 'LOCALAPPDATA', 'PROGRAMFILES', 'PROGRAMDATA',
+    'USERNAME', 'USERDOMAIN', 'COMPUTERNAME', 'OS',
+    'PROCESSOR_ARCHITECTURE', 'NUMBER_OF_PROCESSORS',
+    'TERM', 'COLORTERM', 'NO_COLOR', 'FORCE_COLOR',
+    'NODE_PATH', 'BUN_INSTALL',
+];
 function buildPtyEnv() {
     const env = {};
-    for (const key of PTY_ENV_ALLOWLIST) {
+    const allowlist = IS_WINDOWS ? PTY_ENV_ALLOWLIST_WIN : PTY_ENV_ALLOWLIST;
+    for (const key of allowlist) {
         const v = process.env[key];
         if (v !== undefined)
             env[key] = v;
     }
     return env;
 }
+/**
+ * Wrap a user command so a `__SENTINEL__:<exit>` line is printed after it
+ * finishes — that line drives completion detection in the exec/read flow.
+ * The separator and exit-code variable are shell-family specific:
+ *   POSIX sh/zsh/bash : `cmd; echo "S:$?"`
+ *   PowerShell        : `cmd; echo "S:$LASTEXITCODE"`
+ *   cmd.exe           : `cmd & echo S:%errorlevel%`  (`&` always runs the echo)
+ * Only the completion marker matters; the numeric exit code is informational
+ * (the authoritative code comes from node-pty's onExit).
+ */
+export function buildSentinelCommand(shell, command) {
+    // Split on both separators: a Windows shell path (`C:\…\cmd.exe`) must be
+    // recognized even when this code runs under POSIX path.basename, which does
+    // not treat `\` as a separator.
+    const name = (shell.split(/[\\/]/).pop() || shell).toLowerCase();
+    if (name === 'cmd.exe' || name === 'cmd') {
+        return `${command} & echo ${SENTINEL}:%errorlevel%`;
+    }
+    if (name === 'powershell.exe' || name === 'powershell' || name === 'pwsh.exe' || name === 'pwsh') {
+        return `${command}; echo "${SENTINEL}:$LASTEXITCODE"`;
+    }
+    return `${command}; echo "${SENTINEL}:$?"`;
+}
 /** Get the PTY helper directory, creating it if needed. */
 function getPtyDir() {
     const dir = getPtyDirRoot();
     fs.mkdirSync(dir, { recursive: true });
     return dir;
 }
-/** Get the unix socket path for the PTY server. */
+/**
+ * Resolve the IPC endpoint for a given platform + PTY scratch dir. Pure so both
+ * branches are testable without stubbing process.platform.
+ *
+ * Unix: an AF_UNIX socket file inside the scratch dir.
+ * Windows: a named pipe (`\\.\pipe\…`). Named pipes are NOT filesystem objects,
+ * so the name is derived from a hash of the (per-user) scratch dir to keep it
+ * stable across invocations and isolated per user — and callers must never probe
+ * it with fs.existsSync (it always reports false). Both forms are accepted by
+ * net.createServer/createConnection.
+ */
+export function derivePtyEndpoint(platform, ptyDir) {
+    if (platform === 'win32') {
+        const hash = crypto.createHash('sha1').update(ptyDir).digest('hex').slice(0, 16);
+        return `\\\\.\\pipe\\agents-pty-${hash}`;
+    }
+    return path.join(ptyDir, SOCKET_NAME);
+}
+/** Get the IPC endpoint the PTY server listens on / clients connect to. */
 export function getSocketPath() {
-    return path.join(getPtyDir(), SOCKET_NAME);
+    return derivePtyEndpoint(process.platform, getPtyDir());
 }
 /** Get the path to the PTY server PID file. */
 export function getPtyPidPath() {
@@ -109,16 +168,17 @@ export function isPtyServerRunning() {
         const pid = parseInt(fs.readFileSync(pidPath, 'utf-8').trim(), 10);
         if (isNaN(pid))
             return false;
-        process.kill(pid, 0);
-        return true;
+        if (isAlive(pid))
+            return true;
     }
     catch {
-        try {
-            fs.unlinkSync(pidPath);
-        }
-        catch { }
-        return false;
+        // read failed — fall through and treat the pid file as stale
     }
+    try {
+        fs.unlinkSync(pidPath);
+    }
+    catch { }
+    return false;
 }
 // --- Logging ---
 function rotateLogsIfNeeded(logPath) {
@@ -155,14 +215,17 @@ export async function runPtyServer() {
     let nodePty;
     let XtermTerminal;
     try {
-        nodePty = await import('node-pty');
+        // The Homebridge multiarch fork of node-pty: API-identical (same 1.x N-API
+        // codebase) but ships prebuilt binaries for Linux glibc + musl, x64 + arm64
+        // (plus macOS/Windows), so no compiler is needed on Linux/Alpine/arm64.
+        nodePty = await import('@homebridge/node-pty-prebuilt-multiarch');
         // Handle ESM default export
         if (nodePty.default?.spawn)
             nodePty = nodePty.default;
         // Ensure spawn-helper is executable (bun install doesn't set +x on prebuilds)
         try {
             const __dirname = path.dirname(fileURLToPath(import.meta.url));
-            const ptyBase = path.resolve(__dirname, '..', '..', 'node_modules', 'node-pty');
+            const ptyBase = path.resolve(__dirname, '..', '..', 'node_modules', '@homebridge', 'node-pty-prebuilt-multiarch');
             const helpers = [
                 path.join(ptyBase, 'prebuilds', `${process.platform}-${process.arch}`, 'spawn-helper'),
                 path.join(ptyBase, 'build', 'Release', 'spawn-helper'),
@@ -176,8 +239,8 @@ export async function runPtyServer() {
         catch { }
     }
     catch (err) {
-        console.error('node-pty is required for PTY support.');
-        console.error('Install: cd ' + '~/agents-cli && bun add node-pty');
+        console.error('node-pty (@homebridge/node-pty-prebuilt-multiarch) is required for PTY support.');
+        console.error('Install: bun add @homebridge/node-pty-prebuilt-multiarch');
         process.exit(1);
     }
     try {
@@ -218,8 +281,10 @@ export async function runPtyServer() {
         fs.unlinkSync(pidPath);
     }
     catch { } });
-    // Remove stale socket from a prior crashed server. Safe now that we hold the PID slot.
-    if (fs.existsSync(socketPath)) {
+    // Remove stale socket from a prior crashed server. Safe now that we hold the PID
+    // slot. Windows named pipes are not filesystem inodes — they vanish with their
+    // owning process, so there's nothing to unlink (and existsSync always reports false).
+    if (!IS_WINDOWS && fs.existsSync(socketPath)) {
         try {
             fs.unlinkSync(socketPath);
         }
@@ -283,8 +348,10 @@ export async function runPtyServer() {
             case 'start': {
                 const rows = req.params?.rows || 24;
                 const cols = req.params?.cols || 120;
-                const shell = req.params?.shell || process.env.SHELL || 'zsh';
-                const cwd = req.params?.cwd || process.env.HOME || '/';
+                const shell = req.params?.shell
+                    || (IS_WINDOWS ? (process.env.ComSpec || 'powershell.exe') : (process.env.SHELL || 'zsh'));
+                const cwd = req.params?.cwd
+                    || (IS_WINDOWS ? (process.env.USERPROFILE || process.env.HOME || process.cwd()) : (process.env.HOME || '/'));
                 const id = generateId();
                 let ptyProcess;
                 try {
@@ -355,7 +422,9 @@ export async function runPtyServer() {
                 session.appActive = true;
                 session.activeCommand = command;
                 session.pendingOutput = '';
-                session.pty.write(`${command}; echo "${SENTINEL}:$?"\n`);
+                // Windows conpty submits on CR; POSIX line discipline expects LF.
+                const submit = IS_WINDOWS ? '\r' : '\n';
+                session.pty.write(`${buildSentinelCommand(session.shell, command)}${submit}`);
                 session.lastActivity = Date.now();
                 return { ok: true, submitted: true };
             }
@@ -522,20 +591,28 @@ export async function runPtyServer() {
     // any local user with execute on the parent dir could connect to the socket
     // during the listen()-to-chmod() window. macOS BSD AF_UNIX semantics make
     // socket mode advisory only, so the parent dir is the real boundary.
+    //
+    // On Windows the transport is a named pipe, not a filesystem inode: chmod/umask
+    // are no-ops (and umask throws in some Node builds), and pipe ACLs default to
+    // the creating user. So we skip the Unix hardening entirely there.
     const agentsDir = getPtyDirRoot();
     fs.mkdirSync(agentsDir, { recursive: true });
-    fs.chmodSync(agentsDir, 0o700);
-    // umask covers any inherited group/other bits while listen() is creating
-    // the socket inode — it only matters for the unobservable instant before
-    // we can chmod the inode itself.
-    process.umask(0o077);
+    if (!IS_WINDOWS) {
+        fs.chmodSync(agentsDir, 0o700);
+        // umask covers any inherited group/other bits while listen() is creating
+        // the socket inode — it only matters for the unobservable instant before
+        // we can chmod the inode itself.
+        process.umask(0o077);
+    }
     await new Promise((resolve) => {
         server.listen(socketPath, () => resolve());
     });
     // Surface chmod failures: a 0o600 socket is a load-bearing security
     // assumption, not a nice-to-have. If we can't lock it down, refuse to
-    // start so the caller learns immediately.
-    fs.chmodSync(socketPath, 0o600);
+    // start so the caller learns immediately. (No-op on Windows named pipes.)
+    if (!IS_WINDOWS) {
+        fs.chmodSync(socketPath, 0o600);
+    }
     log('INFO', `PTY server started (PID: ${process.pid}, socket: ${socketPath})`);
     // Shutdown handler
     function shutdown() {
@@ -546,10 +623,13 @@ export async function runPtyServer() {
         sessions.clear();
         clearInterval(cleanupInterval);
         server.close();
-        try {
-            fs.unlinkSync(socketPath);
+        // Named pipes are reclaimed by the OS on close; only Unix sockets leave a file.
+        if (!IS_WINDOWS) {
+            try {
+                fs.unlinkSync(socketPath);
+            }
+            catch { }
         }
-        catch { }
         try {
             fs.unlinkSync(getPtyPidPath());
         }

package/dist/lib/resources/rules.js

@@ -9,9 +9,9 @@
  * - All unique subrules across layers are unioned
  */
 import * as fs from 'fs';
+import { agentConfigDirName } from '../agents.js';
 import * as path from 'path';
 import { getSystemRulesDir, getUserRulesDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
-import { agentConfigDirName } from '../agents.js';
 const SUBRULES_DIR = 'subrules';
 const SUBRULES_README = 'README.md';
 /**

package/dist/lib/resources/skills.js

@@ -5,10 +5,10 @@
  * Format is the same for all agents. Resolution order: project > user > system.
  */
 import * as fs from 'fs';
+import { agentConfigDirName } from '../agents.js';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { getSystemSkillsDir, getUserSkillsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
-import { agentConfigDirName } from '../agents.js';
 /** Default provider uses the real state module. */
 const defaultProvider = {
     getSystemSkillsDir,

package/dist/lib/resources.d.ts

@@ -36,6 +36,8 @@ export interface ResourceEntry {
     name: string;
     path: string;
     scope: 'user' | 'project';
+    /** One-line description pulled from frontmatter; not all resource kinds have one. */
+    description?: string;
 }
 /** A skill resource entry with optional rule count. */
 export interface SkillResourceEntry extends ResourceEntry {

package/dist/lib/resources.js

@@ -106,7 +106,7 @@ export function getAgentResources(agentId, options = {}) {
     const commands = [];
     for (const cmd of listInstalledCommandsWithScope(agentId, cwd, { home })) {
         if (shouldInclude(cmd.scope)) {
-            commands.push({ name: cmd.name, path: cmd.path, scope: cmd.scope });
+            commands.push({ name: cmd.name, path: cmd.path, scope: cmd.scope, description: cmd.description });
         }
     }
     // Skills
@@ -119,6 +119,7 @@ export function getAgentResources(agentId, options = {}) {
                 path: skill.path,
                 scope: skill.scope,
                 ruleCount: skill.ruleCount,
+                description: skill.metadata.description || undefined,
             });
         }
     }

package/dist/lib/rotate.js

@@ -6,10 +6,10 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import * as yaml from 'yaml';
 import { getAccountInfo } from './agents.js';
-import { readMeta, writeMeta, getHelpersDir, getUserAgentsDir } from './state.js';
+import { readMeta, writeMeta, getHelpersDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
+import { getProjectRunConfigs } from './run-config.js';
 import { getUsageInfoByIdentity, getUsageLookupKey, } from './usage.js';
 function getRotateDir() {
     const dir = path.join(getHelpersDir(), 'rotate');
@@ -33,22 +33,10 @@ export function normalizeRunStrategy(value) {
 }
 /** Read project-local run strategy from the nearest agents.yaml, if present. */
 export function getProjectRunStrategy(agent, startPath) {
-    let dir = path.resolve(startPath);
-    const userAgentsYaml = path.join(getUserAgentsDir(), 'agents.yaml');
-    while (dir !== path.dirname(dir)) {
-        const manifestPath = path.join(dir, 'agents.yaml');
-        if (manifestPath !== userAgentsYaml && fs.existsSync(manifestPath)) {
-            try {
-                const parsed = yaml.parse(fs.readFileSync(manifestPath, 'utf-8'));
-                const strategy = normalizeRunStrategy(parsed?.run?.[agent]?.strategy);
-                if (strategy)
-                    return strategy;
-            }
-            catch {
-                // Ignore malformed project config and keep walking, matching version resolution.
-            }
-        }
-        dir = path.dirname(dir);
+    for (const runConfig of getProjectRunConfigs(startPath)) {
+        const strategy = normalizeRunStrategy(runConfig[agent]?.strategy);
+        if (strategy)
+            return strategy;
     }
     return null;
 }

package/dist/lib/run-config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Project-local `run:` config discovery.
+ *
+ * The user/system `agents.yaml` is read through state.ts. Project-local
+ * agents.yaml files are discovered from the current working directory upward.
+ */
+import type { RunConfig } from './types.js';
+/** Return project-local run configs from nearest directory upward. */
+export declare function getProjectRunConfigs(startPath?: string): RunConfig[];

package/dist/lib/run-config.js

@@ -0,0 +1,35 @@
+/**
+ * Project-local `run:` config discovery.
+ *
+ * The user/system `agents.yaml` is read through state.ts. Project-local
+ * agents.yaml files are discovered from the current working directory upward.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getUserAgentsDir } from './state.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Return project-local run configs from nearest directory upward. */
+export function getProjectRunConfigs(startPath = process.cwd()) {
+    const configs = [];
+    let dir = path.resolve(startPath);
+    const userAgentsYaml = path.join(getUserAgentsDir(), 'agents.yaml');
+    while (dir !== path.dirname(dir)) {
+        const manifestPath = path.join(dir, 'agents.yaml');
+        if (manifestPath !== userAgentsYaml && fs.existsSync(manifestPath)) {
+            try {
+                const parsed = yaml.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                if (isRecord(parsed?.run)) {
+                    configs.push(parsed.run);
+                }
+            }
+            catch {
+                // Ignore malformed project config and keep walking.
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    return configs;
+}

package/dist/lib/run-defaults.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Selector-based defaults for `agents run`.
+ *
+ * Stored under agents.yaml:
+ *
+ *   run:
+ *     defaults:
+ *       "claude:*":
+ *         mode: auto
+ *         model: opus
+ *       "claude:2.1.45":
+ *         mode: plan
+ */
+import type { AgentId, Mode, RunConfig, RunDefaults } from './types.js';
+export interface ParsedRunDefaultSelector {
+    agent: AgentId;
+    version: string;
+    selector: string;
+}
+export interface ResolvedRunDefaults extends RunDefaults {
+    sources: {
+        mode?: string;
+        model?: string;
+    };
+}
+export interface RunDefaultEntry {
+    selector: string;
+    defaults: RunDefaults;
+}
+type RunDefaultsInput = {
+    mode?: unknown;
+    model?: unknown;
+};
+export declare function normalizeRunDefaultMode(input: string): Mode;
+export declare function parseRunDefaultSelector(input: string): ParsedRunDefaultSelector;
+export declare function resolveRunDefaultsFromConfig(runConfig: RunConfig | undefined, agent: AgentId, version?: string | null): ResolvedRunDefaults;
+export declare function resolveRunDefaultsFromConfigs(runConfigs: Array<RunConfig | undefined>, agent: AgentId, version?: string | null): ResolvedRunDefaults;
+export declare function resolveRunDefaults(agent: AgentId, version?: string | null, startPath?: string): ResolvedRunDefaults;
+export declare function listRunDefaults(): RunDefaultEntry[];
+export declare function setRunDefault(selectorInput: string, defaultsInput: RunDefaultsInput): RunDefaultEntry;
+export declare function unsetRunDefault(selectorInput: string): boolean;
+export {};

package/dist/lib/run-defaults.js

@@ -0,0 +1,180 @@
+/**
+ * Selector-based defaults for `agents run`.
+ *
+ * Stored under agents.yaml:
+ *
+ *   run:
+ *     defaults:
+ *       "claude:*":
+ *         mode: auto
+ *         model: opus
+ *       "claude:2.1.45":
+ *         mode: plan
+ */
+import { ALL_MODES } from './types.js';
+import { AGENTS } from './agents.js';
+import { readMeta, updateMeta } from './state.js';
+import { getProjectRunConfigs } from './run-config.js';
+const VERSION_RE = /^(?:\*|latest|(?!.*\.\.)[A-Za-z0-9._+-]{1,64})$/;
+function isAgentId(value) {
+    return value in AGENTS;
+}
+export function normalizeRunDefaultMode(input) {
+    const mode = input.trim().toLowerCase();
+    if (mode === 'full')
+        return 'skip';
+    if (ALL_MODES.includes(mode))
+        return mode;
+    throw new Error(`Invalid mode '${input}'. Use one of: ${ALL_MODES.join(', ')} (or 'full' as an alias for 'skip').`);
+}
+function normalizeRunDefaults(defaults, selector) {
+    const out = {};
+    if (defaults.mode !== undefined) {
+        if (typeof defaults.mode !== 'string') {
+            throw new Error(`Invalid mode in run.defaults.${selector}: expected a string.`);
+        }
+        out.mode = normalizeRunDefaultMode(defaults.mode);
+    }
+    if (defaults.model !== undefined) {
+        if (typeof defaults.model !== 'string' || defaults.model.trim() === '') {
+            throw new Error(`Invalid model in run.defaults.${selector}: expected a non-empty string.`);
+        }
+        out.model = defaults.model.trim();
+    }
+    return out;
+}
+export function parseRunDefaultSelector(input) {
+    const raw = input.trim();
+    if (!raw)
+        throw new Error('Selector is required. Use <agent>:<version>, <agent>@<version>, or <agent>:*.');
+    let agentPart;
+    let versionPart;
+    if (raw.includes('@')) {
+        const parts = raw.split('@');
+        if (parts.length !== 2)
+            throw new Error(`Invalid selector '${input}'. Use <agent>@<version>.`);
+        [agentPart, versionPart] = parts;
+    }
+    else if (raw.includes(':')) {
+        const idx = raw.indexOf(':');
+        agentPart = raw.slice(0, idx);
+        versionPart = raw.slice(idx + 1);
+    }
+    else {
+        agentPart = raw;
+        versionPart = '*';
+    }
+    const agent = agentPart.toLowerCase();
+    if (!isAgentId(agent)) {
+        throw new Error(`Invalid agent '${agentPart}'. Available agents: ${Object.keys(AGENTS).join(', ')}.`);
+    }
+    if (!VERSION_RE.test(versionPart)) {
+        throw new Error(`Invalid selector version '${versionPart}'. Use *, latest, or [A-Za-z0-9._+-]{1,64}.`);
+    }
+    return {
+        agent,
+        version: versionPart,
+        selector: `${agent}:${versionPart}`,
+    };
+}
+function sortedDefaults(defaults) {
+    return Object.fromEntries(Object.entries(defaults).sort(([a], [b]) => a.localeCompare(b)));
+}
+export function resolveRunDefaultsFromConfig(runConfig, agent, version) {
+    const defaults = runConfig?.defaults ?? {};
+    const wildcardSelector = `${agent}:*`;
+    const exactSelector = version ? `${agent}:${version}` : null;
+    const resolved = { sources: {} };
+    const wildcard = defaults[wildcardSelector]
+        ? normalizeRunDefaults(defaults[wildcardSelector], wildcardSelector)
+        : null;
+    if (wildcard?.mode) {
+        resolved.mode = wildcard.mode;
+        resolved.sources.mode = wildcardSelector;
+    }
+    if (wildcard?.model) {
+        resolved.model = wildcard.model;
+        resolved.sources.model = wildcardSelector;
+    }
+    if (exactSelector && defaults[exactSelector]) {
+        const exact = normalizeRunDefaults(defaults[exactSelector], exactSelector);
+        if (exact.mode) {
+            resolved.mode = exact.mode;
+            resolved.sources.mode = exactSelector;
+        }
+        if (exact.model) {
+            resolved.model = exact.model;
+            resolved.sources.model = exactSelector;
+        }
+    }
+    return resolved;
+}
+export function resolveRunDefaultsFromConfigs(runConfigs, agent, version) {
+    const resolved = { sources: {} };
+    for (const runConfig of runConfigs) {
+        const next = resolveRunDefaultsFromConfig(runConfig, agent, version);
+        if (next.mode) {
+            resolved.mode = next.mode;
+            resolved.sources.mode = next.sources.mode;
+        }
+        if (next.model) {
+            resolved.model = next.model;
+            resolved.sources.model = next.sources.model;
+        }
+    }
+    return resolved;
+}
+export function resolveRunDefaults(agent, version, startPath = process.cwd()) {
+    const projectRunConfigs = getProjectRunConfigs(startPath).reverse();
+    return resolveRunDefaultsFromConfigs([readMeta().run, ...projectRunConfigs], agent, version);
+}
+export function listRunDefaults() {
+    const defaults = readMeta().run?.defaults ?? {};
+    return Object.entries(defaults)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([selector, value]) => ({
+        selector,
+        defaults: normalizeRunDefaults(value, selector),
+    }));
+}
+export function setRunDefault(selectorInput, defaultsInput) {
+    const parsed = parseRunDefaultSelector(selectorInput);
+    const defaults = normalizeRunDefaults(defaultsInput, parsed.selector);
+    if (!defaults.mode && !defaults.model) {
+        throw new Error('Set at least one default: --mode <mode> or --model <model>.');
+    }
+    updateMeta((meta) => {
+        const run = { ...(meta.run ?? {}) };
+        const currentDefaults = { ...(run.defaults ?? {}) };
+        currentDefaults[parsed.selector] = {
+            ...(currentDefaults[parsed.selector] ?? {}),
+            ...defaults,
+        };
+        run.defaults = sortedDefaults(currentDefaults);
+        return { ...meta, run };
+    });
+    return {
+        selector: parsed.selector,
+        defaults: {
+            ...(readMeta().run?.defaults?.[parsed.selector] ?? {}),
+        },
+    };
+}
+export function unsetRunDefault(selectorInput) {
+    const parsed = parseRunDefaultSelector(selectorInput);
+    let removed = false;
+    updateMeta((meta) => {
+        const run = { ...(meta.run ?? {}) };
+        const currentDefaults = { ...(run.defaults ?? {}) };
+        removed = Object.prototype.hasOwnProperty.call(currentDefaults, parsed.selector);
+        delete currentDefaults[parsed.selector];
+        if (Object.keys(currentDefaults).length > 0) {
+            run.defaults = sortedDefaults(currentDefaults);
+        }
+        else {
+            delete run.defaults;
+        }
+        return { ...meta, run };
+    });
+    return removed;
+}

package/dist/lib/secrets/install-helper.d.ts

@@ -12,10 +12,14 @@
  * modules in `src/lib/secrets/` must import `getKeychainHelperPath()` rather
  * than recomputing it.
  */
+/** Redirect the install root (test only). Returns the previous override so callers can restore. */
+export declare function setInstallRootForTest(dir: string | null): string | null;
 /**
  * Idempotent install. Copies the bundled `.app` to the stable user path. Skips
- * if the destination already exists and `codesign --verify` passes, unless
- * `forceReinstall=true`.
+ * if the destination already exists, `codesign --verify` passes, AND the
+ * installed executable matches the bundled one byte-for-byte — a valid
+ * signature alone is not enough, because an outdated helper signs clean too.
+ * `forceReinstall=true` skips all checks and always copies.
  *
  * Notarization is checked via `spctl --assess` after install — a failure is
  * logged as a warning but does NOT throw. Notarization checks require network
@@ -27,7 +31,11 @@ export declare function ensureKeychainHelperInstalled(opts?: {
 }): void;
 /**
  * Return the absolute path to the helper executable. If the installed bundle
- * is missing, performs a lazy install first.
+ * is missing, or is stale relative to the bundled source helper, performs a
+ * lazy (re)install first. The staleness check is what lets an upgraded CLI
+ * replace a helper a previous version installed — `agents helper install`
+ * never runs on `npm i -g`, so this call site is the only one every machine
+ * is guaranteed to pass through.
  *
  * Throws on non-darwin.
  */