(janitor/comments) remove section banners and narration comments in cloud-agent-next

services/cloud-agent-next/src/control-plane/sandbox/routes.ts

@@ -185,8 +185,6 @@ export function routeView(
   return { state: 'preparing', attemptId: route.attemptId, ...sandboxProgress };
 }
 
-// --- storage -----------------------------------------------------------------
-
 export async function readRoute(db: RouteDatabase, sessionId: string): Promise<RouteRecord | null> {
   const rows = await db.select().from(routesTable).where(eq(routesTable.session_id, sessionId));
   const row = rows[0];
@@ -244,8 +242,6 @@ export async function earliestRouteDeadlineAt(db: RouteDatabase): Promise<number
   return values.length === 0 ? null : Math.min(...values);
 }
 
-// --- route transitions -------------------------------------------------------
-
 /**
  * A route spec with no issuer material, used only when issuance fails. It is
  * never sent to a wrapper (the route is `failed`), and it keeps native tokens

services/cloud-agent-next/src/control-plane/sandbox/sandbox-do.ts

@@ -656,8 +656,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     this.initialized = ctx.blockConcurrencyWhile(() => this.initializeStorage());
   }
 
-  // --- lifecycle entry points -------------------------------------------------
-
   /**
    * Establishes the provider pin and starts the allocation. `prepare` starts an
    * allocation from the stored pin without going through here, so callers that
@@ -727,8 +725,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     };
   }
 
-  // --- routes (B3) ------------------------------------------------------------
-
   /**
    * Session DO -> Sandbox DO (spec §10). Returns the route view at once and
    * never waits for a provider call. An absent or `failed` route starts a new
@@ -839,8 +835,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     });
   }
 
-  // --- worktree deletion (B10) ------------------------------------------------
-
   /**
    * Worker -> Sandbox DO (spec §6 "Billing, credentials and deletion"). Port of
    * the legacy DO cleanup: when the provider stop or the shared runtime is
@@ -1031,8 +1025,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     return (await this.observeWorktreeRuntime(plan.providerRef)).status === 'terminal';
   }
 
-  // --- worktree changes (B10) -------------------------------------------------
-
   /**
    * Session DO -> Sandbox DO (spec §10). Forwards one worktree-change request
    * to the wrapper and returns its result. The Sandbox DO owns no snapshot
@@ -1062,8 +1054,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     return this.beginWrapperControlRequest(frame);
   }
 
-  // --- terminals (B10) --------------------------------------------------------
-
   /**
    * Session DO -> Sandbox DO (spec §10). Forwards exactly one terminal
    * create/resize/close/connect request to the wrapper and returns its result.
@@ -1083,8 +1073,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     return this.beginWrapperControlRequest(terminalRequestFrame(crypto.randomUUID(), input));
   }
 
-  // --- preview ----------------------------------------------------------------
-
   /**
    * Off-queue read the Session DO uses to resolve one preview's provider
    * coordinates. It never enqueues, so a preview never waits behind the control
@@ -1207,8 +1195,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     );
   }
 
-  // --- credentials (B3) -------------------------------------------------------
-
   /**
    * Contained outbound credential lookup (spec §6/§10), same request shape as
    * `src/sandbox-outbound.ts` calls today. Matches the grant by alias, re-checks
@@ -1724,8 +1710,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     });
   }
 
-  // --- init and storage cutover ----------------------------------------------
-
   private async initializeStorage(): Promise<void> {
     const generation = await this.ctx.storage.get<unknown>(GENERATION_KEY);
     if (generation === undefined) {
@@ -1948,8 +1932,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     };
   }
 
-  // --- allocation events and effects -----------------------------------------
-
   private async applyEvent(event: AllocationEvent): Promise<void> {
     const previous = await this.readAllocation();
     const timers = { ...this.sandboxTimers() };
@@ -2046,8 +2028,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     };
   }
 
-  // --- route execution and notifications (B3) ---------------------------------
-
   private async runPrepare(
     spec: ControlPlaneRouteSpec,
     source: ControlPlaneCredentialSource,
@@ -2887,8 +2867,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     return isAdoptableWorktreeScope({ grant, acceptedMarker: marker });
   }
 
-  // --- contained credential helpers (B3) --------------------------------------
-
   /** The managed outbound container id for the current provider/allocation. */
   private outboundContainerIdFor(state: AllocationState): string | null {
     // The container is the containment boundary. When containment is off there
@@ -4487,8 +4465,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     await this.enqueue(() => this.applyEvent(event));
   }
 
-  // --- wrapper socket ---------------------------------------------------------
-
   private readAttachment(ws: WebSocket): WrapperSocketAttachment | null {
     const parsed = wrapperSocketAttachmentSchema.safeParse(ws.deserializeAttachment());
     return parsed.success ? parsed.data : null;
@@ -4957,8 +4933,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     await this.billingRuntime.defer(generation, callback);
   }
 
