argus-decision-mcp 1.0.0 → 1.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Argus
+Copyright (c) 2026 commet
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,5 +1,11 @@
 # argus-decision-mcp
 
+[![npm version](https://img.shields.io/npm/v/argus-decision-mcp.svg)](https://www.npmjs.com/package/argus-decision-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/argus-decision-mcp.svg)](https://www.npmjs.com/package/argus-decision-mcp)
+[![license](https://img.shields.io/npm/l/argus-decision-mcp.svg)](./LICENSE)
+
+> **Keeping Judgment Human.**
+
 > **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
@@ -9,11 +15,13 @@ 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.
+Runs on any MCP host that supports local **stdio** servers — Claude Desktop,
+Claude Code, and other clients that launch a local process. (Remote-only
+connectors that require an HTTP transport aren't supported yet — see the roadmap.)
 
 ```
 ┌─ ARGUS · JUDGMENT RECEIPT ────────────────────────────────┐
-  Sealed 2026-04-02      Settled 2026-06-30
+  Prediction saved 2026-04-02      Result recorded 2026-06-30
 
   THE REAL QUESTION
     Can we cut over without a maintenance window users notice?
@@ -27,19 +35,27 @@ Works with any MCP host — Claude, ChatGPT, Gemini, or any MCP-compatible clien
   ─────────────────────────────────────────────────────────
   AI VERDICT ON THIS DECISION ······················  NONE
   The model never graded you. Reality did.
-└──────────────────────────────────  argus · seal → settle ─┘
+└──────────────────────────  argus · prediction → reality ─┘
 ```
 
 ## Why it's different
 
+**It is not a receipt of what your *agent* did.** A growing set of tools now
+log an AI coding run — prompt captured, files touched, checkpoint saved, replay
+path written down. That receipt is about the *machine's* actions over one run.
+Argus receipts something no run-logger can: *your* judgment call, in your own
+words, opened again on a date you set and settled against **reality** — not
+against a model's opinion, and not against a diff. Machine-action receipts and
+judgment receipts are different primitives; you can keep both.
+
 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
+- **You can't record a result without a saved prediction.** `argus_resolve`
+  hard-errors without a prior `argus_predict` — "no judgment without a falsifiable prediction" 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.
@@ -52,7 +68,10 @@ Claude Code:
 claude mcp add argus -- npx -y argus-decision-mcp
 ```
 
-Or add to your host's MCP config:
+Or add to your host's MCP config. **Zero config works**: with no `env` at all,
+your ledger lives in `~/.argus`.
+
+**Claude Code** (expands `${CLAUDE_PROJECT_DIR}`, so a per-project ledger works):
 
 ```jsonc
 {
@@ -61,19 +80,21 @@ Or add to your host's MCP config:
       "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).
+        // OPTIONAL — per-project ledger. Omit entirely to use ~/.argus.
         "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).
+        // web dashboard. Issue the token in the web app (Settings → sync token).
+        // 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"
+        // "today". Unset = your machine's local timezone (usually right).
+        // Set it only if your machine's clock zone isn't where you live:
+        "ARGUS_TZ": "Asia/Seoul",
+        // OPTIONAL — opt in to anonymous usage telemetry (OFF by default). Sends
+        // a random install id + which tool ran + version/platform; never your
+        // decisions or token. Honors DO_NOT_TRACK. See SECURITY.md → Telemetry.
+        "ARGUS_TELEMETRY": "1"
         // "ARGUS_API_URL": "https://argus.voyage"  // override only for self-host
       }
     }
@@ -81,42 +102,107 @@ Or add to your host's MCP config:
 }
 ```
 
+**Claude Desktop** does **not** expand `${...}` variables — a literal
+`${CLAUDE_PROJECT_DIR}` would fail on every call (Argus names this error when
+it happens). Either omit `ARGUS_DIR` (→ `~/.argus`) or use an absolute path:
+
+```jsonc
+// macOS
+"env": { "ARGUS_DIR": "/Users/you/.argus" }
+// Windows — also note the command form below
+"env": { "ARGUS_DIR": "C:\\Users\\you\\.argus" }
+```
+
+**Windows** hosts often can't launch bare `npx` (it's `npx.cmd`). If the server
+fails to start, use:
+
+```jsonc
+{
+  "command": "cmd",
+  "args": ["/c", "npx", "-y", "argus-decision-mcp"]
+}
+```
+
 > `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.
+> `ARGUS_DIR`, then falls back to `~/.argus`. A per-call `argus_dir` still
+> wins — so Argus works on any host even when env-variable interpolation
+> doesn't.
+
+## Your first receipt (2 minutes)
+
+You never call these tools by name. Once the server is connected, you just
+talk to your AI in plain language and it calls the right tool for you. One
+full loop — from saving a prediction to recording what reality did — looks like
+this:
+
+**1 · Save a prediction** — before you commit to a decision, tell your AI:
+
+> **You:** "I'm shipping the new onboarding flow next week. Save this prediction:
+> signups go up at least 10% by the end of the month."
+
+Argus records your predicate and a check-by date. Nothing is scored — it's a
+prediction against reality, not a grade from the model.
+
+**2 · Update a fact** *(optional, any time before the date)* — if a fact
+your decision leaned on might have moved:
+
+> **You:** "Update the signup number behind my onboarding decision. Has it
+> changed since I saved the prediction?"
+
+Argus compares the new number to the baseline and tells you if it drifted. It
+returns the handle — whether to revisit the decision stays your call.
+
+**3 · Record the result on the check-by date** — when the date arrives:
+
+> **You:** "Record the result of my onboarding prediction. Signups went up 14%."
+
+Argus prints the **Judgment Receipt** at the top of this page — with
+`AI VERDICT … NONE`. You made the call; the record contains what reality did,
+not a model's grade.
+
+That's the whole spine. Everything below is detail on top of these three steps.
+
+## The everyday loop
+
+Argus now exposes six tools named for the job they do. You do not initialize
+it first, choose a ritual, or learn its internal state machine. The first useful
+call creates the local record automatically.
+
+For most decisions the loop is simply:
+
+1. **`argus_capture`** — capture a decision's premises and open questions, in your own words.
+2. **`argus_predict`** — make a falsifiable prediction and the date reality can answer it.
+3. **`argus_check_in`** — see only what needs attention now.
+4. **`argus_resolve`** — record what actually happened, without a score or verdict.
 
-## The loop
+`argus_patterns` reads what is already on record — past decisions and how often
+your predictions held. `argus_settings` handles the few preferences and
+account-sync controls a user may need.
 
 | 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. |
+| `argus_capture` | Captures one decision's premises and open questions in the user's own words, without deciding for you. Its actions add assumptions and open questions, record your answer, update an external fact, change an untested prediction, or close a decision that no longer needs an outcome. |
+| `argus_predict` | Makes a falsifiable prediction (`predicate` + `check_by`) in the user's words. An Argus-drafted line is marked honestly and shown as a one-tap draft to keep, reword, or skip. |
+| `argus_check_in` | Shows only predictions past their check date, external facts due for an update, and open questions due for reconsideration. If nothing needs attention, it stops. |
+| `argus_resolve` | Records what actually happened and issues the Judgment Receipt. Reality supplies the outcome; Argus does not grade it. |
+| `argus_patterns` | Reads active decisions, all records, one Judgment Receipt, one decision's context, or the accumulated frequency of outcomes. Read-only. |
+| `argus_settings` | Reads or updates language, quiet reminders, opt-in premise sync, and explicit account sync. Initialization is automatic. |
 
 ## 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
+once when a prediction was saved 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.
+between saving a prediction and recording its result. Every tool response can
+carry a quiet `due_note`, `argus_check_in` reports due items, and the single
+`argus://attention` resource lets capable hosts auto-inject what needs attention. No
+separate prompt ritual is advertised. 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.
 
@@ -124,12 +210,20 @@ Argus does not pretend liveness.
 
 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).
+receipts render to shareable text. **No telemetry by default.** The only network
+call Argus makes out of the box is the opt-in account sync: if — and only if —
+you set `ARGUS_TOKEN`, a saved prediction or recorded result is POSTed to your own Argus
+account so it can email you at its check-by date. Separately, you can opt in to
+**anonymous** usage telemetry with `ARGUS_TELEMETRY=1` (a random install id +
+which tool ran + version/platform, never your decisions or token; honors
+`DO_NOT_TRACK`) — see SECURITY.md. **Premise data stays on your machine
+by default** — it is not part of the sync payload. There is exactly one switch
+that changes this: `argus_settings` with `action:"update"` and
+`premise_sync:true` (off unless you set it)
+sends a saved decision's *monitored* premises along, so your account's
+autonomous premise-watch can re-check them against reality and email you when
+one materially moves. Unset the token and Argus never touches the network.
+See [SECURITY.md](SECURITY.md).
 
 ## Measured
 

package/SECURITY.md

@@ -2,14 +2,28 @@
 
 ## 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.
+- **All data is local by default.** 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 unless you explicitly set `ARGUS_TOKEN` for account sync (or opt in to
+  anonymous telemetry with `ARGUS_TELEMETRY=1`; see below).
+- **No telemetry by default.** With no `ARGUS_TOKEN` and no `ARGUS_TELEMETRY=1`,
+  the server makes no network calls. Telemetry is strictly **opt-in**: set
+  `ARGUS_TELEMETRY=1` and it sends an anonymous, content-free ping — a random,
+  machine-local install id (`~/.argus/.telemetry-id`, not tied to your account
+  or token, regenerable by deleting the file), which of the built-in tools ran
+  and whether it succeeded, plus the package version, coarse OS platform, and
+  Node major. It **never** sends decision content, titles, predicates, file
+  paths, `argus_dir`, or the account token. `DO_NOT_TRACK=1` disables it even if
+  the flag is set, and the sink stores no `user_id` (nothing to identify).
+  Telemetry rows are **deleted automatically after 90 days** (a daily database
+  job — retention is enforced by the database itself, not by policy prose). The
+  runtime dependency surface is intentionally small and visible in
+  `package.json`: MCP SDK, schema/config helpers, and document parsers.
+  `npm audit --omit=dev` should stay clean before publishing.
+- **Private by default.** On first use Argus adds `sessions/`, `ledger/`,
+  `config.yaml`, and `.bound` to `.argus/.gitignore` so your decisions and
+  local settings are never committed accidentally.
 
 ## Threat model
 

package/dist/a0/account-connect.js

@@ -0,0 +1,180 @@
+import { createServer } from 'node:http';
+import { randomBytes, createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { writeStoredAccountCredential, } from './account-credentials.js';
+const DEFAULT_API_URL = 'https://argus.voyage';
+const CONNECT_TIMEOUT_MS = 5 * 60 * 1000;
+function apiBase(value) {
+    const url = new URL(value.replace(/\/+$/, ''));
+    const local = url.hostname === '127.0.0.1' || url.hostname === 'localhost' || url.hostname === '::1';
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) {
+        throw new Error('ARGUS_API_URL must use HTTPS (HTTP is allowed only for localhost).');
+    }
+    return url.toString().replace(/\/+$/, '');
+}
+function base64url(bytes = 32) {
+    return randomBytes(bytes).toString('base64url');
+}
+function challenge(verifier) {
+    return createHash('sha256').update(verifier).digest('base64url');
+}
+async function defaultOpenExternal(url) {
+    const command = process.platform === 'win32' ? 'explorer.exe' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+    try {
+        const child = spawn(command, [url], { detached: true, stdio: 'ignore', windowsHide: true });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function listen(server) {
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => resolve(server.address().port));
+    });
+}
+function close(server) {
+    return new Promise((resolve) => server.close(() => resolve()));
+}
+function waitForCode(server, expectedState) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error('Account connection timed out.')), CONNECT_TIMEOUT_MS);
+        server.on('request', (request, response) => {
+            const url = new URL(request.url || '/', 'http://127.0.0.1');
+            if (url.pathname !== '/callback') {
+                response.writeHead(404).end('Not found');
+                return;
+            }
+            const code = url.searchParams.get('code');
+            const state = url.searchParams.get('state');
+            if (!code || state !== expectedState) {
+                response.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' }).end('Invalid or expired Argus connection.');
+                return;
+            }
+            clearTimeout(timeout);
+            response.writeHead(200, {
+                'content-type': 'text/html; charset=utf-8',
+                'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'",
+                'cache-control': 'no-store',
+            }).end('<!doctype html><meta charset="utf-8"><title>Argus connected</title><style>body{font:16px system-ui;max-width:38rem;margin:15vh auto;padding:2rem;color:#202020}h1{font-size:1.4rem}</style><h1>Argus account connected</h1><p>You can close this window and return to your terminal.</p>');
+            resolve(code);
+        });
+    });
+}
+async function requestJson(fetchImpl, url, body) {
+    const response = await fetchImpl(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    let json = {};
+    try {
+        json = await response.json();
+    }
+    catch { /* surfaced as protocol failure below */ }
+    return { response, json };
+}
+function tokenFrom(json) {
+    if (typeof json.access_token !== 'string' || !json.access_token.startsWith('argus_pat_'))
+        throw new Error('The account returned an invalid credential.');
+    if (json.token_type !== 'Bearer' || typeof json.scope !== 'string' || typeof json.expires_at !== 'string')
+        throw new Error('The account returned an incomplete credential.');
+    return json;
+}
+function persist(token, base, credentialFile) {
+    const stored = {
+        version: 1,
+        access_token: token.access_token,
+        token_type: 'Bearer',
+        scope: token.scope,
+        expires_at: token.expires_at,
+        api_url: base,
+        connected_at: new Date().toISOString(),
+    };
+    writeStoredAccountCredential(stored, credentialFile);
+    return stored;
+}
+async function connectWithBrowser(options, base) {
+    const verifier = base64url(48);
+    const state = base64url(24);
+    const server = createServer();
+    const port = await listen(server);
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const codePromise = waitForCode(server, state);
+    const authorize = new URL(`${base}/en/auth/callback/mcp-connect`);
+    authorize.searchParams.set('response_type', 'code');
+    authorize.searchParams.set('redirect_uri', redirectUri);
+    authorize.searchParams.set('state', state);
+    authorize.searchParams.set('code_challenge', challenge(verifier));
+    authorize.searchParams.set('code_challenge_method', 'S256');
+    authorize.searchParams.set('client_name', options.clientName || 'Argus MCP');
+    options.writeLine('Opening Argus in your browser to approve this device…');
+    const opened = await options.openExternal(authorize.toString());
+    if (!opened)
+        options.writeLine(`Open this URL in a browser:\n${authorize.toString()}`);
+    try {
+        const code = await codePromise;
+        const { response, json } = await requestJson(options.fetchImpl, `${base}/api/mcp/oauth/token`, {
+            grant_type: 'authorization_code',
+            code,
+            code_verifier: verifier,
+            redirect_uri: redirectUri,
+        });
+        if (!response.ok)
+            throw new Error(`Account token exchange failed (${String(json.error || response.status)}).`);
+        return persist(tokenFrom(json), base, options.credentialFile);
+    }
+    finally {
+        await close(server);
+    }
+}
+async function connectWithDeviceCode(options, base) {
+    const { response, json } = await requestJson(options.fetchImpl, `${base}/api/mcp/oauth/device`, { client_name: options.clientName || 'Argus MCP' });
+    if (!response.ok)
+        throw new Error(`Could not start device authorization (${String(json.error || response.status)}).`);
+    if (typeof json.device_code !== 'string' || typeof json.user_code !== 'string' || typeof json.verification_uri !== 'string') {
+        throw new Error('The account returned an invalid device authorization.');
+    }
+    let interval = typeof json.interval === 'number' ? Math.max(1, json.interval) : 5;
+    const expiresIn = typeof json.expires_in === 'number' ? json.expires_in : 600;
+    const deadline = Date.now() + expiresIn * 1000;
+    options.writeLine(`Open ${String(json.verification_uri)} and enter code: ${json.user_code}`);
+    while (Date.now() < deadline) {
+        await options.sleep(interval * 1000);
+        const poll = await requestJson(options.fetchImpl, `${base}/api/mcp/oauth/token`, {
+            grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+            device_code: json.device_code,
+        });
+        if (poll.response.ok)
+            return persist(tokenFrom(poll.json), base, options.credentialFile);
+        if (poll.json.error === 'authorization_pending')
+            continue;
+        if (poll.json.error === 'slow_down') {
+            interval += 5;
+            continue;
+        }
+        if (poll.json.error === 'access_denied')
+            throw new Error('Account connection was denied.');
+        if (poll.json.error === 'expired_token')
+            break;
+        throw new Error(`Device authorization failed (${String(poll.json.error || poll.response.status)}).`);
+    }
+    throw new Error('Device authorization expired. Start the connection again.');
+}
+export async function connectAccount(options = {}) {
+    const base = apiBase(options.apiUrl || process.env.ARGUS_API_URL || DEFAULT_API_URL);
+    const shared = {
+        ...options,
+        fetchImpl: options.fetchImpl || fetch,
+        openExternal: options.openExternal || defaultOpenExternal,
+        writeLine: options.writeLine || ((line) => process.stdout.write(`${line}\n`)),
+        sleep: options.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    };
+    const credential = options.headless
+        ? await connectWithDeviceCode(shared, base)
+        : await connectWithBrowser(shared, base);
+    shared.writeLine(`Connected. Credential stored locally; expires ${credential.expires_at.slice(0, 10)}.`);
+    return credential;
+}

package/dist/a0/account-credentials.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+function defaultCredentialPath() {
+    const explicit = process.env.ARGUS_ACCOUNT_FILE?.trim();
+    if (explicit)
+        return path.resolve(explicit);
+    const argusDir = process.env.ARGUS_DIR?.trim();
+    if (argusDir)
+        return path.join(path.resolve(argusDir), 'account-credentials.json');
+    if (process.platform === 'win32') {
+        const root = process.env.LOCALAPPDATA?.trim() || path.join(os.homedir(), 'AppData', 'Local');
+        return path.join(root, 'Argus', 'account-credentials.json');
+    }
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'Argus', 'account-credentials.json');
+    }
+    const root = process.env.XDG_CONFIG_HOME?.trim() || path.join(os.homedir(), '.config');
+    return path.join(root, 'argus', 'account-credentials.json');
+}
+export function accountCredentialPath() {
+    return defaultCredentialPath();
+}
+export function readStoredAccountCredential(file = defaultCredentialPath()) {
+    // Unit tests must opt into an isolated temp location. Never probe a
+    // developer's actual config directory merely because a sync helper ran.
+    if (process.env.NODE_ENV === 'test' && !process.env.ARGUS_ACCOUNT_FILE && !process.env.ARGUS_DIR && file === defaultCredentialPath()) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (parsed.version !== 1 || parsed.token_type !== 'Bearer')
+            return null;
+        if (typeof parsed.access_token !== 'string' || !parsed.access_token.startsWith('argus_pat_'))
+            return null;
+        if (typeof parsed.expires_at !== 'string' || Date.parse(parsed.expires_at) <= Date.now())
+            return null;
+        if (typeof parsed.api_url !== 'string' || typeof parsed.scope !== 'string' || typeof parsed.connected_at !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeStoredAccountCredential(credential, file = defaultCredentialPath()) {
+    const dir = path.dirname(file);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const temp = path.join(dir, `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        fs.writeFileSync(temp, `${JSON.stringify(credential, null, 2)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        fs.renameSync(temp, file);
+        try {
+            fs.chmodSync(file, 0o600);
+        }
+        catch { /* Windows ACLs do not use POSIX modes. */ }
+    }
+    finally {
+        try {
+            fs.unlinkSync(temp);
+        }
+        catch { /* rename already removed it */ }
+    }
+}
+/** Manual ARGUS_TOKEN remains the advanced/CI override. */
+export function resolveAccountToken() {
+    const manual = process.env.ARGUS_TOKEN?.trim();
+    if (manual)
+        return manual;
+    return readStoredAccountCredential()?.access_token ?? '';
+}
+export function resolveAccountApiUrl() {
+    const manual = process.env.ARGUS_API_URL?.trim();
+    if (manual)
+        return manual;
+    return readStoredAccountCredential()?.api_url ?? 'https://argus.voyage';
+}
+export function disconnectStoredAccount(file = defaultCredentialPath()) {
+    try {
+        fs.unlinkSync(file);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'ENOENT';
+    }
+}

package/dist/index.js

@@ -2,6 +2,37 @@
 import { createServer } from './server.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 async function main() {
+    if (process.argv[2] === 'connect') {
+        const { connectAccount } = await import('./a0/account-connect.js');
+        await connectAccount({ headless: process.argv.includes('--headless') });
+        return;
+    }
+    if (process.argv[2] === 'disconnect') {
+        const { disconnectStoredAccount } = await import('./a0/account-credentials.js');
+        disconnectStoredAccount();
+        process.stdout.write('Local Argus account credential removed. Revoke the device in Settings to invalidate its server token.\n');
+        return;
+    }
+    if (process.argv[2] === 'capture-scan') {
+        const { runCaptureCli } = await import('./v2/capture-cli.js');
+        await runCaptureCli(process.argv.slice(3));
+        return;
+    }
+    if (process.argv[2] === 'capture-status') {
+        const { runCaptureStatusCli } = await import('./v2/capture-cli.js');
+        runCaptureStatusCli(process.argv.slice(3));
+        return;
+    }
+    if (process.argv[2] === 'capture-purge') {
+        const { runCapturePurgeCli } = await import('./v2/capture-cli.js');
+        runCapturePurgeCli(process.argv.slice(3));
+        return;
+    }
+    if (['archive-export', 'archive-restore', 'local-purge'].includes(process.argv[2] ?? '')) {
+        const { runLifecycleCli } = await import('./v2/lifecycle-cli.js');
+        runLifecycleCli(process.argv[2], process.argv.slice(3));
+        return;
+    }
     const server = await createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
@@ -10,4 +41,7 @@ async function main() {
         process.exit(0);
     });
 }
-main().catch(console.error);
+main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});