@phnx-labs/agents-cli 1.22.71 → 1.22.73

package/dist/lib/fleet-shared-state.d.ts

@@ -2,6 +2,32 @@ import type { CachedUsageSnapshot } from './accounting/usage.js';
 export declare const FLEET_SHARED_STATE_VERSION = 1;
 export declare const FLEET_SHARED_STATE_FILE = "daemon-state.json";
 export type SharedAuthStatus = 'ready' | 'missing' | 'invalid';
+/**
+ * One session's lightweight preview/metadata, mirrored to the fleet so the
+ * interactive device renders a remote-host row's topic/preview INLINE instead of
+ * fetching the peer's digest live over SSH per row (PHNX-3792). Deliberately
+ * NOT a full transcript: only the fields a list row and a compact preview card
+ * need. `machine` is the EXECUTION host the publisher recorded (so an offloaded
+ * session's mirror row matches the same `machine:id` key the live fan-out uses,
+ * never double-counting), `firstUser` is a bounded first-user-message snippet,
+ * and `capturedAt` stamps publish time for the staleness marker.
+ */
+export interface SessionMirrorRow {
+    id: string;
+    shortId: string;
+    agent: string;
+    version?: string;
+    machine: string;
+    cwd?: string;
+    topic?: string;
+    label?: string;
+    firstUser?: string;
+    lastActivity?: string;
+    timestamp: string;
+    ticketId?: string;
+    prUrl?: string;
+    capturedAt: number;
+}
 export interface FleetSharedDeviceState {
     version: typeof FLEET_SHARED_STATE_VERSION;
     device: string;
@@ -11,10 +37,14 @@ export interface FleetSharedDeviceState {
     auth?: {
         status: SharedAuthStatus;
     };
+    sessions?: {
+        rows: SessionMirrorRow[];
+    };
 }
 export interface FleetSharedStatePatch {
     usage?: FleetSharedDeviceState['usage'];
     auth?: FleetSharedDeviceState['auth'];
+    sessions?: FleetSharedDeviceState['sessions'];
 }
 export interface FleetSharedStateReadResult {
     states: FleetSharedDeviceState[];

package/dist/lib/fleet-shared-state.js

@@ -37,6 +37,10 @@ function parseFleetSharedDeviceState(raw, owner) {
         (!isRecord(auth) || !['ready', 'missing', 'invalid'].includes(String(auth.status)))) {
         throw new Error('unrecognized auth verdict');
     }
+    const sessions = parsed.sessions;
+    if (sessions !== undefined && (!isRecord(sessions) || !Array.isArray(sessions.rows))) {
+        throw new Error('unrecognized session mirror');
+    }
     return parsed;
 }
 /**
@@ -58,6 +62,7 @@ function mergeFleetState(currentRaw, device, patch) {
         ...current,
         ...(patch.usage !== undefined ? { usage: patch.usage } : {}),
         ...(patch.auth !== undefined ? { auth: patch.auth } : {}),
+        ...(patch.sessions !== undefined ? { sessions: patch.sessions } : {}),
         version: FLEET_SHARED_STATE_VERSION,
         device,
     };

package/dist/lib/hooks/install.d.ts

@@ -384,10 +384,40 @@ export declare function listUnmanagedHooksInVersionHome(agent: AgentId, version:
  * is normalized to >= 1 (Codex: unwrap_or(600).max(1)).
  */
 export declare function computeCodexHookTrustHash(eventKeyLabel: string, command: string, timeout: number, matcher: string | undefined): string;
-export declare function registerHooksToSettings(agentId: AgentId, versionHome: string, hookManifest?: Record<string, ManifestHook>, agentsDirOverride?: string): {
+/**
+ * Options that narrow `registerHooksToSettings`'s process-global side effects.
+ *
+ * `skipGlobalShimSweep` — do NOT run {@link sweepOrphanShims}. The sweep deletes
+ * every `.sh` in the ONE process-global shim dir (`getHookShimsDir()`,
+ * `~/.agents/.cache/shims/hooks/`) whose name is absent from the manifest it is
+ * handed. That is correct for a normal install/sync (the manifest is the
+ * operator's complete hook set), but catastrophic when the materializer registers
+ * a portable PACKAGE's hooks into an isolated output home: that manifest carries
+ * only the package's hooks, so the sweep would wipe the operator's unrelated
+ * global shims. The materializer sets this so materialization stays isolated
+ * (PHNX-3838); every normal caller leaves it unset and keeps the sweep.
+ */
+export interface RegisterHooksOptions {
+    skipGlobalShimSweep?: boolean;
+}
+export declare function registerHooksToSettings(agentId: AgentId, versionHome: string, hookManifest?: Record<string, ManifestHook>, agentsDirOverride?: string, options?: RegisterHooksOptions): {
     registered: string[];
     errors: string[];
 };
+/**
+ * The concrete config file(s) `registerHooksToSettings` writes for `agentId` in
+ * `home` — the settings/registrar leaves, NOT the per-hook script copies. A
+ * caller materializing into an UNTRUSTED home (the portable-agent materializer)
+ * uses this to verify none of those leaves is a preplanted symlink before the
+ * registrar follows it and overwrites a file outside the home.
+ *
+ * This MUST mirror the `registerHooksToSettings` dispatch above — each arm's
+ * write target is reproduced here, so a new registrar branch adds its leaf here
+ * too. It intentionally returns only the primary settings/registrar file(s); the
+ * per-event/script files a registrar also writes live under the hooks dir the
+ * caller already guards. An agent with no hooks registrar returns `[]`.
+ */
+export declare function hookRegistrationTargets(agentId: AgentId, home: string): string[];
 /**
  * Prune every Claude-family (`settings.json`) hook entry whose command lives
  * under a removed version's home

package/dist/lib/hooks/install.js

@@ -1748,7 +1748,7 @@ function sweepOrphanShims(manifest) {
         catch { /* best effort */ }
     }
 }
