@phnx-labs/agents-cli 1.20.50 → 1.20.51

package/dist/lib/cli-resources.js

@@ -21,6 +21,7 @@ import * as path from 'path';
 import { spawnSync } from 'child_process';
 import * as yaml from 'yaml';
 import { listResources, resolveResource } from './resources.js';
+import { composeWin32CommandLine } from './platform/index.js';
 // ─── Validation primitives ───────────────────────────────────────────────────
 /** Token allowed inside `check:` strings — letters, digits, underscore, dot, slash, dash. */
 const SAFE_CHECK_TOKEN = /^[a-zA-Z0-9_./-]+$/;
@@ -253,19 +254,27 @@ export function resolveCliManifest(name, cwd) {
 // ─── Host detection ──────────────────────────────────────────────────────────
 /**
  * Return true if a command resolves on the current PATH. Uses POSIX `command -v`
- * via spawn argv (no shell); results are cached for the lifetime of the process.
+ * (or `where` on Windows) via spawn argv (no shell); results are cached for the
+ * lifetime of the process.
  */
 const cmdExistsCache = new Map();
 export function hasCommand(cmd) {
     if (cmdExistsCache.has(cmd))
         return cmdExistsCache.get(cmd);
-    // `command` is a shell builtin on most POSIX shells; invoking `sh -c 'command -v X'`
-    // with X as an *argument* (not interpolated) is the safe path. `cmd` may be passed
-    // by callers that haven't validated it, so we route via argv to neutralize metas.
-    const result = spawnSync('sh', ['-c', 'command -v "$1" >/dev/null 2>&1', '_', cmd], {
-        stdio: 'ignore',
-    });
-    const ok = result.status === 0;
+    let ok;
+    if (process.platform === 'win32') {
+        // `sh` only exists when Git Bash is installed; `where` is the native PATH
+        // probe (resolves .exe/.cmd/.bat via PATHEXT). Argv keeps `cmd` uninterpolated.
+        ok = spawnSync('where', [cmd], { stdio: 'ignore' }).status === 0;
+    }
+    else {
+        // `command` is a shell builtin on most POSIX shells; invoking `sh -c 'command -v X'`
+        // with X as an *argument* (not interpolated) is the safe path. `cmd` may be passed
+        // by callers that haven't validated it, so we route via argv to neutralize metas.
+        ok = spawnSync('sh', ['-c', 'command -v "$1" >/dev/null 2>&1', '_', cmd], {
+            stdio: 'ignore',
+        }).status === 0;
+    }
     cmdExistsCache.set(cmd, ok);
     return ok;
 }
@@ -280,7 +289,19 @@ export function isCliInstalled(manifest) {
         return hasCommand(c.cmd);
     }
     const result = spawnSync(c.cmd, c.args, { stdio: 'ignore', timeout: 10_000 });
-    return result.status === 0;
+    if (result.status === 0)
+        return true;
+    // On Windows the PATH entry point is often a `.cmd`/`.bat` shim (npm installs,
+    // script installers), which Node refuses to spawn without a shell (ENOENT /
+    // EINVAL). A failed *spawn* — not a failed run — gets one retry through the
+    // shell, as a single pre-composed line (DEP0190-safe). Check tokens are
+    // SAFE_CHECK_TOKEN-validated at parse time, so the line cannot inject.
+    if (process.platform === 'win32' && result.error) {
+        const line = composeWin32CommandLine(c.cmd, c.args);
+        const retry = spawnSync(line, { stdio: 'ignore', timeout: 10_000, shell: true });
+        return retry.status === 0;
+    }
+    return false;
 }
 // ─── Method selection ────────────────────────────────────────────────────────
 /**
@@ -480,7 +501,3 @@ export function listCliStatus(cwd) {
     }));
     return { statuses, errors };
 }
-/** Names of CLIs that are declared but not currently installed on the host. */
-export function getMissingClis(cwd) {
-    return listCliStatus(cwd).statuses.filter((s) => !s.installed).map((s) => s.manifest);
-}

package/dist/lib/cloud/rush.d.ts

