@phnx-labs/agents-cli 1.20.82 → 1.20.83

package/dist/commands/sessions.d.ts

@@ -3,6 +3,66 @@ import type { SessionAgentId, SessionMeta, ViewMode } from '../lib/session/types
 import { type ActiveSession } from '../lib/session/active.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
 import { type PickedSession } from './sessions-picker.js';
+interface SessionFilterOptions {
+    agent?: string;
+    project?: string;
+    all?: boolean;
+    teams?: boolean;
+    routine?: boolean;
+    since?: string;
+    until?: string;
+}
+interface SessionsOptions extends SessionFilterOptions {
+    /** Also list sessions from the user's own unmanaged ~/.<agent> installs. */
+    unmanaged?: boolean;
+    query?: string;
+    limit?: string;
+    sort?: string;
+    json?: boolean;
+    markdown?: boolean;
+    /** Commander populates this from `--no-redact`: true by default, false when the flag is passed. */
+    redact?: boolean;
+    include?: string;
+    exclude?: string;
+    first?: string;
+    last?: string;
+    artifacts?: boolean;
+    artifact?: string;
+    active?: boolean;
+    /** Emit the on-disk session-scan directories (requires --json); for watchers. */
+    roots?: boolean;
+    cloud?: boolean;
+    host?: string[];
+    /** Group the listing by directory and drop the id/version columns. */
+    tree?: boolean;
+    /** Force the plain flat table instead of the grouped default overview. */
+    flat?: boolean;
+    /** With --active: show only sessions waiting on user input; exit 1 if any. */
+    waiting?: boolean;
+    /** Enrich the listing with live glyphs/preview for running rows. Default on;
+     * `--no-live` sets this false. Commander's `--no-` convention. */
+    live?: boolean;
+    /** Force local-only: skip the cross-machine SSH fan-out (both the default
+     * listing and --active). */
+    local?: boolean;
+    /** --device <target...> — alias for --host; resolves against the device registry. */
+    device?: string[];
+    /** Per-agent shorthands: aliases for `--agent <name>` (prioritized harnesses). */
+    claude?: boolean;
+    codex?: boolean;
+    kimi?: boolean;
+    antigravity?: boolean;
+    grok?: boolean;
+    opencode?: boolean;
+    /** Force the printed listing even on a TTY. Commander's `--no-` convention:
+     * `--no-interactive` sets this false, opting out of the interactive browser. */
+    interactive?: boolean;
+    /** Print the canonical `ag sessions …` command for the given flags and exit —
+     * the non-interactive twin of the browser's `y` hotkey. */
+    printCmd?: boolean;
+    /** Print a compact preview of the matched session and exit (no pager). */
+    preview?: boolean;
+}
 /**
  * Strip terminal/harness noise from a preview so the column stays a single line
  * of plain prose: OSC title escapes, CSI/SGR ANSI, and the harness wrapper tags
@@ -10,6 +70,16 @@ import { type PickedSession } from './sessions-picker.js';
  * a captured transcript tail. Collapses runs of whitespace.
  */
 export declare function cleanPreview(text: string): string;
+/**
+ * Build the live description for an active session: checklist progress (when
+ * present) plus the state engine's preview (the latest turn), a user label, or
+ * the first-prompt topic. Used by both the flat listing's `doing` cell and as
+ * the snippet half of the --active row (identity is layered on in printActiveRow).
+ *
+ * Covers every ActiveSession context: terminal (interactive), headless, teams,
+ * cloud, and sub-agent rows that share the same ActiveSession.todos field.
+ */
+export declare function buildSessionDescription(s: ActiveSession): string;
 /**
  * Identity + checklist + live snippet for an --active / cross-machine row.
  * Surfaces agent-adjacent identity the flat table already has (label, project)
@@ -190,6 +260,20 @@ export declare function gatherActiveSessions(opts?: {
     sessions: ActiveSession[];
     remoteDeviceCount: number;
 }>;
+/**
+ * A bare interactive fleet listing — no query, no render/filter flag — that the
+ * `runSessionBrowser` picker can represent. The single predicate shared by the
+ * bare-browser branch and the `--host` early-return guard so they can't drift:
+ * when this holds, an explicit `--host`/`--device` scope is folded into the
+ * browser (preview-rich, selectable) instead of the legacy per-host raw stream.
+ */
+export declare function isBareBrowserListing(options: SessionsOptions, query: string | undefined): boolean;
+/**
+ * Pure flag-gate half of {@link isBareBrowserListing} (TTY-independent, so it is
+ * unit-testable): true when no query, render, or filter flag is present that the
+ * `runSessionBrowser` picker cannot represent.
+ */
+export declare function hasNoBrowserDisqualifyingFlags(options: SessionsOptions, query: string | undefined): boolean;
 /** One flat table row:
  *   shortId · agent · version · model · project · [glyph] label·doing · [ticket] · [wt] · time
  * `doing` is the live preview when running, else the topic. The `ticket` column

package/dist/commands/sessions.js

@@ -240,7 +240,7 @@ export function cleanPreview(text) {
  * Covers every ActiveSession context: terminal (interactive), headless, teams,
  * cloud, and sub-agent rows that share the same ActiveSession.todos field.
  */
