argus-decision-mcp 1.0.0

package/dist/server.js

@@ -0,0 +1,107 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { TOOLS, TOOL_MAP } from './tools/index.js';
+import { toolJsonSchema } from './tools/tool-types.js';
+import { listResources, listResourceTemplates, readResource } from './resources.js';
+import { listPrompts, getPrompt } from './prompts.js';
+import { SERVER_INSTRUCTIONS } from './lib/spine.js';
+import { setElicitor } from './lib/elicit.js';
+import { appendDueNote } from './lib/due-note.js';
+import { logError } from './lib/log.js';
+import { readFileSync } from 'node:fs';
+// Single version source — package.json (the '1.0.0' literal had drifted from
+// 1.3.0). Both src/server.ts (tests) and dist/server.js sit one level below it.
+function readPackageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0'; // never block startup on a packaging quirk
+    }
+}
+/**
+ * Argus MCP server (blueprint §4). v1 surface = Tools only — the universal
+ * floor that works on every host. The spine bias is carried once by the
+ * `instructions` field (the one spec-sanctioned home for the killed
+ * paste-prompt), rendered from the single spine source. Resources and Prompts
+ * are Phase 2; their capabilities are NOT declared until their handlers exist,
+ * so a host never probes a no-op.
+ */
+export async function createServer() {
+    const server = new Server({ name: 'argus-decision-mcp', version: readPackageVersion() }, {
+        // Capabilities are declared only for primitives whose handlers exist, so
+        // a host never probes a no-op (addendum J). `elicitation` is a client
+        // capability we USE, not a server one we serve — advertised so the SDK
+        // permits elicitInput; tools degrade to text when the host lacks it.
+        capabilities: { tools: {}, resources: {}, prompts: {} },
+        instructions: SERVER_INSTRUCTIONS,
+    });
+    setElicitor((message, requestedSchema) => server.elicitInput({ message, requestedSchema }));
+    // Resources — read-only context (blueprint §4.3).
+    server.setRequestHandler(ListResourcesRequestSchema, async () => listResources());
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => listResourceTemplates());
+    server.setRequestHandler(ReadResourceRequestSchema, async (req) => readResource(req.params.uri));
+    // Prompts — user-triggered discipline rituals (blueprint §4.2).
+    server.setRequestHandler(ListPromptsRequestSchema, async () => listPrompts());
+    server.setRequestHandler(GetPromptRequestSchema, async (req) => getPrompt(req.params.name, req.params.arguments));
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS.map((t) => ({
+            name: t.name,
+            description: t.description,
+            // JSON Schema generated from the Zod source of truth (no hand-kept copy).
+            inputSchema: toolJsonSchema(t.inputSchema),
+            ...(t.outputSchema ? { outputSchema: t.outputSchema } : {}),
+            ...(t.annotations ? { annotations: t.annotations } : {}),
+        })),
+    }));
+    // Serialize tool calls so concurrent invocations can't interleave a
+    // read-replay-then-append against the same ledger (real hosts already wait
+    // for each response; this removes the foot-gun for batched/parallel clients).
+    let chain = Promise.resolve();
+    const serialize = (fn) => {
+        const run = chain.then(fn, fn);
+        chain = run.then(() => undefined, () => undefined);
+        return run;
+    };
+    // The low-level SDK handler's expected return is a broad ServerResult union
+    // (incl. a task-augmented variant) our envelope type isn't nominally part of —
+    // `any` is the sanctioned boundary here; every return below is a real
+    // McpToolResult, built by the typed helpers.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const tool = TOOL_MAP.get(name);
+        if (!tool) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error_code: 'UNKNOWN_TOOL', message: `Unknown tool: ${name}` }) }],
+                isError: true,
+            };
+        }
+        // Runtime input validation from the Zod source (mcp-builder best-practices).
+        // A schema failure is a client bug → a clean, actionable tool-result error
+        // (not a protocol crash); the handler only ever sees validated, default-
+        // applied args.
+        const parsed = tool.inputSchema.safeParse(args ?? {});
+        if (!parsed.success) {
+            const issues = parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ');
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, tool: name, error_code: 'INVALID_INPUT', message: `Invalid arguments — ${issues}` }) }],
+                isError: true,
+            };
+        }
+        try {
+            const result = await serialize(() => tool.handler(parsed.data));
+            return appendDueNote(name, parsed.data, result);
+        }
+        catch (e) {
+            // Last-resort guard — individual handlers already map their own errors.
+            logError(`[${name}] escaped handler`, e);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error_code: 'INTERNAL_ERROR', message: String(e) }) }],
+                isError: true,
+            };
+        }
+    });
+    return server;
+}

