@phnx-labs/agents-cli 1.20.83 → 1.20.84

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 1.20.84
+
+- **Agent onboarding cheat sheet and docs drift guard.** Added
+  `apps/cli/docs/AGENT-CHEATSHEET.md` as a one-page on-ramp for agents, wired it
+  from `apps/cli/AGENTS.md` and `apps/cli/docs/README.md`, and added
+  `scripts/verify-docs.sh` (plus a `verify-docs` npm script and CI job) to catch
+  broken relative links and missing entry-point wiring before merge.
+
+- **Codex can now build, test, and install without escalating to YOLO.** Codex's
+  `workspace-write` sandbox blocks `$HOME`, so `cargo build`, `go build`, `npm/bun install`,
+  `pip install` etc. failed on their out-of-workspace cache writes (`~/.cargo`, `GOCACHE`,
+  `~/.npm`, `~/.cache`, …) — which is what pushed people to `--mode full`
+  (`--dangerously-bypass-approvals-and-sandbox`). agents-cli now writes a platform-resolved
+  baseline of **regenerable toolchain caches** into Codex's `config.toml`
+  (`[sandbox_workspace_write].writable_roots`) on permission sync — `~/.cargo`, `~/.rustup`,
+  `~/.npm`, `~/.bun`, `~/go`, `~/.deno`, `~/.gradle`, `~/.m2`, `~/.gem`, plus `~/Library/Caches`
+  + `~/Library/pnpm` on macOS or `~/.cache` + `~/.local/{share,state}` on Linux. Credential dirs
+  (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.config`, `~/.netrc`) are deliberately excluded, so
+  `--mode auto` stays a real sandbox — far narrower than danger-full-access. Any
+  `writable_roots` you set yourself are preserved (unioned, never clobbered). Source:
+  `apps/cli/src/lib/permissions.ts` (`codexDefaultWritableRoots`, `mergeCodexSandboxWrite`).
+
+- **`agents sessions` team rows now show the team's target and teammate, not just
+  the slug.** Each teammate row reads `<team> · <teammate> · by <orchestrator> ·
+  <live turn | mission>`, where the mission is a one-line summary of the teammate's
+  spawn prompt (`assignedTask`, shown even before it has a transcript). Several
+  teams from one orchestrator stay legible (distinct team names) and each says what
+  it is for. `--active --json` carries `assignedTask`. Source:
+  `apps/cli/src/lib/session/active.ts`, `apps/cli/src/commands/sessions.ts`.
+
 ## 1.20.83
 
 - **Routines now treat date-specific cron schedules as one-shot jobs (RUSH-2074).**

package/dist/commands/sessions.js

@@ -247,7 +247,13 @@ export function buildSessionDescription(s) {
         return cleanPreview([todo, base].filter(Boolean).join(' · '));
     }
     if (s.context === 'teams') {
+        // A teams row identifies its TEAM, then the teammate within it, then who
+        // spun it up, then what it's working on — so several teams from one
+        // orchestrator stay distinct and each shows its target, not just its slug.
         const parts = [s.teamName];
+        // Teammate name (distinct from the team slug) — which member this row is.
+        if (s.label && s.label !== s.teamName)
+            parts.push(s.label);
         // Lineage: which orchestrator spun up this team. Prefer the resolved label,
         // else the short session id, so "by whom" is answerable at a glance.
         const orch = s.orchestratorLabel || (s.orchestratorSessionId ? s.orchestratorSessionId.slice(0, 8) : '');
@@ -255,12 +261,12 @@ export function buildSessionDescription(s) {
             parts.push(`by ${orch}`);
         if (todo)
             parts.push(todo);
-        if (s.preview)
-            parts.push(s.preview);
-        else if (s.label)
-            parts.push(s.label);
-        else if (s.topic)
-            parts.push(s.topic);
+        // Target: the live latest turn if working, else the assigned mission (the
+        // team's task/target, shown even before the teammate has a transcript), else
+        // the transcript topic.
+        const target = s.preview || s.assignedTask || s.topic;
+        if (target)
+            parts.push(target);
         return cleanPreview(parts.filter(Boolean).join(' · '));
     }
     // Terminal, headless, or sub-agent: todos + live preview, then label, then topic.

package/dist/lib/permissions.d.ts

@@ -233,6 +233,27 @@ export declare function convertToKimiFormat(set: PermissionSet): {
  * OpenCode uses: { permission: { bash: { "git *": "allow", "rm *": "deny" } } }
  */
 export declare function convertToOpenCodeFormat(set: PermissionSet): OpenCodePermissions;
+/**
+ * Default extra writable roots for Codex's `workspace-write` sandbox: the
+ * regenerable package/toolchain caches that build/test/install write OUTSIDE the
+ * workspace (cargo registry, npm/bun/pnpm caches, GOPATH/GOCACHE, the OS cache
+ * root, …). Without these, a sandboxed `cargo build` / `go build` / `npm install`
+ * fails on its cache write, which is what pushes users to `--mode full` (YOLO).
+ *
+ * Credential dirs (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.config`, `~/.netrc`) are
+ * deliberately EXCLUDED so the sandbox stays meaningful — this is far from
+ * danger-full-access. Resolved per platform + home; each box regenerates its own
+ * Codex config on sync, so the paths always match the box Codex runs on.
+ */
+export declare function codexDefaultWritableRoots(home?: string, platform?: NodeJS.Platform): string[];
+/**
+ * Merge Codex `[sandbox_workspace_write]` config, UNIONing `writable_roots` so a
+ * baseline cache root never clobbers a root the user configured directly (a
+ * plain object spread would overwrite the whole array), while merging scalar
+ * keys (`network_access`) normally. Shared by the user- and version-scoped Codex
+ * config writers so the two can't drift.
+ */
+export declare function mergeCodexSandboxWrite(existing: Record<string, unknown> | undefined, incoming: NonNullable<CodexPermissions['sandbox_workspace_write']>): Record<string, unknown>;
 /**
  * Convert canonical permission set to Codex format.
  * Codex uses coarse-grained modes, so we infer the best fit.

package/dist/lib/permissions.js

@@ -1007,6 +1007,48 @@ export function convertToOpenCodeFormat(set) {
         },
     };
 }
+/**
+ * Default extra writable roots for Codex's `workspace-write` sandbox: the
+ * regenerable package/toolchain caches that build/test/install write OUTSIDE the
+ * workspace (cargo registry, npm/bun/pnpm caches, GOPATH/GOCACHE, the OS cache
+ * root, …). Without these, a sandboxed `cargo build` / `go build` / `npm install`
+ * fails on its cache write, which is what pushes users to `--mode full` (YOLO).
+ *
+ * Credential dirs (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.config`, `~/.netrc`) are
+ * deliberately EXCLUDED so the sandbox stays meaningful — this is far from
+ * danger-full-access. Resolved per platform + home; each box regenerates its own
+ * Codex config on sync, so the paths always match the box Codex runs on.
+ */
+export function codexDefaultWritableRoots(home = HOME, platform = process.platform) {
+    const shared = ['.cargo', '.rustup', '.npm', '.bun', 'go', '.deno', '.gradle', '.m2', '.gem'];
+    const roots = shared.map((d) => path.join(home, d));
+    if (platform === 'darwin') {
+        roots.push(path.join(home, 'Library', 'Caches'), path.join(home, 'Library', 'pnpm'));
+    }
+    else {
+        // Linux/XDG: ~/.cache covers pip, uv, go-build, ms-playwright, etc.
+        roots.push(path.join(home, '.cache'), path.join(home, '.local', 'share'), path.join(home, '.local', 'state'));
+    }
+    return roots;
+}
+/**
+ * Merge Codex `[sandbox_workspace_write]` config, UNIONing `writable_roots` so a
+ * baseline cache root never clobbers a root the user configured directly (a
+ * plain object spread would overwrite the whole array), while merging scalar
+ * keys (`network_access`) normally. Shared by the user- and version-scoped Codex
+ * config writers so the two can't drift.
+ */
+export function mergeCodexSandboxWrite(existing, incoming) {
+    const existingRoots = Array.isArray(existing?.writable_roots)
+        ? existing.writable_roots
+        : [];
+    const unionRoots = [...new Set([...existingRoots, ...(incoming.writable_roots ?? [])])];
+    return {
+        ...existing,
+        ...incoming,
+        ...(unionRoots.length > 0 ? { writable_roots: unionRoots } : {}),
+    };
+}
 /**
  * Convert canonical permission set to Codex format.
  * Codex uses coarse-grained modes, so we infer the best fit.
@@ -1042,6 +1084,15 @@ export function convertToCodexFormat(set, cwd) {
             network_access: true,
         };
     }
+    // Baseline (unconditional): always grant the regenerable build/test/install
+    // caches as writable roots so `agents run codex` in workspace-write can build,
+    // test, and install without escalating to danger-full-access. Merged with
+    // network_access above when set; applyCodexPermissions unions these with any
+    // writable_roots the user configured directly.
+    result.sandbox_workspace_write = {
+        ...result.sandbox_workspace_write,
+        writable_roots: codexDefaultWritableRoots(),
+    };
     return result;
 }
 // ============================================================================
@@ -1333,8 +1384,10 @@ function applyCodexPermissions(set, scope = 'user', cwd, merge = true) {
         }
         if (newPermissions.sandbox_workspace_write) {
             const existing = config.sandbox_workspace_write;
+            // merge=false is a deliberate full replace (drops any user-custom roots);
+            // production sync always passes merge=true, taking the union path.
             config.sandbox_workspace_write = merge
-                ? { ...existing, ...newPermissions.sandbox_workspace_write }
+                ? mergeCodexSandboxWrite(existing, newPermissions.sandbox_workspace_write)
                 : newPermissions.sandbox_workspace_write;
         }
         fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');
@@ -1450,8 +1503,10 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             }
             if (newPermissions.sandbox_workspace_write) {
                 const existing = config.sandbox_workspace_write;
+                // merge=false is a deliberate full replace (drops any user-custom roots);
+                // production sync always passes merge=true, taking the union path.
                 config.sandbox_workspace_write = merge
-                    ? { ...existing, ...newPermissions.sandbox_workspace_write }
+                    ? mergeCodexSandboxWrite(existing, newPermissions.sandbox_workspace_write)
                     : newPermissions.sandbox_workspace_write;
             }
             fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');

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

@@ -158,6 +158,15 @@ export interface ActiveSession {
     /** Display label for the orchestrator (its topic/label), resolved when the
      * orchestrator is itself present in the active set. Display-only. */
     orchestratorLabel?: string;
