@phnx-labs/agents-cli 1.22.51 → 1.22.52

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.
  */

package/dist/lib/git.js

@@ -829,6 +829,238 @@ export async function adoptRepo(source, targetDir) {
         return { success: false, commit: '', backedUp: [], error: err.message };
     }
 }
+/**
+ * Device-local record of the user config repo's remote URL, kept OUTSIDE the git
+ * tree so it survives a lost `.git` (`.history/` is gitignored runtime state).
+ * This is what lets `agents repo sync user` adopt-in-place a box that was healthy
+ * once and later lost its checkout, without the operator re-typing the URL.
+ */
+function userRepoRemoteRecordPath(dir) {
+    return path.join(dir, '.history', 'user-repo-remote.json');
+}
+/** Read an origin remote URL from a git dir, or null when there is none. */
+export function readOriginUrl(dir) {
+    if (!isGitRepo(dir))
+        return null;
+    try {
+        const url = execFileSync('git', ['-C', dir, 'config', '--get', 'remote.origin.url'], {
+            encoding: 'utf-8',
+        }).trim();
+        return url || null;
+    }
+    catch {
+        return 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 function recordUserRepoRemote(dir, url) {
+    try {
+        const file = userRepoRemoteRecordPath(dir);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ url }, null, 2) + '\n', { mode: 0o600 });
+    }
+    catch {
+        /* runtime cache write is best-effort */
+    }
+}
+/**
+ * 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 function resolveUserRepoRemoteUrl(dir) {
+    const fromOrigin = readOriginUrl(dir);
+    if (fromOrigin)
+        return fromOrigin;
+    const fromEnv = process.env.AGENTS_USER_REPO_URL?.trim();
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const raw = fs.readFileSync(userRepoRemoteRecordPath(dir), 'utf-8');
+        const url = JSON.parse(raw).url?.trim();
+        if (url)
+            return url;
+    }
+    catch {
+        /* no record yet */
+    }
+    return 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 function isStaleAgentsYamlStub(local, committed) {
+    if (local.trim() === committed.trim())
+        return false;
+    const shorter = local.split('\n').length < committed.split('\n').length;
+    const missingBlock = (/^config:/m.test(committed) && !/^config:/m.test(local)) ||
+        (/^hooks:/m.test(committed) && !/^hooks:/m.test(local));
+    return shorter && missingBlock;
+}
+/**
+ * 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 async function adoptRepoInPlace(dir, remoteUrl) {
+    const empty = {
+        success: false,
+        commit: '',
+        materialized: 0,
+        reconciledAgentsYaml: false,
+        localEdits: [],
+    };
+    const trimmed = remoteUrl.trim();
+    try {
+        // The URL is always a resolved git remote (origin / env / record), never a
+        // `gh:` shorthand — so skip parseSource (which THROWS on ssh:// and rewrites
+        // git@github -> https, breaking SSH-key-only auth). assertSafeGitTransport
+        // still blocks the dangerous transports (ext::, file://, option injection)
+        // while permitting https / ssh / scp-style / a local bare repo.
+        assertSafeGitTransport(trimmed);
+        if (!fs.existsSync(dir)) {
+            return { ...empty, error: `Target directory does not exist: ${dir}` };
+        }
+        // Non-interactive git — fail fast on a missing credential instead of hanging
+        // on a prompt (same rationale as adoptRepo).
+        process.env.GIT_TERMINAL_PROMPT = '0';
+        const git = simpleGit(dir);
+        // 1. init + HEAD -> main (idempotent: init on an existing repo is a no-op).
+        //    Set HEAD via symbolic-ref rather than `init -b main` so it works on git
+        //    < 2.28, and lands on `main` even if the repo already initialized as
+        //    `master`.
+        if (!isGitRepo(dir))
+            await git.init();
+        await git.raw(['symbolic-ref', 'HEAD', 'refs/heads/main']);
+        // 2. origin — add only when absent, so a re-run keeps the existing remote.
+        const remotes = await git.getRemotes(true);
+        if (!remotes.some((r) => r.name === 'origin')) {
+            await git.raw(['remote', 'add', 'origin', trimmed]);
+        }
+        // 3-4. fetch, plant the local main on origin/main, set upstream.
+        await git.raw(['fetch', 'origin', 'main']);
+        await git.raw(['update-ref', 'refs/heads/main', 'origin/main']);
+        await git.raw(['branch', '--set-upstream-to=origin/main', 'main']);
+        // 5. index = origin/main, working tree untouched.
+        await git.raw(['read-tree', 'origin/main']);
+        // 6. Materialize only the tracked files MISSING on disk. Passing the explicit
+        //    missing set (never `checkout-index -a`) guarantees no existing local
+        //    file — a stub agents.yaml, a modified rule — is overwritten. Chunked to
+        //    stay under the argv limit on a cold box where most files are missing.
+        const tracked = (await git.raw(['ls-files', '-z'])).split('\0').filter(Boolean);
+        const missing = tracked.filter((rel) => !fs.existsSync(path.join(dir, rel)));
+        for (let i = 0; i < missing.length; i += 500) {
+            await git.raw(['checkout-index', '-f', '--', ...missing.slice(i, i + 500)]);
+        }
+        // 7. Reconcile a stale-stub top-level agents.yaml from origin/main. `restore`
+        //    is plumbing the git-guard allows; it rewrites only this one path.
+        let reconciledAgentsYaml = false;
+        let agentsYamlBackup;
+        if (tracked.includes('agents.yaml')) {
+            const abs = path.join(dir, 'agents.yaml');
+            const local = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf-8') : '';
+            const committed = await git.raw(['show', 'origin/main:agents.yaml']);
+            if (isStaleAgentsYamlStub(local, committed)) {
+                // The stub heuristic can't perfectly distinguish a partial-install stub
+                // from a user who deliberately removed a whole block, so save the local
+                // copy to gitignored runtime state BEFORE restoring — a false positive is
+                // then recoverable and surfaced, never silent data loss.
+                if (local) {
+                    agentsYamlBackup = path.join(dir, '.history', 'agents.yaml.pre-adopt.bak');
+                    fs.mkdirSync(path.dirname(agentsYamlBackup), { recursive: true });
+                    fs.writeFileSync(agentsYamlBackup, local);
+                }
+                await git.raw(['restore', '--source=origin/main', '--', 'agents.yaml']);
+                reconciledAgentsYaml = true;
+            }
+        }
+        // Surface — never silently keep — any tracked path whose local copy still
+        // differs from origin/main after the reconcile (real un-gitignored edits).
+        const dirty = (await git.raw(['status', '--porcelain', '--untracked-files=no']))
+            .split('\n')
+            .map((l) => l.slice(3).trim())
+            .filter(Boolean);
+        installGithooksSymlinks(dir);
+        recordUserRepoRemote(dir, trimmed);
+        const commit = (await git.raw(['rev-parse', '--short', 'HEAD'])).trim();
+        return {
+            success: true,
+            commit,
+            materialized: missing.length,
+            reconciledAgentsYaml,
+            ...(agentsYamlBackup ? { agentsYamlBackup } : {}),
+            localEdits: dirty,
+        };
+    }
+    catch (err) {
+        return { ...empty, error: err.message };
+    }
+}
+/**
+ * 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 async function adoptUserRepoIfNeeded(dir, opts = {}) {
+    const hasOrigin = isGitRepo(dir) && readOriginUrl(dir) !== null;
+    if (hasOrigin)
+        return null;
+    const url = opts.explicitUrl?.trim() || resolveUserRepoRemoteUrl(dir);
+    if (!url) {
+        return {
+            success: false,
+            commit: '',
+            materialized: 0,
+            reconciledAgentsYaml: false,
+            localEdits: [],
+            needsUrl: true,
+            error: `${displayHomePath(dir)} is not a git repo and no remote URL is known.`,
+        };
+    }
+    return adoptRepoInPlace(dir, url);
+}
 /**
  * Check if the repo's origin points to the system repo.
  */

