@phnx-labs/agents-cli 1.20.32 → 1.20.33

package/dist/lib/hosts/option.js

@@ -0,0 +1,19 @@
+/**
+ * Shared `--host` option registrar. Every command that can run on a remote host
+ * declares the flag through here, so its spelling, help text, and companions
+ * (`--remote-cwd`, `--no-tty`, `--any`) stay identical everywhere and show up in
+ * each command's `--help`.
+ *
+ * The flags are consumed centrally by `maybeRunOnHost` (passthrough.ts) *before*
+ * commander parses, so for a real remote run the local action never sees them.
+ * Registering them here still matters: it documents the flag and keeps the local
+ * fall-through (e.g. `--host <this-machine>`) from erroring on an unknown option.
+ */
+/** Attach the standard `--host` flag family to a command and return it (chainable). */
+export function addHostOption(cmd) {
+    return cmd
+        .option('-H, --host <name>', 'Run this command on a registered host (or user@host) over SSH instead of locally. See `agents hosts`.')
+        .option('--remote-cwd <dir>', 'Working directory on the host for --host runs.')
+        .option('--no-tty', 'Force non-interactive output for --host runs even from a terminal.')
+        .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.');
+}

package/dist/lib/hosts/passthrough.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Generic `--host` passthrough — the single choke point that runs an allowlisted
+ * `agents <command>` on a remote host instead of locally, so read-only and
+ * config commands (`view`, `usage`, `cost`, `doctor`, `inspect`, `list`, `sync`)
+ * and the team lifecycle (`teams …`) all gain remote support with no per-command
+ * code. Called once from `index.ts` before commander parses; returns `true` when
+ * it handled the invocation (the local command must then NOT run).
+ *
+ * Transport is SSH (via `ssh-exec.ts`), never a daemon: SSH is the one hardened
+ * choke point already used everywhere, and it gives auth + encryption + host-key
+ * trust for free. Read-only commands stream synchronously (`sshStream`); the one
+ * long-running case — `teams start --watch` — dispatches detached so the remote
+ * supervisor outlives a dropped connection.
+ *
+ * `run` and `sessions` are deliberately absent from the table below: they own
+ * richer `--host` handling in their own command actions (detached run dispatch;
+ * multi-host session fan-out) and must fall through to it.
+ */
+/** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
+export declare function flagValue(args: string[], long: string, short?: string): string | undefined;
+/**
+ * Route `agents <command> … --host <name>` to a remote if the command is
+ * host-routable and a `--host` was given. Returns `false` (run locally) when
+ * there is no `--host`, the command isn't in the table, or the target is this
+ * very machine.
+ *
+ * @param command the resolved subcommand name (`process.argv`'s first non-flag).
+ * @param allArgs `process.argv.slice(2)` — the command name followed by its args.
+ */
+export declare function maybeRunOnHost(command: string, allArgs: string[]): Promise<boolean>;

package/dist/lib/hosts/passthrough.js

