@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/run-notify.js

@@ -1,32 +1,10 @@
-/**
- * Desktop notification when a headless `agents run` finishes (`--notify`).
- *
- * The notifying process is the one that OWNS the run. That is the whole point:
- * the menu bar's quick dispatch used to post its completion notice from the
- * dispatching MenubarHelper's process-termination callback, so a helper that
- * restarted (an upgrade, a crash) took the callback with it — the run kept
- * going, reparented to launchd, and no notification could ever fire. Posting
- * from the run process instead means the notice survives anything that happens
- * to the menu bar, and `notifyDesktop` spawns a FRESH one-shot notifier, so it
- * does not need a helper to have been running at dispatch time either.
- *
- * Armed once via `process.on('exit')` so it covers every way the run command
- * terminates — local spawn, `--device` dispatch, `--lease` box, the error path —
- * rather than being sprinkled over ~50 `process.exit` call sites where the next
- * new exit path would silently miss it.
- */
 import * as path from 'path';
 import { notifyDesktop } from './menubar/notify-desktop.js';
-/** Notification body cap: a banner truncates anyway, and a wall of text is noise. */
 const BODY_MAX = 120;
 function shorten(text, max = BODY_MAX) {
     const flat = text.replace(/\s+/g, ' ').trim();
     return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
 }