-  // --- provider selection -----------------------------------------------------
-
   private ensureVercelBillingRuntime() {
     return this.billingRuntime.ensureRuntime();
   }
@@ -5028,8 +5002,6 @@ export class SandboxControlV2 extends DurableObject<Env> {
     return resolved === undefined ? undefined : { ...resolved, teamId: locator.teamId };
   }
 
-  // --- storage ----------------------------------------------------------------
-
   private async retryAllowed(): Promise<boolean> {
     return routeRetryAllowed(this.routeContext(await this.readAllocation()));
   }

services/cloud-agent-next/src/control-plane/session/session-do.ts

@@ -641,8 +641,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     return peer.worktreeCapture(input);
   }
 
-  // --- init and storage cutover ----------------------------------------------
-
   private async initializeStorage(): Promise<void> {
     const generation = await this.ctx.storage.get<unknown>(GENERATION_KEY);
     if (generation !== GENERATION) {
@@ -702,8 +700,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     }
   }
 
-  // --- registration -----------------------------------------------------------
-
   async registerSession(input: ControlPlaneSessionRegistration): Promise<{ ok: true }> {
     await this.initialized;
     const registration = controlPlaneSessionRegistrationSchema.parse(input);
@@ -1218,8 +1214,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     return { type: 'ok', authorization };
   }
 
-  // --- message flow -----------------------------------------------------------
-
   async send(intent: ControlPlanePromptPayload): Promise<ControlPlaneSendResult> {
     await this.initialized;
     if (this.registration === null) return { type: 'session-not-found' };
@@ -1373,8 +1367,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     }
   }
 
-  // --- notifications (spec §10) ----------------------------------------------
-
   async onRoute(update: ControlPlaneRouteUpdate): Promise<void> {
     await this.initialized;
     if (this.registration === null) return;
@@ -1510,8 +1502,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     });
   }
 
-  // --- worktree changes (B10) -------------------------------------------------
-
   async getWorktreeChanges(): Promise<GetWorktreeChangesOutput> {
     await this.initialized;
     return this.worktreeChanges.get();
@@ -1526,8 +1516,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     return this.worktreeChanges.refresh();
   }
 
-  // --- backstop alarm ---------------------------------------------------------
-
   async alarm(): Promise<void> {
     await this.initialized;
     if (this.registration === null) return;
@@ -1582,8 +1570,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     await this.ctx.storage.setAlarm(Math.min(...candidates));
   }
 
-  // --- reads ------------------------------------------------------------------
-
   async getSession(): Promise<ControlPlaneSessionSnapshot> {
     await this.initialized;
     if (this.registration === null) return { type: 'session-not-found' };
@@ -1767,8 +1753,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     return closed;
   }
 
