ai-foreman 1.7.6 → 1.7.7

package/dist/handoffs.js

@@ -0,0 +1,326 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { continuityInstruction, mergeContinuityDeltas, parseContinuityDelta } from "./continuity.js";
+import { WorkflowDb } from "./workflowDb.js";
+export const HANDOFF_CACHE_RETENTION_DAYS = 30;
+export const HANDOFF_ACCEPTED = "HANDOFF_ACCEPTED";
+export const HANDOFF_REQUEST_START = "RAFI_HANDOFF_REQUEST_START";
+export const HANDOFF_REQUEST_END = "RAFI_HANDOFF_REQUEST_END";
+export function parseBuilderHandoffRequest(text) {
+    const starts = [...text.matchAll(/RAFI_HANDOFF_REQUEST_START/g)];
+    const ends = [...text.matchAll(/RAFI_HANDOFF_REQUEST_END/g)];
+    if (starts.length === 0 && ends.length === 0)
+        return undefined;
+    if (starts.length !== 1 || ends.length !== 1 || starts[0].index >= ends[0].index)
+        throw new Error("malformed structured Builder handoff request envelope");
+    const raw = text.slice(starts[0].index + HANDOFF_REQUEST_START.length, ends[0].index).trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Builder handoff request is not valid JSON");
+    }
+    const expected = new Set(["version", "reason", "decisions", "constraints", "discoveries", "completed_actions", "evidence", "failures", "blockers", "open_work", "next_action", "role_state"]);
+    const unknown = Object.keys(parsed).filter((key) => !expected.has(key));
+    if (unknown.length)
+        throw new Error(`Builder handoff request has unknown fields: ${unknown.join(", ")}`);
+    if (parsed.version !== 1 || typeof parsed.reason !== "string" || !parsed.reason.trim() || !parsed.role_state || typeof parsed.role_state !== "object" || Array.isArray(parsed.role_state))
+        throw new Error("Builder handoff request is missing required v1 fields");
+    const list = (key) => {
+        const value = parsed[key];
+        if (!Array.isArray(value) || value.length > 500 || value.some((item) => typeof item !== "string" || !item.trim() || item.length > 4_000))
+            throw new Error(`Builder handoff request field ${key} must be a bounded string array`);
+        return value;
+    };
+    if (typeof parsed.next_action !== "string" || !parsed.next_action.trim() || parsed.next_action.length > 4_000)
+        throw new Error("Builder handoff next_action must be a non-empty bounded string");
+    return {
+        version: 1,
+        reason: clean(parsed.reason, 2_000),
+        delta: {
+            version: 1,
+            decisions: list("decisions"), constraints: list("constraints"), discoveries: list("discoveries"),
+            completedActions: list("completed_actions"), evidence: list("evidence"), failures: list("failures"),
+            blockers: list("blockers"), openWork: list("open_work"), nextAction: parsed.next_action.trim(),
+        },
+        roleState: sanitizeObject(parsed.role_state),
+    };
+}
+export class HandoffLoopError extends Error {
+    runId;
+    constructor(runId) {
+        super(`third consecutive Builder-requested handoff for run ${runId} has been paused; record a useful verified action or use guided recovery`);
+        this.runId = runId;
+    }
+}
+/** Durable, validated ownership transfer; cache copies are never authoritative. */
+export class HandoffService {
+    projectDir;
+    cacheRoot;
+    constructor(projectDir) {
+        this.projectDir = resolve(projectDir);
+        this.cacheRoot = join(this.projectDir, ".rafi", "cache", "handoffs");
+    }
+    stage(input, now = new Date()) {
+        this.pruneExpiredCache(now);
+        const db = new WorkflowDb(this.projectDir);
+        try {
+            db.ensureRun(input.runId);
+            if (input.requestedByBuilder && this.consecutiveBuilderRequests(db, input.runId) >= 2) {
+                db.appendContinuityEvent({
+                    runId: input.runId, role: "host", kind: "builder_handoff_loop_paused",
+                    payload: { reason: clean(input.reason, 2_000), recovery: `rafi build:resume --run ${input.runId} --guided-recovery` },
+                    authoritativeStateRevision: db.continuityHead(input.runId, "builder")?.authoritativeStateRevision ?? 0,
+                }, now);
+                db.setContinuityHeadState(input.runId, "builder", "degraded", now);
+                throw new HandoffLoopError(input.runId);
+            }
+            const checkpoints = db.continuityCheckpoints(input.runId, input.role);
+            const head = db.continuityHead(input.runId, input.role);
+            const runHead = db.continuityHead(input.runId, "run") ?? head;
+            if (!head || !runHead || checkpoints.length === 0 || (head.state !== "current" && !input.allowNonCurrentContinuity)) {
+                throw new Error(`cannot hand off ${input.role}: the latest continuity checkpoint is ${head?.state ?? "missing"}`);
+            }
+            const prior = db.handoffs(input.runId).at(-1);
+            const generation = (prior?.generation ?? 0) + 1;
+            const resources = (input.resources ?? []).map((resource) => ({
+                label: resource.label,
+                digest: digest(resource.content),
+                authoritative: resource.authoritative,
+            }));
+            resources.unshift({ label: "continuity-checkpoint", digest: head.digest, authoritative: true }, { label: "authoritative-run-state", digest: runHead.digest, authoritative: true });
+            const manifest = {
+                version: 1,
+                runId: input.runId,
+                generation,
+                role: input.role,
+                reason: clean(input.reason, 2_000),
+                ...(input.predecessorSessionId ? { predecessorSessionId: input.predecessorSessionId } : {}),
+                ...(input.predecessorSessionRef ? { predecessorSessionRef: input.predecessorSessionRef } : {}),
+                ...(prior ? { predecessorManifestDigest: prior.manifestDigest } : {}),
+                continuityCheckpointDigest: head.digest,
+                authoritativeStateDigest: runHead.digest,
+                cumulative: mergeContinuityDeltas(checkpoints.map((checkpoint) => checkpoint.delta)),
+                roleState: sanitizeObject(input.roleState ?? {}),
+                lineage: db.handoffs(input.runId).map((item) => item.manifestDigest),
+                ...(input.sessionUsage ? { sessionUsage: input.sessionUsage } : {}),
+                compactionCount: input.compactionCount,
+                compactMaximum: input.compactMaximum,
+                resources,
+                createdAt: now.toISOString(),
+            };
+            const markdown = renderHandoffMarkdown(manifest);
+            const lineage = db.stageHandoff(manifest, markdown);
+            db.appendContinuityEvent({
+                runId: input.runId, role: "host", kind: input.requestedByBuilder ? "builder_handoff_requested" : "handoff_requested",
+                payload: {
+                    generation, reason: manifest.reason,
+                    occupancy: input.roleState?.contextSample ?? input.roleState?.occupancy ?? "unavailable",
+                    sessionUsage: input.sessionUsage ?? "unavailable",
+                    compactionCount: input.compactionCount, compactMaximum: input.compactMaximum, resources,
+                },
+                authoritativeStateRevision: head.authoritativeStateRevision,
+            }, now);
+            const cacheDirectory = this.materialize(manifest, markdown);
+            return { manifest, markdown, lineage, cacheDirectory };
+        }
+        finally {
+            db.close();
+        }
+    }
+    async transfer(input, createSuccessor) {
+        const staged = this.stage(input);
+        const successor = await createSuccessor(staged);
+        return this.acceptStaged(staged, successor);
+    }
+    async acceptStaged(staged, successor) {
+        const db = new WorkflowDb(this.projectDir);
+        try {
+            const response = await successor.sendTurn([
+                "Accept this validated Rafi handoff. Do not repeat completed work and reconcile host receipts before side effects.",
+                staged.markdown,
+                `Manifest JSON: ${JSON.stringify(staged.manifest)}`,
+                `Reply with ${HANDOFF_ACCEPTED} on the first line, then ${continuityInstruction()}`,
+            ].join("\n\n"));
+            const parsed = parseContinuityDelta(response.text);
+            const sessionId = successor.sessionId();
+            const observedSuccessorRef = successor.sessionRef?.();
+            const successorRef = observedSuccessorRef ? { ...observedSuccessorRef, generation: staged.manifest.generation, validatedAt: new Date().toISOString() } : undefined;
+            if (!response.text.trimStart().startsWith(HANDOFF_ACCEPTED) || !parsed.delta || !sessionId || (staged.manifest.predecessorSessionRef && !successorRef)) {
+                db.failHandoff(staged.manifest.runId, staged.manifest.generation, "successor did not provide HANDOFF_ACCEPTED, a valid continuity delta, and a fresh session identity");
+                await successor.close().catch(() => { });
+                throw new Error("fresh successor failed validated handoff acceptance; predecessor retains the lease");
+            }
+            if (staged.manifest.predecessorSessionId && sessionId === staged.manifest.predecessorSessionId) {
+                db.failHandoff(staged.manifest.runId, staged.manifest.generation, "successor reused predecessor session ID");
+                await successor.close().catch(() => { });
+                throw new Error("handoff successor must be a genuinely fresh provider session");
+            }
+            if (successorRef)
+                successor.adoptSessionRef?.(successorRef);
+            db.appendContinuityEvent({ runId: staged.manifest.runId, role: staged.manifest.role, kind: "handoff_successor_accepted", payload: { generation: staged.manifest.generation, sessionId, sessionRef: successorRef, delta: parsed.delta }, authoritativeStateRevision: db.continuityHead(staged.manifest.runId, staged.manifest.role)?.authoritativeStateRevision ?? 0, sessionRef: successorRef });
+            const checkpoint = db.publishContinuityCheckpoint({ runId: staged.manifest.runId, role: staged.manifest.role, delta: parsed.delta, authoritativeStateRevision: db.continuityHead(staged.manifest.runId, staged.manifest.role)?.authoritativeStateRevision ?? 0, sessionRef: successorRef });
+            const lineage = db.acceptHandoff(staged.manifest.runId, staged.manifest.generation, successorRef ?? sessionId);
+            return { ...staged, lineage, successor, successorSessionId: sessionId, acceptanceCheckpointDigest: checkpoint.digest };
+        }
+        catch (error) {
+            const current = db.handoff(staged.manifest.runId, staged.manifest.generation);
+            if (current?.state === "staged")
+                db.failHandoff(staged.manifest.runId, staged.manifest.generation, error instanceof Error ? error.message : String(error));
+            throw error;
+        }
+        finally {
+            db.close();
+        }
+    }
+    inspect(runId, generation) {
+        const db = new WorkflowDb(this.projectDir);
+        try {
+            const selected = generation ?? db.handoffs(runId).at(-1)?.generation;
+            if (selected === undefined)
+                throw new Error(`no handoff history found for run ${runId}`);
+            const value = db.handoffContent(runId, selected);
+            if (!value)
+                throw new Error(`handoff ${runId}/${selected} not found`);
+            return value;
+        }
+        finally {
+            db.close();
+        }
+    }
+    loadStaged(runId, generation) {
+        const value = this.inspect(runId, generation);
+        if (value.lineage.state !== "staged")
+            throw new Error(`handoff ${runId}/${generation} is ${value.lineage.state}, not staged`);
+        return { ...value, cacheDirectory: this.materialize(value.manifest, value.markdown) };
+    }
+    pruneCache(runId, keepLatest = 1) {
+        if (!Number.isSafeInteger(keepLatest) || keepLatest < 0)
+            throw new Error("--keep-latest must be a non-negative safe integer");
+        const runDir = this.safeRunCache(runId);
+        if (!existsSync(runDir))
+            return [];
+        const generations = readdirSync(runDir).filter((name) => /^\d+$/.test(name)).map(Number).sort((a, b) => b - a);
+        const removed = [];
+        for (const generation of generations.slice(keepLatest)) {
+            const target = join(runDir, String(generation));
+            rmSync(target, { recursive: true, force: true });
+            removed.push(target);
+        }
+        return removed;
+    }
+    pruneExpiredCache(now = new Date(), retentionDays = HANDOFF_CACHE_RETENTION_DAYS) {
+        if (!existsSync(this.cacheRoot))
+            return [];
+        const db = new WorkflowDb(this.projectDir);
+        const protectedRuns = new Set(db.resumableRuns().map((run) => run.runId));
+        db.close();
+        const cutoff = now.getTime() - retentionDays * 86_400_000;
+        const removed = [];
+        for (const runId of readdirSync(this.cacheRoot)) {
+            if (protectedRuns.has(runId))
+                continue;
+            const runDir = this.safeRunCache(runId);
+            for (const generation of existsSync(runDir) ? readdirSync(runDir) : []) {
+                const target = join(runDir, generation);
+                if (statSync(target).mtimeMs < cutoff) {
+                    rmSync(target, { recursive: true, force: true });
+                    removed.push(target);
+                }
+            }
+        }
+        return removed;
+    }
+    materialize(manifest, markdown) {
+        const runDir = this.safeRunCache(manifest.runId);
+        mkdirSync(runDir, { recursive: true });
+        const target = join(runDir, String(manifest.generation));
+        if (existsSync(target))
+            return target;
+        const temporary = mkdtempSync(join(runDir, `.stage-${manifest.generation}-`));
+        writeFileSync(join(temporary, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        writeFileSync(join(temporary, "handoff.md"), markdown, { encoding: "utf8", mode: 0o600 });
+        renameSync(temporary, target);
+        return target;
+    }
+    safeRunCache(runId) {
+        if (!/^[A-Za-z0-9._-]+$/.test(runId) || runId === "." || runId === "..")
+            throw new Error("unsafe handoff run ID");
+        const path = join(this.cacheRoot, runId);
+        if (!path.startsWith(`${this.cacheRoot}/`))
+            throw new Error("unsafe handoff cache path");
+        return path;
+    }
+    consecutiveBuilderRequests(db, runId) {
+        let count = 0;
+        let usefulSinceLastRequest = false;
+        const events = db.continuityEvents(runId);
+        for (const event of events) {
+            if (event.kind === "turn_completed" || event.kind === "turn_completed_after_repair") {
+                const payload = event.payload && typeof event.payload === "object" ? event.payload : undefined;
+                const delta = payload?.delta;
+                if (isContinuityDelta(delta) && useful(delta))
+                    usefulSinceLastRequest = true;
+                continue;
+            }
+            if (event.kind === "builder_handoff_requested") {
+                if (usefulSinceLastRequest)
+                    count = 0;
+                count += 1;
+                usefulSinceLastRequest = false;
+            }
+        }
+        return count;
+    }
+}
+export function renderHandoffMarkdown(manifest) {
+    const section = (title, values) => [`## ${title}`, "", ...(values.length ? values.map((value) => `- ${value}`) : ["- None recorded."]), ""];
+    return [
+        `# Rafi handoff — ${manifest.runId} / generation ${manifest.generation}`,
+        "",
+        `Role: ${manifest.role}`,
+        `Reason: ${manifest.reason}`,
+        `Created: ${manifest.createdAt}`,
+        `Compactions: ${manifest.compactionCount}/${manifest.compactMaximum}`,
+        "",
+        ...section("Decisions", manifest.cumulative.decisions),
+        ...section("Constraints", manifest.cumulative.constraints),
+        ...section("Discoveries", manifest.cumulative.discoveries),
+        ...section("Completed work and evidence", [...manifest.cumulative.completedActions, ...manifest.cumulative.evidence]),
+        ...section("Failures and blockers", [...manifest.cumulative.failures, ...manifest.cumulative.blockers]),
+        ...section("Remaining actions", [...manifest.cumulative.openWork, `Next: ${manifest.cumulative.nextAction}`]),
+        "## Role state",
+        "",
+        "```json",
+        JSON.stringify(manifest.roleState, null, 2),
+        "```",
+        "",
+        "## Authoritative source digests",
+        "",
+        "| Source | Digest | Authoritative |",
+        "|---|---|---|",
+        ...manifest.resources.map((resource) => `| ${escapeCell(resource.label)} | \`${resource.digest}\` | ${resource.authoritative ? "yes" : "no"} |`),
+        "",
+    ].join("\n");
+}
+export function writeHandoffInspection(path, content) {
+    const target = resolve(path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, content, { encoding: "utf8", mode: 0o600 });
+}
+function useful(delta) {
+    return delta.completedActions.length > 0 || delta.evidence.length > 0 || delta.decisions.length > 0 || delta.discoveries.length > 0 || delta.blockers.length > 0;
+}
+function isContinuityDelta(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return candidate.version === 1
+        && [candidate.completedActions, candidate.evidence, candidate.decisions, candidate.discoveries, candidate.blockers].every(Array.isArray);
+}
+function digest(value) { return createHash("sha256").update(value).digest("hex"); }
+function clean(value, maximum) { return value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim().slice(0, maximum); }
+function sanitizeObject(value) { return JSON.parse(JSON.stringify(value, (key, entry) => /credential|secret|token|password|raw.?transcript|hidden.?reasoning/i.test(key) ? undefined : typeof entry === "string" ? entry.slice(0, 20_000) : entry)); }
+function escapeCell(value) { return value.replace(/\|/g, "\\|").replace(/[\r\n]+/g, " "); }

package/dist/log.d.ts

@@ -1,7 +1,7 @@
 /** A single structured log record. */
 export interface LogRecord {
     ts: string;
-    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "gitlab-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "pr-auto-merge-enabled" | "pr-auto-merge-failed" | "mr-created" | "mr-existing" | "mr-failed" | "mr-auto-merge-enabled" | "mr-auto-merge-failed" | "branch-auto-merge-wait" | "branch-direct-merge" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "rafi-plan" | "ticket-populate" | "uninstall-proposal" | "qa" | "qa-fix" | "qa-protected-files-changed" | "qa-evidence" | "agent-status" | "error";
+    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "gitlab-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "pr-auto-merge-enabled" | "pr-auto-merge-failed" | "mr-created" | "mr-existing" | "mr-failed" | "mr-auto-merge-enabled" | "mr-auto-merge-failed" | "branch-auto-merge-wait" | "branch-direct-merge" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "rafi-plan" | "ticket-populate" | "uninstall-proposal" | "qa" | "qa-fix" | "qa-protected-files-changed" | "qa-evidence" | "agent-status" | "context-lifecycle" | "handoff-transfer" | "recovery-handoff-accepted" | "guided-recovery-required" | "safe-boundary-paused" | "session-unavailable" | "error";
     [key: string]: unknown;
 }
 /** Append-only JSONL logger. One line per record, plus an echo to the console. */

package/dist/permissions/policy.d.ts

@@ -11,10 +11,14 @@ export interface Classification {
 export declare class PermissionPolicy {
     private readonly config;
     private readonly cwd;
-    constructor(config: PermissionConfig, cwd: string);
+    private readonly options;
+    constructor(config: PermissionConfig, cwd: string, options?: {
+        currentBranchWorkflow?: boolean;
+    });
     classify(req: PermissionRequest): Classification;
     private classifyBash;
     private matchesAllowedPrefix;
     private filePath;
     private insideCwd;
+    private isGitMetadata;
 }

package/dist/permissions/policy.js

@@ -17,9 +17,11 @@ const SHELL_SUBSTITUTION = { pattern: /\$\(|`/, reason: "shell substitution is n
 export class PermissionPolicy {
     config;
     cwd;
-    constructor(config, cwd) {
+    options;
+    constructor(config, cwd, options = {}) {
         this.config = config;
         this.cwd = cwd;
+        this.options = options;
     }
     classify(req) {
         const { toolName, input } = req;
@@ -31,6 +33,9 @@ export class PermissionPolicy {
         }
         if (FILE_TOOLS.has(toolName)) {
             const target = this.filePath(input);
+            if (this.options.currentBranchWorkflow && target && this.isGitMetadata(target)) {
+                return { decision: "escalate", reason: "current-branch workflow forbids direct writes to Git metadata" };
+            }
             if (target && !this.insideCwd(target)) {
                 return {
                     decision: "escalate",
@@ -47,6 +52,9 @@ export class PermissionPolicy {
         return { decision: "escalate", reason: `tool ${toolName} not recognized` };
     }
     classifyBash(command) {
+        if (this.options.currentBranchWorkflow && isCurrentWorkflowGitMutation(command)) {
+            return { decision: "escalate", reason: "current-branch workflow leaves all Git lifecycle and review operations to the user" };
+        }
         // Always-escalate list is checked first against the full command string —
         // a dangerous pattern anywhere in a chained command escalates the whole call.
         const hitEscalate = this.config.escalateBash.find((p) => command.includes(p));
@@ -89,4 +97,43 @@ export class PermissionPolicy {
         const root = resolve(this.cwd);
         return abs === root || abs.startsWith(root + "/");
     }
+    isGitMetadata(target) {
+        const abs = isAbsolute(target) ? resolve(target) : resolve(this.cwd, target);
+        const root = resolve(this.cwd);
+        const relative = abs === root ? "" : abs.startsWith(root + "/") ? abs.slice(root.length + 1) : "";
+        return relative === ".git" || relative.startsWith(".git/");
+    }
+}
+function isCurrentWorkflowGitMutation(command) {
+    const segments = command.split(SHELL_SPLIT).map((part) => part.trim()).filter(Boolean);
+    for (const segment of segments) {
+        if (/^(?:gh|glab)(?:\s|$)/.test(segment))
+            return true;
+        const invocation = /(?:^|\s)git\s+([\s\S]+)$/i.exec(segment);
+        if (!invocation)
+            continue;
+        let remainder = invocation[1].trim();
+        const globalOption = /^(?:(?:-C|-c|--git-dir|--work-tree|--namespace|--exec-path)\s+(?:"[^"]+"|'[^']+'|\S+)|--(?:git-dir|work-tree|namespace|exec-path)=\S+|--(?:no-pager|paginate|no-replace-objects|literal-pathspecs|glob-pathspecs|noglob-pathspecs|icase-pathspecs|bare))(?:\s+|$)/i;
+        while (globalOption.test(remainder))
+            remainder = remainder.replace(globalOption, "").trimStart();
+        const match = /^([a-z][a-z-]*)([\s\S]*)$/i.exec(remainder);
+        if (!match)
+            continue;
+        const subcommand = match[1].toLowerCase();
+        const args = match[2].trim();
+        if (["add", "am", "apply", "checkout", "cherry-pick", "clean", "commit", "fetch", "merge", "mv", "pull", "push", "rebase", "reset", "restore", "revert", "rm", "stash", "switch", "tag", "worktree"].includes(subcommand))
+            return true;
+        if (subcommand === "branch" && args && !/^(?:--show-current|-a|--all|-r|--remotes|-v|-vv|--verbose)(?:\s|$)/.test(args))
+            return true;
+        if (subcommand === "branch")
+            continue;
+        if (subcommand === "remote" && /^(?:$|-v|--verbose|get-url(?:\s|$)|show(?:\s|$))/.test(args))
+            continue;
+        if (["annotate", "blame", "cat-file", "describe", "diff", "diff-tree", "for-each-ref", "grep", "log", "ls-files", "ls-remote", "ls-tree", "merge-base", "name-rev", "rev-list", "rev-parse", "shortlog", "show", "show-ref", "status", "symbolic-ref", "version", "whatchanged"].includes(subcommand))
+            continue;
+        // Configured aliases and unfamiliar porcelain can mutate refs or the
+        // index; current mode permits only an explicit read-only subset.
+        return true;
+    }
+    return false;
 }

package/dist/qaReview.d.ts

@@ -1,8 +1,9 @@
-import type { SessionStrategy } from "rafi-spec";
-import type { BuilderAdapter } from "./adapters/types.js";
+import type { ProviderSessionRefV1, SessionStrategy } from "rafi-spec";
+import type { BuilderAdapter, CompactResult } from "./adapters/types.js";
 import type { TicketDef } from "./tickets/ticketSchema.js";
 export interface QaStreamState {
     sessionId?: string;
+    sessionRef?: ProviderSessionRefV1;
     reviews: number;
     modificationViolations: number;
 }
@@ -26,6 +27,8 @@ export interface IsolatedQaOptions {
     qaStrategy: SessionStrategy;
     state: QaStreamState;
     createQa: (cwd: string, sessionId?: string) => Promise<BuilderAdapter>;
+    /** Host-owned ordinary QA boundary. Fresh strategies must return a validated successor. */
+    sessionBoundary?: (adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy, cwd: string) => Promise<BuilderAdapter>;
     fix: (issues: string) => Promise<{
         ok: boolean;
         detail?: string;
@@ -46,8 +49,5 @@ export interface IsolatedQaResult {
 }
 export declare function runIsolatedQa(opts: IsolatedQaOptions): Promise<IsolatedQaResult>;
 export declare function buildQaReviewHandoff(ticket: TicketDef, builderSummary: string, diffDigest: string, validationChecklist: string[]): string;
-export declare function compactWithRetry(adapter: BuilderAdapter): Promise<{
-    ok: boolean;
-    error?: string;
-}>;
+export declare function compactWithRetry(adapter: BuilderAdapter): Promise<CompactResult>;
 export declare function buildDurableQaFixHandoff(ticket: TicketDef, issues: string, worktree: string, priorResult: string, diffDigest: string): string;

package/dist/qaReview.js

@@ -1,3 +1,4 @@
+import { SessionUnavailableError } from "./adapters/sessionFailure.js";
 import { currentActivity, withActivityPhase } from "./activity.js";
 import { buildQaFixInstruction, buildQaInstruction, parseStepStatus } from "./foreman.js";
 import { createDisposableQaSnapshotAsync } from "./qaSnapshot.js";
@@ -42,21 +43,17 @@ async function oneReview(opts, cycle) {
     const snapshot = await withActivityPhase("preparing disposable QA snapshot", () => createDisposableQaSnapshotAsync(opts.builderWorktree, progress));
     let qa;
     try {
-        const resume = opts.qaStrategy === "compact" && opts.state.modificationViolations === 0 ? opts.state.sessionId : undefined;
-        qa = await opts.createQa(snapshot.path, resume);
-        if (opts.qaStrategy === "compact" && opts.state.reviews > 0 && resume) {
-            const compacted = await withActivityPhase("compacting QA session", () => compactWithRetry(qa));
-            if (!compacted.ok) {
-                await qa.close();
-                qa = await opts.createQa(snapshot.path);
-                opts.state.sessionId = undefined;
-            }
-        }
         const handoff = buildQaReviewHandoff(opts.ticket, opts.builderSummary, snapshot.manifest.diffDigest, loadTicketSetupConfigWithDefaults(opts.builderWorktree).build.validation_checklist);
+        // Every disposable snapshot has a distinct cwd and therefore must have a
+        // fresh provider conversation. Cumulative QA state remains in the durable
+        // continuity/checkpoint stream; an old provider session is never moved
+        // into a newly-created /tmp/rafi-qa-* directory.
+        qa = await opts.createQa(snapshot.path);
         const turn = await qa.sendTurn(handoff);
         const status = parseStepStatus(turn.text);
         opts.state.reviews += 1;
         opts.state.sessionId = qa.sessionId();
+        opts.state.sessionRef = qa.sessionRef?.();
         const changes = await withActivityPhase("checking QA file changes", () => snapshot.qaChanges());
         if (changes.length) {
             opts.state.modificationViolations += 1;
@@ -99,10 +96,19 @@ export async function compactWithRetry(adapter) {
         return { ok: false, error: "native compaction unavailable" };
     let error = "";
     for (let attempt = 0; attempt < 2; attempt++) {
-        const result = await adapter.compact();
-        if (result.ok)
-            return { ok: true };
-        error = result.error ?? "compaction failed";
+        try {
+            const result = await adapter.compact();
+            if (result.ok)
+                return { ok: true };
+            if (result.failure?.category === "session-unavailable")
+                return result;
+            error = result.error ?? "compaction failed";
+        }
+        catch (failure) {
+            if (failure instanceof SessionUnavailableError)
+                return { ok: false, error: failure.message, failure: failure.failure };
+            error = failure instanceof Error ? failure.message : String(failure);
+        }
     }
     return { ok: false, error };
 }

package/dist/sessionAvailability.d.ts

@@ -0,0 +1,15 @@
+import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
+import { ClaudeAdapter } from "./adapters/claude.js";
+import { CodexAdapter } from "./adapters/codex.js";
+import type { BuilderAdapterOptions } from "./adapters/types.js";
+export interface ResolveSessionAvailabilityOptions {
+    cwd?: string;
+    configRoot?: string;
+    workspaceIdentity?: string;
+    runtimeExecutable?: string;
+    now?: Date;
+}
+/** Provider-backed exact-session probe. Codex attaches with thread/resume and never starts a turn. */
+export declare function resolveProviderSessionAvailability(ref: ProviderSessionRefV1, options?: ResolveSessionAvailabilityOptions): Promise<SessionAvailabilityV1>;
+/** Create a validated exact adapter for callers that need one after a successful probe. */
+export declare function createValidatedProviderAdapter(ref: ProviderSessionRefV1, options: Omit<BuilderAdapterOptions, "resumeSessionId" | "resumeSessionRef">): Promise<ClaudeAdapter | CodexAdapter>;

package/dist/sessionAvailability.js

@@ -0,0 +1,57 @@
+import { ClaudeAdapter, probeClaudeSession } from "./adapters/claude.js";
+import { CodexAdapter } from "./adapters/codex.js";
+import { SessionUnavailableError } from "./adapters/sessionFailure.js";
+/** Provider-backed exact-session probe. Codex attaches with thread/resume and never starts a turn. */
+export async function resolveProviderSessionAvailability(ref, options = {}) {
+    const cwd = options.cwd ?? ref.cwd;
+    const configRoot = options.configRoot ?? ref.configRoot;
+    if (ref.provider === "claude") {
+        return probeClaudeSession(ref, { cwd, configRoot, workspaceIdentity: options.workspaceIdentity, now: options.now });
+    }
+    if (ref.source === "legacy-inferred") {
+        return { version: 1, status: "unknown", checkedAt: (options.now ?? new Date()).toISOString(), reason: "legacy-unscoped", detail: "legacy Codex thread IDs cannot be proven exact without an observed scoped binding", sessionRef: ref };
+    }
+    const adapterOptions = {
+        cwd,
+        configRoot,
+        runtimeExecutable: options.runtimeExecutable,
+        runtimePhase: "recovery",
+        resumeSessionRef: ref,
+        sessionRole: ref.role,
+        sessionStream: ref.stream,
+        sessionGeneration: ref.generation,
+        workspaceIdentity: options.workspaceIdentity,
+        ticketId: ref.ticketId,
+        deliveryUnitId: ref.deliveryUnitId,
+        sandboxMode: "read-only",
+        permission: async () => ({ behavior: "deny", message: "session availability probes never run tools" }),
+    };
+    const adapter = new CodexAdapter(adapterOptions);
+    try {
+        return await adapter.validateSession();
+    }
+    catch (error) {
+        return { version: 1, status: "unknown", checkedAt: (options.now ?? new Date()).toISOString(), reason: "probe-failed", detail: error instanceof Error ? error.message : String(error), sessionRef: ref };
+    }
+    finally {
+        await adapter.close().catch(() => { });
+    }
+}
+/** Create a validated exact adapter for callers that need one after a successful probe. */
+export async function createValidatedProviderAdapter(ref, options) {
+    const scoped = { ...options, resumeSessionRef: ref, sessionRole: ref.role, sessionStream: ref.stream, sessionGeneration: ref.generation };
+    if (ref.provider === "claude")
+        return ClaudeAdapter.create(scoped);
+    const adapter = new CodexAdapter(scoped);
+    const availability = await adapter.validateSession();
+    if (availability.status !== "available") {
+        await adapter.close().catch(() => { });
+        throw new SessionUnavailableError({
+            runtime: "codex", phase: "preflight", dispatchState: "not-sent",
+            executable: options.runtimeExecutable ?? "codex", cwd: options.cwd,
+            diagnostics: availability.detail ?? `Codex session ${ref.sessionId} is ${availability.status}`,
+            availability,
+        });
+    }
+    return adapter;
+}

package/dist/sessionIdentity.d.ts

@@ -0,0 +1,33 @@
+import type { ConfigurableAgentRole, ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
+export interface ProviderSessionScope {
+    provider: "claude" | "codex";
+    cwd: string;
+    configRoot: string;
+    role?: ConfigurableAgentRole;
+    stream?: string;
+    workspaceIdentity?: string;
+    ticketId?: string;
+    deliveryUnitId?: string;
+}
+export interface CreateProviderSessionRefInput extends ProviderSessionScope {
+    sessionId: string;
+    generation?: number;
+    source?: ProviderSessionRefV1["source"];
+    createdAt?: string;
+    validatedAt?: string;
+}
+/** Resolve symlinks for an existing location and otherwise return an absolute normalized path. */
+export declare function canonicalSessionPath(path: string): string;
+/**
+ * Stable for one Git worktree lifetime. The token lives in that worktree's
+ * administrative Git directory (not in the checked-out tree), so normal edits
+ * and commits do not change it while removal/recreation cannot inherit it.
+ */
+export declare function captureWorkspaceIdentity(cwd: string): string | undefined;
+export declare function createProviderSessionRef(input: CreateProviderSessionRefInput): ProviderSessionRefV1;
+/** Identity used by accounting, compaction, settings acknowledgements, and mutation leases. */
+export declare function providerSessionKey(ref: ProviderSessionRefV1): string;
+export declare function validateProviderSessionScope(ref: ProviderSessionRefV1, requested: ProviderSessionScope, now?: Date): SessionAvailabilityV1;
+export declare function latestSessionBinding(bindings: readonly ProviderSessionRefV1[] | undefined, role: ConfigurableAgentRole, sessionId?: string): ProviderSessionRefV1 | undefined;
+export declare function resolveUniqueSessionBinding(bindings: readonly ProviderSessionRefV1[] | undefined, sessionId: string): ProviderSessionRefV1 | undefined;
+export declare function upsertSessionBinding(bindings: readonly ProviderSessionRefV1[] | undefined, ref: ProviderSessionRefV1): ProviderSessionRefV1[];