pi-claude-supervisor 0.4.1 → 0.5.1

package/src/acceptance.ts

@@ -0,0 +1,84 @@
+import type { AcceptanceCheck, TaskSpec } from "./types.ts";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_REPAIR_ROUNDS = 3;
+
+/** Normalize legacy plain-text tasks into the structured acceptance model. */
+export function normalizeTaskSpec(value: unknown, fallbackGoal: string): TaskSpec {
+  if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value))) {
+    throw new Error("task spec must be a JSON object");
+  }
+  const source = (value ?? {}) as Record<string, unknown>;
+  const goal = typeof source.goal === "string" && source.goal.trim() ? source.goal.trim() : fallbackGoal.trim();
+  if (!goal) throw new Error("task goal must not be empty");
+  return {
+    goal,
+    scope: stringList(source.scope, "scope"),
+    constraints: stringList(source.constraints, "constraints"),
+    forbidden: stringList(source.forbidden, "forbidden"),
+    acceptance: normalizeChecks(source.acceptance),
+    maxRepairRounds: normalizeRepairRounds(source.maxRepairRounds),
+  };
+}
+
+export function defaultAcceptanceChecks(): AcceptanceCheck[] {
+  return [{
+    id: "diff-check",
+    name: "git diff check",
+    command: "git",
+    args: ["diff", "--check"],
+    required: true,
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+  }];
+}
+
+function normalizeChecks(value: unknown): AcceptanceCheck[] {
+  if (value === undefined) return defaultAcceptanceChecks();
+  if (!Array.isArray(value)) throw new Error("task spec acceptance must be an array");
+  if (value.length === 0) return defaultAcceptanceChecks();
+  const checks = value.map((item, index) => normalizeCheck(item, index));
+  const ids = new Set<string>();
+  for (const check of checks) {
+    if (ids.has(check.id)) throw new Error(`duplicate acceptance check id: ${check.id}`);
+    ids.add(check.id);
+  }
+  return checks;
+}
+
+function normalizeCheck(value: unknown, index: number): AcceptanceCheck {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`acceptance[${index}] must be an object`);
+  const source = value as Record<string, unknown>;
+  const id = typeof source.id === "string" && /^[A-Za-z0-9._-]+$/u.test(source.id.trim())
+    ? source.id.trim()
+    : `check-${index + 1}`;
+  const name = typeof source.name === "string" && source.name.trim() ? source.name.trim() : id;
+  const command = typeof source.command === "string" ? source.command.trim() : "";
+  if (!command) throw new Error(`acceptance[${index}] command must not be empty`);
+  const args = source.args === undefined
+    ? []
+    : Array.isArray(source.args) && source.args.every((arg) => typeof arg === "string")
+      ? source.args.map((arg) => arg)
+      : undefined;
+  if (!args) throw new Error(`acceptance[${index}] args must be an array of strings`);
+  const timeoutValue = source.timeoutMs;
+  const timeoutMs = timeoutValue === undefined ? DEFAULT_TIMEOUT_MS : timeoutValue;
+  if (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60 * 60_000) {
+    throw new Error(`acceptance[${index}] timeoutMs must be between 1 and 3600000`);
+  }
+  if (typeof source.required !== "undefined" && typeof source.required !== "boolean") {
+    throw new Error(`acceptance[${index}] required must be boolean`);
+  }
+  return { id, name, command, args, required: source.required !== false, timeoutMs };
+}
+
+function stringList(value: unknown, field: string): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new Error(`task spec ${field} must be an array of strings`);
+  return value.map((item) => item.trim()).filter(Boolean);
+}
+
+function normalizeRepairRounds(value: unknown): number {
+  if (value === undefined) return DEFAULT_MAX_REPAIR_ROUNDS;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > 10) throw new Error("maxRepairRounds must be between 0 and 10");
+  return value;
+}

package/src/cwd-lease.ts

@@ -36,8 +36,25 @@ export interface CwdLeaseHandoff {
   tmuxSocket?: string;
 }
 
