@phnx-labs/agents-cli 1.22.75 → 1.22.76

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-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/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.

package/dist/lib/fleet-shared-state.d.ts

@@ -26,6 +26,14 @@ export interface SessionMirrorRow {
     timestamp: string;
     ticketId?: string;
     prUrl?: string;
+    /** Daemon-computed goal (PHNX-3939) — carried so a peer renders it with no transcript. */
+    goal?: string;
+    /** Daemon-computed progress checkpoints, newest last (PHNX-3939). */
+    checkpoints?: import('./session/types.js').SessionCheckpoint[];
+    /** Daemon-computed detailed checklist (PHNX-3939). */
+    summaryChecklist?: import('./session/types.js').SessionChecklistItem[];
+    /** Lifecycle of the daemon-computed summary (PHNX-3939). */
+    summaryState?: import('./session/types.js').SummaryState;
     capturedAt: number;
 }
 export interface FleetSharedDeviceState {

package/dist/lib/heal.d.ts

@@ -3,9 +3,10 @@
  * what is actually present/valid in each installed agent home.
  *
  * Powers two callers:
- *   - `agents doctor --fix`  — explicit, operator-driven. Mode 'full': fills
- *     missing, overwrites drifted content, and refreshes stale plugins even when
- *     the baseline is unknown (the operator asked for it).
+ *   - `agents sync` — the one fixer, via the post-reconcile repair pass
+ *     (`lib/reconcile-and-repair.ts`, run at the tail of every sync). Mode
+ *     'full': fills missing, overwrites drifted content, and refreshes stale
+ *     plugins even when the baseline is unknown (the user asked to sync).
  *   - the routines daemon's periodic safety check — Mode 'safe': fixes only the
  *     unambiguous gaps (missing resources, Claude-invalid plugin manifests, and
  *     provably-unmodified stale plugins). Drift and risky refreshes are reported,

package/dist/lib/heal.js

@@ -3,9 +3,10 @@
  * what is actually present/valid in each installed agent home.
  *
  * Powers two callers:
- *   - `agents doctor --fix`  — explicit, operator-driven. Mode 'full': fills
- *     missing, overwrites drifted content, and refreshes stale plugins even when
- *     the baseline is unknown (the operator asked for it).
+ *   - `agents sync` — the one fixer, via the post-reconcile repair pass
+ *     (`lib/reconcile-and-repair.ts`, run at the tail of every sync). Mode
+ *     'full': fills missing, overwrites drifted content, and refreshes stale
+ *     plugins even when the baseline is unknown (the user asked to sync).
  *   - the routines daemon's periodic safety check — Mode 'safe': fixes only the
  *     unambiguous gaps (missing resources, Claude-invalid plugin manifests, and
  *     provably-unmodified stale plugins). Drift and risky refreshes are reported,
@@ -86,7 +87,7 @@ export function notifyHeal(r) {
         ? `${needsAttention} plugin${needsAttention === 1 ? '' : 's'} need attention`
         : 'agents: auto-healed config gaps';
     const body = needsAttention > 0
-        ? `${summarizeHeal(r)}. Run: agents doctor --fix`
+        ? `${summarizeHeal(r)}. Run: agents sync`
         : summarizeHeal(r);
     notifyDesktop({ title, body, action: 'routines:list' });
 }

package/dist/lib/hosts/ready.d.ts

@@ -109,7 +109,7 @@ export interface ViewAgentAccountEligibility {
  * older remote CLI omits `launchable`, so it falls back to `signedIn` — the
  * pre-fix behavior, so a rolling fleet does not regress.
  */
-export declare function viewAgentAccountEligibility(view: string, agent: string): ViewAgentAccountEligibility;
+export declare function viewAgentAccountEligibility(view: string, agent: string, now?: number): ViewAgentAccountEligibility;
 export declare function viewAgentSignedIn(view: string, agent: string): boolean | undefined;
 export interface EnsureReadyOptions {
     agent: string;

package/dist/lib/hosts/ready.js

@@ -12,7 +12,8 @@ import { sshExec, shellQuote } from '../ssh-exec.js';
 import { hostIdentityArgs, sshTargetFor } from './types.js';
 import { remoteShellFor, buildWindowsAgentsCommand, encodePowershell, powershellQuote, POWERSHELL_PROGRESS_SILENCE } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
-import { isDeadVerdict } from '../auth-health.js';
+import { AUTH_PROBE_MAX_AGE_MS, isDeadVerdict } from '../auth-health.js';
+import { USAGE_STALE_REFUSAL_MAX_AGE_MS } from '../accounting/rotate.js';
 /** Resolve this CLI's own version by walking up to the nearest package.json. */
 export function localCliVersion() {
     let dir = path.dirname(fileURLToPath(import.meta.url));
@@ -222,7 +223,7 @@ export function missingPinnedVersionMessage(hostName, agent, version, installed)
  * older remote CLI omits `launchable`, so it falls back to `signedIn` — the
  * pre-fix behavior, so a rolling fleet does not regress.
  */
-export function viewAgentAccountEligibility(view, agent) {
+export function viewAgentAccountEligibility(view, agent, now = Date.now()) {
     try {
         const rows = JSON.parse(view);
         const row = rows.find((candidate) => candidate.agent?.toLowerCase() === agent.toLowerCase());
@@ -234,11 +235,22 @@ export function viewAgentAccountEligibility(view, agent) {
             // Prefer the strict per-version launch signal; fall back to the display
             // `signedIn` for an older remote CLI that does not emit `launchable`.
             const launchable = typeof version.launchable === 'boolean' ? version.launchable : version.signedIn;
-            const throttled = version.usageStatus === 'rate_limited' || version.usageStatus === 'out_of_credits';
+            const usageCapturedAt = version.usageCapturedAt ? Date.parse(version.usageCapturedAt) : Number.NaN;
+            const usageFresh = Number.isFinite(usageCapturedAt)
+                ? now - usageCapturedAt <= USAGE_STALE_REFUSAL_MAX_AGE_MS
+                : version.usageCapturedAt === undefined;
+            const authFresh = typeof version.authCheckedAt === 'number'
+                ? now - version.authCheckedAt <= AUTH_PROBE_MAX_AGE_MS
+                : version.authCheckedAt === undefined;
+            const throttled = usageFresh
+                && (version.usageStatus === 'rate_limited' || version.usageStatus === 'out_of_credits');
             const authBlocked = version.authVerdict !== null
                 && version.authVerdict !== undefined
+                && authFresh
                 && isDeadVerdict(version.authVerdict);
-            const ready = launchable && !authBlocked && !throttled;
+            const freshnessKnown = version.usageCapturedAt !== undefined || version.authCheckedAt !== undefined;
+            const fresh = !freshnessKnown || (usageFresh && authFresh);
+            const ready = launchable && fresh && !authBlocked && !throttled;
             return [{ ready, pickerEligible: ready || !launchable || authBlocked }];
         });
         if (verdicts.length === 0)

package/dist/lib/hosts/reconnect.js

@@ -81,7 +81,9 @@ export function formatDuration(ms) {
 export function reconnectNotice(target, host, attempt, waitMs, remainingMs) {
     const secs = Math.round(waitMs / 1000);
     const when = secs <= 1 ? 'now' : `in ${secs}s`;
-    return `\nConnection to ${host} dropped — ${targetLabel(target)} is still running there.`
+    // A tmux-wrapped run is still live; a bare run was SIGHUPed and focus will
+    // resume it from disk. This wording is truthful for either peer configuration.
+    return `\nConnection to ${host} dropped — reconnecting to ${targetLabel(target)}.`
         + `\n  Reconnecting ${when} · ${formatDuration(remainingMs)} left · attempt ${attempt} · Ctrl-C to stop\n`;
 }
 /** Notice shown once the retry budget is spent on an unreachable host. */
@@ -99,7 +101,7 @@ export function remoteExitNotice(target, host) {
 }
 /** Notice shown when the user stops the wait with Ctrl-C. */
 export function interruptedNotice(target, host) {
-    return `\nStopped reconnecting. ${targetLabel(target)} is still running on ${host}:\n${recoveryHint(target, host)}`;
+    return `\nStopped reconnecting to ${targetLabel(target)} on ${host}. Recover it when the link is stable:\n${recoveryHint(target, host)}`;
 }
 /**
  * Wrap `cmd` in `bash -lc` with an exit-code remap: 255 becomes