crosscheck-mcp 0.2.26 → 0.2.28

package/dist/embed.d.cts

@@ -1,3 +1,60 @@
+/**
+ * A record of which engine processes are alive, and what they are RUNNING.
+ *
+ * WHY
+ * An engine process started weeks earlier was found still serving a pre-fix
+ * build while reporting the version on disk — so `crosscheck doctor` said
+ * "up to date" and the user kept hitting a bug that had already been fixed.
+ * Thirty-six such processes were once killed across twelve trees. Nothing
+ * reaps them and nothing notices them.
+ *
+ * The version a process REPORTS must be the one it LOADED, not the one
+ * currently installed. That is the whole point of writing it down at boot: a
+ * long-lived process cannot tell you what it is running if it re-reads the
+ * answer from disk every time you ask.
+ *
+ * WHY IT ONLY REPORTS
+ * It would be easy to kill anything older than N hours on startup. That is
+ * exactly what not to do here:
+ *   - the CLI and the desktop app share this directory, so "ours" is not a
+ *     safe inference from a name or a path;
+ *   - a long-running process may be mid-panel, and panels cost real money;
+ *   - a pid is reused after a process dies, so killing by a recorded pid can
+ *     kill something unrelated that happens to have inherited the number.
+ * So this module writes, reads, and prunes records of processes that are
+ * already gone. Deciding to kill a live one is the operator's, with the
+ * command printed for them.
+ */
+interface ProcRecord {
+    pid: number;
+    /** The engine version this process LOADED — not what is on disk now. */
+    version: string;
+    /** Epoch ms at boot. */
+    startedAt: number;
+    /** Parent pid at boot: the host that spawned us (Claude Code, a shell). */
+    ppid: number;
+    /** This process's session id, so a stale process can be tied to its rows. */
+    sessionId: string;
+}
+interface ProcStatus extends ProcRecord {
+    alive: boolean;
+    /** True when alive and running a version other than the one installed. */
+    outdated: boolean;
+    ageMs: number;
+}
+/** Is a pid still running? `kill(pid, 0)` signals nothing and throws ESRCH
+ *  when the process is gone — EPERM means alive but owned by someone else,
+ *  which still counts as alive. */
+declare function isAlive(pid: number): boolean;
+/**
+ * Every recorded process, with liveness. Records for dead pids are PRUNED as
+ * a side effect — they are the safe half of cleanup: the process is already
+ * gone, so deleting its note cannot hurt anything.
+ */
+declare function listProcesses(installedVersion: string, env?: NodeJS.ProcessEnv, now?: number): ProcStatus[];
+/** Directory path, for messages that tell an operator where to look. */
+declare function processRegistryPath(env?: NodeJS.ProcessEnv): string;
+
 /** Default model per provider — matches Python's `build_providers()`. */
 declare const DEFAULT_MODELS: Readonly<Record<string, string>>;
 /**
@@ -202,4 +259,4 @@ declare const __test_internals: {
     vaultId: typeof vaultId;
 };
 
-export { DEFAULT_EXCLUDED_PROVIDERS, DEFAULT_FALLBACKS, DEFAULT_MODELS, type EmbeddedEngine, type EmbeddedEngineOptions, type EngineEvent, type EngineEventSink, type EventUsage, KEY_ENV as __KEY_ENV, MODEL_ENV as __MODEL_ENV, __test_internals, createEmbeddedEngine };
+export { DEFAULT_EXCLUDED_PROVIDERS, DEFAULT_FALLBACKS, DEFAULT_MODELS, type EmbeddedEngine, type EmbeddedEngineOptions, type EngineEvent, type EngineEventSink, type EventUsage, type ProcRecord, type ProcStatus, KEY_ENV as __KEY_ENV, MODEL_ENV as __MODEL_ENV, __test_internals, createEmbeddedEngine, isAlive, listProcesses, processRegistryPath };

package/dist/embed.d.ts

@@ -1,3 +1,60 @@
+/**
+ * A record of which engine processes are alive, and what they are RUNNING.
+ *
+ * WHY
+ * An engine process started weeks earlier was found still serving a pre-fix
+ * build while reporting the version on disk — so `crosscheck doctor` said
+ * "up to date" and the user kept hitting a bug that had already been fixed.
+ * Thirty-six such processes were once killed across twelve trees. Nothing
+ * reaps them and nothing notices them.
+ *
+ * The version a process REPORTS must be the one it LOADED, not the one
+ * currently installed. That is the whole point of writing it down at boot: a
+ * long-lived process cannot tell you what it is running if it re-reads the
+ * answer from disk every time you ask.
+ *
+ * WHY IT ONLY REPORTS
+ * It would be easy to kill anything older than N hours on startup. That is
+ * exactly what not to do here:
+ *   - the CLI and the desktop app share this directory, so "ours" is not a
+ *     safe inference from a name or a path;
+ *   - a long-running process may be mid-panel, and panels cost real money;
+ *   - a pid is reused after a process dies, so killing by a recorded pid can
+ *     kill something unrelated that happens to have inherited the number.
+ * So this module writes, reads, and prunes records of processes that are
+ * already gone. Deciding to kill a live one is the operator's, with the
+ * command printed for them.
+ */
+interface ProcRecord {
+    pid: number;
+    /** The engine version this process LOADED — not what is on disk now. */
+    version: string;
+    /** Epoch ms at boot. */
+    startedAt: number;
+    /** Parent pid at boot: the host that spawned us (Claude Code, a shell). */
+    ppid: number;
+    /** This process's session id, so a stale process can be tied to its rows. */
+    sessionId: string;
+}
+interface ProcStatus extends ProcRecord {
+    alive: boolean;
+    /** True when alive and running a version other than the one installed. */
+    outdated: boolean;
+    ageMs: number;
+}
+/** Is a pid still running? `kill(pid, 0)` signals nothing and throws ESRCH
+ *  when the process is gone — EPERM means alive but owned by someone else,
+ *  which still counts as alive. */
+declare function isAlive(pid: number): boolean;
+/**
+ * Every recorded process, with liveness. Records for dead pids are PRUNED as
+ * a side effect — they are the safe half of cleanup: the process is already
+ * gone, so deleting its note cannot hurt anything.
+ */
+declare function listProcesses(installedVersion: string, env?: NodeJS.ProcessEnv, now?: number): ProcStatus[];
+/** Directory path, for messages that tell an operator where to look. */
+declare function processRegistryPath(env?: NodeJS.ProcessEnv): string;
+
 /** Default model per provider — matches Python's `build_providers()`. */
 declare const DEFAULT_MODELS: Readonly<Record<string, string>>;
 /**
@@ -202,4 +259,4 @@ declare const __test_internals: {
     vaultId: typeof vaultId;
 };
 
-export { DEFAULT_EXCLUDED_PROVIDERS, DEFAULT_FALLBACKS, DEFAULT_MODELS, type EmbeddedEngine, type EmbeddedEngineOptions, type EngineEvent, type EngineEventSink, type EventUsage, KEY_ENV as __KEY_ENV, MODEL_ENV as __MODEL_ENV, __test_internals, createEmbeddedEngine };
+export { DEFAULT_EXCLUDED_PROVIDERS, DEFAULT_FALLBACKS, DEFAULT_MODELS, type EmbeddedEngine, type EmbeddedEngineOptions, type EngineEvent, type EngineEventSink, type EventUsage, type ProcRecord, type ProcStatus, KEY_ENV as __KEY_ENV, MODEL_ENV as __MODEL_ENV, __test_internals, createEmbeddedEngine, isAlive, listProcesses, processRegistryPath };