argus-decision-mcp 1.0.0

package/dist/lib/ledger-replay.js

@@ -0,0 +1,295 @@
+import fs from 'fs';
+import { deBom } from './deBom.js';
+import { ledgerPath, sessionsRoot, bearingPath } from './layout.js';
+import { asDate } from './resolve-today.js';
+import { safeSegment } from './safe-path.js';
+function freshEntry(id) {
+    return { id, status: 'candidate', text: '', amend_history: [], premises: [] };
+}
+/**
+ * Fold the ledger into contract states as of `today` (YYYY-MM-DD).
+ * `today` is passed in (never read here) so replay is fully deterministic.
+ */
+export function replayLedger(argusDir, today) {
+    const ids = new Set();
+    const sealedPredicates = new Set();
+    const map = new Map();
+    const stats = {
+        total_sealed: 0, total_settled: 0,
+        held: 0, avoided: 0, partial: 0, still_pending: 0,
+    };
+    let dropped = 0;
+    let skippedUnknown = 0;
+    let oldestTs;
+    let raw;
+    try {
+        raw = deBom(fs.readFileSync(ledgerPath(argusDir), 'utf8'));
+    }
+    catch {
+        return { today, overdue: [], ids, sealedPredicates, contracts: map, stats, integrity: { dropped_lines: 0, skipped_unknown: 0 } };
+    }
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            dropped++; // torn/corrupt line (e.g. crash mid-append) — count, don't silently swallow (N3)
+            continue;
+        }
+        if (!ev['id'] || typeof ev['id'] !== 'string') {
+            dropped++;
+            continue;
+        }
+        const id = ev['id'];
+        // gate_input is an over-fire-gate audit record, not a decision the user
+        // opened — counting it made the first-use greeting vanish after a single
+        // restrained argus_open_decision call (11 S7).
+        if (ev['event'] !== 'gate_input')
+            ids.add(id);
+        // Record inception (P1-E7): ISO timestamps compare lexicographically.
+        if (typeof ev['ts'] === 'string' && ev['ts'] && (!oldestTs || ev['ts'] < oldestTs))
+            oldestTs = ev['ts'];
+        let cur = map.get(id);
+        switch (ev['event']) {
+            case 'harvest':
+                if (!cur) {
+                    cur = freshEntry(id);
+                    cur.text = ev['decision'] || ev['quote'] || '';
+                    map.set(id, cur);
+                }
+                break;
+            case 'seal': {
+                if (!cur) {
+                    cur = freshEntry(id);
+                    map.set(id, cur);
+                } // B1: self-create instead of drop
+                if (typeof ev['predicate'] === 'string') {
+                    sealedPredicates.add(ev['predicate']);
+                    cur.predicate = ev['predicate'];
+                    cur.text = ev['predicate'];
+                }
+                cur.check_by = ev['check_by'];
+                if (typeof ev['basis'] === 'string')
+                    cur.basis = ev['basis'];
+                cur.status = 'sealed';
+                stats.total_sealed++;
+                break;
+            }
+            case 'amend':
+                if (!cur) {
+                    cur = freshEntry(id);
+                    map.set(id, cur);
+                }
+                if (ev['predicate'] != null) {
+                    cur.predicate = ev['predicate'];
+                    cur.text = ev['predicate'];
+                }
+                if (ev['check_by'] != null)
+                    cur.check_by = ev['check_by'];
+                cur.amend_history.push({
+                    predicate: ev['predicate'],
+                    check_by: ev['check_by'],
+                    ts: ev['ts'],
+                });
+                break;
+            case 'dismiss':
+                if (!cur) {
+                    cur = freshEntry(id);
+                    map.set(id, cur);
+                }
+                cur.status = 'dismissed';
+                if (typeof ev['dismiss_reason'] === 'string')
+                    cur.dismiss_reason = ev['dismiss_reason'];
+                break;
+            case 'settle': {
+                if (!cur) {
+                    cur = freshEntry(id);
+                    map.set(id, cur);
+                } // B1: self-create
+                cur.status = 'settled';
+                stats.total_settled++;
+                const outcome = ev['outcome'];
+                cur.outcome = outcome;
+                if (typeof ev['ts'] === 'string' && ev['ts'].length >= 10)
+                    cur.settled_on = ev['ts'].slice(0, 10);
+                if (typeof ev['broken_premise_id'] === 'string')
+                    cur.broken_premise_id = ev['broken_premise_id'];
+                if (outcome === 'held')
+                    stats.held++;
+                else if (outcome === 'avoided')
+                    stats.avoided++;
+                else if (outcome === 'partial')
+                    stats.partial++;
+                else if (outcome === 'still_pending')
+                    stats.still_pending++;
+                break;
+            }
+            // ── living premises (plan v5 §6.1). The fold is not a validator — the
+            //    write-time guard is; replay stays defensive and never throws. ──
+            case 'premise_add': {
+                if (!cur) {
+                    cur = freshEntry(id);
+                    map.set(id, cur);
+                } // defensive only; the guard refuses absent at write time
+                const pid = ev['premise_id'];
+                if (typeof pid !== 'string' || typeof ev['text'] !== 'string') {
+                    dropped++;
+                    break;
+                }
+                const list = (cur.premises ??= []);
+                if (list.some((p) => p.premise_id === pid))
+                    break; // idempotent re-add
+                list.push({
+                    premise_id: pid,
+                    ordinal: typeof ev['ordinal'] === 'number' ? ev['ordinal'] : list.length + 1,
+                    kind: (ev['kind'] === 'open_question' ? 'open_question' : 'premise'),
+                    text: ev['text'],
+                    external: ev['external'] === true,
+                    load_bearing: ev['load_bearing'] === true,
+                    source: (ev['source'] === 'user' ? 'user' : 'ai'),
+                    ...(typeof ev['ai_original'] === 'string' ? { ai_original: ev['ai_original'] } : {}),
+                    status: 'active',
+                    amend_history: [],
+                    recheck_count: 0,
+                });
+                break;
+            }
+            case 'premise_amend': {
+                const p = cur?.premises?.find((x) => x.premise_id === ev['premise_id']);
+                if (!p)
+                    break; // amend of an unknown premise: write-time guard prevents; replay tolerates
+                const action = ev['action'];
+                p.amend_history.push({
+                    action,
+                    from: ev['from'],
+                    to: ev['to'],
+                    note: ev['note'],
+                    ts: ev['ts'],
+                });
+                if ((action === 'refine' || action === 'replace') && typeof ev['to'] === 'string')
+                    p.text = ev['to'];
+                if (action === 'retire')
+                    p.status = 'retired';
+                // Flags may be corrected post-add (e.g. marking a promoted premise external
+                // so monitoring can arm) — monitoring stays DERIVED from these flags.
+                if (typeof ev['external'] === 'boolean')
+                    p.external = ev['external'];
+                if (typeof ev['load_bearing'] === 'boolean')
+                    p.load_bearing = ev['load_bearing'];
+                break;
+            }
+            case 'premise_recheck': {
+                const p = cur?.premises?.find((x) => x.premise_id === ev['premise_id']);
+                if (!p)
+                    break;
+                if (typeof ev['finding'] !== 'string' || typeof ev['source'] !== 'string')
+                    break;
+                p.last_recheck = {
+                    finding: ev['finding'],
+                    ...(typeof ev['numeric_value'] === 'number' ? { numeric_value: ev['numeric_value'] } : {}),
+                    drifted: ev['drifted'] === true,
+                    baseline_only: ev['baseline_only'] === true,
+                    source: ev['source'],
+                    ...(typeof ev['source_detail'] === 'string' ? { source_detail: ev['source_detail'] } : {}),
+                    ts: ev['ts'],
+                };
+                p.recheck_count++;
+                break;
+            }
+            case 'premise_resolve': {
+                const p = cur?.premises?.find((x) => x.premise_id === ev['premise_id']);
+                if (!p)
+                    break;
+                p.status = 'resolved';
+                if (typeof ev['decision'] === 'string')
+                    p.resolved_decision = ev['decision'];
+                break;
+            }
+            case 'gate_input':
+                break; // known meta event (over-fire gate audit) — not a state change, not corrupt
+            default:
+                // Forward-compat tolerance (plan v5 §6.3): a well-formed, VERSIONED event
+                // whose type this binary doesn't know was written by a newer argus-mcp —
+                // skip it silently (like gate_input) instead of counting it as corruption,
+                // so an old install never raises a false integrity alarm on a new ledger.
+                // Only unversioned/structurally-broken events still count as dropped.
+                if (typeof ev['event'] === 'string' && typeof ev['v'] === 'number')
+                    skippedUnknown++;
+                else
+                    dropped++;
+                break;
+        }
+    }
+    const overdue = [];
+    for (const [id, item] of map.entries()) {
+        if (item.status !== 'sealed')
+            continue;
+        const date = asDate(item.check_by);
+        if (date && date <= today)
+            overdue.push({ id, date, text: item.text || '' });
+    }
+    overdue.sort((a, b) => (a.date < b.date ? -1 : 1));
+    return { today, overdue, ids, sealedPredicates, contracts: map, stats, oldest_ts: oldestTs, integrity: { dropped_lines: dropped, skipped_unknown: skippedUnknown } };
+}
+/**
+ * Bearing-file contract seeds that are due but not yet represented in the
+ * ledger (the seal may have been written as a bearing before the ledger event).
+ * Directory names read off disk are validated with `safeSegment` before use.
+ */
+export function bearingContracts(argusDir, today, ledger) {
+    const out = [];
+    const root = sessionsRoot(argusDir);
+    let ids = [];
+    try {
+        ids = fs.readdirSync(root);
+    }
+    catch {
+        return out;
+    }
+    for (const rawId of ids) {
+        let id;
+        try {
+            id = safeSegment(rawId, 'id');
+        }
+        catch {
+            continue;
+        } // skip stray/unsafe dir names
+        if (ledger.sealedPredicates.size && ledger.ids.has(id)) {
+            const entry = ledger.contracts.get(id);
+            if (entry && entry.status !== 'candidate')
+                continue; // already represented
+        }
+        const bearing = readJson(bearingPath(argusDir, id));
+        const seed = bearing && bearing['contract_seed'];
+        if (!seed || typeof seed['predicate'] !== 'string')
+            continue;
+        if (ledger.sealedPredicates.has(seed['predicate']))
+            continue;
+        const date = asDate(seed['check_by']);
+        if (date && date <= today) {
+            out.push({ id, date, predicate: seed['predicate'], check_by: seed['check_by'] });
+        }
+    }
+    return out;
+}
+function readJson(file) {
+    try {
+        return JSON.parse(deBom(fs.readFileSync(file, 'utf8')));
+    }
+    catch {
+        return null;
+    }
+}
+// Re-export for callers that imported these from here historically.
+export { asDate };
+export const _ledgerFileExists = (argusDir) => {
+    try {
+        return fs.existsSync(ledgerPath(argusDir));
+    }
+    catch {
+        return false;
+    }
+};

