@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/commands/storage-migration-status.js

@@ -0,0 +1,44 @@
+import { lstat } from "node:fs/promises";
+import { assertSafePath } from "../core/filesystem.js";
+import { readMaintenanceOwner } from "../storage/maintenance-owner.js";
+
+async function present(target, relativePath) {
+  try { await lstat(await assertSafePath(target, relativePath)); return true; }
+  catch (error) { if (error.code === "ENOENT") return false; throw error; }
+}
+
+async function inspectOwner(target) {
+  const marker = await assertSafePath(target, ".forgeloop/.storage-maintenance");
+  if (!(await lstat(marker)).isDirectory()) return { status: "MALFORMED", owner: null };
+  try {
+    const { value } = await readMaintenanceOwner(target);
+    return {
+      status: "RETAINED",
+      owner: { ownerId: value.ownerId, pid: value.pid, acquiredAt: value.acquiredAt, ...(value.hostname ? { hostname: value.hostname } : {}) },
+      ownerLiveness: "NOT_VERIFIED",
+      handoffPresent: await present(target, ".forgeloop/.storage-maintenance/handoff")
+        || await present(target, `.forgeloop/storage-maintenance-history/handoffs/${value.ownerId}.json`),
+    };
+  } catch (error) {
+    if (error.code === "ENOENT") return { status: "INCOMPLETE", owner: null };
+    if (error.code === "E_STORAGE_MAINTENANCE_OWNER_INVALID") return { status: "MALFORMED", owner: null };
+    throw error;
+  }
+}
+
+/** Inspect bootstrap layout even when ordinary database dispatch is excluded. */
+export async function runStorageMigrationStatus({ target }) {
+  const databasePresent = await present(target, ".forgeloop/state.sqlite");
+  const legacyOperationalPaths = [];
+  for (const relativePath of [".forgeloop/task-state", ".forgeloop/work-state.json", ".forgeloop/events.ndjson", ".forgeloop/.txn"]) {
+    if (await present(target, relativePath)) legacyOperationalPaths.push(relativePath);
+  }
+  const maintenance = await present(target, ".forgeloop/.storage-maintenance")
+    ? await inspectOwner(target) : { status: "NONE", owner: null };
+  return {
+    schemaVersion: 1,
+    layout: databasePresent ? legacyOperationalPaths.length ? "MIXED" : "SQLITE_PRESENT" : "FILESYSTEM",
+    databasePresent, legacyOperationalPaths, maintenance,
+    databaseValidation: "NOT_RUN", publicationValidation: "NOT_VERIFIED",
+  };
+}

package/src/commands/storage-restore-resume.js

@@ -0,0 +1,7 @@
+import { resumeProjectStorageRestore } from "../storage/project-restore.js";
+import { resumeActiveProjectReplacement } from "../storage/project-replacement.js";
+
+export async function runStorageRestoreResume({ target, operationId, expectedOwnerId, writersQuiesced = false, replaceActive = false, packageRoot } = {}) {
+  const resume = replaceActive === true ? resumeActiveProjectReplacement : resumeProjectStorageRestore;
+  return resume(target, { operationId, expectedOwnerId, writersQuiesced, packageRoot });
+}

package/src/commands/storage-restore.js

@@ -0,0 +1,8 @@
+import path from "node:path";
+import { restoreProjectStorageToFreshProject } from "../storage/project-restore.js";
+import { replaceActiveProjectStorage } from "../storage/project-replacement.js";
+
+export async function runStorageRestore({ target, source, writersQuiesced = false, replaceActive = false, packageRoot } = {}) {
+  const restore = replaceActive === true ? replaceActiveProjectStorage : restoreProjectStorageToFreshProject;
+  return restore(path.resolve(target, source), target, { writersQuiesced, packageRoot });
+}

package/src/commands/task-abandon.js

