@llblab/pi-actors 0.43.1 → 0.44.0

package/lib/tools-inspect.ts

@@ -4,12 +4,14 @@
  * Owns exact inspect target/view dispatch; source projection stays in domain modules.
  */
 
+import { statSync } from "node:fs";
 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 { computeRunControlCapacity } from "./run-evidence-policy.ts";
 import * as Paths from "./paths.ts";
 import * as RecipesDiscovery from "./recipes-discovery.ts";
 import * as ReviewDiagnostics from "./review-diagnostics.ts";
@@ -75,20 +77,26 @@ function runtimeTriage(
   const failed = runs.filter((run) => run.status === "failed");
   const pendingControls: RuntimeTriage.RuntimePendingControl[] = [];
   const staleControls: RuntimeTriage.RuntimePendingControl[] = [];
+  const backpressuredRuns: Array<Record<string, unknown>> = [];
   const controlDiagnostics: Array<Record<string, unknown>> = [];
+  const traceDiagnostics: 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) continue;
     const runId = String(run.run ?? "unknown");
     const journal = RunsControls.readRunControlJournalFromStateDir(stateDir);
+    const capacity = computeRunControlCapacity(journal.records);
     controlDiagnostics.push(...journal.diagnostics.map((diagnostic) => ({
       ...(diagnostic.line === undefined ? {} : { line: diagnostic.line }),
-      reason: diagnostic.line === undefined
-        ? "unreadable_control_journal"
-        : "invalid_control_json",
-      run: runId,
+      reason: diagnostic.line === undefined ? "unreadable_control_journal" : "invalid_control_json", run: runId,
     })));
