@kontourai/flow-agents 3.12.0 → 4.0.0

package/.github/workflows/ci.yml

@@ -68,6 +68,10 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check content-boundary
 
+      - name: Hachure boundary
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check hachure-boundary
+
       - name: Decision registry
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check decision-registry
@@ -80,6 +84,10 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check context-map-drift
 
+      - name: Capability matrix drift
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check capability-matrix-drift
+
       - name: Static eval suite
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check static-eval-suite
@@ -137,6 +145,42 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check fixture-retirement-audit-integration
 
+      - name: Narrative source contract integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check narrative-source-contract-integration
+
+      - name: Narrative runtime projection integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check narrative-runtime-projection-integration
+
+      - name: Narrative grounded envelope integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check narrative-grounded-envelope-integration
+
+      - name: Narrative redaction fail-closed integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check narrative-redaction-fail-closed-integration
+
+      - name: Narrative trust isolation integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check narrative-trust-isolation-integration
+
+      - name: Narrative grounding validator integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check narrative-grounding-validator-integration
+
+      - name: Narrative prose renderer integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check narrative-prose-renderer-integration
+
+      - name: Narrative grounded evals integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check narrative-grounded-evals-integration
+
+      - name: Narrative intent annotation integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check narrative-intent-annotation-integration
+
       - name: Publish-change helper integration
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check publish-change-helper-integration
@@ -201,6 +245,18 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check console-tenant-isolation-integration
 
+      - name: Telemetry tool outcome integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check telemetry-tool-outcome-integration
+
+      - name: Telemetry delegation integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check telemetry-delegation-integration
+
+      - name: Telemetry action-class integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check telemetry-action-class-integration
+
       - name: Finalize CI evidence
         if: always()
         run: bash evals/ci/run-baseline.sh --finalize
@@ -246,6 +302,14 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check goal-fit-hook-integration
 
+      - name: Plain stop messaging integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check plain-stop-messaging-integration
+
+      - name: Goal Fit narrative exclusion integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check goal-fit-narrative-exclusion-integration
+
       - name: Hook category behavior integration
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check hook-category-behavior-integration
@@ -338,10 +402,22 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check telemetry-tool-usage-integration
 
+      - name: Telemetry sanitize usage integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check telemetry-sanitize-usage-integration
+
+      - name: Telemetry task slug integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check telemetry-task-slug-integration
+
       - name: Economics record integration
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check economics-record-integration
 
