@kontourai/flow-agents 4.0.0 → 4.2.0

package/scripts/liveness/relay.sh

@@ -7,26 +7,36 @@
 # never forked). The Console side ingests this record type and projects the fleet view + runs the
 # janitor (console repo #125); this script is only the flow-agents EMIT half.
 #
-# STRICTLY OPTIONAL and local-first (ADR 0012 §5): a no-op unless FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
-# is enabled AND a console endpoint is configured. Best-effort throughout — it must NEVER block, slow,
-# or fail the local liveness write that already happened before this was invoked. Every failure path
-# is a quiet `exit 0`.
+# STRICTLY OPTIONAL and local-first (ADR 0012 §5): a no-op unless the liveness relay is enabled AND a
+# console endpoint is configured. Enablement is conf-driven (#567, parity with economics #469): an
+# operator sets `console_liveness_relay=1` in the console conf (or it defaults on once a console url
+# resolves) — NOT an env var. config.sh (sourced below) is the authoritative, trust-gated decision
+# and also supplies the endpoint/token/tenant from the conf. Best-effort throughout — it must NEVER
+# block, slow, or fail the local liveness write that already happened before this was invoked. Every
+# failure path is a quiet `exit 0`.
 #
 # Invoked (fully detached, best-effort) from scripts/hooks/lib/liveness-write.js after the durable
 # local append. Usage: relay.sh '<liveness-event-json>'
 set -uo pipefail
 
-# Opt-in gate — off by default.
-case "${FLOW_AGENTS_CONSOLE_LIVENESS_RELAY:-}" in
-  1 | true | TRUE | yes | on) ;;
-  *) exit 0 ;;
-esac
-
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" || exit 0
 
 # transport.sh sources ${TELEMETRY_DIR}/lib/redact.sh at load — point it at the telemetry lib dir,
 # then reuse the SAME console POST core the telemetry mirror uses.
 export TELEMETRY_DIR="${TELEMETRY_DIR:-$SCRIPT_DIR/../telemetry}"
+
+# Source config.sh FIRST (best-effort, like economics-record.sh) so the conf resolves enablement
+# (FLOW_AGENTS_CONSOLE_LIVENESS_RELAY) and the endpoint/token/tenant — trust-gated for default-path
+# confs. This is what makes conf-only operation work with NO env var set.
+# shellcheck source=/dev/null
+[[ -f "$TELEMETRY_DIR/lib/config.sh" ]] && source "$TELEMETRY_DIR/lib/config.sh" 2>/dev/null || true
+
+# Opt-in gate — off by default, now honoring the conf-derived value config.sh just resolved.
+case "${FLOW_AGENTS_CONSOLE_LIVENESS_RELAY:-}" in
+  1 | true | TRUE | yes | on) ;;
+  *) exit 0 ;;
+esac
+
 [[ -f "$TELEMETRY_DIR/lib/transport.sh" ]] || exit 0
 # shellcheck source=/dev/null
 source "$TELEMETRY_DIR/lib/transport.sh" 2>/dev/null || exit 0
@@ -73,7 +83,9 @@ record="$(printf '%s' "$event_json" | jq -c '{
   ttlSeconds: (.ttlSeconds // null),
   host: (.host // null),
   branch: (.branch // null),
-  artifact_dir: (.artifact_dir // .artifactDir // null)
+  artifact_dir: (.artifact_dir // .artifactDir // null),
+  source: (.source // null),
+  activity: (.activity // null)
 }' 2>/dev/null)" || exit 0
 [[ -z "$record" || "$record" == "null" ]] && exit 0
 

package/scripts/telemetry/lib/config.sh

@@ -109,6 +109,13 @@ FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL="${FLOW_AGENTS_CONSOLE_ECONOMICS_ENDP
 # Set (non-empty) only when the config file carries an explicit console_economics_relay key —
 # distinguishes "operator said 0/1" from "key absent" for the default-on rule below.
 console_economics_relay_raw=""
+# Liveness relay (#567): same conf-driven, opt-out-not-silent-off shape as economics (#469) so an
+# operator enables the hosted liveness mirror via console_liveness_relay=1 in the conf, NOT an env
+# var/.profile. A caller-pre-set env var is the starting point; the config key overrides it; absent
+# any key the default-on rule below turns it on once a console telemetry sink resolves.
+FLOW_AGENTS_CONSOLE_LIVENESS_RELAY="${FLOW_AGENTS_CONSOLE_LIVENESS_RELAY:-}"
+FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="${FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL:-}"
+console_liveness_relay_raw=""
 # Pricing registry source (consumed by lib/pricing.sh). Explicit file/URL win;
 # otherwise lib/pricing.sh uses the bundled pricing.json offline.
 TELEMETRY_PRICING_FILE="${TELEMETRY_PRICING_FILE:-${FLOW_AGENTS_PRICING_FILE:-}}"
@@ -164,6 +171,17 @@ if [[ -f "$TELEMETRY_CONFIG_FILE" ]]; then
           esac
           ;;
         console_economics_endpoint_url) FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL="$value" ;;
+        console_liveness_relay)
+          case "$(echo "$value" | tr '[:upper:]' '[:lower:]')" in
+            1|true|yes|on) console_liveness_relay_raw="1" ;;
+            0|false|no|off) console_liveness_relay_raw="0" ;;
+            *)
+              printf 'warning: config.sh: unrecognized console_liveness_relay value %q; treating as off\n' "$value" >&2
+              console_liveness_relay_raw="$value"
+              ;;
+          esac
+          ;;
+        console_liveness_endpoint_url) FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$value" ;;
         console_pricing_url) TELEMETRY_PRICING_URL="$value" ;;
         pricing_url) TELEMETRY_PRICING_URL="$value" ;;
         pricing_file) TELEMETRY_PRICING_FILE="$value" ;;
