@kontourai/flow-agents 3.6.0 → 3.7.0

package/src/flow-kit/validate.ts

@@ -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";
 
@@ -17,7 +17,7 @@ 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"]);
 
 export interface KitDependencyEntry {
   kit_id: string;
@@ -49,6 +49,89 @@ export interface KitFlowStepActionEntry {
   step_id: string;
   skills: string[];
   operations: string[];
+  /** Gate expectations produced by this action's explicit operation(s). */
+  expectation_ids?: string[];
+  /** Durable artifacts produced by an operation-only action. */
+  artifacts: string[];
+}
+
+export type KitSkillRole = "entrypoint" | "profile" | "step" | "shared-primitive" | "extension";
+
+export interface KitSkillRoleEntry {
+  skill_id: string;
+  role: KitSkillRole;
+  flow_id?: string;
+  step_ids: string[];
+  artifacts: string[];
+  expectation_ids: string[];
+}
+
+const MAX_FLOW_DEFINITION_BYTES = 1024 * 1024;
+
+function sameFileIdentity(left: fs.Stats, right: fs.Stats): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function lstatSafePath(root: string, relativePath: string): { file?: string; stat?: fs.Stats; error?: string } {
+  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: string, relativePath: string): { definition?: Record<string, unknown>; error?: string } {
+  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: number | undefined;
+  let descriptor: number | undefined;
+  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")) as Record<string, unknown> };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ELOOP") return { error: "path must not reference a symbolic link" };
+    return { error: `path is not readable: ${(error as Error).message}` };
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+    if (rootDescriptor !== undefined) fs.closeSync(rootDescriptor);
+  }
 }
 
 /**
@@ -290,6 +373,8 @@ export function parseKitFlowStepActions(manifest: Record<string, unknown>, manif
     }
     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;
@@ -306,6 +391,14 @@ export function parseKitFlowStepActions(manifest: Record<string, unknown>, manif
       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}'`);
@@ -317,11 +410,77 @@ export function parseKitFlowStepActions(manifest: Record<string, unknown>, manif
       step_id: record.step_id,
       skills: skills as string[],
       operations: operations as string[],
+      artifacts: artifacts as string[],
+      ...(Array.isArray(expectationIds) ? { expectation_ids: expectationIds as string[] } : {}),
     });
   });
   return { entries, errors };
 }
 
+export function parseKitSkillRoles(manifest: Record<string, unknown>, manifestPath: string): { entries: KitSkillRoleEntry[]; errors: string[] } {
+  const entries: KitSkillRoleEntry[] = [];
+  const errors: string[] = [];
+  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<KitSkillRole>(["entrypoint", "profile", "step", "shared-primitive", "extension"]);
+  const fields = new Set(["skill_id", "role", "flow_id", "step_ids", "artifacts", "expectation_ids"]);
+  const seen = new Set<string>();
+  raw.forEach((entry, index) => {
+    if (typeof entry !== "object" || entry === null) {
+      errors.push(`${manifestPath}: skill_roles[${index}] must be an object`);
+      return;
+    }
+    const record = entry as Record<string, unknown>;
+    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 as KitSkillRole)) {
+      errors.push(`${manifestPath}: skill_roles[${index}].role must be entrypoint, profile, step, shared-primitive, or extension`);
+      return;
+    }
+    const role = record.role as KitSkillRole;
+    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"] as const) {
+      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): artifact is string => 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 };
+}
+
 export type KitTargetConsumer =
   | "flow"
   | "flow-agents"
@@ -555,6 +714,165 @@ export async function validateKitRepository(kitDir: string): Promise<string[]> {
   for (const err of hookExpectationResult.errors) errors.push(err);
   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 as Record<string, unknown>).id === "string" ? [(entry as Record<string, unknown>).id as string] : [])
+        : []
+    );
+    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}'`);
+
+    type FlowExpectation = { id: string; exportKeys: Set<string> };
+    type FlowMetadata = {
+      steps: Set<string>;
+      expectationsByStep: Map<string, Map<string, FlowExpectation>>;
+      usesFlowByStep: Map<string, string>;
+      exports: Set<string>;
+    };
+    type EffectiveFlowStep = { sourceFlowId: string; stepId: string; expectations: Map<string, FlowExpectation>; flowIds: Set<string> };
+    const flows = new Map<string, FlowMetadata>();
+    if (Array.isArray(manifest.flows)) {
+      for (const entry of manifest.flows) {
+        if (typeof entry !== "object" || entry === null) continue;
+        const flow = entry as Record<string, unknown>;
+        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 as Record<string, unknown>).id === "string" ? [(step as Record<string, unknown>).id as string] : []) : []);
+          const usesFlowByStep = new Map<string, string>();
+          if (Array.isArray(definition.steps)) {
+            for (const step of definition.steps) {
+              if (typeof step !== "object" || step === null) continue;
+              const stepRecord = step as Record<string, unknown>;
+              if (typeof stepRecord.id === "string" && typeof stepRecord.uses_flow === "string") usesFlowByStep.set(stepRecord.id, stepRecord.uses_flow);
+            }
+          }
+          const expectationsByStep = new Map<string, Map<string, FlowExpectation>>();
+          if (typeof definition.gates === "object" && definition.gates !== null) {
+            for (const gate of Object.values(definition.gates as Record<string, unknown>)) {
+              if (typeof gate !== "object" || gate === null) continue;
+              const gateRecord = gate as Record<string, unknown>;
+              if (typeof gateRecord.step !== "string" || !Array.isArray(gateRecord.expects)) continue;
+              const expectations = expectationsByStep.get(gateRecord.step) ?? new Map<string, FlowExpectation>();
+              for (const expectation of gateRecord.expects) {
+                if (typeof expectation !== "object" || expectation === null) continue;
+                const expectationRecord = expectation as Record<string, unknown>;
+                if (typeof expectationRecord.id !== "string") continue;
+                const exportKeys = new Set([expectationRecord.id]);
+                const claimType = (expectationRecord.bundle_claim as Record<string, unknown> | undefined)?.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): entry is string => typeof entry === "string" && entry.length > 0) : []),
+          });
+        } catch {
+          // Core Flow validation reports missing or malformed definitions.
+        }
+      }
+    }
+    const resolveEffectiveFlowStep = (flowId: string, stepId: string, seen = new Set<string>()): EffectiveFlowStep | undefined => {
+      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<string, string[]>();
+    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: KitSkillRoleEntry[] = [];
+      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/src/index.ts

@@ -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
@@ -46,6 +44,9 @@ export {
   syncBuilderFlowSession,
 } from "./builder-flow-runtime.js";
 export type { BuilderFlowAgentLifecycleInput, BuilderFlowAuthorizedLifecycleInput, BuilderFlowSessionInput, BuilderFlowSessionResult } 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 type { BuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 

package/src/lib/observed-command.ts

@@ -0,0 +1,96 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+
+export type ObservedProcessResult = {
+  command: string;
+  exit_code: number | null;
+  output_sha256: string;
+  output: string;
+};
+
+function configuredTimeout(variable: string, fallback: number): number {
+  const value = Number(process.env[variable] ?? fallback);
+  return Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+
+export async function runObservedCommand(command: string, projectRoot: string): Promise<ObservedProcessResult> {
+  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<{ code: number | null; outputSha256: string; output: string }>((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: NodeJS.Timeout | undefined;
+    let killTimer: NodeJS.Timeout | undefined;
+    let cleanupStarted = false;
+    let cleanupComplete = false;
+    let streamsClosed = false;
+    let closedCode: number | null = null;
+    let output = "";
+    const captureOutput = (chunk: Buffer): void => {
+      if (output.length >= 64 * 1024) return;
+      output += chunk.toString("utf8").slice(0, 64 * 1024 - output.length);
+    };
+    const terminateProcessGroup = (signal: NodeJS.Signals): boolean => {
+      try {
+        if (process.platform !== "win32" && child.pid) process.kill(-child.pid, signal);
+        else child.kill(signal);
+        return true;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ESRCH") return false;
+        throw error;
+      }
+    };
+    const fail = (error: Error): void => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      if (killTimer) clearTimeout(killTimer);
+      reject(error);
+    };
+    const complete = (): void => {
+      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 = (): void => {
+      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 as Error);
+          }
+        }, killGraceMs);
+      } catch (error) {
+        fail(error as Error);
+      }
+    };
+    timeout = setTimeout(beginCleanup, timeoutMs);
+    child.stdout.on("data", (chunk: Buffer) => { stdoutHash.update(chunk); captureOutput(chunk); });
+    child.stderr.on("data", (chunk: Buffer) => { 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/src/tools/generate-context-map.ts

@@ -24,8 +24,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"],
@@ -180,7 +182,7 @@ function render(includeRuntime: boolean): string {
     "## 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()), "",