@kontourai/flow-agents 3.5.0 → 3.7.0

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

@@ -7,22 +7,39 @@ import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 // ADR 0016 Abstraction A: shared FlowDefinition resolver (P-a)
-import { resolveActiveFlowStep, resolveAllFlowGateExpects, resolveFlowFilePath, resolvePhaseMap, resolveRouteBackPolicy } from "../lib/flow-resolver.js";
+import { resolveActiveFlowStep, resolveAllFlowGateExpects, resolveFlowFilePath, resolveFlowStep, resolvePhaseMap, resolveRouteBackPolicy } from "../lib/flow-resolver.js";
 import { defaultArtifactRootForRead, flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
 import { ensureSafeDirectory } from "../lib/fs.js";
-import { startBuilderFlowSession, syncBuilderFlowSessionIfPresent } from "../builder-flow-runtime.js";
+import { flowAgentsPackageRoot, flowAgentsPackageVersion } from "../lib/package-version.js";
+import { pinnedFlowAgentsCommand } from "../lib/pinned-cli-command.js";
+import { runObservedCommand } from "../lib/observed-command.js";
+import { captureReviewWorkspaceSnapshot, startBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
 // #291 Wave 1 Task 1.1 exports: ensure-session's ownership guard reuses the EXACT same
 // assignment ⋈ liveness join / claim / supersede logic #290 already ships for the
 // `assignment-provider` CLI, rather than reimplementing a second, parallel join (static ESM
 // import — same idiom already used above for ../lib/flow-resolver.js).
 import { assignmentFilePath, computeEffectiveState, performLocalClaim, performLocalSupersede, readLocalAssignmentStatus, withSubjectLock } from "./assignment-provider.js";
-export const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
+export const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "canceled", "accepted", "archived"]);
 export const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
 export const checkKinds = new Set(["build", "types", "lint", "test", "command", "security", "diff", "browser", "runtime", "policy", "external"]);
 export const checkStatuses = new Set(["pass", "fail", "not_verified", "skip"]);
 export const verdicts = new Set(["pass", "partial", "fail", "not_verified"]);
+export const WORKFLOW_WRITER_CONTRACT_VERSION = "1.0";
+const PUBLIC_WORKFLOW_AUTHORITY = Symbol("public-workflow-authority");
 function now() { return new Date().toISOString().replace(/\.\d{3}Z$/, "Z"); }
 function read(file) { return fs.readFileSync(file, "utf8"); }