-export function registerHooksToSettings(agentId, versionHome, hookManifest, agentsDirOverride) {
+export function registerHooksToSettings(agentId, versionHome, hookManifest, agentsDirOverride, options) {
     if (isAgentHardDeprecated(agentId)) {
         return { registered: [], errors: [] };
     }
@@ -1765,7 +1765,8 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
         }
         return { registered: [], errors: [] };
     }
-    sweepOrphanShims(manifest);
+    if (!options?.skipGlobalShimSweep)
+        sweepOrphanShims(manifest);
     const overrideRoots = agentsDirOverride ? [agentsDirOverride] : null;
     // Scripts are copied into the version home during sync — prefer that stable
     // local path so registered commands don't break when source dirs change.
@@ -1856,6 +1857,47 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     }
     return { registered: [], errors: [] };
 }
+/**
+ * The concrete config file(s) `registerHooksToSettings` writes for `agentId` in
+ * `home` — the settings/registrar leaves, NOT the per-hook script copies. A
+ * caller materializing into an UNTRUSTED home (the portable-agent materializer)
+ * uses this to verify none of those leaves is a preplanted symlink before the
+ * registrar follows it and overwrites a file outside the home.
+ *
+ * This MUST mirror the `registerHooksToSettings` dispatch above — each arm's
+ * write target is reproduced here, so a new registrar branch adds its leaf here
+ * too. It intentionally returns only the primary settings/registrar file(s); the
+ * per-event/script files a registrar also writes live under the hooks dir the
+ * caller already guards. An agent with no hooks registrar returns `[]`.
+ */
+export function hookRegistrationTargets(agentId, home) {
+    switch (agentId) {
+        case 'claude':
+        case 'droid':
+        case 'muse':
+            return [path.join(home, agentConfigDirName(agentId), 'settings.json')];
+        case 'codex':
+            return [path.join(home, '.codex', 'hooks.json'), path.join(home, '.codex', 'config.toml')];
+        case 'antigravity':
+            return [path.join(home, '.gemini', 'antigravity-cli', 'settings.json')];
+        case 'grok':
+            return [path.join(home, '.grok', 'hooks', 'hooks.json')];
+        case 'kimi':
+            return [path.join(home, '.kimi-code', 'config.toml')];
+        case 'copilot':
+            return [path.join(home, '.copilot', 'hooks', COPILOT_MANAGED_HOOKS_FILE)];
+        case 'goose':
+            return [path.join(home, '.agents', 'plugins', GOOSE_MANAGED_PLUGIN_NAME, 'hooks', 'hooks.json')];
+        case 'cursor':
+            return [path.join(home, '.cursor', 'hooks.json')];
+        case 'hermes':
+            return [path.join(home, '.hermes', 'config.yaml')];
+        case 'opencode':
+            return [path.join(home, '.config', 'opencode', 'plugins', 'agents-cli-hooks.ts')];
+        default:
+            return [];
+    }
+}
 const OPENCODE_DIRECT_EVENT_MAP = {
     PreToolUse: 'tool.execute.before',
     PostToolUse: 'tool.execute.after',

package/dist/lib/mcp.d.ts

@@ -142,8 +142,20 @@ export interface WritableMcpServer {
  * version-home configs). `mode: 'merge'` updates/adds the provided server
  * entries while preserving existing entries (used for project-level configs
  * that users may hand-edit or populate via agent CLI commands).
- */
-export declare function writeMcpConfig(agentId: AgentId, configPath: string, servers: WritableMcpServer[], mode?: 'overwrite' | 'merge'): void;
+ *
+ * An empty `servers` list is a no-op by default — most callers pass a
+ * resolved-but-possibly-empty selection and an empty one means "nothing to
+ * apply," not "clear whatever is there," so this must never wipe an existing
+ * config out from under an unrelated caller. `options.allowEmpty` is the
+ * explicit opt-in for a caller that owns the ENTIRE mcp section by
+ * construction (it always knows the complete current desired server set,
+ * including the empty set) and needs `overwrite` to actually clear it —
+ * still only the mcp section: `readExistingConfig` above preserves every
+ * other top-level key already, in both modes.
+ */
+export declare function writeMcpConfig(agentId: AgentId, configPath: string, servers: WritableMcpServer[], mode?: 'overwrite' | 'merge', options?: {
+    allowEmpty?: boolean;
+}): void;
 /**
  * Install MCP servers to an agent.
  * For Claude/Codex: uses CLI commands (claude mcp add, codex mcp add)

package/dist/lib/mcp.js

@@ -516,9 +516,19 @@ function parseJsonc(raw) {
  * version-home configs). `mode: 'merge'` updates/adds the provided server
  * entries while preserving existing entries (used for project-level configs
  * that users may hand-edit or populate via agent CLI commands).
+ *
+ * An empty `servers` list is a no-op by default — most callers pass a
+ * resolved-but-possibly-empty selection and an empty one means "nothing to
+ * apply," not "clear whatever is there," so this must never wipe an existing
+ * config out from under an unrelated caller. `options.allowEmpty` is the
+ * explicit opt-in for a caller that owns the ENTIRE mcp section by
+ * construction (it always knows the complete current desired server set,
+ * including the empty set) and needs `overwrite` to actually clear it —
+ * still only the mcp section: `readExistingConfig` above preserves every
+ * other top-level key already, in both modes.
  */
-export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite') {
-    if (servers.length === 0) {
+export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite', options = {}) {
+    if (servers.length === 0 && !options.allowEmpty) {
         return;
     }
     // Narrowed, not asserted: this is what lets the `never` guard on the default

package/dist/lib/packages/output-home.d.ts

@@ -0,0 +1,39 @@
+/** The three harness homes a portable schema-v3 package can be materialized into. */
+export declare const PORTABLE_HARNESSES: readonly ["claude", "codex", "opencode"];
+export type PortableHarness = (typeof PORTABLE_HARNESSES)[number];
+export declare function isPortableHarness(value: string): value is PortableHarness;
+/** Thrown for a bad front-door argument (harness / version / output home). Never `process.exit`. */
+export declare class MaterializeGuardError extends Error {
+    constructor(message: string);
+}
+/** Reject a harness that is not one of the three portable homes, with a message naming it. */
+export declare function assertPortableHarness(harness: string): PortableHarness;
+/** Reject a non-exact harness version (empty, malformed, or `@latest`). */
+export declare function assertExactHarnessVersion(version: string): string;
+/** True when `raw` still contains a `..` segment after splitting on both separators. */
+export declare function outputHomeHasDotDot(raw: string): boolean;
+/**
+ * Resolve `--output-home` to an absolute path, refusing a target that climbs out
+ * of cwd (relative), uses a `..` segment, IS the live home root, or targets (or
+ * sits inside) an existing live Claude/Codex/OpenCode home — after canonicalizing
+ * symlinks in the existing ancestors so a symlinked target/ancestor can't alias
+ * `$HOME`. Every rejection carries a `Path escape:` prefix so callers surface one
+ * consistent reason.
+ *
+ * If any protected home is instead a DANGLING symlink or chain, the function
+ * fails closed and refuses EVERY output home (via {@link assertNoDanglingLiveHome}),
+ * because the absent target it points at has no canonical spelling to compare a
+ * candidate against and the materializer's first `mkdir -p` would follow the link
+ * and re-create the operator's live home there (PHNX-3838). The existing-home
+ * comparison uses a byte-exact `===` / `startsWith` on two `realpath`-canonical
+ * paths, which is exact filesystem identity — no approximation of the volume's
+ * case/Unicode collation, which an independent macOS review showed cannot be
+ * reproduced in JS from the path text.
+ *
+ * This is a front-door convenience guard. The load-bearing containment invariant
+ * (that no per-resource write/delete escapes the output home — including through
+ * a symlink planted at the harness-config-dir join point, which this function
+ * cannot see because the materializer forms that child itself) is enforced in
+ * `materializeAgentPackage`, so a direct (non-CLI) caller is protected too.
+ */
+export declare function resolveOutputHome(raw: string, cwd?: string, home?: string): string;

package/dist/lib/packages/output-home.js

@@ -0,0 +1,203 @@
+/**
+ * Front-door safety guard for `agents packages materialize` (PHNX-3838).
+ *
+ * The canonical materializer ({@link materializeAgentPackage} in
+ * `agent-spec/materialize.ts`) writes into whatever `outputHome` it is handed —
+ * that is its job, and it must stay destination-agnostic so Factory / Prix Cloud
+ * can point it at any ephemeral home. Refusing a *dangerous* destination is a
+ * CLI-front-door concern, not a materializer concern, so it lives here:
+ *
+ *   - the target may not climb out of cwd (relative) or carry a `..` segment;
+ *   - if any protected live harness home (`~/.claude`, `~/.codex`, `~/.opencode`)
+ *     is a DANGLING symlink or dangling chain, EVERY output home is refused —
+ *     fail closed (see {@link assertNoDanglingLiveHome});
+ *   - the target may not be the operator's live home ROOT, nor — or sit inside —
+ *     an EXISTING live `~/.claude`, `~/.codex`, or `~/.opencode` home;
+ *   - the harness must be one of the three portable homes;
+ *   - the harness version must be an exact version, never `@latest`.
+ *
+ * The live-home ROOT refusal is load-bearing: the materializer appends the
+ * harness config dir (`.claude`/`.codex`/`.opencode`) to `outputHome`, so an
+ * `outputHome` of `$HOME` itself would land straight in the operator's live
+ * `~/.claude`. And because a symlink (`outputHome` itself, or any ancestor)
+ * pointing at `$HOME` re-opens the same hole — `path.resolve` normalizes `..`
+ * but never follows links — the check canonicalizes the existing ancestors with
+ * `realpath` before comparing.
+ *
+ * Kept beside the command (not inside it) so the live-home refusal is
+ * unit-testable without spawning the whole CLI.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { assertWithin, realpathExistingPrefix } from '../paths.js';
+import { VERSION_RE } from '../agent-spec/primitives.js';
+/** The three harness homes a portable schema-v3 package can be materialized into. */
+export const PORTABLE_HARNESSES = ['claude', 'codex', 'opencode'];
+export function isPortableHarness(value) {
+    return PORTABLE_HARNESSES.includes(value);
+}
+/** Thrown for a bad front-door argument (harness / version / output home). Never `process.exit`. */
+export class MaterializeGuardError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MaterializeGuardError';
+    }
+}
+/** Reject a harness that is not one of the three portable homes, with a message naming it. */
+export function assertPortableHarness(harness) {
+    if (!isPortableHarness(harness)) {
+        throw new MaterializeGuardError(`Unsupported capability: '${harness}' is not a portable-agent harness (${PORTABLE_HARNESSES.join(', ')}).`);
+    }
+    return harness;
+}
+/** Reject a non-exact harness version (empty, malformed, or `@latest`). */
+export function assertExactHarnessVersion(version) {
+    if (!version || version === 'latest' || !VERSION_RE.test(version)) {
+        throw new MaterializeGuardError(`Invalid harness version '${version}'. Pass an exact harness version (not @latest).`);
+    }
+    return version;
+}
+/** True when `raw` still contains a `..` segment after splitting on both separators. */
+export function outputHomeHasDotDot(raw) {
+    return raw.split(/[\\/]/).includes('..');
+}
+/**
+ * The absolute path a DANGLING symlink chain ultimately points at, or `null`
+ * when `p` is not a symlink or its chain resolves to an existing file.
+ *
+ * `realpathExistingPrefix` deliberately does NOT follow a dangling LEAF link — it
+ * resolves the link's parent and re-appends the basename — so `~/.claude` → an
+ * absent target canonicalizes to the literal `~/.claude`, and the target itself
+ * sails past every containment compare. Yet the materializer's very first act is
+ * `fs.mkdirSync(outputHome, { recursive: true })`, which FOLLOWS that link and
+ * creates the target, re-pointing the operator's live `~/.claude` at the
+ * materialized tree. So the guard treats a dangling protected home as a fail-
+ * closed condition (see {@link assertNoDanglingLiveHome}). A live symlink (its
+ * target exists) resolves cleanly through `realpathExistingPrefix`, hence the
+ * `!fs.existsSync` gate returns `null` for it. Relative links resolve against
+ * each hop's own directory; a bounded hop budget defuses a symlink cycle
+ * (returning the best-effort endpoint, which still reads as dangling → refused).
+ */
+function danglingLinkChainTarget(p) {
+    let current = path.resolve(p);
+    let followed = false;
+    for (let hops = 0; hops < 40; hops++) {
+        let dest;
+        try {
+            dest = fs.readlinkSync(current);
+        }
+        catch {
+            return followed && !fs.existsSync(current) ? current : null;
+        }
+        followed = true;
+        current = path.resolve(path.dirname(current), dest);
+    }
+    return current;
+}
+/**
+ * Fail CLOSED when any protected live harness home (`~/.claude`, `~/.codex`,
+ * `~/.opencode`) is a DANGLING symlink or dangling symlink chain — refusing
+ * EVERY output home, not merely one that aliases the dangling target.
+ *
+ * Why refuse the whole operation instead of the aliasing path alone: the
+ * materializer's first act is `fs.mkdirSync(outputHome, { recursive: true })`,
+ * which FOLLOWS the link and creates its absent target, re-pointing the
+ * operator's live `~/.<harness>` at the materialized tree. To refuse only the
+ * aliasing output home we would have to decide whether the requested path and
+ * the dangling target name the SAME file — but the target does not exist, so it
+ * cannot be `realpath`'d, and its identity then depends on the destination
+ * volume's own case/Unicode collation, which is per-volume and NOT knowable from
+ * the path text. An independent macOS review confirmed this directly: NFC +
+ * `toLowerCase` is not APFS case folding (APFS treats e.g. U+017F ſ and ASCII `s`
+ * as identical, which `toLowerCase` does not), and an OS-derived case-sensitivity
+ * flag is wrong for per-volume semantics. Rather than approximate an unknowable
+ * collation, the guard refuses outright until the operator repairs the dangling
+ * home. A dangling protected home is an abnormal state, so this over-rejects
+ * nothing a healthy environment relies on; the EXISTING-home comparison stays
+ * exact because `realpath` gives it a trustworthy canonical spelling.
+ */
+function assertNoDanglingLiveHome(realHome) {
+    for (const name of PORTABLE_HARNESSES) {
+        if (danglingLinkChainTarget(path.join(realHome, `.${name}`)) !== null) {
+            throw new MaterializeGuardError(`Path escape: the live .${name} home is a dangling symlink; refusing every output home until it is repaired ` +
+                `(the materializer's mkdir -p would follow the link and re-create your live .${name} at its absent target)`);
+        }
+    }
+}
+/**
+ * The canonical EXISTING live harness home to forbid, per harness: the
+ * `realpathExistingPrefix` of each `~/.<harness>`. For a live symlink this is the
+ * real on-disk target (so `--output-home ~/.claude` and its resolved dir both
+ * match); for a plain dir, or a home that does not exist at all, it is the
+ * literal `~/.<harness>` path. Because both this and the candidate output home
+ * are canonicalized with `realpath`, a byte-exact compare is exact filesystem
+ * identity — `realpath` returns the volume's own on-disk spelling, so two paths
+ * naming the same file collapse to the same string with no need to approximate
+ * the volume's case/Unicode collation. A DANGLING `~/.<harness>` never reaches
+ * here: {@link assertNoDanglingLiveHome} fails closed first, precisely because
+ * its absent target has no realpath-canonical spelling to compare against.
+ */
+function liveHarnessHomes(realHome) {
+    return PORTABLE_HARNESSES.map((name) => ({
+        harness: name,
+        live: realpathExistingPrefix(path.join(realHome, `.${name}`)),
+    }));
+}
+/**
+ * Resolve `--output-home` to an absolute path, refusing a target that climbs out
+ * of cwd (relative), uses a `..` segment, IS the live home root, or targets (or
+ * sits inside) an existing live Claude/Codex/OpenCode home — after canonicalizing
+ * symlinks in the existing ancestors so a symlinked target/ancestor can't alias
+ * `$HOME`. Every rejection carries a `Path escape:` prefix so callers surface one
+ * consistent reason.
+ *
+ * If any protected home is instead a DANGLING symlink or chain, the function
+ * fails closed and refuses EVERY output home (via {@link assertNoDanglingLiveHome}),
+ * because the absent target it points at has no canonical spelling to compare a
+ * candidate against and the materializer's first `mkdir -p` would follow the link
+ * and re-create the operator's live home there (PHNX-3838). The existing-home
+ * comparison uses a byte-exact `===` / `startsWith` on two `realpath`-canonical
+ * paths, which is exact filesystem identity — no approximation of the volume's
+ * case/Unicode collation, which an independent macOS review showed cannot be
+ * reproduced in JS from the path text.
+ *
+ * This is a front-door convenience guard. The load-bearing containment invariant
+ * (that no per-resource write/delete escapes the output home — including through
+ * a symlink planted at the harness-config-dir join point, which this function
+ * cannot see because the materializer forms that child itself) is enforced in
+ * `materializeAgentPackage`, so a direct (non-CLI) caller is protected too.
+ */
+export function resolveOutputHome(raw, cwd = process.cwd(), home = os.homedir()) {
+    if (!raw || raw.includes('\0')) {
+        throw new MaterializeGuardError('Path escape: output home is empty or contains a null byte');
+    }
+    if (outputHomeHasDotDot(raw)) {
+        throw new MaterializeGuardError(`Path escape: ${raw}`);
+    }
+    const resolved = path.resolve(cwd, raw);
+    if (!path.isAbsolute(raw)) {
+        try {
+            assertWithin(cwd, resolved);
+        }
+        catch {
+            throw new MaterializeGuardError(`Path escape: ${raw}`);
+        }
+    }
+    const canonical = realpathExistingPrefix(resolved);
+    const realHome = realpathExistingPrefix(home);
+    // Fail closed first: a dangling protected home makes EVERY output home unsafe,
+    // and its absent target has no realpath-canonical spelling to compare against.
+    assertNoDanglingLiveHome(realHome);
+    // The materializer appends the harness config dir to outputHome, so the live
+    // home ROOT would write straight into ~/.claude etc.
+    if (canonical === realHome) {
+        throw new MaterializeGuardError('Path escape: output home must not be the live home directory');
+    }
+    for (const { harness, live } of liveHarnessHomes(realHome)) {
+        if (canonical === live || canonical.startsWith(live + path.sep)) {
+            throw new MaterializeGuardError(`Path escape: output home must not target the live .${harness} directory`);
+        }
+    }
+    return resolved;
+}

