@telora/daemon 0.22.144 → 0.22.160

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

@@ -17,31 +17,89 @@ export interface WorkerPidEntry {
     startIdentity?: string;
     /** Epoch ms the entry was recorded. */
     recordedAt?: number;
+    /**
+     * A RESERVATION: a lead this daemon is about to spawn, written BEFORE the
+     * child exists so the window between `spawn()` and the pid write is not a
+     * hole in the record. `pid` is PENDING_PID until the real one lands.
+     *
+     * A reservation is never signalled (there is no pid to signal) and never
+     * discarded by a reap: it is the one state that means "a process may exist
+     * and we cannot name it", which every reader must treat as unprovable.
+     */
+    pending?: true;
+    /**
+     * The daemon instance that made a reservation (shell/daemon-instance.ts
+     * `daemonInstanceId`). Only meaningful with `pending`.
+     */
+    reservedBy?: string;
 }
+/** The placeholder pid a reservation carries until the real one is recorded. */
+export declare const PENDING_PID = 0;
 /** 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.
+ * Read the persisted fleet, DISTINGUISHING an absent record from an unreadable
+ * one. Returns null when the file exists but could not be read or parsed as a
+ * fleet -- an EACCES, a truncated write, a hand-edit, anything that is not an
+ * array of entries.
+ *
+ * That distinction is the whole point. The tolerant read below collapses both
+ * into [], and a caller asking "was a lead recorded for this session?" then
+ * reads a corrupt file as PROOF that nothing was spawned -- which is how a live
+ * team's session row gets closed. An absent file is real evidence (no lead was
+ * reserved); an unreadable one is not evidence at all.
+ *
+ * A malformed ELEMENT inside a well-formed array is still dropped: that is one
+ * unusable record, not an unreadable file.
+ */
+export declare function readWorkerPidfileStrict(path?: string): WorkerPidEntry[] | null;
+/**
+ * Read the persisted worker fleet, tolerantly: a missing, unreadable, or
+ * malformed file returns []. Kept for the REAP callers, whose worst case on an
+ * unreadable file is that they signal nothing. A caller that would treat [] as
+ * proof of absence must use {@link readWorkerPidfileStrict} instead.
  */
 export declare function readWorkerPidfile(path?: string): WorkerPidEntry[];
+/**
+ * The whole file, reservations included. Only for readers that reason ABOUT
+ * reservations -- the retention pass and the by-session index. A caller that
+ * wants pids wants {@link readWorkerPidfile}.
+ */
+export declare function readWorkerPidfileWithReservations(path?: string): WorkerPidEntry[];
 /**
  * Record a live team lead with its ownership record (focus, session, start
  * identity). Idempotent per pid (a re-record replaces the entry). No-op for an
  * invalid/init pid (<= 1).
  */
-export declare function recordWorkerProcess(entry: WorkerPidEntry, path?: string): void;
+export declare function recordWorkerProcess(entry: WorkerPidEntry, path?: string): boolean;
+/**
+ * Reserve a lead record BEFORE the process is spawned.
+ *
+ * `launchLeadProcess` used to spawn first and record after, so a hard kill (or
+ * a failed write) in between left a LIVE detached lead with no record anywhere
+ * -- and a reader that takes "no record" for "nothing spawned" then closes that
+ * team's session row. Reserving first removes the window: the record exists
+ * before the process can, and the caller REFUSES the spawn when this returns
+ * false, so a live lead this host cannot name is never created.
+ */
+export declare function reserveLeadRecord(reservation: {
+    label: string;
+    sessionId: string;
+    focusId?: string;
+    reservedBy: string;
+}, path?: string): boolean;
+/** Drop a reservation whose spawn never produced a process. */
+export declare function releaseLeadReservation(sessionId: 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. */
+    /** Liveness probe. Defaults to a kill(pid, 0) existence check (EPERM counts as alive). */
     isAlive?: (pid: number) => boolean;
+    /** True while any non-zombie member of the lead's process GROUP is alive. */
+    isGroupAlive?: (pgid: number) => boolean;
     /** Live process start identity. Defaults to /proc (null off Linux or for a gone pid). */
     readStartIdentity?: (pid: number) => string | null;
 }
