@kontourai/flow-agents 3.5.0 → 3.6.0

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

@@ -3,17 +3,31 @@ import assert from "node:assert/strict";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { generateKeyPairSync, sign } from "node:crypto";
 
 import { FLOW_RUN_EVIDENCE_MANIFEST_PATH, runDir } from "@kontourai/flow";
 import {
+  archiveBuilderFlowSession,
+  cancelBuilderFlowSession,
+  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";
 
 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 +47,10 @@ 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" }) }],
+  });
   return { projectRoot, artifactRoot, sessionDir, slug };
 }
 
@@ -45,6 +63,104 @@ 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;
 }
@@ -152,7 +268,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 +291,282 @@ 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("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([
+    "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 });
@@ -253,6 +648,7 @@ test("failed verification projects Flow-owned route-back attempt and budget", as
 
 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" })],
@@ -297,6 +693,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 () => {

package/src/cli/builder-run.ts

@@ -1,36 +1,87 @@
 import { flagString, parseArgs } from "../lib/args.js";
-import { recoverBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
+import {
+  cancelBuilderFlowSession,
+  archiveBuilderFlowSession,
+  pauseBuilderFlowSession,
+  recoverBuilderFlowSession,
+  releaseBuilderFlowAssignment,
+  resumeBuilderFlowSession,
+  startBuilderFlowSession,
+  syncBuilderFlowSession,
+} from "../builder-flow-runtime.js";
+
+const USAGE = "Usage: flow-agents builder-run <start|sync|recover|pause|resume|cancel|release-assignment|archive> --session-dir <path> [--reason <text> | --authorization-file <path>]";
 
 export async function main(argv: string[]): Promise<number> {
   const parsed = parseArgs(argv);
   const action = parsed.positionals[0];
   const sessionDir = flagString(parsed.flags, "session-dir");
+  const authorizationFile = flagString(parsed.flags, "authorization-file");
+  const reason = flagString(parsed.flags, "reason");
   const validRecoveryArguments = parsed.positionals.length === 1
     && Object.keys(parsed.flags).length === 1
     && typeof parsed.flags["session-dir"] === "string";
   if (action === "recover" && !validRecoveryArguments) {
-    console.error("Usage: flow-agents builder-run <start|sync|recover> --session-dir <path>");
+    console.error(USAGE);
     return 64;
   }
   if (!sessionDir) {
     console.error("builder-run requires --session-dir .kontourai/flow-agents/<slug>");
     return 64;
   }
-  if (action !== "start" && action !== "sync" && action !== "recover") {
-    console.error("Usage: flow-agents builder-run <start|sync|recover> --session-dir <path>");
+  if (!action || !["start", "sync", "recover", "pause", "resume", "cancel", "release-assignment", "archive"].includes(action)) {
+    console.error(USAGE);
+    return 64;
+  }
+  const agentLifecycle = action === "pause" || action === "resume" || action === "release-assignment";
+  const authorizedLifecycle = action === "cancel" || action === "archive";
+  const lifecycle = agentLifecycle || authorizedLifecycle;
+  const allowedLifecycleFlag = (name: string) => name === "session-dir" || (agentLifecycle ? name === "reason" : name === "authorization-file");
+  if (lifecycle && (parsed.positionals.length !== 1 || Object.keys(parsed.flags).some((name) => !allowedLifecycleFlag(name)))) {
+    console.error(USAGE);
+    return 64;
+  }
+  if (agentLifecycle && !reason) {
+    console.error(`builder-run ${action} requires --reason <text>`);
+    return 64;
+  }
+  if (authorizedLifecycle && !authorizationFile) {
+    console.error(`builder-run ${action} requires a signed --authorization-file <path>`);
+    return 64;
+  }
+  if (!lifecycle && (authorizationFile || reason)) {
+    console.error(USAGE);
     return 64;
   }
   const result = action === "start"
     ? await startBuilderFlowSession({ sessionDir })
     : action === "sync"
       ? await syncBuilderFlowSession({ sessionDir })
-      : await recoverBuilderFlowSession({ sessionDir });
+      : action === "recover"
+        ? await recoverBuilderFlowSession({ sessionDir })
+        : action === "pause"
+          ? await pauseBuilderFlowSession({ sessionDir, reason: reason! })
+          : action === "resume"
+            ? await resumeBuilderFlowSession({ sessionDir, reason: reason! })
+            : action === "cancel"
+              ? await cancelBuilderFlowSession({ sessionDir, authorizationFile: authorizationFile! })
+              : action === "release-assignment"
+                ? await releaseBuilderFlowAssignment({ sessionDir, reason: reason! })
+                : await archiveBuilderFlowSession({ sessionDir, authorizationFile: authorizationFile! });
   console.log(JSON.stringify({
     run_id: result.run.runId,
     definition_id: result.run.definitionId,
     current_step: result.run.state.current_step,
     status: result.run.state.status,
     attached: result.attached,
+    ...(action === "cancel" ? {
+      assignment_released: "assignmentReleased" in result ? result.assignmentReleased : false,
+      idempotent: "idempotent" in result ? result.idempotent : false,
+    } : action === "release-assignment" ? {
+      assignment_released: "assignmentReleased" in result ? result.assignmentReleased : false,
+    } : action === "archive" ? {
+      archive_dir: "archiveDir" in result ? result.archiveDir : null,
+    } : {}),
     next_action: result.projection.next_action,
   }));
   return 0;

package/src/cli/workflow-artifact-cleanup-audit.ts

@@ -264,6 +264,9 @@ function classifyWorkflow(slug: string, workflowPath: string): AuditItem {
   if (status === "verified" && nextStatus === "done") {
     return { ...base, classification: "cleanup_candidate", reasons: ["verified workflow has next_action.status done"] };
   }
+  if (status === "canceled" && phase === "done") {
+    return { ...base, classification: "terminal_done", reasons: ["canceled workflow retains its artifacts without requiring delivery promotion"] };
+  }
   if (["delivered", "accepted", "archived"].includes(status) && phase === "done") {
     if (status !== "archived" && !hasPromotionClaim(workflowPath)) {
       return { ...base, classification: "cleanup_candidate", reasons: [`${status} workflow reached phase done without a promotion claim; ${PROMOTE_REMEDY}`] };

package/src/cli/workflow-sidecar.ts

@@ -10,6 +10,8 @@ import { fileURLToPath } from "node:url";
 import { resolveActiveFlowStep, resolveAllFlowGateExpects, resolveFlowFilePath, resolvePhaseMap, resolveRouteBackPolicy, type ActiveFlowStep } from "../lib/flow-resolver.js";
 import { defaultArtifactRootForRead, flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
 import { ensureSafeDirectory } from "../lib/fs.js";
+import { flowAgentsPackageVersion } from "../lib/package-version.js";
+import { pinnedFlowAgentsCommand } from "../lib/pinned-cli-command.js";
 import { startBuilderFlowSession, syncBuilderFlowSessionIfPresent } 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
@@ -19,11 +21,12 @@ import { assignmentFilePath, computeEffectiveState, performLocalClaim, performLo
 
 type AnyObj = Record<string, any>;
 
-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";
 
 function now(): string { return new Date().toISOString().replace(/\.\d{3}Z$/, "Z"); }
 function read(file: string): string { return fs.readFileSync(file, "utf8"); }
@@ -1678,6 +1681,11 @@ function currentDir(root: string, actorKey?: string): string | null {
   }
   return dir;
 }
+
+export function currentWorkflowSessionDir(root: string): string | null {
+  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
@@ -2096,13 +2104,24 @@ async function ensureSession(p: ReturnType<typeof parseArgs>): Promise<number> {
     // 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", "builder.build",
+      "--work-item", workItem.ref,
+      ...(workItem.ref === `local:${slug}` ? ["--task-slug", slug] : []),
+      "--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: string | AnyObj = entry.flowId
       ? entry.flowId === "builder.build"
         ? {
@@ -5421,7 +5440,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
@@ -5889,8 +5908,8 @@ Available claim ids:
 // ─────────────────────────────────────────────────────────────────────────────
 
 
-async function main(): Promise<number> {
-  const _rawArgv = process.argv.slice(2);
+export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+  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
@@ -5965,5 +5984,8 @@ async function main(): Promise<number> {
 const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
 const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } 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); });
 }