@kontourai/flow-agents 3.5.0 → 3.6.0

package/schemas/builder-lifecycle-authorization.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kontourai.dev/schemas/builder-lifecycle-authorization.schema.json",
+  "title": "Builder Lifecycle Authorization",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "operation", "run_id", "subject", "assignment_actor_key", "assignment_actor", "nonce", "expires_at", "request", "signature"],
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "operation": { "enum": ["cancel", "archive"] },
+    "run_id": { "type": "string", "minLength": 1 },
+    "subject": { "type": "string", "minLength": 1 },
+    "assignment_actor_key": { "type": "string", "minLength": 1 },
+    "assignment_actor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runtime", "session_id", "host", "human"],
+      "properties": {
+        "runtime": { "type": "string", "minLength": 1 },
+        "session_id": { "type": "string", "minLength": 1 },
+        "host": { "type": "string", "minLength": 1 },
+        "human": { "type": ["string", "null"] }
+      }
+    },
+    "nonce": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "expires_at": { "type": "string", "format": "date-time" },
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reason", "authority"],
+      "properties": {
+        "reason": { "type": "string", "minLength": 1 },
+        "authority": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "actor", "request_ref", "requested_at"],
+          "properties": {
+            "kind": { "enum": ["user_request", "operator_request"] },
+            "actor": { "type": "string", "minLength": 1 },
+            "request_ref": { "type": "string", "minLength": 1 },
+            "requested_at": { "type": "string", "format": "date-time" }
+          }
+        }
+      }
+    },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["algorithm", "key_id", "value"],
+      "properties": {
+        "algorithm": { "const": "ed25519" },
+        "key_id": { "type": "string", "minLength": 1 },
+        "value": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/schemas/lifecycle-authority-keys.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kontourai.dev/schemas/lifecycle-authority-keys.schema.json",
+  "title": "Lifecycle Authority Key Registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "keys"],
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "keys": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "algorithm", "public_key_pem"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "algorithm": { "const": "ed25519" },
+          "public_key_pem": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/schemas/workflow-state.schema.json

@@ -27,7 +27,7 @@
     },
     "status": {
       "type": "string",
-      "enum": ["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]
+      "enum": ["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "canceled", "accepted", "archived"]
     },
     "phase": {
       "type": "string",

package/scripts/hooks/config-protection.js

@@ -120,6 +120,13 @@ function checkProtectedPathPattern(filePath) {
     };
   }
 
+  if (/(?:^|\/)\.flow-agents\/lifecycle-authority-keys\.json$/.test(norm)) {
+    return {
+      name: '.flow-agents/lifecycle-authority-keys.json',
+      reason: 'an agent could replace the pinned lifecycle authority key and forge cancellation authority',
+    };
+  }
+
   // .kontourai/flow-agents/current.json — an agent could forge active_flow_id / active_step_id
   // to route the gate to a permissive or empty-expects FlowDefinition.
   // SAFE: the workflow CLI writes current.json via fs (writeJson → fs.writeFileSync),
@@ -426,7 +433,7 @@ function checkCommandForBypass(command) {
  */
 // #379: the delivery/ arms carry an optional (?:[^/]+\/)? segment so redirects/tee to the
 // per-session path delivery/<slug>/trust.bundle (+ checkpoint) are caught, not just the flat path.
-const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.checkpoint\.json$/;
+const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)\.flow-agents\/lifecycle-authority-keys\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.checkpoint\.json$/;
 
 /**
  * Return true when a token (an unquoted redirect target or tee argument) matches

package/scripts/hooks/lib/config-protection-remedies.js

@@ -20,6 +20,8 @@ const SANCTIONED_REMEDIES = {
     'There is no sanctioned automated writer for this file. Ask a human maintainer to edit it directly. Never disable this hook to make the write.',
   '.claude/settings.local.json':
     'There is no sanctioned automated writer for this file. Ask a human maintainer to edit it directly. Never disable this hook to make the write.',
+  '.flow-agents/lifecycle-authority-keys.json':
+    'Only the trusted harness installer or a human maintainer may rotate lifecycle authority keys. Never let an agent replace this trust root.',
   '.kontourai/flow-agents/current.json':
     'Use `npm run workflow:sidecar -- ensure-session` (or `advance-state`), which writes this file for you. Never disable this hook to make the write.',
   '.kontourai/flow-agents/current/<actor>.json':
@@ -58,6 +60,7 @@ function remedyFor(name) {
  * basename 'trust.bundle') -- first match wins, deterministically.
  */
 const REMEDY_COMMAND_CANDIDATES = [
+  { name: '.flow-agents/lifecycle-authority-keys.json', needles: ['lifecycle-authority-keys.json'] },
   { name: 'delivery/trust.checkpoint.json', needles: ['delivery/trust.checkpoint.json', 'trust.checkpoint.json'] },
   { name: 'delivery/trust.bundle', needles: ['delivery/trust.bundle'] },
   { name: '.kontourai/flow-agents/<slug>/trust.bundle', needles: ['trust.bundle'] },

package/scripts/hooks/stop-goal-fit.js

@@ -77,7 +77,7 @@ const PRE_EXECUTION_PHASES = new Set(['idea', 'backlog', 'pickup', 'planning']);
 // Terminal tasks are complete — they must never gate a stop or count as "active".
 // A stale current.json pointing at one, or a graveyard of finished states, must
 // not block an unrelated session.
-const TERMINAL_STATUSES = new Set(['done', 'delivered', 'accepted', 'archived', 'complete', 'completed']);
+const TERMINAL_STATUSES = new Set(['done', 'delivered', 'canceled', 'accepted', 'archived', 'complete', 'completed']);
 
 function isTerminalDeliveredState(state) {
   if (!state || typeof state !== 'object') return false;

package/src/builder-flow-run-adapter.ts

@@ -5,15 +5,19 @@ import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
 import {
   attachEvidence,
+  cancelRun,
   evaluateRun,
   expectationsForGate,
   loadRun,
   normalizeTrustBundle,
   openGates,
+  pauseRun,
   readJson,
+  resumeRun,
   startRun,
   validateDefinition,
   type FlowEvidenceEntry,
+  type FlowLifecycleRequest,
   type FlowRunState,
   type GateOutcome,
   type JsonObject,
@@ -67,6 +71,11 @@ export interface LoadBuilderBuildRunInput {
   cwd?: string;
 }
 
+export interface ChangeBuilderBuildRunLifecycleInput extends LoadBuilderBuildRunInput {
+  request: FlowLifecycleRequest;
+  at?: string;
+}
+
 export interface BuilderBuildRunResult {
   definitionId: typeof BUILDER_BUILD_FLOW_ID;
   definitionVersion: string;
@@ -189,6 +198,44 @@ export async function loadBuilderBuildRun(input: LoadBuilderBuildRunInput): Prom
   return resultFromRun(run, input.runId);
 }
 
+export async function pauseBuilderBuildRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderBuildRunResult> {
+  return changeBuilderBuildRunLifecycle(input, pauseRun);
+}
+
+export async function resumeBuilderBuildRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderBuildRunResult> {
+  return changeBuilderBuildRunLifecycle(input, resumeRun);
+}
+
+export async function cancelBuilderBuildRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderBuildRunResult & { idempotent: boolean }> {
+  const changed = await changeBuilderBuildRunLifecycleResult(input, cancelRun);
+  return { ...resultFromRun(changed, input.runId), idempotent: changed.idempotent };
+}
+
+async function changeBuilderBuildRunLifecycle(
+  input: ChangeBuilderBuildRunLifecycleInput,
+  operation: typeof pauseRun | typeof resumeRun,
+): Promise<BuilderBuildRunResult> {
+  const changed = await changeBuilderBuildRunLifecycleResult(input, operation);
+  return resultFromRun(changed, input.runId);
+}
+
+async function changeBuilderBuildRunLifecycleResult(
+  input: ChangeBuilderBuildRunLifecycleInput,
+  operation: typeof pauseRun | typeof resumeRun | typeof cancelRun,
+) {
+  assertRuntimeInput(input, []);
+  if (!isRecord(input.request)) throw new BuilderBuildRunInputError("request", "must be a lifecycle request object");
+  const cwd = input.cwd ?? process.cwd();
+  const before = await loadBuilderBuildRun({ runId: input.runId, cwd });
+  const changed = await operation(input.runId, { cwd, ...input.request, ...(input.at ? { at: input.at } : {}) });
+  const definition = await loadShippedBuilderBuildDefinition(resolveBuilderBuildFlowDefinitionPath());
+  assertCanonicalDefinition(input.runId, definition, changed.definition);
+  if (changed.state.subject !== before.state.subject) {
+    throw new BuilderBuildRunInputError("flow_run.state.subject", "changed during lifecycle transition");
+  }
+  return changed;
+}
+
 function resultFromRun(run: Awaited<ReturnType<typeof loadRun>>, runId: string): BuilderBuildRunResult {
   return {
     definitionId: run.definition.id,

package/src/builder-flow-runtime.ts

@@ -1,8 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
+import { flowAgentsPackageVersion } from "./lib/package-version.js";
+import { pinnedFlowAgentsCommand } from "./lib/pinned-cli-command.js";
 import {
   expectationsForGate,
+  lifecycleRequestMatches,
   openGates,
   readJson,
   runDir,
@@ -12,11 +16,16 @@ import {
   type FlowRunState,
   type JsonObject,
 } from "@kontourai/flow";
+import { assertAuthorizationUnused, loadBuilderLifecycleAuthorization, readAuthorizationConsumption, recordAuthorizationConsumed } from "./builder-lifecycle-authority.js";
+import { assignmentFilePath, performLocalReleaseUnderLock, readLocalAssignmentStatus, resolveCurrentAssignmentActor, withSubjectLock, type ActorStruct } from "./cli/assignment-provider.js";
 import {
   BUILDER_BUILD_FLOW_ID,
   BuilderBuildRunInputError,
+  cancelBuilderBuildRun,
   evaluateBuilderBuildRun,
   loadBuilderBuildRun,
+  pauseBuilderBuildRun,
+  resumeBuilderBuildRun,
   startBuilderBuildRun,
   type BuilderBuildRunResult,
 } from "./builder-flow-run-adapter.js";
@@ -27,6 +36,14 @@ export interface BuilderFlowSessionInput {
   sessionDir: string;
 }
 
+export interface BuilderFlowAuthorizedLifecycleInput extends BuilderFlowSessionInput {
+  authorizationFile: string;
+}
+
+export interface BuilderFlowAgentLifecycleInput extends BuilderFlowSessionInput {
+  reason: string;
+}
+
 export interface BuilderFlowSessionResult {
   sessionDir: string;
   projectRoot: string;
@@ -119,6 +136,195 @@ export async function recoverBuilderFlowSession(input: BuilderFlowSessionInput):
   };
 }
 
+export async function pauseBuilderFlowSession(input: BuilderFlowAgentLifecycleInput): Promise<BuilderFlowSessionResult> {
+  return changeBuilderFlowSessionLifecycle(input, "pause");
+}
+
+export async function resumeBuilderFlowSession(input: BuilderFlowAgentLifecycleInput): Promise<BuilderFlowSessionResult> {
+  return changeBuilderFlowSessionLifecycle(input, "resume");
+}
+
+export async function cancelBuilderFlowSession(input: BuilderFlowAuthorizedLifecycleInput): Promise<BuilderFlowSessionResult & { assignmentReleased: boolean; idempotent: boolean }> {
+  const context = resolveSessionContext(input.sessionDir);
+  return await withSubjectLock(context.artifactRoot, context.slug, async () => {
+    const prepared = await prepareAuthorizedLifecycleChange(input, "cancel", context);
+    assertAuthorizationUnused(prepared.context.artifactRoot, prepared.authorization);
+    const changed = await cancelBuilderBuildRun({ cwd: prepared.context.projectRoot, runId: prepared.context.slug, request: prepared.authorization.request });
+    const released = performLocalReleaseUnderLock(prepared.context.artifactRoot, prepared.context.slug, prepared.authorization.assignment_actor, {
+      actorKey: prepared.authorization.assignment_actor_key,
+      reason: `canonical Flow run canceled by ${prepared.authorization.request.authority.request_ref}`,
+      tolerateNoActiveClaim: true,
+    });
+    const projection = projectFlowRun(prepared.context, changed, prepared.sidecarSnapshot.state);
+    writeProjection(prepared.context, projection, prepared.sidecarSnapshot.raw, "cancellation projection");
+    recordAuthorizationConsumed(prepared.context.artifactRoot, prepared.authorization);
+    return { sessionDir: prepared.context.sessionDir, projectRoot: prepared.context.projectRoot, run: changed, projection, attached: false, assignmentReleased: released !== null, idempotent: changed.idempotent };
+  });
+}
+
+export async function releaseBuilderFlowAssignment(input: BuilderFlowAgentLifecycleInput): Promise<BuilderFlowSessionResult & { assignmentReleased: boolean }> {
+  const context = resolveSessionContext(input.sessionDir);
+  return await withSubjectLock(context.artifactRoot, context.slug, async () => {
+    const prepared = prepareAgentLifecycleChange(input, context);
+    const run = await loadBuilderBuildRun({ cwd: context.projectRoot, runId: context.slug });
+    const released = performLocalReleaseUnderLock(context.artifactRoot, context.slug, prepared.actor, { actorKey: prepared.actorKey, reason: input.reason });
+    return { sessionDir: context.sessionDir, projectRoot: context.projectRoot, run, projection: prepared.sidecarSnapshot.state, attached: false, assignmentReleased: released !== null };
+  });
+}
+
+export async function archiveBuilderFlowSession(input: BuilderFlowAuthorizedLifecycleInput): Promise<BuilderFlowSessionResult & { archiveDir: string }> {
+  const context = resolveSessionContext(input.sessionDir);
+  return await withSubjectLock(context.artifactRoot, context.slug, async () => {
+  const prepared = await prepareAuthorizedLifecycleChange(input, "archive", context);
+  const priorConsumption = readAuthorizationConsumption(prepared.context.artifactRoot, prepared.authorization);
+  const recoveringPreparedArchive = priorConsumption !== null && prepared.sidecarSnapshot.state.status === "archived";
+  if (priorConsumption && !recoveringPreparedArchive) throw new Error("lifecycle authorization nonce has already been consumed");
+  const run = await loadBuilderBuildRun({ cwd: prepared.context.projectRoot, runId: prepared.context.slug });
+  if (run.state.status !== "completed" && run.state.status !== "canceled") {
+    throw new BuilderBuildRunInputError("flow_run.status", "must be completed or canceled before archival");
+  }
+  const archiveRoot = path.join(prepared.context.artifactRoot, "archive");
+  const archiveDir = path.join(archiveRoot, prepared.context.slug);
+  if (pathExistsNoFollow(archiveDir)) throw new BuilderBuildRunInputError("archive", "destination already exists");
+  fs.mkdirSync(archiveRoot, { recursive: true });
+  assertSafeDirectory(archiveRoot, prepared.context.artifactRoot, "archive root");
+  assertSafeDirectory(prepared.context.sessionDir, prepared.context.artifactRoot, "sessionDir");
+  if (!recoveringPreparedArchive && fs.readFileSync(prepared.context.stateFile, "utf8") !== prepared.sidecarSnapshot.raw) {
+    throw new BuilderBuildRunInputError("state.json", "changed during archive preparation");
+  }
+  const archivedState = recoveringPreparedArchive ? prepared.sidecarSnapshot.state : {
+    ...prepared.sidecarSnapshot.state,
+    status: "archived",
+    phase: "done",
+    updated_at: new Date().toISOString(),
+    next_action: { status: "done", summary: "Builder session archived; canonical Flow artifacts remain retained." },
+  };
+  if (!recoveringPreparedArchive) {
+    writeExistingFileNoFollow(prepared.context.stateFile, `${JSON.stringify(archivedState, null, 2)}\n`);
+    clearCurrentPointers(prepared.context.artifactRoot, prepared.context.slug);
+    recordAuthorizationConsumed(prepared.context.artifactRoot, prepared.authorization);
+  }
+  fs.renameSync(prepared.context.sessionDir, archiveDir);
+  return {
+    sessionDir: archiveDir,
+    projectRoot: prepared.context.projectRoot,
+    run,
+    projection: archivedState,
+    attached: false,
+    archiveDir,
+  };
+  });
+}
+
+async function changeBuilderFlowSessionLifecycle(
+  input: BuilderFlowAgentLifecycleInput,
+  operation: "pause" | "resume",
+): Promise<BuilderFlowSessionResult> {
+  const context = resolveSessionContext(input.sessionDir);
+  return await withSubjectLock(context.artifactRoot, context.slug, async () => {
+  const prepared = prepareAgentLifecycleChange(input, context);
+  const change = operation === "pause" ? pauseBuilderBuildRun : resumeBuilderBuildRun;
+  const at = new Date().toISOString();
+  const run = await change({
+    cwd: context.projectRoot,
+    runId: context.slug,
+    request: { reason: input.reason, authority: { kind: "operator_request", actor: prepared.actorKey, request_ref: `flow-agents://assignment/${context.slug}/${operation}/${at}`, requested_at: at } },
+  });
+  const projection = projectFlowRun(context, run, prepared.sidecarSnapshot.state);
+  writeProjection(context, projection, prepared.sidecarSnapshot.raw, `${operation} projection`);
+  return {
+    sessionDir: context.sessionDir,
+    projectRoot: context.projectRoot,
+    run,
+    projection,
+    attached: false,
+  };
+  });
+}
+
+async function prepareAuthorizedLifecycleChange(input: BuilderFlowAuthorizedLifecycleInput, operation: "cancel" | "archive", context: SessionContext): Promise<{
+  context: SessionContext;
+  sidecarSnapshot: SidecarSnapshot;
+  authorization: ReturnType<typeof loadBuilderLifecycleAuthorization>;
+}> {
+  const sidecarSnapshot = readSidecarSnapshot(context);
+  const subject = workflowSubject(sidecarSnapshot.state);
+  const activeAssignment = readLocalAssignmentStatus(context.artifactRoot, context.slug).record;
+  const assignmentFile = assignmentFilePath(context.artifactRoot, context.slug);
+  const persistedAssignment = pathExistsNoFollow(assignmentFile)
+    ? (assertSafeFile(assignmentFile, context.artifactRoot, "assignment record"), JSON.parse(fs.readFileSync(assignmentFile, "utf8")) as AnyRecord)
+    : null;
+  const canonicalRun = await loadBuilderBuildRun({ cwd: context.projectRoot, runId: context.slug });
+  const acceptsReleasedAssignment = (operation === "cancel" && canonicalRun.state.status === "canceled") || operation === "archive";
+  const assignment = activeAssignment ?? (acceptsReleasedAssignment && persistedAssignment?.status === "released" ? persistedAssignment : null);
+  if (!assignment || (assignment.status !== "claimed" && !acceptsReleasedAssignment) || !assignment.actor_key) {
+    throw new BuilderBuildRunInputError("assignment", "must be actively held by a canonical actor before a lifecycle change");
+  }
+  if (assignment.work_item_ref && assignment.work_item_ref !== subject) {
+    throw new BuilderBuildRunInputError("assignment.work_item_ref", "must match the selected Work Item");
+  }
+  const authorization = loadBuilderLifecycleAuthorization(input.authorizationFile, {
+    projectRoot: context.projectRoot,
+    operation,
+    runId: context.slug,
+    subject,
+    actorKey: assignment.actor_key,
+    ...(operation === "cancel" && canonicalRun.state.status === "canceled" ? { allowExpired: true } : {}),
+    ...(operation === "archive" && sidecarSnapshot.state.status === "archived" ? { allowExpired: true } : {}),
+  });
+  if (operation === "cancel" && canonicalRun.state.status === "canceled") {
+    const terminalEvent = canonicalRun.state.lifecycle?.at(-1);
+    if (!terminalEvent || terminalEvent.action !== "cancel" || !lifecycleRequestMatches(terminalEvent, authorization.request)) {
+      throw new BuilderBuildRunInputError("authorization.request", "does not match the canonical cancellation being recovered");
+    }
+  }
+  if (!sameActor(authorization.assignment_actor, assignment.actor)) {
+    throw new BuilderBuildRunInputError("authorization.assignment_actor", "must match the active assignment holder");
+  }
+  return { context, sidecarSnapshot, authorization };
+}
+
+function prepareAgentLifecycleChange(input: BuilderFlowAgentLifecycleInput, context: SessionContext): { sidecarSnapshot: SidecarSnapshot; actor: ActorStruct; actorKey: string } {
+  if (!input.reason.trim()) throw new BuilderBuildRunInputError("reason", "must be non-empty");
+  const resolved = resolveCurrentAssignmentActor();
+  const sidecarSnapshot = readSidecarSnapshot(context);
+  const subject = workflowSubject(sidecarSnapshot.state);
+  const assignment = readLocalAssignmentStatus(context.artifactRoot, context.slug).record;
+  if (!assignment || assignment.status !== "claimed" || assignment.actor_key !== resolved.actorKey || !sameActor(assignment.actor, resolved.actor)) {
+    throw new BuilderBuildRunInputError("assignment", "must be actively held by the current workflow actor");
+  }
+  if (assignment.work_item_ref && assignment.work_item_ref !== subject) throw new BuilderBuildRunInputError("assignment.work_item_ref", "must match the selected Work Item");
+  return { sidecarSnapshot, actor: resolved.actor, actorKey: resolved.actorKey };
+}
+
+function sameActor(left: ActorStruct, right: ActorStruct): boolean {
+  return isDeepStrictEqual({ ...left, human: left.human ?? null }, { ...right, human: right.human ?? null });
+}
+
+function clearCurrentPointers(artifactRoot: string, slug: string): void {
+  const candidates = [path.join(artifactRoot, "current.json")];
+  const actorRoot = path.join(artifactRoot, "current");
+  if (pathExistsNoFollow(actorRoot)) {
+    assertSafeDirectory(actorRoot, artifactRoot, "current directory");
+    candidates.push(...fs.readdirSync(actorRoot).filter((name) => name.endsWith(".json")).map((name) => path.join(actorRoot, name)));
+  }
+  for (const file of candidates) {
+    if (!pathExistsNoFollow(file) || !fs.lstatSync(file).isFile()) continue;
+    const root = file === candidates[0] ? artifactRoot : actorRoot;
+    if (root === actorRoot) assertSafeDirectory(actorRoot, artifactRoot, "current directory");
+    assertSafeFile(file, root, "current pointer");
+    let pointer: AnyRecord;
+    try {
+      pointer = JSON.parse(fs.readFileSync(file, "utf8")) as AnyRecord;
+    } catch (error) {
+      if (!(error instanceof SyntaxError)) throw error;
+      // Archival retains malformed unrelated pointers for explicit repair.
+      continue;
+    }
+    if (pointer.active_slug === slug) fs.unlinkSync(file);
+  }
+}
+
 export async function syncBuilderFlowSessionIfPresent(sessionDir: string): Promise<BuilderFlowSessionResult | null> {
   let context: SessionContext;
   try {
@@ -291,7 +497,9 @@ function projectFlowRun(context: SessionContext, run: BuilderBuildRunResult, sid
   const definition = JSON.parse(fs.readFileSync(path.join(run.dir, "definition.json"), "utf8"));
   const gates = openGates(definition, run.state) as Array<FlowGate & { id: string }>;
   const complete = run.state.status === "completed";
-  const action = complete ? { skills: [], operations: [] } : stepAction(run.state.current_step);
+  const paused = run.state.status === "paused";
+  const canceled = run.state.status === "canceled";
+  const action = complete || paused || canceled ? { skills: [], operations: [] } : stepAction(run.state.current_step);
   if (!action) {
     throw new BuilderBuildRunInputError("kit.flow_step_actions", `does not declare Builder step ${run.state.current_step}`);
   }
@@ -300,7 +508,7 @@ function projectFlowRun(context: SessionContext, run: BuilderBuildRunResult, sid
     .map((expectation: FlowExpectation) => `${expectation.id} (${expectation.bundle_claim.claimType}/${expectation.bundle_claim.subjectType ?? "any"})`));
   const skills = action?.skills ?? [];
   const operations = action?.operations ?? [];
-  const syncCommand = `flow-agents builder-run sync --session-dir .kontourai/flow-agents/${context.slug}`;
+  const syncCommand = pinnedFlowAgentsCommand(flowAgentsPackageVersion(), ["workflow", "status", "--session-dir", `.kontourai/flow-agents/${context.slug}`, "--json"]);
   const routeBack = latestRouteBack(run.state);
   const skillText = skills.length ? `Activate ${skills.map((skill) => `\`${skill}\``).join(" then ")}.` : "No Builder skill is required.";
   const operationText = operations.length ? ` Perform ${operations.map((operation) => `\`${operation}\``).join(" then ")}.` : "";
@@ -312,6 +520,10 @@ function projectFlowRun(context: SessionContext, run: BuilderBuildRunResult, sid
     : "";
   const nextAction = complete
     ? { status: "done", summary: "Canonical Flow run is complete." }
+    : canceled
+      ? { status: "done", summary: "Canonical Flow run was canceled by an authorized external request. Artifacts are retained until separately archived." }
+      : paused
+        ? { status: "blocked", summary: "Canonical Flow run is paused. The current assignment actor may resume it with a reason." }
     : {
         status: "continue",
         summary: `Flow step \`${run.state.current_step}\`: ${skillText}${operationText} ${gateText}${routeText} Then synchronize the recorded evidence.`,
@@ -322,8 +534,8 @@ function projectFlowRun(context: SessionContext, run: BuilderBuildRunResult, sid
   const phase = phaseForStep(definition.phase_map, run.state.current_step) ?? sidecar.phase;
   return {
     ...sidecar,
-    status: complete ? "delivered" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
-    phase: complete ? "done" : phase,
+    status: complete ? "delivered" : canceled ? "canceled" : paused ? "blocked" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
+    phase: complete || canceled ? "done" : phase,
     updated_at: run.state.updated_at,
     flow_run: {
       run_id: run.runId,