@kontourai/flow-agents 3.5.0 → 3.7.0

package/src/cli/builder-flow-runtime.test.mjs

@@ -3,17 +3,33 @@ import assert from "node:assert/strict";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { createHash, generateKeyPairSync, sign } from "node:crypto";
 
 import { FLOW_RUN_EVIDENCE_MANIFEST_PATH, runDir } from "@kontourai/flow";
 import {
+  archiveBuilderFlowSession,
+  cancelBuilderFlowSession,
+  captureReviewWorkspaceSnapshot,
+  pauseBuilderFlowSession,
   recoverBuilderFlowSession,
+  releaseBuilderFlowAssignment,
+  resumeBuilderFlowSession,
   startBuilderFlowSession,
   syncBuilderFlowSession,
 } from "../../build/src/builder-flow-runtime.js";
+import { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization, recordAuthorizationConsumed } from "../../build/src/builder-lifecycle-authority.js";
+import { cancelBuilderBuildRun } from "../../build/src/builder-flow-run-adapter.js";
+import { performLocalClaim, readLocalAssignmentStatus, resolveCurrentAssignmentActor } from "../../build/src/cli/assignment-provider.js";
 import { main as builderRunMain } from "../../build/src/cli/builder-run.js";
+import { inferExecutedTestCount } from "../../build/src/cli/workflow-sidecar.js";
 
 const SUBJECT = "local:work-item/runtime-projection";
 const NOW = "2026-07-09T20:00:00.000Z";
+const PACKAGE_VERSION = JSON.parse(fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+const ACTOR = { runtime: "codex", session_id: "runtime-projection", host: "test-host", human: null };
+const ACTOR_KEY = "codex:runtime-projection:test-host";
+const AUTHORITY_KEY_ID = "runtime-test";
+const AUTHORITY_KEYS = generateKeyPairSync("ed25519");
 
 function makeSession(slug = "runtime-projection") {
   const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-builder-runtime-"));
@@ -33,6 +49,13 @@ function makeSession(slug = "runtime-projection") {
     artifact_dir: `.kontourai/flow-agents/${slug}`,
     updated_at: NOW,
   });
+  writeJson(path.join(projectRoot, ".flow-agents", "lifecycle-authority-keys.json"), {
+    schema_version: "1.0",
+    keys: [{ id: AUTHORITY_KEY_ID, algorithm: "ed25519", public_key_pem: AUTHORITY_KEYS.publicKey.export({ type: "spki", format: "pem" }) }],
+  });
+  fs.mkdirSync(path.join(projectRoot, "review-target"), { recursive: true });
+  fs.writeFileSync(path.join(projectRoot, "review-target", "implementation.txt"), "reviewed implementation\n");
+  fs.writeFileSync(path.join(projectRoot, "review-target", "delivery.md"), "reviewed delivery artifact\n");
   return { projectRoot, artifactRoot, sessionDir, slug };
 }
 
@@ -41,10 +64,117 @@ function writeJson(file, value) {
   fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+test("shell output cannot spoof an executed-test count", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-test-count-"));
+  fs.mkdirSync(path.join(root, "checks"), { recursive: true });
+  fs.writeFileSync(path.join(root, "checks", "fake-test.sh"), "#!/bin/sh\nset -e\nprintf '1 passed\\n'\n");
+  fs.writeFileSync(path.join(root, "checks", "real-test.sh"), "#!/bin/sh\nset -e\ntest -f checks/real-test.sh\n");
+  assert.equal(inferExecutedTestCount("sh checks/fake-test.sh", root, "1 passed\n"), 0);
+  assert.equal(inferExecutedTestCount("sh checks/real-test.sh", root, "1..1\nok 1 - file exists\n"), 1);
+});
+
 function readJson(file) {
   return JSON.parse(fs.readFileSync(file, "utf8"));
 }
 
