@phnx-labs/agents-cli 1.22.56 → 1.22.58

package/dist/commands/insights.d.ts

@@ -7,20 +7,21 @@
  *                                rhythm, edits) — split by Claude account by default
  *   agents insights mix          COUNTERS (sessions index + usage.db recipes:
  *                                harness/model mix, token ratios, secrets, browser)
- *   agents insights <recipe>     One baked mix recipe (harness-mix, tools-per-session, …)
+ *   agents insights mix <recipe> One baked mix recipe (harness-mix, tools-per-session, …)
  *   agents insights query        Raw usage.db rows
  *
- * Sibling observe verbs (stay separate — different questions):
+ * Sibling observe verbs under this same group (different questions):
  *
  *   agents insights cost    what you spent ($ and duration)
  *   agents insights output  what shipped (burn vs PRs and commits)
+ *   agents insights perf    latency (hooks, CLI commands, agent.run) — not popularity
  *   agents view             live quota headroom (per account, with auth state)
- *   agents perf             latency (hooks, CLI commands, agent.run) — not popularity
  *   agents sessions stats   which skills/slash-commands were explicitly invoked
  *
  * Why mix lives here (not a second top-level `trends`): two abstract "analytics"
  * nouns taught agents and humans to guess. One verb, two engines — cheap SQL mix
- * vs transcript facets. Latency stays on `perf` so it is never confused with mix.
+ * vs transcript facets. `perf` (latency) is also nested here now (PHNX-3391) —
+ * performance is an insight, kept a distinct sub-verb so it is never confused with mix.
  *
  * Modelled on Claude Code's `/insights`, with the difference that motivated it: that
  * command reads one account's directory, while `balanced` rotation sprays sessions
@@ -31,7 +32,8 @@
  * the coaching prose by piping the AGGREGATE (never raw transcripts) through a headless
  * `claude -p`.
  *
- * Former top-level `agents trends` is `agents insights mix` / `agents insights trends`.
+ * Former top-level `agents trends` is `agents insights mix` (one section:
+ * `agents insights mix <recipe>`; `--list` names them).
  */
 import type { Command } from 'commander';
 export declare function registerInsightsCommand(program: Command): void;

package/dist/commands/insights.js

@@ -7,20 +7,21 @@
  *                                rhythm, edits) — split by Claude account by default
  *   agents insights mix          COUNTERS (sessions index + usage.db recipes:
  *                                harness/model mix, token ratios, secrets, browser)
- *   agents insights <recipe>     One baked mix recipe (harness-mix, tools-per-session, …)
+ *   agents insights mix <recipe> One baked mix recipe (harness-mix, tools-per-session, …)
  *   agents insights query        Raw usage.db rows
  *
- * Sibling observe verbs (stay separate — different questions):
+ * Sibling observe verbs under this same group (different questions):
  *
  *   agents insights cost    what you spent ($ and duration)
  *   agents insights output  what shipped (burn vs PRs and commits)
+ *   agents insights perf    latency (hooks, CLI commands, agent.run) — not popularity
  *   agents view             live quota headroom (per account, with auth state)
- *   agents perf             latency (hooks, CLI commands, agent.run) — not popularity
  *   agents sessions stats   which skills/slash-commands were explicitly invoked
  *
  * Why mix lives here (not a second top-level `trends`): two abstract "analytics"
  * nouns taught agents and humans to guess. One verb, two engines — cheap SQL mix
- * vs transcript facets. Latency stays on `perf` so it is never confused with mix.
+ * vs transcript facets. `perf` (latency) is also nested here now (PHNX-3391) —
+ * performance is an insight, kept a distinct sub-verb so it is never confused with mix.
  *
  * Modelled on Claude Code's `/insights`, with the difference that motivated it: that
  * command reads one account's directory, while `balanced` rotation sprays sessions
@@ -31,7 +32,8 @@
  * the coaching prose by piping the AGGREGATE (never raw transcripts) through a headless
  * `claude -p`.
  *
- * Former top-level `agents trends` is `agents insights mix` / `agents insights trends`.
+ * Former top-level `agents trends` is `agents insights mix` (one section:
+ * `agents insights mix <recipe>`; `--list` names them).
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
@@ -47,6 +49,7 @@ import { formatUsd } from '../lib/pricing/index.js';
 import { formatDuration } from '../lib/session/render.js';
 import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
 import { registerMixCommands } from '../lib/analytics/mix-commands.js';
