@kontourai/flow-agents 3.6.0 → 3.7.0

package/build/src/flow-kit/validate.js

@@ -1,4 +1,4 @@
-import * as fs from "node:fs";
+import fs from "node:fs";
 import * as path from "node:path";
 import { readJson } from "../lib/fs.js";
 // Extension-only asset classes: validated by Flow Agents. Flows are validated by @kontourai/flow.
@@ -14,7 +14,89 @@ const AGENT_EXTENSION_CLASSES = new Set(["skills", "docs", "adapters", "evals",
 // workflow_triggers / hook_influence_expectations declare kit-owned runtime influence,
 // and first_party is legacy catalog/marketplace metadata. It does not grant runtime
 // capability or steering privilege.
-const KNOWN_METADATA_FIELDS = new Set(["dependencies", "workflow_triggers", "hook_influence_expectations", "flow_step_actions", "first_party"]);
+const KNOWN_METADATA_FIELDS = new Set(["dependencies", "workflow_triggers", "hook_influence_expectations", "flow_step_actions", "skill_roles", "first_party"]);
+const MAX_FLOW_DEFINITION_BYTES = 1024 * 1024;
+function sameFileIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function lstatSafePath(root, relativePath) {
+    const parts = relativePath.split(path.sep);
+    let current = root;
+    for (const [index, part] of parts.entries()) {
+        if (!part || part === "." || part === "..")
+            return { error: "path must stay inside the kit directory" };
+        current = path.join(current, part);
+        const stat = fs.lstatSync(current);
+        if (stat.isSymbolicLink())
+            return { error: "path must not traverse a symbolic link" };
+        if (index < parts.length - 1 && !stat.isDirectory())
+            return { error: "path component must be a directory" };
+        if (index === parts.length - 1)
+            return { file: current, stat };
+    }
+    return { error: "path must reference a regular file" };
+}
+function readSafeFlowDefinition(kitDir, relativePath) {
+    const root = path.resolve(kitDir);
+    if (path.isAbsolute(relativePath))
+        return { error: "path must be relative" };
+    const lexicalFile = path.resolve(root, relativePath);
+    if (lexicalFile === root || !lexicalFile.startsWith(`${root}${path.sep}`))
+        return { error: "path must stay inside the kit directory" };
+    let rootDescriptor;
+    let descriptor;
+    try {
+        const realRoot = fs.realpathSync.native(root);
+        rootDescriptor = fs.openSync(realRoot, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY);
+        const rootIdentity = fs.fstatSync(rootDescriptor);
+        if (!rootIdentity.isDirectory() || !sameFileIdentity(rootIdentity, fs.lstatSync(realRoot)))
+            return { error: "kit directory identity changed while opening flow definition" };
+        const initialPath = lstatSafePath(realRoot, relativePath);
+        if (!initialPath.file || !initialPath.stat)
+            return { error: initialPath.error };
+        if (!initialPath.stat.isFile())
+            return { error: "path must reference a regular file" };
+        if (initialPath.stat.size > MAX_FLOW_DEFINITION_BYTES)
+            return { error: `file exceeds ${MAX_FLOW_DEFINITION_BYTES} bytes` };
+        // O_NOFOLLOW protects the terminal component. Identity checks before and after
+        // opening make a race on any intermediate component fail closed on macOS/Node,
+        // where openat-style traversal from a directory descriptor is not exposed.
+        descriptor = fs.openSync(initialPath.file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        const stat = fs.fstatSync(descriptor);
+        if (!stat.isFile())
+            return { error: "path must reference a regular file" };
+        if (!sameFileIdentity(initialPath.stat, stat))
+            return { error: "flow definition identity changed while opening" };
+        if (stat.size > MAX_FLOW_DEFINITION_BYTES)
+            return { error: `file exceeds ${MAX_FLOW_DEFINITION_BYTES} bytes` };
+        const verifiedPath = lstatSafePath(realRoot, relativePath);
+        if (!verifiedPath.stat || !sameFileIdentity(stat, verifiedPath.stat))
+            return { error: "flow definition identity changed while opening" };
+        const buffer = Buffer.alloc(stat.size);
+        let offset = 0;
+        while (offset < buffer.length) {
+            const read = fs.readSync(descriptor, buffer, offset, buffer.length - offset, offset);
+            if (read === 0)
+                break;
+            offset += read;
+        }
+        const finalStat = fs.fstatSync(descriptor);
+        if (offset !== stat.size || finalStat.size !== stat.size || !sameFileIdentity(stat, finalStat))
+            return { error: "file changed while being read" };
+        return { definition: JSON.parse(buffer.toString("utf8")) };
+    }
+    catch (error) {
+        if (error.code === "ELOOP")
+            return { error: "path must not reference a symbolic link" };
+        return { error: `path is not readable: ${error.message}` };
+    }
+    finally {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+        if (rootDescriptor !== undefined)
+            fs.closeSync(rootDescriptor);
+    }
+}
 /**
  * Parse and shape-validate a kit manifest's `dependencies` field (Flow Agents
  * extension-layer metadata; see docs/adr/0019-kit-dependency-ownership.md).
@@ -249,6 +331,8 @@ export function parseKitFlowStepActions(manifest, manifestPath) {
         }
         const skills = record.skills;
         const operations = record.operations ?? [];
+        const expectationIds = record.expectation_ids;
+        const artifacts = record.artifacts ?? [];
         if (!Array.isArray(skills) || !skills.every(workflowTriggerIdentifier)) {
             errors.push(`${manifestPath}: flow_step_actions[${index}].skills must be an identifier list`);
             return;
@@ -265,6 +349,14 @@ export function parseKitFlowStepActions(manifest, manifestPath) {
             errors.push(`${manifestPath}: flow_step_actions[${index}].operations must not contain duplicates`);
             return;
         }
+        if (expectationIds !== undefined && (!Array.isArray(expectationIds) || !expectationIds.every(workflowTriggerIdentifier) || new Set(expectationIds).size !== expectationIds.length)) {
+            errors.push(`${manifestPath}: flow_step_actions[${index}].expectation_ids must be a unique identifier list when present`);
+            return;
+        }
+        if (!Array.isArray(artifacts) || !artifacts.every((artifact) => typeof artifact === "string" && artifact.trim().length > 0) || new Set(artifacts).size !== artifacts.length) {
+            errors.push(`${manifestPath}: flow_step_actions[${index}].artifacts must be a unique non-empty string list when present`);
+            return;
+        }
         const key = `${record.flow_id}/${record.step_id}`;
         if (seen.has(key)) {
             errors.push(`${manifestPath}: flow_step_actions[${index}] duplicates '${key}'`);
@@ -276,10 +368,78 @@ export function parseKitFlowStepActions(manifest, manifestPath) {
             step_id: record.step_id,
             skills: skills,
             operations: operations,
+            artifacts: artifacts,
+            ...(Array.isArray(expectationIds) ? { expectation_ids: expectationIds } : {}),
         });
     });
     return { entries, errors };
 }
+export function parseKitSkillRoles(manifest, manifestPath) {
+    const entries = [];
+    const errors = [];
+    const raw = manifest.skill_roles;
+    if (raw === undefined)
+        return { entries, errors };
+    if (!Array.isArray(raw)) {
+        errors.push(`${manifestPath}: .skill_roles must be a list`);
+        return { entries, errors };
+    }
+    const roles = new Set(["entrypoint", "profile", "step", "shared-primitive", "extension"]);
+    const fields = new Set(["skill_id", "role", "flow_id", "step_ids", "artifacts", "expectation_ids"]);
+    const seen = new Set();
+    raw.forEach((entry, index) => {
+        if (typeof entry !== "object" || entry === null) {
+            errors.push(`${manifestPath}: skill_roles[${index}] must be an object`);
+            return;
+        }
+        const record = entry;
+        const unknown = Object.keys(record).filter((field) => !fields.has(field));
+        if (unknown.length > 0)
+            errors.push(`${manifestPath}: skill_roles[${index}] contains unsupported field(s): ${unknown.join(", ")}`);
+        if (!workflowTriggerIdentifier(record.skill_id)) {
+            errors.push(`${manifestPath}: skill_roles[${index}].skill_id must be an identifier`);
+            return;
+        }
+        if (seen.has(record.skill_id))
+            errors.push(`${manifestPath}: skill_roles[${index}].skill_id duplicates '${record.skill_id}'`);
+        seen.add(record.skill_id);
+        if (typeof record.role !== "string" || !roles.has(record.role)) {
+            errors.push(`${manifestPath}: skill_roles[${index}].role must be entrypoint, profile, step, shared-primitive, or extension`);
+            return;
+        }
+        const role = record.role;
+        if (record.flow_id !== undefined && !workflowTriggerIdentifier(record.flow_id)) {
+            errors.push(`${manifestPath}: skill_roles[${index}].flow_id must be a Flow identifier when present`);
+        }
+        for (const field of ["step_ids", "expectation_ids"]) {
+            const value = record[field];
+            if (!Array.isArray(value) || !value.every(workflowTriggerIdentifier) || new Set(value).size !== value.length) {
+                errors.push(`${manifestPath}: skill_roles[${index}].${field} must be a unique identifier list`);
+            }
+        }
+        if (!Array.isArray(record.artifacts) || !record.artifacts.every((artifact) => typeof artifact === "string" && artifact.trim().length > 0) || new Set(record.artifacts).size !== record.artifacts.length) {
+            errors.push(`${manifestPath}: skill_roles[${index}].artifacts must be a unique non-empty string list`);
+        }
+        const stepIds = Array.isArray(record.step_ids) ? record.step_ids.filter(workflowTriggerIdentifier) : [];
+        const expectationIds = Array.isArray(record.expectation_ids) ? record.expectation_ids.filter(workflowTriggerIdentifier) : [];
+        const artifacts = Array.isArray(record.artifacts) ? record.artifacts.filter((artifact) => typeof artifact === "string" && artifact.trim().length > 0) : [];
+        const flowId = typeof record.flow_id === "string" && workflowTriggerIdentifier(record.flow_id) ? record.flow_id : undefined;
+        if ((role === "entrypoint" || role === "profile") && (!flowId || stepIds.length > 0 || expectationIds.length > 0 || artifacts.length > 0)) {
+            errors.push(`${manifestPath}: skill_roles[${index}] ${role} must select one flow and own no steps, artifacts, or expectations`);
+        }
+        if (role === "step" && (!flowId || stepIds.length === 0 || artifacts.length === 0)) {
+            errors.push(`${manifestPath}: skill_roles[${index}] step must bind one flow, at least one step, and at least one artifact`);
+        }
+        if (role === "shared-primitive" && (flowId || stepIds.length > 0 || expectationIds.length > 0 || artifacts.length === 0)) {
+            errors.push(`${manifestPath}: skill_roles[${index}] ${role} must own artifacts but no Builder flow, steps, or expectations`);
+        }
+        if (role === "extension" && (flowId || stepIds.length > 0 || expectationIds.length > 0)) {
+            errors.push(`${manifestPath}: skill_roles[${index}] extension must own no Builder flow, steps, or expectations`);
+        }
+        entries.push({ skill_id: record.skill_id, role, ...(flowId ? { flow_id: flowId } : {}), step_ids: stepIds, artifacts, expectation_ids: expectationIds });
+    });
+    return { entries, errors };
+}
 /**
  * Derive the trust level for a kit id.
  * "verified" is reserved for future third-party verification.
@@ -461,6 +621,184 @@ export async function validateKitRepository(kitDir) {
     const flowStepActionResult = parseKitFlowStepActions(manifest, manifestPath);
     for (const err of flowStepActionResult.errors)
         errors.push(err);
+    const skillRoleResult = parseKitSkillRoles(manifest, manifestPath);
+    for (const err of skillRoleResult.errors)
+        errors.push(err);
+    if (manifest.skill_roles !== undefined && skillRoleResult.errors.length === 0) {
+        const declaredSkillIds = new Set(Array.isArray(manifest.skills)
+            ? manifest.skills.flatMap((entry) => typeof entry === "object" && entry !== null && typeof entry.id === "string" ? [entry.id] : [])
+            : []);
+        const roleSkillIds = new Set(skillRoleResult.entries.map((entry) => entry.skill_id));
+        for (const id of declaredSkillIds)
+            if (!roleSkillIds.has(id))
+                errors.push(`${manifestPath}: skill_roles is missing declared skill '${id}'`);
+        for (const id of roleSkillIds)
+            if (!declaredSkillIds.has(id))
+                errors.push(`${manifestPath}: skill_roles references undeclared skill '${id}'`);
+        const flows = new Map();
+        if (Array.isArray(manifest.flows)) {
+            for (const entry of manifest.flows) {
+                if (typeof entry !== "object" || entry === null)
+                    continue;
+                const flow = entry;
+                if (typeof flow.id !== "string" || typeof flow.path !== "string")
+                    continue;
+                const safeDefinition = readSafeFlowDefinition(kitDir, flow.path);
+                if (!safeDefinition.definition) {
+                    errors.push(`${manifestPath}: flows '${flow.id}' ${safeDefinition.error}`);
+                    continue;
+                }
+                try {
+                    const definition = safeDefinition.definition;
+                    const steps = new Set(Array.isArray(definition.steps) ? definition.steps.flatMap((step) => typeof step === "object" && step !== null && typeof step.id === "string" ? [step.id] : []) : []);
+                    const usesFlowByStep = new Map();
+                    if (Array.isArray(definition.steps)) {
+                        for (const step of definition.steps) {
+                            if (typeof step !== "object" || step === null)
+                                continue;
+                            const stepRecord = step;
+                            if (typeof stepRecord.id === "string" && typeof stepRecord.uses_flow === "string")
+                                usesFlowByStep.set(stepRecord.id, stepRecord.uses_flow);
+                        }
+                    }
+                    const expectationsByStep = new Map();
+                    if (typeof definition.gates === "object" && definition.gates !== null) {
+                        for (const gate of Object.values(definition.gates)) {
+                            if (typeof gate !== "object" || gate === null)
+                                continue;
+                            const gateRecord = gate;
+                            if (typeof gateRecord.step !== "string" || !Array.isArray(gateRecord.expects))
+                                continue;
+                            const expectations = expectationsByStep.get(gateRecord.step) ?? new Map();
+                            for (const expectation of gateRecord.expects) {
+                                if (typeof expectation !== "object" || expectation === null)
+                                    continue;
+                                const expectationRecord = expectation;
+                                if (typeof expectationRecord.id !== "string")
+                                    continue;
+                                const exportKeys = new Set([expectationRecord.id]);
+                                const claimType = expectationRecord.bundle_claim?.claimType;
+                                if (typeof claimType === "string")
+                                    exportKeys.add(claimType);
+                                expectations.set(expectationRecord.id, { id: expectationRecord.id, exportKeys });
+                            }
+                            expectationsByStep.set(gateRecord.step, expectations);
+                        }
+                    }
+                    flows.set(flow.id, {
+                        steps,
+                        expectationsByStep,
+                        usesFlowByStep,
+                        exports: new Set(Array.isArray(definition.exports) ? definition.exports.filter((entry) => typeof entry === "string" && entry.length > 0) : []),
+                    });
+                }
+                catch {
+                    // Core Flow validation reports missing or malformed definitions.
+                }
+            }
+        }
+        const resolveEffectiveFlowStep = (flowId, stepId, seen = new Set()) => {
+            const cycleKey = `${flowId}\u0000${stepId}`;
+            if (seen.has(cycleKey))
+                return undefined;
+            seen.add(cycleKey);
+            const flow = flows.get(flowId);
+            if (!flow)
+                return undefined;
+            const direct = flow.expectationsByStep.get(stepId);
+            if (direct)
+                return { sourceFlowId: flowId, stepId, expectations: direct, flowIds: new Set([flowId]) };
+            const childFlowId = flow.usesFlowByStep.get(stepId);
+            if (!childFlowId)
+                return { sourceFlowId: flowId, stepId, expectations: new Map(), flowIds: new Set([flowId]) };
+            const child = resolveEffectiveFlowStep(childFlowId, stepId, seen);
+            const childFlow = flows.get(childFlowId);
+            if (!child || !childFlow || [...child.expectations.values()].some((expectation) => ![...expectation.exportKeys].some((key) => childFlow.exports.has(key))))
+                return undefined;
+            child.flowIds.add(flowId);
+            return child;
+        };
+        for (const row of skillRoleResult.entries) {
+            if (!row.flow_id)
+                continue;
+            const flow = flows.get(row.flow_id);
+            if (!flow) {
+                errors.push(`${manifestPath}: skill_roles '${row.skill_id}' references unknown flow '${row.flow_id}'`);
+                continue;
+            }
+            for (const stepId of row.step_ids)
+                if (!flow.steps.has(stepId))
+                    errors.push(`${manifestPath}: skill_roles '${row.skill_id}' references unknown step '${row.flow_id}/${stepId}'`);
+            const allowedExpectations = new Set(row.step_ids.flatMap((stepId) => [...(resolveEffectiveFlowStep(row.flow_id, stepId)?.expectations.keys() ?? [])]));
+            for (const expectationId of row.expectation_ids)
+                if (!allowedExpectations.has(expectationId))
+                    errors.push(`${manifestPath}: skill_roles '${row.skill_id}' expectation '${expectationId}' is not owned by its bound step(s)`);
+        }
+        const roleByShortId = new Map(skillRoleResult.entries.map((entry) => [entry.skill_id.replace(`${String(manifest.id)}.`, ""), entry]));
+        const producerOwners = new Map();
+        for (const row of skillRoleResult.entries) {
+            if (row.role !== "step" || !row.flow_id)
+                continue;
+            for (const stepId of row.step_ids) {
+                const effectiveStep = resolveEffectiveFlowStep(row.flow_id, stepId);
+                if (!effectiveStep)
+                    continue;
+                for (const expectationId of row.expectation_ids) {
+                    if (!effectiveStep.expectations.has(expectationId))
+                        continue;
+                    const key = `${effectiveStep.sourceFlowId}\u0000${effectiveStep.stepId}\u0000${expectationId}`;
+                    producerOwners.set(key, [...(producerOwners.get(key) ?? []), `skill:${row.skill_id}`]);
+                }
+            }
+        }
+        for (const action of flowStepActionResult.entries) {
+            const containingFlow = flows.get(action.flow_id);
+            if (!containingFlow || !containingFlow.steps.has(action.step_id)) {
+                errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' references an unknown flow step`);
+                continue;
+            }
+            const effectiveStep = resolveEffectiveFlowStep(action.flow_id, action.step_id);
+            if (!effectiveStep) {
+                errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' cannot resolve its composed Flow step`);
+                continue;
+            }
+            const expectedAtStep = effectiveStep.expectations;
+            for (const expectationId of action.expectation_ids ?? []) {
+                if (!expectedAtStep.has(expectationId))
+                    errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' operation expectation '${expectationId}' is not owned by its resolved Flow step`);
+            }
+            if (action.skills.length === 0 && action.operations.length > 0 && expectedAtStep.size > 0 && !(action.expectation_ids?.length)) {
+                errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' operation-only action must explicitly declare expectation_ids`);
+            }
+            const actionRows = [];
+            for (const skill of action.skills) {
+                const row = roleByShortId.get(skill);
+                if (!row || row.role !== "step" || !row.flow_id || !effectiveStep.flowIds.has(row.flow_id) || !row.step_ids.includes(action.step_id)) {
+                    errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' skill '${skill}' must match one step-role binding`);
+                }
+                else {
+                    actionRows.push(row);
+                }
+            }
+            for (const expectationId of expectedAtStep.keys()) {
+                const key = `${effectiveStep.sourceFlowId}\u0000${effectiveStep.stepId}\u0000${expectationId}`;
+                const owners = producerOwners.get(key) ?? [];
+                if (action.operations.length > 0 && action.expectation_ids?.includes(expectationId))
+                    owners.push(`operation:${action.flow_id}/${action.step_id}`);
+                producerOwners.set(key, owners);
+            }
+        }
+        for (const [flowId, flow] of flows) {
+            for (const [stepId, expectations] of flow.expectationsByStep) {
+                for (const expectationId of expectations.keys()) {
+                    const owners = producerOwners.get(`${flowId}\u0000${stepId}\u0000${expectationId}`) ?? [];
+                    if (owners.length !== 1) {
+                        errors.push(`${manifestPath}: flow expectation '${flowId}/${stepId}/${expectationId}' must have exactly one producer owner; found ${owners.length}`);
+                    }
+                }
+            }
+        }
+    }
     if (manifest.first_party !== undefined && typeof manifest.first_party !== "boolean") {
         errors.push(`${manifestPath}: .first_party must be a boolean when present`);
     }

package/build/src/index.js

@@ -1,11 +1,9 @@
 /**
  * Public library surface for `@kontourai/flow-agents`.
  *
- * Native orchestration hosts can import the canonical workflow-sidecar
- * writer/validator here instead of shelling out to the
- * `flow-agents-workflow-sidecar` CLI or reimplementing validated
- * read / merge / write of workflow evidence. This is the same code the CLI
- * runs — importing it does not execute the CLI.
+ * Native orchestration hosts can import the canonical workflow runtime and
+ * sidecar writer/validator instead of reimplementing validated state changes.
+ * Agent-facing Kit guidance uses the public `flow-agents workflow` CLI.
  *
  * The sidecar JSON Schemas ship under `schemas/` and can be validated against
  * directly; the helpers below are the canonical writer/validator that produce
@@ -17,6 +15,8 @@ import * as path from "node:path";
 import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-sidecar.js";
 export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRunInputError, BuilderBuildRunIdentityError, evaluateBuilderBuildRun, loadBuilderBuildRun, resolveBuilderBuildFlowDefinitionPath, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
 export { archiveBuilderFlowSession, cancelBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "./builder-flow-runtime.js";
+// Pure serialization contract used by external lifecycle authorities when
+// signing requests. This does not load, create, or mutate a Flow run.
 export { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 export { defaultArtifactRootForRead, defaultCodexHome, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, durableFlowAgentsRoot, durableInstallRecordPath, DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR, FLOW_AGENTS_RUNTIME_SUBDIR, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.js";
 export { 

package/build/src/lib/observed-command.d.ts

@@ -0,0 +1,7 @@
+export type ObservedProcessResult = {
+    command: string;
+    exit_code: number | null;
+    output_sha256: string;
+    output: string;
+};
+export declare function runObservedCommand(command: string, projectRoot: string): Promise<ObservedProcessResult>;

package/build/src/lib/observed-command.js

@@ -0,0 +1,100 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+function configuredTimeout(variable, fallback) {
+    const value = Number(process.env[variable] ?? fallback);
+    return Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+export async function runObservedCommand(command, projectRoot) {
+    const timeoutMs = configuredTimeout("FLOW_AGENTS_EVIDENCE_COMMAND_TIMEOUT_MS", 600000);
+    const killGraceMs = configuredTimeout("FLOW_AGENTS_EVIDENCE_COMMAND_KILL_GRACE_MS", 5000);
+    const result = await new Promise((resolve, reject) => {
+        const child = spawn("bash", ["-lc", command], {
+            cwd: projectRoot,
+            detached: process.platform !== "win32",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdoutHash = createHash("sha256");
+        const stderrHash = createHash("sha256");
+        let settled = false;
+        let timeout;
+        let killTimer;
+        let cleanupStarted = false;
+        let cleanupComplete = false;
+        let streamsClosed = false;
+        let closedCode = null;
+        let output = "";
+        const captureOutput = (chunk) => {
+            if (output.length >= 64 * 1024)
+                return;
+            output += chunk.toString("utf8").slice(0, 64 * 1024 - output.length);
+        };
+        const terminateProcessGroup = (signal) => {
+            try {
+                if (process.platform !== "win32" && child.pid)
+                    process.kill(-child.pid, signal);
+                else
+                    child.kill(signal);
+                return true;
+            }
+            catch (error) {
+                if (error.code === "ESRCH")
+                    return false;
+                throw error;
+            }
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout)
+                clearTimeout(timeout);
+            if (killTimer)
+                clearTimeout(killTimer);
+            reject(error);
+        };
+        const complete = () => {
+            if (settled || !cleanupComplete || !streamsClosed)
+                return;
+            settled = true;
+            if (timeout)
+                clearTimeout(timeout);
+            const outputHash = createHash("sha256")
+                .update("stdout\0").update(stdoutHash.digest())
+                .update("stderr\0").update(stderrHash.digest());
+            resolve({ code: closedCode, outputSha256: outputHash.digest("hex"), output });
+        };
+        const beginCleanup = () => {
+            if (settled || cleanupStarted)
+                return;
+            cleanupStarted = true;
+            try {
+                if (!terminateProcessGroup("SIGTERM")) {
+                    cleanupComplete = true;
+                    complete();
+                    return;
+                }
+                killTimer = setTimeout(() => {
+                    killTimer = undefined;
+                    try {
+                        terminateProcessGroup("SIGKILL");
+                        cleanupComplete = true;
+                        complete();
+                    }
+                    catch (error) {
+                        fail(error);
+                    }
+                }, killGraceMs);
+            }
+            catch (error) {
+                fail(error);
+            }
+        };
+        timeout = setTimeout(beginCleanup, timeoutMs);
+        child.stdout.on("data", (chunk) => { stdoutHash.update(chunk); captureOutput(chunk); });
+        child.stderr.on("data", (chunk) => { stderrHash.update(chunk); captureOutput(chunk); });
+        child.once("error", fail);
+        child.once("exit", (code) => { closedCode = code; beginCleanup(); });
+        child.once("close", () => { streamsClosed = true; complete(); });
+    });
+    return { command, exit_code: result.code, output_sha256: result.outputSha256, output: result.output };
+}

package/build/src/tools/generate-context-map.js

@@ -23,8 +23,10 @@ const commands = [
     ["Static suite", "bash evals/run.sh static"],
     ["Integration suite", "bash evals/run.sh integration"],
     ["Workflow artifacts", `npm run workflow:validate-artifacts -- --require-sidecars --require-critique ${FLOW_AGENTS_RUNTIME_DIR}/<slug>`],
-    ["Workflow sidecars", "npm run workflow:sidecar -- --help"],
-    ["Claim lookup", "npm run workflow:sidecar -- claim <id> <dir>"],
+    ["Workflow control", "flow-agents workflow --help"],
+    ["Workflow status", "flow-agents workflow status --session-dir .kontourai/flow-agents/<slug> --json"],
+    ["Workflow critique", "flow-agents workflow critique --session-dir .kontourai/flow-agents/<slug> --verdict <pass|fail|not_verified> --summary <text>"],
+    ["Workflow verification", "flow-agents workflow evidence --session-dir .kontourai/flow-agents/<slug> --expectation tests-evidence --status <pass|fail|not_verified> --command \"bash evals/static/test_builder_skill_coherence.sh\" --criterion-json '{\"id\":\"AC-1\",\"status\":\"pass\",\"evidence_refs\":[{\"kind\":\"command\",\"excerpt\":\"bash evals/static/test_builder_skill_coherence.sh\",\"summary\":\"Exact substantive command run for AC-1.\"}]}' --evidence-ref-json '{\"kind\":\"artifact\",\"file\":\".kontourai/flow-agents/<slug>/<slug>--plan-work.md\",\"summary\":\"Reviewable criterion mapping.\"}'"],
     ["Context map drift", "npm run context-map:check"],
     ["Bundle build", "npm run build:bundles"],
     ["Skill drift check", "flow-agents skill-drift-check"],
@@ -193,7 +195,7 @@ function render(includeRuntime) {
         "## Workflow Sidecars", "",
         `Machine-readable workflow state lives beside Markdown artifacts in \`${FLOW_AGENTS_RUNTIME_DIR}/<slug>/\`.`, "",
         ...markdownTable(["Schema", "Title", "ID"], schemas()), "",
-        "Primary tools: `npm run workflow:sidecar`, `npm run workflow:validate-artifacts`, `scripts/hooks/stop-goal-fit.js`, and `scripts/hooks/workflow-steering.js`.", "",
+        "Primary tools: public `flow-agents workflow`, `trust.bundle`, artifact validation, `scripts/hooks/stop-goal-fit.js`, and `scripts/hooks/workflow-steering.js`. The package-internal writer is not an agent or consumer interface.", "",
         "## Workflow Skills", "", ...markdownTable(["Skill", "Source", "When To Load"], workflowRows), "",
         "## Support Skills", "", ...markdownTable(["Skill", "Source", "When To Load"], supportRows), "",
         "## Agents", "", ...markdownTable(["Agent", "Model", "Tools", "Role"], agents()), "",

package/context/scripts/hooks/lib/kit-catalog.js

@@ -137,7 +137,7 @@ function renderKitSteering(trigger) {
     else lines.push(`Activate \`${defaultSkill}\`.`);
   }
   if (targetFlowId) {
-    lines.push(`Keep the session on \`${targetFlowId}\` and use \`npm run workflow:sidecar -- ensure-session --flow-id ${targetFlowId} ...\` when the repo provides the sidecar writer.`);
+    lines.push(`Keep the session on \`${targetFlowId}\`. Use the public \`flow-agents workflow\` interface only when it supports that Flow and its Work Item binding; otherwise report an unsupported-runtime blocker. Never call the package-internal writer from skill guidance.`);
   }
   if (requiredSequence.length) {
     lines.push(`Do not bypass ${requiredSequence.join(' -> ')} for matching work.`);