@phnx-labs/agents-cli 1.22.53 → 1.22.55

package/dist/commands/auth-mint.js

@@ -0,0 +1,96 @@
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { readStdinSync, runOrDie } from '../lib/format.js';
+import { isInteractiveTerminal } from './utils.js';
+import { getMintFlow, listMintableHarnesses, mintAndSeed, } from '../lib/auth-mint.js';
+function collect(value, previous) {
+    return [...previous, value];
+}
+function printResult(result, json) {
+    if (json) {
+        console.log(JSON.stringify({
+            harness: result.harness,
+            account: result.account,
+            email: result.email,
+            authBundleKey: result.authBundleKey,
+            rotated: result.rotated,
+            fleet: result.fleet,
+        }, null, 2));
+        return;
+    }
+    const verb = result.rotated ? 'Rotated' : 'Minted';
+    console.log(chalk.green(`${verb} ${result.harness} setup-token for ${result.email} into account '${result.account}' and reserved auth bundle key ${result.authBundleKey}.`));
+    console.log(chalk.gray('The token is never printed. Native OAuth was not copied.'));
+    console.log(chalk.gray(`Run: agents run ${result.harness} --account ${result.account}`));
+    if (result.fleet.length) {
+        for (const row of result.fleet) {
+            console.log(chalk.green(`  synced ${row.device} (${row.message})`));
+        }
+    }
+}
+export function registerMintCommand(parent, testHooks) {
+    const mint = parent
+        .command('mint <harness>')
+        .description('Mint a long-lived setup-token and seed it as a named account')
+        .option('--account <name-or-email>', 'Named account to create/rotate, or the account email')
+        .option('--email <email>', 'Email that keys the reserved auth bundle when --account is a name')
+        .option('--token-stdin', 'Seed an already-minted token from stdin (skip the PTY drive)')
+        .option('--code <code>', 'Authorization code to paste into the setup-token prompt')
+        .option('--no-open', 'Print the authorize URL instead of opening a browser')
+        .option('--fleet', 'Sync the minted account and reserved auth bundle to every other registered device')
+        .option('--device <name>', 'Sync to this device (repeatable)', collect, [])
+        .option('--json', 'Machine-readable result (never includes the token)')
+        .action((harness, o, command) => {
+        const json = !!o.json || !!command.optsWithGlobals().json;
+        return runOrDie(async () => {
+            getMintFlow(harness);
+            let token;
+            if (o.tokenStdin) {
+                token = readStdinSync();
+                if (!token)
+                    throw new Error('No value received on stdin. Pass the setup-token on stdin with --token-stdin.');
+            }
+            else if (!isInteractiveTerminal() && !o.code) {
+                throw new Error(`Minting ${harness} interactively needs a TTY (or --token-stdin / --code). Supported harnesses: ${listMintableHarnesses().join(', ')}.`);
+            }
+            const result = await mintAndSeed({
+                harness,
+                account: o.account,
+                email: o.email,
+                token,
+                code: o.code,
+                open: o.open,
+                fleet: o.fleet,
+                devices: o.device,
+                json,
+                hooks: {
+                    ...testHooks,
+                    ...(o.tokenStdin || o.code || !isInteractiveTerminal()
+                        ? {}
+                        : {
+                            readCode: async () => {
+                                const { input } = await import('@inquirer/prompts');
+                                return input({ message: 'Paste the authorization code from the browser' });
+                            },
+                        }),
+                },
+            });
+            printResult(result, json);
+        }, { json });
+    });
+    setHelpSections(mint, {
+        examples: `agents accounts mint claude
+agents accounts mint claude --account ada@example.com
+agents accounts mint claude --account work --email ada@example.com
+agents accounts mint claude --token-stdin < token.txt
+agents accounts mint claude --code AUTHCODE --json
+agents accounts mint claude --fleet
+agents auth mint claude --account ada@example.com --json`,
+        notes: `Claude is the only harness with an interactive long-lived setup-token (\`claude setup-token\`, ~1 year, shareable across machines). The command drives that flow in a PTY, opens the authorize URL, captures a well-formed sk-ant-oat01- token (refusing the #1767 TTY-banner capture), and seeds:
+  1. a named provider account (policy never) for \`agents run --account\` / \`agents accounts sync\`
+  2. the reserved FILE-BASED auth bundle keyed per email, which usage/probe reads
+Native rotating OAuth is never copied. Other harnesses fail loud: device-code login is \`agents fleet login\`; API keys are \`agents accounts add\`.
+Already have a token? \`--token-stdin\` skips the browser dance. \`agents auth mint\` is the same command as \`agents accounts mint\`.`,
+    });
+    return mint;
+}

