@kontourai/flow-agents 3.12.1 → 4.1.0

package/dist/codex/build/src/builder-gate-action-envelope.js

@@ -4,9 +4,9 @@ import * as path from "node:path";
 import { createHash } from "node:crypto";
 import { evaluateGate, expectationsForGate, openGates } from "@kontourai/flow";
 import { parseKitFlowStepActions } from "./flow-kit/validate.js";
-import { PUBLIC_OPERATION_CONTRACTS, WORKFLOW_CRITIQUE_STATUSES } from "./cli/public-contracts.js";
+import { EVIDENCE_REF_JSON_SCHEMA, PUBLIC_OPERATION_CONTRACTS, WORKFLOW_CRITIQUE_PARAMETERS, WORKFLOW_EVIDENCE_PARAMETERS, } from "./cli/public-contracts.js";
+import { resolveEffectiveFlowDefinition } from "./lib/flow-resolver.js";
 import { flowAgentsPackageRoot } from "./lib/package-version.js";
-import { pinnedFlowAgentsCommand } from "./lib/pinned-cli-command.js";
 const MAX_METADATA_BYTES = 1_048_576;
 const MAX_ENVELOPE_BYTES = 65_536;
 const MAX_SKILLS = 16;
@@ -16,6 +16,96 @@ const MAX_CANONICAL_EVIDENCE = 256;
 const MAX_OBSERVED_ARTIFACTS = 128;
 const MAX_OBSERVED_ARTIFACT_BYTES = 8 * 1_048_576;
 const CONTROL_ARTIFACTS = new Set(["state.json"]);
