@kinqs/brainrouter-cli 0.3.7 → 0.3.8

package/dist/runtime/anthropicAdapter.js

@@ -0,0 +1,293 @@
+// 0.3.8-I6: Native Anthropic `/v1/messages` adapter.
+//
+// BrainRouter's agent loop keeps chat history in OpenAI's shape
+// (`{role:'system'|'user'|'assistant'|'tool', content, tool_calls?,
+// tool_call_id?, name?}`) because that's the schema every other vendor
+// in the catalog already speaks. This module is the ONE place that hides
+// Anthropic's asymmetric shape from the rest of the codebase:
+//
+//   - `system` is a top-level field, not a `messages[]` entry.
+//   - Tool results come back as `tool_result` blocks WRAPPED in a `user`
+//     message — there is no `tool` role.
+//   - Multiple pending tool_results must collapse into one user turn
+//     with a content array, not one user message per result.
+//   - `tool_use` ids are vendor-assigned and must round-trip verbatim.
+//   - `max_tokens` is REQUIRED (OpenAI treats it as optional).
+//   - Prompt caching breakpoints and extended thinking are first-class
+//     request fields, not headers.
+//
+// Streaming is out of scope for this PR — the agent loop still polls
+// non-streaming responses.
+import { acquireLLMSlot } from './llmSemaphore.js';
+const ANTHROPIC_API_VERSION = '2023-06-01';
+/**
+ * Route to the native adapter when the profile is Anthropic AND the
+ * endpoint hostname is `api.anthropic.com`, OR the explicit
+ * `BRAINROUTER_ANTHROPIC_NATIVE=1` override is set (for vended /
+ * reverse-proxied endpoints that still speak the native shape).
+ *
+ * Anything else — including `provider:'anthropic'` pointed at an
+ * OpenAI-compat gateway — stays on the existing OpenAI path so we
+ * don't break the OpenRouter / Anthropic-compat-shim flows.
+ */
+export function shouldUseAnthropicNative(config, env = process.env) {
+    if (config.provider !== 'anthropic')
+        return false;
+    if (env.BRAINROUTER_ANTHROPIC_NATIVE === '1')
+        return true;
+    const endpoint = config.endpoint ?? 'https://api.anthropic.com/v1';
+    try {
+        const host = new URL(endpoint).hostname.toLowerCase();
+        return host === 'api.anthropic.com' || host.endsWith('.anthropic.com');
+    }
+    catch {
+        return false;
+    }
+}
+function modelDefaultMaxTokens(model) {
+    const m = model.toLowerCase();
+    if (m.includes('haiku'))
+        return 2048;
+    return 4096;
+}
+function supportsExtendedThinking(model) {
+    // Sonnet 4.x / Opus 4.x families. Strip any vendor prefix.
+    const m = model.toLowerCase().split('/').pop() ?? '';
+    return /claude-(?:[a-z0-9.-]*-)?(sonnet|opus)-4/.test(m);
+}
+/**
+ * Pure transform: BrainRouter chat history (OpenAI shape) →
+ * Anthropic `/v1/messages` request body.
+ *
+ * Invariants enforced here so callers don't need to know the Anthropic
+ * rules:
+ *   - The system message (first message with role:'system') is hoisted
+ *     to the top-level `system` field and dropped from `messages`.
+ *   - Consecutive `tool` role entries are merged into one synthetic
+ *     `user` message whose content is an array of `tool_result` blocks.
+ *   - Assistant messages with `tool_calls` emit a content array that
+ *     interleaves text (when present) and `tool_use` blocks. The
+ *     OpenAI tool_call.id is reused as the Anthropic tool_use.id —
+ *     callers must echo it back on the matching tool_result.
+ */
+export function buildAnthropicRequest(config, messages, tools, options = {}) {
+    let systemText;
+    const out = [];
+    let pendingToolResults = null;
+    const flushToolResults = () => {
+        if (pendingToolResults && pendingToolResults.length > 0) {
+            out.push({ role: 'user', content: pendingToolResults });
+        }
+        pendingToolResults = null;
+    };
+    for (const m of messages) {
+        if (m.role === 'system') {
+            // First system message wins; later ones are concatenated so
+            // tagged system prompts (replaceTaggedSystemMessage) still flow.
+            const text = typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+            systemText = systemText ? `${systemText}\n\n${text}` : text;
+            continue;
+        }
+        if (m.role === 'tool') {
+            const block = {
+                type: 'tool_result',
+                tool_use_id: m.tool_call_id,
+                content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
+            };
+            if (!pendingToolResults)
+                pendingToolResults = [];
+            pendingToolResults.push(block);
+            continue;
+        }
+        flushToolResults();
+        if (m.role === 'assistant') {
+            const blocks = [];
+            const text = typeof m.content === 'string' ? m.content : '';
+            if (text)
+                blocks.push({ type: 'text', text });
+            if (Array.isArray(m.tool_calls)) {
+                for (const tc of m.tool_calls) {
+                    let input = {};
+                    const raw = tc?.function?.arguments;
+                    if (typeof raw === 'string' && raw.trim()) {
+                        try {
+                            input = JSON.parse(raw);
+                        }
+                        catch {
+                            input = { _raw: raw };
+                        }
+                    }
+                    else if (raw && typeof raw === 'object') {
+                        input = raw;
+                    }
+                    blocks.push({
+                        type: 'tool_use',
+                        id: tc.id,
+                        name: tc.function?.name,
+                        input,
+                    });
+                }
+            }
+            // An assistant turn with NO content + no tool_calls is dropped —
+            // Anthropic rejects empty assistant turns.
+            if (blocks.length > 0)
+                out.push({ role: 'assistant', content: blocks });
+            continue;
+        }
+        // user
+        const userText = typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+        out.push({ role: 'user', content: [{ type: 'text', text: userText }] });
+    }
+    flushToolResults();
+    const body = {
+        model: config.model,
+        max_tokens: options.maxTokens ?? modelDefaultMaxTokens(config.model),
+        messages: out,
+    };
+    if (systemText) {
+        if (options.cacheEnabled) {
+            body.system = [{ type: 'text', text: systemText, cache_control: { type: 'ephemeral' } }];
+        }
+        else {
+            body.system = systemText;
+        }
+    }
+    if (tools.length > 0) {
+        body.tools = tools.map((t) => ({
+            name: t.name,
+            description: t.description || '',
+            input_schema: t.inputSchema || { type: 'object', properties: {} },
+        }));
+    }
+    // Cache breakpoint on the last assistant message (its last block) so
+    // every subsequent turn reads the prior context from cache.
+    if (options.cacheEnabled) {
+        for (let i = body.messages.length - 1; i >= 0; i--) {
+            const msg = body.messages[i];
+            if (msg.role === 'assistant' && Array.isArray(msg.content) && msg.content.length > 0) {
+                const last = msg.content[msg.content.length - 1];
+                last.cache_control = { type: 'ephemeral' };
+                break;
+            }
+        }
+    }
+    if (options.effort === 'high' &&
+        supportsExtendedThinking(config.model)) {
+        body.thinking = {
+            type: 'enabled',
+            budget_tokens: options.thinkingBudgetTokens ?? 8000,
+        };
+    }
+    return body;
+}
+/**
+ * Pure transform: Anthropic response body → BrainRouter's internal
+ * `ChatResponse` shape. tool_use blocks become OpenAI-style toolCalls
+ * with the Anthropic id preserved verbatim, and `input` is re-serialized
+ * to the `function.arguments` JSON string the agent loop expects.
+ */
+export function parseAnthropicResponse(data) {
+    if (!data || typeof data !== 'object') {
+        throw new Error(`Anthropic response was not a JSON object: ${JSON.stringify(data).slice(0, 400)}`);
+    }
+    if (data.type === 'error' || data.error) {
+        const err = data.error ?? data;
+        const msg = typeof err === 'string' ? err : (err.message ?? JSON.stringify(err));
+        throw new Error(`Anthropic API error: ${msg}`);
+    }
+    const blocks = Array.isArray(data.content) ? data.content : [];
+    const textParts = [];
+    const thinkingParts = [];
+    const toolCalls = [];
+    for (const b of blocks) {
+        if (!b || typeof b !== 'object')
+            continue;
+        if (b.type === 'text' && typeof b.text === 'string') {
+            textParts.push(b.text);
+        }
+        else if (b.type === 'thinking' && typeof b.thinking === 'string') {
+            thinkingParts.push(b.thinking);
+        }
+        else if (b.type === 'tool_use') {
+            toolCalls.push({
+                id: b.id,
+                type: 'function',
+                function: {
+                    name: b.name,
+                    arguments: JSON.stringify(b.input ?? {}),
+                },
+            });
+        }
+    }
+    const usage = data.usage
+        ? {
+            prompt_tokens: data.usage.input_tokens,
+            completion_tokens: data.usage.output_tokens,
+        }
+        : undefined;
+    const result = {
+        content: textParts.join(''),
+        usage,
+    };
+    if (toolCalls.length > 0)
+        result.toolCalls = toolCalls;
+    if (thinkingParts.length > 0)
+        result.thinking = thinkingParts.join('');
+    return result;
+}
+export async function callAnthropic(config, messages, tools, options = {}) {
+    const rawEndpoint = config.endpoint || 'https://api.anthropic.com/v1';
+    const endpoint = rawEndpoint.replace(/\/+$/, '').replace(/\/messages$/, '');
+    const apiKey = config.apiKey || process.env.ANTHROPIC_API_KEY || '';
+    if (!apiKey) {
+        throw new Error('Anthropic API key is required (set ANTHROPIC_API_KEY or config.llm.apiKey).');
+    }
+    const cacheEnabled = process.env.BRAINROUTER_ANTHROPIC_CACHE === '1';
+    const body = buildAnthropicRequest(config, messages, tools, {
+        ...options,
+        cacheEnabled: options.cacheEnabled ?? cacheEnabled,
+    });
+    const headers = {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': ANTHROPIC_API_VERSION,
+    };
+    const timeoutMs = Number(process.env.BRAINROUTER_LLM_TIMEOUT_MS || 120000);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const release = await acquireLLMSlot();
+    let res;
+    try {
+        res = await fetch(`${endpoint}/messages`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        release();
+        if (err?.name === 'AbortError') {
+            throw new Error(`Anthropic request timed out after ${timeoutMs}ms.`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+    release();
+    if (!res.ok) {
+        const errText = await res.text();
+        throw new Error(`Anthropic API error: ${res.status} ${res.statusText} - ${errText}`);
+    }
+    const data = await res.json();
+    const parsed = parseAnthropicResponse(data);
+    if (parsed.thinking && options.onThinking) {
+        options.onThinking(parsed.thinking);
+    }
+    return {
+        content: parsed.content,
+        toolCalls: parsed.toolCalls,
+        usage: parsed.usage,
+    };
+}

package/dist/runtime/cronParser.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal 5-field cron parser — `minute hour dom month dow`.
+ *
+ * Vendored intentionally (no node-cron) to keep the dependency surface
+ * small and the semantics predictable. Supports `*`, comma lists,
+ * ranges (`1-5`), and steps (`15`, `0-30/10`). No seconds, no Quartz
+ * extensions, no `@reboot` macros.
+ */
+export interface CronExpr {
+    minute: Set<number>;
+    hour: Set<number>;
+    dom: Set<number>;
+    month: Set<number>;
+    dow: Set<number>;
+    raw: string;
+}
+export declare function parseCron(expr: string): CronExpr | undefined;
+/**
+ * First firing instant strictly AFTER `after`. Walks the calendar
+ * forward, jumping months/days when fields don't match instead of
+ * scanning minute-by-minute.
+ */
+export declare function nextCronFire(cron: CronExpr, after: Date): Date;

package/dist/runtime/cronParser.js

@@ -0,0 +1,122 @@
+/**
+ * Minimal 5-field cron parser — `minute hour dom month dow`.
+ *
+ * Vendored intentionally (no node-cron) to keep the dependency surface
+ * small and the semantics predictable. Supports `*`, comma lists,
+ * ranges (`1-5`), and steps (`15`, `0-30/10`). No seconds, no Quartz
+ * extensions, no `@reboot` macros.
+ */
+const FIELD_RANGES = [
+    { min: 0, max: 59 }, // minute
+    { min: 0, max: 23 }, // hour
+    { min: 1, max: 31 }, // day of month
+    { min: 1, max: 12 }, // month
+    { min: 0, max: 7 }, // day of week (0 or 7 = Sunday)
+];
+function parseField(raw, min, max) {
+    if (raw.length === 0)
+        return undefined;
+    const out = new Set();
+    for (const part of raw.split(',')) {
+        if (!part)
+            return undefined;
+        let step = 1;
+        let range = part;
+        const slash = part.indexOf('/');
+        if (slash >= 0) {
+            const s = Number(part.slice(slash + 1));
+            if (!Number.isInteger(s) || s < 1)
+                return undefined;
+            step = s;
+            range = part.slice(0, slash);
+        }
+        let lo;
+        let hi;
+        if (range === '*' || range === '') {
+            lo = min;
+            hi = max;
+        }
+        else if (range.includes('-')) {
+            const [a, b] = range.split('-');
+            lo = Number(a);
+            hi = Number(b);
+            if (!Number.isInteger(lo) || !Number.isInteger(hi))
+                return undefined;
+        }
+        else {
+            const v = Number(range);
+            if (!Number.isInteger(v))
+                return undefined;
+            lo = v;
+            hi = v;
+        }
+        if (lo < min || hi > max || lo > hi)
+            return undefined;
+        for (let i = lo; i <= hi; i += step)
+            out.add(i);
+    }
+    return out.size > 0 ? out : undefined;
+}
+export function parseCron(expr) {
+    if (typeof expr !== 'string')
+        return undefined;
+    const trimmed = expr.trim();
+    if (!trimmed)
+        return undefined;
+    const fields = trimmed.split(/\s+/);
+    if (fields.length !== 5)
+        return undefined;
+    const parsed = fields.map((f, i) => parseField(f, FIELD_RANGES[i].min, FIELD_RANGES[i].max));
+    if (parsed.some((p) => !p))
+        return undefined;
+    const [minute, hour, dom, month, dowRaw] = parsed;
+    // Normalize dow: 7 → 0 so Sunday has one representation.
+    const dow = new Set();
+    for (const v of dowRaw)
+        dow.add(v === 7 ? 0 : v);
+    return { minute, hour, dom, month, dow, raw: trimmed };
+}
+/**
+ * First firing instant strictly AFTER `after`. Walks the calendar
+ * forward, jumping months/days when fields don't match instead of
+ * scanning minute-by-minute.
+ */
+export function nextCronFire(cron, after) {
+    const d = new Date(after.getTime());
+    d.setSeconds(0, 0);
+    d.setMinutes(d.getMinutes() + 1);
+    const domRestricted = cron.dom.size !== 31;
+    const dowRestricted = cron.dow.size !== 7;
+    // Safety cap — 8 years of day-level iterations is plenty; if we exhaust
+    // it the expression is effectively impossible (e.g. Feb 30).
+    for (let i = 0; i < 366 * 8; i++) {
+        if (!cron.month.has(d.getMonth() + 1)) {
+            d.setDate(1);
+            d.setMonth(d.getMonth() + 1);
+            d.setHours(0, 0, 0, 0);
+            continue;
+        }
+        const domOk = cron.dom.has(d.getDate());
+        const dowOk = cron.dow.has(d.getDay());
+        // Vixie-cron semantics: when both dom and dow are restricted, EITHER
+        // match counts. Otherwise both must match (the unrestricted field is
+        // effectively `*` and always matches).
+        const dateMatches = domRestricted && dowRestricted ? (domOk || dowOk) : (domOk && dowOk);
+        if (!dateMatches) {
+            d.setDate(d.getDate() + 1);
+            d.setHours(0, 0, 0, 0);
+            continue;
+        }
+        if (!cron.hour.has(d.getHours())) {
+            d.setHours(d.getHours() + 1);
+            d.setMinutes(0, 0, 0);
+            continue;
+        }
+        if (!cron.minute.has(d.getMinutes())) {
+            d.setMinutes(d.getMinutes() + 1, 0, 0);
+            continue;
+        }
+        return d;
+    }
+    throw new Error(`cron next-fire search exhausted for "${cron.raw}"`);
+}

package/dist/runtime/mcpClient.js

@@ -23,7 +23,7 @@ export class McpClientWrapper {
     identity = 'unknown';
     serverName;
     constructor() {
-        this.client = new Client({ name: 'brainrouter-cli', version: '0.3.7' }, { capabilities: {} });
+        this.client = new Client({ name: 'brainrouter-cli', version: '0.3.8' }, { capabilities: {} });
     }
     /** Whether this wrapper has an active MCP transport. */
     isConnected() {

package/dist/runtime/mcpPool.d.ts

@@ -52,6 +52,14 @@ export type McpServerStatus = {
  * mode.
  */
 export declare function selectMcpServerIds(servers: Record<string, ServerConfig>, activeServer?: string, requestedProfile?: string): string[];
+/**
+ * 0.3.8-R5 — Single-underscore `mcp_<server>_<tool>` is the canonical
+ * tool-name shape across the CLI. Any legacy double-underscore
+ * `mcp__<server>__<tool>` form that arrives at the pool boundary
+ * (e.g. through an external surface or older skill) is collapsed here
+ * so downstream code can assume one convention.
+ */
+export declare function normalizeMcpToolName(name: string): string;
 export declare class McpClientPool {
     /** serverId → connected wrapper. */
     private clients;

package/dist/runtime/mcpPool.js

@@ -24,6 +24,22 @@ export function selectMcpServerIds(servers, activeServer, requestedProfile) {
         return identity !== 'brainrouter' || id === activeBrainrouter;
     });
 }
+/**
+ * 0.3.8-R5 — Single-underscore `mcp_<server>_<tool>` is the canonical
+ * tool-name shape across the CLI. Any legacy double-underscore
+ * `mcp__<server>__<tool>` form that arrives at the pool boundary
+ * (e.g. through an external surface or older skill) is collapsed here
+ * so downstream code can assume one convention.
+ */
+export function normalizeMcpToolName(name) {
+    if (!name.startsWith('mcp__'))
+        return name;
+    const rest = name.slice('mcp__'.length);
+    const sep = rest.indexOf('__');
+    if (sep < 0)
+        return name;
+    return `mcp_${rest.slice(0, sep)}_${rest.slice(sep + 2)}`;
+}
 function isBrainrouterOwnedTool(name) {
     return name.startsWith('memory_') ||
         [
@@ -286,6 +302,9 @@ export class McpClientPool {
     }
     /** Internal — map a name (prefixed OR raw) to a concrete server + tool. */
     resolveToolCall(name) {
+        // Back-compat: any legacy double-underscore form is collapsed first so
+        // the rest of the resolver only deals with the canonical shape.
+        name = normalizeMcpToolName(name);
         // Fast path: exact prefixed form match in the index.
         if (name.startsWith('mcp_')) {
             const direct = this.prefixedToServer.get(name);

package/dist/runtime/mcpUtils.d.ts

@@ -36,3 +36,17 @@ export declare function callMcpTool<T = any>(client: McpClient, name: string, ar
  * to UUIDs or namespacing per-role) is a one-file edit, not a sweep.
  */
 export declare function childSessionKey(parentSessionKey: string, childId: string): string;
+/**
+ * Discovery helper for `Set<string>` tool-name lookups across MCP prefix
+ * conventions. The pool normalises tool names to single-underscore
+ * `mcp_<server>_<tool>` at the boundary (0.3.8-R5), so a discovery check
+ * for "is `memory_recall` exposed?" must match either the bare name (raw
+ * single-server flow) or any `mcp_<server>_memory_recall` (post-pool
+ * normalisation).
+ *
+ * Use this anywhere a caller previously did `toolNames.has('memory_recall')` —
+ * those bare-name checks silently miss prefixed names and were the root
+ * cause of `🧠 Briefing: 0 records from (none)` even with the brain MCP
+ * connected.
+ */
+export declare function hasMcpTool(toolNames: Set<string>, bareName: string): boolean;

package/dist/runtime/mcpUtils.js

@@ -62,3 +62,26 @@ export async function callMcpTool(client, name, args) {
 export function childSessionKey(parentSessionKey, childId) {
     return `${parentSessionKey}:child:${childId}`;
 }
+/**
+ * Discovery helper for `Set<string>` tool-name lookups across MCP prefix
+ * conventions. The pool normalises tool names to single-underscore
+ * `mcp_<server>_<tool>` at the boundary (0.3.8-R5), so a discovery check
+ * for "is `memory_recall` exposed?" must match either the bare name (raw
+ * single-server flow) or any `mcp_<server>_memory_recall` (post-pool
+ * normalisation).
+ *
+ * Use this anywhere a caller previously did `toolNames.has('memory_recall')` —
+ * those bare-name checks silently miss prefixed names and were the root
+ * cause of `🧠 Briefing: 0 records from (none)` even with the brain MCP
+ * connected.
+ */
+export function hasMcpTool(toolNames, bareName) {
+    if (toolNames.has(bareName))
+        return true;
+    const suffix = `_${bareName}`;
+    for (const name of toolNames) {
+        if (name.startsWith('mcp_') && name.endsWith(suffix))
+            return true;
+    }
+    return false;
+}

package/dist/runtime/scheduleTicker.d.ts

@@ -0,0 +1,33 @@
+/**
+ * In-process ticker that fires due `/schedule` jobs.
+ *
+ * Singleton per CLI process. Wakes every 30s (override via
+ * `BRAINROUTER_SCHEDULE_TICK_MS`), reloads the persisted store, fires
+ * any jobs whose `nextRun` is now in the past, then advances `nextRun`
+ * past `now()` so a missed window only fires ONCE (catch-up
+ * idempotency).
+ *
+ * No daemon — the ticker dies with the REPL. Schedules that miss
+ * because the CLI was closed are caught on the next REPL boot via the
+ * same "advance past now" rule.
+ */
+import { type ScheduleRecord } from '../state/scheduleStore.js';
+export interface ScheduleTickerOptions {
+    workspaceRoot: string;
+    sessionKey: string;
+    /** Called when a schedule is due. Fire-and-forget. */
+    fire: (command: string, schedule: ScheduleRecord) => void;
+    /** Override the wake interval. Defaults to env or 30 000 ms. */
+    intervalMs?: number;
+    /** Injected clock for tests. */
+    now?: () => number;
+    /** Called when a fire is skipped because the expression is unparseable. */
+    onError?: (msg: string) => void;
+}
+export interface ScheduleTickerHandle {
+    stop: () => void;
+    /** Force one immediate scan (tests + boot catch-up). */
+    tickNow: () => void;
+}
+export declare function isScheduleTickerRunning(): boolean;
+export declare function startScheduleTicker(opts: ScheduleTickerOptions): ScheduleTickerHandle;

package/dist/runtime/scheduleTicker.js

@@ -0,0 +1,99 @@
+/**
+ * In-process ticker that fires due `/schedule` jobs.
+ *
+ * Singleton per CLI process. Wakes every 30s (override via
+ * `BRAINROUTER_SCHEDULE_TICK_MS`), reloads the persisted store, fires
+ * any jobs whose `nextRun` is now in the past, then advances `nextRun`
+ * past `now()` so a missed window only fires ONCE (catch-up
+ * idempotency).
+ *
+ * No daemon — the ticker dies with the REPL. Schedules that miss
+ * because the CLI was closed are caught on the next REPL boot via the
+ * same "advance past now" rule.
+ */
+import { loadSchedules, recordFire, removeSchedule, setScheduleEnabled } from '../state/scheduleStore.js';
+import { parseCron, nextCronFire } from './cronParser.js';
+const DEFAULT_INTERVAL_MS = 30_000;
+const MIN_INTERVAL_MS = 100;
+let active = null;
+export function isScheduleTickerRunning() {
+    return active !== null;
+}
+export function startScheduleTicker(opts) {
+    if (active)
+        return active;
+    const envOverride = Number(process.env.BRAINROUTER_SCHEDULE_TICK_MS);
+    const rawInterval = opts.intervalMs ?? (Number.isFinite(envOverride) && envOverride > 0 ? envOverride : DEFAULT_INTERVAL_MS);
+    const interval = Math.max(MIN_INTERVAL_MS, rawInterval);
+    const now = opts.now ?? (() => Date.now());
+    let stopped = false;
+    let timer = null;
+    const scan = () => {
+        if (stopped)
+            return;
+        const t = now();
+        let schedules;
+        try {
+            schedules = loadSchedules(opts.workspaceRoot);
+        }
+        catch (err) {
+            opts.onError?.(`load failed: ${err.message}`);
+            return;
+        }
+        for (const s of schedules) {
+            if (!s.enabled)
+                continue;
+            if (s.owner !== opts.sessionKey)
+                continue;
+            const nextMs = Date.parse(s.nextRun);
+            if (!Number.isFinite(nextMs) || nextMs > t)
+                continue;
+            try {
+                opts.fire(s.command, s);
+            }
+            catch (err) {
+                opts.onError?.(`fire failed for ${s.id}: ${err.message}`);
+            }
+            if (s.kind === 'once') {
+                removeSchedule(opts.workspaceRoot, s.id);
+                continue;
+            }
+            // Cron: advance nextRun strictly past `t`. parseCron should always
+            // succeed (we validated on add), but tolerate corruption by
+            // disabling rather than spinning forever on a past nextRun.
+            const cron = parseCron(s.expr);
+            if (!cron) {
+                opts.onError?.(`cron expression invalid; disabling ${s.id}: ${s.expr}`);
+                try {
+                    setScheduleEnabled(opts.workspaceRoot, s.id, false);
+                }
+                catch { /* swallow */ }
+                continue;
+            }
+            const next = nextCronFire(cron, new Date(t));
+            recordFire(opts.workspaceRoot, s.id, new Date(t), next.toISOString());
+        }
+    };
+    const tick = () => {
+        if (stopped)
+            return;
+        scan();
+        if (stopped)
+            return;
+        timer = setTimeout(tick, interval);
+    };
+    // Defer the first scan to the next macrotask so the caller finishes
+    // wiring (e.g. Ink's `onReady`) before any fire callback runs.
+    timer = setTimeout(tick, 0);
+    active = {
+        stop: () => {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+            active = null;
+        },
+        tickNow: scan,
+    };
+    return active;
+}