+    if (capacity.backpressured) backpressuredRuns.push({
+      run: runId, pending: capacity.pending, pending_limit: capacity.limit,
+      journal_bytes: statSync(RunsControls.runControlsFile(stateDir)).size,
+    });
+    const traceSummary = RunsTrace.summarizeRunTraceJournal(RunsTrace.readRunTraceJournal(stateDir));
+    if (!traceSummary.history_complete) traceDiagnostics.push({ run: runId, ...traceSummary });
     for (const control of journal.records) {
       const classified = RuntimeTriage.classifyRuntimeControl(
         {
@@ -137,14 +145,15 @@ function runtimeTriage(
     pending_controls: boundedPendingControls,
     stale_control_count: staleControls.length,
     stale_controls: boundedStaleControls,
-    control_diagnostic_count: controlDiagnostics.length,
-    control_diagnostics: controlDiagnostics.slice(0, 40),
+    backpressured_run_count: backpressuredRuns.length, backpressured_runs: backpressuredRuns.slice(0, 40),
+    control_diagnostic_count: controlDiagnostics.length, control_diagnostics: controlDiagnostics.slice(0, 40),
+    trace_diagnostic_count: traceDiagnostics.length, trace_diagnostics: traceDiagnostics.slice(0, 40),
     attention_events: attentionEvents.slice(-40).reverse(),
     next_actions: [
       ...(failed.length ? ["inspect target=runtime view=runs status=failed"] : []),
-      ...staleControls.slice(0, 3).map((entry) =>
+      ...new Set([...staleControls, ...backpressuredRuns].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`,
@@ -159,7 +168,7 @@ 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} 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 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)} backpressured=${Number(details.backpressured_run_count ?? 0)} incomplete_trace=${Number(details.trace_diagnostic_count ?? 0)} attention=${(details.attention_events as unknown[] | undefined)?.length ?? 0}`;
   }
   return `\nruntime version=${String(details.version)} state_schema=${String(details.state_schema)} automatic_review=${String(details.automatic_review)}`;
 }
@@ -252,8 +261,8 @@ function inspectRun(
       throw new Error(`unsupported Trace source: ${source}`);
     }
     return {
-      run,
-      source,
+      run, source,
+      summary: RunsTrace.summarizeRunTraceJournal(RunsTrace.readRunTraceJournal(stateDir)),
       items: TraceProjection.projectRunTrace(stateDir, {
         artifacts: status.artifacts as
           | Record<string, AsyncRuns.RunArtifactDeclaration>
@@ -264,19 +273,40 @@ function inspectRun(
     };
   }
   const runInstanceId = String(status.run_instance_id ?? "");
+  const journal = RunsControls.readRunControlJournalFromStateDir(stateDir);
+  const capacity = computeRunControlCapacity(journal.records);
+  const structuralDiagnostics = journal.records.flatMap((value) => {
+    const classified = RuntimeTriage.classifyRuntimeControl({ run,
+      runInstanceId: runInstanceId || undefined, status: String(status.status ?? "unknown") }, value, Date.now());
+    return classified.diagnostic ? [classified.diagnostic.reason] : [];
+  });
+  let journalBytes = 0;
+  try { journalBytes = statSync(RunsControls.runControlsFile(stateDir)).size; } catch {}
+  const diagnostics = [...journal.diagnostics.map((item) => ({
+    ...(item.line === undefined ? {} : { line: item.line }),
+    reason: item.line === undefined ? "unreadable_control_journal" : "invalid_control_json",
+  })), ...structuralDiagnostics.map((reason) => ({ reason }))].slice(0, 40);
+  const nowMs = Date.now();
+  const stalePending = journal.records.reduce<number>((count, control) => count + Number(Boolean(
+    RuntimeTriage.classifyRuntimeControl({ run, runInstanceId: runInstanceId || undefined,
+      status: String(status.status ?? "unknown") }, control, nowMs).stale)), 0);
   return {
     run,
     run_instance_id: runInstanceId,
     status: status.status,
+    pending: capacity.pending, pending_limit: capacity.limit,
+    available: capacity.available, backpressured: capacity.backpressured,
+    journal_bytes: journalBytes, journal_limit: Limits.RUN_CONTROL_JOURNAL_MAX_BYTES,
+    ...(capacity.oldest_pending_at ? { oldest_pending_at: capacity.oldest_pending_at } : {}),
+    stale_pending: stalePending,
+    diagnostics,
     actor_actions: Array.isArray(status.control) ? status.control : [],
     runtime_actions: status.status === "running" ? ["kill"] : ["archive", "prune"],
     endpoint: runInstanceId
       ? RunControlDelivery.readRunControlEndpoint(stateDir, runInstanceId)
       : undefined,
-    recent_controls: RunsControls.readRunControlsFromStateDir(stateDir)
-      .slice(-Math.max(1, Number(input.lines || 20)))
-      .reverse()
-      .map(ControlProjection.projectRunControl),
+    recent_controls: journal.records.slice(-Math.max(1, Number(input.lines || 20))).reverse()
+      .map((control) => ControlProjection.projectRunControl(control as RunsControls.RunControlRecord)),
   };
 }
 

package/lib/trace-projection.ts

@@ -14,13 +14,13 @@ import {
   resolveArtifactManifest,
   type RunArtifactDeclaration,
 } from "./runs-artifacts.ts";
+import * as RunsControls from "./runs-controls.ts";
 import type { RunControlRecord } from "./runs-controls.ts";
 import { tailFile } from "./runs-status.ts";
-import type { TraceEvent } from "./runs-trace.ts";
+import * as RunsTrace from "./runs-trace.ts";
 import * as SessionEvidence from "./session-evidence.ts";
 import {
   readJsonFileResilient,
-  readJsonlFileResilient,
   type StateReadDiagnostic,
 } from "./state-readers.ts";
 
@@ -44,19 +44,52 @@ export interface TraceItem {
   detail: unknown;
 }
 
+interface OrderedTraceItem {
+  item: TraceItem;
+  ordinal: number;
+  sourceKey: string;
+}
+
 const LIFECYCLE_PREFIXES = ["run.", "command."];
 const SOURCE_LIMIT = 100;
+const SOURCE_RANK: Record<TraceSource, number> = {
+  lifecycle: 6,
+  control: 5,
+  process: 4,
+  agent: 3,
+  artifact: 2,
+  runtime: 1,
+};
 
 function redact(value: unknown): unknown {
   return SessionEvidence.redactSessionEvidenceValue(value);
 }
 
-function sourceForEvent(event: TraceEvent): TraceSource {
+function sourceForEvent(event: RunsTrace.TraceEvent): TraceSource {
   return LIFECYCLE_PREFIXES.some((prefix) => event.kind.startsWith(prefix))
     ? "lifecycle"
     : "runtime";
 }
 
+function ordered(
+  item: TraceItem,
+  sourceKey: string,
+  ordinal: number,
+): OrderedTraceItem {
+  return { item, ordinal, sourceKey };
+}
+
+function compareTraceItems(left: OrderedTraceItem, right: OrderedTraceItem): number {
+  const timestamp = right.item.ts.localeCompare(left.item.ts);
+  if (timestamp) return timestamp;
+  if (left.sourceKey === right.sourceKey) {
+    const ordinal = right.ordinal - left.ordinal;
+    if (ordinal) return ordinal;
+  }
+  return SOURCE_RANK[right.item.source] - SOURCE_RANK[left.item.source] ||
+    right.item.id.localeCompare(left.item.id);
+}
+
 function latestControlTimestamp(control: RunControlRecord): string {
   return (
     control.failed_at ??
@@ -98,125 +131,154 @@ function controlDiagnosticItems(
   }));
 }
 
-function traceEventItems(stateDir: string): TraceItem[] {
-  const read = readJsonlFileResilient<TraceEvent>(join(stateDir, "trace.jsonl"));
-  return [
-    ...read.records.slice(-SOURCE_LIMIT).map((event) => ({
-      id: event.id,
-      ts: event.ts,
-      source: sourceForEvent(event),
-      kind: event.kind,
-      summary: event.summary ?? event.kind,
-      ...(event.level ? { level: event.level } : {}),
-      detail: redact({
-        ...(event.attention ? { attention: event.attention } : {}),
-        ...(event.data !== undefined ? { data: event.data } : {}),
-      }),
-    } satisfies TraceItem)),
-    ...diagnosticItems(read.diagnostics),
-  ];
+function traceEventItems(stateDir: string): OrderedTraceItem[] {
+  const read = RunsTrace.readRunTraceJournal(stateDir);
+  const retained = read.events.slice(-SOURCE_LIMIT);
+  const projected = retained.map(({ event, ordinal }) => ordered({
+    id: event.id,
+    ts: event.ts,
+    source: sourceForEvent(event),
+    kind: event.kind,
+    summary: event.summary ?? event.kind,
+    ...(event.level ? { level: event.level } : {}),
+    detail: redact({
+      ...(event.attention ? { attention: event.attention } : {}),
+      ...(event.data !== undefined ? { data: event.data } : {}),
+    }),
+  }, "trace", ordinal));
+  const diagnostics = diagnosticItems(read.diagnostics).map((item, index) =>
+    ordered(item, "trace", read.events.length + index + 1)
+  );
+  const hasMarker = read.events.some(
+    ({ event }) => event.kind === "runtime.trace_compacted",
+  );
+  if (read.omittedPrefixBytes > 0 && !hasMarker) {
+    diagnostics.push(ordered({
+      id: "runtime:trace-history-incomplete",
+      ts: new Date(0).toISOString(),
+      source: "runtime",
+      kind: "runtime.trace_history_incomplete",
+      summary: "Trace history is incomplete",
+      level: "warning",
+      detail: {
+        omitted_prefix_bytes: read.omittedPrefixBytes,
+        read_bytes: read.readBytes,
+        retained_events: read.events.length,
+      },
+    }, "trace", 0));
+  }
+  return [...projected, ...diagnostics];
 }
 
-function controlItems(stateDir: string): TraceItem[] {
-  const read = readJsonlFileResilient<RunControlRecord>(
-    join(stateDir, "controls.jsonl"),
-  );
+function controlItems(stateDir: string): OrderedTraceItem[] {
+  const read = RunsControls.readRunControlJournalFromStateDir(stateDir);
+  const start = Math.max(0, read.records.length - SOURCE_LIMIT);
+  const projected = read.records.slice(start).map((control, index) => {
+    const value = ControlProjection.projectRunControl(control as RunControlRecord);
+    return ordered({
+      id: `control:${value.id}`,
+      ts: latestControlTimestamp(value),
+      source: "control",
+      kind: `control.${value.status}`,
+      summary: `${value.action} ${value.status}`,
+      ...(value.status === "failed" ? { level: "error" as const } : {}),
+      detail: value,
+    }, "control", start + index + 1);
+  });
   return [
-    ...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),
+    ...projected,
+    ...controlDiagnosticItems(read.diagnostics).map((item, index) =>
+      ordered(item, "control", read.records.length + index + 1)
+    ),
   ];
 }
 
-function agentItems(stateDir: string): TraceItem[] {
+function agentItems(stateDir: string): OrderedTraceItem[] {
   return ExecutionSessions.readExecutionTurns(stateDir)
     .slice(-SOURCE_LIMIT)
     .map((turn) => {
       const text = turn.assistantText ?? turn.userText ?? "Agent turn";
       const summary = text.replaceAll(/\s+/g, " ").trim().slice(0, 160);
-      return {
+      return ordered({
         id: `agent:${turn.commandId}:${turn.sessionFile}:${turn.index}`,
         ts: turn.timestamp ?? new Date(0).toISOString(),
-        source: "agent" as const,
+        source: "agent",
         kind: "agent.turn",
         summary: summary || "Agent turn",
         ...(turn.error ? { level: "error" as const } : {}),
         detail: redact(turn),
-      };
+      }, "agent", turn.index);
     });
 }
 
-function processItems(stateDir: string): TraceItem[] {
+function processItems(stateDir: string): OrderedTraceItem[] {
   return ["stdout", "stderr"].flatMap((stream) => {
     const path = join(stateDir, `${stream}.log`);
     if (!existsSync(path)) return [];
     const stat = statSync(path);
     const tail = tailFile(path, Limits.DEFAULT_INSPECT_LINES);
     if (!tail && stat.size === 0) return [];
-    return [{
+    return [ordered({
       id: `process:${stream}`,
       ts: stat.mtime.toISOString(),
-      source: "process" as const,
+      source: "process",
       kind: `process.${stream}`,
       summary: `${stream} (${stat.size} bytes)`,
       ...(stream === "stderr" ? { level: "warning" as const } : {}),
       detail: redact({ bytes: stat.size, path, tail }),
-    }];
+    }, `process:${stream}`, 1)];
   });
 }
 
-function resultItems(stateDir: string): TraceItem[] {
+function resultItems(stateDir: string): OrderedTraceItem[] {
   const path = join(stateDir, "result.json");
   const read = readJsonFileResilient<Record<string, unknown>>(path, {});
-  if (Object.keys(read.value).length === 0) return diagnosticItems(read.diagnostics);
+  if (Object.keys(read.value).length === 0) {
+    return diagnosticItems(read.diagnostics).map((item, index) =>
+      ordered(item, "process:result", index)
+    );
+  }
   const stat = statSync(path);
   const failed = Number(read.value.code ?? 0) !== 0;
-  return [{
+  return [ordered({
     id: "process:result",
-    ts:
-      typeof read.value.completedAt === "string"
-        ? read.value.completedAt
-        : stat.mtime.toISOString(),
+    ts: typeof read.value.completedAt === "string"
+      ? read.value.completedAt
+      : stat.mtime.toISOString(),
     source: "process",
     kind: failed ? "process.failed" : "process.result",
     summary: failed ? "Run process failed" : "Run process completed",
     ...(failed ? { level: "error" as const } : {}),
     detail: redact(read.value),
-  }, ...diagnosticItems(read.diagnostics)];
+  }, "process:result", 1), ...diagnosticItems(read.diagnostics).map(
+    (item, index) => ordered(item, "process:result", index + 2),
+  )];
 }
 
 function artifactItems(
   stateDir: string,
   declarations: Record<string, RunArtifactDeclaration> | undefined,
-): TraceItem[] {
+): OrderedTraceItem[] {
   const manifest = resolveArtifactManifest(declarations);
   if (!manifest) return [];
-  return Object.entries(manifest).slice(0, SOURCE_LIMIT).map(([name, artifact]) => ({
-    id: `artifact:${name}`,
-    ts: artifact.exists && existsSync(artifact.path)
-      ? statSync(artifact.path).mtime.toISOString()
-      : new Date(0).toISOString(),
-    source: "artifact",
-    kind: artifact.exists ? "artifact.ready" : "artifact.missing",
-    summary: `${name}: ${artifact.exists ? "ready" : "missing"}`,
-    ...(artifact.required && !artifact.exists ? { level: "warning" as const } : {}),
-    detail: redact({
-      exists: artifact.exists,
-      path: relative(stateDir, artifact.path).replaceAll("\\", "/"),
-      required: artifact.required,
-      ...(artifact.size !== undefined ? { size: artifact.size } : {}),
-    }),
-  }));
+  return Object.entries(manifest).slice(0, SOURCE_LIMIT).map(
+    ([name, artifact], index) => ordered({
+      id: `artifact:${name}`,
+      ts: artifact.exists && existsSync(artifact.path)
+        ? statSync(artifact.path).mtime.toISOString()
+        : new Date(0).toISOString(),
+      source: "artifact",
+      kind: artifact.exists ? "artifact.ready" : "artifact.missing",
+      summary: `${name}: ${artifact.exists ? "ready" : "missing"}`,
+      ...(artifact.required && !artifact.exists ? { level: "warning" as const } : {}),
+      detail: redact({
+        exists: artifact.exists,
+        path: relative(stateDir, artifact.path).replaceAll("\\", "/"),
+        required: artifact.required,
+        ...(artifact.size !== undefined ? { size: artifact.size } : {}),
+      }),
+    }, "artifact", index + 1),
+  );
 }
 
 export function projectRunTrace(
@@ -236,9 +298,9 @@ export function projectRunTrace(
     ...resultItems(stateDir),
     ...artifactItems(stateDir, options.artifacts),
   ]
-    .filter((item) => source === "all" || item.source === source)
-    .sort((left, right) =>
-      right.ts.localeCompare(left.ts) || right.id.localeCompare(left.id),
-    );
-  return items.slice(0, Math.max(1, Math.min(options.limit ?? 100, 200)));
+    .filter(({ item }) => source === "all" || item.source === source)
+    .sort(compareTraceItems);
+  return items
+    .slice(0, Math.max(1, Math.min(options.limit ?? 100, 200)))
+    .map(({ item }) => item);
 }

package/package.json

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

package/scripts/conformance.mjs

@@ -15,6 +15,11 @@ const conformanceSuites = [
   "tests/control.test.ts",
   "tests/runs-controls.test.ts",
   "tests/runs-trace.test.ts",
+  "tests/observability.test.ts",
+  "tests/async-run-control.test.ts",
+  "tests/run-kernel-dogfood.test.ts",
+  "tests/installed.scripts.test.ts",
+  "tests/inspector-overlay.test.ts",
   "tests/tools-inspect-kernel.test.ts",
   "tests/recipes-discovery.test.ts",
   "tests/review-swarm-dogfood.test.ts",

package/scripts/locker.mjs

@@ -11,7 +11,6 @@
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
-  appendFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -32,8 +31,12 @@ async function importRuntimeModule(name) {
   return await import(pathToFileURL(existsSync(compiled) ? compiled : source).href);
 }
 
-const { acquireFileMutationLock, writeJsonAtomic, writeTextAtomic } =
-  await importRuntimeModule("file-state");
+const { acquireFileMutationLock, writeJsonAtomic, writeTextAtomic } = await importRuntimeModule("file-state");
+const { readJsonlFileResilient } = await importRuntimeModule("state-readers");
+const LOCKER_JOURNAL_MAX_RECORDS = 512;
+const LOCKER_JOURNAL_MAX_BYTES = 1024 * 1024;
+const { claimRunControlByIdInStateDir, updateRunControlStatusInStateDir } =
+  await importRuntimeModule("runs-controls");
 const { appendRunTraceEvent } = await importRuntimeModule("runs-trace");
 
 function parseArgs(argv) {
@@ -59,7 +62,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 controlsPath = join(stateDir, "controls.jsonl");
   const controlPath = join(stateDir, "control.fifo");
   let runInstanceId;
   mkdirSync(stateDir, { recursive: true });
@@ -96,10 +98,22 @@ async function runLocker(argv = process.argv.slice(2)) {
   }
 
   function journal(event, data = {}) {
-    appendFileSync(
-      journalPath,
-      `${JSON.stringify({ event, ts: new Date().toISOString(), ...data })}\n`,
-    );
+    const release = acquireFileMutationLock(journalPath);
+    try {
+      const records = [...readJsonlFileResilient(journalPath).records,
+        { event, ts: new Date().toISOString(), ...data }]
+        .slice(-LOCKER_JOURNAL_MAX_RECORDS);
+      let content = encodeJournal(records);
+      while (records.length && Buffer.byteLength(content) > LOCKER_JOURNAL_MAX_BYTES) {
+        records.shift();
+        content = encodeJournal(records);
+      }
+      writeTextAtomic(journalPath, content);
+    } finally { release(); }
+  }
+
+  function encodeJournal(records) {
+    return records.length ? `${records.map((record) => JSON.stringify(record)).join("\n")}\n` : "";
   }
 
   function emitTrace(kind, summary, data = {}, level = "info") {
@@ -147,69 +161,6 @@ async function runLocker(argv = process.argv.slice(2)) {
     }
   }
 
-  function acquireControlsLock() {
-    return acquireFileMutationLock(controlsPath);
-  }
-
-  function readControls() {
-    if (!existsSync(controlsPath)) return [];
-    return readFileSync(controlsPath, "utf8")
-      .split("\n")
-      .filter((line) => line.trim())
-      .map((line) => {
-        try {
-          return JSON.parse(line);
-        } catch {
-          return undefined;
-        }
-      })
-      .filter(Boolean);
-  }
-
-  function writeControls(controls) {
-    writeTextAtomic(
-      controlsPath,
-      controls.length
-        ? `${controls.map((control) => JSON.stringify(control)).join("\n")}\n`
-        : "",
-    );
-  }
-
-  function claimControl(id) {
-    const release = acquireControlsLock();
-    try {
-      const controls = readControls();
-      const control = controls.find((item) => item.id === id);
-      if (
-        !control ||
-        control.run_instance_id !== runInstanceId ||
-        (control.status !== "queued" && control.status !== "delivered")
-      ) {
-        return undefined;
-      }
-      control.claimed_at = new Date().toISOString();
-      control.status = "claimed";
-      writeControls(controls);
-      return { ...control };
-    } finally {
-      release();
-    }
-  }
-
-  function finalizeControl(id, status, error) {
-    const release = acquireControlsLock();
-    try {
-      const controls = readControls();
-      const control = controls.find((item) => item.id === id);
-      if (!control || control.status !== "claimed") return;
-      control.status = status;
-      control[`${status}_at`] = new Date().toISOString();
-      if (error) control.error = error;
-      writeControls(controls);
-    } finally {
-      release();
-    }
-  }
 
   function tailJournal(count) {
     if (!existsSync(journalPath)) return [];
@@ -397,7 +348,9 @@ async function runLocker(argv = process.argv.slice(2)) {
   function handleLine(line) {
     const control = normalizeControl(line);
     if (!control) return false;
-    const claimed = claimControl(control.id);
+    const claimed = claimRunControlByIdInStateDir(
+      stateDir, runInstanceId, control.id,
+    );
     if (!claimed) {
       emitTrace(
         "lock.control_rejected",
@@ -409,11 +362,15 @@ async function runLocker(argv = process.argv.slice(2)) {
     }
     try {
       const stopping = handle(claimed) === true;
-      finalizeControl(claimed.id, "handled");
+      updateRunControlStatusInStateDir(
+        stateDir, claimed.id, "handled", {}, ["claimed"],
+      );
       return stopping;
     } catch (error) {
       const text = error instanceof Error ? error.message : String(error);
-      finalizeControl(claimed.id, "failed", text);
+      updateRunControlStatusInStateDir(
+        stateDir, claimed.id, "failed", { error: text }, ["claimed"],
+      );
       journal("lock.error", { error: text });
       emitTrace("lock.error", text, { error: text }, "error");
       return false;