+import { registerPerfSubcommand } from './perf.js';
 import { registerCostCommand } from './cost.js';
 import { registerOutputCommand } from './output.js';
 const execFileAsync = promisify(execFile);
@@ -570,7 +573,7 @@ function configureInsightsCommand(cmd) {
       # Counter mix board (harness/model/token/secrets recipes) — former agents trends
       agents insights mix
       agents insights mix --days 30
-      agents insights harness-mix --json
+      agents insights mix harness-mix --json
       agents insights query --kind secret --days 7
 
       # One account only, all of its history
@@ -586,10 +589,10 @@ function configureInsightsCommand(cmd) {
       Two paths under one verb:
         bare \`agents insights\`     — transcript behaviour (tools, friction, rhythm, by account)
         \`agents insights mix\`      — cheap counters from sessions.db + usage.db
-      Latency is \`agents perf\` (not mix). Quota is \`agents view\`. Spend is
+      Latency is \`agents insights perf\` (not mix). Quota is \`agents view\`. Spend is
       \`agents insights cost\`; shipped output is \`agents insights output\`. Skill/slash popularity
-      is \`agents sessions stats\`. Former top-level \`agents trends\` is \`agents insights mix\`
-      (also \`agents insights trends\`).
+      is \`agents sessions stats\`. Former top-level \`agents trends\` is \`agents insights mix\`.
+      One recipe is \`agents insights mix <recipe>\` (e.g. \`harness-mix\`); \`--list\` names them.
 
       The behavioural report parses in-scope transcripts once and caches facets; later runs
       re-read only files that changed. \`--refresh\` forces a full re-read.
@@ -606,6 +609,10 @@ export function registerInsightsCommand(program) {
     configureInsightsCommand(cmd);
     registerCostCommand(cmd);
     registerOutputCommand(cmd);
+    // Latency rollups (former top-level `agents perf` → `agents insights perf`,
+    // PHNX-3391). A sibling observe verb of cost/output, so it lives on the
+    // top-level insights group beside them, not under `sessions insights`.
+    registerPerfSubcommand(cmd);
 }
 export function registerSessionsInsightsCommand(sessions) {
     configureInsightsCommand(sessions.command('insights'));

package/dist/commands/monitors.js

@@ -139,6 +139,13 @@ function livenessLabel(monitor, state, liveness) {
     if (liveness.lastError) {
         return chalk.red(`checked ${liveness.checkCount}x · error: ${liveness.lastError.replace(/\s+/g, ' ').slice(0, 60)}`);
     }
+    const latestFire = listFires(monitor.name).at(-1);
+    if (latestFire) {
+        const outcome = resolveFireOutcome(monitor.name, latestFire);
+        if (!outcome.ok) {
+            return chalk.red(`ACTION FAILED ${formatRelativeTime(latestFire.firedAt)}`) + chalk.gray(` · checked ${liveness.checkCount}x`);
+        }
+    }
     if (state?.lastFiredAt) {
         return chalk.green(`fired ${formatRelativeTime(state.lastFiredAt)}`) + chalk.gray(` · checked ${liveness.checkCount}x`);
     }
@@ -629,6 +636,8 @@ export function registerMonitorsCommands(program) {
             const payload = monitors.map((m) => {
                 const state = readState(m.name);
                 const liveness = readLiveness(m.name);
+                const latestFire = listFires(m.name).at(-1);
+                const latestOutcome = latestFire ? resolveFireOutcome(m.name, latestFire) : null;
                 return {
                     name: m.name,
                     enabled: m.enabled,
@@ -650,6 +659,8 @@ export function registerMonitorsCommands(program) {
                     lastError: liveness?.lastError ?? null,
                     consecutiveErrors: liveness?.consecutiveErrors ?? 0,
                     stalled: isStalled(m, liveness),
+                    lastActionStatus: latestOutcome?.runStatus ?? null,
+                    lastActionFailed: latestOutcome ? !latestOutcome.ok : false,
                 };
             });
             stdoutJson(payload);

package/dist/commands/perf.d.ts

@@ -1,12 +1,13 @@
 /**
- * `agents perf` — latency rollups over the disposable perf SQLite warehouse.
+ * `agents insights perf` — latency rollups over the disposable perf SQLite
+ * warehouse (former top-level `agents perf`, moved under insights in PHNX-3391).
  *
  * Subcommands:
- *   agents perf              multi-section summary (commands + hooks + runs)
- *   agents perf hooks        per-hook p50/p99 + cache hit rates
- *   agents perf commands     slowest CLI command paths (from command.end)
- *   agents perf run          agent.run / perf.timing labels
- *   agents perf friction     sessions stuck repeatedly hitting the same guard
+ *   agents insights perf              multi-section summary (commands + hooks + runs)
+ *   agents insights perf hooks        per-hook p50/p99 + cache hit rates
+ *   agents insights perf commands     slowest CLI command paths (from command.end)
+ *   agents insights perf run          agent.run / perf.timing labels
+ *   agents insights perf friction     sessions stuck repeatedly hitting the same guard
  *
  * Soft-joins sessions.db via shared string keys (session_id, agent, machine) —
  * no foreign keys. Warehouse lives at ~/.agents/.cache/perf/perf.db (safe to wipe).
@@ -49,5 +50,13 @@ export declare function loadHookProfile(days: number, project?: string): HookPro
  * exit 2 — see lib/friction-heuristics.ts for the grouping.
  */
 export declare function frictionAction(opts: PerfGlobalOpts): void;
-export declare function registerPerfCommand(program: Command): void;
+/**
+ * Attach the `perf` latency-rollup command under a parent (the top-level
+ * `insights` group). Performance is an insight, not a top-level noun — `agents
+ * perf` was retired in favour of `agents insights perf` (PHNX-3391). It is a
+ * sibling of `agents insights cost` / `output`, registered in
+ * `registerInsightsCommand` beside them (top-level insights only, not
+ * `sessions insights`).
+ */
+export declare function registerPerfSubcommand(parent: Command): void;
 export {};

package/dist/commands/perf.js

@@ -1,12 +1,13 @@
 /**
- * `agents perf` — latency rollups over the disposable perf SQLite warehouse.
+ * `agents insights perf` — latency rollups over the disposable perf SQLite
+ * warehouse (former top-level `agents perf`, moved under insights in PHNX-3391).
  *
  * Subcommands:
- *   agents perf              multi-section summary (commands + hooks + runs)
- *   agents perf hooks        per-hook p50/p99 + cache hit rates
- *   agents perf commands     slowest CLI command paths (from command.end)
- *   agents perf run          agent.run / perf.timing labels
- *   agents perf friction     sessions stuck repeatedly hitting the same guard
+ *   agents insights perf              multi-section summary (commands + hooks + runs)
+ *   agents insights perf hooks        per-hook p50/p99 + cache hit rates
+ *   agents insights perf commands     slowest CLI command paths (from command.end)
+ *   agents insights perf run          agent.run / perf.timing labels
+ *   agents insights perf friction     sessions stuck repeatedly hitting the same guard
  *
  * Soft-joins sessions.db via shared string keys (session_id, agent, machine) —
  * no foreign keys. Warehouse lives at ~/.agents/.cache/perf/perf.db (safe to wipe).
@@ -190,7 +191,7 @@ export function frictionAction(opts) {
     // --cwd flag — so silently accepting the flag here would look like it
     // filtered when it did nothing. Fail loud instead of no-op.
     if (opts.project) {
-        console.error(chalk.red("agents perf friction does not support --project yet — friction events carry no cwd to filter on."));
+        console.error(chalk.red("agents insights perf friction does not support --project yet — friction events carry no cwd to filter on."));
         process.exitCode = 1;
         return;
     }
@@ -224,7 +225,7 @@ function summaryAction(opts) {
         }, null, 2));
         return;
     }
-    console.log(chalk.bold(`agents perf — last ${days} day${days === 1 ? '' : 's'}${project ? ` — project ${project}` : ''}`));
+    console.log(chalk.bold(`agents insights perf — last ${days} day${days === 1 ? '' : 's'}${project ? ` — project ${project}` : ''}`));
     console.log(chalk.gray(`warehouse: ${perfDbPath()}  (disposable; soft-join sessions via session_id/agent/machine)`));
     console.log('');
     console.log(chalk.bold('Commands (slowest by p99)'));
@@ -246,7 +247,7 @@ function attachSharedOptions(cmd) {
 }
 /**
  * Commander binds a flag declared on both parent and child to the *parent*.
- * Merge so `agents perf commands --json` still sees json:true on the leaf.
+ * Merge so `agents insights perf commands --json` still sees json:true on the leaf.
  */
 function leafOpts(cmd) {
     const parent = cmd.parent && typeof cmd.parent.opts === 'function'
@@ -254,8 +255,16 @@ function leafOpts(cmd) {
         : {};
     return { ...parent, ...cmd.opts() };
 }
-export function registerPerfCommand(program) {
-    const perf = program
+/**
+ * Attach the `perf` latency-rollup command under a parent (the top-level
+ * `insights` group). Performance is an insight, not a top-level noun — `agents
+ * perf` was retired in favour of `agents insights perf` (PHNX-3391). It is a
+ * sibling of `agents insights cost` / `output`, registered in
+ * `registerInsightsCommand` beside them (top-level insights only, not
+ * `sessions insights`).
+ */
+export function registerPerfSubcommand(parent) {
+    const perf = parent
         .command('perf')
         .description('Latency rollups from the disposable perf warehouse (hooks, commands, runs)')
         .addHelpText('after', `
@@ -264,16 +273,16 @@ Identity columns reuse sessions/events string shapes (session_id, agent, machine
 for soft cross-reference; there are no foreign keys.
 
 Examples:
-  agents perf                        # summary: commands + hooks + runs
-  agents perf hooks                  # per-hook p50/p95/p99 + cache hit rate
-  agents perf commands --days 30     # slowest CLI entrypoints
-  agents perf run --json             # agent.run timings as JSON
-  agents perf hooks --warn-ms 500
-  agents perf hooks --project agents-cli  # scope to one repo's samples
-  agents perf friction               # sessions stuck retrying the same guard block
+  agents insights perf                        # summary: commands + hooks + runs
+  agents insights perf hooks                  # per-hook p50/p95/p99 + cache hit rate
+  agents insights perf commands --days 30     # slowest CLI entrypoints
+  agents insights perf run --json             # agent.run timings as JSON
+  agents insights perf hooks --warn-ms 500
+  agents insights perf hooks --project agents-cli  # scope to one repo's samples
+  agents insights perf friction               # sessions stuck retrying the same guard block
 `);
-    // Options live on the parent so `agents perf --json` and
-    // `agents perf commands --json` both work (see leafOpts).
+    // Options live on the parent so `agents insights perf --json` and
+    // `agents insights perf commands --json` both work (see leafOpts).
     attachSharedOptions(perf).action(function summary() {
         summaryAction(this.opts());
     });

package/dist/commands/prune.js

@@ -66,9 +66,11 @@ function collectOrphans(types, all) {
     }
     if (types.includes('hooks')) {
         for (const { agent, version } of scopePairs(iterHooksCapableVersions(), all)) {
-            // Orphan hooks = scripts present in the version home that no
-            // agents.yaml/hooks.yaml entry registers, so they never fire. Same
-            // definition the doctor overview reports.
+            // Orphan hooks = scripts present in the version home but absent from
+            // every configured source (user + system + extras) — genuinely dead
+            // files, not merely unregistered ones (sync copies helper/test scripts
+            // that no manifest entry declares). Same definition the doctor overview
+            // reports (PHNX-2693).
             const orphans = listUnmanagedHooksInVersionHome(agent, version);
             if (orphans.length > 0) {
                 groups.push({ type: 'hooks', agent, version, orphans });

package/dist/commands/routines.d.ts

@@ -46,5 +46,13 @@ export declare function groupRoutineJobsByDevice(jobs: JobConfig[], registry: De
  */
 export declare function groupRoutineJobsByProject(jobs: JobConfig[], knownProjectNames: Set<string>): RoutineListGroup[];
 export declare function buildRunsJson(runs: RunMeta[]): Record<string, unknown>[];
+/**
+ * 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 declare function runFailureReason(run: RunMeta): string | null;
 /** Register the `agents routines` command tree. */
 export declare function registerRoutinesCommands(program: Command): void;

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

@@ -538,7 +538,7 @@ Examples:
             }
             const version = resolveVersionAlias(agentId, rawVersion);
             if (!version) {
-                console.log(chalk.red(`Pass a version: ${agentId}@<version>. Try 'default' or 'agents list ${agentId}'.`));
+                console.log(chalk.red(`Pass a version: ${agentId}@<version>. Try 'default' or 'agents view ${agentId}'.`));
                 process.exit(1);
             }
             const installed = listInstalledVersions(agentId);

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(/\/+$/, '');