From 2cfdf45cad4339b9a83fa48bc4f05d216e402fd2 Mon Sep 17 00:00:00 2001
From: Sawyer Cutler <sawyer@dirtroad.dev>
Date: Mon, 24 Aug 2026 08:46:43 -0700
Subject: [PATCH] Clean up stale/verbose comments in src/subagent

Comment-only pass: removes ticket-number references, deletes or corrects
comments asserting guarantees the code no longer provides (e.g. a stale
pruneCompleted exemption claim in session-store.ts, an inaccurate
"never capped" claim about fleetRecords in agent-fleet.ts), and trims
narrative comments down to their WHY. No logic changes; no CHANGELOG entry.
---
 src/subagent/agent-fleet.ts              |  42 +++----
 src/subagent/authority.test.ts           |   4 +-
 src/subagent/authority.ts                |   7 +-
 src/subagent/brief-dispatch.ts           |   2 +-
 src/subagent/dispose.ts                  |   2 +-
 src/subagent/fleet-report.ts             |   6 +-
 src/subagent/followup-live-agent.test.ts |   4 +-
 src/subagent/index.test.ts               |   4 +-
 src/subagent/intervention-log.test.ts    |   2 +-
 src/subagent/intervention-log.ts         |   2 +-
 src/subagent/lifecycle-tools.ts          |   4 +-
 src/subagent/nudge-director.ts           |   8 +-
 src/subagent/report.ts                   |   2 +-
 src/subagent/run-authority.test.ts       |  10 +-
 src/subagent/run.ts                      | 136 ++++++++++-------------
 src/subagent/shell-evidence.test.ts      |   2 +-
 src/subagent/shell-evidence.ts           |   2 +-
 src/subagent/submit-result.ts            |   2 +-
 src/subagent/task-tool.ts                |  22 ++--
 src/subagent/thrash.test.ts              |   4 +-
 src/subagent/thrash.ts                   |   4 +-
 src/subagent/tool-preview.ts             |   2 +-
 src/subagent/trace-reader.ts             |   2 +-
 src/subagent/trace-tool.ts               |   6 +-
 src/subagent/types.ts                    |  16 +--
 25 files changed, 141 insertions(+), 156 deletions(-)

