@kontourai/flow-agents 3.5.0 → 3.6.0

package/build/src/cli/assignment-provider.d.ts

@@ -54,6 +54,10 @@ export type AssignmentStatus = {
     record: AssignmentClaimRecord | null;
     has_claim_label?: boolean;
 };
+export declare function resolveCurrentAssignmentActor(): {
+    actor: ActorStruct;
+    actorKey: string;
+};
 export declare function assignmentFilePath(artifactRoot: string, subjectId: string): string;
 export declare function readLocalRecord(artifactRoot: string, subjectId: string): AssignmentClaimRecord | null;
 export declare function writeLocalRecord(artifactRoot: string, subjectId: string, record: AssignmentClaimRecord): void;
@@ -164,6 +168,12 @@ export declare function performLocalRelease(artifactRoot: string, subjectId: str
     actorKey?: string;
     tolerateNoActiveClaim?: boolean;
 }): AssignmentClaimRecord | null;
+/** Caller must already hold this subject's assignment lock through withSubjectLock(). */
+export declare function performLocalReleaseUnderLock(artifactRoot: string, subjectId: string, releasedBy: ActorStruct | null, opts?: {
+    reason?: string;
+    actorKey?: string;
+    tolerateNoActiveClaim?: boolean;
+}): AssignmentClaimRecord | null;
 /**
  * Wave 1 (#291) extraction: the durable-write body previously inlined inside supersedeLocalFile's
  * withSubjectLock() closure, now a parameter-driven pure function so ensure-session's

package/build/src/cli/assignment-provider.js

@@ -76,6 +76,9 @@ function loadActorStruct(args) {
     const actorJsonPath = flagString(args.flags, "actor-json");
     if (actorJsonPath)
         return { actor: loadActorStructFromFile(actorJsonPath) };
+    return resolveCurrentAssignmentActor();
+}
+export function resolveCurrentAssignmentActor() {
     const helper = loadActorIdentityHelper();
     const resolved = helper.resolveActor(process.env);
     if (helper.isUnresolvedActor(resolved.actor))
@@ -86,9 +89,15 @@ function loadActorStruct(args) {
     // CI session — actor_key stays correct (so no false-block), but record.actor is malformed and the
     // audit-trail / `assignment-provider status` output for CI sessions would be corrupt.
     const ci = resolved.source.startsWith("ci-runtime") ? helper.detectCiActor(process.env) : null;
-    const actor = ci && ci.session_id
-        ? { runtime: ci.runtime, session_id: ci.session_id, host: os.hostname(), human: null }
-        : { runtime: helper.detectRuntime(process.env), session_id: resolved.actor, host: os.hostname(), human: null };
+    const runtimeSessionId = resolved.source.startsWith("runtime-session-id") ? helper.runtimeSessionId(process.env) : "";
+    const ancestrySeed = resolved.source === "process-ancestry" ? helper.ancestorActorSeed() : "";
+    const actor = resolved.source === "explicit-override"
+        ? { runtime: "explicit-override", session_id: resolved.actor, host: os.hostname(), human: null }
+        : ci && ci.session_id
+            ? { runtime: ci.runtime, session_id: ci.session_id, host: os.hostname(), human: null }
+            : runtimeSessionId
+                ? { runtime: helper.detectRuntime(process.env), session_id: runtimeSessionId, host: os.hostname(), human: null }
+                : { runtime: helper.detectRuntime(process.env), session_id: ancestrySeed ? `anc-${ancestrySeed}` : resolved.actor, host: os.hostname(), human: null };
     return { actor, actorKey: resolved.actor };
 }
 export function assignmentFilePath(artifactRoot, subjectId) {
@@ -522,61 +531,61 @@ function claimLocalFile(argv) {
  * than allowed to silently no-op or wrongly refuse.
  */
 export function performLocalRelease(artifactRoot, subjectId, releasedBy, opts = {}) {
+    return withSubjectLock(artifactRoot, subjectId, () => performLocalReleaseUnderLock(artifactRoot, subjectId, releasedBy, opts));
+}
+/** Caller must already hold this subject's assignment lock through withSubjectLock(). */
+export function performLocalReleaseUnderLock(artifactRoot, subjectId, releasedBy, opts = {}) {
     const helper = loadActorIdentityHelper();
     const reason = opts.reason ?? "released";
     const tolerateNoActiveClaim = opts.tolerateNoActiveClaim ?? false;
-    // F1 fix (fix-plan iteration 1, CRITICAL): release mutates the same record file claim/supersede
-    // do, under the same per-subject lock (see withSubjectLock()'s doc comment).
-    return withSubjectLock(artifactRoot, subjectId, () => {
-        const existing = readLocalRecord(artifactRoot, subjectId);
-        if (!existing || existing.status !== "claimed") {
-            if (tolerateNoActiveClaim)
+    const existing = readLocalRecord(artifactRoot, subjectId);
+    if (!existing || existing.status !== "claimed") {
+        if (tolerateNoActiveClaim)
+            return null;
+        throw new Error(`no active claim to release for subject: ${subjectId}`);
+    }
+    if (releasedBy) {
+        // Contract guard (hardening fix, #292 review): a caller that supplies `releasedBy` but NOT
+        // `opts.actorKey` against a record that already carries `actor_key` cannot reliably prove
+        // ownership — see this function's doc comment. This is the ONLY combination that fires: it
+        // does NOT fire when `existing.actor_key` is absent (the CLI/fixture path, where both sides
+        // fall back to serializeActor() and legitimately compare equal). Fail loudly rather than
+        // silently no-op (tolerant callers) or wrongly refuse (throwing callers) — never silent.
+        if (!opts.actorKey && existing.actor_key) {
+            if (tolerateNoActiveClaim) {
+                console.error(`[performLocalRelease] cannot verify ownership of an actor_key-stamped record without opts.actorKey; skipping release for ${subjectId}`);
                 return null;
-            throw new Error(`no active claim to release for subject: ${subjectId}`);
-        }
-        if (releasedBy) {
-            // Contract guard (hardening fix, #292 review): a caller that supplies `releasedBy` but NOT
-            // `opts.actorKey` against a record that already carries `actor_key` cannot reliably prove
-            // ownership — see this function's doc comment. This is the ONLY combination that fires: it
-            // does NOT fire when `existing.actor_key` is absent (the CLI/fixture path, where both sides
-            // fall back to serializeActor() and legitimately compare equal). Fail loudly rather than
-            // silently no-op (tolerant callers) or wrongly refuse (throwing callers) — never silent.
-            if (!opts.actorKey && existing.actor_key) {
-                if (tolerateNoActiveClaim) {
-                    console.error(`[performLocalRelease] cannot verify ownership of an actor_key-stamped record without opts.actorKey; skipping release for ${subjectId}`);
-                    return null;
-                }
-                throw new Error("performLocalRelease: pass opts.actorKey (the canonical resolveActor().actor string) when releasedBy is set and the record carries actor_key — serializeActor(releasedBy) is not a valid ownership key for actor_key-stamped records");
-            }
-            // AC6: never force-release a claim held by a different actor. Mirrors
-            // computeEffectiveState()'s canonical self-recognition comparison EXACTLY —
-            // `holderActorKey` prefers the stored `actor_key` (the canonical resolveActor(env).actor
-            // string, present on records written by the fixed performLocalClaim/performLocalSupersede
-            // paths) and only falls back to `serializeActor(existing.actor)` when `actor_key` is
-            // absent (every pre-fix record, every #290 eval fixture). The releaser's side must use the
-            // SAME canonical form: `opts.actorKey` (the caller's resolveActor(env).actor string, e.g.
-            // scripts/hooks/stop-goal-fit.js's Stop hook) when provided, else re-derived via
-            // serializeActor(releasedBy) — never serializeActor() unconditionally on both sides, which
-            // would compare the bare actor_key form against a re-derived triple form for an
-            // explicit-override actor and spuriously reject a legitimate same-actor release (the #291
-            // seam, relocated to this write path).
-            const holderActorKey = existing.actor_key || helper.serializeActor(existing.actor);
-            const releasedByActorKey = opts.actorKey || helper.serializeActor(releasedBy);
-            if (holderActorKey !== releasedByActorKey) {
-                if (tolerateNoActiveClaim)
-                    return null;
-                throw new Error(`--actor-json does not match the current holder (${holderActorKey}); refusing to release a claim held by someone else`);
             }
+            throw new Error("performLocalRelease: pass opts.actorKey (the canonical resolveActor().actor string) when releasedBy is set and the record carries actor_key — serializeActor(releasedBy) is not a valid ownership key for actor_key-stamped records");
         }
-        const record = {
-            ...existing,
-            ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
-            status: "released",
-            audit_trail: [...(existing.audit_trail ?? []), { at: isoNow(), transition: "release", from_actor: existing.actor, to_actor: releasedBy, reason }],
-        };
-        writeLocalRecord(artifactRoot, subjectId, record);
-        return record;
-    });
+        // AC6: never force-release a claim held by a different actor. Mirrors
+        // computeEffectiveState()'s canonical self-recognition comparison EXACTLY —
+        // `holderActorKey` prefers the stored `actor_key` (the canonical resolveActor(env).actor
+        // string, present on records written by the fixed performLocalClaim/performLocalSupersede
+        // paths) and only falls back to `serializeActor(existing.actor)` when `actor_key` is
+        // absent (every pre-fix record, every #290 eval fixture). The releaser's side must use the
+        // SAME canonical form: `opts.actorKey` (the caller's resolveActor(env).actor string, e.g.
+        // scripts/hooks/stop-goal-fit.js's Stop hook) when provided, else re-derived via
+        // serializeActor(releasedBy) — never serializeActor() unconditionally on both sides, which
+        // would compare the bare actor_key form against a re-derived triple form for an
+        // explicit-override actor and spuriously reject a legitimate same-actor release (the #291
+        // seam, relocated to this write path).
+        const holderActorKey = existing.actor_key || helper.serializeActor(existing.actor);
+        const releasedByActorKey = opts.actorKey || helper.serializeActor(releasedBy);
+        if (holderActorKey !== releasedByActorKey) {
+            if (tolerateNoActiveClaim)
+                return null;
+            throw new Error(`--actor-json does not match the current holder (${holderActorKey}); refusing to release a claim held by someone else`);
+        }
+    }
+    const record = {
+        ...existing,
+        ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
+        status: "released",
+        audit_trail: [...(existing.audit_trail ?? []), { at: isoNow(), transition: "release", from_actor: existing.actor, to_actor: releasedBy, reason }],
+    };
+    writeLocalRecord(artifactRoot, subjectId, record);
+    return record;
 }
 function releaseLocalFile(argv) {
     const args = parseArgs(argv);

package/build/src/cli/builder-run.js

@@ -1,35 +1,76 @@
 import { flagString, parseArgs } from "../lib/args.js";
-import { recoverBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
+import { cancelBuilderFlowSession, archiveBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "../builder-flow-runtime.js";
+const USAGE = "Usage: flow-agents builder-run <start|sync|recover|pause|resume|cancel|release-assignment|archive> --session-dir <path> [--reason <text> | --authorization-file <path>]";
 export async function main(argv) {
     const parsed = parseArgs(argv);
     const action = parsed.positionals[0];
     const sessionDir = flagString(parsed.flags, "session-dir");
+    const authorizationFile = flagString(parsed.flags, "authorization-file");
+    const reason = flagString(parsed.flags, "reason");
     const validRecoveryArguments = parsed.positionals.length === 1
         && Object.keys(parsed.flags).length === 1
         && typeof parsed.flags["session-dir"] === "string";
     if (action === "recover" && !validRecoveryArguments) {
-        console.error("Usage: flow-agents builder-run <start|sync|recover> --session-dir <path>");
+        console.error(USAGE);
         return 64;
     }
     if (!sessionDir) {
         console.error("builder-run requires --session-dir .kontourai/flow-agents/<slug>");
         return 64;
     }
-    if (action !== "start" && action !== "sync" && action !== "recover") {
-        console.error("Usage: flow-agents builder-run <start|sync|recover> --session-dir <path>");
+    if (!action || !["start", "sync", "recover", "pause", "resume", "cancel", "release-assignment", "archive"].includes(action)) {
+        console.error(USAGE);
+        return 64;
+    }
+    const agentLifecycle = action === "pause" || action === "resume" || action === "release-assignment";
+    const authorizedLifecycle = action === "cancel" || action === "archive";
+    const lifecycle = agentLifecycle || authorizedLifecycle;
+    const allowedLifecycleFlag = (name) => name === "session-dir" || (agentLifecycle ? name === "reason" : name === "authorization-file");
+    if (lifecycle && (parsed.positionals.length !== 1 || Object.keys(parsed.flags).some((name) => !allowedLifecycleFlag(name)))) {
+        console.error(USAGE);
+        return 64;
+    }
+    if (agentLifecycle && !reason) {
+        console.error(`builder-run ${action} requires --reason <text>`);
+        return 64;
+    }
+    if (authorizedLifecycle && !authorizationFile) {
+        console.error(`builder-run ${action} requires a signed --authorization-file <path>`);
+        return 64;
+    }
+    if (!lifecycle && (authorizationFile || reason)) {
+        console.error(USAGE);
         return 64;
     }
     const result = action === "start"
         ? await startBuilderFlowSession({ sessionDir })
         : action === "sync"
             ? await syncBuilderFlowSession({ sessionDir })
-            : await recoverBuilderFlowSession({ sessionDir });
+            : action === "recover"
+                ? await recoverBuilderFlowSession({ sessionDir })
+                : action === "pause"
+                    ? await pauseBuilderFlowSession({ sessionDir, reason: reason })
+                    : action === "resume"
+                        ? await resumeBuilderFlowSession({ sessionDir, reason: reason })
+                        : action === "cancel"
+                            ? await cancelBuilderFlowSession({ sessionDir, authorizationFile: authorizationFile })
+                            : action === "release-assignment"
+                                ? await releaseBuilderFlowAssignment({ sessionDir, reason: reason })
+                                : await archiveBuilderFlowSession({ sessionDir, authorizationFile: authorizationFile });
     console.log(JSON.stringify({
         run_id: result.run.runId,
         definition_id: result.run.definitionId,
         current_step: result.run.state.current_step,
         status: result.run.state.status,
         attached: result.attached,
+        ...(action === "cancel" ? {
+            assignment_released: "assignmentReleased" in result ? result.assignmentReleased : false,
+            idempotent: "idempotent" in result ? result.idempotent : false,
+        } : action === "release-assignment" ? {
+            assignment_released: "assignmentReleased" in result ? result.assignmentReleased : false,
+        } : action === "archive" ? {
+            archive_dir: "archiveDir" in result ? result.archiveDir : null,
+        } : {}),
         next_action: result.projection.next_action,
     }));
     return 0;

package/build/src/cli/workflow-artifact-cleanup-audit.js

@@ -255,6 +255,9 @@ function classifyWorkflow(slug, workflowPath) {
     if (status === "verified" && nextStatus === "done") {
         return { ...base, classification: "cleanup_candidate", reasons: ["verified workflow has next_action.status done"] };
     }
+    if (status === "canceled" && phase === "done") {
+        return { ...base, classification: "terminal_done", reasons: ["canceled workflow retains its artifacts without requiring delivery promotion"] };
+    }
     if (["delivered", "accepted", "archived"].includes(status) && phase === "done") {
         if (status !== "archived" && !hasPromotionClaim(workflowPath)) {
             return { ...base, classification: "cleanup_candidate", reasons: [`${status} workflow reached phase done without a promotion claim; ${PROMOTE_REMEDY}`] };

package/build/src/cli/workflow-sidecar.d.ts

@@ -6,6 +6,7 @@ export declare const phases: string[];
 export declare const checkKinds: Set<string>;
 export declare const checkStatuses: Set<string>;
 export declare const verdicts: Set<string>;
+export declare const WORKFLOW_WRITER_CONTRACT_VERSION = "1.0";
 export declare function writeJson(file: string, payload: AnyObj): void;
 export declare function loadJson(file: string, fallback?: AnyObj): AnyObj;
 export declare function appendJsonl(file: string, payload: AnyObj): void;
@@ -195,6 +196,7 @@ export declare function writeTrustBundle(dir: string, slug: string, timestamp: s
     errors: string[];
 }>;
 export declare function sidecarBase(slug: string): AnyObj;
+export declare function currentWorkflowSessionDir(root: string): string | null;
 export declare function validateEvidenceRef(ref: AnyObj, label: string): AnyObj;
 export declare function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[];
 export declare function normalizeCheck(raw: AnyObj, allowGateClaimPrefix?: boolean, existingCheckStampById?: ReadonlyMap<string, boolean>): AnyObj;
@@ -622,3 +624,4 @@ export declare function buildGateInquiryRecords(bundle: BundleFile, blockSignal:
 export declare const LIVENESS_TERMINAL: Set<string>;
 export { buildClaimExplanation } from "./sidecar-claim-explain.js";
 export type { ClaimEvidenceItem, ClaimExplanation } from "./sidecar-claim-explain.js";
+export declare function main(argv?: string[]): Promise<number>;

package/build/src/cli/workflow-sidecar.js

@@ -10,17 +10,20 @@ import { fileURLToPath } from "node:url";
 import { resolveActiveFlowStep, resolveAllFlowGateExpects, resolveFlowFilePath, resolvePhaseMap, resolveRouteBackPolicy } from "../lib/flow-resolver.js";
 import { defaultArtifactRootForRead, flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
 import { ensureSafeDirectory } from "../lib/fs.js";
+import { flowAgentsPackageVersion } from "../lib/package-version.js";
+import { pinnedFlowAgentsCommand } from "../lib/pinned-cli-command.js";
 import { startBuilderFlowSession, syncBuilderFlowSessionIfPresent } from "../builder-flow-runtime.js";
 // #291 Wave 1 Task 1.1 exports: ensure-session's ownership guard reuses the EXACT same
 // assignment ⋈ liveness join / claim / supersede logic #290 already ships for the
 // `assignment-provider` CLI, rather than reimplementing a second, parallel join (static ESM
 // import — same idiom already used above for ../lib/flow-resolver.js).
 import { assignmentFilePath, computeEffectiveState, performLocalClaim, performLocalSupersede, readLocalAssignmentStatus, withSubjectLock } from "./assignment-provider.js";
-export const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
+export const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "canceled", "accepted", "archived"]);
 export const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
 export const checkKinds = new Set(["build", "types", "lint", "test", "command", "security", "diff", "browser", "runtime", "policy", "external"]);
 export const checkStatuses = new Set(["pass", "fail", "not_verified", "skip"]);
 export const verdicts = new Set(["pass", "partial", "fail", "not_verified"]);
+export const WORKFLOW_WRITER_CONTRACT_VERSION = "1.0";
 function now() { return new Date().toISOString().replace(/\.\d{3}Z$/, "Z"); }
 function read(file) { return fs.readFileSync(file, "utf8"); }
 export function writeJson(file, payload) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`); }
@@ -1681,6 +1684,10 @@ function currentDir(root, actorKey) {
     }
     return dir;
 }
+export function currentWorkflowSessionDir(root) {
+    const resolved = loadActorIdentityHelper().resolveActor(process.env);
+    return currentDir(path.resolve(root), loadActorIdentityHelper().isUnresolvedActor(resolved.actor) ? undefined : resolved.actor);
+}
 /**
  * #291 Wave 2 Task 2.1 (§6): updates BOTH the legacy current.json (when IT points at `dir` — the
  * exact, unchanged existing check/write) AND the resolved actor's own per-actor current.json
@@ -2082,13 +2089,25 @@ async function ensureSession(p) {
         // takeover continuity true by construction (see Design Decision 3 in the plan).
         const branch = resolveSessionBranch(p, slug);
         const initialMarkdownStatus = entry.flowId ? "new" : "planning";
-        md = `# ${opt(p, "title", slug)}\n\nbranch: ${branch}\nworktree: main\ncreated: ${timestamp}\nstatus: ${initialMarkdownStatus}\ntype: deliver\niteration: 1\n\n## Plan\n\n${opt(p, "summary", "")}\n\n## Definition Of Done\n\n- **User outcome:** ${opt(p, "summary", "Workflow session is durable.")}\n- **Scope:** Workflow session artifacts and sidecars.\n- **Acceptance criteria:**\n${opts(p, "criterion").map((c) => `  - [ ] ${c} - Evidence: pending.`).join("\n")}\n- **Usefulness checks:**\n  - [ ] User-facing workflow is documented or discoverable\n- **Stop-short risks:** Workflow artifacts could drift.\n- **Durable docs target:** not needed\n- **Sandbox mode:** local-edit\n\n## Execution Progress\n\n- [ ] Session initialized.\n\n## Verification Report\n\nBuild: [NOT_VERIFIED] Verification has not run yet.\n\n### Acceptance Criteria\n- [NOT_VERIFIED] Verification has not run yet - Evidence: pending workflow execution and checks.\n\n### Verdict: NOT_VERIFIED\n\n## Goal Fit Gate\n\n- [ ] Original user goal restated\n\n## Final Acceptance\n\n- [ ] CI/relevant checks passed or local equivalent recorded\n`;
+        const acceptanceCriteria = opts(p, "criterion");
+        if (acceptanceCriteria.length === 0)
+            acceptanceCriteria.push(`Complete the requested outcome: ${opt(p, "summary", "Workflow session is durable.")}`);
+        md = `# ${opt(p, "title", slug)}\n\nbranch: ${branch}\nworktree: main\ncreated: ${timestamp}\nstatus: ${initialMarkdownStatus}\ntype: deliver\niteration: 1\n\n## Plan\n\n${opt(p, "summary", "")}\n\n## Definition Of Done\n\n- **User outcome:** ${opt(p, "summary", "Workflow session is durable.")}\n- **Scope:** Workflow session artifacts and sidecars.\n- **Acceptance criteria:**\n${acceptanceCriteria.map((c) => `  - [ ] ${c} - Evidence: pending.`).join("\n")}\n- **Usefulness checks:**\n  - [ ] User-facing workflow is documented or discoverable\n- **Stop-short risks:** Workflow artifacts could drift.\n- **Durable docs target:** not needed\n- **Sandbox mode:** local-edit\n\n## Execution Progress\n\n- [ ] Session initialized.\n\n## Verification Report\n\nBuild: [NOT_VERIFIED] Verification has not run yet.\n\n### Acceptance Criteria\n- [NOT_VERIFIED] Verification has not run yet - Evidence: pending workflow execution and checks.\n\n### Verdict: NOT_VERIFIED\n\n## Goal Fit Gate\n\n- [ ] Original user goal restated\n\n## Final Acceptance\n\n- [ ] CI/relevant checks passed or local equivalent recorded\n`;
         fs.writeFileSync(path.join(dir, `${slug}--deliver.md`), md);
     }
     if (!fs.existsSync(path.join(dir, "state.json")) || !fs.existsSync(path.join(dir, "acceptance.json")) || !fs.existsSync(path.join(dir, "handoff.json"))) {
         const phaseMap = entry.flowId ? resolvePhaseMap(entry.flowId, findRepoRootFromDir(dir)) : null;
         const initialPhase = Object.entries(phaseMap ?? {}).find(([, step]) => step === entry.firstStep)?.[0];
-        const startCommand = `flow-agents builder-run start --session-dir .kontourai/flow-agents/${slug}`;
+        const startCommand = pinnedFlowAgentsCommand(flowAgentsPackageVersion(), [
+            "workflow", "start",
+            "--flow", "builder.build",
+            "--work-item", workItem.ref,
+            ...(workItem.ref === `local:${slug}` ? ["--task-slug", slug] : []),
+            "--artifact-root", root,
+            "--title", opt(p, "title", slug),
+            "--summary", opt(p, "summary", "Workflow session is durable."),
+            ...opts(p, "criterion").flatMap((criterion) => ["--criterion", criterion]),
+        ]);
         const nextAction = entry.flowId
             ? entry.flowId === "builder.build"
                 ? {
@@ -5396,7 +5415,7 @@ function loadLivenessReadHelper() {
 // init-plan claims the work-item; advance-state heartbeats (or releases on terminal),
 // so the workflow lifecycle itself maintains the liveness claim — no manual liveness calls.
 // Additive + fail-open: a liveness-emit failure never affects the workflow command.
-export const LIVENESS_TERMINAL = new Set(["delivered", "accepted", "archived"]);
+export const LIVENESS_TERMINAL = new Set(["delivered", "canceled", "accepted", "archived"]);
 /**
  * Delegate to the shared pure-CJS resolver (scripts/hooks/lib/actor-identity.js), mirroring the
  * createRequire pattern used by readLivenessEvents() above. Deliberately NO inline duplicate
@@ -5840,8 +5859,8 @@ Available claim ids:
     return 0;
 }
 // ─────────────────────────────────────────────────────────────────────────────
-async function main() {
-    const _rawArgv = process.argv.slice(2);
+export async function main(argv = process.argv.slice(2)) {
+    const _rawArgv = argv;
     // #380: `record-check <dir> -- <command...>` — argv after the FIRST literal `--` token is the
     // command to execute verbatim (never option-parsed: a command like `npm test -- --watch`
     // legitimately contains its OWN `--`, so only the record-check dispatcher's own separator, the
@@ -5927,5 +5946,8 @@ catch {
     return process.argv[1];
 } })();
 if (_selfRealPath === _argv1RealPath) {
+    if (path.basename(process.argv[1] ?? "") === "flow-agents-workflow-sidecar") {
+        process.stderr.write("flow-agents-workflow-sidecar is deprecated; use `flow-agents workflow` or an explicitly pinned `npx @kontourai/flow-agents@<version> workflow` command.\n");
+    }
     main().then((code) => process.exit(code)).catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); });
 }

package/build/src/cli/workflow.d.ts

@@ -0,0 +1,2 @@
+export declare const WORKFLOW_CONTRACT_VERSION = "1.0";
+export declare function main(argv: string[]): Promise<number>;