@phnx-labs/agents-cli 1.20.74 → 1.20.76

package/dist/lib/self-update.d.ts

@@ -55,6 +55,23 @@ export declare function saveUpdateCheck(file: string, latestVersion: string): vo
 export declare function dismissUpdateVersion(file: string, version: string): void;
 /** Whether the cached state warrants an upgrade prompt for a copy running `currentVersion`. */
 export declare function shouldPromptUpgrade(cache: UpdateCheckCache | null, currentVersion: string): boolean;
+/**
+ * The on-disk package root of the copy that is currently running.
+ *
+ * For a plain JS install this is just `<__dirname>/..`. Under the compiled
+ * standalone binary (shipped since 1.20.53) it is not: Bun sets `__dirname` to
+ * its embedded virtual FS, so `<__dirname>/..` yields `/$bunfs` — a path that
+ * exists nowhere. That phantom value was reported as a second install by the
+ * multi-install check, and rejected by deriveGlobalPrefix as "not an
+ * npm-managed install", so every self-upgrade from a compiled copy failed.
+ *
+ * The physical executable is `process.execPath`, which ships inside the
+ * package (`<packageRoot>/dist/bin/agents`). Walk up from it to the directory
+ * whose package.json actually names this package rather than assuming a fixed
+ * depth, so a change to the dist layout surfaces as a clear throw here instead
+ * of a wrong prefix that npm would happily install into.
+ */
+export declare function resolveRunningPackageRoot(dirname: string, execPath?: string): string;
 /**
  * Derive the npm global prefix that owns the install at `packageRoot`.
  *
@@ -133,8 +150,12 @@ export interface AgentsCliInstall {
  *
  * npm bin entries are symlinks that resolve to `<packageRoot>/dist/index.js`
  * (the dev install's `~/.local/bin/agents` chains through the dev prefix to
- * the same shape). Anything that doesn't resolve to a dist/index.js inside a
- * package named @phnx-labs/agents-cli is some other tool and is skipped.
+ * the same shape). A shim pointed at the compiled standalone binary resolves
+ * to `<packageRoot>/dist/bin/agents` instead; that shape counts too, otherwise
+ * the copy that actually runs — the compiled one is typically first on PATH —
+ * is invisible to this scan and its root looks like a separate install.
+ * Anything that resolves to neither shape inside a package named
+ * @phnx-labs/agents-cli is some other tool and is skipped.
  * POSIX-only: Windows npm bins are .cmd wrappers, not symlinks.
  */
 export declare function findAgentsCliInstalls(pathEnv: string): AgentsCliInstall[];

package/dist/lib/self-update.js

@@ -116,6 +116,66 @@ export function shouldPromptUpgrade(cache, currentVersion) {
         compareVersions(cache.latestVersion, currentVersion) > 0 &&
         cache.latestVersion !== cache.dismissed);
 }
