agent-tempo 1.0.1

package/dist/cli/daemon.d.ts

@@ -0,0 +1,217 @@
+import { Config } from '../config';
+export declare const DAEMON_PID_PATH: string;
+export declare const DAEMON_LOG_PATH: string;
+/**
+ * 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).
+ */
+export declare const DAEMON_HEARTBEAT_PATH: string;
+/** How often the daemon touches {@link DAEMON_HEARTBEAT_PATH}. */
+export declare const HEARTBEAT_INTERVAL_MS = 60000;
+/**
+ * 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.
+ */
+export declare const HEARTBEAT_STALE_MULTIPLIER = 2;
+export interface DaemonStatus {
+    running: boolean;
+    pid?: number;
+    /**
+     * Milliseconds since the daemon last touched {@link DAEMON_HEARTBEAT_PATH}.
+     * `null` when no heartbeat file exists (fresh daemon hasn't ticked yet, or
+     * pre-heartbeat daemon). `undefined` when the daemon is not running at all.
+     * See {@link HEARTBEAT_STALE_MULTIPLIER} for the staleness threshold.
+     */
+    heartbeatAge?: number | null;
+}
+/**
+ * Check if the daemon is running by reading the PID file and probing the process.
+ * Cleans up stale PID files automatically.
+ */
+export declare function isDaemonRunning(): boolean;
+/**
+ * Get daemon status: running state and PID (if available).
+ */
+export declare function getDaemonStatus(): DaemonStatus;
+/**
+ * @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).
+ */
+export declare function selectOrphans(scanned: DaemonProcessInfo[], trackedPid: number | undefined | ReadonlyArray<number | undefined>): DaemonProcessInfo[];
+/**
+ * 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.
+ */
+export declare function otherProfileHome(): string;
+/**
+ * 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.
+ */
+export declare function getOtherProfilePid(): number | 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.
+ */
+export declare function isOtherProfileLikelyRunning(): boolean;
+/**
+ * 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. */
+export declare const DAEMON_LOCK_PATH: string;
+/**
+ * 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).
+ */
+export declare const STALE_LOCK_MS = 30000;
+/**
+ * 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.
+ */
+export declare const DAEMON_START_TIMEOUT_MS = 30000;
+/** Shape of the JSON persisted inside the start lock. */
+export interface LockFileContent {
+    /** PID of the process that acquired the lock. */
+    pid: number;
+    /** ms-since-epoch when the lock was acquired — used for age-based staleness. */
+    mtime: number;
+}
+/**
+ * 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.
+ */
+export declare function tryAcquireLockFile(lockPath: string, pid?: number, now?: number): boolean;
+/**
+ * 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.
+ */
+export declare function checkLockFileStale(lockPath: string, now?: number): {
+    stale: boolean;
+    reason: string;
+    content: LockFileContent | null;
+};
+export declare function startDaemon(config: Config): Promise<number>;
+/**
+ * Info about a running agent-tempo daemon process discovered via OS process
+ * listing. Returned by {@link scanAgentTempoDaemons}.
+ */
+export interface DaemonProcessInfo {
+    pid: number;
+    /** Full command line as reported by the OS. */
+    commandLine: string;
+}
+/**
+ * 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.
+ */
+export declare function scanAgentTempoDaemons(exec?: (cmd: string, args: readonly string[]) => string, platform?: NodeJS.Platform): DaemonProcessInfo[];
+/**
+ * Options for {@link stopDaemon} — exported for unit tests so we can inject
+ * a stub scanner and killer without spawning real processes. Production
+ * callers should pass no arguments and accept the defaults (real OS scan +
+ * `process.kill`).
+ *
+ * @internal
+ */
+export interface StopDaemonOpts {
+    /** Process scanner — defaults to {@link scanAgentTempoDaemons}. */
+    scan?: () => DaemonProcessInfo[];
+    /** Signal sender — defaults to `process.kill`. */
+    killer?: (pid: number, signal?: NodeJS.Signals | number) => void;
+    /** Platform override — defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+    /**
+     * Cross-profile coexistence probe — defaults to
+     * {@link isOtherProfileLikelyRunning}. Tests stub this so the zombie
+     * reaper logic can be exercised without depending on disk state of the
+     * developer's home dir.
+     */
+    isOtherProfileLikelyRunning?: () => boolean;
+    /**
+     * Cross-profile PID lookup — defaults to {@link getOtherProfilePid}.
+     * Tests stub it for the same reason as `isOtherProfileLikelyRunning`.
+     */
+    getOtherProfilePid?: () => number | undefined;
+}
+/**
+ * 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.
+ */
+export declare function stopDaemon(opts?: StopDaemonOpts): boolean;