@cursor/july 0.1.94 → 0.1.96

package/src/internal/scm/pr-url.ts

@@ -0,0 +1,95 @@
+/**
+ * Provider-neutral PR URL parse. GitHub.com plus the Origin page shapes
+ * humans paste: cursor.com/codebase, review.cursor.com/pr, origin.cursor.com.
+ */
+
+export type PrProvider = "github" | "origin";
+
+export type ParsedPrUrl = {
+  provider: PrProvider;
+  owner: string;
+  repo: string;
+  number: number;
+  url: string;
+};
+
+const ORIGIN_PAGE = /^origin(-[a-z0-9]+)?\.cursor\.com$/i;
+
+function positiveInt(raw: string | undefined): number | undefined {
+  if (raw === undefined) {
+    return undefined;
+  }
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) {
+    return undefined;
+  }
+  return n;
+}
+
+function parsed(
+  provider: PrProvider,
+  owner: string | undefined,
+  repo: string | undefined,
+  number: number | undefined
+): ParsedPrUrl | undefined {
+  if (owner === undefined || repo === undefined || number === undefined) {
+    return undefined;
+  }
+  const url =
+    provider === "origin"
+      ? `https://cursor.com/codebase/${owner}/${repo}/pull/${number}`
+      : `https://github.com/${owner}/${repo}/pull/${number}`;
+  return { provider, owner, repo, number, url };
+}
+
+/** Strip Slack mrkdwn wrappers and trailing punctuation before `URL`. */
+function normalizeRaw(raw: string): string {
+  return raw
+    .trim()
+    .replace(/^[<[]+/, "")
+    .replace(/[>\].,;]+$/, "");
+}
+
+export function parsePrUrl(raw: string): ParsedPrUrl | undefined {
+  let url: URL;
+  try {
+    url = new URL(normalizeRaw(raw));
+  } catch {
+    return undefined;
+  }
+
+  const parts = url.pathname.split("/").filter(Boolean);
+  const host = url.hostname.toLowerCase();
+
+  if (
+    (host === "github.com" || host === "www.github.com") &&
+    parts.length >= 4 &&
+    parts[2] === "pull"
+  ) {
+    return parsed("github", parts[0], parts[1], positiveInt(parts[3]));
+  }
+
+  if (ORIGIN_PAGE.test(host) && parts.length >= 4 && parts[2] === "github") {
+    return parsed("origin", parts[0], parts[1], positiveInt(parts[3]));
+  }
+
+  if (
+    (host === "cursor.com" || host === "www.cursor.com") &&
+    parts[0] === "codebase" &&
+    parts.length >= 5 &&
+    parts[3] === "pull"
+  ) {
+    return parsed("origin", parts[1], parts[2], positiveInt(parts[4]));
+  }
+
+  if (host === "review.cursor.com" && parts[0] === "pr") {
+    if (parts.length >= 5 && parts[3] === "github") {
+      return parsed("origin", parts[1], parts[2], positiveInt(parts[4]));
+    }
+    if (parts.length >= 4) {
+      return parsed("origin", parts[1], parts[2], positiveInt(parts[3]));
+    }
+  }
+
+  return undefined;
+}

package/src/internal/sdk-runner.ts

@@ -16,6 +16,7 @@ import {
   createAgentPlatform,
   type LocalAgentStore,
   type ModelSelection,
+  type Run,
   type RunResult,
   type SDKAgent,
 } from "@cursor/sdk";
@@ -29,11 +30,20 @@ import {
   type TurnUsage,
 } from "../types.js";
 import { mapSdkTokenUsage, usageTokenSum } from "./cloud-turn-cost.js";