+/**
+ * Whether `p` is Bun's embedded virtual filesystem — where a standalone
+ * executable exposes its bundled sources. Nothing there exists on disk: it
+ * cannot be stat'd, installed into, or compared against a real install path.
+ *
+ * Matches the root itself (`/$bunfs`) as well as paths under it, because
+ * `<__dirname>/..` from the embedded entry produces exactly that bare root.
+ * daemon.ts carries a narrower under-the-root-only guard for deciding what may
+ * be supervised; the two are deliberately not shared.
+ */
+function isBunVirtualPath(p) {
+    return /(^|[/\\])\$bunfs([/\\]|$)/.test(p);
+}
+/** Whether `dir` is the root of an installed copy of this package. */
+function isPackageRoot(dir) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+        return pkg.name === NPM_PACKAGE_NAME;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The on-disk package root of the copy that is currently running.
+ *
+ * For a plain JS install this is just `<__dirname>/..`. Under the compiled
+ * standalone binary (shipped since 1.20.53) it is not: Bun sets `__dirname` to
+ * its embedded virtual FS, so `<__dirname>/..` yields `/$bunfs` — a path that
+ * exists nowhere. That phantom value was reported as a second install by the
+ * multi-install check, and rejected by deriveGlobalPrefix as "not an
+ * npm-managed install", so every self-upgrade from a compiled copy failed.
+ *
+ * The physical executable is `process.execPath`, which ships inside the
+ * package (`<packageRoot>/dist/bin/agents`). Walk up from it to the directory
+ * whose package.json actually names this package rather than assuming a fixed
+ * depth, so a change to the dist layout surfaces as a clear throw here instead
+ * of a wrong prefix that npm would happily install into.
+ */
+export function resolveRunningPackageRoot(dirname, execPath = process.execPath) {
+    const fromDirname = path.resolve(dirname, '..');
+    if (!isBunVirtualPath(fromDirname))
+        return fromDirname;
+    if (!execPath || isBunVirtualPath(execPath)) {
+        throw new Error(`Cannot locate the running agents-cli install: __dirname is the Bun virtual path ${fromDirname} ` +
+            `and process.execPath (${execPath || '(empty)'}) is not a real file. ` +
+            `Reinstall with: npm install -g ${NPM_PACKAGE_NAME}`);
+    }
+    let dir = path.dirname(path.resolve(execPath));
+    for (;;) {
+        if (isPackageRoot(dir))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            throw new Error(`Cannot locate the running agents-cli install: no ${NPM_PACKAGE_NAME} package.json above ` +
+                `${execPath}. Reinstall with: npm install -g ${NPM_PACKAGE_NAME}`);
+        }
+        dir = parent;
+    }
+}
 /**
  * Derive the npm global prefix that owns the install at `packageRoot`.
  *
@@ -249,6 +309,24 @@ export function refreshAliasShims(packageRoot) {
         stdio: 'ignore',
     });
 }
+/**
+ * The package root a resolved `agents` entrypoint belongs to, or null when the
+ * path is not an agents-cli entry at all. Two shipped shapes:
+ *   <packageRoot>/dist/index.js    — the JS entry npm links as `agents`
+ *   <packageRoot>/dist/bin/agents  — the compiled standalone executable
+ */
+function packageRootForEntry(real) {
+    const distDir = path.dirname(real);
+    if (path.basename(real) === 'index.js' && path.basename(distDir) === 'dist') {
+        return path.dirname(distDir);
+    }
+    if (path.basename(real) === 'agents' &&
+        path.basename(distDir) === 'bin' &&
+        path.basename(path.dirname(distDir)) === 'dist') {
+        return path.dirname(path.dirname(distDir));
+    }
+    return null;
+}
 /**
  * Scan PATH for `agents` entrypoints and resolve each to the agents-cli
  * package root it executes. More than one distinct root means upgrades,
@@ -257,8 +335,12 @@ export function refreshAliasShims(packageRoot) {
  *
  * npm bin entries are symlinks that resolve to `<packageRoot>/dist/index.js`
  * (the dev install's `~/.local/bin/agents` chains through the dev prefix to
- * the same shape). Anything that doesn't resolve to a dist/index.js inside a
- * package named @phnx-labs/agents-cli is some other tool and is skipped.
+ * the same shape). A shim pointed at the compiled standalone binary resolves
+ * to `<packageRoot>/dist/bin/agents` instead; that shape counts too, otherwise
+ * the copy that actually runs — the compiled one is typically first on PATH —
+ * is invisible to this scan and its root looks like a separate install.
+ * Anything that resolves to neither shape inside a package named
+ * @phnx-labs/agents-cli is some other tool and is skipped.
  * POSIX-only: Windows npm bins are .cmd wrappers, not symlinks.
  */
 export function findAgentsCliInstalls(pathEnv) {
@@ -275,10 +357,9 @@ export function findAgentsCliInstalls(pathEnv) {
         catch {
             continue; // missing or dangling symlink
         }
-        if (path.basename(real) !== 'index.js' || path.basename(path.dirname(real)) !== 'dist') {
+        const packageRoot = packageRootForEntry(real);
+        if (!packageRoot)
             continue;
-        }
-        const packageRoot = path.dirname(path.dirname(real));
         if (seenRoots.has(packageRoot))
             continue;
         let pkg;

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

@@ -1,8 +1,10 @@
 import type { CloudTaskStatus } from '../cloud/types.js';
 import { type PidSessionEntry } from './pid-registry.js';
+import { type HookSessionIndex } from './hook-sessions.js';
 import { type SessionActivity, type AwaitingReason, type StructuredQuestion, type TodoProgress, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
 import type { SessionAttachment } from './types.js';
 import { type SessionProvenance } from './provenance.js';
+import { type Presence } from './detached.js';
 /**
  * Per-PID `lsof` probes run bounded and staggered rather than as one parallel
  * fan-out: a simultaneous system-wide `lsof` burst reads to behavioral EDR
@@ -11,7 +13,15 @@ import { type SessionProvenance } from './provenance.js';
  */
 export declare const LSOF_CONCURRENCY = 4;
 export type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
-export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required';
+/**
+ * `unknown` = the process is alive but we cannot introspect what it is doing —
+ * a live harness whose transcript format we do not parse (everything but
+ * claude/codex), or a resolvable transcript whose `stat` momentarily failed. It
+ * is NOT a synonym for idle: idle is a positive "not mid-turn, not waiting on
+ * you" conclusion drawn from a readable transcript; unknown is the honest "we
+ * can't tell", which we refuse to fake as idle.
+ */
+export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required' | 'unknown';
 export interface ActiveSession {
     context: ActiveContext;
     kind: string;
@@ -71,7 +81,24 @@ export interface ActiveSession {
     attachments?: SessionAttachment[];
     sessionFile?: string;
     startedAtMs?: number;
+    /**
+     * Last-activity epoch — the transcript's last write (mtime). Distinct from
+     * {@link startedAtMs} (session START): a session begun 3h ago but last touched
+     * 20s ago has an old start and a fresh last-activity. The Floor renders "Xs ago"
+     * off this so an idle-but-old session doesn't read as freshly active.
+     */
+    lastActivityMs?: number;
     status: ActiveStatus;
+    /**
+     * Foreground/background presence for the detach/attach model:
+     *   `attached`   — live interactive TUI you're watching;
+     *   `background` — detached: running headless, unattended (via `agents sessions detach`);
+     *   `parked`     — the headless continuation has exited; the transcript is durable.
+     * Absent for ad-hoc headless runs and cloud/team rows, which aren't on the
+     * foreground/background axis. Folded on at the end of {@link getActiveSessions}
+     * from the detach store — never asserted by a source.
+     */
+    presence?: Presence;
     /** How many live PIDs resolve to this same session (subagents/forks). 1 unless collapsed. */
     pidCount?: number;
     /**
@@ -150,6 +177,17 @@ export declare const ACTIVE_SESSION_STALE_MS: number;
  * `.exe` suffix (`claude.exe`), so basename + suffix-strip before the lookup.
  */
 export declare function agentKindFromComm(commRaw: string): string | undefined;
+/**
+ * True when `pid` names a live process AND — when a session's recorded
+ * `startedAtMs` is supplied — that process is plausibly the SAME one, not a later
+ * process that recycled the pid. The OS reuses pids, so a bare
+ * `process.kill(pid, 0)` existence check reports a dead session as alive (a
+ * "zombie") once its pid is handed to an unrelated process. A genuine session
+ * process starts at or before its own recorded start, so a process that began
+ * meaningfully AFTER `startedAtMs` is a reused pid and the session is dead. When
+ * the start time can't be read, we keep the existence answer.
+ */
+export declare function isPidAlive(pid: number, startedAtMs?: number): boolean;
 /**
  * Pick a Claude transcript file within a project dir.
  *
@@ -163,6 +201,34 @@ export declare function agentKindFromComm(commRaw: string): string | undefined;
  * heuristic for a directly-launched agent with no registry entry).
  */
 export declare function pickSessionFile(projectDir: string, sessionId?: string): string | undefined;
+/**
+ * One `stat` → the transcript's creation (≈ session start) and last-write (≈ last
+ * activity) epochs. Both `undefined` when the file can't be stat'd (vanished /
+ * unresolved). `birthtimeMs` can be 0 on filesystems without creation time — coerce
+ * that to `undefined` so callers fall through to a real signal instead of epoch 0.
+ */
+export declare function sessionFileTimes(sessionFile: string | undefined): {
+    birthtimeMs?: number;
+    mtimeMs?: number;
+};
+/**
+ * The ONE place a fallback status is decided when no rich transcript state is
+ * available — a non-Claude/Codex kind we cannot parse, or a Claude/Codex tail
+ * that was empty or unreadable. Honest by construction: it never asserts a status
+ * it cannot justify from a measured signal.
+ *
+ *   - Resolvable transcript, readable mtime → the MEASURED freshness signal:
+ *     written within ACTIVE_MTIME_WINDOW_MS ⇒ `running`, else `idle`.
+ *   - Resolvable transcript whose `stat` throws (file vanished / permission) → we
+ *     genuinely cannot tell ⇒ `unknown`. (This branch previously returned
+ *     `running`, which contradicted the `idle` default one branch up.)
+ *   - No resolvable transcript but the process is alive → alive-but-opaque ⇒
+ *     `unknown`. This is the truthful answer for a live gemini / droid / cursor /
+ *     opencode whose format we don't parse — NOT a fabricated `idle` (which the
+ *     UI reads as "done and waiting"), and it never lies as `running` either.
+ *   - No transcript and the process is not known alive → nothing to report ⇒ `idle`.
+ */
+export declare function resolveFallbackStatus(sessionFile: string | undefined, pidAlive: boolean): ActiveStatus;
 /**
  * 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
@@ -236,14 +302,47 @@ export declare function foldSubordinateAgents(candidates: AgentCandidate[], ppid
  * sort means `headless` (daemon, launchd-spawned, orphan).
  */
 export declare function listUnattributedActive(attributed: Set<number>): Promise<ActiveSession[]>;
+/** One tmux pane's resolved agent identity for the authoritative source. */
+export interface PaneIdentity {
+    agent: 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`). */
+    pid?: number;
+}
+/**
+ * Attribute a single tmux pane to the agent actually running in it.
+ *
+ * The launch registry — written per bare-spawn AND per wrap, each stamped with the
+ * `tmuxPane` it targeted (see src/lib/exec.ts) — is the EXACT, per-pane source of
+ * truth. So an agent spawned into an EXISTING pane (a split, where `$TMUX` is
+ * already set so no new session meta is stamped) is attributed to its OWN launch,
+ * not the session's original agent — closing the gap where such an agent was
+ * dropped by this source and left to the weaker ps-scan fallback. Session-meta
+ * labels remain the fallback for the wrapped origin pane of a session whose
+ * registry entry is absent (a failed best-effort write, or a legacy session that
+ * predates the registry's `tmuxPane` field) — and ONLY for that origin pane
+ * (`meta.pane`), so a split shell pane of a labeled session isn't mis-attributed
+ * the wrapped agent. When `meta.pane` is unknown (attach-existing sessions), any
+ * labeled pane is accepted and the caller's per-session dedupe keeps one.
+ * `source: 'teams'` panes are skipped — teammates are surfaced by listTeamsActive.
+ * Pure so it is unit-tested without tmux.
+ */
+export declare function resolvePaneIdentity(pane: string, meta: {
+    labels?: Record<string, string>;
+    source?: string;
+    pane?: string;
+} | null, liveEntry: PidSessionEntry | undefined, getHookIndex: () => HookSessionIndex): PaneIdentity | undefined;
 /**
  * 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.
+ * tmux-hosted interactive spawns (see src/lib/exec.ts `runInTmux`). Enumerates
+ * every pane on the shared socket and attributes each to the agent running in it
+ * via {@link resolvePaneIdentity}: the per-pane launch registry (exact) first, the
+ * session-meta labels as fallback. Because tmux (not a per-window
+ * `live-terminals.json`) is the source of truth, a tmux-hosted agent is captured
+ * with its exact `%pane` even when the extension registry is stale — INCLUDING an
+ * agent bare-spawned into a split of an existing session, which older logic dropped
+ * (it kept only the first pane per session meta). `source: 'teams'` is skipped.
  */
 export declare function listTmuxAgentSessions(): Promise<ActiveSession[]>;
 /**
@@ -254,4 +353,12 @@ export declare function listTmuxAgentSessions(): Promise<ActiveSession[]>;
  * terminal/headless row for the same session id.
  */
 export declare function getActiveSessions(opts?: ActiveQueryOptions): Promise<ActiveSession[]>;
+/**
+ * Collapse rows that resolve to the *same* session — a session with many
+ * subagent/fork PIDs (all matched to one transcript file) would otherwise print
+ * dozens of identical rows. Keyed by session id, falling back to the transcript
+ * file, then the cloud/run handle, then {@link anonymousWorkerKey}. The first row
+ * wins and carries a `pidCount`.
+ */
+export declare function dedupeBySession(sessions: ActiveSession[]): ActiveSession[];
 export {};