package/dist/lib/monitors/remote.d.ts

@@ -16,6 +16,7 @@
  * an agent's per-PR watcher is running state, not config, and syncing would push
  * every one of them onto every box — the accumulation this guard exists to stop.
  */
+import { type GatherRemoteAgentsJsonDeps } from '../remote-agents-json.js';
 import type { MonitorConfig } from './config.js';
 /** Recursion guard: a peer answering the fan-out must not fan out again. */
 export declare const NO_MONITOR_FANOUT_ENV = "AGENTS_MONITORS_LOCAL";
@@ -39,9 +40,25 @@ export interface FleetMonitorsResult {
      *  silently treating "we could not ask" as "there is no duplicate". */
     skipped: string[];
 }
+export interface GatherFleetMonitorsOptions {
+    /** When supplied, the fan-out aborts as soon as any peer returns a monitor with
+     *  this behavioral fingerprint. The miss path still waits for every peer so the
+     *  guard can prove absence fleet-wide. */
+    againstFingerprint?: string;
+    /** Optional test seam for the SSH boundary; production uses the real capture. */
+    deps?: GatherRemoteAgentsJsonDeps;
+    /** Optional explicit host list; production omits it and asks the device registry. */
+    hosts?: string[];
+}
 /**
  * Every monitor on every other registered device. Never throws: an unreachable
  * fleet degrades to an empty list plus the names we could not consult, and the
  * caller decides what to say about them.
+ *
+ * When {@link GatherFleetMonitorsOptions.againstFingerprint} is provided, a peer
+ * returning that fingerprint is a definitive clash: the remaining peers are
+ * SIGTERM'd immediately rather than burning the rest of the timeout budget.
+ * Absence of a clash still waits for the full fleet, because uniqueness is only
+ * knowable once every peer has answered.
  */