@@ -0,0 +1,141 @@
+/**
+ * Generic `--host` passthrough — the single choke point that runs an allowlisted
+ * `agents <command>` on a remote host instead of locally, so read-only and
+ * config commands (`view`, `usage`, `cost`, `doctor`, `inspect`, `list`, `sync`)
+ * and the team lifecycle (`teams …`) all gain remote support with no per-command
+ * code. Called once from `index.ts` before commander parses; returns `true` when
+ * it handled the invocation (the local command must then NOT run).
+ *
+ * Transport is SSH (via `ssh-exec.ts`), never a daemon: SSH is the one hardened
+ * choke point already used everywhere, and it gives auth + encryption + host-key
+ * trust for free. Read-only commands stream synchronously (`sshStream`); the one
+ * long-running case — `teams start --watch` — dispatches detached so the remote
+ * supervisor outlives a dropped connection.
+ *
+ * `run` and `sessions` are deliberately absent from the table below: they own
+ * richer `--host` handling in their own command actions (detached run dispatch;
+ * multi-host session fan-out) and must fall through to it.
+ */
+import chalk from 'chalk';
+import { assertValidSshTarget, sshStream } from '../ssh-exec.js';
+import { resolveHost, resolveHostByCap } from './registry.js';
+import { sshTargetFor } from './types.js';
+import { dispatchAgentsCommand } from './dispatch.js';
+import { stripRoutingFlags, buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, } from './remote-cmd.js';
+import { machineId } from '../session/sync/config.js';
+const REMOTE_PASSTHROUGH = {
+    view: {},
+    usage: {},
+    cost: {},
+    doctor: {},
+    inspect: {},
+    list: {},
+    sync: { nonInteractive: ['--yes'] },
+    teams: {},
+};
+/** `--no-tty` is stripped like the routing flags but carries no value. */
+const STRIP_SPECS = [...HOST_ROUTING_SPECS, { long: 'no-tty', takesValue: false }];
+/** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
+export function flagValue(args, long, short) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === `--${long}` || (short && a === `-${short}`))
+            return args[i + 1];
+        if (a.startsWith(`--${long}=`))
+            return a.slice(long.length + 3);
+        if (short && a.startsWith(`-${short}=`))
+            return a.slice(short.length + 2);
+        if (short && new RegExp(`^-${short}(.+)`).test(a))
+            return a.slice(2);
+    }
+    return undefined;
+}
+/** Synthesize a `Host` for a raw `user@host` / bare-alias target (not enrolled). */
+function syntheticHost(target) {
+    const at = target.indexOf('@');
+    if (at !== -1) {
+        return { name: target, provider: 'local', source: 'inline', user: target.slice(0, at), address: target.slice(at + 1) };
+    }
+    // Bare name: ssh resolves it from ~/.ssh/config, or connects to it as a hostname.
+    return { name: target, provider: 'local', source: 'ssh-config' };
+}
+/** Resolve a `--host` value to a Host: enrolled name → capability tag → raw target. */
+async function resolveTargetHost(name, any) {
+    const enrolled = await resolveHost(name);
+    if (enrolled)
+        return enrolled;
+    try {
+        return await resolveHostByCap(name, any);
+    }
+    catch (e) {
+        // "Multiple hosts tagged …" is actionable — surface it. "No host tagged" falls
+        // through to treating the value as a literal ssh target.
+        if (e instanceof Error && e.message.startsWith('Multiple hosts'))
+            throw e;
+    }
+    assertValidSshTarget(name); // rejects injection / flag-smuggling before it reaches ssh
+    return syntheticHost(name);
+}
+/**
+ * Route `agents <command> … --host <name>` to a remote if the command is
+ * host-routable and a `--host` was given. Returns `false` (run locally) when
+ * there is no `--host`, the command isn't in the table, or the target is this
+ * very machine.
+ *
+ * @param command the resolved subcommand name (`process.argv`'s first non-flag).
+ * @param allArgs `process.argv.slice(2)` — the command name followed by its args.
+ */
+export async function maybeRunOnHost(command, allArgs) {
+    const spec = REMOTE_PASSTHROUGH[command];
+    if (!spec)
+        return false;
+    const hostName = flagValue(allArgs, 'host', 'H');
+    if (!hostName)
+        return false;
+    // Running against your own machine is just a local run — skip the SSH round-trip.
+    // `machineId()` is the same self-identifier the device registry and session
+    // sync use (lowercased short hostname); compare case-insensitively.
+    if (hostName.toLowerCase() === machineId())
+        return false;
+    const remoteCwd = flagValue(allArgs, 'remote-cwd');
+    const any = allArgs.includes('--any');
+    let host;
+    try {
+        host = await resolveTargetHost(hostName, any);
+    }
+    catch (e) {
+        console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+        process.exitCode = 1;
+        return true;
+    }
+    const target = sshTargetFor(host);
+    // Interactive only when our own stdout is a terminal and the caller didn't opt
+    // out — otherwise force the command's non-interactive path so no half-drawn
+    // picker is piped into a file or another program.
+    const interactive = !!process.stdout.isTTY && !allArgs.includes('--no-tty');
+    let forwarded = stripRoutingFlags(allArgs, STRIP_SPECS);
+    if (!interactive && spec.nonInteractive)
+        forwarded = [...forwarded, ...spec.nonInteractive];
+    // The one long-running case: keep the remote team supervisor alive past a
+    // disconnect by dispatching it detached (nohup), still streaming live.
+    const isWatchedTeamStart = command === 'teams' && forwarded[1] === 'start' && forwarded.includes('--watch');
+    if (isWatchedTeamStart) {
+        try {
+            const { exitCode } = await dispatchAgentsCommand(host, { forwardedArgs: forwarded, remoteCwd });
+            process.exitCode = exitCode && exitCode > 0 ? exitCode : 0;
+        }
+        catch (e) {
+            console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+            process.exitCode = 1;
+        }
+        return true;
+    }
+    const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd);
+    const code = sshStream(target, remoteCmd, { tty: interactive, multiplex: true });
+    if (code === 255) {
+        console.error(chalk.red(`${host.name}: unreachable over SSH (asleep, offline, or host key changed?).`) +
+            chalk.gray(' Check: agents hosts check ' + host.name));
+    }
+    process.exitCode = code;
+    return true;
+}