+import type { ConversationMirror } from "./conversation-mirror.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
+import { describeError } from "./describe-error.js";
+
+/** Mirrors @cursor/sdk's SteerAckOutcome; the published dist may predate it. */
+export type SteerAckOutcome = "complete_delivered" | "revert_to_followup";
 
 /** Internal seam between the session engine and the Cursor SDK harness. */
 export interface AgentRunner {
   runTurn(request: RunnerTurnRequest): Promise<TurnOutcome>;
+  steer?(request: {
+    sessionId: string;
+    text: string;
+  }): Promise<SteerAckOutcome>;
   /**
    * Resolve a local workspace before any session needs it, so the first turn
    * is not the one that pays for it. Best effort, hence the reported outcome:
@@ -117,6 +127,13 @@ export interface CursorSdkRunnerOptions {
    * `LocalAgentStore` for heavy multi-session concurrency.
    */
   store?: LocalAgentStore;
+  /**
+   * Durable mirror for local conversations (v2 hosted engines). Hydrated
+   * before `Agent.resume` so a follow-up landing on a fresh pod finds the
+   * conversation, and persisted — awaited — after each local turn settles,
+   * because a hosted pod can be parked right after the execution reply.
+   */
+  conversationMirror?: ConversationMirror;
   /** Diagnostics for degraded paths (resume-miss fallback). */
   logger?: (line: string) => void;
   /**
@@ -185,6 +202,7 @@ function retryReason(
 
 export class CursorSdkRunner implements AgentRunner {
   private readonly agents = new Map<string, CachedAgentHandle>();
+  private readonly activeRuns = new Map<string, Run>();
   private readonly stores = new Map<string, Promise<LocalAgentStore>>();
   private readonly prewarmReleases: Array<() => Promise<void>> = [];
 
@@ -314,6 +332,7 @@ export class CursorSdkRunner implements AgentRunner {
       ) {
         await request.onRequestId(run.requestId);
       }
+      this.activeRuns.set(request.sessionId, run);
       try {
         const result = await run.wait();
         let outcome = toTurnOutcome(result);
@@ -338,7 +357,25 @@ export class CursorSdkRunner implements AgentRunner {
         }
         return outcome;
       } finally {
+        if (this.activeRuns.get(request.sessionId) === run) {
+          this.activeRuns.delete(request.sessionId);
+        }
         signal?.removeEventListener("abort", onAbort);
+        // Mirror the conversation before replying: on hosted v2 the pod can
+        // be parked as soon as the execution reply lands, so a
+        // fire-and-forget write would race VM teardown. In the `finally` so
+        // a `wait()` that THROWS (transport death mid-turn, an abort with
+        // no follow-up) still persists the checkpoints the turn already
+        // wrote — the store is local SQLite, safe to read on the throw
+        // path, and persistConversation swallows its own errors. Guarded
+        // here (not just inside the helper) so unmirrored turns keep their
+        // exact post-wait sequencing.
+        if (
+          request.runtime === "local" &&
+          this.options.conversationMirror !== undefined
+        ) {
+          await this.persistConversation(request, agent.agentId);
+        }
       }
     } catch (error) {
       // Drop the cached agent so a dead Connect/HTTP2 session cannot poison
@@ -348,6 +385,28 @@ export class CursorSdkRunner implements AgentRunner {
     }
   }
 
+  async steer(request: {
+    sessionId: string;
+    text: string;
+  }): Promise<SteerAckOutcome> {
+    const run = this.activeRuns.get(request.sessionId) as
+      | (Run & {
+          steer?: (text: string) => Promise<SteerAckOutcome>;
+        })
+      | undefined;
+    if (run?.steer === undefined) {
+      return "revert_to_followup";
+    }
+    try {
+      return await run.steer(request.text);
+    } catch (error) {
+      this.log(
+        `[agent-sdk] session ${request.sessionId}: steer failed: ${describeError(error)}`
+      );
+      return "revert_to_followup";
+    }
+  }
+
   /**
    * Build the local executor for a workspace before any session asks for it.
    * The warmed executor is reference counted, so the lease is held until
@@ -469,6 +528,9 @@ export class CursorSdkRunner implements AgentRunner {
   private async buildLocalOptions(
     request: RunnerPrewarmRequest
   ): Promise<AgentOptions> {
+    // Not resolveStore: an injected store is used synchronously (no
+    // microtask, no thenable assimilation), exactly as before the mirror
+    // existed.
     const store =
       this.options.store ?? (await this.getStore(request.runnerStateDir));
     return {
@@ -507,6 +569,15 @@ export class CursorSdkRunner implements AgentRunner {
     }
 
     const agentId = request.sdkAgentId ?? request.sessionId;
+    const mirror = this.options.conversationMirror;
+    if (mirror !== undefined) {
+      // Host replacement: restore the conversation from the durable mirror
+      // before resuming, so the thread continues instead of starting fresh.
+      // A sink failure propagates and fails the turn (retryable) — reading
+      // an outage as "nothing mirrored" would silently fork the thread.
+      const store = await this.resolveStore(request);
+      await mirror.hydrate(store, agentId);
+    }
     try {
       return await Agent.resume(agentId, options);
     } catch (error) {
@@ -570,6 +641,38 @@ export class CursorSdkRunner implements AgentRunner {
     return Agent.create(options);
   }
 
+  private resolveStore(
+    request: Pick<RunnerPrewarmRequest, "runnerStateDir">
+  ): Promise<LocalAgentStore> {
+    return this.options.store !== undefined
+      ? Promise.resolve(this.options.store)
+      : this.getStore(request.runnerStateDir);
+  }
+
+  /**
+   * Mirror the settled turn's conversation. Persist failures are logged and
+   * dropped — a durable-mirror outage must not fail a turn that already ran.
+   */
+  private async persistConversation(
+    request: RunnerTurnRequest,
+    sdkAgentId: string
+  ): Promise<void> {
+    const mirror = this.options.conversationMirror;
+    if (mirror === undefined) {
+      return;
+    }
+    try {
+      const store = await this.resolveStore(request);
+      await mirror.persist(store, sdkAgentId);
+    } catch (error) {
+      this.log(
+        `[agent-sdk] conversation mirror: persist for ${sdkAgentId} failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+
   private getStore(stateDir: string): Promise<LocalAgentStore> {
     let storePromise = this.stores.get(stateDir);
     if (storePromise === undefined) {

package/src/internal/server.ts

@@ -51,6 +51,7 @@ import type {
   ServeOptions,
 } from "../types.js";
 import { V2EngineError } from "./continuation-identity.js";
+import { selectConversationMirror } from "./conversation-mirror.js";
 import {
   type CursorAccountConnectionRef,
   CursorAccountMcpBridge,
@@ -516,12 +517,21 @@ export async function startServer(
       "[agent-sdk] warning: --allow-anonymous admits every HTTP caller as the same principal; use only on a trusted network (e.g. Tailscale) and prefer --bearer-token for shared hosts"
     );
   }
+  // v2 hosted engines mirror the SDK conversation store to the deployment's
+  // shared file storage so a fresh pod resumes threads instead of forking
+  // them. Hosted serve is single-agent; a multi-mount serve (dev) has no
+  // single agent name to mint keys under and does not mirror.
+  const conversationMirror =
+    mounts.length === 1 && mounts[0] !== undefined
+      ? selectConversationMirror({ project: mounts[0].project, logger })
+      : undefined;
   const sdkRunner =
     options.runner ??
     new CursorSdkRunner({
       ...(options.apiKey === undefined || options.apiKey.trim() === ""
         ? {}
         : { apiKey: options.apiKey }),
+      ...(conversationMirror === undefined ? {} : { conversationMirror }),
       logger,
     });
   // Grok Bot turns run on Cursor's hosted Grok Bot (Sand) harness through
@@ -1276,6 +1286,8 @@ function mountAgentRoutes(
           channelId,
           hostedSessionId,
         }),
+      drainSessionDurability: (sessionId) =>
+        engine.drainSessionDurability(sessionId),
     });
   }
   // Playground lists/opens Slack (and other channel) sessions across

package/src/internal/session-engine.ts

@@ -113,6 +113,10 @@ import {
   createHostSlackClient,
   type HostPlatforms,
 } from "./host-platforms.js";
+import {
+  HostedAdmissionLocalSendError,
+  isDuringHostedAdmission,
+} from "./hosted-admission-context.js";
 import {
   formatContinuationToken,
   newContinuationKey,
@@ -132,10 +136,11 @@ import {
   SCHEDULE_CHANNEL_PREFIX,
 } from "./prompt-context.js";
 import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections.js";
-import type { AgentRunner } from "./sdk-runner.js";
+import type { AgentRunner, SteerAckOutcome } from "./sdk-runner.js";
 import { sessionExternalLinks } from "./session-links.js";
 import { SessionStore } from "./session-store.js";
 import { syncSkillsToStore } from "./skills-sync.js";
+import { steeringEnabled } from "./steering.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
 import type { FrameworkSessionStore } from "./storage-roles.js";
 import { decideToolCall, resolveEffect } from "./tool-policy.js";
@@ -465,6 +470,7 @@ export class SessionEngine {
     // for why the choice does not belong to the agent author.
     const frameworkStorage = selectFrameworkStorageDefinition({
       authored: options.project.storage,
+      architecture: options.project.agent.architecture,
     });
     this.storage =
       frameworkStorage === undefined
@@ -693,6 +699,9 @@ export class SessionEngine {
     ) {
       return;
     }
+    if (steeringEnabled()) {
+      return;
+    }
     try {
       await materializeSlackNudgeCarrier({
         harnessCwd,
@@ -811,6 +820,13 @@ export class SessionEngine {
     message: string,
     options: EngineSendOptions = {}
   ): Promise<ChannelSession> {
+    if (isDuringHostedAdmission()) {
+      // Only sends that bypassed the admission capture stub (typically a
+      // startup-captured `onStart` send) reach the engine inside the
+      // admission window; running one would leak an invisible local session
+      // on a sessionless pod.
+      throw new HostedAdmissionLocalSendError();
+    }
     const identity =
       channelId === HTTP_CHANNEL_ID
         ? httpContinuationIdentity(this.project.httpChannel)
@@ -1347,18 +1363,52 @@ export class SessionEngine {
     });
   }
 
+  private async steerIntoRunningTurn(
+    sessionId: string,
+    message: string
+  ): Promise<SteerAckOutcome> {
+    if (this.runner.steer === undefined) {
+      return "revert_to_followup";
+    }
+    try {
+      return await this.runner.steer({ sessionId, text: message });
+    } catch (error) {
+      this.logger(
+        `[session] steer failed for ${sessionId}: ${describeError(error)}`
+      );
+      return "revert_to_followup";
+    }
+  }
+
   private async admitTurn(
     sessionId: string,
     message: string,
     options: AdmitTurnOptions = {}
   ): Promise<boolean> {
     const admission = options.admission ?? "preempt";
+    if (
+      admission === "coalesce" &&
+      steeringEnabled() &&
+      this.isTurnRunning(sessionId)
+    ) {
+      const toolCtx = this.activeToolContexts.get(sessionId);
+      const steerOutcome = await this.steerIntoRunningTurn(sessionId, message);
+      if (steerOutcome === "complete_delivered") {
+        this.logger(`[session] steered into running turn ${sessionId}`);
+        if (toolCtx !== undefined) {
+          toolCtx.emit({ type: "message.received", data: { text: message } });
+          toolCtx.emit({ type: "nudge.delivered", data: {} });
+        }
+        return true;
+      }
+    }
+    // Re-checked after the steer: a turn that ended during it falls through
+    // and this message starts the next turn itself. Enqueueing here instead
+    // would orphan it — the completion drain already ran.
     if (admission === "coalesce" && this.isTurnRunning(sessionId)) {
       this.enqueueCoalesced(sessionId, {
         message,
-        ...(options.sourceTs === undefined
-          ? {}
-          : { sourceTs: options.sourceTs }),
+        sourceTs: options.sourceTs,
       });
       this.logger(`[session] coalesce enqueue ${sessionId}`);
       return true;
@@ -3382,6 +3432,28 @@ export class SessionEngine {
   // Session handles
   // ==========================================================================
 
+  /**
+   * Wait until everything this session has already emitted is durably
+   * mirrored: its dispatch chain first (the chain's tail runs the turn-end
+   * storage flush, so the record carries the boundary event's handler
+   * mutations), then the storage delivery queue. Hosted v2 awaits this
+   * before the execution reply — the pod can be parked the moment the
+   * reply lands, and an unflushed session record would strand a
+   * conversation whose blobs persisted but whose record (which selects the
+   * conversation to hydrate) never reached the sink. No-op without a
+   * storage mirror.
+   */
+  async drainSessionDurability(sessionId: string): Promise<void> {
+    if (this.storage === undefined) {
+      return;
+    }
+    const chain = this.dispatchChains.get(sessionId);
+    if (chain !== undefined) {
+      await chain.catch(() => {});
+    }
+    await this.storage.whenIdle();
+  }
+
   async waitForCompletion(sessionId: string): Promise<TurnOutcome> {
     // Drain admission first so pendingTurns → activeTurns is visible before we
     // decide the session is idle (reminders use this for queueBehindTurn).

package/src/internal/steering.ts

@@ -0,0 +1,17 @@
+/**
+ * Deploy-time switch between the two mid-turn follow-up carriers.
+ *
+ * With ENABLE_STEERING set ("1"/"true"), a Slack follow-up arriving mid-turn
+ * is steered into the running turn via Run.steer and the nudge-carrier file
+ * store is left uninstalled. Unset (the default), the pre-steering behavior
+ * is fully preserved: the carrier is materialized and follow-ups ride the
+ * nudge store to the running turn's next tool boundary.
+ *
+ * Read per call rather than cached so tests can flip it, and because this is
+ * a rollout switch: once steering has proven out in production the flag and
+ * the carrier both go away.
+ */
+export function steeringEnabled(): boolean {
+  const value = process.env.ENABLE_STEERING?.trim().toLowerCase();
+  return value === "1" || value === "true";
+}

package/src/storage-backends/cursor-hosted.ts

@@ -76,6 +76,14 @@ export interface CursorHostedStorageOptions {
   baseUrl?: string;
   /** Bearer credential (default: `CURSOR_API_KEY`). */
   apiKey?: string;
+  /**
+   * Lazy credential, re-resolved on every call and preferred over
+   * {@link apiKey}: hosted freeze snapshots listen unsigned and bind the
+   * key file after serve start, so a value captured at construct time
+   * would be permanently absent. Used by the platform-selected v2
+   * defaults; kept separate so `apiKey` stays a plain string for authors.
+   */
+  resolveApiKey?: () => string | undefined;
   /** Injected for tests. */
   fetch?: typeof fetch;
 }
@@ -180,7 +188,8 @@ function toCasResult(response: KvCasResponse): KvCasResult {
 }
 
 function resolveApiKey(options: CursorHostedStorageOptions): string {
-  const key = (options.apiKey ?? process.env.CURSOR_API_KEY)?.trim();
+  const configured = options.resolveApiKey?.() ?? options.apiKey;
+  const key = (configured ?? process.env.CURSOR_API_KEY)?.trim();
   if (key === undefined || key === "") {
     throw new Error(
       "cursorHostedStorage requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)"

package/src/types.ts

@@ -1262,7 +1262,8 @@ export type ConnectionConfig = (
    * Local runtime only, like all server tools: a `runtime: "cloud"` agent
    * fails discovery, and hybrid per-send cloud sessions refuse the turn.
    * The listing runs once per turn; point this at endpoints that can
-   * answer `tools/list` cheaply.
+   * answer `tools/list` cheaply. Tools whose MCP `annotations.title` is
+   * `do-not-call` are omitted (vendor host-UI / MCP Apps helpers).
    */
   advertiseTools?: boolean;
   /**

package/templates/agentic-owners/README.md

@@ -58,7 +58,7 @@ policy only) opts paths out entirely.
 - One model turn per PR head assesses the diff against the base rubric
   (`agent/lib/owners/prompts/base-review.md`) plus matched rule prompts.
 - The model records a verdict with `record_review`; the host recomputes
-  the policy and applies the deterministic decision — approve, or request
+  the policy and applies the deterministic decision: approve, or request
   the policy owners (max 2, never the author) and leave one comment it
   keeps updated.
 - The model never writes to GitHub. Broken policy files fail closed with

package/templates/agentic-owners/agent/agent.ts

@@ -1,18 +1,8 @@
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
-  model: {
-    id: "grok-4.5",
-    params: [
-      { id: "effort", value: "high" },
-      { id: "fast", value: "true" },
-    ],
-  },
   tools: ["read", "grep", "glob", "ls"],
   local: {
     sandbox: true,
-    cwd: join(homedir(), ".cache", "agent-serve", "agentic-owners"),
   },
 });

package/templates/agentic-owners/agent/channels/github.ts

@@ -22,10 +22,8 @@ const REVIEW_ACTIONS = new Set([
 let log: (line: string) => void = () => {};
 
 export default githubChannel({
-  // With repos configured, the signed-in Cursor account supplies both the
-  // PR event stream and a repo-scoped GitHub credential — no webhook or
-  // GitHub App setup. Empty repos boots without the binding so a fresh
-  // scaffold's `dev` / `eval` run; use `agent-sdk github replay` there.
+  // Empty `repos` skips the Cursor GitHub binding so `dev` / `eval` boot
+  // on a fresh scaffold.
   cursorAccount: config.repos.length > 0 ? { repos: config.repos } : undefined,
   // The model never writes to GitHub; record_review actuates host-side.
   deliverReplies: false,
@@ -33,9 +31,7 @@ export default githubChannel({
     log = (line) => args.logger(`[agentic-owners] ${line}`);
   },
   onPullRequest: async (ctx, pr) => {
-    // A base retarget re-resolves the policy against the new base: the diff
-    // and the governing policy files both changed, so the old verdict — and
-    // any approval it produced — no longer covers this PR. The fresh
+    // A base retarget re-resolves policy against the new base. The fresh
     // actuation dismisses a leftover approve when the new decision holds.
     const baseRetargeted =
       pr.action === "edited" && pr.baseRefChangedFrom !== undefined;
@@ -54,9 +50,8 @@ export default githubChannel({
     try {
       const state = await loadReviewState(forge, log);
       if (!state.enrolled) {
-        // Enrollment can end while an agent approval is live (base retarget,
-        // owned files dropped); dismiss it instead of leaving it counting
-        // toward branch protection under a policy that never granted it.
+        // Enrollment can end while an agent approval is live; dismiss it
+        // instead of leaving it counting toward branch protection.
         return {
           task: () =>
             dismissStaleApprovals(
@@ -69,14 +64,10 @@ export default githubChannel({
         auth: defaultGitHubAuth(ctx),
         message: renderReviewWake(state),
         title: `Review ${ctx.repository.fullName}#${pr.number}`,
-        // Freeze the assessed head host-side: record_review reads this file
-        // instead of trusting a model-supplied SHA, so a mid-turn push (or a
-        // prompt-injected SHA) can never line up with the live head.
         workspaceFiles: { "pr/head.sha": state.pr.headSha },
       };
     } catch (error) {
       if (error instanceof AgenticOwnersConfigValidationError) {
-        // Fail closed but visibly: comment the issues, review nothing.
         return { task: () => reportPolicyError(forge, error) };
       }
       throw error;

package/templates/agentic-owners/agent/lib/config.ts

@@ -1,11 +1,3 @@
-/**
- * The one file to edit: which GitHub repositories the agent reviews.
- *
- * Setting it streams PR events and a repo-scoped GitHub credential through
- * your signed-in Cursor account (`agent-sdk login`) — no webhook or GitHub
- * App setup. While empty, the agent still runs locally against replayed
- * PRs (`agent-sdk github replay <pr-url>`).
- */
 const config = {
   repos: [] as string[], // e.g. ["acme/api"]
 };

package/templates/agentic-owners/agent/lib/review.ts

@@ -1,8 +1,5 @@
-// Policy resolution and actuation over the GitHub API — no repo checkout.
-// Every trusted input (policy files, rule prompts) is read from the PR's
-// **base ref**, so a PR cannot exempt itself by editing its own governance
-// files. Mirrors the Agentic Owners pipeline's `resolvePolicyForPr`, minus
-// the linguist-generated partition and content caching.
+// Policy files and rule prompts are read from the PR's base ref so a PR
+// cannot exempt itself by editing its own governance files.
 
 import {
   decideApproval,
@@ -297,12 +294,6 @@ export async function loadReviewState(
   };
 }
 
-/**
- * The model turn's wake message: composed rubric, PR context, and the
- * host-fetched diff. Fenced so author-controlled patch bytes cannot escape
- * into the trusted markdown (the fence outruns any backtick run inside the
- * patch).
- */
 /**
  * Filenames are author-controlled and render outside the diff fence: strip
  * control characters and backticks so a hostile path cannot fabricate
@@ -648,9 +639,6 @@ export async function actuateReview(input: {
   }).filter(
     (handle) => normalizeHandle(handle) !== normalizeHandle(pr.authorLogin ?? "")
   );
-  // The full decision — policy verdict plus the governance / evidence
-  // fail-closes — is computed in one place; from here on this function
-  // only writes.
   const decision = decideApproval({
     matchedRules: state.matchedRules,
     riskLevel: verdict.riskLevel,
@@ -742,7 +730,6 @@ export async function actuateReview(input: {
   const alreadyRequested = new Set(
     pr.requestedReviewers.map(normalizeHandle)
   );
-  // Adds fill only the remaining slots under the max-of-two rule.
   const newReviewers = decision.requestReviewers
     .filter((handle) => !alreadyRequested.has(normalizeHandle(handle)))
     .slice(

package/templates/agentic-owners/agent/tools/record_review.ts

@@ -41,10 +41,8 @@ export default defineTool({
           "not a GitHub pull-request session — reviews start from the github channel (agent-sdk github replay <pr-url> to test locally)",
       };
     }
-    // The channel wake froze the assessed head into the session workspace.
-    // Reading it here (instead of accepting a model-supplied SHA) means a
-    // mid-turn push can never line up with the live head: the actuation
-    // compares wake-observed against live and skips on any mismatch.
+    // Wake froze the assessed head into the session workspace. A model-supplied
+    // SHA is never trusted.
     let assessedHeadSha: string;
     try {
       assessedHeadSha = (