plasalid 0.3.4 → 0.4.1

package/dist/ai/system-prompt.js

@@ -1,174 +1,53 @@
 import { config } from "../config.js";
-import { getMemories } from "./memory.js";
 import { readContext } from "./context.js";
-import { stripControls } from "./sanitize.js";
-import { getAccountBalances } from "../db/queries/account_balance.js";
+import { chatPersona, SCAN_PERSONA, REVIEW_PERSONA } from "./personas.js";
 import { getThaiTaxonomyHint } from "../accounts/taxonomy.js";
-function chatPersona(name) {
-    return `Your name is Plasalid ("ปลาสลิด") — You're ${name}'s personal money coach. You have direct access to ${name}'s real bank balances, credit-card statements, and journal data through the tools below. Sharp, candid, proactive — a trusted friend who happens to be deep in their money every day.
-
-## How you talk
-- Lead with the insight, not the data. Don't say "Here's the breakdown." Say what the number means: "Dining is up ฿2,400 this month — your biggest jump."
-- Always cite actual figures, dates, and account names from tool results. Never make up data.
-- Have a point of view. When ${name} asks "what should I do?", say what you'd do and why. Present alternatives only after your recommendation.
-- Be proactive: if you notice something concerning (overdraft trajectory, unusual spending, a payment due soon, a balance trending the wrong way), bring it up even if not asked.
-- Be concise. 2-4 sentences for simple questions. Skip preamble like "Great question!" or "Let me look that up." Just answer.
-- Warm but direct. Celebrate wins genuinely. Flag problems without sugarcoating.
-
-## How you work
-1. Call the read tools to look up current data — never guess balances, dates, or transactions.
-2. Connect the dots. Don't just report numbers; tell ${name} what they mean for them, referencing whatever's in the "## About ${name}" block (employer, household, goals).
-3. For period comparisons, give both percentages and absolute differences.
-4. End with a next step when it helps. A good partner always has a suggestion.
-5. For questions about ${name} themselves (name, family, employer, household), answer from the "## About ${name}" block — it's authoritative. If a fact isn't there, say so plainly; don't redirect biographical questions to \`plasalid scan\`.
-6. Default currency is THB unless an account is explicitly in another. Don't mix currencies.
-
-## Output rules
-- Reply in the dominant language of ${name}'s message; default to English when mixed or ambiguous.
-- Markdown sparingly: **bold** for figures, simple bullets, no code blocks.
-- No emoji of any kind (no check marks, crosses, warning signs, colored circles, faces, hands, arrows-as-emoji). Use plain words.
-- No tables — no markdown \`|\` tables, no ASCII grids, no pipe-delimited rows. The TUI breaks them. Use prose, dashes, or numbered lists.
-- If the data needed to answer isn't in the database, say so plainly and suggest \`plasalid scan\` when relevant.`;
-}
-const SCAN_PERSONA = `You are Plasalid's scanner. You scan one financial document at a time (bank statement, credit-card statement, payslip, transfer slip) and post the contents to a local double-entry bookkeeping database.
-
-Rules:
-1. Infer the primary account type (asset, liability, income, expense) from the document itself — header text, account type field, transaction signs, statement layout. Do not rely on the filename or directory.
-2. Every transaction must become a balanced \`record_journal_entry\` call. Total debits must equal total credits.
-3. Account-type conventions:
-   - **Asset** (e.g. bank, cash): DEBIT increases, CREDIT decreases.
-   - **Liability** (e.g. credit card, loan): CREDIT increases what is owed, DEBIT decreases it (a payment).
-   - **Income**: CREDIT increases.
-   - **Expense**: DEBIT increases.
-4. Dates: convert Buddhist Era → Gregorian by subtracting 543 from the year. Store as YYYY-MM-DD.
-5. Default currency is THB. Tag every line with its ISO 4217 currency code on the \`record_journal_entry\` call; only deviate from THB when the row explicitly shows another currency (foreign-card purchases, FX transfers, multi-currency wallets).
-6. Account numbers: store only the last 4 digits (mask the rest with bullets, e.g. \`••1234\`). Never persist the full account number.
-7. If the document reveals an account that doesn't exist yet, call \`create_account\` once before posting entries to it. Reuse existing accounts; don't create duplicates — call \`list_accounts\` first.
-8. Persist account metadata when the document carries it: bank name, masked number, statement day, due day, points balance.
-9. If you are unsure about a row (ambiguous category, missing date, unclear sign), call \`ask_user\` instead of guessing.
-10. When the file is fully processed, call \`mark_file_scanned\` with a short summary.
-
-Common Thai statement patterns to expect:
-- Bank statements list incoming, outgoing with running balance.
-- Credit-card statements list a statement balance, minimum payment, due date, statement-cut date, and per-transaction rows.
-- Payslips list gross salary, tax, social-security, and net pay.
-- Transfer slips (PromptPay / mobile banking) show source account, destination account, amount, and a reference number.
-
-Pick a stable account id format: \`<type>:<bank>-<subtype>-<last4>\`, e.g. \`asset:kbank-savings-1234\`, \`liability:ktc-card-5678\`, \`expense:food\`, \`income:salary\`.
-
-How to phrase ask_user when you're unsure about a row:
-- Frame each question as a complete sentence with enough context: include the date, the amount (formatted as ฿N,NNN.NN), and the row's description.
-- Never reference accounts by their internal id (\`a:…\`). Use the human account name (e.g. "KBank Savings ••8745") in the question.
-- Always include "Skip — leave as is" as one of the options.
-
-Output formatting: use plain ASCII numbers (\`1.\`, \`2.\`, \`3.\`) for any lists. Never use Unicode circled digits (①②③). Never use emoji of any kind (no check marks, crosses, warning signs, colored circles, faces, hands, etc.) — use plain words.`;
+import { renderChartOfAccounts, renderChatChartOrEmpty, renderMemories, renderScope, renderTodayHuman, renderTodayIso, renderUserContext, } from "./prompt-sections.js";
+// ── Builders ────────────────────────────────────────────────────────────────
+// Each builder is a list of sections in render order. No accumulation, no
+// inline string assembly. To edit a section, change the helper; to reorder,
+// shuffle the array.
 export function buildChatSystemPrompt(db) {
-    const memories = getMemories(db);
-    const context = readContext();
     const name = config.userName;
-    const now = new Date();
-    const dateStr = now.toLocaleDateString("en-GB", {
-        weekday: "long",
-        month: "long",
-        day: "numeric",
-        year: "numeric",
-    });
-    let prompt = `${chatPersona(name)}\n\nToday is ${dateStr}.`;
-    prompt += `\n\n## About ${name}\n`;
-    prompt += context
-        ? context
-        : `(No personal context on file yet. ${name} can edit ~/.plasalid/context.md to add family, income, or other facts.)`;
-    const balances = getAccountBalances(db);
-    if (balances.length > 0) {
-        prompt += `\n\n## Accounts on file\n`;
-        prompt += balances
-            .map((a) => `- ${a.id} | ${a.name} | ${a.type}${a.subtype ? `/${a.subtype}` : ""} | balance ${a.balance.toFixed(2)} ${a.currency}`)
-            .join("\n");
-    }
-    else {
-        prompt += `\n\nNo accounts have been scanned yet. ${name} should drop files into ~/.plasalid/data/ and run \`plasalid scan\`.`;
-    }
-    if (memories.length > 0) {
-        prompt += `\n\n## Things to remember about ${name}\n`;
-        prompt += memories
-            .map((m) => `- [${m.category}] ${stripControls(m.content)}`)
-            .join("\n");
-    }
-    return prompt;
+    return joinSections([
+        chatPersona(name),
+        renderTodayHuman(),
+        renderUserContext(name, readContext()),
+        renderChatChartOrEmpty(db, name),
+        renderMemories(db, {
+            header: `Things to remember about ${name}`,
+            showCategory: true,
+        }),
+    ]);
 }
