@phnx-labs/agents-cli 1.22.60 → 1.22.62

package/dist/lib/session/host-link.d.ts

@@ -80,3 +80,25 @@ export interface HostLinkInput {
  * or a running editor.
  */
 export declare function classifyHostLink(input: HostLinkInput): HostLink;
+/**
+ * Did the owning IDE window die while the agent kept RUNNING? This is the ONE
+ * host-link loss that promotes a still-`running` session to `orphaned`
+ * (PHNX-3183): a window that WAS republishing its heartbeat every 4 min went
+ * stale for {@link HOST_HEARTBEAT_STALE_MS}, so it died uncleanly (a crash,
+ * reboot, or dropped SSH) and the agent it hosted outlived it — genuinely
+ * stranded, the "my remote agent is still alive after the laptop rebooted" case.
+ *
+ * Deliberately NARROWER than `no-client`. A tmux attached-client count of zero
+ * is also `no-client`, but for a detached remote pane (`agents run --device`,
+ * which RUSH-3125 wraps in a detached tmux session) that is the NORMAL steady
+ * state between check-ins — launch, detach, return with `agents focus` — not a
+ * loss. Promoting on it would relabel every unattended remote agent as
+ * `orphaned`, the over-reporting that makes the word worthless. Only a lost
+ * WINDOW is a positive "a client was expected and is now gone" for a running
+ * agent; mere absence is not.
+ *
+ * A deliberately-backgrounded session is excluded exactly as
+ * {@link classifyHostLink} excludes it: no client is the point of detaching.
+ * Pure — same injected signals as the classifier.
+ */
+export declare function hostWindowLost(input: HostLinkInput): boolean;

package/dist/lib/session/host-link.js

@@ -33,22 +33,32 @@
  * the extension agree on when a window is dead.
  */
 export const HOST_HEARTBEAT_STALE_MS = 10 * 60_000;
+/**
+ * Did the session's owning IDE window stop republishing its registry slice? A
+ * window republishes every 4 minutes (`HOST_HEARTBEAT_STALE_MS` is 10), so a
+ * slice this old means the window is gone, not merely quiet. Shared by
+ * {@link classifyHostLink} and {@link hostWindowLost} so the staleness rule has
+ * exactly one definition.
+ */
+function windowGone(input) {
+    const now = input.nowMs ?? Date.now();
+    return input.windowHeartbeatMs !== undefined && now - input.windowHeartbeatMs >= HOST_HEARTBEAT_STALE_MS;
+}
 /**
  * Classify a live row's host link. Pure — every signal is passed in, so the
  * whole decision table is unit-testable without a process table, a tmux server,
  * or a running editor.
  */
 export function classifyHostLink(input) {
-    const now = input.nowMs ?? Date.now();
     // A session detached on purpose has no client BY DESIGN. It is the one case
     // that looks identical to an orphan from the outside, so it is excluded first —
     // otherwise every `agents sessions detach` would raise a false alarm.
     if (input.deliberatelyDetached)
         return 'connected';
-    const windowGone = input.windowHeartbeatMs !== undefined && now - input.windowHeartbeatMs >= HOST_HEARTBEAT_STALE_MS;
+    const stale = windowGone(input);
     // The host window stopped keeping its registry slice alive AND the agent it
     // owned is dead: the pair went down together without teardown.
-    if (windowGone && !input.pidAlive)
+    if (stale && !input.pidAlive)
         return 'host-gone';
     if (!input.pidAlive)
         return 'connected'; // a plain dead pid is `closed`, not an orphan
@@ -58,7 +68,7 @@ export function classifyHostLink(input) {
         return 'no-client';
     // Alive, not tmux-hosted (or tmux says someone is attached), but the window
     // that owned it is gone. The agent outlived its editor.
-    if (windowGone)
+    if (stale)
         return 'no-client';
     // Positive evidence of a client: tmux counted at least one attached client, or
     // a window is refreshing its registry slice. Either is a real observation.
@@ -68,3 +78,29 @@ export function classifyHostLink(input) {
     // reporting the healthy answer by default — see {@link HostLink}'s `unknown`.
     return 'unknown';
 }
+/**
+ * Did the owning IDE window die while the agent kept RUNNING? This is the ONE
+ * host-link loss that promotes a still-`running` session to `orphaned`
+ * (PHNX-3183): a window that WAS republishing its heartbeat every 4 min went
+ * stale for {@link HOST_HEARTBEAT_STALE_MS}, so it died uncleanly (a crash,
+ * reboot, or dropped SSH) and the agent it hosted outlived it — genuinely
+ * stranded, the "my remote agent is still alive after the laptop rebooted" case.
+ *
+ * Deliberately NARROWER than `no-client`. A tmux attached-client count of zero
+ * is also `no-client`, but for a detached remote pane (`agents run --device`,
+ * which RUSH-3125 wraps in a detached tmux session) that is the NORMAL steady
+ * state between check-ins — launch, detach, return with `agents focus` — not a
+ * loss. Promoting on it would relabel every unattended remote agent as
+ * `orphaned`, the over-reporting that makes the word worthless. Only a lost
+ * WINDOW is a positive "a client was expected and is now gone" for a running
+ * agent; mere absence is not.
+ *
+ * A deliberately-backgrounded session is excluded exactly as
+ * {@link classifyHostLink} excludes it: no client is the point of detaching.
+ * Pure — same injected signals as the classifier.
+ */
+export function hostWindowLost(input) {
+    if (input.deliberatelyDetached)
+        return false;
+    return input.pidAlive && windowGone(input);
+}

package/dist/lib/session/trajectory.d.ts

@@ -90,6 +90,48 @@ export interface BuildTrajectoryOptions {
     /** Cap on drawn steps; the tail is dropped and counted. Default 5000. */
     maxSteps?: number;
 }
+/**
+ * The effective program a shell command ran, via the shared shell parser
+ * (`extractShellPrograms` — which unwraps the wrappers it knows: `env`, `sudo`,
+ * `agents ssh`; note `timeout` is deliberately NOT a wrapper there, per SES-37,
+ * so `timeout 30 npm test` resolves to `timeout`). On top of that this skips
+ * bare builtins/assignments (`cd`, `export`, …) when a real program follows. For
+ * a pipeline it takes the LEFTMOST effective program (`cat f | grep x` → `cat`),
+ * matching how the parser orders occurrences. Undefined when nothing static is
+ * identifiable. Never executes anything.
+ */
+export declare function effectiveProgram(command: string | undefined): string | undefined;
+/**
+ * One paired step: the drawn {@link TrajectoryStep}, the index of its originating
+ * `tool_use`/`thinking` event, and — once pairing completes — the index of the
+ * `tool_result`/`error` event that answered it. `buildSessionDetailV2` reads these
+ * triples (step, useEvent, resultEvent) to populate the schema-2 per-tool shapes
+ * WITHOUT re-running the callId pairing loop.
+ */
+export interface StepDraft {
+    step: TrajectoryStep;
+    eventIndex: number;
+    callId?: string;
+    resultEventIndex?: number;
+}
+/** Absolute ms per event index (NaN when the timestamp is unparseable). */
+export declare function eventTimestampsMs(events: SessionEvent[]): number[];
+/**
+ * Draw a step for each thinking block and each non-local tool_use, in order, and
+ * pair each `tool_use` with its `tool_result`/`error` on `callId` (FIFO within a
+ * reused id — never across ids, and never by arrival order for concurrent calls,
+ * matching `ToolCallCollector.takePending`'s refusal to guess, `tool-calls.ts:509`).
+ *
+ * `_local` tool calls (Claude `!`-prefixed shell) are excluded to match the
+ * header's tool count (`computeSummaryStats` skips them, `render.ts:224`).
+ *
+ * The single source of the pairing: both {@link buildTrajectory} and
+ * `buildSessionDetailV2` consume the returned drafts (each draft's `eventIndex` +
+ * `resultEventIndex` are the use/result event indices) so the schema-2 producer
+ * never re-implements the loop. Durations/outcomes are still resolved by the
+ * caller — this only draws and pairs.
+ */
+export declare function pairSteps(events: SessionEvent[], eventMs: number[], firstTs: number, redact: boolean, knownSecrets: readonly string[] | undefined): StepDraft[];
 /**
  * Build the derived trajectory for one session's normalized events.
  *

package/dist/lib/session/trajectory.js

@@ -45,7 +45,7 @@ const SHELL_NOISE_PROGRAMS = new Set(['export', 'cd', 'set', 'source', '.', 'uns
  * matching how the parser orders occurrences. Undefined when nothing static is
  * identifiable. Never executes anything.
  */
-function effectiveProgram(command) {
+export function effectiveProgram(command) {
     if (!command)
         return undefined;
     const { occurrences, programs } = extractShellPrograms(command);
@@ -174,36 +174,26 @@ function resultDetail(event, redact, knownSecrets) {
     const clipped = clip(text, DETAIL_MAX);
     return redact ? redactSecrets(clipped, knownSecrets) : clipped;
 }
+/** Absolute ms per event index (NaN when the timestamp is unparseable). */
+export function eventTimestampsMs(events) {
+    return events.map((e) => toMs(e.timestamp));
+}
 /**
- * Build the derived trajectory for one session's normalized events.
- *
- * Pairs each `tool_use` with its `tool_result`/`error` on `callId` (FIFO within a
+ * Draw a step for each thinking block and each non-local tool_use, in order, and
+ * pair each `tool_use` with its `tool_result`/`error` on `callId` (FIFO within a
  * reused id — never across ids, and never by arrival order for concurrent calls,
  * matching `ToolCallCollector.takePending`'s refusal to guess, `tool-calls.ts:509`).
- * A harness with no parseable transcript (OpenClaw, `parse.ts:186`) yields an empty
- * event array and therefore an empty trajectory — never a crash or a fabricated one.
+ *
+ * `_local` tool calls (Claude `!`-prefixed shell) are excluded to match the
+ * header's tool count (`computeSummaryStats` skips them, `render.ts:224`).
+ *
+ * The single source of the pairing: both {@link buildTrajectory} and
+ * `buildSessionDetailV2` consume the returned drafts (each draft's `eventIndex` +
+ * `resultEventIndex` are the use/result event indices) so the schema-2 producer
+ * never re-implements the loop. Durations/outcomes are still resolved by the
+ * caller — this only draws and pairs.
  */
-export function buildTrajectory(events, meta, options = {}) {
-    const redact = options.redact !== false;
-    const knownSecrets = options.knownSecrets;
-    const idleThreshold = options.idleThresholdMs ?? DEFAULT_IDLE_THRESHOLD_MS;
-    const maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
-    const stats = computeSummaryStats(events);
-    const firstTs = stats.firstTs;
-    const spanMs = stats.lastTs > stats.firstTs ? stats.lastTs - stats.firstTs : 0;
-    // Absolute ms per event index (NaN when the timestamp is unparseable).
-    const eventMs = events.map((e) => toMs(e.timestamp));
-    // The next event index (after i) that carries a valid timestamp — the anchor
-    // for the next-event duration fallback and for idle-gap detection.
-    const nextValidTs = new Array(events.length).fill(NaN);
-    for (let i = events.length - 1, later = NaN; i >= 0; i--) {
-        nextValidTs[i] = later;
-        if (!Number.isNaN(eventMs[i]))
-            later = eventMs[i];
-    }
-    // Draw a step for each thinking block and each non-local tool_use, in order.
-    // `_local` tool calls (Claude `!`-prefixed shell) are excluded to match the
-    // header's tool count (`computeSummaryStats` skips them, `render.ts:224`).
+export function pairSteps(events, eventMs, firstTs, redact, knownSecrets) {
     const drafts = [];
     const pendingByCallId = new Map();
     for (let i = 0; i < events.length; i++) {
@@ -261,6 +251,35 @@ export function buildTrajectory(events, meta, options = {}) {
             }
         }
     }
+    return drafts;
+}
+/**
+ * Build the derived trajectory for one session's normalized events.
+ *
+ * Pairs each `tool_use` with its `tool_result`/`error` on `callId` (FIFO within a
+ * reused id — never across ids, and never by arrival order for concurrent calls,
+ * matching `ToolCallCollector.takePending`'s refusal to guess, `tool-calls.ts:509`).
+ * A harness with no parseable transcript (OpenClaw, `parse.ts:186`) yields an empty
+ * event array and therefore an empty trajectory — never a crash or a fabricated one.
+ */
+export function buildTrajectory(events, meta, options = {}) {
+    const redact = options.redact !== false;
+    const knownSecrets = options.knownSecrets;
+    const idleThreshold = options.idleThresholdMs ?? DEFAULT_IDLE_THRESHOLD_MS;
+    const maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
+    const stats = computeSummaryStats(events);
+    const firstTs = stats.firstTs;
+    const spanMs = stats.lastTs > stats.firstTs ? stats.lastTs - stats.firstTs : 0;
+    const eventMs = eventTimestampsMs(events);
+    // The next event index (after i) that carries a valid timestamp — the anchor
+    // for the next-event duration fallback and for idle-gap detection.
+    const nextValidTs = new Array(events.length).fill(NaN);
+    for (let i = events.length - 1, later = NaN; i >= 0; i--) {
+        nextValidTs[i] = later;
+        if (!Number.isNaN(eventMs[i]))
+            later = eventMs[i];
+    }
+    const drafts = pairSteps(events, eventMs, firstTs, redact, knownSecrets);
     // Resolve durations, outcomes, and detail now that pairing is complete.
     for (const draft of drafts) {
         const { step } = draft;

package/dist/lib/ssh-exec.d.ts

@@ -61,6 +61,36 @@ export declare class RemoteUtf8Accumulator {
     end(): string;
     current(): string;
 }
+/**
+ * How long OpenSSH keeps a multiplex master alive after its last client exits
+ * (`ControlPersist`, in seconds).
+ *
+ * The master only survives while it stays IDLE under this window, so it helps
+ * exactly a *repeated* touch of the same host that arrives within the window; a
+ * touch that arrives after the master has expired pays the full cold TCP+auth
+ * handshake again (~100-300ms direct, up to ~500ms relayed; measured on the live
+ * fleet 2026-08-10, PHNX-2582).
+ *
+ * The repeated same-host touches are the ad-hoc `--device` and fleet fan-out
+ * calls — `sessions --active`, `fleet ping`/`status`, `doctor`, `teams`, a
+ * `--device <box>` command run a few times while working — which arrive in
+ * BURSTS spread over minutes, not on a fixed clock. (The one truly high-frequency
+ * caller, `followHostTask`'s ~1.5s follow poll, was already warm even at 60s and
+ * is not the target here.) At the old 60s window any two touches of the same box
+ * more than a minute apart were both cold, so a burst paid a fresh handshake
+ * almost every time.
+ *
+ * 10 minutes keeps a multi-minute burst warm (3-5ms per reuse) while still
+ * bounding how long an idle master lingers — an important limit, because a reused
+ * master to a box that has since slept costs a ~45s ServerAlive teardown on the
+ * first touch (`ServerAliveInterval=15 × ServerAliveCountMax=3`), and a wider
+ * window would only widen the chance of hitting that. The daemon's periodic
+ * SSH-touching services (`usage-sync`/`auth-sync`) tick every 15 minutes, longer
+ * than this window ON PURPOSE: warming them would need a wider window for a
+ * handshake that is negligible at that cadence. Fan-outs stay bounded regardless
+ * by their own per-peer `timeoutMs`.
+ */
+export declare const SSH_CONTROL_PERSIST_SECONDS: number;
 export declare function controlOpts(): string[];
 /**
  * Compose an ssh connection-option prefix.

package/dist/lib/ssh-exec.js

@@ -87,20 +87,52 @@ export class RemoteUtf8Accumulator {
         return this.value;
     }
 }
+/**
+ * How long OpenSSH keeps a multiplex master alive after its last client exits
+ * (`ControlPersist`, in seconds).
+ *
+ * The master only survives while it stays IDLE under this window, so it helps
+ * exactly a *repeated* touch of the same host that arrives within the window; a
+ * touch that arrives after the master has expired pays the full cold TCP+auth
+ * handshake again (~100-300ms direct, up to ~500ms relayed; measured on the live
+ * fleet 2026-08-10, PHNX-2582).
+ *
+ * The repeated same-host touches are the ad-hoc `--device` and fleet fan-out
+ * calls — `sessions --active`, `fleet ping`/`status`, `doctor`, `teams`, a
+ * `--device <box>` command run a few times while working — which arrive in
+ * BURSTS spread over minutes, not on a fixed clock. (The one truly high-frequency
+ * caller, `followHostTask`'s ~1.5s follow poll, was already warm even at 60s and
+ * is not the target here.) At the old 60s window any two touches of the same box
+ * more than a minute apart were both cold, so a burst paid a fresh handshake
+ * almost every time.
+ *
+ * 10 minutes keeps a multi-minute burst warm (3-5ms per reuse) while still
+ * bounding how long an idle master lingers — an important limit, because a reused
+ * master to a box that has since slept costs a ~45s ServerAlive teardown on the
+ * first touch (`ServerAliveInterval=15 × ServerAliveCountMax=3`), and a wider
+ * window would only widen the chance of hitting that. The daemon's periodic
+ * SSH-touching services (`usage-sync`/`auth-sync`) tick every 15 minutes, longer
+ * than this window ON PURPOSE: warming them would need a wider window for a
+ * handshake that is negligible at that cadence. Fan-outs stay bounded regardless
+ * by their own per-peer `timeoutMs`.
+ */
+export const SSH_CONTROL_PERSIST_SECONDS = 10 * 60;
 /**
  * OpenSSH connection-multiplexing options. The first connection to a host opens
  * a control socket; subsequent connections (even from a *separate* `agents`
  * invocation) reuse it, skipping the TCP+auth handshake — so repeated
  * `--device <name>` calls to the same box feel local instead of paying ~100-300ms
- * each. `ControlPersist=60s` keeps the master alive briefly after the last
- * client exits. `%C` (a short fixed-length hash of local-host/remote/port/user)
- * keeps the socket path well under macOS's 104-char `sun_path` limit.
+ * each. `ControlPersist` keeps the master alive after the last client exits, sized
+ * to span a multi-minute burst of repeated touches — see
+ * {@link SSH_CONTROL_PERSIST_SECONDS} for the value and the rationale. `%C` (a
+ * short fixed-length hash of local-host/remote/port/user) keeps the socket path
+ * well under macOS's 104-char `sun_path` limit.
  *
  * This is **on by default** for every `sshExec`/`sshStream` call: the poll loops
  * (`followHostTask`), readiness probes, and per-host fan-outs are exactly the
  * high-frequency callers that benefit most from socket reuse, and they should
  * never have to remember to opt in. A caller passes `multiplex: false` only for
- * a genuine one-shot where a lingering 60s master is pure overhead.
+ * a genuine one-shot where a lingering master is pure overhead.
  *
  * The socket directory is created lazily; if ssh can't open the control socket
  * it falls back to a normal connection (multiplexing is an optimisation, never a
@@ -126,7 +158,7 @@ export function controlOpts() {
     return [
         '-o', 'ControlMaster=auto',
         '-o', `ControlPath=${path.join(dir, 'cm-%C')}`,
-        '-o', 'ControlPersist=60s',
+        '-o', `ControlPersist=${SSH_CONTROL_PERSIST_SECONDS}s`,
     ];
 }
 /**

package/dist/lib/startup/command-registry.js

@@ -5,7 +5,7 @@ const LOADED_COMMAND_NAMES = [
     'routines', 'monitors', 'projects', 'run', 'open', 'reconnect', 'fork', 'config',
     'models', 'modes', 'trash', 'restore', 'doctor',
     'route', 'harness', 'harnesses', 'secrets', 'menubar', 'sync',
-    'refresh-rules', 'factory', 'insights', 'trace',
+    'refresh-rules', 'factory', 'insights', 'trace', 'reminders',
     'pty', 'tmux', 'watchdog', 'browser', 'computer', 'logs', 'events',
     'ssh', 'devices', 'fleet', 'repos', 'repo', 'setup', 'uninstall', 'upgrade', 'sessions',
     'teams', 'cloud', 'message', 'send', 'notify', 'feed',

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

@@ -29,6 +29,17 @@ export interface SubagentTarget {
     occupied(dir: string, name: string): OccupiedEntry[];
     /** Rich metadata for `name`; `null` skips it from the listing. */
     read(dir: string, name: string): SubagentMeta | null;
+    /**
+     * True when the installed subagent `sub` in `dir` byte-matches what `write`
+     * would materialize from `sub.path` NOW — the content-drift check `agents
+     * doctor` uses. Re-renders the CURRENT source through the same transform the
+     * writer uses (never a stored hash), so a prompt-body edit to the source
+     * surfaces as drift even though the filename is unchanged.
+     */
+    matches(dir: string, sub: {
+        name: string;
+        path: string;
+    }): boolean;
 }
 /**
  * Copy every file in `src` into `dest` (created if missing), applying
@@ -55,6 +66,13 @@ export declare function writeSubagentToHome(agent: AgentId, home: string, sub: {
 }): boolean;
 /** Installed subagent names for `agent` under `home` (detector + orphan diff). */
 export declare function listInstalledSubagentNames(agent: AgentId, home: string): string[];
+/**
+ * True when subagent `name` installed for `agent` under `home` byte-matches what
+ * the writer would produce NOW from `sourceDir` — the content-drift predicate
+ * `agents doctor` uses. Returns false when the agent has no registry entry
+ * (nothing could have been written) so an unexpected home copy reads as drift.
+ */
+export declare function subagentContentMatches(agent: AgentId, home: string, name: string, sourceDir: string): boolean;
 /**
  * Rich listing of subagents installed for `agent` under `home`, with parsed
  * metadata. Enumerates names, then reads each -- entries whose metadata is

package/dist/lib/subagents-registry.js

@@ -34,7 +34,17 @@ import * as path from 'path';
 import * as TOML from 'smol-toml';
 import * as yaml from 'yaml';
 import { safeJoin } from './paths.js';
+import { filesContentMatch, normalizeResourceContent } from './resource-content-diff.js';
 import { parseSubagentFrontmatter, transformSubagentForClaude, transformSubagentForCodex, transformSubagentForCopilot, transformSubagentForCursor, transformSubagentForDroid, transformSubagentForGoose, transformSubagentForKiro, transformSubagentForOpenCode, transformSubagentForAntigravity, } from './subagents.js';
+/** Read a file's UTF-8 content, or null when it is missing/unreadable. */
+function readFileSafe(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
 // ── metadata readers (the per-format escape hatch) ───────────────────────────
 /** Frontmatter, skipping files that lack a valid block (claude/grok/droid). */
 function metaFrontmatterSkip(filePath) {
@@ -130,6 +140,13 @@ function flatFile(opts) {
                 return null;
             return { frontmatter, files: [`${name}${opts.ext}`], path: filePath };
         },
+        matches(dir, sub) {
+            const filePath = path.join(dir, `${sub.name}${opts.ext}`);
+            const installed = readFileSafe(filePath);
+            if (installed == null)
+                return false;
+            return normalizeResourceContent(installed) === normalizeResourceContent(opts.transform(sub.path));
+        },
     };
 }
 /** A `<name>/` directory holding one generated `<file>` per subagent. */
@@ -162,6 +179,13 @@ function dirFile(opts) {
                 return null;
             return { frontmatter, files: [opts.file], path: filePath };
         },
+        matches(dir, sub) {
+            const filePath = path.join(dir, sub.name, opts.file);
+            const installed = readFileSafe(filePath);
+            if (installed == null)
+                return false;
+            return normalizeResourceContent(installed) === normalizeResourceContent(opts.transform(sub.path));
+        },
     };
 }
 /** Copy the whole source directory to `<name>/`, detected by `marker`. */
@@ -204,6 +228,49 @@ function dirCopy(opts) {
                 .sort();
             return { frontmatter, files, path: subagentDir };
         },
+        matches(dir, sub) {
+            // dirCopy materializes every source file (with rename) into <dir>/<name>/.
+            // Re-derive the expected file set from source and byte-compare each, so an
+            // edit to any copied file — or an added/removed source file — is drift.
+            const dest = path.join(dir, sub.name);
+            let sourceFiles;
+            try {
+                sourceFiles = fs.readdirSync(sub.path).filter((f) => {
+                    try {
+                        return fs.statSync(path.join(sub.path, f)).isFile();
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+            }
+            catch {
+                return false;
+            }
+            const expectedDestNames = new Set();
+            for (const file of sourceFiles) {
+                const destName = opts.rename?.[file] ?? file;
+                expectedDestNames.add(destName);
+                if (!filesContentMatch(path.join(sub.path, file), path.join(dest, destName)))
+                    return false;
+            }
+            // An extra file left in the installed dir (source file removed) is drift.
+            let destFiles;
+            try {
+                destFiles = fs.readdirSync(dest).filter((f) => {
+                    try {
+                        return fs.statSync(path.join(dest, f)).isFile();
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+            }
+            catch {
+                return false;
+            }
+            return destFiles.every((f) => expectedDestNames.has(f));
+        },
     };
 }
 // ── the registry ─────────────────────────────────────────────────────────────
@@ -295,6 +362,18 @@ export function listInstalledSubagentNames(agent, home) {
         return [];
     return target.names(target.dir(home));
 }
+/**
+ * True when subagent `name` installed for `agent` under `home` byte-matches what
+ * the writer would produce NOW from `sourceDir` — the content-drift predicate
+ * `agents doctor` uses. Returns false when the agent has no registry entry
+ * (nothing could have been written) so an unexpected home copy reads as drift.
+ */
+export function subagentContentMatches(agent, home, name, sourceDir) {
+    const target = SUBAGENT_TARGETS[agent];
+    if (!target)
+        return false;
+    return target.matches(target.dir(home), { name, path: sourceDir });
+}
 /**
  * Rich listing of subagents installed for `agent` under `home`, with parsed
  * metadata. Enumerates names, then reads each -- entries whose metadata is

package/dist/lib/teams/agents.d.ts

@@ -101,6 +101,18 @@ export { captureProcessStartTime };
  * model_reasoning_effort override). Mode (plan/edit/full) is a separate knob.
  */
 export type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
+/**
+ * Append {@link TEAMMATE_PR_POLICY} to a teammate prompt for every WRITE-capable
+ * mode (all but plan, which is read-only and opens no PR). Exported so the CLOUD
+ * dispatch path (`cloudDispatchOptions` in `commands/teams.ts`) applies the SAME
+ * boundary this file's `buildRunArgv` applies to LOCAL and REMOTE teammates. A
+ * cloud teammate is the case that needs it MOST: it runs in the provider's
+ * sandbox, not the shared local version home, so it never inherits the
+ * `merge-guard.sh` PreToolUse hook — the prompt policy is then its ONLY
+ * self-merge layer. Routing every dispatch surface through one helper keeps that
+ * parity from drifting (PHNX-3236).
+ */
+export declare function withTeammatePrPolicy(prompt: string, mode: string): string;
 export declare const VALID_MODES: readonly ["plan", "edit", "auto", "skip", "full"];
 type Mode = 'plan' | 'edit' | 'auto' | 'skip';
 /** Resolve a mode string to a validated Mode, falling back to the given default. */

package/dist/lib/teams/agents.js

@@ -255,6 +255,49 @@ When you're done, provide a brief summary of:
 const CLAUDE_PLAN_MODE_PREFIX = `You are running in HEADLESS PLAN MODE. This mode works like normal plan mode with one exception: you cannot write to ~/.claude/plans/ directory. Instead of writing a plan file, output your complete plan/response as your final message.
 
 `;
+// PHNX-3236: the teammate self-merge boundary, injected as a DISPATCH DEFAULT.
+// A write-capable teammate has `gh pr merge` and authenticates as the repo owner,
+// so it can merge its OWN PR past the required non-author-review gate — which is
+// exactly what happened in the RUSH-2988 wave-1 dispatch (PR #1817, #1820). The
+// root cause was that the boundary lived in per-brief wording: one teammate in the
+// batch was told "open the PR, don't merge" and held off; the others weren't and
+// self-merged. Making it a default the runner appends to every non-plan teammate
+// gives one HARNESS-INDEPENDENT layer instead of relying on each dispatch prompt
+// remembering to say it. The HARD enforcement is merge-guard.sh — a PreToolUse hook
+// the teammate inherits from the shared version home, whose self-authored-verdict
+// exclusion was closed in the same ticket (.agents-system #395) so a verdict a
+// teammate posts on its own PR no longer clears the gate. The two layers do NOT
+// overlap everywhere: hook-capable local/remote teammates get both, but cloud
+// teammates (provider sandbox, no inherited hook) and hook-incapable harnesses
+// (Warp/oz — no hook surface, no allowlist) get ONLY this prompt, so for them it is
+// a soft control. That residual is documented in cli/AGENTS.md §6; server-side
+// branch protection is the client-independent way to close it. This is the
+// harness-independent layer plus the operator hand-off contract, not a replacement
+// for the hard block where the hard block can run.
+const TEAMMATE_PR_POLICY = `
+
+Teammate PR policy (agents teams): when your work opens a pull request, open it and
+hand it off — do NOT merge your OWN PR unless a NON-AUTHOR review verdict has been
+posted on that same PR. You authenticate as the repo owner and share that one
+GitHub identity with every other teammate, so an APPROVE you post on your own PR
+does not count as a non-author review. \`gh pr merge\` on your own PR is blocked by
+merge-guard until a genuine non-author verdict exists on it; never pass --admin or
+otherwise route around that guard. Report the PR as open and let the orchestrator
+or a separate reviewer take it to merge.`;
+/**
+ * Append {@link TEAMMATE_PR_POLICY} to a teammate prompt for every WRITE-capable
+ * mode (all but plan, which is read-only and opens no PR). Exported so the CLOUD
+ * dispatch path (`cloudDispatchOptions` in `commands/teams.ts`) applies the SAME
+ * boundary this file's `buildRunArgv` applies to LOCAL and REMOTE teammates. A
+ * cloud teammate is the case that needs it MOST: it runs in the provider's
+ * sandbox, not the shared local version home, so it never inherits the
+ * `merge-guard.sh` PreToolUse hook — the prompt policy is then its ONLY
+ * self-merge layer. Routing every dispatch surface through one helper keeps that
+ * parity from drifting (PHNX-3236).
+ */
+export function withTeammatePrPolicy(prompt, mode) {
+    return mode === 'plan' ? prompt : prompt + TEAMMATE_PR_POLICY;
+}
 // Canonical modes plus the historical `full` alias (rewritten to `skip` by
 // normalizeModeValue). Keep `full` listed so user-typed CLI flags and stored
 // metadata that pre-date the rename continue to parse.
@@ -2530,6 +2573,14 @@ export class AgentManager {
                 fullPrompt = CLAUDE_PLAN_MODE_PREFIX + fullPrompt;
             }
         }
+        // PHNX-3236: append the self-merge boundary to every WRITE-capable teammate,
+        // fresh or resumed. A plan-mode teammate produces no PR (read-only), so it is
+        // skipped to keep its prompt clean; every other mode can open — and could
+        // self-merge — a PR, so the policy rides along regardless of harness. The
+        // hard block is still merge-guard.sh (inherited hook); see TEAMMATE_PR_POLICY.
+        // The cloud dispatch path applies the SAME helper (withTeammatePrPolicy) so
+        // local, remote, and cloud teammates never diverge on this boundary.
+        fullPrompt = withTeammatePrPolicy(fullPrompt, mode);
         // Profile target takes precedence — `agents run <profile>` resolves the
         // host harness, version pin, and env injection in one place. Plain
         // version pins only apply when no profile is selected.