-export declare function gatherFleetMonitors(): Promise<FleetMonitorsResult>;
+export declare function gatherFleetMonitors(options?: GatherFleetMonitorsOptions): Promise<FleetMonitorsResult>;

package/dist/lib/monitors/remote.js

@@ -17,6 +17,7 @@
  * every one of them onto every box — the accumulation this guard exists to stop.
  */
 import { gatherRemoteAgentsJson } from '../remote-agents-json.js';
+import { monitorFingerprint } from './fingerprint.js';
 /** Recursion guard: a peer answering the fan-out must not fan out again. */
 export const NO_MONITOR_FANOUT_ENV = 'AGENTS_MONITORS_LOCAL';
 /**
@@ -58,15 +59,27 @@ export function parseRemoteMonitors(stdout, machine) {
  * Every monitor on every other registered device. Never throws: an unreachable
  * fleet degrades to an empty list plus the names we could not consult, and the
  * caller decides what to say about them.
+ *
+ * When {@link GatherFleetMonitorsOptions.againstFingerprint} is provided, a peer
+ * returning that fingerprint is a definitive clash: the remaining peers are
+ * SIGTERM'd immediately rather than burning the rest of the timeout budget.
+ * Absence of a clash still waits for the full fleet, because uniqueness is only
+ * knowable once every peer has answered.
  */
