@cassiomc1/forgeloop 1.3.0 → 1.5.0

package/src/core/completion-ownership.js

@@ -0,0 +1,88 @@
+import { LIFECYCLE_MILESTONES, validateStateLedgerCoherence } from "./events.js";
+
+export const CANONICAL_COMPLETION_EVENT = "COMPLETION_VALIDATED";
+
+/**
+ * Canonical completion ownership proof: the minimal, validator-backed evidence
+ * that the lifecycle itself officially reached COMPLETE. This is intentionally
+ * NOT a re-run of full publication/receipt/evidence semantics — it only proves
+ * that claim ownership may be released because canonical completion exists.
+ *
+ * Returns `{ valid: true, completionEvent }` or `{ valid: false, errors }`.
+ */
+export function validateCompletionOwnershipProof({ taskId, state, ledger }) {
+  const errors = [];
+  if (!taskId || typeof taskId !== "string") {
+    return { valid: false, errors: [{ code: "E_COMPLETION_OWNERSHIP_UNPROVEN", message: "Completion ownership proof requires a taskId" }] };
+  }
+  if (!state || state.phase !== "COMPLETE") {
+    errors.push({ code: "E_COMPLETION_OWNERSHIP_UNPROVEN", message: "Work-state phase is not COMPLETE" });
+  }
+  if (!ledger || ledger.valid !== true) {
+    errors.push({
+      code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+      message: `Task event ledger is invalid; completion cannot be proven${ledger?.errors?.length
+        ? `: ${ledger.errors.map((error) => error.message).join("; ")}`
+        : ""}`,
+    });
+  }
+
+  let completionEvent = null;
+  if (ledger && Array.isArray(ledger.events)) {
+    if (ledger.events.some((event) => event.taskId !== taskId)) {
+      errors.push({
+        code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+        message: "Ledger contains an event belonging to a different task",
+      });
+    }
+    const candidates = ledger.events
+      .filter((event) => event.event === CANONICAL_COMPLETION_EVENT && event.taskId === taskId);
+    if (candidates.length === 0) {
+      errors.push({
+        code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+        message: `No canonical ${CANONICAL_COMPLETION_EVENT} event exists for this task`,
+      });
+    } else if (candidates.length > 1) {
+      errors.push({
+        code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+        message: `Multiple ${CANONICAL_COMPLETION_EVENT} events exist; completion is ambiguous`,
+      });
+    } else {
+      completionEvent = candidates[0];
+    }
+  }
+
+  if (state && ledger && Array.isArray(ledger.events)) {
+    const coherenceErrors = validateStateLedgerCoherence(state, ledger.events);
+    if (coherenceErrors.length > 0) {
+      for (const error of coherenceErrors) {
+        errors.push({
+          code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+          message: `State/ledger coherence invalid: ${error.message}`,
+        });
+      }
+    }
+  }
+
+  // No contradictory lifecycle activity may follow the canonical completion:
+  // any milestone at or after VERIFICATION_RECORDED occurring after the
+  // completion event means the lifecycle moved past terminal state.
+  if (completionEvent && ledger && Array.isArray(ledger.events)) {
+    const completionIndex = ledger.events.indexOf(completionEvent);
+    const contradiction = ledger.events.slice(completionIndex + 1).find((event) => {
+      const index = LIFECYCLE_MILESTONES.indexOf(event.event);
+      return index >= LIFECYCLE_MILESTONES.indexOf("VERIFICATION_RECORDED");
+    });
+    if (contradiction) {
+      errors.push({
+        code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+        message: `Lifecycle event ${contradiction.event} follows canonical completion; terminal state contradicted`,
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, completionEvent: null, errors };
+  }
+  return { valid: true, completionEvent };
+}

package/src/core/error-codes.js

@@ -10,6 +10,7 @@ import {
 export const E_TASK_REQUIRED = "E_TASK_REQUIRED";
 export const E_TASK_NOT_FOUND = "E_TASK_NOT_FOUND";
 export const E_TASK_ALREADY_EXISTS = "E_TASK_ALREADY_EXISTS";
+export const E_TASK_COMPLETE = "E_TASK_COMPLETE";
 export const E_TASK_AMBIGUOUS = "E_TASK_AMBIGUOUS";
 export const E_TASK_SELECTOR_CONFLICT = "E_TASK_SELECTOR_CONFLICT";
 export const E_TASK_DESCRIPTOR_INVALID = "E_TASK_DESCRIPTOR_INVALID";
@@ -18,6 +19,7 @@ export const E_TASK_CONTEXT_MISMATCH = "E_TASK_CONTEXT_MISMATCH";
 
 export const E_TASK_LOCKED = "E_TASK_LOCKED";
 export const E_TASK_LOCK_INVALID = "E_TASK_LOCK_INVALID";
+export const E_PROJECT_CLAIMS_LOCK_INCONSISTENT = "E_PROJECT_CLAIMS_LOCK_INCONSISTENT";
 
 export const E_TASK_SCOPE_REQUIRED = "E_TASK_SCOPE_REQUIRED";
 export const E_TASK_SCOPE_CONFLICT = "E_TASK_SCOPE_CONFLICT";
@@ -28,6 +30,17 @@ export const E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE = "E_TASK_CHANGE_ATTRIBUTION_
 
 export const E_TASK_LAYOUT_LEGACY = "E_TASK_LAYOUT_LEGACY";
 export const E_TASK_MIGRATION_INVALID = "E_TASK_MIGRATION_INVALID";
+export const E_TASK_RECOVERY_UNSAFE = "E_TASK_RECOVERY_UNSAFE";
+export const E_TASK_RECOVERY_INCONSISTENT = "E_TASK_RECOVERY_INCONSISTENT";
+export const E_LEGACY_RECOVERY_MIGRATION_INVALID = "E_LEGACY_RECOVERY_MIGRATION_INVALID";
+export const E_COMPLETION_OWNERSHIP_UNPROVEN = "E_COMPLETION_OWNERSHIP_UNPROVEN";
+export const E_TASK_CLAIM_OWNERSHIP_INCONSISTENT = "E_TASK_CLAIM_OWNERSHIP_INCONSISTENT";
+export const E_TASK_RECOVERY_AUTHORIZATION_REQUIRED = "E_TASK_RECOVERY_AUTHORIZATION_REQUIRED";
+export const E_TASK_RECOVERY_AUTHORITY_INVALID = "E_TASK_RECOVERY_AUTHORITY_INVALID";
+export const E_TASK_RECOVERED = "E_TASK_RECOVERED";
+export const E_TASK_NOT_RECOVERED = "E_TASK_NOT_RECOVERED";
+export const E_TASK_RECOVERY_OFFICIAL_PATH_AVAILABLE = "E_TASK_RECOVERY_OFFICIAL_PATH_AVAILABLE";
+export const E_TASK_ALREADY_RECOVERED = "E_TASK_ALREADY_RECOVERED";
 export const E_TASK_MIGRATION_IDENTITY_MISMATCH = "E_TASK_MIGRATION_IDENTITY_MISMATCH";
 export const E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED = "E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED";
 
@@ -151,6 +164,13 @@ export const PUBLIC_ERROR_CODES = Object.freeze({
     meaning: "Multiple tasks exist in the project but no task selector was provided.",
     safeResolution: "Select a task explicitly using --task <id> or FORGELOOP_TASK=<id>.",
   }),
+  E_TASK_COMPLETE: Object.freeze({
+    code: "E_TASK_COMPLETE",
+    category: "task-resolution",
+    classification: "PUBLIC_STABLE",
+    meaning: "A validator-backed COMPLETE task is terminal and cannot be mutated.",
+    safeResolution: "Create or select a non-terminal task for further work; do not modify terminal task state.",
+  }),
   E_TASK_LOCKED: Object.freeze({
     code: "E_TASK_LOCKED",
     category: "concurrency",
@@ -158,12 +178,96 @@ export const PUBLIC_ERROR_CODES = Object.freeze({
     meaning: "Task mutation is currently locked by another concurrent process or run-check.",
     safeResolution: "Wait for the active mutation to complete or inspect the lock with forgeloop task-show.",
   }),
+  E_PROJECT_CLAIMS_LOCK_INCONSISTENT: Object.freeze({
+    code: "E_PROJECT_CLAIMS_LOCK_INCONSISTENT",
+    category: "concurrency",
+    classification: "PUBLIC_STABLE",
+    meaning: "The project-wide claim reservation lock has unknown, corrupt, or concurrently changed ownership metadata.",
+    safeResolution: "Inspect .forgeloop/.claims.lock and retry only after its lease and owner identity can be validated; never force-delete unknown ownership.",
+  }),
   E_TASK_SCOPE_CONFLICT: Object.freeze({
     code: "E_TASK_SCOPE_CONFLICT",
     category: "scope",
     classification: "PUBLIC_STABLE",
     meaning: "Task write claims overlap with another non-complete task in the same checkout.",
-    safeResolution: "Adjust write claims to non-overlapping paths or run tasks in separate worktrees.",
+    safeResolution: "Inspect the conflicting task classification reported in error.conflicts, then reconcile or recover it through its reported official recovery commands before retrying task creation.",
+  }),
+  E_TASK_RECOVERY_UNSAFE: Object.freeze({
+    code: "E_TASK_RECOVERY_UNSAFE",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "Claim-release recovery was refused because the conflicting task is active, inconsistent, already complete, or holds a live lease.",
+    safeResolution: "Resolve the reported classification first; live leases must expire or be released by their owner before recovery.",
+  }),
+  E_TASK_RECOVERY_INCONSISTENT: Object.freeze({
+    code: "E_TASK_RECOVERY_INCONSISTENT",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "Claim-release recovery was refused because the task state, recovery artifact, lock, or event ledger is inconsistent.",
+    safeResolution: "Repair the underlying artifact through its dedicated recovery surface; do not force-complete an unreadable task.",
+  }),
+  E_LEGACY_RECOVERY_MIGRATION_INVALID: Object.freeze({
+    code: "E_LEGACY_RECOVERY_MIGRATION_INVALID",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "The legacy recovery-event repair was refused because the ledger does not match the exact known legacy defect signature, has incompatible later activity, holds a live lock, or is otherwise ambiguous.",
+    safeResolution: "Inspect the structured plan/errors; ambiguous or tampered ledgers stay INCONSISTENT and are never migrated.",
+  }),
+  E_COMPLETION_OWNERSHIP_UNPROVEN: Object.freeze({
+    code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "Work-state claims COMPLETE but the canonical lifecycle/ledger completion proof is missing or invalid, so historical claims stay reserved.",
+    safeResolution: "Restore the canonical completion event and a valid ledger, or re-run the official completion pipeline; phase=COMPLETE alone never releases claims.",
+  }),
+  E_TASK_CLAIM_OWNERSHIP_INCONSISTENT: Object.freeze({
+    code: "E_TASK_CLAIM_OWNERSHIP_INCONSISTENT",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "ForgeLoop cannot prove whether a task still owns its historical write claims.",
+    safeResolution: "Repair and validate the task descriptor, recovery artifact, and complete event ledger before acquiring overlapping claims or mutating the task.",
+  }),
+  E_TASK_RECOVERY_AUTHORIZATION_REQUIRED: Object.freeze({
+    code: "E_TASK_RECOVERY_AUTHORIZATION_REQUIRED",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "task-recover requires explicit caller acknowledgement; this is not host-attested authority.",
+    safeResolution: "Re-run with --acknowledge-recovery only when evidence shows the task is STALE or ABANDONED; --operator-authorized remains a deprecated alias.",
+  }),
+  E_TASK_RECOVERY_AUTHORITY_INVALID: Object.freeze({
+    code: "E_TASK_RECOVERY_AUTHORITY_INVALID",
+    category: "authority",
+    classification: "PUBLIC_STABLE",
+    meaning: "Recovery authority metadata is invalid or claims host attestation without a host-owned grant reference.",
+    safeResolution: "Use caller acknowledgement, or provide a host-attested recovery grant through a trusted host integration.",
+  }),
+  E_TASK_RECOVERED: Object.freeze({
+    code: "E_TASK_RECOVERED",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "The task released its write claims through recovery and ordinary mutation is suspended.",
+    safeResolution: "Run forgeloop task-resume --task <id> to reacquire the released claims before mutating the task.",
+  }),
+  E_TASK_NOT_RECOVERED: Object.freeze({
+    code: "E_TASK_NOT_RECOVERED",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "task-resume was requested for a task without active recovered state.",
+    safeResolution: "Inspect the task with forgeloop task-show; task-resume is only valid while recovery.json is active.",
+  }),
+  E_TASK_RECOVERY_OFFICIAL_PATH_AVAILABLE: Object.freeze({
+    code: "E_TASK_RECOVERY_OFFICIAL_PATH_AVAILABLE",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "Claim-release recovery was refused because canonical lifecycle reconciliation is available.",
+    safeResolution: "Use forgeloop reconcile-closure and the normal verification/completion pipeline instead of task-recover.",
+  }),
+  E_TASK_ALREADY_RECOVERED: Object.freeze({
+    code: "E_TASK_ALREADY_RECOVERED",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "The task already has active durable recovered state.",
+    safeResolution: "Inspect the existing recovery metadata; use task-resume to reacquire claims or leave the task recovered.",
   }),
   E_TASK_SCOPE_DIRTY: Object.freeze({
     code: "E_TASK_SCOPE_DIRTY",
@@ -446,6 +550,7 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_TASK_REQUIRED,
   E_TASK_NOT_FOUND,
   E_TASK_ALREADY_EXISTS,
+  E_TASK_COMPLETE,
   E_TASK_AMBIGUOUS,
   E_TASK_SELECTOR_CONFLICT,
   E_TASK_DESCRIPTOR_INVALID,
@@ -453,6 +558,7 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_TASK_CONTEXT_MISMATCH,
   E_TASK_LOCKED,
   E_TASK_LOCK_INVALID,
+  E_PROJECT_CLAIMS_LOCK_INCONSISTENT,
   E_TASK_SCOPE_REQUIRED,
   E_TASK_SCOPE_CONFLICT,
   E_TASK_SCOPE_DIRTY,
@@ -469,6 +575,17 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE,
   E_TASK_LAYOUT_LEGACY,
   E_TASK_MIGRATION_INVALID,
+  E_TASK_RECOVERY_UNSAFE,
+  E_TASK_RECOVERY_INCONSISTENT,
+  E_LEGACY_RECOVERY_MIGRATION_INVALID,
+  E_COMPLETION_OWNERSHIP_UNPROVEN,
+  E_TASK_CLAIM_OWNERSHIP_INCONSISTENT,
+  E_TASK_RECOVERY_AUTHORIZATION_REQUIRED,
+  E_TASK_RECOVERY_AUTHORITY_INVALID,
+  E_TASK_RECOVERED,
+  E_TASK_NOT_RECOVERED,
+  E_TASK_RECOVERY_OFFICIAL_PATH_AVAILABLE,
+  E_TASK_ALREADY_RECOVERED,
   E_TASK_MIGRATION_IDENTITY_MISMATCH,
   E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED,
   E_CHECK_INERT,

package/src/core/events.js

@@ -15,6 +15,13 @@ import { getActiveTaskTransaction, withTaskTransaction } from "./transaction.js"
 
 import { assertDiagnosisDetails } from "./diagnosis-model.js";
 import { assertDecisionCriterionDetails } from "./settlement-model.js";
+import {
+  LEGACY_RECOVERY_MIGRATION_EVENT,
+  assertLegacyMigrationDetails,
+  isLegacyRecoveryDetailsShape,
+  isLegacyRecoveryEventShape,
+  legacyRecoveryMigrationId,
+} from "./task-recovery-migration.js";
 
 const EVENT_SCHEMA_VERSION = 1;
 export const LIFECYCLE_MILESTONES = Object.freeze([
@@ -97,11 +104,63 @@ export function validateKnownEventDetails(event) {
     case "CHECKPOINT_RECONCILED":
       assertReconcileClosureDetails(event.details);
       return;
+    case "TASK_RECOVERY_RECORDED":
+      assertRecoveryRecordedDetails(event.details);
+      return;
+    case "OPERATOR_RECOVERY_RECORDED":
+      // The exact known legacy defect signature is tolerated here so the
+      // ledger can be parsed and classified. It only becomes valid through an
+      // official migration event (enforced by validateEventLedger).
+      if (!event.details?.recoveryId && isLegacyRecoveryDetailsShape(event.details)) return;
+      assertRecoveryRecordedDetails(event.details);
+      return;
+    case "LEGACY_RECOVERY_MIGRATION_RECORDED":
+      assertLegacyMigrationDetails(event.details);
+      return;
+    case "TASK_RECOVERY_RESUMED":
+      assertRecoveryResumedDetails(event.details);
+      return;
     default:
       return;
   }
 }
 
+function assertStringList(value, label) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item)) {
+    throw protocolError("E_EVENT_INVALID", `${label} must be an array of non-empty strings`);
+  }
+}
+
+function assertRecoveryRecordedDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    throw protocolError("E_EVENT_INVALID", "recovery event requires structured details");
+  }
+  for (const key of ["recoveryId", "classification", "previousPhase", "authorityKind"]) {
+    if (typeof details[key] !== "string" || !details[key]) {
+      throw protocolError("E_EVENT_INVALID", `recovery event details.${key} must be a non-empty string`);
+    }
+  }
+  if (!Number.isInteger(details.previousRevision) || details.previousRevision < 0) {
+    throw protocolError("E_EVENT_INVALID", "recovery event details.previousRevision must be a non-negative integer");
+  }
+  if (!["STALE", "ABANDONED"].includes(details.classification)) {
+    throw protocolError("E_EVENT_INVALID", "recovery event details.classification must be STALE or ABANDONED");
+  }
+  if (!["CALLER_ACKNOWLEDGED", "HOST_ATTESTED"].includes(details.authorityKind)) {
+    throw protocolError("E_EVENT_INVALID", "recovery event details.authorityKind is invalid");
+  }
+  assertStringList(details.reasonCodes, "recovery event details.reasonCodes");
+  assertStringList(details.releasedClaims, "recovery event details.releasedClaims");
+}
+
+function assertRecoveryResumedDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)
+    || typeof details.recoveryId !== "string" || !details.recoveryId) {
+    throw protocolError("E_EVENT_INVALID", "TASK_RECOVERY_RESUMED requires details.recoveryId");
+  }
+  assertStringList(details.reacquiredClaims, "TASK_RECOVERY_RESUMED details.reacquiredClaims");
+}
+
 function assertReconcileClosureDetails(details) {
   if (!details || typeof details !== "object" || Array.isArray(details)) {
     throw protocolError("E_EVENT_INVALID", "CHECKPOINT_RECONCILED requires structured details");
@@ -121,7 +180,7 @@ function assertReconcileClosureDetails(details) {
   }
 }
 
-function eventHash(event) {
+export function eventHash(event) {
   const { hash, ...body } = event;
   return canonicalFingerprint(body);
 }
@@ -242,6 +301,73 @@ export async function appendProtocolEvent(target, input, packageRoot, options =
   return event;
 }
 
+/**
+ * Validates the append-only pairing between unmigrated legacy recovery events
+ * and their official migration events. Strict by default; the official repair
+ * command validates intermediate state with `allowUnmigratedLegacyRecoveryEvents`
+ * before appending the migration events.
+ */
+function validateLegacyRecoveryMigrations(events, errors, { allowUnmigratedLegacyRecoveryEvents = false } = {}) {
+  const migrationBySeq = new Map();
+  for (const event of events) {
+    if (event.event !== LEGACY_RECOVERY_MIGRATION_EVENT) continue;
+    try {
+      assertLegacyMigrationDetails(event.details);
+    } catch (err) {
+      errors.push({ code: err.code ?? "E_EVENT_INVALID", message: `event ${event.seq} (${event.event}): ${err.message}` });
+      continue;
+    }
+    if (migrationBySeq.has(event.details.legacyEventSeq)) {
+      errors.push({
+        code: "E_EVENT_INVALID",
+        message: `event ${event.seq} (${event.event}): duplicate migration for legacy recovery event seq ${event.details.legacyEventSeq}`,
+      });
+      continue;
+    }
+    migrationBySeq.set(event.details.legacyEventSeq, event);
+  }
+  for (const event of events) {
+    if (!isLegacyRecoveryEventShape(event)) continue;
+    const migration = migrationBySeq.get(event.seq);
+    if (!migration) {
+      if (!allowUnmigratedLegacyRecoveryEvents) {
+        errors.push({
+          code: "E_EVENT_INVALID",
+          message: `legacy recovery event ${event.seq} is not officially migrated (run forgeloop task-repair-legacy-recovery)`,
+        });
+      }
+      continue;
+    }
+    migrationBySeq.delete(event.seq);
+    const expectedRecoveryId = legacyRecoveryMigrationId({ taskId: event.taskId, seq: event.seq, hash: event.hash });
+    // Tail-binding: the migration event is appended at the ledger tail and may
+    // sit anywhere after its historical source. It binds by reference only.
+    if (migration.seq <= event.seq) {
+      errors.push({
+        code: "E_EVENT_INVALID",
+        message: `migration event ${migration.seq} must follow legacy recovery event ${event.seq}`,
+      });
+    }
+    if (migration.taskId !== event.taskId
+      || migration.details.legacyTaskId !== event.taskId
+      || migration.details.recoveryId !== expectedRecoveryId
+      || migration.details.legacyEventHash !== event.hash
+      || migration.details.legacyEventAt !== event.at
+      || migration.details.legacyEventType !== event.event) {
+      errors.push({
+        code: "E_LEDGER_HASH_INVALID",
+        message: `migration event ${migration.seq} does not bind legacy recovery event ${event.seq}`,
+      });
+    }
+  }
+  for (const [legacySeq, migration] of migrationBySeq) {
+    errors.push({
+      code: "E_EVENT_INVALID",
+      message: `migration event ${migration.seq} references unknown legacy recovery event seq ${legacySeq}`,
+    });
+  }
+}
+
 export async function validateEventLedger(target, packageRoot, options = {}) {
   const relPath = options?.eventsPath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "events") : ARTIFACT_PATHS.events);
   let events;
@@ -323,6 +449,9 @@ export async function validateEventLedger(target, packageRoot, options = {}) {
       errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "completion rejected before verification started" });
     }
   }
