@llblab/pi-actors 0.41.1 → 0.42.1

package/dist/lib/tools-inspect.js

@@ -6,11 +6,13 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import * as AsyncRuns from "./async-runs.js";
 import * as Limits from "./limits.js";
 import * as Messages from "./messages.js";
 import * as Paths from "./paths.js";
 import * as RecipesDiscovery from "./recipes-discovery.js";
+import * as ReviewDiagnostics from "./review-diagnostics.js";
 import * as Rooms from "./rooms.js";
 import * as Schema from "./schema.js";
 import * as ToolsAccess from "./tools-access.js";
@@ -18,6 +20,14 @@ import * as ToolsMailbox from "./tools-mailbox.js";
 import * as ToolsResponse from "./tools-response.js";
 const asRecord = ToolsResponse.asRecord;
 const maybeJsonText = ToolsResponse.maybeJsonText;
+function compactAutomaticReviewDiagnostics(diagnostics) {
+    const draft = asRecord(diagnostics.draft_review);
+    const tool = asRecord(diagnostics.tool_review);
+    return [
+        `automatic_reviews draft=${String(draft.phase ?? "idle")} tool=${String(tool.phase ?? "idle")}`,
+        `lineages=${String(diagnostics.lineage_count ?? 0)} revision_snapshots=${String(diagnostics.revision_snapshots ?? 0)}`,
+    ].join("\n");
+}
 function compactRunMessages(messages) {
     if (messages.length === 0)
         return "\n(no actor messages)";
@@ -220,8 +230,9 @@ function getPiActorsRuntimeStatus() {
     catch {
         git_commit = undefined;
     }
-    const entrypoint = new URL(import.meta.url).pathname;
+    const entrypoint = fileURLToPath(import.meta.url);
     return {
+        automatic_recipe_review: Paths.isAutomaticRecipeReviewEnabled(),
         entrypoint,
         git_commit,
         mode: entrypoint.includes("/dist/") ? "dist" : "source",
@@ -233,7 +244,7 @@ function getPiActorsRuntimeStatus() {
     };
 }
 function compactPiActorsRuntimeStatus(status) {
-    return `\npi-actors version=${String(status.version)} mode=${String(status.mode)} path=${String(status.package_root)} entrypoint=${String(status.entrypoint)}${status.git_commit ? ` git=${String(status.git_commit)}` : ""}`;
+    return `\npi-actors version=${String(status.version)} mode=${String(status.mode)} automatic_review=${String(status.automatic_recipe_review)} path=${String(status.package_root)} entrypoint=${String(status.entrypoint)}${status.git_commit ? ` git=${String(status.git_commit)}` : ""}`;
 }
 function isStaleClaim(message, now) {
     if (message.status !== "claimed")
@@ -436,8 +447,21 @@ export function createInspectToolDefinition(deps = {}) {
                 if (view !== "status" &&
                     view !== "summary" &&
                     view !== "doctor" &&
-                    view !== "imports") {
-                    throw new Error("inspect recipes supports view=status, view=summary, view=doctor, or view=imports.");
+                    view !== "imports" &&
+                    view !== "reviews") {
+                    throw new Error("inspect recipes supports view=status, view=summary, view=doctor, view=imports, or view=reviews.");
+                }
+                if (view === "reviews") {
+                    const diagnostics = ReviewDiagnostics.readAutomaticReviewDiagnostics({
+                        recipeRoot: deps.recipeRoot ?? Paths.getRecipeRoot(),
+                    });
+                    return {
+                        content: [{
+                                type: "text",
+                                text: maybeJsonText(diagnostics, input.verbose === true, compactAutomaticReviewDiagnostics(diagnostics)),
+                            }],
+                        details: diagnostics,
+                    };
                 }
                 const discovered = RecipesDiscovery.discoverRecipeSources([
                     {

package/dist/lib/tools-local.js

@@ -100,6 +100,10 @@ export function createRuntimeToolDefinition(cfg, exec) {
     }
     if (isAsyncRecipe)
         paramSchema.run_id = Schema.stringSchema("Optional run id override for this async template recipe invocation.");
+    if (isAsyncRecipe) {
+        paramSchema.correlation_id = Schema.stringSchema("Optional workflow correlation id preserved in terminal follow-up delivery.");
+        paramSchema.transport_context = Schema.looseObjectSchema("Optional originating transport route preserved for detached terminal follow-up.");
+    }
     return {
         name: cfg.name,
         label: cfg.name,
@@ -108,13 +112,15 @@ export function createRuntimeToolDefinition(cfg, exec) {
         promptSnippet: isRecipe
             ? Prompts.formatRecipeToolPromptSnippet(cfg.recipe?.name ?? String(cfg.template), isAsyncRecipe)
             : Prompts.formatRegisteredToolPromptSnippet(cfg.template),
-        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+        async execute(toolCallId, params, signal, _onUpdate, ctx) {
             try {
-                if (cfg.sourcePath)
-                    RecipesUsage.recordRecipeLaunch(cfg.sourcePath, new Date(), "tool");
+                if (cfg.sourcePath &&
+                    !RecipesUsage.recordRecipeLaunch(cfg.sourcePath, new Date(), "tool")) {
+                    throw new Error(`Recipe launch rejected because its source changed during activation: ${cfg.sourcePath}. Reload recipe tools and retry.`);
+                }
                 if (isAsyncRecipe) {
                     const input = params;
-                    const { run_id, ...values } = input;
+                    const { correlation_id, run_id, transport_context, ...values } = input;
                     const base = cfg.recipe ? cfg.recipe : { file: String(cfg.template) };
                     const runId = typeof run_id === "string" && run_id.trim()
                         ? run_id.trim()
@@ -122,6 +128,17 @@ export function createRuntimeToolDefinition(cfg, exec) {
                     const meta = AsyncRuns.startRun({
                         ...base,
                         launch_source: "tool",
+                        launch_correlation: {
+                            ...(typeof correlation_id === "string"
+                                ? { correlation_id } : {}),
+                            tool_call_id: toolCallId,
+                        },
+                        ...(transport_context &&
+                            typeof transport_context === "object" &&
+                            !Array.isArray(transport_context)
+                            ? {
+                                transport_context: transport_context,
+                            } : {}),
                         ownerId: getRunOwnerId(ctx),
                         run_id: runId,
                         tool: cfg.name,

package/dist/lib/tools-message.d.ts

@@ -5,5 +5,6 @@
  */
 export interface ActorMessageToolDeps<TContext = unknown> {
     getTool?: (name: string) => any | undefined;
+    handleRuntimeMessage?: (type: string, body: unknown) => Record<string, unknown>;
 }
 export declare function createActorMessageToolDefinition<TContext = unknown>(deps?: ActorMessageToolDeps<TContext>): any;

package/dist/lib/tools-message.js

@@ -274,7 +274,14 @@ export function createActorMessageToolDefinition(deps = {}) {
                     ]
                     : [];
                 if (message.type === "control.kill") {
-                    result = AsyncRuns.killRun(address.value);
+                    result = typeof status.run_instance_id === "string"
+                        ? AsyncRuns.killRun(address.value, {
+                            ...(typeof status.ownerId === "string"
+                                ? { ownerId: status.ownerId }
+                                : {}),
+                            runInstanceId: status.run_instance_id,
+                        })
+                        : { killed: false, reason: "run generation unavailable" };
                 }
                 else if (message.type === "control.archive") {
                     result = AsyncRuns.archiveRun(address.value);
@@ -344,24 +351,29 @@ export function createActorMessageToolDefinition(deps = {}) {
                 };
             }
             else if (address.kind === "tool" && address.value) {
-                const tool = deps.getTool?.(address.value);
-                if (!tool || typeof tool.execute !== "function") {
-                    throw new Error(`tool actor not found or not executable: ${address.value}`);
+                if (address.value === "pi-actors" && deps.handleRuntimeMessage) {
+                    result = deps.handleRuntimeMessage(message.type, message.body);
                 }
-                const toolParams = messageBodyToToolParams(message);
-                let toolResult;
-                try {
-                    toolResult = await tool.execute(`message:${message.type}`, toolParams, _signal, _onUpdate, ctx);
-                }
-                catch (error) {
-                    throw formatToolActorFailure(address.value, message, toolParams, error);
+                else {
+                    const tool = deps.getTool?.(address.value);
+                    if (!tool || typeof tool.execute !== "function") {
+                        throw new Error(`tool actor not found or not executable: ${address.value}`);
+                    }
+                    const toolParams = messageBodyToToolParams(message);
+                    let toolResult;
+                    try {
+                        toolResult = await tool.execute(`message:${message.type}`, toolParams, _signal, _onUpdate, ctx);
+                    }
+                    catch (error) {
+                        throw formatToolActorFailure(address.value, message, toolParams, error);
+                    }
+                    result = {
+                        invoked: true,
+                        sent: true,
+                        tool: address.value,
+                        tool_result: toolResult,
+                    };
                 }
-                result = {
-                    invoked: true,
-                    sent: true,
-                    tool: address.value,
-                    tool_result: toolResult,
-                };
             }
             else if (address.kind === "coordinator" || address.kind === "session") {
                 if (!message.from) {

package/dist/lib/tools-spawn.js

@@ -6,10 +6,12 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
+import { withFileMutationLock } from "./file-state.js";
 import * as Messages from "./messages.js";
 import * as ModelContext from "./model-context.js";
 import * as Paths from "./paths.js";
 import * as RecipesDiscovery from "./recipes-discovery.js";
+import * as RecipesUsage from "./recipes-usage.js";
 import * as Rooms from "./rooms.js";
 import * as Schema from "./schema.js";
 import * as ToolsResponse from "./tools-response.js";
@@ -62,7 +64,8 @@ function writeSpawnDraftRecipe(input, meta) {
         ...(defaults ? { defaults } : {}),
         template: input.template,
     };
-    writeFileSync(path, `${JSON.stringify(recipe, null, 2)}\n`, { flag: "wx" });
+    withFileMutationLock(root, () => withFileMutationLock(path, () => writeFileSync(path, `${JSON.stringify(recipe, null, 2)}\n`, { flag: "wx" })));
+    RecipesUsage.recordRecipeLaunch(path, new Date(), "spawn", Paths.getRecipeRoot());
     return path;
 }
 function enhanceSpawnRecipeError(error, recipe) {
@@ -92,6 +95,7 @@ export function createSpawnToolDefinition() {
         parameters: Schema.objectSchema({
             artifacts: Schema.looseObjectSchema("Optional named artifact paths for the spawned actor."),
             as: Schema.stringSchema("Optional actor address for the spawned run, e.g. run:<id>."),
+            correlation_id: Schema.stringSchema("Optional workflow correlation id preserved in terminal follow-up delivery."),
             file: Schema.stringSchema("Optional template recipe JSON file. Bare names resolve under ~/.pi/agent/recipes."),
             recipe: Schema.stringSchema("Alias for file; template recipe JSON file/name to spawn."),
             template: Schema.unionSchema([
@@ -100,9 +104,10 @@ export function createSpawnToolDefinition() {
                 Schema.looseObjectSchema("Inline command-template object with flags such as parallel, repeat, retry, failure, and nested template."),
             ]),
             values: Schema.looseObjectSchema("Runtime placeholder values passed to the actor."),
+            transport_context: Schema.looseObjectSchema("Optional originating transport route preserved for detached terminal follow-up, e.g. Telegram chat_id and thread_id."),
             verbose: Schema.booleanSchema("Return full JSON instead of compact text."),
         }, []),
-        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        async execute(toolCallId, params, _signal, _onUpdate, ctx) {
             const input = asRecord(params);
             if (input.state_dir !== undefined) {
                 throw new Error("spawn.state_dir is not supported; run state is runtime-owned so run:<id> remains addressable and retention-safe.");
@@ -118,7 +123,14 @@ export function createSpawnToolDefinition() {
                 meta = AsyncRuns.startRun({
                     file: recipe,
                     launch_source: "spawn",
+                    launch_correlation: {
+                        ...(typeof input.correlation_id === "string"
+                            ? { correlation_id: input.correlation_id } : {}),
+                        tool_call_id: toolCallId,
+                    },
                     ownerId: getRunOwnerId(ctx),
+                    ...(input.transport_context
+                        ? { transport_context: asRecord(input.transport_context) } : {}),
                     run_id: runId,
                     ...(input.template !== undefined
                         ? {

package/dist/lib/tools.d.ts

@@ -15,6 +15,7 @@ export interface CoreActorToolDefinitionDeps<TContext extends RuntimeToolContext
     configPath: string;
     getActiveTools: () => string[];
     getRuntimeTool: (name: string) => unknown;
+    handleRuntimeMessage?: (type: string, body: unknown) => Record<string, unknown>;
     registryRuntime: Pick<RegisterToolRuntimeDeps<TContext>, "getToolNameBlocker" | "getTools" | "notify" | "registerRuntimeTool">;
     setActiveTools: (toolNames: string[]) => void;
 }

package/dist/lib/tools.js

@@ -38,6 +38,7 @@ export function createCoreActorToolDefinitions(deps) {
         ToolsSpawn.createSpawnToolDefinition(),
         ToolsMessage.createActorMessageToolDefinition({
             getTool: (name) => deps.getRuntimeTool(name),
+            handleRuntimeMessage: deps.handleRuntimeMessage,
         }),
         ToolsInspect.createInspectToolDefinition({
             getTool: (name) => deps.getRuntimeTool(name),

package/dist/recipes/draft-review.json

@@ -0,0 +1,24 @@
+{
+  "async": true,
+  "args": [
+    "input_path:path",
+    "model:string",
+    "thinking:string"
+  ],
+  "defaults": {
+    "model": "{current_model}",
+    "thinking": "{current_thinking}"
+  },
+  "description": "Read-only background reviewer for one immutable automatic draft-memory batch.",
+  "mailbox": {
+    "accepts": [
+      "control.kill"
+    ],
+    "emits": [
+      "command.done",
+      "run.done",
+      "run.failed"
+    ]
+  },
+  "template": "pi -p --model {model} --thinking {thinking} --no-tools @{input_path} Review the attached immutable pi-actors draft batch. Evaluate every draft independently using launch history, universality, flexibility, parameterization, duplication, safety, and likely future usefulness. Treat draft and sha256 fields as batch-local opaque occurrence/content-group identifiers and return them verbatim. Choose exactly one promote or discard decision per draft; there is no selection quota. Promotion requires a unique absent snake_case target and targetSha256 null. Never return recipe content: the executor derives the exact immutable captured source. Invalid or secret-touching drafts must be discarded. Include assessment with launches, universality, flexibility, futureUsefulness, and safety. Do not mutate, move, register, or delete recipes. End stdout with DRAFT_REVIEW_RESULT on its own line followed by exactly one JSON object with batchId, createdAt, and decisions."
+}

package/dist/recipes/tool-review.json

@@ -0,0 +1,24 @@
+{
+  "async": true,
+  "args": [
+    "input_path:path",
+    "model:string",
+    "thinking:string"
+  ],
+  "defaults": {
+    "model": "{current_model}",
+    "thinking": "{current_thinking}"
+  },
+  "description": "Read-only background reviewer for one immutable 36-tool evolution portfolio.",
+  "mailbox": {
+    "accepts": [
+      "control.kill"
+    ],
+    "emits": [
+      "command.done",
+      "run.done",
+      "run.failed"
+    ]
+  },
+  "template": "pi -p --model {model} --thinking {thinking} --no-tools @{input_path} Review the attached immutable pi-actors active-tool portfolio. Evaluate all 36 tools independently using lifetime and revision usage, adaptability, redundancy, safety, contract quality, and likely future usefulness. Treat source/name and sha256 fields as batch-local opaque occurrence/content-group identifiers, return them verbatim, and infer exact duplication only from a shared content group. Choose exactly one keep, evolve, demote, or merge decision per tool; there is no action quota. evolve may only rename one unchanged captured recipe, demote moves the unchanged recipe to draft memory, and merge may only deduplicate at least two canonically identical captured recipes. Never return recipe or outputs fields; replace and split require explicit operator-authored mutation and are unavailable to automatic review. Do not mutate, register, move, or delete recipes. End stdout with TOOL_REVIEW_RESULT on its own line followed by exactly one JSON object with reviewId, createdAt, and decisions."
+}

package/dist/scripts/async-runner.mjs

@@ -135,7 +135,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
     try {
       return readdirSync(sessionDir, { withFileTypes: true })
         .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
-        .map((entry) => relative(stateDir, join(sessionDir, entry.name)))
+        .map((entry) => relative(stateDir, join(sessionDir, entry.name)).replaceAll("\\", "/"))
         .sort();
     } catch {
       return [];
@@ -167,12 +167,12 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...(recipeContext ? { recipe_context: recipeContext } : {}),
       command: commandDetail,
       ...(materialized.promptFile
-        ? { prompt_file: relative(stateDir, materialized.promptFile) }
+        ? { prompt_file: relative(stateDir, materialized.promptFile).replaceAll("\\", "/") }
         : {}),
       ...(materialized.promptBytes
         ? { prompt_bytes: materialized.promptBytes }
         : {}),
-      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir) } : {}),
+      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir).replaceAll("\\", "/") } : {}),
       attempts: [],
       semantic_acceptance:
         options?.evidenceContext?.acceptOutput === "review_evidence" ||
@@ -209,11 +209,11 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       attempts.push({
         attempt,
         stdout: {
-          path: relative(stateDir, stdoutFile),
+          path: relative(stateDir, stdoutFile).replaceAll("\\", "/"),
           bytes: existsSync(stdoutFile) ? statSync(stdoutFile).size : 0,
         },
         stderr: {
-          path: relative(stateDir, stderrFile),
+          path: relative(stateDir, stderrFile).replaceAll("\\", "/"),
           bytes: existsSync(stderrFile) ? statSync(stderrFile).size : 0,
         },
       });
@@ -248,12 +248,12 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...(recipeContext ? { recipe_context: recipeContext } : {}),
       command: commandDetail,
       ...(materialized.promptFile
-        ? { prompt_file: relative(stateDir, materialized.promptFile) }
+        ? { prompt_file: relative(stateDir, materialized.promptFile).replaceAll("\\", "/") }
         : {}),
       ...(materialized.promptBytes
         ? { prompt_bytes: materialized.promptBytes }
         : {}),
-      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir) } : {}),
+      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir).replaceAll("\\", "/") } : {}),
       ...(commandSessionFiles(sessionDir).length > 0
         ? { session_files: commandSessionFiles(sessionDir) }
         : {}),
@@ -386,7 +386,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       command: commandDetail,
       ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
       ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
-      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir) } : {}),
+      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir).replaceAll("\\", "/") } : {}),
     });
     progressRunning();
     const captureDir = join(stateDir, "captures", commandId);
@@ -457,7 +457,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...captureDetails(result),
       ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
       ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
-      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir) } : {}),
+      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir).replaceAll("\\", "/") } : {}),
       ...(commandSessionFiles(session.sessionDir).length > 0
         ? { session_files: commandSessionFiles(session.sessionDir) }
         : {}),

package/dist/scripts/build-dist.mjs

@@ -20,13 +20,18 @@ import { join } from "node:path";
 
 function run(command, args) {
   const result = spawnSync(command, args, { stdio: "inherit" });
+  if (result.error) throw result.error;
   if (result.status !== 0) process.exit(result.status ?? 1);
 }
 
 rmSync("dist", { recursive: true, force: true });
 mkdirSync("dist", { recursive: true });
 
-run("tsc", ["-p", "tsconfig.build.json"]);
+run(process.execPath, [
+  join("node_modules", "typescript", "bin", "tsc"),
+  "-p",
+  "tsconfig.build.json",
+]);
 
 mkdirSync(join("dist", "pi-actors"), { recursive: true });
 writeFileSync(

package/dist/scripts/conformance.mjs

@@ -28,7 +28,12 @@ function packageRoot() {
 
 const result = spawnSync(
   process.execPath,
-  ["--experimental-strip-types", "--test", ...conformanceSuites],
+  [
+    "--experimental-strip-types",
+    "--test",
+    "--test-concurrency=1",
+    ...conformanceSuites,
+  ],
   { cwd: packageRoot(), encoding: "utf8", stdio: "pipe" },
 );
 

package/dist/scripts/recipe-utils.mjs

@@ -16,7 +16,7 @@ import {
   statSync,
   writeFileSync,
 } from "node:fs";
-import { dirname, extname, join, relative, resolve } from "node:path";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 
 function usage() {
   console.error(`Usage:
@@ -101,7 +101,7 @@ function collectRunSummary(rootValue) {
   const root = resolve(
     rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
   );
-  const files = walkFiles(root, 2).filter((file) => file.endsWith("/run.json"));
+  const files = walkFiles(root, 2).filter((file) => basename(file) === "run.json");
   const rows = [];
   for (const file of files) {
     const run = readJson(file);
@@ -118,7 +118,7 @@ function collectRunSummary(rootValue) {
     const progress = readJson(join(runDir, "progress.json"));
     const result = readJson(join(runDir, "result.json"));
     rows.push({
-      run: run.run_id ?? run.run ?? relative(root, file).split("/")[0],
+      run: run.run_id ?? run.run ?? relative(root, file).split(sep)[0],
       status: getRunStatus(run, progress, result),
       recipe: run.recipe ?? run.recipe_file ?? "",
       updated:

package/dist/scripts/release-gates.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/** Reproducible exact-tree, Domain DAG, secret-hygiene, and ABCd release gates. */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, extname, join, normalize, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const temp = mkdtempSync(join(tmpdir(), "pi-actors-release-index-"));
+const indexPath = join(temp, "index");
+const gitEnv = { ...process.env, GIT_INDEX_FILE: indexPath };
+const failures = [];
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+    ...options,
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      `${command} ${args.join(" ")} failed (${result.status}): ${(result.stderr || result.stdout || "no output").trim()}`,
+    );
+  }
+  return result.stdout;
+}
+
+function check(condition, message) {
+  if (!condition) failures.push(message);
+}
+
+function stagedText(path) {
+  const result = spawnSync("git", ["show", `:${path}`], {
+    cwd: root,
+    env: gitEnv,
+    encoding: "buffer",
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.status !== 0) {
+    failures.push(`could not read staged file: ${path}`);
+    return undefined;
+  }
+  const bytes = result.stdout;
+  if (bytes.includes(0)) return undefined;
+  return bytes.toString("utf8");
+}
+
+function sourceImports(source) {
+  return [...source.matchAll(/^import(?:\s+type)?\s+(?:[^"']+?\s+from\s+)?["']([^"']+)["'];?$/gmu)]
+    .map((match) => match[1]);
+}
+
+function resolveLocalImport(from, specifier, sourceSet) {
+  if (!specifier.startsWith(".")) return undefined;
+  const base = normalize(join(dirname(from), specifier)).replaceAll("\\", "/");
+  const candidates = extname(base)
+    ? [base.replace(/\.js$/u, ".ts")]
+    : [`${base}.ts`, `${base}/index.ts`];
+  return candidates.find((candidate) => sourceSet.has(candidate));
+}
+
+try {
+  run("git", ["read-tree", "HEAD"], { env: gitEnv });
+  run("git", ["add", "-A"], { env: gitEnv });
+  run("git", ["diff", "--cached", "--check"], { env: gitEnv });
+  const files = run("git", ["ls-files", "-z"], { env: gitEnv })
+    .split("\0")
+    .filter(Boolean);
+  const fileSet = new Set(files);
+  console.log(`[release] exact temporary index: ${files.length} files`);
+
+  const secretPatterns = [
+    [/-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----[\s\S]{80,}?-----END(?: [A-Z0-9]+)? PRIVATE KEY-----/u, "private-key block"],
+    [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/u, "AWS access key"],
+    [/\bgithub_pat_[A-Za-z0-9_]{20,}\b|\bgh[pousr]_[A-Za-z0-9]{20,}\b/u, "GitHub token"],
+    [/\bglpat-[A-Za-z0-9_-]{20,}\b|\bnpm_[A-Za-z0-9]{20,}\b|\bxox[baprs]-[A-Za-z0-9-]{10,}\b/u, "service token"],
+  ];
+  const publicPath = /^(?:README\.md|AGENTS\.md|BACKLOG\.md|CHANGELOG\.md|docs\/|skills\/|recipes\/)/u;
+  for (const path of files) {
+    const text = stagedText(path);
+    if (text === undefined) continue;
+    if (!path.startsWith("tests/") && !path.startsWith("fixtures/")) {
+      for (const [pattern, label] of secretPatterns) {
+        check(!pattern.test(text), `${label} detected in ${path}`);
+      }
+    }
+    if (publicPath.test(path)) {
+      check(!/(?:^|[\s"'`])\/home\/[A-Za-z0-9._-]+\//u.test(text), `machine-local path in ${path}`);
+    }
+  }
+  console.log("[release] bounded secret and public-path hygiene checked");
+
+  const sources = files.filter((path) => path === "index.ts" || (path.startsWith("lib/") && path.endsWith(".ts")));
+  const sourceSet = new Set(sources);
+  const graph = new Map();
+  for (const path of sources) {
+    const text = stagedText(path) ?? "";
+    const headerEnd = text.indexOf("*/");
+    const header = headerEnd >= 0 ? text.slice(0, headerEnd + 2) : "";
+    check(
+      header.startsWith("/**") && (header.includes("Zones:") || header.includes("Owns:")),
+      `missing domain header: ${path}`,
+    );
+    const edges = sourceImports(text)
+      .map((specifier) => resolveLocalImport(path, specifier, sourceSet))
+      .filter(Boolean);
+    graph.set(path, edges);
+    if (path.startsWith("lib/")) {
+      check(!edges.includes("index.ts"), `domain imports entrypoint: ${path}`);
+    }
+  }
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(path, stack = []) {
+    if (visiting.has(path)) {
+      failures.push(`Domain DAG cycle: ${[...stack, path].join(" -> ")}`);
+      return;
+    }
+    if (visited.has(path)) return;
+    visiting.add(path);
+    for (const next of graph.get(path) ?? []) visit(next, [...stack, path]);
+    visiting.delete(path);
+    visited.add(path);
+  }
+  for (const path of sources) visit(path);
+  console.log(`[release] strict Domain DAG: ${sources.length} sources, acyclic`);
+
+  for (const path of ["README.md", "AGENTS.md", "BACKLOG.md", "CHANGELOG.md", "docs/README.md"]) {
+    check(fileSet.has(path), `missing ABCd root/context file: ${path}`);
+  }
+  const readStaged = (path) => stagedText(path) ?? "";
+  const readme = readStaged("README.md");
+  for (const path of ["AGENTS.md", "BACKLOG.md", "CHANGELOG.md", "docs/README.md"]) {
+    check(readme.includes(path), `README.md does not route to ${path}`);
+  }
+  for (const path of files.filter((candidate) => candidate.endsWith(".md"))) {
+    const text = readStaged(path);
+    for (const match of text.matchAll(/\[[^\]]*\]\(([^)]+)\)/gu)) {
+      const target = match[1].split("#", 1)[0];
+      if (!target || /^(?:https?:|mailto:)/u.test(target)) continue;
+      const resolved = normalize(join(dirname(path), decodeURIComponent(target))).replaceAll("\\", "/");
+      check(fileSet.has(resolved), `broken Markdown link: ${path} -> ${target}`);
+    }
+  }
+  const docsIndex = readStaged("docs/README.md");
+  for (const path of files.filter((candidate) => candidate.startsWith("docs/") && candidate.endsWith(".md") && candidate !== "docs/README.md")) {
+    check(docsIndex.includes(relative("docs", path).replaceAll("\\", "/")), `docs/README.md omits ${path}`);
+  }
+  console.log("[release] ABCd context roots, routing, and Markdown links checked");
+
+  if (failures.length > 0) {
+    for (const failure of failures) console.error(`[FAIL] ${failure}`);
+    process.exitCode = 1;
+  } else {
+    console.log("[release] all supplemental release gates passed");
+  }
+} catch (error) {
+  console.error(`[FAIL] ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+} finally {
+  rmSync(temp, { recursive: true, force: true });
+}