@phnx-labs/agents-cli 1.22.68 → 1.22.70

package/dist/lib/feed-broadcast.js

@@ -38,8 +38,10 @@ import { isOwnerAlias, readOwnerDest, resolveSendEnvelope, deliverEnvelope } fro
 import { lookupTransport } from './channels/resolve.js';
 import { registerBuiltinProviders } from './channels/providers/index.js';
 import { sendToOwner } from './notify.js';
-import { linearIssueUrl } from './session/linear.js';
+import { linearIssueUrl, linearIssueKeys } from './session/linear.js';
+import { isValidMailboxId } from './mailbox.js';
 import { forwardOwnerNotifyToPeer } from './channels/owner-forward.js';
+import { sinkMessageFormat } from './sink-format.js';
 const LEVEL_RANK = { milestone: 0, important: 1 };
 /** Parse a `--level` value; anything unrecognized is a usage error, not a default. */
 export function parseFeedPostLevel(raw) {
@@ -145,6 +147,27 @@ export function shortSessionChunk(session) {
     const chunk = hex.replace(/[^a-f0-9]/g, '').slice(0, 8);
     return chunk || undefined;
 }
+/**
+ * Tap-to-view link for the session behind a post: the addressable console page
+ * ({@link https://prix.dev/console/sessions/<id>}, prix/web). The footer already
+ * carries a short session crumb for disambiguation; this rides the link trail so
+ * the owner can open the full transcript straight from an iMessage broadcast
+ * instead of hunting for it in the console.
+ *
+ * Accepts any real, path-safe session id — a Claude/Codex UUID *and* a native
+ * `ses_…` id from OpenCode or another harness. The console shard uploader
+ * (`traces/sync.ts`) syncs sessions with no harness filter, so all of them are
+ * addressable; a UUID-only gate would silently drop the link for every non-Claude
+ * harness (the whole point of the link). Reject only an id that could not resolve:
+ * one with a path separator (URL-unsafe, via {@link isValidMailboxId}) or the bare
+ * 8-char footer crumb (a truncated id that would 404).
+ */
+export function sessionConsoleUrl(session) {
+    const id = session?.trim();
+    if (!id || !isValidMailboxId(id) || /^[0-9a-f]{8}$/i.test(id))
+        return undefined;
+    return `https://prix.dev/console/sessions/${id}`;
+}
 /**
  * Scrub em/en dashes from outbound phone copy (house rule + iMessage readability).
  * Collapses whitespace; does not invent meaning.
@@ -158,6 +181,39 @@ export function scrubOutboundDashes(text) {
         .replace(/[ \t]{2,}/g, ' ')
         .trim();
 }
+/** Slack mrkdwn labeled link: `<url|label>` renders as blue `label` text. */
+function slackLink(url, label) {
+    return `<${url}|${label}>`;
+}
+/**
+ * The provider a channel name actually delivers through — the same
+ * `notify.transports` remap `lookupTransport` applies at delivery — so the format
+ * decision and the delivery agree on what Slack is. Identity when no mapping
+ * exists (or no `meta`), matching the default name-identity transport rule.
+ */
+function resolveSinkProvider(channel, meta) {
+    return meta?.notify?.transports?.[channel] ?? channel;
+}
+/**
+ * Replace each real Linear key the text NAMES with a Slack labeled link to its
+ * issue — `PHNX-3689` → `<https://linear.app/getrush/issue/PHNX-3689|PHNX-3689>`
+ * — so the key itself turns blue in place (no trailing URL line). Plain format,
+ * or a key the workspace can't resolve, or a denylisted unit string, is left as
+ * the bare key. `linearIssueKeys` is the same canonical detector the trail used,
+ * so mrkdwn linkifies exactly the keys plain leaves as text.
+ */
+function linkifyKeys(text, format) {
+    if (format !== 'mrkdwn' || !text)
+        return text;
+    let out = text;
+    for (const key of linearIssueKeys(text)) {
+        const url = linearIssueUrl(key);
+        if (!url)
+            continue;
+        out = out.replace(new RegExp(`\\b${key}\\b`, 'g'), slackLink(url, key));
+    }
+    return out;
+}
 /**
  * Footer like "Sent from my iPhone" — who posted, a session crumb, which box.
  *
@@ -165,8 +221,13 @@ export function scrubOutboundDashes(text) {
  *
  * Agent name first; session chunk for disambiguation when many groks run;
  * host last. Skip the uninformative default label `agent`.
+ *
+ * In `mrkdwn` the crumb (`agent/short`) becomes a Slack labeled link to the
+ * session's console page, so the human sentence reads identically while the
+ * crumb turns blue and taps through (PHNX-3698). `plain` keeps the bare sentence
+ * — it can't render a labeled link and must not dump the URL.
  */
-export function composeBroadcastFooter(ctx) {
+export function composeBroadcastFooter(ctx, format = 'plain') {
     const agent = ctx.agent?.trim();
     const agentLabel = agent && agent !== 'agent' ? agent : undefined;
     const session = shortSessionChunk(ctx.session);
@@ -178,6 +239,10 @@ export function composeBroadcastFooter(ctx) {
         who = agentLabel;
     else if (session)
         who = session;
+    // The crumb is only a link when the session resolves to a real console page.
+    const consoleUrl = who ? sessionConsoleUrl(ctx.session) : undefined;
+    if (who && format === 'mrkdwn' && consoleUrl)
+        who = slackLink(consoleUrl, who);
     if (who && host)
         return `Sent from ${who} on ${host}`;
     if (who)
@@ -236,16 +301,17 @@ export function truncateBroadcastBody(body) {
         return body;
     return `${out.trimEnd()}\n… (full in feed)`;
 }
-export function composeBroadcastMessage(ctx) {
+export function composeBroadcastMessage(ctx, format = 'plain') {
     const title = scrubOutboundDashes(ctx.title ?? '');
     const body = truncateBroadcastBody(scrubOutboundDashes(ctx.text ?? ''));
     // Title preferred; if an older post has no title, body alone still sends.
-    const head = title || body;
-    const mid = title && body && title !== body ? body : undefined;
-    const footer = composeBroadcastFooter(ctx);
-    const links = [ctx.ticketUrl, ...(ctx.links ?? [])]
-        .filter((l) => !!l && /^https?:\/\//i.test(l))
-        .filter((l, i, all) => all.indexOf(l) === i);
+    // A `TEAM-N` key the human typed is dead text on a phone — in `mrkdwn` the key
+    // itself becomes a Slack labeled link in place, so nothing rides a trailing
+    // naked URL line; `plain` leaves the bare key (iMessage can't render a label,
+    // and dumping the URL is worse than leaving it — PHNX-3698).
+    const head = linkifyKeys(title || body, format);
+    const mid = title && body && title !== body ? linkifyKeys(body, format) : undefined;
+    const footer = composeBroadcastFooter(ctx, format);
     // The action block: the one thing the operator can act on from a phone. Show the
     // choices, then what happens if they do not answer. Deliberately NOT a CLI command
     // (`agents focus <id>` is unusable from a phone) -- the safe default is the real
@@ -259,8 +325,6 @@ export function composeBroadcastMessage(ctx) {
             : `Default: ${scrubOutboundDashes(ctx.safeDefault)}`)
         : undefined;
     const action = [choices, fallback].filter(Boolean).join('\n') || undefined;
-    // Link trail after the "Sent from" footer so the human sentence stays at the top.
-    const trail = [footer, ...links].filter(Boolean);
     const parts = [];
     if (head)
         parts.push(head);
@@ -275,16 +339,22 @@ export function composeBroadcastMessage(ctx) {
             parts.push('');
         parts.push(action);
     }
-    if (trail.length) {
-        // Blank line before the footer block (iPhone "Sent from my iPhone" spacing).
+    if (footer) {
+        // Blank line before the "Sent from" footer (iPhone "Sent from my iPhone" spacing).
+        // The crumb/ticket links are inline (footer + prose) — never a trailing URL line.
         if (parts.length)
             parts.push('');
-        parts.push(trail.join('\n'));
+        parts.push(footer);
     }
     return parts.join('\n').trim();
 }
-/** The values a template may reference, resolved once per post. */
-function templateVars(ctx) {
+/**
+ * The values a template may reference, resolved once per post. `format` decides
+ * how `{message}` surfaces its links — Slack `mrkdwn` (labeled links) vs `plain`
+ * (the human sentence, no URLs). The scalar `{ticket_url}`/`{links}` vars are the
+ * raw URLs a custom `message:` template can place itself, so they are unaffected.
+ */
+function templateVars(ctx, format = 'plain') {
     return {
         title: ctx.title,
         text: ctx.text,
@@ -296,7 +366,7 @@ function templateVars(ctx) {
         session: ctx.session,
         level: ctx.level,
         links: ctx.links?.length ? ctx.links.join(' ') : undefined,
-        message: composeBroadcastMessage(ctx),
+        message: composeBroadcastMessage(ctx, format),
         block: ctx.blockId,
         class: ctx.class,
         cost: ctx.cost,
@@ -330,9 +400,14 @@ export function renderSinkArgv(template, ctx) {
     }
     return argv.length > 0 ? argv : undefined;
 }
-/** Render one channel-message template with the same fail-closed placeholder contract as argv. */
-export function renderSinkMessage(template, ctx) {
-    const vars = templateVars(ctx);
+/**
+ * Render one channel-message template with the same fail-closed placeholder
+ * contract as argv. `format` (Slack `mrkdwn` vs `plain`) flows into the shared
+ * `{message}` var so a Slack sink gets labeled links and an iMessage/owner sink
+ * gets the plain sentence.
+ */
+export function renderSinkMessage(template, ctx, format = 'plain') {
+    const vars = templateVars(ctx, format);
     let missing = false;
     const rendered = template.replace(PLACEHOLDER, (whole, key) => {
         const value = vars[key];
@@ -367,8 +442,12 @@ export function renderSinkMessage(template, ctx) {
  * A `channel:` sink is gated by the same `minLevel` rule as a `command:` sink —
  * one level check for both shapes, so a dry-run plan is truthful regardless of
  * which shape an operator's sink uses.
+ *
+ * `meta` is used only to resolve a channel name to its real provider for the
+ * mrkdwn/plain format decision (`notify.transports`), the same map delivery uses;
+ * it is optional so a test can plan without a config snapshot (identity mapping).
  */
-export function planFeedBroadcast(config, ctx) {
+export function planFeedBroadcast(config, ctx, meta) {
     if (!config)
         return [];
     const planned = [];
@@ -386,14 +465,28 @@ export function planFeedBroadcast(config, ctx) {
             // placeholder below).
             if (!isOwnerAlias(channel) && !sink.to?.trim())
                 continue;
-            const text = renderSinkMessage(sink.message ?? '{message}', ctx);
+            // Slack renders labeled links; every other channel (iMessage, telegram,
+            // discord, mailbox, desktop) stays plain (PHNX-3698). A DIRECT channel sink
+            // has one known provider, so its format is resolved here. The OWNER ALIAS
+            // fans out to every channel in owner.policy.normal — each with its OWN
+            // provider — so it can't pick one format now: it carries the ctx + template
+            // and re-renders per destination inside the owner fan-out (runChannelSink →
+            // sendToOwner), so the Slack destination turns blue while a sibling iMessage
+            // copy stays plain. The plain body computed here is the dry-run/fallback
+            // default. Keying on the resolved provider (not the raw name) matches what
+            // delivery does.
+            const owner = isOwnerAlias(channel);
+            const template = sink.message ?? '{message}';
+            const provider = owner ? channel : resolveSinkProvider(channel, meta);
+            const text = renderSinkMessage(template, ctx, sinkMessageFormat(provider));
             if (!text)
                 continue;
             planned.push({
                 name,
                 channel,
-                to: isOwnerAlias(channel) ? undefined : sink.to.trim(),
+                to: owner ? undefined : sink.to.trim(),
                 text,
+                ...(owner ? { ctx, messageTemplate: template } : {}),
             });
             continue;
         }
@@ -502,7 +595,17 @@ async function runChannelSink(sink, meta) {
     registerBuiltinProviders();
     const owner = isOwnerAlias(sink.channel);
     if (owner) {
-        const result = await sendToOwner(sink.text ?? '', { meta });
+        // Re-render the body PER owner destination so a Slack channel in the policy
+        // gets mrkdwn labeled links while iMessage stays plain (PHNX-3698). The
+        // fan-out (sendToOwner) resolves each destination's provider and asks this
+        // composer for the matching format. renderSinkMessage is fail-closed on a
+        // missing placeholder — the plan already dropped the sink if the template
+        // couldn't fill, so here it always resolves; `?? sink.text` is a belt-and-
+        // braces guard, never the normal path.
+        const composeForFormat = sink.ctx
+            ? (format) => renderSinkMessage(sink.messageTemplate ?? '{message}', sink.ctx, format) ?? sink.text ?? ''
+            : undefined;
+        const result = await sendToOwner(sink.text ?? '', { meta, composeForFormat });
         return { name, ok: result.ok, ...(result.error ? { error: result.error } : {}) };
     }
     const resolved = resolveSendEnvelope({

package/dist/lib/hooks/install.js

@@ -1845,9 +1845,6 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     if (agentId === 'copilot') {
         return registerHooksForCopilot(versionHome, manifest, resolveScript, managedPrefixes);
     }
-    if (agentId === 'kiro') {
-        return registerHooksForKiro(versionHome, manifest, resolveScript, managedPrefixes);
-    }
     if (agentId === 'goose') {
         return registerHooksForGoose(versionHome, manifest, resolveScript, managedPrefixes);
     }
@@ -2846,90 +2843,6 @@ function registerHooksForCopilot(versionHome, manifest, resolveScript, _managedP
     }
     return { registered, errors };
 }
-/**
- * Canonical hooks.yaml event names → Kiro v3 trigger names.
- * Kiro v3 uses PascalCase triggers under `.kiro/hooks/*.json`
- * (https://kiro.dev/docs/cli/v3/hooks/). Unmapped events are skipped.
- */
-const KIRO_EVENT_MAP = {
-    SessionStart: 'SessionStart',
-    Stop: 'Stop',
-    PreToolUse: 'PreToolUse',
-    PostToolUse: 'PostToolUse',
-    UserPromptSubmit: 'UserPromptSubmit',
-};
-/**
- * Kiro triggers that evaluate the `matcher` regex (tool name, file path, or
- * prompt text depending on the trigger). Lifecycle SessionStart/Stop always fire.
- */
-const KIRO_MATCHER_EVENTS = new Set([
-    'PreToolUse',
-    'PostToolUse',
-    'UserPromptSubmit',
-]);
-/** Managed filename under ~/.kiro/hooks/ — we own this file entirely. */
-const KIRO_MANAGED_HOOKS_FILE = 'agents-cli-hooks.json';
-/**
- * Register hooks for Kiro CLI (v3 standalone hooks format).
- *
- * Each file under `~/.kiro/hooks/*.json` is:
- *   { "version": "v1", "hooks": [ { name, trigger, matcher?, action, timeout?, enabled? } ] }
- *
- * We rewrite a single managed file so GC is a rewrite and user-authored sibling
- * JSON files are never touched. Embedded agent-config hooks (2.x) still work
- * in Kiro but we only write the v3 path.
- */
-function registerHooksForKiro(versionHome, manifest, resolveScript, _managedPrefixes) {
-    const registered = [];
-    const errors = [];
-    const kiroHooksDir = path.join(versionHome, '.kiro', 'hooks');
-    fs.mkdirSync(kiroHooksDir, { recursive: true });
-    const hooks = [];
-    for (const [name, hookDef] of Object.entries(manifest)) {
-        if (!hookDef.events || hookDef.events.length === 0)
-            continue;
-        const commandPath = resolveHookCommand(name, hookDef, resolveScript);
-        if (!commandPath) {
-            errors.push(`${name}: script not found in user or system hooks dir`);
-            continue;
-        }
-        const timeout = hookDef.timeout ?? 60;
-        for (const event of hookDef.events) {
-            const trigger = KIRO_EVENT_MAP[event];
-            if (!trigger)
-                continue;
-            const entry = {
-                name,
-                trigger,
-                action: { type: 'command', command: commandPath },
-                timeout,
-                enabled: true,
-            };
-            if (KIRO_MATCHER_EVENTS.has(trigger) && hookDef.matcher) {
-                entry.matcher = hookDef.matcher;
-            }
-            // De-dupe on (name, trigger, matcher)
-            const existingIdx = hooks.findIndex((h) => h.name === entry.name &&
-                h.trigger === entry.trigger &&
-                (h.matcher ?? '') === (entry.matcher ?? ''));
-            if (existingIdx >= 0) {
-                hooks[existingIdx] = entry;
-            }
-            else {
-                hooks.push(entry);
-            }
-            registered.push(`${name} -> ${trigger}`);
-        }
-    }
-    const outPath = path.join(kiroHooksDir, KIRO_MANAGED_HOOKS_FILE);
-    try {
-        fs.writeFileSync(outPath, JSON.stringify({ version: 'v1', hooks }, null, 2) + '\n', 'utf-8');
-    }
-    catch (err) {
-        errors.push(`Failed to write ${KIRO_MANAGED_HOOKS_FILE}: ${err.message}`);
-    }
-    return { registered, errors };
-}
 /**
  * Canonical hooks.yaml event names that goose supports (Open Plugins PascalCase).
  * Unmapped events are skipped. Goose ≥ 1.34.0.

package/dist/lib/installations/strategies.js

@@ -177,7 +177,7 @@ const globalBinaryStrategy = {
 };
 /**
  * Harnesses installed by an official script that keeps a per-installation copy
- * or symlink farm (grok, cursor, antigravity, hermes, kiro, goose, …). The
+ * or symlink farm (grok, cursor, antigravity, hermes, goose, …). The
  * vendor artifact lands in a global location the installer owns, so the fetch
  * itself is not reversible; what IS per-installation — the version dir's binary
  * link farm — is staged and swapped so a failed re-import cannot strand the

package/dist/lib/mcp-registry.js

@@ -108,13 +108,6 @@ export const MCP_TARGETS = {
         project: (cwd) => path.join(cwd, '.hermes', 'config.yaml'),
         format: 'yaml',
     },
-    pi: {
-        // omp reads user-scope MCP from ~/.omp/agent/.mcp.json and project MCP from
-        // <root>/.mcp.json (both the Claude schema).
-        home: (h) => path.join(h, '.omp', 'agent', '.mcp.json'),
-        project: (cwd) => path.join(cwd, '.mcp.json'),
-        format: 'claude-json',
-    },
     muse: {
         home: (h) => path.join(h, '.config', 'muse', 'settings.json'),
         project: (cwd) => path.join(cwd, '.muse', 'settings.json'),
@@ -143,12 +136,6 @@ export const MCP_TARGETS = {
         format: null,
         unsupportedReason: 'Amp nests MCP under a settings key rather than a top-level map; schema not verified',
     },
-    kiro: {
-        home: (h) => path.join(h, '.kiro', 'settings', 'mcp.json'),
-        project: (cwd) => path.join(cwd, '.kiro', 'settings', 'mcp.json'),
-        format: null,
-        unsupportedReason: 'mcp.json schema not verified against an installed Kiro',
-    },
     goose: {
         home: (h) => path.join(h, '.config', 'goose', 'config.yaml'),
         project: (cwd) => path.join(cwd, '.goose', 'config.yaml'),

package/dist/lib/mcp.js

@@ -529,8 +529,8 @@ export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite')
     }
     const format = target.format;
     switch (format) {
-        // Claude's `{ "mcpServers": {...} }` schema, shared by cursor, kimi, droid,
-        // omp (.mcp.json) and Oz (.warp/.mcp.json): stdio carries command/args/env,
+        // Claude's `{ "mcpServers": {...} }` schema, shared by cursor, kimi, droid
+        // and Oz (.warp/.mcp.json): stdio carries command/args/env,
         // remote carries url + optional headers.
         case 'claude-json': {
             const config = readExistingConfig(configPath, JSON.parse);

package/dist/lib/model-tiers.js

@@ -127,7 +127,7 @@ function rankCatalog(agent, models) {
     // Cursor and Pi (Oh My Pi) are cross-provider aggregators: their ids are
     // provider-qualified (`anthropic/…`, `openai/…`) and span vendors, so price of
     // the normalized base id is the only unifying rank signal.
-    const aggregator = agent === 'cursor' || agent === 'pi';
+    const aggregator = agent === 'cursor';
     const scored = usable.map((m) => {
         const rawId = m.id;
         const baseId = aggregator ? normalizeAggregatorId(rawId) : rawId;

package/dist/lib/models.js

@@ -191,18 +191,6 @@ export function locateModelSource(agent, version) {
             return { path: pathBin, kind: 'cli' };
         return null;
     }
-    if (agent === 'pi') {
-        // omp (Oh My Pi) installs via `bun install -g`; a version-managed install
-        // exposes it under node_modules/.bin/omp, otherwise it lives on PATH. We let
-        // the CLI produce its own catalog via `omp models --json` (extractPiCatalog).
-        const cli = path.join(versionDir, 'node_modules', '.bin', 'omp');
-        if (fs.existsSync(cli))
-            return { path: cli, kind: 'cli' };
-        const pathBin = findOnPath('omp');
-        if (pathBin)
-            return { path: pathBin, kind: 'cli' };
-        return null;
-    }
     if (agent === 'muse') {
         // Muse Code is a self-updating native binary on PATH. It has no catalog
         // CLI; the published model IDs are fixed by Meta Model API docs. Point at
@@ -841,55 +829,6 @@ function extractKimiCatalog(binaryPath) {
     }
     return { models, aliases: {} };
 }
-/**
- * Extract Oh My Pi's catalog via `omp models --json`. omp is a cross-provider
- * aggregator: its catalog is the union of every provider it has a key for, so
- * ids are provider-qualified selectors (`anthropic/claude-opus-4-8`,
- * `openai/gpt-5.2`, `xai/grok-4`, `deepseek/deepseek-chat`, …) — exactly the
- * `provider/model` convention `ModelInfo.id` already uses. Output shape:
- *   {"models":[{"provider":"anthropic","id":"claude-opus-4-8",
- *               "selector":"anthropic/claude-opus-4-8","name":"Claude Opus 4.8",
- *               "cost":{...}}, ...]}
- * The catalog is gated per-provider by key presence (no key -> that provider's
- * models are absent, and an empty env yields `{"models":[]}`). That is truthful:
- * the extractor surfaces exactly the providers the user has authenticated.
- * Pricing is attached uniformly by getModelCatalog via getModelPricing(id),
- * which strips the `provider/` prefix — so no per-catalog price shape here.
- */
-function extractPiCatalog(binaryPath) {
-    let stdout;
-    try {
-        stdout = execFileSync(binaryPath, ['models', '--json'], {
-            encoding: 'utf-8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-            timeout: 15_000,
-            maxBuffer: 64 * 1024 * 1024,
-        });
-    }
-    catch {
-        return { models: [], aliases: {} };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(stdout.replace(/\x1b\[[0-9;]*[A-Za-z]/g, ''));
-    }
-    catch {
-        return { models: [], aliases: {} };
-    }
-    if (!parsed || !Array.isArray(parsed.models))
-        return { models: [], aliases: {} };
-    const models = [];
-    const seen = new Set();
-    for (const m of parsed.models) {
-        // Prefer the provider-qualified selector; fall back to provider/id.
-        const id = m.selector || (m.provider && m.id ? `${m.provider}/${m.id}` : m.id);
-        if (!id || seen.has(id))
-            continue;
-        seen.add(id);
-        models.push({ id, displayName: typeof m.name === 'string' ? m.name : undefined });
-    }
-    return { models, aliases: {} };
-}
 /**
  * Build (or load from cache) the model catalog for a specific (agent, version).
  * Cache is keyed on source-file mtime (binary or js module), so re-extracts
@@ -967,8 +906,6 @@ export function getModelCatalog(agent, version) {
             ({ models, aliases } = extractKimiCatalog(src.path));
         else if (agent === 'grok')
             ({ models, aliases } = extractGrokCatalog(src.path));
-        else if (agent === 'pi')
-            ({ models, aliases } = extractPiCatalog(src.path));
         else if (agent === 'muse')
             ({ models, aliases } = extractMuseCatalog());
     }

package/dist/lib/monitors/engine.js

@@ -54,6 +54,14 @@ export function decideFire(monitor, observation) {
     const raw = observation.raw;
     const payload = observation.meta ?? {};
     const dedupeKey = cond.dedupeKey;
+    // A snapshot the source flagged as an OBSERVATION FAILURE (a poll that exited
+    // non-zero or emitted a transport/auth/rate-limit error) is never a value
+    // change: don't fire, don't move the baseline — so an empty→error→empty flap
+    // can't read as two value changes (PHNX-3510). The engine records it as a
+    // failed check separately, feeding the drought health streak.
+    if (observation.failed) {
+        return { fire: false, value: raw, dedupeKey, persist: false, event: null };
+    }
     if (cond.mode === 'every') {
         // Fire on every tick that carries a real observation. An empty (or
         // whitespace-only) observation means "nothing to report": firing an action
@@ -203,6 +211,16 @@ export class MonitorEngine {
             if (!observation) {
                 checkError = 'source produced no observation';
             }
+            else if (observation.failed) {
+                // The poll ran but did not OBSERVE (non-zero exit, or a transport/auth/
+                // rate-limit error in its output). Skip it entirely: no decideFire, no
+                // fire, watched-state untouched — so no empty→error→empty flap dispatches
+                // an agent on a dead premise. Record it as a failed check so a sustained
+                // streak escalates as a drought, the same health surface `--postcondition`
+                // uses on the action side (PHNX-3510).
+                checkError = `poll failed: ${observation.failureReason ?? 'observation failure'}`;
+                this.logFn('WARN', `monitor '${monitor.name}' poll failed (${observation.failureReason ?? 'observation failure'}) — not treated as a value change`);
+            }
             else {
                 const decision = decideFire(monitor, observation);
                 if (decision.fire && decision.event) {

package/dist/lib/monitors/sources/command.js

@@ -6,6 +6,7 @@
  * here. No agent, no sandbox: a plain `/bin/sh -c` (or `cmd /c` on Windows).
  */
 import { execFile } from 'child_process';
+import { classifyPollFailure } from './failure.js';
 const DEFAULT_TIMEOUT_MS = 60_000;
 /** Run the source command and return its combined stdout as the observation. */
 export function evaluate(source) {
@@ -22,10 +23,19 @@ export function evaluate(source) {
                 : err
                     ? 1
                     : 0;
-            // A non-zero exit is still a real observation (the diff might be exactly
-            // "command started failing"); surface stderr when stdout is empty.
+            // Surface stderr when stdout is empty.
             const raw = (stdout && stdout.length > 0 ? stdout : stderr ?? '').replace(/\s+$/, '');
-            resolve({ raw, meta: { exitCode } });
+            // A poll that failed to OBSERVE — non-zero exit, or a transport/auth/
+            // rate-limit error shape in its output (which a piped `gh … | jq`
+            // swallows the exit code of) — is not a new value. Flag it so the engine
+            // skips it instead of reading empty→error→empty as two value changes and
+            // dispatching an agent on a dead premise (PHNX-3510).
+            const failureReason = classifyPollFailure({ exitCode, text: raw });
+            resolve({
+                raw,
+                meta: { exitCode },
+                ...(failureReason ? { failed: true, failureReason } : {}),
+            });
         });
     });
 }

package/dist/lib/monitors/sources/failure.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Poll-failure classifier (PHNX-3510).
+ *
+ * A poll that FAILS to observe — the command exited non-zero, or its output
+ * carries a transport/auth/rate-limit error shape — is an OBSERVATION FAILURE,
+ * not a new value. Reading it as a value is the defect this closes: a
+ * `gh pr list … | jq` monitor whose gh half intermittently prints
+ * `GraphQL: API rate limit already exceeded …` flapped empty→error→empty, and an
+ * `[on-change]` monitor read that as two value changes and dispatched a full
+ * agent run on a premise that was false.
+ *
+ * The exit code alone is not enough: when gh is piped into jq the shell's exit
+ * status is jq's (0 on empty input), so the rate-limit text can ride an exit-0
+ * observation. The text patterns catch exactly that case. They stay tightly
+ * scoped to unambiguous failure shapes so a legitimate observation whose content
+ * merely mentions "timeout" is never misread as a failure.
+ */
+/** The failure reason matched in a poll's output text, or null when it looks clean. */
+export declare function matchFailureText(text: string): string | null;
+/**
+ * Classify one poll snapshot. Returns a short failure reason when the snapshot is
+ * an observation failure (non-zero exit, or a failure-shaped output), else null —
+ * in which case the snapshot is a genuine value the condition may diff.
+ *
+ * A failure-shaped OUTPUT is checked even on exit 0, because a piped command
+ * (`gh … | jq`) swallows the failing half's exit code. A non-zero exit is a
+ * failure regardless of output shape.
+ */
+export declare function classifyPollFailure(input: {
+    exitCode?: number;
+    text: string;
+}): string | null;

package/dist/lib/monitors/sources/failure.js

@@ -0,0 +1,52 @@
+/**
+ * Poll-failure classifier (PHNX-3510).
+ *
+ * A poll that FAILS to observe — the command exited non-zero, or its output
+ * carries a transport/auth/rate-limit error shape — is an OBSERVATION FAILURE,
+ * not a new value. Reading it as a value is the defect this closes: a
+ * `gh pr list … | jq` monitor whose gh half intermittently prints
+ * `GraphQL: API rate limit already exceeded …` flapped empty→error→empty, and an
+ * `[on-change]` monitor read that as two value changes and dispatched a full
+ * agent run on a premise that was false.
+ *
+ * The exit code alone is not enough: when gh is piped into jq the shell's exit
+ * status is jq's (0 on empty input), so the rate-limit text can ride an exit-0
+ * observation. The text patterns catch exactly that case. They stay tightly
+ * scoped to unambiguous failure shapes so a legitimate observation whose content
+ * merely mentions "timeout" is never misread as a failure.
+ */
+const FAILURE_TEXT_PATTERNS = [
+    { re: /\bAPI rate limit (?:already )?exceeded\b/i, reason: 'API rate limit exceeded' },
+    { re: /\bsecondary rate limit\b/i, reason: 'secondary rate limit' },
+    { re: /^\s*GraphQL:\s/im, reason: 'GraphQL error' },
+    { re: /\bbad credentials\b/i, reason: 'bad credentials' },
+    { re: /\b(?:401 Unauthorized|403 Forbidden)\b/i, reason: 'auth error' },
+    { re: /\bcould not resolve host\b/i, reason: 'transport error (DNS)' },
+    { re: /\bconnection (?:refused|reset|timed out)\b/i, reason: 'connection error' },
+    { re: /\bnetwork is unreachable\b/i, reason: 'network unreachable' },
+];
+/** The failure reason matched in a poll's output text, or null when it looks clean. */
+export function matchFailureText(text) {
+    for (const { re, reason } of FAILURE_TEXT_PATTERNS) {
+        if (re.test(text))
+            return reason;
+    }
+    return null;
+}
+/**
+ * Classify one poll snapshot. Returns a short failure reason when the snapshot is
+ * an observation failure (non-zero exit, or a failure-shaped output), else null —
+ * in which case the snapshot is a genuine value the condition may diff.
+ *
+ * A failure-shaped OUTPUT is checked even on exit 0, because a piped command
+ * (`gh … | jq`) swallows the failing half's exit code. A non-zero exit is a
+ * failure regardless of output shape.
+ */
+export function classifyPollFailure(input) {
+    const textReason = matchFailureText(input.text);
+    const badExit = typeof input.exitCode === 'number' && input.exitCode !== 0;
+    if (badExit) {
+        return textReason ? `${textReason} (exit ${input.exitCode})` : `command exited ${input.exitCode}`;
+    }
+    return textReason;
+}