pi-claude-supervisor 0.9.0 → 0.9.1

package/src/decision-worker.ts

@@ -4,6 +4,7 @@ import { dirname, resolve } from "node:path";
 import { lstat, open, rename, rm, writeFile, type FileHandle } from "node:fs/promises";
 import { isDeepStrictEqual } from "node:util";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, type AgentSession } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_MAX_DECISION_RETRIES } from "./config.ts";
 import { extractJsonObjects } from "./json-extract.ts";
 import type { PiUsageSample, TaskSpec, WorkerEvent } from "./types.ts";
 import { redactSensitive } from "./redaction.ts";
@@ -28,6 +29,16 @@ export interface DecisionContext {
   spec?: TaskSpec;
   /** Wall-clock budget of the task; absent when no deadline is configured. */
   deadline?: DecisionDeadlineContext;
+  /** Outcome of the most recent acceptance/Review round, if one has run. */
+  lastVerification?: DecisionVerificationSummary;
+}
+
+/** A compact view of the last verification: what failed and what the Reviewer asked for. */
+export interface DecisionVerificationSummary {
+  ok: boolean;
+  failedChecks: string[];
+  reviewVerdict?: string;
+  findings: string[];
 }
 
 export interface DecisionDeadlineContext {
@@ -81,6 +92,9 @@ export interface DecisionWorkerOptions {
 export type PiModel = NonNullable<NonNullable<Parameters<typeof createAgentSession>[0]>["model"]>;
 
 const DEFAULT_COMPACTION_TOKENS = 60_000;
+/** First retry wait; each later wait triples, capped at MAX_DECISION_RETRY_BACKOFF_MS. */
+const DEFAULT_DECISION_RETRY_BACKOFF_MS = 5_000;
+const MAX_DECISION_RETRY_BACKOFF_MS = 60_000;
 
 /**
  * A persistent Pi SDK session used only for supervision decisions.
@@ -106,7 +120,7 @@ export class PiDecisionWorker implements DecisionWorkerLike {
     this.#options = options;
     this.#context = { ...options.context };
     this.#timeoutMs = options.timeoutMs ?? 120_000;
-    this.#retryBackoffMs = options.retryBackoffMs ?? 500;
+    this.#retryBackoffMs = options.retryBackoffMs ?? DEFAULT_DECISION_RETRY_BACKOFF_MS;
     this.#compactionTokens = options.compactionTokens ?? DEFAULT_COMPACTION_TOKENS;
   }
 
@@ -188,7 +202,7 @@ export class PiDecisionWorker implements DecisionWorkerLike {
 
   async #processEvent(event: WorkerEvent): Promise<void> {
     if (!this.#session || this.#closed) return;
-    const maxRetries = this.#context.spec?.autonomy.maxDecisionRetries ?? 2;
+    const maxRetries = this.#context.spec?.autonomy.maxDecisionRetries ?? DEFAULT_MAX_DECISION_RETRIES;
     let attempt = 0;
     // undefined selects the primary decision question; a bounded re-prompt
     // (below) switches this to a corrective follow-up on the same session.
@@ -216,7 +230,8 @@ export class PiDecisionWorker implements DecisionWorkerLike {
         if (error instanceof Error && error.name === "AbortError") throw error;
         if (attempt >= maxRetries) throw error;
         attempt += 1;
-        await new Promise<void>((resolveWait) => setTimeout(resolveWait, Math.min(30_000, this.#retryBackoffMs * 2 ** attempt)));
+        // 429/529 overloads last minutes, not seconds: 15s, 45s, then 60s.
+        await new Promise<void>((resolveWait) => setTimeout(resolveWait, Math.min(MAX_DECISION_RETRY_BACKOFF_MS, this.#retryBackoffMs * 3 ** attempt)));
         if (!this.#session || this.#closed) return;
         continue;
       }
@@ -231,6 +246,13 @@ export class PiDecisionWorker implements DecisionWorkerLike {
         prompt = `Your previous reply was not a single valid JSON action (${action.reason}). Return exactly one JSON object now and nothing else.`;
         continue;
       }
+      // `noop` on a completed turn or a pending permission leaves the Worker
+      // idle forever; the Supervisor parks it. Ask once for a concrete action.
+      if (!repromptAttempted && action.action === "noop" && (event.type === "turn_completed" || event.type === "permission_request")) {
+        repromptAttempted = true;
+        prompt = `noop is not a valid action for a ${event.type} event: the Worker is waiting on you and nothing will happen. Choose a concrete action (for example continue, redirect or verify for a completed turn, or allow_permission/deny_permission for a permission request) and return exactly one JSON object now.`;
+        continue;
+      }
       // An action handler may stop or close the session. Do not replay an
       // already-decoded action if the handler itself fails.
       await this.#options.onAction(action, event);
@@ -249,11 +271,15 @@ export class PiDecisionWorker implements DecisionWorkerLike {
     const tokens = this.#session.getContextUsage?.()?.tokens;
     if (typeof tokens !== "number" || tokens <= this.#compactionTokens) return;
     try {
-      await this.#session.compact(
+      // Bounded like any other Decision Worker request: compaction runs on the
+      // serialized decision tail, so a stalled summarization would otherwise
+      // block every later decision.
+      await withTimeout(this.#session.compact(
         "Preserve: the task specification, the policy rules for permissions and boundaries, the current state, and the last three decisions with their reasons.",
-      );
+      ), this.#timeoutMs, "Decision Worker compaction");
       this.#instructionsStale = true;
     } catch {
+      try { this.#session?.abortCompaction?.(); } catch { /* best effort */ }
       // A compaction failure must not fail the decision that already succeeded.
     }
   }
