plasalid 0.7.2 → 0.7.3

package/dist/ai/tools/ingest.js

@@ -414,7 +414,7 @@ export const accountIngestTools = {
 const QUESTION_DEFS = [
     {
         name: "note_question",
-        description: "Record a clarification question without pausing the run. Use SPARINGLY during scan — best-guess expense categorization is preferred (small misses are cheap to fix; a flood of questions is not). Call note_question only when (a) the row is unparseable (skip the row, no transaction_id), (b) you have a doubt about an account itself (pass account_id), or (c) the amount/sign/date/counter-party is genuinely unclear (post your best-guess transaction first, then call this with the transaction_id). Use kind='uncategorized_expense' only for genuinely opaque expense descriptors that landed in expense:uncategorized. The resolver picks these up later with the full picture.",
+        description: "Record a clarification question without pausing the run. Use SPARINGLY during scan — best-guess expense categorization is preferred (small misses are cheap to fix; a flood of questions is not). Call note_question only when (a) the row is unparseable (skip the row, no transaction_id), (b) you have a doubt about an account itself (pass account_id), or (c) the amount/sign/date/counter-party is genuinely unclear (post your best-guess transaction first, then call this with the transaction_id). Use kind='uncategorized_expense' only for genuinely opaque expense descriptors that landed in expense:uncategorized. The clarifier picks these up later with the full picture.",
         input_schema: {
             type: "object",
             properties: {
@@ -424,11 +424,11 @@ const QUESTION_DEFS = [
                 },
                 kind: {
                     type: "string",
-                    description: "Optional category for the question. Use 'uncategorized_expense' when the posting landed in expense:uncategorized; the resolver batches these into one cleanup pass.",
+                    description: "Optional category for the question. Use 'uncategorized_expense' when the posting landed in expense:uncategorized; the clarifier batches these into one cleanup pass.",
                 },
                 options: {
                     type: "array",
-                    description: "Optional list of candidate answers the resolver can offer the user.",
+                    description: "Optional list of candidate answers the clarifier can offer the user.",
                     items: { type: "string" },
                 },
                 transaction_id: {
@@ -474,7 +474,7 @@ export const scanQuestionTools = {
 const RESOLVE_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 resolve`. Not exposed during `plasalid scan` — use `note_question` instead. Pass `question_id` to close an existing question in place. Pass `related_question_ids` to apply the user's single answer to a whole group of sibling questions at once.",
+        description: "Ask the user a clarifying question when you cannot confidently proceed. The pipeline pauses and prompts the user interactively. Available during `plasalid clarify`. Not exposed during `plasalid scan` — use `note_question` instead. Pass `question_id` to close an existing question in place. Pass `related_question_ids` to apply the user's single answer to a whole group of sibling questions at once.",
         input_schema: {
             type: "object",
             properties: {
@@ -489,7 +489,7 @@ const RESOLVE_DEFS = [
                 },
                 question_id: {
                     type: "string",
-                    description: "Id of the primary question this resolves. The user's answer closes (deletes) that row.",
+                    description: "Id of the primary question this clarifies. The user's answer closes (deletes) that row.",
                 },
                 related_question_ids: {
                     type: "array",
@@ -534,7 +534,7 @@ const RESOLVE_LABELS = {
     ask_user: "Asking for clarification",
     close_question: "Closing question",
 };
-async function resolveIngestExecute(db, name, input, ctx) {
+async function clarifyIngestExecute(db, name, input, ctx) {
     if (name === "close_question")
         return closeQuestionTool(db, input, ctx);
     if (name !== "ask_user")
@@ -590,8 +590,8 @@ async function closeQuestionTool(db, input, ctx) {
     }
     return `Closed ${count} question${count === 1 ? "" : "s"}.`;
 }
-export const resolveIngestTools = {
+export const clarifyIngestTools = {
     DEFS: RESOLVE_DEFS,
     LABELS: RESOLVE_LABELS,
-    execute: resolveIngestExecute,
+    execute: clarifyIngestExecute,
 };

package/dist/ai/tools/read.js

@@ -63,7 +63,7 @@ const DEFS = [
     },
     {
         name: "list_questions",
-        description: "List clarification questions recorded by the scanner that have not been resolved yet. Each row carries the prompt, optional candidate answers, and the file/transaction/account it was attached to. The resolver uses this to drive the step-by-step clarification loop.",
+        description: "List clarification questions recorded by the scanner that have not been resolved yet. Each row carries the prompt, optional candidate answers, and the file/transaction/account it was attached to. The clarifier uses this to drive the step-by-step clarification loop.",
         input_schema: {
             type: "object",
             properties: {

package/dist/ai/tools/record.js

@@ -77,8 +77,8 @@ const DEFS = [
         },
     },
     {
-        name: "clarify",
-        description: "Ask the user a clarifying question and return their answer as a string. Use when the utterance is ambiguous (multiple matching accounts, missing amount, unclear date, can't tell expense vs transfer, plan confirmation before a multi-step action). Unlike resolve's ask_user, this does NOT write to the questions table — record-time questions are transient.",
+        name: "confirm",
+        description: "Ask the user to confirm or pick an option and return their answer as a string. Use when the utterance is ambiguous (multiple matching accounts, missing amount, unclear date, can't tell expense vs transfer, plan confirmation before a multi-step action). Unlike clarify's ask_user, this does NOT write to the questions table — record-time questions are transient.",
         input_schema: {
             type: "object",
             properties: {
@@ -111,7 +111,7 @@ const LABELS = {
     adjust_account_balance: "Adjusting balance",
     rename_account: "Renaming account",
     delete_account: "Deleting account",
-    clarify: "Asking for clarification",
+    confirm: "Asking for confirmation",
 };
 async function execute(db, name, input, ctx) {
     switch (name) {
@@ -141,9 +141,9 @@ async function execute(db, name, input, ctx) {
                 return `Could not delete: ${err.message}`;
             }
         }
-        case "clarify": {
+        case "confirm": {
             if (!ctx)
-                return "clarify is only available inside an agent session.";
+                return "confirm is only available inside an agent session.";
             if (!ctx.interactive || !ctx.promptUser) {
                 return `Awaiting user input — cannot proceed in non-interactive mode. Question was: ${sanitizeForPrompt(input.prompt)}`;
             }

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

@@ -2,7 +2,7 @@ import type Database from "libsql";
 import type { ToolDefinition } from "../provider.js";
 import type { ScanProgress } from "../../scanner/progress.js";
 import type { ClosedQuestion } from "../../db/queries/questions.js";
-export type ToolProfile = "scan" | "chat" | "record" | "resolve";
+export type ToolProfile = "scan" | "chat" | "record" | "clarify";
 /**
  * Structured highlights an interactive agent can pass to ask_user. The prompter
  * renders them as a single colored header line above the question (each
@@ -30,7 +30,7 @@ export interface AgentExecutionContext {
     progress?: ScanProgress;
     /** Scan-only: the chunk this agent invocation is processing. */
     chunkId?: string;
-    /** Resolve-only: notified for each closed question so the caller can synthesize memory rules. */
+    /** Clarify-only: notified for each closed question so the caller can synthesize memory rules. */
     onQuestionClosed?: (closed: ClosedQuestion) => void;
 }
 /**

package/dist/cli/commands/clarify.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Zero-arg clarifier. Hands every question to the clarifier (deterministic
+ * passes first, then the LLM agent) and prints a colored summary on completion.
+ */
+export declare function runClarifyCommand(): Promise<void>;

package/dist/cli/commands/clarify.js

@@ -0,0 +1,44 @@
+import chalk from "chalk";
+import { getDb } from "../../db/connection.js";
+import { runClarify } from "../../scanner/clarifier.js";
+import { makePromptUser, makeAgentOnProgress, statusSpinner } from "../ux.js";
+/**
+ * Zero-arg clarifier. Hands every question to the clarifier (deterministic
+ * passes first, then the LLM agent) and prints a colored summary on completion.
+ */
+export async function runClarifyCommand() {
+    const db = getDb();
+    const spinner = statusSpinner("Clarifying...");
+    const promptUser = makePromptUser(spinner);
+    const onProgress = makeAgentOnProgress(spinner);
+    try {
+        const summary = await runClarify({
+            db,
+            interactive: !!process.stdout.isTTY,
+            promptUser,
+            onProgress,
+        });
+        spinner.succeed("Clarify done.");
+        console.log("");
+        console.log(formatSummary(summary));
+    }
+    catch (err) {
+        spinner.fail(err instanceof Error ? err.message : "Clarify failed.");
+        process.exitCode = 1;
+    }
+}
+function formatSummary(summary) {
+    if (summary.total === 0) {
+        return chalk.dim("No questions.");
+    }
+    const tally = Object.entries(summary.tally)
+        .map(([k, v]) => `${k}×${v}`)
+        .join(", ");
+    const lines = [
+        chalk.bold(`Clarified ${summary.clarified}/${summary.total} questions${tally ? ` (${tally})` : ""}.`),
+    ];
+    if (summary.remaining > 0) {
+        lines.push(chalk.yellow(`${summary.remaining} question(s) remain.`));
+    }
+    return lines.join("\n");
+}

package/dist/cli/commands/rules.js

@@ -29,7 +29,7 @@ export function renderRules(db) {
     const rules = collectRules(db);
     if (rules.length === 0) {
         return ("No rules yet.\n\n" +
-            chalk.dim("Rules accumulate as you resolve questions. Run `plasalid resolve` after a scan."));
+            chalk.dim("Rules accumulate as you clarify questions. Run `plasalid clarify` after a scan."));
     }
     const width = Math.max(...rules.map((r) => r.displayId.length));
     const lines = [chalk.bold(`Rules (${rules.length}):`)];

package/dist/cli/commands/scan.js

@@ -99,10 +99,10 @@ async function buildTtyHooks() {
             unsubscribeProgress?.();
             unsubscribeProgress = null;
         },
-        beforeResolve: () => {
-            controller.publish({ type: "phase-set", phase: "resolve" });
+        beforeClarify: () => {
+            controller.publish({ type: "phase-set", phase: "clarify" });
         },
-        afterResolve: () => {
+        afterClarify: () => {
             controller.publish({ type: "phase-set", phase: "done" });
             inkInstance?.unmount();
             inkInstance = null;
@@ -191,8 +191,8 @@ function buildPlainHooks() {
             unsubscribeProgress?.();
             unsubscribeProgress = null;
         },
-        beforeResolve: () => {
-            console.log("Resolving...");
+        beforeClarify: () => {
+            console.log("Clarifying...");
         },
     };
 }
@@ -200,11 +200,11 @@ function renderSummary(state) {
     console.log("");
     const txCount = countTransactions(state);
     console.log(chalk.bold(`Scanned ${state.decrypted.length} file(s) → ${txCount} transactions.`));
-    const r = state.resolveSummary;
+    const r = state.clarifySummary;
     if (r && r.total > 0) {
-        console.log(`Resolved ${r.resolved}/${r.total} questions.`);
+        console.log(`Clarified ${r.clarified}/${r.total} questions.`);
         if (r.remaining > 0) {
-            console.log(chalk.yellow(`${r.remaining} question(s) remain — run ${chalk.cyan("plasalid resolve")} to finish them.`));
+            console.log(chalk.yellow(`${r.remaining} question(s) remain — run ${chalk.cyan("plasalid clarify")} to finish them.`));
         }
     }
     if (state.errors.length > 0) {
@@ -215,7 +215,7 @@ function renderSummary(state) {
     }
     if (txCount > 0) {
         console.log("");
-        console.log(chalk.dim(`Next: run ${chalk.cyan("plasalid")} to chat with your ledger about what just landed.`));
+        console.log(`Next: run ${chalk.cyan("plasalid")} to chat with your ledger about what just landed.`);
     }
 }
 /**

package/dist/cli/commands/status.js

@@ -67,7 +67,7 @@ function systemRows(db) {
         rows.push({
             label: "Questions",
             value: chalk.yellow(formatInteger(questions)),
-            suffix: chalk.dim("run `plasalid resolve`"),
+            suffix: chalk.dim("run `plasalid clarify`"),
         });
     }
     return rows;

package/dist/cli/index.js

@@ -135,12 +135,12 @@ program
     forgetRule(regex);
 });
 program
-    .command("resolve")
-    .description("Resolve every question across the ledger")
+    .command("clarify")
+    .description("Clarify every question across the ledger")
     .action(async () => {
     ensureConfigured();
-    const { runResolveCommand } = await import("./commands/resolve.js");
-    await runResolveCommand();
+    const { runClarifyCommand } = await import("./commands/clarify.js");
+    await runClarifyCommand();
 });
 program.configureHelp({
     formatHelp: () => helpScreen([
@@ -175,8 +175,8 @@ program.configureHelp({
             desc: "Delete learned rules whose ids match <regex> (anchored)",
         },
         {
-            name: "resolve",
-            desc: "Resolve every question across the ledger",
+            name: "clarify",
+            desc: "Clarify every question across the ledger",
         },
     ]),
 });

package/dist/cli/ink/ScanDashboard.d.ts

@@ -2,7 +2,7 @@
  * Events the CLI publishes into the dashboard. The CLI subscribes to the
  * scanner's ScanProgress sink and routes per-chunk ticks here via chunkLookup.
  */
-export type CurrentPhase = "parse" | "resolve" | "done";
+export type CurrentPhase = "parse" | "clarify" | "done";
 export type DashboardEvent = {
     type: "chunk-start";
     fileId: string;

package/dist/cli/ink/ScanDashboard.js

@@ -66,7 +66,7 @@ const PHASE_RENDER = {
     running: (label) => _jsxs(Text, { color: "yellow", children: [_jsx(Spinner, { type: "dots" }), " ", label] }),
     done: (label) => _jsxs(Text, { color: "green", children: ["\u2713 ", label] }),
 };
-const PHASE_ORDER = ["parse", "resolve", "done"];
+const PHASE_ORDER = ["parse", "clarify", "done"];
 function phaseStateOf(label, current) {
     const li = PHASE_ORDER.indexOf(label);
     const ci = PHASE_ORDER.indexOf(current);
@@ -77,7 +77,7 @@ function phaseStateOf(label, current) {
     return "pending";
 }
 function Header({ phase }) {
-    return (_jsxs(Text, { children: [_jsx(Text, { bold: true, children: "Scanner" }), _jsx(Text, { dimColor: true, children: "  ·  " }), _jsx(Text, { color: "green", children: "\u2713 decrypt" }), _jsx(Text, { dimColor: true, children: " -> " }), _jsx(Text, { color: "green", children: "\u2713 chunk" }), _jsx(Text, { dimColor: true, children: " -> " }), PHASE_RENDER[phaseStateOf("parse", phase)]("parse"), _jsx(Text, { dimColor: true, children: " -> " }), PHASE_RENDER[phaseStateOf("resolve", phase)]("resolve")] }));
+    return (_jsxs(Text, { children: [_jsx(Text, { bold: true, children: "Scanner" }), _jsx(Text, { dimColor: true, children: "  ·  " }), _jsx(Text, { color: "green", children: "\u2713 decrypt" }), _jsx(Text, { dimColor: true, children: " -> " }), _jsx(Text, { color: "green", children: "\u2713 chunk" }), _jsx(Text, { dimColor: true, children: " -> " }), PHASE_RENDER[phaseStateOf("parse", phase)]("parse"), _jsx(Text, { dimColor: true, children: " -> " }), PHASE_RENDER[phaseStateOf("clarify", phase)]("clarify")] }));
 }
 function ColumnHeader() {
     return (_jsxs(Box, { flexDirection: "row", children: [_jsx(Box, { width: COL.status, children: _jsx(Text, { dimColor: true, children: "status" }) }), _jsx(Box, { width: COL.files, children: _jsx(Text, { dimColor: true, children: "files" }) }), _jsx(Box, { width: COL.transactions, children: _jsx(Text, { dimColor: true, children: "transactions" }) }), _jsx(Box, { width: COL.questions, children: _jsx(Text, { dimColor: true, children: "questions" }) })] }));

package/dist/cli/setup.js

@@ -36,7 +36,7 @@ function printSummary(dataDir) {
     console.log("Next steps:");
     console.log(`  1. Run ${chalk.cyan("plasalid data")} to drop your bank / credit-card statement PDFs in.`);
     console.log(`  2. Run ${chalk.cyan("plasalid scan")} to parse them.`);
-    console.log(`  3. Run ${chalk.cyan("plasalid resolve")} to work through anything the scanner flagged.`);
+    console.log(`  3. Run ${chalk.cyan("plasalid clarify")} to work through anything the scanner flagged.`);
     console.log(`  4. Run ${chalk.cyan("plasalid")} to chat with your money.`);
     console.log("");
     console.log(chalk.dim(`  Optional: ${chalk.cyan(`plasalid record "..."`)}${chalk.dim(" to record manual/undocumented transaction, balance, or account at any time.")}`));

package/dist/cli/ux.js

@@ -139,7 +139,7 @@ export function makeAgentOnProgress(spinner, subject) {
     };
 }
 /**
- * Render the structured facts the resolve agent attaches to ask_user as a
+ * Render the structured facts the clarify agent attaches to ask_user as a
  * single colored line above the inquirer prompt. Each category has a fixed
  * chalk color so the user's eye picks out the type without reading prose.
  * Returns null when there's nothing to render (so the caller can skip the

package/dist/scanner/clarifier-memory.d.ts

@@ -0,0 +1,8 @@
+import type Database from "libsql";
+import type { ClosedQuestion } from "../db/queries/questions.js";
+/**
+ * Compact every closed question into a memories row (category `scanning_hint`).
+ * The next scan's deterministic memoryRulePass picks them up. Dedups on body —
+ * an identical rule for the same kind + prompt won't be re-inserted.
+ */
+export declare function synthesizeMemoryRules(db: Database.Database, closures: readonly ClosedQuestion[]): number;

package/dist/scanner/clarifier-memory.js

@@ -0,0 +1,24 @@
+/**
+ * Compact every closed question into a memories row (category `scanning_hint`).
+ * The next scan's deterministic memoryRulePass picks them up. Dedups on body —
+ * an identical rule for the same kind + prompt won't be re-inserted.
+ */
+export function synthesizeMemoryRules(db, closures) {
+    if (closures.length === 0)
+        return 0;
+    let inserted = 0;
+    const exists = db.prepare(`SELECT 1 FROM memories WHERE category = ? AND content = ? LIMIT 1`);
+    const insert = db.prepare(`INSERT INTO memories (content, category) VALUES (?, ?)`);
+    for (const c of closures) {
+        const body = formatRule(c);
+        if (exists.get("scanning_hint", body))
+            continue;
+        insert.run(body, "scanning_hint");
+        inserted++;
+    }
+    return inserted;
+}
+function formatRule(c) {
+    const kindLabel = c.kind ?? "general";
+    return `[${kindLabel}] ${c.prompt.replace(/\s+/g, " ").trim()} -> ${c.answer.trim()}`;
+}

package/dist/scanner/clarifier.d.ts

@@ -0,0 +1,39 @@
+import type Database from "libsql";
+import { type QuestionRow } from "../db/queries/questions.js";
+export interface ClarifierContext {
+    readonly db: Database.Database;
+    readonly tally: Record<string, number>;
+}
+export interface ClarifierPass {
+    readonly name: string;
+    readonly kinds: readonly string[];
+    /** Try to close one question. Returns the answer if closed, else null. */
+    tryResolve(u: QuestionRow, ctx: ClarifierContext): Promise<string | null>;
+}
+export interface ClarifySummary {
+    readonly total: number;
+    readonly clarified: number;
+    readonly remaining: number;
+    readonly tally: Readonly<Record<string, number>>;
+}
+export interface RunClarifyOpts {
+    db: Database.Database;
+    /** Narrows to a single scan's questions. Omit = every question. */
+    scanId?: string;
+    interactive?: boolean;
+    promptUser?: (prompt: string, options?: string[], facts?: any) => Promise<string>;
+    onProgress?: (event: {
+        phase: "tool" | "responding";
+        toolName?: string;
+        toolCount: number;
+        elapsedMs: number;
+    }) => void;
+}
+export declare const CLARIFIER_PASSES: readonly ClarifierPass[];
+/**
+ * Single entry point shared by the in-scan resolve phase and the standalone
+ * `plasalid clarify` command. Runs deterministic passes first, then (when
+ * interactive) hands the leftovers to the LLM clarifier agent. Closed
+ * questions get compacted into scanning_hint memories.
+ */
+export declare function runClarify(opts: RunClarifyOpts): Promise<ClarifySummary>;

package/dist/scanner/clarifier.js

@@ -0,0 +1,196 @@
+import { closeQuestion, listQuestions, countQuestions, } from "../db/queries/questions.js";
+import { updatePosting } from "../db/queries/transactions.js";
+import { runClarifyAgent } from "../ai/agent.js";
+import { synthesizeMemoryRules } from "./clarifier-memory.js";
+import { converge } from "./converge.js";
+const MAX_AGENT_PASSES = 3;
+/**
+ * Apply deterministic passes via memory_rules lookups. Closes any question
+ * whose prompt has a stored scanning_hint that already encodes the answer.
+ */
+const memoryRulePass = {
+    name: "memory_rule",
+    kinds: ["uncategorized", "uncategorized_expense", "duplicate", "correlation", "recurrence_candidate", "similar_accounts", "boundary_continuation", "scan_truncated", "scan_commit_failure"],
+    async tryResolve(u, ctx) {
+        const rules = ctx.db
+            .prepare(`SELECT content FROM memories WHERE category = 'scanning_hint'`)
+            .all();
+        const key = canonicalKey(u);
+        for (const r of rules) {
+            const match = parseRule(r.content);
+            if (!match)
+                continue;
+            if (match.key === key)
+                return match.answer;
+        }
+        return null;
+    },
+};
+/**
+ * For an uncategorized expense whose transaction has a merchant with a
+ * stored default_account_id, apply the default to every expense posting on
+ * that transaction.
+ */
+const merchantDefaultPass = {
+    name: "merchant_default",
+    kinds: ["uncategorized_expense"],
+    async tryResolve(u, ctx) {
+        if (!u.transaction_id)
+            return null;
+        const tx = ctx.db
+            .prepare(`SELECT merchant_id FROM transactions WHERE id = ?`)
+            .get(u.transaction_id);
+        if (!tx?.merchant_id)
+            return null;
+        const merchant = ctx.db
+            .prepare(`SELECT default_account_id FROM merchants WHERE id = ?`)
+            .get(tx.merchant_id);
+        const target = merchant?.default_account_id;
+        if (!target)
+            return null;
+        const postings = ctx.db
+            .prepare(`SELECT p.id FROM postings p
+         JOIN accounts a ON a.id = p.account_id
+         WHERE p.transaction_id = ? AND a.id = 'expense:uncategorized'`)
+            .all(u.transaction_id);
+        if (postings.length === 0)
+            return null;
+        for (const p of postings) {
+            updatePosting(ctx.db, p.id, { account_id: target });
+        }
+        return target;
+    },
+};
+export const CLARIFIER_PASSES = [
+    memoryRulePass,
+    merchantDefaultPass,
+];
+/**
+ * Single entry point shared by the in-scan resolve phase and the standalone
+ * `plasalid clarify` command. Runs deterministic passes first, then (when
+ * interactive) hands the leftovers to the LLM clarifier agent. Closed
+ * questions get compacted into scanning_hint memories.
+ */
+export async function runClarify(opts) {
+    const { db } = opts;
+    const tally = {};
+    const closures = [];
+    const initial = listQuestions(db, { scanId: opts.scanId, limit: 1000 });
+    const total = initial.length;
+    if (total === 0) {
+        return { total: 0, clarified: 0, remaining: 0, tally };
+    }
+    for (const u of initial) {
+        const passes = matchingPasses(u);
+        if (passes.length === 0)
+            continue;
+        const result = await tryPasses(u, passes, { db, tally });
+        if (!result)
+            continue;
+        const closed = closeQuestion(db, u.id, result.answer);
+        if (!closed)
+            continue;
+        closures.push(closed);
+        tally[result.passName] = (tally[result.passName] ?? 0) + 1;
+    }
+    const interactive = opts.interactive ?? true;
+    if (interactive && countRemaining(db, opts.scanId) > 0) {
+        await runAgentLoop(opts, closures, tally);
+    }
+    synthesizeMemoryRules(db, closures);
+    const remaining = countRemaining(db, opts.scanId);
+    return { total, clarified: total - remaining, remaining, tally };
+}
+function matchingPasses(u) {
+    if (!u.kind)
+        return [];
+    return CLARIFIER_PASSES.filter(p => p.kinds.includes(u.kind));
+}
+async function tryPasses(u, passes, ctx) {
+    for (const pass of passes) {
+        let answer;
+        try {
+            answer = await pass.tryResolve(u, ctx);
+        }
+        catch (err) {
+            console.error(`[clarifier pass ${pass.name}] ${err instanceof Error ? err.message : String(err)}`);
+            answer = null;
+        }
+        if (answer != null)
+            return { passName: pass.name, answer };
+    }
+    return null;
+}
+function countRemaining(db, scanId) {
+    return scanId ? countQuestions(db, { scan_id: scanId }) : countQuestions(db);
+}
+/**
+ * Stall-protected outer loop around the LLM clarifier. Each pass re-fetches
+ * leftover questions, hands them to the agent, and the agent closes what it
+ * can via close_question / ask_user. The loop stops when nothing closes
+ * between passes. After each pass we diff the pre/post set to recover the
+ * (prompt, kind, answer) tuples the agent closed without going through the
+ * memoryRulePass path.
+ */
+async function runAgentLoop(opts, closures, tally) {
+    const { db } = opts;
+    await converge({
+        initial: countRemaining(db, opts.scanId),
+        maxAttempts: MAX_AGENT_PASSES,
+        isDone: (n) => n === 0,
+        isStalled: (curr, prev) => curr >= prev,
+        onPass: async () => {
+            const before = listQuestions(db, { scanId: opts.scanId, limit: 1000 });
+            if (before.length === 0)
+                return 0;
+            await runClarifyAgent({
+                db,
+                prompt: {},
+                initialMessages: [{ role: "user", content: buildResolveUserMessage(before) }],
+                agentCtx: {
+                    interactive: true,
+                    promptUser: opts.promptUser,
+                    onQuestionClosed: (closed) => {
+                        closures.push(closed);
+                        tally["agent_clarification"] = (tally["agent_clarification"] ?? 0) + 1;
+                    },
+                },
+                onProgress: opts.onProgress,
+            });
+            return countRemaining(db, opts.scanId);
+        },
+    });
+}
+function buildResolveUserMessage(questions) {
+    const lines = [`${questions.length} question(s) to resolve.`, ``, `Questions:`];
+    for (const c of questions) {
+        const options = parseOptions(c.options_json);
+        const optionsStr = options.length > 0 ? ` | options=[${options.join(" / ")}]` : "";
+        lines.push(`- ${c.id} | kind=${c.kind ?? "(none)"} | tx=${c.transaction_id ?? "(none)"} | acct=${c.account_id ?? "(none)"} | file=${c.file_id ?? "(none)"}${optionsStr}`, `    prompt: ${c.prompt.replace(/\n/g, " ")}`);
+    }
+    return lines.join("\n");
+}
+function parseOptions(json) {
+    if (!json)
+        return [];
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed) ? parsed.filter((o) => typeof o === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+function canonicalKey(u) {
+    return `[${u.kind ?? "general"}] ${u.prompt.replace(/\s+/g, " ").trim()}`;
+}
+function parseRule(body) {
+    const idx = body.lastIndexOf(" -> ");
+    if (idx < 0)
+        return null;
+    const key = body.slice(0, idx).trim();
+    const answer = body.slice(idx + 4).trim();
+    if (!key || !answer)
+        return null;
+    return { key, answer };
+}

package/dist/scanner/engine.d.ts

@@ -2,7 +2,7 @@ import type Database from "libsql";
 import type { ScannedFile } from "./walker.js";
 import type { ScanHooks } from "./hooks.js";
 import type { ScanProgress } from "./progress.js";
-import type { ResolveSummary } from "./resolver.js";
+import type { ClarifySummary } from "./clarifier.js";
 export interface Chunk {
     readonly chunkId: string;
     readonly fileId: string;
@@ -37,7 +37,7 @@ export interface PhaseError {
     readonly target?: string;
     readonly error: unknown;
 }
-export type PhaseName = "decrypt" | "chunk" | "parse" | "resolve";
+export type PhaseName = "decrypt" | "chunk" | "parse" | "clarify";
 export interface RunScanOptions {
     regex?: string;
     force?: boolean;
@@ -70,7 +70,7 @@ export interface ScanState {
     skipped: SkippedFile[];
     failed: FailedFile[];
     chunks: Chunk[];
-    resolveSummary: ResolveSummary | null;
+    clarifySummary: ClarifySummary | null;
     errors: PhaseError[];
 }
 export type Phase = (db: Database.Database, state: ScanState, hooks: ScanHooks) => Promise<void>;