@kontourai/flow-agents 3.12.1 → 4.1.0

package/dist/opencode/.opencode/skills/consult-standards/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: "consult-standards"
+description: "Get just-in-time Veritas governance guidance for a file or work area before editing it: run `veritas explain --file <path>` (or `--work-area <id>`) to see the governance excerpt, the Repo Standards rules that apply, their do/don't/examples, and the latest recorded surface status — then edit within those rules. Use before changing a governed repo's files, or when you want to know what standards apply to a path. Pull-based guidance; it does not block (the PreToolUse hook is the enforcement gate)."
+---
+
+# Consult Standards
+
+Before you edit a file in a Veritas-governed repo, ask Veritas what applies to it. `veritas
+explain` projects the repo's governance excerpt + the Repo Standards rules matching that file (or
+work area) + their latest surface status into one just-in-time briefing — so you edit *within* the
+rules instead of discovering a violation only when the PreToolUse hook blocks the write.
+
+**This skill wraps the `veritas` CLI. It reimplements no rule evaluation** — `veritas explain`
+does the matching and projection; the skill only tells you when and how to ask.
+
+## When to use this
+
+- **Before editing** a file in a repo that has a `.veritas/` governance config — especially a
+  file under a governed work area, or one you haven't touched before.
+- **When you want to know what standards apply** to a path or area without reading every rule in
+  `.veritas/repo-standards/` yourself.
+- Not a gate: this is **pull-based** guidance you invoke. Enforcement is separate and automatic —
+  the Veritas PreToolUse hook (engine-side; installed via the kit's governance hooks) evaluates
+  and can *block* a non-conforming write whether or not you consulted first. Consulting first
+  means you shape the edit to pass, rather than getting blocked and retrying.
+
+## How to consult
+
+```bash
+# For a specific file you're about to change:
+veritas explain --file src/path/to/file.ts
+
+# For a whole work area (a Repo Map graph node id):
+veritas explain --work-area <work-area-id>
+
+# Or pass a bare selector (auto-classified as a rule id, a file path if it contains '/', or a work-area token):
+veritas explain src/path/to/file.ts
+```
+
+`veritas explain` prints a **`Veritas JIT Context`** briefing:
+
+- **`Governance:`** — the leading lines of `.veritas/GOVERNANCE.md` (the repo's terse governance rules).
+- One block per **matching rule**: `Rule` / `Kind` / `Enforcement Level` (`Require` / `Guide` / …) /
+  `Summary` / `Do` / `Do not` / `Good` / `Bad` / `Context`.
+- **`Surface status:`** — the latest recorded status for that rule from the evidence artifacts
+  (e.g. `verified`), plus any `Surface fault:` transparency-gap lines.
+
+Read the matching rules, honor their `Do`/`Do not`, and keep the change inside the work area's
+guidance. `No matching requirement found.` means no additional Repo Standard applies to that path
+— proceed normally, it is not an error.
+
+## Source of truth
+
+`veritas explain` is a *projection* of the repo's own governance config. When you want the raw
+standards rather than the filtered view, read them directly — they are the source `explain` reads:
+
+- `.veritas/GOVERNANCE.md` — the terse agent-facing governance rules.
+- `.veritas/repo-standards/*.json` — the Repo Standards (each rule's `summary` / `mustDo` /
+  `mustNotDo` / `exampleGood` / `exampleBad` / `contextLinks`).
+- `.veritas/repo-map.json` — the work-area graph `--work-area` selects against.
+
+## Contract
+
+- **Read-only advisory.** This skill runs `veritas explain`, which reads config and evidence and
+  writes nothing. It never gates, never blocks, never attaches evidence, and has no pass/fail
+  verdict — it surfaces guidance, full stop. Enforcement stays the PreToolUse hook (engine-side).
+- **No MCP server.** Just-in-time guidance here is agent-invoked CLI (`veritas explain`), not a
+  standing MCP service. Per the flow-agents MCP posture (ADR 0011), MCP never carries the gate and
+  enforcement stays hooks; this skill is the deliberate agent-pull replacement for a guidance
+  server, not a new server.
+- **Wraps the engine; reimplements nothing.** All rule matching, governance projection, and
+  surface-status lookup live in `@kontourai/veritas` (`veritas explain` / `src/explain.mjs`). The
+  skill adds no evaluation logic.

package/dist/opencode/.opencode/skills/execute-plan/SKILL.md

@@ -11,7 +11,7 @@ Implement an approved plan while preserving scope, traceability, and recovery co
 
 - **Role:** canonical Builder build-step producer and standalone execution primitive.
 - **Binding:** `builder.build` step `execute`.
-- **Produces:** the active session execution report (`<slug>--deliver.md`), `state.json`, and `implementation-scope` for an active matching run.
+- **Produces:** the active session execution report (`<slug>--deliver.md`), `state.json`, the wave manifest (`waves.json`) for delegated waves, and `implementation-scope` for an active matching run.
 - **Standalone no-run behavior:** execute the supplied plan and return execution evidence. Do not start a Builder run, record Builder evidence, or imply that an inactive Builder flow advanced.
 
 ## Model Routing
@@ -33,8 +33,8 @@ Use `RepositoryAdapter` for repository, target revision, worktree, and changed-f
 
 1. Read the plan. Return it to `plan-work` when it lacks a Definition Of Done, stable acceptance criteria, task mapping, sandbox boundary, or usable execution scope.
 2. Before delegation, compare the current target revision with the plan's base through `RepositoryAdapter`. Re-ground the plan when changed scope intersects its assumptions; record missing confirmation as `NOT_VERIFIED` rather than treating it as fresh.
-3. Give each worker its bounded task, owned files, relevant acceptance IDs, required evidence, sandbox/worktree constraints, rollback conditions, and plan reference.
-4. Run safe independent tasks concurrently and dependent tasks in order. Between waves, collect results, resolve conflicts, and update the execution record with completed work, remaining work, changed files, and supported acceptance criteria.
+3. Before dispatching a wave that delegates work, declare it in the session's wave manifest (`waves.json`, schema `schemas/workflow-waves.schema.json`): `wave_id`, owning step, and one `expected_workers` entry per worker, so the expected worker count (M) exists before any result arrives. Then give each worker its bounded task, owned files, relevant acceptance IDs, required evidence, sandbox/worktree constraints, rollback conditions, and plan reference.
+4. Run safe independent tasks concurrently and dependent tasks in order. Between waves, reconcile results against the wave manifest — never collect from memory or prose. Every declared worker must land exactly one terminal status record (`completed`, `failed`, or `blocked`). Record each declared worker that has no terminal record as `not_reported` — never silently absorb a missing worker — then record the wave's `reconciliation` with an explicit "N of M reported" summary naming the `not_reported` workers (for example "2 of 3 reported; worker-3 not_reported"). Treat the wave as complete only when N equals M; an incomplete wave is visible data that routes to re-dispatch, a blocker, or an explicit accepted gap. After reconciliation, resolve conflicts and update the execution record with completed work, remaining work, changed files, and supported acceptance criteria.
 5. For UI tasks, include the applicable frontend design guidance in the worker instruction.
 6. When implementation completes, record scope integrity: changed files, accepted deviations, task-to-criterion traceability, evidence, and outstanding gaps. Hand off to report-only review and verification; do not treat implementation as verification.
 7. Reconcile the execution report and `state.json` with the active session artifact directory.
@@ -49,6 +49,7 @@ The execution record must identify:
 - each completed task and its supported `AC*` identifiers
 - changed files and any scope deviation with approval or route-back reason
 - worker evidence, conflicts, rollback notes, remaining work, and next action
+- per-wave reconciliation against the manifest: "N of M reported" and any `not_reported` workers with their recovery route
 - current revision comparison and re-grounding decision
 
 ## Active Builder Evidence

package/dist/opencode/.opencode/skills/pull-work/SKILL.md

@@ -32,6 +32,18 @@ Select ready backlog work and prepare a bounded handoff without implementing it.
 
 An optional GitHub adapter may implement these interfaces. Do not require GitHub issue numbers, labels, Projects, pull requests, `gh`, or provider-native dependency APIs.
 
+### Readiness Source Integrity
+
+A configured `BoardProvider` is the canonical Backlog Readiness Source
+(`docs/decisions/backlog-readiness-source.md`). When the configured board
+yields zero ready items or cannot be read, record the provider warning
+(`zero_ready_items`, or the read failure) in the pull-work artifact and route
+to triage/intake for an explicit readiness decision. Never silently
+substitute `WorkItemProvider` issue-level listing for board-driven selection:
+a deliberate issue-listing pass must carry the `board_provider_bypassed`
+warning it received into the artifact, with the reason the board was
+bypassed.
+
 ## Model Routing
 
 For board scans, WIP assessment, dependency joins, and selection bookkeeping, resolve `delegate-mechanical` from `.datum/config.json`. If unavailable, inherit the session model and record the fallback.

package/dist/opencode/.opencode/skills/review-work/SKILL.md

@@ -58,6 +58,17 @@ fallback or escalation in the critique artifact.
      security-policy changes.
    - `tool-dependencies-updater` for dependency-manifest, lockfile, or dependency-tooling changes.
    - A configured domain or policy reviewer when the repository requires one.
+
+   When review fans out to delegated reviewer lanes, declare the fan-out in the
+   session's wave manifest (`waves.json`, schema
+   `schemas/workflow-waves.schema.json`, step `review`) with one
+   `expected_workers` entry per reviewer lane before dispatch. Reconcile against
+   that manifest at collection — "N of M reported" — instead of collecting from
+   memory: every declared reviewer lands exactly one terminal status record;
+   record a reviewer that never reports as `not_reported` in the manifest —
+   never silently absorb it — and carry that lane into the critique as
+   `not_verified` with the missing report named. A missing reviewer is never a
+   clean lane.
 3. Use repository-provided scanners and checks when applicable. Do not install
    a scanner, silently substitute a different one, or mark an unavailable
    required lane clean; record the lane as `NOT_VERIFIED` with the missing

package/dist/opencode/.opencode/skills/standards-authoring/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: "standards-authoring"
+description: "Author or update a repo's Veritas Repo Standards through the kit's standards-authoring flow: run `veritas init --explore`/`--guided` to derive a proposed starter set (project name, repo-shape-adaptive Repo Map nodes, evidence-check inference, and the AGENTS.md/CLAUDE.md governance-block splice), surface it for human approval, then `veritas init --apply` once a human-approved standards-authoring-approval trust.bundle claim satisfies the flow's human-approval gate. Use when adopting Veritas governance in a repo or re-deriving standards after its shape changes — beyond the static starter set `kit provision` scaffolds."
+---
+
+# Standards Authoring
+
+Derive a repo's Veritas Repo Standards, get a human to approve them, then write them — the
+authoring UX `veritas init` provides, driven through the kit's `standards-authoring` flow so
+the write is human-gated.
+
+**Veritas does the derivation and the write; this skill only invokes the `veritas` CLI and
+surfaces its recommendation for approval.** No standards evaluation, derivation, or splice
+logic is reimplemented here (kit non-goal: never fork or reimplement Veritas).
+
+## When to use this vs. `kit provision`
+
+- **`flow-agents kit provision veritas-governance`** copies a *static* starter `.veritas/` set
+  (placeholder project name, generic nodes) — fastest path to a repo that runs
+  `veritas readiness`. See the kit README's "Scaffolding starter standards".
+- **This skill** runs Veritas's *adaptive* authoring: it derives the project name, Repo Map
+  work-area nodes, and evidence-check command from the actual repo, and splices the governance
+  block into existing `AGENTS.md`/`CLAUDE.md` — the per-repo work a verbatim file copy cannot
+  do. Use it to author standards for real, or to re-derive after the repo's shape changes.
+
+## Flow binding
+
+This skill documents how to drive `flows/standards-authoring.flow.json` — a two-step
+**agentless-gate** flow `propose -> apply` with one gate (the kit declares no
+`flow_step_actions`; like `exemption-issuance`, the human produces the gate's approval bundle
+out of band, and this skill is the operator's runbook, not a step-bound action):
+
+- `human-approval-gate` (on `apply`) requires a **verified** `standards-authoring-approval`
+  trust.bundle claim (`subjectType: "repo-governance-change"`) before the apply write is
+  flow-sanctioned.
+
+As with `exemption-issuance`'s `human-approval-gate`, "human-approved" is an **operating
+convention** the gate's claim encodes, not a structural human-only guarantee — Flow's schema
+does not distinguish a human-authored bundle from an agent-authored one (see the kit README's
+"Human-approval evidence: what is and is not enforced"). The gate adds a named claim, a
+documented sequence, and an audit trail on top of the same mitigation `veritas init --apply`
+already carries (it refuses to overwrite existing standards without `--force`).
+
+## Sequence
+
+```bash
+# 1. PROPOSE — derive a recommendation without writing anything.
+veritas init --explore
+#    (or `veritas init --guided --answers <answers.json>` for owner Q&A)
+#    -> writes a hash-pinned recommendation artifact (schema_version, project_name,
+#       repo_insights, artifact_payloads incl. AGENTS.md/CLAUDE.md governance blocks,
+#       artifact_hashes, recommended_repo_map/standards/authority, owner_questions,
+#       reasoning_summary, apply_command). Nothing under .veritas/ is written yet.
+
+# 2. APPROVE — a human reviews the recommendation (its reasoning_summary and owner_questions),
+#    then authors a Hachure trust.bundle asserting the approval:
+#      claimType: "standards-authoring-approval", subjectType: "repo-governance-change",
+#      status: "verified".
+flow init
+flow start kits/veritas-governance/flows/standards-authoring.flow.json --run-id authoring
+flow attach-evidence authoring --gate human-approval-gate --file approval.bundle --bundle
+flow evaluate authoring --gate human-approval-gate --exit-code
+#    exit 0 once the approval claim is verified; exit 1 (block) otherwise.
+
+# 3. APPLY — only after the gate passes, write the approved recommendation.
+veritas init --apply --plan <path-to-recommendation-artifact>
+#    -> validates each artifact_hashes[path] === sha256(payload) (tamper/staleness check
+#       between propose and apply), refuses to overwrite existing starter files without
+#       --force, then writes .veritas/* and splices the governance block into the selected
+#       instruction files.
+```
+
+## Contract
+
+- **Wraps the `veritas` CLI; reimplements nothing.** Project-name derivation, adaptive Repo Map
+  nodes, evidence-check inference, and the governance-block splice all live inside `veritas`
+  (`veritas init` / `src/bootstrap/*` / `src/governance.mjs`). This skill invokes and surfaces;
+  it does not compute standards.
+- **The write is human-gated by convention, not structurally.** The flow's
+  `standards-authoring-approval` claim is the sign-off record; anyone who can
+  `flow attach-evidence --bundle` a conforming claim satisfies it. Read a passing gate as "a
+  verified approval claim of the right shape was attached," not as proof a human attached it.
+- **`veritas init --apply` is create-safe by default:** it refuses to overwrite existing
+  `.veritas/` standards without `--force`. Re-authoring an already-governed repo is therefore an
+  explicit, opt-in action — the skill never silently replaces standards.
+- **No engine dependency, no evaluation.** Nothing here runs or reimplements `veritas readiness`;
+  that stays the `readiness-check` flow's concern.

package/dist/opencode/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/dist/opencode/build/package.json

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

package/dist/opencode/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/dist/opencode/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 () => {