@telora/daemon 0.19.27 → 0.19.31

package/dist/worker-pidfile.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Persisted team-lead pid registry -- closes the hard-kill orphan gap.
+ *
+ * Team leads are spawned detached (their own process group; focus-executor
+ * spawnCrashIsolated). The daemon's graceful shutdown reaps them via
+ * reapWorkerFleet, but a HARD kill (stop --force, a stop timeout, or an
+ * external `kill -9` on the daemon PID) tears the daemon down WITHOUT running
+ * that reap -- and because the leads are detached, they survive and orphan to
+ * init.
+ *
+ * The in-memory activeTeams map dies with the daemon, so a separate process
+ * (the `telora-daemon stop` CLI, or the NEXT daemon at boot) has no way to find
+ * those orphans. This module persists each live lead pid to a small JSON file
+ * in the global state dir so:
+ *
+ *   - the CLI stop --force / timeout path can group-kill (`kill(-pid)`) every
+ *     recorded lead after it SIGKILLs the daemon, and
+ *   - the next daemon boot can reap any lead left alive by a prior hard kill
+ *     (the only closure available for a bare external `kill -9 <daemon>`, which
+ *     no in-process handler can intercept).
+ *
+ * All file ops are best-effort and never throw: a missing/corrupt file yields
+ * an empty fleet, and a write failure is swallowed (orphan prevention is a
+ * backstop, never a blocker on the spawn/exit hot path). One daemon per host
+ * (PID lock) makes read-modify-write races a non-issue.
+ */
+/** A persisted live team lead: its pid and a human label for reap logging. */
+export interface WorkerPidEntry {
+    pid: number;
+    label: string;
+}
+/** Resolve the worker pidfile path in the global state dir (~/.telora/). */
+export declare function resolveWorkerPidfilePath(): string;
+/**
+ * Read the persisted worker fleet. Tolerant: a missing, unreadable, or
+ * malformed file returns []. Only well-formed { pid, label } entries with a
+ * real pid (> 1) survive parsing.
+ */
+export declare function readWorkerPidfile(path?: string): WorkerPidEntry[];
+/**
+ * Record a live team lead. Idempotent per pid (a re-record updates the label).
+ * No-op for an invalid/init pid (<= 1).
+ */
+export declare function recordWorkerPid(pid: number, label: string, path?: string): void;
+/** Remove a lead pid on its exit. No-op when absent. */
+export declare function removeWorkerPid(pid: number, path?: string): void;
+/** Delete the pidfile entirely (graceful shutdown clears it after reaping). */
+export declare function clearWorkerPidfile(path?: string): void;
+/** Injectable seams for {@link reapPersistedWorkerGroups} (test without procs). */
+export interface ReapPersistedDeps {
+    /** Signal sender. Defaults to process.kill. */
+    kill?: (pid: number, signal: NodeJS.Signals) => void;
+    /** Liveness probe. Defaults to a kill(pid, 0) existence check. */
+    isAlive?: (pid: number) => boolean;
+}
+/** Outcome of a persisted-fleet reap, for logging + tests. */
+export interface ReapPersistedResult {
+    /** Pids that were alive and got a group SIGKILL. */
+    reaped: number[];
+    /** Pids skipped because they were already dead (or invalid). */
+    skipped: number[];
+}
+/**
+ * Group-SIGKILL every still-alive persisted lead. Because leads are spawned
+ * detached (own group, pgid == lead pid), `kill(-pid)` reaps the lead AND any
+ * host children it sub-spawned in one signal; a bare-pid fallback covers a lead
+ * that somehow is not a group leader. Pure over the injected seams. Never throws
+ * (a vanished process is success).
+ */
+export declare function reapPersistedWorkerGroups(entries: WorkerPidEntry[], deps?: ReapPersistedDeps): ReapPersistedResult;
+/**
+ * Read + reap the persisted fleet, then clear the file. Used by the CLI hard
+ * stop (after SIGKILLing the daemon) and by the next daemon boot (to reap leads
+ * a prior hard kill orphaned). Returns the reap result for logging.
+ */
+export declare function reapAndClearWorkerPidfile(path?: string, deps?: ReapPersistedDeps): ReapPersistedResult;
+//# sourceMappingURL=worker-pidfile.d.ts.map

