@phnx-labs/agents-cli 1.20.64 → 1.20.66

package/dist/lib/hosts/registry.js

@@ -2,17 +2,23 @@
  * Host provider registry.
  *
  * Mirrors the cloud provider registry: a Map of provider id → implementation,
- * instantiated once. v1 registers only `local`; adding `rush`/`tailscale`/
- * `crabbox` later is a one-line `providers.set(...)` with no caller changes.
+ * instantiated once. Registers `local` then `devices` (order is precedence:
+ * an enrolled host shadows a same-name device); adding `rush`/`crabbox` later
+ * is a one-line `providers.set(...)` with no caller changes.
  */
+import { DeviceOffloadUnsupportedError } from './types.js';
 import { LocalHostProvider } from './providers/local.js';
-import { getDevice } from '../devices/registry.js';
+import { DevicesHostProvider } from './providers/devices.js';
 import { assertValidSshTarget } from '../ssh-exec.js';
+// Re-export so existing importers (tests, commands) keep their path; the class
+// itself lives in types.ts so providers can throw it without a circular import.
+export { DeviceOffloadUnsupportedError };
 const providers = new Map();
 function initProviders() {
     if (providers.size > 0)
         return;
     providers.set('local', new LocalHostProvider());
+    providers.set('devices', new DevicesHostProvider());
 }
 export function getProvider(id) {
     initProviders();
@@ -40,51 +46,13 @@ export async function listAllHosts() {
     }
     return out;
 }
