@llblab/pi-actors 0.43.0 → 0.43.1

package/lib/runtime-triage.ts

@@ -0,0 +1,120 @@
+/**
+ * Pure runtime Control triage policy.
+ * Zones: pending admission, status-age classification, terminal/replacement staleness
+ * Owns Control triage decisions; journal reads and owner filtering stay in adapters, while safe fields come from control-projection.
+ */
+
+import * as ControlProjection from "./control-projection.ts";
+import type { RunControlRecord, RunControlStatus } from "./runs-controls.ts";
+
+export const RUNTIME_CONTROL_STALE_AFTER_MS = 5 * 60 * 1_000;
+
+const PENDING_STATUSES = new Set<RunControlStatus>([
+  "queued",
+  "delivered",
+  "claimed",
+]);
+const TERMINAL_STATUSES = new Set<RunControlStatus>(["handled", "failed"]);
+
+export interface RuntimeTriageRun {
+  run: string;
+  runInstanceId?: string;
+  status: string;
+}
+
+export interface RuntimePendingControl
+  extends ControlProjection.ProjectedRunControl {
+  age_ms: number;
+  reason: "age_threshold_reached" | "run_generation_replaced" | "run_generation_unavailable" | "run_terminal" | "within_age_threshold";
+  run: string;
+  status: "queued" | "delivered" | "claimed";
+  status_at: string;
+}
+
+export interface RuntimeControlDiagnostic {
+  reason: "invalid_action" | "invalid_control_id" | "invalid_generation" | "invalid_record" | "invalid_status" | "invalid_status_timestamp";
+  run: string;
+}
+
+export interface RuntimeControlClassification {
+  diagnostic?: RuntimeControlDiagnostic;
+  pending?: RuntimePendingControl;
+  stale?: RuntimePendingControl;
+}
+
+function diagnostic(
+  run: string,
+  reason: RuntimeControlDiagnostic["reason"],
+): RuntimeControlClassification {
+  return { diagnostic: { reason, run } };
+}
+
+function statusTimestamp(
+  record: Record<string, unknown>,
+  status: RunControlStatus,
+): unknown {
+  if (status === "failed") return record.failed_at;
+  if (status === "handled") return record.handled_at;
+  if (status === "claimed") return record.claimed_at;
+  if (status === "delivered") return record.delivered_at;
+  return record.queued_at;
+}
+
+export function classifyRuntimeControl(
+  run: RuntimeTriageRun,
+  value: unknown,
+  nowMs: number,
+): RuntimeControlClassification {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return diagnostic(run.run, "invalid_record");
+  }
+  const record = value as Record<string, unknown>;
+  const status = record.status as RunControlStatus;
+  if (!PENDING_STATUSES.has(status) && !TERMINAL_STATUSES.has(status)) {
+    return diagnostic(run.run, "invalid_status");
+  }
+  if (typeof record.id !== "string" || !record.id) {
+    return diagnostic(run.run, "invalid_control_id");
+  }
+  if (typeof record.action !== "string" || !record.action) {
+    return diagnostic(run.run, "invalid_action");
+  }
+  if (typeof record.run_instance_id !== "string" || !record.run_instance_id) {
+    return diagnostic(run.run, "invalid_generation");
+  }
+  const timestamp = statusTimestamp(record, status);
+  const timestampMs = typeof timestamp === "string" ? Date.parse(timestamp) : Number.NaN;
+  if (!Number.isFinite(timestampMs)) {
+    return diagnostic(run.run, "invalid_status_timestamp");
+  }
+  if (TERMINAL_STATUSES.has(status)) return {};
+  const ageMs = Math.max(0, Math.floor(nowMs - timestampMs));
+  const staleReason: RuntimePendingControl["reason"] | undefined =
+    !run.runInstanceId
+      ? "run_generation_unavailable"
+      : record.run_instance_id !== run.runInstanceId
+        ? "run_generation_replaced"
+        : run.status !== "running"
+          ? "run_terminal"
+          : ageMs >= RUNTIME_CONTROL_STALE_AFTER_MS
+            ? "age_threshold_reached"
+            : undefined;
+  const projected = ControlProjection.projectRunControl(
+    record as unknown as RunControlRecord,
+  );
+  const pending: RuntimePendingControl = {
+    ...projected,
+    age_ms: ageMs,
+    reason: staleReason ?? "within_age_threshold",
+    run: run.run,
+    status: status as RuntimePendingControl["status"],
+    status_at: statusTimestamp(
+      projected as unknown as Record<string, unknown>,
+      status,
+    ) as string,
+  };
+  return {
+    pending,
+    ...(staleReason ? { stale: pending } : {}),
+  };
+}

