@phnx-labs/agents-cli 1.22.39 → 1.22.40

package/dist/lib/secrets/remote.js

@@ -1,6 +1,6 @@
 /**
  * Remote secrets — read and use `agents secrets` bundles that live on another
- * host, over the same hardened SSH path that `agents secrets export --host`
+ * host, over the same hardened SSH path that `agents secrets export --device`
  * (the write inverse) already uses.
  *
  * This is the READ / USE direction:
@@ -10,7 +10,7 @@
  *              inject it ephemerally — never written to this machine's keychain.
  *
  * Trust model: relies on the operator's existing SSH access to the host (same
- * boundary as `export --host` / `run --host`). Bundle names are shell-quoted
+ * boundary as `export --device` / `run --device`). Bundle names are shell-quoted
  * into the remote command; resolved VALUES return over ssh stdout; a forwarded
  * file-backend passphrase travels over ssh stdin (first line) so it never lands
  * in argv / `ps` / remote shell history. Nothing is persisted locally.
@@ -39,9 +39,8 @@ function hostKeyLookupName(target) {
  *   - **Managed pinned host keys.** Verify against the CLI-owned known_hosts
  *     store (`known-hosts.ts`), not `~/.ssh/known_hosts`. A CHANGED key on a
  *     known host is refused (`StrictHostKeyChecking` `yes` once pinned,
- *     `accept-new` — which still refuses a changed key, only learns a genuinely
- *     new one — before that). So a machine-in-the-middle swapping a pinned host's
- *     key can never receive or return a secret.
+ *     `accept-new` before that). Callers that copy durable provider credentials
+ *     must separately require an existing pin before invoking this transport.
  *   - **No multiplex reuse.** `multiplex: false` — a credential channel never
  *     leaves a persistent `ControlMaster` socket lingering (60s `ControlPersist`)
  *     that any other `agents` invocation to that host would silently reuse.
@@ -49,6 +48,13 @@ function hostKeyLookupName(target) {
 export function credentialTransportSshOpts(target) {
     return { hostKeyOpts: hostKeyCheckingOpts(isHostPinned(hostKeyLookupName(target))), multiplex: false };
 }
+/** Refuse durable credential transfer until the destination SSH key is pinned. */
+export function assertCredentialTransportHostPinned(target, pinned = isHostPinned(hostKeyLookupName(target))) {
+    if (pinned)
+        return;
+    throw new Error(`Refusing to transfer provider credentials to '${target}' before its SSH host key is pinned. ` +
+        `Connect once with 'agents ssh ${target}' and verify the host, then retry.`);
+}
 /**
  * Trust boundary for a remote-resolved env map. A peer's `secrets export` output
  * is untrusted input: a compromised or misconfigured host could return keys that
@@ -85,9 +91,9 @@ function osForTarget(target, lookupName) {
     return byName ?? resolveRemoteOsSync(target.split('@').pop() ?? target);
 }
 /**
- * Resolve a `--host` value to an ssh target STRING for the remote-secrets path.
+ * Resolve a `--device` value to an ssh target STRING for the remote-secrets path.
  * Delegates to the single host/device resolver (`resolveHost`, RUSH-1967) so a
- * name here dials the exact same box `run --host` does; on a miss, treats the
+ * name here dials the exact same box `run --device` does; on a miss, treats the
  * value as a raw ssh target and validates it against injection. Named distinctly
  * from `../devices/resolve-target.ts` (which returns richer shapes) so importing
  * the wrong one can't silently change which machine you dial.
@@ -102,7 +108,7 @@ export async function resolveHostSshTarget(nameOrAlias) {
 /**
  * Merge `--host <single>` / `--hosts <a,b,c>` (and their `--device` / `--devices`
  * aliases) into an ordered, de-duplicated list. All four flags compose; any alone
- * works. `--device`/`--devices` resolve identically to `--host`/`--hosts` so the
+ * works. `--device`/`--devices` resolve identically to `--device`/`--hosts` so the
  * fleet-wide `--device` vocabulary (see `agents run --device`, `agents feed --host`)
  * works on the secrets remote commands too. Empty when none is set.
  */
