@phnx-labs/agents-cli 1.22.50 → 1.22.52

package/dist/lib/channels/owner-forward.js

@@ -0,0 +1,116 @@
+import { loadDevices, isDialableDevice } from '../devices/registry.js';
+import { machineId, normalizeHost } from '../machine-id.js';
+import { RUSH_CHANNELS } from './providers/rush.js';
+import { resolvePeerTarget, sshCapture } from '../session/remote/remote-list.js';
+import { buildRemoteAgentsInvocation, stripClixml } from '../hosts/remote-cmd.js';
+/**
+ * Env marker set on the forwarded `agents send` so a box that received a
+ * forwarded owner notify never forwards it onward. `agents send` does not route
+ * through this module today, so this is defense-in-depth against a future
+ * consumer wiring forwarding into the send path and creating a fan-out loop.
+ */
+export const OWNER_FORWARD_GUARD_ENV = 'AGENTS_OWNER_NO_FORWARD';
+/** Per-peer SSH deadline for a one-shot owner delivery. */
+const PEER_SEND_TIMEOUT_MS = 15_000;
+/**
+ * True when the resolved owner transport is the macOS-only rush family — the
+ * one case a Linux/headless box structurally cannot deliver and a peer can.
+ * `openclaw-telegram` and the local `desktop`/`mailbox` providers are NOT
+ * rush-backed, so a failure there is not a wrong-OS problem and is left as-is.
+ * Mirrors the same `RUSH_CHANNELS.includes(transport)` gate in owner-sink.ts.
+ */
+export function isRushBackedTransport(channel, meta) {
+    const transport = meta.notify?.transports?.[channel] ?? channel;
+    return RUSH_CHANNELS.includes(transport);
+}
+/**
+ * Decide which peers can deliver the owner notification, in try order. Pure —
+ * no I/O — so the channel gate, the recursion guard, self-exclusion, and the
+ * capability/ordering rules are unit-testable without a live tailnet.
+ *
+ * Only macOS peers are candidates: the rush owner transport is macOS-only, so a
+ * Linux/Windows peer could not deliver it either. The configured
+ * `interactive.host` (the box the operator sits at, where rush is signed in) is
+ * tried first when it is among the candidates.
+ */
+export function planOwnerForward(channel, meta, devices, self, opts = {}) {
+    if (opts.guarded)
+        return { candidates: [], skip: 'guarded' };
+    if (!isRushBackedTransport(channel, meta))
+        return { candidates: [], skip: 'not-rush-backed' };
+    const selfId = normalizeHost(self);
+    const capable = devices.filter((d) => d.platform === 'macos' && isDialableDevice(d) && normalizeHost(d.name) !== selfId);
+    const interactiveHost = typeof meta.config?.interactiveHost === 'string'
+        ? normalizeHost(meta.config.interactiveHost)
+        : undefined;
+    const rank = (name) => (interactiveHost && normalizeHost(name) === interactiveHost ? 0 : 1);
+    const candidates = capable
+        .map((d) => normalizeHost(d.name))
+        .sort((a, b) => rank(a) - rank(b));
+    if (candidates.length === 0)
+        return { candidates: [], skip: 'no-capable-peer' };
+    return { candidates };
+}
+async function sendOnPeer(machine, text) {
+    const peer = await resolvePeerTarget(machine);
+    if (!peer)
+        return undefined;
+    const args = ['send', '--to', 'owner', '--text', text, '--json'];
+    // Reuse the one injection-tested remote-command builder every `--device`
+    // dispatch uses (posix `bash -lc` / Windows `-EncodedCommand`), rather than a
+    // second hand-rolled quoting path on a security-sensitive seam. The env map is
+    // the loop guard, exported the same way every remote invocation exports env.
+    const remoteCmd = buildRemoteAgentsInvocation(args, undefined, peer.os, { [OWNER_FORWARD_GUARD_ENV]: '1' });
+    const capture = await sshCapture(peer.target, remoteCmd, PEER_SEND_TIMEOUT_MS);
+    if (capture.code !== 0)
+        return undefined;
+    try {
+        const parsed = JSON.parse(stripClixml(capture.stdout));
+        if (parsed && typeof parsed === 'object' && typeof parsed.ok === 'boolean')
+            return parsed;
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Try each capable peer in order and return the first successful delivery. A
+ * peer that is unreachable or reports its own delivery failure is skipped and
+ * the next is tried; the first `ok:true` wins and stops the sweep so the owner's
+ * phone rings once. Resolves `undefined` when forwarding does not apply or no
+ * peer delivered — the caller then keeps its original local error.
+ *
+ * The transport (`send`) is injectable so the try-order / first-success / stop
+ * orchestration is testable without a live SSH host; the default runs the real
+ * `agents send --to owner` over SSH.
+ */
+export async function forwardOwnerNotifyToPeer(text, channel, meta, opts = {}) {
+    // Cheap, I/O-free gate first: a box that already received a forward, or an
+    // owner channel that isn't the macOS-only rush family, can never forward — so
+    // a normal local success/failure never pays a device-registry disk read.
+    if (process.env[OWNER_FORWARD_GUARD_ENV] === '1')
+        return undefined;
+    if (!isRushBackedTransport(channel, meta))
+        return undefined;
+    const self = opts.self ?? machineId();
+    let devices = opts.devices;
+    if (!devices) {
+        try {
+            devices = Object.values(await loadDevices());
+        }
+        catch {
+            return undefined; // no registry, nothing to forward to
+        }
+    }
+    const plan = planOwnerForward(channel, meta, devices, self);
+    if (plan.candidates.length === 0)
+        return undefined;
+    const send = opts.send ?? sendOnPeer;
+    for (const machine of plan.candidates) {
+        const result = await send(machine, text);
+        if (result?.ok)
+            return result;
+    }
+    return undefined;
+}

package/dist/lib/channels/owner-sink.js

@@ -11,6 +11,13 @@
  * after-the-fact `owner failed: …` line. `agents doctor` had no signal for it,
  * which is exactly the gap RUSH-2258 / RUSH-2262 flagged.
  *
+ * At runtime the owner-delivery lane no longer strands this failure: when local
+ * delivery fails on a box that structurally cannot reach the owner,
+ * `forwardOwnerNotifyToPeer` (owner-forward.ts) hands it to a capable macOS peer
+ * over SSH (PHNX-3303). This finding still stands as a diagnostic — the forward
+ * is best-effort and only lands when a reachable mac peer exists, so a box that
+ * cannot deliver locally is worth surfacing regardless.
+ *
  * This probes the SAME transport the lane uses, from the SAME context doctor runs
  * in, so `agents doctor` can fail loud when this box cannot reach the owner. It is
  * deliberately honest about context: `rush whoami` is what tells a real signed-in

package/dist/lib/claude-statusline.d.ts

@@ -1,4 +1,12 @@
 export declare const CLAUDE_STATUSLINE_COMMAND = "agents __claude-statusline";
+/**
+ * True when `command` re-invokes THIS status-line producer (our private
+ * `__claude-statusline` subcommand) under any binary name or path. Delegating to
+ * such a command is the fork bomb, so both the read side (renderDelegate) and the
+ * write side (installClaudeStatusLine) treat it as "not a real external
+ * producer" and never chain to it.
+ */
+export declare function isStatusLineSelfReference(command: string): boolean;
 interface ClaudeStatusLinePayload {
     cwd?: string;
     workspace?: {
@@ -20,6 +28,7 @@ interface ClaudeStatusLinePayload {
     };
 }
 export declare function ingestClaudeStatusLineUsage(payload: ClaudeStatusLinePayload, versionHome: string): boolean;
+export declare function renderDelegate(payload: string, versionHome: string): string;
 export declare function renderClaudeStatusLine(payload: ClaudeStatusLinePayload, host?: string, delegated?: string): string;
 export declare function runClaudeStatusLine(): Promise<number>;
 export declare function installClaudeStatusLine(versionHome: string): {

package/dist/lib/claude-statusline.js

@@ -7,6 +7,39 @@ import { atomicWriteFileSync } from './fs-atomic.js';
 import { mergeClaudeUsageCacheWindows } from './accounting/usage.js';
 export const CLAUDE_STATUSLINE_COMMAND = 'agents __claude-statusline';
 const DELEGATE_FILE = path.join('.agents', 'claude-statusline-delegate');
+// The private subcommand this feature runs. It is only ever invoked internally,
+// so ANY command that contains it — under any binary name or path (`agents`,
+// `agents-dev`, `ag`, an absolute path, a wrapper) — IS this status-line
+// producer, and delegating to it recurses without bound. Match the subcommand,
+// not the exact `agents __claude-statusline` string, or a delegate seeded with a
+// differently-named binary (e.g. `agents-dev __claude-statusline`) fork-bombs the
+// machine: each render spawns a copy that reads the same delegate and spawns
+// another, forever.
+const STATUSLINE_SUBCOMMAND = '__claude-statusline';
+// Set on the child env before spawning a delegate. If it is already present we
+// are ourselves running as someone's delegate, so we refuse to delegate again —
+// a hard depth-1 backstop that bounds the blast radius even if a self-reference
+// somehow slips past isStatusLineSelfReference(). One hop is the contract:
+// installClaudeStatusLine only ever preserves a single prior command.
+const DELEGATE_GUARD_ENV = 'AGENTS_CLAUDE_STATUSLINE_DELEGATED';
+// A hung or slow delegate must never pin a status-line render open — the render
+// is re-invoked on every refresh, so an unbounded delegate accumulates processes.
+const DELEGATE_TIMEOUT_MS = 5_000;
+/**
+ * True when `command` re-invokes THIS status-line producer (our private
+ * `__claude-statusline` subcommand) under any binary name or path. Delegating to
+ * such a command is the fork bomb, so both the read side (renderDelegate) and the
+ * write side (installClaudeStatusLine) treat it as "not a real external
+ * producer" and never chain to it.
+ */
+export function isStatusLineSelfReference(command) {
+    const trimmed = command.trim();
+    if (!trimmed)
+        return false;
+    if (trimmed === CLAUDE_STATUSLINE_COMMAND)
+        return true;
+    return new RegExp(`(^|\\s)${STATUSLINE_SUBCOMMAND}(\\s|$)`).test(trimmed);
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -48,7 +81,10 @@ export function ingestClaudeStatusLineUsage(payload, versionHome) {
 function delegatePath(versionHome) {
     return path.join(versionHome, DELEGATE_FILE);
 }
-function renderDelegate(payload, versionHome) {
+export function renderDelegate(payload, versionHome) {
+    // Already running as a delegate hop — never spawn another. Hard recursion stop.
+    if (process.env[DELEGATE_GUARD_ENV])
+        return '';
     let command = '';
     try {
         command = fs.readFileSync(delegatePath(versionHome), 'utf8').trim();
@@ -56,13 +92,14 @@ function renderDelegate(payload, versionHome) {
     catch {
         return '';
     }
-    if (!command || command === CLAUDE_STATUSLINE_COMMAND)
+    if (!command || isStatusLineSelfReference(command))
         return '';
     const result = spawnSync(command, {
         shell: true,
         input: payload,
         encoding: 'utf8',
-        env: process.env,
+        env: { ...process.env, [DELEGATE_GUARD_ENV]: '1' },
+        timeout: DELEGATE_TIMEOUT_MS,
     });
     return result.status === 0 ? result.stdout.trim() : '';
 }
@@ -117,11 +154,15 @@ export function installClaudeStatusLine(versionHome) {
             : '';
         if (existing === CLAUDE_STATUSLINE_COMMAND)
             return { changed: false };
-        if (existing) {
+        if (existing && !isStatusLineSelfReference(existing)) {
+            // A genuine third-party status-line command → preserve it as a delegate.
             fs.mkdirSync(path.dirname(delegatePath(versionHome)), { recursive: true });
             atomicWriteFileSync(delegatePath(versionHome), `${existing}\n`);
         }
         else {
+            // Empty, or our own subcommand under a different binary name
+            // (`agents-dev __claude-statusline`, an absolute path, …). Saving that as a
+            // delegate is the fork bomb — never persist it. Drop any prior delegate.
             fs.rmSync(delegatePath(versionHome), { force: true });
         }
         settings.statusLine = {

package/dist/lib/computer/ssh-tunnel.d.ts

@@ -59,11 +59,11 @@ export declare const WIN_HELPER_TOKEN_FILE = "helper-token";
  * the release-asset download (`ensureWinHelperExe`).
  */
 export declare function resolveWinHelperExe(): string | null;
-/** GitHub repo whose `v<version>` releases carry the exe as an asset. */
-export declare const WIN_HELPER_RELEASE_REPO = "phnx-labs/agents-cli";
+/** GitHub repo whose `computer-win/v<version>` releases carry the exe as an asset. */
+export declare const WIN_HELPER_RELEASE_REPO = "phnx-labs/agi-cli";
 /** Cache dir for downloaded helper exes, one subdir per release tag. */
 export declare function winHelperCacheDir(version: string): string;
-/** Release-asset URLs for the exe + its checksum at one exact `v<version>` tag. */
+/** Release-asset URLs for the exe + its checksum at one exact `computer-win/v<version>` tag. */
 export declare function winHelperAssetUrls(version: string): {
     exe: string;
     sha256: string;
@@ -73,10 +73,11 @@ export declare function winHelperAssetUrls(version: string): {
  * a bare hex digest. Throws on anything that does not lead with 64 hex chars.
  */
 /**
- * Download the exe release asset for this CLI version, verify its sha256
+ * Download the exe release asset for this HELPER version, verify its sha256
  * against the published `.sha256` asset, and cache it under the agents cache
- * dir. Only the exact `v<version>` tag is consulted — a missing asset is a
- * hard error naming that tag, never a silent fallback to another release.
+ * dir. Only the exact `computer-win/v<version>` tag is consulted — a missing
+ * asset is a hard error naming that tag, never a silent fallback to another
+ * release. The version is the HELPER's own, not the CLI's.
  */
 export declare function downloadWinHelperExe(version: string): Promise<string>;
 /**

package/dist/lib/computer/ssh-tunnel.js

@@ -127,13 +127,13 @@ export function resolveWinHelperExe() {
     }
     return null;
 }
-/** GitHub repo whose `v<version>` releases carry the exe as an asset. */
-export const WIN_HELPER_RELEASE_REPO = 'phnx-labs/agents-cli';
+/** GitHub repo whose `computer-win/v<version>` releases carry the exe as an asset. */
+export const WIN_HELPER_RELEASE_REPO = 'phnx-labs/agi-cli';
 /** Cache dir for downloaded helper exes, one subdir per release tag. */
 export function winHelperCacheDir(version) {
     return path.join(getCacheDir(), 'computer', 'win-helper', `v${version}`);
 }
-/** Release-asset URLs for the exe + its checksum at one exact `v<version>` tag. */
+/** Release-asset URLs for the exe + its checksum at one exact `computer-win/v<version>` tag. */
 export function winHelperAssetUrls(version) {
     // The helper's OWN tag, not the CLI's. This exe is not an .app bundle so it
     // cannot share helper-download.ts's zip/codesign machinery, but it had the
@@ -148,19 +148,24 @@ export function winHelperAssetUrls(version) {
  * a bare hex digest. Throws on anything that does not lead with 64 hex chars.
  */
 /**
- * Download the exe release asset for this CLI version, verify its sha256
+ * Download the exe release asset for this HELPER version, verify its sha256
  * against the published `.sha256` asset, and cache it under the agents cache
- * dir. Only the exact `v<version>` tag is consulted — a missing asset is a
- * hard error naming that tag, never a silent fallback to another release.
+ * dir. Only the exact `computer-win/v<version>` tag is consulted — a missing
+ * asset is a hard error naming that tag, never a silent fallback to another
+ * release. The version is the HELPER's own, not the CLI's.
  */
 export async function downloadWinHelperExe(version) {
     const cached = path.join(winHelperCacheDir(version), WIN_HELPER_EXE);
     if (fs.existsSync(cached))
         return cached;
-    const tag = `v${version}`;
+    // The SAME tag the URL is built from. This said `v${version}` — the CLI's tag
+    // shape — while winHelperAssetUrls uses helperTag('computer-win', ...), so a
+    // missing asset sent you looking for a tag that does not exist. The mac path
+    // had this fixed already; the Windows path was left behind by the tag split.
+    const tag = helperTag('computer-win', version);
     const { exe: exeUrl, sha256: shaUrl } = winHelperAssetUrls(version);
     const missing = (status, url) => new Error(`no ${WIN_HELPER_EXE} release asset for tag ${tag} (HTTP ${status} on ${url}). ` +
-        `The Windows helper ships as a GitHub release asset per tagged CLI version; ` +
+        `The Windows helper ships as a GitHub release asset on its own helper tag; ` +
         `from a repo checkout you can build it locally instead: bash scripts/build-win.sh`);
     // Checksum first: it is tiny and 404s fast when the tag has no assets.
     const shaRes = await fetch(shaUrl, { signal: AbortSignal.timeout(30_000) });

package/dist/lib/config-keys.d.ts

@@ -28,11 +28,12 @@ export interface ParsedAutoConfigKey {
     scope: 'auto';
     property: 'pool';
 }
-/** A device-scope browser key (self or peer): the profile agents drive, or the
- *  browser that shows the user a page. */
+/** A browser key: the profile agents drive or the browser that shows the user a
+ *  page (both device-scope, self or peer), or `device` — the user-scope fleet
+ *  hub every box drives by default, which is central and never peer-targeted. */
 export interface ParsedBrowserConfigKey {
     scope: 'browser';
-    property: 'profile' | 'viewer';
+    property: 'profile' | 'viewer' | 'device';
     device?: string;
 }
 export interface ParsedProjectConfigKey {

package/dist/lib/config-keys.js

@@ -88,6 +88,9 @@ export function parseConfigKey(key) {
     if (raw === 'browser.viewer') {
         return { scope: 'browser', property: 'viewer' };
     }
+    if (raw === 'browser.device') {
+        return { scope: 'browser', property: 'device' };
+    }
     if (raw === 'project.root') {
         return { scope: 'project', property: 'root' };
     }
@@ -110,7 +113,7 @@ export function parseConfigKey(key) {
         throw new Error(`Invalid auto config key '${key}'. Use auto.pool.`);
     }
     if (raw.startsWith('browser.')) {
-        throw new Error(`Invalid browser config key '${key}'. Use browser.profile or browser.viewer.`);
+        throw new Error(`Invalid browser config key '${key}'. Use browser.profile, browser.viewer, or browser.device.`);
     }
     if (raw.startsWith('project.')) {
         throw new Error(`Invalid project config key '${key}'. Use project.root.`);
@@ -149,7 +152,7 @@ export function listKnownConfigKeys() {
     for (const tier of MODEL_TIERS) {
         keys.push(`run.<agent@version>.tier.${tier}`);
     }
-    keys.push('interactive.host', 'auto.pool', 'browser.profile', 'browser.viewer', 'project.root');
+    keys.push('interactive.host', 'auto.pool', 'browser.profile', 'browser.viewer', 'browser.device', 'project.root');
     for (const prop of DEVICE_CONFIG_PROPERTIES) {
         keys.push(`devices.<name>.${prop}`);
     }
@@ -202,6 +205,10 @@ export function configKeyStorageHint(parsed) {
         case 'auto':
             return 'config.autoPool';
         case 'browser': {
+            if (parsed.property === 'device') {
+                // User scope: one value in the central agents.yaml that syncs fleet-wide.
+                return 'config.defaultBrowserDevice (central agents.yaml; syncs fleet-wide)';
+            }
             const yamlKey = parsed.property === 'viewer' ? 'browserViewer' : 'defaultBrowserProfile';
             return parsed.device
                 ? `devices/${parsed.device}/agents.yaml config.${yamlKey}`

package/dist/lib/device-config.js

@@ -94,6 +94,29 @@ export const CONFIG_KEYS = [
         type: 'string',
         description: 'Browser profile `agents browser start` resolves to without --profile (set via `agents browser use`).',
     },
+    {
+        name: 'browser.device',
+        yamlKey: 'defaultBrowserDevice',
+        // user scope, so a SINGLE value in the central agents.yaml syncs to every box:
+        // the fleet's browser hub. A worker with this set forwards its browser drives
+        // to the hub (as if `--device <hub>` was passed) with no per-command flag, so
+        // every agent shares the hub's one logged-in browser. The hub names itself, so
+        // there it resolves to a self-host and runs locally — which is why one synced
+        // value is safe. Unset = drive this box's own browser (today's behavior).
+        scope: 'user',
+        type: 'string',
+        description: 'Fleet browser hub: the device whose browser `agents browser` drive verbs target by default, with no --device. ' +
+            'The hub itself runs locally; every other box forwards to it. Unset = each box drives its own browser.',
+        validate: (v) => {
+            try {
+                assertValidDeviceName(v);
+                return null;
+            }
+            catch (err) {
+                return err?.message ?? String(err);
+            }
+        },
+    },
     {
         name: 'agents.max-concurrent',
         yamlKey: 'maxAgents',

package/dist/lib/exec.d.ts

@@ -419,6 +419,14 @@ export interface TmuxWrapContext {
     remoteDispatch: boolean;
     /** Whether a tmux binary is on PATH. */
     tmuxAvailable: boolean;
+    /**
+     * True when this process has a real TTY to attach (`stdout.isTTY`).
+     * A piped `agents run --interactive` (session-tracker tests, CI) has none:
+     * wrapping then treating the failed attach as Ctrl-b d leaked live panes
+     * for a week on yosemite-s0 (PHNX-3293). Remote dispatch still wraps
+     * without a TTY — `--device --no-follow` *wants* a detached pane.
+     */
+    hasTty: boolean;
 }
 /**
  * What to do with an interactive spawn. Three outcomes, not two: a run that

package/dist/lib/exec.js

@@ -1210,6 +1210,12 @@ export function resolveTmuxWrap(ctx) {
         return { kind: 'bare' };
     if (ctx.noTmuxEnv)
         return { kind: 'bare' };
+    // Local interactive with no TTY cannot attach. Wrapping anyway creates a
+    // detached pane, attach returns immediately, and resolveAfterAttach treats
+    // the still-alive pane as Ctrl-b d — the session-tracker test leak.
+    // Remote dispatch is the exception: --no-follow *intends* a detached pane.
+    if (!ctx.hasTty && !ctx.remoteDispatch)
+        return { kind: 'bare' };
     if (!ctx.configEnabled && !ctx.remoteDispatch)
         return { kind: 'bare' };
     // Fail loud rather than launch a remote agent that a blink would kill: the
@@ -1668,6 +1674,7 @@ async function spawnAgent(options) {
         configEnabled: isTmuxEnabled(),
         remoteDispatch: process.env[REMOTE_INTERACTIVE_ENV] === '1',
         tmuxAvailable: isTmuxInstalled(),
+        hasTty: !!process.stdout.isTTY,
     });
     if (tmuxWrap.kind === 'undurable') {
         // Refuse rather than start work a blink would destroy. This is the ONLY

package/dist/lib/factory/snapshot.d.ts

@@ -13,7 +13,7 @@ export declare const FACTORY_PROJECTS: readonly [{
     readonly repo: "phnx-labs/rush-cli";
 }, {
     readonly name: "Agents CLI";
-    readonly repo: "phnx-labs/agents-cli";
+    readonly repo: "phnx-labs/agi-cli";
 }, {
     readonly name: "Linear CLI";
     readonly repo: "phnx-labs/linear-cli";

package/dist/lib/factory/snapshot.js

@@ -25,7 +25,7 @@ export const FACTORY_PROJECTS = [
     { name: 'Prix', repo: 'phnx-labs/prix' },
     { name: 'Rush App', repo: 'phnx-labs/rush' },
     { name: 'Rush CLI', repo: 'phnx-labs/rush-cli' },
-    { name: 'Agents CLI', repo: 'phnx-labs/agents-cli' },
+    { name: 'Agents CLI', repo: 'phnx-labs/agi-cli' },
     { name: 'Linear CLI', repo: 'phnx-labs/linear-cli' },
 ];
 const defaults = () => ({

package/dist/lib/feed-broadcast.js

@@ -36,6 +36,7 @@
 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';
 const LEVEL_RANK = { milestone: 0, important: 1 };
 /** Parse a `--level` value; anything unrecognized is a usage error, not a default. */
@@ -473,7 +474,20 @@ async function runChannelSink(sink, meta) {
     if (!provider)
         return { name, ok: false, error };
     const result = await deliverEnvelope(resolved.envelope, meta);
-    return result.ok ? { name, ok: true } : { name, ok: false, error: result.error };
+    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 };
 }
 /**
  * Run the planned sinks. A `command:` sink is a direct spawn with a bounded

package/dist/lib/git.d.ts

@@ -260,6 +260,99 @@ export declare function adoptRepo(source: string, targetDir: string): Promise<{
     backedUp: string[];
     error?: string;
 }>;
+/** Read an origin remote URL from a git dir, or null when there is none. */
+export declare function readOriginUrl(dir: string): string | null;
+/**
+ * Persist the user repo's remote URL to device-local runtime state so a future
+ * adopt-in-place can recover it after a `.git` loss. Best-effort — a write
+ * failure never blocks a sync.
+ */
+export declare function recordUserRepoRemote(dir: string, url: string): void;
+/**
+ * Resolve the user config repo's remote URL WITHOUT hardcoding it, for the
+ * adopt-in-place self-heal. In priority order:
+ *   1. an existing `origin` remote on the dir (a partial repo that kept its
+ *      `.git` but drifted) — the same source `agents repo sync` already reads;
+ *   2. the `AGENTS_USER_REPO_URL` env override (a fresh/never-cloned box);
+ *   3. the device-local record written by a prior healthy sync (a box that lost
+ *      its `.git` but kept `.history/` runtime state).
+ * Returns null when none is known — the caller then guides the operator to
+ * `agents repo pull user <git-url>` instead of crashing.
+ */
+export declare function resolveUserRepoRemoteUrl(dir: string): string | null;
+/**
+ * Decide whether a local top-level `agents.yaml` is a stale install stub that
+ * should be restored from the committed copy, vs. a legitimately customized file
+ * that must be preserved.
+ *
+ * The stub a partial install leaves behind (createDefaultMeta + a few config
+ * writes) is strictly SHORTER than the committed config AND missing whole
+ * top-level blocks the committed one carries (`config:` / `hooks:` — the fleet
+ * browser hub and hook registrations). Device-specific settings live in
+ * `devices/<host>/agents.yaml`, never here, so restoring the top-level file is
+ * safe. A file that already carries those blocks (or is longer) is treated as a
+ * real local edit and left alone — it surfaces as a modified path instead.
+ */
+export declare function isStaleAgentsYamlStub(local: string, committed: string): boolean;
+export interface AdoptInPlaceResult {
+    success: boolean;
+    commit: string;
+    /** Tracked files that were absent locally and materialized from origin/main. */
+    materialized: number;
+    /** True when the stale-stub top-level agents.yaml was restored from origin. */
+    reconciledAgentsYaml: boolean;
+    /**
+     * When agents.yaml was reconciled, the path the PRE-reconcile local copy was
+     * saved to first — so even a false-positive stub match (e.g. a user who
+     * deliberately removed a whole `hooks:`/`config:` block) is recoverable, never
+     * silently lost.
+     */
+    agentsYamlBackup?: string;
+    /**
+     * Tracked paths whose local copy differs from origin/main and was NOT touched
+     * — un-gitignored local edits surfaced rather than silently overwritten.
+     */
+    localEdits: string[];
+    error?: string;
+}
+/**
+ * Adopt an EXISTING, non-git (or origin-less) `~/.agents` directory in place —
+ * git-back it against its remote WITHOUT re-cloning and WITHOUT destroying the
+ * runtime state it carries (`.cache` / `.history` / `scratch` / `.system`, all
+ * gitignored). The self-heal for a partial install (PHNX-3301): the current code
+ * hard-fails with "Not a git repo", and the only manual fix is a destructive
+ * re-clone that wipes that runtime state.
+ *
+ * Plumbing-only, so it never trips the fleet git-guard (no `reset` / `checkout
+ * <branch>` / `stash` / `git config`):
+ *   1. `git init` + point HEAD at `main`.
+ *   2. `git remote add origin <url>`.
+ *   3. `git fetch origin main`.
+ *   4. `git update-ref refs/heads/main origin/main`; set upstream to origin/main.
+ *   5. `git read-tree origin/main` — index = origin/main, working tree untouched.
+ *   6. Materialize only the tracked files MISSING from the working tree
+ *      (`checkout-index` on that set) — existing local files are never overwritten.
+ *   7. Reconcile the top-level `agents.yaml`: restore it from origin/main only
+ *      when the local copy is a stale stub ({@link isStaleAgentsYamlStub}).
+ *
+ * Idempotent: a second run finds the remote/refs already present and simply
+ * re-materializes nothing. Any tracked path with real local edits is returned in
+ * `localEdits` (surfaced, never clobbered).
+ */
+export declare function adoptRepoInPlace(dir: string, remoteUrl: string): Promise<AdoptInPlaceResult>;
+/**
+ * Self-heal entry point for the USER config repo: when `dir` is not a git repo
+ * (or is a repo with no `origin`), resolve its remote URL and adopt it in place;
+ * otherwise return null (nothing to adopt — the normal sync path runs). Returns a
+ * failed result carrying `needsUrl` when the URL cannot be resolved, so the
+ * caller can print the `agents repo pull user <git-url>` remediation instead of
+ * the old "Not a git repo" crash.
+ */
+export declare function adoptUserRepoIfNeeded(dir: string, opts?: {
+    explicitUrl?: string;
+}): Promise<(AdoptInPlaceResult & {
+    needsUrl?: boolean;
+}) | null>;
 /**
  * Check if the repo's origin points to the system repo.
  */