@phnx-labs/agents-cli 1.20.82 → 1.20.84

package/CHANGELOG.md

@@ -1,5 +1,143 @@
 # 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).**
+  `agents routines add --schedule "0 14 29 7 *"` now warns, persists
+  `runOnce: true`, marks the routine as one-shot in `routines list`, and
+  `agents routines cleanup` removes completed expired one-shots that still have
+  user-layer YAML. Source: `apps/cli/src/lib/routines.ts`,
+  `apps/cli/src/lib/scheduler.ts`, `apps/cli/src/commands/routines.ts`.
+
+- **`agents routines list` groups terminal output by device and placement
+  (RUSH-2075).** The default table is bucketed under this machine, fleet-wide,
+  cloud, named devices, and named hosts with offline/unknown registry hints;
+  `--flat` keeps the legacy single table and `--json` remains a flat payload.
+  Source: `apps/cli/src/commands/routines.ts`.
+
+- **`agents.yaml` no longer churns on every meta write.** `writeMetaUnlocked` wrote
+  the central config with `yaml.stringify`, which strips all comments — so the
+  freshly-serialized bytes never matched the comment-annotated file on disk,
+  `writeIfChanged` rewrote it on every meta write, and the perpetually-dirty tree
+  wedged `agents sync` ("Blocked by local changes") across the fleet. It now
+  serializes via a `yaml.Document` round-trip (`serializeCentral`) that edits only
+  the keys that actually changed, so comments, key ordering, and untouched
+  top-level blocks (e.g. `hosts:`) are byte-stable — and a write that changes no
+  central field leaves `agents.yaml` untouched. Source: `apps/cli/src/lib/state.ts`.
+
+- **`agents run codex` can now reach the fleet from inside its sandbox.** Codex's
+  `workspace-write` sandbox blocks `$HOME` (verified against the live CLI and OpenAI's
+  sandbox docs), but the model routinely shells out to `agents ...`, whose runtime state
+  lives under `~/.agents` — the SSH askpass shim (`~/.agents/.cache/devices/askpass.sh`),
+  the device/stats cache, secrets, session writes, config tunings. Those inner writes hit
+  `EROFS` (`agents ssh` died before connecting, so a remote `agents run codex` could not
+  SSH or self-tune), and the fix was previously left to the caller (teams pass
+  `--add-dir ~/.agents` explicitly; a plain `agents run` never did). `buildExecCommand`
+  now grants `~/.agents` as an extra writable root whenever Codex runs `workspace-write`
+  (`--mode edit`/`auto`) — via `--add-dir` on fresh runs (deduped against user
+  `--add-dir`s) and via `-c sandbox_workspace_write.writable_roots` on resume forms (which
+  reject `--add-dir`). This is the officially-recommended way to widen scope "without
+  removing the sandbox entirely" — far narrower than `--mode skip` (danger-full-access).
+  `plan` (read-only) and `skip` (sandbox already dropped) are unaffected. Source:
+  `apps/cli/src/lib/exec.ts` (`buildExecCommand`, `codexWritableRootsConfig`).
+
+- **Fix headless release signing (`errSecInternalComponent`).** `headless-sign-context.sh` now runs `security set-key-partition-list` right after unlocking `rush-signing.keychain-db`, authorizing `codesign`/`apple-tool` to use the Developer ID key non-interactively. Without it, the key's ACL prompts for UI approval that a headless SSH release session can't answer, so `codesign` fails and the npm publish halts. Idempotent; runs every release. Source: `apps/cli/scripts/headless-sign-context.sh`.
+
+- **Cmd-Shift-V clip paste no longer breaks with an "sshd-keygen-wrapper would like
+  to control this computer" prompt.** A menu-bar helper started from an ssh session
+  registered the global chords but could never service them: macOS attributes its
+  Accessibility request to the responsible process, `/usr/libexec/sshd-keygen-wrapper`,
+  not to the helper's bundle, so the prompt named a process whose grant does nothing
+  for the paste (and, if granted, hands keystroke synthesis to everything any ssh
+  session spawns). `RegisterEventHotKey` is first-come, and the prompt naming
+  sshd-keygen-wrapper is itself the evidence that this copy — not the trusted
+  launchd-managed one — had registered Cmd-Shift-V and was servicing it. The
+  interactive mode now refuses to start over a remote shell, and refuses
+  unrecognized arguments: an unknown flag used to fall straight through to the
+  status-bar app, which is how a stray `MenubarHelper --self-test` from a verify run
+  became a permanent second helper. `launchctl bootstrap` (`agents menubar enable`)
+  is unaffected, including when run over ssh. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/Guards.swift`.
+
+- **`agents menubar status` now names a second helper process instead of reporting a
+  healthy `running: yes`.** The check was `pgrep -f MenubarHelper`, which matches any
+  process with that name, so a stray copy holding the global chords looked identical
+  to a working install. Status now identifies the helper by its resolved executable
+  (`ps -o comm=`), reports `running` only for the installed bundle, and lists every
+  other live copy with its pid under `foreignInstances` (also in `--json`). Source:
+  `apps/cli/src/lib/menubar/install-menubar.ts`.
+
+- **The menu bar now says so when a hotkey is unavailable or the paste is not
+  permitted.** A `RegisterEventHotKey` conflict only wrote a line to a launchd log,
+  and a missing Accessibility grant made `Clip.inject` return silently — both looked
+  exactly like a dead hotkey. A stolen chord now posts a notification naming it, and a
+  denied grant copies the `host:path` reference to the clipboard and says which
+  setting to grant, so the clip is never lost. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/Hotkey.swift`,
+  `apps/cli/menubar/Sources/MenubarHelper/Clip.swift`.
+
+- **Fix the release catch-up path aborting on an unbound variable.** When a release PR had already merged and only the tag + publish remained, `release.sh` re-validated CI and then aborted with `line 933: RELEASE_COMMIT: unbound variable`, so the retry never reached npm. The catch-up block that runs when `main` sits exactly at the release merge commit never set `HISTORICAL_CATCHUP`, so phase 4 took the normal-release branch and read `RELEASE_COMMIT`, which only the branch-creating path defines. It now sets the flag, and phase 4 resolves the release commit from the merged PR (`MERGED_RELEASE_SHA` + `CI_TESTED_HEAD`) as intended. This is why 1.20.79, 1.20.80, and 1.20.81 were tagged but never published. Source: `apps/cli/scripts/release.sh`.
+
+- **Removed `agents check` / `agents resources` now forward to their replacements
+  instead of erroring (RUSH-1234).** After the command consolidation, running the
+  removed names produced a bare `unknown command` (their edit-distance to `doctor`
+  was too far to even trigger a "did you mean"). They are now hidden tombstone
+  commands that print a one-line deprecation notice to stderr and re-run the
+  replacement, preserving flags and exit codes: `agents check …` runs
+  `agents doctor --check …` (so `--json` / `--quiet` / `--devices` and the CI
+  drift-gate exit code carry through), and `agents resources …` runs
+  `agents view --merged …` (with `agents inspect <target>` pointed to for
+  per-agent/per-repo detail). The notice goes to stderr so a `--json` consumer's
+  stdout stays clean. Source: `apps/cli/src/index.ts`.
+
+- **`agents sessions --host`/`--device <box>` now opens the interactive fleet
+  browser instead of a raw text dump.** A bare remote listing on a TTY folds the
+  named box into the same preview-rich, selectable picker as the local view (it
+  previously short-circuited to the legacy per-host stream — non-interactive, no
+  previews). A `--host` *query*, a render/filter flag, `--json`, or a
+  non-interactive caller keep the streamed output. Source:
+  `apps/cli/src/commands/sessions.ts`.
+
+- **`agents sessions` now shows which orchestrator spawned each team.** A teams
+  teammate row was keyed off its orchestrator's session id (captured from
+  `AGENTS_SESSION_ID` at spawn), which both hid the lineage and mislabeled the
+  teammate with the orchestrator's id/topic. The teammate now keys off its own
+  transcript, exposes the orchestrator as `orchestratorSessionId` (+ a resolved
+  `orchestratorLabel`) in `--active --json`, and the listing renders
+  `<team> · by <orchestrator>` so "which session spun up this team" is answerable
+  at a glance. Source: `apps/cli/src/lib/session/active.ts`,
+  `apps/cli/src/commands/sessions.ts`.
+
 ## 1.20.82
 
 - **Codex hook sync no longer leaves startup warnings after upgrades.** The Codex