@@ -311,7 +337,9 @@ as the answer and continues. A turn_completed whose result has subtype "error" o
 means the Worker's own API/model call failed mid-turn: choose retry (optionally with a short
 corrective message) or continue to resume it, and park only after repeated failures; a subtype
 "idle" result means the turn ended without a normal stop signal, so inspect the repository and
-decide as for any other turn. Use verify when a turn result indicates the task is complete, even if
+decide as for any other turn. CURRENT CONTEXT.lastVerification, when present, is the last acceptance
+and Review round (failed check ids, Reviewer verdict and findings): after a repair turn, check
+Claude's claim against it before choosing verify. Use verify when a turn result indicates the task is complete, even if
 Claude says it will stop; choose stop only for an explicit stop or technical containment reason.
 Use park only when the task cannot safely produce a candidate because required evidence,
 authority, or runtime capability is unavailable. A parked candidate is asynchronous and must not
@@ -390,6 +418,7 @@ async function askDecision(
         ? { closeOutRemainingMinutes: Math.round(context.deadline.closeOutRemainingMs / 60_000) }
         : {}),
     } : {}),
+    ...(context.lastVerification ? { lastVerification: context.lastVerification } : {}),
   };
   const prompt = `${options.instructionsPrefix ?? ""}UNTRUSTED SUPERVISOR EVENT:\n${boundedEventJson(event)}\n\nCURRENT CONTEXT:\n${boundedJson(currentContext)}\n\nChoose one action now.`;
   return promptForText(session, prompt, timeoutMs, "Decision Worker request", MAX_DECISION_RESPONSE_BYTES, { role: "decision", onUsage: options.onUsage });