@@ -0,0 +1,224 @@
+import { randomUUID } from "node:crypto";
+
+import { resolveTaskContext } from "../core/task-context.js";
+import { inspectTaskConflictState } from "../core/task-conflict-inspection.js";
+import { appendProtocolEvent } from "../core/events.js";
+import { withTaskTransaction } from "../core/transaction.js";
+import { currentRepositoryFingerprint } from "../core/repository.js";
+import { withProjectClaimsLock } from "../core/task-lock.js";
+import { readTaskDescriptor } from "../core/task-descriptor.js";
+import { createTaskRecovery, writeTaskRecovery } from "../core/task-recovery.js";
+import { resolveTaskClaimState } from "../core/task-claim-state.js";
+import {
+  E_TASK_ABANDON_AUTHORIZATION_REQUIRED,
+  E_TASK_ABANDON_INCONSISTENT,
+  E_TASK_ABANDON_INVALID_STATE,
+  E_TASK_ABANDON_UNSAFE,
+  E_TASK_ALREADY_ABANDONED,
+} from "../core/error-codes.js";
+
+const ABANDONMENT_REASON_CODES = Object.freeze(["CALLER_ABANDONED"]);
+
+function abandonError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function sameList(left, right) {
+  return Array.isArray(left)
+    && Array.isArray(right)
+    && left.length === right.length
+    && left.every((value, index) => value === right[index]);
+}
+
+function snapshot(inspection) {
+  return {
+    phase: inspection.evidence.phase,
+    revision: inspection.evidence.workStateRevision,
+    ledgerLastSeq: inspection.evidence.ledgerLastSeq,
+    claimState: inspection.evidence.claimState,
+    effectiveWriteClaims: [...inspection.evidence.effectiveWriteClaims],
+  };
+}
+
+function assertSnapshotUnchanged(before, after, taskId) {
+  const unchanged = before.phase === after.phase
+    && before.revision === after.revision
+    && before.ledgerLastSeq === after.ledgerLastSeq
+    && before.claimState === after.claimState
+    && sameList(before.effectiveWriteClaims, after.effectiveWriteClaims);
+  if (!unchanged) {
+    throw abandonError(
+      E_TASK_ABANDON_UNSAFE,
+      `Task ${taskId} changed during abandonment precondition validation`,
+      { before, after },
+    );
+  }
+}
+
+async function assertAbandonableOwnership(target, taskId, packageRoot) {
+  const projection = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (projection.phase === "COMPLETE" || projection.claimState === "RELEASED_BY_COMPLETION") {
+    throw abandonError(E_TASK_ABANDON_INVALID_STATE, `Task ${taskId} is COMPLETE and cannot be abandoned`);
+  }
+  if (!projection.valid || !projection.ownershipValid) {
+    throw abandonError(
+      E_TASK_ABANDON_INCONSISTENT,
+      `Task ${taskId} claim ownership is inconsistent; abandonment is blocked`,
+      { reasonCodes: projection.reasonCodes, ownershipErrors: projection.ownershipErrors },
+    );
+  }
+  if (projection.claimState === "RELEASED_BY_RECOVERY") {
+    throw abandonError(
+      E_TASK_ALREADY_ABANDONED,
+      `Task ${taskId} is already abandoned/recovered`,
+      { recovery: projection.recovery },
+    );
+  }
+  if (projection.claimState !== "ACTIVE" || projection.mutationAllowed !== true) {
+    throw abandonError(E_TASK_ABANDON_INVALID_STATE, `Task ${taskId} is not an active mutable task`);
+  }
+  return projection;
+}
+
+function assertInspectionAbandonable(taskId, inspection) {
+  if (!inspection.evidence.healthy || !inspection.evidence.ledgerValid || !inspection.evidence.ownershipValid) {
+    throw abandonError(
+      E_TASK_ABANDON_INCONSISTENT,
+      `Task ${taskId} cannot be abandoned because canonical ownership or ledger validation failed`,
+      { reasonCodes: inspection.reasonCodes, ledgerErrors: inspection.evidence.ledgerErrors },
+    );
+  }
+  if (!inspection.evidence.phase || inspection.evidence.phase === "COMPLETE") {
+    throw abandonError(E_TASK_ABANDON_INVALID_STATE, `Task ${taskId} is not eligible for abandonment`);
+  }
+  if (inspection.evidence.claimState !== "ACTIVE" || inspection.evidence.mutationAllowed !== true) {
+    throw abandonError(E_TASK_ABANDON_INVALID_STATE, `Task ${taskId} is not an active mutable task`);
+  }
+}
+
+export async function runTaskAbandon({
+  target,
+  packageRoot,
+  taskId,
+  acknowledgeAbandonment = false,
+} = {}) {
+  if (typeof taskId !== "string" || taskId.trim() === "") {
+    throw abandonError(E_TASK_ABANDON_INVALID_STATE, "task-abandon requires an explicit --task ID");
+  }
+  if (!acknowledgeAbandonment) {
+    throw abandonError(
+      E_TASK_ABANDON_AUTHORIZATION_REQUIRED,
+      "task-abandon requires explicit caller acknowledgement: re-run with --acknowledge-abandonment",
+    );
+  }
+
+  let context;
+  try {
+    context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
+  } catch (error) {
+    throw abandonError(
+      E_TASK_ABANDON_INCONSISTENT,
+      `Task ${taskId} cannot be abandoned because its canonical identity is unreadable`,
+      { causeCode: error.code, causeMessage: error.message },
+    );
+  }
+  const effectiveTaskId = context.taskId;
+  await assertAbandonableOwnership(target, effectiveTaskId, packageRoot);
+
+  return withProjectClaimsLock(target, "task-abandon", async () => {
+    await assertAbandonableOwnership(target, effectiveTaskId, packageRoot);
+    const inspectionBeforeLock = await inspectTaskConflictState(target, {
+      taskId: effectiveTaskId,
+      packageRoot,
+    });
+    assertInspectionAbandonable(effectiveTaskId, inspectionBeforeLock);
+    const before = snapshot(inspectionBeforeLock);
+
+    return withTaskTransaction({
+      target,
+      taskId: effectiveTaskId,
+      operation: "task-abandon",
+      packageRoot,
+      recordCommitEvent: true,
+    }, async (transaction) => {
+      const descriptor = await readTaskDescriptor(target, context.taskKey, packageRoot);
+      if (descriptor.value.taskId !== effectiveTaskId || descriptor.value.taskKey !== context.taskKey) {
+        throw abandonError(E_TASK_ABANDON_UNSAFE, `Task ${effectiveTaskId} identity changed during abandonment`);
+      }
+
+      await assertAbandonableOwnership(target, effectiveTaskId, packageRoot);
+      const inspection = await inspectTaskConflictState(target, {
+        taskId: effectiveTaskId,
+        packageRoot,
+        ignoredLockId: transaction.lock?.lockId ?? null,
+      });
+      assertInspectionAbandonable(effectiveTaskId, inspection);
+      assertSnapshotUnchanged(before, snapshot(inspection), effectiveTaskId);
+
+      const repository = await currentRepositoryFingerprint(target);
+      const recoveryId = `recovery-${randomUUID()}`;
+      const abandonedAt = new Date().toISOString();
+      const releasedClaims = [...inspection.evidence.effectiveWriteClaims];
+      const details = {
+        recoveryId,
+        classification: "ABANDONED",
+        reasonCodes: [...ABANDONMENT_REASON_CODES],
+        previousPhase: inspection.evidence.phase,
+        previousRevision: inspection.evidence.workStateRevision,
+        previousHead: inspection.evidence.repositoryHead,
+        previousBranch: inspection.evidence.repositoryBranch,
+        currentHead: repository.head,
+        currentBranch: repository.branch,
+        releasedClaims,
+        authorityKind: "CALLER_ACKNOWLEDGED",
+      };
+
+      const abandonmentEvent = await appendProtocolEvent(target, {
+        taskId: effectiveTaskId,
+        event: "TASK_ABANDONED",
+        at: abandonedAt,
+        details,
+      }, packageRoot, { taskId: effectiveTaskId });
+
+      await writeTaskRecovery(target, createTaskRecovery({
+        taskId: effectiveTaskId,
+        recoveredAt: abandonedAt,
+        recoveryId,
+        recoveryEventSeq: abandonmentEvent.seq,
+        classificationAtRecovery: "ABANDONED",
+        reasonCodes: ABANDONMENT_REASON_CODES,
+        releasedClaims,
+        previousPhase: inspection.evidence.phase,
+        previousRevision: inspection.evidence.workStateRevision,
+        repositoryFingerprint: repository,
+        authority: { kind: "CALLER_ACKNOWLEDGED" },
+      }), packageRoot);
+
+      return {
+        taskId: effectiveTaskId,
+        taskKey: context.taskKey,
+        abandoned: true,
+        recovered: true,
+        recoveryId,
+        classification: "ABANDONED",
+        reasonCodes: [...ABANDONMENT_REASON_CODES],
+        phase: inspection.evidence.phase,
+        claimsReleased: true,
+        releasedClaims,
+        effectiveWriteClaims: [],
+        claimState: "RELEASED_BY_RECOVERY",
+        mutationAllowed: false,
+        authority: { kind: "CALLER_ACKNOWLEDGED" },
+        message: `Task ${effectiveTaskId} explicitly abandoned by caller acknowledgement; write claims released without completion claim`,
+      };
+    });
+  });
+}
+
+export function formatTaskAbandonResult(result) {
+  const claims = result.releasedClaims.length === 0 ? "none" : result.releasedClaims.join(", ");
+  return `${result.message}\nclassification: ${result.classification}\nphase: ${result.phase} (unchanged)\nreleased claims: ${claims}\n`;
+}