+    /**
+     * For a teams teammate: a one-line summary of the mission it was spawned with
+     * (the `prompt` stored on the teammate record — the team's task/target), so the
+     * listing answers "what is this team working on", not just its name. Survives
+     * before the teammate has produced any transcript (a pending/staged teammate
+     * still shows its target). Distinct from `topic`, which is derived from the
+     * teammate's own transcript once it starts.
+     */
+    assignedTask?: string;
     agentId?: string;
     cloudProvider?: string;
     cloudTaskId?: string;
@@ -338,6 +347,12 @@ interface LiveSignals {
  * {@link resolveFallbackStatus} reports the honest live floor (`running`).
  */
 export declare function computeLiveSignals(kind: string, sessionFile: string | undefined, cwd: string | undefined, pidAlive: boolean): LiveSignals;
+/**
+ * One-line summary of a teammate's spawn prompt — the team's task/target. Takes
+ * the first non-empty line, strips a leading `MISSION:`/`CONTEXT:`/`TASK:` label,
+ * and truncates. Exported for tests.
+ */
+export declare function summarizeMission(prompt: string | null | undefined): string | undefined;
 /** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
 export declare function listTeamsActive(): Promise<ActiveSession[]>;
 /** Live editor-terminal agents across every IDE window. */

package/dist/lib/session/active.js

@@ -576,6 +576,22 @@ function quickExtractTopic(sessionFile) {
     }
     return undefined;
 }
