@phnx-labs/agents-cli 1.22.68 → 1.22.70

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/notify.d.ts

@@ -16,6 +16,7 @@
 import type { OpenBlock } from './feed/feed.js';
 import type { Meta } from './types.js';
 import type { SendResult } from './channels/registry.js';
+import { type SinkMessageFormat } from './sink-format.js';
 export interface OwnerNotifyOptions {
     /** Config source (defaults to `readMeta()`); lets callers/tests inject it. */
     meta?: Meta;
@@ -28,6 +29,16 @@ export interface OwnerNotifyOptions {
     thread?: string;
     attachments?: string[];
     from?: string;
+    /**
+     * Per-destination body composer (PHNX-3698). The owner policy fans one alert
+     * out to several channels (imessage + slack, …), and only Slack can render a
+     * labeled link — so when set, each destination gets the body shaped for its
+     * OWN resolved provider (Slack → `mrkdwn` `<url|label>` links, everything else
+     * → `plain` the human sentence, no URLs) instead of the single `text` going to
+     * every channel. Absent for callers whose body is already final (urgent
+     * blocks, monitor summaries): `text` is delivered verbatim to every channel.
+     */
+    composeForFormat?: (format: SinkMessageFormat) => string;
 }
 export interface NotifyResult {
     ok: boolean;

package/dist/lib/notify.js

@@ -3,6 +3,7 @@ import { getOwnerNotifyDestinationsFromHumans } from './humans.js';
 import { registerBuiltinProviders } from './channels/providers/index.js';
 import { lookupTransport } from './channels/resolve.js';
 import { forwardOwnerNotifyToPeer } from './channels/owner-forward.js';
+import { sinkMessageFormat } from './sink-format.js';
 export function formatUrgentBlockMessage(block) {
     const q = block.questions[0];
     const header = q?.header ? `[${q.header}] ` : '';
@@ -72,11 +73,20 @@ export async function sendToOwner(text, options = {}) {
     registerBuiltinProviders();
     const deliveries = [];
     for (const { channel, to: target } of addressable) {
-        const { provider, error } = lookupTransport(channel, meta);
+        const { provider, providerName, error } = lookupTransport(channel, meta);
+        // Each destination gets the body shaped for the provider it ACTUALLY
+        // delivers through (the same `notify.transports` remap `lookupTransport`
+        // applied), so a Slack destination turns its ticket keys + session crumb
+        // into `<url|label>` links while a sibling iMessage copy stays plain
+        // (PHNX-3698). Without a composer the caller's already-final `text` is used
+        // for every channel.
+        const body = options.composeForFormat
+            ? options.composeForFormat(sinkMessageFormat(providerName))
+            : text;
         let result;
         try {
             result = provider
-                ? await provider.send(text, {
+                ? await provider.send(body, {
                     target,
                     ownerScoped: options.target === undefined,
                     dryRun: options.dryRun,
@@ -99,12 +109,15 @@ export async function sendToOwner(text, options = {}) {
                 };
             }
             else {
-                result = await forwardOwnerNotifyToPeer(text, channel, target, meta, {
+                result = await forwardOwnerNotifyToPeer(body, channel, target, meta, {
                     envelope: { thread: options.thread, from: options.from },
                 }) ?? result;
             }
         }
-        deliveries.push(result);
+        // Echo the exact per-destination body delivered, so a caller (and
+        // `agents notify --dry-run --json`) can see Slack got the labeled-link
+        // variant and iMessage the plain one — the observable proof of PHNX-3698.
+        deliveries.push({ ...result, body });
     }
     if (deliveries.length === 1)
         return deliveries[0];

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

@@ -0,0 +1,55 @@
+/**
+ * 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 { type FeedBroadcastContext } from './feed-broadcast.js';
+import type { SinkMessageFormat } from './sink-format.js';
+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;
+    /**
+     * Rendering vocabulary for this body (PHNX-3698). Slack `mrkdwn` linkifies the
+     * ticket keys and the session crumb as `<url|label>`; `plain` (the default)
+     * keeps the human sentence with no URLs, for iMessage / owner-scoped rush.
+     * The owner fan-out passes one format per destination.
+     */
+    format?: SinkMessageFormat;
+}
+/**
+ * Resolve the run identity into the broadcast context an owner ping is built
+ * from — the shared shape a `feed post` uses. Pure except for the identity/index
+ * reads that {@link resolvePostIdentity} / {@link getSessionById} already perform
+ * for feed posts. Built ONCE so the owner fan-out can render it in more than one
+ * format (Slack vs iMessage) without re-walking the pid registry per destination.
+ */
+export declare function ownerMessageContext(rawText: string, opts?: OwnerMessageOptions): FeedBroadcastContext;
+/**
+ * Shape a raw owner-send body into the composed broadcast message. `format`
+ * decides how links surface — `plain` (default) for iMessage / owner-scoped rush,
+ * `mrkdwn` for a Slack owner destination (PHNX-3698).
+ */
+export declare function composeOwnerMessage(rawText: string, opts?: OwnerMessageOptions): string;
+/**
+ * A per-format composer bound to ONE resolved context — the shape the owner
+ * fan-out wants (PHNX-3698). `agents notify` / `agents send --to owner` build
+ * this once, use `compose('plain')` for the envelope's display body, and hand
+ * `compose` to `sendToOwner` so each policy destination re-renders in its own
+ * format without re-walking the pid registry.
+ */
+export declare function ownerMessageComposer(rawText: string, opts?: OwnerMessageOptions): (format: SinkMessageFormat) => string;

package/dist/lib/owner-message.js

@@ -0,0 +1,64 @@
+/**
+ * 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';
+/**
+ * Resolve the run identity into the broadcast context an owner ping is built
+ * from — the shared shape a `feed post` uses. Pure except for the identity/index
+ * reads that {@link resolvePostIdentity} / {@link getSessionById} already perform
+ * for feed posts. Built ONCE so the owner fan-out can render it in more than one
+ * format (Slack vs iMessage) without re-walking the pid registry per destination.
+ */
+export function ownerMessageContext(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;
+    return {
+        ...(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 } : {}),
+    };
+}
+/**
+ * Shape a raw owner-send body into the composed broadcast message. `format`
+ * decides how links surface — `plain` (default) for iMessage / owner-scoped rush,
+ * `mrkdwn` for a Slack owner destination (PHNX-3698).
+ */
+export function composeOwnerMessage(rawText, opts = {}) {
+    return composeBroadcastMessage(ownerMessageContext(rawText, opts), opts.format ?? 'plain');
+}
+/**
+ * A per-format composer bound to ONE resolved context — the shape the owner
+ * fan-out wants (PHNX-3698). `agents notify` / `agents send --to owner` build
+ * this once, use `compose('plain')` for the envelope's display body, and hand
+ * `compose` to `sendToOwner` so each policy destination re-renders in its own
+ * format without re-walking the pid registry.
+ */
+export function ownerMessageComposer(rawText, opts = {}) {
+    const ctx = ownerMessageContext(rawText, opts);
+    return (format) => composeBroadcastMessage(ctx, format);
+}

package/dist/lib/permissions-registry.d.ts

@@ -1,8 +1,6 @@
 import type { AgentId, PermissionSet } from './types.js';
 /** Canonical tool (lowercased) -> Grok's lowercase tool vocabulary. */
 export declare const GROK_TOOL_BY_CANONICAL: Record<string, string | undefined>;
-/** Canonical tool -> Kiro CLI v3 capability id. */
-export declare const KIRO_CAPABILITY_BY_TOOL: Record<string, string | undefined>;
 /** Canonical tool -> OpenClaw tool id (tool-level granularity only). */
 export declare const CANONICAL_TO_OPENCLAW_TOOL: Record<string, string>;
 /** Canonical tool -> Antigravity's action namespace. */

package/dist/lib/permissions-registry.js

@@ -7,7 +7,7 @@
  * behind `agents permissions add <path>` used to dispatch through hand-written
  * 3-arm switches while
  * `applyPermissionsToVersion` wrote 13 harnesses, so permissions were written
- * for cursor, antigravity, grok, kimi, droid, copilot, kiro, openclaw and
+ * for cursor, antigravity, grok, kimi, droid, copilot, openclaw and
  * hermes and then reported as absent for all ten (RUSH-2676).
  *
  * The key set is pinned to `capableAgents('allowlist')` by
@@ -24,7 +24,7 @@
  * ## Every reverse projection is lossy, and says how
  *
  * The forward direction discards information — several canonical tools collapse
- * onto one native id (`Read`/`Grep`/`Glob` all become Kiro's `fs_read`), and
+ * onto one native id (`Read`/`Grep`/`Glob` all become a coarse capability), and
  * pattern grammars differ (`git:*` becomes `git *`). Reading back therefore
  * recovers a permission set that GRANTS THE SAME ACCESS, not the byte-identical
  * strings that were written. Each target documents its own collapse. Callers that
@@ -45,21 +45,6 @@ export const GROK_TOOL_BY_CANONICAL = {
     grep: 'grep',
     webfetch: 'webfetch',
 };
-/** Canonical tool -> Kiro CLI v3 capability id. */
-export const KIRO_CAPABILITY_BY_TOOL = {
-    bash: 'shell',
-    read: 'fs_read',
-    grep: 'fs_read',
-    glob: 'fs_read',
-    write: 'fs_write',
-    edit: 'fs_write',
-    notebookedit: 'fs_write',
-    webfetch: 'web_fetch',
-    websearch: 'web_search',
-    mcp: 'mcp',
-    subagent: 'subagent',
-    skill: 'skill',
-};
 /** Canonical tool -> OpenClaw tool id (tool-level granularity only). */
 export const CANONICAL_TO_OPENCLAW_TOOL = {
     bash: 'exec',
@@ -81,7 +66,7 @@ export const ANTIGRAVITY_ACTION_BY_TOOL = {
  * native id. Several canonical tools collapse onto one native id, so the
  * inverse must pick a representative; declaration order in the forward table is
  * that choice, which is why `read` (declared before `grep`/`glob`) represents
- * Kiro's `fs_read`.
+ * a coarser native capability.
  */
 function invertFirstWins(forward) {
     const out = {};
@@ -94,7 +79,6 @@ function invertFirstWins(forward) {
     return out;
 }
 const CANONICAL_BY_GROK_TOOL = invertFirstWins(GROK_TOOL_BY_CANONICAL);
-const CANONICAL_BY_KIRO_CAPABILITY = invertFirstWins(KIRO_CAPABILITY_BY_TOOL);
 const CANONICAL_BY_OPENCLAW_TOOL = invertFirstWins(CANONICAL_TO_OPENCLAW_TOOL);
 const CANONICAL_BY_ANTIGRAVITY_ACTION = invertFirstWins(ANTIGRAVITY_ACTION_BY_TOOL);
 /** Filename Codex stores generated deny rules under `.codex/rules/`. */
@@ -585,37 +569,6 @@ export const PERMISSION_TARGETS = {
             return permissionSet(allow, []);
         },
     },
-    kiro: {
-        home: (h) => path.join(h, '.kiro', 'settings', 'permissions.yaml'),
-        lossyBecause: 'Read/Grep/Glob share fs_read and Write/Edit/NotebookEdit share fs_write',
-        toCanonical(configPath) {
-            const config = readYaml(configPath);
-            const rules = config?.rules;
-            if (!Array.isArray(rules))
-                return null;
-            const allow = [];
-            const deny = [];
-            for (const rule of rules) {
-                if (!rule || typeof rule !== 'object' || Array.isArray(rule))
-                    continue;
-                const r = rule;
-                if (typeof r.capability !== 'string')
-                    continue;
-                const lowerTool = CANONICAL_BY_KIRO_CAPABILITY[r.capability];
-                if (!lowerTool)
-                    continue;
-                const matches = stringList(r.match);
-                const canonicals = matches.length
-                    ? matches.map((m) => canonicalRule(lowerTool, lowerTool === 'bash' ? denormalizeBashPattern(m) : m))
-                    : [canonicalRule(lowerTool, null)];
-                if (r.effect === 'deny')
-                    deny.push(...canonicals);
-                else if (r.effect === 'allow')
-                    allow.push(...canonicals);
-            }
-            return permissionSet(allow, deny);
-        },
-    },
     openclaw: {
         home: (h) => path.join(h, '.openclaw', 'openclaw.json'),
         lossyBecause: 'OpenClaw gates whole tools, so only blanket rules were written and all read back as blanket',

package/dist/lib/permissions.d.ts

@@ -190,19 +190,6 @@ export type KimiRule = {
     decision: 'allow' | 'deny';
     pattern: string;
 };
-export type KiroRule = {
-    capability: string;
-    effect: 'allow' | 'deny';
-    match?: string[];
-    exclude?: string[];
-};
-/**
- * Convert canonical permissions to Kiro CLI v3 capability rules.
- * Kiro stores these rules in ~/.kiro/settings/permissions.yaml.
- */
-export declare function convertToKiroFormat(set: PermissionSet): {
-    rules: KiroRule[];
-};
 /**
  * Convert a canonical permission set to Kimi Code's `[permission].rules` format.
  * Kimi (`~/.kimi-code/config.toml`) reads rules of the form
@@ -264,7 +251,7 @@ export declare function convertToCodexFormat(set: PermissionSet, cwd?: string):
  * Every other allowlist-capable harness returns the canonical `PermissionSet`
  * that `PERMISSION_TARGETS` reads back. Before RUSH-2676 they returned `null`,
  * so permissions written for cursor, antigravity, grok, kimi, droid,
- * copilot, kiro, openclaw and hermes were reported as absent.
+ * copilot, openclaw and hermes were reported as absent.
  */
 export declare function readAgentPermissions(agentId: AgentId, scope?: 'user' | 'project', cwd?: string, options?: {
     home?: string;
@@ -315,8 +302,7 @@ export declare function exportPermissionsFromPath(filePath: string): PermissionS
 /**
  * Which harness owns `filePath`, by comparing against the trailing path segments
  * each registry target declares. Longer (more specific) suffixes win, so
- * `.kiro/settings/permissions.yaml` is never mistaken for a bare `permissions.yaml`.
- */
+  */
 export declare function detectPermissionAgentFromPath(filePath: string): AgentId | null;
 /**
  * Get the default permission set from central storage.
@@ -356,7 +342,7 @@ export declare function saveDefaultPermissionSet(set: PermissionSet): {
  * (`lossyBecause` in `permissions-registry.ts`), so a canonical subset check
  * would false-diff a correctly-synced home.
  *
- * Every other allowlist harness (codex/grok/kimi/kiro/antigravity/hermes/copilot)
+ * Every other allowlist harness (codex/grok/kimi/antigravity/hermes/copilot)
  * stores a lossy projection — a sandbox flag, whole-tool gate, per-directory
  * approval, or a split/merged pattern — with no faithful per-group provenance, so
  * doctor stays presence-only there and says so (`detail: 'format cannot verify

package/dist/lib/permissions.js

@@ -20,7 +20,7 @@ import { updateGeminiSettings } from './gemini-settings.js';
 // The canonical<->native tool vocabularies live in the registry, which also owns
 // the reverse projections — so the serializers below and the readers there can
 // never disagree about what `fs_read` or `developer__shell` means.
-import { ANTIGRAVITY_ACTION_BY_TOOL, CANONICAL_TO_OPENCLAW_TOOL, CODEX_RULES_FILENAME, stripJsonComments, GROK_TOOL_BY_CANONICAL, KIRO_CAPABILITY_BY_TOOL, PERMISSION_TARGETS, readCanonicalPermissions, } from './permissions-registry.js';
+import { ANTIGRAVITY_ACTION_BY_TOOL, CANONICAL_TO_OPENCLAW_TOOL, CODEX_RULES_FILENAME, stripJsonComments, GROK_TOOL_BY_CANONICAL, PERMISSION_TARGETS, readCanonicalPermissions, } from './permissions-registry.js';
 export { CODEX_RULES_FILENAME };
 const HOME = os.homedir();
 export const COMPUTER_PERMISSION_RULE_PREFIX = 'Computer';
@@ -799,43 +799,6 @@ function canonicalToGrokRule(perm, action) {
     }
     return { action, tool, pattern };
 }
-/**
- * Convert canonical permissions to Kiro CLI v3 capability rules.
- * Kiro stores these rules in ~/.kiro/settings/permissions.yaml.
- */
-export function convertToKiroFormat(set) {
-    const rules = [];
-    for (const perm of set.allow) {
-        const rule = canonicalToKiroRule(perm, 'allow');
-        if (rule)
-            rules.push(rule);
-    }
-    for (const perm of set.deny ?? []) {
-        const rule = canonicalToKiroRule(perm, 'deny');
-        if (rule)
-            rules.push(rule);
-    }
-    return { rules };
-}
-function canonicalToKiroRule(perm, effect) {
-    if (BLANKET_BASH_FORMS.has(perm)) {
-        return { capability: 'shell', effect };
-    }
-    const parsed = parseCanonicalPreserveCase(perm);
-    const capability = KIRO_CAPABILITY_BY_TOOL[parsed.tool.toLowerCase()];
-    if (!capability)
-        return null;
-    if (parsed.pattern === null || parsed.pattern === '*' || parsed.pattern === '**') {
-        return { capability, effect };
-    }
-    const lowerTool = parsed.tool.toLowerCase();
-    const pattern = lowerTool === 'bash'
-        ? normalizeBashPattern(parsed.pattern)
-        : (lowerTool === 'webfetch' || lowerTool === 'websearch') && parsed.pattern.startsWith('domain:')
-            ? parsed.pattern.slice('domain:'.length)
-            : parsed.pattern;
-    return { capability, effect, match: [pattern] };
-}
 /**
  * Parse a canonical permission string preserving the tool's original casing.
  * `parseCanonicalPattern` lowercases the tool name, which is fine for Grok
@@ -1147,7 +1110,7 @@ function readCodexPermissions(scope = 'user', cwd, options) {
  * Every other allowlist-capable harness returns the canonical `PermissionSet`
  * that `PERMISSION_TARGETS` reads back. Before RUSH-2676 they returned `null`,
  * so permissions written for cursor, antigravity, grok, kimi, droid,
- * copilot, kiro, openclaw and hermes were reported as absent.
+ * copilot, openclaw and hermes were reported as absent.
  */
 export function readAgentPermissions(agentId, scope = 'user', cwd, options) {
     switch (agentId) {
@@ -1598,37 +1561,6 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
             return { success: true };
         }
-        if (agentId === 'kiro') {
-            const permissionsPath = path.join(versionHome, '.kiro', 'settings', 'permissions.yaml');
-            let config = {};
-            if (fs.existsSync(permissionsPath)) {
-                const parsed = yaml.parse(fs.readFileSync(permissionsPath, 'utf-8'));
-                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-                    config = parsed;
-                }
-            }
-            const newRules = convertToKiroFormat(set).rules;
-            if (merge) {
-                const existingRules = Array.isArray(config.rules) ? config.rules : [];
-                const seen = new Set();
-                config.rules = [...existingRules, ...newRules].filter((rule) => {
-                    if (!rule || typeof rule !== 'object' || Array.isArray(rule))
-                        return false;
-                    const record = rule;
-                    const key = `${String(record.effect)}|${String(record.capability)}|${JSON.stringify(record.match ?? [])}|${JSON.stringify(record.exclude ?? [])}`;
-                    if (seen.has(key))
-                        return false;
-                    seen.add(key);
-                    return true;
-                });
-            }
-            else {
-                config.rules = newRules;
-            }
-            fs.mkdirSync(path.dirname(permissionsPath), { recursive: true });
-            fs.writeFileSync(permissionsPath, yaml.stringify(config), 'utf-8');
-            return { success: true };
-        }
         if (agentId === 'openclaw') {
             // OpenClaw's allowlist lives in ~/.openclaw/openclaw.json under `tools`.
             // Only blanket tool-level rules map (see convertToOpenClawFormat). We
@@ -1788,8 +1720,7 @@ export function exportPermissionsFromPath(filePath) {
 /**
  * Which harness owns `filePath`, by comparing against the trailing path segments
  * each registry target declares. Longer (more specific) suffixes win, so
- * `.kiro/settings/permissions.yaml` is never mistaken for a bare `permissions.yaml`.
- */
+  */
 export function detectPermissionAgentFromPath(filePath) {
     const normalized = path.resolve(filePath).split(path.sep).join('/');
     let best = null;
@@ -1906,7 +1837,7 @@ export function saveDefaultPermissionSet(set) {
  * (`lossyBecause` in `permissions-registry.ts`), so a canonical subset check
  * would false-diff a correctly-synced home.
  *
- * Every other allowlist harness (codex/grok/kimi/kiro/antigravity/hermes/copilot)
+ * Every other allowlist harness (codex/grok/kimi/antigravity/hermes/copilot)
  * stores a lossy projection — a sandbox flag, whole-tool gate, per-directory
  * approval, or a split/merged pattern — with no faithful per-group provenance, so
  * doctor stays presence-only there and says so (`detail: 'format cannot verify

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;

package/dist/lib/run-trace-sync.js

@@ -45,33 +45,55 @@ export function shouldAutoSyncTraces(disabled) {
         return false; // never opted into the traces store
     return true;
 }
+/**
+ * Spawn a detached, unref'd `agents traces sync` and return immediately. The one
+ * place the fire-and-forget child is built, shared by the run-exit arm and the
+ * feed/notify important-post trigger.
+ *
+ * Re-invoke this CLI through getCliLaunch, NOT a hand-rolled
+ * [process.execPath, process.argv[1], …] — under the compiled standalone binary
+ * argv[1] is the bun virtual entry (/$bunfs/root/agents), which would become a
+ * bogus subcommand and silently no-op the whole feature (cli-entry.ts). The
+ * spawned `traces sync` is a fresh process with its own event loop, so its own
+ * per-request network timeouts (syncTraces) bound it.
+ */
+function spawnDetachedTraceSync() {
+    try {
+        const { command, args } = getCliLaunch(['traces', 'sync']);
+        const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+        // A child that never starts (ENOENT) emits an async 'error'; without a
+        // listener Node re-throws it as uncaught. Swallow — this is best-effort.
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // A synchronous spawn failure must never change the caller's outcome.
+    }
+}
 /**
  * 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 function armRunFinishTraceSync(opts = {}) {
     if (!shouldAutoSyncTraces(!!opts.disabled))
         return;
-    process.on('exit', () => {
-        try {
-            // Re-invoke this CLI through getCliLaunch, NOT a hand-rolled
-            // [process.execPath, process.argv[1], …] — under the compiled standalone
-            // binary argv[1] is the bun virtual entry (/$bunfs/root/agents), which
-            // would become a bogus subcommand and silently no-op the whole feature
-            // (cli-entry.ts). The spawned `traces sync` is a fresh process with its
-            // own event loop, so its own per-request network timeouts (syncTraces)
-            // bound it — a watchdog here could never fire anyway (Node runs no loop
-            // after an 'exit' handler returns), so we do not pretend to add one.
-            const { command, args } = getCliLaunch(['traces', 'sync']);
-            const child = spawn(command, args, { detached: true, stdio: 'ignore' });
-            // A child that never starts (ENOENT) emits an async 'error'; without a
-            // listener Node re-throws it as uncaught. Swallow — this is best-effort.
-            child.on('error', () => { });
-            child.unref();
-        }
-        catch {
-            // A synchronous spawn failure must never change the run's exit outcome.
-        }
-    });
+    process.on('exit', spawnDetachedTraceSync);
+}
+/**
+ * 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 function fireTraceSyncInBackground(opts = {}) {
+    if (!shouldAutoSyncTraces(!!opts.disabled))
+        return;
+    spawnDetachedTraceSync();
 }

package/dist/lib/rush-session.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Rush session freshness — the ONE judgment shared by every consumer of
+ * ~/.rush/user.yaml (cloud dispatch, cloud session source, secrets sync driver).
+ *
+ * A Rush session stores `expires_at` as Unix seconds. Two values mean "never
+ * expires" and MUST NOT be read as an absolute timestamp:
+ *   - `0`         — an opaque Phoenix `pid_` bearer written by `rush login`;
+ *                   `0` = non-expiring by contract (mirrors rush/cli's isFresh,
+ *                   the same fix RUSH-1310 landed for the daemon-less freshness
+ *                   check and PHNX-3637 landed for the release endpoints).
+ *   - `undefined` — a token written without an expiry.
+ *
+ * Reading `expires_at: 0` as epoch-1970 was PHNX-3645: every Phoenix-authed box
+ * had its valid, non-expiring session rejected as "Rush session expired at
+ * 1970-01-01", so `agents run --cloud`, `agents secrets push/pull` over Rush,
+ * and cloud session discovery all refused to run. Every consumer that parses
+ * freshness routes through this predicate so the special-case lives in one place.
+ */
+export declare function isRushSessionExpired(expiresAt: number | undefined): boolean;

package/dist/lib/rush-session.js

@@ -0,0 +1,24 @@
+/**
+ * Rush session freshness — the ONE judgment shared by every consumer of
+ * ~/.rush/user.yaml (cloud dispatch, cloud session source, secrets sync driver).
+ *
+ * A Rush session stores `expires_at` as Unix seconds. Two values mean "never
+ * expires" and MUST NOT be read as an absolute timestamp:
+ *   - `0`         — an opaque Phoenix `pid_` bearer written by `rush login`;
+ *                   `0` = non-expiring by contract (mirrors rush/cli's isFresh,
+ *                   the same fix RUSH-1310 landed for the daemon-less freshness
+ *                   check and PHNX-3637 landed for the release endpoints).
+ *   - `undefined` — a token written without an expiry.
+ *
+ * Reading `expires_at: 0` as epoch-1970 was PHNX-3645: every Phoenix-authed box
+ * had its valid, non-expiring session rejected as "Rush session expired at
+ * 1970-01-01", so `agents run --cloud`, `agents secrets push/pull` over Rush,
+ * and cloud session discovery all refused to run. Every consumer that parses
+ * freshness routes through this predicate so the special-case lives in one place.
+ */
+export function isRushSessionExpired(expiresAt) {
+    // `0` (non-expiring pid_ bearer) and a missing value are never expired.
+    if (typeof expiresAt !== 'number' || expiresAt === 0)
+        return false;
+    return expiresAt <= Date.now() / 1000;
+}

package/dist/lib/secrets/drivers/rush.js

@@ -13,6 +13,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
+import { isRushSessionExpired } from '../../rush-session.js';
 const PROXY_BASE = 'https://api.prix.dev';
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
 const BUNDLE_ENDPOINT = '/api/v1/secrets/bundles';
@@ -27,7 +28,7 @@ function readRushToken() {
         throw new Error('No session token in ~/.rush/user.yaml. Run `rush login` first.');
     }
     const expiresAt = data.session?.expires_at;
-    if (typeof expiresAt === 'number' && expiresAt <= Date.now() / 1000) {
+    if (isRushSessionExpired(expiresAt)) {
         const expiredAt = new Date(expiresAt * 1000).toISOString();
         throw new Error(`Rush session expired at ${expiredAt}. Run \`rush login\` to refresh.`);
     }