@phnx-labs/agents-cli 1.22.74 → 1.22.76

package/dist/lib/daemon/daemon.js

@@ -32,6 +32,7 @@ import { isSchedulerEnabled, assertSchedulerEnabled, isDaemonEnabled } from '../
 import { recordSubsystemOk, recordSubsystemError, recordSubsystemErrorReason, readSubsystemHealth, SUBSYSTEM_DAEMON_START } from '../daemon-health.js';
 import { ServiceSupervisor } from './supervisor.js';
 import { SessionIndexService } from './session-index-service.js';
+import { SessionSummarizerService } from './session-summarizer-service.js';
 import { SecretsBrokerService } from './secrets-broker-service.js';
 import { MonitorEngineService } from './monitor-engine-service.js';
 import { AccountUsageService, AccountAuthService } from './account-state-daemon-service.js';
@@ -271,7 +272,7 @@ function acquireStartLock() {
  */
 const STOP_LOCK_WAIT_MS = 10_000;
 const STOP_LOCK_POLL_MS = 50;
-function acquireStopLock() {
+function acquireLifecycleLock() {
     const deadline = Date.now() + STOP_LOCK_WAIT_MS;
     for (;;) {
         const release = acquireStartLock();
@@ -481,14 +482,13 @@ export function isDaemonRunning() {
  * liveness check and the write.
  */
 export function claimDaemonInstance() {
-    const release = acquireStartLock();
-    // acquireStartLock() returns null only when another __daemon-run currently
-    // holds the O_EXCL lock — a dead holder's lock is reclaimed and retried inside
-    // acquireStartLock, so null means a *live* claimer is mid-claim. Bail rather
-    // than run the read-evict-write unlocked: otherwise two first-start processes
-    // could each see no pid file (before either writes one) and both claim,
-    // running the concurrent JobScheduler this guard exists to prevent. The live
-    // claimer we bailed for becomes the singleton, so last-wins still holds.
+    // A stop owns this same lock through teardown. Waiting here is load-bearing:
+    // returning false while stopDaemon() holds it lets this replacement exit 0,
+    // then the stop completes with no singleton left alive. The bounded lifecycle
+    // acquisition also preserves concurrent-start serialization: after the first
+    // claimer publishes its pid, the waiter takes the lock and performs the normal
+    // last-wins takeover rather than ever running the read-evict-write unlocked.
+    const release = acquireLifecycleLock();
     if (!release)
         return false;
     try {
@@ -1063,6 +1063,13 @@ export async function runDaemon() {
         supervisor.register(new SessionIndexService());
     else
         log('INFO', 'Session-index warm service disabled');
+    // Session summarizer (PHNX-3939) — registered when the service toggle is on,
+    // but each tick is a no-op unless the operator also set summarizer.enabled and
+    // a model endpoint, so registering it costs nothing while unconfigured.
+    if (isEnabled('session-summarizer'))
+        supervisor.register(new SessionSummarizerService());
+    else
+        log('INFO', 'Session summarizer service disabled');
     // Watchdog, device-probe, self-heal, and keychain-reap are all periodic
     // services managed by the ServiceSupervisor (RUSH-3193 P3). Each is gated
     // the same way as the socket services above; state-dir-check is registered
@@ -2205,7 +2212,7 @@ export function findSurvivingStateDirDaemons(exclude) {
  * never reports success on an unverified stop.
  */
 export function stopDaemon() {
-    const releaseLock = acquireStopLock();
+    const releaseLock = acquireLifecycleLock();
     if (!releaseLock) {
         return {
             ok: false,

package/dist/lib/daemon/session-summarizer-service.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Session-summarizer service (PHNX-3939).
+ *
+ * The single daemon-owned executor that computes a per-session goal / progress
+ * checkpoints / checklist and writes them to the transcript-keyed
+ * `session_summaries` cache, from which the display/merge path serves them onto
+ * the `sessions watch` stream. It NEVER runs on a request path.
+ *
+ * Off by default: `runSummarizerPass` no-ops unless `summarizer.enabled` and a
+ * model endpoint (`summarizer.baseUrl` + `summarizer.model`) are configured, so a
+ * daemon with the feature unconfigured makes zero model calls. Reader-gated and
+ * bounded per tick like the other session services, so it costs nothing while no
+ * one is watching.
+ */
+import { BasePeriodicService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export declare class SessionSummarizerService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs = 20000;
+    readonly deadlineMs = 60000;
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext, signal: AbortSignal): Promise<void>;
+}

package/dist/lib/daemon/session-summarizer-service.js

@@ -0,0 +1,39 @@
+/**
+ * Session-summarizer service (PHNX-3939).
+ *
+ * The single daemon-owned executor that computes a per-session goal / progress
+ * checkpoints / checklist and writes them to the transcript-keyed
+ * `session_summaries` cache, from which the display/merge path serves them onto
+ * the `sessions watch` stream. It NEVER runs on a request path.
+ *
+ * Off by default: `runSummarizerPass` no-ops unless `summarizer.enabled` and a
+ * model endpoint (`summarizer.baseUrl` + `summarizer.model`) are configured, so a
+ * daemon with the feature unconfigured makes zero model calls. Reader-gated and
+ * bounded per tick like the other session services, so it costs nothing while no
+ * one is watching.
+ */
+import { BasePeriodicService } from './service.js';
+import { runSummarizerPass } from '../summarizer/pass.js';
+/** Slower than the state tick — a summary is a coarse signal, not live status. */
+const SESSION_SUMMARIZER_TICK_MS = 20_000;
+/** Hard cap per tick; a local model call is bounded, this leaves generous headroom. */
+const SESSION_SUMMARIZER_DEADLINE_MS = 60_000;
+export class SessionSummarizerService extends BasePeriodicService {
+    id = 'session-summarizer';
+    intervalMs = SESSION_SUMMARIZER_TICK_MS;
+    deadlineMs = SESSION_SUMMARIZER_DEADLINE_MS;
+    async onStart(_ctx) {
+        // No handles to open — each tick reads config + the warm session cache fresh.
+    }
+    async onStop() {
+        // Nothing to release.
+    }
+    async onTick(ctx, signal) {
+        const r = await runSummarizerPass({ signal });
+        if (r.disabled)
+            return; // off / unconfigured — stay silent
+        if (r.computed > 0 || r.skipped > 0) {
+            ctx.log('INFO', `session-summarizer: computed ${r.computed}, skipped ${r.skipped}, reused ${r.reused}`);
+        }
+    }
+}

package/dist/lib/daemon/usage-sync-service.js

@@ -48,6 +48,9 @@ export class UsageSyncService extends BasePeriodicService {
             ctx.log('WARN', `usage-sync: ${transport.skipped}`);
         if (transport.error)
             ctx.log('WARN', `usage-sync: shared-store transport: ${transport.error}`);
+        if (transport.untrackedBackedUp?.length) {
+            ctx.log('WARN', `usage-sync: backed up ${transport.untrackedBackedUp.length} untracked shared-store collision(s) to ${transport.untrackedBackupDir}: ${transport.untrackedBackedUp.join(', ')}`);
+        }
         if (!transport.success)
             return;
         const consumed = consumeUsageSnapshotsFromSharedStore();

package/dist/lib/daemon-services.d.ts

@@ -7,7 +7,7 @@
  * enabled without pulling in the whole daemon lifecycle.
  */
 /** Every service the daemon can host. IDs are kebab-case and stable. */
-export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'catchup' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'self-update' | 'keychain-reap' | 'account-state' | 'account-auth' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state';
+export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'catchup' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'self-update' | 'keychain-reap' | 'account-state' | 'account-auth' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state' | 'session-summarizer';
 /** Human-readable metadata for each service. */
 export interface DaemonServiceDef {
     id: DaemonServiceId;

package/dist/lib/daemon-services.js

@@ -107,6 +107,11 @@ export const DAEMON_SERVICES = [
         title: 'Session-index warm',
         description: 'Keeps this host\'s transcript index current so a locally-started session is discoverable within seconds.',
     },
+    {
+        id: 'session-summarizer',
+        title: 'Session summarizer',
+        description: 'Computes a per-session goal / progress checkpoints / checklist off the request path and delivers them on the session stream. Off unless summarizer.enabled and a local model endpoint are configured (PHNX-3939).',
+    },
     {
         id: 'auth-sync',
         title: 'Auth bundle sync',

package/dist/lib/daemon-ticks.d.ts

@@ -15,7 +15,8 @@
  * timer converge on the same published result.
  */
 import type { FleetStatusRow } from './fleet-status.js';
-import type { AuthProbeRow } from './auth-health.js';
+import { type AuthProbeRow } from './auth-health.js';
+export { AUTH_PROBE_MAX_AGE_MS } from './auth-health.js';
 export declare function isFreshFleetAuthSnapshot(value: {
     row: FleetStatusRow;
     authRows: AuthProbeRow[];
@@ -34,7 +35,6 @@ export declare function isFreshFleetAuthSnapshot(value: {
  * that would blind every non-primary box to revocation. Fleet status still
  * publishes every tick — it does not ride that endpoint.
  */
-export declare const AUTH_PROBE_MAX_AGE_MS: number;
 /**
  * True when every cached auth row was probed within {@link AUTH_PROBE_MAX_AGE_MS}
  * — i.e. reusing them would not let a verdict get staler than one probe window.

package/dist/lib/daemon-ticks.js

@@ -14,6 +14,8 @@
  * by the cross-process refresh lease so an explicit CLI refresh and the daemon
  * timer converge on the same published result.
  */
+import { AUTH_PROBE_MAX_AGE_MS } from './auth-health.js';
+export { AUTH_PROBE_MAX_AGE_MS } from './auth-health.js';
 export function isFreshFleetAuthSnapshot(value, minimumCapturedAt) {
     return value.row.capturedAt >= minimumCapturedAt
         && value.authRows.length > 0
@@ -33,7 +35,6 @@ export function isFreshFleetAuthSnapshot(value, minimumCapturedAt) {
  * that would blind every non-primary box to revocation. Fleet status still
  * publishes every tick — it does not ride that endpoint.
  */
-export const AUTH_PROBE_MAX_AGE_MS = 20 * 60_000;
 /**
  * True when every cached auth row was probed within {@link AUTH_PROBE_MAX_AGE_MS}
  * — i.e. reusing them would not let a verdict get staler than one probe window.

package/dist/lib/daemon-webhooks.js

@@ -18,6 +18,7 @@ import * as yaml from 'yaml';
 import { exec } from 'child_process';
 import { getDaemonConfigDir, getRuntimeStateDir } from './state.js';
 import { atomicWriteFileSync } from './fs-atomic.js';
+import { closeServerBounded } from './secrets/agent.js';
 import { readAndResolveBundleEnv } from './secrets/bundles.js';
 import { startWebhookServer, createFileDeliveryStore, waitForListening } from './triggers/webhook.js';
 import { buildFunnelUpCommand, FUNNEL_PORTS } from './funnel.js';
@@ -195,8 +196,13 @@ export async function startHostedWebhookReceivers(opts) {
                     log('WARN', `webhook ${webhook.source}:${webhook.event} dispatch failed after ack: ${err.message}`);
                 },
             });
+            const sockets = new Set();
+            server.on('connection', (socket) => {
+                sockets.add(socket);
+                socket.once('close', () => sockets.delete(socket));
+            });
             await waitForListening(server);
-            servers.push(server);
+            servers.push({ server, sockets });
             log('INFO', `webhook receiver bound on 127.0.0.1:${port} (bundle ${receiver.bundle})`);
             if (receiver.funnel)
                 reconcileFunnel(receiver.funnel.publicPort, port, log);
@@ -210,6 +216,13 @@ export async function startHostedWebhookReceivers(opts) {
     }
     return {
         count: servers.length,
-        close: () => Promise.all(servers.map((s) => new Promise((resolve) => s.close(() => resolve())))).then(() => undefined),
+        close: () => Promise.all(servers.map(async ({ server, sockets }) => {
+            // Stop accepting first, then force every persistent HTTP connection
+            // closed so keep-alive cannot hold daemon shutdown open indefinitely.
+            const closing = closeServerBounded(server);
+            for (const socket of sockets)
+                socket.destroy();
+            await closing;
+        })).then(() => undefined),
     };
 }

package/dist/lib/deeplink/register.js

@@ -1,6 +1,7 @@
 /**
  * Register the `agents://` URL scheme with the OS so a click in an artifact
- * routes to `agents open <url>` (see url.ts + commands/open.ts).
+ * routes to the machine-only `agents _callback <url>` verb (see url.ts +
+ * commands/open.ts). Humans manage the handler with `agents setup url-scheme`.
  *
  * A browser page cannot spawn a shell; a registered URL scheme is the
  * OS-sanctioned hand-off. Each platform gets its own handler:
@@ -13,8 +14,8 @@
  *
  * The content generators below are pure and unit-tested. The `register*` /
  * `unregister*` / `status*` functions apply them and never throw — they return a
- * {@link SchemeStatus} so callers (setup, `agents open register`, doctor) can
- * report without a try/catch.
+ * {@link SchemeStatus} so callers (setup, `agents setup url-scheme register`,
+ * doctor) can report without a try/catch.
  */
 import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs';
@@ -73,7 +74,7 @@ export function linuxDesktopEntry(invocation) {
         'Type=Application',
         'Name=Agents URL Handler',
         'Comment=Resume an agents session from an agents:// deep link',
-        `Exec=${invocation} open %u`,
+        `Exec=${invocation} _callback %u`,
         'Terminal=false',
         'NoDisplay=true',
         'MimeType=x-scheme-handler/agents;',
@@ -91,7 +92,7 @@ export function macAppleScriptSource(invocation) {
     const literal = invocation.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
     return [
         'on open location this_URL',
-        `\tdo shell script "${literal} open " & quoted form of this_URL`,
+        `\tdo shell script "${literal} _callback " & quoted form of this_URL`,
         'end open location',
     ].join('\n');
 }
@@ -113,7 +114,7 @@ export function windowsRegistryCommands(invocation) {
     return [
         ['add', base, '/ve', '/d', 'URL:agents Protocol', '/f'],
         ['add', base, '/v', 'URL Protocol', '/d', '', '/f'],
-        ['add', `${base}\\shell\\open\\command`, '/ve', '/d', `${invocation} open "%1"`, '/f'],
+        ['add', `${base}\\shell\\open\\command`, '/ve', '/d', `${invocation} _callback "%1"`, '/f'],
     ];
 }
 // ---------------------------------------------------------------------------
@@ -134,19 +135,19 @@ export function agentsUrlSchemeStatus(platform = os.platform(), home = os.homedi
         const p = linuxDesktopPath(home);
         return fs.existsSync(p)
             ? { registered: true, platform, detail: `handler: ${p}` }
-            : { registered: false, platform, detail: `no handler (${p}) — run: agents open register` };
+            : { registered: false, platform, detail: `no handler (${p}) — run: agents setup url-scheme register` };
     }
     if (platform === 'darwin') {
         const p = macAppPath(home);
         return fs.existsSync(p)
             ? { registered: true, platform, detail: `handler: ${p}` }
-            : { registered: false, platform, detail: `no handler (${p}) — run: agents open register` };
+            : { registered: false, platform, detail: `no handler (${p}) — run: agents setup url-scheme register` };
     }
     if (platform === 'win32') {
         const ok = windowsSchemeRegistered();
         return ok
             ? { registered: true, platform, detail: 'handler: HKCU\\Software\\Classes\\agents' }
-            : { registered: false, platform, detail: 'no handler — run: agents open register' };
+            : { registered: false, platform, detail: 'no handler — run: agents setup url-scheme register' };
     }
     return { registered: false, platform, detail: `unsupported platform: ${platform}` };
 }

package/dist/lib/deeplink/url.d.ts

@@ -3,12 +3,12 @@
  *
  * A rendered artifact (a plan or report) embeds `agents://session/<id>` in its
  * provenance line. Clicking it hands the URL to the OS, which routes it to the
- * registered handler (see register.ts) that runs `agents open <url>`. This module
- * turns that URL into a validated {@link AgentsSessionLink} the resume dispatcher
- * consumes.
+ * registered handler (see register.ts) that runs the machine-only `agents _callback
+ * <url>` verb (`open` remains a hidden back-compat alias). This module turns that URL
+ * into a validated {@link AgentsSessionLink} the resume dispatcher consumes.
  *
  * Parsing is deliberately strict: the session id is the only thing that ever
- * reaches a child process, and the `open` command passes it as argv (never
+ * reaches a child process, and the `_callback` command passes it as argv (never
  * interpolated into a shell), so a hostile URL cannot inject a command. Anything
  * that is not `agents://session/<valid-id>` is rejected with a reason.
  *

package/dist/lib/deeplink/url.js

@@ -3,12 +3,12 @@
  *
  * A rendered artifact (a plan or report) embeds `agents://session/<id>` in its
  * provenance line. Clicking it hands the URL to the OS, which routes it to the
- * registered handler (see register.ts) that runs `agents open <url>`. This module
- * turns that URL into a validated {@link AgentsSessionLink} the resume dispatcher
- * consumes.
+ * registered handler (see register.ts) that runs the machine-only `agents _callback
+ * <url>` verb (`open` remains a hidden back-compat alias). This module turns that URL
+ * into a validated {@link AgentsSessionLink} the resume dispatcher consumes.
  *
  * Parsing is deliberately strict: the session id is the only thing that ever
- * reaches a child process, and the `open` command passes it as argv (never
+ * reaches a child process, and the `_callback` command passes it as argv (never
  * interpolated into a shell), so a hostile URL cannot inject a command. Anything
  * that is not `agents://session/<valid-id>` is rejected with a reason.
  *

package/dist/lib/device-config.js

@@ -75,6 +75,31 @@ export const CONFIG_KEYS = [
             ? null
             : `auto.pool must be one of ${AUTO_POOL_MODES.join(' | ')}.`,
     },
+    {
+        name: 'summarizer.enabled',
+        yamlKey: 'summarizerEnabled',
+        scope: 'user',
+        type: 'bool',
+        defaultValue: false,
+        description: 'Whether the daemon computes a per-session goal / progress checkpoints / checklist and delivers them on the ' +
+            'session stream (PHNX-3939). Off by default — zero model calls, no behavior change until enabled. Needs a local ' +
+            'Anthropic-wire model endpoint via summarizer.baseUrl + summarizer.model.',
+    },
+    {
+        name: 'summarizer.baseUrl',
+        yamlKey: 'summarizerBaseUrl',
+        scope: 'user',
+        type: 'string',
+        description: 'Base URL of the Anthropic-wire model endpoint the summarizer calls (Ollama / vLLM / LiteLLM), ' +
+            'e.g. http://localhost:11434. Overridden per-process by AGENTS_SUMMARIZER_BASEURL.',
+    },
+    {
+        name: 'summarizer.model',
+        yamlKey: 'summarizerModel',
+        scope: 'user',
+        type: 'string',
+        description: 'Model the summarizer requests from summarizer.baseUrl, e.g. qwen2.5:3b. Overridden per-process by AGENTS_SUMMARIZER_MODEL.',
+    },
     {
         name: 'browser.viewer',
         yamlKey: 'browserViewer',

package/dist/lib/devices/doctor-findings.d.ts

@@ -113,7 +113,7 @@ export interface LocalFindingInputs {
     /** Read-only Windows OpenSSH AuthorizedKeysFile/content/ACL audit. */
     windowsSshEnrollment?: WindowsSshEnrollmentAudit | null;
     /** `<agent>@<version>` keys whose home is an isolated copy. Their findings are
-     *  never collapsed across versions: the agent-wide `agents doctor <agent> --fix`
+     *  never collapsed across versions: the agent-wide `agents sync <agent>@all`
      *  sweep deliberately skips isolated copies, so a collapsed row would print a
      *  remediation that does not fix them. */
     isolatedVersions?: string[];
@@ -135,14 +135,14 @@ export declare function buildLocalFindings(input: LocalFindingInputs): DoctorFin
 /**
  * Fold findings that say the SAME thing about several versions of one agent into
  * a single row carrying `versions`, and widen its remediation to the agent-wide
- * sweep (`agents doctor claude --fix` heals every non-isolated version in one
+ * sweep (`agents sync claude@all --yes` heals every non-isolated version in one
  * go). Five identical `plugin 'code' — mirror missing` rows, one per installed
  * claude, is the same fact five times.
  *
  * Three things never merge, because for each of them the widened remediation
  * would be wrong:
- *  - **Isolated copies** — the agent-wide sweep deliberately skips them
- *    (`runFix`), so a folded row would print a command that leaves one broken.
+ *  - **Isolated copies** — the agent-wide sweep deliberately skips them, so a
+ *    folded row would print a command that leaves one broken.
  *  - **Findings with no agent** (repo-behind, rc-secret-export, …) — their
  *    `version` field is an alias, not a version.
  *  - **Logouts** ({@link NEVER_COLLAPSED}) — a login is inherently per-version:

package/dist/lib/devices/doctor-findings.js

@@ -235,7 +235,13 @@ export function remediationFor(finding) {
         case 'missing-resource':
         case 'content-drift':
         case 'stale':
-            return idLabel ? `agents doctor ${idLabel} --fix` : 'agents doctor --fix';
+            // doctor diagnoses; `agents sync` fixes (the superset of the old
+            // `doctor --fix`). A bare `agents sync <agent>` hits only the default
+            // version, so an agent-only row collapsed across versions must ask for
+            // @all to reach every one it covers.
+            if (agent && version)
+                return `agents sync ${agent}@${version} --yes`;
+            return agent ? `agents sync ${agent}@all --yes` : 'agents sync';
         case 'hook-runtime-visibility-unavailable':
             return 'upgrade agents-cli on this device';
         case 'never-synced':
@@ -261,8 +267,8 @@ export function remediationFor(finding) {
             return `agents repo pull ${version ?? 'user'}`;
         case 'fleet-resource-gap':
             // The resource is absent from this box's CENTRAL repos, not from a version
-            // home, so `agents doctor --fix` (which reconciles central -> homes) has
-            // nothing to copy. The divergence row cannot say WHICH repo declares it,
+            // home, so `agents sync` (which reconciles central -> homes) has nothing to
+            // copy. The divergence row cannot say WHICH repo declares it,
             // and neither `agents repo pull` nor the sync umbrella touches the system
             // repo (`commands/repo.ts:1186`, `lib/sync-umbrella.ts:104`) — that one is
             // npm-shipped and moves with the CLI. So name both paths rather than a
@@ -317,8 +323,8 @@ function finding(f) {
  * or more collapse into a count plus the first two subjects
  * (`32 hooks missing (incl. 'git-guard', 'rm-guard')`). Naming every item — the
  * pre-RUSH-2069-review behavior — flooded the section with dozens of near-identical
- * rows for one root cause; the count carries the same signal and `--fix` is the
- * same command either way.
+ * rows for one root cause; the count carries the same signal and `agents sync`
+ * is the same command either way.
  */
 function emitGroup(out, items, severity, kind, device, agent, version, noun, verb) {
     if (items.length === 0)
@@ -735,14 +741,14 @@ function execPolicyFinding(device, execPolicy) {
 /**
  * Fold findings that say the SAME thing about several versions of one agent into
  * a single row carrying `versions`, and widen its remediation to the agent-wide
- * sweep (`agents doctor claude --fix` heals every non-isolated version in one
+ * sweep (`agents sync claude@all --yes` heals every non-isolated version in one
  * go). Five identical `plugin 'code' — mirror missing` rows, one per installed
  * claude, is the same fact five times.
  *
  * Three things never merge, because for each of them the widened remediation
  * would be wrong:
- *  - **Isolated copies** — the agent-wide sweep deliberately skips them
- *    (`runFix`), so a folded row would print a command that leaves one broken.
+ *  - **Isolated copies** — the agent-wide sweep deliberately skips them, so a
+ *    folded row would print a command that leaves one broken.
  *  - **Findings with no agent** (repo-behind, rc-secret-export, …) — their
  *    `version` field is an alias, not a version.
  *  - **Logouts** ({@link NEVER_COLLAPSED}) — a login is inherently per-version:

package/dist/lib/devices/registry.js

@@ -22,6 +22,7 @@ import { atomicWriteJsonSync } from '../fs-atomic.js';
 import { machineId } from '../machine-id.js';
 import { addIgnoredEntry, unionDeviceIgnored } from './device-docs.js';
 import { logAndContinueOnLockCompromised } from '../lock-compromise.js';
+import { removeStatsCacheEntry } from './stats-cache.js';
 /**
  * Whether a fan-out should dial this device, honouring the preference stated on
  * {@link DeviceProfile.reachability}: the live SSH probe wins over the cached
@@ -281,6 +282,7 @@ export async function removeDevice(name) {
             return false;
         delete reg[name];
         await saveDevices(reg);
+        removeStatsCacheEntry(name);
         return true;
     });
 }

package/dist/lib/devices/stats-cache.d.ts

@@ -38,6 +38,10 @@ export declare function readStatsCache(): Record<string, DeviceStats>;
  * single-device refresh) never drops the rest of the fleet's cached stats.
  */
 export declare function writeStatsCache(entries: Record<string, DeviceStats>): void;
+/** Drop one removed device so cache-only rows cannot outlive the registry. */
+export declare function removeStatsCacheEntry(name: string): void;
+/** Immutable cache pruning primitive, exported for lifecycle regression tests. */
+export declare function pruneStatsCache(entries: Record<string, DeviceStats>, name: string): Record<string, DeviceStats>;
 export interface FleetStatsResult {
     /** name → stats for every requested device (cache-served + freshly probed). */
     stats: Map<string, DeviceStats>;

package/dist/lib/devices/stats-cache.js

@@ -114,6 +114,25 @@ export function writeStatsCache(entries) {
         // best-effort; a failed write just means the next read falls back to a live probe
     }
 }
+/** Drop one removed device so cache-only rows cannot outlive the registry. */
+export function removeStatsCacheEntry(name) {
+    try {
+        const current = readStatsCache();
+        if (!(name in current))
+            return;
+        const entries = pruneStatsCache(current, name);
+        fs.writeFileSync(cacheFilePath(), JSON.stringify({ version: 1, entries }, null, 2));
+    }
+    catch {
+        // Cache cleanup is best-effort; registry removal remains authoritative.
+    }
+}
+/** Immutable cache pruning primitive, exported for lifecycle regression tests. */
+export function pruneStatsCache(entries, name) {
+    const { [name]: _removed, ...remaining } = entries;
+    void _removed;
+    return remaining;
+}
 /**
  * Load fleet stats cache-first. See the module doc for the default vs
  * `--refresh` behaviour. Never throws — an unreachable box degrades to a

package/dist/lib/drift-sync.d.ts

@@ -7,7 +7,9 @@
  *   - computeSyncStatus()          — the unified detection engine (sync-status.ts)
  *   - pullRepo()                   — fast-forward the `.system` repo (git.ts)
  *   - promptAgentVersionSelection() — the "which agent types / versions?" picker
- *   - heal({ mode: 'full' })       — the reconcile engine `doctor --fix` uses
+ *   - repairAfterSync()            — the shared post-reconcile repair pass
+ *                                    `agents sync` runs (heal + hook rewire +
+ *                                    managed hook runtime shim repair)
  *
  * Combined flow (one confirmation): if `.system` is behind AND resources drifted,
  * a single "Sync all detected" both pulls `.system` and reconciles the chosen

package/dist/lib/drift-sync.js

@@ -7,7 +7,9 @@
  *   - computeSyncStatus()          — the unified detection engine (sync-status.ts)
  *   - pullRepo()                   — fast-forward the `.system` repo (git.ts)
  *   - promptAgentVersionSelection() — the "which agent types / versions?" picker
- *   - heal({ mode: 'full' })       — the reconcile engine `doctor --fix` uses
+ *   - repairAfterSync()            — the shared post-reconcile repair pass
+ *                                    `agents sync` runs (heal + hook rewire +
+ *                                    managed hook runtime shim repair)
  *
  * Combined flow (one confirmation): if `.system` is behind AND resources drifted,
  * a single "Sync all detected" both pulls `.system` and reconciles the chosen
@@ -19,7 +21,7 @@ import chalk from 'chalk';
 import { select, confirm } from '@inquirer/prompts';
 import { AGENTS } from './agents.js';
 import { pullRepo } from './git.js';
-import { heal } from './heal.js';
+import { repairAfterSync, renderRepairAfterSync } from './reconcile-and-repair.js';
 import { promptAgentVersionSelection } from './installations/versions.js';
 import { isInteractiveTerminal, isPromptCancelled } from './format.js';
 import { computeSyncStatus, } from './sync-status.js';
@@ -58,14 +60,23 @@ async function pullSystem(status) {
     console.log(chalk.red(`Could not pull .system: ${res.error ?? 'unknown error'}`));
     return false;
 }
-/** Reconcile a set of versions grouped by agent via the shared heal engine. */
+/**
+ * Reconcile a set of versions grouped by agent through the SHARED post-reconcile
+ * repair pass (`repairAfterSync`) — the same superset the three `agents sync`
+ * handlers run. Beyond the resources `heal()` fills, this also re-wires hooks
+ * left unwired and repairs broken managed hook runtime shims, so drift-sync is
+ * not a third orchestrator that silently skips shim repair. Renders each pass's
+ * rewire / shim-repair detail; the heal rollup is printed separately by the
+ * caller via `reportHealed`.
+ */
 async function healVersions(versionsByAgent, cwd) {
     const out = [];
     for (const [agent, versions] of versionsByAgent) {
         if (versions.length === 0)
             continue;
-        const res = await heal({ mode: 'full', cwd, agent, versions });
-        out.push(...res.versions);
+        const repair = await repairAfterSync({ agent, versions, cwd });
+        out.push(...repair.heal.versions);
+        renderRepairAfterSync(repair, (line) => console.log(line));
     }
     return out;
 }

package/dist/lib/exec.d.ts

@@ -311,6 +311,8 @@ export declare function resolveLaunchId(envLaunchId: string | undefined): string
  * into unrelated invocations.
  */
 export declare function buildExecEnv(options: ExecOptions): NodeJS.ProcessEnv;
+/** Materialize config roots for vendor CLIs that do not create parents recursively. */
+export declare function ensureVendorHomeDir(agent: AgentId, versionHome: string): string | null;
 /**
  * Describes how to translate ExecOptions into CLI arguments for a specific agent.
  *

package/dist/lib/exec.js

@@ -9,7 +9,7 @@ import { randomUUID } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import { ALL_MODES, REMOTE_INTERACTIVE_ENV } from './types.js';
-import { AGENTS, findInPath } from './agents.js';
+import { AGENTS, agentConfigDirName, findInPath } from './agents.js';
 import { parseTimeout } from './scheduling/routines.js';
 import { compareVersions, getBinaryPath, getVersionHomePath, isVersionInstalled, listInstalledVersions, resolveVersion } from './installations/versions.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
@@ -447,6 +447,19 @@ export function buildExecEnv(options) {
         ...options.env,
     };
 }
+/** Materialize config roots for vendor CLIs that do not create parents recursively. */
+export function ensureVendorHomeDir(agent, versionHome) {
+    if (agent !== 'cursor' && agent !== 'grok' && agent !== 'copilot')
+        return null;
+    const vendorHome = path.join(versionHome, agentConfigDirName(agent));
+    fs.mkdirSync(vendorHome, { recursive: true });
+    return vendorHome;
+}
+function ensureVendorHomeForSpawn(options) {
+    const { versionHome } = resolveConfigVersion(options.agent, options.cwd || process.cwd(), options.configVersion ?? options.version);
+    if (versionHome)
+        ensureVendorHomeDir(options.agent, versionHome);
+}
 /**
  * CLI command templates for every supported agent.
  *
@@ -1131,6 +1144,7 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     // practice (POSIX uses the bash shim, which execs the binary and never reaches
     // buildExecEnv — `installations/shims.ts` generateShimScript).
     const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto', env: { AGENT_LAUNCH_ID: launchId } });
+    ensureVendorHomeDir(agent, getVersionHomePath(agent, version));
     const { command, args, shell } = resolveShimSpawn(process.platform, binary, [...launchArgs, ...rawArgs]);
     // Pre-launch marker for the SECOND live launch path: the Windows generated
     // `.cmd` shim delegates here and spawns the harness directly, so without this
@@ -1715,6 +1729,7 @@ async function spawnAgent(options) {
     if (options.agent === 'claude' && !options.resume && !options.sessionId) {
         options = { ...options, sessionId: randomUUID() };
     }
+    ensureVendorHomeForSpawn(options);
     // Record the run's --name against its session id (when both are known at
     // launch) so `agents sessions <name>` resolves it. Best-effort; unnamed runs
     // and agents whose id isn't known up front simply skip this.