+/**
+ * One-line summary of a teammate's spawn prompt — the team's task/target. Takes
+ * the first non-empty line, strips a leading `MISSION:`/`CONTEXT:`/`TASK:` label,
+ * and truncates. Exported for tests.
+ */
+export function summarizeMission(prompt) {
+    if (!prompt)
+        return undefined;
+    const firstLine = prompt.split('\n').map((l) => l.trim()).find(Boolean);
+    if (!firstLine)
+        return undefined;
+    const cleaned = firstLine.replace(/^(MISSION|CONTEXT|TASK|GOAL|OBJECTIVE)\s*[:\-—]\s*/i, '').trim();
+    if (!cleaned)
+        return undefined;
+    return cleaned.length > 80 ? `${cleaned.slice(0, 79)}…` : cleaned;
+}
 /** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
 export async function listTeamsActive() {
     const mgr = new AgentManager();
@@ -607,6 +623,7 @@ export async function listTeamsActive() {
             startedAtMs: a.startedAt.getTime(),
             lastActivityMs: sessionFileTimes(sessionFile).mtimeMs,
             teamName: a.taskName,
+            assignedTask: summarizeMission(a.prompt),
             agentId: a.agentId,
             // The frozen actor stamped on the teammate record (RUSH-2028) — who ran
             // this teammate, surfaced as the owner in --active (RUSH-2018); sidecar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.83",
+  "version": "1.20.84",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -55,6 +55,7 @@
     "start": "node dist/index.js",
     "test": "node ./node_modules/vitest/vitest.mjs run",
     "test:remote": "scripts/sandbox.sh 'bun install && bun run build && bun run test'",
+    "verify-docs": "scripts/verify-docs.sh",
     "test:watch": "node ./node_modules/vitest/vitest.mjs"
   },
   "keywords": [