package/src/events.ts

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { appendFile, chmod, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
+import { currentLockOwner, lockOwnerAlive } from "./lock-owner.ts";
 import { redactSensitive } from "./redaction.ts";
 
 export interface SupervisorEvent {
@@ -71,7 +72,7 @@ export class EventLog {
     while (true) {
       try {
         await mkdir(lockPath);
-        await writeFile(`${lockPath}/owner.json`, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }));
+        await writeFile(`${lockPath}/owner.json`, JSON.stringify(await currentLockOwner()));
         break;
       } catch (error) {
         if (!(error instanceof Error) || !/EEXIST/u.test(error.message)) throw error;
@@ -91,21 +92,14 @@ export class EventLog {
     try {
       const info = await stat(`${lockPath}/owner.json`);
       if (Date.now() - info.mtimeMs < STALE_LOCK_MS) return false;
-      let owner: { pid?: unknown };
+      let owner: unknown;
       try {
-        owner = JSON.parse(await readFile(`${lockPath}/owner.json`, "utf8")) as { pid?: unknown };
+        owner = JSON.parse(await readFile(`${lockPath}/owner.json`, "utf8"));
       } catch {
         await rm(lockPath, { recursive: true, force: true });
         return true;
       }
-      if (typeof owner.pid === "number") {
-        try {
-          process.kill(owner.pid, 0);
-          return false;
-        } catch (error) {
-          if (error instanceof Error && /EPERM/u.test(error.message)) return false;
-        }
-      }
+      if (await lockOwnerAlive(owner)) return false;
       await rm(lockPath, { recursive: true, force: true });
       return true;
     } catch (error) {

package/src/hooks/install.ts

@@ -2,20 +2,11 @@ import { randomUUID } from "node:crypto";
 import { chmod, mkdir, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { HOOK_TIMEOUT_SECONDS, type ClaudeHookEventName } from "./types.ts";
+import { CLAUDE_HOOK_EVENT_NAMES, HOOK_TIMEOUT_SECONDS, type ClaudeHookEventName } from "./types.ts";
 import { HOOK_RELAY_SCRIPT, hookRelayCommand } from "./relay.ts";
 import { hookSocketDirectory } from "./server.ts";
 
-const HOOK_EVENT_NAMES: readonly ClaudeHookEventName[] = [
-  "SessionStart",
-  "SessionEnd",
-  "UserPromptSubmit",
-  "PreToolUse",
-  "PermissionRequest",
-  "Stop",
-  "StopFailure",
-  "Notification",
-];
+const HOOK_EVENT_NAMES: readonly ClaudeHookEventName[] = CLAUDE_HOOK_EVENT_NAMES;
 
 /** Substring that marks a hook command entry as ours, regardless of which stateDir produced it. */
 const RELAY_MARKER = "/hooks/relay.js";

package/src/hooks/server.ts

@@ -3,19 +3,11 @@ import { createServer, type Server, type Socket } from "node:net";
 import { chmod, lstat, mkdir, readdir, readlink, realpath, rename, rm, symlink, unlink } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
-import type { ClaudeHookEvent, ClaudeHookEventName, HookEventSource, HookRelayReply, HookRelayRequest } from "./types.ts";
+import { CLAUDE_HOOK_EVENT_NAMES, type ClaudeHookEvent, type ClaudeHookEventName, type HookEventSource, type HookRelayReply, type HookRelayRequest } from "./types.ts";
 
 const MAX_LINE_BYTES = 1024 * 1024;
 
-const VALID_EVENT_NAMES: ReadonlySet<string> = new Set<ClaudeHookEventName>([
-  "SessionStart",
-  "SessionEnd",
-  "UserPromptSubmit",
-  "PreToolUse",
-  "PermissionRequest",
-  "Stop",
-  "Notification",
-]);
+const VALID_EVENT_NAMES: ReadonlySet<string> = new Set<ClaudeHookEventName>(CLAUDE_HOOK_EVENT_NAMES);
 
 type HookHandler = (request: HookRelayRequest) => Promise<HookRelayReply | undefined>;
 

package/src/hooks/settings.ts

@@ -1,18 +1,9 @@
 import { randomUUID } from "node:crypto";
 import { chmod, mkdir, rename, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { HOOK_TIMEOUT_SECONDS, type ClaudeHookEventName } from "./types.ts";
+import { CLAUDE_HOOK_EVENT_NAMES, HOOK_TIMEOUT_SECONDS, type ClaudeHookEventName } from "./types.ts";
 
-const HOOK_EVENT_NAMES: readonly ClaudeHookEventName[] = [
-  "SessionStart",
-  "SessionEnd",
-  "UserPromptSubmit",
-  "PreToolUse",
-  "PermissionRequest",
-  "Stop",
-  "StopFailure",
-  "Notification",
-];
+const HOOK_EVENT_NAMES: readonly ClaudeHookEventName[] = CLAUDE_HOOK_EVENT_NAMES;
 
 interface HookCommandEntry {
   type: "command";

package/src/hooks/types.ts

@@ -5,15 +5,23 @@
  * event over a unix socket and prints the reply as Claude's hook output.
  */
 
-export type ClaudeHookEventName =
-  | "SessionStart"
-  | "SessionEnd"
-  | "UserPromptSubmit"
-  | "PreToolUse"
-  | "PermissionRequest"
-  | "Stop"
-  | "StopFailure"
-  | "Notification";
+/**
+ * Every hook event the Supervisor consumes. The one list that the installed
+ * hook settings, the per-session settings and the server's request parser all
+ * derive from, so an event cannot be registered and then dropped on arrival.
+ */
+export const CLAUDE_HOOK_EVENT_NAMES = [
+  "SessionStart",
+  "SessionEnd",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PermissionRequest",
+  "Stop",
+  "StopFailure",
+  "Notification",
+] as const;
+
+export type ClaudeHookEventName = typeof CLAUDE_HOOK_EVENT_NAMES[number];
 
 /** The subset of Claude Code hook input the Supervisor consumes (all fields untrusted). */
 export interface ClaudeHookEvent {

package/src/index.ts

@@ -73,6 +73,11 @@ async function userHooksInstalled(settingsPath: string): Promise<boolean> {
  * sessions may run concurrently, but active sessions must use different
  * working directories so workers cannot silently overwrite one another.
  */
+/** The first message a recovered Worker gets: it is a fresh process that never saw the task. */
+function recoveryContinuation(goal: string): string {
+  return `The Supervisor restarted this task after an interruption; you are a fresh session and earlier work may already be in the repository. First inspect git status, git log and the uncommitted diff to see what was done. Then continue the original task to completion, run the relevant checks and commit locally. Original task:\n${goal}`;
+}
+
 export default function piClaudeSupervisor(pi: ExtensionAPI): void {
   loadSupervisorEnvironment();
   const automation = process.env.PI_CLAUDE_SUPERVISOR_MODE === "auto" || process.env.PI_CLAUDE_SUPERVISOR_AUTOMATION === "1";
@@ -185,6 +190,8 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
     return new PiReadOnlyReviewer({ timeoutMs: reviewTimeoutMs(), model: await reviewerPiModelPromise });
   };
   const sessions = new Map<string, Supervisor>();
+  /** The last few tasks that finished and were released, newest last, for `status`/`sessions`. */
+  const finishedSessions = new Map<string, { finishedAt: number; detail: string }>();
   const cwdLeases = new Map<string, CwdLeaseHandle>();
   const cleanupRequiredTasks = new Set<string>();
   const reservedCwds = new Map<string, string>();
@@ -230,6 +237,14 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
     }
   };
   const forgetSession = (taskId: string): void => {
+    // Keep what a finished task ended as: after an overnight run, `status`
+    // is exactly where the operator looks, and the live session is gone.
+    const finished = sessions.get(taskId);
+    if (finished) {
+      finishedSessions.delete(taskId);
+      finishedSessions.set(taskId, { finishedAt: Date.now(), detail: formatSessionDetail(taskId, finished, tmuxModeLabel()) });
+      while (finishedSessions.size > MAX_FINISHED_SESSIONS) finishedSessions.delete(finishedSessions.keys().next().value!);
+    }
     sessions.delete(taskId);
     reservedCwds.delete(taskId);
     cleanupRequiredTasks.delete(taskId);
@@ -885,6 +900,34 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                 throw new Error("Pi session shut down during recovery");
               }
               message = `Worker recovered idle: task=${record.taskId} worker=${handle.id}; original task was not replayed; send an explicit continuation, then use resume-auto`;
+              // `--extend` is an explicit request to carry on unattended: hand
+              // the task back to automation instead of leaving it under
+              // takeover. `--extend 0` needs no message — the close-out
+              // verifies the idle Worker on the next watchdog tick; a real
+              // extension sends a continuation, since the fresh Worker does
+              // not remember the task. A failure here leaves the recovered
+              // Worker idle under takeover, exactly as a plain recover would.
+              if (automaticRecovery && extendMs !== undefined) {
+                const turnBefore = session.turn;
+                try {
+                  await session.resumeAutomation();
+                  if (extendMs > 0) await session.send(recoveryContinuation(record.spec?.goal ?? record.task));
+                  message = extendMs > 0
+                    ? `Worker recovered: task=${record.taskId} worker=${handle.id}; automation resumed with a continuation of the original task; ${formatDurationMs(Math.max(0, recoveryDeadlineMs - elapsedMs))} of budget from now`
+                    : `Worker recovered: task=${record.taskId} worker=${handle.id}; automation resumed; the close-out verifies and reviews the repository as it stands`;
+                } catch (error) {
+                  const detail = redactText(error instanceof Error ? error.message : String(error));
+                  if (session.turn > turnBefore) {
+                    // The continuation reached the Worker (only its audit
+                    // record failed): it is working under automation now,
+                    // and taking it over would leave that turn undecided.
+                    message = `Worker recovered: task=${record.taskId} worker=${handle.id}; automation resumed with a continuation of the original task (warning: ${detail})`;
+                  } else {
+                    await session.takeover().catch(() => {});
+                    message = `${message} (automatic resume failed: ${detail})`;
+                  }
+                }
+              }
             } catch (error) {
               const handle = session.handle ?? startedHandle;
               let cleanupConfirmed = !handle;
@@ -960,15 +1003,22 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
         } else if (operation === "sessions") {
           const recoverable = await decisionStore.list({ activeOnly: true });
           message = formatSessions(sessions, recoverable, tmuxModeLabel());
+          if (finishedSessions.size > 0) message += `\nRecently finished:\n${formatFinishedSessions(finishedSessions)}`;
           const quarantined = await cwdLeaseStore.quarantined();
           if (quarantined.length > 0) {
             message += `\nQuarantined cwd lease records (${quarantined.length}) in ${leaseDir}/quarantine: ${redactText(quarantined.join(", "))}`;
           }
         } else if (operation === "status") {
-          const { session, sessionId } = resolveSession(sessions, activeTaskId, rest, true);
-          message = session
-            ? `task=${sessionId} state=${session.state} worker=${session.handle?.id ?? "none"}${tmuxModeLabel() ? ` mode=${tmuxModeLabel()}` : ""}${formatDeadline(session.deadline)} ${formatUsageDetail(session.usage)}`
-            : formatSessions(sessions, await decisionStore.list({ activeOnly: true }), tmuxModeLabel());
+          const finished = rest[0] && !sessions.has(rest[0]) ? finishedSessions.get(rest[0]) : undefined;
+          if (finished) {
+            message = `finished ${formatDurationMs(Date.now() - finished.finishedAt)} ago: ${finished.detail}`;
+          } else {
+            const { session, sessionId } = resolveSession(sessions, activeTaskId, rest, true);
+            message = session && sessionId
+              ? formatSessionDetail(sessionId, session, tmuxModeLabel())
+              : formatSessions(sessions, await decisionStore.list({ activeOnly: true }), tmuxModeLabel())
+                + (finishedSessions.size > 0 ? `\nRecently finished:\n${formatFinishedSessions(finishedSessions)}` : "");
+          }
         } else if (operation === "capabilities") {
           message = JSON.stringify(adapter.capabilities(), null, 2);
         } else if (operation === "install-hooks" || operation === "uninstall-hooks") {
@@ -1149,6 +1199,35 @@ function formatDeadline(deadline: Supervisor["deadline"]): string {
   return ` deadline=close-out (${formatDurationMs(deadline.closeOutRemainingMs ?? 0)} left)`;
 }
 
+const MAX_FINISHED_SESSIONS = 20;
+
+/**
+ * One task's state in a line: what it is doing, how far it got, and — the
+ * question an operator of an unattended run actually has — whether it is
+ * waiting on them.
+ */
+function formatSessionDetail(taskId: string, session: Supervisor, tmuxModeLabel?: string): string {
+  const task = session.task;
+  const parts = [`task=${taskId}`, `state=${session.state}`, `worker=${session.handle?.id ?? "none"}`];
+  if (tmuxModeLabel) parts.push(`mode=${tmuxModeLabel}`);
+  if (session.humanRequired) parts.push("automation=paused(resume-auto)");
+  if (session.candidateParked) parts.push("candidate=parked");
+  if (task) {
+    parts.push(`turn=${session.turn}/${task.maxTurns}`);
+    if (session.repairRound > 0) parts.push(`repair=${session.repairRound}`);
+    const startedAt = Date.parse(task.startedAt);
+    if (Number.isFinite(startedAt)) parts.push(`elapsed=${formatDurationMs(Math.max(0, Date.now() - startedAt))}`);
+  }
+  const verification = session.lastVerification;
+  if (verification) parts.push(`lastVerify=${verification.ok ? "pass" : "fail"}${verification.review ? `(review=${verification.review.verdict})` : ""}`);
+  const terminal = ["completed", "blocked", "stopped", "failed"].includes(session.state);
+  return `${parts.join(" ")}${terminal ? "" : formatDeadline(session.deadline)} ${formatUsageDetail(session.usage)}`;
+}
+
+function formatFinishedSessions(finished: Map<string, { finishedAt: number; detail: string }>): string {
+  return [...finished.values()].reverse().map((entry) => `  ${formatDurationMs(Date.now() - entry.finishedAt)} ago: ${entry.detail}`).join("\n");
+}
+
 function formatSessions(sessions: Map<string, Supervisor>, recoverable: DecisionSessionRecord[] = [], tmuxModeLabel?: string): string {
   const modeSuffix = tmuxModeLabel ? ` mode=${tmuxModeLabel}` : "";
   const active = [...sessions.entries()]

package/src/json-extract.ts

@@ -4,7 +4,12 @@
  * objects: prose is harmless, but ambiguity must remain non-publishable.
  */
 export function extractJsonObjects(text: string): unknown[] {
-  const objects: unknown[] = [];
+  return extractJsonObjectSpans(text).map((span) => span.value);
+}
+
+/** The same objects, each with the exact source text it was parsed from. */
+export function extractJsonObjectSpans(text: string): Array<{ value: unknown; source: string }> {
+  const objects: Array<{ value: unknown; source: string }> = [];
   let offset = 0;
   while (offset < text.length) {
     const start = text.indexOf("{", offset);
@@ -17,7 +22,7 @@ export function extractJsonObjects(text: string): unknown[] {
     const candidate = text.slice(start, end + 1);
     try {
       const value = JSON.parse(candidate) as unknown;
-      if (value && typeof value === "object" && !Array.isArray(value)) objects.push(value);
+      if (value && typeof value === "object" && !Array.isArray(value)) objects.push({ value, source: candidate });
       offset = end + 1;
     } catch {
       offset = start + 1;
@@ -47,3 +52,37 @@ export function balancedObjectEnd(text: string, start: number): number {
   }
   return -1;
 }
+
+/**
+ * True when any object in this (already valid) JSON text names a key twice.
+ * `JSON.parse` silently keeps the last value, so a duplicate is how text
+ * spliced into a string can override a field it was never meant to touch.
+ * Keys are compared decoded, so `"\u0076erdict"` duplicates `"verdict"`.
+ */
+export function jsonHasDuplicateKeys(json: string): boolean {
+  const scopes: Array<Set<string> | undefined> = [];
+  let index = 0;
+  while (index < json.length) {
+    const character = json[index];
+    if (character === '"') {
+      let end = index + 1;
+      while (end < json.length && json[end] !== '"') end += json[end] === "\\" ? 2 : 1;
+      const token = json.slice(index, end + 1);
+      index = end + 1;
+      let next = index;
+      while (next < json.length && /\s/u.test(json[next]!)) next += 1;
+      const scope = scopes.at(-1);
+      if (json[next] === ":" && scope) {
+        const key = JSON.parse(token) as string;
+        if (scope.has(key)) return true;
+        scope.add(key);
+      }
+      continue;
+    }
+    if (character === "{") scopes.push(new Set());
+    else if (character === "[") scopes.push(undefined);
+    else if (character === "}" || character === "]") scopes.pop();
+    index += 1;
+  }
+  return false;
+}

package/src/lock-owner.ts

@@ -0,0 +1,55 @@
+import { readFile } from "node:fs/promises";
+
+/**
+ * Identity written into a short-lived lock directory's `owner.json`. The pid
+ * alone is not an identity: after a crash and a container or VM restart the
+ * next Pi often gets the same pid, and a lock judged only by `kill(pid, 0)`
+ * then looks held forever. The pid's start time (Linux) makes it one.
+ */
+export interface LockOwner {
+  pid: number;
+  startTime?: string;
+  at: string;
+}
+
+let ownStartTime: Promise<string | undefined> | undefined;
+
+/** The owner record for a lock taken by this process. */
+export async function currentLockOwner(): Promise<LockOwner> {
+  ownStartTime ??= processStartTime(process.pid);
+  const startTime = await ownStartTime;
+  return { pid: process.pid, ...(startTime ? { startTime } : {}), at: new Date().toISOString() };
+}
+
+/**
+ * Whether the process that wrote `owner` still exists. A missing or malformed
+ * record, a dead pid, or a live pid with a different start time (a reused
+ * pid) all mean the lock is abandoned; only a live pid whose start time still
+ * matches (or cannot be compared) keeps it.
+ */
+export async function lockOwnerAlive(owner: unknown): Promise<boolean> {
+  if (!owner || typeof owner !== "object") return false;
+  const { pid, startTime } = owner as { pid?: unknown; startTime?: unknown };
+  if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    if (!(error instanceof Error && /EPERM/u.test(error.message))) return false;
+  }
+  if (typeof startTime !== "string") return true;
+  const current = await processStartTime(pid);
+  return current === undefined || current === startTime;
+}
+
+/** Linux process start time in clock ticks since boot (field 22 of /proc/<pid>/stat). */
+export async function processStartTime(pid: number): Promise<string | undefined> {
+  try {
+    const statText = await readFile(`/proc/${pid}/stat`, "utf8");
+    const closeParen = statText.lastIndexOf(")");
+    const fields = closeParen >= 0 ? statText.slice(closeParen + 2).trim().split(/\s+/u) : [];
+    const startTime = fields[19];
+    return startTime && /^\d+$/u.test(startTime) ? startTime : undefined;
+  } catch {
+    return undefined;
+  }
+}