ai-foreman 1.7.19 → 1.7.21

package/dist/tickets/ticketSchema.d.ts

@@ -1,3 +1,4 @@
+import { type QaPreparationDepthDecisionV1 } from "rafi-spec";
 export type TicketPriority = "P0" | "P1" | "P2" | "P3";
 export type TicketSize = "XS" | "S" | "M" | "L" | "XL";
 export type TicketRisk = "Low" | "Medium" | "High";
@@ -22,6 +23,7 @@ export interface TicketPlanRef {
     slice_ref: string;
 }
 export interface TicketDef {
+    qa_preparation?: QaPreparationDepthDecisionV1;
     id: string;
     order: number;
     title: string;
@@ -47,6 +49,104 @@ export declare const TICKET_JSON_SCHEMA: {
     readonly required: readonly ["id", "order", "title", "area", "priority", "size", "risk", "depends_on", "summary", "acceptance", "required_tests", "likely_files"];
     readonly additionalProperties: true;
     readonly properties: {
+        readonly qa_preparation: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["version", "decisionId", "level", "rationale", "riskFactors", "policyVersion", "plannerOperationId", "plannerIdentity", "timestamp", "minimumLevel", "minimumReasons"];
+            readonly properties: {
+                readonly version: {
+                    readonly const: 1;
+                };
+                readonly decisionId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly level: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 5;
+                };
+                readonly rationale: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly policyVersion: {
+                    readonly const: "qa-preparation-v1";
+                };
+                readonly plannerOperationId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly plannerIdentity: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly timestamp: {
+                    readonly type: "string";
+                    readonly pattern: "^\\d{4}-\\d{2}-\\d{2}T";
+                };
+                readonly minimumLevel: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 5;
+                };
+                readonly minimumReasons: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                };
+                readonly predecessorDecisionId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly lowRisk: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["narrowBehavior", "understoodDependencies", "adequateVerification"];
+                    readonly properties: {
+                        readonly narrowBehavior: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly understoodDependencies: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly adequateVerification: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                    };
+                };
+                readonly riskFactors: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["category", "rationale", "references"];
+                        readonly properties: {
+                            readonly category: {
+                                readonly enum: string[];
+                            };
+                            readonly rationale: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly references: {
+                                readonly type: "array";
+                                readonly minItems: 1;
+                                readonly items: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
         readonly id: {
             readonly type: "string";
             readonly pattern: "^[A-Za-z][A-Za-z0-9-_]*$";
@@ -212,6 +312,104 @@ export declare const TICKETS_FILE_SCHEMA: {
                 readonly required: readonly ["id", "order", "title", "area", "priority", "size", "risk", "depends_on", "summary", "acceptance", "required_tests", "likely_files"];
                 readonly additionalProperties: true;
                 readonly properties: {
+                    readonly qa_preparation: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["version", "decisionId", "level", "rationale", "riskFactors", "policyVersion", "plannerOperationId", "plannerIdentity", "timestamp", "minimumLevel", "minimumReasons"];
+                        readonly properties: {
+                            readonly version: {
+                                readonly const: 1;
+                            };
+                            readonly decisionId: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly level: {
+                                readonly type: "integer";
+                                readonly minimum: 1;
+                                readonly maximum: 5;
+                            };
+                            readonly rationale: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly policyVersion: {
+                                readonly const: "qa-preparation-v1";
+                            };
+                            readonly plannerOperationId: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly plannerIdentity: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly timestamp: {
+                                readonly type: "string";
+                                readonly pattern: "^\\d{4}-\\d{2}-\\d{2}T";
+                            };
+                            readonly minimumLevel: {
+                                readonly type: "integer";
+                                readonly minimum: 1;
+                                readonly maximum: 5;
+                            };
+                            readonly minimumReasons: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                            };
+                            readonly predecessorDecisionId: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly lowRisk: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["narrowBehavior", "understoodDependencies", "adequateVerification"];
+                                readonly properties: {
+                                    readonly narrowBehavior: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                    readonly understoodDependencies: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                    readonly adequateVerification: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                };
+                            };
+                            readonly riskFactors: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "object";
+                                    readonly additionalProperties: false;
+                                    readonly required: readonly ["category", "rationale", "references"];
+                                    readonly properties: {
+                                        readonly category: {
+                                            readonly enum: string[];
+                                        };
+                                        readonly rationale: {
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        };
+                                        readonly references: {
+                                            readonly type: "array";
+                                            readonly minItems: 1;
+                                            readonly items: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
                     readonly id: {
                         readonly type: "string";
                         readonly pattern: "^[A-Za-z][A-Za-z0-9-_]*$";

package/dist/tickets/ticketSchema.js

@@ -1,3 +1,4 @@
+import { qaPreparationDepthDecisionV1Schema } from "rafi-spec";
 export const TICKET_JSON_SCHEMA = {
     type: "object",
     required: [
@@ -6,6 +7,7 @@ export const TICKET_JSON_SCHEMA = {
     ],
     additionalProperties: true,
     properties: {
+        qa_preparation: qaPreparationDepthDecisionV1Schema,
         id: { type: "string", pattern: "^[A-Za-z][A-Za-z0-9-_]*$" },
         order: { type: "number", minimum: 0 },
         title: { type: "string", minLength: 1 },

package/dist/windowsProbeJob.d.ts

@@ -0,0 +1,12 @@
+export declare const WINDOWS_JOB_SOURCE: string;
+/** Standard npm shims are invoked as Node argv, never interpreted as shell text. */
+export declare function windowsRuntimeInvocation(executable: string, args: string[]): {
+    executable: string;
+    args: string[];
+};
+export declare function windowsProbeCommand(tag: string, executable: string, args: string[], cwd: string, ownerStart: string, gated?: boolean): {
+    executable: string;
+    args: string[];
+    config: string;
+};
+export declare function windowsProbeJobState(tag: string, timeoutMs?: number): "absent" | "empty" | "active" | "unknown";

package/dist/windowsProbeJob.js

@@ -0,0 +1,144 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+// Keep this host program separate from all provider/user input. The provider is
+// created suspended, assigned to a non-breakaway Job Object, then resumed.
+// https://learn.microsoft.com/en-us/windows/win32/procthread/job-objects
+export const WINDOWS_JOB_SOURCE = String.raw `
+using System;
+using System.Text;
+using System.Threading;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+public static class RafiProbeJob {
+  [StructLayout(LayoutKind.Sequential)] struct Limits {
+    public long ProcessTime, JobTime; public uint Flags;
+    public UIntPtr MinWorking, MaxWorking; public uint ActiveLimit;
+    public UIntPtr Affinity; public uint Priority, Scheduling;
+  }
+  [StructLayout(LayoutKind.Sequential)] struct Io { public ulong ReadOps, WriteOps, OtherOps, ReadBytes, WriteBytes, OtherBytes; }
+  [StructLayout(LayoutKind.Sequential)] struct Extended { public Limits Basic; public Io Io; public UIntPtr ProcessMemory, JobMemory, PeakProcess, PeakJob; }
+  [StructLayout(LayoutKind.Sequential)] struct Accounting { public long User, Kernel, PeriodUser, PeriodKernel; public uint Faults, Total, Active, Terminated; }
+  [StructLayout(LayoutKind.Sequential, CharSet=CharSet.Unicode)] struct Startup {
+    public int Size; public string Reserved, Desktop, Title;
+    public uint X,Y,XSize,YSize,XChars,YChars,Fill,Flags;
+    public ushort Show,ReservedSize; public IntPtr ReservedBytes,Input,Output,Error;
+  }
+  [StructLayout(LayoutKind.Sequential)] struct StartupEx { public Startup Basic; public IntPtr Attributes; }
+  [StructLayout(LayoutKind.Sequential)] struct ProcessInfo { public IntPtr Process,Thread; public uint Pid,Tid; }
+  [DllImport("kernel32.dll", CharSet=CharSet.Unicode, SetLastError=true)] static extern IntPtr CreateJobObject(IntPtr security,string name);
+  [DllImport("kernel32.dll", CharSet=CharSet.Unicode, SetLastError=true)] static extern IntPtr OpenJobObject(uint access,bool inherit,string name);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern bool SetInformationJobObject(IntPtr job,int kind,ref Extended value,uint size);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern bool QueryInformationJobObject(IntPtr job,int kind,out Accounting value,uint size,IntPtr returned);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern bool InitializeProcThreadAttributeList(IntPtr list,int count,int flags,ref UIntPtr size);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern bool UpdateProcThreadAttribute(IntPtr list,uint flags,UIntPtr attribute,IntPtr value,UIntPtr size,IntPtr previous,IntPtr returned);
+  [DllImport("kernel32.dll")] static extern void DeleteProcThreadAttributeList(IntPtr list);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern bool TerminateJobObject(IntPtr job,uint code);
+  [DllImport("kernel32.dll", CharSet=CharSet.Unicode, SetLastError=true)] static extern bool CreateProcess(string app,StringBuilder command,IntPtr processSecurity,IntPtr threadSecurity,bool inherit,uint flags,IntPtr env,string cwd,ref StartupEx startup,out ProcessInfo process);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern uint ResumeThread(IntPtr thread);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern uint WaitForSingleObject(IntPtr handle,uint timeout);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern bool GetExitCodeProcess(IntPtr handle,out uint code);
+  [DllImport("kernel32.dll")] static extern IntPtr GetStdHandle(int which);
+  [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr handle);
+  static void Check(bool okay) { if (!okay) throw new Win32Exception(Marshal.GetLastWin32Error()); }
+  static string Name(string tag) { return "Global\\RafiProbe-" + Guid.Parse(tag).ToString(); }
+  public static string Quote(string value) {
+    StringBuilder result=new StringBuilder("\""); int slashes=0;
+    foreach(char c in value) {
+      if(c=='\\') { slashes++; continue; }
+      if(c=='\"') { result.Append('\\',slashes*2+1); result.Append(c); }
+      else { result.Append('\\',slashes); result.Append(c); }
+      slashes=0;
+    }
+    result.Append('\\',slashes*2); result.Append('"'); return result.ToString();
+  }
+  static uint Active(IntPtr job) { Accounting value; Check(QueryInformationJobObject(job,1,out value,(uint)Marshal.SizeOf(typeof(Accounting)),IntPtr.Zero)); return value.Active; }
+  public static string Query(string tag) {
+    IntPtr job=OpenJobObject(4,false,Name(tag));
+    if(job==IntPtr.Zero) { if(Marshal.GetLastWin32Error()==2) return "absent"; return "unknown"; }
+    try { return Active(job)==0 ? "empty" : "active"; } finally { CloseHandle(job); }
+  }
+  static bool OwnerAlive(int pid,long start) {
+    try { using(var owner=System.Diagnostics.Process.GetProcessById(pid)) return !owner.HasExited && owner.StartTime.ToUniversalTime().ToFileTimeUtc()==start; } catch { return false; }
+  }
+  public static int Run(string tag,string executable,string[] args,string cwd,int ownerPid,long ownerStart) {
+    IntPtr job=CreateJobObject(IntPtr.Zero,Name(tag));
+    if(job==IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
+    if(Marshal.GetLastWin32Error()==183) { CloseHandle(job); throw new Exception("Job name already exists"); }
+    ProcessInfo child=new ProcessInfo(); IntPtr attributes=IntPtr.Zero, jobs=IntPtr.Zero; bool initialized=false;
+    try {
+      Extended limits=new Extended(); limits.Basic.Flags=0x2000; // KILL_ON_JOB_CLOSE; never allow breakaway.
+      Check(SetInformationJobObject(job,9,ref limits,(uint)Marshal.SizeOf(typeof(Extended))));
+      UIntPtr bytes=UIntPtr.Zero; InitializeProcThreadAttributeList(IntPtr.Zero,1,0,ref bytes);
+      Check(bytes.ToUInt64()>0); attributes=Marshal.AllocHGlobal((IntPtr)(long)bytes.ToUInt64());
+      Check(InitializeProcThreadAttributeList(attributes,1,0,ref bytes)); initialized=true;
+      jobs=Marshal.AllocHGlobal(IntPtr.Size); Marshal.WriteIntPtr(jobs,job);
+      // PROC_THREAD_ATTRIBUTE_JOB_LIST assigns containment atomically with creation.
+      Check(UpdateProcThreadAttribute(attributes,0,new UIntPtr(0x2000du),jobs,new UIntPtr((uint)IntPtr.Size),IntPtr.Zero,IntPtr.Zero));
+      StartupEx startup=new StartupEx(); startup.Basic.Size=Marshal.SizeOf(typeof(StartupEx)); startup.Basic.Flags=0x100; startup.Attributes=attributes;
+      startup.Basic.Input=GetStdHandle(-10); startup.Basic.Output=GetStdHandle(-11); startup.Basic.Error=GetStdHandle(-12);
+      StringBuilder command=new StringBuilder(Quote(executable)); foreach(string arg in args) command.Append(" ").Append(Quote(arg));
+      Check(CreateProcess(executable,command,IntPtr.Zero,IntPtr.Zero,true,0x80004,IntPtr.Zero,cwd,ref startup,out child));
+      if(!OwnerAlive(ownerPid,ownerStart)) throw new Exception("Probe owner exited before startup");
+      Check(ResumeThread(child.Thread)!=0xffffffff);
+      while(true) {
+        uint waited=WaitForSingleObject(child.Process,100);
+        if(waited==0) break;
+        Check(waited==258); // WAIT_TIMEOUT
+        if(!OwnerAlive(ownerPid,ownerStart)) { TerminateJobObject(job,125); throw new Exception("Probe owner exited"); }
+      }
+      uint code; Check(GetExitCodeProcess(child.Process,out code));
+      Check(TerminateJobObject(job,0));
+      DateTime deadline=DateTime.UtcNow.AddSeconds(5);
+      while(Active(job)!=0 && DateTime.UtcNow<deadline) Thread.Sleep(25);
+      if(Active(job)!=0) throw new Exception("Job cleanup could not be verified");
+      return unchecked((int)code);
+    } finally {
+      if(initialized) DeleteProcThreadAttributeList(attributes);
+      if(attributes!=IntPtr.Zero) Marshal.FreeHGlobal(attributes);
+      if(jobs!=IntPtr.Zero) Marshal.FreeHGlobal(jobs);
+      if(child.Thread!=IntPtr.Zero) CloseHandle(child.Thread);
+      if(child.Process!=IntPtr.Zero) CloseHandle(child.Process);
+      CloseHandle(job);
+    }
+  }
+}`;
+function encoded(script) { return ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")]; }
+const declaration = `$ErrorActionPreference='Stop'; Add-Type -TypeDefinition @'\n${WINDOWS_JOB_SOURCE}\n'@;`;
+/** Standard npm shims are invoked as Node argv, never interpreted as shell text. */
+export function windowsRuntimeInvocation(executable, args) {
+    if (!/\.(cmd|bat)$/i.test(executable))
+        return { executable, args };
+    const shim = readFileSync(executable, "utf8");
+    const match = /"%(?:dp0%|~dp0)[\\/]*([^"\r\n]+\.[cm]?js)"/i.exec(shim);
+    if (!match)
+        throw new Error("Unsupported Windows runtime shim; install the provider's standard npm shim or native executable");
+    const script = join(dirname(executable), match[1]);
+    if (!existsSync(script))
+        throw new Error("Windows runtime shim target is missing");
+    return { executable: process.execPath, args: [script, ...args] };
+}
+export function windowsProbeCommand(tag, executable, args, cwd, ownerStart, gated = false) {
+    if (!/^[a-f0-9-]{36}$/.test(tag))
+        throw new Error("Invalid Windows job identity");
+    if (!/^win:\d+$/.test(ownerStart))
+        throw new Error("Windows probe owner identity is unavailable");
+    const target = windowsRuntimeInvocation(executable, args);
+    return {
+        executable: join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
+        args: encoded(`${gated ? "if ([Console]::In.ReadLine() -ne 'rafi-create-job') { exit 125 };" : ""}${declaration}\n$c=ConvertFrom-Json $env:RAFI_WINDOWS_PROBE_CONFIG; Remove-Item Env:RAFI_WINDOWS_PROBE_CONFIG; $code=[RafiProbeJob]::Run([string]$c.tag,[string]$c.executable,[string[]]$c.args,[string]$c.cwd,[int]$c.ownerPid,[long]$c.ownerStart); exit $code`),
+        config: JSON.stringify({ tag, ...target, cwd, ownerPid: process.pid, ownerStart: ownerStart.slice(4) }),
+    };
+}
+export function windowsProbeJobState(tag, timeoutMs = 10_000) {
+    if (!/^[a-f0-9-]{36}$/.test(tag))
+        return "unknown";
+    try {
+        const powershell = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+        const output = execFileSync(powershell, encoded(`${declaration}\n[RafiProbeJob]::Query('${tag}')`), { encoding: "utf8", timeout: Math.max(1, timeoutMs), stdio: ["ignore", "pipe", "ignore"] }).trim();
+        return output === "absent" || output === "empty" || output === "active" ? output : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}

package/dist/workflowDb.d.ts

@@ -1,5 +1,13 @@
+import { type GraphDerivedAccess } from "./graph/derived.js";
+import { QaPreparationStore } from "./qaPreparationStore.js";
+import { GraphStore } from "./graph/storage.js";
+import { reconcileWork, type BuildOwnershipRepairV1 } from "./buildWorkReconciliation.js";
+import { verifyGuidance, verifyBuilderGuidance, finishGuidance, type InstructionRecipient } from "./buildInterventions.js";
+import { type AdmitWorkInput } from "./buildWorkAdmission.js";
+import { type ReadinessProcess } from "./readinessCleanup.js";
+import { type BuildAdmission, type BuildLaunch } from "./buildAdmission.js";
 import type { BuildRecoveryDecisionReceipt, ContextSample, ContinuityCheckpoint, ContinuityDelta, ContinuityEvent, ContinuityHead, ContinuityHeadState, HandoffLineage, HandoffAcceptanceReceiptV1, HandoffManifestV1, LiveSettingsAcknowledgment, OperationLifecycle, PendingHumanDecision, ProviderSessionRefV1, RecoveryAttemptOutcome, RecoveryAttemptReceipt, ResolvedAutonomyPolicy, ResolvedAgentSettings, SessionUsageSample, StructuredInterruption, SupervisorState, WorkflowIssue } from "rafi-spec";
-import type { QaDeliveryTurnV3, QaDeliveryOutcome, QaDeliveryInvocationV3 } from "./qaDeliveryJournal.js";
+import type { QaDeliveryTurn, QaDeliveryOutcome, QaDeliveryInvocationV3 } from "./qaDeliveryJournal.js";
 import type { BranchResumeSession } from "./branch/resume.js";
 import { type BuilderRemediationReceiptV2, type BuilderRemediationReceiptV3, type FrozenQaSourceStateV2, type HandoffAcceptanceReceiptV2, type QaPassCertificateV2, type QaReducerEventV2, type QaReducerStateV2, type QaReportDisposition, type QaReviewBasisV2, type QaTurnIntentV2, type QaTurnReceiptV2 } from "./qaProtocolV2.js";
 export declare const WORKFLOW_DB_FILE = ".rafi/recovery.sqlite3";
@@ -196,12 +204,101 @@ export interface QaReportRecordV2 {
 /** Authoritative persistence for every resumable workflow in a project. */
 export declare class WorkflowDb {
     readonly projectDir: string;
+    private readonly readinessAccess?;
     readonly path: string;
     private readonly db;
-    constructor(projectDir: string, path?: string);
+    private writerAuthority?;
+    private writerLease?;
+    private coordinatorTransition;
+    private lineageTransition;
+    private workAuthority;
+    constructor(projectDir: string, path?: string, readinessAccess?: {
+        probeId: string;
+    } | {
+        runId: string;
+    } | undefined);
+    /** Connection-local SQL fences: helper/reconciler cannot gain general writer rights. */
+    private restrictReadinessConnection;
     close(): void;
+    qaPreparationStore(): QaPreparationStore;
+    graphStore(): GraphStore;
+    admitWork(input: AdmitWorkInput): import("rafi-spec").BuildWorkAdmissionV1;
+    private assertInstructionOwner;
+    reserveGuidance(runId: string, workId: string, recipient: InstructionRecipient, operationId: string, sourceDigest: string, text: string, reserve?: boolean): {
+        text: string;
+        ids: string[];
+    };
+    reconcileInstructionDeliveries(runId: string, workId: string): void;
+    decisionWorkId(decision: PendingHumanDecision): string | undefined;
+    finishGuidance(ids: string[], recipient: InstructionRecipient, result: Parameters<typeof finishGuidance>[3]): void;
+    builderVerificationContext(runId: string, workId: string, sourceDigest: string): {
+        text: string;
+        ids: string[];
+    };
+    verifyBuilderGuidance(ids: string[], certificate: Parameters<typeof verifyBuilderGuidance>[2], response: string, receiptDigest: string): void;
+    verifyGuidance(ids: string[], certificate: Parameters<typeof verifyGuidance>[2], response: string): void;
+    hasQueuedBuilderGuidance(runId: string, workId: string): boolean;
+    instruction(id: string): import("./buildInterventions.js").BuildInstruction | undefined;
+    assertFinalizationControls(runId: string, workId: string): void;
+    consumeInstructionControls(runId: string, workId: string, kind?: "questions" | "attempts"): string | undefined;
+    reconcileWork(request: BuildOwnershipRepairV1, input: Parameters<typeof reconcileWork>[2]): Record<string, unknown>;
+    reconciliation(id: string): Record<string, unknown> | undefined;
+    workDefinitions(runId: string): Array<{
+        workId: string;
+        kind: string;
+        definition: unknown;
+    }>;
+    recordWorkAssignment(runId: string, workId: string, operationId: string, record: unknown): void;
+    admittedWork(runId: string, workId: string): import("rafi-spec").BuildWorkAdmissionV1 | undefined;
+    assertAdmittedWork(runId: string, workId: string): import("rafi-spec").BuildWorkAdmissionV1;
     /** Atomic local changes only; never await provider or filesystem work here. */
     atomic<T>(work: () => T): T;
+    buildAdmission(): BuildAdmission | undefined;
+    private assertNoLegacyBuildOwner;
+    private assertExecutionProtocol;
+    acquireBuildAdmission(runId: string, phase: BuildAdmission["phase"]): BuildAdmission;
+    acquireBuildRecoveryAdmission(runId: string): BuildAdmission;
+    admitLeasedBuild(lease: ProjectLease): BuildAdmission;
+    reacquireBuildCoordinator(runId: string): BuildAdmission;
+    assertBuildAdmission(authority: BuildAdmission): void;
+    releaseBuildAdmission(authority: BuildAdmission): void;
+    reserveBuildLaunch(authority: BuildAdmission, role: BuildAdmission["phase"], digest: string, protocol?: BuildLaunch["protocol"]): BuildLaunch;
+    dispatchBuildLaunch(authority: BuildAdmission, token: string): void;
+    failBuildLaunch(authority: BuildAdmission, token: string): void;
+    claimBuildLaunch(runId: string, token: string, role: BuildAdmission["phase"], digest: string): BuildAdmission;
+    registerBuildLaunchChild(token: string): void;
+    acknowledgeBuildLaunchChild(authority: BuildAdmission, token: string, pid: number): void;
+    reconcileBuildLaunches(runId: string, original?: BuildAdmission): "retired" | "claimed" | "unknown";
+    buildLaunch(token: string): BuildLaunch | undefined;
+    preparationSuccessor(runId: string): string;
+    reservePreparationRetry(predecessor: string, args: string[], expectedStartArgs?: string): {
+        runId: string;
+        launch: BuildLaunch;
+        authority: BuildAdmission;
+    };
+    beginOwnedPreparationProcess(authority: BuildAdmission, tag?: string, gated?: boolean): string;
+    recordOwnedPreparationProcess(authority: BuildAdmission, id: string, pid: number): void;
+    finishOwnedPreparationProcess(authority: BuildAdmission, id: string, noChild?: boolean, outcome?: {
+        ready: boolean;
+        exitCode: number | null;
+        timedOut: boolean;
+        cancelled: boolean;
+    }): void;
+    readinessProcesses(runId?: string): ReadinessProcess[];
+    unresolvedPreparationProcesses(runId: string): string[];
+    registerReadinessHelper(id: string): void;
+    authorizeReadinessHelper(authority: BuildAdmission, id: string, pid: number): void;
+    assertReadinessHelper(id: string): ReadinessProcess;
+    recordReadinessCreator(id: string, pid: number): void;
+    private assertReadinessRelationships;
+    readinessCleanupDetails(runId: string): string[];
+    private assertReadinessCleanupOwner;
+    revokeReadinessHelper(id: string, original?: BuildAdmission): void;
+    reconcileReadiness(runId: string, original?: BuildAdmission, deadline?: number): Promise<string[]>;
+    preparationEligibility(runId: string): {
+        eligible: boolean;
+        reasons: string[];
+    };
     /** Ensure non-workflow build records can use the same durable event store. */
     ensureRun(runId: string, kind?: WorkflowKind, now?: Date): WorkflowRunSnapshot;
     createRun(input: {
@@ -219,6 +316,13 @@ export declare class WorkflowDb {
     completedPlanApprovals(): Array<Record<string, unknown>>;
     activeRuns(): WorkflowRunSnapshot[];
     resumableRuns(kind?: WorkflowKind): WorkflowRunSnapshot[];
+    /** Supervisors may pause a worker generation; they cannot publish worker state. */
+    transitionSupervisor(runId: string, workerGeneration: number, update: {
+        status?: WorkflowRunStatus;
+        checkpoint: string;
+        event?: string;
+        payload?: unknown;
+    }): WorkflowRunSnapshot;
     transition(runId: string, update: {
         status?: WorkflowRunStatus;
         checkpoint: string;
@@ -264,6 +368,7 @@ export declare class WorkflowDb {
     }, now?: Date): ContinuityCheckpoint;
     continuityCheckpoints(runId: string, role?: "builder" | "qa"): ContinuityCheckpoint[];
     latestContinuityCheckpoint(runId: string, role: "builder" | "qa"): ContinuityCheckpoint | undefined;
+    private assertGraphContinuityAccess;
     continuityHead(runId: string, role: "builder" | "qa" | "run"): ContinuityHead | undefined;
     setContinuityHeadState(runId: string, role: "builder" | "qa", state: ContinuityHeadState, now?: Date): ContinuityHead | undefined;
     recordSession(runId: string, role: string, stream: string, session: string | ProviderSessionRefV1 | undefined, transition: string, settings: ResolvedAgentSettings, now?: Date): void;
@@ -289,9 +394,16 @@ export declare class WorkflowDb {
         choices: PendingHumanDecision["choices"];
         evidence?: PendingHumanDecision["evidence"];
     }, now?: Date): PendingHumanDecision;
+    cancelPendingHumanDecisions(runId: string, reason: string, now?: Date): void;
+    humanDecisionKey(decisionId: string): string | undefined;
     humanDecision(decisionId: string): PendingHumanDecision | undefined;
     pendingHumanDecisions(runId: string): PendingHumanDecision[];
+    decisionContinuationAvailable(runId: string, decisionId: string): boolean;
+    nextDecisionContinuationKey(runId: string, decisionId: string): string;
     answeredTicketDecisions(runId: string, scopeRevision: string): PendingHumanDecision[];
+    /** Unconsumed answers to an older definition must not silently reopen a ticket. */
+    staleTicketDecisions(runId: string, scopeRevision: string): PendingHumanDecision[];
+    refreshStaleTicketDecisions(runId: string, scopeRevision: string, tickets?: readonly string[]): void;
     answerHumanDecision(runId: string, decisionId: string, choiceId: string, now?: Date, answer?: string): PendingHumanDecision;
     putSupervisorState(runId: string, state: SupervisorState, now?: Date): SupervisorState;
     runningSupervisors(): Array<{
@@ -315,6 +427,7 @@ export declare class WorkflowDb {
     operation(idempotencyKey: string): OperationRecord | undefined;
     operations(runId: string): OperationRecord[];
     putEvidence(kind: "handoff" | "diff" | "test" | "qa", value: string | Buffer, now?: Date): string;
+    registerGraphEvidence(value: string | Buffer, access: GraphDerivedAccess | GraphDerivedAccess[]): void;
     getEvidence(digest: string): Buffer | undefined;
     putQaRecoveryHead(input: Omit<QaRecoveryHeadRecord, "updatedAt">, now?: Date): QaRecoveryHeadRecord;
     qaRecoveryHead(runId: string, ticketId?: string): QaRecoveryHeadRecord | undefined;
@@ -329,8 +442,8 @@ export declare class WorkflowDb {
     qaRemediationAttempts(runId: string, ticketId: string): QaRemediationAttemptRecord[];
     qaRemediationAttempt(attemptId: string): QaRemediationAttemptRecord | undefined;
     recordQaDeliveryInvocation(record: QaDeliveryInvocationV3): void;
-    recordQaDeliveryTurn(turn: QaDeliveryTurnV3): void;
-    qaDeliveryTurns(operationId: string): QaDeliveryTurnV3[];
+    recordQaDeliveryTurn(turn: QaDeliveryTurn): void;
+    qaDeliveryTurns(operationId: string): QaDeliveryTurn[];
     /** Attempts, including ambiguous intents, are the common legacy/production ledger. */
     qaAutomaticRemediationCount(runId: string, ticketId: string): number;
     authorizeQaRemediation(runId: string, ticketId: string, reviewAttemptId: string, reason: string): string;
@@ -405,7 +518,8 @@ export declare class WorkflowDb {
     setQaReportDisposition(reportDigest: string, disposition: QaReportDisposition, reason: string, now?: Date): void;
     markQaReportsRecheckRequired(runId: string, ticketId: string, reason: string, now?: Date): void;
     resolveQaReportsAfterPass(runId: string, ticketId: string, now?: Date): void;
-    commitQaWaiver(runId: string, ticketId: string, expectedRevision: number, reason: string, now?: Date): QaReducerStateV2;
+    authorizeContractQaWaiver(runId: string, workId: string, decisionId: string): string;
+    commitQaWaiver(runId: string, ticketId: string, expectedRevision: number, reason: string, now?: Date, authorizationRef?: string): QaReducerStateV2;
     builderRemediationReceipt(operationId: string): BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3 | undefined;
     recordBuilderRemediationReceipt(receipt: BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3): void;
     commitBuilderRemediationSuccess(receipt: BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3, expectedRevision: number, now?: Date): QaReducerStateV2;
@@ -419,12 +533,13 @@ export declare class WorkflowDb {
         receipt?: BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3;
         expectedRevision: number;
     }, now?: Date): QaReducerStateV2;
+    private assertContractCertificate;
     issueQaPassCertificate(input: Omit<QaPassCertificateV2, "version" | "certificateId" | "unresolvedReportCount" | "issuedAt">, now?: Date): QaPassCertificateV2;
     commitQaPass(input: Omit<QaPassCertificateV2, "version" | "certificateId" | "unresolvedReportCount" | "issuedAt">, expectedRevision: number, now?: Date): QaPassCertificateV2;
     /** Accept a passing verdict, its review-attempt outcome, report resolution, certificate, and reducer edge atomically. */
     commitQaPassAttempt(attemptId: string, input: Omit<QaPassCertificateV2, "version" | "certificateId" | "unresolvedReportCount" | "issuedAt">, detail: string, expectedRevision: number, now?: Date): QaPassCertificateV2;
     consumeQaPassCertificate(runId: string, ticketId: string, certificateId: string, consumer: string, now?: Date): QaPassCertificateV2;
-    invalidateUnconsumedQaPassCertificates(runId: string, ticketId: string, reason: string, now?: Date): void;
+    invalidateUnconsumedQaPassCertificates(runId: string, ticketId: string, reason: string, now?: Date, issuedBefore?: string): void;
     invalidateQaPassBeforeFinalization(input: {
         runId: string;
         ticketId: string;