@phnx-labs/agents-cli 1.22.72 → 1.22.74

package/dist/lib/daemon/usage-sync-service.js

@@ -1,10 +1,17 @@
 /**
- * Fleet usage-snapshot sync as a `PeriodicService` (PHNX-3392 usage-sync).
+ * Fleet shared-state sync as a `PeriodicService` (PHNX-3392 usage-sync,
+ * PHNX-3792 session mirror).
  *
- * A headed box publishes its local identity-keyed Claude usage rows into its
- * owned file in the fleet-synced user repo. The tick then runs one serialized,
- * timeout-bounded git exchange; a worker reads the delivered peer snapshots
- * and merges newest-wins. No tick opens a device-to-device SSH mesh.
+ * This is the one tick that owns the bounded Git exchange over the fleet-synced
+ * user repo, so every non-secret daemon-state field rides it rather than opening
+ * a second committer. Each tick: (1) publishes this box's own fields into its
+ * conflict-free `devices/<device>/daemon-state.json` — a headed box's Claude
+ * usage snapshot, and EVERY box's lightweight session digests (PHNX-3792);
+ * (2) runs one serialized, timeout-bounded commit/rebase/push; (3) consumes the
+ * peer fields the exchange delivered — a worker merges usage newest-wins, and
+ * every non-worker box folds peers' session digests into its local index so the
+ * picker renders remote-host previews inline. No tick opens a device-to-device
+ * SSH mesh.
  */
 import { BasePeriodicService } from './service.js';
 const USAGE_SYNC_TICK_MS = 15 * 60_000;
@@ -23,11 +30,18 @@ export class UsageSyncService extends BasePeriodicService {
     }
     async onTick(ctx) {
         const { consumeUsageSnapshotsFromSharedStore, publishUsageSnapshotToSharedStore } = await import('../accounting/usage-sync.js');
+        const { consumeSessionMirrorFromSharedStore, publishSessionMirrorToSharedStore } = await import('../session/mirror.js');
+        // Publish every owned field BEFORE the single git exchange so they ride one commit.
         const published = await publishUsageSnapshotToSharedStore();
         if (published.changed)
             ctx.log('INFO', `usage-sync: published usage snapshot to ${published.path}`);
         if (published.error)
             ctx.log('WARN', `usage-sync: publish: ${published.error}`);
+        const mirrored = await publishSessionMirrorToSharedStore();
+        if (mirrored.changed)
+            ctx.log('INFO', `session-mirror: published ${mirrored.count} session digest(s)`);
+        if (mirrored.error)
+            ctx.log('WARN', `session-mirror: publish: ${mirrored.error}`);
         const { syncFleetSharedStateRepo } = await import('../fleet-shared-repo-sync.js');
         const transport = await syncFleetSharedStateRepo();
         if (transport.skipped)
@@ -42,5 +56,13 @@ export class UsageSyncService extends BasePeriodicService {
         }
         for (const err of consumed.errors)
             ctx.log('WARN', `usage-sync: ${err.device}: ${err.message}`);
+        const foldedIn = consumeSessionMirrorFromSharedStore();
+        if (foldedIn.merged > 0) {
+            ctx.log('INFO', `session-mirror: folded ${foldedIn.merged} session(s) from ${foldedIn.sources.join(', ')}`);
+        }
+        if (foldedIn.pruned > 0)
+            ctx.log('INFO', `session-mirror: pruned ${foldedIn.pruned} stale mirror row(s)`);
+        for (const err of foldedIn.errors)
+            ctx.log('WARN', `session-mirror: ${err.device}: ${err.message}`);
     }
 }

package/dist/lib/exec.js

@@ -1166,6 +1166,7 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
                     sessionId: passthroughSessionId,
                     actor: resolveActor().id,
                     initiatedBy: resolveActor().kind,
+                    phoenixId: resolveActor().phoenixId,
                     startedAtMs: Date.now(),
                 });
             }
@@ -1564,6 +1565,7 @@ async function runInTmux(options, executable, args) {
                 sessionId: options.sessionId,
                 actor: resolveActor().id,
                 initiatedBy: resolveActor().kind,
+                phoenixId: resolveActor().phoenixId,
                 harness: customHarnessName(options),
                 startedAtMs: Date.now(),
             });
@@ -1899,6 +1901,7 @@ async function spawnAgent(options) {
                 sessionId: options.sessionId,
                 actor: resolveActor().id,
                 initiatedBy: resolveActor().kind,
+                phoenixId: resolveActor().phoenixId,
                 harness: customHarnessName(options),
                 startedAtMs: Date.now(),
             });

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

@@ -7,7 +7,11 @@ export declare function projectAgentRoot(projectRoot: string, agent: AgentId): s
 export declare function syncProjectResourcesToAgent(agent: AgentId, version: string, projectAgentsDir: string): ProjectResourceSyncResult;
 /**
  * Turn the manifest's managed paths (relative to agentRoot) into anchored,
- * POSIX, projectRoot-relative `.gitignore` entries. Two guards keep it honest:
+ * POSIX, `referenceRoot`-relative ignore entries. `referenceRoot` is the
+ * directory the anchored `/…` patterns resolve against — the git worktree root
+ * for a `.git/info/exclude` block, since git anchors info/exclude patterns at
+ * the top of the working tree (not at the harness dir). Two guards keep it
+ * honest:
  *   - drop any path that escapes the harness config dir (e.g. grok writes
  *     commands back into the tracked `.agents/` tree via a `../` subdir —
  *     ignoring that would hide tracked source; separate bug, PHNX-3718);
@@ -16,7 +20,7 @@ export declare function syncProjectResourcesToAgent(agent: AgentId, version: str
  *     these never masks a hand-authored or committed file (e.g. a repo that
  *     commits its own `.claude/CLAUDE.md` keeps it — it is not in the manifest).
  */
-export declare function managedGitignoreEntries(agentRoot: string, projectRoot: string, managed: string[]): string[];
+export declare function managedGitignoreEntries(agentRoot: string, referenceRoot: string, managed: string[]): string[];
 /**
  * One human line for the files a project sync left alone because you already
  * wrote them. This is the normal steady state — every sync of a project whose