@zq-silk/yui 0.15.11 → 0.16.0

package/dist/repository/projectMaintenanceLock.js

@@ -1,5 +1,8 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { setTimeout as delay } from "node:timers/promises";
+import { currentFileLockOwner, fileLockOwnerIsLive } from "../core/fileLockOwner.js";
 /**
  * Per-Project maintenance fence.
  *
@@ -12,35 +15,66 @@ import { join } from "node:path";
  * gone; the owner file records PID + process start time, so a recycled PID
  * can never pass for the original holder.
  *
- * Maintenance operations are long-lived, so a contended fence fails fast
- * with a retryable error instead of blocking the CLI for seconds.
+ * Contenders wait asynchronously within one monotonic budget. Only lock
+ * acquisition is retried; the caller's protected operation is never replayed.
  */
-const PROJECT_MAINTENANCE_LOCK_TIMEOUT_MS = 250;
-const PROJECT_MAINTENANCE_LOCK_RETRY_MS = 10;
+const PROJECT_MAINTENANCE_LOCK_TIMEOUT_MS = 60_000;
+const PROJECT_MAINTENANCE_LOCK_RETRY_MIN_MS = 200;
+const PROJECT_MAINTENANCE_LOCK_RETRY_MAX_MS = 500;
 /** A lock older than this with a dead owner is reclaimed. */
 const STALE_PROJECT_MAINTENANCE_LOCK_AGE_MS = 1_000;
 /**
- * Raised when a Project's maintenance fence is already held. The caller
- * made no changes and is safe to retry once the holder finishes.
+ * Raised when acquisition exhausted its budget. This acquisition has not
+ * started the protected operation; callers retain responsibility for any
+ * earlier effects and must not replay the whole operation implicitly.
  */
 export class ProjectMaintenanceLockedError extends Error {
+    timeoutMs;
     projectId;
     retryable = true;
-    constructor(projectId) {
-        super(`Project maintenance is already in progress for ${projectId}; retry once it finishes.`);
+    constructor(projectId, timeoutMs = PROJECT_MAINTENANCE_LOCK_TIMEOUT_MS) {
+        super(`Timed out after ${timeoutMs}ms waiting for Project maintenance on ${projectId}; `
+            + "the lock was not acquired. Read current state before retrying.");
+        this.timeoutMs = timeoutMs;
         this.name = "ProjectMaintenanceLockedError";
         this.projectId = projectId;
     }
 }
+export class ProjectMaintenanceLockCancelledError extends Error {
+    projectId;
+    constructor(projectId, cause) {
+        super(`Cancelled waiting for Project maintenance on ${projectId}; the lock was not acquired.`, { cause });
+        this.projectId = projectId;
+        this.name = "ProjectMaintenanceLockCancelledError";
+    }
+}
+function acquisitionBudget(options) {
+    const timeoutMs = options.timeoutMs ?? PROJECT_MAINTENANCE_LOCK_TIMEOUT_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+        throw new RangeError("Project maintenance timeout must be a finite nonnegative number.");
+    }
+    const now = options.now ?? (() => performance.now());
+    return {
+        timeoutMs,
+        deadline: now() + timeoutMs,
+        now,
+        random: options.random ?? Math.random,
+        wait: options.wait ?? ((milliseconds, signal) => delay(milliseconds, undefined, { signal })),
+        signal: options.signal
+    };
+}
+function assertNotCancelled(projectId, signal) {
+    if (signal?.aborted)
+        throw new ProjectMaintenanceLockCancelledError(projectId, signal.reason);
+}
 /** Directory of one Project's maintenance fence, below the Home's locks area. */
 export function projectMaintenanceLockPath(home, projectId) {
     return join(home, "locks", "projects", `${projectId}.lock`);
 }
 /**
  * Acquire one Project's maintenance fence. Returns the release function;
- * callers MUST release on every exit path (try/finally). A live holder
- * fails fast with {@link ProjectMaintenanceLockedError}; a stale (dead)
- * holder is reclaimed.
+ * callers MUST release on every exit path (try/finally). A live holder is
+ * never stolen, including at timeout; a stale (dead) holder is reclaimed.
  *
  * There is no in-process reentrancy: every acquisition contends, so two
  * independent operations in the same process are mutually exclusive just
@@ -48,14 +82,26 @@ export function projectMaintenanceLockPath(home, projectId) {
  * fence while its caller already holds it) goes through private
  * already-locked methods, never through a second acquisition.
  */
