pi-oracle 0.1.11 → 0.2.0

package/extensions/oracle/lib/tools.ts

@@ -2,44 +2,58 @@ import { randomUUID } from "node:crypto";
 import { lstat, mkdtemp, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join, posix } from "node:path";
-import { StringEnum } from "@mariozechner/pi-ai";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import { isLockTimeoutError, withGlobalReconcileLock, withLock } from "./locks.js";
 import { loadOracleConfig, EFFORTS, MODEL_FAMILIES, type OracleEffort, type OracleModelFamily } from "./config.js";
 import {
+  appendCleanupWarnings,
   cancelOracleJob,
   createJob,
+  getJobDir,
   getSessionFile,
-  isActiveOracleJob,
+  hasDurableWorkerHandoff,
+  isOpenOracleJob,
+  isTerminalOracleJob,
+  listOracleJobDirs,
+  markWakeupSettled,
   readJob,
   pruneTerminalOracleJobs,
   reconcileStaleOracleJobs,
   resolveArchiveInputs,
   sha256File,
+  shouldAdvanceQueueAfterCancellation,
   spawnWorker,
+  terminateWorkerPid,
   updateJob,
   withJobPhase,
+  type OracleJob,
 } from "./jobs.js";
+import { getQueuePosition, promoteQueuedJobs, promoteQueuedJobsWithinAdmissionLock } from "./queue.js";
 import { refreshOracleStatus } from "./poller.js";
 import {
-  acquireConversationLease,
-  acquireRuntimeLease,
   allocateRuntime,
   cleanupRuntimeArtifacts,
   getProjectId,
   getSessionId,
   parseConversationId,
+  requirePersistedSessionFile,
+  tryAcquireConversationLease,
+  tryAcquireRuntimeLease,
 } from "./runtime.js";
 
