argus-decision-mcp 1.0.0

package/dist/tools/review.js

@@ -0,0 +1,182 @@
+import fs from 'fs';
+import { z } from 'zod';
+import { envelope, toolError } from '../lib/envelope.js';
+import { ENVELOPE_OUTPUT_SCHEMA } from './tool-types.js';
+import { handleToolException } from './errors.js';
+import { ingest, scoreReviewability, routeLenses, buildExtractionPrompt, reviewabilityBand, LENSES, LENS_VERSION, REVIEW_SCHEMA_VERSION, } from '../lib/review/index.js';
+/**
+ * argus_review — document Judgment Review parity with the webapp (design doc
+ * §"웹앱과 MCP는 같은 Judgment Receipt"). Same ingest / anchoring / reviewability
+ * / lens routing / SSOT prompt as src/lib/review — the ONLY difference is that
+ * here the host agent is the model, so the tool hands it the scaffold instead of
+ * calling an LLM. The falsifiable follow-up it produces is sealed through the
+ * existing argus_seal → argus_settle loop (one receipt machine, no second store).
+ *
+ * Read-only: it computes + returns; it does not write to .argus. The write
+ * happens at seal, where the user owns the prediction.
+ */
+const MAX_DOC_BYTES = 400_000;
+const UNIT_LIMIT = 160;
+// Cap the units block so a large doc can't return a giant tool response
+// (mcp-builder §CHARACTER_LIMIT). Whichever bound hits first — count or chars.
+const CHAR_BUDGET = 20_000;
+const CONCERNS = ['strategic_fit', 'evidence', 'stakeholder_objection', 'execution_risk', 'ai_answer_trust', 'full_judgment_review'];
+const EXT_KIND = {
+    md: 'markdown', markdown: 'markdown', txt: 'txt', text: 'txt',
+    pdf: 'pdf', docx: 'docx', pptx: 'pptx',
+};
+const inputSchema = z.strictObject({
+    text: z.string().max(MAX_DOC_BYTES).describe('The document body to review (paste). Provide this OR file_path.').optional(),
+    file_path: z.string().max(1024).describe('Absolute path to a TEXT document (.md/.txt). Binary decks/PDFs degrade honestly — paste their text instead.').optional(),
+    source_kind: z.enum(['paste', 'markdown', 'txt', 'pdf', 'docx', 'pptx', 'transcript', 'llm_answer', 'pr_diff']).describe('Override the inferred source kind.').optional(),
+    title: z.string().max(300).optional(),
+    concerns: z.array(z.enum(CONCERNS)).max(3).describe('What to weight — drives lens routing.').optional(),
+    audience_hint: z.string().max(200).optional(),
+    biggest_worry: z.string().max(300).optional(),
+    stakes: z.enum(['low', 'medium', 'high']).describe('Optional stakes hint for lens routing (default medium).').optional(),
+});
+export const review = {
+    name: 'argus_review',
+    description: 'Review an EXISTING document (strategy memo / PRD / deck text / AI answer) for judgment risk. ' +
+        'Returns: a reviewability score+band, the routed review lenses, and the extraction prompt (which embeds the anchored source units + output schema) — then hands YOU (the model) the analysis to run. ' +
+        'Anchor every finding to the source; never deliver a verdict on the document. End by sealing ONE falsifiable follow-up via argus_seal. ' +
+        'Use for a document the user already wrote; to open a FRESH decision use argus_open_decision instead. Binary decks/PDFs degrade honestly — paste their text.',
+    inputSchema,
+    outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+    annotations: { title: 'Review a document', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (a) => {
+        try {
+            const filePath = typeof a['file_path'] === 'string' ? a['file_path'] : '';
+            let text = typeof a['text'] === 'string' ? a['text'] : '';
+            let inferredKind = a['source_kind'];
+            let title = typeof a['title'] === 'string' ? a['title'] : '';
+            if (!text && filePath) {
+                const ext = (filePath.split('.').pop() || '').toLowerCase();
+                inferredKind = inferredKind ?? EXT_KIND[ext] ?? 'txt';
+                if (['pdf', 'docx', 'pptx'].includes(inferredKind)) {
+                    return toolError({
+                        ok: false, tool: 'argus_review', error_code: 'BINARY_UNSUPPORTED',
+                        message: `${inferredKind.toUpperCase()} files aren't text-extracted in the MCP.`,
+                        recovery: 'Paste the document text into `text`, or convert to markdown/txt first.',
+                    });
+                }
+                try {
+                    const stat = fs.statSync(filePath);
+                    if (stat.size > MAX_DOC_BYTES) {
+                        return toolError({
+                            ok: false, tool: 'argus_review', error_code: 'TOO_LARGE',
+                            message: `Document exceeds ${MAX_DOC_BYTES} bytes.`,
+                            recovery: 'Review the most decision-bearing section, or split the document.',
+                        });
+                    }
+                    text = fs.readFileSync(filePath, 'utf8');
+                    if (!title)
+                        title = filePath.split(/[\\/]/).pop() || '';
+                }
+                catch {
+                    return toolError({
+                        ok: false, tool: 'argus_review', error_code: 'READ_FAILED',
+                        message: `Could not read file: ${filePath}`,
+                        recovery: 'Check the path (absolute), or paste the text into `text`.',
+                    });
+                }
+            }
+            if (!text.trim() || text.trim().length < 20) {
+                return toolError({
+                    ok: false, tool: 'argus_review', error_code: 'EMPTY',
+                    message: 'No reviewable text was provided.',
+                    recovery: 'Pass `text` (≥ 20 chars) or a readable `file_path`.',
+                });
+            }
+            const concerns = Array.isArray(a['concerns'])
+                ? a['concerns']
+                : ['full_judgment_review'];
+            const artifact = ingest({ source_kind: inferredKind ?? 'paste', title, text, privacy_mode: 'receipt_only' });
+            // Honest degrade — never a confident review over unextractable input.
+            if (artifact.extraction_quality === 'unsupported' || artifact.units.length === 0) {
+                return envelope({
+                    ok: true, tool: 'argus_review',
+                    surface: '이 문서는 지금 상태로는 전체 검수가 어렵습니다. 무엇이 빠졌는지부터 확인하세요.',
+                    next_actions: ['skip'],
+                    data: {
+                        needs_context: true,
+                        extraction_quality: artifact.extraction_quality,
+                        notes: artifact.extraction_notes,
+                    },
+                });
+            }
+            const reviewability = scoreReviewability(artifact);
+            const band = reviewabilityBand(reviewability.score);
+            // Routing needs a profile; without an LLM pass we use a neutral default
+            // (disclosed) — the agent's own extraction refines it. Concerns still steer.
+            const profile = {
+                artifact_maturity: 'working_draft',
+                document_type: 'unknown',
+                intent: 'decide',
+                audience: 'unknown',
+                stakes: a['stakes'] ?? 'medium',
+                source_confidence: 0.3,
+                inferred: { document_type: true, intent: true, audience: true, stakes: true },
+            };
+            const routing = routeLenses(profile, artifact, { concerns, maxLensCalls: 7 });
+            const ctx = {
+                audience_hint: typeof a['audience_hint'] === 'string' ? a['audience_hint'] : undefined,
+                biggest_worry: typeof a['biggest_worry'] === 'string' ? a['biggest_worry'] : undefined,
+                concerns,
+            };
+            // Effective unit count: min of UNIT_LIMIT and however many fit the char budget.
+            let charAcc = 0;
+            let effLimit = 0;
+            for (const u of artifact.units) {
+                if (effLimit >= UNIT_LIMIT)
+                    break;
+                charAcc += u.text.length + 48; // rough per-rendered-line overhead (id + kind + loc)
+                if (charAcc > CHAR_BUDGET && effLimit > 0)
+                    break;
+                effLimit++;
+            }
+            const extraction = buildExtractionPrompt(artifact.units, ctx, effLimit);
+            const lenses = routing.selected.map((id) => ({
+                id,
+                label: LENSES[id].label,
+                purpose: LENSES[id].purpose,
+                review_questions: LENSES[id].review_questions,
+                avoid: LENSES[id].failure_modes,
+            }));
+            return envelope({
+                ok: true, tool: 'argus_review',
+                surface: `검수 준비 완료 — "${artifact.source_title}" · 검수 가능성 ${reviewability.score}/100 (${band}) · 렌즈 ${lenses.length}개. 아래 단위를 근거로, 렌즈별로 검토한 뒤 사람이 판단할 것과 반증 가능한 예측 하나를 뽑아 argus_seal로 봉인하세요.`,
+                next_actions: ['argus_seal', 'skip'],
+                data: {
+                    schema_version: REVIEW_SCHEMA_VERSION,
+                    lens_version: LENS_VERSION,
+                    artifact_id: artifact.artifact_id,
+                    source_title: artifact.source_title,
+                    reviewability: { score: reviewability.score, band, reasons: reviewability.reasons },
+                    structure: artifact.detected_structure,
+                    routing: { selected: routing.selected, disclosure: routing.disclosure, note: '라우팅은 기본 프로파일 기준의 제안입니다 — 추출 단계에서 문서 프로파일을 확정하면 렌즈를 조정하세요.' },
+                    lenses,
+                    // The SSOT extraction prompt already embeds the anchored units + the
+                    // output schema — the agent works off THIS single block for every
+                    // stage (no separate units dump; the source text is heavy and should
+                    // not be sent twice).
+                    extraction_prompt: extraction,
+                    units_shown: Math.min(artifact.units.length, effLimit),
+                    units_total: artifact.units.length,
+                    ...(artifact.units.length > effLimit
+                        ? { units_truncated_note: `문서 단위 ${artifact.units.length}개 중 앞 ${effLimit}개만 실었습니다(응답 크기 제한). 더 검수하려면 뒷부분을 따로 넣으세요.` }
+                        : {}),
+                    protocol: [
+                        '1) extraction_prompt(그 안의 units + 출력 스키마)를 적용해 문서 판단 지도(profile + claims/assumptions/decision_points)를 만든다.',
+                        '2) lenses의 각 렌즈로 그 units를 근거로 검토한다 — 모든 finding은 unit을 근거로 하고, 산문에는 unit_id를 노출하지 않는다.',
+                        '3) 사람이 직접 판단해야 할 항목(judgment obligations)을 분리한다. 평결하지 않는다.',
+                        '4) 현실이 pass/fail로 답할 반증 가능한 예측 1개를 뽑아 argus_seal로 봉인한다 — 예측·pass/fail 조건·check_by는 사용자의 것이다.',
+                    ],
+                },
+            });
+        }
+        catch (e) {
+            return handleToolException('argus_review', e);
+        }
+    },
+};

package/dist/tools/seal.js

@@ -0,0 +1,152 @@
+import { atomicWriteJson } from '../lib/atomic-write.js';
+import { bearingPath } from '../lib/layout.js';
+import { resolveToolArgusDir } from '../lib/argus-dir.js';
+import { resolveToday } from '../lib/resolve-today.js';
+import { resolveContract } from '../lib/resolve-contract.js';
+import { guardTransition } from '../lib/state-machine.js';
+import { validateSeal } from '../lib/validate-seal.js';
+import { appendLedger } from '../lib/ledger-append.js';
+import { writeSealReceipt } from '../lib/receipt.js';
+import { premiseId, MAX_ACTIVE_PREMISES, MAX_LOAD_BEARING } from '../lib/premises.js';
+import { pushToAccount } from '../lib/push-account.js';
+import { ensurePrivacyGitignore } from '../lib/privacy.js';
+import { renderSeal } from '../lib/render-receipt.js';
+import { surfaceLocale } from '../lib/surfaces.js';
+import { SCHEMA_VERSION } from '../lib/spine.js';
+import { z } from 'zod';
+import { envelope, toolError } from '../lib/envelope.js';
+import { ENVELOPE_OUTPUT_SCHEMA, zArgusDir, zId, zDate } from './tool-types.js';
+import { handleToolException } from './errors.js';
+const inputSchema = z.strictObject({
+    argus_dir: zArgusDir,
+    id: zId.describe('The id from argus_open_decision.'),
+    predicate: z.string().min(8).max(400).describe('A prediction reality can mark true/false. Good: "cutover downtime < 5 min". Bad: "it will go well".'),
+    check_by: zDate.describe('YYYY-MM-DD, a real future date — when you will come back to settle.'),
+    predicate_owner: z.enum(['user', 'ai_surfaced']).describe('Provenance. Never forge. "user" = the user wrote or affirmed it. "ai_surfaced" = Argus drafted, unconfirmed.'),
+    basis: z.enum(['judgment', 'luck', 'mixed', 'unsure']).optional(),
+    real_question: z.string().max(400).describe('The real question behind the answer (receipt).').optional(),
+    unverified_assumption: z.string().max(400).describe('The core assumption not yet verified (receipt).').optional(),
+    human_only: z.string().max(400).describe('What only a human can judge here (receipt).').optional(),
+    human_judgment: z.string().max(400).describe("The user's one-line call. MUST be the user's words — never an Argus-drafted line relabeled.").optional(),
+    today_override: zDate.optional(),
+});
+export const seal = {
+    name: 'argus_seal',
+    description: 'Seal a falsifiable prediction (predicate + check-by date) for an open decision. Captures the seal-time Judgment Receipt fields. Refuses an empty/non-falsifiable predicate or a non-future date. On success, data.seal_text is the sealing confirmation rendered for the user — show it to them verbatim.',
+    inputSchema,
+    outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+    // openWorldHint: true — with ARGUS_TOKEN set, sealing also mirrors to the account.
+    annotations: { title: 'Seal a prediction', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (a) => {
+        try {
+            const dir = resolveToolArgusDir(a['argus_dir']);
+            const id = String(a['id'] ?? '');
+            const today = resolveToday({ override: a['today_override'] });
+            const current = resolveContract(dir, id, today);
+            guardTransition(current.state, 'seal'); // throws DECISION_CLOSED / ILLEGAL_TRANSITION
+            const vErr = validateSeal(a['predicate'], a['check_by'], today);
+            if (vErr) {
+                return toolError({ ok: false, tool: 'argus_seal', error_code: vErr.code, message: vErr.message, recovery: vErr.recovery });
+            }
+            const predicate = String(a['predicate']);
+            const checkBy = String(a['check_by']);
+            const now = new Date().toISOString();
+            await ensurePrivacyGitignore(dir);
+            // seal-time receipt (the rich fields that make the receipt not blank)
+            const receipt = await writeSealReceipt(dir, {
+                id, predicate, check_by: checkBy,
+                real_question: a['real_question'],
+                unverified_assumption: a['unverified_assumption'],
+                human_only: a['human_only'],
+                human_judgment: a['human_judgment'],
+                basis: a['basis'],
+            }, now);
+            // bearing seed (so a due contract is visible even before the ledger is replayed elsewhere)
+            await atomicWriteJson(bearingPath(dir, id), {
+                v: SCHEMA_VERSION, id, contract_seed: { predicate, check_by: checkBy }, predicate_owner: a['predicate_owner'],
+            });
+            // ledger: self-create harvest if the decision was sealed without an explicit open
+            const events = [];
+            if (current.state === 'absent')
+                events.push({ id, event: 'harvest', decision: predicate });
+            events.push({ id, event: 'seal', predicate, check_by: checkBy, basis: a['basis'] });
+            // Promotion (plan v5 §5.4): the named unverified_assumption IS the first
+            // premise — the premise set is canonical, the seal field is its input
+            // alias. source='user' (receipt judgment fields are user-named),
+            // external=false until the user marks it (honest default: we cannot infer
+            // reality-checkability), load_bearing=true (it is the receipt headline).
+            // Skipped field ⇒ no promotion. Dedup + cap-safe: never fails the seal.
+            let promotedRef = null;
+            const ua = a['unverified_assumption'];
+            if (ua && ua.trim()) {
+                const existingPrems = current.entry?.premises ?? [];
+                const pid = premiseId(id, 'premise', ua);
+                const lbCount = existingPrems.filter((p) => p.status === 'active' && p.load_bearing).length;
+                const activeCount = existingPrems.filter((p) => p.status === 'active').length;
+                const isDup = existingPrems.some((p) => p.premise_id === pid);
+                if (!isDup && activeCount < MAX_ACTIVE_PREMISES) {
+                    const ordinal = existingPrems.reduce((m, p) => Math.max(m, p.ordinal), 0) + 1;
+                    events.push({
+                        id, event: 'premise_add', premise_id: pid, ordinal,
+                        kind: 'premise', text: ua.trim(),
+                        external: false, load_bearing: lbCount < MAX_LOAD_BEARING,
+                        source: 'user',
+                    });
+                    promotedRef = `P${ordinal}`;
+                }
+            }
+            await appendLedger(dir, events, now);
+            const namedAssumption = !receipt.skipped.includes('unverified_assumption');
+            const nudge = namedAssumption
+                ? ''
+                : ' You sealed without naming the assumption it rests on — that\'s recorded as skipped, not hidden. You can still name it.';
+            // Opt-in: mirror the prediction to the user's account so the Companion
+            // Brief can email it at check-by. No token ⇒ silent local-only no-op;
+            // failure never affects the seal that already succeeded locally.
+            const sync = await pushToAccount({
+                action: 'seal', id, predicate, check_by: checkBy, sealed_at: now,
+                source_title: predicate.slice(0, 80),
+                real_question: a['real_question'],
+                human_judgment: a['human_judgment'],
+            });
+            // 3-state sync voice (11 S3): success speaks, no-token stays silent
+            // (local-only is the chosen default, not a failure), and a FAILURE with a
+            // token set must speak — the user believes an email is coming.
+            const syncLine = sync.synced
+                ? ' Synced to your account — you\'ll get an email when it comes due.'
+                : sync.reason === 'no_token'
+                    ? ''
+                    : ` (Account sync didn't go through — ${sync.reason}. Your seal is safe locally; the email reminder won't fire until it syncs. Try argus_sync later.)`;
+            // The sealing confirmation (P1-E2): the terminal twin of the webapp's
+            // seal certificate. surface stays the short model-facing line; seal_text
+            // is FOR THE USER (the tool description says: show it verbatim).
+            const seal_text = renderSeal({
+                predicate,
+                predicate_owner: a['predicate_owner'],
+                sealed_on: now.slice(0, 10),
+                check_by: checkBy,
+                today,
+                locale: surfaceLocale(dir),
+            });
+            return envelope({
+                ok: true, tool: 'argus_seal',
+                surface: `Sealed. "${predicate}" — reality answers on ${checkBy}. Come back then with argus_settle.${nudge}${syncLine}`,
+                next_actions: ['argus_check_in', 'stop'],
+                data: {
+                    id, predicate, check_by: checkBy, predicate_owner: a['predicate_owner'],
+                    seal_text,
+                    status: 'sealed', ledger_events_written: events.map((e) => e.event),
+                    skipped: receipt.skipped,
+                    account_synced: sync.synced,
+                    ...(sync.synced ? {} : { account_sync_reason: sync.reason }),
+                    // The named assumption now lives as a tracked premise (canonical set).
+                    // Marking it external (argus_premises op=amend) arms reality re-checks.
+                    ...(promotedRef ? { premise_promoted: promotedRef } : {}),
+                },
+            });
+        }
+        catch (e) {
+            return handleToolException('argus_seal', e);
+        }
+    },
+};

package/dist/tools/settle.js

@@ -0,0 +1,126 @@
+import { resolveToolArgusDir } from '../lib/argus-dir.js';
+import { resolveToday, asDate } from '../lib/resolve-today.js';
+import { resolveContract } from '../lib/resolve-contract.js';
+import { guardTransition } from '../lib/state-machine.js';
+import { appendLedger } from '../lib/ledger-append.js';
+import { writeSettleReceipt } from '../lib/receipt.js';
+import { pushToAccount } from '../lib/push-account.js';
+import { elicit, canElicit } from '../lib/elicit.js';
+import { renderReceipt } from '../lib/render-receipt.js';
+import { resolvePremiseRef, receiptPremisesInfo } from '../lib/premises.js';
+import { z } from 'zod';
+import { envelope, toolError } from '../lib/envelope.js';
+import { ENVELOPE_OUTPUT_SCHEMA, zArgusDir, zId, zDate } from './tool-types.js';
+import { handleToolException } from './errors.js';
+const inputSchema = z.strictObject({
+    argus_dir: zArgusDir,
+    id: zId,
+    outcome: z.enum(['held', 'avoided', 'partial', 'still_pending']).describe("What reality did to the prediction. Record the user's words — never infer. If omitted, Argus asks the user directly (elicitation) on hosts that support it.").optional(),
+    outcome_source: z.literal('user_stated').describe('Single value "user_stated". An AI-inferred outcome cannot be expressed.'),
+    what_happened: z.string().min(1).max(600),
+    broken_premise_ref: z.string().max(64).optional().describe('Optional, USER-attributed: which tracked premise (ordinal like "P1"), if any, broke and drove the outcome. Never inferred by the model — ask, or omit.'),
+    today_override: zDate.optional(),
+});
+export const settle = {
+    name: 'argus_settle',
+    description: 'Settle a sealed decision against reality and issue a Judgment Receipt with zero AI verdict. Hard-errors if there is no prior seal. The outcome is the user\'s — recorded, never inferred.',
+    inputSchema,
+    outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+    // openWorldHint: true — with ARGUS_TOKEN set, settling also mirrors to the account.
+    // idempotentHint:false (11 S7) — a repeat settle is NOT a no-op: it hard-errors
+    // ALREADY_SETTLED (append-only ledger), so the hint was a false signal to hosts.
+    annotations: { title: 'Settle against reality', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (a) => {
+        try {
+            const dir = resolveToolArgusDir(a['argus_dir']);
+            const id = String(a['id'] ?? '');
+            const today = resolveToday({ override: a['today_override'] });
+            const current = resolveContract(dir, id, today);
+            guardTransition(current.state, 'settle'); // NO_PRIOR_SEAL / ALREADY_SETTLED / DECISION_CLOSED
+            // Outcome is the user's — recorded, never inferred. If the model didn't
+            // supply it, ask the USER directly with a structured choice (spine-safe:
+            // this is reality, not a verdict). Falls back to requiring it on hosts
+            // without elicitation.
+            let outcome = a['outcome'];
+            if (!outcome && canElicit()) {
+                const picked = await elicit('현실이 어떻게 답했나요? (What did reality do?)', {
+                    type: 'object',
+                    properties: {
+                        outcome: {
+                            type: 'string',
+                            enum: ['held', 'avoided', 'partial', 'still_pending'],
+                            enumNames: ['그렇게 됐다 (held)', '피했다 (avoided)', '부분적으로 (partial)', '아직 불분명 (still pending)'],
+                            description: 'What reality did to your sealed prediction.',
+                        },
+                    },
+                    required: ['outcome'],
+                });
+                const v = picked?.['outcome'];
+                if (v === 'held' || v === 'avoided' || v === 'partial' || v === 'still_pending')
+                    outcome = v;
+            }
+            if (!outcome) {
+                return toolError({
+                    ok: false, tool: 'argus_settle', error_code: 'OUTCOME_REQUIRED',
+                    message: 'Reality has to answer: held, avoided, partial, or still_pending.',
+                    recovery: 'Ask the user what actually happened and pass it as `outcome` — never infer it.',
+                });
+            }
+            const checkBy = asDate(current.check_by);
+            if (outcome === 'still_pending' && checkBy && checkBy > today) {
+                return toolError({
+                    ok: false, tool: 'argus_settle', error_code: 'PREMATURE_SETTLE',
+                    message: `Not due yet (check-by ${checkBy}, today ${today}).`,
+                    recovery: 'Wait for the check-by date, or amend the date if the timeline changed.',
+                });
+            }
+            // Premise-level attribution (plan v5 P2) — the user's own read of WHICH
+            // premise broke. Counts feed track_record frequency statements; never a
+            // grade. An invalid ref fails loudly rather than mis-attributing.
+            let brokenPremiseId;
+            let brokenPremiseRef;
+            const bpr = a['broken_premise_ref'];
+            if (typeof bpr === 'string' && bpr.trim()) {
+                const p = resolvePremiseRef(current.entry?.premises ?? [], bpr); // throws NO_SUCH_PREMISE/AMBIGUOUS_REF
+                brokenPremiseId = p.premise_id;
+                brokenPremiseRef = `P${p.ordinal}`;
+            }
+            const now = new Date().toISOString();
+            await appendLedger(dir, [{ id, event: 'settle', outcome, decision: a['what_happened'], ...(brokenPremiseId ? { broken_premise_id: brokenPremiseId } : {}) }], now);
+            const receipt = await writeSettleReceipt(dir, id, { what_happened: String(a['what_happened']), outcome, settled_at: now }, { predicate: current.predicate, check_by: current.check_by });
+            // Mirror the outcome to the account (opt-in) so a synced prediction stops
+            // being "due" — otherwise the Companion Brief would keep re-nudging it.
+            // No-op when there's no token or the id was never synced.
+            const sync = await pushToAccount({
+                action: 'settle', id, outcome, what_happened: String(a['what_happened']), settled_at: now,
+            });
+            // 3-state sync voice (11 S3, same pattern as seal): silence is only honest
+            // for the no-token default — a failed mirror means the account keeps
+            // listing this as due (and may re-email it), so say so.
+            const syncLine = sync.synced
+                ? ''
+                : sync.reason === 'no_token'
+                    ? ''
+                    : ` (Account sync didn't go through — ${sync.reason}. Your settlement is safe locally; the account may keep listing this as due until it syncs. Try argus_sync later.)`;
+            return envelope({
+                ok: true, tool: 'argus_settle',
+                surface: 'Settled. The receipt records what you predicted and what reality did — no grade.' + syncLine,
+                next_actions: ['argus_recall', 'stop'],
+                data: {
+                    id, outcome, outcome_source: 'user_stated',
+                    assumption_held: receipt.assumption_held,
+                    ...(brokenPremiseRef ? { broken_premise: brokenPremiseRef, broken_premise_source: 'user_stated' } : {}),
+                    ai_verdict: null,
+                    account_synced: sync.synced,
+                    ...(sync.synced ? {} : { account_sync_reason: sync.reason }),
+                    receipt,
+                    // The premise set is canonical — the receipt's summary renders from the fold (plan v5 §3.3).
+                    receipt_text: renderReceipt(receipt, receiptPremisesInfo(current.entry)),
+                },
+            });
+        }
+        catch (e) {
+            return handleToolException('argus_settle', e);
+        }
+    },
+};

package/dist/tools/sync.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { envelope, toolError } from '../lib/envelope.js';
+import { ENVELOPE_OUTPUT_SCHEMA, zArgusDir } from './tool-types.js';
+import { handleToolException } from './errors.js';
+import { fetchAccountReceipts } from '../lib/push-account.js';
+import { resolveToolArgusDir } from '../lib/argus-dir.js';
+import { resolveToday } from '../lib/resolve-today.js';
+import { replayLedger } from '../lib/ledger-replay.js';
+import { surfacesFor } from '../lib/surfaces.js';
+/**
+ * argus_sync — the explicit, bidirectional bridge (design doc §연결 방식).
+ *
+ * PUSH is automatic: argus_seal / argus_settle already mirror to the account
+ * when ARGUS_TOKEN is set. PULL is this tool: it lists your account receipts —
+ * live judgments + what's due — so the terminal can settle without the web app.
+ * Read-only and opt-in; with no token it explains how to connect.
+ */
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+const inputSchema = z.strictObject({
+    argus_dir: zArgusDir,
+    due_only: z.boolean().default(false).describe('List only receipts whose check-by date has arrived.'),
+    limit: z.number().int().min(1).max(MAX_LIMIT).default(DEFAULT_LIMIT).describe(`Max receipts to list (default ${DEFAULT_LIMIT}). Due items are ordered first.`),
+});
+export const sync = {
+    name: 'argus_sync',
+    description: 'Pull your Argus account receipts into the terminal — live judgments and what is due. ' +
+        'Returns: receipts (id, local_id, settle_path, title, state, next_check_by, due, open_predicates) with due items first, plus total/due/has_more. ' +
+        'Account ids carry an mcp_ prefix for terminal-sealed judgments: settle those with argus_settle using local_id (NOT the account id). ' +
+        'Web-sealed judgments (local_id null) settle in the web dashboard. ' +
+        'A terminal-sealed judgment already settled on the web is flagged settled_in_account:true — record the same outcome locally with argus_settle if you want it in this ledger too. ' +
+        'Seals/settles already push to the account automatically; this is the READ side. Use due_only:true to see just what needs settling. Requires ARGUS_TOKEN (Settings → sync token).',
+    inputSchema,
+    outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+    annotations: { title: 'Sync account receipts', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (a) => {
+        try {
+            const pull = await fetchAccountReceipts();
+            if (!pull.ok && pull.reason === 'no_token') {
+                return toolError({
+                    ok: false, tool: 'argus_sync', error_code: 'NOT_CONNECTED',
+                    message: 'This terminal is not connected to an Argus account.',
+                    recovery: 'Issue a token in the web app (Settings → sync token) and set ARGUS_TOKEN in your MCP config.',
+                });
+            }
+            if (!pull.ok) {
+                return toolError({
+                    ok: false, tool: 'argus_sync', error_code: 'SYNC_FAILED',
+                    message: `Could not reach the account (${pull.reason}).`,
+                    recovery: 'Check your network / ARGUS_API_URL, then try again. Local seals are unaffected.',
+                });
+            }
+            const dueOnly = a['due_only'] === true;
+            const rawLimit = typeof a['limit'] === 'number' ? Math.floor(a['limit']) : DEFAULT_LIMIT;
+            const limit = Math.max(1, Math.min(MAX_LIMIT, rawLimit));
+            const matched = dueOnly ? pull.receipts.filter((r) => r.due) : pull.receipts;
+            const receipts = matched.slice(0, limit);
+            const dueCount = pull.receipts.filter((r) => r.due).length;
+            const truncated = matched.length > receipts.length;
+            // ④ Reverse cross-check (best-effort, read-only): a judgment sealed here
+            // but settled in the WEB stays 'sealed' in the local ledger forever, so
+            // check_in / recall keep citing it as due. Compare account state against
+            // the local ledger and FLAG the mismatch — never auto-settle locally
+            // (recording an outcome without the user's own words would be a machine
+            // settlement on an append-only ledger; the user runs argus_settle).
+            let localContracts = null;
+            let boundDir = null;
+            try {
+                boundDir = resolveToolArgusDir(a['argus_dir']);
+                localContracts = replayLedger(boundDir, resolveToday({})).contracts;
+            }
+            catch {
+                localContracts = null; // no local dir bound — account-only listing, skip the cross-check
+            }
+            // Locale brain (P1-E1): surface strings come from the {ko,en} dictionary,
+            // picked by the config's locale. No bound dir / no config → base 'en'.
+            const S = surfacesFor(boundDir).sync;
+            const settledInAccount = (accountId, accountState) => {
+                if (!localContracts || accountState !== 'settled' || !accountId.startsWith('mcp_'))
+                    return false;
+                const entry = localContracts.get(accountId.slice(4));
+                return entry?.status === 'sealed'; // sealed locally (incl. derived-due) yet already settled in the account
+            };
+            const settledInAccountCount = pull.receipts.filter((r) => settledInAccount(r.id, r.state)).length;
+            const baseSurface = dueCount > 0
+                ? S.live_with_due(pull.receipts.length, dueCount)
+                : S.live_no_due(pull.receipts.length);
+            const crossCheckLine = settledInAccountCount > 0
+                ? S.settled_on_web(settledInAccountCount)
+                : '';
+            return envelope({
+                ok: true, tool: 'argus_sync',
+                surface: baseSurface + crossCheckLine,
+                next_actions: dueCount > 0 ? ['argus_settle', 'stop'] : ['stop'],
+                data: {
+                    total: pull.receipts.length,
+                    due: dueCount,
+                    count: receipts.length,
+                    has_more: truncated,
+                    ...(truncated ? { truncation_note: S.truncation(receipts.length, matched.length) } : {}),
+                    receipts: receipts.map((r) => {
+                        // Terminal-sealed judgments live in the account under an `mcp_` prefix
+                        // (webapp api/mcp/seal rowId). Settling with the ACCOUNT id always
+                        // fails (NO_PRIOR_SEAL: the local ledger knows the unprefixed id), so
+                        // hand the caller the exact id argus_settle expects — or route
+                        // web-sealed rows to the web dashboard.
+                        const localId = r.id.startsWith('mcp_') ? r.id.slice(4) : null;
+                        return {
+                            id: r.id,
+                            local_id: localId,
+                            settle_path: localId ? 'argus_settle (use local_id)' : 'webapp',
+                            title: r.source_title,
+                            state: r.state,
+                            next_check_by: r.next_check_by,
+                            due: r.due,
+                            open_predicates: r.open_predicates,
+                            // Settled in the account (web) while the local ledger still says
+                            // sealed. Flag only — the local record stays the user's to write.
+                            ...(settledInAccount(r.id, r.state) ? { settled_in_account: true } : {}),
+                        };
+                    }),
+                },
+            });
+        }
+        catch (e) {
+            return handleToolException('argus_sync', e);
+        }
+    },
+};

package/dist/tools/tool-types.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+// ── Shared field builders (DRY — argus_dir / id / date recur on every tool) ──
+// argus_dir is OPTIONAL: omit it to use the ARGUS_DIR env var from your MCP
+// config (the ergonomic default — set once, never pass again). A per-call value
+// still wins. Resolution + validation live in resolveToolArgusDir.
+export const zArgusDir = z
+    .string()
+    .describe('Absolute path to the .argus directory (no ".."). Omit to use the ARGUS_DIR env var from your MCP config.')
+    .optional();
+export const zId = z.string().regex(/^[A-Za-z0-9._-]+$/, 'id may only contain A-Z a-z 0-9 . _ -');
+export const zDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'must be YYYY-MM-DD');
+/** JSON Schema for tools/list, generated from the Zod source (drop $schema noise). */
+export function toolJsonSchema(schema) {
+    const json = z.toJSONSchema(schema);
+    delete json['$schema'];
+    return json;
+}
+/** Shared envelope output schema fragment (structuredContent contract). */
+export const ENVELOPE_OUTPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        ok: { type: 'boolean' },
+        tool: { type: 'string' },
+        surface: { type: 'string' },
+        next_actions: { type: 'array', items: { type: 'string' } },
+        data: { type: 'object' },
+        over_fire_gate: { type: 'object' },
+        error_code: { type: 'string' },
+        message: { type: 'string' },
+    },
+    required: ['ok', 'tool'],
+};