toolroll 0.5.0

package/dist/codex-limits.d.ts

@@ -0,0 +1,15 @@
+import { type LimitReading } from "./provider-limits.js";
+import type { Store } from "./store.js";
+/** Ask Codex for its limits: its app server over stdio, in its own process group and a scratch folder, one read,
+ * then gone (killed if it lingers). Resolves once the process has ended; null when Codex isn't installed or doesn't
+ * answer in time. A key account has no windows but says so (`billing`). */
+export declare function readCodexLimits(options?: {
+    command?: string;
+    timeoutMs?: number;
+    graceMs?: number;
+}): Promise<LimitReading | null>;
+/** The loop beside the console: Codex's limits and account every five minutes while Toolroll runs Codex on its
+ * plan. Never in tests, the demo, or the end-to-end harness (which runs with the person's own sign-in), and never while
+ * a Codex build is running (both would refresh the same sign-in). One read at a time: the next waits for the last
+ * process to end. */
+export declare function startCodexLimits(store: Store, everyMs?: number): () => void;

package/dist/codex-limits.js

@@ -0,0 +1,145 @@
+/** Codex's plan limits and account, read from its app server (v105): kept apart from provider-limits.ts so the run
+ * pipeline that notes Claude's readings never loads Codex's transport. */
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+import { codingEnvironment } from "./coding-provider.js";
+import { codexLimitsOf, record } from "./provider-limits.js";
+import { billingOf } from "./spend.js";
+import { envValue } from "./names.js";
+/** How Codex says its account bills (`account/read`'s account): a ChatGPT sign-in is its plan unless the plan itself is
+ * billed by use; a key or Amazon Bedrock is a key. */
+function accountBilling(account) {
+    const type = account?.["type"];
+    if (typeof type !== "string")
+        return undefined;
+    if (type.toLowerCase() === "chatgpt")
+        return typeof account["planType"] === "string" && /usage.?based/i.test(account["planType"]) ? "api-key" : "subscription";
+    return /api.?key|bedrock/i.test(type) ? "api-key" : undefined;
+}
+/** End the app server and everything it started: its process group, then a kill after a grace period. */
+function end(child, graceMs) {
+    return new Promise(done => {
+        const signal = (name) => {
+            try {
+                if (child.pid !== undefined && process.platform !== "win32")
+                    process.kill(-child.pid, name);
+                else
+                    child.kill(name);
+            }
+            catch { /* gone */ }
+        };
+        // The leader may be gone while something it started lives on: the group hears it either way.
+        if (child.exitCode !== null || child.signalCode !== null) {
+            signal("SIGKILL");
+            return done();
+        }
+        const hard = setTimeout(() => { signal("SIGKILL"); setTimeout(done, 1_000).unref?.(); }, graceMs);
+        hard.unref?.();
+        child.once("exit", () => { clearTimeout(hard); done(); });
+        signal("SIGTERM");
+    });
+}
+/** Ask Codex for its limits: its app server over stdio, in its own process group and a scratch folder, one read,
+ * then gone (killed if it lingers). Resolves once the process has ended; null when Codex isn't installed or doesn't
+ * answer in time. A key account has no windows but says so (`billing`). */
+export function readCodexLimits(options = {}) {
+    return new Promise(resolve => {
+        const env = codingEnvironment();
+        // Its plan's limits: a key in the environment would make it an API account.
+        for (const key of ["OPENAI_API_KEY", "CODEX_API_KEY"])
+            delete env[key];
+        let child;
+        try {
+            child = spawn(options.command ?? "codex", ["app-server", "--listen", "stdio://"], {
+                cwd: tmpdir(), env, shell: false, windowsHide: true, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "ignore"],
+            });
+        }
+        catch {
+            resolve(null);
+            return;
+        }
+        let settled = false;
+        let buffered = "";
+        let billing;
+        let limits;
+        let accountRead = false;
+        const finish = (reading) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const answer = reading ?? (billing === undefined ? null : { provider: "codex", plan: null, windows: [], partial: true, billing });
+            void end(child, options.graceMs ?? 3_000).then(() => resolve(answer === null || billing === undefined ? answer : { ...answer, billing }));
+        };
+        const timer = setTimeout(() => finish(limits ?? null), options.timeoutMs ?? 15_000);
+        child.once("error", () => finish(null));
+        child.once("exit", () => finish(null));
+        child.stdin?.on("error", () => finish(null));
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            buffered += chunk;
+            if (buffered.length > 256 * 1024)
+                return finish(null);
+            let newline;
+            while ((newline = buffered.indexOf("\n")) !== -1) {
+                const line = buffered.slice(0, newline);
+                buffered = buffered.slice(newline + 1);
+                let message = null;
+                try {
+                    message = record(JSON.parse(line));
+                }
+                catch {
+                    continue;
+                }
+                if (message?.["id"] === 1) {
+                    child.stdin?.write([{ jsonrpc: "2.0", method: "initialized" }, { jsonrpc: "2.0", id: 2, method: "account/rateLimits/read" },
+                        { jsonrpc: "2.0", id: 3, method: "account/read", params: {} }].map(one => `${JSON.stringify(one)}\n`).join(""));
+                }
+                else if (message?.["id"] === 2) {
+                    limits = message["error"] === undefined ? codexLimitsOf(message["result"]) : null;
+                }
+                else if (message?.["id"] === 3) {
+                    accountRead = true;
+                    billing = accountBilling(record(record(message["result"])?.["account"]));
+                }
+                if (limits !== undefined && accountRead)
+                    finish(limits);
+            }
+        });
+        child.stdin?.write(`${JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { clientInfo: { name: "toolroll", version: "1" } } })}\n`);
+    });
+}
+/** The loop beside the console: Codex's limits and account every five minutes while Toolroll runs Codex on its
+ * plan. Never in tests, the demo, or the end-to-end harness (which runs with the person's own sign-in), and never while
+ * a Codex build is running (both would refresh the same sign-in). One read at a time: the next waits for the last
+ * process to end. */
+export function startCodexLimits(store, everyMs = 5 * 60_000) {
+    if (process.env["VITEST"] !== undefined || envValue(process.env, "NO_PLAN_PROBE") !== undefined || store.isDemo())
+        return () => { };
+    let stopped = false, busy = false;
+    const pass = async () => {
+        if (stopped || busy || billingOf("codex") !== "subscription")
+            return;
+        // A Codex run started in the last few hours and not finished: let it have the sign-in to itself.
+        const recent = new Date(Date.now() - 6 * 3_600_000).toISOString();
+        if (store.handle.prepare("SELECT 1 AS live FROM run WHERE provider = 'codex' AND outcome IS NULL AND started_at > ? LIMIT 1").get(recent) !== undefined)
+            return;
+        busy = true;
+        try {
+            const reading = await readCodexLimits();
+            if (reading !== null && !stopped)
+                store.recordProviderLimits(reading, new Date());
+        }
+        catch {
+            // The next pass tries again.
+        }
+        finally {
+            busy = false;
+        }
+    };
+    const timer = setInterval(() => void pass(), everyMs);
+    timer.unref?.();
+    const first = setTimeout(() => void pass(), 10_000);
+    first.unref?.();
+    return () => { stopped = true; clearInterval(timer); clearTimeout(first); };
+}

