@kontourai/flow-agents 4.0.0 → 4.2.0

package/dist/codex/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/dist/codex/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/dist/kiro/agents/tool-security-reviewer.json

@@ -88,6 +88,6 @@
   ],
   "name": "tool-security-reviewer",
   "description": "Delegate to me for security analysis. Checks OWASP Top 10, secrets detection, input validation, injection vulnerabilities, auth/authz, and rate limiting. Read-only analysis with shell for scanning tools.",
-  "prompt": "You are a security reviewer. You analyze source code for vulnerabilities and produce a structured security report.\n\n## Input\nYou receive:\n- A list of files to review\n- Optional focus area (auth, input handling, DB, etc.)\n\n## Security Checklist\n\nFor each file, check:\n- **Hardcoded secrets**: API keys, tokens, passwords, connection strings, private keys\n- **SQL injection**: string concatenation in queries, missing parameterization\n- **XSS**: unescaped user input in HTML/templates, innerHTML usage\n- **CSRF**: missing CSRF tokens on state-changing endpoints\n- **Path traversal**: user input in file paths without sanitization\n- **Auth bypasses**: missing auth checks, broken access control, privilege escalation\n- **Rate limiting**: unprotected endpoints susceptible to abuse\n- **Error leakage**: stack traces, internal paths, or system info in error responses\n- **Dependency vulnerabilities**: run npm audit / pip-audit / cargo audit if available\n\n## OWASP Top 10 Mapping\n\nTag each finding with its OWASP category:\n- A01: Broken Access Control\n- A02: Cryptographic Failures\n- A03: Injection\n- A04: Insecure Design\n- A05: Security Misconfiguration\n- A06: Vulnerable Components\n- A07: Auth Failures\n- A08: Data Integrity Failures\n- A09: Logging Failures\n- A10: SSRF\n\n## Trigger Conditions\n\nPrioritize review of code involving:\n- Authentication or authorization logic\n- User input handling (forms, query params, headers)\n- Database queries\n- File system operations\n- External API calls\n- Cryptographic operations\n- Payment or financial code\n\n## Secret Patterns\n\nScan for common patterns:\n- `AKIA[0-9A-Z]{16}` (AWS access keys)\n- `-----BEGIN (RSA |EC )?PRIVATE KEY-----`\n- `(password|secret|token|api_key)\\s*[:=]\\s*['\"][^'\"]+['\"]`\n- Base64-encoded strings >40 chars in assignments\n\n## Output\n\nReturn a structured security report:\n```markdown\n## Security Review\n\nFiles analyzed: <count>\nFindings: <count by severity>\n\n### Findings\n\n#### [CRITICAL/HIGH/MEDIUM/LOW] <OWASP-ID> — <file>:<line> — <title>\n<description with evidence>\n**Remediation:** <specific fix>\n\n### Summary\n<overall assessment>\n```\n\n## Rules\n- No false positives without evidence. Show the vulnerable code.\n- Run dependency audit tools if available (npm audit, pip-audit, cargo audit).\n- If no security issues found, say so clearly — don't invent findings.\n- This is read-only analysis. Do not modify any files.",
+  "prompt": "You are a security reviewer. You analyze source code for vulnerabilities and produce a structured security report.\n\n## Input\nYou receive:\n- A list of files to review\n- Optional focus area (auth, input handling, DB, etc.)\n\n## Security Checklist\n\nFor each file, check:\n- **Hardcoded secrets**: API keys, tokens, passwords, connection strings, private keys\n- **SQL injection**: string concatenation in queries, missing parameterization\n- **XSS**: unescaped user input in HTML/templates, innerHTML usage\n- **CSRF**: missing CSRF tokens on state-changing endpoints\n- **Path traversal**: user input in file paths without sanitization\n- **Auth bypasses**: missing auth checks, broken access control, privilege escalation\n- **Rate limiting**: unprotected endpoints susceptible to abuse\n- **Error leakage**: stack traces, internal paths, or system info in error responses\n- **Dependency vulnerabilities**: run npm audit / pip-audit / cargo audit if available\n\n## OWASP Top 10 Mapping\n\nTag each finding with its OWASP category:\n- A01: Broken Access Control\n- A02: Cryptographic Failures\n- A03: Injection\n- A04: Insecure Design\n- A05: Security Misconfiguration\n- A06: Vulnerable Components\n- A07: Auth Failures\n- A08: Data Integrity Failures\n- A09: Logging Failures\n- A10: SSRF\n\n## Trigger Conditions\n\nPrioritize review of code involving:\n- Authentication or authorization logic\n- User input handling (forms, query params, headers)\n- Database queries\n- File system operations\n- External API calls\n- Cryptographic operations\n- Payment or financial code\n\n## Secret Patterns\n\nScan for common patterns:\n- `AKIA[0-9A-Z]{16}` (AWS access keys)\n- `-----BEGIN (RSA |EC )?PRIVATE KEY-----`\n- `(password|secret|token|api_key)\\s*[:=]\\s*['\"][^'\"]+['\"]`\n- Base64-encoded strings >40 chars in assignments\n\n## Output\n\nReturn a structured security report:\n```markdown\n## Security Review\n\nFiles analyzed: <count>\nFindings: <count by severity>\n\n### Findings\n\n#### [CRITICAL/HIGH/MEDIUM/LOW] <OWASP-ID> — <file>:<line> — <title>\n<description with evidence>\n**Remediation:** <specific fix>\n\n### Summary\n<overall assessment>\n```\n\n## Rules\n- No false positives without evidence: cite the exact `file:line` and a one-line description of the weakness as the evidence.\n- Do NOT reproduce exploit payloads, working attack strings, or large copied blocks of vulnerable code in the report. A precise `file:line` reference plus a short description IS the evidence — reproduction detail belongs in the fix pass, not the recorded finding. (This keeps security findings recordable through `workflow critique`, whose reviewer runtime's provider may content-filter exploit-shaped prose.)\n- Run dependency audit tools if available (npm audit, pip-audit, cargo audit).\n- If no security issues found, say so clearly — don't invent findings.\n- This is read-only analysis. Do not modify any files.",
   "model": "claude-sonnet-4.6-1m"
 }

