ai-foreman 1.7.19 → 1.7.21

package/dist/buildWorkAuthorization.js

@@ -0,0 +1,23 @@
+import { WorkflowDb } from "./workflowDb.js";
+import { buildScopeRevision } from "./buildApproval.js";
+import { loadTicketsConfig, resolveTicketPaths } from "./tickets/config.js";
+import { loadTickets } from "./tickets/ticketLoader.js";
+import { qaDigest } from "./qaProtocolV2.js";
+/** Called by the CLI only after its source-bound approval gate succeeds. */
+export function admitApprovedTicket(projectDir, runId, ticketId, approvedRevision, authorization) {
+    const ticket = loadTickets(resolveTicketPaths(loadTicketsConfig(projectDir), projectDir).tickets).find(ticket => ticket.id === ticketId);
+    if (!ticket || buildScopeRevision(projectDir) !== approvedRevision)
+        throw new Error("Ticket requirements changed after approval; reselect and approve current work");
+    const db = new WorkflowDb(projectDir);
+    try {
+        db.atomic(() => {
+            const current = loadTickets(resolveTicketPaths(loadTicketsConfig(projectDir), projectDir).tickets).find(ticket => ticket.id === ticketId);
+            if (!current || buildScopeRevision(projectDir) !== approvedRevision || JSON.stringify(current) !== JSON.stringify(ticket))
+                throw new Error("Ticket eligibility or requirements changed during admission; reselect approved work");
+            db.admitWork({ runId, kind: "ticket", ticketId, definition: ticket, approvalId: qaDigest("build-work-approval", { runId, approvedRevision, authorization }), scopeRevision: approvedRevision, provenance: { userTurn: authorization, reason: "CLI source-bound build approval gate succeeded" } });
+        });
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/buildWorkContext.d.ts

@@ -0,0 +1,3 @@
+import type { TicketDef } from "./tickets/ticketSchema.js";
+/** Full authoritative definition, shared by initial/resumed/remediation paths. */
+export declare function renderBuildWorkContext(ticket: TicketDef, checklist: readonly string[]): string;

package/dist/buildWorkContext.js

@@ -0,0 +1,6 @@
+/** Full authoritative definition, shared by initial/resumed/remediation paths. */
+export function renderBuildWorkContext(ticket, checklist) {
+    return ["Full assigned work definition (scope authority):", JSON.stringify(ticket, null, 2),
+        "Project validation checklist:", ...(checklist.length ? checklist.map((item, index) => `${index + 1}. ${item}`) : ["No additional project checklist configured."]),
+        "Implement this assigned work and provide verification evidence. Final QA runs independently in a separate disposable snapshot and fresh reviewer conversation."].join("\n");
+}

package/dist/buildWorkMigration.d.ts

@@ -0,0 +1,9 @@
+import type Database from "better-sqlite3";
+export declare const BUILD_WORK_SCHEMA_VERSION = 4;
+/** A copied database must be rebound by state transfer, never by an ordinary writer. */
+export declare function assertBuildProject(db: Database.Database, projectDir: string): void;
+/** Classify legacy records without converting observed progress into permission. */
+export declare function migrateBuildWork(db: Database.Database, projectDir: string, faults?: {
+    beforeGuards?(): void;
+    beforeCommit?(): void;
+}): void;

package/dist/buildWorkMigration.js

@@ -0,0 +1,206 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, closeSync, cpSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { classifyProcess } from "./processIdentity.js";
+export const BUILD_WORK_SCHEMA_VERSION = 4;
+const migration = "004_admitted_build_work";
+/** A copied database must be rebound by state transfer, never by an ordinary writer. */
+export function assertBuildProject(db, projectDir) {
+    const identity = db.prepare("SELECT canonical_root FROM build_project_identity WHERE singleton=1").get();
+    if (identity.canonical_root !== realpathSync(projectDir))
+        throw new Error("Build project identity requires explicit state-transfer rebinding");
+}
+/** Classify legacy records without converting observed progress into permission. */
+export function migrateBuildWork(db, projectDir, faults) {
+    if (db.prepare("SELECT 1 FROM recovery_schema_migrations WHERE migration=?").get(migration)) {
+        assertBuildProject(db, projectDir);
+        return;
+    }
+    const lease = db.prepare("SELECT pid,process_start,host FROM project_lease").get();
+    if (lease && classifyProcess(lease.pid, lease.process_start, lease.host).state !== "dead")
+        throw new Error("Work admission upgrade requires stopped, verified writers and a consistent backup");
+    const owner = db.prepare("SELECT record_json FROM build_admission").get();
+    if (owner) {
+        const identity = JSON.parse(owner.record_json);
+        if (classifyProcess(identity.pid, identity.processStart, identity.host).state !== "dead")
+            throw new Error("Work admission upgrade requires a stopped, verified build owner");
+    }
+    const backup = db.serialize();
+    // The coherent WAL-visible backup survives even a rolled-back upgrade.
+    // Publish the packet copy and manifest before enabling any new writer.
+    const backupDigest = createHash("sha256").update(backup).digest("hex");
+    const backupRoot = join(projectDir, ".rafi", "backups", "work-admission-v4");
+    const backupPath = join(backupRoot, backupDigest);
+    mkdirSync(backupRoot, { recursive: true, mode: 0o700 });
+    if (!existsSync(backupPath)) {
+        const staging = join(backupRoot, `${backupDigest}.${randomUUID()}.tmp`);
+        mkdirSync(staging, { mode: 0o700 });
+        const file = join(staging, "recovery.sqlite3");
+        writeFileSync(file, backup, { mode: 0o600 });
+        const descriptor = openSync(file, "r");
+        try {
+            fsyncSync(descriptor);
+        }
+        finally {
+            closeSync(descriptor);
+        }
+        const packets = join(projectDir, ".foreman", "qa-report-recovery");
+        if (existsSync(packets))
+            cpSync(packets, join(staging, "qa-report-recovery"), { recursive: true, dereference: false });
+        const packetFiles = syncBackupTree(staging);
+        const manifest = join(staging, "manifest.json");
+        writeFileSync(manifest, JSON.stringify({ version: 1, databaseDigest: backupDigest, canonicalRoot: realpathSync(projectDir), createdAt: new Date().toISOString(), packetCopy: existsSync(packets), files: packetFiles }), { mode: 0o600 });
+        syncFile(manifest);
+        syncDirectory(staging);
+        renameSync(staging, backupPath);
+        syncDirectory(backupRoot);
+    }
+    if (createHash("sha256").update(readFileSync(join(backupPath, "recovery.sqlite3"))).digest("hex") !== backupDigest)
+        throw new Error("Work admission backup failed integrity verification; preserve state before retry");
+    try {
+        db.transaction(() => {
+            db.exec(`
+      CREATE TABLE build_work_upgrade_backup(singleton INTEGER PRIMARY KEY CHECK(singleton=1),database_bytes BLOB NOT NULL,created_at TEXT NOT NULL);
+      CREATE TABLE build_project_identity(singleton INTEGER PRIMARY KEY CHECK(singleton=1),project_id TEXT NOT NULL UNIQUE,canonical_root TEXT NOT NULL);
+      CREATE TABLE build_work_scope(run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),work_id TEXT NOT NULL,kind TEXT NOT NULL CHECK(kind IN ('ticket','synthetic')),ticket_id TEXT,state TEXT NOT NULL CHECK(state IN ('admitted','quarantined')),definition_json TEXT NOT NULL,PRIMARY KEY(run_id,work_id),UNIQUE(run_id,ticket_id),CHECK((kind='ticket' AND ticket_id=work_id) OR (kind='synthetic' AND ticket_id IS NULL)));
+      CREATE TABLE build_work_admissions(sequence INTEGER PRIMARY KEY AUTOINCREMENT,admission_id TEXT NOT NULL UNIQUE,run_id TEXT NOT NULL,work_id TEXT NOT NULL,assignment_id TEXT NOT NULL,approval_id TEXT NOT NULL,scope_revision TEXT NOT NULL,requirements_digest TEXT NOT NULL,record_json TEXT NOT NULL,admitted_at TEXT NOT NULL,FOREIGN KEY(run_id,work_id) REFERENCES build_work_scope(run_id,work_id));
+      CREATE TABLE build_assignments(assignment_id TEXT PRIMARY KEY,run_id TEXT NOT NULL,work_id TEXT NOT NULL,operation_id TEXT NOT NULL UNIQUE,record_json TEXT NOT NULL,FOREIGN KEY(run_id,work_id) REFERENCES build_work_scope(run_id,work_id));
+      CREATE TABLE build_ownership_conflicts(conflict_id TEXT PRIMARY KEY,run_id TEXT NOT NULL,work_id TEXT NOT NULL,status TEXT NOT NULL,revision INTEGER NOT NULL,record_json TEXT NOT NULL,FOREIGN KEY(run_id,work_id) REFERENCES build_work_scope(run_id,work_id));
+      CREATE TABLE build_work_events(sequence INTEGER PRIMARY KEY AUTOINCREMENT,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),work_id TEXT NOT NULL,table_name TEXT NOT NULL,record_key TEXT NOT NULL,action TEXT NOT NULL,record_json TEXT NOT NULL,created_at TEXT NOT NULL);
+      CREATE TABLE build_reconciliations(reconciliation_id TEXT PRIMARY KEY,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),expected_revision TEXT NOT NULL,record_json TEXT NOT NULL,created_at TEXT NOT NULL);
+    `);
+            const now = new Date().toISOString();
+            db.prepare("INSERT INTO build_work_upgrade_backup VALUES(1,?,?)").run(backup, now);
+            db.prepare("INSERT INTO build_project_identity VALUES(1,?,?)").run(randomUUID(), realpathSync(projectDir));
+            const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'qa_%'").all().filter(({ name }) => /^[a-z_]+$/.test(name));
+            for (const { name } of tables) {
+                const columns = db.prepare(`PRAGMA table_info(${name})`).all();
+                if (!columns.some(column => column.name === "run_id") || !columns.some(column => column.name === "ticket_id"))
+                    continue;
+                for (const row of db.prepare(`SELECT DISTINCT run_id,ticket_id FROM ${name}`).all()) {
+                    db.prepare("INSERT OR IGNORE INTO build_work_scope VALUES(?,?,'ticket',?,'quarantined','{}')").run(row.run_id, row.ticket_id, row.ticket_id);
+                    db.prepare("INSERT OR IGNORE INTO build_ownership_conflicts VALUES(?,?,?,'unresolved',1,?)").run(`legacy:${row.run_id}:${row.ticket_id}`, row.run_id, row.ticket_id, JSON.stringify({ reason: "Legacy QA progress is not proof of run-bound approval and assignment", classification: "ownership_unestablished", observedTable: name }));
+                }
+            }
+            faults?.beforeGuards?.();
+            // Replace V3 guards atomically. Old connections register 3 and fail even on heartbeat writes.
+            for (const trigger of db.prepare("SELECT name,sql FROM sqlite_master WHERE type='trigger' AND name LIKE 'handback_v3_%'").all()) {
+                db.exec(`DROP TRIGGER "${trigger.name}"`);
+                db.exec(trigger.sql.replace("rafi_writer_protocol() != 3", "rafi_writer_protocol() != 4"));
+            }
+            db.function("rafi_writer_protocol", () => 4);
+            for (const { name } of db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'build_%'").all()) {
+                if (!/^[a-z_]+$/.test(name))
+                    throw new Error("Unexpected build storage table");
+                for (const action of ["INSERT", "UPDATE", "DELETE"])
+                    db.exec(`CREATE TRIGGER IF NOT EXISTS work_v4_protocol_${name}_${action} BEFORE ${action} ON ${name} BEGIN SELECT CASE WHEN rafi_writer_protocol()<>4 THEN RAISE(ABORT,'incompatible work admission writer') END; END`);
+            }
+            for (const { name } of tables) {
+                const columns = db.prepare(`PRAGMA table_info(${name})`).all();
+                let scope;
+                if (columns.some(column => column.name === "run_id") && columns.some(column => column.name === "ticket_id"))
+                    scope = target => `s.run_id=${target}.run_id AND s.work_id=${target}.ticket_id`;
+                else if (columns.some(column => column.name === "run_id") && columns.some(column => column.name === "work_id"))
+                    scope = target => `s.run_id=${target}.run_id AND s.work_id=${target}.work_id`;
+                else if (name === "qa_preparation_attempts" || name === "qa_preparation_progress")
+                    scope = target => `EXISTS(SELECT 1 FROM qa_preparation_budgets b WHERE b.id=${target}.budget_id AND b.run_id=s.run_id AND b.work_id=s.work_id)`;
+                else if (name === "qa_contract_receipts")
+                    scope = target => `EXISTS(SELECT 1 FROM qa_verification_contracts c WHERE c.digest=${target}.contract_digest AND c.run_id=s.run_id AND c.work_id=s.work_id)`;
+                else if (columns.some(column => column.name === "report_occurrence_id"))
+                    scope = target => `EXISTS(SELECT 1 FROM qa_reports r WHERE r.report_occurrence_id=${target}.report_occurrence_id AND r.run_id=s.run_id AND r.ticket_id=s.work_id)`;
+                else if (columns.some(column => column.name === "operation_id"))
+                    scope = target => `EXISTS(SELECT 1 FROM qa_turns t WHERE t.operation_id=${target}.operation_id AND t.run_id=s.run_id AND t.ticket_id=s.work_id)`;
+                else
+                    continue;
+                for (const action of ["INSERT", "UPDATE", "DELETE"]) {
+                    const target = action === "DELETE" ? "OLD" : "NEW";
+                    db.exec(`CREATE TRIGGER work_v4_scope_${name}_${action} BEFORE ${action} ON ${name} WHEN NOT EXISTS(SELECT 1 FROM build_work_scope s WHERE ${scope(target)} AND s.state='admitted') BEGIN SELECT RAISE(ABORT,'QA work is not admitted; reconcile ownership first'); END`);
+                }
+            }
+            for (const { name } of tables) {
+                const columns = db.prepare(`PRAGMA table_info(${name})`).all();
+                if (!columns.some(column => column.name === "run_id") || !columns.some(column => column.name === "ticket_id"))
+                    continue;
+                const keys = columns.filter(column => column.pk).sort((a, b) => a.pk - b.pk).map(column => `NEW.${column.name}`);
+                const retained = columns.filter(column => column.pk || ["status", "state", "disposition", "review_number", "from_revision", "to_revision", "source_digest", "source_state_digest", "report_digest", "review_basis_digest", "certificate_id", "generation", "request_digest", "response_digest", "summary_digest", "event_json"].includes(column.name)).flatMap(column => [`'${column.name}'`, `NEW.${column.name}`]);
+                for (const action of ["INSERT", "UPDATE"])
+                    db.exec(`CREATE TRIGGER work_v4_order_${name}_${action} AFTER ${action} ON ${name} BEGIN INSERT INTO build_work_events(run_id,work_id,table_name,record_key,action,record_json,created_at) VALUES(NEW.run_id,NEW.ticket_id,'${name}',json_array(${keys.join(",")}), '${action.toLowerCase()}',json_object(${retained.join(",")}),strftime('%Y-%m-%dT%H:%M:%fZ','now')); END`);
+            }
+            for (const { name } of tables) {
+                const columns = db.prepare(`PRAGMA table_info(${name})`).all();
+                if (columns.some(column => column.name === "run_id") && columns.some(column => column.name === "ticket_id"))
+                    db.exec(`CREATE TRIGGER work_v4_identity_${name} BEFORE UPDATE ON ${name} WHEN NEW.run_id<>OLD.run_id OR NEW.ticket_id<>OLD.ticket_id BEGIN SELECT RAISE(ABORT,'Scoped QA identity is immutable'); END`);
+            }
+            for (const action of ["INSERT", "UPDATE"]) {
+                db.exec(`CREATE TRIGGER work_v4_report_parent_${action} BEFORE ${action} ON qa_reports WHEN NOT EXISTS(SELECT 1 FROM qa_review_attempts p WHERE p.run_id=NEW.run_id AND p.ticket_id=NEW.ticket_id AND p.review_number=NEW.review_number AND p.source_digest=NEW.source_state_digest AND p.report_digest=NEW.report_digest) BEGIN SELECT RAISE(ABORT,'QA report parent ownership mismatch'); END;
+        CREATE TRIGGER work_v4_chain_parent_${action} BEFORE ${action} ON qa_report_chains WHEN NOT EXISTS(SELECT 1 FROM qa_reports p JOIN qa_reports s ON p.run_id=s.run_id AND p.ticket_id=s.ticket_id WHERE p.report_occurrence_id=NEW.predecessor_occurrence_id AND s.report_occurrence_id=NEW.successor_occurrence_id AND p.report_digest=NEW.predecessor_report_digest AND s.report_digest=NEW.successor_report_digest) BEGIN SELECT RAISE(ABORT,'QA report chain parent ownership mismatch'); END;
+        CREATE TRIGGER work_v4_assignment_${action} BEFORE ${action} ON operation_journal WHEN NEW.kind='build-assignment' AND NOT EXISTS(SELECT 1 FROM build_work_scope s WHERE s.run_id=NEW.run_id AND s.work_id=json_extract(NEW.intent_json,'$.ticketId') AND s.state='admitted') BEGIN SELECT RAISE(ABORT,'Builder assignment is not admitted'); END;
+        CREATE TRIGGER work_v4_branch_${action} BEFORE ${action} ON branch_resume_sessions WHEN NOT EXISTS(SELECT 1 FROM build_work_scope s WHERE s.run_id=NEW.run_id AND s.work_id=NEW.ticket AND s.state='admitted') BEGIN SELECT RAISE(ABORT,'Branch work is not admitted'); END;`);
+            }
+            db.exec(`CREATE TRIGGER work_v4_membership_update BEFORE UPDATE OF state_json ON workflow_runs WHEN EXISTS(SELECT 1 FROM build_work_admissions a WHERE a.run_id=NEW.run_id AND NOT EXISTS(SELECT 1 FROM json_each(NEW.state_json,'$.tickets') j WHERE j.value=a.work_id)) AND json_extract(NEW.state_json,'$.version') IS NOT NULL BEGIN SELECT RAISE(ABORT,'Build snapshot cannot drop admitted work'); END;
+      CREATE TRIGGER work_v4_admission_update BEFORE UPDATE ON build_work_admissions BEGIN SELECT RAISE(ABORT,'Work admissions are immutable'); END;
+      CREATE TRIGGER work_v4_admission_delete BEFORE DELETE ON build_work_admissions BEGIN SELECT RAISE(ABORT,'Work admissions are immutable'); END;
+      CREATE TRIGGER work_v4_scope_identity BEFORE UPDATE ON build_work_scope WHEN NEW.run_id<>OLD.run_id OR NEW.work_id<>OLD.work_id OR NEW.kind<>OLD.kind OR NEW.ticket_id IS NOT OLD.ticket_id BEGIN SELECT RAISE(ABORT,'Work identity is immutable'); END;
+      CREATE TRIGGER work_v4_scope_delete BEFORE DELETE ON build_work_scope BEGIN SELECT RAISE(ABORT,'Work scope must be retained'); END;`);
+            for (const table of ["build_work_scope", "build_work_admissions", "build_assignments", "build_ownership_conflicts", "build_reconciliations"]) {
+                for (const action of ["INSERT", "UPDATE", "DELETE"])
+                    db.exec(`CREATE TRIGGER work_v4_authority_${table}_${action} BEFORE ${action} ON ${table} WHEN rafi_work_authority()=0 BEGIN SELECT RAISE(ABORT,'Restricted work admission authority required'); END`);
+            }
+            for (const action of ["INSERT", "UPDATE"])
+                db.exec(`CREATE TRIGGER work_v4_remediation_parent_${action} BEFORE ${action} ON qa_remediation_attempts WHEN NOT EXISTS(SELECT 1 FROM qa_review_attempts p WHERE p.attempt_id=NEW.review_attempt_id AND p.run_id=NEW.run_id AND p.ticket_id=NEW.ticket_id) BEGIN SELECT RAISE(ABORT,'Remediation parent ownership mismatch'); END;
+      CREATE TRIGGER work_v4_finalization_parent_${action} BEFORE ${action} ON qa_finalization_steps WHEN NOT EXISTS(SELECT 1 FROM qa_pass_certificates p WHERE p.certificate_id=NEW.certificate_id AND p.run_id=NEW.run_id AND p.ticket_id=NEW.ticket_id) BEGIN SELECT RAISE(ABORT,'Finalization parent ownership mismatch'); END;
+      CREATE TRIGGER work_v4_handoff_parent_${action} BEFORE ${action} ON qa_failure_handoffs WHEN NOT EXISTS(SELECT 1 FROM qa_reports p JOIN qa_review_attempts a ON a.run_id=p.run_id AND a.ticket_id=p.ticket_id AND a.review_number=p.review_number WHERE p.report_occurrence_id=NEW.report_occurrence_id AND p.run_id=NEW.run_id AND p.ticket_id=NEW.ticket_id AND p.report_digest=NEW.report_digest AND a.attempt_id=NEW.review_attempt_id) BEGIN SELECT RAISE(ABORT,'Failure handoff parent ownership mismatch'); END;
+      CREATE TRIGGER work_v4_authorization_parent_${action} BEFORE ${action} ON qa_remediation_authorizations WHEN NOT EXISTS(SELECT 1 FROM qa_review_attempts p WHERE p.attempt_id=NEW.review_attempt_id AND p.run_id=NEW.run_id AND p.ticket_id=NEW.ticket_id) BEGIN SELECT RAISE(ABORT,'Authorization parent ownership mismatch'); END;`);
+            for (const action of ["INSERT", "UPDATE"]) {
+                db.exec(`CREATE TRIGGER work_v4_delivery_parent_${action} BEFORE ${action} ON qa_delivery_turns WHEN NOT EXISTS(SELECT 1 FROM qa_failure_handoffs h WHERE h.operation_id=NEW.operation_id AND h.report_occurrence_id=NEW.report_occurrence_id) BEGIN SELECT RAISE(ABORT,'QA delivery parent ownership mismatch'); END`);
+                for (const table of ["qa_findings", "qa_report_dispositions"])
+                    db.exec(`CREATE TRIGGER work_v4_occurrence_digest_${table}_${action} BEFORE ${action} ON ${table} WHEN NOT EXISTS(SELECT 1 FROM qa_reports r WHERE r.report_occurrence_id=NEW.report_occurrence_id AND r.report_digest=NEW.report_digest) BEGIN SELECT RAISE(ABORT,'QA occurrence digest ownership mismatch'); END`);
+            }
+            db.exec(`CREATE TRIGGER work_v4_delivery_identity BEFORE UPDATE ON qa_delivery_turns WHEN NEW.operation_id<>OLD.operation_id OR NEW.report_occurrence_id<>OLD.report_occurrence_id OR NEW.turn_index<>OLD.turn_index OR NEW.turn_record_id<>OLD.turn_record_id BEGIN SELECT RAISE(ABORT,'QA delivery identity is immutable'); END`);
+            for (const action of ["INSERT", "UPDATE"])
+                db.exec(`CREATE TRIGGER work_v4_certificate_parent_${action} BEFORE ${action} ON qa_pass_certificates WHEN NOT EXISTS(SELECT 1 FROM qa_turns t JOIN qa_turn_events e ON e.operation_id=t.operation_id AND e.event_index=0 WHERE t.run_id=NEW.run_id AND t.ticket_id=NEW.ticket_id AND t.source_state_digest=NEW.source_state_digest AND t.review_basis_digest=NEW.review_basis_digest AND t.status='completed' AND e.event_digest=NEW.turn_receipt_digest AND e.event_json=t.receipt_json AND json_extract(t.receipt_json,'$.terminalEventObserved')=1 AND length(json_extract(t.receipt_json,'$.providerTurnId'))>0) BEGIN SELECT RAISE(ABORT,'QA certificate completion receipt ownership mismatch'); END`);
+            for (const table of ["build_reconciliations", "build_work_events"])
+                for (const action of ["UPDATE", "DELETE"])
+                    db.exec(`CREATE TRIGGER work_v4_immutable_${table}_${action} BEFORE ${action} ON ${table} BEGIN SELECT RAISE(ABORT,'Build audit history is immutable'); END`);
+            faults?.beforeCommit?.();
+            if (db.pragma("foreign_key_check").length || db.pragma("integrity_check", { simple: true }) !== "ok")
+                throw new Error("Work admission upgrade integrity failure");
+            db.prepare("INSERT INTO recovery_schema_migrations VALUES(?,?)").run(migration, now);
+            db.pragma("user_version = 4");
+        }).immediate();
+    }
+    catch (error) {
+        db.function("rafi_writer_protocol", () => 3);
+        throw error;
+    }
+}
+function syncFile(path) { const descriptor = openSync(path, "r"); try {
+    fsyncSync(descriptor);
+}
+finally {
+    closeSync(descriptor);
+} }
+function syncDirectory(path) { if (process.platform !== "win32")
+    syncFile(path); }
+function syncBackupTree(root) {
+    const files = [];
+    const visit = (directory) => {
+        chmodSync(directory, 0o700);
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory())
+                visit(path);
+            else {
+                const bytes = entry.isSymbolicLink() ? Buffer.from(readlinkSync(path)) : readFileSync(path);
+                if (!entry.isSymbolicLink()) {
+                    chmodSync(path, 0o600);
+                    syncFile(path);
+                }
+                files.push({ path: relative(root, path), kind: entry.isSymbolicLink() ? "symlink" : "file", digest: createHash("sha256").update(bytes).digest("hex") });
+            }
+        }
+        syncDirectory(directory);
+    };
+    visit(root);
+    return files.sort((a, b) => a.path.localeCompare(b.path));
+}

