@steipete/oracle 1.0.7 → 1.1.0

package/dist/oracle/src/sessionManager.js

@@ -0,0 +1,205 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+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 DEFAULT_SLUG = 'session';
+const MAX_SLUG_WORDS = 5;
+const MIN_CUSTOM_SLUG_WORDS = 3;
+async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}
+export async function ensureSessionStorage() {
+    await ensureDir(SESSIONS_DIR);
+}
+function slugify(text, maxWords = MAX_SLUG_WORDS) {
+    const normalized = text?.toLowerCase() ?? '';
+    const words = normalized.match(/[a-z0-9]+/g) ?? [];
+    const trimmed = words.slice(0, maxWords);
+    return trimmed.length > 0 ? trimmed.join('-') : DEFAULT_SLUG;
+}
+function countSlugWords(slug) {
+    return slug.split('-').filter(Boolean).length;
+}
+function normalizeCustomSlug(candidate) {
+    const slug = slugify(candidate, MAX_SLUG_WORDS);
+    const wordCount = countSlugWords(slug);
+    if (wordCount < MIN_CUSTOM_SLUG_WORDS || wordCount > MAX_SLUG_WORDS) {
+        throw new Error(`Custom slug must include between ${MIN_CUSTOM_SLUG_WORDS} and ${MAX_SLUG_WORDS} words.`);
+    }
+    return slug;
+}
+export function createSessionId(prompt, customSlug) {
+    if (customSlug) {
+        return normalizeCustomSlug(customSlug);
+    }
+    return slugify(prompt);
+}
+function sessionDir(id) {
+    return path.join(SESSIONS_DIR, id);
+}
+function metaPath(id) {
+    return path.join(sessionDir(id), 'session.json');
+}
+function logPath(id) {
+    return path.join(sessionDir(id), 'output.log');
+}
+function requestPath(id) {
+    return path.join(sessionDir(id), 'request.json');
+}
+async function fileExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureUniqueSessionId(baseSlug) {
+    let candidate = baseSlug;
+    let suffix = 2;
+    while (await fileExists(sessionDir(candidate))) {
+        candidate = `${baseSlug}-${suffix}`;
+        suffix += 1;
+    }
+    return candidate;
+}
+export async function initializeSession(options, cwd) {
+    await ensureSessionStorage();
+    const baseSlug = createSessionId(options.prompt || DEFAULT_SLUG, options.slug);
+    const sessionId = await ensureUniqueSessionId(baseSlug);
+    const dir = sessionDir(sessionId);
+    await ensureDir(dir);
+    const mode = options.mode ?? 'api';
+    const browserConfig = options.browserConfig;
+    const metadata = {
+        id: sessionId,
+        createdAt: new Date().toISOString(),
+        status: 'pending',
+        promptPreview: (options.prompt || '').slice(0, 160),
+        model: options.model,
+        cwd,
+        mode,
+        browser: browserConfig ? { config: browserConfig } : undefined,
+        options: {
+            prompt: options.prompt,
+            file: options.file ?? [],
+            model: options.model,
+            maxInput: options.maxInput,
+            system: options.system,
+            maxOutput: options.maxOutput,
+            silent: options.silent,
+            filesReport: options.filesReport,
+            slug: sessionId,
+            mode,
+            browserConfig,
+            verbose: options.verbose,
+            heartbeatIntervalMs: options.heartbeatIntervalMs,
+            browserInlineFiles: options.browserInlineFiles,
+            background: options.background,
+        },
+    };
+    await fs.writeFile(metaPath(sessionId), JSON.stringify(metadata, null, 2), 'utf8');
+    await fs.writeFile(requestPath(sessionId), JSON.stringify(metadata.options, null, 2), 'utf8');
+    await fs.writeFile(logPath(sessionId), '', 'utf8');
+    return metadata;
+}
+export async function readSessionMetadata(sessionId) {
+    try {
+        const raw = await fs.readFile(metaPath(sessionId), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function updateSessionMetadata(sessionId, updates) {
+    const existing = (await readSessionMetadata(sessionId)) ?? { id: sessionId };
+    const next = { ...existing, ...updates };
+    await fs.writeFile(metaPath(sessionId), JSON.stringify(next, null, 2), 'utf8');
+    return next;
+}
+export function createSessionLogWriter(sessionId) {
+    const stream = createWriteStream(logPath(sessionId), { flags: 'a' });
+    const logLine = (line = '') => {
+        stream.write(`${line}\n`);
+    };
+    const writeChunk = (chunk) => {
+        stream.write(chunk);
+        return true;
+    };
+    return { stream, logLine, writeChunk, logPath: logPath(sessionId) };
+}
+export async function listSessionsMetadata() {
+    await ensureSessionStorage();
+    const entries = await fs.readdir(SESSIONS_DIR).catch(() => []);
+    const metas = [];
+    for (const entry of entries) {
+        const meta = await readSessionMetadata(entry);
+        if (meta) {
+            metas.push(meta);
+        }
+    }
+    return metas.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+}
+export function filterSessionsByRange(metas, { hours = 24, includeAll = false, limit = 100 }) {
+    const maxLimit = Math.min(limit, MAX_STATUS_LIMIT);
+    let filtered = metas;
+    if (!includeAll) {
+        const cutoff = Date.now() - hours * 60 * 60 * 1000;
+        filtered = metas.filter((meta) => new Date(meta.createdAt).getTime() >= cutoff);
+    }
+    const limited = filtered.slice(0, maxLimit);
+    const truncated = filtered.length > maxLimit;
+    return { entries: limited, truncated, total: filtered.length };
+}
+export async function readSessionLog(sessionId) {
+    try {
+        return await fs.readFile(logPath(sessionId), 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+export async function deleteSessionsOlderThan({ hours = 24, includeAll = false, } = {}) {
+    await ensureSessionStorage();
+    const entries = await fs.readdir(SESSIONS_DIR).catch(() => []);
+    if (!entries.length) {
+        return { deleted: 0, remaining: 0 };
+    }
+    const cutoff = includeAll ? Number.NEGATIVE_INFINITY : Date.now() - hours * 60 * 60 * 1000;
+    let deleted = 0;
+    for (const entry of entries) {
+        const dir = sessionDir(entry);
+        let createdMs;
+        const meta = await readSessionMetadata(entry);
+        if (meta?.createdAt) {
+            const parsed = Date.parse(meta.createdAt);
+            if (!Number.isNaN(parsed)) {
+                createdMs = parsed;
+            }
+        }
+        if (createdMs == null) {
+            try {
+                const stats = await fs.stat(dir);
+                createdMs = stats.birthtimeMs || stats.mtimeMs;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (includeAll || (createdMs != null && createdMs < cutoff)) {
+            await fs.rm(dir, { recursive: true, force: true });
+            deleted += 1;
+        }
+    }
+    const remaining = Math.max(entries.length - deleted, 0);
+    return { deleted, remaining };
+}
+export async function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export { ORACLE_HOME, SESSIONS_DIR, MAX_STATUS_LIMIT };

package/dist/oracle/src/version.js

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+let cachedVersion = null;
+export function getCliVersion() {
+    if (cachedVersion) {
+        return cachedVersion;
+    }
+    cachedVersion = readVersionFromPackage();
+    return cachedVersion;
+}
+function readVersionFromPackage() {
+    const modulePath = fileURLToPath(import.meta.url);
+    let currentDir = path.dirname(modulePath);
+    const filesystemRoot = path.parse(currentDir).root;
+    // biome-ignore lint/nursery/noUnnecessaryConditions: deliberate sentinel loop to walk up directories
+    while (true) {
+        const candidate = path.join(currentDir, 'package.json');
+        try {
+            const raw = readFileSync(candidate, 'utf8');
+            const parsed = JSON.parse(raw);
+            const version = typeof parsed.version === 'string' && parsed.version.trim().length > 0
+                ? parsed.version.trim()
+                : '0.0.0';
+            return version;
+        }
+        catch (error) {
+            const code = error instanceof Error && 'code' in error ? error.code : undefined;
+            if (code && code !== 'ENOENT') {
+                break;
+            }
+        }
+        if (currentDir === filesystemRoot) {
+            break;
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    return '0.0.0';
+}

package/dist/src/cli/help.js

@@ -45,6 +45,7 @@ function renderHelpFooter(program, colors) {
     const tips = [
         `${colors.bullet('•')} Attach lots of source (whole directories beat single files) and keep total input under ~196k tokens.`,
         `${colors.bullet('•')} Oracle starts empty—open with a short project briefing (stack, services, build steps), spell out the question and prior attempts, and why it matters; the more explanation and context you provide, the better the response will be.`,
+        `${colors.bullet('•')} Oracle is one-shot: it does not remember prior runs, so start fresh each time with full context.`,
         `${colors.bullet('•')} Run ${colors.accent('--files-report')} to inspect token spend before hitting the API.`,
         `${colors.bullet('•')} Non-preview runs spawn detached sessions so they keep streaming even if your terminal closes — reattach anytime via ${colors.accent('pnpm oracle session <slug>')}.`,
         `${colors.bullet('•')} Set a memorable 3–5 word slug via ${colors.accent('--slug "<words>"')} to keep session IDs tidy.`,

package/dist/src/cli/markdownRenderer.js

@@ -0,0 +1,18 @@
+import { render as renderMarkdown } from 'markdansi';
+export function renderMarkdownAnsi(markdown) {
+    try {
+        const color = Boolean(process.stdout.isTTY);
+        const width = process.stdout.columns;
+        const hyperlinks = color; // enable OSC 8 only when we have color/TTY
+        return renderMarkdown(markdown, {
+            color,
+            width,
+            wrap: true,
+            hyperlinks,
+        });
+    }
+    catch {
+        // Last-resort fallback: return the raw markdown so we never crash.
+        return markdown;
+    }
+}

package/dist/src/cli/rootAlias.js

@@ -14,3 +14,17 @@ export async function handleStatusFlag(options, deps = defaultDeps) {
     await deps.showStatus({ hours: 24, includeAll: false, limit: 100, showExamples: true });
     return true;
 }
+const defaultSessionDeps = {
+    attachSession,
+};
+/**
+ * Hidden root-level alias to attach to a stored session (`--session <id>`).
+ * Returns true when the alias was handled so callers can short-circuit.
+ */
+export async function handleSessionAlias(options, deps = defaultSessionDeps) {
+    if (!options.session) {
+        return false;
+    }
+    await deps.attachSession(options.session);
+    return true;
+}

package/dist/src/cli/sessionCommand.js

@@ -1,14 +1,25 @@
+import chalk from 'chalk';
 import { usesDefaultStatusFilters } from './options.js';
 import { attachSession, showStatus } from './sessionDisplay.js';
-import { deleteSessionsOlderThan } from '../sessionManager.js';
+import { deleteSessionsOlderThan, getSessionPaths } from '../sessionManager.js';
 const defaultDependencies = {
     showStatus,
     attachSession,
     usesDefaultStatusFilters,
     deleteSessionsOlderThan,
+    getSessionPaths,
 };
+const SESSION_OPTION_KEYS = new Set(['hours', 'limit', 'all', 'clear', 'clean', 'render', 'renderMarkdown', 'path']);
 export async function handleSessionCommand(sessionId, command, deps = defaultDependencies) {
     const sessionOptions = command.opts();
+    if (sessionOptions.verboseRender) {
+        process.env.ORACLE_VERBOSE_RENDER = '1';
+    }
+    const renderSource = command.getOptionValueSource?.('render');
+    const renderMarkdownSource = command.getOptionValueSource?.('renderMarkdown');
+    const renderExplicit = renderSource === 'cli' || renderMarkdownSource === 'cli';
+    const autoRender = !renderExplicit && process.stdout.isTTY;
+    const pathRequested = Boolean(sessionOptions.path);
     const clearRequested = Boolean(sessionOptions.clear || sessionOptions.clean);
     if (clearRequested) {
         if (sessionId) {
@@ -28,6 +39,28 @@ export async function handleSessionCommand(sessionId, command, deps = defaultDep
         process.exitCode = 1;
         return;
     }
+    if (pathRequested) {
+        if (!sessionId) {
+            console.error('The --path flag requires a session ID.');
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const paths = await deps.getSessionPaths(sessionId);
+            const richTty = Boolean(process.stdout.isTTY && chalk.level > 0);
+            const label = (text) => (richTty ? chalk.cyan(text) : text);
+            const value = (text) => (richTty ? chalk.dim(text) : text);
+            console.log(`${label('Session dir:')} ${value(paths.dir)}`);
+            console.log(`${label('Metadata:')} ${value(paths.metadata)}`);
+            console.log(`${label('Request:')} ${value(paths.request)}`);
+            console.log(`${label('Log:')} ${value(paths.log)}`);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exitCode = 1;
+        }
+        return;
+    }
     if (!sessionId) {
         const showExamples = deps.usesDefaultStatusFilters(command);
         await deps.showStatus({
@@ -38,7 +71,13 @@ export async function handleSessionCommand(sessionId, command, deps = defaultDep
         });
         return;
     }
-    await deps.attachSession(sessionId);
+    // Surface any root-level flags that were provided but are ignored when attaching to a session.
+    const ignoredFlags = listIgnoredFlags(command);
+    if (ignoredFlags.length > 0) {
+        console.log(`Ignoring flags on session attach: ${ignoredFlags.join(', ')}`);
+    }
+    const renderMarkdown = Boolean(sessionOptions.render || sessionOptions.renderMarkdown || autoRender);
+    await deps.attachSession(sessionId, { renderMarkdown });
 }
 export function formatSessionCleanupMessage(result, scope) {
     const deletedLabel = `${result.deleted} ${result.deleted === 1 ? 'session' : 'sessions'}`;
@@ -46,3 +85,22 @@ export function formatSessionCleanupMessage(result, scope) {
     const hint = 'Run "oracle session --clear --all" to delete everything.';
     return `Deleted ${deletedLabel} (${scope}). ${remainingLabel}.\n${hint}`;
 }
+function listIgnoredFlags(command) {
+    const opts = command.optsWithGlobals();
+    const ignored = [];
+    for (const key of Object.keys(opts)) {
+        if (SESSION_OPTION_KEYS.has(key)) {
+            continue;
+        }
+        const source = command.getOptionValueSource?.(key);
+        if (source !== 'cli' && source !== 'env') {
+            continue;
+        }
+        const value = opts[key];
+        if (value === undefined || value === false || value === null) {
+            continue;
+        }
+        ignored.push(key);
+    }
+    return ignored;
+}

package/dist/src/cli/sessionDisplay.js

@@ -1,8 +1,10 @@
 import chalk from 'chalk';
 import kleur from 'kleur';
 import { filterSessionsByRange, listSessionsMetadata, readSessionLog, readSessionMetadata, SESSIONS_DIR, wait, } from '../sessionManager.js';
-const isTty = process.stdout.isTTY;
-const dim = (text) => (isTty ? kleur.dim(text) : text);
+import { renderMarkdownAnsi } from './markdownRenderer.js';
+const isTty = () => Boolean(process.stdout.isTTY);
+const dim = (text) => (isTty() ? kleur.dim(text) : text);
+const MAX_RENDER_BYTES = 200_000;
 const CLEANUP_TIP = 'Tip: Run "oracle session --clear --hours 24" to prune cached runs (add --all to wipe everything).';
 export async function showStatus({ hours, includeAll, limit, showExamples = false }) {
     const metas = await listSessionsMetadata();
@@ -50,6 +52,8 @@ export async function attachSession(sessionId, options) {
         return;
     }
     const initialStatus = metadata.status;
+    const wantsRender = Boolean(options?.renderMarkdown);
+    const isVerbose = Boolean(process.env.ORACLE_VERBOSE_RENDER);
     if (!options?.suppressMetadata) {
         const reattachLine = buildReattachLine(metadata);
         if (reattachLine) {
@@ -75,15 +79,96 @@ export async function attachSession(sessionId, options) {
     if (shouldTrimIntro) {
         const fullLog = await readSessionLog(sessionId);
         const trimmed = trimBeforeFirstAnswer(fullLog);
-        process.stdout.write(trimmed);
+        const size = Buffer.byteLength(trimmed, 'utf8');
+        const canRender = wantsRender && isTty() && size <= MAX_RENDER_BYTES;
+        if (wantsRender && size > MAX_RENDER_BYTES) {
+            const msg = `Render skipped (log too large: ${size} bytes > ${MAX_RENDER_BYTES}). Showing raw text.`;
+            console.log(dim(msg));
+            if (isVerbose) {
+                console.log(dim(`Verbose: renderMarkdown=true tty=${isTty()} size=${size}`));
+            }
+        }
+        else if (wantsRender && !isTty()) {
+            const msg = 'Render requested but stdout is not a TTY; showing raw text.';
+            console.log(dim(msg));
+            if (isVerbose) {
+                console.log(dim(`Verbose: renderMarkdown=true tty=${isTty()} size=${size}`));
+            }
+        }
+        if (canRender) {
+            if (isVerbose) {
+                console.log(dim(`Verbose: rendering markdown (size=${size}, tty=${isTty()})`));
+            }
+            process.stdout.write(renderMarkdownAnsi(trimmed));
+        }
+        else {
+            process.stdout.write(trimmed);
+        }
         return;
     }
+    if (wantsRender) {
+        console.log(dim('Render will apply after completion; streaming raw text meanwhile...'));
+        if (isVerbose) {
+            console.log(dim(`Verbose: streaming phase renderMarkdown=true tty=${isTty()}`));
+        }
+    }
+    const liveRenderState = wantsRender && isTty()
+        ? { pending: '', inFence: false, inTable: false, renderedBytes: 0, fallback: false, noticedFallback: false }
+        : null;
     let lastLength = 0;
+    const renderLiveChunk = (chunk) => {
+        if (!liveRenderState || chunk.length === 0) {
+            process.stdout.write(chunk);
+            return;
+        }
+        if (liveRenderState.fallback) {
+            process.stdout.write(chunk);
+            return;
+        }
+        liveRenderState.pending += chunk;
+        const { chunks, remainder } = extractRenderableChunks(liveRenderState.pending, liveRenderState);
+        liveRenderState.pending = remainder;
+        for (const candidate of chunks) {
+            const projected = liveRenderState.renderedBytes + Buffer.byteLength(candidate, 'utf8');
+            if (projected > MAX_RENDER_BYTES) {
+                if (!liveRenderState.noticedFallback) {
+                    console.log(dim(`Render skipped (log too large: > ${MAX_RENDER_BYTES} bytes). Showing raw text.`));
+                    liveRenderState.noticedFallback = true;
+                }
+                liveRenderState.fallback = true;
+                process.stdout.write(candidate + liveRenderState.pending);
+                liveRenderState.pending = '';
+                return;
+            }
+            process.stdout.write(renderMarkdownAnsi(candidate));
+            liveRenderState.renderedBytes += Buffer.byteLength(candidate, 'utf8');
+        }
+    };
+    const flushRemainder = () => {
+        if (!liveRenderState || liveRenderState.fallback) {
+            return;
+        }
+        if (liveRenderState.pending.length === 0) {
+            return;
+        }
+        const text = liveRenderState.pending;
+        liveRenderState.pending = '';
+        const projected = liveRenderState.renderedBytes + Buffer.byteLength(text, 'utf8');
+        if (projected > MAX_RENDER_BYTES) {
+            if (!liveRenderState.noticedFallback) {
+                console.log(dim(`Render skipped (log too large: > ${MAX_RENDER_BYTES} bytes). Showing raw text.`));
+            }
+            process.stdout.write(text);
+            liveRenderState.fallback = true;
+            return;
+        }
+        process.stdout.write(renderMarkdownAnsi(text));
+    };
     const printNew = async () => {
         const text = await readSessionLog(sessionId);
         const nextChunk = text.slice(lastLength);
         if (nextChunk.length > 0) {
-            process.stdout.write(nextChunk);
+            renderLiveChunk(nextChunk);
             lastLength = text.length;
         }
     };
@@ -96,6 +181,7 @@ export async function attachSession(sessionId, options) {
         }
         if (latest.status === 'completed' || latest.status === 'error') {
             await printNew();
+            flushRemainder();
             if (!options?.suppressMetadata) {
                 if (latest.status === 'error' && latest.errorMessage) {
                     console.log('\nResult:');
@@ -234,3 +320,42 @@ function printStatusExamples() {
     console.log(dim('    Attach to a specific running/completed session to stream its output.'));
     console.log(dim(CLEANUP_TIP));
 }
+function extractRenderableChunks(text, state) {
+    const chunks = [];
+    let buffer = '';
+    const lines = text.split(/(\n)/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const segment = lines[i];
+        if (segment === '\n') {
+            buffer += segment;
+            // Detect code fences
+            const prev = lines[i - 1] ?? '';
+            const fenceMatch = prev.match(/^(\s*)(`{3,}|~{3,})(.*)$/);
+            if (!state.inFence && fenceMatch) {
+                state.inFence = true;
+                state.fenceDelimiter = fenceMatch[2];
+            }
+            else if (state.inFence && state.fenceDelimiter && prev.startsWith(state.fenceDelimiter)) {
+                state.inFence = false;
+                state.fenceDelimiter = undefined;
+            }
+            const trimmed = prev.trim();
+            if (!state.inFence) {
+                if (!state.inTable && trimmed.startsWith('|') && trimmed.includes('|')) {
+                    state.inTable = true;
+                }
+                if (state.inTable && trimmed === '') {
+                    state.inTable = false;
+                }
+            }
+            const safeBreak = !state.inFence && !state.inTable && trimmed === '';
+            if (safeBreak) {
+                chunks.push(buffer);
+                buffer = '';
+            }
+            continue;
+        }
+        buffer += segment;
+    }
+    return { chunks, remainder: buffer };
+}

package/dist/src/oracle/oscProgress.js

@@ -0,0 +1,60 @@
+import process from 'node:process';
+const OSC = '\u001b]9;4;';
+const ST = '\u001b\\';
+function sanitizeLabel(label) {
+    const withoutEscape = label.split('\u001b').join('');
+    const withoutBellAndSt = withoutEscape.replaceAll('\u0007', '').replaceAll('\u009c', '');
+    return withoutBellAndSt.replaceAll(']', '').trim();
+}
+export function supportsOscProgress(env = process.env, isTty = process.stdout.isTTY) {
+    if (!isTty) {
+        return false;
+    }
+    if (env.ORACLE_NO_OSC_PROGRESS === '1') {
+        return false;
+    }
+    if (env.ORACLE_FORCE_OSC_PROGRESS === '1') {
+        return true;
+    }
+    const termProgram = (env.TERM_PROGRAM ?? '').toLowerCase();
+    if (termProgram.includes('ghostty')) {
+        return true;
+    }
+    if (termProgram.includes('wezterm')) {
+        return true;
+    }
+    if (env.WT_SESSION) {
+        return true; // Windows Terminal exposes this
+    }
+    return false;
+}
+export function startOscProgress(options = {}) {
+    const { label = 'Waiting for OpenAI', targetMs = 10 * 60_000, write = (text) => process.stdout.write(text) } = options;
+    if (!supportsOscProgress(options.env, options.isTty)) {
+        return () => { };
+    }
+    const cleanLabel = sanitizeLabel(label);
+    const target = Math.max(targetMs, 1_000);
+    const send = (state, percent) => {
+        const clamped = Math.max(0, Math.min(100, Math.round(percent)));
+        write(`${OSC}${state};${clamped};${cleanLabel}${ST}`);
+    };
+    const startedAt = Date.now();
+    send(1, 0); // activate progress bar
+    const timer = setInterval(() => {
+        const elapsed = Date.now() - startedAt;
+        const percent = Math.min(99, (elapsed / target) * 100);
+        send(1, percent);
+    }, 900);
+    timer.unref?.();
+    let stopped = false;
+    return () => {
+        // biome-ignore lint/nursery/noUnnecessaryConditions: multiple callers may try to stop
+        if (stopped) {
+            return;
+        }
+        stopped = true;
+        clearInterval(timer);
+        send(0, 0); // clear the progress bar
+    };
+}