@lazyingart/agintiflow 0.20.206 → 0.20.207

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.206",
+  "version": "0.20.207",
   "type": "module",
   "description": "AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-aware intelligence, software automation, and industrial workflows.",
   "license": "Apache-2.0",
@@ -152,6 +152,7 @@
     "smoke:runtime-core": "node scripts/smoke-runtime-core.js",
     "smoke:localllm-auto-max": "node scripts/smoke-localllm-auto-max.js",
     "smoke:localllm-code-routing": "node scripts/smoke-localllm-code-routing.js",
+    "smoke:local-failure-recovery": "node scripts/smoke-local-failure-recovery.js",
     "smoke:local-resource-policy": "node scripts/smoke-local-resource-policy.js",
     "smoke:context-budget-recovery": "node scripts/smoke-context-budget-recovery.js",
     "smoke:localllm-model-tiers": "node scripts/smoke-localllm-model-tiers.js",
@@ -188,7 +189,7 @@
     "storage:migrate": "node bin/aginti-cli.js storage migrate",
     "publish:env": "node scripts/npm-publish-from-env.js publish --access public",
     "publish:env:whoami": "node scripts/npm-publish-from-env.js whoami",
-    "test": "npm run check && npm run smoke:integration-production-mount && npm run smoke:localllm-provider && npm run smoke:localllm-model-tiers && npm run smoke:localllm-code-routing && npm run smoke:localllm-auto-max && npm run smoke:local-resource-policy && npm run smoke:context-budget-recovery && npm run smoke:session-runtime && npm run smoke:runtime-core && npm run smoke:progressive-tools && npm run smoke:truthful-completion && npm run smoke:writing-specialist-routing && npm run eval:local-first-agent && npm run eval:provider-attribution && npm run smoke:runtime-compat && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:math-rendering && npm run smoke:web-ui && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:execution-policy && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:deep-research && npm run smoke:public-research && npm run smoke:safe-chat && npm run smoke:auth && npm run smoke:agentlink && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:mcp && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:supervision-ledger && npm run smoke:tmux-tools && npm run smoke:long-jobs && npm run smoke:run-stdin && npm run smoke:cli-chat && npm run smoke:inbox",
+    "test": "npm run check && npm run smoke:integration-production-mount && npm run smoke:localllm-provider && npm run smoke:localllm-model-tiers && npm run smoke:localllm-code-routing && npm run smoke:local-failure-recovery && npm run smoke:localllm-auto-max && npm run smoke:local-resource-policy && npm run smoke:context-budget-recovery && npm run smoke:session-runtime && npm run smoke:runtime-core && npm run smoke:progressive-tools && npm run smoke:truthful-completion && npm run smoke:writing-specialist-routing && npm run eval:local-first-agent && npm run eval:provider-attribution && npm run smoke:runtime-compat && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:math-rendering && npm run smoke:web-ui && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:execution-policy && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:deep-research && npm run smoke:public-research && npm run smoke:safe-chat && npm run smoke:auth && npm run smoke:agentlink && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:mcp && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:supervision-ledger && npm run smoke:tmux-tools && npm run smoke:long-jobs && npm run smoke:run-stdin && npm run smoke:cli-chat && npm run smoke:inbox",
     "pack:dry-run": "npm pack --dry-run",
     "smoke:capabilities": "node scripts/smoke-capabilities.js"
   },

package/scripts/smoke-progressive-tool-selection.js