+function consumedAuthorizationRecords(session) {
+  const directory = path.join(session.artifactRoot, "lifecycle-authority", "consumed");
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory).sort().map((name) => readJson(path.join(directory, name)));
+}
+
+function claimSessionAssignment(session) {
+  performLocalClaim(session.artifactRoot, session.slug, ACTOR, {
+    ttlSeconds: 1800,
+    actorKey: ACTOR_KEY,
+    branch: `agent/${session.slug}`,
+    artifactDir: session.sessionDir,
+    workItemRef: SUBJECT,
+    reason: "test",
+  });
+}
+
+function claimAmbientSessionAssignment(session) {
+  const ambient = resolveCurrentAssignmentActor();
+  performLocalClaim(session.artifactRoot, session.slug, ambient.actor, {
+    ttlSeconds: 1800,
+    actorKey: ambient.actorKey,
+    branch: `agent/${session.slug}`,
+    artifactDir: session.sessionDir,
+    workItemRef: SUBJECT,
+    reason: "test",
+  });
+  return ambient;
+}
+
+function lifecycleAuthorization(session, operation, name, overrides = {}) {
+  const file = path.join(session.projectRoot, `${name}.authorization.json`);
+  const unsigned = {
+    schema_version: "1.0",
+    operation,
+    run_id: session.slug,
+    subject: SUBJECT,
+    assignment_actor_key: ACTOR_KEY,
+    assignment_actor: ACTOR,
+    nonce: `${session.slug}:${name}`,
+    expires_at: "2026-07-09T21:00:00.000Z",
+    request: {
+      reason: `${name} requested by fixture`,
+      authority: {
+        kind: "user_request",
+        actor: "fixture-user",
+        request_ref: `fixture://request/${name}`,
+        requested_at: NOW,
+      },
+    },
+    ...overrides,
+  };
+  const value = {
+    ...unsigned,
+    signature: {
+      algorithm: "ed25519",
+      key_id: AUTHORITY_KEY_ID,
+      value: sign(null, Buffer.from(builderLifecycleAuthorizationPayload(unsigned)), AUTHORITY_KEYS.privateKey).toString("base64"),
+    },
+  };
+  writeJson(file, value);
+  return file;
+}
+
+function liveLifecycleAuthorization(session, operation, name, overrides = {}) {
+  const requestedAt = new Date();
+  return lifecycleAuthorization(session, operation, name, {
+    expires_at: new Date(requestedAt.getTime() + 60 * 60_000).toISOString(),
+    request: {
+      reason: `${name} requested by fixture`,
+      authority: {
+        kind: "user_request",
+        actor: "fixture-user",
+        request_ref: `fixture://request/${name}`,
+        requested_at: requestedAt.toISOString(),
+      },
+    },
+    ...overrides,
+  });
+}
+
+function expiredLifecycleAuthorization(session, operation, name, overrides = {}) {
+  const requestedAt = new Date(Date.now() - 120_000);
+  return lifecycleAuthorization(session, operation, name, {
+    expires_at: new Date(Date.now() - 60_000).toISOString(),
+    request: {
+      reason: `${name} requested by fixture`,
+      authority: {
+        kind: "user_request",
+        actor: "fixture-user",
+        request_ref: `fixture://request/${name}`,
+        requested_at: requestedAt.toISOString(),
+      },
+    },
+    ...overrides,
+  });
+}
+
 function snapshotFile(file) {
   return fs.existsSync(file) ? fs.readFileSync(file).toString("base64") : null;
 }
@@ -84,7 +214,7 @@ async function assertRecoveryRejectsWithoutWrites(session, pattern) {
   assert.deepEqual(snapshotProjectionTargets(session), beforeProjection);
 }
 
