@llblab/pi-actors 0.43.1 → 0.45.0

package/lib/recipes-discovery.ts

@@ -122,6 +122,25 @@ function getRecipeCommandTemplateConfig(
     : config) as CommandTemplates.CommandTemplateConfig;
 }
 
+function getRecipeDiagnosticTemplateConfig(
+  config: TemplateRecipeConfig,
+): CommandTemplates.CommandTemplateObjectConfig {
+  const templateConfig = getRecipeCommandTemplateConfig(config);
+  return typeof templateConfig === "object" && !Array.isArray(templateConfig)
+    ? {
+        ...templateConfig,
+        defaults: {
+          ...(templateConfig.defaults ?? {}),
+          ...(config.defaults ?? {}),
+          ...(config.values ?? {}),
+        },
+      }
+    : {
+        defaults: { ...(config.defaults ?? {}), ...(config.values ?? {}) },
+        template: templateConfig,
+      };
+}
+
 function getRecipeConfigDiagnostics(
   file: string,
   config: TemplateRecipeConfig | undefined,
@@ -131,7 +150,7 @@ function getRecipeConfigDiagnostics(
     return [`Invalid recipe: ${file}${reason ? `: ${reason}` : ""}`];
   }
   return CommandTemplates.getCommandTemplateWarnings(
-    getRecipeCommandTemplateConfig(config),
+    getRecipeDiagnosticTemplateConfig(config),
   ).map((warning) => `Recipe ${file}: ${warning}`);
 }
 
