toolroll 0.9.92 → 0.9.94

package/dist/invoke.js

@@ -27,7 +27,7 @@ import { attestProvider } from "./attest.js";
 import { run as runCommand, runOwnerTag, streamsInput } from "./exec.js";
 import { spawnSync } from "node:child_process";
 import { currentContainment } from "./containment.js";
-import { recordRunBillingBasis, recordRunCostUnknown, recordRunModelReported } from "./store.js";
+import { recordCheckStamp, recordRunBillingBasis, recordRunCostUnknown, recordRunModelReported } from "./store.js";
 import { witnessedRunner } from "./process-custody.js";
 import { underStopWatch } from "./task-control.js";
 import { childDatabaseEnv, isolatedChildDatabase, removeChildDatabase as removeAgentDatabase } from "./child-database.js";
@@ -39,10 +39,12 @@ import { dirname, join } from "node:path";
 import { poolRootOf } from "./worktree.js";
 import { checkLaunchRoot, signInGrants, signInIsItself } from "./agent-fence.js";
 import { localModeOn } from "./local-owner.js";
+import { CHECK_STAMP_VERSION, EVERYWHERE, unfencedStamp } from "./check-stamp.js";
 import { CHECK_ACCESS_DEFAULT, checkAccessHere, localModeCap, narrowestAccess, narrowestNetwork, signInsAvailable } from "./check-access.js";
 import { readDenyPath } from "./project-sandbox.js";
 import { sandboxRuntimeWords } from "./sandbox-runtime.js";
 import { canonicalJson } from "./canonical-json.js";
+import { deliveredFile } from "./code-map-admission.js";
 import { buildCacheEnv, buildCacheFolder, grantFolder, writeAllowlist, WRITES_DEFAULT, CheckoutBindingError, trustedWorktreeBinding, checkoutGitEnv, HARDENED_GIT_ARGS, codexFenceArgv, fenceFor, fencedGitEnv, LEGACY_SANDBOX, launchSandboxOf, linuxFenceAvailable, macosFenceAvailable, NO_GRANTS, sandboxedSpawn, serverGrantsOf, runFolders, taskBoundary } from "./agent-fence.js";
 import { proxyEnv, providerOnlyNetwork, repositoryEcosystems, resolveNetwork, startEgressProxy } from "./egress.js";
 import { claudeConfigDir, claudeDefaults, codexDefaults, codexHomeDir, isolatedCodexHome } from "./provider-home.js";
