@phnx-labs/agents-cli 1.20.41 → 1.20.42

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

@@ -84,11 +84,35 @@ export interface ActiveSession {
      * (after the --json/--waiting gates) — NOT emitted on the discovery path.
      */
     tmuxTarget?: string;
+    /**
+     * Which host app + tab a tmux-hosted session is currently being VIEWED in,
+     * resolved from the attached tmux client (its terminal PID -> app via
+     * HOST_MATCHERS, its tab via the per-app resolver). `undefined` means no
+     * client is attached — the session is running detached. Transient,
+     * renderer-set (see src/lib/session/viewing-in.ts) — NOT on the discovery path.
+     */
+    viewingIn?: {
+        app: string;
+        tab?: number;
+    };
 }
 export interface ActiveQueryOptions {
     /** Skip the `ps` scan for ad-hoc headless agents. */
     skipHeadless?: boolean;
 }
+/**
+ * Pick a Claude transcript file within a project dir.
+ *
+ * With a CONCRETE session id: return that id's `<id>.jsonl` or undefined — NEVER a
+ * sibling's. Falling back to the newest file here is the bug that made N distinct
+ * co-located sessions (e.g. several editor tabs in one cwd, or two worktree siblings)
+ * all collapse onto ONE file and render identical preview + topic (they look like
+ * duplicate cards). The mtime fallback is only sound when NO id is known.
+ *
+ * With NO id: return the newest `.jsonl` by mtime (the legitimate single-session
+ * heuristic for a directly-launched agent with no registry entry).
+ */
+export declare function pickSessionFile(projectDir: string, sessionId?: string): string | undefined;
 /**
  * Locate the live transcript for an agent process. Claude files are keyed by
  * cwd (+ optional session uuid); Codex files are date-partitioned, so we resolve
@@ -117,6 +141,14 @@ export declare function parseWin32ProcessCsv(out: string): ProcRow[];
  * for testing the bound; production always uses the real `lsof`-backed probe.
  */
 export declare function resolveCwds(pids: number[], probe?: (pid: number) => Promise<string | undefined>): Promise<(string | undefined)[]>;
