agent-tempo 1.0.1

package/dist/cli/daemon.js

@@ -0,0 +1,632 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DAEMON_START_TIMEOUT_MS = exports.STALE_LOCK_MS = exports.DAEMON_LOCK_PATH = exports.HEARTBEAT_STALE_MULTIPLIER = exports.HEARTBEAT_INTERVAL_MS = exports.DAEMON_HEARTBEAT_PATH = exports.DAEMON_LOG_PATH = exports.DAEMON_PID_PATH = void 0;
+exports.isDaemonRunning = isDaemonRunning;
+exports.getDaemonStatus = getDaemonStatus;
+exports.selectOrphans = selectOrphans;
+exports.otherProfileHome = otherProfileHome;
+exports.getOtherProfilePid = getOtherProfilePid;
+exports.isOtherProfileLikelyRunning = isOtherProfileLikelyRunning;
+exports.tryAcquireLockFile = tryAcquireLockFile;
+exports.checkLockFileStale = checkLockFileStale;
+exports.startDaemon = startDaemon;
+exports.scanAgentTempoDaemons = scanAgentTempoDaemons;
+exports.stopDaemon = stopDaemon;
+/**
+ * Daemon process management utilities.
+ *
+ * The daemon runs Temporal workers in a detached background process,
+ * replacing the per-session workers. MCP sessions become pure clients.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const os_1 = require("os");
+const config_1 = require("../config");
+const log = (...args) => console.error('[agent-tempo:daemon]', ...args);
+exports.DAEMON_PID_PATH = path.join(config_1.AGENT_TEMPO_HOME, 'daemon.pid');
+exports.DAEMON_LOG_PATH = path.join(config_1.AGENT_TEMPO_HOME, 'daemon.log');
+/**
+ * Path to the daemon heartbeat file. The running daemon touches this file
+ * on a {@link HEARTBEAT_INTERVAL_MS} cadence so `daemon status` can
+ * distinguish "pid is alive AND main loop is serving" from "pid is alive
+ * but something hung" (#157 diagnostic improvement).
+ */
+exports.DAEMON_HEARTBEAT_PATH = path.join(config_1.AGENT_TEMPO_HOME, 'daemon.heartbeat');
+/** How often the daemon touches {@link DAEMON_HEARTBEAT_PATH}. */
+exports.HEARTBEAT_INTERVAL_MS = 60_000;
+/**
+ * Multiplier applied to {@link HEARTBEAT_INTERVAL_MS} to decide whether a
+ * heartbeat is stale. A 2x buffer tolerates one missed tick (brief GC pause,
+ * synchronous activity) without false-flagging a healthy daemon.
+ */
+exports.HEARTBEAT_STALE_MULTIPLIER = 2;
+/** Entry point for the daemon process (compiled JS). */
+const DAEMON_ENTRY_PATH = path.resolve(__dirname, '..', 'daemon.js');
+/**
+ * Probe whether a PID refers to a live process using `kill(pid, 0)`.
+ *
+ * EPERM is reported on Windows for foreign (UAC-isolated) processes and
+ * must be treated as "alive" — we just can't signal it. Anything else
+ * (ESRCH, ENOENT, invalid-pid) means the process is gone.
+ */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * Check if the daemon is running by reading the PID file and probing the process.
+ * Cleans up stale PID files automatically.
+ */
+function isDaemonRunning() {
+    return getDaemonStatus().running;
+}
+/**
+ * Get daemon status: running state and PID (if available).
+ */
+function getDaemonStatus() {
+    if (!fs.existsSync(exports.DAEMON_PID_PATH)) {
+        return { running: false };
+    }
+    let pid;
+    try {
+        pid = parseInt(fs.readFileSync(exports.DAEMON_PID_PATH, 'utf8').trim(), 10);
+        if (isNaN(pid)) {
+            fs.unlinkSync(exports.DAEMON_PID_PATH);
+            return { running: false };
+        }
+    }
+    catch {
+        return { running: false };
+    }
+    if (isPidAlive(pid)) {
+        return { running: true, pid, heartbeatAge: readHeartbeatAge() };
+    }
+    // Process is dead — clean up stale PID file.
+    try {
+        fs.unlinkSync(exports.DAEMON_PID_PATH);
+    }
+    catch { /* ignore */ }
+    return { running: false };
+}
+/**
+ * Read the heartbeat file and return milliseconds since its mtime, or `null`
+ * if the file doesn't exist. Used by {@link getDaemonStatus} when the daemon
+ * is running — see the `heartbeatAge` field on {@link DaemonStatus}.
+ *
+ * Any other read/stat error is treated as "unknown" (`null`) rather than
+ * propagating — `daemon status` should degrade to silent-unknown rather than
+ * crash on an unexpected filesystem condition.
+ */
+function readHeartbeatAge() {
+    try {
+        const mtimeMs = fs.statSync(exports.DAEMON_HEARTBEAT_PATH).mtimeMs;
+        const age = Date.now() - mtimeMs;
+        return age >= 0 ? age : 0;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @internal — exported for unit testing {@link DAEMON_CMDLINE_RE} edge cases
+ * without needing to spin up a real child process. Filters a scanner result
+ * to the "orphan" subset: matching processes that aren't tracked by any
+ * known PID file. Used by `daemon start`'s pre-flight check (#157 PR B).
+ *
+ * Accepts a single tracked PID (existing call shape) OR an array of known
+ * PIDs (ADR 0014 §5.6 — the dev profile passes the prod profile's PID
+ * here too so dev + prod daemons can coexist on the same machine without
+ * either misclassifying the other as an orphan).
+ */
+function selectOrphans(scanned, trackedPid) {
+    if (trackedPid === undefined)
+        return scanned;
+    if (Array.isArray(trackedPid)) {
+        const known = new Set(trackedPid.filter((p) => typeof p === 'number'));
+        if (known.size === 0)
+            return scanned;
+        return scanned.filter((p) => !known.has(p.pid));
+    }
+    return scanned.filter((p) => p.pid !== trackedPid);
+}
+/**
+ * Resolve the OPPOSITE profile's home directory. Used by cross-profile
+ * coexistence checks (ADR 0014 §5.6). Returns the prod home in dev mode
+ * and the dev home in prod mode.
+ *
+ * Exported so tests can verify the swap logic without fixture homedirs.
+ */
+function otherProfileHome() {
+    const base = (0, config_1.isDevMode)() ? config_1.PROD_HOME_DIR_NAME : config_1.DEV_HOME_DIR_NAME;
+    return path.join((0, os_1.homedir)(), base);
+}
+/**
+ * Return the live PID (if any) of the OPPOSITE profile's daemon.
+ *
+ * In dev mode, this returns the prod daemon's PID; in prod mode, the dev
+ * daemon's PID. Used by orphan detection to keep dev and prod daemons
+ * from misclassifying each other (ADR 0014 §5.6 — "they naturally
+ * coexist"). Returns `undefined` when no PID file exists, the contents
+ * are unparseable, or the recorded process is dead.
+ *
+ * Exported for unit testing — can be stubbed alongside `getDaemonStatus`
+ * in `evaluateStartPreflight` tests.
+ */
+function getOtherProfilePid() {
+    const otherPidPath = path.join(otherProfileHome(), 'daemon.pid');
+    if (!fs.existsSync(otherPidPath))
+        return undefined;
+    try {
+        const pid = parseInt(fs.readFileSync(otherPidPath, 'utf8').trim(), 10);
+        if (Number.isNaN(pid))
+            return undefined;
+        return isPidAlive(pid) ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Best-effort signal that the OPPOSITE profile may have a running daemon
+ * even if we couldn't pin a PID. Used by `stopDaemon` to suppress the
+ * zombie reaper when there's a non-trivial chance of cross-profile
+ * collateral damage (ADR 0014 §5.6).
+ *
+ * Returns true when either:
+ *   - `daemon.pid` exists in the other profile's home AND contains a
+ *     parseable, live PID (the strict case, also reported by
+ *     {@link getOtherProfilePid}).
+ *   - `daemon.port` exists in the other profile's home (weak signal:
+ *     the file is written on daemon HTTP listener startup; it may
+ *     linger across an uncleaned crash, but that's exactly the case
+ *     where conservative behaviour matters).
+ *
+ * The heuristic deliberately errs on the side of NOT reaping. A false
+ * positive (port file exists, daemon long dead) costs zombie cleanup;
+ * a false negative (process killed because we missed evidence) costs
+ * the user their other profile's daemon.
+ */
+function isOtherProfileLikelyRunning() {
+    if (getOtherProfilePid() !== undefined)
+        return true;
+    const otherPortPath = path.join(otherProfileHome(), 'daemon.port');
+    return fs.existsSync(otherPortPath);
+}
+/**
+ * Start the daemon process. If already running, returns the existing PID.
+ *
+ * The daemon is spawned as a detached child process with stdout/stderr
+ * redirected to a log file. Config is passed via environment variables.
+ */
+/** Lock file path for preventing concurrent daemon starts. */
+exports.DAEMON_LOCK_PATH = exports.DAEMON_PID_PATH + '.lock';
+/**
+ * How long a start lock can sit on disk before we treat it as abandoned
+ * regardless of whether the recorded PID appears alive. Daemon startup
+ * should never take this long; longer values just delay recovery after a
+ * crashed starter (see issue #182).
+ */
+exports.STALE_LOCK_MS = 30_000;
+/**
+ * Timeout for waiting on another starter's PID file — generous window for
+ * cold-start slack on fresh installs (npm-global, uncompiled native deps).
+ * Bumped from 10s per researcher recommendation for issue #182.
+ */
+exports.DAEMON_START_TIMEOUT_MS = 30_000;
+/**
+ * Attempt to atomically create the start lock with {pid, mtime} contents.
+ *
+ * Returns `true` on success, `false` if the lock already exists. Any other
+ * error (EACCES, ENOSPC, …) propagates. Exported for unit testing the
+ * acquire path without spawning a real daemon.
+ */
+function tryAcquireLockFile(lockPath, pid = process.pid, now = Date.now()) {
+    try {
+        const content = { pid, mtime: now };
+        // `wx` = atomic create-or-fail with EEXIST on conflict. Combined with
+        // writeFileSync, this writes the content in the same syscall sequence,
+        // so a racing reader never observes a zero-byte lock.
+        fs.writeFileSync(lockPath, JSON.stringify(content), { flag: 'wx' });
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return false;
+        throw err;
+    }
+}
+/**
+ * Inspect a start lock and decide whether it's abandoned.
+ *
+ * A lock is stale when any of:
+ *  - the file is missing (treat as stale so callers retry immediately)
+ *  - the contents are malformed (not JSON, missing pid/mtime)
+ *  - mtime is older than {@link STALE_LOCK_MS}
+ *  - `process.kill(pid, 0)` reports ESRCH (or anything other than EPERM)
+ *
+ * EPERM on the PID probe is treated as "alive" to match
+ * {@link getDaemonStatus} — on Windows, UAC-isolated foreign processes
+ * return EPERM for a running PID, so we must not interpret it as dead.
+ *
+ * Exported for unit testing.
+ */
+function checkLockFileStale(lockPath, now = Date.now()) {
+    let raw;
+    try {
+        raw = fs.readFileSync(lockPath, 'utf8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT') {
+            return { stale: true, reason: 'lock file missing', content: null };
+        }
+        return { stale: true, reason: `lock file unreadable (${code ?? 'unknown'})`, content: null };
+    }
+    let content = null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.pid === 'number' && typeof parsed?.mtime === 'number') {
+            content = { pid: parsed.pid, mtime: parsed.mtime };
+        }
+    }
+    catch {
+        // fall through — malformed
+    }
+    if (!content) {
+        const preview = raw.length > 80 ? raw.slice(0, 80) + '…' : raw;
+        return {
+            stale: true,
+            reason: `malformed lock content: ${JSON.stringify(preview)}`,
+            content: null,
+        };
+    }
+    const ageMs = now - content.mtime;
+    if (ageMs > exports.STALE_LOCK_MS) {
+        return {
+            stale: true,
+            reason: `mtime ${Math.round(ageMs / 1000)}s old (>${exports.STALE_LOCK_MS / 1000}s threshold)`,
+            content,
+        };
+    }
+    if (isPidAlive(content.pid)) {
+        return {
+            stale: false,
+            reason: `pid ${content.pid} alive, mtime ${ageMs}ms old`,
+            content,
+        };
+    }
+    return {
+        stale: true,
+        reason: `pid ${content.pid} not alive`,
+        content,
+    };
+}
+/**
+ * Wait for the PID file to appear and contain a valid, live PID.
+ * Used both by the spawning process and by processes waiting on the lock.
+ */
+async function waitForDaemonPid(timeoutMs) {
+    const POLL_MS = 200;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await new Promise(resolve => setTimeout(resolve, POLL_MS));
+        if (fs.existsSync(exports.DAEMON_PID_PATH)) {
+            const status = getDaemonStatus();
+            if (status.running && status.pid) {
+                return status.pid;
+            }
+        }
+    }
+    throw new Error('Daemon did not start within timeout. Check logs: ' + exports.DAEMON_LOG_PATH);
+}
+async function startDaemon(config) {
+    // Check if already running
+    const status = getDaemonStatus();
+    if (status.running && status.pid) {
+        log(`Daemon already running (pid ${status.pid})`);
+        return status.pid;
+    }
+    // Ensure daemon directory exists
+    fs.mkdirSync(config_1.AGENT_TEMPO_HOME, { recursive: true });
+    // Acquire exclusive start lock. If another process holds the lock, decide
+    // whether to wait for it (live starter) or auto-repair it (stale from a
+    // crashed prior attempt — issue #182).
+    let acquired = tryAcquireLockFile(exports.DAEMON_LOCK_PATH);
+    if (!acquired) {
+        const state = checkLockFileStale(exports.DAEMON_LOCK_PATH);
+        if (state.stale) {
+            // Loud log — silent self-healing hides bugs. If this fires repeatedly
+            // it's a signal that daemon startup is crashing before PID-file write.
+            log(`⚠️  Stale daemon start lock detected — auto-repairing (${state.reason})`);
+            if (state.content) {
+                log(`⚠️  Lock contents: pid=${state.content.pid}, mtime=${new Date(state.content.mtime).toISOString()}`);
+            }
+            log('⚠️  If this repeats, inspect ' + exports.DAEMON_LOG_PATH + ' for startup crashes.');
+            try {
+                fs.unlinkSync(exports.DAEMON_LOCK_PATH);
+            }
+            catch { /* already gone */ }
+            // Retry once. If we still lose, another process won the recovery race —
+            // fall through to the wait path.
+            acquired = tryAcquireLockFile(exports.DAEMON_LOCK_PATH);
+            if (!acquired) {
+                log('Lost stale-lock recovery race to another starter — waiting for its daemon...');
+                return waitForDaemonPid(exports.DAEMON_START_TIMEOUT_MS);
+            }
+        }
+        else {
+            // Healthy concurrent starter — wait for its PID file.
+            log(`Another process is starting the daemon (${state.reason}) — waiting...`);
+            return waitForDaemonPid(exports.DAEMON_START_TIMEOUT_MS);
+        }
+    }
+    try {
+        // Re-check after acquiring lock — daemon may have started between our
+        // initial check and lock acquisition
+        const recheck = getDaemonStatus();
+        if (recheck.running && recheck.pid) {
+            log(`Daemon already running (pid ${recheck.pid})`);
+            return recheck.pid;
+        }
+        // Open log file for daemon stdout/stderr
+        const logFd = fs.openSync(exports.DAEMON_LOG_PATH, 'a');
+        // Pass Temporal config to daemon via environment variables
+        const env = {
+            ...process.env,
+            [config_1.ENV.TEMPORAL_ADDRESS]: config.temporalAddress,
+            [config_1.ENV.TEMPORAL_NAMESPACE]: config.temporalNamespace,
+            [config_1.ENV.TASK_QUEUE]: config.taskQueue,
+        };
+        if (config.temporalApiKey)
+            env[config_1.ENV.TEMPORAL_API_KEY] = config.temporalApiKey;
+        if (config.temporalTlsCertPath)
+            env[config_1.ENV.TEMPORAL_TLS_CERT_PATH] = config.temporalTlsCertPath;
+        if (config.temporalTlsKeyPath)
+            env[config_1.ENV.TEMPORAL_TLS_KEY_PATH] = config.temporalTlsKeyPath;
+        const child = (0, child_process_1.spawn)(process.execPath, [DAEMON_ENTRY_PATH], {
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+            env,
+        });
+        child.unref();
+        fs.closeSync(logFd);
+        log(`Spawned daemon process (pid ${child.pid})`);
+        // Wait for PID file to appear (daemon writes it on startup). Generous
+        // timeout for cold-start slack on fresh installs (#182).
+        return await waitForDaemonPid(exports.DAEMON_START_TIMEOUT_MS);
+    }
+    finally {
+        // Release lock. We no longer hold an fd — writeFileSync closed it for us.
+        try {
+            fs.unlinkSync(exports.DAEMON_LOCK_PATH);
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Matches a node process running the compiled daemon entry — both global-install
+ * paths (`...\agent-tempo\dist\daemon.js`) and dev-tree paths. Narrow enough to
+ * exclude unrelated `node` processes on the system; never force-kills based on
+ * this match alone (self-healing is gated by explicit user action per #157).
+ */
+const DAEMON_CMDLINE_RE = /\bnode(?:\.exe)?\b.*\bagent-tempo\b.*[\\/]dist[\\/]daemon\.js\b/i;
+/**
+ * Shell out to the platform process list and return any matching daemon
+ * processes. Hand-rolled per-platform to avoid a new dependency:
+ *  - Windows: PowerShell `Get-CimInstance Win32_Process` (modern, robust) with a
+ *    `tasklist` fallback for environments without PowerShell on PATH
+ *  - POSIX: `ps -eo pid,command` (portable across macOS + Linux)
+ *
+ * Returns `[]` on any scanner failure — this is a best-effort observability
+ * helper, not a correctness guarantee. Errors are swallowed so a broken
+ * scanner can't itself take down `daemon status`.
+ *
+ * Exported for testing with a stubbed executor.
+ */
+function scanAgentTempoDaemons(exec = (cmd, args) => (0, child_process_1.execFileSync)(cmd, args, { encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }), platform = process.platform) {
+    try {
+        if (platform === 'win32') {
+            return scanWindows(exec);
+        }
+        return scanPosix(exec);
+    }
+    catch {
+        return [];
+    }
+}
+/** Windows scan via PowerShell → CSV. Falls back to `wmic` if PowerShell is missing. */
+function scanWindows(exec) {
+    // PowerShell CSV output puts ProcessId in col 0, CommandLine in col 1.
+    // `-NoProfile` avoids loading user profile scripts that would slow startup.
+    const ps = "Get-CimInstance -ClassName Win32_Process -Filter \"Name='node.exe'\" | " +
+        'Select-Object ProcessId,CommandLine | ConvertTo-Csv -NoTypeInformation';
+    try {
+        const out = exec('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps]);
+        return parseCsvMatches(out);
+    }
+    catch {
+        // Fall through to wmic — legacy, still present on most Windows SKUs.
+        const out = exec('wmic', ['process', 'where', "name='node.exe'", 'get', 'ProcessId,CommandLine', '/format:csv']);
+        return parseCsvMatches(out);
+    }
+}
+/** POSIX scan via `ps -eo pid,command`. */
+function scanPosix(exec) {
+    const out = exec('ps', ['-eo', 'pid,command']);
+    const matches = [];
+    for (const line of out.split('\n')) {
+        // Skip header row ("  PID COMMAND").
+        const trimmed = line.trim();
+        if (!trimmed || /^pid\b/i.test(trimmed))
+            continue;
+        const m = /^(\d+)\s+(.+)$/.exec(trimmed);
+        if (!m)
+            continue;
+        const pid = parseInt(m[1], 10);
+        const commandLine = m[2];
+        if (!isNaN(pid) && DAEMON_CMDLINE_RE.test(commandLine) && pid !== process.pid) {
+            matches.push({ pid, commandLine });
+        }
+    }
+    return matches;
+}
+/** Parse CSV output from PowerShell's ConvertTo-Csv or wmic and filter matches. */
+function parseCsvMatches(csv) {
+    const matches = [];
+    for (const line of csv.split(/\r?\n/)) {
+        // CSV rows: quoted fields separated by commas. Both PowerShell and wmic
+        // emit a header row + blank lines. Keep the parser permissive — we only
+        // need ProcessId (numeric) and a line that contains the daemon signature.
+        if (!line || /^"?ProcessId\b/i.test(line) || /^Node,Command/i.test(line))
+            continue;
+        // Find a plausible ProcessId (column order differs between PS and wmic:
+        // PS puts it first, wmic puts it last). Take the first numeric token
+        // that isn't obviously part of the command line (i.e. inside a long
+        // quoted path). In practice both formats surface the pid as a bare or
+        // single-quoted token unadjacent to path-like text.
+        const pidMatch = line.match(/(?:^|,)"?(\d+)"?(?=,|$)/);
+        if (!pidMatch)
+            continue;
+        const pid = parseInt(pidMatch[1], 10);
+        if (isNaN(pid) || pid === process.pid)
+            continue;
+        // Match the daemon signature against the FULL LINE. CSV quoting (both
+        // PowerShell's doubled-quote `""` form and backslash-escape variants)
+        // doesn't hide the literal `node.exe` and `agent-tempo\dist\daemon.js`
+        // substrings from a substring regex — splitting into quoted fields would
+        // wrongly separate `node.exe` from `agent-tempo\dist\daemon.js` when
+        // they're in different CSV columns (e.g. `"node.exe" "...\daemon.js"`).
+        if (DAEMON_CMDLINE_RE.test(line)) {
+            matches.push({ pid, commandLine: line });
+        }
+    }
+    return matches;
+}
+/**
+ * Send the platform-appropriate stop signal to a single daemon PID.
+ * Swallows errors — the process may have already exited, or be UAC-isolated
+ * on Windows. Returns `true` if `process.kill` succeeded, `false` otherwise.
+ */
+function killDaemonPid(pid, killer = process.kill.bind(process), platform = process.platform) {
+    try {
+        if (platform === 'win32') {
+            // Windows doesn't support SIGTERM — just kill the process.
+            killer(pid);
+        }
+        else {
+            killer(pid, 'SIGTERM');
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Stop the daemon process by sending SIGTERM (or killing on Windows). In
+ * addition to the daemon tracked by the PID file, this also reaps any
+ * **zombie** daemons — `node dist/daemon.js` processes detected by
+ * {@link scanAgentTempoDaemons} that the PID file doesn't know about.
+ *
+ * Why reap zombies on every stop? When a prior daemon loses PID-file
+ * tracking (crashed `daemon stop`, manual PID-file delete, surviving across
+ * a `down --destroy` from before this fix), the orphan keeps polling
+ * Temporal task queues and executing activities — sometimes with stale code
+ * from before the most recent rebuild. That has caused real user-visible
+ * incidents where activities ran the pre-fix `resume: true` spawn path
+ * because a zombie daemon held the cached pre-rebuild code in memory.
+ *
+ * Returns `true` if at least one process (tracked or zombie) was stopped.
+ */
+function stopDaemon(opts = {}) {
+    const scan = opts.scan ?? scanAgentTempoDaemons;
+    const killer = opts.killer ?? process.kill.bind(process);
+    const platform = opts.platform ?? process.platform;
+    const otherLikelyRunning = opts.isOtherProfileLikelyRunning ?? isOtherProfileLikelyRunning;
+    const otherPidLookup = opts.getOtherProfilePid ?? getOtherProfilePid;
+    const status = getDaemonStatus();
+    let stopped = false;
+    // Kill the tracked daemon first (if any). We do this even if `kill` fails —
+    // the PID file is invariant we own, so we always clean it up.
+    if (status.running && status.pid !== undefined) {
+        killDaemonPid(status.pid, killer, platform);
+        try {
+            fs.unlinkSync(exports.DAEMON_PID_PATH);
+        }
+        catch { /* ignore */ }
+        stopped = true;
+    }
+    // Now reap any zombies. `selectOrphans` filters the scan to "everything
+    // except the PIDs we know about", so we don't double-signal the tracked
+    // daemon (harmless but cleaner).
+    //
+    // ADR 0014 §5.6 — when cross-profile coexistence is plausible (the
+    // OPPOSITE profile shows any sign of running: PID file, port file),
+    // suppress the zombie reaper entirely. The reaper is a #157 safety
+    // net for the SINGLE-profile case where a crashed daemon left an
+    // untracked node process behind. With dev + prod coexisting on the
+    // same machine, the reaper would happily kill the other profile's
+    // daemon — losing the user's prod state because they ran
+    // `--dev daemon stop`. The trade-off is acceptable: an actual zombie
+    // can be reaped later (manual `kill <pid>` based on the printed
+    // command line), but a wrongly-killed prod daemon costs the user
+    // their state.
+    let zombies = [];
+    if (otherLikelyRunning()) {
+        log('cross-profile coexistence detected — skipping zombie reaper to avoid touching the other profile (ADR 0014 §5.6)');
+    }
+    else {
+        try {
+            zombies = selectOrphans(scan(), [status.pid, otherPidLookup()]);
+        }
+        catch {
+            // Scanner failures are non-fatal — we already did the primary stop above.
+            zombies = [];
+        }
+    }
+    for (const z of zombies) {
+        if (killDaemonPid(z.pid, killer, platform)) {
+            stopped = true;
+        }
+    }
+    return stopped;
+}

package/dist/cli/dashboard-command.d.ts

@@ -0,0 +1,20 @@
+import { CliOverrides } from '../config';
+export interface DashboardCommandArgs extends CliOverrides {
+    /** Override the daemon port (defaults to the port-file value). */
+    port?: number;
+    /** Override the daemon bind address (defaults to 127.0.0.1). */
+    bind?: string;
+    /** When true, print the URL but don't launch the browser. */
+    noOpen?: boolean;
+    /** Mint a single-use pairing token + show QR for cross-device. */
+    pair?: boolean;
+    /** Bearer to include on the pair-create POST. */
+    bearer?: string;
+    /** Machine-parseable output (single-line JSON). */
+    json?: boolean;
+}
+/**
+ * Public entry point — invoked by the CLI dispatcher. Returns void;
+ * exits the process with code 1 on error, 0 on success.
+ */
+export declare function dashboardCommand(args: DashboardCommandArgs): Promise<void>;