agentwire-dev 1.79.0__tar.gz → 1.80.0__tar.gz

{agentwire_dev-1.79.0 → agentwire_dev-1.80.0}/.github/workflows/pytest.yml

@@ -48,7 +48,7 @@ jobs:
       - name: Run test suite (full) + coverage
         if: github.event_name != 'pull_request'
         run: >
-          uv run --no-sync pytest -q -m "not requires_tmux"
+          uv run --no-sync pytest -q -m "not requires_tmux and not upgrade"
           --cov=agentwire --cov-report=term-missing --cov-report=xml
 
       - name: Publish coverage summary (report-only)
@@ -70,6 +70,29 @@ jobs:
           path: coverage.xml
           if-no-files-found: ignore
 
+  # Upgrade test (#1276): the previous release from PyPI, upgraded in place to this checkout, in a
+  # fresh HOME. Needs the network and builds two venvs, so it is NOT in the PR gate: it runs on
+  # pushes to main and on PRs into a release branch. Budget: ~10 min timeout, ~1 min typical.
+  # PyPI index lag is the one flake to rerun, not a reason to skip it.
+  upgrade:
+    name: upgrade from previous release
+    if: github.event_name == 'push' || startsWith(github.base_ref, 'release')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Sync dependencies
+        run: uv sync --extra dev
+
+      - name: Upgrade test
+        run: uv run --no-sync pytest -q -m upgrade tests/integration/test_upgrade_from_release.py
+
   # The hook is `python -I -m damage_control.hook` and runs under whatever `python3` the user
   # has; the package's declared floor is 3.9 (#1223: a 3.10-only construct made the hooks crash
   # non-blocking, i.e. fail OPEN). The main job runs 3.12 and cannot see that. agentwire itself

