ai-delivery-workflow 0.2.2

package/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs

@@ -0,0 +1,1073 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+const moduleRequire = createRequire(import.meta.url);
+
+const VALID_STATUS = new Set([
+  "queued", "preparing", "running", "checkpointed", "pending-review",
+  "blocked", "interrupted", "completed", "failed", "abandoned",
+]);
+const FINISH_STATUS = new Set(["completed", "blocked", "interrupted", "failed", "abandoned"]);
+const CLOSED_STATUS = new Set(["completed", "failed", "abandoned"]);
+const RESUMABLE_STATUS = new Set([
+  "preparing", "running", "checkpointed", "pending-review", "blocked", "interrupted",
+]);
+const VALID_NEXT_ACTION_OWNER = new Set(["agent", "user", "external"]);
+const REPEATABLE_ARGS = new Set([
+  "scope", "input-artifact", "standard", "planned-output", "actual-output",
+  "completed-step", "blocker", "evidence", "depends-on",
+]);
+
+function parseArgs(argv) {
+  const result = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (!value.startsWith("--")) {
+      result._.push(value);
+      continue;
+    }
+    const key = value.slice(2);
+    const next = argv[index + 1];
+    const parsed = next && !next.startsWith("--") ? (index += 1, next) : true;
+    if (REPEATABLE_ARGS.has(key)) {
+      result[key] = [...(result[key] || []), parsed];
+    } else {
+      result[key] = parsed;
+    }
+  }
+  return result;
+}
+
+function requireValue(args, key) {
+  const value = args[key];
+  if (!value || value === true) throw new Error(`Missing --${key}`);
+  return value;
+}
+
+function now() {
+  return new Date().toISOString();
+}
+
+function sanitizeId(value) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value)) {
+    throw new Error(`Invalid identifier: ${value}`);
+  }
+  return value;
+}
+
+function parseSequence(value) {
+  if (value === undefined || value === null || value === "") return null;
+  const sequence = Number(value);
+  if (!Number.isInteger(sequence) || sequence < 1) {
+    throw new Error(`Invalid positive integer sequence: ${value}`);
+  }
+  return sequence;
+}
+
+function parseNextActionOwner(value, fallback = "agent") {
+  const owner = value === undefined ? fallback : value;
+  if (!VALID_NEXT_ACTION_OWNER.has(owner)) {
+    throw new Error(`Invalid next action owner: ${owner}; use agent, user, or external.`);
+  }
+  return owner;
+}
+
+function requestedNextActionOwner(args) {
+  if (args["next-action-owner"] === undefined) return null;
+  return parseNextActionOwner(args["next-action-owner"]);
+}
+
+function assertWaitStateTransfer(task, args, command) {
+  const requestedOwner = requestedNextActionOwner(args);
+  if (task.next_action_owner === "agent") return requestedOwner;
+  if (requestedOwner !== "agent") {
+    throw new Error(
+      `Task ${task.task_id} is waiting for ${task.next_action_owner}; ${command} requires an explicit --next-action-owner agent after that input exists.`,
+    );
+  }
+  if (!args["next-action"] || args["next-action"] === true) {
+    throw new Error(`Task ${task.task_id} requires a new --next-action when ownership transfers to agent.`);
+  }
+  return requestedOwner;
+}
+
+function findProjectRoot(start = process.cwd()) {
+  let current = path.resolve(start);
+  while (true) {
+    if (fs.existsSync(path.join(current, ".workflow", "delivery", "project.yaml"))) return current;
+    if (fs.existsSync(path.join(current, "delivery", "project.yaml"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(start);
+    current = parent;
+  }
+}
+
+function workflowRootFor(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, ".workflow", "delivery", "project.yaml"))) {
+    return path.join(projectRoot, ".workflow");
+  }
+  if (fs.existsSync(path.join(projectRoot, "delivery", "project.yaml"))) return projectRoot;
+  return path.join(projectRoot, ".workflow");
+}
+
+function taskMarkerFile(stateRoot) {
+  return path.join(workflowRootFor(stateRoot), "delivery", "runtime", "active-task.json");
+}
+
+function readTaskMarker(start = process.cwd()) {
+  const markerFile = taskMarkerFile(findProjectRoot(start));
+  if (!markerFile) return null;
+  if (!fs.existsSync(markerFile)) return null;
+  const marker = JSON.parse(fs.readFileSync(markerFile, "utf8"));
+  if (!marker.task_id || !marker.state_root) {
+    throw new Error(`Invalid task marker: ${markerFile}`);
+  }
+  return { ...marker, marker_file: markerFile };
+}
+
+function statePaths(args) {
+  const projectRoot = path.resolve(args.root || findProjectRoot());
+  const marker = readTaskMarker(projectRoot);
+  const stateRoot = path.resolve(args["state-root"] || marker?.state_root || projectRoot);
+  const workflowRoot = workflowRootFor(stateRoot);
+  const runtime = path.join(workflowRoot, "delivery", "runtime");
+  return { projectRoot, stateRoot, workflowRoot, runtime, marker };
+}
+
+function atomicWrite(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  fs.renameSync(temp, file);
+}
+
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function withTaskLock(runtime, taskId, action) {
+  const lockDir = path.join(runtime, "locks");
+  const lockFile = path.join(lockDir, `${taskId}.lock`);
+  fs.mkdirSync(lockDir, { recursive: true });
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    const token = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    let fd;
+    try {
+      fd = fs.openSync(lockFile, "wx");
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      let age;
+      try {
+        age = Date.now() - fs.statSync(lockFile).mtimeMs;
+      } catch (statError) {
+        if (statError.code === "ENOENT") continue;
+        throw statError;
+      }
+      if (age > 60_000) {
+        const staleFile = `${lockFile}.${process.pid}.${Date.now()}.stale`;
+        try {
+          fs.renameSync(lockFile, staleFile);
+          fs.unlinkSync(staleFile);
+        } catch (staleError) {
+          if (staleError.code !== "ENOENT" && staleError.code !== "EACCES" && staleError.code !== "EPERM") {
+            throw staleError;
+          }
+        }
+        continue;
+      }
+      sleep(20);
+      continue;
+    }
+    try {
+      fs.writeFileSync(fd, `${token} ${now()}\n`, "utf8");
+      return action();
+    } finally {
+      fs.closeSync(fd);
+      try {
+        const owner = fs.readFileSync(lockFile, "utf8");
+        if (owner.startsWith(`${token} `)) fs.unlinkSync(lockFile);
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+  }
+  throw new Error(`Timed out acquiring task lock: ${taskId}`);
+}
+
+function taskFile(runtime, taskId) {
+  return path.join(runtime, "tasks", `${taskId}.json`);
+}
+
+function sharedTaskFile(workflowRoot, taskId) {
+  return path.join(workflowRoot, "control", "tasks", `${taskId}.yaml`);
+}
+
+function portablePath(root, target) {
+  const relative = path.relative(root, target);
+  return relative && !relative.startsWith("..") && !path.isAbsolute(relative)
+    ? relative.replaceAll("\\", "/")
+    : target;
+}
+
+function parseWorkspaceConfiguration(workflowRoot) {
+  const workspaceFile = path.join(workflowRoot, "config", "workspace.yaml");
+  if (!fs.existsSync(workspaceFile)) return null;
+  let yaml;
+  try {
+    yaml = moduleRequire("yaml");
+  } catch {
+    const vendorRoot = path.join(workflowRoot, "tools", "state", "vendor", "yaml");
+    const vendorRequire = createRequire(path.join(vendorRoot, "package.json"));
+    yaml = vendorRequire("./");
+  }
+  return { file: workspaceFile, configuration: yaml.parse(fs.readFileSync(workspaceFile, "utf8")) };
+}
+
+function configuredCodeState(workflowRoot) {
+  const workspace = parseWorkspaceConfiguration(workflowRoot);
+  if (!workspace) {
+    throw new Error(`Authoritative workspace configuration is missing: ${path.join(workflowRoot, "config", "workspace.yaml")}`);
+  }
+  const codePath = workspace.configuration?.code_repository?.path;
+  const normalized = codePath && !path.isAbsolute(codePath)
+    ? path.normalize(codePath).replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "")
+    : null;
+  if (!normalized || normalized.includes("/") || normalized === "." || normalized === "..") {
+    throw new Error(`Code repository path must be a relative direct child in ${workspace.file}`);
+  }
+  const projectRoot = path.basename(workflowRoot) === ".workflow"
+    ? path.dirname(workflowRoot)
+    : workflowRoot;
+  const codeRoot = path.resolve(projectRoot, normalized);
+  const relative = path.relative(projectRoot, codeRoot);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`Code repository path escapes the project: ${codePath}`);
+  }
+  const code = gitState(codeRoot);
+  if (!code.repository || path.resolve(code.root).toLowerCase() !== codeRoot.toLowerCase()) {
+    throw new Error(`Configured code repository is not an independent Git root: ${codeRoot}`);
+  }
+  return code;
+}
+
+function writeSharedTask(runtime, workflowRoot, task) {
+  const sharedFile = sharedTaskFile(workflowRoot, task.task_id);
+  let previousRevision = 0;
+  if (fs.existsSync(sharedFile)) {
+    previousRevision = Number(JSON.parse(fs.readFileSync(sharedFile, "utf8")).shared_revision || 0);
+    const localRevision = Number(task.shared_revision || 0);
+    if (localRevision !== previousRevision) {
+      throw new Error(
+        `Local and shared task state conflict for ${task.task_id}: local revision ${localRevision}, shared revision ${previousRevision}; recover before updating.`,
+      );
+    }
+  }
+  task.shared_revision = previousRevision + 1;
+  const code = configuredCodeState(workflowRoot);
+  const shared = {
+    ...task,
+    state_root: ".",
+    worktree: portablePath(task.state_root, task.worktree),
+    code_branch: code.branch || task.branch || null,
+    code_commit: code.head || null,
+  };
+  atomicWrite(taskFile(runtime, task.task_id), task);
+  writeCheckpoint(runtime, task);
+  atomicWrite(sharedFile, shared);
+  const checkpointId = `${task.shared_revision}-${task.updated_at.replaceAll(":", "-")}`;
+  atomicWrite(path.join(workflowRoot, "control", "checkpoints", task.task_id, `${checkpointId}.yaml`), shared);
+}
+
+function readSharedTasks(workflowRoot, stateRoot) {
+  const directory = path.join(workflowRoot, "control", "tasks");
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory)
+    .filter((name) => name.endsWith(".yaml"))
+    .map((name) => {
+      const shared = normalizeTask(JSON.parse(fs.readFileSync(path.join(directory, name), "utf8")));
+      shared.state_root = stateRoot;
+      shared.worktree = path.isAbsolute(shared.worktree)
+        ? shared.worktree
+        : path.resolve(stateRoot, shared.worktree || "code");
+      return shared;
+    });
+}
+
+function archivedTaskIndexFile(runtime, taskId) {
+  return path.join(runtime, "archive", "index", "tasks", `${taskId}.json`);
+}
+
+function archivedVersionIndexFile(runtime, iterationId) {
+  return path.join(runtime, "archive", "index", "versions", `${iterationId}.json`);
+}
+
+function readTask(runtime, taskId) {
+  const file = taskFile(runtime, taskId);
+  if (!fs.existsSync(file)) throw new Error(`Task not found: ${taskId}`);
+  return normalizeTask(JSON.parse(fs.readFileSync(file, "utf8")));
+}
+
+function normalizeTask(task) {
+  for (const key of [
+    "scope", "input_artifacts", "standards", "planned_outputs", "actual_outputs",
+    "completed_steps", "blockers", "evidence", "depends_on",
+  ]) {
+    if (!Array.isArray(task[key])) task[key] = [];
+    task[key] = [...new Set(task[key])];
+  }
+  task.sequence = parseSequence(task.sequence);
+  task.next_action_owner = parseNextActionOwner(task.next_action_owner);
+  return task;
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
+}
+
+function comparableTaskState(task) {
+  const comparable = { ...task };
+  const stateRoot = path.resolve(comparable.state_root || ".");
+  comparable.state_root = process.platform === "win32" ? stateRoot.toLowerCase() : stateRoot;
+  if (comparable.worktree) {
+    const worktree = path.resolve(stateRoot, comparable.worktree);
+    comparable.worktree = process.platform === "win32" ? worktree.toLowerCase() : worktree;
+  }
+  for (const key of ["code_branch", "code_commit"]) delete comparable[key];
+  return comparable;
+}
+
+function taskStateChecksum(task) {
+  return crypto.createHash("sha256")
+    .update(JSON.stringify(stableValue(comparableTaskState(task))))
+    .digest("hex");
+}
+
+function assertTaskSourcesMatch(local, shared) {
+  if (Number(local.shared_revision || 0) !== Number(shared.shared_revision || 0)) {
+    throw new Error(
+      `Local and shared task state conflict for ${local.task_id}: local revision ${local.shared_revision || 0}, shared revision ${shared.shared_revision || 0}; reconcile before recovery.`,
+    );
+  }
+  if (taskStateChecksum(local) !== taskStateChecksum(shared)) {
+    throw new Error(
+      `Local and shared task state conflict for ${local.task_id}: revision ${local.shared_revision || 0} has different content; reconcile before recovery.`,
+    );
+  }
+}
+
+function taskSources(runtime, workflowRoot, stateRoot, taskId) {
+  const localFile = taskFile(runtime, taskId);
+  const local = fs.existsSync(localFile) ? readTask(runtime, taskId) : null;
+  const shared = readSharedTasks(workflowRoot, stateRoot).find((task) => task.task_id === taskId) || null;
+  if (local && shared) assertTaskSourcesMatch(local, shared);
+  return { local, shared, task: local || shared };
+}
+
+function appendEvent(runtime, taskId, type, details = {}) {
+  const file = path.join(runtime, "events", `${taskId}.jsonl`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, `${JSON.stringify({ at: now(), type, task_id: taskId, ...details })}\n`, "utf8");
+}
+
+function copyIfExists(source, destination) {
+  if (!fs.existsSync(source)) return;
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  if (fs.statSync(source).isDirectory()) fs.cpSync(source, destination, { recursive: true, force: true });
+  else fs.copyFileSync(source, destination);
+}
+
+function removeIfExists(target) {
+  if (!fs.existsSync(target)) return;
+  if (fs.statSync(target).isDirectory()) fs.rmSync(target, { recursive: true, force: true });
+  else fs.unlinkSync(target);
+}
+
+function clearTaskMarker(task) {
+  if (!task.state_root) return;
+  const markerFile = taskMarkerFile(task.state_root);
+  if (!fs.existsSync(markerFile)) return;
+  try {
+    const marker = JSON.parse(fs.readFileSync(markerFile, "utf8"));
+    if (marker.task_id === task.task_id) fs.unlinkSync(markerFile);
+  } catch {
+    // Preserve an invalid marker for explicit reconciliation.
+  }
+}
+
+function removeActiveTaskBundle(runtime, task) {
+  removeIfExists(taskFile(runtime, task.task_id));
+  removeIfExists(path.join(runtime, "checkpoints", task.task_id));
+  removeIfExists(path.join(runtime, "events", `${task.task_id}.jsonl`));
+  removeIfExists(path.join(runtime, "heartbeats", `${task.task_id}.json`));
+  removeIfExists(path.join(runtime, "resumes", `${task.task_id}.md`));
+  clearTaskMarker(task);
+}
+
+function removeSharedTaskBundle(workflowRoot, task) {
+  removeIfExists(sharedTaskFile(workflowRoot, task.task_id));
+  removeIfExists(path.join(workflowRoot, "control", "checkpoints", task.task_id));
+}
+
+function copyTaskToVersionArchive(runtime, task, archiveDirectory, archivedAt) {
+  const taskDirectory = path.join(archiveDirectory, "tasks", task.task_id);
+  const archivedTask = {
+    ...task,
+    archived_at: archivedAt,
+    archive_path: path.relative(task.state_root, taskDirectory).replaceAll("\\", "/"),
+  };
+  fs.mkdirSync(taskDirectory, { recursive: true });
+  copyIfExists(path.join(runtime, "checkpoints", task.task_id), path.join(taskDirectory, "checkpoints"));
+  copyIfExists(path.join(runtime, "events", `${task.task_id}.jsonl`), path.join(taskDirectory, "events.jsonl"));
+  copyIfExists(path.join(runtime, "heartbeats", `${task.task_id}.json`), path.join(taskDirectory, "heartbeat.json"));
+  copyIfExists(path.join(runtime, "resumes", `${task.task_id}.md`), path.join(taskDirectory, "resume.md"));
+  atomicWrite(path.join(taskDirectory, "task.json"), archivedTask);
+  return archivedTask;
+}
+
+function copyTaskToPortableArchive(stateRoot, workflowRoot, task, archiveDirectory, archivedAt) {
+  const taskDirectory = path.join(archiveDirectory, "tasks", task.task_id);
+  const sharedFile = sharedTaskFile(workflowRoot, task.task_id);
+  const portableTask = fs.existsSync(sharedFile)
+    ? normalizeTask(JSON.parse(fs.readFileSync(sharedFile, "utf8")))
+    : normalizeTask({ ...task, state_root: ".", worktree: portablePath(task.state_root, task.worktree) });
+  portableTask.archived_at = archivedAt;
+  portableTask.archive_path = path.relative(stateRoot, taskDirectory).replaceAll("\\", "/");
+  fs.mkdirSync(taskDirectory, { recursive: true });
+  copyIfExists(
+    path.join(workflowRoot, "control", "checkpoints", task.task_id),
+    path.join(taskDirectory, "checkpoints"),
+  );
+  atomicWrite(path.join(taskDirectory, "task.json"), portableTask);
+  return portableTask;
+}
+
+function writeCheckpoint(runtime, task) {
+  const stamp = now().replaceAll(":", "-");
+  atomicWrite(path.join(runtime, "checkpoints", task.task_id, `${stamp}.json`), task);
+}
+
+function writeResume(runtime, task, reconciliation = null) {
+  const lines = [
+    `# Task Recovery: ${task.task_id}`,
+    "",
+    "## Objective", "", task.goal || "Not recorded.", "",
+    "## Recorded State", "", `- Status: ${task.status}`, `- Node: ${task.node}`, `- Skill: ${task.skill}`,
+    `- Sequence: ${task.sequence || "not recorded"}`,
+    `- Dependencies: ${task.depends_on.length ? task.depends_on.join(", ") : "none"}`,
+    `- Next action owner: ${task.next_action_owner}`,
+    `- Branch: ${task.branch || "not recorded"}`, `- Worktree: ${task.worktree || "not recorded"}`, "",
+    "## Completed Work And Evidence", "",
+    ...(task.completed_steps.length ? task.completed_steps.map((step) => `- ${step}`) : ["- None recorded."]), "",
+    ...(task.actual_outputs?.length ? ["### Actual Outputs", "", ...task.actual_outputs.map((item) => `- ${item}`), ""] : []),
+    ...(task.evidence?.length ? ["### Evidence", "", ...task.evidence.map((item) => `- ${item}`), ""] : []),
+    "## Blockers", "",
+    ...(task.blockers.length ? task.blockers.map((item) => `- ${item}`) : ["- None recorded."]), "",
+    "## Next Idempotent Action", "", task.next_action || "Reconcile state before continuing.", "",
+  ];
+  if (reconciliation) {
+    lines.push("## Reconciled Workspace And Git State", "", "```json", JSON.stringify(reconciliation, null, 2), "```", "");
+  }
+  const file = path.join(runtime, "resumes", `${task.task_id}.md`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${lines.join("\n")}\n`, "utf8");
+}
+
+function gitState(cwd) {
+  const run = (args) => spawnSync("git", args, { cwd, encoding: "utf8", windowsHide: true });
+  const root = run(["rev-parse", "--show-toplevel"]);
+  if (root.status !== 0) return { repository: false };
+  const branch = run(["branch", "--show-current"]);
+  const head = run(["rev-parse", "HEAD"]);
+  const status = run(["status", "--porcelain=v1"]);
+  return {
+    repository: true,
+    root: root.stdout.trim(),
+    branch: branch.stdout.trim(),
+    head: head.status === 0 ? head.stdout.trim() : null,
+    dirty_paths: status.stdout.split(/\r?\n/).filter(Boolean).map((line) => line.slice(3)),
+  };
+}
+
+function compareTasks(left, right) {
+  const leftSequence = left.sequence ?? Number.MAX_SAFE_INTEGER;
+  const rightSequence = right.sequence ?? Number.MAX_SAFE_INTEGER;
+  return leftSequence - rightSequence || left.task_id.localeCompare(right.task_id);
+}
+
+function readRuntimeTasks(runtime) {
+  const tasksDir = path.join(runtime, "tasks");
+  if (!fs.existsSync(tasksDir)) return [];
+  return fs.readdirSync(tasksDir)
+    .filter((name) => name.endsWith(".json"))
+    .map((name) => normalizeTask(JSON.parse(fs.readFileSync(path.join(tasksDir, name), "utf8"))));
+}
+
+function dependencyState(task, tasksById) {
+  const missing = [];
+  const incomplete = [];
+  for (const dependencyId of task.depends_on) {
+    const dependency = tasksById.get(dependencyId);
+    if (!dependency) missing.push(dependencyId);
+    else if (dependency.status !== "completed") {
+      incomplete.push({ task_id: dependencyId, status: dependency.status });
+    }
+  }
+  return { missing, incomplete, satisfied: !missing.length && !incomplete.length };
+}
+
+function summarizeIteration(tasks, iterationId) {
+  const iterationTasks = tasks.filter((task) => task.iteration_id === iterationId).sort(compareTasks);
+  const tasksById = new Map(iterationTasks.map((task) => [task.task_id, task]));
+  const completed = iterationTasks.filter((task) => task.status === "completed");
+  const closed = iterationTasks.filter((task) => CLOSED_STATUS.has(task.status));
+  const active = iterationTasks.filter((task) => RESUMABLE_STATUS.has(task.status));
+  const queued = iterationTasks.filter((task) => task.status === "queued");
+  const ready = queued.filter((task) => dependencyState(task, tasksById).satisfied);
+  const waiting = queued
+    .filter((task) => !ready.includes(task))
+    .map((task) => ({ task_id: task.task_id, ...dependencyState(task, tasksById) }));
+  const recommended = [...active, ...ready].sort(compareTasks)[0] || null;
+  return {
+    iteration_id: iterationId,
+    total_tasks: iterationTasks.length,
+    completed_tasks: completed.length,
+    closed_tasks: closed.length,
+    remaining_tasks: iterationTasks.length - closed.length,
+    active_task_ids: active.map((task) => task.task_id),
+    queued_task_ids: queued.map((task) => task.task_id),
+    ready_task_ids: ready.map((task) => task.task_id),
+    waiting_tasks: waiting,
+    recommended_task_id: recommended?.task_id || null,
+    recommended_status: recommended?.status || null,
+    next_action: recommended?.next_action || null,
+    next_action_owner: recommended?.next_action_owner || null,
+  };
+}
+
+function commandInit(args) {
+  const taskId = sanitizeId(requireValue(args, "task-id"));
+  const iterationId = sanitizeId(requireValue(args, "iteration-id"));
+  const { projectRoot, stateRoot, workflowRoot, runtime } = statePaths(args);
+  return withTaskLock(runtime, `version.${iterationId}`, () => withTaskLock(runtime, taskId, () => {
+    if (fs.existsSync(archivedTaskIndexFile(runtime, taskId))) {
+      throw new Error(`Task ID is already archived and cannot be reused: ${taskId}`);
+    }
+    if (fs.existsSync(archivedVersionIndexFile(runtime, iterationId))) {
+      throw new Error(`Version is already archived and cannot accept new tasks: ${iterationId}`);
+    }
+    const file = taskFile(runtime, taskId);
+    const existing = fs.existsSync(file)
+      ? normalizeTask(JSON.parse(fs.readFileSync(file, "utf8")))
+      : null;
+    if (existing && existing.iteration_id !== iterationId) {
+      throw new Error(`Task ${taskId} already belongs to iteration ${existing.iteration_id}`);
+    }
+    const shared = readSharedTasks(workflowRoot, stateRoot).find((item) => item.task_id === taskId);
+    if (existing && shared) assertTaskSourcesMatch(existing, shared);
+    if (existing) assertWaitStateTransfer(existing, args, "init");
+    const status = args.status || "preparing";
+    const dependsOn = (args["depends-on"] || existing?.depends_on || []).map(sanitizeId);
+    if (dependsOn.includes(taskId)) throw new Error(`Task cannot depend on itself: ${taskId}`);
+    const timestamp = now();
+    const task = {
+      task_id: taskId,
+      iteration_id: iterationId,
+      node: requireValue(args, "node"),
+      skill: requireValue(args, "skill"),
+      status,
+      sequence: parseSequence(args.sequence ?? existing?.sequence),
+      depends_on: dependsOn,
+      attempt: existing ? Number(existing.attempt || 0) + 1 : 1,
+      goal: requireValue(args, "goal"),
+      scope: args.scope || existing?.scope || [],
+      input_artifacts: args["input-artifact"] || existing?.input_artifacts || [],
+      standards: args.standard || existing?.standards || [],
+      branch: args.branch || existing?.branch || null,
+      worktree: path.resolve(args.worktree || projectRoot),
+      state_root: stateRoot,
+      planned_outputs: args["planned-output"] || existing?.planned_outputs || [],
+      actual_outputs: existing?.actual_outputs || [],
+      completed_steps: existing?.completed_steps || [],
+      blockers: [],
+      next_action: requireValue(args, "next-action"),
+      next_action_owner: parseNextActionOwner(args["next-action-owner"], existing?.next_action_owner),
+      evidence: existing?.evidence || [],
+      created_at: existing?.created_at || timestamp,
+      started_at: status === "queued" ? existing?.started_at || null : existing?.started_at || timestamp,
+      updated_at: timestamp,
+      finished_at: CLOSED_STATUS.has(status) ? existing?.finished_at || timestamp : null,
+    };
+    if (!VALID_STATUS.has(task.status)) throw new Error(`Invalid status: ${task.status}`);
+    writeSharedTask(runtime, workflowRoot, task);
+    writeResume(runtime, task);
+    if (RESUMABLE_STATUS.has(status)) {
+      atomicWrite(taskMarkerFile(stateRoot), { task_id: taskId, state_root: stateRoot });
+    } else {
+      clearTaskMarker(task);
+    }
+    appendEvent(runtime, taskId, "task-initialized", { status: task.status, attempt: task.attempt });
+    return task;
+  }));
+}
+
+function commandActivate(args) {
+  const taskId = sanitizeId(requireValue(args, "task-id"));
+  const { stateRoot, workflowRoot, runtime, marker } = statePaths(args);
+  if (marker && marker.task_id !== taskId) {
+    throw new Error(`Task marker points to active task ${marker.task_id}, not ${taskId}`);
+  }
+  const initialSources = taskSources(runtime, workflowRoot, stateRoot, taskId);
+  if (!initialSources.task) throw new Error(`Task not found: ${taskId}`);
+  if (!initialSources.local) {
+    if (initialSources.task.next_action_owner === "agent") {
+      throw new Error(`Task ${taskId} has no local runtime state; run recover before activation.`);
+    }
+    assertWaitStateTransfer(initialSources.task, args, "activate");
+  }
+  const initial = initialSources.task;
+  return withTaskLock(runtime, `version.${initial.iteration_id}`, () => withTaskLock(runtime, taskId, () => {
+    const currentSources = taskSources(runtime, workflowRoot, stateRoot, taskId);
+    const task = currentSources.task;
+    if (!task) throw new Error(`Task not found: ${taskId}`);
+    if (!new Set(["queued", "preparing", "checkpointed", "blocked", "interrupted"]).has(task.status)) {
+      throw new Error(`Task ${taskId} cannot be activated from status ${task.status}`);
+    }
+    const sharedTasks = readSharedTasks(workflowRoot, stateRoot);
+    const tasksById = new Map(sharedTasks.map((item) => [item.task_id, item]));
+    for (const item of readRuntimeTasks(runtime)) {
+      const shared = tasksById.get(item.task_id);
+      if (shared) assertTaskSourcesMatch(item, shared);
+      tasksById.set(item.task_id, item);
+    }
+    const dependencies = dependencyState(task, tasksById);
+    if (!dependencies.satisfied) {
+      const details = [
+        ...dependencies.missing.map((id) => `${id}:missing`),
+        ...dependencies.incomplete.map((item) => `${item.task_id}:${item.status}`),
+      ];
+      throw new Error(`Task ${taskId} has unsatisfied dependencies: ${details.join(", ")}`);
+    }
+    const status = args.status || "running";
+    if (!new Set(["preparing", "running"]).has(status)) {
+      throw new Error("activate --status must be preparing or running");
+    }
+    const requestedOwner = assertWaitStateTransfer(task, args, "activate");
+    if (task.next_action_owner === "agent" && requestedOwner && requestedOwner !== "agent") {
+      throw new Error("activate --next-action-owner may only be agent; use checkpoint or finish to enter a wait state.");
+    }
+    const firstStart = !task.started_at;
+    task.status = status;
+    task.attempt = firstStart ? Number(task.attempt || 1) : Number(task.attempt || 0) + 1;
+    task.started_at ||= now();
+    task.updated_at = now();
+    task.finished_at = null;
+    task.blockers = [];
+    if (args["next-action"] && args["next-action"] !== true) task.next_action = args["next-action"];
+    if (requestedOwner) task.next_action_owner = requestedOwner;
+    writeSharedTask(runtime, workflowRoot, task);
+    writeResume(runtime, task);
+    atomicWrite(taskMarkerFile(task.state_root), {
+      task_id: taskId,
+      iteration_id: task.iteration_id,
+      state_root: task.state_root,
+    });
+    appendEvent(runtime, taskId, "task-activated", { status, attempt: task.attempt });
+    return task;
+  }));
+}
+
+function commandUpdate(args, finish = false) {
+  const taskId = sanitizeId(requireValue(args, "task-id"));
+  const { stateRoot, workflowRoot, runtime, marker } = statePaths(args);
+  if (marker && marker.task_id !== taskId) {
+    throw new Error(`Task marker points to ${marker.task_id}, not ${taskId}`);
+  }
+  return withTaskLock(runtime, taskId, () => {
+    const task = readTask(runtime, taskId);
+    const shared = readSharedTasks(workflowRoot, stateRoot).find((item) => item.task_id === taskId);
+    if (shared) assertTaskSourcesMatch(task, shared);
+    const requestedOwner = assertWaitStateTransfer(task, args, finish ? "finish" : "checkpoint");
+    const status = requireValue(args, "status");
+    if (!VALID_STATUS.has(status)) throw new Error(`Invalid status: ${status}`);
+    if (finish && !FINISH_STATUS.has(status)) {
+      throw new Error(`finish requires one of: ${[...FINISH_STATUS].join(", ")}`);
+    }
+    task.status = status;
+    task.next_action = requireValue(args, "next-action");
+    task.next_action_owner = requestedOwner || task.next_action_owner;
+    for (const step of args["completed-step"] || []) {
+      if (!task.completed_steps.includes(step)) task.completed_steps.push(step);
+    }
+    task.blockers = status === "blocked" ? [...(args.blocker || [])] : [];
+    task.evidence = [...new Set([...task.evidence, ...(args.evidence || [])])];
+    for (const output of args["actual-output"] || []) {
+      if (!task.actual_outputs.includes(output)) task.actual_outputs.push(output);
+    }
+    task.updated_at = now();
+    task.finished_at = finish ? now() : null;
+    writeSharedTask(runtime, workflowRoot, task);
+    writeResume(runtime, task);
+    appendEvent(runtime, taskId, finish ? "task-finished" : "task-checkpointed", { status });
+    if (finish && CLOSED_STATUS.has(status)) clearTaskMarker(task);
+    return task;
+  });
+}
+
+function commandArchiveVersion(args) {
+  const { runtime, stateRoot, workflowRoot } = statePaths(args);
+  const iterationId = sanitizeId(requireValue(args, "iteration-id"));
+  const versionStatus = requireValue(args, "version-status");
+  if (!new Set(["release-ready", "released", "abandoned"]).has(versionStatus)) {
+    throw new Error("--version-status must be release-ready, released, or abandoned");
+  }
+  const releaseId = args["release-id"] && args["release-id"] !== true ? sanitizeId(args["release-id"]) : null;
+  const candidateId = args["candidate-id"] && args["candidate-id"] !== true
+    ? sanitizeId(args["candidate-id"])
+    : null;
+  if (versionStatus === "released" && !releaseId) throw new Error("released version archive requires --release-id");
+  if (versionStatus === "release-ready" && !candidateId) {
+    throw new Error("release-ready version archive requires --candidate-id");
+  }
+  const evidence = args.evidence || [];
+  if (!evidence.length) throw new Error("version archive requires at least one --evidence");
+  const tasksDir = path.join(runtime, "tasks");
+  if (!fs.existsSync(tasksDir)) throw new Error(`No active task store found for version: ${iterationId}`);
+  return withTaskLock(runtime, `version.${iterationId}`, () => {
+    const portableArchiveDirectory = path.join(workflowRoot, "control", "archives", "versions", iterationId);
+    if (fs.existsSync(archivedVersionIndexFile(runtime, iterationId))
+      || fs.existsSync(path.join(portableArchiveDirectory, "version-manifest.json"))) {
+      throw new Error(`Version is already archived: ${iterationId}`);
+    }
+    const tasks = fs.readdirSync(tasksDir)
+      .filter((name) => name.endsWith(".json"))
+      .map((name) => normalizeTask(JSON.parse(fs.readFileSync(path.join(tasksDir, name), "utf8"))))
+      .filter((task) => task.iteration_id === iterationId);
+    if (!tasks.length) throw new Error(`No tasks found for version: ${iterationId}`);
+    const sharedById = new Map(readSharedTasks(workflowRoot, stateRoot).map((task) => [task.task_id, task]));
+    for (const task of tasks) {
+      const shared = sharedById.get(task.task_id);
+      if (!shared) throw new Error(`Shared task state not found: ${task.task_id}`);
+      assertTaskSourcesMatch(task, shared);
+    }
+    const notClosed = tasks.filter((task) => !CLOSED_STATUS.has(task.status));
+    if (notClosed.length) {
+      throw new Error(`Version ${iterationId} is not closed; active tasks: ${notClosed.map((task) => `${task.task_id}:${task.status}`).join(", ")}`);
+    }
+
+    const archivedAt = now();
+    const writeRuntimeArchive = !Boolean(args["portable-only"]);
+    const archiveDirectory = path.join(runtime, "archive", "versions", iterationId);
+    if (writeRuntimeArchive) {
+      tasks.map((task) => copyTaskToVersionArchive(runtime, task, archiveDirectory, archivedAt));
+    }
+    const archivedTasks = tasks.map((task) =>
+      copyTaskToPortableArchive(stateRoot, workflowRoot, task, portableArchiveDirectory, archivedAt));
+    const relativeArchive = path.relative(stateRoot, portableArchiveDirectory).replaceAll("\\", "/");
+    const manifest = {
+      iteration_id: iterationId,
+      version_status: versionStatus,
+      release_id: releaseId,
+      candidate_id: candidateId,
+      evidence,
+      task_count: archivedTasks.length,
+      archived_at: archivedAt,
+      archive_path: relativeArchive,
+      tasks: archivedTasks.map((task) => ({
+        task_id: task.task_id,
+        node: task.node,
+        skill: task.skill,
+        status: task.status,
+        finished_at: task.finished_at,
+        archive_path: task.archive_path,
+      })),
+    };
+    if (writeRuntimeArchive) atomicWrite(path.join(archiveDirectory, "version-manifest.json"), manifest);
+    atomicWrite(path.join(portableArchiveDirectory, "version-manifest.json"), manifest);
+    if (writeRuntimeArchive) {
+      atomicWrite(archivedVersionIndexFile(runtime, iterationId), manifest);
+      for (const task of archivedTasks) {
+        atomicWrite(archivedTaskIndexFile(runtime, task.task_id), {
+          task_id: task.task_id,
+          iteration_id: iterationId,
+          status: task.status,
+          archive_path: task.archive_path,
+        });
+      }
+    }
+    for (const task of tasks) {
+      removeActiveTaskBundle(runtime, task);
+      removeSharedTaskBundle(workflowRoot, task);
+    }
+    return { ...manifest, runtime_archive_created: writeRuntimeArchive, archived_tasks: manifest.tasks };
+  });
+}
+
+function commandRecover(args) {
+  const { runtime, workflowRoot, stateRoot } = statePaths(args);
+  const tasksDir = path.join(runtime, "tasks");
+  const staleMs = Number(args["stale-minutes"] || 15) * 60_000;
+  const requested = args["task-id"] ? sanitizeId(args["task-id"]) : null;
+  const requestedIteration = args["iteration-id"] ? sanitizeId(args["iteration-id"]) : null;
+  const includeClosed = Boolean(args["include-closed"]);
+  const localTasks = readRuntimeTasks(runtime);
+  const localById = new Map(localTasks.map((task) => [task.task_id, task]));
+  for (const shared of readSharedTasks(workflowRoot, stateRoot)) {
+    const local = localById.get(shared.task_id);
+    if (!local) {
+      localById.set(shared.task_id, shared);
+      if (shared.next_action_owner === "agent") atomicWrite(taskFile(runtime, shared.task_id), shared);
+    } else {
+      assertTaskSourcesMatch(local, shared);
+    }
+  }
+  const allTasks = [...localById.values()];
+  if (!allTasks.length) return { tasks: [], iterations: [], message: "No local or shared tasks found." };
+  const selectedTasks = requestedIteration
+    ? allTasks.filter((task) => task.iteration_id === requestedIteration)
+    : allTasks;
+  const iterationIds = [...new Set(selectedTasks.map((task) => task.iteration_id))].sort();
+  const reports = [];
+  for (const task of selectedTasks.sort(compareTasks)) {
+    if (requested && task.task_id !== requested) continue;
+    if (!includeClosed && CLOSED_STATUS.has(task.status)) continue;
+    const heartbeatFile = path.join(runtime, "heartbeats", `${task.task_id}.json`);
+    const heartbeat = fs.existsSync(heartbeatFile) ? JSON.parse(fs.readFileSync(heartbeatFile, "utf8")) : null;
+    const latest = new Date(heartbeat?.updated_at || task.updated_at).getTime();
+    const stale = task.status === "running" && Date.now() - latest > staleMs;
+    const worktreeExists = Boolean(task.worktree && fs.existsSync(task.worktree));
+    const git = worktreeExists ? gitState(task.worktree) : { repository: false };
+    const branchMatches = !task.branch || (git.repository && task.branch === git.branch);
+    const warnings = [];
+    if (!worktreeExists) warnings.push("Recorded worktree does not exist; locate or recreate it before resuming.");
+    if (task.branch && !git.repository) warnings.push("Recorded worktree is not a Git repository; reconcile it before resuming.");
+    else if (!branchMatches) warnings.push(`Recorded branch ${task.branch} differs from current branch ${git.branch || "(detached)"}.`);
+    const reconciliation = {
+      heartbeat,
+      stale_running_task: stale,
+      suggested_status: stale ? "interrupted" : task.status,
+      worktree_exists: worktreeExists,
+      branch_matches: branchMatches,
+      warnings,
+      git,
+    };
+    if (stale && args["mark-interrupted"]) {
+      withTaskLock(runtime, task.task_id, () => {
+        const current = readTask(runtime, task.task_id);
+        if (current.next_action_owner !== "agent") {
+          throw new Error(
+            `Task ${current.task_id} is waiting for ${current.next_action_owner}; recover --mark-interrupted cannot mutate a wait state.`,
+          );
+        }
+        current.status = "interrupted";
+        current.updated_at = now();
+        current.next_action ||= "Reconcile workspace and resume the last idempotent action.";
+        writeSharedTask(runtime, workflowRoot, current);
+        appendEvent(runtime, current.task_id, "task-interrupted", { reason: "stale-heartbeat" });
+        Object.assign(task, current);
+      });
+    }
+    if (task.next_action_owner === "agent") writeResume(runtime, task, reconciliation);
+    reports.push({ task, reconciliation });
+  }
+  return {
+    tasks: reports,
+    iterations: iterationIds.map((iterationId) => summarizeIteration(allTasks, iterationId)),
+  };
+}
+
+function commandPublish(args) {
+  const taskId = sanitizeId(requireValue(args, "task-id"));
+  const { stateRoot, workflowRoot } = statePaths(args);
+  const sharedFile = sharedTaskFile(workflowRoot, taskId);
+  const checkpointDirectory = path.join(workflowRoot, "control", "checkpoints", taskId);
+  if (!fs.existsSync(sharedFile)) throw new Error(`Shared task state not found: ${taskId}`);
+
+  const repository = gitState(stateRoot);
+  if (!repository.repository || path.resolve(repository.root).toLowerCase() !== path.resolve(stateRoot).toLowerCase()) {
+    throw new Error("Shared task state must be published from the workflow Git repository root.");
+  }
+  const workspaceFile = path.join(stateRoot, ".workflow", "config", "workspace.yaml");
+  if (!fs.existsSync(workspaceFile)) throw new Error(`Workspace configuration is missing: ${workspaceFile}`);
+  const workspaceText = fs.readFileSync(workspaceFile, "utf8");
+  const workflowSection = workspaceText.match(/^workflow_repository:\s*\r?\n((?:[ \t]+.*(?:\r?\n|$))*)/m)?.[1] || "";
+  const scalar = (text, key) => {
+    const raw = text.match(new RegExp(`^\\s+${key}:\\s*(.+?)\\s*$`, "m"))?.[1];
+    if (!raw || raw === "null" || raw === "~") return null;
+    return raw.replace(/^['"]|['"]$/g, "");
+  };
+  const expectedBranch = scalar(workflowSection, "branch");
+  const configuredRemote = scalar(workflowSection, "remote");
+  if (!expectedBranch || repository.branch !== expectedBranch) {
+    throw new Error(`Workflow state can only be published from ${expectedBranch || "the configured workflow branch"}; current branch is ${repository.branch || "detached"}.`);
+  }
+  const origin = spawnSync("git", ["remote", "get-url", "origin"], {
+    cwd: stateRoot, encoding: "utf8", windowsHide: true,
+  });
+  const normalizeRemote = (value) => {
+    if (!value) return null;
+    const candidate = value.trim();
+    return path.isAbsolute(candidate)
+      ? path.resolve(candidate).replaceAll("\\", "/").toLowerCase()
+      : candidate.replaceAll("\\", "/").replace(/\/$/, "");
+  };
+  if (configuredRemote && (origin.status !== 0
+    || normalizeRemote(origin.stdout) !== normalizeRemote(configuredRemote))) {
+    throw new Error("Workflow origin does not match .workflow/config/workspace.yaml.");
+  }
+  if (args.push && !configuredRemote) throw new Error("--push requires a configured workflow remote.");
+  const upstream = spawnSync("git", ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"], {
+    cwd: stateRoot, encoding: "utf8", windowsHide: true,
+  });
+  if (upstream.status === 0 && upstream.stdout.trim() !== `origin/${expectedBranch}`) {
+    throw new Error(`Workflow upstream must be origin/${expectedBranch}, found ${upstream.stdout.trim()}.`);
+  }
+  const shared = JSON.parse(fs.readFileSync(sharedFile, "utf8"));
+  const workflowDocumentRoot = path.join(stateRoot, ".workflow");
+  const taskOwnedArtifacts = [...(shared.actual_outputs || []), ...(shared.evidence || [])]
+    .map((value) => String(value).replaceAll("\\", "/"))
+    .filter((value) => value.startsWith(".workflow/"))
+    .filter((value) => {
+      const absolute = path.resolve(stateRoot, value);
+      const relative = path.relative(workflowDocumentRoot, absolute);
+      return !relative.startsWith("..") && !path.isAbsolute(relative) && fs.existsSync(absolute);
+    });
+  const allowed = [
+    path.relative(stateRoot, sharedFile).replaceAll("\\", "/"),
+    `${path.relative(stateRoot, checkpointDirectory).replaceAll("\\", "/")}/`,
+    ...taskOwnedArtifacts,
+  ];
+  const status = spawnSync("git", ["status", "--porcelain=v1", "--untracked-files=all"], {
+    cwd: stateRoot,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (status.status !== 0) throw new Error(`Cannot inspect workflow Git state: ${status.stderr.trim()}`);
+  const dirty = status.stdout.split(/\r?\n/).filter(Boolean).map((line) => line.slice(3).replaceAll("\\", "/"));
+  const unrelated = dirty.filter((file) => !allowed.some((entry) => entry.endsWith("/") ? file.startsWith(entry) : file === entry));
+  if (unrelated.length) throw new Error(`Workflow repository has unrelated dirty paths: ${unrelated.join(", ")}`);
+  if (!dirty.length) return { task_id: taskId, published: false, pushed: false, message: "Shared task state is already committed." };
+
+  const addPaths = allowed.map((entry) => entry.endsWith("/") ? entry.slice(0, -1) : entry);
+  const add = spawnSync("git", ["add", "--", ...addPaths], {
+    cwd: stateRoot,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (add.status !== 0) throw new Error(`Cannot stage shared task state: ${add.stderr.trim()}`);
+  const commit = spawnSync("git", ["commit", "-m", `workflow(task): publish ${taskId} r${shared.shared_revision}`], {
+    cwd: stateRoot,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (commit.status !== 0) throw new Error(`Cannot commit shared task state: ${commit.stderr.trim()}`);
+  const head = spawnSync("git", ["rev-parse", "HEAD"], { cwd: stateRoot, encoding: "utf8", windowsHide: true });
+  let pushed = false;
+  if (args.push) {
+    const pushArgs = upstream.status === 0
+      ? ["push", "origin", `HEAD:refs/heads/${expectedBranch}`]
+      : ["push", "--set-upstream", "origin", `HEAD:refs/heads/${expectedBranch}`];
+    const push = spawnSync("git", pushArgs, { cwd: stateRoot, encoding: "utf8", windowsHide: true });
+    if (push.status !== 0) throw new Error(`Shared state was committed but push failed: ${push.stderr.trim()}`);
+    pushed = true;
+  }
+  return { task_id: taskId, published: true, pushed, workflow_commit: head.stdout.trim() };
+}
+
+function taskEvolutionContext(args, command) {
+  if (!new Set(["init", "activate", "checkpoint", "finish", "archive-version"]).has(command)) return null;
+  const projectRoot = path.resolve(args.root || findProjectRoot());
+  const evolutionCli = path.join(projectRoot, ".workflow", "tools", "evolution", "evolve.mjs");
+  if (!fs.existsSync(evolutionCli)) return null;
+  const taskId = args["task-id"] && args["task-id"] !== true ? String(args["task-id"]) : null;
+  let revision = 0;
+  if (taskId) {
+    try {
+      const { runtime, workflowRoot } = statePaths(args);
+      const localFile = taskFile(runtime, taskId);
+      const sharedFile = sharedTaskFile(workflowRoot, taskId);
+      const sourceFile = fs.existsSync(localFile) ? localFile : sharedFile;
+      const task = JSON.parse(fs.readFileSync(sourceFile, "utf8"));
+      revision = Number(task.shared_revision || 0);
+    } catch {
+      revision = 0;
+    }
+  }
+  return {
+    projectRoot,
+    evolutionCli,
+    command,
+    taskId,
+    iterationId: args["iteration-id"] && args["iteration-id"] !== true ? String(args["iteration-id"]) : null,
+    revision,
+  };
+}
+
+function dispatchTaskEvolution(context, phase, result = null, error = null) {
+  if (!context) return { decision: "pass" };
+  const identity = context.taskId || context.iterationId || "unspecified";
+  const idempotencyKey = `task-state-task-${phase}-${context.command}-${identity}-r${context.revision}`;
+  const event = {
+    schema_version: 1,
+    event_id: `EVT-${crypto.createHash("sha256").update(idempotencyKey).digest("hex").slice(0, 24)}`,
+    idempotency_key: idempotencyKey,
+    event_type: `task.${phase}`,
+    occurred_at: now(),
+    sequence: context.revision,
+    scope: {
+      task_id: context.taskId,
+      iteration_id: context.iterationId || result?.iteration_id || null,
+      action: context.command,
+    },
+    source_ref: { command: context.command, shared_revision: context.revision },
+    payload: error
+      ? { outcome: "failed", error: error.message }
+      : { outcome: phase === "before" ? "pending" : "succeeded", status: result?.status || null },
+  };
+  const dispatched = spawnSync(process.execPath, [
+    context.evolutionCli, "hook", "dispatch", "--input", "-", "--project", context.projectRoot,
+  ], {
+    cwd: context.projectRoot,
+    input: JSON.stringify(event),
+    encoding: "utf8",
+    timeout: 15_000,
+    windowsHide: true,
+  });
+  if (dispatched.error || dispatched.status !== 0) {
+    return { decision: "warn", messages: [dispatched.error?.message || dispatched.stderr || "Evolution Hook dispatch failed."], evidence_refs: [] };
+  }
+  try {
+    return JSON.parse(dispatched.stdout || "{}");
+  } catch {
+    return { decision: "warn", messages: ["Evolution Hook returned invalid JSON."], evidence_refs: [] };
+  }
+}
+
+const args = parseArgs(process.argv.slice(2));
+const command = args._[0];
+const evolutionContext = taskEvolutionContext(args, command);
+try {
+  const before = dispatchTaskEvolution(evolutionContext, "before");
+  if (before.decision === "block") {
+    throw new Error(`Evolution Hook blocked ${command}: ${(before.messages || []).join("; ") || "no rationale"}`);
+  }
+  let result;
+  if (command === "init") result = commandInit(args);
+  else if (command === "activate") result = commandActivate(args);
+  else if (command === "checkpoint") result = commandUpdate(args, false);
+  else if (command === "finish") result = commandUpdate(args, true);
+  else if (command === "archive-version") result = commandArchiveVersion(args);
+  else if (command === "recover") result = commandRecover(args);
+  else if (command === "publish") result = commandPublish(args);
+  else throw new Error("Use init, activate, checkpoint, finish, archive-version, recover, or publish.");
+  dispatchTaskEvolution(evolutionContext, "after", result);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} catch (error) {
+  dispatchTaskEvolution(evolutionContext, "failed", null, error);
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}