@@ -158,7 +164,7 @@ export function remoteSecretsRaw(target, args, opts = {}) {
     // to multiplex — see `credentialTransportSshOpts` (RUSH-2527). A `-tt` session
     // (a remote reveal/passphrase prompt) additionally allocates a PTY and never
     // multiplexes, and it COMPOSES with the secret posture: a `view --reveal` over
-    // `--host` both prompts AND streams the plaintext value back over ssh stdout,
+    // `--device` both prompts AND streams the plaintext value back over ssh stdout,
     // so it needs the managed host-key pin too — `tty` must not short-circuit past
     // `secret`. A plain browse `list` passes neither and keeps the shared baseline.
     const posture = opts.secret ? credentialTransportSshOpts(target) : {};
@@ -180,13 +186,13 @@ export function remoteSecretsRaw(target, args, opts = {}) {
  * appear (the macOS file-store guard then hard-errors "needs
  * AGENTS_SECRETS_PASSPHRASE") — this inherits the caller's real terminal, so the
  * remote sees a genuine TTY and its hidden passphrase prompt surfaces and reads
- * the keystrokes. This is the transport for `unlock --host`: you type the remote
+ * the keystrokes. This is the transport for `unlock --device`: you type the remote
  * bundle's passphrase at your own terminal. Output is NOT captured (it streams
  * to the terminal); only the exit code is returned.
  */
 export function remoteSecretsStream(target, args, opts = {}) {
     const remoteCmd = buildRemoteAgentsInvocation(['secrets', ...args], undefined, osForTarget(target, opts.osLookupName));
-    // `unlock --host` carries the remote bundle's passphrase to the destination over
+    // `unlock --device` carries the remote bundle's passphrase to the destination over
     // this interactive channel, so it is secret-bearing: pin the managed host key
     // (a changed key is refused) and never multiplex (RUSH-2527).
     return sshStream(target, remoteCmd, { tty: true, ...credentialTransportSshOpts(target) });
@@ -346,7 +352,7 @@ export function keychainWriteFailureMessage(host, bundle, reason) {
         `A macOS login keychain is LOCKED under headless SSH, so a keychain-backed write ` +
         `lands the bundle metadata but no readable secret items, and later reads fail with ` +
         `"stored item '…' not found". Re-run with a headless-readable backend:\n` +
-        `    agents secrets export ${bundle} --host ${host} --remote-backend file\n` +
+        `    agents secrets export ${bundle} --device ${host} --remote-backend file\n` +
         `(needs AGENTS_SECRETS_PASSPHRASE set locally), or unlock the remote keychain first ` +
         `(e.g. an interactive login / \`agents secrets unlock\` on ${host}) and retry.`);
 }
@@ -400,7 +406,7 @@ export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {})
 }
 /**
  * The `bash -lc` command + stdin payload that drives a **file-backed** remote
- * import for `secrets export --host … --remote-backend file`.
+ * import for `secrets export --device … --remote-backend file`.
  *
  * The file store is passphrase-free by default: with `AGENTS_SECRETS_PASSPHRASE`
  * unset the remote `agents secrets import --backend file` auto-provisions the
@@ -422,7 +428,8 @@ export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {})
  */
 export function buildRemoteFileImportCommand(bundle, dotenv, opts = {}) {
     const force = opts.force ? ' --force' : '';
-    const importCmd = `agents secrets import ${shellQuote(bundle)} --from - --backend file${force}`;
+    const policy = opts.policyNever ? ' --policy never --i-understand' : '';
+    const importCmd = `agents secrets import ${shellQuote(bundle)} --from - --backend file${force}${policy}`;
     const passphrase = opts.passphrase ?? '';
     if (passphrase) {
         // Opt-in shared passphrase: read it off the FIRST stdin line, export it, then

package/dist/lib/secrets/vault.js

@@ -237,7 +237,7 @@ export function getVaultSession() {
 function requireVaultKey() {
     const session = getVaultSession();
     if (!session.loggedIn) {
-        throw new Error('Not logged in. Run: agents login');
+        throw new Error('Synced secrets locked. Run: agents secrets vault unlock');
     }
     return session.key;
 }
@@ -259,7 +259,7 @@ function parseVaultItem(item) {
 function vaultMissingError(file) {
     return new Error(`Vault file is missing: ${file}. A vault was created but the file is gone` +
         ' (a sync conflict, an undownloaded placeholder, or an accidental move/delete).' +
-        ' Restore it before writing, or run: agents login --create --force to start over.');
+        ' Restore it before writing, or run: agents secrets vault unlock --create --force to start over.');
 }
 function readVaultData() {
     const file = vaultPath();

package/dist/lib/self-heal/checks/shadowing.js

@@ -6,7 +6,7 @@
 import { resultOf } from '../types.js';
 import { AGENTS } from '../../agents.js';
 import { getPathShadowingExecutable, adoptShadowingLauncher, listAgentsWithNonIsolatedInstalledVersions, } from '../../shims.js';
-import { getGlobalDefault } from '../../versions.js';
+import { getGlobalDefault } from '../../installations/versions.js';
 export const shadowingCheck = {
     id: 'shadowing',
     title: 'Launcher shadowing the version-managed shim',

package/dist/lib/self-heal/checks/shims.js

@@ -5,7 +5,7 @@
 import { resultOf } from '../types.js';
 import { AGENTS } from '../../agents.js';
 import { createShim, ensureShimCurrent, ensureVersionedAliasCurrent, isShimCurrent, isVersionedAliasCurrent, removeShim, shimExists, shimPointsAtLiveInstall, removeLegacyUserShim, listAgentsWithInstalledVersions, listAgentsWithNonIsolatedInstalledVersions, listShimFileNames, pruneOrphanedCommandShim, } from '../../shims.js';
-import { listInstalledVersions } from '../../versions.js';
+import { listInstalledVersions } from '../../installations/versions.js';
 export const shimsCheck = {
     id: 'shims',
     title: 'Dispatch shims + versioned aliases',

package/dist/lib/self-update.d.ts

@@ -200,7 +200,24 @@ export interface MultiInstallInventoryEntry {
     packageRoot: string;
     version: string;
     note: string;
+    /** True for the copy that is currently executing. */
+    running: boolean;
+    /**
+     * True when a bare `agents doctor --fix` deletes this copy (RUSH-2415:
+     * npx-cache / unsafe-legacy / pre-1.22.30 with a fixed peer). False for the
+     * running copy and for any duplicate --fix will not touch — a healthy
+     * >=1.22.30 peer, or a pre-1.22.30 copy with no fixed peer to fall back to;
+     * both need the manual command from manualUninstallCommand() (RUSH-2705/2713).
+     */
+    autoPurgeable: boolean;
 }
+/**
+ * The exact shell command that removes the install at `packageRoot` by hand —
+ * the remedy for duplicates `doctor --fix` deliberately will not purge
+ * (RUSH-2705). `--prefix` pins the target tree no matter which npm binary
+ * PATH resolves, mirroring installPackageIntoPrefix.
+ */
+export declare function manualUninstallCommand(packageRoot: string): string;
 export declare function buildMultiInstallInventory(runningRoot: string, runningVersion: string, installs: AgentsCliInstall[]): MultiInstallInventoryEntry[];
 /** Why a discovered install is safe to delete without an interactive confirm. */
 export type RemovableInstallReason = 'npx-cache' | 'unsafe-legacy-helper' | 'pre-fixed-version';
@@ -250,6 +267,27 @@ export declare function purgeRemovableAgentsCliInstalls(candidates: RemovableAge
     dryRun?: boolean;
     runningRoot?: string;
 }): PurgeRemovableInstallsResult;
+/** A detected duplicate that `doctor --fix` will not purge (RUSH-2705). */
+export interface UnresolvedDuplicateInstall {
+    packageRoot: string;
+    version: string;
+    /** Exact shell command that removes this copy by hand. */
+    manualRemoveCommand: string;
+}
+export interface RemediateStaleInstallsResult extends PurgeRemovableInstallsResult {
+    inventory: MultiInstallInventoryEntry[];
+    candidates: RemovableAgentsCliInstall[];
+    /**
+     * Duplicates detected but NOT auto-purged, for either reason:
+     *   1. a healthy >=1.22.30 global (safe, just redundant), or
+     *   2. a pre-1.22.30 copy left alone only because no fixed peer exists to fall
+     *      back to (the anti-stranding guard) — this one is genuinely vulnerable,
+     *      not healthy.
+     * Either way the caller must surface manualRemoveCommand — otherwise the
+     * multi-install warning keeps firing with no working remedy (RUSH-2705/2713).
+     */
+    unresolved: UnresolvedDuplicateInstall[];
+}
 /**
  * Scan + classify + purge in one call. Used by `agents doctor --fix` and
  * `agents upgrade` so both paths remediate the same set of latent copies.
@@ -260,10 +298,7 @@ export declare function remediateStaleAgentsCliInstalls(opts: {
     pathEnv?: string;
     findOpts?: FindAgentsCliInstallsOptions;
     dryRun?: boolean;
-}): PurgeRemovableInstallsResult & {
-    inventory: MultiInstallInventoryEntry[];
-    candidates: RemovableAgentsCliInstall[];
-};
+}): RemediateStaleInstallsResult;
 /**
  * Resolve every `agents` entrypoint on PATH, then inspect the bounded global
  * install layouts used by NVM, fnm, Volta, Bun, npm, and npx. More than one

package/dist/lib/self-update.js

@@ -145,6 +145,13 @@ export function readMultiInstallScanCache(file) {
             !Array.isArray(raw.inventory)) {
             return null;
         }
+        // A cache written before the entries carried running/autoPurgeable
+        // (RUSH-2705) cannot drive the banner's remedy choice — treat it as
+        // corrupt so the caller re-scans rather than mis-advertising --fix.
+        const entries = raw.inventory;
+        if (entries.some((entry) => typeof entry?.running !== 'boolean' || typeof entry?.autoPurgeable !== 'boolean')) {
+            return null;
+        }
         return raw;
     }
     catch {
@@ -415,11 +422,67 @@ function packageRootForEntry(real) {
     }
     return null;
 }
+/** Best-effort canonical path; keeps the input when realpath fails. */
+function canonicalPath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/**
+ * Ensure the running copy participates in classification (the "has a fixed
+ * peer" check) even when the PATH scan missed it — a source tree or unusual
+ * layout. The running root is never deleted regardless.
+ */
+function withRunningInstall(installs, runningRoot, runningVersion) {
+    const runningCanonical = canonicalPath(runningRoot);
+    const already = installs.some((install) => canonicalPath(install.packageRoot) === runningCanonical);
+    if (already)
+        return installs;
+    return [...installs, {
+            packageRoot: runningRoot,
+            version: runningVersion,
+            // Unknown for a synthetic entry — classify only uses version for the
+            // fixed-peer check; the running root is never deleted regardless.
+            atomicHelperInstall: true,
+        }];
+}
+/**
+ * The exact shell command that removes the install at `packageRoot` by hand —
+ * the remedy for duplicates `doctor --fix` deliberately will not purge
+ * (RUSH-2705). `--prefix` pins the target tree no matter which npm binary
+ * PATH resolves, mirroring installPackageIntoPrefix.
+ */
+export function manualUninstallCommand(packageRoot) {
+    const resolved = path.resolve(packageRoot);
+    if (detectPackageManager(resolved) === 'bun') {
+        return `bun remove -g ${NPM_PACKAGE_NAME}`;
+    }
+    try {
+        return `npm uninstall -g --prefix '${deriveGlobalPrefix(resolved)}' ${NPM_PACKAGE_NAME}`;
+    }
+    catch {
+        // Not inside a node_modules tree — no npm prefix owns it; deleting the
+        // directory is the only removal there is.
+        return `rm -rf '${resolved}'`;
+    }
+}
 export function buildMultiInstallInventory(runningRoot, runningVersion, installs) {
+    const runningCanonical = canonicalPath(runningRoot);
+    const removableRoots = new Set(classifyRemovableAgentsCliInstalls(runningRoot, withRunningInstall(installs, runningRoot, runningVersion)).map((candidate) => candidate.packageRoot));
     const byRoot = new Map();
-    byRoot.set(runningRoot, { packageRoot: runningRoot, version: runningVersion, note: 'running' });
+    byRoot.set(runningRoot, {
+        packageRoot: runningRoot,
+        version: runningVersion,
+        note: 'running',
+        running: true,
+        autoPurgeable: false,
+    });
     for (const install of installs) {
-        const notes = [install.packageRoot === runningRoot
+        const running = canonicalPath(install.packageRoot) === runningCanonical;
+        const notes = [running
                 ? 'running'
                 : install.binPath
                     ? `agents on PATH: ${install.binPath}`
@@ -430,6 +493,8 @@ export function buildMultiInstallInventory(runningRoot, runningVersion, installs
             packageRoot: install.packageRoot,
             version: install.version,
             note: notes.join('; '),
+            running,
+            autoPurgeable: !running && removableRoots.has(canonicalPath(install.packageRoot)),
         });
     }
     return [...byRoot.values()];
@@ -588,38 +653,26 @@ export function purgeRemovableAgentsCliInstalls(candidates, opts = {}) {
  */
 export function remediateStaleAgentsCliInstalls(opts) {
     const pathEnv = opts.pathEnv ?? (process.env.PATH || '');
-    const installs = findAgentsCliInstalls(pathEnv, opts.findOpts);
+    let installs = findAgentsCliInstalls(pathEnv, opts.findOpts);
     // Ensure the running root participates in "has a fixed peer" even when the
     // PATH scan missed it (source tree, unusual layout).
     if (opts.runningVersion) {
-        const already = installs.some((i) => {
-            try {
-                return fs.realpathSync(i.packageRoot) === fs.realpathSync(opts.runningRoot);
-            }
-            catch {
-                return i.packageRoot === opts.runningRoot;
-            }
-        });
-        if (!already) {
-            installs.push({
-                packageRoot: opts.runningRoot,
-                version: opts.runningVersion,
-                // Unknown for a synthetic entry — classify only uses version for the
-                // fixed-peer check; the running root is never deleted regardless.
-                atomicHelperInstall: true,
-            });
-        }
+        installs = withRunningInstall(installs, opts.runningRoot, opts.runningVersion);
     }
     const candidates = classifyRemovableAgentsCliInstalls(opts.runningRoot, installs);
     const purge = purgeRemovableAgentsCliInstalls(candidates, {
         dryRun: opts.dryRun,
         runningRoot: opts.runningRoot,
     });
-    return {
-        ...purge,
-        candidates,
-        inventory: buildMultiInstallInventory(opts.runningRoot, opts.runningVersion ?? 'unknown', installs),
-    };
+    const inventory = buildMultiInstallInventory(opts.runningRoot, opts.runningVersion ?? 'unknown', installs);
+    const unresolved = inventory
+        .filter((entry) => !entry.running && !entry.autoPurgeable)
+        .map((entry) => ({
+        packageRoot: entry.packageRoot,
+        version: entry.version,
+        manualRemoveCommand: manualUninstallCommand(entry.packageRoot),
+    }));
+    return { ...purge, candidates, inventory, unresolved };
 }
 function childDirectories(parent) {
     try {

package/dist/lib/serve/control.d.ts

@@ -77,7 +77,7 @@ export declare function spawnDetached(command: string, args: string[], stdio?: S
 /**
  * Default run dispatcher: re-invoke `agents run` with a server-minted id so the
  * run is addressable, detached so it outlives this request (and the anchor
- * process). Local runs detach here; `--host` runs detach on the executor via
+ * process). Local runs detach here; `--device` runs detach on the executor via
  * the existing dispatch path.
  */
 export declare const defaultRunner: RunDispatcher;

package/dist/lib/serve/control.js

@@ -2,7 +2,7 @@ import { createServer } from 'http';
 import fs from 'fs';
 import { spawn } from 'child_process';
 import { randomUUID, randomBytes } from 'crypto';
-import { getAgentsInvocation } from '../daemon.js';
+import { getAgentsInvocation } from '../daemon/daemon.js';
 import { handleServeGet, resolveServeContext } from './server.js';
 import { verifyControlToken } from './token.js';
 import { readNewEvents, streamDir, streamLogPath } from './stream.js';
@@ -127,7 +127,7 @@ export function spawnDetached(command, args, stdio = 'ignore') {
 /**
  * Default run dispatcher: re-invoke `agents run` with a server-minted id so the
  * run is addressable, detached so it outlives this request (and the anchor
- * process). Local runs detach here; `--host` runs detach on the executor via
+ * process). Local runs detach here; `--device` runs detach on the executor via
  * the existing dispatch path.
  */
 export const defaultRunner = async (req) => {
@@ -144,7 +144,7 @@ export const defaultRunner = async (req) => {
     if (req.mode)
         argv.push('--mode', req.mode);
     if (req.host)
-        argv.push('--host', req.host);
+        argv.push('--device', req.host);
     if (req.cwd)
         argv.push('--cwd', req.cwd);
     const inv = getAgentsInvocation(argv);
@@ -152,7 +152,7 @@ export const defaultRunner = async (req) => {
     // unhandled 'error' that crashes the anchor for every other session.
     //
     // For an anchor-local run, capture the `--json` NDJSON to a per-session file
-    // so `GET /api/session/:id/stream` can offset-tail it. A `--host` run emits
+    // so `GET /api/session/:id/stream` can offset-tail it. A `--device` run emits
     // its NDJSON on the remote box (streaming that reuses pullRemoteLogDelta — a
     // follow-up), so we don't capture the local dispatcher's output.
     if (req.host) {

package/dist/lib/serve/data.d.ts

@@ -15,7 +15,7 @@
  */
 import { AgentManager } from '../teams/agents.js';
 import type { AgentStatusSummary } from '../teams/api.js';
-import type { JobConfig } from '../routines.js';
+import type { JobConfig } from '../scheduling/routines.js';
 import type { CloudTask } from '../cloud/types.js';
 /** One teammate's worktree and its current uncommitted diff. */
 export interface WorktreeDiff {

package/dist/lib/serve/data.js

@@ -16,7 +16,7 @@
 import { AgentManager } from '../teams/agents.js';
 import { handleTasks, handleStatus, toTaskStatusSummary } from '../teams/api.js';
 import { gitDiff } from '../teams/worktree.js';
-import { listJobs } from '../routines.js';
+import { listJobs } from '../scheduling/routines.js';
 import { listTasks as listCloudTasks } from '../cloud/store.js';
 /**
  * Build the per-worktree diffs for a set of teammates. Only teammates with a

package/dist/lib/serve/stream.js

@@ -9,7 +9,7 @@
  * phone that drops mid-run reconnects with `?offset=<bytes>` (or the standard
  * `Last-Event-ID` header) and never loses or double-counts an event.
  *
- * Scope: this streams runs whose executor is the anchor itself (no `--host`).
+ * Scope: this streams runs whose executor is the anchor itself (no `--device`).
  * Streaming a run offloaded to another box reuses `pullRemoteLogDelta` and is a
  * follow-up; see the changelog fragment.
  */

package/dist/lib/service-manifest.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A short, stable hash of this process's HOME when — and only when — HOME has
+ * been redirected away from the account's real home.
+ *
+ * `os.userInfo().homedir` reads the OS/passwd record directly and ignores
+ * `$HOME` (unlike `os.homedir()`, which honors it), so comparing the two
+ * detects exactly that redirection: true for every hermetic test process, false
+ * for every real interactive or production invocation. A real user's services
+ * therefore keep registering under their unchanged production identifiers.
+ */
+export declare function isolatedHomeSuffix(): string | null;
+/**
+ * Namespace a service identifier under a redirected HOME. Returns `base`
+ * unchanged for a real production invocation.
+ */
+export declare function namespacedServiceLabel(base: string): string;
+/**
+ * The home-resolution environment every generated service manifest must carry,
+ * so the service-manager-started child resolves the SAME home the caller did.
+ *
+ * `AGENTS_REAL_HOME` is the canonical seam that distinguishes an agent's
+ * isolated version home from the active installation home; pinning it alongside
+ * HOME keeps a child that a login shell or service manager re-homes pointed at
+ * the installation the caller meant.
+ */
+export declare function serviceManifestHomeEnv(): {
+    HOME: string;
+    AGENTS_REAL_HOME: string;
+};

package/dist/lib/service-manifest.js

@@ -0,0 +1,80 @@
+/**
+ * One rule for every service manifest this CLI writes — the launchd plists and
+ * the systemd unit that a service manager, not this process, will later start.
+ *
+ * RUSH-2639. A service manager does NOT inherit the environment of whoever
+ * called `launchctl bootstrap` / `systemctl --user start`. The started child
+ * sees the login session's own environment plus whatever the manifest declares,
+ * so a manifest that omits HOME hands its child the ACCOUNT home no matter what
+ * HOME the process that generated and loaded it was running under. In
+ * production that is a no-op — the login session's HOME already is the account
+ * home — but under the hermetic test harness (`tests/setup.ts` redirects HOME to
+ * a fork-private sandbox) it means a service-manager-started process silently
+ * escapes the sandbox and bootstraps the developer's or the CI runner's REAL
+ * `~/.agents` (`ensureAgentsDir`, `state.ts`, creates `.system`, `.history`,
+ * `.cache`, `routines`).
+ *
+ * The same asymmetry applies to the service IDENTIFIER. `launchctl` and
+ * `systemctl` route `bootout`/`bootstrap`/`unload`/`load`/`list` by identifier
+ * alone, never by the manifest file's path, so a sandboxed instance's own
+ * teardown of its own never-loaded manifest tears down whatever job the OS
+ * already has registered under that same label — on a developer's machine, the
+ * real always-on service; in CI, another concurrent test fork's.
+ *
+ * Both were fixed once for the daemon and left unfixed for the menu-bar helper
+ * (`lib/menubar/install-menubar.ts`) and the computer helper
+ * (`commands/computer.ts`), which is why the leak survived the daemon fix. This
+ * module is the single place both rules live, so a new manifest has one obvious
+ * thing to call.
+ *
+ * It is not yet the only consumer of the identifier rule: `lib/secrets/agent.ts`
+ * keeps a literal `SERVICE_LABEL` for its `bootout`. That path is retire-only —
+ * it detects and removes a plist an older version installed and generates none
+ * of its own — so it has no HOME to bake and was deliberately left alone.
+ */
+import * as crypto from 'crypto';
+import * as os from 'os';
+import * as path from 'path';
+/**
+ * A short, stable hash of this process's HOME when — and only when — HOME has
+ * been redirected away from the account's real home.
+ *
+ * `os.userInfo().homedir` reads the OS/passwd record directly and ignores
+ * `$HOME` (unlike `os.homedir()`, which honors it), so comparing the two
+ * detects exactly that redirection: true for every hermetic test process, false
+ * for every real interactive or production invocation. A real user's services
+ * therefore keep registering under their unchanged production identifiers.
+ */
+export function isolatedHomeSuffix() {
+    try {
+        const effective = path.resolve(process.env.HOME || os.homedir());
+        const real = path.resolve(os.userInfo().homedir);
+        if (effective === real)
+            return null;
+        return crypto.createHash('sha256').update(effective).digest('hex').slice(0, 12);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Namespace a service identifier under a redirected HOME. Returns `base`
+ * unchanged for a real production invocation.
+ */
+export function namespacedServiceLabel(base) {
+    const suffix = isolatedHomeSuffix();
+    return suffix ? `${base}.sandbox-${suffix}` : base;
+}
+/**
+ * The home-resolution environment every generated service manifest must carry,
+ * so the service-manager-started child resolves the SAME home the caller did.
+ *
+ * `AGENTS_REAL_HOME` is the canonical seam that distinguishes an agent's
+ * isolated version home from the active installation home; pinning it alongside
+ * HOME keeps a child that a login shell or service manager re-homes pointed at
+ * the installation the caller meant.
+ */
+export function serviceManifestHomeEnv() {
+    const home = process.env.HOME || os.homedir();
+    return { HOME: home, AGENTS_REAL_HOME: process.env.AGENTS_REAL_HOME || home };
+}