diff --git a/src/subagent/agent-fleet.ts b/src/subagent/agent-fleet.ts
index 49a9638e3..7cfdb7fa2 100644
--- a/src/subagent/agent-fleet.ts
+++ b/src/subagent/agent-fleet.ts
@@ -1,6 +1,6 @@
 /**
- * spawn_agent / wait_agents (CL-6942): the non-blocking half of fleet
- * dispatch, split out of `task()`'s fused spawn+wait.
+ * spawn_agent / wait_agents: the non-blocking half of fleet dispatch,
+ * split out of `task()`'s fused spawn+wait.
  *
  * `task()` (task-tool.ts) remains the fused, blocking primitive and is
  * unchanged. These two verbs let an orchestrator start several workers in
@@ -395,9 +395,9 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
         description,
         agentId: resolved.directorId,
         brief,
-        // CL-6943: a spawn_agent worker's session survives a clean
-        // completion instead of being torn down — close_agent (or
-        // resume_agent, transitively) governs it from here on.
+        // A spawn_agent worker's session survives a clean completion instead
+        // of being torn down — close_agent (or resume_agent, transitively)
+        // governs it from here on.
         retained: true,
       });
       deps.fleetRecords.register(session.id);
@@ -446,8 +446,8 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
         ...(resolved.capabilities !== undefined ? { capabilities: resolved.capabilities } : {}),
         systemPromptRole: resolved.systemPromptRole,
         directorId: resolved.directorId,
-        // CL-6943: keep the session open after a clean completion, and hand
-        // the store a bounded close for close_agent to call later.
+        // Keep the session open after a clean completion, and hand the
+        // store a bounded close for close_agent to call later.
         persist: true,
         onAgentReady: ({ close, interrupt, followup }) => {
           deps.sessions.registerClose(session.id, close);
@@ -458,27 +458,27 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
       };
 
       // Fire and forget: this handler must return before the worker finishes.
-      // fleetRecords (never capped) is the durable source of truth wait_agents
-      // reads from; deps.sessions.complete/fail is still called for the TUI's
-      // benefit, but only after fleetRecords already has the result, and
-      // fleetRecords is written before it so the synchronous subscribe
-      // notification fired by complete()/fail() always sees the up-to-date
+      // fleetRecords is the durable source of truth wait_agents reads from
+      // (see the module doc for its own cap/eviction policy);
+      // deps.sessions.complete/fail is still called for the TUI's benefit,
+      // but only after fleetRecords already has the result, so the
+      // synchronous subscribe notification always sees the up-to-date
       // record.
       deps
         .run(params)
         .then((result) => {
           if (childCtl.signal.aborted) return;
-          // CL-6997: interrupt_agent already flipped this session to
-          // "interrupted" synchronously (session-store.interruptOne) — do
-          // not let the settling promise's normal bookkeeping overwrite
-          // that with a "completed" status.
+          // interrupt_agent already flipped this session to "interrupted"
+          // synchronously (session-store.interruptOne) — do not let the
+          // settling promise's normal bookkeeping overwrite that with a
+          // "completed" status.
           if (result.interrupted === true) return;
           deps.fleetRecords.resolve(session.id, result.report);
-          // CL-7001: result.agentRetained is only true on run.ts's clean-
-          // completion path when persist actually skipped teardown — a
-          // deadline/cancel salvage resolves through the same promise but
-          // always disposed its agent first, so the store must not treat it
-          // as resumable just because retained:true was requested at spawn.
+          // result.agentRetained is only true on run.ts's clean-completion
+          // path when persist actually skipped teardown — a deadline/cancel
+          // salvage resolves through the same promise but always disposed
+          // its agent first, so the store must not treat it as resumable
+          // just because retained:true was requested at spawn.
           deps.sessions.complete(session.id, result.report, {
             agentRetained: result.agentRetained === true,
           });
diff --git a/src/subagent/authority.test.ts b/src/subagent/authority.test.ts
index cf38fa6ef..f38ca8df9 100644
--- a/src/subagent/authority.test.ts
+++ b/src/subagent/authority.test.ts
@@ -11,10 +11,10 @@ describe("assertTierMayMountFleetVerb", () => {
     expect(() => assertTierMayMountFleetVerb("leaf", "task")).toThrow(FleetAuthorityError);
     expect(() => assertTierMayMountFleetVerb("leaf", "search_agents")).toThrow(FleetAuthorityError);
     expect(() => assertTierMayMountFleetVerb("leaf", "spawn_agent")).toThrow(FleetAuthorityError);
-    // CL-6943: the reusable-session verbs are gated the same way.
+    // The reusable-session verbs are gated the same way.
     expect(() => assertTierMayMountFleetVerb("leaf", "close_agent")).toThrow(FleetAuthorityError);
     expect(() => assertTierMayMountFleetVerb("leaf", "resume_agent")).toThrow(FleetAuthorityError);
-    // CL-6997: interrupt_agent / followup_task are gated the same way.
+    // Interrupt_agent / followup_task are gated the same way.
     expect(() => assertTierMayMountFleetVerb("leaf", "interrupt_agent")).toThrow(
       FleetAuthorityError,
     );
diff --git a/src/subagent/authority.ts b/src/subagent/authority.ts
index 1d4e3ea16..42e8fc465 100644
--- a/src/subagent/authority.ts
+++ b/src/subagent/authority.ts
@@ -1,5 +1,5 @@
 /**
- * Fleet authority (CL-6941): the runtime boundary between the three tiers.
+ * Fleet authority: the runtime boundary between the three tiers.
  *
  * Tier enforcement lives here and at the tool-mount point in run.ts — never
  * in a prompt. This module owns two checks:
@@ -93,9 +93,8 @@ function isDescendant(
  * No verb in this codebase currently lets one live agent target another
  * (`task` only spawns; it never addresses an existing session), so the
  * subtree rule below is exercised only by authority.test.ts — it is not
- * enforced at runtime yet. It exists now so CL-6942 (split spawn from wait)
- * and CL-6944 (send_input steering) — the first two verbs that make one
- * agent addressable by another — can call it from day one instead of
+ * enforced at runtime yet. It exists now so future verbs that make one
+ * agent addressable by another can call it from day one instead of
  * inventing their own check. Until one of those wires a call site here, do
  * not describe this rule as enforced; only assertTierMayMountFleetVerb is.
  *
diff --git a/src/subagent/brief-dispatch.ts b/src/subagent/brief-dispatch.ts
index d2c1cdac1..5fdf698af 100644
--- a/src/subagent/brief-dispatch.ts
+++ b/src/subagent/brief-dispatch.ts
@@ -1,5 +1,5 @@
 /**
- * Parent-side re-dispatch bookkeeping for task briefs (CL-4343 + CL-5203).
+ * Parent-side re-dispatch bookkeeping for task briefs.
  *
  * This module tracks how often the *parent* re-spawns the same brief so
  * salvage outcomes can be classified per-fingerprint (successful completes
diff --git a/src/subagent/dispose.ts b/src/subagent/dispose.ts
index 377e1c692..20dd5931e 100644
--- a/src/subagent/dispose.ts
+++ b/src/subagent/dispose.ts
@@ -31,7 +31,7 @@ export function isSubAgentCancelError(err: unknown, signal?: AbortSignal): boole
 export const SUBAGENT_SPAWN_DRAIN_MS = 2_000;
 
 /**
- * Bounded cleanup deadline for close_agent (CL-6943): a wedged descendant's
+ * Bounded cleanup deadline for close_agent: a wedged descendant's
  * teardown is abandoned (not awaited further), not a reason to hang the
  * caller.
  */
diff --git a/src/subagent/fleet-report.ts b/src/subagent/fleet-report.ts
index 4353a7a40..392b076be 100644
--- a/src/subagent/fleet-report.ts
+++ b/src/subagent/fleet-report.ts
@@ -6,7 +6,7 @@
  * cannot keep: a lane failed or went quiet, and the single moment the fleet runs
  * dry. Per-lane "done — summary" walls are intentionally never printed — they
  * restate the strip and the parent and turn the transcript into a second
- * status log (CL-5846).
+ * status log.
  *
  * Pure and stateless per call — the caller keeps the returned watch and hands
  * it back on the next observation. No painting, no store access.
@@ -175,7 +175,7 @@ export function observeFleet(
 
     // A lane going quiet is no longer emitted to the transcript: the single
     // agents-panel rollup row carries the quiet count instead, so a stalled
-    // fleet stops producing "went quiet" walls (CL-5846). stallReported is
+    // fleet stops producing "went quiet" walls. stallReported is
     // still tracked internally so the strip does not flap.
   }
 
