@phnx-labs/agents-cli 1.20.52 → 1.20.53

package/dist/commands/message.js

@@ -1,15 +1,119 @@
 import chalk from 'chalk';
+import { spawn } from 'child_process';
 import { die } from '../lib/format.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { getTaskById, updateTaskStatus } from '../lib/cloud/store.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { mailboxDir, enqueue } from '../lib/mailbox.js';
-import { resolveMessageTarget } from '../lib/mailbox-target.js';
+import { resolveMessageTarget, mailboxIdForActiveSession } from '../lib/mailbox-target.js';
+import { blockIdForSession, listBlocks, readBlock, recordAnswer, recordMessageReceipt, } from '../lib/feed.js';
+import { verifyOperatorIdentity } from '../lib/operator.js';
+import { resolveAnswerRoute, resumeArgv, } from '../lib/answer-router.js';
+import { injectIntoTerminal } from '../lib/terminal/inject.js';
+/** Find the still-open block addressed to `mailboxId`, if any. */
+function findOpenBlockForMailbox(mailboxId) {
+    // Fast path: the mailbox id is usually the session id, so the block id is
+    // directly derivable. This avoids scanning the whole feed store.
+    const direct = readBlock(blockIdForSession(mailboxId));
+    if (direct && direct.mailboxId === mailboxId)
+        return direct;
+    // Fallback: scan (agentId-based mailbox ids, rare).
+    return listBlocks().find((b) => b.mailboxId === mailboxId);
+}
+/** Live session whose mailbox id equals `mailboxId`. */
+function findSessionForMailbox(mailboxId, sessions) {
+    return sessions.find((s) => mailboxIdForActiveSession(s) === mailboxId);
+}
+/** Claim first-answer-wins on the open block; dies if already answered / unauthorized. */
+function claimBlockAnswer(block, opts) {
+    if (!block)
+        return;
+    const operatorId = opts.as;
+    // High-consequence answers require env-proven identity (AGENTS_OPERATOR_ID),
+    // not merely a caller-supplied known --as id (RUSH-1619).
+    const verified = verifyOperatorIdentity(operatorId);
+    const claim = recordAnswer(block.blockId, {
+        answeredBy: opts.from,
+        answeredFrom: opts.surface || 'cli',
+        operatorId,
+        verified,
+    });
+    if (!claim.ok) {
+        if ('unauthorized' in claim) {
+            die(`Not authorized: ${claim.reason}`);
+        }
+        const who = claim.existing.answeredFrom + (claim.existing.answeredBy ? ` (${claim.existing.answeredBy})` : '');
+        die(`This question was already answered by ${who}.`);
+    }
+}
+async function deliverViaMailbox(mailboxId, text, block, opts) {
+    const msgId = enqueue(mailboxDir(mailboxId), {
+        to: mailboxId,
+        text,
+        from: opts.from,
+        blockId: block?.blockId,
+    });
+    if (block) {
+        recordMessageReceipt(block.blockId, {
+            msgId,
+            status: 'queued',
+            at: new Date().toISOString(),
+            from: opts.from,
+        });
+        console.log(chalk.green(`Queued message ${msgId} for ${mailboxId}. `) +
+            chalk.dim(`Answer tied to ${block.blockId}; the agent will see it at its next tool call.`));
+    }
+    else {
+        console.log(chalk.green(`Queued message ${msgId} for ${mailboxId}. `) +
+            chalk.dim('The agent will see it at its next tool call.'));
+    }
+}
+async function deliverViaInject(route, mailboxId) {
+    if (!route.inject || route.payload == null) {
+        die(`Internal error: inject route missing target/payload for ${mailboxId}.`);
+    }
+    const result = await injectIntoTerminal(route.inject, route.payload, {
+        // Digit selection and free text both need Enter to submit the TUI choice.
+        enter: true,
+        // Digit+Enter as two writes is safer for Ink TUI.
+        combined: false,
+    });
+    if (!result.ok) {
+        die(`Failed to inject answer into ${route.inject.backend}: ${result.error ?? 'unknown error'}`);
+    }
+    console.log(chalk.green(`Answered ${mailboxId} via ${route.inject.backend}. `) +
+        chalk.dim(route.reason));
+}
+async function deliverViaResume(route, mailboxId) {
+    if (route.kind !== 'resume') {
+        die(`Internal error: resume route incomplete for ${mailboxId}.`);
+    }
+    const argv = resumeArgv(route);
+    // Spawn the same agents binary the user invoked (process.argv[1]) so version
+    // pins and wrappers stay consistent. Detach so the resume can take over a TTY
+    // when interactive; for feed answers we pass the prompt non-interactively.
+    const bin = process.argv[1] ?? 'agents';
+    const child = spawn(process.execPath, [bin, ...argv], {
+        stdio: 'inherit',
+        env: process.env,
+    });
+    const code = await new Promise((resolve) => {
+        child.on('exit', (c) => resolve(c ?? 1));
+        child.on('error', () => resolve(1));
+    });
+    if (code !== 0) {
+        die(`Resume of ${mailboxId} exited with code ${code}. Tried: agents ${argv.join(' ')}`);
+    }
+    console.log(chalk.green(`Resumed ${mailboxId} with answer. `) +
+        chalk.dim(route.reason));
+}
 export function registerMessageCommand(program) {
     program
         .command('message <target> <text>')
-        .description('Send a message to a running agent (delivered at its next tool call) or a cloud task.')
+        .description('Send a message to a running or parked agent (mailbox / PTY-select / resume by runtime).')
         .option('--from <who>', 'Label recorded as the sender of this message')
+        .option('--as <operator>', 'Verified operator id answering a high-consequence block')
+        .option('--surface <surface>', 'Surface that is sending this answer (feed, terminal, etc.)', 'cli')
         .action(async (target, text, opts) => {
         if (!target.trim()) {
             die('Target must be a session/agent id or cloud task id. Run `agents sessions --active` to list running agents.');
@@ -32,9 +136,40 @@ export function registerMessageCommand(program) {
             }
             case 'local': {
                 try {
-                    const msgId = enqueue(mailboxDir(res.id), { to: res.id, text, from: opts.from });
-                    console.log(chalk.green(`Queued message ${msgId} for ${res.id}. `) +
-                        chalk.dim('The agent will see it at its next tool call.'));
+                    const block = findOpenBlockForMailbox(res.id);
+                    const session = findSessionForMailbox(res.id, sessions);
+                    const route = resolveAnswerRoute({
+                        mailboxId: res.id,
+                        answer: text,
+                        block,
+                        session,
+                    });
+                    if (route.kind === 'refuse') {
+                        die(route.reason);
+                    }
+                    // First-answer-wins for any path that closes an open block.
+                    claimBlockAnswer(block, opts);
+                    if (route.kind === 'mailbox') {
+                        await deliverViaMailbox(res.id, text, block, opts);
+                        return;
+                    }
+                    if (route.kind === 'tmux' || route.kind === 'iterm' || route.kind === 'pty') {
+                        await deliverViaInject(route, res.id);
+                        if (block) {
+                            recordMessageReceipt(block.blockId, {
+                                msgId: `inject-${Date.now()}`,
+                                status: 'queued',
+                                at: new Date().toISOString(),
+                                from: opts.from,
+                            });
+                        }
+                        return;
+                    }
+                    if (route.kind === 'resume') {
+                        await deliverViaResume(route, res.id);
+                        return;
+                    }
+                    die(`Unknown delivery route: ${route.kind}`);
                 }
                 catch (err) {
                     die(err.message);

package/dist/commands/routines.js

@@ -156,6 +156,18 @@ export function registerRoutinesCommands(program) {
 
       The background scheduler auto-starts the first time you add a routine.
       Manage it with 'agents routines start|stop|status'.
+
+      Version / credit failover (same semantics as 'agents run'):
+        - Omit 'version:' to let the configured run strategy (default: balanced)
+          pick a healthy install and skip accounts that are out of credits or
+          rate-limited. Pin with 'version: 2.1.x' when you want one install only.
+        - Foreground 'agents routines run' re-dispatches to the next healthy
+          same-agent account when a mid-run rate/usage limit is detected.
+        - Detached/daemon fires use the pre-flight pick only (next tick re-selects).
+        - Diagnostic lines log which account was picked, which were skipped, and
+          each failover hop: look for "[agents] routine <name>:" in the run log.
+        - Headless Claude auth: store CLAUDE_CODE_OAUTH_TOKEN in the 'claude'
+          secrets bundle so the daemon can inject it into routine spawns.
     `,
     });
     routinesCmd

package/dist/commands/secrets-migrate.d.ts

@@ -20,5 +20,6 @@
  * writes and produces the backup.
  */
 import type { Command } from 'commander';
-/** Register `agents secrets migrate-acl` on the parent secrets Command. */
+/** Register the keychain-migration commands (`migrate-acl`, `rekey`) on the
+ * parent secrets Command. */
 export declare function registerSecretsMigrateAclCommand(secrets: Command): void;

package/dist/commands/secrets-migrate.js

@@ -23,21 +23,24 @@ import chalk from 'chalk';
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, listKeychainItems, listLegacyKeychainItems, listOrphanedKeychainItems, migrateOrphanedKeychainItems, setKeychainToken, } from '../lib/secrets/index.js';
+import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, listKeychainItems, listLegacyKeychainItems, listOrphanedKeychainItems, migrateOrphanedKeychainItems, rekeyServiceNames, rekeyStatus, setKeychainToken, withRawKeychainServiceNames, } from '../lib/secrets/index.js';
 import { getBackupsDir } from '../lib/state.js';
 import { encryptBlob, MIN_PASSPHRASE_LEN } from '../lib/secrets/sync.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 const ITEM_PREFIX = 'agents-cli.';
 function enumerateItems() {
     const seen = new Map();
-    for (const item of listKeychainItems(ITEM_PREFIX)) {
-        // hasKeychainToken with sync=false probes the non-synced keychain; the
-        // helper's list returns both. We don't try to distinguish — re-write with
-        // sync=false by default and only flip to sync=true if the value is only
-        // readable via the synced-only probe.
-        const localExists = hasKeychainToken(item);
-        seen.set(item, { item, sync: !localExists });
-    }
+    // Raw scope: operate on the literal enumerated names (see #316).
+    withRawKeychainServiceNames(() => {
+        for (const item of listKeychainItems(ITEM_PREFIX)) {
+            // hasKeychainToken with sync=false probes the non-synced keychain; the
+            // helper's list returns both. We don't try to distinguish — re-write with
+            // sync=false by default and only flip to sync=true if the value is only
+            // readable via the synced-only probe.
+            const localExists = hasKeychainToken(item);
+            seen.set(item, { item, sync: !localExists });
+        }
+    });
     return [...seen.values()];
 }
 function writeEncryptedBackup(records, passphrase) {
@@ -63,6 +66,12 @@ async function promptPassphrase() {
     return first;
 }
 function migrateOne(record) {
+    // Raw scope: `item` is a literal service name enumerated from the helper —
+    // possibly a pre-re-key cleartext leftover — and this rewrite must target
+    // exactly that item, never its hashed transform (see #316).
+    return withRawKeychainServiceNames(() => migrateOneRaw(record));
+}
+function migrateOneRaw(record) {
     const { item, value } = record;
     // Delete + re-add to force macOS to bind a fresh ACL on the new item.
     // SecItemUpdate preserves the existing ACL, so an in-place rewrite would
@@ -97,8 +106,10 @@ function migrateOne(record) {
     }
     return { item, status: 'ok' };
 }
-/** Register `agents secrets migrate-acl` on the parent secrets Command. */
+/** Register the keychain-migration commands (`migrate-acl`, `rekey`) on the
+ * parent secrets Command. */
 export function registerSecretsMigrateAclCommand(secrets) {
+    registerSecretsRekeyCommand(secrets);
     secrets
         .command('migrate-acl')
         .description('Refresh legacy keychain ACLs and re-home items stranded in a stale access group. Dry-run by default.')
@@ -122,9 +133,14 @@ export function registerSecretsMigrateAclCommand(secrets) {
             //       pre-#279 non-concrete group, invisible to the pinned queries.
             //       Re-homed by the helper behind a single Touch ID.
             // Default: only legacy stragglers for (a); `--all` forces a full rewrite.
-            const names = opts.all ? listKeychainItems(prefix) : listLegacyKeychainItems(prefix);
+            // Raw scope: migrate-acl operates on the literal names the helper
+            // enumerates (which may include pre-re-key cleartext leftovers) — the
+            // #316 name-hashing transform must not rewrite them.
+            const names = opts.all
+                ? withRawKeychainServiceNames(() => listKeychainItems(prefix))
+                : listLegacyKeychainItems(prefix);
             const items = names.map((item) => {
-                const localExists = hasKeychainToken(item);
+                const localExists = withRawKeychainServiceNames(() => hasKeychainToken(item));
                 return { item, sync: !localExists };
             });
             const orphans = listOrphanedKeychainItems(prefix);
@@ -160,7 +176,7 @@ export function registerSecretsMigrateAclCommand(secrets) {
             // read failure here counts the legacy items as failed but does NOT abort —
             // the orphan sweep (b) is independent and must still run.
             if (items.length > 0) {
-                const fetched = getKeychainTokens(items.map((i) => i.item));
+                const fetched = withRawKeychainServiceNames(() => getKeychainTokens(items.map((i) => i.item)));
                 const records = [];
                 for (const { item, sync } of items) {
                     const value = fetched.get(item);
@@ -257,3 +273,62 @@ export function registerSecretsMigrateAclCommand(secrets) {
         }
     });
 }
+/**
+ * `agents secrets rekey` — the one-time #316 migration: replace enumerable
+ * cleartext keychain service names (`agents-cli.secrets.<bundle>.<KEY>`, …)
+ * with opaque HMAC-hashed names. Normally runs automatically on the first
+ * interactive keychain use after upgrade; this command exists for headless
+ * machines, retrying after a cancelled Touch ID, and prefix-restricted test
+ * runs. Idempotent — safe to re-run any time.
+ */
+function registerSecretsRekeyCommand(secrets) {
+    secrets
+        .command('rekey')
+        .description('Replace enumerable keychain service names with opaque HMAC-hashed names (one-time; idempotent). macOS only.')
+        .option('--status', 'Report re-key state without changing anything')
+        .option('--prefix <p...>', 'Restrict to cleartext services starting with PREFIX (partial run: moves matching items but does NOT activate hashed naming)')
+        .action((opts) => {
+        try {
+            if (process.platform !== 'darwin') {
+                throw new Error('secrets rekey is macOS-only. Linux/Windows service names are not enumerable via the keychain helper.');
+            }
+            if (opts.status) {
+                const st = rekeyStatus();
+                console.log(st.migrated
+                    ? chalk.green('Hashed service names: ACTIVE')
+                    : chalk.yellow('Hashed service names: not yet active'));
+                console.log(`  HMAC key present: ${st.hasKey ? 'yes' : 'no'}`);
+                if (!st.enumerationOk) {
+                    console.log(chalk.red('  Keychain enumeration unavailable (locked keybag?) — counts below are unreliable.'));
+                }
+                console.log(`  Cleartext-named items remaining: ${st.cleartext.length}`);
+                if (st.pendingDeletes > 0) {
+                    console.log(chalk.yellow(`  Pending deletes from an interrupted run: ${st.pendingDeletes} (finished automatically on next use)`));
+                }
+                return;
+            }
+            for (const p of opts.prefix ?? []) {
+                if (!p.startsWith(ITEM_PREFIX)) {
+                    throw new Error(`--prefix must start with '${ITEM_PREFIX}' to avoid touching unrelated Keychain items (got '${p}').`);
+                }
+            }
+            const report = rekeyServiceNames({
+                prefixes: opts.prefix,
+                announce: true,
+                log: (line) => console.log(line),
+            });
+            if (report.failed.length > 0)
+                process.exit(1);
+            if (report.nothingToDo && report.activated) {
+                console.log(chalk.green('Nothing to re-key — hashed service names are active.'));
+            }
+        }
+        catch (err) {
+            const msg = err.message;
+            console.error(chalk.red(msg));
+            // Touch ID cancel exits 4 (matching the helper's contract); re-running
+            // resumes where it left off.
+            process.exit(/touch id cancelled/i.test(msg) ? 4 : 1);
+        }
+    });
+}

package/dist/commands/secrets.js

@@ -208,10 +208,13 @@ async function importFromICloud(bundleName, opts) {
             parts.push(`skipped ${result.skipped} (already set, pass --force)`);
         if (result.missing.length)
             parts.push(`unreadable (left in iCloud): ${result.missing.join(', ')}`);
+        if (result.unimportable.length)
+            parts.push(`reserved, not importable (left in iCloud): ${result.unimportable.join(', ')}`);
         if (opts.purge)
             parts.push(`purged ${result.purged} iCloud item(s)`);
         const line = `${candidate.name}: ${parts.join(', ')}`;
-        console.log(result.missing.length ? chalk.yellow(line) : chalk.green(line));
+        const warn = result.missing.length > 0 || result.unimportable.length > 0;
+        console.log(warn ? chalk.yellow(line) : chalk.green(line));
     }
 }
 /**

package/dist/commands/sessions.js

@@ -25,7 +25,7 @@ import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { gatherRemoteActive, NO_FANOUT_ENV } from '../lib/session/remote-active.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
 import { stringWidth, truncateToWidth, padToWidth, terminalWidth } from '../lib/session/width.js';
-import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex } from '../lib/session/discover.js';
+import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex, getSessionRoots } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
 import { runRemoteSessions, buildForwardedArgs } from '../lib/session/remote.js';
@@ -796,6 +796,14 @@ async function sessionsAction(query, options) {
     if (options.device && options.device.length > 0) {
         options.host = [...(options.host ?? []), ...options.device];
     }
+    // --roots: emit the local session-scan directories, per agent, as JSON. A pure
+    // machine-readable query (no listing/render) — external watchers (the Factory
+    // extension's fs.watch) read it to track the same dirs the CLI scans, instead
+    // of hardcoding `~/.claude|.codex|.gemini`. Always local; ignores other flags.
+    if (options.roots) {
+        process.stdout.write(JSON.stringify(getSessionRoots(), null, 2) + '\n');
+        return;
+    }
     // --host WITHOUT --active. `--json` fans the recent listing out and emits ONE
     // clean merged SessionMeta[] array (same shape as the local --json path), for
     // scripts/extensions that JSON.parse a remote's history. Without --json it
@@ -2047,6 +2055,7 @@ export function registerSessionsCommands(program) {
         .option('--artifacts', 'List all files written or edited during a session')
         .option('--artifact <name>', 'Read a specific artifact by filename or path (outputs to stdout)')
         .option('--active', 'Show only sessions running right now across terminals, teams, cloud, and headless agents')
+        .option('--roots', 'With --json: emit the on-disk directories scanned for session transcripts, per agent (for external watchers)')
         .option('--local', 'Only this machine — skip the cross-machine SSH fan-out (default listing and --active)')
         .option('--waiting', 'With --active: show only sessions waiting on your input (exits non-zero if any)')
         .option('--tree', 'Group the listing by directory; drops the id/version columns for readability')

package/dist/commands/worktree.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
 import { die } from '../lib/format.js';
+import { getGitRoot } from '../lib/git.js';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import * as fs from 'fs/promises';
@@ -14,10 +15,11 @@ function isValidTerminalId(id) {
     // hostile or buggy caller can't inject path traversal or shell metachars.
     return /^[A-Za-z0-9._-]+$/.test(id) && id.length > 0 && id.length <= 128;
 }
+// Thin command-layer wrapper over the shared lib/git.ts `getGitRoot`: turns its
+// throw into a clean `die()` message. The git plumbing lives in one place now.
 async function gitRoot(cwd) {
     try {
-        const { stdout } = await execFileAsync('git', ['rev-parse', '--show-toplevel'], { cwd });
-        return stdout.trim();
+        return await getGitRoot(cwd);
     }
     catch {
         die(`Not inside a git repo: ${cwd}`);

package/dist/index.js

@@ -50,7 +50,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadFeed, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadFeed, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { emit, redactArgs } from './lib/events.js';
@@ -73,6 +73,7 @@ program
     .name('agents')
     .description('Environment manager for AI agents')
     .version(VERSION)
+    .option('--verbose', 'Show startup self-heal details on stderr')
     .helpOption('-h, --help', 'Show help')
     .addHelpCommand(false);
 // ─── Audit backbone ────────────────────────────────────────────────────────────
@@ -207,6 +208,7 @@ Automation tips:
 Options:
   -V, --version                   Show version number
   -h, --help                      Show help
+  --verbose                       Show startup self-heal details on stderr
 
 System config lives in ~/.agents/.system/. Run 'agents <command> --help' for details.
 `;
@@ -464,8 +466,8 @@ async function checkForUpdates() {
         }
     }
 }
-async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequested) {
-    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequested, verboseStartup) {
+    if (!verboseStartup && (!process.stdin.isTTY || !process.stdout.isTTY)) {
         return;
     }
     // Pure documentation paths must never trigger interactive repair — mirrors
@@ -487,8 +489,12 @@ async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequ
     // (a real native binary shadowing the shim) or is worth saying once (a PATH entry
     // just added). Suppression is persistent and keyed to the condition — a new
     // terminal no longer re-nags (the old per-PPID sentinel did, every shell).
-    const { healShimsInteractive } = await import('./lib/shim-heal.js');
-    const noticeLines = await healShimsInteractive();
+    const { runInteractiveShimHeal } = await import('./lib/shim-heal.js');
+    const { summarizeSelfHeal } = await import('./lib/self-heal/registry.js');
+    const { noticeLines, report } = await runInteractiveShimHeal();
+    if (verboseStartup) {
+        process.stderr.write(`[agents] startup self-heal: ${summarizeSelfHeal(report)}\n`);
+    }
     if (noticeLines) {
         for (const line of noticeLines)
             console.log(chalk.gray(line));
@@ -499,17 +505,8 @@ async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequ
 // close over entry-point-local state (program re-parsing, VERSION, the npm
 // upgrade helpers). The lazy registrar and the all-commands fallback below both
 // call them, so the behavior is identical to the old eager registration.
-/** Deprecated `memory` command — hard error pointing users at `rules`. */
-function registerMemoryCommand(p) {
-    p.command('memory', { hidden: true })
-        .allowUnknownOption()
-        .allowExcessArguments()
-        .action(() => {
-        console.error(chalk.red('"agents memory" has been renamed to "agents rules".'));
-        console.error(chalk.gray('Run "agents rules --help" for usage.\n'));
-        process.exit(1);
-    });
-}
+// memory is a first-class resource command (see commands/memory.ts via
+// COMMAND_LOADERS). The old memory→rules tombstone was removed in RUSH-1330.
 /** Deprecated `perms` alias — re-parses as `permissions`. */
 function registerPermsAliasCommand(p) {
     p.command('perms', { hidden: true })
@@ -616,9 +613,6 @@ async function reg(loader) {
  */
 async function registerEagerForRequest(name) {
     switch (name) {
-        case 'memory':
-            registerMemoryCommand(program);
-            return true;
         case 'perms':
             // The action re-parses as `permissions`, so that target must exist too.
             registerPermsAliasCommand(program);
@@ -659,7 +653,7 @@ async function registerAllEagerCommands() {
     await reg(loadHooks);
     await reg(loadSkills);
     await reg(loadRules);
-    registerMemoryCommand(program);
+    await reg(loadMemory);
     await reg(loadPermissions);
     registerPermsAliasCommand(program);
     await reg(loadMcp);
@@ -768,6 +762,7 @@ program.on('command:*', (operands) => {
 // and whether the update check + background sync run at all.
 const passedArgs = process.argv.slice(2);
 const requestedCommand = passedArgs.find((arg) => !arg.startsWith('-'));
+const verboseStartup = passedArgs.includes('--verbose');
 // Help and version output are pure documentation — they must never gate on
 // setup, otherwise `agents <cmd> --help` becomes useless on a fresh box.
 const helpOrVersionRequested = passedArgs.some((arg) => arg === '--help' || arg === '-h' || arg === '--version' || arg === '-V');
@@ -922,7 +917,7 @@ if (passedArgs.length === 0) {
     process.exit(0);
 }
 try {
-    await maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequested);
+    await maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequested, verboseStartup);
     await program.parseAsync();
 }
 catch (err) {