+  validateLegacyRecoveryMigrations(events, errors, {
+    allowUnmigratedLegacyRecoveryEvents: options?.allowUnmigratedLegacyRecoveryEvents === true,
+  });
   return { valid: errors.length === 0, events, errors };
 }
 

package/src/core/filesystem.js

@@ -10,6 +10,55 @@ import {
   unlink,
 } from "node:fs/promises";
 import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+const WINDOWS_TRANSIENT_RETRY_DELAYS_MS = Object.freeze([5, 10, 20, 40]);
+
+async function fsCallWithTransientWindowsRetry(fsImpl, filePath, {
+  platform = process.platform,
+  retryDelaysMs = WINDOWS_TRANSIENT_RETRY_DELAYS_MS,
+  delayImpl = delay,
+} = {}) {
+  let retryIndex = 0;
+  while (true) {
+    try {
+      return await fsImpl(filePath);
+    } catch (error) {
+      const retryable = platform === "win32"
+        && (error?.code === "EPERM" || error?.code === "EACCES")
+        && retryIndex < retryDelaysMs.length;
+      if (!retryable) throw error;
+      await delayImpl(retryDelaysMs[retryIndex]);
+      retryIndex += 1;
+    }
+  }
+}
+
+export async function realpathWithTransientWindowsRetry(filePath, {
+  platform = process.platform,
+  retryDelaysMs = WINDOWS_TRANSIENT_RETRY_DELAYS_MS,
+  realpathImpl = realpath,
+  delayImpl = delay,
+} = {}) {
+  return fsCallWithTransientWindowsRetry(realpathImpl, filePath, {
+    platform,
+    retryDelaysMs,
+    delayImpl,
+  });
+}
+
+export function lstatWithTransientWindowsRetry(filePath, {
+  platform = process.platform,
+  retryDelaysMs = WINDOWS_TRANSIENT_RETRY_DELAYS_MS,
+  lstatImpl = lstat,
+  delayImpl = delay,
+} = {}) {
+  return fsCallWithTransientWindowsRetry(lstatImpl, filePath, {
+    platform,
+    retryDelaysMs,
+    delayImpl,
+  });
+}
 
 export function ensureWithin(root, relativePath) {
   if (path.isAbsolute(relativePath)) {
@@ -27,7 +76,7 @@ export function ensureWithin(root, relativePath) {
 export async function assertSafePath(root, relativePath) {
   const destination = ensureWithin(root, relativePath);
   const absoluteRoot = path.resolve(root);
-  const rootInfo = await lstat(absoluteRoot);
+  const rootInfo = await lstatWithTransientWindowsRetry(absoluteRoot);
   if (rootInfo.isSymbolicLink() || !rootInfo.isDirectory()) {
     throw new Error(`Target directory must not be a symlink: ${absoluteRoot}`);
   }
@@ -37,7 +86,7 @@ export async function assertSafePath(root, relativePath) {
   for (const segment of segments) {
     current = path.join(current, segment);
     try {
-      const info = await lstat(current);
+      const info = await lstatWithTransientWindowsRetry(current);
       if (info.isSymbolicLink()) {
         throw new Error(`Path uses a symlink inside target directory: ${relativePath}`);
       }
@@ -50,12 +99,12 @@ export async function assertSafePath(root, relativePath) {
   let existing = destination;
   while (true) {
     try {
-      const info = await lstat(existing);
+      const info = await lstatWithTransientWindowsRetry(existing);
       if (info.isSymbolicLink()) {
         throw new Error(`Path uses a symlink inside target directory: ${relativePath}`);
       }
-      const resolvedRoot = await realpath(absoluteRoot);
-      const resolvedExisting = await realpath(existing);
+      const resolvedRoot = await realpathWithTransientWindowsRetry(absoluteRoot);
+      const resolvedExisting = await realpathWithTransientWindowsRetry(existing);
       const relativeResolved = path.relative(resolvedRoot, resolvedExisting);
       if (relativeResolved === ".." || relativeResolved.startsWith(`..${path.sep}`) || path.isAbsolute(relativeResolved)) {
         throw new Error(`Path escapes target directory: ${relativePath}`);
@@ -137,4 +186,4 @@ export async function writeFileAtomic(filePath, bytes, { dryRun = false } = {})
     }
     throw error;
   }
-}
+}

package/src/core/inspect.js

@@ -11,6 +11,7 @@ import { FORGELOOP_KIT_DIR } from "./target-layout.js";
 import { trustedAuthorityConfiguration } from "./trusted-authority.js";
 import { reconcileContinuity } from "./continuity-reconciliation.js";
 import { continuityFinding, continuityIsHealthy } from "./continuity-observability.js";
+import { findTaskById } from "./task-discovery.js";
 
 function profileMetadata(bytes) {
   const text = bytes.toString("utf8");
@@ -40,6 +41,7 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
   const statePath = ensureWithin(target, effectiveStateRel);
   const statePresent = await fileExists(statePath);
   const state = await readAndClassifyWorkState({ target, packageRoot, contractFile, taskId, stateFile: effectiveStateRel });
+  const taskInfo = taskId ? await findTaskById(target, taskId, packageRoot) : null;
   const continuity = await reconcileContinuity({ target, packageRoot, taskId });
   const schemaRoot = manifest?.layoutVersion >= 2
     ? ensureWithin(target, FORGELOOP_KIT_DIR)
@@ -78,6 +80,21 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
   const continuityIssue = continuityFinding(continuity);
   if (continuityIssue) findings.push(continuityIssue);
 
+  if (taskInfo?.ownershipValid === false) {
+    findings.push({
+      code: "task-claim-ownership-inconsistent",
+      severity: "error",
+      path: taskArtifactPath(taskId, "recovery"),
+      message: "Task claim ownership cannot be validated from recovery state and ledger history.",
+      remediation: `Run forgeloop validate-protocol --task ${taskId} --json and repair the reported protocol-owned artifact.`,
+      evidence: createEvidence({
+        kind: "BLOCKED",
+        source: taskArtifactPath(taskId, "events"),
+        result: "E_TASK_CLAIM_OWNERSHIP_INCONSISTENT",
+      }),
+    });
+  }
+
   if (state.status === "INVALID") {
     findings.push({
       code: "state-invalid",
@@ -132,6 +149,15 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
       evidence: protocolEvidence,
     },
     state: { ...state, path: WORK_STATE_PATH, present: statePresent },
+    recovery: taskInfo?.recovery ?? null,
+    claims: taskInfo ? {
+      state: taskInfo.claimState,
+      historical: taskInfo.historicalWriteClaims,
+      effective: taskInfo.effectiveWriteClaims,
+      mutationAllowed: taskInfo.mutationAllowed,
+      ownershipValid: taskInfo.ownershipValid,
+      ownershipErrors: taskInfo.ownershipErrors ?? taskInfo.errors ?? [],
+    } : null,
     continuity,
     compatibility: {
       deprecated: true,
@@ -142,6 +168,7 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
     ok: doctor.ok
       && !manifestError
       && schemaHealth.status === "valid"
+      && taskInfo?.ownershipValid !== false
       && !["INVALID", "REVALIDATION_REQUIRED"].includes(state.status)
       && continuityIsHealthy(continuity),
   };