-/**
- * The finish notification for one run. Pure — the exit handler and the tests
- * both build through here, so what ships is what is asserted.
- */
 export function buildRunFinishNotification(ctx, exitCode) {
     const label = ctx.name?.trim() || ctx.agent;
     const project = ctx.cwd ? path.basename(ctx.cwd) : undefined;
@@ -35,25 +13,17 @@ export function buildRunFinishNotification(ctx, exitCode) {
     const n = {
         title: ok ? `${label} finished` : `${label} failed`,
         body: shorten(ctx.prompt?.trim() || `${ctx.agent} run`),
-        // The harness that ran becomes the banner's right-hand avatar, so a finished
-        // run is identifiable at a glance even when `--name` renamed the title.
         agent: ctx.agent,
-        // Categorize so the companion can offer the run's follow-up buttons; a
-        // failed run gets the failure category, a clean one the done category.
         category: ok ? 'done' : 'failure',
     };
     if (where)
         n.subtitle = where;
     if (ctx.sessionId)
         n.sessionId = ctx.sessionId;
-    // The primary click target: a report opens the report file, else the PR url.
     if (ctx.reportPath)
         n.action = `open:${ctx.reportPath}`;
     else if (ctx.url)
         n.action = `url:${ctx.url}`;
-    // Follow-up buttons the companion renders: open the report when one exists,
-    // open the PR when a url is known. `open-report` reuses the `open:` action
-    // resolution; `open-pr` opens `ctx.url`.
     const choices = [];
     if (ctx.reportPath)
         choices.push({ id: 'open-report', label: 'Open report' });
@@ -63,12 +33,6 @@ export function buildRunFinishNotification(ctx, exitCode) {
         n.choices = choices;
     return n;
 }
-/**
- * Post the finish notification when this process exits. Best-effort by
- * construction: `notifyDesktop` swallows its own failures, and a run killed
- * outright (SIGKILL) never reaches an exit handler — that is the documented
- * limit, not a case to paper over.
- */
 export function armRunFinishNotification(ctx) {
     process.on('exit', (code) => {
         notifyDesktop(buildRunFinishNotification(ctx, code));

package/dist/lib/run-trace-sync.d.ts

@@ -1,28 +1,7 @@
-/**
- * The policy gate, pure and unit-testable. `disabled` is the resolved
- * `--no-trace-sync` (commander maps it to `traceSync === false`).
- */
 export declare function shouldAutoSyncTraces(disabled: boolean): boolean;
-/**
- * Arm a fire-and-forget `agents traces sync` for when this process exits.
- * No-op unless {@link shouldAutoSyncTraces} passes. Best-effort by
- * construction: a missing binary or a stalled child never affects the run.
- * The spawn happens in the exit handler because the upload is async work Node
- * cannot run after `exit` — a watchdog here could never fire.
- */
 export declare function armRunFinishTraceSync(opts?: {
     disabled?: boolean;
 }): void;
-/**
- * Fire a fire-and-forget `agents traces sync` NOW (not on exit). An important
- * owner-bound ping (`feed post --level important`, `agents send --to owner`,
- * `send --to owner`) links the caller's `…/console/sessions/<id>` page, and that
- * page only exists once the session's shard has been uploaded — trace sync fires
- * on run exit (PHNX-3628), not when a mid-run ping is posted. This closes that
- * gap so the tapped link resolves instead of 404ing. No-op unless
- * {@link shouldAutoSyncTraces} passes (signed in + already opted into the store);
- * the incremental watermark keeps the push to essentially just this session.
- */
 export declare function fireTraceSyncInBackground(opts?: {
     disabled?: boolean;
 }): void;

package/dist/lib/run-trace-sync.js

@@ -1,97 +1,33 @@
-/**
- * Auto-sync this device's just-finished session trace when a local, headless
- * `agents run` exits (PHNX-3628).
- *
- * Why exit-armed + spawn, exactly like `run-notify`: the sync reads this
- * device's `sessions.db` and PUTs redacted shards over the network — async work
- * that CANNOT run inside a `process.on('exit')` handler (Node runs no more
- * microtasks after exit). So, mirroring `notifyDesktop`, on exit we SPAWN a
- * detached `agents traces sync` and unref it; it finishes after the parent is
- * gone, and the run itself returns immediately instead of waiting on the PUTs.
- *
- * The upload is incremental by construction (`syncTraces` de-dups by the
- * `traces-sync.json` mtime watermark), so the spawned sync pushes essentially
- * just the session that finished, not the whole history.
- *
- * Default policy: fire ONLY when the user has ALREADY opted into the traces
- * store — i.e. they are signed in AND have run `agents traces sync` at least
- * once (`hasSyncedBefore`). A user who never synced is never touched. Opt out
- * of a given run with `--no-trace-sync` or `AGENTS_NO_TRACE_SYNC=1`.
- *
- * Local runs only: a run placed on another machine (`--device`/`--on`/
- * `--computer`/`--where device:`, `--lease`, `--box`, or `--cloud`) has its
- * trajectory on the REMOTE box, not this device's `sessions.db`, so arming here
- * would upload nothing useful — the remote box runs its own exit sync. The
- * caller gates every remote-placement signal out before arming (it reuses the
- * file's own `hostTargetGiven` predicate plus `--lease`/`--box`; `--cloud`
- * returns earlier).
- */
 import { spawn } from 'child_process';
 import { getCliLaunch } from './cli-entry.js';
 import { readSession } from './identity/client.js';
 import { hasSyncedBefore } from './traces/sync.js';
-/**
- * The policy gate, pure and unit-testable. `disabled` is the resolved
- * `--no-trace-sync` (commander maps it to `traceSync === false`).
- */
 export function shouldAutoSyncTraces(disabled) {
     if (disabled)
         return false;
     if (process.env.AGENTS_NO_TRACE_SYNC === '1')
         return false;
     if (!readSession())
-        return false; // not signed in → nothing to authenticate an upload
+        return false;
     if (!hasSyncedBefore())
-        return false; // never opted into the traces store
+        return false;
     return true;
 }
-/**
- * Spawn a detached, unref'd `agents traces sync` and return immediately. The one
- * place the fire-and-forget child is built, shared by the run-exit arm and the
- * feed/notify important-post trigger.
- *
- * Re-invoke this CLI through getCliLaunch, NOT a hand-rolled
- * [process.execPath, process.argv[1], …] — under the compiled standalone binary
- * argv[1] is the bun virtual entry (/$bunfs/root/agents), which would become a
- * bogus subcommand and silently no-op the whole feature (cli-entry.ts). The
- * spawned `traces sync` is a fresh process with its own event loop, so its own
- * per-request network timeouts (syncTraces) bound it.
- */
 function spawnDetachedTraceSync() {
     try {
         const { command, args } = getCliLaunch(['traces', 'sync']);
         const child = spawn(command, args, { detached: true, stdio: 'ignore' });
-        // A child that never starts (ENOENT) emits an async 'error'; without a
-        // listener Node re-throws it as uncaught. Swallow — this is best-effort.
         child.on('error', () => { });
         child.unref();
     }
     catch {
-        // A synchronous spawn failure must never change the caller's outcome.
     }
 }
-/**
- * Arm a fire-and-forget `agents traces sync` for when this process exits.
- * No-op unless {@link shouldAutoSyncTraces} passes. Best-effort by
- * construction: a missing binary or a stalled child never affects the run.
- * The spawn happens in the exit handler because the upload is async work Node
- * cannot run after `exit` — a watchdog here could never fire.
- */
 export function armRunFinishTraceSync(opts = {}) {
     if (!shouldAutoSyncTraces(!!opts.disabled))
         return;
     process.on('exit', spawnDetachedTraceSync);
 }
-/**
- * Fire a fire-and-forget `agents traces sync` NOW (not on exit). An important
- * owner-bound ping (`feed post --level important`, `agents send --to owner`,
- * `send --to owner`) links the caller's `…/console/sessions/<id>` page, and that
- * page only exists once the session's shard has been uploaded — trace sync fires
- * on run exit (PHNX-3628), not when a mid-run ping is posted. This closes that
- * gap so the tapped link resolves instead of 404ing. No-op unless
- * {@link shouldAutoSyncTraces} passes (signed in + already opted into the store);
- * the incremental watermark keeps the push to essentially just this session.
- */
 export function fireTraceSyncInBackground(opts = {}) {
     if (!shouldAutoSyncTraces(!!opts.disabled))
         return;

package/dist/lib/rush-session.d.ts

@@ -1,27 +1 @@
-/**
- * Rush session freshness — the ONE judgment shared by every consumer of
- * ~/.rush/user.yaml (cloud dispatch, cloud session source, secrets sync driver).
- *
- * A Rush session stores `expires_at` as Unix MILLISECONDS — the same unit
- * rush/cli writes and reads it in (`sessionTokenFresh` in auth_reader.go compares
- * against `time.Now()...UnixMilli()`), and the same unit the JWT `exp` claim maps
- * to (`exp * 1000`). So freshness must compare it against `Date.now()` (ms), NOT
- * `Date.now() / 1000` (seconds). Comparing ms against seconds was PHNX-3805: a
- * long-expired session (e.g. `expires_at: 1788157222000`) read as `1.788e12 <=
- * 1.788e9` → always false → never expired, so `agents cloud providers` reported
- * Rush `available: true` on a dead session and every dispatch failed with a 401.
- *
- * Two values mean "never expires" and MUST NOT be read as an absolute timestamp:
- *   - `0`         — an opaque Phoenix `pid_` bearer written by `rush login`;
- *                   `0` = non-expiring by contract (mirrors rush/cli's isFresh,
- *                   the same fix RUSH-1310 landed for the daemon-less freshness
- *                   check and PHNX-3637 landed for the release endpoints).
- *   - `undefined` — a token written without an expiry.
- *
- * Reading `expires_at: 0` as epoch-1970 was PHNX-3645: every Phoenix-authed box
- * had its valid, non-expiring session rejected as "Rush session expired at
- * 1970-01-01", so `agents run --cloud`, `agents secrets push/pull` over Rush,
- * and cloud session discovery all refused to run. Every consumer that parses
- * freshness routes through this predicate so the special-case lives in one place.
- */
 export declare function isRushSessionExpired(expiresAt: number | undefined): boolean;

package/dist/lib/rush-session.js

@@ -1,33 +1,5 @@
-/**
- * Rush session freshness — the ONE judgment shared by every consumer of
- * ~/.rush/user.yaml (cloud dispatch, cloud session source, secrets sync driver).
- *
- * A Rush session stores `expires_at` as Unix MILLISECONDS — the same unit
- * rush/cli writes and reads it in (`sessionTokenFresh` in auth_reader.go compares
- * against `time.Now()...UnixMilli()`), and the same unit the JWT `exp` claim maps
- * to (`exp * 1000`). So freshness must compare it against `Date.now()` (ms), NOT
- * `Date.now() / 1000` (seconds). Comparing ms against seconds was PHNX-3805: a
- * long-expired session (e.g. `expires_at: 1788157222000`) read as `1.788e12 <=
- * 1.788e9` → always false → never expired, so `agents cloud providers` reported
- * Rush `available: true` on a dead session and every dispatch failed with a 401.
- *
- * Two values mean "never expires" and MUST NOT be read as an absolute timestamp:
- *   - `0`         — an opaque Phoenix `pid_` bearer written by `rush login`;
- *                   `0` = non-expiring by contract (mirrors rush/cli's isFresh,
- *                   the same fix RUSH-1310 landed for the daemon-less freshness
- *                   check and PHNX-3637 landed for the release endpoints).
- *   - `undefined` — a token written without an expiry.
- *
- * Reading `expires_at: 0` as epoch-1970 was PHNX-3645: every Phoenix-authed box
- * had its valid, non-expiring session rejected as "Rush session expired at
- * 1970-01-01", so `agents run --cloud`, `agents secrets push/pull` over Rush,
- * and cloud session discovery all refused to run. Every consumer that parses
- * freshness routes through this predicate so the special-case lives in one place.
- */
 export function isRushSessionExpired(expiresAt) {
-    // `0` (non-expiring pid_ bearer) and a missing value are never expired.
     if (typeof expiresAt !== 'number' || expiresAt === 0)
         return false;
-    // expires_at is Unix milliseconds — compare ms to ms.
     return expiresAt <= Date.now();
 }

package/dist/lib/sandbox.d.ts

@@ -1,60 +1,15 @@
-/**
- * Sandbox environment for routine job execution.
- *
- * Creates an overlay HOME directory per job with symlinked allowed
- * directories and agent-specific config files (permissions, settings).
- * The spawned agent process sees only the overlay, limiting filesystem
- * access to explicitly allowed paths.
- */
 import type { JobConfig } from './scheduling/routines.js';
 import type { AgentId } from './types.js';
-/**
- * Absolute path to this host's `gh` config directory (`hosts.yml` + `config.yml`),
- * or null when the host has never run `gh auth login`. Prefer `GH_CONFIG_DIR` when
- * the parent already pinned one; otherwise `$XDG_CONFIG_HOME/gh` or `~/.config/gh`.
- */
 export declare function resolveHostGhConfigDir(): string | null;
-/** True when this host holds usable GitHub CLI auth (hosts.yml or a token env). */
 export declare function hostHasGhAuth(): boolean;
-/** Build a restricted environment for a sandboxed process, setting HOME to the overlay. */
 export declare function buildSpawnEnv(overlayHome: string, extraEnv?: Record<string, string>): Record<string, string>;
-/**
- * Get the overlay HOME directory path for a named job.
- *
- * The job name originates from routine YAML (`name:` field or file basename),
- * which can arrive from a synced user/system config repo. `safeJoin` contains
- * it to a single segment beneath the routines dir so a crafted name such as
- * `../../../..` cannot steer `prepareJobHome`/`cleanJobHome` (which does a
- * recursive `rmSync`) at a path outside `~/.agents/routines`.
- */
 export declare function getJobHomePath(name: string): string;
-/** Create a fresh overlay HOME for a job, including agent config and allowed-dir symlinks. */
 export declare function prepareJobHome(config: JobConfig, version?: string): string;
-/** Link only the selected harness login into the disposable routine HOME. */
 export declare function linkVersionAuth(overlayHome: string, agent: AgentId, version?: string): void;
-/**
- * Link this host's `gh` config directory into the disposable overlay so
- * `$HOME/.config/gh` resolves even when `GH_CONFIG_DIR` is unset. Mirrors
- * `generateCursorConfig`: same-host credentials, never copied to another box.
- */
 export declare function linkHostGhConfig(overlayHome: string): void;
-/**
- * Refuse to launch a sandboxed child when THIS host holds GitHub auth but the
- * spawn env would hide it. The RUSH-2860 failure mode was silent: the monitor
- * fire recorded `ok` (spawn succeeded) while every `gh` call inside the child
- * failed. Prefer forwarding (buildSpawnEnv / linkHostGhConfig); this assert is
- * the regression tripwire — if forwarding ever regresses, fail loud at spawn
- * instead of recording a hollow success. No-ops when the host has no gh auth
- * (jobs that do not need GitHub still run).
- */
 export declare function assertSandboxForwardsHostGhAuth(spawnEnv: Record<string, string>): void;
-/** Link this host's Cursor login and CLI config into the disposable overlay. */
 export declare function generateCursorConfig(overlayHome: string): void;
-/** Remove a job's overlay HOME directory entirely. */
 export declare function cleanJobHome(name: string): void;
-/** Symlink allowed directories into the overlay HOME, skipping paths outside the real HOME. */
 export declare function symlinkAllowedDirs(overlayHome: string, dirs: string[]): void;
-/** Generate a Claude settings.json in the overlay with scoped permissions from the job config. */
 export declare function generateClaudeConfig(overlayHome: string, config: JobConfig): void;
-/** Generate a Codex config.toml in the overlay with model and approval-mode settings. */
 export declare function generateCodexConfig(overlayHome: string, config: JobConfig): void;

package/dist/lib/sandbox.js

@@ -1,11 +1,3 @@
-/**
- * Sandbox environment for routine job execution.
- *
- * Creates an overlay HOME directory per job with symlinked allowed
- * directories and agent-specific config files (permissions, settings).
- * The spawned agent process sees only the overlay, limiting filesystem
- * access to explicitly allowed paths.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -22,7 +14,6 @@ function resolveRealHome() {
         return home;
     }
 }
-/** Environment variables forwarded from the parent process into the sandbox. */
 const ENV_ALLOWLIST = [
     'PATH',
     'SHELL',
@@ -44,21 +35,16 @@ const ENV_ALLOWLIST = [
     'VISUAL',
     'NO_COLOR',
     'FORCE_COLOR',
-    // GitHub CLI — same host credentials interactive `agents run` already sees.
-    // Without these, a sandboxed monitor `--run` child has no gh auth even when
-    // the daemon user is logged in (RUSH-2860).
     'GH_TOKEN',
     'GH_HOST',
     'GH_ENTERPRISE_TOKEN',
     'GITHUB_TOKEN',
     'GH_CONFIG_DIR',
 ];
-/** Tools safe to grant as wildcards (no filesystem access). */
 const SAFE_TOOLS = {
     web_search: 'WebSearch(*)',
     web_fetch: 'WebFetch(*)',
 };
-/** Bare tool names that get scoped to allow.dirs, never wildcarded. */
 const DIR_SCOPED_TOOLS = new Set(['read', 'write', 'edit', 'glob', 'grep', 'notebook_edit']);
 function tomlString(value) {
     if (/[\r\n]/.test(value)) {
@@ -66,15 +52,7 @@ function tomlString(value) {
     }
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
-/**
- * Absolute path to this host's `gh` config directory (`hosts.yml` + `config.yml`),
- * or null when the host has never run `gh auth login`. Prefer `GH_CONFIG_DIR` when
- * the parent already pinned one; otherwise `$XDG_CONFIG_HOME/gh` or `~/.config/gh`.
- */
 export function resolveHostGhConfigDir() {
-    // Honor an explicit pin only when it actually exists; otherwise fall through
-    // to the default locations so a stale/broken GH_CONFIG_DIR cannot hide a
-    // healthy ~/.config/gh (RUSH-2860).
     if (process.env.GH_CONFIG_DIR && fs.existsSync(process.env.GH_CONFIG_DIR)) {
         return process.env.GH_CONFIG_DIR;
     }
@@ -82,7 +60,6 @@ export function resolveHostGhConfigDir() {
     const ghDir = path.join(configHome, 'gh');
     return fs.existsSync(ghDir) ? ghDir : null;
 }
-/** True when this host holds usable GitHub CLI auth (hosts.yml or a token env). */
 export function hostHasGhAuth() {
     if (process.env.GH_TOKEN || process.env.GH_ENTERPRISE_TOKEN || process.env.GITHUB_TOKEN) {
         return true;
@@ -92,7 +69,6 @@ export function hostHasGhAuth() {
         return false;
     return fs.existsSync(path.join(dir, 'hosts.yml'));
 }
-/** Build a restricted environment for a sandboxed process, setting HOME to the overlay. */
 export function buildSpawnEnv(overlayHome, extraEnv) {
     const env = {
         HOME: overlayHome,
@@ -103,11 +79,6 @@ export function buildSpawnEnv(overlayHome, extraEnv) {
             env[key] = process.env[key];
         }
     }
-    // Pin GH_CONFIG_DIR at the REAL host config so `gh` does not look under the
-    // disposable overlay HOME (which has no hosts.yml). Same posture as linking
-    // Cursor's auth.json — forward the credentials the daemon user already holds
-    // (RUSH-2860). Always prefer resolveHostGhConfigDir over a stale allowlisted
-    // value; an explicit extraEnv GH_CONFIG_DIR still wins below.
     const hostGh = resolveHostGhConfigDir();
     if (hostGh) {
         env.GH_CONFIG_DIR = hostGh;
@@ -120,19 +91,9 @@ export function buildSpawnEnv(overlayHome, extraEnv) {
     }
     return env;
 }
-/**
- * Get the overlay HOME directory path for a named job.
- *
- * The job name originates from routine YAML (`name:` field or file basename),
- * which can arrive from a synced user/system config repo. `safeJoin` contains
- * it to a single segment beneath the routines dir so a crafted name such as
- * `../../../..` cannot steer `prepareJobHome`/`cleanJobHome` (which does a
- * recursive `rmSync`) at a path outside `~/.agents/routines`.
- */
 export function getJobHomePath(name) {
     return path.join(safeJoin(getRoutinesDir(), name), 'home');
 }
-/** Create a fresh overlay HOME for a job, including agent config and allowed-dir symlinks. */
 export function prepareJobHome(config, version) {
     const overlayHome = getJobHomePath(config.name);
     cleanJobHome(config.name);
@@ -147,25 +108,12 @@ export function prepareJobHome(config, version) {
     else if (config.agent === 'cursor') {
         generateCursorConfig(overlayHome);
     }
-    // Host tool credentials / setup the overlay HOME would otherwise hide.
-    // Cursor already links its own auth above; gh is harness-agnostic and needed
-    // by every sandboxed `--run` that shells out to `gh` (RUSH-2860 — monitor
-    // merge agents saw "not logged into any GitHub hosts" while the daemon user
-    // was fine).
-    //
-    // Deliberately NOT linking the real ~/.agents here. It would put the secrets
-    // master key (.secrets-key) and the encrypted store (.cache/secrets) together
-    // at a predictable path inside the overlay, through a writable symlink, in a
-    // child whose prompt can carry untrusted text from a watched source. The
-    // separate "agents-cli is not set up" defect (state.ts ignores AGENTS_USER_DIR)
-    // gets its own scoped change: RUSH-2954.
     linkHostGhConfig(overlayHome);
     if (config.allow?.dirs) {
         symlinkAllowedDirs(overlayHome, config.allow.dirs);
     }
     return overlayHome;
 }
-/** Link only the selected harness login into the disposable routine HOME. */
 export function linkVersionAuth(overlayHome, agent, version) {
     if (!version)
         return;
@@ -185,18 +133,13 @@ export function linkVersionAuth(overlayHome, agent, version) {
         try {
             fs.rmSync(target, { force: true });
         }
-        catch { /* absent */ }
+        catch { }
         try {
             createLink(source, target);
         }
-        catch { /* the harness fails auth loudly if linking is unavailable */ }
+        catch { }
     }
 }
-/**
- * Link this host's `gh` config directory into the disposable overlay so
- * `$HOME/.config/gh` resolves even when `GH_CONFIG_DIR` is unset. Mirrors
- * `generateCursorConfig`: same-host credentials, never copied to another box.
- */
 export function linkHostGhConfig(overlayHome) {
     const realGhDir = resolveHostGhConfigDir();
     if (!realGhDir || !fs.existsSync(realGhDir))
@@ -209,18 +152,8 @@ export function linkHostGhConfig(overlayHome) {
         createLink(realGhDir, overlayGhDir);
     }
     catch {
-        /* cross-volume or link creation refused: GH_CONFIG_DIR in buildSpawnEnv is the backup */
     }
 }
-/**
- * Refuse to launch a sandboxed child when THIS host holds GitHub auth but the
- * spawn env would hide it. The RUSH-2860 failure mode was silent: the monitor
- * fire recorded `ok` (spawn succeeded) while every `gh` call inside the child
- * failed. Prefer forwarding (buildSpawnEnv / linkHostGhConfig); this assert is
- * the regression tripwire — if forwarding ever regresses, fail loud at spawn
- * instead of recording a hollow success. No-ops when the host has no gh auth
- * (jobs that do not need GitHub still run).
- */
 export function assertSandboxForwardsHostGhAuth(spawnEnv) {
     if (!hostHasGhAuth())
         return;
@@ -234,7 +167,6 @@ export function assertSandboxForwardsHostGhAuth(spawnEnv) {
         '(no GH_CONFIG_DIR / ~/.config/gh / GH_TOKEN). Refusing to launch — ' +
         'the agent would record ok then fail every gh call (RUSH-2860).');
 }
-/** Link this host's Cursor login and CLI config into the disposable overlay. */
 export function generateCursorConfig(overlayHome) {
     const realCursorDir = path.join(process.env.AGENTS_REAL_HOME || resolveRealHome(), '.cursor');
     const realAuth = path.join(realCursorDir, 'auth.json');
@@ -244,18 +176,14 @@ export function generateCursorConfig(overlayHome) {
     fs.mkdirSync(overlayCursorDir, { recursive: true });
     const overlayAuth = path.join(overlayCursorDir, 'auth.json');
     if (process.platform === 'win32') {
-        // File symlinks need Developer Mode on Windows. A same-volume hard link
-        // shares the credential inode without copying its contents to another host.
         try {
             fs.linkSync(realAuth, overlayAuth);
         }
-        catch { /* cross-volume or link creation refused: Cursor will fail auth loudly */ }
+        catch { }
     }
     else {
         fs.symlinkSync(realAuth, overlayAuth);
     }
-    // cli-config.json carries account identity alongside the file-store token, so
-    // it must remain linked rather than copied.
     const realCliConfig = path.join(realCursorDir, 'cli-config.json');
     if (fs.existsSync(realCliConfig)) {
         const overlayCliConfig = path.join(overlayCursorDir, 'cli-config.json');
@@ -265,29 +193,24 @@ export function generateCursorConfig(overlayHome) {
             else
                 fs.symlinkSync(realCliConfig, overlayCliConfig);
         }
-        catch { /* cross-volume or link creation refused: Cursor will fail auth loudly */ }
+        catch { }
     }
 }
-/** Remove a job's overlay HOME directory entirely. */
 export function cleanJobHome(name) {
     const overlayHome = getJobHomePath(name);
     if (fs.existsSync(overlayHome)) {
         fs.rmSync(overlayHome, { recursive: true, force: true });
     }
 }
-/** Symlink allowed directories into the overlay HOME, skipping paths outside the real HOME. */
 export function symlinkAllowedDirs(overlayHome, dirs) {
     const realHome = resolveRealHome();
     for (const dir of dirs) {
         const expanded = dir.replace(/^~/, realHome);
-        // Resolve .. and symlinks to prevent path traversal outside HOME
         let realPath;
         try {
-            // Use realpath if the directory exists (resolves symlinks)
             realPath = fs.realpathSync(expanded);
         }
         catch {
-            // Directory doesn't exist yet — resolve .. components without following symlinks
             realPath = path.resolve(expanded);
         }
         if (!realPath.startsWith(realHome + path.sep) && realPath !== realHome) {
@@ -299,15 +222,12 @@ export function symlinkAllowedDirs(overlayHome, dirs) {
         fs.mkdirSync(parentDir, { recursive: true });
         if (!fs.existsSync(symlinkTarget)) {
             try {
-                // createLink uses a junction for directories on Windows (no elevation),
-                // a plain symlink on POSIX — allowed dirs are directories.
                 createLink(realPath, symlinkTarget);
             }
-            catch { /* link already exists or refused */ }
+            catch { }
         }
     }
 }
-/** Generate a Claude settings.json in the overlay with scoped permissions from the job config. */
 export function generateClaudeConfig(overlayHome, config) {
     const realHome = resolveRealHome();
     const claudeDir = path.join(overlayHome, '.claude');
@@ -316,32 +236,25 @@ export function generateClaudeConfig(overlayHome, config) {
     const enabledTools = new Set(config.allow?.tools || []);
     if (config.allow?.tools) {
         for (const tool of config.allow.tools) {
-            // Safe wildcards (no filesystem access)
             if (tool in SAFE_TOOLS) {
                 allowPermissions.push(SAFE_TOOLS[tool]);
                 continue;
             }
-            // Bare filesystem tool names — permissions come from allow.dirs
             if (DIR_SCOPED_TOOLS.has(tool)) {
                 continue;
             }
-            // Bare "bash" — must use scoped pattern like "Bash(git *)"
             if (tool === 'bash') {
                 throw new Error('Bare "bash" not allowed in sandbox — use scoped patterns like "Bash(git *)"');
             }
-            // Reject wildcard patterns like Bash(*), Read(*)
             if (/^\w+\(\*\)$/.test(tool)) {
                 throw new Error(`Wildcard "${tool}" not allowed in sandbox — use scoped patterns`);
             }
-            // Scoped pattern like "Bash(git *)" — pass through
             allowPermissions.push(tool);
         }
     }
-    // Scope filesystem tools to allowed dirs
     if (config.allow?.dirs) {
         for (const dir of config.allow.dirs) {
             const resolved = dir.replace(/^~/, realHome);
-            // Read always granted for allowed dirs
             allowPermissions.push(`Read(${resolved}/**)`);
             if (config.mode === 'edit') {
                 allowPermissions.push(`Write(${resolved}/**)`);
@@ -366,7 +279,6 @@ export function generateClaudeConfig(overlayHome, config) {
     };
     fs.writeFileSync(path.join(claudeDir, 'settings.json'), JSON.stringify(settings, null, 2), 'utf-8');
 }
-/** Generate a Codex config.toml in the overlay with model and approval-mode settings. */
 export function generateCodexConfig(overlayHome, config) {
     const codexDir = path.join(overlayHome, '.codex');
     fs.mkdirSync(codexDir, { recursive: true });

package/dist/lib/scheduler.d.ts

@@ -1,37 +1,9 @@
-/**
- * Cron-based job scheduler for routines.
- *
- * Wraps the croner library to manage scheduled jobs in-memory. The daemon
- * process creates a single JobScheduler instance that loads enabled jobs
- * on startup and reloads them on SIGHUP.
- */
 import { Cron } from 'croner';
 import type { JobConfig } from './scheduling/routines.js';
-/** How a fire was triggered, carrying the scheduler's intended UTC slot time. */
 interface TriggerContext {
-    /** The ALIGNED cron slot this callback fires for, for the single-fire claim
-     *  keyed on (routine, scheduledFor). Derived by {@link fireSlot} — NOT croner's
-     *  raw `currentRun()`, which carries wall-clock jitter. */
     scheduledFor?: Date;
 }
-/**
- * The aligned occurrence boundary a fire callback belongs to — the value the
- * single-fire `(routine, scheduledFor)` claim keys on.
- *
- * croner's `currentRun()` inside a fire callback is the JITTERED wall-clock
- * trigger instant (it carries milliseconds — verified against croner 10.x), not
- * the aligned schedule boundary. Keying `slotRunId` on it directly minted a
- * distinct run id per delivery, so two callbacks for one occurrence each claimed
- * a different run dir and both launched, and a live fire never collided with its
- * catch-up twin (`missedRunId`, which keys on the aligned boundary). Flooring the
- * fire to its schedule boundary via {@link alignedSlotForFire} makes the claim a
- * structural claim on the occurrence identity (SING-15). Always returns a
- * concrete Date — `currentRun()` falls back to now, and an unresolvable boundary
- * falls back to the fire instant — so the forward path never dispatches without a
- * durable slot key.
- */
 export declare function fireSlot(cron: Cron): Date;
-/** In-memory cron scheduler that triggers a callback when jobs fire. */
 export declare class JobScheduler {
     private jobs;
     private onTrigger;