package/lib/tool-review-scheduler.ts

@@ -404,7 +404,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
         ...state,
         failedStage: "approval_state",
         lastError: "approved review path is unavailable",
-        nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+        nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
         phase: "processing_failed" as const,
         updatedAt: (options.now ?? (() => new Date()))().toISOString(),
       };
@@ -427,7 +427,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
           ...state,
           failedStage: "transaction",
           lastError: `tool review transaction remained ${transaction.phase}`,
-          nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+          nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
           phase: "processing_failed" as const,
           updatedAt: (options.now ?? (() => new Date()))().toISOString(),
         };
@@ -458,7 +458,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
           ...pending,
           failedStage: "lineage",
           lastError: error instanceof Error ? error.message : String(error),
-          nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+          nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
         };
         writeJsonAtomic(statePath, failedPending);
         return { outcome: "lineage_pending", state: failedPending };
@@ -478,7 +478,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
         ...state,
         failedStage: "transaction",
         lastError: error instanceof Error ? error.message : String(error),
-        nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+        nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
         phase: "processing_failed" as const,
         updatedAt: (options.now ?? (() => new Date()))().toISOString(),
       };
@@ -541,7 +541,7 @@ export function createToolReviewScheduler(
           ...existing,
           failedStage: processed.stage ?? "review_result",
           lastError: processed.error ?? "automatic tool reviewer failed",
-          nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+          nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
           phase: processed.outcome === "processing_failed"
             ? "processing_failed"
             : "failed",
@@ -577,7 +577,7 @@ export function createToolReviewScheduler(
             attempts: existing.attempts + 1,
             failedStage: "review_launch",
             lastError: error instanceof Error ? error.message : String(error),
-            nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+            nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
             phase: "failed",
             updatedAt: now().toISOString(),
           } satisfies ToolReviewAdmissionState);
