@cassiomc1/forgeloop 1.2.3 → 1.3.0

package/src/core/phase.js

@@ -9,7 +9,7 @@ import {
 } from "./events.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { assertWorkPhase, isValidTransition } from "./protocol.js";
-import { readWorkState, writeWorkState } from "./work-state.js";
+import { readWorkState, mutateWorkState } from "./work-state.js";
 import { evaluateCompletion } from "./completion.js";
 import { evaluatePreflight } from "./preflight.js";
 import { requiredEvidenceForTarget } from "./completion-artifacts.js";
@@ -304,6 +304,7 @@ export async function advanceWorkState(target, toPhase, options = {}) {
     next.verificationCycle = reenteringVerification ? (state.verificationCycle ?? 1) + 1 : (state.verificationCycle ?? 1);
   }
   if (reenteringVerification) delete next.lastCompletionAttempt;
+  next.revision = (state.revision ?? 0) + 1;
   let nextReceipt = null;
   try {
     const receipt = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
@@ -361,7 +362,12 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   } catch (error) {
     if (error.code !== "ARTIFACT_MISSING") throw error;
   }
-  await writeWorkState(target, next, { packageRoot, taskId, statePath });
+  await mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId,
+    statePath,
+  }, () => next);
   if (nextReceipt) {
     await writeJsonArtifact(target, receiptRel, nextReceipt, "execution-receipt", packageRoot);
   }

package/src/core/protocol-info.js

@@ -0,0 +1,41 @@
+import { CLI_COMMAND_DEFINITIONS } from "./cli-command-definitions.js";
+import { ARTIFACT_REGISTRY } from "./artifact-registry.js";
+import { PUBLIC_ERROR_REGISTRY } from "./error-codes.js";
+import { GUIDE_REGISTRY } from "./guide-registry.js";
+import { PROTOCOL_VERSION, WORK_PHASES, WORK_TRANSITIONS } from "./protocol.js";
+
+export const SCHEMA_COMPATIBILITY_POLICY = Object.freeze({
+  protocolVersion: PROTOCOL_VERSION,
+  schemaVersion: 1,
+  read: "Readers reject unknown protocol or schema versions; compatibility changes require a new published version.",
+  write: "Writers emit only the current schema and protocol versions.",
+  migration: "Use migrate-protocol --to <version> --dry-run to plan an explicit supported migration. Legacy singleton artifacts are migrated with a receipt-backed task-migrate action.",
+});
+
+function publicSchemaVersions() {
+  return Object.fromEntries(
+    [...new Set(Object.values(ARTIFACT_REGISTRY)
+      .filter((artifact) => artifact.isPublic && artifact.isPersisted)
+      .map((artifact) => artifact.schema))]
+      .sort()
+      .map((schema) => [schema, [SCHEMA_COMPATIBILITY_POLICY.schemaVersion]]),
+  );
+}
+
+export function protocolInfo({ packageVersion = null } = {}) {
+  const errors = Object.values(PUBLIC_ERROR_REGISTRY);
+  const schemaVersions = publicSchemaVersions();
+  return {
+    packageVersion,
+    protocolVersion: PROTOCOL_VERSION,
+    readsProtocol: [PROTOCOL_VERSION],
+    writesProtocol: [PROTOCOL_VERSION],
+    readsSchemaVersions: schemaVersions,
+    writesSchemaVersions: schemaVersions,
+    compatibility: SCHEMA_COMPATIBILITY_POLICY,
+    lifecycle: { phases: WORK_PHASES, transitions: WORK_TRANSITIONS },
+    guides: Object.values(GUIDE_REGISTRY),
+    commands: Object.values(CLI_COMMAND_DEFINITIONS).map(({ name, category, mutation, description }) => ({ name, category, mutation, description })),
+    errors,
+  };
+}

package/src/core/protocol-migration.js

