@kontourai/flow-agents 3.5.0 → 3.6.0

package/.github/workflows/ci.yml

@@ -266,6 +266,10 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check bundle-install-integration
 
+      - name: Public workflow CLI integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check public-workflow-cli-integration
+
       - name: Bundle lifecycle integration
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check bundle-lifecycle-integration

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [3.6.0](https://github.com/kontourai/flow-agents/compare/v3.5.0...v3.6.0) (2026-07-11)
+
+
+### Features
+
+* **builder:** add authority-aware lifecycle controls ([#546](https://github.com/kontourai/flow-agents/issues/546)) ([5164902](https://github.com/kontourai/flow-agents/commit/51649020bc9a90dd77907f2aabdd9fb593f43504))
+* **cli:** add public workflow command ([#548](https://github.com/kontourai/flow-agents/issues/548)) ([2dad479](https://github.com/kontourai/flow-agents/commit/2dad47974819100ecb850fa0bec645e911d168f8))
+
 ## [3.5.0](https://github.com/kontourai/flow-agents/compare/v3.4.3...v3.5.0) (2026-07-10)
 
 

package/build/src/builder-flow-run-adapter.d.ts

@@ -1,4 +1,4 @@
-import { type FlowEvidenceEntry, type FlowRunState, type GateOutcome, type JsonObject } from "@kontourai/flow";
+import { type FlowEvidenceEntry, type FlowLifecycleRequest, type FlowRunState, type GateOutcome, type JsonObject } from "@kontourai/flow";
 export declare const BUILDER_BUILD_FLOW_ID = "builder.build";
 export declare const BUILDER_BUILD_FLOW_RELATIVE_PATH = "kits/builder/flows/build.flow.json";
 export interface BuilderBuildTrustBundleEvidenceInput {
@@ -41,6 +41,10 @@ export interface LoadBuilderBuildRunInput {
     runId: string;
     cwd?: string;
 }
+export interface ChangeBuilderBuildRunLifecycleInput extends LoadBuilderBuildRunInput {
+    request: FlowLifecycleRequest;
+    at?: string;
+}
 export interface BuilderBuildRunResult {
     definitionId: typeof BUILDER_BUILD_FLOW_ID;
     definitionVersion: string;
@@ -78,3 +82,8 @@ export declare function resolveBuilderBuildFlowDefinitionPath(startDir?: string)
 export declare function startBuilderBuildRun(input: StartBuilderBuildRunInput): Promise<BuilderBuildRunResult>;
 export declare function evaluateBuilderBuildRun(input: EvaluateBuilderBuildRunInput): Promise<BuilderBuildRunResult>;
 export declare function loadBuilderBuildRun(input: LoadBuilderBuildRunInput): Promise<BuilderBuildRunResult>;
+export declare function pauseBuilderBuildRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderBuildRunResult>;
+export declare function resumeBuilderBuildRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderBuildRunResult>;
+export declare function cancelBuilderBuildRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderBuildRunResult & {
+    idempotent: boolean;
+}>;

package/build/src/builder-flow-run-adapter.js

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
-import { attachEvidence, evaluateRun, expectationsForGate, loadRun, normalizeTrustBundle, openGates, readJson, startRun, validateDefinition, } from "@kontourai/flow";
+import { attachEvidence, cancelRun, evaluateRun, expectationsForGate, loadRun, normalizeTrustBundle, openGates, pauseRun, readJson, resumeRun, startRun, validateDefinition, } from "@kontourai/flow";
 import { resolveEffectiveFlowDefinition } from "./lib/flow-resolver.js";
 export const BUILDER_BUILD_FLOW_ID = "builder.build";
 export const BUILDER_BUILD_FLOW_RELATIVE_PATH = "kits/builder/flows/build.flow.json";
@@ -97,6 +97,34 @@ export async function loadBuilderBuildRun(input) {
     assertCanonicalDefinition(input.runId, definition, run.definition);
     return resultFromRun(run, input.runId);
 }
+export async function pauseBuilderBuildRun(input) {
+    return changeBuilderBuildRunLifecycle(input, pauseRun);
+}
+export async function resumeBuilderBuildRun(input) {
+    return changeBuilderBuildRunLifecycle(input, resumeRun);
+}
+export async function cancelBuilderBuildRun(input) {
+    const changed = await changeBuilderBuildRunLifecycleResult(input, cancelRun);
+    return { ...resultFromRun(changed, input.runId), idempotent: changed.idempotent };
+}
+async function changeBuilderBuildRunLifecycle(input, operation) {
+    const changed = await changeBuilderBuildRunLifecycleResult(input, operation);
+    return resultFromRun(changed, input.runId);
+}
+async function changeBuilderBuildRunLifecycleResult(input, operation) {
+    assertRuntimeInput(input, []);
+    if (!isRecord(input.request))
+        throw new BuilderBuildRunInputError("request", "must be a lifecycle request object");
+    const cwd = input.cwd ?? process.cwd();
+    const before = await loadBuilderBuildRun({ runId: input.runId, cwd });
+    const changed = await operation(input.runId, { cwd, ...input.request, ...(input.at ? { at: input.at } : {}) });
+    const definition = await loadShippedBuilderBuildDefinition(resolveBuilderBuildFlowDefinitionPath());
+    assertCanonicalDefinition(input.runId, definition, changed.definition);
+    if (changed.state.subject !== before.state.subject) {
+        throw new BuilderBuildRunInputError("flow_run.state.subject", "changed during lifecycle transition");
+    }
+    return changed;
+}
 function resultFromRun(run, runId) {
     return {
         definitionId: run.definition.id,

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

@@ -3,6 +3,12 @@ type AnyRecord = Record<string, any>;
 export interface BuilderFlowSessionInput {
     sessionDir: string;
 }
+export interface BuilderFlowAuthorizedLifecycleInput extends BuilderFlowSessionInput {
+    authorizationFile: string;
+}
+export interface BuilderFlowAgentLifecycleInput extends BuilderFlowSessionInput {
+    reason: string;
+}
 export interface BuilderFlowSessionResult {
     sessionDir: string;
     projectRoot: string;
@@ -13,5 +19,17 @@ export interface BuilderFlowSessionResult {
 export declare function startBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
 export declare function syncBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
 export declare function recoverBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
+export declare function pauseBuilderFlowSession(input: BuilderFlowAgentLifecycleInput): Promise<BuilderFlowSessionResult>;
+export declare function resumeBuilderFlowSession(input: BuilderFlowAgentLifecycleInput): Promise<BuilderFlowSessionResult>;
+export declare function cancelBuilderFlowSession(input: BuilderFlowAuthorizedLifecycleInput): Promise<BuilderFlowSessionResult & {
+    assignmentReleased: boolean;
+    idempotent: boolean;
+}>;
+export declare function releaseBuilderFlowAssignment(input: BuilderFlowAgentLifecycleInput): Promise<BuilderFlowSessionResult & {
+    assignmentReleased: boolean;
+}>;
+export declare function archiveBuilderFlowSession(input: BuilderFlowAuthorizedLifecycleInput): Promise<BuilderFlowSessionResult & {
+    archiveDir: string;
+}>;
 export declare function syncBuilderFlowSessionIfPresent(sessionDir: string): Promise<BuilderFlowSessionResult | null>;
 export {};

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

@@ -1,8 +1,13 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { expectationsForGate, openGates, readJson, runDir, sha256File, } from "@kontourai/flow";
-import { BUILDER_BUILD_FLOW_ID, BuilderBuildRunInputError, evaluateBuilderBuildRun, loadBuilderBuildRun, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
+import { isDeepStrictEqual } from "node:util";
+import { flowAgentsPackageVersion } from "./lib/package-version.js";
+import { pinnedFlowAgentsCommand } from "./lib/pinned-cli-command.js";
+import { expectationsForGate, lifecycleRequestMatches, openGates, readJson, runDir, sha256File, } from "@kontourai/flow";
+import { assertAuthorizationUnused, 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, cancelBuilderBuildRun, evaluateBuilderBuildRun, loadBuilderBuildRun, pauseBuilderBuildRun, resumeBuilderBuildRun, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
 export async function startBuilderFlowSession(input) {
     const context = resolveSessionContext(input.sessionDir);
     const sidecarSnapshot = readSidecarSnapshot(context);
@@ -59,6 +64,187 @@ export async function recoverBuilderFlowSession(input) {
         attached: false,
     };
 }
+export async function pauseBuilderFlowSession(input) {
+    return changeBuilderFlowSessionLifecycle(input, "pause");
+}
+export async function resumeBuilderFlowSession(input) {
+    return changeBuilderFlowSessionLifecycle(input, "resume");
+}
+export async function cancelBuilderFlowSession(input) {
+    const context = resolveSessionContext(input.sessionDir);
+    return await withSubjectLock(context.artifactRoot, context.slug, async () => {
+        const prepared = await prepareAuthorizedLifecycleChange(input, "cancel", context);
+        assertAuthorizationUnused(prepared.context.artifactRoot, prepared.authorization);
+        const changed = await cancelBuilderBuildRun({ cwd: prepared.context.projectRoot, runId: prepared.context.slug, request: prepared.authorization.request });
+        const released = performLocalReleaseUnderLock(prepared.context.artifactRoot, prepared.context.slug, prepared.authorization.assignment_actor, {
+            actorKey: prepared.authorization.assignment_actor_key,
+            reason: `canonical Flow run canceled by ${prepared.authorization.request.authority.request_ref}`,
+            tolerateNoActiveClaim: true,
+        });
+        const projection = projectFlowRun(prepared.context, changed, prepared.sidecarSnapshot.state);
+        writeProjection(prepared.context, projection, prepared.sidecarSnapshot.raw, "cancellation projection");
+        recordAuthorizationConsumed(prepared.context.artifactRoot, prepared.authorization);
+        return { sessionDir: prepared.context.sessionDir, projectRoot: prepared.context.projectRoot, run: changed, projection, attached: false, assignmentReleased: released !== null, idempotent: changed.idempotent };
+    });
+}
+export async function releaseBuilderFlowAssignment(input) {
+    const context = resolveSessionContext(input.sessionDir);
+    return await withSubjectLock(context.artifactRoot, context.slug, async () => {
+        const prepared = prepareAgentLifecycleChange(input, context);
+        const run = await loadBuilderBuildRun({ cwd: context.projectRoot, runId: context.slug });
+        const released = performLocalReleaseUnderLock(context.artifactRoot, context.slug, prepared.actor, { actorKey: prepared.actorKey, reason: input.reason });
+        return { sessionDir: context.sessionDir, projectRoot: context.projectRoot, run, projection: prepared.sidecarSnapshot.state, attached: false, assignmentReleased: released !== null };
+    });
+}
+export async function archiveBuilderFlowSession(input) {
+    const context = resolveSessionContext(input.sessionDir);
+    return await withSubjectLock(context.artifactRoot, context.slug, async () => {
+        const prepared = await prepareAuthorizedLifecycleChange(input, "archive", context);
+        const priorConsumption = readAuthorizationConsumption(prepared.context.artifactRoot, prepared.authorization);
+        const recoveringPreparedArchive = priorConsumption !== null && prepared.sidecarSnapshot.state.status === "archived";
+        if (priorConsumption && !recoveringPreparedArchive)
+            throw new Error("lifecycle authorization nonce has already been consumed");
+        const run = await loadBuilderBuildRun({ cwd: prepared.context.projectRoot, runId: prepared.context.slug });
+        if (run.state.status !== "completed" && run.state.status !== "canceled") {
+            throw new BuilderBuildRunInputError("flow_run.status", "must be completed or canceled before archival");
+        }
+        const archiveRoot = path.join(prepared.context.artifactRoot, "archive");
+        const archiveDir = path.join(archiveRoot, prepared.context.slug);
+        if (pathExistsNoFollow(archiveDir))
+            throw new BuilderBuildRunInputError("archive", "destination already exists");
+        fs.mkdirSync(archiveRoot, { recursive: true });
+        assertSafeDirectory(archiveRoot, prepared.context.artifactRoot, "archive root");
+        assertSafeDirectory(prepared.context.sessionDir, prepared.context.artifactRoot, "sessionDir");
+        if (!recoveringPreparedArchive && fs.readFileSync(prepared.context.stateFile, "utf8") !== prepared.sidecarSnapshot.raw) {
+            throw new BuilderBuildRunInputError("state.json", "changed during archive preparation");
+        }
+        const archivedState = recoveringPreparedArchive ? prepared.sidecarSnapshot.state : {
+            ...prepared.sidecarSnapshot.state,
+            status: "archived",
+            phase: "done",
+            updated_at: new Date().toISOString(),
+            next_action: { status: "done", summary: "Builder session archived; canonical Flow artifacts remain retained." },
+        };
+        if (!recoveringPreparedArchive) {
+            writeExistingFileNoFollow(prepared.context.stateFile, `${JSON.stringify(archivedState, null, 2)}\n`);
+            clearCurrentPointers(prepared.context.artifactRoot, prepared.context.slug);
+            recordAuthorizationConsumed(prepared.context.artifactRoot, prepared.authorization);
+        }
+        fs.renameSync(prepared.context.sessionDir, archiveDir);
+        return {
+            sessionDir: archiveDir,
+            projectRoot: prepared.context.projectRoot,
+            run,
+            projection: archivedState,
+            attached: false,
+            archiveDir,
+        };
+    });
+}
+async function changeBuilderFlowSessionLifecycle(input, operation) {
+    const context = resolveSessionContext(input.sessionDir);
+    return await withSubjectLock(context.artifactRoot, context.slug, async () => {
+        const prepared = prepareAgentLifecycleChange(input, context);
+        const change = operation === "pause" ? pauseBuilderBuildRun : resumeBuilderBuildRun;
+        const at = new Date().toISOString();
+        const run = await change({
+            cwd: context.projectRoot,
+            runId: context.slug,
+            request: { reason: input.reason, authority: { kind: "operator_request", actor: prepared.actorKey, request_ref: `flow-agents://assignment/${context.slug}/${operation}/${at}`, requested_at: at } },
+        });
+        const projection = projectFlowRun(context, run, prepared.sidecarSnapshot.state);
+        writeProjection(context, projection, prepared.sidecarSnapshot.raw, `${operation} projection`);
+        return {
+            sessionDir: context.sessionDir,
+            projectRoot: context.projectRoot,
+            run,
+            projection,
+            attached: false,
+        };
+    });
+}
+async function prepareAuthorizedLifecycleChange(input, operation, context) {
+    const sidecarSnapshot = readSidecarSnapshot(context);
+    const subject = workflowSubject(sidecarSnapshot.state);
+    const activeAssignment = readLocalAssignmentStatus(context.artifactRoot, context.slug).record;
+    const assignmentFile = assignmentFilePath(context.artifactRoot, context.slug);
+    const persistedAssignment = pathExistsNoFollow(assignmentFile)
+        ? (assertSafeFile(assignmentFile, context.artifactRoot, "assignment record"), JSON.parse(fs.readFileSync(assignmentFile, "utf8")))
+        : null;
+    const canonicalRun = await loadBuilderBuildRun({ cwd: context.projectRoot, runId: context.slug });
+    const acceptsReleasedAssignment = (operation === "cancel" && canonicalRun.state.status === "canceled") || operation === "archive";
+    const assignment = activeAssignment ?? (acceptsReleasedAssignment && persistedAssignment?.status === "released" ? persistedAssignment : null);
+    if (!assignment || (assignment.status !== "claimed" && !acceptsReleasedAssignment) || !assignment.actor_key) {
+        throw new BuilderBuildRunInputError("assignment", "must be actively held by a canonical actor before a lifecycle change");
+    }
+    if (assignment.work_item_ref && assignment.work_item_ref !== subject) {
+        throw new BuilderBuildRunInputError("assignment.work_item_ref", "must match the selected Work Item");
+    }
+    const authorization = loadBuilderLifecycleAuthorization(input.authorizationFile, {
+        projectRoot: context.projectRoot,
+        operation,
+        runId: context.slug,
+        subject,
+        actorKey: assignment.actor_key,
+        ...(operation === "cancel" && canonicalRun.state.status === "canceled" ? { allowExpired: true } : {}),
+        ...(operation === "archive" && sidecarSnapshot.state.status === "archived" ? { allowExpired: true } : {}),
+    });
+    if (operation === "cancel" && canonicalRun.state.status === "canceled") {
+        const terminalEvent = canonicalRun.state.lifecycle?.at(-1);
+        if (!terminalEvent || terminalEvent.action !== "cancel" || !lifecycleRequestMatches(terminalEvent, authorization.request)) {
+            throw new BuilderBuildRunInputError("authorization.request", "does not match the canonical cancellation being recovered");
+        }
+    }
+    if (!sameActor(authorization.assignment_actor, assignment.actor)) {
+        throw new BuilderBuildRunInputError("authorization.assignment_actor", "must match the active assignment holder");
+    }
+    return { context, sidecarSnapshot, authorization };
+}
+function prepareAgentLifecycleChange(input, context) {
+    if (!input.reason.trim())
+        throw new BuilderBuildRunInputError("reason", "must be non-empty");
+    const resolved = resolveCurrentAssignmentActor();
+    const sidecarSnapshot = readSidecarSnapshot(context);
+    const subject = workflowSubject(sidecarSnapshot.state);
+    const assignment = readLocalAssignmentStatus(context.artifactRoot, context.slug).record;
+    if (!assignment || assignment.status !== "claimed" || assignment.actor_key !== resolved.actorKey || !sameActor(assignment.actor, resolved.actor)) {
+        throw new BuilderBuildRunInputError("assignment", "must be actively held by the current workflow actor");
+    }
+    if (assignment.work_item_ref && assignment.work_item_ref !== subject)
+        throw new BuilderBuildRunInputError("assignment.work_item_ref", "must match the selected Work Item");
+    return { sidecarSnapshot, actor: resolved.actor, actorKey: resolved.actorKey };
+}
+function sameActor(left, right) {
+    return isDeepStrictEqual({ ...left, human: left.human ?? null }, { ...right, human: right.human ?? null });
+}
+function clearCurrentPointers(artifactRoot, slug) {
+    const candidates = [path.join(artifactRoot, "current.json")];
+    const actorRoot = path.join(artifactRoot, "current");
+    if (pathExistsNoFollow(actorRoot)) {
+        assertSafeDirectory(actorRoot, artifactRoot, "current directory");
+        candidates.push(...fs.readdirSync(actorRoot).filter((name) => name.endsWith(".json")).map((name) => path.join(actorRoot, name)));
+    }
+    for (const file of candidates) {
+        if (!pathExistsNoFollow(file) || !fs.lstatSync(file).isFile())
+            continue;
+        const root = file === candidates[0] ? artifactRoot : actorRoot;
+        if (root === actorRoot)
+            assertSafeDirectory(actorRoot, artifactRoot, "current directory");
+        assertSafeFile(file, root, "current pointer");
+        let pointer;
+        try {
+            pointer = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError))
+                throw error;
+            // Archival retains malformed unrelated pointers for explicit repair.
+            continue;
+        }
+        if (pointer.active_slug === slug)
+            fs.unlinkSync(file);
+    }
+}
 export async function syncBuilderFlowSessionIfPresent(sessionDir) {
     let context;
     try {
@@ -216,7 +402,9 @@ function projectFlowRun(context, run, sidecar) {
     const definition = JSON.parse(fs.readFileSync(path.join(run.dir, "definition.json"), "utf8"));
     const gates = openGates(definition, run.state);
     const complete = run.state.status === "completed";
-    const action = complete ? { skills: [], operations: [] } : stepAction(run.state.current_step);
+    const paused = run.state.status === "paused";
+    const canceled = run.state.status === "canceled";
+    const action = complete || paused || canceled ? { skills: [], operations: [] } : stepAction(run.state.current_step);
     if (!action) {
         throw new BuilderBuildRunInputError("kit.flow_step_actions", `does not declare Builder step ${run.state.current_step}`);
     }
@@ -225,7 +413,7 @@ function projectFlowRun(context, run, sidecar) {
         .map((expectation) => `${expectation.id} (${expectation.bundle_claim.claimType}/${expectation.bundle_claim.subjectType ?? "any"})`));
     const skills = action?.skills ?? [];
     const operations = action?.operations ?? [];
-    const syncCommand = `flow-agents builder-run sync --session-dir .kontourai/flow-agents/${context.slug}`;
+    const syncCommand = pinnedFlowAgentsCommand(flowAgentsPackageVersion(), ["workflow", "status", "--session-dir", `.kontourai/flow-agents/${context.slug}`, "--json"]);
     const routeBack = latestRouteBack(run.state);
     const skillText = skills.length ? `Activate ${skills.map((skill) => `\`${skill}\``).join(" then ")}.` : "No Builder skill is required.";
     const operationText = operations.length ? ` Perform ${operations.map((operation) => `\`${operation}\``).join(" then ")}.` : "";
@@ -237,18 +425,22 @@ function projectFlowRun(context, run, sidecar) {
         : "";
     const nextAction = complete
         ? { status: "done", summary: "Canonical Flow run is complete." }
-        : {
-            status: "continue",
-            summary: `Flow step \`${run.state.current_step}\`: ${skillText}${operationText} ${gateText}${routeText} Then synchronize the recorded evidence.`,
-            skills,
-            operations,
-            command: syncCommand,
-        };
+        : canceled
+            ? { status: "done", summary: "Canonical Flow run was canceled by an authorized external request. Artifacts are retained until separately archived." }
+            : paused
+                ? { status: "blocked", summary: "Canonical Flow run is paused. The current assignment actor may resume it with a reason." }
+                : {
+                    status: "continue",
+                    summary: `Flow step \`${run.state.current_step}\`: ${skillText}${operationText} ${gateText}${routeText} Then synchronize the recorded evidence.`,
+                    skills,
+                    operations,
+                    command: syncCommand,
+                };
     const phase = phaseForStep(definition.phase_map, run.state.current_step) ?? sidecar.phase;
     return {
         ...sidecar,
-        status: complete ? "delivered" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
-        phase: complete ? "done" : phase,
+        status: complete ? "delivered" : canceled ? "canceled" : paused ? "blocked" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
+        phase: complete || canceled ? "done" : phase,
         updated_at: run.state.updated_at,
         flow_run: {
             run_id: run.runId,

package/build/src/builder-lifecycle-authority.d.ts

@@ -0,0 +1,35 @@
+import type { FlowLifecycleRequest } from "@kontourai/flow";
+import type { ActorStruct } from "./cli/assignment-provider.js";
+type JsonRecord = Record<string, unknown>;
+export type AuthorizedBuilderLifecycleOperation = "cancel" | "archive";
+export interface BuilderLifecycleAuthorization {
+    schema_version: "1.0";
+    operation: AuthorizedBuilderLifecycleOperation;
+    run_id: string;
+    subject: string;
+    assignment_actor_key: string;
+    assignment_actor: ActorStruct;
+    nonce: string;
+    expires_at: string;
+    request: FlowLifecycleRequest;
+    signature: {
+        algorithm: "ed25519";
+        key_id: string;
+        value: string;
+    };
+}
+export declare function lifecycleAuthorityKeysPath(projectRoot: string): string;
+export declare function loadBuilderLifecycleAuthorization(fileInput: string, expected: {
+    projectRoot: string;
+    operation: AuthorizedBuilderLifecycleOperation;
+    runId: string;
+    subject: string;
+    actorKey: string;
+    now?: string;
+    allowExpired?: boolean;
+}): BuilderLifecycleAuthorization;
+export declare function builderLifecycleAuthorizationPayload(value: Omit<BuilderLifecycleAuthorization, "signature">): 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;
+export {};

package/build/src/builder-lifecycle-authority.js

@@ -0,0 +1,219 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash, createPublicKey, verify } from "node:crypto";
+import { durableFlowAgentsRoot } from "./lib/local-artifact-root.js";
+export function lifecycleAuthorityKeysPath(projectRoot) {
+    return path.join(durableFlowAgentsRoot(projectRoot), "lifecycle-authority-keys.json");
+}
+export function loadBuilderLifecycleAuthorization(fileInput, expected) {
+    const value = readRegularJson(fileInput, "lifecycle authorization");
+    assertExactKeys(value, ["schema_version", "operation", "run_id", "subject", "assignment_actor_key", "assignment_actor", "nonce", "expires_at", "request", "signature"], "authorization");
+    if (value.schema_version !== "1.0")
+        throw new Error("lifecycle authorization schema_version must be 1.0");
+    assertEqual(value.operation, expected.operation, "operation");
+    assertEqual(value.run_id, expected.runId, "run_id");
+    assertEqual(value.subject, expected.subject, "subject");
+    assertEqual(value.assignment_actor_key, expected.actorKey, "assignment_actor_key");
+    const assignmentActor = validateActor(value.assignment_actor);
+    const request = validateRequest(value.request);
+    const nonce = boundedText(value.nonce, "nonce", 256);
+    const expiresAt = dateTime(value.expires_at, "expires_at");
+    const requestedAt = Date.parse(request.authority.requested_at);
+    const now = Date.parse(expected.now ?? new Date().toISOString());
+    if (expiresAt < requestedAt)
+        throw new Error("lifecycle authorization expires_at must not precede request.authority.requested_at");
+    if (now > expiresAt && !expected.allowExpired)
+        throw new Error("lifecycle authorization is expired");
+    if (requestedAt > now + 5 * 60_000)
+        throw new Error("lifecycle authorization request time is in the future");
+    const signature = validateSignature(value.signature);
+    const authorization = {
+        schema_version: "1.0",
+        operation: expected.operation,
+        run_id: expected.runId,
+        subject: expected.subject,
+        assignment_actor_key: expected.actorKey,
+        assignment_actor: assignmentActor,
+        nonce,
+        expires_at: value.expires_at,
+        request,
+        signature,
+    };
+    verifyAuthorizationSignature(authorization, lifecycleAuthorityKeysPath(expected.projectRoot));
+    return authorization;
+}
+export function builderLifecycleAuthorizationPayload(value) {
+    return JSON.stringify(value);
+}
+export function assertAuthorizationUnused(artifactRoot, authorization) {
+    if (!readAuthorizationConsumption(artifactRoot, authorization))
+        return;
+    throw new Error("lifecycle authorization nonce has already been consumed");
+}
+export function readAuthorizationConsumption(artifactRoot, authorization) {
+    const file = consumedAuthorizationPath(artifactRoot, authorization);
+    if (!pathExistsNoFollow(file))
+        return null;
+    const record = readRegularJson(file, "consumed lifecycle authorization record");
+    if (record.run_id !== authorization.run_id
+        || record.operation !== authorization.operation
+        || record.nonce !== authorization.nonce
+        || record.key_id !== authorization.signature.key_id
+        || record.authorization_sha256 !== authorizationDigest(authorization)) {
+        throw new Error("consumed lifecycle authorization record does not match its integrity key");
+    }
+    return record;
+}
+export function recordAuthorizationConsumed(artifactRoot, authorization, at = new Date().toISOString()) {
+    const file = consumedAuthorizationPath(artifactRoot, authorization);
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true });
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || !pathIsWithin(fs.realpathSync(directory), fs.realpathSync(artifactRoot)))
+        throw new Error("lifecycle authorization registry directory is unsafe");
+    const temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+    const descriptor = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+        fs.writeFileSync(descriptor, `${JSON.stringify({ run_id: authorization.run_id, operation: authorization.operation, nonce: authorization.nonce, key_id: authorization.signature.key_id, authorization_sha256: authorizationDigest(authorization), at })}\n`);
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    try {
+        fs.linkSync(temporary, file);
+        const directoryDescriptor = fs.openSync(directory, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            fs.fsyncSync(directoryDescriptor);
+        }
+        finally {
+            fs.closeSync(directoryDescriptor);
+        }
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+}
+function consumedAuthorizationPath(artifactRoot, authorization) {
+    const integrityKey = createHash("sha256").update(authorization.run_id).update("\0").update(authorization.nonce).digest("hex");
+    return path.join(artifactRoot, "lifecycle-authority", "consumed", `${integrityKey}.json`);
+}
+function authorizationDigest(authorization) {
+    return createHash("sha256").update(JSON.stringify(authorization)).digest("hex");
+}
+function verifyAuthorizationSignature(authorization, keysFile) {
+    const registry = readRegularJson(keysFile, "lifecycle authority key registry", true);
+    assertExactKeys(registry, ["schema_version", "keys"], "key registry");
+    if (registry.schema_version !== "1.0" || !Array.isArray(registry.keys))
+        throw new Error("lifecycle authority key registry must contain schema_version 1.0 and keys[]");
+    const key = registry.keys.find((candidate) => isRecord(candidate) && candidate.id === authorization.signature.key_id);
+    if (!isRecord(key) || key.algorithm !== "ed25519" || typeof key.public_key_pem !== "string" || key.public_key_pem.trim().length === 0) {
+        throw new Error(`lifecycle authorization key ${authorization.signature.key_id} is not trusted`);
+    }
+    const { signature: _signature, ...unsigned } = authorization;
+    let verified = false;
+    try {
+        verified = verify(null, Buffer.from(builderLifecycleAuthorizationPayload(unsigned)), createPublicKey(key.public_key_pem), Buffer.from(authorization.signature.value, "base64"));
+    }
+    catch {
+        verified = false;
+    }
+    if (!verified)
+        throw new Error("lifecycle authorization signature is invalid");
+}
+function readRegularJson(fileInput, label, requireProtected = false) {
+    const file = path.resolve(fileInput);
+    const descriptor = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+        const stat = fs.fstatSync(descriptor);
+        if (!stat.isFile())
+            throw new Error(`${label} must be a regular file`);
+        if (stat.size > 64 * 1024)
+            throw new Error(`${label} exceeds 64 KiB`);
+        if (requireProtected && (stat.mode & 0o022) !== 0)
+            throw new Error(`${label} must not be group- or world-writable`);
+        const value = JSON.parse(fs.readFileSync(descriptor, "utf8"));
+        if (!isRecord(value))
+            throw new Error(`${label} must be a JSON object`);
+        return value;
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function validateActor(value) {
+    if (!isRecord(value))
+        throw new Error("lifecycle authorization assignment_actor must be an object");
+    assertExactKeys(value, ["runtime", "session_id", "host", "human"], "assignment_actor");
+    if (!Object.prototype.hasOwnProperty.call(value, "human"))
+        throw new Error("lifecycle authorization assignment_actor.human is required");
+    for (const field of ["runtime", "session_id", "host"])
+        boundedText(value[field], `assignment_actor.${field}`, 256);
+    if (value.human !== undefined && value.human !== null)
+        boundedText(value.human, "assignment_actor.human", 256);
+    return { runtime: value.runtime, session_id: value.session_id, host: value.host, human: value.human == null ? null : value.human };
+}
+function validateRequest(value) {
+    if (!isRecord(value))
+        throw new Error("lifecycle authorization request must be an object");
+    assertExactKeys(value, ["reason", "authority"], "request");
+    const reason = boundedText(value.reason, "request.reason", 4096);
+    if (!isRecord(value.authority))
+        throw new Error("lifecycle authorization request.authority must be an object");
+    assertExactKeys(value.authority, ["kind", "actor", "request_ref", "requested_at"], "request.authority");
+    if (value.authority.kind !== "user_request" && value.authority.kind !== "operator_request")
+        throw new Error("lifecycle authorization request.authority.kind must be user_request or operator_request");
+    const actor = boundedText(value.authority.actor, "request.authority.actor", 256);
+    const requestRef = boundedText(value.authority.request_ref, "request.authority.request_ref", 2048);
+    dateTime(value.authority.requested_at, "request.authority.requested_at");
+    return { reason, authority: { kind: value.authority.kind, actor, request_ref: requestRef, requested_at: value.authority.requested_at } };
+}
+function validateSignature(value) {
+    if (!isRecord(value))
+        throw new Error("lifecycle authorization signature must be an object");
+    assertExactKeys(value, ["algorithm", "key_id", "value"], "signature");
+    if (value.algorithm !== "ed25519")
+        throw new Error("lifecycle authorization signature.algorithm must be ed25519");
+    return { algorithm: "ed25519", key_id: boundedText(value.key_id, "signature.key_id", 256), value: boundedText(value.value, "signature.value", 1024) };
+}
+function assertEqual(actual, expected, field) {
+    if (actual !== expected)
+        throw new Error(`lifecycle authorization ${field} does not match the requested Builder operation`);
+}
+function assertExactKeys(value, allowed, field) {
+    const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
+    if (unexpected.length)
+        throw new Error(`lifecycle authorization ${field} contains unsupported field ${unexpected[0]}`);
+}
+function dateTime(value, field) {
+    const text = boundedText(value, field, 128);
+    if (!Number.isFinite(Date.parse(text)))
+        throw new Error(`lifecycle authorization ${field} must be a date-time`);
+    return Date.parse(text);
+}
+function boundedText(value, field, limit) {
+    if (!nonEmpty(value) || [...value].length > limit)
+        throw new Error(`lifecycle authorization ${field} must be a non-empty string of at most ${limit} characters`);
+    return value;
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0 && !/[\x00-\x1f\x7f]/.test(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function pathExistsNoFollow(candidate) {
+    try {
+        fs.lstatSync(candidate);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function pathIsWithin(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}