@phnx-labs/agents-cli 1.22.42 → 1.22.43

package/dist/lib/installations/versions.js

@@ -32,9 +32,9 @@ import { VERSION_RE, compareVersions } from '../agent-spec/primitives.js';
 import { AGENTS, agentConfigDirName, getAccountEmail, resolveAgentName, formatAgentError, findInPath, isSelfUpdatingAgent, isAgentHardDeprecated, hardDeprecationError } from '../agents.js';
 import { discoverPermissionGroups, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from '../permissions.js';
 import { parseMcpConfigForScan, isProjectMcpTrusted } from '../mcp.js';
-import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink, assertIsolationBoundary, } from './shims.js';
+import { createVersionedAlias, removeVersionedAlias, switchConfigSymlink, getConfigSymlinkVersion, ensureClaudeInsideSymlink, assertIsolationBoundary, isIsolationProtected, } from './shims.js';
 import { importInstallScriptBinary } from '../import.js';
-import { createInstallation, getBinaryPath, getCliVersionFromPath, getGlobalDefault, getIsolatedDefault, getLiveVersion, getVersionDir, getVersionHomePath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, isGlobalBinaryAgent, isVersionInstalled, isVersionIsolated, listInstalledVersions, pickCanonicalGlobalBinaryVersion, } from './store.js';
+import { createInstallation, getBinaryPath, getCliVersionFromPath, getGlobalDefault, getIsolatedDefault, getLiveVersion, getVersionDir, getVersionHomePath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, isGlobalBinaryAgent, isVersionInstalled, isVersionIsolated, listInstalledVersions, pickCanonicalGlobalBinaryVersion, resolveVersion, } from './store.js';
 export * from './store.js';
 import { INSTALLATION_RECORD_FILE } from './types.js';
 import { composeWin32CommandLine } from '../platform/index.js';
@@ -1745,6 +1745,61 @@ export function removeAllVersions(agent) {
     }
     return removed;
 }
