@phnx-labs/agents-cli 1.22.57 → 1.22.58

package/dist/commands/routines.js

@@ -245,12 +245,17 @@ function renderRoutineRows({ jobs, scheduler, overdueSet, link, now, local = tru
                     : lastStatus === 'missed' ? chalk.magenta
                         : chalk.gray;
         const overdueTag = overdueSet.has(job.name) ? chalk.yellow(' (overdue)') : '';
+        // Append the concrete reason a routine did not complete (auth_failed, wedged,
+        // blocked, missed) right in the Last Status cell, so the list answers "why"
+        // without a drill-in. Only for non-completed local runs; peer rows stay blank.
+        const reason = latestRun ? runFailureReason(latestRun) : null;
+        const reasonTag = reason ? chalk.gray(` — ${reason}`) : '';
         const agentLabelPadded = job.command
             ? chalk.magenta('command'.padEnd(10))
             : job.workflow
                 ? chalk.magenta(`wf:${job.workflow}`.padEnd(10))
                 : (job.agent || '').padEnd(10);
-        console.log(`  ${chalk.cyan(job.name.padEnd(NAME_W))} ${agentLabelPadded} ${repoCell}${' '.repeat(repoPadding)} ${deviceCell}${' '.repeat(devicePad)} ${schedStr.padEnd(SCHED_W)} ${enabledStr}${' '.repeat(enabledPad)} ${chalk.gray(nextStr.padEnd(NEXT_W))} ${statusColor(lastStatus)}${overdueTag}`);
+        console.log(`  ${chalk.cyan(job.name.padEnd(NAME_W))} ${agentLabelPadded} ${repoCell}${' '.repeat(repoPadding)} ${deviceCell}${' '.repeat(devicePad)} ${schedStr.padEnd(SCHED_W)} ${enabledStr}${' '.repeat(enabledPad)} ${chalk.gray(nextStr.padEnd(NEXT_W))} ${statusColor(lastStatus)}${overdueTag}${reasonTag}`);
     }
 }
 function parseRoutineTrigger(options) {
@@ -622,6 +627,43 @@ function routineMatchesQuery(job, q) {
         .toLowerCase()
         .includes(q);
 }
+/** Friendly one-liners for the claim a `skipped` run lost. */
+const SKIP_REASON_LABEL = {
+    active_run: 'wedged: a prior run is still active',
+    duplicate_slot: 'duplicate slot (already fired)',
+    wrong_owner: 'pinned to another device',
+};
+/**
+ * The short, human reason a run did not simply complete — for inline display in
+ * the list/detail so "why did it fail" needs no dig into the run dir. Prefers the
+ * concrete `errorMessage` (which carries `auth_failed: …`, OAuth-revoked, timeouts),
+ * then the readiness block for a `blocked` run, then the mapped skip reason. Returns
+ * null for a healthy (`completed`/`running`) run, which needs no annotation.
+ */
+export function runFailureReason(run) {
+    if (run.status === 'completed' || run.status === 'running')
+        return null;
+    const compact = (s) => {
+        const one = s.replace(/\s+/g, ' ').trim();
+        return one.length > 80 ? one.slice(0, 79) + '…' : one;
+    };
+    if (run.errorMessage)
+        return compact(run.errorMessage);
+    if (run.status === 'blocked' && run.readiness) {
+        return compact(run.readiness.message || run.readiness.code);
+    }
+    if (run.skipReason)
+        return SKIP_REASON_LABEL[run.skipReason];
+    if (run.status === 'missed')
+        return 'scheduler was not running when it came due';
+    // The most common failure shape: a command/agent body that exited nonzero with
+    // no structured errorMessage (the cause is in stdout). Naming the exit code is
+    // still more than the bare status word, and tells the reader it ran and threw.
+    if ((run.status === 'failed' || run.status === 'timeout') && run.exitCode !== null && run.exitCode !== undefined) {
+        return `exit ${run.exitCode}`;
+    }
+    return null;
+}
 /** One compact routine row for the browser list: name · kind · schedule · next · last. */
 function routineBrowserRow(job, scheduler, overdueSet, now) {
     const kind = job.command ? 'command' : job.workflow ? `wf:${job.workflow}` : job.agent ?? '?';
@@ -685,7 +727,12 @@ function buildRoutineDetail(job, scheduler, now) {
                     ? chalk.red(run.status)
                     : chalk.yellow(run.status);
             const dur = run.completedAt ? ` ${formatRunDuration(run.startedAt, run.completedAt)}` : '';
-            lines.push(`  ${run.startedAt}  ${status}${dur}`);
+            // Surface WHY a run did not complete, inline, so "looking at status" does not
+            // require digging into the run dir. auth_failed / OAuth-revoked, a wedged
+            // active-run skip, or a readiness block all live on the RunMeta already.
+            const reason = runFailureReason(run);
+            const why = reason ? chalk.gray(` — ${reason}`) : '';
+            lines.push(`  ${run.startedAt}  ${status}${dur}${why}`);
         }
     }
     // 4. Stats
@@ -1533,7 +1580,9 @@ export function registerRoutinesCommands(program) {
                 : run.status === 'failed'
                     ? chalk.red(run.status)
                     : chalk.yellow(run.status);
-            console.log(`  ${run.runId}  ${status}  ${run.startedAt}`);
+            const reason = runFailureReason(run);
+            const why = reason ? chalk.gray(` — ${reason}`) : '';
+            console.log(`  ${run.runId}  ${status}  ${run.startedAt}${why}`);
         }
     });
     routinesCmd