package/dist/lib/locale.js

@@ -0,0 +1,20 @@
+import fs from 'fs';
+import { configPath } from './layout.js';
+export function detectLocale(argusDir) {
+    try {
+        const cfg = fs.readFileSync(configPath(argusDir), 'utf8');
+        const m = cfg.match(/^locale:\s*(ko|en)\b/m);
+        if (m)
+            return m[1];
+    }
+    catch { /* no config */ }
+    const env = process.env['LANG'] || process.env['LC_ALL'] || '';
+    if (/^ko/i.test(env))
+        return 'ko';
+    try {
+        if (/^ko/i.test(Intl.DateTimeFormat().resolvedOptions().locale))
+            return 'ko';
+    }
+    catch { /* Intl unavailable */ }
+    return 'en';
+}

package/dist/lib/log.js

@@ -0,0 +1,14 @@
+/**
+ * Diagnostics go to stderr ONLY (addendum N4). A stdio MCP server must never
+ * write to stdout — that channel carries JSON-RPC frames and any stray byte
+ * corrupts the protocol. Verbose output is gated behind ARGUS_DEBUG.
+ */
+export function logError(msg, err) {
+    const detail = err instanceof Error ? err.stack || err.message : err !== undefined ? String(err) : '';
+    process.stderr.write(`argus-mcp ERROR ${msg}${detail ? ' :: ' + detail : ''}\n`);
+}
+export function logDebug(msg) {
+    if (process.env['ARGUS_DEBUG']) {
+        process.stderr.write(`argus-mcp DEBUG ${msg}\n`);
+    }
+}

