refactor(comments): trim verbose comments across the codebase

e2e/compaction-atomicity.test.ts

@@ -42,8 +42,7 @@ function mapArchive(dir: string) {
   });
 }
 
-// A turn sequence carrying one tool_call/tool_result pair — the shape the
-// completeness gate checks for evidence coverage.
+// One tool_call/tool_result pair — the shape the completeness gate checks for coverage.
 function toolExchangeHistory(): ConversationTurn[] {
   return [
     turn("fact-a"),
@@ -182,9 +181,8 @@ describe("compaction atomicity", () => {
     const adopted1 = await first.apply(history1, ctx);
     expect(adopted1.record.reason).toBe("compact");
 
-    // The new spine never passes through inbound admission, so adoption must
-    // leave it in the archive — otherwise the next fold rejects it as
-    // uncovered (a repaired spine is never echoed verbatim).
+    // The new spine never passes inbound admission, so adoption must leave
+    // it in the archive.
     const handoffs = (await archive.listOccurrences()).filter(
       (occurrence) => occurrence.provenance === "compaction-handoff",
     );

e2e/compaction-baseline.test.ts

@@ -85,10 +85,9 @@ async function snapshot(session: IntegrationSession) {
   return { hash: createHash("sha256").update(raw).digest("hex"), turns };
 }
 
-// CL-8744: folded-away evidence lives in the fat handoff file, not the live
-// prompt. Every fold overwrites the same stable latest key (a per-fold key
-// would make each spine novel, which the completeness gate must reject), so
-// one read behind the spine's pointer recovers the whole cumulative record.
+// Folded-away evidence lives in the handoff file behind the spine's pointer:
+// every fold overwrites the same latest key, so one read recovers the whole
+// cumulative record.
 async function readHandoffFile(
   session: IntegrationSession,
   key: string,
@@ -265,8 +264,7 @@ describe("integration — compaction mechanics baseline", () => {
           skipPermissions: true,
           reactorGated: false,
         }),
-        // CL-9007: pin a tiny tail budget so the calibrated growth volumes
-        // still fold instead of fitting the default live tail.
+        // Pin a tiny tail budget so the calibrated growth volumes still fold.
         compactionShape: { tailBudgetTokens: 10 },
         compactionCompletion: async (turns) => {
           const context = turns
@@ -384,14 +382,11 @@ describe("integration — compaction mechanics baseline", () => {
           folds.push(observation);
           expect(qualifyingFold(observation)).toBe(true);
           expect(summaryInputs.length).toBe(fold + 1);
-          // CL-8744: the live prompt carries only the thin spine plus its
-          // pointer — the spine's cumulative evidence echo keeps every
-          // required marker inference-visible, so the responder still
-          // recovers the full set from the reply itself.
+          // The live prompt carries only the thin spine plus its pointer; the
+          // cumulative evidence echo keeps markers recoverable from the reply.
           const recovered = recoverEvidence(reply);
           expect(recovered).toEqual([...REQUIRED_EVIDENCE]);
-          // The full structured record lives in the fat handoff file behind
-          // the spine's pointer: every section present, every marker verbatim.
+          // The full record lives in the handoff file behind the spine's pointer.
           const handoffKey = spineHandoffKey(after.turns);
           expect(handoffKey).toBe(HANDOFF_LATEST_KEY);
           const fileText = await readHandoffFile(session, handoffKey as string);
@@ -414,9 +409,8 @@ describe("integration — compaction mechanics baseline", () => {
               .map((fact) => fact.id)
               .sort(),
           ).toEqual(REQUIRED_EVIDENCE.map((fact) => fact.id).sort());
-          // The live spine may grow with newly discovered tokens; dropped prior
-          // spines are adopted into the evidence archive so the completeness
-          // gate still certifies the fold (qualifyingFold above).
+          // Dropped prior spines are adopted into the archive so the
+          // completeness gate still certifies the fold.
           spineTexts.push(spineText(after.turns));
           expect(spineTexts[fold]?.startsWith(COMPACTED_PREFIX)).toBe(true);
           expect(spineTexts[fold]).toContain("Handoff:");

e2e/compaction-read-paging.test.ts

@@ -15,8 +15,7 @@ const WireRequest = type({
   messages: type({ role: "string", content: "unknown" }).array(),
 });
 
-// claude-integration resolves a 200k context window, so a 200k-token usage
-// frame reports over the 120k auto-compaction threshold.
+// A 200k-token usage frame clears the 120k auto-compaction threshold.
 const TRIGGER_USAGE = {
   input: 200_000,
   output: 1,
@@ -41,16 +40,12 @@ function logLines(count: number): string {
 async function openFoldSession(): Promise<E2ESession> {
   const session = await openE2ESession({
     permissionGate: e2ePermissionGate(),
-    // A tiny tail budget keeps the fold honest: the default 2500-token
-    // budget would absorb this small scenario into the live tail and the
-    // compactor would correctly no-op.
-    // Budget fits the paged read windows in the live tail but not the bulky
-    // pad turns, so the fold still fires.
+    // A tiny tail budget keeps this small scenario from fitting the live tail;
+    // the budget fits the read windows but not the bulky pad turns, so the
+    // fold fires.
     compactionShape: { tailBudgetTokens: 500 },
-    // A short handoff, not a prompt echo: complete() receives the summarizer
-    // prompt turns, and a 4k echo gets truncated off the verify-repair tail
-    // so the fold aborts. This scenario asserts on kept live bodies, not the
-    // summary text.
+    // A short handoff keeps the fold from aborting on a 4k echo; assertions
+    // target the kept live bodies, not the summary text.
     compactionCompletion: async () =>
       "Goal: page through var/log/big.log. Next: keep reading remaining windows.",
   });
@@ -84,12 +79,9 @@ async function padTurns(session: E2ESession, count: number): Promise<void> {
 }
 
 /**
- * One user turn that pages through the log and folds mid-turn: each scripted
- * read reply reports low usage so the governor stays disarmed until the
- * final call, whose 200k usage frame arms the tool.done intercept — the
- * compact+emit batch runs, the delivered continuation re-enters inference,
- * and the last scripted reply answers the post-fold request. Keeping every
- * read inside this turn is what lands the kept windows in the live tail.
+ * One user turn that pages through the log and folds mid-turn: reads report
+ * low usage until the final 200k frame arms the compact+emit batch; keeping
+ * every read in this turn lands the kept windows in the live tail.
  */
 async function readChainThenFold(
   session: E2ESession,
@@ -130,9 +122,8 @@ describe("e2e — automatic compaction keeps the read resume recipe", () => {
         );
         expect(spines).toHaveLength(1);
 
-        // Each kept window still carries its own body and resume recipe —
-        // the summary echoed turn text only, so these strings can only come
-        // from the live kept results.
+        // Each kept window still carries its own body and resume recipe — the
+        // summary echoed turn text only, so these strings come from the live results.
         expect(body).toContain("Use offset=40 to continue");
         expect(body).toContain("Use offset=60 to continue");
         expect(body).toContain("log line 25");
@@ -160,8 +151,7 @@ describe("e2e — automatic compaction keeps the read resume recipe", () => {
 
         const body = await lastRequestBody(session);
         expect(body).toContain(COMPACTED_PREFIX);
-        // The newest copy of the identical window keeps its body and notice;
-        // exactly one older duplicate renders as a stub.
+        // The newest duplicate stays whole; exactly one older one renders as a stub.
         expect(body).toContain("Use offset=40 to continue");
         const stubs = body.match(/omitted from context/g) ?? [];
         expect(stubs).toHaveLength(1);

e2e/crash-finalize.test.ts

@@ -43,13 +43,8 @@ describe("integration — crash finalizes run.json", () => {
       const raw = readFileSync(runJsonPath, "utf8");
       const state = JSON.parse(raw) as RunState;
 
-      // The fixture also parks two unawaited straggler "running" snapshot
-      // writes behind a test-only gate (setTestWriteGate) that it releases
-      // only after the crash handler has flipped isCrashed(), guaranteeing
-      // both are still queued — not dispatched to the kernel — at that
-      // moment. Without the isCrashed() guard in saveState
-      // (src/session/state.ts), one of those would win the rename() race
-      // once released and this would read back "running".
+      // The fixture parks two "running" writes behind setTestWriteGate until
+      // isCrashed() flips, so no straggler rename() wins over "crashed".
       expect(state.status).toBe("crashed");
       expect(state.finishedAt).toBeGreaterThan(0);
       expect(state.error).toContain("simulated crash");
@@ -89,10 +84,7 @@ describe("integration — crash finalizes run.json", () => {
       expect(exitCode).toBe(1);
       expect(stderr).toContain("uncaughtException: Error: simulated crash");
 
-      // The bug this pins: the outgoing session's terminal "done" write must
-      // not clear the active-run handle, or the crash below finds it null
-      // and never writes a crashed record for the session actually running
-      // at the time of the crash.
+      // The terminal "done" write must not clear the active-run handle, or the crash writes no record.
       const outgoingRunJsonPath = join(
         sessionDir(cwd, sessionId, home),
         "run.json",
@@ -143,16 +135,10 @@ describe("integration — crash finalizes run.json", () => {
         "uncaughtException: Error: simulated crash during run-end write",
       );
 
-      // The bug this pins: finalizeRunState used to clear the active-run
-      // handle only after its own saveState write resolved. With the
-      // run-end write parked mid-flight (this fixture's gate never
-      // releases), the handle stayed live for the entire window, so the
-      // crash handler saw a live run and wrote a "crashed" record via
-      // saveCrashState — which bypasses the gate — clobbering what should
-      // have been a clean finish. Clearing the handle before the await
-      // closes that window: the crash handler finds no active run and
-      // writes nothing, so the last write to land is the one from the
-      // initial saveState above ("running"), never "crashed".
+      // finalizeRunState used to clear the active-run handle only after its
+      // saveState write resolved; the crash handler then saw a live run and
+      // wrote "crashed" via saveCrashState, clobbering the clean finish.
+      // Clearing the handle before the await closes that window.
       const runJsonPath = join(stdout.trim(), "run.json");
       const raw = readFileSync(runJsonPath, "utf8");
       const state = JSON.parse(raw) as RunState;

e2e/credential-recovery.test.ts

@@ -74,10 +74,8 @@ describe("e2e — credential recovery switches the live source", () => {
             material: { secret: "backup-key" },
           },
         },
-        // The production Corbits policy with a stubbed OAuth refresh —
-        // the refresh succeeds, the retry is armed, the second 401 is
-        // terminal. A real scheduler lets the zero-delay retry actually
-        // elapse; the harness scheduler is inert.
+        // Production retry policy with a stubbed OAuth refresh; a real
+        // scheduler lets the zero-delay retry actually elapse.
         retryPolicy: createCorbitsRetryPolicy({
           providerId: PRIMARY.id,
           refreshCredential: async () => undefined,
@@ -145,9 +143,8 @@ describe("e2e — credential recovery switches the live source", () => {
           "no backup alternative offered",
         );
 
-        // Phase 2: the real switch path — setSources on the live agent,
-        // arm on the real director, deliver the continuation, then pump
-        // the replayed turn through the backup provider.
+        // Phase 2: switch sources on the live agent, arm the continuation,
+        // deliver, and pump the replayed turn through the backup provider.
         const pump = session.harness.run({ wallClockBudgetMs: Infinity });
         const acceptance = applyCredentialRecoverySelection({
           state: recovery,
@@ -180,8 +177,7 @@ describe("e2e — credential recovery switches the live source", () => {
         const backupHits = requests.filter((r) =>
           RequestURL.assert(r).url.includes(BACKUP_HOST),
         );
-        // Two primary hits prove the refresh→retry path ran: an inert or
-        // api-key provenance would terminal-fail after the first 401.
+        // Two primary hits prove the refresh→retry path ran.
         expect(primaryHits).toHaveLength(2);
         expect(backupHits).toHaveLength(1);
         // The replay carries the original operator message, not a synthetic

e2e/git-push-scoped.test.ts

@@ -1,8 +1,7 @@
 /**
- * `bin/git-push-scoped` must never write to global git config: not on a
- * normal push, not when two pushes race, and not when one is killed
- * mid-flight. Every test runs against an isolated HOME/GIT_CONFIG_GLOBAL
- * so a bug here can never touch the real machine's config.
+ * bin/git-push-scoped must never write global git config, even under races
+ * or mid-flight kills; every test runs with an isolated HOME so a bug can
+ * never touch the real machine's config.
  */
 
 import { spawn } from "node:child_process";
@@ -71,8 +70,7 @@ beforeEach(() => {
     "[user]\n\tname = Sentinel\n\temail = sentinel@example.com\n",
   );
 
-  // Stub `gh` on PATH so the script's `command -v gh` check passes without
-  // depending on a real GitHub CLI install or credentials.
+  // Stub gh on PATH so the command -v gh check passes without a real install.
   fakeBinDir = join(root, "fakebin");
   mkdirSync(fakeBinDir);
   const ghStub = join(fakeBinDir, "gh");
@@ -126,8 +124,7 @@ describe("git-push-scoped", () => {
     const remote = initBareRemote("remote-slow.git");
     const work = initWorkingRepo("work-slow", remote);
 
-    // A pre-receive hook that sleeps gives us a reliable window to kill the
-    // push while it is in flight.
+    // A sleeping pre-receive hook gives a reliable window to kill the push in flight.
     const hookPath = join(remote, "hooks", "pre-receive");
     writeFileSync(hookPath, "#!/usr/bin/env bash\nsleep 5\n");
     chmodSync(hookPath, 0o755);
@@ -144,8 +141,7 @@ describe("git-push-scoped", () => {
       child.on("exit", (code, signal) => resolve({ code, signal }));
     });
 
-    // The pre-receive hook sleeps 5s, so the push is still in flight here;
-    // kill it well inside that window.
+    // The hook sleeps 5s, so the push is still in flight; kill it inside that window.
     await new Promise((resolve) => setTimeout(resolve, 30));
     child.kill("SIGKILL");
     const { signal } = await exited;

e2e/harness.ts

@@ -1,14 +1,12 @@
 /**
  * End-to-end scenario harness: full agent-loop runs against the production
- * stack — live tool dispatch, chat director, posix tools plus permission
- * middleware, git-backed context store, production compactor — with only
- * inference scripted by @intx/inference-testing. `e2e/integration-harness.ts` owns
- * the assembly; this layer adds fixture-repo seeding and small scenario
- * conveniences so e2e files stay declarative.
+ * stack (tools, director, permissions, context store, compactor) with only
+ * inference scripted by @intx/inference-testing.
  *
- * Deliberate boundary: no TUI and no process spawn here — a scenario drives
- * `agent.send` through the same seam the runners use. PTY-level coverage is
- * a separate layer and out of scope for this harness.
+ * Layer split: `integration-harness.ts` owns the assembly; this file adds
+ * fixture-repo seeding and scenario conveniences so e2e files stay
+ * declarative. No TUI or process spawn: scenarios drive `agent.send` through
+ * the seam the runners use.
  */
 
 import { cpSync, mkdirSync, writeFileSync } from "node:fs";
@@ -46,15 +44,14 @@ export type E2ESession = IntegrationSession;
 
 export interface OpenE2ESessionOpts extends OpenIntegrationSessionOpts {
   /**
-   * Name of a `fixtures/<name>` directory copied into the session cwd
-   * before the scenario runs. `node_modules` and `.git` are skipped: fixture
-   * deps install into the real repo, and the repo marker belongs to the
-   * `git` option, not to whatever the fixture happens to contain.
+   * Name of a `fixtures/<name>` directory copied into the session cwd.
+   * `node_modules` and `.git` are skipped: fixture deps install into the
+   * real repo, and the repo marker belongs to the `git` option.
    */
   fixture?: string;
   /**
-   * Initialize the session cwd as a git repository. Defaults to true — a
-   * "fixture-repo run" should look like one to worktree-aware permission
+   * Initialize the session cwd as a git repository; defaults to true.
+   * A fixture-repo run should look like one to worktree-aware permission
    * and trust checks. Pass false only when the scenario asserts on
    * non-repo behavior.
    */
@@ -85,7 +82,7 @@ export function e2ePermissionGate(): PermissionGate {
   });
 }
 
-/** Write (or overwrite) a file inside the session cwd mid-scenario. */
+/** Write a file inside the session cwd mid-scenario. */
 export function seedFile(
   session: E2ESession,
   relativePath: string,
@@ -100,16 +97,15 @@ export interface OperatorTurn {
   /** The exact message sent — recovery flows key on its identity. */
   message: InboundMessage;
   events: ReactorEmittedEvent[];
-  /** The raw send result — a terminally-failed turn is not asserted here. */
+  /** The raw send result; failures are returned, not thrown. */
   outcome: SendOutcome | unknown;
 }
 
 /**
  * Send one operator message and pump the harness until the send settles,
- * whatever the outcome. Unlike runUntilDone this never asserts a reply —
- * scenarios that script a terminal failure (credential recovery, provider
- * outage) need the failure's event stream plus the send outcome, not a
- * thrown expectation.
+ * whatever the outcome. Never asserts a reply (unlike `runUntilDone`):
+ * terminal-failure scenarios need the failure's event stream plus the send
+ * outcome.
  */
 export async function sendOperatorTurn(
   session: E2ESession,
@@ -130,10 +126,9 @@ export async function sendOperatorTurn(
   };
   const events: ReactorEmittedEvent[] = [];
   const continuationGate = createContinuationGate();
-  // The collector outlives the send: recovery scenarios deliver a follow-up
-  // turn after this returns, and its events keep appending to `events`. The
-  // catch mirrors runUntilSuspended — a stream error must not become an
-  // unhandled rejection in the shared test process.
+  // The collector outlives the send so recovery follow-up events keep
+  // appending; the catch keeps stream errors from becoming unhandled
+  // rejections in the shared test process.
   void (async () => {
     for await (const event of session.agent.stream()) {
       events.push(event);
@@ -161,9 +156,9 @@ export interface ScriptedReply {
 
 /**
  * Queue one model response per inference request, in order — the common
- * "model calls tools, then answers" scenario spine. Thin sugar over
- * `scenario.replyOnce`; reach for `whenRequestBodyMatches`/`createStream`
- * directly when a reply must key on request content or timing.
+ * "model calls tools, then answers" spine. Use
+ * `whenRequestBodyMatches`/`createStream` directly when a reply must key on
+ * request content or timing.
  */
 export function scriptReplies(
   session: E2ESession,