@@ -184,7 +184,7 @@ export function observeFleet(
 
   // Board owns live lanes. Parent prose owns success narratives. Transcript
   // only: fail/stall while work is still running, or one dry-fleet tally.
-  // Never per-lane "done — summary" walls (CL-5846).
+  // Never per-lane "done — summary" walls.
   if (wentDry) {
     return {
       watch,
diff --git a/src/subagent/followup-live-agent.test.ts b/src/subagent/followup-live-agent.test.ts
index c589c1eed..0472b9b27 100644
--- a/src/subagent/followup-live-agent.test.ts
+++ b/src/subagent/followup-live-agent.test.ts
@@ -1,5 +1,5 @@
 /**
- * CL-6997 regression guard: lifecycle-tools.test.ts proves interrupt_agent /
+ * Regression guard: lifecycle-tools.test.ts proves interrupt_agent /
  * followup_task behave correctly against *fake registered closures* at the
  * tool/store layer — it never exercises run.ts's real wiring, where
  * `followup` calls `agent!.send()` on the same live agent object created by
@@ -82,7 +82,7 @@ function createStubAgent() {
   };
 }
 
-describe("interrupt_agent / followup_task reuse the same live agent (CL-6997)", () => {
+describe("interrupt_agent / followup_task reuse the same live agent", () => {
   test("followup after interrupt sends into the SAME agent instance — not a rebuilt one", async () => {
     const cwd = await tmpCwd();
     let constructions = 0;
diff --git a/src/subagent/index.test.ts b/src/subagent/index.test.ts
index 83ae18518..0ae42b6e2 100644
--- a/src/subagent/index.test.ts
+++ b/src/subagent/index.test.ts
@@ -284,7 +284,7 @@ describe("sub-agent stop helpers", () => {
     ).toBeNull();
   });
 
-  test("re-read pressure no longer stops a worker (CL-6936)", () => {
+  test("re-read pressure no longer stops a worker", () => {
     let thrash = EMPTY_THRASH_STATE;
     thrash = nextThrashState(thrash, [
       { type: "tool_call", name: "edit_file", arguments: { path: "a.ts" } },
@@ -608,7 +608,7 @@ describe("thrash edge cases", () => {
     expect(stop(s)).toBeNull();
   });
 
-  test("re-reading the same chunk repeatedly is not a stop (CL-6936)", () => {
+  test("re-reading the same chunk repeatedly is not a stop", () => {
     let s = EMPTY_THRASH_STATE;
     s = nextThrashState(s, [edit("big.ts")]);
     for (let i = 0; i < 8; i++) {
diff --git a/src/subagent/intervention-log.test.ts b/src/subagent/intervention-log.test.ts
index 4c16255d8..2d74db8d7 100644
--- a/src/subagent/intervention-log.test.ts
+++ b/src/subagent/intervention-log.test.ts
@@ -24,7 +24,7 @@ async function flush(): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, 10));
 }
 
-describe("intervention log (CL-6938)", () => {
+describe("intervention log", () => {
   test("records carry the shared context, the measurement, and the run state", async () => {
     const dir = await mkdtemp(join(tmpdir(), "intervention-log-"));
     const sink = createInterventionLog(
diff --git a/src/subagent/intervention-log.ts b/src/subagent/intervention-log.ts
index 5e52749f8..b6eb6990c 100644
--- a/src/subagent/intervention-log.ts
+++ b/src/subagent/intervention-log.ts
@@ -4,7 +4,7 @@
  * There was no way to tell how often a stop or nudge trigger was wrong. Every
  * threshold in the tree was set by judgment, and the tuning history is a
  * record of that not working — a grok 6/10 pair reverted as miscalibrated,
- * and a grok stall timeout reverted (CL-6938).
+ * and a grok stall timeout reverted.
  *
  * The point of this file is that a threshold change can cite data. Each record
  * carries the trigger's *measured value beside its threshold*, the identity of
diff --git a/src/subagent/lifecycle-tools.ts b/src/subagent/lifecycle-tools.ts
index d37cba9c8..68601b556 100644
--- a/src/subagent/lifecycle-tools.ts
+++ b/src/subagent/lifecycle-tools.ts
@@ -1,6 +1,6 @@
 /**
- * close_agent / resume_agent (CL-6943): the session-lifecycle half of
- * reusable worker sessions. spawn_agent/wait_agents (CL-6942) start and
+ * close_agent / resume_agent: the session-lifecycle half of
+ * reusable worker sessions. spawn_agent/wait_agents start and
  * collect workers; these two verbs let an orchestrator tear one down on
  * purpose (close_agent) or bring a retained one back for further input
  * (resume_agent), instead of every session dying the instant its turn ends.
diff --git a/src/subagent/nudge-director.ts b/src/subagent/nudge-director.ts
index d3b617816..add920355 100644
--- a/src/subagent/nudge-director.ts
+++ b/src/subagent/nudge-director.ts
@@ -107,11 +107,11 @@ export class SubAgentDirector extends DefaultDirector {
   private lastAssistantText = "";
   // Every stop and nudge is recorded with its measured value beside its
   // threshold, so a later threshold change can cite data instead of judgment
-  // (CL-6938). Defaults to a no-op: logging is diagnostic, never required.
+  //. Defaults to a no-op: logging is diagnostic, never required.
   private interventions: InterventionSink = NOOP_INTERVENTION_SINK;
-  // Structured stop-reason side channel (CL-6946 part 2): fired synchronously
-  // whenever this director force-stops, so the caller learns the reason as a
-  // typed value rather than re-parsing the forcedStopReport prose it returns.
+  // Structured stop-reason side channel: fired synchronously whenever this
+  // director force-stops, so the caller learns the reason as a typed value
+  // rather than re-parsing the forcedStopReport prose it returns.
   private onForcedStop: (reason: ForcedStopReason) => void = () => {};
 
   /** Route this leaf's stop/nudge decisions to an intervention log. */
diff --git a/src/subagent/report.ts b/src/subagent/report.ts
index d31fcf328..c66356c04 100644
--- a/src/subagent/report.ts
+++ b/src/subagent/report.ts
@@ -47,7 +47,7 @@ export interface DispatchBrief {
   successCriteria?: readonly string[];
   doNot?: readonly string[];
   reportFocus?: string;
-  /** Turn token (CL-6946) a leaf must echo back to `submit_result`. Leaf-tier dispatches only. */
+  /** Turn token a leaf must echo back to `submit_result`. Leaf-tier dispatches only. */
   turnToken?: string;
 }
 
diff --git a/src/subagent/run-authority.test.ts b/src/subagent/run-authority.test.ts
index 4229b065a..3dfbd3e9b 100644
--- a/src/subagent/run-authority.test.ts
+++ b/src/subagent/run-authority.test.ts
@@ -1,9 +1,9 @@
 /**
- * Gate-level proof for CL-6941: authority.test.ts proves the assert
- * functions throw when called directly, which is necessary but not
- * sufficient — it does not prove runSubAgent itself cannot be talked into
- * mounting a fleet verb for a caller whose tier cannot be established. These
- * tests drive runSubAgent (the real mount point) end to end.
+ * authority.test.ts proves the assert functions throw when called directly,
+ * which is necessary but not sufficient — it does not prove runSubAgent
+ * itself cannot be talked into mounting a fleet verb for a caller whose tier
+ * cannot be established. These tests drive runSubAgent (the real mount
+ * point) end to end.
  */
 
 import { describe, expect, test } from "bun:test";
diff --git a/src/subagent/run.ts b/src/subagent/run.ts
index 0db131fee..9feb03660 100644
--- a/src/subagent/run.ts
+++ b/src/subagent/run.ts
@@ -202,13 +202,11 @@ export interface SubAgentRunController {
   deadlineHit: () => boolean;
   /** Abort the run from inside, distinct from parent cancel and deadline. */
   abort: (reason: Error) => void;
-  // CL-7001: normally tears down the timer and the parent-abort forwarding
-  // listener. Pass keepParentListener:true for a run that is persisting
-  // (retained, clean completion) — otherwise a later parent abort (operator
-  // cancel/close reaching this run's own params.signal) would stop
-  // propagating into runController.signal, and closeOnAbort — which is
-  // registered on runController.signal, not the parent's — would never fire
-  // for the still-open session.
+  // Normally tears down the timer and the parent-abort forwarding listener.
+  // Pass keepParentListener:true for a run that is persisting (retained,
+  // clean completion) — otherwise a later parent abort would stop
+  // propagating into runController.signal, and closeOnAbort would never
+  // fire for the still-open session.
   dispose: (opts?: { keepParentListener?: boolean }) => void;
 }
 
@@ -312,15 +310,14 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
   });
 
   const permissionGate = params.permissionGate;
-  // Turn token (CL-6946): identifies this dispatch to submit_result so a
-  // submission survives only for the turn it was spawned under — if the
-  // orchestrator redirects/steers away, a stale submit_result call (echoing
-  // an old token) is rejected rather than silently accepted.
+  // Identifies this dispatch to submit_result so a submission survives
+  // only for the turn it was spawned under — a stale call from a redirected
+  // orchestrator (echoing an old token) is rejected.
   const turnToken = params.tier === "leaf" ? generateSessionId() : undefined;
   const submitResultState = createSubmitResultState();
   const spawnRegistry = createSubAgentSpawnRegistryPlugin();
-  // Child tools resolve spills against the child's own store first, then the
-  // parent's (CL-4323): parent tool-output:// URIs handed in the brief must
+  // Child tools resolve spills against the child's own store first, then
+  // the parent's: parent tool-output:// URIs handed in the brief must
   // remain readable after spawn, and the child's own spills stay local.
   let childBlobReader: BlobReader | undefined;
   const sessionBlobReader = createCompositeBlobReader(() => childBlobReader, params.getBlobReader);
@@ -341,12 +338,12 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
   let streamPromise: Promise<void> | undefined;
   let closeOnAbort: (() => void) | undefined;
   // Set only on the clean-completion return path; read by the finally block
-  // to decide whether a persisted session's teardown is skipped (CL-6943).
+  // to decide whether a persisted session's teardown is skipped.
   let turnSucceeded = false;
-  // CL-6997: set only on the interrupt_agent path (a dedicated signal fired
-  // by the `interrupt` handle below, never runController) — the finally
-  // block skips teardown here too, exactly like a persisted clean success,
-  // so the agent and its workdir lock stay live for a later followup_task.
+  // Set only on the interrupt_agent path (a dedicated signal fired by the
+  // `interrupt` handle below, never runController) — the finally block
+  // skips teardown here too, so the agent and its workdir lock stay live
+  // for a later followup_task.
   let interruptedKeepAlive = false;
   // Scoped to this run's `agent.send()` call only. Firing it rejects that
   // one send's promise (per Agent.send's documented signal option) without
@@ -448,8 +445,8 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
       }),
     ];
 
