@steipete/oracle 1.1.0 → 1.2.0

package/dist/src/mcp/tools/sessionResources.js

@@ -0,0 +1,64 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import fs from 'node:fs/promises';
+import { getSessionPaths, readSessionLog, readSessionMetadata } from '../../sessionManager.js';
+// URIs:
+// - oracle-session://<id>/metadata
+// - oracle-session://<id>/log
+// - oracle-session://<id>/request
+export function registerSessionResources(server) {
+    const template = new ResourceTemplate('oracle-session://{id}/{kind}', { list: undefined });
+    server.registerResource('oracle-session', template, {
+        title: 'oracle session resources',
+        description: 'Read stored session metadata, log, or request payload.',
+    }, async (uri, variables) => {
+        const idRaw = variables?.id;
+        const kindRaw = variables?.kind;
+        // uri-template variables arrive as string | string[]; collapse to first value.
+        const id = Array.isArray(idRaw) ? idRaw[0] : idRaw;
+        const kind = Array.isArray(kindRaw) ? kindRaw[0] : kindRaw;
+        if (!id || !kind) {
+            throw new Error('Missing id or kind');
+        }
+        const paths = await getSessionPaths(id);
+        switch (kind) {
+            case 'metadata': {
+                const metadata = await readSessionMetadata(id);
+                if (!metadata) {
+                    throw new Error(`Session "${id}" not found.`);
+                }
+                return {
+                    contents: [
+                        {
+                            uri: uri.href,
+                            text: JSON.stringify(metadata, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'log': {
+                const log = await readSessionLog(id);
+                return {
+                    contents: [
+                        {
+                            uri: uri.href,
+                            text: log,
+                        },
+                    ],
+                };
+            }
+            case 'request': {
+                const raw = await fs.readFile(paths.request, 'utf8');
+                return {
+                    contents: [
+                        {
+                            uri: uri.href,
+                            text: raw,
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unsupported resource kind: ${kind}`);
+        }
+    });
+}

package/dist/src/mcp/tools/sessions.js

@@ -0,0 +1,106 @@
+import fs from 'node:fs/promises';
+import { z } from 'zod';
+import { filterSessionsByRange, getSessionPaths, listSessionsMetadata, readSessionLog, readSessionMetadata, } from '../../sessionManager.js';
+import { sessionsInputSchema } from '../types.js';
+const sessionsInputShape = {
+    id: z.string().optional(),
+    hours: z.number().optional(),
+    limit: z.number().optional(),
+    includeAll: z.boolean().optional(),
+    detail: z.boolean().optional(),
+};
+const sessionsOutputShape = {
+    entries: z
+        .array(z.object({
+        id: z.string(),
+        createdAt: z.string(),
+        status: z.string(),
+        model: z.string().optional(),
+        mode: z.string().optional(),
+    }))
+        .optional(),
+    total: z.number().optional(),
+    truncated: z.boolean().optional(),
+    session: z
+        .object({
+        metadata: z.record(z.string(), z.any()),
+        log: z.string(),
+        request: z.record(z.string(), z.any()).optional(),
+    })
+        .optional(),
+};
+export function registerSessionsTool(server) {
+    server.registerTool('sessions', {
+        title: 'List or fetch oracle sessions',
+        description: 'List stored sessions (same defaults as `oracle status`) or, with id/slug, return a summary row. Pass detail:true to include metadata, log, and stored request for that session.',
+        inputSchema: sessionsInputShape,
+        outputSchema: sessionsOutputShape,
+    }, async (input) => {
+        const textContent = (text) => [{ type: 'text', text }];
+        const { id, hours = 24, limit = 100, includeAll = false, detail = false } = sessionsInputSchema.parse(input);
+        if (id) {
+            if (!detail) {
+                const metadata = await readSessionMetadata(id);
+                if (!metadata) {
+                    throw new Error(`Session "${id}" not found.`);
+                }
+                return {
+                    content: textContent(`${metadata.createdAt} | ${metadata.status} | ${metadata.model ?? 'n/a'} | ${metadata.id}`),
+                    structuredContent: {
+                        entries: [
+                            {
+                                id: metadata.id,
+                                createdAt: metadata.createdAt,
+                                status: metadata.status,
+                                model: metadata.model,
+                                mode: metadata.mode,
+                            },
+                        ],
+                        total: 1,
+                        truncated: false,
+                    },
+                };
+            }
+            const metadata = await readSessionMetadata(id);
+            if (!metadata) {
+                throw new Error(`Session "${id}" not found.`);
+            }
+            const log = await readSessionLog(id);
+            let request;
+            try {
+                const paths = await getSessionPaths(id);
+                const raw = await fs.readFile(paths.request, 'utf8');
+                // Old sessions may lack a request payload; treat it as best-effort metadata.
+                request = JSON.parse(raw);
+            }
+            catch {
+                request = undefined;
+            }
+            return {
+                content: textContent(log),
+                structuredContent: { session: { metadata, log, request } },
+            };
+        }
+        const metas = await listSessionsMetadata();
+        const { entries, truncated, total } = filterSessionsByRange(metas, { hours, includeAll, limit });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: entries.map((entry) => `${entry.createdAt} | ${entry.status} | ${entry.model ?? 'n/a'} | ${entry.id}`).join('\n'),
+                },
+            ],
+            structuredContent: {
+                entries: entries.map((entry) => ({
+                    id: entry.id,
+                    createdAt: entry.createdAt,
+                    status: entry.status,
+                    model: entry.model,
+                    mode: entry.mode,
+                })),
+                total,
+                truncated,
+            },
+        };
+    });
+}

package/dist/src/mcp/types.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export const consultInputSchema = z.object({
+    prompt: z.string().min(1, 'Prompt is required.'),
+    files: z.array(z.string()).default([]),
+    model: z.string().optional(),
+    engine: z.enum(['api', 'browser']).optional(),
+    browserModelLabel: z.string().optional(),
+    search: z.boolean().optional(),
+    slug: z.string().optional(),
+});
+export const sessionsInputSchema = z.object({
+    id: z.string().optional(),
+    hours: z.number().optional(),
+    limit: z.number().optional(),
+    includeAll: z.boolean().optional(),
+    detail: z.boolean().optional(),
+});

package/dist/src/mcp/utils.js

@@ -0,0 +1,24 @@
+import { resolveRunOptionsFromConfig } from '../cli/runOptions.js';
+import { Launcher } from 'chrome-launcher';
+export function mapConsultToRunOptions({ prompt, files, model, engine, search, userConfig, env = process.env, }) {
+    // Normalize CLI-style inputs through the shared resolver so config/env defaults apply,
+    // then overlay MCP-only overrides such as explicit search toggles.
+    const result = resolveRunOptionsFromConfig({ prompt, files, model, engine, userConfig, env });
+    if (typeof search === 'boolean') {
+        result.runOptions.search = search;
+    }
+    return result;
+}
+export function ensureBrowserAvailable(engine) {
+    if (engine !== 'browser') {
+        return null;
+    }
+    if (process.env.CHROME_PATH) {
+        return null;
+    }
+    const found = Launcher.getFirstInstallation();
+    if (!found) {
+        return 'Browser engine unavailable: no Chrome installation found and CHROME_PATH is unset.';
+    }
+    return null;
+}

package/dist/src/oracle/files.js

@@ -4,6 +4,7 @@ import fg from 'fast-glob';
 import { FileValidationError } from './errors.js';
 const MAX_FILE_SIZE_BYTES = 1 * 1024 * 1024; // 1 MB
 const DEFAULT_FS = fs;
+const DEFAULT_IGNORED_DIRS = ['node_modules', 'dist', 'coverage', '.git', '.turbo', '.next', 'build', 'tmp'];
 export async function readFiles(filePaths, { cwd = process.cwd(), fsModule = DEFAULT_FS, maxFileSizeBytes = MAX_FILE_SIZE_BYTES } = {}) {
     if (!filePaths || filePaths.length === 0) {
         return [];
@@ -20,7 +21,28 @@ export async function readFiles(filePaths, { cwd = process.cwd(), fsModule = DEF
         }
         candidatePaths = await expandWithCustomFs(partitioned, fsModule);
     }
-    if (candidatePaths.length === 0) {
+    const allowedLiteralDirs = partitioned.literalDirectories
+        .map((dir) => path.resolve(dir))
+        .filter((dir) => DEFAULT_IGNORED_DIRS.includes(path.basename(dir)));
+    const allowedLiteralFiles = partitioned.literalFiles.map((file) => path.resolve(file));
+    const resolvedLiteralDirs = new Set(allowedLiteralDirs);
+    const allowedPaths = new Set([...allowedLiteralDirs, ...allowedLiteralFiles]);
+    const ignoredWhitelist = await buildIgnoredWhitelist(candidatePaths, cwd, fsModule);
+    const ignoredLog = new Set();
+    const filteredCandidates = candidatePaths.filter((filePath) => {
+        const ignoredDir = findIgnoredAncestor(filePath, cwd, resolvedLiteralDirs, allowedPaths, ignoredWhitelist);
+        if (!ignoredDir) {
+            return true;
+        }
+        const displayFile = relativePath(filePath, cwd);
+        const key = `${ignoredDir}|${displayFile}`;
+        if (!ignoredLog.has(key)) {
+            console.log(`Skipping default-ignored path: ${displayFile} (matches ${ignoredDir})`);
+            ignoredLog.add(key);
+        }
+        return false;
+    });
+    if (filteredCandidates.length === 0) {
         throw new FileValidationError('No files matched the provided --file patterns.', {
             patterns: partitioned.globPatterns,
             excludes: partitioned.excludePatterns,
@@ -28,7 +50,7 @@ export async function readFiles(filePaths, { cwd = process.cwd(), fsModule = DEF
     }
     const oversized = [];
     const accepted = [];
-    for (const filePath of candidatePaths) {
+    for (const filePath of filteredCandidates) {
         let stats;
         try {
             stats = await fsModule.stat(filePath);
@@ -111,15 +133,130 @@ async function expandWithNativeGlob(partitioned, cwd) {
     if (patterns.length === 0) {
         return [];
     }
-    const matches = await fg(patterns, {
+    const dotfileOptIn = patterns.some((pattern) => includesDotfileSegment(pattern));
+    const gitignoreSets = await loadGitignoreSets(cwd);
+    const matches = (await fg(patterns, {
         cwd,
-        absolute: true,
+        absolute: false,
         dot: true,
         ignore: partitioned.excludePatterns,
         onlyFiles: true,
         followSymbolicLinks: false,
-    });
-    return Array.from(new Set(matches.map((match) => path.resolve(match))));
+    }));
+    const resolved = matches.map((match) => path.resolve(cwd, match));
+    const filtered = resolved.filter((filePath) => !isGitignored(filePath, gitignoreSets));
+    const finalFiles = dotfileOptIn ? filtered : filtered.filter((filePath) => !path.basename(filePath).startsWith('.'));
+    return Array.from(new Set(finalFiles));
+}
+async function loadGitignoreSets(cwd) {
+    const gitignorePaths = await fg('**/.gitignore', { cwd, dot: true, absolute: true, onlyFiles: true, followSymbolicLinks: false });
+    const sets = [];
+    for (const filePath of gitignorePaths) {
+        try {
+            const raw = await fs.readFile(filePath, 'utf8');
+            const patterns = raw
+                .split('\n')
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0 && !line.startsWith('#'));
+            if (patterns.length > 0) {
+                sets.push({ dir: path.dirname(filePath), patterns });
+            }
+        }
+        catch {
+            // Ignore unreadable .gitignore files
+        }
+    }
+    // Ensure deterministic parent-before-child ordering
+    return sets.sort((a, b) => a.dir.localeCompare(b.dir));
+}
+function isGitignored(filePath, sets) {
+    for (const { dir, patterns } of sets) {
+        if (!filePath.startsWith(dir)) {
+            continue;
+        }
+        const relative = path.relative(dir, filePath) || path.basename(filePath);
+        if (matchesAny(relative, patterns)) {
+            return true;
+        }
+    }
+    return false;
+}
+async function buildIgnoredWhitelist(filePaths, cwd, fsModule) {
+    const whitelist = new Set();
+    for (const filePath of filePaths) {
+        const absolute = path.resolve(filePath);
+        const rel = path.relative(cwd, absolute);
+        const parts = rel.split(path.sep).filter(Boolean);
+        for (let i = 0; i < parts.length - 1; i += 1) {
+            const part = parts[i];
+            if (!DEFAULT_IGNORED_DIRS.includes(part)) {
+                continue;
+            }
+            const dirPath = path.resolve(cwd, ...parts.slice(0, i + 1));
+            if (whitelist.has(dirPath)) {
+                continue;
+            }
+            try {
+                const stats = await fsModule.stat(path.join(dirPath, '.gitignore'));
+                if (stats.isFile()) {
+                    whitelist.add(dirPath);
+                }
+            }
+            catch {
+                // no .gitignore at this level; keep ignored
+            }
+        }
+    }
+    return whitelist;
+}
+function findIgnoredAncestor(filePath, cwd, _literalDirs, allowedPaths, ignoredWhitelist) {
+    const absolute = path.resolve(filePath);
+    if (Array.from(allowedPaths).some((allowed) => absolute === allowed || absolute.startsWith(`${allowed}${path.sep}`))) {
+        return null; // explicitly requested path overrides default ignore when the ignored dir itself was passed
+    }
+    const rel = path.relative(cwd, absolute);
+    const parts = rel.split(path.sep);
+    for (let idx = 0; idx < parts.length; idx += 1) {
+        const part = parts[idx];
+        if (!DEFAULT_IGNORED_DIRS.includes(part)) {
+            continue;
+        }
+        const ignoredDir = path.resolve(cwd, parts.slice(0, idx + 1).join(path.sep));
+        if (ignoredWhitelist.has(ignoredDir)) {
+            continue;
+        }
+        return part;
+    }
+    return null;
+}
+function matchesAny(relativePath, patterns) {
+    return patterns.some((pattern) => matchesPattern(relativePath, pattern));
+}
+function matchesPattern(relativePath, pattern) {
+    if (!pattern) {
+        return false;
+    }
+    const normalized = pattern.replace(/\\+/g, '/');
+    // Directory rule
+    if (normalized.endsWith('/')) {
+        const dir = normalized.slice(0, -1);
+        return relativePath === dir || relativePath.startsWith(`${dir}/`);
+    }
+    // Simple glob support (* and **)
+    const regex = globToRegex(normalized);
+    return regex.test(relativePath);
+}
+function globToRegex(pattern) {
+    const withMarkers = pattern.replace(/\*\*/g, '§§DOUBLESTAR§§').replace(/\*/g, '§§SINGLESTAR§§');
+    const escaped = withMarkers.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    const restored = escaped
+        .replace(/§§DOUBLESTAR§§/g, '.*')
+        .replace(/§§SINGLESTAR§§/g, '[^/]*');
+    return new RegExp(`^${restored}$`);
+}
+function includesDotfileSegment(pattern) {
+    const segments = pattern.split('/');
+    return segments.some((segment) => segment.startsWith('.') && segment.length > 1);
 }
 async function expandWithCustomFs(partitioned, fsModule) {
     const paths = new Set();

package/dist/src/oracle/run.js

@@ -8,6 +8,7 @@ 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';
@@ -85,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);
@@ -112,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');
@@ -231,9 +228,27 @@ export async function runOracle(options, deps = {}) {
     }
     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) {
@@ -262,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');
     }
@@ -272,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,6 +218,7 @@ 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);
@@ -220,3 +236,32 @@ export async function getSessionPaths(sessionId) {
     }
     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>