@kontourai/flow-agents 3.12.0 → 4.0.0

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

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

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

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

package/dist/claude-code/build/src/builder-lifecycle-authority.js

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

package/dist/claude-code/build/src/cli/builder-run.js

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

package/dist/claude-code/build/src/cli/narrative-render.d.ts

@@ -0,0 +1,95 @@
+import { type GroundedExecutionNarrative, type WrittenGroundedNarrative } from "../narrative/envelope.js";
+import { type EntailmentIdentity, type EntailmentProvenance } from "../narrative/grounding-validator.js";
+import { type Statement } from "../narrative/statements.js";
+export declare const PROSE_PROMPT_VERSION: "narrative-prose-renderer/v1";
+export declare const PROSE_ECONOMICS_FILE = "prose-economics.jsonl";
+export interface ProseGeneratorSentence {
+    text: string;
+    statement_refs: string[];
+}
+export interface ProseGeneratorUsage {
+    input_tokens: number;
+    output_tokens: number;
+}
+export interface GeneratedProse {
+    sentences: ProseGeneratorSentence[];
+    usage: ProseGeneratorUsage;
+}
+export interface ProseSourceView {
+    source_ref: string;
+    stream: string;
+    content: string;
+}
+export interface ProseGeneratorInput {
+    /** Frozen runtime-projection statements only (turns[].statements + document_statements). */
+    statements: Statement[];
+    /** Policy-filtered frozen snapshot views for every source_ref cited by `statements`. */
+    sourceViews: ProseSourceView[];
+}
+export interface ProseGenerator {
+    identity: EntailmentIdentity;
+    generate(input: ProseGeneratorInput): Promise<GeneratedProse>;
+}
+export declare const stubGenerator: ProseGenerator;
+export interface ProviderOptIn {
+    tenant: string;
+    data_residency: string;
+    payload_policy: string;
+}
+export interface ProviderConfig {
+    endpoint?: string;
+    optIn?: ProviderOptIn;
+}
+export declare function providerAllowed(config: ProviderConfig, endpoint: string): boolean;
+export declare class ProviderNotAllowedError extends Error {
+    readonly endpoint: string;
+    readonly name = "ProviderNotAllowedError";
+    constructor(endpoint: string);
+}
+export interface ModelGeneratorConfig extends ProviderConfig {
+    model: string;
+    provider: string;
+    timeoutMs?: number;
+}
+/** Local-first default real path (D5): an operator-configured local model server. */
+export declare function localModelGenerator(config: ModelGeneratorConfig): ProseGenerator;
+/** Hosted path (D5/R6/AC8): inert without EXPLICIT opt-in; never dials without it. */
+export declare function hostedModelGenerator(config: ModelGeneratorConfig): ProseGenerator;
+export declare class GeneratorTimeoutError extends Error {
+    readonly name = "GeneratorTimeoutError";
+}
+export type ProseRenderOutcome = "accepted" | "generator_error" | "generator_timeout" | "validator_error" | "validator_reject";
+export type ProseEconomicsRecord = EntailmentProvenance & {
+    attempted_at: string;
+    outcome: ProseRenderOutcome;
+    detail?: string;
+};
+export interface RenderProseOptions {
+    compiledAt: string;
+    outDir: string;
+    generator: ProseGenerator;
+    timeoutMs?: number;
+}
+export interface RenderProseResult {
+    envelope: GroundedExecutionNarrative;
+    written: WrittenGroundedNarrative;
+    outcome: "prose_published" | "deterministic_only";
+    reason?: string;
+    prose?: {
+        path: string;
+        sha256: string;
+    };
+    provenance: ProseEconomicsRecord;
+}
+/**
+ * Fail-closed orchestrator (D4/LB1). The #613/#623 compose -> schema-validate ->
+ * grounding-validate prefix is unchanged and still throws before ANY write on a
+ * malformed/ungrounded envelope (nothing to attempt generation over). Once that
+ * substrate is valid, the deterministic #613 output is ALWAYS written first (R4's
+ * guarantee), then generation is attempted under a bounded timeout. ANY
+ * generator error/timeout/validator error/reject leaves ZERO prose artifacts and
+ * records economics for the attempt; only an accepted, re-validated, prose-augmented
+ * statement set is published alongside the deterministic narrative.
+ */
+export declare function renderProse(narrativeDir: string, opts: RenderProseOptions): Promise<RenderProseResult>;
+export declare function main(argv?: string[]): Promise<number>;