@phnx-labs/agents-cli 1.22.57 → 1.22.59

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/routines.test-fixture.js

@@ -149,6 +149,11 @@ export function createDaemonHarness(fileSlug) {
                 // and kills real tmux-wrapped processes every five-minute tick (RUSH-2545).
                 AGENTS_HISTORY_DIR: path.join(home, '.agents', '.history'),
                 AGENTS_SKIP_MIGRATION: '1',
+                // PHNX-2545 test-home tripwire: name the isolated home this daemon must
+                // resolve its state dir under. If the HOME override above ever failed to
+                // reach the child, runDaemon()'s assertTestDaemonHome() refuses to boot
+                // instead of ticking its scheduler against the operator's real host.
+                AGENTS_DAEMON_TEST_HOME: home,
             },
             detached: true,
             stdio: 'ignore',

package/dist/commands/send.d.ts

@@ -11,7 +11,8 @@
  * Compat: positional text still works (`agents send "hi" --channel … --to …`).
  *
  * `agents notify` is the same delivery path with owner defaults
- * (`send --to owner`). Not a second stack. Not agent control — use
+ * (`send --to owner`) and is deprecated — new callers should use
+ * `agents feed post`. Not a second stack. Not agent control — use
  * `agents message` / `agents sessions inject` for running agents.
  *
  * Feed / activity are a different plane (record + read); feed.broadcast may

package/dist/commands/send.js

@@ -47,7 +47,7 @@ async function runSend(positionalText, opts, ownerMode) {
 }
 const SHARED_NOTES = `
   Planes (do not mix them up):
-    send / notify     - DELIVER a message to a recipient (this command)
+    send              - DELIVER a message to a recipient (this command)
     feed post         - RECORD progress / milestones (optional broadcast may call send)
     activity          - READ the activity stream (not a send path)
     message / inject  - CONTROL a running agent (mailbox answer or terminal keystroke)
@@ -97,7 +97,7 @@ export function registerSendCommand(program) {
     });
     const notifyCmd = program
         .command('notify [text]')
-        .description('Deliver to the owner (alias of send --to owner). Channel + target default from notify.owner in agents.yaml.')
+        .description('[DEPRECATED] Deliver to the owner (alias of send --to owner). Use "agents feed post" for new code.')
         .option('--text <text>', 'message body (preferred over positional text)')
         .option('--channel <name>', 'override owner channel')
         .option('--to <target>', 'override owner target (or pass a non-owner dest with --channel)')
@@ -110,7 +110,7 @@ export function registerSendCommand(program) {
         .option('--dry-run', 'resolve + build but do not send');
     setHelpSections(notifyCmd, {
         examples: `
-      # Same as: agents send --to owner --text "…"
+      # Deprecated: prefer "agents feed post --title \"…\" \"…\" --level important"
       agents notify --text "Build finished — PR #1346 is green"
       agents notify "legacy positional still works"
 