-function buildSessionDescription(s) {
+export function buildSessionDescription(s) {
     const todo = formatTodoCompact(s.todos);
     if (s.context === 'cloud') {
         const base = s.preview || `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`;
@@ -248,6 +248,11 @@ function buildSessionDescription(s) {
     }
     if (s.context === 'teams') {
         const parts = [s.teamName];
+        // Lineage: which orchestrator spun up this team. Prefer the resolved label,
+        // else the short session id, so "by whom" is answerable at a glance.
+        const orch = s.orchestratorLabel || (s.orchestratorSessionId ? s.orchestratorSessionId.slice(0, 8) : '');
+        if (orch)
+            parts.push(`by ${orch}`);
         if (todo)
             parts.push(todo);
         if (s.preview)
@@ -997,6 +1002,33 @@ function printCrossMachineTip() {
 function useInteractiveBrowser(options) {
     return options.interactive !== false && !options.json && isInteractiveTerminal();
 }
+/**
+ * A bare interactive fleet listing — no query, no render/filter flag — that the
+ * `runSessionBrowser` picker can represent. The single predicate shared by the
+ * bare-browser branch and the `--host` early-return guard so they can't drift:
+ * when this holds, an explicit `--host`/`--device` scope is folded into the
+ * browser (preview-rich, selectable) instead of the legacy per-host raw stream.
+ */
+export function isBareBrowserListing(options, query) {
+    return useInteractiveBrowser(options) && hasNoBrowserDisqualifyingFlags(options, query);
+}
+/**
+ * Pure flag-gate half of {@link isBareBrowserListing} (TTY-independent, so it is
+ * unit-testable): true when no query, render, or filter flag is present that the
+ * `runSessionBrowser` picker cannot represent.
+ */
+export function hasNoBrowserDisqualifyingFlags(options, query) {
+    return (!query &&
+        !options.routine &&
+        !options.flat &&
+        !options.tree &&
+        !options.markdown &&
+        !options.until &&
+        !options.project &&
+        !options.sort &&
+        !options.artifacts &&
+        options.artifact === undefined);
+}
 /** The canonical `ag sessions …` command for a set of flags — the twin of the
  * browser's `y` hotkey (see --print-cmd). Normalizes to the stable flag form. */
 function canonicalSessionsCommand(query, options) {
@@ -1099,14 +1131,21 @@ async function sessionsAction(query, options) {
             await runRemoteSessionsJson(options.host);
             return;
         }
-        try {
-            runRemoteSessions(options.host);
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
+        // A bare interactive `--host`/`--device <box>` listing falls through to the
+        // fleet browser below, which folds the named host(s) into the same merged,
+        // preview-rich, selectable view as the local listing (via gatherRemoteList).
+        // A query, a render/filter flag, or a non-interactive caller keeps the legacy
+        // per-host raw stream under a `── host ──` banner.
+        if (!isBareBrowserListing(options, query)) {
+            try {
+                runRemoteSessions(options.host);
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+            return;
         }
-        return;
     }
     // --preview <id/query>: resolve one session and print its compact preview, then
     // exit — checked before --active so `--active --preview <id>` peeks the id
@@ -1160,17 +1199,7 @@ async function sessionsAction(query, options) {
     // filter the browser can't represent), or --no-interactive keep the existing
     // printed/render paths (agents and scripts unaffected). An explicit --since seeds
     // the browser's window so the flag is honored, not swallowed.
-    if (useInteractiveBrowser(options) &&
-        !query &&
-        !options.routine &&
-        !options.flat &&
-        !options.tree &&
-        !options.markdown &&
-        !options.until &&
-        !options.project &&
-        !options.sort &&
-        !options.artifacts &&
-        options.artifact === undefined) {
+    if (isBareBrowserListing(options, query)) {
         const { runSessionBrowser, bareBrowserSeed } = await import('./sessions-browser.js');
         await runSessionBrowser(bareBrowserSeed({
             teams: options.teams,

package/dist/index.js

@@ -656,6 +656,41 @@ function registerJobsCronAliasCommand(p, alias) {
         await program.parseAsync(['node', 'agents', ...args]);
     });
 }
+/**
+ * Removed `check` command (RUSH-1234) — re-parses as `doctor --check`, forwarding
+ * any remaining flags so `check --quiet` / `check --json` / `check --devices` keep
+ * working and the drift-gate exit code survives the rename. The notice goes to
+ * stderr so `--json` stdout stays clean for CI parsers.
+ */
+function registerCheckTombstoneCommand(p) {
+    p.command('check', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async () => {
+        console.error(chalk.yellow('Deprecated: "agents check" is now "agents doctor --check". Running that for you.\n'));
+        const args = process.argv.slice(2);
+        args[0] = 'doctor';
+        args.splice(1, 0, '--check');
+        await program.parseAsync(['node', 'agents', ...args]);
+    });
+}
+/**
+ * Removed `resources` command (RUSH-1234) — re-parses as `view --merged` (the
+ * cross-layer, first-wins resource table now lives there; `agents inspect <target>`
+ * covers per-agent / per-repo detail). Forwards remaining flags like `--json`.
+ */
+function registerResourcesTombstoneCommand(p) {
+    p.command('resources', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async () => {
+        console.error(chalk.yellow('Deprecated: "agents resources" is now "agents view --merged" (use "agents inspect <target>" for per-agent/per-repo detail). Running that for you.\n'));
+        const args = process.argv.slice(2);
+        args[0] = 'view';
+        args.splice(1, 0, '--merged');
+        await program.parseAsync(['node', 'agents', ...args]);
+    });
+}
 /** Self-upgrade command (`agents upgrade [version]`). */
 function registerUpgradeCommand(p) {
     p.command('upgrade')
@@ -739,6 +774,16 @@ async function registerEagerForRequest(name) {
             registerJobsCronAliasCommand(program, name);
             await reg(loadRoutines);
             return true;
+        case 'check':
+            // The action re-parses as `doctor --check`, so doctor must exist too.
+            registerCheckTombstoneCommand(program);
+            await reg(loadDoctor);
+            return true;
+        case 'resources':
+            // The action re-parses as `view --merged`, so view must exist too.
+            registerResourcesTombstoneCommand(program);
+            await reg(loadView);
+            return true;
         case 'upgrade':
             registerUpgradeCommand(program);
             return true;
@@ -759,6 +804,7 @@ async function registerEagerForRequest(name) {
  */
 async function registerAllEagerCommands() {
     await reg(loadView);
+    registerResourcesTombstoneCommand(program);
     await reg(loadShare);
     await reg(loadSend);
     await reg(loadInspect);
@@ -791,6 +837,7 @@ async function registerAllEagerCommands() {
     await reg(loadTrash);
     await reg(loadRestore);
     await reg(loadDoctor);
+    registerCheckTombstoneCommand(program);
     await reg(loadApply);
     await reg(loadStatus);
     registerExecAliasCommand(program);

package/dist/lib/exec.d.ts

@@ -262,6 +262,13 @@ export declare const AGENT_COMMANDS: Record<AgentId, AgentCommandTemplate>;
  * return false resume via the universal Tier-2 `/continue` replay instead.
  */
 export declare function nativeResume(agent: AgentId): boolean;
+/**
+ * Build the `-c` value that adds `dir` to codex's workspace-write writable
+ * roots. Codex parses the value as TOML, so it's a single-element TOML array of
+ * one quoted string. Used on codex resume forms, which reject `--add-dir` and
+ * only accept `-c` config overrides.
+ */
+export declare function codexWritableRootsConfig(dir: string): string;
 /** Assemble the full CLI argument array for an agent invocation. */
 export declare function buildExecCommand(options: ExecOptions): string[];
 /** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */

package/dist/lib/exec.js

@@ -16,7 +16,7 @@ import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { resolveActor, actorEnv } from './actor.js';
-import { getShimsDir, getHistoryDir } from './state.js';
+import { getShimsDir, getHistoryDir, getUserAgentsDir } from './state.js';
 import { resolveCodexHome } from './codex-home.js';
 import { readCodexConfiguredModel } from './shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
@@ -573,6 +573,15 @@ export const AGENT_COMMANDS = {
 export function nativeResume(agent) {
     return AGENT_COMMANDS[agent]?.resume !== undefined;
 }
+/**
+ * Build the `-c` value that adds `dir` to codex's workspace-write writable
+ * roots. Codex parses the value as TOML, so it's a single-element TOML array of
+ * one quoted string. Used on codex resume forms, which reject `--add-dir` and
+ * only accept `-c` config overrides.
+ */
+export function codexWritableRootsConfig(dir) {
+    return `sandbox_workspace_write.writable_roots=[${JSON.stringify(dir)}]`;
+}
 /** Assemble the full CLI argument array for an agent invocation. */
 export function buildExecCommand(options) {
     const template = AGENT_COMMANDS[options.agent];
@@ -658,6 +667,18 @@ export function buildExecCommand(options) {
         // AGENT_COMMANDS.modeFlags drifted apart. Tests assert they agree.
         throw new Error(`Internal error: ${options.agent} declares '${resolvedMode}' in capabilities.modes but has no entry in AGENT_COMMANDS.modeFlags.${resolvedMode}.`);
     }
+    // Codex's workspace-write sandbox blocks $HOME (verified against the live CLI
+    // and OpenAI's sandbox docs: writable roots extend scope "without removing the
+    // sandbox entirely"). But the model routinely shells out to `agents ...`, whose
+    // runtime state lives under ~/.agents — the SSH askpass shim
+    // (~/.agents/.cache/devices/askpass.sh), the device/stats cache, secrets,
+    // session writes, config tunings. Without ~/.agents as a writable root those
+    // inner writes fail with EROFS (e.g. `agents ssh` dies before connecting),
+    // which is why a remote `agents run codex` couldn't reach the fleet. Grant it
+    // implicitly whenever codex runs workspace-write — far narrower than --mode skip
+    // (danger-full-access). Fresh runs take --add-dir (below); resume forms reject
+    // --add-dir, so they take the same root via -c writable_roots here.
+    const codexWorkspaceWrite = options.agent === 'codex' && resolvedMode === 'edit';
     if (resumeSpec && 'subcommand' in resumeSpec) {
         if (resolvedMode === 'skip') {
             // skip = yolo on resume too; both `codex resume` (TUI) and
@@ -667,6 +688,8 @@ export function buildExecCommand(options) {
         else if (interactive) {
             // `codex resume` (TUI) accepts the same -s/--sandbox flags as a fresh run.
             cmd.push(...modeFlags);
+            if (codexWorkspaceWrite)
+                cmd.push('-c', codexWritableRootsConfig(getUserAgentsDir()));
         }
         else {
             // `codex exec resume` rejects `--sandbox <mode>` (verified against
@@ -676,6 +699,7 @@ export function buildExecCommand(options) {
             cmd.push('-c', `sandbox_mode=${resolvedMode === 'plan' ? 'read-only' : 'workspace-write'}`);
             if (resolvedMode !== 'plan') {
                 cmd.push('-c', 'sandbox_workspace_write.network_access=true');
+                cmd.push('-c', codexWritableRootsConfig(getUserAgentsDir()));
             }
         }
     }
@@ -779,9 +803,16 @@ export function buildExecCommand(options) {
     // 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 &&
+    //
+    // On top of any user-supplied dirs, a fresh codex workspace-write run
+    // implicitly gets ~/.agents (deduped) so the CLI's own tooling — askpass,
+    // secrets, sessions, tunings — can write from inside the sandbox. Resume forms
+    // get the same root via -c writable_roots above (see codexWorkspaceWrite).
+    const codexImplicitDirs = codexWorkspaceWrite && !options.resume ? [getUserAgentsDir()] : [];
+    const addDirs = [...new Set([...(options.addDirs ?? []), ...codexImplicitDirs])];
+    if (addDirs.length > 0 &&
         (options.agent === 'claude' || (options.agent === 'codex' && !options.resume))) {
-        for (const dir of options.addDirs) {
+        for (const dir of addDirs) {
             cmd.push('--add-dir', dir);
         }
     }

package/dist/lib/hooks.d.ts

@@ -21,12 +21,41 @@ export declare function resolveHookScriptPath(script: string): string | null;
  * os.homedir()/path.sep at the call site.
  */
 export declare function toPortableCommand(absPath: string, home?: string, sep?: string): string;
+/**
+ * Collapse version-scoped registrations by logical resource identity rather
+ * than absolute command path. When the same resource is present in several
+ * homes, the active home's command wins even if it appears later. Commands
+ * outside version homes are user-owned and remain untouched.
+ */
+export declare function deduplicateVersionHookCommands(commands: string[], activeVersionHome: string): string[];
 import type { AgentId, InstalledHook, ManifestHook } from './types.js';
 export type HookEntry = {
     name: string;
     scriptPath: string;
     dataFile?: string;
 };
+export interface VersionHookCopy {
+    agent: AgentId;
+    version: string;
+    name: string;
+    path: string;
+    hash: string;
+    active: boolean;
+}
+export interface DuplicateVersionHook {
+    agent: AgentId;
+    name: string;
+    kind: 'duplicate' | 'drift';
+    authoritative: VersionHookCopy;
+    copies: VersionHookCopy[];
+}
+/**
+ * Inspect every installed hooks-capable harness without assuming a native
+ * settings format. Same-name copies with one content hash are installation
+ * noise; multiple hashes are drift. The active version is always selected as
+ * the authoritative copy when it participates in the group.
+ */
+export declare function inspectDuplicateVersionHooks(cwd?: string): DuplicateVersionHook[];
 /**
  * List hook entries in a single directory, grouping script + data files by
  * basename. Exported so doctor-diff can reuse the same grouping the sync path

package/dist/lib/hooks.js

@@ -146,9 +146,113 @@ function isStaleSiblingVersionCommand(command, current) {
     const id = versionHomeIdentity(command);
     return id !== null && id.agent === current.agent && id.version !== current.version;
 }
-import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
+function hookResourceName(command) {
+    const withoutArgs = command.trim().split(/\s+/)[0];
+    return path.basename(withoutArgs).replace(/\.[^.]+$/, '');
+}
+/**
+ * Collapse version-scoped registrations by logical resource identity rather
+ * than absolute command path. When the same resource is present in several
+ * homes, the active home's command wins even if it appears later. Commands
+ * outside version homes are user-owned and remain untouched.
+ */
+export function deduplicateVersionHookCommands(commands, activeVersionHome) {
+    const active = versionHomeIdentity(activeVersionHome);
+    if (!active)
+        return [...commands];
+    const selected = new Map();
+    const passthrough = [];
+    for (const command of commands) {
+        const identity = versionHomeIdentity(command);
+        if (!identity || identity.agent !== active.agent) {
+            passthrough.push(command);
+            continue;
+        }
+        const key = `${identity.agent}\0${hookResourceName(command)}`;
+        const candidateIsActive = identity.version === active.version;
+        const prior = selected.get(key);
+        if (!prior || (!prior.active && candidateIsActive)) {
+            selected.set(key, { command, active: candidateIsActive });
+        }
+    }
+    return [...passthrough, ...Array.from(selected.values(), ({ command }) => command)];
+}
+/**
+ * Collapse a matcher group's hook entries down to the deduplicated command
+ * multiset {@link deduplicateVersionHookCommands} returns, preserving order and
+ * the concrete entry objects. The deduped list is honored as a per-command
+ * budget, NOT a membership set: two identical active-version entries collapse to
+ * one because the budget for that command is one. (A membership `Set.has` test
+ * would keep both — the bug this replaces.) Passthrough (user / non-version-home)
+ * commands keep their original multiplicity, so genuine user hooks are untouched.
+ */
+function collapseVersionHookEntries(entries, activeVersionHome) {
+    const budget = new Map();
+    for (const command of deduplicateVersionHookCommands(entries.map((e) => e.command), activeVersionHome)) {
+        budget.set(command, (budget.get(command) ?? 0) + 1);
+    }
+    return entries.filter((e) => {
+        const remaining = budget.get(e.command) ?? 0;
+        if (remaining <= 0)
+            return false;
+        budget.set(e.command, remaining - 1);
+        return true;
+    });
+}
+import { getEffectiveHome, getVersionHomePath, listInstalledVersions, resolveVersion } from './versions.js';
 import { generateHookShim, getHookShimPath, isValidHookShimName, parseCacheConfig, removeHookShim } from './hooks/cache.js';
 import { getHookShimsDir } from './state.js';
+function hookContentHash(scriptPath) {
+    return crypto.createHash('sha256').update(fs.readFileSync(scriptPath)).digest('hex');
+}
+/**
+ * Inspect every installed hooks-capable harness without assuming a native
+ * settings format. Same-name copies with one content hash are installation
+ * noise; multiple hashes are drift. The active version is always selected as
+ * the authoritative copy when it participates in the group.
+ */
+export function inspectDuplicateVersionHooks(cwd = process.cwd()) {
+    const byResource = new Map();
+    for (const { agent, version } of iterHooksCapableVersions()) {
+        const activeVersion = resolveVersion(agent, cwd);
+        for (const entry of listHooksInVersionHome(agent, version)) {
+            let hash;
+            try {
+                hash = hookContentHash(entry.scriptPath);
+            }
+            catch {
+                continue;
+            }
+            const copy = {
+                agent,
+                version,
+                name: entry.name,
+                path: entry.scriptPath,
+                hash,
+                active: version === activeVersion,
+            };
+            const key = `${agent}\0${entry.name}`;
+            const copies = byResource.get(key) ?? [];
+            copies.push(copy);
+            byResource.set(key, copies);
+        }
+    }
+    const findings = [];
+    for (const copies of byResource.values()) {
+        if (copies.length < 2)
+            continue;
+        copies.sort((a, b) => a.version.localeCompare(b.version, undefined, { numeric: true }));
+        const authoritative = copies.find((copy) => copy.active) ?? copies[copies.length - 1];
+        findings.push({
+            agent: authoritative.agent,
+            name: authoritative.name,
+            kind: new Set(copies.map((copy) => copy.hash)).size === 1 ? 'duplicate' : 'drift',
+            authoritative,
+            copies,
+        });
+    }
+    return findings.sort((a, b) => `${a.agent}/${a.name}`.localeCompare(`${b.agent}/${b.name}`));
+}
 /**
  * Resolve the command path to register for a hook.
  *
@@ -1351,8 +1455,9 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
         for (const group of eventEntries) {
             if (!group.hooks)
                 continue;
-            group.hooks = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
+            const managed = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
                 !isStaleSiblingVersionCommand(h.command, currentVh));
+            group.hooks = collapseVersionHookEntries(managed, versionHome);
         }
     }
     // Remove empty matcher groups left after cleanup
@@ -1509,8 +1614,9 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
         for (const group of eventGroups) {
             if (!group.hooks)
                 continue;
-            group.hooks = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
+            const managed = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
                 !isStaleSiblingVersionCommand(h.command, currentVh));
+            group.hooks = collapseVersionHookEntries(managed, versionHome);
         }
     }
     for (const [event, eventGroups] of Object.entries(hooksFile.hooks)) {

package/dist/lib/menubar/install-menubar.d.ts

@@ -124,6 +124,28 @@ export declare function disableMenubarService(): void;
  * Best-effort — never throws into startup.
  */
 export declare function installMenubarLaunchAgentOnUpgrade(): void;
+/** A live MenubarHelper process: its pid and the executable it is running. */
+export interface MenubarProcess {
+    pid: number;
+    executable: string;
+}
+/**
+ * Split the live MenubarHelper processes into the installed bundle's own
+ * (`running`) and every other copy (`foreign`).
+ *
+ * `pgrep -f MenubarHelper` conflated the two, so a stray dev build could hold
+ * the global Cmd-Shift-V chord (RegisterEventHotKey is first-come) while status
+ * still reported a healthy `running: yes` — the paste was dead and nothing said
+ * so. A foreign copy is the thing to look for, so name it.
+ *
+ * Identity comes from `comm` (the resolved executable), never from a substring
+ * of the command line: matching the latter flags any shell that merely mentions
+ * MenubarHelper. `command` is consulted only to drop `--notify` one-shots.
+ */
+export declare function classifyMenubarProcesses(commOutput: string, commandOutput: string, installedExec: string): {
+    running: boolean;
+    foreign: MenubarProcess[];
+};
 export interface MenubarStatus {
     platform: string;
     source: string | null;
@@ -133,6 +155,8 @@ export interface MenubarStatus {
     stale: boolean;
     serviceInstalled: boolean;
     running: boolean;
+    /** Live MenubarHelper processes that are NOT the installed bundle. */
+    foreignInstances: MenubarProcess[];
     disabledByUser: boolean;
 }
 export declare function getMenubarStatus(): MenubarStatus;

package/dist/lib/menubar/install-menubar.js

@@ -441,12 +441,61 @@ export function installMenubarLaunchAgentOnUpgrade() {
         /* never block startup on the menu bar */
     }
 }
+/** Parse `ps -axo pid=,<field>=` into pid -> field. The field is the rest of the
+ *  line, so a path containing spaces (App Support does) survives intact. */
+function parsePsLines(psOutput) {
+    const out = new Map();
+    for (const line of psOutput.split('\n')) {
+        const m = /^\s*(\d+)\s+(.+)$/.exec(line);
+        if (m)
+            out.set(Number(m[1]), m[2]);
+    }
+    return out;
+}
+/**
+ * Split the live MenubarHelper processes into the installed bundle's own
+ * (`running`) and every other copy (`foreign`).
+ *
+ * `pgrep -f MenubarHelper` conflated the two, so a stray dev build could hold
+ * the global Cmd-Shift-V chord (RegisterEventHotKey is first-come) while status
+ * still reported a healthy `running: yes` — the paste was dead and nothing said
+ * so. A foreign copy is the thing to look for, so name it.
+ *
+ * Identity comes from `comm` (the resolved executable), never from a substring
+ * of the command line: matching the latter flags any shell that merely mentions
+ * MenubarHelper. `command` is consulted only to drop `--notify` one-shots.
+ */
+export function classifyMenubarProcesses(commOutput, commandOutput, installedExec) {
+    const commands = parsePsLines(commandOutput);
+    const foreign = [];
+    let running = false;
+    for (const [pid, executable] of parsePsLines(commOutput)) {
+        if (path.basename(executable) !== 'MenubarHelper')
+            continue;
+        // `--notify` is a one-shot that posts a notification and exits; it runs the
+        // installed binary but never claims the status item or the chords.
+        if ((commands.get(pid) || '').includes('--notify'))
+            continue;
+        if (executable === installedExec)
+            running = true;
+        else
+            foreign.push({ pid, executable });
+    }
+    return { running, foreign };
+}
 export function getMenubarStatus() {
     const dest = installedAppPath();
     let running = false;
+    let foreignInstances = [];
     if (onDarwin()) {
-        const r = spawnSync('pgrep', ['-f', 'MenubarHelper'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
-        running = r.status === 0 && (r.stdout || '').trim().length > 0;
+        const ps = (format) => spawnSync('ps', ['-axo', format], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
+        const comm = ps('pid=,comm=');
+        const command = ps('pid=,command=');
+        if (comm.status === 0 && command.status === 0) {
+            const c = classifyMenubarProcesses(comm.stdout || '', command.stdout || '', installedExecutablePath());
+            running = c.running;
+            foreignInstances = c.foreign;
+        }
     }
     const serviceInstalled = menubarServiceInstalled();
     return {
@@ -458,6 +507,7 @@ export function getMenubarStatus() {
         stale: onDarwin() && serviceInstalled && menubarSetupStale(),
         serviceInstalled,
         running,
+        foreignInstances,
         disabledByUser: menubarDisabledByUser(),
     };
 }