@phnx-labs/agents-cli 1.20.88 → 1.20.89

package/dist/commands/routines.js

@@ -70,6 +70,8 @@ function fireConditionLabel(job) {
             job.trigger.action ? `action=${job.trigger.action}` : null,
             job.trigger.teamKey ? `team=${job.trigger.teamKey}` : null,
             job.trigger.label ? `label=${job.trigger.label}` : null,
+            job.trigger.stateTo ? `stateTo=${job.trigger.stateTo}` : null,
+            job.trigger.stateFrom ? `stateFrom=${job.trigger.stateFrom}` : null,
         ].filter(Boolean).join(', ');
         return `on linear:${job.trigger.event}${filters ? ` (${filters})` : ''}`;
     }
@@ -261,6 +263,10 @@ function parseRoutineTrigger(options) {
             trigger.teamKey = options.teamKey;
         if (typeof options.label === 'string')
             trigger.label = options.label;
+        if (typeof options.stateTo === 'string')
+            trigger.stateTo = options.stateTo;
+        if (typeof options.stateFrom === 'string')
+            trigger.stateFrom = options.stateFrom;
         return trigger;
     }
     throw new Error('--on source must be github or linear');
@@ -591,6 +597,8 @@ export function registerRoutinesCommands(program) {
         .option('--action <name>', 'Webhook action filter for --on triggers (GitHub: labeled/opened; Linear: update)')
         .option('--team-key <key>', 'Linear team key filter for --on linear:<event> (e.g. RUSH)')
         .option('--label <name>', 'Label filter for --on triggers (GitHub label name or Linear issue label)')
+        .option('--state-to <name>', 'Linear current-state filter for --on linear:<event> (e.g. Plan)')
+        .option('--state-from <name>', 'Linear previous-state filter for --on linear:<event> (e.g. Triage)')
         .option('--end-at <iso>', 'Stop firing on or after this ISO 8601 timestamp (e.g., "2026-12-31T23:59:00Z"); routine auto-disables.')
         .option('--disabled', 'Create the routine but keep it paused (enable later with resume)')
         .option('--resume <sessionId>', 'At fire time, resume this existing session id (via `agents run <agent> --resume`) instead of starting fresh — the actual session reopens with full context and the prompt becomes its next turn. Powers self-scheduled wake-ups (e.g. /hibernate). Requires --agent claude or codex; runs un-sandboxed (the session store lives in the real home, not the job overlay).')
@@ -884,12 +892,26 @@ export function registerRoutinesCommands(program) {
     routinesCmd
         .command('edit [name]')
         .description('Open a routine in $EDITOR. Creates a new YAML template if the routine does not exist.')
-        .action(async (name) => {
+        .option('--state-to <name>', 'Update the Linear current-state filter before opening the editor')
+        .option('--state-from <name>', 'Update the Linear previous-state filter before opening the editor')
+        .action(async (name, options) => {
         if (!name) {
             name = await pickJob('Select job to edit', undefined, ['agents routines edit <name>']) ?? undefined;
             if (!name)
                 return;
         }
+        const existing = readJob(name);
+        if (existing && (options.stateTo !== undefined || options.stateFrom !== undefined)) {
+            if (!existing.trigger || existing.trigger.type !== 'linear_event') {
+                console.error(chalk.red(`'${name}' does not have a Linear trigger; --state-to/--state-from only apply to linear triggers`));
+                process.exit(1);
+            }
+            if (options.stateTo !== undefined)
+                existing.trigger.stateTo = options.stateTo || undefined;
+            if (options.stateFrom !== undefined)
+                existing.trigger.stateFrom = options.stateFrom || undefined;
+            writeJob(existing);
+        }
         const jobPath = getJobPath(name);
         if (!jobPath) {
             // Job doesn't exist - create a new one

package/dist/commands/secrets-rotate-passphrase.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `agents secrets rotate-passphrase` — rotate the encrypted file store's
+ * machine-local master passphrase (RUSH-1975).
+ *
+ * Re-encrypts every `<item>.enc` under a freshly generated key and rewrites the
+ * 0600 key file in place, atomically: the new store is staged, verified
+ * (round-trip + count), fsync'd, then swapped by directory rename, so a crash
+ * leaves the old store intact and readable. Headless-safe and Linux-first — the
+ * remediation path for a compromised passphrase (RUSH-1968), where the two
+ * supported alternatives are unacceptable (a hand-rolled non-atomic script, or
+ * export-to-plaintext which is the exposure being fixed).
+ *
+ * Dry-run by default, matching `import-keyring`; `--commit` performs the swap.
+ */
+import type { Command } from 'commander';
+/** Register `agents secrets rotate-passphrase` on the parent secrets Command. */
+export declare function registerSecretsRotatePassphraseCommand(secrets: Command): void;

package/dist/commands/secrets-rotate-passphrase.js

@@ -0,0 +1,96 @@
+/**
+ * `agents secrets rotate-passphrase` — rotate the encrypted file store's
+ * machine-local master passphrase (RUSH-1975).
+ *
+ * Re-encrypts every `<item>.enc` under a freshly generated key and rewrites the
+ * 0600 key file in place, atomically: the new store is staged, verified
+ * (round-trip + count), fsync'd, then swapped by directory rename, so a crash
+ * leaves the old store intact and readable. Headless-safe and Linux-first — the
+ * remediation path for a compromised passphrase (RUSH-1968), where the two
+ * supported alternatives are unacceptable (a hand-rolled non-atomic script, or
+ * export-to-plaintext which is the exposure being fixed).
+ *
+ * Dry-run by default, matching `import-keyring`; `--commit` performs the swap.
+ */
+import chalk from 'chalk';
+import { machinePassphraseExists, rotatePassphrase } from '../lib/secrets/filestore.js';
+import { agentStatus } from '../lib/secrets/agent.js';
+/** Register `agents secrets rotate-passphrase` on the parent secrets Command. */
+export function registerSecretsRotatePassphraseCommand(secrets) {
+    secrets
+        .command('rotate-passphrase')
+        .description('Re-key the encrypted file store under a new machine-local passphrase (atomic, headless-safe). Dry-run by default.')
+        .option('--commit', 'Perform the rotation (default is dry-run reporting only)')
+        .option('--dry-run', 'Report bundle count and round-trip result without re-keying (the default). Still heals an interrupted rotation — that is the one thing it writes.')
+        .option('--force', 'Override the safety refusals (held broker unlocks, or a passphrase exported in the environment)')
+        .addHelpText('after', `
+Rotates the auto-provisioned file-store key at ~/.agents/.secrets-key/passphrase:
+decrypts every item under the current key, re-encrypts under a new one, verifies
+every item round-trips, then swaps the store and key file atomically. A crash
+before the swap leaves the old store readable with the old key; a crash inside the
+swap self-heals on the next rotate-passphrase run (not on an ordinary get). No
+plaintext secret value or passphrase is ever written to disk, argv, or a log.
+
+Examples:
+  # Report what would rotate (no writes)
+  agents secrets rotate-passphrase
+
+  # Perform the rotation
+  agents secrets rotate-passphrase --commit`)
+        .action(async (opts) => {
+        try {
+            if (opts.commit && opts.dryRun) {
+                throw new Error('--commit and --dry-run are mutually exclusive.');
+            }
+            const dryRun = !opts.commit;
+            if (!machinePassphraseExists()) {
+                throw new Error('No machine-local passphrase is provisioned on this box, so there is nothing to rotate. ' +
+                    'This command re-keys the file store\'s auto-provisioned key at ~/.agents/.secrets-key/passphrase.');
+            }
+            // Guard 1: refuse while the secrets-agent holds live unlocks (macOS), so a
+            // concurrent read cannot land against a half-swapped store. --force overrides.
+            if (!dryRun && !opts.force) {
+                const held = await agentStatus();
+                if (held.length > 0) {
+                    throw new Error(`The secrets-agent is holding ${held.length} unlocked bundle(s) (${held.map((e) => e.name).join(', ')}). ` +
+                        'Lock them first (`agents secrets lock --all`) so no concurrent read races the rotation, or pass --force.');
+                }
+            }
+            // Guard 2: a passphrase exported in the environment shadows the on-disk key
+            // file with a now-stale value after the rotation, breaking every read. This
+            // is the exact RUSH-1968 footgun — refuse the commit and point at the fix.
+            if (!dryRun && !opts.force && (process.env.AGENTS_SECRETS_PASSPHRASE ?? '').length > 0) {
+                throw new Error('AGENTS_SECRETS_PASSPHRASE is set in this environment; it would shadow the rotated key file ' +
+                    'with a stale value and break every read. Unset it (this is the RUSH-1968 fix) before rotating, or pass --force.');
+            }
+            const report = rotatePassphrase({ dryRun });
+            console.log(`${chalk.bold(String(report.bundleCount))} item(s) decrypt under the current key and ` +
+                `${report.roundTripOk ? chalk.green('round-trip cleanly') : chalk.red('failed to round-trip')} under a new key.`);
+            if (report.skipped.length > 0) {
+                console.log(chalk.gray(`skipped ${report.skipped.length} orphan file(s) (not re-keyed):`));
+                for (const s of report.skipped)
+                    console.log(chalk.gray(`  - ${s}`));
+            }
+            if (report.dryRun) {
+                if (report.recoveredInterruptedRotation) {
+                    // Be precise: this run DID write. Recovery is deliberately not gated on
+                    // --commit, because healing is how a crashed store becomes readable
+                    // again without re-keying it.
+                    console.log(chalk.yellow('Recovered an interrupted rotation: the store was healed back to a single ' +
+                        'readable state. That is the only thing this dry run wrote — no re-keying happened.'));
+                }
+                else {
+                    console.log(chalk.gray('Dry-run: nothing written.'));
+                }
+                console.log(chalk.gray(`Pass --commit to re-encrypt the store and swap the key file (${report.keyFilePath}).`));
+                return;
+            }
+            console.log(chalk.green(`Rotated: re-encrypted ${report.bundleCount} item(s) and rewrote ${report.keyFilePath} (mode 0600).`));
+            console.log(chalk.gray('The previous key and ciphertext were removed. Any process still holding the old passphrase in its environment must be restarted.'));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/secrets.js

@@ -38,6 +38,7 @@ import { getVaultSession, vaultExists } from '../lib/secrets/vault.js';
 import { registerSecretsSyncCommands } from './secrets-sync.js';
 import { registerSecretsMigrateAclCommand } from './secrets-migrate.js';
 import { registerSecretsImportKeyringCommand } from './secrets-import.js';
+import { registerSecretsRotatePassphraseCommand } from './secrets-rotate-passphrase.js';
 /** Prompt the user for a secret value with masked input. Requires an interactive TTY. */
 async function promptForSecret(message) {
     if (!isInteractiveTerminal()) {
@@ -2419,6 +2420,7 @@ Examples:
     registerSecretsSyncCommands(cmd);
     registerSecretsMigrateAclCommand(cmd);
     registerSecretsImportKeyringCommand(cmd);
+    registerSecretsRotatePassphraseCommand(cmd);
 }
 /** Validate a prompt-policy value, throwing a clear message on a bad one (the
  * caller's try/catch renders it and exits). Accepts the legacy `biometry` /

package/dist/commands/sessions.d.ts

@@ -136,11 +136,17 @@ export declare function linkCwdCell(s: Pick<SessionMeta, 'cwd' | '_remote'>, lab
  * (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 declare function serializeActiveSessionsForJson(sessions: ActiveSession[]): Array<ActiveSession & {
+export declare function serializeActiveSessionsForJson(sessions: ActiveSession[]): Array<Omit<ActiveSession, 'viewingIn'> & {
     ticketId: string | null;
     project: string | null;
     prLink: string | null;
+    viewingIn: string | null;
 }>;
 /**
  * Compact owner display for the `--active` owner column: the local-part of a

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;

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/commands.js

@@ -11,6 +11,7 @@ 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';
@@ -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);
@@ -694,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
@@ -1106,15 +1140,35 @@ function daemonPathValue(agentsBin, systemDirs) {
 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}).`);
@@ -1132,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

package/dist/lib/events.d.ts

@@ -13,7 +13,7 @@
  */
 import { type ActorKind } from './actor.js';
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.unlocked' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.unlocked' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'webhook.received' | 'webhook.authorized' | 'webhook.rejected' | 'webhook.matched' | 'webhook.fired' | 'webhook.handler.start' | 'webhook.handler.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
 export declare function levelFor(event: EventType): EventLevel;
 export interface EventMeta {
     ts: string;

package/dist/lib/factory/snapshot.d.ts

@@ -0,0 +1,78 @@
+import { type ActiveSession } from '../session/active.js';
+import { serializeActiveSessionsForJson } from '../../commands/sessions.js';
+import { readAuthHealthCache, type AuthVerdict } from '../auth-health.js';
+import { readStatsCache } from '../devices/stats-cache.js';
+export declare const FACTORY_PROJECTS: readonly [{
+    readonly name: "Prix";
+    readonly repo: "phnx-labs/prix";
+}, {
+    readonly name: "Rush App";
+    readonly repo: "phnx-labs/rush";
+}, {
+    readonly name: "Rush CLI";
+    readonly repo: "phnx-labs/rush-cli";
+}, {
+    readonly name: "Agents CLI";
+    readonly repo: "phnx-labs/agents-cli";
+}, {
+    readonly name: "Linear CLI";
+    readonly repo: "phnx-labs/linear-cli";
+}];
+export interface FactoryConfig {
+    source: 'default' | 'file';
+    ceiling: number;
+    max_dispatch_per_tick: number;
+    per_project: Record<string, {
+        weight: number;
+        cap: number;
+    }>;
+    idle_boxes: string[];
+    digest: {
+        times: string[];
+        tz: string;
+    };
+}
+export interface FactorySnapshot {
+    generatedAt: string;
+    sessions: ReturnType<typeof serializeActiveSessionsForJson>;
+    queues: Record<string, {
+        todo: number;
+        inProgress: number;
+        blocked: number;
+    }>;
+    prs: Array<{
+        repo: string;
+        number: number;
+        ci: string;
+        review: string;
+        mergeable: string;
+    }>;
+    devices: Array<{
+        name: string;
+        load: number | null;
+        idle: boolean;
+    }>;
+    recentRuns: Array<{
+        routine: string;
+        status: string;
+        durationMs: number | null;
+    }>;
+    auth: {
+        claude: AuthVerdict | null;
+    };
+    config: FactoryConfig;
+}
+export interface SnapshotDependencies {
+    home: string;
+    now: () => Date;
+    activeSessions: () => Promise<ActiveSession[]>;
+    run: (file: string, args: string[]) => Promise<string>;
+    readAuth: () => ReturnType<typeof readAuthHealthCache>;
+    readDeviceStats: () => ReturnType<typeof readStatsCache>;
+}
+export declare function readFactoryConfig(home: string): FactoryConfig;
+export declare function queueCounts(todoPayload: unknown, openPayload: unknown): FactorySnapshot['queues'][string];
+export declare function parsePullRequests(repo: string, payload: unknown): FactorySnapshot['prs'];
+export declare function parseDevices(payload: unknown, cached?: ReturnType<typeof readStatsCache>): FactorySnapshot['devices'];
+export declare function readRecentRuns(home: string, limit?: number): FactorySnapshot['recentRuns'];
+export declare function buildFactorySnapshot(overrides?: Partial<SnapshotDependencies>): Promise<FactorySnapshot>;