package/src/commands/task-list.js

@@ -1,60 +1,25 @@
-import { discoverTasks } from "../core/task-discovery.js";
+import { discoverTaskListPage } from "../core/task-discovery.js";
 import { WORK_PHASES } from "../core/protocol.js";
 
 export async function runTaskList({ target, packageRoot, phase = null, active = false, limit = null, offset = 0 } = {}) {
-  const tasks = await discoverTasks(target, packageRoot);
   const normalizedPhase = typeof phase === "string" && phase.trim() !== "" ? phase.trim().toUpperCase() : null;
+  const start = Number.isInteger(offset) && offset >= 0 ? offset : 0;
+  const pageLimit = Number.isInteger(limit) && limit >= 0 ? limit : null;
+  const { tasks: projected, total } = await discoverTaskListPage(target, packageRoot, { phase: normalizedPhase, active, offset: start, limit: pageLimit });
   if (normalizedPhase && !WORK_PHASES.includes(normalizedPhase)) {
     const error = new Error(`Unknown task phase filter: ${phase}`);
     error.code = "E_TASK_PHASE_INVALID";
     throw error;
   }
-  const phaseFiltered = normalizedPhase ? tasks.filter((task) => task.phase === normalizedPhase) : tasks;
-  const filtered = active
-    ? phaseFiltered.filter((task) => task.claimState === "ACTIVE" && task.mutationAllowed === true)
-    : phaseFiltered;
-  const start = Number.isInteger(offset) && offset >= 0 ? offset : 0;
-  const end = Number.isInteger(limit) && limit >= 0 ? start + limit : undefined;
-  const projected = filtered.slice(start, end);
+  const end = pageLimit === null ? undefined : start + pageLimit;
   return {
-    tasks: projected.map((task) => {
-      if (task.healthy === false) {
-        return {
-          taskId: task.taskId ?? null,
-          taskKey: task.taskKey,
-          directory: task.directory,
-          healthy: false,
-          error: task.error,
-        };
-      }
-      return {
-        taskId: task.taskId,
-        taskKey: task.taskKey,
-        directory: task.directory,
-        healthy: true,
-        phase: task.phase,
-        writeClaims: task.writeClaims ?? [],
-        historicalWriteClaims: task.historicalWriteClaims ?? [],
-        effectiveWriteClaims: task.effectiveWriteClaims ?? [],
-        claimState: task.claimState,
-        recovery: task.recovery,
-        mutationAllowed: task.mutationAllowed,
-        ownershipValid: task.ownershipValid,
-        ownershipErrors: task.ownershipErrors ?? task.errors ?? [],
-        reasonCodes: task.reasonCodes ?? [],
-        locked: task.locked,
-        hasContinuity: task.hasContinuity,
-        hasReceipt: task.hasReceipt,
-        createdAt: task.createdAt,
-        updatedAt: task.updatedAt,
-      };
-    }),
+    tasks: projected,
     ...(normalizedPhase ? { phase: normalizedPhase } : {}),
     ...(active ? { active: true } : {}),
     offset: start,
     ...(Number.isInteger(limit) && limit >= 0 ? { limit } : {}),
-    total: filtered.length,
-    hasMore: end !== undefined ? end < filtered.length : false,
+    total,
+    hasMore: end !== undefined ? end < total : false,
   };
 }
 