package/dist/commands/auth.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { PhoenixApiError, clearSession, createSpace, createSpaceInvite, fetchWhoAmI, listSpaceMembers, listSpaces, pollDeviceToken, readSession, removeSpaceMember, resolveMemberFromList, resolveSpaceFromList, slugify, startDeviceAuthorization, updateSpaceMemberRole, writeSession, } from '../lib/identity/index.js';
 import { setHelpSections } from '../lib/help.js';
 import { runOrDie } from '../lib/format.js';
+import { registerMintCommand } from './auth-mint.js';
 /**
  * `agents auth` — sign in to Phoenix ID, the account layer behind team spaces.
  * Signing in is optional: every local feature works with no account. Everything
@@ -95,13 +96,15 @@ export function registerAuthCommand(program) {
     setHelpSections(auth, {
         examples: `agents auth login                         # device-code sign-in via your browser
 agents auth whoami                        # who this machine is signed in as
+agents auth mint claude                   # mint a Claude setup-token into a named account
 agents auth space create "Design Team"    # start a space
 agents auth space invite ada@example.com  # add a teammate
 agents auth logout                        # clear this machine only`,
         notes: `Signing in is optional — every local feature works with no account; team spaces are what it unlocks.
 Sign-in is Google-only and opens a Phoenix-branded page; the CLI never sees a password.
 The session lives in this machine's agents state dir, so logging out here signs out nothing else.
-Point at a different backend with PHOENIX_ID_BASE (defaults to the production service).`,
+Point at a different backend with PHOENIX_ID_BASE (defaults to the production service).
+\`agents auth mint\` is the harness setup-token mint (same command as \`agents accounts mint\`); it does not sign you into Phoenix ID.`,
     });
     auth
         .command('login')
@@ -115,6 +118,7 @@ Point at a different backend with PHOENIX_ID_BASE (defaults to the production se
         const json = !!o.json || !!command.optsWithGlobals().json;
         return runOrDie(() => whoami(json), { json });
     });
+    registerMintCommand(auth);
     auth
         .command('logout')
         .description("Clear this machine's session (no other device is affected)")

package/dist/commands/browser.js

@@ -1308,7 +1308,7 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('remote-control [state]')
-        .description("Allow or deny other fleet machines driving THIS machine's browser over `browser --device`. " +
+        .description("Allow or deny other fleet machines driving THIS machine's browser over `browser --device` or `agents ssh …` (`agents browser` / `ag browser` / standalone `browser`). " +
         '`on`/`off` to set (device-local, never synced); no argument prints the current value. Default off.')
         .option('--json', 'Output as JSON')
         .action((state, opts) => {

package/dist/commands/cost.js

@@ -21,8 +21,14 @@ Examples:
 
 Cost is computed offline from a versioned per-model price table (${PRICING_VERSION}).
 `)
-        .action(async (options) => {
-        await costAction(options);
+        // Read opts via optsWithGlobals(): `--json`/`--since`/`--by` collide by name
+        // with the `insights` parent's own options, so commander binds them to the
+        // parent at parse time and the leaf's plain opts() never sees them. Merging
+        // ancestor opts is what the sibling `insights mix` recipes already do
+        // (mix-commands.ts) — without it every flag on this command is silently
+        // dropped (e.g. `agents insights cost --json` printed the human table).
+        .action(async (_options, command) => {
+        await costAction(command.optsWithGlobals());
     });
 }
 /** Map the --by flag to a rollup group, rejecting unknown values. */

package/dist/commands/daemon.js