@@ -612,7 +612,7 @@ export function createToolReviewScheduler(
           failedStage: "review_launch",
           inputPath: batch.inputPath,
           lastError: error instanceof Error ? error.message : String(error),
-          nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+          nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
           phase: "failed",
           reviewerInputPath: batch.reviewerInputPath,
           reviewId: batch.reviewId,

package/lib/tools-inspect.ts

@@ -7,6 +7,7 @@
 import { join } from "node:path";
 
 import * as AsyncRuns from "./async-runs.ts";
+import * as ControlProjection from "./control-projection.ts";
 import * as Inspector from "./inspector.ts";
 import * as Limits from "./limits.ts";
 import * as Paths from "./paths.ts";
@@ -15,6 +16,8 @@ import * as ReviewDiagnostics from "./review-diagnostics.ts";
 import * as RunsControls from "./runs-controls.ts";
 import * as RunControlDelivery from "./runs-control-delivery.ts";
 import * as RunsTrace from "./runs-trace.ts";
+import * as RuntimeIdentity from "./runtime-identity.ts";
+import * as RuntimeTriage from "./runtime-triage.ts";
 import * as Schema from "./schema.ts";
 import * as ToolsAccess from "./tools-access.ts";
 import * as ToolsResponse from "./tools-response.ts";
@@ -35,7 +38,8 @@ function runtimeStatus(): Record<string, unknown> {
   return {
     automatic_review: process.env.PI_ACTORS_AUTOMATIC_REVIEW !== "off",
     run_root: Paths.getRunStateRoot(),
-    version: process.env.npm_package_version ?? "unknown",
+    state_schema: RuntimeIdentity.RUN_STATE_SCHEMA,
+    version: RuntimeIdentity.getPackageVersion(),
   };
 }
 
@@ -69,13 +73,39 @@ function runtimeTriage(
   const inventory = runtimeRuns(ctx, deps, undefined);
   const runs = inventory.runs as Array<Record<string, unknown>>;
   const failed = runs.filter((run) => run.status === "failed");
-  const staleControls = runs.flatMap((run) => {
+  const pendingControls: RuntimeTriage.RuntimePendingControl[] = [];
+  const staleControls: RuntimeTriage.RuntimePendingControl[] = [];
+  const controlDiagnostics: Array<Record<string, unknown>> = [];
+  const nowMs = Date.now();
+  for (const run of runs) {
     const stateDir = typeof run.state_dir === "string" ? run.state_dir : undefined;
-    if (!stateDir) return [];
-    return RunsControls.readRunControlsFromStateDir(stateDir)
-      .filter((control) => control.status === "queued" || control.status === "claimed")
-      .map((control) => ({ run: run.run, control }));
-  });
+    if (!stateDir) continue;
+    const runId = String(run.run ?? "unknown");
+    const journal = RunsControls.readRunControlJournalFromStateDir(stateDir);
+    controlDiagnostics.push(...journal.diagnostics.map((diagnostic) => ({
+      ...(diagnostic.line === undefined ? {} : { line: diagnostic.line }),
+      reason: diagnostic.line === undefined
+        ? "unreadable_control_journal"
+        : "invalid_control_json",
+      run: runId,
+    })));
+    for (const control of journal.records) {
+      const classified = RuntimeTriage.classifyRuntimeControl(
+        {
+          run: runId,
+          ...(typeof run.run_instance_id === "string"
+            ? { runInstanceId: run.run_instance_id }
+            : {}),
+          status: String(run.status ?? "unknown"),
+        },
+        control,
+        nowMs,
+      );
+      if (classified.pending) pendingControls.push(classified.pending);
+      if (classified.stale) staleControls.push(classified.stale);
+      if (classified.diagnostic) controlDiagnostics.push({ ...classified.diagnostic });
+    }
+  }
   const attentionEvents = runs.flatMap((run) => {
     const stateDir = typeof run.state_dir === "string" ? run.state_dir : undefined;
     if (!stateDir) return [];
@@ -90,18 +120,31 @@ function runtimeTriage(
         ts: event.ts,
       }));
   });