package/dist/coding-context.d.ts

@@ -0,0 +1,55 @@
+import type { Store } from './store.js';
+export type CodingContextMetadata = {
+    version: 1;
+    repo: string;
+    identity: string;
+    baseRevision: string;
+    knowledge: {
+        revision: number;
+        selectionSha256: string;
+        references: {
+            id: string;
+            title: string;
+            path: string | null;
+            sourceSha: string | null;
+            sourceRevision: string | null;
+        }[];
+        omitted: {
+            title: string;
+            reason: string;
+        }[];
+    };
+    skills: {
+        revision: number;
+        packages: {
+            name: string;
+            sha256: string;
+            skillFile: string;
+        }[];
+    };
+    directory: string | null;
+    files: {
+        path: string;
+        sha256: string;
+    }[];
+};
+export type CodingContext = {
+    text: string;
+    metadata: CodingContextMetadata;
+    sha256: string;
+};
+/**
+ * Call before thread/start with the canonical project and the exact worktree
+ * base. Persist the returned object with the coding session and reuse it on
+ * resume; calling this again intentionally selects a new context version.
+ * root is a coordinator-owned directory outside repository worktrees.
+ */
+export declare function prepareCodingContext(store: Store, args: {
+    repo: string;
+    actor: string;
+    baseRevision: string;
+    prompt: string;
+    root: string;
+}): CodingContext;
+/** Integrity check for a persisted capture. The caller must separately recheck current account access. */
+export declare function verifyCodingContext(context: CodingContext, repo: string, baseRevision: string): void;