+export { EVIDENCE_REF_JSON_SCHEMA } from "./cli/public-contracts.js";
+export function installedBuilderSkillIdentity(skill) {
+    const packageRoot = flowAgentsPackageRoot();
+    const packageMetadata = readBoundedJson(packageRoot, "package.json", "flow-agents package metadata");
+    if (typeof packageMetadata.version !== "string" || !packageMetadata.version)
+        throw new Error("flow-agents package metadata has no version");
+    const kit = readBoundedJson(packageRoot, path.join("kits", "builder", "kit.json"), "Builder kit metadata");
+    return skillIdentity(kit, packageRoot, packageMetadata.version, skill);
+}
+export function installedBuilderImplementationAllowed(definitionId, currentStep) {
+    const packageRoot = flowAgentsPackageRoot();
+    const kit = readBoundedJson(packageRoot, path.join("kits", "builder", "kit.json"), "Builder kit metadata");
+    const parsed = parseKitFlowStepActions(kit, "kits/builder/kit.json");
+    if (parsed.errors.length)
+        throw new Error(`Builder gate-action metadata is invalid: ${parsed.errors.join("; ")}`);
+    const selected = parsed.entries.filter((entry) => entry.flow_id === definitionId && entry.step_id === currentStep);
+    if (selected.length !== 1)
+        throw new Error(`Builder gate-action metadata must declare exactly one action for ${definitionId}/${currentStep}`);
+    return selected[0].implementation_allowed;
+}
+export function installedBuilderGateActionAuthority(definitionId, currentStep, runId) {
+    const packageRoot = flowAgentsPackageRoot();
+    const packageMetadata = readBoundedJson(packageRoot, "package.json", "flow-agents package metadata");
+    if (typeof packageMetadata.version !== "string" || !packageMetadata.version)
+        throw new Error("flow-agents package metadata has no version");
+    const packageVersion = packageMetadata.version;
+    const kit = readBoundedJson(packageRoot, path.join("kits", "builder", "kit.json"), "Builder kit metadata");
+    const parsed = parseKitFlowStepActions(kit, "kits/builder/kit.json");
+    if (parsed.errors.length)
+        throw new Error(`Builder gate-action metadata is invalid: ${parsed.errors.join("; ")}`);
+    const selected = parsed.entries.filter((entry) => entry.flow_id === definitionId && entry.step_id === currentStep);
+    if (selected.length !== 1)
+        throw new Error(`Builder gate-action metadata must declare exactly one action for ${definitionId}/${currentStep}`);
+    const action = selected[0];
+    const definition = resolveEffectiveFlowDefinition(definitionId, packageRoot, { allowOverride: false });
+    if (typeof definition?.version !== "string" || definition.version.length === 0) {
+        throw new Error(`Installed Builder Flow has no version for ${definitionId}`);
+    }
+    const gates = isRecord(definition?.gates) ? Object.entries(definition.gates)
+        .flatMap(([gateId, gate]) => isRecord(gate) && gate.step === currentStep ? [[gateId, gate]] : []) : [];
+    if (gates.length !== 1)
+        throw new Error(`Installed Builder Flow must declare exactly one gate for ${definitionId}/${currentStep}`);
+    const [gateId, gate] = gates[0];
+    const expects = Array.isArray(gate.expects) ? gate.expects : [];
+    const requirements = expects.map((expectation) => {
+        if (!isRecord(expectation))
+            throw new Error("Installed Builder gate expectation is malformed");
+        const requirement = requirementFromExpectation(gateId, expectation, new Set(), false);
+        const { status: _status, ...shape } = requirement;
+        return shape;
+    });
+    if (!sameSet(action.expectation_ids, requirements.map((requirement) => requirement.id))) {
+        throw new Error(`Installed Builder action evidence does not match ${definitionId}/${currentStep}`);
+    }
+    const sessionArgument = `.kontourai/flow-agents/${runId}`;
+    const declaredArtifacts = action.artifacts.filter((artifact) => !isControlArtifact(artifact))
+        .map((artifact) => artifactTarget(artifact, runId, sessionArgument, action));
+    const artifactBindings = action.artifact_bindings
+        .filter((binding) => !isControlArtifact(binding.artifact))
+        .map((binding) => ({
+        target: artifactTarget(binding.artifact, runId, sessionArgument, action),
+        expectation_ids: [...binding.expectation_ids],
+    }));
+    const operation = action.operations[0];
+    const protocol = operation ? PUBLIC_OPERATION_CONTRACTS[operation] : undefined;
+    const actionEnvelope = {
+        skills: action.skills.map((skill) => skillIdentity(kit, packageRoot, packageVersion, skill)),
+        operations: [...action.operations],
+        declared_artifacts: declaredArtifacts,
+        artifact_bindings: artifactBindings,
+        declared_evidence: [...action.expectation_ids],
+        implementation_allowed: action.implementation_allowed,
+    };
+    return {
+        definition_version: definition.version,
+        gate_id: gateId,
+        requirements,
+        action: actionEnvelope,
+        mutations: action.expectation_bindings.map((binding) => publicMutation(binding, sessionArgument, packageVersion)),
+        artifact_bindings: artifactBindings,
+        ...(protocol?.availability.status === "external_capability_required" ? {
+            external_capability: {
+                status: "waiting",
+                operation: protocol.operation,
+                capability: protocol.capability,
+                completion: "external_verification_required",
+            },
+        } : {}),
+    };
+}
 /** Derive bounded adapter context without trusting adapter telemetry. */
 export function deriveBuilderGateActionEnvelope(input) {
     const loaded = loadGateAction(input);
@@ -86,12 +176,11 @@ function assembleGateActionEnvelope(input, loaded, derived) {
     const { gates, requirements, unresolved, unresolvedRequired, acceptedExceptions } = derived;
     const sessionDir = path.resolve(input.sessionDir);
     const sessionArgument = sessionPathForPublicCommand(input.projectRoot, sessionDir);
-    const statusCommand = pinnedFlowAgentsCommand(packageVersion, ["workflow", "status", "--session-dir", sessionArgument, "--json"]);
     const requiredArtifacts = action.artifact_bindings
         .filter((binding) => !isControlArtifact(binding.artifact) && binding.expectation_ids.some((id) => unresolvedRequired.includes(id)))
-        .map((binding) => binding.artifact);
+        .map((binding) => artifactTarget(binding.artifact, sessionDir, sessionArgument, action));
     const envelope = {
-        schema_version: "2.0",
+        schema_version: "3.0",
         flow: {
             run_id: input.run.runId,
             definition_id: input.run.definitionId,
@@ -101,9 +190,14 @@ function assembleGateActionEnvelope(input, loaded, derived) {
             gate_ids: gates.map((gate) => gate.id),
         },
         gate: { requirements, unresolved_requirement_ids: unresolved, accepted_exceptions: acceptedExceptions },
-        action: envelopeAction(action, actionableArtifacts, kit, packageRoot, packageVersion),
+        action: envelopeAction(action, actionableArtifacts, sessionDir, sessionArgument, kit, packageRoot, packageVersion),
         public_interfaces: {
-            status: { command: statusCommand },
+            status: {
+                package: { name: "@kontourai/flow-agents", version: packageVersion },
+                command: "flow-agents",
+                argv: ["workflow", "status", "--session-dir", sessionArgument, "--json"],
+            },
+            schemas: { evidence_ref_json: structuredClone(EVIDENCE_REF_JSON_SCHEMA) },
             mutations: action.expectation_bindings.map((binding) => publicMutation(binding, sessionArgument, packageVersion)),
         },
         stop_condition: envelopeStopCondition(input, gates, action, requiredArtifacts, unresolvedRequired),
@@ -114,11 +208,18 @@ function assembleGateActionEnvelope(input, loaded, derived) {
     };
     return envelope;
 }
-function envelopeAction(action, artifacts, kit, packageRoot, packageVersion) {
+function envelopeAction(action, artifacts, sessionDir, sessionArgument, kit, packageRoot, packageVersion) {
+    const declaredArtifacts = artifacts.map((artifact) => artifactTarget(artifact, sessionDir, sessionArgument, action));
     return {
         skills: action.skills.map((skill) => skillIdentity(kit, packageRoot, packageVersion, skill)),
         operations: [...action.operations],
-        declared_artifacts: [...artifacts],
+        declared_artifacts: declaredArtifacts,
+        artifact_bindings: action.artifact_bindings
+            .filter((binding) => !isControlArtifact(binding.artifact))
+            .map((binding) => ({
+            target: artifactTarget(binding.artifact, sessionDir, sessionArgument, action),
+            expectation_ids: [...binding.expectation_ids],
+        })),
         declared_evidence: [...action.expectation_ids],
         implementation_allowed: action.implementation_allowed,
     };
@@ -183,15 +284,7 @@ function publicMutation(binding, sessionArgument, packageVersion) {
             package: { name: "@kontourai/flow-agents", version: packageVersion },
             command: "flow-agents",
             argv: ["workflow", "critique", "--session-dir", sessionArgument, "--json"],
-            parameters: [
-                { name: "id", flag: "--id", required: false },
-                { name: "verdict", flag: "--verdict", required: true, allowed_values: [...WORKFLOW_CRITIQUE_STATUSES] },
-                { name: "summary", flag: "--summary", required: true },
-                { name: "lane_json", flag: "--lane-json", required: true, repeatable: true },
-                { name: "artifact_ref", flag: "--artifact-ref", required: false, repeatable: true, required_when: { parameter: "verdict", equals: "pass" } },
-                { name: "finding_json", flag: "--finding-json", required: false, repeatable: true },
-                { name: "timestamp", flag: "--timestamp", required: false },
-            ],
+            parameters: structuredClone(WORKFLOW_CRITIQUE_PARAMETERS),
         };
     }
     return workflowEvidenceMutation(binding.expectation_id, sessionArgument, packageVersion);
@@ -203,16 +296,55 @@ function workflowEvidenceMutation(expectationId, sessionArgument, packageVersion
         package: { name: "@kontourai/flow-agents", version: packageVersion },
         command: "flow-agents",
         argv: ["workflow", "evidence", "--session-dir", sessionArgument, "--expectation", expectationId, "--json"],
-        parameters: [
-            { name: "status", flag: "--status", required: true, allowed_values: ["pass", "fail", "not_verified"] },
-            { name: "summary", flag: "--summary", required: true },
-            { name: "evidence_ref_json", flag: "--evidence-ref-json", required: true, repeatable: true },
-            { name: "route_reason", flag: "--route-reason", required: false },
-            { name: "criterion_json", flag: "--criterion-json", required: false, repeatable: true },
-            { name: "accepted_gap_reason", flag: "--accepted-gap-reason", required: false },
-            { name: "waived_by", flag: "--waived-by", required: false },
-            { name: "command", flag: "--command", required: false, repeatable: true },
-        ],
+        parameters: structuredClone(WORKFLOW_EVIDENCE_PARAMETERS),
+    };
+}
+function artifactTarget(artifact, sessionDir, sessionArgument, action) {
+    if (!artifact.includes("#")) {
+        const fileName = artifact.replaceAll("<slug>", path.basename(sessionDir));
+        const expectationIds = new Set(action.artifact_bindings
+            .filter((binding) => binding.artifact === artifact)
+            .flatMap((binding) => binding.expectation_ids));
+        const operations = action.expectation_bindings
+            .filter((binding) => expectationIds.has(binding.expectation_id) && binding.interface === "operation")
+            .flatMap((binding) => binding.operation ? [binding.operation] : []);
+        if (operations.length > 0) {
+            return {
+                kind: "file",
+                ref: artifact,
+                path: path.join(sessionArgument, fileName).split(path.sep).join("/"),
+                direct_write_allowed: false,
+                produced_via: { interface: "operation", operations: [...new Set(operations)] },
+            };
+        }
+        if (action.skills.length === 0)
+            throw new Error(`Builder gate-action file '${artifact}' has no skill or operation producer`);
+        return {
+            kind: "file",
+            ref: artifact,
+            path: path.join(sessionArgument, fileName).split(path.sep).join("/"),
+            direct_write_allowed: true,
+            produced_via: { interface: "skill", skill_ids: [...action.skills] },
+        };
+    }
+    const match = /^trust\.bundle#([a-z0-9]+(?:[.-][a-z0-9]+)*)$/.exec(artifact);
+    if (!match)
+        throw new Error(`Builder gate-action artifact '${artifact}' is not a supported trust slice`);
+    const expectationIds = new Set(action.artifact_bindings
+        .filter((binding) => binding.artifact === artifact)
+        .flatMap((binding) => binding.expectation_ids));
+    const recordVia = [...new Set(action.expectation_bindings
+            .filter((binding) => expectationIds.has(binding.expectation_id))
+            .flatMap((binding) => binding.interface === "workflow.evidence" || binding.interface === "workflow.critique" ? [binding.interface] : []))];
+    if (recordVia.length === 0)
+        throw new Error(`Builder gate-action trust slice '${artifact}' has no public recording interface`);
+    return {
+        kind: "trust_slice",
+        ref: artifact,
+        bundle_file: "trust.bundle",
+        slice_id: match[1],
+        direct_write_allowed: false,
+        record_via: recordVia,
     };
 }
 function requirementFromExpectation(gateId, expectation, satisfied, acceptedException) {

package/dist/codex/build/src/builder-lifecycle-authority.d.ts

@@ -29,6 +29,32 @@ export declare function loadBuilderLifecycleAuthorization(fileInput: string, exp
     allowExpired?: boolean;
 }): BuilderLifecycleAuthorization;
 export declare function builderLifecycleAuthorizationPayload(value: Omit<BuilderLifecycleAuthorization, "signature">): string;
+/**
+ * Build the canonical UNSIGNED authorization for a lifecycle operation, plus the
+ * exact bytes an operator must sign (#659 Slice C — "friendly cancel").
+ *
+ * The whole point is signing-payload parity: `verifyAuthorizationSignature`
+ * recomputes the signed bytes from the *loaded* authorization, after normalizing
+ * `assignment_actor`/`request` through `validateActor`/`validateRequest` and
+ * re-assembling the top-level keys in a fixed order. So we build the unsigned
+ * object here through the *same* validators and the *same* key order, and derive
+ * `signingPayload` from it — guaranteeing that a signature produced over
+ * `signingPayload` will verify. (The validators are idempotent, so re-running
+ * them on this already-canonical object at load time yields identical bytes.)
+ */
+export declare function buildUnsignedLifecycleAuthorization(fields: {
+    operation: AuthorizedBuilderLifecycleOperation;
+    run_id: string;
+    subject: string;
+    assignment_actor_key: string;
+    assignment_actor: unknown;
+    nonce: string;
+    expires_at: string;
+    request: unknown;
+}): {
+    unsigned: Omit<BuilderLifecycleAuthorization, "signature">;
+    signingPayload: string;
+};
 export declare function assertAuthorizationUnused(artifactRoot: string, authorization: BuilderLifecycleAuthorization): void;
 export declare function readAuthorizationConsumption(artifactRoot: string, authorization: BuilderLifecycleAuthorization): JsonRecord | null;
 export declare function recordAuthorizationConsumed(artifactRoot: string, authorization: BuilderLifecycleAuthorization, at?: string): void;

package/dist/codex/build/src/builder-lifecycle-authority.js

@@ -45,6 +45,44 @@ export function loadBuilderLifecycleAuthorization(fileInput, expected) {
 export function builderLifecycleAuthorizationPayload(value) {
     return JSON.stringify(value);
 }
+/**
+ * Build the canonical UNSIGNED authorization for a lifecycle operation, plus the
+ * exact bytes an operator must sign (#659 Slice C — "friendly cancel").
+ *
+ * The whole point is signing-payload parity: `verifyAuthorizationSignature`
+ * recomputes the signed bytes from the *loaded* authorization, after normalizing
+ * `assignment_actor`/`request` through `validateActor`/`validateRequest` and
+ * re-assembling the top-level keys in a fixed order. So we build the unsigned
+ * object here through the *same* validators and the *same* key order, and derive
+ * `signingPayload` from it — guaranteeing that a signature produced over
+ * `signingPayload` will verify. (The validators are idempotent, so re-running
+ * them on this already-canonical object at load time yields identical bytes.)
+ */
+export function buildUnsignedLifecycleAuthorization(fields) {
+    boundedText(fields.run_id, "run_id", 256);
+    boundedText(fields.subject, "subject", 2048);
+    boundedText(fields.assignment_actor_key, "assignment_actor_key", 256);
+    boundedText(fields.nonce, "nonce", 256);
+    const assignment_actor = validateActor(fields.assignment_actor);
+    const request = validateRequest(fields.request);
+    const expiresAt = dateTime(fields.expires_at, "expires_at");
+    const requestedAt = Date.parse(request.authority.requested_at);
+    if (expiresAt < requestedAt) {
+        throw new Error("lifecycle authorization expires_at must not precede request.authority.requested_at");
+    }
+    const unsigned = {
+        schema_version: "1.0",
+        operation: fields.operation,
+        run_id: fields.run_id,
+        subject: fields.subject,
+        assignment_actor_key: fields.assignment_actor_key,
+        assignment_actor,
+        nonce: fields.nonce,
+        expires_at: fields.expires_at,
+        request,
+    };
+    return { unsigned, signingPayload: builderLifecycleAuthorizationPayload(unsigned) };
+}
 export function assertAuthorizationUnused(artifactRoot, authorization) {
     if (!readAuthorizationConsumption(artifactRoot, authorization))
         return;

package/dist/codex/build/src/cli/builder-run.js

@@ -1,6 +1,66 @@
+import * as fs from "node:fs";
 import { flagString, parseArgs } from "../lib/args.js";
-import { cancelBuilderFlowSession, archiveBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, } from "../builder-flow-runtime.js";
-const USAGE = "Usage: flow-agents builder-run <recover|pause|resume|cancel|release-assignment|archive> --session-dir <path> [--reason <text> | --authorization-file <path>]";
+import { cancelBuilderFlowSession, archiveBuilderFlowSession, pauseBuilderFlowSession, prepareBuilderCancelRequest, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, } from "../builder-flow-runtime.js";
+const USAGE = "Usage: flow-agents builder-run <recover|pause|resume|cancel|cancel-request|release-assignment|archive> --session-dir <path> [--reason <text> | --authorization-file <path>]";
+const CANCEL_REQUEST_USAGE = "Usage: flow-agents builder-run cancel-request --session-dir <path> [--out <file>] [--reason <text>] [--actor <name>] [--expires-in-hours <n>]";
+/**
+ * `cancel-request` (#659 Slice C) — mint a ready-to-sign cancel authorization so
+ * an operator no longer hand-assembles the JSON. READ-ONLY: it signs and cancels
+ * nothing; the ed25519 signature lock is unchanged. The operator signs the
+ * emitted `signing_payload`, drops the signature into the written file, and runs
+ * `builder-run cancel --authorization-file <file>` as before.
+ */
+async function runCancelRequest(sessionDir, flags) {
+    const allowed = new Set(["session-dir", "out", "reason", "actor", "expires-in-hours"]);
+    if (Object.keys(flags).some((name) => !allowed.has(name))) {
+        console.error(CANCEL_REQUEST_USAGE);
+        return 64;
+    }
+    const expiresRaw = flagString(flags, "expires-in-hours");
+    let expiresInHours;
+    if (expiresRaw !== undefined) {
+        expiresInHours = Number(expiresRaw);
+        // Upper-bound it (1 year) so a pathological value can't overflow the Date
+        // math into an Invalid Date / uncaught RangeError; return the usual usage code.
+        if (!Number.isFinite(expiresInHours) || expiresInHours <= 0 || expiresInHours > 8760) {
+            console.error("builder-run cancel-request --expires-in-hours must be a positive number of at most 8760 (1 year)");
+            return 64;
+        }
+    }
+    const prepared = await prepareBuilderCancelRequest({
+        sessionDir,
+        reason: flagString(flags, "reason"),
+        requestActor: flagString(flags, "actor"),
+        expiresInHours,
+    });
+    const outFile = flagString(flags, "out") ?? prepared.suggestedOutFile;
+    // Symlink-safe write, matching this codebase's O_NOFOLLOW pattern for writes
+    // into session dirs (recordAuthorizationConsumed / writeExistingFileNoFollow):
+    // never follow a symlink planted at the target and clobber it.
+    const fd = fs.openSync(outFile, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+        fs.writeFileSync(fd, `${JSON.stringify(prepared.authorization, null, 2)}\n`);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    console.log(JSON.stringify({
+        run_id: prepared.runId,
+        subject: prepared.subject,
+        run_status: prepared.runStatus,
+        already_terminal: prepared.alreadyTerminal,
+        unsigned_authorization_file: outFile,
+        signing_payload: prepared.signingPayload,
+        next_steps: [
+            `Sign the exact bytes in "signing_payload" with your ed25519 lifecycle-authority key (base64).`,
+            `Add a "signature" block: {"algorithm":"ed25519","key_id":"<your registry key id>","value":"<base64 signature>"} to ${outFile}, and save it as the signed authorization file.`,
+            `Run: flow-agents builder-run cancel --session-dir ${sessionDir} --authorization-file <signed file>`,
+            `The signature is verified against .flow-agents/lifecycle-authority-keys.json; nothing here weakens that.`,
+        ],
+        ...(prepared.alreadyTerminal ? { note: `Run is already ${prepared.runStatus}; cancel would be a no-op.` } : {}),
+    }, null, 2));
+    return 0;
+}
 export async function main(argv) {
     const parsed = parseArgs(argv);
     const action = parsed.positionals[0];
@@ -18,6 +78,15 @@ export async function main(argv) {
         console.error("builder-run requires --session-dir .kontourai/flow-agents/<slug>");
         return 64;
     }
+    // cancel-request is a READ-ONLY authorization generator with its own flag set;
+    // handle it before the mutation-lifecycle validation below.
+    if (action === "cancel-request") {
+        if (parsed.positionals.length !== 1) {
+            console.error(CANCEL_REQUEST_USAGE);
+            return 64;
+        }
+        return await runCancelRequest(sessionDir, parsed.flags);
+    }
     if (!action || !["recover", "pause", "resume", "cancel", "release-assignment", "archive"].includes(action)) {
         console.error(USAGE);
         return 64;

package/dist/codex/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/codex/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.