+  const boundedStaleControls = staleControls.slice(0, 40);
+  const staleKeys = new Set(boundedStaleControls.map((control) =>
+    `${control.run}\0${control.run_instance_id}\0${control.id}`,
+  ));
+  const boundedPendingControls = [
+    ...boundedStaleControls,
+    ...pendingControls.filter((control) =>
+      !staleKeys.has(`${control.run}\0${control.run_instance_id}\0${control.id}`),
+    ),
+  ].slice(0, 40);
   return {
     ...inventory,
     failed_runs: failed,
-    stale_controls: staleControls.slice(0, 40),
+    pending_control_count: pendingControls.length,
+    pending_controls: boundedPendingControls,
+    stale_control_count: staleControls.length,
+    stale_controls: boundedStaleControls,
+    control_diagnostic_count: controlDiagnostics.length,
+    control_diagnostics: controlDiagnostics.slice(0, 40),
     attention_events: attentionEvents.slice(-40).reverse(),
     next_actions: [
       ...(failed.length ? ["inspect target=runtime view=runs status=failed"] : []),
-      ...(staleControls.length
-        ? staleControls.slice(0, 3).map((entry) =>
-            `inspect target=run:${String(entry.run)} view=control`,
-          )
-        : []),
+      ...staleControls.slice(0, 3).map((entry) =>
+        `inspect target=run:${entry.run} view=control`,
+      ),
       ...(attentionEvents.length
         ? attentionEvents.slice(-3).map((entry) =>
             `inspect target=run:${String(entry.run)} view=trace source=runtime`,
@@ -116,9 +159,9 @@ function compactRuntime(view: string, details: Record<string, unknown>): string
     return `\nruntime runs=${(details.runs as unknown[] | undefined)?.length ?? 0}`;
   }
   if (view === "triage") {
-    return `\nruntime failed=${(details.failed_runs as unknown[] | undefined)?.length ?? 0} stale_controls=${(details.stale_controls as unknown[] | undefined)?.length ?? 0} attention=${(details.attention_events as unknown[] | undefined)?.length ?? 0}`;
+    return `\nruntime failed=${(details.failed_runs as unknown[] | undefined)?.length ?? 0} pending_controls=${Number(details.pending_control_count ?? 0)} stale_controls=${Number(details.stale_control_count ?? 0)} attention=${(details.attention_events as unknown[] | undefined)?.length ?? 0}`;
   }
-  return `\nruntime version=${String(details.version ?? "unknown")} automatic_review=${String(details.automatic_review)}`;
+  return `\nruntime version=${String(details.version)} state_schema=${String(details.state_schema)} automatic_review=${String(details.automatic_review)}`;
 }
 
 function inspectRuntime(
@@ -232,7 +275,8 @@ function inspectRun(
       : undefined,
     recent_controls: RunsControls.readRunControlsFromStateDir(stateDir)
       .slice(-Math.max(1, Number(input.lines || 20)))
-      .reverse(),
+      .reverse()
+      .map(ControlProjection.projectRunControl),
   };
 }
 

package/lib/tools-message.ts

@@ -46,8 +46,7 @@ function runNextActions(run: string, result: Record<string, unknown>): string[]
 }
 
 export interface ControlToolDeps {
-  getTool?: (name: string) => unknown;
-  handleRuntimeMessage?: (
+  handleRuntimeControl?: (
     action: string,
     input: unknown,
   ) => Record<string, unknown>;
@@ -64,11 +63,11 @@ export function createControlToolDefinition<TContext = unknown>(
     parameters: Schema.objectSchema(
       {
         target: Schema.stringSchema("Run target run:<id>, or literal runtime."),
-        action: Schema.stringSchema("Lowercase semantic Control action."),
+        action: Schema.stringSchema("Lowercase ASCII Control action, at most 64 characters."),
         input: Schema.unionSchema([
-          Schema.stringSchema("Optional Control input string."),
-          Schema.looseObjectSchema("Optional structured Control input."),
-          Schema.arraySchema("Optional structured Control input array."),
+          Schema.stringSchema("Optional Control input string; serialized JSON must fit 380 bytes."),
+          Schema.looseObjectSchema("Optional structured Control input; serialized JSON must fit 380 bytes."),
+          Schema.arraySchema("Optional structured Control input array; serialized JSON must fit 380 bytes."),
         ]),
         verbose: Schema.booleanSchema("Return full JSON instead of compact text."),
       },
@@ -89,10 +88,10 @@ export function createControlToolDefinition<TContext = unknown>(
             `unsupported runtime Control action: ${request.action}; use review.retry or review.reset`,
           );
         }
-        if (!deps.handleRuntimeMessage) {
+        if (!deps.handleRuntimeControl) {
           throw new Error("runtime Control is unavailable");
         }
-        result = deps.handleRuntimeMessage(request.action, request.input);
+        result = deps.handleRuntimeControl(request.action, request.input);
       } else {
         const run = request.target.slice(4);
         const status = ToolsAccess.assertRunAccessibleToContext(run, ctx);

package/lib/tools-response.ts

@@ -133,18 +133,6 @@ export function compactAsyncRunStatus(value: unknown): string {
   return `\n${tokens.join(" ")}`;
 }
 
-export function artifactNextActions(
-  run: unknown,
-  artifacts: Record<string, unknown>,
-): string[] {
-  const id = String(run ?? "").trim();
-  if (!id || Object.keys(artifacts).length === 0) return [];
-  return [
-    `inspect target=run:${id} view=artifacts verbose=true`,
-    `inspect target=run:${id} view=messages`,
-  ];
-}
-
 export function maybeJsonText(
   value: unknown,
   verbose: boolean | undefined,

package/lib/tools.ts

@@ -25,9 +25,9 @@ export interface CoreActorToolDefinitionDeps<
   configPath: string;
   getActiveTools: () => string[];
   getRuntimeTool: (name: string) => unknown;
-  handleRuntimeMessage?: (
-    type: string,
-    body: unknown,
+  handleRuntimeControl?: (
+    action: string,
+    input: unknown,
   ) => Record<string, unknown>;
   registryRuntime: Pick<
     RegisterToolRuntimeDeps<TContext>,
@@ -74,7 +74,7 @@ export function createCoreActorToolDefinitions<
     }),
     ToolsSpawn.createSpawnToolDefinition<TContext>(),
     ToolsMessage.createControlToolDefinition<TContext>({
-      handleRuntimeMessage: deps.handleRuntimeMessage,
+      handleRuntimeControl: deps.handleRuntimeControl,
     }),
     ToolsInspect.createInspectToolDefinition<TContext>({
       getTool: (name) => deps.getRuntimeTool(name),

package/lib/trace-projection.ts

@@ -7,6 +7,7 @@
 import { existsSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 
+import * as ControlProjection from "./control-projection.ts";
 import * as ExecutionSessions from "./execution-sessions.ts";
 import * as Limits from "./limits.ts";
 import {
@@ -78,6 +79,25 @@ function diagnosticItems(diagnostics: StateReadDiagnostic[]): TraceItem[] {
   }));
 }
 
+function controlDiagnosticItems(
+  diagnostics: StateReadDiagnostic[],
+): TraceItem[] {
+  return diagnostics.slice(-SOURCE_LIMIT).map((diagnostic, index) => ({
+    id: `control-diagnostic:${diagnostic.line ?? 0}:${index}`,
+    ts: new Date(0).toISOString(),
+    source: "runtime",
+    kind: "state.read_error",
+    summary: "Malformed or unreadable Control evidence",
+    level: "warning",
+    detail: {
+      ...(diagnostic.line === undefined ? {} : { line: diagnostic.line }),
+      reason: diagnostic.line === undefined
+        ? "unreadable_control_journal"
+        : "invalid_control_json",
+    },
+  }));
+}
+
 function traceEventItems(stateDir: string): TraceItem[] {
   const read = readJsonlFileResilient<TraceEvent>(join(stateDir, "trace.jsonl"));
   return [
@@ -102,16 +122,19 @@ function controlItems(stateDir: string): TraceItem[] {
     join(stateDir, "controls.jsonl"),
   );
   return [
-    ...read.records.slice(-SOURCE_LIMIT).map((control) => ({
-      id: `control:${control.id}`,
-      ts: latestControlTimestamp(control),
-      source: "control" as const,
-      kind: `control.${control.status}`,
-      summary: `${control.action} ${control.status}`,
-      ...(control.status === "failed" ? { level: "error" as const } : {}),
-      detail: redact(control),
-    })),
-    ...diagnosticItems(read.diagnostics),
+    ...read.records.slice(-SOURCE_LIMIT).map((control) => {
+      const projected = ControlProjection.projectRunControl(control);
+      return {
+        id: `control:${projected.id}`,
+        ts: latestControlTimestamp(projected),
+        source: "control" as const,
+        kind: `control.${projected.status}`,
+        summary: `${projected.action} ${projected.status}`,
+        ...(projected.status === "failed" ? { level: "error" as const } : {}),
+        detail: projected,
+      };
+    }),
+    ...controlDiagnosticItems(read.diagnostics),
   ];
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.43.0",
+  "version": "0.43.1",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/scripts/locker.mjs

@@ -9,13 +9,12 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
 import {
   appendFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
-  rmSync,
 } from "node:fs";
 import { createServer } from "node:net";
 import { dirname, join, resolve } from "node:path";
@@ -35,6 +34,7 @@ async function importRuntimeModule(name) {
 
 const { acquireFileMutationLock, writeJsonAtomic, writeTextAtomic } =
   await importRuntimeModule("file-state");
+const { appendRunTraceEvent } = await importRuntimeModule("runs-trace");
 
 function parseArgs(argv) {
   const args = { mode: "serve", stateDir: "", leaseMs: 600000, lines: 20 };
@@ -59,7 +59,6 @@ async function runLocker(argv = process.argv.slice(2)) {
   const queuePath = join(stateDir, "queue.json");
   const locksPath = join(stateDir, "locks.json");
   const journalPath = join(stateDir, "journal.jsonl");
-  const tracePath = join(stateDir, "trace.jsonl");
   const controlsPath = join(stateDir, "controls.jsonl");
   const controlPath = join(stateDir, "control.fifo");
   let runInstanceId;
@@ -104,18 +103,13 @@ async function runLocker(argv = process.argv.slice(2)) {
   }
 
   function emitTrace(kind, summary, data = {}, level = "info") {
-    appendFileSync(
-      tracePath,
-      `${JSON.stringify({
-        attention: "followup",
-        data,
-        id: randomUUID(),
-        kind,
-        level,
-        summary,
-        ts: new Date().toISOString(),
-      })}\n`,
-    );
+    appendRunTraceEvent(stateDir, {
+      attention: "followup",
+      data,
+      kind,
+      level,
+      summary,
+    });
   }
 
   function now() {
@@ -454,7 +448,6 @@ async function runLocker(argv = process.argv.slice(2)) {
   }
 
   async function serveNamedPipe(endpoint) {
-    rmSync(endpoint.path, { force: true });
     let resolveStopped;
     const stopped = new Promise((resolve) => {
       resolveStopped = resolve;

package/scripts/music-player.mjs

@@ -52,6 +52,7 @@ async function importRuntimeModule(name) {
 
 const { acquireFileMutationLock, writeTextAtomic } =
   await importRuntimeModule("file-state");
+const { appendRunTraceEvent } = await importRuntimeModule("runs-trace");
 
 const AUDIO_EXTENSIONS = new Set([
   ".aac",
@@ -420,18 +421,12 @@ function readText(path) {
 }
 
 function emitPlayerEvent(ctx, kind, summary, data = {}) {
-  writeText(
-    ctx.eventFile,
-    `${JSON.stringify({
-      data,
-      id: randomUUID(),
-      kind,
-      level: "info",
-      summary,
-      ts: new Date().toISOString(),
-    })}\n`,
-    "a",
-  );
+  appendRunTraceEvent(ctx.stateDir, {
+    data,
+    kind,
+    level: "info",
+    summary,
+  });
 }
 
 function emitTrackEvent(ctx, index, count, track, player) {
@@ -859,7 +854,6 @@ async function playMain(args) {
   const ctx = {
     commandFile: join(stateDir, "command.txt"),
     current: undefined,
-    eventFile: join(stateDir, "trace.jsonl"),
     controlsFile: join(stateDir, "controls.jsonl"),
     pidFile: join(stateDir, "current.pid"),
     playerControlFile: join(stateDir, "player-control.txt"),

package/scripts/release-gates.mjs

@@ -145,13 +145,44 @@ try {
   }
   console.log("[release] removed-surface and legacy-fallback allowlists checked");
 
-  const baselineShippedLines = 35_077;
+  const directTraceWrite = /(?:appendFileSync|writeFileSync|writeText(?:Atomic)?)\s*\(\s*[A-Za-z0-9_.]*?(?:trace|event)(?:Path|File)/iu;
+  for (const path of files.filter((candidate) =>
+    (candidate.startsWith("lib/") && candidate.endsWith(".ts")) ||
+    (candidate.startsWith("scripts/") && candidate.endsWith(".mjs"))
+  )) {
+    if (path === "lib/runs-trace.ts") continue;
+    check(!directTraceWrite.test(stagedText(path) ?? ""), `direct Trace writer outside canonical authority: ${path}`);
+  }
+  const canonicalTrace = stagedText("lib/runs-trace.ts") ?? "";
+  check(/withFileMutationLock\(path/u.test(canonicalTrace), "canonical Trace append lacks mutation lock");
+  for (const path of [
+    "scripts/async-runner.mjs",
+    "scripts/locker.mjs",
+    "scripts/music-player.mjs",
+  ]) {
+    const text = stagedText(path) ?? "";
+    check(
+      text.includes('importRuntimeModule("runs-trace")') && text.includes("appendRunTraceEvent"),
+      `first-party Trace writer bypasses canonical runtime module: ${path}`,
+    );
+  }
+  console.log("[release] canonical Trace writer residue checked");
+
+  check(
+    (stagedText("scripts/validate-recipe.mjs") ?? "").includes(
+      "qaReport.diagnostics.length === 0 && qaReport.warnings.length === 0",
+    ),
+    "Recipe QA warnings are not release-blocking",
+  );
+  console.log("[release] zero-warning Recipe QA gate checked");
+
+  const baselineShippedLines = 28_853;
   const shippedPath = /^(?:lib\/|scripts\/|recipes\/|docs\/|skills\/)/u;
   const shippedLines = files
     .filter((path) => shippedPath.test(path))
     .reduce((total, path) => total + (((stagedText(path) ?? "").match(/\n/gu) ?? []).length + 1), 0);
   check(shippedLines < baselineShippedLines, `shipped lines ${shippedLines} are not below baseline ${baselineShippedLines}`);
-  console.log(`[release] shipped lines ${shippedLines} < frozen baseline ${baselineShippedLines}`);
+  console.log(`[release] shipped lines ${shippedLines} < released baseline ${baselineShippedLines}`);
 
   const sources = files.filter((path) => path === "index.ts" || (path.startsWith("lib/") && path.endsWith(".ts")));
   const sourceSet = new Set(sources);

package/scripts/validate-recipe.mjs

@@ -29,7 +29,7 @@ export function validateRecipeUsage() {
   return `Usage:
   validate-recipe.mjs <recipe-file-or-dir> [--all] [--qa] [--summary]
 
-Validates one template recipe file, or all *.json/*.md files in a directory when --all is set. Add --qa for packaged-recipe quality checks. Add --summary for compact CLI output.`;
+Validates one template recipe file, or all *.json/*.md files in a directory when --all is set. Add --qa for packaged-recipe quality checks, where diagnostics and warnings fail validation. Add --summary for compact CLI output.`;
 }
 
 function expandPath(value) {
@@ -120,8 +120,6 @@ function validateHelperPaths(file, config) {
 function qaDiagnostics(file, config) {
   const diagnostics = [];
   const warnings = [];
-  if (typeof config.description !== "string" || !config.description.trim())
-    warnings.push("description: missing or empty");
   if (config.mailbox !== undefined)
     diagnostics.push("recipe.mailbox was removed; use control actions and Trace events");
   diagnostics.push(...validateArtifactDeclarations(config));
@@ -138,7 +136,7 @@ function qaDiagnostics(file, config) {
 }
 
 function qaOk(qaReport) {
-  return qaReport.diagnostics.length === 0;
+  return qaReport.diagnostics.length === 0 && qaReport.warnings.length === 0;
 }
 
 function validateFile(file, qa = false) {
@@ -225,6 +223,9 @@ function summarizeReport(report) {
         ...(result.qa?.diagnostics?.length
           ? { diagnostics: result.qa.diagnostics }
           : {}),
+        ...(result.qa?.warnings?.length
+          ? { warnings: result.qa.warnings }
+          : {}),
       })),
   };
 }