-const RECONCILE_PERSONA = `You are Plasalid's reconciler. You revisit existing journal entries and accounts to fix data-quality issues: duplicate transactions, mis-categorized lines, inconsistent account naming, missing metadata, sign-convention slips.
-
-Hard rules:
-1. Survey first. Call list_accounts and get_net_worth, then use find_duplicate_entries, find_similar_accounts, and find_unused_accounts to gather candidate issues within the user's requested scope.
-2. For every write you propose, call ask_user with concrete options. Wait for the user's confirmation before applying.
-3. Conservative defaults: when uncertain, save_memory and skip. Never delete without explicit user confirmation. If dry-run is enabled, the write tools will return "Would ..." messages — relay those to the user without further action.
-4. Bookkeeping rules still apply. record_journal_entry must balance. For amount fixes, delete the broken entry and record a fresh replacement.
-5. Stop when there's nothing material left to fix. Call mark_reconcile_done with a short summary (counts of merges/deletes/edits applied).
-
-How to phrase ask_user:
-- Frame each question as a complete sentence with enough context for the user to decide quickly. Include the date, the amount (formatted as ฿N,NNN.NN), the description, and the affected account names.
-- Never reference entries or accounts by their internal id (\`je:…\`, \`a:…\`) in the question. Use the date + description + human account name instead.
-- Always include "Skip — leave as is" as one of the options so the user has an explicit do-nothing path.
-- Example:
-  Avoid: \`prompt: "Merge these?"\`
-  Prefer: \`prompt: "Two ฿350 lunch entries dated 2026-01-15 and 2026-01-17, both posted to KBank Savings ••8745 → Food. Merge into one?"\`, \`options: ["Yes — delete the 01-17 entry", "Yes — delete the 01-15 entry", "Skip — leave as is"]\`
-
-How to write the mark_reconcile_done summary:
-- Write a short user-facing report of what actually changed, in plain language. The user does not know what the internal detectors are.
-- Report counts and actions, never internal grouping. Examples:
-  - "Merged 3 duplicate transactions. Renamed 1 account. No other changes."
-  - "No duplicates found. Skipped 2 unused accounts on your instruction."
-- Never reference internal detector names (\`find_duplicate_entries\`, "Group 1", "Group 1-5", "candidate group N"). Those are tool internals.
-- Keep the summary to one to three sentences. Lead with what was applied; tail with what was skipped or deferred.
-
-Output formatting:
-- Use plain ASCII numbers (\`1.\`, \`2.\`, \`3.\`) for any lists or option numbering you generate. Never use Unicode circled digits (①②③).
-- Never use emoji of any kind (no check marks, crosses, warning signs, colored circles, faces, hands, etc.) — use plain words.
-- Always reply in English.
-- Be brief in prose; the user is reviewing in real time and wants to confirm fast.`;
-export function buildReconcileSystemPrompt(db, opts) {
-    const balances = getAccountBalances(db);
-    const memories = getMemories(db);
-    const today = new Date().toISOString().slice(0, 10);
-    let prompt = `${RECONCILE_PERSONA}\n\nToday is ${today}.\n\n## Current chart of accounts\n`;
-    prompt +=
-        balances.length === 0
-            ? "(empty)"
-            : balances
-                .map((a) => `- ${a.id} | ${a.name} | ${a.type}${a.subtype ? `/${a.subtype}` : ""} | balance ${a.balance.toFixed(2)} ${a.currency}`)
-                .join("\n");
-    prompt += `\n\n## Scope`;
-    prompt += `\n- account: ${opts.accountId ?? "all"}`;
-    prompt += `\n- from: ${opts.from ?? "all time"}`;
-    prompt += `\n- to: ${opts.to ?? "now"}`;
-    prompt += `\n- dry run: ${opts.dryRun ? "yes — write tools will not mutate the DB" : "no — write tools will mutate the DB after confirmation"}`;
-    if (memories.length > 0) {
-        prompt += `\n\n## Saved memories (apply where relevant)\n`;
-        prompt += memories
-            .map((m) => `- [${m.category}] ${stripControls(m.content)}`)
-            .join("\n");
-    }
-    return prompt;
+export function buildReviewSystemPrompt(db, opts) {
+    return joinSections([
+        REVIEW_PERSONA,
+        renderTodayIso(),
+        renderChartOfAccounts(db, { withBalance: true, emptyState: "review" }),
+        renderScope(opts),
+        renderMemories(db, {
+            header: "Rules you've already learned (apply directly; do not re-ask the user)",
+            showCategory: true,
+        }),
+    ]);
 }
 export function buildScanSystemPrompt(db, opts) {
-    const balances = getAccountBalances(db);
-    const memories = getMemories(db);
-    const today = new Date().toISOString().slice(0, 10);
-    let prompt = `${SCAN_PERSONA}\n\nToday is ${today}.\n\n## Current chart of accounts\n`;
-    prompt +=
-        balances.length === 0
-            ? "(empty — you may need to create accounts)"
-            : balances
-                .map((a) => `- ${a.id} | ${a.name} | ${a.type}${a.subtype ? `/${a.subtype}` : ""}`)
-                .join("\n");
-    prompt += `\n\n## File context\nFile: ${opts.fileName}`;
-    prompt += `\n\n## Taxonomy hints\n${getThaiTaxonomyHint()}`;
-    if (memories.length > 0) {
-        prompt += `\n\n## Saved scanning hints (memories)\n`;
-        prompt += memories
-            .filter((m) => m.category === "scanning_hint" || m.category === "general")
-            .map((m) => `- ${stripControls(m.content)}`)
-            .join("\n");
-    }
-    return prompt;
+    return joinSections([
+        SCAN_PERSONA,
+        renderTodayIso(),
+        renderChartOfAccounts(db, { withBalance: false, emptyState: "scan" }),
+        `## File context\nFile: ${opts.fileName}`,
+        `## Taxonomy hints\n${getThaiTaxonomyHint()}`,
+        renderMemories(db, {
+            header: "Rules you've already learned (apply silently before raising a concern)",
+            filterCategories: ["scanning_hint", "general"],
+            showCategory: false,
+        }),
+    ]);
+}
+// ── Composition helper ─────────────────────────────────────────────────────
+/** Drop null/empty sections, join the rest with a blank line. */
+function joinSections(sections) {
+    return sections.filter((s) => !!s).join("\n\n");
 }

package/dist/ai/tools/index.js

@@ -1,23 +1,27 @@
 import { commonTools } from "./common.js";
 import { readTools } from "./read.js";
-import { ingestTools } from "./ingest.js";
+import { scanIngestTools, reviewIngestTools } from "./ingest.js";
 import { scanTools } from "./scan.js";
-import { reconcileTools } from "./reconcile.js";
+import { reviewTools } from "./review.js";
 /**
  * Profile composition. Each profile is the union of one or more tool modules;
  * the dispatcher iterates every module on each tool call so we never need a
  * central switch.
+ *
+ * `scanIngestTools` (create_account / update_account_metadata /
+ * record_journal_entry / note_concern) ships with both scan and review — scan
+ * uses them to post, review uses them to fix.
  */
 const PROFILES = {
-    scan: [commonTools, ingestTools, scanTools],
+    scan: [commonTools, scanIngestTools, scanTools],
     chat: [commonTools, readTools],
-    reconcile: [commonTools, readTools, ingestTools, reconcileTools],
+    review: [commonTools, readTools, scanIngestTools, reviewIngestTools, reviewTools],
 };
 export function getToolDefinitions(profile) {
     return PROFILES[profile].flatMap(m => m.DEFS);
 }
 export async function executeTool(db, name, input, ctx) {
-    for (const mod of [commonTools, readTools, ingestTools, scanTools, reconcileTools]) {
+    for (const mod of [commonTools, readTools, scanIngestTools, reviewIngestTools, scanTools, reviewTools]) {
         const result = await mod.execute(db, name, input, ctx);
         if (result !== undefined)
             return result;
@@ -28,7 +32,8 @@ export async function executeTool(db, name, input, ctx) {
 export const TOOL_LABELS = {
     ...commonTools.LABELS,
     ...readTools.LABELS,
-    ...ingestTools.LABELS,
+    ...scanIngestTools.LABELS,
+    ...reviewIngestTools.LABELS,
     ...scanTools.LABELS,
-    ...reconcileTools.LABELS,
+    ...reviewTools.LABELS,
 };

package/dist/ai/tools/ingest.d.ts

@@ -1,2 +1,3 @@
 import type { ToolModule } from "./types.js";
-export declare const ingestTools: ToolModule;
+export declare const scanIngestTools: ToolModule;
+export declare const reviewIngestTools: ToolModule;

package/dist/ai/tools/ingest.js

@@ -1,10 +1,17 @@
-import { randomUUID } from "crypto";
 import { findAccountById } from "../../db/queries/account_balance.js";
 import { recordJournalEntry } from "../../db/queries/journal.js";
+import { getConcernTarget, recordConcern, resolveConcern, } from "../../db/queries/concerns.js";
+import { runExclusive as runAccountExclusive } from "../../scanner/account_mutex.js";
 import { sanitizeForPrompt } from "../sanitize.js";
-import { ALL_THAI_INSTITUTIONS, ACCOUNT_TYPE_DESCRIPTIONS, } from "../../accounts/taxonomy.js";
+import { ACCOUNT_TYPE_DESCRIPTIONS, } from "../../accounts/taxonomy.js";
 const ACCOUNT_TYPES = Object.keys(ACCOUNT_TYPE_DESCRIPTIONS);
-const DEFS = [
+// ── Scan-side tool definitions ──────────────────────────────────────────────
+// These tools are exposed during both `plasalid scan` and `plasalid review`:
+// scan uses them to post the initial picture; review uses the same primitives
+// to fix mistakes (re-create a botched account, post a corrected entry, etc.).
+// `note_concern` belongs here too — it records a clarification without ever
+// prompting the user, which is what scan needs.
+const SCAN_DEFS = [
     {
         name: "create_account",
         description: "Create a new account in the chart of accounts when a statement reveals one that doesn't exist yet. Use a stable id like 'asset:kbank-savings-1234'.",
@@ -71,29 +78,40 @@ const DEFS = [
         },
     },
     {
-        name: "ask_user",
-        description: "Ask the user a clarifying question when you cannot confidently proceed. The pipeline pauses and prompts the user interactively when running `plasalid scan` or `plasalid reconcile`.",
+        name: "note_concern",
+        description: "Record a clarification request without pausing the run. Use during scan when a row is ambiguous (post your best-guess journal entry first, then call this with the entry's id), when a row is unparseable (skip the entry, call this with no entry_id), or when you have a concern about an account itself (pass account_id). The reviewer picks these up later with the full picture.",
         input_schema: {
             type: "object",
             properties: {
-                prompt: { type: "string", description: "The question to ask in plain language." },
+                prompt: {
+                    type: "string",
+                    description: "The question or concern in a complete sentence, with date, ฿-formatted amount, and human account names. Never reference internal ids.",
+                },
                 options: {
                     type: "array",
-                    description: "Optional list of candidate answers.",
+                    description: "Optional list of candidate answers the reviewer can offer the user.",
                     items: { type: "string" },
                 },
+                entry_id: {
+                    type: "string",
+                    description: "Id of the journal entry this concern relates to (returned by record_journal_entry). Omit for file-level concerns about an unparseable row.",
+                },
+                account_id: {
+                    type: "string",
+                    description: "Id of the account this concern relates to. Set when the statement's bank name, currency, statement_day, due_day, or other metadata disagrees with the stored account, or when you suspect a new account you're about to create duplicates an existing one. Can be combined with entry_id.",
+                },
             },
             required: ["prompt"],
         },
     },
 ];
-const LABELS = {
+const SCAN_LABELS = {
     create_account: "Creating account",
     update_account_metadata: "Updating account metadata",
     record_journal_entry: "Posting journal entry",
-    ask_user: "Asking for clarification",
+    note_concern: "Noting concern",
 };
-async function execute(db, name, input, ctx) {
+async function scanExecute(db, name, input, ctx) {
     switch (name) {
         case "create_account": {
             if (ctx?.dryRun)
@@ -101,102 +119,221 @@ async function execute(db, name, input, ctx) {
             if (!ACCOUNT_TYPES.includes(input.type)) {
                 return `Invalid type "${input.type}". Allowed: ${ACCOUNT_TYPES.join(", ")}.`;
             }
-            const knownCodes = new Set(ALL_THAI_INSTITUTIONS.map(i => i.code));
             const bank = input.bank_name ? String(input.bank_name).toUpperCase() : null;
-            if (bank && !knownCodes.has(bank)) {
-                // Allow unknown institutions; taxonomy is a hint, not a hard list.
-            }
-            try {
-                db.prepare(`INSERT INTO accounts (id, name, type, subtype, bank_name, account_number_masked, currency, due_day, statement_day, metadata_json)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(input.id, input.name, input.type, input.subtype || null, bank, input.account_number_masked || null, input.currency || "THB", input.due_day ?? null, input.statement_day ?? null, input.metadata ? JSON.stringify(input.metadata) : null);
-                return `Account created: ${input.id} (${input.name}, ${input.type}).`;
-            }
-            catch (err) {
-                if (String(err.message).includes("UNIQUE")) {
-                    return `Account "${input.id}" already exists. Use update_account_metadata to modify it.`;
+            // Account writes serialize across concurrent scan agents so the next
+            // list_accounts call (from any agent) sees this row.
+            return await runAccountExclusive(() => {
+                try {
+                    db.prepare(`INSERT INTO accounts (id, name, type, subtype, bank_name, account_number_masked, currency, due_day, statement_day, metadata_json)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(input.id, input.name, input.type, input.subtype || null, bank, input.account_number_masked || null, input.currency || "THB", input.due_day ?? null, input.statement_day ?? null, input.metadata ? JSON.stringify(input.metadata) : null);
+                    return `Account created: ${input.id} (${input.name}, ${input.type}).`;
                 }
-                throw err;
-            }
+                catch (err) {
+                    if (String(err.message).includes("UNIQUE")) {
+                        return `Account "${input.id}" already exists. Use update_account_metadata to modify it.`;
+                    }
+                    throw err;
+                }
+            });
         }
         case "update_account_metadata": {
             if (ctx?.dryRun)
                 return `Would update metadata for ${input.account_id}: ${JSON.stringify(input)}`;
-            const acct = findAccountById(db, input.account_id);
-            if (!acct)
-                return `Account "${input.account_id}" not found.`;
-            const updates = [];
-            const params = [];
-            if (input.due_day !== undefined) {
-                updates.push("due_day = ?");
-                params.push(input.due_day);
-            }
-            if (input.statement_day !== undefined) {
-                updates.push("statement_day = ?");
-                params.push(input.statement_day);
-            }
-            if (input.points_balance !== undefined) {
-                updates.push("points_balance = ?");
-                params.push(input.points_balance);
-            }
-            if (input.account_number_masked !== undefined) {
-                updates.push("account_number_masked = ?");
-                params.push(input.account_number_masked);
-            }
-            if (input.bank_name !== undefined) {
-                updates.push("bank_name = ?");
-                params.push(String(input.bank_name).toUpperCase());
-            }
-            if (input.metadata) {
-                const existing = acct.metadata_json ? JSON.parse(acct.metadata_json) : {};
-                const merged = { ...existing, ...input.metadata };
-                updates.push("metadata_json = ?");
-                params.push(JSON.stringify(merged));
-            }
-            if (updates.length === 0)
-                return "Nothing to update.";
-            params.push(input.account_id);
-            db.prepare(`UPDATE accounts SET ${updates.join(", ")} WHERE id = ?`).run(...params);
-            return `Updated ${input.account_id}.`;
+            return await runAccountExclusive(() => {
+                const acct = findAccountById(db, input.account_id);
+                if (!acct)
+                    return `Account "${input.account_id}" not found.`;
+                const updates = [];
+                const params = [];
+                if (input.due_day !== undefined) {
+                    updates.push("due_day = ?");
+                    params.push(input.due_day);
+                }
+                if (input.statement_day !== undefined) {
+                    updates.push("statement_day = ?");
+                    params.push(input.statement_day);
+                }
+                if (input.points_balance !== undefined) {
+                    updates.push("points_balance = ?");
+                    params.push(input.points_balance);
+                }
+                if (input.account_number_masked !== undefined) {
+                    updates.push("account_number_masked = ?");
+                    params.push(input.account_number_masked);
+                }
+                if (input.bank_name !== undefined) {
+                    updates.push("bank_name = ?");
+                    params.push(String(input.bank_name).toUpperCase());
+                }
+                if (input.metadata) {
+                    const existing = acct.metadata_json ? JSON.parse(acct.metadata_json) : {};
+                    const merged = { ...existing, ...input.metadata };
+                    updates.push("metadata_json = ?");
+                    params.push(JSON.stringify(merged));
+                }
+                if (updates.length === 0)
+                    return "Nothing to update.";
+                params.push(input.account_id);
+                db.prepare(`UPDATE accounts SET ${updates.join(", ")} WHERE id = ?`).run(...params);
+                return `Updated ${input.account_id}.`;
+            });
         }
         case "record_journal_entry": {
             if (!ctx)
                 return "record_journal_entry is only available inside an agent session.";
             if (ctx.dryRun)
                 return `Would post journal entry "${input.description}" on ${input.date}.`;
+            const entryInput = {
+                date: input.date,
+                description: input.description,
+                source_file_id: ctx.fileId,
+                source_page: input.source_page ?? null,
+                lines: (input.lines || []).map((l) => ({
+                    account_id: l.account_id,
+                    debit: l.debit ?? 0,
+                    credit: l.credit ?? 0,
+                    currency: l.currency || "THB",
+                    memo: l.memo ?? null,
+                })),
+            };
             try {
-                const entryId = recordJournalEntry(db, {
-                    date: input.date,
-                    description: input.description,
-                    source_file_id: ctx.fileId,
-                    source_page: input.source_page ?? null,
-                    lines: (input.lines || []).map((l) => ({
-                        account_id: l.account_id,
-                        debit: l.debit ?? 0,
-                        credit: l.credit ?? 0,
-                        currency: l.currency || "THB",
-                        memo: l.memo ?? null,
-                    })),
-                });
+                const entryId = ctx.buffer
+                    ? ctx.buffer.appendEntry(entryInput)
+                    : recordJournalEntry(db, entryInput);
                 return `Posted journal entry ${entryId} (${input.date}).`;
             }
             catch (err) {
                 return `Could not post journal entry: ${err.message}`;
             }
         }
-        case "ask_user": {
+        case "note_concern": {
             if (!ctx)
-                return "ask_user is only available inside an agent session.";
-            const id = `pq:${randomUUID()}`;
-            db.prepare(`INSERT INTO pending_questions (id, file_id, prompt, options_json) VALUES (?, ?, ?, ?)`).run(id, ctx.fileId ?? null, input.prompt, input.options ? JSON.stringify(input.options) : null);
-            if (ctx.interactive && ctx.promptUser) {
-                const answer = await ctx.promptUser(input.prompt, input.options);
-                db.prepare(`UPDATE pending_questions SET answer = ?, resolved_at = datetime('now') WHERE id = ?`).run(answer, id);
-                return `User answered: ${sanitizeForPrompt(answer)}`;
+                return "note_concern is only available inside an agent session.";
+            const target = {
+                entry_id: input.entry_id ?? null,
+                account_id: input.account_id ?? null,
+            };
+            if (ctx.buffer) {
+                ctx.buffer.appendConcern({ ...target, prompt: input.prompt, options: input.options });
+                return `Concern noted (buffered). Continue with the next row.`;
             }
-            return `Question recorded for later (${id}). Awaiting user input — do not act on assumptions about this answer.`;
+            const id = recordConcern(db, {
+                file_id: ctx.fileId ?? null,
+                entry_id: target.entry_id,
+                account_id: target.account_id,
+                prompt: input.prompt,
+                options: input.options,
+            });
+            return `Concern noted (${id}). Continue with the next row.`;
         }
         default:
             return undefined;
     }
 }
-export const ingestTools = { DEFS, LABELS, execute };
+export const scanIngestTools = {
+    DEFS: SCAN_DEFS,
+    LABELS: SCAN_LABELS,
+    execute: scanExecute,
+};
+// ── Review-only tool definitions ────────────────────────────────────────────
+// `ask_user` is the only interactive primitive. Scan never reaches it (the
+// scan profile doesn't include this module), so we don't need a "scan, please
+// don't use this" guard.
+const REVIEW_DEFS = [
+    {
+        name: "ask_user",
+        description: "Ask the user a clarifying question when you cannot confidently proceed. The pipeline pauses and prompts the user interactively. Available during `plasalid review`. Not exposed during `plasalid scan` — use `note_concern` instead. Pass `entry_id` / `account_id` to attach the question to the same target as a scan-noted concern. Pass `concern_id` to resolve an existing open concern in place (recommended when re-posing a scan-noted concern to the user). Pass `related_concern_ids` to apply the user's single answer to a whole group of sibling concerns at once.",
+        input_schema: {
+            type: "object",
+            properties: {
+                prompt: { type: "string", description: "The question to ask in plain language." },
+                options: {
+                    type: "array",
+                    description: "Optional list of candidate answers.",
+                    items: { type: "string" },
+                },
+                entry_id: {
+                    type: "string",
+                    description: "Optional: journal entry this question is about. Used to clear the entry's has_concern flag once all its concerns close.",
+                },
+                account_id: {
+                    type: "string",
+                    description: "Optional: account this question is about. Used to clear the account's has_concern flag once all its concerns close.",
+                },
+                concern_id: {
+                    type: "string",
+                    description: "Optional: id of an existing open concern. If supplied, the user's answer resolves that row in place instead of creating a new one.",
+                },
+                related_concern_ids: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional: ids of additional open concerns that share the same answer as `concern_id`. The user is prompted once; every listed concern (plus the primary) is marked resolved with the same answer. Use this for grouping duplicate questions — e.g., 12 Lazada rows that all categorize the same way — so the user isn't asked the same thing twelve times.",
+                },
+                facts: {
+                    type: "object",
+                    description: "Optional structured highlights rendered as a single colored header line above the question. Provide whichever fields apply; the prompter colorizes each by category (amount=yellow, date=cyan, merchant=green, accounts=magenta). Keep the `prompt` text short — the facts header carries the context.",
+                    properties: {
+                        amount: { type: "string", description: "฿-formatted amount, e.g. '฿1,200.00'." },
+                        date: { type: "string", description: "ISO date or short range, e.g. '2026-04-15' or '2026-02-15 to 2026-05-15'." },
+                        merchant: { type: "string", description: "Counterparty / merchant name, e.g. 'LAZADA TH', 'Spotify'." },
+                        accounts: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Human account names involved. For merges, list the survivor first.",
+                        },
+                    },
+                },
+            },
+            required: ["prompt"],
+        },
+    },
+];
+const REVIEW_LABELS = {
+    ask_user: "Asking for clarification",
+};
+async function reviewExecute(db, name, input, ctx) {
+    if (name !== "ask_user")
+        return undefined;
+    if (!ctx)
+        return "ask_user is only available inside an agent session.";
+    // Two modes: resolve an existing concern in place (concern_id supplied),
+    // or post a fresh question that becomes its own concerns row.
+    let id;
+    if (input.concern_id) {
+        id = String(input.concern_id);
+        if (!getConcernTarget(db, id))
+            return `Concern ${id} not found.`;
+    }
+    else {
+        id = recordConcern(db, {
+            file_id: ctx.fileId ?? null,
+            entry_id: input.entry_id ?? null,
+            account_id: input.account_id ?? null,
+            prompt: input.prompt,
+            options: input.options,
+        });
+    }
+    if (ctx.interactive && ctx.promptUser) {
+        const answer = await ctx.promptUser(input.prompt, input.options, input.facts);
+        resolveConcern(db, id, answer);
+        // Propagate the same answer to every sibling in the group so the user
+        // isn't asked the same thing again. Skip the primary id if the agent
+        // happened to include it.
+        const siblings = Array.isArray(input.related_concern_ids) ? input.related_concern_ids : [];
+        let propagated = 0;
+        for (const sibId of siblings) {
+            if (sibId === id)
+                continue;
+            if (resolveConcern(db, String(sibId), answer))
+                propagated++;
+        }
+        const totalResolved = 1 + propagated;
+        return `User answered: ${sanitizeForPrompt(answer)}${totalResolved > 1 ? ` (applied to ${totalResolved} concern${totalResolved === 1 ? "" : "s"})` : ""}`;
+    }
+    return `Question recorded for later (${id}). Awaiting user input — do not act on assumptions about this answer.`;
+}
+export const reviewIngestTools = {
+    DEFS: REVIEW_DEFS,
+    LABELS: REVIEW_LABELS,
+    execute: reviewExecute,
+};