-    // submit_result (CL-6946): typed reporting channel, Tier 3 leaves only.
-    // Gated by the existing tier machinery — never invent a parallel check.
+    // Typed reporting channel, Tier 3 leaves only. Gated by the existing
+    // tier machinery — never invent a parallel check.
     if (params.tier === "leaf") {
       tools = [
         ...tools,
@@ -473,14 +470,10 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
     // the prompt. Nested dispatch always forbids further orchestration so the
     // tree bottoms out after one hop.
     if (params.orchestrator === true) {
-      // Tier enforcement at the mount point (CL-6941), not the prompt: FAILS
-      // CLOSED. The caller (task-tool.ts) resolves orchestratorTier from
-      // either the closed DirectorPackage.tier or an explicit
-      // AgentProfile.tier opt-in; an unresolved tier defaults to "leaf" here,
-      // not to "skip the check" — a caller that cannot be identified must be
-      // denied, never silently trusted. This is what stops a project/plugin
-      // AgentProfile with orchestrator: true from mounting task/search_agents
-      // just because it is outside the closed director set.
+      // Tier enforcement at the mount point, not the prompt, fails closed:
+      // an unresolved tier defaults to "leaf" rather than skipping the check,
+      // so an AgentProfile outside the closed director set cannot mount
+      // task/search_agents just by setting orchestrator: true.
       const tier = params.orchestratorTier ?? "leaf";
       for (const verb of [
         "task",
@@ -552,11 +545,11 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
           getNodes: () => nd.sessions?.list() ?? [],
         }),
       ];
-      // spawn_agent/wait_agents (CL-6942) need a session store as their
-      // mailbox; reuse the orchestrator's if it has one, else give this
-      // install its own. fleetRecords is a small never-capped map for
-      // terminal results the session store's display cap would otherwise
-      // evict before wait_agents collects them (see agent-fleet.ts).
+      // spawn_agent/wait_agents need a session store as their mailbox;
+      // reuse the orchestrator's if it has one, else give this install its
+      // own. fleetRecords holds terminal results the session store's
+      // display cap would otherwise evict before wait_agents collects them
+      // (see agent-fleet.ts).
       const fleetSessions = nd.sessions ?? createSubAgentSessionStore();
       const fleetRecords = createFleetRecords();
       const fleetDeps = {
@@ -694,8 +687,8 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
       params.id !== undefined && /^[A-Za-z0-9_-]+$/.test(params.id) ? params.id : undefined;
     const workdir = join(params.workdirBase, "subagents", safeRequestedId ?? generateSessionId());
     await mkdir(workdir, { recursive: true });
-    // One record per stop/nudge, with its measured value beside its threshold,
-    // written into this leaf's own trace dir (CL-6938).
+    // One record per stop/nudge, with its measured value beside its
+    // threshold, written into this leaf's own trace dir.
     interventions = createInterventionLog(workdir, {
       role: params.orchestrator === true ? "orchestrator" : "leaf",
       provider: params.provider.providerName,
@@ -816,13 +809,12 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
       runController.signal.addEventListener("abort", closeOnAbort, { once: true });
     }
 
-    // CL-6943: hand the caller a bounded, idempotent close it can call at any
-    // time (close_agent) — independent of whether this run ends up retained.
+    // Hand the caller a bounded, idempotent close it can call at any time
+    // (close_agent) — independent of whether this run ends up retained.
     // Aborting first stops a still-running turn before tearing down; on an
-    // already-finished turn the abort is a no-op and disposeSubAgentSession
-    // just releases resources. The timeout races teardown itself so a wedged
-    // descendant cannot hang the caller — see dispose.ts's documented
-    // close()-ordering issue (CL-6984) for why teardown itself can stall.
+    // already-finished turn the abort is a no-op. The timeout races teardown
+    // itself so a wedged descendant cannot hang the caller — see dispose.ts
+    // for the close()-ordering issue that can stall it.
     if (params.onAgentReady !== undefined) {
       const boundedClose = async (deadlineMs = DEFAULT_CLOSE_DEADLINE_MS): Promise<void> => {
         if (!runController.signal.aborted) runController.abort(new Error("closed by close_agent"));
@@ -839,25 +831,21 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
           teardown,
           new Promise<void>((resolve) => setTimeout(resolve, deadlineMs)),
         ]);
-        // CL-7001: the run's finally block kept the parent-abort forwarding
-        // listener alive for a persisted session (see runController.dispose's
-        // doc); now that this session is actually closing, tear it down for
-        // real so the listener does not outlive the session.
+        // The finally block kept the parent-abort forwarding listener alive
+        // for a persisted session (see runController.dispose's doc); now that
+        // this session is actually closing, tear it down for real.
         runController.dispose();
       };
-      // CL-6997: interrupt only fires interruptController — never
-      // runController/close, so it cannot hit the close()-ordering wedge
-      // documented in dispose.ts (CL-6984).
+      // Interrupt only fires interruptController — never runController/
+      // close, so it cannot hit the close()-ordering wedge documented in
+      // dispose.ts.
       const interrupt = (): void => {
         if (!interruptController.signal.aborted) {
           interruptController.abort(new Error("interrupted by interrupt_agent"));
         }
       };
-      // CL-6997: followup_task's payoff — call agent.send() again on the
-      // same live agent object. The vendored send-queue serializes this
-      // behind whatever cycle was in flight (interrupted or not), and
-      // agent.history()/the context store already hold every prior turn, so
-      // this reuses full context rather than starting fresh.
+      // followup_task's payoff — call agent.send() again on the same live
+      // agent object, reusing full context rather than starting fresh.
       const followup = async (message: string): Promise<string> => {
         const result = await agent!.send(message, { signal: runController.signal });
         return result.reply.trim().length > 0
@@ -889,8 +877,8 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
     };
     try {
       ensureNotAborted();
-      // Combine the run's own controller with the dedicated interrupt signal
-      // (CL-6997) so either one stops this send() call, while only
+      // Combine the run's own controller with the dedicated interrupt
+      // signal so either one stops this send() call, while only
       // runController's abort is wired to closeOnAbort/teardown.
       const sendSignal =
         typeof AbortSignal.any === "function"
@@ -918,23 +906,22 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
       // Normalize into the structured envelope so the parent always gets a
       // consistent shape even when the model rambling-returns free-form prose.
       const report = formatSubAgentReport(parseSubAgentReport(reply));
-      // A clean completion is the only outcome CL-6943 retains: an aborted or
-      // salvaged run below falls through without setting this, so the finally
-      // block still tears down exactly as before for those.
+      // A clean completion is the only outcome that retains: an aborted or
+      // salvaged run below falls through without setting this, so the
+      // finally block still tears down for those.
       turnSucceeded = true;
       return {
         report: appendActivitySummary(report, toolNamesUsed),
         ...(directorForcedStopReason !== undefined ? { stopReason: directorForcedStopReason } : {}),
-        // CL-7001: only this path skips teardown below when persist is set —
-        // tell the caller so a salvage below is never mistaken for a still-
-        // live, resumable agent.
+        // Only this path skips teardown below when persist is set — tell
+        // the caller so a salvage below is never mistaken for a still-live,
+        // resumable agent.
         ...(params.persist === true ? { agentRetained: true } : {}),
       };
     } catch (err) {
-      // CL-6997: interrupt_agent fired its own signal, not runController's —
-      // check that first so an interrupted send doesn't fall into the
-      // cancel/deadline salvage path (which tears down in the finally
-      // block) or rethrow as a bare AbortError.
+      // interrupt_agent fired its own signal, not runController's — check
+      // that first so an interrupted send doesn't fall into the cancel/
+      // deadline salvage path or rethrow as a bare AbortError.
       if (interruptController.signal.aborted && !runController.signal.aborted) {
         interruptedKeepAlive = true;
         const abortedCycleText = await cycleRecorder.dispose("cancelled", { drain: streamPromise });
@@ -993,20 +980,19 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
     }
   } finally {
     if (stallWatchdog !== undefined) clearInterval(stallWatchdog);
-    // CL-7001 + CL-6997: a run keeps its agent alive either because it
-    // completed cleanly under persist, or because interrupt_agent fired and
-    // the session must stay reusable. Both skip teardown and both need the
-    // parent-signal listener kept so a later cancel still reaches them.
+    // A run keeps its agent alive either because it completed cleanly
+    // under persist, or because interrupt_agent fired and the session must
+    // stay reusable. Both skip teardown and both need the parent-signal
+    // listener kept so a later cancel still reaches them.
     const persisting = (params.persist === true && turnSucceeded) || interruptedKeepAlive;
-    // CL-7001: a persisting run must keep the parent-signal forwarding alive
-    // (see createSubAgentRunController's dispose doc) — boundedClose (the
+    // A persisting run must keep the parent-signal forwarding alive (see
+    // createSubAgentRunController's dispose doc) — boundedClose (the
     // close_agent handle) fully disposes the runController itself once the
     // session actually tears down.
     runController.dispose({ keepParentListener: persisting });
-    // CL-6943: a persisted, cleanly-completed session skips teardown here —
-    // it stays open until close_agent (or a later failed/aborted run) tears
-    // it down. Everything else (no persist, a thrown error, an
-    // aborted/salvaged run) disposes exactly as before.
+    // A persisted, cleanly-completed session skips teardown here — it
+    // stays open until close_agent (or a later failed/aborted run) tears it
+    // down.
     if (!persisting) {
       await disposeSubAgentSession({
         signal: runController.signal,
diff --git a/src/subagent/shell-evidence.test.ts b/src/subagent/shell-evidence.test.ts
index dc4c64d87..4023fb4d9 100644
--- a/src/subagent/shell-evidence.test.ts
+++ b/src/subagent/shell-evidence.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, test } from "bun:test";
 
 import { classifyShellFileEvidence } from "./shell-evidence.js";
 
-describe("classifyShellFileEvidence (CL-6937)", () => {
+describe("classifyShellFileEvidence", () => {
   test("readers count as reads with their file operand", () => {
     expect(classifyShellFileEvidence("cat src/a.ts").reads).toContain("src/a.ts");
     expect(classifyShellFileEvidence("head -n 5 src/a.ts").reads).toContain("src/a.ts");
diff --git a/src/subagent/shell-evidence.ts b/src/subagent/shell-evidence.ts
index d90254a4e..6a2548a3b 100644
--- a/src/subagent/shell-evidence.ts
+++ b/src/subagent/shell-evidence.ts
@@ -1,4 +1,4 @@
-// --- Shell file evidence (CL-6937) -----------------------------------------
+// --- Shell file evidence -----------------------------------------
 //
 // The stop policy's requireEvidence / CritiqueDirector gate measures whether
 // a worker did real work by counting typed tool calls. Reads done through
diff --git a/src/subagent/submit-result.ts b/src/subagent/submit-result.ts
index 94251d41c..8f85a6448 100644
--- a/src/subagent/submit-result.ts
+++ b/src/subagent/submit-result.ts
@@ -1,5 +1,5 @@
 /**
- * submit_result evaluation (CL-6946): pure logic, unit-testable without
+ * submit_result evaluation: pure logic, unit-testable without
  * spinning up a full agent loop. run.ts wires this into the tool handler and
  * owns the per-turn `SubmitResultState` (one instance per runSubAgent call).
  */
diff --git a/src/subagent/task-tool.ts b/src/subagent/task-tool.ts
index 6cc91b85d..e16c95944 100644
--- a/src/subagent/task-tool.ts
+++ b/src/subagent/task-tool.ts
@@ -67,7 +67,7 @@ export const TaskToolArgs = type({
   "report_focus?": "string",
 });
 
-// Deprecated (CL-7004): task() is the fused, blocking spawn+wait primitive.
+// Deprecated: task() is the fused, blocking spawn+wait primitive.
 // Prefer spawn_agent + wait_agents for new call sites — spawn_agent returns
 // immediately and wait_agents blocks on whichever workers you need next, so
 // multiple workers do not serialize behind one call. task() is not removed —
@@ -198,8 +198,8 @@ function taskToolResult(
     callId,
     content,
     ...(isError ? { isError: true } : {}),
-    // Structured stop-reason side channel (CL-6946 part 2): the parent chat
-    // director classifies salvage outcomes from this, never from `content`.
+    // Structured stop-reason side channel: the parent chat director
+    // classifies salvage outcomes from this, not from `content`.
     ...(stopReason !== undefined ? { detail: { stopReason } } : {}),
   };
 }
@@ -220,7 +220,7 @@ function receivedFieldPreview(value: string): string {
 /**
  * Rejection naming only the actually-bad required fields, echoing the valid
  * one back. A generic "requires description and prompt" hid which field was
- * missing, so models retried the identical call verbatim (CL-6901).
+ * missing, so models retried the identical call verbatim.
  */
 function requiredTaskFieldsError(
   args: Record<string, unknown>,
@@ -256,7 +256,7 @@ export function createTaskTool(deps: TaskToolDeps): AgentTool {
   const briefLedger = createBriefDispatchLedger();
   // Every completed dispatch gets an outcome record — the log otherwise
   // carries shape and run state but never what the run actually produced.
-  // Tagged with the dispatched child's provider/model/family (CL-6968) so
+  // Tagged with the dispatched child's provider/model/family so
   // per-model intervention counts finally have a denominator: the same
   // provider/model this dispatch actually ran under, taken after profile/
   // agent inference resolution — never a name the parent merely intended.
@@ -277,7 +277,7 @@ export function createTaskTool(deps: TaskToolDeps): AgentTool {
       family,
     });
   };
-  // Concurrent-lane overlap detection (CL-6952), replacing the static
+  // Concurrent-lane overlap detection, replacing the static
   // per-package writePaths lock. There is no field in the task() contract a
   // caller uses to declare which files a dispatch will touch, so the only
   // honestly knowable "intended scope" at spawn is the working directory the
@@ -346,7 +346,7 @@ export function createTaskTool(deps: TaskToolDeps): AgentTool {
       let systemPromptRole: string | undefined;
       let orchestrator = false;
       /**
-       * Fleet authority tier (CL-6941) for this dispatch — forwarded to
+       * Fleet authority tier for this dispatch — forwarded to
        * runSubAgent, which fails closed (denies task/search_agents) when
        * orchestrator is true and this is left undefined or resolves to
        * "leaf". Set alongside `orchestrator = true` in every branch below;
@@ -411,7 +411,7 @@ export function createTaskTool(deps: TaskToolDeps): AgentTool {
       };
 
       if (agentId !== undefined && agentId.length > 0) {
-        // Closed director fleet (CL-5818): resolve package even when profiles
+        // Closed director fleet: resolve package even when profiles
         // are not loaded; profiles may still pin inference for the same id.
         if (isDirectorId(agentId)) {
           const resolved = resolveDirector({ agentId });
@@ -477,7 +477,7 @@ export function createTaskTool(deps: TaskToolDeps): AgentTool {
           // even if their profile is marked orchestrator — recursion bottoms out.
           if (profile.orchestrator === true && deps.allowOrchestrator !== false) {
             orchestrator = true;
-            // Fail closed (CL-6941): a profile is outside the closed director
+            // Fail closed: a profile is outside the closed director
             // set, so orchestrator: true alone does not grant a tier. No
             // profile field opts in; orchestratorTier stays undefined, which
             // runSubAgent treats as "leaf" and denies task/search_agents.
@@ -685,7 +685,7 @@ export function createTaskTool(deps: TaskToolDeps): AgentTool {
       let worktreeCwd: string | undefined;
       let worktreeStashBaseline: readonly string[] | null = [];
       let worktreeHeadAtCreate: string | undefined;
-      // Full child wall: worktree setup → run → teardown (CL-5170 exclusive share).
+      // Full child wall: worktree setup → run → teardown.
       const turnId = currentTurnId();
       const subagentSpanId = start("subagent", {
         ...(turnId !== null && turnId.length > 0 ? { parentId: turnId } : {}),
@@ -794,7 +794,7 @@ export function createTaskTool(deps: TaskToolDeps): AgentTool {
                 }
               : {}),
             ...(deps.deadlineMs !== undefined ? { deadlineMs: deps.deadlineMs } : {}),
-            // submit_result mount gate (CL-6946): only a resolved Tier 3 leaf
+            // submit_result mount gate: only a resolved Tier 3 leaf
             // director gets tier here, and only if it declared an outputType.
             ...(resolvedPackage !== undefined ? { tier: resolvedPackage.tier } : {}),
             ...(resolvedPackage?.reportContract?.outputType !== undefined
diff --git a/src/subagent/thrash.test.ts b/src/subagent/thrash.test.ts
index d9640bee5..fba4496e9 100644
--- a/src/subagent/thrash.test.ts
+++ b/src/subagent/thrash.test.ts
@@ -53,7 +53,7 @@ describe("thrash pure module", () => {
     let state = EMPTY_THRASH_STATE;
     state = nextThrashState(state, [read("a.ts")]);
     // An edit no longer erases read evidence: readCounts is the requireEvidence
-    // record, not a thrash counter (CL-6936).
+    // record, not a thrash counter.
     state = nextThrashState(state, [edit("a.ts")]);
     expect(state.readCounts.get("a.ts")).toBe(1);
     state = nextThrashState(state, [read("a.ts"), read("a.ts")]);
@@ -75,7 +75,7 @@ describe("thrash pure module", () => {
     expect(state.totalToolCalls).toBe(1);
   });
 
-  test("run_shell file reads count as read evidence (CL-6937)", () => {
+  test("run_shell file reads count as read evidence", () => {
     const shell = (command: string): ThrashToolCallBlock => ({
       type: "tool_call",
       name: "run_shell",
diff --git a/src/subagent/thrash.ts b/src/subagent/thrash.ts
index b6985dabc..6aaa06df7 100644
--- a/src/subagent/thrash.ts
+++ b/src/subagent/thrash.ts
@@ -1,7 +1,7 @@
 /**
  * Pure read/edit bookkeeping for dispatched workers, consumed by
  * evaluateSubAgentStop's requireEvidence check (CritiqueDirector). Reads
- * performed through run_shell count as evidence too (CL-6937) — the prompt
+ * performed through run_shell count as evidence too — the prompt
  * prohibits shell file work, but a prompt violation deserves a correction,
  * not a verdict that the work never happened. `editedPaths` (from typed write
  * tools only) is diagnostics for interventions.jsonl; no stop decision
@@ -109,7 +109,7 @@ export function nextThrashState(
       const key = searchKey(name, args);
       readCounts.set(key, (readCounts.get(key) ?? 0) + 1);
     } else if (name === SHELL_TOOL) {
-      // Shell reads are evidence too (CL-6937) — the prompt prohibits shell
+      // Shell reads are evidence too — the prompt prohibits shell
       // file work, but a prompt violation deserves a correction, not a
       // verdict that the work never happened.
       const command = args.command;
diff --git a/src/subagent/tool-preview.ts b/src/subagent/tool-preview.ts
index a0d7d4fb3..bb75ded63 100644
--- a/src/subagent/tool-preview.ts
+++ b/src/subagent/tool-preview.ts
@@ -2,7 +2,7 @@
  * One-line previews of what a live tool call is doing — the subject of a lane
  * row, not a serialisation of its arguments.
  *
- * CL-5765: operators watching a fleet need to tell six shell commands apart;
+ * Operators watching a fleet need to tell six shell commands apart;
  * the bare tool name cannot. Previews are bounded, single-line, and secret-
  * scrubbed so the agents strip never becomes a new leak path for credentials
  * that happen to sit in a command string.
diff --git a/src/subagent/trace-reader.ts b/src/subagent/trace-reader.ts
index 431ae36de..d5e0959f7 100644
--- a/src/subagent/trace-reader.ts
+++ b/src/subagent/trace-reader.ts
@@ -1,5 +1,5 @@
 /**
- * On-disk trace reader backing the `read_agent_trace` fleet verb (CL-6951).
+ * On-disk trace reader backing the `read_agent_trace` fleet verb.
  *
  * Every sub-agent worker writes its full turn history to `turns.jsonl`
  * (segmented — see incremental-jsonl.ts) under its own workdir, but nothing
diff --git a/src/subagent/trace-tool.ts b/src/subagent/trace-tool.ts
index 27b516c5b..4ff4b1d46 100644
--- a/src/subagent/trace-tool.ts
+++ b/src/subagent/trace-tool.ts
@@ -1,5 +1,5 @@
 /**
- * `read_agent_trace` tool (CL-6951): lets an orchestrator or nested
+ * `read_agent_trace` tool: lets an orchestrator or nested
  * orchestrator inspect what a worker has actually done on disk — its turns,
  * tool calls, and errors — even if the worker is still running or was
  * cancelled/interrupted and its in-memory session record is gone.
@@ -137,8 +137,8 @@ export function createReadAgentTraceTool(
       }
       if (authority !== undefined) {
         // Fails closed: an actor whose own store id could not be resolved
-        // (no session record for this dispatch) must never be trusted with
-        // fleet-wide read access, mirroring CL-6941's unresolved-tier rule.
+        // (no session record for this dispatch) is denied fleet-wide read
+        // access, mirroring the unresolved-tier rule elsewhere.
         if (authority.actorId === undefined) {
           return (
             "Error: read_agent_trace is unavailable for this worker (no resolvable session " +
diff --git a/src/subagent/types.ts b/src/subagent/types.ts
index 802a867f0..adfdb8c6c 100644
--- a/src/subagent/types.ts
+++ b/src/subagent/types.ts
@@ -119,7 +119,7 @@ export type RunSubAgentParams = {
   // advertising permission without the tool is a hard break.
   orchestrator?: boolean;
   /**
-   * Fleet authority tier (CL-6941) for this dispatch, resolved by the caller
+   * Fleet authority tier for this dispatch, resolved by the caller
    * (task-tool.ts) from either the closed DirectorPackage.tier or an explicit
    * AgentProfile.tier opt-in. Required whenever orchestrator is true:
    * runSubAgent fails closed (denies task/search_agents) when orchestrator is
@@ -137,7 +137,7 @@ export type RunSubAgentParams = {
    */
   deadlineMs?: number;
   /**
-   * Resolved director tier (CL-6946), independent of `orchestratorTier` (which
+   * Resolved director tier, independent of `orchestratorTier` (which
    * is only ever set when `orchestrator` is true). Set by task-tool.ts from
    * `DirectorPackage.tier`. runSubAgent mounts `submit_result` only when this
    * is `"leaf"` — the existing tier machinery (authority.ts / directors/types.ts)
@@ -147,7 +147,7 @@ export type RunSubAgentParams = {
   /** DirectorPackage.reportContract.outputType, when the resolved leaf declares one. */
   reportType?: OutputType;
   /**
-   * CL-6943: when true, a clean successful completion skips the normal
+   * when true, a clean successful completion skips the normal
    * end-of-turn teardown (agent.close() / posixTools.dispose()) so the
    * session stays open and reusable. A failure or an aborted/cancelled run
    * still tears down as before — only a clean success is retained. A caller
@@ -160,9 +160,9 @@ export type RunSubAgentParams = {
    * sent), with handles the caller can register for later use against this
    * session:
    *
-   *  - `close`: bounded teardown for close_agent (unchanged from CL-6943).
+   *  - `close`: bounded teardown for close_agent.
    *  - `interrupt`: stops the in-flight `agent.send()` by firing a signal
-   *    scoped to that call only (CL-6997) — distinct from `close`'s
+   *    scoped to that call only — distinct from `close`'s
    *    AbortController, so firing it never touches agent.close() or the
    *    workdir lock. The reactor cycle itself keeps running in the
    *    background (same documented behavior as `Agent.send`'s own
@@ -186,12 +186,12 @@ export type RunSubAgentParams = {
   }) => void;
 } & SubAgentSandboxDeps;
 
-/** runSubAgent's result: the parent-facing report plus, when force-stopped, the structured reason why (CL-6946 part 2) — classify outcomes from `stopReason`, never by parsing `report`. */
+/** runSubAgent's result: the parent-facing report plus, when force-stopped, the structured reason why — classify outcomes from `stopReason`, not by parsing `report`. */
 export interface RunSubAgentResult {
   report: string;
   stopReason?: ForcedStopReason;
   /**
-   * CL-7001: true only on the clean-completion path when `persist: true`
+   * true only on the clean-completion path when `persist: true`
    * actually skipped teardown (mirrors run.ts's own turnSucceeded gate). A
    * deadline/cancel salvage returns without throwing but always disposes its
    * agent, so this is absent (falsy) there even though the promise resolves
@@ -200,7 +200,7 @@ export interface RunSubAgentResult {
    */
   agentRetained?: boolean;
   /**
-   * CL-6997: true only when this run ended because interrupt_agent fired
+   * true only when this run ended because interrupt_agent fired
    * (not a plain cancel/deadline) — the caller must not run its normal
    * complete()/fail() bookkeeping over this result, since interrupt_agent
    * already transitioned the session to "interrupted" synchronously.