package/dist/lib/numeric-drift.js

@@ -0,0 +1,32 @@
+/**
+ * Numeric premise drift — the only MECHANICAL drift decision (plan v5 §7.1).
+ *
+ * Deliberately takes explicit numbers, never parses them out of prose: the
+ * webapp's regex-first-number approach reads "2026년 기준금리 3.5%" as 2026 and
+ * manufactures fake drift. The HOST names the number; this function only compares.
+ *
+ * Text premises are NOT decided here — a paraphrase is not a changed fact, so
+ * string comparison over-fires. For text, the host asserts `changed` as a
+ * research finding (provenance-armed, recorded verbatim; see argus_recheck).
+ */
+/** Relative move (fraction) below which a numeric change is noise, not drift. */
+export const NUMERIC_DRIFT_THRESHOLD = 0.1;
+export function numericDrift(prev, next) {
+    if (!Number.isFinite(prev) || !Number.isFinite(next)) {
+        return { drifted: false, reason: 'non-finite input — not comparable' };
+    }
+    if (prev === next)
+        return { drifted: false, reason: 'unchanged' };
+    const signFlip = Math.sign(prev) !== Math.sign(next) && prev !== 0 && next !== 0;
+    if (prev === 0) {
+        // No relative base — any move off zero is a real change.
+        return { drifted: true, reason: `moved off zero: 0 → ${next}` };
+    }
+    const rel = Math.abs(next - prev) / Math.abs(prev);
+    if (signFlip)
+        return { drifted: true, reason: `sign flip: ${prev} → ${next}` };
+    if (rel >= NUMERIC_DRIFT_THRESHOLD) {
+        return { drifted: true, reason: `moved ${Math.round(rel * 100)}%: ${prev} → ${next}` };
+    }
+    return { drifted: false, reason: `moved ${Math.round(rel * 100)}% (<${Math.round(NUMERIC_DRIFT_THRESHOLD * 100)}% threshold)` };
+}

