agentwire-dev 1.46.0__tar.gz → 1.48.0__tar.gz

agentwire_dev-1.48.0/.claude/commands/handoff.md

@@ -0,0 +1,142 @@
+---
+description: Distill this conversation into a shareable handoff bundle (ai-handoff.md + show-the-story.html)
+---
+
+# /handoff
+
+You are about to compile this conversation into a **shareable handoff bundle**. The output is two artifacts:
+
+1. **`ai-handoff.md`** — XML-tagged markdown a teammate can paste into another LLM (Opus 4.7) to roughly continue the conversation.
+2. **`show-the-story.html`** — single-file presentation a human can open in a browser.
+
+You are uniquely positioned to do this well: you already have full conversation context. Don't ask the user clarifying questions unless something is genuinely ambiguous — distill what you know.
+
+## Workflow
+
+### 1. Initialize the bundle
+
+Call the MCP tool to create the bundle dir and pre-fill the template with git state and the CLAUDE.md/rules/memory chain:
+
+```
+mcp__agentwire__handoff_init(title="<short slug>")
+```
+
+The tool returns a `bundle_dir` and an `ai_handoff_path`. The pre-filled template at `ai_handoff_path` already has:
+- `<metadata>` populated with cwd, branch, commit, repo url
+- `<instructions>` populated with the full CLAUDE.md chain (verbatim)
+- `<project_state>` populated with `git status`, `git log`, and uncommitted diff
+
+You **must not touch** the `<instructions>` section unless redacting something sensitive — it's what makes the bundle portable across machines.
+
+### 2. Read the pre-filled template
+
+Use Read on `ai_handoff_path` to see exactly what got pre-filled.
+
+### 3. Fill in the rest
+
+Use Write (or Edit) on `ai_handoff_path` to replace every `{{ ... }}` placeholder with real content. Specifically:
+
+#### `<title>`
+One short line summarizing the session — what it was about, not what was decided. Roughly 4-8 words.
+
+#### `<metadata>` extras
+Fill `started_at` / `ended_at` if you can estimate them, `user_identity` (if mentioned), and `mcp_servers` (the ones actually used in this conversation).
+
+#### `<environment>`
+What the receiver can't see from `cwd` alone. Active panes, channels (Slack/Discord/email), scheduler state if relevant. If nothing notable, write a one-line "no special environment" note.
+
+#### `<conversation_summary>`
+This is the most load-bearing section. Be dense and structured.
+
+- `<goal>` — one sentence: what this session set out to do.
+- `<tldr>` — one paragraph the receiver reads first. Convey decisions made, current state, and what's next.
+- `<decisions>` — every meaningful decision. For each: `<title>` (short name), `<rationale>` (why), `<alternatives>` (what was considered and not picked). If a user message confirmed a choice, that's a decision.
+- `<dead_ends>` — things tried and rejected. Critical: this saves the receiver from retracing your steps.
+- `<open_threads>` — what's unresolved. Be specific. "tests/handoff/test_parser.py needs malformed-input cases" beats "tests pending".
+- `<stats>` — turns, files_touched, tools_used, duration_minutes. Estimates are fine.
+
+#### `<journey>`
+3-7 narrative beats — the *story* of the session, not the transcript. For each beat:
+- `<beat title="...">` — short headline.
+- `<quote>...</quote>` — optional verbatim line from the conversation that captured the turn (user or assistant).
+- `<what_happened>...</what_happened>` — what actually changed.
+
+This drives the visual presentation in show-the-story.html. Aim for memorable beats: turning points, surprises, decisions, blockers.
+
+#### `<recent_turns>`
+The last ~10-20 turns, **filtered**:
+- Drop tool noise (file reads, searches) unless the result drove a decision.
+- Keep all user turns verbatim — they're the signal of intent.
+- Keep assistant turns that made decisions, asked questions, or summarized.
+- Use markdown: `**user:**` / `**assistant:**` labels, blockquotes for quoted content.
+
+#### `<handoff>`
+Direct instructions to the next agent.
+- `<one_sentence>` — what they should do first.
+- `<resume_at>` — concrete file path / TODO id / step number.
+- `<caveats>` — permission boundaries ("don't push", "don't edit X without asking"), env-specific notes, anything the receiver could trip on.
+
+#### `<theme>`
+Pick a palette and vibe that matches the **emotional tone** of the session. A debugging crisis at 2am gets different colors than a clean greenfield design pass. Be honest in `mood`. The shape:
+
+```json
+{
+  "name": "short-slug",
+  "mood": "honest read of the session's emotional tone — 1 short sentence",
+  "palette": {
+    "bg": "#hex",
+    "surface": "#hex",
+    "fg": "#hex",
+    "muted": "#hex",
+    "accent": "#hex",
+    "accent_2": "#hex",
+    "border": "#hex"
+  },
+  "fonts": {
+    "heading": "css font-family stack",
+    "body": "css font-family stack"
+  },
+  "motion": "subtle"
+}
+```
+
+Tips:
+- Dark backgrounds work better in this template — `bg` should be deep.
+- `accent` is the dominant interactive color (tabs, headlines, highlights). Pick something that signals the mood.
+- `accent_2` is for warnings / dead-ends. Often a warm color.
+- Keep `fonts.heading` monospace-leaning, `fonts.body` sans-serif. Override only if the mood justifies it.
+- `motion`: `"subtle"` (default), `"playful"` (longer transitions), `"none"` (instant).
+
+### 4. Render the HTML
+
+After writing `ai-handoff.md`, render the HTML:
+
+```
+mcp__agentwire__handoff_render(bundle_dir="<from step 1>", story=true)
+```
+
+If render fails, the parser will tell you which tag is missing or malformed — fix and re-run.
+
+### 5. Report
+
+Give the user:
+- The bundle dir path
+- A one-sentence summary of what you produced
+- An explicit pointer to open `show-the-story.html` in a browser
+
+Don't paste the full ai-handoff.md back — it's long. Just confirm it's saved and mention the highlights you captured (number of decisions, dead ends, journey beats, theme name/mood).
+
+## Quality bar
+
+The receiver's first impression is everything. A great handoff:
+- Reads cold — the receiver doesn't need to be in this folder.
+- Is honest about dead ends. Hiding what didn't work wastes the receiver's tokens.
+- Names specific files and line numbers, not vague pointers.
+- Picks a theme that captures the session's actual feel. Don't pick "professional blue" for a chaotic debug session.
+
+## Don't
+
+- Don't ask the user "should I include X?" — make the call yourself.
+- Don't paste the entire conversation as `<recent_turns>` — filter aggressively.
+- Don't over-design the theme. The structure is fixed; you're picking colors and vibes, not a layout.
+- Don't edit `<instructions>` (the CLAUDE.md chain) unless redacting secrets.

