@phnx-labs/agents-cli 1.20.87 → 1.20.89

package/dist/commands/sessions.js

@@ -20,7 +20,7 @@ import { looksLikePath, toComparablePath, homeDir, needsWindowsShell, findExecut
 import { getActiveSessions } from '../lib/session/active.js';
 import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
 import { mapPanesToTargets, listClients } from '../lib/tmux/session.js';
-import { resolveViewingIn } from '../lib/session/viewing-in.js';
+import { resolveViewingIn, viewingInLabel } from '../lib/session/viewing-in.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { gatherRemoteActive, NO_FANOUT_ENV } from '../lib/session/remote-active.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
@@ -442,6 +442,11 @@ function modelLabel(model) {
  * (null when unknown) alongside the raw fields, so every active row is joinable.
  * `project` uses the same derivation SessionMeta does — basename(cwd) (see
  * discover.ts) — so the active view and the history view join identically.
+ *
+ * `viewingIn` flattens to the same display string the row renderer prints —
+ * `'codium tab 3'` / `'detached'` / null — so a consumer can tell a watched
+ * session from an orphaned one (its terminal died, the agent is still running)
+ * without re-implementing the tmux client lookup.
  */
 export function serializeActiveSessionsForJson(sessions) {
     return sessions.map((s) => ({
@@ -449,6 +454,7 @@ export function serializeActiveSessionsForJson(sessions) {
         ticketId: s.ticket?.id ?? null,
         project: s.cwd ? path.basename(s.cwd) : null,
         prLink: s.pr?.url ?? null,
+        viewingIn: viewingInLabel(s) ?? null,
     }));
 }
 /**
@@ -496,13 +502,9 @@ function locatorBadge(s) {
         // For a tmux-hosted session, say which app+tab is looking at it right now
         // (or that it's running detached). Only meaningful for tmux (the pane is the
         // durable handle; the viewer is transient).
-        if (s.viewingIn) {
-            const tab = s.viewingIn.tab != null ? ` tab ${s.viewingIn.tab}` : '';
-            parts.push(chalk.gray(`viewing in ${s.viewingIn.app}${tab}`));
-        }
-        else {
-            parts.push(chalk.gray('detached'));
-        }
+        const label = viewingInLabel(s);
+        if (label)
+            parts.push(chalk.gray(label === 'detached' ? label : `viewing in ${label}`));
     }
     else if (p?.mux?.kind === 'screen') {
         parts.push(chalk.green('screen'));
@@ -860,13 +862,33 @@ async function enrichLocalLocators(local) {
         }
     }
     catch { /* non-fatal */ }
-    // tmux attach targets + "viewing in <app> tab N", one batched query per socket.
+    // One Ghostty enumeration shared across every socket's viewing-in resolve
+    // (a tmux client can be attached from a Ghostty tab).
+    await enrichTmuxLocators(local, await enumerateGhosttyTabsQuietly());
+}
+/** {@link enumerateGhosttyTabs}, best-effort — an osascript failure yields no surfaces. */
+async function enumerateGhosttyTabsQuietly() {
+    try {
+        return await enumerateGhosttyTabs();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The tmux half of {@link enrichLocalLocators}: the `session:window.pane` attach
+ * target and "viewing in <app> tab N" / detached, one batched query per socket.
+ *
+ * Split out because it is the only locator the `--json` path can afford. It costs
+ * tmux queries and a `ps` read — no osascript — so scriptable output stays cheap
+ * while still answering the question a consumer actually needs: is anyone looking
+ * at this session, or is it running orphaned? Without `surfaces`, a Ghostty-attached
+ * client still resolves as attached, just without its tab number.
+ */
+async function enrichTmuxLocators(local, surfaces = []) {
     try {
         const tmux = local.filter(s => s.provenance?.mux?.kind === 'tmux' && s.provenance.mux.pane);
         if (tmux.length > 0) {
-            // One Ghostty enumeration shared across every socket's viewing-in resolve
-            // (a tmux client can be attached from a Ghostty tab).
-            const surfaces = await enumerateGhosttyTabs();
             const sockets = new Set(tmux.map(s => s.provenance.mux.socket));
             for (const socket of sockets) {
                 const paneMap = await mapPanesToTargets(socket);
@@ -964,6 +986,11 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
     // present so a supervising agent or hook can poll it as a gate.
     const sessions = waitingOnly ? merged.filter(s => s.status === 'input_required') : merged;
     if (asJson) {
+        // Resolve who is watching each local tmux pane before serializing: `viewingIn`
+        // is how a consumer distinguishes a session someone is looking at from one
+        // running orphaned after its terminal died. tmux-only (no osascript) so the
+        // scriptable path stays cheap — see enrichTmuxLocators.
+        await enrichTmuxLocators(sessions.filter(s => !s.machine || s.machine === self));
         process.stdout.write(JSON.stringify(serializeActiveSessionsForJson(sessions), null, 2) + '\n');
         if (waitingOnly && sessions.length > 0)
             process.exitCode = 1;
@@ -2368,6 +2395,7 @@ export function buildResumeCommand(session) {
         case 'grok':
         case 'kimi':
         case 'droid':
+        case 'cursor':
             // Grok (and some others) sessions are captured artifacts, not resumable the same way.
             return null;
     }

package/dist/commands/ssh.js

@@ -313,7 +313,7 @@ function printFleetResults(results) {
     if (failed > 0)
         process.exitCode = 1;
 }
-function localHealthRow(self, stats) {
+async function localHealthRow(self, stats) {
     return {
         name: self,
         platform: process.platform === 'darwin' ? 'macos' : process.platform,
@@ -324,7 +324,7 @@ function localHealthRow(self, stats) {
         orphans: countOrphans(),
         // Local baseline inventory for cross-device divergence (RUSH-2027) — the
         // yardstick every remote box is compared against.
-        inventory: collectLocalFleetInventory(process.cwd()),
+        inventory: await collectLocalFleetInventory(process.cwd()),
     };
 }
 async function probeRemoteHealth(target) {
@@ -369,7 +369,7 @@ async function runFleetStatus(opts) {
     // read from a fresh probe, not a stale tailscale snapshot (RUSH-1965).
     // Best-effort: a registry write must never break the status render.
     await writeReachability(collectReachabilityWriteBacks(reg, statsMap)).catch(() => { });
-    const rows = [localHealthRow(self, statsMap.get(self))];
+    const rows = [await localHealthRow(self, statsMap.get(self))];
     const remoteTargets = remoteFleetTargets(planned, self)
         .map((t) => ({
         name: t.device.name,

package/dist/commands/usage.d.ts

@@ -6,8 +6,9 @@
  *   - codex:  parsed from latest session log's rate_limits event
  *   - kimi:   live Kimi Code /usages API call (cached for 2 minutes)
  *   - droid:  live Factory billing/limits API call (cached for 2 minutes)
- *   - others: marked as "not exposed by CLI" (Gemini, OpenCode, Cursor, etc.
- *     don't publish per-account usage today)
+ *   - grok:   parsed from the latest local usage event
+ *   - cursor: live Cursor usage API call (cached for 2 minutes)
+ *   - others: marked as "not exposed by CLI"
  */
 import type { Command } from 'commander';
 import type { AgentId } from '../lib/types.js';

package/dist/commands/usage.js

@@ -2,14 +2,7 @@ import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import { ALL_AGENT_IDS, AGENTS, getAccountInfo, agentLabel, resolveAgentName, formatAgentError, } from '../lib/agents.js';
 import { listInstalledVersions, getGlobalDefault, getVersionHomePath } from '../lib/versions.js';
-import { formatUsageSection, getUsageInfoForIdentity } from '../lib/usage.js';
-/**
- * Agents whose CLI surfaces usage data we can read today. Kept in sync with the
- * live/last-seen sources `getUsageInfo` dispatches on in `../lib/usage.js`
- * (claude, codex, kimi, droid) — an agent with a usage source but missing here
- * would wrongly print "does not publish usage data" for a signed-in account.
- */
-const USAGE_SUPPORTED = new Set(['claude', 'codex', 'kimi', 'droid']);
+import { agentReportsUsage, formatUsageSection, getUsageInfoForIdentity } from '../lib/usage.js';
 export function registerUsageCommand(program) {
     addHostOption(program.command('usage [agent]'))
         .description('Show rate-limit / quota usage per agent')
@@ -55,7 +48,7 @@ async function collectAgentUsage(agentId) {
     // Plain name — color is applied only at text-render time (formatAgentUsage), so
     // `--json` never emits ANSI escapes in `label` (e.g. under FORCE_COLOR=1).
     const label = AGENTS[agentId].name;
-    if (!USAGE_SUPPORTED.has(agentId)) {
+    if (!agentReportsUsage(agentId)) {
         return { agent: agentId, label, status: 'unsupported' };
     }
     const versions = listInstalledVersions(agentId);

package/dist/commands/webhook.js

@@ -77,9 +77,14 @@ export function registerWebhookCommand(program) {
                 // Durable delivery dedup: replays survive a receiver restart (an
                 // in-memory store would forget every seen delivery on restart).
                 deliveryStore: createFileDeliveryStore(path.join(getRuntimeStateDir(), 'webhook', 'deliveries.json')),
-                onDelivery: (webhook, fired) => {
+                onDelivery: (webhook, fired, handlers) => {
+                    const parts = [];
+                    if (fired.length)
+                        parts.push(`routines ${fired.map((f) => f.jobName).join(', ')}`);
+                    if (handlers.length)
+                        parts.push(`handlers ${handlers.map((h) => h.handlerName).join(', ')}`);
                     console.log(`${new Date().toISOString()} ${webhook.source}:${webhook.event} ` +
-                        `${fired.length ? `fired ${fired.map((f) => f.jobName).join(', ')}` : 'no match'}`);
+                        (parts.length ? `fired ${parts.join('; ')}` : 'no match'));
                 },
             });
             await waitForListening(server);

package/dist/lib/agents.d.ts

@@ -165,7 +165,7 @@ export declare function formatClaudeOrgLabel(orgType: string | null | undefined)
  */
 export declare function accountOrgBadge(info?: Pick<AccountInfo, 'organizationType' | 'organizationName'> | null): string | null;
 /** Agents whose local credential formats expose enough state for account selection. */
-export declare const ACCOUNT_INSPECTION_AGENT_IDS: readonly ["claude", "codex", "gemini", "grok", "antigravity", "kimi", "droid", "opencode"];
+export declare const ACCOUNT_INSPECTION_AGENT_IDS: readonly ["claude", "codex", "gemini", "cursor", "grok", "antigravity", "kimi", "droid", "opencode"];
 /** Whether agents-cli can determine this agent's per-version sign-in state. */
 export declare function supportsAccountInspection(agentId: AgentId): boolean;
 /**
@@ -176,6 +176,36 @@ export declare function supportsAccountInspection(agentId: AgentId): boolean;
 export declare function accountDisplayLabel(info?: Pick<AccountInfo, 'email' | 'accountId' | 'signedIn' | 'organizationType' | 'organizationName'> | null): string;
 /** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;
+/** Where an agent's credential file lives, split into the per-version copy and
+ *  the active/global copy under the real HOME. */
+export interface CredentialPresence {
+    /** The credential file exists inside the passed version home. */
+    perVersion: boolean;
+    /** The credential file exists under the active/global HOME (the one the login
+     *  symlink actually targets), independent of the version home. */
+    active: boolean;
+    /** Whether agents-cli knows WHERE this agent's credential lives at all — i.e.
+     *  the agent has an entry in {@link CREDENTIAL_FILE_SEGMENTS}. When false both
+     *  probes are trivially false because there is nothing to look for, so absence
+     *  is NOT evidence of a logout and no caller may treat it as provable.
+     *
+     *  This is deliberately separate from `supportsAccountInspection`: the two
+     *  registries move independently, and an agent has already been added to the
+     *  inspection set without a credential path (cursor), which without this flag
+     *  produced a false "logged out" critical for every installed version. */
+    knownLocation: boolean;
+}
+/**
+ * File-presence probe for an agent's credential, split by location: whether it
+ * exists in a SPECIFIC version home (`perVersion`) and whether it exists under
+ * the active/global HOME (`active`). A logged-out claim is only *provable* when
+ * BOTH are absent — a version that merely lacks its own copy but shares the
+ * global login is signed in, not logged out. Pure file existence; no decrypt,
+ * no network, no keychain prompt. Agents with no inspectable identity return
+ * `{ perVersion: false, active: false }` and must NEVER yield a provable-logout
+ * claim (the caller gates on {@link supportsAccountInspection}).
+ */
+export declare function credentialPresence(agentId: AgentId, versionHome: string): CredentialPresence;
 /** Decrypted contents of Droid's auth.v2.file (subset we consume). */
 export interface DroidAuthPayload {
     access_token?: string;

package/dist/lib/agents.js

@@ -1014,6 +1014,7 @@ export const ACCOUNT_INSPECTION_AGENT_IDS = [
     'claude',
     'codex',
     'gemini',
+    'cursor',
     'grok',
     'antigravity',
     'kimi',
@@ -1077,6 +1078,60 @@ function resolveAccountCredentialPath(base, ...segments) {
     }
     return null;
 }
+/**
+ * The on-disk credential file(s) each account-inspectable agent authenticates
+ * from, expressed as path segments under a home. Mirrors the exact files
+ * {@link getAccountInfo} reads, so a presence check here matches what a real
+ * launch would find. Each entry is a list of alternatives — the FIRST that
+ * exists counts as present (claude writes either `.claude/.claude.json` under
+ * the shimmed config dir or a home-level `.claude.json`). Agents whose login is
+ * stored only in the OS keychain on some platforms (antigravity, and claude's
+ * token) still expose a credential FILE — the presence of that file is the
+ * signal we key off; its absence on BOTH the per-version home and the active
+ * home is what makes a logged-out claim provable.
+ */
+const CREDENTIAL_FILE_SEGMENTS = {
+    claude: [['.claude', '.claude.json'], ['.claude.json']],
+    codex: [['.codex', 'auth.json']],
+    gemini: [['.gemini', 'google_accounts.json']],
+    grok: [['.grok', 'auth.json']],
+    kimi: [['.kimi-code', 'credentials', 'kimi-code.json']],
+    droid: [['.factory', 'auth.v2.file']],
+    antigravity: [['.gemini', 'antigravity-cli', 'antigravity-oauth-token']],
+    opencode: [['.local', 'share', 'opencode', 'auth.json']],
+};
+/** Whether an agent's credential file exists under a given home. */
+function credentialFileExistsUnder(agentId, home) {
+    const alternatives = CREDENTIAL_FILE_SEGMENTS[agentId];
+    if (!alternatives)
+        return false;
+    for (const segments of alternatives) {
+        const p = path.join(home, ...segments);
+        try {
+            if (fs.existsSync(p))
+                return true;
+        }
+        catch { /* unreadable */ }
+    }
+    return false;
+}
+/**
+ * File-presence probe for an agent's credential, split by location: whether it
+ * exists in a SPECIFIC version home (`perVersion`) and whether it exists under
+ * the active/global HOME (`active`). A logged-out claim is only *provable* when
+ * BOTH are absent — a version that merely lacks its own copy but shares the
+ * global login is signed in, not logged out. Pure file existence; no decrypt,
+ * no network, no keychain prompt. Agents with no inspectable identity return
+ * `{ perVersion: false, active: false }` and must NEVER yield a provable-logout
+ * claim (the caller gates on {@link supportsAccountInspection}).
+ */
+export function credentialPresence(agentId, versionHome) {
+    const realHome = process.env.AGENTS_REAL_HOME || os.homedir();
+    const perVersion = credentialFileExistsUnder(agentId, versionHome);
+    const active = credentialFileExistsUnder(agentId, realHome);
+    const knownLocation = (CREDENTIAL_FILE_SEGMENTS[agentId]?.length ?? 0) > 0;
+    return { perVersion, active, knownLocation };
+}
 /**
  * Factory Droid stores its OAuth credential encrypted at ~/.factory/auth.v2.file
  * (AES-256-GCM, format `ivB64:tagB64:ctB64`) with the 32-byte key base64-stored

package/dist/lib/command-skills.d.ts

@@ -4,6 +4,16 @@
  */
 import type { AgentId } from './types.js';
 export declare function shouldInstallCommandAsSkill(agent: AgentId, version: string): boolean;
+/**
+ * Agents whose native command files serve a separate surface while their CLI
+ * consumes the generated skill form. Keep this registry distinct from
+ * `shouldInstallCommandAsSkill`: these targets need both writes, not a format
+ * replacement.
+ */
+export declare const COMMAND_SKILL_DUAL_WRITE_TARGETS: {
+    cursor: true;
+};
+export declare function shouldAlsoInstallCommandAsSkill(agent: AgentId, version: string): boolean;
 export declare function commandSkillName(commandName: string): string;
 export declare function buildCommandSkillContent(commandName: string, sourcePath: string): string;
 export declare function skillSourceExists(skillName: string, skillSourceDirs: Array<string | null | undefined>): boolean;

package/dist/lib/command-skills.js

@@ -52,6 +52,20 @@ function readSkillCommandMarker(skillMdPath) {
 export function shouldInstallCommandAsSkill(agent, version) {
     return !supports(agent, 'commands', version).ok && supports(agent, 'skills', version).ok;
 }
+/**
+ * Agents whose native command files serve a separate surface while their CLI
+ * consumes the generated skill form. Keep this registry distinct from
+ * `shouldInstallCommandAsSkill`: these targets need both writes, not a format
+ * replacement.
+ */
+export const COMMAND_SKILL_DUAL_WRITE_TARGETS = {
+    cursor: true,
+};
+export function shouldAlsoInstallCommandAsSkill(agent, version) {
+    return COMMAND_SKILL_DUAL_WRITE_TARGETS[agent] === true
+        && supports(agent, 'commands', version).ok
+        && supports(agent, 'skills', version).ok;
+}
 export function commandSkillName(commandName) {
     return commandName;
 }

package/dist/lib/commands.js

@@ -11,11 +11,12 @@ import * as path from 'path';
 import * as yaml from 'yaml';
 import { AGENTS, ensureCommandsDir, agentConfigDirName, resolveAgentName } from './agents.js';
 import { capableAgents, isCapable, supports } from './capabilities.js';
+import { isDirectoryDoc } from './resources.js';
 import { markdownToToml } from './convert.js';
 import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir, getTrashCommandsDir } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions, resolveVersion } from './versions.js';
 import { discoverPlugins } from './plugins.js';
-import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldInstallCommandAsSkill, } from './command-skills.js';
+import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from './command-skills.js';
 import { installGooseCommandToVersion, listGooseCommandsInVersion, gooseCommandMatches, removeGooseCommandFromVersion, } from './goose-commands.js';
 function compareVersions(a, b) {
     const aParts = a.split('.').map((n) => parseInt(n, 10) || 0);
@@ -150,6 +151,8 @@ export function discoverCommands(repoPath) {
         for (const file of fs.readdirSync(commandsDir)) {
             if (file.endsWith('.md')) {
                 const name = file.replace('.md', '');
+                if (isDirectoryDoc('commands', name))
+                    continue;
                 const sourcePath = path.join(commandsDir, file);
                 const metadata = parseCommandMetadata(sourcePath);
                 const validation = validateCommandMetadata(metadata, name);
@@ -211,6 +214,14 @@ export function installCommand(sourcePath, agentId, commandName, method = 'symli
     const agent = AGENTS[agentId];
     ensureCommandsDir(agentId);
     const home = getEffectiveHome(agentId);
+    const installVersion = pinnedVersion ?? listInstalledVersions(agentId)[0] ?? '';
+    const alsoInstallAsSkill = shouldAlsoInstallCommandAsSkill(agentId, installVersion);
+    if (alsoInstallAsSkill) {
+        const installed = installCommandSkillToVersion(path.join(home, agentConfigDirName(agentId)), commandName, sourcePath, [getSkillsDir(), ...getEnabledExtraRepos().map((repo) => path.join(repo.dir, 'skills'))]);
+        if (!installed.success) {
+            return { path: '', method: 'copy', error: installed.error, warnings: validation.warnings };
+        }
+    }
     // Goose: a slash command is a recipe YAML registered in config.yaml, not a
     // native command file under commandsSubdir.
     if (agentId === 'goose') {
@@ -401,6 +412,11 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
             ...getEnabledExtraRepos().map((repo) => path.join(repo.dir, 'skills')),
         ]);
     }
+    if (shouldAlsoInstallCommandAsSkill(agent, version)) {
+        const installed = installCommandSkillToVersion(agentDir, commandName, sourcePath, [getSkillsDir(), ...getEnabledExtraRepos().map((repo) => path.join(repo.dir, 'skills'))]);
+        if (!installed.success)
+            return installed;
+    }
     // Goose: a slash command is a recipe YAML registered in config.yaml, not a
     // native command file. Write the recipe + slash_commands entry.
     if (agent === 'goose') {
@@ -441,6 +457,11 @@ export function removeCommandFromVersion(agent, version, commandName) {
     if (shouldInstallCommandAsSkill(agent, version)) {
         return removeCommandSkillFromVersion(agentDir, commandName);
     }
+    if (shouldAlsoInstallCommandAsSkill(agent, version)) {
+        const removed = removeCommandSkillFromVersion(agentDir, commandName);
+        if (!removed.success)
+            return removed;
+    }
     if (agent === 'goose') {
         const trashDir = path.join(getTrashCommandsDir(), agent, version, commandName);
         return removeGooseCommandFromVersion(versionHome, commandName, trashDir);
@@ -676,7 +697,12 @@ export function listCentralCommands() {
         if (!fs.existsSync(dir))
             continue;
         for (const f of fs.readdirSync(dir).filter((f) => f.endsWith('.md'))) {
-            seen.add(f.replace('.md', ''));
+            const name = f.replace('.md', '');
+            // A directory's README/AGENTS/CLAUDE/GEMINI documents the dir, it is not a
+            // command. Without this the picker offers a name resolveResource refuses.
+            if (isDirectoryDoc('commands', name))
+                continue;
+            seen.add(name);
         }
     }
     return Array.from(seen);

package/dist/lib/daemon.d.ts

@@ -86,6 +86,23 @@ export declare function log(level: string, message: string): void;
  * anchoring failed (logged, non-fatal).
  */
 export declare function anchorDaemonCwd(): string | null;
+/**
+ * Surface, at the daemon's OWN startup, that it was launched from an ephemeral
+ * root that will wedge it if the directory is removed. This is the runtime
+ * companion to the launch-time check in validateDaemonBinary (which only runs
+ * when the daemon is *spawned* via getDaemonLaunch): a direct
+ * `agents __daemon-run` from a temp or worktree build — e.g. a review/verify
+ * checkout under /tmp — never passes through that path, so without this the
+ * wedge risk stays invisible until jobs start ENOENT-ing on their dynamic
+ * imports. Best-effort and non-fatal; the cwd is already handled by
+ * anchorDaemonCwd, but a deleted module root can only be flagged, not repaired.
+ *
+ * `resolveBin` is injectable (defaults to getAgentsBinPath) so the wiring — the
+ * predicate call, the WARN, and the non-fatal guard around a throwing resolver —
+ * is testable. Returns the warning message it logged, or null when the launch
+ * root is stable (or could not be resolved).
+ */
+export declare function warnEphemeralDaemonRoot(resolveBin?: () => string): string | null;
 export declare function runDaemon(): Promise<void>;
 /**
  * Write a launchd plist or systemd unit with owner-only permissions atomically.
@@ -175,6 +192,18 @@ export declare function getAgentsInvocation(subArgs: string[], agentsBin?: strin
     command: string;
     args: string[];
 };
+/**
+ * A daemon binary living under an ephemeral path — a git worktree, or a temp
+ * directory (`/tmp`, `/var/folders`, `/dev/shm`) — is a latent wedge. The daemon
+ * is long-lived but resolves its own job modules by dynamic `import()` rooted at
+ * this entry (getAgentsBinPath → process.argv[1]). If that directory is later
+ * removed (`git worktree remove`, a `/tmp` cleanup, a review/verify checkout
+ * teardown) the running daemon keeps ENOENT-ing on every job it loads —
+ * `anchorDaemonCwd` rescues the cwd, but nothing can re-root a deleted module
+ * tree. Returns a human phrase naming the ephemeral kind, or null for a stable
+ * install path (version home, a global npm prefix, a normal source checkout).
+ */
+export declare function describeEphemeralDaemonRoot(binPath: string): string | null;
 export declare function validateDaemonBinary(binPath: string): {
     warnings: string[];
 };

package/dist/lib/daemon.js

@@ -321,6 +321,39 @@ export function anchorDaemonCwd() {
         return null;
     }
 }
+/**
+ * Surface, at the daemon's OWN startup, that it was launched from an ephemeral
+ * root that will wedge it if the directory is removed. This is the runtime
+ * companion to the launch-time check in validateDaemonBinary (which only runs
+ * when the daemon is *spawned* via getDaemonLaunch): a direct
+ * `agents __daemon-run` from a temp or worktree build — e.g. a review/verify
+ * checkout under /tmp — never passes through that path, so without this the
+ * wedge risk stays invisible until jobs start ENOENT-ing on their dynamic
+ * imports. Best-effort and non-fatal; the cwd is already handled by
+ * anchorDaemonCwd, but a deleted module root can only be flagged, not repaired.
+ *
+ * `resolveBin` is injectable (defaults to getAgentsBinPath) so the wiring — the
+ * predicate call, the WARN, and the non-fatal guard around a throwing resolver —
+ * is testable. Returns the warning message it logged, or null when the launch
+ * root is stable (or could not be resolved).
+ */
+export function warnEphemeralDaemonRoot(resolveBin = getAgentsBinPath) {
+    try {
+        const bin = resolveBin();
+        const ephemeralRoot = describeEphemeralDaemonRoot(bin);
+        if (!ephemeralRoot)
+            return null;
+        const message = `Daemon launched from ${ephemeralRoot} (${bin}); if that directory is removed, ` +
+            `every routine will fail with ENOENT on its module imports. Run the daemon from the ` +
+            `globally installed binary instead (npm i -g @phnx-labs/agents-cli), then restart it.`;
+        log('WARN', message);
+        return message;
+    }
+    catch (err) {
+        log('WARN', `Could not check daemon launch root: ${err.message}`);
+        return null;
+    }
+}
 export async function runDaemon() {
     // Single-instance guard: a direct `agents __daemon-run` (manual, or a
     // service-manager restart racing a live predecessor) must not clobber a
@@ -334,6 +367,7 @@ export async function runDaemon() {
     }
     log('INFO', `Daemon started (PID: ${process.pid})`);
     anchorDaemonCwd();
+    warnEphemeralDaemonRoot();
     // The daemon holds NO Claude credential of its own. Routine runs authenticate
     // exactly like an interactive `agents run`: through the per-account
     // CLAUDE_CONFIG_DIR login on this device (its own auto-refreshing
@@ -880,7 +914,7 @@ ${[launch.command, ...launch.args].map((arg) => `    <string>${xmlEscape(arg)}</
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
-    <string>${daemonNodeBinDir()}:/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${os.homedir()}/.bun/bin</string>
+    <string>${daemonPathValue(agentsBin, ['/usr/local/bin', '/usr/bin', '/bin', '/opt/homebrew/bin', `${os.homedir()}/.bun/bin`])}</string>
   </dict>
 </dict>
 </plist>`;
@@ -909,7 +943,7 @@ Type=simple
 ExecStart=${execStart}
 Restart=always
 RestartSec=10
-Environment=PATH=${daemonNodeBinDir()}:/usr/local/bin:/usr/bin:/bin
+Environment=PATH=${daemonPathValue(agentsBin, ['/usr/local/bin', '/usr/bin', '/bin'])}
 
 [Install]
 WantedBy=default.target`;
@@ -1074,6 +1108,21 @@ export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
 function daemonNodeBinDir() {
     return path.dirname(process.execPath);
 }
+/**
+ * The full PATH value the daemon service manifest pins, in order: the Node runtime
+ * dir (so the shim's shebang and any child resolve the exact installing Node — see
+ * {@link daemonNodeBinDir}), then the directory of the `agents` shim itself, then
+ * the platform's system dirs. The shim's own dir matters because a scheduled
+ * `command` routine shells out to the bare name `agents`
+ * (`/bin/sh -c 'agents watchdog --nudge'`): when the shim lives outside the Node
+ * bin dir — a `~/.local/bin` global install, a separate npm prefix — a PATH
+ * carrying only the Node dir resolves `agents` to nothing and every routine dies
+ * with `exit 127`. Deduped across the whole list, so a Node/shim dir that already
+ * appears among the system dirs (e.g. a `/usr/local/bin` install) never doubles.
+ */
+function daemonPathValue(agentsBin, systemDirs) {
+    return [...new Set([daemonNodeBinDir(), path.dirname(agentsBin), ...systemDirs])].join(':');
+}
 /**
  * Build the argv to relaunch the `agents` CLI with the given subcommand args.
  *
@@ -1091,15 +1140,35 @@ function daemonNodeBinDir() {
 export function getAgentsInvocation(subArgs, agentsBin = getAgentsBinPath()) {
     return getCliLaunch(subArgs, agentsBin);
 }
+/**
+ * A daemon binary living under an ephemeral path — a git worktree, or a temp
+ * directory (`/tmp`, `/var/folders`, `/dev/shm`) — is a latent wedge. The daemon
+ * is long-lived but resolves its own job modules by dynamic `import()` rooted at
+ * this entry (getAgentsBinPath → process.argv[1]). If that directory is later
+ * removed (`git worktree remove`, a `/tmp` cleanup, a review/verify checkout
+ * teardown) the running daemon keeps ENOENT-ing on every job it loads —
+ * `anchorDaemonCwd` rescues the cwd, but nothing can re-root a deleted module
+ * tree. Returns a human phrase naming the ephemeral kind, or null for a stable
+ * install path (version home, a global npm prefix, a normal source checkout).
+ */
+export function describeEphemeralDaemonRoot(binPath) {
+    if (/[/\\]\.agents[/\\]worktrees[/\\]/.test(binPath))
+        return 'a git worktree';
+    if (/^(?:\/private)?\/tmp[/\\]|^(?:\/private)?\/var\/folders[/\\]|^\/dev\/shm[/\\]/.test(binPath)) {
+        return 'a temporary directory';
+    }
+    return null;
+}
 export function validateDaemonBinary(binPath) {
     const warnings = [];
     if (BUN_VIRTUAL_ROOT.test(binPath)) {
         throw new Error(`Refusing to supervise daemon: resolved binary is a bun virtual path (${binPath}). ` +
             `Install agents globally (npm i -g @phnx-labs/agents-cli) and restart.`);
     }
-    if (/[/\\]\.agents[/\\]worktrees[/\\]/.test(binPath)) {
-        warnings.push(`Warning: daemon binary is inside a git worktree (${binPath}). ` +
-            `A worktree deletion will wedge the daemon. Use the globally installed binary instead.`);
+    const ephemeralRoot = describeEphemeralDaemonRoot(binPath);
+    if (ephemeralRoot) {
+        warnings.push(`Warning: daemon binary is inside ${ephemeralRoot} (${binPath}). ` +
+            `Deleting it will wedge the daemon. Use the globally installed binary instead.`);
     }
     if (!fs.existsSync(binPath) && !/\.(c|m)?js$/.test(binPath)) {
         warnings.push(`Warning: daemon binary does not exist on disk (${binPath}).`);
@@ -1117,7 +1186,7 @@ export function startDetached(opts = {}) {
     // and a console-close event tears it down when the launcher exits (#556).
     const child = spawn(command, args, {
         stdio: ['ignore', logFd, logFd],
-        ...backgroundSpawnOptions({ fdStdio: true }),
+        ...backgroundSpawnOptions({ cwd: os.homedir(), fdStdio: true }),
         env: opts.env ?? process.env,
     });
     // A failed spawn (ENOENT/EACCES) emits 'error' asynchronously; without a