package/README.md

@@ -306,7 +306,7 @@ agents sessions detach a1b2c3d4     # go headless in the background, keep workin
 agents sessions attach a1b2c3d4     # resume it interactively, right here
 ```
 
-Both are agent-agnostic -- they route through the same `agents run --resume` path (native resume for Claude/Codex, `/continue` replay for the rest). `agents sessions --active` marks each session's `presence` -- `attached` (you're watching it), `background` (running headless), or `parked` (its background run finished) -- so the menu bar and Factory show where every agent is. In the Factory extension, **Agents: Detach** (`Cmd/Ctrl+K B`) and **Agents: Attach** (`Cmd/Ctrl+K A`) do the same over the focused terminal.
+Both are agent-agnostic -- they route through the same `agents run --resume` path (native resume for Claude/Codex, `/continue` replay for the rest). `agents sessions --active` shows each session's **owner** (the human who launched it, resolved from the tailnet identity, or `-` for an unresolved local run) and its `presence` -- `attached` (you're watching it), `background` (running headless), or `parked` (its background run finished) -- so the menu bar and Factory show who is running what, and where. In the Factory extension, **Agents: Detach** (`Cmd/Ctrl+K B`) and **Agents: Attach** (`Cmd/Ctrl+K A`) do the same over the focused terminal.
 
 ---
 

package/dist/commands/doctor.d.ts

@@ -24,6 +24,7 @@
 import type { Command } from 'commander';
 import { type FleetDivergenceReport } from '../lib/devices/fleet-divergence.js';
 import { type VersionResourceReport } from '../lib/doctor-diff.js';
+import { type DuplicateVersionHook } from '../lib/hooks.js';
 import { type SyncStatusRow, type OrphanRow } from '../lib/drift.js';
 import { type FetchStatusMarker } from '../lib/auto-pull.js';
 export declare function wrapLine(prefix: string, text: string, width?: number): string[];
@@ -106,5 +107,5 @@ export declare function healthBlockLines(verdict: DoctorVerdict, opts: {
  * and orphan resources into severity-tagged findings. Agent-agnostic: every
  * installed version is classified the same way. Pure, so it is unit-testable.
  */
-export declare function computeOverviewHealth(syncRows: SyncStatusRow[], orphanRows: OrphanRow[], repoBehindMarkers: FetchStatusMarker[]): DoctorVerdict;
+export declare function computeOverviewHealth(syncRows: SyncStatusRow[], orphanRows: OrphanRow[], repoBehindMarkers: FetchStatusMarker[], duplicateHooks?: DuplicateVersionHook[]): DoctorVerdict;
 export declare function registerDoctorCommand(program: Command): void;

package/dist/commands/doctor.js

@@ -18,7 +18,7 @@ import { formatSignInBadge } from '../lib/signin-badge.js';
 import { getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalledVersions, parseAgentSpec, } from '../lib/versions.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
-import { checkVersionHookWiring, registerHooksToSettings } from '../lib/hooks.js';
+import { checkVersionHookWiring, inspectDuplicateVersionHooks, registerHooksToSettings } from '../lib/hooks.js';
 import { isVersionIsolated } from '../lib/versions.js';
 import { computeDrift, checkSyncStatus, countOrphans, computeSourceBehind } from '../lib/drift.js';
 import { readAuthHealthCache, summarizeHostAuth } from '../lib/auth-health.js';
@@ -67,11 +67,11 @@ function printWrappedLine(prefix, text) {
     for (const line of wrapLine(prefix, text))
         console.log(chalk.gray(line));
 }
-function renderOverviewText(clis, syncRows, orphanRows, hostClis, signIn, repoBehindMarkers) {
+function renderOverviewText(clis, syncRows, orphanRows, hostClis, signIn, repoBehindMarkers, duplicateHooks) {
     // Triaged health banner FIRST, so a user running bare `agents doctor` sees what
     // is unhealthy, why it matters, and the exact fix before scrolling the detail
     // sections below. Same triage model as target mode, aggregated across versions.
-    const overviewHealth = computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers);
+    const overviewHealth = computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers, duplicateHooks);
     console.log(chalk.bold('Health'));
     renderHealthBlock(overviewHealth, {
         healthySummary: syncRows.length
@@ -827,9 +827,26 @@ function renderHealthBlock(verdict, opts) {
  * and orphan resources into severity-tagged findings. Agent-agnostic: every
  * installed version is classified the same way. Pure, so it is unit-testable.
  */
-export function computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers) {
+export function computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers, duplicateHooks = []) {
     const issues = [];
     const pretty = (agent, version) => `${AGENT_NAMES[agent] || agent}@${version}`;
+    // critical/warning: same hook resource materialized in several version homes.
+    // Different content is more severe because a stale copy can disagree with
+    // the active gate; byte-identical copies are noise and duplicate runtime cost.
+    for (const finding of duplicateHooks) {
+        const versions = finding.copies.map((copy) => copy.version).join(', ');
+        const active = finding.authoritative.version;
+        const drift = finding.kind === 'drift';
+        issues.push({
+            severity: drift ? 'critical' : 'warning',
+            category: drift ? 'duplicate-hook-drift' : 'duplicate-hook',
+            subject: `${finding.agent}/${finding.name}`,
+            impact: `${drift ? 'different content' : 'identical content'} across versions ${versions}; ${active} is authoritative`,
+            fix: `agents sync ${finding.agent}@${active} --yes`,
+            text: `${finding.name} ${drift ? 'drift' : 'duplicated'} across ${versions}`,
+            color: drift ? 'red' : 'yellow',
+        });
+    }
     // critical: unwired hooks / broken settings.json per version
     for (const row of syncRows) {
         const n = row.unwiredHooks ?? 0;
@@ -1406,6 +1423,7 @@ export function registerDoctorCommand(program) {
             const orphanRows = countOrphans();
             const hostClis = listCliStatus(cwd);
             const repoBehindMarkers = readRepoBehindMarkers();
+            const duplicateHooks = inspectDuplicateVersionHooks(cwd);
             // Advisory login state per installed agent (file-based getAccountInfo,
             // no home → the account-global/active credential). Best-effort: a probe
             // failure just leaves that agent's badge as "logged out".
@@ -1433,7 +1451,8 @@ export function registerDoctorCommand(program) {
                     // Triaged overview health — severity/category/subject/impact/fix per
                     // finding, aggregated across versions. Additive; existing consumers
                     // reading `sync`/`orphans`/`repos` are unaffected.
-                    health: computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers),
+                    health: computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers, duplicateHooks),
+                    duplicateHooks,
                     // This host's harness inventory — installed resources per kind,
                     // installed version ids per agent, and `.agents`/`.system` repo
                     // state — so `agents doctor --devices` can compare presence across
@@ -1461,7 +1480,7 @@ export function registerDoctorCommand(program) {
                 }, null, 2));
                 return;
             }
-            renderOverviewText(clis, syncRows, orphanRows, hostClis, signIn, repoBehindMarkers);
+            renderOverviewText(clis, syncRows, orphanRows, hostClis, signIn, repoBehindMarkers, duplicateHooks);
             // Point at the interactive reconcile when anything is out of sync — the
             // report shouldn't be a dead end. `agents status` runs the unified
             // home-reading engine and offers to sync (opt-in, never auto-fires here).

package/dist/commands/menubar.js

@@ -65,6 +65,18 @@ export function registerMenubarCommands(program) {
         console.log(`  current version    ${chalk.gray(s.currentVersion)}`);
         console.log(`  bundle source      ${s.source ? chalk.gray(s.source) : chalk.red('missing (cannot enable)')}`);
         console.log(`  disabled by user   ${yn(s.disabledByUser)}`);
+        if (s.foreignInstances.length > 0) {
+            // RegisterEventHotKey is first-come, so the helper that registered the
+            // chord first owns Cmd-Shift-V/O. A process list cannot say which that
+            // was — only that a rival exists — so report the conflict, not a
+            // winner. The loser
+            // has no other symptom: its chords simply never fire.
+            const n = s.foreignInstances.length;
+            console.log(chalk.yellow(`\n  ${n} other helper process${n === 1 ? '' : 'es'} running — ${n === 1 ? 'it' : 'they'} may hold Cmd-Shift-V/O instead of the installed one:`));
+            for (const p of s.foreignInstances)
+                console.log(chalk.gray(`    ${p.pid}  ${p.executable}`));
+            console.log(chalk.gray('  End it, then `agents menubar enable` to restart the installed helper.'));
+        }
         if (s.stale) {
             console.log(chalk.yellow('\n  Installed helper is stale — runs on next `agents` startup, or `agents menubar enable` now.'));
         }

package/dist/commands/routines.d.ts

@@ -6,13 +6,20 @@
  * Also exposes scheduler lifecycle controls (start/stop/status/logs).
  */
 import type { Command } from 'commander';
-import type { RunMeta } from '../lib/routines.js';
+import type { JobConfig, RunMeta } from '../lib/routines.js';
+import type { DeviceRegistry } from '../lib/devices/registry.js';
 /**
  * Human-friendly wall-clock a run took (e.g. "  · 3 min", "  · 45 sec"), or ""
  * when it hasn't completed or timestamps are unparseable. Leading separator lets
  * callers drop it straight into a status line.
  */
 export declare function formatRunDuration(startedAt: string, completedAt: string | null): string;
+export interface RoutineListGroup {
+    key: string;
+    title: string;
+    jobs: JobConfig[];
+}
+export declare function groupRoutineJobsByDevice(jobs: JobConfig[], registry: DeviceRegistry, self?: string): RoutineListGroup[];
 export declare function buildRunsJson(runs: RunMeta[]): Record<string, unknown>[];
 /** Register the `agents routines` command tree. */
 export declare function registerRoutinesCommands(program: Command): void;