@cassiomc1/forgeloop 1.2.4 → 1.5.0

package/src/core/task-recovery.js

@@ -0,0 +1,205 @@
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { LEGACY_RECOVERY_MIGRATION_EVENT } from "./task-recovery-migration.js";
+import { readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import {
+  E_TASK_RECOVERY_AUTHORITY_INVALID,
+} from "./error-codes.js";
+import { taskArtifactPath } from "./task-paths.js";
+import { getActiveTaskTransaction } from "./transaction.js";
+import { classifyRecoveryHistory } from "./recovery-history.js";
+
+export const TASK_RECOVERY_SCHEMA_VERSION = 1;
+export const TASK_RECOVERY_EVENT_TYPES = Object.freeze(new Set([
+  "TASK_RECOVERY_RECORDED",
+  "OPERATOR_RECOVERY_RECORDED",
+  LEGACY_RECOVERY_MIGRATION_EVENT,
+]));
+
+export function createTaskRecovery({
+  taskId,
+  recoveredAt,
+  recoveryId,
+  recoveryEventSeq,
+  classificationAtRecovery,
+  reasonCodes,
+  releasedClaims,
+  previousPhase,
+  previousRevision,
+  repositoryFingerprint,
+  authority,
+}) {
+  const recovery = {
+    schemaVersion: TASK_RECOVERY_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId,
+    status: "RECOVERED",
+    recoveredAt,
+    recoveryId,
+    recoveryEventSeq,
+    classificationAtRecovery,
+    reasonCodes: [...reasonCodes],
+    releasedClaims: [...releasedClaims],
+    previousPhase,
+    previousRevision,
+    repositoryFingerprint: { ...repositoryFingerprint },
+    authority: { ...authority },
+  };
+  assertTaskRecoveryAuthority(recovery);
+  return recovery;
+}
+
+export function assertTaskRecoveryAuthority(recovery) {
+  const authority = recovery?.authority;
+  const validCaller = authority?.kind === "CALLER_ACKNOWLEDGED" && authority.grantRef === undefined;
+  const validHost = authority?.kind === "HOST_ATTESTED"
+    && typeof authority.grantRef === "string"
+    && authority.grantRef.trim() !== "";
+  if (validCaller || validHost) return recovery;
+  const error = new Error(
+    "Recovery authority must be caller acknowledgement or host attestation with a trusted grant reference",
+  );
+  error.code = E_TASK_RECOVERY_AUTHORITY_INVALID;
+  throw error;
+}
+
+export async function readTaskRecovery(target, { taskId, packageRoot } = {}) {
+  try {
+    const artifact = await readJsonArtifact(target, taskArtifactPath(taskId, "recovery"), "task-recovery", packageRoot);
+    assertTaskRecoveryAuthority(artifact.value);
+    return artifact;
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") return null;
+    throw error;
+  }
+}
+
+export function writeTaskRecovery(target, recovery, packageRoot) {
+  assertTaskRecoveryAuthority(recovery);
+  return writeJsonArtifact(
+    target,
+    taskArtifactPath(recovery.taskId, "recovery"),
+    recovery,
+    "task-recovery",
+    packageRoot,
+    { taskId: recovery.taskId, operation: "write-task-recovery" },
+  );
+}
+
+export async function clearTaskRecovery(target, { taskId } = {}) {
+  const transaction = getActiveTaskTransaction();
+  if (!transaction) {
+    throw new Error("clearTaskRecovery requires an active task transaction");
+  }
+  await transaction.stageDelete(taskArtifactPath(taskId, "recovery"));
+}
+
+export function isTaskRecovered(recovery) {
+  return recovery?.status === "RECOVERED";
+}
+
+export async function assertTaskNotRecovered(target, { taskId, packageRoot } = {}) {
+  const { assertTaskMutationAllowed } = await import("./task-claim-state.js");
+  return assertTaskMutationAllowed(target, { taskId, packageRoot });
+}
+
+export function effectiveTaskClaims({
+  validatedClaimState = null,
+  historicalWriteClaims = null,
+  writeClaims = [],
+} = {}) {
+  const historical = historicalWriteClaims ?? writeClaims;
+  // Only VALIDATED canonical ownership may release claims. A bare
+  // `phase === "COMPLETE"` never proves completion ownership.
+  const validatedRelease = validatedClaimState?.valid === true
+    && ["RELEASED_BY_COMPLETION", "RELEASED_BY_RECOVERY"].includes(validatedClaimState.claimState);
+  return validatedRelease ? [] : [...historical];
+}
+
+export function taskClaimProjection({
+  validatedClaimState = null,
+  historicalWriteClaims: suppliedHistoricalClaims = null,
+  writeClaims = [],
+} = {}) {
+  const historicalWriteClaims = [...(suppliedHistoricalClaims ?? writeClaims)];
+  const effectiveWriteClaims = effectiveTaskClaims({
+    validatedClaimState,
+    historicalWriteClaims,
+  });
+  const claimState = validatedClaimState?.valid === true
+    ? validatedClaimState.claimState
+    : "ACTIVE";
+  return {
+    writeClaims: effectiveWriteClaims,
+    historicalWriteClaims,
+    effectiveWriteClaims,
+    claimState,
+    mutationAllowed: claimState === "ACTIVE",
+  };
+}
+
+function sameList(left, right) {
+  return Array.isArray(left)
+    && Array.isArray(right)
+    && left.length === right.length
+    && left.every((value, index) => value === right[index]);
+}
+
+function recoveryConsistencyError(message) {
+  return { code: "E_TASK_RECOVERY_INCONSISTENT", message };
+}
+
+export function validateTaskRecoveryConsistency({
+  taskId,
+  recovery = null,
+  events = [],
+  historicalWriteClaims = null,
+  recoveryHistory = null,
+} = {}) {
+  const history = recoveryHistory ?? classifyRecoveryHistory(events);
+  const errors = [...history.errors];
+
+  if (!recovery) {
+    if (history.valid && history.activeRecovery) {
+      errors.push(recoveryConsistencyError(
+        `Recovery event ${history.activeRecovery.recoveryId} has neither an active recovery artifact nor a resume event`,
+      ));
+    }
+    return errors;
+  }
+  if (!history.activeRecovery || history.activeRecovery.recoveryId !== recovery.recoveryId) {
+    errors.push(recoveryConsistencyError(
+      `Recovery artifact ${recovery.recoveryId ?? "unknown"} does not match the active recovery history`,
+    ));
+  }
+  if (recovery.taskId !== taskId) {
+    errors.push(recoveryConsistencyError(`Recovery artifact belongs to ${recovery.taskId}, not ${taskId}`));
+  }
+  const event = events.find((candidate) => candidate.seq === recovery.recoveryEventSeq);
+  if (!event || !TASK_RECOVERY_EVENT_TYPES.has(event.event)) {
+    errors.push(recoveryConsistencyError(
+      `Recovery artifact references missing recovery event seq ${recovery.recoveryEventSeq}`,
+    ));
+    return errors;
+  }
+
+  const comparisons = [
+    [event.taskId === recovery.taskId, "taskId"],
+    [event.at === recovery.recoveredAt, "recoveredAt"],
+    [event.details?.recoveryId === recovery.recoveryId, "recoveryId"],
+    [event.details?.classification === recovery.classificationAtRecovery, "classificationAtRecovery"],
+    [sameList(event.details?.reasonCodes, recovery.reasonCodes), "reasonCodes"],
+    [sameList(event.details?.releasedClaims, recovery.releasedClaims), "releasedClaims"],
+    [event.details?.previousPhase === recovery.previousPhase, "previousPhase"],
+    [event.details?.previousRevision === recovery.previousRevision, "previousRevision"],
+    [event.details?.currentBranch === recovery.repositoryFingerprint?.branch, "repositoryFingerprint.branch"],
+    [event.details?.currentHead === recovery.repositoryFingerprint?.head, "repositoryFingerprint.head"],
+    [event.details?.authorityKind === recovery.authority?.kind, "authority.kind"],
+  ];
+  for (const [matches, field] of comparisons) {
+    if (!matches) errors.push(recoveryConsistencyError(`Recovery artifact and ledger disagree on ${field}`));
+  }
+  if (historicalWriteClaims && !sameList(historicalWriteClaims, recovery.releasedClaims)) {
+    errors.push(recoveryConsistencyError("Recovery releasedClaims do not match the task descriptor's historical claims"));
+  }
+  return errors;
+}

package/src/core/task-scope.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import {
   E_TASK_CHANGE_OUTSIDE_SCOPE,
+  E_TASK_CLAIM_OWNERSHIP_INCONSISTENT,
   E_TASK_DESCRIPTOR_INVALID,
   E_TASK_SCOPE_CONFLICT,
   E_TASK_SCOPE_DIRTY,
@@ -93,7 +94,9 @@ export function checkScopeConflicts(newClaims, existingTasks = [], currentTaskId
     // Only non-COMPLETE tasks hold active write claims
     if (task.phase === "COMPLETE") continue;
 
-    const taskClaims = normalizeWriteClaims(task.writeClaims ?? task.descriptor?.writeClaims ?? []);
+    const taskClaims = normalizeWriteClaims(task.claimState === undefined
+      ? (task.writeClaims ?? task.descriptor?.writeClaims ?? [])
+      : (task.effectiveWriteClaims ?? []));
     for (const newClaim of normalizedNew) {
       for (const existingClaim of taskClaims) {
         if (claimsOverlap(newClaim, existingClaim)) {
@@ -112,6 +115,35 @@ export function checkScopeConflicts(newClaims, existingTasks = [], currentTaskId
 }
 
 export function assertNoScopeConflicts(newClaims, existingTasks = [], currentTaskId = null) {
+  const normalizedNew = normalizeWriteClaims(newClaims);
+  if (normalizedNew.length > 0) {
+    const ownershipBlockers = existingTasks.filter((task) => {
+      if (task.taskId === currentTaskId) return false;
+      if (task.healthy === false) return true;
+      if (task.claimState !== "INCONSISTENT" && task.ownershipValid !== false) return false;
+      const retainedClaims = normalizeWriteClaims(
+        task.effectiveWriteClaims ?? task.writeClaims ?? task.descriptor?.writeClaims ?? [],
+      );
+      return retainedClaims.length === 0
+        || normalizedNew.some((claim) => retainedClaims.some((retained) => claimsOverlap(claim, retained)));
+    });
+    if (ownershipBlockers.length > 0) {
+      const error = new Error(
+        `Cannot acquire write claims while task ownership is inconsistent: ${ownershipBlockers
+          .map((task) => task.taskId ?? task.taskKey)
+          .join(", ")}`,
+      );
+      error.code = E_TASK_CLAIM_OWNERSHIP_INCONSISTENT;
+      error.tasks = ownershipBlockers.map((task) => ({
+        taskId: task.taskId ?? null,
+        taskKey: task.taskKey ?? null,
+        claimState: task.claimState ?? "INCONSISTENT",
+        reasonCodes: task.reasonCodes ?? [task.error?.code].filter(Boolean),
+      }));
+      throw error;
+    }
+  }
+
   const conflicts = checkScopeConflicts(newClaims, existingTasks, currentTaskId);
   if (conflicts.length > 0) {
     const first = conflicts[0];

package/src/core/templates.js

@@ -66,6 +66,7 @@ export const TEMPLATE_PATHS = [
   "schemas/task-bundle.schema.json",
   "schemas/authority.schema.json",
   "schemas/task-descriptor.schema.json",
+  "schemas/task-recovery.schema.json",
 ];
 
 export function getPackageRoot() {

package/src/core/transaction.js

@@ -0,0 +1,285 @@
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { mkdir, open, readdir, readFile, rename, stat, truncate, unlink } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import path from "node:path";
+
+import { assertSafePath, ensureWithin, fileExists, writeFileAtomic } from "./filesystem.js";
+import { withTaskLock } from "./task-lock.js";
+import { E_TASK_LOCKED } from "./error-codes.js";
+
+const TRANSACTION_ROOT = ".forgeloop/.txn";
+const LOCK_WAIT_TIMEOUT_MS = 5_000;
+const transactionContext = new AsyncLocalStorage();
+
+export function getActiveTaskTransaction() {
+  return transactionContext.getStore() ?? null;
+}
+
+function transactionPath(transactionId) {
+  return `${TRANSACTION_ROOT}/${transactionId}`;
+}
+
+async function writeManifest(target, relativePath, manifest) {
+  await writeFileAtomic(ensureWithin(target, relativePath), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+export async function findIncompleteTransactions(target) {
+  const root = ensureWithin(target, TRANSACTION_ROOT);
+  if (!(await fileExists(root))) return [];
+  const entries = await readdir(root, { withFileTypes: true });
+  const found = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    try {
+      const manifest = JSON.parse(await readFile(path.join(root, entry.name, "manifest.json"), "utf8"));
+      if (manifest.status !== "COMMITTED") found.push(manifest);
+    } catch {
+      found.push({ transactionId: entry.name, status: "ABANDONED", malformed: true });
+    }
+  }
+  return found;
+}
+
+function writePath(entry) {
+  return typeof entry === "string" ? entry : entry.path;
+}
+
+async function rollbackPublishedWrites(target, root, manifest) {
+  const writes = [...manifest.writes].reverse();
+  for (const entry of writes) {
+    if (!entry || typeof entry !== "object") continue;
+    const relativePath = writePath(entry);
+    if (entry.kind === "APPEND") {
+      if (!entry.appendStarted) continue;
+      const destination = ensureWithin(target, relativePath);
+      const originalSize = Number.isInteger(entry.originalSize) && entry.originalSize >= 0 ? entry.originalSize : 0;
+      if (await fileExists(destination)) {
+        if (originalSize === 0) await unlink(destination);
+        else await truncate(destination, originalSize);
+      }
+      continue;
+    }
+    if (!entry.published && !entry.backupPending && !entry.backupCreated) continue;
+    const destination = ensureWithin(target, relativePath);
+    const backup = ensureWithin(target, `${root}/backup/${relativePath}`);
+    if (entry.published && await fileExists(destination)) await unlink(destination);
+    if (entry.hadPrevious && await fileExists(backup)) {
+      await mkdir(path.dirname(destination), { recursive: true });
+      await rename(backup, destination);
+    }
+  }
+}
+
+export async function recoverIncompleteTransactions(target) {
+  const rootPath = ensureWithin(target, TRANSACTION_ROOT);
+  if (!(await fileExists(rootPath))) return [];
+  const recovered = [];
+  for (const entry of await readdir(rootPath, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const root = transactionPath(entry.name);
+    const manifestPath = `${root}/manifest.json`;
+    try {
+      const manifest = JSON.parse(await readFile(ensureWithin(target, manifestPath), "utf8"));
+      if (manifest.status !== "COMMITTING") continue;
+      await rollbackPublishedWrites(target, root, manifest);
+      manifest.status = "ROLLED_BACK";
+      manifest.recoveredAt = new Date().toISOString();
+      await writeManifest(target, manifestPath, manifest);
+      recovered.push({ transactionId: manifest.transactionId, status: manifest.status });
+    } catch (error) {
+      recovered.push({ transactionId: entry.name, status: "RECOVERY_FAILED", error: error.message });
+    }
+  }
+  return recovered;
+}
+
+export async function withTaskTransaction({
+  target,
+  taskId,
+  lockTaskId = taskId,
+  operation = "mutation",
+  packageRoot,
+  recordCommitEvent = false,
+} = {}, callback) {
+  if (!target || !taskId) throw new Error("target and taskId are required for a task transaction");
+  const started = Date.now();
+  const runWithLock = async () => withTaskLock(target, lockTaskId, operation, async (lock) => {
+    const transactionId = `txn-${randomUUID()}`;
+    const root = transactionPath(transactionId);
+    const stageRoot = `${root}/stage`;
+    const manifestPath = `${root}/manifest.json`;
+    await assertSafePath(target, manifestPath);
+    await mkdir(ensureWithin(target, stageRoot), { recursive: true });
+    const manifest = { schemaVersion: 1, transactionId, taskId, operation, lockId: lock.lockId, startedAt: new Date().toISOString(), status: "STAGING", writes: [] };
+    await writeManifest(target, manifestPath, manifest);
+    const tx = {
+      transactionId,
+      lock,
+      async readText(relativePath) {
+        await assertSafePath(target, relativePath);
+        if (manifest.writes.some((entry) => writePath(entry) === relativePath && entry.kind === "DELETE")) {
+          return null;
+        }
+        const staged = ensureWithin(target, `${stageRoot}/${relativePath}`);
+        if (await fileExists(staged)) return readFile(staged, "utf8");
+        const appendStaged = ensureWithin(target, `${stageRoot}/${relativePath}.append`);
+        const appendText = await fileExists(appendStaged) ? await readFile(appendStaged, "utf8") : "";
+        const destination = ensureWithin(target, relativePath);
+        if (!(await fileExists(destination))) return appendText || null;
+        return `${await readFile(destination, "utf8")}${appendText}`;
+      },
+      async stageText(relativePath, text) {
+        await assertSafePath(target, relativePath);
+        const conflicting = manifest.writes.find((entry) => writePath(entry) === relativePath);
+        if (conflicting?.kind === "APPEND" || conflicting?.kind === "DELETE") {
+          throw new Error(`cannot replace ${conflicting.kind.toLowerCase()}-staged path: ${relativePath}`);
+        }
+        const staged = `${stageRoot}/${relativePath}`;
+        await assertSafePath(target, staged);
+        await writeFileAtomic(ensureWithin(target, staged), text);
+        if (!manifest.writes.some((entry) => writePath(entry) === relativePath)) {
+          manifest.writes.push({ path: relativePath, hadPrevious: false, published: false });
+        }
+        await writeManifest(target, manifestPath, manifest);
+      },
+      async appendText(relativePath, text) {
+        await assertSafePath(target, relativePath);
+        if (typeof text !== "string" || text.length === 0) throw new Error("transaction append text must be a non-empty string");
+        if (manifest.writes.some((entry) => writePath(entry) === relativePath && entry.kind !== "APPEND")) {
+          throw new Error(`cannot append to replace-staged path: ${relativePath}`);
+        }
+        const destination = ensureWithin(target, relativePath);
+        const staged = ensureWithin(target, `${stageRoot}/${relativePath}.append`);
+        const existing = await fileExists(staged) ? await readFile(staged, "utf8") : "";
+        await writeFileAtomic(staged, `${existing}${text}`);
+        let entry = manifest.writes.find((candidate) => writePath(candidate) === relativePath);
+        if (!entry) {
+          entry = {
+            path: relativePath,
+            kind: "APPEND",
+            originalSize: (await fileExists(destination)) ? (await stat(destination)).size : 0,
+            appendStarted: false,
+            published: false,
+          };
+          manifest.writes.push(entry);
+        }
+        await writeManifest(target, manifestPath, manifest);
+      },
+      async stageDelete(relativePath) {
+        await assertSafePath(target, relativePath);
+        if (manifest.writes.some((entry) => writePath(entry) === relativePath)) {
+          throw new Error(`cannot delete write-staged path: ${relativePath}`);
+        }
+        const destination = ensureWithin(target, relativePath);
+        if (!(await fileExists(destination))) {
+          throw new Error(`transaction delete target is missing: ${relativePath}`);
+        }
+        manifest.writes.push({
+          path: relativePath,
+          kind: "DELETE",
+          hadPrevious: false,
+          published: false,
+        });
+        await writeManifest(target, manifestPath, manifest);
+      },
+    };
+    try {
+      const result = await transactionContext.run(tx, async () => {
+        const callbackResult = await callback(tx);
+        if (recordCommitEvent) {
+          // Import lazily to keep the transaction/event dependency directional
+          // at module initialization. The event is staged while this task's
+          // transaction context is still active and is published last below.
+          const { appendProtocolEvent } = await import("./events.js");
+          await appendProtocolEvent(target, {
+            taskId,
+            event: "TRANSACTION_COMMITTED",
+            details: { transactionId, operation },
+          }, packageRoot, { taskId });
+        }
+        return callbackResult;
+      });
+      manifest.status = "COMMITTING";
+      await writeManifest(target, manifestPath, manifest);
+      // The ledger is the commit witness. Publishing it last means that a
+      // visible TRANSACTION_COMMITTED event cannot precede a required staged
+      // artifact in the same transaction.
+      const writes = [...manifest.writes].sort((left, right) => {
+        const leftIsLedger = writePath(left).endsWith("events.ndjson");
+        const rightIsLedger = writePath(right).endsWith("events.ndjson");
+        return Number(leftIsLedger) - Number(rightIsLedger);
+      });
+      for (const entry of writes) {
+        const relativePath = writePath(entry);
+        const staged = ensureWithin(target, `${stageRoot}/${relativePath}`);
+        const destination = ensureWithin(target, relativePath);
+        if (entry.kind === "APPEND") {
+          const appendStaged = ensureWithin(target, `${stageRoot}/${relativePath}.append`);
+          const appendText = await readFile(appendStaged, "utf8");
+          await mkdir(path.dirname(destination), { recursive: true });
+          entry.appendStarted = true;
+          await writeManifest(target, manifestPath, manifest);
+          const handle = await open(destination, "a", 0o644);
+          try {
+            await handle.writeFile(appendText);
+            await handle.sync();
+          } finally {
+            await handle.close();
+          }
+          entry.published = true;
+          await writeManifest(target, manifestPath, manifest);
+          continue;
+        }
+        const backup = ensureWithin(target, `${root}/backup/${relativePath}`);
+        await mkdir(path.dirname(destination), { recursive: true });
+        entry.hadPrevious = await fileExists(destination);
+        if (entry.hadPrevious) {
+          entry.backupPending = true;
+          await writeManifest(target, manifestPath, manifest);
+          await mkdir(path.dirname(backup), { recursive: true });
+          await rename(destination, backup);
+          entry.backupCreated = true;
+        }
+        await writeManifest(target, manifestPath, manifest);
+        if (entry.kind === "DELETE") {
+          entry.published = true;
+          await writeManifest(target, manifestPath, manifest);
+          continue;
+        }
+        await rename(staged, destination);
+        entry.published = true;
+        await writeManifest(target, manifestPath, manifest);
+      }
+      manifest.status = "COMMITTED";
+      manifest.committedAt = new Date().toISOString();
+      await writeManifest(target, manifestPath, manifest);
+      return result;
+    } catch (error) {
+      if (manifest.status === "COMMITTING") {
+        try {
+          await rollbackPublishedWrites(target, root, manifest);
+          manifest.status = "ROLLED_BACK";
+          manifest.recoveredAt = new Date().toISOString();
+        } catch (rollbackError) {
+          manifest.status = "ABANDONED";
+          manifest.rollbackError = { message: rollbackError.message };
+        }
+      } else {
+        manifest.status = "ABANDONED";
+      }
+      manifest.failedAt = new Date().toISOString();
+      manifest.error = { message: error.message };
+      await writeManifest(target, manifestPath, manifest);
+      throw error;
+    }
+  });
+  while (true) {
+    try {
+      return await runWithLock();
+    } catch (error) {
+      if (error.code !== E_TASK_LOCKED || Date.now() - started >= LOCK_WAIT_TIMEOUT_MS) throw error;
+      await delay(20);
+    }
+  }
+}

package/src/core/work-state.js

@@ -19,6 +19,7 @@ import { assertJsonBytes } from "./json-safety.js";
 import { assertCoverageList } from "./coverage.js";
 import { canonicalFingerprint } from "./artifacts.js";
 import { taskArtifactPath } from "./task-paths.js";
+import { getActiveTaskTransaction, withTaskTransaction } from "./transaction.js";
 
 export const WORK_STATE_PATH = ".forgeloop/work-state.json";
 
@@ -163,6 +164,9 @@ export function assertWorkStateSemantics(state) {
   if (state.verificationCycle !== undefined && (!Number.isInteger(state.verificationCycle) || state.verificationCycle < 1)) {
     throw new WorkStateError("verificationCycle must be a positive integer");
   }
+  if (state.revision !== undefined && (!Number.isInteger(state.revision) || state.revision < 0)) {
+    throw new WorkStateError("revision must be a non-negative integer");
+  }
   if (state.lastCompletionAttempt !== undefined) {
     if (!state.lastCompletionAttempt || typeof state.lastCompletionAttempt !== "object" || Array.isArray(state.lastCompletionAttempt)) {
       throw new WorkStateError("lastCompletionAttempt must be an object");
@@ -216,6 +220,7 @@ export function createWorkState(input) {
     blockers: [...(input.blockers ?? [])],
     verificationEvidence: [...(input.verificationEvidence ?? [])],
     lastUpdated: input.lastUpdated ?? new Date().toISOString(),
+    revision: input.revision ?? 0,
   };
   if (input.verificationCycle !== undefined) state.verificationCycle = input.verificationCycle;
   if (input.lastCompletionAttempt !== undefined) state.lastCompletionAttempt = structuredClone(input.lastCompletionAttempt);
@@ -238,12 +243,20 @@ export async function readWorkState(target, options = {}) {
 
   await assertSafePath(target, relPath);
   const statePath = ensureWithin(target, relPath);
-  if (!(await fileExists(statePath))) return null;
   let state;
   try {
-    const bytes = await readBytes(statePath);
-    assertJsonBytes(bytes, relPath);
-    state = JSON.parse(bytes.toString("utf8"));
+    const transaction = getActiveTaskTransaction();
+    const staged = transaction ? await transaction.readText(relPath) : null;
+    if (staged === null) {
+      if (!(await fileExists(statePath))) return null;
+      const bytes = await readBytes(statePath);
+      assertJsonBytes(bytes, relPath);
+      state = JSON.parse(bytes.toString("utf8"));
+    } else {
+      const bytes = Buffer.from(staged, "utf8");
+      assertJsonBytes(bytes, relPath);
+      state = JSON.parse(staged);
+    }
   } catch (error) {
     throw new WorkStateError(`Unable to parse ${relPath}: ${error.message}`);
   }
@@ -276,11 +289,62 @@ export async function writeWorkState(target, state, options = {}) {
 
   await validateStoredState(state, packageRoot);
   await assertSafePath(target, relPath);
-  const statePath = ensureWithin(target, relPath);
-  await writeFileAtomic(statePath, `${JSON.stringify(state, null, 2)}\n`, { dryRun });
+  const serialized = `${JSON.stringify(state, null, 2)}\n`;
+  const transaction = getActiveTaskTransaction();
+  if (!dryRun && transaction) {
+    await transaction.stageText(relPath, serialized);
+  } else {
+    const statePath = ensureWithin(target, relPath);
+    await writeFileAtomic(statePath, serialized, { dryRun });
+  }
   return state;
 }
 
+export async function mutateWorkState(target, { expectedRevision, packageRoot = getPackageRoot(), taskId, statePath } = {}, updater) {
+  if (!Number.isInteger(expectedRevision) || expectedRevision < 0) {
+    const error = new WorkStateError("expectedRevision must be a non-negative integer");
+    error.code = "E_STATE_REVISION_CONFLICT";
+    throw error;
+  }
+  if (!getActiveTaskTransaction()) {
+    return withTaskTransaction({
+      target,
+      taskId: taskId ?? "legacy-work-state",
+      lockTaskId: taskId ?? "legacy-work-state",
+      operation: "mutate-work-state",
+    }, async () => mutateWorkState(target, { expectedRevision, packageRoot, taskId, statePath }, updater));
+  }
+  const current = await readWorkState(target, { packageRoot, taskId, statePath });
+  if (!current || (current.revision ?? 0) !== expectedRevision) {
+    const error = new WorkStateError("Work state revision does not match expected revision");
+    error.code = "E_STATE_REVISION_CONFLICT";
+    throw error;
+  }
+  const updated = await updater(structuredClone(current));
+  const next = createWorkState({
+    ...updated,
+    revision: expectedRevision + 1,
+    lastUpdated: updated.lastUpdated ?? new Date().toISOString(),
+  });
+  await writeWorkState(target, next, { packageRoot, taskId, statePath });
+  return next;
+}
+
+export async function initializeWorkState(target, state, { packageRoot = getPackageRoot(), taskId, statePath } = {}) {
+  if (getActiveTaskTransaction()) {
+    const current = await readWorkState(target, { packageRoot, taskId, statePath });
+    if (current) return current;
+    await writeWorkState(target, state, { packageRoot, taskId, statePath });
+    return state;
+  }
+  return withTaskTransaction({
+    target,
+    taskId: taskId ?? "legacy-work-state",
+    lockTaskId: taskId ?? "legacy-work-state",
+    operation: "initialize-work-state",
+  }, async () => initializeWorkState(target, state, { packageRoot, taskId, statePath }));
+}
+
 export async function clearWorkState(target, options = {}) {
   const relPath = options?.statePath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "state") : WORK_STATE_PATH);
   await assertSafePath(target, relPath);