@phnx-labs/agents-cli 1.20.82 → 1.20.84

package/dist/index.js

@@ -656,6 +656,41 @@ function registerJobsCronAliasCommand(p, alias) {
         await program.parseAsync(['node', 'agents', ...args]);
     });
 }
+/**
+ * Removed `check` command (RUSH-1234) — re-parses as `doctor --check`, forwarding
+ * any remaining flags so `check --quiet` / `check --json` / `check --devices` keep
+ * working and the drift-gate exit code survives the rename. The notice goes to
+ * stderr so `--json` stdout stays clean for CI parsers.
+ */
+function registerCheckTombstoneCommand(p) {
+    p.command('check', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async () => {
+        console.error(chalk.yellow('Deprecated: "agents check" is now "agents doctor --check". Running that for you.\n'));
+        const args = process.argv.slice(2);
+        args[0] = 'doctor';
+        args.splice(1, 0, '--check');
+        await program.parseAsync(['node', 'agents', ...args]);
+    });
+}
+/**
+ * Removed `resources` command (RUSH-1234) — re-parses as `view --merged` (the
+ * cross-layer, first-wins resource table now lives there; `agents inspect <target>`
+ * covers per-agent / per-repo detail). Forwards remaining flags like `--json`.
+ */
+function registerResourcesTombstoneCommand(p) {
+    p.command('resources', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async () => {
+        console.error(chalk.yellow('Deprecated: "agents resources" is now "agents view --merged" (use "agents inspect <target>" for per-agent/per-repo detail). Running that for you.\n'));
+        const args = process.argv.slice(2);
+        args[0] = 'view';
+        args.splice(1, 0, '--merged');
+        await program.parseAsync(['node', 'agents', ...args]);
+    });
+}
 /** Self-upgrade command (`agents upgrade [version]`). */
 function registerUpgradeCommand(p) {
     p.command('upgrade')
@@ -739,6 +774,16 @@ async function registerEagerForRequest(name) {
             registerJobsCronAliasCommand(program, name);
             await reg(loadRoutines);
             return true;
+        case 'check':
+            // The action re-parses as `doctor --check`, so doctor must exist too.
+            registerCheckTombstoneCommand(program);
+            await reg(loadDoctor);
+            return true;
+        case 'resources':
+            // The action re-parses as `view --merged`, so view must exist too.
+            registerResourcesTombstoneCommand(program);
+            await reg(loadView);
+            return true;
         case 'upgrade':
             registerUpgradeCommand(program);
             return true;
@@ -759,6 +804,7 @@ async function registerEagerForRequest(name) {
  */
 async function registerAllEagerCommands() {
     await reg(loadView);
+    registerResourcesTombstoneCommand(program);
     await reg(loadShare);
     await reg(loadSend);
     await reg(loadInspect);
@@ -791,6 +837,7 @@ async function registerAllEagerCommands() {
     await reg(loadTrash);
     await reg(loadRestore);
     await reg(loadDoctor);
+    registerCheckTombstoneCommand(program);
     await reg(loadApply);
     await reg(loadStatus);
     registerExecAliasCommand(program);

package/dist/lib/exec.d.ts

@@ -262,6 +262,13 @@ export declare const AGENT_COMMANDS: Record<AgentId, AgentCommandTemplate>;
  * return false resume via the universal Tier-2 `/continue` replay instead.
  */
 export declare function nativeResume(agent: AgentId): boolean;
+/**
+ * Build the `-c` value that adds `dir` to codex's workspace-write writable
+ * roots. Codex parses the value as TOML, so it's a single-element TOML array of
+ * one quoted string. Used on codex resume forms, which reject `--add-dir` and
+ * only accept `-c` config overrides.
+ */
+export declare function codexWritableRootsConfig(dir: string): string;
 /** Assemble the full CLI argument array for an agent invocation. */
 export declare function buildExecCommand(options: ExecOptions): string[];
 /** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */

package/dist/lib/exec.js

@@ -16,7 +16,7 @@ import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { resolveActor, actorEnv } from './actor.js';
-import { getShimsDir, getHistoryDir } from './state.js';
+import { getShimsDir, getHistoryDir, getUserAgentsDir } from './state.js';
 import { resolveCodexHome } from './codex-home.js';
 import { readCodexConfiguredModel } from './shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
@@ -573,6 +573,15 @@ export const AGENT_COMMANDS = {
 export function nativeResume(agent) {
     return AGENT_COMMANDS[agent]?.resume !== undefined;
 }
+/**
+ * Build the `-c` value that adds `dir` to codex's workspace-write writable
+ * roots. Codex parses the value as TOML, so it's a single-element TOML array of
+ * one quoted string. Used on codex resume forms, which reject `--add-dir` and
+ * only accept `-c` config overrides.
+ */
+export function codexWritableRootsConfig(dir) {
+    return `sandbox_workspace_write.writable_roots=[${JSON.stringify(dir)}]`;
+}
 /** Assemble the full CLI argument array for an agent invocation. */
 export function buildExecCommand(options) {
     const template = AGENT_COMMANDS[options.agent];
@@ -658,6 +667,18 @@ export function buildExecCommand(options) {
         // AGENT_COMMANDS.modeFlags drifted apart. Tests assert they agree.
         throw new Error(`Internal error: ${options.agent} declares '${resolvedMode}' in capabilities.modes but has no entry in AGENT_COMMANDS.modeFlags.${resolvedMode}.`);
     }
+    // Codex's workspace-write sandbox blocks $HOME (verified against the live CLI
+    // and OpenAI's sandbox docs: writable roots extend scope "without removing the
+    // sandbox entirely"). 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. Without ~/.agents as a writable root those
+    // inner writes fail with EROFS (e.g. `agents ssh` dies before connecting),
+    // which is why a remote `agents run codex` couldn't reach the fleet. Grant it
+    // implicitly whenever codex runs workspace-write — far narrower than --mode skip
+    // (danger-full-access). Fresh runs take --add-dir (below); resume forms reject
+    // --add-dir, so they take the same root via -c writable_roots here.
+    const codexWorkspaceWrite = options.agent === 'codex' && resolvedMode === 'edit';
     if (resumeSpec && 'subcommand' in resumeSpec) {
         if (resolvedMode === 'skip') {
             // skip = yolo on resume too; both `codex resume` (TUI) and
@@ -667,6 +688,8 @@ export function buildExecCommand(options) {
         else if (interactive) {
             // `codex resume` (TUI) accepts the same -s/--sandbox flags as a fresh run.
             cmd.push(...modeFlags);
+            if (codexWorkspaceWrite)
+                cmd.push('-c', codexWritableRootsConfig(getUserAgentsDir()));
         }
         else {
             // `codex exec resume` rejects `--sandbox <mode>` (verified against
@@ -676,6 +699,7 @@ export function buildExecCommand(options) {
             cmd.push('-c', `sandbox_mode=${resolvedMode === 'plan' ? 'read-only' : 'workspace-write'}`);
             if (resolvedMode !== 'plan') {
                 cmd.push('-c', 'sandbox_workspace_write.network_access=true');
+                cmd.push('-c', codexWritableRootsConfig(getUserAgentsDir()));
             }
         }
     }
@@ -779,9 +803,16 @@ export function buildExecCommand(options) {
     // claude-only, silently dropped for codex and masked by edit mode carrying
     // the approval/sandbox bypass. Codex's resume forms reject --add-dir, so
     // skip it there (claude's flag-based resume accepts it).
-    if (options.addDirs &&
+    //
+    // On top of any user-supplied dirs, a fresh codex workspace-write run
+    // implicitly gets ~/.agents (deduped) so the CLI's own tooling — askpass,
+    // secrets, sessions, tunings — can write from inside the sandbox. Resume forms
+    // get the same root via -c writable_roots above (see codexWorkspaceWrite).
+    const codexImplicitDirs = codexWorkspaceWrite && !options.resume ? [getUserAgentsDir()] : [];
+    const addDirs = [...new Set([...(options.addDirs ?? []), ...codexImplicitDirs])];
+    if (addDirs.length > 0 &&
         (options.agent === 'claude' || (options.agent === 'codex' && !options.resume))) {
-        for (const dir of options.addDirs) {
+        for (const dir of addDirs) {
             cmd.push('--add-dir', dir);
         }
     }

package/dist/lib/hooks.d.ts

@@ -21,12 +21,41 @@ export declare function resolveHookScriptPath(script: string): string | null;
  * os.homedir()/path.sep at the call site.
  */
 export declare function toPortableCommand(absPath: string, home?: string, sep?: string): string;
+/**
+ * Collapse version-scoped registrations by logical resource identity rather
+ * than absolute command path. When the same resource is present in several
+ * homes, the active home's command wins even if it appears later. Commands
+ * outside version homes are user-owned and remain untouched.
+ */
+export declare function deduplicateVersionHookCommands(commands: string[], activeVersionHome: string): string[];
 import type { AgentId, InstalledHook, ManifestHook } from './types.js';
 export type HookEntry = {
     name: string;
     scriptPath: string;
     dataFile?: string;
 };
+export interface VersionHookCopy {
+    agent: AgentId;
+    version: string;
+    name: string;
+    path: string;
+    hash: string;
+    active: boolean;
+}
+export interface DuplicateVersionHook {
+    agent: AgentId;
+    name: string;
+    kind: 'duplicate' | 'drift';
+    authoritative: VersionHookCopy;
+    copies: VersionHookCopy[];
+}
+/**
+ * Inspect every installed hooks-capable harness without assuming a native
+ * settings format. Same-name copies with one content hash are installation
+ * noise; multiple hashes are drift. The active version is always selected as
+ * the authoritative copy when it participates in the group.
+ */
+export declare function inspectDuplicateVersionHooks(cwd?: string): DuplicateVersionHook[];
 /**
  * List hook entries in a single directory, grouping script + data files by
  * basename. Exported so doctor-diff can reuse the same grouping the sync path

package/dist/lib/hooks.js

@@ -146,9 +146,113 @@ function isStaleSiblingVersionCommand(command, current) {
     const id = versionHomeIdentity(command);
     return id !== null && id.agent === current.agent && id.version !== current.version;
 }
-import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
+function hookResourceName(command) {
+    const withoutArgs = command.trim().split(/\s+/)[0];
+    return path.basename(withoutArgs).replace(/\.[^.]+$/, '');
+}
+/**
+ * Collapse version-scoped registrations by logical resource identity rather
+ * than absolute command path. When the same resource is present in several
+ * homes, the active home's command wins even if it appears later. Commands
+ * outside version homes are user-owned and remain untouched.
+ */
+export function deduplicateVersionHookCommands(commands, activeVersionHome) {
+    const active = versionHomeIdentity(activeVersionHome);
+    if (!active)
+        return [...commands];
+    const selected = new Map();
+    const passthrough = [];
+    for (const command of commands) {
+        const identity = versionHomeIdentity(command);
+        if (!identity || identity.agent !== active.agent) {
+            passthrough.push(command);
+            continue;
+        }
+        const key = `${identity.agent}\0${hookResourceName(command)}`;
+        const candidateIsActive = identity.version === active.version;
+        const prior = selected.get(key);
+        if (!prior || (!prior.active && candidateIsActive)) {
+            selected.set(key, { command, active: candidateIsActive });
+        }
+    }
+    return [...passthrough, ...Array.from(selected.values(), ({ command }) => command)];
+}
+/**
+ * Collapse a matcher group's hook entries down to the deduplicated command
+ * multiset {@link deduplicateVersionHookCommands} returns, preserving order and
+ * the concrete entry objects. The deduped list is honored as a per-command
+ * budget, NOT a membership set: two identical active-version entries collapse to
+ * one because the budget for that command is one. (A membership `Set.has` test
+ * would keep both — the bug this replaces.) Passthrough (user / non-version-home)
+ * commands keep their original multiplicity, so genuine user hooks are untouched.
+ */
+function collapseVersionHookEntries(entries, activeVersionHome) {
+    const budget = new Map();
+    for (const command of deduplicateVersionHookCommands(entries.map((e) => e.command), activeVersionHome)) {
+        budget.set(command, (budget.get(command) ?? 0) + 1);
+    }
+    return entries.filter((e) => {
+        const remaining = budget.get(e.command) ?? 0;
+        if (remaining <= 0)
+            return false;
+        budget.set(e.command, remaining - 1);
+        return true;
+    });
+}
+import { getEffectiveHome, getVersionHomePath, listInstalledVersions, resolveVersion } from './versions.js';
 import { generateHookShim, getHookShimPath, isValidHookShimName, parseCacheConfig, removeHookShim } from './hooks/cache.js';
 import { getHookShimsDir } from './state.js';
+function hookContentHash(scriptPath) {
+    return crypto.createHash('sha256').update(fs.readFileSync(scriptPath)).digest('hex');
+}
+/**
+ * Inspect every installed hooks-capable harness without assuming a native
+ * settings format. Same-name copies with one content hash are installation
+ * noise; multiple hashes are drift. The active version is always selected as
+ * the authoritative copy when it participates in the group.
+ */
+export function inspectDuplicateVersionHooks(cwd = process.cwd()) {
+    const byResource = new Map();
+    for (const { agent, version } of iterHooksCapableVersions()) {
+        const activeVersion = resolveVersion(agent, cwd);
+        for (const entry of listHooksInVersionHome(agent, version)) {
+            let hash;
+            try {
+                hash = hookContentHash(entry.scriptPath);
+            }
+            catch {
+                continue;
+            }
+            const copy = {
+                agent,
+                version,
+                name: entry.name,
+                path: entry.scriptPath,
+                hash,
+                active: version === activeVersion,
+            };
+            const key = `${agent}\0${entry.name}`;
+            const copies = byResource.get(key) ?? [];
+            copies.push(copy);
+            byResource.set(key, copies);
+        }
+    }
+    const findings = [];
+    for (const copies of byResource.values()) {
+        if (copies.length < 2)
+            continue;
+        copies.sort((a, b) => a.version.localeCompare(b.version, undefined, { numeric: true }));
+        const authoritative = copies.find((copy) => copy.active) ?? copies[copies.length - 1];
+        findings.push({
+            agent: authoritative.agent,
+            name: authoritative.name,
+            kind: new Set(copies.map((copy) => copy.hash)).size === 1 ? 'duplicate' : 'drift',
+            authoritative,
+            copies,
+        });
+    }
+    return findings.sort((a, b) => `${a.agent}/${a.name}`.localeCompare(`${b.agent}/${b.name}`));
+}
 /**
  * Resolve the command path to register for a hook.
  *
@@ -1351,8 +1455,9 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
         for (const group of eventEntries) {
             if (!group.hooks)
                 continue;
-            group.hooks = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
+            const managed = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
                 !isStaleSiblingVersionCommand(h.command, currentVh));
+            group.hooks = collapseVersionHookEntries(managed, versionHome);
         }
     }
     // Remove empty matcher groups left after cleanup
@@ -1509,8 +1614,9 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
         for (const group of eventGroups) {
             if (!group.hooks)
                 continue;
-            group.hooks = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
+            const managed = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
                 !isStaleSiblingVersionCommand(h.command, currentVh));
+            group.hooks = collapseVersionHookEntries(managed, versionHome);
         }
     }
     for (const [event, eventGroups] of Object.entries(hooksFile.hooks)) {

package/dist/lib/menubar/install-menubar.d.ts

@@ -124,6 +124,28 @@ export declare function disableMenubarService(): void;
  * Best-effort — never throws into startup.
  */
 export declare function installMenubarLaunchAgentOnUpgrade(): void;
+/** A live MenubarHelper process: its pid and the executable it is running. */
+export interface MenubarProcess {
+    pid: number;
+    executable: string;
+}
+/**
+ * Split the live MenubarHelper processes into the installed bundle's own
+ * (`running`) and every other copy (`foreign`).
+ *
+ * `pgrep -f MenubarHelper` conflated the two, so a stray dev build could hold
+ * the global Cmd-Shift-V chord (RegisterEventHotKey is first-come) while status
+ * still reported a healthy `running: yes` — the paste was dead and nothing said
+ * so. A foreign copy is the thing to look for, so name it.
+ *
+ * Identity comes from `comm` (the resolved executable), never from a substring
+ * of the command line: matching the latter flags any shell that merely mentions
+ * MenubarHelper. `command` is consulted only to drop `--notify` one-shots.
+ */
+export declare function classifyMenubarProcesses(commOutput: string, commandOutput: string, installedExec: string): {
+    running: boolean;
+    foreign: MenubarProcess[];
+};
 export interface MenubarStatus {
     platform: string;
     source: string | null;
@@ -133,6 +155,8 @@ export interface MenubarStatus {
     stale: boolean;
     serviceInstalled: boolean;
     running: boolean;
+    /** Live MenubarHelper processes that are NOT the installed bundle. */
+    foreignInstances: MenubarProcess[];
     disabledByUser: boolean;
 }
 export declare function getMenubarStatus(): MenubarStatus;

package/dist/lib/menubar/install-menubar.js

@@ -441,12 +441,61 @@ export function installMenubarLaunchAgentOnUpgrade() {
         /* never block startup on the menu bar */
     }
 }
+/** Parse `ps -axo pid=,<field>=` into pid -> field. The field is the rest of the
+ *  line, so a path containing spaces (App Support does) survives intact. */
+function parsePsLines(psOutput) {
+    const out = new Map();
+    for (const line of psOutput.split('\n')) {
+        const m = /^\s*(\d+)\s+(.+)$/.exec(line);
+        if (m)
+            out.set(Number(m[1]), m[2]);
+    }
+    return out;
+}
+/**
+ * Split the live MenubarHelper processes into the installed bundle's own
+ * (`running`) and every other copy (`foreign`).
+ *
+ * `pgrep -f MenubarHelper` conflated the two, so a stray dev build could hold
+ * the global Cmd-Shift-V chord (RegisterEventHotKey is first-come) while status
+ * still reported a healthy `running: yes` — the paste was dead and nothing said
+ * so. A foreign copy is the thing to look for, so name it.
+ *
+ * Identity comes from `comm` (the resolved executable), never from a substring
+ * of the command line: matching the latter flags any shell that merely mentions
+ * MenubarHelper. `command` is consulted only to drop `--notify` one-shots.
+ */
+export function classifyMenubarProcesses(commOutput, commandOutput, installedExec) {
+    const commands = parsePsLines(commandOutput);
+    const foreign = [];
+    let running = false;
+    for (const [pid, executable] of parsePsLines(commOutput)) {
+        if (path.basename(executable) !== 'MenubarHelper')
+            continue;
+        // `--notify` is a one-shot that posts a notification and exits; it runs the
+        // installed binary but never claims the status item or the chords.
+        if ((commands.get(pid) || '').includes('--notify'))
+            continue;
+        if (executable === installedExec)
+            running = true;
+        else
+            foreign.push({ pid, executable });
+    }
+    return { running, foreign };
+}
 export function getMenubarStatus() {
     const dest = installedAppPath();
     let running = false;
+    let foreignInstances = [];
     if (onDarwin()) {
-        const r = spawnSync('pgrep', ['-f', 'MenubarHelper'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
-        running = r.status === 0 && (r.stdout || '').trim().length > 0;
+        const ps = (format) => spawnSync('ps', ['-axo', format], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
+        const comm = ps('pid=,comm=');
+        const command = ps('pid=,command=');
+        if (comm.status === 0 && command.status === 0) {
+            const c = classifyMenubarProcesses(comm.stdout || '', command.stdout || '', installedExecutablePath());
+            running = c.running;
+            foreignInstances = c.foreign;
+        }
     }
     const serviceInstalled = menubarServiceInstalled();
     return {
@@ -458,6 +507,7 @@ export function getMenubarStatus() {
         stale: onDarwin() && serviceInstalled && menubarSetupStale(),
         serviceInstalled,
         running,
+        foreignInstances,
         disabledByUser: menubarDisabledByUser(),
     };
 }

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

@@ -347,6 +347,19 @@ export declare function validateJob(config: Partial<JobConfig>): string[];
 export declare function validateTrigger(trigger: unknown): string[];
 /** True when a job's endAt has already elapsed. False when endAt is unset or in the future. */
 export declare function isPastEndAt(config: Pick<JobConfig, 'endAt'>, now?: Date): boolean;
+export interface OneShotScheduleParts {
+    minute: number;
+    hour: number;
+    day: number;
+    month: number;
+}
+export declare function parseOneShotLikeSchedule(schedule: string | undefined | null): OneShotScheduleParts | null;
+export declare function isOneShotLikeSchedule(schedule: string | undefined | null): boolean;
+export declare function isOneShotRoutine(config: Pick<JobConfig, 'schedule' | 'runOnce'>): boolean;
+export declare function oneShotScheduleFireDate(schedule: string | undefined | null, now?: Date, timezone?: string): Date | null;
+export declare function isPastOneShotRoutine(config: Pick<JobConfig, 'schedule' | 'runOnce' | 'timezone'>, now?: Date): boolean;
+export declare function hasCompletedOneShotRun(config: Pick<JobConfig, 'name' | 'schedule' | 'runOnce' | 'timezone'>, now?: Date): boolean;
+export declare function shouldPurgeCompletedOneShotRoutine(config: Pick<JobConfig, 'name' | 'schedule' | 'runOnce' | 'timezone'>, now?: Date): boolean;
 /** Expand built-in and user-defined template variables in a job's prompt string. */
 export declare function resolveJobPrompt(config: JobConfig): string;
 /** Parse a human-readable timeout string (e.g. "10m", "2h", "1h30m", "3d", "1w") into milliseconds.