package/dist/buildWorkReconciliation.d.ts

@@ -0,0 +1,12 @@
+import type Database from "better-sqlite3";
+import { type BuildOwnershipRepairV1 } from "rafi-spec";
+export type { BuildOwnershipRepairV1 } from "rafi-spec";
+export declare function validateOwnershipRepair(value: unknown): asserts value is BuildOwnershipRepairV1;
+/** Audited metadata repair; source separation/restoration must be inspected before this commit. */
+export declare function reconcileWork(db: Database.Database, request: BuildOwnershipRepairV1, input: {
+    revision: string;
+    sourceDigest: string;
+    definition: unknown;
+    requiredPaths: string[];
+    userTurn: string;
+}): Record<string, unknown>;

package/dist/buildWorkReconciliation.js

@@ -0,0 +1,70 @@
+import { realpathSync } from "node:fs";
+import { admitWork } from "./buildWorkAdmission.js";
+import { qaDigest } from "./qaProtocolV2.js";
+import { validateBuildOwnershipRepairV1 } from "rafi-spec";
+export function validateOwnershipRepair(value) {
+    const validation = validateBuildOwnershipRepairV1(value);
+    if (!validation.valid)
+        throw new Error(`Invalid ownership repair: ${validation.errors.join("; ")}`);
+    const request = value;
+    if ([request.authorization, request.attestation].some(text => !text.trim() || Buffer.byteLength(text) > 16384))
+        throw new Error("Repair requires bounded authorization and attestation");
+    if (new Set(request.mapping.map(item => item.path)).size !== request.mapping.length)
+        throw new Error("Repair mapping paths must be unique");
+}
+/** Audited metadata repair; source separation/restoration must be inspected before this commit. */
+export function reconcileWork(db, request, input) {
+    const prior = db.prepare("SELECT record_json FROM build_reconciliations WHERE reconciliation_id=?").get(request.requestId);
+    if (prior) {
+        const receipt = JSON.parse(prior.record_json);
+        if (receipt.requestDigest !== qaDigest("ownership-repair-request", request))
+            throw new Error("Repair idempotency key collision");
+        return receipt;
+    }
+    if (request.expectedRevision !== input.revision || request.inspectedSourceDigest !== input.sourceDigest)
+        throw new Error("Ownership or inspected source changed; inspect the current revision before repair");
+    if (input.requiredPaths.some(path => !request.mapping.some(item => item.path === path && item.workId === request.workId)))
+        throw new Error("Every preserved change must have an inspected mapping to the authorized target work");
+    if (request.mapping.some(item => item.workId !== request.workId || !input.requiredPaths.includes(item.path)))
+        throw new Error("Mapping contains a foreign work identity or an uninspected path");
+    const uncertain = db.prepare("SELECT 1 FROM operation_journal WHERE run_id=? AND kind='provider-dispatch' AND status IN ('in_progress','uncertain')").get(request.runId);
+    if (uncertain)
+        throw new Error("Provider dispatch must be reconciled separately before ownership repair; attestation cannot establish nonexecution");
+    if (request.choice === "link_provenance") {
+        const decision = request.decisionId ? db.prepare("SELECT * FROM human_decisions WHERE decision_id=? AND run_id=? AND status='answered'").get(request.decisionId, request.runId) : undefined;
+        const approval = decision ? JSON.parse(decision.decision_json) : undefined;
+        const assignments = db.prepare("SELECT intent_json,result_json FROM operation_journal WHERE run_id=? AND kind='build-assignment' AND json_extract(intent_json,'$.ticketId')=? AND status='confirmed'").all(request.runId, request.workId);
+        const assignment = assignments.some(row => {
+            const intent = JSON.parse(row.intent_json), result = JSON.parse(row.result_json), session = result.providerMetadata?.sessionRef;
+            if (result.rejection || result.sourceError || !result.turnId || !result.responseDigest || !result.after?.digest || !intent.before?.digest || intent.requirementsDigest !== qaDigest("admitted-requirements", input.definition) || !session || session.source !== "observed" || !session.validatedAt || session.role !== "builder" || session.ticketId !== request.workId)
+                return false;
+            try {
+                if (realpathSync(session.cwd) !== realpathSync(intent.worktree))
+                    return false;
+            }
+            catch {
+                return false;
+            }
+            return !!db.prepare("SELECT 1 FROM provider_sessions WHERE run_id=? AND role='builder' AND session_id=? AND session_ref_json=?").get(request.runId, session.sessionId, JSON.stringify(session));
+        });
+        const checkpoint = db.prepare("SELECT 1 FROM workflow_events WHERE run_id=? AND (json_extract(payload_json,'$.ticketId')=? OR json_extract(payload_json,'$.currentTicket')=?)").get(request.runId, request.workId, request.workId);
+        if (!decision?.decision_key.includes(request.scopeRevision) || approval?.selectedChoiceId !== "proceed" || !assignment || !checkpoint)
+            throw new Error("Approval, assignment and checkpoint provenance is incomplete; use explicit mapped-work authorization instead");
+    }
+    const now = new Date().toISOString();
+    const state = db.prepare("SELECT state FROM qa_ticket_heads WHERE run_id=? AND ticket_id=?").get(request.runId, request.workId)?.state;
+    const requiresFreshQa = request.choice !== "quarantine" && state !== "completed" && state !== "waived";
+    const receipt = { version: 1, reconciliationId: request.requestId, runId: request.runId, workId: request.workId, requestDigest: qaDigest("ownership-repair-request", request), request, userTurn: input.userTurn, beforeRevision: input.revision, sourceDigest: input.sourceDigest, historicalAuthorityProven: request.choice === "link_provenance", requiresFreshQa, executionDisposition: request.choice === "quarantine" ? "quarantined" : state === "completed" ? "terminal_metadata_repaired" : state === "waived" ? "existing_waiver_policy" : "fresh_qa_required", executionReopened: false, providerReplayAuthorized: false, createdAt: now };
+    db.prepare("INSERT INTO build_reconciliations VALUES(?,?,?,?,?)").run(request.requestId, request.runId, request.expectedRevision, JSON.stringify(receipt), now);
+    if (request.choice === "quarantine") {
+        db.prepare("UPDATE build_work_scope SET state='quarantined' WHERE run_id=? AND work_id=?").run(request.runId, request.workId);
+        db.prepare("UPDATE build_ownership_conflicts SET record_json=json_set(record_json,'$.manualDecision',?),revision=revision+1 WHERE run_id=? AND work_id=? AND status='unresolved'").run(request.requestId, request.runId, request.workId);
+        return receipt;
+    }
+    db.prepare("UPDATE build_work_scope SET state='admitted' WHERE run_id=? AND work_id=?").run(request.runId, request.workId);
+    admitWork(db, { runId: request.runId, kind: "ticket", ticketId: request.workId, definition: input.definition, approvalId: request.requestId, scopeRevision: request.scopeRevision, provenance: { userTurn: input.userTurn, decisionId: request.decisionId, reason: request.choice === "link_provenance" ? "Audited run-bound authorization provenance" : "Operator explicitly authorized inspected preserved changes for fresh verification" } }, true);
+    db.prepare("UPDATE build_ownership_conflicts SET status='reconciled',revision=revision+1,record_json=json_set(record_json,'$.reconciliationId',?) WHERE run_id=? AND work_id=? AND status='unresolved'").run(request.requestId, request.runId, request.workId);
+    // Retain every old byte and outcome. The audit permits fresh QA, never replay of this turn.
+    db.prepare("UPDATE operation_journal SET result_json=json_set(COALESCE(result_json,'{}'),'$.reconciliationId',?,'$.replayForbidden',1),updated_at=? WHERE run_id=? AND kind='build-assignment' AND json_extract(intent_json,'$.ticketId')=?").run(request.requestId, now, request.runId, request.workId);
+    return receipt;
+}