package/dist/coding-context.js

@@ -0,0 +1,92 @@
+/** Managed context captured once for a native coding session; no synthetic worker runs. */
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename, dirname, join, resolve, relative, isAbsolute, sep } from 'node:path';
+import { KNOWLEDGE_GUIDANCE, selectProjectKnowledge } from './project-knowledge.js';
+import { materializeProjectSkills, PROJECT_SKILLS_GUIDANCE, selectProjectSkills } from './project-skills.js';
+import { learningIdentity, learningSha } from './project-learning.js';
+function freeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            freeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+const digest = (text, metadata) => learningSha(JSON.stringify({ text, metadata }));
+const fileDigest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+function futureRealPath(path) {
+    let existing = resolve(path);
+    const suffix = [];
+    while (!existsSync(existing)) {
+        suffix.unshift(basename(existing));
+        existing = dirname(existing);
+    }
+    if (!statSync(existing).isDirectory())
+        throw Error('Choose a directory for managed coding context.');
+    return resolve(realpathSync(existing), ...suffix);
+}
+/**
+ * Call before thread/start with the canonical project and the exact worktree
+ * base. Persist the returned object with the coding session and reuse it on
+ * resume; calling this again intentionally selects a new context version.
+ * root is a coordinator-owned directory outside repository worktrees.
+ */
+export function prepareCodingContext(store, args) {
+    const captured = store.transact(() => {
+        const knowledge = selectProjectKnowledge(store, { repo: args.repo, actor: args.actor, query: args.prompt, baseRevision: args.baseRevision });
+        const skills = selectProjectSkills(store, args.repo, args.actor);
+        return { identity: learningIdentity(args.repo), knowledge, skills };
+    });
+    // The materialized package must not become an agent-authored repository
+    // change or replace native .agents, .codex, AGENTS.md, or MCP configuration.
+    const root = futureRealPath(args.root);
+    const fromRepo = relative(args.repo, root);
+    if (!fromRepo || (!fromRepo.startsWith('..' + sep) && !isAbsolute(fromRepo) && fromRepo !== '..'))
+        throw Error('Store managed coding context outside the project worktree.');
+    const supplied = materializeProjectSkills(captured.skills, root, 'coding');
+    const directory = supplied.directory === null ? null : realpathSync(supplied.directory);
+    const parts = [];
+    if (captured.knowledge.revision > 0)
+        parts.push(KNOWLEDGE_GUIDANCE, JSON.stringify(captured.knowledge));
+    if (supplied.catalog.length)
+        parts.push('Project skills supplied for this coding session. ' + PROJECT_SKILLS_GUIDANCE, JSON.stringify(supplied.catalog));
+    const text = parts.length ? '\nToolroll project context, frozen when this coding session started. Native repository and home instructions, tools, and MCP configuration still apply.\n' + parts.join('\n') + '\n' : '';
+    const metadata = {
+        version: 1,
+        repo: args.repo,
+        identity: captured.identity,
+        baseRevision: args.baseRevision,
+        knowledge: {
+            revision: captured.knowledge.revision,
+            selectionSha256: learningSha(JSON.stringify(captured.knowledge)),
+            references: captured.knowledge.references.map(({ id, title, path, sourceSha, sourceRevision }) => ({ id, title, path, sourceSha, sourceRevision })),
+            omitted: captured.knowledge.omitted,
+        },
+        skills: {
+            revision: captured.skills.revision,
+            packages: supplied.catalog.map(skill => ({ name: skill.name, sha256: skill.version, skillFile: skill.skillFile })),
+        },
+        directory,
+        files: captured.skills.packages.flatMap(skill => skill.files.map(file => ({ path: `${skill.name}/${file.path}`, sha256: fileDigest(Buffer.from(file.base64, 'base64')) }))),
+    };
+    return freeze({ text, metadata, sha256: digest(text, metadata) });
+}
+/** Integrity check for a persisted capture. The caller must separately recheck current account access. */
+export function verifyCodingContext(context, repo, baseRevision) {
+    if (context.metadata.version !== 1 || context.metadata.repo !== repo || context.metadata.baseRevision !== baseRevision || context.metadata.identity !== learningIdentity(repo) || context.sha256 !== digest(context.text, context.metadata))
+        throw Error('The coding session context could not be verified.');
+    if (context.metadata.files.length && context.metadata.directory === null)
+        throw Error('The coding session skill files are unavailable.');
+    try {
+        for (const file of context.metadata.files) {
+            const directory = context.metadata.directory;
+            const path = join(directory, file.path);
+            if (file.path.split('/').some(segment => !segment || segment === '.' || segment === '..') || isAbsolute(file.path) || realpathSync(path) !== path || !statSync(path).isFile() || fileDigest(readFileSync(path)) !== file.sha256)
+                throw Error('Changed skill file.');
+        }
+    }
+    catch (cause) {
+        throw Error('A coding session skill file changed or is unavailable.', { cause });
+    }
+}