@@ -49,8 +107,21 @@ export interface ReapPersistedDeps {
 export interface ReapPersistedResult {
     /** Pids that were alive and got a group SIGKILL. */
     reaped: number[];
-    /** Pids skipped because they were already dead (or invalid). */
+    /** Pids skipped because they were already dead, reserved, or identity-mismatched. */
     skipped: number[];
+    /**
+     * Pids that were ALIVE and could not be signalled (EPERM -- another user's
+     * process holding our recorded number, or a group we may not touch). They
+     * were not reaped, and saying so is the difference between a record that is
+     * safe to drop and one that is not.
+     */
+    unsignalled: number[];
+    /**
+     * Pids that were ALIVE and whose identity could not be VERIFIED as the lead we
+     * recorded (no identity recorded, or none readable now). They are not signalled
+     * -- a SIGKILL there could end an unrelated process -- and their records are kept.
+     */
+    unverified: number[];
 }
 /**
  * Group-SIGKILL every still-alive persisted lead. Because leads are spawned
@@ -61,9 +132,54 @@ export interface ReapPersistedResult {
  */
 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.
+ * True when this recorded lead is STILL RUNNING and still the process that was
+ * recorded -- alive, and with a start identity that has not changed under it.
+ *
+ * A pid whose start identity no longer matches was recycled: the recorded lead
+ * is gone and an unrelated process now holds its number.
+ */
+export declare function recordedLeadStillRunning(entry: WorkerPidEntry, deps?: ReapPersistedDeps): boolean;
+/**
+ * Read + reap the persisted fleet, then RETAIN whatever it could not confirm
+ * gone. Used by the CLI hard stop (after SIGKILLing the daemon) and by the next
+ * daemon boot (to reap leads a prior hard kill orphaned).
+ *
+ * It used to clear the file unconditionally, which threw away the record of
+ * exactly the processes the reap FAILED to end -- a kill that raised EPERM, or
+ * a group that outlived SIGKILL. Those survivors are precisely what the next
+ * reader needs to know about: crash recovery runs after this and must not close
+ * a session row whose team is still running, and with the file cleared it had no
+ * way to tell. Retaining until CONFIRMED GONE is also the rule the one-shot
+ * ownership records already follow.
+ *
+ * Returns the reap result for logging.
  */
 export declare function reapAndClearWorkerPidfile(path?: string, deps?: ReapPersistedDeps): ReapPersistedResult;
+/**
+ * Clear the pidfile ONLY when nothing it records survives.
+ *
+ * The graceful-stop and auto-update paths cleared it unconditionally, on the
+ * reasoning that `reapWorkerFleet` had just ended everything. It has not
+ * necessarily: that reap is bounded and best-effort, so a worker that outlived
+ * SIGKILL, one that could not be signalled, and a reservation whose spawn is in
+ * flight all survive it -- and clearing here erases the record of exactly those,
+ * right before a re-exec'd daemon's boot reap would have acted on them.
+ *
+ * Same rule as {@link reapAndClearWorkerPidfile}: retain until CONFIRMED GONE.
+ * Returns the survivors it kept.
+ */
+export declare function clearWorkerPidfileIfAllGone(path?: string, deps?: ReapPersistedDeps): WorkerPidEntry[];
+/**
+ * The leads this host has a durable record of, by the agent_sessions row each
+ * was spawned for. Null when the record cannot be read at all -- which is NOT
+ * the same as "no leads": a caller must treat an unreadable record as unknown
+ * rather than as proof that nothing is running.
+ *
+ * This is the correlation crash recovery needs. `launchLeadProcess` writes the
+ * record BEFORE `spawnTeamProcess` persists the row's `running` status and pid,
+ * so a row still reading `starting` with no pid -- the window a hard kill or a
+ * failed API write leaves behind -- is exactly the case where the DB knows
+ * nothing and this file knows everything.
+ */
+export declare function readLeadRecordsBySession(path?: string): Map<string, WorkerPidEntry> | null;
 //# sourceMappingURL=worker-pidfile.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"worker-pidfile.d.ts","sourceRoot":"","sources":["../../src/shell/worker-pidfile.ts"],"names":[],"mappings":"AA8CA;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAsBD,4EAA4E;AAC5E,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,MAAmC,GAAG,cAAc,EAAE,CAc7F;AAYD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,GAAE,MAAmC,GAAG,IAAI,CAK1G;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,CAOlF;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;IACnC,yFAAyF;IACzF,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACpD;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,CAsCrB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,GAAE,MAAmC,EACzC,IAAI,GAAE,iBAAsB,GAC3B,mBAAmB,CAKrB"}
+{"version":3,"file":"worker-pidfile.d.ts","sourceRoot":"","sources":["../../src/shell/worker-pidfile.ts"],"names":[],"mappings":"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"}