@kontourai/flow-agents 4.0.0 → 4.2.0

package/src/cli/kit.ts

@@ -6,7 +6,8 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagBool, flagString } from "../lib/args.js";
 import { assertPathContained, assertPathsDisjoint, atomicWriteJson, copyDirAtomic, ensureSafeDirectory, isoNow, readJson, walkFiles } from "../lib/fs.js";
-import { assertKitRepository, deriveKitTargets, parseKitDependencies } from "../flow-kit/validate.js";
+import { assertKitRepository, deriveKitTargets, parseKitDependencies, validateKitRepositoryDiagnostics } from "../flow-kit/validate.js";
+import { provisionKit, ProvisionConflictError } from "../flow-kit/provision.js";
 import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
 import { defaultCodexHome } from "../lib/local-artifact-root.js";
 import { root } from "../tools/common.js";
@@ -35,6 +36,17 @@ function resolveCatalogKitSource(source: string): string | null {
   return path.resolve(path.dirname(repoCatalogPath), "..", rel);
 }
 
+function resolveProvisionKitSource(source: string, dest: string): string | null {
+  const localPath = path.resolve(source);
+  if (fs.existsSync(localPath)) return localPath;
+  const installed = loadRegistry(dest).kits.find((entry) => entry.id === source);
+  if (installed) {
+    const installedSource = installedPath(dest, source);
+    if (fs.existsSync(installedSource)) return installedSource;
+  }
+  return resolveCatalogKitSource(source);
+}
+
 function loadRegistry(dest: string): { schema_version: string; kits: Record<string, unknown>[] } {
   const file = registryPath(dest);
   if (!fs.existsSync(file)) return { schema_version: "1.0", kits: [] };
@@ -64,6 +76,17 @@ function warnUninstalledDependencies(manifest: Record<string, unknown>, manifest
   }
 }
 