package/dist/coding-handoff.d.ts

@@ -0,0 +1,57 @@
+import { type AcceptanceCriterion } from './scope.js';
+import type { Store } from './store.js';
+export type CodingHandoffPreview = {
+    sessionId: string;
+    repo: string;
+    base: string;
+    candidate: string;
+    title: string;
+    originalPrompt: string;
+    changedPaths: string[];
+};
+type ReceiptTerms = CodingHandoffPreview & {
+    version: 1;
+    identity: string;
+    actor: string;
+    generation: number;
+    goal: string;
+    acceptance: AcceptanceCriterion[];
+    outOfScope: string;
+};
+export type CodingHandoffReceipt = ReceiptTerms & {
+    id: string;
+    taskId: string;
+    branch: string;
+};
+export type CodingHandoffInput = {
+    sessionId: string;
+    repo: string;
+    base: string;
+    candidate: string;
+    title: string;
+    goal: string;
+    acceptance: unknown;
+    actor: string;
+};
+type Handoff = {
+    taskId: string;
+    scopeDigest: string;
+    receipt: CodingHandoffReceipt;
+};
+export declare function codingHandoffPreview(store: Store, input: {
+    sessionId: string;
+    actor: string;
+}): CodingHandoffPreview;
+/** Returns null only for ordinary tasks. A coding marker always requires its receipt. */
+export declare function readCodingHandoff(store: Store, taskId: string): Handoff | null;
+/** No agent dispatch, approval, push, or modification of an existing Git ref. */
+export declare function createCodingHandoff(store: Store, input: CodingHandoffInput): Handoff;
+/** Called before setup and immediately before recording the attempt's base. */
+export declare function verifyCodingHandoffBase(store: Store, input: {
+    taskId: string;
+    taskRef: number;
+    repo: string;
+    branch: string;
+    head: string;
+}): void;
+export {};

package/dist/coding-handoff.js