package/dist/builderGuidanceFollowup.d.ts

@@ -0,0 +1,15 @@
+import type { BuilderAdapter } from "./adapters/types.js";
+import { type BuilderGuidanceFollowup } from "./buildAssignment.js";
+import type { QaFixResult } from "./qaReview.js";
+/** One journaled mutation shared by current-branch and isolated-worktree resume. */
+export declare function deliverBuilderGuidanceFollowup(scope: {
+    projectDir: string;
+    runId: string;
+    ticketId: string;
+    worktree: string;
+}, instruction: string, followup: BuilderGuidanceFollowup, host: {
+    prepare(instruction: string): Promise<BuilderAdapter>;
+    validateRequirements(): void;
+    recordSession?(adapter: BuilderAdapter): void;
+    completed?(operationId: string, adapter: BuilderAdapter): Promise<void>;
+}): Promise<QaFixResult>;

package/dist/builderGuidanceFollowup.js

@@ -0,0 +1,34 @@
+import { collectBuilderContractCoverage } from "./qaBuilderCoverage.js";
+import { maintainGraphTask } from "./graph/boundary.js";
+import { ensureBuilderContract } from "./qaBuildGate.js";
+import { graphContext, sendGraphTurn } from "./graph/turn.js";
+import { beginBuildAssignment, finishBuildAssignment } from "./buildAssignment.js";
+import { parseStepStatus } from "./foreman.js";
+/** One journaled mutation shared by current-branch and isolated-worktree resume. */
+export async function deliverBuilderGuidanceFollowup(scope, instruction, followup, host) {
+    try {
+        const adapter = await host.prepare(instruction);
+        await adapter.prepareSession?.();
+        host.validateRequirements();
+        host.recordSession?.(adapter);
+        instruction += "\n" + await ensureBuilderContract(scope.projectDir, scope.runId, scope.ticketId, scope.worktree, adapter);
+        const assignment = beginBuildAssignment(scope.projectDir, scope.runId, scope.ticketId, scope.worktree, instruction, followup, adapter);
+        // The handback policy prevents provider wrappers from retrying this mutation.
+        const result = await sendGraphTurn(adapter, assignment.instruction, graphContext(scope.projectDir, scope.worktree, "manager-guidance", assignment.instruction, { logicalTaskId: assignment.operationId, operationId: assignment.operationId, runId: scope.runId, workId: scope.ticketId }), { handback: true, logicalActionId: assignment.operationId });
+        const status = parseStepStatus(result.text);
+        if (!result.isError && !result.failure && status.kind === "done")
+            await collectBuilderContractCoverage(scope.projectDir, scope.runId, scope.ticketId, scope.worktree, adapter, assignment.operationId, assignment.instruction, result);
+        const rejection = finishBuildAssignment(scope.projectDir, assignment, result, status);
+        if (!rejection && !result.isError && status.kind === "done")
+            await maintainGraphTask(scope.projectDir, scope.worktree, assignment.operationId, adapter).catch(() => undefined);
+        await host.completed?.(assignment.operationId, adapter);
+        if (rejection || result.isError || result.failure || status.kind !== "done" || !result.turnId)
+            return { ok: false, detail: rejection ?? result.failure?.diagnostics ?? `Builder follow-up stopped with ${status.kind}; reconcile its result before continuing`, response: result.text };
+        return { ok: true, response: result.text, summary: status.summary ?? "Builder applied waiting guidance", providerTurnId: result.turnId };
+    }
+    catch (error) {
+        // A thrown submission leaves the assignment in progress. The existing
+        // assignment fence prevents another Builder turn without reconciliation.
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/cli/doctor.js

@@ -11,6 +11,7 @@ import { resolveExecutablePath, sanitizeDiagnostics } from "../runtimeReadiness.
 import { ObservabilityReader, ObservabilityStore } from "../observability.js";
 import { WorkflowReader } from "../workflowReader.js";
 import { WorkflowDb } from "../workflowDb.js";
+import { error, success, warning } from "../terminalStyle.js";
 const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"))?.version;
 function commandVersion(command) {
     const result = spawnSync(command, ["--version"], {
@@ -41,12 +42,12 @@ export function buildDoctorCommand() {
         }
         let errors = 0;
         const report = (ok, label, detail) => {
-            console.log(`${ok ? "ok" : "!!"} ${label}${detail ? ` — ${detail}` : ""}`);
+            console.log(`${ok ? success("ok") : error("!!")} ${label}${detail ? ` — ${detail}` : ""}`);
             if (!ok)
                 errors++;
         };
         const warn = (label, detail) => {
-            console.log(`-- ${label}${detail ? ` — ${detail}` : ""}`);
+            console.log(`${warning("--")} ${label}${detail ? ` — ${detail}` : ""}`);
         };
         report(Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10) >= 20, "node >=20", process.version);
         report(Boolean(PACKAGE_VERSION), "foreman package version", PACKAGE_VERSION);

package/dist/cli/graph.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function buildGraphCommand(): Command;

package/dist/cli/graph.js

@@ -0,0 +1,75 @@
+import { pruneGraph } from "../graph/lifecycle.js";
+import { fileSemanticHost } from "../graph/semantic.js";
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { assertGraphConfig, assertGraphReadRequest, DEFAULT_GRAPH_CONFIG } from "rafi-spec";
+import { loadGraphConfig } from "../graph/config.js";
+import { adoptGraph, disableGraph, refreshGraph, ensureGraphInstallation } from "../graph/maintenance.js";
+import { acquireGraphView, graphStatus, readGraph } from "../graph/read.js";
+import { captureGraphCorpus } from "../graph/corpus.js";
+export function buildGraphCommand() {
+    const command = new Command("graph").description("Adopt and inspect scoped local Graphify evidence. Reads never install or refresh.");
+    command.command("status").argument("[project]", "project configuration root", ".").option("--json", "emit structured status").action((project) => {
+        const result = graphStatus(resolve(project));
+        console.log(JSON.stringify(result, null, 2));
+    });
+    command.command("adopt").argument("[project]", "project configuration root", ".").option("--yes", "accept the displayed scope and selective maintenance policy").option("--config <file>", "complete graph policy JSON").option("--code-only", "explicitly omit semantic extraction").action(async (project, opts) => {
+        const root = resolve(project);
+        const config = opts.config ? JSON.parse(readFileSync(resolve(opts.config), "utf8")) : structuredClone(DEFAULT_GRAPH_CONFIG);
+        if (opts.codeOnly)
+            config.mode = "code-only";
+        assertGraphConfig(config);
+        console.log(`Graphify adoption policy:\n${JSON.stringify(config, null, 2)}\nReuses a compatible installation or installs pinned Graphify in a Rafi-owned isolated environment. Initial extraction and selective maintenance are authorized by acceptance.`);
+        if (!opts.yes) {
+            if (!process.stdin.isTTY || !process.stdout.isTTY)
+                throw new Error("Adoption requires --yes and a complete policy in noninteractive mode");
+            const { confirm, isCancel } = await import("@clack/prompts");
+            const accepted = await confirm({ message: "Accept this Graphify scope and policy?", initialValue: true });
+            if (isCancel(accepted) || !accepted)
+                return;
+        }
+        const adoption = adoptGraph(root, { config, authorization: "explicit" });
+        const python = await ensureGraphInstallation(root);
+        const result = await refreshGraph(root, root, adoption.initialOperationId, { python });
+        console.log(JSON.stringify(result, null, 2));
+        if (result.state !== "published")
+            throw new Error(result.reason ?? "Initial graph unavailable");
+    });
+    command.command("refresh").argument("[project]", "project configuration root", ".").option("--workspace <path>", "authorized source workspace").option("--task <id>", "stable task id for idempotent retry").option("--semantic-request <file>", "write captured host extraction packet (requires --task)").option("--semantic-result <file>", "consume exact host result (requires --task)").action(async (project, opts) => {
+        if ((opts.semanticRequest || opts.semanticResult) && !opts.task)
+            throw new Error("Semantic exchange requires a stable --task ID");
+        if (opts.semanticRequest && opts.semanticResult)
+            throw new Error("Choose request or result exchange, not both");
+        const root = resolve(project), workspace = opts.workspace ? resolve(opts.workspace) : root;
+        const result = await refreshGraph(root, workspace, opts.task ?? randomUUID(), { semanticHost: fileSemanticHost({ requestPath: opts.semanticRequest ? resolve(opts.semanticRequest) : undefined, resultPath: opts.semanticResult ? resolve(opts.semanticResult) : undefined }) });
+        console.log(JSON.stringify(result, null, 2));
+        if (result.state !== "published")
+            throw new Error(result.reason ?? "Graph refresh unavailable");
+    });
+    command.command("prune").argument("[project]", "project configuration root", ".").action((project) => console.log(JSON.stringify(pruneGraph(resolve(project)), null, 2)));
+    command.command("disable").argument("[project]", "project configuration root", ".").action((project) => { disableGraph(resolve(project)); console.log("Graph integration disabled; retained evidence preserved."); });
+    command.command("enable").argument("[project]", "project configuration root", ".").action((project) => {
+        const root = resolve(project), prior = loadGraphConfig(root);
+        if (!prior.adoption)
+            throw new Error("No prior adoption; use graph adopt");
+        adoptGraph(root, { config: { ...prior.adoption.config, enabled: true }, authorization: "explicit" });
+        console.log("Graph integration enabled under its accepted policy.");
+    });
+    for (const operation of ["query", "node", "neighbors", "path", "impact"]) {
+        command.command(operation).argument("<query>", "query text or node id").argument("[target]", "target node for path").option("--project <path>", "configuration/source project root", ".").option("--json", "structured evidence").option("--direction <direction>", "incoming | outgoing | both", "both").action(async (query, target, opts) => {
+            const root = resolve(opts.project);
+            const op = { operation, ...(operation === "query" ? { query } : { seeds: [query] }), ...(target ? { target } : {}), direction: opts.direction };
+            assertGraphReadRequest({ kind: "rafi_graph_request", version: 1, requestId: "cli", operations: [op] });
+            const config = loadGraphConfig(root);
+            const corpus = config.enabled ? captureGraphCorpus(root, root, config) : undefined;
+            const view = acquireGraphView(root, root, corpus);
+            const result = "graph" in view ? await readGraph(view, op) : view;
+            console.log(JSON.stringify(result, null, 2));
+            if (result.status === "unavailable" || result.status === "invalid-request")
+                throw new Error("Graph evidence unavailable; see the structured limitation above");
+        });
+    }
+    return command;
+}

package/dist/cli/manager.d.ts

@@ -1,5 +1,7 @@
+import { ManagerEvidenceService } from "../managerEvidence.js";
 import { Command } from "commander";
 import type { EffortLevel } from "../adapters/types.js";
+import type { ManagerEvidencePageV2 } from "rafi-spec";
 import type { ExternalDiagnosticMode } from "../diagnostics.js";
 export interface ManagerCommandOptions {
     resolveProject?: (project: string | undefined) => string;
@@ -15,3 +17,9 @@ export declare function runManager(projectDir: string, options: {
     fast?: boolean;
     external?: ExternalDiagnosticMode;
 }): Promise<void>;
+/** Only original user commands enter here. Model output and retained reports cannot export raw bytes. */
+export declare function executeManagerHostCommand(service: ManagerEvidenceService, command: string, write: (text: string) => void, complete?: boolean): boolean;
+/** Drain one pinned snapshot and expand every referenced artifact before host close.
+ * Errors are returned as incomplete output; an expired snapshot is never refreshed.
+ * This host output is deliberately independent of bounded model packets. */
+export declare function completeManagerHostEvidence(service: ManagerEvidenceService, first: ManagerEvidencePageV2): ManagerEvidencePageV2;