{agentwire_dev-1.46.0 → agentwire_dev-1.48.0}/.gitignore

@@ -57,3 +57,6 @@ htmlcov/
 
 # pytest-textual-snapshot diff page (regenerated each run)
 snapshot_report.html
+
+# Node
+node_modules/

agentwire_dev-1.48.0/AGENTS.md

@@ -0,0 +1,5 @@
+# AgentWire
+
+Voice interface for AI coding agents. Push-to-talk from any device to tmux sessions running Claude Code.
+
+Agent instructions, conventions, and architecture live in [CLAUDE.md](CLAUDE.md).

{agentwire_dev-1.46.0 → agentwire_dev-1.48.0}/CONTRIBUTING.md

@@ -144,7 +144,7 @@ def validate_config(config: Config) -> tuple[list[ConfigError], list[ConfigWarni
 
 ## CLI First
 
-All session/machine logic lives in CLI commands (`__main__.py`). The web portal is a thin wrapper that:
+All session/machine logic lives in the CLI. The command tree is split per-domain (#495): shared helpers (machine config, SSH, JSON output, session resolution, etc.) live in `core.py`; each command group lives in its own `agentwire/<domain>_cli.py` exposing a `register_<domain>_parser(subparsers)` registrar, and `build_parser()` imports them and runs the `_REGISTRARS` loop. `__main__.py` is just the entry point. Adding a command means writing a new `*_cli.py` + appending its registrar, not editing a god-file. The web portal is a thin wrapper that:
 
 1. Calls CLI via `run_agentwire_cmd(["command", "args"])`
 2. Parses JSON output (`--json` flag)
@@ -159,7 +159,9 @@ When adding new functionality:
 
 ```
 agentwire/
-├── __main__.py      # CLI commands (entry point)
+├── __main__.py      # CLI entry point (imports + runs the registrar loop)
+├── core.py          # Shared CLI helpers (machine config, SSH, JSON, session resolution)
+├── *_cli.py         # Per-domain command groups, each with a register_<domain>_parser()
 ├── server.py        # WebSocket server
 ├── config.py        # Configuration dataclasses
 ├── errors.py        # Structured error classes

{agentwire_dev-1.46.0 → agentwire_dev-1.48.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentwire-dev
-Version: 1.46.0
+Version: 1.48.0
 Summary: Multi-session voice web interface for AI coding agents
 Project-URL: Homepage, https://agentwire.dev
 Project-URL: Repository, https://github.com/dotdevdotdev/agentwire-dev
@@ -256,7 +256,6 @@ Requires-Dist: fastapi>=0.104.0; extra == 'tts'
 Requires-Dist: faster-whisper>=1.0.0; extra == 'tts'
 Requires-Dist: pydantic>=2.0.0; extra == 'tts'
 Requires-Dist: python-multipart>=0.0.6; extra == 'tts'
-Requires-Dist: runpod>=1.6.0; extra == 'tts'
 Requires-Dist: torch>=2.0.0; extra == 'tts'
 Requires-Dist: torchaudio>=2.0.0; extra == 'tts'
 Requires-Dist: uvicorn>=0.24.0; extra == 'tts'
@@ -295,9 +294,9 @@ structurally can't match:
   the machine.
 - **Voice-native, not voice-bolted-on.** Push-to-talk in, **neural TTS out on plain
   CPU** (Kokoro, no GPU). Want your agents to talk back in a **cloned voice**? Run a
-  self-hosted GPU shim (Chatterbox / Qwen / Zonos) — same machine, still your keys.
+  self-hosted GPU shim (Chatterbox / Zonos) — same machine, still your keys.
 - **Built to orchestrate _many_ agents, not watch one.** Council (multi-soul
-  deliberation), an overnight scheduler, briefing mode, and worktree-parallel
+  deliberation), a recurring scheduler, briefing mode, and worktree-parallel
   workers — tmux- and Claude-Code-native from the ground up.
 
 > **Use the official app to watch one session; use AgentWire to orchestrate many,
@@ -388,7 +387,7 @@ pip install agentwire-dev
 | **Voice Control** | Push-to-talk from any device on your network |
 | **Neural Voice + Cloning** | Kokoro neural TTS on CPU out of the box; voice cloning via a self-hosted GPU shim |
 | **Council** | Fan a prompt to multiple "soul" sessions (brain, conscience, critic…), synthesize with attribution |
-| **Scheduler** | Overnight / recurring autonomous tasks with gates, priorities, and usage-limit recovery |
+| **Scheduler** | Recurring autonomous tasks with gates, priorities, and usage-limit recovery |
 | **Briefing Mode** | A terse human-facing anchor fans out verbose worktree correspondents, then briefs you on cue |
 | **Multi-Session** | Run multiple agents on different projects simultaneously |
 | **Git Worktrees** | Same project, multiple branches, parallel agents |
@@ -474,7 +473,7 @@ Two tiers, both sides:
 # ~/.agentwire/config.yaml
 tts:
   backend: "custom"
-  url: "http://localhost:8100"     # agentwire tts start (kokoro CPU / chatterbox GPU / qwen / zonos)
+  url: "http://localhost:8100"     # agentwire tts start (kokoro CPU / chatterbox GPU / zonos)
   options:
     backend: kokoro
 stt:

{agentwire_dev-1.46.0 → agentwire_dev-1.48.0}/README.md

@@ -31,9 +31,9 @@ structurally can't match:
   the machine.
 - **Voice-native, not voice-bolted-on.** Push-to-talk in, **neural TTS out on plain
   CPU** (Kokoro, no GPU). Want your agents to talk back in a **cloned voice**? Run a
-  self-hosted GPU shim (Chatterbox / Qwen / Zonos) — same machine, still your keys.
+  self-hosted GPU shim (Chatterbox / Zonos) — same machine, still your keys.
 - **Built to orchestrate _many_ agents, not watch one.** Council (multi-soul
-  deliberation), an overnight scheduler, briefing mode, and worktree-parallel
+  deliberation), a recurring scheduler, briefing mode, and worktree-parallel
   workers — tmux- and Claude-Code-native from the ground up.
 
 > **Use the official app to watch one session; use AgentWire to orchestrate many,
@@ -124,7 +124,7 @@ pip install agentwire-dev
 | **Voice Control** | Push-to-talk from any device on your network |
 | **Neural Voice + Cloning** | Kokoro neural TTS on CPU out of the box; voice cloning via a self-hosted GPU shim |
 | **Council** | Fan a prompt to multiple "soul" sessions (brain, conscience, critic…), synthesize with attribution |
-| **Scheduler** | Overnight / recurring autonomous tasks with gates, priorities, and usage-limit recovery |
+| **Scheduler** | Recurring autonomous tasks with gates, priorities, and usage-limit recovery |
 | **Briefing Mode** | A terse human-facing anchor fans out verbose worktree correspondents, then briefs you on cue |
 | **Multi-Session** | Run multiple agents on different projects simultaneously |
 | **Git Worktrees** | Same project, multiple branches, parallel agents |
@@ -210,7 +210,7 @@ Two tiers, both sides:
 # ~/.agentwire/config.yaml
 tts:
   backend: "custom"
-  url: "http://localhost:8100"     # agentwire tts start (kokoro CPU / chatterbox GPU / qwen / zonos)
+  url: "http://localhost:8100"     # agentwire tts start (kokoro CPU / chatterbox GPU / zonos)
   options:
     backend: kokoro
 stt:

{agentwire_dev-1.46.0 → agentwire_dev-1.48.0}/RELEASING.md

@@ -34,10 +34,13 @@ unzip -l dist/agentwire_dev-{VERSION}-py3-none-any.whl | grep -E "templates/|sta
 
 ### 4. Publish to PyPI
 
-The `PYPI_TOKEN` lives in `~/.agentwire/.env`. Pass it explicitly:
+The `PYPI_TOKEN` lives in `~/.agentwire/.env`. Don't `source` the file — it can
+contain unquoted `&` in other values (e.g. a URL with query params), which makes
+the shell hit a parse error before `uv publish` ever runs. Grep the token out
+directly:
 
 ```bash
-source ~/.agentwire/.env && uv publish --token "$PYPI_TOKEN" dist/agentwire_dev-{VERSION}*
+uv publish --token "$(grep '^PYPI_TOKEN=' ~/.agentwire/.env | cut -d= -f2-)" dist/agentwire_dev-{VERSION}*
 ```
 
 ### 5. Create GitHub release

{agentwire_dev-1.46.0 → agentwire_dev-1.48.0}/agentwire/__init__.py

@@ -1,3 +1,3 @@
 """AgentWire - Multi-session voice web interface for AI coding agents."""
 
-__version__ = "1.46.0"
+__version__ = "1.48.0"

agentwire_dev-1.48.0/agentwire/__main__.py

@@ -0,0 +1,391 @@
+"""CLI entry point for AgentWire."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+# Load .env files (project first, then global config)
+load_dotenv()  # .env in current directory
+load_dotenv(Path.home() / ".agentwire" / ".env")  # Global config
+
+from . import (  # noqa: E402  # must follow load_dotenv() above
+    __version__,
+)
+from .core import (  # noqa: E402,F401  # E402: must follow load_dotenv(); F401: re-exported moved helpers
+    _UNATTENDED_ENV_KEYS,
+    CONFIG_DIR,
+    KIND_DEFAULT_POSTURE,
+    AgentCommand,
+    _add_posture_harness_flags,
+    _build_tmux_env_flags,
+    _build_tmux_env_flags_shell,
+    _check_portal_health,
+    _check_tmux_installed,
+    _default_portal_url,
+    _display_parent,
+    _get_agentwire_path,
+    _get_all_machines,
+    _get_machine_config,
+    _get_portal_url,
+    _get_session_project_path,
+    _git_behind_origin,
+    _install_global_tmux_hooks,
+    _notify_portal_sessions_changed,
+    _output_json,
+    _output_result,
+    _parse_session_target,
+    _portal_auth_headers,
+    _post_desktop_notification,
+    _record_session_creator,
+    _resolve_session_type_from_args,
+    _run_remote,
+    _set_session_name_env,
+    _start_portal_local,
+    _tmux_global_option,
+    _with_unattended_env,
+    build_agent_command,
+    check_pip_environment,
+    check_python_version,
+    format_relative_time,
+    generate_certs,
+    get_kokoro_session_name,
+    get_portal_session_name,
+    get_source_dir,
+    get_stt_session_name,
+    get_tts_session_name,
+    inject_session_env,
+    load_config,
+    load_session_metadata,
+    parse_env_args,
+    store_session_metadata,
+    tmux_session_exists,
+    tmux_session_has_agent,
+    wait_for_shell_prompt,
+)
+
+
+class VersionAction(argparse.Action):
+    """Custom version action that checks Python version and pip environment."""
+
+    def __init__(self, option_strings, dest=argparse.SUPPRESS, default=argparse.SUPPRESS, help=None):
+        super().__init__(option_strings, dest=dest, default=default, nargs=0, help=help)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        # Print version
+        print(f"agentwire {__version__}")
+        print(f"Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")
+
+        # Check version compatibility
+        version_ok = check_python_version()
+        env_ok = check_pip_environment()
+
+        if version_ok and env_ok:
+            print("\n✓ System is ready for AgentWire")
+        else:
+            print("\n⚠️  Please resolve the issues above before installing/running AgentWire")
+
+        parser.exit()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level argparse parser with every registered subcommand.
+
+    Extracted from ``main()`` so the parser tree can be constructed without
+    dispatching, which the CLI smoke tests rely on to enumerate subcommands
+    and invoke their ``--help`` (see ``tests/unit/test_cli_smoke.py``).
+    """
+    parser = argparse.ArgumentParser(
+        prog="agentwire",
+        description="Multi-session voice web interface for AI coding agents.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Command Categories:
+  Getting Started:
+    init             Interactive setup wizard
+    portal           Manage the web portal
+    new              Create a new Claude Code session
+    say              Speak text via TTS
+
+  Sessions:
+    list             List panes or sessions
+    info             Get session information
+    kill             Kill a session or pane
+    spawn            Spawn a worker pane in current session
+    worktree         Create a git worktree + session
+    send             Send prompt to a session or pane
+    output           Read session or pane output
+
+  Voice:
+    listen           Voice input recording
+    voiceclone       Record and upload voice clones
+    tts              Manage TTS server
+    stt              Manage STT server
+
+  Diagnostics:
+    doctor           Auto-diagnose and fix common issues
+    network          Network diagnostics and status
+    safety           Damage control security commands
+    hooks            Manage agentwire hook files
+
+  Advanced:
+    council          Multi-soul council operations
+    scheduler        Manage the task scheduler
+    ensure           Run named task with reliable session management
+    limits           Usage-limit recovery management
+"""
+    )
+    parser.add_argument(
+        "--version",
+        action=VersionAction,
+        help="Show version and check system compatibility",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # === quo command ===
+    from agentwire.channels.quo import cmd_quo
+    quo_parser = subparsers.add_parser("quo", help="Send SMS via Quo (OpenPhone)")
+    quo_parser.add_argument("--body", "-b", type=str, help="Message body (or pipe via stdin)")
+    quo_parser.add_argument("--to", type=str, help="Recipient phone number (+E.164 format)")
+    quo_parser.add_argument("-q", "--quiet", action="store_true", help="Suppress success output")
+    quo_parser.set_defaults(func=cmd_quo)
+
+    # === email command ===
+    from agentwire.channels.email import cmd_email
+    email_parser = subparsers.add_parser("email", help="Send branded email notification via Resend")
+    email_parser.add_argument(
+        "--to", action="append", default=None,
+        help="Recipient email. Repeat or pass comma-separated for multiple recipients (default: from config).",
+    )
+    email_parser.add_argument("--subject", "-s", type=str, help="Email subject")
+    email_parser.add_argument("--body", "-b", type=str, help="Email body - markdown supported (or pipe via stdin)")
+    email_parser.add_argument("--attach", "-a", type=str, action="append", help="Attach file (can use multiple times)")
+    email_parser.add_argument("--plain", action="store_true", help="Send plain text only (no HTML template)")
+    email_parser.add_argument("-q", "--quiet", action="store_true", help="Suppress success output")
+    email_parser.set_defaults(func=cmd_email)
+
+    # === fetch command ===
+    from agentwire.fetch import cmd_fetch
+    fetch_parser = subparsers.add_parser(
+        "fetch",
+        help="Fetch a URL via Jina Reader — handles JS-rendered pages, returns clean markdown.",
+    )
+    fetch_parser.add_argument("url", help="URL to fetch")
+    fetch_parser.add_argument(
+        "--limit", "-l", type=int, default=8000,
+        help="Max characters to return (default: 8000, 0 = no limit)",
+    )
+    fetch_parser.set_defaults(func=cmd_fetch)
+
+    # === Extracted command groups (each registrar owns its own subparser) ===
+    # Phase 1 of #495 appends one entry here per extracted domain.
+    #   - limits: usage-limit recovery (detect dialog, park, auto-resume)
+    #   - diff:   structured git diff for the mobile Review window
+    #   - prompts: prompt routing (rides the limits watchdog)
+    #   - msg:    polite agent-to-agent inbox (rides the watchdog)
+    from . import diff_cli, limits_cli, msg_cli, pane_cli, prompts_cli, send_cli  # noqa: I001  # session_cli kept on its own line below to minimize Phase 1 #495 merge conflicts
+    from . import session_cli
+    from . import channels_cli, portal_cli, tts_cli
+    from . import scheduler_cli, ensure_cli
+    from . import doctor_cli, history_cli, machine_cli, safety_cli
+    from . import handoff_cli, hooks_cli, mcp_cli, roles_cli, tunnels_cli
+    from . import notify_cli, push_cli, repo_cli, system_cli, wiki_cli
+    from .council import cli as council_cli
+
+    _REGISTRARS = [  # noqa: N806  # registry constant; Phase 1 of #495 appends here
+        diff_cli.register_diff_parser,
+        prompts_cli.register_prompts_parser,
+        msg_cli.register_msg_parser,
+        limits_cli.register_limits_parser,
+        pane_cli.register_pane_parser,
+        send_cli.register_send_parser,
+        session_cli.register_session_parser,
+        portal_cli.register_portal_parser,
+        tts_cli.register_tts_parser,
+        channels_cli.register_channels_parser,
+        scheduler_cli.register_scheduler_parser,
+        ensure_cli.register_ensure_parser,
+        doctor_cli.register_doctor_parser,
+        safety_cli.register_safety_parser,
+        machine_cli.register_machine_parser,
+        history_cli.register_history_parser,
+        roles_cli.register_roles_parser,
+        roles_cli.register_projects_parser,
+        hooks_cli.register_hooks_parser,
+        tunnels_cli.register_tunnels_parser,
+        handoff_cli.register_handoff_parser,
+        mcp_cli.register_mcp_parser,
+        notify_cli.register_notify_parser,
+        wiki_cli.register_wiki_parser,
+        system_cli.register_system_parser,
+        push_cli.register_push_parser,
+        repo_cli.register_repo_parser,
+    ]
+    for _reg in _REGISTRARS:
+        _reg(subparsers)
+
+    # === council command group ===
+    council_parser = subparsers.add_parser(
+        "council",
+        help="Multi-soul council: fan a prompt out to lens sessions, synthesize",
+        description=(
+            "An agentwire-council orchestrator session fans prompts out to a "
+            "roster of lens souls (brain, conscience, gut, critic, historian, "
+            "devils-advocate), collects their takes through a file inbox, and "
+            "synthesizes. See docs/wiki/council.md."
+        ),
+    )
+    council_subparsers = council_parser.add_subparsers(dest="council_command")
+
+    # Targeting is shared: --name picks the sitting; absent, the cwd-repo-slug
+    # if it matches a live sitting, else the sole live sitting, else error.
+    _name_help = "Sitting name (default: cwd-repo-slug / sole live sitting)"
+
+    # council start
+    c_start = council_subparsers.add_parser(
+        "start", help="Start a sitting: orchestrator + all soul sessions"
+    )
+    c_start.add_argument(
+        "--name", help="Sitting name (default: cwd-repo-slug)"
+    )
+    c_start.add_argument(
+        "--roster", help="Comma-separated lens names (default: full bundled roster)"
+    )
+    c_start.add_argument("--type", help="Session type (default: claude-bypass)")
+    c_start.add_argument("--model", help="Model override for all council sessions")
+    c_start.add_argument(
+        "--force", action="store_true", help="Tear down a live sitting first"
+    )
+    c_start.add_argument("--json", action="store_true", help="Output JSON")
+    c_start.set_defaults(func=council_cli.cmd_council_start)
+
+    # council stop
+    c_stop = council_subparsers.add_parser(
+        "stop", help="Kill the sitting's sessions (prompt history kept)"
+    )
+    c_stop.add_argument("--name", help=_name_help)
+    c_stop.add_argument("--json", action="store_true", help="Output JSON")
+    c_stop.set_defaults(func=council_cli.cmd_council_stop)
+
+    # council status
+    c_status = council_subparsers.add_parser(
+        "status", help="Sitting state, session liveness, open prompts"
+    )
+    c_status.add_argument("--name", help=_name_help)
+    c_status.add_argument("--json", action="store_true", help="Output JSON")
+    c_status.set_defaults(func=council_cli.cmd_council_status)
+
+    # council list
+    c_list = council_subparsers.add_parser(
+        "list", help="Every known sitting: name, cwd, age, live sessions, prompts"
+    )
+    c_list.add_argument("--json", action="store_true", help="Output JSON")
+    c_list.set_defaults(func=council_cli.cmd_council_list)
+
+    # council ask
+    c_ask = council_subparsers.add_parser(
+        "ask", help="Fan a prompt out to every soul in the sitting"
+    )
+    c_ask.add_argument("prompt", nargs="?", help="Prompt text (or --file / stdin)")
+    c_ask.add_argument("--name", help=_name_help)
+    c_ask.add_argument("--file", help="Read prompt text from a file")
+    c_ask.add_argument("--json", action="store_true", help="Output JSON")
+    c_ask.set_defaults(func=council_cli.cmd_council_ask)
+
+    # council collect
+    c_collect = council_subparsers.add_parser(
+        "collect", help="Wait for every soul's take/ack/pass (or timeout)"
+    )
+    c_collect.add_argument("--name", help=_name_help)
+    c_collect.add_argument("--prompt", type=int, help="Prompt id (default: latest)")
+    c_collect.add_argument(
+        "--timeout", type=float, default=120, help="Soft timeout in seconds (default: 120)"
+    )
+    c_collect.add_argument(
+        "--no-wait", action="store_true", help="Snapshot once, don't block"
+    )
+    c_collect.add_argument("--json", action="store_true", help="Output JSON")
+    c_collect.set_defaults(func=council_cli.cmd_council_collect)
+
+    # council reply (run by souls)
+    c_reply = council_subparsers.add_parser(
+        "reply", help="File a soul's reply: --take / --ack / --pass"
+    )
+    c_reply.add_argument("--name", help=_name_help)
+    c_reply.add_argument("--prompt", type=int, help="Prompt id (default: latest)")
+    c_reply.add_argument(
+        "--take", action="store_true", help="Substantive take (text required)"
+    )
+    c_reply.add_argument(
+        "--ack", action="store_true", help="Researching — follow-up coming"
+    )
+    c_reply.add_argument(
+        "--pass", action="store_true", help="Nothing to add through this lens"
+    )
+    c_reply.add_argument("--soul", help="Lens name (default: inferred from session)")
+    c_reply.add_argument("--text", help="Reply text")
+    c_reply.add_argument("--file", help="Read reply text from a file")
+    c_reply.add_argument("--json", action="store_true", help="Output JSON")
+    c_reply.set_defaults(func=council_cli.cmd_council_reply)
+
+    return parser
+
+
+def _find_subparser(parser: argparse.ArgumentParser, *names: str):
+    """Walk the subparser tree by command name(s); return the parser or None."""
+    current = parser
+    for name in names:
+        sub = None
+        for action in current._actions:
+            if isinstance(action, argparse._SubParsersAction):
+                sub = action.choices.get(name)
+                break
+        if sub is None:
+            return None
+        current = sub
+    return current
+
+
+# Command groups whose bare invocation (no subcommand) prints group help.
+_GROUP_COMMANDS = [
+    "portal", "tts", "stt", "tunnels", "machine", "history", "handoff",
+    "wiki", "hooks", "projects", "safety", "network", "listen",
+    "voiceclone", "roles", "task", "lock", "scheduler", "council", "limits",
+]
+
+
+def main() -> int:
+    """Main entry point."""
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    if (
+        args.command in _GROUP_COMMANDS
+        and getattr(args, f"{args.command}_command", None) is None
+    ):
+        _find_subparser(parser, args.command).print_help()
+        return 0
+
+    if (
+        args.command == "safety"
+        and getattr(args, "safety_command", None) == "tooldefs"
+        and getattr(args, "tooldefs_command", None) is None
+    ):
+        _find_subparser(parser, "safety", "tooldefs").print_help()
+        return 0
+
+    if hasattr(args, "func"):
+        return args.func(args)
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())