toolroll 0.9.36 → 0.9.37

package/dist/coding-context.d.ts

@@ -1,43 +1,6 @@
 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;
-};
+import { type CodingContext } from './contracts/coding-context.js';
+export type { CodingContext, CodingContextMetadata } from './contracts/coding-context.js';
 /**
  * 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

package/dist/coding-context.js

@@ -5,6 +5,7 @@ import { basename, dirname, join, resolve, relative, isAbsolute, sep } from 'nod
 import { KNOWLEDGE_GUIDANCE, selectProjectKnowledge } from './project-knowledge.js';
 import { materializeProjectSkills, PROJECT_SKILLS_GUIDANCE, selectProjectSkills } from './project-skills.js';
 import { identityMatches, learningIdentity, learningSha } from './project-learning.js';
+import { CODING_CONTEXT_VERSION } from './contracts/coding-context.js';
 function freeze(value) {
     if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
         for (const child of Object.values(value))
@@ -70,7 +71,7 @@ export function prepareCodingContext(store, args) {
         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) });
+    return freeze({ version: CODING_CONTEXT_VERSION, 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) {

package/dist/coding-handoff.d.ts

@@ -1,28 +1,7 @@
-import { type AcceptanceCriterion } from './scope.js';
+import { type CodingHandoffReceipt } from './contracts/coding-handoff.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 { CodingHandoffReceipt } from './contracts/coding-handoff.js';
+export type CodingHandoffPreview = Pick<CodingHandoffReceipt, 'sessionId' | 'repo' | 'base' | 'candidate' | 'title' | 'originalPrompt' | 'changedPaths'>;
 export type CodingHandoffInput = {
     sessionId: string;
     repo: string;
@@ -42,6 +21,9 @@ export declare function codingHandoffPreview(store: Store, input: {
     sessionId: string;
     actor: string;
 }): CodingHandoffPreview;
+/** The saved bytes are verified before they are parsed; identity and branch are checked on the parsed terms. */
+export declare function parseReceipt(row: Record<string, unknown>): CodingHandoffReceipt;
+export declare function sealPayload(receipt: CodingHandoffReceipt, scopeDigest: string): string;
 /** 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. */
@@ -54,4 +36,3 @@ export declare function verifyCodingHandoffBase(store: Store, input: {
     branch: string;
     head: string;
 }): void;
-export {};

package/dist/coding-handoff.js

@@ -10,6 +10,8 @@ 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 { parseCodingHandoffReceipt } from './contracts/coding-handoff.js';
+import { parseCodingSessionDocument } from './contracts/coding-workspace.js';
 import { BRANCH_PREFIXES, taskBranch } from './names.js';
 const PREFIX = 'coding:';
 const SHA = /^[a-f0-9]{40}$/;
@@ -84,7 +86,7 @@ function sessionFor(db, store, sessionId, actor) {
     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 session = parseCodingSessionDocument(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.');
@@ -132,18 +134,22 @@ 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) {
+/** The saved bytes are verified before they are parsed; identity and branch are checked on the parsed terms. */
+export 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 read = parseCodingHandoffReceipt(payload);
+    if (!read.ok)
+        throw Error(`The coding handoff receipt could not be read: ${read.issues.map(issue => issue.line).join('; ')}`);
+    const receipt = read.value;
     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))