@@ -0,0 +1,277 @@
+/** A committed native session enters the existing review flow, never another executor. */
+import { execFileSync } from 'node:child_process';
+import { lstatSync, realpathSync } from 'node:fs';
+import { sqliteRuntime } from './sqlite-runtime.js';
+import { codingCatalogPath } from './coding-update.js';
+import { updateAdmissionPaused } from './desktop-update-gate.js';
+import { learningIdentity, learningSha } from './project-learning.js';
+import { fileTaskProposal } from './proposal.js';
+import { parseAcceptanceCriteria, proposeGuarded } from './scope.js';
+import { validateTaskText } from './task-text.js';
+import { PROOF_LIMITS } from './proof.js';
+import { readPreparedEvidence } from './prepared-evidence.js';
+import { BRANCH_PREFIXES, taskBranch } from './names.js';
+const PREFIX = 'coding:';
+const SHA = /^[a-f0-9]{40}$/;
+const EXCLUSIONS = 'Verify the saved candidate only. Further code changes need a new review task.';
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS coding_handoff (id TEXT PRIMARY KEY, payload TEXT NOT NULL, sha TEXT NOT NULL, created_at TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS coding_handoff_scope (id TEXT PRIMARY KEY REFERENCES coding_handoff(id), payload TEXT NOT NULL, sha TEXT NOT NULL);
+CREATE TRIGGER IF NOT EXISTS coding_handoff_no_update BEFORE UPDATE ON coding_handoff BEGIN SELECT RAISE(ABORT,'Coding handoff receipts are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS coding_handoff_no_delete BEFORE DELETE ON coding_handoff BEGIN SELECT RAISE(ABORT,'Coding handoff receipts are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS coding_handoff_scope_no_update BEFORE UPDATE ON coding_handoff_scope BEGIN SELECT RAISE(ABORT,'Coding handoff seals are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS coding_handoff_scope_no_delete BEFORE DELETE ON coding_handoff_scope BEGIN SELECT RAISE(ABORT,'Coding handoff seals are immutable'); END;
+`;
+function catalog(store, readOnly) {
+    const path = codingCatalogPath(store.handle);
+    if (path === null)
+        throw Error('This installation has no saved coding catalog.');
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw Error('Not a regular catalog.');
+    }
+    catch {
+        throw Error('The coding catalog is missing or linked. Preserve the session and restore its catalog.');
+    }
+    const db = new (sqliteRuntime().DatabaseSync)(path, { readOnly });
+    try {
+        db.exec('PRAGMA busy_timeout=3000');
+        for (const table of ['coding_session', 'coding_item', 'coding_submission', 'coding_request']) {
+            if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(table))
+                throw Error('The coding catalog is incomplete.');
+        }
+        if (!readOnly)
+            db.exec(SCHEMA);
+        return db;
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+}
+function git(repo, args) {
+    try {
+        return execFileSync('git', ['--no-optional-locks', '--no-replace-objects', '--no-lazy-fetch', '-c', 'core.hooksPath=/dev/null', '-C', repo, ...args], {
+            encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000, maxBuffer: 1_048_576,
+        }).trimEnd();
+    }
+    catch {
+        throw Error('The committed coding result could not be verified in Git. Check the project and try again.');
+    }
+}
+function branchHead(repo, branch) {
+    try {
+        return execFileSync('git', ['--no-optional-locks', '--no-replace-objects', '-C', repo, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    }
+    catch (error) {
+        if (error.status === 1)
+            return null;
+        throw Error('The review branch could not be inspected.');
+    }
+}
+function actorGeneration(store, actor, repo) {
+    const account = store.accountOf(actor);
+    if (!store.schemaCurrent() || !account || !store.isInstanceOperator(actor) || !store.accountCanAccess(actor, repo))
+        throw Error('An installation operator must review this coding result.');
+    if (updateAdmissionPaused(store.handle))
+        throw Error('Toolroll is updating. Create the review task after the update finishes.');
+    return account.generation;
+}
+function sessionFor(db, store, sessionId, actor) {
+    if (!/^[a-f0-9]{32}$/.test(sessionId))
+        throw Error('Choose a saved coding session.');
+    const row = db.prepare('SELECT owner,generation,repo,document FROM coding_session WHERE id=?').get(sessionId);
+    if (!row || row['owner'] !== actor)
+        throw Error('This coding session is not available to your account.');
+    const session = JSON.parse(String(row['document']));
+    const generation = actorGeneration(store, actor, String(row['repo']));
+    if (row['generation'] !== generation || session.id !== sessionId || session.owner !== actor || session.generation !== generation || session.repo !== row['repo'])
+        throw Error('The coding session no longer matches your account or project.');
+    return session;
+}
+function preview(db, store, sessionId, actor) {
+    const session = sessionFor(db, store, sessionId, actor);
+    if (!['ready', 'interrupted', 'failed'].includes(session.status) || session.turnId !== null || session.deliveryReviewRequired ||
+        db.prepare("SELECT 1 FROM coding_submission WHERE session=? AND status IN ('preparing','pending','uncertain')").get(sessionId) ||
+        db.prepare("SELECT 1 FROM coding_request WHERE session=? AND status='pending'").get(sessionId))
+        throw Error('Finish the current coding action and resolve uncertain delivery before creating a review task.');
+    if (!SHA.test(session.base))
+        throw Error('The coding session has no exact starting commit.');
+    learningIdentity(session.repo);
+    if (git(session.worktree, ['symbolic-ref', '--short', 'HEAD']) !== session.branch ||
+        realpathSync(git(session.worktree, ['rev-parse', '--path-format=absolute', '--git-common-dir'])) !== realpathSync(git(session.repo, ['rev-parse', '--path-format=absolute', '--git-common-dir'])))
+        throw Error('The coding checkout no longer matches its saved project and branch.');
+    if (git(session.worktree, ['status', '--porcelain=v1', '-z', '--untracked-files=all']) !== '')
+        throw Error('Commit the coding changes before creating a review task. Uncommitted work stays in the coding session.');
+    const candidate = git(session.worktree, ['rev-parse', '--verify', 'HEAD^{commit}']);
+    if (!SHA.test(candidate))
+        throw Error('The coding result has no exact commit.');
+    git(session.repo, ['merge-base', '--is-ancestor', session.base, candidate]);
+    const changedPaths = git(session.repo, ['diff', '--name-only', '--no-renames', '-z', session.base, candidate]).split('\0').filter(Boolean);
+    if (!changedPaths.length)
+        throw Error('There are no committed changes to review.');
+    if (changedPaths.length > PROOF_LIMITS.changed || changedPaths.some(path => Buffer.byteLength(path) > PROOF_LIMITS.changedPath || /[\x00-\x1f\x7f]/.test(path)))
+        throw Error('The complete coding change exceeds the current evidence limits. Split it into explicitly scoped changes before review.');
+    const first = db.prepare("SELECT payload FROM coding_item WHERE session=? AND json_extract(payload,'$.type')='userMessage' ORDER BY position LIMIT 1").get(sessionId);
+    const originalPrompt = first ? JSON.parse(String(first['payload'])).text : null;
+    if (typeof originalPrompt !== 'string' || !originalPrompt.trim())
+        throw Error('The session’s original request is unavailable. Restore its conversation before creating a review task.');
+    return { sessionId, repo: session.repo, base: session.base, candidate, title: session.title, originalPrompt, changedPaths };
+}
+export function codingHandoffPreview(store, input) {
+    const db = catalog(store, true);
+    try {
+        return preview(db, store, input.sessionId, input.actor);
+    }
+    finally {
+        db.close();
+    }
+}
+function makeReceipt(terms) {
+    const id = learningSha(JSON.stringify(terms)).slice(0, 32), taskId = `coding-review-${id}`;
+    return { ...terms, id, taskId, branch: taskBranch(taskId) };
+}
+function parseReceipt(row) {
+    const payload = String(row['payload']);
+    if (learningSha(payload) !== row['sha'])
+        throw Error('The coding handoff receipt could not be verified.');
+    const receipt = JSON.parse(payload);
+    const { id, taskId, branch, ...terms } = receipt;
+    const expected = makeReceipt(terms);
+    if (receipt.version !== 1 || row['id'] !== id || id !== expected.id || taskId !== expected.taskId || !BRANCH_PREFIXES.some(prefix => branch === `${prefix}${taskId}`) || !SHA.test(receipt.base) || !SHA.test(receipt.candidate))
+        throw Error('The coding handoff receipt identity could not be verified.');
+    return receipt;
+}
+function sealPayload(receipt, scopeDigest) {
+    return JSON.stringify({ version: 1, id: receipt.id, receiptSha256: learningSha(JSON.stringify(receipt)), scopeDigest });
+}
+function verifySeal(db, receipt, digest) {
+    const seal = db.prepare('SELECT payload,sha FROM coding_handoff_scope WHERE id=?').get(receipt.id);
+    if (!seal || seal['payload'] !== sealPayload(receipt, digest) || learningSha(String(seal['payload'])) !== seal['sha'])
+        throw Error('The coding review scope changed or its saved receipt is missing. Create a new review task for the current terms.');
+}
+/** Returns null only for ordinary tasks. A coding marker always requires its receipt. */
+export function readCodingHandoff(store, taskId) {
+    const provenance = store.filedViaOf(taskId);
+    if (!provenance?.startsWith(PREFIX))
+        return null;
+    if (!/^coding:[a-f0-9]{32}$/.test(provenance))
+        throw Error('The coding handoff identity is invalid.');
+    const db = catalog(store, true);
+    try {
+        const row = db.prepare('SELECT * FROM coding_handoff WHERE id=?').get(provenance.slice(PREFIX.length));
+        if (!row)
+            throw Error('The coding handoff receipt is missing. Restore it before review.');
+        const receipt = parseReceipt(row), scope = store.getScope(taskId), ref = store.lookupRef(taskId);
+        if (receipt.taskId !== taskId || ref?.repo !== receipt.repo || receipt.identity !== learningIdentity(receipt.repo) || !scope || scope.termsProblem != null || scope.candidate !== receipt.candidate)
+            throw Error('The coding review no longer matches its saved project, candidate or scope.');
+        verifySeal(db, receipt, scope.digest);
+        return { taskId, scopeDigest: scope.digest, receipt };
+    }
+    finally {
+        db.close();
+    }
+}
+/** No agent dispatch, approval, push, or modification of an existing Git ref. */
+export function createCodingHandoff(store, input) {
+    const invalid = validateTaskText({ title: input.title, goal: input.goal });
+    if (invalid)
+        throw Error(invalid.message);
+    if (!input.goal.trim())
+        throw Error('Describe what this result should achieve.');
+    const parsed = parseAcceptanceCriteria(input.acceptance);
+    if (parsed.problems.length || !parsed.criteria.length)
+        throw Error(parsed.problems.map(problem => problem.message).join(' ') || 'Add at least one acceptance criterion.');
+    const db = catalog(store, false);
+    try {
+        const shown = preview(db, store, input.sessionId, input.actor);
+        if (shown.repo !== input.repo || shown.base !== input.base || shown.candidate !== input.candidate)
+            throw Error('The coding result changed. Review the current committed result before creating its task.');
+        if (parsed.criteria.some(criterion => criterion.evidence.includes('screenshot')))
+            readPreparedEvidence(shown.repo, shown.candidate, true);
+        const receipt = makeReceipt({ ...shown, version: 1, identity: learningIdentity(input.repo), actor: input.actor,
+            generation: actorGeneration(store, input.actor, input.repo), title: input.title.trim(), goal: input.goal.trim(), acceptance: parsed.criteria, outOfScope: EXCLUSIONS });
+        const payload = JSON.stringify(receipt), sha = learningSha(payload);
+        db.exec('BEGIN IMMEDIATE');
+        let reserved = false;
+        try {
+            const prior = db.prepare('SELECT * FROM coding_handoff WHERE id=?').get(receipt.id);
+            if (prior) {
+                if (JSON.stringify(parseReceipt(prior)) !== payload)
+                    throw Error('This coding handoff conflicts with its saved receipt.');
+                reserved = true;
+            }
+            else {
+                if (store.lookupRef(receipt.taskId) || branchHead(input.repo, receipt.branch) !== null)
+                    throw Error('The review task or branch already exists. It has been preserved.');
+                db.prepare('INSERT INTO coding_handoff VALUES(?,?,?,?)').run(receipt.id, payload, sha, new Date().toISOString());
+            }
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+        if (store.lookupRef(receipt.taskId)) {
+            const existing = readCodingHandoff(store, receipt.taskId);
+            if (!reserved || !existing || JSON.stringify(existing.receipt) !== payload)
+                throw Error('This task belongs to another handoff. It has been preserved.');
+            const head = branchHead(input.repo, receipt.branch);
+            if (head === null)
+                throw Error('The saved review branch is missing. Restore it before continuing.');
+            verifyCodingHandoffBase(store, { taskId: receipt.taskId, taskRef: store.lookupRef(receipt.taskId).id, repo: receipt.repo, branch: receipt.branch, head });
+            return existing;
+        }
+        const current = branchHead(input.repo, receipt.branch);
+        const refMessage = `Toolroll coding handoff ${sha}`;
+        if (current === null)
+            git(input.repo, ['update-ref', '--create-reflog', '-m', refMessage, `refs/heads/${receipt.branch}`, input.base, '0'.repeat(40)]);
+        else if (!reserved || current !== input.base || git(input.repo, ['reflog', 'show', '-1', '--format=%gs', `refs/heads/${receipt.branch}`]) !== refMessage)
+            throw Error('The reserved review branch changed. It has been preserved; create a new handoff.');
+        // No checked-out/leased branch is adopted, even if its HEAD happens to match.
+        if (git(input.repo, ['worktree', 'list', '--porcelain']).split('\n').includes(`branch refs/heads/${receipt.branch}`))
+            throw Error('The review branch is already checked out. Its work has been preserved.');
+        return store.transact(() => {
+            if (actorGeneration(store, input.actor, input.repo) !== receipt.generation)
+                throw Error('Your account changed. Sign in again.');
+            if (branchHead(input.repo, receipt.branch) !== receipt.base)
+                throw Error('The review branch moved before filing. Its work has been preserved.');
+            const made = fileTaskProposal(store, { id: receipt.taskId, title: receipt.title, repo: receipt.repo, goal: receipt.goal,
+                outOfScope: receipt.outOfScope, acceptance: receipt.acceptance, filedVia: PREFIX + receipt.id, filedBy: { name: input.actor, kind: "person" }, planning: 'skip', admittedRepos: [receipt.repo] }, new Date());
+            if (!made.ok)
+                throw Error(made.message);
+            const ref = store.lookupRef(made.id);
+            const proposed = proposeGuarded(store, { taskId: made.id, author: input.actor, taskRef: ref.id, sawDigest: store.getScope(made.id).digest,
+                goal: receipt.goal, outOfScope: receipt.outOfScope, acceptance: receipt.acceptance, candidate: receipt.candidate, now: new Date() });
+            if (!proposed.ok)
+                throw Error(proposed.message || 'The prepared review scope could not be saved.');
+            const seal = sealPayload(receipt, proposed.scope.digest);
+            const prior = db.prepare('SELECT 1 FROM coding_handoff_scope WHERE id=?').get(receipt.id);
+            if (prior)
+                verifySeal(db, receipt, proposed.scope.digest);
+            else
+                db.prepare('INSERT INTO coding_handoff_scope VALUES(?,?,?)').run(receipt.id, seal, learningSha(seal));
+            // The durable sidecar seal precedes the main transaction commit. Failure
+            // here rolls back the ordinary task; receipt and branch remain recoverable.
+            return { taskId: made.id, scopeDigest: proposed.scope.digest, receipt };
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+/** Called before setup and immediately before recording the attempt's base. */
+export function verifyCodingHandoffBase(store, input) {
+    const handoff = readCodingHandoff(store, input.taskId);
+    if (!handoff)
+        return;
+    const { receipt } = handoff;
+    if (store.lookupRef(input.taskId)?.id !== input.taskRef || input.repo !== receipt.repo || input.branch !== receipt.branch)
+        throw Error('The coding review is assigned to a different task, project or branch.');
+    const pinned = store.firstBuilderBase(input.taskRef, input.branch);
+    if (!SHA.test(input.head) || (pinned ?? input.head) !== receipt.base)
+        throw Error('The review branch no longer starts at the coding session’s original commit. Its work has been preserved; create a new review task.');
+    if (pinned !== null)
+        git(receipt.repo, ['merge-base', '--is-ancestor', receipt.base, input.head]);
+}