@steipete/oracle 1.0.8 → 1.2.0

package/dist/src/oracle/run.js

@@ -8,11 +8,13 @@ import { APIConnectionError, APIConnectionTimeoutError } from 'openai';
 import { DEFAULT_SYSTEM_PROMPT, MODEL_CONFIGS, TOKENIZER_OPTIONS } from './config.js';
 import { readFiles } from './files.js';
 import { buildPrompt, buildRequestBody } from './request.js';
+import { estimateRequestTokens } from './tokenEstimate.js';
 import { formatElapsed, formatUSD } from './format.js';
 import { getFileTokenStats, printFileTokenStats } from './tokenStats.js';
 import { OracleResponseError, OracleTransportError, PromptValidationError, describeTransportError, toTransportError, } from './errors.js';
 import { createDefaultClientFactory } from './client.js';
 import { startHeartbeat } from '../heartbeat.js';
+import { startOscProgress } from './oscProgress.js';
 import { getCliVersion } from '../version.js';
 import { createFsAdapter } from './fsAdapter.js';
 const isTty = process.stdout.isTTY;
@@ -84,19 +86,23 @@ export async function runOracle(options, deps = {}) {
     logVerbose(`Attached files use ${totalFileTokens.toLocaleString()} tokens`);
     const systemPrompt = options.system?.trim() || DEFAULT_SYSTEM_PROMPT;
     const promptWithFiles = buildPrompt(options.prompt, files, cwd);
-    const tokenizerInput = [
-        { role: 'system', content: systemPrompt },
-        { role: 'user', content: promptWithFiles },
-    ];
-    const estimatedInputTokens = modelConfig.tokenizer(tokenizerInput, TOKENIZER_OPTIONS);
-    logVerbose(`Estimated tokens (prompt + files): ${estimatedInputTokens.toLocaleString()}`);
     const fileCount = files.length;
     const cliVersion = getCliVersion();
     const richTty = process.stdout.isTTY && chalk.level > 0;
     const headerModelLabel = richTty ? chalk.cyan(modelConfig.model) : modelConfig.model;
+    const requestBody = buildRequestBody({
+        modelConfig,
+        systemPrompt,
+        userPrompt: promptWithFiles,
+        searchEnabled,
+        maxOutputTokens: options.maxOutput,
+        background: useBackground,
+        storeResponse: useBackground,
+    });
+    const estimatedInputTokens = estimateRequestTokens(requestBody, modelConfig);
     const tokenLabel = richTty ? chalk.green(estimatedInputTokens.toLocaleString()) : estimatedInputTokens.toLocaleString();
     const fileLabel = richTty ? chalk.magenta(fileCount.toString()) : fileCount.toString();
-    const headerLine = `Oracle (${cliVersion}) consulting ${headerModelLabel}'s crystal ball with ${tokenLabel} tokens and ${fileLabel} files...`;
+    const headerLine = `oracle (${cliVersion}) consulting ${headerModelLabel}'s crystal ball with ${tokenLabel} tokens and ${fileLabel} files...`;
     const shouldReportFiles = (options.filesReport || fileTokenInfo.totalTokens > inputTokenBudget) && fileTokenInfo.stats.length > 0;
     if (!isPreview) {
         log(headerLine);
@@ -111,15 +117,7 @@ export async function runOracle(options, deps = {}) {
     if (estimatedInputTokens > inputTokenBudget) {
         throw new PromptValidationError(`Input too large (${estimatedInputTokens.toLocaleString()} tokens). Limit is ${inputTokenBudget.toLocaleString()} tokens.`, { estimatedInputTokens, inputTokenBudget });
     }
-    const requestBody = buildRequestBody({
-        modelConfig,
-        systemPrompt,
-        userPrompt: promptWithFiles,
-        searchEnabled,
-        maxOutputTokens: options.maxOutput,
-        background: useBackground,
-        storeResponse: useBackground,
-    });
+    logVerbose(`Estimated tokens (request body): ${estimatedInputTokens.toLocaleString()}`);
     if (isPreview && previewMode) {
         if (previewMode === 'json' || previewMode === 'full') {
             log('Request JSON');
@@ -142,6 +140,11 @@ export async function runOracle(options, deps = {}) {
     }
     const openAiClient = client ?? clientFactory(apiKey);
     logVerbose('Dispatching request to OpenAI Responses API...');
+    const stopOscProgress = startOscProgress({
+        label: useBackground ? 'Waiting for OpenAI (background)' : 'Waiting for OpenAI',
+        targetMs: useBackground ? BACKGROUND_MAX_WAIT_MS : 10 * 60_000,
+        write,
+    });
     const runStart = now();
     let response = null;
     let elapsedMs = 0;
@@ -154,74 +157,98 @@ export async function runOracle(options, deps = {}) {
             answerHeaderPrinted = true;
         }
     };
-    if (useBackground) {
-        response = await executeBackgroundResponse({
-            client: openAiClient,
-            requestBody,
-            log,
-            wait,
-            heartbeatIntervalMs: options.heartbeatIntervalMs,
-            now,
-        });
-        elapsedMs = now() - runStart;
-    }
-    else {
-        const stream = await openAiClient.responses.stream(requestBody);
-        let heartbeatActive = false;
-        let stopHeartbeat = null;
-        const stopHeartbeatNow = () => {
-            if (!heartbeatActive) {
-                return;
-            }
-            heartbeatActive = false;
-            stopHeartbeat?.();
-            stopHeartbeat = null;
-        };
-        if (options.heartbeatIntervalMs && options.heartbeatIntervalMs > 0) {
-            heartbeatActive = true;
-            stopHeartbeat = startHeartbeat({
-                intervalMs: options.heartbeatIntervalMs,
-                log: (message) => log(message),
-                isActive: () => heartbeatActive,
-                makeMessage: (elapsedMs) => {
-                    const elapsedText = formatElapsed(elapsedMs);
-                    return `API connection active — ${elapsedText} elapsed. Expect up to ~10 min before GPT-5 responds.`;
-                },
+    try {
+        if (useBackground) {
+            response = await executeBackgroundResponse({
+                client: openAiClient,
+                requestBody,
+                log,
+                wait,
+                heartbeatIntervalMs: options.heartbeatIntervalMs,
+                now,
             });
+            elapsedMs = now() - runStart;
         }
-        try {
-            for await (const event of stream) {
-                if (event.type === 'response.output_text.delta') {
-                    stopHeartbeatNow();
-                    sawTextDelta = true;
-                    ensureAnswerHeader();
-                    if (!options.silent && typeof event.delta === 'string') {
-                        write(event.delta);
+        else {
+            const stream = await openAiClient.responses.stream(requestBody);
+            let heartbeatActive = false;
+            let stopHeartbeat = null;
+            const stopHeartbeatNow = () => {
+                if (!heartbeatActive) {
+                    return;
+                }
+                heartbeatActive = false;
+                stopHeartbeat?.();
+                stopHeartbeat = null;
+            };
+            if (options.heartbeatIntervalMs && options.heartbeatIntervalMs > 0) {
+                heartbeatActive = true;
+                stopHeartbeat = startHeartbeat({
+                    intervalMs: options.heartbeatIntervalMs,
+                    log: (message) => log(message),
+                    isActive: () => heartbeatActive,
+                    makeMessage: (elapsedMs) => {
+                        const elapsedText = formatElapsed(elapsedMs);
+                        return `API connection active — ${elapsedText} elapsed. Expect up to ~10 min before GPT-5 responds.`;
+                    },
+                });
+            }
+            try {
+                for await (const event of stream) {
+                    if (event.type === 'response.output_text.delta') {
+                        stopOscProgress();
+                        stopHeartbeatNow();
+                        sawTextDelta = true;
+                        ensureAnswerHeader();
+                        if (!options.silent && typeof event.delta === 'string') {
+                            write(event.delta);
+                        }
                     }
                 }
             }
-        }
-        catch (streamError) {
-            if (typeof stream.abort === 'function') {
-                stream.abort();
+            catch (streamError) {
+                if (typeof stream.abort === 'function') {
+                    stream.abort();
+                }
+                stopHeartbeatNow();
+                const transportError = toTransportError(streamError);
+                log(chalk.yellow(describeTransportError(transportError)));
+                throw transportError;
             }
+            response = await stream.finalResponse();
             stopHeartbeatNow();
-            const transportError = toTransportError(streamError);
-            log(chalk.yellow(describeTransportError(transportError)));
-            throw transportError;
+            elapsedMs = now() - runStart;
         }
-        response = await stream.finalResponse();
-        stopHeartbeatNow();
-        elapsedMs = now() - runStart;
+    }
+    finally {
+        stopOscProgress();
     }
     if (!response) {
         throw new Error('OpenAI did not return a response.');
     }
     logVerbose(`Response status: ${response.status ?? 'completed'}`);
     if (response.status && response.status !== 'completed') {
-        const detail = response.error?.message || response.incomplete_details?.reason || response.status;
-        log(chalk.yellow(`OpenAI ended the run early (status=${response.status}${response.incomplete_details?.reason ? `, reason=${response.incomplete_details.reason}` : ''}).`));
-        throw new OracleResponseError(`Response did not complete: ${detail}`, response);
+        // OpenAI can reply `in_progress` even after the stream closes; give it a brief grace poll.
+        if (response.id && response.status === 'in_progress') {
+            const polishingStart = now();
+            const pollIntervalMs = 2_000;
+            const maxWaitMs = 60_000;
+            log(chalk.dim('Response still in_progress; polling until completion...'));
+            // Short polling loop — we don't want to hang forever, just catch late finalization.
+            while (now() - polishingStart < maxWaitMs) {
+                await wait(pollIntervalMs);
+                const refreshed = await openAiClient.responses.retrieve(response.id);
+                if (refreshed.status === 'completed') {
+                    response = refreshed;
+                    break;
+                }
+            }
+        }
+        if (response.status !== 'completed') {
+            const detail = response.error?.message || response.incomplete_details?.reason || response.status;
+            log(chalk.yellow(`OpenAI ended the run early (status=${response.status}${response.incomplete_details?.reason ? `, reason=${response.incomplete_details.reason}` : ''}).`));
+            throw new OracleResponseError(`Response did not complete: ${detail}`, response);
+        }
     }
     const answerText = extractTextOutput(response);
     if (!options.silent) {
@@ -250,6 +277,12 @@ export async function runOracle(options, deps = {}) {
         .map((value, index) => formatTokenValue(value, usage, index))
         .join('/');
     statsParts.push(`tok(i/o/r/t)=${tokensDisplay}`);
+    const actualInput = usage.input_tokens;
+    if (actualInput !== undefined) {
+        const delta = actualInput - estimatedInputTokens;
+        const deltaText = delta === 0 ? '' : delta > 0 ? ` (+${delta.toLocaleString()})` : ` (${delta.toLocaleString()})`;
+        statsParts.push(`est→actual=${estimatedInputTokens.toLocaleString()}→${actualInput.toLocaleString()}${deltaText}`);
+    }
     if (!searchEnabled) {
         statsParts.push('search=off');
     }
@@ -260,7 +293,7 @@ export async function runOracle(options, deps = {}) {
     return {
         mode: 'live',
         response,
-        usage: { inputTokens, outputTokens, reasoningTokens, totalTokens },
+        usage: { inputTokens, outputTokens, reasoningTokens, totalTokens, cost },
         elapsedMs,
     };
 }

package/dist/src/oracle/tokenEstimate.js

@@ -0,0 +1,34 @@
+import { TOKENIZER_OPTIONS } from './config.js';
+/**
+ * Estimate input tokens from the full request body instead of just system/user text.
+ * This is a conservative approximation: we tokenize the key textual fields and add a fixed buffer
+ * to cover structural JSON overhead and server-side wrappers (tools/reasoning/background/store).
+ */
+export function estimateRequestTokens(requestBody, modelConfig, bufferTokens = 200) {
+    const parts = [];
+    if (requestBody.instructions) {
+        parts.push(requestBody.instructions);
+    }
+    for (const turn of requestBody.input ?? []) {
+        for (const content of turn.content ?? []) {
+            if (typeof content.text === 'string') {
+                parts.push(content.text);
+            }
+        }
+    }
+    if (requestBody.tools && requestBody.tools.length > 0) {
+        parts.push(JSON.stringify(requestBody.tools));
+    }
+    if (requestBody.reasoning) {
+        parts.push(JSON.stringify(requestBody.reasoning));
+    }
+    if (requestBody.background) {
+        parts.push('background:true');
+    }
+    if (requestBody.store) {
+        parts.push('store:true');
+    }
+    const concatenated = parts.join('\n');
+    const baseEstimate = modelConfig.tokenizer(concatenated, TOKENIZER_OPTIONS);
+    return baseEstimate + bufferTokens;
+}

package/dist/src/sessionManager.js

@@ -5,6 +5,7 @@ import { createWriteStream } from 'node:fs';
 const ORACLE_HOME = process.env.ORACLE_HOME_DIR ?? path.join(os.homedir(), '.oracle');
 const SESSIONS_DIR = path.join(ORACLE_HOME, 'sessions');
 const MAX_STATUS_LIMIT = 1000;
+const ZOMBIE_MAX_AGE_MS = 30 * 60 * 1000; // 30 minutes
 const DEFAULT_SLUG = 'session';
 const MAX_SLUG_WORDS = 5;
 const MIN_CUSTOM_SLUG_WORDS = 3;
@@ -67,7 +68,7 @@ async function ensureUniqueSessionId(baseSlug) {
     }
     return candidate;
 }
-export async function initializeSession(options, cwd) {
+export async function initializeSession(options, cwd, notifications) {
     await ensureSessionStorage();
     const baseSlug = createSessionId(options.prompt || DEFAULT_SLUG, options.slug);
     const sessionId = await ensureUniqueSessionId(baseSlug);
@@ -84,6 +85,7 @@ export async function initializeSession(options, cwd) {
         cwd,
         mode,
         browser: browserConfig ? { config: browserConfig } : undefined,
+        notifications,
         options: {
             prompt: options.prompt,
             file: options.file ?? [],
@@ -99,7 +101,9 @@ export async function initializeSession(options, cwd) {
             verbose: options.verbose,
             heartbeatIntervalMs: options.heartbeatIntervalMs,
             browserInlineFiles: options.browserInlineFiles,
+            browserBundleFiles: options.browserBundleFiles,
             background: options.background,
+            search: options.search,
         },
     };
     await fs.writeFile(metaPath(sessionId), JSON.stringify(metadata, null, 2), 'utf8');
@@ -110,7 +114,8 @@ export async function initializeSession(options, cwd) {
 export async function readSessionMetadata(sessionId) {
     try {
         const raw = await fs.readFile(metaPath(sessionId), 'utf8');
-        return JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        return await markZombie(parsed, { persist: false }); // transient check; do not touch disk on single read
     }
     catch {
         return null;
@@ -138,8 +143,9 @@ export async function listSessionsMetadata() {
     const entries = await fs.readdir(SESSIONS_DIR).catch(() => []);
     const metas = [];
     for (const entry of entries) {
-        const meta = await readSessionMetadata(entry);
+        let meta = await readSessionMetadata(entry);
         if (meta) {
+            meta = await markZombie(meta, { persist: true }); // keep stored metadata consistent with zombie detection
             metas.push(meta);
         }
     }
@@ -164,6 +170,15 @@ export async function readSessionLog(sessionId) {
         return '';
     }
 }
+export async function readSessionRequest(sessionId) {
+    try {
+        const raw = await fs.readFile(requestPath(sessionId), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
 export async function deleteSessionsOlderThan({ hours = 24, includeAll = false, } = {}) {
     await ensureSessionStorage();
     const entries = await fs.readdir(SESSIONS_DIR).catch(() => []);
@@ -203,3 +218,50 @@ export async function wait(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 export { ORACLE_HOME, SESSIONS_DIR, MAX_STATUS_LIMIT };
+export { ZOMBIE_MAX_AGE_MS };
+export async function getSessionPaths(sessionId) {
+    const dir = sessionDir(sessionId);
+    const metadata = metaPath(sessionId);
+    const log = logPath(sessionId);
+    const request = requestPath(sessionId);
+    const required = [metadata, log, request];
+    const missing = [];
+    for (const file of required) {
+        if (!(await fileExists(file))) {
+            missing.push(path.basename(file));
+        }
+    }
+    if (missing.length > 0) {
+        throw new Error(`Session "${sessionId}" is missing: ${missing.join(', ')}`);
+    }
+    return { dir, metadata, log, request };
+}
+async function markZombie(meta, { persist }) {
+    if (!isZombie(meta)) {
+        return meta;
+    }
+    const updated = {
+        ...meta,
+        status: 'error',
+        errorMessage: 'Session marked as zombie (>30m stale)',
+        completedAt: new Date().toISOString(),
+    };
+    if (persist) {
+        await fs.writeFile(metaPath(meta.id), JSON.stringify(updated, null, 2), 'utf8');
+    }
+    return updated;
+}
+function isZombie(meta) {
+    if (meta.status !== 'running') {
+        return false;
+    }
+    const reference = meta.startedAt ?? meta.createdAt;
+    if (!reference) {
+        return false;
+    }
+    const startedMs = Date.parse(reference);
+    if (Number.isNaN(startedMs)) {
+        return false;
+    }
+    return Date.now() - startedMs > ZOMBIE_MAX_AGE_MS;
+}

package/dist/vendor/oracle-notifier/OracleNotifier.app/Contents/Info.plist

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleIdentifier</key>
+  <string>com.steipete.oracle.notifier</string>
+  <key>CFBundleName</key>
+  <string>OracleNotifier</string>
+  <key>CFBundleDisplayName</key>
+  <string>Oracle Notifier</string>
+  <key>CFBundleExecutable</key>
+  <string>OracleNotifier</string>
+  <key>CFBundleIconFile</key>
+  <string>OracleIcon</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>LSMinimumSystemVersion</key>
+  <string>13.0</string>
+</dict>
+</plist>

package/dist/vendor/oracle-notifier/OracleNotifier.app/Contents/_CodeSignature/CodeResources

@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>files</key>
+	<dict>
+		<key>Resources/OracleIcon.icns</key>
+		<data>
+		edUHAMetayIv3xtc3Vb92VXRLfM=
+		</data>
+	</dict>
+	<key>files2</key>
+	<dict>
+		<key>Resources/OracleIcon.icns</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			AVPJK/6w6IOsDLmZTW4hL+Za+/4wHMxZiIp0t6m3NRA=
+			</data>
+		</dict>
+	</dict>
+	<key>rules</key>
+	<dict>
+		<key>^Resources/</key>
+		<true/>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^version.plist$</key>
+		<true/>
+	</dict>
+	<key>rules2</key>
+	<dict>
+		<key>.*\.dSYM($|/)</key>
+		<dict>
+			<key>weight</key>
+			<real>11</real>
+		</dict>
+		<key>^(.*/)?\.DS_Store$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>2000</real>
+		</dict>
+		<key>^(Frameworks|SharedFrameworks|PlugIns|Plug-ins|XPCServices|Helpers|MacOS|Library/(Automator|Spotlight|LoginItems))/</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^.*</key>
+		<true/>
+		<key>^Info\.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^PkgInfo$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^[^/]+$</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^embedded\.provisionprofile$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^version\.plist$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+	</dict>
+</dict>
+</plist>

package/dist/vendor/oracle-notifier/OracleNotifier.swift

@@ -0,0 +1,45 @@
+import Foundation
+import UserNotifications
+
+let args = CommandLine.arguments
+// Usage: OracleNotifier <title> <message> [soundName]
+if args.count < 3 {
+  fputs("usage: OracleNotifier <title> <message> [soundName]\n", stderr)
+  exit(1)
+}
+let title = args[1]
+let message = args[2]
+let soundName = args.count >= 4 ? args[3] : "Glass"
+
+let center = UNUserNotificationCenter.current()
+let group = DispatchGroup()
+group.enter()
+center.requestAuthorization(options: [.alert, .sound, .badge]) { granted, error in
+  if let error = error {
+    fputs("auth error: \(error)\n", stderr)
+    group.leave()
+    return
+  }
+  if !granted {
+    fputs("authorization not granted\n", stderr)
+    group.leave()
+    return
+  }
+  let content = UNMutableNotificationContent()
+  content.title = title
+  content.body = message
+  if !soundName.isEmpty {
+    content.sound = UNNotificationSound(named: UNNotificationSoundName(rawValue: soundName))
+  } else {
+    content.sound = UNNotificationSound.default
+  }
+  let request = UNNotificationRequest(identifier: UUID().uuidString, content: content, trigger: nil)
+  center.add(request) { addError in
+    if let addError = addError {
+      fputs("add error: \(addError)\n", stderr)
+    }
+    group.leave()
+  }
+}
+_ = group.wait(timeout: .now() + 2)
+RunLoop.current.run(until: Date().addingTimeInterval(1))

package/dist/vendor/oracle-notifier/README.md

@@ -0,0 +1,24 @@
+# Oracle Notifier helper (macOS, arm64)
+
+Builds a tiny signed helper app for macOS notifications with the Oracle icon.
+
+## Build
+
+```bash
+cd vendor/oracle-notifier
+# Optional: notarize by setting App Store Connect key credentials
+export APP_STORE_CONNECT_API_KEY_P8="$(cat AuthKey_XXXXXX.p8)" # with literal newlines or \n escaped
+export APP_STORE_CONNECT_KEY_ID=XXXXXX
+export APP_STORE_CONNECT_ISSUER_ID=YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY
+./build-notifier.sh
+```
+
+- Requires Xcode command line tools (swiftc) and a macOS Developer ID certificate. Without a valid cert, the build fails (no ad-hoc fallback).
+- If `APP_STORE_CONNECT_*` vars are set, the script notarizes and staples the ticket.
+- Output: `OracleNotifier.app` (arm64 only), bundled with `OracleIcon.icns`.
+
+## Usage
+The CLI prefers this helper on macOS; if it fails or is missing, it falls back to toasted-notifier/terminal-notifier.
+
+## Permissions
+After first run, allow notifications for “Oracle Notifier” in System Settings → Notifications.