@@ -1856,6 +1905,11 @@ export function registerRoutinesCommands(program) {
             chalk.gray(`  ${run.startedAt}`) +
             chalk.gray(formatRunDuration(run.startedAt, run.completedAt)) +
             (run.exitCode !== null && run.exitCode !== undefined ? chalk.gray(`  exit ${run.exitCode}`) : ''));
+        // The structured reason (auth_failed, blocked readiness, wedged skip) — the
+        // report/stdout tail below often buries or omits it, so name it up front.
+        const logsReason = runFailureReason(run);
+        if (logsReason)
+            console.log(chalk.red('reason: ') + chalk.gray(logsReason));
         console.log(chalk.gray('─'.repeat(60)));
         const reportPath = path.join(getRunDir(name, runId), 'report.md');
         if (fs.existsSync(reportPath)) {

package/dist/commands/sessions-picker.d.ts

@@ -1,6 +1,7 @@
 import type { SessionEvent, SessionMeta, TodoProgress } from '../lib/session/types.js';
 import { fetchPeerPreviewDigest } from '../lib/session/remote-list.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
+import type { FileChange } from '../lib/session/digest.js';
 import { extractArtifacts, extractHooks, extractLinks, extractSkills } from '../lib/session/highlights.js';
 /**
  * Compact checklist tally for list rows and previews (RUSH-2045).
@@ -118,6 +119,16 @@ export interface SessionPreviewDigest {
     backgroundShellCount?: number;
     toolTags: string[];
     changes: ReturnType<typeof changeCounts>;
+    /**
+     * The per-file source paths behind `changes`. `changes` keeps the roll-up
+     * counts every existing consumer already reads; `changedFiles` carries the
+     * real path + op the CLI computed at scan time (via classifyFileChanges) and
+     * used to discard — kept so a consumer that renders a per-file diff list (the
+     * AGI EXT Fleet detail panel, PHNX-2973) has the paths, not just the totals.
+     * Capped so a session that rewrote thousands of files can't bloat the cached
+     * digest / JSON payload; the `changes` counts stay the true totals.
+     */
+    changedFiles: FileChange[];
     dirs: string[];
     repos: string[];
     artifacts: ReturnType<typeof extractArtifacts>;

package/dist/commands/sessions-picker.js

@@ -229,6 +229,14 @@ export function sanitizeRemoteDigest(raw) {
         backgroundShellCount: optNum(d.backgroundShellCount),
         toolTags: strList(d.toolTags),
         changes,
+        // Per-file paths from an untrusted peer: keep only well-formed {path, op}
+        // entries (path scrubbed of terminal escapes, op a known FileOp), bounded
+        // like the local build so a hostile peer can't flood the pane.
+        changedFiles: objList(d.changedFiles, (f) => {
+            const path = str(f.path);
+            const op = f.op === 'created' || f.op === 'modified' || f.op === 'deleted' ? f.op : undefined;
+            return path && op ? { path, op } : undefined;
+        }).slice(0, CHANGED_FILES_MAX),
         dirs: strList(d.dirs),
         repos: strList(d.repos),
         artifacts: objList(d.artifacts, (a) => {
@@ -655,6 +663,10 @@ const LAST_RESPONSE_MAX_LINES = 15;
 const LAST_RESPONSE_MAX_LINES_WITH_TODOS = 8;
 const TODOS_MAX_ITEMS = 5;
 const DIRS_TOUCHED_MAX = 5;
+// Upper bound on the per-file `changedFiles` list carried on the digest. High
+// enough to cover any real session's edits, low enough that a runaway rewrite
+// can't bloat the cached JSON. The `changes` counts stay the true totals.
+const CHANGED_FILES_MAX = 200;
 /** Fold a harness-normalized event stream into the stable preview data model. */
 export function buildSessionPreviewDigest(events, session) {
     let firstUser = '';
@@ -747,6 +759,10 @@ export function buildSessionPreviewDigest(events, session) {
         backgroundShellCount,
         toolTags: [...toolTags],
         changes: chg,
+        // Full per-file list the picker used to collapse to `chg` and throw away.
+        // Bounded so a mass-rewrite session can't blow up the cached digest; the
+        // counts above remain the true totals.
+        changedFiles: changes.slice(0, CHANGED_FILES_MAX),
         dirs: directoriesTouched(session, events, changes),
         repos: extractRepos(events, session.cwd),
         artifacts: extractArtifacts(changes),

package/dist/commands/sessions.js

@@ -2061,6 +2061,7 @@ export async function renderSessionPreview(query, scope) {
                 tokenCount: session.tokenCount,
                 costUsd: session.costUsd,
                 label: session.label,
+                topic: session.topic,
                 ticketId: session.ticketId,
                 prUrl: session.prUrl,
             },

package/dist/commands/share.d.ts

@@ -250,6 +250,17 @@ export interface ShareUpdateResult {
     templateHash: string;
     baseUrl: string;
     workerName: string;
+    /** True when this was a `--check` run: nothing was deployed, the fields below
+     * just report whether a deploy WOULD be needed. Used by the release train to
+     * decide during preflight — before it verifies deploy creds — whether this
+     * release even changes the Worker. */
+    checked?: boolean;
+    /** Whether the current `worker-template.ts` render differs from what the
+     * endpoint last deployed (or `--force`/an endpoint with no recorded hash). */
+    deployNeeded?: boolean;
+    /** The template hash the endpoint last deployed, per local config. Undefined
+     * on an endpoint provisioned before the hash field existed. */
+    deployedHash?: string;
 }
 /** Re-deploy the Worker script on an ALREADY-provisioned endpoint to match the
  * current `worker-template.ts`. Reuses the existing account/worker/bucket and
@@ -264,6 +275,9 @@ export declare function runShareUpdate(opts?: {
     account?: string;
     token?: string;
     force?: boolean;
+    /** Report whether a deploy is needed and return without deploying. Needs no
+     * Cloudflare credentials — change detection is a pure local render+hash. */
+    check?: boolean;
     request?: CloudflareRequester;
     /** Bind PHOENIX_ID_BASE even when the configured hostname is not the managed domain. */
     managed?: boolean;

package/dist/commands/share.js

@@ -820,6 +820,7 @@ Prefer to change visibility without a browser? Use 'agents artifacts share visib
         .option('--account <id>', 'Cloudflare account id override (default: the configured endpoint\'s account)')
         .option('--token <t>', 'Cloudflare API token (else read from --bundle)')
         .option('--force', 're-deploy even if the deployed template already matches')
+        .option('--check', 'report whether a deploy is needed and exit without deploying (needs no Cloudflare credentials)')
         // Named --update-json, not --json: `share <file>` (the parent) already
         // owns --json for its own publish-time result. Commander resolves an
         // option's long name against the WHOLE ancestor chain, so a same-named
@@ -832,6 +833,12 @@ Prefer to change visibility without a browser? Use 'agents artifacts share visib
                 console.log(JSON.stringify(result, null, 2));
                 return;
             }
+            if (result.checked) {
+                console.log(result.deployNeeded
+                    ? chalk.yellow(`Worker '${result.workerName}' template is outdated — deploy needed (current render ${result.templateHash.slice(0, 12)}…).`)
+                    : chalk.dim(`Worker '${result.workerName}' already matches the current template — no deploy needed.`));
+                return;
+            }
             if (result.updated) {
                 console.log(chalk.green(`Worker '${result.workerName}' updated → template ${result.templateHash.slice(0, 12)}…`));
             }
@@ -851,11 +858,18 @@ Prefer to change visibility without a browser? Use 'agents artifacts share visib
 
       # Force a re-deploy even though the template hash already matches
       agents artifacts share update --force
+
+      # Report whether a deploy is due without deploying (no Cloudflare creds needed)
+      agents artifacts share update --check --update-json
     `,
         notes: `
   Reuses the existing account/worker/bucket from 'agents artifacts share status' and the
   existing write token — it never re-provisions a bucket, touches routes, or
   regenerates the token. See 'agents artifacts share status' for whether an update is due.
+
+  --check renders the current template and compares its hash to what the endpoint last
+  deployed, then exits — deploying nothing and reading no Cloudflare credentials. The
+  release train uses it to decide, before publish, whether a release changes the Worker.
     `,
     });
     shareCmd
@@ -1222,6 +1236,27 @@ export async function runShareUpdate(opts = {}) {
     if (!cfg) {
         throw new Error("Not configured. Run 'agents artifacts setup' (to provision) or 'agents artifacts share join' first.");
     }
+    // Change detection is a pure local computation (render + sha256), so it needs
+    // no Cloudflare credentials. The release train calls this in `--check` mode
+    // during preflight — BEFORE it has verified the deploy creds — to decide
+    // whether this release changes the Worker at all. `shareTemplateStatus` is the
+    // same comparator `agents artifacts share status` uses; 'unknown' (an endpoint
+    // with no recorded hash) deploys, mirroring `updateWorker`'s undefined-previous
+    // behavior.
+    const worker = renderWorkerBundle();
+    const templateHash = hashWorkerScript(worker.script);
+    const deployNeeded = opts.force === true || shareTemplateStatus(cfg) !== 'current';
+    if (opts.check) {
+        return {
+            updated: false,
+            checked: true,
+            deployNeeded,
+            templateHash,
+            deployedHash: cfg.templateHash,
+            baseUrl: cfg.baseUrl,
+            workerName: cfg.workerName,
+        };
+    }
     const { apiToken, accountId: acctFromBundle } = readCloudflareCreds(opts.bundle ?? DEFAULT_CF_BUNDLE, {
         apiToken: opts.token,
         accountId: opts.account,
@@ -1231,7 +1266,6 @@ export async function runShareUpdate(opts = {}) {
         throw new Error("Share endpoint has no Cloudflare account id — `agents artifacts share update` cannot call the API. Pass --account <id>, or re-run 'agents artifacts share join'.");
     }
     const writeToken = readWriteToken();
-    const worker = renderWorkerBundle();
     const phoenixIdBase = phoenixIdBaseForDeploy({ managed: opts.managed }, cfg);
     const provisionOpts = {
         ...(opts.request ? { request: opts.request } : {}),
@@ -1242,7 +1276,14 @@ export async function runShareUpdate(opts = {}) {
     if (!result.skipped) {
         writeShareConfig({ ...cfg, accountId, templateHash: result.templateHash });
     }
-    return { updated: !result.skipped, templateHash: result.templateHash, baseUrl: cfg.baseUrl, workerName: cfg.workerName };
+    return {
+        updated: !result.skipped,
+        templateHash: result.templateHash,
+        deployNeeded,
+        deployedHash: cfg.templateHash,
+        baseUrl: cfg.baseUrl,
+        workerName: cfg.workerName,
+    };
 }
 function cleanHostname(domain) {
     const raw = domain?.trim().replace(/\/+$/, '');

package/dist/commands/status.js

@@ -78,7 +78,7 @@ export function registerStatusCommand(syncCmd) {
         // A non-git / partial ~/.agents is its own drift state, not a per-agent
         // "N missing" — surface it distinctly so the real problem isn't buried (PHNX-3301).
         if (status.user.notGitRepo) {
-            console.log(`  ${'~/.agents (user repo)'.padEnd(28)} ${chalk.yellow('not a git repo — will adopt on next `agents repo sync user`')}`);
+            console.log(`  ${'~/.agents (user repo)'.padEnd(28)} ${chalk.yellow('not a git repo — will adopt on next `agents sync` (or `agents repo sync user`)')}`);
         }
         if (status.agents.length === 0) {
             console.log(chalk.gray('  (no installed agent versions)'));

package/dist/commands/sync.js

@@ -45,6 +45,7 @@ import { runLaunchSync } from '../lib/project-launch.js';
 import { formatKeptProjectResources } from '../lib/project-resources.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { runUmbrellaSync } from '../lib/sync-umbrella.js';
+import { verifyVersionConverged, formatResidualDrift } from '../lib/sync-status.js';
 import { addHostOption } from '../lib/hosts/option.js';
 import { syncRepoGit, adoptUserRepoIfNeeded, recordUserRepoRemote, resolveUserRepoRemoteUrl } from '../lib/git.js';
 import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos } from '../lib/state.js';
@@ -53,6 +54,46 @@ import { registerStatusCommand } from './status.js';
 function emitJson(payload) {
     console.log(JSON.stringify(payload));
 }
+/**
+ * Post-reconcile verification (PHNX-3186): after a sync writes into a set of
+ * version homes, re-read each home and confirm it now matches its resolved
+ * sources. The `agents sync` success line MUST NOT read "reconciled" while the
+ * drift it was asked to fix stays put. Any residual drifted/missing resource
+ * sets a non-zero exit code and — outside `--json` — names the exact unfixed
+ * drift so the operator sees what did not converge instead of a false ✓. Orphans
+ * are excluded (sync never removes them). Returns the residual for `--json`.
+ */
+function verifyReconciled(pairs, cwd) {
+    const residual = [];
+    const seen = new Set();
+    for (const { agent, version } of pairs) {
+        const key = `${agent}@${version}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const r = verifyVersionConverged(agent, version, cwd);
+        if (r)
+            residual.push(r);
+    }
+    // Residual drift is reported loudly via `ok:false` + the printed ⚠ block, but
+    // does NOT change the exit code — matching the declined-write precedent
+    // (RUSH-2700). The fleet fan-out (`agents sync --device all`) THROWS on a
+    // non-zero peer exit (`hosts/passthrough.ts`), discarding that box's JSON, so a
+    // non-zero exit here would hide the very `residualDrift` payload it emitted.
+    // Callers that must treat an incomplete sync as failure read `ok`/`residualDrift`
+    // from `--json`, exactly as they already do for declines.
+    return residual;
+}
+/** Print the residual-drift block naming exactly what did not converge. */
+function printResidual(residual, errLog) {
+    if (residual.length === 0)
+        return;
+    const lines = formatResidualDrift(residual);
+    errLog(chalk.yellow(`⚠ sync did not fully reconcile — ${lines.length} resource(s) still drift after writing:`));
+    for (const line of lines)
+        errLog(chalk.yellow(`  ${line}`));
+    errLog(chalk.gray('  Re-run the sync; a gap that survives a re-run is a real unreconcilable drift — report it.'));
+}
 /**
  * Translate per-kind CLI flags into a `ResourceSelection` for `buildSelection`.
  * Returns `undefined` when no kind flag was given (caller should use full sync).
@@ -429,6 +470,7 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
         await runInteractiveReconcile(opts, outLog, errLog);
         return;
     }
+    const cwd = opts.cwd || process.cwd();
     const flags = {
         repos: opts.repos,
         secrets: opts.secrets,
@@ -459,10 +501,18 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
         // --cloud (fetch-only, no local reconcile).
         if (!opts.cloud)
             evictCentralBrowserProfilesForSync(quiet, json, outLog, errLog);
+        // Post-reconcile verification (PHNX-3186): re-read every version the reconcile
+        // wrote into and confirm it now matches source. Without this the umbrella
+        // printed `✓ sync: reconciled` unconditionally, the exact false-success the
+        // ticket reports. Residual drift downgrades the line and sets a non-zero exit.
+        const residual = result.reconciled
+            ? verifyReconciled(result.reconciledVersions.map((r) => ({ agent: r.agent, version: r.version })), cwd)
+            : [];
         if (json) {
             emitJson({
-                // A refused resource is not a clean sync (RUSH-2700).
-                ok: result.declined.length === 0,
+                // A refused resource OR residual drift is not a clean sync (RUSH-2700 +
+                // PHNX-3186).
+                ok: result.declined.length === 0 && residual.length === 0,
                 mode: 'umbrella',
                 plan: result.plan,
                 repos: result.repos,
@@ -470,6 +520,7 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
                 devices: result.devices,
                 reconciled: result.reconciled,
                 declined: result.declined,
+                residualDrift: residual,
             });
             return;
         }
@@ -482,12 +533,18 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
             if (result.secrets) {
                 parts.push(result.secrets.skipped ? 'secrets skipped' : `secrets ${result.secrets.pulled} pulled`);
             }
+            // Only claim "reconciled" when the reconcile actually converged. Residual
+            // drift is already printed loudly by verifyReconciled above; reflect it in
+            // the one-line summary rather than a bare ✓.
             if (result.reconciled)
-                parts.push('reconciled');
-            outLog(chalk.green(`✓ sync: ${parts.join(' · ') || 'nothing to do'}`));
+                parts.push(residual.length === 0 ? 'reconciled' : 'reconcile INCOMPLETE');
+            const symbol = residual.length === 0 ? chalk.green('✓') : chalk.yellow('⚠');
+            const line = `${symbol} sync: ${parts.join(' · ') || 'nothing to do'}`;
+            outLog(residual.length === 0 ? chalk.green(line) : chalk.yellow(line));
             const errs = [...(result.repos?.errors ?? []), ...(result.secrets?.errors ?? [])];
             for (const e of errs)
                 errLog(chalk.yellow(`  ! ${e}`));
+            printResidual(residual, errLog);
         }
     }
     catch (err) {
@@ -700,13 +757,23 @@ async function runSync(agentSpec, repoArg, opts) {
             if (!quiet && !json)
                 printSyncDetail(result, agentId, v, cwd);
         }
+        // Verify each version actually converged; a repo-scoped sync only touched
+        // that repo's kinds, so skip verification there (the other layers legitimately
+        // still differ and are not this run's responsibility).
+        const residual = repoScope
+            ? []
+            : verifyReconciled(versions.map(({ version: v }) => ({ agent: agentId, version: v })), cwd);
+        if (!quiet && !json)
+            printResidual(residual, errLog);
         if (json) {
             emitJson({
-                // Any version that refused a write makes the whole run not-ok (RUSH-2700).
-                ok: versions.every(({ result }) => result.declined.length === 0),
+                // Any version that refused a write, or any residual drift after the
+                // reconcile, makes the whole run not-ok (RUSH-2700 + PHNX-3186).
+                ok: versions.every(({ result }) => result.declined.length === 0) && residual.length === 0,
                 mode: 'agent-all',
                 agent: agentId,
                 repo: repoScope,
+                residualDrift: residual,
                 ...healedPointers,
                 versions: versions.map(({ version: v, result }) => ({
                     version: v,
@@ -901,6 +968,11 @@ async function runSync(agentSpec, repoArg, opts) {
         return;
     }
     const result = syncResourcesToVersion(agentId, version, selection, { projectDir, cwd, force, allowExecSurfaces: !!opts.allowExecSurfaces });
+    // Post-reconcile verification (PHNX-3186). Only for a FULL reconcile
+    // (`!selection`): an interactive subset-selection deliberately touched only the
+    // picked kinds, so the rest legitimately still differs and is not this run's
+    // failure. This is the exact path `agents sync <agent>[@version]` takes.
+    const residual = selection ? [] : verifyReconciled([{ agent: agentId, version }], cwd);
     // Compile project-scope rules into the workspace itself so each agent's
     // native loader picks up cwd/<INSTRUCTIONS_FILE>. projectDir is the
     // .agents/ directory; the workspace root is its parent.
@@ -910,8 +982,11 @@ async function runSync(agentSpec, repoArg, opts) {
         projectCompile = compileRulesForProject(projectRoot);
     }
     if (json) {
+        const base = agentSyncJson(agentId, version, result);
         emitJson({
-            ...agentSyncJson(agentId, version, result),
+            ...base,
+            ok: base.ok === true && residual.length === 0,
+            residualDrift: residual,
             ...healedPointers,
             projectCompile: projectCompile
                 ? {
@@ -928,6 +1003,7 @@ async function runSync(agentSpec, repoArg, opts) {
         return;
     // ---------- 6. Detailed output ----------
     printSyncDetail(result, agentId, version, cwd);
+    printResidual(residual, errLog);
     if (projectCompile?.compiled) {
         const linkInfo = projectCompile.symlinks.length > 0
             ? ` (+ ${projectCompile.symlinks.join(', ')})`

package/dist/commands/traces.js

@@ -109,6 +109,13 @@ async function handleSync(opts) {
         parts.push(chalk.dim('nothing new'));
     }
     console.log(parts.join(chalk.dim('  ·  ')));
+    // The per-session data can upload cleanly while the aggregated console shard
+    // fails to refresh (e.g. the sessions DB is locked by a running app). That used
+    // to be silent, so the console sat stale with no signal here (PHNX-3401).
+    if (result.indexError) {
+        console.log(chalk.yellow('  ⚠ console index not refreshed') +
+            chalk.dim(` (${result.indexError}) — dashboard may be stale; it will retry next sync`));
+    }
 }
 async function handleStatus() {
     const ledger = readSyncLedger();

package/dist/index.d.ts

@@ -15,7 +15,7 @@
  *   - `__secrets-get` / `__secrets-ping` / `__secrets-lock` (SYNC_* tokens)
  *   - `__shim`
  *   - `__claude-statusline`
- *   - `__usage-ingest`
+ *   - `__usage-ingest` / `__usage-export`
  *   - `__daemon-run`
  *
  * The tokens are imported from the leaf module sync-commands.ts — the SAME

package/dist/index.js

@@ -15,7 +15,7 @@
  *   - `__secrets-get` / `__secrets-ping` / `__secrets-lock` (SYNC_* tokens)
  *   - `__shim`
  *   - `__claude-statusline`
- *   - `__usage-ingest`
+ *   - `__usage-ingest` / `__usage-export`
  *   - `__daemon-run`
  *
  * The tokens are imported from the leaf module sync-commands.ts — the SAME
@@ -84,6 +84,11 @@ if (process.argv[2] === '__usage-ingest') {
     const { runUsageIngest } = await import('./lib/accounting/usage-ingest.js');
     process.exit(await runUsageIngest());
 }
+if (process.argv[2] === '__usage-export') {
+    const { exportClaudeUsageCacheRows } = await import('./lib/accounting/usage.js');
+    process.stdout.write(JSON.stringify({ v: 1, rows: exportClaudeUsageCacheRows() }));
+    process.exit(0);
+}
 if (process.argv[2] === '__daemon-run') {
     const { runDaemon, log: daemonLog } = await import('./lib/daemon/daemon.js');
     // RUSH-2418: the daemon is the one always-on process here, and it ran with no

package/dist/lib/account-registry.d.ts

@@ -63,11 +63,15 @@ export declare function unbindAccount(nameOrId: string, target: string): void;
 /** Every target bound to `accountId`: this box's device-doc bindings merged over
  * the fleet-shared central bindings (PHNX-3315). */
 export declare function accountBindings(accountId: string, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>): string[];
+export interface AccountSelection {
+    id: string;
+    source: 'explicit' | 'binding' | 'default';
+}
 /** Explicit selection wins over a configured per-harness default. */
 export declare function resolveAccountSelection(explicit: string | undefined, agent: AgentId, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, opts?: {
     useDefault?: boolean;
     target?: string;
-}): string | undefined;
+}): AccountSelection | undefined;
 export interface AddAccountOptions {
     baseUrl?: string;
 }