package/dist/lib/overfire-gate.js

@@ -0,0 +1,39 @@
+/**
+ * Over-fire gate (blueprint §3.3 — the mirror clause as code).
+ *
+ * `zero judgment` is wider than "don't judge the user" — it also means don't
+ * judge WHETHER to intervene. This gate runs inside argus_open_decision BEFORE
+ * any crux question is formed. On a flat / low-stakes / reversible / already-
+ * closed decision it returns restraint ("leave as is"), emitting no question
+ * and no fork.
+ *
+ * HONEST LIMIT (M2): the inputs are CLAIMED by the model, not measured. The gate
+ * cannot be more right than its inputs — it is a restraint bias, not a
+ * correcting oracle. Contradictory inputs are flagged for one re-confirmation,
+ * and the inputs are logged so post-hoc evals can measure input accuracy.
+ */
+export function overfireGate(s) {
+    // Contradictory signals → ask once before trusting them (M2).
+    if (s.reversibility === 'easily_reversible' && s.stakes === 'high') {
+        return {
+            fire: false,
+            reason: 'contradictory_signals',
+            response: 'reconfirm',
+        };
+    }
+    if (s.is_vent)
+        return { fire: false, reason: 'vent', response: 'leave_as_is' };
+    if (s.is_factual)
+        return { fire: false, reason: 'factual', response: 'leave_as_is' };
+    if (s.already_decided)
+        return { fire: false, reason: 'already_closed', response: 'leave_as_is' };
+    // Reversible + not high stakes → restraint (the cost of being wrong is an undo).
+    if (s.reversibility === 'easily_reversible' && s.stakes !== 'high') {
+        return { fire: false, reason: 'reversible_low_stakes', response: 'leave_as_is' };
+    }
+    // Genuinely low/trivial stakes → restraint.
+    if (s.stakes === 'trivial' || s.stakes === 'low') {
+        return { fire: false, reason: 'low_stakes', response: 'leave_as_is' };
+    }
+    return { fire: true, reason: 'consequential_open_fork', response: 'fire' };
+}

