sid-harness 0.3.0__py3-none-any.whl

sid_harness/cli.py

@@ -0,0 +1,937 @@
+"""``sid`` CLI entry point.
+
+    sid run --task "<goal>" --dir <path> [--model auto] [--verify] [--context]
+    sid session start|resume|replay
+    sid tools [--mcp CMD] [--json]
+    sid policy --dir <path> [--json]
+
+One engine (the shared SID native loop), SID as the only model backend.
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import shlex
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import __version__, config
+from .client import SIDClient, SIDClientError
+from .local_workspace import LocalWorkspace, LocalWorkspaceError
+from .runner import RunError, RunOutcome, execute_run
+from .session import Session, SessionError, SessionStoreError
+from .session.bounds import BoundsError, SessionBounds
+from .workspace import WorkspaceError
+
+
+def _add_common_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--base-url", default=None, help="SID /v1 base URL (env SID_BASE_URL).")
+    parser.add_argument("--api-key", default=None, help="Your SID key (env SID_API_KEY).")
+    parser.add_argument("--model", default="auto", help="Model id or 'auto' (default).")
+    parser.add_argument("--routing-profile", default=None, help="X-Routing-Profile (default: agent).")
+    parser.add_argument("--criteria", action="append", default=None, help="Acceptance criterion (repeatable).")
+    parser.add_argument("--out-of-scope", action="append", default=None, help="Out-of-scope item (repeatable).")
+    parser.add_argument("--max-tokens", type=int, default=8000)
+    parser.add_argument("--reasoning-effort", default=None)
+    parser.add_argument("--verify", action="store_true", help="Also review the produced diff via /v1/verify/patch.")
+    parser.add_argument(
+        "--write",
+        action="store_true",
+        help="Apply the loop's changed files to the real working tree (default: read-only).",
+    )
+    parser.add_argument(
+        "--allow-delete",
+        action="store_true",
+        help=(
+            "Explicitly approve deletions the run proposes (default: deny). "
+            "Deletions are never applied silently."
+        ),
+    )
+    parser.add_argument(
+        "--test-cmd",
+        default=None,
+        metavar="CMD",
+        help=(
+            "Human-approved test command to run locally in --dir (SUB-80). "
+            "Split into an argv list and executed without a shell, with a "
+            "bounded timeout and bounded output."
+        ),
+    )
+    parser.add_argument("--receipt", default=None, help="Receipt JSON path (default: <dir>/.sid/runs/<run_id>.json).")
+    parser.add_argument("--json", action="store_true", help="Print the receipt JSON to stdout.")
+    parser.add_argument("--quiet", action="store_true")
+    parser.add_argument(
+        "--context",
+        action="store_true",
+        help="Prepend repo-scale retrieved context for the task (SUB-55; read-only).",
+    )
+    parser.add_argument(
+        "--context-k",
+        type=int,
+        default=4,
+        help="Number of retrieved context chunks to prepend (default: 4).",
+    )
+    parser.add_argument(
+        "--mcp",
+        action="append",
+        default=None,
+        metavar="CMD",
+        help="Connect an MCP stdio server (e.g. --mcp 'npx -y @some/mcp') and expose its tools (repeatable).",
+    )
+    parser.add_argument(
+        "--bounds-config",
+        default=None,
+        help="JSON file overriding loop bounds (turns/tool calls/workspace size).",
+    )
+    parser.add_argument(
+        "--no-diagnostics",
+        dest="diagnostics",
+        action="store_false",
+        default=True,
+        help="Ignore the editor/LSP diagnostics feed for this run (SUB-96).",
+    )
+
+
+def _add_project_options(parser: argparse.ArgumentParser) -> None:
+    """SUB-94: project rules/skills/subagents/plan on the CLI run paths."""
+    parser.add_argument(
+        "--skills",
+        action="append",
+        default=None,
+        metavar="NAME",
+        help=(
+            "Load a named skill from the project's .opencode/skills (repeatable; "
+            "SUB-94). Without --skills, .sid/config 'skills' applies."
+        ),
+    )
+    parser.add_argument(
+        "--skills-root",
+        default=None,
+        metavar="DIR",
+        help="Skills directory to load from (default: nearest .opencode/skills).",
+    )
+    parser.add_argument(
+        "--subagent",
+        action="append",
+        default=None,
+        metavar="TASK",
+        help=(
+            "Run TASK as a parallel subagent through the same loop and feed its "
+            "findings to the main run (repeatable; SUB-94)."
+        ),
+    )
+    parser.add_argument(
+        "--plan",
+        action="store_true",
+        help="Run read-only plan mode: propose a plan, write nothing (SUB-94).",
+    )
+    parser.add_argument(
+        "--todo",
+        action="append",
+        default=None,
+        metavar="TEXT",
+        help="Seed the run's todo list (repeatable; SUB-94).",
+    )
+
+
+def _add_session_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--approve",
+        action="store_true",
+        help="Approve the proposed diff for --write without prompting.",
+    )
+
+
+def _add_git_write_options(parser: argparse.ArgumentParser) -> None:
+    """Explicit opt-in for the git write path (SUB-95). Default stays read-only."""
+    parser.add_argument(
+        "--git-write",
+        action="store_true",
+        help=(
+            "Opt in to the git write path: create a branch, commit the approved "
+            "diff, push the branch, and open a PR with gh. Never main/master, "
+            "never forced; each step needs its own approval."
+        ),
+    )
+    parser.add_argument(
+        "--git-branch",
+        default=None,
+        help="Branch to create/commit/push (default: sid/<run_id>).",
+    )
+    parser.add_argument(
+        "--git-message",
+        default=None,
+        help="Commit message and PR body (default: the task text).",
+    )
+    parser.add_argument(
+        "--git-base",
+        default=None,
+        help="Pull-request base branch (default: main). The PR target is not a push.",
+    )
+    parser.add_argument(
+        "--no-pr",
+        action="store_true",
+        help="Push the branch but do not open a pull request.",
+    )
+    parser.add_argument(
+        "--approve",
+        action="store_true",
+        help=(
+            "Approve each pending step without prompting (diff apply and every "
+            "git-write step). Without it, a non-interactive run fails closed."
+        ),
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sid",
+        description="SID first-party local coding harness (v1) — drives SID's native loop.",
+    )
+    parser.add_argument("--version", action="version", version=f"sid-harness {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    setup = sub.add_parser(
+        "setup",
+        help="Verify your key with /v1/me, save it, and choose a default project dir.",
+    )
+    setup.add_argument("--api-key", default=None, help="Your SID key (env SID_API_KEY).")
+    setup.add_argument("--base-url", default=None, help="SID /v1 base URL (env SID_BASE_URL).")
+    setup.add_argument("--dir", default=None, help="Default project directory (default: current dir).")
+    setup.add_argument(
+        "--non-interactive",
+        action="store_true",
+        help="Never prompt; use flags, env, config, or the current directory.",
+    )
+    setup.add_argument("--json", action="store_true")
+
+    run = sub.add_parser("run", help="Run one bounded task against SID's native loop.")
+    run.add_argument("--task", required=True)
+    run.add_argument("--dir", default=None, help="Project directory (default: `sid setup`'s dir).")
+    _add_common_options(run)
+    _add_project_options(run)
+    _add_git_write_options(run)
+
+    tui = sub.add_parser("tui", help="Interactive terminal loop over the same engine.")
+    tui.add_argument("--dir", default=None, help="Project directory (default: `sid setup`'s dir).")
+    _add_common_options(tui)
+    _add_project_options(tui)
+    _add_git_write_options(tui)
+
+    status = sub.add_parser(
+        "status",
+        help="Show local git/worktree status for --dir (read-only, no model call).",
+    )
+    status.add_argument("--dir", default=None, help="Project directory (default: `sid setup`'s dir).")
+    status.add_argument("--diff", action="store_true", help="Also print `git diff`.")
+    status.add_argument("--json", action="store_true")
+
+    session = sub.add_parser(
+        "session",
+        help="Durable local sessions: start, resume, replay (approve-before-apply on --write).",
+    )
+    session_sub = session.add_subparsers(dest="session_command")
+
+    session_start = session_sub.add_parser("start", help="Start a durable session and run once.")
+    session_start.add_argument("--task", required=True)
+    session_start.add_argument("--dir", default=None, help="Project directory (default: `sid setup`'s dir).")
+    _add_common_options(session_start)
+    _add_session_options(session_start)
+
+    session_resume = session_sub.add_parser("resume", help="Continue an existing session.")
+    session_resume.add_argument("--session", required=True)
+    session_resume.add_argument("--task", default=None, help="New task (default: the session's task).")
+    session_resume.add_argument("--dir", default=None, help="Project directory (default: `sid setup`'s dir).")
+    _add_common_options(session_resume)
+    _add_session_options(session_resume)
+
+    session_replay = session_sub.add_parser("replay", help="Print a session's run receipts (no model call).")
+    session_replay.add_argument("--session", required=True)
+    session_replay.add_argument("--dir", default=None, help="Project directory (default: `sid setup`'s dir).")
+    session_replay.add_argument("--json", action="store_true")
+
+    tools = sub.add_parser(
+        "tools",
+        help="List the loop's tool contract (base + optional MCP servers).",
+    )
+    tools.add_argument("--mcp", action="append", default=None, metavar="CMD")
+    tools.add_argument("--json", action="store_true")
+
+    policy = sub.add_parser(
+        "policy",
+        help="Show the platform worktree/gate policy for --dir (read-only, no model call).",
+    )
+    policy.add_argument("--dir", default=None, help="Project directory (default: `sid setup`'s dir).")
+    policy.add_argument("--json", action="store_true")
+
+    selftest = sub.add_parser(
+        "selftest",
+        help="Drive one loop turn against a local stub endpoint and write a receipt.",
+    )
+    selftest.add_argument("--receipt", default=None)
+
+    bridge = sub.add_parser(
+        "bridge",
+        help="Run the localhost filesystem bridge so the Studio web UI can read --dir.",
+    )
+    _add_bridge_options(bridge, auto_open=False)
+
+    companion = sub.add_parser(
+        "companion",
+        help="Start the bridge and open the Studio with one-click pairing (read-only by default).",
+    )
+    _add_bridge_options(companion, auto_open=True)
+
+    lsp = sub.add_parser(
+        "lsp",
+        help="Run the SID language server on stdio; it feeds diagnostics into the loop (SUB-96).",
+    )
+    lsp.add_argument(
+        "--dir",
+        default=None,
+        help="Workspace root (default: the initialize request's root, else cwd).",
+    )
+
+    editor = sub.add_parser(
+        "editor",
+        help="Install the bundled VS Code extension (SUB-96).",
+    )
+    editor_sub = editor.add_subparsers(dest="editor_command")
+    editor_install = editor_sub.add_parser(
+        "install",
+        help="Copy the bundled VS Code extension into VS Code's extensions directory.",
+    )
+    editor_install.add_argument("--target-dir", default=None, help="Override the extensions directory.")
+    editor_install.add_argument("--force", action="store_true", help="Refresh an existing install.")
+    editor_install.add_argument("--json", action="store_true")
+
+    apply_cmd = sub.add_parser(
+        "apply",
+        help="Apply an approved run receipt's readback to --dir through the same write path.",
+    )
+    apply_cmd.add_argument("--dir", required=True)
+    apply_cmd.add_argument("--receipt", required=True)
+    apply_cmd.add_argument(
+        "--approve",
+        action="store_true",
+        help="Explicit human approval; without it nothing is written.",
+    )
+    apply_cmd.add_argument("--json", action="store_true")
+    return parser
+
+
+def _add_bridge_options(parser: argparse.ArgumentParser, *, auto_open: bool) -> None:
+    parser.add_argument("--dir", required=True)
+    parser.add_argument("--port", type=int, default=8787)
+    parser.add_argument("--token", default=None, help="Fixed token (default: generated per launch).")
+    parser.add_argument("--pair-code", default=None, help="Fixed pairing code (default: generated per launch).")
+    parser.add_argument("--pair-ttl", type=float, default=600)
+    parser.add_argument(
+        "--write",
+        action="store_true",
+        help="Make write mode available (default: read-only); the user still grants it explicitly in the Studio.",
+    )
+    parser.add_argument("--state-dir", default=None, help="Receipts/grant state directory (default: ~/.sid/bridge).")
+    parser.add_argument(
+        "--studio-url",
+        default=None,
+        help="Studio page that opens (companion default: https://app.superintelligencedog.com/studio.html).",
+    )
+    parser.add_argument(
+        "--allow-origin",
+        action="append",
+        default=None,
+        metavar="ORIGIN",
+        help="Add a trusted Studio origin (self-hosted); repeatable.",
+    )
+    parser.add_argument("--base-url", default=None, help="SID /v1 base URL used for runs (never taken from the browser).")
+    if auto_open:
+        parser.add_argument("--no-open", action="store_true", help="Do not open the browser (print the pair URL).")
+
+
+def _file_link(path: Path) -> str:
+    resolved = Path(path).resolve()
+    try:
+        return resolved.as_uri()
+    except ValueError:  # pragma: no cover - unusual non-file path
+        return str(resolved)
+
+
+def _render(outcome: RunOutcome, *, as_json: bool, quiet: bool) -> None:
+    receipt = outcome.receipt
+    if as_json:
+        print(json.dumps(receipt, indent=2, sort_keys=True, ensure_ascii=False))
+        return
+    if not quiet:
+        print(f"model: {receipt['model']}  steps: {receipt['steps']}  tool_calls: {receipt['tool_calls']}")
+        print(f"changed: {', '.join(receipt['changed']) or '(none)'}")
+        if receipt.get("context"):
+            print(f"context: {receipt['context'].get('chunks_used', 0)} chunk(s)")
+        if receipt.get("diff"):
+            print("\n--- diff ---")
+            print(receipt["diff"].rstrip("\n"))
+        print(f"\n{receipt['final_response']}")
+        if receipt.get("verify"):
+            print(f"\nverify: {receipt['verify'].get('verdict')}")
+        if receipt["tests_executed"]:
+            print(
+                f"tests_executed: true  backend: {receipt.get('test_backend')}  "
+                f"exit: {receipt.get('test_exit_code')}  passed: {receipt.get('test_passed')}"
+            )
+        else:
+            print(f"tests_executed: false  ({receipt.get('test', {}).get('detail')})")
+        git_write = receipt.get("git_write")
+        if git_write:
+            print(
+                f"git_write: {git_write.get('status')}  branch: {git_write.get('branch')}  "
+                f"commit: {git_write.get('commit')}  pr: {git_write.get('pr_url')}"
+            )
+            if git_write.get("reason"):
+                print(f"git_write detail: {git_write['reason']}")
+    print(f"receipt: {_file_link(outcome.receipt_path)}")
+
+
+def _make_client(args: argparse.Namespace) -> SIDClient:
+    return SIDClient(
+        base_url=getattr(args, "base_url", None),
+        api_key=getattr(args, "api_key", None),
+        routing_profile=getattr(args, "routing_profile", None),
+    )
+
+
+def _cmd_setup(args: argparse.Namespace) -> int:
+    """Verify the key against ``/v1/me``, then persist config + default dir."""
+    saved = config.load_config()
+    api_key = (
+        args.api_key
+        or os.environ.get("SID_API_KEY")
+        or (saved.get("api_key") if isinstance(saved.get("api_key"), str) else "")
+    )
+    if not api_key and not args.non_interactive and sys.stdin.isatty():
+        api_key = getpass.getpass("SID API key: ").strip()
+    if not api_key:
+        print(
+            "BLOCKED: no SID API key. Pass --api-key, set SID_API_KEY, or run "
+            "interactively.",
+            file=sys.stderr,
+        )
+        return 2
+
+    base_url = args.base_url or os.environ.get("SID_BASE_URL") or None
+    try:
+        client = SIDClient(base_url=base_url, api_key=api_key)
+        account = client.me()
+    except SIDClientError as exc:
+        print(f"BLOCKED: key verification failed: {exc}", file=sys.stderr)
+        return 2
+
+    default_dir = args.dir
+    if not default_dir:
+        existing = saved.get("default_dir")
+        default_dir = existing if isinstance(existing, str) and existing else None
+    if not default_dir and not args.non_interactive and sys.stdin.isatty():
+        answer = input(f"Default project directory [{Path.cwd()}]: ").strip()
+        default_dir = answer or str(Path.cwd())
+    if not default_dir:
+        default_dir = str(Path.cwd())
+    directory = Path(default_dir).expanduser().resolve()
+    if not directory.is_dir():
+        print(f"BLOCKED: default dir is not an existing directory: {directory}", file=sys.stderr)
+        return 2
+
+    merged = dict(saved)
+    merged.update(
+        {
+            "api_key": api_key,
+            "base_url": client.base_url,
+            "default_dir": str(directory),
+            "api_key_id": account.get("api_key_id"),
+            "plan": account.get("plan"),
+            "verified_at": datetime.now(timezone.utc).isoformat(),
+        }
+    )
+    path = config.save_config(merged)
+    payload = {
+        "ok": True,
+        "config": str(path),
+        "base_url": client.base_url,
+        "default_dir": str(directory),
+        "api_key_id": account.get("api_key_id"),
+        "plan": account.get("plan"),
+    }
+    if args.json:
+        print(json.dumps(payload, indent=2, sort_keys=True, ensure_ascii=False))
+        return 0
+    print(f"key verified: {account.get('name') or 'SID key'} (plan: {account.get('plan') or 'unknown'})")
+    print(f"saved: {path}")
+    print(f"default dir: {directory}")
+    print("next: sid run --task \"...\"")
+    return 0
+
+
+def _apply_default_dir(args: argparse.Namespace) -> bool:
+    if getattr(args, "dir", None):
+        return True
+    configured = config.get_default_dir()
+    if configured:
+        args.dir = configured
+        return True
+    print(
+        "BLOCKED: no --dir given and no default dir saved. "
+        "Run `sid setup --dir <path>` first.",
+        file=sys.stderr,
+    )
+    return False
+
+
+def _resolve_bounds(args: argparse.Namespace) -> SessionBounds:
+    return SessionBounds.resolve(config_path=getattr(args, "bounds_config", None))
+
+
+def _split_command(command: str) -> list[str]:
+    """Split an ``--mcp`` command line, Windows-path aware.
+
+    POSIX ``shlex.split`` eats backslashes, which corrupts a Windows executable
+    path (``C:\\Python\\python.exe``). On Windows, tokenize without POSIX rules
+    and strip surrounding quotes from each token.
+    """
+    command = (command or "").strip()
+    if not command:
+        return []
+    lexer = shlex.shlex(command, posix=(os.name != "nt"))
+    lexer.whitespace_split = True
+    lexer.commenters = ""
+    tokens = list(lexer)
+    if os.name == "nt":
+        tokens = [
+            token[1:-1]
+            if len(token) >= 2 and token[0] == token[-1] and token[0] in ("'", '"')
+            else token
+            for token in tokens
+        ]
+    return tokens
+
+
+def _approved_test_argv(args: argparse.Namespace) -> list[str] | None:
+    """The ``--test-cmd`` command as an argv LIST (never a shell string)."""
+    command = getattr(args, "test_cmd", None)
+    if not command:
+        return None
+    tokens = _split_command(command)
+    return tokens or None
+
+
+def _build_registry(args: argparse.Namespace):
+    """Return (registry, closers) for any --mcp servers; (None, []) when none."""
+    commands = getattr(args, "mcp", None)
+    if not commands:
+        return None, []
+    from .tools import MCPClient, StdioTransport, ToolRegistry, register_mcp_tools
+
+    registry = ToolRegistry()
+    closers = []
+    for command in commands:
+        parts = _split_command(command)
+        if not parts:
+            continue
+        mcp = MCPClient(StdioTransport(parts[0], parts[1:]))
+        mcp.initialize()
+        register_mcp_tools(registry, mcp)
+        closers.append(mcp)
+    return registry, closers
+
+
+def _git_write_approver(args: argparse.Namespace):
+    """One approval per git step; fail closed without a TTY and without --approve."""
+    explicit = bool(getattr(args, "approve", False))
+
+    def approve(step):
+        print(f"[git-write] {step.render()}", file=sys.stderr)
+        if explicit:
+            return True
+        if not sys.stdin.isatty():
+            print(
+                "BLOCKED: --git-write needs an interactive approval (or --approve) "
+                "and stdin is not a terminal; no git step was taken.",
+                file=sys.stderr,
+            )
+            return False
+        print(f"Approve {step.name}? [y/N] ", end="", file=sys.stderr, flush=True)
+        try:
+            answer = input()
+        except (EOFError, KeyboardInterrupt):
+            return False
+        return answer.strip().lower() in ("y", "yes")
+
+    return approve
+
+
+def _run_common(args: argparse.Namespace, task: str, *, reporter) -> RunOutcome:
+    client = _make_client(args)
+    bounds = _resolve_bounds(args)
+    registry, closers = _build_registry(args)
+    git_write = bool(getattr(args, "git_write", False))
+    try:
+        return execute_run(
+            task=task,
+            directory=args.dir,
+            client=client,
+            model=args.model,
+            criteria=args.criteria,
+            out_of_scope=args.out_of_scope,
+            test_argv=_approved_test_argv(args),
+            max_tokens=args.max_tokens,
+            reasoning_effort=args.reasoning_effort,
+            verify=args.verify,
+            write=getattr(args, "write", False),
+            allow_delete=getattr(args, "allow_delete", False),
+            git_write=git_write,
+            git_branch=getattr(args, "git_branch", None),
+            git_message=getattr(args, "git_message", None),
+            git_base=getattr(args, "git_base", None),
+            git_pr=not getattr(args, "no_pr", False),
+            git_approve=_git_write_approver(args) if git_write else None,
+            receipt_path=args.receipt,
+            reporter=reporter,
+            context=getattr(args, "context", False),
+            context_k=getattr(args, "context_k", 4),
+            registry=registry,
+            bounds=bounds,
+            diagnostics=getattr(args, "diagnostics", True),
+            skills=getattr(args, "skills", None),
+            skills_root=getattr(args, "skills_root", None),
+            subagents=getattr(args, "subagent", None),
+            plan=bool(getattr(args, "plan", False)),
+            todos=getattr(args, "todo", None),
+        )
+    finally:
+        for mcp in closers:
+            mcp.close()
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    reporter = (lambda _message: None) if args.quiet else (lambda message: print(message, file=sys.stderr))
+    try:
+        outcome = _run_common(args, args.task, reporter=reporter)
+    except (SIDClientError, WorkspaceError, LocalWorkspaceError, BoundsError, RunError) as exc:
+        print(f"BLOCKED: {exc}", file=sys.stderr)
+        return 2
+    _render(outcome, as_json=args.json, quiet=args.quiet)
+    return 0
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    try:
+        workspace = LocalWorkspace.open(args.dir)
+    except LocalWorkspaceError as exc:
+        print(f"BLOCKED: {exc}", file=sys.stderr)
+        return 2
+    info = workspace.git
+    status = workspace.status()
+    if args.json:
+        payload = {"git": info.as_dict(), "status": status}
+        if args.diff:
+            payload["diff"] = workspace.diff()
+        print(json.dumps(payload, indent=2, sort_keys=True, ensure_ascii=False))
+        return 0
+    print(f"dir: {workspace.root}")
+    if not info.is_repo:
+        print("git: not a repository")
+        return 0
+    kind = "worktree" if info.is_worktree else "checkout"
+    print(f"git: {kind}  branch: {info.branch or '(detached)'}  head: {(info.head or '')[:12]}")
+    print(f"root: {info.root}")
+    if status:
+        print(f"status ({len(status)}):")
+        for line in status:
+            print(f"  {line}")
+    else:
+        print("status: clean")
+    if args.diff:
+        print("\n--- diff ---")
+        print(workspace.diff().rstrip("\n"))
+    return 0
+
+
+def _cmd_tools(args: argparse.Namespace) -> int:
+    from .tools import MCPClient, StdioTransport, ToolRegistry, register_mcp_tools
+    from .tools.registry import BASE_TOOL_NAMES
+
+    registry = ToolRegistry()
+    closers = []
+    try:
+        for command in args.mcp or []:
+            parts = _split_command(command)
+            if not parts:
+                continue
+            mcp = MCPClient(StdioTransport(parts[0], parts[1:]))
+            mcp.initialize()
+            register_mcp_tools(registry, mcp)
+            closers.append(mcp)
+    except Exception as exc:
+        print(f"BLOCKED: {exc}", file=sys.stderr)
+        return 2
+    finally:
+        for mcp in closers:
+            mcp.close()
+
+    payload = {
+        "base": list(BASE_TOOL_NAMES),
+        "extensions": registry.extension_names(),
+        "all": registry.names(),
+    }
+    if args.json:
+        print(json.dumps(payload, indent=2, sort_keys=True, ensure_ascii=False))
+        return 0
+    print(f"base tools ({len(payload['base'])}): {', '.join(payload['base'])}")
+    if payload["extensions"]:
+        print(f"extension tools ({len(payload['extensions'])}): {', '.join(payload['extensions'])}")
+    else:
+        print("extension tools: none (pass --mcp '<command>' to add a server's tools)")
+    return 0
+
+
+def _cmd_policy(args: argparse.Namespace) -> int:
+    from .policy import policy_report
+
+    report = policy_report(args.dir)
+    if args.json:
+        print(json.dumps(report, indent=2, sort_keys=True, ensure_ascii=False))
+        return 0
+    worktree = report["worktree"]
+    gates = report["gates"]
+    print(f"dir: {worktree['directory']}")
+    if not worktree["is_repo"]:
+        print("policy: not a git repository (no platform policy applies)")
+        return 0
+    kind = "MAIN checkout (integration-only)" if worktree["is_main_checkout"] else "session worktree"
+    print(f"worktree: {kind}  branch: {worktree['branch'] or '(detached)'}")
+    print(f"reason: {worktree['reason']}")
+    print(f"gates on disk: {len(gates['gate_files'])}  wired: {len(gates['wired_gates'])}")
+    if gates["missing_wired"]:
+        print(f"missing wired gates: {', '.join(gates['missing_wired'])}")
+    return 0
+
+
+def _session_approver(explicit: bool):
+    def approve(proposal):
+        print(proposal.render())
+        if explicit:
+            return True
+        if not sys.stdin.isatty():
+            print(
+                "BLOCKED: --write without --approve and stdin is not a terminal; "
+                "changes were not applied.",
+                file=sys.stderr,
+            )
+            return False
+        answer = input("Apply these changes to the working tree? [y/N] ").strip().lower()
+        return answer in ("y", "yes")
+
+    return approve
+
+
+def _render_session(outcome, *, as_json: bool, quiet: bool) -> None:
+    receipt = outcome.receipt
+    if as_json:
+        print(json.dumps(receipt, indent=2, sort_keys=True, ensure_ascii=False))
+        return
+    if not quiet:
+        print(f"session: {receipt['session']['session_id']}  status: {receipt['status']}")
+        print(f"model: {receipt['model']}  steps: {receipt['steps']}  tool_calls: {receipt['tool_calls']}")
+        print(f"changed: {', '.join(receipt['changed']) or '(none)'}")
+        decision = "approved" if outcome.review.approved else "refused"
+        print(f"apply: {decision} ({outcome.review.reason})")
+        print(f"\n{receipt['final_response']}")
+    print(f"receipt: {_file_link(outcome.receipt_path)}")
+
+
+def _cmd_session(args: argparse.Namespace) -> int:
+    command = getattr(args, "session_command", None)
+    if command is None:
+        print("BLOCKED: choose a session subcommand: start | resume | replay", file=sys.stderr)
+        return 2
+    try:
+        if command == "replay":
+            session = Session.load(args.dir, args.session)
+            runs = session.replay()
+            if args.json:
+                print(json.dumps(runs, indent=2, sort_keys=True, ensure_ascii=False))
+            else:
+                print(
+                    f"session: {session.session_id}  status: {session.record['status']}  "
+                    f"runs: {len(runs)}"
+                )
+                for index, run in enumerate(runs):
+                    changed = ", ".join(run.get("changed") or []) or "(none)"
+                    print(f"  [{index}] {run['run_id']}  status={run.get('status')}  changed={changed}")
+            return 0
+
+        bounds = _resolve_bounds(args)
+        client = _make_client(args)
+        if command == "start":
+            session = Session.start(args.dir, task=args.task, bounds=bounds)
+            task = None
+        else:
+            session = Session.resume(args.dir, args.session, bounds=bounds)
+            task = args.task
+        reporter = (
+            (lambda _message: None)
+            if args.quiet
+            else (lambda message: print(message, file=sys.stderr))
+        )
+        outcome = session.run(
+            client=client,
+            task=task,
+            criteria=args.criteria,
+            out_of_scope=args.out_of_scope,
+            test_argv=_approved_test_argv(args),
+            model=args.model,
+            max_tokens=args.max_tokens,
+            reasoning_effort=args.reasoning_effort,
+            verify=args.verify,
+            write=args.write,
+            allow_delete=getattr(args, "allow_delete", False),
+            approve=_session_approver(args.approve) if args.write else None,
+            reporter=reporter,
+            diagnostics=getattr(args, "diagnostics", True),
+        )
+    except (
+        SIDClientError,
+        WorkspaceError,
+        LocalWorkspaceError,
+        SessionError,
+        SessionStoreError,
+        BoundsError,
+    ) as exc:
+        print(f"BLOCKED: {exc}", file=sys.stderr)
+        return 2
+    _render_session(outcome, as_json=args.json, quiet=args.quiet)
+    return 0
+
+
+def _cmd_editor(args: argparse.Namespace) -> int:
+    if getattr(args, "editor_command", None) != "install":
+        print("BLOCKED: choose an editor subcommand: install", file=sys.stderr)
+        return 2
+    from .editor import EditorError, install
+
+    try:
+        result = install(args.target_dir, force=args.force)
+    except EditorError as exc:
+        print(f"BLOCKED: {exc}", file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps(result, indent=2, sort_keys=True, ensure_ascii=False))
+        return 0
+    print(f"extension {result['status']}: {result['extension']}")
+    print("reload VS Code to activate the SID commands.")
+    return 0
+
+
+def _cmd_apply(args: argparse.Namespace) -> int:
+    from .editor import EditorError, apply_receipt
+
+    try:
+        result = apply_receipt(args.dir, args.receipt, approve=args.approve)
+    except (EditorError, LocalWorkspaceError) as exc:
+        print(f"BLOCKED: {exc}", file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps(result, indent=2, sort_keys=True, ensure_ascii=False))
+    elif result["status"] == "applied":
+        print(f"applied: {', '.join(result['applied'])}")
+    elif result["status"] == "nothing-to-apply":
+        print("nothing to apply: the receipt carries no changed files")
+    else:
+        print(f"{result['status']}: no files written")
+    return 2 if result["status"] in ("approval-required", "refused-by-policy") else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv if argv is not None else sys.argv[1:])
+    if args.command == "setup":
+        return _cmd_setup(args)
+    if args.command in {"run", "tui", "status", "session", "policy"} and not _apply_default_dir(args):
+        return 2
+    if args.command == "run":
+        return _cmd_run(args)
+    if args.command == "tui":
+        from .tui import run_tui
+
+        return run_tui(args)
+    if args.command == "status":
+        return _cmd_status(args)
+    if args.command == "session":
+        return _cmd_session(args)
+    if args.command == "tools":
+        return _cmd_tools(args)
+    if args.command == "policy":
+        return _cmd_policy(args)
+    if args.command == "selftest":
+        from .selftest import run_selftest
+
+        try:
+            outcome = run_selftest(receipt_path=args.receipt)
+        except Exception as exc:  # selftest is a diagnostic; report and fail closed
+            print(f"selftest FAILED: {exc}", file=sys.stderr)
+            return 1
+        print(f"selftest OK — receipt: {_file_link(outcome.receipt_path)}")
+        return 0
+    if args.command == "bridge":
+        from .bridge import ALLOWED_ORIGINS, main as bridge_main
+
+        argv = ["--dir", args.dir, "--port", str(args.port), "--pair-ttl", str(args.pair_ttl)]
+        if args.token:
+            argv += ["--token", args.token]
+        if args.pair_code:
+            argv += ["--pair-code", args.pair_code]
+        if args.write:
+            argv.append("--write")
+        if args.state_dir:
+            argv += ["--state-dir", args.state_dir]
+        if args.studio_url:
+            argv += ["--studio-url", args.studio_url]
+        else:
+            argv += ["--studio-url", "https://app.superintelligencedog.com/studio.html"]
+        for origin in args.allow_origin or []:
+            if origin not in ALLOWED_ORIGINS:
+                argv += ["--allow-origin", origin]
+        if args.base_url:
+            argv += ["--base-url", args.base_url]
+        return bridge_main(argv)
+    if args.command == "companion":
+        from .companion import DEFAULT_STUDIO_URL, main as companion_main
+
+        argv = ["--dir", args.dir, "--port", str(args.port), "--pair-ttl", str(args.pair_ttl)]
+        argv += ["--studio-url", args.studio_url or DEFAULT_STUDIO_URL]
+        if args.token:
+            argv += ["--token", args.token]
+        if args.pair_code:
+            argv += ["--pair-code", args.pair_code]
+        if args.write:
+            argv.append("--write")
+        if args.state_dir:
+            argv += ["--state-dir", args.state_dir]
+        if args.no_open:
+            argv.append("--no-open")
+        for origin in args.allow_origin or []:
+            argv += ["--allow-origin", origin]
+        if args.base_url:
+            argv += ["--base-url", args.base_url]
+        return companion_main(argv)
+    if args.command == "lsp":
+        from .lsp import serve_stdio
+
+        return serve_stdio(args.dir)
+    if args.command == "editor":
+        return _cmd_editor(args)
+    if args.command == "apply":
+        return _cmd_apply(args)
+    parser.print_help()
+    return 2