{agentwire_dev-1.79.0 → agentwire_dev-1.80.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentwire-dev
-Version: 1.79.0
+Version: 1.80.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
@@ -228,7 +228,7 @@ Requires-Dist: aiohttp-jinja2>=1.6
 Requires-Dist: aiohttp>=3.13.4
 Requires-Dist: av>=12.0.0
 Requires-Dist: certifi>=2026.10.23
-Requires-Dist: damage-control-dev<0.3,>=0.2.0
+Requires-Dist: damage-control-dev<0.4,>=0.3.0
 Requires-Dist: fastapi>=0.104.0
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: kokoro-onnx>=0.4.9; python_version < '3.14'

{agentwire_dev-1.79.0 → agentwire_dev-1.80.0}/RELEASING.md

@@ -6,17 +6,22 @@ Every release does **both** a PyPI publish and a GitHub release. The **GitHub re
 
 ## The engine is a separate project (single source)
 
-The damage-control engine has exactly one source: the `damage-control-dev` repo (<https://github.com/dotdevdotdev/damage-control-dev>), published on PyPI. `agentwire-dev` only *consumes* it through the range in `pyproject.toml` (currently `damage-control-dev>=0.2.0,<0.3`); a checkout and a PyPI install both resolve it from PyPI. There is no copy of the engine in this repo and nothing to release from here. `tests/unit/test_damage_control_pin.py` checks that the declared floor/ceiling parse and that the installed engine satisfies them.
+The damage-control engine has exactly one source: the `damage-control-dev` repo (<https://github.com/dotdevdotdev/damage-control-dev>), published on PyPI. `agentwire-dev` only *consumes* it through the range in `pyproject.toml` (currently `damage-control-dev>=0.3.0,<0.4`); a checkout and a PyPI install both resolve it from PyPI. There is no copy of the engine in this repo and nothing to release from here. `tests/unit/test_damage_control_pin.py` checks that the declared floor/ceiling parse and that the installed engine satisfies them.
 
 To ship an engine change:
 
 1. **Land it in the damage-control-dev repo**, tag and release it there (its own release flow). Do not tag or release from this repo.
-2. **Raise the floor here** in a normal agentwire PR: bump the `>=` in `pyproject.toml` (and the `<` ceiling too if the engine crossed it, e.g. `>=0.2.0,<0.3`), run `uv lock`, and re-run `scripts/golden_snapshot.py check` and `scripts/effective_rules.py --check` — re-record the golden only if the behavior change is intended, in that same PR.
+2. **Raise the floor here** in a normal agentwire PR: bump the `>=` in `pyproject.toml` (and the `<` ceiling too if the engine crossed it, e.g. `>=0.3.0,<0.4`), run `uv lock`, and re-run `scripts/golden_snapshot.py check` and `scripts/effective_rules.py --check` — re-record the golden only if the behavior change is intended, in that same PR.
 3. **Verify against the published wheel** before releasing agentwire: in a scratch venv, install the agentwire wheel (it pulls the engine from PyPI), then run the fast suite, `agentwire doctor` and a hook subprocess smoke under a temp `HOME`.
 4. **Then** bump and publish `agentwire-dev` (steps below), then the GitHub release.
 
 An `agentwire-dev` whose floor names an engine version PyPI doesn't have yet is uninstallable, so step 1 always completes (published) before step 2 merges.
 
+## Pre-release checklist
+
+- The **`upgrade from previous release`** job in `.github/workflows/pytest.yml` is green on the commit you are about to tag (it runs on pushes to main and on PRs into a `release*` branch, not on ordinary PRs). It installs the previous release from PyPI, upgrades it to this checkout in a fresh `HOME`, then asserts `safety migrate` and `doctor` behave. Details: [`docs/wiki/internals/upgrade-test.md`](docs/wiki/internals/upgrade-test.md). Rerun it if the only failure is PyPI index lag.
+- Engine bumps: also follow step 3 of the engine section above.
+
 ## Steps
 
 ### 1. Bump version

{agentwire_dev-1.79.0 → agentwire_dev-1.80.0}/agentwire/__init__.py

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

{agentwire_dev-1.79.0 → agentwire_dev-1.80.0}/agentwire/__main__.py

@@ -189,7 +189,7 @@ Command Categories:
     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, palette_cli, push_cli, repo_cli, system_cli, wiki_cli
-    from . import restart_cli, tabs_cli, wait_cli, worktree_cli
+    from . import fleet_cli, restart_cli, tabs_cli, wait_cli, worktree_cli
     from .council import cli as council_cli
 
     _REGISTRARS = [  # noqa: N806  # registry constant; Phase 1 of #495 appends here
@@ -226,6 +226,7 @@ Command Categories:
         palette_cli.register_palette_parser,
         tabs_cli.register_tabs_parser,
         wait_cli.register_wait_parser,
+        fleet_cli.register_fleet_parser,
         worktree_cli.register_helper_parser,
     ]
     for _reg in _REGISTRARS:

{agentwire_dev-1.79.0 → agentwire_dev-1.80.0}/agentwire/cohort.py

@@ -132,19 +132,43 @@ def ledger_path(parent: str) -> Path:
     return path
 
 
+def read(parent: str) -> tuple[dict | None, str | None]:
+    """``(ledger, problem)`` — exactly one is None.
+
+    ``problem`` is ``"missing"`` (no file) or ``"corrupt: <why>"``. The
+    distinction is for read-only reporters (``agentwire fleet``); the guard
+    paths use :func:`load`, which deliberately collapses both to "no cohort".
+    """
+    try:
+        text = ledger_path(parent).read_text()
+    except FileNotFoundError:
+        return None, "missing"
+    except (OSError, ValueError) as e:  # ValueError: invalid session name / undecodable bytes
+        return None, f"corrupt: {e}"
+    try:
+        data = json.loads(text)
+    except ValueError as e:
+        return None, f"corrupt: {e}"
+    if not isinstance(data, dict) or not isinstance(data.get("children"), list):
+        return None, "corrupt: not a cohort ledger (no children list)"
+    return data, None
+
+
 def load(parent: str) -> dict | None:
     """The parent's ledger, or None when absent/unreadable/malformed.
 
     Fails open on purpose: a corrupt ledger reads as "no cohort", so the guard
     stops suppressing and the parent resumes normal idle handling.
     """
-    try:
-        data = json.loads(ledger_path(parent).read_text())
-    except (OSError, ValueError):
-        return None
-    if not isinstance(data, dict) or not isinstance(data.get("children"), list):
-        return None
-    return data
+    return read(parent)[0]
+
+
+def ledger_parents() -> list[str]:
+    """Every parent session that has a ledger file, sorted (worktree names nest)."""
+    if not COHORT_ROOT.exists():
+        return []
+    return sorted(str(p.relative_to(COHORT_ROOT))[: -len(".json")]
+                  for p in COHORT_ROOT.rglob("*.json"))
 
 
 def _save(parent: str, data: dict) -> None:
@@ -301,6 +325,7 @@ def _mark(data: dict, child: str, state: str, report: str | None = None) -> None
     for entry in data["children"]:
         if entry.get("session") == child:
             entry["state"] = state
+            entry["resolved_at"] = _now()
             if report is not None:
                 entry["report"] = report
 
@@ -344,6 +369,7 @@ def record_delivery(parent: str, messages: list) -> None:
                 else:
                     continue
                 entry["delivered"] = True
+                entry["resolved_at"] = _now()
                 changed = True
                 log_event("delivered_by_drain", parent=parent, child=entry["session"],
                           state=entry["state"])

{agentwire_dev-1.79.0 → agentwire_dev-1.80.0}/agentwire/config.py

@@ -295,6 +295,27 @@ class AgentConfig:
     command: str = field(default_factory=_get_default_agent_command)
 
 
+@dataclass
+class SandboxConfig:
+    """Allowances for ``agentwire new --sandbox`` (#1279). Opt-in; nothing here
+    applies to a session launched without the flag. Writes are otherwise
+    limited to the session's working directory; ``~/.agentwire`` stays
+    read-only except the message-passing paths below, so a sandboxed agent
+    cannot edit ``damagecontrol.yml`` or ``.env``."""
+
+    allow_write: list[str] = field(default_factory=lambda: [
+        "~/.cache/uv",  # uv run / uv sync
+        "~/.agentwire/inbox", "~/.agentwire/inbox-events.jsonl",  # msg send / notify-parent --queued
+        "~/.agentwire/sent-ledger",
+    ])
+    allowed_domains: list[str] = field(default_factory=lambda: [
+        "github.com", "api.github.com", "pypi.org", "files.pythonhosted.org",
+    ])
+    allow_unix_sockets: list[str] = field(default_factory=list)  # tmux socket is always added
+    excluded_commands: list[str] = field(default_factory=lambda: ["gh *"])  # Go TLS fails under the proxy on macOS
+    allow_local_binding: bool = True  # macOS: needed to reach the local portal API
+
+
 @dataclass
 class MachinesConfig:
     """Remote machines registry configuration."""
@@ -618,6 +639,7 @@ class Config:
     tts: TTSConfig = field(default_factory=TTSConfig)
     stt: STTConfig = field(default_factory=STTConfig)
     agent: AgentConfig = field(default_factory=AgentConfig)
+    sandbox: SandboxConfig = field(default_factory=SandboxConfig)
     machines: MachinesConfig = field(default_factory=MachinesConfig)
     uploads: UploadsConfig = field(default_factory=UploadsConfig)
     artifacts: ArtifactsConfig = field(default_factory=ArtifactsConfig)
@@ -775,6 +797,14 @@ def _dict_to_config(data: dict) -> Config:
         command=agent_data.get("command", _get_default_agent_command()),
     )
 
+    # Sandbox allowances (#1279) — a key that is absent keeps its default.
+    sandbox_data = data.get("sandbox") or {}
+    sandbox_defaults = SandboxConfig()
+    sandbox = SandboxConfig(**{
+        key: sandbox_data.get(key, getattr(sandbox_defaults, key))
+        for key in SandboxConfig.__dataclass_fields__
+    })
+
     # Machines
     machines_data = data.get("machines", {})
     machines = MachinesConfig(
@@ -1017,6 +1047,7 @@ def _dict_to_config(data: dict) -> Config:
         tts=tts,
         stt=stt,
         agent=agent,
+        sandbox=sandbox,
         machines=machines,
         uploads=uploads,
         artifacts=artifacts,

{agentwire_dev-1.79.0 → agentwire_dev-1.80.0}/agentwire/core.py

@@ -254,6 +254,7 @@ class AgentCommand:
     roles: list[str] = field(default_factory=list)  # Role NAMES, in merge order
     model: str | None = None  # --model override, if the launch chose one
     effort: str | None = None  # --effort override, if the launch chose one
+    sandbox: bool = False  # launched under Claude Code's sandbox (--sandbox, #1279)
 
 
 _UNATTENDED_ENV_KEYS = ("AGENTWIRE_UNATTENDED", "AGENTWIRE_UNATTENDED_ALLOW")
@@ -626,9 +627,13 @@ def build_agent_command(
     model: str | None = None,
     resume_session_id: str | None = None,
     effort: str | None = None,
+    sandbox: bool = False,
 ) -> AgentCommand:
     """Build the shell command + injected env for the given posture.
 
+    ``sandbox`` adds ``--settings`` enabling Claude Code's native sandbox with
+    the allowances from ``config.yaml`` (#1279; see :mod:`agentwire.sandbox`).
+
     The ONE flag-builder (#729): fresh sessions AND history resume both route
     through here, so a posture always launches with the same flags — no
     create-vs-resume drift. Posture switches the permission-mode flags; ``bare``
@@ -687,6 +692,12 @@ def build_agent_command(
     if effort:
         parts.append(f"--effort {effort}")
 
+    if sandbox:
+        from . import sandbox as sandbox_mod
+        from .config import load_config as load_typed_config
+
+        parts.append(sandbox_mod.settings_flag(sandbox_mod.settings_for(load_typed_config())))
+
     # Role-based flags (merged roles always apply — no tool-locking posture left)
     role_prompt_path = None
     if merged:
@@ -712,6 +723,7 @@ def build_agent_command(
         roles=role_names,
         model=model,
         effort=effort,
+        sandbox=sandbox,
     )
 
 
@@ -1523,6 +1535,7 @@ def record_session_launch(
         # conversation back on a different model/effort than it was running on.
         "model": agent.model,
         "effort": agent.effort,
+        "sandbox": agent.sandbox,
         "role_prompt_path": agent.role_prompt_path,
         "launched_at": now,
         **({"repo": None, "branch": None, "worktree_path": None}

{agentwire_dev-1.79.0 → agentwire_dev-1.80.0}/agentwire/doctor_cli.py

@@ -1128,13 +1128,11 @@ def _render_cohort_section() -> int:
     from . import cohort
 
     suspects = []
-    if cohort.COHORT_ROOT.exists():
-        for path in sorted(cohort.COHORT_ROOT.rglob("*.json")):
-            parent = str(path.relative_to(cohort.COHORT_ROOT))[: -len(".json")]
-            data = cohort.load(parent)
-            reason = cohort.suspect_reason(parent, data) if data else None
-            if reason:
-                suspects.append((parent, reason))
+    for parent in cohort.ledger_parents():
+        data = cohort.load(parent)
+        reason = cohort.suspect_reason(parent, data) if data else None
+        if reason:
+            suspects.append((parent, reason))
     if not suspects:
         print("  [ok] No suspect cohort ledgers")
         return 0
@@ -1146,6 +1144,28 @@ def _render_cohort_section() -> int:
     return 1
 
 
+def _render_fleet_section() -> int:
+    """Doctor section: delegation problems from ``agentwire fleet`` (#1277).
+
+    Renders :func:`fleet.build_fleet` and nothing else — the flags are decided
+    there, so doctor, the CLI and the portal cannot disagree.
+    """
+    from . import fleet
+
+    data = fleet.build_fleet(None)
+    problems = len(data["flagged"]) + len(data["broken_ledgers"])
+    if not problems:
+        print("  [ok] No stuck or silent children in any fan-out")
+        return 0
+    print(f"  [!!] {problems} fleet problem(s):")
+    for b in data["broken_ledgers"]:
+        print(f"       - {b['parent']}: cohort ledger {b['ledger']}")
+    for f in data["flagged"]:
+        print(f"       - {f['session']} (child of {f['parent']}): {f['flag']}")
+    print("       Details: agentwire fleet --all")
+    return 1
+
+
 def _render_auth_expired_section() -> int:
     """Doctor section: an active expired-login outage (#906).
 
@@ -1426,6 +1446,28 @@ def _render_role_prompt_store_section(
     return 1, 1
 
 
+def _render_sandbox_section() -> int:
+    """Which recorded sessions run under the Claude Code sandbox (#1279).
+
+    Reads the launch record — the flag is recorded, not guessed from a pane —
+    and flags a machine where a sandboxed session could not (re)start, since
+    ``failIfUnavailable`` makes that a hard refusal, not a silent downgrade.
+    """
+    from . import sandbox
+
+    names = sandbox.sandboxed_sessions()
+    problem = sandbox.platform_problem()
+    if not names:
+        print("  [ok] No session was launched with --sandbox")
+        return 0
+    for name in names:
+        print(f"  [ok] {name}: sandboxed (launch record)")
+    if problem:
+        print(f"  [!!] sandbox cannot start on this machine: {problem}")
+        return 1
+    return 0
+
+
 def _render_blocked_prompt_section() -> int:
     """Doctor section: agent alive, but the pane sits on an unanswered menu (#905).
 
@@ -2165,6 +2207,12 @@ def cmd_doctor(args) -> int:
     print("\nChecking for suspect cohort ledgers...")
     issues_found += _render_cohort_section()
 
+    print("\nChecking the fleet (stuck or silent children)...")
+    try:
+        issues_found += _render_fleet_section()
+    except Exception as e:
+        print(f"  [..] Could not check the fleet: {e}")
+
     # 10c. Expired Claude login (#906) — the state that made #867 cost two
     # hours. Nothing else on this list would surface it: the pane is alive and
     # the agent process is running, so every liveness check passes.
@@ -2251,6 +2299,12 @@ def cmd_doctor(args) -> int:
     except Exception as e:
         print(f"  [..] Could not check the role-prompt store: {e}")
 
+    print("\nChecking sandboxed sessions (#1279)...")
+    try:
+        issues_found += _render_sandbox_section()
+    except Exception as e:
+        print(f"  [..] Could not check sandboxed sessions: {e}")
+
     # 12c. Sessions blocked on an unanswered dialog (#905). The one state every
     # other check calls healthy: the agent process is running, so liveness
     # passes, while the pane sits on a menu and does nothing.

agentwire_dev-1.80.0/agentwire/fleet.py

@@ -0,0 +1,189 @@
+"""Fleet view — one read-only picture of every session an orchestrator spawned (#1277).
+
+Delegation failed silently in three different ways (no parent, wrong parent
+name, dead-lettered reports) and each was found hours later by the owner. The
+data to see all three already exists in four places; this module is the ONE
+reader that joins them:
+
+* the cohort ledger (:mod:`agentwire.cohort`) — who spawned whom, and what each
+  child's report-back resolved to;
+* the worktree registry — a child's branch;
+* the inbox (:mod:`agentwire.inbox`) — reports waiting for, or dead-lettered
+  away from, the parent, plus messages waiting for the child itself;
+* session records and tmux liveness.
+
+``agentwire fleet --json`` is :func:`build_fleet`'s output verbatim; ``doctor``
+and the portal call the CLI and render it — neither re-derives anything.
+
+**Reads only.** No ledger is rewritten, no message touched, nothing killed.
+
+**Absence is reported, never raised.** A corrupt ledger is a parent row whose
+``ledger`` field says so; a child with no session record is a row with
+``session_record: false``. A reader that crashes on the broken thing it exists
+to expose is useless exactly when it matters.
+
+Flags (``flags`` on a child, aggregated in ``flagged``):
+
+``idle_no_report``
+    The child went idle and the only thing it left was the idle handler's
+    placeholder — its work may not have happened.
+``report_queued_to_dead_session``
+    A report from the child sits in the inbox of a parent that is not live;
+    nothing will ever drain it.
+``report_dead_lettered``
+    A load-bearing message from the child was dead-lettered on the way to the
+    parent.
+``gone_with_open_pr``
+    The child's session is gone but its branch still has an OPEN PR — nobody
+    is positioned to act on it. PR state comes from
+    :func:`agentwire.session_cli.pr_for_branch`, the same probe the dangling-PR
+    scan uses.
+``no_session_record``
+    A live child with no launch record — its role and parent are unknowable.
+"""
+
+from __future__ import annotations
+
+import time
+
+from . import cohort, inbox, worktree_registry
+
+IDLE_NO_REPORT = "idle_no_report"
+REPORT_QUEUED_TO_DEAD = "report_queued_to_dead_session"
+REPORT_DEAD_LETTERED = "report_dead_lettered"
+GONE_WITH_OPEN_PR = "gone_with_open_pr"
+NO_SESSION_RECORD = "no_session_record"
+
+STATE_RUNNING = "running"
+STATE_IDLE = "idle"
+STATE_GONE = "gone"
+
+
+def _oldest_age_s(messages: list, now_ms: int) -> int | None:
+    stamps = [m.ts for m in messages if m.ts]
+    return max(0, (now_ms - min(stamps)) // 1000) if stamps else None
+
+
+def _safe(fn, *args) -> list:
+    """An inbox read that degrades to "nothing" — an unreadable inbox must not
+    take the whole fleet view down with it."""
+    try:
+        return fn(*args)
+    except (OSError, ValueError):
+        return []
+
+
+def _branches_by_session() -> dict[str, dict]:
+    """Registry entry per worktree-topology session (pane entries name their
+    OWNER, not a child, so they are not a branch of any session here)."""
+    try:
+        rows = worktree_registry.all_entries()
+    except Exception:
+        return {}
+    return {r["session"]: r for r in rows
+            if r.get("session") and r.get("topology", "worktree") == "worktree"}
+
+
+def _child_row(parent: str, parent_live: bool, entry: dict, *, registry: dict[str, dict],
+               parent_pending: list, parent_dead: list, now_ms: int,
+               with_pr: bool) -> dict:
+    from .core import load_session_metadata
+    from .session_cli import pr_for_branch
+
+    name = str(entry.get("session") or "")
+    ledger_state = entry.get("state")
+    live = bool(name) and cohort.session_exists(name)
+    if not live:
+        state = STATE_GONE
+    elif ledger_state == cohort.IDLE:
+        state = STATE_IDLE
+    else:
+        state = STATE_RUNNING
+
+    record = load_session_metadata(name) if name else {}
+    reg = registry.get(name) or {}
+    branch = reg.get("branch")
+    pr = pr_for_branch(branch, reg.get("project")) if (with_pr and branch) else None
+
+    queued = [m for m in parent_pending if m.sender == name and m.kind in cohort.REPORT_KINDS]
+    dead = inbox.load_bearing([m for m in parent_dead if m.sender == name])
+    resolved_at = entry.get("resolved_at")
+
+    row = {
+        "session": name,
+        "parent": parent,
+        "role": record.get("role"),
+        "roles": record.get("roles") or [],
+        "topology": entry.get("topology"),
+        "state": state,
+        "ledger_state": ledger_state,
+        "session_record": bool(record),
+        "branch": branch,
+        "pr": {"state": str(pr.get("state", "")).upper(), "url": pr.get("url")} if pr else None,
+        "last_report_at": resolved_at if ledger_state == cohort.REPORTED else None,
+        "inbox_waiting_age_s": _oldest_age_s(_safe(inbox.list_messages, name), now_ms) if name else None,
+        "dead_letter_age_s": _oldest_age_s(_safe(inbox.list_dead, name), now_ms) if name else None,
+        "report_queued_age_s": _oldest_age_s(queued, now_ms),
+        "report_dead_letter_age_s": _oldest_age_s(dead, now_ms),
+        "flags": [],
+    }
+    flags = row["flags"]
+    if ledger_state == cohort.IDLE:
+        flags.append(IDLE_NO_REPORT)
+    if queued and not parent_live:
+        flags.append(REPORT_QUEUED_TO_DEAD)
+    if dead:
+        flags.append(REPORT_DEAD_LETTERED)
+    if state == STATE_GONE and row["pr"] and row["pr"]["state"] == "OPEN":
+        flags.append(GONE_WITH_OPEN_PR)
+    if live and not record:
+        flags.append(NO_SESSION_RECORD)
+    return row
+
+
+def _parent_row(parent: str, *, registry: dict[str, dict], now_ms: int, with_pr: bool) -> dict:
+    data, problem = cohort.read(parent)
+    row = {
+        "parent": parent,
+        "live": cohort.session_exists(parent),
+        "ledger": problem or "ok",
+        "task": (data or {}).get("task"),
+        "children": [],
+    }
+    if data is None:
+        return row
+    parent_pending = _safe(inbox.list_messages, parent)
+    parent_dead = _safe(inbox.list_dead, parent)
+    for entry in data["children"]:
+        if not isinstance(entry, dict):
+            continue
+        row["children"].append(_child_row(
+            parent, row["live"], entry, registry=registry, parent_pending=parent_pending,
+            parent_dead=parent_dead, now_ms=now_ms, with_pr=with_pr))
+    return row
+
+
+def build_fleet(parent: str | None = None, *, with_pr: bool = True) -> dict:
+    """The fleet view: one row per parent, one row per child under it.
+
+    *parent* ``None`` means every ledger on the machine; otherwise just that
+    parent (a parent with no ledger yields a row saying ``missing``, so a typo
+    is visible rather than an empty success). Zero ledgers is a valid, empty
+    fleet.
+    """
+    now_ms = int(time.time() * 1000)
+    registry = _branches_by_session()
+    parents = [parent] if parent else cohort.ledger_parents()
+    rows = [_parent_row(p, registry=registry, now_ms=now_ms, with_pr=with_pr) for p in parents]
+    flagged = [
+        {"session": c["session"], "parent": r["parent"], "flag": f}
+        for r in rows for c in r["children"] for f in c["flags"]
+    ]
+    broken = [{"parent": r["parent"], "ledger": r["ledger"]}
+              for r in rows if r["ledger"] not in ("ok", "missing")]
+    return {
+        "success": True,
+        "parents": rows,
+        "flagged": flagged,
+        "broken_ledgers": broken,
+    }

agentwire_dev-1.80.0/agentwire/fleet_cli.py

@@ -0,0 +1,89 @@
+"""``agentwire fleet`` — the report-back ledger and fleet view (#1277).
+
+The CLI is the single source of truth: ``--json`` is :func:`fleet.build_fleet`
+verbatim, and ``doctor`` and the portal both call it. See :mod:`agentwire.fleet`.
+"""
+
+import json
+import time
+
+from . import fleet
+
+
+def _age(seconds) -> str:
+    if seconds is None:
+        return "-"
+    for unit, size in (("d", 86400), ("h", 3600), ("m", 60)):
+        if seconds >= size:
+            return f"{seconds // size}{unit}"
+    return f"{seconds}s"
+
+
+def render_fleet_text(data: dict) -> str:
+    """Human rendering of a :func:`fleet.build_fleet` result."""
+    lines: list[str] = []
+    for p in data["parents"]:
+        live = "live" if p["live"] else "NOT LIVE"
+        lines.append(f"{p['parent']} ({live})" + (f" — ledger {p['ledger']}" if p["ledger"] != "ok" else ""))
+        for c in p["children"]:
+            bits = [c["state"], c.get("topology") or "?"]
+            if c.get("role"):
+                bits.append(c["role"])
+            if c.get("branch"):
+                bits.append(f"branch={c['branch']}")
+            if c.get("pr"):
+                bits.append(f"PR {c['pr']['state']} {c['pr'].get('url') or ''}".strip())
+            if c.get("last_report_at"):
+                bits.append(f"reported {_age(int(time.time()) - int(c['last_report_at']))} ago")
+            for label, key in (("inbox", "inbox_waiting_age_s"), ("dead", "dead_letter_age_s"),
+                               ("report queued", "report_queued_age_s"),
+                               ("report dead-lettered", "report_dead_letter_age_s")):
+                if c.get(key) is not None:
+                    bits.append(f"{label} {_age(c[key])}")
+            flags = "".join(f"  [!! {f}]" for f in c["flags"])
+            lines.append(f"  {c['session']}: {', '.join(bits)}{flags}")
+        if not p["children"] and p["ledger"] == "ok":
+            lines.append("  (no children)")
+    if not data["parents"]:
+        lines.append("No cohort ledgers — nothing has been spawned with a report-back.")
+    if data["flagged"]:
+        lines.append(f"\n{len(data['flagged'])} problem(s) flagged.")
+    return "\n".join(lines)
+
+
+def cmd_fleet(args) -> int:
+    """Print the fleet. Read-only; exit 0 even when flags are raised."""
+    from . import pane_manager
+
+    parent = None
+    if not getattr(args, "all", False):
+        parent = getattr(args, "session", None) or pane_manager.get_current_session()
+    data = fleet.build_fleet(parent, with_pr=not getattr(args, "no_pr", False))
+    if getattr(args, "json", False):
+        print(json.dumps(data, indent=2))
+    else:
+        print(render_fleet_text(data))
+    return 0
+
+
+def register_fleet_parser(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "fleet",
+        help="Every session an orchestrator spawned: state, PR, report-back, stuck messages",
+        description=(
+            "Read-only view of a session's fan-out: per child its role/topology, "
+            "state (running/idle/gone), branch and open PR, last report time, and "
+            "the age of any message waiting in or dead-lettered from its inbox. "
+            "Flags a child that went idle without reporting, a report queued for "
+            "a session that is not live, a dead-lettered report, and a gone "
+            "child still holding an open PR."
+        ),
+    )
+    parser.add_argument("-s", "--session",
+                        help="Orchestrator to show (default: the current tmux session)")
+    parser.add_argument("--all", action="store_true",
+                        help="Every orchestrator with a cohort ledger on this machine")
+    parser.add_argument("--no-pr", action="store_true",
+                        help="Skip the GitHub PR lookup (faster; offline)")
+    parser.add_argument("--json", action="store_true", help="Output JSON")
+    parser.set_defaults(func=cmd_fleet)