pi-oracle 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.2.2 - 2026-04-07
+
+### Fixed
+- missed ChatGPT file artifacts now map generic download controls onto nearby filenames and download from live DOM selectors instead of relying only on filename-labeled snapshot refs
+- oracle jobs no longer report a false-clean completion when response-local artifact signals are present but capture fails or remains inconclusive
+- artifact label extraction now collapses paths and mixed response text down to real filenames so suspicious artifact fallback logic does not emit bogus labels
+
+### Added
+- regression coverage for artifact label extraction edge cases and ambiguous download-control artifact detection
+
+## 0.2.1 - 2026-04-07
+
+### Fixed
+- wake-up guidance now tells receivers to use `oracle_read(jobId)` as the canonical way to consume completion results
+- manual inspection before the first wake-up no longer suppresses the initial reminder attempt
+- wake-up settlement now records provenance so suppressed/settled delivery can be explained in postmortems
+- queued archive cleanup retries now retry queued archive deletion and keep warnings until cleanup succeeds
+- queued archive byte-pressure accounting now includes retained pre-submit archives instead of only currently queued jobs
+
 ## 0.2.0 - 2026-04-06
 
 ### Added

package/README.md

@@ -136,7 +136,9 @@ Detailed design and maintainer docs:
 Completion notification semantics:
 - oracle responses and artifacts are always persisted durably in oracle job state under the configured oracle jobs dir (`${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` by default)
 - completion delivery into pi sessions is best-effort wake-up based; the extension no longer appends synthetic assistant completion messages into session history
-- manual `oracle_read` or `/oracle-status` inspection settles further reminder retries once the terminal job has been opened
+- wake-up content tells the receiving assistant to call `oracle_read(jobId)` as the canonical completion-consumption path, with saved file paths included as secondary context
+- manual `oracle_read` or `/oracle-status` inspection settles further reminder retries once the terminal job has been opened, and now persists settlement provenance for postmortems
+- manual inspection before the first wake-up attempt is recorded as observation only and does not suppress the first reminder send
 - if a wake-up does not land, the job remains available via its saved response/artifacts and status commands
 
 ## Privacy / local data

package/docs/ORACLE_DESIGN.md

@@ -336,6 +336,14 @@ Important fields include:
 - `wakeupAttemptCount`
 - `wakeupLastRequestedAt`
 - `wakeupSettledAt`
+- `wakeupSettledSource`
+- `wakeupSettledSessionFile`
+- `wakeupSettledSessionKey`
+- `wakeupSettledBeforeFirstAttempt`
+- `wakeupObservedAt`
+- `wakeupObservedSource`
+- `wakeupObservedSessionFile`
+- `wakeupObservedSessionKey`
 - `notifyClaimedAt`
 - `notifyClaimedBy`
 - `artifactFailureCount`
@@ -461,7 +469,9 @@ The extension still uses the same general `pi`-native background completion patt
 - poller scans jobs on an interval
 - completed job durability lives in oracle job state plus saved response/artifact files, not in synthetic session-history assistant messages
 - when a matching job reaches `complete`, `failed`, or `cancelled`, the poller issues bounded best-effort wake-up reminders to whichever matching session is currently live
-- manual `oracle_read` or `/oracle-status` inspection settles further reminder retries once the terminal job has been opened
+- those wake-ups direct the receiver to `oracle_read(jobId)` as the canonical completion-consumption path, while still surfacing saved response/artifact paths as secondary context
+- manual `oracle_read` or `/oracle-status` inspection settles further reminder retries once the terminal job has been opened and persists provenance about which path/session settled the wake-up
+- manual inspection before the first wake-up attempt is recorded separately as observation metadata and does not suppress the first reminder send
 - if no wake-up lands, the job remains available via `/oracle-status`, `oracle_read`, and the saved `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` response/artifact files
 - because completion delivery is best-effort, pruning uses explicit terminal-job age policy instead of pretending a durable session notification happened
 - recently sent wake-ups keep response/artifact files retained briefly so follow-up turns do not point at deleted paths if cleanup or pruning races with delivery

package/extensions/oracle/lib/commands.ts

@@ -121,7 +121,11 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
         return;
       }
       if (isTerminalOracleJob(job)) {
-        await markWakeupSettled(job.id);
+        await markWakeupSettled(job.id, {
+          source: "oracle_status",
+          sessionFile: ctx.sessionManager.getSessionFile?.(),
+          cwd: ctx.cwd,
+        });
       }
       ctx.ui.notify(summarizeJob(job.id), "info");
     },

package/extensions/oracle/lib/jobs.ts

@@ -25,6 +25,8 @@ export type OracleJobPhase =
   | "failed"
   | "cancelled";
 
+export type OracleWakeupSettlementSource = "oracle_read" | "oracle_status";
+
 export const ACTIVE_ORACLE_JOB_STATUSES: OracleJobStatus[] = ["preparing", "submitted", "waiting"];
 export const OPEN_ORACLE_JOB_STATUSES: OracleJobStatus[] = ["queued", ...ACTIVE_ORACLE_JOB_STATUSES];
 export const TERMINAL_ORACLE_JOB_STATUSES: OracleJobStatus[] = ["complete", "failed", "cancelled"];
@@ -56,6 +58,10 @@ export function shouldAdvanceQueueAfterCancellation(job: Pick<OracleJob, "status
   return job.status === "cancelled" && !job.cleanupPending && !job.cleanupWarnings?.length;
 }
 