@@ -75,30 +75,6 @@ export declare function buildDispatchBody(input: {
      */
     images?: ImageAttachment[] | null;
 }): Record<string, unknown>;
-/** A single account registered in Rush Cloud's multi-account rotation pool. */
-export interface RemoteAccount {
-    id: string;
-    provider: string;
-    email: string | null;
-    subscription_type: string | null;
-    five_hour_pct: number | null;
-    seven_day_pct: number | null;
-    usage_fetched_at: string | null;
-    created_at: string;
-}
-/** Fetch all Claude accounts in this user's Rush Cloud rotation pool (no tokens). */
-export declare function listRemoteAccounts(): Promise<RemoteAccount[]>;
-/**
- * Register a CLAUDE_CODE_OAUTH_TOKEN with Rush Cloud's rotation pool.
- * The server validates the token against the Anthropic usage API and stores it
- * encrypted in Vault. Returns the account metadata (no token).
- */
-export declare function addRemoteAccount(provider: string, pastedToken: string): Promise<RemoteAccount & {
-    five_hour_pct: number | null;
-    seven_day_pct: number | null;
-}>;
-/** Remove a Claude account from Rush Cloud's rotation pool by its ID. */
-export declare function removeRemoteAccount(id: string): Promise<void>;
 export declare class RushCloudProvider implements CloudProvider {
     id: "rush";
     name: string;

package/dist/lib/cloud/rush.js

@@ -294,37 +294,6 @@ export function buildDispatchBody(input) {
     }
     return body;
 }
