@tetsuo-ai/agenc 0.16.1 → 0.19.0

package/lib/sqlite-lock.mjs

@@ -7,6 +7,14 @@
 // contention is retried asynchronously against one monotonic deadline.
 
 import { execFile } from "node:child_process";
+import {
+  closeSync,
+  constants as fsConstants,
+  fstatSync,
+  lstatSync,
+  openSync,
+  realpathSync,
+} from "node:fs";
 import {
   chmod,
   lstat,
@@ -33,7 +41,18 @@ const REGISTRY_SYMBOL = Symbol.for("@tetsuo-ai/agenc.sqlite-lock-registry");
 const MAX_BUSY_RETRY_MS = 50;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 const UNSUPPORTED_FILE_ID_64 = 0xffff_ffff_ffff_ffffn;
+const WINDOWS_PATH_TRANSPORT_MAX_CHARS = 16_384;
+const WINDOWS_PATH_TRANSPORT_MAX_ENTRIES = 128;
 const WINDOWS_SYSTEM_ROOT = String.raw`\\?\GLOBALROOT\SystemRoot`;
+const WINDOWS_EXECUTABLE_FILESYSTEM = {
+  lstat: (path) => lstatSync(path, { bigint: true }),
+  open: (path) => openSync(
+    path,
+    fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0),
+  ),
+  fstat: (descriptor) => fstatSync(descriptor, { bigint: true }),
+  close: closeSync,
+};
 const LOCAL_FILESYSTEM_TYPES = new Set([
   "apfs", "bcachefs", "btrfs", "exfat", "ext2", "ext3", "ext4", "f2fs",
   "hfs", "hfsplus", "jfs", "msdos", "nilfs2", "ntfs", "ntfs3", "overlay",
@@ -54,10 +73,20 @@ const DARWIN_ACL_KNOWN_TOKENS = new Set([
   ...DARWIN_ACL_INHERITANCE_FLAGS,
   ...DARWIN_ACL_MUTATION_RIGHTS,
 ]);
+const DARWIN_ACL_VERDICT_CACHE_LIMIT = 512;
+const darwinAclVerdicts = new Map();
 
 const WINDOWS_SECURITY_SCRIPT = String.raw`
 $ErrorActionPreference = 'Stop'
-$entries = @(ConvertFrom-Json -InputObject $env:AGENC_LOCK_PATHS_JSON)
+# Keep this direct-.NET only: module autoload can exhaust the shared lock deadline.
+$transport = [string]$env:AGENC_LOCK_PATHS
+if ([string]::IsNullOrEmpty($transport) -or $transport.Length -gt ${WINDOWS_PATH_TRANSPORT_MAX_CHARS}) {
+  throw 'invalid protected-path transport'
+}
+$entries = [string[]]$transport.Split([char]10)
+if ($entries.Count -lt 1 -or $entries.Count -gt ${WINDOWS_PATH_TRANSPORT_MAX_ENTRIES}) {
+  throw 'invalid protected-path transport'
+}
 $currentSid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
 $trusted = @(
   $currentSid,
@@ -65,27 +94,50 @@ $trusted = @(
   'S-1-5-32-544',
   'S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464'
 )
-$leafMutationMask = [int64]852310
-$ancestorMutationMask = [int64]852306
+# Specific mutation rights plus GENERIC_WRITE and GENERIC_ALL.
+$leafMutationMask = [int64]1343029590
+$ancestorMutationMask = [int64]1343029586
 foreach ($entry in $entries) {
-  $requested = [string]$entry.path
-  $role = [string]$entry.role
+  $separator = $entry.IndexOf([char]58)
+  if ($separator -lt 1 -or $separator -eq ($entry.Length - 1)) {
+    throw 'invalid protected-path transport'
+  }
+  $role = $entry.Substring(0, $separator)
   if (@('leafDirectory', 'ancestorDirectory', 'file') -notcontains $role) {
     throw "invalid protected-path role: $role"
   }
+  $encodedPath = $entry.Substring($separator + 1)
+  if (($encodedPath.Length % 4) -ne 0) { throw 'invalid protected-path transport' }
+  $pathBytes = [System.Convert]::FromBase64String($encodedPath)
+  if (($pathBytes.Length % 2) -ne 0) { throw 'invalid protected-path transport' }
+  if ([System.Convert]::ToBase64String($pathBytes) -cne $encodedPath) {
+    throw 'non-canonical protected-path transport'
+  }
+  $pathCharacters = [char[]]::new([int]($pathBytes.Length / 2))
+  for ($index = 0; $index -lt $pathCharacters.Length; $index += 1) {
+    $byteOffset = $index * 2
+    $lowByte = [int]$pathBytes[$byteOffset]
+    $highByte = [int]$pathBytes[$byteOffset + 1]
+    $pathCharacters[$index] = [char]($lowByte -bor ($highByte -shl 8))
+  }
+  $requested = [string]::new($pathCharacters)
   $mutationMask = if ($role -eq 'ancestorDirectory') {
     $ancestorMutationMask
   } else {
     $leafMutationMask
   }
-  $full = [System.IO.Path]::GetFullPath([string]$requested)
+  $full = [System.IO.Path]::GetFullPath($requested)
   if ($full.StartsWith('\\') -or $full.StartsWith('\\?\') -or $full.StartsWith('\\.\')) {
     throw "network and device paths are unsupported: $full"
   }
-  $item = Get-Item -LiteralPath $full -Force
-  if (($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) {
+  $attributes = [System.IO.File]::GetAttributes($full)
+  if (($attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) {
     throw "reparse points are unsupported: $full"
   }
+  $isDirectory = ($attributes -band [System.IO.FileAttributes]::Directory) -ne 0
+  if ($isDirectory -ne ($role -ne 'file')) {
+    throw "protected-path role does not match its type: $full"
+  }
   $drive = [System.IO.DriveInfo]::new([System.IO.Path]::GetPathRoot($full))
   if (@(2, 3, 6) -notcontains [int]$drive.DriveType) {
     throw "non-local drive is unsupported: $full"
@@ -93,12 +145,16 @@ foreach ($entry in $entries) {
   if ($drive.DriveFormat -ne 'NTFS') {
     throw "filesystem cannot enforce the required ACL contract: $full"
   }
-  $acl = Get-Acl -LiteralPath $full
+  $aclSections = [System.Security.AccessControl.AccessControlSections]::Owner -bor [System.Security.AccessControl.AccessControlSections]::Access
+  if ($isDirectory) {
+    $acl = [System.IO.Directory]::GetAccessControl($full, $aclSections)
+  } else {
+    $acl = [System.IO.File]::GetAccessControl($full, $aclSections)
+  }
   if (-not $acl.AreAccessRulesCanonical) {
     throw "non-canonical ACL is unsupported: $full"
   }
-  $bytes = [byte[]]::new($acl.BinaryLength)
-  $acl.GetSecurityDescriptorBinaryForm($bytes, 0)
+  $bytes = $acl.GetSecurityDescriptorBinaryForm()
   $raw = [System.Security.AccessControl.RawSecurityDescriptor]::new($bytes, 0)
   if ($null -eq $raw.DiscretionaryAcl) {
     throw "null DACL is unsupported: $full"
@@ -125,7 +181,8 @@ foreach ($entry in $entries) {
       }
     }
     $sid = $rule.IdentityReference.Value
-    if ($trusted -notcontains $sid -and (([int64]$rule.FileSystemRights -band $mutationMask) -ne 0)) {
+    $rights = ([int64]$rule.FileSystemRights) -band [int64]4294967295
+    if ($trusted -notcontains $sid -and (($rights -band $mutationMask) -ne 0)) {
       throw "untrusted mutation ACE on lock path: $full"
     }
   }
@@ -170,6 +227,17 @@ function throwIfExpired(context, path, cause) {
   }
 }
 
+function reportProgress(context, phase) {
+  try {
+    const result = context.onProgress?.(phase);
+    if (result !== undefined) {
+      void Promise.resolve(result).catch(() => {});
+    }
+  } catch {
+    // Diagnostics must never change lock acquisition or release semantics.
+  }
+}
+
 function processLockRegistry() {
   const current = process[REGISTRY_SYMBOL];
   if (current !== undefined) {
@@ -355,10 +423,45 @@ function validateDarwinAclListing(stdout, path, role) {
 }
 
 async function assertDarwinPathSecurity(path, role, context) {
+  return assertDarwinPathSecurityWithIO(
+    path,
+    role,
+    context,
+    execFileUtf8,
+    (candidate) => lstat(candidate, { bigint: true }),
+  );
+}
+
+// HFS+ reports change time in whole seconds, so an ACL edit within the same
+// second can leave the identity unchanged. Only sub-second change times are
+// precise enough to cache a verdict.
+function hasSubsecondChangeTime(stats) {
+  if (typeof stats.ctimeNs === "bigint") return stats.ctimeNs % 1_000_000_000n !== 0n;
+  return Number.isFinite(stats.ctimeMs) && stats.ctimeMs % 1000 !== 0;
+}
+
+function darwinAclIdentity(stats) {
+  return [
+    stats.dev, stats.ino, stats.ctimeNs ?? stats.ctimeMs,
+    stats.mode, stats.uid, stats.gid,
+    process.getuid?.(), process.geteuid?.(),
+  ].join(":");
+}
+
+async function assertDarwinPathSecurityWithIO(path, role, context, lister, statPath) {
   throwIfExpired(context, path);
+  // A Darwin ACL edit advances ctime. Re-stat on every lookup so an old
+  // successful verdict cannot authorize a changed inode, owner, or ACL.
+  const before = darwinAclIdentity(await statPath(path));
+  const cacheKey = `${role}\0${path}`;
+  if (darwinAclVerdicts.get(cacheKey) === before) {
+    throwIfExpired(context, path);
+    return;
+  }
+  darwinAclVerdicts.delete(cacheKey);
   let result;
   try {
-    result = await execFileUtf8(
+    result = await lister(
       "/bin/ls",
       ["-ldeq", path],
       {
@@ -376,33 +479,136 @@ async function assertDarwinPathSecurity(path, role, context) {
   }
   validateDarwinAclListing(result.stdout, path, role);
   throwIfExpired(context, path);
+  // A path changed while ls ran must never seed a verdict for its new state.
+  const afterStats = await statPath(path);
+  const after = darwinAclIdentity(afterStats);
+  throwIfExpired(context, path);
+  if (after === before && hasSubsecondChangeTime(afterStats)) {
+    if (darwinAclVerdicts.size >= DARWIN_ACL_VERDICT_CACHE_LIMIT) {
+      darwinAclVerdicts.delete(darwinAclVerdicts.keys().next().value);
+    }
+    darwinAclVerdicts.set(cacheKey, before);
+  }
 }
 
-function trustedWindowsPowerShellPath() {
-  // GLOBALROOT enters the true system object-manager namespace instead of a
-  // session-specific or environment-selected DOS path. Never resolve this
-  // executable through PATH, SystemRoot, WINDIR, or another caller-controlled
-  // value.
+function trustedWindowsPowerShellPath(
+  canonicalize = realpathSync.native,
+  filesystem = WINDOWS_EXECUTABLE_FILESYSTEM,
+) {
+  // Derive a CreateProcess-compatible DOS spelling from GLOBALROOT, then prove
+  // both spellings still name the same regular system file before launch.
+  const systemRoot = canonicalize(WINDOWS_SYSTEM_ROOT);
+  if (!/^[a-z]:\\/iu.test(systemRoot) || win32.normalize(systemRoot) !== systemRoot) {
+    throw new Error("trusted Windows SystemRoot did not resolve to a canonical local DOS path");
+  }
+  const workingDirectory = win32.join(systemRoot, "System32");
+  const executable = win32.join(
+    workingDirectory,
+    "WindowsPowerShell",
+    "v1.0",
+    "powershell.exe",
+  );
+  const namespaceExecutable = win32.join(
+    WINDOWS_SYSTEM_ROOT,
+    "System32",
+    "WindowsPowerShell",
+    "v1.0",
+    "powershell.exe",
+  );
+  verifyWindowsExecutableAliases(namespaceExecutable, executable, filesystem);
   return {
-    systemRoot: WINDOWS_SYSTEM_ROOT,
-    workingDirectory: win32.join(WINDOWS_SYSTEM_ROOT, "System32"),
-    executable: win32.join(
-      WINDOWS_SYSTEM_ROOT,
-      "System32",
-      "WindowsPowerShell",
-      "v1.0",
-      "powershell.exe",
-    ),
+    systemRoot,
+    workingDirectory,
+    executable,
   };
 }
 
-function windowsPowerShellEnvironment(paths) {
-  const { systemRoot, workingDirectory } = trustedWindowsPowerShellPath();
+function verifyWindowsExecutableAliases(namespaceExecutable, executable, filesystem) {
+  let namespaceDescriptor;
+  let candidateDescriptor;
+  let operationError;
+  try {
+    const namespaceBefore = filesystem.lstat(namespaceExecutable);
+    const candidateBefore = filesystem.lstat(executable);
+    assertRegularWindowsExecutable(namespaceBefore, "GLOBALROOT path");
+    assertRegularWindowsExecutable(candidateBefore, "DOS path");
+    namespaceDescriptor = filesystem.open(namespaceExecutable);
+    candidateDescriptor = filesystem.open(executable);
+    const namespaceOpened = filesystem.fstat(namespaceDescriptor);
+    const candidateOpened = filesystem.fstat(candidateDescriptor);
+    const namespaceAfter = filesystem.lstat(namespaceExecutable);
+    const candidateAfter = filesystem.lstat(executable);
+    assertRegularWindowsExecutable(namespaceOpened, "GLOBALROOT descriptor");
+    assertRegularWindowsExecutable(candidateOpened, "DOS descriptor");
+    assertRegularWindowsExecutable(namespaceAfter, "GLOBALROOT path");
+    assertRegularWindowsExecutable(candidateAfter, "DOS path");
+    for (const identity of [
+      namespaceBefore,
+      candidateBefore,
+      namespaceOpened,
+      candidateOpened,
+      namespaceAfter,
+      candidateAfter,
+    ]) {
+      if (
+        identity.dev <= 0n || identity.ino <= 0n ||
+        identity.dev === UNSUPPORTED_FILE_ID_64 || identity.ino === UNSUPPORTED_FILE_ID_64
+      ) {
+        throw new Error("trusted Windows system executable identity is unavailable");
+      }
+    }
+    if (
+      !sameFileIdentity(namespaceBefore, namespaceOpened) ||
+      !sameFileIdentity(namespaceOpened, namespaceAfter) ||
+      !sameFileIdentity(candidateBefore, candidateOpened) ||
+      !sameFileIdentity(candidateOpened, candidateAfter) ||
+      !sameFileIdentity(namespaceOpened, candidateOpened)
+    ) {
+      throw new Error("trusted Windows system executable identity mismatch");
+    }
+  } catch (error) {
+    operationError = error;
+  }
+  const closeErrors = [];
+  for (const descriptor of [candidateDescriptor, namespaceDescriptor]) {
+    if (descriptor === undefined) continue;
+    try { filesystem.close(descriptor); } catch (error) { closeErrors.push(error); }
+  }
+  if (operationError !== undefined) {
+    if (closeErrors.length > 0) {
+      throw new AggregateError(
+        [operationError, ...closeErrors],
+        "trusted Windows executable validation and cleanup both failed",
+      );
+    }
+    throw operationError;
+  }
+  if (closeErrors.length === 1) throw closeErrors[0];
+  if (closeErrors.length > 1) {
+    throw new AggregateError(
+      closeErrors,
+      "trusted Windows executable descriptor cleanup failed",
+    );
+  }
+}
+
+function assertRegularWindowsExecutable(identity, spelling) {
+  if (!identity.isFile() || identity.isSymbolicLink()) {
+    throw new Error(`trusted Windows ${spelling} executable is not a regular non-link file`);
+  }
+}
+
+function sameFileIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function windowsPowerShellEnvironment(paths, trustedPaths = trustedWindowsPowerShellPath()) {
+  const { systemRoot, workingDirectory } = trustedPaths;
   // libuv fills a fixed set of "required" Windows variables from the parent
   // when they are absent. Define every one so poisoned caller state cannot be
   // silently inherited into the validation helper.
   return {
-    AGENC_LOCK_PATHS_JSON: JSON.stringify(paths),
+    AGENC_LOCK_PATHS: windowsPathTransport(paths),
     APPDATA: "",
     COMSPEC: "",
     HOMEDRIVE: "",
@@ -423,10 +629,42 @@ function windowsPowerShellEnvironment(paths) {
   };
 }
 
+function windowsPathTransport(entries) {
+  if (
+    !Array.isArray(entries) ||
+    entries.length < 1 ||
+    entries.length > WINDOWS_PATH_TRANSPORT_MAX_ENTRIES
+  ) {
+    throw new Error("agenc: Windows protected-path transport has an invalid entry count");
+  }
+  const records = [];
+  let transportChars = 0;
+  for (const entry of entries) {
+    const path = entry?.path;
+    const role = entry?.role;
+    if (
+      typeof path !== "string" ||
+      path.length === 0 ||
+      path.length > WINDOWS_PATH_TRANSPORT_MAX_CHARS ||
+      (role !== "leafDirectory" && role !== "ancestorDirectory" && role !== "file")
+    ) {
+      throw new Error("agenc: Windows protected-path transport entry is invalid");
+    }
+    const record = `${role}:${Buffer.from(path, "utf16le").toString("base64")}`;
+    transportChars += record.length + (records.length === 0 ? 0 : 1);
+    if (transportChars > WINDOWS_PATH_TRANSPORT_MAX_CHARS) {
+      throw new Error("agenc: Windows protected-path transport exceeds its limit");
+    }
+    records.push(record);
+  }
+  return records.join("\n");
+}
+
 async function assertWindowsPathSecurity(entries, context) {
   const displayPath = entries.at(-1)?.path ?? "unknown";
   throwIfExpired(context, displayPath);
-  const { workingDirectory, executable } = trustedWindowsPowerShellPath();
+  const trustedPaths = trustedWindowsPowerShellPath();
+  const { workingDirectory, executable } = trustedPaths;
   let result;
   try {
     result = await execFileUtf8(
@@ -440,7 +678,7 @@ async function assertWindowsPathSecurity(entries, context) {
       ],
       {
         cwd: workingDirectory,
-        env: windowsPowerShellEnvironment(entries),
+        env: windowsPowerShellEnvironment(entries, trustedPaths),
         maxBuffer: 1024 * 1024,
         windowsHide: true,
       },
@@ -526,6 +764,7 @@ export async function assertLocalPrivateDirectory(
     label = "AgenC operation",
     deadline: suppliedDeadline,
     allowTrustedStickyLeaf = false,
+    onProgress,
   } = {},
 ) {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
@@ -537,6 +776,9 @@ export async function assertLocalPrivateDirectory(
   if (typeof allowTrustedStickyLeaf !== "boolean") {
     throw new TypeError("allowTrustedStickyLeaf must be boolean");
   }
+  if (onProgress !== undefined && typeof onProgress !== "function") {
+    throw new TypeError("lock onProgress must be a function");
+  }
   const context = {
     deadline: Math.min(
       suppliedDeadline ?? Number.POSITIVE_INFINITY,
@@ -544,7 +786,9 @@ export async function assertLocalPrivateDirectory(
     ),
     label,
     timeoutMs,
+    onProgress,
   };
+  reportProgress(context, "private directory validation started");
   const absolute = resolve(requestedPath);
   throwIfExpired(context, absolute);
   const canonical = await realpath(absolute);
@@ -584,6 +828,7 @@ export async function assertLocalPrivateDirectory(
     identityFromStats(stats, path);
   }
   if (process.platform === "win32") {
+    reportProgress(context, "Windows ancestor ACL validation started");
     await assertWindowsPathSecurity(
       ancestors.map((path, index) => ({
         path,
@@ -591,6 +836,7 @@ export async function assertLocalPrivateDirectory(
       })),
       context,
     );
+    reportProgress(context, "Windows ancestor ACL validation complete");
   } else {
     await assertLocalFilesystem(canonical, context);
     if (process.platform === "darwin") {
@@ -614,6 +860,7 @@ export async function assertLocalPrivateDirectory(
       throw new Error(`agenc: protected directory identity changed during validation: ${path}`);
     }
   }
+  reportProgress(context, "private directory validation complete");
   return canonical;
 }
 
@@ -660,6 +907,7 @@ export async function assertLocalPrivateFile(
     timeoutMs = 60_000,
     label = "AgenC operation",
     deadline: suppliedDeadline,
+    onProgress,
   } = {},
 ) {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
@@ -668,6 +916,9 @@ export async function assertLocalPrivateFile(
   if (suppliedDeadline !== undefined && !Number.isFinite(suppliedDeadline)) {
     throw new TypeError("lock deadline must be finite");
   }
+  if (onProgress !== undefined && typeof onProgress !== "function") {
+    throw new TypeError("lock onProgress must be a function");
+  }
   const context = {
     deadline: Math.min(
       suppliedDeadline ?? Number.POSITIVE_INFINITY,
@@ -675,13 +926,16 @@ export async function assertLocalPrivateFile(
     ),
     label,
     timeoutMs,
+    onProgress,
   };
+  reportProgress(context, "private file validation started");
   const absolute = resolve(requestedPath);
   const parent = dirname(absolute);
   const canonicalParent = await assertLocalPrivateDirectory(parent, {
     timeoutMs,
     label,
     deadline: context.deadline,
+    ...(onProgress === undefined ? {} : { onProgress }),
   });
   if (canonicalParent !== parent) {
     throw new Error(`agenc: protected file parent must use its canonical path: ${parent}`);
@@ -706,7 +960,9 @@ export async function assertLocalPrivateFile(
     throw new Error(`agenc: protected file must use its canonical path: ${absolute}`);
   }
   if (process.platform === "win32") {
+    reportProgress(context, "Windows file ACL validation started");
     await assertWindowsPathSecurity([{ path: canonical, role: "file" }], context);
+    reportProgress(context, "Windows file ACL validation complete");
   } else if (process.platform === "darwin") {
     await assertDarwinPathSecurity(canonical, "file", context);
   }
@@ -718,21 +974,30 @@ export async function assertLocalPrivateFile(
   ) {
     throw new Error(`agenc: protected file identity changed during validation: ${canonical}`);
   }
+  reportProgress(context, "private file validation complete");
   return canonical;
 }
 
 async function prepareLockPath(requestedPath, context) {
   const absolute = resolve(requestedPath);
+  reportProgress(context, "lock path preparation started");
   throwIfExpired(context, absolute);
   await mkdir(dirname(absolute), { recursive: true, mode: 0o700 });
+  reportProgress(context, "lock parent creation complete");
   throwIfExpired(context, absolute);
   const parent = await realpath(dirname(absolute));
+  reportProgress(context, "lock parent canonicalization complete");
   throwIfExpired(context, absolute);
+  reportProgress(context, "lock parent security validation started");
   const validatedParent = await assertLocalPrivateDirectory(parent, {
     timeoutMs: context.timeoutMs,
     label: context.label,
     deadline: context.deadline,
+    ...(context.onProgress === undefined
+      ? {}
+      : { onProgress: context.onProgress }),
   });
+  reportProgress(context, "lock parent security validation complete");
   if (validatedParent !== parent) {
     throw new Error(`agenc: lock database parent must use its canonical path: ${parent}`);
   }
@@ -755,6 +1020,7 @@ async function prepareLockPath(requestedPath, context) {
   } catch (error) {
     if (error?.code !== "EEXIST") throw error;
   }
+  reportProgress(context, "lock database file creation complete");
   throwIfExpired(context, path);
   const pathStats = await lstat(path, { bigint: true });
   assertRegularSingleLink(pathStats, path);
@@ -769,10 +1035,12 @@ async function prepareLockPath(requestedPath, context) {
       await assertDarwinPathSecurity(canonical, "lock database file", context);
     }
   } else {
+    reportProgress(context, "lock database ACL validation started");
     await assertWindowsPathSecurity([
       { path: parent, role: "leafDirectory" },
       { path: canonical, role: "file" },
     ], context);
+    reportProgress(context, "lock database ACL validation complete");
   }
   throwIfExpired(context, canonical);
   const securedStats = await lstat(canonical, { bigint: true });
@@ -787,7 +1055,11 @@ async function prepareLockPath(requestedPath, context) {
   };
 }
 
-async function revalidatePreparedLock(prepared, context) {
+async function revalidatePreparedLock(
+  prepared,
+  context,
+  { validateWindowsAcl = false } = {},
+) {
   throwIfExpired(context, prepared.path);
   const parentStats = await lstat(prepared.parent, { bigint: true });
   if (!parentStats.isDirectory() || parentStats.isSymbolicLink()) {
@@ -800,7 +1072,7 @@ async function revalidatePreparedLock(prepared, context) {
   if (stats.dev !== prepared.dev || stats.ino !== prepared.ino) {
     throw new Error(`agenc: lock database identity changed during acquisition: ${prepared.path}`);
   }
-  if (process.platform === "win32") {
+  if (process.platform === "win32" && validateWindowsAcl) {
     await assertWindowsPathSecurity([
       { path: prepared.parent, role: "leafDirectory" },
       { path: prepared.path, role: "file" },
@@ -896,18 +1168,27 @@ function busyTransitionError(path, mode) {
   );
 }
 
-function beginAndValidateLock(database, path) {
+function beginAndValidateLock(database, path, context) {
   for (let phase = 0; phase < 8; phase += 1) {
+    reportProgress(context, "SQLite transaction begin started");
     database.exec("BEGIN IMMEDIATE");
+    reportProgress(context, "SQLite transaction begin complete");
+    reportProgress(context, "SQLite lock database inspection started");
     const state = inspectLockDatabase(database, path);
+    reportProgress(context, "SQLite lock database inspection complete");
+    reportProgress(context, "SQLite journal mode inspection started");
     const journalMode = pragmaText(database, "journal_mode");
+    reportProgress(context, "SQLite journal mode inspection complete");
     if (journalMode !== "delete") {
+      reportProgress(context, "SQLite journal mode reset started");
       database.exec("ROLLBACK");
       const selected = pragmaText(database, "journal_mode=DELETE");
       if (selected !== "delete") throw busyTransitionError(path, selected);
+      reportProgress(context, "SQLite journal mode reset complete");
       continue;
     }
     if (state === "empty") {
+      reportProgress(context, "SQLite lock database initialization started");
       database.exec(`
         PRAGMA application_id = ${LOCK_APPLICATION_ID};
         CREATE TABLE agenc_local_process_lock (
@@ -918,6 +1199,7 @@ function beginAndValidateLock(database, path) {
         VALUES (1, ${LOCK_FORMAT_VERSION});
         COMMIT;
       `);
+      reportProgress(context, "SQLite lock database initialization complete");
       continue;
     }
     return;
@@ -954,7 +1236,32 @@ async function waitForBusyRetry(context, path, attempt, cause) {
   if (remaining <= 0) throw timeoutError(context, path, cause);
   const exponentialCap = Math.min(MAX_BUSY_RETRY_MS, 2 ** Math.min(attempt, 6));
   const jitter = Math.max(1, Math.floor(Math.random() * (exponentialCap + 1)));
-  await delay(Math.min(remaining, jitter));
+  const waitMs = Math.min(remaining, jitter);
+  const signal = context.retryWakeSignal;
+  if (signal === undefined || context.retryWakeConsumed) {
+    await delay(waitMs);
+  } else {
+    // A hint only shortens one sleep. The next attempt must still validate
+    // the path and acquire the SQLite transaction against the same deadline.
+    let timer;
+    let wake;
+    try {
+      await new Promise((resolve) => {
+        wake = () => {
+          context.retryWakeConsumed = true;
+          resolve();
+        };
+        timer = setTimeout(resolve, waitMs);
+        signal.addEventListener("abort", wake, { once: true });
+        // Covers readiness before subscription as well as before acquisition.
+        if (signal.aborted) wake();
+        reportProgress(context, "SQLite busy retry wait started");
+      });
+    } finally {
+      clearTimeout(timer);
+      if (wake !== undefined) signal.removeEventListener("abort", wake);
+    }
+  }
   throwIfExpired(context, path, cause);
 }
 
@@ -963,16 +1270,29 @@ async function acquireSqliteDatabase(DatabaseSync, prepared, context) {
   let lastBusy;
   while (true) {
     throwIfExpired(context, prepared.path, lastBusy);
-    await revalidatePreparedLock(prepared, context);
+    reportProgress(context, "SQLite pre-open lock validation started");
+    await revalidatePreparedLock(prepared, context, {
+      // The creation path already validated the complete ancestor chain and
+      // the exact parent/file ACLs. Revalidate ACLs after contention because
+      // another holder and an unbounded interval have crossed this attempt.
+      validateWindowsAcl: attempt > 0,
+    });
+    reportProgress(context, "SQLite pre-open lock validation complete");
     let database;
     try {
+      reportProgress(context, "SQLite database open started");
       database = new DatabaseSync(prepared.path, {
         allowExtension: false,
         timeout: 0,
       });
+      reportProgress(context, "SQLite database open complete");
+      reportProgress(context, "SQLite connection hardening started");
       configureLocalSqliteLockConnection(database);
+      reportProgress(context, "SQLite connection hardening complete");
+      reportProgress(context, "SQLite post-open lock validation started");
       await revalidatePreparedLock(prepared, context);
-      beginAndValidateLock(database, prepared.path);
+      reportProgress(context, "SQLite post-open lock validation complete");
+      beginAndValidateLock(database, prepared.path, context);
       throwIfExpired(context, prepared.path, lastBusy);
       return database;
     } catch (error) {
@@ -1027,6 +1347,8 @@ export async function acquireLocalSqliteLocks(
     timeoutMs = 60_000,
     label = "AgenC operation",
     deadline: suppliedDeadline,
+    onProgress,
+    retryWakeSignal,
   } = {},
 ) {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
@@ -1038,6 +1360,12 @@ export async function acquireLocalSqliteLocks(
   if (!Array.isArray(requestedPaths)) {
     throw new TypeError("lock paths must be an array");
   }
+  if (onProgress !== undefined && typeof onProgress !== "function") {
+    throw new TypeError("lock onProgress must be a function");
+  }
+  if (retryWakeSignal !== undefined && !(retryWakeSignal instanceof AbortSignal)) {
+    throw new TypeError("lock retryWakeSignal must be an AbortSignal");
+  }
   if (requestedPaths.length === 0) return () => {};
 
   const startedAt = performance.now();
@@ -1048,6 +1376,9 @@ export async function acquireLocalSqliteLocks(
     ),
     label,
     timeoutMs,
+    onProgress,
+    retryWakeSignal,
+    retryWakeConsumed: false,
   };
   const firstDisplayPath = resolve(requestedPaths[0]);
   throwIfExpired(context, firstDisplayPath);
@@ -1058,6 +1389,7 @@ export async function acquireLocalSqliteLocks(
     const prepared = await prepareLockPath(requestedPath, context);
     preparedByIdentity.set(prepared.identityKey, prepared);
   }
+  reportProgress(context, "lock path preparation complete");
   const preparedLocks = [...preparedByIdentity.values()].sort((left, right) =>
     left.identityKey < right.identityKey ? -1 : left.identityKey > right.identityKey ? 1 : 0);
   const pendingLocal = [];
@@ -1069,8 +1401,11 @@ export async function acquireLocalSqliteLocks(
       const release = await acquireInProcessLock(prepared, context);
       pendingLocal.push({ prepared, release });
     }
+    reportProgress(context, "in-process lock acquisition complete");
     throwIfExpired(context, currentPath);
+    reportProgress(context, "SQLite module import started");
     const { DatabaseSync } = await import("node:sqlite");
+    reportProgress(context, "SQLite module import complete");
     throwIfExpired(context, currentPath);
     for (const { prepared, release } of pendingLocal) {
       currentPath = prepared.path;
@@ -1080,7 +1415,9 @@ export async function acquireLocalSqliteLocks(
         inProcessReleased: false,
       };
       acquired.push(item);
+      reportProgress(context, "SQLite transaction acquisition started");
       item.database = await acquireSqliteDatabase(DatabaseSync, prepared, context);
+      reportProgress(context, "SQLite transaction acquisition complete");
     }
   } catch (error) {
     const cleanupErrors = [];