@phnx-labs/agents-cli 1.22.68 → 1.22.69

package/dist/lib/feed-broadcast.d.ts

@@ -136,11 +136,56 @@ export interface SinkOutcome {
 export declare function shortHost(host: string | undefined): string | undefined;
 /** First 8 hex chars of a session id for the footer (readable, not a full uuid). */
 export declare function shortSessionChunk(session: string | undefined): string | 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 declare function sessionConsoleUrl(session: string | undefined): string | undefined;
 /**
  * Scrub em/en dashes from outbound phone copy (house rule + iMessage readability).
  * Collapses whitespace; does not invent meaning.
  */
 export declare function scrubOutboundDashes(text: string): string;
+/**
+ * The rendering vocabulary a sink can display, which decides how the shared
+ * `{message}` surfaces its links (PHNX-3698):
+ *
+ *   - `mrkdwn` — Slack, which renders `<url|label>` as blue tappable text. The
+ *     session crumb and every ticket key the prose NAMES become inline labeled
+ *     links, so nothing rides a trailing naked-URL line.
+ *   - `plain` — iMessage, the owner-scoped rush message, a spawned `command:`
+ *     sink, desktop banners: none can render a labeled link and a dumped naked
+ *     URL reads as noise, so the message stays the human sentence with no URLs.
+ *
+ * The default is `plain`; only a Slack `channel:` sink opts into `mrkdwn`.
+ */
+export type SinkMessageFormat = 'plain' | 'mrkdwn';
+/**
+ * Only Slack renders `<url|label>`, so it is the one format that gets labeled
+ * links. iMessage / owner-scoped rush / command / desktop sinks stay `plain`
+ * (they can't turn `claude/6fc1db18` blue, and dumping the raw URL is worse than
+ * leaving the crumb unlinked — PHNX-3698).
+ *
+ * The argument is the **resolved provider name**, not the sink's declared
+ * channel: an operator can point an arbitrary channel name at the Slack provider
+ * through `notify.transports` (e.g. `eng-alerts -> slack`), and delivery keys off
+ * that resolved provider (`lookupTransport`), so the format decision must too —
+ * otherwise an aliased Slack sink would compose plain while delivering to Slack,
+ * or a name remapped AWAY from Slack would emit `<url|label>` markup a non-Slack
+ * transport shows literally. {@link resolveSinkProvider} does the mapping.
+ */
+export declare function sinkMessageFormat(provider: string | undefined): SinkMessageFormat;
 /**
  * Footer like "Sent from my iPhone" — who posted, a session crumb, which box.
  *
@@ -148,10 +193,15 @@ export declare function scrubOutboundDashes(text: string): string;
  *
  * 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 declare function composeBroadcastFooter(ctx: FeedBroadcastContext): string | undefined;
+export declare function composeBroadcastFooter(ctx: FeedBroadcastContext, format?: SinkMessageFormat): string | undefined;
 export declare function truncateBroadcastBody(body: string): string;
-export declare function composeBroadcastMessage(ctx: FeedBroadcastContext): string;
+export declare function composeBroadcastMessage(ctx: FeedBroadcastContext, format?: SinkMessageFormat): string;
 /**
  * Substitute `{placeholder}` tokens in an argv template. Returns undefined when
  * the template needs a value this post does not have — the sink is then skipped
@@ -159,8 +209,13 @@ export declare function composeBroadcastMessage(ctx: FeedBroadcastContext): stri
  * would otherwise comment on nothing.
  */
 export declare function renderSinkArgv(template: string[], ctx: FeedBroadcastContext): string[] | undefined;
-/** Render one channel-message template with the same fail-closed placeholder contract as argv. */
-export declare function renderSinkMessage(template: string, ctx: FeedBroadcastContext): string | undefined;
+/**
+ * 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 declare function renderSinkMessage(template: string, ctx: FeedBroadcastContext, format?: SinkMessageFormat): string | undefined;
 /**
  * Which sinks this post reaches, in config order. Pure — the dry-run listing and
  * the real fan-out plan through here, so what `--dry-run` shows is what runs.
@@ -168,8 +223,12 @@ export declare function renderSinkMessage(template: string, ctx: FeedBroadcastCo
  * 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 declare function planFeedBroadcast(config: FeedBroadcastConfig | undefined, ctx: FeedBroadcastContext): PlannedSink[];
+export declare function planFeedBroadcast(config: FeedBroadcastConfig | undefined, ctx: FeedBroadcastContext, meta?: Meta): PlannedSink[];
 /**
  * The effective sink config for a post: the operator's `feed.broadcast`, or —
  * when that is unset or empty — an implicit fallback straight to

package/dist/lib/feed-broadcast.js

@@ -38,7 +38,8 @@ 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';
 const LEVEL_RANK = { milestone: 0, important: 1 };
 /** Parse a `--level` value; anything unrecognized is a usage error, not a default. */
@@ -145,6 +146,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 +180,56 @@ 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}>`;
+}
+/**
+ * Only Slack renders `<url|label>`, so it is the one format that gets labeled
+ * links. iMessage / owner-scoped rush / command / desktop sinks stay `plain`
+ * (they can't turn `claude/6fc1db18` blue, and dumping the raw URL is worse than
+ * leaving the crumb unlinked — PHNX-3698).
+ *
+ * The argument is the **resolved provider name**, not the sink's declared
+ * channel: an operator can point an arbitrary channel name at the Slack provider
+ * through `notify.transports` (e.g. `eng-alerts -> slack`), and delivery keys off
+ * that resolved provider (`lookupTransport`), so the format decision must too —
+ * otherwise an aliased Slack sink would compose plain while delivering to Slack,
+ * or a name remapped AWAY from Slack would emit `<url|label>` markup a non-Slack
+ * transport shows literally. {@link resolveSinkProvider} does the mapping.
+ */
+export function sinkMessageFormat(provider) {
+    return provider?.trim().toLowerCase() === 'slack' ? 'mrkdwn' : 'plain';
+}
+/**
+ * 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 +237,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 +255,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 +317,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 +341,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 +355,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 +382,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 +416,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 +458,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,7 +481,14 @@ 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 (owner alias, iMessage,
+            // telegram, discord, mailbox, desktop) stays plain (PHNX-3698). The owner
+            // alias is deliberately plain even when it fans out to a Slack destination:
+            // it delivers ONE shared string to every channel in owner.policy.normal, so
+            // mrkdwn markup would corrupt a sibling iMessage copy. Keying on the
+            // resolved provider (not the raw name) matches what delivery does.
+            const provider = isOwnerAlias(channel) ? channel : resolveSinkProvider(channel, meta);
+            const text = renderSinkMessage(sink.message ?? '{message}', ctx, sinkMessageFormat(provider));
             if (!text)
                 continue;
             planned.push({

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;
+}

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

@@ -11,6 +11,15 @@ import type { MonitorSource } from '../config.js';
 export interface Observation {
     raw: string;
     meta?: Record<string, unknown>;
+    /**
+     * The source flagged this snapshot as an OBSERVATION FAILURE (a poll that
+     * exited non-zero or emitted a transport/auth/rate-limit error), not a value.
+     * The engine skips it: no fire, watched-state untouched, counted as a failed
+     * check for drought health (PHNX-3510).
+     */
+    failed?: boolean;
+    /** Short human reason for `failed`, surfaced in drought health and `test`. */
+    failureReason?: string;
 }
 /** Poll-model evaluator: return one observation, or null when none is available. */
 export type SourceEvaluator = (source: MonitorSource) => Promise<Observation | null>;

package/dist/lib/owner-message.d.ts

@@ -0,0 +1,12 @@
+export interface OwnerMessageOptions {
+    /** Scannable subject line, when the caller has one (feed post does; notify does not). */
+    title?: string;
+    /** Explicit session id (`--session`); otherwise resolved from the run environment. */
+    sessionId?: string;
+}
+/**
+ * Shape a raw owner-send body into the composed broadcast message. Pure except
+ * for the identity/index reads that {@link resolvePostIdentity} /
+ * {@link getSessionById} already perform for feed posts.
+ */
+export declare function composeOwnerMessage(rawText: string, opts?: OwnerMessageOptions): string;

package/dist/lib/owner-message.js

@@ -0,0 +1,44 @@
+/**
+ * Compose an owner-bound phone ping through the SAME shaper `agents feed post`
+ * uses, so `agents notify` / `agents send --to owner` stop shipping a raw body
+ * dump (PHNX-3698).
+ *
+ * Before this, an owner send delivered the body verbatim: a long wall of prose,
+ * a `TEAM-N` key iMessage renders as dead text, and no way back to the session.
+ * Routing the body through {@link composeBroadcastMessage} makes an owner ping
+ * identical to an important feed post of the same event — short-shaped body,
+ * every ticket key linkified to its Linear URL, and the current session's
+ * `…/console/sessions/<id>` page as a tappable crumb.
+ *
+ * The session/agent/host are resolved the same way a feed post resolves them
+ * ({@link resolvePostIdentity} — the pid-registry / env walk), so a `notify`
+ * run inside an agent session inherits that session with no flag. Outside a
+ * session (a human at a shell) identity is undefined: the ping still gets
+ * short-shaping and ticket linkification, just no session crumb.
+ */
+import { composeBroadcastMessage } from './feed-broadcast.js';
+import { resolvePostIdentity } from './feed-post.js';
+import { getSessionById, resolveFullSessionId } from './session/db.js';
+import { linearIssueUrl } from './session/linear.js';
+/**
+ * Shape a raw owner-send body into the composed broadcast message. Pure except
+ * for the identity/index reads that {@link resolvePostIdentity} /
+ * {@link getSessionById} already perform for feed posts.
+ */
+export function composeOwnerMessage(rawText, opts = {}) {
+    const identity = resolvePostIdentity({ sessionId: opts.sessionId });
+    // A footer crumb that would 404 (an 8-char short id) is upgraded to the full
+    // indexed id so the console URL resolves; a full/native id passes through.
+    const session = resolveFullSessionId(identity?.sessionId);
+    const ticket = session ? getSessionById(session)?.ticketId : undefined;
+    const ctx = {
+        ...(opts.title?.trim() ? { title: opts.title.trim() } : {}),
+        text: rawText,
+        level: 'important',
+        ...(ticket ? { ticket, ticketUrl: linearIssueUrl(ticket) } : {}),
+        ...(identity?.agent ? { agent: identity.agent } : {}),
+        ...(identity?.host ? { host: identity.host } : {}),
+        ...(session ? { session } : {}),
+    };
+    return composeBroadcastMessage(ctx);
+}

package/dist/lib/run-trace-sync.d.ts

@@ -7,7 +7,22 @@ export declare function shouldAutoSyncTraces(disabled: boolean): boolean;
  * Arm a fire-and-forget `agents traces sync` for when this process exits.
  * No-op unless {@link shouldAutoSyncTraces} passes. Best-effort by
  * construction: a missing binary or a stalled child never affects the run.
+ * The spawn happens in the exit handler because the upload is async work Node
+ * cannot run after `exit` — a watchdog here could never fire.
  */
 export declare function armRunFinishTraceSync(opts?: {
     disabled?: boolean;
 }): void;
+/**
+ * Fire a fire-and-forget `agents traces sync` NOW (not on exit). An important
+ * owner-bound ping (`feed post --level important`, `agents notify`,
+ * `send --to owner`) links the caller's `…/console/sessions/<id>` page, and that
+ * page only exists once the session's shard has been uploaded — trace sync fires
+ * on run exit (PHNX-3628), not when a mid-run ping is posted. This closes that
+ * gap so the tapped link resolves instead of 404ing. No-op unless
+ * {@link shouldAutoSyncTraces} passes (signed in + already opted into the store);
+ * the incremental watermark keeps the push to essentially just this session.
+ */
+export declare function fireTraceSyncInBackground(opts?: {
+    disabled?: boolean;
+}): void;