package/dist/tools/amend-dismiss.js

@@ -0,0 +1,90 @@
+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 { 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';
+export const amend = {
+    name: 'argus_amend',
+    description: 'Adjust an open or not-yet-due sealed decision\'s predicate or check-by date. Refused once the check-by date has arrived (no moving the goalpost after the fact).',
+    inputSchema: z.strictObject({
+        argus_dir: zArgusDir,
+        id: zId,
+        predicate: z.string().min(8).max(400).optional(),
+        check_by: zDate.optional(),
+        today_override: zDate.optional(),
+    }),
+    outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+    annotations: { title: 'Amend a decision', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    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, 'amend'); // GOALPOST_MOVED / DECISION_CLOSED / ILLEGAL_TRANSITION
+            const predicate = a['predicate'] ?? current.predicate;
+            const checkBy = a['check_by'] ?? current.check_by;
+            if (a['check_by'] != null || a['predicate'] != null) {
+                const vErr = validateSeal(predicate, checkBy, today);
+                if (vErr)
+                    return toolError({ ok: false, tool: 'argus_amend', error_code: vErr.code, message: vErr.message, recovery: vErr.recovery });
+            }
+            const now = new Date().toISOString();
+            await appendLedger(dir, [{ id, event: 'amend', predicate: a['predicate'], check_by: a['check_by'] }], now);
+            if (predicate && checkBy) {
+                await atomicWriteJson(bearingPath(dir, id), { v: SCHEMA_VERSION, id, contract_seed: { predicate, check_by: checkBy } });
+            }
+            return envelope({
+                ok: true, tool: 'argus_amend',
+                surface: `Amended. Now: "${predicate}" — check-by ${checkBy}.`,
+                next_actions: ['argus_check_in', 'stop'],
+                data: { id, predicate, check_by: checkBy },
+            });
+        }
+        catch (e) {
+            return handleToolException('argus_amend', e);
+        }
+    },
+};
+export const dismiss = {
+    name: 'argus_dismiss',
+    description: 'Close a decision without settling it — the user moved on, decided elsewhere, or it became irrelevant. Terminal; not reopened.',
+    inputSchema: z.strictObject({
+        argus_dir: zArgusDir,
+        id: zId,
+        dismiss_reason: z.enum(['became_irrelevant', 'decided_elsewhere', 'changed_mind', 'other']),
+        note: z.string().max(300).optional(),
+        today_override: zDate.optional(),
+    }),
+    outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+    // idempotentHint:false (11 S7) — a repeat dismiss hard-errors DECISION_CLOSED.
+    annotations: { title: 'Dismiss a decision', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    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, 'dismiss');
+            const now = new Date().toISOString();
+            await appendLedger(dir, [{ id, event: 'dismiss', dismiss_reason: a['dismiss_reason'], decision: a['note'] }], now);
+            return envelope({
+                ok: true, tool: 'argus_dismiss',
+                surface: 'Dismissed. Closed without a verdict.',
+                next_actions: ['stop'],
+                data: { id, dismiss_reason: a['dismiss_reason'] },
+            });
+        }
+        catch (e) {
+            return handleToolException('argus_dismiss', e);
+        }
+    },
+};

package/dist/tools/check-in.js