@@ -204,6 +204,136 @@ sameNames(
 assert(!names(artifactValidationTools).includes("search_files"), "artifact validation phase reopened broad search");
 assert(!names(artifactValidationTools).includes("open_url"), "artifact validation phase reopened browser discovery");
 
+const localFailureRecoveryTools = selectProgressiveTools(allTools, {
+  config: { provider: "localllm", localFailureRecoveryActive: true },
+  goal: "Recover from repeated failed edits without restarting the task.",
+  profile: "code",
+  messages: [
+    { role: "assistant", tool_calls: [{ id: "failed-edit", function: { name: "apply_patch", arguments: "{}" } }] },
+    { role: "tool", tool_call_id: "failed-edit", content: '{"ok":false}' },
+  ],
+});
+sameNames(
+  localFailureRecoveryTools,
+  ["read_file", "apply_patch", "write_file", "run_command", "search_files", "inspect_project", "finish"],
+  "local failure recovery did not restore the bounded repair surface"
+);
+
+const dataDiscoveryStarterTools = selectProgressiveTools(allTools, {
+  config: { provider: "localllm" },
+  goal: "Clean these experiment exports and leave a reproducible analysis.",
+  profile: "data",
+});
+sameNames(
+  dataDiscoveryStarterTools,
+  ["inspect_project", "finish"],
+  "local data task exposed mutation tools before project inspection"
+);
+
+const dataInspectionMessages = [
+  { role: "user", content: "Goal: Clean these experiment exports and leave a reproducible analysis." },
+  {
+    role: "assistant",
+    tool_calls: [{ id: "data-inspect", function: { name: "inspect_project", arguments: '{"path":"."}' } }],
+  },
+  {
+    role: "tool",
+    tool_call_id: "data-inspect",
+    content: JSON.stringify({
+      ok: true,
+      recommendedReads: ["README.md", "tests/test_analysis.py"],
+      manifestFiles: [{ path: "README.md" }],
+      testFiles: [{ path: "tests/test_analysis.py" }],
+      topLevel: [
+        { path: "analysis.py", type: "file" },
+        { path: "TASK.md", type: "file" },
+      ],
+    }),
+  },
+];
+const dataContextTools = selectProgressiveTools(allTools, {
+  config: { provider: "localllm" },
+  goal: "Clean these experiment exports and leave a reproducible analysis.",
+  profile: "data",
+  messages: dataInspectionMessages,
+});
+sameNames(
+  dataContextTools,
+  ["read_file", "finish"],
+  "local data task exposed mutation tools before reading project contracts"
+);
+assertStrict.deepEqual(
+  enumFor(dataContextTools, "read_file", "path"),
+  ["README.md"],
+  "local data instruction phase did not constrain read_file to discovered instruction paths"
+);
+
+const dataImplementationMessages = [
+  ...dataInspectionMessages,
+  {
+    role: "assistant",
+    tool_calls: [{ id: "data-readme", function: { name: "read_file", arguments: '{"path":"README.md"}' } }],
+  },
+  { role: "tool", tool_call_id: "data-readme", content: '{"ok":true,"path":"README.md"}' },
+];
+const dataImplementationTools = selectProgressiveTools(allTools, {
+  config: { provider: "localllm" },
+  goal: "Clean these experiment exports and leave a reproducible analysis.",
+  profile: "data",
+  messages: dataImplementationMessages,
+});
+sameNames(
+  dataImplementationTools,
+  ["read_file", "finish"],
+  "local data task exposed mutation tools before reading an analyzer/config/test surface"
+);
+assertStrict.deepEqual(
+  enumFor(dataImplementationTools, "read_file", "path"),
+  ["tests/test_analysis.py", "analysis.py"],
+  "local data context phase did not constrain read_file to discovered analysis paths"
+);
+
+const dataReadyMessages = [
+  ...dataImplementationMessages,
+  {
+    role: "assistant",
+    tool_calls: [
+      { id: "data-test", function: { name: "read_file", arguments: '{"path":"tests/test_analysis.py"}' } },
+    ],
+  },
+  { role: "tool", tool_call_id: "data-test", content: '{"ok":true,"path":"tests/test_analysis.py"}' },
+];
+const dataReadyTools = selectProgressiveTools(allTools, {
+  config: { provider: "localllm" },
+  goal: "Clean these experiment exports and leave a reproducible analysis.",
+  profile: "data",
+  messages: dataReadyMessages,
+});
+sameNames(dataReadyTools, LOCAL_COMPACT_CODE_TOOL_NAMES, "local data task did not unlock after bounded discovery");
+
+const dataRecoveryBeforeDiscoveryTools = selectProgressiveTools(allTools, {
+  config: { provider: "localllm", localFailureRecoveryActive: true },
+  goal: "Recover this data task after a failed mutation.",
+  profile: "data",
+});
+sameNames(
+  dataRecoveryBeforeDiscoveryTools,
+  ["inspect_project", "finish"],
+  "local recovery bypassed the incomplete data discovery gate"
+);
+
+const dataRecoveryAfterDiscoveryTools = selectProgressiveTools(allTools, {
+  config: { provider: "localllm", localFailureRecoveryActive: true },
+  goal: "Recover this data task after a failed mutation.",
+  profile: "data",
+  messages: dataReadyMessages,
+});
+sameNames(
+  dataRecoveryAfterDiscoveryTools,
+  ["read_file", "apply_patch", "write_file", "run_command", "search_files", "inspect_project", "finish"],
+  "local recovery remained trapped after data discovery completed"
+);
+
 const artifactRepairTools = selectProgressiveTools(allTools, {
   config: { provider: "localllm", artifactValidationPhase: true, artifactValidationNeedsRepair: true },
   goal: "Repair the exact report from deterministic preflight evidence.",

package/scripts/smoke-skills.js

@@ -90,6 +90,13 @@ assert(selectedIds("debug a C# dotnet web API").includes("dotnet-csharp"), ".NET
 assert(selectedIds("fix a PHP Laravel composer project").includes("php"), "PHP prompt did not select php");
 assert(selectedIds("repair a Ruby Rails app with RSpec").includes("ruby"), "Ruby prompt did not select ruby");
 assert(selectedIds("clean a CSV dataset and make plots").includes("data-analysis"), "data prompt did not select data-analysis");
+const focusedDataSkills = selectedIds(
+  "these experiment exports are a mess; clean them, make a useful plot and report",
+  "data"
+);
+assert(focusedDataSkills.includes("data-analysis"), "explicit data profile omitted its core analysis skill");
+assert(!focusedDataSkills.includes("novel-writing"), "explicit data profile selected unrelated novel guidance");
+assert(!focusedDataSkills.includes("media-transcription-report"), "explicit data profile selected unrelated media guidance");
 assert(selectedIds("convert scanned PDF EPUB and image sources to markdown with OCR").includes("source-ingestion"), "source ingestion prompt did not select source-ingestion");
 assert(selectedIds("use json schema to fetch valid structured json for each chunk in parallel").includes("structured-json"), "structured JSON prompt did not select structured-json");
 assert(selectedIds("write README API docs and a tutorial").includes("docs-knowledge"), "docs prompt did not select docs-knowledge");

package/skills/data-analysis/SKILL.md

@@ -23,7 +23,8 @@ tools:
 ---
 # Data Analysis And ETL
 
-Preserve raw inputs. Inspect schemas, row counts, missing values, duplicate rows, units, time zones, and suspicious outliers before writing conclusions.
+Preserve raw/source/input exports as immutable evidence unless the user explicitly authorizes an in-place source change. Start with `inspect_project`, then read project instructions plus the relevant existing analyzer, configuration, and tests before editing or running ad hoc calculations. Inspect schemas, row counts, missing values, duplicate rows, units, aliases, time zones, and suspicious outliers before writing conclusions.
 
-Prefer a reproducible script over one-off chat math. Save cleaned data, plots, and reports with descriptive filenames. Rerun the script after edits and verify the output actually changed as intended.
+Prefer the project's existing reproducible analyzer over one-off chat math; repair or extend it when needed. Save cleaned data, plots, and reports at the exact declared output paths. Keep machine outputs separate from raw inputs and make the report explain methods, evidence, limitations, and the practical result.
 
+After an edit or patch conflict, reread the exact target and error before choosing a different bounded repair. Never repeat an unchanged failing patch. Rerun the smallest relevant check, then the full analysis and project tests. Verify cleaned schemas and row counts, inspect plot metadata or pixels, remove only generated caches, and do not claim success until every requested artifact exists and can be regenerated.

package/src/agent-runner.js

@@ -7,6 +7,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { chromium } from "playwright";
 import { createClient, createPlan, requestNextStep } from "./model-client.js";
 import { SessionStore } from "./session-store.js";
+import { assertIntegrationRunAgentInvocation } from "./integration-session-persistence.js";
 import { captureSnapshot } from "./snapshot.js";
 import { checkToolUse } from "./guardrails.js";
 import { ensureDockerSandboxReady, runDockerSandboxCommand } from "./docker-sandbox.js";
@@ -60,6 +61,12 @@ import {
   resolveLocalCodeRoute,
   restoreLocalCodePolicy,
 } from "./local-code-routing.js";
+import {
+  activateLocalFailureRecovery,
+  applyLocalFailureRecovery,
+  decideLocalFailureRecovery,
+  localFailureRecoveryInstruction,
+} from "./local-failure-recovery.js";
 import { resolveRuntimeConfig } from "./config.js";
 import {
   captureSessionRuntime,
@@ -236,8 +243,9 @@ function withSelectedSkillReadOnlyRoots(config = {}, state = {}) {
 function throwIfAborted(config) {
   if (config.abortSignal?.aborted) {
     const reason = config.abortSignal.reason;
-    const error = reason instanceof Error ? reason : new Error("Run interrupted by user.");
-    error.name = error.name || "AbortError";
+    if (reason instanceof Error) throw reason;
+    const error = new Error("Run interrupted by user.");
+    error.name = "AbortError";
     throw error;
   }
 }
@@ -2524,9 +2532,10 @@ export function recordExactOutputProgress(state = {}, toolResult = {}, config =
 }
 
 export function nextStepRuntimeConfig(config = {}, state = {}) {
+  const runtimeConfig = applyLocalFailureRecovery(config, state);
   if (state.meta?.artifactProgress?.complete) {
     return {
-      ...config,
+      ...runtimeConfig,
       artifactValidationPhase: true,
       convergenceOutputPhase: false,
       artifactValidationNeedsRepair: state.meta.artifactProgress.needsRepair === true,
@@ -2540,10 +2549,10 @@ export function nextStepRuntimeConfig(config = {}, state = {}) {
     };
   }
   const staticTotal = Number(state.meta?.toolLoop?.staticTotal || 0);
-  if (staticTotal < STATIC_DISCOVERY_CONVERGENCE_LIMIT) return config;
+  if (staticTotal < STATIC_DISCOVERY_CONVERGENCE_LIMIT) return runtimeConfig;
   const requiresPerSourceChecks = state.meta?.scs?.taskContract?.requiresPerSourceChecks === true;
   return {
-    ...config,
+    ...runtimeConfig,
     convergenceOutputPhase: true,
     convergenceAllowRunCommand: requiresPerSourceChecks,
   };
@@ -4166,11 +4175,15 @@ async function recordToolContractViolation({ config, state, store, observers, va
     total: totalViolationCount,
     lastCode: validation.code || "TOOL_CALL_INVALID",
   };
+  const localRecovery = decideLocalFailureRecovery(config, state);
+  const deferStopToLocalRecovery =
+    violationCount >= 2 && localRecovery.active === true && localRecovery.activated === true;
   const result = {
     ok: false,
     blocked: true,
-    recoverable: violationCount < 2,
-    stopRun: violationCount >= 2,
+    recoverable: violationCount < 2 || deferStopToLocalRecovery,
+    stopRun: violationCount >= 2 && !deferStopToLocalRecovery,
+    localFailureRecoveryPending: deferStopToLocalRecovery,
     violationCount,
     reason: validation.reason || "The model returned an invalid tool call and it was not dispatched.",
     category: "tool-contract-violation",
@@ -4524,6 +4537,7 @@ async function recordPreInferenceFailure({ error, config, state, store, observer
 }
 
 export async function runAgent(config) {
+  assertIntegrationRunAgentInvocation(config);
   const incomingConfig = config;
   const sessionId = config.resume || config.sessionId || `web-agent-${crypto.randomUUID()}`;
   const store = new SessionStore(config.sessionsDir, sessionId, {
@@ -5027,6 +5041,37 @@ export async function runAgent(config) {
       const step = state.stepsCompleted + 1;
       throwIfAborted(config);
       await injectQueuedUserMessages(store, state, observers);
+      const localFailureRecovery = activateLocalFailureRecovery(config, state);
+      if (localFailureRecovery.active) {
+        config = applyLocalFailureRecovery(config, state);
+      }
+      if (localFailureRecovery.activated) {
+        state.provider = config.provider;
+        state.model = config.model;
+        state.meta.runtimeConfig = captureSessionRuntime(config, {
+          revision: state.meta.runtimeConfig?.revision || 1,
+        });
+        const recoveryInstruction = localFailureRecoveryInstruction(localFailureRecovery);
+        state.messages.push({ role: "user", content: recoveryInstruction });
+        const detail = {
+          step,
+          fromModel: localFailureRecovery.fromModel,
+          model: localFailureRecovery.model,
+          failureCount: localFailureRecovery.failureCount,
+          repeatedSignatureCount: localFailureRecovery.repeatedSignatureCount,
+          contractViolationCount: localFailureRecovery.contractViolationCount || 0,
+          failedTools: localFailureRecovery.failedTools || [],
+          reason: localFailureRecovery.reason,
+        };
+        await store.appendEvent("provider.local_failure_recovery", detail);
+        observers.event("provider.local_failure_recovery", detail);
+        emitConsole(
+          config,
+          `Local route recovery: ${localFailureRecovery.fromModel} -> ${localFailureRecovery.model} after repeated tool failures.`,
+          { kind: "meta" }
+        );
+        await store.saveState(state);
+      }
       const snapshot = await buildSnapshot(browserState, store, step, config);
       state.meta.lastUrl = snapshot.url || state.meta.lastUrl;
       await saveBrowserState(browserState, store).catch(() => {});

package/src/integration-core-event-projector.js

@@ -59,7 +59,7 @@ const FORBIDDEN_KEYS = new Set([
   "url",
 ]);
 const ABSOLUTE_PATH_OR_SECRET_PATTERN =
-  /(?:^|[\s("'`])(?:\/(?:workspace|home|users|root|etc|usr|var|opt|srv|run|tmp|proc|sys|dev|mnt|media|aginti-(?:home|cache|env))(?:\/|\b)|[A-Za-z]:\\|(?:api[_-]?key|token|secret|password)\s*[:=])/iu;
+  /(?:^|[\s("'`<>\[{=])(?:file:\/\/\/[^\s"'`<>)\]}]+|\/(?!\/)[^\s"'`<>)\]}]+|[A-Za-z]:[\\/][^\s"'`<>)\]}]+|\\\\[^\\/\s"'`<>)\]}]+\\[^\s"'`<>)\]}]+|(?:api[_-]?key|token|secret|password)\s*[:=])/iu;
 const EVENT_LEDGER_STORE_REQUIRED_KEYS = Object.freeze([
   "owner",
   "authority",
@@ -383,29 +383,103 @@ export function createIntegrationCoreEventProjector(options = {}) {
     }
   }
 
+  function toolStateKey(scope) {
+    return `${scope.principalId}\n${scope.browserSessionId}\n${scope.threadId}\n${scope.runId}`;
+  }
+
+  function validateLedgerHeadCursor(headInput, label) {
+    const seq = Number(headInput?.seq ?? 0);
+    const hash = String(headInput?.hash ?? "0".repeat(64));
+    if (
+      !Number.isSafeInteger(seq) ||
+      seq < 0 ||
+      !/^[a-f0-9]{64}$/u.test(hash) ||
+      ((seq === 0) !== (hash === "0".repeat(64)))
+    ) {
+      authorityFail("PUBLIC_EVENT_LEDGER_CORRUPT", `${label} cursor is invalid.`);
+    }
+    return Object.freeze({ seq, hash });
+  }
+
+  function assertPublicEventEnvelopeHash(event, label) {
+    const checked = createPublicIntegrationEvent({
+      threadId: event.threadId,
+      runId: event.runId,
+      seq: event.seq,
+      type: event.type,
+      payload: event.payload,
+      createdAt: event.createdAt,
+      previousHash: event.previousHash,
+    });
+    if (
+      event.schemaVersion !== checked.schemaVersion ||
+      event.id !== checked.id ||
+      event.hash !== checked.hash ||
+      contractDigest(event) !== contractDigest(checked)
+    ) {
+      authorityFail("PUBLIC_EVENT_LEDGER_CORRUPT", `${label} hash is invalid.`);
+    }
+  }
+
+  async function loadLedgerHeadAndLastEvent(ledger, scope) {
+    if (
+      !ledger ||
+      typeof ledger.loadHead !== "function" ||
+      typeof ledger.loadCursor !== "function" ||
+      typeof ledger.loadEventsAfter !== "function"
+    ) {
+      authorityFail("PUBLIC_EVENT_LEDGER_UNAVAILABLE", "Public event ledger head is unavailable.");
+    }
+    const head = validateLedgerHeadCursor(await ledger.loadHead(), "Public event ledger head");
+    if (head.seq === 0) return Object.freeze({ head, lastEvent: null });
+    const cursor = validateLedgerHeadCursor(await ledger.loadCursor(head.seq), "Public event ledger head event");
+    if (cursor.seq !== head.seq || cursor.hash !== head.hash) {
+      authorityFail("PUBLIC_EVENT_LEDGER_CORRUPT", "Public event ledger head cursor does not match the last event.");
+    }
+    const events = await ledger.loadEventsAfter(head.seq - 1);
+    if (!Array.isArray(events) || events.length !== 1) {
+      authorityFail("PUBLIC_EVENT_LEDGER_CORRUPT", "Public event ledger did not return the exact last event.");
+    }
+    const [lastEvent] = events;
+    assertExactPublicEventView(lastEvent, "Public event ledger last event");
+    if (
+      lastEvent.threadId !== scope.threadId ||
+      lastEvent.runId !== scope.runId ||
+      lastEvent.seq !== head.seq ||
+      lastEvent.hash !== head.hash
+    ) {
+      authorityFail("PUBLIC_EVENT_LEDGER_CORRUPT", "Public event ledger last event does not match the requested head.");
+    }
+    if (
+      (lastEvent.principalId !== undefined && lastEvent.principalId !== scope.principalId) ||
+      (lastEvent.browserSessionId !== undefined && lastEvent.browserSessionId !== scope.browserSessionId)
+    ) {
+      authorityFail("PUBLIC_EVENT_LEDGER_CORRUPT", "Public event ledger last event substituted scope.");
+    }
+    assertPublicEventEnvelopeHash(lastEvent, "Public event ledger last event");
+    return Object.freeze({ head, lastEvent });
+  }
+
   async function appendProjectedEvent(projectedInput, scopeInput) {
     const scope = assertScope(scopeInput);
     const projected = projectedInput;
     if (!projected) return null;
+    const projectedIsTerminal = TERMINAL_TYPES.has(projected.type);
+    if ((projected.terminal === true) !== projectedIsTerminal) {
+      authorityFail("UNSUPPORTED_CORE_EVENT", "Projected event terminal flag does not match its public type.", { status: 400 });
+    }
+    const stateKey = toolStateKey(scope);
     const ledger =
       typeof eventLedgerStore.ledgerForRun === "function"
         ? eventLedgerStore.ledgerForRun(scope)
         : null;
     assertLedgerScope(ledger || {}, scope);
-    const head =
-      ledger && typeof ledger.loadHead === "function"
-        ? await ledger.loadHead()
-        : { seq: 0, hash: "0".repeat(64) };
-    const previousSeq = Number(head?.seq || 0);
-    const previousHash = String(head?.hash || "0".repeat(64));
-    if (
-      !Number.isSafeInteger(previousSeq) ||
-      previousSeq < 0 ||
-      !/^[a-f0-9]{64}$/u.test(previousHash) ||
-      ((previousSeq === 0) !== (previousHash === "0".repeat(64)))
-    ) {
-      authorityFail("PUBLIC_EVENT_LEDGER_CORRUPT", "Public event ledger head cursor is invalid.");
+    const { head, lastEvent } = await loadLedgerHeadAndLastEvent(ledger, scope);
+    if (lastEvent && TERMINAL_TYPES.has(lastEvent.type)) {
+      authorityFail("PUBLIC_EVENT_LEDGER_CORRUPT", "Public event ledger terminal finality blocks later run events.");
     }
+    const previousSeq = head.seq;
+    const previousHash = head.hash;
     if (
       projected.expectedPreviousSeq !== undefined &&
       (projected.expectedPreviousSeq !== previousSeq || projected.expectedPreviousHash !== previousHash)
@@ -418,11 +492,23 @@ export function createIntegrationCoreEventProjector(options = {}) {
       createdAt: projected.createdAt,
     });
     assertExactPublicEventView(event, "Public event ledger append");
+    const checked = createPublicIntegrationEvent({
+      threadId: event.threadId,
+      runId: event.runId,
+      seq: event.seq,
+      type: event.type,
+      payload: event.payload,
+      createdAt: event.createdAt,
+      previousHash: event.previousHash,
+    });
     if (
       event.threadId !== scope.threadId ||
       event.runId !== scope.runId ||
+      event.schemaVersion !== checked.schemaVersion ||
+      event.id !== checked.id ||
       event.seq !== previousSeq + 1 ||
       event.previousHash !== previousHash ||
+      event.hash !== checked.hash ||
       event.type !== projected.type ||
       event.createdAt !== projected.createdAt ||
       contractDigest(event.payload) !== contractDigest(projected.payload)
@@ -435,16 +521,7 @@ export function createIntegrationCoreEventProjector(options = {}) {
     ) {
       authorityFail("PUBLIC_EVENT_LEDGER_CORRUPT", "Public event ledger append substituted the requested scope.");
     }
-    const checked = createPublicIntegrationEvent({
-      threadId: event.threadId,
-      runId: event.runId,
-      seq: event.seq,
-      type: event.type,
-      payload: event.payload,
-      createdAt: event.createdAt,
-      previousHash: event.previousHash,
-    });
-    if (checked.hash !== event.hash) {
+    if (checked.hash !== event.hash || contractDigest(checked) !== contractDigest(event)) {
       authorityFail("PUBLIC_EVENT_LEDGER_CORRUPT", "Appended public event hash is invalid.");
     }
     if (ledger && typeof ledger.loadHead === "function") {
@@ -453,36 +530,39 @@ export function createIntegrationCoreEventProjector(options = {}) {
         authorityFail("PUBLIC_EVENT_LEDGER_CORRUPT", "Public event ledger head did not advance to the appended event.");
       }
     }
-    if (projected.terminal) toolStateByRun.delete(scope.runId);
+    if (projected.terminal) {
+      toolStateByRun.delete(stateKey);
+    }
     return Object.freeze({ ...checked, terminal: projected.terminal });
   }
 
   async function appendCoreEvent(type, data, scopeInput) {
     const scope = assertScope(scopeInput);
     const rawType = String(type || "");
+    const stateKey = toolStateKey(scope);
     const needsToolState = TOOL_EVENT_TYPES.has(rawType);
-    const hadState = toolStateByRun.has(scope.runId);
-    let toolState = needsToolState ? toolStateByRun.get(scope.runId) : undefined;
+    const hadState = toolStateByRun.has(stateKey);
+    let toolState = needsToolState ? toolStateByRun.get(stateKey) : undefined;
     if (needsToolState && !toolState) {
       toolState = { nextOrdinal: 0, activeByTool: new Map() };
-      toolStateByRun.set(scope.runId, toolState);
+      toolStateByRun.set(stateKey, toolState);
     }
     const snapshot = needsToolState ? snapshotToolState(toolState) : null;
     let projected = null;
     try {
       projected = projectCoreEvent(type, data, { now, runId: scope.runId, ...(needsToolState ? { toolState } : {}) });
     } catch (error) {
-      if (needsToolState) restoreToolState(scope.runId, hadState, snapshot);
+      if (needsToolState) restoreToolState(stateKey, hadState, snapshot);
       throw error;
     }
     if (!projected) {
-      if (needsToolState) restoreToolState(scope.runId, hadState, snapshot);
+      if (needsToolState) restoreToolState(stateKey, hadState, snapshot);
       return null;
     }
     try {
       return await appendProjectedEvent(projected, scope);
     } catch (error) {
-      if (needsToolState) restoreToolState(scope.runId, hadState, snapshot);
+      if (needsToolState) restoreToolState(stateKey, hadState, snapshot);
       throw error;
     }
   }
@@ -496,8 +576,12 @@ export function createIntegrationCoreEventProjector(options = {}) {
     owner: "aginti",
     authority: "aginti",
     appendCoreEvent,
-    appendProjectedEvent,
     appendAuthorityTerminalEvent,
+    clearRun(scopeInput, options = {}) {
+      const scope = assertScope(scopeInput);
+      const stateKey = toolStateKey(scope);
+      toolStateByRun.delete(stateKey);
+    },
     projectCoreEvent(type, data, scope = {}) {
       return projectCoreEvent(type, data, { now, runId: scope.runId || "" });
     },