@stacksjs/defaults 0.75.360 → 0.75.362

package/ai/skills/stacks-technical-diagrams/scripts/check-update.mjs

@@ -0,0 +1,1717 @@
+#!/usr/bin/env node
+
+import crypto from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { fileURLToPath } from 'node:url';
+
+import {
+  DEFAULT_MANIFEST_URL,
+  SKILL_ID,
+  UpdateContractError,
+  compareSemver,
+  isStableCoreVersion,
+  parseSemver,
+  validateLocalRelease,
+  validateReleaseNotesUrl,
+  validateReleaseSummary,
+  validateStableUpdateManifest,
+} from './update-contract.mjs';
+import { sameEntry } from '../renderers/shared/path-semantics.mjs';
+
+const OPERATION_STATE_FILE = 'state.json';
+const OPERATION_OWNER_FILE = 'owner.json';
+const ACTIVE_CLAIM_DIRECTORY = 'active-claim';
+const OPERATION_NAME = /^(reserved|pending|committed|fenced|cancelled)-(\d{1,20})$/;
+const MAX_OPERATION_GENERATION = (10n ** 20n) - 1n;
+const CHECK_TTL_MS = 24 * 60 * 60 * 1_000;
+const MAX_CACHE_HORIZON_MS = Math.ceil(CHECK_TTL_MS * 1.2);
+const FIRST_FAILURE_DELAY_MS = 6 * 60 * 60 * 1_000;
+const LATER_FAILURE_DELAY_MS = 24 * 60 * 60 * 1_000;
+const DEFAULT_TIMEOUT_MS = 1_000;
+const MAX_RESPONSE_BYTES = 32 * 1_024;
+const MAX_LOCAL_RELEASE_BYTES = 4 * 1_024;
+const MAX_CACHE_STATE_BYTES = 64 * 1_024;
+const MAX_CLAIM_OWNER_BYTES = 1_024;
+const LONGEST_ISO_TIMESTAMP = '+275760-09-13T00:00:00.000Z';
+const LOCK_STALE_MS = 30_000;
+const PREFERENCE_LOCK_WAIT_MS = 1_200;
+const LOCK_RETRY_DELAY_MS = 20;
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const defaultReleasePath = path.resolve(scriptDirectory, '..', 'skill-release.json');
+
+class FileIdentityChangedError extends Error {}
+class ManifestWithdrawnError extends Error {}
+
+function silent(reason) {
+  return { status: 'silent', reason };
+}
+
+function updatesDisabled() {
+  return process.env.ARCHIFY_UPDATE_CHECK_DISABLED === '1';
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasOnlyKeys(value, allowed) {
+  return Object.keys(value).every((key) => allowed.has(key));
+}
+
+function validateManifest(value) {
+  const manifest = validateStableUpdateManifest(value);
+  return {
+    version: manifest.version,
+    targetDigest: `sha256:${manifest.artifact.sha256}`,
+    severity: manifest.severity,
+    summary: manifest.summary,
+    releaseNotes: manifest.releaseNotes,
+  };
+}
+
+function validateCachedCandidate(value) {
+  if (!isPlainObject(value)
+    || !hasOnlyKeys(value, new Set([
+      'version', 'targetDigest', 'severity', 'releaseNotes', 'checkedAt', 'summary',
+    ]))) return null;
+  try {
+    if (!isStableCoreVersion(value.version)) return null;
+    if (!DIGEST_PATTERN.test(value.targetDigest)
+      || !['normal', 'security'].includes(value.severity)) return null;
+    validateReleaseNotesUrl(value.releaseNotes, value.version);
+    if (Object.hasOwn(value, 'summary')) validateReleaseSummary(value.summary);
+    if (typeof value.checkedAt !== 'string' || !Number.isFinite(Date.parse(value.checkedAt))) return null;
+    return { ...value };
+  } catch {
+    return null;
+  }
+}
+
+function emptyState(installedVersion = null) {
+  return {
+    schemaVersion: 2,
+    skillId: SKILL_ID,
+    installedVersion,
+    check: {
+      nextCheckAt: null,
+      consecutiveFailures: 0,
+    },
+    preferences: [],
+  };
+}
+
+function validPreference(value) {
+  return isPlainObject(value)
+    && hasOnlyKeys(value, new Set(['targetDigest', 'version', 'mode', 'until']))
+    && DIGEST_PATTERN.test(value.targetDigest)
+    && isStableCoreVersion(value.version)
+    && ['ignore', 'snooze'].includes(value.mode)
+    && (value.mode === 'ignore' ? value.until === null
+      : typeof value.until === 'string' && Number.isFinite(Date.parse(value.until)));
+}
+
+function encodeBoundedState(state) {
+  const encoded = Buffer.from(`${JSON.stringify(state)}\n`, 'utf8');
+  return encoded.length <= MAX_CACHE_STATE_BYTES ? encoded : null;
+}
+
+function stateWithFailureCheck(state, nextCheckAt, consecutiveFailures, withdrawCandidate = false) {
+  const failedState = {
+    ...state,
+    check: { nextCheckAt, consecutiveFailures },
+  };
+  if (withdrawCandidate) delete failedState.candidate;
+  return failedState;
+}
+
+// A committed state must leave room for its own failure backoff.
+function encodeRecoverableState(state) {
+  const encoded = encodeBoundedState(state);
+  if (!encoded || !encodeBoundedState(stateWithFailureCheck(state, LONGEST_ISO_TIMESTAMP, 2))) return null;
+  return encoded;
+}
+
+function versionCacheDirectory(cacheDirectory, installedVersion) {
+  const partition = crypto.createHash('sha256').update(installedVersion).digest('hex').slice(0, 24);
+  return path.join(cacheDirectory, `version-${partition}`);
+}
+
+function normalizeState(value, installedVersion) {
+  const effectiveInstalledVersion = installedVersion ?? value?.installedVersion ?? null;
+  if (!isPlainObject(value) || value.schemaVersion !== 2 || value.skillId !== SKILL_ID
+    || (installedVersion !== null && value.installedVersion !== installedVersion)
+    || (value.installedVersion !== null && typeof value.installedVersion !== 'string')
+    || !isPlainObject(value.check)
+    || !(value.check.nextCheckAt === null || typeof value.check.nextCheckAt === 'string')
+    || !Number.isSafeInteger(value.check.consecutiveFailures)
+    || value.check.consecutiveFailures < 0
+    || !Array.isArray(value.preferences) || value.preferences.length > 32
+    || value.preferences.some((preference) => !validPreference(preference))) return null;
+  if (effectiveInstalledVersion !== null) {
+    try {
+      parseSemver(effectiveInstalledVersion);
+    } catch {
+      return null;
+    }
+  }
+
+  const state = emptyState(effectiveInstalledVersion);
+  state.check.nextCheckAt = value.check.nextCheckAt;
+  state.check.consecutiveFailures = value.check.consecutiveFailures;
+  state.preferences = value.preferences.map((preference) => ({ ...preference }));
+  const hasCandidate = Object.hasOwn(value, 'candidate');
+  const candidate = validateCachedCandidate(value.candidate);
+  if (hasCandidate && !candidate) return null;
+  if (candidate) state.candidate = candidate;
+  return encodeRecoverableState(state) ? state : null;
+}
+
+function isSameFile(left, right) {
+  if (left.dev !== right.dev || left.ino !== right.ino) return false;
+  if (left.ino !== 0n) return true;
+  if (left.birthtimeNs === 0n || right.birthtimeNs === 0n) return false;
+  return left.birthtimeNs === right.birthtimeNs
+    && left.mode === right.mode;
+}
+
+function assertBoundedRegularFile(metadata, maxBytes) {
+  if (!metadata.isFile()
+    || metadata.isSymbolicLink()
+    || metadata.size > BigInt(maxBytes)) {
+    throw new Error('unsafe JSON file');
+  }
+}
+
+async function readJsonFile(target, maxBytes, expectedMetadata = null) {
+  const pathMetadata = await fs.lstat(target, { bigint: true });
+  if (expectedMetadata && !isSameFile(expectedMetadata, pathMetadata)) {
+    throw new FileIdentityChangedError('JSON file identity changed');
+  }
+  assertBoundedRegularFile(pathMetadata, maxBytes);
+  const flags = fsConstants.O_RDONLY
+    | (fsConstants.O_NOFOLLOW ?? 0)
+    | (fsConstants.O_NONBLOCK ?? 0);
+  const handle = await fs.open(target, flags);
+  try {
+    const handleMetadata = await handle.stat({ bigint: true });
+    const currentPathMetadata = await fs.lstat(target, { bigint: true });
+    assertBoundedRegularFile(handleMetadata, maxBytes);
+    assertBoundedRegularFile(currentPathMetadata, maxBytes);
+    if (!isSameFile(pathMetadata, handleMetadata)
+      || !isSameFile(currentPathMetadata, handleMetadata)) {
+      throw new FileIdentityChangedError('JSON file changed while opening');
+    }
+
+    const chunks = [];
+    let size = 0;
+    while (size <= maxBytes) {
+      const chunk = Buffer.allocUnsafe(Math.min(8 * 1_024, (maxBytes + 1) - size));
+      const { bytesRead } = await handle.read(chunk, 0, chunk.length, size);
+      if (bytesRead === 0) break;
+      chunks.push(chunk.subarray(0, bytesRead));
+      size += bytesRead;
+    }
+    if (size > maxBytes) throw new Error('JSON file is too large');
+    return JSON.parse(Buffer.concat(chunks, size).toString('utf8'));
+  } finally {
+    await handle.close();
+  }
+}
+
+function isWithinDirectory(directory, target) {
+  const relative = path.relative(directory, target);
+  return relative === ''
+    // path-contract-allow: lexical-capability -- No-follow snapshots bind this mutation boundary.
+    || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
+}
+
+async function physicalDirectorySuffix(directory, target) {
+  const absoluteTarget = path.resolve(target);
+  const parsed = path.parse(absoluteTarget);
+  const segments = absoluteTarget.slice(parsed.root.length).split(path.sep).filter(Boolean);
+  let prefix = parsed.root;
+  for (let index = 0; index < segments.length; index += 1) {
+    prefix = path.join(prefix, segments[index]);
+    const relation = sameEntry(directory, prefix);
+    if (relation.status === 'match') {
+      const metadata = await fs.lstat(prefix, { bigint: true });
+      if (metadata.isSymbolicLink()) {
+        throw new Error(`trusted cache prefix is a symbolic link or junction: ${prefix}`);
+      }
+      return segments.slice(index + 1);
+    }
+    if (relation.status === 'unknown' && relation.reason.code === 'entry-missing') break;
+  }
+  return null;
+}
+
+async function canonicalizeTrustedDirectoryPrefix(target) {
+  const absoluteTarget = path.resolve(target);
+  const trustedDirectories = [...new Set([os.homedir(), os.tmpdir()].map((directory) => (
+    path.resolve(directory)
+  )))].sort((left, right) => right.length - left.length);
+  for (const trustedDirectory of trustedDirectories) {
+    const suffix = await physicalDirectorySuffix(trustedDirectory, absoluteTarget);
+    if (suffix === null) continue;
+    try {
+      const canonicalDirectory = await fs.realpath(trustedDirectory);
+      return path.resolve(canonicalDirectory, ...suffix);
+    } catch {
+      // Fall back to validating the absolute path from its filesystem root.
+    }
+  }
+  return target;
+}
+
+function assertSafeDirectory(metadata) {
+  if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+    throw new Error('unsafe cache directory');
+  }
+}
+
+class CachePathChangedError extends Error {}
+class CacheOperationRaceError extends Error {}
+class OperationFencedError extends Error {}
+
+const preparedCacheDirectories = new Map();
+
+function invalidateCacheToken(token, message, cause) {
+  token.trusted = false;
+  if (cause instanceof CachePathChangedError) return cause;
+  const error = new CachePathChangedError(message);
+  if (cause) error.cause = cause;
+  return error;
+}
+
+async function verifyDirectorySnapshots(token, snapshots, description) {
+  if (!token.trusted) throw new CachePathChangedError('cache directory is no longer trusted');
+  try {
+    for (const snapshot of snapshots) {
+      const metadata = await fs.lstat(snapshot.directory, { bigint: true });
+      assertSafeDirectory(metadata);
+      if (!isSameFile(snapshot.metadata, metadata)) {
+        throw new Error(`${description} changed`);
+      }
+    }
+  } catch (error) {
+    throw invalidateCacheToken(token, `${description} changed`, error);
+  }
+}
+
+async function verifyCacheToken(token) {
+  await verifyDirectorySnapshots(token, token.ancestorSnapshots, 'cache directory');
+}
+
+async function guardedCacheRead(token, read) {
+  await verifyCacheToken(token);
+  let result;
+  try {
+    result = await read();
+  } catch (error) {
+    await verifyCacheToken(token);
+    throw error;
+  }
+  await verifyCacheToken(token);
+  return result;
+}
+
+function cacheTokenFor(cacheDirectory) {
+  const token = preparedCacheDirectories.get(path.resolve(cacheDirectory));
+  if (!token || !token.trusted) {
+    throw new CachePathChangedError('cache directory has not been prepared safely');
+  }
+  return token;
+}
+
+function resolveCacheTarget(token, target) {
+  const resolved = path.resolve(target);
+  const relative = path.relative(token.directory, resolved);
+  // This is a lexical capability check, not a physical-containment query. The
+  // async lstat snapshots below bind the prepared directory and every mutation
+  // parent across awaits; following a link here would weaken that no-link rule.
+  if (relative === '' || !isWithinDirectory(token.directory, resolved)) {
+    throw invalidateCacheToken(token, 'cache mutation escaped its prepared directory');
+  }
+  return resolved;
+}
+
+async function captureMutationParentSnapshots(token, targets) {
+  await verifyCacheToken(token);
+  const snapshots = new Map();
+  try {
+    for (const target of targets) {
+      const parent = path.dirname(resolveCacheTarget(token, target));
+      const relative = path.relative(token.directory, parent);
+      let current = token.directory;
+      for (const component of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, component);
+        if (snapshots.has(current)) continue;
+        const metadata = await fs.lstat(current, { bigint: true });
+        assertSafeDirectory(metadata);
+        snapshots.set(current, { directory: current, metadata });
+      }
+    }
+  } catch (error) {
+    throw invalidateCacheToken(token, 'cache mutation parent changed', error);
+  }
+  const captured = [...snapshots.values()];
+  await verifyMutationParentSnapshots(token, captured);
+  await verifyCacheToken(token);
+  return captured;
+}
+
+async function verifyMutationParentSnapshots(token, snapshots) {
+  try {
+    for (const snapshot of snapshots) {
+      const metadata = await fs.lstat(snapshot.directory, { bigint: true });
+      assertSafeDirectory(metadata);
+      if (!isSameFile(snapshot.metadata, metadata)) {
+        throw new Error('cache mutation parent changed');
+      }
+    }
+  } catch (error) {
+    const raced = new CacheOperationRaceError('cache mutation parent changed');
+    raced.cause = error;
+    throw raced;
+  }
+}
+
+async function verifyMutationContext(token, parentSnapshots) {
+  await verifyCacheToken(token);
+  await verifyMutationParentSnapshots(token, parentSnapshots);
+  await verifyCacheToken(token);
+}
+
+function assertSafeCacheEntry(metadata) {
+  if (metadata.isSymbolicLink() || (!metadata.isDirectory() && !metadata.isFile())) {
+    throw new Error('unsafe cache entry');
+  }
+}
+
+function assertSafeRegularFile(metadata) {
+  if (!metadata.isFile() || metadata.isSymbolicLink()) {
+    throw new Error('unsafe cache file');
+  }
+}
+
+function assertRenameableCacheEntry(metadata) {
+  if (!metadata.isDirectory() && !metadata.isFile() && !metadata.isSymbolicLink()) {
+    throw new Error('unsafe cache rename entry');
+  }
+}
+
+async function stableCacheEntry(
+  token,
+  target,
+  validate,
+  expectedMetadata = null,
+  missingIsOperationRace = false,
+) {
+  const resolved = resolveCacheTarget(token, target);
+  try {
+    const first = await fs.lstat(resolved, { bigint: true });
+    validate(first);
+    if (expectedMetadata && !isSameFile(expectedMetadata, first)) {
+      throw new Error('cache entry identity changed');
+    }
+    await verifyCacheToken(token);
+    const second = await fs.lstat(resolved, { bigint: true });
+    validate(second);
+    if (!isSameFile(first, second)
+      || (expectedMetadata && !isSameFile(expectedMetadata, second))) {
+      throw new Error('cache entry identity changed');
+    }
+    return second;
+  } catch (error) {
+    if (missingIsOperationRace && error?.code === 'ENOENT') {
+      await verifyCacheToken(token);
+      throw error;
+    }
+    throw invalidateCacheToken(token, 'cache mutation produced an untrusted object', error);
+  }
+}
+
+async function guardedCacheEntryRead(
+  token,
+  target,
+  validate,
+  read,
+  expectedMetadata = null,
+) {
+  const metadata = await stableCacheEntry(
+    token,
+    target,
+    validate,
+    expectedMetadata,
+    true,
+  );
+  let result;
+  try {
+    result = await read(metadata);
+  } catch (error) {
+    await stableCacheEntry(token, target, validate, metadata, true);
+    throw error;
+  }
+  await stableCacheEntry(token, target, validate, metadata, true);
+  return result;
+}
+
+async function stablePreparedDirectory(token, target) {
+  try {
+    const first = await fs.lstat(target, { bigint: true });
+    assertSafeDirectory(first);
+    await verifyCacheToken(token);
+    const second = await fs.lstat(target, { bigint: true });
+    assertSafeDirectory(second);
+    if (!isSameFile(first, second)) throw new Error('prepared directory identity changed');
+    return second;
+  } catch (error) {
+    throw invalidateCacheToken(token, 'prepared directory could not be verified', error);
+  }
+}
+
+async function assertCacheTargetAbsent(token, target) {
+  const resolved = resolveCacheTarget(token, target);
+  try {
+    await fs.lstat(resolved, { bigint: true });
+  } catch (error) {
+    if (error?.code === 'ENOENT') return;
+    throw invalidateCacheToken(token, 'cache mutation target could not be verified', error);
+  }
+  throw invalidateCacheToken(token, 'cache mutation left an unexpected object');
+}
+
+async function guardedCacheMutation(token, parentSnapshots, {
+  mutate,
+  verifyBefore = null,
+  verifyAfter,
+}) {
+  await verifyMutationContext(token, parentSnapshots);
+  if (verifyBefore) await verifyBefore();
+  let result;
+  try {
+    result = await mutate();
+  } catch (error) {
+    await verifyMutationContext(token, parentSnapshots);
+    throw error;
+  }
+  try {
+    await verifyMutationContext(token, parentSnapshots);
+    const verified = await verifyAfter(result);
+    await verifyMutationContext(token, parentSnapshots);
+    return verified ?? result;
+  } catch (error) {
+    if (error instanceof CacheOperationRaceError) throw error;
+    throw invalidateCacheToken(token, 'cache mutation could not be verified', error);
+  }
+}
+
+async function cacheMkdirWithToken(token, target, options, parentSnapshots = null) {
+  const resolved = path.resolve(target);
+  const parents = parentSnapshots ?? await captureMutationParentSnapshots(token, [resolved]);
+  return guardedCacheMutation(token, parents, {
+    mutate: () => fs.mkdir(resolved, options),
+    verifyAfter: () => (parentSnapshots === null
+      ? stableCacheEntry(token, resolved, assertSafeDirectory)
+      : stablePreparedDirectory(token, resolved)),
+  });
+}
+
+async function cacheMkdir(cacheDirectory, target, options) {
+  return cacheMkdirWithToken(cacheTokenFor(cacheDirectory), target, options);
+}
+
+async function cacheWriteFile(cacheDirectory, target, data, options) {
+  if (options?.flag !== 'wx') {
+    throw new Error('cache files must be created exclusively');
+  }
+  const token = cacheTokenFor(cacheDirectory);
+  const resolved = resolveCacheTarget(token, target);
+  const parents = await captureMutationParentSnapshots(token, [resolved]);
+  return guardedCacheMutation(token, parents, {
+    mutate: async () => {
+      const flags = fsConstants.O_WRONLY
+        | fsConstants.O_CREAT
+        | fsConstants.O_EXCL
+        | (fsConstants.O_NOFOLLOW ?? 0);
+      const handle = await fs.open(resolved, flags, options.mode);
+      try {
+        const openedMetadata = await handle.stat({ bigint: true });
+        if (!openedMetadata.isFile() || openedMetadata.isSymbolicLink()) {
+          throw new Error('cache write did not open a regular file');
+        }
+        await handle.writeFile(data, options.encoding ? { encoding: options.encoding } : undefined);
+        const writtenMetadata = await handle.stat({ bigint: true });
+        const expectedBytes = Buffer.isBuffer(data)
+          ? data.length
+          : Buffer.byteLength(data, options.encoding || 'utf8');
+        if (!isSameFile(openedMetadata, writtenMetadata)
+          || writtenMetadata.size !== BigInt(expectedBytes)) {
+          throw new Error('cache write did not preserve the opened file identity and size');
+        }
+        return writtenMetadata;
+      } finally {
+        await handle.close();
+      }
+    },
+    verifyAfter: (writtenMetadata) => stableCacheEntry(token, resolved, (metadata) => {
+      if (!metadata.isFile() || metadata.isSymbolicLink()) {
+        throw new Error('cache write did not create a regular file');
+      }
+    }, writtenMetadata),
+  });
+}
+
+async function cacheRename(
+  cacheDirectory,
+  source,
+  destination,
+  validate,
+  expectedSourceMetadata = null,
+) {
+  if (typeof validate !== 'function') {
+    throw new TypeError('cache rename requires an explicit entry validator');
+  }
+  const token = cacheTokenFor(cacheDirectory);
+  const resolvedSource = resolveCacheTarget(token, source);
+  const resolvedDestination = resolveCacheTarget(token, destination);
+  const parents = await captureMutationParentSnapshots(
+    token,
+    [resolvedSource, resolvedDestination],
+  );
+  const sourceMetadata = await stableCacheEntry(
+    token,
+    resolvedSource,
+    validate,
+    expectedSourceMetadata,
+    true,
+  );
+  return guardedCacheMutation(token, parents, {
+    verifyBefore: () => stableCacheEntry(
+      token,
+      resolvedSource,
+      validate,
+      sourceMetadata,
+      true,
+    ),
+    mutate: () => fs.rename(resolvedSource, resolvedDestination),
+    verifyAfter: async () => {
+      await assertCacheTargetAbsent(token, resolvedSource);
+      return stableCacheEntry(
+        token,
+        resolvedDestination,
+        validate,
+        sourceMetadata,
+      );
+    },
+  });
+}
+
+async function cacheRm(cacheDirectory, target, options) {
+  if (options?.recursive) {
+    throw new Error('recursive cache removal is not allowed');
+  }
+  const token = cacheTokenFor(cacheDirectory);
+  const resolved = resolveCacheTarget(token, target);
+  const parents = await captureMutationParentSnapshots(token, [resolved]);
+  let initialMetadata;
+  try {
+    initialMetadata = await fs.lstat(resolved, { bigint: true });
+  } catch (error) {
+    if (error?.code === 'ENOENT' && options?.force) {
+      await verifyMutationContext(token, parents);
+      return;
+    }
+    throw error;
+  }
+  try {
+    assertSafeCacheEntry(initialMetadata);
+  } catch (error) {
+    throw invalidateCacheToken(token, 'cache removal target is unsafe', error);
+  }
+  const targetMetadata = await stableCacheEntry(
+    token,
+    resolved,
+    assertSafeCacheEntry,
+    initialMetadata,
+  );
+  return guardedCacheMutation(token, parents, {
+    verifyBefore: () => stableCacheEntry(
+      token,
+      resolved,
+      assertSafeCacheEntry,
+      targetMetadata,
+    ),
+    mutate: () => fs.rm(resolved, options),
+    verifyAfter: () => assertCacheTargetAbsent(token, resolved),
+  });
+}
+
+async function prepareCacheDirectory(cacheDirectory) {
+  const absoluteTarget = path.resolve(cacheDirectory);
+  const target = await canonicalizeTrustedDirectoryPrefix(absoluteTarget);
+  const parsed = path.parse(target);
+  const components = target.slice(parsed.root.length).split(path.sep).filter(Boolean);
+  let current = parsed.root;
+  const token = {
+    directory: target,
+    ancestorSnapshots: [],
+    trusted: true,
+  };
+
+  for (const component of components) {
+    current = path.join(current, component);
+    let metadata;
+    try {
+      metadata = await fs.lstat(current, { bigint: true });
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      try {
+        await cacheMkdirWithToken(token, current, { mode: 0o700 }, []);
+      } catch (mkdirError) {
+        if (mkdirError?.code !== 'EEXIST') throw mkdirError;
+      }
+      metadata = await fs.lstat(current, { bigint: true });
+    }
+    assertSafeDirectory(metadata);
+    token.ancestorSnapshots.push({ directory: current, metadata });
+  }
+
+  await verifyCacheToken(token);
+  preparedCacheDirectories.set(target, token);
+  return target;
+}
+
+function operationName(kind, generation) {
+  return `${kind}-${generation.toString().padStart(20, '0')}`;
+}
+
+function parseOperationName(name) {
+  const match = OPERATION_NAME.exec(name);
+  if (!match) return null;
+  return { kind: match[1], generation: BigInt(match[2]) };
+}
+
+async function listOperations(cacheDirectory, token = cacheTokenFor(cacheDirectory)) {
+  return guardedCacheRead(token, async () => {
+    try {
+      const entries = await fs.readdir(cacheDirectory, { withFileTypes: true });
+      return entries.flatMap((entry) => {
+        const parsed = parseOperationName(entry.name);
+        if (!parsed) return [];
+        if (!entry.isDirectory() || entry.isSymbolicLink()) {
+          throw invalidateCacheToken(
+            token,
+            `cache operation ${entry.name} is not a safe directory`,
+          );
+        }
+        return [{ ...parsed, name: entry.name, directory: path.join(cacheDirectory, entry.name) }];
+      });
+    } catch (error) {
+      if (error?.code === 'ENOENT') return [];
+      throw error;
+    }
+  });
+}
+
+async function readState(cacheDirectory, installedVersion = null) {
+  const token = cacheTokenFor(cacheDirectory);
+  return guardedCacheRead(token, async () => {
+    const operations = (await listOperations(cacheDirectory, token))
+      .filter((operation) => operation.kind === 'committed')
+      .sort((left, right) => (left.generation > right.generation ? -1 : 1));
+    for (const operation of operations) {
+      try {
+        const state = await guardedCacheEntryRead(
+          token,
+          operation.directory,
+          assertSafeDirectory,
+          async () => normalizeState(
+            await readJsonFile(
+              path.join(operation.directory, OPERATION_STATE_FILE),
+              MAX_CACHE_STATE_BYTES,
+            ),
+            installedVersion,
+          ),
+        );
+        if (state) return state;
+      } catch (error) {
+        if (error instanceof FileIdentityChangedError
+          || error instanceof CachePathChangedError
+          || error instanceof CacheOperationRaceError) throw error;
+        // An incomplete or corrupt generation is ignored in favor of the previous commit.
+      }
+    }
+    return emptyState(installedVersion);
+  });
+}
+
+async function operationIsActive(
+  cacheDirectory,
+  operation,
+  token = cacheTokenFor(cacheDirectory),
+) {
+  try {
+    return await guardedCacheEntryRead(
+      token,
+      operation.directory,
+      assertSafeDirectory,
+      async (directoryMetadata) => {
+        try {
+          const ownerMetadata = await fs.lstat(
+            path.join(operation.directory, OPERATION_OWNER_FILE),
+            { bigint: true },
+          );
+          if (!ownerMetadata.isFile() || ownerMetadata.isSymbolicLink()) return false;
+          try {
+            const owner = await readJsonFile(
+              path.join(operation.directory, OPERATION_OWNER_FILE),
+              MAX_CLAIM_OWNER_BYTES,
+              ownerMetadata,
+            );
+            if (Number.isSafeInteger(owner?.pid) && owner.pid > 0 && processIsGone(owner.pid)) {
+              return false;
+            }
+          } catch (error) {
+            if (error instanceof FileIdentityChangedError) throw error;
+            // A malformed owner still gets the hard lease before recovery.
+          }
+          return metadataIsWithinLease(ownerMetadata);
+        } catch (error) {
+          if (error?.code !== 'ENOENT') throw error;
+          return metadataIsWithinLease(directoryMetadata);
+        }
+      },
+    );
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+function processIsGone(pid) {
+  try {
+    process.kill(pid, 0);
+    return false;
+  } catch (error) {
+    return error?.code === 'ESRCH';
+  }
+}
+
+function validateClaimOwner(value) {
+  if (!isPlainObject(value)
+    || !hasOnlyKeys(value, new Set(['pid', 'token', 'generation']))
+    || !Number.isSafeInteger(value.pid)
+    || value.pid <= 0
+    || typeof value.token !== 'string'
+    || !/^[a-f0-9]{32}$/.test(value.token)
+    || typeof value.generation !== 'string'
+    || !/^[1-9]\d*$/.test(value.generation)) return null;
+  return { ...value, generation: BigInt(value.generation) };
+}
+
+function metadataIsWithinLease(metadata) {
+  if (typeof metadata.mtimeNs === 'bigint') {
+    const ageNs = (BigInt(Date.now()) * 1_000_000n) - metadata.mtimeNs;
+    const absoluteAgeNs = ageNs < 0n ? -ageNs : ageNs;
+    return absoluteAgeNs <= BigInt(LOCK_STALE_MS) * 1_000_000n;
+  }
+  return Math.abs(Date.now() - metadata.mtimeMs) <= LOCK_STALE_MS;
+}
+
+function corruptClaimStatus(directory, directoryMetadata, ownerMetadata = directoryMetadata) {
+  if (metadataIsWithinLease(ownerMetadata)) {
+    return { state: 'busy', directory, metadata: directoryMetadata, owner: null };
+  }
+  const fingerprint = crypto.createHash('sha256')
+    .update(JSON.stringify({
+      directory: {
+        dev: directoryMetadata.dev.toString(),
+        ino: directoryMetadata.ino.toString(),
+        mode: directoryMetadata.mode.toString(),
+        birthtimeNs: directoryMetadata.birthtimeNs.toString(),
+      },
+    }))
+    .digest('hex')
+    .slice(0, 24);
+  return {
+    state: 'releasable',
+    directory,
+    metadata: directoryMetadata,
+    key: `corrupt-${fingerprint}`,
+    owner: null,
+  };
+}
+
+async function inspectActiveClaim(cacheDirectory) {
+  const token = cacheTokenFor(cacheDirectory);
+  return guardedCacheRead(token, async () => {
+    const directory = path.join(cacheDirectory, ACTIVE_CLAIM_DIRECTORY);
+    let directoryMetadata;
+    try {
+      directoryMetadata = await fs.lstat(directory, { bigint: true });
+    } catch (error) {
+      if (error?.code === 'ENOENT') return { state: 'absent', directory };
+      throw error;
+    }
+    if (!directoryMetadata.isDirectory() || directoryMetadata.isSymbolicLink()) {
+      return corruptClaimStatus(directory, directoryMetadata);
+    }
+    return guardedCacheEntryRead(
+      token,
+      directory,
+      assertSafeDirectory,
+      async (stableDirectoryMetadata) => {
+        const ownerPath = path.join(directory, OPERATION_OWNER_FILE);
+        let ownerMetadata = stableDirectoryMetadata;
+        let owner = null;
+        try {
+          ownerMetadata = await fs.lstat(ownerPath, { bigint: true });
+          if (!ownerMetadata.isFile()
+            || ownerMetadata.isSymbolicLink()
+            || ownerMetadata.size > BigInt(MAX_CLAIM_OWNER_BYTES)) {
+            return corruptClaimStatus(directory, stableDirectoryMetadata, ownerMetadata);
+          }
+          const ownerSource = await readJsonFile(
+            ownerPath,
+            MAX_CLAIM_OWNER_BYTES,
+            ownerMetadata,
+          );
+          owner = validateClaimOwner(ownerSource);
+        } catch (error) {
+          if (error instanceof FileIdentityChangedError) throw error;
+          // A malformed claim is recoverable only after the same hard lease as a crashed owner.
+        }
+
+        if (owner) {
+          const operations = await listOperations(cacheDirectory, token);
+          if (operations.some((operation) => operation.generation === owner.generation
+            && ['committed', 'fenced', 'cancelled'].includes(operation.kind))) {
+            return {
+              state: 'releasable',
+              directory,
+              metadata: stableDirectoryMetadata,
+              key: owner.generation.toString(),
+              owner,
+            };
+          }
+          const pending = operations.find((operation) => operation.kind === 'pending'
+            && operation.generation === owner.generation);
+          if (pending) {
+            if (await operationIsActive(cacheDirectory, pending, token)) {
+              return {
+                state: 'busy',
+                directory,
+                metadata: stableDirectoryMetadata,
+                owner,
+              };
+            }
+            return {
+              state: 'releasable',
+              directory,
+              metadata: stableDirectoryMetadata,
+              key: owner.generation.toString(),
+              owner,
+            };
+          }
+        }
+
+        return corruptClaimStatus(directory, stableDirectoryMetadata, ownerMetadata);
+      },
+      directoryMetadata,
+    );
+  });
+}
+
+async function retireActiveClaim(cacheDirectory, claim) {
+  const retirement = path.join(cacheDirectory, `retired-claim-${claim.key}`);
+  await cacheMkdir(cacheDirectory, retirement, { mode: 0o700 }).catch((error) => {
+    if (error?.code !== 'EEXIST') throw error;
+  });
+  try {
+    const retirementMetadata = await fs.lstat(retirement);
+    if (!retirementMetadata.isDirectory() || retirementMetadata.isSymbolicLink()) return false;
+  } catch (error) {
+    if (error instanceof CacheOperationRaceError) return false;
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+  try {
+    const metadata = await fs.lstat(claim.directory);
+    if (metadata.isDirectory() && !metadata.isSymbolicLink()) {
+      await cacheWriteFile(
+        cacheDirectory,
+        path.join(claim.directory, '.retirement-guard'),
+        `${claim.key}\n`,
+        { encoding: 'utf8', flag: 'wx', mode: 0o600 },
+      ).catch((error) => {
+        if (error?.code !== 'EEXIST') throw error;
+      });
+    }
+  } catch (error) {
+    if (error instanceof CacheOperationRaceError) return false;
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+  try {
+    await cacheRename(
+      cacheDirectory,
+      claim.directory,
+      path.join(retirement, 'active'),
+      assertRenameableCacheEntry,
+      claim.metadata,
+    );
+    return true;
+  } catch (error) {
+    if (error instanceof CacheOperationRaceError) return false;
+    if (['ENOENT', 'EEXIST', 'ENOTEMPTY', 'EPERM'].includes(error?.code)) return false;
+    throw error;
+  }
+}
+
+async function prepareOperationClaim(cacheDirectory, operation) {
+  const directory = path.join(cacheDirectory, operationName('claim', operation.generation));
+  await cacheMkdir(cacheDirectory, directory, { mode: 0o700 });
+  await cacheWriteFile(
+    cacheDirectory,
+    path.join(directory, OPERATION_OWNER_FILE),
+    `${JSON.stringify({
+      pid: process.pid,
+      token: operation.token,
+      generation: operation.generation.toString(),
+    })}\n`,
+    { encoding: 'utf8', flag: 'wx', mode: 0o600 },
+  );
+  operation.preparedClaimDirectory = directory;
+}
+
+async function discardPreparedClaim(cacheDirectory, operation) {
+  if (!operation.preparedClaimDirectory) return;
+  const discarded = path.join(
+    cacheDirectory,
+    `discarded-claim-${operation.generation.toString().padStart(20, '0')}-${operation.token}`,
+  );
+  try {
+    await cacheRename(
+      cacheDirectory,
+      operation.preparedClaimDirectory,
+      discarded,
+      assertSafeDirectory,
+    );
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  delete operation.preparedClaimDirectory;
+}
+
+async function promoteOperationClaim(cacheDirectory, operation) {
+  await prepareOperationClaim(cacheDirectory, operation);
+  const activeDirectory = path.join(cacheDirectory, ACTIVE_CLAIM_DIRECTORY);
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    if (await operationIsSuperseded(cacheDirectory, operation)) {
+      await discardPreparedClaim(cacheDirectory, operation);
+      return false;
+    }
+    const active = await inspectActiveClaim(cacheDirectory);
+    if (active.state === 'busy') {
+      await discardPreparedClaim(cacheDirectory, operation);
+      return false;
+    }
+    if (active.state === 'releasable') {
+      if (active.owner?.generation > operation.generation) {
+        await discardPreparedClaim(cacheDirectory, operation);
+        return false;
+      }
+      await retireActiveClaim(cacheDirectory, active);
+      continue;
+    }
+    try {
+      await cacheRename(
+        cacheDirectory,
+        operation.preparedClaimDirectory,
+        activeDirectory,
+        assertSafeDirectory,
+      );
+      delete operation.preparedClaimDirectory;
+      if (!await operationIsActive(cacheDirectory, operation)) return false;
+      return true;
+    } catch (promotionError) {
+      const raced = await inspectActiveClaim(cacheDirectory);
+      if (raced.state === 'absent') {
+        if (['EEXIST', 'ENOTEMPTY', 'EPERM'].includes(promotionError?.code)) continue;
+        await discardPreparedClaim(cacheDirectory, operation);
+        throw promotionError;
+      }
+      continue;
+    }
+  }
+  await discardPreparedClaim(cacheDirectory, operation);
+  return false;
+}
+
+async function operationOwnsActiveClaim(cacheDirectory, operation) {
+  const active = await inspectActiveClaim(cacheDirectory);
+  return active.state === 'busy'
+    && active.owner?.generation === operation.generation
+    && active.owner.token === operation.token;
+}
+
+async function hasActivePendingOperation(cacheDirectory) {
+  const token = cacheTokenFor(cacheDirectory);
+  return guardedCacheRead(token, async () => {
+    const pending = (await listOperations(cacheDirectory, token))
+      .filter((operation) => operation.kind === 'pending');
+    return (await Promise.all(pending.map(
+      (operation) => operationIsActive(cacheDirectory, operation, token),
+    ))).some(Boolean);
+  });
+}
+
+async function reserveOperation(cacheDirectory) {
+  cacheDirectory = await prepareCacheDirectory(cacheDirectory);
+  const operations = await listOperations(cacheDirectory);
+  const occupied = new Set(operations.map((operation) => operation.generation.toString()));
+  let generation = 1n;
+  while (true) {
+    while (occupied.has(generation.toString())) generation += 1n;
+    if (generation > MAX_OPERATION_GENERATION) throw new Error('operation generation space exhausted');
+    const reservation = path.join(cacheDirectory, operationName('reserved', generation));
+    try {
+      await cacheMkdir(cacheDirectory, reservation, { mode: 0o700 });
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      occupied.add(generation.toString());
+      generation += 1n;
+      continue;
+    }
+    const directory = path.join(cacheDirectory, operationName('pending', generation));
+    try {
+      await cacheMkdir(cacheDirectory, directory, { mode: 0o700 });
+      const operation = {
+        generation,
+        token: crypto.randomBytes(16).toString('hex'),
+        directory,
+      };
+      try {
+        await cacheWriteFile(
+          cacheDirectory,
+          path.join(directory, OPERATION_OWNER_FILE),
+          `${JSON.stringify({ pid: process.pid, token: operation.token })}\n`,
+          { encoding: 'utf8', flag: 'wx', mode: 0o600 },
+        );
+      } catch (error) {
+        if (await operationWasFenced(cacheDirectory, operation)) {
+          const fencedError = new OperationFencedError('operation was fenced while reserving');
+          fencedError.cause = error;
+          throw fencedError;
+        }
+        await cacheRename(
+          cacheDirectory,
+          directory,
+          path.join(cacheDirectory, operationName('cancelled', generation)),
+          assertSafeDirectory,
+        ).catch(() => {});
+        throw error;
+      }
+      return operation;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      occupied.add(generation.toString());
+      generation += 1n;
+    }
+  }
+}
+
+async function operationIsSuperseded(cacheDirectory, operation) {
+  return (await listOperations(cacheDirectory))
+    .some((candidate) => candidate.generation > operation.generation);
+}
+
+async function operationWasFenced(cacheDirectory, operation) {
+  const token = cacheTokenFor(cacheDirectory);
+  return guardedCacheRead(token, async () => {
+    try {
+      await fs.lstat(operation.directory, { bigint: true });
+      return false;
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+    const fencedDirectory = path.join(
+      cacheDirectory,
+      operationName('fenced', operation.generation),
+    );
+    try {
+      await stableCacheEntry(
+        token,
+        fencedDirectory,
+        assertSafeDirectory,
+        null,
+        true,
+      );
+      return true;
+    } catch (error) {
+      if (error?.code === 'ENOENT') return false;
+      throw error;
+    }
+  });
+}
+
+async function transitionOperation(cacheDirectory, operation, kind) {
+  const destination = path.join(cacheDirectory, operationName(kind, operation.generation));
+  await cacheRename(cacheDirectory, operation.directory, destination, assertSafeDirectory);
+}
+
+async function cancelOperation(cacheDirectory, operation) {
+  try {
+    await transitionOperation(cacheDirectory, operation, 'cancelled');
+  } catch (error) {
+    // A higher generation may already have fenced this unique pending directory.
+    if (error?.code !== 'ENOENT') throw error;
+  }
+}
+
+async function acquireOperation(cacheDirectory) {
+  cacheDirectory = await prepareCacheDirectory(cacheDirectory);
+  if ((await inspectActiveClaim(cacheDirectory)).state === 'busy') return null;
+  if (await hasActivePendingOperation(cacheDirectory)) return null;
+  let operation;
+  try {
+    operation = await reserveOperation(cacheDirectory);
+  } catch (error) {
+    if (error instanceof OperationFencedError) return null;
+    throw error;
+  }
+  if (!await operationIsSuperseded(cacheDirectory, operation)
+    && await promoteOperationClaim(cacheDirectory, operation)) return operation;
+  await cancelOperation(cacheDirectory, operation);
+  return null;
+}
+
+async function fenceLowerOperations(cacheDirectory, operation) {
+  const lower = (await listOperations(cacheDirectory))
+    .filter((candidate) => candidate.kind === 'pending'
+      && candidate.generation < operation.generation)
+    .sort((left, right) => (left.generation < right.generation ? -1 : 1));
+  for (const candidate of lower) {
+    try {
+      await cacheRename(
+        cacheDirectory,
+        candidate.directory,
+        path.join(cacheDirectory, operationName('fenced', candidate.generation)),
+        assertSafeDirectory,
+      );
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+}
+
+async function commitOperation(cacheDirectory, operation, installedVersion, mutate) {
+  if (!await operationOwnsActiveClaim(cacheDirectory, operation)) {
+    await cancelOperation(cacheDirectory, operation);
+    return { fenced: true, result: silent('check-in-progress') };
+  }
+  await fenceLowerOperations(cacheDirectory, operation);
+  if (!await operationOwnsActiveClaim(cacheDirectory, operation)) {
+    await cancelOperation(cacheDirectory, operation);
+    return { fenced: true, result: silent('check-in-progress') };
+  }
+  const state = await readState(cacheDirectory, installedVersion);
+  const decision = mutate(state);
+  if (!decision.state) {
+    await cancelOperation(cacheDirectory, operation);
+    return { fenced: false, result: decision.result };
+  }
+  let committedState = decision.state;
+  let committedResult = decision.result;
+  let encodedState = encodeRecoverableState(committedState);
+  if (!encodedState && decision.capacityFallback) {
+    committedState = decision.capacityFallback.state;
+    committedResult = decision.capacityFallback.result;
+    encodedState = encodeRecoverableState(committedState);
+  }
+  if (!encodedState) {
+    await cancelOperation(cacheDirectory, operation);
+    return { fenced: false, result: silent('cache-unavailable') };
+  }
+  const temporary = path.join(
+    operation.directory,
+    `.state.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`,
+  );
+  try {
+    await cacheWriteFile(cacheDirectory, temporary, encodedState, {
+      flag: 'wx',
+      mode: 0o600,
+    });
+    await cacheRename(
+      cacheDirectory,
+      temporary,
+      path.join(operation.directory, OPERATION_STATE_FILE),
+      assertSafeRegularFile,
+    );
+    await transitionOperation(cacheDirectory, operation, 'committed');
+    return { fenced: false, result: committedResult };
+  } catch (error) {
+    if (await operationWasFenced(cacheDirectory, operation)) {
+      return { fenced: true, result: silent('check-in-progress') };
+    }
+    await cacheRm(cacheDirectory, temporary, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+function nextSuccessfulCheck(nowMs, random) {
+  const boundedRandom = Math.min(1, Math.max(0, Number(random()) || 0));
+  const multiplier = 0.8 + (boundedRandom * 0.4);
+  return new Date(nowMs + Math.round(CHECK_TTL_MS * multiplier)).toISOString();
+}
+
+function nextFailedCheck(nowMs, failures) {
+  const delay = failures <= 1 ? FIRST_FAILURE_DELAY_MS : LATER_FAILURE_DELAY_MS;
+  return new Date(nowMs + delay).toISOString();
+}
+
+function stateAfterFailedCheck(state, nowMs, withdrawCandidate = false) {
+  const failures = Math.min(state.check.consecutiveFailures + 1, 2);
+  return stateWithFailureCheck(
+    state,
+    nextFailedCheck(nowMs, failures),
+    failures,
+    withdrawCandidate,
+  );
+}
+
+function eventKeyForDigest(targetDigest) {
+  return `${SKILL_ID}@${targetDigest}`;
+}
+
+function digestForEventKey(eventKey) {
+  const prefix = `${SKILL_ID}@`;
+  if (typeof eventKey !== 'string' || !eventKey.startsWith(prefix)) return null;
+  const digest = eventKey.slice(prefix.length);
+  return DIGEST_PATTERN.test(digest) ? digest : null;
+}
+
+function notification(localRelease, candidate, source) {
+  return {
+    status: 'update_available',
+    eventKey: eventKeyForDigest(candidate.targetDigest),
+    installedVersion: localRelease.version,
+    latestVersion: candidate.version,
+    targetDigest: candidate.targetDigest,
+    severity: candidate.severity,
+    summary: candidate.summary ?? null,
+    releaseNotes: candidate.releaseNotes,
+    source,
+    checkedAt: candidate.checkedAt,
+    noticeRequired: true,
+  };
+}
+
+function resultForCandidate(localRelease, state, { source = 'cache', nowMs = Date.now() } = {}) {
+  const { candidate } = state;
+  if (!candidate) return silent('cache-valid');
+  if (compareSemver(candidate.version, localRelease.version) <= 0) {
+    return {
+      status: 'current', installedVersion: localRelease.version,
+      availableVersion: candidate.version, checkedAt: candidate.checkedAt,
+      source, noticeRequired: false,
+    };
+  }
+  const result = notification(localRelease, candidate, source);
+  const preference = state.preferences?.find((entry) => entry.targetDigest === candidate.targetDigest
+    && entry.version === candidate.version);
+  if (preference?.mode === 'ignore') return { ...result, noticeRequired: false, reason: 'ignored' };
+  if (preference?.mode === 'snooze' && Date.parse(preference.until) > nowMs) {
+    return { ...result, noticeRequired: false, reason: 'snoozed', suppressedUntil: preference.until };
+  }
+  return result;
+}
+
+async function readBoundedBody(response) {
+  const contentLength = Number(response.headers.get('content-length'));
+  if (Number.isFinite(contentLength) && contentLength > MAX_RESPONSE_BYTES) {
+    await cancelResponseBody(response);
+    throw new UpdateContractError('manifest response is too large');
+  }
+  if (!response.body || typeof response.body.getReader !== 'function') {
+    throw new UpdateContractError('manifest response has no bounded stream');
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > MAX_RESPONSE_BYTES) {
+        await reader.cancel().catch(() => {});
+        throw new UpdateContractError('manifest response is too large');
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const joined = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    joined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(joined);
+  } catch {
+    throw new UpdateContractError('manifest is not valid UTF-8');
+  }
+}
+
+async function cancelResponseBody(response) {
+  try {
+    if (response.body && typeof response.body.cancel === 'function') {
+      await response.body.cancel();
+    }
+  } catch {
+    // Network cleanup is best-effort; the original response classification wins.
+  }
+}
+
+async function fetchCandidate({ fetchImpl, manifestUrl, timeoutMs }) {
+  if (manifestUrl !== DEFAULT_MANIFEST_URL) throw new UpdateContractError('unexpected manifest URL');
+  const controller = new AbortController();
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new Error('update check timed out'));
+    }, timeoutMs);
+  });
+  const request = (async () => {
+    const headers = { accept: 'application/json' };
+    const response = await fetchImpl(manifestUrl, {
+      method: 'GET',
+      headers,
+      redirect: 'error',
+      signal: controller.signal,
+    });
+    if (response.status !== 200) {
+      await cancelResponseBody(response);
+      if (response.status === 404 || response.status === 410) {
+        throw new ManifestWithdrawnError('manifest was withdrawn');
+      }
+      throw new Error(`manifest returned HTTP ${response.status}`);
+    }
+    const mediaType = response.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase();
+    if (mediaType !== 'application/json') {
+      await cancelResponseBody(response);
+      throw new UpdateContractError('manifest is not JSON');
+    }
+    const source = await readBoundedBody(response);
+    let decoded;
+    try {
+      decoded = JSON.parse(source);
+    } catch {
+      throw new UpdateContractError('manifest is not valid bounded JSON');
+    }
+    return { candidate: validateManifest(decoded) };
+  })();
+  try {
+    return await Promise.race([request, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function defaultCacheDirectory() {
+  const homeDirectory = os.homedir();
+  if (process.platform === 'win32') {
+    const localData = process.env.LOCALAPPDATA;
+    return path.join(localData && path.isAbsolute(localData) ? localData : path.join(homeDirectory, 'AppData', 'Local'), 'archify-skill');
+  }
+  if (process.platform === 'darwin') return path.join(homeDirectory, 'Library', 'Caches', 'archify-skill');
+  const xdgCache = process.env.XDG_CACHE_HOME;
+  return path.join(xdgCache && path.isAbsolute(xdgCache) ? xdgCache : path.join(homeDirectory, '.cache'), 'archify-skill');
+}
+
+function freshStateResult(localRelease, state, nowMs) {
+  const nextCheckAt = Date.parse(state.check.nextCheckAt || '');
+  if (Number.isFinite(nextCheckAt) && nextCheckAt > nowMs
+    && nextCheckAt <= nowMs + MAX_CACHE_HORIZON_MS) {
+    return resultForCandidate(localRelease, state, { nowMs });
+  }
+  return null;
+}
+
+async function resultAfterLosingOperation(cacheDirectory, operation, localRelease, nowMs) {
+  await cancelOperation(cacheDirectory, operation);
+  const cached = await readState(cacheDirectory, localRelease.version);
+  return cached.candidate ? resultForCandidate(localRelease, cached, { nowMs }) : silent('check-in-progress');
+}
+
+async function waitUntilRetry(deadline, monotonicNow) {
+  let remaining;
+  try {
+    remaining = deadline - Number(monotonicNow());
+  } catch {
+    return false;
+  }
+  if (!Number.isFinite(remaining) || remaining <= 0) return false;
+  await new Promise((resolve) => setTimeout(
+    resolve,
+    Math.min(LOCK_RETRY_DELAY_MS, remaining),
+  ));
+  return true;
+}
+
+export async function checkForUpdate({
+  releasePath = defaultReleasePath,
+  cacheDirectory = defaultCacheDirectory(),
+  fetchImpl = globalThis.fetch,
+  now = Date.now,
+  random = Math.random,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  fetchDeadlineNs,
+} = {}) {
+  if (updatesDisabled()) return silent('disabled');
+  if (typeof fetchImpl !== 'function') return silent('runtime-unavailable');
+  let localRelease;
+  try {
+    localRelease = validateLocalRelease(await readJsonFile(releasePath, MAX_LOCAL_RELEASE_BYTES));
+  } catch {
+    return silent('invalid-local-release');
+  }
+
+  const nowMs = Number(now());
+  if (!Number.isFinite(nowMs)) return silent('invalid-clock');
+  let stateDirectory = versionCacheDirectory(cacheDirectory, localRelease.version);
+  let state;
+  try {
+    stateDirectory = await prepareCacheDirectory(stateDirectory);
+    state = await readState(stateDirectory, localRelease.version);
+  } catch {
+    return silent('cache-unavailable');
+  }
+  const cachedResult = freshStateResult(localRelease, state, nowMs);
+  if (cachedResult) return cachedResult;
+
+  let operation;
+  try {
+    operation = await acquireOperation(stateDirectory);
+  } catch {
+    return silent('cache-unavailable');
+  }
+  if (!operation) {
+    try {
+      const cached = await readState(stateDirectory, localRelease.version);
+      return cached.candidate ? resultForCandidate(localRelease, cached, { nowMs }) : silent('check-in-progress');
+    } catch {
+      return silent('cache-unavailable');
+    }
+  }
+
+  try {
+    state = await readState(stateDirectory, localRelease.version);
+    const racedResult = freshStateResult(localRelease, state, nowMs);
+    if (racedResult) {
+      await cancelOperation(stateDirectory, operation);
+      return racedResult;
+    }
+
+    if (!await operationOwnsActiveClaim(stateDirectory, operation)) {
+      return await resultAfterLosingOperation(stateDirectory, operation, localRelease, nowMs);
+    }
+
+    await verifyCacheToken(cacheTokenFor(stateDirectory));
+    if (!await operationOwnsActiveClaim(stateDirectory, operation)) {
+      return await resultAfterLosingOperation(stateDirectory, operation, localRelease, nowMs);
+    }
+    let fetched;
+    try {
+      const remainingFetchMs = fetchDeadlineNs === undefined ? timeoutMs
+        : Math.min(timeoutMs, Number(fetchDeadlineNs - process.hrtime.bigint()) / 1_000_000);
+      if (remainingFetchMs <= 0) throw new Error('update fetch deadline expired during cache preparation');
+      fetched = await fetchCandidate({
+        fetchImpl,
+        manifestUrl: localRelease.updateManifestUrl,
+        timeoutMs: remainingFetchMs,
+      });
+    } catch (error) {
+      const withdrawn = error instanceof ManifestWithdrawnError;
+      const reason = withdrawn ? 'withdrawn'
+        : error instanceof UpdateContractError ? 'invalid-manifest' : 'check-failed';
+      // Offline or invalid checks keep repeating the last validated candidate.
+      const failedResult = (known) => (!withdrawn && known.candidate
+        ? resultForCandidate(localRelease, known, { nowMs }) : silent(reason));
+      try {
+        const committed = await commitOperation(
+          stateDirectory,
+          operation,
+          localRelease.version,
+          (current) => ({
+            state: stateAfterFailedCheck(current, nowMs, withdrawn),
+            result: failedResult(current),
+          }),
+        );
+        if (committed.fenced) {
+          return await resultAfterLosingOperation(stateDirectory, operation, localRelease, nowMs);
+        }
+        return committed.result;
+      } catch {
+        await cancelOperation(stateDirectory, operation).catch(() => {});
+        return failedResult(state);
+      }
+    }
+
+    const candidate = { ...fetched.candidate, checkedAt: new Date(nowMs).toISOString() };
+    try {
+      const committed = await commitOperation(
+        stateDirectory,
+        operation,
+        localRelease.version,
+        (current) => {
+          const next = {
+            ...current,
+            candidate,
+            check: {
+              nextCheckAt: nextSuccessfulCheck(nowMs, random),
+              consecutiveFailures: 0,
+            },
+          };
+          const result = resultForCandidate(localRelease, next, { source: 'network', nowMs });
+          return {
+            state: next,
+            result,
+            capacityFallback: { state: stateAfterFailedCheck(current, nowMs, true), result },
+          };
+        },
+      );
+      if (committed.fenced) {
+        return await resultAfterLosingOperation(stateDirectory, operation, localRelease, nowMs);
+      }
+      return committed.result;
+    } catch {
+      await cancelOperation(stateDirectory, operation).catch(() => {});
+      return resultForCandidate(localRelease, { ...state, candidate }, { source: 'network', nowMs });
+    }
+  } catch {
+    await cancelOperation(stateDirectory, operation).catch(() => {});
+    return silent('cache-unavailable');
+  }
+}
+
+export async function setUpdatePreference({
+  releasePath = defaultReleasePath,
+  cacheDirectory = defaultCacheDirectory(),
+  eventKey,
+  mode,
+  days = 7,
+  now = Date.now,
+  monotonicNow = () => performance.now(),
+} = {}) {
+  const targetDigest = digestForEventKey(eventKey);
+  if (!targetDigest || !['snooze', 'ignore'].includes(mode)
+    || (mode === 'snooze' && (!Number.isInteger(days) || days < 1 || days > 365))) {
+    return silent('invalid-preference');
+  }
+  let localRelease;
+  try {
+    localRelease = validateLocalRelease(await readJsonFile(releasePath, MAX_LOCAL_RELEASE_BYTES));
+  } catch {
+    return silent('invalid-local-release');
+  }
+  let stateDirectory = versionCacheDirectory(cacheDirectory, localRelease.version);
+  try {
+    stateDirectory = await prepareCacheDirectory(stateDirectory);
+  } catch {
+    return silent('cache-unavailable');
+  }
+  const nowMs = Number(now());
+  if (!Number.isFinite(nowMs)) return silent('invalid-clock');
+  const deadline = Number(monotonicNow()) + PREFERENCE_LOCK_WAIT_MS;
+  while (Number(monotonicNow()) < deadline) {
+    let operation;
+    try {
+      operation = await acquireOperation(stateDirectory);
+    } catch {
+      return silent('cache-unavailable');
+    }
+    if (!operation) {
+      if (!await waitUntilRetry(deadline, monotonicNow)) break;
+      continue;
+    }
+    try {
+      const committed = await commitOperation(
+        stateDirectory, operation, localRelease.version, (state) => {
+          if (!state.candidate || state.candidate.targetDigest !== targetDigest
+            || compareSemver(state.candidate.version, localRelease.version) <= 0) {
+            return { state: null, result: silent('invalid-preference') };
+          }
+          const preference = {
+            targetDigest,
+            version: state.candidate.version,
+            mode,
+            until: mode === 'snooze' ? new Date(nowMs + days * 24 * 60 * 60 * 1_000).toISOString() : null,
+          };
+          const preferences = (state.preferences || [])
+            .filter((entry) => entry.targetDigest !== targetDigest)
+            .slice(-30);
+          preferences.push(preference);
+          return {
+            state: { ...state, preferences },
+            result: { status: mode === 'snooze' ? 'snoozed' : 'ignored', eventKey,
+              ...(preference.until ? { suppressedUntil: preference.until } : {}) },
+          };
+        },
+      );
+      if (!committed.fenced) return committed.result;
+    } catch {
+      await cancelOperation(stateDirectory, operation).catch(() => {});
+      return silent('cache-unavailable');
+    }
+  }
+  return silent('check-in-progress');
+}
+
+async function runCli() {
+  if (updatesDisabled()) return silent('disabled');
+  const argumentsList = process.argv.slice(2);
+  if (argumentsList.length === 0) return checkForUpdate();
+  if (argumentsList.length === 2 && argumentsList[0] === '--ack') {
+    return silent('legacy-ack-no-op');
+  }
+  if (argumentsList.length === 2 && argumentsList[0] === '--snooze') {
+    return setUpdatePreference({ eventKey: argumentsList[1], mode: 'snooze' });
+  }
+  if (argumentsList.length === 2 && argumentsList[0] === '--ignore') {
+    return setUpdatePreference({ eventKey: argumentsList[1], mode: 'ignore' });
+  }
+  return silent('invalid-arguments');
+}
+
+export function isMainModule({
+  argvPath = process.argv[1],
+  modulePath = fileURLToPath(import.meta.url),
+} = {}) {
+  if (!argvPath) return false;
+  try {
+    return sameEntry(argvPath, modulePath).status === 'match';
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  let result;
+  try {
+    result = await runCli();
+  } catch {
+    result = silent('check-failed');
+  }
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}