-/** Fetch all Claude accounts in this user's Rush Cloud rotation pool (no tokens). */
-export async function listRemoteAccounts() {
-    const token = readToken();
-    const res = await api('GET', '/api/v1/cloud-accounts', token);
-    if (!res.ok) {
-        throw new Error(`Failed to list accounts (${res.status}): ${sanitizeErrorBody(await res.text())}`);
-    }
-    const data = await res.json();
-    return data.accounts ?? [];
-}
-/**
- * Register a CLAUDE_CODE_OAUTH_TOKEN with Rush Cloud's rotation pool.
- * The server validates the token against the Anthropic usage API and stores it
- * encrypted in Vault. Returns the account metadata (no token).
- */
-export async function addRemoteAccount(provider, pastedToken) {
-    const token = readToken();
-    const res = await api('POST', '/api/v1/cloud-accounts', token, { provider, token: pastedToken });
-    if (!res.ok) {
-        throw new Error(`Failed to add account (${res.status}): ${sanitizeErrorBody(await res.text())}`);
-    }
-    return await res.json();
-}
-/** Remove a Claude account from Rush Cloud's rotation pool by its ID. */
-export async function removeRemoteAccount(id) {
-    const token = readToken();
-    const res = await api('DELETE', `/api/v1/cloud-accounts/${encodeURIComponent(id)}`, token);
-    if (!res.ok) {
-        throw new Error(`Failed to remove account (${res.status}): ${sanitizeErrorBody(await res.text())}`);
-    }
-}
 export class RushCloudProvider {
     id = 'rush';
     name = 'Rush Cloud';

package/dist/lib/crabbox/cli.js

@@ -209,7 +209,10 @@ export function crabboxRunScript(slug, script, opts = {}) {
 /** Release the lease / delete the box. Best-effort; never throws. */
 export function crabboxStop(slug, opts = {}) {
     try {
-        const r = spawnSync('crabbox', ['stop', '--id', slug], { encoding: 'utf-8', env: crabboxEnv(opts) });
+        // Positional target: crabbox's stop subcommand has no --id flag (unlike
+        // status/run/ssh) — `stop --id <slug>` dies with "flag provided but not
+        // defined: -id" and the box leaks past the run it was leased for.
+        const r = spawnSync('crabbox', ['stop', slug], { encoding: 'utf-8', env: crabboxEnv(opts) });
         return r.status === 0;
     }
     catch {

package/dist/lib/crabbox/lease.js

@@ -12,6 +12,34 @@ import { buildCredentialScript } from './runtimes.js';
 function q(s) {
     return "'" + s.replace(/'/g, "'\\''") + "'";
 }
+/**
+ * Bash snippet that guarantees `agents` is runnable on the box. Fresh crabbox
+ * images ship without node, and the box user may not own the global npm prefix,
+ * so everything installs user-level under ~/.local (node from the official
+ * latest-v22.x tarball to satisfy engines.node >=22.5.0). Exits 96 with a
+ * diagnostic when the CLI still isn't runnable — a silent `|| true` here used
+ * to surface only as `agents: command not found` deep in the script.
+ */
+const ENSURE_AGENTS_CLI = [
+    'export PATH="$HOME/.local/bin:$PATH"',
+    'if ! command -v node >/dev/null 2>&1; then',
+    '  case "$(uname -m)" in aarch64|arm64) narch=arm64;; *) narch=x64;; esac',
+    '  nver=$(curl -fsSL https://nodejs.org/dist/latest-v22.x/ | grep -oE "v22\\.[0-9]+\\.[0-9]+" | head -1)',
+    '  mkdir -p "$HOME/.local"',
+    '  curl -fsSL "https://nodejs.org/dist/latest-v22.x/node-$nver-linux-$narch.tar.xz" | tar -xJ -C "$HOME/.local" --strip-components=1',
+    'fi',
+    'if ! command -v agents >/dev/null 2>&1; then',
+    '  npm config set prefix "$HOME/.local" >/dev/null 2>&1 || true',
+    '  npm install -g @phnx-labs/agents-cli >/dev/null 2>&1',
+    'fi',
+    'if ! command -v agents >/dev/null 2>&1; then',
+    '  echo "lease bootstrap: agents-cli install failed (node: $(command -v node || echo missing))" >&2',
+    '  exit 96',
+    'fi',
+    // Same first-run guard the hosts bootstrap uses (hosts/ready.ts) — a fresh
+    // install refuses `agents run` with "agents-cli is not set up" until setup ran.
+    'if [ ! -d "$HOME/.agents/.system" ]; then agents setup >/dev/null 2>&1 || true; fi',
+].join('\n');
 /**
  * Build the single bootstrap script run on the box: ensure agents-cli, install
  * the picked runtime CLIs, write their credentials, run the agent, then shred
@@ -35,7 +63,7 @@ export function buildBootstrapScript(opts) {
     const installRuntimes = opts.runtimes.map((id) => `agents add ${q(id)} >/dev/null 2>&1 || true`).join('\n');
     return [
         'set -uo pipefail',
-        'if ! command -v agents >/dev/null 2>&1; then npm install -g @phnx-labs/agents-cli >/dev/null 2>&1 || true; fi',
+        ENSURE_AGENTS_CLI,
         installRuntimes,
         credScript,
         `${runParts.join(' ')}`,

package/dist/lib/daemon.js

@@ -393,6 +393,45 @@ export async function runDaemon() {
     };
     const healInterval = setInterval(() => { void runHealCheck(); }, 6 * 60 * 60_000);
     const healKickoff = setTimeout(() => { void runHealCheck(); }, 30_000);
+    // Auto-dispatch: for any managed project that has opted in (autoDispatch:true +
+    // maxAgents>0 in ~/.agents/factory/projects.json), pick up Linear tickets that
+    // are delegated to an agent and still in Todo, and DISPATCH each through
+    // agents-cli's own cloud-provider layer (resolveProvider().dispatch(), same as
+    // `agents cloud run`) — then mark it Doing so it isn't re-picked. Capped at
+    // maxAgents concurrent per project. No hidden Prix dependency: Rush is one
+    // provider among rush/codex/factory, pinned per-project via `provider`. OFF
+    // unless a project opts in; no opted-in project or no LINEAR_API_KEY is a clean
+    // no-op. Overlap-guarded like the probes above. ~every 3 min.
+    let autoDispatching = false;
+    const runAutoDispatch = async () => {
+        if (autoDispatching)
+            return;
+        autoDispatching = true;
+        try {
+            const { readAutoDispatchProjects, isEligible, autoDispatchTick } = await import('./auto-dispatch.js');
+            const projects = readAutoDispatchProjects();
+            if (!projects.some(isEligible))
+                return; // opt-in: nothing enabled → skip
+            const { createLinearGateway } = await import('./auto-dispatch-linear.js');
+            const linear = createLinearGateway();
+            if (!linear)
+                return; // no LINEAR_API_KEY configured → skip
+            const { createProviderDispatcher } = await import('./auto-dispatch-provider.js');
+            const dispatcher = createProviderDispatcher();
+            const dispatched = await autoDispatchTick({ projects, linear, dispatcher, log: (lvl, m) => log(lvl, m) });
+            if (dispatched.length) {
+                log('INFO', `auto-dispatch: started ${dispatched.length} delegated ticket(s): ${dispatched.map((d) => d.identifier).join(', ')}`);
+            }
+        }
+        catch (err) {
+            log('ERROR', `auto-dispatch failed: ${err.message}`);
+        }
+        finally {
+            autoDispatching = false;
+        }
+    };
+    const autoDispatchInterval = setInterval(() => { void runAutoDispatch(); }, 3 * 60_000);
+    const autoDispatchKickoff = setTimeout(() => { void runAutoDispatch(); }, 45_000);
     // Device probe: refresh registered devices' reachability and detect newly
     // appeared tailnet nodes, dropping a sentinel per pending device so the
     // menu-bar helper can surface "NEW DEVICES → Register / Ignore". Refresh mode
@@ -500,6 +539,8 @@ export async function runDaemon() {
         clearInterval(syncInterval);
         clearInterval(healInterval);
         clearTimeout(healKickoff);
+        clearInterval(autoDispatchInterval);
+        clearTimeout(autoDispatchKickoff);
         clearInterval(deviceProbeInterval);
         clearTimeout(deviceProbeKickoff);
         clearInterval(tmuxReconcileInterval);

package/dist/lib/exec.js

@@ -307,12 +307,12 @@ export const AGENT_COMMANDS = {
         promptFlag: 'positional',
         resume: { subcommand: 'resume' },
         modeFlags: {
-            // NOTE: codex has no read-only mode in --sandbox; 'plan' here means
-            // "workspace-write but no auto-approval" — closer to plan-as-restraint.
-            // True read-only requires --sandbox read-only which we haven't wired.
-            plan: ['--sandbox', 'workspace-write'],
-            edit: ['--sandbox', 'workspace-write', '--dangerously-bypass-approvals-and-sandbox'],
-            // skip drops the sandbox entirely; --dangerously-bypass-approvals-and-sandbox then approves anything.
+            plan: ['--sandbox', 'read-only'],
+            // Sandboxed writes inside the workspace. Network stays on (workspace-write
+            // disables it by default) so edit-mode runs can still use git/gh/package
+            // installs. No approval bypass here — only `skip` drops the guardrails.
+            edit: ['--sandbox', 'workspace-write', '-c', 'sandbox_workspace_write.network_access=true'],
+            // skip = codex --yolo: drops the sandbox entirely and approves anything.
             skip: ['--dangerously-bypass-approvals-and-sandbox'],
         },
         jsonFlags: ['--json'],
@@ -563,14 +563,25 @@ export function buildExecCommand(options) {
         throw new Error(`Internal error: ${options.agent} declares '${resolvedMode}' in capabilities.modes but has no entry in AGENT_COMMANDS.modeFlags.${resolvedMode}.`);
     }
     if (resumeSpec && 'subcommand' in resumeSpec) {
-        // codex `exec resume` / `resume` does NOT accept `--sandbox <mode>` (only the
-        // bypass flag, verified against `codex exec resume --help`). So the standard
-        // codex modeFlags can't be reused on resume. A non-plan HEADLESS resume needs
-        // the bypass or it stalls on approval prompts; plan and interactive resume
-        // inherit codex's default sandbox and pass no flag.
-        if (!interactive && resolvedMode !== 'plan') {
+        if (resolvedMode === 'skip') {
+            // skip = yolo on resume too; both `codex resume` (TUI) and
+            // `codex exec resume` accept the bypass flag.
             cmd.push('--dangerously-bypass-approvals-and-sandbox');
         }
+        else if (interactive) {
+            // `codex resume` (TUI) accepts the same -s/--sandbox flags as a fresh run.
+            cmd.push(...modeFlags);
+        }
+        else {
+            // `codex exec resume` rejects `--sandbox <mode>` (verified against
+            // `codex exec resume --help` on 0.142.5), but takes -c config overrides —
+            // map the mode through sandbox_mode so a non-skip resume never gets the
+            // approval/sandbox bypass.
+            cmd.push('-c', `sandbox_mode=${resolvedMode === 'plan' ? 'read-only' : 'workspace-write'}`);
+            if (resolvedMode !== 'plan') {
+                cmd.push('-c', 'sandbox_workspace_write.network_access=true');
+            }
+        }
     }
     else if (options.agent === 'kimi' && !interactive) {
         // kimi's headless prompt mode (`-p`/`--prompt`) is self-contained and REFUSES
@@ -659,8 +670,14 @@ export function buildExecCommand(options) {
             cmd.push(template.promptFlag, options.prompt);
         }
     }
-    // Claude-specific: add dirs
-    if (options.agent === 'claude' && options.addDirs) {
+    // Extra writable dirs. Claude and Codex both take `--add-dir`; for Codex it
+    // widens the workspace-write sandbox (teams relies on this to let teammates
+    // write ~/.agents), so it must actually be forwarded — it used to be
+    // claude-only, silently dropped for codex and masked by edit mode carrying
+    // the approval/sandbox bypass. Codex's resume forms reject --add-dir, so
+    // skip it there (claude's flag-based resume accepts it).
+    if (options.addDirs &&
+        (options.agent === 'claude' || (options.agent === 'codex' && !options.resume))) {
         for (const dir of options.addDirs) {
             cmd.push('--add-dir', dir);
         }

package/dist/lib/format.d.ts

@@ -0,0 +1,38 @@
+/** Print `msg` in red to stderr and exit the process with `code`. */
+export declare function die(msg: string, code?: number): never;
+/**
+ * Truncate `s` to at most `max` characters, appending a single-char ellipsis
+ * (`…`) when shortened. Character-count based (not ANSI/width aware — use
+ * `truncateToWidth` from `session/width.ts` for colored strings).
+ */
+export declare function truncate(s: string, max: number): string;
+/**
+ * Format an ISO timestamp as a compact relative age: "just now", "5m ago",
+ * "3h ago", "2d ago". The canonical short form — the long "5 minutes ago"
+ * variant that once lived in `cloud.ts` is deliberately dropped. (For the
+ * session-list long form with calendar fallback, see
+ * `formatRelativeTime` in `session/relative-time.ts`.)
+ */
+export declare function relTime(iso: string): string;
+/** Format a millisecond duration as "45s", "3m", "2h 5m", "1d 3h". */
+export declare function humanDuration(ms: number): string;
+/**
+ * Visible column width of `s`, ignoring ANSI SGR color codes (e.g. chalk
+ * wrappers). Matches the full CSI sequence including the `\x1b` escape.
+ */
+export declare function visibleWidth(s: string): number;
+/** Pad `s` with trailing spaces to a target character width. */
+export declare function padRight(s: string, width: number): string;
+/** Pad `s` with trailing spaces to a target *visible* width (ANSI-aware). */
+export declare function padVisible(s: string, width: number): string;
+/** True when `--json` was passed or stdout is not a TTY. */
+export declare function isJsonMode(opts: {
+    json?: boolean;
+}): boolean;
+/** Read all of stdin synchronously and return it UTF-8 decoded and trimmed. */
+export declare function readStdinSync(): string;
+/**
+ * Wrap `text` in an OSC 8 hyperlink to `filePath` (as a `file://` URL) when
+ * stdout is a TTY; otherwise return `text` unchanged.
+ */
+export declare function termLink(text: string, filePath: string): string;

package/dist/lib/format.js

@@ -0,0 +1,108 @@
+/**
+ * Shared terminal-formatting helpers.
+ *
+ * These small utilities were previously copy-pasted across ~20 command and lib
+ * files, and had drifted into behavior differences (truncation ellipsis `...`
+ * vs `…` vs `.`; `relTime` long "5 minutes ago" vs short "5m ago"; a
+ * `visibleWidth` regex missing its `\x1b` escape). This module is the single
+ * canonical home — every consumer imports from here.
+ */
+import chalk from 'chalk';
+import { readSync } from 'node:fs';
+/** Print `msg` in red to stderr and exit the process with `code`. */
+export function die(msg, code = 1) {
+    console.error(chalk.red(msg));
+    process.exit(code);
+}
+/**
+ * Truncate `s` to at most `max` characters, appending a single-char ellipsis
+ * (`…`) when shortened. Character-count based (not ANSI/width aware — use
+ * `truncateToWidth` from `session/width.ts` for colored strings).
+ */
+export function truncate(s, max) {
+    return s.length <= max ? s : s.slice(0, max - 1) + '…';
+}
+/**
+ * Format an ISO timestamp as a compact relative age: "just now", "5m ago",
+ * "3h ago", "2d ago". The canonical short form — the long "5 minutes ago"
+ * variant that once lived in `cloud.ts` is deliberately dropped. (For the
+ * session-list long form with calendar fallback, see
+ * `formatRelativeTime` in `session/relative-time.ts`.)
+ */
+export function relTime(iso) {
+    const secs = Math.floor((Date.now() - new Date(iso).getTime()) / 1000);
+    if (secs < 10)
+        return 'just now';
+    if (secs < 60)
+        return `${secs}s ago`;
+    if (secs < 3600)
+        return `${Math.floor(secs / 60)}m ago`;
+    if (secs < 86400)
+        return `${Math.floor(secs / 3600)}h ago`;
+    return `${Math.floor(secs / 86400)}d ago`;
+}
+/** Format a millisecond duration as "45s", "3m", "2h 5m", "1d 3h". */
+export function humanDuration(ms) {
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    const mm = m % 60;
+    if (h < 24)
+        return mm ? `${h}h ${mm}m` : `${h}h`;
+    const d = Math.floor(h / 24);
+    const hh = h % 24;
+    return hh ? `${d}d ${hh}h` : `${d}d`;
+}
+/**
+ * Visible column width of `s`, ignoring ANSI SGR color codes (e.g. chalk
+ * wrappers). Matches the full CSI sequence including the `\x1b` escape.
+ */
+export function visibleWidth(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+/** Pad `s` with trailing spaces to a target character width. */
+export function padRight(s, width) {
+    return s.length >= width ? s : s + ' '.repeat(width - s.length);
+}
+/** Pad `s` with trailing spaces to a target *visible* width (ANSI-aware). */
+export function padVisible(s, width) {
+    const w = visibleWidth(s);
+    return w >= width ? s : s + ' '.repeat(width - w);
+}
+/** True when `--json` was passed or stdout is not a TTY. */
+export function isJsonMode(opts) {
+    return Boolean(opts.json) || !process.stdout.isTTY;
+}
+/** Read all of stdin synchronously and return it UTF-8 decoded and trimmed. */
+export function readStdinSync() {
+    const chunks = [];
+    const buf = Buffer.alloc(65536);
+    while (true) {
+        let bytesRead;
+        try {
+            bytesRead = readSync(0, buf, 0, buf.length, null);
+        }
+        catch {
+            break;
+        }
+        if (bytesRead === 0)
+            break;
+        chunks.push(Buffer.from(buf.subarray(0, bytesRead)));
+    }
+    return Buffer.concat(chunks).toString('utf-8').trim();
+}
+/**
+ * Wrap `text` in an OSC 8 hyperlink to `filePath` (as a `file://` URL) when
+ * stdout is a TTY; otherwise return `text` unchanged.
+ */
+export function termLink(text, filePath) {
+    if (!filePath || !process.stdout.isTTY)
+        return text;
+    const url = `file://${filePath}`;
+    return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
+}

package/dist/lib/git.d.ts

@@ -104,6 +104,27 @@ export declare function cloneIntoExisting(source: string, targetDir: string): Pr
     commit: string;
     error?: string;
 }>;
+/**
+ * Git-back an EXISTING, populated directory from a remote — clone it in place
+ * without deleting the local files. Turns a plain `~/.agents` folder (which setup
+ * creates as a bare `mkdirSync` and never git-clones — see state.ts ensureAgentsDir)
+ * into a real clone of the user's config remote, so `agents repo pull/push` and
+ * `agents sync` work on a fresh or Windows machine that never got the manual clone.
+ *
+ * Unlike cloneIntoExisting (which blindly `checkout .`s over local files), this
+ * BACKS UP every tracked file whose local copy differs from the remote — into a
+ * sibling `<dir>.pre-adopt-backup/` OUTSIDE the repo so it can't be re-committed —
+ * before overwriting it. So a box with local edits to agents.yaml/hooks/rules
+ * doesn't silently lose them. Untracked runtime state (.cache/.history/.system,
+ * all gitignored) is never touched because `checkout .` only restores tracked paths.
+ */
+export declare function adoptRepo(source: string, targetDir: string): Promise<{
+    success: boolean;
+    commit: string;
+    backupDir?: string;
+    backedUp: string[];
+    error?: string;
+}>;
 /**
  * Check if the repo's origin points to the system repo.
  */

package/dist/lib/git.js

@@ -462,6 +462,98 @@ export async function cloneIntoExisting(source, targetDir) {
         return { success: false, commit: '', error: err.message };
     }
 }
+/**
+ * Git-back an EXISTING, populated directory from a remote — clone it in place
+ * without deleting the local files. Turns a plain `~/.agents` folder (which setup
+ * creates as a bare `mkdirSync` and never git-clones — see state.ts ensureAgentsDir)
+ * into a real clone of the user's config remote, so `agents repo pull/push` and
+ * `agents sync` work on a fresh or Windows machine that never got the manual clone.
+ *
+ * Unlike cloneIntoExisting (which blindly `checkout .`s over local files), this
+ * BACKS UP every tracked file whose local copy differs from the remote — into a
+ * sibling `<dir>.pre-adopt-backup/` OUTSIDE the repo so it can't be re-committed —
+ * before overwriting it. So a box with local edits to agents.yaml/hooks/rules
+ * doesn't silently lose them. Untracked runtime state (.cache/.history/.system,
+ * all gitignored) is never touched because `checkout .` only restores tracked paths.
+ */
+export async function adoptRepo(source, targetDir) {
+    const trimmed = source.trim();
+    if (fs.existsSync(path.join(targetDir, '.git'))) {
+        return { success: false, commit: '', backedUp: [], error: 'Already a git repo — nothing to adopt' };
+    }
+    // Preserve the user's transport. `parseSource` THROWS for `ssh://` and any
+    // non-github `git@host:` URL, and rewrites `git@github.com:x` → https (breaking
+    // SSH-key-only auth — the common config-repo setup — so a private clone hangs on
+    // a credential prompt). So for an SSH URL, clone it AS-IS and never call
+    // parseSource; for everything else, normalize + reject local via parseSource —
+    // inside the try, so a malformed URL returns a graceful error, not a stack trace.
+    const isSsh = trimmed.startsWith('git@') || trimmed.startsWith('ssh://');
+    const tempDir = path.join(targetDir, '.git-adopt-temp');
+    try {
+        let cloneUrl;
+        let ref;
+        if (isSsh) {
+            cloneUrl = trimmed; // SSH stays SSH; clone the remote's default HEAD.
+        }
+        else {
+            const parsed = parseSource(source);
+            if (parsed.type === 'local') {
+                return { success: false, commit: '', backedUp: [], error: 'Cannot adopt from a local source' };
+            }
+            cloneUrl = parsed.url;
+            ref = parsed.ref;
+        }
+        assertSafeGitTransport(cloneUrl);
+        fs.mkdirSync(targetDir, { recursive: true });
+        // Idempotency: clear a stale temp left by an interrupted prior run.
+        if (fs.existsSync(tempDir))
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        // Clone to temp, then move its .git in so the index == remote HEAD.
+        // Fail fast on a missing credential instead of hanging on a prompt: set
+        // GIT_TERMINAL_PROMPT=0 on the inherited env directly rather than via
+        // simple-git's `.env()`, which validates and rejects command-like vars the
+        // harness may set (GIT_EDITOR, PAGER, …) — the child inherits process.env,
+        // and non-interactive git is what we always want in the CLI anyway.
+        process.env.GIT_TERMINAL_PROMPT = '0';
+        await simpleGit().clone(cloneUrl, tempDir);
+        const repoGit = simpleGit(tempDir);
+        if (ref)
+            await repoGit.checkout(ref);
+        fs.renameSync(path.join(tempDir, '.git'), path.join(targetDir, '.git'));
+        fs.rmSync(tempDir, { recursive: true, force: true });
+        const targetGit = simpleGit(targetDir);
+        // Back up any TRACKED file whose local copy differs from the remote before the
+        // checkout clobbers it. `diff --name-only` (worktree vs the moved-in index) is
+        // exactly that set; a deleted-locally file has nothing to preserve.
+        const diff = await targetGit.diff(['--name-only']);
+        const clobbered = diff.split('\n').map((s) => s.trim()).filter(Boolean);
+        let backupDir;
+        const backedUp = [];
+        if (clobbered.length > 0) {
+            backupDir = path.join(path.dirname(targetDir), path.basename(targetDir) + '.pre-adopt-backup');
+            for (const rel of clobbered) {
+                const src = path.join(targetDir, rel);
+                if (!fs.existsSync(src))
+                    continue;
+                const dst = path.join(backupDir, rel);
+                fs.mkdirSync(path.dirname(dst), { recursive: true });
+                fs.copyFileSync(src, dst);
+                backedUp.push(rel);
+            }
+        }
+        // Materialize the remote's tracked files (respects .gitignore, so
+        // .cache/.history/.system stay put), overwriting the now-backed-up locals.
+        await targetGit.checkout('.');
+        installGithooksSymlinks(targetDir);
+        const log = await targetGit.log({ maxCount: 1 });
+        return { success: true, commit: log.latest?.hash.slice(0, 8) || 'unknown', backupDir, backedUp };
+    }
+    catch (err) {
+        if (fs.existsSync(tempDir))
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        return { success: false, commit: '', backedUp: [], error: err.message };
+    }
+}
 /**
  * Check if the repo's origin points to the system repo.
  */

package/dist/lib/hooks/cache.d.ts

@@ -1,4 +1,4 @@
-import type { HookCache, HookCacheConfig } from '../types.js';
+import type { HookCache, HookCacheConfig, HookMatches } from '../types.js';
 /**
  * Parse a `cache:` value from hooks.yaml into the canonical config form.
  * Accepts the shorthand string ("5m", "30s-bg") or the full object form.
@@ -30,11 +30,18 @@ export interface HookShimPaths {
 /**
  * Generate (or refresh) the shim script for a hook. Idempotent — only writes
  * when the content differs from what's on disk. Returns the absolute shim path.
+ *
+ * A shim is generated when the hook opts into caching (`cache`) and/or declares
+ * `matches:` predicates. When `matches` is present the shim gates execution on
+ * those predicates before running the underlying script (see `renderShim`);
+ * when `cache` is absent the shim is a thin pass-through wrapper that only
+ * applies the gate and forwards stdin/stdout unchanged.
  */
 export declare function generateHookShim(args: {
     name: string;
     scriptPath: string;
-    cache: HookCacheConfig;
+    cache?: HookCacheConfig | null;
+    matches?: HookMatches;
     paths?: HookShimPaths;
 }): string;
 /**