+export function hasRetainedPreSubmitArchive(job: Pick<OracleJob, "submittedAt" | "archiveDeletedAfterUpload" | "archivePath">): boolean {
+  return !job.submittedAt && !job.archiveDeletedAfterUpload && typeof job.archivePath === "string" && job.archivePath.length > 0;
+}
+
 export function hasDurableWorkerHandoff(
   job: Pick<OracleJob, "status" | "phase" | "workerPid" | "workerStartedAt" | "heartbeatAt">,
 ): boolean {
@@ -147,6 +153,14 @@ export interface OracleJob {
   wakeupAttemptCount?: number;
   wakeupLastRequestedAt?: string;
   wakeupSettledAt?: string;
+  wakeupSettledSource?: OracleWakeupSettlementSource;
+  wakeupSettledSessionFile?: string;
+  wakeupSettledSessionKey?: string;
+  wakeupSettledBeforeFirstAttempt?: boolean;
+  wakeupObservedAt?: string;
+  wakeupObservedSource?: OracleWakeupSettlementSource;
+  wakeupObservedSessionFile?: string;
+  wakeupObservedSessionKey?: string;
   notifyClaimedAt?: string;
   notifyClaimedBy?: string;
   artifactFailureCount?: number;
@@ -443,17 +457,32 @@ function getTerminalCleanupStaleReason(job: Pick<OracleJob, "status" | "cleanupP
 }
 
 export async function cleanupJobResources(
-  job: Pick<OracleJob, "submittedAt" | "runtimeId" | "runtimeProfileDir" | "runtimeSessionName" | "conversationId">,
+  job: Pick<OracleJob, "submittedAt" | "runtimeId" | "runtimeProfileDir" | "runtimeSessionName" | "conversationId" | "archivePath" | "archiveDeletedAfterUpload">,
 ): Promise<OracleCleanupReport> {
+  const report: OracleCleanupReport = { attempted: [], warnings: [] };
+
+  if (hasRetainedPreSubmitArchive(job)) {
+    report.attempted.push("queuedArchive");
+    await rm(job.archivePath, { force: true }).catch((error: Error) => {
+      report.warnings.push(`Failed to remove queued archive ${job.archivePath}: ${error.message}`);
+    });
+  }
+
   if (!job.submittedAt) {
-    return { attempted: [], warnings: [] };
+    return report;
   }
-  return cleanupRuntimeArtifacts({
+
+  const runtimeReport = await cleanupRuntimeArtifacts({
     runtimeId: job.runtimeId,
     runtimeProfileDir: job.runtimeProfileDir,
     runtimeSessionName: job.runtimeSessionName,
     conversationId: job.conversationId,
   });
+
+  return {
+    attempted: [...report.attempted, ...runtimeReport.attempted],
+    warnings: [...report.warnings, ...runtimeReport.warnings],
+  };
 }
 
 function getCleanupRetentionMs(job: OracleJob): { complete: number; failed: number } {
@@ -774,12 +803,57 @@ export async function noteWakeupRequested(jobId: string, at = new Date().toISOSt
   }
 }
 
-export async function markWakeupSettled(jobId: string, at = new Date().toISOString()): Promise<OracleJob | undefined> {
+function getWakeupSessionKey(sessionFile: string | undefined, cwd: string | undefined): string | undefined {
+  if (!sessionFile || !cwd) return undefined;
+  const projectId = getProjectId(cwd);
+  return `${projectId}::${getSessionId(sessionFile, projectId)}`;
+}
+
+export async function markWakeupSettled(
+  jobId: string,
+  options: {
+    source: OracleWakeupSettlementSource;
+    sessionFile?: string;
+    cwd?: string;
+    at?: string;
+    allowBeforeFirstAttempt?: boolean;
+  },
+): Promise<OracleJob | undefined> {
+  const at = options.at ?? new Date().toISOString();
+  const sessionKey = getWakeupSessionKey(options.sessionFile, options.cwd);
+
   try {
-    return await updateJob(jobId, (job) => ({
-      ...job,
-      wakeupSettledAt: job.wakeupSettledAt ?? at,
-    }));
+    return await updateJob(jobId, (job) => {
+      const beforeFirstAttempt = !job.wakeupLastRequestedAt && (job.wakeupAttemptCount ?? 0) === 0;
+      if (job.wakeupSettledAt) {
+        return {
+          ...job,
+          wakeupSettledSource: job.wakeupSettledSource ?? options.source,
+          wakeupSettledSessionFile: job.wakeupSettledSessionFile ?? options.sessionFile,
+          wakeupSettledSessionKey: job.wakeupSettledSessionKey ?? sessionKey,
+          wakeupSettledBeforeFirstAttempt: job.wakeupSettledBeforeFirstAttempt ?? beforeFirstAttempt,
+        };
+      }
+
+      if (beforeFirstAttempt && !options.allowBeforeFirstAttempt) {
+        return {
+          ...job,
+          wakeupObservedAt: job.wakeupObservedAt ?? at,
+          wakeupObservedSource: job.wakeupObservedSource ?? options.source,
+          wakeupObservedSessionFile: job.wakeupObservedSessionFile ?? options.sessionFile,
+          wakeupObservedSessionKey: job.wakeupObservedSessionKey ?? sessionKey,
+        };
+      }
+
+      return {
+        ...job,
+        wakeupSettledAt: at,
+        wakeupSettledSource: options.source,
+        wakeupSettledSessionFile: options.sessionFile,
+        wakeupSettledSessionKey: sessionKey,
+        wakeupSettledBeforeFirstAttempt: beforeFirstAttempt,
+      };
+    });
   } catch {
     return readJob(jobId);
   }
@@ -805,17 +879,14 @@ export async function cancelOracleJob(id: string, reason = "Cancelled by user"):
         }, now),
       }));
 
-      const cleanupWarnings: string[] = [];
-      await rm(cancelled.archivePath, { force: true }).catch((error: Error) => {
-        cleanupWarnings.push(`Failed to remove queued archive ${cancelled.archivePath}: ${error.message}`);
-      });
-      if (cleanupWarnings.length === 0) return cancelled;
+      const cleanupReport = await cleanupJobResources(cancelled);
+      if (cleanupReport.warnings.length === 0) return cancelled;
 
       return updateJob(id, (job) => ({
         ...job,
-        cleanupWarnings: [...(job.cleanupWarnings || []), ...cleanupWarnings],
+        cleanupWarnings: [...(job.cleanupWarnings || []), ...cleanupReport.warnings],
         lastCleanupAt: now,
-        error: [job.error, ...cleanupWarnings].filter(Boolean).join("\n"),
+        error: [job.error, ...cleanupReport.warnings].filter(Boolean).join("\n"),
       }));
     }
 

