clearhand 0.1.0

package/dist/server/routes/api.js

@@ -0,0 +1,704 @@
+import { Router } from 'express';
+import { audit, claimCaseIfNew, countPendingFinancialActions, now, softSupersedeProposals } from '../db/index.js';
+import { enrichCaseFromStripe } from '../context.js';
+import { approveAndExecuteActions, rejectAction, setCaseStatus, } from '../services/approval.js';
+import { lintAndNormalizeAction, lintDraft } from '../services/lint.js';
+import { overlayStatus, readOverlayFile } from '../services/overlay.js';
+import { ACTION_TYPES, DEFAULT_EXECUTION_ORDER, isValidStripeId, } from '../../shared/actions.js';
+import { verifyStripeKey, stripeBusinessSummary, stripeInventory, STRIPE_SECRET_NAME, } from '../connectors/stripe.js';
+import { fetchSentSamples, gmailDefaults, mailboxInventory, verifyMailbox, MAILBOX_SECRET_NAME, } from '../connectors/mailbox.js';
+import { appendEvent, applyStyleSelection, eventsAfter, getOnboardingState, ONBOARDING_STAGES, saveConfirmation, setStage, } from '../services/onboarding.js';
+import { verifyGithub, GITHUB_SECRET_NAME } from '../connectors/github.js';
+import { crawlPages } from '../connectors/crawl.js';
+import { connectionsStatus, mailboxConfig, setConnection, writeConnectionsManifest, } from '../services/connections.js';
+import { listEgress } from '../trust/egress.js';
+import { makeMailer } from '../connectors/mailbox.js';
+export function apiRouter(ctx) {
+    const r = Router();
+    const { db, secrets } = ctx;
+    const err = (res, status, error, extra = {}) => res.status(status).json({ error, ...extra });
+    /**
+     * The execute-token gate. Opt-in: when CLEARHAND_EXECUTE_TOKEN is set, the
+     * money path requires it as a bearer token.
+     */
+    const requireExecuteToken = (req, res) => {
+        const expected = process.env.CLEARHAND_EXECUTE_TOKEN;
+        if (!expected)
+            return true;
+        const got = req.headers.authorization?.replace(/^Bearer\s+/i, '') ?? req.headers['x-clearhand-token'];
+        if (got !== expected) {
+            err(res, 401, 'missing or invalid execute token');
+            return false;
+        }
+        return true;
+    };
+    // ------------------------------------------------------------- status --
+    r.get('/status', (_req, res) => {
+        const queue = db
+            .prepare(`SELECT
+           SUM(CASE WHEN status IN ('new','processed','reviewing') THEN 1 ELSE 0 END) AS open_cases,
+           (SELECT COUNT(*) FROM actions WHERE status = 'proposed') AS pending_proposals
+         FROM cases`)
+            .get();
+        res.json({
+            clearhand: '0.1.0',
+            demo_mode: ctx.demo,
+            secret_storage: secrets.backendName,
+            connections: connectionsStatus(db, secrets),
+            overlay: { files: overlayStatus() },
+            queue: {
+                open_cases: queue.open_cases ?? 0,
+                pending_proposals: queue.pending_proposals ?? 0,
+            },
+        });
+        writeConnectionsManifest(db, secrets);
+    });
+    // --------------------------------------------------------- onboarding --
+    r.get('/onboarding', (_req, res) => {
+        const state = getOnboardingState(db);
+        const last = db.prepare(`SELECT MAX(id) AS m FROM onboarding_events`).get();
+        res.json({ state, last_event_id: last.m ?? 0, demo_mode: ctx.demo });
+    });
+    r.patch('/onboarding/stage', (req, res) => {
+        const stage = String(req.body?.stage ?? '');
+        const status = String(req.body?.status ?? '');
+        if (!ONBOARDING_STAGES.includes(stage)) {
+            return err(res, 400, `unknown stage "${stage}"`);
+        }
+        if (!['pending', 'active', 'done', 'skipped'].includes(status)) {
+            return err(res, 400, `invalid status "${status}"`);
+        }
+        res.json({ state: setStage(db, stage, status) });
+    });
+    r.post('/onboarding/events', (req, res) => {
+        const { stage, kind, payload } = req.body ?? {};
+        if (typeof stage !== 'string' || typeof kind !== 'string') {
+            return err(res, 400, 'stage and kind required');
+        }
+        const id = appendEvent(db, stage, kind, payload);
+        res.json({ id });
+    });
+    r.get('/onboarding/events', (req, res) => {
+        const after = Number(req.query.after) || 0;
+        res.json({ events: eventsAfter(db, after) });
+    });
+    r.post('/onboarding/confirmations', (req, res) => {
+        const { key, value } = req.body ?? {};
+        if (typeof key !== 'string' || !key)
+            return err(res, 400, 'key required');
+        res.json({ state: saveConfirmation(db, key, value) });
+    });
+    r.post('/onboarding/style', (req, res) => {
+        const b = req.body ?? {};
+        if (!['by_the_book', 'track_record', 'generous'].includes(b.choice)) {
+            return err(res, 400, 'choice must be by_the_book | track_record | generous');
+        }
+        if (typeof b.contractText !== 'string' || b.contractText.trim().length < 20) {
+            return err(res, 400, 'contractText required — the prose IS the policy');
+        }
+        const sel = {
+            choice: b.choice,
+            escalation: {
+                legalOrChargeback: true,
+                repeatRefunders: b.escalation?.repeatRefunders !== false,
+                amountOverCents: typeof b.escalation?.amountOverCents === 'number'
+                    ? Math.trunc(b.escalation.amountOverCents)
+                    : null,
+                vipList: Array.isArray(b.escalation?.vipList) ? b.escalation.vipList.map(String) : [],
+            },
+            cancelDefault: b.cancelDefault === 'immediate' ? 'immediate' : 'end_of_period',
+            contractText: b.contractText,
+        };
+        applyStyleSelection(db, sel);
+        res.json({ ok: true, written: 'overlay/policies.md' });
+    });
+    // -------------------------------------------------------------- trust --
+    r.get('/trust', (_req, res) => {
+        res.json({
+            secret_storage: secrets.backendName,
+            secrets: secrets.list(), // metadata + masked hints only
+            secret_access_log: db
+                .prepare(`SELECT * FROM secret_access_log ORDER BY id DESC LIMIT 200`)
+                .all(),
+            egress: listEgress(db),
+            telemetry: 'none — ClearHand has no telemetry endpoint',
+        });
+    });
+    r.get('/audit', (req, res) => {
+        const caseId = req.query.case_id ? Number(req.query.case_id) : null;
+        const rows = caseId
+            ? db.prepare(`SELECT * FROM audit_log WHERE case_id = ? ORDER BY id DESC LIMIT 500`).all(caseId)
+            : db.prepare(`SELECT * FROM audit_log ORDER BY id DESC LIMIT 500`).all();
+        res.json({ audit: rows });
+    });
+    // -------------------------------------------------------- connections --
+    r.post('/connections/stripe', async (req, res) => {
+        const key = typeof req.body?.api_key === 'string' ? req.body.api_key.trim() : '';
+        if (!key)
+            return err(res, 400, 'api_key required');
+        if (ctx.demo) {
+            // Demo mode: simulated connect so the whole onboarding is walkable
+            // without real credentials. No secret is stored; nothing leaves the
+            // machine. Inventory matches the seeded data.
+            setConnection(db, 'stripe', 'connected', { keyType: 'demo', accountHint: '…demo' });
+            setStage(db, 'stripe', 'done');
+            return res.json({
+                ok: true,
+                key_type: 'demo',
+                warning: null,
+                inventory: { products: 3, prices: 7, charges: '1842', refunds: '41', disputes: '3' },
+            });
+        }
+        const check = await verifyStripeKey(db, key);
+        if (!check.ok) {
+            setConnection(db, 'stripe', 'error', null, check.error);
+            return err(res, 400, `Stripe key verification failed: ${check.error}`);
+        }
+        secrets.set(STRIPE_SECRET_NAME, key);
+        setConnection(db, 'stripe', 'connected', { keyType: check.keyType, accountHint: check.accountHint });
+        audit(db, 'human', 'connection_added', { detail: { id: 'stripe', keyType: check.keyType } });
+        writeConnectionsManifest(db, secrets);
+        setStage(db, 'stripe', 'done');
+        let inventory = null;
+        try {
+            inventory = await stripeInventory(db, secrets);
+        }
+        catch {
+            // counts are a nicety; connect already succeeded
+        }
+        res.json({ ok: true, key_type: check.keyType, warning: check.warning ?? null, inventory });
+    });
+    r.post('/connections/mailbox', async (req, res) => {
+        const { address, password } = req.body ?? {};
+        if (typeof address !== 'string' || !address.includes('@') || typeof password !== 'string' || !password) {
+            return err(res, 400, 'address and password required');
+        }
+        const cfg = {
+            ...gmailDefaults(address),
+            ...(req.body.imapHost ? { imapHost: String(req.body.imapHost) } : {}),
+            ...(req.body.imapPort ? { imapPort: Number(req.body.imapPort) } : {}),
+            ...(req.body.smtpHost ? { smtpHost: String(req.body.smtpHost) } : {}),
+            ...(req.body.smtpPort ? { smtpPort: Number(req.body.smtpPort) } : {}),
+            ...(req.body.displayName ? { displayName: String(req.body.displayName) } : {}),
+        };
+        if (ctx.demo) {
+            setConnection(db, 'mailbox', 'connected', {
+                ...cfg,
+                address: 'support@demo.app',
+            });
+            setStage(db, 'mailbox', 'done');
+            return res.json({
+                ok: true,
+                address: 'support@demo.app',
+                inventory: { inboxMessages: 1284, sentMessages: 312, sentFolder: '[Demo]/Sent' },
+            });
+        }
+        secrets.set(MAILBOX_SECRET_NAME, password);
+        const check = await verifyMailbox(db, secrets, cfg);
+        if (!check.ok) {
+            secrets.delete(MAILBOX_SECRET_NAME);
+            setConnection(db, 'mailbox', 'error', null, check.error);
+            return err(res, 400, `mailbox login failed: ${check.error}`);
+        }
+        setConnection(db, 'mailbox', 'connected', cfg);
+        audit(db, 'human', 'connection_added', { detail: { id: 'mailbox', address } });
+        writeConnectionsManifest(db, secrets);
+        setStage(db, 'mailbox', 'done');
+        let inventory = null;
+        try {
+            inventory = await mailboxInventory(db, secrets, cfg);
+        }
+        catch {
+            // counts are a nicety; connect already succeeded
+        }
+        res.json({ ok: true, address, inventory });
+    });
+    r.post('/connections/github', async (req, res) => {
+        const { token, repo } = req.body ?? {};
+        if (typeof token !== 'string' || !token || typeof repo !== 'string' || !/^[\w.-]+\/[\w.-]+$/.test(repo)) {
+            return err(res, 400, 'token and repo ("owner/name") required');
+        }
+        secrets.set(GITHUB_SECRET_NAME, token);
+        const check = await verifyGithub(db, secrets, { repo });
+        if (!check.ok) {
+            secrets.delete(GITHUB_SECRET_NAME);
+            setConnection(db, 'github', 'error', null, check.error);
+            return err(res, 400, `GitHub verification failed: ${check.error}`);
+        }
+        setConnection(db, 'github', 'connected', { repo });
+        audit(db, 'human', 'connection_added', { detail: { id: 'github', repo } });
+        writeConnectionsManifest(db, secrets);
+        res.json({ ok: true, repo });
+    });
+    r.delete('/connections/:id', (req, res) => {
+        const id = req.params.id;
+        const secretName = { stripe: STRIPE_SECRET_NAME, mailbox: MAILBOX_SECRET_NAME, github: GITHUB_SECRET_NAME }[id];
+        if (!secretName)
+            return err(res, 404, 'unknown connection');
+        secrets.delete(secretName);
+        setConnection(db, id, 'disconnected', null);
+        audit(db, 'human', 'connection_removed', { detail: { id } });
+        writeConnectionsManifest(db, secrets);
+        res.json({ ok: true });
+    });
+    // -------------------------------------------------------------- cases --
+    r.get('/cases', (req, res) => {
+        const clauses = [];
+        const params = [];
+        if (req.query.status) {
+            clauses.push(`c.status = ?`);
+            params.push(String(req.query.status));
+        }
+        if (req.query.category) {
+            clauses.push(`c.category = ?`);
+            params.push(String(req.query.category));
+        }
+        if (req.query.search) {
+            // Metadata AND message bodies — "find the customer who mentioned X"
+            // must work even when X never made it into a subject or summary.
+            clauses.push(`(c.subject LIKE ? OR cu.email LIKE ? OR c.summary LIKE ?
+          OR EXISTS (SELECT 1 FROM emails e WHERE e.case_id = c.id AND e.body_text LIKE ?))`);
+            const like = `%${String(req.query.search)}%`;
+            params.push(like, like, like, like);
+        }
+        if (req.query.date_from) {
+            clauses.push(`c.created_at >= ?`);
+            params.push(String(req.query.date_from));
+        }
+        if (req.query.date_to) {
+            clauses.push(`c.created_at <= ?`);
+            params.push(String(req.query.date_to));
+        }
+        const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+        // money_first: cases owing refunds/cancels surface first — this is what
+        // makes "the queue is sorted money-first" true.
+        const ORDERINGS = {
+            updated: 'c.updated_at DESC',
+            oldest: 'c.created_at ASC',
+            money_first: 'pending_financial DESC, proposed_actions DESC, c.updated_at DESC',
+        };
+        const orderBy = ORDERINGS[String(req.query.sort ?? 'updated')] ?? ORDERINGS.updated;
+        const limit = Math.min(Number(req.query.limit) || 50, 200);
+        const offset = Number(req.query.offset) || 0;
+        const cases = db
+            .prepare(`SELECT c.*, cu.email AS customer_email, cu.name AS customer_name,
+           (SELECT COUNT(*) FROM actions a WHERE a.case_id = c.id AND a.status = 'proposed') AS proposed_actions,
+           (SELECT COUNT(*) FROM actions a WHERE a.case_id = c.id AND a.action_type IN ('refund','cancel_subscription')
+              AND a.status IN ('proposed','approved','executing','failed')) AS pending_financial
+         FROM cases c LEFT JOIN customers cu ON cu.id = c.customer_id
+         ${where} ORDER BY ${orderBy} LIMIT ? OFFSET ?`)
+            .all(...params, limit, offset);
+        const total = db
+            .prepare(`SELECT COUNT(*) AS n FROM cases c LEFT JOIN customers cu ON cu.id = c.customer_id ${where}`)
+            .get(...params).n;
+        res.json({ cases, total });
+    });
+    r.get('/cases/:id', (req, res) => {
+        const id = Number(req.params.id);
+        const row = db
+            .prepare(`SELECT c.*, cu.email AS customer_email, cu.name AS customer_name
+           FROM cases c LEFT JOIN customers cu ON cu.id = c.customer_id WHERE c.id = ?`)
+            .get(id);
+        if (!row)
+            return err(res, 404, 'case not found');
+        const emails = db.prepare(`SELECT * FROM emails WHERE case_id = ? ORDER BY received_at`).all(id);
+        const draft = db
+            .prepare(`SELECT * FROM drafts WHERE case_id = ? AND is_current = 1 ORDER BY version DESC LIMIT 1`)
+            .get(id);
+        const actions = db
+            .prepare(`SELECT * FROM actions WHERE case_id = ? ORDER BY execution_order, id`)
+            .all(id);
+        let prepared_context = null;
+        try {
+            prepared_context = row.prepared_context_json ? JSON.parse(String(row.prepared_context_json)) : null;
+        }
+        catch {
+            prepared_context = null;
+        }
+        res.json({ ...row, prepared_context, emails, draft: draft ?? null, actions });
+    });
+    r.post('/cases', (req, res) => {
+        const { email, subject, body } = req.body ?? {};
+        if (typeof email !== 'string' || !email.includes('@'))
+            return err(res, 400, 'email required');
+        db.prepare(`INSERT INTO customers (email, created_at, updated_at) VALUES (?, ?, ?)
+       ON CONFLICT(email) DO NOTHING`).run(email, now(), now());
+        const customerId = db.prepare(`SELECT id FROM customers WHERE email = ?`).get(email).id;
+        const caseId = Number(db
+            .prepare(`INSERT INTO cases (customer_id, source, conversation_key, subject, status, created_at, updated_at)
+           VALUES (?, 'manual', ?, ?, 'new', ?, ?)`)
+            .run(customerId, `manual-${Date.now()}`, subject ?? '(no subject)', now(), now()).lastInsertRowid);
+        if (typeof body === 'string' && body) {
+            db.prepare(`INSERT INTO emails (case_id, direction, from_addr, subject, body_text, received_at, created_at)
+         VALUES (?, 'inbound', ?, ?, ?, ?, ?)`).run(caseId, email, subject ?? null, body, now(), now());
+        }
+        audit(db, 'human', 'case_created', { caseId });
+        res.json({ id: caseId });
+    });
+    r.patch('/cases/:id', (req, res) => {
+        const id = Number(req.params.id);
+        const allowed = ['category', 'priority', 'summary', 'language'];
+        const sets = [];
+        const params = [];
+        for (const key of allowed) {
+            if (req.body?.[key] !== undefined) {
+                sets.push(`${key} = ?`);
+                params.push(req.body[key]);
+            }
+        }
+        if (!sets.length)
+            return err(res, 400, 'nothing to update');
+        const result = db
+            .prepare(`UPDATE cases SET ${sets.join(', ')}, updated_at = ? WHERE id = ?`)
+            .run(...params, now(), id);
+        if (result.changes === 0)
+            return err(res, 404, 'case not found');
+        claimCaseIfNew(db, id);
+        res.json({ ok: true });
+    });
+    r.post('/cases/:id/status', (req, res) => {
+        const id = Number(req.params.id);
+        const status = String(req.body?.status ?? '');
+        if (!['new', 'processed', 'reviewing', 'pending', 'resolved', 'escalated', 'ignored'].includes(status)) {
+            return err(res, 400, `invalid status "${status}"`);
+        }
+        // The blocking resolve-guard, on every status-change path.
+        if (status === 'resolved' && !req.body?.allow_pending_financial) {
+            const pending = countPendingFinancialActions(db, id);
+            if (pending > 0) {
+                return err(res, 409, 'cannot resolve: financial actions not yet executed', {
+                    code: 'pending_financial_actions',
+                    pending_financial: pending,
+                });
+            }
+        }
+        setCaseStatus(db, id, status);
+        audit(db, 'human', 'case_status_changed', { caseId: id, detail: { status } });
+        res.json({ ok: true, status });
+    });
+    r.post('/cases/:id/enrich', async (req, res) => {
+        const id = Number(req.params.id);
+        if (ctx.demo)
+            return res.json({ ok: true, note: 'demo mode — context is pre-seeded' });
+        try {
+            await enrichCaseFromStripe(db, secrets, id);
+            res.json({ ok: true });
+        }
+        catch (e) {
+            err(res, 502, `enrichment failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    r.patch('/cases/:id/context', (req, res) => {
+        const id = Number(req.params.id);
+        const row = db.prepare(`SELECT prepared_context_json FROM cases WHERE id = ?`).get(id);
+        if (!row)
+            return err(res, 404, 'case not found');
+        // Trust boundary: the `stripe` slice is server-owned (written only by the
+        // enricher). LLM-supplied money data is radioactive; agents may add
+        // qualitative slices only.
+        const allowed = ['customer_history', 'site_facts', 'notes', 'bug_repro'];
+        let ctxJson = {};
+        try {
+            ctxJson = row.prepared_context_json ? JSON.parse(row.prepared_context_json) : {};
+        }
+        catch {
+            ctxJson = {};
+        }
+        const rejected = [];
+        for (const [key, value] of Object.entries(req.body ?? {})) {
+            if (allowed.includes(key))
+                ctxJson[key] = value;
+            else
+                rejected.push(key);
+        }
+        db.prepare(`UPDATE cases SET prepared_context_json = ?, updated_at = ? WHERE id = ?`).run(JSON.stringify(ctxJson), now(), id);
+        claimCaseIfNew(db, id);
+        res.json({ ok: true, rejected_keys: rejected });
+    });
+    r.post('/cases/:id/update-draft', (req, res) => {
+        const id = Number(req.params.id);
+        const { body_english, body_translated, target_language } = req.body ?? {};
+        if (typeof body_english !== 'string' || !body_english.trim()) {
+            return err(res, 400, 'body_english required');
+        }
+        const createdBy = req.body?.created_by === 'agent' ? 'agent' : 'human';
+        const prev = db
+            .prepare(`SELECT * FROM drafts WHERE case_id = ? AND is_current = 1 ORDER BY version DESC LIMIT 1`)
+            .get(id);
+        db.prepare(`UPDATE drafts SET is_current = 0 WHERE case_id = ?`).run(id);
+        db.prepare(`INSERT INTO drafts (case_id, version, body_english, body_translated, target_language, is_current, created_by, created_at)
+       VALUES (?, ?, ?, ?, ?, 1, ?, ?)`).run(id, (prev?.version ?? 0) + 1, body_english, body_translated ?? null, target_language ?? null, createdBy, now());
+        claimCaseIfNew(db, id);
+        // The learning loop: a human replacing an agent draft is a labeled example.
+        if (createdBy === 'human' && prev?.created_by === 'agent' && prev.body_english !== body_english) {
+            db.prepare(`INSERT INTO feedback_events (case_id, event_type, original_json, modified_json, created_at)
+         VALUES (?, 'draft_edit', ?, ?, ?)`).run(id, JSON.stringify({ body: prev.body_english }), JSON.stringify({ body: body_english }), now());
+        }
+        res.json({ ok: true, warnings: lintDraft(body_english) });
+    });
+    // ------------------------------------------------------------- actions --
+    r.post('/cases/:id/actions', (req, res) => {
+        const id = Number(req.params.id);
+        const actionType = String(req.body?.action_type ?? '');
+        const rawProposal = req.body?.proposal;
+        if (!ACTION_TYPES.includes(actionType)) {
+            return err(res, 400, `unknown action_type "${actionType}"`);
+        }
+        if (typeof rawProposal !== 'object' || rawProposal === null) {
+            return err(res, 400, 'proposal object required');
+        }
+        if (!db.prepare(`SELECT 1 FROM cases WHERE id = ?`).get(id))
+            return err(res, 404, 'case not found');
+        // Anti-hallucination: strip invalid Stripe ids so the executor re-resolves
+        // from trusted data instead of acting on a made-up identifier.
+        const proposal = { ...rawProposal };
+        if (typeof proposal.subscription_id === 'string' && !isValidStripeId(proposal.subscription_id, 'sub_')) {
+            delete proposal.subscription_id;
+        }
+        if (typeof proposal.charge_id === 'string' &&
+            !isValidStripeId(proposal.charge_id, 'ch_') &&
+            !isValidStripeId(proposal.charge_id, 'py_') &&
+            !isValidStripeId(proposal.charge_id, 'sub_') // sub-in-charge rescue happens in the executor
+        ) {
+            delete proposal.charge_id;
+        }
+        // Single-active-subscription resolution from the server-owned context.
+        if (actionType === 'cancel_subscription' && !proposal.subscription_id) {
+            const ctxRow = db.prepare(`SELECT prepared_context_json FROM cases WHERE id = ?`).get(id);
+            try {
+                const pctx = ctxRow.prepared_context_json ? JSON.parse(ctxRow.prepared_context_json) : {};
+                const subs = (pctx.stripe?.customers ?? []).flatMap((c) => c.subscriptions ?? []);
+                const active = subs.filter((s) => ['active', 'trialing', 'past_due'].includes(s.status));
+                if (active.length === 1)
+                    proposal.subscription_id = active[0].id;
+            }
+            catch {
+                // leave unresolved; lint/executor will handle
+            }
+        }
+        const lint = lintAndNormalizeAction(actionType, proposal);
+        if (lint.errors.length > 0) {
+            return err(res, 400, 'proposal failed lint', { details: lint.errors });
+        }
+        const order = typeof req.body?.execution_order === 'number'
+            ? req.body.execution_order
+            : DEFAULT_EXECUTION_ORDER[actionType];
+        const inserted = db
+            .prepare(`INSERT INTO actions (case_id, action_type, status, execution_order, proposal_json, confidence, policy_matched, created_at)
+         VALUES (?, ?, 'proposed', ?, ?, ?, ?, ?)`)
+            .run(id, actionType, order, JSON.stringify(lint.proposal), typeof req.body?.confidence === 'number' ? req.body.confidence : null, req.body?.policy_matched ?? null, now());
+        const actionId = Number(inserted.lastInsertRowid);
+        claimCaseIfNew(db, id);
+        const superseded = softSupersedeProposals(db, id, actionType, actionId, 'replaced by newer proposal');
+        audit(db, 'agent', 'action_proposed', { caseId: id, actionId, detail: { actionType, superseded } });
+        const action = db.prepare(`SELECT * FROM actions WHERE id = ?`).get(actionId);
+        res.json({ action, warnings: lint.warnings, superseded });
+    });
+    r.post('/cases/:id/actions/:actionId/reject', (req, res) => {
+        const ok = rejectAction(db, Number(req.params.actionId), req.body?.reason);
+        if (!ok)
+            return err(res, 404, 'action not found');
+        res.json({ ok: true });
+    });
+    // THE ONLY MONEY PATH.
+    r.post('/cases/:id/actions/execute', async (req, res) => {
+        if (!requireExecuteToken(req, res))
+            return;
+        const id = Number(req.params.id);
+        const actionIds = Array.isArray(req.body?.actionIds) ? req.body.actionIds.map(Number) : [];
+        if (actionIds.length === 0)
+            return err(res, 400, 'actionIds required');
+        const result = await approveAndExecuteActions(ctx.approval, id, actionIds, {
+            perActionParams: req.body?.perActionParams,
+            sendMode: req.body?.sendMode,
+            allowPendingFinancial: Boolean(req.body?.allow_pending_financial),
+            approvedBy: 'human',
+        });
+        const caseRow = db.prepare(`SELECT * FROM cases WHERE id = ?`).get(id);
+        res.json({
+            success: result.lintFailures.length === 0 && result.results.every((x) => x.success),
+            approved_action_ids: result.approvedIds,
+            lint_failures: result.lintFailures,
+            results: result.results,
+            case: caseRow,
+        });
+    });
+    r.post('/cases/:id/send-reply', async (req, res) => {
+        const id = Number(req.params.id);
+        const body = typeof req.body?.body === 'string' ? req.body.body : '';
+        if (!body.trim())
+            return err(res, 400, 'body required');
+        // Pre-send guard (one half of the Incident-C defense): a reply is exactly
+        // how a customer gets told "you're refunded" while nothing ran.
+        const pending = countPendingFinancialActions(db, id);
+        if (pending > 0 && !req.body?.allow_pending_financial) {
+            return err(res, 409, 'refusing to send: financial actions not yet executed', {
+                code: 'pending_financial_actions',
+                pending_financial: pending,
+            });
+        }
+        const caseRow = db
+            .prepare(`SELECT c.id, cu.email FROM cases c LEFT JOIN customers cu ON cu.id = c.customer_id WHERE c.id = ?`)
+            .get(id);
+        if (!caseRow?.email)
+            return err(res, 404, 'case not found or has no customer email');
+        try {
+            if (ctx.demo) {
+                db.prepare(`INSERT INTO emails (case_id, direction, to_addr, body_text, received_at, created_at)
+           VALUES (?, 'outbound', ?, ?, ?, ?)`).run(id, caseRow.email, body, now(), now());
+            }
+            else {
+                const cfg = mailboxConfig(db);
+                if (!cfg)
+                    return err(res, 502, 'mailbox not connected', { stage: 'smtp_send' });
+                const sent = await makeMailer(db, secrets, cfg).sendReply({
+                    caseId: id,
+                    to: caseRow.email,
+                    body,
+                    ref: `manual-send:case:${id}`,
+                });
+                db.prepare(`INSERT INTO emails (case_id, direction, to_addr, body_text, provider_message_id, received_at, created_at)
+           VALUES (?, 'outbound', ?, ?, ?, ?, ?)`).run(id, caseRow.email, body, sent.providerMessageId, now(), now());
+            }
+            // Manual send marks pending send_reply proposals executed — but NEVER
+            // executes financial actions (the other half of the defense).
+            db.prepare(`UPDATE actions SET status = 'executed', executed_at = ?
+          WHERE case_id = ? AND action_type = 'send_reply' AND status IN ('proposed','approved')`).run(now(), id);
+            audit(db, 'human', 'manual_reply_sent', { caseId: id });
+            const stillPending = countPendingFinancialActions(db, id);
+            res.json({
+                success: true,
+                warning: stillPending > 0
+                    ? `reply sent but ${stillPending} financial action(s) still pending on this case`
+                    : null,
+            });
+        }
+        catch (e) {
+            err(res, 502, `send failed: ${e instanceof Error ? e.message : String(e)}`, { stage: 'smtp_send' });
+        }
+    });
+    // ------------------------------------------------------------ mailbox --
+    r.post('/sync', async (_req, res) => {
+        if (ctx.demo)
+            return res.json({ ok: true, note: 'demo mode — inbox is pre-seeded', scanned: 0, ingested: 0 });
+        const cfg = mailboxConfig(db);
+        if (!cfg)
+            return err(res, 400, 'mailbox not connected');
+        try {
+            const { syncInbox } = await import('../connectors/mailbox.js');
+            const result = await syncInbox(db, secrets, cfg);
+            res.json({ ok: true, ...result });
+        }
+        catch (e) {
+            err(res, 502, `sync failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    // ------------------------------------------------- onboarding extract --
+    r.post('/extract/sent-samples', async (req, res) => {
+        if (ctx.demo)
+            return err(res, 400, 'not available in demo mode');
+        const cfg = mailboxConfig(db);
+        if (!cfg)
+            return err(res, 400, 'mailbox not connected');
+        try {
+            const samples = await fetchSentSamples(db, secrets, cfg, {
+                limit: Math.min(Number(req.body?.limit) || 200, 500),
+                sinceDays: Math.min(Number(req.body?.sinceDays) || 90, 365),
+            });
+            res.json({ count: samples.length, samples });
+        }
+        catch (e) {
+            err(res, 502, `extraction failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    r.post('/extract/stripe-summary', async (_req, res) => {
+        if (ctx.demo)
+            return err(res, 400, 'not available in demo mode');
+        try {
+            res.json(await stripeBusinessSummary(db, secrets));
+        }
+        catch (e) {
+            err(res, 502, `extraction failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    r.post('/extract/crawl', async (req, res) => {
+        const urls = Array.isArray(req.body?.urls) ? req.body.urls.map(String) : [];
+        if (urls.length === 0)
+            return err(res, 400, 'urls required');
+        res.json({ pages: await crawlPages(db, urls) });
+    });
+    // -------------------------------------------------------- calibration --
+    r.get('/calibrations', (_req, res) => {
+        res.json({ calibrations: db.prepare(`SELECT * FROM calibrations ORDER BY id`).all() });
+    });
+    r.post('/calibrations', (req, res) => {
+        const { customer_message, clearhand_draft, actual_reply, context_note } = req.body ?? {};
+        if (typeof customer_message !== 'string' || typeof clearhand_draft !== 'string') {
+            return err(res, 400, 'customer_message and clearhand_draft required');
+        }
+        const inserted = db
+            .prepare(`INSERT INTO calibrations (customer_message, context_note, clearhand_draft, actual_reply, created_at)
+         VALUES (?, ?, ?, ?, ?)`)
+            .run(customer_message, context_note ?? null, clearhand_draft, actual_reply ?? null, now());
+        res.json({ id: Number(inserted.lastInsertRowid) });
+    });
+    r.post('/calibrations/:id/review', (req, res) => {
+        const id = Number(req.params.id);
+        const verdict = String(req.body?.verdict ?? '');
+        if (!['fine', 'edited', 'wrong_policy', 'wrong_facts', 'wrong_tone'].includes(verdict)) {
+            return err(res, 400, 'verdict must be one of fine|edited|wrong_policy|wrong_facts|wrong_tone');
+        }
+        const result = db
+            .prepare(`UPDATE calibrations SET verdict = ?, tags = ?, note = ?, reviewed_at = ? WHERE id = ?`)
+            .run(verdict, JSON.stringify(req.body?.tags ?? []), req.body?.note ?? null, now(), id);
+        if (result.changes === 0)
+            return err(res, 404, 'calibration not found');
+        // Every calibration verdict is learning-loop input.
+        db.prepare(`INSERT INTO feedback_events (event_type, original_json, diff_summary, created_at)
+       VALUES ('calibration', ?, ?, ?)`).run(JSON.stringify({ calibration_id: id, verdict }), req.body?.note ?? null, now());
+        res.json({ ok: true });
+    });
+    // ------------------------------------------------- overlay & learning --
+    r.get('/overlay', (_req, res) => res.json({ files: overlayStatus() }));
+    r.get('/overlay/:name', (req, res) => {
+        const content = readOverlayFile(req.params.name);
+        if (content === null)
+            return err(res, 404, 'overlay file not found');
+        res.json({ name: req.params.name, content });
+    });
+    r.get('/feedback', (_req, res) => {
+        res.json({
+            events: db.prepare(`SELECT * FROM feedback_events ORDER BY id DESC LIMIT 200`).all(),
+        });
+    });
+    r.get('/learning-reviews', (_req, res) => {
+        res.json({ reviews: db.prepare(`SELECT * FROM learning_reviews ORDER BY id DESC LIMIT 100`).all() });
+    });
+    r.post('/learning-reviews', (req, res) => {
+        const { case_id, category, proposed_rule, target_file, target_section } = req.body ?? {};
+        if (typeof proposed_rule !== 'string' || typeof target_file !== 'string') {
+            return err(res, 400, 'proposed_rule and target_file required');
+        }
+        const inserted = db
+            .prepare(`INSERT INTO learning_reviews (case_id, category, proposed_rule, target_file, target_section, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)`)
+            .run(case_id ?? null, category ?? null, proposed_rule, target_file, target_section ?? null, now());
+        res.json({ id: Number(inserted.lastInsertRowid) });
+    });
+    r.post('/learning-reviews/:id/resolve', (req, res) => {
+        const status = String(req.body?.status ?? '');
+        // Human gate: proposed -> approved|rejected (dashboard). Agent side:
+        // approved -> applied, only after the overlay edit actually landed.
+        if (!['approved', 'rejected', 'applied'].includes(status)) {
+            return err(res, 400, 'status must be approved|rejected|applied');
+        }
+        const from = status === 'applied' ? 'approved' : 'proposed';
+        const result = db
+            .prepare(`UPDATE learning_reviews SET status = ?, resolved_at = ? WHERE id = ? AND status = ?`)
+            .run(status, now(), Number(req.params.id), from);
+        if (result.changes === 0)
+            return err(res, 404, `review not found or not in '${from}' state`);
+        res.json({ ok: true });
+    });
+    return r;
+}