package/dist/lib/hosts/remote-cmd.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure argv helpers for `--host` passthrough — build the remote `agents …`
+ * invocation and strip the local-only routing flags before forwarding.
+ *
+ * Kept free of any SSH/process side effects so the two-layer quoting and the
+ * flag-stripping edge cases (glued short forms, `=value`, variadic) are unit
+ * testable without a live host. The transport itself lives in `ssh-exec.ts`
+ * (`sshExec`/`sshStream`); orchestration lives in `passthrough.ts`.
+ */
+/** A flag to strip from a forwarded argv, with whether it consumes a value. */
+export interface StripSpec {
+    /** Long form without leading dashes, e.g. `host`, `remote-cwd`. */
+    long: string;
+    /** Optional single-letter short form without the dash, e.g. `H`. */
+    short?: string;
+    /** True when the flag takes a following value token (`--host <name>`). */
+    takesValue: boolean;
+}
+/**
+ * Remove routing flags (and their values) from a command's args, leaving the
+ * rest untouched and in order so they forward verbatim to the remote binary.
+ * Handles every form commander accepts: `--host h`, `--host=h`, `-H h`, `-H=h`,
+ * and the glued short form `-Hh`.
+ *
+ * @param args the command's args (already past the command name).
+ */
+export declare function stripRoutingFlags(args: string[], specs: StripSpec[]): string[];
+/** The routing flags every `--host`-capable command shares. */
+export declare const HOST_ROUTING_SPECS: StripSpec[];
+/**
+ * Build the single command string for `ssh <target> <cmd>`. The forwarded args
+ * are quoted for the inner login shell, then the whole `agents …` invocation is
+ * quoted again so it survives `bash -lc <...>` — `bash -lc` so the remote login
+ * PATH resolves `agents`. An optional `cd` runs first for `--remote-cwd`.
+ */
+export declare function buildRemoteAgentsInvocation(forwardedArgs: string[], remoteCwd?: string): string;

package/dist/lib/hosts/remote-cmd.js

@@ -0,0 +1,56 @@
+/**
+ * Pure argv helpers for `--host` passthrough — build the remote `agents …`
+ * invocation and strip the local-only routing flags before forwarding.
+ *
+ * Kept free of any SSH/process side effects so the two-layer quoting and the
+ * flag-stripping edge cases (glued short forms, `=value`, variadic) are unit
+ * testable without a live host. The transport itself lives in `ssh-exec.ts`
+ * (`sshExec`/`sshStream`); orchestration lives in `passthrough.ts`.
+ */
+import { shellQuote } from '../ssh-exec.js';
+/**
+ * Remove routing flags (and their values) from a command's args, leaving the
+ * rest untouched and in order so they forward verbatim to the remote binary.
+ * Handles every form commander accepts: `--host h`, `--host=h`, `-H h`, `-H=h`,
+ * and the glued short form `-Hh`.
+ *
+ * @param args the command's args (already past the command name).
+ */
+export function stripRoutingFlags(args, specs) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const spec = specs.find((s) => {
+            if (a === `--${s.long}` || a.startsWith(`--${s.long}=`))
+                return true;
+            if (s.short && (a === `-${s.short}` || a.startsWith(`-${s.short}=`) || new RegExp(`^-${s.short}.+`).test(a)))
+                return true;
+            return false;
+        });
+        if (!spec) {
+            out.push(a);
+            continue;
+        }
+        // Consume a separate value token only for the exact-match (space-separated) forms.
+        const isExact = a === `--${spec.long}` || (spec.short && a === `-${spec.short}`);
+        if (spec.takesValue && isExact && i + 1 < args.length)
+            i++;
+    }
+    return out;
+}
+/** The routing flags every `--host`-capable command shares. */
+export const HOST_ROUTING_SPECS = [
+    { long: 'host', short: 'H', takesValue: true },
+    { long: 'remote-cwd', takesValue: true },
+];
+/**
+ * Build the single command string for `ssh <target> <cmd>`. The forwarded args
+ * are quoted for the inner login shell, then the whole `agents …` invocation is
+ * quoted again so it survives `bash -lc <...>` — `bash -lc` so the remote login
+ * PATH resolves `agents`. An optional `cd` runs first for `--remote-cwd`.
+ */
+export function buildRemoteAgentsInvocation(forwardedArgs, remoteCwd) {
+    const inner = ['agents', ...forwardedArgs].map(shellQuote).join(' ');
+    const withCwd = remoteCwd ? `cd ${shellQuote(remoteCwd)} && ${inner}` : inner;
+    return `bash -lc ${shellQuote(withCwd)}`;
+}

