youmd 0.10.2 → 0.12.0

package/dist/lib/orchestrator/run-journal.js

@@ -0,0 +1,912 @@
+"use strict";
+// run-journal.ts — durable, atomic state for governed orchestrator runs.
+//
+// A run becomes governed only when spawn_agent carries a run_id. Ungoverned loops keep their
+// historical behavior. Governed runs cannot complete until a distinct, terminal reviewer records
+// a structured approval; rejected reviews advance a bounded retry counter or block the run.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RUN_EVENTS = exports.RUN_EVIDENCE_KINDS = exports.RUN_WORKER_ROLES = void 0;
+exports.isRunWorkerRole = isRunWorkerRole;
+exports.validateAssignmentPreflight = validateAssignmentPreflight;
+exports.loadRunJournal = loadRunJournal;
+exports.saveRunJournal = saveRunJournal;
+exports.createOrLoadRun = createOrLoadRun;
+exports.assignRunWorker = assignRunWorker;
+exports.recordRunWorkerAssertion = recordRunWorkerAssertion;
+exports.completeRunReview = completeRunReview;
+exports.findBoundUnfinishedRunIds = findBoundUnfinishedRunIds;
+exports.runFinishBlocker = runFinishBlocker;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../config");
+exports.RUN_WORKER_ROLES = ["planner", "specialist", "qa", "design", "reviewer"];
+exports.RUN_EVIDENCE_KINDS = ["test", "artifact", "screenshot", "log", "review", "metric"];
+exports.MAX_RUN_EVENTS = 256;
+const RUN_ID_TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const MAX_RUN_ID_LENGTH = 128;
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_MAX_WORKER_ASSIGNMENTS = 20;
+const DEFAULT_MAX_EVIDENCE_ITEMS = 64;
+const MAX_EVENT_TEXT = 1000;
+const MAX_EVIDENCE_REF = 1000;
+const MAX_RUN_WORKER_IDENTITIES = 512;
+function runsDir(options = {}) {
+    return options.dir ?? path.join((0, config_1.getWritableHomeBundleDir)(), "orchestrator", "runs");
+}
+function validRunId(runId) {
+    if (!runId || runId.length > MAX_RUN_ID_LENGTH)
+        return false;
+    const token = runId.startsWith("run:") ? runId.slice(4) : runId;
+    return RUN_ID_TOKEN_RE.test(token);
+}
+function isRunWorkerRole(role) {
+    return exports.RUN_WORKER_ROLES.includes(role);
+}
+function runPath(runId, options = {}) {
+    if (!validRunId(runId))
+        throw new Error("run_id must use an optional run: prefix and a bounded safe token");
+    return path.join(runsDir(options), `${runId}.json`);
+}
+function isStringRecord(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.values(value).every((entry) => typeof entry === "string"));
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string" && !!entry.trim());
+}
+function boundedText(value, max = MAX_EVENT_TEXT) {
+    return value
+        .replace(/[\u0000-\u001f\u007f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, max);
+}
+function isSafeEvidenceRef(value) {
+    const ref = value.trim();
+    if (!ref || ref.length > MAX_EVIDENCE_REF || /[\u0000-\u001f]/.test(ref))
+        return false;
+    if (/^https?:\/\//i.test(ref)) {
+        try {
+            const url = new URL(ref);
+            return url.protocol === "https:" || url.protocol === "http:";
+        }
+        catch {
+            return false;
+        }
+    }
+    if (path.isAbsolute(ref) || ref.split(/[\\/]+/).includes(".."))
+        return false;
+    return true;
+}
+function isRunEvidence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const row = value;
+    return (exports.RUN_EVIDENCE_KINDS.includes(String(row.kind)) &&
+        typeof row.source === "string" &&
+        !!row.source.trim() &&
+        typeof row.workerId === "string" &&
+        !!row.workerId.trim() &&
+        isRunWorkerRole(String(row.role)) &&
+        typeof row.summary === "string" &&
+        !!row.summary.trim() &&
+        typeof row.recordedAt === "string" &&
+        (row.ref === undefined || (typeof row.ref === "string" && isSafeEvidenceRef(row.ref))) &&
+        (row.sha256 === undefined || (typeof row.sha256 === "string" && /^[a-f0-9]{64}$/i.test(row.sha256))));
+}
+function isDesignApplicability(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const row = value;
+    return ((row.status === "required" || row.status === "not_applicable") &&
+        typeof row.reason === "string" &&
+        (row.status === "required" || !!row.reason.trim()));
+}
+function normalizeEvidence(values, workerId, role, recordedAt) {
+    const evidence = [];
+    for (const value of values) {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return { error: "evidence must use typed provenance objects, not free-form strings" };
+        }
+        const row = value;
+        const kind = String(row.kind || "");
+        const source = boundedText(String(row.source || ""), 256);
+        const summary = boundedText(String(row.summary || ""));
+        const ref = row.ref === undefined ? undefined : String(row.ref).trim();
+        const sha256 = row.sha256 === undefined ? undefined : String(row.sha256).trim().toLowerCase();
+        const candidate = {
+            kind,
+            source,
+            workerId,
+            role,
+            summary,
+            ...(ref ? { ref } : {}),
+            ...(sha256 ? { sha256 } : {}),
+            recordedAt,
+        };
+        if (!isRunEvidence(candidate)) {
+            return {
+                error: "evidence requires kind=test|artifact|screenshot|log|review|metric, bounded source/summary, a safe relative/http(s) ref, and optional sha256",
+            };
+        }
+        evidence.push(candidate);
+    }
+    return { evidence };
+}
+function isPreflight(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const row = value;
+    return ((row.mode === "auto" || row.mode === "explicit") &&
+        typeof row.harness === "string" &&
+        !!row.harness.trim() &&
+        typeof row.host === "string" &&
+        !!row.host.trim() &&
+        typeof row.recordedAt === "string" &&
+        (row.capabilityReason === undefined || typeof row.capabilityReason === "string") &&
+        (row.proof === undefined || typeof row.proof === "string"));
+}
+function isRunEvent(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const row = value;
+    return (Number.isInteger(row.sequence) &&
+        Number(row.sequence) >= 1 &&
+        [
+            "created",
+            "worker_assigned",
+            "handoff",
+            "review_started",
+            "worker_result",
+            "review_recorded",
+            "retry_required",
+            "blocked",
+            "completed",
+        ].includes(String(row.type)) &&
+        typeof row.at === "string" &&
+        Number.isInteger(row.attempt) &&
+        Number(row.attempt) >= 1 &&
+        ["working", "review", "retry_required", "completed", "blocked"].includes(String(row.toStage)) &&
+        (row.fromStage === undefined ||
+            ["working", "review", "retry_required", "completed", "blocked"].includes(String(row.fromStage))) &&
+        (row.role === undefined || isRunWorkerRole(row.role)) &&
+        (row.workerId === undefined || typeof row.workerId === "string") &&
+        (row.from === undefined || typeof row.from === "string") &&
+        (row.to === undefined || typeof row.to === "string") &&
+        (row.summary === undefined || typeof row.summary === "string") &&
+        (row.preflight === undefined || isPreflight(row.preflight)));
+}
+function appendRunEvent(journal, input) {
+    const events = Array.isArray(journal.events) ? journal.events : [];
+    const sequence = events.reduce((max, event) => Math.max(max, event.sequence), 0) + 1;
+    const event = {
+        ...input,
+        sequence,
+        attempt: input.attempt ?? journal.attempt,
+        ...(input.summary ? { summary: boundedText(input.summary) } : {}),
+    };
+    journal.events = [...events, event].slice(-exports.MAX_RUN_EVENTS);
+}
+function validateAssignmentPreflight(input) {
+    if (!input)
+        return "governed worker assignment requires capability preflight evidence";
+    if (input.mode !== "auto" && input.mode !== "explicit") {
+        return "capability preflight mode must be auto or explicit";
+    }
+    const harness = boundedText(input.harness || "", 128);
+    const host = boundedText(input.host || "", 255);
+    if (!harness || !host)
+        return "capability preflight requires selected harness and host";
+    if (input.mode === "auto" && !boundedText(input.capabilityReason || "")) {
+        return "auto-selected harness requires a capability reason";
+    }
+    if (input.mode === "explicit" && !boundedText(input.proof || "")) {
+        return "explicit harness selection requires harness proof";
+    }
+    return undefined;
+}
+function isJournal(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const row = value;
+    const evidenceValid = Array.isArray(row.evidence) && row.evidence.every((item) => {
+        if (isRunEvidence(item))
+            return true;
+        // Read-only compatibility for v1 journals; loadRunJournal upgrades these before mutation.
+        return (!!item &&
+            typeof item === "object" &&
+            typeof item.workerId === "string" &&
+            typeof item.role === "string" &&
+            typeof item.summary === "string" &&
+            typeof item.recordedAt === "string");
+    });
+    const verdictValid = row.reviewerVerdict === undefined ||
+        (!!row.reviewerVerdict &&
+            ["approved", "changes_requested"].includes(row.reviewerVerdict.status) &&
+            typeof row.reviewerVerdict.reviewerId === "string" &&
+            typeof row.reviewerVerdict.summary === "string" &&
+            Array.isArray(row.reviewerVerdict.issues) &&
+            row.reviewerVerdict.issues.every((issue) => typeof issue === "string") &&
+            (row.reviewerVerdict.semanticSuccess === undefined ||
+                (typeof row.reviewerVerdict.semanticSuccess.met === "boolean" &&
+                    typeof row.reviewerVerdict.semanticSuccess.summary === "string")) &&
+            typeof row.reviewerVerdict.recordedAt === "string");
+    const eventsValid = row.events === undefined ||
+        (Array.isArray(row.events) && row.events.length <= exports.MAX_RUN_EVENTS && row.events.every(isRunEvent));
+    return (typeof row.runId === "string" &&
+        validRunId(row.runId) &&
+        ["working", "review", "retry_required", "completed", "blocked"].includes(String(row.stage)) &&
+        isStringRecord(row.workers) &&
+        Number.isInteger(row.attempt) &&
+        Number(row.attempt) >= 1 &&
+        Number.isInteger(row.maxAttempts) &&
+        Number(row.maxAttempts) >= 1 &&
+        evidenceValid &&
+        eventsValid &&
+        verdictValid &&
+        (row.workflowVersion === undefined || row.workflowVersion === 2) &&
+        (row.designApplicability === undefined || isDesignApplicability(row.designApplicability)) &&
+        (row.cursor === undefined || [...exports.RUN_WORKER_ROLES, "done", "blocked"].includes(row.cursor)) &&
+        (row.workerAssertions === undefined ||
+            (Array.isArray(row.workerAssertions) &&
+                row.workerAssertions.every((assertion) => !!assertion &&
+                    Number.isInteger(assertion.attempt) &&
+                    assertion.attempt >= 1 &&
+                    typeof assertion.workerId === "string" &&
+                    ["planner", "specialist", "qa", "design"].includes(String(assertion.role)) &&
+                    (assertion.status === "passed" || assertion.status === "failed") &&
+                    typeof assertion.summary === "string" &&
+                    Array.isArray(assertion.evidence) &&
+                    assertion.evidence.every(isRunEvidence) &&
+                    typeof assertion.recordedAt === "string"))) &&
+        (row.budget === undefined ||
+            (Number.isInteger(row.budget.maxAttempts) &&
+                row.budget.maxAttempts >= 1 &&
+                Number.isInteger(row.budget.maxWorkerAssignments) &&
+                row.budget.maxWorkerAssignments >= 1 &&
+                Number.isInteger(row.budget.maxEvidenceItems) &&
+                row.budget.maxEvidenceItems >= 1)) &&
+        (row.usage === undefined ||
+            (Number.isInteger(row.usage.workerAssignments) &&
+                row.usage.workerAssignments >= 0 &&
+                Number.isInteger(row.usage.evidenceItems) &&
+                row.usage.evidenceItems >= 0)) &&
+        (row.taskId === undefined || typeof row.taskId === "string") &&
+        (row.sessionId === undefined || typeof row.sessionId === "string") &&
+        (row.executionWorkerIds === undefined ||
+            (isStringArray(row.executionWorkerIds) && row.executionWorkerIds.length <= MAX_RUN_WORKER_IDENTITIES)) &&
+        (row.reviewerWorkerIds === undefined ||
+            (isStringArray(row.reviewerWorkerIds) && row.reviewerWorkerIds.length <= MAX_RUN_WORKER_IDENTITIES)) &&
+        typeof row.createdAt === "string" &&
+        typeof row.updatedAt === "string");
+}
+function archiveCorrupt(target) {
+    try {
+        const archived = `${target}.corrupt-${Date.now()}`;
+        fs.renameSync(target, archived);
+    }
+    catch {
+        // A concurrent reader may already have archived it. A corrupt journal must never crash U.
+    }
+}
+/** Load a persisted run. Invalid/partial JSON is quarantined and treated as missing. */
+function loadRunJournal(runId, options = {}) {
+    let target;
+    try {
+        target = runPath(runId, options);
+        const parsed = JSON.parse(fs.readFileSync(target, "utf8"));
+        if (!isJournal(parsed) || parsed.runId !== runId) {
+            archiveCorrupt(target);
+            return undefined;
+        }
+        const journal = parsed;
+        // v1 journals predate append-only events. They remain readable and gain events on the next mutation.
+        journal.events = Array.isArray(journal.events) ? journal.events : [];
+        journal.evidence = journal.evidence.map((item) => isRunEvidence(item)
+            ? item
+            : (() => {
+                const legacy = item;
+                return {
+                    kind: "log",
+                    source: `legacy:${boundedText(legacy.workerId || "unknown", 128)}`,
+                    workerId: boundedText(legacy.workerId || "unknown", 128),
+                    role: isRunWorkerRole(legacy.role || "") ? legacy.role : "reviewer",
+                    summary: boundedText(legacy.summary || "legacy evidence"),
+                    recordedAt: legacy.recordedAt || new Date(0).toISOString(),
+                };
+            })());
+        if (journal.reviewerVerdict && !journal.reviewerVerdict.semanticSuccess) {
+            journal.reviewerVerdict.semanticSuccess = {
+                met: journal.reviewerVerdict.status === "approved",
+                summary: "legacy reviewer verdict (semantic-success field was not recorded)",
+            };
+        }
+        if (journal.workflowVersion === 2) {
+            journal.workerAssertions = Array.isArray(journal.workerAssertions) ? journal.workerAssertions : [];
+            journal.budget = journal.budget ?? {
+                maxAttempts: journal.maxAttempts,
+                maxWorkerAssignments: DEFAULT_MAX_WORKER_ASSIGNMENTS,
+                maxEvidenceItems: DEFAULT_MAX_EVIDENCE_ITEMS,
+            };
+            journal.usage = journal.usage ?? {
+                workerAssignments: journal.events.filter((event) => event.type === "worker_assigned").length,
+                evidenceItems: journal.evidence.length,
+            };
+            journal.cursor = journal.cursor ?? (journal.stage === "completed" ? "done" : "planner");
+        }
+        // Older journals only have mutable role slots. Seed the durable identity sets from every
+        // retained assignment event plus current slots; future reassignments can no longer erase them.
+        const assignedEvents = journal.events.filter((event) => event.type === "worker_assigned");
+        journal.executionWorkerIds = Array.from(new Set([
+            ...(Array.isArray(journal.executionWorkerIds) ? journal.executionWorkerIds : []),
+            ...assignedEvents
+                .filter((event) => event.role !== "reviewer")
+                .map((event) => event.workerId)
+                .filter((id) => !!id),
+            ...Object.entries(journal.workers)
+                .filter(([role]) => role !== "reviewer")
+                .map(([, id]) => id),
+        ]));
+        journal.reviewerWorkerIds = Array.from(new Set([
+            ...(Array.isArray(journal.reviewerWorkerIds) ? journal.reviewerWorkerIds : []),
+            ...assignedEvents
+                .filter((event) => event.role === "reviewer")
+                .map((event) => event.workerId)
+                .filter((id) => !!id),
+            ...(journal.workers.reviewer ? [journal.workers.reviewer] : []),
+        ]));
+        return journal;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT" && target)
+            archiveCorrupt(target);
+        return undefined;
+    }
+}
+/** Atomic 0600 checkpoint: a restart sees either the old complete record or the new one. */
+function saveRunJournal(journal, options = {}) {
+    const target = runPath(journal.runId, options);
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    const tmp = `${target}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    try {
+        fs.writeFileSync(tmp, `${JSON.stringify(journal, null, 2)}\n`, { mode: 0o600 });
+        fs.renameSync(tmp, target);
+    }
+    finally {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch {
+            /* rename already removed it */
+        }
+    }
+}
+function createOrLoadRun(input, options = {}) {
+    if (!validRunId(input.runId))
+        return { ok: false, error: "invalid run_id" };
+    const existing = loadRunJournal(input.runId, options);
+    if (existing) {
+        const taskId = input.taskId?.trim();
+        const sessionId = input.sessionId ? boundedText(input.sessionId, 256) : undefined;
+        if (taskId && existing.taskId && existing.taskId !== taskId) {
+            return { ok: false, error: `run ${input.runId} already belongs to task ${existing.taskId}` };
+        }
+        if (sessionId && existing.sessionId && existing.sessionId !== sessionId) {
+            return { ok: false, error: `run ${input.runId} already belongs to session ${existing.sessionId}` };
+        }
+        let changed = false;
+        if (taskId && !existing.taskId) {
+            existing.taskId = taskId;
+            changed = true;
+        }
+        if (sessionId && !existing.sessionId) {
+            existing.sessionId = sessionId;
+            changed = true;
+        }
+        if (changed) {
+            existing.updatedAt = (options.now?.() ?? new Date()).toISOString();
+            saveRunJournal(existing, options);
+        }
+        return { ok: true, journal: existing };
+    }
+    if (input.workflowVersion === 2 && !isDesignApplicability(input.designApplicability)) {
+        return {
+            ok: false,
+            error: "strict governed runs require designApplicability.status=required|not_applicable; not_applicable also requires a reason",
+        };
+    }
+    const requestedMax = Number.isFinite(input.maxAttempts) ? Number(input.maxAttempts) : DEFAULT_MAX_ATTEMPTS;
+    const maxAttempts = Math.max(1, Math.min(10, Math.trunc(requestedMax)));
+    const maxWorkerAssignments = Math.max(4, Math.min(100, Math.trunc(Number(input.maxWorkerAssignments) || DEFAULT_MAX_WORKER_ASSIGNMENTS)));
+    const maxEvidenceItems = Math.max(4, Math.min(256, Math.trunc(Number(input.maxEvidenceItems) || DEFAULT_MAX_EVIDENCE_ITEMS)));
+    const timestamp = (options.now?.() ?? new Date()).toISOString();
+    const journal = {
+        runId: input.runId,
+        taskId: input.taskId?.trim() || undefined,
+        sessionId: input.sessionId ? boundedText(input.sessionId, 256) : undefined,
+        stage: "working",
+        ...(input.workflowVersion === 2
+            ? {
+                workflowVersion: 2,
+                designApplicability: {
+                    status: input.designApplicability.status,
+                    reason: boundedText(input.designApplicability.reason),
+                },
+                cursor: "planner",
+                workerAssertions: [],
+                budget: { maxAttempts, maxWorkerAssignments, maxEvidenceItems },
+                usage: { workerAssignments: 0, evidenceItems: 0 },
+            }
+            : {}),
+        workers: {},
+        executionWorkerIds: [],
+        reviewerWorkerIds: [],
+        attempt: 1,
+        maxAttempts,
+        evidence: [],
+        events: [],
+        createdAt: timestamp,
+        updatedAt: timestamp,
+    };
+    appendRunEvent(journal, {
+        type: "created",
+        at: timestamp,
+        toStage: "working",
+        summary: input.taskId ? `created for task ${input.taskId}` : "created governed run",
+    });
+    saveRunJournal(journal, options);
+    return { ok: true, journal };
+}
+/** Attribute a spawned worker to a durable run and advance it into work or review. */
+function assignRunWorker(input, options = {}) {
+    const role = input.role.trim().toLowerCase();
+    const workerId = input.workerId.trim();
+    if (!role || !workerId)
+        return { ok: false, error: "role and workerId are required" };
+    if (!isRunWorkerRole(role)) {
+        return { ok: false, error: `role must be one of: ${exports.RUN_WORKER_ROLES.join(", ")}` };
+    }
+    const preflightError = validateAssignmentPreflight(input.preflight);
+    if (preflightError)
+        return { ok: false, error: preflightError };
+    const before = loadRunJournal(input.runId, options);
+    if (!before && input.workflowVersion === 2 && role !== "planner") {
+        return { ok: false, error: "strict governed runs must start with role=planner" };
+    }
+    const created = createOrLoadRun(input, options);
+    if (!created.ok || !created.journal)
+        return created;
+    const journal = created.journal;
+    if (journal.stage === "completed" || journal.stage === "blocked") {
+        return { ok: false, error: `run ${journal.runId} is already ${journal.stage}` };
+    }
+    if (journal.workflowVersion === 2) {
+        if (!journal.cursor || !journal.budget || !journal.usage || !journal.designApplicability) {
+            return { ok: false, error: `run ${journal.runId} is missing strict workflow state` };
+        }
+        if (journal.cursor !== role) {
+            return {
+                ok: false,
+                error: `run ${journal.runId} expects role=${journal.cursor}; cannot assign ${role}`,
+            };
+        }
+        if (journal.workers[role]) {
+            return { ok: false, error: `role=${role} already has an assigned worker for attempt ${journal.attempt}` };
+        }
+        if (journal.usage.workerAssignments >= journal.budget.maxWorkerAssignments) {
+            return { ok: false, error: "run worker-assignment budget exhausted" };
+        }
+    }
+    const fromStage = journal.stage;
+    const timestamp = (options.now?.() ?? new Date()).toISOString();
+    const preflight = {
+        mode: input.preflight.mode,
+        harness: boundedText(input.preflight.harness, 128),
+        host: boundedText(input.preflight.host, 255),
+        ...(input.preflight.capabilityReason
+            ? { capabilityReason: boundedText(input.preflight.capabilityReason) }
+            : {}),
+        ...(input.preflight.proof ? { proof: boundedText(input.preflight.proof) } : {}),
+        recordedAt: timestamp,
+    };
+    if (role === "reviewer") {
+        if (journal.executionWorkerIds.includes(workerId)) {
+            return { ok: false, error: "reviewer must be distinct from every specialist worker" };
+        }
+        if (!journal.reviewerWorkerIds.includes(workerId) && journal.reviewerWorkerIds.length >= MAX_RUN_WORKER_IDENTITIES) {
+            return { ok: false, error: "run reviewer identity budget exhausted" };
+        }
+        journal.stage = "review";
+    }
+    else {
+        if (journal.reviewerWorkerIds.includes(workerId)) {
+            return { ok: false, error: "specialist cannot reuse the reviewer worker" };
+        }
+        if (!journal.executionWorkerIds.includes(workerId) && journal.executionWorkerIds.length >= MAX_RUN_WORKER_IDENTITIES) {
+            return { ok: false, error: "run execution identity budget exhausted" };
+        }
+        journal.stage = "working";
+    }
+    journal.workers[role] = workerId;
+    if (role === "reviewer") {
+        if (!journal.reviewerWorkerIds.includes(workerId))
+            journal.reviewerWorkerIds.push(workerId);
+    }
+    else if (!journal.executionWorkerIds.includes(workerId)) {
+        journal.executionWorkerIds.push(workerId);
+    }
+    if (journal.workflowVersion === 2 && journal.usage)
+        journal.usage.workerAssignments += 1;
+    appendRunEvent(journal, {
+        type: "worker_assigned",
+        at: timestamp,
+        fromStage,
+        toStage: journal.stage,
+        role,
+        workerId,
+        summary: `${role} assigned with ${preflight.harness} on ${preflight.host}`,
+        preflight,
+    });
+    appendRunEvent(journal, {
+        type: "handoff",
+        at: timestamp,
+        fromStage,
+        toStage: journal.stage,
+        role,
+        workerId,
+        from: "orchestrator",
+        to: workerId,
+        summary: `handoff to ${role}`,
+    });
+    if (role === "reviewer") {
+        appendRunEvent(journal, {
+            type: "review_started",
+            at: timestamp,
+            fromStage,
+            toStage: "review",
+            role,
+            workerId,
+            summary: "distinct reviewer assigned",
+        });
+    }
+    journal.updatedAt = timestamp;
+    saveRunJournal(journal, options);
+    return { ok: true, journal };
+}
+function requiredExecutionRoles(journal) {
+    return journal.designApplicability?.status === "required"
+        ? ["planner", "specialist", "qa", "design"]
+        : ["planner", "specialist", "qa"];
+}
+function moveToRetryOrBlocked(journal, timestamp, summary, workerId, role) {
+    const fromStage = journal.stage;
+    if (journal.attempt < journal.maxAttempts) {
+        journal.attempt += 1;
+        journal.stage = "retry_required";
+        journal.cursor = "planner";
+        journal.workers = {};
+        appendRunEvent(journal, {
+            type: "retry_required",
+            at: timestamp,
+            attempt: journal.attempt,
+            fromStage,
+            toStage: "retry_required",
+            role,
+            workerId,
+            summary,
+        });
+    }
+    else {
+        journal.stage = "blocked";
+        journal.cursor = "blocked";
+        journal.blockedAt = timestamp;
+        appendRunEvent(journal, {
+            type: "blocked",
+            at: timestamp,
+            fromStage,
+            toStage: "blocked",
+            role,
+            workerId,
+            summary,
+        });
+    }
+}
+/** Record a terminal planner/specialist/QA/design assertion and advance the fixed v2 cursor. */
+function recordRunWorkerAssertion(input, options = {}) {
+    const journal = loadRunJournal(input.runId, options);
+    if (!journal)
+        return { ok: false, error: `run ${input.runId} was not found or is corrupt` };
+    if (journal.workflowVersion !== 2 || !journal.cursor || !journal.budget || !journal.usage) {
+        return { ok: false, error: "worker assertions require a strict v2 governed run" };
+    }
+    if (journal.stage === "completed" || journal.stage === "blocked") {
+        return { ok: false, error: `run ${journal.runId} is already ${journal.stage}` };
+    }
+    const role = input.role.trim().toLowerCase();
+    if (!isRunWorkerRole(role) || role === "reviewer") {
+        return { ok: false, error: "worker result role must be planner, specialist, qa, or design" };
+    }
+    if (journal.cursor !== role || journal.workers[role] !== input.workerId) {
+        return { ok: false, error: `worker result must match the current role=${journal.cursor} assignment` };
+    }
+    if (!input.workerTerminal)
+        return { ok: false, error: "worker must be terminal before recording its result" };
+    if (input.status === "passed" && !input.workerSucceeded) {
+        return { ok: false, error: "a stopped, failed, or non-zero worker cannot assert passed" };
+    }
+    const summary = boundedText(input.summary || "");
+    if (!summary)
+        return { ok: false, error: "worker result requires a non-empty summary" };
+    const timestamp = (options.now?.() ?? new Date()).toISOString();
+    const normalized = normalizeEvidence(input.evidence ?? [], input.workerId, role, timestamp);
+    if (normalized.error)
+        return { ok: false, error: normalized.error };
+    const evidence = normalized.evidence ?? [];
+    if (input.status === "passed" && evidence.length === 0) {
+        return { ok: false, error: "passed worker result requires typed evidence" };
+    }
+    if (journal.usage.evidenceItems + evidence.length > journal.budget.maxEvidenceItems) {
+        return { ok: false, error: "run evidence budget exhausted" };
+    }
+    const assertion = {
+        attempt: journal.attempt,
+        workerId: input.workerId,
+        role,
+        status: input.status,
+        summary,
+        evidence,
+        recordedAt: timestamp,
+    };
+    journal.workerAssertions = [...(journal.workerAssertions ?? []), assertion];
+    journal.evidence.push(...evidence);
+    journal.usage.evidenceItems += evidence.length;
+    appendRunEvent(journal, {
+        type: "worker_result",
+        at: timestamp,
+        fromStage: journal.stage,
+        toStage: journal.stage,
+        role,
+        workerId: input.workerId,
+        summary: `${input.status}: ${summary}`,
+    });
+    if (input.status === "failed") {
+        moveToRetryOrBlocked(journal, timestamp, summary, input.workerId, role);
+    }
+    else {
+        const roles = requiredExecutionRoles(journal);
+        const currentIndex = roles.indexOf(role);
+        journal.cursor = currentIndex === roles.length - 1 ? "reviewer" : roles[currentIndex + 1];
+        delete journal.workers[role];
+    }
+    journal.updatedAt = timestamp;
+    saveRunJournal(journal, options);
+    return { ok: true, journal };
+}
+/** Apply a terminal review. Approval completes; rejection retries or blocks at the budget. */
+function completeRunReview(input, options = {}) {
+    const journal = loadRunJournal(input.runId, options);
+    if (!journal)
+        return { ok: false, error: `run ${input.runId} was not found or is corrupt` };
+    if (journal.stage === "completed" || journal.stage === "blocked") {
+        return { ok: false, error: `run ${journal.runId} is already ${journal.stage}` };
+    }
+    if (journal.workers.reviewer !== input.reviewerId) {
+        return { ok: false, error: "reviewer_id must match the worker assigned to role=reviewer" };
+    }
+    if (journal.executionWorkerIds.includes(input.reviewerId)) {
+        return { ok: false, error: "specialist/self-approval is not allowed" };
+    }
+    if (!input.reviewerTerminal) {
+        return { ok: false, error: "reviewer must be terminal before complete_run" };
+    }
+    if (journal.workflowVersion === 2 && !input.reviewerSucceeded) {
+        return { ok: false, error: "reviewer must exit successfully; stopped, failed, and non-zero reviewers cannot approve" };
+    }
+    const summary = input.verdict.summary?.trim();
+    if (!summary || !["approved", "changes_requested"].includes(input.verdict.status)) {
+        return { ok: false, error: "verdict requires status=approved|changes_requested and a non-empty summary" };
+    }
+    const timestamp = (options.now?.() ?? new Date()).toISOString();
+    let concreteEvidence;
+    if (journal.workflowVersion === 2) {
+        if (journal.cursor !== "reviewer" || journal.stage !== "review") {
+            return { ok: false, error: `run ${journal.runId} is not ready for review (cursor=${journal.cursor})` };
+        }
+        const passedRoles = new Set((journal.workerAssertions ?? [])
+            .filter((assertion) => assertion.attempt === journal.attempt && assertion.status === "passed")
+            .map((assertion) => assertion.role));
+        const missing = requiredExecutionRoles(journal).filter((role) => !passedRoles.has(role));
+        if (missing.length)
+            return { ok: false, error: `review cannot complete; successful assertions missing: ${missing.join(", ")}` };
+        const normalized = normalizeEvidence(input.evidence ?? [], input.reviewerId, "reviewer", timestamp);
+        if (normalized.error)
+            return { ok: false, error: normalized.error };
+        concreteEvidence = normalized.evidence ?? [];
+        if (!journal.budget || !journal.usage)
+            return { ok: false, error: "run is missing budget state" };
+        if (journal.usage.evidenceItems + concreteEvidence.length > journal.budget.maxEvidenceItems) {
+            return { ok: false, error: "run evidence budget exhausted" };
+        }
+        const semantic = input.verdict.semanticSuccess;
+        if (!semantic || typeof semantic.met !== "boolean" || !boundedText(semantic.summary || "")) {
+            return { ok: false, error: "strict verdict requires semanticSuccess.met and a non-empty summary" };
+        }
+        if (input.verdict.status === "approved" && !semantic.met) {
+            return { ok: false, error: "approved verdict requires semanticSuccess.met=true" };
+        }
+        const issues = (input.verdict.issues ?? []).map(String).map((issue) => boundedText(issue)).filter(Boolean);
+        if (input.verdict.status === "approved" && issues.length > 0) {
+            return { ok: false, error: "approved verdict cannot carry unresolved issues" };
+        }
+        if (input.verdict.status === "changes_requested" && issues.length === 0) {
+            return { ok: false, error: "changes_requested verdict requires at least one actionable issue" };
+        }
+        if (input.verdict.status === "approved" && concreteEvidence.length === 0) {
+            return { ok: false, error: "approved verdict requires typed reviewer evidence" };
+        }
+    }
+    else {
+        concreteEvidence = (input.evidence ?? [])
+            .map(String)
+            .map((item) => item.trim())
+            .filter(Boolean)
+            .map((item) => ({
+            kind: "review",
+            source: `legacy:${input.reviewerId}`,
+            workerId: input.reviewerId,
+            role: "reviewer",
+            summary: boundedText(item),
+            recordedAt: timestamp,
+        }));
+        if (input.verdict.status === "approved" && concreteEvidence.length === 0) {
+            return { ok: false, error: "approved verdict requires at least one non-empty concrete evidence item" };
+        }
+    }
+    const fromStage = journal.stage;
+    const verdict = {
+        status: input.verdict.status,
+        reviewerId: input.reviewerId,
+        summary,
+        issues: (input.verdict.issues ?? []).map(String).map((issue) => boundedText(issue)).filter(Boolean),
+        semanticSuccess: input.verdict.semanticSuccess
+            ? { met: input.verdict.semanticSuccess.met, summary: boundedText(input.verdict.semanticSuccess.summary) }
+            : { met: input.verdict.status === "approved", summary: "legacy reviewer verdict" },
+        recordedAt: timestamp,
+    };
+    journal.reviewerVerdict = verdict;
+    appendRunEvent(journal, {
+        type: "review_recorded",
+        at: timestamp,
+        fromStage,
+        toStage: fromStage,
+        role: "reviewer",
+        workerId: input.reviewerId,
+        summary: `${verdict.status}: ${verdict.summary}`,
+    });
+    journal.evidence.push(...concreteEvidence);
+    if (journal.workflowVersion === 2 && journal.usage)
+        journal.usage.evidenceItems += concreteEvidence.length;
+    if (verdict.status === "approved") {
+        journal.stage = "completed";
+        journal.cursor = "done";
+        journal.completedAt = timestamp;
+        appendRunEvent(journal, {
+            type: "completed",
+            at: timestamp,
+            fromStage,
+            toStage: "completed",
+            role: "reviewer",
+            workerId: input.reviewerId,
+            summary: verdict.summary,
+        });
+    }
+    else if (journal.workflowVersion === 2) {
+        moveToRetryOrBlocked(journal, timestamp, verdict.summary, input.reviewerId, "reviewer");
+    }
+    else if (journal.attempt < journal.maxAttempts) {
+        journal.attempt += 1;
+        journal.stage = "retry_required";
+        delete journal.workers.reviewer;
+        appendRunEvent(journal, {
+            type: "retry_required", at: timestamp, attempt: journal.attempt, fromStage,
+            toStage: "retry_required", role: "reviewer", workerId: input.reviewerId, summary: verdict.summary,
+        });
+    }
+    else {
+        journal.stage = "blocked";
+        journal.blockedAt = timestamp;
+        appendRunEvent(journal, {
+            type: "blocked", at: timestamp, fromStage, toStage: "blocked", role: "reviewer",
+            workerId: input.reviewerId, summary: verdict.summary,
+        });
+    }
+    journal.updatedAt = timestamp;
+    saveRunJournal(journal, options);
+    return { ok: true, journal };
+}
+/** Discover only unfinished governed runs bound to this task or orchestration session. */
+function findBoundUnfinishedRunIds(binding, options = {}) {
+    const taskId = binding.taskId?.trim();
+    const sessionId = binding.sessionId?.trim();
+    if (!taskId && !sessionId)
+        return [];
+    let names;
+    try {
+        names = fs.readdirSync(runsDir(options));
+    }
+    catch {
+        return [];
+    }
+    const matches = [];
+    for (const name of names.sort()) {
+        if (!name.endsWith(".json"))
+            continue;
+        const runId = name.slice(0, -5);
+        if (!validRunId(runId))
+            continue;
+        const journal = loadRunJournal(runId, options);
+        if (!journal)
+            continue;
+        // A task binding is more specific than a goal-derived session. When present, use it
+        // exclusively so two distinct tasks with identical goal text cannot block one another.
+        const bound = taskId ? journal.taskId === taskId : Boolean(sessionId && journal.sessionId === sessionId);
+        if (!bound)
+            continue;
+        if (journal.stage === "completed" &&
+            journal.reviewerVerdict?.status === "approved" &&
+            (journal.workflowVersion !== 2 || journal.reviewerVerdict.semanticSuccess.met))
+            continue;
+        matches.push(runId);
+    }
+    return matches;
+}
+/** A governed loop may finish only after every run it touched has reviewer-approved completion. */
+function runFinishBlocker(runIds, options = {}) {
+    for (const runId of runIds) {
+        const journal = loadRunJournal(runId, options);
+        if (!journal)
+            return `governed run ${runId} is missing or corrupt`;
+        if (journal.stage !== "completed" ||
+            journal.reviewerVerdict?.status !== "approved" ||
+            (journal.workflowVersion === 2 && !journal.reviewerVerdict.semanticSuccess.met)) {
+            return `governed run ${runId} is ${journal.stage} (attempt ${journal.attempt}/${journal.maxAttempts}); a distinct terminal reviewer must approve it through complete_run`;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=run-journal.js.map