+function stringEnum(values: readonly string[], description: string) {
+  return Type.Union(values.map((value) => Type.Literal(value)), { description });
+}
+
 const ORACLE_SUBMIT_PARAMS = Type.Object({
   prompt: Type.String({ description: "Prompt text to send to ChatGPT web." }),
   files: Type.Array(Type.String({ description: "Project-relative file or directory path to include in the archive." }), {
     description: "Exact project-relative files/directories to include in the oracle archive.",
     minItems: 1,
   }),
-  modelFamily: Type.Optional(StringEnum(MODEL_FAMILIES, { description: "ChatGPT model family: instant, thinking, or pro." })),
-  effort: Type.Optional(StringEnum(EFFORTS, { description: "Reasoning effort. Use only values supported by the chosen model family." })),
+  modelFamily: Type.Optional(stringEnum(MODEL_FAMILIES, "ChatGPT model family: instant, thinking, or pro.")),
+  effort: Type.Optional(stringEnum(EFFORTS, "Reasoning effort. Use only values supported by the chosen model family.")),
   autoSwitchToThinking: Type.Optional(
     Type.Boolean({ description: "Only valid when modelFamily is instant. Omit for thinking and pro." }),
   ),
@@ -60,6 +74,10 @@ const VALID_EFFORTS: Record<OracleModelFamily, readonly OracleEffort[]> = {
   pro: ["standard", "extended"],
 };
 
+const MAX_ARCHIVE_BYTES = 250 * 1024 * 1024;
+const MAX_QUEUED_JOBS_PER_ACTIVE_RUNTIME = 1;
+const MAX_QUEUED_ARCHIVE_BYTES_PER_ACTIVE_RUNTIME = MAX_ARCHIVE_BYTES;
+
 const DEFAULT_ARCHIVE_EXCLUDED_DIR_NAMES_ANYWHERE = new Set([
   ".git",
   ".hg",
@@ -89,11 +107,35 @@ const DEFAULT_ARCHIVE_EXCLUDED_DIR_NAMES_ANYWHERE = new Set([
   ".serverless",
   ".aws-sam",
 ]);
-const DEFAULT_ARCHIVE_EXCLUDED_DIR_NAMES_AT_REPO_ROOT = new Set(["coverage", "htmlcov", "tmp", "temp", ".tmp", "dist", "build", "out"]);
-const DEFAULT_ARCHIVE_EXCLUDED_FILES = new Set([".coverage", ".DS_Store", "Thumbs.db"]);
-const DEFAULT_ARCHIVE_EXCLUDED_SUFFIXES = [".pyc", ".pyo", ".pyd", ".tsbuildinfo", ".tfstate"];
+const DEFAULT_ARCHIVE_EXCLUDED_DIR_NAMES_AT_REPO_ROOT = new Set(["coverage", "htmlcov", "tmp", "temp", ".tmp", "dist", "build", "out", "secrets", ".secrets"]);
+const DEFAULT_ARCHIVE_EXCLUDED_FILES = new Set([
+  ".coverage",
+  ".DS_Store",
+  ".env",
+  ".netrc",
+  ".npmrc",
+  ".pypirc",
+  "Thumbs.db",
+  "id_dsa",
+  "id_ecdsa",
+  "id_ed25519",
+  "id_rsa",
+]);
+const DEFAULT_ARCHIVE_EXCLUDED_SUFFIXES = [".db", ".key", ".p12", ".pfx", ".pyc", ".pyd", ".pyo", ".pem", ".sqlite", ".sqlite3", ".tsbuildinfo", ".tfstate"];
 const DEFAULT_ARCHIVE_EXCLUDED_SUBSTRINGS = [".tfstate."];
+const DEFAULT_ARCHIVE_EXCLUDED_ENV_ALLOWLIST = new Set([".env.dist", ".env.example", ".env.sample", ".env.template"]);
 const DEFAULT_ARCHIVE_EXCLUDED_PATH_SEQUENCES = [[".yarn", "cache"]] as const;
+const ADAPTIVE_ARCHIVE_PRUNE_DIR_NAMES_ANYWHERE = new Set(["build", "dist", "out", "coverage", "htmlcov", "tmp", "temp", ".tmp"]);
+const ADAPTIVE_ARCHIVE_PRUNE_PROTECTED_ANCESTOR_DIR_NAMES = new Set(["src", "source", "sources", "lib"]);
+
+type ArchiveSizeBreakdownRow = { relativePath: string; bytes: number };
+type ArchiveCreationResult = {
+  sha256: string;
+  archiveBytes: number;
+  initialArchiveBytes?: number;
+  autoPrunedPrefixes: ArchiveSizeBreakdownRow[];
+  includedEntries: string[];
+};
 
 function pathContainsSequence(relativePath: string, sequence: readonly string[]): boolean {
   const segments = relativePath.split("/").filter(Boolean);
@@ -108,6 +150,62 @@ function getRelativeDepth(relativePath: string): number {
   return relativePath.split("/").filter(Boolean).length;
 }
 
+function formatBytes(bytes: number): string {
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MiB`;
+}
+
+function formatDirectoryLabel(relativePath: string): string {
+  return relativePath.endsWith("/") ? relativePath : `${relativePath}/`;
+}
+
+function summarizeByKey(
+  entrySizes: ArchiveSizeBreakdownRow[],
+  keyForEntry: (relativePath: string) => string | undefined,
+  limit = 7,
+): ArchiveSizeBreakdownRow[] {
+  const totals = new Map<string, number>();
+  for (const entry of entrySizes) {
+    const key = keyForEntry(entry.relativePath);
+    if (!key) continue;
+    totals.set(key, (totals.get(key) ?? 0) + entry.bytes);
+  }
+  return [...totals.entries()]
+    .map(([relativePath, bytes]) => ({ relativePath, bytes }))
+    .sort((left, right) => right.bytes - left.bytes || left.relativePath.localeCompare(right.relativePath))
+    .slice(0, limit);
+}
+
+function summarizeTopLevelIncludedPaths(entrySizes: ArchiveSizeBreakdownRow[]): ArchiveSizeBreakdownRow[] {
+  return summarizeByKey(entrySizes, (relativePath) => {
+    const [topLevel, ...rest] = relativePath.split("/").filter(Boolean);
+    if (!topLevel) return undefined;
+    return rest.length > 0 ? `${topLevel}/` : topLevel;
+  });
+}
+
+function getAdaptivePrunePrefix(relativePath: string): string | undefined {
+  const segments = relativePath.split("/").filter(Boolean);
+  for (let index = 0; index < segments.length - 1; index += 1) {
+    const name = segments[index];
+    if (!ADAPTIVE_ARCHIVE_PRUNE_DIR_NAMES_ANYWHERE.has(name)) continue;
+    const ancestors = segments.slice(0, index);
+    if (ancestors.some((segment) => ADAPTIVE_ARCHIVE_PRUNE_PROTECTED_ANCESTOR_DIR_NAMES.has(segment))) continue;
+    return segments.slice(0, index + 1).join("/");
+  }
+  return undefined;
+}
+
+function summarizeAdaptivePruneCandidates(
+  entrySizes: ArchiveSizeBreakdownRow[],
+  minimumBytes = 0,
+): ArchiveSizeBreakdownRow[] {
+  return summarizeByKey(entrySizes, getAdaptivePrunePrefix, Number.POSITIVE_INFINITY).filter((entry) => entry.bytes >= minimumBytes);
+}
+
+function pruneEntriesByPrefix(entries: string[], prefix: string): string[] {
+  return entries.filter((entry) => entry !== prefix && !entry.startsWith(`${prefix}/`));
+}
+
 function shouldExcludeArchivePath(relativePath: string, isDirectory: boolean, options?: { forceInclude?: boolean }): boolean {
   const normalized = posix.normalize(relativePath).replace(/^\.\//, "");
   if (!normalized || normalized === ".") return false;
@@ -120,6 +218,7 @@ function shouldExcludeArchivePath(relativePath: string, isDirectory: boolean, op
     return false;
   }
   if (DEFAULT_ARCHIVE_EXCLUDED_FILES.has(name)) return true;
+  if (name.startsWith(".env.") && !DEFAULT_ARCHIVE_EXCLUDED_ENV_ALLOWLIST.has(name)) return true;
   if (DEFAULT_ARCHIVE_EXCLUDED_SUFFIXES.some((suffix) => name.endsWith(suffix))) return true;
   if (DEFAULT_ARCHIVE_EXCLUDED_SUBSTRINGS.some((needle) => name.includes(needle))) return true;
   return false;
@@ -173,87 +272,191 @@ async function expandArchiveEntries(cwd: string, relativePath: string, options?:
   return results;
 }
 
-export async function resolveExpandedArchiveEntries(cwd: string, files: string[]): Promise<string[]> {
-  const entries = resolveArchiveInputs(cwd, files);
+async function resolveExpandedArchiveEntriesFromInputs(
+  cwd: string,
+  entries: Array<{ absolute: string; relative: string }>,
+): Promise<string[]> {
   return Array.from(new Set((await Promise.all(entries.map(async (entry) => {
-    const absolute = join(cwd, entry.relative);
-    const statEntry = await lstat(absolute);
+    const statEntry = await lstat(entry.absolute);
     const forceIncludeSubtree = statEntry.isDirectory() && entry.relative !== "." && shouldExcludeArchivePath(entry.relative, true);
     return expandArchiveEntries(cwd, entry.relative, { forceIncludeSubtree });
   }))).flat())).sort();
 }
 
-async function createArchive(cwd: string, files: string[], archivePath: string): Promise<string> {
-  const expandedEntries = await resolveExpandedArchiveEntries(cwd, files);
+export async function resolveExpandedArchiveEntries(cwd: string, files: string[]): Promise<string[]> {
+  return resolveExpandedArchiveEntriesFromInputs(cwd, resolveArchiveInputs(cwd, files));
+}
+
+function isWholeRepoArchiveSelection(entries: Array<{ absolute: string; relative: string }>): boolean {
+  return entries.length === 1 && entries[0]?.relative === ".";
+}
+
+async function measureArchiveEntrySizes(cwd: string, entries: string[]): Promise<ArchiveSizeBreakdownRow[]> {
+  return Promise.all(entries.map(async (relativePath) => ({ relativePath, bytes: (await lstat(join(cwd, relativePath))).size })));
+}
+
+function formatArchiveOversizeError(args: {
+  archiveBytes: number;
+  maxBytes: number;
+  entrySizes: ArchiveSizeBreakdownRow[];
+  autoPrunedPrefixes: ArchiveSizeBreakdownRow[];
+  adaptivePruneMinBytes?: number;
+}): string {
+  const topLevel = summarizeTopLevelIncludedPaths(args.entrySizes);
+  const adaptiveCandidates = summarizeAdaptivePruneCandidates(args.entrySizes, args.adaptivePruneMinBytes).slice(0, 7);
+  return [
+    `Oracle archive exceeds ChatGPT upload limit after default exclusions${args.autoPrunedPrefixes.length > 0 ? " and automatic generic generated-output-dir pruning" : ""}: ${args.archiveBytes} bytes >= ${args.maxBytes} bytes`,
+    args.autoPrunedPrefixes.length > 0 ? "Automatically pruned generic generated-output paths before failing:" : undefined,
+    ...args.autoPrunedPrefixes.map((entry) => `- ${formatDirectoryLabel(entry.relativePath)} — ${formatBytes(entry.bytes)}`),
+    topLevel.length > 0 ? "Approx top-level included sizes:" : undefined,
+    ...topLevel.map((entry) => `- ${entry.relativePath} — ${formatBytes(entry.bytes)}`),
+    adaptiveCandidates.length > 0 ? "Largest remaining generic generated-output-dir candidates:" : undefined,
+    ...adaptiveCandidates.map((entry) => `- ${formatDirectoryLabel(entry.relativePath)} — ${formatBytes(entry.bytes)}`),
+    "Retry with narrower archive inputs, starting with modified files plus adjacent files plus directly relevant subtrees.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+async function writeArchiveFile(cwd: string, entries: string[], archivePath: string, listPath: string): Promise<number> {
+  await writeFile(listPath, Buffer.from(`${entries.join("\0")}\0`), { mode: 0o600 });
+  await rm(archivePath, { force: true }).catch(() => undefined);
+
+  const { spawn } = await import("node:child_process");
+  await new Promise<void>((resolvePromise, rejectPromise) => {
+    const tar = spawn("tar", ["--null", "-cf", "-", "-T", listPath], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const zstd = spawn("zstd", ["-19", "-T0", "-f", "-o", archivePath], {
+      stdio: ["pipe", "ignore", "pipe"],
+    });
+
+    let stderr = "";
+    let settled = false;
+    let tarCode: number | null | undefined;
+    let zstdCode: number | null | undefined;
+
+    const finish = (error?: Error) => {
+      if (settled) return;
+      if (error) {
+        settled = true;
+        tar.kill("SIGTERM");
+        zstd.kill("SIGTERM");
+        rejectPromise(error);
+        return;
+      }
+      if (tarCode === undefined || zstdCode === undefined) return;
+      settled = true;
+      if (tarCode === 0 && zstdCode === 0) resolvePromise();
+      else rejectPromise(new Error(stderr || `archive command failed (tar=${tarCode}, zstd=${zstdCode})`));
+    };
+
+    tar.stderr.on("data", (data) => {
+      stderr += String(data);
+    });
+    zstd.stderr.on("data", (data) => {
+      stderr += String(data);
+    });
+    tar.on("error", (error) => finish(error instanceof Error ? error : new Error(String(error))));
+    zstd.on("error", (error) => finish(error instanceof Error ? error : new Error(String(error))));
+    tar.on("close", (code) => {
+      tarCode = code;
+      finish();
+    });
+    zstd.on("close", (code) => {
+      zstdCode = code;
+      finish();
+    });
+    tar.stdout.pipe(zstd.stdin);
+  });
+
+  return (await stat(archivePath)).size;
+}
+
+export async function createArchiveForTesting(
+  cwd: string,
+  files: string[],
+  archivePath: string,
+  options?: { maxBytes?: number; adaptivePruneMinBytes?: number },
+): Promise<ArchiveCreationResult> {
+  const archiveInputs = resolveArchiveInputs(cwd, files);
+  const wholeRepoSelection = isWholeRepoArchiveSelection(archiveInputs);
+  let expandedEntries = await resolveExpandedArchiveEntriesFromInputs(cwd, archiveInputs);
   if (expandedEntries.length === 0) {
     throw new Error("Oracle archive inputs are empty after default exclusions");
   }
+
   const listDir = await mkdtemp(join(tmpdir(), "oracle-filelist-"));
   const listPath = join(listDir, "files.list");
-  await writeFile(listPath, Buffer.from(`${expandedEntries.join("\0")}\0`), { mode: 0o600 });
+  const maxBytes = options?.maxBytes ?? MAX_ARCHIVE_BYTES;
+  const adaptivePruneMinBytes = options?.adaptivePruneMinBytes ?? 0;
+  const autoPrunedPrefixes: ArchiveSizeBreakdownRow[] = [];
+  let initialArchiveBytes: number | undefined;
 
   try {
-    const { spawn } = await import("node:child_process");
-    await new Promise<void>((resolvePromise, rejectPromise) => {
-      const tar = spawn("tar", ["--null", "-cf", "-", "-T", listPath], {
-        cwd,
-        stdio: ["ignore", "pipe", "pipe"],
-      });
-      const zstd = spawn("zstd", ["-19", "-T0", "-o", archivePath], {
-        stdio: ["pipe", "ignore", "pipe"],
-      });
-
-      let stderr = "";
-      let settled = false;
-      let tarCode: number | null | undefined;
-      let zstdCode: number | null | undefined;
-
-      const finish = (error?: Error) => {
-        if (settled) return;
-        if (error) {
-          settled = true;
-          tar.kill("SIGTERM");
-          zstd.kill("SIGTERM");
-          rejectPromise(error);
-          return;
-        }
-        if (tarCode === undefined || zstdCode === undefined) return;
-        settled = true;
-        if (tarCode === 0 && zstdCode === 0) resolvePromise();
-        else rejectPromise(new Error(stderr || `archive command failed (tar=${tarCode}, zstd=${zstdCode})`));
-      };
+    while (true) {
+      if (expandedEntries.length === 0) {
+        throw new Error("Oracle archive inputs are empty after default exclusions and automatic size pruning");
+      }
 
-      tar.stderr.on("data", (data) => {
-        stderr += String(data);
-      });
-      zstd.stderr.on("data", (data) => {
-        stderr += String(data);
-      });
-      tar.on("error", (error) => finish(error instanceof Error ? error : new Error(String(error))));
-      zstd.on("error", (error) => finish(error instanceof Error ? error : new Error(String(error))));
-      tar.on("close", (code) => {
-        tarCode = code;
-        finish();
-      });
-      zstd.on("close", (code) => {
-        zstdCode = code;
-        finish();
-      });
-      tar.stdout.pipe(zstd.stdin);
-    });
+      const archiveBytes = await writeArchiveFile(cwd, expandedEntries, archivePath, listPath);
+      if (archiveBytes < maxBytes) {
+        return {
+          sha256: await sha256File(archivePath),
+          archiveBytes,
+          initialArchiveBytes,
+          autoPrunedPrefixes,
+          includedEntries: [...expandedEntries],
+        };
+      }
 
-    const archiveStat = await stat(archivePath);
-    const maxBytes = 250 * 1024 * 1024;
-    if (archiveStat.size >= maxBytes) {
-      throw new Error(`Oracle archive exceeds ChatGPT upload limit: ${archiveStat.size} bytes`);
-    }
+      if (initialArchiveBytes === undefined) initialArchiveBytes = archiveBytes;
+      const entrySizes = await measureArchiveEntrySizes(cwd, expandedEntries);
+      if (!wholeRepoSelection) {
+        throw new Error(formatArchiveOversizeError({ archiveBytes, maxBytes, entrySizes, autoPrunedPrefixes, adaptivePruneMinBytes }));
+      }
+
+      const nextCandidate = summarizeAdaptivePruneCandidates(entrySizes, adaptivePruneMinBytes).find(
+        (entry) => !autoPrunedPrefixes.some((pruned) => pruned.relativePath === entry.relativePath),
+      );
+      if (!nextCandidate) {
+        throw new Error(formatArchiveOversizeError({ archiveBytes, maxBytes, entrySizes, autoPrunedPrefixes, adaptivePruneMinBytes }));
+      }
 
-    return sha256File(archivePath);
+      autoPrunedPrefixes.push(nextCandidate);
+      expandedEntries = pruneEntriesByPrefix(expandedEntries, nextCandidate.relativePath);
+    }
   } finally {
     await rm(listDir, { recursive: true, force: true }).catch(() => undefined);
   }
 }
 
+async function createArchive(cwd: string, files: string[], archivePath: string): Promise<ArchiveCreationResult> {
+  return createArchiveForTesting(cwd, files, archivePath);
+}
+
+async function getQueuedArchivePressure(): Promise<{ queuedJobs: number; queuedArchiveBytes: number }> {
+  const queuedJobs = listOracleJobDirs()
+    .map((dir) => readJob(dir))
+    .filter((job): job is NonNullable<typeof job> => Boolean(job && job.status === "queued"));
+
+  const queuedArchiveBytes = (await Promise.all(
+    queuedJobs.map(async (job) => {
+      try {
+        return (await stat(job.archivePath)).size;
+      } catch {
+        return 0;
+      }
+    }),
+  )).reduce((sum, bytes) => sum + bytes, 0);
+
+  return {
+    queuedJobs: queuedJobs.length,
+    queuedArchiveBytes,
+  };
+}
+
 function validateSubmissionOptions(
   params: { effort?: OracleEffort; autoSwitchToThinking?: boolean },
   modelFamily: OracleModelFamily,
@@ -311,6 +514,7 @@ function redactJobDetails(job: NonNullable<ReturnType<typeof readJob>>) {
     projectId: job.projectId,
     sessionId: job.sessionId,
     createdAt: job.createdAt,
+    queuedAt: job.queuedAt,
     submittedAt: job.submittedAt,
     completedAt: job.completedAt,
     followUpToJobId: job.followUpToJobId,
@@ -329,6 +533,35 @@ function redactJobDetails(job: NonNullable<ReturnType<typeof readJob>>) {
   };
 }
 
+function formatAutoPrunedArchiveMessage(autoPrunedPrefixes: ArchiveCreationResult["autoPrunedPrefixes"]): string | undefined {
+  if (autoPrunedPrefixes.length === 0) return undefined;
+  return `Archive auto-pruned generic generated-output-name dirs to fit size limit: ${autoPrunedPrefixes.map((entry) => `${entry.relativePath}/ (${formatBytes(entry.bytes)})`).join(", ")}`;
+}
+
+function formatSubmitResponse(
+  job: NonNullable<ReturnType<typeof readJob>>,
+  options: {
+    autoPrunedPrefixes: ArchiveCreationResult["autoPrunedPrefixes"];
+    queued: boolean;
+    queuePosition?: number;
+    queueDepth?: number;
+  },
+): string {
+  return [
+    `${options.queued ? "Oracle job queued" : "Oracle job dispatched"}: ${job.id}`,
+    options.queued && options.queuePosition && options.queueDepth ? `Queue position: ${options.queuePosition} of ${options.queueDepth}` : undefined,
+    job.followUpToJobId ? `Follow-up to: ${job.followUpToJobId}` : undefined,
+    `Prompt: ${job.promptPath}`,
+    `Archive: ${job.archivePath}`,
+    formatAutoPrunedArchiveMessage(options.autoPrunedPrefixes),
+    `Response will be written to: ${job.responsePath}`,
+    options.queued ? "The job will start automatically when capacity is available." : undefined,
+    "Stop now and wait for the oracle completion wake-up.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
 export function registerOracleTools(pi: ExtensionAPI, workerPath: string): void {
   pi.registerTool({
     name: "oracle_submit",
@@ -338,25 +571,32 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string): void
     promptSnippet: "Dispatch a background ChatGPT web oracle job after gathering repo context.",
     promptGuidelines: [
       "Gather context before calling oracle_submit.",
-      "Always include a narrowly scoped archive of exact relevant files/directories.",
+      "By default, archive the whole repo by passing '.'; default archive exclusions apply automatically, including common bulky outputs and obvious credentials/private data like .env files, key material, credential dotfiles, local database files, and root secrets directories.",
+      "Only narrow file selection when the user explicitly asks, the task is clearly scoped smaller, or privacy/sensitivity requires it.",
+      "For very targeted asks like a single function or stack trace, a smaller archive is preferable.",
+      "When files='.' and the post-exclusion archive is still too large, submit automatically prunes the largest nested directories matching generic generated-output names like build/, dist/, out/, coverage/, and tmp/ outside obvious source roots like src/ and lib/ until the archive fits or no candidate remains; successful submissions report what was pruned.",
+      "If a submitted oracle job later fails because upload is rejected, retry smaller: remove the largest obviously irrelevant/generated content first, then narrow to modified files plus adjacent files plus directly relevant subtrees, then explain the cut or ask the user if still needed.",
+      "If oracle_submit itself fails because the local archive still exceeds the upload limit after default exclusions and automatic generic generated-output-dir pruning, or for any other submit-time error, stop and report the error instead of retrying automatically.",
+      "If oracle_submit returns a queued job instead of an immediately dispatched one, treat that as success and stop exactly the same way.",
       "Stop after dispatching oracle_submit; do not continue the task while the oracle job is running.",
-      "If oracle_submit fails, stop and report the error instead of retrying automatically.",
       "Only use autoSwitchToThinking with modelFamily=instant.",
     ],
     parameters: ORACLE_SUBMIT_PARAMS,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const config = loadOracleConfig(ctx.cwd);
-      const originSessionFile = getSessionFile(ctx);
+      const originSessionFile = requirePersistedSessionFile(getSessionFile(ctx), "submit oracle jobs");
       const projectId = getProjectId(ctx.cwd);
       const sessionId = getSessionId(originSessionFile, projectId);
-      const modelFamily = params.modelFamily ?? config.defaults.modelFamily;
-      const requestedEffort = params.effort ?? config.defaults.effort;
-      const effort = modelFamily === "instant" ? undefined : requestedEffort;
+      const submittedModelFamily = params.modelFamily as OracleModelFamily | undefined;
+      const submittedEffort = params.effort as OracleEffort | undefined;
+      const modelFamily: OracleModelFamily = submittedModelFamily ?? config.defaults.modelFamily;
+      const requestedEffort: OracleEffort = submittedEffort ?? config.defaults.effort;
+      const effort: OracleEffort | undefined = modelFamily === "instant" ? undefined : requestedEffort;
       const rawAutoSwitchToThinking = params.autoSwitchToThinking ?? config.defaults.autoSwitchToThinking;
       const autoSwitchToThinking = modelFamily === "instant" ? rawAutoSwitchToThinking : false;
       const followUp = resolveFollowUp(params.followUpJobId, ctx.cwd);
 
-      validateSubmissionOptions(params, modelFamily, effort, autoSwitchToThinking);
+      validateSubmissionOptions({ effort: submittedEffort, autoSwitchToThinking: params.autoSwitchToThinking }, modelFamily, effort, autoSwitchToThinking);
       try {
         await withGlobalReconcileLock({ processPid: process.pid, source: "oracle_submit", cwd: ctx.cwd }, async () => {
           await reconcileStaleOracleJobs();
@@ -369,29 +609,95 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string): void
       const jobId = randomUUID();
       const tempArchivePath = join(tmpdir(), `oracle-archive-${jobId}.tar.zst`);
       const runtime = allocateRuntime(config);
-      let job;
+      let job: OracleJob | undefined;
+      let archive: ArchiveCreationResult | undefined;
+      let queued = false;
+      let queuedSubmissionDurable = false;
+      let runtimeLeaseAcquired = false;
+      let conversationLeaseAcquired = false;
+      let workerSpawned = false;
+      let spawnedWorker: Awaited<ReturnType<typeof spawnWorker>> | undefined;
 
       try {
-        const archiveSha256 = await createArchive(ctx.cwd, params.files, tempArchivePath);
+        archive = await createArchive(ctx.cwd, params.files, tempArchivePath);
+        const currentArchive = archive;
         await withLock("admission", "global", { jobId, processPid: process.pid }, async () => {
-          await acquireRuntimeLease(config, {
+          await promoteQueuedJobsWithinAdmissionLock({ workerPath, source: "oracle_submit" });
+
+          const admittedAt = new Date().toISOString();
+          const runtimeAttempt = await tryAcquireRuntimeLease(config, {
             jobId,
             runtimeId: runtime.runtimeId,
             runtimeSessionName: runtime.runtimeSessionName,
             runtimeProfileDir: runtime.runtimeProfileDir,
             projectId,
             sessionId,
-            createdAt: new Date().toISOString(),
+            createdAt: admittedAt,
           });
+
+          if (!runtimeAttempt.acquired) {
+            const queuePressure = await getQueuedArchivePressure();
+            const maxQueuedJobs = config.browser.maxConcurrentJobs * MAX_QUEUED_JOBS_PER_ACTIVE_RUNTIME;
+            if (queuePressure.queuedJobs >= maxQueuedJobs) {
+              throw new Error(
+                `Oracle is busy (${runtimeAttempt.liveLeases.length}/${config.browser.maxConcurrentJobs} active, ${queuePressure.queuedJobs}/${maxQueuedJobs} queued). ` +
+                  "Retry later instead of enqueuing more archive state.",
+              );
+            }
+            const maxQueuedArchiveBytes = config.browser.maxConcurrentJobs * MAX_QUEUED_ARCHIVE_BYTES_PER_ACTIVE_RUNTIME;
+            if (queuePressure.queuedArchiveBytes + currentArchive.archiveBytes > maxQueuedArchiveBytes) {
+              throw new Error(
+                `Oracle queued archive storage is full (${queuePressure.queuedArchiveBytes + currentArchive.archiveBytes} bytes > ${maxQueuedArchiveBytes} bytes across queued jobs). ` +
+                  "Retry later or narrow the archive inputs.",
+              );
+            }
+
+            queued = true;
+            job = await createJob(
+              jobId,
+              {
+                prompt: params.prompt,
+                files: params.files,
+                modelFamily,
+                effort,
+                autoSwitchToThinking,
+                followUpToJobId: followUp.followUpToJobId,
+                chatUrl: followUp.chatUrl,
+                requestSource: "tool",
+              },
+              ctx.cwd,
+              originSessionFile,
+              config,
+              runtime,
+              { initialState: "queued", createdAt: admittedAt },
+            );
+            await rename(tempArchivePath, job.archivePath);
+            job = await updateJob(job.id, (current) => ({
+              ...current,
+              archiveSha256: currentArchive.sha256,
+            }));
+            queuedSubmissionDurable = true;
+            return;
+          }
+
+          runtimeLeaseAcquired = true;
           if (followUp.conversationId) {
-            await acquireConversationLease({
+            const conversationAttempt = await tryAcquireConversationLease({
               jobId,
               conversationId: followUp.conversationId,
               projectId,
               sessionId,
-              createdAt: new Date().toISOString(),
+              createdAt: admittedAt,
             });
+            if (!conversationAttempt.acquired) {
+              throw new Error(
+                `Oracle conversation ${followUp.conversationId} is already in use by job ${conversationAttempt.blocker?.jobId ?? "unknown"}. ` +
+                  "Concurrent follow-ups to the same ChatGPT thread are not allowed.",
+              );
+            }
+            conversationLeaseAcquired = true;
           }
+
           job = await createJob(
             jobId,
             {
@@ -408,40 +714,109 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string): void
             originSessionFile,
             config,
             runtime,
+            { initialState: "submitted", createdAt: admittedAt },
           );
+          await rename(tempArchivePath, job.archivePath);
+          spawnedWorker = await spawnWorker(workerPath, job.id);
+          workerSpawned = true;
+          const worker = spawnedWorker;
+          job = await updateJob(job.id, (current) => ({
+            ...current,
+            archiveSha256: currentArchive.sha256,
+            workerPid: worker.pid,
+            workerNonce: worker.nonce,
+            workerStartedAt: worker.startedAt,
+          }));
         });
-        await rename(tempArchivePath, job.archivePath);
-        const worker = await spawnWorker(workerPath, job.id);
-        await updateJob(job.id, (current) => ({
-          ...current,
-          archiveSha256,
-          workerPid: worker.pid,
-          workerNonce: worker.nonce,
-          workerStartedAt: worker.startedAt,
-        }));
+        if (!job || !archive) throw new Error(`Oracle submission ${jobId} did not persist job metadata durably`);
         if (ctx.hasUI) refreshOracleStatus(ctx);
 
+        const queuePosition = queued ? getQueuePosition(job.id) : undefined;
         return {
           content: [
             {
               type: "text",
-              text: [
-                `Oracle job dispatched: ${job.id}`,
-                followUp.followUpToJobId ? `Follow-up to: ${followUp.followUpToJobId}` : undefined,
-                `Prompt: ${job.promptPath}`,
-                `Archive: ${job.archivePath}`,
-                `Response will be written to: ${job.responsePath}`,
-                "Stop now and wait for the oracle completion wake-up.",
-              ]
-                .filter(Boolean)
-                .join("\n"),
+              text: formatSubmitResponse(job, {
+                autoPrunedPrefixes: currentArchive.autoPrunedPrefixes,
+                queued,
+                queuePosition: queuePosition?.position,
+                queueDepth: queuePosition?.depth,
+              }),
             },
           ],
-          details: { jobId: job.id, archiveSha256, runtimeId: job.runtimeId, followUpToJobId: followUp.followUpToJobId },
+          details: {
+            jobId: job.id,
+            queued,
+            queuePosition: queuePosition?.position,
+            queueDepth: queuePosition?.depth,
+            archiveSha256: currentArchive.sha256,
+            archiveBytes: currentArchive.archiveBytes,
+            initialArchiveBytes: currentArchive.initialArchiveBytes,
+            autoPrunedArchivePaths: currentArchive.autoPrunedPrefixes,
+            runtimeId: job.runtimeId,
+            followUpToJobId: followUp.followUpToJobId,
+          },
         };
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        if (job) {
+        const latest = job ? readJob(job.id) : undefined;
+        if (latest?.status === "queued" && queuedSubmissionDurable) {
+          if (ctx.hasUI) refreshOracleStatus(ctx);
+          const queuePosition = getQueuePosition(latest.id);
+          return {
+            content: [
+              {
+                type: "text",
+                text: formatSubmitResponse(latest, {
+                  autoPrunedPrefixes: archive?.autoPrunedPrefixes ?? [],
+                  queued: true,
+                  queuePosition: queuePosition?.position,
+                  queueDepth: queuePosition?.depth,
+                }),
+              },
+            ],
+            details: {
+              jobId: latest.id,
+              queued: true,
+              queuePosition: queuePosition?.position,
+              queueDepth: queuePosition?.depth,
+              archiveSha256: latest.archiveSha256,
+              archiveBytes: archive?.archiveBytes,
+              initialArchiveBytes: archive?.initialArchiveBytes,
+              autoPrunedArchivePaths: archive?.autoPrunedPrefixes,
+              runtimeId: latest.runtimeId,
+              followUpToJobId: latest.followUpToJobId,
+            },
+          };
+        }
+        if (workerSpawned && latest && hasDurableWorkerHandoff(latest)) {
+          if (ctx.hasUI) refreshOracleStatus(ctx);
+          return {
+            content: [
+              {
+                type: "text",
+                text: formatSubmitResponse(latest, {
+                  autoPrunedPrefixes: archive?.autoPrunedPrefixes ?? [],
+                  queued: false,
+                }),
+              },
+            ],
+            details: {
+              jobId: latest.id,
+              queued: false,
+              archiveSha256: latest.archiveSha256,
+              archiveBytes: archive?.archiveBytes,
+              initialArchiveBytes: archive?.initialArchiveBytes,
+              autoPrunedArchivePaths: archive?.autoPrunedPrefixes,
+              runtimeId: latest.runtimeId,
+              followUpToJobId: latest.followUpToJobId,
+            },
+          };
+        }
+        if (spawnedWorker) {
+          await terminateWorkerPid(spawnedWorker.pid, spawnedWorker.startedAt).catch(() => undefined);
+        }
+        if (job && (!latest || !isTerminalOracleJob(latest))) {
           const failedAt = new Date().toISOString();
           await updateJob(job.id, (current) => ({
             ...current,
@@ -452,12 +827,15 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string): void
             }, failedAt),
           })).catch(() => undefined);
         }
-        await cleanupRuntimeArtifacts({
-          runtimeId: runtime.runtimeId,
-          runtimeProfileDir: runtime.runtimeProfileDir,
-          runtimeSessionName: runtime.runtimeSessionName,
-          conversationId: followUp.conversationId,
-        }).catch(() => undefined);
+        const cleanupReport = await cleanupRuntimeArtifacts({
+          runtimeId: runtimeLeaseAcquired ? runtime.runtimeId : undefined,
+          runtimeProfileDir: runtimeLeaseAcquired ? runtime.runtimeProfileDir : undefined,
+          runtimeSessionName: workerSpawned ? runtime.runtimeSessionName : undefined,
+          conversationId: conversationLeaseAcquired ? followUp.conversationId : undefined,
+        }).catch(() => ({ attempted: [], warnings: [] }));
+        if (job && cleanupReport.warnings.length > 0) {
+          await appendCleanupWarnings(job.id, cleanupReport.warnings).catch(() => undefined);
+        }
         if (ctx.hasUI) refreshOracleStatus(ctx);
         throw error;
       } finally {
@@ -476,10 +854,12 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string): void
       if (!job || job.projectId !== getProjectId(ctx.cwd)) {
         throw new Error(`Oracle job not found in this project: ${params.jobId}`);
       }
+      const latest = isTerminalOracleJob(job) ? await markWakeupSettled(job.id) : job;
+      const current = latest ?? readJob(job.id) ?? job;
 
       let responsePreview = "";
       try {
-        const response = await import("node:fs/promises").then((fs) => fs.readFile(job.responsePath || "", "utf8"));
+        const response = await import("node:fs/promises").then((fs) => fs.readFile(current.responsePath || "", "utf8"));
         responsePreview = response.slice(0, 4000);
       } catch {
         responsePreview = "(response not available yet)";
@@ -490,14 +870,22 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string): void
           {
             type: "text",
             text: [
-              `job: ${job.id}`,
-              `status: ${job.status}`,
-              job.followUpToJobId ? `follow-up-to: ${job.followUpToJobId}` : undefined,
-              job.chatUrl ? `chat: ${job.chatUrl}` : undefined,
-              job.responsePath ? `response: ${job.responsePath}` : undefined,
-              job.responseFormat ? `response-format: ${job.responseFormat}` : undefined,
-              `artifacts: /tmp/oracle-${job.id}/artifacts`,
-              job.error ? `error: ${job.error}` : undefined,
+              `job: ${current.id}`,
+              `status: ${current.status}`,
+              current.queuedAt ? `queued: ${current.queuedAt}` : undefined,
+              current.submittedAt ? `submitted: ${current.submittedAt}` : undefined,
+              ...(current.status === "queued"
+                ? (() => {
+                  const queuePosition = getQueuePosition(current.id);
+                  return queuePosition ? [`queue-position: ${queuePosition.position} of ${queuePosition.depth}`] : [];
+                })()
+                : []),
+              current.followUpToJobId ? `follow-up-to: ${current.followUpToJobId}` : undefined,
+              current.chatUrl ? `chat: ${current.chatUrl}` : undefined,
+              current.responsePath ? `response: ${current.responsePath}` : undefined,
+              current.responseFormat ? `response-format: ${current.responseFormat}` : undefined,
+              `artifacts: ${getJobDir(current.id)}/artifacts`,
+              current.error ? `error: ${current.error}` : undefined,
               "",
               responsePreview,
             ]
@@ -505,7 +893,7 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string): void
               .join("\n"),
           },
         ],
-        details: { job: redactJobDetails(job) },
+        details: { job: redactJobDetails(current) },
       };
     },
   });
@@ -513,24 +901,27 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string): void
   pi.registerTool({
     name: "oracle_cancel",
     label: "Oracle Cancel",
-    description: "Cancel an active oracle job.",
+    description: "Cancel a queued or active oracle job.",
     parameters: ORACLE_CANCEL_PARAMS,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const job = readJob(params.jobId);
       if (!job || job.projectId !== getProjectId(ctx.cwd)) {
         throw new Error(`Oracle job not found in this project: ${params.jobId}`);
       }
-      if (!isActiveOracleJob(job)) {
+      if (!isOpenOracleJob(job)) {
         return {
-          content: [{ type: "text", text: `Oracle job ${job.id} is not active (${job.status}).` }],
+          content: [{ type: "text", text: `Oracle job ${job.id} is not cancellable (${job.status}).` }],
           details: { job: redactJobDetails(job) },
         };
       }
 
       const cancelled = await cancelOracleJob(params.jobId);
+      if (shouldAdvanceQueueAfterCancellation(cancelled)) {
+        await promoteQueuedJobs({ workerPath, source: "oracle_cancel_tool" });
+      }
       if (ctx.hasUI) refreshOracleStatus(ctx);
       return {
-        content: [{ type: "text", text: `Cancelled oracle job ${cancelled.id}.` }],
+        content: [{ type: "text", text: cancelled.status === "cancelled" || cancelled.status === "failed" ? `Cancelled oracle job ${cancelled.id}.` : `Oracle job ${cancelled.id} was already ${cancelled.status}.` }],
         details: { job: redactJobDetails(cancelled) },
       };
     },