@phnx-labs/agents-cli 1.22.52 → 1.22.54

package/dist/lib/help.js

@@ -7,6 +7,27 @@ const commandGroupRegistry = new WeakMap();
 export function registerCommandGroups(parent, groups) {
     commandGroupRegistry.set(parent, groups);
 }
+/**
+ * Front-door command groups shown on `agents --help`. Derived from measured
+ * reach: tier 1 = setup/run/sessions/view, tier 2 = teams/browser/secrets/
+ * devices/accounts/add. The remaining groups stay discoverable through the
+ * pointer rendered below these groups.
+ */
+export const FRONT_DOOR_COMMAND_GROUPS = [
+    {
+        title: 'Quick start',
+        names: ['setup', 'view', 'run', 'sessions'],
+    },
+    {
+        title: 'Most-used',
+        names: ['teams', 'browser', 'secrets', 'devices', 'accounts', 'add'],
+    },
+];
+const compactRootHelp = new WeakMap();
+/** Mark the root program so its help only renders front-door groups + a pointer. */
+export function setCompactRootHelp(program) {
+    compactRootHelp.set(program, true);
+}
 const helpSectionRegistry = new WeakMap();
 /**
  * Attach an Examples block (rendered between the description and Arguments)
@@ -136,7 +157,14 @@ function formatHelpCommandsFirst(cmd, helper) {
             output = output.concat([`${title}:`, formatList(subs.map(renderCommand)), '']);
         }
         const remaining = visibleCommands.filter((s) => !placed.has(s.name()));
-        if (remaining.length > 0) {
+        if (compactRootHelp.get(cmd)) {
+            output = output.concat([
+                'Commands:',
+                `  See "${cmd.name()} --help-all" for every command.`,
+                '',
+            ]);
+        }
+        else if (remaining.length > 0) {
             output = output.concat(['Commands:', formatList(remaining.map(renderCommand)), '']);
         }
     }

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

@@ -40,9 +40,10 @@ export declare function withActorEnv(env?: Record<string, string>): Record<strin
  *
  * `extra` carries the markers that are true of ONE path rather than both — the
  * interactive dispatch adds REMOTE_INTERACTIVE_ENV, which the remote CLI reads
- * to decide it must detach. It goes through this builder rather than being
- * concatenated on at the call site so every remote env marker is exported the
- * same way, in one place.
+ * to know its stdio is an ssh link (reconnect target, `--no-follow` pane
+ * requirement). It goes through this builder rather than being concatenated on
+ * at the call site so every remote env marker is exported the same way, in one
+ * place.
  */
 export declare function remoteRunShellPrelude(agent: string, extra?: Record<string, string>): string;
 /**

package/dist/lib/hosts/dispatch.js

@@ -78,9 +78,10 @@ export function withActorEnv(env) {
  *
  * `extra` carries the markers that are true of ONE path rather than both — the
  * interactive dispatch adds REMOTE_INTERACTIVE_ENV, which the remote CLI reads
- * to decide it must detach. It goes through this builder rather than being
- * concatenated on at the call site so every remote env marker is exported the
- * same way, in one place.
+ * to know its stdio is an ssh link (reconnect target, `--no-follow` pane
+ * requirement). It goes through this builder rather than being concatenated on
+ * at the call site so every remote env marker is exported the same way, in one
+ * place.
  */
 export function remoteRunShellPrelude(agent, extra = {}) {
     const guard = agent === RUN_AUTO_KEYWORD ? { [RUN_AUTO_HOST_RESOLVED_ENV]: '1' } : {};
@@ -497,11 +498,14 @@ export async function runInteractiveOnHost(host, opts) {
     // than re-resolving from this box's SSH_CONNECTION (RUSH-2028); a `run auto`
     // dispatch also gets the chain-hop guard (remoteRunShellPrelude).
     //
-    // REMOTE_INTERACTIVE_ENV rides the same prelude and is what makes the remote
-    // agent DETACHED: its stdio is this ssh link, so without the tmux wrap a
-    // blink SIGHUPs it and the in-flight turn is gone — while reconnect.ts is
-    // built to re-attach a pane it assumes survived (RUSH-3125). Set here, on the
-    // interactive path only: `launchDetached` already setsids the headless one.
+    // REMOTE_INTERACTIVE_ENV rides the same prelude and tells the remote CLI its
+    // stdio is this ssh link: it marks the run as reconnect-managed (a drop is
+    // answered by reconnect.ts, which rejoins the live pane or resumes the
+    // session in place) and, when the launcher has no TTY (CI, scripts), requires
+    // the detached pane that is the run's only interface. Since PHNX-3316 it no
+    // longer forces the tmux wrap on a TTY-followed run — the peer's
+    // tmux.enabled decides that. Set here, on the interactive path only:
+    // `launchDetached` already setsids the headless one.
     const prelude = remoteRunShellPrelude(opts.agent, { [REMOTE_INTERACTIVE_ENV]: '1' });
     let remoteCmd = `${prelude}${cwd}${invocation}`;
     if (opts.copyCreds) {

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

@@ -17,7 +17,7 @@
  * "not supported" message — never commander's raw `unknown option`.
  */
 import { type Host } from './types.js';
-import { type DeviceProfile, type DeviceRegistry } from '../devices/registry.js';
+import { type DeviceRegistry } from '../devices/registry.js';
 import { runLocalCommand, runOnDevice } from '../devices/fleet.js';
 /** Re-export for callers that historically imported flagValue from this module. */
 export { flagValue, hasHostRoutingFlag } from './routing-flag.js';
@@ -69,15 +69,6 @@ export interface FleetPassthroughOptions {
     /** Override this machine's id (tests). Defaults to `machineId()`. */
     self?: string;
 }
-/**
- * Prefix a fan-out remote command so the far side sees AGENTS_FLEET_REMOTE=1 —
- * the same marker the single-target dispatch sets via env. `wrapRemoteCommand`
- * joins the argv with spaces (POSIX) or base64-encodes it for PowerShell, so a
- * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
- * `$env:VAR='1'; …` on PowerShell. Only remote (non-self) targets get it; the
- * self target runs locally and must stay ungated.
- */
-export declare function markFleetRemote(cmd: string[], device: DeviceProfile): string[];
 /** Run `agents <command> …` across every registered device and render the roster. */
 export declare function runFleetPassthrough(command: string, allArgs: string[], spec: RemoteSpec, opts?: FleetPassthroughOptions): Promise<boolean>;
 /**

package/dist/lib/hosts/passthrough.js

@@ -32,6 +32,7 @@ import { isDeviceInteractive, resolveInteractiveDevice, interactiveUnsetError, }
 import { flagValue, hasHostRoutingFlag } from './routing-flag.js';
 import { loadDevices } from '../devices/registry.js';
 import { isSelfHost } from '../devices/self-host.js';
+import { markFleetRemote } from '../devices/connect.js';
 import { fanOutDevices, planFleetTargets, runLocalCommand, runOnDevice, } from '../devices/fleet.js';
 import { platformGroupLabel } from '../devices/health-report.js';
 import { isKnownTopLevelCommand } from '../startup/command-registry.js';
@@ -368,19 +369,6 @@ function renderFleetRoster(command, forwarded, results, self) {
         console.log(chalk.gray(summaryParts.join(' · ')));
     }
 }
-/**
- * Prefix a fan-out remote command so the far side sees AGENTS_FLEET_REMOTE=1 —
- * the same marker the single-target dispatch sets via env. `wrapRemoteCommand`
- * joins the argv with spaces (POSIX) or base64-encodes it for PowerShell, so a
- * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
- * `$env:VAR='1'; …` on PowerShell. Only remote (non-self) targets get it; the
- * self target runs locally and must stay ungated.
- */
-export function markFleetRemote(cmd, device) {
-    return device.shell === 'powershell'
-        ? [`$env:AGENTS_FLEET_REMOTE='1';`, ...cmd]
-        : ['env', 'AGENTS_FLEET_REMOTE=1', ...cmd];
-}
 /** Run `agents <command> …` across every registered device and render the roster. */
 export async function runFleetPassthrough(command, allArgs, spec, opts = {}) {
     const self = opts.self ?? machineId();

package/dist/lib/hosts/providers/local.d.ts

@@ -2,9 +2,15 @@
  * Local host provider: the v1 directory.
  *
  * `list()` is the union of ssh-config `Host` stanzas (read-only, connection
- * details owned by ssh) and inline entries the user registered in agents.yaml.
- * The `Meta.hosts` overlay (caps/os, keyed by name) is merged onto both. We
- * never copy or rewrite ssh config.
+ * details owned by ssh) and inline entries the user registered. The host
+ * overlay (caps/os, keyed by name) is merged onto both. We never copy or
+ * rewrite ssh config.
+ *
+ * PHNX-3315: registrations are DEVICE-SCOPED — each box writes only its own
+ * `hosts:` block in `devices/<machine>/agents.yaml` (via `Meta.deviceHosts`),
+ * so N boxes no longer rewrite one shared `hosts:` map (the pull conflict).
+ * Reads are the cross-box UNION of every device doc, plus any lingering central
+ * legacy entries drained by the migration.
  */
 import type { Host, HostProvider, HostProviderCapabilities } from '../types.js';
 export declare class LocalHostProvider implements HostProvider {

package/dist/lib/hosts/providers/local.js

@@ -2,14 +2,28 @@
  * Local host provider: the v1 directory.
  *
  * `list()` is the union of ssh-config `Host` stanzas (read-only, connection
- * details owned by ssh) and inline entries the user registered in agents.yaml.
- * The `Meta.hosts` overlay (caps/os, keyed by name) is merged onto both. We
- * never copy or rewrite ssh config.
+ * details owned by ssh) and inline entries the user registered. The host
+ * overlay (caps/os, keyed by name) is merged onto both. We never copy or
+ * rewrite ssh config.
+ *
+ * PHNX-3315: registrations are DEVICE-SCOPED — each box writes only its own
+ * `hosts:` block in `devices/<machine>/agents.yaml` (via `Meta.deviceHosts`),
+ * so N boxes no longer rewrite one shared `hosts:` map (the pull conflict).
+ * Reads are the cross-box UNION of every device doc, plus any lingering central
+ * legacy entries drained by the migration.
  */
 import { readMeta, updateMeta } from '../../state.js';
+import { unionDeviceHosts } from '../../devices/device-docs.js';
 import { listSshConfigHosts, isSshConfigHost } from '../ssh-config.js';
+/** The EFFECTIVE host overlay: the cross-box union of every device doc's
+ * `hosts:` block, with any lingering central-legacy `hosts:` entries as a base
+ * (a device doc wins on a name collision). Newest `addedAt` wins across boxes. */
 function entries() {
-    return readMeta().hosts ?? {};
+    return { ...readMeta().hosts, ...unionDeviceHosts() };
+}
+/** THIS box's OWN host registrations (the writable slice in the device doc). */
+function ownEntries(meta = readMeta()) {
+    return meta.deviceHosts ?? {};
 }
 function toHost(name, entry, enrolled) {
     return {
@@ -63,19 +77,16 @@ export class LocalHostProvider {
             ...(spec.caps && spec.caps.length ? { caps: spec.caps } : {}),
             addedAt: spec.addedAt ?? new Date().toISOString(),
         };
-        updateMeta((meta) => ({ ...meta, hosts: { ...(meta.hosts ?? {}), [spec.name]: entry } }));
+        // Device-scoped: land in THIS box's device doc, never the shared central map.
+        updateMeta((meta) => ({ ...meta, deviceHosts: { ...ownEntries(meta), [spec.name]: entry } }));
         return toHost(spec.name, entry, true);
     }
     async remove(name) {
+        // A box only owns the registrations in its own device doc; drop from there.
         updateMeta((meta) => {
-            const hosts = { ...(meta.hosts ?? {}) };
+            const hosts = { ...ownEntries(meta) };
             delete hosts[name];
-            // Drop the key entirely when empty so we don't leave `hosts: {}` behind.
-            if (Object.keys(hosts).length === 0) {
-                const { hosts: _omit, ...rest } = meta;
-                return rest;
-            }
-            return { ...meta, hosts };
+            return { ...meta, deviceHosts: hosts };
         });
     }
 }

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

@@ -211,10 +211,13 @@ export declare function startConnectionTarget(opts: {
 /**
  * Decide what happens after an interactive `--device` stream returns.
  *
- * Auto-reconnect only when the link dropped (255) AND the run is tmux-hosted
- * (`willReconnect`). `--raw` is not wrapped, so it never reconnects — but it
- * still prints the session id: the user is at a shell, and EXEC-55 does not
- * exempt raw (RUSH-3227). Bundling the notice behind `!isRaw` was the miss.
+ * Auto-reconnect fires whenever the link dropped (255) and the run did not opt
+ * out with `--raw` (`willReconnect`) — wrap or no wrap. A wrapped run's pane
+ * survived, so the reattach rejoins it; a bare run's agent died with the link,
+ * so the same verb resumes the session in place from disk (PHNX-3316). `--raw`
+ * never reconnects — but it still prints the session id: the user is at a
+ * shell, and EXEC-55 does not exempt raw (RUSH-3227). Bundling the notice
+ * behind `!isRaw` was the miss.
  */
 export declare function afterInteractiveRemoteExit(opts: {
     target?: ReconnectTarget;

package/dist/lib/hosts/reconnect.js

@@ -2,34 +2,35 @@
  * Auto-reconnect for an interactive `agents run --device` session whose
  * SSH link dropped.
  *
- * A remote interactive agent runs in a DETACHED tmux session on the peer (see
- * lib/exec.ts `runInTmux`), so a network blink kills only the local ssh client —
- * the agent keeps running.
- *
- * **That premise is a guarantee, not a hope, only since RUSH-3125.** It used to
- * rest on the peer's `tmux.enabled`, an ergonomics preference that defaults OFF
- * — so on a default box the agent was a child of the sshd session, a blink
- * SIGHUPed it, and this file reconnected to a corpse while telling the user it
- * was "still running there." The interactive dispatch now exports
- * REMOTE_INTERACTIVE_ENV and exec.ts `resolveTmuxWrap` wraps on it regardless of
- * that toggle, so what is written below actually holds. Anything that would let
- * a remote interactive run reach the peer unwrapped breaks this whole file.
+ * What the reconnect lands on depends on the peer's `tmux.enabled`
+ * (PHNX-3316). With the wrap opted in, the agent runs in a DETACHED tmux
+ * session on the peer (see lib/exec.ts `runInTmux`), so a network blink kills
+ * only the local ssh client and the reattach below rejoins the live pane.
+ * With the wrap off — the fleet default — the remote agent is a child of the
+ * sshd session and a blink SIGHUPs it: the in-flight turn is lost, and the
+ * reattach RESUMES the harness session from disk instead. Both outcomes go
+ * through the same verb below; what changed in PHNX-3316 is that "resumed"
+ * is once again an honest, expected result rather than a corpse this file
+ * pretended was alive (the pre-RUSH-3125 bug), and RUSH-3125's forced wrap —
+ * which made the pane a guarantee by overriding the operator's tmux.enabled —
+ * is gone with it.
  *
  * `sshStream` reports that drop as exit code 255 (ssh's
  * own connection-layer failure; see ssh-exec.ts). Without this, exec.ts would
  * `process.exit(255)` and the user would have to notice, find the session id, and
- * `agents sessions focus` by hand. Instead we re-attach the live remote pane over
- * SSH automatically, with bounded backoff, until the user detaches cleanly (the
- * remote returns 0), the agent exits (the tmux session is gone; a non-255 code),
- * or the user interrupts the wait with Ctrl-C ({@link waitOrInterrupt} → 130).
+ * `agents sessions focus` by hand. Instead we re-attach over SSH automatically,
+ * with bounded backoff, until the user detaches cleanly (the remote returns 0),
+ * the agent exits (a non-255 code), or the user interrupts the wait with
+ * Ctrl-C ({@link waitOrInterrupt} → 130).
  *
  * The re-attach reuses the peer's OWN recovery verb — `agents sessions focus <id>
  * --local` — which JOINS the live local tmux pane there (a second client, no fork)
- * when it still exists, and RESUMES the session in place when the pane is already
- * gone. Dropping `--attach-only` is deliberate: a reattach that lands after the
- * remote pane died must not dead-end at a bare shell (the RUSH-2085 bug), it must
- * fall through to resume so the user is put back into the agent. There is one
- * re-attach implementation (the peer's focus) to keep in sync.
+ * when it exists, and RESUMES the session in place when there is no pane — which
+ * is every drop on a default (wrap-off) box. Dropping `--attach-only` is
+ * deliberate: a reattach that finds no pane must not dead-end at a bare shell
+ * (the RUSH-2085 bug), it must fall through to resume so the user is put back
+ * into the agent. There is one re-attach implementation (the peer's focus) to
+ * keep in sync.
  *
  * **What it takes to refill the budget: reached the host AND held the pane.** ssh
  * returns 255 for BOTH "couldn't connect at all" and "connected, then the link
@@ -314,10 +315,13 @@ export function startConnectionTarget(opts) {
 /**
  * Decide what happens after an interactive `--device` stream returns.
  *
- * Auto-reconnect only when the link dropped (255) AND the run is tmux-hosted
- * (`willReconnect`). `--raw` is not wrapped, so it never reconnects — but it
- * still prints the session id: the user is at a shell, and EXEC-55 does not
- * exempt raw (RUSH-3227). Bundling the notice behind `!isRaw` was the miss.
+ * Auto-reconnect fires whenever the link dropped (255) and the run did not opt
+ * out with `--raw` (`willReconnect`) — wrap or no wrap. A wrapped run's pane
+ * survived, so the reattach rejoins it; a bare run's agent died with the link,
+ * so the same verb resumes the session in place from disk (PHNX-3316). `--raw`
+ * never reconnects — but it still prints the session id: the user is at a
+ * shell, and EXEC-55 does not exempt raw (RUSH-3227). Bundling the notice
+ * behind `!isRaw` was the miss.
  */
 export function afterInteractiveRemoteExit(opts) {
     if (!opts.target)

package/dist/lib/hosts/registry.js

@@ -22,6 +22,7 @@ import { DevicesHostProvider } from './providers/devices.js';
 import { assertValidSshTarget } from '../ssh-exec.js';
 import { normalizeHost } from '../machine-id.js';
 import { readMeta } from '../state.js';
+import { unionDeviceHosts } from '../devices/device-docs.js';
 import { isSshConfigHost } from './ssh-config.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { loadDevices } from '../devices/registry.js';
@@ -187,7 +188,9 @@ export async function matchHost(name, opts = {}) {
     catch {
         reg = {};
     }
-    const overlay = readMeta().hosts?.[host];
+    // The effective host overlay is the cross-box union of every device doc's
+    // `hosts:` block (PHNX-3315), plus any lingering central-legacy entry.
+    const overlay = { ...readMeta().hosts, ...unionDeviceHosts() }[host];
     // 1. A registered device (normalized match) — its live address/OS/presence win.
     const device = matchDevice(host, reg);
     if (device)

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

@@ -19,6 +19,7 @@
 import { loadDevicesSync } from '../devices/registry.js';
 import { readDeviceConfigValues } from '../device-config.js';
 import { readMeta } from '../state.js';
+import { unionDeviceHosts } from '../devices/device-docs.js';
 /** Resolve the OS/platform string for a host name, or undefined if unknown. */
 export function resolveRemoteOsSync(name) {
     try {
@@ -33,5 +34,6 @@ export function resolveRemoteOsSync(name) {
         // A corrupt/unreadable device registry must never break command building —
         // fall through to the host overlay and ultimately the POSIX default.
     }
-    return readMeta().hosts?.[name]?.os;
+    // Cross-box union of the device-scoped host overlays, central legacy as base.
+    return ({ ...readMeta().hosts, ...unionDeviceHosts() }[name])?.os;
 }

package/dist/lib/installations/versions.js

@@ -49,7 +49,7 @@ import { emit } from '../feed/events.js';
 import { safeJoin } from '../paths.js';
 import { readSkillSourceCommandMarker, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from '../command-skills.js';
 import { getWriter, getDetector } from '../staleness/registry.js';
-import { syncMemoryToVersionHome } from '../memory.js';
+import { syncMemoryToVersionHome, syncClaudeProjectMemoryDir } from '../memory.js';
 import { listPluginSkillNames, resolveCommandSource, resolveSkillSource } from '../staleness/writers/sources.js';
 import { syncProjectResourcesToAgent } from '../project-resources.js';
 import { installClaudeStatusLine } from '../claude-statusline.js';
@@ -2860,6 +2860,14 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     if (supports(agent, 'memory', version).ok) {
         syncMemoryToVersionHome(agent, versionHome, cwd);
     }
+    // Claude Code's own NATIVE per-project auto-memory (.claude/projects/<key>/memory/,
+    // PHNX-2817) is a separate, unmanaged directory Claude writes into itself — make it
+    // version-independent the same way project-level rules already are, via a shared
+    // symlink, so a note survives an agent version upgrade instead of vanishing into a
+    // fresh, empty version home.
+    if (agent === 'claude') {
+        syncClaudeProjectMemoryDir(versionHome, cwd);
+    }
     // Prune resources deleted from source (RUSH-2438). Runs only on a repo-scope
     // reconcile (`options.prune`) with a caller selection — a full sync
     // (`!userPassedSelection`) already sweeps orphans above, and an additive

package/dist/lib/linux-userns.d.ts

@@ -0,0 +1,58 @@
+/** Path of the AppArmor knob that gates unprivileged userns on Ubuntu 23.10+. */
+export declare const APPARMOR_USERNS_SYSCTL_PATH = "/proc/sys/kernel/apparmor_restrict_unprivileged_userns";
+export type UsernsState = 
+/** A new user namespace with a uid map can be created — Codex's sandbox works. */
+'ok'
+/** Unprivileged userns is restricted — Codex's bwrap sandbox cannot start. */
+ | 'blocked'
+/** Could not determine (non-Linux, or the probe could not run). */
+ | 'unknown';
+export interface UsernsStatus {
+    state: UsernsState;
+    /** One-line human reason, present when `blocked` or `unknown`. */
+    reason?: string;
+}
+/** The raw signals the pure interpreter reasons over. */
+export interface UsernsInputs {
+    platform: NodeJS.Platform;
+    /**
+     * Contents of {@link APPARMOR_USERNS_SYSCTL_PATH} trimmed, or null when the
+     * file is absent (older kernels / no AppArmor userns mediation).
+     */
+    apparmorRestrict: string | null;
+    /**
+     * Result of actually attempting to create a user namespace with a uid map:
+     *   - 'ok'      → the probe created the namespace and mapped root.
+     *   - 'denied'  → the kernel refused the uid_map write (the restricted case).
+     *   - 'no-tool' → the probe binary (`unshare`) was missing or failed to spawn.
+     */
+    unshareProbe: 'ok' | 'denied' | 'no-tool';
+}
+/**
+ * Decide userns availability from raw signals. Pure — no I/O.
+ *
+ * The definitive signal is the actual probe: if we successfully created a userns
+ * and wrote a uid map, the sandbox works regardless of the sysctl (an AppArmor
+ * profile may grant a specific binary `userns` even while the global knob is 1).
+ * A denied probe is a hard `blocked`. When the probe tool is missing we fall back
+ * to the sysctl: `1` → `blocked`, `0`/absent → `unknown` (we could not prove it,
+ * and refuse to claim `ok` we did not observe).
+ */
+export declare function interpretUsernsInputs(inputs: UsernsInputs): UsernsStatus;
+/** Read the AppArmor userns sysctl, or null when the file is absent. */
+export declare function readApparmorRestrict(sysctlPath?: string): string | null;
+/**
+ * Actually try to create a user namespace and map root inside it — the same
+ * operation bwrap performs (`unshare --user --map-root-user`). This is the ground
+ * truth: it observes exactly what the kernel/AppArmor policy permits for *this*
+ * process, rather than inferring from the sysctl alone.
+ */
+export declare function probeUnshare(): 'ok' | 'denied' | 'no-tool';
+/**
+ * Resolve whether an unprivileged user namespace can be created on this host,
+ * cached for the process (the answer is a stable property of the box). Non-Linux
+ * short-circuits to `ok` without spawning anything.
+ */
+export declare function probeUnprivilegedUserns(platform?: NodeJS.Platform): UsernsStatus;
+/** Test-only: drop the process cache so a test can re-probe. */
+export declare function resetUsernsCacheForTests(): void;

package/dist/lib/linux-userns.js

@@ -0,0 +1,116 @@
+/**
+ * Unprivileged user-namespace availability on Linux — the capability Codex's
+ * Linux sandbox needs, and the one Ubuntu 23.10+ restricts by default.
+ *
+ * Codex ≥0.146 implements its `read-only` and `workspace-write` sandbox modes on
+ * Linux with a bundled **bubblewrap** (`bwrap`), extracted per-run to
+ * `$CODEX_HOME/tmp/arg0/codex-XXXX/` and exec'd from a memfd. bwrap sets up its
+ * mounts inside a fresh **unprivileged user namespace** (`--unshare-user`, then a
+ * write to `/proc/self/uid_map`). Ubuntu 24.04 ships
+ * `kernel.apparmor_restrict_unprivileged_userns=1`, which denies that to an
+ * unconfined binary — so bwrap dies with `bwrap: setting up uid map: Permission
+ * denied` and a headless Codex run lands zero tools (no file writes, no shell).
+ * `danger-full-access` (our `skip` mode) drops the sandbox and is the only mode
+ * that avoids bwrap; the legacy Landlock backend is gone (`use_linux_sandbox_bwrap`
+ * is `removed`, `use_legacy_landlock` panics under the permission-profile model).
+ *
+ * This module is the single detector. It is pure at its core
+ * ({@link interpretUsernsInputs}) so the decision is unit-testable without a
+ * shell, and {@link probeUnprivilegedUserns} gathers the real inputs once per
+ * process. See PHNX-3285.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+/** Path of the AppArmor knob that gates unprivileged userns on Ubuntu 23.10+. */
+export const APPARMOR_USERNS_SYSCTL_PATH = '/proc/sys/kernel/apparmor_restrict_unprivileged_userns';
+/**
+ * Decide userns availability from raw signals. Pure — no I/O.
+ *
+ * The definitive signal is the actual probe: if we successfully created a userns
+ * and wrote a uid map, the sandbox works regardless of the sysctl (an AppArmor
+ * profile may grant a specific binary `userns` even while the global knob is 1).
+ * A denied probe is a hard `blocked`. When the probe tool is missing we fall back
+ * to the sysctl: `1` → `blocked`, `0`/absent → `unknown` (we could not prove it,
+ * and refuse to claim `ok` we did not observe).
+ */
+export function interpretUsernsInputs(inputs) {
+    if (inputs.platform !== 'linux')
+        return { state: 'ok' };
+    if (inputs.unshareProbe === 'ok')
+        return { state: 'ok' };
+    if (inputs.unshareProbe === 'denied') {
+        const via = inputs.apparmorRestrict === '1'
+            ? ' (kernel.apparmor_restrict_unprivileged_userns=1)'
+            : '';
+        return {
+            state: 'blocked',
+            reason: `the kernel denied creating an unprivileged user namespace${via}`,
+        };
+    }
+    // Probe tool unavailable — lean on the AppArmor knob.
+    if (inputs.apparmorRestrict === '1') {
+        return {
+            state: 'blocked',
+            reason: 'unprivileged user namespaces are AppArmor-restricted ' +
+                '(kernel.apparmor_restrict_unprivileged_userns=1) and `unshare` was not available to confirm',
+        };
+    }
+    return {
+        state: 'unknown',
+        reason: '`unshare` was not available to probe user-namespace support',
+    };
+}
+/** Read the AppArmor userns sysctl, or null when the file is absent. */
+export function readApparmorRestrict(sysctlPath = APPARMOR_USERNS_SYSCTL_PATH) {
+    try {
+        return fs.readFileSync(sysctlPath, 'utf8').trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Actually try to create a user namespace and map root inside it — the same
+ * operation bwrap performs (`unshare --user --map-root-user`). This is the ground
+ * truth: it observes exactly what the kernel/AppArmor policy permits for *this*
+ * process, rather than inferring from the sysctl alone.
+ */
+export function probeUnshare() {
+    try {
+        execFileSync('unshare', ['--user', '--map-root-user', 'true'], {
+            stdio: 'ignore',
+            timeout: 5000,
+        });
+        return 'ok';
+    }
+    catch (err) {
+        // ENOENT / spawn failure → the tool isn't here; anything else (nonzero exit
+        // from the denied uid_map write) is the restricted case.
+        const code = err?.code;
+        if (code === 'ENOENT')
+            return 'no-tool';
+        return 'denied';
+    }
+}
+let cached = null;
+/**
+ * Resolve whether an unprivileged user namespace can be created on this host,
+ * cached for the process (the answer is a stable property of the box). Non-Linux
+ * short-circuits to `ok` without spawning anything.
+ */
+export function probeUnprivilegedUserns(platform = process.platform) {
+    if (platform !== 'linux')
+        return { state: 'ok' };
+    if (cached)
+        return cached;
+    cached = interpretUsernsInputs({
+        platform,
+        apparmorRestrict: readApparmorRestrict(),
+        unshareProbe: probeUnshare(),
+    });
+    return cached;
+}
+/** Test-only: drop the process cache so a test can re-probe. */
+export function resetUsernsCacheForTests() {
+    cached = null;
+}

package/dist/lib/memory.d.ts

@@ -53,3 +53,29 @@ export declare function rebuildMemoryIndex(dir: string): void;
 export declare function memoryTargetDir(agent: AgentId): string;
 /** Copy canonical layered memory into one version home. Returns fact names written. */
 export declare function syncMemoryToVersionHome(agent: AgentId, versionHome: string, cwd?: string): string[];
+/**
+ * Canonical shared dir for Claude Code's NATIVE per-project auto-memory —
+ * `<versionHome>/.claude/projects/<project-key>/memory/*.md`, the freeform
+ * notes Claude writes for itself during a session. Distinct from the layered
+ * `memory` resource above (~/.agents/memory/ facts synced into
+ * `.claude/memory/`): this dir is keyed by project (via
+ * {@link claudeProjectDirName}), not by agent version, and Claude Code itself
+ * decides what goes in it — agents-cli only makes the directory
+ * version-independent, never writes into it.
+ */
+export declare function getClaudeProjectMemoryDir(cwd: string): string;
+/**
+ * Make Claude Code's native per-project memory dir version-independent by
+ * symlinking `<versionHome>/.claude/projects/<project-key>/memory/` into the
+ * one canonical dir every installed Claude version's home shares for this
+ * project (PHNX-2817). Without this, `getVersionHomePath` gives every
+ * installed version its own isolated HOME, so a note written under one
+ * version is invisible under another — the directory is just empty there.
+ *
+ * Idempotent and safe to call on every sync: a dir already linked to the
+ * canonical target is left alone; a PRE-EXISTING real directory with content
+ * (the common case today, since this bug has always left one behind) has its
+ * files migrated into the canonical dir first — never discarded — before
+ * being replaced by the symlink.
+ */
+export declare function syncClaudeProjectMemoryDir(versionHome: string, cwd?: string): void;