@llblab/pi-actors 0.41.0 → 0.42.0

package/lib/file-state.ts

@@ -40,42 +40,144 @@ function canonicalMutationPath(path: string): string {
   return process.platform === "win32" ? canonical.toLowerCase() : canonical;
 }
 
-function mutationLockPath(path: string): string {
+export function mutationLockPath(path: string): string {
   const key = createHash("sha256")
     .update(canonicalMutationPath(path))
     .digest("hex");
   return join(FILE_MUTATION_LOCK_ROOT, `${key}.lock`);
 }
 
-function lockOwnerIsDead(lockPath: string): boolean {
+function lockOwnerStatus(lockPath: string): "alive" | "dead" | "unknown" {
   try {
     const owner = JSON.parse(
       readFileSync(join(lockPath, "owner.json"), "utf8"),
     ) as { pid?: unknown };
     const pid = Number(owner.pid);
-    if (!Number.isInteger(pid) || pid <= 0) return false;
+    if (!Number.isInteger(pid) || pid <= 0) return "unknown";
     try {
       process.kill(pid, 0);
-      return false;
+      return "alive";
     } catch (error) {
-      return (error as NodeJS.ErrnoException).code === "ESRCH";
+      return (error as NodeJS.ErrnoException).code === "ESRCH"
+        ? "dead"
+        : "unknown";
     }
   } catch {
+    return "unknown";
+  }
+}
+
+export interface FileMutationLockOptions {
+  onBeforeReclaimRemove?(): void;
+  onContention?(): void;
+  onRemovalContention?(): void;
+}
+
+function readLockToken(lockPath: string): string | undefined {
+  try {
+    const owner = JSON.parse(
+      readFileSync(join(lockPath, "owner.json"), "utf8"),
+    ) as { token?: unknown };
+    return typeof owner.token === "string" ? owner.token : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function tryReclaimRemovalBoundary(reclaimPath: string): void {
+  if (!existsSync(reclaimPath)) return;
+  try {
+    const inspectedToken = readLockToken(reclaimPath);
+    const age = Date.now() - statSync(reclaimPath).mtimeMs;
+    const ownerStatus = lockOwnerStatus(reclaimPath);
+    if (
+      (ownerStatus === "dead" ||
+        (ownerStatus === "unknown" && age > FILE_MUTATION_LOCK_STALE_MS)) &&
+      readLockToken(reclaimPath) === inspectedToken
+    ) {
+      rmSync(reclaimPath, { recursive: true, force: true });
+    }
+  } catch {
+    /* another contender changed the boundary */
+  }
+}
+
+function withRemovalBoundary(
+  lockPath: string,
+  action: () => void,
+): boolean {
+  const reclaimPath = `${lockPath}.reclaim`;
+  const token = randomUUID();
+  try {
+    mkdirSync(reclaimPath);
+    try {
+      writeFileSync(
+        join(reclaimPath, "owner.json"),
+        `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`,
+        "utf8",
+      );
+    } catch (error) {
+      rmSync(reclaimPath, { recursive: true, force: true });
+      throw error;
+    }
+  } catch {
+    tryReclaimRemovalBoundary(reclaimPath);
+    return false;
+  }
+  try {
+    action();
+    return true;
+  } finally {
+    if (readLockToken(reclaimPath) === token) {
+      rmSync(reclaimPath, { recursive: true, force: true });
+    }
+  }
+}
+
+function tryReclaimMutationLock(
+  lockPath: string,
+  options: FileMutationLockOptions,
+): boolean {
+  let reclaimed = false;
+  if (!withRemovalBoundary(lockPath, () => {
+    if (!existsSync(lockPath)) {
+      reclaimed = true;
+      return;
+    }
+    const inspectedToken = readLockToken(lockPath);
+    const age = Date.now() - statSync(lockPath).mtimeMs;
+    const ownerStatus = lockOwnerStatus(lockPath);
+    if (
+      (ownerStatus === "dead" ||
+        (ownerStatus === "unknown" && age > FILE_MUTATION_LOCK_STALE_MS)) &&
+      readLockToken(lockPath) === inspectedToken
+    ) {
+      options.onBeforeReclaimRemove?.();
+      rmSync(lockPath, { recursive: true, force: true });
+      reclaimed = true;
+    }
+  })) {
     return false;
   }
+  return reclaimed;
 }
 
-export function withFileMutationLock<T>(path: string, mutate: () => T): T {
+export function acquireFileMutationLock(
+  path: string,
+  options: FileMutationLockOptions = {},
+): () => void {
   mkdirSync(FILE_MUTATION_LOCK_ROOT, { recursive: true });
   const lockPath = mutationLockPath(path);
   const deadline = Date.now() + FILE_MUTATION_LOCK_TIMEOUT_MS;
+  const token = randomUUID();
+  let contentionReported = false;
   for (;;) {
     try {
       mkdirSync(lockPath);
       try {
         writeFileSync(
           join(lockPath, "owner.json"),
-          `${JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() })}\n`,
+          `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`,
           "utf8",
         );
       } catch (error) {
@@ -84,18 +186,11 @@ export function withFileMutationLock<T>(path: string, mutate: () => T): T {
       }
       break;
     } catch (error) {
-      try {
-        if (
-          Date.now() - statSync(lockPath).mtimeMs >
-            FILE_MUTATION_LOCK_STALE_MS &&
-          lockOwnerIsDead(lockPath)
-        ) {
-          rmSync(lockPath, { recursive: true, force: true });
-          continue;
-        }
-      } catch {
-        continue;
+      if (!contentionReported) {
+        contentionReported = true;
+        options.onContention?.();
       }
+      tryReclaimMutationLock(lockPath, options);
       if (Date.now() >= deadline) {
         throw new Error(`Timed out waiting for file mutation lock: ${canonicalMutationPath(path)}`, {
           cause: error,
@@ -104,10 +199,39 @@ export function withFileMutationLock<T>(path: string, mutate: () => T): T {
       Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
     }
   }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const deadline = Date.now() + FILE_MUTATION_LOCK_TIMEOUT_MS;
+    let removalContentionReported = false;
+    while (
+      !withRemovalBoundary(lockPath, () => {
+        if (readLockToken(lockPath) === token) {
+          rmSync(lockPath, { recursive: true, force: true });
+        }
+      })
+    ) {
+      if (!removalContentionReported) {
+        removalContentionReported = true;
+        options.onRemovalContention?.();
+      }
+      if (Date.now() >= deadline) return;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  };
+}
+
+export function withFileMutationLock<T>(
+  path: string,
+  mutate: () => T,
+  options: FileMutationLockOptions = {},
+): T {
+  const release = acquireFileMutationLock(path, options);
   try {
     return mutate();
   } finally {
-    rmSync(lockPath, { recursive: true, force: true });
+    release();
   }
 }
 

package/lib/inspector-actions.ts

@@ -0,0 +1,79 @@
+/**
+ * Actor Inspector run actions.
+ * Owns: exact-session run-action authorization, canonical kill routing, and bounded operator feedback.
+ */
+
+import { join } from "node:path";
+
+import { safeRunId } from "./runs-identity.ts";
+
+const FEEDBACK_LIMIT = 180;
+
+export interface ActorInspectorKillResult {
+  ok: boolean;
+  message: string;
+}
+
+export interface ActorInspectorKillDeps {
+  getRunStatus: (runOrDir: string) => Record<string, unknown>;
+  killRun: (
+    runOrDir: string,
+    expected: { ownerId: string; runInstanceId: string },
+  ) => Record<string, unknown>;
+}
+
+function bounded(value: unknown): string {
+  const text = String(value ?? "").replaceAll(/\s+/g, " ").trim();
+  return text.length <= FEEDBACK_LIMIT
+    ? text
+    : `${text.slice(0, FEEDBACK_LIMIT - 1)}…`;
+}
+
+export function killOwnedInspectorRun(
+  ownerId: string,
+  run: string,
+  stateRoot: string,
+  expectedRunInstanceId: string,
+  deps: ActorInspectorKillDeps,
+): ActorInspectorKillResult {
+  let stateDir: string;
+  try {
+    stateDir = join(stateRoot, safeRunId(run));
+  } catch (error) {
+    return {
+      ok: false,
+      message: `Kill rejected: ${bounded(error instanceof Error ? error.message : error)}`,
+    };
+  }
+  try {
+    const status = deps.getRunStatus(stateDir);
+    if (status.ownerId !== ownerId) {
+      return { ok: false, message: "Kill rejected: run ownership changed." };
+    }
+    if (status.status !== "running") {
+      return {
+        ok: false,
+        message: `Kill unavailable: run is ${bounded(status.status || "terminal")}.`,
+      };
+    }
+    if (status.run_instance_id !== expectedRunInstanceId) {
+      return { ok: false, message: "Kill rejected: run generation changed." };
+    }
+    const result = deps.killRun(stateDir, {
+      ownerId,
+      runInstanceId: expectedRunInstanceId,
+    });
+    if (result.killed === true) {
+      return { ok: true, message: `Killed run:${run}.` };
+    }
+    return {
+      ok: false,
+      message: `Kill failed: ${bounded(result.reason || "control rejected")}.`,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      message: `Kill failed: ${bounded(error instanceof Error ? error.message : error)}.`,
+    };
+  }
+}

package/lib/inspector-command.ts

@@ -0,0 +1,54 @@
+/**
+ * Actor Inspector command adapter.
+ * Zones: Pi command registration, overlay construction, owned-run control ports
+ * Owns host-facing Inspector launch wiring without owning Inspector state or actions.
+ */
+
+import * as AsyncRuns from "./async-runs.ts";
+import * as InspectorActions from "./inspector-actions.ts";
+import * as InspectorOverlay from "./inspector-overlay.ts";
+import * as Paths from "./paths.ts";
+import type * as Pi from "./pi.ts";
+
+export function registerActorInspectorCommand(
+  pi: Pi.ExtensionAPI,
+  getRunOwnerId: (ctx: Pi.ExtensionContext) => string,
+): void {
+  pi.registerCommand("actors-inspector", {
+    description: "Open the keyboard-driven actor inspector overlay",
+    handler: async (_args, ctx) => {
+      ctx.ui.setWidget("zz-pi-actors-comms", undefined);
+      await ctx.ui.custom<void>(
+        (tui, theme, _keybindings, done) =>
+          new InspectorOverlay.ActorInspectorOverlay({
+            done,
+            killRun: (run, runInstanceId) =>
+              InspectorActions.killOwnedInspectorRun(
+                getRunOwnerId(ctx),
+                run,
+                Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
+                runInstanceId,
+                {
+                  getRunStatus: AsyncRuns.getRunStatus,
+                  killRun: AsyncRuns.killRun,
+                },
+              ),
+            ownerId: getRunOwnerId(ctx),
+            stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
+            theme,
+            tui,
+          }),
+        {
+          overlay: true,
+          overlayOptions: {
+            anchor: "center",
+            width: "94%",
+            minWidth: 72,
+            maxHeight: "94%",
+            margin: 1,
+          },
+        },
+      );
+    },
+  });
+}