@llblab/pi-actors 0.43.0 → 0.44.0

package/lib/command-templates.ts

@@ -5,9 +5,9 @@
  */
 
 import { spawn } from "node:child_process";
-import { appendFileSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { accessSync, appendFileSync, constants, mkdirSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { isAbsolute, join, resolve as resolvePath } from "node:path";
+import { basename, delimiter, extname, isAbsolute, join, resolve as resolvePath } from "node:path";
 
 export type CommandTemplateFailureScope = "continue" | "branch" | "root";
 
@@ -259,7 +259,7 @@ function getLeafCommandTemplateRiskLabels(
   const command = getExecutableName(parts[0]);
   const args = parts.slice(1);
   const labels = new Set<CommandTemplateRiskLabel>();
-  if (["bash", "sh", "zsh", "fish"].includes(command)) {
+  if (["bash", "sh", "zsh", "fish"].includes(command) || command.endsWith(".sh")) {
     labels.add("risk.shell");
     if (hasAnyFlag(args, ["-c"])) labels.add("risk.eval");
   }
@@ -602,6 +602,46 @@ export function expandCommandTemplateExecutable(
   return command;
 }
 
+export type CommandTemplateExecutableResolver = (name: string) => string | undefined;
+
+function resolveExecutableOnPath(name: string): string | undefined {
+  if (name === "node" && /^node(?:\.exe)?$/i.test(basename(process.execPath)))
+    return process.execPath;
+  const pathValue = Object.entries(process.env)
+    .find(([key]) => key.toLowerCase() === "path")?.[1] ?? "";
+  const suffixes = process.platform === "win32" ? [".exe", ".com"] : [""];
+  for (const entry of pathValue.split(delimiter).filter(Boolean)) {
+    const directory = entry.replace(/^"|"$/g, "");
+    for (const suffix of suffixes) {
+      const candidate = join(directory, `${name}${suffix}`);
+      try {
+        accessSync(candidate, constants.X_OK);
+        if (statSync(candidate).isFile()) return candidate;
+      } catch {}
+    }
+  }
+  return undefined;
+}
+
+export function resolveCommandTemplateScriptInvocation(
+  invocation: CommandTemplateInvocation,
+  resolveExecutable: CommandTemplateExecutableResolver = resolveExecutableOnPath,
+): CommandTemplateInvocation {
+  const extension = extname(invocation.command).toLowerCase();
+  const interpreters = extension === ".js" || extension === ".mjs"
+    ? [["node"], ["bun"], ["deno", "run"]]
+    : extension === ".sh" ? [["bash"]] : [];
+  if (interpreters.length === 0) return invocation;
+  for (const [name, ...prefix] of interpreters) {
+    const executable = resolveExecutable(name);
+    if (executable)
+      return { command: executable, args: [...prefix, invocation.command, ...invocation.args] };
+  }
+  throw new Error(
+    `No interpreter available for command-template ${extension} script; tried ${interpreters.map(([name]) => name).join(", ")}.`,
+  );
+}
+
 function evaluateCommandTemplateExpression(
   expression: string,
   values: Record<string, unknown>,
@@ -1072,5 +1112,5 @@ export function buildCommandTemplateInvocation(
       ),
     )
     .filter((part) => part !== "");
-  return { command, args };
+  return resolveCommandTemplateScriptInvocation({ command, args });
 }

package/lib/control-projection.ts

@@ -0,0 +1,105 @@
+/**
+ * Model-facing Run Control projection.
+ * Zones: structured redaction, bounded Control input/error, decision-useful evidence
+ * Owns safe Control reads; durable journals and lifecycle transitions remain in runs-controls.
+ */
+
+import * as Limits from "./limits.ts";
+import type { RunControlRecord, RunControlStatus } from "./runs-controls.ts";
+import * as SessionEvidence from "./session-evidence.ts";
+
+export interface ProjectedRunControl {
+  action: string;
+  claimed_at?: string;
+  delivered_at?: string;
+  error?: string;
+  failed_at?: string;
+  handled_at?: string;
+  id: string;
+  input?: unknown;
+  queued_at: string;
+  run_instance_id: string;
+  status: RunControlStatus;
+}
+
+const OPTIONAL_TIMESTAMP_FIELDS = [
+  "claimed_at",
+  "delivered_at",
+  "failed_at",
+  "handled_at",
+] as const;
+type OptionalTimestampField = (typeof OPTIONAL_TIMESTAMP_FIELDS)[number];
+
+function boundedRedactedString(value: string, maxChars: number): string {
+  const redacted = SessionEvidence.redactSessionEvidenceValue(value, maxChars);
+  return typeof redacted === "string"
+    ? redacted
+    : String(redacted).slice(0, maxChars);
+}
+
+function boundedRedactedValue(value: unknown): unknown {
+  const redacted = SessionEvidence.redactSessionEvidenceValue(
+    value,
+    Limits.INSPECTOR_BODY_PREVIEW_CHARS,
+  );
+  let serialized: string | undefined;
+  try {
+    serialized = JSON.stringify(redacted);
+  } catch {
+    return "[UNSERIALIZABLE]";
+  }
+  if (serialized === undefined) return "[UNSERIALIZABLE]";
+  if (serialized.length <= Limits.INSPECTOR_BODY_PREVIEW_CHARS) return redacted;
+  let preview = serialized.slice(0, Limits.INSPECTOR_BODY_PREVIEW_CHARS);
+  let bounded = { preview: `${preview}…`, truncated: true };
+  while (
+    preview &&
+    JSON.stringify(bounded).length > Limits.INSPECTOR_BODY_PREVIEW_CHARS
+  ) {
+    const excess = JSON.stringify(bounded).length - Limits.INSPECTOR_BODY_PREVIEW_CHARS;
+    preview = preview.slice(0, Math.max(0, preview.length - Math.max(1, excess)));
+    bounded = { preview: `${preview}…`, truncated: true };
+  }
+  return bounded;
+}
+
+export function projectRunControl(
+  control: RunControlRecord,
+): ProjectedRunControl {
+  const timestamps = Object.fromEntries(
+    OPTIONAL_TIMESTAMP_FIELDS.flatMap((field) => {
+      const value = control[field];
+      return typeof value === "string"
+        ? [[field, boundedRedactedString(value, Limits.COMPACT_PREVIEW_CHARS)] as const]
+        : [];
+    }),
+  ) as Partial<Pick<ProjectedRunControl, OptionalTimestampField>>;
+  return {
+    action: boundedRedactedString(control.action, Limits.COMPACT_PREVIEW_CHARS),
+    ...timestamps,
+    ...(typeof control.error === "string"
+      ? {
+          error: boundedRedactedString(
+            control.error,
+            Limits.INSPECTOR_BODY_PREVIEW_CHARS,
+          ),
+        }
+      : {}),
+    id: boundedRedactedString(control.id, Limits.COMPACT_PREVIEW_CHARS),
+    ...(control.input !== undefined
+      ? { input: boundedRedactedValue(control.input) }
+      : {}),
+    queued_at: boundedRedactedString(
+      control.queued_at,
+      Limits.COMPACT_PREVIEW_CHARS,
+    ),
+    run_instance_id: boundedRedactedString(
+      control.run_instance_id,
+      Limits.COMPACT_PREVIEW_CHARS,
+    ),
+    status: boundedRedactedString(
+      control.status,
+      Limits.COMPACT_PREVIEW_CHARS,
+    ) as RunControlStatus,
+  };
+}

package/lib/control.ts

@@ -27,7 +27,27 @@ const REMOVED_FIELDS = new Set([
   "type",
 ]);
 
-function serializedInputBytes(input: unknown): number {
+export function isControlAction(value: string): boolean {
+  return ACTION_PATTERN.test(value);
+}
+
+export function normalizeControlAction(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("control.action is required");
+  }
+  const action = value.trim();
+  if (!isControlAction(action)) {
+    throw new Error(`invalid control action: ${action}`);
+  }
+  if (action.length > Limits.CONTROL_ACTION_MAX_LENGTH) {
+    throw new Error(
+      `control.action exceeds ${Limits.CONTROL_ACTION_MAX_LENGTH} ASCII characters`,
+    );
+  }
+  return action;
+}
+
+export function normalizeControlInput(input: unknown): unknown {
   let serialized: string | undefined;
   try {
     serialized = JSON.stringify(input);
@@ -37,7 +57,13 @@ function serializedInputBytes(input: unknown): number {
   if (serialized === undefined) {
     throw new Error("control.input must be JSON-serializable");
   }
-  return Buffer.byteLength(serialized);
+  const bytes = Buffer.byteLength(serialized);
+  if (bytes > Limits.CONTROL_INPUT_MAX_BYTES) {
+    throw new Error(
+      `control.input exceeds ${Limits.CONTROL_INPUT_MAX_BYTES} serialized bytes`,
+    );
+  }
+  return JSON.parse(serialized) as unknown;
 }
 
 function normalizeTarget(value: unknown): ControlRequest["target"] {
@@ -75,28 +101,17 @@ export function normalizeControlRequest(input: unknown): ControlRequest {
     throw new Error(`unsupported control fields: ${unknown.sort().join(", ")}`);
   }
   const target = normalizeTarget(record.target);
-  if (typeof record.action !== "string" || !record.action.trim()) {
-    throw new Error("control.action is required");
-  }
-  const action = record.action.trim();
-  if (!ACTION_PATTERN.test(action)) {
-    throw new Error(`invalid control action: ${action}`);
-  }
+  const action = normalizeControlAction(record.action);
   if (record.verbose !== undefined && typeof record.verbose !== "boolean") {
     throw new Error("control.verbose must be a boolean");
   }
-  if (
-    record.input !== undefined &&
-    serializedInputBytes(record.input) > Limits.CONTROL_INPUT_MAX_BYTES
-  ) {
-    throw new Error(
-      `control.input exceeds ${Limits.CONTROL_INPUT_MAX_BYTES} bytes`,
-    );
-  }
+  const normalizedInput = record.input === undefined
+    ? undefined
+    : normalizeControlInput(record.input);
   return {
     target,
     action,
-    ...(record.input !== undefined ? { input: record.input } : {}),
+    ...(normalizedInput !== undefined ? { input: normalizedInput } : {}),
     ...(record.verbose !== undefined ? { verbose: record.verbose } : {}),
   };
 }

package/lib/draft-sleep.ts

@@ -498,7 +498,7 @@ export function createDraftSleepScheduler(
             ...existing,
             failedStage: processed.stage ?? "result_processing",
             lastError: processed.error ?? "automatic draft review processing failed",
-            nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"draft\"}",
+            nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
             phase: "processing_failed",
             processingAttempts: (existing.processingAttempts ?? 0) + 1,
             updatedAt: now().toISOString(),
@@ -509,7 +509,7 @@ export function createDraftSleepScheduler(
           ...existing,
           failedStage: processed.stage ?? "review_result",
           lastError: processed.error ?? "automatic draft reviewer failed",
-          nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"draft\"}",
+          nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
           phase: "failed",
           runId: undefined,
           updatedAt: now().toISOString(),
@@ -552,7 +552,7 @@ export function createDraftSleepScheduler(
           attempts: (prior?.batchId === batch.batchId ? prior.attempts : 0) + 1,
           failedStage: "review_launch",
           lastError: error instanceof Error ? error.message : String(error),
-          nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"draft\"}",
+          nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
           batchId: batch.batchId,
           inputPath: batch.inputPath,
           phase: "failed",

package/lib/file-state.ts

@@ -4,24 +4,17 @@
  * Owns generic durable JSON file writes shared by registry config and async run state.
  */
 
+import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import {
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readFileSync,
-  realpathSync,
-  renameSync,
-  rmSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, parse, resolve } from "node:path";
 
-const FILE_MUTATION_LOCK_TIMEOUT_MS = 5000;
+const FILE_MUTATION_LOCK_TIMEOUT_MS = process.platform === "win32" ? 30000 : 15000;
 const FILE_MUTATION_LOCK_STALE_MS = 30000;
+const FILE_MUTATION_LOCK_RECLAIM_POLL_MS = 100;
+const FILE_MUTATION_LOCK_REMOVAL_GRACE_MS = 250;
+const FILE_MUTATION_LOCK_MAX_WAIT_MS = 50;
 const FILE_MUTATION_LOCK_ROOT = join(tmpdir(), "pi-actors-file-locks");
 
 function canonicalMutationPath(path: string): string {
@@ -56,6 +49,16 @@ export function mutationLockPath(path: string): string {
   return join(FILE_MUTATION_LOCK_ROOT, `${key}.lock`);
 }
 
+function isZombieProcess(pid: number): boolean {
+  if (process.platform === "linux") try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    return stat.slice(stat.lastIndexOf(")") + 2).startsWith("Z ");
+  } catch { return false; }
+  if (process.platform !== "darwin") return false;
+  const result = spawnSync("ps", ["-p", String(pid), "-o", "stat="], { encoding: "utf8" });
+  return result.status === 0 && result.stdout.trim().startsWith("Z");
+}
+
 function lockOwnerStatus(lockPath: string): "alive" | "dead" | "unknown" {
   try {
     const owner = JSON.parse(
@@ -65,6 +68,8 @@ function lockOwnerStatus(lockPath: string): "alive" | "dead" | "unknown" {
     if (!Number.isInteger(pid) || pid <= 0) return "unknown";
     try {
       process.kill(pid, 0);
+      if (Date.now() - statSync(lockPath).mtimeMs > FILE_MUTATION_LOCK_REMOVAL_GRACE_MS &&
+          isZombieProcess(pid)) return "dead";
       return "alive";
     } catch (error) {
       return (error as NodeJS.ErrnoException).code === "ESRCH"
@@ -77,6 +82,7 @@ function lockOwnerStatus(lockPath: string): "alive" | "dead" | "unknown" {
 }
 
 export interface FileMutationLockOptions {
+  onBeforeLockPublish?(): void;
   onBeforeReclaimRemove?(): void;
   onContention?(): void;
   onRemovalContention?(): void;
@@ -93,18 +99,41 @@ function readLockToken(lockPath: string): string | undefined {
   }
 }
 
+function prepareLockBoundary(lockPath: string, token: string, onBeforePublish?: () => void): string {
+  const pendingPath = `${lockPath}.${process.pid}.${token}.pending`;
+  try {
+    mkdirSync(pendingPath);
+    writeFileSync(join(pendingPath, "owner.json"), `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`, "utf8");
+    onBeforePublish?.();
+    return pendingPath;
+  } catch (error) {
+    try { rmSync(pendingPath, { recursive: true, force: true }); } catch {}
+    throw error;
+  }
+}
+
+function removeLockBoundary(lockPath: string, token: string | undefined): boolean {
+  if (readLockToken(lockPath) !== token) return false;
+  if (process.platform === "win32") try { rmSync(lockPath, { recursive: true, force: true, maxRetries: 20, retryDelay: 5 }); return true; } catch { return false; }
+  const removingPath = `${lockPath}.${process.pid}.${randomUUID()}.removing`;
+  try { renameSync(lockPath, removingPath); } catch { return false; }
+  try { rmSync(removingPath, { recursive: true, force: true }); } catch {}
+  return true;
+}
+
 function tryReclaimRemovalBoundary(reclaimPath: string): void {
   if (!existsSync(reclaimPath)) return;
   try {
-    const inspectedToken = readLockToken(reclaimPath);
     const age = Date.now() - statSync(reclaimPath).mtimeMs;
+    if (age <= FILE_MUTATION_LOCK_REMOVAL_GRACE_MS) return;
+    const inspectedToken = readLockToken(reclaimPath);
     const ownerStatus = lockOwnerStatus(reclaimPath);
     if (
       (ownerStatus === "dead" ||
         (ownerStatus === "unknown" && age > FILE_MUTATION_LOCK_STALE_MS)) &&
       readLockToken(reclaimPath) === inspectedToken
     ) {
-      rmSync(reclaimPath, { recursive: true, force: true });
+      removeLockBoundary(reclaimPath, inspectedToken);
     }
   } catch {
     /* another contender changed the boundary */
@@ -117,29 +146,20 @@ function withRemovalBoundary(
 ): boolean {
   const reclaimPath = `${lockPath}.reclaim`;
   const token = randomUUID();
+  const pendingPath = prepareLockBoundary(reclaimPath, token);
   try {
-    mkdirSync(reclaimPath);
+    try { renameSync(pendingPath, reclaimPath); } catch {
+      tryReclaimRemovalBoundary(reclaimPath);
+      return false;
+    }
     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;
+      action();
+      return true;
+    } finally {
+      removeLockBoundary(reclaimPath, token);
     }
-  } catch {
-    tryReclaimRemovalBoundary(reclaimPath);
-    return false;
-  }
-  try {
-    action();
-    return true;
   } finally {
-    if (readLockToken(reclaimPath) === token) {
-      rmSync(reclaimPath, { recursive: true, force: true });
-    }
+    try { rmSync(pendingPath, { recursive: true, force: true }); } catch {}
   }
 }
 
@@ -162,8 +182,7 @@ function tryReclaimMutationLock(
       readLockToken(lockPath) === inspectedToken
     ) {
       options.onBeforeReclaimRemove?.();
-      rmSync(lockPath, { recursive: true, force: true });
-      reclaimed = true;
+      reclaimed = removeLockBoundary(lockPath, inspectedToken);
     }
   })) {
     return false;
@@ -179,34 +198,40 @@ export function acquireFileMutationLock(
   const lockPath = mutationLockPath(path);
   const deadline = Date.now() + FILE_MUTATION_LOCK_TIMEOUT_MS;
   const token = randomUUID();
+  const pendingPath = prepareLockBoundary(lockPath, token, options.onBeforeLockPublish);
   let contentionReported = false;
-  for (;;) {
-    try {
-      mkdirSync(lockPath);
+  let nextReclaimAt = 0;
+  let waitMs = 10;
+  try {
+    for (;;) {
       try {
-        writeFileSync(
-          join(lockPath, "owner.json"),
-          `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`,
-          "utf8",
-        );
+        renameSync(pendingPath, lockPath);
+        break;
       } catch (error) {
-        rmSync(lockPath, { recursive: true, force: true });
-        throw error;
-      }
-      break;
-    } catch (error) {
-      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,
-        });
+        if (!contentionReported) {
+          contentionReported = true;
+          options.onContention?.();
+        }
+        const now = Date.now();
+        if (now >= nextReclaimAt) {
+          nextReclaimAt = now + FILE_MUTATION_LOCK_RECLAIM_POLL_MS;
+          if (tryReclaimMutationLock(lockPath, options)) {
+            waitMs = 10;
+            continue;
+          }
+        }
+        if (now >= deadline) {
+          throw new Error(`Timed out waiting for file mutation lock: ${canonicalMutationPath(path)}`, {
+            cause: error,
+          });
+        }
+        const jitter = Math.floor(Math.random() * Math.max(1, Math.floor(waitMs / 2)));
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, waitMs + jitter);
+        waitMs = Math.min(FILE_MUTATION_LOCK_MAX_WAIT_MS, waitMs + 5);
       }
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
     }
+  } finally {
+    try { rmSync(pendingPath, { recursive: true, force: true }); } catch {}
   }
   let released = false;
   return () => {
@@ -216,9 +241,7 @@ export function acquireFileMutationLock(
     let removalContentionReported = false;
     while (
       !withRemovalBoundary(lockPath, () => {
-        if (readLockToken(lockPath) === token) {
-          rmSync(lockPath, { recursive: true, force: true });
-        }
+        removeLockBoundary(lockPath, token);
       })
     ) {
       if (!removalContentionReported) {
@@ -244,11 +267,16 @@ export function withFileMutationLock<T>(
   }
 }
 
-export function writeTextAtomic(path: string, content: string): void {
+export function writeTextAtomic(
+  path: string,
+  content: string,
+  options: { onBeforeReplace?(): void } = {},
+): void {
   mkdirSync(dirname(path), { recursive: true });
   const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
   try {
     writeFileSync(tempPath, content, "utf8");
+    options.onBeforeReplace?.();
     renameSync(tempPath, path);
   } catch (error) {
     try {