@phnx-labs/agents-cli 1.22.75 → 1.22.76

package/dist/lib/identity/client.d.ts

@@ -30,6 +30,12 @@ export interface PhoenixSession {
     access_token: string;
     email?: string;
     userId?: string;
+    /**
+     * Hosted OAuth profile image (https URL), when Phoenix ID exposes one. Wins
+     * over the email-Gravatar fallback in share attribution. Optional forever —
+     * a missing value just means the Gravatar/initials fallback.
+     */
+    avatarUrl?: string;
     /** Unix ms; absent means the server did not scope the token's lifetime. */
     expires_at?: number;
 }

package/dist/lib/identity/index.d.ts

@@ -16,6 +16,8 @@ export interface WhoAmI {
     userId: string;
     email: string;
     valid: true;
+    /** Hosted OAuth profile image, when Phoenix ID stores one for this user. */
+    avatar_url?: string;
 }
 /**
  * RFC 8628 poll outcomes. `pending` and `slow_down` are normal states of a
@@ -28,6 +30,10 @@ export type DevicePoll = {
     user: {
         email: string;
         id: string;
+        /** Hosted OAuth profile image, when the provider exposed one to Phoenix ID. */
+        avatar_url?: string;
+        /** Google-style alias some providers use for the same field. */
+        picture?: string;
     };
 } | {
     status: 'pending';
@@ -41,6 +47,16 @@ export type DevicePoll = {
 export declare function startDeviceAuthorization(): Promise<DeviceAuthorization>;
 export declare function pollDeviceToken(deviceCode: string): Promise<DevicePoll>;
 export declare function fetchWhoAmI(token?: string): Promise<WhoAmI>;
+/**
+ * Best-effort fill of the session's hosted avatar (PHNX-3547): sessions written
+ * before the CLI tracked avatars have none, so ask `/api/v1/auth/me` and merge
+ * a hosted `avatar_url` into the persisted session — future publishes then
+ * stamp the OAuth profile image instead of only a Gravatar hash. A no-op when
+ * signed out, when an avatar is already stored, or when the server exposes
+ * none; network/server failures are swallowed (the share attribution falls
+ * back to Gravatar/initials either way).
+ */
+export declare function refreshSessionAvatar(): Promise<void>;
 export interface SpaceSummary {
     id: string;
     slug: string;

package/dist/lib/identity/index.js

@@ -2,7 +2,7 @@
  * Phoenix ID — the typed surface commands use. Every route the account backend
  * exposes is a function here; no command builds a URL or reads a token itself.
  */
-import { phoenixRequest, PhoenixApiError } from './client.js';
+import { phoenixRequest, PhoenixApiError, readSession, writeSession } from './client.js';
 export { PHOENIX_ID_BASE, PhoenixApiError, clearSession, readSession, sessionFilePath, writeSession, } from './client.js';
 export function startDeviceAuthorization() {
     return phoenixRequest('POST', '/api/v1/auth/device/authorization', {
@@ -38,6 +38,30 @@ export async function pollDeviceToken(deviceCode) {
 export function fetchWhoAmI(token) {
     return phoenixRequest('GET', '/api/v1/auth/me', { token });
 }
+/**
+ * Best-effort fill of the session's hosted avatar (PHNX-3547): sessions written
+ * before the CLI tracked avatars have none, so ask `/api/v1/auth/me` and merge
+ * a hosted `avatar_url` into the persisted session — future publishes then
+ * stamp the OAuth profile image instead of only a Gravatar hash. A no-op when
+ * signed out, when an avatar is already stored, or when the server exposes
+ * none; network/server failures are swallowed (the share attribution falls
+ * back to Gravatar/initials either way).
+ */
+export async function refreshSessionAvatar() {
+    const session = readSession();
+    if (!session || session.avatarUrl)
+        return;
+    try {
+        const me = await fetchWhoAmI();
+        const hosted = me.avatar_url?.trim();
+        if (hosted && /^https:\/\//i.test(hosted)) {
+            writeSession({ ...session, avatarUrl: hosted });
+        }
+    }
+    catch {
+        // Offline or server without the field — the Gravatar fallback covers it.
+    }
+}
 export const listSpaces = () => phoenixRequest('GET', '/api/v1/spaces');
 export const createSpace = (input) => phoenixRequest('POST', '/api/v1/spaces', { body: input });
 export const getSpace = (id) => phoenixRequest('GET', `/api/v1/spaces/${encodeURIComponent(id)}`);

package/dist/lib/profiles.d.ts

@@ -177,6 +177,8 @@ export interface HostModelOptions {
 export declare function profileFromHostModel(name: string, host: AgentId, model: string, opts?: HostModelOptions): Profile;
 /** Overrides applied on top of the source when forking a harness. */
 export interface ForkProfileOptions {
+    /** Translate the fork onto a different native harness host. */
+    host?: AgentId;
     /** Swap the pinned model. Written onto the source's model env key when it has
      *  one, else onto the host's canonical model var. */
     model?: string;

package/dist/lib/profiles.js

@@ -404,31 +404,50 @@ export function profileFromHostModel(name, host, model, opts = {}) {
  */
 export function forkProfile(source, name, opts = {}) {
     validateProfileName(name);
-    const host = source.host.agent;
+    const sourceHost = source.host.agent;
+    const host = opts.host ?? sourceHost;
     const env = { ...source.env };
-    if (opts.model) {
-        env[profileModelEnvKey(source) ?? modelEnvKeyForHost(host)] = opts.model;
+    const sourceModelKey = profileModelEnvKey(source) ?? modelEnvKeyForHost(sourceHost);
+    const targetModelKey = modelEnvKeyForHost(host);
+    const model = opts.model ?? env[sourceModelKey];
+    if (host !== sourceHost && sourceModelKey !== targetModelKey)
+        delete env[sourceModelKey];
+    if (model) {
+        env[targetModelKey] = model;
     }
-    if (opts.baseUrl) {
-        const key = baseUrlEnvKeyForHost(host);
+    const sourceBaseKey = baseUrlEnvKeyForHost(sourceHost);
+    const targetBaseKey = baseUrlEnvKeyForHost(host);
+    const baseUrl = opts.baseUrl ?? (sourceBaseKey ? env[sourceBaseKey] : undefined);
+    if (host !== sourceHost && sourceBaseKey && sourceBaseKey !== targetBaseKey)
+        delete env[sourceBaseKey];
+    if (baseUrl) {
+        const key = targetBaseKey;
         if (!key) {
             throw new Error(`Host '${host}' has no known base-URL env var; drop --base-url or fork onto a claude/codex host.`);
         }
-        env[key] = opts.baseUrl;
+        env[key] = baseUrl;
     }
     const forked = {
         ...source,
         name,
-        host: { agent: host, ...(opts.version ? { version: opts.version } : source.host.version ? { version: source.host.version } : {}) },
+        host: { agent: host, ...(opts.version ? { version: opts.version } : host === sourceHost && source.host.version ? { version: source.host.version } : {}) },
         env,
         // The source's description names the source's model, so inheriting it
         // across a model swap would describe the fork wrongly.
-        description: opts.description ?? (opts.model ? `Forked from ${source.name}: ${opts.model}` : source.description),
+        description: opts.description ?? (opts.model || host !== sourceHost
+            ? `Forked from ${source.name}: ${model ?? host}`
+            : source.description),
         forkedFrom: source.name,
     };
+    if (forked.auth && host !== sourceHost) {
+        const envVar = authEnvKeyForHost(host);
+        if (!envVar)
+            throw new Error(`Host '${host}' has no known auth env var; the source auth binding cannot be translated.`);
+        forked.auth = { ...forked.auth, envVar };
+    }
     // A fork that repoints the model or endpoint is no longer that preset — keep
     // the preset link only while the fork still matches what the preset defines.
-    if (opts.model || opts.baseUrl)
+    if (opts.model || opts.baseUrl || host !== sourceHost)
         delete forked.preset;
     if (opts.provider) {
         const envVar = opts.authEnvVar ?? source.auth?.envVar ?? authEnvKeyForHost(host);

package/dist/lib/reconcile-and-repair.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Post-reconcile repair — the shared "make it whole" pass `agents sync` runs
+ * after its prune+write, so sync is a true superset of the old `doctor --fix`.
+ *
+ * `syncResourcesToVersion` reconciles resource FILES (and, with a caller
+ * selection, prunes orphans). It does NOT: fill live-home gaps the staleness
+ * manifest can't see, generate/repair the managed hook runtime shims, or re-wire
+ * a present-but-unwired hook into settings.json. `doctor --fix` used to do all of
+ * that; now sync does, by calling this one routine at the tail of every reconcile.
+ * (The destructive stale-CLI purge `doctor --fix` also ran is NOT automatic here
+ * — it runs only via the explicit `agents sync --prune-clis`, see `pruneClis`.)
+ *
+ * Ordering matters: sync's own prune+write happens FIRST (unchanged), THEN this
+ * repair pass. Prune stays sync's job; heal only FILLS and FIXES (never deletes),
+ * so the two never fight. Pure of stdout — returns a structured report;
+ * `renderRepairAfterSync` prints it only when the caller is neither `--json` nor
+ * `--quiet`.
+ */
+import type { AgentId } from './types.js';
+import { type HealResult } from './heal.js';
+import { type HookRuntimeRepairReport } from './hooks/install.js';
+import { type RemediateStaleInstallsResult, type FindAgentsCliInstallsOptions } from './self-update.js';
+export interface HookRewireResult {
+    agent: AgentId;
+    version: string;
+    /** Hooks newly wired into settings.json by this pass. */
+    rewired: number;
+    /** Hooks still unwired after re-registering (source/home mismatch). */
+    remaining: number;
+    /** Stable failure class; never expose a generated temporary shim pathname. */
+    failure?: 'register-failed';
+}
+export interface RepairAfterSyncReport {
+    heal: HealResult;
+    hookRewire: HookRewireResult[];
+    hookRuntimeRepair: HookRuntimeRepairReport;
+    /** Only populated on the umbrella (no-agent) path; null otherwise. */
+    staleInstallPurge: RemediateStaleInstallsResult | null;
+}
+/**
+ * Test/override hook that scopes the destructive stale-CLI purge to injected
+ * paths so it NEVER touches real machine installs. `findAgentsCliInstalls`
+ * hard-codes `/usr/local/lib/node_modules` et al. when `globalNodeModulesDirs` is
+ * absent, so a purge is unsafe to run unscoped in a test — inject sandbox paths.
+ */
+export interface PurgeInjection {
+    runningRoot?: string;
+    runningVersion?: string;
+    pathEnv?: string;
+    findOpts?: FindAgentsCliInstallsOptions;
+    dryRun?: boolean;
+}
+export interface RepairAfterSyncOptions {
+    /** Scope the repair to one agent; omit for the umbrella sweep across all
+     *  installed agents. (The purge is NOT tied to this — see `pruneClis`.) */
+    agent?: AgentId;
+    /** The versions of `agent` the sync just reconciled. Passing them scopes
+     *  heal + rewire + runtime-repair to exactly those homes; omitting lets heal
+     *  apply its own non-isolated sweep. */
+    versions?: string[];
+    /** Resolution cwd for heal's diff. Defaults to heal's neutral home dir. */
+    cwd?: string;
+    /** Run the DESTRUCTIVE machine-wide stale-CLI purge (`fs.rmSync`s other
+     *  agents-cli installs). Default false — the purge is NEVER automatic; it runs
+     *  only on the umbrella (no-agent) path AND only when the caller passed
+     *  `agents sync --prune-clis`. */
+    pruneClis?: boolean;
+    /** Scope the purge scan+delete to injected paths (tests only). */
+    purgeInjection?: PurgeInjection;
+}
+/**
+ * Run the post-reconcile repair pass over the agents/versions a sync just
+ * touched: heal live-home gaps (mode 'full', matching the old `doctor --fix`),
+ * re-wire hooks the diff-driven heal leaves behind, run one bounded managed-hook
+ * runtime repair, and — ONLY when `pruneClis` is set on the umbrella (no-agent)
+ * path — purge stale/legacy agents-cli copies. The purge is never automatic.
+ * Returns a full account; never writes to stdout.
+ */
+export declare function repairAfterSync(opts: RepairAfterSyncOptions): Promise<RepairAfterSyncReport>;
+/** True when the repair pass changed (or attempted to change) anything. */
+export declare function repairChangedAnything(report: RepairAfterSyncReport): boolean;
+/**
+ * True when the RECONCILE repair left a per-version problem a human must fix — an
+ * unresolvable managed hook runtime shim, or a hook that could not be re-wired.
+ * These gate a sync's `ok`/exit code (the yosemite-s1 class the old
+ * `doctor --fix` surfaced).
+ *
+ * The machine-wide stale-CLI purge is deliberately EXCLUDED: a purge that could
+ * not delete a system-wide install (typically `EACCES` on `/usr/local/...`, which
+ * needs sudo) is a hygiene issue unrelated to whether the reconcile succeeded, so
+ * it must not flip a fleet peer's `agents sync --json` to `ok: false`. Purge
+ * failures stay fully visible — in the JSON `repair.staleInstallPurge.failed` and
+ * the rendered `hold`/`manual` lines.
+ */
+export declare function repairHadFailures(report: RepairAfterSyncReport): boolean;
+/**
+ * Serialize the repair pass for a `--json` sync payload — the machine surface the
+ * deleted `doctor --fix --json` used to carry (heal detail + hook rewire + hook
+ * runtime repair + the umbrella stale-CLI purge). Attached under the `repair` key
+ * so fleet fan-out sees what the reconcile fixed and whether anything still needs
+ * a human (mirror `repairHadFailures`).
+ */
+export declare function repairAfterSyncJson(report: RepairAfterSyncReport): Record<string, unknown>;
+/**
+ * Print the repair pass's human-readable detail. Sync calls this only on the
+ * interactive / non-json path; the header is emitted only when something actually
+ * changed, so a clean sync stays quiet.
+ */
+export declare function renderRepairAfterSync(report: RepairAfterSyncReport, log?: (s: string) => void): void;

package/dist/lib/reconcile-and-repair.js

@@ -0,0 +1,267 @@
+import { AGENTS, ALL_AGENT_IDS } from './agents.js';
+import chalk from 'chalk';
+import { heal, healChangedAnything } from './heal.js';
+import { checkVersionHookWiring, registerHooksToSettings, repairManagedHookRuntimeArtifacts, } from './hooks/install.js';
+import { getVersionHomePath, listInstalledVersions, isVersionIsolated, } from './installations/versions.js';
+import { invalidateDoctorOverviewCache } from './devices/doctor-overview-cache.js';
+import { remediateStaleAgentsCliInstalls, resolveRunningPackageRoot, } from './self-update.js';
+import { getCliVersion } from './version.js';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+const __moduleDirname = path.dirname(fileURLToPath(import.meta.url));
+const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
+// Claude-family agents whose native hook wiring `checkVersionHookWiring` can
+// verify (and `registerHooksToSettings` re-wire).
+const HOOK_WIRING_FIX_AGENTS = ['claude', 'droid'];
+// ─── hook re-wire (files reconciled but not referenced in settings.json) ─────
+/**
+ * Re-wire hooks that reconcile as files but are absent from settings.json.
+ *
+ * heal() only re-syncs resources the diff flags missing/diff; a hook whose file
+ * is byte-identical to source but never referenced in settings.json is neither,
+ * so heal walks past it. registerHooksToSettings (the same call `agents sync`
+ * makes at versions.ts) regenerates the wiring, so run it for any Claude-family
+ * version this repair targets that has unwired hooks. Only claude/droid — the
+ * set checkVersionHookWiring can verify.
+ */
+function rewireUnwiredHooks(agent, versions) {
+    const out = [];
+    const agents = agent
+        ? (HOOK_WIRING_FIX_AGENTS.includes(agent) ? [agent] : [])
+        : HOOK_WIRING_FIX_AGENTS;
+    for (const a of agents) {
+        // Explicit versions (the sync's reconcile targets) are honoured as-is; a
+        // sweep excludes isolated copies, mirroring heal().
+        const vers = agent && versions && versions.length > 0
+            ? versions
+            : listInstalledVersions(a).filter((v) => !isVersionIsolated(a, v));
+        for (const version of vers) {
+            const before = checkVersionHookWiring(a, version);
+            if (!before.supported)
+                continue;
+            const need = before.unwired.length + (before.settingsMissing ? (before.expected ?? 0) : 0);
+            if (need === 0)
+                continue;
+            try {
+                const registration = registerHooksToSettings(a, getVersionHomePath(a, version));
+                if (registration.errors.length > 0) {
+                    out.push({ agent: a, version, rewired: 0, remaining: need, failure: 'register-failed' });
+                    continue;
+                }
+                const after = checkVersionHookWiring(a, version);
+                const remaining = after.unwired.length + (after.settingsMissing ? (after.expected ?? 0) : 0);
+                out.push({ agent: a, version, rewired: Math.max(0, need - remaining), remaining });
+            }
+            catch {
+                // A shim write can fail before the native config writer returns its own
+                // errors. Record the same stable class and keep the repair moving to the
+                // one bounded runtime repair pass below.
+                out.push({ agent: a, version, rewired: 0, remaining: need, failure: 'register-failed' });
+            }
+        }
+    }
+    return out;
+}
+function runtimeRepairFilter(agent, versions) {
+    if (!agent)
+        return undefined;
+    // A single concrete target narrows to that version. Broad selectors (@all,
+    // agent-only) still make one bounded repair pass for that harness.
+    return {
+        agent,
+        ...(versions && versions.length === 1 ? { version: versions[0] } : {}),
+    };
+}
+/**
+ * RUSH-2415: delete npx-cache / unsafe-legacy / pre-1.22.30 agents-cli copies
+ * when a fixed peer already exists. DESTRUCTIVE (`fs.rmSync`), so it is never
+ * automatic — it runs only via `agents sync --prune-clis`. `injection` scopes the
+ * scan+delete to sandbox paths in tests so it can never touch a real install.
+ */
+function purgeStaleAgentsCliCopies(injection) {
+    let runningRoot = injection?.runningRoot;
+    if (!runningRoot) {
+        try {
+            // resolveRunningPackageRoot walks up until package.json names this package.
+            runningRoot = resolveRunningPackageRoot(__moduleDirname);
+        }
+        catch {
+            return null;
+        }
+    }
+    return remediateStaleAgentsCliInstalls({
+        runningRoot,
+        runningVersion: injection?.runningVersion ?? getCliVersion(),
+        ...(injection?.pathEnv !== undefined ? { pathEnv: injection.pathEnv } : {}),
+        ...(injection?.findOpts ? { findOpts: injection.findOpts } : {}),
+        ...(injection?.dryRun ? { dryRun: injection.dryRun } : {}),
+    });
+}
+// ─── public entrypoint ────────────────────────────────────────────────────────
+/**
+ * Run the post-reconcile repair pass over the agents/versions a sync just
+ * touched: heal live-home gaps (mode 'full', matching the old `doctor --fix`),
+ * re-wire hooks the diff-driven heal leaves behind, run one bounded managed-hook
+ * runtime repair, and — ONLY when `pruneClis` is set on the umbrella (no-agent)
+ * path — purge stale/legacy agents-cli copies. The purge is never automatic.
+ * Returns a full account; never writes to stdout.
+ */
+export async function repairAfterSync(opts) {
+    const healResult = await heal({
+        mode: 'full',
+        agent: opts.agent,
+        versions: opts.agent ? opts.versions : undefined,
+        ...(opts.cwd ? { cwd: opts.cwd } : {}),
+    });
+    // Re-wire hooks the diff-driven heal leaves behind (present file, not wired).
+    const hookRewire = rewireUnwiredHooks(opts.agent, opts.versions);
+    // One inspect→generate→verify pass after resource + native-wiring repair have
+    // settled. This routine never calls sync/register and never retries.
+    const hookRuntimeRepair = repairManagedHookRuntimeArtifacts({
+        filter: runtimeRepairFilter(opts.agent, opts.versions),
+    });
+    // The stale-CLI purge is DESTRUCTIVE and NEVER automatic: it runs only on the
+    // umbrella (no-agent) path AND only when the caller opted in via
+    // `agents sync --prune-clis`. Drift-fixers above always run; this does not.
+    const staleInstallPurge = (!opts.agent && opts.pruneClis === true)
+        ? purgeStaleAgentsCliCopies(opts.purgeInjection)
+        : null;
+    const report = {
+        heal: healResult,
+        hookRewire,
+        hookRuntimeRepair,
+        staleInstallPurge,
+    };
+    if (repairChangedAnything(report))
+        invalidateDoctorOverviewCache();
+    return report;
+}
+/** True when the repair pass changed (or attempted to change) anything. */
+export function repairChangedAnything(report) {
+    return (healChangedAnything(report.heal) ||
+        report.hookRewire.some((r) => r.rewired > 0 || r.remaining > 0 || r.failure !== undefined) ||
+        report.hookRuntimeRepair.attempts.length > 0 ||
+        (report.staleInstallPurge !== null &&
+            (report.staleInstallPurge.removed.length > 0 || report.staleInstallPurge.failed.length > 0)));
+}
+/**
+ * True when the RECONCILE repair left a per-version problem a human must fix — an
+ * unresolvable managed hook runtime shim, or a hook that could not be re-wired.
+ * These gate a sync's `ok`/exit code (the yosemite-s1 class the old
+ * `doctor --fix` surfaced).
+ *
+ * The machine-wide stale-CLI purge is deliberately EXCLUDED: a purge that could
+ * not delete a system-wide install (typically `EACCES` on `/usr/local/...`, which
+ * needs sudo) is a hygiene issue unrelated to whether the reconcile succeeded, so
+ * it must not flip a fleet peer's `agents sync --json` to `ok: false`. Purge
+ * failures stay fully visible — in the JSON `repair.staleInstallPurge.failed` and
+ * the rendered `hold`/`manual` lines.
+ */
+export function repairHadFailures(report) {
+    return (report.hookRewire.some((r) => r.failure !== undefined) ||
+        report.hookRuntimeRepair.needsAttention.length > 0);
+}
+/**
+ * Serialize the repair pass for a `--json` sync payload — the machine surface the
+ * deleted `doctor --fix --json` used to carry (heal detail + hook rewire + hook
+ * runtime repair + the umbrella stale-CLI purge). Attached under the `repair` key
+ * so fleet fan-out sees what the reconcile fixed and whether anything still needs
+ * a human (mirror `repairHadFailures`).
+ */
+export function repairAfterSyncJson(report) {
+    return {
+        heal: report.heal,
+        hookRewire: report.hookRewire,
+        hookRuntimeRepair: report.hookRuntimeRepair,
+        staleInstallPurge: report.staleInstallPurge,
+        hadFailures: repairHadFailures(report),
+    };
+}
+// ─── rendering (human output; sync calls this only when !json && !quiet) ─────
+function renderHealText(result, log) {
+    for (const r of result.repairedManifests) {
+        log(`  ${chalk.green('repair')}  plugin ${chalk.bold(r.plugin)} ${chalk.gray(`— dropped invalid ${r.droppedFields.join(', ')} field`)}`);
+    }
+    for (const r of result.refreshedPlugins) {
+        log(`  ${chalk.green('refresh')} plugin ${chalk.bold(r.plugin)}  ${chalk.gray(`${r.from} → ${r.to}`)}`);
+    }
+    for (const s of result.skippedPlugins) {
+        const why = s.reason === 'modified'
+            ? `locally modified — left as-is (run \`agents plugins update ${s.plugin}\` to force)`
+            : `no baseline recorded — left as-is (run \`agents plugins update ${s.plugin}\` to adopt)`;
+        log(`  ${chalk.yellow('hold  ')} plugin ${chalk.bold(s.plugin)}  ${chalk.gray(`${s.from} → ${s.upstream} available; ${why}`)}`);
+    }
+    for (const v of result.versions) {
+        const label = `${AGENT_NAMES[v.agent] || v.agent}@${v.version}`;
+        if (v.healed.length === 0 && v.skipped.length === 0)
+            continue;
+        const byKind = new Map();
+        for (const h of v.healed)
+            byKind.set(h.kind, (byKind.get(h.kind) ?? 0) + 1);
+        const parts = Array.from(byKind, ([k, n]) => `${n} ${k}`);
+        if (v.healed.length > 0) {
+            log(`  ${chalk.green('fixed ')}  ${label}  ${chalk.gray(parts.join(', '))}`);
+        }
+        const drift = v.skipped.filter((s) => s.reason === 'drift');
+        const unres = v.skipped.filter((s) => s.reason === 'unreconcilable');
+        if (drift.length > 0) {
+            log(`  ${chalk.yellow('drift ')}  ${label}  ${chalk.gray(`${drift.length} hand-edited — left as-is (use \`--diff\` to inspect)`)}`);
+        }
+        if (unres.length > 0) {
+            const names = unres.map((s) => `${s.kind}/${s.name}`).join(', ');
+            log(`  ${chalk.yellow('hold  ')}  ${label}  ${chalk.gray(`${unres.length} couldn't reconcile (${names}) — source/home mismatch the writer can't satisfy`)}`);
+        }
+    }
+}
+function renderHookRewireText(rewired, log) {
+    for (const r of rewired) {
+        const label = `${AGENT_NAMES[r.agent] || r.agent}@${r.version}`;
+        if (r.failure) {
+            log(`  ${chalk.red('hold  ')} ${label}  ${chalk.gray('native hook wiring could not be updated')}`);
+        }
+        else if (r.remaining === 0) {
+            log(`  ${chalk.green('rewired')} ${label}  ${chalk.gray(`${r.rewired} hook${r.rewired === 1 ? '' : 's'} wired into settings.json`)}`);
+        }
+        else {
+            log(`  ${chalk.yellow('hold  ')} ${label}  ${chalk.gray(`${r.remaining} hook${r.remaining === 1 ? '' : 's'} still unwired — run \`agents sync ${r.agent}@${r.version} --yes\``)}`);
+        }
+    }
+}
+function renderHookRuntimeRepairText(repair, log) {
+    for (const fixed of repair.fixed) {
+        log(`  ${chalk.green('fixed ')}  ${chalk.gray(fixed)}`);
+    }
+    for (const unresolved of repair.needsAttention) {
+        log(`  ${chalk.red('hold  ')}  ${chalk.gray(unresolved)}`);
+    }
+}
+function renderStaleInstallPurgeText(purge, log) {
+    if (purge.removed.length === 0 && purge.failed.length === 0 && purge.unresolved.length === 0)
+        return;
+    log(chalk.bold('\nStale agents-cli installs'));
+    for (const r of purge.removed) {
+        const why = r.reasons.join(', ');
+        log(`  ${chalk.green('purged')} ${chalk.gray(`${r.packageRoot}  ${r.version}  (${why})`)}`);
+    }
+    for (const f of purge.failed) {
+        log(`  ${chalk.red('hold  ')} ${chalk.gray(`${f.packageRoot}  ${f.version}  — ${f.error}`)}`);
+    }
+    for (const u of purge.unresolved) {
+        log(`  ${chalk.yellow('manual')} ${chalk.gray(`${u.packageRoot}  ${u.version}  — remove it with:`)}`);
+        log(`         ${chalk.bold(u.manualRemoveCommand)}`);
+    }
+}
+/**
+ * Print the repair pass's human-readable detail. Sync calls this only on the
+ * interactive / non-json path; the header is emitted only when something actually
+ * changed, so a clean sync stays quiet.
+ */
+export function renderRepairAfterSync(report, log = (s) => console.log(s)) {
+    if (!repairChangedAnything(report))
+        return;
+    renderHealText(report.heal, log);
+    renderHookRewireText(report.hookRewire, log);
+    renderHookRuntimeRepairText(report.hookRuntimeRepair, log);
+    if (report.staleInstallPurge)
+        renderStaleInstallPurgeText(report.staleInstallPurge, log);
+}

package/dist/lib/routers.d.ts

@@ -52,6 +52,17 @@ export declare function readRouter(name: string, cwd?: string): Router;
 export declare function writeRouter(router: Router): void;
 /** Delete a router from the user layer. Returns false if it did not exist there. */
 export declare function deleteRouter(name: string): boolean;
+/**
+ * Rename a router on disk, re-keying the user-layer file and preserving every
+ * field (harness allowlists, weights, linked accounts, hijack flag).
+ *
+ * Throws if `oldName` does not resolve, if it resolves from a non-user layer
+ * (renaming would write a shadowed user-layer copy -- see {@link routerSource}),
+ * or if `newName` already resolves in any layer. There is no `--force` /
+ * overwrite path -- a collision is a hard error directing the user to remove
+ * the target first.
+ */
+export declare function renameRouter(oldName: string, newName: string): void;
 /**
  * Fail-loud token validation (E1 of the Agent Router spec): a router MUST NOT
  * persist a harness id or model/tier token this machine cannot vouch for.
@@ -76,6 +87,6 @@ export declare function validateRouter(router: Router): void;
 /**
  * List every router resolved project > user > system (deduplicated union,
  * project wins on a name collision -- same precedence as {@link resolveResource}).
- * Malformed files are silently skipped, surfaced via `agents route show <name>`.
+ * Malformed files are silently skipped, surfaced via `agents route view <name>`.
  */
 export declare function listRouters(cwd?: string): Router[];

package/dist/lib/routers.js

@@ -89,6 +89,35 @@ export function deleteRouter(name) {
     fs.unlinkSync(file);
     return true;
 }
+/**
+ * Rename a router on disk, re-keying the user-layer file and preserving every
+ * field (harness allowlists, weights, linked accounts, hijack flag).
+ *
+ * Throws if `oldName` does not resolve, if it resolves from a non-user layer
+ * (renaming would write a shadowed user-layer copy -- see {@link routerSource}),
+ * or if `newName` already resolves in any layer. There is no `--force` /
+ * overwrite path -- a collision is a hard error directing the user to remove
+ * the target first.
+ */
+export function renameRouter(oldName, newName) {
+    validateRouterName(newName);
+    const source = routerSource(oldName);
+    if (source === null) {
+        throw new Error(`Router '${oldName}' not found.`);
+    }
+    if (source !== 'user') {
+        throw new Error(`Router '${oldName}' resolves from the '${source}' layer, not 'user' -- ` +
+            `agents route rename can only rename a user-layer router. Rename its file directly, ` +
+            `or create a user-layer router under a different name.`);
+    }
+    if (routerExists(newName)) {
+        throw new Error(`Router '${newName}' already exists; remove it first.`);
+    }
+    const router = readRouter(oldName);
+    router.name = newName;
+    writeRouter(router);
+    deleteRouter(oldName);
+}
 /**
  * Fail-loud token validation (E1 of the Agent Router spec): a router MUST NOT
  * persist a harness id or model/tier token this machine cannot vouch for.
@@ -137,7 +166,7 @@ export function validateRouter(router) {
 /**
  * List every router resolved project > user > system (deduplicated union,
  * project wins on a name collision -- same precedence as {@link resolveResource}).
- * Malformed files are silently skipped, surfaced via `agents route show <name>`.
+ * Malformed files are silently skipped, surfaced via `agents route view <name>`.
  */
 export function listRouters(cwd) {
     const routers = [];

package/dist/lib/scheduling/routines.js

@@ -1025,10 +1025,16 @@ export function validateJob(config) {
     if (config.remoteCwd !== undefined && strategy !== 'host' && strategy !== 'fleet') {
         errors.push('remoteCwd only applies to host/fleet-placed routines — set hostStrategy: host|fleet, or drop it');
     }
-    if (config.project !== undefined && (typeof config.project !== 'string' || config.project.trim() === '')) {
+    if (config.project === null) {
+        errors.push('project is null — quote YAML values that look like null literals');
+    }
+    else if (config.project !== undefined && (typeof config.project !== 'string' || config.project.trim() === '')) {
         errors.push('project (the singular execution anchor) must be a non-empty project name');
     }
-    if (config.cwd !== undefined && (typeof config.cwd !== 'string' || config.cwd.trim() === '')) {
+    if (config.cwd === null) {
+        errors.push('cwd is null — a bare ~ is YAML null; quote it as "~" for the home directory');
+    }
+    else if (config.cwd !== undefined && (typeof config.cwd !== 'string' || config.cwd.trim() === '')) {
         errors.push('cwd (the portable execution directory) must be a non-empty path string');
     }
     // `remoteCwd` is the legacy host-placement path; `cwd` is its canonical

package/dist/lib/session/active.d.ts

@@ -432,6 +432,19 @@ export interface ActiveSession {
      * session (PHNX-3688). Absent for non-tmux rows.
      */
     tmuxName?: string;
+    /**
+     * Daemon-computed 1–2 line goal from the session's first user turn (PHNX-3939).
+     * Produced off the request path by the background `SessionSummarizerService`
+     * and merged from the `session_summaries` cache in {@link applyImmutableMemo};
+     * rides the `sessions watch` stream free via the `...row` spread.
+     */
+    goal?: string;
+    /** Daemon-computed progress checkpoints, newest last (PHNX-3939). */
+    checkpoints?: import('./types.js').SessionCheckpoint[];
+    /** Daemon-computed detailed checklist for the session (PHNX-3939). */
+    summaryChecklist?: import('./types.js').SessionChecklistItem[];
+    /** Lifecycle of the daemon-computed summary; `skipped` when disabled (PHNX-3939). */
+    summaryState?: import('./types.js').SummaryState;
 }
 export declare function activeStatusFromCloudStatus(status: CloudTaskStatus): ActiveStatus;
 interface ActiveQueryOptions {