strata-agent-memory 0.2.0__py3-none-any.whl

agent_memory/cli.py

@@ -0,0 +1,1405 @@
+"""Command-line interface. Every operation available to the MCP server is also here,
+so a human, a shell script, a CI job, or a local model with tool-calling can use it.
+
+With ``--remote URL`` the commands a replica can answer go over HTTP to an
+`agent-memory serve` instead of to a ledger under this directory, so a second machine
+needs a token rather than a clone (docs/BETA-SPEC.md section 4.4).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections import Counter
+from pathlib import Path
+from typing import List, Optional
+
+from . import __version__
+from . import audit as audit_mod
+from . import compact as compact_mod
+from . import contracts
+from . import evidence as ev
+from . import export as export_mod
+from . import memorizer
+from . import pathmap
+from . import recheck as recheck_mod
+from . import reliability as rel_mod
+from . import remote as remote_mod
+from . import signing
+from .compiler import MODES, ROLES, compile_context, record_compilation
+from .identity import detect_author, detect_session
+from .ledger import (
+    DIR_NAME, TRUSTED_ORG_PATHS_NAME, TRUSTED_REPOS_NAME, UNTRUSTED_POLICY, ConfigError, Ledger,
+    find_root, trust_org_path, trust_repo, write_starter_config,
+)
+from .records import CLAIM_TYPES, ValidationError, make_scope, new_record
+from .render import RENDERERS, render
+from .trust import TIERS, assess
+
+
+def _author(args, ledger: Ledger) -> dict:
+    return detect_author(
+        ledger.config, cwd=str(ledger.root),
+        kind="human" if getattr(args, "as_human", False) else None,
+        harness=getattr(args, "harness", None), model=getattr(args, "model", None),
+        session=getattr(args, "session", None), user=getattr(args, "user", None),
+    )
+
+
+def _scope(args, ledger: Ledger, author: dict) -> dict:
+    level = getattr(args, "scope", None) or "project"
+    return make_scope(level=level, project=ledger.config.get("project", "default"), user=author["user"] if level == "user" else None)
+
+
+def _print(obj) -> None:
+    if isinstance(obj, str):
+        sys.stdout.write(obj if obj.endswith("\n") else obj + "\n")
+    else:
+        print(json.dumps(obj, indent=2, ensure_ascii=False))
+
+
+def _path_map(args, ledger: Ledger):
+    """config.path_map, then AGENT_MEMORY_PATH_MAP, then --map: the last wins (§2)."""
+    return pathmap.load(ledger.config, flags=getattr(args, "map", None))
+
+
+def _sign_after(args, ledger: Ledger, author: dict, scope: dict, rec: dict, out: dict) -> bool:
+    """File an attestation over ``rec`` when --sign was given; False when it did not.
+
+    The record itself is already in the ledger and cannot be unfiled, so a failed
+    signature is reported on stderr and in the exit code rather than pretended away.
+    """
+    if not getattr(args, "sign", False):
+        return True
+    try:
+        att = signing.sign_record(ledger, author, scope, rec["id"], key_id=getattr(args, "key", None))
+    except (ValidationError, signing.SigningUnavailable) as exc:
+        out["attestation"] = None
+        print(f"filed {rec['id']} but did not sign it: {exc}", file=sys.stderr)
+        return False
+    out["attestation"] = att["id"]
+    return True
+
+
+# --------------------------------------------------------------------------- commands
+
+def cmd_init(args) -> int:
+    root = Path(args.path or ".")
+    if args.org:
+        # checked before anything is written: a path that does not exist is a typo, and
+        # writing it to a file outside the project and exiting 0 is not an answer (F-11)
+        org = Path(args.org).expanduser()
+        if not org.is_dir():
+            print(f"no such directory: {org}; --org takes an existing shared org-ledger "
+                  f"directory. Nothing was written.", file=sys.stderr)
+            return 2
+    fresh = not (root / DIR_NAME / "config.json").exists()
+    ledger = Ledger.init(root, project=args.project, org_path=args.org, user=args.user)
+    # every run, not just the first: a ledger written before the allowlist existed is
+    # exactly the one that needs it, and `init` is what three documents tell you to run (F-4)
+    added = write_starter_config(ledger)
+    out = {"root": str(ledger.root), "config": ledger.config, "added_keys": added}
+    if fresh:
+        # a ledger this command just created is one nobody else wrote
+        out["trusted_repos"] = str(trust_repo(ledger.root))
+    if args.org:
+        # the repository may name an org path; only this machine may accept one (S7)
+        out["trusted_org_paths"] = str(trust_org_path(args.org))
+    _print(out)
+    print(f"project name: {ledger.config.get('project')}"
+          + ("" if args.project else " (the directory name)")
+          + f"; every record filed here is bound to it. Change it with "
+            f"`agent-memory init {args.path or '.'} --project NAME`.", file=sys.stderr)
+    if added:
+        print(f"wrote {', '.join(added)} to {ledger.dir / 'config.json'}"
+              + (" (this ledger had none)" if not fresh else ""), file=sys.stderr)
+    if "recheck_allow" in added:
+        allow = ledger.config.get("recheck_allow") or []
+        print(f"re-check allowlist: {len(allow)} entries in "
+              f"{ledger.dir / 'config.json'} (\"recheck_allow\"). An entry is an argv prefix, "
+              "so add e.g. \"npm run lint\" to widen it by one command. A bare `python` or "
+              "`sh` entry admits arbitrary code: a receipt is a command every machine that "
+              "re-checks it runs unattended.", file=sys.stderr)
+    if fresh:
+        print(f"trusted this repository ({out['trusted_repos']}), so its config.json decides "
+              f"policy on this machine.", file=sys.stderr)
+    elif not ledger.trusted:
+        print(f"this ledger already existed, so it was not trusted: a config.json a clone "
+              f"brings with it only proposes policy (allowlist, redaction, path map, signers, "
+              f"org path, cross-vendor rule). Run `agent-memory trust {args.path or '.'}` if "
+              f"this checkout is yours.", file=sys.stderr)
+    return 0
+
+
+def cmd_trust(args) -> int:
+    root = find_root(Path(args.path or "."))
+    if root is None:
+        print(f"no {DIR_NAME} directory found above {args.path or Path.cwd()}; run "
+              f"`agent-memory init`", file=sys.stderr)
+        return 2
+    path = trust_repo(root)
+    cfg_path = root / DIR_NAME / "config.json"
+    try:
+        config = json.loads(cfg_path.read_text()) if cfg_path.exists() else {}
+    except json.JSONDecodeError as exc:
+        print(f"config.json is not valid JSON (a merge conflict?): {exc} ({cfg_path})", file=sys.stderr)
+        return 2
+    honoured = sorted(k for k in UNTRUSTED_POLICY if k in config)
+    _print({"root": str(root), "trusted_repos": str(path), "now_honoured": honoured})
+    print(f"trusted {root}: its config.json now decides policy on this machine"
+          + (f" ({', '.join(honoured)})" if honoured else "")
+          + f". Remove the line from {path} to undo.", file=sys.stderr)
+    return 0
+
+
+def cmd_whoami(args) -> int:
+    ledger = Ledger.open()
+    _print(_author(args, ledger))
+    return 0
+
+
+def cmd_run(args) -> int:
+    ledger = Ledger.open()
+    author = _author(args, ledger)
+    cmd = list(args.cmd or [])
+    if cmd and cmd[0] == "--":
+        cmd = cmd[1:]
+    if not cmd:
+        print("usage: agent-memory run [--cwd DIR] -- <command...>", file=sys.stderr)
+        return 2
+    if cmd[0].startswith("-"):
+        # an option that landed in the command means the caller mis-typed; never receipt it
+        print(f"usage: agent-memory run [--cwd DIR] -- <command...>; {cmd[0]!r} looks like an option, "
+              "put agent-memory's own options before the --", file=sys.stderr)
+        return 2
+    body = ev.run_and_capture(cmd if len(cmd) > 1 or not args.shell else cmd[0], cwd=args.cwd or str(ledger.root),
+                              shell=args.shell, timeout=args.timeout, policy=ledger.config)
+    if args.assurance:  # otherwise the ledger stamps the default on append
+        body["assurance"] = args.assurance
+    if args.no_rerun:  # a deploy, a migration: nothing in the fleet may run this again
+        body["rerun"] = False
+    rec = ledger.append(new_record("evidence", author, _scope(args, ledger, author), body))
+    body = rec["body"]
+    out = {"id": rec["id"], "kind": body["kind"], "assurance": body.get("assurance"),
+           "exit": body["exit"], "duration_ms": body["duration_ms"]}
+    if body.get("redacted"):  # say that something was scrubbed, never what it was
+        out["redacted"] = body["redacted"]
+    if body.get("start_error"):  # the process never started; say so instead of a traceback
+        out["start_error"] = body["start_error"]
+    if body.get("rerun") is False:
+        out["rerun"] = False
+    if body["kind"] == "test":
+        out.update({"passed": body["passed"], "failed": body["failed"], "summary": body.get("summary")})
+    if not args.quiet:
+        sys.stderr.write(body["stdout_tail"][-1500:])
+        sys.stderr.write(body["stderr_tail"][-800:])
+        if body["stdout_tail"] or body["stderr_tail"]:
+            sys.stderr.write("\n")
+    signed = _sign_after(args, ledger, author, _scope(args, ledger, author), rec, out)
+    _print(out)
+    if not signed:
+        return 3
+    return 0 if body["exit"] == 0 else 1
+
+
+def cmd_claim(args) -> int:
+    ledger = Ledger.open()
+    author = _author(args, ledger)
+    body = {"type": args.type, "statement": args.statement}
+    evidence: List = list(args.evidence or [])
+    try:
+        if args.commit is not None:
+            evidence.append(ev.commit_binding(str(ledger.root), args.commit or None, branch=args.branch))
+        for f in args.file or []:
+            evidence.append(ev.file_binding(f))
+        for f in args.env or []:
+            # what the claim is true *under*: a change here makes it stale, not wrong
+            evidence.append(ev.file_binding(f, role="environment"))
+        if args.diff:
+            base, _, head = args.diff.partition("..")
+            evidence.append(ev.diff_binding(str(ledger.root), base, head or "HEAD"))
+    except ValueError as exc:  # a binding that does not resolve is a rejection, not a crash
+        print(f"rejected: {exc}", file=sys.stderr)
+        return 3
+    if args.attest:
+        evidence.append({"kind": "human", "who": author["user"], "statement": args.attest})
+    if evidence:
+        body["evidence"] = evidence
+    for key in ("rationale", "example", "outcome", "source", "contract"):
+        val = getattr(args, key, None)
+        if val is not None:
+            body[key] = val
+    if args.expect_exit is not None or args.expect_failed is not None:
+        # the claim is about a deliberate failure state, so say which one it expects
+        body["expect"] = {}
+        if args.expect_exit is not None:
+            body["expect"]["exit"] = args.expect_exit
+        if args.expect_failed is not None:
+            body["expect"]["failed"] = args.expect_failed
+    if args.confidence is not None:
+        body["confidence"] = args.confidence
+    if args.ttl_days is not None:
+        body["ttl_days"] = args.ttl_days
+    rec = new_record("claim", author, _scope(args, ledger, author), body, derived_from=args.derived_from or (), tags=args.tag or ())
+    try:
+        rec = ledger.append(rec)
+    except ValidationError as exc:
+        print(f"rejected: {exc}", file=sys.stderr)
+        return 3
+    tier = assess(ledger).get(rec["id"], {}).get("tier")
+    out = {"id": rec["id"], "type": rec["body"]["type"], "tier": tier}
+    signed = _sign_after(args, ledger, author, _scope(args, ledger, author), rec, out)
+    _print(out)
+    return 0 if signed else 3
+
+
+def cmd_verify(args) -> int:
+    ledger = Ledger.open()
+    author = _author(args, ledger)
+    claim = ledger.get(args.claim)
+    if claim is None or claim["kind"] != "claim":
+        print(f"no claim {args.claim}", file=sys.stderr)
+        return 2
+    results = ev.recheck_claim(ledger, claim, cwd=str(ledger.root), strict=args.strict, timeout=args.timeout,
+                               path_map=_path_map(args, ledger))
+    verdict = args.verdict
+    method = "human" if author["kind"] == "human" and verdict else ("independent" if verdict else "rerun")
+    env_changed: list = []
+    auto_note = None
+    if not verdict:
+        verdict, env_changed, auto_note = ev.verdict_from_results(results, ledger, claim)
+    vbody = {"claim": claim["id"], "verdict": verdict, "method": method, "results": results}
+    note = args.note
+    if auto_note:  # e.g. every binding matched, but the receipt it matched had failed
+        note = f"{note}; {auto_note}" if note else auto_note
+    if env_changed:  # the proof still holds; the world it held in does not
+        vbody["environment_changed"] = True
+        changed = "environment changed: " + ", ".join(env_changed)
+        note = f"{note}; {changed}" if note else changed
+    if note:
+        vbody["note"] = note
+    tags = [f"lens:{args.lens}"] if args.lens else []
+    try:
+        rec = ledger.append(new_record("verification", author, _scope(args, ledger, author), vbody,
+                                       derived_from=[claim["id"]], tags=tags))
+    except ValidationError as exc:
+        print(f"rejected: {exc}", file=sys.stderr)
+        return 3
+    out = {"id": rec["id"], "verdict": verdict, "method": method, "environment_changed": bool(env_changed),
+           "claim_tier_now": assess(ledger)[claim["id"]]["tier"], "results": results}
+    signed = _sign_after(args, ledger, author, _scope(args, ledger, author), rec, out)
+    _print(out)
+    if not signed:
+        return 3
+    return 0 if verdict != "refuted" else 1
+
+
+def cmd_retract(args) -> int:
+    ledger = Ledger.open()
+    author = _author(args, ledger)
+    rec = ledger.append(new_record("retraction", author, _scope(args, ledger, author), {"claim": args.claim, "reason": args.reason},
+                                   derived_from=[args.claim]))
+    tainted = sorted(ledger.dependents_of(args.claim, through_kinds=("claim",)))
+    out = {"id": rec["id"], "tainted_dependents": tainted}
+    signed = _sign_after(args, ledger, author, _scope(args, ledger, author), rec, out)
+    _print(out)
+    return 0 if signed else 3
+
+
+def cmd_compile(args) -> int:
+    ledger = Ledger.open()
+    author = _author(args, ledger)
+    compiled = compile_context(ledger, role=args.role, mode=args.mode, task=args.task, contract_id=args.contract,
+                               tags=args.tag or (), budget_tokens=args.budget, reader=author,
+                               include_tainted=args.include_tainted, round_no=args.round, lens=args.lens,
+                               reliability=not args.no_reliability)
+    text = render(compiled, args.render)
+    if not args.no_receipt:
+        rec = record_compilation(ledger, compiled, text, args.render, author, _scope(args, ledger, author),
+                                 save_dir=ledger.dir / "compiled")
+        if args.render != "json":
+            text += f"\n<!-- compilation receipt {rec['id']} -->\n"
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8")
+        print(f"wrote {args.output}", file=sys.stderr)
+    else:
+        _print(text)
+    return 0
+
+
+def cmd_search(args) -> int:
+    ledger = Ledger.open()
+    assessment = assess(ledger)
+    for rec in ledger.search(" ".join(args.query), kinds=args.kind or ("claim",), limit=args.limit):
+        tier = assessment.get(rec["id"], {}).get("tier", "-")
+        body = rec["body"]
+        text = body.get("statement") or body.get("title") or body.get("state") or json.dumps(body)[:160]
+        print(f"{rec['id']}  {rec['ts'][:10]}  [{tier}] {rec['author'].get('harness')}: {text[:160]}")
+    return 0
+
+
+def cmd_show(args) -> int:
+    ledger = Ledger.open()
+    rec = ledger.get(args.id)
+    if rec is None:
+        print(f"no record {args.id}", file=sys.stderr)
+        return 2
+    out = dict(rec)
+    if rec["kind"] == "claim":
+        assessment = assess(ledger)
+        out["trust"] = assessment.get(rec["id"])
+        out["verifications"] = [v["id"] for v in ledger.verifications_for(rec["id"])]
+        out["retractions"] = [r["id"] for r in ledger.retractions_for(rec["id"])]
+        out["dependents"] = sorted(ledger.dependents_of(rec["id"]))
+        # what history says about claims like this one, or nothing when there is too little
+        table = rel_mod.cell_table(ledger, assessment, config=ledger.config)
+        rows = rel_mod.judgment_calibration(ledger, assessment, config=ledger.config)
+        annotated = rel_mod.annotate(rec, assessment, table, rows, config=ledger.config)
+        out["reliability"] = None if annotated is None else dict(annotated[1], line=annotated[0])
+    _print(out)
+    return 0
+
+
+def cmd_list(args) -> int:
+    ledger = Ledger.open()
+    assessment = assess(ledger)
+    rows = ledger.all() if args.kind == "all" else ledger.by_kind(args.kind)
+    for rec in rows[-args.limit:]:
+        body = rec["body"]
+        tier = assessment.get(rec["id"], {}).get("tier", "")
+        text = body.get("statement") or body.get("title") or body.get("state") or body.get("cmd") or body.get("claim") or ""
+        print(f"{rec['id']}  {rec['ts'][:16]}  {rec['kind']:<15} {('[' + tier + ']') if tier else '':<15} {rec['author'].get('harness')}: {str(text)[:120]}")
+    return 0
+
+
+def cmd_contract(args) -> int:
+    ledger = Ledger.open()
+    author = _author(args, ledger)
+    scope = _scope(args, ledger, author)
+    if args.action == "create":
+        acceptance = []
+        for c in args.check or []:
+            acceptance.append({"kind": "command", "cmd": c, "expect_exit": 0})
+        for s in args.human_check or []:
+            acceptance.append({"kind": "human", "statement": s})
+        for f in args.file_check or []:
+            acceptance.append({"kind": "file", "path": f})
+        if args.acceptance_json:
+            acceptance += json.loads(Path(args.acceptance_json).read_text())
+        try:
+            rec = contracts.create(ledger, author, scope, args.title, args.task, acceptance, assigned_to=args.assign,
+                                   tags=args.tag or (), issue=args.issue)
+        except ValidationError as exc:
+            print(f"rejected: {exc}", file=sys.stderr)
+            return 3
+        out = {"id": rec["id"], "status": "proposed"}
+        signed = _sign_after(args, ledger, author, scope, rec, out)
+        _print(out)
+        return 0 if signed else 3
+    if args.action == "update":
+        rec = contracts.update(ledger, author, scope, args.id, args.status, note=args.note, claims=args.claims or ())
+        out = {"id": rec["id"], "status": args.status}
+        signed = _sign_after(args, ledger, author, scope, rec, out)
+        _print(out)
+        return 0 if signed else 3
+    if args.action == "from-issue":
+        try:
+            rec = contracts.from_issue(ledger, author, scope, args.ref, checks=args.check or (),
+                                       human_checks=args.human_check or (), file_checks=args.file_check or (),
+                                       assign=args.assign, tags=args.tag or ())
+        except ValidationError as exc:  # gh missing/unauthenticated, or a contract with no check
+            print(f"rejected: {exc}", file=sys.stderr)
+            return 3
+        _print({"id": rec["id"], "status": "proposed", "issue": rec["body"].get("issue"),
+                "title": rec["body"]["title"]})
+        return 0
+    if args.action == "sync":
+        try:
+            out = contracts.sync(ledger, args.id, close=args.close)
+        except ValidationError as exc:
+            print(f"rejected: {exc}", file=sys.stderr)
+            return 3
+        _print(out)
+        if out.get("refused"):  # the issue tracker does not get to say done before the ledger does
+            print(f"refused: {out['refused']}", file=sys.stderr)
+            return 1
+        return 0
+    if args.action == "status":
+        st = contracts.status_of(ledger, args.id, assess(ledger))
+        _print(st)
+        return 0
+    if args.action == "accept":
+        results = contracts.run_acceptance(ledger, args.id, cwd=str(ledger.root), author=author, scope=scope)
+        filed = [r["receipt"] for r in results if r.get("receipt")]
+        ok = all(r["outcome"] in ("match", "skipped") for r in results)
+        _print({"contract": args.id, "all_pass": ok, "receipts": filed,
+                "results": [{"check": r["check"], "outcome": r["outcome"], "detail": r["detail"]} for r in results]})
+        return 0 if ok else 1
+    if args.action == "list":
+        for st in contracts.open_contracts(ledger):
+            print(f"{st['id']}  {st['status']:<12} {st['title']}  ({len(st['claims'])} claims)")
+        return 0
+    return 2
+
+
+def cmd_recheck(args) -> int:
+    ledger = Ledger.open()
+    author = _author(args, ledger)
+    scope = _scope(args, ledger, author)
+    types = [t for group in (args.type or []) for t in str(group).split(",") if t.strip()]
+    try:
+        rows = recheck_mod.run(ledger, author, scope, only=args.only, types=types, older_than=args.older_than,
+                               max=args.max, cwd=str(ledger.root), timeout=args.timeout,
+                               path_map=_path_map(args, ledger), dry_run=args.dry_run,
+                               min_age_days=args.min_age_days, force=args.force)
+    except ValueError as exc:  # a malformed --map or --only is a usage error, not a crash
+        print(f"recheck: {exc}", file=sys.stderr)
+        return 2
+    if args.json:
+        _print(rows)
+    else:
+        for row in rows:
+            if row.get("error"):
+                print(f"{row['id']}  error: {row['error']}")
+            elif row.get("skipped") == recheck_mod.OWN_CLAIM:
+                print(f"{row['id']}  skipped: {row['skipped']} (a self-report is not a verification)")
+            elif row.get("plan") is not None:  # --dry-run: what would run, not what it did
+                print(f"{row['id']}  dry run  {row['statement'][:80]}")
+                for b in row["plan"]:
+                    what = f"  {b['cmd']}" if b.get("cmd") else ""
+                    where = f"  (in {b['cwd']})" if b.get("cwd") else ""
+                    print(f"    {b['decision']:<16} {b['evidence']} [{b['kind']}]{what}{where}")
+            elif row.get("skipped"):
+                print(f"{row['id']}  skipped: {row['skipped']} (--force re-checks it anyway)")
+            else:
+                print(f"{row['id']}  {row['verdict']}  {row['filed'] or '-'}  {row['statement'][:80]}")
+        summary = recheck_mod.summarize(rows)
+        print("recheck: " + ", ".join(f"{k}={v}" for k, v in summary.items()), file=sys.stderr)
+    return recheck_mod.exit_code(rows)
+
+
+def cmd_keygen(args) -> int:
+    ledger = Ledger.open()
+    author = _author(args, ledger)
+    try:
+        key = signing.keygen(user=author["user"], out_dir=args.out)
+    except signing.SigningUnavailable as exc:
+        # 3, like `sign`: the command was well formed and this machine cannot do it (F-11)
+        print(str(exc), file=sys.stderr)
+        return 3
+    signing.register(ledger, key)
+    # the private half is named, never printed: the public half is what others need
+    _print({"key_id": key["key_id"], "alg": key["alg"], "public": key["public"], "user": key["user"],
+            "private_key": key["path"], "registered_in": str(ledger.dir / "config.json")})
+    return 0
+
+
+def cmd_sign(args) -> int:
+    ledger = Ledger.open()
+    author = _author(args, ledger)
+    scope = _scope(args, ledger, author)
+    out = []
+    for rid in args.ids:
+        try:
+            att = signing.sign_record(ledger, author, scope, rid, key_id=args.key)
+        except signing.SigningUnavailable as exc:
+            # the same condition keygen answers for, and the same answer: a missing optional
+            # dependency is not a usage error (F-11)
+            print(str(exc), file=sys.stderr)
+            return 3
+        except ValidationError as exc:
+            print(f"rejected: {exc}", file=sys.stderr)
+            return 3
+        out.append({"id": att["id"], "record": rid, "key_id": att["body"]["key_id"]})
+    _print(out)
+    return 0
+
+
+def cmd_verify_signatures(args) -> int:
+    ledger = Ledger.open()
+    rep = signing.report(ledger)
+    if args.json:
+        _print(rep)
+    else:
+        print(f"attestations: {rep['attested']}  valid={rep['valid']} invalid={rep['invalid']} "
+              f"unknown_key={rep['unknown']} unverifiable={rep['unavailable']}")
+        for item in rep["items"]:
+            print(f"{item['id']}  {item['status']:<12} {item['record']}  [{item['key_id']}] {item['detail']}")
+        if rep["unavailable"]:
+            print(signing.NO_CRYPTO + f"; {signing.INSTALL_HINT}", file=sys.stderr)
+    return 3 if rep["invalid"] else 0
+
+
+def cmd_audit(args) -> int:
+    ledger = Ledger.open()
+    rep = audit_mod.report(ledger, recheck=args.recheck, cwd=str(ledger.root),
+                           path_map=_path_map(args, ledger))
+    if args.json:
+        _print({k: (dict(v) if hasattr(v, "most_common") else v) for k, v in rep.items()})
+    else:
+        _print(audit_mod.format_report(rep))
+    return 0
+
+
+def cmd_reliability(args) -> int:
+    ledger = Ledger.open()
+    config = dict(ledger.config)
+    if args.n_min is not None:
+        config["reliability"] = dict(rel_mod.settings(ledger.config), n_min=args.n_min)
+    try:
+        rep = rel_mod.report(ledger, assess(ledger, config=config), config=config, since=args.since)
+    except ValueError as exc:  # an unparseable --since or an invalid --n-min is a usage error, not a crash
+        print(f"reliability: {exc}", file=sys.stderr)
+        return 2
+    rep = rel_mod.view(rep, args.by)
+    _print(rep if args.json else rel_mod.format_report(rep))
+    return 0
+
+
+def cmd_compact(args) -> int:
+    ledger = Ledger.open()
+    author = _author(args, ledger)
+    scope = _scope(args, ledger, author)
+    claims = compact_mod.select_candidates(ledger, older_than_days=args.older_than, contract_id=args.contract, tags=args.tag or ())
+    if args.ids:
+        wanted = set(args.ids)
+        claims = [c for c in ledger.claims() if c["id"] in wanted]
+    if not claims:
+        print("nothing to compact", file=sys.stderr)
+        return 1
+    summarizer = None
+    if args.llm_endpoint:
+        try:
+            summarizer = memorizer.summarize_state(args.llm_endpoint, args.llm_model or "qwen2.5:14b",
+                                                   api_key=args.llm_api_key, insecure=args.llm_insecure)
+        except ValueError as exc:  # a key bound for a plaintext endpoint
+            print(f"refused: {exc}", file=sys.stderr)
+            return 2
+    rec = compact_mod.build_compaction(ledger, claims, author, scope, tags=args.tag or (), summarizer=summarizer)
+    if args.dry_run:
+        _print(rec)
+        return 0
+    rec = ledger.append(rec)
+    _print({"id": rec["id"], "replaces": len(rec["body"]["replaces"]), "counts": rec["body"]["counts"]})
+    return 0
+
+
+def cmd_memorize(args) -> int:
+    ledger = Ledger.open()
+    author = _author(args, ledger)
+    scope = _scope(args, ledger, author)
+    transcript = Path(args.transcript).read_text(encoding="utf-8") if args.transcript != "-" else sys.stdin.read()
+    try:  # checked before the transcript goes anywhere, not while it is in flight
+        memorizer.check_endpoint(args.llm_endpoint, memorizer.resolve_api_key(args.llm_api_key),
+                                 args.llm_insecure)
+    except ValueError as exc:
+        print(f"refused: {exc}", file=sys.stderr)
+        return 2
+    proposals = memorizer.extract_claims(transcript, args.llm_endpoint, args.llm_model, max_claims=args.max,
+                                         api_key=args.llm_api_key, insecure=args.llm_insecure)
+    if args.dry_run:
+        _print(proposals)
+        return 0
+    filed, dropped = memorizer.file_proposals(ledger, proposals, author, scope)
+    _print({"filed": [{"id": r["id"], "type": r["body"]["type"], "statement": r["body"]["statement"][:100]} for r in filed],
+            "dropped": [{"statement": p.get("statement", "")[:100], "reason": why} for p, why in dropped]})
+    return 0
+
+
+def cmd_export(args) -> int:
+    ledger = Ledger.open()
+    reader = _author(args, ledger)  # another user's private receipts are not ours to export
+    try:
+        text = export_mod.export(ledger, args.format, ids=args.ids or None, reader=reader)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8")
+        print(f"wrote {args.output}", file=sys.stderr)
+    else:
+        _print(text)
+    return 0
+
+
+def cmd_fsck(args) -> int:
+    ledger = Ledger.open()
+    rep = ledger.fsck(rewrite=args.rewrite, force=args.force)
+    _print(rep)
+    return 0 if not rep["invalid"] and not rep["corrupt"] else 1
+
+
+def cmd_redact(args) -> int:
+    ledger = Ledger.open()
+    author = _author(args, ledger)
+    if author.get("kind") != "human":
+        print("redaction is a human act: re-run with --as-human (the tombstone records who did it)",
+              file=sys.stderr)
+        return 3
+    tomb = ledger.redact(args.id, args.reason, author)
+    body = tomb["body"]
+    _print({"id": tomb["id"], "kind": tomb["kind"], "redacted": True, "reason": body["reason"],
+            "redacted_by": body["redacted_by"]["user"], "redacted_at": body["redacted_at"],
+            "original_sha256": body["original_sha256"]})
+    print("the content is gone from this copy only: anyone who already pulled this repository still "
+          "has the line, and the ledger's git history does too", file=sys.stderr)
+    return 0
+
+
+def cmd_hook(args) -> int:
+    from . import hooks
+    return hooks.main([args.event], harness=args.harness or hooks.default_harness(), nudge=args.nudge)
+
+
+def cmd_mcp(args) -> int:
+    from . import mcp_server
+    mcp_server.main(args.root)
+    return 0
+
+
+def serve_defaults() -> dict:
+    """The scheduled lane's bounds, from the module that runs it: the flags and the
+    server agree on one set of numbers (imported here so `--help` costs no sqlite)."""
+    from . import serve as serve_mod
+    return {"lane_max": serve_mod.LANE_MAX, "lane_timeout": serve_mod.LANE_TIMEOUT,
+            "lane_older_than": serve_mod.LANE_OLDER_THAN}
+
+
+def cmd_serve(args) -> int:
+    from . import serve as serve_mod
+    return serve_mod.main(host=args.host, port=args.port, tokens=args.tokens, allow_run=args.allow_run,
+                          allow_origin=args.allow_origin or (), recheck_every=args.recheck_every,
+                          git_sync_every=args.git_sync_every, rebuild=args.rebuild, json_logs=args.json_logs,
+                          root=args.root, lane_max=args.lane_max, lane_timeout=args.lane_timeout,
+                          lane_older_than=args.lane_older_than)
+
+
+# --------------------------------------------------------------------------- remote mode
+#
+# With --remote the ledger is somebody else's process. Three things follow, and every
+# function below is an application of them:
+#
+#   * identity comes from the token, so --harness/--model/--user/--as-human are refused
+#     rather than sent and ignored (docs/PROTOCOL.md section 10);
+#   * a flag the HTTP API cannot carry is refused for the same reason: a claim that
+#     silently lost its --ttl-days is a claim nobody can audit;
+#   * `run` still runs here. A receipt is worth what the machine it ran on is worth, so
+#     the command executes locally and only the record travels.
+
+# the local ledger is the whole of what these do; there is nothing to send
+LOCAL_ONLY = ("init", "trust", "fsck", "redact", "keygen", "sign", "recheck", "serve", "hook",
+              "mcp", "compact", "memorize")
+IDENTITY_OVERRIDES = ("as_human", "harness", "model", "user")
+# `verify --timeout` bounds the re-check subprocess, which only the process running it
+# can bound. The parser's default lives here so the remote path can tell a value the
+# caller typed from the one argparse filled in, and refuse only the former.
+VERIFY_TIMEOUT = 600.0
+
+
+def _remote_session(args) -> Optional[str]:
+    """The run a remote record came from: --session, else the harness's own session id
+    when the environment actually names one. It is the only thing a client may declare
+    about itself, and "unknown" declares nothing."""
+    if getattr(args, "session", None):
+        return args.session
+    session = detect_session()
+    return session if session != "unknown" else None
+
+
+def _refuse(command: str, flags: List[str], why: str) -> int:
+    print(f"{command}: {', '.join(flags)} not available over --remote: {why}", file=sys.stderr)
+    return 2
+
+
+def _given(*pairs) -> List[str]:
+    """The flags in ``pairs`` ((flag, value), ...) the caller actually passed."""
+    return [flag for flag, value in pairs if value not in (None, False, (), [], "")]
+
+
+def _remote_scope(args, client, identity: Optional[dict] = None) -> Optional[dict]:
+    """The scope a record POSTed to /records carries, or None to let the server stamp it.
+
+    A record is bound to its project, so the project in the scope has to be the served
+    ledger's own name and not this directory's: only a non-default --scope has to ask
+    /health for it, and a user scope also needs the user the token files under.
+    """
+    level = getattr(args, "scope", None) or "project"
+    if level == "project":
+        return None  # the server builds it from its own project, which is the only right answer
+    user = (identity or client.whoami())["user"] if level == "user" else None
+    return make_scope(level=level, project=client.health()["project"], user=user)
+
+
+def _remote_tier(client, rid: str) -> Optional[str]:
+    """The trust tier the served ledger computes for a claim it just accepted. POST
+    /records answers with the record; the tier is one read away and is what the local
+    `claim` prints."""
+    return ((client.get_record(rid) or {}).get("trust") or {}).get("tier")
+
+
+def _remote_claim(args, client) -> int:
+    """POST /claims for a plain claim; POST /records for one with a binding.
+
+    A commit, file, diff or human binding is computed here, against the checkout the
+    person typing has, which is the only machine that can compute it -- so the claim is
+    built as a record with no author, exactly as `run` builds a receipt, and the server
+    stamps the identity and the id. The binding still has to verify when it is filed:
+    that check happens on the server host, so a path only this machine can see comes
+    back as `rejected: evidence binding does not verify`.
+    """
+    if args.sign:
+        return _refuse("claim", ["--sign"], "signing reads the keys registered in the local ledger")
+    bound = _given(("--commit", args.commit is not None), ("--file", args.file), ("--env", args.env),
+                   ("--diff", args.diff), ("--attest", args.attest))
+    # the token's user is what a human attestation is signed with, and what a user scope
+    # is filed under: one round trip, and only when one of them was asked for
+    identity = client.whoami() if (args.attest or (bound and args.scope == "user")) else None
+    body = {"type": args.type, "statement": args.statement}
+    evidence: List = list(args.evidence or [])
+    try:
+        if args.commit is not None:  # the repo is this directory: there is no other checkout here
+            evidence.append(ev.commit_binding(None, args.commit or None, branch=args.branch))
+        for f in args.file or []:
+            evidence.append(ev.file_binding(f))
+        for f in args.env or []:
+            evidence.append(ev.file_binding(f, role="environment"))
+        if args.diff:
+            base, _, head = args.diff.partition("..")
+            evidence.append(ev.diff_binding(None, base, head or "HEAD"))
+    except ValueError as exc:  # a binding that does not resolve is a rejection, not a crash
+        print(f"rejected: {exc}", file=sys.stderr)
+        return 3
+    if args.attest:
+        evidence.append({"kind": "human", "who": identity["user"], "statement": args.attest})
+    if evidence:
+        body["evidence"] = evidence
+    for key in ("rationale", "example", "outcome", "source", "contract", "confidence", "ttl_days"):
+        val = getattr(args, key, None)
+        if val is not None:
+            body[key] = val
+    if args.expect_exit is not None or args.expect_failed is not None:
+        body["expect"] = {}
+        if args.expect_exit is not None:
+            body["expect"]["exit"] = args.expect_exit
+        if args.expect_failed is not None:
+            body["expect"]["failed"] = args.expect_failed
+    tags, derived = list(args.tag or []), list(args.derived_from or [])
+    if not bound:
+        _print(client.post_claim(dict(body, scope=args.scope, tags=tags, derived_from=derived)))
+        return 0
+    payload = {"kind": "claim", "body": body, "tags": tags, "derived_from": derived}
+    scope = _remote_scope(args, client, identity)
+    if scope:
+        payload["scope"] = scope
+    rec, _ = client.post_record(payload)
+    _print({"id": rec["id"], "type": rec["body"]["type"], "tier": _remote_tier(client, rec["id"])})
+    return 0
+
+
+def _remote_retract(args, client) -> int:
+    """A retraction is a record like any other: built here, filed there under the token.
+
+    The dependents come back from the served ledger, which walks the closure through
+    claims and compactions (what `show` reports), so the list is the one the server will
+    act on rather than one computed from a ledger this machine does not have.
+    """
+    if args.sign:
+        return _refuse("retract", ["--sign"], "signing reads the keys registered in the local ledger")
+    payload = {"kind": "retraction", "body": {"claim": args.claim, "reason": args.reason},
+               "derived_from": [args.claim]}
+    scope = _remote_scope(args, client)
+    if scope:
+        payload["scope"] = scope
+    rec, _ = client.post_record(payload)
+    _print({"id": rec["id"], "tainted_dependents": client.get_record(args.claim).get("dependents") or []})
+    return 0
+
+
+def _remote_list(args, client) -> int:
+    # trust=true is what makes this the same listing as the local one: a page is the
+    # index's answer and carries no tier until the server is asked to add it
+    page = client.list_records(kind=None if args.kind == "all" else args.kind, limit=args.limit,
+                               trust=True)
+    records = page.get("records") or []
+    # the page is newest first; the local `list` prints the newest N oldest-first
+    for rec in reversed(records):
+        body = rec["body"]
+        tier = rec.get("tier") or ""
+        text = (body.get("statement") or body.get("title") or body.get("state") or body.get("cmd")
+                or body.get("claim") or "")
+        print(f"{rec['id']}  {rec['ts'][:16]}  {rec['kind']:<15} "
+              f"{('[' + tier + ']') if tier else '':<15} "
+              f"{rec['author'].get('harness')}: {str(text)[:120]}")
+    if len(records) < args.limit and page.get("next_cursor"):
+        print(f"the served ledger pages at {len(records)} records; there are more", file=sys.stderr)
+    return 0
+
+
+def _remote_run(args, client) -> int:
+    """Run the command here and file the receipt there.
+
+    The server never executes this: a receipt records what happened on the machine that
+    ran the command, and that machine is this one. Only the finished body crosses, with
+    no author on it, so the server stamps the token's identity and computes the id.
+    """
+    if args.sign:
+        return _refuse("run", ["--sign"], "signing reads the keys registered in the local ledger")
+    cmd = list(args.cmd or [])
+    if cmd and cmd[0] == "--":
+        cmd = cmd[1:]
+    if not cmd:
+        print("usage: agent-memory run [--cwd DIR] -- <command...>", file=sys.stderr)
+        return 2
+    if cmd[0].startswith("-"):
+        print(f"usage: agent-memory run [--cwd DIR] -- <command...>; {cmd[0]!r} looks like an option, "
+              "put agent-memory's own options before the --", file=sys.stderr)
+        return 2
+    # no local config to read a redaction list from: the built-in patterns are what
+    # scrubs this body, and they run before the record exists either way
+    body = ev.run_and_capture(cmd if len(cmd) > 1 or not args.shell else cmd[0], cwd=args.cwd or os.getcwd(),
+                              shell=args.shell, timeout=args.timeout)
+    if args.assurance:
+        body["assurance"] = args.assurance
+    if args.no_rerun:
+        body["rerun"] = False
+    rec, _ = client.post_record({"kind": "evidence", "body": body})
+    body = rec["body"]
+    out = {"id": rec["id"], "kind": body["kind"], "assurance": body.get("assurance"),
+           "exit": body["exit"], "duration_ms": body["duration_ms"]}
+    if body.get("redacted"):
+        out["redacted"] = body["redacted"]
+    if body.get("start_error"):
+        out["start_error"] = body["start_error"]
+    if body.get("rerun") is False:
+        out["rerun"] = False
+    if body["kind"] == "test":
+        out.update({"passed": body["passed"], "failed": body["failed"], "summary": body.get("summary")})
+    if not args.quiet:
+        sys.stderr.write(body["stdout_tail"][-1500:])
+        sys.stderr.write(body["stderr_tail"][-800:])
+        if body["stdout_tail"] or body["stderr_tail"]:
+            sys.stderr.write("\n")
+    _print(out)
+    return 0 if body["exit"] == 0 else 1
+
+
+def _remote_verify(args, client) -> int:
+    """Ask the server to re-check a claim on its own host.
+
+    Whether it may is the operator's decision, not ours: without --allow-run the answer
+    is a 403 whose message says to run the re-check where the receipts were made.
+    """
+    if args.sign:
+        return _refuse("verify", ["--sign"], "signing reads the keys registered in the local ledger")
+    refused = _given(("--verdict", args.verdict), ("--map", args.map),
+                     ("--timeout", args.timeout != VERIFY_TIMEOUT))
+    if refused:
+        return _refuse("verify", refused, "POST /verify/{id} carries none of them: the server files what "
+                                          "its own re-check found, under the identity of the token, with "
+                                          "its own path map and its own per-binding timeout")
+    out = client.post_verify(args.claim, strict=args.strict, note=args.note, lens=args.lens)
+    _print(out)
+    return 0 if out.get("verdict") != "refuted" else 1
+
+
+def _remote_compile(args, client) -> int:
+    text, receipt = client.compile(role=args.role, mode=args.mode, task=args.task, contract=args.contract,
+                                   tags=args.tag or (), budget=args.budget, round_no=args.round,
+                                   lens=args.lens, render=args.render, receipt=not args.no_receipt,
+                                   include_tainted=args.include_tainted,
+                                   reliability=not args.no_reliability)
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8")
+        print(f"wrote {args.output}", file=sys.stderr)
+    else:
+        _print(text)
+    if receipt:  # what the server recorded about this reader, whatever the renderer was
+        print(f"compilation receipt {receipt}", file=sys.stderr)
+    return 0
+
+
+def _remote_audit(args, client) -> int:
+    refused = _given(("--recheck", args.recheck), ("--map", args.map))
+    if refused:
+        return _refuse("audit", refused, "GET /audit re-runs nothing; re-check with `verify`, or audit "
+                                         "where the ledger is")
+    rep = client.audit()
+    if args.json:
+        _print(rep)
+    else:
+        # the counters crossed the wire as plain objects, and the report ranks two of them
+        for key in ("authors", "vendors"):
+            rep[key] = Counter(rep.get(key) or {})
+        _print(audit_mod.format_report(rep))
+    return 0
+
+
+def _remote_reliability(args, client) -> int:
+    rep = client.reliability(by=args.by, since=args.since, n_min=args.n_min)
+    _print(rep if args.json else rel_mod.format_report(rep))
+    return 0
+
+
+def _remote_show(args, client) -> int:
+    _print(client.get_record(args.id))
+    return 0
+
+
+def _remote_search(args, client) -> int:
+    for row in client.search(" ".join(args.query), kinds=args.kind or (), limit=args.limit):
+        text = str(row.get("body") or "")
+        print(f"{row['id']}  {row['ts'][:10]}  [{row.get('tier') or '-'}] {row.get('by')}: {text[:160]}")
+    return 0
+
+
+def _remote_contract_status(args, client) -> int:
+    _print(client.contract_status(args.id))
+    return 0
+
+
+def _remote_whoami(args, client) -> int:
+    """Who the token says we are, and which ledger that is: `memory_whoami` over MCP
+    (there is no GET /whoami) plus what /health says about the replica answering."""
+    out = dict(client.whoami())
+    # the tool answered for the MCP session it was asked through, and that session was
+    # deleted a moment later: what a record filed from here would carry is our own
+    out["session"] = client.session or "unknown"
+    out["session_source"] = "client" if client.session else "unknown"
+    out["remote"] = client.base
+    out["server"] = client.health()
+    _print(out)
+    return 0
+
+
+REMOTE_COMMANDS = {
+    "claim": _remote_claim, "run": _remote_run, "verify": _remote_verify, "compile": _remote_compile,
+    "audit": _remote_audit, "reliability": _remote_reliability, "show": _remote_show,
+    "search": _remote_search, "contract status": _remote_contract_status, "whoami": _remote_whoami,
+    "retract": _remote_retract, "list": _remote_list,
+}
+
+
+def run_remote(args, base: str) -> int:
+    """Dispatch one command against a served ledger.
+
+    A command the replica cannot answer refuses here rather than falling through to a
+    local ledger: with --remote given, a ledger under this directory -- if there is one
+    at all -- is not the one the user meant.
+    """
+    command = args.command if args.command != "contract" else f"contract {args.action}"
+    fn = REMOTE_COMMANDS.get(command)
+    if fn is None:
+        why = ("it needs the local ledger" if args.command in LOCAL_ONLY else
+               "the HTTP API has no route for it")
+        print(f"{command}: not available over --remote; {why}. Run it where the ledger is, "
+              f"or drop --remote.", file=sys.stderr)
+        return 2
+    overridden = [f"--{name.replace('_', '-')}" for name in IDENTITY_OVERRIDES if getattr(args, name, None)]
+    if overridden:
+        return _refuse(command, overridden, "the token decides every identity field of every record it "
+                                            "files; --session is the one thing a client may declare")
+    token = remote_mod.resolve_token(args.token)
+    if token and remote_mod.in_the_clear(base):
+        # `serve` terminates no TLS: without a proxy in front of it the token is on the wire
+        print(f"warning: the token goes to {base} in clear text; put TLS in front of the server",
+              file=sys.stderr)
+    client = remote_mod.Client(base, token=token, session=_remote_session(args))
+    try:
+        return fn(args, client)
+    except remote_mod.RemoteError as exc:
+        if exc.status == 422:  # a filing rule, in the server's own words
+            print(f"rejected: {exc.message}", file=sys.stderr)
+            return 3
+        print(f"{command}: {exc}", file=sys.stderr)
+        return 2
+
+
+# --------------------------------------------------------------------------- parser
+
+def _add_identity(p: argparse.ArgumentParser) -> None:
+    g = p.add_argument_group("identity")
+    g.add_argument("--as-human", action="store_true", help="file as a human author (default when not inside a harness)")
+    g.add_argument("--harness", help="override detected harness (claude-code, codex-cli, gemini-cli, ollama, ...)")
+    g.add_argument("--model", help="model name for lineage (e.g. claude-opus-5, qwen3.6-35b)")
+    g.add_argument("--session", help="session id override")
+    g.add_argument("--user", help="user id override")
+    g.add_argument("--scope", choices=["user", "project", "org"], default="project")
+
+
+def _add_signing(p: argparse.ArgumentParser) -> None:
+    g = p.add_argument_group("signing")
+    g.add_argument("--sign", action="store_true",
+                   help="file an ed25519 attestation over the new record (needs strata-agent-memory[sign])")
+    g.add_argument("--key", help=f"key id to sign with (default: ${signing.KEY_ENV}, or the only registered key)")
+
+
+def _add_map(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--map", action="append", metavar="FROM=TO",
+                   help="translate an absolute path recorded in a receipt before re-checking it, so a "
+                        "second machine can answer for it (repeatable; merged over config.path_map and "
+                        f"${pathmap.ENV_VAR})")
+
+
+def _add_llm_key(p: argparse.ArgumentParser) -> None:
+    g = p.add_argument_group("llm credentials")
+    g.add_argument("--llm-api-key", metavar="KEY",
+                   help=f"key for --llm-endpoint (or ${memorizer.API_KEY_ENV}); with neither, no "
+                        "Authorization header is sent. $OPENAI_API_KEY is never read: the endpoint "
+                        "is whatever you typed, and the transcript goes with the key")
+    g.add_argument("--llm-insecure", action="store_true",
+                   help="allow sending the key to a plain http:// endpoint")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="agent-memory", description="Portable, auditable, cross-vendor agent memory.")
+    p.add_argument("--version", action="version", version=f"agent-memory {__version__}")
+    p.add_argument("--remote", metavar="URL",
+                   help=f"file through a ledger served by `agent-memory serve` instead of one under "
+                        f"this directory (or ${remote_mod.REMOTE_ENV}). Goes before the command: "
+                        f"`agent-memory --remote https://host claim ...`. Commands that need the local "
+                        f"ledger refuse; `run` still runs here and files the receipt there")
+    p.add_argument("--token", metavar="T",
+                   help=f"bearer token for --remote (or ${remote_mod.TOKEN_ENV}): it decides the "
+                        f"identity every record it files carries, so --harness, --model, --user and "
+                        f"--as-human are refused over --remote")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("init", help="create .agent-memory in a project (or add missing policy keys)",
+                       description="Create .agent-memory in a project, or add the policy keys an "
+                                   "older ledger is missing (recheck_allow, recheck_allow_shell, "
+                                   "redact). Writes two files outside the project when it creates a "
+                                   f"ledger: ~/{DIR_NAME}/{TRUSTED_REPOS_NAME} (this machine trusts the "
+                                   "repository's config.json) and, with --org, "
+                                   f"~/{DIR_NAME}/{TRUSTED_ORG_PATHS_NAME}. An existing ledger is not trusted "
+                                   "by re-running init: use `agent-memory trust`.")
+    s.add_argument("path", nargs="?")
+    s.add_argument("--project")
+    s.add_argument("--org", help="path to an existing shared org-scope ledger directory")
+    s.add_argument("--user")
+    s.set_defaults(fn=cmd_init)
+
+    s = sub.add_parser("trust", help="trust this repository's config.json on this machine",
+                       description="A config.json is committed, so a clone brings it with it: until "
+                                   "this machine trusts the repository, its recheck_allow, "
+                                   "recheck_allow_shell, redact, path_map, org_path, signers, "
+                                   "vendor_map and cross_vendor_required decide nothing. This "
+                                   f"records the decision in ~/{DIR_NAME}/{TRUSTED_REPOS_NAME}, outside the "
+                                   "repository.")
+    s.add_argument("path", nargs="?", help="a path inside the checkout (default: the current one)")
+    s.set_defaults(fn=cmd_trust)
+
+    s = sub.add_parser("whoami", help="show the identity records will be filed under")
+    _add_identity(s)
+    s.set_defaults(fn=cmd_whoami)
+
+    s = sub.add_parser("run", help="run a command and file an evidence receipt (prints ev_ id)")
+    s.add_argument("--cwd")
+    s.add_argument("--shell", action="store_true", help="run through the shell (pass one quoted string)")
+    s.add_argument("--timeout", type=float, default=600)
+    s.add_argument("--assurance", choices=["static", "dynamic", "adversarial"],
+                   help="override the assurance class of the receipt (default: static for lint/type/check "
+                        "commands and bindings, dynamic for anything executed, adversarial for exploit or fuzz harnesses)")
+    s.add_argument("--no-rerun", action="store_true",
+                   help="mark the receipt do-not-re-run: no lane, audit or server will execute this "
+                        "command again (use it for deploys and migrations; the claim it backs stays "
+                        "evidenced and can never reach verified by re-run)")
+    s.add_argument("-q", "--quiet", action="store_true")
+    s.add_argument("cmd", nargs=argparse.REMAINDER)
+    _add_identity(s)
+    _add_signing(s)
+    s.set_defaults(fn=cmd_run)
+
+    s = sub.add_parser("claim", help="file a claim")
+    s.add_argument("type", choices=sorted(CLAIM_TYPES))
+    s.add_argument("statement")
+    s.add_argument("-e", "--evidence", action="append", help="receipt id (ev_...) from `run`")
+    s.add_argument("--commit", nargs="?", const="", help="bind to a commit sha (default HEAD)")
+    s.add_argument("--branch", help="with --commit: require sha to be an ancestor of this branch")
+    s.add_argument("--file", action="append", help="bind to a file's current hash")
+    s.add_argument("--env", action="append", help="bind to the current hash of an environment file "
+                                                  "(lockfile, version manifest): when it changes the claim goes stale, "
+                                                  "not refuted (repeatable)")
+    s.add_argument("--diff", help="bind to `git diff --stat BASE..HEAD`")
+    s.add_argument("--attest", help="human attestation text (humans only)")
+    s.add_argument("--rationale")
+    s.add_argument("--example")
+    s.add_argument("--outcome", choices=["success", "failure", "unknown"])
+    s.add_argument("--source")
+    s.add_argument("--contract")
+    s.add_argument("--expect-exit", type=int, help="the exit code the cited receipts must show (default 0): "
+                                                   "use it to claim a deliberate failure state")
+    s.add_argument("--expect-failed", type=int, help="with --expect-exit: the number of failing tests the cited "
+                                                     "test receipts must show (default 0)")
+    s.add_argument("--confidence", type=float)
+    s.add_argument("--ttl-days", type=float)
+    s.add_argument("--derived-from", action="append")
+    s.add_argument("-t", "--tag", action="append")
+    _add_identity(s)
+    _add_signing(s)
+    s.set_defaults(fn=cmd_claim)
+
+    s = sub.add_parser("verify", help="re-run a claim's evidence and file a verification")
+    s.add_argument("claim")
+    s.add_argument("--verdict", choices=["verified", "refuted", "inconclusive"], help="override the re-check result")
+    s.add_argument("--note")
+    s.add_argument("--lens", help="review lens (correctness, security, spec, performance, operability, or free text); "
+                                  "stored as the tag lens:<value>")
+    s.add_argument("--strict", action="store_true", help="also require identical stdout hash")
+    s.add_argument("--timeout", type=float, default=VERIFY_TIMEOUT)
+    _add_map(s)
+    _add_identity(s)
+    _add_signing(s)
+    s.set_defaults(fn=cmd_verify)
+
+    s = sub.add_parser("retract", help="retract a claim (taints everything derived from it)")
+    s.add_argument("claim")
+    s.add_argument("reason")
+    _add_identity(s)
+    _add_signing(s)
+    s.set_defaults(fn=cmd_retract)
+
+    s = sub.add_parser("compile", help="compile memory into a context block for a role")
+    s.add_argument("--role", choices=list(ROLES), default="supervisor")
+    s.add_argument("--mode", choices=list(MODES))
+    s.add_argument("--task")
+    s.add_argument("--contract")
+    s.add_argument("-t", "--tag", action="append")
+    s.add_argument("--budget", type=int)
+    s.add_argument("--round", type=int, default=1)
+    s.add_argument("--lens", help="verifier lens: correctness, security, spec, performance, operability, or free text")
+    s.add_argument("--render", choices=sorted(RENDERERS), default="markdown")
+    s.add_argument("--include-tainted", action="store_true")
+    s.add_argument("--no-receipt", action="store_true", help="do not file a compilation receipt")
+    s.add_argument("--no-reliability", action="store_true",
+                   help="do not annotate items with measured reliability (and leave the block out of the receipt)")
+    s.add_argument("-o", "--output")
+    _add_identity(s)
+    s.set_defaults(fn=cmd_compile)
+
+    s = sub.add_parser("search", help="keyword search")
+    s.add_argument("query", nargs="+")
+    s.add_argument("--kind", action="append")
+    s.add_argument("--limit", type=int, default=20)
+    s.set_defaults(fn=cmd_search)
+
+    s = sub.add_parser("show", help="show one record with trust info")
+    s.add_argument("id")
+    s.set_defaults(fn=cmd_show)
+
+    s = sub.add_parser("list", help="list records")
+    s.add_argument("--kind", default="claim", help="claim|evidence|verification|retraction|compaction|compilation|contract|contract_update|all")
+    s.add_argument("--limit", type=int, default=50)
+    s.set_defaults(fn=cmd_list)
+
+    s = sub.add_parser("contract", help="task contracts")
+    cs = s.add_subparsers(dest="action", required=True)
+    c = cs.add_parser("create")
+    c.add_argument("title")
+    c.add_argument("task")
+    c.add_argument("--check", action="append", help="acceptance command expecting exit 0 (repeatable)")
+    c.add_argument("--human-check", action="append")
+    c.add_argument("--file-check", action="append")
+    c.add_argument("--acceptance-json", help="path to a JSON list of acceptance checks")
+    c.add_argument("--assign")
+    c.add_argument("--issue", help="GitHub issue URL or number (source of truth for what work exists)")
+    c.add_argument("-t", "--tag", action="append")
+    _add_identity(c)
+    _add_signing(c)
+    c = cs.add_parser("update")
+    c.add_argument("id")
+    c.add_argument("status", choices=["proposed", "accepted", "in_progress", "submitted", "verified", "closed", "rejected"])
+    c.add_argument("--note")
+    c.add_argument("--claims", nargs="*")
+    _add_identity(c)
+    _add_signing(c)
+    c = cs.add_parser("from-issue", help="create a contract from a GitHub issue (needs the gh CLI)")
+    c.add_argument("ref", help="issue URL, owner/repo#N, or a number in this repository")
+    c.add_argument("--check", action="append", help="acceptance command expecting exit 0 (repeatable)")
+    c.add_argument("--human-check", action="append")
+    c.add_argument("--file-check", action="append")
+    c.add_argument("--assign")
+    c.add_argument("-t", "--tag", action="append")
+    _add_identity(c)
+    c = cs.add_parser("sync", help="comment the contract status on its issue; --close closes the issue")
+    c.add_argument("id")
+    c.add_argument("--close", action="store_true",
+                   help="close the issue, but only when the contract itself is closed")
+    _add_identity(c)
+    c = cs.add_parser("status")
+    c.add_argument("id")
+    _add_identity(c)
+    c = cs.add_parser("accept", help="run the acceptance checks and file receipts")
+    c.add_argument("id")
+    _add_identity(c)
+    c = cs.add_parser("list")
+    _add_identity(c)
+    s.set_defaults(fn=cmd_contract)
+
+    s = sub.add_parser("audit", help="audit report")
+    s.add_argument("--recheck", action="store_true", help="re-run every evidence binding (slow)")
+    _add_map(s)
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(fn=cmd_audit)
+
+    s = sub.add_parser("recheck", help="the verifier lane: re-run selected claims' receipts and file "
+                                       "verifications under the running identity")
+    s.add_argument("--only", choices=list(recheck_mod.ONLY_CHOICES), default="unverified",
+                   help="unverified (tier evidenced, default), stale, or all (everything but refuted/tainted)")
+    s.add_argument("--type", action="append",
+                   help="restrict to these claim types, comma-separated (e.g. outcome,fact)")
+    s.add_argument("--max", type=int, help="stop after this many claims")
+    s.add_argument("--older-than", type=float, metavar="DAYS", help="only claims older than this")
+    s.add_argument("--timeout", type=float, default=600, help="per-binding timeout in seconds")
+    s.add_argument("--min-age-days", type=float, default=recheck_mod.MIN_AGE_DAYS, metavar="DAYS",
+                   help="skip a claim this identity already verified more recently than this "
+                        "(default 1; 0 disables the skip), so a nightly lane does not file the same "
+                        "verdict every night")
+    s.add_argument("--force", action="store_true",
+                   help="re-check even what this identity verified within --min-age-days")
+    _add_map(s)
+    s.add_argument("--dry-run", action="store_true",
+                   help="execute nothing: print the bindings each selected claim would re-run, "
+                        "where, and what the config's allowlist decides about each")
+    s.add_argument("--json", action="store_true")
+    _add_identity(s)
+    s.set_defaults(fn=cmd_recheck)
+
+    s = sub.add_parser("keygen", help="generate an ed25519 signing key and register its public half")
+    s.add_argument("--user", help="the user the key belongs to (default: the detected identity)")
+    s.add_argument("--out", help="directory for the private key (default ~/.agent-memory/keys)")
+    s.set_defaults(fn=cmd_keygen)
+
+    s = sub.add_parser("sign", help="file attestations over existing records")
+    s.add_argument("ids", nargs="+")
+    s.add_argument("--key", help=f"key id to sign with (default: ${signing.KEY_ENV}, or the only registered key)")
+    _add_identity(s)
+    s.set_defaults(fn=cmd_sign)
+
+    s = sub.add_parser("verify-signatures", help="check every attestation in the ledger (exit 3 on any invalid)")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(fn=cmd_verify_signatures)
+
+    s = sub.add_parser("reliability", help="measured reliability: refutation priors, same-lineage agreement, "
+                                          "fitted staleness and judgment calibration")
+    s.add_argument("--by", choices=list(rel_mod.VIEWS), default="cell",
+                   help="cell (the full table and every section), vendor, type, or author")
+    s.add_argument("--since", help="restrict the events (not the claims) to this date onwards, e.g. 2026-01-01")
+    s.add_argument("--n-min", type=int, help="override reliability.n_min (below it the answer is insufficient history)")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(fn=cmd_reliability)
+
+    s = sub.add_parser("compact", help="compact older claims into an ancestry-preserving summary")
+    s.add_argument("--older-than", type=float, help="days")
+    s.add_argument("--contract")
+    s.add_argument("--ids", nargs="*")
+    s.add_argument("-t", "--tag", action="append")
+    s.add_argument("--llm-endpoint", help="OpenAI-compatible base URL for an optional summarization pass")
+    s.add_argument("--llm-model")
+    _add_llm_key(s)
+    s.add_argument("--dry-run", action="store_true")
+    _add_identity(s)
+    s.set_defaults(fn=cmd_compact)
+
+    s = sub.add_parser("memorize", help="extract claims from a transcript with any OpenAI-compatible model")
+    s.add_argument("transcript", help="path or - for stdin")
+    s.add_argument("--llm-endpoint", required=True)
+    s.add_argument("--llm-model", required=True)
+    _add_llm_key(s)
+    s.add_argument("--max", type=int, default=20)
+    s.add_argument("--dry-run", action="store_true")
+    _add_identity(s)
+    s.set_defaults(fn=cmd_memorize)
+
+    s = sub.add_parser("export", help="export the ledger in a standard format")
+    s.add_argument("--format", choices=list(export_mod.FORMATS), default="prov-json",
+                   help="prov-json (W3C PROV for auditors), in-toto (one unsigned Statement per receipt), "
+                        "claim-evidence-map (markdown table of claims, proofs and verdicts)")
+    s.add_argument("--ids", nargs="*", help="limit the export to these record ids")
+    s.add_argument("-o", "--output")
+    s.set_defaults(fn=cmd_export)
+
+    s = sub.add_parser("fsck", help="validate the ledger; --rewrite drops duplicate lines")
+    s.add_argument("--rewrite", action="store_true")
+    s.add_argument("--force", action="store_true",
+                   help="with --rewrite, also drop corrupt lines. Without it they are kept and the "
+                        "report says where each one is: a torn line can hold most of a record whose "
+                        "author was told it was filed")
+    s.set_defaults(fn=cmd_fsck)
+
+    s = sub.add_parser("redact", help="erase a filed record's content, leaving a tombstone with its id, "
+                                      "author and provenance (a captured secret, a name that must not be "
+                                      "in a shared repository)")
+    s.add_argument("id")
+    s.add_argument("--reason", required=True, help="why it was removed; this stays in the ledger")
+    _add_identity(s)
+    s.set_defaults(fn=cmd_redact)
+
+    s = sub.add_parser("hook", help="harness hook adapter (reads hook JSON on stdin)")
+    s.add_argument("event", choices=["session-start", "subagent-start", "stop"])
+    s.add_argument("--harness", choices=["claude-code", "codex-cli", "gemini-cli", "cursor"], default=None,
+                   help="whose hook JSON is on stdin (default: the harness detected from the environment, "
+                        "else claude-code)")
+    s.add_argument("--nudge", action="store_true",
+                   help="on stop, hand the reminder back to the agent once where the harness documents a "
+                        "continuation mechanism (Codex, Cursor); elsewhere it only reaches the user")
+    s.set_defaults(fn=cmd_hook)
+
+    s = sub.add_parser("mcp", help="serve the MCP server over stdio")
+    s.add_argument("--root")
+    s.set_defaults(fn=cmd_mcp)
+
+    s = sub.add_parser("serve", help="serve this ledger over HTTP and remote MCP (a disposable replica)")
+    s.add_argument("--host", default="127.0.0.1", help="a non-loopback host needs a tokens file")
+    s.add_argument("--port", type=int, default=8765)
+    s.add_argument("--tokens", help="JSON file mapping bearer tokens to authors "
+                                    "(default .agent-memory/private/serve-tokens.json)")
+    s.add_argument("--allow-origin", action="append", help="an extra allowed Origin (repeatable); loopback "
+                                                           "origins are always allowed")
+    s.add_argument("--allow-run", action="store_true",
+                   help="let memory_run and POST /verify run commands on this host")
+    s.add_argument("--recheck-every", type=float, metavar="SECONDS",
+                   help="run the recheck lane on this interval under the server identity")
+    s.add_argument("--lane-max", type=int, default=serve_defaults()["lane_max"], metavar="N",
+                   help="claims one scheduled lane run may re-check (default %(default)s)")
+    s.add_argument("--lane-timeout", type=float, default=serve_defaults()["lane_timeout"], metavar="SECONDS",
+                   help="per-binding timeout in the scheduled lane (default %(default)s)")
+    s.add_argument("--lane-older-than", type=float, default=serve_defaults()["lane_older_than"], metavar="DAYS",
+                   help="only re-check claims last verified this long ago (default %(default)s)")
+    s.add_argument("--git-sync-every", type=float, metavar="SECONDS",
+                   help="commit, pull --rebase and push the ledger on this interval")
+    s.add_argument("--rebuild", action="store_true", help="rebuild the SQLite index from the shards")
+    s.add_argument("--json-logs", action="store_true", help="write the request log to stdout instead of stderr")
+    s.add_argument("--root")
+    s.set_defaults(fn=cmd_serve)
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        base = remote_mod.resolve_base(args.remote)
+    except ValueError as exc:  # a URL that is not one: a typo, not a server that is down
+        print(f"--remote: {exc}", file=sys.stderr)
+        return 2
+    try:
+        if base:
+            return run_remote(args, base)
+        return int(args.fn(args) or 0)
+    except FileNotFoundError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    except ConfigError as exc:  # a config.json nobody can parse is a message, not a traceback
+        print(str(exc), file=sys.stderr)
+        return 2
+    except ValidationError as exc:
+        print(f"rejected: {exc}", file=sys.stderr)
+        return 3
+    except KeyError as exc:
+        print(f"not found: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())