@@ -0,0 +1,59 @@
+import { E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED } from "./error-codes.js";
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { detectLegacySingletonLayout, migrateLegacyLayout } from "./task-migration.js";
+import { getPackageRoot } from "./templates.js";
+
+function assertSupportedTarget(to) {
+  if (to === undefined || to === null || to === "") {
+    const error = new Error("migrate-protocol requires --to <protocolVersion>");
+    error.code = E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED;
+    throw error;
+  }
+
+  if (String(to) !== String(PROTOCOL_VERSION)) {
+    const error = new Error(
+      `Protocol version ${to} is not supported by this ForgeLoop release; supported target: ${PROTOCOL_VERSION}.`,
+    );
+    error.code = E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED;
+    throw error;
+  }
+}
+
+/**
+ * Migrates only state that has an explicitly supported, receipt-backed path.
+ * Future protocol versions must add a dedicated migration before becoming an
+ * accepted target here; accepting an unknown target would risk silent rewrite.
+ */
+export async function migrateProtocol(
+  target,
+  { to, dryRun = false, packageRoot = getPackageRoot() } = {},
+) {
+  assertSupportedTarget(to);
+  const legacy = await detectLegacySingletonLayout(target);
+
+  if (!legacy.hasLegacy) {
+    return {
+      migrated: false,
+      dryRun,
+      fromProtocol: PROTOCOL_VERSION,
+      toProtocol: PROTOCOL_VERSION,
+      status: "ALREADY_COMPATIBLE",
+      actions: [],
+      message: `Target already uses supported protocol ${PROTOCOL_VERSION}; no migration is required.`,
+    };
+  }
+
+  const result = await migrateLegacyLayout(target, { dryRun, packageRoot });
+  return {
+    ...result,
+    fromProtocol: PROTOCOL_VERSION,
+    toProtocol: PROTOCOL_VERSION,
+    status: dryRun ? "PLANNED_LEGACY_LAYOUT_MIGRATION" : "MIGRATED_LEGACY_LAYOUT",
+    actions: [{
+      kind: "LEGACY_LAYOUT_MIGRATION",
+      command: "task-migrate",
+      receipt: ".forgeloop/task-state/<taskKey>/migration-receipt.json",
+      artifacts: legacy.legacyFiles.map((item) => item.path),
+    }],
+  };
+}

package/src/core/reconcile-closure.js

@@ -1,9 +1,11 @@
 import { readContract } from "./contract.js";
+import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { appendProtocolEvent, validateEventLedger } from "./events.js";
 import { runCommandExecution } from "./execution.js";
+import { createReceipt } from "./receipt.js";
 import { currentRepositoryFingerprint } from "./repository.js";
 import { taskArtifactPath } from "./task-paths.js";
-import { classifyLoadedWorkState, readWorkState, writeWorkState } from "./work-state.js";
+import { classifyLoadedWorkState, readWorkState, mutateWorkState } from "./work-state.js";
 
 export const RECONCILE_EVENT = "CHECKPOINT_RECONCILED";
 
