@phnx-labs/agents-cli 1.22.51 → 1.22.53

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/active.d.ts

@@ -62,7 +62,7 @@ export declare function attributedSetLostPids(prev: Set<number>, next: Set<numbe
 export declare function filterCachedUnattributed(sessions: ActiveSession[], attributed: Set<number>, alive: (pid: number, startedAtMs?: number) => boolean): ActiveSession[];
 type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
 /** The SessionMeta fields the live-row backfill reads — the enrichment a running process cannot report. */
-export type BackfillMeta = Pick<SessionMeta, 'version' | 'timestamp' | 'label' | 'ticketId' | 'prUrl' | 'prNumber' | 'origin' | 'routineName'>;
+export type BackfillMeta = Pick<SessionMeta, 'version' | 'timestamp' | 'label' | 'ticketId' | 'prUrl' | 'prNumber' | 'origin' | 'routineName' | 'harness'>;
 export declare function backfillActiveRowsFromMeta(sessions: ActiveSession[], metaById: Map<string, BackfillMeta>): void;
 export declare function backfillActiveRowsFromIndex(sessions: ActiveSession[]): void;
 export declare function isRunningLiveSession(s: ActiveSession): boolean;
@@ -112,6 +112,13 @@ export type RecapSource = 'label' | 'last' | 'prompt';
 export interface ActiveSession {
     context: ActiveContext;
     kind: string;
+    /**
+     * Custom harness / profile name when this live process was launched via
+     * `agents run <profile>` (e.g. `deepseek`). `kind` stays the HOST process
+     * (claude) so transcript lookup and live-signal parsers keep working.
+     * `sessions --active` displays this when set (PHNX-2935).
+     */
+    harness?: string;
     /** Specific host app — 'code', 'cursor', 'codium', 'iterm', 'terminal', 'warp', 'tmux', etc. */
     host?: string;
     pid?: number;
@@ -652,6 +659,8 @@ export declare function listUnattributedActive(attributed: Set<number>): Promise
 /** One tmux pane's resolved agent identity for the authoritative source. */
 interface PaneIdentity {
     agent: string;
+    /** Custom harness/profile name from the launch registry, when set. */
+    harness?: string;
     /** Exact session id when resolvable (launch registry, or the hook join). */
     sessionId?: string;
     /** The agent's OS pid from the launch registry (may differ from `pane_pid`). */

package/dist/lib/session/active.js

@@ -166,6 +166,8 @@ export function backfillActiveRowsFromMeta(sessions, metaById) {
             s.origin = m.origin;
         if (!s.routineName && m.routineName)
             s.routineName = m.routineName;
+        if (!s.harness && m.harness)
+            s.harness = m.harness;
     }
 }
 function loadBackfillMetaFor(sessions) {
@@ -1010,6 +1012,7 @@ export async function listTeamsActive(opts = {}) {
         return applyState({
             context: 'teams',
             kind: a.agentType,
+            harness: a.profileName ?? undefined,
             pid: a.pid ?? undefined,
             sessionId: resolvedId,
             machine: offloaded ? execHost : undefined,
@@ -1071,6 +1074,7 @@ export async function listTerminalsActive() {
         return applyState({
             context: 'terminal',
             kind: t.kind,
+            harness: pidEntry?.harness,
             host: detectHost(t.pid, procByPid),
             tty: procByPid.get(t.pid)?.tty,
             pid: t.pid,
@@ -1557,6 +1561,7 @@ async function listUnattributedActiveLive(attributed) {
         out.push(applyState({
             context,
             kind,
+            harness: entry?.harness,
             host,
             tty: procByPid.get(pid)?.tty,
             pid,
@@ -1621,7 +1626,7 @@ export function resolvePaneIdentity(pane, sessName, meta, liveEntry, getHookInde
                 terminalId: liveEntry.terminalId,
             })?.session_id
             ?? nameSessionId;
-        return { agent: liveEntry.agent, sessionId, pid: liveEntry.pid };
+        return { agent: liveEntry.agent, harness: liveEntry.harness, sessionId, pid: liveEntry.pid };
     }
     // No live-registry entry. Session-meta labels are the wrapped-origin fallback;
     // prefer them, then fall back to the name so a pane with neither a registry
@@ -1771,6 +1776,7 @@ export async function listTmuxAgentSessions() {
         out.push(applyState({
             context: 'terminal',
             kind: id.agent,
+            harness: id.harness,
             host: 'tmux',
             pid,
             sessionId: id.sessionId ?? sessionIdFromFile(sessionFile),

package/dist/lib/session/actor-sidecar.d.ts

@@ -7,6 +7,13 @@ export interface SessionActorRecord {
     initiatedBy?: 'human' | 'agent';
     /** Effective permissions mode used by the launcher. */
     mode?: SessionRunMode;
+    /**
+     * Custom harness / profile name when launched via `agents run <profile>`
+     * (e.g. `deepseek`). Joined onto the session index at scan time so a
+     * durable listing can distinguish the profile from its host agent
+     * (PHNX-2935).
+     */
+    harness?: string;
     /** Stable wrapper names that resolve to this native session id. */
     aliases?: string[];
     startedAtMs: number;

package/dist/lib/session/actor-sidecar.js

@@ -40,6 +40,7 @@ function isSafeAlias(alias) {
 function hasRecordData(record) {
     return typeof record.actor === 'string'
         || typeof record.mode === 'string'
+        || typeof record.harness === 'string'
         || (Array.isArray(record.aliases) && record.aliases.some(alias => typeof alias === 'string'));
 }
 function normalizedAliases(aliases) {
@@ -83,6 +84,7 @@ export function writeSessionAliasRecord(sessionId, alias) {
             actor: previous?.actor,
             initiatedBy: previous?.initiatedBy,
             mode: previous?.mode,
+            harness: previous?.harness,
             aliases: normalizedAliases([...(previous?.aliases ?? []), alias]),
             startedAtMs: previous?.startedAtMs ?? Date.now(),
         });

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

@@ -12,7 +12,7 @@ import { type IndexedToolCall } from './tool-calls.js';
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/sessions.md calls the constant the source of truth). */
-export declare const SCHEMA_VERSION = 40;
+export declare const SCHEMA_VERSION = 41;
 /**
  * Bumping this invalidates every cached facet row without touching the schema
  * version, so a change to the extraction logic (a new metric, a corrected bucket)

package/dist/lib/session/db.js

@@ -27,7 +27,7 @@ const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/sessions.md calls the constant the source of truth). */
-export const SCHEMA_VERSION = 40;
+export const SCHEMA_VERSION = 41;
 /**
  * Bump to force `agents sessions backfill resources` to re-derive every
  * session's skill/slash-command tallies on its next run (resource_scan_ledger
@@ -64,6 +64,7 @@ CREATE TABLE IF NOT EXISTS sessions (
   id TEXT PRIMARY KEY,
   short_id TEXT NOT NULL,
   agent TEXT NOT NULL,
+  harness TEXT,
   origin TEXT DEFAULT 'cli',
   routine_name TEXT,
   routine_run_id TEXT,
@@ -1072,6 +1073,18 @@ function migrateSchema(db, fromVersion) {
             db.exec(`ALTER TABLE sessions ADD COLUMN background_shell_count INTEGER`);
         }
     }
+    if (fromVersion < 41) {
+        // v40 -> v41: persist the custom-harness / profile name a run was launched
+        // as (PHNX-2935). Transcript discovery still keys `agent` on the HOST
+        // (the file lives under the host's session dir), so without this column
+        // `agents sessions` cannot tell `agents run deepseek` from a native claude
+        // run. Additive, no ledger flush — the name is launch metadata joined from
+        // the actor sidecar, not parsed from the transcript. Pre-upgrade rows stay
+        // NULL (native / unknown) until a sidecar-backed rescan fills them.
+        const cols = new Set(db.prepare(`PRAGMA table_info(sessions)`).all().map((c) => c.name));
+        if (!cols.has('harness'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN harness TEXT`);
+    }
 }
 /**
  * Stamp `account_key` / `account_org` / `account` on every Claude row from its
@@ -1194,6 +1207,21 @@ export function getDB() {
         db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_machine_ts ON sessions(machine, timestamp DESC)`);
         db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_agent_ts ON sessions(agent, timestamp DESC)`);
     }
+    // harness column: only after the column is guaranteed present.
+    // Fresh SCHEMA (v41) includes the column; older DBs get it from migrate v41.
+    // schema_version can be stamped at SCHEMA_VERSION without the column existing
+    // — getDB writes the marker for any DB whose meta has no row (a hand-built
+    // or partially-created index), and migrateSchema never runs in that path
+    // (`currentVersion === undefined`). If a partial upgrade left schema_version
+    // ahead of the column, repair here so the next upsertSession INSERT naming
+    // `harness` does not throw (PHNX-2935). Same shape as the `machine` repair
+    // above, for the same reason.
+    {
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (!cols.some((c) => c.name === 'harness')) {
+            db.exec(`ALTER TABLE sessions ADD COLUMN harness TEXT`);
+        }
+    }
     // One-shot cleanup of the pre-SQLite JSONL indexes. Safe — nothing reads
     // them anymore. Guarded by a meta flag so we only try once.
     const cleaned = db.prepare(`SELECT value FROM meta WHERE key = 'legacy_indexes_removed'`).get();
@@ -1583,7 +1611,7 @@ export function recordDirScans(entries) {
 }
 const upsertSessionStmt = (db) => db.prepare(`
   INSERT INTO sessions (
-    id, short_id, agent, origin, routine_name, routine_run_id,
+    id, short_id, agent, harness, origin, routine_name, routine_run_id,
     version, account, account_key, account_org, mode, timestamp, last_activity,
     project, cwd, git_branch, topic, label, message_count, token_count,
     output_tokens, input_tokens, cache_read_tokens, cache_write_tokens,
@@ -1594,7 +1622,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     recent_directories_touched, linear_project, linear_project_url, machine,
     actor, initiated_by, used_browser, used_computer
   ) VALUES (
-    @id, @short_id, @agent, @origin, @routine_name, @routine_run_id,
+    @id, @short_id, @agent, @harness, @origin, @routine_name, @routine_run_id,
     @version, @account, @account_key, @account_org, @mode, @timestamp, @last_activity,
     @project, @cwd, @git_branch, @topic, @label, @message_count, @token_count,
     @output_tokens, @input_tokens, @cache_read_tokens, @cache_write_tokens,
@@ -1608,6 +1636,11 @@ const upsertSessionStmt = (db) => db.prepare(`
   ON CONFLICT(id) DO UPDATE SET
     short_id = excluded.short_id,
     agent = excluded.agent,
+    -- Custom harness/profile name is launch metadata, not transcript-derived.
+    -- COALESCE(existing, incoming) keeps a stored stamp on rescan (the scanner
+    -- carries none) and backfills a NULL-first row once the sidecar lands —
+    -- the same write-once pattern as actor/initiated_by (PHNX-2935).
+    harness = COALESCE(sessions.harness, excluded.harness),
     origin = excluded.origin,
     routine_name = excluded.routine_name,
     routine_run_id = excluded.routine_run_id,
@@ -1886,6 +1919,7 @@ export function upsertSession(meta, content, scan) {
         id: meta.id,
         short_id: meta.shortId,
         agent: meta.agent,
+        harness: meta.harness ?? actorRec?.harness ?? null,
         origin: meta.origin ?? 'cli',
         routine_name: meta.routineName ?? null,
         routine_run_id: meta.routineRunId ?? null,
@@ -2081,6 +2115,7 @@ export function upsertSessionsBatch(entries) {
                     id: meta.id,
                     short_id: meta.shortId,
                     agent: meta.agent,
+                    harness: meta.harness ?? actorIndex.get(meta.id)?.harness ?? null,
                     origin: meta.origin ?? 'cli',
                     routine_name: meta.routineName ?? null,
                     routine_run_id: meta.routineRunId ?? null,
@@ -2309,6 +2344,7 @@ function rowToMeta(row) {
         id: row.id,
         shortId: row.short_id,
         agent: row.agent,
+        harness: row.harness ?? undefined,
         origin: (row.origin === 'routine' ? 'routine' : 'cli'),
         routineName: row.routine_name ?? undefined,
         routineRunId: row.routine_run_id ?? undefined,

package/dist/lib/session/discover.js

@@ -26,7 +26,7 @@ import { getConfigSymlinkVersion } from '../installations/shims.js';
 import { SESSION_AGENTS } from './types.js';
 import { deriveShortId } from './short-id.js';
 import { buildClaudeAccountIndex, resolveClaudeAccount } from './claude-accounts.js';
-import { extractSessionTopic, extractSlashCommandName, extractSlashCommandFromToolInput, classifyUserPrompt } from './prompt.js';
+import { extractSessionTopic, extractSlashCommandName, extractSlashCommandFromToolInput, cleanGeneratedSessionLabel } from './prompt.js';
 import { isBackgroundShellStart, isSkillInvocation, extractSkills, extractSlashCommands, isSubAgentTool } from './highlights.js';
 import { parseAntigravity, parseCursor, splitSessionFilePath } from './parse.js';
 import { extractPrUrl, detectWorktree, detectTicket, isPrCreateCommand, detectSpawnedTeam, isTicketCreateTool, extractCreatedTicket, extractRecentDirectoriesTouched, extractTodoProgressFromEvents } from './state.js';
@@ -3268,15 +3268,10 @@ export function finalizeClaudeScan(state) {
     // A topic is the first meaningful prompt. Harness-owned names travel in the
     // separate label field so consumers can replace an early topic once Claude's
     // generated title (or a later `/rename`) arrives.
-    // Claude's generated `ai-title` is derived from the first turn, so a session
-    // opened with a skill gets named after the injected "Base directory for this
-    // skill: …" line instead of its task — and that name then wins on every
-    // surface for the session's whole life. `classifyUserPrompt` reports `skill`
-    // only for that injected line, so collapse it to `/<skill>`. A `/rename`
-    // (`custom-title`) is the user's own words and is never rewritten.
-    const generated = classifyUserPrompt(state.aiTitle ?? '');
-    const label = state.customTitle
-        || (generated.kind === 'skill' ? generated.clean : state.aiTitle);
+    // Generated titles (Claude `ai-title`, Cursor `chatMeta.title`) go through
+    // one shared cleaner so a skill-preamble echo collapses to `/<skill>`. A
+    // `/rename` (`custom-title`) is the user's own words and is never rewritten.
+    const label = state.customTitle || cleanGeneratedSessionLabel(state.aiTitle);
     const worktree = detectWorktree(state.cwd, state.gitBranch);
     const ticket = detectTicket(state.userTexts.join('\n') || undefined, state.gitBranch);
     return {
@@ -4391,8 +4386,8 @@ export function readCursorMeta(filePath, currentVersion) {
         .filter((event) => event.type === 'message' && event.role === 'user' && event.content)
         .map((event) => event.content);
     const firstUserText = userTexts[0];
-    const title = typeof chatMeta?.title === 'string' && chatMeta.title.trim()
-        ? chatMeta.title.trim()
+    const title = typeof chatMeta?.title === 'string'
+        ? cleanGeneratedSessionLabel(chatMeta.title)
         : undefined;
     const meta = {
         id: sessionId,

package/dist/lib/session/live-metadata.js

@@ -37,6 +37,7 @@ export function activeSessionToSessionMeta(active, self, nowMs) {
         id,
         shortId: deriveShortId(id),
         agent: active.kind,
+        harness: active.harness,
         timestamp: new Date(startedMs).toISOString(),
         lastActivity: new Date(lastMs).toISOString(),
         // An empty file path is honest — a just-created session may have no

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

package/dist/lib/session/local-tmux-attach.js

@@ -0,0 +1,164 @@
+/**
+ * Attach a LIVE tmux pane on THIS box, with zero SSH — the local half of the
+ * PHNX-3292 product rule: "first unique match wins, local before fleet."
+ *
+ * `agents tmux ls` prints `ag-<agent>-<8hex>` names. A selector that already
+ * names one of those panes (the full alias, or its bare 8-hex suffix when it
+ * is unique among LIVE local panes) is attached directly — no session index
+ * lookup, no fleet SSH fan-out. `sessions resume`, the deprecated `sessions
+ * attach`, and `sessions focus` all take this gate before anything else.
+ *
+ * Lives outside `commands/` (not in focus.ts) so `sessions-resume.ts` and
+ * `attach.ts` can both import it without a focus.ts <-> sessions-resume.ts
+ * import cycle (focus.ts already imports from sessions-resume.ts).
+ */
+import fs from 'node:fs';
+import chalk from 'chalk';
+import { attachTmux, ensureSessionHookRepaired, getDefaultSocketPath, hasSession, listSessions, runTmux, teardownIfAgentExited } from '../tmux/index.js';
+import { isAgentTmuxAlias } from './types.js';
+/** Width of `SessionMeta.shortId` / the hex an `ag-<agent>-<8hex>` alias embeds. */
+const SHORT_SESSION_ID_RE = /^[0-9a-f]{8}$/i;
+/** 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 function looksLikeTmuxAlias(selector) {
+    return isAgentTmuxAlias(selector);
+}
+/**
+ * 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 async function resolveTmuxAliasState(selector, socket) {
+    if (!looksLikeTmuxAlias(selector))
+        return 'not-an-alias';
+    const sock = socket ?? getDefaultSocketPath();
+    if (!fs.existsSync(sock))
+        return 'no-server';
+    if (!(await hasSession(selector, sock).catch(() => false)))
+        return 'absent';
+    const panes = await runTmux({
+        socket: sock,
+        args: ['list-panes', '-t', `=${selector}`, '-F', '#{pane_dead}'],
+    }).catch(() => undefined);
+    const states = (panes?.stdout ?? '').split('\n').map(s => s.trim()).filter(Boolean);
+    return states.some(d => d === '0') ? 'live' : 'dead';
+}
+/**
+ * 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 function shouldAttachLocalTmuxAliasBeforeFleet(selector, hosts) {
+    return !!selector && hosts.length === 0 && isAgentTmuxAlias(selector);
+}
+/**
+ * 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 async function attachLiveTmuxAlias(selector) {
+    const socket = getDefaultSocketPath();
+    if (await resolveTmuxAliasState(selector, socket) !== 'live')
+        return false;
+    if (!process.stdout.isTTY) {
+        console.error(chalk.red(`"${selector}" is a live tmux session, but attaching needs a TTY.`));
+        console.error(chalk.gray(`  Run it from a terminal, or: agents tmux attach ${selector}`));
+        process.exitCode = 1;
+        return true;
+    }
+    // Already inside a tmux client on this socket — which is the normal state for
+    // an interactive agent session here — MOVE that client instead of nesting a
+    // second one. jumpTo (go.ts) does the same; attaching from inside tmux
+    // otherwise stacks clients rather than taking you to the session.
+    if (process.env.TMUX) {
+        await runTmux({ socket, args: ['switch-client', '-t', `=${selector}`], throwOnError: false }).catch(() => { });
+        console.log(chalk.gray(`Switched this tmux client to ${selector}.`));
+        return true;
+    }
+    console.log(chalk.gray(`Attaching ${selector} — Ctrl-b d to detach.`));
+    // Repair a legacy/stale pane-died hook before handing the session to an
+    // attach client — the 5-min daemon reconcile that used to cover this was
+    // deleted; attach-time repair is what closes the gap now (RUSH-2435).
+    await ensureSessionHookRepaired(selector, socket);
+    const code = await attachTmux({ socket, args: ['attach-session', '-t', `=${selector}`] });
+    await teardownIfAgentExited(selector, socket);
+    process.exitCode = code;
+    return true;
+}
+/**
+ * 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 async function resolveUniqueLocalLiveAliasBySuffix(shortId, socket) {
+    const sock = socket ?? getDefaultSocketPath();
+    if (!fs.existsSync(sock))
+        return { kind: 'none' };
+    let sessions;
+    try {
+        sessions = await listSessions({ socket: sock });
+    }
+    catch {
+        return { kind: 'none' };
+    }
+    const named = sessions
+        .map((session) => session.name)
+        .filter((name) => isAgentTmuxAlias(name) && name.toLowerCase().endsWith(shortId.toLowerCase()));
+    if (named.length === 0)
+        return { kind: 'none' };
+    const states = await Promise.all(named.map(async (name) => ({ name, state: await resolveTmuxAliasState(name, sock) })));
+    const live = states.filter((entry) => entry.state === 'live').map((entry) => entry.name);
+    if (live.length === 0)
+        return { kind: 'none' };
+    if (live.length > 1)
+        return { kind: 'collision', aliases: live };
+    return { kind: 'alias', alias: live[0] };
+}
+/**
+ * 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 async function attachLocalLiveSelector(selector, hosts) {
+    if (shouldAttachLocalTmuxAliasBeforeFleet(selector, hosts)) {
+        return attachLiveTmuxAlias(selector);
+    }
+    if (!selector || hosts.length > 0 || !SHORT_SESSION_ID_RE.test(selector))
+        return false;
+    const found = await resolveUniqueLocalLiveAliasBySuffix(selector);
+    if (found.kind === 'none')
+        return false;
+    if (found.kind === 'collision') {
+        console.error(chalk.red(`"${selector}" matches ${found.aliases.length} live local panes: ${found.aliases.join(', ')}`));
+        console.error(chalk.gray('  Pass the full alias to disambiguate — see: agents tmux ls'));
+        process.exitCode = 1;
+        return true;
+    }
+    return attachLiveTmuxAlias(found.alias);
+}