-  // --- delete and worktree deletion ------------------------------------------
-
   /**
    * C1c: updates a prepared session's callback target (legacy `tryUpdate`,
    * retained for `services/code-review-infra`). Stores the same grouped
@@ -2015,8 +1999,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     this.preparationRecorders.clear();
   }
 
-  // --- terminals (B10) --------------------------------------------------------
-
   /** Worker-facing terminal RPC (spec §10); routing/handler wiring is C1. */
   async terminalCreate(input: {
     operationId: string;
@@ -2041,8 +2023,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     return this.terminals.close(input);
   }
 
-  // --- preview ----------------------------------------------------------------
-
   /**
    * Worker-facing preview resolver (spec §10). Runs on the RPC path, not the
    * operation queue, so a preview never waits behind queued messages. It owns
@@ -2054,8 +2034,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     return this.preview.resolve();
   }
 
-  // --- stream -----------------------------------------------------------------
-
   async fetch(request: Request): Promise<Response> {
     await this.initialized;
     const pathname = new URL(request.url).pathname;
@@ -2129,8 +2107,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     });
   }
 
-  // --- route view -------------------------------------------------------------
-
   private async applyView(view: ControlPlaneRouteView, pass = this.transportPass()): Promise<void> {
     // The route view is the source of the preparation row: the previous
     // persisted view names the attempt that is open, so a transition closes it
@@ -2509,8 +2485,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     return namespace === undefined ? null : namespace.getByName(sandboxId);
   }
 
-  // --- preparation progress ---------------------------------------------------
-
   /**
    * The preparation attempt id is the route attempt id (spec §10); the trigger
    * is the oldest queued message. The recorder owns step continuity and the
@@ -2646,8 +2620,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     return this.route.state === 'unknown' ? null : this.route.attemptId;
   }
 
-  // --- settlement and message events -----------------------------------------
-
   private async settleMessages(
     messageIds: readonly string[],
     status: Extract<SessionMessageState, 'completed' | 'failed' | 'cancelled'>,
@@ -2867,8 +2839,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
     this.streamHandler().broadcastEvent(event);
   }
 
-  // --- connected-event projections -------------------------------------------
-
   private deriveCloudStatus(): {
     type: 'preparing' | 'ready' | 'finalizing' | 'error';
     step?: string;
@@ -2956,8 +2926,6 @@ export class SandboxSessionV2 extends DurableObject<Env> {
         };
   }
 
-  // --- storage ----------------------------------------------------------------
-
   private async loadMessages(): Promise<SessionMessage[]> {
     const rows = await this.db
       .select()

services/cloud-agent-next/src/persistence/CloudAgentSession.ts

@@ -505,8 +505,6 @@ export class CloudAgentSession extends DurableObject<WorkerEnv> {
   constructor(ctx: DurableObjectState, env: WorkerEnv) {
     super(ctx, env);
 
-    // Extract sessionId from DO name pattern: "userId:sessionId"
-    // The DO name is set by the worker when creating the stub.
     // Split on the *last* colon because userId may contain colons
     // (e.g. "oauth/google:12345:agent_abc" → sessionId = "agent_abc").
     const doName = ctx.id.name;
@@ -1278,7 +1276,6 @@ export class CloudAgentSession extends DurableObject<WorkerEnv> {
       return response;
     }
 
-    // Route ingest WebSocket (internal only - from queue consumer)
     if (url.pathname === '/ingest') {
       if (await this.hasDeletionIntent()) {
         return new Response('Session not found', { status: 404 });
@@ -1303,9 +1300,6 @@ export class CloudAgentSession extends DurableObject<WorkerEnv> {
       await ingestHandler.handleIngestMessage(ws, message);
       return;
     }
-
-    // Stream connections are server-push only, ignore client messages
-    // Future: could handle client commands like subscribe/unsubscribe
   }
 
   /**

services/cloud-agent-next/src/persistence/schemas.ts

@@ -226,8 +226,6 @@ export const MCPServerConfigSchema = z.discriminatedUnion('type', [
   MCPRemoteServerConfigSchema,
 ]);
 
-// --- Runtime instructions ---
-
 /**
  * Runtime instruction schema. Each entry is materialized to
  * `${SESSION_HOME}/.kilocode/rules/<name>.md` at preparation time, alongside
@@ -278,8 +276,6 @@ export const InitialExecutionPayloadSchema = z.discriminatedUnion('type', [
 
 export type InitialExecutionPayload = z.infer<typeof InitialExecutionPayloadSchema>;
 
-// --- Profile bundle ---
-
 /**
  * Schema for the profile-derived configuration bundle persisted with a
  * session. Current metadata stores this under the nested `profile` key.
@@ -341,7 +337,6 @@ export const MetadataSchema = z.object({
    * legacy record parsing.
    */
   profile: SessionProfileBundleSchema.optional(),
-  // --- Legacy flat profile fields (read-only fallback, no longer written) ---
   ...SharedSessionProfileFields,
   upstreamBranch: branchNameSchema.optional(),
   kiloSessionId: z.string().optional(),

services/cloud-agent-next/src/session/session-registration.ts

@@ -276,8 +276,6 @@ type NewSessionAllocation = SessionRegistrationResult & {
   runtimeAuthorization?: { token: string; seal: string };
 };
 
-// ----- operation-ledger boundary (P1-A-08b) -----------------------------------
-
 /**
  * Allocation failure stages reported to the operation ledger, matching the
  * `session_create_settled` `failure_stage` enum for pre-DO work.
@@ -1630,8 +1628,6 @@ export async function startNewSession(
   return registerAndAdmitInitialTurn(input, ctx, options, allocation, ledger);
 }
 
-// ----- ledger-guarded session creation ----------------------------------------
-
 /**
  * Ledger `canonical_result` key holding the SHA-256 fingerprint of the immutable
  * create intent, recorded with the first admitted create's progress. A same-key

services/cloud-agent-next/src/shared/control-plane-protocol.ts

@@ -1000,8 +1000,6 @@ const controlPlaneWorktreeDeleteFrameSchema = z
   })
   .strict();
 
-// --- terminals (B10) --------------------------------------------------------
-
 /**
  * Session DO -> Sandbox DO terminal request (spec §10). The Sandbox DO forwards
  * exactly one request frame and returns the wrapper's `terminal.result`. The

services/cloud-agent-next/src/shared/runtime-profile.ts

@@ -88,8 +88,6 @@ export const RuntimeSkillsSchema = z
 
 export type RuntimeSkillInput = z.infer<typeof RuntimeSkillSchema>;
 
-// --- Runtime agents ---
-
 const PermissionActionSchema = z.enum(['allow', 'ask', 'deny']);
 // Flat permissive shape — the runtime tolerates any shape the CLI accepts
 // (bare action string, per-tool map with per-pattern maps, null sentinels).
@@ -154,8 +152,6 @@ export const RuntimeAgentsSchema = z
 
 export type RuntimeAgentInput = z.infer<typeof RuntimeAgentSchema>;
 
-// --- Runtime kilo commands ---
-
 export const RuntimeKiloCommandSchema = z.object({
   name: z
     .string()