+/**
+ * Repoint an agent's version pointers — the global/isolated default and the
+ * `~/.<agent>` config symlink — off any version that is no longer installed, so
+ * neither `agents sync`/`agents run` resolution nor the conventional-path home
+ * can land on a dead version (RUSH-2471).
+ *
+ * How a pointer goes dangling: {@link removeVersion} reassigns the defaults and
+ * clears the config symlink only when IT removes the pointed-at version. A
+ * version-home whose launch binary disappears by any other route — grok
+ * self-updated its per-version binary out from under the old dir, a manual
+ * delete, a half-finished install that seeded the home but never landed the
+ * binary — leaves the default and/or the symlink pointing at something
+ * {@link isVersionInstalled} reports as gone.
+ *
+ * Called from the sync resolve path so the invariant self-heals. Mirrors
+ * {@link removeVersion}'s reassignment: the global default prefers the newest
+ * NON-isolated survivor else clears; the isolated default prefers the newest
+ * remaining isolated copy else clears. The symlink is repointed at the now-healed
+ * resolved default, else the newest installed non-isolated version. A symlink
+ * already on an installed version, a real (non-symlink) config dir, and an
+ * isolated-only agent are left untouched.
+ */
+export async function healDanglingVersionPointers(agent, cwd) {
+    const healed = {};
+    const installed = listInstalledVersions(agent);
+    const globalDefault = getGlobalDefault(agent);
+    if (globalDefault !== null && !isVersionInstalled(agent, globalDefault)) {
+        const promotable = installed.filter((v) => !isVersionIsolated(agent, v));
+        const to = promotable.length > 0 ? promotable[promotable.length - 1] : undefined;
+        setGlobalDefault(agent, to);
+        healed.globalDefault = { from: globalDefault, to: to ?? null };
+    }
+    const isolatedDefault = getIsolatedDefault(agent);
+    if (isolatedDefault !== null && !isVersionInstalled(agent, isolatedDefault)) {
+        const survivors = installed.filter((v) => isVersionIsolated(agent, v));
+        const to = survivors.length > 0 ? survivors[survivors.length - 1] : undefined;
+        setIsolatedDefault(agent, to);
+        healed.isolatedDefault = { from: isolatedDefault, to: to ?? null };
+    }
+    const current = getConfigSymlinkVersion(agent);
+    const nonIsolated = installed.filter((v) => !isVersionIsolated(agent, v));
+    if (current !== null &&
+        !isVersionInstalled(agent, current) &&
+        !isIsolationProtected(agent) &&
+        nonIsolated.length > 0) {
+        const pinned = resolveVersion(agent, cwd);
+        const target = pinned && isVersionInstalled(agent, pinned) && !isVersionIsolated(agent, pinned)
+            ? pinned
+            : nonIsolated[nonIsolated.length - 1];
+        const result = await switchConfigSymlink(agent, target);
+        if (result.success)
+            healed.configSymlink = { from: current, to: target };
+    }
+    return healed;
+}
 /**
  * Normalize a user-supplied @version token across CLI subcommands.
  *

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

@@ -24,7 +24,7 @@ import { getRuntimeStateDir, getHelpersDir } from '../state.js';
 import { getCliVersion, resolveAgentsBin, resolveInstalledLayout } from '../version.js';
 import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
 import { compareVersions } from '../agent-spec/primitives.js';
-import { namespacedServiceLabel, serviceManifestHomeEnv } from '../service-manifest.js';
+import { namespacedServiceLabel, serviceManifestHomeEnv, serviceManagerRegistrationAllowed } from '../service-manifest.js';
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 const SERVICE_LABEL_BASE = 'com.phnx-labs.agents-menubar';
@@ -333,6 +333,11 @@ ${envXml}
  * is the only sequence that reliably re-attaches the status item.
  */
 export function restartMenubarLaunchAgent(uid, plist, exec = execFileSync) {
+    const reg = serviceManagerRegistrationAllowed();
+    if (!reg.allowed) {
+        process.stderr.write(`[agents] ${reg.reason}\n`);
+        return;
+    }
     const serviceTarget = `gui/${uid}/${serviceLabel()}`;
     const opts = { stdio: ['ignore', 'ignore', 'ignore'] };
     try {
@@ -467,15 +472,21 @@ export function disableMenubarService() {
     if (!onDarwin())
         return;
     const plist = servicePlistPath();
-    const uid = process.getuid?.() ?? 0;
-    try {
-        execFileSync('launchctl', ['bootout', `gui/${uid}/${serviceLabel()}`], { stdio: ['ignore', 'ignore', 'ignore'] });
-    }
-    catch {
+    const reg = serviceManagerRegistrationAllowed();
+    if (reg.allowed) {
+        const uid = process.getuid?.() ?? 0;
         try {
-            execFileSync('launchctl', ['unload', '-w', plist], { stdio: ['ignore', 'ignore', 'ignore'] });
+            execFileSync('launchctl', ['bootout', `gui/${uid}/${serviceLabel()}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+        }
+        catch {
+            try {
+                execFileSync('launchctl', ['unload', '-w', plist], { stdio: ['ignore', 'ignore', 'ignore'] });
+            }
+            catch { /* not loaded */ }
         }
-        catch { /* not loaded */ }
+    }
+    else {
+        process.stderr.write(`[agents] ${reg.reason}\n`);
     }
     try {
         fs.unlinkSync(plist);

package/dist/lib/monitors/config.d.ts

@@ -68,8 +68,8 @@ export type MonitorActionType = 'run' | 'routine' | 'notify' | 'webhook-out';
  */
 export interface ActionConfig {
     type: MonitorActionType;
-    /** run: which agent to spawn. */
-    agent?: AgentId;
+    /** run: which agent to spawn — a native harness id or a custom harness name (agents harness list). */
+    agent?: AgentId | (string & {});
     /** run: the prompt; `{event}` is replaced with the fired event summary. */
     prompt?: string;
     /** run: execution mode (shared with routines). */

package/dist/lib/monitors/config.js

@@ -17,6 +17,7 @@ import { safeJoin, isSafeSegmentName } from '../paths.js';
 import { atomicWriteFileSync } from '../fs-atomic.js';
 import { machineId, normalizeHost } from '../machine-id.js';
 import { ALL_AGENT_IDS } from '../agents.js';
+import { isCustomHarnessName } from '../profiles.js';
 /** Default values applied to every monitor config when fields are omitted. */
 const MONITOR_DEFAULTS = {
     enabled: true,
@@ -215,8 +216,8 @@ export function validateMonitor(config) {
             errors.push(`action has conflicting fields (${populatedAct.join(', ')}); specify exactly one action`);
         }
         if (action.type === 'run') {
-            if (action.agent && !ALL_AGENT_IDS.includes(action.agent)) {
-                errors.push(`action.agent must be one of: ${ALL_AGENT_IDS.join(', ')}`);
+            if (action.agent && !ALL_AGENT_IDS.includes(action.agent) && !isCustomHarnessName(action.agent)) {
+                errors.push(`action.agent must be one of: ${ALL_AGENT_IDS.join(', ')}, or a custom harness (agents harness list)`);
             }
             if (!action.prompt || typeof action.prompt !== 'string') {
                 errors.push("action.type 'run' requires action.prompt");

package/dist/lib/origin-machine.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Resolve which machine a session transcript originated on.
+ *
+ * Cross-machine sync mirrors a remote transcript to
+ * `backups/<agent>/<machine>/<subdir>/…`. Every other transcript is a live-home
+ * file on this box, so the origin is the local machine id.
+ *
+ * Kept in a leaf module (no session/db imports) so both discovery and the
+ * sessions DB upsert path can stamp `machine` without circular deps.
+ */
+/** Local machine id, cached for the process lifetime. */
+export declare function localMachineId(): string;
+/**
+ * The machine a discovered session originated on.
+ * When the path sits under the agent's backups root, the first segment below it
+ * is the origin machine id; otherwise it's the local machine.
+ */
+export declare function machineForSessionFile(filePath: string, agent: string): string;

package/dist/lib/origin-machine.js

@@ -0,0 +1,34 @@
+/**
+ * Resolve which machine a session transcript originated on.
+ *
+ * Cross-machine sync mirrors a remote transcript to
+ * `backups/<agent>/<machine>/<subdir>/…`. Every other transcript is a live-home
+ * file on this box, so the origin is the local machine id.
+ *
+ * Kept in a leaf module (no session/db imports) so both discovery and the
+ * sessions DB upsert path can stamp `machine` without circular deps.
+ */
+import * as path from 'path';
+import { getHistoryDir } from './state.js';
+import { machineId } from './machine-id.js';
+let _localMachineId;
+/** Local machine id, cached for the process lifetime. */
+export function localMachineId() {
+    return (_localMachineId ??= machineId());
+}
+/**
+ * The machine a discovered session originated on.
+ * When the path sits under the agent's backups root, the first segment below it
+ * is the origin machine id; otherwise it's the local machine.
+ */
+export function machineForSessionFile(filePath, agent) {
+    if (!filePath)
+        return localMachineId();
+    const base = path.join(getHistoryDir(), 'backups', agent) + path.sep;
+    if (filePath.startsWith(base)) {
+        const seg = filePath.slice(base.length).split(path.sep)[0];
+        if (seg)
+            return seg;
+    }
+    return localMachineId();
+}

package/dist/lib/perf/db.js

@@ -8,7 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import Database from '../sqlite.js';
 import { getPerfDbPath, getPerfDir } from '../state.js';
-import { localMachineId } from '../session/origin-machine.js';
+import { localMachineId } from '../origin-machine.js';
 import { resolveProjectKey } from '../project-key.js';
 import { percentile } from '../percentile.js';
 import { resolveSpoolPath, shortSessionId, _resetPerfSpoolForTest } from './spool.js';

package/dist/lib/perf/spool.js

@@ -9,7 +9,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { getPerfSpoolPath } from '../state.js';
-import { localMachineId } from '../session/origin-machine.js';
+import { localMachineId } from '../origin-machine.js';
 let _spoolOverride = null;
 let _disabled = false;
 /** Test seam — pair with db._resetPerfDbForTest. */

package/dist/lib/profiles.d.ts

@@ -96,6 +96,13 @@ export declare function getProfilePath(name: string): string;
 export declare function validateProfileName(name: string): void;
 /** Check whether a profile YAML file exists on disk. */
 export declare function profileExists(name: string): boolean;
+/**
+ * True when `name` is a custom harness (a profile that is not shadowing a
+ * native agent id) — the predicate routines/monitors use to accept an
+ * `agent:` value that `agents run` will resolve as a profile. A native id
+ * always reads as native, matching exec's resolution order.
+ */
+export declare function isCustomHarnessName(name: string): boolean;
 /** Read and parse a profile from disk. Throws if not found or malformed. */
 export declare function readProfile(name: string): Profile;
 /** Write a profile to disk atomically (write-to-tmp then rename). */

package/dist/lib/profiles.js

@@ -9,6 +9,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'node:crypto';
 import * as yaml from 'yaml';
+import { ALL_AGENT_IDS } from './agents.js';
 import { getUserAgentsDir } from './state.js';
 import { deleteKeychainToken, getKeychainToken, hasKeychainToken, keychainItemName } from './secrets/profiles.js';
 import { getPreset } from './profiles-presets.js';
@@ -39,6 +40,17 @@ export function validateProfileName(name) {
 export function profileExists(name) {
     return fs.existsSync(profilePath(name));
 }
+/**
+ * True when `name` is a custom harness (a profile that is not shadowing a
+ * native agent id) — the predicate routines/monitors use to accept an
+ * `agent:` value that `agents run` will resolve as a profile. A native id
+ * always reads as native, matching exec's resolution order.
+ */
+export function isCustomHarnessName(name) {
+    if (!PROFILE_NAME_PATTERN.test(name))
+        return false;
+    return !ALL_AGENT_IDS.includes(name) && profileExists(name);
+}
 /** Read and parse a profile from disk. Throws if not found or malformed. */
 export function readProfile(name) {
     validateProfileName(name);
@@ -77,7 +89,11 @@ function migrateLegacyProfileAuth(profile, file) {
     }
     const migratedAccount = findAccount(accountName);
     const oldItem = profile.auth.keychainItem;
-    profile.account = migratedAccount.id;
+    // Reference by NAME, not id: profiles sync fleet-wide with `agents repo push`
+    // while account ids are minted per-device, so an id ref breaks on every other
+    // machine ("Unknown account '<uuid>'"). Names are the portable handle — the
+    // registry resolves both, and `accounts rename` already rewrites name refs.
+    profile.account = migratedAccount.name;
     profile.provider = provider;
     delete profile.auth;
     delete profile.authOptional;
@@ -477,6 +493,15 @@ export function renameProfile(oldName, newName) {
 export function resolveProfileEnv(profile) {
     const env = { ...profile.env };
     if (profile.account) {
+        if (!findAccount(profile.account)) {
+            // The commonest cause: the profile synced here via `agents repo push/pull`
+            // but its account ref was minted on another device (legacy id refs), so
+            // the bare "Unknown account" from the registry gives the user nothing to
+            // act on. Name the harness and the repair.
+            throw new Error(`Harness '${profile.name}' references account '${profile.account}', which does not exist on this device. ` +
+                `Accounts are per-machine; pick one from 'agents accounts list' and repoint with ` +
+                `'agents harness edit ${profile.name} --account <name>', or add it with 'agents accounts add'.`);
+        }
         const account = resolveCredentialAccount(profile.account, profile.host.agent, profile.provider);
         Object.assign(env, account.env);
     }

package/dist/lib/sandbox.d.ts

@@ -7,6 +7,14 @@
  * access to explicitly allowed paths.
  */
 import type { JobConfig } from './scheduling/routines.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>;
 /**
@@ -21,6 +29,22 @@ export declare function buildSpawnEnv(overlayHome: string, extraEnv?: Record<str
 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): string;
+/**
+ * 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. */

package/dist/lib/sandbox.js

@@ -43,6 +43,14 @@ 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 = {
@@ -57,6 +65,32 @@ 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;
+    }
+    const configHome = process.env.XDG_CONFIG_HOME || path.join(resolveRealHome(), '.config');
+    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;
+    }
+    const dir = resolveHostGhConfigDir();
+    if (!dir)
+        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 = {
@@ -68,6 +102,18 @@ 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;
+    }
+    else {
+        delete env.GH_CONFIG_DIR;
+    }
     if (extraEnv) {
         Object.assign(env, extraEnv);
     }
@@ -101,11 +147,66 @@ export function prepareJobHome(config) {
     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 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))
+        return;
+    const overlayGhDir = path.join(overlayHome, '.config', 'gh');
+    if (fs.existsSync(overlayGhDir))
+        return;
+    fs.mkdirSync(path.dirname(overlayGhDir), { recursive: true });
+    try {
+        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;
+    if (spawnEnv.GH_TOKEN || spawnEnv.GH_ENTERPRISE_TOKEN || spawnEnv.GITHUB_TOKEN)
+        return;
+    if (spawnEnv.GH_CONFIG_DIR && fs.existsSync(path.join(spawnEnv.GH_CONFIG_DIR, 'hosts.yml')))
+        return;
+    if (spawnEnv.HOME && fs.existsSync(path.join(spawnEnv.HOME, '.config', 'gh', 'hosts.yml')))
+        return;
+    throw new Error("sandbox spawn would hide this host's GitHub auth from the child " +
+        '(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 realConfigHome = process.env.XDG_CONFIG_HOME || path.join(resolveRealHome(), '.config');

package/dist/lib/scheduling/routines.d.ts

@@ -107,8 +107,14 @@ export interface JobConfig {
     schedule?: string;
     /** Event/webhook fire condition. Optional when `schedule` is set. */
     trigger?: JobTrigger;
-    /** Which agent runs the routine. Optional — omitted for `workflow`/`command` routines. Exactly one of agent/workflow/command must be set. */
-    agent?: AgentId;
+    /**
+     * Which agent runs the routine — a native harness id, or the name of a
+     * custom harness (`agents harness list`), which the runner delegates to
+     * `agents run <name>` the same way workflow jobs are. Optional — omitted
+     * for `workflow`/`command` routines. Exactly one of agent/workflow/command
+     * must be set.
+     */
+    agent?: AgentId | (string & {});
     workflow?: string;
     /**
      * A plain shell command run directly instead of an agent/workflow — no LLM,
@@ -298,16 +304,16 @@ export interface JobConfig {
      * `lib/monitors/config.ts`) — re-gating here was double-gating on the wrong
      * key.
      *
-     * Deliberately narrow: a monitor's `routine` action fires a REAL routine, which
-     * keeps its activation gate, so a routine defined but not activated on this
-     * device is still refused.
+     * Deliberately narrow: a monitor's or webhook handler's `routine` action fires a
+     * REAL routine, which keeps its activation gate, so a routine defined but not
+     * activated on this device is still refused.
      *
      * Runtime-only, enforced at both ends of the schema boundary: `writeJob`
      * strips it, and `readJobFileResult` refuses a definition that carries it
      * (a hand-authored one would otherwise fire on every box regardless of
      * activation, since the daemon's load path never calls `validateJob`).
      */
-    dispatchedBy?: 'monitor';
+    dispatchedBy?: 'monitor' | 'webhook';
 }
 /**
  * Canonical form of a routine's `projects` field: drop non-string and empty
@@ -399,7 +405,7 @@ export declare function resolveJobExecutionContext(config: Pick<JobConfig, 'name
 export interface RunMeta {
     jobName: string;
     runId: string;
-    agent?: AgentId;
+    agent?: AgentId | (string & {});
     /**
      * Resolved agent version this run launched under. Re-pointed to each failover
      * attempt's version as the single-shot chain advances (runner.ts), so it names
@@ -504,10 +510,13 @@ export declare function finalizeRunMeta(meta: RunMeta, status: RunMeta['status']
  * `yosemite-s0` all agree. Every fire path (cron scheduler, webhook,
  * catchup/overdue, manual run) gates on this.
  *
- * A monitor-dispatched job ({@link JobConfig.dispatchedBy} `=== 'monitor'`) skips
+ * A monitor- or webhook-dispatched job ({@link JobConfig.dispatchedBy} set) skips
  * the routine activation manifest: it is not a routine, so its name can never be
  * a member and the lookup could only ever answer "not activated here"
- * (RUSH-2681). Its ownership was already decided by the monitor's `device:` pin.
+ * (RUSH-2681 for monitors; the same hole broke every `run.agent`/`run.workflow`
+ * webhook handler, which the receiver logged as `fired` while the run record read
+ * `skipped` with an empty allowlist). Ownership was already decided upstream — by
+ * the monitor's `device:` pin, or by the one box the webhook was delivered to.
  */
 export declare function jobRunsOnThisDevice(config: Pick<JobConfig, 'name' | 'devices' | 'dispatchedBy'>): boolean;
 /**

package/dist/lib/scheduling/routines.js

@@ -14,6 +14,7 @@ import { getRoutinesDir, getSystemRoutinesDir, getRunsDir, ensureAgentsDir, getP
 import * as os from 'os';
 import { safeJoin, isSafeSegmentName } from '../paths.js';
 import { isSafeProjectName, loadProjectDef, projectBasePath } from '../projects.js';
+import { isCustomHarnessName } from '../profiles.js';
 import { resolveRoutineExecutionContext, } from '../routine-context.js';
 import { atomicWriteFileSync } from '../fs-atomic.js';
 import { ALL_AGENT_IDS, ROUTINE_AGENT_IDS } from '../agents.js';
@@ -351,13 +352,16 @@ export function finalizeRunMeta(meta, status, exitCode, opts) {
  * `yosemite-s0` all agree. Every fire path (cron scheduler, webhook,
  * catchup/overdue, manual run) gates on this.
  *
- * A monitor-dispatched job ({@link JobConfig.dispatchedBy} `=== 'monitor'`) skips
+ * A monitor- or webhook-dispatched job ({@link JobConfig.dispatchedBy} set) skips
  * the routine activation manifest: it is not a routine, so its name can never be
  * a member and the lookup could only ever answer "not activated here"
- * (RUSH-2681). Its ownership was already decided by the monitor's `device:` pin.
+ * (RUSH-2681 for monitors; the same hole broke every `run.agent`/`run.workflow`
+ * webhook handler, which the receiver logged as `fired` while the run record read
+ * `skipped` with an empty allowlist). Ownership was already decided upstream — by
+ * the monitor's `device:` pin, or by the one box the webhook was delivered to.
  */
 export function jobRunsOnThisDevice(config) {
-    if (config.dispatchedBy !== 'monitor') {
+    if (config.dispatchedBy === undefined) {
         const activated = routineEnabledOnThisDevice(config.name);
         if (activated !== null)
             return activated;
@@ -636,7 +640,7 @@ export function readJobFileResult(filePath) {
     // written back (writeJob deletes it), so its presence here means hand-authored
     // state, not drift.
     if (Object.prototype.hasOwnProperty.call(parsed, 'dispatchedBy')) {
-        return { config: null, problem: '`dispatchedBy:` is a runtime-only monitor marker, not a routine field — routine is inert' };
+        return { config: null, problem: '`dispatchedBy:` is a runtime-only monitor/webhook marker, not a routine field — routine is inert' };
     }
     return {
         config: {
@@ -844,13 +848,17 @@ export function validateJob(config) {
     if (config.command !== undefined && (typeof config.command !== 'string' || config.command.trim() === '')) {
         errors.push('command must be a non-empty shell command string');
     }
-    if (hasAgent && config.agent && !ALL_AGENT_IDS.includes(config.agent)) {
-        errors.push(`agent must be one of: ${ALL_AGENT_IDS.join(', ')}`);
+    if (hasAgent && config.agent && !ALL_AGENT_IDS.includes(config.agent) && !isCustomHarnessName(config.agent)) {
+        errors.push(`agent must be one of: ${ALL_AGENT_IDS.join(', ')}, or a custom harness (agents harness list)`);
     }
     else if (hasAgent && config.agent && strategy === 'local' &&
-        !ROUTINE_AGENT_IDS.includes(config.agent)) {
+        !ROUTINE_AGENT_IDS.includes(config.agent) &&
+        // A custom harness is exempt from the local-daemon command table: the
+        // runner delegates it to `agents run <name>`, the same path workflow
+        // jobs take, so no ROUTINE_AGENT_COMMANDS template is needed.
+        !isCustomHarnessName(config.agent)) {
         // The local daemon only knows how to build a command for the agents in
-        // ROUTINE_AGENT_IDS (runner.ts's AGENT_COMMANDS table) — anything else is a
+        // ROUTINE_AGENT_IDS (baked from AGENT_COMMANDS in runner.ts) — anything else is a
         // real, installable agent (it passed the ALL_AGENT_IDS check above) but one
         // the daemon can't fire itself, so reject it now instead of accepting the
         // routine and failing at fire time (runner.ts buildJobCommand: "Unsupported

package/dist/lib/secrets/agent.js

@@ -36,6 +36,7 @@ import { getCliVersion, getCliVersionFresh } from '../version.js';
 import { getCliLaunch } from '../cli-entry.js';
 import { GLOBAL_HARNESS, bundleScopeChain } from './scope.js';
 import { deleteLeaseSession, rehydrateSessions, pruneSessionsOnSleep } from './session-store.js';
+import { serviceManagerRegistrationAllowed } from '../service-manifest.js';
 import { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
 import { MAX_LEASE_MS, MIN_LEASE_MS } from './lease.js';
 import { selectLeasedEnv } from './lease.js';
@@ -316,7 +317,11 @@ export function retireLegacySecretsAgentService() {
     const plist = servicePlistPath();
     // Only the real LaunchAgents dir is launchd-managed; a relocated (test) dir
     // has no bootstrapped job, so skip launchctl and just remove the plist.
-    if (!process.env.AGENTS_SECRETS_LAUNCHAGENTS_DIR) {
+    // Also skip launchctl under a redirected HOME: launchctl is per-user-session
+    // and HOME-independent, so a sandboxed process would still talk to the real
+    // launchd (RUSH-2968).
+    const reg = serviceManagerRegistrationAllowed();
+    if (!process.env.AGENTS_SECRETS_LAUNCHAGENTS_DIR && reg.allowed) {
         const uid = process.getuid?.() ?? 0;
         try {
             execFileSync('launchctl', ['bootout', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
@@ -328,6 +333,9 @@ export function retireLegacySecretsAgentService() {
             catch { /* not loaded */ }
         }
     }
+    else if (!reg.allowed) {
+        process.stderr.write(`[agents] ${reg.reason}\n`);
+    }
     try {
         fs.unlinkSync(plist);
     }

package/dist/lib/secrets/index.js

@@ -32,7 +32,7 @@ import { windowsBackend, usesFileFallback as windowsUsesFileFallback, importNati
 import { isHeadlessSecretsContext } from './headless.js';
 import { KEYCHAIN_READ_BACKOFF_TTL_MS, clearKeychainReadBackoff, isKeychainReadBackedOff, noteKeychainReadFailure, } from './read-backoff.js';
 import { getKeychainHelperPath } from './install-helper.js';
-import { deriveShortId } from '../session/short-id.js';
+import { deriveShortId } from '../text/short-id.js';
 const SERVICE_PREFIX = 'agents-cli';
 export const SECRETS_ITEM_PREFIX = `${SERVICE_PREFIX}.secrets.`;
 const BUNDLES_ITEM_PREFIX = `${SERVICE_PREFIX}.bundles.`;