@@ -0,0 +1,158 @@
+import { resolveToolArgusDir } from '../lib/argus-dir.js';
+import { resolveToday, asDate } from '../lib/resolve-today.js';
+import { replayLedger, bearingContracts } from '../lib/ledger-replay.js';
+import { duePremises, groupDuePremises } from '../lib/premises.js';
+import { readReceipt, SKIPPED } from '../lib/receipt.js';
+import { surfacesFor } from '../lib/surfaces.js';
+import { z } from 'zod';
+import { envelope } from '../lib/envelope.js';
+import { ENVELOPE_OUTPUT_SCHEMA, zArgusDir, zDate } from './tool-types.js';
+import { handleToolException } from './errors.js';
+const inputSchema = z.strictObject({
+    argus_dir: zArgusDir,
+    include_upcoming_days: z.number().int().min(0).max(30).default(0).describe('Also list sealed contracts coming due within N days (informational — nothing to settle yet).'),
+    today_override: zDate.optional(),
+});
+export const checkIn = {
+    name: 'argus_check_in',
+    description: 'Return decision contracts whose check-by date has arrived (and optionally upcoming ones). A return nudge — reads and routes to argus_settle. If nothing is due, it says so and stops; it does not manufacture engagement.',
+    inputSchema,
+    outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+    annotations: { title: 'Check what is due', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (a) => {
+        try {
+            const dir = resolveToolArgusDir(a['argus_dir']);
+            const today = resolveToday({ override: a['today_override'] });
+            const ledger = replayLedger(dir, today);
+            const seeds = bearingContracts(dir, today, ledger);
+            const dueMap = new Map();
+            for (const c of ledger.overdue) {
+                dueMap.set(c.id, { id: c.id, predicate: c.text, check_by: c.date, days_overdue: daysBetween(c.date, today), source: 'ledger' });
+            }
+            for (const s of seeds) {
+                if (!dueMap.has(s.id))
+                    dueMap.set(s.id, { id: s.id, predicate: s.predicate, check_by: s.check_by, days_overdue: daysBetween(s.date, today), source: 'bearing' });
+            }
+            const due = Array.from(dueMap.values()).sort((x, y) => x.check_by < y.check_by ? -1 : 1);
+            // Locale brain (P1-E1): all check_in surface strings come from the
+            // {ko,en} dictionary, picked by the config's locale.
+            const S = surfacesFor(dir).checkin;
+            // 닻 거울 (P1-E3): each due item carries its seal date + the user's OWN
+            // seal-time words (receipt.human_judgment; omitted when skipped). The
+            // mirror is recognition by date arithmetic, never a welcome greeting —
+            // and the quote is the user's sentence, not a machine verdict.
+            const dueEnriched = due.map((d) => {
+                const receipt = readReceipt(dir, d.id);
+                if (!receipt?.created_at)
+                    return d;
+                const sealed_at = String(receipt.created_at).slice(0, 10);
+                const words = typeof receipt.human_judgment === 'string' &&
+                    receipt.human_judgment.trim().length > 0 &&
+                    receipt.human_judgment !== SKIPPED
+                    ? receipt.human_judgment.trim()
+                    : undefined;
+                return {
+                    ...d,
+                    sealed_at,
+                    days_since_seal: daysBetween(sealed_at, today),
+                    ...(words ? { your_words_then: words } : {}),
+                };
+            });
+            // include_upcoming_days, actually implemented (11 S2 — an accepted-then-
+            // discarded argument is a silent lie in the schema). Sealed contracts whose
+            // check-by falls within the window: informational only, nothing to settle.
+            const upDays = typeof a['include_upcoming_days'] === 'number'
+                ? Math.max(0, Math.min(30, Math.floor(a['include_upcoming_days'])))
+                : 0;
+            const upcoming = [];
+            if (upDays > 0) {
+                const horizon = addDays(today, upDays);
+                for (const [cid, entry] of ledger.contracts.entries()) {
+                    if (entry.status !== 'sealed' || dueMap.has(cid))
+                        continue;
+                    const date = asDate(entry.check_by);
+                    if (date && date > today && date <= horizon) {
+                        upcoming.push({ id: cid, predicate: entry.text || '', check_by: date });
+                    }
+                }
+                upcoming.sort((x, y) => (x.check_by < y.check_by ? -1 : 1));
+            }
+            const upcomingLine = upcoming.length > 0
+                ? S.upcoming(upcoming.length, upDays)
+                : '';
+            // Ledger-corruption disclosure (11 P2-8): dropped_lines was counted in
+            // data.integrity but never SAID. Silence is not kindness — one factual
+            // sentence + the backup handle. No blame, no gate.
+            const integrityLine = ledger.integrity.dropped_lines > 0
+                ? S.dropped_lines(ledger.integrity.dropped_lines)
+                : '';
+            // Living premises: monitored facts due for a reality re-check, grouped so
+            // the same fact under several decisions is ONE re-check (plan v5 P1/P5).
+            const TOP = 5;
+            const premiseGroups = groupDuePremises(duePremises(ledger));
+            const duePrem = premiseGroups.slice(0, TOP).map((g) => ({
+                fact: g.text,
+                decisions: g.premises.map((p) => ({ decision_id: p.decision_id, decision: p.decision_text, ref: `P${p.ordinal}`, staleness: p.days_stale === null ? 'never re-checked' : `${p.days_stale}d` })),
+            }));
+            if (due.length === 0 && premiseGroups.length === 0) {
+                // Static hint, no network (P1-E4 ③ / master §5-18): check_in stays a
+                // local, deterministic read — but a token means the user ALSO seals in
+                // their account (web), and "nothing" here must not read as "nothing
+                // anywhere". One sentence, argus_sync is the one place that looks.
+                const accountHint = (process.env.ARGUS_TOKEN || '').trim()
+                    ? S.account_hint
+                    : '';
+                return envelope({
+                    ok: true, tool: 'argus_check_in',
+                    surface: S.nothing_due + accountHint + upcomingLine + integrityLine,
+                    next_actions: ['stop'],
+                    data: { due: [], due_count: 0, due_premises: [], due_premise_count: 0, ...(upDays > 0 ? { upcoming } : {}), today },
+                });
+            }
+            const parts = [];
+            if (due.length > 0) {
+                // 닻 거울: the OLDEST due item's seal-time words lead the surface
+                // (one quote only — the rest stay in data, no surface bloat). Falls
+                // back to the count-only line when there are no words to mirror.
+                const oldest = dueEnriched[0];
+                parts.push(oldest?.your_words_then && typeof oldest.days_since_seal === 'number'
+                    ? S.anchor_mirror(oldest.days_since_seal, due.length, clip(oldest.your_words_then, 200))
+                    : S.due_contracts(due.length));
+            }
+            if (premiseGroups.length > 0)
+                parts.push(S.due_premises(premiseGroups.length));
+            return envelope({
+                ok: true, tool: 'argus_check_in',
+                surface: parts.join(' ') + upcomingLine + integrityLine,
+                next_actions: due.length > 0 ? ['argus_settle'] : ['argus_recall'],
+                data: {
+                    due: dueEnriched, due_count: due.length,
+                    due_premises: duePrem, due_premise_count: premiseGroups.length,
+                    ...(premiseGroups.length > TOP ? { due_premises_truncated: `${premiseGroups.length} groups, showing ${TOP}` } : {}),
+                    ...(upDays > 0 ? { upcoming } : {}),
+                    today, integrity: ledger.integrity,
+                },
+            });
+        }
+        catch (e) {
+            return handleToolException('argus_check_in', e);
+        }
+    },
+};
+function daysBetween(from, to) {
+    const a = Date.parse(from + 'T00:00:00Z');
+    const b = Date.parse(to + 'T00:00:00Z');
+    if (Number.isNaN(a) || Number.isNaN(b))
+        return 0;
+    return Math.round((b - a) / 86400000);
+}
+/** Keep the mirrored quote a quote, not a wall — the full text stays in data. */
+function clip(s, max) {
+    return s.length <= max ? s : s.slice(0, max - 1) + '…';
+}
+function addDays(day, days) {
+    const t = Date.parse(day + 'T00:00:00Z');
+    if (Number.isNaN(t))
+        return day;
+    return new Date(t + days * 86400000).toISOString().slice(0, 10);
+}

package/dist/tools/errors.js

@@ -0,0 +1,23 @@
+import { toolError } from '../lib/envelope.js';
+import { ArgusDirError } from '../lib/argus-dir.js';
+import { PathSafetyError } from '../lib/safe-path.js';
+import { GuardError } from '../lib/state-machine.js';
+import { logError } from '../lib/log.js';
+/**
+ * Map a thrown exception to a spine-safe tool error envelope. Known typed
+ * errors carry their own code + recovery hint; anything else is an internal
+ * error (logged to stderr, never stdout).
+ */
+export function handleToolException(tool, e) {
+    if (e instanceof ArgusDirError) {
+        return toolError({ ok: false, tool, error_code: e.code, message: e.message, recovery: 'Pass an absolute .argus path with no "..".' });
+    }
+    if (e instanceof PathSafetyError) {
+        return toolError({ ok: false, tool, error_code: e.code, message: e.message, recovery: 'Use ids/labels matching [A-Za-z0-9._-] only.' });
+    }
+    if (e instanceof GuardError) {
+        return toolError({ ok: false, tool, error_code: e.code, message: e.message, recovery: e.recovery });
+    }
+    logError(`[${tool}] unhandled`, e);
+    return toolError({ ok: false, tool, error_code: 'INTERNAL_ERROR', message: String(e instanceof Error ? e.message : e) });
+}

package/dist/tools/index.js

@@ -0,0 +1,14 @@
+import { openDecision } from './open-decision.js';
+import { seal } from './seal.js';
+import { settle } from './settle.js';
+import { checkIn } from './check-in.js';
+import { recall } from './recall.js';
+import { amend, dismiss } from './amend-dismiss.js';
+import { init, config } from './init-config.js';
+import { review } from './review.js';
+import { sync } from './sync.js';
+import { premises } from './premises.js';
+import { recheck } from './recheck.js';
+/** The full registered tool set. There is deliberately no verdict/grade/score tool. */
+export const TOOLS = [openDecision, review, premises, seal, recheck, settle, checkIn, recall, sync, amend, dismiss, init, config];
+export const TOOL_MAP = new Map(TOOLS.map((t) => [t.name, t]));

package/dist/tools/init-config.js

@@ -0,0 +1,99 @@
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import yaml from 'js-yaml';
+import { configPath, sessionsRoot, ledgerDir } from '../lib/layout.js';
+import { atomicWriteText } from '../lib/atomic-write.js';
+import { detectLocale } from '../lib/locale.js';
+import { resolveToolArgusDir, writeBoundMarker } from '../lib/argus-dir.js';
+import { ensurePrivacyGitignore } from '../lib/privacy.js';
+import { replayLedger } from '../lib/ledger-replay.js';
+import { resolveToday } from '../lib/resolve-today.js';
+import { SCHEMA_VERSION } from '../lib/spine.js';
+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';
+function readConfig(dir) {
+    try {
+        return yaml.load(fsSync.readFileSync(configPath(dir), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export const init = {
+    name: 'argus_init',
+    description: 'Initialize the .argus directory (sessions, ledger, config, privacy .gitignore) and bind it for resource reads. Call once before other tools. Safe to call again.',
+    inputSchema: z.strictObject({ argus_dir: zArgusDir }),
+    outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+    annotations: { title: 'Initialize Argus', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (a) => {
+        try {
+            const dir = resolveToolArgusDir(a['argus_dir']);
+            await fs.mkdir(sessionsRoot(dir), { recursive: true });
+            await fs.mkdir(ledgerDir(dir), { recursive: true });
+            await ensurePrivacyGitignore(dir);
+            writeBoundMarker(dir);
+            if (!fsSync.existsSync(configPath(dir))) {
+                const cfg = { schema_version: SCHEMA_VERSION, locale: detectLocale(dir), boss: null, team: null, archive: null };
+                await atomicWriteText(configPath(dir), yaml.dump(cfg));
+            }
+            const today = resolveToday({});
+            const empty = replayLedger(dir, today).ids.size === 0;
+            // TZ visibility (12 §3.3): expose today + tz so an install in KST notices
+            // "today is yesterday" immediately instead of at the first missed check-in.
+            // Default stays UTC (blueprint M4 determinism) — this is disclosure only.
+            const tz = process.env['ARGUS_TZ'] || 'UTC (set ARGUS_TZ to change)';
+            return envelope({
+                ok: true, tool: 'argus_init',
+                surface: empty
+                    ? 'Argus is ready. It does not give answers — it records a prediction + a check-by date and meets reality on that date. Open your first decision with argus_open_decision.'
+                    : 'Argus is ready.',
+                next_actions: empty ? ['argus_open_decision'] : ['argus_check_in'],
+                data: { initialized: true, argus_dir: dir, today, tz },
+            });
+        }
+        catch (e) {
+            return handleToolException('argus_init', e);
+        }
+    },
+};
+export const config = {
+    name: 'argus_config',
+    description: 'Read or update non-spine settings (locale, boss, team, archive). Passing only argus_dir reads; passing fields merges and writes. There is no setting that turns off falsifiability, seal-before-settle, or honest provenance — the spine is not configurable.',
+    inputSchema: z.strictObject({
+        argus_dir: zArgusDir,
+        locale: z.enum(['ko', 'en']).optional(),
+        boss: z.string().optional(),
+        team: z.string().optional(),
+        archive: z.boolean().optional(),
+    }),
+    outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+    annotations: { title: 'Read/update settings', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (a) => {
+        try {
+            const dir = resolveToolArgusDir(a['argus_dir']);
+            const writeKeys = ['locale', 'boss', 'team', 'archive'].filter((k) => k in a);
+            const existing = readConfig(dir) ?? { schema_version: SCHEMA_VERSION, locale: detectLocale(dir), boss: null, team: null, archive: null };
+            if (writeKeys.length === 0) {
+                return envelope({ ok: true, tool: 'argus_config', surface: 'Config read.', next_actions: ['stop'], data: { config: existing, existed: !!readConfig(dir) } });
+            }
+            if ('locale' in a && a['locale'] !== 'ko' && a['locale'] !== 'en') {
+                return toolError({ ok: false, tool: 'argus_config', error_code: 'INVALID_LOCALE', message: 'locale must be "ko" or "en".' });
+            }
+            const merged = {
+                ...existing,
+                schema_version: SCHEMA_VERSION,
+                ...(('locale' in a) ? { locale: a['locale'] } : {}),
+                ...(('boss' in a) ? { boss: a['boss'] } : {}),
+                ...(('team' in a) ? { team: a['team'] } : {}),
+                ...(('archive' in a) ? { archive: a['archive'] } : {}),
+            };
+            await atomicWriteText(configPath(dir), yaml.dump(merged));
+            return envelope({ ok: true, tool: 'argus_config', surface: 'Config updated.', next_actions: ['stop'], data: { config: merged } });
+        }
+        catch (e) {
+            return handleToolException('argus_config', e);
+        }
+    },
+};

package/dist/tools/open-decision.js

@@ -0,0 +1,128 @@
+import { atomicWriteJson } from '../lib/atomic-write.js';
+import { sessionFilePath } 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 { overfireGate } from '../lib/overfire-gate.js';
+import { validateCrux } from '../lib/validate-crux.js';
+import { computeContinuity } from '../lib/continuity.js';
+import { appendLedger } from '../lib/ledger-append.js';
+import { ensurePrivacyGitignore } from '../lib/privacy.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.min(1).max(128).describe('Single identifier for this decision (used as the file segment). A new decision gets a new id.'),
+    decision: z.string().min(1).max(600).describe('The choice the user actually faces, in one neutral sentence. A choice, not an opinion.'),
+    stakes: z.enum(['trivial', 'low', 'moderate', 'high']).describe('Cost of being wrong. If between two, pick the lower (restraint default).'),
+    reversibility: z.enum(['one_way_door', 'costly_to_reverse', 'easily_reversible']),
+    status_quo: z.string().min(1).max(300).describe('What happens if nothing is done — so "leave_as_is" is always a real option.'),
+    already_decided: z.boolean().default(false),
+    user_question: z.string().max(600).optional(),
+    crux_question: z.string().max(400).describe('The ONE neutral load-bearing question, phrased as a question. Never a fork, never a lean.').optional(),
+    load_bearing_assumption: z.string().max(400).describe('The single assumption the decision rests on (neutral).').optional(),
+    related_to: z.array(zId).max(20).describe('Ids of past decisions the user considers similar — surfaces a frequency-only track record, never a verdict.').optional(),
+    today_override: zDate.optional(),
+});
+// Restraint reasons → human sentences (11 P2-1/S6). Each names WHY no fork is
+// manufactured; the caller appends the fixed handle-return coda. 'flat' is kept
+// for forward-compat even though the current gate never emits it.
+const REASON_LINE = {
+    vent: 'This reads like something to say out loud, not a fork to force.',
+    factual: 'This is a question with an answer, not a decision to open.',
+    already_closed: 'You already made this call. Argus does not reopen it.',
+    flat: 'The options are close to even — no load-bearing question to manufacture.',
+    reversible_low_stakes: 'Cheap to undo and little at stake — trying it IS the test.',
+    low_stakes: 'Little rides on this — the steady move is to leave it as is.',
+};
+export const openDecision = {
+    name: 'argus_open_decision',
+    description: 'Open a consequential decision. Runs a fire-or-not restraint gate FIRST; if it fires, surfaces at most one neutral crux question and a "leave as is" option. Never a fork, never a verdict, never a lean. On flat/low-stakes/reversible/closed decisions it returns restraint.',
+    inputSchema,
+    outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+    annotations: { title: 'Open a decision', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    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);
+            if (a['already_decided'] === true && (current.state === 'sealed' || current.state === 'due' || current.state === 'settled')) {
+                return toolError({
+                    ok: false, tool: 'argus_open_decision', error_code: 'ALREADY_CLOSED',
+                    message: 'This decision is already underway or closed.',
+                    recovery: 'To check reality, call argus_settle. Closed decisions are not reopened.',
+                });
+            }
+            const signals = {
+                stakes: a['stakes'],
+                reversibility: a['reversibility'],
+                already_decided: a['already_decided'] === true,
+            };
+            const gate = overfireGate(signals);
+            const now = new Date().toISOString();
+            // Always log the gate inputs for post-hoc accuracy measurement (M2).
+            await appendLedger(dir, [{ id, event: 'gate_input', gate: { ...signals, verdict: gate.reason } }], now);
+            if (gate.response === 'reconfirm') {
+                return envelope({
+                    ok: true, tool: 'argus_open_decision',
+                    surface: 'These signals look contradictory (high stakes yet easily reversible). Re-confirm stakes and reversibility before going further.',
+                    next_actions: ['argus_open_decision', 'leave_as_is'],
+                    over_fire_gate: { fired: false, reason: gate.reason },
+                    data: { id, crux_question: null, restraint_option: a['status_quo'], fork_emitted: false, harvest_written: false },
+                });
+            }
+            if (!gate.fire) {
+                return envelope({
+                    ok: true, tool: 'argus_open_decision',
+                    // Human sentence, not a snake_case enum (11 P2-1). Contract (§4): the
+                    // line ENDS by naming the option and returning the handle — never a
+                    // directive ("leave it") issued in the user's stead.
+                    surface: `${REASON_LINE[gate.reason] ?? 'No fork to manufacture here.'} Leaving it as is stays a real option.`,
+                    next_actions: ['leave_as_is', 'skip'],
+                    over_fire_gate: { fired: false, reason: gate.reason },
+                    data: { id, crux_question: null, restraint_option: a['status_quo'], fork_emitted: false, harvest_written: false },
+                });
+            }
+            // FIRE: validate any model-supplied crux, persist the harvest.
+            const cruxErr = validateCrux(a['crux_question']);
+            if (cruxErr) {
+                return toolError({ ok: false, tool: 'argus_open_decision', error_code: cruxErr.code, message: cruxErr.message, recovery: cruxErr.recovery });
+            }
+            await ensurePrivacyGitignore(dir);
+            await atomicWriteJson(sessionFilePath(dir, id), {
+                v: SCHEMA_VERSION, id, problem_text: a['decision'], status_quo: a['status_quo'],
+                load_bearing_assumption: a['load_bearing_assumption'] ?? null, created_at: now,
+            });
+            await appendLedger(dir, [{ id, event: 'harvest', decision: a['decision'] }], now);
+            const crux = a['crux_question'] ?? null;
+            const relatedIds = Array.isArray(a['related_to']) ? a['related_to'] : [];
+            const continuity = relatedIds.length ? computeContinuity(dir, relatedIds) : undefined;
+            return envelope({
+                ok: true, tool: 'argus_open_decision',
+                surface: crux
+                    ? `Opened. The one question that decides this: ${crux}`
+                    : 'Opened. Surface exactly ONE neutral crux question (a question, not a fork or a lean), then seal a falsifiable prediction.',
+                next_actions: ['argus_seal', 'leave_as_is', 'skip'],
+                over_fire_gate: { fired: true, reason: gate.reason },
+                data: {
+                    id,
+                    crux_question: crux,
+                    crux_question_provenance: crux ? 'ai_surfaced' : undefined,
+                    load_bearing_assumption: a['load_bearing_assumption'] ?? null,
+                    restraint_option: a['status_quo'],
+                    fork_emitted: false,
+                    harvest_written: true,
+                    continuity,
+                    lean_disclosure: 'Naming the load-bearing question points faintly at the flip; that residual lean is a known limit, not a verdict.',
+                },
+            });
+        }
+        catch (e) {
+            return handleToolException('argus_open_decision', e);
+        }
+    },
+};