package/dist/lib/paths.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Canonicalize `target` by `realpath`-resolving its longest EXISTING ancestor and
+ * re-appending the not-yet-created tail. A plain `realpathSync(target)` throws when
+ * `target` (a fresh output dir, a not-yet-written file) does not exist — but any
+ * symlink in the part that DOES exist (the target itself, or an ancestor) is
+ * exactly the escape hatch a containment check must resolve before comparing.
+ * Unlike `path.resolve` (which only normalizes `..`), this follows links.
+ */
+export declare function realpathExistingPrefix(target: string): string;
 /**
  * True when `name` is a safe single path segment: non-empty, not '.'/'..',
  * free of path separators and null bytes, and within the filename length limit.

package/dist/lib/paths.js

@@ -1,4 +1,30 @@
+import * as fs from 'fs';
 import * as path from 'path';
+/**
+ * Canonicalize `target` by `realpath`-resolving its longest EXISTING ancestor and
+ * re-appending the not-yet-created tail. A plain `realpathSync(target)` throws when
+ * `target` (a fresh output dir, a not-yet-written file) does not exist — but any
+ * symlink in the part that DOES exist (the target itself, or an ancestor) is
+ * exactly the escape hatch a containment check must resolve before comparing.
+ * Unlike `path.resolve` (which only normalizes `..`), this follows links.
+ */
+export function realpathExistingPrefix(target) {
+    let current = path.resolve(target);
+    const tail = [];
+    for (;;) {
+        try {
+            const real = fs.realpathSync(current);
+            return tail.length ? path.join(real, ...tail.reverse()) : real;
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return path.resolve(target); // nothing on this path exists
+            tail.push(path.basename(current));
+            current = parent;
+        }
+    }
+}
 /**
  * True when `name` is a safe single path segment: non-empty, not '.'/'..',
  * free of path separators and null bytes, and within the filename length limit.

package/dist/lib/project-resources.js

@@ -141,7 +141,9 @@ function applyManagedBlock(content, begin, end, entries) {
         if (entries.length > 0) {
             return [...lines.slice(0, bi), begin, ...entries, end, ...lines.slice(ei + 1)].join('\n');
         }
-        // Prune the block, tidying the blank lines that hugged it.
+        // Prune the block, tidying the blank lines that hugged it. Vestigial on the
+        // reconcileProjectGitignore path (its entries always include the manifest,
+        // so entries.length is never 0 there) — kept for a direct caller/unit test.
         const before = lines.slice(0, bi);
         const after = lines.slice(ei + 1);
         while (before.length && before[before.length - 1].trim() === '')
@@ -162,16 +164,23 @@ function applyManagedBlock(content, begin, end, entries) {
  * generated per-harness resource dir never shows as untracked dirt. Idempotent
  * and convergent: replaces the block in place and writes only when the content
  * actually changes, so the launch hot path does not churn the file (or its
- * watchers) every run — even in a project synced by several harnesses. Called
- * with an empty `managed` set when a sync clears a harness, which prunes the
- * block. Never creates a `.gitignore` outside a git working tree.
+ * watchers) every run — even in a project synced by several harnesses. When a
+ * sync clears a harness's resources the block does not vanish: it shrinks to the
+ * lone `.agents-managed.json` entry (that file still sits in the harness dir and
+ * must stay ignored), so the block is only ever fully pruned by hand, never via
+ * this call path. Never creates a `.gitignore` outside a git working tree.
  */
 function reconcileProjectGitignore(projectRoot, agent, agentRoot, managed) {
     const gitignorePath = path.join(projectRoot, '.gitignore');
     if (!isInsideGitRepo(projectRoot) && !pathExists(gitignorePath))
         return;
     const { begin, end } = gitignoreMarkers(agent);
-    const entries = managedGitignoreEntries(agentRoot, projectRoot, managed);
+    // Ignore the manifest marker file too, not just the synced resources: the
+    // sync always writes `<agentRoot>/.agents-managed.json`, so without this the
+    // harness dir still shows as untracked in `git status` on the strength of that
+    // one file (defeating the whole point). It lives at agentRoot, so it resolves
+    // through the same anchoring + escape guard as any managed path.
+    const entries = managedGitignoreEntries(agentRoot, projectRoot, [MANIFEST_FILE, ...managed]);
     let original = '';
     try {
         original = fs.readFileSync(gitignorePath, 'utf-8');

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

@@ -402,6 +402,18 @@ export interface ActiveSession {
      * did not inherit a terminal id.
      */
     terminalId?: string;
+    /**
+     * The launch id (`AGENT_LAUNCH_ID`) the CLI stamps on every agent at spawn — a
+     * stable UUID that is identical locally and across an SSH hop and survives a
+     * session-id rotation (`/clear`, exit-and-rerun). Unlike `sessionId` (which the
+     * non-Claude harnesses only mint after boot) it exists from the first tick, so
+     * it is the join key a client uses to re-identify a session on the watch stream.
+     * Populated wherever the by-pid launch registry resolves — reliably for
+     * `agents run`-launched processes; still absent for editor-launched terminals
+     * whose shell pid does not line up with the agent-pid registry today (the same
+     * limitation the `readPidSessionEntry` call in `listTerminalsActive` documents).
+     */
+    launchId?: string;
     /**
      * tmux pane id (`%N`) when this row was discovered via the tmux source AND its
      * session id could not be resolved (a born-unidentifiable non-Claude pane). It

package/dist/lib/session/active.js

@@ -1059,6 +1059,8 @@ export async function listTerminalsActive() {
             tty: procByPid.get(t.pid)?.tty,
             pid: t.pid,
             sessionId: t.sessionId ?? sessionIdFromFile(sessionFile),
+            launchId: pidEntry?.launchId,
+            terminalId: pidEntry?.terminalId,
             cwd: t.cwd ?? undefined,
             label,
             name,
@@ -1558,7 +1560,8 @@ async function listUnattributedActiveLive(attributed) {
             lastActivityMs: mtimeMs,
             pidCount: 1 + (foldedByRoot.get(pid) ?? 0),
             owner: resolveOwner(entry?.actor, resolvedId),
-            terminalId: entry?.terminalId,
+            launchId: entry?.launchId ?? hookRec?.launch_id,
+            terminalId: entry?.terminalId ?? hookRec?.terminal_id,
         }, state, sessionFile, true));
     }
     // Housekeeping: drop registry files for pids that have since died.
@@ -1773,6 +1776,7 @@ export async function listTmuxAgentSessions() {
             // Factory / --active join key: AGENT_TERMINAL_ID stamped on the launch
             // registry and preserved by SessionStart. Without this, Grok/Codex tmux
             // panes never surface terminalId even when by-pid has it (RUSH-2192).
+            launchId: liveEntry?.launchId,
             terminalId: liveEntry?.terminalId,
             // An id-less pane keys its dedupe on the unique pane, so two anonymous
             // co-located panes stay two rows instead of folding into one.

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

@@ -5,6 +5,13 @@ export interface SessionActorRecord {
     actor?: string;
     /** Actor kind (`resolveActor().kind`). */
     initiatedBy?: 'human' | 'agent';
+    /**
+     * Phoenix id of the responsible actor (`resolveActor().phoenixId`) — the
+     * tailnet human's stable Phoenix identity, resolved from the `actors:` map at
+     * spawn (PHNX-3798). Pairs with {@link actor}: joined onto the session index at
+     * scan time so a durable listing can surface the Phoenix id, not just the email.
+     */
+    phoenixId?: string;
     /** Effective permissions mode used by the launcher. */
     mode?: SessionRunMode;
     /**

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

@@ -39,6 +39,7 @@ function isSafeAlias(alias) {
 }
 function hasRecordData(record) {
     return typeof record.actor === 'string'
+        || typeof record.phoenixId === 'string'
         || typeof record.mode === 'string'
         || typeof record.version === 'string'
         || typeof record.harness === 'string'
@@ -84,6 +85,7 @@ export function writeSessionAliasRecord(sessionId, alias) {
             sessionId,
             actor: previous?.actor,
             initiatedBy: previous?.initiatedBy,
+            phoenixId: previous?.phoenixId,
             mode: previous?.mode,
             version: previous?.version,
             harness: previous?.harness,