+/**
+ * Resolve the host app for a single pid by walking its process ancestry with the
+ * same HOST_MATCHERS logic `detectHost` uses. Reads the whole process table per
+ * call, so it's for the low-cardinality renderer path (one tmux client per
+ * session), not a hot loop. Returns undefined when nothing above the pid is a
+ * recognised UI. Exported for the "viewing in <app>" resolver.
+ */
+export declare function hostFromPid(pid: number): Promise<string | undefined>;
 export interface AgentCandidate {
     pid: number;
     kind: string;
@@ -155,9 +187,21 @@ export declare function foldSubordinateAgents(candidates: AgentCandidate[], ppid
  */
 export declare function listUnattributedActive(attributed: Set<number>): Promise<ActiveSession[]>;
 /**
- * Union of all four sources. Teams and terminals spawn actual CLI processes
- * that also show up in `ps`, so headless attribution runs last with the
- * already-attributed PIDs removed.
+ * Agents hosted in the shared-socket tmux server — the authoritative source for
+ * tmux-wrapped interactive spawns (see src/lib/exec.ts `runInTmux`). Enumerates
+ * every pane on the shared socket and keeps those whose session meta was stamped
+ * with `labels.agent` + `labels.sessionId` by the spawn-wrap. Because tmux (not a
+ * per-window `live-terminals.json`) is the source of truth, a tmux-hosted agent is
+ * ALWAYS captured with its exact `%pane` even when the extension registry is stale
+ * or absent. `source: 'teams'` is skipped — teammates are surfaced by listTeamsActive.
+ */
+export declare function listTmuxAgentSessions(): Promise<ActiveSession[]>;
+/**
+ * Union of all sources. Teams and terminals spawn actual CLI processes that
+ * also show up in `ps`, so headless attribution runs last with the already-
+ * attributed PIDs removed. The tmux source goes FIRST into the dedupe so a
+ * tmux-hosted agent's row (which carries the exact `%pane`) wins over a staler
+ * terminal/headless row for the same session id.
  */
 export declare function getActiveSessions(opts?: ActiveQueryOptions): Promise<ActiveSession[]>;
 export {};

package/dist/lib/session/active.js

@@ -120,11 +120,24 @@ function claudeProjectDirName(cwd) {
  * fall back to the most-recent-mtime .jsonl in the project's folder.
  */
 function findClaudeSessionFile(cwd, sessionId) {
-    const projectDir = path.join(HOME, '.claude', 'projects', claudeProjectDirName(cwd));
+    return pickSessionFile(path.join(HOME, '.claude', 'projects', claudeProjectDirName(cwd)), sessionId);
+}
+/**
+ * Pick a Claude transcript file within a project dir.
+ *
+ * With a CONCRETE session id: return that id's `<id>.jsonl` or undefined — NEVER a
+ * sibling's. Falling back to the newest file here is the bug that made N distinct
+ * co-located sessions (e.g. several editor tabs in one cwd, or two worktree siblings)
+ * all collapse onto ONE file and render identical preview + topic (they look like
+ * duplicate cards). The mtime fallback is only sound when NO id is known.
+ *
+ * With NO id: return the newest `.jsonl` by mtime (the legitimate single-session
+ * heuristic for a directly-launched agent with no registry entry).
+ */
+export function pickSessionFile(projectDir, sessionId) {
     if (sessionId) {
         const specific = path.join(projectDir, `${sessionId}.jsonl`);
-        if (fs.existsSync(specific))
-            return specific;
+        return fs.existsSync(specific) ? specific : undefined;
     }
     let files;
     try {
@@ -146,8 +159,12 @@ function findClaudeSessionFile(cwd, sessionId) {
     return best?.path;
 }
 function classifyActivity(sessionFile) {
+    // No resolvable transcript is NOT evidence of activity — default to idle. (Before
+    // the no-borrow fix in pickSessionFile this rarely fired because every terminal
+    // borrowed the newest file; now a session with an unresolved id lands here, and
+    // "running" would wrongly light it up.)
     if (!sessionFile)
-        return 'running';
+        return 'idle';
     try {
         const mtimeMs = fs.statSync(sessionFile).mtimeMs;
         return Date.now() - mtimeMs < ACTIVE_MTIME_WINDOW_MS ? 'running' : 'idle';
@@ -326,7 +343,17 @@ export async function listTerminalsActive() {
     // Build label map from Claude's sessions/*.json for /rename support
     const labelMap = buildClaudeLabelMap();
     return entries.map((t) => {
-        const sessionFile = findSessionFileForKind(t.kind, t.cwd ?? undefined, t.sessionId);
+        // The id cached in live-terminals.json goes stale when Claude rotates its
+        // transcript uuid on resume/compact, so it often no longer matches any
+        // <id>.jsonl. When the pid registry knows this pid's current id, prefer it —
+        // the same source the headless path uses. NOTE: live-terminals.json stores the
+        // SHELL pid, while the by-pid registry is keyed by the AGENT pid, so for
+        // editor-launched terminals this lookup returns undefined today and we fall
+        // back to the stale cached id — the duplicate-card fix comes from
+        // pickSessionFile no longer borrowing a sibling, not from this lookup. Kept as
+        // a forward-looking hook for the cases where the pid does line up.
+        const resolvedId = readPidSessionEntry(t.pid)?.sessionId ?? t.sessionId;
+        const sessionFile = findSessionFileForKind(t.kind, t.cwd ?? undefined, resolvedId);
         // Prefer label from live terminal, fall back to Claude's session label
         const label = t.label ?? (t.sessionId ? labelMap.get(t.sessionId) : undefined) ?? undefined;
         // Extract topic from session file (first meaningful user message)
@@ -539,6 +566,21 @@ function detectHost(pid, procByPid) {
     }
     return undefined;
 }
+/**
+ * Resolve the host app for a single pid by walking its process ancestry with the
+ * same HOST_MATCHERS logic `detectHost` uses. Reads the whole process table per
+ * call, so it's for the low-cardinality renderer path (one tmux client per
+ * session), not a hot loop. Returns undefined when nothing above the pid is a
+ * recognised UI. Exported for the "viewing in <app>" resolver.
+ */
+export async function hostFromPid(pid) {
+    if (!pid || pid < 1)
+        return undefined;
+    const procByPid = new Map();
+    for (const r of await readProcessTable())
+        procByPid.set(r.pid, r);
+    return detectHost(pid, procByPid);
+}
 /** IDE / terminal / multiplexer hosts all count as UI-hosted. Absence = truly headless. */
 const UI_HOSTS = new Set([
     'code', 'cursor', 'codium', 'windsurf',
@@ -703,17 +745,97 @@ export async function listUnattributedActive(attributed) {
     return out;
 }
 /**
- * Union of all four sources. Teams and terminals spawn actual CLI processes
- * that also show up in `ps`, so headless attribution runs last with the
- * already-attributed PIDs removed.
+ * Agents hosted in the shared-socket tmux server — the authoritative source for
+ * tmux-wrapped interactive spawns (see src/lib/exec.ts `runInTmux`). Enumerates
+ * every pane on the shared socket and keeps those whose session meta was stamped
+ * with `labels.agent` + `labels.sessionId` by the spawn-wrap. Because tmux (not a
+ * per-window `live-terminals.json`) is the source of truth, a tmux-hosted agent is
+ * ALWAYS captured with its exact `%pane` even when the extension registry is stale
+ * or absent. `source: 'teams'` is skipped — teammates are surfaced by listTeamsActive.
+ */
+export async function listTmuxAgentSessions() {
+    const { getDefaultSocketPath } = await import('../tmux/paths.js');
+    const { readSessionMeta } = await import('../tmux/session.js');
+    const { runTmux } = await import('../tmux/binary.js');
+    const socket = getDefaultSocketPath();
+    if (!fs.existsSync(socket))
+        return [];
+    let res;
+    try {
+        res = await runTmux({
+            socket,
+            args: ['list-panes', '-a', '-F', '#{pane_id}\t#{session_name}\t#{pane_pid}\t#{pane_current_path}'],
+            throwOnError: false,
+        });
+    }
+    catch {
+        return [];
+    }
+    if (res.code !== 0)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const line of res.stdout.split('\n')) {
+        if (!line.trim())
+            continue;
+        const [pane, sessName, pidRaw, curPath] = line.split('\t');
+        if (!pane || !sessName)
+            continue;
+        const meta = readSessionMeta(sessName);
+        const agent = meta?.labels?.agent;
+        const sessionId = meta?.labels?.sessionId;
+        if (!agent || !sessionId)
+            continue; // only our stamped agent sessions
+        if (meta?.source === 'teams')
+            continue; // teammates come from listTeamsActive
+        if (seen.has(sessionId))
+            continue; // first pane per session wins
+        seen.add(sessionId);
+        const pid = parseInt(pidRaw, 10) || undefined;
+        const cwd = meta?.cwd ?? (curPath || undefined);
+        const sessionFile = findSessionFileForKind(agent, cwd, sessionId);
+        const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
+        const state = computeLiveState(agent, sessionFile, cwd, pid ? isPidAlive(pid) : true);
+        // Provenance is known exactly here (the pane IS a tmux pane) — set it so
+        // enrichProvenance skips it and the locator/reply rails resolve off the pane.
+        const provenance = {
+            host: os.hostname(),
+            transport: 'local',
+            mux: { kind: 'tmux', socket, pane },
+            reply: { rail: 'tmux', target: pane, socket },
+        };
+        out.push(applyState({
+            context: 'terminal',
+            kind: agent,
+            host: 'tmux',
+            pid,
+            sessionId,
+            cwd,
+            topic,
+            sessionFile,
+            provenance,
+        }, state, sessionFile));
+    }
+    return out;
+}
+/**
+ * Union of all sources. Teams and terminals spawn actual CLI processes that
+ * also show up in `ps`, so headless attribution runs last with the already-
+ * attributed PIDs removed. The tmux source goes FIRST into the dedupe so a
+ * tmux-hosted agent's row (which carries the exact `%pane`) wins over a staler
+ * terminal/headless row for the same session id.
  */
 export async function getActiveSessions(opts = {}) {
-    const [teams, terminals, cloud] = await Promise.all([
+    const [tmuxAgents, teams, terminals, cloud] = await Promise.all([
+        listTmuxAgentSessions().catch(() => []),
         listTeamsActive().catch(() => []),
         listTerminalsActive().catch(() => []),
         Promise.resolve(listCloudActive()),
     ]);
     const knownPids = new Set();
+    for (const s of tmuxAgents)
+        if (s.pid)
+            knownPids.add(s.pid);
     for (const s of teams)
         if (s.pid)
             knownPids.add(s.pid);
@@ -721,7 +843,7 @@ export async function getActiveSessions(opts = {}) {
         if (s.pid)
             knownPids.add(s.pid);
     const unattributed = opts.skipHeadless ? [] : await listUnattributedActive(knownPids);
-    const merged = dedupeBySession([...teams, ...terminals, ...cloud, ...unattributed]);
+    const merged = dedupeBySession([...tmuxAgents, ...teams, ...terminals, ...cloud, ...unattributed]);
     await enrichProvenance(merged);
     return merged;
 }

package/dist/lib/session/db.js

@@ -538,37 +538,51 @@ export function upsertSessionsBatch(entries) {
         for (const { meta, content, scan } of items) {
             if (alreadyIndexed.has(meta.id))
                 continue;
-            upsert.run({
-                id: meta.id,
-                short_id: meta.shortId,
-                agent: meta.agent,
-                version: meta.version ?? null,
-                account: meta.account ?? null,
-                timestamp: meta.timestamp,
-                last_activity: resolveLastActivity(meta, scan),
-                project: meta.project ?? null,
-                cwd: meta.cwd ?? null,
-                git_branch: meta.gitBranch ?? null,
-                topic: meta.topic ?? null,
-                label: meta.label ?? null,
-                message_count: meta.messageCount ?? null,
-                token_count: meta.tokenCount ?? null,
-                cost_usd: meta.costUsd ?? null,
-                duration_ms: meta.durationMs ?? null,
-                file_path: meta.filePath,
-                file_mtime_ms: scan?.fileMtimeMs ?? null,
-                file_size: scan?.fileSize ?? null,
-                scanned_at: now,
-                is_team_origin: meta.isTeamOrigin ? 1 : 0,
-                pr_url: meta.prUrl ?? null,
-                pr_number: meta.prNumber ?? null,
-                worktree_slug: meta.worktreeSlug ?? null,
-                ticket_id: meta.ticketId ?? null,
-            });
-            delText.run(meta.id);
-            insText.run(meta.id, meta.label ?? '', meta.topic ?? '', meta.project ?? '', content ?? '');
-            if (scan && meta.filePath) {
-                ledger.run(canonicalLedgerKey(meta.filePath), scan.fileMtimeMs, scan.fileSize, now);
+            // Per-row guard: one malformed session (e.g. a required field that resolves to
+            // NULL) must not abort the whole batch and take down the entire `agents sessions`
+            // listing. A constraint error uses SQLite's ABORT resolution — it reverts only the
+            // failing statement, not the transaction — and the db.transaction wrapper only rolls
+            // back when the error escapes `fn`, so catching + skipping here leaves the txn valid
+            // and committable. We deliberately do NOT stamp the ledger for a skipped row, so the
+            // next scan re-tries it (self-healing once the underlying parser is fixed).
+            try {
+                upsert.run({
+                    id: meta.id,
+                    short_id: meta.shortId,
+                    agent: meta.agent,
+                    version: meta.version ?? null,
+                    account: meta.account ?? null,
+                    timestamp: meta.timestamp,
+                    last_activity: resolveLastActivity(meta, scan),
+                    project: meta.project ?? null,
+                    cwd: meta.cwd ?? null,
+                    git_branch: meta.gitBranch ?? null,
+                    topic: meta.topic ?? null,
+                    label: meta.label ?? null,
+                    message_count: meta.messageCount ?? null,
+                    token_count: meta.tokenCount ?? null,
+                    cost_usd: meta.costUsd ?? null,
+                    duration_ms: meta.durationMs ?? null,
+                    file_path: meta.filePath,
+                    file_mtime_ms: scan?.fileMtimeMs ?? null,
+                    file_size: scan?.fileSize ?? null,
+                    scanned_at: now,
+                    is_team_origin: meta.isTeamOrigin ? 1 : 0,
+                    pr_url: meta.prUrl ?? null,
+                    pr_number: meta.prNumber ?? null,
+                    worktree_slug: meta.worktreeSlug ?? null,
+                    ticket_id: meta.ticketId ?? null,
+                });
+                delText.run(meta.id);
+                insText.run(meta.id, meta.label ?? '', meta.topic ?? '', meta.project ?? '', content ?? '');
+                if (scan && meta.filePath) {
+                    ledger.run(canonicalLedgerKey(meta.filePath), scan.fileMtimeMs, scan.fileSize, now);
+                }
+            }
+            catch (err) {
+                if (process.stderr.isTTY) {
+                    console.error(`Warning: skipped unindexable session ${meta.id}: ${err.message}`);
+                }
             }
         }
     });

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

@@ -150,6 +150,11 @@ export declare function readCodexMeta(filePath: string, resolveAccount?: () => s
 export declare function scanClaudeSession(filePath: string): Promise<ClaudeSessionScan>;
 /** Read up to maxLines non-empty lines from the beginning of a file. */
 export declare function readFirstLines(filePath: string, maxLines: number): Promise<string[]>;
+/** Parse a single Kimi session state.json file to extract session metadata. */
+export declare function readKimiMeta(filePath: string): {
+    meta: SessionMeta;
+    content: string;
+} | null;
 /** Parse a time filter string (relative like '7d' or ISO timestamp) into epoch milliseconds. */
 export declare function parseTimeFilter(input: string): number;
 export {};

package/dist/lib/session/discover.js

@@ -2345,7 +2345,7 @@ async function scanKimiIncremental(onProgress) {
     recordScans(touched);
 }
 /** Parse a single Kimi session state.json file to extract session metadata. */
-function readKimiMeta(filePath) {
+export function readKimiMeta(filePath) {
     let state;
     try {
         state = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
@@ -2362,7 +2362,14 @@ function readKimiMeta(filePath) {
     const topic = title || lastPrompt || undefined;
     const createdAt = typeof state.createdAt === 'string' ? state.createdAt : undefined;
     const updatedAt = typeof state.updatedAt === 'string' ? state.updatedAt : undefined;
-    const timestamp = updatedAt || createdAt;
+    // Coerce to never-null, the same way every other parser does (Rush/Hermes/Droid/…):
+    // a real createdAt/updatedAt still wins; otherwise fall back to the state.json mtime.
+    // Kimi was the lone parser that could yield `undefined`, which binds NULL into
+    // `timestamp TEXT NOT NULL` and aborts the whole batch index. mtime also matches how
+    // the listing already ranks Kimi (last_activity resolves to the file mtime).
+    const stat = safeStatSync(filePath);
+    const timestamp = updatedAt || createdAt
+        || (stat ? stat.mtime.toISOString() : new Date().toISOString());
     const shortId = sessionId.replace(/^session_/, '').slice(0, 8);
     // Try to infer project from session directory path
     // ~/.kimi-code/sessions/<workdir_hash>/session_<uuid>/

package/dist/lib/session/viewing-in.d.ts

@@ -0,0 +1,54 @@
+/**
+ * "Viewing in <app> tab N" for tmux-hosted agent sessions.
+ *
+ * A tmux-wrapped agent (see src/lib/exec.ts `runInTmux`) runs detached on the
+ * shared socket; a terminal only *displays* it while a client is attached. This
+ * resolver answers "which app + tab is looking at this session right now" by
+ * matching the session to its attached tmux client(s) and reusing the app/tab
+ * resolvers we already have:
+ *
+ *   - app  — the client's terminal PID walked up the process ancestry via the
+ *            shared HOST_MATCHERS logic (`hostFromPid`).
+ *   - tab  — per app: Ghostty via `assignGhosttyTabs` (cwd + title match), iTerm
+ *            via the `t<n>` field of the client's `$ITERM_SESSION_ID`, and
+ *            VS Code / Cursor / Codium via the extension-published `tabIndex` in
+ *            live-terminals.json (keyed by session id).
+ *
+ * No client attached => `undefined` (the session is running detached). Every
+ * lookup is best-effort; a miss degrades to `{ app }` with no tab, never throws.
+ */
+import type { TmuxClient } from '../tmux/session.js';
+import type { ActiveSession } from './active.js';
+import { type GhosttySurface } from './ghostty-tabs.js';
+/** Where a tmux-hosted session is currently displayed. */
+export interface ViewingIn {
+    /** Host app of the attached client — 'ghostty', 'iterm', 'code', 'codium', … */
+    app: string;
+    /** 1-based tab number within that app, when it can be resolved. */
+    tab?: number;
+}
+/** Injection seams so `resolveViewingIn` is unit-testable without a live tmux/ps/osascript. */
+export interface ViewingInDeps {
+    /** Ghostty surfaces (window/tab/cwd/title). Enumerated once by the caller and shared. */
+    ghosttySurfaces?: GhosttySurface[];
+    /** pane id -> `session:window.pane`, from `mapPanesToTargets`. Used to find the session name. */
+    paneToTarget?: Map<string, string>;
+    /** client pid -> host app. Defaults to the real `hostFromPid`. */
+    resolveApp?: (pid: number) => Promise<string | undefined>;
+    /** client pid -> raw env. Defaults to reading /proc (Linux) or `ps eww` (macOS). */
+    readClientEnv?: (pid: number) => Promise<Record<string, string> | undefined>;
+    /** session id -> VS Code editor-tab index, from live-terminals.json. Defaults to the real read. */
+    tabIndexForSession?: (sessionId: string | undefined) => number | undefined;
+}
+/**
+ * Resolve where a single tmux-hosted session is being viewed. Returns undefined
+ * when the session isn't tmux-hosted, can't be located, or has no client
+ * attached (detached). Pure aside from the injected (defaulted) probes.
+ */
+export declare function resolveViewingIn(session: ActiveSession, clients: TmuxClient[], deps?: ViewingInDeps): Promise<ViewingIn | undefined>;
+/**
+ * iTerm tab from the attaching client's `$ITERM_SESSION_ID` (`w<n>t<n>p<n>:UUID`).
+ * The `t<n>` field is iTerm2's 0-based tab index; we present it 1-based to match
+ * Ghostty's `index of tab`. Exported for the parser test.
+ */
+export declare function itermTabFromSessionId(value: string | undefined): number | undefined;

package/dist/lib/session/viewing-in.js

@@ -0,0 +1,155 @@
+/**
+ * "Viewing in <app> tab N" for tmux-hosted agent sessions.
+ *
+ * A tmux-wrapped agent (see src/lib/exec.ts `runInTmux`) runs detached on the
+ * shared socket; a terminal only *displays* it while a client is attached. This
+ * resolver answers "which app + tab is looking at this session right now" by
+ * matching the session to its attached tmux client(s) and reusing the app/tab
+ * resolvers we already have:
+ *
+ *   - app  — the client's terminal PID walked up the process ancestry via the
+ *            shared HOST_MATCHERS logic (`hostFromPid`).
+ *   - tab  — per app: Ghostty via `assignGhosttyTabs` (cwd + title match), iTerm
+ *            via the `t<n>` field of the client's `$ITERM_SESSION_ID`, and
+ *            VS Code / Cursor / Codium via the extension-published `tabIndex` in
+ *            live-terminals.json (keyed by session id).
+ *
+ * No client attached => `undefined` (the session is running detached). Every
+ * lookup is best-effort; a miss degrades to `{ app }` with no tab, never throws.
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { readFile } from 'fs/promises';
+import { hostFromPid } from './active.js';
+import { enumerateGhosttyTabs, assignGhosttyTabs } from './ghostty-tabs.js';
+import { getTerminalsDir } from '../state.js';
+const execFileAsync = promisify(execFile);
+/** Apps whose tab index is published by the extension via live-terminals.json. */
+const EDITOR_APPS = new Set(['code', 'cursor', 'codium', 'windsurf']);
+/** The tmux session name a session's pane belongs to, from `session:window.pane`. */
+function sessionNameFor(session, paneToTarget) {
+    const pane = session.provenance?.mux?.pane;
+    const target = (pane && paneToTarget?.get(pane)) ?? session.tmuxTarget;
+    if (!target)
+        return undefined;
+    const name = target.split(':')[0];
+    return name || undefined;
+}
+/**
+ * Resolve where a single tmux-hosted session is being viewed. Returns undefined
+ * when the session isn't tmux-hosted, can't be located, or has no client
+ * attached (detached). Pure aside from the injected (defaulted) probes.
+ */
+export async function resolveViewingIn(session, clients, deps = {}) {
+    if (session.provenance?.mux?.kind !== 'tmux' || !session.provenance.mux.pane)
+        return undefined;
+    const sessName = sessionNameFor(session, deps.paneToTarget);
+    if (!sessName)
+        return undefined;
+    const attached = clients.filter((c) => c.target.split(':')[0] === sessName);
+    if (attached.length === 0)
+        return undefined; // running detached — no viewer
+    const client = attached[0];
+    const resolveApp = deps.resolveApp ?? hostFromPid;
+    const app = (await resolveApp(client.pid)) ?? 'terminal';
+    let tab;
+    if (app === 'ghostty') {
+        tab = await ghosttyTab(session, deps.ghosttySurfaces);
+    }
+    else if (app === 'iterm') {
+        tab = await itermTab(client.pid, deps.readClientEnv ?? readClientEnv);
+    }
+    else if (EDITOR_APPS.has(app)) {
+        const lookup = deps.tabIndexForSession ?? tabIndexFromLiveTerminals;
+        tab = lookup(session.sessionId);
+    }
+    return { app, tab };
+}
+/** Ghostty tab via the existing cwd+title matcher, reusing shared surfaces when provided. */
+async function ghosttyTab(session, surfaces) {
+    const s = surfaces ?? (await enumerateGhosttyTabs());
+    if (s.length === 0)
+        return undefined;
+    // assignGhosttyTabs only considers host === 'ghostty' sessions; use a probe
+    // clone so we don't mutate the real row's host.
+    const probe = { ...session, host: 'ghostty' };
+    return assignGhosttyTabs([probe], s).get(probe);
+}
+/**
+ * iTerm tab from the attaching client's `$ITERM_SESSION_ID` (`w<n>t<n>p<n>:UUID`).
+ * The `t<n>` field is iTerm2's 0-based tab index; we present it 1-based to match
+ * Ghostty's `index of tab`. Exported for the parser test.
+ */
+export function itermTabFromSessionId(value) {
+    if (!value)
+        return undefined;
+    const m = value.match(/t(\d+)/);
+    if (!m)
+        return undefined;
+    const n = parseInt(m[1], 10);
+    return Number.isFinite(n) ? n + 1 : undefined;
+}
+async function itermTab(pid, readEnv) {
+    const env = await readEnv(pid);
+    return itermTabFromSessionId(env?.ITERM_SESSION_ID);
+}
+/** Read a process's env (best-effort): /proc on Linux, `ps eww` on macOS. */
+async function readClientEnv(pid) {
+    if (process.platform === 'linux') {
+        try {
+            const buf = await readFile(`/proc/${pid}/environ`, 'utf8');
+            const env = {};
+            for (const pair of buf.split('\0')) {
+                const eq = pair.indexOf('=');
+                if (eq > 0)
+                    env[pair.slice(0, eq)] = pair.slice(eq + 1);
+            }
+            return env;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (process.platform === 'darwin') {
+        try {
+            const { stdout } = await execFileAsync('ps', ['eww', '-p', String(pid), '-o', 'command='], {
+                encoding: 'utf8',
+                maxBuffer: 1024 * 1024,
+            });
+            // ITERM_SESSION_ID is a single token (no spaces): grab it out of the flat line.
+            const m = stdout.match(/(?:^|\s)ITERM_SESSION_ID=(\S+)/);
+            return m ? { ITERM_SESSION_ID: m[1] } : {};
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * VS Code editor-tab index for a session, from the extension's live-terminals.json
+ * (`tabIndex` per entry — the DATA CONTRACT with the extension teammate). Read
+ * directly (not via active.ts's readLiveTerminals, which strips tabIndex).
+ */
+function tabIndexFromLiveTerminals(sessionId) {
+    if (!sessionId)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(path.join(getTerminalsDir(), 'live-terminals.json'), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return undefined;
+    for (const slice of Object.values(parsed)) {
+        for (const e of (slice?.entries ?? [])) {
+            if (e?.sessionId === sessionId && typeof e.tabIndex === 'number')
+                return e.tabIndex;
+        }
+    }
+    return undefined;
+}

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

@@ -47,7 +47,7 @@ export declare function startSSHTunnel(user: string, host: string, localPort: nu
 export declare const REMOTE_HELPER_PORT = 8765;
 /** Task Scheduler task name for the daemon. Stable so setup/stop pair up. */
 export declare const REMOTE_TASK_NAME = "AgentsComputerHelper";
-/** Basename of the cross-published exe under packages/computer-helper-win/dist. */
+/** Basename of the cross-published exe under native/computer-win/dist. */
 export declare const WIN_HELPER_EXE = "computer-helper-win.exe";
 /**
  * Locate the cross-published Windows daemon exe. Only the local build output is

package/dist/lib/ssh-tunnel.js

@@ -86,7 +86,7 @@ export function startSSHTunnel(user, host, localPort, remotePort, opts = {}) {
 export const REMOTE_HELPER_PORT = 8765;
 /** Task Scheduler task name for the daemon. Stable so setup/stop pair up. */
 export const REMOTE_TASK_NAME = 'AgentsComputerHelper';
-/** Basename of the cross-published exe under packages/computer-helper-win/dist. */
+/** Basename of the cross-published exe under native/computer-win/dist. */
 export const WIN_HELPER_EXE = 'computer-helper-win.exe';
 /**
  * Locate the cross-published Windows daemon exe. Only the local build output is
@@ -95,8 +95,8 @@ export const WIN_HELPER_EXE = 'computer-helper-win.exe';
 export function resolveWinHelperExe() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [
-        // Running from the agents-cli checkout (src/lib -> repo root).
-        path.resolve(here, '..', '..', 'packages', 'computer-helper-win', 'dist', WIN_HELPER_EXE),
+        // Running from the agents-cli checkout. apps/cli/dist/lib -> repo root (4 up) -> native/computer-win.
+        path.resolve(here, '..', '..', '..', '..', 'native', 'computer-win', 'dist', WIN_HELPER_EXE),
         // Bundled with the npm package (dist/lib -> package root).
         path.resolve(here, '..', 'computer-helper-win', WIN_HELPER_EXE),
     ];