@kontourai/flow-agents 3.9.0 → 3.10.0

package/src/cli/public-api.test.mjs

@@ -37,6 +37,7 @@ test("public API retains the documented native-host compatibility surface", asyn
     "startBuilderBuildRun", "evaluateBuilderBuildRun", "startBuilderFlowSession",
     "pauseBuilderFlowSession", "resumeBuilderFlowSession", "cancelBuilderFlowSession",
     "archiveBuilderFlowSession", "recoverBuilderFlowSession", "releaseBuilderFlowAssignment",
+    "ContinuationAdapterTimeoutError",
     "writeJson", "appendJsonl", "sidecarBase", "writeState", "writeSidecar",
   ]) {
     assert.equal(typeof lib[name], "function", `${name} must remain package-root exported`);

package/src/cli/validate-workflow-artifacts.ts

@@ -22,6 +22,10 @@ const sidecarSchemas: Record<string, string> = {
   "release.json": "schemas/workflow-release.schema.json",
   "learning.json": "schemas/workflow-learning.schema.json",
 };
+// Runtime coordination records live below a session but are not workflow
+// sidecars. Recursing into them would validate continuation-driver/state.json
+// against the public workflow-state schema and turn an active driver into a
+// false Goal Fit hard block.
 
 function readText(file: string): string {
   return fs.readFileSync(file, "utf8");
@@ -91,11 +95,25 @@ function hasExplicitAcceptance(text: string): boolean {
   return /explicitly accepted|accepted by user|user accepted|accepted gap/i.test(text);
 }
 
+function isPrivateRuntimeChild(dir: string): boolean {
+  if (path.basename(dir) !== "continuation-driver") return false;
+  const sessionDir = path.dirname(dir);
+  const sessionState = path.join(sessionDir, "state.json");
+  try {
+    const stat = fs.lstatSync(sessionState);
+    if (stat.isSymbolicLink() || !stat.isFile()) return false;
+    const state = JSON.parse(readText(sessionState)) as { task_slug?: unknown };
+    return state.task_slug === path.basename(sessionDir);
+  } catch {
+    return false;
+  }
+}
+
 function walk(dir: string): string[] {
   const out: string[] = [];
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const p = path.join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...walk(p));
+    if (entry.isDirectory() && !isPrivateRuntimeChild(p)) out.push(...walk(p));
     else out.push(p);
   }
   return out;

package/src/cli/workflow-sidecar.ts

@@ -275,7 +275,9 @@ function resolveEnsureSessionActor(p: ReturnType<typeof parseArgs>): { actorStru
     die("ensure-session --actor value strips to empty under the allowed actor charset ([A-Za-z0-9_.-]) — pass a value containing at least one letter, digit, underscore, period, or hyphen.");
   }
   const explicitActor = explicitActorRaw ? helper.sanitizeSegment(explicitActorRaw) : "";
-  const resolved = explicitActor ? { actor: explicitActor, source: "explicit-override" } : helper.resolveActor(process.env);
+  const resolved = explicitActor
+    ? { actor: explicitActor, source: "explicit-override", actorStruct: { runtime: "explicit-override", session_id: explicitActor, host: os.hostname() } }
+    : helper.resolveActorIdentity(process.env);
   const unresolved = helper.isUnresolvedActor(resolved.actor);
   const branchActorKey = unresolved ? `unknown-actor-${unknownDisambiguator(resolved.actor)}` : resolved.actor;
 
@@ -286,17 +288,8 @@ function resolveEnsureSessionActor(p: ReturnType<typeof parseArgs>): { actorStru
     return { actorStruct: { runtime: "unresolved", session_id: branchActorKey, host: os.hostname() }, actorKey: resolved.actor, branchActorKey, unresolved: true };
   }
 
-  // #398: the CI-runtime tier must reconstruct the SAME struct resolveActor serialized, or
-  // `serializeActor(actorStruct)` would diverge from `resolved.actor` (the else-branch would rebuild
-  // an ANCESTRY struct — detectRuntime→unknown, runtimeSessionId→'' — so the claim's stored
-  // actor_key would not match the CI actor at publish → self not recognized → false-block, the exact
-  // bug this issue removes). Uses the SAME helper.detectCiActor as resolveActor, single-sourced.
-  const ciActor = resolved.source.startsWith("ci-runtime") ? helper.detectCiActor(process.env) : null;
-  const actorStruct: ActorStruct = resolved.source === "explicit-override"
-    ? { runtime: "explicit-override", session_id: resolved.actor, host: os.hostname() }
-    : ciActor && ciActor.session_id
-      ? { runtime: ciActor.runtime, session_id: ciActor.session_id, host: os.hostname() }
-      : { runtime: helper.detectRuntime(process.env), session_id: helper.runtimeSessionId(process.env) || (() => { const seed = helper.ancestorActorSeed(); return seed ? `anc-${seed}` : ""; })(), host: os.hostname() };
+  if (!resolved.actorStruct) die("ensure-session could not resolve a canonical actor struct");
+  const actorStruct: ActorStruct = resolved.actorStruct;
   const actorKey = helper.serializeActor(actorStruct);
   return { actorStruct, actorKey, branchActorKey, unresolved: false };
 }