-export async function gatherFleetMonitors() {
+export async function gatherFleetMonitors(options = {}) {
     try {
         const result = await gatherRemoteAgentsJson({
             args: ['monitors', 'list', '--json'],
             noFanoutEnv: NO_MONITOR_FANOUT_ENV,
+            hosts: options.hosts,
             parse: parseRemoteMonitors,
             quiet: true,
-        });
+            earlyExit: options.againstFingerprint
+                ? {
+                    isDefinitive: (item) => monitorFingerprint(item.monitor) === options.againstFingerprint,
+                }
+                : undefined,
+        }, options.deps);
         return {
             monitors: result.items,
             skipped: [...result.skipped, ...result.parseFailed],

package/dist/lib/notify.d.ts

@@ -48,6 +48,13 @@ export declare function buildOpenClawNotifyArgs(text: string, opts: {
  * selects the provider per host. A missing owner config or a delivery failure
  * (e.g. openclaw not on PATH) returns a clean `SendResult` error — never a raw
  * ENOENT — so callers surface a consistent, best-effort failure.
+ *
+ * When local delivery fails because THIS box structurally cannot reach the owner
+ * — the rush-backed owner channel is macOS-only, so a headless Linux worker can
+ * never ring the phone (PHNX-3303) — the notify is forwarded over SSH to a
+ * capable fleet peer that DOES have the provider, mirroring the reroute
+ * `agents message` already uses. A successful forward is returned as the result;
+ * if no capable peer is reachable, the original clean local error stands.
  */
 export declare function sendToOwner(text: string, options?: OwnerNotifyOptions): Promise<SendResult>;
 export declare function notifyUrgentBlock(block: OpenBlock, options?: OwnerNotifyOptions): Promise<NotifyResult>;

package/dist/lib/notify.js

@@ -2,6 +2,7 @@ import { readMeta } from './state.js';
 import { getOwnerNotifyFromHumans } from './humans.js';
 import { registerBuiltinProviders } from './channels/providers/index.js';
 import { lookupTransport } from './channels/resolve.js';
+import { forwardOwnerNotifyToPeer } from './channels/owner-forward.js';
 export function formatUrgentBlockMessage(block) {
     const q = block.questions[0];
     const header = q?.header ? `[${q.header}] ` : '';
@@ -38,6 +39,13 @@ export function buildOpenClawNotifyArgs(text, opts) {
  * selects the provider per host. A missing owner config or a delivery failure
  * (e.g. openclaw not on PATH) returns a clean `SendResult` error — never a raw
  * ENOENT — so callers surface a consistent, best-effort failure.
+ *
+ * When local delivery fails because THIS box structurally cannot reach the owner
+ * — the rush-backed owner channel is macOS-only, so a headless Linux worker can
+ * never ring the phone (PHNX-3303) — the notify is forwarded over SSH to a
+ * capable fleet peer that DOES have the provider, mirroring the reroute
+ * `agents message` already uses. A successful forward is returned as the result;
+ * if no capable peer is reachable, the original clean local error stands.
  */
 export async function sendToOwner(text, options = {}) {
     const meta = options.meta ?? readMeta();
@@ -57,11 +65,17 @@ export async function sendToOwner(text, options = {}) {
     if (!provider) {
         return { ok: false, channel, id: target, error };
     }
-    return provider.send(text, {
+    const local = await provider.send(text, {
         target,
         ownerScoped: options.target === undefined,
         dryRun: options.dryRun,
     });
+    // A dry-run never delivers, and an override target is an explicit recipient
+    // (not the fleet-wide owner) — neither should hop to a peer.
+    if (local.ok || options.dryRun || options.target !== undefined)
+        return local;
+    const forwarded = await forwardOwnerNotifyToPeer(text, channel, meta);
+    return forwarded ?? local;
 }
 export async function notifyUrgentBlock(block, options = {}) {
     if (block.notifiedAt) {

package/dist/lib/session/local-tmux-attach.d.ts

@@ -0,0 +1,69 @@
+export type TmuxAliasState = 'not-an-alias' | 'no-server' | 'absent' | 'dead' | 'live';
+/** Shape of the tmux alias the CLI mints for an agent session: `ag-<agent>-<shortid>`.
+ * Delegates to the one canonical matcher beside the name parsers in active.ts. */
+export declare function looksLikeTmuxAlias(selector: string): boolean;
+/**
+ * Classify a selector against the live tmux server. Split from the attach so the
+ * decision is testable against a real tmux server without replacing the caller's
+ * shell (attaching is not something a test can undo).
+ */
+export declare function resolveTmuxAliasState(selector: string, socket?: string): Promise<TmuxAliasState>;
+/**
+ * A local `ag-<agent>-<8hex>` alias names a pane on THIS box. Attach it
+ * without any fleet SSH. `--device` keeps the sweep: the caller scoped
+ * identity to another machine.
+ */
+export declare function shouldAttachLocalTmuxAliasBeforeFleet(selector: string | undefined, hosts: string[]): selector is string;
+/**
+ * Attach a live tmux session named exactly as the selector, without needing the
+ * session index to know anything about it.
+ *
+ * SES-41 requires a `ag-<agent>-<8hex>` tmux alias to resolve, but the alias's
+ * hex is the LAUNCH id, not the harness session id, and for a harness that
+ * writes no `state/sessions/<pid>.json` record there is no mapping back to a
+ * SessionMeta at all. The pane is the thing the user asked for, and its NAME is
+ * sufficient to attach it — so an unattributable session is still reachable
+ * instead of being a dead end that forces raw `tmux -S … attach`.
+ *
+ * Returns false when this is not an alias, the server/session is absent, or
+ * every pane is dead — the caller then continues to normal id resolution.
+ * SES-39's "re-read `pane_dead` immediately before attach" is honoured here:
+ * liveness is queried at attach time, not read from a roster.
+ */
+export declare function attachLiveTmuxAlias(selector: string): Promise<boolean>;
+export type LocalAliasBySuffix = {
+    kind: 'alias';
+    alias: string;
+} | {
+    kind: 'collision';
+    aliases: string[];
+} | {
+    kind: 'none';
+};
+/**
+ * Resolve a bare 8-hex selector (`agents tmux ls`'s hex column, typed without
+ * the `ag-<agent>-` prefix) against LIVE local panes only. Dead panes matching
+ * the suffix are excluded before the uniqueness check — a retained, exited pane
+ * must never compete with (or block) a live one for the same short id.
+ *
+ * Exported for direct testing: `attachLocalLiveSelector` composes this with a
+ * real `attachTmux()` call, which a unit test cannot safely invoke (it takes
+ * over the terminal).
+ */
+export declare function resolveUniqueLocalLiveAliasBySuffix(shortId: string, socket?: string): Promise<LocalAliasBySuffix>;
+/**
+ * The full local gate (PHNX-3292 rule 1): a selector that is either a live
+ * local tmux alias, or a bare 8-hex short id that names exactly one live local
+ * pane, attaches immediately — zero SSH. `--device`/`hosts` scopes identity to
+ * another machine and disables this gate entirely (rule 4).
+ *
+ * Two LIVE local panes matching the same 8-hex suffix fail closed (rule 5): a
+ * collision is reported with both names rather than guessing, and the caller
+ * must not fall through to fleet resolution for a selector that is genuinely
+ * ambiguous ON THIS BOX.
+ *
+ * Returns `false` (never attached, never reported) when the selector does not
+ * name a live local pane at all, so the caller can continue to session-id
+ * resolution / the fleet race.
+ */
+export declare function attachLocalLiveSelector(selector: string | undefined, hosts: string[]): Promise<boolean>;