package/dist/lib/secrets/bundles.js

@@ -21,7 +21,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
+import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, keychainUsesFileFallback, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
 import { fileStore } from './filestore.js';
 import { emit } from '../events.js';
 import { readMeta } from '../state.js';
@@ -379,25 +379,34 @@ export function listBundles() {
     // prompt instead of N. Bundle metadata items carry user-presence ACLs (same
     // as secret values), so a naive loop over readBundle() spawns a fresh
     // LAContext per item — meaning N biometric prompts for `secrets list`.
-    let keychainServices = [];
-    try {
-        keychainServices = listKeychainItems(BUNDLE_META_PREFIX);
-    }
-    catch {
-        keychainServices = [];
-    }
-    const keychainNames = keychainServices
-        .map((s) => s.slice(BUNDLE_META_PREFIX.length))
-        .filter((n) => BUNDLE_NAME_PATTERN.test(n));
-    if (keychainNames.length > 0) {
-        const fetched = getKeychainTokens(keychainNames.map(bundleMetaItem));
-        for (const name of keychainNames) {
-            const json = fetched.get(bundleMetaItem(name));
-            if (json === undefined)
-                continue;
-            const bundle = parseBundleMeta(name, json, 'keychain');
-            if (bundle)
-                out.push(bundle);
+    //
+    // SKIP this entirely when the keychain backend is routing to the encrypted
+    // file store (Linux headless / locked-collection fallback): there,
+    // listKeychainItems() returns the SAME items the file enumeration below
+    // reads, so running both would list every file-backed bundle twice — once
+    // mislabeled `keychain`, once correctly `[file]`. Under the fallback the
+    // file store is the single source of truth, so the block below covers all.
+    if (!keychainUsesFileFallback()) {
+        let keychainServices = [];
+        try {
+            keychainServices = listKeychainItems(BUNDLE_META_PREFIX);
+        }
+        catch {
+            keychainServices = [];
+        }
+        const keychainNames = keychainServices
+            .map((s) => s.slice(BUNDLE_META_PREFIX.length))
+            .filter((n) => BUNDLE_NAME_PATTERN.test(n));
+        if (keychainNames.length > 0) {
+            const fetched = getKeychainTokens(keychainNames.map(bundleMetaItem));
+            for (const name of keychainNames) {
+                const json = fetched.get(bundleMetaItem(name));
+                if (json === undefined)
+                    continue;
+                const bundle = parseBundleMeta(name, json, 'keychain');
+                if (bundle)
+                    out.push(bundle);
+            }
         }
     }
     // File-backed bundles live in the encrypted-file store. Enumeration is a

package/dist/lib/secrets/index.d.ts

@@ -86,6 +86,17 @@ export declare function getKeychainTokens(items: string[]): Map<string, string>;
 export declare function setKeychainToken(item: string, value: string): void;
 /** Delete a keychain/keyring item. Returns true if it existed. Never prompts for biometry. */
 export declare function deleteKeychainToken(item: string): boolean;
+/**
+ * True when the active keychain backend transparently routes reads/writes to
+ * the encrypted-file store instead of the OS credential store. This only
+ * happens on Linux under the headless / locked-collection fallback
+ * (src/lib/secrets/linux.ts); macOS and the test backend always return false.
+ *
+ * Callers that ALSO enumerate the file store directly (e.g. `listBundles`)
+ * use this to avoid double-counting: under the fallback `listKeychainItems`
+ * and the direct file enumeration return the same items.
+ */
+export declare function keychainUsesFileFallback(): boolean;
 /** Enumerate keychain/keyring item names starting with the given prefix. */
 export declare function listKeychainItems(prefix: string): string[];
 /**

package/dist/lib/secrets/index.js

@@ -23,7 +23,7 @@ import { execFileSync, spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { linuxBackend } from './linux.js';
+import { linuxBackend, usesFileFallback as linuxUsesFileFallback } from './linux.js';
 import { getKeychainHelperPath } from './install-helper.js';
 const SERVICE_PREFIX = 'agents-cli';
 const SECRETS_ITEM_PREFIX = `${SERVICE_PREFIX}.secrets.`;
@@ -278,6 +278,23 @@ export function deleteKeychainToken(item) {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
+/**
+ * True when the active keychain backend transparently routes reads/writes to
+ * the encrypted-file store instead of the OS credential store. This only
+ * happens on Linux under the headless / locked-collection fallback
+ * (src/lib/secrets/linux.ts); macOS and the test backend always return false.
+ *
+ * Callers that ALSO enumerate the file store directly (e.g. `listBundles`)
+ * use this to avoid double-counting: under the fallback `listKeychainItems`
+ * and the direct file enumeration return the same items.
+ */
+export function keychainUsesFileFallback() {
+    if (backend)
+        return false;
+    if (isLinux())
+        return linuxUsesFileFallback();
+    return false;
+}
 /** Enumerate keychain/keyring item names starting with the given prefix. */
 export function listKeychainItems(prefix) {
     if (backend)

package/dist/lib/secrets/linux.d.ts

@@ -18,6 +18,20 @@
  */
 import type { KeychainBackend } from './index.js';
 export { encryptForFallback, decryptForFallback, fileBackend, type EncFile, } from './filestore.js';
+/**
+ * True when secret operations currently route to the encrypted-file store
+ * instead of the Secret Service (the headless / locked-collection fallback).
+ *
+ * Runs the same `preflight()` decision every read and write uses, so it can't
+ * drift from where bytes actually land. `preflight()` throws only in the
+ * interactive / no-secret-tool / no-passphrase case — where nothing is stored
+ * — so treat that as "not on the file path".
+ *
+ * `listBundles()` needs this: under the fallback the keychain enumeration
+ * (`linuxBackend.list`) and the file enumeration read the SAME store, so
+ * without this signal every file-backed bundle would be listed twice.
+ */
+export declare function usesFileFallback(): boolean;
 /** secret-tool lookup attributes:
  *   service=agents-cli account=<user> item=<itemName> */
 export declare function hasSecretToolToken(item: string): boolean;

package/dist/lib/secrets/linux.js

@@ -86,6 +86,27 @@ function preflight() {
     }
     return 'secret-tool';
 }
+/**
+ * True when secret operations currently route to the encrypted-file store
+ * instead of the Secret Service (the headless / locked-collection fallback).
+ *
+ * Runs the same `preflight()` decision every read and write uses, so it can't
+ * drift from where bytes actually land. `preflight()` throws only in the
+ * interactive / no-secret-tool / no-passphrase case — where nothing is stored
+ * — so treat that as "not on the file path".
+ *
+ * `listBundles()` needs this: under the fallback the keychain enumeration
+ * (`linuxBackend.list`) and the file enumeration read the SAME store, so
+ * without this signal every file-backed bundle would be listed twice.
+ */
+export function usesFileFallback() {
+    try {
+        return preflight() === 'file';
+    }
+    catch {
+        return false;
+    }
+}
 // ---------- secret-tool ops with fallback ----------
 /** secret-tool lookup attributes:
  *   service=agents-cli account=<user> item=<itemName> */

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

@@ -1,4 +1,5 @@
 import { type SessionActivity, type AwaitingReason, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
+import { type SessionProvenance } from './provenance.js';
 export type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
 export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required';
 export interface ActiveSession {
@@ -30,6 +31,13 @@ export interface ActiveSession {
     status: ActiveStatus;
     /** How many live PIDs resolve to this same session (subagents/forks). 1 unless collapsed. */
     pidCount?: number;
+    /**
+     * Where the process actually lives — machine host, local vs SSH, tmux pane,
+     * and whether a rail exists to type back into it. Read from the process env
+     * (`/proc/<pid>/environ` on Linux, `ps eww` on macOS) during enrichment.
+     * Absent for cloud sessions (no local pid) and any pid whose env is unreadable.
+     */
+    provenance?: SessionProvenance;
     teamName?: string;
     agentId?: string;
     cloudProvider?: string;

package/dist/lib/session/active.js

@@ -29,6 +29,7 @@ import { latestSessionFileForCwd } from './db.js';
 import { extractSessionTopic } from './prompt.js';
 import { readSessionTail } from './tail.js';
 import { inferSessionState } from './state.js';
+import { detectProvenance } from './provenance.js';
 const execFileAsync = promisify(execFile);
 const HOME = os.homedir();
 const LIVE_TERMINALS_FILE = path.join(getTerminalsDir(), 'live-terminals.json');
@@ -536,7 +537,23 @@ export async function getActiveSessions(opts = {}) {
         if (s.pid)
             knownPids.add(s.pid);
     const unattributed = opts.skipHeadless ? [] : await listUnattributedActive(knownPids);
-    return dedupeBySession([...teams, ...terminals, ...cloud, ...unattributed]);
+    const merged = dedupeBySession([...teams, ...terminals, ...cloud, ...unattributed]);
+    await enrichProvenance(merged);
+    return merged;
+}
+/**
+ * Attach provenance (host / local-vs-SSH / tmux pane / reply rail) to every
+ * session that has a live pid. Mutates in place. Runs after dedupe so we probe
+ * each session once, not once per fork pid. Probes run in parallel — each is a
+ * single /proc read (Linux) or `ps` call (macOS); failures leave `provenance`
+ * undefined rather than blocking the listing.
+ */
+async function enrichProvenance(sessions) {
+    await Promise.all(sessions.map(async (s) => {
+        if (s.provenance || !s.pid)
+            return;
+        s.provenance = await detectProvenance(s.pid);
+    }));
 }
 /**
  * Collapse rows that resolve to the *same* session — a session with many

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

@@ -0,0 +1,56 @@
+export interface SshOrigin {
+    clientIp: string;
+    clientPort: number;
+    serverIp: string;
+    serverPort: number;
+}
+export interface MuxLocation {
+    kind: 'tmux' | 'screen';
+    /** tmux server socket path (first comma-field of $TMUX). Undefined for screen. */
+    socket?: string;
+    /** Exact pane id from $TMUX_PANE, e.g. '%3' — the send-keys target. */
+    pane?: string;
+    /** screen session name from $STY, e.g. '12345.pts-0.host'. */
+    session?: string;
+}
+/** How the feed can type back into a session, derived from rails that exist today. */
+export type ReplyRail = {
+    rail: 'tmux';
+    target: string;
+    socket?: string;
+} | null;
+export interface SessionProvenance {
+    /** Machine the process runs on — os.hostname(). Drives HOSTS grouping. */
+    host: string;
+    /** 'ssh' when SSH_CONNECTION is present in the process env, else 'local'. */
+    transport: 'local' | 'ssh';
+    /** Populated when transport === 'ssh'. */
+    ssh?: SshOrigin;
+    /** TERM_PROGRAM: 'iTerm.app', 'vscode', 'WezTerm', 'tmux', 'Apple_Terminal', … */
+    term?: string;
+    /** Multiplexer the process sits inside, from $TMUX / $STY. */
+    mux?: MuxLocation;
+    /** Whether an existing rail can type back into this session (see module doc). */
+    reply: ReplyRail;
+}
+/** Env vars that carry provenance. Kept small so the macOS `ps` scan stays cheap. */
+export declare const PROVENANCE_ENV_KEYS: readonly ["SSH_CONNECTION", "SSH_TTY", "TMUX", "TMUX_PANE", "TERM_PROGRAM", "STY"];
+/** Parse the NUL-separated body of /proc/<pid>/environ into a plain object. */
+export declare function parseProcEnviron(buf: string): Record<string, string>;
+/**
+ * Pull known env vars out of a macOS `ps eww` command+env line. For each
+ * `KEY=` match we consume the declared number of tokens (default 1), so
+ * SSH_CONNECTION's internal spaces survive while a following unknown var
+ * (e.g. `PWD=…`) is not swallowed into the previous value.
+ */
+export declare function extractKnownEnv(text: string, keys: readonly string[]): Record<string, string>;
+/** `<client_ip> <client_port> <server_ip> <server_port>` → structured origin. */
+export declare function parseSshConnection(value: string): SshOrigin | undefined;
+/** Build a SessionProvenance from a raw env map + the local hostname. Pure. */
+export declare function deriveProvenance(env: Record<string, string>, hostname: string): SessionProvenance;
+/**
+ * Resolve provenance for a live pid. Returns undefined when the process env
+ * can't be read (process gone, foreign uid, unsupported platform) — we never
+ * fabricate a 'local' answer we can't back with the env.
+ */
+export declare function detectProvenance(pid: number): Promise<SessionProvenance | undefined>;