+/**
+ * Print non-blocking kit-validation warnings (e.g. an agent-spawning trigger surface
+ * declared without complete guard config — context/contracts/trigger-guards.md).
+ * Shared by BOTH install source forms (local path and git clone) so the standing
+ * warning contract cannot silently diverge between them. Same non-blocking
+ * `warning:` convention as warnUninstalledDependencies above.
+ */
+async function printKitValidationWarnings(kitDir: string): Promise<void> {
+  for (const warning of (await validateKitRepositoryDiagnostics(kitDir)).warnings) console.log(`warning: ${warning}`);
+}
+
 function contentHash(root: string): string {
   const hash = crypto.createHash("sha256");
   for (const file of walkFiles(root)) {
@@ -126,6 +149,7 @@ async function installLocalSource(source: string, argv: string[]): Promise<numbe
   let manifest: Record<string, unknown>;
   try {
     manifest = await assertKitRepository(source);
+    await printKitValidationWarnings(source);
   } catch (error) {
     console.log("Flow Kit repository validation failed:");
     for (const diagnostic of ((error as Error & { diagnostics?: string[] }).diagnostics ?? [(error as Error).message])) console.log(` - ${diagnostic}`);
@@ -213,6 +237,7 @@ async function installGitSource(rawUrl: string, argv: string[]): Promise<number>
     let manifest: Record<string, unknown>;
     try {
       manifest = await assertKitRepository(tmpBase);
+      await printKitValidationWarnings(tmpBase);
     } catch (error) {
       console.log("Flow Kit repository validation failed:");
       for (const diagnostic of ((error as Error & { diagnostics?: string[] }).diagnostics ?? [(error as Error).message])) {
@@ -325,6 +350,60 @@ function activate(argv: string[]): number {
   return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }
 
+async function validate(argv: string[]): Promise<number> {
+  const args = parseArgs(argv);
+  const kitDir = path.resolve(args.positionals[0] ?? ".");
+  const diagnostics = await validateKitRepositoryDiagnostics(kitDir);
+  for (const warning of diagnostics.warnings) console.log(`warning: ${warning}`);
+  if (diagnostics.errors.length) {
+    console.log("Flow Kit repository validation failed:");
+    for (const error of diagnostics.errors) console.log(` - ${error}`);
+    return 1;
+  }
+  console.log(`Flow Kit repository validation passed: ${kitDir}`);
+  return 0;
+}
+
+async function provision(argv: string[]): Promise<number> {
+  const args = parseArgs(argv);
+  const source = args.positionals[0];
+  if (!source) {
+    console.error("provision: missing <kit-id-or-path> argument");
+    console.error("usage: flow-agents kit provision <kit-id-or-path> [--target <dir>] [--force] [--dry-run]");
+    return 2;
+  }
+  const dest = resolveDest(args.flags);
+  const kitDir = resolveProvisionKitSource(source, dest);
+  if (!kitDir) {
+    console.error(`provision: kit '${source}' was not found as a local path, installed kit, or catalog kit`);
+    return 1;
+  }
+  const target = path.resolve(flagString(args.flags, "target", process.cwd()) ?? process.cwd());
+  try {
+    const result = await provisionKit(kitDir, target, {
+      force: flagBool(args.flags, "force"),
+      dryRun: flagBool(args.flags, "dry-run"),
+    });
+    for (const file of result.files) console.log(`${result.dry_run ? "would provision" : "provisioned"}: ${file.source} -> ${file.destination}`);
+    if (result.dry_run) console.log(`dry-run: ${result.files.length} file(s) declared by kit '${result.kit_id}'; no files written`);
+    else if (result.files.length === 0) console.log(`kit '${result.kit_id}' declares no provisions`);
+    else console.log(`provisioned ${result.files.length} file(s) from kit '${result.kit_id}' into ${target}`);
+    return 0;
+  } catch (error) {
+    if (error instanceof ProvisionConflictError) {
+      console.error(`provision: ${error.message}; rerun with --force to overwrite`);
+      for (const conflict of error.conflicts) console.error(`conflict: ${conflict.target} (${conflict.destination})`);
+      return 1;
+    }
+    const diagnostics = (error as Error & { diagnostics?: string[] }).diagnostics;
+    if (diagnostics?.length) {
+      console.error("Flow Kit repository validation failed:");
+      for (const diagnostic of diagnostics) console.error(` - ${diagnostic}`);
+    } else console.error(`provision: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
 /**
  * inspect <kit-dir> [--json]
  *
@@ -373,8 +452,10 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
   if (command === "list") return list(rest);
   if (command === "status") return status(rest);
   if (command === "activate") return activate(rest);
+  if (command === "validate") return await validate(rest);
+  if (command === "provision") return await provision(rest);
   if (command === "inspect") return await inspect(rest);
-  console.error("usage: flow-agents kit <install|activate|inspect|list|status> ...");
+  console.error("usage: flow-agents kit <install|activate|validate|provision|inspect|list|status> ...");
   return 2;
 }
 

package/src/cli/pull-work-provider.ts

@@ -849,7 +849,13 @@ export function main(argv = process.argv.slice(2)): number {
     const freshness = revisionFreshness(item, freshnessInputs);
     return { ...item, dependency_impacts: dependencyImpacts(item, resolved), revision_freshness: freshness, readiness: applyFreshnessToReadiness(classify(item, settings, resolved), freshness) };
   });
-  console.log(JSON.stringify({ items }, null, 2));
+  // A configured BoardProvider is the canonical readiness source (docs/decisions/backlog-readiness-source.md).
+  // Reaching this issue-level listing path with a board configured is a bypass that must be loud, never silent.
+  const bypassedBoard = asRecord(asRecord(settings.board_provider)?.board);
+  const warnings = bypassedBoard
+    ? [{ code: "board_provider_bypassed", message: "A BoardProvider is configured but this pass used WorkItemProvider issue-level listing; board-driven selection is the canonical readiness source. Surface this bypass in the pull-work artifact instead of treating issue listing as a silent fallback." }]
+    : [];
+  console.log(JSON.stringify({ items, warnings }, null, 2));
   return 0;
 }
 

package/src/cli/validate-waves.test.mjs

@@ -0,0 +1,134 @@
+// Unit tests for waves.json wave-manifest reconciliation validation (#663 slice 1).
+//
+// validate-workflow-artifacts.ts is a CLI script (no exported helpers), so these
+// node:test units drive the built validator as a child process against temp fixture
+// directories — the same black-box surface CI's workflow-artifact-integration lane
+// uses, but fast and countable as unit executions. They pin the load-bearing
+// behavior of the reconcile-against-manifest contract:
+//   - a reconciled wave with an explicit not_reported worker is VALID DATA
+//     ("2 of 3 reported; worker-3 not_reported") — visibility, not a block;
+//   - a silent drop (complete claim over a missing worker record) FAILS with
+//     messages naming the dropped worker, the count mismatch, and the impossible
+//     complete claim.
+//
+// Run: `node --test src/cli/validate-waves.test.mjs` (requires `npm run build`).
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const validator = path.join(repoRoot, "build", "src", "cli", "validate-workflow-artifacts.js");
+
+function runValidator(wavesPayload) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "waves-unit-"));
+  try {
+    fs.writeFileSync(path.join(dir, "waves.json"), JSON.stringify(wavesPayload, null, 2));
+    const result = spawnSync(process.execPath, [validator, dir], { encoding: "utf8" });
+    return { status: result.status, output: `${result.stdout}\n${result.stderr}` };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function manifest(waveOverrides) {
+  return {
+    schema_version: "1.0",
+    task_slug: "waves-unit",
+    waves: [
+      {
+        wave_id: "execute-wave-1",
+        step: "execute",
+        declared_at: "2026-07-16T00:00:00Z",
+        expected_workers: [
+          { worker_id: "worker-1", task: "task one" },
+          { worker_id: "worker-2", task: "task two" },
+          { worker_id: "worker-3", task: "task three" },
+        ],
+        ...waveOverrides,
+      },
+    ],
+  };
+}
+
+test("fully reported wave reconciles complete and validates", () => {
+  const { status, output } = runValidator(manifest({
+    worker_results: [
+      { worker_id: "worker-1", status: "completed", summary: "done", recorded_at: "2026-07-16T01:00:00Z" },
+      { worker_id: "worker-2", status: "failed", summary: "tests failing", recorded_at: "2026-07-16T01:00:00Z" },
+      { worker_id: "worker-3", status: "blocked", summary: "blocked on approval", recorded_at: "2026-07-16T01:00:00Z" },
+    ],
+    reconciliation: {
+      status: "complete",
+      expected_count: 3,
+      reported_count: 3,
+      summary: "3 of 3 reported; no workers not_reported",
+      reconciled_at: "2026-07-16T01:05:00Z",
+    },
+  }));
+  assert.equal(status, 0, output);
+});
+
+test("2 of 3 reported with explicit not_reported worker is valid data, not a block", () => {
+  const { status, output } = runValidator(manifest({
+    worker_results: [
+      { worker_id: "worker-1", status: "completed", summary: "done", recorded_at: "2026-07-16T01:00:00Z" },
+      { worker_id: "worker-2", status: "completed", summary: "done", recorded_at: "2026-07-16T01:00:00Z" },
+      { worker_id: "worker-3", status: "not_reported", summary: "no terminal report by wave close; routed to re-dispatch", recorded_at: "2026-07-16T01:05:00Z" },
+    ],
+    reconciliation: {
+      status: "incomplete",
+      expected_count: 3,
+      reported_count: 2,
+      summary: "2 of 3 reported; worker-3 not_reported",
+      reconciled_at: "2026-07-16T01:05:00Z",
+    },
+  }));
+  assert.equal(status, 0, output);
+});
+
+test("silent drop behind a complete claim fails naming the missing worker", () => {
+  const { status, output } = runValidator(manifest({
+    worker_results: [
+      { worker_id: "worker-1", status: "completed", summary: "done", recorded_at: "2026-07-16T01:00:00Z" },
+      { worker_id: "worker-2", status: "completed", summary: "done", recorded_at: "2026-07-16T01:00:00Z" },
+    ],
+    reconciliation: {
+      status: "complete",
+      expected_count: 3,
+      reported_count: 3,
+      summary: "3 of 3 reported",
+      reconciled_at: "2026-07-16T01:05:00Z",
+    },
+  }));
+  assert.equal(status, 1);
+  assert.match(output, /worker worker-3 has no terminal status record/);
+  assert.match(output, /reported_count is 3 but 2 of 3 expected workers/);
+  assert.match(output, /complete requires every expected worker/);
+});
+
+test("duplicate terminal records and undeclared reporters are rejected", () => {
+  const { status, output } = runValidator(manifest({
+    worker_results: [
+      { worker_id: "worker-1", status: "completed", summary: "done", recorded_at: "2026-07-16T01:00:00Z" },
+      { worker_id: "worker-1", status: "failed", summary: "again", recorded_at: "2026-07-16T01:01:00Z" },
+      { worker_id: "worker-9", status: "completed", summary: "surprise", recorded_at: "2026-07-16T01:00:00Z" },
+    ],
+  }));
+  assert.equal(status, 1);
+  assert.match(output, /more than one terminal status record for worker worker-1/);
+  assert.match(output, /worker worker-9 that is not declared in expected_workers/);
+});
+
+test("unknown terminal status fails against the schema enum", () => {
+  const { status, output } = runValidator(manifest({
+    worker_results: [
+      { worker_id: "worker-1", status: "maybe-done", summary: "unclear", recorded_at: "2026-07-16T01:00:00Z" },
+    ],
+  }));
+  assert.equal(status, 1);
+  assert.match(output, /status must be one of: completed, failed, blocked, not_reported/);
+});

package/src/cli/validate-workflow-artifacts.ts

@@ -21,6 +21,7 @@ const sidecarSchemas: Record<string, string> = {
   "critique.json": "schemas/workflow-critique.schema.json",
   "release.json": "schemas/workflow-release.schema.json",
   "learning.json": "schemas/workflow-learning.schema.json",
+  "waves.json": "schemas/workflow-waves.schema.json",
 };
 // Runtime coordination records live below a session but are not workflow
 // sidecars. Recursing into them would validate continuation-driver/state.json
@@ -321,12 +322,58 @@ function validateSidecar(file: string): { issues: Issue[]; warnings: Issue[] } {
       if (Array.isArray(value.post_deploy_checks) && value.post_deploy_checks.some((c: any) => !["planned", "pass"].includes(c.status))) issues.push({ path: file, message: "deploy decision requires post_deploy_checks to be planned or pass" });
     }
   }
+  if (path.basename(file) === "waves.json") {
+    validateWaves(file, value, issues);
+  }
   if (path.basename(file) === "state.json" && value && typeof value === "object" && !Array.isArray(value) && !("branch" in value)) {
     warnings.push({ path: file, message: "state.json has no branch field (legacy/pre-#289 session) — re-run `ensure-session` to backfill agent/<actor>/<slug>." });
   }
   return { issues, warnings };
 }
 
+// #663 slice 1: wave-result reconciliation is machine-checkable, not prose. The schema
+// (schemas/workflow-waves.schema.json) validates the shape; these semantic checks enforce the
+// cross-record arithmetic the mini schema engine cannot express: exactly one terminal status
+// record per declared worker, no undeclared reporters, reconciliation counts that match the
+// records, and a `complete` claim that is impossible while any expected worker lacks a
+// worker-landed terminal status. Missing workers must be recorded explicitly as not_reported —
+// a reconciled wave never silently absorbs a dropped worker. Enforcement here is data-level
+// validation only; stop-hook refusal of wave completion is #663 part 3 (slice 2).
+function validateWaves(file: string, value: any, issues: Issue[]): void {
+  const waves = Array.isArray(value?.waves) ? value.waves : [];
+  waves.forEach((wave: any, index: number) => {
+    const loc = `waves.json.waves[${index}]`;
+    const expected: any[] = Array.isArray(wave?.expected_workers) ? wave.expected_workers : [];
+    const results: any[] = Array.isArray(wave?.worker_results) ? wave.worker_results : [];
+    const expectedIds = expected.map((w) => w?.worker_id).filter((id) => typeof id === "string" && id.length > 0);
+    const expectedIdSet = new Set(expectedIds);
+    if (expectedIdSet.size !== expectedIds.length) issues.push({ path: file, message: `${loc}.expected_workers must declare unique worker_id values` });
+    const resultIds = results.map((r) => r?.worker_id).filter((id) => typeof id === "string" && id.length > 0);
+    const seen = new Set<string>();
+    for (const id of resultIds) {
+      if (seen.has(id)) issues.push({ path: file, message: `${loc}.worker_results has more than one terminal status record for worker ${id}; each worker lands exactly one` });
+      seen.add(id);
+      if (!expectedIdSet.has(id)) issues.push({ path: file, message: `${loc}.worker_results records worker ${id} that is not declared in expected_workers; declare every worker in the manifest before dispatch` });
+    }
+    const reconciliation = wave?.reconciliation;
+    if (!reconciliation || typeof reconciliation !== "object" || Array.isArray(reconciliation)) return;
+    const expectedCount = expectedIds.length;
+    const reportedIds = new Set(results.filter((r) => ["completed", "failed", "blocked"].includes(r?.status) && expectedIdSet.has(r?.worker_id)).map((r) => r.worker_id as string));
+    const reportedCount = reportedIds.size;
+    if (reconciliation.expected_count !== expectedCount) issues.push({ path: file, message: `${loc}.reconciliation.expected_count is ${reconciliation.expected_count} but expected_workers declares ${expectedCount}` });
+    if (reconciliation.reported_count !== reportedCount) issues.push({ path: file, message: `${loc}.reconciliation.reported_count is ${reconciliation.reported_count} but ${reportedCount} of ${expectedCount} expected workers have a worker-landed terminal status (completed|failed|blocked)` });
+    const missing = expectedIds.filter((id) => !results.some((r) => r?.worker_id === id));
+    for (const id of missing) issues.push({ path: file, message: `${loc} is reconciled but worker ${id} has no terminal status record; record it explicitly as not_reported — never silently absorb a missing worker` });
+    const notReported = results.filter((r) => r?.status === "not_reported" && expectedIdSet.has(r?.worker_id));
+    if (reconciliation.status === "complete" && (missing.length > 0 || notReported.length > 0 || reportedCount !== expectedCount)) {
+      issues.push({ path: file, message: `${loc}.reconciliation.status complete requires every expected worker to have a worker-landed terminal status; got ${reportedCount} of ${expectedCount} reported` });
+    }
+    if (reconciliation.status === "incomplete" && missing.length === 0 && notReported.length === 0 && reportedCount === expectedCount) {
+      issues.push({ path: file, message: `${loc}.reconciliation.status incomplete contradicts the records: all ${expectedCount} expected workers reported` });
+    }
+  });
+}
+
 function validateLearningCorrections(file: string, status: unknown, records: any[], issues: Issue[]): void {
   records.forEach((record, index) => {
     const correction = record?.correction;

package/src/cli/workflow.ts

@@ -717,7 +717,13 @@ function assertDistinctReviewActor(sessionDir: string, slug: string): ReturnType
   const assignment = readActiveAssignment(sessionDir, slug);
   const caller = resolveCurrentAssignmentActor();
   if (assignment.actor_key === caller.actorKey) {
-    throw new Error("workflow critique requires a reviewer identity distinct from the active implementation assignment actor");
+    throw new Error(
+      "workflow critique requires a reviewer identity distinct from the active implementation assignment actor. " +
+        "The reviewer identity is derived from the runtime actor, so an orchestrator that implemented and now reviews " +
+        "resolves to the same actor. To record an independent review, run the reviewer under a distinct actor: set " +
+        "FLOW_AGENTS_ACTOR=<reviewer-id> on the reviewing process, or run the reviewer in a separate runtime session " +
+        "(the runtime session id seeds the actor).",
+    );
   }
   return caller;
 }

package/src/flow-kit/provision.ts

@@ -0,0 +1,118 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicCopyFile, atomicWriteJson, canonicalProspectivePath, walkFiles } from "../lib/fs.js";
+import { PROVISION_MANIFEST_DIR, assertKitRepository, type KitProvisionEntry } from "./validate.js";
+
+export type ProvisionedFile = { id: string; target: string };
+
+export type ProvisionPlanEntry = ProvisionedFile & {
+  source: string;
+  destination: string;
+};
+
+export type ProvisionResult = {
+  kit_id: string;
+  kit_hash?: string;
+  files: ProvisionPlanEntry[];
+  manifest_path?: string;
+  dry_run: boolean;
+};
+
+export class ProvisionConflictError extends Error {
+  readonly conflicts: ProvisionPlanEntry[];
+
+  constructor(conflicts: ProvisionPlanEntry[]) {
+    super(`provisioning conflicts with ${conflicts.length} existing destination(s)`);
+    this.name = "ProvisionConflictError";
+    this.conflicts = conflicts;
+  }
+}
+
+function kitContentHash(kitDir: string): string {
+  const hash = crypto.createHash("sha256");
+  for (const file of walkFiles(kitDir)) {
+    const rel = path.relative(kitDir, file).split(path.sep).join("/");
+    if (rel.split("/").some((part) => [".git", "__pycache__", ".pytest_cache"].includes(part))) continue;
+    hash.update(rel);
+    hash.update("\0");
+    hash.update(fs.readFileSync(file));
+    hash.update("\0");
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function isContained(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+function assertSafeDestination(rootReal: string, destination: string): void {
+  const prospective = canonicalProspectivePath(destination);
+  if (!isContained(rootReal, prospective)) throw new Error(`provision target escapes consumer repository: ${destination}`);
+  if (!fs.existsSync(destination)) return;
+  const stat = fs.lstatSync(destination);
+  if (stat.isSymbolicLink()) throw new Error(`refusing provision target symlink: ${destination}`);
+  if (!stat.isFile()) throw new Error(`provision target is not a regular file: ${destination}`);
+}
+
+function manifestProvisions(manifest: Record<string, unknown>): KitProvisionEntry[] {
+  if (!Array.isArray(manifest.provisions)) return [];
+  return manifest.provisions.map((entry) => {
+    const record = entry as Record<string, unknown>;
+    return {
+      id: String(record.id),
+      path: String(record.path),
+      target: path.posix.normalize(String(record.target).replace(/\\/g, "/")),
+      ...(typeof record.description === "string" ? { description: record.description } : {}),
+    };
+  });
+}
+
+export async function provisionKit(
+  kitDir: string,
+  targetDir: string,
+  options: { force?: boolean; dryRun?: boolean } = {},
+): Promise<ProvisionResult> {
+  const kitRoot = fs.realpathSync(path.resolve(kitDir));
+  const targetPath = path.resolve(targetDir);
+  if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
+    throw new Error(`provision target must exist and be a directory: ${targetPath}`);
+  }
+  const targetRoot = fs.realpathSync(targetPath);
+  const manifest = await assertKitRepository(kitRoot);
+  const kitId = String(manifest.id);
+  const files = manifestProvisions(manifest).map((entry) => ({
+    id: entry.id,
+    target: entry.target,
+    source: path.resolve(kitRoot, entry.path),
+    destination: path.resolve(targetRoot, ...entry.target.split("/")),
+  }));
+
+  for (const file of files) assertSafeDestination(targetRoot, file.destination);
+  // Defense in depth against a source swapped to a link after validation: re-assert the
+  // link-resolved source stays inside the kit before we read and copy its bytes.
+  for (const file of files) {
+    const realSource = fs.realpathSync(file.source);
+    if (realSource !== kitRoot && !realSource.startsWith(`${kitRoot}${path.sep}`)) {
+      throw new Error(`provision source escapes the kit directory: ${file.id}`);
+    }
+  }
+  const conflicts = options.force ? [] : files.filter((file) => fs.existsSync(file.destination));
+  if (conflicts.length) throw new ProvisionConflictError(conflicts);
+
+  const kitHash = kitContentHash(kitRoot);
+  if (options.dryRun || files.length === 0) return { kit_id: kitId, kit_hash: kitHash, files, dry_run: Boolean(options.dryRun) };
+
+  const manifestPath = path.join(targetRoot, ...PROVISION_MANIFEST_DIR.split("/"), `${kitId}.json`);
+  assertSafeDestination(targetRoot, manifestPath);
+  for (const file of files) atomicCopyFile(targetRoot, file.source, file.destination);
+  atomicWriteJson(targetRoot, manifestPath, {
+    schema_version: "1.0",
+    kit_id: kitId,
+    kit_hash: kitHash,
+    provisioned_at: new Date().toISOString(),
+    files: files.map(({ id, target }) => ({ id, target })),
+  });
+  return { kit_id: kitId, kit_hash: kitHash, files, manifest_path: manifestPath, dry_run: false };
+}