+    if (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) {
+export function sealPayload(receipt, scopeDigest) {
     return JSON.stringify({ version: 1, id: receipt.id, receiptSha256: learningSha(JSON.stringify(receipt)), scopeDigest });
 }
 function verifySeal(db, receipt, digest) {

package/dist/coding-types.d.ts

@@ -1,29 +1,5 @@
-import type { CodingContext } from './coding-context.js';
-export type CodingStatus = 'starting' | 'ready' | 'working' | 'needs-input' | 'stopping' | 'interrupted' | 'failed' | 'uncertain' | 'closed';
-export type CodingSession = {
-    id: string;
-    owner: string;
-    generation: number;
-    repo: string;
-    title: string;
-    provider: 'codex';
-    model: string | null;
-    branch: string;
-    base: string;
-    worktree: string;
-    nativeThreadId: string | null;
-    turnId: string | null;
-    status: CodingStatus;
-    error: string | null;
-    createdAt: string;
-    updatedAt: string;
-    deliveryReviewRequired?: boolean;
-    initialRequest?: {
-        requestId: string;
-        prompt: string;
-    };
-    context?: CodingContext;
-};
+export type { CodingSession, CodingStatus } from './contracts/coding-workspace.js';
+import type { CodingSession } from './contracts/coding-workspace.js';
 export type CodingItem = {
     id: string;
     type: string;

package/dist/coding-workspace.d.ts

@@ -60,6 +60,8 @@ export declare class CodingWorkspace {
     constructor(options: Options);
     private authorize;
     private read;
+    /** Preserve legacy reads, but never mutate an unidentified row or save an unreadable record's error projection. */
+    private catalogRow;
     private admit;
     private releaseOperation;
     list(actor: CodingActor): CodingSession[];

package/dist/coding-workspace.js

@@ -9,6 +9,7 @@ import { run } from './exec.js';
 import { processMayBeAlive } from './process-liveness.js';
 import { createCodexCodingProvider } from './coding-provider.js';
 import { verifyCodingContext } from './coding-context.js';
+import { codingSessionDocument, parseCodingSessionDocument } from './contracts/coding-workspace.js';
 export class CodingActionError extends Error {
     delivery;
     sessionId;
@@ -77,8 +78,10 @@ export class CodingWorkspace {
             const clean = !prior || prior['clean'] === 1;
             this.recoveryRequired = !clean;
             this.db.prepare('INSERT OR REPLACE INTO coding_owner VALUES(1,?,?,?,?)').run(this.owner, process.pid, prior?.['native_pid'] ?? null, clean ? 1 : 0);
-            for (const row of this.db.prepare('SELECT document FROM coding_session').all()) {
-                const session = JSON.parse(String(row['document']));
+            for (const row of this.db.prepare('SELECT * FROM coding_session').all()) {
+                const { session, usable } = this.catalogRow(row);
+                if (!usable)
+                    continue;
                 if (session.status !== 'closed' && (!clean || busy.has(session.status)))
                     this.save({ ...session, status: clean ? 'interrupted' : 'uncertain', turnId: null, error: clean ? null : 'The previous server stopped without a verified process exit. Work is preserved; session recovery needs a process check before resuming.' });
             }
@@ -99,7 +102,23 @@ export class CodingWorkspace {
         const row = this.db.prepare('SELECT document FROM coding_session WHERE id=?').get(id);
         if (!row)
             throw Error('Coding session unavailable.');
-        return JSON.parse(String(row['document']));
+        return parseCodingSessionDocument(String(row['document']));
+    }
+    /** Preserve legacy reads, but never mutate an unidentified row or save an unreadable record's error projection. */
+    catalogRow(row) {
+        try {
+            const session = parseCodingSessionDocument(String(row['document']));
+            const usable = session.id === row['id'] && session.owner === row['owner'] && session.generation === row['generation'] && session.repo === row['repo'];
+            return { session, usable };
+        }
+        catch (error) {
+            return { usable: false, session: {
+                    id: String(row['id']), owner: String(row['owner']), generation: Number(row['generation']), repo: String(row['repo']),
+                    title: 'Unreadable coding session', provider: 'codex', model: null, branch: '', base: '', worktree: '',
+                    nativeThreadId: null, turnId: null, status: 'failed', createdAt: '', updatedAt: '',
+                    error: error instanceof Error ? error.message : 'The saved coding session could not be read.',
+                } };
+        }
     }
     admit() {
         if (this.closed || this.closing || this.persistenceFailed)
@@ -116,7 +135,7 @@ export class CodingWorkspace {
         }
     }
     list(actor) {
-        return this.db.prepare('SELECT document FROM coding_session WHERE owner=? AND generation=? ORDER BY rowid DESC').all(actor.name, actor.generation).map(row => JSON.parse(String(row['document'])));
+        return this.db.prepare('SELECT * FROM coding_session WHERE owner=? AND generation=? ORDER BY rowid DESC').all(actor.name, actor.generation).map(row => this.catalogRow(row).session);
     }
     /** Inspect a fixed metadata window before loading admitted documents.
      * A filtered window can be short without proving the entire list empty. */
@@ -127,13 +146,18 @@ export class CodingWorkspace {
         const window = rows.slice(0, 100);
         const admitted = window.filter(row => options.authorized(String(row['repo'])));
         const selected = admitted.slice(0, Math.min(100, Math.max(1, options.limit)));
-        return { sessions: selected.map(row => this.get(String(row['id']), actor)), truncated: rows.length > window.length || admitted.length > selected.length };
+        const sessions = selected.map(row => {
+            const session = this.catalogRow(this.db.prepare('SELECT * FROM coding_session WHERE id=? AND owner=? AND generation=?').get(String(row['id']), actor.name, actor.generation)).session;
+            this.authorize(actor, session.repo);
+            return session;
+        });
+        return { sessions, truncated: rows.length > window.length || admitted.length > selected.length };
     }
     get(id, actor) {
         const row = this.db.prepare('SELECT document FROM coding_session WHERE id=? AND owner=? AND generation=?').get(id, actor.name, actor.generation);
         if (!row)
             throw Error('This coding session is not available to your account.');
-        const session = JSON.parse(String(row['document']));
+        const session = parseCodingSessionDocument(String(row['document']));
         this.authorize(actor, session.repo);
         return session;
     }
@@ -204,13 +228,16 @@ export class CodingWorkspace {
     }
     save(session) {
         session.updatedAt = now();
-        this.db.prepare('INSERT INTO coding_session(id,owner,generation,repo,document) VALUES(?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET document=excluded.document,revision=revision+1').run(session.id, session.owner, session.generation, session.repo, JSON.stringify(session));
+        this.db.prepare('INSERT INTO coding_session(id,owner,generation,repo,document) VALUES(?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET document=excluded.document,revision=revision+1').run(session.id, session.owner, session.generation, session.repo, codingSessionDocument(session));
     }
     byThread(thread) {
         if (typeof thread !== 'string')
             return null;
-        const row = this.db.prepare("SELECT document FROM coding_session WHERE json_extract(document,'$.nativeThreadId')=?").get(thread);
-        return row ? JSON.parse(String(row['document'])) : null;
+        const row = this.db.prepare("SELECT * FROM coding_session WHERE json_extract(document,'$.nativeThreadId')=?").get(thread);
+        if (!row)
+            return null;
+        const { session, usable } = this.catalogRow(row);
+        return usable ? session : null;
     }
     putItem(session, item) {
         // Re-reading unchanged native history must not invalidate the request
@@ -285,8 +312,10 @@ export class CodingWorkspace {
         if (event.kind === 'exit') {
             this.flush();
             this.loaded.clear();
-            for (const row of this.db.prepare('SELECT document FROM coding_session').all()) {
-                const session = JSON.parse(String(row['document']));
+            for (const row of this.db.prepare('SELECT * FROM coding_session').all()) {
+                const { session, usable } = this.catalogRow(row);
+                if (!usable)
+                    continue;
                 if (busy.has(session.status))
                     this.save({ ...session, status: 'uncertain', error: 'The agent connection closed. Work is preserved; delivery and process exit need to be checked before continuing.' });
             }
@@ -522,7 +551,12 @@ export class CodingWorkspace {
         this.operations.add(id);
         try {
             if (this.provider) {
-                const active = this.db.prepare('SELECT document FROM coding_session').all().some(row => busy.has(JSON.parse(String(row['document'])).status));
+                const active = this.db.prepare('SELECT * FROM coding_session').all().some(row => {
+                    const { session, usable } = this.catalogRow(row);
+                    if (!usable)
+                        throw new CodingActionError('A saved coding session could not be checked. Repair its record before reconnecting the agent.', 'rejected', id);
+                    return busy.has(session.status);
+                });
                 if (active)
                     throw new CodingActionError('Another coding turn is still active. Wait for it to finish or stop it before reconnecting the agent.', 'rejected', id);
                 await this.provider.close();
@@ -754,8 +788,10 @@ export class CodingWorkspace {
             this.db.close();
             return;
         }
-        for (const row of this.db.prepare('SELECT document FROM coding_session').all()) {
-            const session = JSON.parse(String(row['document']));
+        for (const row of this.db.prepare('SELECT * FROM coding_session').all()) {
+            const { session, usable } = this.catalogRow(row);
+            if (!usable)
+                continue;
             const uncertain = this.db.prepare("SELECT 1 FROM coding_submission WHERE session=? AND status IN ('preparing','pending','uncertain')").get(session.id);
             if (!uncertain && (busy.has(session.status) || session.status === 'uncertain'))
                 this.save({ ...session, status: 'interrupted', turnId: null, error: null });

package/dist/contracts/acceptance-terms.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The acceptance rubric's vocabulary and limits: the evidence kinds a criterion may require, and how many criteria
+ * and bytes a rubric may hold. A leaf with no imports but TEXT_LIMITS, because the plan contract (src/contracts/plan.ts)
+ * reads these through scope.ts while scope.ts reads the plan contract's criterion: kept here, both load in either order.
+ */
+export declare const EVIDENCE_KINDS: readonly ["check", "screenshot", "changed-path", "manual-review"];
+export type EvidenceKind = (typeof EVIDENCE_KINDS)[number];
+export declare const ACCEPTANCE_LIMITS: {
+    readonly criteria: 12;
+    readonly id: 40;
+    readonly statement: 1000;
+    readonly how: 500;
+    readonly evidenceKinds: 4;
+};

package/dist/contracts/acceptance-terms.js

@@ -0,0 +1,16 @@
+/**
+ * The acceptance rubric's vocabulary and limits: the evidence kinds a criterion may require, and how many criteria
+ * and bytes a rubric may hold. A leaf with no imports but TEXT_LIMITS, because the plan contract (src/contracts/plan.ts)
+ * reads these through scope.ts while scope.ts reads the plan contract's criterion: kept here, both load in either order.
+ */
+import { TEXT_LIMITS } from "../text-limits.js";
+export const EVIDENCE_KINDS = ["check", "screenshot", "changed-path", "manual-review"];
+export const ACCEPTANCE_LIMITS = {
+    criteria: 12,
+    id: TEXT_LIMITS.acceptanceIdBytes,
+    // A statement is one testable outcome; three hundred bytes forced people to
+    // drop the qualifying clause that made it testable.
+    statement: TEXT_LIMITS.acceptanceStatementBytes,
+    how: TEXT_LIMITS.acceptanceHowBytes,
+    evidenceKinds: EVIDENCE_KINDS.length,
+};