@@ -1613,6 +1606,7 @@ function resolveFirstStep(flowId: string, repoRoot: string): string | null {
 function loadCurrentPointerHelper(): {
   perActorCurrentFile: (flowAgentsDir: string, actorKey: string) => string;
   readCurrentPointer: (flowAgentsDir: string, actorKey?: string) => { payload: AnyObj | null; source: "per-actor" | "legacy" | "none"; file: string | null };
+  readOwnCurrentPointer: (flowAgentsDir: string, actorKey?: string) => { payload: AnyObj | null; source: "per-actor" | "legacy" | "none"; file: string | null };
   writePerActorCurrent: (flowAgentsDir: string, actorKey: string, payload: AnyObj) => void;
 } {
   const _req = createRequire(import.meta.url);
@@ -1620,6 +1614,7 @@ function loadCurrentPointerHelper(): {
   return _req(helperPath) as {
     perActorCurrentFile: (flowAgentsDir: string, actorKey: string) => string;
     readCurrentPointer: (flowAgentsDir: string, actorKey?: string) => { payload: AnyObj | null; source: "per-actor" | "legacy" | "none"; file: string | null };
+    readOwnCurrentPointer: (flowAgentsDir: string, actorKey?: string) => { payload: AnyObj | null; source: "per-actor" | "legacy" | "none"; file: string | null };
     writePerActorCurrent: (flowAgentsDir: string, actorKey: string, payload: AnyObj) => void;
   };
 }
@@ -1758,9 +1753,15 @@ function updateCurrentAgent(root: string, dir: string, agentId: string, status:
 
   if (actorKey && !loadActorIdentityHelper().isUnresolvedActor(actorKey)) {
     const helper = loadCurrentPointerHelper();
-    const perActorFile = helper.perActorCurrentFile(root, actorKey);
-    let perActor: AnyObj | null = null;
-    try { perActor = fs.existsSync(perActorFile) ? (JSON.parse(fs.readFileSync(perActorFile, "utf8")) as AnyObj) : null; } catch { perActor = null; }
+    // #440 fix-wave 3: read through the legacy-aware path (readOwnCurrentPointer tries the new
+    // collision-resistant filename first, then falls back to the pre-fix-wave-2 legacy filename)
+    // instead of a direct fs read of perActorCurrentFile() alone — a direct read of ONLY the new
+    // filename would silently skip this active_agents/updated_at projection for a pointer a
+    // still-running pre-fix-wave-2 sidecar wrote under the old name. The write below always goes
+    // through writePerActorCurrent (new filename only), so the pointer migrates to the new name
+    // on first touch.
+    const pointer = helper.readOwnCurrentPointer(root, actorKey);
+    const perActor = pointer.payload;
     if (perActor && path.resolve(root, perActor.artifact_dir ?? "") === path.resolve(dir)) {
       helper.writePerActorCurrent(root, actorKey, applyAgentUpdate(perActor));
     }
@@ -6088,6 +6089,7 @@ export const LIVENESS_TERMINAL = new Set(["delivered", "canceled", "accepted", "
  */
 function loadActorIdentityHelper(): {
   resolveActor: (env: NodeJS.ProcessEnv) => { actor: string; source: string };
+  resolveActorIdentity: (env: NodeJS.ProcessEnv) => { actor: string; source: string; actorStruct: ActorStruct | null };
   sanitizeSegment: (value: unknown) => string;
   isUnresolvedActor: (actor: string) => boolean;
   // #291 Wave 2 Task 2.1: widened (additive only — every existing caller above keeps using only
@@ -6097,22 +6099,15 @@ function loadActorIdentityHelper(): {
   // assignment-claim identity (a DIFFERENT identity concept from the flat actorKey used for
   // branch-naming/liveness — see resolveEnsureSessionActor's doc comment for why both exist).
   serializeActor: (actor: Partial<ActorStruct> | undefined) => string;
-  detectRuntime: (env: NodeJS.ProcessEnv) => string;
-  runtimeSessionId: (env: NodeJS.ProcessEnv) => string;
-  detectCiActor: (env: NodeJS.ProcessEnv) => { runtime: string; session_id: string } | null;
-  ancestorActorSeed: () => string;
 } {
   const _req = createRequire(import.meta.url);
   const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/actor-identity.js");
   return _req(helperPath) as {
     resolveActor: (env: NodeJS.ProcessEnv) => { actor: string; source: string };
+    resolveActorIdentity: (env: NodeJS.ProcessEnv) => { actor: string; source: string; actorStruct: ActorStruct | null };
     sanitizeSegment: (value: unknown) => string;
     isUnresolvedActor: (actor: string) => boolean;
     serializeActor: (actor: Partial<ActorStruct> | undefined) => string;
-    detectRuntime: (env: NodeJS.ProcessEnv) => string;
-    runtimeSessionId: (env: NodeJS.ProcessEnv) => string;
-    detectCiActor: (env: NodeJS.ProcessEnv) => { runtime: string; session_id: string } | null;
-    ancestorActorSeed: () => string;
   };
 }
 function resolveLivenessActor(): string {

package/src/cli/workflow.ts

@@ -15,7 +15,7 @@ import { flagBool, flagList, flagString, parseArgs } from "../lib/args.js";
 import { main as builderRun } from "./builder-run.js";
 import { currentWorkflowSessionDir, isMeaningfulTestCommand, mainFromPublicWorkflow, WORKFLOW_WRITER_CONTRACT_VERSION } from "./workflow-sidecar.js";
 import { resolveCurrentAssignmentActor, withSubjectLock } from "./assignment-provider.js";
-import { executeLoadedContinuationAdapter, loadContinuationAdapterCommand, waitForContinuationBarrier } from "./continuation-adapter.js";
+import { assertLoadedContinuationAdapterIntegrity, executeLoadedContinuationAdapter, loadContinuationAdapterCommand, waitForContinuationBarrier } from "./continuation-adapter.js";
 
 type JsonRecord = Record<string, unknown>;
 
@@ -81,16 +81,39 @@ async function drive(sessionDir: string, argv: string[], json: boolean): Promise
   const barrierWaitMs = integerFlag(parsed.flags, "barrier-wait-ms", 300_000, 0, 86_400_000);
   const barrierPollMs = integerFlag(parsed.flags, "barrier-poll-ms", 1_000, 1, 60_000);
   const { slug, projectRoot } = readBoundSession(sessionDir);
-  assertMatchingAssignmentActor(sessionDir, slug);
+  assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
   const adapterCommand = loadContinuationAdapterCommand(adapterCommandFile);
-  const result = await withContinuationDriverLock(sessionDir, async () => {
-    assertMatchingAssignmentActor(sessionDir, slug);
+  const result = await withContinuationDriverLock(sessionDir, async (lock) => {
+    assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
     return driveBuilderFlowSession({
       sessionDir,
       maxTurns,
       adapterCommandIdentity: adapterCommand.identity,
-      authorizeTurn: async () => { assertMatchingAssignmentActor(sessionDir, slug); },
-      execute: async (request) => executeLoadedContinuationAdapter(adapterCommand, request, { cwd: projectRoot, timeoutMs: turnTimeoutMs }),
+      authorizeTurn: async () => { assertOrdinaryMatchingAssignmentActor(sessionDir, slug); },
+      issueTurnAuthority: async (request) => {
+        const currentAssignment = assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
+        assertLoadedContinuationAdapterIntegrity(adapterCommand);
+        const authority = loadContinuationTurnAuthority();
+        return authority.issueActiveTurnAuthority({
+          sessionDir,
+          runId: request.run_id,
+          definitionId: request.definition_id,
+          currentStep: request.current_step,
+          iteration: request.iteration,
+          maxTurns: request.max_turns,
+          adapterCommandIdentity: adapterCommand.identity,
+          assignmentActor: currentAssignment.actorKey,
+          assignmentActorStruct: currentAssignment.actor,
+          lock,
+          timeoutMs: turnTimeoutMs,
+        });
+      },
+      execute: async (request, context) => executeLoadedContinuationAdapter(adapterCommand, request, {
+        cwd: projectRoot,
+        timeoutMs: turnTimeoutMs,
+        continuationTurnSecret: context?.continuationTurnSecret,
+        continuationRunId: context?.continuationRunId,
+      }),
       waitForBarrier: async (barrier) => waitForContinuationBarrier(barrier, { maxWaitMs: barrierWaitMs, pollMs: barrierPollMs }),
     });
   });
@@ -99,6 +122,16 @@ async function drive(sessionDir: string, argv: string[], json: boolean): Promise
   return 0;
 }
 
+function loadContinuationTurnAuthority(): {
+  issueActiveTurnAuthority(input: Record<string, unknown>): { runId: string; turnSecret: string; publicKeyDigest: string; cleanup(): boolean };
+  validateSignedActiveTurnAssignmentAuthority(input: Record<string, unknown>): { valid: boolean; record?: { assignment_actor: string; assignment_actor_struct: Record<string, unknown> } };
+} {
+  return REQUIRE(path.resolve(PACKAGE_ROOT, "scripts", "hooks", "lib", "continuation-turn-authority.js")) as {
+    issueActiveTurnAuthority(input: Record<string, unknown>): { runId: string; turnSecret: string; publicKeyDigest: string; cleanup(): boolean };
+    validateSignedActiveTurnAssignmentAuthority(input: Record<string, unknown>): { valid: boolean; record?: { assignment_actor: string; assignment_actor_struct: Record<string, unknown> } };
+  };
+}
+
 async function start(argv: string[]): Promise<number> {
   const parsed = parseArgs(argv);
   assertOnlyFlags(parsed.flags, new Set(["flow", "work-item", "task-slug", "artifact-root", "source-request", "summary", "title", "criterion", "assignment-provider", "effective-state-json"]), "workflow start");
@@ -518,15 +551,42 @@ function readAssignment(sessionDir: string, slug: string): JsonRecord {
 }
 
 function assertMatchingAssignmentActor(sessionDir: string, slug: string): ReturnType<typeof resolveCurrentAssignmentActor> {
-  const assignment = readActiveAssignment(sessionDir, slug);
-  const caller = resolveCurrentAssignmentActor();
-  const normalizeActor = (value: unknown): JsonRecord | null => value && typeof value === "object" ? { ...(value as JsonRecord), human: (value as JsonRecord).human ?? null } : null;
-  if (assignment.actor_key !== caller.actorKey || !isDeepStrictEqual(normalizeActor(assignment.actor), normalizeActor(caller.actor))) {
-    throw new Error("workflow mutation requires the session's active, matching assignment actor");
+  const { assignment, caller, matches } = assignmentActorContext(sessionDir, slug);
+  if (matches) return caller;
+
+  const authority = loadContinuationTurnAuthority().validateSignedActiveTurnAssignmentAuthority({
+    sessionDir,
+    runId: process.env.FLOW_AGENTS_CONTINUATION_RUN_ID,
+    turnSecret: process.env.FLOW_AGENTS_CONTINUATION_TURN_SECRET,
+  });
+  if (authority.valid && authority.record
+    && assignment.actor_key === authority.record.assignment_actor
+    && isDeepStrictEqual(normalizeAssignmentActor(assignment.actor), normalizeAssignmentActor(authority.record.assignment_actor_struct))) {
+    return { actorKey: authority.record.assignment_actor, actor: normalizeAssignmentActor(authority.record.assignment_actor_struct)! as ReturnType<typeof resolveCurrentAssignmentActor>["actor"] };
   }
+  throw new Error("workflow mutation requires the session's active, matching assignment actor");
+}
+
+function assertOrdinaryMatchingAssignmentActor(sessionDir: string, slug: string): ReturnType<typeof resolveCurrentAssignmentActor> {
+  const { caller, matches } = assignmentActorContext(sessionDir, slug);
+  if (!matches) throw new Error("workflow mutation requires the session's active, matching assignment actor");
   return caller;
 }
 
+function assignmentActorContext(sessionDir: string, slug: string): {
+  assignment: JsonRecord;
+  caller: ReturnType<typeof resolveCurrentAssignmentActor>;
+  matches: boolean;
+} {
+  const assignment = readActiveAssignment(sessionDir, slug);
+  const caller = resolveCurrentAssignmentActor();
+  return { assignment, caller, matches: assignment.actor_key === caller.actorKey && isDeepStrictEqual(normalizeAssignmentActor(assignment.actor), normalizeAssignmentActor(caller.actor)) };
+}
+
+function normalizeAssignmentActor(value: unknown): JsonRecord | null {
+  return value && typeof value === "object" ? { ...(value as JsonRecord), human: (value as JsonRecord).human ?? null } : null;
+}
+
 function readActiveAssignment(sessionDir: string, slug: string): JsonRecord {
   const assignment = readAssignment(sessionDir, slug);
   if (assignment.status !== "claimed" || assignment.artifact_dir !== slug || typeof assignment.actor_key !== "string" || !assignment.actor_key || !assignment.actor || typeof assignment.actor !== "object" || Array.isArray(assignment.actor)) {

package/src/continuation-driver.ts

@@ -32,6 +32,15 @@ export type ContinuationTurnResult =
   | { status: "completed"; summary?: string }
   | { status: "wait"; barrier: ContinuationBarrier; summary?: string };
 
+export class ContinuationAdapterTimeoutError extends Error {
+  readonly code = "CONTINUATION_ADAPTER_TIMEOUT";
+
+  constructor(timeoutMs: number) {
+    super(`continuation adapter timed out after ${timeoutMs}ms`);
+    this.name = "ContinuationAdapterTimeoutError";
+  }
+}
+
 export type ContinuationDriverState = {
   schema_version: "1.0";
   run_id: string;
@@ -40,13 +49,17 @@ export type ContinuationDriverState = {
   adapter_command_identity: string | null;
   status: "active" | "waiting" | "done" | "failed" | "budget_exhausted";
   turns_started: number;
+  // Added after schema 1.0 shipped. Legacy state files may omit it.
+  active_turn_step?: string | null;
+  // Anchors the ephemeral signer outside active-turn.json. Legacy state files may omit it.
+  active_turn_public_key_digest?: string | null;
   pending_barrier: ContinuationBarrier | null;
   updated_at: string;
 };
 
 export type ContinuationDriverEvent = {
   schema_version: "1.0";
-  type: "started" | "turn_started" | "turn_completed" | "turn_failed" | "parked" | "resumed" | "done" | "budget_exhausted";
+  type: "started" | "turn_started" | "turn_completed" | "gate_not_advanced" | "turn_failed" | "authority_cleanup_failed" | "parked" | "resumed" | "done" | "budget_exhausted";
   run_id: string;
   definition_id: string;
   current_step: string;
@@ -54,6 +67,7 @@ export type ContinuationDriverEvent = {
   at: string;
   barrier?: ContinuationBarrier;
   summary?: string;
+  failure_kind?: "adapter_error" | "timeout";
 };
 
 export interface ContinuationStateStore {
@@ -65,9 +79,27 @@ export interface ContinuationStateStore {
 export interface ContinuationRuntimePort {
   inspect(): Promise<ContinuationSnapshot>;
   synchronize(): Promise<ContinuationSnapshot>;
-  execute(request: ContinuationTurnRequest): Promise<ContinuationTurnResult>;
+  execute(request: ContinuationTurnRequest, context?: ContinuationTurnContext): Promise<ContinuationTurnResult>;
 }
 
+export type ContinuationTurnContext = {
+  continuationTurnSecret?: string;
+  continuationRunId?: string;
+};
+
+export type ContinuationDriverLockLease = {
+  pid: number;
+  token: string;
+  created_at: string;
+};
+
+export type ContinuationTurnAuthority = {
+  runId: string;
+  turnSecret: string;
+  publicKeyDigest: string;
+  cleanup(): boolean;
+};
+
 export type ContinuationDriverOutcome = {
   outcome: "done" | "waiting" | "failed" | "budget_exhausted";
   turns_started: number;
@@ -82,6 +114,7 @@ export interface RunContinuationDriverInput {
   store: ContinuationStateStore;
   waitForBarrier?: (barrier: ContinuationBarrier) => Promise<"ready" | "pending">;
   authorizeTurn?: () => Promise<void>;
+  issueTurnAuthority?: (request: ContinuationTurnRequest) => Promise<ContinuationTurnAuthority>;
   now?: () => Date;
 }
 
@@ -92,6 +125,7 @@ export interface DriveBuilderFlowSessionInput {
   execute: ContinuationRuntimePort["execute"];
   waitForBarrier?: RunContinuationDriverInput["waitForBarrier"];
   authorizeTurn?: RunContinuationDriverInput["authorizeTurn"];
+  issueTurnAuthority?: RunContinuationDriverInput["issueTurnAuthority"];
   now?: () => Date;
 }
 
@@ -100,6 +134,7 @@ export async function runContinuationDriver(input: RunContinuationDriverInput):
   const now = input.now ?? (() => new Date());
   const waitForBarrier = input.waitForBarrier ?? (async () => "pending" as const);
   const authorizeTurn = input.authorizeTurn ?? (async () => {});
+  const issueTurnAuthority = input.issueTurnAuthority;
   const adapterCommandIdentity = input.adapterCommandIdentity ?? null;
   let snapshot = validateSnapshot(await input.runtime.inspect());
   let state = loadOrCreateState(input.store, snapshot, input.maxTurns, adapterCommandIdentity, now);
@@ -114,10 +149,10 @@ export async function runContinuationDriver(input: RunContinuationDriverInput):
     const barrier = state.pending_barrier;
     const readiness = await waitForBarrier(barrier);
     if (readiness === "pending") {
-      state = saveState(input.store, state, { status: "waiting" }, now);
+      state = saveState(input.store, state, { status: "waiting", active_turn_step: null, active_turn_public_key_digest: null }, now);
       return { outcome: "waiting", turns_started: state.turns_started, snapshot, barrier };
     }
-    state = saveState(input.store, state, { status: "active", pending_barrier: null }, now);
+    state = saveState(input.store, state, { status: "active", active_turn_step: null, active_turn_public_key_digest: null, pending_barrier: null }, now);
     appendEvent(input.store, state, snapshot, "resumed", now, { barrier });
   }
 
@@ -127,18 +162,26 @@ export async function runContinuationDriver(input: RunContinuationDriverInput):
   if (initialOutcome === "done") return finishDone(input.store, state, snapshot, now);
   if (initialOutcome === "failed") return finishFailed(input.store, state, snapshot, now);
   if (initialOutcome === "waiting") {
-    state = saveState(input.store, state, { status: "waiting" }, now);
+    state = saveState(input.store, state, { status: "waiting", active_turn_step: null, active_turn_public_key_digest: null }, now);
     return { outcome: "waiting", turns_started: state.turns_started, snapshot };
   }
 
   while (state.turns_started < input.maxTurns) {
     await authorizeTurn();
     const iteration = state.turns_started + 1;
-    state = saveState(input.store, state, { status: "active", turns_started: iteration }, now);
+    state = saveState(input.store, state, {
+      status: "active",
+      turns_started: iteration,
+      active_turn_step: snapshot.current_step,
+      active_turn_public_key_digest: null,
+    }, now);
     appendEvent(input.store, state, snapshot, "turn_started", now);
     let result: ContinuationTurnResult;
+    let request: ContinuationTurnRequest;
+    let authority: ContinuationTurnAuthority | undefined;
+    let terminalized = false;
     try {
-      result = validateTurnResult(await input.runtime.execute(Object.freeze({
+      request = Object.freeze({
         schema_version: "1.0",
         run_id: snapshot.run_id,
         definition_id: snapshot.definition_id,
@@ -146,19 +189,53 @@ export async function runContinuationDriver(input: RunContinuationDriverInput):
         iteration,
         max_turns: input.maxTurns,
         next_action: snapshot.next_action ? structuredClone(snapshot.next_action) : null,
-      })));
+      });
+      authority = issueTurnAuthority ? await issueTurnAuthority(request) : undefined;
+      if (authority) {
+        state = saveState(input.store, state, { active_turn_public_key_digest: authority.publicKeyDigest }, now);
+      }
+      result = validateTurnResult(await input.runtime.execute(request, authority ? {
+        continuationTurnSecret: authority.turnSecret,
+        continuationRunId: authority.runId,
+      } : undefined));
     } catch (error) {
-      appendEvent(input.store, state, snapshot, "turn_failed", now, { summary: boundedErrorMessage(error) });
+      const summary = boundedErrorMessage(error);
+      appendEvent(input.store, state, snapshot, "turn_failed", now, { summary, failure_kind: error instanceof ContinuationAdapterTimeoutError ? "timeout" : "adapter_error" });
       snapshot = validateSnapshot(await input.runtime.synchronize());
       assertMissionIdentity(state, snapshot);
       const outcome = canonicalOutcome(snapshot);
-      if (outcome === "done") return finishDone(input.store, state, snapshot, now);
-      if (outcome === "failed") return finishFailed(input.store, state, snapshot, now);
+      if (outcome === "done") {
+        terminalized = true;
+        return finishDone(input.store, state, snapshot, now);
+      }
+      if (outcome === "failed") {
+        terminalized = true;
+        return finishFailed(input.store, state, snapshot, now);
+      }
       if (outcome === "waiting") {
         state = saveState(input.store, state, { status: "waiting" }, now);
         return { outcome: "waiting", turns_started: state.turns_started, snapshot };
       }
       continue;
+    } finally {
+      let cleanupFailure: string | undefined;
+      try {
+        if (authority && !authority.cleanup()) cleanupFailure = "continuation turn authority cleanup returned false";
+      } catch (error) {
+        cleanupFailure = boundedErrorMessage(error);
+      } finally {
+        if (!terminalized) state = saveState(input.store, state, {
+          active_turn_step: null,
+          active_turn_public_key_digest: null,
+        }, now);
+        if (cleanupFailure) {
+          try {
+            appendEvent(input.store, state, snapshot, "authority_cleanup_failed", now, { summary: cleanupFailure });
+          } catch {
+            // Audit is best effort. A cleanup extension must not replace the adapter outcome.
+          }
+        }
+      }
     }
     appendEvent(input.store, state, snapshot, "turn_completed", now, { summary: result.summary });
 
@@ -175,6 +252,9 @@ export async function runContinuationDriver(input: RunContinuationDriverInput):
 
     snapshot = validateSnapshot(await input.runtime.synchronize());
     assertMissionIdentity(state, snapshot);
+    if (snapshot.status === "active" && snapshot.current_step === request.current_step) {
+      appendEvent(input.store, state, snapshot, "gate_not_advanced", now, { summary: "adapter completed without canonical gate advancement" });
+    }
     const outcome = canonicalOutcome(snapshot);
     if (outcome === "done") return finishDone(input.store, state, snapshot, now);
     if (outcome === "failed") return finishFailed(input.store, state, snapshot, now);
@@ -184,7 +264,11 @@ export async function runContinuationDriver(input: RunContinuationDriverInput):
     }
   }
 
-  state = saveState(input.store, state, { status: "budget_exhausted" }, now);
+  state = saveState(input.store, state, {
+    status: "budget_exhausted",
+    active_turn_step: null,
+    active_turn_public_key_digest: null,
+  }, now);
   appendEvent(input.store, state, snapshot, "budget_exhausted", now);
   return { outcome: "budget_exhausted", turns_started: state.turns_started, snapshot };
 }
@@ -203,21 +287,23 @@ export async function driveBuilderFlowSession(input: DriveBuilderFlowSessionInpu
     store: createFileContinuationStore(sessionDir),
     ...(input.waitForBarrier ? { waitForBarrier: input.waitForBarrier } : {}),
     ...(input.authorizeTurn ? { authorizeTurn: input.authorizeTurn } : {}),
+    ...(input.issueTurnAuthority ? { issueTurnAuthority: input.issueTurnAuthority } : {}),
     ...(input.now ? { now: input.now } : {}),
   });
 }
 
-export async function withContinuationDriverLock<T>(sessionDirInput: string, body: () => Promise<T>): Promise<T> {
+export async function withContinuationDriverLock<T>(sessionDirInput: string, body: (lease: ContinuationDriverLockLease) => Promise<T>): Promise<T> {
   const sessionDir = path.resolve(sessionDirInput);
   const driverDir = path.join(sessionDir, "continuation-driver");
   const locksDir = path.join(driverDir, "locks");
   ensureSafeDirectory(sessionDir, locksDir);
   const token = randomUUID();
   const lockFile = path.join(locksDir, `${process.pid}-${token}.lock`);
-  const owner = { schema_version: "1.0" as const, pid: process.pid, token, created_at: new Date().toISOString() };
+  const lease: ContinuationDriverLockLease = { pid: process.pid, token, created_at: new Date().toISOString() };
+  const owner = { schema_version: "1.0" as const, ...lease };
   acquireDriverLock(locksDir, lockFile, owner);
   try {
-    return await body();
+    return await body(lease);
   } finally {
     releaseDriverLock(lockFile, token);
   }
@@ -362,6 +448,8 @@ function loadOrCreateState(
     adapter_command_identity: adapterCommandIdentity,
     status: "active",
     turns_started: 0,
+    active_turn_step: null,
+    active_turn_public_key_digest: null,
     pending_barrier: null,
     updated_at: now().toISOString(),
   };
@@ -375,20 +463,30 @@ function canonicalOutcome(snapshot: ContinuationSnapshot): "done" | "waiting" |
 }
 
 function finishDone(store: ContinuationStateStore, state: ContinuationDriverState, snapshot: ContinuationSnapshot, now: () => Date): ContinuationDriverOutcome {
-  const done = saveState(store, state, { status: "done", pending_barrier: null }, now);
+  const done = saveState(store, state, {
+    status: "done",
+    active_turn_step: null,
+    active_turn_public_key_digest: null,
+    pending_barrier: null,
+  }, now);
   appendEvent(store, done, snapshot, "done", now);
   return { outcome: "done", turns_started: done.turns_started, snapshot };
 }
 
 function finishFailed(store: ContinuationStateStore, state: ContinuationDriverState, snapshot: ContinuationSnapshot, now: () => Date): ContinuationDriverOutcome {
-  const failed = saveState(store, state, { status: "failed", pending_barrier: null }, now);
+  const failed = saveState(store, state, {
+    status: "failed",
+    active_turn_step: null,
+    active_turn_public_key_digest: null,
+    pending_barrier: null,
+  }, now);
   return { outcome: "failed", turns_started: failed.turns_started, snapshot };
 }
 
 function saveState(
   store: ContinuationStateStore,
   current: ContinuationDriverState,
-  patch: Partial<Pick<ContinuationDriverState, "status" | "turns_started" | "pending_barrier">>,
+  patch: Partial<Pick<ContinuationDriverState, "status" | "turns_started" | "active_turn_step" | "active_turn_public_key_digest" | "pending_barrier">>,
   now: () => Date,
 ): ContinuationDriverState {
   const next = { ...current, ...patch, updated_at: now().toISOString() };
@@ -402,7 +500,7 @@ function appendEvent(
   snapshot: ContinuationSnapshot,
   type: ContinuationDriverEvent["type"],
   now: () => Date,
-  extra: Pick<ContinuationDriverEvent, "barrier" | "summary"> = {},
+  extra: Pick<ContinuationDriverEvent, "barrier" | "summary" | "failure_kind"> = {},
 ): void {
   store.append({
     schema_version: "1.0",
@@ -414,6 +512,7 @@ function appendEvent(
     at: now().toISOString(),
     ...(extra.barrier ? { barrier: extra.barrier } : {}),
     ...(extra.summary ? { summary: extra.summary } : {}),
+    ...(extra.failure_kind ? { failure_kind: extra.failure_kind } : {}),
   });
 }
 
@@ -461,6 +560,13 @@ function validateState(state: ContinuationDriverState): void {
   }
   if (!Number.isSafeInteger(state.turns_started) || state.turns_started < 0) throw new Error("continuation driver turns_started must be a non-negative integer");
   if (state.turns_started > state.max_turns) throw new Error("continuation driver turns_started cannot exceed max_turns");
+  if (state.active_turn_step !== undefined && state.active_turn_step !== null && (typeof state.active_turn_step !== "string" || state.active_turn_step.length === 0)) {
+    throw new Error("continuation driver active_turn_step must be a non-empty string or null");
+  }
+  if (state.active_turn_public_key_digest !== undefined && state.active_turn_public_key_digest !== null
+    && (typeof state.active_turn_public_key_digest !== "string" || !/^[a-f0-9]{64}$/.test(state.active_turn_public_key_digest))) {
+    throw new Error("continuation driver active_turn_public_key_digest must be a SHA-256 hex digest or null");
+  }
   if (!new Set(["active", "waiting", "done", "failed", "budget_exhausted"]).has(state.status)) throw new Error("continuation driver state status is invalid");
   if (state.status === "budget_exhausted" && state.turns_started !== state.max_turns) {
     throw new Error("continuation driver budget_exhausted state must consume max_turns");

package/src/index.ts

@@ -46,6 +46,7 @@ export {
 export type { BuilderFlowAgentLifecycleInput, BuilderFlowAuthorizedLifecycleInput, BuilderFlowSessionInput, BuilderFlowSessionResult } from "./builder-flow-runtime.js";
 
 export {
+  ContinuationAdapterTimeoutError,
   createFileContinuationStore,
   driveBuilderFlowSession,
   runContinuationDriver,
@@ -54,11 +55,14 @@ export {
 export type {
   ContinuationBarrier,
   ContinuationDriverEvent,
+  ContinuationDriverLockLease,
   ContinuationDriverOutcome,
   ContinuationDriverState,
   ContinuationRuntimePort,
   ContinuationSnapshot,
   ContinuationStateStore,
+  ContinuationTurnAuthority,
+  ContinuationTurnContext,
   ContinuationTurnRequest,
   ContinuationTurnResult,
   DriveBuilderFlowSessionInput,