@@ -960,6 +962,8 @@ function runFence(store, runId, provider, keyHome, ownTools, writes = WRITES_DEF
         // checkout was recorded in (a --pool elsewhere), so another project's worktree, present at launch, is out of reach. Native wrappers also cover later creations.
         const launch = fenceFor(provider === "command" ? "command" : "build", { databaseFile, worktree, ...home, boundary, binding, runFolders: folders, poolRoots,
             extra: allowed?.deny ?? [], linked: linkedFor(store, worktree), writes: allowed === null ? null : { writes: allowed.writes, readOnly: allowed.readOnly }, policy: sandbox.policy, provider,
+            // This launch's code map file: exactly that file, read-only, inside the denied state folder. Commands don't get it.
+            ...(provider === "command" ? {} : { exactFile: deliveredFile(store, runId) }),
             // The sealed read denies, and whatever the project lists now too (adding a deny only narrows).
             readDeny: [...new Set([...sandbox.readDeny, ...(row === null ? [] : store.projectSandbox(row.repo).readDeny)])].map(one => readDenyPath(one, keyHome ?? homedir())), machLookup: sandbox.machLookup });
         return {
@@ -992,6 +996,7 @@ export function fencedCommands(store, runId, writes, inner, available = () => ma
         if (!available()) {
             if (store.unfencedAgentsAllowed()) {
                 store.stampRunCheckAccess(runId, "unsandboxed");
+                stampLaunch(store, [runId], unfencedStamp());
                 return inner(file, args, options);
             }
             return { code: 1, stdout: "", stderr: "This machine can't confine the build's commands (no macOS sandbox, no working bubblewrap), so they didn't run. Install bubblewrap, socat and ripgrep (Linux), or an instance operator allows unconfined agents with `toolroll config unconfined-agents allow`.\n", timedOut: false, notFound: false };
@@ -1002,13 +1007,17 @@ export function fencedCommands(store, runId, writes, inner, available = () => ma
             mkdirSync(temp, { mode: 0o700 });
             // Not sandboxed (check-access.ts): the project's checks are trusted by the whole instance, as before 0.9.66. Never
             // while local mode is on (easy-start C5): then they run in the fence, sandboxed.
-            if (access === "unsandboxed" && !localModeOn(store))
+            if (access === "unsandboxed" && !localModeOn(store)) {
+                stampLaunch(store, [runId], unfencedStamp());
                 return await inner(file, args, { ...options, env: { ...(options?.env ?? {}), TMPDIR: temp, TMP: temp, TEMP: temp } });
+            }
             const fenced = runFence(store, runId, "command", undefined, own, writes, sandbox);
             if (fenced.problem !== undefined)
                 return { code: 1, stdout: "", stderr: `${fenced.problem}\n`, timedOut: false, notFound: false };
-            if (fenced.fence.length === 0)
+            if (fenced.fence.length === 0) {
+                stampLaunch(store, [runId], unfencedStamp());
                 return inner(file, args, options);
+            }
             // A self-hosted check's own database (child-database.ts) is the command's to write too.
             const database = options?.env?.["TOOLROLL_DB"];
             const checkData = database === undefined || fenced.grants.writes === undefined ? null : grantFolder(dirname(database), false);
@@ -1020,12 +1029,14 @@ export function fencedCommands(store, runId, writes, inner, available = () => ma
             if (signIns !== null && "problem" in signIns)
                 return { code: 1, stdout: "", stderr: `${signIns.problem}\n`, timedOut: false, notFound: false };
             try {
+                // Each sign-in file looked at again right before the launch: one no longer itself isn't granted.
+                // Never the keychain: the sign-ins kept there come in the environment, read outside (keychainSignIns).
+                const given = signIns === null ? grants : { ...grants, signIns: { ...signIns.grants, read: signIns.grants.read.filter(path => signInIsItself(realpathSync(homedir()), path)) }, network: signIns.network };
+                stampLaunch(store, [runId], fencedStamp(signIns === null ? "sandboxed" : "sign-ins", fenced.fence, given, signIns === null ? undefined : network));
                 return await inner(file, args, {
                     ...options,
                     fence: fenced.fence,
-                    // Each sign-in file looked at again right before the launch: one no longer itself isn't granted.
-                    // Never the keychain: the sign-ins kept there come in the environment, read outside (keychainSignIns).
-                    fenceGrants: signIns === null ? grants : { ...grants, signIns: { ...signIns.grants, read: signIns.grants.read.filter(path => signInIsItself(realpathSync(homedir()), path)) }, network: signIns.network },
+                    fenceGrants: given,
                     confinement: "required",
                     env: { ...(options?.env ?? {}), TMPDIR: temp, TMP: temp, TEMP: temp, ...(fenced.cache === undefined || fenced.grants.writes === undefined ? {} : buildCacheEnv(fenced.cache)), ...(signIns?.env ?? {}) },
                     ...(signIns === null ? {} : { omitEnv: [...(options?.omitEnv ?? []), ...SIGN_INS_OMITTED_ENV] }),
@@ -1046,26 +1057,32 @@ export function fencedCommands(store, runId, writes, inner, available = () => ma
  * project's writes setting, only that checkout, its Git data, its own temp folder, the project's caches and its check
  * database writable. Where nothing can confine them, they run only when an instance operator allowed unconfined agents.
  */
-export function fencedCheckoutCommands(store, repo, checkout, inner, available = () => macosFenceAvailable() || linuxFenceAvailable(), access = CHECK_ACCESS_DEFAULT, network, sandbox = LEGACY_SANDBOX) {
+export function fencedCheckoutCommands(store, repo, checkout, inner, available = () => macosFenceAvailable() || linuxFenceAvailable(), access = CHECK_ACCESS_DEFAULT, network, sandbox = LEGACY_SANDBOX, stampRuns = []) {
     if (inner !== runCommand)
         return inner;
     return async (file, args, options) => {
         if (!available()) {
-            if (store.unfencedAgentsAllowed())
+            if (store.unfencedAgentsAllowed()) {
+                stampLaunch(store, stampRuns, unfencedStamp());
                 return inner(file, args, options);
+            }
             return { code: 1, stdout: "", stderr: "This machine can't confine the project's checks (no macOS sandbox, no working bubblewrap), so they didn't run. Install bubblewrap, socat and ripgrep (Linux), or an instance operator allows unconfined agents with `toolroll config unconfined-agents allow`.\n", timedOut: false, notFound: false };
         }
         const databaseFile = store.databaseFile();
-        if (databaseFile === null)
+        if (databaseFile === null) {
+            stampLaunch(store, stampRuns, unfencedStamp());
             return inner(file, args, options);
+        }
         const own = realpathSync(mkdtempSync(join(checkLaunchRoot(), "so-cmd-")));
         try {
             const temp = join(own, "tmp");
             mkdirSync(temp, { mode: 0o700 });
             // Not sandboxed (check-access.ts): the project's checks are trusted by the whole instance, as before 0.9.66. Never
             // while local mode is on (easy-start C5): then they run in the fence, sandboxed.
-            if (access === "unsandboxed" && !localModeOn(store))
+            if (access === "unsandboxed" && !localModeOn(store)) {
+                stampLaunch(store, stampRuns, unfencedStamp());
                 return await inner(file, args, { ...options, env: { ...(options?.env ?? {}), TMPDIR: temp, TMP: temp, TEMP: temp } });
+            }
             let binding;
             try {
                 binding = trustedWorktreeBinding(repo, checkout);
@@ -1091,12 +1108,14 @@ export function fencedCheckoutCommands(store, repo, checkout, inner, available =
             if (signIns !== null && "problem" in signIns)
                 return { code: 1, stdout: "", stderr: `${signIns.problem}\n`, timedOut: false, notFound: false };
             try {
+                // Each sign-in file looked at again right before the launch: one no longer itself isn't granted.
+                // Never the keychain: the sign-ins kept there come in the environment, read outside (keychainSignIns).
+                const given = signIns === null ? grants : { ...grants, signIns: { ...signIns.grants, read: signIns.grants.read.filter(path => signInIsItself(realpathSync(homedir()), path)) }, network: signIns.network };
+                stampLaunch(store, stampRuns, fencedStamp(signIns === null ? "sandboxed" : "sign-ins", launch.fence, given, signIns === null ? undefined : network));
                 return await inner(file, args, {
                     ...options,
                     fence: launch.fence,
-                    // Each sign-in file looked at again right before the launch: one no longer itself isn't granted.
-                    // Never the keychain: the sign-ins kept there come in the environment, read outside (keychainSignIns).
-                    fenceGrants: signIns === null ? grants : { ...grants, signIns: { ...signIns.grants, read: signIns.grants.read.filter(path => signInIsItself(realpathSync(homedir()), path)) }, network: signIns.network },
+                    fenceGrants: given,
                     confinement: launch.confinement,
                     env: { ...(options?.env ?? {}), TMPDIR: temp, TMP: temp, TEMP: temp, ...(allowed === null ? {} : buildCacheEnv(cache)), ...(signIns?.env ?? {}) },
                     ...(signIns === null ? {} : { omitEnv: [...(options?.omitEnv ?? []), ...SIGN_INS_OMITTED_ENV] }),
@@ -1284,7 +1303,7 @@ export function checkoutRunner(store, repo, checkout, inner, runIds, ran, platfo
     return (file, args, options) => {
         const launch = checkoutLaunchOf(store, repo, runIds, platform);
         ran(actualCheckAccess(store, launch.access));
-        return fencedCheckoutCommands(store, repo, checkout, inner, undefined, launch.access, launch.network, checkoutSandboxOf(store, repo, runIds))(file, args, options);
+        return fencedCheckoutCommands(store, repo, checkout, inner, undefined, launch.access, launch.network, checkoutSandboxOf(store, repo, runIds), runIds)(file, args, options);
     };
 }
 /**
@@ -1308,6 +1327,22 @@ export function checkoutSandboxOf(store, repo, runIds) {
         machLookup: common(one => one.machLookup, live.machLookup),
     };
 }
+/** A fenced launch's stamp: the level it runs at and exactly what it was given (check-stamp.ts), read from the grants the
+ * launch itself takes, never from what was asked for. */
+export function fencedStamp(level, fence, grants, network) {
+    const writes = grants.writes;
+    return {
+        version: CHECK_STAMP_VERSION, level, policyDigest: fenceDigest(fence, grants),
+        writable: writes === undefined ? [EVERYWHERE] : [...new Set([...writes.subpaths, ...writes.prefixes.map(one => `${one.path}${one.suffix}`)])].sort(),
+        readable: [...new Set([...grants.readable, ...(grants.signIns?.read ?? [])])].sort(),
+        network: network === undefined ? { mode: "machine" } : { mode: network.mode, hosts: [...network.hosts].sort() },
+    };
+}
+function stampLaunch(store, runs, stamp) {
+    const now = new Date();
+    for (const runId of runs)
+        recordCheckStamp(store, runId, stamp, now);
+}
 /** The digest of a launch's whole fence (its denied paths and grants, canonical), as stamped on its run (C11). */
 export function fenceDigest(fence, grants) {
     return createHash("sha256").update(`toolroll:fence:${canonicalJson({ fence: [...fence], grants: grants })}`).digest("hex").slice(0, 32);

package/dist/job-object-helper.ps1

@@ -25,7 +25,9 @@ param(
   # a space or a percent sign the controller passed.
   [Parameter(Position = 1)] [string] $Encoded,
   [string] $JobName,
-  [string] $QueryName
+  [string] $QueryName,
+  # A whole-job memory limit in bytes (the code map's bounded reads); 0 is none.
+  [long] $MemoryLimit = 0
 )
 
 $ErrorActionPreference = "Stop"
@@ -68,6 +70,7 @@ public static class SoJob {
   public const int JobObjectBasicAccountingInformation = 1;
   public const int JobObjectExtendedLimitInformation = 9;
   public const uint JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x2000;
+  public const uint JOB_OBJECT_LIMIT_JOB_MEMORY = 0x200;
   public const uint CREATE_SUSPENDED = 0x4;
   public const uint CREATE_UNICODE_ENVIRONMENT = 0x400;
   public const int STARTF_USESTDHANDLES = 0x100;
@@ -111,7 +114,7 @@ public static class SoJob {
     catch { return "unknown"; }
     finally { CloseHandle(job); }
   }
-  public static IntPtr MakeJob(string name) {
+  public static IntPtr MakeJob(string name, long memoryLimit) {
     IntPtr job = CreateJobObjectW(IntPtr.Zero, name);
     int createdError = Marshal.GetLastWin32Error();
     if (job != IntPtr.Zero && createdError == 183) { CloseHandle(job); throw new Exception("job name already exists"); }
@@ -119,6 +122,10 @@ public static class SoJob {
     var info = new JOBOBJECT_EXTENDED_LIMIT_INFORMATION();
     // Kill on close; NO breakaway flags, so nothing inside may leave the job.
     info.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
+    if (memoryLimit > 0) {
+      info.BasicLimitInformation.LimitFlags |= JOB_OBJECT_LIMIT_JOB_MEMORY;
+      info.JobMemoryLimit = new UIntPtr((ulong)memoryLimit);
+    }
     int size = Marshal.SizeOf(typeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION));
     IntPtr buffer = Marshal.AllocHGlobal(size);
     try {
@@ -177,7 +184,7 @@ try {
   [string[]]$targetArguments = ConvertFrom-Json -InputObject ([System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($Encoded)))
   if ($targetArguments.Count -lt 1) { throw "the target argv is empty" }
   # Admission arrives only after the controller durably records this helper.
-  $job = [SoJob]::MakeJob($JobName)
+  $job = [SoJob]::MakeJob($JobName, $MemoryLimit)
   Send "ready"
   $admission = $reader.ReadLineAsync()
   if (-not $admission.Wait(15000) -or $admission.Result -cne "go") { throw "job admission refused" }

package/dist/keymap.d.ts

@@ -0,0 +1,41 @@
+/** One keymap for the console and the terminal UI (docs/plans/plain-toolroll.md P1.7). A shortcut only ever presses a
+ * control the page already rendered, the same press a person's click makes, so any password field or confirm it opens
+ * still appears; with no such control on the page the key does nothing. Shortcuts sleep in text fields, with a
+ * modifier held, and while the shortcuts list is open. Navigation keys go to a page and post nothing. */
+/** What a key does in the console. `press`: the first visible, enabled control matching these, in order. */
+export type WebShortcut = {
+    kind: "go";
+    href: string;
+} | {
+    kind: "press";
+    selectors: readonly string[];
+} | {
+    kind: "search";
+} | {
+    kind: "help";
+};
+/** What a key does in the terminal UI, or null with the reason it has none there (a named gap). */
+export type TuiShortcut = "new" | "ink" | "send-back" | "retry" | "list" | "help";
+export type Shortcut = {
+    keys: string;
+    says: string;
+    web: WebShortcut;
+    tui: TuiShortcut | {
+        none: string;
+    };
+};
+/** The page's ink act: Approve (the approve control itself, password popover and all) or Accept. */
+export declare const INK_ACT_SELECTORS: readonly ["[data-ink-approve]", '[data-ink-act="accept"]', "[data-accept-result][data-primary-action]"];
+/** Send back: the control that opens the Send back form (never its submit: the note comes first). */
+export declare const SEND_BACK_SELECTORS: readonly ['[data-act="request-changes"]', '[data-act="revise"]', 'a.result-feedback-link[href="#request-changes"]'];
+/** Retry: the result's Retry, or the failed box's own Retry form. */
+export declare const RETRY_SELECTORS: readonly ['[data-act="retry"]', 'form[data-retry] button[type="submit"]', 'form[data-rebuild] button[type="submit"]'];
+export declare const SHORTCUTS: readonly Shortcut[];
+/** The keys typed, as the help list shows them: "g h" reads "g then h". */
+export declare const keyWords: (keys: string) => string;
+/**
+ * The console's key routing, as an inline script (it runs inside chromeScript's closure, which defines `show` for the
+ * jump-to palette, `toggleHelp`, `helpOpen`, `close` and `go`). Generated from SHORTCUTS, so the table is the only
+ * place a key is defined.
+ */
+export declare function webKeymapScript(): string;

package/dist/keymap.js

@@ -0,0 +1,51 @@
+/** One keymap for the console and the terminal UI (docs/plans/plain-toolroll.md P1.7). A shortcut only ever presses a
+ * control the page already rendered, the same press a person's click makes, so any password field or confirm it opens
+ * still appears; with no such control on the page the key does nothing. Shortcuts sleep in text fields, with a
+ * modifier held, and while the shortcuts list is open. Navigation keys go to a page and post nothing. */
+/** The page's ink act: Approve (the approve control itself, password popover and all) or Accept. */
+export const INK_ACT_SELECTORS = ["[data-ink-approve]", '[data-ink-act="accept"]', "[data-accept-result][data-primary-action]"];
+/** Send back: the control that opens the Send back form (never its submit: the note comes first). */
+export const SEND_BACK_SELECTORS = ['[data-act="request-changes"]', '[data-act="revise"]', 'a.result-feedback-link[href="#request-changes"]'];
+/** Retry: the result's Retry, or the failed box's own Retry form. */
+export const RETRY_SELECTORS = ['[data-act="retry"]', 'form[data-retry] button[type="submit"]', 'form[data-rebuild] button[type="submit"]'];
+export const SHORTCUTS = [
+    { keys: "n", says: "new task", web: { kind: "go", href: "/tasks/new" }, tui: "new" },
+    { keys: "a", says: "Approve or Accept (presses the button on the page)", web: { kind: "press", selectors: INK_ACT_SELECTORS }, tui: "ink" },
+    { keys: "b", says: "Send back (opens its note)", web: { kind: "press", selectors: SEND_BACK_SELECTORS }, tui: "send-back" },
+    { keys: "r", says: "Retry (presses the button on the page)", web: { kind: "press", selectors: RETRY_SELECTORS }, tui: "retry" },
+    { keys: "/", says: "search", web: { kind: "search" }, tui: { none: "The terminal has no search; press w to open the console." } },
+    { keys: "g h", says: "go Home", web: { kind: "go", href: "/" }, tui: "list" },
+    { keys: "g t", says: "go to Tasks", web: { kind: "go", href: "/tasks" }, tui: "list" },
+    { keys: "?", says: "these shortcuts", web: { kind: "help" }, tui: "help" },
+];
+/** The keys typed, as the help list shows them: "g h" reads "g then h". */
+export const keyWords = (keys) => keys.split(" ").join(" then ");
+/**
+ * The console's key routing, as an inline script (it runs inside chromeScript's closure, which defines `show` for the
+ * jump-to palette, `toggleHelp`, `helpOpen`, `close` and `go`). Generated from SHORTCUTS, so the table is the only
+ * place a key is defined.
+ */
+export function webKeymapScript() {
+    const single = {}, after = {};
+    for (const one of SHORTCUTS) {
+        const parts = one.keys.split(" ");
+        if (parts.length === 1)
+            single[parts[0]] = one.web;
+        else if (parts[0] === "g")
+            after[parts[1]] = one.web;
+    }
+    return `var KEYS=${JSON.stringify(single)},GKEYS=${JSON.stringify(after)};` +
+        // A control a person could press right now: rendered, shown, and not disabled.
+        `function pressable(el){if(!el||el.disabled||el.getAttribute("aria-disabled")==="true")return false;` +
+        `if(el.closest("[hidden],[inert]"))return false;var r=el.getClientRects();return r.length>0;}` +
+        // Press it exactly as a click would; a submit whose form isn't complete (an empty password, a required reason)
+        // shows the browser's own prompt for it instead of posting.
+        `function press(selectors){for(var s=0;s<selectors.length;s++){var all=document.querySelectorAll(selectors[s]);` +
+        `for(var i=0;i<all.length;i++){var el=all[i];if(!pressable(el))continue;` +
+        `var form=el.form||null;var submits=el.tagName.toLowerCase()==="button"&&(el.type==="submit"||el.getAttribute("type")===null)&&form;` +
+        `if(submits&&!form.checkValidity()){form.reportValidity();return true;}` +
+        `el.click();return true;}}return false;}` +
+        `function search(){if(document.querySelector("[data-workspace-shell]")){window.dispatchEvent(new CustomEvent("so:open-search",{detail:document.activeElement}));return;}show();}` +
+        `function run(act){if(act.kind==="go"){go(act.href);return true;}if(act.kind==="press")return press(act.selectors);` +
+        `if(act.kind==="search"){search();return true;}if(act.kind==="help"){toggleHelp();return true;}return false;}`;
+}

package/dist/knowledge-cli.js

@@ -112,7 +112,7 @@ export async function runKnowledgeCommand(positional, options, context) {
         admittedToken = token;
     }
     const cacheRoot = context.evidenceRoot ? join(dirname(context.evidenceRoot), 'repository-context') : namedPath(join(homedir(), '.cache'), ['repository-context']);
-    const result = await repositoryContext({ repo: resolve(repo), query, mode: spec.action === 'impact' ? 'impact' : 'search', refresh: spec.action === 'refresh', cacheRoot, ...(typeof base === 'string' ? { baseRevision: base } : {}) });
+    const result = await repositoryContext({ repo: resolve(repo), ...(admittedToken ? { project: resolve(repo) } : {}), query, mode: spec.action === 'impact' ? 'impact' : 'search', refresh: spec.action === 'refresh', cacheRoot, ...(typeof base === 'string' ? { baseRevision: base } : {}) });
     if (admittedToken) {
         const current = authenticateCoordinator(context.store, admittedToken);
         if (!current.ok)

package/dist/knowledge-ui.d.ts

@@ -1,17 +1,18 @@
 import { type KnowledgeDraft, type KnowledgeSelection, type KnowledgeView } from './project-knowledge.js';
 import { type Html } from './html.js';
+import { type MemoryUse } from './memory-use.js';
 /** A section as a frame (after ReUI's Frame, MIT): its heading on the raised well, its body one paper panel. The
  * cards inside become hairline-divided rows of that panel, never cards in a card. */
 export declare function framedSection(heading: string, body: Html | string, extra?: string): Html;
 export declare const KNOWLEDGE_CSS = ".knowledge{max-width:780px;min-width:0;overflow-wrap:anywhere}.knowledge .card{padding:20px;min-width:0;margin:16px 0}.knowledge h2{margin:0 0 12px}.knowledge form{display:grid;gap:12px;margin:0}.knowledge label{display:grid;gap:6px}.knowledge textarea,.knowledge input,.knowledge select{box-sizing:border-box;width:100%;min-width:0;max-width:100%}.knowledge textarea{resize:vertical;min-height:110px}.knowledge button,.knowledge summary,.knowledge .button-link{min-height:44px}.knowledge button{justify-self:start;white-space:nowrap}.knowledge summary{padding:12px 0;cursor:pointer}.knowledge pre{white-space:pre-wrap;overflow-wrap:anywhere;font:inherit}.knowledge .knowledge-actions{display:flex;gap:12px;flex-wrap:wrap}.knowledge .meta{font-size:.86rem}.knowledge .knowledge-source{display:block}.knowledge details+details{border-top:1px solid var(--so-line)}.memory-stats{display:flex;flex-wrap:wrap;gap:.4rem}.memory-stats span+span::before{content:\"\u00B7\";margin-right:.4rem}.knowledge.frame{margin:0 0 16px}.knowledge.frame>.frame-head h2,.knowledge.frame>summary.frame-head{margin:0;font-size:13px;font-weight:600;line-height:1.4}.knowledge.frame>summary.frame-head{min-height:44px;padding:4px 10px}.knowledge.frame>.frame-panel{min-width:0}.knowledge.frame>.frame-panel>:first-child{margin-top:0}.knowledge.frame>.frame-panel>:last-child{margin-bottom:0}.knowledge .frame-panel>details.card,.knowledge .frame-panel .learning .card{margin:0;padding:0;border:0;border-radius:0;background:none;box-shadow:none}.knowledge .frame-panel>details.card+details.card,.knowledge .frame-panel .learning .card+.card{border-top:1px solid var(--so-line);padding-top:4px}.knowledge.frame>summary.frame-head{justify-content:flex-start}.knowledge form.field-row{grid-template-columns:minmax(0,1fr) auto;align-items:end}.knowledge form.field-row>label,.knowledge form.field-row :is(input,select,button){margin:0}@media(max-width:600px){.knowledge .card{padding:16px}.knowledge h2{font-size:1.1rem}}";
-export declare function knowledgeHtml(view: KnowledgeView, csrf: string, canManage: boolean, draft?: KnowledgeDraft, error?: string): Html;
+export declare function knowledgeHtml(view: KnowledgeView, csrf: string, canManage: boolean, draft?: KnowledgeDraft, error?: string, use?: ReadonlyMap<string, MemoryUse>): Html;
 export declare function knowledgeContextHtml(snapshot: KnowledgeSelection | null): Html | '';
 import type { Decision, MemoryHit } from './project-memory.js';
-export declare const MEMORY_INTRO = "What the lead and crew read before they work. Every change keeps its history.";
+export declare const MEMORY_INTRO = "What the lead and crew read before they work. Every change keeps its history. Last included is counted in runs.";
 export declare function decisionsHtml(repo: string, decisions: Decision[], csrf: string, canManage: boolean, draft?: {
     claim?: string;
     why?: string;
-}, error?: string): Html;
+}, error?: string, use?: ReadonlyMap<string, MemoryUse>, afterwards?: (decision: Decision) => string | null): Html;
 export declare function memorySearchHtml(repo: string, query: string, hits: MemoryHit[] | null): Html;
 import type { MemoryProposal } from './memory-pass.js';
 export declare function proposalsHtml(repo: string, proposals: MemoryProposal[], status: {
@@ -25,4 +26,20 @@ export declare function proposalsHtml(repo: string, proposals: MemoryProposal[],
     };
     openGaps: number;
     pending: number;
-} | null, csrf: string, canManage: boolean): Html;
+} | null, csrf: string, canManage: boolean, who?: string): Html;
+import type { TidyProposal } from './memory-tidy.js';
+export declare function cleanUpHtml(repo: string, proposals: readonly TidyProposal[], manage: boolean): Html;
+/** On a saved version's page: the references that aren't in current knowledge, each back as a new version. */
+export declare function referenceRestoreHtml(repo: string, revision: number, references: readonly {
+    id: string;
+    title: string;
+}[], manage: boolean): Html | '';
+/** Retired decisions, undoable merges and disabled lessons, each with its way back. */
+export declare function restoreHtml(repo: string, retired: readonly Decision[], merges: readonly {
+    merge: number;
+    successor: number;
+    predecessors: number[];
+}[], lessons: readonly {
+    id: number;
+    observation: string;
+}[], manage: boolean): Html | '';

package/dist/knowledge-ui.js

@@ -1,6 +1,7 @@
 import { STALE_KNOWLEDGE } from './project-knowledge.js';
 import { html, joinHtml, postForm } from './html.js';
-import { acts, btn, codeLine, disclose, formRow, input, note, notice, settingsLink, settingsRecord, settingsSection, textarea } from './server/kit.js';
+import { lastIncludedWords } from './memory-use.js';
+import { acts, btn, codeLine, disclose, formRow, input, note, notice, radios, settingsLink, settingsRecord, settingsSection, textarea } from './server/kit.js';
 // Hidden fields as they always were: a missing value is an empty field.
 const fields = (data) => Object.fromEntries(Object.entries(data).map(([k, v]) => [k, String(v ?? '')]));
 /** A section as a frame (after ReUI's Frame, MIT): its heading on the raised well, its body one paper panel. The
@@ -9,7 +10,7 @@ export function framedSection(heading, body, extra = '') {
     return html `<section class="${`knowledge frame${extra ? ` ${extra}` : ''}`}"><div class="frame-head"><h2>${heading}</h2></div><div class="frame-panel">${body}</div></section>`;
 }
 export const KNOWLEDGE_CSS = `.knowledge{max-width:780px;min-width:0;overflow-wrap:anywhere}.knowledge .card{padding:20px;min-width:0;margin:16px 0}.knowledge h2{margin:0 0 12px}.knowledge form{display:grid;gap:12px;margin:0}.knowledge label{display:grid;gap:6px}.knowledge textarea,.knowledge input,.knowledge select{box-sizing:border-box;width:100%;min-width:0;max-width:100%}.knowledge textarea{resize:vertical;min-height:110px}.knowledge button,.knowledge summary,.knowledge .button-link{min-height:44px}.knowledge button{justify-self:start;white-space:nowrap}.knowledge summary{padding:12px 0;cursor:pointer}.knowledge pre{white-space:pre-wrap;overflow-wrap:anywhere;font:inherit}.knowledge .knowledge-actions{display:flex;gap:12px;flex-wrap:wrap}.knowledge .meta{font-size:.86rem}.knowledge .knowledge-source{display:block}.knowledge details+details{border-top:1px solid var(--so-line)}.memory-stats{display:flex;flex-wrap:wrap;gap:.4rem}.memory-stats span+span::before{content:"·";margin-right:.4rem}.knowledge.frame{margin:0 0 16px}.knowledge.frame>.frame-head h2,.knowledge.frame>summary.frame-head{margin:0;font-size:13px;font-weight:600;line-height:1.4}.knowledge.frame>summary.frame-head{min-height:44px;padding:4px 10px}.knowledge.frame>.frame-panel{min-width:0}.knowledge.frame>.frame-panel>:first-child{margin-top:0}.knowledge.frame>.frame-panel>:last-child{margin-bottom:0}.knowledge .frame-panel>details.card,.knowledge .frame-panel .learning .card{margin:0;padding:0;border:0;border-radius:0;background:none;box-shadow:none}.knowledge .frame-panel>details.card+details.card,.knowledge .frame-panel .learning .card+.card{border-top:1px solid var(--so-line);padding-top:4px}.knowledge.frame>summary.frame-head{justify-content:flex-start}.knowledge form.field-row{grid-template-columns:minmax(0,1fr) auto;align-items:end}.knowledge form.field-row>label,.knowledge form.field-row :is(input,select,button){margin:0}@media(max-width:600px){.knowledge .card{padding:16px}.knowledge h2{font-size:1.1rem}}`;
-export function knowledgeHtml(view, csrf, canManage, draft, error) {
+export function knowledgeHtml(view, csrf, canManage, draft, error, use = new Map()) {
     const manage = canManage && !!csrf;
     const base = { repo: view.repo, identity: view.identity, revision: view.revision };
     const form = (action, body, extra = {}) => postForm('/settings/knowledge/change', body, { hidden: fields({ ...base, action, ...extra }) });
@@ -22,6 +23,7 @@ export function knowledgeHtml(view, csrf, canManage, draft, error) {
     const refs = view.knowledge.references.map(ref => settingsRecord({
         title: ref.title,
         sub: ref.path ? html `<span class="k-mono">${ref.path} · ${ref.sourceRevision?.slice(0, 7)}</span>` : '',
+        when: lastIncludedWords(use.get(`reference:${ref.id}`)),
         more: joinHtml([
             disclose('Read reference', html `<pre class="k-scode">${ref.content}</pre>`, draft?.id === ref.id),
             manage ? disclose('Edit reference', joinHtml([
@@ -59,14 +61,16 @@ export function knowledgeContextHtml(snapshot) {
         return '';
     return html `<details class="knowledge result-knowledge"><summary>Context used</summary><p class="meta">Project knowledge · version ${snapshot.revision}${snapshot.inheritedFrom === null ? '' : ` · from run #${snapshot.inheritedFrom}`}</p>${snapshot.instructions ? html `<details><summary>Instructions</summary><pre>${snapshot.instructions}</pre></details>` : html `<p>No project instructions were supplied.</p>`}${snapshot.references.map(r => html `<details><summary>${r.title}</summary>${r.path ? html `<p class="meta">${r.path} · ${r.sourceRevision}</p>` : ''}<pre>${r.content}</pre></details>`)}${snapshot.omitted.length ? html `<details><summary>Not included (${snapshot.omitted.length})</summary><ul>${snapshot.omitted.map(r => html `<li>${r.title} — ${r.reason}</li>`)}</ul></details>` : ''}</details>`;
 }
-export const MEMORY_INTRO = 'What the lead and crew read before they work. Every change keeps its history.';
-export function decisionsHtml(repo, decisions, csrf, canManage, draft, error) {
+export const MEMORY_INTRO = 'What the lead and crew read before they work. Every change keeps its history. Last included is counted in runs.';
+export function decisionsHtml(repo, decisions, csrf, canManage, draft, error, use = new Map(), afterwards = () => null) {
     const manage = canManage && !!csrf;
     const base = { repo };
     const form = (action, body, extra = {}) => postForm('/settings/knowledge/decision', body, { hidden: fields({ ...base, action, ...extra }) });
     const rows = decisions.map(d => settingsRecord({
         title: d.claim, sub: d.why, when: html `<span class="k-num">#${d.id}</span> · ${d.decidedBy} · ${d.decidedAt.slice(0, 10)}`, attrs: { id: `decision-${d.id}` },
         more: joinHtml([
+            note(lastIncludedWords(use.get(`decision:${d.id}`))),
+            afterwards(d) === null ? '' : note(afterwards(d)),
             note(`${d.sourceKind}${d.sourceRef ? ` · ${d.sourceRef}` : ''}${d.supersedes === null ? '' : ` · replaces #${d.supersedes}`}`),
             manage ? disclose('Retire', form('retire', joinHtml([
                 formRow('Why it no longer holds', null, input({ id: `decision-${d.id}-reason`, name: 'reason', attrs: { maxlength: 500, required: true, 'aria-label': 'Why it no longer holds' } }), 'wide'),
@@ -89,14 +93,30 @@ export function memorySearchHtml(repo, query, hits) {
             results,
         ]) });
 }
-export function proposalsHtml(repo, proposals, status, csrf, canManage) {
+import { NOTE_SURFACE } from './lesson-notes.js';
+export function proposalsHtml(repo, proposals, status, csrf, canManage, who = '') {
     const manage = canManage && !!csrf;
     const line = status === null ? '' : joinHtml([
         note(`${status.sessions.analyzed}/${status.sessions.total} sessions read${status.sessions.failed ? ` · ${status.sessions.failed} failed` : ''} · ${status.openGaps} open gap${status.openGaps === 1 ? '' : 's'} · Instructions ${status.instructionBytes}/${status.budgetBytes} bytes`),
         disclose('Read new sessions', joinHtml([note('Run this on this computer:'), codeLine(`toolroll memory propose --repo ${repo}`)])),
     ]);
     const decide = (p, decision, label) => postForm('/settings/knowledge/proposal', btn(label, { sm: true, variant: decision === 'accept' ? 'outline' : 'ghost', type: 'submit' }), { hidden: fields({ repo, proposal: p.id, decision }) });
-    const cards = proposals.map(p => settingsRecord({
+    // A lesson note: the facts, the failure line as output, and the person's own words in an edit box that starts as a draft.
+    const lessonNote = (p) => settingsRecord({
+        title: p.title, sub: html `<span class="k-num">#${p.id}</span> · Lesson note`,
+        more: joinHtml([
+            note(p.rationale),
+            ...p.evidence.map(ev => html `<pre class="k-scode">${ev.quote}</pre>`),
+            manage ? joinHtml([
+                postForm('/settings/knowledge/note', joinHtml([
+                    formRow('Note', 'Say it in your own words before accepting.', textarea({ id: `note-${p.id}`, name: 'claim', rows: 3, value: p.afterText, attrs: { maxlength: 240, required: true, 'aria-label': 'Note' } }), 'top'),
+                    acts(btn(`Accept as ${who}`, { sm: true, type: 'submit' })),
+                ]), { hidden: fields({ repo, proposal: p.id, decision: 'accept' }) }),
+                postForm('/settings/knowledge/note', btn('Reject', { sm: true, variant: 'ghost', type: 'submit' }), { hidden: fields({ repo, proposal: p.id, decision: 'reject' }) }),
+            ]) : '',
+        ]),
+    });
+    const cards = proposals.map(p => p.surface === NOTE_SURFACE ? lessonNote(p) : settingsRecord({
         title: p.title, sub: html `<span class="k-num">#${p.id}</span> · ${p.kind} · ${p.sessions} sessions`,
         action: manage ? html `${decide(p, 'accept', 'Accept')}${decide(p, 'reject', 'Reject')}` : '',
         more: joinHtml([
@@ -106,5 +126,53 @@ export function proposalsHtml(repo, proposals, status, csrf, canManage) {
             html `<ul class="k-note">${p.evidence.map(ev => html `<li>“${ev.quote.slice(0, 200)}” · ${ev.session.split(':')[0] ?? ''}</li>`)}</ul>`,
         ]),
     }));
-    return settingsSection({ id: 'proposals', title: 'Proposed from sessions', body: joinHtml([line, cards.length ? joinHtml(cards) : note('Nothing to review. Suggestions appear when the same mistake shows up in two sessions.')]) });
+    return settingsSection({ id: 'proposals', title: 'Proposed changes', body: joinHtml([line, cards.length ? joinHtml(cards) : note('Nothing to review. Suggestions appear when the same mistake shows up in two sessions.')]) });
+}
+const CLEANUP_TITLES = { retire: 'Retire unused', merge: 'Merge duplicates', contradiction: 'Contradiction', 'note-failing': 'Note keeps failing', restore: 'Restore', unmerge: 'Undo merge' };
+const cleanupItem = (p, item) => item.kind === 'decision' ? `Decision #${item.id} · version ${item.revision} · ${item.status}${p.titles[`decision:${item.id}`] ? ` · ${p.titles[`decision:${item.id}`]}` : ''}`
+    : item.kind === 'lesson' ? `Lesson #${item.id} · version ${item.version}` : `Reference · knowledge version ${item.revision}`;
+/** Radio choices for a proposal with no default: nothing is pre-selected. */
+const choices = (name, options) => radios({ name, legend: 'Choose one', current: '', items: options.map(([value, label]) => ({ value, label })) });
+export function cleanUpHtml(repo, proposals, manage) {
+    const form = (body, hidden) => postForm('/settings/knowledge/tidy', body, { hidden: fields({ repo, ...hidden }) });
+    const accept = (p) => {
+        const tail = Array.isArray(p.evidence['tail']) ? p.evidence['tail'] : [];
+        const decisions = p.items.flatMap(item => item.kind === 'decision' ? [item.id] : []);
+        const extra = p.kind === 'contradiction' ? joinHtml([choices('choice', [...decisions.map(id => [`keep:${id}`, `Keep #${id}, retire the other`]), ['both', 'Keep both'], ['new', 'Write a new one']]),
+            formRow('New decision', null, input({ id: `tidy-${p.id}-claim`, name: 'claim', attrs: { maxlength: 240, 'aria-label': 'New decision' } }), 'wide'), formRow('Why', null, input({ id: `tidy-${p.id}-why`, name: 'why', attrs: { maxlength: 500, 'aria-label': 'Why' } }), 'wide')])
+            : p.kind === 'note-failing' ? joinHtml([choices('choice', [['rewrite', 'Rewrite it'], ['retire', 'Retire it']]),
+                formRow('New note', null, input({ id: `tidy-${p.id}-claim`, name: 'claim', attrs: { maxlength: 240, 'aria-label': 'New note' } }), 'wide'), formRow('Why', null, input({ id: `tidy-${p.id}-why`, name: 'why', attrs: { maxlength: 500, 'aria-label': 'Why' } }), 'wide')])
+                : (p.kind === 'restore' || p.kind === 'unmerge') && tail.length > 0 ? choices('choice', [['retire', `Retire ${tail.map(id => `#${id}`).join(', ')}`], ['keep', 'Keep both active']])
+                    : p.kind === 'merge' ? formRow('Merged decision', null, input({ id: `tidy-${p.id}-claim`, name: 'claim', value: p.afterText ?? '', attrs: { maxlength: 240, 'aria-label': 'Merged decision' } }), 'wide') : '';
+        return form(joinHtml([extra, acts(btn('Accept', { sm: true, type: 'submit' }))]), { action: 'accept', proposal: p.id });
+    };
+    const rows = proposals.map(p => settingsRecord({
+        title: CLEANUP_TITLES[p.kind], sub: p.rationale,
+        more: joinHtml([
+            html `<ul class="k-note">${p.items.map(item => html `<li>${cleanupItem(p, item)}</li>`)}</ul>`,
+            manage ? joinHtml([accept(p), form(btn('Reject', { sm: true, variant: 'ghost', type: 'submit' }), { action: 'reject', proposal: p.id })]) : '',
+        ]),
+    }));
+    return settingsSection({ id: 'clean-up', title: 'Clean up', body: joinHtml([
+            rows.length ? joinHtml(rows) : note('Nothing to clean up.'),
+            manage ? form(acts(btn('Clean up', { sm: true, type: 'submit' })), { action: 'propose' }) : '',
+        ]) });
+}
+/** On a saved version's page: the references that aren't in current knowledge, each back as a new version. */
+export function referenceRestoreHtml(repo, revision, references, manage) {
+    if (!manage || references.length === 0)
+        return '';
+    return settingsSection({ id: 'reference-restore', title: 'References no longer in use', body: joinHtml(references.map(ref => settingsRecord({ title: ref.title,
+            action: postForm('/settings/knowledge/tidy', btn('Restore', { sm: true, variant: 'ghost', type: 'submit' }), { hidden: fields({ repo, action: 'reference', target: ref.id, revision }) }) }))) });
+}
+/** Retired decisions, undoable merges and disabled lessons, each with its way back. */
+export function restoreHtml(repo, retired, merges, lessons, manage) {
+    if (retired.length + merges.length + lessons.length === 0)
+        return '';
+    const form = (label, action, target) => manage ? postForm('/settings/knowledge/tidy', btn(label, { sm: true, variant: 'ghost', type: 'submit' }), { hidden: fields({ repo, action, target }) }) : '';
+    return html `<details class="knowledge frame"><summary class="frame-head">Retired</summary><div class="frame-panel">${joinHtml([
+        ...merges.map(m => settingsRecord({ title: `Merge of ${m.predecessors.map(id => `#${id}`).join(', ')} into #${m.successor}`, action: form('Undo merge', 'unmerge', m.merge) })),
+        ...retired.map(d => settingsRecord({ title: d.claim, sub: html `<span class="k-num">#${d.id}</span> · ${d.status}`, action: form('Restore', 'restore', d.id) })),
+        ...lessons.map(l => settingsRecord({ title: l.observation, sub: 'Lesson', action: form('Use again', 'readopt', l.id) })),
+    ])}</div></details>`;
 }

package/dist/laptop-background.d.ts

@@ -51,6 +51,8 @@ export type LaptopSeams = {
     host?: string;
     healthTimeoutMs?: number;
     exitTimeoutMs?: number;
+    /** The build an installed unit would start, from its entry point (default: the version in that package's package.json). */
+    buildAt?: (entry: string) => string | null;
     /** The foreground `up` this invoker started (the terminal UI's child): its controller's pid, and how to start it again. */
     foreground?: {
         controllerPid: number;
@@ -168,4 +170,18 @@ export declare function backgroundInstalled(seams?: LaptopSeams): boolean;
  * `up` beside it — and prove the console it runs live. Our own label only.
  */
 export declare function startInstalledService(store: Store, databaseFile: string, seams?: LaptopSeams): Promise<AttachProof>;
+export type BuilderRestart = {
+    restarted: true;
+} | {
+    restarted: false;
+    reason: "unsupported" | "not-installed" | "not-wanted" | "paused" | "running" | "unproven" | "disabled" | "identity" | "attempts" | "failed";
+    message?: string;
+};
+/**
+ * Start our own service again, by Toolroll alone, only when a person's recorded wish is to run, nothing is stopping or
+ * updating, the old process is proved gone, what would start is what ran, and it isn't over its attempts. Every other
+ * answer leaves the need with one label, "Start the builder". This never enables a disabled label, which is what sets it
+ * apart from `startService`: a person's own yes.
+ */
+export declare function restartOwnBuilder(store: Store, databaseFile: string, seams?: LaptopSeams, now?: Date): Promise<BuilderRestart>;
 export {};