@phnx-labs/agents-cli 1.22.50 → 1.22.52

package/dist/lib/menubar/install-menubar.js

@@ -25,7 +25,7 @@ import { getCliVersion, resolveAgentsBin, resolveInstalledLayout } from '../vers
 import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
 import { compareVersions } from '../agent-spec/primitives.js';
 import { namespacedServiceLabel, serviceManifestHomeEnv, serviceManagerRegistrationAllowed } from '../service-manifest.js';
-import { downloadMenubarHelperApp } from './download-menubar.js';
+import { downloadMenubarHelperApp, menubarHelperCacheDir } from './download-menubar.js';
 import { helperFloor } from '../helper-versions.js';
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
@@ -89,13 +89,42 @@ function installedAppPath() {
 function installedVersionMarkerPath() {
     return path.join(installDir(), '.menubar-version');
 }
-function readInstalledMenubarVersion() {
+/**
+ * What the installed helper IS — deliberately not the CLI's version.
+ *
+ * `source` matters because the two install paths have different notions of
+ * "changed": a release bundle is identified by its helper version, while a local
+ * dev build has none (menubar/scripts/build.sh hardcodes CFBundleShortVersionString),
+ * so it is identified by the source path + mtime it was copied from.
+ */
+/** Version label for a bundle that has none of its own (a local dev build). */
+export const LOCAL_BUILD_LABEL = 'local';
+/**
+ * Read the stamp, tolerating the pre-JSON format.
+ *
+ * Older installs wrote a bare version string — and wrote the CLI's version into
+ * it, which is the bug this replaces. Such a stamp cannot be compared on the
+ * helper axis at all, so it reports `legacy` and is treated as stale exactly
+ * once, which re-stamps it in the new format. That mirrors the existing
+ * null-is-stale rule and is why the migration cannot loop.
+ */
+function readInstalledMenubarStamp() {
+    let raw;
     try {
-        return fs.readFileSync(installedVersionMarkerPath(), 'utf-8').trim() || null;
+        raw = fs.readFileSync(installedVersionMarkerPath(), 'utf-8').trim();
     }
     catch {
         return null;
     }
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && (parsed.source === 'release' || parsed.source === 'local'))
+            return parsed;
+    }
+    catch { /* fall through to legacy */ }
+    return { source: 'legacy', raw };
 }
 /** Executable inside the installed bundle. */
 function installedExecutablePath() {
@@ -425,7 +454,17 @@ export function restartMenubarHelperAfterSwap(uid, ownProcesses, exec = execFile
 function startMenubarServiceFromSource(opts = {}) {
     if (!onDarwin())
         return false;
-    const exec = ensureMenubarAppInstalled({ forceReinstall: true, sourceAppPath: opts.sourceAppPath });
+    // Resolve the source HERE, once, and hand the SAME value to the installer and
+    // the stamp. Passing `opts.sourceAppPath` to both let them disagree: the
+    // installer falls back to `sourceAppPath()` internally, so on the self-heal
+    // path (which passes nothing) it would install a LOCAL build while the stamp
+    // recorded a release version. The next invocation then computed `local`, saw a
+    // kind mismatch, and reinstalled — every time, forever. That is the #2109
+    // storm this whole change exists to stop, so the two must read one variable.
+    const src = opts.sourceAppPath ?? sourceAppPath();
+    if (!src)
+        return false;
+    const exec = ensureMenubarAppInstalled({ forceReinstall: true, sourceAppPath: src });
     if (!exec)
         return false;
     // Never bootstrap a helper macOS will reject at launch: an invalid signature
@@ -441,7 +480,7 @@ function startMenubarServiceFromSource(opts = {}) {
     }
     if (opts.clearOptOut)
         clearMenubarOptOut();
-    installAndStartService(exec);
+    installAndStartService(exec, stampFor(src));
     return true;
 }
 /**
@@ -481,33 +520,121 @@ function clearMenubarOptOut() {
  * particular is what the upgrade self-heal reads to decide staleness, and a
  * path that skipped it would make every later `agents` invocation reinstall.
  */
-function installAndStartService(exec) {
+function installAndStartService(exec, stamp) {
     const plist = servicePlistPath();
     fs.mkdirSync(path.dirname(plist), { recursive: true });
     fs.writeFileSync(plist, generateServicePlist(exec));
     restartMenubarLaunchAgent(process.getuid?.() ?? 0, plist);
     try {
-        fs.writeFileSync(installedVersionMarkerPath(), getCliVersion());
+        fs.writeFileSync(installedVersionMarkerPath(), JSON.stringify(stamp));
+    }
+    catch { /* best effort */ }
+}
+/**
+ * Render a stamp as a comparable/displayable version string.
+ *
+ * A local build has no version of its own, so it reports `local`; the ownership
+ * contest treats that as "not comparable" and falls through to its owner arm,
+ * which is the correct outcome — a dev build must never win a version contest
+ * against a release.
+ */
+export function stampVersionLabel(stamp) {
+    if (!stamp)
+        return null;
+    if (stamp.source === 'release')
+        return stamp.helperVersion;
+    if (stamp.source === 'legacy')
+        return null;
+    return LOCAL_BUILD_LABEL;
+}
+/** What this install would put on disk right now, as a stamp. */
+function availableStamp() {
+    const src = sourceAppPath();
+    // No local bundle means the release path: what would be installed is the
+    // helper version the floor names.
+    return src ? stampFor(src) : { source: 'release', helperVersion: helperFloor('menubar') };
+}
+/** The helper version this install would put on disk right now, for display. */
+function availableHelperLabel() {
+    return stampVersionLabel(availableStamp()) ?? LOCAL_BUILD_LABEL;
+}
+/**
+ * Identify the bundle about to be installed, for the stamp.
+ *
+ * A bundle is a RELEASE iff it sits under the helper's own download cache —
+ * asked of `menubarHelperCacheDir`, not pattern-matched out of the path. A regex
+ * for `/v<x.y.z>/` gets this wrong in both directions: a checkout living under
+ * any directory that happens to contain a version-shaped segment reads as a
+ * release, and a release cache laid out differently reads as local. Either
+ * misclassification flips `source` between invocations, and a kind change is
+ * unconditionally stale — which is a reinstall loop.
+ */
+export function stampFor(resolvedSourceAppPath) {
+    const version = releaseVersionOfCachedBundle(resolvedSourceAppPath);
+    if (version)
+        return { source: 'release', helperVersion: version };
+    let mtime = 0;
+    try {
+        mtime = fs.statSync(resolvedSourceAppPath).mtimeMs;
     }
     catch { /* best effort */ }
+    return { source: 'local', sourceStamp: `${resolvedSourceAppPath}@${mtime}` };
+}
+/**
+ * The helper version a path denotes, iff it is inside that version's cache dir.
+ * Returns null for anything else — including a version-shaped path that is not
+ * actually the cache.
+ */
+export function releaseVersionOfCachedBundle(appPath, cacheDirFor = menubarHelperCacheDir) {
+    // Try EVERY version-shaped segment, not just the leftmost. A cached bundle
+    // under a home or mount path that itself contains an unrelated `vX.Y.Z`
+    // (an nvm dir, a versioned volume) would otherwise match that first segment,
+    // fail the prefix check, and be misclassified as a local build.
+    const resolved = path.resolve(appPath);
+    for (const m of appPath.matchAll(/v(\d+\.\d+\.\d+)/g)) {
+        const expected = path.resolve(cacheDirFor(m[1]));
+        if (resolved === expected || resolved.startsWith(expected + path.sep))
+            return m[1];
+    }
+    return null;
 }
 /**
- * Pure staleness decision (no I/O) so the truth table is unit-testable. The
- * installed service is stale when the helper binary is gone, or when it was
- * installed by a different CLI version than the one now running — a version
- * change is the signal that the plist's baked interpreter/entry/bundle paths
- * and the helper binary itself may have drifted. A null installedVersion
- * (pre-stamp install) counts as stale so old installs get re-stamped once.
+ * Pure staleness decision (no I/O) so the truth table is unit-testable.
+ *
+ * This compares the HELPER axis, not the CLI's. It used to compare the installed
+ * stamp against `getCliVersion()`, which was wrong in both directions once the
+ * helpers gained their own version line: every CLI release made an unchanged
+ * helper look stale and reinstalled it (the #2109 restart storm), while a
+ * genuinely newer helper at the same CLI version never looked stale at all.
+ *
+ * Stale when: the executable is gone; nothing is stamped; the stamp predates the
+ * JSON format (`legacy` — re-stamped once); the install KIND changed
+ * (local <-> release), since a dev build and a release bundle are not
+ * interchangeable; a release install whose available helper version is newer;
+ * or a local install whose source path or mtime moved.
  */
 export function isMenubarStale(opts) {
     if (!opts.execExists)
         return true;
-    return opts.installedVersion !== opts.currentVersion;
+    const { installed, available } = opts;
+    if (!installed)
+        return true;
+    if (installed.source === 'legacy')
+        return true;
+    if (installed.source !== available.source)
+        return true;
+    if (installed.source === 'release' && available.source === 'release') {
+        return compareVersions(available.helperVersion, installed.helperVersion) > 0;
+    }
+    if (installed.source === 'local' && available.source === 'local') {
+        return installed.sourceStamp !== available.sourceStamp;
+    }
+    return true;
 }
 function menubarSetupStale() {
     return isMenubarStale({
-        installedVersion: readInstalledMenubarVersion(),
-        currentVersion: getCliVersion(),
+        installed: readInstalledMenubarStamp(),
+        available: availableStamp(),
         execExists: fs.existsSync(installedExecutablePath()),
     });
 }
@@ -662,7 +789,14 @@ export function mayInstallMenubarHelper(opts) {
     // running, nothing deadlocks.
     if (!opts.ownerEntryExists)
         return opts.sourceIsDeveloperId;
-    if (opts.installedVersion && opts.currentVersion) {
+    // `local` is a KIND marker, not a version — a dev build has none. Comparing it
+    // with compareVersions would order it against real semver arbitrarily and let a
+    // dev build win (or lose) a contest it should not enter. When either side is a
+    // local build the version arm is skipped entirely and the owner arm decides,
+    // which is the correct outcome: ownership, not version, distinguishes them.
+    const comparableVersions = opts.installedVersion && opts.currentVersion &&
+        opts.installedVersion !== LOCAL_BUILD_LABEL && opts.currentVersion !== LOCAL_BUILD_LABEL;
+    if (comparableVersions) {
         const versionOrder = compareVersions(opts.currentVersion, opts.installedVersion);
         if (versionOrder > 0)
             return opts.sourceIsDeveloperId;
@@ -730,8 +864,8 @@ function mayHealMenubar(needsDevIdHeal) {
         ownerEntryExists: Boolean(plistEntry) && fs.existsSync(plistEntry),
         helperExecMissing: !fs.existsSync(installedExecutablePath()),
         needsDevIdHeal,
-        installedVersion: readInstalledMenubarVersion(),
-        currentVersion: getCliVersion(),
+        installedVersion: stampVersionLabel(readInstalledMenubarStamp()),
+        currentVersion: availableHelperLabel(),
         msSinceLastHeal: msSinceLastMenubarHeal(),
         cooldownMs: MENUBAR_TAKEOVER_COOLDOWN_MS,
         sourceIsDeveloperId: Boolean(src) && hasDeveloperIdSignature(src),
@@ -931,7 +1065,24 @@ export async function runMenubarSetup() {
         step('bundle', 'failed', 'could not install the helper bundle');
         return { steps, configured: false, status: getMenubarStatus() };
     }
-    step('bundle', before.installedVersion === getCliVersion() ? 'ok' : 'changed', `${installedAppPath()} (${getCliVersion()})`);
+    // The helper axis here too: this label read "ok" only when the installed
+    // helper's stamp happened to equal the CLI's version, which after this change
+    // is never true on a release install.
+    //
+    // Compare the STAMPS, not their labels. `stampVersionLabel` collapses every
+    // local build to the literal 'local', discarding the mtime — so a real dev
+    // rebuild (which the surrounding logic does correctly reinstall) would print
+    // "ok" and hide that anything changed. That is the same collapse already
+    // excluded in `versionMatches` and `mayInstallMenubarHelper`; this was the
+    // third site and the only one still reading through the lossy label.
+    const bundleStamp = readInstalledMenubarStamp();
+    // Reuse the file's canonical comparator rather than a second, serialization
+    // -based one: `JSON.stringify` was sound only because both stamps come from
+    // `stampFor`, which is an implicit key-order dependency with no reason to
+    // exist when isMenubarStale already answers exactly this question.
+    const bundleUnchanged = bundleStamp !== null &&
+        !isMenubarStale({ installed: bundleStamp, available: availableStamp(), execExists: true });
+    step('bundle', bundleUnchanged ? 'ok' : 'changed', `${installedAppPath()} (${stampVersionLabel(bundleStamp) ?? 'unknown'})`);
     if (!(codesignVerifies(installedAppPath()) && gatekeeperAssesses(installedAppPath()))) {
         step('signature', 'failed', 'not notarized/valid on this machine — refusing to start it (Gatekeeper rejects an ' +
             'un-notarized helper as "damaged"). Upgrade to a notarized build of agents-cli.');
@@ -941,7 +1092,7 @@ export async function runMenubarSetup() {
     // Clear the sticky opt-out: running `setup` is an explicit request for the
     // menu bar, so a stale `menubar disable` must not silently win.
     clearMenubarOptOut();
-    installAndStartService(exec);
+    installAndStartService(exec, stampFor(src ?? undefined));
     step('login item', before.serviceInstalled ? 'ok' : 'changed', `${serviceLabel()} — starts at login, restarts if it dies`);
     // launchd's bootstrap+kickstart is asynchronous; give the status item a beat
     // to claim the lock before counting instances, or `setup` reports zero on a
@@ -1043,8 +1194,9 @@ export function getMenubarStatus() {
         platform: process.platform,
         source: sourceAppPath(),
         installedApp: fs.existsSync(dest) ? dest : null,
-        installedVersion: readInstalledMenubarVersion(),
-        currentVersion: getCliVersion(),
+        installedVersion: stampVersionLabel(readInstalledMenubarStamp()),
+        currentVersion: availableHelperLabel(),
+        cliVersion: getCliVersion(),
         stale: onDarwin() && serviceInstalled && menubarSetupStale(),
         serviceInstalled,
         running: own.length > 0,
@@ -1105,6 +1257,7 @@ export function buildMenubarDoctorReport() {
             installPath: null,
             installedVersion: null,
             currentVersion: getCliVersion(),
+            cliVersion: getCliVersion(),
             versionMatches: false,
             signingIdentity: 'unknown',
             running: false,
@@ -1137,7 +1290,13 @@ export function buildMenubarDoctorReport() {
         installPath: appPath,
         installedVersion: status.installedVersion,
         currentVersion: status.currentVersion,
-        versionMatches: status.installedVersion === status.currentVersion,
+        cliVersion: status.cliVersion,
+        // Two local builds are not a version "mismatch" — neither carries a version.
+        // Reporting one told the user to run `setup` for a difference that does not
+        // exist, which is what made the old hint fire forever.
+        versionMatches: status.installedVersion === LOCAL_BUILD_LABEL && status.currentVersion === LOCAL_BUILD_LABEL
+            ? true
+            : status.installedVersion === status.currentVersion,
         signingIdentity,
         running: status.running,
         staleRunningProcess,

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>;