@ikon85/agent-workflow-kit 0.34.3 → 0.34.5

package/scripts/test_skill_readiness_contract.py

@@ -56,7 +56,12 @@ for (const skill of Object.keys(fixture.readinessFixture.skills)) {
 const kit = await makeKit({ '.claude/skills/to-prd/SKILL.md': 'fixture\n' });
 const consumer = await makeEmptyDir();
 async function setKitReadiness(manifest) {
-  const content = `${JSON.stringify(manifest, null, 2)}\n`;
+  const candidateManifest = structuredClone(manifest);
+  for (const [name, declaration] of Object.entries(candidateManifest.skills)) {
+    declaration.publish = name === 'to-prd';
+    if (name === 'to-prd') declaration.surfaces = ['claude'];
+  }
+  const content = `${JSON.stringify(candidateManifest, null, 2)}\n`;
   const path = join(kit, readinessPath);
   await mkdir(join(kit, '.claude/skills'), { recursive: true });
   await writeFile(path, content);

package/scripts/test_skill_setup_workflow_seeds.py

@@ -49,13 +49,12 @@ def classify(first_line, is_empty):
 
 
 def update_workflow_action(
-    provider, choice, destination_exists, prerequisites=True,
-    pull_requests_allowed=True,
+    provider, choice, destination_exists, pull_requests_allowed=True,
 ):
     """Reference decision table for the prompt-driven setup contract."""
     if provider != "github" or destination_exists or choice != "enable":
         return "skip"
-    return "create" if prerequisites and pull_requests_allowed else "skip"
+    return "create" if pull_requests_allowed else "skip"
 
 
 def load_census_setup_effects():
@@ -421,19 +420,18 @@ class SeedTemplatesValid(unittest.TestCase):
 
     def test_update_workflow_provider_and_choice_fixtures(self):
         fixtures = [
-            ("github", "enable", False, True, True, "create"),
-            ("github", "opt-out", False, True, True, "skip"),
-            ("github", "later", False, True, True, "skip"),
-            ("github", "enable", True, True, True, "skip"),
-            ("github", "enable", False, False, True, "skip"),
-            ("github", "enable", False, True, False, "skip"),
-            ("gitlab", "enable", False, True, True, "skip"),
-            ("local", "enable", False, True, True, "skip"),
+            ("github", "enable", False, True, "create"),
+            ("github", "opt-out", False, True, "skip"),
+            ("github", "later", False, True, "skip"),
+            ("github", "enable", True, True, "skip"),
+            ("github", "enable", False, False, "skip"),
+            ("gitlab", "enable", False, True, "skip"),
+            ("local", "enable", False, True, "skip"),
         ]
-        for provider, choice, exists, prerequisites, allowed, expected in fixtures:
+        for provider, choice, exists, allowed, expected in fixtures:
             self.assertEqual(
                 update_workflow_action(
-                    provider, choice, exists, prerequisites, allowed,
+                    provider, choice, exists, allowed,
                 ), expected,
             )
 
@@ -446,8 +444,8 @@ class SeedTemplatesValid(unittest.TestCase):
             "Ask later",
             "GitHub tracker",
             "skipped (already present)",
-            "package-lock.json",
-            "npm test",
+            "built-in Kit invariant validator",
+            "no Consumer package script",
             "can_approve_pull_request_reviews",
             "Allow GitHub Actions to create and approve pull requests",
             "explicit confirmation",
@@ -461,10 +459,13 @@ class SeedTemplatesValid(unittest.TestCase):
             "schedule:", "workflow_dispatch:", "contents: write",
             "pull-requests: write", "agent-workflow-kit-update-pr",
             "@ikon85/agent-workflow-kit@latest", "fetch-depth: 0",
-            "node-version: 22.14", "npm ci --ignore-scripts",
+            "node-version: 22.14", "Verify and upsert the Kit update pull request",
         ):
             self.assertIn(token, workflow)
-        for forbidden in ("npm_token", "NPM_TOKEN", "auto-merge", "gh pr merge"):
+        for forbidden in (
+            "npm_token", "NPM_TOKEN", "auto-merge", "gh pr merge",
+            "npm ci", "npm test", "package-lock.json",
+        ):
             self.assertNotIn(forbidden, workflow)
 
         mirror = (REPO / ".agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml")

package/src/commands/update.mjs

@@ -2,8 +2,11 @@ import { readFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { assertConsumerReleaseParity } from '../../scripts/release-parity.mjs';
 import {
-  activateCandidate, adoptReadinessCandidate, readReadinessManifest, stageConsumer, verifyCandidate,
+  activateCandidate, adoptReadinessCandidate, materializeUpdateCandidate, readReadinessManifest,
 } from '../lib/updateCandidate.mjs';
+import {
+  verifyCandidateSchema, verifyUpdateCandidate,
+} from '../lib/verifyUpdateCandidate.mjs';
 import { reconcile } from '../lib/updateReconcile.mjs';
 import {
   CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, readManifest,
@@ -46,7 +49,7 @@ export async function update(options) {
 async function updatePackage(options) {
   const {
     kitRoot, consumerRoot, decide = () => false, dryRun = false,
-    releaseIdentities, verify = verifyCandidate, activate = activateCandidate,
+    releaseIdentities, verify = verifyUpdateCandidate, activate = activateCandidate,
     signal, onState = () => {}, resumeFrom,
   } = options;
   const history = [];
@@ -57,7 +60,8 @@ async function updatePackage(options) {
   if (!pkg) throw new Error('kit package manifest not found');
   if (!dryRun) verifyRelease(releaseIdentities, pkg.kitVersion);
   const consumerManifestPath = join(consumerRoot, CONSUMER_MANIFEST_NAME);
-  if (!await readManifest(consumerManifestPath)) {
+  const priorConsumerManifest = await readManifest(consumerManifestPath);
+  if (!priorConsumerManifest) {
     throw new Error('not initialised — run `init` first');
   }
   const consumerManifestBefore = await readFile(consumerManifestPath);
@@ -75,7 +79,7 @@ async function updatePackage(options) {
   let previewFailure;
   try {
     Object.assign(preview, await previewReadinessAdoption({
-      kitRoot, consumerRoot, priorReadinessManifest, nextReadinessManifest,
+      kitRoot, consumerRoot, pkg, priorReadinessManifest, nextReadinessManifest,
     }));
     preview.conflicts.push(...(preview.migrationConflicts ?? []).map((path) => ({
       path,
@@ -108,18 +112,26 @@ async function updatePackage(options) {
   }
   return applyTransaction({
     kitRoot, consumerRoot, pkg, preview: resolvedPreview, decisions, verify, activate, signal, resumeFrom,
-    consumerManifestBefore, priorReadinessManifest, nextReadinessManifest, history, transition,
+    consumerManifestBefore, priorConsumerManifest,
+    priorReadinessManifest, nextReadinessManifest, history, transition,
   });
 }
 
 async function previewReadinessAdoption(context) {
-  const { kitRoot, consumerRoot, priorReadinessManifest, nextReadinessManifest } = context;
-  const candidateRoot = await stageConsumer(consumerRoot);
+  const {
+    kitRoot, consumerRoot, pkg, priorReadinessManifest, nextReadinessManifest,
+  } = context;
+  const candidateRoot = await materializeUpdateCandidate({
+    consumerRoot, pkg, priorReadinessManifest, nextReadinessManifest,
+  });
   try {
-    await reconcile({
+    const candidatePreview = await reconcile({
       kitRoot, consumerRoot: candidateRoot,
       decide: (action) => action === 'collision' ? 'keep-as-owned' : false,
     });
+    await verifyCandidateSchema(candidateRoot, {
+      pkg, preview: candidatePreview, priorReadinessManifest, nextReadinessManifest,
+    });
     return await adoptReadinessCandidate({
       candidateRoot, consumerRoot, priorManifest: priorReadinessManifest,
       nextManifest: nextReadinessManifest,
@@ -146,7 +158,8 @@ async function resolvePreview({ kitRoot, consumerRoot, preview, decisions, decid
 async function applyTransaction(context) {
   const {
     kitRoot, consumerRoot, pkg, preview, decisions, verify, activate, signal, resumeFrom,
-    consumerManifestBefore, priorReadinessManifest, nextReadinessManifest, history, transition,
+    consumerManifestBefore, priorConsumerManifest,
+    priorReadinessManifest, nextReadinessManifest, history, transition,
   } = context;
   let candidateRoot = resumeFrom;
   let keepCandidate = false;
@@ -157,12 +170,29 @@ async function applyTransaction(context) {
       throw new Error('collision-bearing candidate cannot be resumed safely');
     }
     if (!candidateRoot) {
-      candidateRoot = await stageConsumer(consumerRoot);
+      candidateRoot = await materializeUpdateCandidate({
+        consumerRoot, pkg, priorReadinessManifest, nextReadinessManifest,
+      });
       await reconcile({
         kitRoot, consumerRoot: candidateRoot,
         decide: (action, path) => decisions.get(decisionKey(action, path)),
       });
     }
+    phase = 'verification';
+    await transition('verifying');
+    const abort = async () => {
+      keepCandidate = true;
+      return { ...await terminal(preview, 'aborted', history, transition), candidateRoot };
+    };
+    if (signal?.aborted) return abort();
+    const canonicalContext = {
+      pkg: structuredClone(pkg),
+      preview: structuredClone(preview),
+      priorConsumerManifest: structuredClone(priorConsumerManifest),
+      priorReadinessManifest: structuredClone(priorReadinessManifest),
+      nextReadinessManifest: structuredClone(nextReadinessManifest),
+    };
+    await verifyCandidateSchema(candidateRoot, canonicalContext);
     const readiness = await adoptReadinessCandidate({
       candidateRoot, consumerRoot, priorManifest: priorReadinessManifest,
       nextManifest: nextReadinessManifest,
@@ -178,18 +208,20 @@ async function applyTransaction(context) {
     if (readiness.incompatible.length) {
       throw new Error(`monotonic compatibility would block existing skill core: ${readiness.incompatible.join(', ')}`);
     }
-    phase = 'verification';
-    await transition('verifying');
-    const abort = async () => {
-      keepCandidate = true;
-      return { ...await terminal(preview, 'aborted', history, transition), candidateRoot };
-    };
-    if (signal?.aborted) return abort();
-    await verify(candidateRoot);
+    canonicalContext.preview = structuredClone(preview);
+    await verifyUpdateCandidate(candidateRoot, canonicalContext);
+    if (verify !== verifyUpdateCandidate) {
+      const extensionContext = structuredClone(canonicalContext);
+      await verify(candidateRoot, extensionContext);
+      await verifyUpdateCandidate(candidateRoot, canonicalContext);
+    }
     if (signal?.aborted) return abort();
     phase = 'activation';
     await activate({
-      candidateRoot, consumerRoot, pkg, preview, consumerManifestBefore,
+      candidateRoot, consumerRoot,
+      pkg: canonicalContext.pkg,
+      preview: canonicalContext.preview,
+      consumerManifestBefore,
     });
     return { ...await terminal(preview, 'applied', history, transition), status: 'updated' };
   } catch (error) {
@@ -252,4 +284,4 @@ async function terminal(result, state, history, transition) {
   };
 }
 
-export { verifyCandidate } from '../lib/updateCandidate.mjs';
+export { verifyUpdateCandidate, verifyUpdateCandidate as verifyCandidate } from '../lib/verifyUpdateCandidate.mjs';

package/src/lib/bundle.mjs

@@ -107,7 +107,7 @@ export const HELPER_FILES = [
   // wave. Library (imported by the Phase-0 claim protocol) → 0o644.
   { path: 'src/lib/waveClaim.mjs', kind: 'script', mode: 0o644 },
   // GitHub-consumer automation: invokes the existing update command, then owns
-  // only the stable tested branch/pull-request upsert.
+  // only the stable Kit-verified branch/pull-request upsert.
   { path: 'scripts/kit-update-pr.mjs', kind: 'script', mode: 0o755 },
   // Stdlib-only project census foundation. index.mjs is the stable consumer
   // entrypoint; its five local modules must ship with it as one helper unit.

package/src/lib/updateCandidate.mjs

@@ -1,8 +1,11 @@
-import { execFile } from 'node:child_process';
-import { access, cp, lstat, mkdtemp, readFile, rm, stat, symlink } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import {
+  access, lstat, mkdtemp, open, readFile, realpath, rm, stat,
+} from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join, relative } from 'node:path';
-import { promisify } from 'node:util';
+import {
+  isAbsolute, join, normalize, posix, relative, sep,
+} from 'node:path';
 import { writeAtomic } from './atomicWrite.mjs';
 import { validateConsumerFile } from './consumerPath.mjs';
 import { sha256File } from './hash.mjs';
@@ -10,38 +13,195 @@ import { stubSentinel } from './sentinel.mjs';
 import { STUB_TARGETS } from './bundle.mjs';
 import {
   CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, READINESS_MANIFEST_PATH,
-  indexByPath, readManifest, writeManifest,
+  filesForInstallRole, indexByPath, readManifest, writeManifest,
 } from './manifest.mjs';
 import { checkSkill, evaluateCapability, inspectProdSections } from '../../scripts/readiness.mjs';
 
-const run = promisify(execFile);
 const exists = (path) => access(path).then(() => true, () => false);
 const pathEntryExists = (path) => lstat(path).then(() => true, (error) => {
   if (error.code === 'ENOENT') return false;
   throw error;
 });
 const MIGRATABLE_INSTRUCTION_PATHS = new Set(['CLAUDE.md', 'AGENTS.md']);
+const INTEGRATION_INPUTS = [
+  'package.json', '.claude/settings.json', '.claude/settings.local.json',
+];
+const FORBIDDEN_CANDIDATE_ROOTS = new Set(['.git', '.worktrees', 'node_modules']);
+const PLATFORM_PATH_SEMANTICS = { isAbsolute, normalize, sep };
 
-/** Copy a verification candidate without duplicating git metadata or dependencies. */
-export async function stageConsumer(consumerRoot) {
+/** Materialize only manifest state and declared Consumer inputs for verification. */
+export async function materializeUpdateCandidate({
+  consumerRoot, pkg, priorReadinessManifest, nextReadinessManifest,
+  afterInputValidation = async () => {},
+}) {
   const candidateRoot = await mkdtemp(join(tmpdir(), 'agent-workflow-kit-stage-'));
-  const nodeModules = join(consumerRoot, 'node_modules');
-  await cp(consumerRoot, candidateRoot, {
-    recursive: true,
-    filter: (source) => {
-      const rel = relative(consumerRoot, source);
-      return rel !== '.git' && !rel.startsWith('.git/') &&
-        rel !== 'node_modules' && !rel.startsWith('node_modules/');
-    },
-  });
-  if (await exists(nodeModules)) await symlink(nodeModules, join(candidateRoot, 'node_modules'), 'dir');
-  return candidateRoot;
+  try {
+    const paths = candidateInputPaths({
+      pkg, manifests: [priorReadinessManifest, nextReadinessManifest],
+    });
+    for (const path of paths) {
+      await copyCandidateInput(consumerRoot, candidateRoot, path, afterInputValidation);
+    }
+    await copyDeclaredRunbooks({
+      consumerRoot, candidateRoot, manifests: [priorReadinessManifest, nextReadinessManifest],
+      afterInputValidation,
+    });
+    return candidateRoot;
+  } catch (error) {
+    await rm(candidateRoot, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export function candidateInputPaths({ pkg, manifests }) {
+  const candidates = [
+    CONSUMER_MANIFEST_NAME,
+    ...INTEGRATION_INPUTS,
+    ...filesForInstallRole(pkg).map(({ path }) => path),
+  ];
+  for (const manifest of manifests) {
+    for (const capability of Object.values(manifest?.readiness?.capabilities ?? {})) {
+      candidates.push(...(capability.evidence?.paths ?? []));
+    }
+  }
+  const paths = new Set(candidates.filter((path) => !isForbiddenCandidatePath(path)));
+  return [...paths].sort();
+}
+
+async function copyDeclaredRunbooks({
+  consumerRoot, candidateRoot, manifests, afterInputValidation,
+}) {
+  const runbooks = await declaredCandidateRunbookPaths({ candidateRoot, manifests });
+  for (const path of runbooks) {
+    await copyCandidateInput(consumerRoot, candidateRoot, path, afterInputValidation);
+  }
+}
+
+export async function declaredCandidateRunbookPaths({ candidateRoot, manifests }) {
+  const runbooks = new Set();
+  for (const manifest of manifests) {
+    for (const capability of Object.values(manifest?.readiness?.capabilities ?? {})) {
+      const evidence = capability.evidence;
+      if (evidence?.type !== 'runbook-reference') continue;
+      const declaration = await readCandidateText(candidateRoot, evidence.paths?.[0]);
+      for (const match of declaration?.matchAll(/`([^`\n]+\.md)`/g) ?? []) {
+        if (!match[1].includes('template')) runbooks.add(match[1]);
+      }
+    }
+  }
+  return [...runbooks].sort();
+}
+
+async function readCandidateText(candidateRoot, path) {
+  if (!path) return null;
+  try {
+    return await readFile(join(candidateRoot, path), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function copyCandidateInput(consumerRoot, candidateRoot, path, afterInputValidation) {
+  if (isForbiddenCandidatePath(path)) return;
+  const consumerPath = validateCandidateManifestPath(path);
+  let source;
+  try {
+    source = await validateConsumerFile(consumerRoot, consumerPath);
+  } catch (error) {
+    if (!error.message.startsWith('unsafe consumer path (not a regular file):')) throw error;
+    if (!await pathEntryExists(join(consumerRoot, path))) return;
+    throw error;
+  }
+  const root = await realpath(consumerRoot);
+  const resolved = await realpath(source);
+  assertResolvedConsumerPath(root, resolved, path);
+  const validated = await stat(resolved, { bigint: true });
+  const pathname = await lstat(source, { bigint: true });
+  if (!sameFile(validated, pathname)) {
+    throw new Error(`consumer input changed while staging: ${path}`);
+  }
+  await afterInputValidation(path);
+
+  let handle;
+  try {
+    handle = await open(source, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const opened = await handle.stat({ bigint: true });
+    if (!opened.isFile() || !sameFile(validated, opened)) {
+      throw new Error(`consumer input changed while staging: ${path}`);
+    }
+    const bytes = await handle.readFile();
+    const finished = await handle.stat({ bigint: true });
+    if (!sameFileSnapshot(opened, finished)) {
+      throw new Error(`consumer input changed while staging: ${path}`);
+    }
+    const resolvedAfter = await realpath(source);
+    assertResolvedConsumerPath(root, resolvedAfter, path);
+    const current = await stat(resolvedAfter, { bigint: true });
+    if (!sameFile(opened, current)) {
+      throw new Error(`consumer input changed while staging: ${path}`);
+    }
+    await writeAtomic(join(candidateRoot, path), bytes, Number(opened.mode));
+  } catch (error) {
+    if (error.code === 'ELOOP') {
+      throw new Error(`unsafe consumer path (not a regular file): ${path}`, { cause: error });
+    }
+    throw error;
+  } finally {
+    await handle?.close();
+  }
+}
+
+/**
+ * Accept the package manifest's canonical slash-separated path and translate it
+ * only after platform-independent lexical validation.
+ */
+export function validateCandidateManifestPath(path, pathSemantics = PLATFORM_PATH_SEMANTICS) {
+  if (typeof path !== 'string' || !path || path === '.' || path.includes('\\')
+      || path.split('/').includes('..')
+      || posix.isAbsolute(path) || posix.normalize(path) !== path) {
+    throw new Error(`unsafe candidate manifest path: ${path}`);
+  }
+  const platformPath = path.split('/').join(pathSemantics.sep);
+  if (pathSemantics.isAbsolute(platformPath)
+      || pathSemantics.normalize(platformPath) !== platformPath) {
+    throw new Error(`unsafe candidate manifest path: ${path}`);
+  }
+  return platformPath;
+}
+
+function isForbiddenCandidatePath(path) {
+  if (typeof path !== 'string') return false;
+  const [root] = path.split(/[\\/]/);
+  return FORBIDDEN_CANDIDATE_ROOTS.has(root);
+}
+
+function assertResolvedConsumerPath(root, resolved, path) {
+  const fromRoot = relative(root, resolved);
+  if (!fromRoot || fromRoot === '..' || fromRoot.startsWith(`..${pathSeparator()}`)
+      || isAbsolute(fromRoot)) {
+    throw new Error(`unsafe consumer path (resolved outside root): ${path}`);
+  }
+}
+
+function pathSeparator() {
+  return process.platform === 'win32' ? '\\' : '/';
+}
+
+function sameFile(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function sameFileSnapshot(left, right) {
+  return sameFile(left, right) && left.size === right.size &&
+    left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
 }
 
 /** Activate only verified kit-owned deltas, rolling every touched path back on failure. */
 export async function activateCandidate({
   candidateRoot, consumerRoot, pkg, preview, consumerManifestBefore,
-  afterGenerated = async () => {},
+  afterSnapshot = async () => {}, afterGenerated = async () => {},
+  beforeTargetRevalidation = async () => {},
 }) {
   const changed = [...preview.added, ...preview.updated];
   const generated = preview.generated ?? [];
@@ -50,10 +210,6 @@ export async function activateCandidate({
     ...changed, ...generated, ...migrations.map(({ path }) => path),
     ...preview.deleted, CONSUMER_MANIFEST_NAME,
   ];
-  const currentManifest = await readFile(join(consumerRoot, CONSUMER_MANIFEST_NAME));
-  if (!currentManifest.equals(consumerManifestBefore)) {
-    throw new Error('consumer manifest changed during verification');
-  }
   const pkgIdx = indexByPath(pkg, 'files');
   for (const path of changed) {
     if (await sha256File(join(candidateRoot, path)) !== pkgIdx.get(path)?.sha256) {
@@ -72,28 +228,77 @@ export async function activateCandidate({
       throw new Error(`migrated candidate hash mismatch: ${migration.path}`);
     }
   }
+  const manifestBeforeSnapshot = await readFile(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  if (!manifestBeforeSnapshot.equals(consumerManifestBefore)) {
+    throw new Error('consumer manifest changed during verification');
+  }
   await assertConsumerStillMatchesPreview(consumerRoot, preview);
   const rollback = new Map();
-  for (const path of touched) rollback.set(path, await snapshot(join(consumerRoot, path)));
+  for (const path of touched) {
+    rollback.set(path, await snapshot(join(consumerRoot, path), path));
+  }
+  await afterSnapshot();
+  const currentManifest = await readFile(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  if (!currentManifest.equals(consumerManifestBefore)) {
+    throw new Error('consumer manifest changed during verification');
+  }
+  await assertConsumerStillMatchesPreview(consumerRoot, preview);
+  const applied = [];
+  const applyTarget = async (path, action) => {
+    await beforeTargetRevalidation(path);
+    await assertTargetStillMatchesSnapshot(
+      join(consumerRoot, path), rollback.get(path), path,
+    );
+    // Optimistic revalidation cannot remove the filesystem check-to-rename
+    // micro-window; it does keep every later destination behind a fresh check.
+    await action();
+    const record = { path, snapshot: null, captured: false };
+    applied.push(record);
+    record.snapshot = await snapshot(join(consumerRoot, path), path);
+    record.captured = true;
+  };
   try {
     for (const path of changed) {
-      await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)), pkgIdx.get(path)?.mode);
+      const bytes = await readFile(join(candidateRoot, path));
+      await applyTarget(path, () => writeAtomic(
+        join(consumerRoot, path), bytes, pkgIdx.get(path)?.mode,
+      ));
     }
     for (const path of generated) {
-      await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)));
+      const bytes = await readFile(join(candidateRoot, path));
+      await applyTarget(path, () => writeAtomic(join(consumerRoot, path), bytes));
     }
     for (const { path } of migrations) {
-      await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)));
+      const bytes = await readFile(join(candidateRoot, path));
+      await applyTarget(path, () => writeAtomic(join(consumerRoot, path), bytes));
     }
     await afterGenerated();
-    for (const path of preview.deleted) await rm(join(consumerRoot, path), { force: true });
-    await writeAtomic(
-      join(consumerRoot, CONSUMER_MANIFEST_NAME),
-      await readFile(join(candidateRoot, CONSUMER_MANIFEST_NAME)),
-    );
+    for (const path of preview.deleted) {
+      await applyTarget(path, () => rm(join(consumerRoot, path), { force: true }));
+    }
+    const manifestBytes = await readFile(join(candidateRoot, CONSUMER_MANIFEST_NAME));
+    await applyTarget(CONSUMER_MANIFEST_NAME, () => writeAtomic(
+      join(consumerRoot, CONSUMER_MANIFEST_NAME), manifestBytes,
+    ));
   } catch (error) {
-    for (const path of touched.reverse()) await restore(join(consumerRoot, path), rollback.get(path));
-    error.consumerState = 'rolled-back';
+    const rollbackConflicts = [];
+    for (const record of applied.reverse()) {
+      const target = join(consumerRoot, record.path);
+      if (!record.captured
+          || !await targetStillMatchesSnapshot(target, record.snapshot, record.path)) {
+        rollbackConflicts.push(record.path);
+        continue;
+      }
+      await restore(target, rollback.get(record.path));
+    }
+    if (rollbackConflicts.length) {
+      rollbackConflicts.sort();
+      error.message = `${error.message}; rollback preserved concurrent edits: ` +
+        rollbackConflicts.join(', ');
+    }
+    error.consumerState = rollbackConflicts.length
+      ? 'rollback-conflicted'
+      : (applied.length ? 'rolled-back' : 'unchanged');
     throw error;
   }
 }
@@ -278,26 +483,49 @@ export async function readReadinessManifest(root) {
   return readManifest(join(root, READINESS_MANIFEST_PATH));
 }
 
-async function snapshot(path) {
-  if (!await exists(path)) return null;
-  const info = await stat(path);
-  return { bytes: await readFile(path), mode: info.mode };
+async function snapshot(path, displayPath = path) {
+  let before;
+  try {
+    before = await lstat(path, { bigint: true });
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  if (!before.isFile()) {
+    throw new Error(`unsafe consumer activation path: ${displayPath}`);
+  }
+  const bytes = await readFile(path);
+  const after = await lstat(path, { bigint: true });
+  if (!sameFileSnapshot(before, after)) {
+    throw new Error(`consumer changed during activation: ${displayPath}`);
+  }
+  return { bytes, mode: Number(before.mode), identity: before };
 }
 
-async function restore(path, saved) {
-  if (!saved) return rm(path, { force: true });
-  await writeAtomic(path, saved.bytes, saved.mode);
+async function assertTargetStillMatchesSnapshot(path, expected, displayPath) {
+  if (!await targetStillMatchesSnapshot(path, expected, displayPath)) {
+    throw new Error(`consumer changed during activation: ${displayPath}`);
+  }
 }
 
-/** Default candidate gate: run the consumer's existing npm test command. */
-export async function verifyCandidate(candidateRoot) {
-  let pkg;
+async function targetStillMatchesSnapshot(path, expected, displayPath) {
+  let current;
   try {
-    pkg = JSON.parse(await readFile(join(candidateRoot, 'package.json'), 'utf8'));
+    current = await snapshot(path, displayPath);
   } catch (error) {
-    if (error.code === 'ENOENT') throw new Error('candidate has no package.json test command');
-    throw error;
+    return false;
   }
-  if (!pkg.scripts?.test) throw new Error('candidate has no package.json test command');
-  await run('npm', ['test'], { cwd: candidateRoot });
+  return sameActivationSnapshot(expected, current);
+}
+
+function sameActivationSnapshot(expected, current) {
+  if (!expected || !current) return expected === current;
+  return expected.mode === current.mode
+    && expected.bytes.equals(current.bytes)
+    && sameFileSnapshot(expected.identity, current.identity);
+}
+
+async function restore(path, saved) {
+  if (!saved) return rm(path, { force: true });
+  await writeAtomic(path, saved.bytes, saved.mode);
 }