atmem 2.3.3__tar.gz → 2.3.4__tar.gz

{atmem-2.3.3/atmem.egg-info → atmem-2.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atmem
-Version: 2.3.3
+Version: 2.3.4
 Summary: Host-neutral Agent Black Box and reversible memory control plane.
 Author-email: Javad Taghia <taghia.javad@gmail.com>
 Maintainer-email: Aetna / AtMem <aetna000@gmail.com>
@@ -25,7 +25,9 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: atmem-atbot==0.1.0
+Requires-Dist: atflows==0.1.1
 Requires-Dist: cryptography<49,>=42
+Provides-Extra: atflows
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
@@ -77,12 +79,12 @@ Dynamic: license-file
 
 # AtMem
 
-[![Version 2.3.3](https://img.shields.io/badge/version-2.3.3-blue)](./docs/releases/v2.3.3.md)
+[![Version 2.3.4](https://img.shields.io/badge/version-2.3.4-blue)](./docs/releases/v2.3.4.md)
 [![CI](https://github.com/aetna000/atmem/actions/workflows/ci.yml/badge.svg)](https://github.com/aetna000/atmem/actions/workflows/ci.yml)
 
 **AtMem is a host-neutral Agent Black Box and reversible memory control plane.**
 
-> **Release status:** AtMem 2.3.3 is the stable encrypted Agent Black Box release.
+> **Release status:** AtMem 2.3.4 is the stable Agent Black Box and governed-memory release. It installs AtFlows 0.1.1 by default, with optional AtMem-owned login and read-only review leads.
 > It records exact host-observed text and supported multimodal boundaries by default,
 > while keeping every claim limited to what the connected agent actually supplied.
 
@@ -99,7 +101,7 @@ authorizes, stores, scopes, injects, corrects, and deletes memory.
 ### 1. Install AtMem and choose memory intelligence
 
 ```bash
-python -m pip install --upgrade atmem==2.3.3
+python -m pip install --upgrade atmem==2.3.4
 atmem atbot setup
 atmem atbot doctor
 atmem init
@@ -132,7 +134,7 @@ package yourself.
 Already using AtMem 2.1 with OpenClaw? Upgrade in place:
 
 ```bash
-python -m pip install --upgrade atmem==2.3.3
+python -m pip install --upgrade atmem==2.3.4
 atmem openclaw upgrade
 atmem control verify
 ```
@@ -155,7 +157,7 @@ selected by `python`, rather than an unrelated `pip` executable on `PATH`.
 #### Pydantic AI — native capability
 
 ```bash
-python -m pip install 'atmem[pydantic-ai]==2.3.3'
+python -m pip install 'atmem[pydantic-ai]==2.3.4'
 atmem control shadow --host generic --memory-db ~/.atmem/memories.db
 ```
 
@@ -180,7 +182,7 @@ agent = Agent("openai:gpt-5-mini", capabilities=[memory])
 #### LangChain/LangGraph — native middleware
 
 ```bash
-python -m pip install 'atmem[langgraph]==2.3.3'
+python -m pip install 'atmem[langgraph]==2.3.4'
 atmem control shadow --host generic --memory-db ~/.atmem/memories.db
 ```
 
@@ -244,7 +246,7 @@ open tasks. AtBot may propose a change, but AtMem revalidates and commits it.
 
 See the [Governed Task State guide](docs/governed-task-state.md) for lifecycle,
 correction, provenance, expiry, benchmark, and automation examples, and read
-the [2.3.3 release notes](docs/releases/v2.3.3.md) before upgrading.
+the [2.3.4 release notes](docs/releases/v2.3.4.md) before upgrading.
 
 ### Prove memory quality locally
 
@@ -258,8 +260,9 @@ perfect; other quality metrics cannot fall below checked-in baselines. Optional
 local/hosted profiles, LongMemEval import and fair Mem0 OSS comparison are also
 available without adding Mem0 or model SDKs to the base install. See the
 [memory benchmark guide](docs/benchmarks.md) for commands and honest limits.
-The [2.3.3 release](docs/releases/v2.3.3.md) improves local retrieval work and
-archive layout while retaining existing retrieval defaults. Developer opt-in
+The retrieval and archive improvements from [2.3.3](docs/releases/v2.3.3.md)
+remain in [2.3.4](docs/releases/v2.3.4.md), which adds the optional AtFlows
+observability and shared-login scope. Developer opt-in
 fusion, scoped graph nomination and matrix reuse are available for evaluation;
 broader performance targets remain research, not release claims.
 
@@ -346,7 +349,7 @@ and restores it exactly.
 ## Installation details
 
 ```bash
-python -m pip install atmem==2.3.3
+python -m pip install atmem==2.3.4
 atmem --version
 ```
 
@@ -356,7 +359,7 @@ embedding model, while the semantic extra adds local sentence-transformer
 choices:
 
 ```bash
-python -m pip install 'atmem[semantic]==2.3.3'
+python -m pip install 'atmem[semantic]==2.3.4'
 ```
 
 For repository development, install both workspace packages:
@@ -544,7 +547,7 @@ atmem control restore
 Existing 2.1 installations upgrade without starting a new migration:
 
 ```bash
-python -m pip install --upgrade atmem==2.3.3
+python -m pip install --upgrade atmem==2.3.4
 atmem openclaw upgrade
 atmem control verify
 ```
@@ -715,6 +718,11 @@ system-of-record verification.
 
 ## Documentation map
 
+Official website documentation is maintained through the public
+[documentation inventory](docs/website/manifest.json). See
+[how to contribute and update release docs](docs/website-contributing.md).
+Website publication follows a separate owner-reviewed, main-only deployment.
+
 - [Current implementation status](docs/current-status.md)
 - [Generic runtime adapter](docs/generic-adapter.md)
 - [Delegated context-provider contract](docs/contracts/delegated-context-provider-v1.md)
@@ -772,8 +780,8 @@ npm test
 npm run smoke
 ```
 
-Current repository metadata is version **2.3.3**, with the matched OpenClaw
-bridge **2.3.3**. Release validation requires exact Python/bridge alignment;
+Current source metadata is the **2.3.4 stable target**, with matched OpenClaw
+bridge source **2.3.4**. Release validation requires exact Python/bridge alignment;
 AtBot retains its independent stable compatible version **0.1.0**.
 
 ## License

{atmem-2.3.3 → atmem-2.3.4}/README.md

@@ -1,11 +1,11 @@
 # AtMem
 
-[![Version 2.3.3](https://img.shields.io/badge/version-2.3.3-blue)](./docs/releases/v2.3.3.md)
+[![Version 2.3.4](https://img.shields.io/badge/version-2.3.4-blue)](./docs/releases/v2.3.4.md)
 [![CI](https://github.com/aetna000/atmem/actions/workflows/ci.yml/badge.svg)](https://github.com/aetna000/atmem/actions/workflows/ci.yml)
 
 **AtMem is a host-neutral Agent Black Box and reversible memory control plane.**
 
-> **Release status:** AtMem 2.3.3 is the stable encrypted Agent Black Box release.
+> **Release status:** AtMem 2.3.4 is the stable Agent Black Box and governed-memory release. It installs AtFlows 0.1.1 by default, with optional AtMem-owned login and read-only review leads.
 > It records exact host-observed text and supported multimodal boundaries by default,
 > while keeping every claim limited to what the connected agent actually supplied.
 
@@ -22,7 +22,7 @@ authorizes, stores, scopes, injects, corrects, and deletes memory.
 ### 1. Install AtMem and choose memory intelligence
 
 ```bash
-python -m pip install --upgrade atmem==2.3.3
+python -m pip install --upgrade atmem==2.3.4
 atmem atbot setup
 atmem atbot doctor
 atmem init
@@ -55,7 +55,7 @@ package yourself.
 Already using AtMem 2.1 with OpenClaw? Upgrade in place:
 
 ```bash
-python -m pip install --upgrade atmem==2.3.3
+python -m pip install --upgrade atmem==2.3.4
 atmem openclaw upgrade
 atmem control verify
 ```
@@ -78,7 +78,7 @@ selected by `python`, rather than an unrelated `pip` executable on `PATH`.
 #### Pydantic AI — native capability
 
 ```bash
-python -m pip install 'atmem[pydantic-ai]==2.3.3'
+python -m pip install 'atmem[pydantic-ai]==2.3.4'
 atmem control shadow --host generic --memory-db ~/.atmem/memories.db
 ```
 
@@ -103,7 +103,7 @@ agent = Agent("openai:gpt-5-mini", capabilities=[memory])
 #### LangChain/LangGraph — native middleware
 
 ```bash
-python -m pip install 'atmem[langgraph]==2.3.3'
+python -m pip install 'atmem[langgraph]==2.3.4'
 atmem control shadow --host generic --memory-db ~/.atmem/memories.db
 ```
 
@@ -167,7 +167,7 @@ open tasks. AtBot may propose a change, but AtMem revalidates and commits it.
 
 See the [Governed Task State guide](docs/governed-task-state.md) for lifecycle,
 correction, provenance, expiry, benchmark, and automation examples, and read
-the [2.3.3 release notes](docs/releases/v2.3.3.md) before upgrading.
+the [2.3.4 release notes](docs/releases/v2.3.4.md) before upgrading.
 
 ### Prove memory quality locally
 
@@ -181,8 +181,9 @@ perfect; other quality metrics cannot fall below checked-in baselines. Optional
 local/hosted profiles, LongMemEval import and fair Mem0 OSS comparison are also
 available without adding Mem0 or model SDKs to the base install. See the
 [memory benchmark guide](docs/benchmarks.md) for commands and honest limits.
-The [2.3.3 release](docs/releases/v2.3.3.md) improves local retrieval work and
-archive layout while retaining existing retrieval defaults. Developer opt-in
+The retrieval and archive improvements from [2.3.3](docs/releases/v2.3.3.md)
+remain in [2.3.4](docs/releases/v2.3.4.md), which adds the optional AtFlows
+observability and shared-login scope. Developer opt-in
 fusion, scoped graph nomination and matrix reuse are available for evaluation;
 broader performance targets remain research, not release claims.
 
@@ -269,7 +270,7 @@ and restores it exactly.
 ## Installation details
 
 ```bash
-python -m pip install atmem==2.3.3
+python -m pip install atmem==2.3.4
 atmem --version
 ```
 
@@ -279,7 +280,7 @@ embedding model, while the semantic extra adds local sentence-transformer
 choices:
 
 ```bash
-python -m pip install 'atmem[semantic]==2.3.3'
+python -m pip install 'atmem[semantic]==2.3.4'
 ```
 
 For repository development, install both workspace packages:
@@ -467,7 +468,7 @@ atmem control restore
 Existing 2.1 installations upgrade without starting a new migration:
 
 ```bash
-python -m pip install --upgrade atmem==2.3.3
+python -m pip install --upgrade atmem==2.3.4
 atmem openclaw upgrade
 atmem control verify
 ```
@@ -638,6 +639,11 @@ system-of-record verification.
 
 ## Documentation map
 
+Official website documentation is maintained through the public
+[documentation inventory](docs/website/manifest.json). See
+[how to contribute and update release docs](docs/website-contributing.md).
+Website publication follows a separate owner-reviewed, main-only deployment.
+
 - [Current implementation status](docs/current-status.md)
 - [Generic runtime adapter](docs/generic-adapter.md)
 - [Delegated context-provider contract](docs/contracts/delegated-context-provider-v1.md)
@@ -695,8 +701,8 @@ npm test
 npm run smoke
 ```
 
-Current repository metadata is version **2.3.3**, with the matched OpenClaw
-bridge **2.3.3**. Release validation requires exact Python/bridge alignment;
+Current source metadata is the **2.3.4 stable target**, with matched OpenClaw
+bridge source **2.3.4**. Release validation requires exact Python/bridge alignment;
 AtBot retains its independent stable compatible version **0.1.0**.
 
 ## License

{atmem-2.3.3 → atmem-2.3.4}/atmem/cli.py

@@ -6,9 +6,12 @@ from importlib.metadata import PackageNotFoundError, version
 import json
 import os
 from pathlib import Path
+import re
 import shutil
+import site
 import subprocess
 import sys
+import sysconfig
 from typing import Any
 from urllib.parse import urlencode
 
@@ -44,6 +47,122 @@ def _installed_version() -> str:
         return "unknown"
 
 
+def _companion_version(package: str) -> str:
+    try:
+        return version(package)
+    except PackageNotFoundError:
+        return "not installed"
+
+
+def _safe_atflows_status(output: str) -> str:
+    """Retain only bounded loopback links from the companion status output."""
+    rows: list[str] = []
+    pattern = re.compile(
+        r"Dashboard:\s*http://(localhost|127\.0\.0\.1):(\d{1,5})\s+"
+        r"Proxy:\s*http://(localhost|127\.0\.0\.1):(\d{1,5})"
+    )
+    for match in pattern.finditer(output[:4096]):
+        dashboard_host, dashboard_port, proxy_host, proxy_port = match.groups()
+        if not 1 <= int(dashboard_port) <= 65535 or not 1 <= int(proxy_port) <= 65535:
+            continue
+        # Review accepts numeric loopback only; display copyable compatible URLs.
+        dashboard_host = "127.0.0.1" if dashboard_host == "localhost" else dashboard_host
+        proxy_host = "127.0.0.1" if proxy_host == "localhost" else proxy_host
+        rows.append(
+            f"Dashboard: http://{dashboard_host}:{dashboard_port}  "
+            f"Proxy: http://{proxy_host}:{proxy_port}"
+        )
+        if len(rows) == 8:
+            break
+    return "\n".join(rows) if rows else "No running AtFlows server reported."
+
+
+def _atflows_executable(expected_version: str) -> Path | None:
+    name = "atflows.exe" if os.name == "nt" else "atflows"
+    paths = [
+        Path(sys.executable).with_name(name),
+        Path(sysconfig.get_path("scripts")) / name,
+        Path(site.getuserbase()) / ("Scripts" if os.name == "nt" else "bin") / name,
+    ]
+    found = shutil.which("atflows")
+    if found:
+        paths.append(Path(found))
+    for path in dict.fromkeys(paths):
+        if not path.is_file():
+            continue
+        try:
+            result = subprocess.run(
+                [str(path), "--version"], capture_output=True, text=True,
+                timeout=5, check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            continue
+        if result.returncode == 0 and result.stdout.strip() == f"atflows {expected_version}":
+            return path
+    return None
+
+
+def _run_install_status(args: argparse.Namespace) -> None:
+    """Report installed packages and local service links without starting them."""
+    from atmem.dashboard_daemon import manage_dashboard_daemon
+    from atmem.home.layout import resolve_home
+
+    dashboard = manage_dashboard_daemon("status")
+    atflows_version = _companion_version("atflows")
+    atflows_bin = (
+        _atflows_executable(atflows_version)
+        if atflows_version != "not installed" else None
+    )
+    atflows_status = (
+        "AtFlows CLI unavailable in this Python environment."
+        if atflows_version != "not installed" else
+        "AtFlows is not installed in this Python environment."
+    )
+    if atflows_bin is not None:
+        try:
+            result = subprocess.run(
+                [str(atflows_bin), "status"], capture_output=True, text=True,
+                timeout=5, check=False,
+            )
+            atflows_status = (
+                _safe_atflows_status(result.stdout)
+                if result.returncode == 0 else
+                "Status unavailable; run `atflows status` to retry."
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            atflows_status = "Status unavailable; run `atflows status` to retry."
+    report = {
+        "format": "atmem-install-status-v1",
+        "packages": {
+            "atmem": _installed_version(),
+            "atmem-atbot": _companion_version("atmem-atbot"),
+            "atflows": atflows_version,
+        },
+        "home": str(resolve_home()),
+        "dashboard": {
+            "running": bool(dashboard.get("running")),
+            "url": dashboard.get("url") if dashboard.get("running") else None,
+        },
+        "atflows_status": atflows_status,
+    }
+    if args.json:
+        _print(report)
+        return
+    print("AtMem installation\n")
+    for label, package in (("AtMem", "atmem"), ("AtBot", "atmem-atbot"), ("AtFlows", "atflows")):
+        print(f"  {label:<18}{report['packages'][package]}")
+    print(f"  {'AtMem Home':<18}{report['home']}")
+    print("\nLocal dashboards")
+    print("  AtMem              " + (str(report["dashboard"]["url"]) if report["dashboard"]["running"] else "No managed service record (manual start may still be running)"))
+    for line in atflows_status.splitlines():
+        print("  " + line)
+    print("\nNext steps")
+    print("  atmem init         Create the local Administrator; copy its one-time password")
+    print("  atflows init       Set up AtFlows when you want tracing and review")
+    print("  atflows status     Show its running dashboard and proxy URLs")
+    print("  AtBot setup and behaviour are unchanged.")
+
+
 def _run_features(args: argparse.Namespace) -> None:
     from atmem.contracts.versions import capabilities
     manifest = capabilities()
@@ -75,6 +194,9 @@ def main() -> None:
         description="Governed memory and agent oversight, with optional AtBot intelligence.",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""Start here:
+  atmem status
+      Show installed package versions and running local dashboard links.
+
   atmem atbot setup
       Choose local AI, a hosted API, or the safe deterministic fallback.
 
@@ -100,6 +222,11 @@ Run `atmem COMMAND --help` for command-specific examples.""",
     )
     subparsers = parser.add_subparsers(dest="command")
 
+    status_parser = subparsers.add_parser(
+        "status", help="Show installed companions, local dashboards and setup steps"
+    )
+    status_parser.add_argument("--json", action="store_true")
+
     home_parser = subparsers.add_parser(
         "home", help="Inspect, verify, migrate or adopt the portable AtMem Home"
     )
@@ -1343,7 +1470,8 @@ or input errors.""",
         command_parser = evidence_commands.add_parser(name, help=help_text)
         command_parser.add_argument("--state", default=None)
         if name not in {"status", "create-test-accounts"}:
-            command_parser.add_argument("--token", required=True)
+            command_parser.add_argument("--token", help="Legacy evidence token argument (visible in process listings)")
+            command_parser.add_argument("--token-env", default="ATMEM_EVIDENCE_TOKEN", help="Environment variable containing the evidence token")
         if name in {"show", "reconstruct", "replay-manifest", "delete-run", "export-plaintext"}:
             command_parser.add_argument("run_id")
         if name == "search":
@@ -1362,6 +1490,26 @@ or input errors.""",
             command_parser.add_argument("--confirm", required=True)
             command_parser.add_argument("--output", required=True)
 
+    atflows_parser = subparsers.add_parser(
+        "atflows", help="Inspect optional AtFlows telemetry against protected AtMem evidence"
+    )
+    atflows_commands = atflows_parser.add_subparsers(dest="atflows_command")
+    atflows_review = atflows_commands.add_parser(
+        "review", help="Produce read-only exact-session review leads"
+    )
+    atflows_review.add_argument("run_id")
+    atflows_review.add_argument("--session-id", required=True)
+    atflows_review.add_argument("--since-ms", type=int, required=True)
+    atflows_review.add_argument("--until-ms", type=int, required=True)
+    atflows_review.add_argument("--token", help="AtMem evidence token (legacy argument; visible in process listings)")
+    atflows_review.add_argument("--token-env", default="ATMEM_EVIDENCE_TOKEN", help="Environment variable containing the AtMem evidence token")
+    atflows_review.add_argument("--state", default=None)
+    atflows_review.add_argument("--base-url", default="http://127.0.0.1:1337")
+    atflows_review.add_argument("--password-env", default="ATFLOWS_ADMIN_PASSWORD")
+    atflows_output = atflows_review.add_mutually_exclusive_group()
+    atflows_output.add_argument("--json", action="store_true", help="Print the versioned JSON report (default)")
+    atflows_output.add_argument("--human", action="store_true", help="Print a concise human-readable report")
+
     verify_run_parser = subparsers.add_parser(
         "verify-run",
         help="Verify one agent run and print its unified coverage report",
@@ -1388,6 +1536,10 @@ or input errors.""",
         _print_cli_welcome(parser)
         return
 
+    if args.command == "status":
+        _run_install_status(args)
+        return
+
     if args.command == "init":
         _run_identity_init(args)
         return
@@ -1476,6 +1628,13 @@ or input errors.""",
         _run_evidence(args)
         return
 
+    if args.command == "atflows":
+        if args.atflows_command is None:
+            atflows_parser.print_help()
+            return
+        _run_atflows(args)
+        return
+
     if args.command == "verify-run":
         args.blackbox_command = "verify"
         _run_blackbox(args)
@@ -3722,6 +3881,8 @@ def _print_cli_welcome(parser: argparse.ArgumentParser) -> None:
     print("     atmem dashboard\n")
     print("  5. Check AtBot and its configured model")
     print("     atmem atbot doctor\n")
+    print("  6. Check installed packages and local dashboard links")
+    print("     atmem status\n")
     print("AtMem starts safely: no memory injection is enabled until you explicitly activate it.")
     print("Run `atmem --help` for every command or `atmem atbot` for provider examples.")
 
@@ -4013,25 +4174,31 @@ def _identity_manager(state_path: str | None):
     return manager
 
 
-def _print_bootstrap(value: dict[str, Any], *, as_json: bool = False) -> None:
+def _print_bootstrap(value: dict[str, Any], *, as_json: bool = False, port: int = 8766) -> None:
     if as_json:
         _print(value)
         return
     if not value.get("created"):
         print("AtMem is already initialized. Existing credentials were not changed or disclosed.")
-        print("Dashboard: http://127.0.0.1:8766/")
+        print(f"Dashboard: http://127.0.0.1:{port}/")
         return
-    print("AtMem local Administrator created")
+    print("AtMem local setup\n")
+    print(f"  AtMem              {_installed_version()}")
+    print(f"  AtBot              {_companion_version('atmem-atbot')}")
+    print(f"  AtFlows            {_companion_version('atflows')}")
+    print(f"  Dashboard          http://127.0.0.1:{port}/")
     print(f"  Username           {value['username']}")
-    print(f"  Temporary password {value['password']}")
-    print("  Dashboard          http://127.0.0.1:8766/")
-    print("Sign in and change this temporary password. It will not be shown again.")
+    print("\n  Temporary password (copy now):")
+    print(f"    {value['password']}")
+    print("\nSign in and change this password; it will not be shown again.")
+    print("Run `atflows init` when you want to set up tracing and its own Administrator.")
+    print("Run `atmem status` or `atflows status` for local dashboard links.")
 
 
 def _run_identity_init(args: argparse.Namespace) -> None:
     manager = _identity_manager(args.state)
     bootstrap = manager.identity_service().bootstrap()
-    _print_bootstrap(bootstrap, as_json=args.json)
+    _print_bootstrap(bootstrap, as_json=args.json, port=args.port)
     if args.json or args.no_open or not bootstrap.get("created"):
         return
     from atmem.dashboard_daemon import _open_default_browser, manage_dashboard_daemon
@@ -4190,7 +4357,7 @@ def _serve_dashboard(
         if not sys.stdin.isatty():
             raise ValueError("local identity is not initialized; run `atmem init` before starting the dashboard daemon")
         bootstrap = identity.bootstrap()
-        _print_bootstrap(bootstrap)
+        _print_bootstrap(bootstrap, port=port)
     from atmem.control.atbot_service import AtBotServiceManager
 
     atbot_manager = AtBotServiceManager()
@@ -4577,6 +4744,99 @@ def _run_blackbox(args: argparse.Namespace) -> None:
         print(format_flight_report(report), end="")
 
 
+def _format_atflows_review(report: dict[str, Any]) -> str:
+    coverage = report["coverage"]
+    lines = [
+        "AtMem + AtFlows review",
+        f"  Run             {report['run_id']}",
+        f"  Session         {report['session_id']}",
+        f"  Correlation     {report['correlation']}",
+    ]
+    if report.get("reason"):
+        lines.append(f"  Reason          {report['reason']}")
+    if coverage["reported"]:
+        lines.append(
+            f"  Coverage        {coverage['atflows_rows']} rows, "
+            f"{coverage['unique_traces']} traces"
+            + (" (truncated)" if coverage["truncated"] else "")
+        )
+    else:
+        lines.append("  Coverage        not reported without an authorized exact-session link")
+    lines.append(f"  Review leads    {len(report['leads'])}")
+    for lead in report["leads"]:
+        lines.append(f"    {lead['reason_code']}: {lead['trace_id']}")
+    lines.append(f"  Limit           {report['limitation']}")
+    return "\n".join(lines) + "\n"
+
+
+def _read_evidence_token(args: argparse.Namespace) -> str:
+    token = args.token or os.environ.get(args.token_env)
+    if not token and sys.stdin.isatty():
+        token = getpass.getpass("AtMem evidence token: ")
+    if not token:
+        raise ValueError("AtMem evidence token is required; set the selected token environment variable or use --token")
+    return token
+
+
+def _run_atflows(args: argparse.Namespace) -> None:
+    from atmem.control.manager import ControlPlaneManager, DEFAULT_STATE_PATH
+    from atmem.evidence.models import EvidenceOperation, EvidenceScope
+    from atmem.integrations.atflows import auth_mode, fetch_traces, review_leads
+
+    manager = ControlPlaneManager(args.state or str(DEFAULT_STATE_PATH))
+    service = manager.evidence_service()
+    principal = service.authenticate(_read_evidence_token(args))
+    if principal is None:
+        raise ValueError("invalid evidence account token")
+    principal.authorize(
+        EvidenceOperation.VIEW,
+        EvidenceScope(
+            principal.scope.tenant_id,
+            principal.scope.subject_id,
+            principal.scope.workspace_id,
+            args.run_id,
+        ),
+    )
+    if auth_mode(args.base_url) == "atmem":
+        username = os.environ.get("ATMEM_USERNAME") or input("AtMem username: ")
+        password = os.environ.get("ATMEM_PASSWORD") or getpass.getpass("AtMem password: ")
+        identity = manager.identity_service()
+        session = identity.login(username, password)
+        token = session["session_token"]
+        try:
+            traces = fetch_traces(
+                base_url=args.base_url,
+                atmem_session=token,
+                session_id=args.session_id,
+                since_ms=args.since_ms,
+                until_ms=args.until_ms,
+            )
+        finally:
+            identity.logout(token)
+    else:
+        password = os.environ.get(args.password_env) or getpass.getpass("AtFlows Administrator password: ")
+        traces = fetch_traces(
+            base_url=args.base_url,
+            password=password,
+            session_id=args.session_id,
+            since_ms=args.since_ms,
+            until_ms=args.until_ms,
+        )
+    report = review_leads(
+        service,
+        principal,
+        run_id=args.run_id,
+        session_id=args.session_id,
+        traces=traces,
+        since_ms=args.since_ms,
+        until_ms=args.until_ms,
+    )
+    if args.human:
+        print(_format_atflows_review(report), end="")
+    else:
+        _print(report)
+
+
 def _run_evidence(args: argparse.Namespace) -> None:
     from atmem.control.manager import ControlPlaneManager, DEFAULT_STATE_PATH
     from atmem.evidence import CaptureMode, EvidenceRole, EvidenceScope
@@ -4598,7 +4858,7 @@ def _run_evidence(args: argparse.Namespace) -> None:
             }
         )
         return
-    principal = service.authenticate(args.token)
+    principal = service.authenticate(_read_evidence_token(args))
     if principal is None:
         raise ValueError("invalid evidence account token")
     if command == "show":