@phnx-labs/agents-cli 1.22.114 → 1.22.116

package/dist/lib/projects.js

@@ -455,6 +455,84 @@ export function projectNameForCwd(cwd, defs) {
     }
     return best ?? weakBest;
 }
+/**
+ * Definition list, memoized against a stamp over the definition FILES, for the
+ * per-tick readers (PHNX-3999).
+ *
+ * {@link listProjectDefs} parses every `<name>.yaml`, which is the right cost for
+ * a command but not for a row builder on the `feed watch` / `sessions watch`
+ * stream — that runs twice a second for as long as an editor window is open (see
+ * `AGENTS.md`, every tick is budgeted). One `readdir` plus one `stat` per
+ * definition replaces N YAML parses.
+ *
+ * The stamp is each file's name + mtime + size, NOT the directory's mtime: editing
+ * a definition in place — retargeting a project's `root`, which is exactly what
+ * changes which sessions belong to it — moves the FILE's mtime and leaves the
+ * directory's untouched, so a directory stamp would serve a stale association for
+ * the life of the process. An unreadable directory is not cached: the next call
+ * retries.
+ */
+let projectDefsMemo = null;
+function projectDefsStamp() {
+    try {
+        const dir = getProjectsDir();
+        const files = fs.readdirSync(dir).filter((f) => f.endsWith('.yaml')).sort();
+        return files
+            .map((f) => {
+            try {
+                const st = fs.statSync(path.join(dir, f));
+                return `${f}:${st.mtimeMs}:${st.size}`;
+            }
+            catch {
+                // Removed between readdir and stat — its absence is part of the stamp.
+                return `${f}:gone`;
+            }
+        })
+            .join('\n');
+    }
+    catch {
+        return null;
+    }
+}
+export function listProjectDefsCached() {
+    const stamp = projectDefsStamp();
+    // No projects dir (or unreadable): nothing is confirmed, and nothing to cache.
+    if (stamp === null)
+        return [];
+    if (projectDefsMemo && projectDefsMemo.stamp === stamp)
+        return projectDefsMemo.defs;
+    const defs = listProjectDefs();
+    projectDefsMemo = { stamp, defs };
+    return defs;
+}
+/** Drop the {@link listProjectDefsCached} memo — for tests that rewrite the dir within one mtime tick. */
+export function resetProjectDefsCache() {
+    projectDefsMemo = null;
+}
+/**
+ * The **confirmed** project for a working directory, or `undefined` when the
+ * association is not confirmed (PHNX-3999 F08/F09).
+ *
+ * Confirmed means exactly one thing: a registered project definition
+ * ({@link projectNameForCwd}) whose root contains this path. Being inside *some*
+ * git repository is NOT a project association — a repo nobody registered, a
+ * checkout of someone else's code, or a loose directory that merely has a
+ * `.git` in it would each invent a project name out of a folder, which is the
+ * wrong-grouping the owner's recording shows at 01:30–01:56. So is a bare
+ * directory basename ({@link resolveProjectKey}, which always answers).
+ *
+ * A consumer renders `undefined` as Uncategorized and keeps the session
+ * reachable in its full list — nothing is hidden by not being grouped.
+ *
+ * Use {@link resolveProjectNameForCwd} instead when you want a best-effort
+ * bucket KEY for joining rows; use this when the answer is shown to a person as
+ * "this work belongs to that project".
+ */
+export function confirmedProjectForCwd(cwd, defs = listProjectDefsCached()) {
+    if (!cwd)
+        return undefined;
+    return projectNameForCwd(cwd, defs);
+}
 /**
  * The canonical project label for a cwd, for every surface that buckets work by
  * project (the activity timeline, feed posts, the sessions overview): the

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.5";
+export declare const SECRETS_CLI_SPEC = "@phnx-labs/secrets-cli@0.1.5";
+export declare const SECRETS_CLI_INSTALL_HINT = "npm i -g @phnx-labs/secrets-cli@0.1.5";
+/**
+ * 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.5';
+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/active.d.ts

@@ -71,6 +71,7 @@ export declare function activeSessionProjectKey(s: Pick<ActiveSession, 'cwd' | '
 export declare function serializeActiveSessionsForJson(sessions: ActiveSession[]): Array<Omit<ActiveSession, 'viewingIn'> & {
     ticketId: string | null;
     project: string;
+    confirmedProject: string | null;
     prLink: string | null;
     viewingIn: string | null;
 }>;

package/dist/lib/session/active.js

@@ -38,6 +38,7 @@ import { computeTokPerSec } from './throughput.js';
 import { inferSessionState } from './state.js';
 import { isSessionTrackedAgent, SESSION_AGENTS, AG_TMUX_NAME_RE } from './types.js';
 import { AGENTS } from '../agents.js';
+import { confirmedProjectForCwd, listProjectDefsCached } from '../projects.js';
 import { detectProvenance } from './provenance.js';
 import { loadDevices } from '../devices/registry.js';
 import { machineId, normalizeHost } from '../machine-id.js';
@@ -227,10 +228,17 @@ export function activeSessionProjectKey(s) {
     return s.context === 'cloud' ? 'cloud' : 'other';
 }
 export function serializeActiveSessionsForJson(sessions) {
+    // One definition read for the whole batch, not per row (PHNX-3999 F08/F09).
+    const defs = listProjectDefsCached();
     return sessions.map((s) => ({
         ...s,
         ticketId: s.ticket?.id ?? null,
         project: activeSessionProjectKey(s),
+        // The project a person is shown this row under, or null for Uncategorized.
+        // `project` above is the always-present join KEY (basename of the cwd, or the
+        // explicit cloud/other bucket) and stays exactly as it was — grouping by it is
+        // what filed unbound directories as projects of their own.
+        confirmedProject: confirmedProjectForCwd(s.cwd, defs) ?? null,
         prLink: s.pr?.url ?? null,
         viewingIn: viewingInLabel(s) ?? null,
     }));