surf-cli 2.15.1 → 2.16.0

package/README.md

@@ -526,7 +526,7 @@ surf aistudio.build "game" --keep-open --timeout 600          # Keep tab open, 1
 
 #### Oracle
 
-Use `surf oracle` for a durable, local ChatGPT consult instead of a quick `surf chatgpt` one-shot. It persists jobs by conversation URL, supports repeatable file-context globs, and verifies requested model and reasoning effort before submission. ChatGPT model aliases include `instant`, `thinking`, `pro`, `gpt-5.5`, and `gpt-5.6-sol`; `pro` selects the current ChatGPT GPT-5.6 Sol Pro web mode.
+Use `surf oracle` for a durable, local ChatGPT consult instead of a quick `surf chatgpt` one-shot. It persists jobs by conversation URL, supports repeatable file-context globs, and verifies requested model and reasoning effort before submission. ChatGPT model aliases include `instant`, `thinking`, `pro`, `gpt-5.5`, and `gpt-5.6-sol`. Use `--model gpt-5.6-sol --effort pro` for GPT-5.6 Sol with Pro effort.
 
 ```bash
 surf oracle ask "review this change" --files "src/**/*.ts" --model gpt-5.5 --effort pro --detach --json
@@ -996,9 +996,9 @@ pi -e /path/to/surf-cli/pi-extension/surf.ts
 
 It registers `surf_read`, `surf_screenshot`, `surf_click`, `surf_type`, `surf_tool`, and the `surf_oracle_*` tools. Browser calls use Surf's native-host socket, not shell commands. If `pi-subagents/background-work` is installed, the extension also reports active oracle jobs started by that Pi session. Pi still loads the browser tools when pi-subagents is not installed.
 
-The extension also registers a `surf-oracle` external-job provider when a Pi runtime exposes that provider bridge. The provider implements pi-subagents' external-job contract: `start`, `status`, `result`, and `reattach` operations that return `providerJobId`, a contract state (`queued`, `running`, `completed`, `failed`), the durable conversation URL, the captured result text as `output`, and failure code and message when present. It reads `options.model` and `options.effort` for starts, so a Pi profile can request `model: pro` and reach the ChatGPT GPT-5.6 Sol Pro web mode through Surf. Capacity stays fail-closed: Surf returns the blocking job id instead of silently queueing a second ChatGPT job.
+The extension also registers a `surf-oracle` external-job provider when a Pi runtime exposes that provider bridge. The provider implements pi-subagents' external-job contract: `start`, `status`, `result`, and `reattach` operations that return `providerJobId`, a contract state (`queued`, `running`, `completed`, `failed`), the durable conversation URL, the captured result text as `output`, and failure code and message when present. It reads `options.model` and `options.effort` for starts, so a Pi profile can request `model: gpt-5.6-sol` plus `effort: pro` and reach ChatGPT GPT-5.6 Sol with Pro effort through Surf. Capacity stays fail-closed: Surf returns the blocking job id instead of silently queueing a second ChatGPT job.
 
-When Surf is installed as a Pi package, it also exposes an optional `gpt-pro` package agent for `pi-subagents`. That profile uses `runner.type: external-job`, provider `surf-oracle`, and `options.model: pro`. Surf remains useful without Pi or `pi-subagents`; the package agent only wires Surf's browser-backed model alias into Pi's agent picker.
+When Surf is installed as a Pi package, it also exposes an optional `gpt-pro` package agent for `pi-subagents`. That profile uses `runner.type: external-job`, provider `surf-oracle`, `options.model: gpt-5.6-sol`, and `options.effort: pro`. Surf remains useful without Pi or `pi-subagents`; the package agent only wires Surf's browser-backed model alias into Pi's agent picker.
 
 Shell-based agents should select a unique session with `SURF_SESSION` and call `surf session.ensure` before their first browser command. The optional Pi extension still uses its existing socket-tool interface; callers that coordinate several Pi workers should pass explicit tab targets until session selection is exposed by that integration.
 

package/agents/gpt-pro.md

@@ -5,7 +5,8 @@ runner:
   type: external-job
   provider: surf-oracle
   options:
-    model: pro
+    model: gpt-5.6-sol
+    effort: pro
 async: true
 systemPromptMode: replace
 inheritProjectContext: false

package/native/chatgpt-client-selection.cjs

@@ -4,7 +4,7 @@ const CHATGPT_MODEL_ALIASES = new Map([
   ["gpt53", "instant"],
   ["thinking", "thinking"],
   ["gpt54thinking", "thinking"],
-  ["pro", "gpt56sol"],
+  ["pro", "pro"],
   ["gpt54pro", "pro"],
   ["55", "gpt55"],
   ["gpt55", "gpt55"],

package/native/chatgpt-client-ui.cjs

@@ -191,11 +191,22 @@ async function readPicker(cdp, kind, click = false) {
     `(() => {
       ${buildClickDispatcher()}
       const kind = ${JSON.stringify(kind)};
-      const nodes = Array.from(document.querySelectorAll(${JSON.stringify(selector)})).filter((node) => {
+      let nodes = Array.from(document.querySelectorAll(${JSON.stringify(selector)})).filter((node) => {
         const value = ((node.getAttribute?.('aria-label') || '') + ' ' + (node.textContent || '')).toLowerCase();
-        if (kind === 'model') return value.includes('gpt') || value.includes('pro') || value.includes('thinking') || value.includes('instant');
-        return value.includes('thinking') || value.includes('pro');
+        if (kind !== 'model') return value.includes('thinking') || value.includes('pro');
+        return value.includes('gpt') || value.includes('thinking') || value.includes('instant');
       });
+      if (kind === 'model' && nodes.length === 0) {
+        nodes = Array.from(document.querySelectorAll(${JSON.stringify(selector)})).filter((node) => {
+          const value = ((node.getAttribute?.('aria-label') || '') + ' ' + (node.textContent || '')).toLowerCase();
+          return value.includes('pro');
+        });
+      }
+      if (kind === 'model' && nodes.length === 0) {
+        nodes = Array.from(document.querySelectorAll(${JSON.stringify(selector)})).filter((node) =>
+          node.getAttribute?.('aria-haspopup') === 'menu' || node.getAttribute?.('aria-expanded') !== null
+        );
+      }
       const items = nodes.map((node) => {
         const text = (node.textContent || '').replace(/\\s+/g, ' ').trim();
         const aria = (node.getAttribute?.('aria-label') || '').replace(/\\s+/g, ' ').trim();
@@ -329,6 +340,12 @@ async function selectModel(cdp, desiredModel, timeoutMs = 8000, signal) {
   if (picker?.items?.length !== 1) throw verificationError("model", desiredModel);
   await delay(300, signal);
   const menu = await waitForMenu(cdp, "model", timeoutMs, signal);
+  const currentAdvancedModel = verifyChatGPTModelSelection(
+    menu.items.filter((item) => /\bmodel\b/i.test(String(item?.label || ""))),
+    desiredModel,
+  );
+  if (currentAdvancedModel) return currentAdvancedModel.displayLabel || currentAdvancedModel.label;
+
   const match = resolveChatGPTModelMenuOption(menu.items, desiredModel);
   if (!match || !(await clickMenuItem(cdp, "model", match))) {
     throw verificationError("model", desiredModel, menu.items);

package/native/oracle-host.cjs

@@ -71,7 +71,9 @@ function createOracleHost({ queueAiRequest, requestCallExtension, buildProviderU
       model,
       effortRequested: args.effort ?? null,
       follow: args.follow ?? null,
+      requestId: args.requestId ?? null,
     });
+    if (created.requestDeduped) return oracleJobs.getJob(created.id);
     let createdTabId = null;
 
     try {
@@ -109,6 +111,8 @@ function createOracleHost({ queueAiRequest, requestCallExtension, buildProviderU
             oracleJobs.appendTurn(parent.id, {
               prompt: args.prompt,
               dispatchedAt: dispatchedJob.dispatchedAt,
+              childJobId: created.id,
+              requestId: args.requestId ?? null,
             });
           }
         },
@@ -259,6 +263,8 @@ function createOracleHost({ queueAiRequest, requestCallExtension, buildProviderU
         oracleJobs.markTurnCaptured(captured.follow, {
           dispatchedAt: captured.dispatchedAt,
           capturedAt: captured.capturedAt,
+          childJobId: captured.id,
+          requestId: captured.requestId ?? null,
         });
       }
       if (captured.tabId) {

package/native/oracle-jobs.cjs

@@ -39,6 +39,32 @@ function promptDigest(prompt) {
   return `sha256:${crypto.createHash("sha256").update(prompt).digest("hex")}`;
 }
 
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+function requestFingerprint({ prompt, contextManifest, model, effortRequested, follow }) {
+  return promptDigest(stableJson({
+    promptDigest: promptDigest(prompt),
+    contextManifest: contextManifest ?? {},
+    model: model ?? null,
+    effortRequested: effortRequested ?? null,
+    follow: follow ?? null,
+  }));
+}
+
+function normalizedRequestId(requestId) {
+  if (requestId === null || requestId === undefined) return null;
+  if (typeof requestId !== "string" || !requestId.trim() || requestId.trim() !== requestId || requestId.length > 256 || requestId.includes("\0")) {
+    throw codedError("invalid_request", "oracle requestId must be a non-empty trimmed string");
+  }
+  return requestId;
+}
+
 function hydrateJobMetadata(job, root = getPrivateStateRoot()) {
   const prompt = job.promptDigest ? null : readPrivateFile(path.join(jobDirectory(job.id, root), "request.md"), {
     root,
@@ -66,10 +92,27 @@ function readJobs(root = getPrivateStateRoot()) {
     .map((job) => hydrateJobMetadata(job, root));
 }
 
-function createJob({ prompt, contextManifest = {}, model = null, effortRequested = null, follow = null }) {
+function createJob({ prompt, contextManifest = {}, model = null, effortRequested = null, follow = null, requestId = null }) {
   const root = getPrivateStateRoot();
   const base = oracleRoot(root);
   ensurePrivateDir(base, root);
+  const safeRequestId = normalizedRequestId(requestId);
+  const fingerprint = safeRequestId
+    ? requestFingerprint({ prompt, contextManifest, model, effortRequested, follow })
+    : null;
+  if (safeRequestId) {
+    const existing = readJobs(root).find((job) => job.requestId === safeRequestId);
+    if (existing) {
+      if (existing.requestFingerprint !== fingerprint) {
+        throw codedError(
+          "idempotency_conflict",
+          `oracle requestId ${safeRequestId} was already used for a different request`,
+          { jobId: existing.id },
+        );
+      }
+      return { ...existing, requestDeduped: true };
+    }
+  }
   const inFlight = readJobs(root).find((job) => !TERMINAL_STATES.has(job.state));
   if (inFlight) {
     throw codedError(
@@ -108,6 +151,7 @@ function createJob({ prompt, contextManifest = {}, model = null, effortRequested
       effortRequested,
       effortVerified: null,
       promptDigest: promptDigest(prompt),
+      ...(safeRequestId ? { requestId: safeRequestId, requestFingerprint: fingerprint } : {}),
       createdAt: now.toISOString(),
       dispatchedAt: null,
       awaitingAt: null,
@@ -215,10 +259,14 @@ function updateTabId(id, tabId) {
 
 function appendTurn(id, turn) {
   const job = getJob(id);
+  const duplicate = job.turns.find((existing) => (turn.childJobId && existing.childJobId === turn.childJobId) || (turn.requestId && existing.requestId === turn.requestId));
+  if (duplicate) return job;
   const storedTurn = {
     prompt: turn.prompt,
     dispatchedAt: turn.dispatchedAt ?? null,
     capturedAt: turn.capturedAt ?? null,
+    ...(turn.childJobId ? { childJobId: turn.childJobId } : {}),
+    ...(turn.requestId ? { requestId: turn.requestId } : {}),
   };
   const root = getPrivateStateRoot();
   const directory = jobDirectory(id, root);
@@ -229,9 +277,9 @@ function appendTurn(id, turn) {
   return updated;
 }
 
-function markTurnCaptured(id, { dispatchedAt, capturedAt }) {
+function markTurnCaptured(id, { dispatchedAt, capturedAt, childJobId, requestId }) {
   const job = getJob(id);
-  const turnIndex = job.turns.findIndex((turn) => turn.dispatchedAt === dispatchedAt);
+  const turnIndex = job.turns.findIndex((turn) => (childJobId && turn.childJobId === childJobId) || (requestId && turn.requestId === requestId) || turn.dispatchedAt === dispatchedAt);
   if (turnIndex === -1) {
     throw codedError(
       "invalid_transition",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.15.1",
+  "version": "2.16.0",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",

package/pi-extension/surf.ts

@@ -43,15 +43,10 @@ type ToolResult = { content: Array<{ type: "text" | "image"; text?: string; data
 type OracleJob = {
   id: string;
   state: string;
-  conversationUrl?: string | null;
-  model?: string | null;
-  modelRequested?: string | null;
-  modelVerified?: string | null;
-  effortRequested?: string | null;
-  effortVerified?: string | null;
-  promptDigest?: string | null;
+  conversationUrl: string | null;
+  follow: string | null;
   response?: string;
-  error?: { code?: string; message?: string } | null;
+  error: { code?: string; message?: string } | null;
 };
 
 type BackgroundWorkProvider = {
@@ -75,6 +70,7 @@ type OracleExternalJob = {
   id: string;
   state: string;
   conversationUrl: string | null;
+  follow?: string;
   resultText?: string;
   failure?: { code: string; message: string };
 };
@@ -97,6 +93,7 @@ type OracleExternalJobProvider = {
   status(id: string): Promise<PiExternalJobHandle>;
   result(id: string): Promise<PiExternalJobResult>;
   reattach(id: string): Promise<PiExternalJobHandle>;
+  followUp?(input: Record<string, unknown>): Promise<PiExternalJobHandle>;
 };
 
 type RegisterExternalJobProvider = (provider: OracleExternalJobProvider) => () => void;
@@ -257,11 +254,40 @@ export async function resolveExternalJobProviderRegister(
   return registerGlobalExternalJobProvider;
 }
 
+function optionalOracleString(value: unknown, field: string): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") throw new Error(`Surf oracle response included an invalid ${field}`);
+  return value;
+}
+
+function oracleFailure(value: unknown): OracleJob["error"] {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Surf oracle response included invalid failure details");
+  }
+  const details = value as Record<string, unknown>;
+  const code = optionalOracleString(details.code, "failure code");
+  const message = optionalOracleString(details.message, "failure message");
+  return { ...(code === undefined ? {} : { code }), ...(message === undefined ? {} : { message }) };
+}
+
 function asOracleJob(value: unknown): OracleJob {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Surf oracle response did not include job metadata");
-  const job = value as Partial<OracleJob>;
-  if (typeof job.id !== "string" || typeof job.state !== "string") throw new Error("Surf oracle response did not include job id and state");
-  return job as OracleJob;
+  const job = value as Record<string, unknown>;
+  if (typeof job.id !== "string" || !job.id || job.id.trim() !== job.id || typeof job.state !== "string") {
+    throw new Error("Surf oracle response did not include a valid job id and state");
+  }
+  const conversationUrl = optionalOracleString(job.conversationUrl, "conversation URL");
+  const follow = optionalOracleString(job.follow, "follow job id");
+  const response = optionalOracleString(job.response, "result text");
+  return {
+    id: job.id,
+    state: job.state,
+    conversationUrl: conversationUrl ?? null,
+    follow: follow ?? null,
+    error: oracleFailure(job.error),
+    ...(response === undefined ? {} : { response }),
+  };
 }
 
 function oracleExternalJob(job: OracleJob): OracleExternalJob {
@@ -273,6 +299,7 @@ function oracleExternalJob(job: OracleJob): OracleExternalJob {
     id: job.id,
     state: job.state,
     conversationUrl: job.conversationUrl ?? null,
+    ...(typeof job.follow === "string" ? { follow: job.follow } : {}),
     ...(resultText === undefined ? {} : { resultText }),
     ...(failure ? { failure } : {}),
   };
@@ -333,6 +360,7 @@ async function requestOracleJob(request: typeof requestSurf, tool: string, args:
 }
 
 function emitFailedOracleJob(error: unknown, emitTerminal: EmitOracleJob) {
+  if (error && typeof error === "object" && "code" in error && error.code === "SURF_REQUEST_ABORTED") return;
   if (!error || typeof error !== "object" || !("jobId" in error) || typeof error.jobId !== "string") return;
   emitTerminal({ id: error.jobId, state: "failed" });
 }
@@ -347,8 +375,41 @@ function oracleOption(input: Record<string, unknown>, key: "model" | "effort"):
   return typeof direct === "string" ? direct : undefined;
 }
 
+function optionalString(input: Record<string, unknown>, key: string): string | undefined {
+  const value = input[key];
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function parentProviderJobId(input: Record<string, unknown>): string {
+  const id = optionalString(input, "parentProviderJobId") ?? optionalString(input, "providerJobId");
+  if (!id) throw new Error("parentProviderJobId required");
+  return id;
+}
+
+function assertFollowJob(job: OracleExternalJob, parentId: string) {
+  if (job.id === parentId) throw new Error(`Surf oracle follow-up reused parent job '${parentId}'`);
+  if (job.follow !== parentId) throw new Error(`Surf oracle follow-up job '${job.id}' is not linked to parent '${parentId}'`);
+}
+
+const ORACLE_STATUS_HARVEST_TIMEOUT_SECONDS = 5;
+
+async function requestOracleJobStatus(request: typeof requestSurf, id: string) {
+  try {
+    return await requestOracleJob(request, "oracle.result", {
+      id,
+      timeout: ORACLE_STATUS_HARVEST_TIMEOUT_SECONDS,
+    });
+  } catch (error) {
+    if (!error || typeof error !== "object") throw error;
+    if ("code" in error && error.code === "SURF_REQUEST_ABORTED") throw error;
+    if ("jobId" in error && error.jobId === id) {
+      return requestOracleJob(request, "oracle.status", { id });
+    }
+    throw error;
+  }
+}
+
 export function createOracleExternalJobProvider(
-  sessionId: string,
   jobIds: Set<string>,
   request: typeof requestSurf = requestSurf,
   rememberJob: RememberOracleJob = (jobId) => {
@@ -356,8 +417,9 @@ export function createOracleExternalJobProvider(
     return true;
   },
   emitTerminal: EmitOracleJob = () => false,
+  options: { followUp?: boolean } = {},
 ): OracleExternalJobProvider {
-  return {
+  const provider: OracleExternalJobProvider = {
     name: "surf-oracle",
     async start(input) {
       const prompt = typeof input.prompt === "string" ? input.prompt : "";
@@ -373,7 +435,9 @@ export function createOracleExternalJobProvider(
       return piExternalJobHandle(job);
     },
     async status(id) {
-      return piExternalJobHandle(await requestOracleJob(request, "oracle.status", { id }));
+      const job = await requestOracleJobStatus(request, id);
+      emitTerminal({ id: job.id, state: job.state });
+      return piExternalJobHandle(job);
     },
     result(id) {
       return requestOracleJob(request, "oracle.result", { id })
@@ -387,7 +451,7 @@ export function createOracleExternalJobProvider(
         });
     },
     reattach(id) {
-      return requestOracleJob(request, "oracle.result", { id })
+      return requestOracleJobStatus(request, id)
         .then((job) => {
           rememberJob(job.id);
           emitTerminal({ id: job.id, state: job.state });
@@ -399,6 +463,27 @@ export function createOracleExternalJobProvider(
         });
     },
   };
+  if (options.followUp) {
+    provider.followUp = async (input) => {
+      const prompt = typeof input.prompt === "string" ? input.prompt : "";
+      if (!prompt.trim()) throw new Error("prompt required");
+      const parentId = parentProviderJobId(input);
+      const model = oracleOption(input, "model");
+      const effort = oracleOption(input, "effort");
+      const requestId = optionalString(input, "requestId");
+      const job = await requestOracleJob(request, "oracle.ask", {
+        prompt,
+        follow: parentId,
+        ...(model !== undefined ? { model } : {}),
+        ...(effort !== undefined ? { effort } : {}),
+        ...(requestId !== undefined ? { requestId } : {}),
+      });
+      assertFollowJob(job, parentId);
+      rememberJob(job.id);
+      return piExternalJobHandle(job);
+    };
+  }
+  return provider;
 }
 
 export function registerOptionalBackgroundProvider(sessionId: string, jobIds: Set<string>, listJobs: () => Array<{ id: string; state: string }>, register: RegisterBackgroundWorkProvider) {
@@ -412,14 +497,21 @@ export function registerOptionalBackgroundProvider(sessionId: string, jobIds: Se
 }
 
 export function registerOptionalExternalJobProvider(
-  sessionId: string,
   jobIds: Set<string>,
   register: RegisterExternalJobProvider,
   request: typeof requestSurf = requestSurf,
   rememberJob?: RememberOracleJob,
   emitTerminal?: EmitOracleJob,
 ) {
-  return register(createOracleExternalJobProvider(sessionId, jobIds, request, rememberJob, emitTerminal));
+  const provider = createOracleExternalJobProvider(jobIds, request, rememberJob, emitTerminal, { followUp: true });
+  try {
+    return register(provider);
+  } catch (error) {
+    if (String(error instanceof Error ? error.message : error).includes("followUp")) {
+      return register(createOracleExternalJobProvider(jobIds, request, rememberJob, emitTerminal));
+    }
+    throw error;
+  }
 }
 
 export function rememberOracleJobForSession(jobIds: Set<string>, jobId: unknown, requestGeneration: number, currentGeneration: number, sessionActive: boolean): boolean {
@@ -533,7 +625,7 @@ export default function surfExtension(pi: Pi) {
       const rememberForGeneration = (jobId: string) => rememberOracleJobForSession(oracleJobIds, jobId, generation, sessionGeneration, sessionActive);
       const emitFinished = (job: Pick<OracleExternalJob, "id" | "state">) => emitOracleFinished(pi, job);
       dispose = registerOptionalBackgroundProvider(sessionId, oracleJobIds, jobs.listJobs, registerGlobalBackgroundProvider);
-      disposeExternal = registerOptionalExternalJobProvider(sessionId, oracleJobIds, registerGlobalExternalJobProvider, requestSurf, rememberForGeneration, emitFinished);
+      disposeExternal = registerOptionalExternalJobProvider(oracleJobIds, registerGlobalExternalJobProvider, requestSurf, rememberForGeneration, emitFinished);
       sessionActive = true;
       void resolveBackgroundWorkRegister().then((register) => {
         try {
@@ -552,7 +644,7 @@ export default function surfExtension(pi: Pi) {
       void resolveExternalJobProviderRegister().then((register) => {
         try {
           if (register === registerGlobalExternalJobProvider || generation !== sessionGeneration) return;
-          const nextDispose = registerOptionalExternalJobProvider(sessionId, oracleJobIds, register, requestSurf, rememberForGeneration, emitFinished);
+          const nextDispose = registerOptionalExternalJobProvider(oracleJobIds, register, requestSurf, rememberForGeneration, emitFinished);
           if (generation !== sessionGeneration) {
             nextDispose();
             return;

package/skills/surf/SKILL.md

@@ -112,11 +112,11 @@ surf oracle result <job-id> --wait --json
 
 `status` reads persisted state without touching Chrome. `result` attempts to harvest the answer and returns the job object with `response` once its state is `captured`. A Ctrl-C during waiting exits with status 130 and prints `Recover with: surf oracle result <id>`. Once the job is `awaiting`, the persisted ChatGPT conversation URL is its durable key, so `surf oracle result <id>` can recover after CLI exit, native-host restart, or Chrome restart by reopening that conversation.
 
-Treat Pro quota as scarce. Oracle never selects Pro implicitly; request it with `--model pro` or `--effort pro`. ChatGPT model aliases include `instant`, `thinking`, `pro`, `gpt-5.5`, and `gpt-5.6-sol`. Accepted `--effort` values are `light`, `standard`, `extended`, `heavy`, and `pro`. Requested model and effort selections are read back before submission, and an unverifiable selection fails with `model_verification_failed` instead of silently continuing. Capacity is one non-terminal oracle job. A `capacity` error includes the in-flight job ID; poll that job or wait for it to finish rather than submitting the same consult again.
+Treat Pro quota as scarce. Oracle never selects Pro effort implicitly; request it with `--effort pro`. ChatGPT model aliases include `instant`, `thinking`, `pro`, `gpt-5.5`, and `gpt-5.6-sol`. Accepted `--effort` values are `light`, `standard`, `extended`, `heavy`, and `pro`. Use `--model gpt-5.6-sol --effort pro` for GPT-5.6 Sol with Pro effort. Requested model and effort selections are read back before submission, and an unverifiable selection fails with `model_verification_failed` instead of silently continuing. Capacity is one non-terminal oracle job. A `capacity` error includes the in-flight job ID; poll that job or wait for it to finish rather than submitting the same consult again.
 
-When loaded as a Pi extension, Surf also registers a `surf-oracle` external-job provider when the runtime exposes that bridge. The provider maps `start`, `status`, `result`, and `reattach` to durable Surf Oracle jobs and returns pi-subagents' external-job contract shape: `providerJobId`, a contract state (`queued`, `running`, `completed`, `failed`), the conversation URL, the captured result text as `output`, and failure code and message. It honors `options.model` and `options.effort` for starts, so `model: pro` selects ChatGPT GPT-5.6 Sol Pro web mode through the browser. `reattach` only harvests an existing job by ID; it never submits the prompt again.
+When loaded as a Pi extension, Surf also registers a `surf-oracle` external-job provider when the runtime exposes that bridge. The provider maps `start`, `status`, `result`, and `reattach` to durable Surf Oracle jobs and returns pi-subagents' external-job contract shape: `providerJobId`, a contract state (`queued`, `running`, `completed`, `failed`), the conversation URL, the captured result text as `output`, and failure code and message. It honors `options.model` and `options.effort` for starts, so `model: gpt-5.6-sol` plus `effort: pro` selects ChatGPT GPT-5.6 Sol with Pro effort through the browser. `reattach` only harvests an existing job by ID; it never submits the prompt again.
 
-When Surf is installed as a Pi package, it exposes an optional `gpt-pro` package agent for `pi-subagents`. That profile uses `runner.type: external-job`, provider `surf-oracle`, and `options.model: pro`. Surf remains useful without Pi or `pi-subagents`.
+When Surf is installed as a Pi package, it exposes an optional `gpt-pro` package agent for `pi-subagents`. That profile uses `runner.type: external-job`, provider `surf-oracle`, `options.model: gpt-5.6-sol`, and `options.effort: pro`. Surf remains useful without Pi or `pi-subagents`.
 
 Context comes from repeatable `--files` globs. Surf fails closed when a glob matches nothing or a matched file is unreadable, binary, or invalid UTF-8. It also blocks gitignored files and basenames matching `.env*`, `*.pem`, `*.key`, `id_rsa*`, `id_ed25519*`, `*.p12`, `*.pfx`, `credentials*`, or `secrets*`. Use `--allow-sensitive` only after intentionally reviewing those files; it overrides the block rather than redacting content. Context up to 60,000 evidence characters is inserted inline, while larger context becomes one private text attachment. The assembly manifest records each path, byte count, SHA-256, inline or bundle disposition, and deny-list outcome.