toolroll 0.5.0

package/dist/restart-certification.js

@@ -0,0 +1,226 @@
+/**
+ * Restart certification (plan acceptance 7): a BASELINE of the boot, the
+ * runtime, the installed service and the database's live custody, taken
+ * before a login or reboot; and a VERIFICATION afterwards against the same
+ * database — boot identity as the OS reports it, service liveness by a
+ * fresh heartbeat, recovery of what the old boot left pending, task
+ * completion — without printing a secret and without rebooting anything.
+ *
+ * The precise limits, written into every baseline so nobody reads more
+ * into a pass than it proves:
+ *   - macOS LaunchAgents resume at USER LOGIN after a reboot, not before
+ *     FileVault unlock / login; a machine that sits at the login window
+ *     runs nothing.
+ *   - Linux user services depend on a login session or `loginctl
+ *     enable-linger`; without linger the user manager stops at logout.
+ *   - The Windows Task Scheduler logon trigger is a LOGON trigger, not a
+ *     boot service.
+ *   - This tool never reboots, logs out, or restarts a service itself. A
+ *     physical reboot that has not happened is not claimed: `bootChanged`
+ *     is the OS's own word, and `unknown` stays unknown.
+ */
+import { hostname } from "node:os";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync, realpathSync, readdirSync, statSync } from "node:fs";
+import { bootIdentity, currentBootId, provenDeadByBootChange } from "./boot-identity.js";
+import { containmentStatus, currentContainment } from "./containment.js";
+import { daemonStatus } from "./daemon.js";
+import { isAlive } from "./runner.js";
+import { SCHEMA_VERSION } from "./store.js";
+export const RESTART_LIMITS = [
+    "macOS LaunchAgents resume at user login after a reboot, not before FileVault unlock/login; a machine at the login window runs nothing",
+    "Linux user services depend on a login session or loginctl enable-linger; without linger the user manager stops at logout",
+    "the Windows Task Scheduler logon trigger is a logon trigger, not a boot service",
+    "this tool never reboots, logs out, or restarts a service; bootChanged is the OS's own boot identity, and unknown stays unknown",
+    "a pass here certifies this database, this service label and this boot — not a physical reboot that did not happen",
+    "task recovery means earlier running attempts moved on; only explicitly named completion tasks must reach done",
+];
+function bootFacts(identity) {
+    return identity.ok ? { id: identity.id, source: identity.source, problem: null } : { id: null, source: null, problem: identity.detail };
+}
+const memoryIdentities = new WeakMap();
+function databaseIdentity(store) {
+    const file = store.raw().prepare("PRAGMA database_list").all().find(row => row["name"] === "main")?.["file"];
+    if (typeof file !== "string" || file === "") {
+        let id = memoryIdentities.get(store);
+        if (!id) {
+            id = randomUUID();
+            memoryIdentities.set(store, id);
+        }
+        return id;
+    }
+    const path = realpathSync(file), stat = statSync(path);
+    return createHash("sha256").update(JSON.stringify([path, stat.dev, stat.ino])).digest("hex");
+}
+export function restartRuntimeDigest(executable = process.execPath, root = dirname(fileURLToPath(import.meta.url))) {
+    const hash = createHash("sha256").update(readFileSync(executable));
+    for (const name of readdirSync(root).filter(name => /\.(js|ts|ps1)$/.test(name)).sort())
+        hash.update(name).update(readFileSync(join(root, name)));
+    return hash.digest("hex");
+}
+/** Everything a person needs to compare later, none of what they must not see. */
+export async function recordRestartBaseline(inputs) {
+    const { store } = inputs;
+    const now = inputs.now ?? new Date();
+    const raw = store.raw();
+    const service = inputs.service === undefined ? null : { ...(await daemonStatus(inputs.service.definition, inputs.service.run)), label: inputs.service.definition.label, platform: inputs.service.definition.platform };
+    const pendingStops = raw.prepare("SELECT run, task_ref, requested_at FROM run_stop WHERE settled_at IS NULL ORDER BY run").all()
+        .map(row => ({ run: Number(row["run"]), taskRef: Number(row["task_ref"]), requestedAt: String(row["requested_at"]), problem: store.stopQuiescenceProblem(Number(row["run"])) }));
+    const openRuns = raw.prepare("SELECT id, task_ref, role, runner, lease_id FROM run WHERE outcome IS NULL ORDER BY id").all()
+        .map(row => ({ id: Number(row["id"]), taskRef: Number(row["task_ref"]), role: String(row["role"]), runner: String(row["runner"]), leaseId: String(row["lease_id"]) }));
+    const witnesses = raw.prepare("SELECT run, pid, host, boot_id, containment, exited_at FROM run_process WHERE exited_at IS NULL ORDER BY id").all()
+        .map(row => ({ run: Number(row["run"]), pid: row["pid"] === null ? null : Number(row["pid"]), host: String(row["host"]), bootId: row["boot_id"] === null ? null : String(row["boot_id"]), containment: row["containment"] === null ? null : String(row["containment"]), open: true }));
+    return {
+        version: 2,
+        runnerName: inputs.runnerName ?? null,
+        completionTasks: [...(inputs.completionTasks ?? [])],
+        recordedAt: now.toISOString(),
+        host: hostname(),
+        boot: bootFacts(inputs.boot ?? bootIdentity()),
+        runtime: { digest: (inputs.runtimeDigest ?? restartRuntimeDigest)(), nodeVersion: process.version, execPath: process.execPath, platform: process.platform, packageVersion: inputs.packageVersion ?? readPackageVersion() },
+        containment: containmentStatus(currentContainment()),
+        service,
+        database: {
+            identity: databaseIdentity(store),
+            schemaVersion: SCHEMA_VERSION,
+            runners: store.listRunners().map(one => ({ name: one.name, host: one.host, heartbeatAt: one.heartbeatAt, alive: isAlive(one, now), retired: one.retiredAt !== null })),
+            pendingStops,
+            openRuns,
+            runningTasks: store.listTasks("running").map(task => task.id),
+            witnesses,
+        },
+        limits: RESTART_LIMITS,
+    };
+}
+function readPackageVersion() {
+    try {
+        const url = new URL("../package.json", import.meta.url);
+        if (!existsSync(url))
+            return null;
+        const parsed = JSON.parse(readFileSync(url, "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compare now against the baseline. Recovery is judged by the SAME rules
+ * the controller uses (stopQuiescenceProblem, settleQuiescentStops): a
+ * stop the old boot left pending settles only when its witnesses are
+ * proven gone — by the verified boot change, or by the probes — and a
+ * stop that still cannot settle is reported with the exact reason, never
+ * forced.
+ */
+export async function verifyRestartRecovery(inputs) {
+    const { store, baseline } = inputs;
+    const expectation = inputs.expect ?? "either";
+    const checks = [];
+    const identity = inputs.boot ?? bootIdentity();
+    const current = await recordRestartBaseline({ ...inputs, ...(baseline.runnerName ? { runnerName: baseline.runnerName } : {}), completionTasks: baseline.completionTasks ?? [], boot: identity });
+    const sameDatabase = baseline.version === 2 && baseline.database.identity === current.database.identity;
+    checks.push({ name: "database", ok: sameDatabase, detail: sameDatabase ? "same database file identity" : "database identity differs or baseline predates identity verification; no recovery mutations performed" });
+    // 1. Boot identity, as the OS reports it.
+    const sameHost = baseline.host === current.host;
+    const bootChanged = !sameHost || baseline.boot.id === null || current.boot.id === null
+        ? null
+        : provenDeadByBootChange({ host: current.host, bootId: baseline.boot.id }, { host: current.host, bootId: current.boot.id });
+    checks.push({ name: "host", ok: sameHost, detail: sameHost ? `same host ${current.host}` : `baseline was taken on ${baseline.host}, this is ${current.host} — nothing here certifies that machine` });
+    checks.push({
+        name: "boot-identity",
+        ok: bootChanged !== null && (expectation === "either" || (expectation === "reboot") === bootChanged),
+        detail: bootChanged === null
+            ? `boot identity unknown (baseline ${baseline.boot.id ?? baseline.boot.problem ?? "none"}, now ${current.boot.id ?? current.boot.problem ?? "none"}) — no reboot is claimed`
+            : bootChanged
+                ? `verified boot change ${baseline.boot.id} → ${current.boot.id}${expectation === "login" ? " — but a login without reboot was expected" : ""}`
+                : `same boot ${current.boot.id}${expectation === "reboot" ? " — the reboot has NOT happened" : ""}`,
+    });
+    // 2. Runtime identity.
+    const sameRuntime = baseline.runtime.digest === current.runtime.digest && baseline.runtime.execPath === current.runtime.execPath && baseline.runtime.nodeVersion === current.runtime.nodeVersion && baseline.runtime.packageVersion === current.runtime.packageVersion;
+    checks.push({ name: "runtime", ok: sameRuntime, detail: sameRuntime ? `same runtime node ${current.runtime.nodeVersion} at ${current.runtime.execPath}, package ${current.runtime.packageVersion ?? "?"}` : `runtime changed: ${baseline.runtime.nodeVersion}@${baseline.runtime.execPath} (${baseline.runtime.packageVersion ?? "?"}) → ${current.runtime.nodeVersion}@${current.runtime.execPath} (${current.runtime.packageVersion ?? "?"})` });
+    checks.push({ name: "schema", ok: current.database.schemaVersion === baseline.database.schemaVersion, detail: `schema v${baseline.database.schemaVersion} → v${current.database.schemaVersion}` });
+    // 3. Service liveness: loaded is not working; a working controller shows a running process AND a fresh heartbeat.
+    if (baseline.service !== null || current.service !== null) {
+        const service = current.service;
+        if (service === null)
+            checks.push({ name: "service", ok: false, detail: "no service definition was given to verify against" });
+        else {
+            const problems = service.problems.length === 0 ? "" : ` — ${service.problems.join("; ")}`;
+            checks.push({ name: "service", ok: service.state === "running" && service.problems.length === 0 && !service.stale && baseline.service?.label === service.label, detail: `${service.label}: ${service.detail}${service.stale ? " (installed definition is stale: reinstall to load the current one)" : ""}${problems}` });
+        }
+    }
+    const baselineBeats = new Map(baseline.database.runners.map(one => [one.name, one.heartbeatAt]));
+    const liveRunners = current.database.runners.filter(one => !one.retired);
+    const fresh = liveRunners.filter(one => one.host === current.host && one.alive && (baseline.runnerName === null || one.name === baseline.runnerName) && baselineBeats.has(one.name) && one.heartbeatAt > baselineBeats.get(one.name));
+    checks.push({
+        name: "heartbeat",
+        ok: fresh.length > 0,
+        detail: fresh.length > 0
+            ? `fresh live heartbeat from ${fresh.map(one => `${one.name} at ${one.heartbeatAt}`).join(", ")}`
+            : liveRunners.length === 0
+                ? "no live runner is registered — the controller has not come back"
+                : `no runner has beaten since the baseline (${liveRunners.map(one => `${one.name}: ${one.heartbeatAt}${one.alive ? "" : " (stale)"}`).join(", ")}) — a loaded service is not a working controller`,
+    });
+    // 4. Recovery of what the old boot left pending.
+    if (sameDatabase && inputs.recover !== false)
+        store.settleQuiescentStops(inputs.now ?? new Date());
+    const remaining = baseline.database.pendingStops.map(stop => ({ run: stop.run, settled: store.stopOf(stop.run)?.settledAt != null, problem: store.stopQuiescenceProblem(stop.run) }));
+    const unsettled = remaining.filter(one => !one.settled);
+    checks.push({
+        name: "pending-stops",
+        ok: unsettled.length === 0,
+        detail: baseline.database.pendingStops.length === 0
+            ? "no stop was pending at the baseline"
+            : unsettled.length === 0
+                ? `every pending stop settled (${remaining.map(one => `#${one.run}`).join(", ")})`
+                : `still pending: ${unsettled.map(one => `#${one.run} — ${one.problem ?? "unsettled"}`).join("; ")}`,
+    });
+    const staleOpen = current.database.openRuns.filter(run => baseline.database.openRuns.some(old => old.id === run.id));
+    checks.push({
+        name: "open-runs",
+        ok: staleOpen.length === 0,
+        detail: baseline.database.openRuns.length === 0
+            ? "no run was open at the baseline"
+            : staleOpen.length === 0
+                ? `every run open at the baseline has ended (${baseline.database.openRuns.map(run => `#${run.id}`).join(", ")})`
+                : `still open from before: ${staleOpen.map(run => `#${run.id} (${run.role}, ${run.runner})`).join(", ")} — recovery has not run, or its lease is still live`,
+    });
+    const oldWitnesses = baseline.database.witnesses.filter(one => one.bootId !== null && current.boot.id !== null && one.host === current.host);
+    const survivors = oldWitnesses.filter(one => !provenDeadByBootChange({ host: one.host, bootId: one.bootId }, { host: current.host, bootId: current.boot.id }));
+    checks.push({
+        name: "old-boot-custody",
+        ok: bootChanged !== true || survivors.length === 0,
+        detail: bootChanged === true
+            ? `${oldWitnesses.length} witness(es) of the previous boot are proven gone by boot identity`
+            : `${baseline.database.witnesses.length} open witness(es) at the baseline are judged by their probes, not by a boot change`,
+    });
+    // 5. Task completion since the baseline.
+    const stillRunning = current.database.runningTasks.filter(id => baseline.database.runningTasks.includes(id));
+    checks.push({
+        name: "tasks",
+        ok: stillRunning.length === 0,
+        detail: baseline.database.runningTasks.length === 0
+            ? "no task was running at the baseline"
+            : stillRunning.length === 0
+                ? `every task running at the baseline moved on (${baseline.database.runningTasks.join(", ")})`
+                : `still running from before: ${stillRunning.join(", ")}`,
+    });
+    for (const taskId of baseline.completionTasks ?? []) {
+        const task = store.getTask(taskId);
+        checks.push({ name: `completion:${taskId}`, ok: task?.state === "done", detail: task ? `${taskId}: ${task.state}` : `${taskId}: missing` });
+    }
+    return { ok: checks.every(check => check.ok), bootChanged, expectation, checks, current, limits: RESTART_LIMITS };
+}
+/** The baseline and verification are meant to be printed; this keeps a secret from ever entering them. */
+export function assertNoSecret(json, secrets) {
+    for (const secret of secrets) {
+        if (secret !== "" && json.includes(secret))
+            throw new Error("the certification output would contain a credential; refusing to write it");
+    }
+}
+/** The current boot id, for scripts that print it beside a baseline. */
+export function bootIdNow() {
+    return currentBootId();
+}

package/dist/result-actions.d.ts

@@ -0,0 +1,28 @@
+import type { Store } from "./store.js";
+export type RevisionResult = {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    status: number;
+    message: string;
+};
+type RevisionInput = Parameters<typeof createResultRevision>[2];
+/** One user action: add the typed change and seal exactly the displayed
+ * saved notes. A refusal rolls back the note; a replay returns the same task. */
+export declare function requestResultChanges(store: Store, evidenceRoot: string, input: RevisionInput & {
+    note: string;
+    path: string;
+    line: string;
+    request: string | null;
+}, now: Date): RevisionResult;
+export declare function createResultRevision(store: Store, evidenceRoot: string, input: {
+    run: number;
+    batch: string | null;
+    source: string | null;
+    actor: string;
+    repos: readonly string[] | null;
+    includeUnplaced?: boolean;
+    allowMode?: boolean;
+}, now: Date): RevisionResult;
+export {};

package/dist/result-actions.js

@@ -0,0 +1,270 @@
+/** Shared result-to-revision action for the result form and chat.
+ * The caller authenticates; this service checks project access and the exact
+ * displayed note batch, then uses the existing atomic revision/approval boundary.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { EVIDENCE_CAPS, readVerifiedArtifact, writeEvidenceFile } from "./evidence.js";
+import { isRevisionFeedback, parseRevisionBatch, revisionSourceOf, commentSourceKey, REQUEST_TOKEN } from "./result-review.js";
+import { validateNote, hasForbiddenControls } from "./decision.js";
+import { TASK_TEXT_LIMITS, validateTaskText } from "./task-text.js";
+import { modeFilingCoverage } from "./scope.js";
+/** One user action: add the typed change and seal exactly the displayed
+ * saved notes. A refusal rolls back the note; a replay returns the same task. */
+export function requestResultChanges(store, evidenceRoot, input, now) {
+    try {
+        return store.transact(() => store.savepoint(() => {
+            const fail = (status, message) => { throw new ChangeRequestRefusal(status, message); };
+            if (!input.note.trim()) {
+                if (input.path.trim() || input.line.trim())
+                    return fail(400, "Describe the change before attaching a file or line.");
+                if (!input.batch)
+                    return fail(400, "Describe a change or use a saved note.");
+                return createResultRevision(store, evidenceRoot, input, now);
+            }
+            const valid = validateNote(input.note);
+            if (!valid.ok)
+                return fail(400, valid.problem);
+            if (input.request === null || !REQUEST_TOKEN.test(input.request))
+                return fail(400, "Reload the result before requesting changes. Your draft stays here.");
+            const batch = input.batch === "" ? [] : parseRevisionBatch(input.batch);
+            if (batch === null)
+                return fail(400, "Reload the result to review the saved notes.");
+            const path = input.path.trim() || null;
+            const line = input.line.trim() === "" ? null : Number(input.line);
+            if (path !== null && (path.length > 300 || hasForbiddenControls(path)))
+                return fail(400, "Enter a file path of up to 300 characters, without control characters.");
+            if (line !== null && (path === null || !Number.isInteger(line) || line < 1 || line > 1_000_000))
+                return fail(400, "Choose a file and a whole line number from 1 to 1,000,000.");
+            const run = store.getRun(input.run);
+            const repo = run === null ? null : store.refById(run.taskRef)?.repo ?? null;
+            if (run === null || (repo === null ? input.includeUnplaced !== true : input.repos !== null && !input.repos.includes(repo)))
+                return fail(404, "No such result.");
+            const artifact = store.artifactsFor(run.id).find(one => one.kind === "terminal-diff");
+            if (!artifact || !readVerifiedArtifact(evidenceRoot, artifact).ok)
+                return fail(409, "The saved changes could not be verified. Restore the result before requesting changes.");
+            const sourceKey = commentSourceKey(input.actor, input.request);
+            let noteId = store.addDiffComment({ artifactId: artifact.id, runId: run.id, path, line, note: valid.note, author: input.actor, sourceKey }, now);
+            if (noteId === null) {
+                const earlier = store.diffCommentBySourceKey(sourceKey);
+                if (!earlier || earlier.run !== run.id || earlier.path !== path || earlier.line !== line || earlier.note !== valid.note)
+                    return fail(409, "This submission already saved different feedback. Reopen the result and try again.");
+                noteId = earlier.id;
+            }
+            const result = createResultRevision(store, evidenceRoot, { ...input, batch: [...new Set([...batch, noteId])].sort((a, b) => a - b).join(",") }, now);
+            if (!result.ok)
+                return fail(result.status, result.message);
+            return result;
+        }));
+    }
+    catch (error) {
+        if (error instanceof ChangeRequestRefusal)
+            return { ok: false, status: error.status, message: error.message };
+        throw error;
+    }
+}
+class ChangeRequestRefusal extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export function createResultRevision(store, evidenceRoot, input, now) {
+    return store.transact(() => {
+        const id = input.run;
+        const visible = (repo) => repo === null ? input.includeUnplaced === true : input.repos === null || input.repos.includes(repo);
+        const fail = (status, message) => ({ ok: false, status, message });
+        const found = store.getRun(id);
+        if (found === null || !visible(store.refById(found.taskRef)?.repo ?? null))
+            return fail(404, "No such result.");
+        const sourceTaskId = store.externalIdFor(found.taskRef) ?? "?";
+        const sourceScope = store.getScope(sourceTaskId);
+        const sourceFamily = store.taskFamilyOf(sourceTaskId, input.repos, input.includeUnplaced ?? false);
+        if (sourceFamily === null || sourceFamily.problem !== null)
+            return fail(409, "The revision history cannot be verified in this project.");
+        const repo = store.refById(found.taskRef)?.repo ?? null;
+        // THE DISPLAYED BATCH (repair 2026-09-14, finding 2): the form names
+        // the exact note ids its reader saw and the source terms it was
+        // rendered against. The seal binds to those ids and nothing else —
+        // "every live note at POST time" would let an old submission, a
+        // replay, or a second tab consume notes its reader never displayed.
+        const batchIds = parseRevisionBatch(input.batch);
+        const postedSource = input.source;
+        if (batchIds === null || postedSource === null || postedSource === "") {
+            return fail(400, "this form is out of date — it names no note batch; reload the result and create the revision from the notes shown there");
+        }
+        const byId = new Map(store.allDiffComments(id).map(one => [one.id, one]));
+        const named = batchIds.map(one => byId.get(one));
+        if (named.some(one => one === undefined)) {
+            return fail(400, "this batch names notes that are not on this result — reload the result");
+        }
+        const batch = named;
+        // A replay must match the immutable brief's entire batch and source,
+        // not just a subset whose notes happen to name the same child. Read-only
+        // replay can return its original child even after the source is rescoped.
+        const replayChild = (notes) => {
+            const child = notes[0]?.consumedBy;
+            if (!child || notes.length !== batchIds.length || notes.some(one => one.consumedBy !== child))
+                return null;
+            const ref = store.lookupRef(child);
+            const lineage = ref === null ? null : store.revisionSourceOf(ref.id);
+            if (ref === null || !visible(ref.repo) || lineage === null || lineage.sourceRun !== id || lineage.sourceTask !== sourceTaskId)
+                return null;
+            try {
+                const read = readVerifiedArtifact(evidenceRoot, lineage.briefArtifact);
+                if (!read.ok)
+                    return null;
+                const brief = JSON.parse(read.content.toString("utf8"));
+                if (brief.sourceRun !== id || brief.sourceTask !== sourceTaskId || revisionSourceOf(brief.sourceScopeDigest) !== postedSource || !Array.isArray(brief.comments))
+                    return null;
+                return brief.comments.length === batchIds.length && brief.comments.every((one, at) => one.id === batchIds[at]) ? child : null;
+            }
+            catch {
+                return null;
+            }
+        };
+        // A retry of an OLD request: every note it names is already sealed
+        // into one revision — that revision is the answer, and no note added
+        // since is touched. A batch partly sealed elsewhere is refused whole.
+        const consumers = new Set(batch.map(one => one.consumedBy).filter((one) => one !== null));
+        const replay = replayChild(batch);
+        if (replay !== null)
+            return { ok: true, id: replay };
+        if (consumers.size > 0) {
+            return fail(409, `some of these notes were already sealed into revision ${[...consumers].join(", ")}; the others are still waiting — reload the result to see the current batch`);
+        }
+        if (postedSource !== revisionSourceOf(sourceScope?.digest ?? null)) {
+            return fail(409, "the task's terms changed since this page was shown — reload the result and read the current terms before creating a revision");
+        }
+        if (batch.some(one => one.supersededBy !== null)) {
+            return fail(409, "a note in this batch was superseded — reload the result to see the current batch");
+        }
+        if (batch.some(one => !isRevisionFeedback(one)))
+            return fail(409, "Review observations are not requested changes. Use Request change to add your feedback first.");
+        const comments = batch;
+        // Keep the subject recognizable, including when revising a revision.
+        // Reserve the suffix before truncating, at whole grapheme boundaries.
+        const suffix = " — revision";
+        const subject = (store.getTask(sourceTaskId)?.title ?? "").trim().replace(/(?: — revision)+$/u, "").trim() || "Task";
+        let prefix = "";
+        for (const { segment } of new Intl.Segmenter("en", { granularity: "grapheme" }).segment(subject)) {
+            if ((prefix + segment + suffix).length > TASK_TEXT_LIMITS.title)
+                break;
+            prefix += segment;
+        }
+        const candidateTitle = `${prefix.trimEnd() || "Task"}${suffix}`;
+        const title = validateTaskText({ title: candidateTitle }) === null ? candidateTitle : `Task${suffix}`;
+        const feedbackKind = comments.every(one => one.path !== null) ? "annotations" : "feedback";
+        const terminal = store.artifactsFor(id).find(one => one.kind === "terminal-diff");
+        if (terminal !== undefined) {
+            const proven = readVerifiedArtifact(evidenceRoot, terminal);
+            if (!proven.ok) {
+                return fail(409, `the reviewed diff no longer verifies (${proven.problem}) — the batch cannot seal against it`);
+            }
+        }
+        // The brief is serialized and size-checked BEFORE anything is created
+        // (Codex M5-M8 audit, IV-3): a structured artifact must never pass
+        // through byte truncation — truncated JSON is not a smaller brief,
+        // it is no brief wearing one's name.
+        const brief = {
+            schema: 1,
+            sourceTask: sourceTaskId,
+            sourceRun: id,
+            sourceScopeDigest: sourceScope?.digest ?? null,
+            head: found.headRevision,
+            diffArtifactSha: terminal?.sha256 ?? null,
+            comments: comments.map(one => ({
+                id: one.id,
+                path: one.path,
+                line: one.line,
+                note: one.note,
+                author: one.author,
+                createdAt: one.createdAt,
+            })),
+        };
+        const briefBytes = Buffer.from(JSON.stringify(brief, null, 2), "utf8");
+        if (briefBytes.length > EVIDENCE_CAPS["revision-brief"]) {
+            return fail(400, "this batch is too large for one brief — seal it in parts");
+        }
+        // The file first, under a nonce name — a file whose seal fails is an
+        // orphan on disk, never authority. Then ONE transaction: task with
+        // the source scope's limits INHERITED (audit IV-2 — a revision that
+        // drops the exclusions is an approval screen telling a lie), the
+        // artifact row, the relation, and exactly this comment batch.
+        const briefName = `revision-brief-${randomBytes(6).toString("hex")}.json`;
+        const key = writeEvidenceFile(evidenceRoot, id, briefName, briefBytes);
+        // C1's revision arm: when the SEALER is the mode's signer and the
+        // mode auto-approves their filings, the revision task approves
+        // inside the same transaction, with mode provenance. Everything
+        // else about the seal is unchanged; without coverage, the revision
+        // keeps its own approval ceremony.
+        const sealed = store.transact(() => {
+            // Coverage first (cookie road only): its budget and escalated
+            // posture ride the FILING so the digest binds them (surfaces
+            // round 1, finding 2) — never a stamp after the fact.
+            const coverage = input.allowMode === true ? modeFilingCoverage(store, repo, input.actor, now) : null;
+            // ONE revision boundary (contract handoff task 2): the source's
+            // goal, exclusions, touches, rubric, risk, quality, posture,
+            // budget, overrides and pins are read from the SOURCE ROWS inside
+            // the seal, which re-proves the task/run/scope-digest binding and
+            // the brief's custody first — the scope read above only names the
+            // digest this batch was drafted against.
+            const result = store.sealRevision({
+                source: { task: sourceTaskId, run: id, scopeDigest: sourceScope?.digest ?? null },
+                brief: { evidenceRoot, key, sha256: createHash("sha256").update(briefBytes).digest("hex"), bytes: briefBytes.length, capture: "machine-authored revision brief (exit 0)" },
+                child: {
+                    title: `Revise ${sourceTaskId} from ${comments.length} annotation${comments.length === 1 ? "" : "s"} on build #${id}`,
+                    repair: `apply the ${feedbackKind} recorded on build #${id}; the revision brief carries the exact batch`,
+                },
+                commentIds: comments.map(one => one.id),
+                coverage,
+                requestedBy: input.actor,
+            }, now);
+            if (result.ok) {
+                // The unchanged legacy title above feeds the store's existing slug
+                // and collision handling. Set only this new row's display title,
+                // atomically with its seal; retries returned earlier, untouched.
+                store.raw().prepare("UPDATE task SET title = ? WHERE id = ?").run(title, result.id);
+            }
+            // Planned afresh: the planner reads the copied terms and these notes, and a note asking for
+            // more than the old plan allows becomes an amendment the person approves before anything
+            // builds. Under a live mode the filing is approved at once instead, as every signer filing
+            // is; revisions never inherit the mode's planner authority (docs/AUTO_APPROVAL.md).
+            if (result.ok && coverage === null) {
+                const ref = store.lookupRef(result.id);
+                if (ref !== null)
+                    store.requestPlan(ref.id, now);
+            }
+            if (result.ok && coverage !== null) {
+                // A scope whose profile could not resolve is unapprovable by the
+                // human road (approve() refuses) — the mode road refuses too.
+                const filedScope = store.getScope(result.id);
+                if (filedScope?.profileState === "resolved") {
+                    // A false answer here is the coordinator quarantine (review
+                    // finding 7): the revision stays honestly unapproved and the
+                    // task page it redirects to says so in the quarantine words.
+                    void store.sealScopeApproval(result.id, input.actor, now, {}, { kind: "mode", modeDigest: coverage.digest });
+                }
+            }
+            return result;
+        });
+        if (!sealed.ok) {
+            // Two sealers of one batch race on the consumption count; the
+            // loser is sent to the winner's revision — the one that consumed
+            // EXACTLY this batch, never merely the newest child of the run — so
+            // a double click or a two-tab submission lands on ONE revision.
+            if (sealed.reason === "duplicate" || sealed.reason === "comments-taken") {
+                const settled = store.allDiffComments(id).filter(one => batchIds.includes(one.id));
+                const takers = new Set(settled.map(one => one.consumedBy).filter((one) => one !== null));
+                const winner = replayChild(settled);
+                if (winner !== null)
+                    return { ok: true, id: winner };
+                if (takers.size > 0) {
+                    return fail(409, `some of these notes were just sealed into revision ${[...takers].join(", ")}; the others are still waiting — reload the result to see the current batch`);
+                }
+            }
+            return fail(409, `could not seal the revision: ${sealed.detail}`);
+        }
+        return { ok: true, id: sealed.id };
+    });
+}

package/dist/result-completion.d.ts

@@ -0,0 +1,18 @@
+/**
+ * v102: what a result actually changed, read from the build's sealed diff
+ * inventory, and whether a result that changed protected files may go out.
+ * Completion and publication share this so neither can be the gap.
+ */
+import type { Store } from "./store.js";
+/** The ledger action a person's (or lead's) completion of a result writes. */
+export declare const COMPLETION_ACTION = "assignment handoff checked";
+/** The files a build changed, renames on both sides; null when the inventory can't be read whole. */
+export declare function changedFilesOf(store: Store, runId: number, root: string): string[] | null;
+/** Everything a result's branch carries: this build's changes and every build of every task it revises (a
+ * revision builds on its source's head, so its branch holds the source's commits too). null when any of
+ * them can't be read whole. */
+export declare function familyChangedFiles(store: Store, taskId: string, runId: number, root: string): string[] | null;
+/** Why a build's branch must wait before it's pushed (and so before any PR or merge): it (or a task it
+ * revises) changed protected files on a one-person approval, and nobody but its approver and requesters
+ * has marked it complete. */
+export declare function protectedPublicationHold(store: Store, runId: number, root: string): string | null;

package/dist/result-completion.js

@@ -0,0 +1,66 @@
+import { readVerifiedArtifact } from "./evidence.js";
+/** The ledger action a person's (or lead's) completion of a result writes. */
+export const COMPLETION_ACTION = "assignment handoff checked";
+/** The files a build changed, renames on both sides; null when the inventory can't be read whole. */
+export function changedFilesOf(store, runId, root) {
+    const stat = store.artifactsFor(runId).find(one => one.kind === "diff-stat");
+    if (stat === undefined || stat.truncated || stat.captureStatus !== "ok")
+        return null;
+    const read = readVerifiedArtifact(root, stat);
+    if (!read.ok)
+        return null;
+    try {
+        const inventory = JSON.parse(read.content.toString("utf8"));
+        if (inventory.filesTruncated !== false || !Array.isArray(inventory.files))
+            return null;
+        // A rename changes both places: moving a protected file out of its folder touches it.
+        return inventory.files.flatMap(one => [one.path, one.renamedFrom]).filter((path) => typeof path === "string" && path !== "");
+    }
+    catch {
+        return null;
+    }
+}
+/** Everything a result's branch carries: this build's changes and every build of every task it revises (a
+ * revision builds on its source's head, so its branch holds the source's commits too). null when any of
+ * them can't be read whole. */
+export function familyChangedFiles(store, taskId, runId, root) {
+    const files = new Set();
+    const runs = new Set([runId]);
+    const chain = store.revisionAncestryStatus(taskId).chain;
+    for (const id of chain.length === 0 ? [taskId] : chain) {
+        const ref = store.lookupRef(id);
+        if (ref === null)
+            continue;
+        for (const run of store.runsFor(ref.id))
+            if ((run.role === "builder" || run.role === "repair") && (id !== taskId || run.id === runId))
+                runs.add(run.id);
+    }
+    for (const id of runs) {
+        // A build that never recorded a diff contributed nothing to the branch; one whose diff can't be read counts as protected.
+        if (!store.artifactsFor(id).some(one => one.kind === "diff-stat") && id !== runId)
+            continue;
+        const changed = changedFilesOf(store, id, root);
+        if (changed === null)
+            return null;
+        for (const file of changed)
+            files.add(file);
+    }
+    return [...files];
+}
+/** Why a build's branch must wait before it's pushed (and so before any PR or merge): it (or a task it
+ * revises) changed protected files on a one-person approval, and nobody but its approver and requesters
+ * has marked it complete. */
+export function protectedPublicationHold(store, runId, root) {
+    const run = store.getRun(runId);
+    const taskId = run === null ? null : store.externalIdFor(run.taskRef);
+    if (taskId === null)
+        return null;
+    const changed = familyChangedFiles(store, taskId, runId, root);
+    if (store.protectedResultProblem(taskId, changed, null) === null)
+        return null;
+    const completers = store.handle.prepare("SELECT DISTINCT actor FROM action_ledger WHERE run_id = ? AND action = ?").all(runId, COMPLETION_ACTION)
+        .map(row => String(row["actor"])).filter(actor => actor.startsWith("operator:")).map(actor => actor.slice("operator:".length));
+    if (completers.some(name => store.protectedResultProblem(taskId, changed, name) === null))
+        return null;
+    return "held: it changed protected files on a one-person approval, so it publishes once someone other than its approver marks it complete";
+}