toolroll 0.9.104 → 0.9.105

package/dist/mcp-oauth.js

@@ -7,22 +7,13 @@ import { PKCE_CHALLENGE, readOAuthRegistration, readOAuthTokenRequest } from "./
 import { html, htmlString, joinHtml, postForm, scriptElement, styleElement } from "./html.js";
 import { KEY_FILL_SCRIPT } from "./server/mutation-key.js";
 import { withFormToken } from "./server/request-context.js";
-/** How long each piece lives. A code is spent at once; a grant ends after 30 days and the person consents again. */
 export const OAUTH_TIMES = { requestMs: 10 * 60_000, codeMs: 60_000, accessSeconds: 3600, grantDays: 30 };
-/** The most sign-ins waiting at once, and registered clients kept. */
 export const OAUTH_LIMITS = { requests: 200, requestsPerSource: 20, clients: 500, clientsPerSource: 20 };
-/** The most a registration or form body may be. */
 const MAX_BODY = 16 * 1024;
 export const OAUTH_SCOPES = ["read", "act"];
 const REFRESH_SHAPE = /^sor_([a-f0-9]{12})_([A-Za-z0-9_-]{43})$/;
 export const RESOURCE_PATH = "/mcp";
 export const resourceMetadataUrl = (origin) => `${origin}/.well-known/oauth-protected-resource${RESOURCE_PATH}`;
-// ---- what a bearer may do -------------------------------------------------------------------------------------------
-/**
- * Whether an API token may sign in to this request's path now. An ordinary token: yes (its own checks are elsewhere).
- * An MCP sign-in's token: only at /mcp, only while its access secret is fresh and the account is at the generation
- * that consented.
- */
 export function oauthTokenAllowed(store, tokenId, path, now) {
     const grant = store.oauthGrant(tokenId);
     if (grant === null)
@@ -32,15 +23,10 @@ export function oauthTokenAllowed(store, tokenId, path, now) {
     const account = store.accountOf(grant.account);
     return account !== null && account.revokedAt === null && account.generation === grant.generation;
 }
-/** The projects an MCP sign-in's token was granted (the person's live access still applies), or null for an ordinary token. */
 export const oauthProjects = (store, tokenId) => store.oauthGrant(tokenId)?.projects ?? null;
 const sha256 = (text) => createHash("sha256").update(text, "utf8").digest("hex");
 const same = (a, b) => { const x = Buffer.from(a), y = Buffer.from(b); return x.length === y.length && timingSafeEqual(x, y); };
 const clean = (text) => text.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2066-\u2069]+/g, " ").replace(/\s+/g, " ").trim();
-/**
- * A redirect a client may register: https anywhere, or http on 127.0.0.1 / [::1] (RFC 8252 §7.3), with no
- * credentials or fragment.
- */
 export function redirectAllowed(value) {
     let url;
     try {
@@ -53,7 +39,6 @@ export function redirectAllowed(value) {
         return false;
     return url.protocol === "https:" || url.protocol === "http:" && (url.hostname === "127.0.0.1" || url.hostname === "[::1]");
 }
-/** A redirect matches a registered one exactly; on a loopback http address any port does (RFC 8252 §7.3). */
 export function redirectMatches(presented, registered) {
     if (registered.includes(presented))
         return presented;
@@ -81,26 +66,18 @@ export function createOAuthHttp(options) {
         response.end(JSON.stringify(body));
     };
     const oauthError = (response, status, error, description) => json(response, status, { error, error_description: description });
-    /** A page of this sign-in: script-free (but for the key fill, on a consent while the browser key is required), never
-     * framed, posting only to this console. */
     const page = (response, status, document, fill = false) => {
         const nonce = fill && options.keyFill?.() === true ? randomBytes(16).toString("base64") : null;
         response.writeHead(status, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "referrer-policy": "no-referrer", "x-content-type-options": "nosniff", "x-frame-options": "DENY",
             "content-security-policy": `default-src 'none'; style-src 'unsafe-inline';${nonce === null ? "" : ` script-src 'nonce-${nonce}';`} form-action 'self'; frame-ancestors 'none'; base-uri 'none'` });
         response.end(nonce === null ? htmlString(document) : htmlString(document).replace(/<\/body><\/html>$/, `${htmlString(scriptElement(KEY_FILL_SCRIPT, { nonce }))}</body></html>`));
     };
-    /**
-     * On to an address by a page that moves on by itself, never a redirect: a redirect answering a form is held to
-     * the consent page's form-action 'self', so the browser would stop it on the way to the client. Also how a
-     * sign-in that arrived from another app reaches this console's own pages with the session cookie (SameSite=Strict).
-     */
     const moveOn = (response, to, words) => {
         response.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "referrer-policy": "no-referrer", "x-content-type-options": "nosniff", "x-frame-options": "DENY",
             "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'" });
         response.end(htmlString(html `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="refresh" content="0;url=${to}"><title>Toolroll</title>${STYLE}<main><p>${words} <a href="${to}">Continue</a></p></main></html>`));
     };
     const problemPage = (response, status, title, said) => page(response, status, shell(title, html `<h1>${title}</h1><p>${said}</p>`));