@@ -186,6 +204,17 @@ elif [[ -z "$FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY" \
   FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY=1
 fi
 
+# Liveness relay default-on rule (#567), identical shape to economics above: an explicit
+# console_liveness_relay config key always wins; otherwise, once a console telemetry sink resolves,
+# the relay defaults ON unless a caller already pre-set FLOW_AGENTS_CONSOLE_LIVENESS_RELAY in the
+# environment. relay.sh's own opt-in gate reads this exact variable.
+if [[ -n "$console_liveness_relay_raw" ]]; then
+  FLOW_AGENTS_CONSOLE_LIVENESS_RELAY="$console_liveness_relay_raw"
+elif [[ -z "$FLOW_AGENTS_CONSOLE_LIVENESS_RELAY" \
+      && ( -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_TELEMETRY_ENDPOINT_URL:-}" ) ]]; then
+  FLOW_AGENTS_CONSOLE_LIVENESS_RELAY=1
+fi
+
 # Pricing URL is explicit-only (env or config). Do not derive the console
 # pricing endpoint by default; the bundled registry is the reliable offline floor.
 

package/src/cli/builder-flow-runtime.test.mjs

@@ -1860,6 +1860,92 @@ test("publish-change reports an external capability gap and self-authored result
   await releaseBuilderFlowAssignment({ sessionDir: session.sessionDir, reason: `test cleanup for ${ambient.actorKey}` });
 });
 
+async function advanceSessionToPrOpen(session) {
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const steps = [
+    () => [bundleClaim({ expectation: "selected-work", claimType: "builder.pull-work.selected", subjectType: "work-item" })],
+    () => [
+      bundleClaim({ expectation: "pickup-probe-readiness", claimType: "builder.design-probe.pickup-readiness", subjectType: "work-item" }),
+      bundleClaim({ expectation: "probe-decisions-or-accepted-gaps", claimType: "builder.design-probe.decisions", subjectType: "decision" }),
+    ],
+    () => [bundleClaim({ expectation: "implementation-plan", claimType: "builder.plan.implementation", subjectType: "artifact" })],
+    () => [bundleClaim({ expectation: "implementation-scope", claimType: "builder.execute.scope", subjectType: "change" })],
+    () => [bundleClaim({ expectation: "tests-evidence", claimType: "builder.verify.tests", subjectType: "flow-step" }), ...verifiedTestsPrerequisites(session)],
+    () => [bundleClaim({ expectation: "merge-readiness", claimType: "builder.merge-ready.readiness", subjectType: "change" })],
+  ];
+  let latest = null;
+  for (const entries of steps) latest = await writeAndSync(session, entries());
+  assert.equal(latest.run.state.current_step, "pr-open");
+  return latest;
+}
+
+test("pr-open route-back with missing_evidence returns the run to verify and supports repair re-entry (#695 item a)", async () => {
+  const session = makeSession("propen-routeback");
+  await advanceSessionToPrOpen(session);
+
+  // The #663 wedge scenario: a trust divergence is discovered at pr-open. A failing
+  // pull-request-opened claim declaring the missing_evidence route reason must land
+  // the canonical run back at verify — the sanctioned repair surface — not throw.
+  const failureTimestamp = new Date().toISOString();
+  const routed = await writeAndSync(session, [bundleClaim({
+    expectation: "pull-request-opened",
+    claimType: "builder.pr-open.pull-request",
+    subjectType: "pull-request",
+    status: "fail",
+    routeReason: "missing_evidence",
+    timestamp: failureTimestamp,
+  })]);
+
+  assert.equal(routed.attached, true);
+  assert.equal(routed.run.state.current_step, "verify");
+  const routeBacks = routed.run.state.transitions.filter((transition) => transition.type === "route_back");
+  assert.equal(routeBacks.length, 1);
+  assert.equal(routeBacks[0].from_step, "pr-open");
+  assert.equal(routeBacks[0].to_step, "verify");
+  assert.equal(routeBacks[0].route_reason, "missing_evidence");
+  assert.equal(routeBacks[0].gate_id, "builder.publish-learn:pr-open-gate");
+  assert.equal(routed.projection.flow_run.route_back_attempt, 1);
+  assert.equal(routed.projection.flow_run.route_back_max_attempts, 3);
+  assert.match(routed.projection.next_action.summary, /Route-back history: attempt 1\/3 returned to `verify` for `missing_evidence`/);
+
+  // Repair loop: fresh verify evidence re-passes verify, fresh merge-readiness
+  // re-passes merge-ready, and the run returns to pr-open.
+  const repairedAt = new Date(Date.parse(routed.run.state.transitions.at(-1).at) + 1).toISOString();
+  const reverified = await writeAndSync(session, [
+    withIdentitySuffix(bundleClaim({ expectation: "tests-evidence", claimType: "builder.verify.tests", subjectType: "flow-step", timestamp: repairedAt }), "repair"),
+    ...verifiedTestsPrerequisites(session, repairedAt).map((entry, index) => withIdentitySuffix(entry, `repair-${index}`)),
+  ]);
+  assert.equal(reverified.run.state.current_step, "merge-ready");
+  const returned = await writeAndSync(session, [
+    withIdentitySuffix(bundleClaim({ expectation: "merge-readiness", claimType: "builder.merge-ready.readiness", subjectType: "change", timestamp: new Date().toISOString() }), "repair"),
+  ]);
+  assert.equal(returned.run.state.current_step, "pr-open");
+});
+
+test("pr-open route-back with an undeclared reason still throws and mutates nothing", async () => {
+  const session = makeSession("propen-undeclared-reason");
+  await advanceSessionToPrOpen(session);
+
+  const flowDirectory = runDir(session.slug, session.projectRoot);
+  const beforeState = readJson(path.join(flowDirectory, "state.json"));
+  const beforeManifest = readJson(path.join(flowDirectory, FLOW_RUN_EVIDENCE_MANIFEST_PATH));
+
+  writeBundle(session.sessionDir, [bundleClaim({
+    expectation: "pull-request-opened",
+    claimType: "builder.pr-open.pull-request",
+    subjectType: "pull-request",
+    status: "fail",
+    routeReason: "stale_critique",
+    timestamp: new Date().toISOString(),
+  })]);
+  await assert.rejects(
+    () => syncBuilderFlowSession({ sessionDir: session.sessionDir }),
+    /route_reason.*is not declared by gate builder\.publish-learn:pr-open-gate/,
+  );
+  assert.deepEqual(readJson(path.join(flowDirectory, "state.json")), beforeState);
+  assert.deepEqual(readJson(path.join(flowDirectory, FLOW_RUN_EVIDENCE_MANIFEST_PATH)), beforeManifest);
+});
+
 test("recovery loads the slug-bound run, restores every matching projection, and preserves every Flow byte", async () => {
   const session = makeSession("recover-active");
   await startBuilderFlowSession({ sessionDir: session.sessionDir });

package/src/cli/flow-resolver-composition.test.mjs

@@ -4,7 +4,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { resolveEffectiveFlowDefinition, resolveFlowFilePath } from "../../build/src/lib/flow-resolver.js";
+import { validateDefinition } from "@kontourai/flow";
+
+import { resolveEffectiveFlowDefinition, resolveFlowFilePath, resolveFlowStep } from "../../build/src/lib/flow-resolver.js";
 
 const REPO_ROOT = path.resolve(import.meta.dirname, "../..");
 
@@ -26,6 +28,23 @@ test("effective Builder definition materializes uses_flow and Flow-native comple
   );
 });
 
+test("composed pr-open-gate declares the missing_evidence repair route to verify (#695 item a)", () => {
+  const definition = resolveEffectiveFlowDefinition("builder.build", REPO_ROOT);
+  assert.ok(definition);
+  const gate = definition.gates["builder.publish-learn:pr-open-gate"];
+  assert.deepEqual(gate.on_route_back, { missing_evidence: "verify", default: "verify" });
+  assert.deepEqual(gate.route_back_policy, { max_attempts: 3, on_exceeded: "block" });
+  // Every declared route-back target must exist in the EFFECTIVE step set — the
+  // composed definition (where `verify` lives) must stay a valid Flow definition.
+  assert.doesNotThrow(() => validateDefinition(definition));
+  // The live resolver surfaces the declared reasons at the composed step, which is
+  // what record-gate-claim's --route-reason validation reads.
+  const step = resolveFlowStep("builder.build", "pr-open", REPO_ROOT);
+  assert.ok(step);
+  assert.equal(step.gateId, "builder.publish-learn:pr-open-gate");
+  assert.deepEqual([...step.routeBackReasons].sort(), ["default", "missing_evidence"]);
+});
+
 test("installed package definitions resolve when a consumer repo has no kits directory", () => {
   const consumer = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-consumer-"));
   const resolved = resolveFlowFilePath("builder", "build", "builder.build", consumer, false);

package/src/cli/init.ts

@@ -8,6 +8,7 @@ import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
 import { activateCodexLocal } from "../runtime-adapters.js";
+import { provisionKit, ProvisionConflictError } from "../flow-kit/provision.js";
 import { main as buildBundles } from "../tools/build-universal-bundles.js";
 import { root } from "../tools/common.js";
 import { defaultCodexHome, durableInstallRecordPath, skillsManifestPath } from "../lib/local-artifact-root.js";
@@ -640,7 +641,21 @@ function installBundle(bundle: string, options: InitOptions): number {
   return result.status ?? 1;
 }
 
-function activateKits(options: InitOptions): number {
+function kitPathForInit(kitId: string, dest: string): string | null {
+  const catalogPath = path.join(root, "kits", "catalog.json");
+  if (fs.existsSync(catalogPath)) {
+    const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf8")) as { kits?: unknown[] };
+    const entry = Array.isArray(catalog.kits)
+      ? catalog.kits.find((item) => typeof item === "object" && item !== null && (item as Record<string, unknown>).id === kitId)
+      : undefined;
+    const rel = entry && typeof entry === "object" ? (entry as Record<string, unknown>).path : undefined;
+    if (typeof rel === "string") return path.resolve(root, rel);
+  }
+  const installed = path.join(dest, "kits", "local", "repositories", kitId);
+  return fs.existsSync(installed) ? installed : null;
+}
+
+async function activateKits(options: InitOptions): Promise<number> {
   const activeKitIds = options.activeKitIds ?? [];
   if (!options.activateKits || activeKitIds.length === 0 || options.runtime !== "codex") return 0;
   const result = activateCodexLocal(options.dest, options.dest, { kitIdFilter: activeKitIds });
@@ -650,6 +665,19 @@ function activateKits(options: InitOptions): number {
   }
   const generated = Array.isArray(result.generated_runtime_files) ? result.generated_runtime_files : [];
   console.log(`Activated ${generated.length} Codex local runtime asset(s)`);
+  for (const kitId of activeKitIds) {
+    const kitDir = kitPathForInit(kitId, options.dest);
+    if (!kitDir) throw new Error(`activated kit '${kitId}' could not be resolved for provisioning`);
+    try {
+      const provisioned = await provisionKit(kitDir, options.dest);
+      if (provisioned.files.length > 0) console.log(`Provisioned ${provisioned.files.length} file(s) from kit '${kitId}'`);
+    } catch (error) {
+      if (!(error instanceof ProvisionConflictError)) throw error;
+      for (const conflict of error.conflicts) {
+        console.warn(`flow-agents init: warning: skipped existing provision '${conflict.target}' from kit '${kitId}'`);
+      }
+    }
+  }
   return 0;
 }
 
@@ -867,7 +895,7 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
       const installed = result.status ?? 1;
       if (installed !== 0) return installed;
       writeInstallRecord(options.dest, "codex", true, options.activeKitIds ?? []);
-      return activateKits(options);
+      return await activateKits(options);
     }
     // --global for pi: NOT_VERIFIED (no documented global dir). Warn and fall through to workspace install.
     if (options.global && options.runtime === "pi") {
@@ -881,7 +909,7 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
     const installed = installBundle(bundle, options);
     if (installed !== 0) return installed;
     writeInstallRecord(options.dest, options.runtime, options.global, options.activeKitIds ?? []);
-    const activated = activateKits(options);
+    const activated = await activateKits(options);
     // G2/G3: shared post-install auto-verify + summary tail. Applies
     // identically whether main() reached here via headlessOptions() or
     // interactiveOptions() -- never changes `activated`'s exit code.

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);
@@ -908,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");
+});