@phnx-labs/agents-cli 1.22.114 → 1.22.115

package/dist/lib/mcp.js

@@ -380,25 +380,31 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
  * Uses: codex mcp add <name> -- <cmd> [args...]
  */
 function installMcpViaCodex(binaryPath, server, versionHome) {
-    if (server.config.transport === 'stdio') {
+    let args;
+    if (server.config.transport === 'http') {
+        if (!server.config.url)
+            throw new Error(`HTTP MCP '${server.name}' has no url`);
+        // codex mcp add <name> --url <url>
+        args = ['mcp', 'add', server.name, '--url', server.config.url];
+    }
+    else {
         // codex mcp add -- <name> <cmd> [args...]
-        const args = [
+        args = [
             'mcp', 'add',
             '--',
             server.name,
             server.config.command,
             ...(server.config.args || [])
         ];
-        // RUSH-1752: user-controlled MCP command/args must not reach cmd.exe unquoted.
-        const spec = execFileShellSpec(binaryPath, args);
-        execFileSync(spec.command, spec.args, {
-            stdio: 'pipe',
-            timeout: 30000,
-            env: { ...process.env, HOME: versionHome },
-            shell: spec.shell,
-        });
     }
-    // Note: Codex may not support HTTP MCPs
+    // RUSH-1752: user-controlled MCP command/args must not reach cmd.exe unquoted.
+    const spec = execFileShellSpec(binaryPath, args);
+    execFileSync(spec.command, spec.args, {
+        stdio: 'pipe',
+        timeout: 30000,
+        env: { ...process.env, HOME: versionHome },
+        shell: spec.shell,
+    });
 }
 export async function registerMcpCommandToTargets(targets, name, commandSpec, scope = 'user', transport = 'stdio') {
     const results = [];

package/dist/lib/probe.d.ts

@@ -3,6 +3,9 @@
  * timeout — matching the `execFileAsync` contract the version probe had — and
  * reaps the probe's whole process group on every settle path.
  */
-export declare function probeCapture(cmd: string, args: string[], timeoutMs: number): Promise<{
+export declare function probeCapture(cmd: string, args: string[], timeoutMs: number, options?: {
+    acceptedExitCodes?: number[];
+    maxOutputBytes?: number;
+}): Promise<{
     stdout: string;
 }>;

package/dist/lib/probe.js

@@ -59,7 +59,7 @@ function reapGroup(pid) {
  * timeout — matching the `execFileAsync` contract the version probe had — and
  * reaps the probe's whole process group on every settle path.
  */
-export function probeCapture(cmd, args, timeoutMs) {
+export function probeCapture(cmd, args, timeoutMs, options = {}) {
     return new Promise((resolve, reject) => {
         const child = spawn(cmd, args, {
             detached: GROUP_REAP,
@@ -92,6 +92,9 @@ export function probeCapture(cmd, args, timeoutMs) {
         child.stdout?.setEncoding('utf8');
         child.stdout?.on('data', (d) => {
             out += d;
+            if (Buffer.byteLength(out) > (options.maxOutputBytes ?? 1024 * 1024)) {
+                settle(new Error(`probe output exceeded limit: ${cmd}`));
+            }
         });
         child.on('error', (e) => settle(e));
         // 'exit', not 'close': a forked grandchild inherits the stdout pipe, and
@@ -99,7 +102,7 @@ export function probeCapture(cmd, args, timeoutMs) {
         // process this helper exists to reap. Settle when the probed binary
         // itself exits; one tick's grace lets its final stdout chunks land.
         child.on('exit', (code) => {
-            setImmediate(() => settle(code === 0 ? null : new Error(`probe exited ${code}: ${cmd} ${args.join(' ')}`)));
+            setImmediate(() => settle(code !== null && (options.acceptedExitCodes ?? [0]).includes(code) ? null : new Error(`probe exited ${code}: ${cmd} ${args.join(' ')}`)));
         });
     });
 }

package/dist/lib/pwsh.d.ts

@@ -9,3 +9,36 @@
  * spawns powershell.exe with an argv array).
  */
 export declare function encodePwshBase64(script: string): string;
+/** Single-quote a value for PowerShell's own parser (embedded `'` doubled). */
+export declare function pwshLiteral(value: string): string;
+/**
+ * PowerShell statements that run a NATIVE program with exact argv.
+ *
+ * Windows has no argv array: a process receives ONE string and splits it itself.
+ * PowerShell 5.1 rebuilds that string when it invokes a native program, and its
+ * serializer is lossy — measured on a real peer, an EMPTY argument is dropped and
+ * an embedded `"` is discarded. So the arguments are pre-escaped by the caller to
+ * the `CommandLineToArgvW` rules (`quoteWin32ExecArg`) and handed to .NET as one
+ * `Arguments` string, which `CreateProcess` receives essentially verbatim. No shell
+ * is involved, so no `%VAR%` expansion and no newline sensitivity.
+ *
+ * `UseShellExecute = $false` with no redirection leaves the child on the inherited
+ * handles, which is what lets a binary stdout stream through unchanged.
+ *
+ * `WorkingDirectory` is set explicitly from `(Get-Location).ProviderPath`, and that
+ * is not belt-and-braces: PowerShell's `Set-Location` moves the SHELL's location
+ * without updating the .NET process's OS working directory, so a child launched
+ * through `ProcessStartInfo` would otherwise start in whatever directory the
+ * process began in — silently ignoring a caller's `cwd` (`--remote-cwd`). The
+ * `ProviderPath` form is what yields a real filesystem path rather than a
+ * PowerShell provider path.
+ *
+ * @param fileNameExpr a PowerShell EXPRESSION for the executable (a quoted literal,
+ *   or something like `$__c.Source`) — not a raw path, so a caller that resolved the
+ *   target on the peer can pass its variable.
+ * @param argumentsExpr a PowerShell EXPRESSION producing the argument string —
+ *   `pwshLiteral(line)` for a static one, or a concatenation when part of it is
+ *   only known on the peer (a resolved interpreter entry, say).
+ * @param exitVar variable name for the child, so a caller can chain on it.
+ */
+export declare function pwshNativeExecStatements(fileNameExpr: string, argumentsExpr: string, exitVar?: string): string[];

package/dist/lib/pwsh.js

@@ -11,3 +11,59 @@
 export function encodePwshBase64(script) {
     return Buffer.from(script, 'utf16le').toString('base64');
 }
+/** Single-quote a value for PowerShell's own parser (embedded `'` doubled). */
+export function pwshLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * PowerShell statements that run a NATIVE program with exact argv.
+ *
+ * Windows has no argv array: a process receives ONE string and splits it itself.
+ * PowerShell 5.1 rebuilds that string when it invokes a native program, and its
+ * serializer is lossy — measured on a real peer, an EMPTY argument is dropped and
+ * an embedded `"` is discarded. So the arguments are pre-escaped by the caller to
+ * the `CommandLineToArgvW` rules (`quoteWin32ExecArg`) and handed to .NET as one
+ * `Arguments` string, which `CreateProcess` receives essentially verbatim. No shell
+ * is involved, so no `%VAR%` expansion and no newline sensitivity.
+ *
+ * `UseShellExecute = $false` with no redirection leaves the child on the inherited
+ * handles, which is what lets a binary stdout stream through unchanged.
+ *
+ * `WorkingDirectory` is set explicitly from `(Get-Location).ProviderPath`, and that
+ * is not belt-and-braces: PowerShell's `Set-Location` moves the SHELL's location
+ * without updating the .NET process's OS working directory, so a child launched
+ * through `ProcessStartInfo` would otherwise start in whatever directory the
+ * process began in — silently ignoring a caller's `cwd` (`--remote-cwd`). The
+ * `ProviderPath` form is what yields a real filesystem path rather than a
+ * PowerShell provider path.
+ *
+ * @param fileNameExpr a PowerShell EXPRESSION for the executable (a quoted literal,
+ *   or something like `$__c.Source`) — not a raw path, so a caller that resolved the
+ *   target on the peer can pass its variable.
+ * @param argumentsExpr a PowerShell EXPRESSION producing the argument string —
+ *   `pwshLiteral(line)` for a static one, or a concatenation when part of it is
+ *   only known on the peer (a resolved interpreter entry, say).
+ * @param exitVar variable name for the child, so a caller can chain on it.
+ */
+export function pwshNativeExecStatements(fileNameExpr, argumentsExpr, exitVar = '$zp') {
+    // Deliberately terse. The whole script is base64'd into ONE ssh command line,
+    // and OpenSSH-for-Windows caps that far below cmd.exe's 8191 — measured on a
+    // real peer, it fails between ~2.8k and ~4.1k characters. UTF-16LE + base64
+    // inflates by ~2.7x, so every character here costs almost three on the wire.
+    // `System.` is implicit for these types, and `-EA` is the canonical alias.
+    return [
+        `$zi=New-Object Diagnostics.ProcessStartInfo`,
+        `$zi.FileName=${fileNameExpr}`,
+        `$zi.Arguments=${argumentsExpr}`,
+        `$zi.UseShellExecute=$false`,
+        `$zi.WorkingDirectory=(Get-Location).ProviderPath`,
+        // The CALLER sets `$ErrorActionPreference='Stop'` for the whole script, so it
+        // is not repeated here — every character costs ~2.7 on the wire after base64.
+        // The null guard below is what makes a swallowed Start failure impossible to
+        // mistake for success: without it the handle is $null, the code is $null, and
+        // `exit $null` reports 0.
+        `${exitVar}=[Diagnostics.Process]::Start($zi)`,
+        `if($null -eq ${exitVar}){throw "start failed: $($zi.FileName)"}`,
+        `${exitVar}.WaitForExit()`,
+    ];
+}

package/dist/lib/redact.d.ts

@@ -23,3 +23,11 @@ export declare function redactSecrets(text: string, knownValues?: readonly strin
  * credential verbatim even when its format matches no pattern.
  */
 export declare function knownSecretValuesFromEnv(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Mask email addresses in already-rendered text. A published page's sensitive-
+ * content scan refuses a body containing an email (`artifacts share` does the
+ * same), and almost every real transcript carries a few — git author addresses,
+ * `gh api user`, a pasted log. Masking them here means the page genuinely does
+ * not carry them, rather than training callers to pass `--force`.
+ */
+export declare function redactEmails(text: string): string;

package/dist/lib/redact.js

@@ -185,3 +185,14 @@ export function knownSecretValuesFromEnv(env = process.env) {
     }
     return out;
 }
+const EMAIL_RE = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+/**
+ * Mask email addresses in already-rendered text. A published page's sensitive-
+ * content scan refuses a body containing an email (`artifacts share` does the
+ * same), and almost every real transcript carries a few — git author addresses,
+ * `gh api user`, a pasted log. Masking them here means the page genuinely does
+ * not carry them, rather than training callers to pass `--force`.
+ */
+export function redactEmails(text) {
+    return text.replace(EMAIL_RE, '[EMAIL]');
+}

package/dist/lib/refresh.d.ts

@@ -6,10 +6,10 @@
  * The reconcile stage behind `agents sync` (the umbrella `--local` path calls
  * this; see sync-umbrella.ts) and any other caller that needs to re-derive local
  * state from declared configuration. Does NOT do any git operations — that lives
- * in `agents repo pull`. (Also still reachable via the deprecated, hidden
- * `agents repo refresh` alias.)
+ * in `agents repo pull`.
  */
 import type { AgentId } from './types.js';
+import { type ResourceSelection } from './installations/versions.js';
 interface RefreshOptions {
     /** Limit operations to a single agent (claude/codex/etc). Default: all installed. */
     agentFilter?: AgentId;
@@ -22,6 +22,10 @@ interface RefreshOptions {
      * (`agents sync --json` / fleet fan-out) so stdout stays a single JSON object.
      */
     quiet?: boolean;
+    /** Limit reconciliation to the requested resource kinds/names. */
+    selection?: ResourceSelection;
+    /** Explicit consent for selected plugins that add executable surfaces. */
+    allowExecSurfaces?: boolean;
 }
 /**
  * Re-materialize local state from declared configuration: install CLI versions,

package/dist/lib/refresh.js

@@ -6,8 +6,7 @@
  * The reconcile stage behind `agents sync` (the umbrella `--local` path calls
  * this; see sync-umbrella.ts) and any other caller that needs to re-derive local
  * state from declared configuration. Does NOT do any git operations — that lives
- * in `agents repo pull`. (Also still reachable via the deprecated, hidden
- * `agents repo refresh` alias.)
+ * in `agents repo pull`.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -50,7 +49,7 @@ function migratePromptcutsToRoot(agentsDir, quiet = false) {
     }
 }
 export async function refresh(options = {}) {
-    const { agentFilter, skipPrompts = false, skipClis = false, quiet = false } = options;
+    const { agentFilter, skipPrompts = false, skipClis = false, quiet = false, selection: requestedSelection, allowExecSurfaces = false, } = options;
     const agentsDir = getUserAgentsDir();
     // Gate every human progress line so --json / fleet fan-out can parse stdout.
     const log = (...args) => { if (!quiet)
@@ -59,7 +58,8 @@ export async function refresh(options = {}) {
     // synced list cannot also mean "declined and here is why" (RUSH-2700).
     const declined = [];
     const reconciled = [];
-    migratePromptcutsToRoot(agentsDir, quiet);
+    if (!requestedSelection)
+        migratePromptcutsToRoot(agentsDir, quiet);
     const manifest = readManifest(agentsDir);
     if (!manifest) {
         log(chalk.gray(`No ${MANIFEST_FILENAME} found`));
@@ -94,17 +94,23 @@ export async function refresh(options = {}) {
         }
     }
     // 2. Register MCP servers
-    if (manifest?.mcp && Object.keys(manifest.mcp).length > 0) {
+    if ((!requestedSelection || requestedSelection.mcp) && manifest?.mcp && Object.keys(manifest.mcp).length > 0) {
         log(chalk.bold('\nMCP Servers:\n'));
         for (const [name, config] of Object.entries(manifest.mcp)) {
-            if (!config.command || config.transport === 'http')
+            if (Array.isArray(requestedSelection?.mcp) && !requestedSelection.mcp.includes(name))
                 continue;
+            const transport = config.transport || 'stdio';
+            const commandOrUrl = transport === 'http' ? config.url : config.command;
+            if (!commandOrUrl) {
+                log(`  ${chalk.cyan(name)}: ${chalk.yellow(`missing ${transport === 'http' ? 'url' : 'command'}`)}`);
+                continue;
+            }
             const scopedAgents = (config.agents ? [...config.agents] : [...capableAgents('mcp')]).filter((id) => !agentFilter || id === agentFilter);
             const scopedVersions = config.agentVersions
                 ? Object.fromEntries(Object.entries(config.agentVersions).filter(([agentId]) => !agentFilter || agentId === agentFilter))
                 : undefined;
             const targets = resolveConfiguredAgentTargets(scopedAgents, scopedVersions, capableAgents('mcp'));
-            const results = await registerMcpToTargets(targets, name, config.command, config.scope || 'user', config.transport || 'stdio');
+            const results = await registerMcpToTargets(targets, name, commandOrUrl, config.scope || 'user', transport);
             for (const result of results) {
                 if (result.success) {
                     const label = result.version
@@ -116,22 +122,25 @@ export async function refresh(options = {}) {
         }
     }
     // 3. Sync resources into version homes.
-    // Unattended (`skipPrompts` / `agents sync --yes --local`): every installed
-    // version — otherwise non-default homes keep stale hooks after a system
-    // update (fleet multi-harness: only the default version was refreshed).
-    // Interactive: default only; re-run `agents sync <agent>@all` for the rest.
+    // Unattended (`skipPrompts` / `agents sync --yes --local`) and explicit
+    // resource selectors: every installed version. Otherwise non-default homes
+    // keep stale resources after a system update or named plugin sync.
+    // Interactive full reconcile: default only.
     const cliStates = await getAllCliStates();
     const agentsToSync = agentFilter ? [agentFilter] : MANAGED_AGENT_IDS;
     const available = getAvailableResources();
     for (const agentId of agentsToSync) {
-        if (!cliStates[agentId]?.installed && listInstalledVersions(agentId).length === 0)
+        const installedVersions = listInstalledVersions(agentId);
+        if (!cliStates[agentId]?.installed && installedVersions.length === 0)
             continue;
         const defaultVer = getGlobalDefault(agentId);
-        if (!defaultVer)
+        if (!defaultVer && !requestedSelection)
             continue;
-        const versionsToSync = skipPrompts
-            ? listInstalledVersions(agentId)
+        const versionsToSync = requestedSelection || skipPrompts
+            ? installedVersions
             : [defaultVer];
+        if (versionsToSync.length === 0)
+            continue;
         // Interactive-only: getActuallySyncedResources walks every skill tree with
         // content compares (~1s/agent on a full install). The unattended path
         // (`skipPrompts` / `agents sync --yes`) never reads these — it always
@@ -139,7 +148,7 @@ export async function refresh(options = {}) {
         let actuallySynced;
         let newResources;
         let hasAnySynced = false;
-        if (!skipPrompts) {
+        if (!skipPrompts && !requestedSelection) {
             actuallySynced = getActuallySyncedResources(agentId, defaultVer);
             newResources = getNewResources(available, actuallySynced, getProjectOnlyResources());
             hasAnySynced = actuallySynced.commands.length > 0 ||
@@ -153,7 +162,10 @@ export async function refresh(options = {}) {
         try {
             let selection;
             let forceFullSync = false;
-            if (skipPrompts) {
+            if (requestedSelection) {
+                selection = requestedSelection;
+            }
+            else if (skipPrompts) {
                 forceFullSync = true;
             }
             else if (!hasAnySynced) {
@@ -176,7 +188,11 @@ export async function refresh(options = {}) {
                 for (const ver of versionsToSync) {
                     // Pass the already-built `available` so each version does not re-scan
                     // resource trees (RUSH-2320 #5).
-                    const syncResult = syncResourcesToVersion(agentId, ver, selection, { available, ...(forceFullSync ? { force: true } : {}) });
+                    const syncResult = syncResourcesToVersion(agentId, ver, selection, {
+                        available,
+                        allowExecSurfaces,
+                        ...(forceFullSync || requestedSelection ? { force: true } : {}),
+                    });
                     reconciled.push({ agent: agentId, version: ver });
                     if (syncResult.commands)
                         kinds.add('commands');
@@ -214,7 +230,7 @@ export async function refresh(options = {}) {
         }
     }
     // 4. Register hooks as lifecycle events (same version set as resource sync)
-    const hookManifest = parseHookManifest();
+    const hookManifest = requestedSelection ? {} : parseHookManifest();
     if (Object.keys(hookManifest).length > 0) {
         let hookRegistered = 0;
         const hookAgents = new Set(capableAgents('hooks'));
@@ -242,25 +258,27 @@ export async function refresh(options = {}) {
     // 5. Auto-add shims to PATH
     // Refresh the gh overload shim so `gh pr checks` escapes the GraphQL rate limit
     // for every user, transparently (PHNX-3501). Idempotent; POSIX-only in v1.
-    try {
-        ensureGhOverloadShim();
-    }
-    catch {
-        // Never let a shim-write hiccup break sync — real gh stays fine without it.
-    }
-    if (!isShimsInPath()) {
-        const pathResult = addShimsToPath();
-        if (pathResult.success && !pathResult.alreadyPresent) {
-            log(chalk.green(`\nAdded shims to ${pathResult.location}`));
-            log(chalk.gray(pathResult.reloadHint));
+    if (!requestedSelection) {
+        try {
+            ensureGhOverloadShim();
+        }
+        catch {
+            // Never let a shim-write hiccup break sync — real gh stays fine without it.
         }
-        else if (!pathResult.success) {
-            log(chalk.yellow('\nCould not auto-add shims to PATH:'));
-            log(chalk.gray(getPathSetupInstructions()));
+        if (!isShimsInPath()) {
+            const pathResult = addShimsToPath();
+            if (pathResult.success && !pathResult.alreadyPresent) {
+                log(chalk.green(`\nAdded shims to ${pathResult.location}`));
+                log(chalk.gray(pathResult.reloadHint));
+            }
+            else if (!pathResult.success) {
+                log(chalk.yellow('\nCould not auto-add shims to PATH:'));
+                log(chalk.gray(getPathSetupInstructions()));
+            }
         }
     }
     // 6. Prompt for missing default versions
-    if (!skipPrompts) {
+    if (!skipPrompts && !requestedSelection) {
         const agentsNeedingDefault = [];
         for (const agentId of agentsToSync) {
             const versions = listInstalledVersions(agentId);
@@ -307,53 +325,55 @@ export async function refresh(options = {}) {
         }
     }
     // 7. Install declared host-CLIs
-    try {
-        const { statuses, errors } = listCliStatus(process.cwd());
-        for (const err of errors) {
-            log(chalk.yellow(`  CLI manifest parse error: ${err.file}: ${err.reason}`));
-        }
-        const missing = statuses.filter((s) => !s.installed);
-        if (missing.length > 0) {
-            log(chalk.bold('\nDeclared CLIs missing from this host:'));
-            for (const s of missing) {
-                const method = selectInstallMethod(s.manifest);
-                const action = method ? describeMethod(method) : chalk.red('no compatible install method');
-                log(`  ${chalk.cyan(s.manifest.name.padEnd(20))} ${chalk.gray(action)}`);
+    if (!requestedSelection) {
+        try {
+            const { statuses, errors } = listCliStatus(process.cwd());
+            for (const err of errors) {
+                log(chalk.yellow(`  CLI manifest parse error: ${err.file}: ${err.reason}`));
             }
-            log('');
-            if (!skipPrompts) {
-                const proceed = await confirm({ message: `Install ${missing.length} missing CLI(s) now?`, default: true });
-                if (proceed) {
-                    for (const s of missing) {
-                        log(chalk.bold(`\n→ ${s.manifest.name}`));
-                        const result = installCli(s.manifest);
-                        if (result.error) {
-                            log(chalk.red(`  ${result.error}`));
-                            continue;
-                        }
-                        if (result.installed) {
-                            log(chalk.green(`  installed`));
-                            if (s.manifest.postInstall) {
-                                log(chalk.gray(s.manifest.postInstall.trim().split('\n').map((l) => '  ' + l).join('\n')));
+            const missing = statuses.filter((s) => !s.installed);
+            if (missing.length > 0) {
+                log(chalk.bold('\nDeclared CLIs missing from this host:'));
+                for (const s of missing) {
+                    const method = selectInstallMethod(s.manifest);
+                    const action = method ? describeMethod(method) : chalk.red('no compatible install method');
+                    log(`  ${chalk.cyan(s.manifest.name.padEnd(20))} ${chalk.gray(action)}`);
+                }
+                log('');
+                if (!skipPrompts) {
+                    const proceed = await confirm({ message: `Install ${missing.length} missing CLI(s) now?`, default: true });
+                    if (proceed) {
+                        for (const s of missing) {
+                            log(chalk.bold(`\n→ ${s.manifest.name}`));
+                            const result = installCli(s.manifest);
+                            if (result.error) {
+                                log(chalk.red(`  ${result.error}`));
+                                continue;
+                            }
+                            if (result.installed) {
+                                log(chalk.green(`  installed`));
+                                if (s.manifest.postInstall) {
+                                    log(chalk.gray(s.manifest.postInstall.trim().split('\n').map((l) => '  ' + l).join('\n')));
+                                }
+                            }
+                            else {
+                                log(chalk.yellow(`  install ran but \`${describeCheck(s.manifest.check)}\` still fails`));
                             }
                         }
-                        else {
-                            log(chalk.yellow(`  install ran but \`${describeCheck(s.manifest.check)}\` still fails`));
-                        }
+                    }
+                    else {
+                        log(chalk.gray(`Skipped. Run 'agents cli install' later.`));
                     }
                 }
                 else {
-                    log(chalk.gray(`Skipped. Run 'agents cli install' later.`));
+                    log(chalk.gray(`Run 'agents cli install' to install them.`));
                 }
             }
-            else {
-                log(chalk.gray(`Run 'agents cli install' to install them.`));
-            }
         }
-    }
-    catch (err) {
-        if (!isPromptCancelled(err)) {
-            log(chalk.yellow(`CLI install skipped: ${err.message}`));
+        catch (err) {
+            if (!isPromptCancelled(err)) {
+                log(chalk.yellow(`CLI install skipped: ${err.message}`));
+            }
         }
     }
     // A resource agents-cli refused to write is reported, never swallowed —

package/dist/lib/secrets-cli.d.ts

@@ -0,0 +1,11 @@
+export declare const SECRETS_CLI_NAME = "secrets";
+export declare const SECRETS_CLI_PACKAGE = "@phnx-labs/secrets-cli";
+/** Published standalone `agents setup secrets` installs; bump with the protocol. */
+export declare const SECRETS_CLI_VERSION = "0.1.4";
+export declare const SECRETS_CLI_SPEC = "@phnx-labs/secrets-cli@0.1.4";
+export declare const SECRETS_CLI_INSTALL_HINT = "npm i -g @phnx-labs/secrets-cli@0.1.4";
+/**
+ * True when `$SECRETS_BIN` is set or a real `secrets` executable is on PATH
+ * outside agents-cli's shims dir. Does not spawn the binary.
+ */
+export declare function isSecretsPresent(): boolean;

package/dist/lib/secrets-cli.js

@@ -0,0 +1,30 @@
+/**
+ * The standalone `secrets` CLI that agents-cli talks to (PHNX-3989).
+ *
+ * The engine lives in `@phnx-labs/secrets-cli`. This module is the single pin
+ * and presence check shared by the process client (`secrets-client.ts`) and
+ * `agents setup secrets` — it carries no storage. Presence is `findInPath`,
+ * which skips `~/.agents/.cache/shims`: a leftover alias there `exec`s
+ * `agents secrets` and would recurse (agi-cli#3532).
+ *
+ * Keep this file free of `cli-resources` imports: `secrets-client.ts` loads it,
+ * and a cycle through the host-CLI parser would pull yaml/spawn into the
+ * process-client module graph.
+ */
+import { findInPath } from './agent-spec/agents.js';
+export const SECRETS_CLI_NAME = 'secrets';
+export const SECRETS_CLI_PACKAGE = '@phnx-labs/secrets-cli';
+/** Published standalone `agents setup secrets` installs; bump with the protocol. */
+export const SECRETS_CLI_VERSION = '0.1.4';
+export const SECRETS_CLI_SPEC = `${SECRETS_CLI_PACKAGE}@${SECRETS_CLI_VERSION}`;
+export const SECRETS_CLI_INSTALL_HINT = `npm i -g ${SECRETS_CLI_SPEC}`;
+/**
+ * True when `$SECRETS_BIN` is set or a real `secrets` executable is on PATH
+ * outside agents-cli's shims dir. Does not spawn the binary.
+ */
+export function isSecretsPresent() {
+    const explicit = process.env.SECRETS_BIN?.trim();
+    if (explicit)
+        return true;
+    return findInPath(SECRETS_CLI_NAME) !== null;
+}

package/dist/lib/secrets-client.js

@@ -49,6 +49,7 @@
  */
 import { spawn, spawnSync } from 'node:child_process';
 import { findInPath } from './agent-spec/agents.js';
+import { SECRETS_CLI_INSTALL_HINT } from './secrets-cli.js';
 import { getUserAgentsDir } from './state.js';
 /**
  * Wire contract, mirrored from `secrets-cli/src/protocol.ts`. Both sides MUST
@@ -216,8 +217,8 @@ export function resolveSecretsBin() {
     const resolved = explicit && explicit.length > 0 ? explicit : findInPath('secrets');
     if (!resolved) {
         throw new SecretsClientError('SECRETS_BIN_MISSING', 'The standalone `secrets` CLI was not found. Install it with:\n' +
-            '  npm i -g @phnx-labs/secrets-cli\n' +
-            'or point $SECRETS_BIN at its executable.');
+            `  ${SECRETS_CLI_INSTALL_HINT}\n` +
+            'or run `agents setup secrets`.');
     }
     cachedBin = resolved;
     return resolved;

package/dist/lib/session/detached.d.ts

@@ -20,6 +20,13 @@ export declare function clearDetachRecord(sessionId: string): void;
 export declare function listDetachRecords(): DetachRecord[];
 /** True while the recorded headless continuation is still the live process we spawned. */
 export declare function isHeadlessAlive(rec: DetachRecord): boolean;
+/**
+ * Stop the detached continuation before a local foreground resume starts.
+ * The start-time check in {@link isHeadlessAlive} prevents signalling a reused
+ * PID; a continuation that ignores SIGTERM fails closed instead of running
+ * alongside a second process against the same transcript.
+ */
+export declare function takeOverDetachedSession(sessionId: string): Promise<boolean>;
 /**
  * Presence for a session id from the detach store alone:
  *   - no record            -> undefined (caller decides: `attached` for a live

package/dist/lib/session/detached.js

@@ -77,6 +77,35 @@ export function isHeadlessAlive(rec) {
     }
     return true;
 }
+/**
+ * Stop the detached continuation before a local foreground resume starts.
+ * The start-time check in {@link isHeadlessAlive} prevents signalling a reused
+ * PID; a continuation that ignores SIGTERM fails closed instead of running
+ * alongside a second process against the same transcript.
+ */
+export async function takeOverDetachedSession(sessionId) {
+    const rec = readDetachRecord(sessionId);
+    if (!rec)
+        return false;
+    if (isHeadlessAlive(rec)) {
+        try {
+            process.kill(rec.headlessPid, 'SIGTERM');
+        }
+        catch (err) {
+            if (isHeadlessAlive(rec))
+                throw err;
+        }
+        const deadline = Date.now() + 2_000;
+        while (isHeadlessAlive(rec) && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+        if (isHeadlessAlive(rec)) {
+            throw new Error(`Detached continuation ${rec.headlessPid} did not stop; refusing to resume a duplicate process.`);
+        }
+    }
+    clearDetachRecord(sessionId);
+    return true;
+}
 /**
  * Presence for a session id from the detach store alone:
  *   - no record            -> undefined (caller decides: `attached` for a live