@scira/cli 0.1.8 → 0.1.9

package/dist/utils/markdown-joiner.js

@@ -1,19 +1,12 @@
-// Regex patterns for markdown matching
 const LINK_PATTERN = /^\[.*?\]\(.*?\)$/;
 const BOLD_PATTERN = /^\*\*.*?\*\*$/;
-// Matches *text* but NOT **text** (negative lookahead ensures second char isn't *)
 const ITALIC_PATTERN = /^\*(?!\*).+\*$/;
 const TABLE_ROW_PATTERN = /^\|.+\|$/;
-// Matches markdown table delimiter rows like: | --- | ---: | :-: |
 const TABLE_DELIMITER_PATTERN = /^\|\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)*\|\s*$/;
 const WHITESPACE_PATTERN = /\s/;
-// Rich XML tags that must be passed through intact
 const RICH_TAGS = ['app_preview', 'download'];
-// Matches an opening rich tag e.g. <app_preview> or <download>
 const RICH_TAG_OPEN_RE = new RegExp(`<(${RICH_TAGS.join('|')})>`, 'i');
-// Inline buffer cap: flush as raw text if a markdown element doesn't close within this many chars
 const MAX_INLINE_BUFFER = 512;
-// Rich-tag buffer cap: safety valve for malformed/missing closing tags
 const MAX_RICH_TAG_BUFFER = 65536;
 class MarkdownJoiner {
     buffer = '';
@@ -27,10 +20,8 @@ class MarkdownJoiner {
     processText(text) {
         let output = '';
         for (const char of text) {
-            // Rich-tag passthrough mode: buffer everything until closing tag
             if (this.bufferMode === 'rich-tag') {
                 this.buffer += char;
-                // Safety cap: if the rich tag never closes, flush as raw text
                 if (this.buffer.length > MAX_RICH_TAG_BUFFER) {
                     output += this.buffer;
                     this.richTagName = null;
@@ -58,42 +49,34 @@ class MarkdownJoiner {
             }
             else if (this.bufferMode === 'inline') {
                 this.buffer += char;
-                // Cap inline buffer to prevent quadratic regex cost on unbounded input
                 if (this.buffer.length > MAX_INLINE_BUFFER) {
                     output += this.buffer;
                     this.clearBuffer();
                     this.isAtLineStart = char === '\n';
                     continue;
                 }
-                // Check if buffer has grown into a rich tag opener
                 if (this.buffer.startsWith('<')) {
                     const match = RICH_TAG_OPEN_RE.exec(this.buffer);
                     if (match && this.buffer.endsWith('>')) {
-                        // Confirmed rich tag open — switch to rich-tag mode
                         this.richTagName = match[1];
                         this.bufferMode = 'rich-tag';
                         this.isAtLineStart = false;
                         continue;
                     }
-                    // Still potentially building a rich tag — keep buffering until > or mismatch
                     if (!this.isFalsePositiveTag(char)) {
                         this.isAtLineStart = char === '\n';
                         continue;
                     }
-                    // Not a rich tag — flush as raw text
                     output += this.buffer;
                     this.clearBuffer();
                     this.isAtLineStart = char === '\n';
                     continue;
                 }
-                // Check for complete markdown elements or false positives
                 if (this.isCompleteLink() || this.isCompleteBold() || this.isCompleteItalic()) {
-                    // Complete markdown element - flush buffer as is
                     output += this.buffer;
                     this.clearBuffer();
                 }
                 else if (this.isFalsePositive(char)) {
-                    // False positive - flush buffer as raw text
                     output += this.buffer;
                     this.clearBuffer();
                 }
@@ -105,7 +88,6 @@ class MarkdownJoiner {
                         if (char !== '|') {
                             output += this.pendingTableHeaderLine;
                             this.pendingTableHeaderLine = null;
-                            // fall through to handle this char normally
                         }
                         else {
                             this.tableLineMode = 'delimiter';
@@ -135,7 +117,6 @@ class MarkdownJoiner {
                     this.isAtLineStart = false;
                     continue;
                 }
-                // Pass through character directly
                 output += char;
                 this.isAtLineStart = char === '\n';
             }
@@ -150,7 +131,6 @@ class MarkdownJoiner {
         this.tableLineMode = null;
         if (mode === 'header') {
             if (this.isTableHeaderCandidate(line)) {
-                // Hold header line until we see whether next line is a delimiter row
                 this.pendingTableHeaderLine = lineWithNewline;
                 return '';
             }
@@ -169,19 +149,15 @@ class MarkdownJoiner {
         return TABLE_ROW_PATTERN.test(line) && !TABLE_DELIMITER_PATTERN.test(line);
     }
     isCompleteLink() {
-        // Match [text](url) pattern
         return LINK_PATTERN.test(this.buffer);
     }
     isCompleteBold() {
-        // Match **text** pattern
         return BOLD_PATTERN.test(this.buffer);
     }
     isCompleteItalic() {
-        // Match *text* pattern (but not **text**)
         return ITALIC_PATTERN.test(this.buffer);
     }
     isFalsePositiveTag(char) {
-        // A < buffer is a false positive if we hit newline, another <, or > without matching a rich tag
         if (char === '\n' || (char === '<' && this.buffer.length > 1))
             return true;
         if (char === '>' && !RICH_TAG_OPEN_RE.test(this.buffer))
@@ -189,19 +165,13 @@ class MarkdownJoiner {
         return false;
     }
     isFalsePositive(char) {
-        // For links: if we see [ followed by something other than valid link syntax
         if (this.buffer.startsWith('[')) {
-            // If we hit a newline or another [ without completing the link, it's false positive
             return char === '\n' || (char === '[' && this.buffer.length > 1);
         }
-        // For emphasis: if we see * or ** followed by whitespace or newline
         if (this.buffer.startsWith('*')) {
-            // Single * followed by whitespace is likely a list item or not emphasis
-            // (buffer already includes char, so length 2 means just "*" + the whitespace char)
             if (this.buffer.length === 2 && WHITESPACE_PATTERN.test(char)) {
                 return true;
             }
-            // If we hit newline without completing emphasis, it's false positive
             return char === '\n';
         }
         return false;

package/dist/utils/process.js

@@ -0,0 +1,12 @@
+/** True if a process with this pid is currently running. Signal 0 is an existence check — it never kills. */
+export function isProcessRunning(pid) {
+    if (pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/time.js

@@ -0,0 +1,21 @@
+/** Compact relative time, e.g. "now", "5m ago", "3h ago", "2d ago", "3w ago". */
+export function relativeTime(ms) {
+    if (!ms)
+        return "";
+    const diff = Date.now() - ms;
+    if (diff < 60_000)
+        return "now";
+    const mins = Math.floor(diff / 60_000);
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 7)
+        return `${days}d ago`;
+    const weeks = Math.floor(days / 7);
+    if (weeks < 5)
+        return `${weeks}w ago`;
+    return new Date(ms).toLocaleDateString();
+}

package/dist/utils/watch-notice.js

@@ -0,0 +1,40 @@
+import { peekUnreadResults, commitReadCursor } from "../watch/store.js";
+import { formatDiffCounts } from "../watch/format.js";
+import { relativeTime } from "./time.js";
+/**
+ * Unread background-watch results plus the cursor offset to commit once shown.
+ * Read-only — the cursor is committed separately (commitWatchNotices) only after
+ * the banner is actually printed, so a crash can't silently mark results read.
+ * Returns an empty set on any failure — this must never break the CLI.
+ */
+export async function checkWatchNotices() {
+    try {
+        return await peekUnreadResults();
+    }
+    catch {
+        return { results: [], nextOffset: 0 };
+    }
+}
+/** Mark results read up to `byteOffset` — call only after the banner has been shown. */
+export async function commitWatchNotices(byteOffset) {
+    try {
+        await commitReadCursor(byteOffset);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function briefDiff(r) {
+    return formatDiffCounts(r.added, r.removed) || "no changes";
+}
+/** Cyan banner summarizing unread background-watch results, shown after a CLI command. */
+export function formatWatchNotice(results) {
+    const lines = [`${results.length} watch result${results.length > 1 ? "s" : ""} ready:`];
+    for (const r of results) {
+        lines.push(r.status === "ok"
+            ? `  • ${r.watchName} — ran ${relativeTime(new Date(r.ranAt).getTime())}, ${briefDiff(r)}`
+            : `  • ${r.watchName} — failed: ${r.errorMessage ?? "unknown error"}`);
+    }
+    lines.push(`Run "scira watch list" to view scheduled watches`);
+    return lines.join("\n");
+}

package/dist/watch/daemon-lock.js

@@ -0,0 +1,13 @@
+import { join } from "node:path";
+import { WATCH_DIR } from "./store.js";
+export { isProcessRunning } from "../utils/process.js";
+export const DAEMON_PID_FILE = join(WATCH_DIR, "daemon.pid.json");
+export const DAEMON_LOG_FILE = join(WATCH_DIR, "daemon.log");
+export async function readLock() {
+    try {
+        return (await Bun.file(DAEMON_PID_FILE).json());
+    }
+    catch {
+        return null;
+    }
+}

package/dist/watch/daemon.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env bun
+// Background scheduler. Spawned detached by `scira watch start`; ticks every
+// 60s, firing any scheduled watch that isDue(). A PID lock prevents duplicate
+// daemons. Paths and lock helpers are shared with the start/stop/status
+// commands via ./daemon-lock.js.
+import { appendFile, mkdir, rm } from "node:fs/promises";
+import { loadWatches, markWatchesRan, WATCH_DIR } from "./store.js";
+import { isDue } from "./scheduler.js";
+import { executeWatch } from "./executor.js";
+import { DAEMON_LOG_FILE, DAEMON_PID_FILE, isProcessRunning, readLock } from "./daemon-lock.js";
+const TICK_MS = 60_000;
+async function log(msg) {
+    await appendFile(DAEMON_LOG_FILE, `[${new Date().toISOString()}] ${msg}\n`).catch(() => { });
+}
+async function runTick() {
+    // Reload each tick so watches added/removed while running take effect.
+    const watches = await loadWatches();
+    const now = new Date();
+    const due = watches.filter((w) => w.enabled && isDue(w, now));
+    if (due.length === 0)
+        return;
+    // Stamp every due watch in a single write BEFORE firing any. This makes the
+    // tick the sole writer of lastRunAt, so the next tick (or a still-in-flight
+    // run) sees them as already-run and won't double-fire — no read-modify-write
+    // race between the concurrent fire-and-forget executions below.
+    await markWatchesRan(due.map((w) => w.id), now.toISOString());
+    for (const watch of due) {
+        void log(`starting watch "${watch.name}" (${watch.id})`);
+        // Fire-and-forget: a long research run shouldn't block other due watches.
+        void executeWatch(watch)
+            .then((r) => log(`completed watch "${watch.name}" (${r.status})`))
+            .catch((err) => log(`watch "${watch.name}" failed: ${err instanceof Error ? err.message : String(err)}`));
+    }
+}
+async function main() {
+    // Refuse to start if a live daemon already holds the lock.
+    const existing = await readLock();
+    if (existing && isProcessRunning(existing.pid)) {
+        process.stderr.write(`Daemon already running (pid ${existing.pid})\n`);
+        process.exit(1);
+    }
+    await mkdir(WATCH_DIR, { recursive: true });
+    await Bun.write(DAEMON_PID_FILE, JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }));
+    const cleanup = () => {
+        rm(DAEMON_PID_FILE, { force: true }).catch(() => { });
+        process.exit(0);
+    };
+    process.on("SIGTERM", cleanup);
+    process.on("SIGINT", cleanup);
+    await log(`started (pid ${process.pid})`);
+    await runTick(); // run an initial tick immediately, then on the interval
+    setInterval(() => {
+        void runTick().catch((e) => log(`tick error: ${e instanceof Error ? e.message : String(e)}`));
+    }, TICK_MS);
+}
+main().catch((err) => {
+    process.stderr.write(`[daemon] fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/watch/executor.js

@@ -0,0 +1,43 @@
+import { loadSciraEnv } from "../config/env-store.js";
+import { loadConfig } from "../config/load-config.js";
+import { runOnceAndDiff } from "./runner.js";
+import { appendResult } from "./store.js";
+import { formatDiffCounts } from "./format.js";
+import { tryDesktopNotify } from "../utils/desktop-notify.js";
+function resultId(watchId, ranAt) {
+    return `result_${watchId}_${ranAt.replace(/[:.]/gu, "-")}`;
+}
+function notifyBody(added, removed) {
+    const counts = formatDiffCounts(added, removed);
+    return counts ? `Research complete — ${counts}.` : "Research complete — no changes.";
+}
+/**
+ * Execute one scheduled watch: run a fresh research pass, diff against the prior
+ * report, record the result, and fire a desktop notification. Records an error
+ * result (never throws) so the daemon's tick loop and the unread-results banner
+ * stay consistent regardless of how the run went. The daemon stamps lastRunAt
+ * before calling this, so we don't touch it here.
+ */
+export async function executeWatch(watch) {
+    // The detached daemon doesn't run the CLI bootstrap, so load this watch's
+    // project-scoped API keys (~/.scira/.env + <projectRoot>/.scira/.env) before
+    // resolving config — otherwise a watch for a project other than the daemon's
+    // launch dir would run without its keys.
+    loadSciraEnv(watch.projectRoot);
+    const config = await loadConfig(watch.projectRoot);
+    const ranAt = new Date().toISOString();
+    const base = { id: resultId(watch.id, ranAt), watchId: watch.id, watchName: watch.name, goal: watch.goal, ranAt };
+    let result;
+    try {
+        const { runPath, diff } = await runOnceAndDiff(watch.goal, config, watch.projectRoot);
+        result = { ...base, runPath, added: diff.added.length, removed: diff.removed.length, status: "ok" };
+    }
+    catch (err) {
+        result = { ...base, runPath: "", added: 0, removed: 0, status: "error", errorMessage: err instanceof Error ? err.message : String(err) };
+    }
+    await appendResult(result);
+    if (result.status === "ok") {
+        await tryDesktopNotify(`Scira: ${watch.name}`, notifyBody(result.added, result.removed));
+    }
+    return result;
+}

package/dist/watch/format.js

@@ -0,0 +1,9 @@
+/** "3 added, 1 removed" — or "" when nothing changed. Shared by the notifier and the CLI banner. */
+export function formatDiffCounts(added, removed) {
+    const parts = [];
+    if (added > 0)
+        parts.push(`${added} added`);
+    if (removed > 0)
+        parts.push(`${removed} removed`);
+    return parts.join(", ");
+}

package/dist/watch/runner.js

@@ -2,29 +2,54 @@ import { readFile } from "node:fs/promises";
 import { diffLines } from "diff";
 import { createRun, listRuns, getRunPaths } from "../storage/run-store.js";
 import { runResearchAgent } from "../agent/main-agent.js";
-/** Compare two report.md texts and return a human-readable diff summary. */
-export function diffReports(prev, next) {
+export function computeReportDiff(prev, next) {
     const changes = diffLines(prev, next);
     const added = changes.filter((c) => c.added).map((c) => c.value.trim()).filter(Boolean);
     const removed = changes.filter((c) => c.removed).map((c) => c.value.trim()).filter(Boolean);
-    if (added.length === 0 && removed.length === 0)
-        return "No changes detected.";
-    const lines = [];
-    if (added.length > 0) {
-        lines.push(`+++ ${added.length} added section(s):\n${added.map((a) => `  + ${a.slice(0, 120)}`).join("\n")}`);
+    let text;
+    if (added.length === 0 && removed.length === 0) {
+        text = "No changes detected.";
     }
-    if (removed.length > 0) {
-        lines.push(`--- ${removed.length} removed section(s):\n${removed.map((r) => `  - ${r.slice(0, 120)}`).join("\n")}`);
+    else {
+        const lines = [];
+        if (added.length > 0) {
+            lines.push(`+++ ${added.length} added section(s):\n${added.map((a) => `  + ${a.slice(0, 120)}`).join("\n")}`);
+        }
+        if (removed.length > 0) {
+            lines.push(`--- ${removed.length} removed section(s):\n${removed.map((r) => `  - ${r.slice(0, 120)}`).join("\n")}`);
+        }
+        text = lines.join("\n");
     }
-    return lines.join("\n");
+    return { added, removed, text };
+}
+/** Thrown when creating the run directory fails — a fatal, non-retryable error for the watch loop. */
+export class CreateRunError extends Error {
 }
 async function getLastReport(goal, config, projectRoot) {
     const runs = await listRuns(config, projectRoot);
-    const last = runs.find((r) => r.goal === goal || r.goal.includes(goal));
+    // Exact goal match only — a substring fallback could diff against an unrelated
+    // run whose goal merely contains this one (e.g. "AI" vs "AI safety").
+    const last = runs.find((r) => r.goal === goal);
     if (!last)
         return "";
     return readFile(getRunPaths(last.path).report, "utf8").catch(() => "");
 }
+/**
+ * Run a single research pass for `goal` and diff its report against the most
+ * recent prior run of the same goal. The shared primitive behind both watch
+ * modes — foreground (watchLoop) and background (the daemon's executor) — so
+ * neither reimplements create-run → run-agent → diff.
+ */
+export async function runOnceAndDiff(goal, config, projectRoot = process.cwd(), onRunStart) {
+    const prevReport = await getLastReport(goal, config, projectRoot);
+    const state = await createRun(goal, config, projectRoot).catch((err) => {
+        throw new CreateRunError(err instanceof Error ? err.message : String(err));
+    });
+    onRunStart?.(state.path);
+    await runResearchAgent(state.path, goal, config);
+    const nextReport = await Bun.file(getRunPaths(state.path).report).text().catch(() => "");
+    return { runPath: state.path, diff: computeReportDiff(prevReport, nextReport) };
+}
 /**
  * Run the watch loop. Resolves when maxRuns is reached or signal is aborted.
  */
@@ -34,25 +59,17 @@ export async function watchLoop(opts, signal) {
     while (!signal?.aborted) {
         if (maxRuns !== undefined && tick >= maxRuns)
             break;
-        const prevReport = await getLastReport(goal, config, projectRoot);
-        let runPath;
-        try {
-            const state = await createRun(goal, config, projectRoot);
-            runPath = state.path;
-        }
-        catch (err) {
-            opts.onError?.(err instanceof Error ? err : new Error(String(err)), tick);
-            break;
-        }
-        opts.onRunStart?.(runPath, tick);
         try {
-            await runResearchAgent(runPath, goal, config);
-            const nextReport = await Bun.file(getRunPaths(runPath).report).text().catch(() => "");
-            const diffText = diffReports(prevReport, nextReport);
-            opts.onRunComplete?.(runPath, diffText, tick);
+            const { runPath, diff } = await runOnceAndDiff(goal, config, projectRoot, (runPath) => opts.onRunStart?.(runPath, tick));
+            opts.onRunComplete?.(runPath, diff, tick);
         }
         catch (err) {
-            opts.onError?.(err instanceof Error ? err : new Error(String(err)), tick);
+            const error = err instanceof Error ? err : new Error(String(err));
+            opts.onError?.(error, tick);
+            // A failed run dir creation is fatal (disk full, bad permissions) — retrying
+            // every interval would spin forever. Agent/run failures are transient: continue.
+            if (error instanceof CreateRunError)
+                break;
         }
         tick++;
         if (maxRuns !== undefined && tick >= maxRuns)

package/dist/watch/scheduler.js

@@ -0,0 +1,58 @@
+// All scheduling is in local wall-clock time: "run at 09:00" means the user's
+// 09:00. Day-of-week is 0=Sun … 6=Sat.
+function startOfDay(d) {
+    const s = new Date(d);
+    s.setHours(0, 0, 0, 0);
+    return s;
+}
+function parseHHMM(atHHMM) {
+    const [h, m] = atHHMM.split(":").map(Number);
+    return { hours: h ?? 0, minutes: m ?? 0 };
+}
+function atTimeOn(day, atHHMM) {
+    const { hours, minutes } = parseHHMM(atHHMM);
+    const t = new Date(day);
+    t.setHours(hours, minutes, 0, 0);
+    return t;
+}
+// Weekly watches fire on the weekday they were created on.
+function weeklyDow(watch) {
+    return new Date(watch.createdAt).getDay();
+}
+function firesOn(watch, dow) {
+    switch (watch.frequency) {
+        case "day":
+            return true;
+        case "weekday":
+            return dow !== 0 && dow !== 6;
+        case "week":
+            return dow === weeklyDow(watch);
+    }
+}
+/**
+ * True when the watch should run at `now`: today is an eligible day, the trigger
+ * time has passed, and it hasn't already run today. The already-ran-today guard
+ * is what makes the daemon's 60s tick idempotent.
+ */
+export function isDue(watch, now) {
+    if (!firesOn(watch, now.getDay()))
+        return false;
+    const target = atTimeOn(now, watch.atHHMM);
+    if (now < target)
+        return false; // trigger time hasn't arrived yet today
+    if (watch.lastRunAt === null)
+        return true;
+    return new Date(watch.lastRunAt) < startOfDay(target);
+}
+/** The next wall-clock time this watch will fire, scanning up to two weeks out. */
+export function nextRunAt(watch, from) {
+    const cursor = new Date(from);
+    for (let i = 0; i < 14; i++) {
+        const candidate = atTimeOn(cursor, watch.atHHMM);
+        if (firesOn(watch, candidate.getDay()) && candidate > from)
+            return candidate;
+        cursor.setDate(cursor.getDate() + 1);
+        cursor.setHours(0, 0, 0, 0);
+    }
+    return atTimeOn(cursor, watch.atHHMM);
+}

package/dist/watch/store.js

@@ -0,0 +1,110 @@
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { SavedWatchSchema } from "../types/index.js";
+import { appendJsonl } from "../storage/jsonl.js";
+// Scheduled-watch state lives under ~/.scira/watch/, independent of any
+// project's run directory — the daemon must reach it without a cwd.
+export const WATCH_DIR = join(homedir(), ".scira", "watch");
+const WATCHES_FILE = join(WATCH_DIR, "watches.json");
+const RESULTS_FILE = join(WATCH_DIR, "results.jsonl");
+const CURSOR_FILE = join(WATCH_DIR, "read-cursor.json");
+// --- Scheduled watch definitions -----------------------------------------
+export async function loadWatches() {
+    try {
+        const raw = (await Bun.file(WATCHES_FILE).json());
+        // Drop entries that no longer match the schema rather than throwing — one
+        // corrupt watch shouldn't break the daemon or the CLI banner.
+        return raw.flatMap((w) => {
+            const parsed = SavedWatchSchema.safeParse(w);
+            return parsed.success ? [parsed.data] : [];
+        });
+    }
+    catch {
+        return [];
+    }
+}
+async function saveWatches(list) {
+    await mkdir(WATCH_DIR, { recursive: true });
+    await Bun.write(WATCHES_FILE, `${JSON.stringify(list, null, 2)}\n`);
+}
+export function nextWatchId(existing) {
+    const nums = existing
+        .map((w) => /^watch_(\d+)$/u.exec(w.id)?.[1])
+        .filter((n) => Boolean(n))
+        .map((n) => Number.parseInt(n, 10));
+    const next = nums.length > 0 ? Math.max(...nums) + 1 : 1;
+    return `watch_${String(next).padStart(3, "0")}`;
+}
+export async function addWatch(w) {
+    await saveWatches([...(await loadWatches()), w]);
+}
+export async function removeWatch(id) {
+    await saveWatches((await loadWatches()).filter((w) => w.id !== id));
+}
+export async function findWatch(idOrName) {
+    return (await loadWatches()).find((w) => w.id === idOrName || w.name === idOrName);
+}
+/**
+ * Stamp lastRunAt on several watches in a single read-modify-write. The daemon
+ * calls this once per tick for all due watches, so concurrent (fire-and-forget)
+ * executions can't race on watches.json and drop each other's stamps.
+ */
+export async function markWatchesRan(ids, ranAtIso) {
+    if (ids.length === 0)
+        return;
+    const set = new Set(ids);
+    const list = await loadWatches();
+    await saveWatches(list.map((w) => (set.has(w.id) ? { ...w, lastRunAt: ranAtIso } : w)));
+}
+// --- Execution results ---------------------------------------------------
+export async function appendResult(r) {
+    await appendJsonl(RESULTS_FILE, r);
+}
+/**
+ * Results appended since the user last saw them, plus the byte offset to commit
+ * once they've actually been shown. This is read-only — it does NOT advance the
+ * cursor — so a crash before display can't silently mark results read. The
+ * cursor is a byte offset into the append-only file, so we parse only the new
+ * tail rather than the whole history on every CLI invocation.
+ */
+export async function peekUnreadResults() {
+    let offset = 0;
+    try {
+        const raw = (await Bun.file(CURSOR_FILE).json());
+        offset = raw.byteOffset ?? 0;
+    }
+    catch {
+        /* no cursor yet — read from the start */
+    }
+    const file = Bun.file(RESULTS_FILE);
+    const size = file.size; // 0 when the file doesn't exist yet
+    if (size === 0)
+        return { results: [], nextOffset: 0 };
+    if (offset > size)
+        offset = 0; // file was truncated/rotated — re-read from start
+    let text = "";
+    try {
+        text = await file.slice(offset).text();
+    }
+    catch {
+        return { results: [], nextOffset: offset };
+    }
+    const results = [];
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            results.push(JSON.parse(line));
+        }
+        catch {
+            /* skip a partially-written trailing line */
+        }
+    }
+    return { results, nextOffset: size };
+}
+/** Advance the read cursor — call only after the results have actually been shown. */
+export async function commitReadCursor(byteOffset) {
+    await mkdir(WATCH_DIR, { recursive: true });
+    await Bun.write(CURSOR_FILE, JSON.stringify({ byteOffset }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scira/cli",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Scira — terminal-native AI research agent with grounded sources, verified claims, and local run storage.",
   "license": "MIT",
   "type": "module",