refactor(session): deepen comment compression in the runtime assembly cluster

Author: Gustav-Simonsson

src/session/assemble-runtime.ts

@@ -279,8 +279,7 @@ export interface SessionGate {
 /**
  * Seed approvals (session → project → global → provider-model) and build the
  * permission gate over roots, persist, and log wiring. Runners differ only
- * in how approval reaches an operator (modal vs stdin) — both arrive as
- * callbacks.
+ * in the operator channel (modal vs stdin); approval arrives as a callback.
  */
 export async function assembleSessionGate(
   args: SessionGateArgs,
@@ -378,18 +377,18 @@ export interface AdvertisedToolset {
 
 /**
  * Fixed built-in prefix plus session-activated tools, family-gated for the
- * wire. The provider identity is read per call so a live model switch
- * re-gates without rebuilding the agent.
+ * wire. Provider identity is read per call, so a live model switch re-gates
+ * without a rebuild.
  *
  * Activation and advertisement are split: activating opens the call gate at
  * once; flushPromotions commits names onto the wire (promote-on-execute
- * flushes the one called name, tool_search only the top ranked hits). Fold
- * breaks the cache prefix — pruneIdlePromotions drops the advertised tail
- * back to it.
+ * flushes the called name, tool_search only top-ranked hits). Fold breaks
+ * the cache prefix — pruneIdlePromotions drops the advertised tail back to
+ * it.
  *
  * `pinnedTools` (local settings) merge into the prefix — advertised from the
- * first turn and exempt from activation state, so resume needs no
- * tool_search round-trip for the project's hottest integrations.
+ * first turn, exempt from activation state, so resume skips the tool_search
+ * round-trip for them.
  */
 export function createAdvertisedToolset(args: {
   sessionMode: SessionMode;
@@ -566,9 +565,8 @@ export interface ChatAgentWiring {
   anthropicCachePrompt?: () => boolean;
   /**
    * Present when a resumed run record has an Anthropic-protocol cache write
-   * and the provider about to be called is the same protocol. Read at each
-   * build so an interrupt rebuild of the same session still folds before the
-   * next infer. Omitted for a new session.
+   * and the next provider is the same protocol. Read at each build so an
+   * interrupt rebuild of the same session still folds before the next infer.
    */
   getCacheWriteSeed?: () => { at: number; model: string } | undefined;
   /** Assigns the runner's live agent/storage holders; keeps call sites unchanged. */
@@ -850,9 +848,9 @@ export interface SessionLifecycle {
 
 /**
  * Hook manager, turn observer, run sink, and in-flight cycle recorder. Pure
- * construction — every live value (session id, source, context dir) is read
- * through a getter at event time, so it can assemble before the agent exists
- * (the TUI builds it early, exec late; same call, different position).
+ * construction — live values (session id, source, context dir) are read
+ * through getters at event time, so it can assemble before the agent exists
+ * (TUI early, exec late).
  */
 export async function assembleSessionLifecycle(
   wiring: SessionLifecycleWiring,

src/session/compaction-handoff.ts

@@ -825,11 +825,9 @@ export function renderHandoffFile(
 }
 
 /**
- * Render the thin live spine: goal cut at a token boundary, standing output
- * tokens uncut, constraints/decisions, the evidence echo, activated tools,
- * and the file pointer. Starts with COMPACTED_PREFIX so the next fold parses
- * it as a handoff turn. Counts, file lists, and next actions stay in the fat
- * file.
+ * Render the thin live spine (shape in the module doc). Starts with
+ * COMPACTED_PREFIX so the next fold parses it as a handoff turn; counts,
+ * file lists, and next actions stay in the fat file.
  */
 export function renderHandoffSpine(
   spine: SpineFacts,
@@ -891,9 +889,9 @@ export interface HandoffFold {
 }
 
 /**
- * Build one fold's handoff: extract the artifact from the folded turns
- * (unioned with the previous fat file when provided), render the fat file,
- * and return the thin spine carrying the file's pointer.
+ * Build one fold's handoff: extract the artifact (unioned with the previous
+ * fat file when provided), render the fat file, and return the thin spine
+ * carrying the file's pointer.
  */
 export function buildHandoffFold(
   foldedTurns: readonly ConversationTurn[],

src/session/optimized-context-store.ts

@@ -86,13 +86,12 @@ function sanitizeCallId(callId: string): string {
 
 /**
  * Parse conversation turns out of one JSONL segment. A crash can tear the
- * final line of the active segment mid-write; `tolerateTornTail` drops it
- * instead of aborting resume. Null padding from a stale keepBytes write is
- * stripped. `skipMalformed` drops (or partially recovers) a bad line
- * anywhere and keeps surrounding history — used by `loadRecentTurns` and
- * the reactor's `load()` recovery path, since a bad line should not kill
- * the session. A truncated stub glued to the next append still yields a
- * trailing complete turn via `recoverTurnFromGluedLine`.
+ * final line of the active segment mid-write; `tolerateTornTail` drops it.
+ * Null padding from a stale keepBytes write is stripped. `skipMalformed`
+ * drops (or partially recovers) a bad line anywhere and keeps surrounding
+ * history — used by `loadRecentTurns` and the reactor's `load()` recovery
+ * path. A truncated stub glued to the next append still yields a trailing
+ * complete turn via `recoverTurnFromGluedLine`.
  */
 function recoverTurnFromGluedLine(line: string): ConversationTurn | null {
   // Walk every `{` start: a truncated prefix glued onto a complete record

src/session/runtime-assembly.ts

@@ -118,8 +118,8 @@ export interface LiveSubAgentSources {
 /**
  * Single owner of every session fact a sub-agent spawn reads. Each switch
  * path (model picker, /agent, post-connect refresh, favorite toggle)
- * reassigns the runner's config, so all three derive from a config getter
- * per spawn; hand-synced snapshots went stale when a switch path missed one.
+ * reassigns the runner's config, so all three read a config getter per
+ * spawn; hand-synced snapshots went stale when a switch path missed one.
  */
 export function createLiveSubAgentSources(
   getConfig: () => SubAgentSourcesConfig,
@@ -213,7 +213,7 @@ function persistBestEffort(
  * Route a gate-persisted grant to the store its scope selects. Session
  * grants never reach here — the gate keeps those in memory only.
  * `getActiveProviderModel` is read at persist time so a live model switch
- * stores under the pair now in use.
+ * stores under the pair in use.
  */
 export function createApprovalPersist(
   cwd: string,
@@ -582,9 +582,9 @@ export function createSessionPruningCompactor(
 
 /**
  * Content-less inbound the compaction governor self-delivers after a compact
- * cycle so the reactor re-enters (it emits no event after compact). Single
- * owner for the TUI, exec, and sub-agent loops; the copies were
- * byte-identical, so a new field is a one-site change.
+ * so the reactor re-enters (it emits nothing after). One owner for the TUI,
+ * exec, and sub-agent loops — the copies were byte-identical, so a new
+ * field is a one-site change.
  */
 export function buildCompactionContinuationMessage(): InboundMessage {
   return {
@@ -604,10 +604,10 @@ export function buildCompactionContinuationMessage(): InboundMessage {
 /**
  * Per-host consume-once gate for the compaction continuation emit. The
  * reactor emits it before compact runs and nothing after, so the emission
- * is the outstanding-continuation claim. Each emission (keyed by its
+ * is the outstanding-continuation claim. Each emission (keyed by a
  * session-scoped seq) is answered at most once: a replayed duplicate is
- * ignored since every delivery costs a billable inference, and a forged
- * fresh seq is answered with wait, so it cannot burn a model turn either.
+ * ignored (every delivery costs a billable inference) and a forged fresh
+ * seq is answered with wait, so it cannot burn a model turn.
  */
 export function createContinuationGate(): {
   shouldDeliver: (seq: number) => boolean;

src/session/summarizer.ts

@@ -2,8 +2,8 @@
 //
 // On compaction the pruning compactor replaces older turns with a summary. A
 // deterministic stats blob loses what resuming work needs, so this module
-// writes a structured, workflow-aware narrative via one inference call
-// against the session's own model.
+// writes a structured, workflow-aware narrative in one inference call on the
+// session's own model.
 
 import { type } from "arktype";
 import { runInference, type Dependencies } from "@intx/inference";
@@ -119,8 +119,7 @@ export async function buildArchiveSummaryExcerpt(
 }
 
 // What the agent was doing when compaction fired, so the summary preserves
-// the workflow contract ("we are at step 3/7 of /build") instead of dropping
-// it into the compacted region.
+// the workflow contract ("we are at step 3/7 of /build").
 export interface SummaryContext {
   workflow?: {
     name?: string;
@@ -453,8 +452,8 @@ export interface ModelSummarizerOptions {
 /**
  * Build a `summarize(turns, ctx)` function suitable for `CompactorConfig`.
  * Throws on empty output or a failed call so the compact cycle can substitute
- * a statistics-only stub; the session pruning wrapper owns that stub's
- * operator notice and fires it only after the fold commits.
+ * a statistics-only stub; the pruning wrapper owns that stub's notice and
+ * fires it only after the fold commits.
  */
 export function createModelSummarizer(
   options: ModelSummarizerOptions,