@kontourai/flow-agents 3.7.0 → 3.9.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [3.9.0](https://github.com/kontourai/flow-agents/compare/v3.8.0...v3.9.0) (2026-07-12)
+
+
+### Features
+
+* **workflow:** add bounded continuation driver ([#560](https://github.com/kontourai/flow-agents/issues/560)) ([e6365ab](https://github.com/kontourai/flow-agents/commit/e6365aba324c76ee164681c987d20916c315444e))
+
+## [3.8.0](https://github.com/kontourai/flow-agents/compare/v3.7.0...v3.8.0) (2026-07-12)
+
+
+### Features
+
+* **packaging:** install portable skills under .agents ([#551](https://github.com/kontourai/flow-agents/issues/551)) ([12f12e3](https://github.com/kontourai/flow-agents/commit/12f12e3d0a32b398e47a9ac01604179c58bf14ba))
+
+
+### Fixes
+
+* **builder:** make gate evidence sync visit-safe ([#558](https://github.com/kontourai/flow-agents/issues/558)) ([1c0e8dc](https://github.com/kontourai/flow-agents/commit/1c0e8dcea6bdfd7d54484f950b2432fcf727b0ea))
+
 ## [3.7.0](https://github.com/kontourai/flow-agents/compare/v3.6.0...v3.7.0) (2026-07-12)
 
 

package/build/src/builder-flow-runtime.js

@@ -277,9 +277,13 @@ async function syncAndProject(context, initial, sidecarSnapshot) {
         const snapshot = stageTrustBundleSnapshot(context);
         try {
             const rawBundle = JSON.parse(snapshot.raw.toString("utf8"));
-            const gateEvidence = await bundleGateEvidence(rawBundle, gates[0], run.state.subject, context.projectRoot);
+            const gateEvidence = await bundleGateEvidence(rawBundle, gates[0], run.state, run.state.subject, context.projectRoot, manifestEvidence(run.manifest));
             if (gateEvidence) {
-                const alreadyAttached = manifestEvidence(run.manifest).some((entry) => entry.gate_id === gates[0].id && entry.sha256 === snapshot.sha256);
+                const alreadyAttached = manifestEvidence(run.manifest).some((entry) => entry.gate_id === gates[0].id
+                    && entry.sha256 === snapshot.sha256
+                    && typeof entry.superseded_by !== "string"
+                    && timestampAtOrAfter(entry.attached_at, gateEvidence.visitEnteredAt)
+                    && gateEvidence.expectationIds.every((expectationId) => Array.isArray(entry.expectation_ids) && entry.expectation_ids.includes(expectationId)));
                 if (!alreadyAttached) {
                     const supersede = manifestEvidence(run.manifest)
                         .filter((entry) => entry.gate_id === gates[0].id && typeof entry.superseded_by !== "string")
@@ -294,6 +298,7 @@ async function syncAndProject(context, initial, sidecarSnapshot) {
                             ...(supersede.length > 0 ? { supersede } : {}),
                             ...(gateEvidence.failed ? { status: "failed" } : {}),
                             ...(gateEvidence.routeReason ? { routeReason: gateEvidence.routeReason } : {}),
+                            expectationIds: gateEvidence.expectationIds,
                         },
                     });
                     attached = true;
@@ -377,15 +382,67 @@ function persistedFlowId(state) {
 function openGatesForResult(run) {
     return openGates(JSON.parse(fs.readFileSync(path.join(run.dir, "definition.json"), "utf8")), run.state);
 }
-async function bundleGateEvidence(bundle, gate, subject, projectRoot) {
+async function bundleGateEvidence(bundle, gate, state, subject, projectRoot, manifest) {
     if (!isRecord(bundle) || !Array.isArray(bundle.claims))
         return null;
-    const selectors = expectationsForGate(gate).map((expectation) => expectation.bundle_claim);
+    const expectations = expectationsForGate(gate);
+    const visit = currentGateVisit(state, String(gate.step));
+    const enteredAt = visit.enteredAt;
+    const synchronizedAt = Date.now();
+    const maxClockSkewMs = 30_000;
+    const priorVisitClaimIds = new Set();
+    const priorVisitEvidenceIds = new Set();
+    for (const entry of manifest) {
+        if (entry.gate_id !== String(gate.id))
+            continue;
+        const claims = isRecord(entry.bundle) && Array.isArray(entry.bundle.claims) ? entry.bundle.claims : [];
+        for (const historical of claims) {
+            if (isRecord(historical) && typeof historical.id === "string")
+                priorVisitClaimIds.add(historical.id);
+        }
+        const evidence = isRecord(entry.bundle) && Array.isArray(entry.bundle.evidence) ? entry.bundle.evidence : [];
+        for (const historical of evidence) {
+            if (isRecord(historical) && typeof historical.id === "string")
+                priorVisitEvidenceIds.add(historical.id);
+        }
+    }
+    const claimIsCurrent = (claim) => {
+        if (typeof claim.id !== "string" || priorVisitClaimIds.has(claim.id))
+            return false;
+        const timestamps = [];
+        const createdAt = parseTimestamp(claim.createdAt);
+        if (createdAt !== null)
+            timestamps.push(createdAt);
+        if (Array.isArray(bundle.evidence))
+            for (const evidence of bundle.evidence) {
+                if (!isRecord(evidence) || evidence.claimId !== claim.id)
+                    continue;
+                if (typeof evidence.id !== "string" || priorVisitEvidenceIds.has(evidence.id))
+                    return false;
+                const observedAt = parseTimestamp(evidence.observedAt);
+                if (observedAt !== null)
+                    timestamps.push(observedAt);
+            }
+        const initialAcquisitionSkew = visit.initial && claim.claimType === "builder.pull-work.selected" ? maxClockSkewMs : 0;
+        return timestamps.some((timestamp) => timestamp >= enteredAt - initialAcquisitionSkew
+            && timestamp <= synchronizedAt + maxClockSkewMs);
+    };
     const relevant = bundle.claims.filter((claim) => {
         if (!isRecord(claim))
             return false;
-        return selectors.some((candidate) => candidate.claimType === claim.claimType
-            && (!candidate.subjectType || candidate.subjectType === claim.subjectType));
+        if (claim.producerStatus === "superseded")
+            return false;
+        const metadata = isRecord(claim.metadata) ? claim.metadata : null;
+        if (metadata && typeof metadata.superseded_by === "string")
+            return false;
+        return expectations.some((expectation) => {
+            const candidate = expectation.bundle_claim;
+            return candidate
+                && claimIsCurrent(claim)
+                &&
+                    candidate.claimType === claim.claimType
+                && (!candidate.subjectType || candidate.subjectType === claim.subjectType);
+        });
     });
     if (relevant.length === 0)
         return null;
@@ -393,6 +450,11 @@ async function bundleGateEvidence(bundle, gate, subject, projectRoot) {
         throw new BuilderBuildRunInputError("evidence.claims.metadata.workflow_subject_ref", "must match the persisted run subject");
     }
     const failed = relevant.some((claim) => claim.value === "fail" || claim.status === "disputed");
+    const expectationIds = expectations.filter((expectation) => relevant.some((claim) => {
+        const selector = expectation.bundle_claim;
+        return selector.claimType === claim.claimType && (!selector.subjectType || selector.subjectType === claim.subjectType);
+    })).map((expectation) => expectation.id);
+    const missingRequired = expectations.filter((expectation) => expectation.required && !expectationIds.includes(expectation.id));
     const routeReasons = [...new Set(relevant.flatMap((claim) => {
             const metadata = isRecord(claim.metadata) ? claim.metadata : null;
             const gateClaim = metadata && isRecord(metadata.gate_claim) ? metadata.gate_claim : null;
@@ -402,6 +464,13 @@ async function bundleGateEvidence(bundle, gate, subject, projectRoot) {
         throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", "must agree across current-gate claims");
     }
     const routeReason = routeReasons[0] ?? null;
+    if (failed && !routeReason)
+        return null;
+    // Passing evidence waits for the complete expectation set. A failing
+    // snapshot is complete only when a gate producer explicitly declares its
+    // route reason; report-only disputed critique state remains pending.
+    if (!failed && missingRequired.length > 0)
+        return null;
     if (routeReason && !failed) {
         throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", "requires failed current-gate evidence");
     }
@@ -412,7 +481,33 @@ async function bundleGateEvidence(bundle, gate, subject, projectRoot) {
     if (String(gate.id) === "verify-gate" && relevant.some((claim) => claim.claimType === "builder.verify.tests" && claim.value === "pass")) {
         await assertVerifiedTestsTrust(bundle.claims, projectRoot);
     }
-    return { failed, routeReason };
+    return { failed, routeReason, expectationIds, visitEnteredAt: enteredAt };
+}
+function currentGateVisit(state, step) {
+    let enteredAt = null;
+    for (const transition of state.transitions ?? []) {
+        if (transition.to_step !== step)
+            continue;
+        const parsed = parseTimestamp(transition.at);
+        if (parsed !== null)
+            enteredAt = parsed;
+    }
+    const initial = parseTimestamp(state.updated_at);
+    if (enteredAt !== null)
+        return { enteredAt, initial: false };
+    if (initial !== null)
+        return { enteredAt: initial, initial: true };
+    throw new BuilderBuildRunInputError("flow_run.state.updated_at", "must establish the current gate visit boundary");
+}
+function parseTimestamp(value) {
+    if (typeof value !== "string")
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function timestampAtOrAfter(value, boundary) {
+    const parsed = parseTimestamp(value);
+    return parsed !== null && parsed >= boundary;
 }
 async function assertVerifiedTestsTrust(claims, projectRoot) {
     const testClaims = claims.filter((claim) => isRecord(claim)
@@ -665,7 +760,9 @@ function projectFlowRun(context, run, sidecar) {
     const complete = run.state.status === "completed";
     const paused = run.state.status === "paused";
     const canceled = run.state.status === "canceled";
-    const action = complete || paused || canceled ? { skills: [], operations: [] } : stepAction(run.definitionId, run.state.current_step);
+    const needsDecision = run.state.status === "needs_decision";
+    const failed = run.state.status === "failed";
+    const action = complete || paused || canceled || needsDecision || failed ? { skills: [], operations: [] } : stepAction(run.definitionId, run.state.current_step);
     if (!action) {
         throw new BuilderBuildRunInputError("kit.flow_step_actions", `does not declare Builder step ${run.state.current_step}`);
     }
@@ -690,18 +787,22 @@ function projectFlowRun(context, run, sidecar) {
             ? { status: "done", summary: "Canonical Flow run was canceled by an authorized external request. Artifacts are retained until separately archived." }
             : paused
                 ? { status: "blocked", summary: "Canonical Flow run is paused. The current assignment actor may resume it with a reason." }
-                : {
-                    status: "continue",
-                    summary: `Flow step \`${run.state.current_step}\`: ${skillText}${operationText} ${gateText}${routeText} Then synchronize the recorded evidence.`,
-                    skills,
-                    operations,
-                    command: syncCommand,
-                };
+                : needsDecision
+                    ? { status: "blocked", summary: "Canonical Flow requires an external decision before continuation." }
+                    : failed
+                        ? { status: "failed", summary: "Canonical Flow run failed; no continuation turn is allowed." }
+                        : {
+                            status: "continue",
+                            summary: `Flow step \`${run.state.current_step}\`: ${skillText}${operationText} ${gateText}${routeText} Then synchronize the recorded evidence.`,
+                            skills,
+                            operations,
+                            command: syncCommand,
+                        };
     const phase = phaseForStep(definition.phase_map, run.state.current_step) ?? sidecar.phase;
     return {
         ...sidecar,
-        status: complete ? "delivered" : canceled ? "canceled" : paused ? "blocked" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
-        phase: complete || canceled ? "done" : phase,
+        status: complete ? "delivered" : canceled ? "canceled" : failed ? "failed" : (paused || needsDecision) ? "blocked" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
+        phase: complete || canceled || failed ? "done" : phase,
         updated_at: run.state.updated_at,
         flow_run: {
             run_id: run.runId,

package/build/src/cli/assignment-provider.js

@@ -626,7 +626,19 @@ export function performLocalReleaseUnderLock(artifactRoot, subjectId, releasedBy
         // seam, relocated to this write path).
         const holderActorKey = existing.actor_key || helper.serializeActor(existing.actor);
         const releasedByActorKey = opts.actorKey || helper.serializeActor(releasedBy);
-        if (holderActorKey !== releasedByActorKey) {
+        // Pre-3.7 lifecycle events could persist the derived ancestry actor before
+        // sanitizeSegment removed ':' separators. Modern explicit/env release paths
+        // always use the sanitized form. Accept only that one-way legacy migration;
+        // never normalize two modern keys or relax ownership to a prefix match.
+        const sameActorStruct = existing.actor.runtime === releasedBy.runtime
+            && existing.actor.session_id === releasedBy.session_id
+            && existing.actor.host === releasedBy.host
+            && (existing.actor.human ?? null) === (releasedBy.human ?? null);
+        const legacyActorKeyMatches = holderActorKey.includes(":")
+            && holderActorKey === helper.serializeActor(existing.actor)
+            && helper.sanitizeSegment(holderActorKey) === releasedByActorKey
+            && sameActorStruct;
+        if (holderActorKey !== releasedByActorKey && !legacyActorKeyMatches) {
             if (tolerateNoActiveClaim)
                 return null;
             throw new Error(`--actor-json does not match the current holder (${holderActorKey}); refusing to release a claim held by someone else`);

package/build/src/cli/continuation-adapter.d.ts

@@ -0,0 +1,24 @@
+import type { ContinuationBarrier, ContinuationTurnRequest, ContinuationTurnResult } from "../continuation-driver.js";
+export type ContinuationAdapterCommand = {
+    argv: string[];
+    identity: string;
+    integrity: Array<{
+        file: string;
+        sha256: string;
+    }>;
+};
+export declare function loadContinuationAdapterCommand(commandFileInput: string): ContinuationAdapterCommand;
+export declare function executeContinuationAdapter(commandFileInput: string, request: ContinuationTurnRequest, options: {
+    cwd: string;
+    timeoutMs: number;
+}): Promise<ContinuationTurnResult>;
+export declare function executeLoadedContinuationAdapter(command: ContinuationAdapterCommand, request: ContinuationTurnRequest, options: {
+    cwd: string;
+    timeoutMs: number;
+}): Promise<ContinuationTurnResult>;
+export declare function waitForContinuationBarrier(barrier: ContinuationBarrier, options: {
+    maxWaitMs: number;
+    pollMs: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<"ready" | "pending">;

package/build/src/cli/continuation-adapter.js

@@ -0,0 +1,225 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+export function loadContinuationAdapterCommand(commandFileInput) {
+    const commandFile = path.resolve(commandFileInput);
+    const command = validateAdapterCommand(JSON.parse(readRegularFileNoFollow(commandFile, "continuation adapter command file")));
+    if (!path.isAbsolute(command.argv[0]))
+        throw new Error("continuation adapter executable must be an absolute path");
+    const integrity = [...new Set(command.argv.filter((entry) => path.isAbsolute(entry) && regularFileExists(entry)))]
+        .map((file) => ({ file, sha256: sha256File(file, "continuation adapter integrity file") }));
+    if (!integrity.some((entry) => entry.file === command.argv[0]))
+        throw new Error("continuation adapter executable must be a regular file");
+    const identity = createHash("sha256").update(JSON.stringify({ ...command, integrity })).digest("hex");
+    return { ...command, identity, integrity };
+}
+export async function executeContinuationAdapter(commandFileInput, request, options) {
+    const command = loadContinuationAdapterCommand(commandFileInput);
+    return executeLoadedContinuationAdapter(command, request, options);
+}
+export async function executeLoadedContinuationAdapter(command, request, options) {
+    for (const entry of command.integrity) {
+        if (sha256File(entry.file, "continuation adapter integrity file") !== entry.sha256) {
+            throw new Error(`continuation adapter integrity changed after mission binding: ${entry.file}`);
+        }
+    }
+    assertPositiveInteger(options.timeoutMs, "continuation adapter timeoutMs", 1, 86_400_000);
+    return await spawnAdapter(command, request, options);
+}
+export async function waitForContinuationBarrier(barrier, options) {
+    assertPositiveInteger(options.maxWaitMs, "continuation barrier maxWaitMs", 0, 86_400_000);
+    assertPositiveInteger(options.pollMs, "continuation barrier pollMs", 1, 60_000);
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const stopAt = now() + options.maxWaitMs;
+    if (barrier.kind === "deadline") {
+        const deadline = Date.parse(barrier.at);
+        if (deadline <= now())
+            return "ready";
+        const waitMs = Math.min(deadline - now(), Math.max(0, stopAt - now()));
+        if (waitMs > 0)
+            await sleep(waitMs);
+        return Date.parse(barrier.at) <= now() ? "ready" : "pending";
+    }
+    while (pidAlive(barrier.pid)) {
+        const remaining = stopAt - now();
+        if (remaining <= 0)
+            return "pending";
+        await sleep(Math.min(options.pollMs, remaining));
+    }
+    return "ready";
+}
+function spawnAdapter(command, request, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command.argv[0], command.argv.slice(1), {
+            cwd: options.cwd,
+            env: process.env,
+            detached: process.platform !== "win32",
+            shell: false,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const stdout = [];
+        const stderr = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let settled = false;
+        let forcedKill;
+        let terminationError;
+        const maxBytes = 4 * 1024 * 1024;
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            terminationError = new Error(`continuation adapter timed out after ${options.timeoutMs}ms`);
+            terminateProcessGroup(child.pid, "SIGTERM");
+            forcedKill = setTimeout(() => terminateProcessGroup(child.pid, "SIGKILL"), 250);
+        }, options.timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            stdoutBytes += chunk.length;
+            if (stdoutBytes > maxBytes) {
+                if (!terminationError) {
+                    terminationError = new Error("continuation adapter stdout exceeded 4 MiB");
+                    clearTimeout(timeout);
+                    terminateProcessGroup(child.pid, "SIGTERM");
+                    forcedKill = setTimeout(() => terminateProcessGroup(child.pid, "SIGKILL"), 250);
+                }
+                return;
+            }
+            stdout.push(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderrBytes += chunk.length;
+            if (stderrBytes <= maxBytes)
+                stderr.push(chunk);
+        });
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (forcedKill)
+                clearTimeout(forcedKill);
+            reject(error);
+        });
+        child.on("close", (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (forcedKill)
+                clearTimeout(forcedKill);
+            if (terminationError) {
+                reject(terminationError);
+                return;
+            }
+            const stderrText = Buffer.concat(stderr).toString("utf8").trim();
+            if (code !== 0) {
+                scheduleProcessGroupTermination(child.pid);
+                reject(new Error(`continuation adapter exited ${code ?? signal ?? "unknown"}${stderrText ? `: ${stderrText}` : ""}`));
+                return;
+            }
+            const output = Buffer.concat(stdout).toString("utf8").trim();
+            try {
+                const result = JSON.parse(output);
+                if (!isValidWaitResult(result))
+                    scheduleProcessGroupTermination(child.pid);
+                resolve(result);
+            }
+            catch {
+                scheduleProcessGroupTermination(child.pid);
+                reject(new Error("continuation adapter must emit exactly one JSON result on stdout"));
+            }
+        });
+        child.stdin.on("error", (error) => {
+            if (error.code !== "EPIPE" && !settled) {
+                settled = true;
+                clearTimeout(timeout);
+                if (forcedKill)
+                    clearTimeout(forcedKill);
+                scheduleProcessGroupTermination(child.pid);
+                reject(error);
+            }
+        });
+        child.stdin.end(`${JSON.stringify(request)}\n`);
+    });
+}
+function validateAdapterCommand(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("continuation adapter command file must contain an object");
+    const argv = value.argv;
+    if (!Array.isArray(argv) || argv.length === 0 || argv.length > 128 || argv.some((entry) => typeof entry !== "string" || entry.length === 0 || entry.includes("\0"))) {
+        throw new Error("continuation adapter command argv must contain 1 through 128 non-empty strings");
+    }
+    return { argv: [...argv] };
+}
+function assertRegularFile(file, label) {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile())
+        throw new Error(`${label} must be a regular file`);
+}
+function readRegularFileNoFollow(file, label) {
+    return readRegularFileBufferNoFollow(file, label).toString("utf8");
+}
+function readRegularFileBufferNoFollow(file, label) {
+    assertRegularFile(file, label);
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+    try {
+        if (!fs.fstatSync(fd).isFile())
+            throw new Error(`${label} must be a regular file`);
+        return fs.readFileSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function assertPositiveInteger(value, label, min, max) {
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        throw new Error(`${label} must be an integer from ${min} through ${max}`);
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function terminateProcessGroup(pid, signal) {
+    if (!pid)
+        return;
+    try {
+        process.kill(process.platform === "win32" ? pid : -pid, signal);
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+}
+function isValidWaitResult(result) {
+    if (result?.status !== "wait" || !result.barrier || typeof result.barrier !== "object")
+        return false;
+    if (result.barrier.kind === "pid")
+        return Number.isSafeInteger(result.barrier.pid) && result.barrier.pid > 0;
+    return result.barrier.kind === "deadline" && typeof result.barrier.at === "string" && Number.isFinite(Date.parse(result.barrier.at));
+}
+function scheduleProcessGroupTermination(pid) {
+    terminateProcessGroup(pid, "SIGTERM");
+    const forcedKill = setTimeout(() => terminateProcessGroup(pid, "SIGKILL"), 250);
+    forcedKill.unref();
+}
+function regularFileExists(file) {
+    try {
+        const stat = fs.lstatSync(file);
+        return !stat.isSymbolicLink() && stat.isFile();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function sha256File(file, label) {
+    return createHash("sha256").update(readRegularFileBufferNoFollow(file, label)).digest("hex");
+}

package/build/src/cli/workflow-sidecar.js

@@ -880,7 +880,9 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
             continue;
         const subjectId = `${slug}/${check.id}`;
         const fieldOrBehavior = String(check.summary ?? check.id);
-        const claimId = generateClaimId(subjectId, "flow-agents.workflow", fieldOrBehavior);
+        const gateClaimIdentityVersion = check._gate_claim_identity_version === 2 ? 2 : 1;
+        const gateClaimRecordedAt = gateClaimIdentityVersion === 2 && typeof check._gate_claim_recorded_at === "string" ? check._gate_claim_recorded_at : null;
+        const claimId = generateClaimId(subjectId, "flow-agents.workflow", gateClaimRecordedAt ? `${fieldOrBehavior}::gate-visit::${gateClaimRecordedAt}` : fieldOrBehavior);
         const evId = `ev:${claimId}`;
         const legacyClaimType = `workflow.check.${check.kind ?? "external"}`;
         const cmd = typeof check.command === "string" ? check.command.replace(/\s+/g, " ").trim() : "";
@@ -1034,7 +1036,7 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
             // restored stamp) takes the currently-active step's id.
             const declaredStepId = gateClaimDeclaredStepId ?? (activeStep ? activeStep.stepId : null);
             const declaredMetadata = gateClaimExpectationId
-                ? { ...claimMetadata, gate_claim: { expectation_id: gateClaimExpectationId, claim_type: declared.claimType, subject_type: declared.subjectType, step_id: declaredStepId, ...(gateClaimRouteReason ? { route_reason: gateClaimRouteReason } : {}) } }
+                ? { ...claimMetadata, gate_claim: { expectation_id: gateClaimExpectationId, claim_type: declared.claimType, subject_type: declared.subjectType, step_id: declaredStepId, ...(gateClaimIdentityVersion === 2 ? { identity_version: 2 } : {}), ...(gateClaimRecordedAt ? { recorded_at: gateClaimRecordedAt } : {}), ...(gateClaimRouteReason ? { route_reason: gateClaimRouteReason } : {}) } }
                 : claimMetadata;
             const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: effectiveStatus, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, ...(declaredMetadata ? { metadata: declaredMetadata } : {}) };
             const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [evItem], events: claimEvents, policies: [declaredPolicy] });
@@ -1053,7 +1055,9 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
             continue;
         const subjectId = `${slug}/${criterion.id}`;
         const fieldOrBehavior = String(criterion.description ?? criterion.id);
-        const claimId = generateClaimId(subjectId, "flow-agents.workflow", fieldOrBehavior);
+        const criterionIdentityVersion = criterion.identity_version === 2 ? 2 : 1;
+        const criterionVerifiedAt = criterionIdentityVersion === 2 && typeof criterion.verified_at === "string" ? criterion.verified_at : null;
+        const claimId = generateClaimId(subjectId, "flow-agents.workflow", criterionVerifiedAt ? `${fieldOrBehavior}::verified::${criterionVerifiedAt}` : fieldOrBehavior);
         const legacyClaimType = "workflow.acceptance.criterion";
         const policy = ensurePolicy(legacyClaimType, "high", []);
         const evStatus = criterionStatusToEventStatus(String(criterion.status ?? ""));
@@ -1068,7 +1072,7 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         if (declared) {
             // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
             const declaredPolicy = ensurePolicy(declared.claimType, "high", []);
-            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, metadata: { origin: "acceptance", criterion: { id: criterion.id, description: criterion.description ?? criterion.id, status: criterion.status, evidence_refs: Array.isArray(criterion.evidence_refs) ? criterion.evidence_refs : [] }, ...(workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}) } };
+            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, metadata: { origin: "acceptance", criterion: { id: criterion.id, description: criterion.description ?? criterion.id, status: criterion.status, evidence_refs: Array.isArray(criterion.evidence_refs) ? criterion.evidence_refs : [], ...(criterionIdentityVersion === 2 ? { identity_version: 2 } : {}), ...(criterionVerifiedAt ? { verified_at: criterionVerifiedAt } : {}) }, ...(workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}) } };
             const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [], events: claimEvents, policies: [declaredPolicy] });
             claims.push({ ...declaredClaimObj, status: declaredStatus });
         }
@@ -1092,10 +1096,12 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         const supersededBy = typeof c.superseded_by === "string" && c.superseded_by.length > 0 ? c.superseded_by : null;
         const critiqueReviewer = String(c.reviewer ?? "tool-code-reviewer");
         const critiqueReviewedAt = String(c.reviewed_at ?? ts);
+        const critiqueIdentityVersion = c.identity_version === 2 ? 2 : 1;
         const critMeta = {
             origin: "critique",
             reviewer: critiqueReviewer,
             reviewed_at: critiqueReviewedAt,
+            ...(critiqueIdentityVersion === 2 ? { identity_version: 2 } : {}),
             findings: Array.isArray(c.findings) ? c.findings : [],
             lanes: Array.isArray(c.lanes) ? c.lanes : [],
             review_target: c.review_target && typeof c.review_target === "object" ? c.review_target : { artifacts: [] },
@@ -1107,7 +1113,9 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         // A superseded historical write gets a distinct, stable claimId so it co-exists with the live
         // claim of the same critique id (never overwrites or duplicates it). The salt is reproducible
         // across rebuilds because superseded_by + reviewed_at are preserved in metadata.
-        const claimIdSalt = supersededBy ? `${fieldOrBehavior}::superseded::${supersededBy}::${critiqueReviewedAt}` : fieldOrBehavior;
+        const claimIdSalt = critiqueIdentityVersion === 2
+            ? `${fieldOrBehavior}::reviewed::${critiqueReviewedAt}${supersededBy ? `::superseded::${supersededBy}` : ""}`
+            : (supersededBy ? `${fieldOrBehavior}::superseded::${supersededBy}::${critiqueReviewedAt}` : fieldOrBehavior);
         const claimId = generateClaimId(subjectId, "flow-agents.workflow", claimIdSalt);
         const legacyClaimType = "workflow.critique.review";
         const policy = ensurePolicy(legacyClaimType, "medium", []);
@@ -2770,7 +2778,7 @@ function requireObservedCommandRefs(refs, observedCommands, label, requireAll =
             die(`${label} requires a top-level command evidence ref for every successful observed command`);
     }
 }
-function completePassingCriteria(existing, raw, observedCommands) {
+function completePassingCriteria(existing, raw, observedCommands, verifiedAt) {
     if (raw.length === 0)
         die("record-gate-claim requires --criterion-json for a passing tests-evidence claim");
     const incoming = raw.map((value) => parseJson(value, "--criterion-json"));
@@ -2794,7 +2802,7 @@ function completePassingCriteria(existing, raw, observedCommands) {
         if (refs.length === 0)
             die(`criterion ${ids[index]} requires reviewable evidence_refs`);
         requireObservedCommandRefs(refs, observedCommands, `criterion ${ids[index]}`);
-        return { ...expectedById.get(ids[index]), status: "pass", evidence_refs: refs };
+        return { ...expectedById.get(ids[index]), status: "pass", evidence_refs: refs, identity_version: 2, verified_at: verifiedAt };
     });
 }
 const critiqueStatuses = new Set(["pass", "fail", "not_verified"]);
@@ -3234,6 +3242,10 @@ function checksFromBundle(dir) {
             check._gate_claim_declared_subject = gc.subject_type;
         if (typeof gc.step_id === "string")
             check._gate_claim_declared_step_id = gc.step_id;
+        if (typeof gc.recorded_at === "string")
+            check._gate_claim_recorded_at = gc.recorded_at;
+        if (gc.identity_version === 2)
+            check._gate_claim_identity_version = 2;
         if (typeof gc.route_reason === "string")
             check._gate_claim_route_reason = gc.route_reason;
     };
@@ -3423,6 +3435,7 @@ function critiquesFromBundle(dir) {
             review_target: md.review_target && typeof md.review_target === "object" && !Array.isArray(md.review_target) ? md.review_target : { artifacts: [] },
             reviewer: typeof md.reviewer === "string" ? md.reviewer : "tool-code-reviewer",
             reviewed_at: typeof md.reviewed_at === "string" ? md.reviewed_at : (c.updatedAt || c.createdAt || now()),
+            ...(md.identity_version === 2 ? { identity_version: 2 } : {}),
             artifact_refs: Array.isArray(md.artifact_refs) ? md.artifact_refs : [],
             ...(typeof md.superseded_by === "string" && md.superseded_by.length > 0 ? { superseded_by: md.superseded_by } : {}),
         };
@@ -3444,6 +3457,8 @@ function criteriaFromBundle(dir) {
             description: typeof saved.description === "string" ? saved.description : (claim.fieldOrBehavior || ""),
             status: typeof saved.status === "string" ? saved.status : (claim.value ?? "not_verified"),
             evidence_refs: Array.isArray(saved.evidence_refs) ? saved.evidence_refs : [],
+            ...(typeof saved.verified_at === "string" ? { verified_at: saved.verified_at } : {}),
+            ...(saved.identity_version === 2 ? { identity_version: 2 } : {}),
         };
     })
         .filter((criterion) => typeof criterion.id === "string" && criterion.id.length > 0);
@@ -3503,7 +3518,7 @@ async function recordEvidence(p) {
         die("record-evidence requires at least one --check-json or --surface-trust-json");
     validateAcceptanceEvidenceRefs(dir, p);
     // Phase 4c: bundle is the sole verification artifact — stop writing evidence.json and acceptance.json update.
-    const ts = opt(p, "timestamp", now());
+    const ts = opt(p, "timestamp", new Date().toISOString());
     // #298: readBundleState + merge-by-id instead of unconditionally replacing every prior check —
     // record-evidence previously never called checksFromBundle(dir), so it dropped every check
     // recorded by an earlier record-evidence/record-check/record-gate-claim call. A later check
@@ -3710,7 +3725,7 @@ function diagnostic(dir, code, summary) {
 async function recordGateClaim(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
     const slug = taskSlugFor(dir, opt(p, "task-slug"));
-    const ts = opt(p, "timestamp", now());
+    const ts = opt(p, "timestamp", new Date().toISOString());
     const statusVal = opt(p, "status");
     if (!["pass", "fail", "not_verified"].includes(statusVal))
         die("--status must be one of: pass, fail, not_verified");
@@ -3795,6 +3810,8 @@ async function recordGateClaim(p) {
         status: statusVal,
         summary,
         _gate_claim_expectation_id: targetExpectation.id,
+        _gate_claim_identity_version: 2,
+        _gate_claim_recorded_at: ts,
         ...(routeReason ? { _gate_claim_route_reason: routeReason } : {}),
     };
     // Include structured evidence refs if provided
@@ -3836,7 +3853,7 @@ async function recordGateClaim(p) {
     // SAME expectation id supersedes the earlier check for that expectation (mergeChecksById); a
     // gate claim against a different expectation is additive.
     const _existingState = readBundleState(dir);
-    const criteria = mustRunTests ? completePassingCriteria(_existingState.criteria, opts(p, "criterion-json"), observedCommandNames) : _existingState.criteria;
+    const criteria = mustRunTests ? completePassingCriteria(_existingState.criteria, opts(p, "criterion-json"), observedCommandNames, ts) : _existingState.criteria;
     if (mustRunTests) {
         const liveCritiques = _existingState.critiques.filter((critique) => !critique.superseded_by);
         if (liveCritiques.length === 0 || liveCritiques.some((critique) => !critiqueIsCleanAndCurrent(dir, critique))) {
@@ -4062,7 +4079,8 @@ async function recordCritique(p) {
     const critique = {
         id: critiqueId,
         reviewer: opt(p, "reviewer", "tool-code-reviewer"),
-        reviewed_at: opt(p, "timestamp", now()),
+        reviewed_at: opt(p, "timestamp", new Date().toISOString()),
+        identity_version: 2,
         verdict,
         summary,
         lanes,