+function readRegularFileNoFollow(file, label) {
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile())
+            die(`${label} must be a regular file`);
+        return fs.readFileSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 export function writeJson(file, payload) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`); }
 // Single-line but readable "key": "value" form. Built by collapsing the
 // structural whitespace from an indented stringify — corruption-proof, unlike a
@@ -44,8 +61,14 @@ function slugify(value, fallback) { return value.toLowerCase().replace(/[^a-z0-9
  * Reuses slugify() for normalization. Validates that the id is a numeric GitHub issue number. */
 function workItemSlug(ref) {
     const hashIdx = ref.indexOf("#");
-    if (hashIdx < 0 || hashIdx === ref.length - 1)
-        die("--work-item must be in owner/repo#id format");
+    if (hashIdx < 0) {
+        if (!/^[a-z][a-z0-9-]*:[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(ref) || ref.includes("..")) {
+            die("--work-item must be a provider-neutral provider:id ref or owner/repo#numeric-id");
+        }
+        return slugify(ref, "work-item");
+    }
+    if (hashIdx === ref.length - 1)
+        die("--work-item must be in owner/repo#numeric-id format");
     const repoPath = ref.slice(0, hashIdx);
     const id = ref.slice(hashIdx + 1);
     if (!/^\d+$/.test(id))
@@ -59,9 +82,12 @@ function workItemSlug(ref) {
 function assignmentSubjectMatchesWorkItem(slug, ref) {
     if (ref === `local:${slug}`)
         return true;
-    if (!/^[^/#]+\/[^/#]+#\d+$/.test(ref))
+    try {
+        return workItemSlug(ref) === slug;
+    }
+    catch {
         return false;
-    return workItemSlug(ref) === slug;
+    }
 }
 function sessionWorkItem(p, slug, dir) {
     const providerRef = opt(p, "work-item");
@@ -584,10 +610,10 @@ export function reduceCaptureLogByCommand(commandLog) {
  * @param timestamp  ISO-8601 timestamp for createdAt / updatedAt / observedAt
  * @param checks     Normalized check objects (from record-evidence --check-json / --surface-trust-json)
  * @param criteria   Acceptance criteria objects (from acceptance.json .criteria array)
- * @param critiques  Critique objects (from critique.json .critiques array)
+ * @param critiques  Critique objects reconstructed from trust.bundle claims
  * @param commandLog Optional parsed command-log.jsonl entries (capture-authoritative fold)
  */
-export async function buildTrustBundle(slug, timestamp, checks, criteria, critiques, commandLog, flowAgentsDir, actorKey) {
+export async function buildTrustBundle(slug, timestamp, checks, criteria, critiques, commandLog, flowAgentsDir, actorKey, exactFlowContext) {
     const surface = await tryLoadSurface();
     if (!surface)
         return null;
@@ -600,7 +626,10 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
     // #291 Wave 2 Task 2.1 (§7)/Task 2.2: actorKey (when the caller already resolved one — see
     // writeTrustBundle below) threads through to resolveActiveFlowStep's per-actor-first,
     // legacy-fallback current.json read; omitted, this is IDENTICAL to pre-#291 behavior.
-    const activeStep = flowAgentsDir ? resolveActiveFlowStep(flowAgentsDir, actorKey) : null;
+    const exactRepoRoot = flowAgentsDir ? findRepoRootFromDir(path.dirname(flowAgentsDir)) : null;
+    const activeStep = exactFlowContext && exactRepoRoot
+        ? resolveFlowStep(exactFlowContext.flowId, exactFlowContext.stepId, exactRepoRoot)
+        : flowAgentsDir ? resolveActiveFlowStep(flowAgentsDir, actorKey) : null;
     // #270 CRITICAL/HIGH fix: resolve the session's active_flow_id independent of whether the
     // CURRENTLY-active step resolves — a stamped gate claim names the STEP IT WAS ORIGINALLY
     // RECORDED AT (frozen in metadata.gate_claim.step_id), which is routinely a DIFFERENT step than
@@ -609,6 +638,8 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
     // the gate claim was recorded at — the validation must be against the FULL flow definition
     // (every step's gate expects[], via resolveAllFlowGateExpects), not just the active one.
     const sessionFlowId = (() => {
+        if (exactFlowContext)
+            return exactFlowContext.flowId;
         if (!flowAgentsDir)
             return null;
         try {
@@ -899,6 +930,11 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         const outputDigestMeta = typeof check._output_sha256 === "string" && check._output_sha256.length > 0
             ? { algorithm: "sha256", hex: check._output_sha256 }
             : null;
+        const observedCommandsMeta = Array.isArray(check._observed_commands)
+            ? check._observed_commands
+                .filter((entry) => typeof entry?.command === "string" && typeof entry?.exit_code === "number" && typeof entry?.output_sha256 === "string")
+                .map((entry) => ({ command: entry.command, exit_code: entry.exit_code, output_sha256: entry.output_sha256, ...(Number.isSafeInteger(entry.test_count) ? { test_count: entry.test_count } : {}), ...(entry.execution_proof && typeof entry.execution_proof === "object" ? { execution_proof: entry.execution_proof } : {}) }))
+            : null;
         // #270(a)/(c): a gate claim's declared claimType/subjectType, once resolved (either freshly
         // via matchExpectsEntry below, or restored from a prior write's metadata.gate_claim stamp by
         // checksFromBundle), is stamped here so it is frozen at record time — a later bundle rebuild
@@ -928,11 +964,15 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
             origin: "check",
             check_kind: String(check.kind ?? "external"),
             ...(activeStep && workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}),
+            ...(typeof check._producer === "string" ? { expected_producer: check._producer } : {}),
+            ...(typeof check._recorded_by === "string" ? { recorded_by: check._recorded_by } : {}),
+            ...(Array.isArray(check._producer_self_produced_trust_slices) ? { self_produced_trust_slices: check._producer_self_produced_trust_slices } : {}),
             ...(waiver ? { waiver } : {}),
             ...(promotionMeta ? { promotion: promotionMeta } : {}),
             ...(artifactRefsMeta ? { artifact_refs: artifactRefsMeta } : {}),
             ...(standardRefsMeta ? { standard_refs: standardRefsMeta } : {}),
             ...(outputDigestMeta ? { output_digest: outputDigestMeta } : {}),
+            ...(observedCommandsMeta && observedCommandsMeta.length > 0 ? { observed_commands: observedCommandsMeta } : {}),
         };
         const claimEvents = [];
         if (evStatus) {
@@ -1028,13 +1068,13 @@ 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", ...(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 : [] }, ...(workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}) } };
             const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [], events: claimEvents, policies: [declaredPolicy] });
             claims.push({ ...declaredClaimObj, status: declaredStatus });
         }
         else {
             // No active flow step — only the workflow.* primary claim (legitimate no-flow fallback path).
-            const claimObj = { id: claimId, subjectType: "workflow-acceptance-criterion", subjectId, facet: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: policy.id, metadata: { origin: "acceptance" } };
+            const claimObj = { id: claimId, subjectType: "workflow-acceptance-criterion", subjectId, facet: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: policy.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 : [] } } };
             const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [], events: claimEvents, policies: [policy] });
             claims.push({ ...claimObj, status: derivedStatus });
         }
@@ -1052,7 +1092,18 @@ 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 critMeta = { origin: "critique", reviewer: critiqueReviewer, reviewed_at: critiqueReviewedAt, ...(activeStep && workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}), ...(supersededBy ? { superseded_by: supersededBy } : {}) };
+        const critMeta = {
+            origin: "critique",
+            reviewer: critiqueReviewer,
+            reviewed_at: critiqueReviewedAt,
+            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: [] },
+            // Keep the legacy field for consumers that still render a flat artifact list.
+            artifact_refs: Array.isArray(c.artifact_refs) ? c.artifact_refs : [],
+            ...(activeStep && workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}),
+            ...(supersededBy ? { superseded_by: supersededBy } : {}),
+        };
         // 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.
@@ -1068,18 +1119,15 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
             events.push(evt);
             claimEvents.push(evt);
         }
-        // P-d: declared-only when active flow/step present (shadow retired); no-flow path unchanged.
-        const declared = matchExpectsEntry("critique");
-        const claimType = declared ? declared.claimType : legacyClaimType;
-        const subjectType = declared ? declared.subjectType : "workflow-critique";
-        const claimPolicy = declared ? ensurePolicy(declared.claimType, "medium", []) : policy;
-        const claimObj = { id: claimId, subjectType, subjectId, facet: "flow-agents.workflow", claimType, fieldOrBehavior, value: c.verdict, createdAt: ts, updatedAt: ts, impactLevel: "medium", verificationPolicyId: claimPolicy.id, metadata: critMeta };
+        // Critique is intentionally report-only. It must never inherit a Flow gate expectation,
+        // even while a run is positioned at a gate-bearing step.
+        const claimObj = { id: claimId, subjectType: "workflow-critique", subjectId, facet: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: c.verdict, createdAt: ts, updatedAt: ts, impactLevel: "medium", verificationPolicyId: policy.id, metadata: critMeta };
         if (supersededBy) {
             // History: status is "superseded" directly (no verification event); excluded from evaluation.
             claims.push({ ...claimObj, status: "superseded" });
         }
         else {
-            const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [], events: claimEvents, policies: [claimPolicy] });
+            const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [], events: claimEvents, policies: [policy] });
             claims.push({ ...claimObj, status: derivedStatus });
         }
     }
@@ -1105,7 +1153,7 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
  * @param criteria   Acceptance criteria objects (same as buildTrustBundle)
  * @param critiques  Critique objects (same as buildTrustBundle)
  */
-export async function writeTrustBundle(dir, slug, timestamp, checks, criteria, critiques, actorKey) {
+export async function writeTrustBundle(dir, slug, timestamp, checks, criteria, critiques, actorKey, exactFlowContext) {
     try {
         // Fold the deterministic capture log (PostToolUse evidence-capture) into the
         // bundle so capture is authoritative over claimed status. Best-effort read.
@@ -1131,15 +1179,22 @@ export async function writeTrustBundle(dir, slug, timestamp, checks, criteria, c
         const _flowAgentsDir = path.dirname(dir);
         const _effectiveActorKey = actorKey ?? loadActorIdentityHelper().resolveActor(process.env).actor;
         let _scopedFlowAgentsDir = undefined;
-        try {
-            const _currentRaw = loadCurrentPointerHelper().readCurrentPointer(_flowAgentsDir, _effectiveActorKey).payload;
-            const _artDir = _currentRaw && typeof _currentRaw["artifact_dir"] === "string" ? _currentRaw["artifact_dir"] : null;
-            if (_artDir && path.resolve(_flowAgentsDir, _artDir) === path.resolve(dir)) {
-                _scopedFlowAgentsDir = _flowAgentsDir;
+        if (exactFlowContext) {
+            // The context was read from this session's persisted flow_run. Navigation pointers may
+            // lag or point at another run and must not override an explicit session mutation.
+            _scopedFlowAgentsDir = _flowAgentsDir;
+        }
+        else {
+            try {
+                const _currentRaw = loadCurrentPointerHelper().readCurrentPointer(_flowAgentsDir, _effectiveActorKey).payload;
+                const _artDir = _currentRaw && typeof _currentRaw["artifact_dir"] === "string" ? _currentRaw["artifact_dir"] : null;
+                if (_artDir && path.resolve(_flowAgentsDir, _artDir) === path.resolve(dir)) {
+                    _scopedFlowAgentsDir = _flowAgentsDir;
+                }
             }
+            catch { /* current.json absent or unreadable — no scoping */ }
         }
-        catch { /* current.json absent or unreadable — no scoping */ }
-        const bundle = await buildTrustBundle(slug, timestamp, checks, criteria, critiques, commandLog, _scopedFlowAgentsDir, _effectiveActorKey);
+        const bundle = await buildTrustBundle(slug, timestamp, checks, criteria, critiques, commandLog, _scopedFlowAgentsDir, _effectiveActorKey, exactFlowContext);
         if (!bundle)
             return { written: false, errors: [] }; // Surface unavailable — fail-open, skip write
         const result = await validateTrustBundle(bundle);
@@ -1148,7 +1203,6 @@ export async function writeTrustBundle(dir, slug, timestamp, checks, criteria, c
             return { written: false, errors: result.errors };
         }
         writeJson(path.join(dir, "trust.bundle"), bundle);
-        await syncBuilderFlowSessionIfPresent(dir);
         return { written: true, errors: [] };
     }
     catch (err) {
@@ -1681,6 +1735,10 @@ function currentDir(root, actorKey) {
     }
     return dir;
 }
+export function currentWorkflowSessionDir(root) {
+    const resolved = loadActorIdentityHelper().resolveActor(process.env);
+    return currentDir(path.resolve(root), loadActorIdentityHelper().isUnresolvedActor(resolved.actor) ? undefined : resolved.actor);
+}
 /**
  * #291 Wave 2 Task 2.1 (§6): updates BOTH the legacy current.json (when IT points at `dir` — the
  * exact, unchanged existing check/write) AND the resolved actor's own per-actor current.json
@@ -1754,6 +1812,9 @@ function initSidecars(dir, slug, sourceRequest, summary, nextAction, timestamp,
         ...sidecarBase(slug), status: initialLifecycle?.status ?? "planned", phase: initialLifecycle?.phase ?? "planning", created_at: existingState.created_at || timestamp, updated_at: timestamp,
         ...(branch ? { branch } : {}),
         ...(retainedWorkItemRefs.length > 0 ? { work_item_refs: retainedWorkItemRefs } : {}),
+        ...(existingState.flow_run && typeof existingState.flow_run === "object" && !Array.isArray(existingState.flow_run)
+            ? { flow_run: existingState.flow_run }
+            : {}),
         artifact_paths: relArtifacts(dir),
         next_action: nextActionPayload,
     });
@@ -1830,14 +1891,40 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution, workItemR
     const nowMs = opt(p, "now") ? Date.parse(opt(p, "now")) : Date.now();
     const assignmentProviderKind = opt(p, "assignment-provider", "local-file");
     let effective;
+    let providerEvidenceBytes;
     const effectiveStateJsonFlag = opt(p, "effective-state-json");
     if (effectiveStateJsonFlag) {
-        const parsed = loadJsonInputFile(effectiveStateJsonFlag);
+        providerEvidenceBytes = effectiveStateJsonFlag === "-"
+            ? fs.readFileSync(0)
+            : readRegularFileNoFollow(path.resolve(effectiveStateJsonFlag), "ensure-session --effective-state-json");
+        const parsed = JSON.parse(providerEvidenceBytes.toString("utf8"));
         const candidate = parsed && typeof parsed === "object" ? parsed.effective : undefined;
+        const assignment = parsed && typeof parsed === "object" ? parsed.assignment : undefined;
+        const record = assignment && typeof assignment.record === "object" && assignment.record !== null ? assignment.record : undefined;
         const validStates = new Set(["held", "reclaimable", "human-held", "free"]);
         if (!candidate || typeof candidate.effective_state !== "string" || !validStates.has(candidate.effective_state)) {
             die(`ensure-session --effective-state-json must contain an .effective object with a recognized effective_state (held|reclaimable|human-held|free); got ${JSON.stringify(candidate ? candidate.effective_state : candidate)}`);
         }
+        if (workItemRef && (parsed.role !== "AssignmentStatus"
+            || parsed.provider !== assignmentProviderKind
+            || assignment?.provider !== assignmentProviderKind
+            || assignment?.subject_id !== slug
+            || record?.role !== "AssignmentClaimRecord"
+            || record?.status !== "claimed"
+            || record?.subject_id !== slug
+            || record?.work_item_ref !== workItemRef
+            || record?.actor_key !== resolution.branchActorKey
+            || assignment?.assignee !== resolution.branchActorKey
+            || !record.actor || typeof record.actor !== "object"
+            || record.actor.runtime !== resolution.actorStruct.runtime
+            || record.actor.session_id !== resolution.actorStruct.session_id
+            || record.actor.host !== resolution.actorStruct.host
+            || (record.actor.human ?? null) !== (resolution.actorStruct.human ?? null)
+            || candidate.effective_state !== "held"
+            || candidate.reason !== "self_is_holder"
+            || candidate.holder?.actor !== resolution.branchActorKey)) {
+            die("ensure-session --effective-state-json must be the configured provider's AssignmentStatus for this Work Item, with a claimed record and self_is_holder actor matching the current runtime");
+        }
         effective = candidate;
     }
     else if (assignmentProviderKind === "local-file") {
@@ -1875,9 +1962,7 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution, workItemR
         return null;
     }
     const selectedWorkEvidence = () => {
-        // Only a claim read from the local provider is durable evidence. Precomputed provider state
-        // can authorize entry, but it cannot prove that this process acquired the Work Item.
-        if (!workItemRef || effectiveStateJsonFlag || assignmentProviderKind !== "local-file")
+        if (!workItemRef)
             return null;
         const assignment = readLocalAssignmentStatus(root, slug);
         const record = assignment.record;
@@ -1891,6 +1976,8 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution, workItemR
         return {
             assignmentFile: assignmentFilePath(root, slug),
             actorKey: resolution.branchActorKey,
+            ...(effectiveStateJsonFlag ? { providerEvidenceFile: path.resolve(effectiveStateJsonFlag) } : {}),
+            ...(providerEvidenceBytes ? { providerEvidenceBytes } : {}),
         };
     };
     const resolveBranchForClaim = () => {
@@ -1904,8 +1991,22 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution, workItemR
             // ActorStruct triple), so this redundant belt-and-suspenders check agrees with the
             // effective_state computation instead of silently using a different identity.
             const isSelf = effective.reason === "self_is_holder" || (!!effective.holder?.actor && effective.holder.actor === resolution.branchActorKey);
-            if (isSelf)
+            if (isSelf) {
+                if (assignmentProviderKind !== "local-file") {
+                    const local = readLocalAssignmentStatus(root, slug).record;
+                    if (!local || local.status !== "claimed") {
+                        performLocalClaim(root, slug, resolution.actorStruct, {
+                            ttlSeconds: opt(p, "claim-ttl-seconds") ? Number(opt(p, "claim-ttl-seconds")) : loadLivenessPolicyHelper().resolveTtlSeconds(process.env),
+                            branch: resolveBranchForClaim(),
+                            artifactDir: path.relative(root, dir) || ".",
+                            reason: `provider-confirmed ${assignmentProviderKind} ownership mirror`,
+                            actorKey: resolution.branchActorKey,
+                            ...(workItemRef ? { workItemRef } : {}),
+                        });
+                    }
+                }
                 return selectedWorkEvidence();
+            }
             const holderActor = sanitize(effective.holder?.actor ?? "unknown");
             const lastAtSuffix = effective.holder?.last_at ? ` (last_at ${sanitize(effective.holder.last_at)})` : "";
             die(`ensure-session refused: subject ${sanitize(slug)} is currently held by a different, still-live actor (${holderActor}${lastAtSuffix}). Pick a different work item, or confirm the holder session is truly gone before considering a takeover.`);
@@ -1957,6 +2058,9 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution, workItemR
             return selectedWorkEvidence();
         }
         case "free": {
+            if (assignmentProviderKind !== "local-file") {
+                die(`ensure-session refused: provider ${JSON.stringify(assignmentProviderKind)} has not confirmed this actor as the Work Item holder`);
+            }
             performLocalClaim(root, slug, resolution.actorStruct, {
                 ttlSeconds: opt(p, "claim-ttl-seconds") ? Number(opt(p, "claim-ttl-seconds")) : loadLivenessPolicyHelper().resolveTtlSeconds(process.env),
                 branch: resolveBranchForClaim(),
@@ -2008,11 +2112,11 @@ function resolveEnsureSessionEntry(p, dir) {
     }
     return { flowId, stepId: explicitStep || firstStep, firstStep };
 }
-function assertCanonicalBuilderArtifactRoot(root) {
+function assertCanonicalBuilderArtifactRoot(root, flowId) {
     const kontouraiRoot = path.dirname(root);
     const projectRoot = path.dirname(kontouraiRoot);
     if (path.basename(root) !== "flow-agents" || path.basename(kontouraiRoot) !== ".kontourai") {
-        die("ensure-session --flow-id builder.build requires --artifact-root <project>/.kontourai/flow-agents");
+        die(`ensure-session --flow-id ${flowId} requires --artifact-root <project>/.kontourai/flow-agents`);
     }
     const statIfPresent = (candidate) => {
         try {
@@ -2026,7 +2130,7 @@ function assertCanonicalBuilderArtifactRoot(root) {
     };
     const projectStat = statIfPresent(projectRoot);
     if (projectStat && (projectStat.isSymbolicLink() || !projectStat.isDirectory())) {
-        die(`ensure-session --flow-id builder.build requires a non-symlink project root: ${projectRoot}`);
+        die(`ensure-session --flow-id ${flowId} requires a non-symlink project root: ${projectRoot}`);
     }
     const realProjectRoot = projectStat ? fs.realpathSync(projectRoot) : projectRoot;
     for (const [candidate, expected, label] of [
@@ -2037,7 +2141,7 @@ function assertCanonicalBuilderArtifactRoot(root) {
         if (!stat)
             continue;
         if (stat.isSymbolicLink() || !stat.isDirectory() || fs.realpathSync(candidate) !== expected) {
-            die(`ensure-session --flow-id builder.build requires a non-symlink ${label}: ${candidate}`);
+            die(`ensure-session --flow-id ${flowId} requires a non-symlink ${label}: ${candidate}`);
         }
     }
 }
@@ -2047,18 +2151,18 @@ function preflightEnsureSession(p) {
     const dir = sessionDirFor(root, slug);
     assertSafeSessionDirectory(root, dir);
     const entry = resolveEnsureSessionEntry(p, dir);
-    if (entry.flowId === "builder.build")
-        assertCanonicalBuilderArtifactRoot(root);
+    if (entry.flowId === "builder.build" || entry.flowId === "builder.shape")
+        assertCanonicalBuilderArtifactRoot(root, entry.flowId);
     sessionWorkItem(p, slug, dir);
 }
-async function ensureSession(p) {
+async function ensureSession(p, allowCanonicalFlowMutation) {
     const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : flowAgentsArtifactRoot();
     const slug = opt(p, "task-slug") || (opt(p, "work-item") ? workItemSlug(opt(p, "work-item")) : die("--task-slug is required (or pass --work-item to derive it)"));
     const dir = sessionDirFor(root, slug);
     assertSafeSessionDirectory(root, dir);
     const entry = resolveEnsureSessionEntry(p, dir);
-    if (entry.flowId === "builder.build")
-        assertCanonicalBuilderArtifactRoot(root);
+    if (entry.flowId === "builder.build" || entry.flowId === "builder.shape")
+        assertCanonicalBuilderArtifactRoot(root, entry.flowId);
     const workItem = sessionWorkItem(p, slug, dir);
     // #291 Wave 2 Task 2.1 (§3, §4): resolve the actor ONCE, then run the ownership guard BEFORE
     // any directory/file is created — a refusal must never leave a stray empty session dir. Reused
@@ -2068,8 +2172,20 @@ async function ensureSession(p) {
     const selectionWorkItemRef = entry.flowId === "builder.build" && assignmentSubjectMatchesWorkItem(slug, workItem.ref)
         ? workItem.ref
         : undefined;
-    const selectedWorkEvidence = enforceEnsureSessionOwnership(p, root, slug, dir, actorResolution, selectionWorkItemRef);
+    let selectedWorkEvidence = enforceEnsureSessionOwnership(p, root, slug, dir, actorResolution, selectionWorkItemRef);
     ensureSafeDirectory(root, dir);
+    if (selectedWorkEvidence?.providerEvidenceBytes) {
+        const staged = path.join(dir, "assignment-provider-state.json");
+        if (fs.existsSync(staged)) {
+            if (!readRegularFileNoFollow(staged, "ensure-session provider state evidence destination").equals(selectedWorkEvidence.providerEvidenceBytes))
+                die("ensure-session provider state evidence conflicts with the existing immutable snapshot");
+        }
+        else {
+            fs.writeFileSync(staged, selectedWorkEvidence.providerEvidenceBytes, { flag: "wx", mode: 0o600 });
+        }
+        fs.chmodSync(staged, 0o400);
+        selectedWorkEvidence = { ...selectedWorkEvidence, providerEvidenceFile: staged };
+    }
     const timestamp = opt(p, "timestamp", now());
     if (workItem.localRecord && !fs.existsSync(path.join(dir, "work-item.json"))) {
         writeJson(path.join(dir, "work-item.json"), workItem.localRecord);
@@ -2082,13 +2198,27 @@ async function ensureSession(p) {
         // takeover continuity true by construction (see Design Decision 3 in the plan).
         const branch = resolveSessionBranch(p, slug);
         const initialMarkdownStatus = entry.flowId ? "new" : "planning";
-        md = `# ${opt(p, "title", slug)}\n\nbranch: ${branch}\nworktree: main\ncreated: ${timestamp}\nstatus: ${initialMarkdownStatus}\ntype: deliver\niteration: 1\n\n## Plan\n\n${opt(p, "summary", "")}\n\n## Definition Of Done\n\n- **User outcome:** ${opt(p, "summary", "Workflow session is durable.")}\n- **Scope:** Workflow session artifacts and sidecars.\n- **Acceptance criteria:**\n${opts(p, "criterion").map((c) => `  - [ ] ${c} - Evidence: pending.`).join("\n")}\n- **Usefulness checks:**\n  - [ ] User-facing workflow is documented or discoverable\n- **Stop-short risks:** Workflow artifacts could drift.\n- **Durable docs target:** not needed\n- **Sandbox mode:** local-edit\n\n## Execution Progress\n\n- [ ] Session initialized.\n\n## Verification Report\n\nBuild: [NOT_VERIFIED] Verification has not run yet.\n\n### Acceptance Criteria\n- [NOT_VERIFIED] Verification has not run yet - Evidence: pending workflow execution and checks.\n\n### Verdict: NOT_VERIFIED\n\n## Goal Fit Gate\n\n- [ ] Original user goal restated\n\n## Final Acceptance\n\n- [ ] CI/relevant checks passed or local equivalent recorded\n`;
+        const acceptanceCriteria = opts(p, "criterion");
+        if (acceptanceCriteria.length === 0)
+            acceptanceCriteria.push(`Complete the requested outcome: ${opt(p, "summary", "Workflow session is durable.")}`);
+        md = `# ${opt(p, "title", slug)}\n\nbranch: ${branch}\nworktree: main\ncreated: ${timestamp}\nstatus: ${initialMarkdownStatus}\ntype: deliver\niteration: 1\n\n## Plan\n\n${opt(p, "summary", "")}\n\n## Definition Of Done\n\n- **User outcome:** ${opt(p, "summary", "Workflow session is durable.")}\n- **Scope:** Workflow session artifacts and sidecars.\n- **Acceptance criteria:**\n${acceptanceCriteria.map((c) => `  - [ ] ${c} - Evidence: pending.`).join("\n")}\n- **Usefulness checks:**\n  - [ ] User-facing workflow is documented or discoverable\n- **Stop-short risks:** Workflow artifacts could drift.\n- **Durable docs target:** not needed\n- **Sandbox mode:** local-edit\n\n## Execution Progress\n\n- [ ] Session initialized.\n\n## Verification Report\n\nBuild: [NOT_VERIFIED] Verification has not run yet.\n\n### Acceptance Criteria\n- [NOT_VERIFIED] Verification has not run yet - Evidence: pending workflow execution and checks.\n\n### Verdict: NOT_VERIFIED\n\n## Goal Fit Gate\n\n- [ ] Original user goal restated\n\n## Final Acceptance\n\n- [ ] CI/relevant checks passed or local equivalent recorded\n`;
         fs.writeFileSync(path.join(dir, `${slug}--deliver.md`), md);
     }
     if (!fs.existsSync(path.join(dir, "state.json")) || !fs.existsSync(path.join(dir, "acceptance.json")) || !fs.existsSync(path.join(dir, "handoff.json"))) {
         const phaseMap = entry.flowId ? resolvePhaseMap(entry.flowId, findRepoRootFromDir(dir)) : null;
         const initialPhase = Object.entries(phaseMap ?? {}).find(([, step]) => step === entry.firstStep)?.[0];
-        const startCommand = `flow-agents builder-run start --session-dir .kontourai/flow-agents/${slug}`;
+        const startCommand = pinnedFlowAgentsCommand(flowAgentsPackageVersion(), [
+            "workflow", "start",
+            "--flow", entry.flowId,
+            ...(entry.flowId === "builder.shape" ? [] : ["--work-item", workItem.ref]),
+            ...(workItem.ref === `local:${slug}` ? ["--task-slug", slug] : []),
+            "--assignment-provider", opt(p, "assignment-provider", "local-file"),
+            ...(selectedWorkEvidence?.providerEvidenceFile ? ["--effective-state-json", selectedWorkEvidence.providerEvidenceFile] : []),
+            "--artifact-root", root,
+            "--title", opt(p, "title", slug),
+            "--summary", opt(p, "summary", "Workflow session is durable."),
+            ...opts(p, "criterion").flatMap((criterion) => ["--criterion", criterion]),
+        ]);
         const nextAction = entry.flowId
             ? entry.flowId === "builder.build"
                 ? {
@@ -2116,9 +2246,9 @@ async function ensureSession(p) {
         ? persistedCurrent.active_step_id
         : entry.stepId;
     writeCurrent(root, dir, timestamp, "workflow-sidecar", "ensure-session", entry.flowId || undefined, resumedStep || undefined, actorResolution.unresolved ? undefined : actorResolution.branchActorKey);
-    if (entry.flowId === "builder.build") {
+    if (allowCanonicalFlowMutation && (entry.flowId === "builder.build" || entry.flowId === "builder.shape")) {
         try {
-            const started = await startBuilderFlowSession({ sessionDir: dir });
+            const started = await startBuilderFlowSession({ sessionDir: dir, flowId: entry.flowId });
             if (started.run.state.current_step === "pull-work"
                 && selectedWorkEvidence
                 && assignmentSubjectMatchesWorkItem(slug, workItem.ref)) {
@@ -2133,8 +2263,25 @@ async function ensureSession(p) {
                     }
                     const assignmentContent = fs.readFileSync(selectedWorkEvidence.assignmentFile);
                     const assignmentDigest = createHash("sha256").update(assignmentContent).digest("hex");
+                    const providerEvidenceBytes = selectedWorkEvidence.providerEvidenceFile
+                        ? readRegularFileNoFollow(selectedWorkEvidence.providerEvidenceFile, "selected-work provider evidence")
+                        : null;
+                    if (providerEvidenceBytes && selectedWorkEvidence.providerEvidenceBytes && !providerEvidenceBytes.equals(selectedWorkEvidence.providerEvidenceBytes)) {
+                        die("ensure-session refused to emit selected-work evidence: provider evidence changed after ownership validation");
+                    }
+                    const providerEvidenceDigest = providerEvidenceBytes ? createHash("sha256").update(providerEvidenceBytes).digest("hex") : null;
                     const projectRoot = path.dirname(path.dirname(root));
                     const evidenceFile = path.relative(projectRoot, selectedWorkEvidence.assignmentFile);
+                    const pullWorkReport = path.join(dir, `${slug}--pull-work.md`);
+                    let reportIsValid = false;
+                    try {
+                        const reportStat = fs.lstatSync(pullWorkReport);
+                        reportIsValid = !reportStat.isSymbolicLink() && reportStat.isFile() && fs.readFileSync(pullWorkReport, "utf8").includes(workItem.ref);
+                    }
+                    catch { /* handled by the stable contract error below */ }
+                    if (!reportIsValid) {
+                        die(`ensure-session refused to emit selected-work evidence: expected concrete pull-work selection report ${pullWorkReport} naming ${JSON.stringify(workItem.ref)}`);
+                    }
                     await recordGateClaim(parseArgs([
                         "record-gate-claim",
                         dir,
@@ -2147,8 +2294,25 @@ async function ensureSession(p) {
                             file: evidenceFile,
                             summary: `Durable local assignment record for the selected Work Item and active actor; sha256:${assignmentDigest}.`,
                         }),
+                        ...(selectedWorkEvidence.providerEvidenceFile ? [
+                            "--evidence-ref-json", JSON.stringify({
+                                kind: "artifact",
+                                file: path.relative(projectRoot, selectedWorkEvidence.providerEvidenceFile),
+                                summary: `Provider assignment state confirming ownership before the local runtime lease was mirrored; sha256:${providerEvidenceDigest}.`,
+                            }),
+                        ] : []),
+                        "--evidence-ref-json", JSON.stringify({
+                            kind: "artifact",
+                            file: path.relative(projectRoot, pullWorkReport),
+                            summary: `Concrete pull-work selection report for ${workItem.ref}.`,
+                        }),
                         "--timestamp", timestamp,
                     ]));
+                    if (selectedWorkEvidence.providerEvidenceFile && selectedWorkEvidence.providerEvidenceBytes
+                        && !readRegularFileNoFollow(selectedWorkEvidence.providerEvidenceFile, "selected-work provider evidence").equals(selectedWorkEvidence.providerEvidenceBytes)) {
+                        die("ensure-session refused to synchronize selected-work evidence: provider evidence changed during claim recording");
+                    }
+                    await syncBuilderFlowSession({ sessionDir: dir });
                 });
             }
         }
@@ -2285,6 +2449,423 @@ export function normalizeEvidenceRefs(raw, label) {
         return validateEvidenceRef({ ...ref }, label);
     });
 }
