@llblab/pi-actors 0.39.0 → 0.40.1

package/lib/recipes-usage.ts

@@ -6,8 +6,9 @@
 
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 
-import { writeJsonAtomic } from "./file-state.ts";
+import { withFileMutationLock, writeJsonAtomic } from "./file-state.ts";
 
 interface RecipesUsageRecord {
   calls?: number;
@@ -47,6 +48,19 @@ function getRecipeFingerprint(raw: Record<string, unknown>): string {
 
 export type RecipeLaunchKind = "direct" | "spawn" | "tool";
 
+export function getRecipeUsagePath(path: string): string {
+  return join(dirname(path), ".usage", `${basename(path)}.json`);
+}
+
+export function readRecipeUsage(path: string): Record<string, unknown> | undefined {
+  try {
+    const value = JSON.parse(readFileSync(getRecipeUsagePath(path), "utf8"));
+    return isRecord(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function launchCounterKey(
   kind: RecipeLaunchKind,
 ): "direct_calls" | "spawn_calls" | "tool_calls" {
@@ -59,19 +73,21 @@ export function recordRecipeLaunch(
   kind: RecipeLaunchKind = "direct",
 ): boolean {
   if (!existsSync(path)) return false;
-  try {
-    const raw = JSON.parse(readFileSync(path, "utf8"));
-    if (!isRecord(raw)) return false;
-    const usage: RecipesUsageRecord = isRecord(raw.usage) ? raw.usage : {};
-    const fingerprint = getRecipeFingerprint(raw);
-    const changed =
-      typeof usage.fingerprint === "string" &&
-      usage.fingerprint !== fingerprint;
-    const nowIso = now.toISOString();
-    const counterKey = launchCounterKey(kind);
-    writeJsonAtomic(path, {
-      ...raw,
-      usage: {
+  const usagePath = getRecipeUsagePath(path);
+  return withFileMutationLock(usagePath, () => {
+    try {
+      const raw = JSON.parse(readFileSync(path, "utf8"));
+      if (!isRecord(raw)) return false;
+      const storedUsage = readRecipeUsage(path);
+      const usage: RecipesUsageRecord =
+        storedUsage ?? (isRecord(raw.usage) ? raw.usage : {});
+      const fingerprint = getRecipeFingerprint(raw);
+      const changed =
+        typeof usage.fingerprint === "string" &&
+        usage.fingerprint !== fingerprint;
+      const nowIso = now.toISOString();
+      const counterKey = launchCounterKey(kind);
+      writeJsonAtomic(usagePath, {
         ...usage,
         calls: (changed ? 0 : normalizeCalls(usage.calls)) + 1,
         [counterKey]: (changed ? 0 : normalizeCalls(usage[counterKey])) + 1,
@@ -84,10 +100,10 @@ export function recordRecipeLaunch(
               reset_reason: "recipe content fingerprint changed",
             }
           : {}),
-      },
-    });
-    return true;
-  } catch {
-    return false;
-  }
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  });
 }

package/lib/registry.ts

@@ -4,13 +4,13 @@
  * Owns register/update/delete validation, persistence, runtime side effects, and result payloads
  */
 
-import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 
 import * as CommandTemplates from "./command-templates.ts";
 import * as Config from "./config.ts";
 import * as ExecutionOutput from "./execution-output.ts";
-import { writeJsonAtomic } from "./file-state.ts";
+import { withFileMutationLock, writeJsonAtomic } from "./file-state.ts";
 import * as Identity from "./identity.ts";
 import * as Paths from "./paths.ts";
 import * as RecipesReferences from "./recipes-references.ts";
@@ -20,7 +20,6 @@ export interface RegisterToolInput {
   name?: string;
   description?: string;
   async?: boolean;
-  state_dir?: string;
   template?: CommandTemplates.CommandTemplateValue | null;
   draft?: string;
   args?: string;
@@ -36,7 +35,6 @@ export interface RegisterToolResultDetails {
   draft?: string;
   promoted?: boolean;
   recipeName?: string;
-  state_dir?: string;
   template?: CommandTemplates.CommandTemplateValue;
   templateWarnings?: string[];
   tool: string;
@@ -194,7 +192,6 @@ function persistToolRecipe<TContext>(
   writeJsonAtomic(path, {
     description: cfg.description,
     ...(cfg.recipe?.async !== undefined ? { async: cfg.recipe.async } : {}),
-    ...(cfg.recipe?.state_dir ? { state_dir: cfg.recipe.state_dir } : {}),
     ...(cfg.storedArgs ? { args: cfg.storedArgs } : {}),
     ...(cfg.storedDefaults ? { defaults: cfg.storedDefaults } : {}),
     ...(cfg.recipe?.values ? { values: cfg.recipe.values } : {}),
@@ -238,6 +235,28 @@ function deleteTool<TContext>(
   };
 }
 
+function readAuthoritativeStoredTool<TContext>(
+  deps: RegisterToolRuntimeDeps<TContext>,
+  name: string,
+): { exists: boolean; tool?: Config.RegisteredTool } {
+  const path = getToolRecipePath(deps, name);
+  if (!existsSync(path)) return { exists: false };
+  try {
+    const normalized = Config.normalizeStoredTool(
+      name,
+      JSON.parse(readFileSync(path, "utf8")),
+      deps.reservedToolNames,
+    );
+    if (!normalized.cfg) return { exists: true };
+    return {
+      exists: true,
+      tool: { ...normalized.cfg, sourcePath: path },
+    };
+  } catch {
+    return { exists: true };
+  }
+}
+
 function getInputTemplate(
   value: CommandTemplates.CommandTemplateValue | null | undefined,
 ): CommandTemplates.CommandTemplateValue | null | undefined {
@@ -303,9 +322,6 @@ function buildConfig(
     ? {
         name: inputRecipe,
         ...(typeof input.async === "boolean" ? { async: input.async } : {}),
-        ...(typeof input.state_dir === "string" && input.state_dir.trim()
-          ? { state_dir: input.state_dir.trim() }
-          : {}),
         template: finalTemplate,
         ...(input.values && typeof input.values === "object"
           ? { values: input.values }
@@ -359,11 +375,11 @@ function buildConfig(
   };
 }
 
-export async function executeRegisterTool<TContext>(
+function executeRegisterToolUnlocked<TContext>(
   params: unknown,
   ctx: TContext,
   deps: RegisterToolRuntimeDeps<TContext>,
-): Promise<RegisterToolResult> {
+): RegisterToolResult {
   const input = params as RegisterToolInput;
   if (!input.name) return listTools(deps);
   const name = Identity.normalizeToolName(input.name);
@@ -382,10 +398,11 @@ export async function executeRegisterTool<TContext>(
   if (templateProvided && (template === null || template === ""))
     return deleteTool(name, ctx, deps);
   const tools = deps.getTools();
-  const existing = tools.get(name);
+  const authoritative = readAuthoritativeStoredTool(deps, name);
+  const existing = authoritative.tool ?? tools.get(name);
   const blocker = deps.getToolNameBlocker(name);
   if (blocker) throw new Error(ExecutionOutput.formatToolText(blocker));
-  if (existing && !input.update) {
+  if ((authoritative.exists || existing) && !input.update) {
     throw new Error(
       ExecutionOutput.formatToolText(
         `Tool "${name}" already registered. Use update=true to overwrite.`,
@@ -437,10 +454,23 @@ export async function executeRegisterTool<TContext>(
       defaults: cfg.defaults,
       ...(cfg.recipe?.async !== undefined ? { async: cfg.recipe.async } : {}),
       ...(cfg.recipe?.name ? { recipeName: cfg.recipe.name } : {}),
-      ...(cfg.recipe?.state_dir ? { state_dir: cfg.recipe.state_dir } : {}),
       ...(cfg.template ? { template: cfg.template } : {}),
       ...(templateWarnings.length > 0 ? { templateWarnings } : {}),
       tool: name,
     },
   };
 }
+
+export async function executeRegisterTool<TContext>(
+  params: unknown,
+  ctx: TContext,
+  deps: RegisterToolRuntimeDeps<TContext>,
+): Promise<RegisterToolResult> {
+  const input = params as RegisterToolInput;
+  if (!input.name) return executeRegisterToolUnlocked(params, ctx, deps);
+  const name = Identity.normalizeToolName(input.name);
+  if (!name) return executeRegisterToolUnlocked(params, ctx, deps);
+  return withFileMutationLock(getToolRecipePath(deps, name), () =>
+    executeRegisterToolUnlocked(params, ctx, deps),
+  );
+}

package/lib/runs-ownership.ts

@@ -0,0 +1,117 @@
+/**
+ * Async run state-directory ownership.
+ * Owns the marker proof required before launch and destructive retention.
+ */
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join, resolve } from "node:path";
+
+import { writeJsonAtomic } from "./file-state.ts";
+
+export const RUN_STATE_OWNERSHIP_FILE = ".pi-actors-run-state.json";
+
+interface RunStateOwnershipMarker {
+  created_at: string;
+  ownership_token: string;
+  run: string;
+  state_dir: string;
+  version: 1;
+}
+
+function markerPath(stateDir: string): string {
+  return join(stateDir, RUN_STATE_OWNERSHIP_FILE);
+}
+
+function comparablePath(path: string): string {
+  const resolved = resolve(path);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function assertCanonicalDirectory(stateDir: string): string {
+  const resolved = resolve(stateDir);
+  if (lstatSync(resolved).isSymbolicLink()) {
+    throw new Error(`Run state directory cannot be a symlink: ${resolved}`);
+  }
+  const canonical = realpathSync(resolved);
+  if (comparablePath(canonical) !== comparablePath(resolved)) {
+    throw new Error(`Run state directory has an ambiguous symlink alias: ${resolved}`);
+  }
+  return resolved;
+}
+
+function readMarker(stateDir: string): RunStateOwnershipMarker | undefined {
+  try {
+    const value = JSON.parse(readFileSync(markerPath(stateDir), "utf8")) as Partial<RunStateOwnershipMarker>;
+    if (
+      value.version !== 1 ||
+      typeof value.run !== "string" ||
+      typeof value.state_dir !== "string" ||
+      typeof value.ownership_token !== "string" ||
+      !value.ownership_token
+    ) {
+      return undefined;
+    }
+    return value as RunStateOwnershipMarker;
+  } catch {
+    return undefined;
+  }
+}
+
+function assertMarkerMatches(
+  marker: RunStateOwnershipMarker | undefined,
+  stateDir: string,
+  run: string,
+): RunStateOwnershipMarker {
+  if (!marker) {
+    throw new Error(`Run state ownership marker is missing or invalid: ${stateDir}`);
+  }
+  if (marker.state_dir !== stateDir || marker.run !== run) {
+    throw new Error(`Run state ownership marker does not match run ${run}: ${stateDir}`);
+  }
+  return marker;
+}
+
+export function claimRunStateDirectory(stateDir: string, run: string): string {
+  const resolved = resolve(stateDir);
+  if (existsSync(resolved) && lstatSync(resolved).isSymbolicLink()) {
+    throw new Error(`Run state directory cannot be a symlink: ${resolved}`);
+  }
+  mkdirSync(resolved, { recursive: true });
+  const canonical = assertCanonicalDirectory(resolved);
+  const existing = readMarker(canonical);
+  if (existing) {
+    assertMarkerMatches(existing, canonical, run);
+    return canonical;
+  }
+  const existingEntries = readdirSync(canonical).filter(
+    (entry) => entry !== ".start.lock",
+  );
+  if (existingEntries.length > 0) {
+    throw new Error(`Refusing to claim existing non-run directory: ${canonical}`);
+  }
+  writeJsonAtomic(markerPath(canonical), {
+    created_at: new Date().toISOString(),
+    ownership_token: randomUUID(),
+    run,
+    state_dir: canonical,
+    version: 1,
+  } satisfies RunStateOwnershipMarker);
+  return canonical;
+}
+
+export function assertOwnedRunStateDirectory(
+  stateDir: string,
+  run: string,
+): string {
+  const canonical = assertCanonicalDirectory(stateDir);
+  assertMarkerMatches(readMarker(canonical), canonical, run);
+  return canonical;
+}

package/lib/runs-process.ts

@@ -1,12 +1,36 @@
 /**
  * Async run process identity helpers.
- * Owns liveness checks and Linux runner identity matching for run-owned processes.
+ * Owns cross-platform liveness and stable runner process identity proofs.
  */
 
-import { existsSync, readFileSync, readlinkSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { platform } from "node:os";
 import { resolve } from "node:path";
 
+export interface RunProcessIdentity {
+  command: string;
+  cwd?: string;
+  platform: NodeJS.Platform;
+  start_time: string;
+}
+
+export type RunProcessIdentityStatus =
+  | "valid"
+  | "dead_pid"
+  | "owner_mismatch"
+  | "unsupported_proof";
+
+export interface RunProcessIdentityResult {
+  status: RunProcessIdentityStatus;
+  valid: boolean;
+}
+
+type ProcessIdentityReader = (
+  pid: number,
+  runtimePlatform: NodeJS.Platform,
+) => RunProcessIdentity | undefined;
+
 export function isAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
@@ -16,25 +40,123 @@ export function isAlive(pid: number): boolean {
   }
 }
 
-export function pidMatchesRun(
+function readLinuxIdentity(pid: number): RunProcessIdentity | undefined {
+  if (!existsSync(`/proc/${pid}`)) return undefined;
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    const close = stat.lastIndexOf(")");
+    const fields = stat.slice(close + 2).trim().split(/\s+/);
+    const startTime = fields[19];
+    if (!startTime) return undefined;
+    return {
+      command: readFileSync(`/proc/${pid}/cmdline`, "utf8").replaceAll("\0", " ").trim(),
+      cwd: readlinkSync(`/proc/${pid}/cwd`),
+      platform: "linux",
+      start_time: startTime,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function readDarwinIdentity(pid: number): RunProcessIdentity | undefined {
+  const result = spawnSync(
+    "ps",
+    ["-p", String(pid), "-o", "lstart=", "-o", "command="],
+    { encoding: "utf8" },
+  );
+  if (result.status !== 0) return undefined;
+  const match = result.stdout.trim().match(/^(.{24})\s+(.+)$/s);
+  if (!match) return undefined;
+  return {
+    command: match[2].trim(),
+    platform: "darwin",
+    start_time: match[1].trim(),
+  };
+}
+
+function readWindowsIdentity(pid: number): RunProcessIdentity | undefined {
+  const command = [
+    `$p = Get-CimInstance Win32_Process -Filter \"ProcessId = ${pid}\";`,
+    "if ($null -eq $p) { exit 3 };",
+    "$p | Select-Object CreationDate,ExecutablePath,CommandLine | ConvertTo-Json -Compress",
+  ].join(" ");
+  const result = spawnSync(
+    "powershell.exe",
+    ["-NoProfile", "-NonInteractive", "-Command", command],
+    { encoding: "utf8", windowsHide: true },
+  );
+  if (result.status !== 0) return undefined;
+  try {
+    const value = JSON.parse(result.stdout) as Record<string, unknown>;
+    if (typeof value.CreationDate !== "string") return undefined;
+    const executable = typeof value.ExecutablePath === "string" ? value.ExecutablePath : "";
+    const commandLine = typeof value.CommandLine === "string" ? value.CommandLine : "";
+    return {
+      command: `${executable}\n${commandLine}`.trim(),
+      platform: "win32",
+      start_time: value.CreationDate,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function readProcessIdentity(
+  pid: number,
+  runtimePlatform: NodeJS.Platform = platform(),
+): RunProcessIdentity | undefined {
+  if (runtimePlatform === "linux") return readLinuxIdentity(pid);
+  if (runtimePlatform === "darwin") return readDarwinIdentity(pid);
+  if (runtimePlatform === "win32") return readWindowsIdentity(pid);
+  return undefined;
+}
+
+export function captureRunProcessIdentity(
   pid: number,
   cwd: string,
   stateDir: string,
   runnerPath: string,
-): boolean {
-  if (platform() !== "linux" || !existsSync(`/proc/${pid}`))
-    return isAlive(pid);
-  try {
-    const procCwd = readlinkSync(`/proc/${pid}/cwd`);
-    const cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8");
-    return (
-      procCwd === resolve(cwd) &&
-      cmdline.includes(runnerPath) &&
-      cmdline.includes(stateDir)
-    );
-  } catch {
-    return false;
+  runtimePlatform: NodeJS.Platform = platform(),
+  reader: ProcessIdentityReader = readProcessIdentity,
+): RunProcessIdentity | undefined {
+  const identity = reader(pid, runtimePlatform);
+  if (!identity) return undefined;
+  if (!identity.command.includes(runnerPath) || !identity.command.includes(stateDir)) {
+    return undefined;
+  }
+  const resolvedCwd = resolve(cwd);
+  const canonicalCwd = existsSync(resolvedCwd)
+    ? realpathSync.native(resolvedCwd)
+    : resolvedCwd;
+  const expectedCwd =
+    runtimePlatform === "win32" ? canonicalCwd.toLowerCase() : canonicalCwd;
+  const actualCwd =
+    runtimePlatform === "win32" && identity.cwd
+      ? identity.cwd.toLowerCase()
+      : identity.cwd;
+  if (actualCwd && actualCwd !== expectedCwd) return undefined;
+  return identity;
+}
+
+export function verifyRunProcessIdentity(
+  pid: number,
+  expected: RunProcessIdentity | undefined,
+  runtimePlatform: NodeJS.Platform = platform(),
+  reader: ProcessIdentityReader = readProcessIdentity,
+  alive: (pid: number) => boolean = isAlive,
+): RunProcessIdentityResult {
+  if (!alive(pid)) return { status: "dead_pid", valid: false };
+  if (!expected || expected.platform !== runtimePlatform) {
+    return { status: "unsupported_proof", valid: false };
   }
+  const current = reader(pid, runtimePlatform);
+  if (!current) return { status: "unsupported_proof", valid: false };
+  const valid =
+    current.start_time === expected.start_time &&
+    current.command === expected.command &&
+    current.cwd === expected.cwd;
+  return { status: valid ? "valid" : "owner_mismatch", valid };
 }
 
 export function isWithinRunnerIdentityGrace(

package/lib/runs-retention.ts

@@ -3,6 +3,7 @@
  * Owns terminal-run archive and prune filesystem behavior.
  */
 
+import { createHash } from "node:crypto";
 import { cpSync, mkdirSync, renameSync, rmSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
@@ -12,6 +13,16 @@ import {
   type RunArtifactDeclaration,
 } from "./runs-artifacts.ts";
 import { safeRunId } from "./runs-identity.ts";
+import { assertOwnedRunStateDirectory } from "./runs-ownership.ts";
+
+function retainedArtifactFilename(name: string, path: string): string {
+  const readableName = name.replace(/[^A-Za-z0-9_.-]+/g, "_") || "artifact";
+  const identity = createHash("sha256")
+    .update(`${name}\0${path}`)
+    .digest("hex")
+    .slice(0, 8);
+  return `${readableName}-${identity}--${basename(path)}`;
+}
 
 function archivePathFor(run: string, stateDir: string): string {
   const archiveRoot = join(dirname(stateDir), "archived");
@@ -27,6 +38,7 @@ export function archiveTerminalRun(
 ): Record<string, unknown> {
   const stateDir = String(status.state_dir);
   const run = String(status.run ?? basename(stateDir));
+  assertOwnedRunStateDirectory(stateDir, run);
   const archiveDir = archivePathFor(run, stateDir);
   renameSync(stateDir, archiveDir);
   mkdirSync(stateDir, { recursive: true });
@@ -45,9 +57,11 @@ export function archiveTerminalRun(
 export function pruneTerminalRun(
   status: Record<string, unknown>,
   options: { preserveArtifacts?: boolean } = {},
+  deps: { copyArtifact?: typeof cpSync } = {},
 ): Record<string, unknown> {
   const stateDir = String(status.state_dir);
   const run = String(status.run ?? basename(stateDir));
+  assertOwnedRunStateDirectory(stateDir, run);
   const manifest = resolveArtifactManifest(
     status.artifacts as Record<string, RunArtifactDeclaration> | undefined,
   );
@@ -61,8 +75,14 @@ export function pruneTerminalRun(
     mkdirSync(preserveRoot, { recursive: true });
     for (const [name, artifact] of Object.entries(manifest)) {
       if (!artifact.exists) continue;
-      const target = join(preserveRoot, basename(artifact.path));
-      cpSync(artifact.path, target, { force: true });
+      const target = join(
+        preserveRoot,
+        retainedArtifactFilename(name, artifact.path),
+      );
+      (deps.copyArtifact ?? cpSync)(artifact.path, target, {
+        force: true,
+        preserveTimestamps: true,
+      });
       preserved[name] = target;
     }
   }