package/dist/lib/premises.js

@@ -0,0 +1,153 @@
+import { deriveState } from './state-machine.js';
+import { GuardError } from './state-machine.js';
+/** Hard caps (plan v5 §2): a decision is 5 premises, not a wiki. */
+export const MAX_ACTIVE_PREMISES = 5;
+export const MAX_LOAD_BEARING = 2;
+/** Re-check cadence: gates DUE-COMPUTATION ONLY — an explicit recheck is always
+ *  writable (the mistake-correction path, plan v5 P3). */
+export const RECHECK_MIN_INTERVAL_DAYS = 7;
+// ── identity ──────────────────────────────────────────────────────────────
+export function normalizePremiseText(text) {
+    return text.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+/** Stable, decision-scoped premise id (djb2). Stable across re-adds so nothing
+ *  is orphaned; scoped by decision so identical facts in two decisions don't
+ *  collide on the row while still being groupable by normalized text. */
+export function premiseId(decisionId, kind, text) {
+    const key = `${decisionId}:${kind}:${normalizePremiseText(text)}`;
+    let h = 5381;
+    for (let i = 0; i < key.length; i++)
+        h = ((h << 5) + h + key.charCodeAt(i)) >>> 0;
+    return `p_${h.toString(36)}`;
+}
+/** Monitoring is DERIVED, never stored (state-is-the-fold): only an active,
+ *  load-bearing, external premise is watched — the opt-out default that arms
+ *  the return loop without ceremony (plan v5 §12). */
+export function isMonitored(p) {
+    return p.kind === 'premise' && p.status === 'active' && p.external && p.load_bearing;
+}
+// ── ref resolution (ordinals beat opaque ids across turns) ────────────────
+/**
+ * Resolve a user/host premise reference: an ordinal ("P1"/"p1"/"1"), a full
+ * premise_id, or an unambiguous id prefix (≥4 chars). Throws GuardError
+ * NO_SUCH_PREMISE / AMBIGUOUS_REF with the current list in the recovery hint.
+ */
+export function resolvePremiseRef(premises, ref) {
+    const list = premises ?? [];
+    const listing = list.map((p) => `P${p.ordinal}=${p.premise_id} (${p.status}) "${p.text.slice(0, 40)}"`).join('; ') || '(none)';
+    const r = ref.trim();
+    const ord = /^[Pp]?(\d+)$/.exec(r);
+    if (ord) {
+        const n = parseInt(ord[1], 10);
+        const hit = list.find((p) => p.ordinal === n);
+        if (hit)
+            return hit;
+        throw new GuardError('NO_SUCH_PREMISE', `No premise P${n} on this decision.`, `Current premises: ${listing}`);
+    }
+    const exact = list.find((p) => p.premise_id === r);
+    if (exact)
+        return exact;
+    if (r.length >= 4) {
+        const matches = list.filter((p) => p.premise_id.startsWith(r));
+        if (matches.length === 1)
+            return matches[0];
+        if (matches.length > 1) {
+            throw new GuardError('AMBIGUOUS_REF', `"${r}" matches ${matches.length} premises.`, `Use the ordinal instead: ${listing}`);
+        }
+    }
+    throw new GuardError('NO_SUCH_PREMISE', `No premise matches "${r}".`, `Use an ordinal like "P1". Current premises: ${listing}`);
+}
+function dateOnly(ts) {
+    return ts && ts.length >= 10 ? ts.slice(0, 10) : undefined;
+}
+function daysBetween(from, to) {
+    const a = Date.parse(from + 'T00:00:00Z');
+    const b = Date.parse(to + 'T00:00:00Z');
+    if (Number.isNaN(a) || Number.isNaN(b))
+        return 0;
+    return Math.round((b - a) / 86400000);
+}
+/** Is this premise due for a re-check as of `today`? Monitored + never checked,
+ *  or last checked ≥ RECHECK_MIN_INTERVAL_DAYS ago. (Writing a recheck is never
+ *  blocked by this — it gates the nudge, not the pen.) */
+export function isDueForRecheck(p, today) {
+    if (!isMonitored(p))
+        return false;
+    const last = dateOnly(p.last_recheck?.ts);
+    if (!last)
+        return true;
+    return daysBetween(last, today) >= RECHECK_MIN_INTERVAL_DAYS;
+}
+/**
+ * All due premises across the ledger. Sealing arms monitoring (plan v5 P4): only
+ * decisions in sealed|due state count — an opened-never-sealed decision's
+ * premises are tracked but never nagged, and settled/dismissed are closed.
+ */
+export function duePremises(state) {
+    const out = [];
+    for (const entry of state.contracts.values()) {
+        const dState = deriveState(entry, state.today);
+        if (dState !== 'sealed' && dState !== 'due')
+            continue;
+        for (const p of entry.premises ?? []) {
+            if (!isDueForRecheck(p, state.today))
+                continue;
+            const last = dateOnly(p.last_recheck?.ts);
+            out.push({
+                decision_id: entry.id,
+                decision_text: (entry.text || '').slice(0, 48),
+                ordinal: p.ordinal,
+                premise_id: p.premise_id,
+                text: p.text,
+                last_checked: last,
+                days_stale: last ? daysBetween(last, state.today) : null,
+            });
+        }
+    }
+    // Never-checked first (most stale), then by staleness.
+    out.sort((a, b) => (b.days_stale ?? Infinity) - (a.days_stale ?? Infinity));
+    return out;
+}
+export function groupDuePremises(due) {
+    const byText = new Map();
+    for (const d of due) {
+        const key = normalizePremiseText(d.text);
+        const g = byText.get(key);
+        if (g)
+            g.premises.push(d);
+        else
+            byText.set(key, { text: d.text, premises: [d] });
+    }
+    return [...byText.values()];
+}
+/** The living-premises summary a receipt renders from (plan v5 §3.3): the
+ *  premise set is canonical — headline = first active load-bearing premise. */
+export function receiptPremisesInfo(entry) {
+    const list = entry?.premises ?? [];
+    if (list.length === 0)
+        return undefined;
+    const headline = list.find((p) => p.status === 'active' && p.load_bearing && p.kind === 'premise')?.text;
+    return {
+        ...(headline ? { headline } : {}),
+        tracked: list.length,
+        changed_at_recheck: list.filter((p) => p.last_recheck?.drifted === true).length,
+    };
+}
+/** Active monitored premises across OTHER decisions whose normalized text matches
+ *  — the explicit apply_to_matching fan-out targets (plan v5 P1). */
+export function matchingMonitoredPremises(state, sourceDecisionId, text) {
+    const key = normalizePremiseText(text);
+    const out = [];
+    for (const entry of state.contracts.values()) {
+        if (entry.id === sourceDecisionId)
+            continue;
+        const dState = deriveState(entry, state.today);
+        if (dState !== 'sealed' && dState !== 'due' && dState !== 'opened')
+            continue;
+        for (const p of entry.premises ?? []) {
+            if (isMonitored(p) && normalizePremiseText(p.text) === key)
+                out.push({ entry, premise: p });
+        }
+    }
+    return out;
+}

package/dist/lib/privacy.js

@@ -0,0 +1,22 @@
+import fs from 'fs/promises';
+import path from 'path';
+/**
+ * Ensure the `.argus/.gitignore` keeps private decision data out of git
+ * (SECURITY.md: ".argus holds private decisions, gitignored"). Idempotent.
+ */
+export async function ensurePrivacyGitignore(argusDir) {
+    const gitignorePath = path.join(argusDir, '.gitignore');
+    try {
+        const existing = await fs.readFile(gitignorePath, 'utf8').catch(() => '');
+        const lines = new Set(existing.split('\n').map((l) => l.trim()));
+        const needed = ['sessions/', 'ledger/', '.bound'];
+        const toAdd = needed.filter((n) => !lines.has(n));
+        if (toAdd.length) {
+            await fs.mkdir(argusDir, { recursive: true });
+            await fs.appendFile(gitignorePath, (existing && !existing.endsWith('\n') ? '\n' : '') + toAdd.join('\n') + '\n');
+        }
+    }
+    catch {
+        /* non-critical */
+    }
+}

package/dist/lib/push-account.js

@@ -0,0 +1,70 @@
+/**
+ * Opt-in account sync (design: "MCP도 이메일로 귀환").
+ *
+ * The MCP server is a short-lived stdio process — it is NOT alive at a
+ * prediction's check-by date, so it cannot email you itself. To close the loop
+ * it pushes the sealed prediction to the user's Argus account, where an
+ * always-on server cron (the Companion Brief) emails it when it comes due and
+ * the webapp dashboard shows it.
+ *
+ * Strictly opt-in: with no ARGUS_TOKEN the push is a silent no-op and the seal
+ * stays purely local (the privacy-preserving default). Fire-safe: any failure
+ * degrades to local-only and never breaks the seal that already succeeded.
+ *
+ *   MCP config env:
+ *     ARGUS_TOKEN    argus_pat_… (issued in the webapp; same token as `argus push`)
+ *     ARGUS_API_URL  optional, defaults to https://argus.voyage
+ */
+const TIMEOUT_MS = 5000;
+/** Pull the account's receipts (the sync's read side). No token ⇒ empty. */
+export async function fetchAccountReceipts() {
+    const token = (process.env.ARGUS_TOKEN || '').trim();
+    if (!token || !token.startsWith('argus_pat_'))
+        return { ok: false, reason: 'no_token', receipts: [] };
+    const base = (process.env.ARGUS_API_URL || 'https://argus.voyage').replace(/\/+$/, '');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const res = await fetch(`${base}/api/mcp/receipts`, {
+            headers: { authorization: `Bearer ${token}` },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return { ok: false, reason: `http_${res.status}`, receipts: [] };
+        const body = (await res.json());
+        return { ok: true, receipts: Array.isArray(body.receipts) ? body.receipts : [] };
+    }
+    catch {
+        return { ok: false, reason: 'network', receipts: [] };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function pushToAccount(payload) {
+    const token = (process.env.ARGUS_TOKEN || '').trim();
+    if (!token)
+        return { synced: false, reason: 'no_token' }; // local-only (default)
+    if (!token.startsWith('argus_pat_'))
+        return { synced: false, reason: 'bad_token_format' };
+    const base = (process.env.ARGUS_API_URL || 'https://argus.voyage').replace(/\/+$/, '');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const res = await fetch(`${base}/api/mcp/seal`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return { synced: false, reason: `http_${res.status}` };
+        return { synced: true };
+    }
+    catch {
+        return { synced: false, reason: 'network' }; // never throws — local seal already stands
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}