+      - name: Capability declarations integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check capability-declarations-integration
+
       - name: Learning review proposals integration
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check learning-review-proposals-integration

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## [4.0.0](https://github.com/kontourai/flow-agents/compare/v3.12.1...v4.0.0) (2026-07-16)
+
+
+### ⚠ BREAKING CHANGES
+
+* gate-action envelopes now require schema 3.0 typed artifact targets and structured package-bound public interfaces.
+
+### Features
+
+* add check-hachure-boundary ratchet (layer-doctrine enforcement) ([#668](https://github.com/kontourai/flow-agents/issues/668)) ([803f427](https://github.com/kontourai/flow-agents/commit/803f42783ce1427339e18602c8fda5abad1e65c3))
+* add mission-bound continuation context policy ([#639](https://github.com/kontourai/flow-agents/issues/639)) ([2a21810](https://github.com/kontourai/flow-agents/commit/2a218101ca97a10b88b205c86861fec40588d401))
+* consume @kontourai/surface explainClaim; retire the local prototype ([#171](https://github.com/kontourai/flow-agents/issues/171)) ([#638](https://github.com/kontourai/flow-agents/issues/638)) ([d4da065](https://github.com/kontourai/flow-agents/commit/d4da065121a2438f9d63a481eee5b8c7c35d282d))
+* **evals:** grounded narrative eval corpus, scorers, and mutation battery ([#612](https://github.com/kontourai/flow-agents/issues/612)) ([#667](https://github.com/kontourai/flow-agents/issues/667)) ([6cbb4ec](https://github.com/kontourai/flow-agents/commit/6cbb4ecd0a29183f47daf61939b97d7cebdaccb0))
+* make gate actions executable and typed ([#627](https://github.com/kontourai/flow-agents/issues/627)) ([df0a4f4](https://github.com/kontourai/flow-agents/commit/df0a4f4140caef5a21cec24ad5aea97802dcff88))
+* migrate InquiryRecord validation from raw hachure to Surface ([#674](https://github.com/kontourai/flow-agents/issues/674)) ([7d91e90](https://github.com/kontourai/flow-agents/commit/7d91e90273718b39d9b788540788349f1be8155e))
+* **narrative:** bounded at-action agent_stated intent annotation + fallback ([#622](https://github.com/kontourai/flow-agents/issues/622)) ([#665](https://github.com/kontourai/flow-agents/issues/665)) ([aac2dea](https://github.com/kontourai/flow-agents/commit/aac2dea06d182922a48bb0a106ea250103486e97))
+* **narrative:** deterministic grounding validator — fail-closed publication gate ([#623](https://github.com/kontourai/flow-agents/issues/623)) ([#654](https://github.com/kontourai/flow-agents/issues/654)) ([b6d5148](https://github.com/kontourai/flow-agents/commit/b6d514855d5a960fc9b6b043951dee515c289552))
+* **narrative:** grounded runtime projection — turn spine, atomic statements, throw-don't-omit coverage ([#618](https://github.com/kontourai/flow-agents/issues/618)) ([#642](https://github.com/kontourai/flow-agents/issues/642)) ([3dfcb52](https://github.com/kontourai/flow-agents/commit/3dfcb520b0e999effe98390f6c114deb4023eb64))
+* **narrative:** grounded-execution-narrative/v1 — deterministic composition over authority-owned projections ([#613](https://github.com/kontourai/flow-agents/issues/613)) ([#645](https://github.com/kontourai/flow-agents/issues/645)) ([840d8a9](https://github.com/kontourai/flow-agents/commit/840d8a95d7d30838cdd534ecaca7883d1ac5b19a))
+* **narrative:** model-assisted prose renderer — display-only, fail-closed ([#614](https://github.com/kontourai/flow-agents/issues/614)) ([#655](https://github.com/kontourai/flow-agents/issues/655)) ([f8d67c9](https://github.com/kontourai/flow-agents/commit/f8d67c98b2891eee0d301da8145ea64b312b152d))
+* **narrative:** source contract — frozen manifest, snapshot-at-compile, integrity classes, resolver ([#617](https://github.com/kontourai/flow-agents/issues/617)) ([#632](https://github.com/kontourai/flow-agents/issues/632)) ([e09ee0e](https://github.com/kontourai/flow-agents/commit/e09ee0ebf0d39c3eeb694a480842be6dd2068a29))
+* **narrative:** trust isolation — namespace, canonical+content-shape evidence guards, negative-test battery ([#619](https://github.com/kontourai/flow-agents/issues/619)) ([#653](https://github.com/kontourai/flow-agents/issues/653)) ([90535c5](https://github.com/kontourai/flow-agents/commit/90535c5b33295f9aabab59cdd3731dced07ea3c8))
+* **telemetry:** delegationTarget on tool events + Codex-CLI detection ([#581](https://github.com/kontourai/flow-agents/issues/581)) ([#676](https://github.com/kontourai/flow-agents/issues/676)) ([bb38be0](https://github.com/kontourai/flow-agents/commit/bb38be07238bcd8ed313e6958b9ba96a2e67ef45))
+* **telemetry:** durationMs / outcome / status per tool result ([#580](https://github.com/kontourai/flow-agents/issues/580)) ([#675](https://github.com/kontourai/flow-agents/issues/675)) ([6892ae0](https://github.com/kontourai/flow-agents/commit/6892ae0e0495bedb369238197b05d847284c4089))
+* **telemetry:** normalized action-class ontology on tool events ([#582](https://github.com/kontourai/flow-agents/issues/582)) ([#678](https://github.com/kontourai/flow-agents/issues/678)) ([3d7422c](https://github.com/kontourai/flow-agents/commit/3d7422ce7b7d0a10d54426c861ff22a37728d17a))
+* **trust:** writer-observed execution in the command log ([#634](https://github.com/kontourai/flow-agents/issues/634)) ([#636](https://github.com/kontourai/flow-agents/issues/636)) ([3352895](https://github.com/kontourai/flow-agents/commit/3352895855172801ec29a2717f67cc00909ea29c))
+
+
+### Fixes
+
+* bind workflow guidance to canonical flow state ([d73eb69](https://github.com/kontourai/flow-agents/commit/d73eb695c4744ee58029ec1b4a89b0b585c3872a))
+* bind workflow guidance to canonical Flow state ([814f4a2](https://github.com/kontourai/flow-agents/commit/814f4a284aa015de1fb2e689fac8fa29df23ccaa))
+* constrain continuation repair to issued gate ([876851d](https://github.com/kontourai/flow-agents/commit/876851d95756bf7131643a7db5b344b7eb4ce733))
+* constrain continuation repair to issued gate ([05de903](https://github.com/kontourai/flow-agents/commit/05de90331d2092af25d854ce5be526749027d928))
+* expose gate-action artifact expectation bindings ([#629](https://github.com/kontourai/flow-agents/issues/629)) ([721905d](https://github.com/kontourai/flow-agents/commit/721905d9135622928b3f8c4bbe7910d1d3c4a47e))
+* preserve acceptance claim integrity across gates ([#633](https://github.com/kontourai/flow-agents/issues/633)) ([81da744](https://github.com/kontourai/flow-agents/commit/81da744107d3f5bec4e6d82fa992c76c34c24ec9))
+* preserve optional artifact bindings ([#631](https://github.com/kontourai/flow-agents/issues/631)) ([00e75b6](https://github.com/kontourai/flow-agents/commit/00e75b6f76854197aa8e59a4b532e7f09797d4e4))
+* return signed continuation turns to driver ([#635](https://github.com/kontourai/flow-agents/issues/635)) ([acf09c9](https://github.com/kontourai/flow-agents/commit/acf09c9780d5e70f594c4f6c4dc6f4b9405f96c0))
+* suppress terminal workflow actions ([9e78243](https://github.com/kontourai/flow-agents/commit/9e7824326577761b85be802448bd87b27e6ede9f))
+* **telemetry:** fail CLOSED on console-relay usage sanitize ([#568](https://github.com/kontourai/flow-agents/issues/568) follow-up) ([#666](https://github.com/kontourai/flow-agents/issues/666)) ([2f46d49](https://github.com/kontourai/flow-agents/commit/2f46d491e29fd0e3b6c494a0889202890dbf314b))
+
+## [3.12.1](https://github.com/kontourai/flow-agents/compare/v3.12.0...v3.12.1) (2026-07-13)
+
+
+### Fixes
+
+* bind gate-action requirements to gates ([#608](https://github.com/kontourai/flow-agents/issues/608)) ([b1e9ad1](https://github.com/kontourai/flow-agents/commit/b1e9ad1a03ba1b88e09d6ace156e33c010bc6848))
+
 ## [3.12.0](https://github.com/kontourai/flow-agents/compare/v3.11.0...v3.12.0) (2026-07-13)
 
 

package/build/generated/capability-declarations.json

@@ -0,0 +1,177 @@
+{
+  "claude-code": {
+    "turn_id": {
+      "status": "supported"
+    },
+    "transcript_path": {
+      "status": "supported"
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "partial",
+      "note": "Captured only when the workflow records an evidence/verdict event for the sub-agent — not guaranteed every run."
+    }
+  },
+  "codex": {
+    "turn_id": {
+      "status": "supported"
+    },
+    "transcript_path": {
+      "status": "supported"
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "unsupported",
+      "reason": "Codex does not surface a per-sub-agent terminal verdict to the orchestrator."
+    }
+  },
+  "kiro": {
+    "turn_id": {
+      "status": "supported"
+    },
+    "transcript_path": {
+      "status": "supported"
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "partial",
+      "note": "Captured only when the workflow records an evidence/verdict event for the sub-agent — not guaranteed every run."
+    }
+  },
+  "opencode": {
+    "turn_id": {
+      "status": "partial",
+      "note": "session.start telemetry is unavailable in opencode run (non-interactive) mode; tool events still carry a turn context."
+    },
+    "transcript_path": {
+      "status": "unsupported",
+      "reason": "opencode does not expose a per-session transcript path to hooks."
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "unsupported",
+      "reason": "opencode does not surface per-sub-agent terminal verdicts."
+    }
+  },
+  "pi": {
+    "turn_id": {
+      "status": "supported"
+    },
+    "transcript_path": {
+      "status": "unsupported",
+      "reason": "pi does not expose a per-session transcript path to hooks."
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "unsupported",
+      "reason": "pi has no named-subagent registry, so per-sub-agent verdicts are not observable."
+    }
+  },
+  "codex-local": {
+    "turn_id": {
+      "status": "unsupported",
+      "reason": "codex-local is a kit-activation adapter, not an agent-runtime telemetry source; it emits no per-turn agent-runtime telemetry."
+    },
+    "transcript_path": {
+      "status": "unsupported",
+      "reason": "codex-local is a kit-activation adapter and does not expose a per-session transcript path."
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "unsupported",
+      "reason": "codex-local is a kit-activation adapter and does not surface per-sub-agent terminal verdicts."
+    }
+  },
+  "strands-local": {
+    "turn_id": {
+      "status": "unsupported",
+      "reason": "strands-local is a kit-activation adapter, not an agent-runtime telemetry source; it emits no per-turn agent-runtime telemetry."
+    },
+    "transcript_path": {
+      "status": "unsupported",
+      "reason": "strands-local is a kit-activation adapter and does not expose a per-session transcript path."
+    },
+    "intent_annotation": {
+      "status": "unsupported",
+      "reason": "Intent-annotation capture is not implemented on any runtime yet (#622)."
+    },
+    "per_delegation_trace_context": {
+      "status": "unsupported",
+      "reason": "Per-delegation trace-context propagation is not implemented on any runtime yet (#425)."
+    },
+    "per_delegation_tokens": {
+      "status": "unsupported",
+      "reason": "No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead."
+    },
+    "terminal_verdict": {
+      "status": "unsupported",
+      "reason": "strands-local is a kit-activation adapter and does not surface per-sub-agent terminal verdicts."
+    }
+  }
+}

package/build/src/builder-flow-runtime.d.ts

@@ -1,4 +1,5 @@
 import { type GateActionEnvelope, type GateActionProgressSnapshot } from "./builder-gate-action-envelope.js";
+import { type BuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 import { type BuilderFlowId, type BuilderFlowRunResult } from "./builder-flow-run-adapter.js";
 type AnyRecord = Record<string, any>;
 export interface BuilderFlowSessionInput {
@@ -32,6 +33,42 @@ export declare function cancelBuilderFlowSession(input: BuilderFlowAuthorizedLif
     assignmentReleased: boolean;
     idempotent: boolean;
 }>;
+export interface BuilderCancelRequestInput extends BuilderFlowSessionInput {
+    /** Free-text reason recorded in the authorization request. */
+    reason?: string;
+    /** Human/operator identity recorded as request.authority.actor. */
+    requestActor?: string;
+    /** Validity window for the emitted authorization (default 24h). */
+    expiresInHours?: number;
+    /** Override the request timestamp (tests); defaults to now. */
+    now?: string;
+    /** Override the nonce (tests); defaults to a fresh unique value. */
+    nonce?: string;
+}
+export interface BuilderCancelRequestResult {
+    runId: string;
+    subject: string;
+    runStatus: string;
+    /** True when the run is already terminal (cancel would be idempotent/no-op). */
+    alreadyTerminal: boolean;
+    /** The unsigned, ready-to-sign authorization (schema-valid, canonical order). */
+    authorization: Omit<BuilderLifecycleAuthorization, "signature">;
+    /** The exact bytes the operator must sign; a signature over these verifies. */
+    signingPayload: string;
+    /** Where the CLI writes the unsigned authorization by default. */
+    suggestedOutFile: string;
+}
+/**
+ * Generate a ready-to-sign cancel authorization for a run (#659 Slice C).
+ *
+ * READ-ONLY: this mints the *unsigned* payload (correct run identity, active
+ * assignment holder, fresh nonce/expiry) so an operator no longer has to
+ * hand-assemble the JSON. It does NOT sign, cancel, or mutate anything — the
+ * ed25519 signature lock is fully preserved; the operator still signs
+ * `signingPayload` with their key, and `builder-run cancel --authorization-file`
+ * verifies it as before.
+ */
+export declare function prepareBuilderCancelRequest(input: BuilderCancelRequestInput): Promise<BuilderCancelRequestResult>;
 export declare function releaseBuilderFlowAssignment(input: BuilderFlowAgentLifecycleInput): Promise<BuilderFlowSessionResult & {
     assignmentReleased: boolean;
 }>;

package/build/src/builder-flow-runtime.js

@@ -7,7 +7,7 @@ import { flowAgentsPackageVersion } from "./lib/package-version.js";
 import { pinnedFlowAgentsCommand } from "./lib/pinned-cli-command.js";
 import { deriveBuilderGateActionEnvelope, deriveBuilderGateActionProgressSnapshot } from "./builder-gate-action-envelope.js";
 import { evaluateGate, expectationsForGate, lifecycleRequestMatches, openGates, } from "@kontourai/flow";
-import { assertAuthorizationUnused, loadBuilderLifecycleAuthorization, readAuthorizationConsumption, recordAuthorizationConsumed } from "./builder-lifecycle-authority.js";
+import { assertAuthorizationUnused, buildUnsignedLifecycleAuthorization, loadBuilderLifecycleAuthorization, readAuthorizationConsumption, recordAuthorizationConsumed } from "./builder-lifecycle-authority.js";
 import { assignmentFilePath, performLocalReleaseUnderLock, readLocalAssignmentStatus, resolveCurrentAssignmentActor, withSubjectLock } from "./cli/assignment-provider.js";
 import { BUILDER_BUILD_FLOW_ID, BuilderBuildRunInputError, cancelBuilderFlowRun, evaluateBuilderFlowRun, loadBuilderFlowRun, pauseBuilderFlowRun, resumeBuilderFlowRun, startBuilderFlowRun, } from "./builder-flow-run-adapter.js";
 export async function startBuilderFlowSession(input) {
@@ -113,6 +113,76 @@ export async function cancelBuilderFlowSession(input) {
         return { sessionDir: prepared.context.sessionDir, projectRoot: prepared.context.projectRoot, run: changed, projection, gateActionEnvelope, progressSnapshot, attached: false, assignmentReleased: released !== null, idempotent: changed.idempotent };
     });
 }
+/**
+ * Generate a ready-to-sign cancel authorization for a run (#659 Slice C).
+ *
+ * READ-ONLY: this mints the *unsigned* payload (correct run identity, active
+ * assignment holder, fresh nonce/expiry) so an operator no longer has to
+ * hand-assemble the JSON. It does NOT sign, cancel, or mutate anything — the
+ * ed25519 signature lock is fully preserved; the operator still signs
+ * `signingPayload` with their key, and `builder-run cancel --authorization-file`
+ * verifies it as before.
+ */
+export async function prepareBuilderCancelRequest(input) {
+    const context = resolveSessionContext(input.sessionDir);
+    const sidecarSnapshot = readSidecarSnapshot(context);
+    const subject = workflowSubject(sidecarSnapshot.state);
+    const canonicalRun = await loadBuilderFlowRun({ cwd: context.projectRoot, runId: context.slug });
+    const terminalStatuses = ["canceled", "completed", "archived"];
+    const alreadyTerminal = terminalStatuses.includes(canonicalRun.state.status);
+    const activeAssignment = readLocalAssignmentStatus(context.artifactRoot, context.slug).record;
+    const assignmentFile = assignmentFilePath(context.artifactRoot, context.slug);
+    const persistedAssignment = pathExistsNoFollow(assignmentFile)
+        ? JSON.parse(fs.readFileSync(assignmentFile, "utf8"))
+        : null;
+    // When the run is already canceled, its assignment is released — accept the
+    // persisted holder so an operator can still mint a (recovery) authorization.
+    // Mirror prepareAuthorizedLifecycleChange's redemption gate EXACTLY so we never
+    // mint an authorization the real cancel would reject: a cancel may reuse a
+    // released assignment only when the run is already `canceled` (idempotent
+    // recovery) and the persisted record's status is `released`. A completed or
+    // archived run with no active holder is not cancel-redeemable, so refuse.
+    const acceptsReleasedAssignment = canonicalRun.state.status === "canceled";
+    const assignment = activeAssignment
+        ?? (acceptsReleasedAssignment && persistedAssignment?.status === "released" ? persistedAssignment : null);
+    if (!assignment || !assignment.actor_key || !assignment.actor) {
+        throw new BuilderBuildRunInputError("assignment", "the run has no assignment holder to authorize a cancel against");
+    }
+    const now = input.now ? new Date(input.now) : new Date();
+    if (!Number.isFinite(now.getTime()))
+        throw new BuilderBuildRunInputError("now", "must be a valid date-time");
+    const requestedAt = now.toISOString();
+    const hours = input.expiresInHours && input.expiresInHours > 0 ? input.expiresInHours : 24;
+    const expiresAt = new Date(now.getTime() + hours * 3_600_000).toISOString();
+    const nonce = input.nonce ?? `cancel-request-${context.slug}-${now.getTime()}-${randomBytes(6).toString("hex")}`;
+    const { unsigned, signingPayload } = buildUnsignedLifecycleAuthorization({
+        operation: "cancel",
+        run_id: context.slug,
+        subject,
+        assignment_actor_key: assignment.actor_key,
+        assignment_actor: assignment.actor,
+        nonce,
+        expires_at: expiresAt,
+        request: {
+            reason: (input.reason && input.reason.trim()) || `Operator-requested cancellation of run ${context.slug}.`,
+            authority: {
+                kind: "user_request",
+                actor: (input.requestActor && input.requestActor.trim()) || "operator",
+                request_ref: `flow-agents://cancel-request/${context.slug}/${now.getTime()}`,
+                requested_at: requestedAt,
+            },
+        },
+    });
+    return {
+        runId: context.slug,
+        subject,
+        runStatus: canonicalRun.state.status,
+        alreadyTerminal,
+        authorization: unsigned,
+        signingPayload,
+        suggestedOutFile: path.join(context.sessionDir, "cancel.authorization.unsigned.json"),
+    };
+}
 export async function releaseBuilderFlowAssignment(input) {
     const context = resolveSessionContext(input.sessionDir);
     return await withSubjectLock(context.artifactRoot, context.slug, async () => {

package/build/src/builder-gate-action-envelope.d.ts

@@ -5,12 +5,43 @@ export type GateActionInterfaceParameter = {
     name: string;
     flag: string;
     required: boolean;
-    allowed_values?: string[];
+    allowed_values?: readonly string[];
     repeatable?: boolean;
     required_when?: {
         parameter: string;
         equals: string;
     };
+    value_schema_ref?: "#/public_interfaces/schemas/evidence_ref_json";
+};
+export type GateActionArtifactTarget = {
+    kind: "file";
+    ref: string;
+    path: string;
+    direct_write_allowed: true;
+    produced_via: {
+        interface: "skill";
+        skill_ids: string[];
+    };
+} | {
+    kind: "file";
+    ref: string;
+    path: string;
+    direct_write_allowed: false;
+    produced_via: {
+        interface: "operation";
+        operations: string[];
+    };
+} | {
+    kind: "trust_slice";
+    ref: string;
+    bundle_file: "trust.bundle";
+    slice_id: string;
+    direct_write_allowed: false;
+    record_via: Array<"workflow.evidence" | "workflow.critique">;
+};
+export type GateActionArtifactBinding = {
+    target: GateActionArtifactTarget;
+    expectation_ids: string[];
 };
 export type GateActionWorkflowMutation = {
     expectation_id: string;
@@ -21,7 +52,7 @@ export type GateActionWorkflowMutation = {
     };
     command: "flow-agents";
     argv: string[];
-    parameters: GateActionInterfaceParameter[];
+    parameters: readonly GateActionInterfaceParameter[];
 };
 export type GateActionPublicMutation = GateActionWorkflowMutation | {
     expectation_id: string;
@@ -35,7 +66,7 @@ export type GateActionPublicMutation = GateActionWorkflowMutation | {
     };
 };
 export type GateActionEnvelope = {
-    schema_version: "1.0";
+    schema_version: "3.0";
     flow: {
         run_id: string;
         definition_id: string;
@@ -47,6 +78,7 @@ export type GateActionEnvelope = {
     gate: {
         requirements: Array<{
             id: string;
+            gate_id: string;
             required: boolean;
             description: string;
             claim_type: string;
@@ -71,13 +103,22 @@ export type GateActionEnvelope = {
             sha256: string;
         }>;
         operations: string[];
-        declared_artifacts: string[];
+        declared_artifacts: GateActionArtifactTarget[];
+        artifact_bindings: GateActionArtifactBinding[];
         declared_evidence: string[];
         implementation_allowed: boolean;
     };
     public_interfaces: {
         status: {
-            command: string;
+            package: {
+                name: "@kontourai/flow-agents";
+                version: string;
+            };
+            command: "flow-agents";
+            argv: string[];
+        };
+        schemas: {
+            evidence_ref_json: AnyRecord;
         };
         mutations: GateActionPublicMutation[];
     };
@@ -91,7 +132,7 @@ export type GateActionEnvelope = {
         };
         required: {
             skill_ids: string[];
-            artifact_refs: string[];
+            artifact_refs: GateActionArtifactTarget[];
             unresolved_evidence_ids: string[];
         };
         sequence: ["activate_required_skills", "produce_declared_artifacts", "record_bound_evidence", "synchronize_canonical_flow", "return_adapter_result"];
@@ -111,6 +152,7 @@ export type GateActionEnvelope = {
         prior_turn?: GateActionPriorProgress;
     };
 };
+export { EVIDENCE_REF_JSON_SCHEMA } from "./cli/public-contracts.js";
 export type GateActionProgressSnapshot = Pick<GateActionEnvelope["progress"], "canonical_evidence" | "observed_artifacts"> & {
     current_step: string;
     /** Optional for compatibility with snapshots persisted before terminal status capture. */
@@ -137,6 +179,17 @@ export type BuilderGateActionEnvelopeInput = {
     };
     definition: AnyRecord;
 };
+export declare function installedBuilderSkillIdentity(skill: string): GateActionEnvelope["action"]["skills"][number];
+export declare function installedBuilderImplementationAllowed(definitionId: string, currentStep: string): boolean;
+export declare function installedBuilderGateActionAuthority(definitionId: string, currentStep: string, runId: string): {
+    definition_version: string;
+    gate_id: string;
+    requirements: Array<Omit<GateActionEnvelope["gate"]["requirements"][number], "status">>;
+    action: GateActionEnvelope["action"];
+    mutations: GateActionPublicMutation[];
+    artifact_bindings: GateActionArtifactBinding[];
+    external_capability?: NonNullable<GateActionEnvelope["stop_condition"]["external_capability"]>;
+};
 /** Derive bounded adapter context without trusting adapter telemetry. */
 export declare function deriveBuilderGateActionEnvelope(input: BuilderGateActionEnvelopeInput): GateActionEnvelope;
 /**
@@ -148,4 +201,3 @@ export declare function deriveBuilderGateActionProgressSnapshot(input: BuilderGa
 export declare function gateActionProgressSnapshot(envelope: GateActionEnvelope): GateActionProgressSnapshot;
 export declare function withGateActionPriorProgress(envelope: GateActionEnvelope, priorTurn: GateActionPriorProgress): GateActionEnvelope;
 export declare function observeBuilderArtifactsForProgress(sessionDir: string, artifacts: string[]): string[];
-export {};