package/src/commands/task-migrate-contract-bootstrap-repair.js

@@ -0,0 +1,288 @@
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { readContract } from "../core/contract.js";
+import { appendProtocolEvent, validateEventLedger, validateStateLedgerCoherence } from "../core/events.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { resolveTaskContext } from "../core/task-context.js";
+import { taskArtifactPath } from "../core/task-paths.js";
+import {
+  classifyLockStaleness,
+  readLockInfo,
+  releaseStaleTaskLockIfUnchanged,
+  withProjectClaimsLock,
+} from "../core/task-lock.js";
+import { withTaskTransaction } from "../core/transaction.js";
+import { resolveTaskClaimState } from "../core/task-claim-state.js";
+import { readWorkState } from "../core/work-state.js";
+import {
+  CONTRACT_BOOTSTRAP_REPAIR_AUTHORITY,
+  CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_DEFECT,
+  CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_EVENT,
+  CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_VERSION,
+  assertContractBootstrapRepairMigrationDetails,
+  isLegacyContractBootstrapRepairMigrationCandidate,
+  resolveEffectiveContractBootstrapRepairAnchor,
+} from "../core/contract-bootstrap-recovery.js";
+import {
+  E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_AUTHORIZATION_REQUIRED,
+  E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+  E_TASK_LOCKED,
+} from "../core/error-codes.js";
+
+function migrationError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function routePath(taskId) {
+  return taskArtifactPath(taskId, "route");
+}
+
+async function proveLegacyRepairState(target, packageRoot, taskId, marker) {
+  const contract = await readContract(target, packageRoot, { taskId });
+  if (contract.fingerprint !== marker.details.contractFingerprint) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Current contract does not match the legacy repair marker fingerprint",
+      { artifacts: [taskArtifactPath(taskId, "contract")] },
+    );
+  }
+
+  const state = await readWorkState(target, { packageRoot, taskId });
+  if (!state) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Current work-state is required to prove the legacy repair boundary",
+      { artifacts: [taskArtifactPath(taskId, "state")] },
+    );
+  }
+  if (state.taskId !== taskId
+    || state.phase !== marker.details.reconstructedPhase
+    || state.contractFingerprint !== marker.details.contractFingerprint
+    || canonicalFingerprint(state) !== marker.details.reconstructedStateFingerprint) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Current work-state does not exactly match the legacy repair marker reconstruction",
+      { artifacts: [taskArtifactPath(taskId, "state")] },
+    );
+  }
+  if (!Number.isInteger(state.revision) || state.revision < 0) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Current work-state revision is not a valid non-negative integer",
+      { artifacts: [taskArtifactPath(taskId, "state")] },
+    );
+  }
+
+  let route = null;
+  if (state.phase === "ROUTED") {
+    try {
+      route = await readPersistedRoute(target, packageRoot, { taskId });
+    } catch (error) {
+      throw migrationError(
+        E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+        `ROUTED legacy repair requires a readable persisted route: ${error.message}`,
+        { artifacts: [routePath(taskId)] },
+      );
+    }
+    if (marker.details.routeFingerprint === null
+      || state.routeFingerprint !== marker.details.routeFingerprint
+      || route.fingerprint !== marker.details.routeFingerprint
+      || route.value.contractFingerprint !== marker.details.contractFingerprint) {
+      throw migrationError(
+        E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+        "Persisted route does not exactly match the legacy repair marker reconstruction",
+        { artifacts: [routePath(taskId)] },
+      );
+    }
+  } else if (marker.details.routeFingerprint !== null || state.routeFingerprint !== undefined) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "CONTRACT_READY legacy repair must not claim a route",
+      { artifacts: [taskArtifactPath(taskId, "state")] },
+    );
+  }
+
+  return { contract, state, route };
+}
+
+function migrationResult(taskId, candidate, migrationEvent, alreadyMigrated) {
+  return {
+    taskId,
+    migrated: !alreadyMigrated,
+    alreadyMigrated,
+    legacyMarkerSeq: candidate.marker.seq,
+    legacyRepairCommitSeq: candidate.repairCommit.seq,
+    migrationEventSeq: migrationEvent?.seq ?? null,
+    repairId: candidate.marker.details.repairId,
+    reconstructedPhase: candidate.marker.details.reconstructedPhase,
+  };
+}
+
+async function inspectAlreadyMigrated(target, packageRoot, taskId, ledger) {
+  const anchor = resolveEffectiveContractBootstrapRepairAnchor(ledger.events);
+  if (!ledger.valid || !anchor || anchor.kind !== "MIGRATED_LEGACY") {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Existing contract bootstrap migration is invalid or the ledger is not strict",
+    );
+  }
+  const ownership = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!ownership.ownershipValid) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Current task state no longer satisfies the migrated task ownership invariants",
+      { errors: ownership.errors },
+    );
+  }
+  return migrationResult(taskId, { marker: anchor.sourceMarker, repairCommit: ledger.events[anchor.sourceMarker.seq] }, anchor.migrationEvent, true);
+}
+
+export async function runTaskMigrateContractBootstrapRepair({ target, packageRoot, taskId, acknowledgeMigration } = {}) {
+  if (!acknowledgeMigration) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_AUTHORIZATION_REQUIRED,
+      "task-migrate-contract-bootstrap-repair requires fresh explicit --acknowledge-migration",
+    );
+  }
+
+  const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
+  const effectiveTaskId = context.taskId;
+  const initial = await validateEventLedger(target, packageRoot, {
+    taskId: effectiveTaskId,
+    allowUnmigratedLegacyContractBootstrapRepairMarkers: true,
+  });
+  if (!initial.valid) {
+    const strict = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+    if (strict.valid) return inspectAlreadyMigrated(target, packageRoot, effectiveTaskId, strict);
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Ledger is not structurally trustworthy for legacy contract bootstrap migration",
+      { errors: initial.errors },
+    );
+  }
+  const initialCandidate = isLegacyContractBootstrapRepairMigrationCandidate(initial.events, effectiveTaskId);
+  if (!initialCandidate) {
+    const strict = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+    if (strict.valid) return inspectAlreadyMigrated(target, packageRoot, effectiveTaskId, strict);
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Ledger does not match the exact legacy contract bootstrap repair migration boundary",
+      { errors: initial.errors },
+    );
+  }
+
+  return withProjectClaimsLock(target, "task-migrate-contract-bootstrap-repair", async () => {
+    const lock = await readLockInfo(target, effectiveTaskId);
+    const status = classifyLockStaleness(lock);
+    if (status.status === "LIVE") throw migrationError(E_TASK_LOCKED, `Task ${effectiveTaskId} has a live mutation lock`);
+    if (status.status === "UNKNOWN" || status.status === "CORRUPT") {
+      throw migrationError(
+        E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+        `Task ${effectiveTaskId} lock state is ${status.status}; refusing unsafe migration`,
+      );
+    }
+    if (status.status === "STALE") {
+      const released = await releaseStaleTaskLockIfUnchanged(target, effectiveTaskId, lock);
+      if (!released.released && released.reason !== "LOCK_MISSING") {
+        throw migrationError(
+          E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+          `Task ${effectiveTaskId} stale lock could not be safely released: ${released.reason}`,
+        );
+      }
+    }
+
+    const result = await withTaskTransaction({
+      target,
+      taskId: effectiveTaskId,
+      operation: "task-migrate-contract-bootstrap-repair",
+      packageRoot,
+      recordCommitEvent: true,
+    }, async () => {
+      const locked = await validateEventLedger(target, packageRoot, {
+        taskId: effectiveTaskId,
+        allowUnmigratedLegacyContractBootstrapRepairMarkers: true,
+      });
+      if (!locked.valid) {
+        const strict = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+        if (strict.valid) return inspectAlreadyMigrated(target, packageRoot, effectiveTaskId, strict);
+        throw migrationError(
+          E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+          "Pre-commit ledger revalidation failed inside the migration transaction",
+          { errors: locked.errors },
+        );
+      }
+      const candidate = isLegacyContractBootstrapRepairMigrationCandidate(locked.events, effectiveTaskId);
+      if (!candidate
+        || candidate.marker.seq !== initialCandidate.marker.seq
+        || candidate.marker.hash !== initialCandidate.marker.hash
+        || candidate.repairCommit.hash !== initialCandidate.repairCommit.hash) {
+        const strict = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+        if (strict.valid) return inspectAlreadyMigrated(target, packageRoot, effectiveTaskId, strict);
+        throw migrationError(
+          E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+          "Ledger changed between inspection and migration lock; aborting",
+        );
+      }
+
+      const proof = await proveLegacyRepairState(target, packageRoot, effectiveTaskId, candidate.marker);
+      const coherenceErrors = validateStateLedgerCoherence(proof.state, locked.events);
+      if (coherenceErrors.length > 0) {
+        throw migrationError(
+          E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+          "Work-state and ledger are not coherent at the legacy repair boundary",
+          { errors: coherenceErrors },
+        );
+      }
+      const migratedAt = new Date().toISOString();
+      const details = {
+        migrationVersion: CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_VERSION,
+        defect: CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_DEFECT,
+        legacyMarkerSeq: candidate.marker.seq,
+        legacyMarkerHash: candidate.marker.hash,
+        legacyRepairId: candidate.marker.details.repairId,
+        legacyRepairCommitSeq: candidate.repairCommit.seq,
+        legacyRepairCommitHash: candidate.repairCommit.hash,
+        legacyRepairTransactionId: candidate.repairCommit.details.transactionId,
+        taskId: effectiveTaskId,
+        contractFingerprint: candidate.marker.details.contractFingerprint,
+        reconstructedPhase: candidate.marker.details.reconstructedPhase,
+        routeFingerprint: candidate.marker.details.routeFingerprint,
+        reconstructedStateFingerprint: candidate.marker.details.reconstructedStateFingerprint,
+        reconstructedStateRevision: proof.state.revision,
+        migratedAt,
+        authorityKind: CONTRACT_BOOTSTRAP_REPAIR_AUTHORITY,
+      };
+      assertContractBootstrapRepairMigrationDetails(details);
+      const migrationEvent = await appendProtocolEvent(target, {
+        taskId: effectiveTaskId,
+        event: CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_EVENT,
+        at: migratedAt,
+        details,
+      }, packageRoot, { taskId: effectiveTaskId });
+      return migrationResult(effectiveTaskId, candidate, migrationEvent, false);
+    });
+
+    const finalLedger = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+    if (!finalLedger.valid) {
+      throw migrationError(
+        E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+        "Post-migration ledger validation failed; the legacy repair remains unverified",
+        { errors: finalLedger.errors },
+      );
+    }
+    return result;
+  });
+}
+
+export function formatTaskMigrateContractBootstrapRepairResult(result) {
+  return [
+    `taskId: ${result.taskId}`,
+    `migration: ${result.alreadyMigrated ? "already migrated" : "migrated"}`,
+    `legacy marker seq: ${result.legacyMarkerSeq}`,
+    `migration event seq: ${result.migrationEventSeq}`,
+    `repairId: ${result.repairId}`,
+    "",
+  ].join("\n");
+}

package/src/commands/task-migrate.js

@@ -1,7 +1,7 @@
-import { migrateLegacyLayout } from "../core/task-migration.js";
+import { migrateLegacyTaskStorage } from "../core/task-storage-migration.js";
 
-export async function runTaskMigrate({ target, packageRoot, dryRun = false } = {}) {
-  const result = await migrateLegacyLayout(target, { packageRoot, dryRun });
+export async function runTaskMigrate({ target, packageRoot, dryRun = false, destination, writersQuiesced = false } = {}) {
+  const result = await migrateLegacyTaskStorage(target, { packageRoot, dryRun, destination, writersQuiesced });
   return result;
 }