toolroll 0.9.103 → 0.9.105

package/dist/codex-limits.js

@@ -1,13 +1,9 @@
-/** 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")
@@ -16,7 +12,6 @@ function accountBilling(account) {
         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) => {
@@ -26,9 +21,8 @@ function end(child, graceMs) {
                 else
                     child.kill(name);
             }
-            catch { /* gone */ }
+            catch { }
         };
-        // 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();
@@ -39,13 +33,9 @@ function end(child, graceMs) {
         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;
@@ -109,10 +99,6 @@ export function readCodexLimits(options = {}) {
         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 () => { };
@@ -120,7 +106,6 @@ export function startCodexLimits(store, everyMs = 5 * 60_000) {
     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;
@@ -131,7 +116,6 @@ export function startCodexLimits(store, everyMs = 5 * 60_000) {
                 store.recordProviderLimits(reading, new Date());
         }
         catch {
-            // The next pass tries again.
         }
         finally {
             busy = false;

package/dist/coding-context.js

@@ -1,4 +1,3 @@
-/** 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';
@@ -27,20 +26,12 @@ function futureRealPath(path) {
         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 !== '..'))
@@ -73,7 +64,6 @@ export function prepareCodingContext(store, args) {
     };
     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) {
     if (context.metadata.version !== 1 || context.metadata.repo !== repo || context.metadata.baseRevision !== baseRevision || !identityMatches(repo, context.metadata.identity) || context.sha256 !== digest(context.text, context.metadata))
         throw Error('The coding session context could not be verified.');

package/dist/coding-handoff.js

@@ -1,4 +1,3 @@
-/** A committed native session enters the existing review flow, never another executor. */
 import { checkoutGitSync, noLazyFetch, viewedGitSync } from './teardown-git.js';
 import { lstatSync, realpathSync } from 'node:fs';
 import { sqliteRuntime } from './sqlite-runtime.js';
@@ -52,8 +51,6 @@ function catalog(store, readOnly) {
         throw error;
     }
 }
-// The coding checkout is written by an agent (its config, hooks, filters): every read goes through the hardened
-// checkout git, which the code page's GET preview also uses (docs/plans/get-side-effects.md).
 function git(repo, args) {
     try {
         return checkoutGitSync(repo, ['--no-replace-objects', ...noLazyFetch(), ...args]).trimEnd();
@@ -62,8 +59,6 @@ function git(repo, args) {
         throw Error('The committed coding result could not be verified in Git. Check the project and try again.');
     }
 }
-// The project's repository is shared with every build (its config, includes): read through the frozen, bounded view
-// (eval-harness review 2, finding 6), and never inside a database transaction.
 export function branchHead(repo, branch) {
     let ran;
     try {
@@ -141,7 +136,6 @@ function makeReceipt(terms) {
     const id = learningSha(JSON.stringify(terms)).slice(0, 32), taskId = `coding-review-${id}`;
     return { ...terms, id, taskId, branch: taskBranch(taskId) };
 }
-/** 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'])
@@ -164,7 +158,6 @@ function verifySeal(db, receipt, digest) {
     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))
@@ -186,7 +179,6 @@ export function readCodingHandoff(store, taskId) {
         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)
@@ -206,7 +198,6 @@ export function createCodingHandoff(store, input) {
         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);
-        // Git is read before the reservation's transaction, never inside it (review 2, finding 6).
         const before = branchHead(input.repo, receipt.branch);
         db.exec('BEGIN IMMEDIATE');
         let reserved = false;
@@ -244,10 +235,8 @@ export function createCodingHandoff(store, input) {
             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.');
-        // The branch, read last before filing and outside the transaction: a database transaction never holds a git ref still.
         if (branchHead(input.repo, receipt.branch) !== receipt.base)
             throw Error('The review branch moved before filing. Its work has been preserved.');
         return store.transact(() => {
@@ -268,8 +257,6 @@ export function createCodingHandoff(store, input) {
                 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 };
         });
     }
@@ -277,7 +264,6 @@ export function createCodingHandoff(store, input) {
         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)

package/dist/coding-provider.js

@@ -14,7 +14,6 @@ import { observeProcessTree, sampleProcessTree, stopProcessTree } from "./proces
 import { isOwnEnv } from "./names.js";
 import { isProtectedEnvName } from "./protected-storage.js";
 import { sleep } from "./sleep.js";
-/** A response from the server, distinct from an ambiguous transport failure. */
 export class CodingProviderRequestError extends Error {
     code;
     data;
@@ -39,8 +38,6 @@ export class CodingProviderShutdownError extends Error {
         this.name = "CodingProviderShutdownError";
     }
 }
-// A corrupt/noisy child must never grow an unbounded transcript or write queue.
-// Fail the connection explicitly; never truncate a valid protocol message.
 const MAX_FRAME_BYTES = 16 * 1024 * 1024;
 const MAX_PENDING_REQUESTS = 128;
 const EXIT_GRACE_MS = 1_000;
@@ -54,20 +51,11 @@ export function codingEnvironment() {
         "CODEX_SHELL", "CODEX_CI", "CODEX_VERSION", "CODEX_SAGE_BACKFILL_TRACKER_TAB_REUSE",
     ]);
     for (const key of Object.keys(env)) {
-        // Preserve native Codex auth, HOME, PATH, CODEX_HOME and project config.
-        // A parent desktop session's control pipe and identity do not belong to
-        // this independent native client. Keep install/runtime paths such as
-        // CODEX_MCP_NODE_PATH. Service credentials stay with the web service; no chat or vault variable reaches it
-        // (protected-storage.ts).
         if (isOwnEnv(key) || isProtectedEnvName(key) || /^CODEX_APP_TOOLS_/.test(key) || invokingSession.has(key) || key === "NODE_OPTIONS" || key === "NODE_PATH")
             delete env[key];
     }
     return env;
 }
-/** Native app-server JSONL transport. It keeps Codex's normal config, tools and
- * approval rules. There are no request/turn deadlines or automatic retries.
- * Protocol: https://learn.chatgpt.com/docs/app-server (installed CLI schema).
- */
 export function createCodexCodingProvider(options = {}) {
     let child = null;
     let container = null;
@@ -85,7 +73,6 @@ export function createCodexCodingProvider(options = {}) {
     let ancestryUnknown = false;
     const observationFailures = [];
     const host = hostname(), machineId = currentMachineId();
-    // Bind the boot at creation, not when an old snapshot is requested later.
     const bootId = currentBootId();
     let nextId = 0;
     let frameParts = [];
@@ -108,8 +95,6 @@ export function createCodexCodingProvider(options = {}) {
                 listener(event);
             }
             catch {
-                // A failed persistence/event consumer cannot silently drop an approval
-                // or part of the transcript while the agent continues to mutate files.
                 if (event.kind !== "exit")
                     fail("Codex updates could not be recorded. The session was disconnected; inspect its saved result.");
             }
@@ -129,8 +114,6 @@ export function createCodexCodingProvider(options = {}) {
     }
     function fail(message) {
         disconnect(message);
-        // Keep the rejected cleanup promise for close() to expose to the owner.
-        // The local catch only prevents an unhandled rejection in an event handler.
         void close().catch(() => { });
     }
     function write(message) {
@@ -208,8 +191,6 @@ export function createCodexCodingProvider(options = {}) {
                 return;
             }
             if (listeners.size === 0) {
-                // An absent UI/consumer must never imply consent or leave a tool waiting
-                // indefinitely for an approval nobody can see.
                 write({ id: message.id, error: { code: -32601, message: "No client is available to handle this request." } });
                 return;
             }
@@ -296,8 +277,6 @@ export function createCodexCodingProvider(options = {}) {
             throw new CodingProviderRequestError(-32000, "Codex could not start. Check that the Codex CLI is installed and the project directory exists.");
         }
         if (container === null) {
-            // The existing observer has no Windows ancestry backend. A plain root
-            // PID there cannot establish tool-process exit without a native job.
             if (process.platform === "win32")
                 ancestryUnknown = true;
             observeProcessTree(child, {
@@ -315,7 +294,6 @@ export function createCodexCodingProvider(options = {}) {
             if (disconnected === null && !closing)
                 fail(frameBytes ? "Codex disconnected with an incomplete protocol message. The request outcome is unknown." : "Codex closed its connection. Inspect the saved session before continuing.");
         });
-        // Drain diagnostics without retaining or forwarding paths, prompts or credentials.
         child.stderr.resume();
         child.stdin.on("error", () => fail("Codex input disconnected. The last request may have run; inspect the saved session."));
         child.stdout.on("error", () => fail("Codex updates disconnected. Inspect the saved session before continuing."));
@@ -327,10 +305,7 @@ export function createCodexCodingProvider(options = {}) {
             if (!closing)
                 fail("Codex exited. The last request may have run; inspect the saved session before continuing.");
         });
-        // Failed spawn emits close without exit.
         child.once("close", () => { exited = true; resolveExit(); });
-        // Publish the owned handle before initialization can start a native task.
-        // Even a failed initialize must leave its process/container witness behind.
         custodyChanged();
         if (launch !== undefined && child.pid !== undefined) {
             const attached = await launch.attach(child);
@@ -378,8 +353,6 @@ export function createCodexCodingProvider(options = {}) {
                 container.release();
         }
         else {
-            // Root exit cannot prove escaped tool-process exit. Do not signal saved
-            // descendants after ancestry is lost or silently release session custody.
             const absent = () => (owned.pid === undefined || !processMayBeAlive(owned.pid, process.platform !== "win32")) && [...descendants.values()].every(({ pid, group }) => !processMayBeAlive(pid, group));
             const until = Date.now() + EXIT_GRACE_MS;
             while (!ancestryUnknown && !absent() && Date.now() < until)
@@ -394,7 +367,6 @@ export function createCodexCodingProvider(options = {}) {
     function close() {
         if (shutdown === null) {
             closing = true;
-            // Assign before invoking callbacks: an exit listener may also call close.
             shutdown = Promise.resolve().then(stop);
         }
         return shutdown;
@@ -431,14 +403,6 @@ export function createCodexCodingProvider(options = {}) {
         close,
     };
 }
-/**
- * An interactive Codex session's confinement (docs/plans/sandbox-parity.md C3): the permission profile a Codex build
- * gets (agent-fence.ts codexFenceConfig), as the thread's config overrides: Toolroll's state, every other launch's
- * folder and every other checkout in the plane's pools and the coding sessions' own pool denied, the session's own
- * worktree given back; Codex's workspace writes; no network (Codex's command sandbox can't route through a proxy, and
- * sessions have never had one). The worktree is bound to its project by the plane's own records first; anything that
- * doesn't prove refuses the session.
- */
 export function codingSessionPermissions(store, worktreeRoot) {
     return input => sessionPermissions(store, { ...input, worktreeRoot });
 }
@@ -449,16 +413,13 @@ async function sessionPermissions(store, input) {
     try {
         const poolRoots = [join(dirname(databaseFile), "worktrees"), input.worktreeRoot, ...store.listWorktrees().map(record => poolRootOf(record.path, record.repo))];
         const binding = trustedWorktreeBinding(input.repo, input.worktree, poolRoots);
-        // The storage check, awaited off this thread (protected-storage.ts).
         const storage = await prepareProtectedStorage();
         const boundary = taskBoundary({ worktree: input.worktree, provider: "codex", binding, policy: FENCE_POLICY_CURRENT, storage });
-        // The project's read denies, read live (a session seals none; they only narrow).
         const readDeny = store.projectSandbox(input.repo).readDeny.map(one => readDenyPath(one, homedir()));
         const launch = fenceFor("build", { databaseFile, worktree: input.worktree, boundary, binding, runFolders: runFolders(null), poolRoots, readDeny, policy: FENCE_POLICY_CURRENT, storage });
         return { config: codexFenceConfig(launch.fence, false, launch.fenceGrants) };
     }
     catch (error) {
-        // The storage check's own words survive: what didn't finish, and which program macOS may need to allow.
         return { problem: storageRefusalOf(error)?.message ?? "The session's worktree couldn't be bound to its project, so the session was not started." };
     }
 }

package/dist/coding-shipping-ui.js

@@ -1,5 +1,4 @@
 import { html, postForm } from './html.js';
-/** A reviewable handoff. The next screen retains the existing approval terms. */
 export function codingShippingHtml(preview, values, error) {
     const goal = values?.get('goal') ?? preview.title;
     const criteria = values?.get('acceptance') ?? '';

package/dist/coding-ui.js

@@ -94,7 +94,6 @@ export const CODING_CSS = `
 @media(prefers-reduced-motion:reduce){.coding-workspace *{scroll-behavior:auto!important}}
 `;
 export function codingWorkspaceScript() {
-    // Passwordless: the request form the script builds leaves its password field out (the server proves the session).
     const approvePassword = passwordlessRendering() ? "" : '<label>Password to approve this request<input type="password" name="password" autocomplete="current-password" required></label>';
     return String.raw `(() => {
   const root = document.querySelector('.coding-workspace');

package/dist/coding-update.js

@@ -42,7 +42,6 @@ function connect(file, readOnly) {
 }
 function withCatalog(orders, absent, readOnly, action) {
     const file = codingCatalogPath(orders);
-    // A legacy installation has no coding catalog. Never create one in the updater.
     if (file === null || !codingCatalogExists(file))
         return absent;
     const db = connect(file, readOnly);
@@ -59,8 +58,6 @@ function gateStatements(id) {
         throw Error('Invalid coding update identity.');
     const refusal = `SELECT RAISE(ABORT, '${pausedMessage} [${id}]');`;
     return [
-        // Workspace saves are INSERT ... ON CONFLICT UPDATE, so existing-session
-        // events, approvals and Stop must still be allowed to settle during drain.
         `CREATE TRIGGER ${gatePrefix}session BEFORE INSERT ON coding_session WHEN NOT EXISTS (SELECT 1 FROM coding_session WHERE id=NEW.id) BEGIN ${refusal} END`,
         `CREATE TRIGGER ${gatePrefix}submission BEFORE INSERT ON coding_submission BEGIN ${refusal} END`,
     ];
@@ -93,8 +90,6 @@ export function activeCodingUpdateWork(orders) {
         codingDeliveries: Number(db.prepare("SELECT count(*) n FROM coding_submission WHERE status IN ('preparing','pending','uncertain')").get()?.['n']),
     }));
 }
-/** An idle provider may remain loaded during drain. The normal server stop
- * must close it and establish native/tool exit before either app swap. */
 export function assertCodingUpdateStopped(orders) {
     withCatalog(orders, undefined, true, db => {
         const owner = db.prepare('SELECT token,pid,native_pid,clean FROM coding_owner WHERE singleton=1').get();
@@ -102,13 +97,6 @@ export function assertCodingUpdateStopped(orders) {
             throw Error('The coding server has not verified agent and tool shutdown. No app was replaced.');
     });
 }
-/** A runtime killed before its close (deploys over 0.9.11, Oct 2) leaves the
- * owner record naming a dead process, and every later swap refuses. Only an
- * updater that has itself proved each process of the stopped service gone may
- * release it here, and only while nothing the catalog records still lives:
- * the agent, its tools, a session or an unconfirmed message. Returns what it
- * released, or null when the record was already released by an ordinary stop;
- * anything unproven keeps the ordinary refusal. */
 export function releaseStaleCodingOwner(orders, stoppedPids, alive = processMayBeAlive) {
     return withCatalog(orders, null, false, db => {
         db.exec('BEGIN IMMEDIATE');
@@ -120,14 +108,12 @@ export function releaseStaleCodingOwner(orders, stoppedPids, alive = processMayB
                 return null;
             }
             const refuse = (why) => { throw Error(`The coding server has not verified agent and tool shutdown (${why}). No app was replaced.`); };
-            // A record its own server released while recovery was still required stays as it is: that needs a person's check.
             if (owner['token'] === '' || !Number.isSafeInteger(pid) || pid <= 0)
                 refuse('its saved record needs a recovery check');
             if (!stoppedPids.includes(pid))
                 refuse(`process ${pid} is not one this update stopped`);
             if (alive(pid, false))
                 refuse(`process ${pid} is still running`);
-            // The agent runs in its own process group: a service killed by launchd can leave it behind.
             if (nativePid !== null && alive(nativePid, true))
                 refuse(`the agent process ${nativePid} is still running`);
             const custody = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='coding_custody'").get()
@@ -164,22 +150,19 @@ export function releaseStaleCodingOwner(orders, stoppedPids, alive = processMayB
             try {
                 db.exec('ROLLBACK');
             }
-            catch { /* already ended */ }
+            catch { }
             throw error;
         }
     });
 }
 function snapshot(db) {
     const data = {};
-    // Include every catalog table, including current/future custody records.
     for (const row of db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all()) {
         const name = String(row['name']);
         data[name] = db.prepare(`SELECT * FROM "${name.replaceAll('"', '""')}" ORDER BY rowid`).all();
     }
     return createHash('sha256').update(JSON.stringify(data)).digest('hex');
 }
-/** Back up through SQLite so committed WAL records are included. This is a
- * retained recovery artifact; updates never restore the live catalog. */
 export async function backupCodingCatalog(sourceFile, target, updateId) {
     const reservation = connect(sourceFile, false);
     try {

package/dist/coding-workspace.js

@@ -38,7 +38,6 @@ function actionError(error, fallback, sessionId) {
     const outcome = object(error)['outcomeUnknown'];
     return new CodingActionError(error instanceof Error ? error.message : 'The coding action could not finish.', outcome === true ? 'unknown' : outcome === false ? 'rejected' : fallback, sessionId);
 }
-/** A native session catalog, separate from the unattended task/proof ledger. */
 export class CodingWorkspace {
     options;
     db;
@@ -106,7 +105,6 @@ export class CodingWorkspace {
             throw Error('Coding session unavailable.');
         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']));
@@ -139,8 +137,6 @@ export class CodingWorkspace {
     list(actor) {
         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. */
     listBounded(actor, options) {
         const rows = options.repo === undefined
             ? this.db.prepare('SELECT id,repo FROM coding_session WHERE owner=? AND generation=? ORDER BY rowid DESC LIMIT 101').all(actor.name, actor.generation)
@@ -170,8 +166,6 @@ export class CodingWorkspace {
         const revision = Number(this.db.prepare('SELECT revision FROM coding_session WHERE id=?').get(id)?.['revision']);
         return { session, items, requests, revision };
     }
-    /** Bounded transport read: query only the recent window plus one row
-     * for omission detection. The browser's full snapshot remains unchanged. */
     snapshotBounded(id, actor) {
         const session = this.get(id, actor);
         const itemRows = this.db.prepare('SELECT payload FROM coding_item WHERE session=? ORDER BY position DESC LIMIT 101').all(id);
@@ -190,8 +184,6 @@ export class CodingWorkspace {
         if (expected && (expected.revision !== this.revision(id, actor) || expected.nativeThreadId !== session.nativeThreadId || expected.turnId !== session.turnId))
             throw new CodingStateConflictError(id);
     }
-    /** Persist acceptance before calling the native owner. Repeating a key only
-     * reads its receipt; it never repeats a mutation, including after restart. */
     async command(actor, key, request, check, perform) {
         if (!keyPattern.test(key))
             throw Error('This operation needs a valid request ID.');
@@ -242,8 +234,6 @@ export class CodingWorkspace {
         return usable ? session : null;
     }
     putItem(session, item) {
-        // Re-reading unchanged native history must not invalidate the request
-        // that loaded it. New or changed history still requires a fresh look.
         const saved = this.db.prepare('INSERT INTO coding_item(session,id,payload) VALUES(?,?,?) ON CONFLICT(session,id) DO UPDATE SET payload=excluded.payload WHERE coding_item.payload <> excluded.payload').run(session, item.id, JSON.stringify(item));
         if (saved.changes)
             this.db.prepare('UPDATE coding_session SET revision=revision+1 WHERE id=?').run(session);
@@ -273,13 +263,11 @@ export class CodingWorkspace {
             text = (Array.isArray(item['changes']) ? item['changes'] : []).map(change => string(object(change)['path'])).join('\n');
         if (!text)
             text = string(item['summary']) || type.replace(/([a-z])([A-Z])/g, '$1 $2');
-        // Detailed command output stays in native history. The workspace is a bounded projection.
         if (text.length > 100_000)
             text = text.slice(0, 100_000) + '\n[More output is available in the native session.]';
         const clientId = string(item['clientId']) || string(item['clientUserMessageId']);
         return { id, type, text, status: string(item['status']) || null, ...(type === 'userMessage' && clientId ? { clientId } : {}) };
     }
-    /** The thread's confinement, made right before each start or resume from the plane's own records. */
     async permissionsFor(repo, worktree) {
         const made = await this.options.permissions({ repo, worktree });
         if ('problem' in made)
@@ -401,8 +389,6 @@ export class CodingWorkspace {
         }
     }
     async git(repo, args, project = repo) {
-        // The project's repository and the session's checkout are agent-written: the hardened git, against a frozen view of
-        // the repository's config and info (teardown-git.ts checkoutGit).
         const result = await checkoutGit(run, 'build', { repo: project })('git', ['--no-optional-locks', ...args], { cwd: repo, timeoutMs: 60_000, maxBuffer: 1_048_576 });
         if (result.code !== 0)
             throw Error('Git could not complete this workspace operation. Check the repository and try again.');
@@ -550,8 +536,6 @@ export class CodingWorkspace {
             return false;
         }
     }
-    /** Reconnect the exact native conversation. An absent receipt never proves
-     * non-delivery, so an unmatched message requires an explicit review action. */
     async recover(id, actor, expected) {
         this.admit();
         this.assertExpected(id, actor, expected);
@@ -666,8 +650,6 @@ export class CodingWorkspace {
             const message = uncertain && !accepted ? 'The connection closed before delivery was confirmed. Your message may have reached the agent; it will not be sent again automatically.' : failure.message;
             this.db.prepare("UPDATE coding_submission SET status=?,error=? WHERE session=? AND key=? AND status!='accepted'").run(uncertain ? 'uncertain' : 'failed', message, id, requestId);
             const current = this.read(id);
-            // A refused draft does not fail the saved turn. Unknown reconnects still
-            // require reconciliation even when this message never reached transport.
             this.save({ ...current, status: accepted || (!transmissionAttempted && !uncertain) ? current.status : uncertain ? 'uncertain' : current.turnId ? current.status : 'failed', error: message });
             throw new CodingActionError(message, failure.delivery, id);
         }
@@ -732,10 +714,6 @@ export class CodingWorkspace {
     }
     async changes(id, actor) {
         const session = this.get(id, actor);
-        // The code page reads this on a GET (docs/plans/get-side-effects.md), from a checkout the agent writes: every git
-        // here is the hardened checkout git, which refuses a config that could run a command and reads no global config.
-        // Read mode: the read flags, and the checkout's config and info/attributes as read once (teardown-git.ts readView),
-        // hold even if the agent changes them after checkoutGit read them: no hook, pager, filter or network.
         const safe = checkoutGit(run, 'read');
         const read = async (args) => {
             const result = await safe('git', args, { cwd: session.worktree, timeoutMs: 60_000, maxBuffer: 1_048_576 });
@@ -749,8 +727,6 @@ export class CodingWorkspace {
             read(['ls-files', '--others', '--exclude-standard', '-z']),
         ]);
         let diff = tracked.stdout, truncated = tracked.code !== 0;
-        // git's no-index diff describes symlinks themselves; it does not follow a
-        // new link out of the checkout to display its target's contents.
         const paths = untracked.split('\0').filter(Boolean);
         for (let index = 0; index < paths.length; index++) {
             if (index >= 100 || Buffer.byteLength(diff) >= 1_048_576) {
@@ -797,13 +773,10 @@ export class CodingWorkspace {
             await new Promise(resolve => this.operationWaiters.add(resolve));
         if (this.commands.size)
             await new Promise(resolve => this.commandWaiters.add(resolve));
-        // Saving the last delta must never be a prerequisite for stopping the
-        // owned agent. A failed save still fences installation and clean release.
         if (persistenceError || this.persistenceFailed)
             throw Error('Coding activity could not be saved. Agent cleanup was attempted; preserve the catalog and repair storage before restarting.', { cause: persistenceError });
         if (shutdownError)
             throw shutdownError;
-        // Closing this new server cannot establish the exit of a previous runtime.
         if (this.recoveryRequired) {
             this.db.prepare("UPDATE coding_owner SET token='',pid=0 WHERE token=?").run(this.owner);
             this.closed = true;