package/dist/kiro/build/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "type": "module"
 }

package/dist/kiro/build/src/cli/init.js

@@ -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";
@@ -571,7 +572,21 @@ function installBundle(bundle, options) {
     }
     return result.status ?? 1;
 }
-function activateKits(options) {
+function kitPathForInit(kitId, dest) {
+    const catalogPath = path.join(root, "kits", "catalog.json");
+    if (fs.existsSync(catalogPath)) {
+        const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf8"));
+        const entry = Array.isArray(catalog.kits)
+            ? catalog.kits.find((item) => typeof item === "object" && item !== null && item.id === kitId)
+            : undefined;
+        const rel = entry && typeof entry === "object" ? entry.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) {
     const activeKitIds = options.activeKitIds ?? [];
     if (!options.activateKits || activeKitIds.length === 0 || options.runtime !== "codex")
         return 0;
@@ -582,6 +597,23 @@ function activateKits(options) {
     }
     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;
 }
 /**
@@ -809,7 +841,7 @@ export async function main(argv = process.argv.slice(2)) {
             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") {
@@ -822,7 +854,7 @@ export async function main(argv = process.argv.slice(2)) {
         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/dist/kiro/build/src/cli/kit.js

@@ -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,18 @@ function resolveCatalogKitSource(source) {
         return null;
     return path.resolve(path.dirname(repoCatalogPath), "..", rel);
 }
+function resolveProvisionKitSource(source, dest) {
+    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) {
     const file = registryPath(dest);
     if (!fs.existsSync(file))
@@ -64,6 +77,17 @@ function warnUninstalledDependencies(manifest, manifestPath, dest) {
         }
     }
 }
+/**
+ * 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) {
+    for (const warning of (await validateKitRepositoryDiagnostics(kitDir)).warnings)
+        console.log(`warning: ${warning}`);
+}
 function contentHash(root) {
     const hash = crypto.createHash("sha256");
     for (const file of walkFiles(root)) {
@@ -122,6 +146,7 @@ async function installLocalSource(source, argv) {
     let manifest;
     try {
         manifest = await assertKitRepository(source);
+        await printKitValidationWarnings(source);
     }
     catch (error) {
         console.log("Flow Kit repository validation failed:");
@@ -211,6 +236,7 @@ async function installGitSource(rawUrl, argv) {
         let manifest;
         try {
             manifest = await assertKitRepository(tmpBase);
+            await printKitValidationWarnings(tmpBase);
         }
         catch (error) {
             console.log("Flow Kit repository validation failed:");
@@ -321,6 +347,69 @@ function activate(argv) {
     console.log(JSON.stringify(result, null, 2));
     return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }
+async function validate(argv) {
+    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) {
+    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.diagnostics;
+        if (diagnostics?.length) {
+            console.error("Flow Kit repository validation failed:");
+            for (const diagnostic of diagnostics)
+                console.error(` - ${diagnostic}`);
+        }
+        else
+            console.error(`provision: ${error.message}`);
+        return 1;
+    }
+}
 /**
  * inspect <kit-dir> [--json]
  *
@@ -375,9 +464,13 @@ export async function main(argv = process.argv.slice(2)) {
         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;
 }
 // Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.

package/dist/kiro/build/src/cli/pull-work-provider.js

@@ -804,7 +804,13 @@ export function main(argv = process.argv.slice(2)) {
         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;
 }
 // Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.

package/dist/kiro/build/src/cli/validate-workflow-artifacts.js

@@ -18,6 +18,7 @@ const sidecarSchemas = {
     "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
@@ -386,11 +387,63 @@ function validateSidecar(file) {
                 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, value, issues) {
+    const waves = Array.isArray(value?.waves) ? value.waves : [];
+    waves.forEach((wave, index) => {
+        const loc = `waves.json.waves[${index}]`;
+        const expected = Array.isArray(wave?.expected_workers) ? wave.expected_workers : [];
+        const results = 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();
+        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));
+        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, status, records, issues) {
     records.forEach((record, index) => {
         const correction = record?.correction;

package/dist/kiro/build/src/cli/workflow.js

@@ -733,7 +733,11 @@ function assertDistinctReviewActor(sessionDir, slug) {
     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/dist/kiro/build/src/flow-kit/provision.d.ts

@@ -0,0 +1,23 @@
+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 declare class ProvisionConflictError extends Error {
+    readonly conflicts: ProvisionPlanEntry[];
+    constructor(conflicts: ProvisionPlanEntry[]);
+}
+export declare function provisionKit(kitDir: string, targetDir: string, options?: {
+    force?: boolean;
+    dryRun?: boolean;
+}): Promise<ProvisionResult>;

package/dist/kiro/build/src/flow-kit/provision.js

@@ -0,0 +1,99 @@
+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 } from "./validate.js";
+export class ProvisionConflictError extends Error {
+    conflicts;
+    constructor(conflicts) {
+        super(`provisioning conflicts with ${conflicts.length} existing destination(s)`);
+        this.name = "ProvisionConflictError";
+        this.conflicts = conflicts;
+    }
+}
+function kitContentHash(kitDir) {
+    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, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function assertSafeDestination(rootReal, destination) {
+    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) {
+    if (!Array.isArray(manifest.provisions))
+        return [];
+    return manifest.provisions.map((entry) => {
+        const record = entry;
+        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, targetDir, options = {}) {
+    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 };
+}