argus-decision-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Argus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# argus-decision-mcp
+
+> **Your AI gives you an answer. Argus gives you a receipt — and checks it against reality on the date you set.**
+
+Argus is an MCP server for **decision accountability**. Instead of grading your
+choices, it makes you write down a *falsifiable prediction* and a *check-by
+date*, then brings you back on that date to compare what you predicted against
+what actually happened. The artifact it produces — a **Judgment Receipt** —
+carries one line no other AI tool will: `AI VERDICT … NONE`. The model never
+graded you. Reality did.
+
+Works with any MCP host — Claude, ChatGPT, Gemini, or any MCP-compatible client.
+
+```
+┌─ ARGUS · JUDGMENT RECEIPT ────────────────────────────────┐
+  Sealed 2026-04-02      Settled 2026-06-30
+
+  THE REAL QUESTION
+    Can we cut over without a maintenance window users notice?
+  THE UNVERIFIED ASSUMPTION
+    The index rebuild fits inside the replication lag budget.
+  HUMAN-ONLY CALL   Whether a 5-minute blip is acceptable.
+  …made by          Me. (not the model)
+
+  YOU PREDICTED   "Cutover downtime is under 5 minutes"   (check-by 2026-06-30)
+  WHAT HAPPENED   Cutover took 3 minutes, no customer reports.
+  ─────────────────────────────────────────────────────────
+  AI VERDICT ON THIS DECISION ······················  NONE
+  The model never graded you. Reality did.
+└──────────────────────────────────  argus · seal → settle ─┘
+```
+
+## Why it's different
+
+Most decision tools compete on a *better answer*, a *score*, a *confidence*.
+Argus does the opposite, and the opposite is enforced **structurally**, not
+promised in prose:
+
+- **There is no verdict tool.** The model cannot grade your decision because no
+  `argus_verdict` / `argus_score` tool exists to call. `grep dist/` and see.
+- **You can't settle what you never sealed.** `argus_settle` hard-errors without
+  a prior `argus_seal` — "no judgment without a falsifiable bet" is a
+  precondition, not a suggestion.
+- **State is the ledger, not a flag.** A decision's status is the fold of an
+  append-only event log, so it can't be faked by calling tools out of order.
+
+## Install
+
+Claude Code:
+
+```bash
+claude mcp add argus -- npx -y argus-decision-mcp
+```
+
+Or add to your host's MCP config:
+
+```jsonc
+{
+  "mcpServers": {
+    "argus": {
+      "command": "npx",
+      "args": ["-y", "argus-decision-mcp"],
+      "env": {
+        // Set this ONCE and you never pass argus_dir again — every tool falls
+        // back to it. Claude Code expands ${CLAUDE_PROJECT_DIR}; on other hosts
+        // put an absolute path here (or pass argus_dir per call).
+        "ARGUS_DIR": "${CLAUDE_PROJECT_DIR}/.argus",
+        // OPTIONAL — connect to your Argus account so sealed predictions get an
+        // email at their check-by date (the Companion Brief) and show up in the
+        // web dashboard. Issue the token in the web app. Leave it unset to stay
+        // fully local (the privacy-preserving default).
+        "ARGUS_TOKEN": "argus_pat_…",
+        // OPTIONAL — the timezone that decides when a check-by date becomes
+        // "today". Unset = UTC, which for Korean users means the day flips at
+        // 9am KST (a due decision won't show until then). Set your zone:
+        "ARGUS_TZ": "Asia/Seoul"
+        // "ARGUS_API_URL": "https://argus.voyage"  // override only for self-host
+      }
+    }
+  }
+}
+```
+
+> `argus_dir` is **optional** on every tool: omit it and it resolves from
+> `ARGUS_DIR`. A per-call `argus_dir` still wins — so Argus works on any host
+> even when env-variable interpolation doesn't.
+
+## The loop
+
+| Tool | What it does |
+|------|--------------|
+| `argus_open_decision` | Opens a consequential decision. Runs a restraint gate first — on a flat / low-stakes / reversible / already-closed call it tells you to leave it as is. If it fires, it surfaces **one** neutral question, never a fork or a lean. |
+| `argus_review` | Reviews an existing document (strategy memo / PRD / deck text / AI answer) for judgment risk: reviewability score, routed lenses, source units with anchors, and the extraction prompt — then hands the analysis to you. Degrades honestly on unextractable input; never a verdict. End by sealing one follow-up. |
+| `argus_seal` | Seals a falsifiable prediction (`predicate` + `check_by`) and captures the receipt's real-question / unverified-assumption / human-only / your-call fields. Refuses an empty predicate or a non-future date. If you seal without naming the assumption, it's recorded as an explicit **skip** — never a forced gate (which would just eject the tiredest user), never a silent blank. With `ARGUS_TOKEN` set, the prediction also syncs to your account so the Companion Brief can email you at its check-by date. |
+| `argus_premises` | Tracks the **premises** a decision rests on — the facts and open questions behind it. `add` records them (echoed back in full); `amend` takes your correction verbatim (the AI's original stays on the record — the edit is the signal); `resolve` closes an open question **in your own words** (it cannot offer options or leans — that shape doesn't exist here). Premises lock once the check-by arrives: no retroactive premise-planting, no retiring the one about to be proven wrong. |
+| `argus_recheck` | Re-checks one premise against reality between seal and settle. The host researches the current fact; the tool compares **explicit numbers** mechanically (never regex-parses prose) or records the host's provenance-tagged `changed` assertion for text facts. First check is a baseline and never alerts. When the fact drifted: it says so and returns the handle — whether to revisit the decision stays your call. `apply_to_matching` re-checks the same fact under your other decisions at once. |
+| `argus_settle` | On the check-by date, records what reality did and issues the Judgment Receipt. Hard-errors without a prior seal. Optionally records **which premise broke** (your attribution, never inferred) — over time your track record can say "3 of your 4 missed bets traced to a broken external premise": a frequency, never a diagnosis. |
+| `argus_amend` | Changes the predicate or check-by date **before** reality answers — a course change, not an erasure (the original stays on the append-only ledger). Hard-errors once the decision is settled. |
+| `argus_dismiss` | Closes a decision **without settling** — it became irrelevant, was decided elsewhere, or you changed your mind. No verdict is recorded; terminal, not reopened. |
+| `argus_check_in` | Returns contracts past their check-by date **and premise facts due for a re-check** (the same fact under several decisions is one re-check). If nothing is due, it says so and stops — it doesn't manufacture engagement. |
+| `argus_sync` | Pulls your account receipts into the terminal (live judgments + what's due) so you can settle here. Seals push automatically; this is the read side. Requires `ARGUS_TOKEN`. |
+| `argus_recall` | Reads your own history: a receipt, the open contracts, or a sample-size-caveated track record (never a tier or score). |
+| `argus_init` / `argus_config` | Initialize the `.argus` directory; read/write non-spine settings. |
+
+## Living premises
+
+The receipt's sharpest line — `THE UNVERIFIED ASSUMPTION` — used to be written
+once at seal and then go dead. Now it's a **tracked object**: name the premises
+a decision rests on, correct the ones the model got wrong (your edit is part of
+the record), and re-check the load-bearing external facts against reality while
+the bet is still open. When a rate hike breaks the premise under three of your
+decisions, that's **one** re-check, not three.
+
+Honest limits, stated up front: an MCP server is passive — nothing wakes it
+between seal and settle. The return loop rides four levers: every tool response
+carries a quiet `due_note`; `argus_check_in` reports due premises;
+the `argus://premises/due` resource lets hosts auto-inject them; and the
+`/argus-settle` ritual includes the re-check choreography. Anything more
+periodic (cron, reminders) belongs to your host or habits, not this server.
+A premise that never gets re-checked shows up honestly as `never re-checked` —
+Argus does not pretend liveness.
+
+## Data
+
+Everything is local, under `.argus/` in your project (gitignored by default) —
+an append-only `ledger.jsonl` **you own**: plain JSON lines, no lock-in,
+receipts render to shareable text. No telemetry. The **only** network call
+Argus ever makes is the opt-in account sync: if — and only if — you set
+`ARGUS_TOKEN`, a sealed/settled prediction is POSTed to your own Argus account
+so it can email you at its check-by date. **Premise data never leaves your
+machine** — it is not part of the sync payload. Unset the token and Argus never
+touches the network. See [SECURITY.md](SECURITY.md).
+
+## Measured
+
+The structural claims are tested, not asserted — `npm test` runs deterministic
+gates (no verdict tool exists, settle-without-seal refused, path traversal
+blocked, receipts carry `ai_verdict: null`). A model-in-the-loop spine eval
+(`npm run eval`, 12 scenarios, opus judge) measured, across Sonnet 4.6 and
+Haiku 4.5:
+
+| | over-fire on flat cases | crux carries a lean | free-text verdict leak |
+|---|---|---|---|
+| Sonnet 4.6 | 0 / 6 | 0 / 12 | 0 / 12 |
+| Haiku 4.5 | 0 / 6 | 0 / 12 | 1 / 12 |
+
+Tool-surface verdict leak is **0 by construction**. The one free-text leak
+(Haiku, on "salad or sandwich") is exactly the limit below — a model can still
+type an opinion in chat, and Argus reports that number rather than hiding it.
+
+## An honest limit
+
+Argus removes the verdict from its *tool surface* and walls off settling a bet
+that was never made. It cannot stop a model from typing an opinion in free chat
+between tool calls — no MCP server can. So Argus doesn't claim "zero judgment";
+it surfaces one question, names any faint lean as a known limit, and lets
+reality do the grading. `zero judgment` is an asymptote, disclosed — not a badge.
+
+## Develop
+
+```bash
+npm install
+npm run build
+npm test          # deterministic spine + state-machine + path-safety gates
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+MIT licensed.

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security
+
+## Data & privacy
+
+- **All data is local.** Argus writes only under the `.argus/` directory you
+  point it at: an append-only `ledger/ledger.jsonl`, per-decision
+  `sessions/{id}/` files, and a `config.yaml`. Nothing leaves the machine.
+- **No telemetry, no network.** The runtime dependency surface is two packages
+  (`@modelcontextprotocol/sdk`, `js-yaml`). `npm ls --prod` should show no
+  analytics or network client. CI fails if the production dependency tree grows.
+- **Private by default.** `argus_init` adds `sessions/`, `ledger/`, and `.bound`
+  to `.argus/.gitignore` so your decisions are never committed.
+
+## Threat model
+
+Argus runs as a local stdio MCP server. Tool arguments are produced by an LLM
+and may be influenced by untrusted context, so:
+
+- **Path traversal.** Every `id` / label flows through a single `safeSegment`
+  validator (`[A-Za-z0-9._-]`, no `..`, no separators, no percent-encoding) and
+  every built path is checked with `assertInside`, which resolves the deepest
+  existing ancestor via `realpath` so a symlink/junction can't be used to escape
+  `.argus/`. Covered by `safe-path.test.ts` (incl. Windows `..\`, `%2e`).
+- **Ledger integrity.** The ledger is trusted local state; its integrity rests
+  on filesystem permissions. v1 does **not** sign entries — a process with write
+  access to `.argus/` could append a forged `settle`. Replay counts unparseable
+  lines and surfaces `integrity.dropped_lines` rather than silently swallowing a
+  torn record. If you need tamper-evidence, keep `.argus/` on a controlled path.
+- **Diagnostics never touch stdout.** A stdio server must keep stdout clean for
+  JSON-RPC framing; all logging goes to stderr (`ARGUS_DEBUG` for verbose).
+
+## Reporting
+
+Open a private security advisory on the repository, or email the maintainer.
+Please don't file public issues for vulnerabilities.

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { createServer } from './server.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+async function main() {
+    const server = await createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.on('SIGINT', async () => {
+        await server.close();
+        process.exit(0);
+    });
+}
+main().catch(console.error);

package/dist/lib/argus-dir.js

@@ -0,0 +1,85 @@
+import fs from 'fs';
+import path from 'path';
+import { boundMarkerPath } from './layout.js';
+/**
+ * argus_dir resolution + precedence (blueprint §4.0 + addendum A/B).
+ *
+ * The `${workspaceFolder}` config variable only expands in VS Code — Claude
+ * Code expands `${CLAUDE_PROJECT_DIR}`, others expand nothing. So env
+ * interpolation is the LEAST reliable channel and must come last. Tools always
+ * receive a per-call `argus_dir`, which works on every host, so that wins.
+ *
+ * Precedence:
+ *   1. per-call `argus_dir` argument            (works on every host)
+ *   2. last dir written to `.bound` by argus_init (read-side for Resources)
+ *   3. ARGUS_DIR env                            (host-dependent interpolation)
+ */
+export class ArgusDirError extends Error {
+    code = 'ARGUS_DIR_INVALID';
+    constructor(message) {
+        super(message);
+        this.name = 'ArgusDirError';
+    }
+}
+/** Validate a per-call argus_dir: must be an absolute path, no traversal segments. */
+export function requireArgusDir(callArg) {
+    if (typeof callArg !== 'string' || callArg.length === 0) {
+        throw new ArgusDirError('argus_dir is required (absolute path to the .argus directory).');
+    }
+    const resolved = path.resolve(callArg);
+    if (!path.isAbsolute(callArg)) {
+        throw new ArgusDirError('argus_dir must be an absolute path.');
+    }
+    if (callArg.split(/[\\/]/).some((seg) => seg === '..')) {
+        throw new ArgusDirError("argus_dir must not contain '..'.");
+    }
+    return resolved;
+}
+/**
+ * Resolve argus_dir for a TOOL call, implementing the full precedence the
+ * blueprint promised (§4.0): a per-call `argus_dir` wins, else the `ARGUS_DIR`
+ * env var. This is the ergonomic win — set ARGUS_DIR once in the MCP config and
+ * never pass the path again. Both channels get the same path-safety validation;
+ * omitting both yields one clear, actionable error.
+ */
+export function resolveToolArgusDir(callArg) {
+    if (typeof callArg === 'string' && callArg.length > 0)
+        return requireArgusDir(callArg);
+    const env = process.env['ARGUS_DIR'];
+    if (typeof env === 'string' && env.length > 0)
+        return requireArgusDir(env);
+    throw new ArgusDirError('No argus_dir given and ARGUS_DIR is not set. Pass an absolute argus_dir, or set "ARGUS_DIR" in your MCP config env (then you can omit it every call).');
+}
+/** Record the bound dir so Resources (which get no args) can find it later. */
+export function writeBoundMarker(argusDir) {
+    try {
+        const envDirs = readBoundList(argusDir);
+        if (!envDirs.includes(argusDir))
+            envDirs.unshift(argusDir);
+        fs.writeFileSync(boundMarkerPath(argusDir), JSON.stringify({ bound: envDirs.slice(0, 8) }), 'utf8');
+    }
+    catch {
+        /* non-critical */
+    }
+}
+function readBoundList(argusDir) {
+    try {
+        const raw = fs.readFileSync(boundMarkerPath(argusDir), 'utf8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.bound) ? parsed.bound.filter((x) => typeof x === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Resolve argus_dir for a Resource read (no per-call arg available).
+ * Returns null (unbound) rather than throwing — the Resource degrades cleanly.
+ */
+export function resolveArgusDirForResource() {
+    const env = process.env['ARGUS_DIR'];
+    if (typeof env === 'string' && env.length > 0 && path.isAbsolute(env)) {
+        return path.resolve(env);
+    }
+    return null;
+}

package/dist/lib/atomic-write.js

@@ -0,0 +1,19 @@
+import fs from 'fs/promises';
+import path from 'path';
+export async function atomicWriteJson(filePath, data) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    const tmp = filePath + '.tmp.' + process.pid;
+    const json = JSON.stringify(data, null, 2);
+    // Verify it round-trips before committing
+    JSON.parse(json);
+    await fs.writeFile(tmp, json, 'utf8');
+    await fs.rename(tmp, filePath);
+}
+export async function atomicWriteText(filePath, text) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    const tmp = filePath + '.tmp.' + process.pid;
+    await fs.writeFile(tmp, text, 'utf8');
+    await fs.rename(tmp, filePath);
+}

package/dist/lib/continuity.js

@@ -0,0 +1,31 @@
+import { readReceipt } from './receipt.js';
+/**
+ * Track-record continuity (addendum L — the n=1 moat). Given past decision ids
+ * the user tags as similar, report a sample-size-scaled frequency statement.
+ * NEVER a verdict, never "you tend to..." — frequency only, with a small-sample
+ * caveat (spine rule 2).
+ */
+export function computeContinuity(argusDir, relatedIds) {
+    const related = [];
+    let held = 0, settled = 0;
+    for (const id of relatedIds) {
+        const r = readReceipt(argusDir, id);
+        if (!r)
+            continue;
+        related.push({ id, outcome: r.outcome, predicate: r.predicate });
+        if (r.outcome) {
+            settled++;
+            if (r.outcome === 'held')
+                held++;
+        }
+    }
+    const frequency_statement = settled === 0
+        ? 'No settled history among the decisions you tagged as similar.'
+        : `Of ${settled} similar decision(s) you settled: ${held} held, ${settled - held} did not.`;
+    return {
+        related,
+        frequency_statement,
+        sample_size: settled,
+        sample_size_caveat: settled > 0 && settled < 10 ? 'Sample is small — read this as history, not a pattern about you.' : undefined,
+    };
+}

package/dist/lib/deBom.js

@@ -0,0 +1,3 @@
+export function deBom(s) {
+    return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
+}

package/dist/lib/discipline.js

@@ -0,0 +1,42 @@
+/**
+ * Single source for the spine DISCIPLINE prose (blueprint §4.2 + addendum K).
+ *
+ * This is where the killed copy-paste system prompt now lives — but as
+ * server-defined MCP Prompts the user explicitly turns on, not a string they
+ * paste. Every prompt message and the reframe thesis render from here so the
+ * three surfaces (webapp / plugin / mcp) cannot drift. The server `instructions`
+ * field (spine.ts) and these prompts are the only prose; everything load-bearing
+ * is structure.
+ */
+export const BIND_DISCIPLINE = [
+    'You are running the Argus BIND ritual. Hold this order, do not skip a step:',
+    '',
+    'STEP 0 — fire or not. Is this a genuinely consequential, hard-to-reverse fork? If it is flat, low-stakes, easily reversible, or already decided, say so and stop — recommend leaving it as is. Do not manufacture a decision.',
+    'STEP 1 — one question. If it fires, surface the SINGLE load-bearing assumption as ONE neutral question. Not a fork ("A or B?"), not a lean ("the stronger case is..."), not advice. A question.',
+    'STEP 2 — seal a bet. Help the user commit a falsifiable prediction (a predicate reality can mark true/false) and a check-by date, then call argus_seal. The prediction is the user\'s — never relabel an Argus-drafted line as theirs.',
+    '',
+    'You are the recorder, not the judge. Never tell the user their decision is right or wrong.',
+].join('\n');
+export const SETTLE_DISCIPLINE = [
+    'You are running the Argus SETTLE ritual.',
+    '',
+    'For each contract past its check-by date, ask the user what reality did — held, avoided, partial, or still pending. Record what they say with argus_settle; never infer the outcome yourself.',
+    'Settlement is a single commitment against reality, not a debate with the model. The outcome belongs to the user.',
+    'The receipt carries no AI verdict. Reality settles it.',
+].join('\n');
+export const REVIEW_DISCIPLINE = [
+    'You are running the Argus REVIEW ritual on an existing document (strategy memo / PRD / deck text / AI answer).',
+    '',
+    'STEP 0 — call argus_review with the document text (or a .md/.txt path). It returns a reviewability score, the routed lenses, and the source units with anchors. If it degrades honestly (unextractable / too thin), surface what is missing and stop — do not fake a review.',
+    'STEP 1 — build the judgment map. Run the returned extraction_prompt over the units: profile, core question, claims (supported/weak/unsupported), unspoken assumptions, decision points. Anchor everything to a unit; never expose a unit_id in prose.',
+    'STEP 2 — apply each routed lens. Emit only findings that reference a specific claim/unit. No generic advice ("리스크를 고려하세요"). Separate what only a HUMAN can judge (judgment obligations) — do not decide it for them.',
+    'STEP 3 — seal one bet. Pull the single most falsifiable follow-up prediction and seal it with argus_seal (predicate + pass/fail + check-by). The prediction is the user\'s.',
+    '',
+    'You are the recorder, not the judge. No verdict on the document ("이 전략은 틀렸다", "진행하세요"). Surface the risks anchored to the source; the judgment stays the user\'s.',
+].join('\n');
+export const REFRAME_DISCIPLINE = [
+    'You are running the Argus REFRAME lens — the generative half of the spine (surface assumptions; do not judge).',
+    '',
+    'Surface the hidden assumptions buried in the user\'s question — the ones that, if false, change the answer. For each, name the axis it sits on and what becomes true if it is wrong. Tag them as ai_surfaced (Argus raised them, the user has not confirmed them).',
+    'Frame as "참고:" / "worth noticing:" — reference, not directive. Do NOT recommend a direction, do NOT rank the options, do NOT decide. The point is to sharpen the question, not to answer it.',
+].join('\n');

package/dist/lib/due-note.js

@@ -0,0 +1,54 @@
+import { replayLedger } from './ledger-replay.js';
+import { duePremises, groupDuePremises } from './premises.js';
+import { resolveToolArgusDir } from './argus-dir.js';
+import { resolveToday } from './resolve-today.js';
+/**
+ * Dispatch-level due-note piggyback (plan v5 §5-2, restraint rules §3.4).
+ *
+ * An MCP server is passive — nothing wakes it between seal and settle. The one
+ * moment it reliably has is WHEN THE USER IS ALREADY HERE: any successful tool
+ * call. So the dispatcher quietly annotates every ok-envelope with what is due.
+ *
+ * Restraint, by construction:
+ *  - counts only, in `data.due_note` — the surface line stays about the tool
+ *    that was called; whether to raise the note is the HOST's choice
+ *  - absent entirely at zero (an empty nag cannot be expressed)
+ *  - argus_check_in is skipped (it IS the due surface — no duplication)
+ *  - never overwrites a due_note a tool set itself; never touches errors
+ *  - any internal failure returns the result untouched (a broken note must
+ *    never tax the tool call that succeeded)
+ */
+const SKIP_TOOLS = new Set(['argus_check_in']);
+export function appendDueNote(toolName, args, result) {
+    try {
+        if (result.isError || SKIP_TOOLS.has(toolName))
+            return result;
+        const sc = result.structuredContent;
+        if (!sc || sc['ok'] !== true)
+            return result;
+        const dir = resolveToolArgusDir(args['argus_dir']); // unbound → throws → untouched
+        const today = resolveToday({ override: args['today_override'] });
+        const state = replayLedger(dir, today);
+        const contractsDue = state.overdue.length;
+        const premiseFactsDue = groupDuePremises(duePremises(state)).length;
+        if (contractsDue === 0 && premiseFactsDue === 0)
+            return result;
+        const parts = [];
+        if (premiseFactsDue > 0)
+            parts.push(`${premiseFactsDue} premise fact(s) to re-check (argus_recheck)`);
+        if (contractsDue > 0)
+            parts.push(`${contractsDue} contract(s) to settle (argus_settle)`);
+        const data = (sc['data'] ??= {});
+        if (!('due_note' in data))
+            data['due_note'] = parts.join(' · ');
+        const na = sc['next_actions'];
+        if (Array.isArray(na) && !na.includes('argus_check_in'))
+            na.push('argus_check_in');
+        // Refresh the text mirror — envelope() serialized before this annotation.
+        result.content = [{ type: 'text', text: JSON.stringify(sc, null, 2) }];
+        return result;
+    }
+    catch {
+        return result;
+    }
+}

package/dist/lib/elicit.js

@@ -0,0 +1,30 @@
+/**
+ * Elicitation seam (MCP elicitation/create). Lets a tool ask the END USER a
+ * structured choice — the MCP-native equivalent of a choice+free-text picker —
+ * for spine-SAFE inputs only: settlement outcome, concern selection, predicate
+ * wording. Never for the decision crux (a multiple-choice crux is a fork, which
+ * the spine forbids).
+ *
+ * The server injects the real elicitor at startup. When the host doesn't support
+ * elicitation (many don't yet), `elicit` returns null and callers fall back to
+ * the text flow — no crash, no dead end.
+ */
+let _elicit = null;
+export function setElicitor(fn) {
+    _elicit = fn;
+}
+export function canElicit() {
+    return _elicit !== null;
+}
+/** Ask the user; returns null if unsupported / errored / not accepted. */
+export async function elicit(message, requestedSchema) {
+    if (!_elicit)
+        return null;
+    try {
+        const res = await _elicit(message, requestedSchema);
+        return res.action === 'accept' && res.content ? res.content : null;
+    }
+    catch {
+        return null; // host declared support but failed — fall back to text
+    }
+}

package/dist/lib/envelope.js

@@ -0,0 +1,13 @@
+export function envelope(e) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(e, null, 2) }],
+        structuredContent: e,
+    };
+}
+export function toolError(e) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(e, null, 2) }],
+        structuredContent: e,
+        isError: true,
+    };
+}

package/dist/lib/layout.js

@@ -0,0 +1,32 @@
+import path from 'path';
+import { safeSegment, assertInside } from './safe-path.js';
+/**
+ * Filesystem layout (blueprint §3.0). `argus_dir` IS the `.argus/` directory.
+ *
+ * Single-identity model: one decision = one `id` = one directory
+ * `sessions/{id}/`. There is no `versions/{label}/` tier anymore (clean break).
+ * The bearing and the receipt live at fixed names inside the session dir.
+ *
+ * Every `id` flows through `safeSegment`, and every built path is checked with
+ * `assertInside` so a crafted id can never escape `.argus/`.
+ */
+export const sessionsRoot = (argusDir) => path.join(argusDir, 'sessions');
+export const ledgerDir = (argusDir) => path.join(argusDir, 'ledger');
+export const ledgerPath = (argusDir) => path.join(ledgerDir(argusDir), 'ledger.jsonl');
+export const configPath = (argusDir) => path.join(argusDir, 'config.yaml');
+export const boundMarkerPath = (argusDir) => path.join(argusDir, '.bound');
+export function sessionDir(argusDir, id) {
+    const root = sessionsRoot(argusDir);
+    const dir = path.join(root, safeSegment(id, 'id'));
+    assertInside(root, dir);
+    return dir;
+}
+export function bearingPath(argusDir, id) {
+    return path.join(sessionDir(argusDir, id), 'current_bearing.json');
+}
+export function receiptPath(argusDir, id) {
+    return path.join(sessionDir(argusDir, id), 'receipt.json');
+}
+export function sessionFilePath(argusDir, id) {
+    return path.join(sessionDir(argusDir, id), 'session.json');
+}

package/dist/lib/ledger-append.js

@@ -0,0 +1,27 @@
+import fs from 'fs';
+import fsP from 'fs/promises';
+import { ledgerPath, ledgerDir } from './layout.js';
+import { SCHEMA_VERSION } from './spine.js';
+export async function appendLedger(argusDir, events, now) {
+    await fsP.mkdir(ledgerDir(argusDir), { recursive: true });
+    const lPath = ledgerPath(argusDir);
+    const lines = events
+        .map((ev) => JSON.stringify({ v: SCHEMA_VERSION, ts: ev.ts || now, ...ev }))
+        .join('\n') + '\n';
+    await new Promise((resolve, reject) => {
+        let fd;
+        try {
+            fd = fs.openSync(lPath, fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_WRONLY);
+            fs.writeSync(fd, lines, null, 'utf8');
+            resolve();
+        }
+        catch (e) {
+            reject(e);
+        }
+        finally {
+            if (fd !== undefined)
+                fs.closeSync(fd);
+        }
+    });
+    return { written: events.length };
+}