package/dist/worker-pidfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-pidfile.d.ts","sourceRoot":"","sources":["../src/worker-pidfile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,4EAA4E;AAC5E,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,MAAmC,GAAG,cAAc,EAAE,CAoB7F;AAWD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAmC,GAAG,IAAI,CAK3G;AAED,wDAAwD;AACxD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,MAAmC,GAAG,IAAI,CAS5F;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,MAAmC,GAAG,IAAI,CAMlF;AAED,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC;IACrD,kEAAkE;IAClE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACpC;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,gEAAgE;IAChE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAYD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,cAAc,EAAE,EACzB,IAAI,GAAE,iBAAsB,GAC3B,mBAAmB,CA4BrB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,GAAE,MAAmC,EACzC,IAAI,GAAE,iBAAsB,GAC3B,mBAAmB,CAKrB"}

package/dist/worker-pidfile.js

@@ -0,0 +1,161 @@
+/**
+ * Persisted team-lead pid registry -- closes the hard-kill orphan gap.
+ *
+ * Team leads are spawned detached (their own process group; focus-executor
+ * spawnCrashIsolated). The daemon's graceful shutdown reaps them via
+ * reapWorkerFleet, but a HARD kill (stop --force, a stop timeout, or an
+ * external `kill -9` on the daemon PID) tears the daemon down WITHOUT running
+ * that reap -- and because the leads are detached, they survive and orphan to
+ * init.
+ *
+ * The in-memory activeTeams map dies with the daemon, so a separate process
+ * (the `telora-daemon stop` CLI, or the NEXT daemon at boot) has no way to find
+ * those orphans. This module persists each live lead pid to a small JSON file
+ * in the global state dir so:
+ *
+ *   - the CLI stop --force / timeout path can group-kill (`kill(-pid)`) every
+ *     recorded lead after it SIGKILLs the daemon, and
+ *   - the next daemon boot can reap any lead left alive by a prior hard kill
+ *     (the only closure available for a bare external `kill -9 <daemon>`, which
+ *     no in-process handler can intercept).
+ *
+ * All file ops are best-effort and never throw: a missing/corrupt file yields
+ * an empty fleet, and a write failure is swallowed (orphan prevention is a
+ * backstop, never a blocker on the spawn/exit hot path). One daemon per host
+ * (PID lock) makes read-modify-write races a non-issue.
+ */
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { resolveGlobalStateDir } from './daemon-process.js';
+/** Resolve the worker pidfile path in the global state dir (~/.telora/). */
+export function resolveWorkerPidfilePath() {
+    return resolve(resolveGlobalStateDir(), 'daemon.workers.json');
+}
+/**
+ * Read the persisted worker fleet. Tolerant: a missing, unreadable, or
+ * malformed file returns []. Only well-formed { pid, label } entries with a
+ * real pid (> 1) survive parsing.
+ */
+export function readWorkerPidfile(path = resolveWorkerPidfilePath()) {
+    if (!existsSync(path))
+        return [];
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!Array.isArray(raw))
+            return [];
+        const out = [];
+        for (const e of raw) {
+            if (typeof e === 'object' && e !== null &&
+                typeof e.pid === 'number' &&
+                e.pid > 1) {
+                const entry = e;
+                out.push({ pid: entry.pid, label: typeof entry.label === 'string' ? entry.label : 'unknown' });
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/** Best-effort write of the fleet. Swallows all errors. */
+function writeWorkerPidfile(entries, path) {
+    try {
+        writeFileSync(path, JSON.stringify(entries), { mode: 0o600 });
+    }
+    catch {
+        // Orphan prevention is a backstop -- never fail a spawn/exit on this.
+    }
+}
+/**
+ * Record a live team lead. Idempotent per pid (a re-record updates the label).
+ * No-op for an invalid/init pid (<= 1).
+ */
+export function recordWorkerPid(pid, label, path = resolveWorkerPidfilePath()) {
+    if (!Number.isInteger(pid) || pid <= 1)
+        return;
+    const entries = readWorkerPidfile(path).filter((e) => e.pid !== pid);
+    entries.push({ pid, label });
+    writeWorkerPidfile(entries, path);
+}
+/** Remove a lead pid on its exit. No-op when absent. */
+export function removeWorkerPid(pid, path = resolveWorkerPidfilePath()) {
+    const entries = readWorkerPidfile(path);
+    const next = entries.filter((e) => e.pid !== pid);
+    if (next.length === entries.length)
+        return;
+    if (next.length === 0) {
+        clearWorkerPidfile(path);
+        return;
+    }
+    writeWorkerPidfile(next, path);
+}
+/** Delete the pidfile entirely (graceful shutdown clears it after reaping). */
+export function clearWorkerPidfile(path = resolveWorkerPidfilePath()) {
+    try {
+        if (existsSync(path))
+            unlinkSync(path);
+    }
+    catch {
+        // Best effort.
+    }
+}
+/** Default liveness: kill(pid, 0) throws iff the process does not exist. */
+function defaultIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Group-SIGKILL every still-alive persisted lead. Because leads are spawned
+ * detached (own group, pgid == lead pid), `kill(-pid)` reaps the lead AND any
+ * host children it sub-spawned in one signal; a bare-pid fallback covers a lead
+ * that somehow is not a group leader. Pure over the injected seams. Never throws
+ * (a vanished process is success).
+ */
+export function reapPersistedWorkerGroups(entries, deps = {}) {
+    const kill = deps.kill ?? ((pid, signal) => { process.kill(pid, signal); });
+    const isAlive = deps.isAlive ?? defaultIsAlive;
+    const result = { reaped: [], skipped: [] };
+    for (const entry of entries) {
+        const { pid } = entry;
+        if (!Number.isInteger(pid) || pid <= 1) {
+            result.skipped.push(pid);
+            continue;
+        }
+        if (!isAlive(pid)) {
+            result.skipped.push(pid);
+            continue;
+        }
+        // Group-first (detached lead => pgid == pid), bare-pid fallback.
+        try {
+            kill(-pid, 'SIGKILL');
+        }
+        catch {
+            try {
+                kill(pid, 'SIGKILL');
+            }
+            catch {
+                // Already gone.
+            }
+        }
+        result.reaped.push(pid);
+    }
+    return result;
+}
+/**
+ * Read + reap the persisted fleet, then clear the file. Used by the CLI hard
+ * stop (after SIGKILLing the daemon) and by the next daemon boot (to reap leads
+ * a prior hard kill orphaned). Returns the reap result for logging.
+ */
+export function reapAndClearWorkerPidfile(path = resolveWorkerPidfilePath(), deps = {}) {
+    const entries = readWorkerPidfile(path);
+    const result = reapPersistedWorkerGroups(entries, deps);
+    clearWorkerPidfile(path);
+    return result;
+}
+//# sourceMappingURL=worker-pidfile.js.map

package/dist/worker-pidfile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-pidfile.js","sourceRoot":"","sources":["../src/worker-pidfile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAQ5D,4EAA4E;AAC5E,MAAM,UAAU,wBAAwB;IACtC,OAAO,OAAO,CAAC,qBAAqB,EAAE,EAAE,qBAAqB,CAAC,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,wBAAwB,EAAE;IACzE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAY,CAAC;QAC/D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;QACnC,MAAM,GAAG,GAAqB,EAAE,CAAC;QACjC,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;YACpB,IACE,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI;gBACnC,OAAQ,CAAoB,CAAC,GAAG,KAAK,QAAQ;gBAC5C,CAAoB,CAAC,GAAG,GAAG,CAAC,EAC7B,CAAC;gBACD,MAAM,KAAK,GAAG,CAAmB,CAAC;gBAClC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;YACjG,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,2DAA2D;AAC3D,SAAS,kBAAkB,CAAC,OAAyB,EAAE,IAAY;IACjE,IAAI,CAAC;QACH,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;IACxE,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,KAAa,EAAE,OAAe,wBAAwB,EAAE;IACnG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO;IAC/C,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IACrE,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7B,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,OAAe,wBAAwB,EAAE;IACpF,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IAClD,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM;QAAE,OAAO;IAC3C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO;IACT,CAAC;IACD,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB,CAAC,OAAe,wBAAwB,EAAE;IAC1E,IAAI,CAAC;QACH,IAAI,UAAU,CAAC,IAAI,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;AACH,CAAC;AAkBD,4EAA4E;AAC5E,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAyB,EACzB,OAA0B,EAAE;IAE5B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,cAAc,CAAC;IAC/C,MAAM,MAAM,GAAwB,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAEhE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;YACvC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QACD,iEAAiE;QACjE,IAAI,CAAC;YACH,IAAI,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC;gBACH,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YACvB,CAAC;YAAC,MAAM,CAAC;gBACP,gBAAgB;YAClB,CAAC;QACH,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAe,wBAAwB,EAAE,EACzC,OAA0B,EAAE;IAE5B,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,yBAAyB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACxD,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telora/daemon",
-  "version": "0.19.27",
+  "version": "0.19.31",
   "description": "Agent orchestration daemon for Telora - spawns and manages Claude Code instances",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
   "//testRunner": "Uses Node.js built-in test runner (node:test) via tsx for TypeScript support. The root package uses Vitest; this is a deliberate choice for the daemon package to avoid framework dependencies. See src/__tests__/ for test files.",
   "dependencies": {
     "@telora/daemon": "^0.19.2",
-    "@telora/daemon-core": "^0.2.56",
+    "@telora/daemon-core": "^0.2.57",
     "@telora/mcp-products": "^0.22.88",
     "commander": "^14.0.3",
     "yaml": "^2.4.0",