package/extensions/oracle/lib/poller.ts

@@ -180,9 +180,10 @@ function buildNotificationContent(job: OraclePollerJob): string {
   const artifactsPath = `${getJobDir(job.id)}/artifacts`;
   return [
     `Oracle job ${job.id} is ${job.status}.`,
-    `Read response: ${responsePath}`,
+    `Use oracle_read with jobId ${job.id} to open the response and settle wake-up retries.`,
+    `Response file: ${responsePath}`,
     `Artifacts: ${artifactsPath}`,
-    job.error ? `Error: ${job.error}` : "Continue from the oracle output.",
+    job.error ? `Error: ${job.error}` : "After oracle_read, continue from the oracle output.",
   ].join("\n");
 }
 

package/extensions/oracle/lib/runtime.ts

@@ -231,7 +231,7 @@ export async function cloneSeedProfileToRuntime(config: OracleConfig, runtimePro
 const AGENT_BROWSER_CLOSE_TIMEOUT_MS = 10_000;
 
 export interface OracleCleanupReport {
-  attempted: Array<"browser" | "runtimeProfileDir" | "conversationLease" | "runtimeLease">;
+  attempted: Array<"browser" | "runtimeProfileDir" | "conversationLease" | "runtimeLease" | "queuedArchive">;
   warnings: string[];
 }
 

package/extensions/oracle/lib/tools.ts

@@ -13,6 +13,7 @@ import {
   getJobDir,
   getSessionFile,
   hasDurableWorkerHandoff,
+  hasRetainedPreSubmitArchive,
   isOpenOracleJob,
   isTerminalOracleJob,
   listOracleJobDirs,
@@ -436,27 +437,60 @@ async function createArchive(cwd: string, files: string[], archivePath: string):
   return createArchiveForTesting(cwd, files, archivePath);
 }
 
-async function getQueuedArchivePressure(): Promise<{ queuedJobs: number; queuedArchiveBytes: number }> {
-  const queuedJobs = listOracleJobDirs()
+export interface QueuedArchivePressure {
+  queuedJobs: number;
+  queuedArchiveBytes: number;
+}
+
+export async function getQueuedArchivePressure(): Promise<QueuedArchivePressure> {
+  const jobs = listOracleJobDirs()
     .map((dir) => readJob(dir))
-    .filter((job): job is NonNullable<typeof job> => Boolean(job && job.status === "queued"));
+    .filter((job): job is NonNullable<typeof job> => Boolean(job));
 
   const queuedArchiveBytes = (await Promise.all(
-    queuedJobs.map(async (job) => {
-      try {
-        return (await stat(job.archivePath)).size;
-      } catch {
-        return 0;
-      }
-    }),
+    jobs
+      .filter((job) => hasRetainedPreSubmitArchive(job))
+      .map(async (job) => {
+        try {
+          return (await stat(job.archivePath)).size;
+        } catch {
+          return 0;
+        }
+      }),
   )).reduce((sum, bytes) => sum + bytes, 0);
 
   return {
-    queuedJobs: queuedJobs.length,
+    queuedJobs: jobs.filter((job) => job.status === "queued").length,
     queuedArchiveBytes,
   };
 }
 
+export function getQueueAdmissionFailure(args: {
+  queuePressure: QueuedArchivePressure;
+  archiveBytes: number;
+  activeJobs: number;
+  maxActiveJobs: number;
+  maxQueuedJobs: number;
+  maxQueuedArchiveBytes: number;
+}): string | undefined {
+  if (args.queuePressure.queuedJobs >= args.maxQueuedJobs) {
+    return (
+      `Oracle is busy (${args.activeJobs}/${args.maxActiveJobs} active, ${args.queuePressure.queuedJobs}/${args.maxQueuedJobs} queued). ` +
+      "Retry later instead of enqueuing more archive state."
+    );
+  }
+
+  const queuedArchiveBytes = args.queuePressure.queuedArchiveBytes + args.archiveBytes;
+  if (queuedArchiveBytes > args.maxQueuedArchiveBytes) {
+    return (
+      `Oracle queued archive storage is full (${queuedArchiveBytes} bytes > ${args.maxQueuedArchiveBytes} bytes across queued jobs and retained pre-submit archives). ` +
+      "Retry later or narrow the archive inputs."
+    );
+  }
+
+  return undefined;
+}
+
 function validateSubmissionOptions(
   params: { effort?: OracleEffort; autoSwitchToThinking?: boolean },
   modelFamily: OracleModelFamily,
@@ -638,18 +672,17 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string): void
           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.",
-              );
+            const queueAdmissionFailure = getQueueAdmissionFailure({
+              queuePressure,
+              archiveBytes: currentArchive.archiveBytes,
+              activeJobs: runtimeAttempt.liveLeases.length,
+              maxActiveJobs: config.browser.maxConcurrentJobs,
+              maxQueuedJobs,
+              maxQueuedArchiveBytes,
+            });
+            if (queueAdmissionFailure) {
+              throw new Error(queueAdmissionFailure);
             }
 
             queued = true;
@@ -854,7 +887,13 @@ 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 latest = isTerminalOracleJob(job)
+        ? await markWakeupSettled(job.id, {
+          source: "oracle_read",
+          sessionFile: getSessionFile(ctx),
+          cwd: ctx.cwd,
+        })
+        : job;
       const current = latest ?? readJob(job.id) ?? job;
 
       let responsePreview = "";

package/extensions/oracle/worker/artifact-heuristics.d.mts

@@ -10,20 +10,36 @@ export interface SnapshotEntry {
 
 export interface StructuralArtifactCandidateInput {
   label?: string;
+  selector?: string;
+  controlLabel?: string;
   paragraphText?: string;
   listItemText?: string;
-  paragraphFileButtonCount?: number;
+  paragraphInteractiveCount?: number;
+  paragraphArtifactLabelCount?: number;
   paragraphOtherTextLength?: number;
-  listItemFileButtonCount?: number;
-  focusableFileButtonCount?: number;
+  listItemInteractiveCount?: number;
+  listItemArtifactLabelCount?: number;
+  focusableInteractiveCount?: number;
+  focusableArtifactLabelCount?: number;
   focusableOtherTextLength?: number;
 }
 
 export interface StructuralArtifactCandidate {
   label: string;
+  selector?: string;
+  controlLabel?: string;
+}
+
+export interface StructuralArtifactCandidatePartition {
+  confirmed: StructuralArtifactCandidate[];
+  suspicious: StructuralArtifactCandidate[];
 }
 
 export function parseSnapshotEntries(snapshot: string): SnapshotEntry[];
+export function extractArtifactLabels(value: string): string[];
 export function filterStructuralArtifactCandidates(
   candidates: StructuralArtifactCandidateInput[],
 ): StructuralArtifactCandidate[];
+export function partitionStructuralArtifactCandidates(
+  candidates: StructuralArtifactCandidateInput[],
+): StructuralArtifactCandidatePartition;

package/extensions/oracle/worker/artifact-heuristics.mjs

@@ -1,7 +1,8 @@
-export const FILE_LABEL_PATTERN_SOURCE = String.raw`(?:^|[^\w])[^\n]*\.[A-Za-z0-9]{1,12}(?:$|[^\w])`;
-const FILE_LABEL_PATTERN = new RegExp(FILE_LABEL_PATTERN_SOURCE);
+export const FILE_LABEL_PATTERN_SOURCE = String.raw`(?:^|[^A-Za-z0-9._~/-])((?:(?:[A-Za-z]:)?[\\/]|[.~][\\/])?(?:[^\\/\s"'<>|]+[\\/])*[^\\/\s"'<>|]+\.[A-Za-z0-9]{1,12})(?=$|[^A-Za-z0-9._~/-])`;
+const FILE_LABEL_PATTERN = new RegExp(FILE_LABEL_PATTERN_SOURCE, "g");
 export const GENERIC_ARTIFACT_LABELS = ["ATTACHED", "DONE"];
 const GENERIC_ARTIFACT_LABEL_SET = new Set(GENERIC_ARTIFACT_LABELS);
+const GENERIC_DOWNLOAD_CONTROL_PATTERN = /(?:^|\b)(?:download|save)(?:\b|$)/i;
 
 export function parseSnapshotEntries(snapshot) {
   return String(snapshot || "")
@@ -29,11 +30,61 @@ function normalizeText(value) {
   return String(value || "").replace(/\s+/g, " ").trim();
 }
 
+function sanitizeArtifactLabel(value) {
+  const normalized = normalizeText(value).replace(/^[^A-Za-z0-9._~/-]+|[^A-Za-z0-9._~/-]+$/g, "");
+  if (!normalized) return "";
+  const basename = normalized.split(/[\\/]/).filter(Boolean).at(-1) || "";
+  return basename.replace(/^[^A-Za-z0-9._-]+|[^A-Za-z0-9._-]+$/g, "");
+}
+
+export function extractArtifactLabels(value) {
+  const seen = new Set();
+  const labels = [];
+  for (const match of String(value || "").matchAll(FILE_LABEL_PATTERN)) {
+    const normalized = sanitizeArtifactLabel(match[1] || match[0] || "");
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    labels.push(normalized);
+  }
+  return labels;
+}
+
 export function isLikelyArtifactLabel(label) {
   const normalized = normalizeText(label);
   if (!normalized) return false;
   if (GENERIC_ARTIFACT_LABEL_SET.has(normalized.toUpperCase())) return true;
-  return FILE_LABEL_PATTERN.test(normalized);
+  return extractArtifactLabels(normalized).length > 0;
+}
+
+function hasGenericDownloadControl(controlLabel) {
+  return GENERIC_DOWNLOAD_CONTROL_PATTERN.test(normalizeText(controlLabel));
+}
+
+function normalizeCandidate(candidate) {
+  const label = normalizeText(candidate?.label);
+  return label ? { ...candidate, label } : undefined;
+}
+
+function hasArtifactSignal(candidate) {
+  const label = normalizeText(candidate?.label);
+  if (!isLikelyArtifactLabel(label)) return false;
+
+  const paragraphInteractiveCount = Number(candidate?.paragraphInteractiveCount || 0);
+  const listItemInteractiveCount = Number(candidate?.listItemInteractiveCount || 0);
+  const focusableInteractiveCount = Number(candidate?.focusableInteractiveCount || 0);
+  const paragraphArtifactLabelCount = Number(candidate?.paragraphArtifactLabelCount || 0);
+  const listItemArtifactLabelCount = Number(candidate?.listItemArtifactLabelCount || 0);
+  const focusableArtifactLabelCount = Number(candidate?.focusableArtifactLabelCount || 0);
+
+  return (
+    hasGenericDownloadControl(candidate?.controlLabel) ||
+    paragraphInteractiveCount > 0 ||
+    listItemInteractiveCount > 0 ||
+    focusableInteractiveCount > 0 ||
+    paragraphArtifactLabelCount > 0 ||
+    listItemArtifactLabelCount > 0 ||
+    focusableArtifactLabelCount > 0
+  );
 }
 
 export function isStructuralArtifactCandidate(candidate) {
@@ -41,36 +92,56 @@ export function isStructuralArtifactCandidate(candidate) {
   if (!isLikelyArtifactLabel(label)) return false;
 
   const listItemText = normalizeText(candidate?.listItemText);
-  const listItemFileButtonCount = Number(candidate?.listItemFileButtonCount || 0);
-  const paragraphFileButtonCount = Number(candidate?.paragraphFileButtonCount || 0);
+  const listItemInteractiveCount = Number(candidate?.listItemInteractiveCount || 0);
+  const listItemArtifactLabelCount = Number(candidate?.listItemArtifactLabelCount || 0);
+  const paragraphInteractiveCount = Number(candidate?.paragraphInteractiveCount || 0);
+  const paragraphArtifactLabelCount = Number(candidate?.paragraphArtifactLabelCount || 0);
   const paragraphOtherTextLength = Number(candidate?.paragraphOtherTextLength ?? Number.POSITIVE_INFINITY);
-  const focusableFileButtonCount = Number(candidate?.focusableFileButtonCount || 0);
+  const focusableInteractiveCount = Number(candidate?.focusableInteractiveCount || 0);
+  const focusableArtifactLabelCount = Number(candidate?.focusableArtifactLabelCount || 0);
   const focusableOtherTextLength = Number(candidate?.focusableOtherTextLength ?? Number.POSITIVE_INFINITY);
 
-  if (listItemText === label && listItemFileButtonCount === 1) {
+  if (listItemText === label && listItemInteractiveCount === 1 && listItemArtifactLabelCount === 1) {
     return true;
   }
 
-  if (paragraphFileButtonCount === 1 && paragraphOtherTextLength <= 32) {
+  if (paragraphArtifactLabelCount === 1 && paragraphInteractiveCount === 1 && paragraphOtherTextLength <= 32) {
     return true;
   }
 
-  if (focusableFileButtonCount >= 1 && focusableOtherTextLength <= 64) {
+  if (focusableArtifactLabelCount >= 1 && focusableInteractiveCount >= 1 && focusableOtherTextLength <= 64) {
     return true;
   }
 
   return false;
 }
 
-export function filterStructuralArtifactCandidates(candidates) {
-  const seen = new Set();
-  const filtered = [];
+export function partitionStructuralArtifactCandidates(candidates) {
+  const confirmedSeen = new Set();
+  const suspiciousSeen = new Set();
+  const confirmed = [];
+  const suspicious = [];
+
   for (const candidate of candidates || []) {
-    const label = normalizeText(candidate?.label);
-    if (!label || seen.has(label)) continue;
-    if (!isStructuralArtifactCandidate(candidate)) continue;
-    seen.add(label);
-    filtered.push({ label });
+    const normalized = normalizeCandidate(candidate);
+    if (!normalized) continue;
+    if (!hasArtifactSignal(normalized)) continue;
+
+    if (isStructuralArtifactCandidate(normalized)) {
+      if (confirmedSeen.has(normalized.label)) continue;
+      confirmedSeen.add(normalized.label);
+      confirmed.push(normalized);
+      continue;
+    }
+
+    if (suspiciousSeen.has(normalized.label)) continue;
+    suspiciousSeen.add(normalized.label);
+    suspicious.push(normalized);
   }
-  return filtered;
+
+  return { confirmed, suspicious: suspicious.filter((candidate) => !confirmedSeen.has(candidate.label)) };
+}
+
+export function filterStructuralArtifactCandidates(candidates) {
+  return partitionStructuralArtifactCandidates(candidates).confirmed;
 }

package/extensions/oracle/worker/run-job.mjs

@@ -4,7 +4,7 @@ import { appendFile, chmod, mkdir, readFile, rename, rm, stat, writeFile } from
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, execFileSync } from "node:child_process";
-import { FILE_LABEL_PATTERN_SOURCE, filterStructuralArtifactCandidates, GENERIC_ARTIFACT_LABELS, parseSnapshotEntries } from "./artifact-heuristics.mjs";
+import { extractArtifactLabels, FILE_LABEL_PATTERN_SOURCE, GENERIC_ARTIFACT_LABELS, parseSnapshotEntries, partitionStructuralArtifactCandidates } from "./artifact-heuristics.mjs";
 import { createLease, listLeaseMetadata, readLeaseMetadata, releaseLease, withLock } from "./state-locks.mjs";
 
 const jobId = process.argv[2];
@@ -1497,28 +1497,52 @@ function preferredArtifactName(label, index) {
 async function collectArtifactCandidates(job, responseIndex, responseText = "") {
   const snapshot = await snapshotText(job);
   const targetSlice = assistantSnapshotSlice(snapshot, responseIndex);
-  if (!targetSlice) return { snapshot, targetSlice, candidates: [] };
+  if (!targetSlice) return { snapshot, targetSlice, candidates: [], suspiciousLabels: [] };
 
   const structural = await evalPage(
     job,
     toJsonScript(`
       const normalize = (value) => String(value || '').replace(/\s+/g, ' ').trim();
       const genericArtifactLabels = new Set(${JSON.stringify(GENERIC_ARTIFACT_LABELS)});
-      const fileLabelPattern = new RegExp(${JSON.stringify(FILE_LABEL_PATTERN_SOURCE)});
+      const fileLabelPattern = new RegExp(${JSON.stringify(FILE_LABEL_PATTERN_SOURCE)}, 'g');
+      const downloadControlPattern = /(?:^|\\b)(?:download|save)(?:\\b|$)/i;
+      const artifactMarkerAttr = 'data-pi-oracle-artifact-candidate';
+      const artifactPrefix = 'pi-oracle-artifact-${jobId}-${responseIndex}-';
+      const sanitize = (value) => normalize(value).replace(/^[^A-Za-z0-9._~/-]+|[^A-Za-z0-9._~/-]+$/g, '');
+      const sanitizeArtifactLabel = (value) => {
+        const normalized = sanitize(value);
+        if (!normalized) return '';
+        const basename = normalized.split(/[\\/]/).filter(Boolean).at(-1) || '';
+        return basename.replace(/^[^A-Za-z0-9._-]+|[^A-Za-z0-9._-]+$/g, '');
+      };
+      const extractArtifactLabels = (value) => {
+        const seen = new Set();
+        const labels = [];
+        for (const match of String(value || '').matchAll(fileLabelPattern)) {
+          const label = sanitizeArtifactLabel(match[1] || match[0] || '');
+          if (!label || seen.has(label)) continue;
+          seen.add(label);
+          labels.push(label);
+        }
+        return labels;
+      };
       const isFileLabel = (value) => {
         const normalized = normalize(value);
         if (!normalized) return false;
         if (genericArtifactLabels.has(normalized.toUpperCase())) return true;
-        return fileLabelPattern.test(normalized);
+        return extractArtifactLabels(normalized).length > 0;
       };
+      const isDownloadControl = (value) => downloadControlPattern.test(normalize(value));
       const headings = Array.from(document.querySelectorAll('h1,h2,h3,h4,h5,h6,[role="heading"]'))
         .filter((el) => normalize(el.textContent) === 'ChatGPT said:');
       const host = headings[${responseIndex}]?.nextElementSibling;
       if (!host) return { candidates: [] };
 
-      const fileButtons = (node) => node
-        ? Array.from(node.querySelectorAll('button, a')).map((candidate) => normalize(candidate.textContent)).filter(isFileLabel)
-        : [];
+      const interactiveElements = (node) => node ? Array.from(node.querySelectorAll('button, a')) : [];
+      const interactiveLabels = (node) => interactiveElements(node)
+        .map((candidate) => normalize(candidate.textContent || candidate.getAttribute('aria-label') || candidate.getAttribute('title')))
+        .filter(Boolean);
+      const artifactLabelsForNode = (node) => extractArtifactLabels(node?.textContent || '');
       const otherTextLength = (text, labels) => {
         let remaining = normalize(text);
         for (const label of labels || []) {
@@ -1528,25 +1552,43 @@ async function collectArtifactCandidates(job, responseIndex, responseText = "")
         return remaining.length;
       };
       const focusableFor = (node) => node?.closest('[tabindex]');
+      const uniqueLabel = (...groups) => {
+        for (const group of groups) {
+          const labels = Array.from(new Set((group || []).map(sanitizeArtifactLabel).filter(Boolean)));
+          if (labels.length === 1) return labels[0];
+        }
+        return undefined;
+      };
 
-      const candidates = Array.from(host.querySelectorAll('button, a'))
-        .map((button) => {
-          const label = normalize(button.textContent);
-          if (!isFileLabel(label)) return null;
+      const candidates = interactiveElements(host)
+        .map((button, index) => {
+          const controlLabel = normalize(button.textContent || button.getAttribute('aria-label') || button.getAttribute('title'));
           const paragraph = button.closest('p');
           const listItem = button.closest('li');
           const focusable = focusableFor(button);
-          const paragraphFileLabels = fileButtons(paragraph);
-          const focusableFileLabels = fileButtons(focusable);
+          const ownArtifactLabels = extractArtifactLabels(controlLabel);
+          const paragraphArtifactLabels = artifactLabelsForNode(paragraph);
+          const listItemArtifactLabels = artifactLabelsForNode(listItem);
+          const focusableArtifactLabels = artifactLabelsForNode(focusable);
+          const label = uniqueLabel(ownArtifactLabels, listItemArtifactLabels, paragraphArtifactLabels, focusableArtifactLabels);
+          if (!label && !isFileLabel(controlLabel) && !isDownloadControl(controlLabel)) return null;
+          if (!label) return null;
+          const marker = artifactPrefix + index;
+          button.setAttribute(artifactMarkerAttr, marker);
           return {
             label,
+            selector: '[' + artifactMarkerAttr + '="' + marker + '"]',
+            controlLabel,
             paragraphText: normalize(paragraph?.textContent),
             listItemText: normalize(listItem?.textContent),
-            paragraphFileButtonCount: paragraphFileLabels.length,
-            paragraphOtherTextLength: otherTextLength(paragraph?.textContent, paragraphFileLabels),
-            listItemFileButtonCount: fileButtons(listItem).length,
-            focusableFileButtonCount: focusableFileLabels.length,
-            focusableOtherTextLength: otherTextLength(focusable?.textContent, focusableFileLabels),
+            paragraphInteractiveCount: interactiveElements(paragraph).length,
+            paragraphArtifactLabelCount: Array.from(new Set(paragraphArtifactLabels)).length,
+            paragraphOtherTextLength: otherTextLength(paragraph?.textContent, [...paragraphArtifactLabels, ...interactiveLabels(paragraph)]),
+            listItemInteractiveCount: interactiveElements(listItem).length,
+            listItemArtifactLabelCount: Array.from(new Set(listItemArtifactLabels)).length,
+            focusableInteractiveCount: interactiveElements(focusable).length,
+            focusableArtifactLabelCount: Array.from(new Set(focusableArtifactLabels)).length,
+            focusableOtherTextLength: otherTextLength(focusable?.textContent, [...focusableArtifactLabels, ...interactiveLabels(focusable)]),
           };
         })
         .filter(Boolean);
@@ -1555,10 +1597,26 @@ async function collectArtifactCandidates(job, responseIndex, responseText = "")
     `),
   );
 
+  const partitioned = partitionStructuralArtifactCandidates(structural?.candidates || []);
+  const snapshotEntries = parseSnapshotEntries(targetSlice);
+  const hasGenericArtifactControl = snapshotEntries.some(
+    (entry) =>
+      (entry.kind === "button" || entry.kind === "link") &&
+      !entry.disabled &&
+      /(?:^|\b)(?:download|save)(?:\b|$)/i.test(`${entry.label || ""} ${entry.value || ""}`),
+  );
+  const suspiciousFromText = hasGenericArtifactControl
+    ? extractArtifactLabels(responseText)
+        .filter((label) => !partitioned.confirmed.some((candidate) => candidate.label === label) && !partitioned.suspicious.some((candidate) => candidate.label === label))
+        .map((label) => ({ label }))
+    : [];
+
   return {
     snapshot,
     targetSlice,
-    candidates: filterStructuralArtifactCandidates(structural?.candidates || []),
+    candidates: partitioned.confirmed,
+    suspiciousLabels: [...partitioned.suspicious.map((candidate) => candidate.label), ...suspiciousFromText.map((candidate) => candidate.label)]
+      .filter((label, index, labels) => labels.indexOf(label) === index),
   };
 }
 
@@ -1566,11 +1624,14 @@ async function waitForStableArtifactCandidates(job, responseIndex, responseText
   const deadline = Date.now() + ARTIFACT_CANDIDATE_STABILITY_TIMEOUT_MS;
   let lastSignature;
   let stablePolls = 0;
-  let latest = { snapshot: "", targetSlice: undefined, candidates: [] };
+  let latest = { snapshot: "", targetSlice: undefined, candidates: [], suspiciousLabels: [] };
 
   while (Date.now() < deadline) {
     latest = await collectArtifactCandidates(job, responseIndex, responseText);
-    const signature = latest.candidates.map((candidate) => candidate.label).join("\n");
+    const signature = JSON.stringify({
+      candidates: latest.candidates.map((candidate) => candidate.label),
+      suspiciousLabels: latest.suspiciousLabels,
+    });
     if (signature === lastSignature) stablePolls += 1;
     else {
       lastSignature = signature;
@@ -1628,7 +1689,7 @@ async function downloadArtifacts(job, responseIndex, responseText = "") {
     return [];
   }
 
-  const { targetSlice, candidates } = await reopenConversationForArtifacts(job, responseIndex, responseText, "initial");
+  let { targetSlice, candidates, suspiciousLabels } = await reopenConversationForArtifacts(job, responseIndex, responseText, "initial");
   if (!targetSlice) {
     await log(`No assistant response found in snapshot for response index ${responseIndex}`);
     await secureWriteText(`${jobDir}/artifacts.json`, "[]\n");
@@ -1637,33 +1698,32 @@ async function downloadArtifacts(job, responseIndex, responseText = "") {
   }
 
   await log(`Artifact candidates: ${candidates.map((candidate) => candidate.label).join(", ") || "(none)"}`);
+  if (suspiciousLabels.length > 0) {
+    await log(`Suspicious artifact signals: ${suspiciousLabels.join(", ")}`);
+  }
 
   const artifactsDir = `${jobDir}/artifacts`;
   await ensurePrivateDir(artifactsDir);
   const artifacts = [];
   await flushArtifactsState(artifacts);
 
-  for (const [index, candidate] of candidates.entries()) {
+  for (const [index, originalCandidate] of candidates.entries()) {
     let downloaded = false;
+    let activeCandidate = originalCandidate;
     for (let attempt = 1; attempt <= ARTIFACT_DOWNLOAD_MAX_ATTEMPTS && !downloaded; attempt += 1) {
-      const freshSnapshot = await snapshotText(job);
-      const freshSlice = assistantSnapshotSlice(freshSnapshot, responseIndex);
-      if (!freshSlice) break;
-      const freshEntries = parseSnapshotEntries(freshSlice);
-      const entry = freshEntries.find(
-        (artifactEntry) => artifactEntry.label === candidate.label && (artifactEntry.kind === "button" || artifactEntry.kind === "link") && !artifactEntry.disabled,
-      );
-      if (!entry) {
-        await log(`Artifact "${candidate.label}" not found in fresh snapshot, skipping`);
+      if (!activeCandidate?.selector) {
+        await log(`Artifact "${originalCandidate.label}" has no live selector, marking unconfirmed`);
+        artifacts.push({ displayName: originalCandidate.label, unconfirmed: true, error: "Artifact candidate lost its live selector before download." });
+        await flushArtifactsState(artifacts);
         break;
       }
 
-      const destinationPath = join(artifactsDir, preferredArtifactName(candidate.label, index));
+      const destinationPath = join(artifactsDir, preferredArtifactName(originalCandidate.label, index));
       await rm(destinationPath, { force: true }).catch(() => undefined);
       try {
-        await log(`Artifact "${candidate.label}" download attempt ${attempt}/${ARTIFACT_DOWNLOAD_MAX_ATTEMPTS} using ref ${entry.ref}`);
+        await log(`Artifact "${originalCandidate.label}" download attempt ${attempt}/${ARTIFACT_DOWNLOAD_MAX_ATTEMPTS} using selector ${activeCandidate.selector}`);
         await withHeartbeatWhile(() =>
-          agentBrowser(job, "download", entry.ref, destinationPath, {
+          agentBrowser(job, "download", activeCandidate.selector, destinationPath, {
             timeoutMs: ARTIFACT_DOWNLOAD_TIMEOUT_MS,
           }),
         );
@@ -1675,7 +1735,7 @@ async function downloadArtifacts(job, responseIndex, responseText = "") {
           detectType(destinationPath),
         ]);
         artifacts.push({
-          displayName: candidate.label,
+          displayName: originalCandidate.label,
           fileName: basename(destinationPath),
           copiedPath: destinationPath,
           size,
@@ -1686,11 +1746,15 @@ async function downloadArtifacts(job, responseIndex, responseText = "") {
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         await rm(destinationPath, { force: true }).catch(() => undefined);
-        await log(`Artifact "${candidate.label}" download failed on attempt ${attempt}/${ARTIFACT_DOWNLOAD_MAX_ATTEMPTS}: ${message}`);
+        await log(`Artifact "${originalCandidate.label}" download failed on attempt ${attempt}/${ARTIFACT_DOWNLOAD_MAX_ATTEMPTS}: ${message}`);
         if (attempt >= ARTIFACT_DOWNLOAD_MAX_ATTEMPTS) {
-          artifacts.push({ displayName: candidate.label, unconfirmed: true, error: message });
+          artifacts.push({ displayName: originalCandidate.label, unconfirmed: true, error: message });
         } else {
-          await reopenConversationForArtifacts(job, responseIndex, responseText, `retry ${attempt + 1} for ${candidate.label}`);
+          const refreshed = await reopenConversationForArtifacts(job, responseIndex, responseText, `retry ${attempt + 1} for ${originalCandidate.label}`);
+          targetSlice = refreshed.targetSlice;
+          candidates = refreshed.candidates;
+          suspiciousLabels = refreshed.suspiciousLabels;
+          activeCandidate = candidates.find((candidate) => candidate.label === originalCandidate.label);
           await sleep(1_000);
         }
       } finally {
@@ -1699,6 +1763,16 @@ async function downloadArtifacts(job, responseIndex, responseText = "") {
     }
   }
 
+  const capturedArtifactLabels = new Set(artifacts.map((artifact) => artifact.displayName).filter(Boolean));
+  const missedArtifactLabels = suspiciousLabels.filter((label) => !capturedArtifactLabels.has(label));
+  if (missedArtifactLabels.length > 0) {
+    await log(`Marking missed artifact signals as unconfirmed: ${missedArtifactLabels.join(", ")}`);
+    for (const label of missedArtifactLabels) {
+      artifacts.push({ displayName: label, unconfirmed: true, error: "Response-local artifact signal was present, but no downloadable artifact was captured." });
+    }
+    await flushArtifactsState(artifacts);
+  }
+
   return artifacts;
 }
 
@@ -1759,9 +1833,10 @@ async function run() {
     currentJob = await mutateJob((job) => ({ ...job, ...phasePatch("downloading_artifacts", { heartbeatAt: new Date().toISOString() }) }));
     const artifacts = await downloadArtifacts(currentJob, completion.responseIndex, completion.responseText);
     const artifactFailureCount = artifacts.filter((artifact) => artifact.unconfirmed || artifact.error).length;
+    const finalPhase = artifactFailureCount > 0 ? "complete_with_artifact_errors" : "complete";
 
     await heartbeat(
-      phasePatch(artifactFailureCount > 0 ? "complete_with_artifact_errors" : "complete", {
+      phasePatch(finalPhase, {
         status: "complete",
         completedAt: new Date().toISOString(),
         responsePath: currentJob.responsePath,
@@ -1773,7 +1848,7 @@ async function run() {
     );
     const persistedJob = await readJob().catch(() => undefined);
     await log(`Persisted final status after completion write: ${persistedJob?.status || "unknown"}`);
-    await log(`Job ${currentJob.id} complete`);
+    await log(`Job ${currentJob.id} complete (${finalPhase}, artifact failures=${artifactFailureCount})`);
   } catch (error) {
     if (!shuttingDown) {
       const message = error instanceof Error ? error.message : String(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-oracle",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "ChatGPT web-oracle extension for pi with isolated browser auth, async jobs, and project-context archives.",
   "private": false,
   "license": "MIT",