@phnx-labs/agents-cli 1.22.60 → 1.22.62

package/dist/lib/doctor-diff.js

@@ -9,21 +9,44 @@
  *   - missing  — resolved source exists, not present in home
  *   - extra    — present in home, no source in any layer
  *
- * Coverage:
+ * Coverage — every kind `syncResourcesToVersion` writes is content-aware, so a
+ * byte change under an unchanged name is `diff`, never a false `ok` (PHNX-3504):
  *   commands, skills, hooks, rules — full content compare with source layer.
- *   mcp, permissions, subagents, plugins, promptcuts — presence-only.
+ *   mcp        — structural compare of the home server def vs resolved source.
+ *   subagents  — re-render source through the registry transform, byte-compare.
+ *   workflows  — layout-aware per-harness content compare (dir tree or file).
+ *   memory     — knowledge facts (~/.agents/memory/*.md), per-fact byte-compare.
+ *   plugins    — per-item content compare of the marketplace mirror.
+ *   permissions — per-rule compare in the harness's native vocabulary for the
+ *     representable harnesses (claude/opencode/cursor/droid/openclaw); the lossy
+ *     TOML/flag harnesses stay presence-only with an honest `detail`, never a
+ *     faked `ok`.
+ * A completeness test binds `DOCTOR_ALL_KINDS` to the writer set so a future
+ * synced kind cannot silently become a blind spot. `promptcuts` is NOT a kind —
+ * it is not version-scoped, so there is nothing per-home to diff.
  *
  * Intentional asymmetries (must mirror sync):
  *   - hooks ignore the project layer (`syncResourcesToVersion` skips
  *     project/.agents/hooks/ for safety).
- *   - rules/AGENTS.md on agents without native @-import support is compared
- *     against the compiled artifact, not the raw source file.
+ *   - rules/AGENTS.md is compared against the preset composition the rules writer
+ *     emits (`composeRulesFromState`), re-rendered from the current `subrules/`
+ *     fragments — so a fragment edit is caught even though `rules/AGENTS.md`
+ *     never changed. A non-@-import home compiled by `agents refresh-rules`
+ *     carries a leading `COMPILED_HEADER`, which is stripped before comparing so
+ *     a header-compiled home still reconciles (the header is not source content).
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { AGENTS, agentConfigDirName } from './agents.js';
-import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getEffectivePromptcutsPath, getActiveRulesPreset, } from './state.js';
+import { AGENTS, agentConfigDirName, getMcpConfigPathForHome } from './agents.js';
+import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getActiveRulesPreset, } from './state.js';
 import { composeRulesFromState } from './rules/compose.js';
+import { COMPILED_HEADER, supportsRulesImports } from './rules/compile.js';
+import { dirsContentMatch, filesContentMatch } from './resource-content-diff.js';
+import { subagentContentMatches } from './subagents-registry.js';
+import { getMcpServersByName, mcpServerMatches } from './mcp.js';
+import { permissionsGroupMatches, PERMISSIONS_REPRESENTABLE } from './permissions.js';
+import { workflowContentMatches, resolveWorkflowRef } from './workflows.js';
+import { listMemoryFacts, memoryTargetDir } from './memory.js';
 import { getAvailableResources, getActuallySyncedResources, getVersionHomePath, compareVersions, } from './installations/versions.js';
 import { discoverPlugins, marketplaceSpecForName } from './plugins/plugins.js';
 import { pluginInstallDir, repairableManifestFields } from './plugins/plugin-marketplace.js';
@@ -47,7 +70,8 @@ const ALL_KINDS = [
     'permissions',
     'subagents',
     'plugins',
-    'promptcuts',
+    'workflows',
+    'memory',
 ];
 function normalize(content) {
     return content.replace(/\r\n/g, '\n').trim();
@@ -121,6 +145,36 @@ function buildLayerBases(cwd, kind, opts = {}) {
         out.push({ layer: 'extra', path: path.join(e.dir, kind), alias: e.alias });
     return out;
 }
+/**
+ * Resolve directory-shaped source resources of `kind` by name across the layers
+ * (project > user > system > extra; first layer wins a name collision), keeping
+ * only entries whose directory satisfies `predicate` (e.g. holds `AGENT.md`).
+ */
+function resolveSourceDirsByName(kind, cwd, excludeProject, predicate) {
+    const out = new Map();
+    for (const base of buildLayerBases(cwd, kind, { excludeProject })) {
+        if (!fs.existsSync(base.path))
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(base.path, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            if (out.has(entry.name))
+                continue;
+            const dir = path.join(base.path, entry.name);
+            if (!predicate(dir))
+                continue;
+            out.set(entry.name, { layer: base.layer, path: dir, alias: base.alias });
+        }
+    }
+    return out;
+}
 // ─── commands ─────────────────────────────────────────────────────────────────
 function diffCommands(agent, version, cwd, excludeProject = false) {
     const agentConfig = AGENTS[agent];
@@ -265,55 +319,6 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
 // ─── skills ───────────────────────────────────────────────────────────────────
-function dirsContentMatch(src, dst) {
-    const ignore = new Set(['.DS_Store', '.git', '.gitignore', '.venv', '__pycache__', 'node_modules']);
-    const srcEntries = (() => {
-        try {
-            return fs.readdirSync(src, { withFileTypes: true });
-        }
-        catch {
-            return null;
-        }
-    })();
-    const dstEntries = (() => {
-        try {
-            return fs.readdirSync(dst, { withFileTypes: true });
-        }
-        catch {
-            return null;
-        }
-    })();
-    if (!srcEntries || !dstEntries)
-        return false;
-    const filter = (es) => es.filter((e) => !e.isSymbolicLink() && !ignore.has(e.name)).sort((a, b) => a.name.localeCompare(b.name));
-    const srcF = filter(srcEntries);
-    const dstF = filter(dstEntries);
-    if (srcF.length !== dstF.length)
-        return false;
-    for (let i = 0; i < srcF.length; i++) {
-        if (srcF[i].name !== dstF[i].name)
-            return false;
-        const a = path.join(src, srcF[i].name);
-        const b = path.join(dst, dstF[i].name);
-        if (srcF[i].isDirectory()) {
-            if (!dstF[i].isDirectory())
-                return false;
-            if (!dirsContentMatch(a, b))
-                return false;
-        }
-        else if (srcF[i].isFile()) {
-            if (!dstF[i].isFile())
-                return false;
-            const ac = readSafe(a);
-            const bc = readSafe(b);
-            if (ac == null || bc == null)
-                return false;
-            if (normalize(ac) !== normalize(bc))
-                return false;
-        }
-    }
-    return true;
-}
 function diffSkills(agent, version, cwd, excludeProject = false) {
     // Native ~/.agents/skills consumers (Gemini, …) read central skills directly.
     // The orchestrator DELETES their version-home skills dir (syncResourcesToVersion)
@@ -523,11 +528,18 @@ function diffRules(agent, version, cwd, excludeProject = false) {
             continue;
         }
         const expected = expectedRuleContent(agent, name, version, src.path);
-        const actual = readSafe(homePath);
+        let actual = readSafe(homePath);
         if (expected == null || actual == null) {
             rows.push({ kind: 'rules', name, status: 'diff', source: src.layer, sourcePath: src.path, homePath });
             continue;
         }
+        // A non-@-import home compiled by `agents refresh-rules` carries a leading
+        // COMPILED_HEADER the raw preset composition does not. Strip it before the
+        // compare so a header-compiled home still reconciles — the header is
+        // agents-cli provenance, not source content (PHNX-3504).
+        if (name === 'AGENTS' && !supportsRulesImports(agent) && actual.startsWith(COMPILED_HEADER)) {
+            actual = actual.slice(COMPILED_HEADER.length);
+        }
         rows.push({
             kind: 'rules',
             name,
@@ -555,22 +567,175 @@ function diffRules(agent, version, cwd, excludeProject = false) {
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
-// ─── presence-only kinds ──────────────────────────────────────────────────────
-function diffPresenceOnly(kind, available, synced) {
+// ─── mcp (content-aware) ────────────────────────────────────────────────────
+function diffMcp(agent, version, cwd, available, synced) {
+    const versionHome = getVersionHomePath(agent, version);
+    const syncedSet = new Set(synced);
     const availableSet = new Set(available);
+    const homePath = getMcpConfigPathForHome(agent, versionHome);
+    // Resolve each available server's source def once (project trust off — this is
+    // a read-only diff, and the writer applies the same servers).
+    const sourceByName = new Map(getMcpServersByName(available, { cwd, enforceProjectTrust: false }).map((s) => [s.name, s]));
+    const rows = [];
+    for (const name of available) {
+        if (!syncedSet.has(name)) {
+            rows.push({ kind: 'mcp', name, status: 'missing', sourcePath: sourceByName.get(name)?.path });
+            continue;
+        }
+        const source = sourceByName.get(name);
+        const matches = source ? mcpServerMatches(agent, versionHome, name, source.config) : false;
+        rows.push({
+            kind: 'mcp',
+            name,
+            status: matches ? 'ok' : 'diff',
+            sourcePath: source?.path,
+            homePath,
+        });
+    }
+    for (const name of synced) {
+        if (!availableSet.has(name))
+            rows.push({ kind: 'mcp', name, status: 'extra', homePath });
+    }
+    return rows.sort((a, b) => a.name.localeCompare(b.name));
+}
+// ─── permissions (content-aware where the native format allows) ──────────────
+function diffPermissions(agent, version, available, synced) {
+    const versionHome = getVersionHomePath(agent, version);
     const syncedSet = new Set(synced);
+    const availableSet = new Set(available);
+    const representable = PERMISSIONS_REPRESENTABLE.has(agent);
     const rows = [];
     for (const name of available) {
+        if (!syncedSet.has(name)) {
+            rows.push({ kind: 'permissions', name, status: 'missing' });
+            continue;
+        }
+        if (representable) {
+            const matches = permissionsGroupMatches(agent, versionHome, name);
+            rows.push({ kind: 'permissions', name, status: matches ? 'ok' : 'diff' });
+        }
+        else {
+            // Lossy TOML/flag harness — the on-disk format carries no faithful
+            // per-group rule provenance, so we can only attest presence. Say so
+            // explicitly rather than fake a verified `ok` (PHNX-3504).
+            rows.push({ kind: 'permissions', name, status: 'ok', detail: 'format cannot verify content' });
+        }
+    }
+    for (const name of synced) {
+        if (!availableSet.has(name))
+            rows.push({ kind: 'permissions', name, status: 'extra' });
+    }
+    return rows.sort((a, b) => a.name.localeCompare(b.name));
+}
+// ─── subagents (content-aware) ───────────────────────────────────────────────
+function diffSubagents(agent, version, cwd, available, synced) {
+    const versionHome = getVersionHomePath(agent, version);
+    const syncedSet = new Set(synced);
+    const availableSet = new Set(available);
+    // Resolve sources across the SAME layers `available` was built from
+    // (getAvailableResources is project-inclusive), so every available name finds
+    // its source dir for the content compare rather than false-diffing.
+    const sourceByName = resolveSourceDirsByName('subagents', cwd, false, (dir) => fs.existsSync(path.join(dir, 'AGENT.md')));
+    const rows = [];
+    for (const name of available) {
+        const src = sourceByName.get(name);
+        if (!syncedSet.has(name)) {
+            rows.push({ kind: 'subagents', name, status: 'missing', source: src?.layer, sourcePath: src?.path });
+            continue;
+        }
+        const matches = src ? subagentContentMatches(agent, versionHome, name, src.path) : false;
         rows.push({
-            kind,
+            kind: 'subagents',
             name,
-            status: syncedSet.has(name) ? 'ok' : 'missing',
+            status: matches ? 'ok' : 'diff',
+            source: src?.layer,
+            sourcePath: src?.path,
         });
     }
     for (const name of synced) {
-        if (availableSet.has(name))
+        if (!availableSet.has(name))
+            rows.push({ kind: 'subagents', name, status: 'extra' });
+    }
+    return rows.sort((a, b) => a.name.localeCompare(b.name));
+}
+// ─── workflows (content-aware) ───────────────────────────────────────────────
+function diffWorkflows(agent, version, cwd, available, synced) {
+    const versionHome = getVersionHomePath(agent, version);
+    const syncedSet = new Set(synced);
+    const availableSet = new Set(available);
+    const rows = [];
+    for (const name of available) {
+        const sourcePath = resolveWorkflowRef(name, cwd);
+        if (!syncedSet.has(name)) {
+            rows.push({ kind: 'workflows', name, status: 'missing', sourcePath: sourcePath ?? undefined });
             continue;
-        rows.push({ kind, name, status: 'extra' });
+        }
+        const matches = sourcePath ? workflowContentMatches(agent, versionHome, name, sourcePath) : false;
+        rows.push({
+            kind: 'workflows',
+            name,
+            status: matches ? 'ok' : 'diff',
+            sourcePath: sourcePath ?? undefined,
+        });
+    }
+    for (const name of synced) {
+        if (!availableSet.has(name))
+            rows.push({ kind: 'workflows', name, status: 'extra' });
+    }
+    return rows.sort((a, b) => a.name.localeCompare(b.name));
+}
+// ─── memory (knowledge facts — content-aware) ────────────────────────────────
+/**
+ * Diff synced knowledge-fact memory (~/.agents/memory/*.md fanned into each
+ * capable home under `memoryTargetDir`). Distinct from the rules-preset list
+ * that overloads `AvailableResources.memory` — this reads the canonical facts
+ * (`listMemoryFacts`) and the home copies bounded by the `.agents-cli-memory.json`
+ * manifest, so an untracked native memory file the user authored is never
+ * mistaken for drift (PHNX-3504).
+ */
+function diffMemory(agent, version, cwd) {
+    if (!supports(agent, 'memory', version).ok)
+        return [];
+    const versionHome = getVersionHomePath(agent, version);
+    const targetDir = path.join(versionHome, memoryTargetDir(agent));
+    const facts = listMemoryFacts(cwd);
+    // The manifest names exactly the fact files agents-cli wrote (plus 'MEMORY').
+    const managedManifestPath = path.join(targetDir, '.agents-cli-memory.json');
+    let managed = [];
+    try {
+        const raw = JSON.parse(fs.readFileSync(managedManifestPath, 'utf-8'));
+        if (Array.isArray(raw.facts))
+            managed = raw.facts.filter((f) => typeof f === 'string');
+    }
+    catch { /* no manifest → nothing managed yet */ }
+    const managedSet = new Set(managed);
+    const rows = [];
+    const factNames = new Set(facts.map((f) => f.name));
+    for (const fact of facts) {
+        const homePath = path.join(targetDir, `${fact.name}.md`);
+        if (!fs.existsSync(homePath)) {
+            rows.push({ kind: 'memory', name: fact.name, status: 'missing', source: fact.layer, sourcePath: fact.path });
+            continue;
+        }
+        const matches = filesContentMatch(fact.path, homePath);
+        rows.push({
+            kind: 'memory',
+            name: fact.name,
+            status: matches ? 'ok' : 'diff',
+            source: fact.layer,
+            sourcePath: fact.path,
+            homePath,
+        });
+    }
+    // A managed fact still on disk but no longer in the canonical set is an orphan
+    // the next sync would prune — surface it as extra. Never flag 'MEMORY' (the
+    // index, always regenerated) or an unmanaged native file (not ours to reconcile).
+    for (const name of managedSet) {
+        if (name === 'MEMORY' || factNames.has(name))
+            continue;
+        const homePath = path.join(targetDir, `${name}.md`);
+        if (fs.existsSync(homePath))
+            rows.push({ kind: 'memory', name, status: 'extra', homePath });
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -683,12 +848,6 @@ function diffPlugins(agent, version, cwd) {
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
-function diffPromptcuts() {
-    const sourcePath = getEffectivePromptcutsPath();
-    if (!fs.existsSync(sourcePath))
-        return [];
-    return [{ kind: 'promptcuts', name: 'promptcuts.yaml', status: 'ok', sourcePath }];
-}
 export function diffVersionResources(agent, version, options = {}) {
     const rawCwd = options.cwd ?? process.cwd();
     const excludeProject = options.excludeProject ?? false;
@@ -709,7 +868,8 @@ export function diffVersionResources(agent, version, options = {}) {
         permissions: [],
         subagents: [],
         plugins: [],
-        promptcuts: [],
+        workflows: [],
+        memory: [],
     };
     if (requested.has('commands'))
         empty.commands = diffCommands(agent, version, cwd, excludeProject);
@@ -725,20 +885,26 @@ export function diffVersionResources(agent, version, options = {}) {
     if (requested.has('rules'))
         empty.rules = diffRules(agent, version, cwd, excludeProject);
     if (requested.has('mcp'))
-        empty.mcp = diffPresenceOnly('mcp', available.mcp, synced.mcp);
-    if (requested.has('permissions'))
-        empty.permissions = diffPresenceOnly('permissions', available.permissions, synced.permissions);
+        empty.mcp = diffMcp(agent, version, cwd, available.mcp, synced.mcp);
+    if (requested.has('permissions')) {
+        empty.permissions = diffPermissions(agent, version, supports(agent, 'allowlist', version).ok ? available.permissions : [], synced.permissions);
+    }
     // Subagents are version-gated (e.g. kimi >= 0.29.0). A version below the floor
     // is never written any subagent by the sync writer, so counting the source
     // ones as "missing" is phantom drift no sync can clear (PHNX-3186). Zero the
     // available set when unsupported; a stale installed copy still surfaces `extra`.
     if (requested.has('subagents')) {
-        empty.subagents = diffPresenceOnly('subagents', supports(agent, 'subagents', version).ok ? available.subagents : [], synced.subagents);
+        empty.subagents = diffSubagents(agent, version, cwd, supports(agent, 'subagents', version).ok ? available.subagents : [], synced.subagents);
     }
     if (requested.has('plugins'))
         empty.plugins = diffPlugins(agent, version, cwd);
-    if (requested.has('promptcuts'))
-        empty.promptcuts = diffPromptcuts();
+    // Workflows are version-gated too (e.g. grok >= 0.2.111); zero the available
+    // set below the floor so a source workflow is not phantom-missing drift.
+    if (requested.has('workflows')) {
+        empty.workflows = diffWorkflows(agent, version, cwd, supports(agent, 'workflows', version).ok ? available.workflows : [], synced.workflows);
+    }
+    if (requested.has('memory'))
+        empty.memory = diffMemory(agent, version, cwd);
     let ok = 0, diff = 0, missing = 0, extra = 0;
     for (const list of Object.values(empty)) {
         for (const r of list) {

package/dist/lib/feed/events.d.ts

@@ -13,7 +13,7 @@
  */
 import type { ActorKind } from '../actor.js';
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'run.dispatched' | 'daemon.start' | 'daemon.stop' | 'daemon.error' | 'daemon.info' | 'routine.start' | 'routine.end' | 'watchdog.action' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'computer.action' | 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view' | 'secrets.lease-denied' | 'secrets.lease-expire' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'webhook.received' | 'webhook.authorized' | 'webhook.rejected' | 'webhook.matched' | 'webhook.fired' | 'webhook.failed' | 'webhook.handler.start' | 'webhook.handler.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'factory.command' | 'factory.action' | 'factory.uri' | 'factory.launch' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'run.dispatched' | 'daemon.start' | 'daemon.stop' | 'daemon.error' | 'daemon.info' | 'routine.start' | 'routine.end' | 'watchdog.action' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'computer.action' | 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view' | 'secrets.lease-denied' | 'secrets.lease-expire' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'rotation.unresolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'webhook.received' | 'webhook.authorized' | 'webhook.rejected' | 'webhook.matched' | 'webhook.fired' | 'webhook.failed' | 'webhook.handler.start' | 'webhook.handler.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'factory.command' | 'factory.action' | 'factory.uri' | 'factory.launch' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
 /** Every known event kind. Derived from {@link EVENT_TYPE_TABLE}, never hand-listed. */
 export declare const EVENT_TYPES: readonly EventType[];
 /** Runtime guard for an event kind arriving from outside this process. */

package/dist/lib/feed/events.js

@@ -19,25 +19,33 @@ import { gzipSync, gunzipSync } from 'node:zlib';
 import { ensureLockTarget, withFileLock } from '../fs-atomic.js';
 import { getUserAgentsDir } from '../state.js';
 import { stampProvenance, resetEventProvenanceForTest } from '../event-provenance.js';
-/** Lazy perf warehouse write — avoids a hard cycle at module load. */
+import { recordSample } from '../perf/spool.js';
+/**
+ * Perf warehouse write. SYNCHRONOUS by design (PHNX-3497): `recordSample` is an
+ * `appendFileSync` that never opens SQLite (see perf/spool.ts), so calling it
+ * directly costs one file append and lands the row before this function returns.
+ * It MUST NOT be deferred behind a `void import().then(...)`: the `agent.run`
+ * timer ends at the very tail of `agents run`, and the CLI process exits before
+ * any deferred microtask runs — so a fire-and-forget spool write was silently
+ * lost on every foreground run, leaving the PHNX-3468 startup-phase surface with
+ * no data. (Hooks were unaffected only because their shim appends the spool line
+ * synchronously in bash.)
+ */
 function recordPerfTiming(payload) {
     try {
         const phases = payload.phases && Object.keys(payload.phases).length > 0 ? payload.phases : undefined;
         const metaJson = phases ? JSON.stringify({ phases }) : undefined;
-        // Dynamic import keeps events.ts free of a load-time dependency on perf/db.
-        void import('../perf/spool.js').then(({ recordSample }) => {
-            recordSample({
-                kind: 'perf.timing',
-                label: payload.label,
-                durationMs: payload.durationMs,
-                status: payload.status,
-                agent: payload.agent,
-                agentVersion: payload.version,
-                sessionId: payload.sessionId,
-                cwd: payload.cwd,
-                metaJson,
-            });
-        }).catch(() => { });
+        recordSample({
+            kind: 'perf.timing',
+            label: payload.label,
+            durationMs: payload.durationMs,
+            status: payload.status,
+            agent: payload.agent,
+            agentVersion: payload.version,
+            sessionId: payload.sessionId,
+            cwd: payload.cwd,
+            metaJson,
+        });
     }
     catch {
         // fail soft
@@ -127,6 +135,7 @@ const EVENT_TYPE_TABLE = {
     'mcp.add': true, 'mcp.remove': true, 'mcp.register': true,
     'resource.sync': true,
     'rotation.resolved': true,
+    'rotation.unresolved': true,
     'command.start': true, 'command.end': true,
     'perf.timing': true,
     'session.start': true, 'session.end': true,
@@ -156,7 +165,7 @@ const AUDIT_EVENTS = new Set([
     'version.install', 'version.switch', 'version.remove',
     'skill.install', 'skill.remove',
     'mcp.add', 'mcp.remove', 'mcp.register',
-    'rotation.resolved',
+    'rotation.resolved', 'rotation.unresolved',
     'session.start', 'session.end',
     // Daemon lifecycle (always-on process start/stop/error is audit-relevant).
     // browser.* / computer.action stay info — they are already on the event stream;

package/dist/lib/feed-broadcast.js

@@ -36,8 +36,8 @@
 import { spawnSync } from 'child_process';
 import { isOwnerAlias, readOwnerDest, resolveSendEnvelope, deliverEnvelope } from './channels/send.js';
 import { lookupTransport } from './channels/resolve.js';
-import { forwardOwnerNotifyToPeer } from './channels/owner-forward.js';
 import { registerBuiltinProviders } from './channels/providers/index.js';
+import { sendToOwner } from './notify.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) {
@@ -462,6 +462,10 @@ async function runChannelSink(sink, meta) {
     // for a name that is, in fact, registered.
     registerBuiltinProviders();
     const owner = isOwnerAlias(sink.channel);
+    if (owner) {
+        const result = await sendToOwner(sink.text ?? '', { meta });
+        return { name, ok: result.ok, ...(result.error ? { error: result.error } : {}) };
+    }
     const resolved = resolveSendEnvelope({
         text: sink.text ?? '',
         channel: owner ? undefined : sink.channel,
@@ -476,17 +480,6 @@ async function runChannelSink(sink, meta) {
     const result = await deliverEnvelope(resolved.envelope, meta);
     if (result.ok)
         return { name, ok: true };
-    // The owner sink failed locally. When this box structurally cannot reach the
-    // owner (the rush-backed channel is macOS-only, so a headless Linux worker can
-    // never ring the phone — PHNX-3303), hand the delivery to a capable fleet peer
-    // over SSH rather than stranding the important post. Only the `owner` alias
-    // forwards: it resolves the peer's own fleet-synced owner destination, so a
-    // non-owner channel sink with an explicit recipient stays local.
-    if (owner) {
-        const forwarded = await forwardOwnerNotifyToPeer(sink.text ?? '', resolved.envelope.channel, meta);
-        if (forwarded?.ok)
-            return { name, ok: true };
-    }
     return { name, ok: false, error: result.error };
 }
 /**

package/dist/lib/github/gh-overload.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The delegate behind the `gh` PATH shim (`agents __gh --real-gh <path> -- <argv>`).
+ *
+ * Agents are statically trained to type `gh pr checks …`; the shim intercepts that
+ * habit and routes it here so the rate-limit-prone read runs over REST instead of
+ * GraphQL — no new command for an agent to remember. This is the Tier-1 scope:
+ * only `gh pr checks` is handled; every other invocation execs the real gh
+ * byte-for-byte (the shim already passes non-`pr checks` verbs straight to real gh,
+ * and this file passes through defensively for anything it cannot cleanly serve).
+ *
+ * Two switch modes (see the PHNX-3501 plan):
+ *   - `--watch` → EAGER REST: own the poll loop, re-anchored to the live head SHA
+ *     each tick, so a superseded run's red can never be reported (PHNX-3042).
+ *   - one-shot → LAZY: run real gh first; only translate to REST when it fails with
+ *     the exact GraphQL rate-limit signal. An over-budget GraphQL call is rejected
+ *     at 0 points, so this is nearly free and never reproduces gh's happy path.
+ *
+ * Fail-open is the rule: anything not cleanly resolvable (no PR number/URL, an
+ * unmappable request) execs real gh rather than returning wrong data.
+ */
+import { type RollupItem } from './rest.js';
+interface Parsed {
+    realGh: string;
+    ghArgs: string[];
+}
+/** Split `--real-gh <path> -- <gh argv>`; defaults realGh to bare `gh`. */
+export declare function parseDelegateArgs(argv: string[]): Parsed;
+export interface Target {
+    repo: string;
+    number: number;
+}
+/** owner/repo from a git remote URL, or null. */
+export declare function repoFromRemote(remoteUrl: string): string | null;
+/**
+ * Resolve `{repo, number}` from the `gh pr checks` argv + cwd, over git/REST only.
+ * Returns null (→ caller passes through to real gh) when it can't be resolved
+ * cleanly, e.g. no number and no open PR for the current branch.
+ */
+export declare function resolveTarget(ghArgs: string[], cwd: string, realGh: string): Promise<Target | null>;
+/** Render one rollup as `gh pr checks`-ish lines (or JSON when asked). */
+export declare function renderRollup(input: RollupItem[], json: boolean): string;
+/**
+ * True once CI has settled for this SHA.
+ *
+ * Check-suites only disambiguate an EMPTY rollup: no checks + no pending suites is
+ * "genuinely none" (settled); no checks + a pending suite is "not registered yet"
+ * (wait). Once real checks exist we decide on THEM alone and ignore suites — some
+ * App integrations (claude/cursor reviewers) register a suite that stays `queued`
+ * forever and never posts a run, exactly what `gh pr checks` also ignores.
+ */
+export declare function isSettled(rollup: RollupItem[], pendingSuites: number): boolean;
+/** Eager REST watch: poll to a terminal state, re-anchored to the live head SHA. */
+export declare function watchChecks(target: Target, json: boolean, realGh: string): Promise<number>;
+/** Lazy one-shot: real gh first; translate to REST only on the exact rate-limit signal. */
+export declare function checksOnce(target: Target | null, json: boolean, realGh: string, ghArgs: string[]): Promise<number>;
+/** Entry point for the `__gh` early branch in index.ts. */
+export declare function runGhOverload(argv: string[], cwd?: string): Promise<number>;
+export {};