@@ -886,7 +886,7 @@ export function registerDaemonCommand(program) {
       always. Use 'agents routines stats' for per-routine failure detail.
 
       'disable' is a persisted kill switch: it stops routines/add,
-      routines/start, routines/catchup, and webhook triggers from auto-starting
+      routines/start, routines/catchup, monitors/add, and webhook triggers from auto-starting
       the daemon (daemon.enabled: false in ~/.agents/devices/<host>/agents.yaml).
       'agents daemon start' still starts it explicitly, same as
       'systemctl start' on a disabled unit.
@@ -974,7 +974,7 @@ export function registerDaemonCommand(program) {
         .description('Clear the daemon.enabled kill switch. Does not start the daemon by itself.')
         .action(() => {
         setConfigValue('daemon.enabled', true);
-        console.log(chalk.green('daemon.enabled: true') + chalk.gray(' — auto-start surfaces (routines add/start/catchup, webhooks) may bring the daemon up again'));
+        console.log(chalk.green('daemon.enabled: true') + chalk.gray(' — auto-start surfaces (routines add/start/catchup, monitors add, webhooks) may bring the daemon up again'));
     });
     cmd.command('disable')
         .description('Persist daemon.enabled: false — nothing auto-starts the daemon until re-enabled. Does not stop a running daemon.')

package/dist/commands/doctor.js

@@ -24,6 +24,7 @@ import { resolveAgentTargets, AgentSpecError } from '../lib/agent-spec/index.js'
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
 import { checkVersionHookWiring, inspectDuplicateVersionHooks, registerHooksToSettings, repairManagedHookRuntimeArtifacts } from '../lib/hooks/install.js';
+import { inspectReservedAuthBundle } from '../lib/secrets/bundles.js';
 import { isVersionIsolated } from '../lib/installations/versions.js';
 import { computeDrift, checkSyncStatus, countOrphans, computeSourceBehind } from '../lib/drift.js';
 import { readAuthHealthCache, summarizeHostAuth } from '../lib/auth-health.js';
@@ -118,13 +119,15 @@ function printWrappedLine(prefix, text) {
  * file and line. Run `agents doctor` on that box for the specifics — the
  * message says so.
  */
-const REMOTE_FORWARDED_KINDS = ['rc-secret-export', 'env-secret-export', 'ssh-key-enrollment'];
+const REMOTE_FORWARDED_KINDS = ['rc-secret-export', 'env-secret-export', 'auth-bundle-wrong-backend', 'ssh-key-enrollment'];
 /** Canonical, locally-authored text for a forwarded kind. Never the remote's. */
 const REMOTE_SECRET_MESSAGE = {
     'rc-secret-export': 'a credential-shaped export was found in this box\'s shell rc files'
         + ' — run `agents doctor` there for the file and line',
     'env-secret-export': 'AGENTS_SECRETS_PASSPHRASE is set in this box\'s process environment'
         + ' — run `agents doctor` there for detail',
+    'auth-bundle-wrong-backend': "reserved secrets bundle 'auth' exists but is not file-backed"
+        + ' — run `agents doctor` there to recreate it',
     'ssh-key-enrollment': 'Windows OpenSSH key enrollment is invalid'
         + ' — run `agents doctor` on this box for the effective path or ACL failure',
 };
@@ -442,6 +445,7 @@ async function runDevicesDoctor(opts) {
                 hostClis: toHostCliInput(listCliStatus(cwd)),
                 rcSecrets: scanUserRcFiles(),
                 masterPassphraseInEnv: masterPassphraseInEnv(),
+                authBundleWrongBackend: !inspectReservedAuthBundle().ok,
                 execPolicy: process.platform === 'win32'
                     ? { platform: process.platform, policy: getEffectiveExecutionPolicy() }
                     : undefined,
@@ -1680,6 +1684,7 @@ export function registerDoctorCommand(program) {
                 hostClis: toHostCliInput(hostClis),
                 rcSecrets: scanUserRcFiles(),
                 masterPassphraseInEnv: masterPassphraseInEnv(),
+                authBundleWrongBackend: !inspectReservedAuthBundle().ok,
                 // getEffectiveExecutionPolicy spawns powershell — a doomed process on
                 // POSIX, where the advisory never applies. Probe only on Windows.
                 execPolicy: process.platform === 'win32'

package/dist/commands/exec.js

@@ -654,13 +654,13 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         Interactive plan (omit the prompt) works everywhere it is listed.
 
       Run strategy (set via --strategy or run.<agent>.strategy in agents.yaml):
-        pinned     use the workspace/global pinned version
+        pinned     use the workspace/global pinned version; if that version is logged out on this device, pick a signed-in sibling instead of dying (an explicit @version pin is unchanged)
         available  use pinned if it can run right now; otherwise switch to another signed-in version
         balanced   distribute load across healthy accounts by remaining capacity (default)
         A version/account is skipped when it is rate-limited right now — any usage window (incl. the 5-hour session window) at 100%, matching the 'agents view' badge.
         --balanced is shorthand for --strategy balanced. Ignored when @version is pinned, when a profile is used, or with --fallback.
-        Zero healthy accounts under balanced/available exits nonzero naming each
-        excluded account and the earliest window reset — use --strategy pinned to force.
+        Zero healthy accounts under balanced/available (or a logged-out pinned default with no signed-in sibling) exits nonzero naming each
+        excluded account and the earliest window reset — use --strategy pinned to force a rate-limited default; a logged-out default is never forced.
 
       'auto' harness (agents run auto): picks the host (14d usage affinity,
       unless --device is given), the harness (installed CLIs weighted by
@@ -2368,13 +2368,15 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             process.exit(1);
         }
         const strategy = options.balanced ? 'balanced' : explicitStrategy ?? configuredStrategy;
-        // Strategy only applies to bare agent invocations. Explicit @version and
-        // profiles already define their execution target. A --fallback chain does
-        // NOT pin the primary: it only names where to cascade on a rate limit, so
-        // the bare primary still resolves through the strategy — otherwise every
+        // Strategy applies to bare (unpinned) invocations. Explicit @version and
+        // profiles already name the target. A --fallback chain does NOT pin the
+        // primary: it only names where to cascade on a rate limit, so the bare
+        // primary still resolves through the strategy — otherwise every
         // `agents run claude --fallback codex` run lands on the pinned default
         // account and account rotation silently stops (the gh-monitor heal bug).
-        if (!accountPickerRequested && !configuredAccount && (strategy !== 'pinned' || options.balanced || explicitStrategy)) {
+        // `pinned` still resolves so a logged-out default can yield to a signed-in
+        // sibling on this device (PHNX-2685); an explicit @version pin is unchanged.
+        if (!accountPickerRequested && !configuredAccount && (!version || strategy !== 'pinned' || options.balanced || explicitStrategy)) {
             if (version) {
                 process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: version ${version} is pinned\n`));
             }

package/dist/commands/focus.d.ts

@@ -110,6 +110,7 @@ export declare function dedupeSessionsByLogicalId(rows: SessionMeta[], self?: st
  * peer-owned session without `--device`, matching `resume`/`preview`.
  */
 export declare function focusTargetForResolved(poolMatch: SessionMeta | undefined, resolved: SessionMeta): SessionMeta;
+export declare function focusResolvedSession(meta: SessionMeta, liveById: Map<string, ActiveSession>, self: string, fallback: UnreachableFallback, attachOnly: boolean, reconnectReattach?: boolean): Promise<void>;
 /** Focus one row selected by the shared session browser through the same
  * attach/recover decision as `agents sessions focus <id>`. */
 export declare function focusSelectedSession(meta: SessionMeta, active: ActiveSession | undefined, self: string): Promise<void>;

package/dist/commands/focus.js

@@ -494,10 +494,10 @@ async function pickFocusCandidates(sessions, liveById, initialSearch) {
 export function focusTargetForResolved(poolMatch, resolved) {
     return poolMatch ?? resolved;
 }
-async function focusResolvedSession(meta, liveById, self, fallback, attachOnly, reconnectReattach = false) {
+export async function focusResolvedSession(meta, liveById, self, fallback, attachOnly, reconnectReattach = false) {
     const active = liveById.get(meta.id);
     if (active && isAttachableLiveSession(active)) {
-        await jumpTo(active, self, fallback);
+        await jumpTo(active, self, fallback, meta.id);
         return;
     }
     if (attachOnly) {

package/dist/commands/go.d.ts

@@ -104,9 +104,10 @@ export declare function describeWhere(s: ActiveSession, self: string): Where;
 /**
  * What to do when a session can't be *attached* (no tmux/Ghostty rail). `go`
  * refuses; `focus` opens a new tab and resumes. `remote` is the peer name when
- * the session lives on another machine, else undefined.
+ * the session lives on another machine, else undefined. `fallbackId` is the
+ * indexed session id when the live row has not registered one yet (PHNX-3356).
  */
-export type UnreachableFallback = (s: ActiveSession, remote: string | undefined) => void | Promise<void>;
+export type UnreachableFallback = (s: ActiveSession, remote: string | undefined, fallbackId?: string) => void | Promise<void>;
 export type AttachRailLiveness = {
     state: 'alive';
 } | {
@@ -121,5 +122,5 @@ export type AttachRailLiveness = {
 export declare function probeAttachRail(s: ActiveSession, self: string): Promise<AttachRailLiveness>;
 /** Strict attach-only fallback: no pane means no attach. Never open a shell or
  * start recovery, because both would violate the caller's no-fork intent. */
-export declare function refuseFallback(s: ActiveSession, remote: string | undefined): Promise<void>;
-export declare function jumpTo(s: ActiveSession, self: string, fallback?: UnreachableFallback): Promise<void>;
+export declare function refuseFallback(s: ActiveSession, remote: string | undefined, fallbackId?: string): Promise<void>;
+export declare function jumpTo(s: ActiveSession, self: string, fallback?: UnreachableFallback, fallbackId?: string): Promise<void>;

package/dist/commands/go.js

@@ -312,17 +312,17 @@ export async function probeAttachRail(s, self) {
 }
 /** Strict attach-only fallback: no pane means no attach. Never open a shell or
  * start recovery, because both would violate the caller's no-fork intent. */
-export async function refuseFallback(s, remote) {
+export async function refuseFallback(s, remote, fallbackId) {
     if (remote) {
         console.log(chalk.yellow(`Can't attach ${shortId(s)} on ${remote} — it has no living tmux pane.`));
         process.exitCode = 1;
         return;
     }
     console.log(chalk.yellow(`Can't jump to ${shortId(s)} — it's in ${s.host ?? 'an unknown terminal'} with no attach rail (not tmux/Ghostty).`) +
-        chalk.gray(`\n${addressabilityRecoveryHint(s)}`));
+        chalk.gray(`\n${addressabilityRecoveryHint(s, fallbackId)}`));
     process.exitCode = 1;
 }
-export async function jumpTo(s, self, fallback = refuseFallback) {
+export async function jumpTo(s, self, fallback = refuseFallback, fallbackId) {
     const remote = sessionProcessHost(s, self);
     const mux = s.provenance?.mux;
     // Path C: remote tmux — ssh in and attach, resolving the pane's session on the remote.
@@ -330,7 +330,7 @@ export async function jumpTo(s, self, fallback = refuseFallback) {
         if (mux?.kind === 'tmux' && mux.pane) {
             const liveness = await probeAttachRail(s, self);
             if (liveness.state !== 'alive') {
-                await fallback(s, remote);
+                await fallback(s, remote, fallbackId);
                 return;
             }
             assertValidSshTarget(remote);
@@ -349,14 +349,14 @@ export async function jumpTo(s, self, fallback = refuseFallback) {
             process.exit(code);
         }
         // Remote, not in tmux → hand off to the fallback (go: shell; focus: resume in a tab).
-        await fallback(s, remote);
+        await fallback(s, remote, fallbackId);
         return;
     }
     // Path B: local tmux — attach (or switch-client if we're already inside tmux).
     if (mux?.kind === 'tmux' && mux.pane) {
         const liveness = await probeAttachRail(s, self);
         if (liveness.state !== 'alive') {
-            await fallback(s, undefined);
+            await fallback(s, undefined, fallbackId);
             return;
         }
         const socket = mux.socket ?? getDefaultSocketPath();
@@ -403,7 +403,7 @@ export async function jumpTo(s, self, fallback = refuseFallback) {
         return;
     }
     // Path D: no attach rail (headless / plain terminal) → hand off to the fallback.
-    await fallback(s, undefined);
+    await fallback(s, undefined, fallbackId);
 }
 /** Resolve a local tmux pane id to its session name + window index. */
 async function resolveLocalPane(socket, pane) {

package/dist/commands/insights.js

@@ -246,6 +246,9 @@ function renderReport(groups, dim, meta, actions, harnesses) {
     for (const g of groups)
         mergeFacets(all, g.facets);
     renderCounts('Top tools', topEntries(all.toolCounts, 8), out);
+    // The `Bash`/`exec` bar above says a shell ran; this says WHICH binary — git, gh,
+    // agents, find, ssh→git — so the tool mix is actionable rather than one lump.
+    renderCounts('Shell commands', topEntries(all.bashCommands, 12), out);
     renderCounts('Languages', topEntries(all.languages, 6), out);
     renderCounts('Models', topEntries(all.models, 6), out);
     // Friction — the section that earns the command.
@@ -281,6 +284,9 @@ function renderReport(groups, dim, meta, actions, harnesses) {
             out.push(`    ${chalk.gray('·')} ${padToWidth(e.name, 16)} ${chalk.gray(String(e.count))}`);
     }
     renderCounts('Friction / thrash', topEntries(all.frictionSignals, 10), out);
+    // Which shell binary was failing when a `failed tool loop: Bash` fired — makes the
+    // loop attributable (`git reconcile`, `find`, `gh`) instead of a bare tool name.
+    renderCounts('Shell command failures', topEntries(all.bashCommandFailures, 8), out);
     renderCounts('Dissatisfaction / corrections', topEntries(all.correctionSignals, 10), out);
     renderCounts('Automatable repeats', topEntries(all.automationSignals, 10), out);
     renderCounts('Harness split', harnesses, out);
@@ -297,6 +303,9 @@ function renderReport(groups, dim, meta, actions, harnesses) {
             out.push(`  ${padToWidth(action.priority, 7)} ${padToWidth(action.category, 11)} ` +
                 `${String(action.evidenceCount).padStart(8)}  ${padToWidth(action.sampleSessionIds.join(', '), 25)} ${action.action}`);
         }
+        // This report is aggregate by contract (SES-IF-4c); a sample id above drills into
+        // one session's timeline via the per-session surface, not a single-session mode here.
+        out.push(chalk.gray('  drill into a sample session:  agents sessions trace <id>'));
     }
     // Output
     out.push('');

package/dist/commands/monitors.js

@@ -24,6 +24,7 @@ import { IS_WINDOWS } from '../lib/platform/index.js';
 import { safeJoin } from '../lib/paths.js';
 import { machineId, normalizeHost } from '../lib/machine-id.js';
 import { loadDevices } from '../lib/devices/registry.js';
+import { assertDaemonEnabled } from '../lib/device-config.js';
 import { setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
 function stdoutJson(payload) {
@@ -52,6 +53,26 @@ function sourceLabel(source) {
             return source.type;
     }
 }
+/** Warn when a run/routine action has no postcondition — completed-exit-0 still records as ok (PHNX-2842). */
+function warnMissingPostcondition(action) {
+    if ((action.type === 'run' || action.type === 'routine') && !action.postcondition) {
+        stderrLine(chalk.yellow(`  Note: ${action.type} has no --postcondition — a completed agent that did nothing will still record as ok. Add --postcondition '<cmd>' that exits 0 when the intended effect happened.`));
+    }
+}
+/** Reconciled one-line outcome for a fire (ok / no effect / failed). */
+function fireOutcomeDisplay(name, f) {
+    const rec = resolveFireOutcome(name, f);
+    if (rec.ok)
+        return { label: chalk.green('ok'), note: '' };
+    if (rec.effect === 'none') {
+        const note = rec.error ? chalk.gray(`    ${rec.error}`) : '';
+        return { label: chalk.yellow('no effect'), note };
+    }
+    const corrected = f.ok !== false && rec.runStatus
+        ? chalk.yellow(` (run ${rec.runStatus})`)
+        : '';
+    return { label: chalk.red('failed') + corrected, note: '' };
+}
 /** A one-line human label for a monitor's action. */
 function actionLabel(action) {
     switch (action.type) {
@@ -123,12 +144,26 @@ function livenessLabel(monitor, state, liveness) {
     }
     return chalk.gray(`checked ${liveness.checkCount}x · last ${checkedAgo} · no match yet`);
 }
-/** Start or reload the background daemon so a newly-added monitor is watched. */
+/**
+ * Start or reload the background daemon so a newly-added monitor is watched.
+ * Returns false when auto-start was refused (`daemon.enabled=false`); the add
+ * itself already succeeded — the monitor is config and stays valid fleet-wide.
+ * The refusal names the setting and the fix. Mirrors `ensureSchedulerRunning`
+ * in commands/routines.ts (PHNX-2637).
+ */
 function ensureDaemonRunning() {
+    try {
+        assertDaemonEnabled();
+    }
+    catch (err) {
+        // Loud stated skip, on stderr so --json stdout stays clean.
+        stderrLine(chalk.yellow(err.message));
+        return false;
+    }
     if (isDaemonRunning()) {
         signalDaemonReload();
         stderrLine(chalk.gray('Daemon reloaded'));
-        return;
+        return true;
     }
     const result = startDaemon();
     if (result.pid) {
@@ -138,6 +173,7 @@ function ensureDaemonRunning() {
     else {
         stderrLine(chalk.yellow('Could not start the daemon. Start it manually with: agents routines start'));
     }
+    return true;
 }
 /**
  * Assert the postcondition of `add`: the engine actually picked the monitor up.
@@ -272,10 +308,16 @@ function buildAction(options) {
             action.effort = options.effort;
         if (options.actionTimeout)
             action.timeout = options.actionTimeout;
+        if (options.postcondition)
+            action.postcondition = options.postcondition;
+        chosen.push(action);
+    }
+    if (options.routine) {
+        const action = { type: 'routine', routine: options.routine };
+        if (options.postcondition)
+            action.postcondition = options.postcondition;
         chosen.push(action);
     }
-    if (options.routine)
-        chosen.push({ type: 'routine', routine: options.routine });
     if (options.notify !== undefined) {
         // --notify may be a bare flag (notify the owner) or carry a channel that
         // overrides notify.owner.channel. Left unset, the send resolves the owner
@@ -293,6 +335,10 @@ function buildAction(options) {
         stderrLine(chalk.red(`Exactly one action is allowed; got ${chosen.map((c) => c.type).join(', ')}`));
         process.exit(1);
     }
+    if (options.postcondition && chosen[0].type !== 'run' && chosen[0].type !== 'routine') {
+        stderrLine(chalk.red('--postcondition only applies to --run or --routine'));
+        process.exit(1);
+    }
     return chosen[0];
 }
 /** Interactive monitor picker. Returns the selected name or null on cancel/empty. */
@@ -379,7 +425,7 @@ async function guardAgainstDuplicateMonitor(config, force) {
 export function registerMonitorsCommands(program) {
     const monitorsCmd = program
         .command('monitors')
-        .description('Durable event-triggered watchers: watch a source, detect a change, fire an action. The daemon auto-starts on first add.');
+        .description('Durable event-triggered watchers: watch a source, detect a change, fire an action. The daemon auto-starts on first add unless daemon.enabled is false.');
     setHelpSections(monitorsCmd, {
         examples: `
       # CI went red → triage it (poll a command, diff, fire an agent)
@@ -388,6 +434,12 @@ export function registerMonitorsCommands(program) {
         --run claude --prompt 'CI failed on #1119: {event}. Diagnose and fix.' \\
         --device yosemite-s0
 
+      # Merge-on-green: the fire is ok only if the PR actually merged
+      agents monitors add merge-1682 \\
+        --poll 'gh pr view 1682 --json state --jq .state' 2m --match OPEN \\
+        --run claude --prompt 'Rebase-merge #1682: {event}' \\
+        --postcondition 'gh pr view 1682 --json state --jq .state | grep -qx MERGED'
+
       # SSL cert issued → notify (poll an HTTPS endpoint every 8h)
       agents monitors add cert-issued \\
         --poll-http 'https://secure.ssl.com/team/.../co-ec1l5dgjofa' 8h \\
@@ -406,10 +458,14 @@ export function registerMonitorsCommands(program) {
         - SOURCE    (--watch, --poll, --poll-http, --ws, --watch-file, --watch-device, --on)
         - CONDITION (--on-change [default], --match <re>, --every; --dedupe-key)
         - ACTION    (--run <agent> --prompt, --routine, --notify, --webhook-out)
+                    --postcondition <cmd> on --run/--routine asserts the effect
+                    happened (exit 0) after the agent settles; otherwise the
+                    fire records as "no effect", not ok.
 
       The fired event is injected into a run/routine prompt as {event}.
       Pin the single OWNER device with --device (exactly-once). The daemon (shared
-      with routines) auto-starts on first add; manage it with 'agents routines start|stop'.
+      with routines) auto-starts on first add unless daemon.enabled is false on this
+      device; manage it with 'agents daemon start|stop' (or 'agents routines start|stop').
 
       v1 evaluates poll sources (command, poll, poll-http, file, device). Push
       sources (ws, webhook) are accepted but delivered through a receiver wired in
@@ -419,7 +475,7 @@ export function registerMonitorsCommands(program) {
     // ─── add ────────────────────────────────────────────────────────────────────
     monitorsCmd
         .command('add [nameOrPath]')
-        .description('Create a monitor from inline flags or a YAML file. Auto-starts the daemon.')
+        .description('Create a monitor from inline flags or a YAML file. Auto-starts the daemon unless daemon.enabled is false.')
         // SOURCE
         .option('--watch <cmd>', 'Run a shell command; its stdout is the observation')
         .option('--poll <cmd...>', 'Re-run a command every interval: --poll "<cmd>" <interval> (e.g. 30s)')
@@ -445,6 +501,7 @@ export function registerMonitorsCommands(program) {
         .option('--mode <mode>', 'Execution mode for --run: plan, edit, auto, or skip')
         .option('--effort <effort>', 'Reasoning effort for --run: low | medium | high | xhigh | max | auto')
         .option('--action-timeout <t>', 'Kill the --run action if it runs longer than this (e.g. 10m)')
+        .option('--postcondition <cmd>', 'Shell command that must exit 0 after a --run/--routine action settles; otherwise the fire records as no-effect, not ok. {event} is replaced with the fired event summary')
         .option('--routine <name>', 'Fire an existing routine on change')
         .option('--notify [channel]', 'Notify the owner (notify.owner); [channel] overrides the owner channel')
         .option('--webhook-out <url>', 'POST the event to this URL')
@@ -481,8 +538,9 @@ export function registerMonitorsCommands(program) {
             await guardAgainstDuplicateMonitor(config, options.force === true);
             writeMonitor(config);
             console.log(chalk.green(`Monitor '${name}' added`));
-            ensureDaemonRunning();
-            await assertEnginePickup(config);
+            warnMissingPostcondition(config.action);
+            if (ensureDaemonRunning())
+                await assertEnginePickup(config);
             return;
         }
         if (!nameOrPath) {
@@ -556,8 +614,9 @@ export function registerMonitorsCommands(program) {
         writeMonitor(config);
         console.log(chalk.green(`Monitor '${nameOrPath}' added`));
         console.log(chalk.gray(`  ${sourceLabel(source)} → [${condition.mode}] → ${actionLabel(action)} · owner: ${ownerLabel(config)}`));
-        ensureDaemonRunning();
-        await assertEnginePickup(config);
+        warnMissingPostcondition(action);
+        if (ensureDaemonRunning())
+            await assertEnginePickup(config);
     });
     // ─── list ────────────────────────────────────────────────────────────────────
     monitorsCmd
@@ -641,7 +700,7 @@ export function registerMonitorsCommands(program) {
                 state,
                 liveness,
                 stalled: isStalled(monitor, liveness),
-                recentFires,
+                recentFires: recentFires.map((f) => ({ ...f, reconciled: resolveFireOutcome(name, f) })),
             });
             return;
         }
@@ -671,9 +730,11 @@ export function registerMonitorsCommands(program) {
         if (recentFires.length > 0) {
             console.log(chalk.bold('\nRecent fires'));
             for (const f of recentFires) {
-                // Reconciled against the run's real status — see `runs`, above (RUSH-2690).
-                const { ok } = resolveFireOutcome(name, f);
-                console.log(`  ${chalk.gray(f.firedAt)}  ${f.action ?? '?'}  ${ok ? chalk.green('ok') : chalk.red('failed')}`);
+                // Reconciled against the run's real status + postcondition (RUSH-2690, PHNX-2842).
+                const { label, note } = fireOutcomeDisplay(name, f);
+                console.log(`  ${chalk.gray(f.firedAt)}  ${f.action ?? '?'}  ${label}`);
+                if (note)
+                    console.log(note);
             }
         }
     });
@@ -847,23 +908,17 @@ export function registerMonitorsCommands(program) {
         }
         console.log(chalk.bold(`Fire history: ${name}\n`));
         for (const f of fires.slice(-20)) {
-            // Reconcile against the run's REAL, current status (RUSH-2690) rather
-            // than trusting the frozen `ok` written at fire time — `dispatchAction`
-            // only sees a synchronous 'running' snapshot before the run has
-            // actually settled, so a run that later fails/times out/never produces
-            // output would otherwise read `ok` here forever while `agents monitors
-            // logs` (which reads the run record fresh) already shows the truth.
-            const { ok, runStatus } = resolveFireOutcome(name, f);
-            const outcome = ok ? chalk.green('ok') : chalk.red('failed');
-            // Surface the divergence explicitly when the frozen write disagreed
-            // with the reconciled read — the exact "fire says ok, run says
-            // otherwise" symptom RUSH-2690 reported.
-            const corrected = f.ok !== false && !ok && runStatus
-                ? chalk.yellow(` (run ${runStatus})`)
-                : '';
+            // Reconcile against the run's REAL, current status (RUSH-2690) and a
+            // declared postcondition (PHNX-2842) rather than trusting the frozen
+            // `ok` written at fire time — `dispatchAction` only sees a synchronous
+            // 'running' snapshot before the run has actually settled, and a
+            // `completed` agent that did nothing used to read `ok` here forever.
+            const { label, note } = fireOutcomeDisplay(name, f);
             const runRef = f.runId ? chalk.gray(`  run ${f.runId}`) : '';
-            console.log(`  ${f.firedAt}  ${(f.action ?? '?').padEnd(12)} ${outcome}${corrected}${runRef}`);
+            console.log(`  ${f.firedAt}  ${(f.action ?? '?').padEnd(12)} ${label}${runRef}`);
             console.log(chalk.gray(`    ${f.summary.slice(0, 100)}`));
+            if (note)
+                console.log(note);
         }
     });
     // ─── pause / resume ───────────────────────────────────────────────────────────