@@ -141,7 +160,7 @@ function getRecipeRiskLabels(
   if (!config) return [];
   const labels = new Set(
     CommandTemplates.getCommandTemplateRiskLabels(
-      getRecipeCommandTemplateConfig(config),
+      getRecipeDiagnosticTemplateConfig(config),
     ),
   );
   if (config.async === true) labels.add("risk.long_running");
@@ -846,9 +865,10 @@ export function toRegisteredTool(
   assertToolSafeRepeatConfig(
     argTemplateConfig,
     explicitArgTypes,
-    cfg.defaults ?? {},
+    { ...(cfg.defaults ?? {}), ...(cfg.values ?? {}) },
   );
   const argTypes = Schema.getTemplateArgTypes(argTemplateConfig);
+  Schema.assertCompatibleToolArgTypes(explicitArgTypes, argTypes);
   return {
     name: entry.id,
     description,

package/lib/recipes-references.ts

@@ -6,7 +6,7 @@
 
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, extname, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, relative, resolve } from "node:path";
 
 import type {
   CommandTemplateConfig,
@@ -15,6 +15,7 @@ import type {
 import * as CommandTemplates from "./command-templates.ts";
 import * as Paths from "./paths.ts";
 import * as RecipeControl from "./recipe-control.ts";
+import * as Schema from "./schema.ts";
 
 const MAX_RECIPE_FILE_BYTES = 1024 * 1024;
 const MAX_RECIPE_IMPORT_DEPTH = 32;
@@ -57,6 +58,8 @@ export interface TemplateRecipeDefinition {
 
 export interface TemplateRecipeConfig extends TemplateRecipeDefinition {
   async?: boolean;
+  recipe_dir?: string;
+  skill_dir?: string;
 }
 
 interface ImportedRecipe {
@@ -74,6 +77,7 @@ export interface TemplateRecipeContextRecord {
   file: string;
   import_path: string[];
   name: string;
+  qualified_name?: string;
   recipe: Record<string, unknown>;
   role: "entry" | "import";
 }
@@ -82,10 +86,120 @@ export interface ReadResolvedRecipeConfigOptions {
   includeActorRecipeContext?: boolean;
 }
 
+const RUNTIME_RECIPE_VALUE_NAMES = new Set(["recipe_dir", "skill_dir"]);
+const activeSkillRecipeRoots = new Map<string, Set<string>>();
+
+export interface ActiveSkillRecipeSource {
+  name: string;
+  filePath?: string;
+  baseDir?: string;
+}
+
+export function setActiveSkillRecipeSources(
+  skills: ActiveSkillRecipeSource[],
+): void {
+  activeSkillRecipeRoots.clear();
+  for (const skill of skills) {
+    const name = skill.name.trim();
+    const skillDir = skill.baseDir
+      ? resolve(skill.baseDir)
+      : skill.filePath
+        ? dirname(resolve(skill.filePath))
+        : undefined;
+    if (!name || !skillDir) continue;
+    const roots = activeSkillRecipeRoots.get(name) ?? new Set<string>();
+    roots.add(resolve(skillDir, "recipes"));
+    activeSkillRecipeRoots.set(name, roots);
+  }
+}
+
+export function getActiveSkillRecipeNamespaces(): Record<string, string[]> {
+  return Object.fromEntries(
+    [...activeSkillRecipeRoots.entries()]
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, roots]) => [name, [...roots].sort()]),
+  );
+}
+
+function qualifiedRecipeNameForFile(file: string): string | undefined {
+  const path = resolve(file);
+  const stdRelation = relative(Paths.getPackagedRecipeRoot(), path);
+  if (
+    stdRelation &&
+    !stdRelation.startsWith("..") &&
+    !isAbsolute(stdRelation)
+  ) {
+    return `std:${stdRelation.replace(/\.(?:json|md)$/u, "")}`;
+  }
+  for (const [skillName, roots] of activeSkillRecipeRoots) {
+    if (roots.size !== 1) continue;
+    const root = [...roots][0];
+    const relation = relative(root, path);
+    if (relation && !relation.startsWith("..") && !isAbsolute(relation))
+      return `skill:${skillName}/${relation.replaceAll("\\", "/").replace(/\.(?:json|md)$/u, "")}`;
+  }
+  return undefined;
+}
+
+function qualifiedRecipeCandidates(value: string): string[] | undefined {
+  if (value.startsWith("std:")) {
+    return recipeNameFiles(value.slice(4)).map((file) =>
+      resolve(Paths.getPackagedRecipeRoot(), file),
+    );
+  }
+  if (!value.startsWith("skill:")) return undefined;
+  const qualified = value.slice(6);
+  const separator = qualified.indexOf("/");
+  if (separator <= 0 || separator === qualified.length - 1)
+    throw new Error(`Invalid Skill Recipe reference: ${value}`);
+  const skillName = qualified.slice(0, separator);
+  const recipeName = qualified.slice(separator + 1);
+  const roots = [...(activeSkillRecipeRoots.get(skillName) ?? [])];
+  if (roots.length === 0)
+    throw new Error(`Active Skill Recipe namespace not found: ${skillName}`);
+  if (roots.length > 1)
+    throw new Error(
+      `Ambiguous active Skill Recipe namespace ${skillName}: ${roots.join(", ")}`,
+    );
+  const root = roots[0];
+  return recipeNameFiles(recipeName).map((file) => {
+    const candidate = resolve(root, file);
+    const relation = relative(root, candidate);
+    if (!relation || relation.startsWith("..") || isAbsolute(relation))
+      throw new Error(`Skill Recipe reference escapes its recipes root: ${value}`);
+    return candidate;
+  });
+}
+
 function hasWhitespace(value: string): boolean {
   return /\s/.test(value);
 }
 
+function findOwningSkillDir(recipeFile: string): string | undefined {
+  let current = dirname(recipeFile);
+  while (true) {
+    if (existsSync(resolve(current, "SKILL.md"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+function assertRuntimeRecipeValuesNotDeclared(raw: Record<string, unknown>): void {
+  const args = Array.isArray(raw.args)
+    ? Schema.getExplicitToolArgNames(raw.args.map(String))
+    : [];
+  for (const name of RUNTIME_RECIPE_VALUE_NAMES) {
+    if (
+      args.includes(name) ||
+      (isRecord(raw.defaults) && Object.hasOwn(raw.defaults, name)) ||
+      (isRecord(raw.values) && Object.hasOwn(raw.values, name))
+    ) {
+      throw new Error(`Recipe runtime value is reserved: ${name}`);
+    }
+  }
+}
+
 export function resolveRecipePath(
   value: string,
   recipeRoot = Paths.getRecipeRoot(),
@@ -125,6 +239,8 @@ function recipeCandidatePaths(
   value: string,
   currentRecipeRoot: string,
 ): string[] {
+  const qualified = qualifiedRecipeCandidates(value.trim());
+  if (qualified) return qualified;
   if (!isBareRecipeName(value))
     return [resolveRecipePath(value, currentRecipeRoot)];
   const roots = [
@@ -646,6 +762,63 @@ function mergeDefaults(
   return Object.keys(merged).length > 0 ? merged : undefined;
 }
 
+function assertRecipeDefaultsDeclared(
+  args: string[] | undefined,
+  defaults: Record<string, unknown> | undefined,
+  label: string,
+): void {
+  const spec = Schema.parseToolArgDeclarationList(args ?? []);
+  if (spec.error) throw new Error(spec.error);
+  if (spec.args.length === 0) return;
+  const declared = new Set(spec.args);
+  for (const key of Object.keys(defaults ?? {})) {
+    if (!declared.has(key)) throw new Error(`Unknown ${label} argument: ${key}`);
+  }
+}
+
+function assertRecipeArgumentContract(
+  config: Pick<
+    TemplateRecipeDefinition,
+    "args" | "defaults" | "values" | "template"
+  >,
+  label = "Recipe default",
+): void {
+  assertRecipeDefaultsDeclared(config.args, config.defaults, label);
+  const spec = Schema.parseToolArgDeclarationList(config.args ?? []);
+  if (spec.error) throw new Error(spec.error);
+  Schema.assertCompatibleToolArgTypes(
+    spec.argTypes,
+    Schema.getTemplateArgTypes({ template: config.template }),
+  );
+  const staticValues = Object.fromEntries(
+    Object.entries({ ...config.defaults, ...config.values }).filter(
+      ([, value]) =>
+        typeof value !== "string" || !/\{[^{}]+\}/.test(value),
+    ),
+  );
+  Schema.normalizeRuntimeValues(staticValues, spec.argTypes);
+}
+
+function resolveRecipeValueLayers(
+  args: string[] | undefined,
+  ...layers: Array<Record<string, unknown> | undefined>
+): Record<string, unknown> | undefined {
+  const spec = Schema.parseToolArgDeclarationList(args ?? []);
+  if (spec.error) throw new Error(spec.error);
+  const merged = mergeDefaults(spec.defaults, ...layers);
+  if (!merged) return undefined;
+  const staticValues = Object.fromEntries(
+    Object.entries(merged).filter(
+      ([, value]) =>
+        typeof value !== "string" || !/\{[^{}]+\}/.test(value),
+    ),
+  );
+  return {
+    ...merged,
+    ...Schema.normalizeRuntimeValues(staticValues, spec.argTypes),
+  };
+}
+
 function applyDefaultsToTemplate(
   template: CommandTemplateValue,
   defaults: Record<string, unknown> | undefined,
@@ -655,6 +828,7 @@ function applyDefaultsToTemplate(
   delete cleanOverrides.name;
   delete cleanOverrides.template;
   delete cleanOverrides.values;
+  delete cleanOverrides.defaults;
   if (typeof template === "object" && !Array.isArray(template)) {
     return {
       ...template,
@@ -716,11 +890,22 @@ function applyDelegatedRecipeToNode(
   delegated: TemplateRecipeConfig,
   overrides: Record<string, unknown> = {},
 ): CommandTemplateValue {
-  return applyDefaultsToTemplate(
-    delegated.template,
+  const nodeDefaults = isRecord(overrides.defaults)
+    ? overrides.defaults
+    : undefined;
+  const nodeValues = isRecord(overrides.values) ? overrides.values : undefined;
+  const values = resolveRecipeValueLayers(
+    delegated.args,
+    delegated.defaults,
     delegated.values,
-    overrides,
+    nodeDefaults,
+    nodeValues,
+    {
+      ...(delegated.recipe_dir ? { recipe_dir: delegated.recipe_dir } : {}),
+      ...(delegated.skill_dir ? { skill_dir: delegated.skill_dir } : {}),
+    },
   );
+  return applyDefaultsToTemplate(delegated.template, values, overrides);
 }
 
 function expandRecipeDelegations(
@@ -830,7 +1015,8 @@ function expandImportNodes(
       ? record.defaults
       : undefined;
     const nodeValues = isRecord(record.values) ? record.values : undefined;
-    const defaults = mergeDefaults(
+    const defaults = resolveRecipeValueLayers(
+      imported.config.args,
       imported.defaults,
       imported.values,
       nodeDefaults,
@@ -897,6 +1083,8 @@ export function readResolvedRecipeConfig(
   const raw = readRawRecipeConfig(path);
   if (!raw || !Object.hasOwn(raw, "template")) return undefined;
   RecipeControl.assertRecipeHasNoMailbox(raw);
+  assertRuntimeRecipeValuesNotDeclared(raw);
+  assertRecipeArgumentContract(raw as unknown as TemplateRecipeDefinition);
   const imports: Record<string, ImportedRecipe> = {};
   for (const [alias, binding] of Object.entries(getRecipeImports(raw))) {
     const importPath = resolveRecipeImportPath(
@@ -913,13 +1101,22 @@ export function readResolvedRecipeConfig(
       typeof binding === "string" ? undefined : binding.defaults;
     const bindingValues =
       typeof binding === "string" ? undefined : binding.values;
+    assertRecipeDefaultsDeclared(
+      config.args,
+      bindingDefaults,
+      `Recipe import ${alias} default`,
+    );
     imports[alias] = {
       alias,
       file: importPath,
       name: config.name ?? alias,
       config,
       defaults: { ...(config.defaults ?? {}), ...(bindingDefaults ?? {}) },
-      values: { ...(bindingValues ?? {}) },
+      values: {
+        ...(bindingValues ?? {}),
+        ...(config.recipe_dir ? { recipe_dir: config.recipe_dir } : {}),
+        ...(config.skill_dir ? { skill_dir: config.skill_dir } : {}),
+      },
     };
   }
   const substituted = substituteImportRefs(raw, imports) as Record<
@@ -945,6 +1142,21 @@ export function readResolvedRecipeConfig(
       )
     : expandRecipeDelegations(expandedImportsTemplate, path, stack, options);
   const recipeName = getRecipeIdFromPath(path);
+  const recipeDir = dirname(path);
+  const skillDir = findOwningSkillDir(path);
+  if (
+    !skillDir &&
+    JSON.stringify({
+      artifacts: substituted.artifacts,
+      defaults: substituted.defaults,
+      template: substituted.template,
+      values: substituted.values,
+    }).includes("{skill_dir}")
+  ) {
+    throw new Error(
+      `Recipe uses {skill_dir} outside an owning Skill directory: ${path}`,
+    );
+  }
   const templateWithContext = options.includeActorRecipeContext
     ? withActorRecipeContext(expandedTemplate, {
         file: path,
@@ -967,6 +1179,8 @@ export function readResolvedRecipeConfig(
   );
   return {
     name: recipeName,
+    recipe_dir: recipeDir,
+    ...(skillDir ? { skill_dir: skillDir } : {}),
     ...(typeof substituted.description === "string" &&
     substituted.description.trim()
       ? { description: substituted.description.trim() }
@@ -1059,7 +1273,11 @@ export function readResolvedRecipeConfig(
     ...(typeof substituted.repeat === "number"
       ? { repeat: substituted.repeat }
       : {}),
-    ...(isRecord(substituted.values) ? { values: substituted.values } : {}),
+    values: {
+      ...(isRecord(substituted.values) ? substituted.values : {}),
+      recipe_dir: recipeDir,
+      ...(skillDir ? { skill_dir: skillDir } : {}),
+    },
     ...(isRecord(substituted.usage) ? { usage: substituted.usage } : {}),
   };
 }
@@ -1084,12 +1302,14 @@ function collectRecipeContextRecords(
   }
   const raw = readRawRecipeConfig(path);
   if (!raw || !Object.hasOwn(raw, "template")) return [];
+  const qualifiedName = qualifiedRecipeNameForFile(path);
   const record: TemplateRecipeContextRecord = {
     ...(alias ? { alias } : {}),
     depth: stack.length,
     file: path,
     import_path: importPath,
     name: getRecipeIdFromPath(path),
+    ...(qualifiedName ? { qualified_name: qualifiedName } : {}),
     recipe: raw,
     role: stack.length === 0 ? "entry" : "import",
   };

package/lib/run-evidence-policy.ts

@@ -0,0 +1,242 @@
+/**
+ * Pure bounded Run-evidence policy.
+ * Zones: Trace retention, compaction accounting, Control capacity and admission
+ * Owns deterministic limits policy; journal I/O, locks, lifecycle authorization, and projection stay in adapters.
+ * Trace keeps the newest physical suffix because semantic priority would silently
+ * redefine causal history. Admitted Controls never expire: only a real terminal
+ * transition or generation replacement proves that durable work is finished.
+ */
+
+import * as Limits from "./limits.ts";
+
+export const TRACE_COMPACTION_KIND = "runtime.trace_compacted";
+export const TRACE_COMPACTION_VERSION = 1;
+export type TraceJournalUsage = { bytes: number; events: number };
+export type TraceRetentionCandidate<T> = { encodedBytes: number; value: T };
+export type TraceRetentionSelection<T> = {
+  droppedEvents: number; retained: TraceRetentionCandidate<T>[];
+  retainedBytes: number; retainedEvents: number;
+};
+export interface TraceCompactionData {
+  version: typeof TRACE_COMPACTION_VERSION;
+  compactions_total: number;
+  dropped_valid_events_total: number;
+  dropped_malformed_lines_total: number;
+  dropped_bytes_total: number;
+  dropped_event_count_exact: boolean;
+  retained_events: number;
+  retained_bytes: number;
+  history_complete: false;
+}
+export interface TraceCompactionDelta {
+  dropped_valid_events: number;
+  dropped_malformed_lines: number;
+  dropped_bytes: number;
+  dropped_event_count_exact: boolean;
+  retained_events: number;
+  retained_bytes: number;
+}
+export type RunControlStatus = "queued" | "delivered" | "claimed" | "handled" | "failed";
+export type RunControlCapacity = {
+  available: number; backpressured: boolean; limit: number;
+  oldest_pending_at?: string; pending: number;
+};
+export type RunControlAdmissionIntegrity =
+  | "valid" | "unreadable" | "malformed" | "noncanonical"
+  | "invalid_record" | "invalid_status_timestamp" | "generation_mismatch"
+  | "journal_bytes";
+export interface RunControlAdmissionErrorDetails {
+  reason: "control_backpressure" | "control_journal_integrity";
+  pending: number;
+  limit: number;
+  journal_bytes: number;
+  journal_limit: number;
+  oldest_pending_at?: string;
+  run_instance_id: string;
+  next_actions: string[];
+  integrity_reason?: string;
+}
+export type RunControlAdmissionDecision =
+  { admitted: true; capacity: RunControlCapacity } |
+  { admitted: false; capacity: RunControlCapacity; error: RunControlAdmissionErrorDetails };
+export type RunControlAdmissionInput = {
+  integrity: RunControlAdmissionIntegrity; journalBytes: number;
+  newRecordBytes: number; records: readonly unknown[];
+  retainedJournalBytes: number; runInstanceId: string;
+  capacity?: RunControlCapacity;
+};
+
+const PENDING_CONTROL_STATUSES = new Set<RunControlStatus>(["queued", "delivered", "claimed"]);
+const TERMINAL_CONTROL_STATUSES = new Set<RunControlStatus>(["handled", "failed"]);
+const CONTROL_ADMISSION_NEXT_ACTIONS = [
+  "inspect target=run:<id> view=control",
+  "inspect target=runtime view=triage",
+];
+
+function isCount(value: number): boolean {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+function assertCount(value: number, name: string): void {
+  if (!isCount(value)) throw new RangeError(`${name} must be a non-negative safe integer`);
+}
+function boundedAdd(left: number, right: number): number {
+  return Math.min(Number.MAX_SAFE_INTEGER, left + right);
+}
+export function traceAppendFits(usage: TraceJournalUsage, encodedEventBytes: number): boolean {
+  if (!isCount(usage.events) || !isCount(usage.bytes) || !isCount(encodedEventBytes)) return false;
+  return usage.events + 1 <= Limits.TRACE_JOURNAL_MAX_EVENTS &&
+    usage.bytes + encodedEventBytes <= Limits.TRACE_JOURNAL_MAX_BYTES;
+}
+
+export function selectNewestTraceSuffix<T>(
+  candidates: readonly TraceRetentionCandidate<T>[],
+  reserve: { bytes?: number; events?: number } = {},
+): TraceRetentionSelection<T> {
+  const reservedBytes = reserve.bytes ?? 0;
+  const reservedEvents = reserve.events ?? 0;
+  assertCount(reservedBytes, "reserved Trace bytes");
+  assertCount(reservedEvents, "reserved Trace events");
+  const byteBudget = Math.max(0, Limits.TRACE_JOURNAL_TARGET_BYTES - reservedBytes);
+  const eventBudget = Math.max(0, Limits.TRACE_JOURNAL_TARGET_EVENTS - reservedEvents);
+  let retainedBytes = 0;
+  let start = candidates.length;
+  while (start > 0 && candidates.length - start < eventBudget) {
+    const candidate = candidates[start - 1]!;
+    assertCount(candidate.encodedBytes, "encoded Trace bytes");
+    if (retainedBytes + candidate.encodedBytes > byteBudget) break;
+    retainedBytes += candidate.encodedBytes;
+    start -= 1;
+  }
+  const retained = candidates.slice(start);
+  return {
+    droppedEvents: candidates.length - retained.length,
+    retained,
+    retainedBytes,
+    retainedEvents: retained.length,
+  };
+}
+
+export function accumulateTraceCompactionStatistics(
+  previous: TraceCompactionData | undefined,
+  delta: TraceCompactionDelta,
+): TraceCompactionData {
+  for (const [name, value] of Object.entries(delta)) {
+    if (name !== "dropped_event_count_exact") assertCount(value as number, name);
+  }
+  const prior = previous ?? {
+    compactions_total: 0,
+    dropped_bytes_total: 0,
+    dropped_event_count_exact: true,
+    dropped_malformed_lines_total: 0,
+    dropped_valid_events_total: 0,
+  };
+  const eventCountOverflow = prior.dropped_valid_events_total +
+    delta.dropped_valid_events > Number.MAX_SAFE_INTEGER;
+  return {
+    version: TRACE_COMPACTION_VERSION,
+    compactions_total: boundedAdd(prior.compactions_total, 1),
+    dropped_valid_events_total: boundedAdd(prior.dropped_valid_events_total, delta.dropped_valid_events),
+    dropped_malformed_lines_total: boundedAdd(prior.dropped_malformed_lines_total, delta.dropped_malformed_lines),
+    dropped_bytes_total: boundedAdd(prior.dropped_bytes_total, delta.dropped_bytes),
+    dropped_event_count_exact: prior.dropped_event_count_exact &&
+      delta.dropped_event_count_exact && !eventCountOverflow,
+    retained_events: delta.retained_events,
+    retained_bytes: delta.retained_bytes,
+    history_complete: false,
+  };
+}
+
+export function traceCompactionMarkerInput(data: TraceCompactionData): {
+  data: TraceCompactionData; kind: typeof TRACE_COMPACTION_KIND; level: "warning";
+} {
+  return { data, kind: TRACE_COMPACTION_KIND, level: "warning" };
+}
+
+export function classifyRunControlRecord(value: unknown): "pending" | "terminal" | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const status = (value as { status?: unknown }).status as RunControlStatus;
+  if (PENDING_CONTROL_STATUSES.has(status)) return "pending";
+  if (TERMINAL_CONTROL_STATUSES.has(status)) return "terminal";
+  return undefined;
+}
+
+export function runControlStatusTimestamp(
+  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 computeRunControlCapacity(records: readonly unknown[]): RunControlCapacity {
+  let oldest: { timestamp: string; timestampMs: number } | undefined;
+  let pending = 0;
+  for (const value of records) {
+    if (classifyRunControlRecord(value) !== "pending") continue;
+    pending += 1;
+    const record = value as Record<string, unknown>;
+    const timestamp = runControlStatusTimestamp(record, record.status as RunControlStatus);
+    const timestampMs = typeof timestamp === "string" ? Date.parse(timestamp) : Number.NaN;
+    if (typeof timestamp === "string" && Number.isFinite(timestampMs) &&
+        (!oldest || timestampMs < oldest.timestampMs)) {
+      oldest = { timestamp, timestampMs };
+    }
+  }
+  return {
+    available: Math.max(0, Limits.RUN_CONTROL_PENDING_LIMIT - pending),
+    backpressured: pending >= Limits.RUN_CONTROL_PENDING_LIMIT,
+    limit: Limits.RUN_CONTROL_PENDING_LIMIT,
+    ...(oldest ? { oldest_pending_at: oldest.timestamp } : {}),
+    pending,
+  };
+}
+
+export function decideRunControlAdmission(
+  input: RunControlAdmissionInput,
+): RunControlAdmissionDecision {
+  const capacity = input.capacity ?? computeRunControlCapacity(input.records);
+  const reject = (
+    reason: RunControlAdmissionErrorDetails["reason"],
+    integrityReason?: string,
+  ): RunControlAdmissionDecision => ({
+    admitted: false,
+    capacity,
+    error: {
+      reason,
+      pending: capacity.pending,
+      limit: capacity.limit,
+      journal_bytes: input.journalBytes,
+      journal_limit: Limits.RUN_CONTROL_JOURNAL_MAX_BYTES,
+      ...(capacity.oldest_pending_at ? { oldest_pending_at: capacity.oldest_pending_at } : {}),
+      run_instance_id: input.runInstanceId,
+      next_actions: [...CONTROL_ADMISSION_NEXT_ACTIONS],
+      ...(integrityReason ? { integrity_reason: integrityReason } : {}),
+    },
+  });
+  if (input.integrity !== "valid") return reject("control_journal_integrity", input.integrity);
+  if (!isCount(input.journalBytes) || !isCount(input.retainedJournalBytes) ||
+      !isCount(input.newRecordBytes) ||
+      input.journalBytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+    return reject("control_journal_integrity", "journal_bytes");
+  }
+  for (const value of input.records) {
+    const classification = classifyRunControlRecord(value);
+    if (!classification) return reject("control_journal_integrity", "invalid_record");
+    if (classification !== "pending") continue;
+    const record = value as Record<string, unknown>;
+    const timestamp = runControlStatusTimestamp(record, record.status as RunControlStatus);
+    if (typeof timestamp !== "string" || !Number.isFinite(Date.parse(timestamp))) {
+      return reject("control_journal_integrity", "invalid_status_timestamp");
+    }
+    if (record.run_instance_id !== input.runInstanceId) {
+      return reject("control_journal_integrity", "generation_mismatch");
+    }
+  }
+  if (capacity.backpressured ||
+      input.retainedJournalBytes + input.newRecordBytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+    return reject("control_backpressure");
+  }
+  return { admitted: true, capacity };
+}

package/lib/run-ui-runtime.ts

@@ -106,6 +106,7 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
         ownerId: deps.getRunOwnerId(ctx),
         sink: Pi.createNotificationSink(deps.pi, ctx),
         state: observation,
+        includeAttention: true,
       });
       reportDiagnostics(ctx);
     },
@@ -141,6 +142,7 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     },
     start(ctx) {
       close();
+      Observability.primeRunAttentionState(observation, deps.getRunOwnerId(ctx));
       update(ctx, true, true);
       watcher.refresh();
       reconciliation.start();