-function bundleClaim({ expectation, claimType, subjectType, status = "pass", routeReason, subject = SUBJECT }) {
+function bundleClaim({ expectation, claimType, subjectType, status = "pass", routeReason, subject = SUBJECT, testCount = 1, timestamp = NOW }) {
   const claimId = `claim.${expectation}`;
   return {
     claim: {
@@ -96,6 +226,11 @@ function bundleClaim({ expectation, claimType, subjectType, status = "pass", rou
       value: status,
       metadata: {
         workflow_subject_ref: subject,
+        ...(expectation === "tests-evidence" ? {
+          recorded_by: "implementation-actor",
+          artifact_refs: [{ kind: "command", excerpt: "node --test src/cli/builder-flow-runtime.test.mjs", summary: "Runtime fixture assertion." }],
+          observed_commands: [{ command: "node --test src/cli/builder-flow-runtime.test.mjs", exit_code: 0, test_count: testCount, output_sha256: "0".repeat(64) }],
+        } : {}),
         gate_claim: {
           expectation_id: expectation,
           claim_type: claimType,
@@ -103,8 +238,8 @@ function bundleClaim({ expectation, claimType, subjectType, status = "pass", rou
           ...(routeReason ? { route_reason: routeReason } : {}),
         },
       },
-      createdAt: NOW,
-      updatedAt: NOW,
+      createdAt: timestamp,
+      updatedAt: timestamp,
     },
     evidence: {
       id: `evidence.${expectation}`,
@@ -113,7 +248,7 @@ function bundleClaim({ expectation, claimType, subjectType, status = "pass", rou
       method: "attestation",
       sourceRef: "src/cli/builder-flow-runtime.test.mjs",
       excerptOrSummary: `${expectation} fixture`,
-      observedAt: NOW,
+      observedAt: timestamp,
       collectedBy: "flow-agents-test",
     },
     event: {
@@ -123,10 +258,47 @@ function bundleClaim({ expectation, claimType, subjectType, status = "pass", rou
       actor: "flow-agents-test",
       method: "attestation",
       evidenceIds: [`evidence.${expectation}`],
-      createdAt: NOW,
-      verifiedAt: NOW,
+      createdAt: timestamp,
+      verifiedAt: timestamp,
+    },
+  };
+}
+
+function verifiedTestsPrerequisites(session, timestamp = NOW) {
+  const reviewArtifact = path.join(session.projectRoot, "review-target", "delivery.md");
+  const implementation = path.join(session.projectRoot, "review-target", "implementation.txt");
+  const implementationFile = path.relative(session.projectRoot, implementation);
+  const implementationBytes = fs.readFileSync(implementation);
+  const implementationSha256 = createHash("sha256").update(implementationBytes).digest("hex");
+  const workspaceDigest = createHash("sha256")
+    .update("flow-agents:reviewed-files:v1\0")
+    .update(implementationFile).update("\0").update(implementationBytes).update("\0")
+    .digest("hex");
+  const critique = bundleClaim({ expectation: "clean-critique", claimType: "workflow.critique.review", subjectType: "workflow-critique", timestamp });
+  critique.claim.metadata = {
+    workflow_subject_ref: SUBJECT,
+    origin: "critique",
+    reviewer: "reviewer-actor",
+    findings: [],
+    lanes: [{ id: "code", status: "pass" }],
+    review_target: {
+      artifacts: [{ file: path.relative(session.projectRoot, reviewArtifact), sha256: createHash("sha256").update(fs.readFileSync(reviewArtifact)).digest("hex") }],
+      workspace_snapshot: {
+        version: 1,
+        kind: "reviewed-files",
+        algorithm: "sha256",
+        digest: workspaceDigest,
+        files: [{ file: implementationFile, sha256: implementationSha256 }],
+      },
     },
   };
+  const criterion = bundleClaim({ expectation: "verified-criterion", claimType: "workflow.acceptance.criterion", subjectType: "flow-step", timestamp });
+  criterion.claim.metadata = {
+    workflow_subject_ref: SUBJECT,
+    origin: "acceptance",
+    criterion: { id: "ac-runtime", status: "pass", evidence_refs: [{ kind: "command", excerpt: "node --test src/cli/builder-flow-runtime.test.mjs", summary: "Runtime fixture assertion." }] },
+  };
+  return [critique, criterion];
 }
 
 function writeBundle(sessionDir, entries) {
@@ -152,7 +324,10 @@ test("small-model client can start and advance from projected actions without ch
   assert.equal(started.run.state.current_step, "pull-work");
   assert.deepEqual(started.projection.next_action.skills, ["pull-work"]);
   assert.deepEqual(started.projection.next_action.operations, []);
-  assert.equal(started.projection.next_action.command, `flow-agents builder-run sync --session-dir .kontourai/flow-agents/${session.slug}`);
+  assert.match(started.projection.next_action.command, /^sh -c /);
+  assert.match(started.projection.next_action.command, /--prefix "\$root"/);
+  assert.ok(started.projection.next_action.command.includes(`'@kontourai/flow-agents@${PACKAGE_VERSION}'`));
+  assert.ok(started.projection.next_action.command.includes(`'workflow' 'status' '--session-dir' '.kontourai/flow-agents/${session.slug}' '--json'`));
   assert.ok(fs.existsSync(runDir(session.slug, session.projectRoot)));
   assert.ok(!fs.existsSync(path.join(session.projectRoot, ".flow", "runs")), "retired runtime path must not be created");
 
@@ -172,6 +347,331 @@ test("small-model client can start and advance from projected actions without ch
   assert.equal(duplicate.run.manifest.evidence.length, advanced.run.manifest.evidence.length);
 });
 
+test("sync attaches the staged trust.bundle bytes when the session bundle is replaced", async () => {
+  const session = makeSession("snapshot-attachment");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const originalEntries = [bundleClaim({ expectation: "selected-work", claimType: "builder.pull-work.selected", subjectType: "work-item" })];
+  writeBundle(session.sessionDir, originalEntries);
+  const bundleFile = path.join(session.sessionDir, "trust.bundle");
+  const originalDigest = createHash("sha256").update(fs.readFileSync(bundleFile)).digest("hex");
+  let replaceBundle;
+  const replaced = new Promise((resolve) => { replaceBundle = resolve; });
+  const watcher = fs.watch(session.sessionDir, (_event, filename) => {
+    if (String(filename) !== ".trust-bundle-snapshots") return;
+    fs.writeFileSync(bundleFile, "{\"claims\":[]}");
+    replaceBundle();
+  });
+  try {
+    const syncing = syncBuilderFlowSession({ sessionDir: session.sessionDir });
+    await Promise.race([
+      replaced,
+      new Promise((_, reject) => setTimeout(() => reject(new Error("trust.bundle snapshot was not staged")), 2_000)),
+    ]);
+    const synced = await syncing;
+    assert.equal(synced.attached, true);
+  } finally {
+    watcher.close();
+  }
+  const manifest = readJson(path.join(runDir(session.slug, session.projectRoot), FLOW_RUN_EVIDENCE_MANIFEST_PATH));
+  assert.equal(manifest.evidence.at(-1).sha256, originalDigest);
+  assert.equal(fs.existsSync(path.join(session.sessionDir, ".trust-bundle-snapshots")), false);
+});
+
+test("start rejects a requested Builder flow that differs from the existing run before projection mutation", async (t) => {
+  for (const [existingFlowId, requestedFlowId] of [["builder.shape", "builder.build"], ["builder.build", "builder.shape"]]) {
+    await t.test(`${existingFlowId} cannot resume as ${requestedFlowId}`, async () => {
+      const session = makeSession(`flow-mismatch-${existingFlowId.replace('.', '-')}`);
+      await startBuilderFlowSession({ sessionDir: session.sessionDir, flowId: existingFlowId });
+      const beforeFlow = snapshotTree(runDir(session.slug, session.projectRoot));
+      const beforeProjection = snapshotProjectionTargets(session);
+      await assert.rejects(
+        () => startBuilderFlowSession({ sessionDir: session.sessionDir, flowId: requestedFlowId }),
+        new RegExp(`requested ${requestedFlowId} does not match the existing ${existingFlowId} run`),
+      );
+      assert.deepEqual(snapshotTree(runDir(session.slug, session.projectRoot)), beforeFlow);
+      assert.deepEqual(snapshotProjectionTargets(session), beforeProjection);
+    });
+  }
+});
+
+test("pause and resume preserve the current Flow step and active assignment", async () => {
+  const session = makeSession("lifecycle-pause-resume");
+  claimAmbientSessionAssignment(session);
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const before = readJson(path.join(runDir(session.slug, session.projectRoot), "state.json"));
+
+  const paused = await pauseBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    reason: "fixture pause",
+  });
+  assert.equal(paused.run.state.status, "paused");
+  assert.equal(paused.run.state.current_step, before.current_step);
+  assert.deepEqual(paused.run.state.transitions, before.transitions);
+  assert.equal(paused.projection.status, "blocked");
+  assert.equal(readLocalAssignmentStatus(session.artifactRoot, session.slug).record.status, "claimed");
+
+  const resumed = await resumeBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    reason: "fixture resume",
+  });
+  assert.equal(resumed.run.state.status, "active");
+  assert.equal(resumed.run.state.current_step, before.current_step);
+  assert.deepEqual(resumed.run.state.transitions, before.transitions);
+  assert.equal(readLocalAssignmentStatus(session.artifactRoot, session.slug).record.status, "claimed");
+});
+
+test("authorized cancellation is canonical, terminal, and releases the assignment exactly once", async () => {
+  const session = makeSession("lifecycle-cancel");
+  claimSessionAssignment(session);
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const authorizationFile = liveLifecycleAuthorization(session, "cancel", "cancel");
+
+  const canceled = await cancelBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    authorizationFile,
+  });
+  assert.equal(canceled.run.state.status, "canceled");
+  assert.equal(canceled.projection.status, "canceled");
+  assert.equal(canceled.assignmentReleased, true);
+  assert.equal(canceled.idempotent, false);
+  const assignmentFile = path.join(session.artifactRoot, "assignment", `${session.slug}.json`);
+  assert.equal(readJson(assignmentFile).status, "released");
+  const firstAudit = readJson(assignmentFile).audit_trail;
+
+  await assert.rejects(() => cancelBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    authorizationFile,
+  }), /nonce has already been consumed/);
+  assert.deepEqual(readJson(assignmentFile).audit_trail, firstAudit);
+});
+
+test("assignment release is independent of Flow lifecycle", async () => {
+  const session = makeSession("lifecycle-release-assignment");
+  claimAmbientSessionAssignment(session);
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const beforeFlow = snapshotTree(runDir(session.slug, session.projectRoot));
+
+  const released = await releaseBuilderFlowAssignment({
+    sessionDir: session.sessionDir,
+    reason: "fixture assignment release",
+  });
+
+  assert.equal(released.assignmentReleased, true);
+  assert.deepEqual(snapshotTree(runDir(session.slug, session.projectRoot)), beforeFlow);
+  assert.equal(readJson(path.join(session.artifactRoot, "assignment", `${session.slug}.json`)).status, "released");
+});
+
+test("archive rejects active runs and retains canceled Flow and session artifacts", async () => {
+  const session = makeSession("lifecycle-archive");
+  claimSessionAssignment(session);
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const cancelAuthorization = liveLifecycleAuthorization(session, "cancel", "archive-cancel");
+  const authorizationFile = liveLifecycleAuthorization(session, "archive", "archive");
+  const beforeReject = snapshotTree(session.sessionDir);
+  await assert.rejects(() => archiveBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    authorizationFile,
+  }), /must be completed or canceled/);
+  assert.deepEqual(snapshotTree(session.sessionDir), beforeReject);
+
+  await cancelBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    authorizationFile: cancelAuthorization,
+  });
+  const beforeFlow = snapshotTree(runDir(session.slug, session.projectRoot));
+  const beforeSession = snapshotTree(session.sessionDir);
+  const archived = await archiveBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    authorizationFile,
+  });
+
+  assert.equal(archived.archiveDir, path.join(session.artifactRoot, "archive", session.slug));
+  assert.equal(fs.existsSync(session.sessionDir), false);
+  assert.equal(readJson(path.join(archived.archiveDir, "state.json")).status, "archived");
+  assert.deepEqual(snapshotTree(runDir(session.slug, session.projectRoot)), beforeFlow);
+  const archivedFiles = snapshotTree(archived.archiveDir).map(([name]) => name);
+  for (const [name] of beforeSession) assert.ok(archivedFiles.includes(name), `archive retained ${name}`);
+  assert.deepEqual(consumedAuthorizationRecords(session).map((record) => record.operation).sort(), ["archive", "cancel"]);
+});
+
+test("archive rejects a symlinked archive root without moving the session", async () => {
+  const session = makeSession("lifecycle-archive-symlink");
+  claimSessionAssignment(session);
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const cancelAuthorization = liveLifecycleAuthorization(session, "cancel", "archive-symlink-cancel");
+  const authorizationFile = liveLifecycleAuthorization(session, "archive", "archive-symlink");
+  await cancelBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    authorizationFile: cancelAuthorization,
+  });
+  const outside = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-archive-outside-"));
+  fs.symlinkSync(outside, path.join(session.artifactRoot, "archive"), "dir");
+  const beforeSession = snapshotTree(session.sessionDir);
+
+  await assert.rejects(() => archiveBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    authorizationFile,
+  }), /archive root.*symbolic link/);
+
+  assert.deepEqual(snapshotTree(session.sessionDir), beforeSession);
+  assert.deepEqual(fs.readdirSync(outside), []);
+});
+
+test("archive retries the exact consumed authorization after an interrupted prepared move", async () => {
+  const session = makeSession("lifecycle-archive-recovery");
+  claimSessionAssignment(session);
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  await cancelBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    authorizationFile: liveLifecycleAuthorization(session, "cancel", "archive-recovery-cancel"),
+  });
+  const authorizationFile = expiredLifecycleAuthorization(session, "archive", "archive-recovery");
+  const rawAuthorization = readJson(authorizationFile);
+  const authorization = loadBuilderLifecycleAuthorization(authorizationFile, {
+    projectRoot: session.projectRoot,
+    operation: "archive",
+    runId: session.slug,
+    subject: SUBJECT,
+    actorKey: ACTOR_KEY,
+    now: new Date(Date.parse(rawAuthorization.request.authority.requested_at) + 30_000).toISOString(),
+  });
+  const preparedState = readJson(path.join(session.sessionDir, "state.json"));
+  preparedState.status = "archived";
+  preparedState.phase = "done";
+  preparedState.next_action = { status: "done", summary: "Builder session archived; canonical Flow artifacts remain retained." };
+  writeJson(path.join(session.sessionDir, "state.json"), preparedState);
+  recordAuthorizationConsumed(session.artifactRoot, authorization);
+
+  const conflictingAuthorization = liveLifecycleAuthorization(session, "archive", "archive-recovery-conflict", {
+    nonce: authorization.nonce,
+  });
+  await assert.rejects(
+    () => archiveBuilderFlowSession({ sessionDir: session.sessionDir, authorizationFile: conflictingAuthorization }),
+    /does not match its integrity key/,
+  );
+  assert.equal(fs.existsSync(session.sessionDir), true);
+
+  const recovered = await archiveBuilderFlowSession({ sessionDir: session.sessionDir, authorizationFile });
+  assert.equal(fs.existsSync(session.sessionDir), false);
+  assert.equal(readJson(path.join(recovered.archiveDir, "state.json")).status, "archived");
+  assert.equal(consumedAuthorizationRecords(session).length, 2);
+});
+
+test("mismatched and expired cancellation authority fail before Flow or sidecar mutation", async (t) => {
+  for (const [name, overrides, pattern] of [
+    ["wrong-run", { run_id: "another-run" }, /run_id does not match/],
+    ["wrong-subject", { subject: "local:other" }, /subject does not match/],
+    ["wrong-actor", { assignment_actor_key: "another-actor" }, /assignment_actor_key does not match/],
+    ["wrong-actor-struct", { assignment_actor: { ...ACTOR, session_id: "another-session" } }, /assignment_actor.*active assignment holder/],
+    ["wrong-operation", { operation: "archive" }, /operation does not match/],
+    ["expired", {}, /expired/],
+  ]) {
+    await t.test(name, async () => {
+      const session = makeSession(`lifecycle-reject-${name}`);
+      claimSessionAssignment(session);
+      await startBuilderFlowSession({ sessionDir: session.sessionDir });
+      const beforeFlow = snapshotTree(runDir(session.slug, session.projectRoot));
+      const beforeProjection = snapshotProjectionTargets(session);
+      const beforeAssignment = snapshotFile(path.join(session.artifactRoot, "assignment", `${session.slug}.json`));
+      await assert.rejects(() => cancelBuilderFlowSession({
+        sessionDir: session.sessionDir,
+        authorizationFile: name === "expired"
+          ? expiredLifecycleAuthorization(session, "cancel", name, overrides)
+          : liveLifecycleAuthorization(session, "cancel", name, overrides),
+      }), pattern);
+      assert.deepEqual(snapshotTree(runDir(session.slug, session.projectRoot)), beforeFlow);
+      assert.deepEqual(snapshotProjectionTargets(session), beforeProjection);
+      assert.equal(snapshotFile(path.join(session.artifactRoot, "assignment", `${session.slug}.json`)), beforeAssignment);
+    });
+  }
+});
+
+test("conflicting cancellation request replay is rejected without a second transition or release", async () => {
+  const session = makeSession("lifecycle-conflicting-replay");
+  claimSessionAssignment(session);
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  await cancelBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    authorizationFile: liveLifecycleAuthorization(session, "cancel", "cancel-original"),
+  });
+  const beforeFlow = snapshotTree(runDir(session.slug, session.projectRoot));
+  const assignmentFile = path.join(session.artifactRoot, "assignment", `${session.slug}.json`);
+  const beforeAssignment = snapshotFile(assignmentFile);
+  await assert.rejects(() => cancelBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    authorizationFile: liveLifecycleAuthorization(session, "cancel", "cancel-conflict"),
+  }), /does not match the canonical cancellation/);
+  assert.deepEqual(snapshotTree(runDir(session.slug, session.projectRoot)), beforeFlow);
+  assert.equal(snapshotFile(assignmentFile), beforeAssignment);
+});
+
+test("tampered or unsigned cancellation authority fails before mutation", async () => {
+  const session = makeSession("lifecycle-signature-reject");
+  claimSessionAssignment(session);
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const authorizationFile = liveLifecycleAuthorization(session, "cancel", "signature-reject");
+  const tampered = readJson(authorizationFile);
+  tampered.request.reason = "agent-authored replacement";
+  writeJson(authorizationFile, tampered);
+  const beforeFlow = snapshotTree(runDir(session.slug, session.projectRoot));
+  const beforeAssignment = snapshotFile(path.join(session.artifactRoot, "assignment", `${session.slug}.json`));
+
+  await assert.rejects(() => cancelBuilderFlowSession({ sessionDir: session.sessionDir, authorizationFile }), /signature is invalid/);
+  assert.deepEqual(snapshotTree(runDir(session.slug, session.projectRoot)), beforeFlow);
+  assert.equal(snapshotFile(path.join(session.artifactRoot, "assignment", `${session.slug}.json`)), beforeAssignment);
+});
+
+test("expired authority can finish side effects for its matching canonical cancellation", async () => {
+  const session = makeSession("lifecycle-cancel-recovery");
+  claimSessionAssignment(session);
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const authorizationFile = expiredLifecycleAuthorization(session, "cancel", "cancel-recovery");
+  const authorization = readJson(authorizationFile);
+  await cancelBuilderBuildRun({
+    cwd: session.projectRoot,
+    runId: session.slug,
+    request: authorization.request,
+    at: new Date(Date.parse(authorization.expires_at) - 1_000).toISOString(),
+  });
+  assert.equal(readJson(path.join(runDir(session.slug, session.projectRoot), "state.json")).status, "canceled");
+  assert.equal(readJson(path.join(session.artifactRoot, "assignment", `${session.slug}.json`)).status, "claimed");
+  assert.deepEqual(consumedAuthorizationRecords(session), []);
+
+  const recovered = await cancelBuilderFlowSession({ sessionDir: session.sessionDir, authorizationFile });
+  assert.equal(recovered.idempotent, true);
+  assert.equal(recovered.assignmentReleased, true);
+  assert.equal(recovered.projection.status, "canceled");
+  assert.equal(consumedAuthorizationRecords(session).length, 1);
+});
+
+test("builder-run exposes lifecycle actions without caller-selected Flow identity", async () => {
+  const session = makeSession("lifecycle-cli");
+  const ambient = resolveCurrentAssignmentActor();
+  performLocalClaim(session.artifactRoot, session.slug, ambient.actor, { actorKey: ambient.actorKey, ttlSeconds: 1800, branch: `agent/${session.slug}`, artifactDir: session.sessionDir, workItemRef: SUBJECT, reason: "test" });
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  assert.equal(await builderRunMain(["start", "--session-dir", session.sessionDir]), 64);
+  assert.equal(await builderRunMain(["sync", "--session-dir", session.sessionDir]), 64);
+  assert.equal(await builderRunMain([
+    "pause", "--session-dir", session.sessionDir,
+    "--reason", "cli pause",
+  ]), 0);
+  assert.equal(await builderRunMain([
+    "resume", "--session-dir", session.sessionDir,
+    "--reason", "cli resume",
+  ]), 0);
+  const cliCancel = liveLifecycleAuthorization(session, "cancel", "cli-cancel", { assignment_actor_key: ambient.actorKey, assignment_actor: ambient.actor });
+  assert.equal(await builderRunMain([
+    "cancel", "--session-dir", session.sessionDir,
+    "--authorization-file", cliCancel,
+  ]), 0);
+  assert.equal(readJson(path.join(runDir(session.slug, session.projectRoot), "state.json")).status, "canceled");
+  assert.equal(await builderRunMain([
+    "cancel", "--session-dir", session.sessionDir,
+    "--authorization-file", liveLifecycleAuthorization(session, "cancel", "cli-clock-override", { assignment_actor_key: ambient.actorKey, assignment_actor: ambient.actor }),
+    "--now", "2020-01-01T00:00:00.000Z",
+  ]), 64);
+});
+
 test("automatic start refuses a slug-bound run for another Work Item without mutation", async () => {
   const session = makeSession("start-subject-mismatch");
   await startBuilderFlowSession({ sessionDir: session.sessionDir });
@@ -249,10 +749,92 @@ test("failed verification projects Flow-owned route-back attempt and budget", as
   assert.equal(routed.projection.flow_run.route_back_max_attempts, 3);
   assert.match(routed.projection.next_action.summary, /Route-back history: attempt 1\/3 returned to `execute` for `implementation_defect`/);
   assert.deepEqual(routed.projection.next_action.skills, ["execute-plan"]);
+
+  const reentered = await writeAndSync(session, [bundleClaim({
+    expectation: "implementation-scope",
+    claimType: "builder.execute.scope",
+    subjectType: "change",
+    timestamp: new Date().toISOString(),
+  })]);
+  assert.equal(reentered.run.state.current_step, "verify");
+  const correctedAt = new Date(Date.parse(reentered.run.state.transitions.at(-1).at) + 1).toISOString();
+  const corrected = await writeAndSync(session, [
+    bundleClaim({ expectation: "tests-evidence", claimType: "builder.verify.tests", subjectType: "flow-step", timestamp: correctedAt }),
+    ...verifiedTestsPrerequisites(session, correctedAt),
+  ]);
+  assert.equal(corrected.run.state.current_step, "merge-ready");
+  const verifyEvidence = corrected.run.manifest.evidence.filter((entry) => entry.gate_id === "verify-gate");
+  assert.equal(verifyEvidence.length, 2);
+  assert.equal(verifyEvidence[0].superseded_by, verifyEvidence[1].id);
+});
+
+test("passing tests-evidence rejects a critique whose reviewed artifact changed", async () => {
+  const session = makeSession("stale-critique-artifact");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  await writeAndSync(session, [bundleClaim({ expectation: "selected-work", claimType: "builder.pull-work.selected", subjectType: "work-item" })]);
+  await writeAndSync(session, [
+    bundleClaim({ expectation: "pickup-probe-readiness", claimType: "builder.design-probe.pickup-readiness", subjectType: "work-item" }),
+    bundleClaim({ expectation: "probe-decisions-or-accepted-gaps", claimType: "builder.design-probe.decisions", subjectType: "decision" }),
+  ]);
+  await writeAndSync(session, [bundleClaim({ expectation: "implementation-plan", claimType: "builder.plan.implementation", subjectType: "artifact" })]);
+  await writeAndSync(session, [bundleClaim({ expectation: "implementation-scope", claimType: "builder.execute.scope", subjectType: "change" })]);
+  const prerequisites = verifiedTestsPrerequisites(session);
+  fs.writeFileSync(path.join(session.projectRoot, "review-target", "delivery.md"), "changed after review\n");
+  await assert.rejects(
+    () => writeAndSync(session, [bundleClaim({ expectation: "tests-evidence", claimType: "builder.verify.tests", subjectType: "flow-step" }), ...prerequisites]),
+    /review_target\.artifacts\.sha256.*does not match/,
+  );
+});
+
+test("passing tests-evidence rejects a successful command that executed zero tests", async () => {
+  const session = makeSession("zero-test-evidence");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  await writeAndSync(session, [bundleClaim({ expectation: "selected-work", claimType: "builder.pull-work.selected", subjectType: "work-item" })]);
+  await writeAndSync(session, [
+    bundleClaim({ expectation: "pickup-probe-readiness", claimType: "builder.design-probe.pickup-readiness", subjectType: "work-item" }),
+    bundleClaim({ expectation: "probe-decisions-or-accepted-gaps", claimType: "builder.design-probe.decisions", subjectType: "decision" }),
+  ]);
+  await writeAndSync(session, [bundleClaim({ expectation: "implementation-plan", claimType: "builder.plan.implementation", subjectType: "artifact" })]);
+  await writeAndSync(session, [bundleClaim({ expectation: "implementation-scope", claimType: "builder.execute.scope", subjectType: "change" })]);
+  await assert.rejects(
+    () => writeAndSync(session, [
+      bundleClaim({ expectation: "tests-evidence", claimType: "builder.verify.tests", subjectType: "flow-step", testCount: 0 }),
+      ...verifiedTestsPrerequisites(session),
+    ]),
+    /positive executed-test count/,
+  );
+});
+
+test("passing tests-evidence rejects a critique after implementation source changed", async () => {
+  const session = makeSession("stale-critique-workspace");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  await writeAndSync(session, [bundleClaim({ expectation: "selected-work", claimType: "builder.pull-work.selected", subjectType: "work-item" })]);
+  await writeAndSync(session, [
+    bundleClaim({ expectation: "pickup-probe-readiness", claimType: "builder.design-probe.pickup-readiness", subjectType: "work-item" }),
+    bundleClaim({ expectation: "probe-decisions-or-accepted-gaps", claimType: "builder.design-probe.decisions", subjectType: "decision" }),
+  ]);
+  await writeAndSync(session, [bundleClaim({ expectation: "implementation-plan", claimType: "builder.plan.implementation", subjectType: "artifact" })]);
+  await writeAndSync(session, [bundleClaim({ expectation: "implementation-scope", claimType: "builder.execute.scope", subjectType: "change" })]);
+  const prerequisites = verifiedTestsPrerequisites(session);
+  fs.writeFileSync(path.join(session.projectRoot, "review-target", "implementation.txt"), "source changed after review\n");
+  await assert.rejects(
+    () => writeAndSync(session, [bundleClaim({ expectation: "tests-evidence", claimType: "builder.verify.tests", subjectType: "flow-step" }), ...prerequisites]),
+    /review_target\.workspace_snapshot\.digest.*does not match/,
+  );
+});
+
+test("workspace review fails closed when a Git worktree marker cannot be inspected", () => {
+  const session = makeSession("git-inspection-unavailable");
+  fs.mkdirSync(path.join(session.projectRoot, ".git"));
+  assert.throws(
+    () => captureReviewWorkspaceSnapshot(session.projectRoot, [{ file: "review-target/delivery.md", sha256: createHash("sha256").update("reviewed delivery\n").digest("hex") }]),
+    /could not inspect the Git worktree/,
+  );
 });
 
 test("verified sidecar claims drive the composed publish and learning prefix to completion", async () => {
   const session = makeSession("composed-completion");
+  claimSessionAssignment(session);
   await startBuilderFlowSession({ sessionDir: session.sessionDir });
   const steps = [
     [bundleClaim({ expectation: "selected-work", claimType: "builder.pull-work.selected", subjectType: "work-item" })],
@@ -262,7 +844,7 @@ test("verified sidecar claims drive the composed publish and learning prefix to
     ],
     [bundleClaim({ expectation: "implementation-plan", claimType: "builder.plan.implementation", subjectType: "artifact" })],
     [bundleClaim({ expectation: "implementation-scope", claimType: "builder.execute.scope", subjectType: "change" })],
-    [bundleClaim({ expectation: "tests-evidence", claimType: "builder.verify.tests", subjectType: "flow-step" })],
+    [bundleClaim({ expectation: "tests-evidence", claimType: "builder.verify.tests", subjectType: "flow-step" }), ...verifiedTestsPrerequisites(session)],
     [bundleClaim({ expectation: "merge-readiness", claimType: "builder.merge-ready.readiness", subjectType: "change" })],
   ];
   for (const entries of steps) await writeAndSync(session, entries);
@@ -297,6 +879,13 @@ test("verified sidecar claims drive the composed publish and learning prefix to
   assert.equal(recovered.projection.phase, "done");
   assert.deepEqual(recovered.projection.next_action, { status: "done", summary: "Canonical Flow run is complete." });
   assert.deepEqual(snapshotTree(flowDirectory), beforeFlow);
+
+  const archived = await archiveBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    authorizationFile: liveLifecycleAuthorization(session, "archive", "completed-archive"),
+  });
+  assert.equal(readJson(path.join(archived.archiveDir, "state.json")).status, "archived");
+  assert.deepEqual(snapshotTree(flowDirectory), beforeFlow);
 });
 
 test("recovery loads the slug-bound run, restores every matching projection, and preserves every Flow byte", async () => {