@@ -120,13 +120,15 @@ export function registerSendCommand(program) {
       agents notify --text "probe" --dry-run --json
     `,
         notes: `
-      notify ≡ send --to owner. One delivery stack (lib/channels). Set
-      notify.owner.{channel,to} in agents.yaml once per machine/fleet.
+      DEPRECATED. notify ≡ send --to owner and still works, but new callers
+      should use "agents feed post" (record + optional broadcast) instead.
+      Set notify.owner.{channel,to} in agents.yaml once per machine/fleet.
 
       ${SHARED_NOTES}
     `,
     });
     notifyCmd.action(async (text, opts) => {
+        console.error(chalk.yellow('Warning: "agents notify" is deprecated. Use "agents feed post" for progress posts that can also reach the owner.'));
         await runSend(text, opts, true);
     });
 }

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-stats.js

@@ -6,6 +6,19 @@ import { discoverPlugins } from '../lib/plugins/plugins.js';
 import { setHelpSections } from '../lib/help.js';
 import { terminalWidth, truncateToWidth, padToWidth, stringWidth } from '../lib/session/width.js';
 const DEFAULT_TOP = 20;
+/**
+ * The recorded-set the zero-counts must be read against (PHNX-2301). A resource
+ * only records an EXPLICIT invocation from a harness that emits the event:
+ * `Skill` tool calls come from Claude + Kimi, slash-commands from Claude only
+ * (`SKILL_TOOL_NAME_BY_AGENT` in `lib/session/highlights.ts`, slash-command
+ * parsing in `lib/session/parse.ts`). A session under any other harness — or an
+ * auto-triggered skill, which emits no event on any harness — contributes
+ * nothing, so its resources read as 0 whether or not they were used. Keep these
+ * in lockstep with the writer: widening them here without a verified transcript
+ * tool-name would make the caveat lie about coverage it does not have.
+ */
+const RECORDING_SKILL_HARNESSES = ['claude', 'kimi'];
+const RECORDING_COMMAND_HARNESSES = ['claude'];
 /**
  * The both-ends "dead weight" set: installed resources whose identity
  * (kind + name — name already embeds `plugin:short`, so it matches the stored
@@ -128,7 +141,7 @@ async function statsAction(cmd) {
     const totalInvocations = allInvoked.reduce((s, r) => s + r.invocations, 0);
     if (opts.json) {
         process.stdout.write(JSON.stringify({
-            schemaVersion: 1,
+            schemaVersion: 2,
             kind: 'sessions-stats',
             generatedAt: new Date().toISOString(),
             filters: {
@@ -142,9 +155,21 @@ async function statsAction(cmd) {
             signal: {
                 explicitOnly: true,
                 note: 'Explicit invocations only (slash commands + Skill tool calls). Auto-triggered skills emit no event and read as 0. Skill invocations are recorded for Claude and Kimi; slash-commands for Claude only.',
+                // Structured recorded-set so a machine consumer can tell a zero from a
+                // non-recording harness apart from a genuine non-use (PHNX-2301): a
+                // zeroInvoked resource may simply have been auto-triggered, or only
+                // used under a harness not in these sets.
+                recording: {
+                    skills: RECORDING_SKILL_HARNESSES,
+                    commands: RECORDING_COMMAND_HARNESSES,
+                },
             },
             coverage: {
+                // sessionsWithUsage/sessionsIndexed kept for the SES-IF-4b envelope
+                // contract; sessionsScanned is the honest backfill-coverage numerator
+                // (ledger rows), distinct from the absolute sessionsWithUsage count.
                 sessionsWithUsage: coverage.covered,
+                sessionsScanned: coverage.scanned,
                 sessionsIndexed: coverage.total,
             },
             totals: {
@@ -210,8 +235,12 @@ function renderHuman(args) {
     out.push(chalk.bold('Resource usage') +
         chalk.gray(`  ·  ${allInvokedCount} invoked · ${totalInvocations} invocation${totalInvocations !== 1 ? 's' : ''}` +
             (scopeBits.length ? `  ·  ${scopeBits.join(' · ')}` : '')));
-    out.push(chalk.gray(`  coverage: ${coverage.covered}/${coverage.total} sessions carry the signal`) +
-        (coverage.total > 0 && coverage.covered / coverage.total < 0.5
+    // Scan coverage (ledger) is the honest "has the backfill folded in history?"
+    // signal and drives the hint; sessionsWithUsage is an ABSOLUTE count of sessions
+    // carrying ≥1 explicit invocation, which stays small at full scan coverage
+    // because most sessions invoke nothing (PHNX-2301).
+    out.push(chalk.gray(`  coverage: ${coverage.scanned}/${coverage.total} sessions scanned · ${coverage.covered} carry an explicit invocation`) +
+        (coverage.total > 0 && coverage.scanned / coverage.total < 0.5
             ? chalk.yellow('  — run `agents sessions backfill resources` to fold in history')
             : ''));
     out.push(chalk.gray('  signal: explicit invocations only (slash commands + Skill tool); auto-triggered skills read as 0; skills from Claude+Kimi, slash-commands Claude-only'));
@@ -228,8 +257,11 @@ function renderHuman(args) {
         }
         out.push('');
     }
-    // Zero-invoked section (the dead weight).
-    out.push(chalk.bold('Installed but never invoked') + chalk.gray(`  (${zeroInvoked.length})`));
+    // Zero-invoked section (the dead weight). "Never invoked" is scoped to the
+    // recorded set: never EXPLICITLY invoked under a recording harness (skills
+    // Claude+Kimi, commands Claude-only) — it may still have been auto-triggered or
+    // used under another harness, which is why this is dead-weight EVIDENCE, not proof.
+    out.push(chalk.bold('Installed but never explicitly invoked') + chalk.gray(`  (${zeroInvoked.length})`));
     if (zeroInvoked.length === 0) {
         out.push(chalk.gray('  (every installed resource has at least one explicit invocation in this window)'));
     }

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,
             },
@@ -2315,9 +2316,16 @@ limitSource) {
         return;
     }
     // --device / --devices values are merged into options.host for internal routing. A bare `all` / `fleet` sentinel means
-    // "search every peer" — which is already the default — so it resolves to no
-    // explicit host set rather than erroring on a device literally named "all".
-    const deviceTargets = [...(options.device ?? []), ...(options.devices ?? [])]
+    // "search every peer" — which is already the default for `--active` and the
+    // interactive listing — so it resolves to no explicit host set rather than
+    // erroring on a device literally named "all".
+    const rawDeviceTargets = [...(options.device ?? []), ...(options.devices ?? [])];
+    // But the HISTORICAL `--json` listing does NOT fan out by default (it stays a
+    // deterministic local slice for scripts), so the sentinel would otherwise be
+    // silently dropped and the fleet never reached (PHNX-2673). Remember it so that
+    // path can sweep every peer, exactly as the interactive listing already does.
+    const fleetWide = rawDeviceTargets.some(t => t.toLowerCase() === 'all' || t.toLowerCase() === 'fleet');
+    const deviceTargets = rawDeviceTargets
         .filter(t => t.toLowerCase() !== 'all' && t.toLowerCase() !== 'fleet');
     if (deviceTargets.length > 0) {
         options.host = [...(options.host ?? []), ...deviceTargets];
@@ -2774,16 +2782,43 @@ limitSource) {
             // each peer) would fall to FTS content search and return every transcript
             // that merely MENTIONS the id, defeating exact remote resolution. A genuine
             // search phrase keeps the ranked metadata+content path.
-            const filtered = searchQuery
+            let filtered = searchQuery
                 ? resolveSessionQuery(sessions, searchQuery, {
                     scope: { agent: options.agent, project: options.project, routine: options.routine },
                 }).matches
                 : sessions;
+            // `--device all`/`--fleet` on a historical `--json` query fans out to every
+            // peer and merges their rows in — the SAME SSH sweep the interactive listing
+            // below uses, and the whole-fleet twin of the explicit `--device <host>
+            // --json` path (`runRemoteSessionsJson`). Without this the documented
+            // "search the whole fleet" flag returned local rows only (PHNX-2673). Guarded
+            // to the sentinel so a bare `--json` stays a deterministic local slice for
+            // scripts, and skipped under `--local`/the peer recursion guard. Dead peers
+            // are skipped by the fan-out, never fatal — enrichment, not a dependency.
+            const forceLocalJson = options.local === true || process.env[NO_FANOUT_ENV] === '1';
+            if (fleetWide && !forceLocalJson) {
+                const forwarded = ensureWholeIndex(buildForwardedArgs(process.argv, new Set(options.host ?? [])));
+                if (!forwarded.includes('--json'))
+                    forwarded.push('--json');
+                const fanSpinner = isInteractiveTerminal() ? ora('Reaching other machines...').start() : null;
+                try {
+                    const { sessions: remoteSessions } = await gatherRemoteList(forwarded, undefined);
+                    if (remoteSessions.length > 0) {
+                        filtered = mergeLocalFirst([...filtered, ...remoteSessions], machineId());
+                    }
+                }
+                catch {
+                    // fan-out is an enrichment, never a hard dependency
+                }
+                finally {
+                    fanSpinner?.stop();
+                }
+            }
             // JSON is the canonical picker contract: enrich the durable rows once
             // from the shared live cache so every consumer gets lifecycle/recovery
             // metadata without performing its own join or transcript scan.
             const live = await gatherActiveSessions({
-                local: options.local === true || process.env[NO_FANOUT_ENV] === '1',
+                local: forceLocalJson,
                 hosts: options.host,
             });
             process.stdout.write(serializeSessionsJson(serializeSessionPickerRows(filtered, live.sessions)));

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

@@ -130,7 +130,11 @@ function pctCell(v, width) {
  * header — which defeats the scannability this column exists for. */
 const SPEC_WIDTH_MIN = 12;
 /** The static hardware as one compact cell — `12c 64G 1T`: cores, total RAM,
- * total root disk via fmtBytes. `—` only when no probe has ever seen the box.
+ * total root disk via fmtBytes. `—` covers two cases: no probe has ever seen
+ * the box, or the probe answered but yielded no usable core count (`parseNcpu`
+ * finding none, or the Windows `ncpu` group failing the finite-and-positive
+ * check) — the cell is keyed on `ncpu` because a spec string without it would
+ * read as a machine with zero cores.
  *
  * Deliberately NOT gated on `reachable`: hardware does not change while a
  * machine is down, so an offline device keeps rendering the spec from its last
@@ -2298,6 +2302,13 @@ box; \`agents doctor\` names it.
 
 A box whose probe cannot answer (no POSIX shell, e.g. Windows) is reported
 \`unverified\` rather than counted as a success.
+
+The upgrade OWNS its global bin links: after installing, it verifies that
+\`<prefix>/bin/{agents,ag,browser,computer}\` resolve to the freshly-installed
+copy and RESTORES any the package manager dropped — the state that once left a
+box upgraded in place but with every \`agents\` invocation "command not found"
+(PHNX-2768). A link it cannot make resolve fails the upgrade loud, so that box
+is reported \`failed\` (exit non-zero), never a stranded \`ok\`.
 `)
         .action(async (version) => {
         let cmd;

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)'));