+/**
+ * Explicit recovery takeover. This is intentionally separate from ordinary
+ * acquisition: an old Pi owner may have died while its Worker survived.
+ */
+export interface CwdLeaseTakeover {
+  taskId: string;
+  /** Run before the old lease is removed; failure leaves the old lease intact. */
+  beforeReplace?: (lease: CwdLeaseRecord) => Promise<void>;
+}
+
+export interface CwdLeaseAcquireOptions {
+  handoff?: CwdLeaseHandoff;
+  takeover?: CwdLeaseTakeover;
+}
+
 export interface CwdLeaseHandle {
   readonly record: CwdLeaseRecord;
+  /** Task id whose lease was explicitly handed off/taken over, if any. */
+  readonly replacedTaskId?: string;
   updateWorker(worker: CwdLeaseWorker): Promise<void>;
   release(): Promise<void>;
 }
@@ -63,7 +80,9 @@ export class CwdLeaseStore {
     return this.#directory;
   }
 
-  async acquire(cwd: string, taskId: string, transport: CwdLeaseTransport, options: { handoff?: CwdLeaseHandoff } = {}): Promise<CwdLeaseHandle> {
+  async acquire(cwd: string, taskId: string, transport: CwdLeaseTransport, options: CwdLeaseAcquireOptions = {}): Promise<CwdLeaseHandle> {
+    assertTaskId(taskId);
+    if (options.takeover) assertTaskId(options.takeover.taskId);
     const canonicalCwd = await realpath(resolve(cwd));
     const now = new Date().toISOString();
     const lease: CwdLeaseRecord = {
@@ -77,6 +96,7 @@ export class CwdLeaseStore {
       updatedAt: now,
       worker: { transport },
     };
+    let replacedTaskId: string | undefined;
     await this.#withLock(async () => {
       const leases = await this.#readAll();
       let handoffLease: CwdLeaseRecord | undefined;
@@ -88,23 +108,35 @@ export class CwdLeaseStore {
           continue;
         }
         if (!pathsOverlap(existing.cwd, canonicalCwd)) continue;
+        if (options.takeover?.taskId === existing.taskId
+          && existing.cwd === canonicalCwd
+          && await canTakeoverLease(existing)) {
+          await options.takeover.beforeReplace?.(existing);
+          replacedTaskId = existing.taskId;
+          await rm(this.#path(existing.leaseId), { force: true });
+          continue;
+        }
         throw new Error(`working-directory lease is held by task ${existing.taskId}: ${redactText(existing.cwd)}`);
       }
       await this.#write(lease);
-      if (handoffLease) await rm(this.#path(handoffLease.leaseId), { force: true });
+      if (handoffLease) {
+        replacedTaskId = handoffLease.taskId;
+        await rm(this.#path(handoffLease.leaseId), { force: true });
+      }
     });
-    return this.#handle(lease);
+    return this.#handle(lease, replacedTaskId);
   }
 
   async list(): Promise<CwdLeaseRecord[]> {
     return this.#withLock(() => this.#readAll());
   }
 
-  #handle(initial: CwdLeaseRecord): CwdLeaseHandle {
+  #handle(initial: CwdLeaseRecord, replacedTaskId?: string): CwdLeaseHandle {
     let current = { ...initial, worker: initial.worker ? { ...initial.worker } : undefined };
     let released = false;
     return {
       get record() { return current; },
+      get replacedTaskId() { return replacedTaskId; },
       updateWorker: async (worker) => {
         if (released) throw new Error("cwd lease has already been released");
         assertWorker(worker);
@@ -157,8 +189,8 @@ export class CwdLeaseStore {
   async #write(lease: CwdLeaseRecord): Promise<void> {
     await this.#ensureDirectory();
     const target = this.#path(lease.leaseId);
-    const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(temporary, `${JSON.stringify(lease, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    const temporary = `${target}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(lease, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
     await rename(temporary, target);
     await chmod(target, 0o600);
   }
@@ -252,6 +284,10 @@ async function processIdentityLive(pid: number, expectedStartTime?: string): Pro
   const currentStartTime = await processStartTime(pid);
   if (currentStartTime && expectedStartTime) return currentStartTime === expectedStartTime;
   if (currentStartTime) return true;
+  return processExists(pid);
+}
+
+async function processExists(pid: number): Promise<boolean> {
   try {
     process.kill(pid, 0);
     return true;
@@ -260,6 +296,55 @@ async function processIdentityLive(pid: number, expectedStartTime?: string): Pro
   }
 }
 
+async function processGroupExists(pid: number): Promise<boolean> {
+  try {
+    process.kill(-pid, 0);
+    return true;
+  } catch (error) {
+    return error instanceof Error && /EPERM/u.test(error.message);
+  }
+}
+
+async function cgroupHasProcesses(path: string): Promise<boolean> {
+  // Lease files are untrusted state. Never read an arbitrary path during
+  // takeover; only a real, canonical cgroup below the kernel cgroup root is
+  // eligible for this check. Missing/unreadable evidence is not proof of an
+  // empty cgroup: a descendant may have escaped before the cgroup disappeared.
+  const cgroupRoot = resolve("/sys/fs/cgroup");
+  const cgroupPath = resolve(path);
+  if (cgroupPath === cgroupRoot || !cgroupPath.startsWith(`${cgroupRoot}/`)) return true;
+  try {
+    const cgroupInfo = await lstat(cgroupPath);
+    if (!cgroupInfo.isDirectory() || cgroupInfo.isSymbolicLink()) return true;
+    const canonicalPath = await realpath(cgroupPath);
+    if (canonicalPath !== cgroupPath || !canonicalPath.startsWith(`${cgroupRoot}/`)) return true;
+    const procsPath = join(canonicalPath, "cgroup.procs");
+    const procsInfo = await lstat(procsPath);
+    if (!procsInfo.isFile() || procsInfo.isSymbolicLink()) return true;
+    const contents = await readFile(procsPath, "utf8");
+    return contents.split(/\s+/u).some((pid) => /^\d+$/u.test(pid));
+  } catch {
+    return true;
+  }
+}
+
+async function canTakeoverLease(lease: CwdLeaseRecord): Promise<boolean> {
+  // The old supervisor owner must be gone. A dead owner is not enough when
+  // the detached Worker itself is still alive.
+  if (await processExists(lease.ownerPid)) return false;
+  const worker = lease.worker;
+  if (!worker) return false;
+  if (worker.transport === "tmux") return false;
+  if (!worker.pid) return false;
+  if (await processExists(worker.pid)) return false;
+  if (await processGroupExists(worker.pid)) return false;
+  // A process-group check cannot see a setsid descendant. Explicit takeover
+  // therefore requires the verified cgroup boundary used by the adapter.
+  if (!worker.cgroupPath || !resolve(worker.cgroupPath).startsWith(`${resolve("/sys/fs/cgroup")}/`)) return false;
+  if (await cgroupHasProcesses(worker.cgroupPath)) return false;
+  return true;
+}
+
 async function processStartTime(pid: number): Promise<string | undefined> {
   try {
     const statText = await readFile(`/proc/${pid}/stat`, "utf8");
@@ -288,6 +373,10 @@ async function matchesHandoff(lease: CwdLeaseRecord, handoff: CwdLeaseHandoff):
   return !(await processIdentityLive(lease.ownerPid, lease.ownerStartTime));
 }
 
+function assertTaskId(taskId: string): void {
+  if (!/^[0-9a-f-]{36}$/iu.test(taskId)) throw new Error("invalid cwd lease task id");
+}
+
 function assertWorker(worker: CwdLeaseWorker): void {
   if (!["process-pipe", "jsonl", "pty", "tmux"].includes(worker.transport)
     || (worker.pid !== undefined && (!Number.isSafeInteger(worker.pid) || worker.pid < 1))