+function canonicalProjectRootForSession(dir) {
+    const artifactRoot = path.dirname(dir);
+    const kontouraiRoot = path.dirname(artifactRoot);
+    if (path.basename(artifactRoot) !== "flow-agents" || path.basename(kontouraiRoot) !== ".kontourai")
+        die("gate evidence requires a canonical .kontourai/flow-agents session");
+    const projectRoot = path.dirname(kontouraiRoot);
+    const stat = fs.lstatSync(projectRoot);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        die("gate evidence project root must be a non-symlink directory");
+    return projectRoot;
+}
+function pathIsWithinRoot(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+function validateLocalEvidenceFile(projectRoot, raw, label) {
+    const candidate = path.resolve(projectRoot, raw);
+    if (!pathIsWithinRoot(candidate, projectRoot))
+        die(`${label} must remain inside the canonical project root`);
+    let stat;
+    try {
+        stat = fs.lstatSync(candidate);
+    }
+    catch {
+        die(`${label} does not exist`);
+    }
+    if (stat.isSymbolicLink() || !stat.isFile())
+        die(`${label} must be a non-symlink regular file`);
+    if (!pathIsWithinRoot(fs.realpathSync(candidate), fs.realpathSync(projectRoot)))
+        die(`${label} escapes the canonical project root`);
+    return path.relative(projectRoot, candidate);
+}
+function globMatches(pattern, relative) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replaceAll("**", "::GLOBSTAR::").replaceAll("*", "[^/]*").replaceAll("::GLOBSTAR::", ".*");
+    return new RegExp(`^${escaped}$`).test(relative);
+}
+function expectedGateProducer(flowId, stepId, expectationId) {
+    const manifest = loadJson(path.join(flowAgentsPackageRoot(), "kits", "builder", "kit.json"));
+    const actions = Array.isArray(manifest.flow_step_actions) ? manifest.flow_step_actions : [];
+    const action = actions.find((candidate) => candidate.flow_id === flowId && candidate.step_id === stepId);
+    if (!action)
+        die(`record-gate-claim cannot derive a producer for unknown Flow step ${flowId}/${stepId}`);
+    const skills = Array.isArray(action.skills) ? action.skills.filter((value) => typeof value === "string") : [];
+    const roles = Array.isArray(manifest.skill_roles) ? manifest.skill_roles : [];
+    const owners = roles.filter((role) => typeof role.skill_id === "string"
+        && Array.isArray(role.step_ids) && role.step_ids.includes(stepId)
+        && Array.isArray(role.expectation_ids) && role.expectation_ids.includes(expectationId)
+        && skills.includes(role.skill_id.replace(/^builder\./, "")));
+    if (owners.length === 0) {
+        const operations = Array.isArray(action.operations) ? action.operations.filter((value) => typeof value === "string") : [];
+        const operationExpectations = Array.isArray(action.expectation_ids) ? action.expectation_ids : [];
+        if (operations.length === 1 && operationExpectations.includes(expectationId)) {
+            const artifacts = Array.isArray(action.artifacts) ? action.artifacts.filter((value) => typeof value === "string") : [];
+            return {
+                id: `operation:${operations[0]}`,
+                artifactPatterns: artifacts.filter((value) => !value.includes("#")),
+                selfProducedTrustSlices: artifacts.filter((value) => value.startsWith("trust.bundle#")).map((value) => value.slice("trust.bundle#".length)),
+            };
+        }
+    }
+    if (owners.length !== 1)
+        die(`record-gate-claim cannot derive exactly one producer for ${flowId}/${stepId}/${expectationId}`);
+    const owner = owners[0];
+    const artifacts = (Array.isArray(owner.artifacts) ? owner.artifacts : []).filter((value) => typeof value === "string" && value !== "ephemeral decision record");
+    return {
+        id: owner.skill_id,
+        artifactPatterns: artifacts.filter((value) => !value.includes("#")),
+        selfProducedTrustSlices: artifacts.filter((value) => value.startsWith("trust.bundle#")).map((value) => value.slice("trust.bundle#".length)),
+    };
+}
+function validateReviewableGateEvidence(dir, slug, refs, producer, label) {
+    if (refs.length === 0)
+        die(`${label} requires at least one reviewable --evidence-ref-json`);
+    const projectRoot = canonicalProjectRootForSession(dir);
+    let declaredProducerArtifactFound = producer.artifactPatterns.length === 0;
+    let localOrCommandEvidenceFound = false;
+    for (const [index, ref] of refs.entries()) {
+        if (ref.kind === "command" && hasNonEmptyString(ref.excerpt))
+            localOrCommandEvidenceFound = true;
+        if (typeof ref.file !== "string")
+            continue;
+        const relative = validateLocalEvidenceFile(projectRoot, ref.file, `${label} evidence ref ${index}`);
+        ref.file = relative;
+        localOrCommandEvidenceFound = true;
+        if (ref.kind === "artifact" && producer.artifactPatterns.length > 0) {
+            const patterns = producer.artifactPatterns.map((pattern) => {
+                const expanded = pattern.replaceAll("<slug>", slug);
+                return expanded.startsWith(".kontourai/") ? expanded : `.kontourai/flow-agents/${slug}/${expanded}`;
+            });
+            if (patterns.some((pattern) => globMatches(pattern, relative)))
+                declaredProducerArtifactFound = true;
+        }
+    }
+    if (!declaredProducerArtifactFound)
+        die(`${label} requires a declared durable artifact from producer ${producer.id}`);
+    if (producer.selfProducedTrustSlices.length > 0 && !localOrCommandEvidenceFound) {
+        die(`${label} is produced as trust.bundle fragment(s) ${producer.selfProducedTrustSlices.join(", ")} and requires local artifact or command evidence; external-only references cannot prove a passing claim`);
+    }
+}
+function commandFromEvidenceRef(ref) {
+    return typeof ref.excerpt === "string" ? ref.excerpt.trim() : (typeof ref.url === "string" ? ref.url.trim() : "");
+}
+function hasTestIntent(name) {
+    return /(?:^|[-_.\/])(test|tests|check|checks|verify|verification|spec|specs|eval|evals)(?:$|[-_.\/])/i.test(name) || /(?:test|check|verify|spec|eval)/i.test(path.basename(name));
+}
+function resolvesExplicitTestTarget(projectRoot, token) {
+    if (!hasTestIntent(token))
+        return false;
+    try {
+        if (/[*?\[]/.test(token))
+            return fs.globSync(token, { cwd: projectRoot }).length > 0;
+        const target = path.resolve(projectRoot, token);
+        return pathIsWithinRoot(target, projectRoot) && fs.lstatSync(target).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function staticTestUnits(file, executable) {
+    try {
+        const content = fs.readFileSync(file, "utf8").slice(0, 256 * 1024);
+        const hashComments = !["cargo", "go"].includes(executable);
+        const active = content.split("\n")
+            .map((line) => hashComments ? line.replace(/\s+#.*$/, "") : line.replace(/\s+\/\/.*$/, ""))
+            .filter((line) => hashComments ? !line.trimStart().startsWith("#") : !line.trimStart().startsWith("//"))
+            .join("\n");
+        if (["bash", "sh", "zsh"].includes(executable)
+            && !/(?:^|\n)\s*set\s+(?:-[^\n\s]*e[^\n\s]*|-o\s+errexit)(?:\s|$)/.test(active))
+            return 0;
+        const assertions = active.match(/(?:\b(?:test|it)\s*\(|\b(?:assert|expect)\s*\(|^\s*(?:async\s+)?def\s+test_|^\s*(?:public\s+)?function\s+test|^\s*it\s+["']|^\s*func\s+(?:Test|Fuzz|Example)\w*\s*\(|#\[(?:\w+::)?test\]|^(?:if\s+! ?)?(?:test\s|\[\s|\[\[\s|(?:grep|rg|diff|cmp)\s))/gm) ?? [];
+        return assertions.length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Produce evidence from the locally executed command and statically reviewable
+ * test units. Runner stdout is deliberately excluded: any executable can print
+ * a Vitest/Jest-looking success summary, but it cannot turn a non-test script
+ * into a supported test workflow or supply this locally-created proof.
+ */
+export function testExecutionProof(command, projectRoot, seenScripts = new Set(), packageScriptBody = false) {
+    const normalized = command.trim().replace(/\s+/g, " ");
+    if (!normalized || /[`$()]/.test(normalized))
+        return null;
+    if (/[;&|]/.test(normalized)) {
+        if (!packageScriptBody || normalized.includes("||") || /[;|]/.test(normalized))
+            return null;
+        const segments = normalized.split(/\s*&&\s*/).filter(Boolean);
+        return segments.length > 1 ? segments.map((segment) => testExecutionProof(segment, projectRoot, new Set(seenScripts), false)).find(Boolean) ?? null : null;
+    }
+    if (/^(?:true|:|\/usr\/bin\/true)$/i.test(normalized))
+        return null;
+    if (/^(?:echo|printf)(?:\s|$)/i.test(normalized))
+        return null;
+    if (/(?:^|\s)(?:--version|-v|--help|-h)(?:\s|$)/.test(normalized))
+        return null;
+    const tokens = normalized.split(" ").filter(Boolean);
+    while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[0] ?? ""))
+        tokens.shift();
+    const executable = tokens[0] ?? "";
+    const executableName = path.basename(executable);
+    if (["npm", "pnpm", "yarn", "bun"].includes(executableName)) {
+        // `bun test` is Bun's test runner; package scripts use `bun run <script>`.
+        if (executableName === "bun" && tokens[1] === "test") {
+            const target = tokens.slice(2).find((token) => !token.startsWith("-") && resolvesExplicitTestTarget(projectRoot, token));
+            const units = target ? staticTestUnits(path.resolve(projectRoot, target), "bun") : 0;
+            return units > 0 ? { kind: "local-process-exit", runner: "bun test", static_test_units: units } : null;
+        }
+        const script = tokens[1] === "run" || tokens[1] === "run-script" ? tokens[2] : tokens[1];
+        if (!script || !hasTestIntent(script) || seenScripts.has(script))
+            return null;
+        try {
+            const pkg = loadJson(path.join(projectRoot, "package.json"));
+            const scriptCommand = pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts[script] : undefined;
+            if (typeof scriptCommand !== "string")
+                return null;
+            seenScripts.add(script);
+            return testExecutionProof(scriptCommand, projectRoot, seenScripts, true);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (["vitest", "jest", "mocha", "ava", "pytest", "rspec", "phpunit"].includes(executableName)
+        && !tokens.some((token) => /pass.?with.?no.?tests/i.test(token))) {
+        if (executable !== executableName)
+            return null;
+        const targets = tokens.slice(1)
+            .filter((token) => !token.startsWith("-") && resolvesExplicitTestTarget(projectRoot, token))
+            .flatMap((token) => /[*?\[]/.test(token) ? fs.globSync(token, { cwd: projectRoot }) : [token]);
+        const units = targets.reduce((total, target) => total + staticTestUnits(path.resolve(projectRoot, target), executableName), 0);
+        return units > 0 ? { kind: "local-process-exit", runner: executableName, static_test_units: units } : null;
+    }
+    if (executableName === "cargo" && tokens[1] === "test") {
+        const files = [...fs.globSync("tests/**/*.rs", { cwd: projectRoot }), ...fs.globSync("src/**/*.rs", { cwd: projectRoot })];
+        const units = [...new Set(files)].reduce((total, file) => total + staticTestUnits(path.resolve(projectRoot, file), "cargo"), 0);
+        return units > 0 ? { kind: "local-process-exit", runner: "cargo test", static_test_units: units } : null;
+    }
+    if (executableName === "go" && tokens[1] === "test") {
+        const files = fs.globSync("**/*_test.go", { cwd: projectRoot, exclude: ["vendor/**", ".git/**"] });
+        const units = files.reduce((total, file) => total + staticTestUnits(path.resolve(projectRoot, file), "go"), 0);
+        return units > 0 ? { kind: "local-process-exit", runner: "go test", static_test_units: units } : null;
+    }
+    if (executableName === "npx" && tokens[1] && ["vitest", "jest", "mocha", "ava", "pytest"].includes(path.basename(tokens[1]))) {
+        const runner = path.basename(tokens[1]);
+        const targets = tokens.slice(2)
+            .filter((token) => !token.startsWith("-") && resolvesExplicitTestTarget(projectRoot, token))
+            .flatMap((token) => /[*?\[]/.test(token) ? fs.globSync(token, { cwd: projectRoot }) : [token]);
+        const units = targets.reduce((total, target) => total + staticTestUnits(path.resolve(projectRoot, target), runner), 0);
+        return units > 0 ? { kind: "local-process-exit", runner: `npx ${runner}`, static_test_units: units } : null;
+    }
+    if (executableName === "node" && tokens.includes("--test")) {
+        const testFlag = tokens.indexOf("--test");
+        const targets = tokens.slice(testFlag + 1)
+            .filter((token) => !token.startsWith("-") && resolvesExplicitTestTarget(projectRoot, token))
+            .flatMap((token) => /[*?\[]/.test(token) ? fs.globSync(token, { cwd: projectRoot }) : [token]);
+        const units = targets.reduce((total, target) => total + staticTestUnits(path.resolve(projectRoot, target), executableName), 0);
+        return units > 0 ? { kind: "local-process-exit", runner: "node --test", static_test_units: units } : null;
+    }
+    const scriptPath = ["bash", "sh", "zsh", "tsx", "ts-node"].includes(executableName) ? tokens[1] : executable;
+    if (!scriptPath || ["-c", "-lc", "-e"].includes(scriptPath) || !hasTestIntent(scriptPath))
+        return null;
+    try {
+        const resolved = path.resolve(projectRoot, scriptPath);
+        const stat = fs.lstatSync(resolved);
+        if (stat.isSymbolicLink() || !stat.isFile() || !pathIsWithinRoot(fs.realpathSync(resolved), fs.realpathSync(projectRoot)))
+            return null;
+        const units = staticTestUnits(resolved, executableName);
+        return units > 0 ? { kind: "local-process-exit", runner: executableName, static_test_units: units } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Validate test-evidence command shape without executing it. */
+export function isMeaningfulTestCommand(command, projectRoot, seenScripts = new Set(), packageScriptBody = false) {
+    return testExecutionProof(command, projectRoot, seenScripts, packageScriptBody) !== null;
+}
+export function observedExecutedTestCount(output) {
+    const counts = [];
+    for (const pattern of [
+        /^\s*(?:#|ℹ)\s*tests\s+(\d+)\s*$/gim,
+        /^\s*1\.\.(\d+)(?:\s|$)/gim,
+        /\b(\d+)\s+passed\b/gim,
+    ]) {
+        for (const match of output.matchAll(pattern))
+            counts.push(Number(match[1]));
+    }
+    const explicitPasses = output.match(/^\s*(?:---\s+PASS:|ok\s+\d+\s+-)/gm)?.length ?? 0;
+    if (explicitPasses > 0)
+        counts.push(explicitPasses);
+    const goPackages = output.match(/^ok\s+\S+(?:\s|$)/gm)?.length ?? 0;
+    if (goPackages > 0)
+        counts.push(goPackages);
+    return Math.max(0, ...counts.filter((count) => Number.isSafeInteger(count) && count > 0));
+}
+export function inferExecutedTestCount(command, projectRoot, output, seenScripts = new Set()) {
+    const proof = testExecutionProof(command, projectRoot, seenScripts);
+    if (!proof)
+        return 0;
+    const observed = observedExecutedTestCount(output);
+    return observed > 0 ? Math.min(proof.static_test_units, observed) : 0;
+}
+async function normalizeObservedCommands(commands, projectRoot, requireTestIntent, expectedStatus) {
+    if (commands.length === 0)
+        die("record-gate-claim requires at least one --command for observed command evidence");
+    if (new Set(commands).size !== commands.length)
+        die("record-gate-claim --command values must be unique");
+    for (const command of commands) {
+        const { isRunnableCommandText } = loadRunnableCommandHelper();
+        if (!isRunnableCommandText(command))
+            die(`record-gate-claim --command "${command}" is not a runnable shell command — prose belongs in --summary, which is never executed.`);
+        if (requireTestIntent && !isMeaningfulTestCommand(command, projectRoot))
+            die("record-gate-claim tests-evidence command must resolve through a non-vacuous package script or a known test/check/verify/eval runner or project-local test path; shell wrappers, no-ops, version/help commands, and arbitrary node -e commands are not evidence");
+    }
+    // Passing test evidence is always executed exactly once by this canonical
+    // writer. Caller-supplied observations remain available for non-test
+    // attestations but can never stand in for locally observed test execution.
+    const observed = await Promise.all(commands.map(async (command) => {
+        const result = await runObservedCommand(command, projectRoot);
+        const proof = requireTestIntent ? testExecutionProof(command, projectRoot) : null;
+        return { command, exit_code: result.exit_code, output_sha256: result.output_sha256, ...(proof ? { test_count: inferExecutedTestCount(command, projectRoot, result.output), execution_proof: proof } : {}) };
+    }));
+    if (observed.length !== commands.length)
+        die("record-gate-claim requires exactly one --observed-command-json for every --command");
+    const byCommand = new Map();
+    for (const entry of observed) {
+        if (typeof entry.command !== "string" || typeof entry.exit_code !== "number" || !Number.isInteger(entry.exit_code) || typeof entry.output_sha256 !== "string" || !/^[a-f0-9]{64}$/i.test(entry.output_sha256))
+            die("--observed-command-json must contain command, integer exit_code, and sha256 output_sha256");
+        if (!commands.includes(entry.command))
+            die("--observed-command-json command must exactly match one supplied --command");
+        if (expectedStatus === "pass" && entry.exit_code !== 0)
+            die(`record-gate-claim passing evidence command failed (exit ${entry.exit_code}): ${entry.command}`);
+        if (expectedStatus === "fail" && entry.exit_code === 0)
+            die(`record-gate-claim failing evidence command unexpectedly passed: ${entry.command}`);
+        if (requireTestIntent && (!Number.isSafeInteger(entry.test_count) || Number(entry.test_count) <= 0 || !entry.execution_proof || entry.execution_proof.kind !== "local-process-exit"))
+            die(`record-gate-claim passing tests-evidence command did not produce a local execution proof: ${entry.command}`);
+        if (byCommand.has(entry.command))
+            die("--observed-command-json command values must be unique");
+        byCommand.set(entry.command, entry);
+    }
+    if (commands.some((command) => !byCommand.has(command)))
+        die("every --command requires a corresponding --observed-command-json");
+    return commands.map((command) => byCommand.get(command));
+}
+function requireObservedCommandRefs(refs, observedCommands, label, requireAll = false) {
+    const commandRefs = refs.filter((ref) => ref.kind === "command");
+    if (commandRefs.length === 0)
+        die(`${label} requires a command evidence ref matching a successful observed command`);
+    for (const ref of commandRefs) {
+        if (!observedCommands.has(commandFromEvidenceRef(ref)))
+            die(`${label} command evidence ref must exactly match a successful --observed-command-json command`);
+    }
+    if (requireAll) {
+        const referenced = new Set(commandRefs.map(commandFromEvidenceRef));
+        if ([...observedCommands].some((command) => !referenced.has(command)))
+            die(`${label} requires a top-level command evidence ref for every successful observed command`);
+    }
+}
+function completePassingCriteria(existing, raw, observedCommands) {
+    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"));
+    const expectedById = new Map();
+    for (const criterion of existing) {
+        const id = String(criterion.id ?? "");
+        if (id.length > 0)
+            expectedById.set(id, criterion);
+    }
+    const expectedIds = [...expectedById.keys()];
+    const ids = incoming.map((criterion) => typeof criterion.id === "string" ? criterion.id : "");
+    if (new Set(ids).size !== ids.length || ids.length !== expectedIds.length || ids.some((id) => !expectedIds.includes(id))) {
+        die(`--criterion-json must cover every declared acceptance criterion exactly once (expected: ${expectedIds.join(", ") || "none"}; received: ${ids.join(", ") || "none"})`);
+    }
+    return incoming.map((criterion, index) => {
+        if (Object.keys(criterion).some((key) => !["id", "status", "evidence_refs"].includes(key)))
+            die(`criterion ${ids[index]} may update only id, status, and evidence_refs`);
+        if (criterion.status !== "pass")
+            die(`criterion ${ids[index]} must have status pass for a passing tests-evidence claim`);
+        const refs = normalizeEvidenceRefs(criterion.evidence_refs, `criterion ${ids[index]} evidence_refs`);
+        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 };
+    });
+}
+const critiqueStatuses = new Set(["pass", "fail", "not_verified"]);
+const safeCritiqueId = /^[a-z][a-z0-9_-]*$/;
+function normalizeCritiqueLanes(raw) {
+    if (raw.length === 0)
+        die("record-critique requires at least one --lane-json");
+    const lanes = raw.map((value, index) => {
+        const lane = parseJson(value, "--lane-json");
+        const keys = Object.keys(lane);
+        if (keys.some((key) => !["id", "status", "summary", "evidence_refs"].includes(key)))
+            die(`--lane-json ${index} contains unsupported fields`);
+        if (!safeCritiqueId.test(String(lane.id ?? "")))
+            die(`--lane-json ${index} id must be a unique safe identifier`);
+        if (!critiqueStatuses.has(String(lane.status ?? "")))
+            die(`--lane-json ${index} status must be one of: pass, fail, not_verified`);
+        if (!hasNonEmptyString(lane.summary))
+            die(`--lane-json ${index} summary must be non-empty`);
+        const evidenceRefs = normalizeEvidenceRefs(lane.evidence_refs, `--lane-json ${index} evidence_refs`);
+        if (evidenceRefs.length === 0)
+            die(`--lane-json ${index} requires structured reviewable evidence_refs`);
+        return { id: lane.id, status: lane.status, summary: lane.summary, evidence_refs: evidenceRefs };
+    });
+    if (new Set(lanes.map((lane) => lane.id)).size !== lanes.length)
+        die("--lane-json ids must be unique");
+    return lanes;
+}
+function reviewTargetArtifacts(dir, rawPaths, label) {
+    const projectRoot = canonicalProjectRootForSession(dir);
+    const fallback = path.join(dir, `${taskSlugFor(dir)}--deliver.md`);
+    const paths = rawPaths.length > 0 ? rawPaths : (fs.existsSync(fallback) ? [fallback] : []);
+    const files = paths.map((raw, index) => validateLocalEvidenceFile(projectRoot, raw, `${label} artifact ${index}`));
+    if (new Set(files).size !== files.length)
+        die(`${label} artifact refs must be unique`);
+    return files.map((file) => ({ file, sha256: createHash("sha256").update(fs.readFileSync(path.join(projectRoot, file))).digest("hex") }));
+}
+function reviewTargetArtifactsMatch(dir, reviewTarget) {
+    try {
+        if (!reviewTarget || typeof reviewTarget !== "object" || Array.isArray(reviewTarget))
+            return false;
+        const artifacts = reviewTarget.artifacts;
+        if (!Array.isArray(artifacts) || artifacts.length === 0)
+            return false;
+        const projectRoot = canonicalProjectRootForSession(dir);
+        const files = new Set();
+        return artifacts.every((artifact) => {
+            if (!artifact || typeof artifact !== "object")
+                return false;
+            const file = artifact.file;
+            const sha256 = artifact.sha256;
+            if (!hasNonEmptyString(file) || !/^[a-f0-9]{64}$/i.test(String(sha256)) || files.has(file))
+                return false;
+            files.add(file);
+            const relative = validateLocalEvidenceFile(projectRoot, file, "critique review_target artifact");
+            const digest = createHash("sha256").update(fs.readFileSync(path.join(projectRoot, relative))).digest("hex");
+            return digest === sha256;
+        });
+    }
+    catch {
+        return false;
+    }
+}
+function critiqueIsCleanAndCurrent(dir, critique) {
+    if (critique.verdict !== "pass")
+        return false;
+    if (!Array.isArray(critique.lanes) || critique.lanes.length === 0 || critique.lanes.some((lane) => lane.status !== "pass"))
+        return false;
+    if (Array.isArray(critique.findings) && critique.findings.some((finding) => finding.status === "open"))
+        return false;
+    return reviewTargetArtifactsMatch(dir, critique.review_target);
+}
 // #270 HIGH fix (iteration 3): the `gate-claim-` check-id prefix is RESERVED for
 // record-gate-claim's own internally-constructed ids (`id: \`gate-claim-${checkId}\`` — see
 // recordGateClaim below). Every OTHER writer of check ids (record-evidence --check-json,
@@ -2618,6 +3199,20 @@ function checksFromBundle(dir) {
         const od = md && typeof md === "object" ? md.output_digest : undefined;
         return od && typeof od === "object" && od.algorithm === "sha256" && typeof od.hex === "string" && od.hex.length > 0 ? od.hex : undefined;
     };
+    const observedCommandsOf = (claim) => {
+        const md = claim.metadata;
+        const observed = md && typeof md === "object" ? md.observed_commands : undefined;
+        return Array.isArray(observed) ? observed.filter((entry) => typeof entry?.command === "string" && typeof entry?.exit_code === "number" && typeof entry?.output_sha256 === "string") : undefined;
+    };
+    const applyProducerStamp = (check, claim) => {
+        const md = claim.metadata;
+        if (md && typeof md.expected_producer === "string")
+            check._producer = md.expected_producer;
+        if (md && typeof md.recorded_by === "string")
+            check._recorded_by = md.recorded_by;
+        if (md && Array.isArray(md.self_produced_trust_slices))
+            check._producer_self_produced_trust_slices = md.self_produced_trust_slices;
+    };
     // #270(a)/(c): read side of the gate_claim stamp (write side: buildTrustBundle's
     // claimMetadata.gate_claim, above). Restoring expectation_id/claim_type/subject_type/step_id
     // is what lets a REBUILD (record-evidence/record-critique/record-learning, after the recorded
@@ -2711,6 +3306,10 @@ function checksFromBundle(dir) {
         const outputSha256 = outputSha256Of(claim);
         if (outputSha256)
             check._output_sha256 = outputSha256;
+        const observedCommands = observedCommandsOf(claim);
+        if (observedCommands)
+            check._observed_commands = observedCommands;
+        applyProducerStamp(check, claim);
         applyGateClaimStamp(check, claim);
         applyGateClaimShapeUnstamped(check, claim);
         checks.push(check);
@@ -2733,6 +3332,10 @@ function checksFromBundle(dir) {
         const outputSha256 = outputSha256Of(claim);
         if (outputSha256)
             check._output_sha256 = outputSha256;
+        const observedCommands = observedCommandsOf(claim);
+        if (observedCommands)
+            check._observed_commands = observedCommands;
+        applyProducerStamp(check, claim);
         applyGateClaimStamp(check, claim);
         applyGateClaimShapeUnstamped(check, claim);
         checks.push(check);
@@ -2767,9 +3370,18 @@ function existingCheckStampMap(checks) {
  */
 function readBundleState(dir) {
     const acceptance = loadJson(path.join(dir, "acceptance.json"));
+    const bundledCriteria = criteriaFromBundle(dir);
+    const acceptedCriteria = Array.isArray(acceptance.criteria) ? acceptance.criteria : [];
+    const contractSignature = (criteria) => JSON.stringify(criteria.map((criterion) => ({
+        id: criterion.id ?? null,
+        description: criterion.description ?? null,
+    })));
+    const criteria = acceptedCriteria.length > 0 && contractSignature(acceptedCriteria) !== contractSignature(bundledCriteria)
+        ? acceptedCriteria
+        : (bundledCriteria.length > 0 ? bundledCriteria : acceptedCriteria);
     return {
         checks: checksFromBundle(dir),
-        criteria: Array.isArray(acceptance.criteria) ? acceptance.criteria : [],
+        criteria,
         critiques: critiquesFromBundle(dir),
     };
 }
@@ -2806,14 +3418,36 @@ function critiquesFromBundle(dir) {
             id: String(c.subjectId || "").split("/").pop() || c.id,
             verdict: c.value ?? "not_verified",
             summary: c.fieldOrBehavior || "",
-            findings: [],
+            findings: Array.isArray(md.findings) ? md.findings : [],
+            lanes: Array.isArray(md.lanes) ? md.lanes : [],
+            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()),
-            artifact_refs: [],
+            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 } : {}),
         };
     });
 }
+function criteriaFromBundle(dir) {
+    const bundle = loadJson(path.join(dir, "trust.bundle"));
+    if (!Array.isArray(bundle.claims))
+        return [];
+    for (const claim of bundle.claims)
+        requireStampedClaim(claim, dir);
+    return bundle.claims
+        .filter((claim) => claim && claimOrigin(claim) === "acceptance")
+        .map((claim) => {
+        const md = claim.metadata && typeof claim.metadata === "object" && !Array.isArray(claim.metadata) ? claim.metadata : {};
+        const saved = md.criterion && typeof md.criterion === "object" && !Array.isArray(md.criterion) ? md.criterion : {};
+        return {
+            id: typeof saved.id === "string" ? saved.id : String(claim.subjectId || "").split("/").pop(),
+            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 : [],
+        };
+    })
+        .filter((criterion) => typeof criterion.id === "string" && criterion.id.length > 0);
+}
 // ─────────────────────────────────────────────────────────────────────────────
 /**
  * WS8 (ADR 0020): parse the accepted-gap waiver flags. Both --accepted-gap-reason and
@@ -2876,13 +3510,11 @@ async function recordEvidence(p) {
     // with the same id supersedes the earlier one (same-id resupply); a new id is additive.
     // (_existingState was already read above, before normalizeCheck ran, so the reserved-prefix
     // exists-check sees the SAME bundle snapshot the merge below uses — no second read needed.)
-    const _criteriaStatus = verdict === "pass" ? "pass" : verdict === "fail" ? "fail" : "not_verified";
-    const _criteriaForBundle = _existingState.criteria.map((c) => ({ ...c, status: _criteriaStatus }));
     const _mergedChecks = mergeChecksById(_existingState.checks, checks);
     // #268: preserve any existing critique claims (including superseded history) instead of dropping
     // them — record-evidence previously hardcoded critiques:[] here, silently erasing finding history
     // whenever it ran after a critique existed.
-    assertBundleWritten(await writeTrustBundle(dir, slug, ts, _mergedChecks, _criteriaForBundle, _existingState.critiques));
+    assertBundleWritten(await writeTrustBundle(dir, slug, ts, _mergedChecks, _existingState.criteria, _existingState.critiques));
     const stateStatus = verdict === "pass" ? "verified" : verdict === "fail" ? "failed" : "not_verified";
     writeState(dir, slug, stateStatus, "verification", ts, "Evidence recorded.");
     return 0;
@@ -3089,14 +3721,23 @@ async function recordGateClaim(p) {
         die("--route-reason is only valid with --status fail");
     if (routeReason && !/^[a-z][a-z0-9_-]*$/.test(routeReason))
         die("--route-reason must be a lowercase classifier identifier");
-    // Resolve the active flow step from current.json. #291 Wave 2 Task 2.1 (§7)/Task 2.2: resolve
-    // the CALLING actor's own current-pointer (per-actor-first, legacy-fallback) rather than an
-    // unconditional legacy-only read — this is the fix for record-gate-claim's pre-existing (#291
-    // Stop-short risk) lack of a dir-scoping guard: it now resolves ITS OWN actor's current.json
-    // view, not a different actor's more-recently-written legacy pointer.
+    // Prefer the exact session's canonical Flow projection. Actor/global current pointers are
+    // ambient navigation state and may legitimately point at another run or lag this run.
+    // Legacy sessions without flow_run retain the per-actor current-pointer fallback.
     const flowAgentsDir = path.dirname(dir);
     const gateClaimActorKey = resolveReadActorKey(p);
-    const activeStep = resolveActiveFlowStep(flowAgentsDir, gateClaimActorKey);
+    const sidecarState = loadJson(path.join(dir, "state.json"));
+    const projectedRun = sidecarState.flow_run && typeof sidecarState.flow_run === "object" && !Array.isArray(sidecarState.flow_run)
+        ? sidecarState.flow_run
+        : null;
+    const exactFlowId = projectedRun && typeof projectedRun.definition_id === "string" ? projectedRun.definition_id : null;
+    const exactStepId = projectedRun && typeof projectedRun.current_step === "string" ? projectedRun.current_step : null;
+    const exactFlowContext = exactFlowId && exactStepId ? { flowId: exactFlowId, stepId: exactStepId } : undefined;
+    const activeStep = exactFlowContext
+        ? resolveFlowStep(exactFlowContext.flowId, exactFlowContext.stepId, findRepoRootFromDir(path.dirname(flowAgentsDir)))
+        : resolveActiveFlowStep(flowAgentsDir, gateClaimActorKey);
+    if (exactFlowContext && !activeStep)
+        die(`record-gate-claim cannot resolve exact session Flow step ${exactFlowContext.flowId}/${exactFlowContext.stepId}`);
     if (!activeStep)
         die("record-gate-claim requires an active flow step in current.json (set via ensure-session --flow-id or advance-state --flow-definition)");
     if (routeReason && !activeStep.routeBackReasons.includes(routeReason)) {
@@ -3119,17 +3760,38 @@ async function recordGateClaim(p) {
         die(`record-gate-claim: gate "${activeStep.gateId}" has ${expects.length} expects[] entries; --expectation <id> is required. Available: ${expects.map((e) => e.id).join(", ")}`);
     }
     const { claimType, subjectType } = targetExpectation.bundle_claim;
-    // Build a synthetic external check that will be matched by matchExpectsEntry to produce
-    // a correctly-typed claim. We use kind="external" so it routes through the non-policy,
-    // non-flow-step fallback path. The subjectType on the resulting claim comes from the
-    // expects[] entry via matchExpectsEntry.
+    const gateCommands = opts(p, "command");
+    const gateCommand = gateCommands[0] ?? "";
+    const mustRunTests = targetExpectation.id === "tests-evidence" && statusVal === "pass";
+    const observedCommandRaw = opts(p, "observed-command-json");
+    if (mustRunTests && gateCommands.length === 0)
+        die("record-gate-claim requires at least one --command for a passing tests-evidence claim");
+    const projectRoot = gateCommands.length > 0 ? canonicalProjectRootForSession(dir) : null;
+    const observedCommands = gateCommands.length > 0
+        ? await normalizeObservedCommands(gateCommands, projectRoot, mustRunTests, statusVal)
+        : [];
+    const observedCommandNames = new Set(observedCommands.map((entry) => entry.command));
+    let outputSha256 = null;
+    if (!mustRunTests && gateCommands.length > 1)
+        die("record-gate-claim accepts repeatable --command only for passing tests-evidence claims");
+    if (gateCommands.length === 0 && observedCommandRaw.length > 0)
+        die("--observed-command-json requires --command");
+    if (!mustRunTests && gateCommand && observedCommandRaw.length === 0) {
+        const { isRunnableCommandText } = loadRunnableCommandHelper();
+        if (!isRunnableCommandText(gateCommand))
+            die(`record-gate-claim --command "${gateCommand}" is not a runnable shell command — prose belongs in --summary, which is never executed.`);
+    }
+    if (observedCommands.length > 0)
+        outputSha256 = observedCommands[0].output_sha256;
+    // Build a gate-targeted check that matchExpectsEntry maps to the declared claim tuple.
+    // Command-backed checks retain their executable evidence classification.
     const checkId = expectationId || targetExpectation.id;
     // Build a minimal "external" check. Include _gate_claim_expectation_id so that
     // matchExpectsEntry can do an exact lookup for multi-expects[] gates (ADR 0016 P-d Increment 2).
     // normalizeCheck preserves extra underscore-prefixed fields without stripping them.
     const check = {
         id: `gate-claim-${checkId}`,
-        kind: "external",
+        kind: gateCommands.length > 0 ? "command" : "external",
         status: statusVal,
         summary,
         _gate_claim_expectation_id: targetExpectation.id,
@@ -3137,23 +3799,31 @@ async function recordGateClaim(p) {
     };
     // Include structured evidence refs if provided
     const evidenceRefs = opts(p, "evidence-ref-json").map((v) => validateEvidenceRef(parseJson(v, "--evidence-ref-json"), "--evidence-ref-json"));
+    const producer = expectedGateProducer(exactFlowContext?.flowId ?? activeStep.flowId, activeStep.stepId, targetExpectation.id);
+    if (statusVal === "pass")
+        validateReviewableGateEvidence(dir, slug, evidenceRefs, producer, `gate claim ${targetExpectation.id}`);
+    if (mustRunTests)
+        requireObservedCommandRefs(evidenceRefs, observedCommandNames, "a passing tests-evidence claim", true);
     if (evidenceRefs.length > 0) {
         check.artifact_refs = evidenceRefs;
     }
+    check._producer = producer.id;
+    check._recorded_by = gateClaimActorKey;
+    if (producer.selfProducedTrustSlices.length > 0)
+        check._producer_self_produced_trust_slices = producer.selfProducedTrustSlices;
     // #270(b)/#412: --command gives a gate claim a real, runnable execution.label distinct from
     // the human --summary prose, so stop-goal-fit.js's bundleClaimedPassCommandChecks section (B)
     // finds a real command to re-run instead of falling back to fieldOrBehavior (the --summary
     // prose itself), which it would otherwise execute as a shell command under
     // FLOW_AGENTS_GOAL_FIT_RECHECK. Validated at record time with the same isRunnableCommandText
     // heuristic the Stop-hook backstop uses (single-sourced — see loadRunnableCommandHelper).
-    const gateCommand = opt(p, "command");
-    if (gateCommand) {
-        const { isRunnableCommandText } = loadRunnableCommandHelper();
-        if (!isRunnableCommandText(gateCommand))
-            die(`record-gate-claim --command "${gateCommand}" is not a runnable shell command — prose belongs in --summary, which is never executed.`);
+    if (gateCommand)
         check.command = gateCommand;
-    }
+    if (observedCommands.length > 0)
+        check._observed_commands = observedCommands;
     const checkNormalized = normalizeCheck(check, /* allowGateClaimPrefix */ true);
+    if (outputSha256)
+        checkNormalized._output_sha256 = outputSha256;
     // WS8 (ADR 0020): honor the accepted-gap waiver flags for a gate claim too.
     const gateWaiver = parseWaiver(p, ts);
     if (gateWaiver)
@@ -3166,8 +3836,17 @@ 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;
+    if (mustRunTests) {
+        const liveCritiques = _existingState.critiques.filter((critique) => !critique.superseded_by);
+        if (liveCritiques.length === 0 || liveCritiques.some((critique) => !critiqueIsCleanAndCurrent(dir, critique))) {
+            die("a passing tests-evidence claim requires a current clean critique first");
+        }
+        for (const criterion of criteria)
+            validateReviewableGateEvidence(dir, slug, criterion.evidence_refs, producer, `criterion ${criterion.id}`);
+    }
     const _mergedChecks = mergeChecksById(_existingState.checks, [checkNormalized]);
-    assertBundleWritten(await writeTrustBundle(dir, slug, ts, _mergedChecks, _existingState.criteria, _existingState.critiques, gateClaimActorKey));
+    assertBundleWritten(await writeTrustBundle(dir, slug, ts, _mergedChecks, criteria, _existingState.critiques, gateClaimActorKey, exactFlowContext));
     return 0;
 }
 /**
@@ -3354,12 +4033,46 @@ export function normalizeFinding(raw) {
 async function recordCritique(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
     const slug = taskSlugFor(dir, opt(p, "task-slug"));
-    // Phase 4c: accumulate existing critiques from trust.bundle (critique.json no longer written).
-    // Fall back to critique.json for legacy sessions that still have it on disk.
-    const existingCritiqueJson = loadJson(path.join(dir, "critique.json"), { critiques: [] });
-    const legacyCritiques = Array.isArray(existingCritiqueJson.critiques) ? existingCritiqueJson.critiques : [];
-    const bundleCritiques = legacyCritiques.length === 0 ? critiquesFromBundle(dir) : legacyCritiques;
-    const critique = { id: opt(p, "id") || "review", reviewer: opt(p, "reviewer", "tool-code-reviewer"), reviewed_at: opt(p, "timestamp", now()), verdict: opt(p, "verdict", "pass"), summary: opt(p, "summary"), artifact_refs: opts(p, "artifact-ref"), findings: opts(p, "finding-json").map((v) => normalizeFinding(parseJson(v, "--finding-json"))) };
+    const verdict = opt(p, "verdict");
+    if (!critiqueStatuses.has(verdict))
+        die("record-critique requires --verdict pass, fail, or not_verified");
+    const summary = opt(p, "summary");
+    if (!hasNonEmptyString(summary))
+        die("record-critique requires --summary");
+    const lanes = normalizeCritiqueLanes(opts(p, "lane-json"));
+    const reviewArtifacts = reviewTargetArtifacts(dir, opts(p, "artifact-ref"), "record-critique review_target");
+    if (verdict === "pass" && (lanes.some((lane) => lane.status !== "pass") || reviewArtifacts.length === 0)) {
+        die("a passing critique requires every lane to pass and at least one local reviewed --artifact-ref");
+    }
+    const sidecarState = loadJson(path.join(dir, "state.json"));
+    const projectedRun = sidecarState.flow_run && typeof sidecarState.flow_run === "object" && !Array.isArray(sidecarState.flow_run)
+        ? sidecarState.flow_run
+        : null;
+    const exactFlowContext = projectedRun
+        && typeof projectedRun.definition_id === "string"
+        && typeof projectedRun.current_step === "string"
+        ? { flowId: projectedRun.definition_id, stepId: projectedRun.current_step }
+        : undefined;
+    // trust.bundle is the sole critique source. critique.json is unsupported historical residue.
+    const _critiqueState = readBundleState(dir);
+    const bundleCritiques = _critiqueState.critiques;
+    const critiqueId = opt(p, "id", "review");
+    if (!safeCritiqueId.test(critiqueId))
+        die("record-critique --id must be a safe identifier");
+    const critique = {
+        id: critiqueId,
+        reviewer: opt(p, "reviewer", "tool-code-reviewer"),
+        reviewed_at: opt(p, "timestamp", now()),
+        verdict,
+        summary,
+        lanes,
+        review_target: {
+            artifacts: reviewArtifacts,
+            workspace_snapshot: captureReviewWorkspaceSnapshot(canonicalProjectRootForSession(dir), reviewArtifacts.map((artifact) => ({ file: String(artifact.file), sha256: String(artifact.sha256) }))),
+        },
+        artifact_refs: reviewArtifacts.map((artifact) => artifact.file),
+        findings: opts(p, "finding-json").map((v) => normalizeFinding(parseJson(v, "--finding-json"))),
+    };
     if (critique.verdict === "pass" && critique.findings.some((f) => f.status === "open"))
         die("required critique must pass");
     // #267/#282: supersede-by-critique-id. The latest write for a critique id wins for
@@ -3386,8 +4099,7 @@ async function recordCritique(p) {
     // checksFromBundle + acceptance.json read inline — this is the exact pattern readBundleState
     // already exists to share; recordLearning uses it directly (see below) and recordCritique
     // previously duplicated it by hand for no reason.
-    const _critiqueState = readBundleState(dir);
-    assertBundleWritten(await writeTrustBundle(dir, slug, critique.reviewed_at, _critiqueState.checks, _critiqueState.criteria, critiques));
+    assertBundleWritten(await writeTrustBundle(dir, slug, critique.reviewed_at, _critiqueState.checks, _critiqueState.criteria, critiques, undefined, exactFlowContext));
     return 0;
 }
 function frontmatter(text, key) {
@@ -3413,7 +4125,22 @@ async function importCritique(p) {
         const title = m.groups?.title ?? "finding";
         findings.push({ id: slugify(title, `finding-${findings.length + 1}`), severity: (m.groups?.severity ?? "info").toLowerCase(), status: opt(p, "finding-status", verdict === "pass" ? "fixed" : "open"), description: title, file_refs: [m.groups?.target ?? review] });
     }
-    const parsed = { ...p, positional: [dir], opts: { ...p.opts, id: [slugify(path.basename(review).replace(/\.md$/, ""), "review")], reviewer: ["tool-code-reviewer"], verdict: [verdict], summary: [`Imported critique from ${path.basename(review)}`], "finding-json": findings.map((f) => JSON.stringify(f)) }, flags: p.flags };
+    const importedArtifact = path.relative(canonicalProjectRootForSession(dir), review);
+    const parsed = {
+        ...p,
+        positional: [dir],
+        opts: {
+            ...p.opts,
+            id: [slugify(path.basename(review).replace(/\.md$/, ""), "review")],
+            reviewer: ["tool-code-reviewer"],
+            verdict: [verdict],
+            summary: [`Imported critique from ${path.basename(review)}`],
+            "artifact-ref": [importedArtifact],
+            "lane-json": [JSON.stringify({ id: "imported-review", status: verdict, summary: `Imported review artifact ${path.basename(review)}.`, evidence_refs: [{ kind: "artifact", file: importedArtifact, summary: "Imported review artifact." }] })],
+            "finding-json": findings.map((f) => JSON.stringify(f)),
+        },
+        flags: p.flags,
+    };
     const result = await recordCritique(parsed);
     if (verdict !== "pass")
         die("required critique must pass");
@@ -4763,10 +5490,7 @@ function evidenceClean(dir) {
     });
 }
 function critiqueClean(dir) {
-    // Phase 4c: read from trust.bundle (sole verification artifact); fall back to critique.json for
-    // legacy (pre-bundle-era) sessions — unrelated to origin stamping. When a trust.bundle IS
-    // present, every claim must be stamped (requireStampedClaim); no claimType-derivation fallback
-    // for an unstamped claim (#268/#344).
+    // trust.bundle is the sole critique artifact. Legacy critique.json must not influence gates.
     const bundle = loadJson(path.join(dir, "trust.bundle"));
     if (Array.isArray(bundle.claims)) {
         for (const c of bundle.claims)
@@ -4781,14 +5505,11 @@ function critiqueClean(dir) {
         });
         if (critiqueClaims.length === 0)
             return false; // no critique written yet
-        return critiqueClaims.every((c) => {
-            const v = String(c.value || "");
-            return v !== "fail" && c.status !== "disputed" && c.status !== "rejected";
-        });
+        return critiquesFromBundle(dir)
+            .filter((critique) => !critique.superseded_by)
+            .every((critique) => critiqueIsCleanAndCurrent(dir, critique));
     }
-    // Legacy fallback: critique.json
-    const c = loadJson(path.join(dir, "critique.json"), {});
-    return c.status === "pass" && Array.isArray(c.critiques) && c.critiques.every((x) => x.verdict !== "fail" && (!Array.isArray(x.findings) || x.findings.every((f) => f.status !== "open" && (f.file_refs === undefined || Array.isArray(f.file_refs)))));
+    return false;
 }
 function assertExistingLearningValid(dir) {
     const file = path.join(dir, "learning.json");
@@ -4846,8 +5567,7 @@ async function dogfoodPass(p) {
                 die(opt(p, "release-decision") ? "requires clean critique" : "requires clean critique before recording pass evidence");
             if (!opt(p, "critique-id") && !critiqueClean(dir))
                 die("requires passing critique");
-            // Phase 4c: if existing state has a dirty critique (in bundle or legacy critique.json), block even when adding a new critique-id.
-            if (!critiqueClean(dir) && (fs.existsSync(path.join(dir, "trust.bundle")) || fs.existsSync(path.join(dir, "critique.json"))))
+            if (!critiqueClean(dir) && fs.existsSync(path.join(dir, "trust.bundle")))
                 die(opt(p, "release-decision") ? "requires clean critique" : "requires clean critique before recording pass evidence");
         }
     }
@@ -5105,7 +5825,7 @@ async function gateReview(p) {
     // Locate trust.bundle — required per SKILL.md contract
     const bundlePath = path.join(dir, "trust.bundle");
     if (!fs.existsSync(bundlePath)) {
-        process.stderr.write(`[gate-review] trust.bundle absent at ${bundlePath} — NOT_VERIFIED. Build ADR 0010 Phase 1 first.\n`);
+        process.stderr.write(`[gate-review] trust.bundle absent at ${bundlePath} — NOT_VERIFIED. Record the required trust bundle before running gate review.\n`);
         return 1;
     }
     // Load Surface (ESM, fail-open)
@@ -5396,7 +6116,7 @@ function loadLivenessReadHelper() {
 // init-plan claims the work-item; advance-state heartbeats (or releases on terminal),
 // so the workflow lifecycle itself maintains the liveness claim — no manual liveness calls.
 // Additive + fail-open: a liveness-emit failure never affects the workflow command.
-export const LIVENESS_TERMINAL = new Set(["delivered", "accepted", "archived"]);
+export const LIVENESS_TERMINAL = new Set(["delivered", "canceled", "accepted", "archived"]);
 /**
  * Delegate to the shared pure-CJS resolver (scripts/hooks/lib/actor-identity.js), mirroring the
  * createRequire pattern used by readLivenessEvents() above. Deliberately NO inline duplicate
@@ -5840,8 +6560,11 @@ Available claim ids:
     return 0;
 }
 // ─────────────────────────────────────────────────────────────────────────────
-async function main() {
-    const _rawArgv = process.argv.slice(2);
+export function mainFromPublicWorkflow(argv) {
+    return main(argv, PUBLIC_WORKFLOW_AUTHORITY);
+}
+export async function main(argv = process.argv.slice(2), authority) {
+    const _rawArgv = argv;
     // #380: `record-check <dir> -- <command...>` — argv after the FIRST literal `--` token is the
     // command to execute verbatim (never option-parsed: a command like `npm test -- --watch`
     // legitimately contains its OWN `--`, so only the record-check dispatcher's own separator, the
@@ -5882,7 +6605,7 @@ async function main() {
         : p.command === "record-agent-event" ? explicitArtifactRoot(p) : p.command === "claim" ? (p.positional[1] ? path.resolve(p.positional[1]) : "") : p.command === "resolve-slug" ? "" : (isLivenessWhoami || isLivenessVerdict) ? "" : p.positional[0] ? artifactDirFrom(p.positional[0]) : "";
     return withLock(lockRoot, ["ensure-session", "record-agent-event", "dogfood-pass"].includes(p.command), p.command, () => {
         switch (p.command) {
-            case "ensure-session": return ensureSession(p);
+            case "ensure-session": return ensureSession(p, authority === PUBLIC_WORKFLOW_AUTHORITY);
             case "current": return current(p);
             case "record-agent-event": return recordAgentEvent(p);
             case "init-plan": return initPlan(p);
@@ -5927,5 +6650,8 @@ catch {
     return process.argv[1];
 } })();
 if (_selfRealPath === _argv1RealPath) {
+    if (path.basename(process.argv[1] ?? "") === "flow-agents-workflow-sidecar") {
+        process.stderr.write("flow-agents-workflow-sidecar is deprecated; use `flow-agents workflow` or an explicitly pinned `npx @kontourai/flow-agents@<version> workflow` command.\n");
+    }
     main().then((code) => process.exit(code)).catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); });
 }