@@ -63,6 +65,7 @@ export async function runReconcileClosure({
   const stateRel = taskArtifactPath(taskId, "state");
   const contractRel = taskArtifactPath(taskId, "contract");
   const eventsRel = taskArtifactPath(taskId, "events");
+  const receiptRel = taskArtifactPath(taskId, "receipt");
 
   const state = await readWorkState(target, { packageRoot, taskId });
   if (!state) {
@@ -154,11 +157,26 @@ export async function runReconcileClosure({
     },
   }, packageRoot, { taskId });
 
-  await writeWorkState(target, {
+  const nextState = await mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId,
+  }, () => ({
     ...state,
     repositoryFingerprint: repository,
     lastUpdated: new Date().toISOString(),
-  }, { packageRoot, taskId });
+  }));
+
+  try {
+    const receipt = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
+    const reboundReceipt = await createReceipt({
+      ...receipt.value,
+      stateFingerprint: canonicalFingerprint(nextState),
+    }, packageRoot, { target, taskId, authorityContext, runtimeContext });
+    await writeJsonArtifact(target, receiptRel, reboundReceipt, "execution-receipt", packageRoot);
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
 
   return {
     taskId,
@@ -172,4 +190,4 @@ export async function runReconcileClosure({
     executionPath: execution.path,
     event: RECONCILE_EVENT,
   };
-}
+}

package/src/core/resumability.js

@@ -1,5 +1,5 @@
 import { currentRepositoryFingerprint } from "./repository.js";
-import { createWorkState, readWorkState, writeWorkState } from "./work-state.js";
+import { createWorkState, initializeWorkState, readWorkState, mutateWorkState } from "./work-state.js";
 
 const DEFAULT_PENDING_STEPS = ["planning", "implementation", "verification"];
 
@@ -22,8 +22,7 @@ export async function ensureResumableState({ target, packageRoot, contract, rout
     blockers: [],
     verificationEvidence: [],
   });
-  await writeWorkState(target, state, { packageRoot, taskId, statePath });
-  return state;
+  return initializeWorkState(target, state, { packageRoot, taskId, statePath });
 }
 
 export async function synchronizePreflightState({
@@ -57,7 +56,10 @@ export async function synchronizePreflightState({
   if (JSON.stringify(withoutTimestamp(candidate)) === JSON.stringify(withoutTimestamp(state))) {
     return state;
   }
-  const next = { ...candidate, lastUpdated: new Date().toISOString() };
-  await writeWorkState(target, next, { packageRoot, taskId, statePath });
-  return next;
+  return mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId,
+    statePath,
+  }, () => ({ ...candidate, lastUpdated: new Date().toISOString() }));
 }

package/src/core/task-command.js

@@ -1,5 +1,5 @@
 import { resolveTaskContext } from "./task-context.js";
-import { withTaskLock } from "./task-lock.js";
+import { withTaskTransaction } from "./transaction.js";
 
 export async function withResolvedTask(
   target,
@@ -32,8 +32,8 @@ export async function withTaskMutation(
   });
 
   if (taskContext) {
-    return withTaskLock(target, taskContext.taskId, operation, async () => {
-      return callback(taskContext);
+    return withTaskTransaction({ target, taskId: taskContext.taskId, operation, packageRoot: options.packageRoot, recordCommitEvent: true }, async (transaction) => {
+      return callback({ ...taskContext, transaction });
     });
   }
 

package/src/core/task-lock.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { mkdir, open, readFile, unlink } from "node:fs/promises";
 import path from "node:path";
+import os from "node:os";
 import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
 import { taskLockPath } from "./task-paths.js";
 import { E_TASK_LOCKED } from "./error-codes.js";
@@ -22,6 +23,25 @@ export async function readLockInfo(target, taskId) {
   }
 }
 
+export function classifyLockStaleness(lock, now = Date.now()) {
+  if (!lock || lock.corrupted) return { status: "UNKNOWN", stale: false };
+  const heartbeat = Date.parse(lock.heartbeatAt ?? lock.acquiredAt);
+  const leaseMs = Number.isInteger(lock.leaseMs) && lock.leaseMs > 0 ? lock.leaseMs : 300000;
+  if (!Number.isFinite(heartbeat)) return { status: "UNKNOWN", stale: false };
+  return now > heartbeat + leaseMs
+    ? { status: "STALE", stale: true, expiresAt: new Date(heartbeat + leaseMs).toISOString() }
+    : { status: "LIVE", stale: false, expiresAt: new Date(heartbeat + leaseMs).toISOString() };
+}
+
+/**
+ * PID values can be reused. Pairing the PID with the process start epoch gives
+ * a portable, serializable ownership token without a daemon or platform-only
+ * process inspector. Consumers must still treat remote owners as unknown.
+ */
+export function currentProcessStartToken(now = Date.now(), uptimeSeconds = process.uptime()) {
+  return `${process.pid}:${Math.max(0, Math.floor(now - (uptimeSeconds * 1000)))}`;
+}
+
 export const CLAIMS_LOCK_REL_PATH = ".forgeloop/.claims.lock";
 
 export async function readProjectClaimsLockInfo(target) {
@@ -46,12 +66,18 @@ export async function acquireProjectClaimsLock(target, operation = "claim-reserv
 
   await mkdir(path.dirname(fullPath), { recursive: true });
 
+  const acquiredAt = new Date().toISOString();
   const lockData = {
     lockId: randomUUID(),
     scope: "claims-reservation",
     operation,
     pid: process.pid,
-    acquiredAt: new Date().toISOString(),
+    hostname: os.hostname(),
+    processStartToken: currentProcessStartToken(),
+    ownerInstanceId: randomUUID(),
+    acquiredAt,
+    heartbeatAt: acquiredAt,
+    leaseMs: 300000,
   };
 
   let fileHandle;
@@ -123,12 +149,18 @@ export async function acquireTaskLock(target, taskId, operation = "mutation") {
 
   await mkdir(path.dirname(fullPath), { recursive: true });
 
+  const acquiredAt = new Date().toISOString();
   const lockData = {
     lockId: randomUUID(),
     taskId,
     operation,
     pid: process.pid,
-    acquiredAt: new Date().toISOString(),
+    hostname: os.hostname(),
+    processStartToken: currentProcessStartToken(),
+    ownerInstanceId: randomUUID(),
+    acquiredAt,
+    heartbeatAt: acquiredAt,
+    leaseMs: 300000,
   };
 
   let fileHandle;
@@ -179,7 +211,7 @@ export async function acquireTaskLock(target, taskId, operation = "mutation") {
   }
 }
 
-export async function forceUnlockTask(target, taskId) {
+export async function forceUnlockTask(target, taskId, { staleOnly = false } = {}) {
   const relativePath = taskLockPath(taskId);
   await assertSafePath(target, relativePath);
   const fullPath = ensureWithin(target, relativePath);
@@ -189,8 +221,12 @@ export async function forceUnlockTask(target, taskId) {
   }
 
   const existing = await readLockInfo(target, taskId);
+  const classification = classifyLockStaleness(existing);
+  if (staleOnly && !classification.stale) {
+    return { unlocked: false, previousLock: existing, classification };
+  }
   await unlink(fullPath);
-  return { unlocked: true, previousLock: existing };
+  return { unlocked: true, previousLock: existing, classification };
 }
 
 export async function withTaskLock(target, taskId, operationOrCallback, callback) {

package/src/core/task-migration.js

@@ -1,6 +1,6 @@
 import { cp, mkdir, rename, rm } from "node:fs/promises";
 import path from "node:path";
-import { ensureWithin, fileExists } from "./filesystem.js";
+import { ensureWithin, fileExists, writeFileAtomic } from "./filesystem.js";
 import { getPackageRoot } from "./templates.js";
 import {
   LEGACY_TASK_ARTIFACT_PATHS,
@@ -308,6 +308,23 @@ export async function migrateLegacyLayout(
     assertMigrationSnapshotsEqual(sourceSnapshot, finalSnapshot, "published namespace");
     await readTaskDescriptor(target, canonicalTaskId, packageRoot);
 
+    const migrationReceipt = {
+      schemaVersion: 1,
+      protocolVersion: 1,
+      kind: "LEGACY_TASK_MIGRATION",
+      taskId: canonicalTaskId,
+      taskKey,
+      migratedAt: new Date().toISOString(),
+      source: sourceSnapshot,
+      destination: finalSnapshot,
+      cleanupStatus: "PENDING",
+    };
+    await writeFileAtomic(
+      ensureWithin(target, `${finalDirRel}/migration-receipt.json`),
+      `${JSON.stringify(migrationReceipt, null, 2)}\n`,
+    );
+    migratedArtifacts.push("migration-receipt.json");
+
     // Test hook for cleanup failure testing
     if (typeof beforeLegacyCleanupForTest === "function") {
       await beforeLegacyCleanupForTest({ finalDirAbs, finalDirRel, target });
@@ -323,6 +340,12 @@ export async function migrateLegacyLayout(
           await removeLegacyArtifact(target, item.path);
         }
       }
+      migrationReceipt.cleanupStatus = "COMPLETED";
+      migrationReceipt.cleanedAt = new Date().toISOString();
+      await writeFileAtomic(
+        ensureWithin(target, `${finalDirRel}/migration-receipt.json`),
+        `${JSON.stringify(migrationReceipt, null, 2)}\n`,
+      );
     } catch (cleanupErr) {
       const error = new Error(
         `Migration published successfully to ${finalDirRel}, but legacy cleanup failed: ${cleanupErr.message}. Manual cleanup required.`,

package/src/core/task-paths.js

@@ -1,6 +1,7 @@
 import { assertTaskId, taskStorageKey } from "./task-identity.js";
 
 export const TASK_STATE_ROOT = ".forgeloop/task-state";
+export const TASK_LOCK_ROOT = ".forgeloop/locks";
 export const SESSIONS_ROOT = ".forgeloop/sessions";
 
 export const TASK_ARTIFACT_FILES = Object.freeze({
@@ -74,7 +75,8 @@ export function taskExecutionPath(taskId, executionId) {
 }
 
 export function taskLockPath(taskId) {
-  return taskArtifactPath(taskId, "lock");
+  assertTaskId(taskId);
+  return `${TASK_LOCK_ROOT}/${taskStorageKey(taskId)}.lock`;
 }
 
 export function sessionArtifactPath(sessionId) {

package/src/core/transaction.js

@@ -0,0 +1,259 @@
+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);
+        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);
+        if (manifest.writes.some((entry) => writePath(entry) === relativePath && entry.kind === "APPEND")) {
+          throw new Error(`cannot replace append-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);
+      },
+    };
+    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);
+        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);
+    }
+  }
+}