-    /** Back to the client with an answer: the code, or an error, and its state; `iss` names this console (RFC 9207). */
     const backToClient = (response, origin, redirectUri, state, answer, words) => {
         const to = new URL(redirectUri);
         for (const [key, value] of Object.entries(answer))
@@ -135,7 +112,6 @@ export function createOAuthHttp(options) {
             if (one.expires <= now)
                 waiting.delete(id);
     };
-    // ---- discovery ----
     const resourceMetadata = (origin) => ({
         resource: `${origin}${RESOURCE_PATH}`, authorization_servers: [origin], scopes_supported: [...OAUTH_SCOPES], bearer_methods_supported: ["header"], resource_name: "Toolroll",
     });
@@ -152,7 +128,6 @@ export function createOAuthHttp(options) {
         code_challenge_methods_supported: ["S256"],
         authorization_response_iss_parameter_supported: true,
     });
-    // ---- registration ----
     async function register(request, response) {
         if (request.method !== "POST")
             return oauthError(response, 405, "invalid_request", "Register with a POST.");
@@ -191,7 +166,6 @@ export function createOAuthHttp(options) {
             grant_types: ["authorization_code", "refresh_token"], response_types: ["code"], token_endpoint_auth_method: "none",
         });
     }
-    // ---- the sign-in and consent ----
     function authorizeStart(request, response, url, origin) {
         const now = options.clock().getTime();
         prune(now);
@@ -203,7 +177,6 @@ export function createOAuthHttp(options) {
         }
         const client = store.oauthClient(params.get("client_id") ?? "");
         const redirectUri = client === null ? null : redirectMatches(params.get("redirect_uri") ?? "", client.redirectUris);
-        // Registration is anonymous. Even a registered redirect is untrusted until the person decides.
         if (client === null || redirectUri === null)
             return problemPage(response, 400, "This sign-in link isn't valid", "Your MCP client isn't registered here, or asked to return somewhere it didn't register. Start again from the client.");
         const state = params.get("state");
@@ -243,7 +216,6 @@ export function createOAuthHttp(options) {
         const step = session.sso?.fresh === true
             ? html `<p class="meta">Confirmed with ${session.sso.label}.</p><input type="hidden" name="password" value="">`
             : html `<label class="field">Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label>${session.sso === null ? "" : html `<p class="meta"><a href="/login/sso?reauth=1&amp;return=${encodeURIComponent(`/oauth/authorize?request=${id}`)}">Confirm with ${session.sso.label}</a> instead.</p>`}`;
-        // The consent form carries the console session's own CSRF token (checked against session.csrf on the post).
         const consentForm = (body) => withFormToken(session.csrf, () => postForm("/oauth/authorize", body, { hidden: { request: id } }));
         const body = joinHtml([
             html `<h1>${title}</h1>`,
@@ -291,10 +263,8 @@ export function createOAuthHttp(options) {
             return problemPage(response, 400, "This form isn't valid", "Start again from your MCP client.");
         const text = await readBody(request);
         const form = new URLSearchParams(text ?? "");
-        // The person's own act: their session's CSRF value, posted from this console's own page.
         if (text === null || !options.sameSite(request) || !same(form.get("csrf") ?? "", session.csrf))
             return problemPage(response, 403, "This form expired", "Nothing was allowed. Start again from your MCP client.");
-        // Easy-start C2: on a protected loopback install, the key only this console's own page holds.
         if (options.keyed !== undefined && !options.keyed(request, form))
             return problemPage(response, 403, "Reconnect to Toolroll", "This tab isn't connected to Toolroll, so nothing was allowed. Open Toolroll, reconnect, then start again from your MCP client.");
         const id = form.get("request") ?? "";
@@ -324,14 +294,12 @@ export function createOAuthHttp(options) {
         const mine = options.projectsFor(session.name);
         if (chosen.length === 0)
             return again(400, "Choose at least one project.");
-        // Never named back: a project outside the person's access is refused without saying whether it exists.
         if (!chosen.every(path => mine.includes(path)))
             return again(403, "Choose from your own projects.");
         if (!adapterPolicy({ caller: "cookie", capability: account.role === "approver" ? "act" : "read", viewer: account.role === "viewer" }, "step-up", source => source === "none" && chosen.every(path => mine.includes(path))).ok)
             return again(403, "Choose from your own projects.");
         if (!options.confirm(request, session, form.get("password") ?? ""))
             return again(403, "Enter your Toolroll password to allow access.");
-        // Re-proved after the step-up: the code carries the generation the person consented under, never a newer one.
         const current = store.accountOf(session.name);
         if (current === null || current.revokedAt !== null || current.generation !== session.generation)
             return problemPage(response, 403, "Sign in first", "Your access changed. Sign in again; nothing was allowed.");
@@ -341,7 +309,6 @@ export function createOAuthHttp(options) {
             challenge: one.challenge, expiresAt: new Date(now.getTime() + OAUTH_TIMES.codeMs).toISOString() });
         return backToClient(response, origin, one.redirectUri, one.state, { code }, "Allowed. Returning to your MCP client…");
     }
-    // ---- tokens ----
     async function token(request, response, origin) {
         if (request.method !== "POST")
             return oauthError(response, 405, "invalid_request", "Use POST.");
@@ -373,14 +340,12 @@ export function createOAuthHttp(options) {
         if (client === null)
             return oauthError(response, 401, "invalid_client", "This client isn't registered here.");
         const invalid = () => oauthError(response, 400, "invalid_grant", "This sign-in is no longer valid. Sign in again from your MCP client.");
-        /** The projects still in the person's reach, of those granted; a grant that reaches none is over. */
         const reachable = (account, projects) => { const mine = options.projectsFor(account); return projects.filter(path => mine.includes(path)); };
         if (ask.grant_type === "authorization_code") {
             const codeHash = sha256(ask.code);
             const taken = store.takeOAuthCode(codeHash, now);
             if (taken === null)
                 return invalid();
-            // A code spent twice: whatever it made ends too (RFC 6749 §4.1.2).
             if ("used" in taken) {
                 if (taken.used !== null)
                     store.revokeApiToken(taken.used, "toolroll", now, "its sign-in code was used twice");
@@ -415,7 +380,6 @@ export function createOAuthHttp(options) {
             return rotated.reason === "invalid_scope" ? oauthError(response, 400, "invalid_scope", "A refresh can't widen access.") : invalid();
         return json(response, 200, { access_token: `so_${id}_${accessSecret}`, token_type: "Bearer", expires_in: OAUTH_TIMES.accessSeconds, refresh_token: `sor_${id}_${refresh}`, scope: rotated.access });
     }
-    /** Handles the sign-in's addresses; false for any other path. */
     return async (request, response, url) => {
         const path = url.pathname;
         const discovery = path === "/.well-known/oauth-protected-resource" || path === `/.well-known/oauth-protected-resource${RESOURCE_PATH}` || path === "/.well-known/oauth-authorization-server";
@@ -459,7 +423,6 @@ export function createOAuthHttp(options) {
         return true;
     };
 }
-/** The sign-in's pages stand alone: no stylesheet, script or font loads here, so the palette rides inline. */
 const STYLE = styleElement([
     `:root{color-scheme:light dark;--ground:#efefef;--paper:#fff;--ink:#171717;--muted:#666;--line:#e6e6e6;--soft:#f2f2f2;--accent:#171717;--on-accent:#fff;--problem:#b42318}`,
     `@media (prefers-color-scheme:dark){:root{--ground:#0b0b0b;--paper:#161616;--ink:#ededed;--muted:#a1a1a1;--line:#262626;--soft:#1f1f1f;--accent:#ededed;--on-accent:#0b0b0b;--problem:#ff8a80}}`,

package/dist/mcp-person.js

@@ -1,13 +1,4 @@
 import { adapterPolicy } from "./server/route-policy.js";
-/**
- * A person's tools on the HTTP gateway. A person signs in with their own API token (api-tokens.ts) and every tool call
- * is the exact `toolroll` command line they could type, run on the server under their principal through
- * `runOperateAs` with source "mcp": the command's own authorization, project grants and attribution apply, and its
- * `--json` envelope is the answer. Nothing here reads data directly — a coordinator handler would skip the person's
- * project grants — and nothing here approves, answers or changes people or policy: those verbs have no tool.
- *
- * tools/list follows the account's role and the token's scope; dispatch checks again, independent of the list.
- */
 import { parseContract, toModelSchema } from "./contracts/contract.js";
 import { PERSON_TOOL_INPUTS, PERSON_TOOL_OUTPUTS } from "./contracts/gateway-tools.js";
 import { reportToolOutput } from "./contracts/lead-tools.js";
@@ -51,12 +42,10 @@ const TOOLS = {
     },
 };
 const NAMES = Object.keys(PERSON_TOOL_INPUTS);
-/** What this person may call: every read, and the acts only on an act token of an account that acts. */
 export function personTools(person) {
     return NAMES.filter(name => mayCall(person, name)).map(name => ({ name, description: TOOLS[name].description, inputSchema: toModelSchema(PERSON_TOOL_INPUTS[name]) }));
 }
 const mayCall = (person, name) => !TOOLS[name].acts || person.principal.scope === "act" && person.role === "approver";
-/** One person tools/call: read by its schema, checked against the person, then run as the command it names. */
 export async function callPersonTool(person, store, runAs, params) {
     const name = typeof params["name"] === "string" ? params["name"] : "";
     if (!NAMES.includes(name))

package/dist/mcp.js

@@ -1,32 +1,4 @@
 import { statSync } from 'node:fs';
-/**
- * `toolroll mcp` — the MCP stdio adapter (MCP gateway spec v6). What a
- * call means lives in the transport-free core (mcp-core.ts); this file owns
- * the stdio transport, era pinning and the connection's lifecycle.
- *
- *
- * Zero-dep JSON-RPC 2.0 over stdio, newline-delimited; stdout carries
- * protocol bytes ONLY (logs go to stderr); clean EOF is clean shutdown.
- * Two pinned protocol revisions:
- *
- *   - modern `2026-07-28`: stateless; every request carries its version in
- *     `_meta`; `server/discover` describes the server; successful results
- *     are schema-complete (`resultType: "complete"`, and tools/list +
- *     discover carry `ttlMs: 0` with the narrowest `cacheScope`).
- *   - legacy `2025-11-25`: the initialize era — a client asking for an
- *     unsupported version is answered WITH this one (negotiation, not
- *     refusal); `notifications/initialized` is received and ignored. The
- *     eras never cross: initialize never counter-offers the modern one.
- *
- * No JSON-RPC batching in either era (arrays reject). A cancellation is a
- * notification: the server stops work on that id and suppresses its
- * response entirely. Limits: request ≤ 256 KiB, JSON depth ≤ 32.
- *
- * EVERY tool call authenticates the coordinator credential; the schema
- * version is re-read per call (a concurrent migration refuses in words
- * and the server exits). Protocol errors are JSON-RPC errors; tool-level
- * refusals are successful `tools/call` results with `isError: true`.
- */
 import { PACKAGE_VERSION } from "./version.js";
 import { authenticateCoordinator } from "./coordinator.js";
 import { LEGACY, META_CAPABILITIES, META_SERVER, META_VERSION, MODERN, TOOLS, UNSUPPORTED_VERSION, callCoordinatorTool, capabilitiesShape, readMessage, shapeResult, toolsPayload, } from "./mcp-core.js";
@@ -42,18 +14,12 @@ function fileIdentity(path) {
         return null;
     }
 }
-/** Still the same file at the same path: not moved aside, deleted, or replaced by a rename. */
 function sameFile(was) {
     const now = fileIdentity(was.path);
     return now !== null && now.dev === was.dev && now.ino === was.ino;
 }
-/** Serve until EOF. The store is already open through the non-migrating
- * door; the token was startup-verified by the caller (and dies here again
- * if it does not hold). */
 export function serveMcp(store, token, io, clock = () => new Date(), enrolled = null, evidenceRoot) {
-    /** Per connection: which decisions this credential read in full (v3). */
     const readDecisions = new Set();
-    /** The database file this server opened, by identity (null in memory). */
     const database = fileIdentity(store.databaseFile());
     const auth = authenticateCoordinator(store, token);
     if (!auth.ok) {
@@ -65,37 +31,23 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
                     : "no live coordinator credential matches this token",
         };
     }
-    // Cancellation semantics on a SERIAL server (round-2 finding 2, stated
-    // rather than pretended): every request completes before the next line
-    // is read, so no cancellation can arrive while its target is genuinely
-    // in flight — and the revision permits ignoring cancellations for
-    // completed requests. The registry exists so any future asynchronous
-    // tool inherits correct suppression, and so a pre-cancelled FUTURE id
-    // can never be blacklisted (the in-flight check).
     const cancelled = new Set();
     const inFlight = new Set();
-    // Legacy lifecycle state (review finding 2): initialize must come first
-    // in the handshake era; the modern era is stateless by design.
     let initializeSeen = false;
     let legacyReady = false;
-    // Stdio pins ONE era per connection (round-2 finding 2): the first
-    // era-classified request decides, and the other era's metadata refuses.
     let pinnedEra = null;
     const error = (id, code, message) => io.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }));
     const respond = (id, era, result, cacheable) => {
         if (id !== null && cancelled.has(JSON.stringify(id)))
-            return; // suppressed entirely
+            return;
         io.write(JSON.stringify({ jsonrpc: "2.0", id, result: shapeResult(era, result, cacheable) }));
     };
     const callTool = (id, era, params) => {
-        // A restore or rollback puts a different file at the database's path: this server's connection still reads and
-        // writes the one it replaced, so it answers nothing more and exits (the agent starts it again on the new one).
         if (database !== null && !sameFile(database)) {
             error(id, -32000, "the database was replaced underneath this server (a Toolroll restore or rollback) — restart it");
             io.exit(0);
             return;
         }
-        // A moved schema or a credential that no longer stands refuses in words and the server exits clean.
         const outcome = callCoordinatorTool({ store, token, enrolled, clock, readDecisions, ...(evidenceRoot === undefined ? {} : { evidenceRoot }) }, params);
         if (outcome.kind === "result")
             return respond(id, era, outcome.result, false);
@@ -112,36 +64,25 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
             return;
         }
         const { id, method, params, meta } = read;
-        // Every method — lifecycle included — refuses on a moved schema
-        // (review finding 3): a server that answers discover from one world
-        // and tools from another is lying to somebody.
         if (!store.schemaCurrent()) {
             error(id, -32000, "the database schema moved underneath this server — restart it");
             io.exit(0);
             return;
         }
         if (method === "notifications/cancelled") {
-            // Cancellation touches IN-FLIGHT work only (review finding 2): an id
-            // never seen, already answered, or yet to arrive is not cancellable —
-            // pre-cancelling the future would let a peer suppress request ids
-            // forever.
             const target = params["requestId"];
             if (target !== undefined && inFlight.has(JSON.stringify(target))) {
                 cancelled.add(JSON.stringify(target));
             }
-            return; // a notification — no reply of any kind
+            return;
         }
         if (method === "notifications/initialized") {
-            // Only a handshake that actually happened completes (round-2 f2).
             if (initializeSeen)
                 legacyReady = true;
             return;
         }
         if (method.startsWith("notifications/"))
-            return; // unknown notification: silence, never an error
-        // An unsupported protocol version refuses -32022 with the revision's
-        // OWN shape for EVERY request — server/discover included (round-3
-        // finding 4): the ask precedes any per-method branch.
+            return;
         const declared = typeof meta[META_VERSION] === "string" ? meta[META_VERSION] : null;
         if (declared !== null && declared !== MODERN && declared !== LEGACY) {
             io.write(JSON.stringify({
@@ -162,8 +103,6 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
             }
             pinnedEra = "legacy";
             initializeSeen = true;
-            // The handshake era can only negotiate ITSELF: an unsupported ask is
-            // answered WITH the legacy version, never the modern one.
             respond(id, "legacy", {
                 protocolVersion: LEGACY,
                 capabilities: { tools: {} },
@@ -177,8 +116,6 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
                 return;
             }
             if (declared !== MODERN || !capabilitiesShape(meta[META_CAPABILITIES])) {
-                // The modern era's requests carry BOTH namespaced keys (round-2
-                // finding 1) — a bare discover is not a modern request.
                 error(id, -32600, `server/discover requires _meta["${META_VERSION}"] = "${MODERN}" and _meta["${META_CAPABILITIES}"]`);
                 return;
             }
@@ -192,10 +129,6 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
             }, true);
             return;
         }
-        // Era classification precedes every remaining method — ping and unknown
-        // methods included (round-3 finding 1): a refused modern ping still pins
-        // the modern era, and a cross-era unknown method refuses on the pin
-        // instead of slipping past it.
         const era = declared === MODERN ? "modern" : "legacy";
         if (era === "modern" && !capabilitiesShape(meta[META_CAPABILITIES])) {
             error(id, -32600, `a ${MODERN} request carries _meta["${META_CAPABILITIES}"]`);
@@ -207,7 +140,6 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
         }
         pinnedEra = era;
         if (method === "ping") {
-            // ping left the protocol in 2026-07-28 — only the handshake era has it.
             if (era === "modern") {
                 error(id, -32601, "ping is not part of the modern revision");
                 return;
@@ -215,8 +147,6 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
             respond(id, "legacy", {}, false);
             return;
         }
-        // The handshake era operates only after its lifecycle completed; the
-        // modern era is stateless and needs no handshake.
         if (era === "legacy" && !legacyReady && (method === "tools/list" || method === "tools/call")) {
             error(id, -32002, "not initialized — the handshake era requires initialize and notifications/initialized first");
             return;

package/dist/memory-cli.js

@@ -1,6 +1,3 @@
-/** `toolroll memory …`: the project's decisions and one search over its
- * memory, from the terminal. Reads use the remembered local login; writes
- * record who did them. Nothing here starts a model. */
 import { envelopeJson } from './envelope.js';
 import { decisionHistory, getDecision, listDecisions, recordDecision, retireDecision, searchMemory } from './project-memory.js';
 import { decideProposal, defaultAnalyzer, defaultTidyAnalyzer, listProposals, memoryStatus, runMemoryPass } from './memory-pass.js';

package/dist/memory-pass.js

@@ -1,15 +1,3 @@
-/**
- * The backward pass over project memory (modelled on backpass, 2026-09-21):
- * sessions are the loss signal, the always-loaded instructions are the
- * weights, and nothing lands without verbatim evidence from at least two
- * distinct sessions and a person's accept. Four stages, all read-only until
- * apply: collect sessions (plane threads and crew runs from the database,
- * Claude Code and Codex session files on this machine), distil each to a
- * bounded trace, analyse each trace once per surface version, aggregate
- * gaps in a ledger that survives runs, then propose a few edits. `apply`
- * is the one writer, and it writes through the ordinary knowledge and
- * decision stores so every edit keeps its revision.
- */
 import { inEvalWorld } from './eval-gate.js';
 import { createHash } from 'node:crypto';
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
@@ -27,19 +15,14 @@ import { currentLocalOwner } from './local-owner.js';
 import { CONTRADICTION_SCHEMA } from './memory-tidy.js';
 import { contractError, parseContract } from './contracts/contract.js';
 import { MEMORY_VERDICT_MODEL_SCHEMA, MEMORY_VERDICT_VERSION, memoryEvidenceSchema, memoryProposalSchema, memoryVerdictReadSchema, readSavedVerdict, savedVerdictSchema } from './contracts/memory-pass.js';
-/** One session's trace, in characters (TEXT_LIMITS.memoryTrace). */
 export const MEMORY_TRACE_BYTES = TEXT_LIMITS.memoryTrace;
 export const MEMORY_MIN_SESSIONS = 2;
 export const MEMORY_MAX_PROPOSALS = 6;
-/** The project instructions' budget: the same limit knowledge holds them to. */
 export const INSTRUCTION_BUDGET_BYTES = TEXT_LIMITS.knowledgeInstructionsBytes;
-/** How many claims of each kind one verdict keeps. */
 const VERDICT_ITEMS = 20;
 export const MEMORY_GAP_MAX_AGE_MS = 90 * 24 * 3_600_000;
 const sha = (text) => createHash('sha256').update(text).digest('hex');
-/** The Claude Code project directory for a checkout: the path with every slash turned into a dash. */
 export const claudeProjectDir = (cwd, home = homedir()) => join(home, '.claude', 'projects', cwd.replaceAll('/', '-'));
-/** Coarse by design: a line that trips the secret scanner is dropped whole, named by pattern. */
 function redact(text) {
     const hits = new Map(scanForSecrets(text).map(hit => [hit.line, hit.name]));
     if (hits.size === 0)
@@ -54,7 +37,6 @@ catch {
     return [];
 } });
 const obj = (v) => (v !== null && typeof v === 'object' && !Array.isArray(v) ? v : {});
-/** Claude Code: one JSONL per session; user/assistant text verbatim, tool calls one line, results clipped, thinking dropped. */
 export function distillClaude(path) {
     const lines = [];
     for (const raw of jsonLines(path)) {
@@ -79,7 +61,6 @@ export function distillClaude(path) {
     }
     return redact(lines.join('\n'));
 }
-/** Codex: rollout JSONL; messages and custom tool calls, outputs clipped. */
 export function distillCodex(path) {
     const lines = [];
     for (const raw of jsonLines(path)) {
@@ -140,7 +121,6 @@ function fileSources(repo, kind, home) {
     }
     return out;
 }
-/** The plane's own sessions: lead threads that touched the project, and finished crew runs with their handoff and check output. */
 function planeSources(store, repo, evidenceRoot) {
     const out = [];
     const threads = store.handle.prepare(`SELECT c.thread AS thread, c.id AS conversation, MAX(m.id) AS last, MAX(m.created_at) AS at FROM team_conversation c JOIN lead_message m ON m.thread=c.thread AND m.pending=0
@@ -173,7 +153,6 @@ export function collectSessions(store, repo, options = {}) {
     const sources = [...planeSources(store, repo, options.evidenceRoot), ...(options.local === false ? [] : [...fileSources(repo, 'claude', home), ...fileSources(repo, 'codex', home)])];
     return sources.sort((a, b) => b.at.localeCompare(a.at));
 }
-/** The always-loaded surface: instruction lines with stable ids, active decisions with theirs. Its hash keys the analysis cache. */
 export function memorySurface(store, repo, actor) {
     const view = knowledgeView(store, repo, actor);
     const instructions = view.knowledge.instructions.split('\n').map(line => line.trim()).filter(Boolean).map((text, index) => ({ id: `IN-${String(index + 1).padStart(3, '0')}`, text }));
@@ -190,10 +169,8 @@ export function analysisPrompt(surface, openGaps) {
         'Rules: every item needs a verbatim quote copied from the trace or it is discarded; negative evidence outranks positive; class harm means following the instruction caused damage, non-compliance means it was ignored; a mistake caused by the harness or task framing is domain orchestration; report nothing rather than something weak; an empty array is a good answer.',
     ].join('\n');
 }
-/** The production analyser: one call through the configured chat provider, no tools, no history. */
 export function defaultAnalyzer(store, options) {
     return async (input) => {
-        // An eval world makes no provider call it can't record (eval-gate.ts, Codex round 1 #3): the backward pass waits.
         if (inEvalWorld())
             return { ok: false, problem: 'The backward pass makes no provider call in an eval world.' };
         const config = store.getChatConfig();
@@ -219,12 +196,10 @@ export function defaultAnalyzer(store, options) {
             const answer = await performLeadRequest(request, config.provider, AbortSignal.timeout(options.timeoutMs ?? 120_000), options.fetcher);
             return answer.ok ? { ok: true, text: answer.answer.text } : { ok: false, problem: answer.problem };
         }
-        // The verdict's own schema is the harness's structured output, so the answer is the verdict itself.
         const answer = await performSubscriptionLeadRequest({ provider: config.provider, model: config.model, system, dataDocument, history, tools: [], outputSchema: MEMORY_VERDICT_MODEL_SCHEMA, timeoutMs: options.timeoutMs ?? 180_000 }, options.runner);
         return answer.ok ? { ok: true, text: answer.answer.text } : { ok: false, problem: answer.problem };
     };
 }
-/** The clean-up's question to the chat model, asked only on a person's request (memory-tidy.ts proposeTidy). */
 export function defaultTidyAnalyzer(store, options = {}) {
     return async (input) => {
         if (inEvalWorld())
@@ -255,10 +230,6 @@ export function defaultTidyAnalyzer(store, options = {}) {
     };
 }
 const UNREADABLE = 'The analysis was not a readable verdict.';
-/**
- * Read the analyser's answer with the tolerant parse-side schema, then keep only claims whose quote
- * is really in the trace and, for an instruction's effect, whose id is on the surface audited.
- */
 export function parseVerdict(text, trace, surface) {
     const start = text.indexOf('{'), end = text.lastIndexOf('}');
     if (start < 0 || end <= start)
@@ -284,14 +255,8 @@ export function parseVerdict(text, trace, surface) {
             gaps: list(read.value.gaps),
         } };
 }
-/** A verdict as a session keeps it: through its schema, with its version. */
 const keptVerdict = (verdict) => JSON.stringify(savedVerdictSchema.parse({ version: MEMORY_VERDICT_VERSION, ...verdict }));
 const gapKey = (mistake) => sha(mistake.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim()).slice(0, 16);
-/**
- * Collect, distil, analyse and aggregate for one project. Never writes memory:
- * it fills the ledger and the proposal queue. Each session is analysed once
- * per surface version; a failed analysis is named and retried next run.
- */
 export async function runMemoryPass(store, args, now = new Date()) {
     const surface = memorySurface(store, args.repo, args.actor);
     const sessions = collectSessions(store, args.repo, { ...(args.evidenceRoot === undefined ? {} : { evidenceRoot: args.evidenceRoot }), ...(args.home === undefined ? {} : { home: args.home }), ...(args.local === undefined ? {} : { local: args.local }) }).slice(0, args.maxSessions ?? 100);
@@ -347,8 +312,6 @@ export async function runMemoryPass(store, args, now = new Date()) {
     report.proposals = synthesizeProposals(store, args.repo, args.actor, surface, now);
     return report;
 }
-// ---- 4. propose --------------------------------------------------------------------
-/** A proposal row through its schema; one that does not read as a proposal names the field. */
 function proposalOf(row) {
     const read = memoryProposalSchema.safeParse({ id: Number(row['id']), repo: String(row['repo']), kind: row['kind'], fingerprint: String(row['fingerprint']), title: String(row['title']), rationale: String(row['rationale']),
         beforeText: row['before_text'] === null ? null : String(row['before_text']), afterText: String(row['after_text']), evidence: JSON.parse(String(row['evidence'])),
@@ -357,20 +320,11 @@ function proposalOf(row) {
         throw Error(`Memory proposal ${String(row['id'])} could not be read: ${contractError(read.error).join('; ')}`);
     return read.data;
 }
-/**
- * Turn corroborated gaps and harm into a few proposals: an addition needs
- * the gap seen in at least two distinct sessions; a removal needs harm from
- * following the instruction in two sessions. Under the instruction budget an
- * addition is proposed only when it fits; over it, the run says so instead
- * of growing the file. A rejected fingerprint is not proposed again until
- * more sessions corroborate it.
- */
 export function synthesizeProposals(store, repo, actor, surface, now = new Date()) {
     const view = knowledgeView(store, repo, actor);
     const budgetLeft = INSTRUCTION_BUDGET_BYTES - Buffer.byteLength(view.knowledge.instructions);
     let made = 0;
     store.transact(() => {
-        // A lesson note is bound to its own recorded facts, not to the surface.
         store.handle.prepare("UPDATE memory_proposal SET status='stale' WHERE repo=? AND status='pending' AND surface<>? AND surface<>?").run(repo, surface.version, NOTE_SURFACE);
         const pendingFingerprints = new Set(store.handle.prepare("SELECT fingerprint FROM memory_proposal WHERE repo=? AND status='pending'").all(repo).map(row => String(row['fingerprint'])));
         const rejected = new Map(store.handle.prepare('SELECT fingerprint, sessions FROM memory_rejection WHERE repo=?').all(repo).map(row => [String(row['fingerprint']), Number(row['sessions'])]));
@@ -385,7 +339,6 @@ export function synthesizeProposals(store, repo, actor, surface, now = new Date(
             pendingFingerprints.add(fingerprint);
             made++;
         };
-        // Additions from corroborated gaps.
         const gaps = store.handle.prepare("SELECT g.id, g.key, g.mistake, g.proposed FROM memory_gap g WHERE g.repo=? AND g.retired_at IS NULL AND g.domain='project' ORDER BY g.last_seen DESC").all(repo);
         for (const gap of gaps) {
             const sightings = store.handle.prepare('SELECT session, quote FROM memory_sighting WHERE gap=? ORDER BY at').all(Number(gap['id'])).map(row => ({ session: String(row['session']), quote: String(row['quote']) }));
@@ -403,7 +356,6 @@ export function synthesizeProposals(store, repo, actor, surface, now = new Date(
             }
             consider('instruction-add', `add:${String(gap['key'])}`, `Add: ${clip(proposed, 80)}`, `Mistake seen in ${new Set(sightings.map(s => s.session)).size} sessions: ${String(gap['mistake'])}`, null, proposed, sightings);
         }
-        // Removals from harm.
         const harm = new Map();
         for (const row of store.handle.prepare("SELECT id, verdict FROM memory_session WHERE repo=? AND surface=? AND verdict IS NOT NULL").all(repo, surface.version)) {
             let kept;
@@ -432,12 +384,10 @@ export function synthesizeProposals(store, repo, actor, surface, now = new Date(
 export function listProposals(store, repo, status = 'pending') {
     return store.handle.prepare(`SELECT * FROM memory_proposal WHERE repo=? AND (?='all' OR status=?) ORDER BY id DESC LIMIT 100`).all(repo, status, status).map(row => proposalOf(row));
 }
-/** The one writer: accept applies the edit through the knowledge or decision store as the person; reject remembers the fingerprint and its corroboration. */
 export function decideProposal(store, args, now = new Date()) {
     refuseLeadMemoryWrite();
     return store.transact(() => {
         refuseLeadMemoryWrite();
-        // A person who may change this project's memory, read inside the write (a revoked account or lost access refuses).
         if (!store.accountCanAccess(args.actor, args.repo) || store.accountOf(args.actor)?.role !== 'approver')
             throw Error('Project memory is outside your access.');
         const row = store.handle.prepare('SELECT * FROM memory_proposal WHERE id=? AND repo=?').get(args.id, args.repo);
@@ -447,7 +397,6 @@ export function decideProposal(store, args, now = new Date()) {
         if (proposal.status !== 'pending')
             throw Error('That proposal was already decided.');
         const note = lessonNoteOf(store, proposal.id);
-        // The laptop's local owner may decide lesson notes and clean-ups, nothing else here (D3): the act says which.
         const local = currentLocalOwner();
         if (local !== null && (note === null || local.act !== 'memory-review'))
             throw Error('Sign in with your password to do this.');
@@ -461,7 +410,6 @@ export function decideProposal(store, args, now = new Date()) {
                 .run(args.repo, proposal.fingerprint, now.toISOString(), args.actor, proposal.sessions);
         }
         else if (note !== null) {
-            // A person's words, not the draft: "failed then passed" is what Toolroll recorded; what it means is theirs to say.
             const claim = (args.claim ?? '').trim();
             if (claim === '' || claim === proposal.afterText.trim())
                 throw Error('Write the note in your own words before accepting it.');
@@ -493,7 +441,6 @@ export function memoryStatus(store, repo, actor) {
         pending: Number(store.handle.prepare("SELECT COUNT(*) AS n FROM memory_proposal WHERE repo=? AND status='pending'").get(repo)?.['n'] ?? 0),
         included: includedLines(store, repo, actor, view.knowledge.references) };
 }
-/** "Last included" for every decision, reference and adopted lesson, in the order they're listed elsewhere. */
 function includedLines(store, repo, actor, references) {
     const use = memoryUseOf(store, repo);
     const line = (kind, item, title) => ({ kind, item, title, words: lastIncludedWords(use.get(`${kind}:${item}`)) });