-/**
- * Thrown when a device resolves but can't be used as an offload target because
- * it authenticates with a password. The offload path runs over `sshExec`, whose
- * `SSH_OPTS` force `BatchMode=yes` (no password prompts), so only key / ssh-config
- * auth can carry a `--host` run. Named so the top-level catch prints the message
- * cleanly instead of a stack trace.
- */
-export class DeviceOffloadUnsupportedError extends Error {
-    constructor(name) {
-        super(`Device "${name}" uses password auth, which --host offload can't use yet ` +
-            `(runs go over ssh with BatchMode=yes). Switch it to key auth with ` +
-            `\`agents devices set ${name} --auth key\`, or enroll it as a host with ` +
-            `\`agents hosts add ${name}\`.`);
-        this.name = 'DeviceOffloadUnsupportedError';
-    }
-}
-/**
- * Bridge a registered device into a `Host` so `--host <device>` just works.
- * A device's dnsName (preferred) or ip becomes the ssh address; `source: 'inline'`
- * makes `sshTargetFor` emit `user@address`.
- */
-function deviceToHost(device) {
-    if (device.auth.method === 'password') {
-        throw new DeviceOffloadUnsupportedError(device.name);
-    }
-    const address = device.address.dnsName ?? device.address.ip;
-    if (!address) {
-        throw new Error(`Device "${device.name}" has no address (Tailscale DNS name or IP) to reach it by.`);
-    }
-    return {
-        name: device.name,
-        provider: 'local',
-        source: 'inline',
-        address,
-        user: device.user,
-        ...(device.platform !== 'unknown' ? { os: device.platform } : {}),
-        enrolled: true,
-    };
-}
 /**
  * Resolve a host name to a single host, or null if unknown. Resolution order:
- *   1. host providers — the `agents hosts` registry (agents.yaml overlay + ssh-config)
- *   2. the devices registry (`agents devices`) — a machine registered once with
- *      `agents devices sync` is reachable by `--host`/`--device` with no second enroll
- *   3. an ad-hoc `user@host` (must contain `@`, validated) — nothing to register
+ *   1. host providers, in registration order — the `agents hosts` registry
+ *      (`local`: agents.yaml overlay + ssh-config), then the devices registry
+ *      (`devices`: a machine registered once with `agents devices sync` is
+ *      reachable by `--host`/`--device` with no second enroll)
+ *   2. an ad-hoc `user@host` (must contain `@`, validated) — nothing to register
  *
  * A bare unknown name returns null so capability-tag routing (`resolveHostByCap`)
  * stays reachable: `--host gpu` must fall through to a cap lookup, not be misread
@@ -96,9 +64,6 @@ export async function resolveHost(name) {
         if (host)
             return host;
     }
-    const device = await getDevice(name);
-    if (device)
-        return deviceToHost(device);
     if (name.includes('@')) {
         assertValidSshTarget(name);
         const at = name.indexOf('@');
@@ -111,7 +76,9 @@ export async function resolveHost(name) {
  * matching host, or throws on 0 or >1 matches unless `any` is set (then first).
  */
 export async function resolveHostByCap(cap, any = false) {
-    const matches = (await listAllHosts()).filter((h) => h.caps?.includes(cap));
+    // Non-dispatchable hosts (password-auth devices) are listed for honesty but
+    // must never be picked as a run target.
+    const matches = (await listAllHosts()).filter((h) => h.caps?.includes(cap) && h.dispatchable !== false);
     if (matches.length === 0)
         throw new Error(`No host tagged "${cap}". Tag one with: agents hosts add <name> --cap ${cap}`);
     if (matches.length > 1 && !any) {

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

@@ -33,6 +33,29 @@ export declare function stripRoutingFlags(args: string[], specs: StripSpec[]): s
  * binary (which would re-trigger routing).
  */
 export declare const HOST_ROUTING_SPECS: StripSpec[];
+/** How one `agents run` option behaves when the run is offloaded with `--host`. */
+export type RunOptionForwarding = 
+/** Appended to the remote `agents run` argv — same behavior local or remote. */
+'forward'
+/** Refused with an actionable error BEFORE dispatch — never silently dropped. */
+ | 'reject'
+/** Consumed by the dispatching side (routing, follow rendering, cwd portability). */
+ | 'local-only';
+/**
+ * The forwarding contract for `agents run … --host`: every option of the `run`
+ * command is classified here, keyed by its commander attribute name. A
+ * commander-introspection test (run-forwarding.test.ts) fails when a run
+ * option is missing from this table, so a new option can never silently drop
+ * at the SSH boundary again — the exact bug this table exists to prevent
+ * (--secrets/--effort/--env/--timeout historically vanished on --host runs
+ * with no error).
+ *
+ * Rejections are value-aware at the call site (exec.ts): `--secrets` only
+ * rejects when a bundle was actually passed, `--resume` only when bare.
+ */
+export declare const RUN_OPTION_FORWARDING: Record<string, RunOptionForwarding>;
+/** Actionable messages for value-aware rejections, keyed by attribute name. */
+export declare const RUN_OPTION_REJECT_MESSAGES: Record<string, string>;
 /**
  * Build the single command string for `ssh <target> <cmd>`. The forwarded args
  * are quoted for the inner login shell, then the whole `agents …` invocation is

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

@@ -50,6 +50,77 @@ export const HOST_ROUTING_SPECS = [
     { long: 'device', takesValue: true },
     { long: 'remote-cwd', takesValue: true },
 ];
+/**
+ * The forwarding contract for `agents run … --host`: every option of the `run`
+ * command is classified here, keyed by its commander attribute name. A
+ * commander-introspection test (run-forwarding.test.ts) fails when a run
+ * option is missing from this table, so a new option can never silently drop
+ * at the SSH boundary again — the exact bug this table exists to prevent
+ * (--secrets/--effort/--env/--timeout historically vanished on --host runs
+ * with no error).
+ *
+ * Rejections are value-aware at the call site (exec.ts): `--secrets` only
+ * rejects when a bundle was actually passed, `--resume` only when bare.
+ */
+export const RUN_OPTION_FORWARDING = {
+    // forwarded — the remote run behaves exactly like a local one
+    mode: 'forward',
+    effort: 'forward',
+    model: 'forward',
+    env: 'forward',
+    addDir: 'forward',
+    name: 'forward',
+    resume: 'forward', // concrete id only — bare `--resume` rejects (picker can't cross SSH)
+    sessionId: 'forward',
+    timeout: 'forward',
+    fallback: 'forward',
+    balanced: 'forward',
+    strategy: 'forward',
+    loop: 'forward',
+    maxIterations: 'forward',
+    budget: 'forward',
+    until: 'forward',
+    interval: 'forward',
+    json: 'forward', // remote emits ndjson into its log; the local follow streams it verbatim
+    verbose: 'forward',
+    yes: 'forward', // a detached remote run can't answer the budget-confirm prompt
+    acp: 'forward', // the remote CLI routes through ACP on ITS side of the wire
+    autoSecrets: 'forward', // workflow frontmatter secrets resolve on the REMOTE keychain
+    // rejected — cannot cross the SSH boundary; fail loud, never degrade
+    secrets: 'reject',
+    secretsKeys: 'reject',
+    allowExpired: 'reject',
+    resumeCheckpoint: 'reject',
+    // local-only — routing, dispatch-path choice, and follow rendering
+    quiet: 'local-only', // the remote argv always carries --quiet
+    headless: 'local-only',
+    interactive: 'local-only', // the interactive path forwards --interactive itself
+    cwd: 'local-only', // made portable into remoteCwd
+    project: 'local-only',
+    remoteCwd: 'local-only',
+    raw: 'local-only', // interactive builder forwards --raw itself
+    tmux: 'local-only',
+    disableTmux: 'local-only',
+    host: 'local-only',
+    device: 'local-only',
+    on: 'local-only',
+    computer: 'local-only',
+    any: 'local-only',
+    follow: 'local-only',
+    lease: 'local-only',
+    keepBox: 'local-only',
+    copyCreds: 'local-only', // copies creds TO the host before dispatch — local concern only
+};
+/** Actionable messages for value-aware rejections, keyed by attribute name. */
+export const RUN_OPTION_REJECT_MESSAGES = {
+    secrets: '--secrets cannot cross the SSH boundary — Keychain values are never sent to a host implicitly. ' +
+        'Provision the bundle on the host first (agents secrets export --host <name>), then run without --secrets; ' +
+        'workflow frontmatter secrets resolve from the HOST\'s own keychain.',
+    secretsKeys: '--secrets-keys applies to --secrets bundles, which cannot cross the SSH boundary (see --secrets).',
+    allowExpired: '--allow-expired applies to --secrets bundles, which cannot cross the SSH boundary (see --secrets).',
+    resumeCheckpoint: '--resume-checkpoint reads a local checkpoint.json — it cannot resume a run on another machine. Run it locally, or start a fresh --loop run on the host.',
+    resumeBare: '--resume with no id opens the interactive picker, which cannot run across a detached host dispatch. Pass a concrete session id: agents run <agent> --resume <id> --host <name>.',
+};
 /**
  * Build the single command string for `ssh <target> <cmd>`. The forwarded args
  * are quoted for the inner login shell, then the whole `agents …` invocation is
@@ -156,12 +227,16 @@ export function buildWindowsAgentsCommand(cmd) {
  */
 export function buildWindowsStdinImportCommand(bundle, opts = {}) {
     const force = opts.force ? ' --force' : '';
+    // Create AND write the temp file INSIDE the try so its finally always cleans
+    // up: if GetTempFileName succeeds but WriteAllText (or the import) then throws,
+    // the secret-bearing temp file would otherwise be left behind (RUSH-1764). $tmp
+    // starts null so a GetTempFileName that itself throws leaves nothing to remove.
     const script = [
         '$in = [Console]::In.ReadToEnd()',
-        '$tmp = [System.IO.Path]::GetTempFileName()',
-        '[System.IO.File]::WriteAllText($tmp, $in)',
-        `try { & agents secrets import ${powershellQuote(bundle)} --from $tmp${force}; $code = $LASTEXITCODE } ` +
-            `finally { Remove-Item -LiteralPath $tmp -Force -ErrorAction SilentlyContinue }`,
+        '$tmp = $null',
+        `try { $tmp = [System.IO.Path]::GetTempFileName(); [System.IO.File]::WriteAllText($tmp, $in); ` +
+            `& agents secrets import ${powershellQuote(bundle)} --from $tmp${force}; $code = $LASTEXITCODE } ` +
+            `finally { if ($tmp) { Remove-Item -LiteralPath $tmp -Force -ErrorAction SilentlyContinue } }`,
         'if ($null -eq $code) { $code = 1 }',
         'exit $code',
     ].join('; ');

package/dist/lib/hosts/run-target.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared host-run dispatch — the one path every surface uses to run an agent on
+ * another machine: `agents run --host` (commands/exec.ts), the `host` cloud
+ * provider (`agents cloud run --provider host`), and host-placed routines.
+ *
+ * Wraps the two steps every caller needs and previously lived inline in
+ * exec.ts's `--host` branch:
+ *   1. resolution — name → capability tag → error, with the same fall-through
+ *      semantics as `agents run --host` (only "Multiple hosts tagged…" is a
+ *      resolution verdict; "no host tagged" degrades to unknown-host), and
+ *   2. headless dispatch — session-id mint (Claude only), detached SSH launch,
+ *      and LOCAL session-index registration so the run shows in `agents sessions`.
+ *
+ * Interactive dispatch stays in exec.ts: it is inherently tied to the caller's
+ * TTY and has no other consumers.
+ */
+import type { Host } from './types.js';
+import type { DispatchResult } from './dispatch.js';
+import type { HostCredentials } from './credentials.js';
+/**
+ * Resolution failed with a user-actionable message the caller should print
+ * verbatim. Distinct from `DeviceOffloadUnsupportedError` (which propagates to
+ * the top-level catch) so callers can tell "bad name" from "bad auth method".
+ */
+export declare class HostResolutionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve a `--host` value the way `agents run` does: exact name (providers →
+ * devices → `user@host`), then capability tag. Throws `HostResolutionError`
+ * for an ambiguous tag or an unknown name; lets `DeviceOffloadUnsupportedError`
+ * (password-auth device) propagate untouched for the top-level catch.
+ */
+export declare function resolveHostRunTarget(name: string, opts?: {
+    any?: boolean;
+}): Promise<Host>;
+export interface HostPromptRun {
+    agent: string;
+    prompt: string;
+    /** Explicit agent version pin, forwarded as `agent@version`. */
+    version?: string;
+    mode?: string;
+    model?: string;
+    /** Durable `--name <slug>` handle recorded on the task. */
+    name?: string;
+    /** Resume an existing session on the host by concrete id. */
+    resume?: string;
+    /** Working directory on the host, already made remote-portable by the caller. */
+    remoteCwd?: string;
+    /** Stream progress and block until completion (default true). */
+    follow?: boolean;
+    timeoutMs?: number;
+    /** Local directory to record in the session index (defaults to process.cwd()). */
+    cwd?: string;
+    /** Forwarded run options — see RUN_OPTION_FORWARDING in remote-cmd.ts. */
+    effort?: string;
+    env?: string[];
+    addDir?: string[];
+    timeout?: string;
+    strategy?: string;
+    balanced?: boolean;
+    fallback?: string;
+    loop?: boolean;
+    maxIterations?: string;
+    budget?: string;
+    until?: string;
+    interval?: string;
+    json?: boolean;
+    verbose?: boolean;
+    yes?: boolean;
+    acp?: boolean;
+    autoSecrets?: boolean;
+    passthroughArgs?: string[];
+    /** Copy runtime credentials to the host before the run and shred them after. */
+    copyCreds?: HostCredentials;
+}
+/**
+ * Dispatch a headless prompt run onto a resolved host: mint the forced session
+ * id (Claude is the only agent that accepts `--session-id`; on resume the
+ * remote session keeps its id), launch detached over SSH, and register the run
+ * in the LOCAL session index. Returns the task record and the remote exit code
+ * (`-1` = follow window closed while the run continues).
+ */
+export declare function dispatchPromptToHost(host: Host, opts: HostPromptRun): Promise<DispatchResult>;

package/dist/lib/hosts/run-target.js

@@ -0,0 +1,99 @@
+/**
+ * Shared host-run dispatch — the one path every surface uses to run an agent on
+ * another machine: `agents run --host` (commands/exec.ts), the `host` cloud
+ * provider (`agents cloud run --provider host`), and host-placed routines.
+ *
+ * Wraps the two steps every caller needs and previously lived inline in
+ * exec.ts's `--host` branch:
+ *   1. resolution — name → capability tag → error, with the same fall-through
+ *      semantics as `agents run --host` (only "Multiple hosts tagged…" is a
+ *      resolution verdict; "no host tagged" degrades to unknown-host), and
+ *   2. headless dispatch — session-id mint (Claude only), detached SSH launch,
+ *      and LOCAL session-index registration so the run shows in `agents sessions`.
+ *
+ * Interactive dispatch stays in exec.ts: it is inherently tied to the caller's
+ * TTY and has no other consumers.
+ */
+import { randomUUID } from 'crypto';
+import { resolveHost, resolveHostByCap } from './registry.js';
+import { dispatchToHost } from './dispatch.js';
+import { registerHostSession } from './session-index.js';
+/**
+ * Resolution failed with a user-actionable message the caller should print
+ * verbatim. Distinct from `DeviceOffloadUnsupportedError` (which propagates to
+ * the top-level catch) so callers can tell "bad name" from "bad auth method".
+ */
+export class HostResolutionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HostResolutionError';
+    }
+}
+/**
+ * Resolve a `--host` value the way `agents run` does: exact name (providers →
+ * devices → `user@host`), then capability tag. Throws `HostResolutionError`
+ * for an ambiguous tag or an unknown name; lets `DeviceOffloadUnsupportedError`
+ * (password-auth device) propagate untouched for the top-level catch.
+ */
+export async function resolveHostRunTarget(name, opts = {}) {
+    let host = await resolveHost(name);
+    if (!host) {
+        try {
+            host = await resolveHostByCap(name, opts.any);
+        }
+        catch (e) {
+            const msg = e.message ?? '';
+            // Ambiguity is a verdict, not a miss — surface it. "No host tagged"
+            // falls through to the generic unknown-host error below.
+            if (msg.startsWith('Multiple hosts'))
+                throw new HostResolutionError(msg);
+        }
+    }
+    if (!host)
+        throw new HostResolutionError(`Unknown host "${name}". List hosts: agents hosts list`);
+    return host;
+}
+/**
+ * Dispatch a headless prompt run onto a resolved host: mint the forced session
+ * id (Claude is the only agent that accepts `--session-id`; on resume the
+ * remote session keeps its id), launch detached over SSH, and register the run
+ * in the LOCAL session index. Returns the task record and the remote exit code
+ * (`-1` = follow window closed while the run continues).
+ */
+export async function dispatchPromptToHost(host, opts) {
+    const sessionId = opts.agent === 'claude' && !opts.resume ? randomUUID() : undefined;
+    const result = await dispatchToHost(host, {
+        agent: opts.agent,
+        prompt: opts.prompt,
+        version: opts.version,
+        mode: opts.mode,
+        model: opts.model,
+        remoteCwd: opts.remoteCwd,
+        sessionId,
+        name: opts.name,
+        resume: opts.resume,
+        follow: opts.follow !== false,
+        timeoutMs: opts.timeoutMs,
+        effort: opts.effort,
+        env: opts.env,
+        addDir: opts.addDir,
+        timeout: opts.timeout,
+        strategy: opts.strategy,
+        balanced: opts.balanced,
+        fallback: opts.fallback,
+        loop: opts.loop,
+        maxIterations: opts.maxIterations,
+        budget: opts.budget,
+        until: opts.until,
+        interval: opts.interval,
+        json: opts.json,
+        verbose: opts.verbose,
+        yes: opts.yes,
+        acp: opts.acp,
+        autoSecrets: opts.autoSecrets,
+        passthroughArgs: opts.passthroughArgs,
+        copyCreds: opts.copyCreds,
+    });
+    registerHostSession(result.task, { cwd: opts.cwd ?? process.cwd(), prompt: opts.prompt });
+    return result;
+}

package/dist/lib/hosts/types.d.ts

@@ -2,13 +2,14 @@
  * Agent-host provider contract.
  *
  * A `HostProvider` answers "what are my hosts, and how do I reach them?" — the
- * pluggable directory/metadata/reachability layer. v1 ships only the `local`
- * provider (ssh-config ∪ inline registry); `rush`/`tailscale`/`crabbox` are
- * additive fast-follows behind this same contract. Capability-gated so partial
- * providers are first-class (mirrors the cloud provider registry).
+ * pluggable directory/metadata/reachability layer. Shipped providers: `local`
+ * (ssh-config ∪ inline registry) and `devices` (the Tailscale fleet from
+ * `agents devices`); `rush`/`crabbox` remain additive fast-follows behind this
+ * same contract. Capability-gated so partial providers are first-class
+ * (mirrors the cloud provider registry).
  */
 import type { HostEntry } from '../types.js';
-export type HostProviderId = 'local';
+export type HostProviderId = 'local' | 'devices';
 export type HostStatus = 'online' | 'offline' | 'unknown';
 /** A host as seen at runtime: its persisted entry plus name/provider/status. */
 export interface Host extends HostEntry {
@@ -17,6 +18,23 @@ export interface Host extends HostEntry {
     /** True when the host has an explicit overlay/inline entry in the registry. */
     enrolled?: boolean;
     status?: HostStatus;
+    /**
+     * False when the host is listed for honesty but can't carry a `--host` run
+     * (today: password-auth devices — offload rides BatchMode=yes ssh). Absent
+     * means dispatchable. Cap routing and target pickers filter on this.
+     */
+    dispatchable?: boolean;
+}
+/**
+ * Thrown when a device resolves but can't be used as an offload target because
+ * it authenticates with a password. The offload path runs over `sshExec`, whose
+ * `SSH_OPTS` force `BatchMode=yes` (no password prompts), so only key / ssh-config
+ * auth can carry a `--host` run. Named so the top-level catch prints the message
+ * cleanly instead of a stack trace. (Lives here, not registry.ts, so providers
+ * can throw it without a circular import; registry.ts re-exports it.)
+ */
+export declare class DeviceOffloadUnsupportedError extends Error {
+    constructor(name: string);
 }
 export interface HostProviderCapabilities {
     /** Can list/track hosts. */

package/dist/lib/hosts/types.js

@@ -2,11 +2,29 @@
  * Agent-host provider contract.
  *
  * A `HostProvider` answers "what are my hosts, and how do I reach them?" — the
- * pluggable directory/metadata/reachability layer. v1 ships only the `local`
- * provider (ssh-config ∪ inline registry); `rush`/`tailscale`/`crabbox` are
- * additive fast-follows behind this same contract. Capability-gated so partial
- * providers are first-class (mirrors the cloud provider registry).
+ * pluggable directory/metadata/reachability layer. Shipped providers: `local`
+ * (ssh-config ∪ inline registry) and `devices` (the Tailscale fleet from
+ * `agents devices`); `rush`/`crabbox` remain additive fast-follows behind this
+ * same contract. Capability-gated so partial providers are first-class
+ * (mirrors the cloud provider registry).
  */
+/**
+ * Thrown when a device resolves but can't be used as an offload target because
+ * it authenticates with a password. The offload path runs over `sshExec`, whose
+ * `SSH_OPTS` force `BatchMode=yes` (no password prompts), so only key / ssh-config
+ * auth can carry a `--host` run. Named so the top-level catch prints the message
+ * cleanly instead of a stack trace. (Lives here, not registry.ts, so providers
+ * can throw it without a circular import; registry.ts re-exports it.)
+ */
+export class DeviceOffloadUnsupportedError extends Error {
+    constructor(name) {
+        super(`Device "${name}" uses password auth, which --host offload can't use yet ` +
+            `(runs go over ssh with BatchMode=yes). Switch it to key auth with ` +
+            `\`agents devices set ${name} --auth key\`, or enroll it as a host with ` +
+            `\`agents hosts add ${name}\`.`);
+        this.name = 'DeviceOffloadUnsupportedError';
+    }
+}
 /**
  * The ssh target string for a host: the bare name for ssh-config hosts (ssh
  * resolves HostName/User/Port/Identity), else `user@address` (or `address`).

package/dist/lib/linear-autoclose.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Linear auto-close: close Linear issues whose linked GitHub PRs have merged.
+ *
+ * The pure decision function `shouldCloseIssue` is the only logic here —
+ * it is unit-tested and shared with the command routine's equivalent
+ * shell check.  The rest (Linear GraphQL, gh invocations) lives in the
+ * routine YAML's `command:` shell script so the routine stays self-contained
+ * and independent of the CLI build.
+ *
+ * @see apps/cli/routines/linear-autoclose.yml
+ */
+/**
+ * Subset of `gh pr view --json state,mergedAt` output that drives the
+ * close decision.  State is one of: OPEN | CLOSED | MERGED (gh GraphQL).
+ */
+export interface PrInfo {
+    /** gh GraphQL PR state: 'OPEN' | 'CLOSED' | 'MERGED' */
+    state: string;
+    /** ISO-8601 merge timestamp, or null when the PR was not merged. */
+    mergedAt: string | null;
+}
+/**
+ * Pure decision: returns true when the PR has been merged and its linked
+ * Linear issue should therefore be closed.
+ *
+ * A PR is considered merged only when both conditions hold:
+ *   1. `state === 'MERGED'`  — gh marks CLOSED (rejected) separately from MERGED
+ *   2. `mergedAt !== null`   — defensive guard; a merged PR always carries a timestamp
+ */
+export declare function shouldCloseIssue(pr: PrInfo): boolean;

package/dist/lib/linear-autoclose.js

@@ -0,0 +1,22 @@
+/**
+ * Linear auto-close: close Linear issues whose linked GitHub PRs have merged.
+ *
+ * The pure decision function `shouldCloseIssue` is the only logic here —
+ * it is unit-tested and shared with the command routine's equivalent
+ * shell check.  The rest (Linear GraphQL, gh invocations) lives in the
+ * routine YAML's `command:` shell script so the routine stays self-contained
+ * and independent of the CLI build.
+ *
+ * @see apps/cli/routines/linear-autoclose.yml
+ */
+/**
+ * Pure decision: returns true when the PR has been merged and its linked
+ * Linear issue should therefore be closed.
+ *
+ * A PR is considered merged only when both conditions hold:
+ *   1. `state === 'MERGED'`  — gh marks CLOSED (rejected) separately from MERGED
+ *   2. `mergedAt !== null`   — defensive guard; a merged PR always carries a timestamp
+ */
+export function shouldCloseIssue(pr) {
+    return pr.state === 'MERGED' && pr.mergedAt !== null;
+}

package/dist/lib/mcp.d.ts

@@ -44,10 +44,35 @@ export declare function parseMcpServerConfig(filePath: string): McpYamlConfig |
  * command-line options or that contain characters unsafe for argv/identifier use.
  */
 export declare function validateMcpServerName(name: string): void;
+/** Path to the user-owned project-trust store (never inside a repo). */
+export declare function getMcpTrustStorePath(): string;
+/**
+ * Whether the project that owns `projectAgentsDir` has been explicitly trusted
+ * for MCP auto-apply. Untrusted by default (fail closed).
+ */
+export declare function isProjectMcpTrusted(projectAgentsDir: string): boolean;
+/**
+ * Record explicit trust for the project containing `cwd` so its project-scoped
+ * MCP servers may be registered/spawned. Returns the trusted project root, or
+ * null when `cwd` is not inside a project (no `.agents/` to trust).
+ */
+export declare function trustProjectMcp(cwd?: string): string | null;
+/** Revoke MCP trust for the project containing `cwd`. Returns true if it was trusted. */
+export declare function untrustProjectMcp(cwd?: string): boolean;
 /**
  * List all MCP server configs from ~/.agents/mcp/.
+ *
+ * When `enforceProjectTrust` is set, project-scoped configs are included only
+ * for a project the user has explicitly trusted (see `isProjectMcpTrusted`) —
+ * this is the choke point that keeps an untrusted cloned repo's MCP servers out
+ * of the register/spawn path. It ALSO fixes name-collision shadowing: an
+ * untrusted project entry is dropped before dedup, so it can never mask a
+ * same-named user entry. Display callers omit the flag to surface project
+ * entries (command+args and all) regardless of trust.
  */
-export declare function listMcpServerConfigs(cwd?: string): InstalledMcpServer[];
+export declare function listMcpServerConfigs(cwd?: string, options?: {
+    enforceProjectTrust?: boolean;
+}): InstalledMcpServer[];
 /**
  * Scan a repository for MCP server YAML configs.
  * Looks under <repoPath>/mcp/*.yaml — same on-disk layout as ~/.agents/mcp/.
@@ -70,6 +95,7 @@ export declare function installMcpConfigCentrally(sourcePath: string): {
  */
 export declare function getMcpServersByName(names?: string[], options?: {
     cwd?: string;
+    enforceProjectTrust?: boolean;
 }): InstalledMcpServer[];
 /**
  * Assemble the JSON payload Claude's `--mcp-config` flag expects from a set of