-export function acquireProjectMaintenanceLock(home, projectId) {
+export function acquireProjectMaintenanceLock(home, projectId, options = {}) {
+    return acquireWithBudget(home, projectId, acquisitionBudget(options));
+}
+async function acquireWithBudget(home, projectId, budget, firstProject = true) {
     const lock = projectMaintenanceLockPath(home, projectId);
+    assertNotCancelled(projectId, budget.signal);
+    const ownerIdentity = currentFileLockOwner();
     mkdirSync(join(home, "locks", "projects"), { recursive: true, mode: 0o700 });
-    const deadline = Date.now() + PROJECT_MAINTENANCE_LOCK_TIMEOUT_MS;
+    let firstAttempt = firstProject;
     while (true) {
+        assertNotCancelled(projectId, budget.signal);
+        // Always try the first Project immediately, even for a zero-budget probe.
+        // Every retry and subsequent Project shares the original deadline.
+        if (!firstAttempt && budget.now() >= budget.deadline) {
+            throw new ProjectMaintenanceLockedError(projectId, budget.timeoutMs);
+        }
+        firstAttempt = false;
         try {
             mkdirSync(lock, { mode: 0o700 });
-            const ownerIdentity = writeOwnerIdentity(lock);
+            writeOwnerIdentity(lock, ownerIdentity);
             let released = false;
             return () => {
                 if (released)
@@ -70,16 +116,27 @@ export function acquireProjectMaintenanceLock(home, projectId) {
         catch (error) {
             if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
                 throw error;
+            if (budget.now() >= budget.deadline) {
+                throw new ProjectMaintenanceLockedError(projectId, budget.timeoutMs);
+            }
             reclaimStaleProjectMaintenanceLock(lock);
-            if (Date.now() >= deadline)
-                throw new ProjectMaintenanceLockedError(projectId);
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, PROJECT_MAINTENANCE_LOCK_RETRY_MS);
+            const remaining = budget.deadline - budget.now();
+            if (remaining <= 0)
+                throw new ProjectMaintenanceLockedError(projectId, budget.timeoutMs);
+            const jitter = PROJECT_MAINTENANCE_LOCK_RETRY_MIN_MS
+                + budget.random() * (PROJECT_MAINTENANCE_LOCK_RETRY_MAX_MS - PROJECT_MAINTENANCE_LOCK_RETRY_MIN_MS);
+            try {
+                await budget.wait(Math.min(jitter, remaining), budget.signal);
+            }
+            catch (waitError) {
+                assertNotCancelled(projectId, budget.signal);
+                throw waitError;
+            }
         }
     }
 }
 /** Write this process's owner identity and return the exact bytes recorded. */
-function writeOwnerIdentity(lock) {
-    const identity = `${process.pid}:${processStartIdentity() ?? ""}`;
+function writeOwnerIdentity(lock, identity = currentFileLockOwner()) {
     writeFileSync(join(lock, "owner"), `${identity}\n`, { mode: 0o600 });
     return identity;
 }
@@ -108,11 +165,12 @@ function releaseOwnedProjectMaintenanceLock(lock, ownerIdentity) {
  * including ones this process already holds: callers that need nesting must
  * use an already-locked private path instead of acquiring twice.
  */
-export function acquireProjectMaintenanceLocks(home, projectIds) {
+export async function acquireProjectMaintenanceLocks(home, projectIds, options = {}) {
+    const budget = acquisitionBudget(options);
     const releases = [];
     try {
         for (const projectId of [...new Set(projectIds)].sort()) {
-            releases.push(acquireProjectMaintenanceLock(home, projectId));
+            releases.push(await acquireWithBudget(home, projectId, budget, releases.length === 0));
         }
     }
     catch (error) {
@@ -131,14 +189,17 @@ export function acquireProjectMaintenanceLocks(home, projectIds) {
 }
 /**
  * Non-blocking fence check for the Controller: a Project is fenced only
- * while a live process holds its lock. A stale (dead-owner) lock reads as
- * unfenced, so a crashed maintenance process never wedges preparation.
+ * while a live or unverified process holds its lock. Only proven stale owners
+ * read as unfenced; incomplete evidence never authorizes preparation.
  */
 export function isProjectMaintenanceFenced(home, projectId) {
     const lock = projectMaintenanceLockPath(home, projectId);
-    if (!existsSync(lock))
-        return false;
-    return lockOwnerIsAlive(lock);
+    try {
+        return fileLockOwnerIsLive(lock);
+    }
+    catch {
+        return true;
+    }
 }
 /**
  * Reclaim a stale (dead-owner) lock through a crash-safe compare-and-delete
@@ -156,9 +217,8 @@ function reclaimStaleProjectMaintenanceLock(lock) {
     catch (error) {
         if (!isEnoent(error))
             throw error;
-        // Ownerless lock: a crash between mkdir and owner publication. Reclaim
-        // only when the directory is old enough that the creator is not still
-        // initializing; a fresh lock may have its owner file written imminently.
+        // Allow publication its initial grace period; an older missing owner is
+        // diagnosed as unverified below, never treated as a dead creator.
         try {
             if (Date.now() - statSync(lock).mtimeMs < STALE_PROJECT_MAINTENANCE_LOCK_AGE_MS)
                 return;
@@ -179,7 +239,7 @@ function reclaimStaleProjectMaintenanceLock(lock) {
             return;
         throw error;
     }
-    if (expectedOwner !== null && lockOwnerIsAlive(lock))
+    if (fileLockOwnerIsLive(lock))
         return;
     const reclaimLock = `${lock}.reclaim`;
     for (let attempt = 0; attempt < 2; attempt += 1) {
@@ -228,7 +288,7 @@ function reclaimStaleProjectMaintenanceLock(lock) {
             }
             if (currentOwner !== expectedOwner)
                 return;
-            if (currentOwner !== null && lockOwnerIsAlive(lock))
+            if (fileLockOwnerIsLive(lock))
                 return;
             rmSync(lock, { recursive: true, force: true });
         }
@@ -240,70 +300,26 @@ function reclaimStaleProjectMaintenanceLock(lock) {
 }
 /**
  * Reclaim a reclaim-lock directory only when it is provably orphaned: its
- * owner is dead (or unrecorded) AND it is older than the age bound, so a
+ * owner is provably dead AND it is older than the age bound, so a
  * lock whose owner just mkdir'ed but has not written its owner is not stolen.
  * Uses the same PID + start-time identity check as the main fence, so a
  * recycled PID with a different start identity does not keep an orphaned
- * reclaim lock alive. An ownerless (ENOENT owner) lock is still reclaimed;
- * an unreadable owner fails closed (treated as live).
+ * reclaim lock alive. An ownerless or unreadable lock remains unverified.
  * Returns true when it removed the lock (caller retries), false otherwise.
  */
 function reclaimOrphanedReclaimLock(reclaimLock) {
     try {
         if (Date.now() - statSync(reclaimLock).mtimeMs < STALE_PROJECT_MAINTENANCE_LOCK_AGE_MS)
             return false;
-        if (lockOwnerIsAlive(reclaimLock))
+        if (fileLockOwnerIsLive(reclaimLock))
             return false;
         rmSync(reclaimLock, { recursive: true, force: true });
         return true;
     }
     catch (error) {
-        return isEnoent(error);
-    }
-}
-function lockOwnerIsAlive(lock) {
-    let owner;
-    try {
-        owner = readFileSync(join(lock, "owner"), "utf8").trim();
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-            return false;
-        // An unreadable owner file fails closed: treat the fence as held.
-        return true;
-    }
-    const separator = owner.indexOf(":");
-    const pid = Number.parseInt(separator < 0 ? owner : owner.slice(0, separator), 10);
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
-    const recordedIdentity = separator < 0 ? "" : owner.slice(separator + 1);
-    // PID + start-time identity: a recycled PID can never match the holder.
-    const currentIdentity = processStartIdentity(pid);
-    if (currentIdentity !== undefined) {
-        return recordedIdentity !== "" && currentIdentity === recordedIdentity;
-    }
-    // Off /proc (non-Linux): fall back to liveness.
-    return processIsAlive(pid);
-}
-/** Linux process start time (clock ticks since boot) for a PID; undefined off /proc. */
-function processStartIdentity(pid = process.pid) {
-    try {
-        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
-        const close = stat.lastIndexOf(")");
-        const fields = stat.slice(close + 2).split(" ");
-        return fields[19] ?? "0"; // field 22: starttime
-    }
-    catch {
-        return undefined;
-    }
-}
-function processIsAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return error instanceof Error && "code" in error && error.code === "EPERM";
+        if (isEnoent(error))
+            return true;
+        throw error;
     }
 }
 function isEnoent(error) {

package/dist/repository/taskBaseFreshness.js

@@ -95,7 +95,7 @@ export async function inspectTaskBaseFreshness(taskId, store, options = {}) {
             baseRef: binding.baseRef,
             baseCommit,
             status,
-            source: tracked?.source ?? (project.remoteUrl === undefined ? "not-applicable" : "compatibility-projection"),
+            source: tracked?.source ?? (project.remoteUrl === undefined ? "not-applicable" : "unknown"),
             workspacePath,
             workspaceClean,
             ...(physicalHead === undefined ? {} : { physicalHead }),