@tetsuo-ai/agenc 0.17.0 → 0.19.0

package/lib/sqlite-lock.mjs

@@ -73,6 +73,8 @@ 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'
@@ -225,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) {
@@ -410,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],
       {
@@ -431,6 +479,16 @@ 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(
@@ -706,6 +764,7 @@ export async function assertLocalPrivateDirectory(
     label = "AgenC operation",
     deadline: suppliedDeadline,
     allowTrustedStickyLeaf = false,
+    onProgress,
   } = {},
 ) {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
@@ -717,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,
@@ -724,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);
@@ -764,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,
@@ -771,6 +836,7 @@ export async function assertLocalPrivateDirectory(
       })),
       context,
     );
+    reportProgress(context, "Windows ancestor ACL validation complete");
   } else {
     await assertLocalFilesystem(canonical, context);
     if (process.platform === "darwin") {
@@ -794,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;
 }
 
@@ -840,6 +907,7 @@ export async function assertLocalPrivateFile(
     timeoutMs = 60_000,
     label = "AgenC operation",
     deadline: suppliedDeadline,
+    onProgress,
   } = {},
 ) {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
@@ -848,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,
@@ -855,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}`);
@@ -886,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);
   }
@@ -898,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}`);
   }
@@ -935,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);
@@ -949,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 });
@@ -967,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()) {
@@ -980,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" },
@@ -1076,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 (
@@ -1098,6 +1199,7 @@ function beginAndValidateLock(database, path) {
         VALUES (1, ${LOCK_FORMAT_VERSION});
         COMMIT;
       `);
+      reportProgress(context, "SQLite lock database initialization complete");
       continue;
     }
     return;
@@ -1134,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);
 }
 
@@ -1143,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) {
@@ -1207,6 +1347,8 @@ export async function acquireLocalSqliteLocks(
     timeoutMs = 60_000,
     label = "AgenC operation",
     deadline: suppliedDeadline,
+    onProgress,
+    retryWakeSignal,
   } = {},
 ) {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
@@ -1218,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();
@@ -1228,6 +1376,9 @@ export async function acquireLocalSqliteLocks(
     ),
     label,
     timeoutMs,
+    onProgress,
+    retryWakeSignal,
+    retryWakeConsumed: false,
   };
   const firstDisplayPath = resolve(requestedPaths[0]);
   throwIfExpired(context, firstDisplayPath);
@@ -1238,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 = [];
@@ -1249,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;
@@ -1260,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 = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tetsuo-ai/agenc",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Public AgenC CLI launcher package",
   "license": "MIT",
   "type": "module",
@@ -21,6 +21,8 @@
     "src/launcher.mjs",
     "lib/activation-lock-identity.d.mts",
     "lib/activation-lock-identity.mjs",
+    "lib/home-authority.d.mts",
+    "lib/home-authority.mjs",
     "lib/generated-wrapper.d.mts",
     "lib/generated-wrapper.mjs",
     "lib/runtime-archive.d.mts",
@@ -32,11 +34,12 @@
     "lib/sqlite-lock.d.mts",
     "lib/sqlite-lock.mjs",
     "scripts/postinstall.mjs",
-    "generated/agenc-runtime-manifest-v2.json"
+    "generated/agenc-runtime-manifest-v2.json",
+    "generated/startup-preflight.mjs"
   ],
   "scripts": {
     "postinstall": "node ./scripts/postinstall.mjs",
-    "prepack": "node ./scripts/check-package-ready.mjs && node ../../scripts/canonicalize-package-modes.mjs .",
+    "prepack": "node ../../runtime/scripts/check-launcher-preflight.mjs --check && node ./scripts/check-package-ready.mjs && node ../../scripts/canonicalize-package-modes.mjs .",
     "build:runtime-tarball": "node ./scripts/build-runtime-tarball.mjs",
     "gen:manifest": "node ./scripts/gen-manifest.mjs",
     "test": "node --test test/*.test.mjs"

package/scripts/postinstall.mjs

@@ -2,6 +2,9 @@
 // Runs on `npm install @tetsuo-ai/agenc`. Pre-fetches the platform runtime so
 // the first `agenc` invocation is fast. Best-effort: a failure here (offline
 // install, CI, etc.) is NOT fatal — the launcher fetches lazily on first run.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 // Skip in obviously non-interactive / packaging contexts.
 if (process.env.AGENC_SKIP_POSTINSTALL === "1" || process.env.CI === "true") {
@@ -9,8 +12,26 @@ if (process.env.AGENC_SKIP_POSTINSTALL === "1" || process.env.CI === "true") {
 }
 
 try {
-  const { ensureRuntime } = await import("../lib/runtime-manager.mjs");
-  await ensureRuntime();
+  const { ensureRuntimeLaunch } = await import("../lib/runtime-manager.mjs");
+  const launch = await ensureRuntimeLaunch();
+  const helper = join(dirname(launch.runtimeBin), "prepare-peer-credentials.mjs");
+  if (existsSync(helper)) {
+    // Use the installed runtime's Node ABI and private library directory.
+    // Preparation only warms the user cache; signed package bytes stay intact.
+    const result = spawnSync(launch.nodeBin, [helper], {
+      env: {
+        ...process.env,
+        ...(launch.nodeLibraryPath === undefined
+          ? {}
+          : { LD_LIBRARY_PATH: launch.nodeLibraryPath }),
+      },
+      stdio: "inherit",
+      timeout: 30_000,
+    });
+    if (result.error !== undefined || result.status !== 0) {
+      process.stderr.write("agenc: native peer credential preparation skipped; startup will retry.\n");
+    }
+  }
 } catch (err) {
   process.stderr.write(
     `agenc: runtime pre-fetch skipped (${err?.message ?? err}); it will be fetched on first run.\n`,