@kontourai/flow-agents 3.12.1 → 4.1.0

package/src/cli/kit-metadata-security.test.mjs

@@ -7,7 +7,7 @@ import { createRequire, syncBuiltinESMExports } from "node:module";
 
 import { readKitInventory } from "../../build/src/runtime-adapters.js";
 import { main as validateHookInfluence } from "../../build/src/cli/validate-hook-influence.js";
-import { parseKitFlowStepActions, parseKitSkillRoles, validateKitRepository } from "../../build/src/flow-kit/validate.js";
+import { parseKitAgentSpawnTriggers, parseKitFlowStepActions, parseKitSkillRoles, validateKitRepository, validateKitRepositoryDiagnostics } from "../../build/src/flow-kit/validate.js";
 import { observeBuilderArtifactsForProgress } from "../../build/src/builder-gate-action-envelope.js";
 
 const require = createRequire(import.meta.url);
@@ -148,6 +148,85 @@ test("flow step action metadata preserves explicit operation expectation ownersh
   assert.deepEqual(result.entries[0]?.artifacts, []);
 });
 
+test("flow step action metadata preserves optional artifacts without expectation ownership", () => {
+  const result = parseKitFlowStepActions({
+    flow_step_actions: [{
+      flow_id: "builder.build",
+      step_id: "observe",
+      skills: ["observe-work"],
+      operations: [],
+      implementation_allowed: false,
+      artifacts: ["optional.md"],
+      expectation_ids: [],
+      expectation_bindings: [],
+      artifact_bindings: [{ artifact: "optional.md", expectation_ids: [] }],
+    }],
+  }, "fixture/kit.json");
+
+  assert.deepEqual(result.errors, []);
+  assert.deepEqual(result.entries[0].artifact_bindings, [{ artifact: "optional.md", expectation_ids: [] }]);
+});
+
+test("flow step action metadata rejects unowned trust slices without a recording interface", () => {
+  const result = parseKitFlowStepActions({
+    flow_step_actions: [{
+      flow_id: "builder.build",
+      step_id: "observe",
+      skills: [],
+      operations: [],
+      implementation_allowed: false,
+      artifacts: ["trust.bundle#optional"],
+      expectation_ids: [],
+      expectation_bindings: [],
+      artifact_bindings: [{ artifact: "trust.bundle#optional", expectation_ids: [] }],
+    }],
+  }, "fixture/kit.json");
+
+  assert.match(result.errors.join("\n"), /trust slice must own at least one expectation/);
+});
+
+test("flow step action metadata permits mixed workflow and operation ownership for files", () => {
+  const result = parseKitFlowStepActions({
+    flow_step_actions: [{
+      flow_id: "builder.build",
+      step_id: "publish",
+      skills: ["publish-summary"],
+      operations: ["publish-change"],
+      implementation_allowed: false,
+      artifacts: ["publish-change.result.json"],
+      expectation_ids: ["published-change", "published-summary"],
+      expectation_bindings: [
+        { expectation_id: "published-change", interface: "operation", operation: "publish-change" },
+        { expectation_id: "published-summary", interface: "workflow.evidence" },
+      ],
+      artifact_bindings: [{ artifact: "publish-change.result.json", expectation_ids: ["published-change", "published-summary"] }],
+    }],
+  }, "fixture/kit.json");
+
+  assert.deepEqual(result.errors, []);
+});
+
+test("flow step action metadata rejects artifact ownership without a compatible producer", () => {
+  const operationTrustSlice = parseKitFlowStepActions({
+    flow_step_actions: [{
+      flow_id: "builder.build", step_id: "publish", skills: [], operations: ["publish-change"], implementation_allowed: false,
+      artifacts: ["trust.bundle#published"], expectation_ids: ["published-change"],
+      expectation_bindings: [{ expectation_id: "published-change", interface: "operation", operation: "publish-change" }],
+      artifact_bindings: [{ artifact: "trust.bundle#published", expectation_ids: ["published-change"] }],
+    }],
+  }, "fixture/kit.json");
+  assert.match(operationTrustSlice.errors.join("\n"), /trust slice cannot own an operation expectation/);
+
+  const unproducedFile = parseKitFlowStepActions({
+    flow_step_actions: [{
+      flow_id: "builder.build", step_id: "observe", skills: [], operations: [], implementation_allowed: false,
+      artifacts: ["optional.md"], expectation_ids: [], expectation_bindings: [],
+      artifact_bindings: [{ artifact: "optional.md", expectation_ids: [] }],
+    }],
+  }, "fixture/kit.json");
+  assert.match(unproducedFile.errors.join("\n"), /file has no skill or operation producer/);
+});
+
 test("Builder action validation rejects expectation omissions, unsafe artifacts, and unknown operations", async () => {
   async function errorsFor(name, mutate) {
     const root = tempRoot(`flow-agents-action-contract-${name}-`);
@@ -222,7 +301,7 @@ test("metadata validation matches runtime skill and run-wide observable artifact
   const actions = Array.from({ length: 5 }, (_, actionIndex) => {
     const slice = artifacts.slice(actionIndex * 32, (actionIndex + 1) * 32);
     return {
-      flow_id: "builder.build", step_id: `step${actionIndex}`, skills: [], operations: [], implementation_allowed: false,
+      flow_id: "builder.build", step_id: `step${actionIndex}`, skills: ["observe-work"], operations: [], implementation_allowed: false,
       artifacts: slice, expectation_ids: [], expectation_bindings: [],
       artifact_bindings: slice.map((artifact) => ({ artifact, expectation_ids: [] })),
     };
@@ -231,7 +310,12 @@ test("metadata validation matches runtime skill and run-wide observable artifact
   assert.match(tooManyArtifacts.errors.join("\n"), /exceed 128 distinct observable file artifacts/);
 
   actions[4].artifacts = ["state.json", "trust.bundle#virtual"];
-  actions[4].artifact_bindings = actions[4].artifacts.map((artifact) => ({ artifact, expectation_ids: [] }));
+  actions[4].expectation_ids = ["virtual-evidence"];
+  actions[4].expectation_bindings = [{ expectation_id: "virtual-evidence", interface: "workflow.evidence" }];
+  actions[4].artifact_bindings = [
+    { artifact: "state.json", expectation_ids: [] },
+    { artifact: "trust.bundle#virtual", expectation_ids: ["virtual-evidence"] },
+  ];
   const excluded = parseKitFlowStepActions({ flow_step_actions: actions }, "fixture/kit.json");
   assert.doesNotMatch(excluded.errors.join("\n"), /distinct observable file artifacts/);
 });
@@ -380,6 +464,10 @@ test("mixed skill and operation ownership follows each expectation binding inter
   const policyBinding = action.expectation_bindings.find((entry) => entry.expectation_id === "policy-compliance");
   policyBinding.interface = "operation";
   policyBinding.operation = "publish-change";
+  const policyArtifactBinding = action.artifact_bindings.find((entry) => entry.expectation_ids.includes("policy-compliance"));
+  const policyArtifactIndex = action.artifacts.indexOf(policyArtifactBinding.artifact);
+  action.artifacts[policyArtifactIndex] = "publish-change.result.json";
+  policyArtifactBinding.artifact = "publish-change.result.json";
   const verifier = manifest.skill_roles.find((entry) => entry.skill_id === "builder.verify-work");
   verifier.expectation_ids = verifier.expectation_ids.filter((id) => id !== "policy-compliance");
   writeJson(manifestFile, manifest);
@@ -820,3 +908,165 @@ test("workflowTriggersFor returns Knowledge's structured capture trigger", () =>
   assert.match(trigger.steering, /Keep the session on `knowledge\.ingest`/);
   assert.match(trigger.steering, /unsupported-runtime blocker/);
 });
+
+test("agent spawn trigger metadata accepts a fully guarded declaration without errors or warnings", () => {
+  const result = parseKitAgentSpawnTriggers({
+    agent_spawn_triggers: [
+      {
+        id: "on-check-failure",
+        description: "Escalates failing checks to a headless agent run.",
+        spawns_agent_runs: true,
+        guards: { dedup_key: "check-name+failure-signature", cooldown_seconds: 900, daily_cap: 20, max_concurrent: 1 },
+      },
+      {
+        id: "notify-only",
+        description: "Fires a notification; never spawns agent runs.",
+        spawns_agent_runs: false,
+      },
+    ],
+  }, "fixture/kit.json");
+
+  assert.deepEqual(result.errors, []);
+  assert.deepEqual(result.warnings, []);
+  assert.equal(result.entries.length, 2);
+  assert.deepEqual(result.entries[0].guards, { dedup_key: "check-name+failure-signature", cooldown_seconds: 900, daily_cap: 20, max_concurrent: 1 });
+  assert.equal(result.entries[1].guards, undefined);
+});
+
+test("agent spawn trigger without guards warns (never errors) when it spawns agent runs", () => {
+  const missing = parseKitAgentSpawnTriggers({
+    agent_spawn_triggers: [
+      { id: "on-schedule", description: "Scheduled automation spawning agent runs.", spawns_agent_runs: true },
+    ],
+  }, "fixture/kit.json");
+  assert.deepEqual(missing.errors, []);
+  assert.equal(missing.warnings.length, 1);
+  assert.match(missing.warnings[0], /agent_spawn_triggers\[0\] \('on-schedule'\) spawns agent runs without complete guard config/);
+  assert.match(missing.warnings[0], /missing: dedup_key, cooldown_seconds, daily_cap, max_concurrent/);
+  assert.match(missing.warnings[0], /context\/contracts\/trigger-guards\.md/);
+  assert.equal(missing.entries.length, 1);
+
+  const incomplete = parseKitAgentSpawnTriggers({
+    agent_spawn_triggers: [
+      { id: "on-check-failure", description: "Escalation.", spawns_agent_runs: true, guards: { cooldown_seconds: 900 } },
+    ],
+  }, "fixture/kit.json");
+  assert.deepEqual(incomplete.errors, []);
+  assert.equal(incomplete.warnings.length, 1);
+  assert.match(incomplete.warnings[0], /missing: dedup_key, daily_cap, max_concurrent/);
+
+  const nonSpawning = parseKitAgentSpawnTriggers({
+    agent_spawn_triggers: [
+      { id: "notify-only", description: "Notification only.", spawns_agent_runs: false },
+    ],
+  }, "fixture/kit.json");
+  assert.deepEqual(nonSpawning.errors, []);
+  assert.deepEqual(nonSpawning.warnings, []);
+});
+
+test("agent spawn trigger metadata rejects malformed shapes as errors", () => {
+  const notAList = parseKitAgentSpawnTriggers({ agent_spawn_triggers: {} }, "fixture/kit.json");
+  assert.match(notAList.errors.join("\n"), /\.agent_spawn_triggers must be a list/);
+
+  const result = parseKitAgentSpawnTriggers({
+    agent_spawn_triggers: [
+      { id: "Bad Id", description: "x", spawns_agent_runs: true },
+      { id: "dup", description: "x", spawns_agent_runs: true, guards: { dedup_key: "sig", cooldown_seconds: 900, daily_cap: 20, max_concurrent: 1 } },
+      { id: "dup", description: "x", spawns_agent_runs: true, guards: { dedup_key: "sig", cooldown_seconds: 900, daily_cap: 20, max_concurrent: 1 } },
+      { id: "no-description", spawns_agent_runs: true },
+      { id: "no-boolean", description: "x", spawns_agent_runs: "yes" },
+      { id: "bad-guards", description: "x", spawns_agent_runs: true, guards: [] },
+      { id: "bad-guard-values", description: "x", spawns_agent_runs: true, guards: { dedup_key: " ", cooldown_seconds: 0, daily_cap: 1.5, max_concurrent: -1 } },
+      { id: "unknown-guard", description: "x", spawns_agent_runs: true, guards: { dedup_key: "sig", cooldown_seconds: 900, daily_cap: 20, max_concurrent: 1, burst: 5 } },
+      { id: "unknown-field", description: "x", spawns_agent_runs: true, command: "private-bypass" },
+    ],
+  }, "fixture/kit.json");
+
+  const errors = result.errors.join("\n");
+  assert.match(errors, /agent_spawn_triggers\[0\]\.id must match/);
+  assert.match(errors, /agent_spawn_triggers\[2\]\.id duplicates 'dup'/);
+  assert.match(errors, /agent_spawn_triggers\[3\]\.description must be a non-empty string/);
+  assert.match(errors, /agent_spawn_triggers\[4\]\.spawns_agent_runs must be a boolean/);
+  assert.match(errors, /agent_spawn_triggers\[5\]\.guards must be an object/);
+  assert.match(errors, /agent_spawn_triggers\[6\]\.guards\.dedup_key must be a non-empty string/);
+  assert.match(errors, /agent_spawn_triggers\[6\]\.guards\.cooldown_seconds must be an integer >= 1/);
+  assert.match(errors, /agent_spawn_triggers\[6\]\.guards\.daily_cap must be an integer >= 1/);
+  assert.match(errors, /agent_spawn_triggers\[6\]\.guards\.max_concurrent must be an integer >= 1/);
+  assert.match(errors, /agent_spawn_triggers\[7\]\.guards contains unsupported field\(s\): burst/);
+  assert.match(errors, /agent_spawn_triggers\[8\] contains unsupported field\(s\): command/);
+  // Malformed entries fail shape validation; only the first 'dup' entry (valid shape) parses.
+  assert.equal(result.entries.length, 1);
+  // Shape violations are errors, never demoted to the guard-completeness warning channel.
+  assert.deepEqual(result.warnings, []);
+});
+
+test("kit repository diagnostics carry the guardless-spawn warning and never leak it into errors", async () => {
+  const root = tempRoot("flow-agents-agent-spawn-trigger-repo-");
+  const kit = path.join(root, "builder");
+  fs.cpSync("kits/builder", kit, { recursive: true });
+  const manifestFile = path.join(kit, "kit.json");
+  const manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+  manifest.agent_spawn_triggers = [
+    { id: "on-check-failure", description: "Escalates failing checks to a headless agent run.", spawns_agent_runs: true },
+  ];
+  writeJson(manifestFile, manifest);
+
+  const diagnostics = await validateKitRepositoryDiagnostics(kit);
+  assert.deepEqual(diagnostics.errors, []);
+  assert.equal(diagnostics.warnings.length, 1);
+  assert.match(diagnostics.warnings[0], /spawns agent runs without complete guard config/);
+  // validateKitRepository keeps its errors-only contract: a warning is not an error.
+  assert.deepEqual(await validateKitRepository(kit), []);
+
+  // A fully guarded declaration is clean on both channels.
+  manifest.agent_spawn_triggers[0].guards = { dedup_key: "check-name+failure-signature", cooldown_seconds: 900, daily_cap: 20, max_concurrent: 1 };
+  writeJson(manifestFile, manifest);
+  const guarded = await validateKitRepositoryDiagnostics(kit);
+  assert.deepEqual(guarded.errors, []);
+  assert.deepEqual(guarded.warnings, []);
+
+  // agent_spawn_triggers is recognized Flow Agents metadata, not a third-party namespace.
+  const { deriveKitTargets } = await import("../../build/src/flow-kit/validate.js");
+  const targets = await deriveKitTargets(manifest, kit);
+  assert.deepEqual(targets.third_party_extensions, []);
+});
+
+test("kit install surfaces the guardless-spawn warning non-blockingly for BOTH source forms (local path and git URL)", async () => {
+  const { execFileSync } = await import("node:child_process");
+  const root = tempRoot("flow-agents-agent-spawn-trigger-install-");
+  const kitSource = path.join(root, "guarded-kit");
+  fs.mkdirSync(path.join(kitSource, "flows"), { recursive: true });
+  writeJson(path.join(kitSource, "kit.json"), {
+    schema_version: "1.0",
+    id: "guardless-demo",
+    name: "Guardless Demo Kit",
+    flows: [{ id: "demo.flow", path: "flows/demo.flow.json" }],
+    agent_spawn_triggers: [
+      { id: "on-check-failure", description: "Escalates failing checks to a headless agent run.", spawns_agent_runs: true },
+    ],
+  });
+  writeJson(path.join(kitSource, "flows", "demo.flow.json"), {
+    id: "demo.flow",
+    version: "1.0",
+    steps: [{ id: "only", next: null }],
+    gates: {},
+  });
+  const cli = path.resolve("build/src/cli.js");
+  const runInstall = (source, destName) => {
+    return execFileSync(process.execPath, [cli, "kit", "install", source, "--dest", path.join(root, destName)], { encoding: "utf8" });
+  };
+
+  // Local-path source form.
+  const localOut = runInstall(kitSource, "dest-local");
+  assert.match(localOut, /warning: .*agent_spawn_triggers\[0\] \('on-check-failure'\) spawns agent runs without complete guard config/);
+  assert.match(localOut, /installed local kit 'guardless-demo'/);
+
+  // Git-URL source form (file:// clone of the same kit).
+  const git = (args, cwd) => execFileSync("git", ["-c", "user.email=kit-test@example.invalid", "-c", "user.name=kit-test", ...args], { cwd, encoding: "utf8" });
+  git(["init", "--quiet"], kitSource);
+  git(["add", "-A"], kitSource);
+  git(["commit", "--quiet", "-m", "kit fixture"], kitSource);
+  const gitOut = runInstall(`file://${kitSource}`, "dest-git");
+  assert.match(gitOut, /warning: .*agent_spawn_triggers\[0\] \('on-check-failure'\) spawns agent runs without complete guard config/);
+  assert.match(gitOut, /installed git kit 'guardless-demo'/);
+});

package/src/cli/kit-provisioning.test.mjs

@@ -0,0 +1,122 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { validateKitRepository } from "../../build/src/flow-kit/validate.js";
+import { provisionKit, ProvisionConflictError } from "../../build/src/flow-kit/provision.js";
+
+const FLOW = {
+  id: "fixture.review",
+  version: "1.0",
+  steps: [{ id: "review", next: "done" }, { id: "done", next: null }],
+  gates: {},
+};
+
+function fixture(provisions) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "kit-provision-unit-"));
+  fs.mkdirSync(path.join(dir, "flows"));
+  fs.mkdirSync(path.join(dir, "payload"));
+  fs.writeFileSync(path.join(dir, "flows", "review.flow.json"), JSON.stringify(FLOW));
+  fs.writeFileSync(path.join(dir, "payload", "one.txt"), "one-new\n");
+  fs.writeFileSync(path.join(dir, "payload", "two.txt"), "two-new\n");
+  fs.writeFileSync(path.join(dir, "kit.json"), JSON.stringify({
+    schema_version: "1.0",
+    id: "fixture",
+    name: "Fixture",
+    flows: [{ id: "fixture.review", path: "flows/review.flow.json" }],
+    provisions,
+  }));
+  return dir;
+}
+
+const entry = (id, source, target) => ({ id: `fixture.${id}`, path: `payload/${source}`, target });
+
+test("provision validation rejects unsafe and duplicate normalized targets", async () => {
+  const cases = [
+    [[entry("one", "one.txt", "../escape.txt")], "traversal segments"],
+    [[entry("one", "one.txt", path.resolve("/tmp/escape.txt"))], "must be relative"],
+    [[entry("one", "one.txt", ".git/config")], "must not be inside .git"],
+    [[entry("one", "one.txt", ".GIT/hooks/pre-push")], "must not be inside .git"],
+    [[entry("one", "one.txt", "docs//same.txt"), entry("two", "two.txt", "docs/same.txt")], "target duplicates"],
+    [[entry("one", "one.txt", "README.md"), entry("two", "two.txt", "readme.md")], "target duplicates"],
+    [[entry("one", "one.txt", ".kontourai/flow-agents/provisions/fixture.json")], "provision manifest namespace"],
+    [[{ id: "fixture.one", path: "payload/../payload/one.txt", target: "out.txt" }], "must not contain traversal segments"],
+  ];
+  for (const [provisions, message] of cases) {
+    const errors = await validateKitRepository(fixture(provisions));
+    assert.equal(errors.some((error) => error.includes(message)), true, errors.join("\n"));
+  }
+});
+
+test("provision core preflights conflicts before writing and force overwrites", async () => {
+  const kit = fixture([entry("one", "one.txt", "docs/one.txt"), entry("two", "two.txt", "docs/two.txt")]);
+  const target = fs.mkdtempSync(path.join(os.tmpdir(), "kit-provision-target-"));
+  fs.mkdirSync(path.join(target, "docs"));
+  fs.writeFileSync(path.join(target, "docs", "two.txt"), "keep\n");
+
+  await assert.rejects(() => provisionKit(kit, target), (error) => error instanceof ProvisionConflictError && error.conflicts.length === 1);
+  assert.equal(fs.existsSync(path.join(target, "docs", "one.txt")), false);
+  assert.equal(fs.readFileSync(path.join(target, "docs", "two.txt"), "utf8"), "keep\n");
+
+  const result = await provisionKit(kit, target, { force: true });
+  assert.equal(fs.readFileSync(path.join(target, "docs", "one.txt"), "utf8"), "one-new\n");
+  assert.equal(fs.readFileSync(path.join(target, "docs", "two.txt"), "utf8"), "two-new\n");
+  const manifest = JSON.parse(fs.readFileSync(result.manifest_path, "utf8"));
+  assert.equal(manifest.schema_version, "1.0");
+  assert.equal(manifest.kit_id, "fixture");
+  assert.match(manifest.kit_hash, /^sha256:[a-f0-9]{64}$/);
+  assert.deepEqual(manifest.files, [{ id: "fixture.one", target: "docs/one.txt" }, { id: "fixture.two", target: "docs/two.txt" }]);
+});
+
+test("provision core dry-run writes neither files nor manifest", async () => {
+  const kit = fixture([entry("one", "one.txt", "docs/one.txt")]);
+  const target = fs.mkdtempSync(path.join(os.tmpdir(), "kit-provision-dry-"));
+  const result = await provisionKit(kit, target, { dryRun: true });
+  assert.equal(result.dry_run, true);
+  assert.equal(fs.existsSync(path.join(target, "docs", "one.txt")), false);
+  assert.equal(fs.existsSync(path.join(target, ".kontourai")), false);
+});
+
+test("provision core rejects destination paths whose existing ancestor escapes through a symlink", async () => {
+  const kit = fixture([entry("one", "one.txt", "linked/one.txt")]);
+  const target = fs.mkdtempSync(path.join(os.tmpdir(), "kit-provision-link-target-"));
+  const outside = fs.mkdtempSync(path.join(os.tmpdir(), "kit-provision-link-outside-"));
+  fs.symlinkSync(outside, path.join(target, "linked"), "dir");
+  await assert.rejects(() => provisionKit(kit, target), /escapes consumer repository/);
+  assert.equal(fs.existsSync(path.join(outside, "one.txt")), false);
+});
+
+test("provision rejects a source that resolves outside the kit through a symlink", async () => {
+  const kit = fixture([entry("host", "host.txt", "copied.txt")]);
+  const outside = fs.mkdtempSync(path.join(os.tmpdir(), "kit-provision-src-outside-"));
+  const secret = path.join(outside, "secret.txt");
+  fs.writeFileSync(secret, "off-kit-secret\n");
+  fs.symlinkSync(secret, path.join(kit, "payload", "host.txt"));
+
+  const errors = await validateKitRepository(kit);
+  assert.equal(errors.some((error) => error.includes("must not resolve outside the kit directory")), true, errors.join("\n"));
+
+  const target = fs.mkdtempSync(path.join(os.tmpdir(), "kit-provision-src-target-"));
+  await assert.rejects(() => provisionKit(kit, target), /escapes the kit directory|validation failed/);
+  assert.equal(fs.existsSync(path.join(target, "copied.txt")), false);
+});
+
+test("init activation provisions create-only and reports rerun conflicts without failing", () => {
+  const kit = fixture([entry("one", "one.txt", "docs/one.txt")]);
+  const target = fs.mkdtempSync(path.join(os.tmpdir(), "kit-provision-init-"));
+  const install = spawnSync(process.execPath, ["build/src/cli.js", "kit", "install", kit, "--dest", target], { encoding: "utf8" });
+  assert.equal(install.status, 0, `${install.stdout}\n${install.stderr}`);
+  const args = ["build/src/cli.js", "init", "--runtime", "codex", "--dest", target, "--telemetry-sink", "local-files", "--activate-kit", "fixture", "--yes"];
+  const first = spawnSync(process.execPath, args, { encoding: "utf8" });
+  assert.equal(first.status, 0, `${first.stdout}\n${first.stderr}`);
+  assert.equal(fs.readFileSync(path.join(target, "docs", "one.txt"), "utf8"), "one-new\n");
+
+  fs.writeFileSync(path.join(target, "docs", "one.txt"), "consumer-owned\n");
+  const second = spawnSync(process.execPath, args, { encoding: "utf8" });
+  assert.equal(second.status, 0, `${second.stdout}\n${second.stderr}`);
+  assert.match(`${second.stdout}\n${second.stderr}`, /skipped existing provision 'docs\/one.txt'/);
+  assert.equal(fs.readFileSync(path.join(target, "docs", "one.txt"), "utf8"), "consumer-owned\n");
+});

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;
 }