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

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

@@ -93,6 +93,31 @@ jobs:
       - name: Upgrade test
         run: uv run --no-sync pytest -q -m upgrade tests/integration/test_upgrade_from_release.py
 
+  # Scoped-allow mutation check (#1293): scripts/mutate_scoped_allow.py breaks each #914 safety
+  # property once and demands a red test. It exits 1 on any surviving mutation AND on a stale
+  # anchor (a skipped mutation counts as a survivor), so engine or source drift that silently
+  # detaches an anchor turns this job red. Pushes to main only, not the PR gate.
+  # Budget: ~10 min timeout, ~30 s typical (19 mutations x one test file).
+  mutation:
+    name: scoped-allow mutation check
+    if: github.event_name == 'push'
+    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"
+
+      # The script mutates the engine inside this checkout's .venv, so it must exist.
+      - name: Sync dependencies
+        run: uv sync --extra dev
+
+      - name: Mutation check
+        run: uv run --extra dev python scripts/mutate_scoped_allow.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.80.0 → agentwire_dev-1.81.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentwire-dev
-Version: 1.80.0
+Version: 1.81.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.4,>=0.3.0
+Requires-Dist: damage-control-dev<0.5,>=0.4.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.80.0 → agentwire_dev-1.81.0}/RELEASING.md

@@ -6,7 +6,7 @@ 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.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.
+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.4.0,<0.5`); 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:
 
@@ -20,6 +20,7 @@ An `agentwire-dev` whose floor names an engine version PyPI doesn't have yet is
 ## 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.
+- The **`scoped-allow mutation check`** job in the same workflow is green on that commit (pushes to main only; ~30 s). It runs `scripts/mutate_scoped_allow.py` and fails on any surviving mutation or stale anchor. If it is red after an engine floor bump, re-anchor the mutations in the script rather than skipping it.
 - Engine bumps: also follow step 3 of the engine section above.
 
 ## Steps

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

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

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

@@ -1563,6 +1563,23 @@ def record_session_launch(
     return metadata
 
 
+def session_owns_cwd(metadata: dict, cwd: str) -> bool:
+    """Whether *cwd* is where the recorded session runs (#1289).
+
+    Compared as Claude keys history: the physical path through
+    ``history.encode_project_path``, against ``cwd_at_launch`` and
+    ``worktree_path``. A nested ``claude -p`` started from a pane in a scratch
+    directory fails this, which keeps its conversation out of the chain.
+    """
+    from .history import encode_project_path
+
+    def key(path: str) -> str:
+        return encode_project_path(os.path.realpath(path))
+
+    owned = {key(p) for p in (metadata.get("cwd_at_launch"), metadata.get("worktree_path")) if p}
+    return key(cwd) in owned
+
+
 def record_conversation_change(session_name: str, conversation_id: str) -> bool:
     """Make *conversation_id* the session's CURRENT conversation (#1271).
 

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

@@ -882,7 +882,7 @@ def scan_orphaned_history(sessions: list[str] | None = None) -> list[dict]:
       flag hundreds of them, most of which nobody will ever relaunch.
     """
     from .core import load_session_metadata, recorded_sessions, tmux_session_cwd
-    from .history import locate_conversation
+    from .history import survey_chain
 
     findings: list[dict] = []
     for name in sessions if sessions is not None else recorded_sessions():
@@ -898,9 +898,7 @@ def scan_orphaned_history(sessions: list[str] | None = None) -> list[dict]:
         # Newest first, mirroring the order restart walks — so "the current
         # conversation" is the first link, and the orphans read in the order
         # anyone would care about them.
-        located = [locate_conversation(cid, running_in) for cid in reversed(ids)]
-        orphans = [loc for loc in located if loc.status == "orphaned"]
-        resumable = next((loc for loc in located if loc.resumable), None)
+        located, orphans, resumable = survey_chain(ids, running_in)
 
         common = {
             "session": name,
@@ -993,7 +991,9 @@ def _render_orphaned_history_section() -> int:
     :func:`scan_orphaned_history`).
     """
     findings = scan_orphaned_history()
-    orphaned = [f for f in findings if f["status"] == "orphaned"]
+    orphans_all = [f for f in findings if f["status"] == "orphaned"]
+    orphaned = [f for f in orphans_all if f["live"]]
+    dead_orphaned = [f for f in orphans_all if not f["live"]]
     gone = [f for f in findings if f["status"] == "gone"]
 
     if not orphaned:
@@ -1011,11 +1011,26 @@ def _render_orphaned_history_section() -> int:
                   + ("   [moved since launch]" if f["moved"] else ""))
             print(f"         history:  {f['found_at']}")
             print(f"         expected: {f['expected_dir']}/")
+        print("       Ids whose history sits under scratch directories are nested "
+              "`claude -p` runs a worker made from its pane: before #1289 the "
+              "session-start hook recorded them into the chain. The session's own "
+              "conversation is the one keyed to its launch cwd.")
         print("       Recover with `agentwire history migrate` — the transcripts are "
               "intact, just keyed to the old path. Until then `agentwire restart` on a "
               "'current conversation' one starts FRESH (role intact) rather than "
               "failing, and never silences this line.")
 
+    if dead_orphaned:
+        print(f"  [..] {len(dead_orphaned)} session(s) not running with orphaned "
+              "conversation history (torn-down sessions keep their record; not scored):")
+        for f in dead_orphaned:
+            extra = len(f["orphaned_ids"]) - 1
+            print(f"       - {f['session']} conversation {f['conversation_id'][:8]}"
+                  + (f", +{extra} more orphaned" if extra > 0 else "")
+                  + f" — history: {f['found_at']}")
+        print("       Recover: `agentwire history migrate --session <name>` (add --apply), "
+              "or drop the dead records: `agentwire history prune --dead` (lists; --yes deletes).")
+
     if gone:
         print(f"  [..] {len(gone)} live session(s) with no conversation history on disk "
               "(never prompted, or evicted by Claude — not determinable here):")

{agentwire_dev-1.80.0 → agentwire_dev-1.81.0}/agentwire/history.py

@@ -297,6 +297,22 @@ def locate_conversation(
     )
 
 
+def survey_chain(
+    conversation_ids: list[str], cwd
+) -> tuple[list[ConversationLocation], list[ConversationLocation], ConversationLocation | None]:
+    """Probe EVERY link of a recorded chain, newest first.
+
+    Returns ``(located, orphans, resumable)``: all links, the orphaned ones,
+    and the newest resumable one. The one survey ``doctor`` and teardown share,
+    so "this chain has orphans" has a single answer (see
+    :func:`locate_conversation` for the per-link predicate).
+    """
+    located = [locate_conversation(cid, cwd) for cid in reversed(conversation_ids)]
+    orphans = [loc for loc in located if loc.status == "orphaned"]
+    resumable = next((loc for loc in located if loc.resumable), None)
+    return located, orphans, resumable
+
+
 def _get_machine_config(machine_id: str) -> dict | None:
     """Load machine config from machines.json.
 

{agentwire_dev-1.80.0 → agentwire_dev-1.81.0}/agentwire/history_cli.py

@@ -448,6 +448,95 @@ def cmd_history_migrate(args) -> int:
     return 1 if failed else 0
 
 
+def dead_session_records(older_than_s: int | None = None, *, now: float | None = None) -> list[dict]:
+    """Session records whose tmux session is not running, oldest first.
+
+    ``age_s`` is the record's own mtime age (last launch/hook write), so
+    ``older_than_s`` spares a session torn down moments ago. Each entry says
+    whether its chain has orphaned conversations — the thing worth knowing
+    before deleting the only map from session name to conversation.
+    """
+    from .core import (
+        load_session_metadata,
+        recorded_sessions,
+        session_metadata_path,
+        tmux_session_exists,
+    )
+    from .history import survey_chain
+
+    now = time.time() if now is None else now
+    rows = []
+    for name in recorded_sessions():
+        if tmux_session_exists(name):
+            continue
+        path = session_metadata_path(name)
+        try:
+            age = now - path.stat().st_mtime
+        except OSError:
+            continue
+        if older_than_s is not None and age < older_than_s:
+            continue
+        metadata = load_session_metadata(name)
+        ids = list(metadata.get("conversation_ids") or [])
+        cwd = metadata.get("cwd_at_launch")
+        orphaned = [loc.conversation_id for loc in survey_chain(ids, cwd)[1]] if ids and cwd else []
+        rows.append({"session": name, "path": str(path.parent), "age_s": int(age),
+                     "orphaned_ids": orphaned})
+    return sorted(rows, key=lambda r: -r["age_s"])
+
+
+def _delete_record(session: str) -> None:
+    """Remove a session's record file, then its now-empty directories."""
+    from .core import session_metadata_path, sessions_dir
+
+    path = session_metadata_path(session)
+    path.unlink()
+    root = sessions_dir()
+    parent = path.parent
+    while parent != root:
+        try:
+            parent.rmdir()
+        except OSError:
+            break  # not empty — other files live here; leave them
+        parent = parent.parent
+
+
+def cmd_history_prune(args) -> int:
+    """List dead session records; delete them only with --yes."""
+    from .msg_cli import _parse_duration
+
+    if not args.dead:
+        return _output_result(False, args.json, "Usage: agentwire history prune --dead [--older-than 14d] [--yes]")
+    older = None
+    if args.older_than:
+        older = _parse_duration(args.older_than)
+        if older is None:
+            return _output_result(False, args.json, f"Bad --older-than {args.older_than!r} (use e.g. 14d, 12h)")
+
+    rows = dead_session_records(older)
+    deleted = []
+    if args.yes:
+        for r in rows:
+            _delete_record(r["session"])
+            deleted.append(r["session"])
+
+    if args.json:
+        return _output_json({"success": True, "deleted": deleted, "dead": rows,
+                             "applied": args.yes})
+    if not rows:
+        print("No dead session records.")
+        return 0
+    for r in rows:
+        flag = f"  [{len(r['orphaned_ids'])} orphaned conversation(s)]" if r["orphaned_ids"] else ""
+        print(f"{'deleted' if args.yes else 'dead'}: {r['session']} ({r['age_s'] // 86400}d old){flag}")
+    if args.yes:
+        print(f"\nDeleted {len(deleted)} record(s).")
+    else:
+        print(f"\n{len(rows)} dead record(s). Re-run with --yes to delete them "
+              "(a record is the only map from session name to conversation).")
+    return 0
+
+
 def register_history_parser(subparsers) -> None:
     history_parser = subparsers.add_parser("history", help="Claude Code session history")
     history_subparsers = history_parser.add_subparsers(dest="history_command")
@@ -503,3 +592,16 @@ def register_history_parser(subparsers) -> None:
                              help="Delete the old history dir, but only after the copy verifies")
     history_mig.add_argument("--json", action="store_true", help="JSON output")
     history_mig.set_defaults(func=cmd_history_migrate)
+
+    # history prune
+    history_prune = history_subparsers.add_parser(
+        "prune",
+        help="List (or with --yes delete) session records of sessions that are not running",
+    )
+    history_prune.add_argument("--dead", action="store_true",
+                               help="Target records whose tmux session is not running")
+    history_prune.add_argument("--older-than", help="Only records untouched for this long (e.g. 14d)")
+    history_prune.add_argument("--yes", action="store_true",
+                               help="Delete the listed records (default is list only)")
+    history_prune.add_argument("--json", action="store_true", help="JSON output")
+    history_prune.set_defaults(func=cmd_history_prune)

{agentwire_dev-1.80.0 → agentwire_dev-1.81.0}/agentwire/hooks_cli.py

@@ -757,7 +757,7 @@ def record_session_start(payload: dict) -> str:
     :func:`cmd_hooks_session_start` is the one place that turns that into exit 0.
     """
     from . import pane_manager
-    from .core import record_conversation_change
+    from .core import load_session_metadata, record_conversation_change, session_owns_cwd
 
     conversation_id = payload.get("session_id")
     if not isinstance(conversation_id, str) or not conversation_id:
@@ -771,6 +771,16 @@ def record_session_start(payload: dict) -> str:
         return f"skipped: worker pane {session}.{pane_index}"
 
     source = payload.get("source", "?")
+    # A headless `claude -p` started from this pane inherits $TMUX_PANE and fires
+    # this same hook with source=startup, indistinguishable from a real start
+    # except by its cwd (#1289).
+    payload_cwd = payload.get("cwd")
+    if not isinstance(payload_cwd, str) or not payload_cwd:
+        return f"ignored: payload has no cwd, cannot tell {session}'s conversation from a nested run"
+    metadata = load_session_metadata(session)
+    if metadata.get("cwd_at_launch") and not session_owns_cwd(metadata, payload_cwd):
+        return (f"ignored: {conversation_id} ran in {payload_cwd}, not {session}'s "
+                f"{metadata['cwd_at_launch']} (nested run, source={source})")
     if record_conversation_change(session, conversation_id):
         return f"recorded {conversation_id} for {session} (source={source})"
     return f"unchanged: {session} already at {conversation_id} or has no launch record"

{agentwire_dev-1.80.0 → agentwire_dev-1.81.0}/agentwire/mcp_worktree.py

@@ -5,7 +5,7 @@ from .mcp_core import (
     get_caller_session,
     mcp,
 )
-from .worktree import teardown_session_note
+from .worktree import teardown_record_note, teardown_session_note
 
 
 @mcp.tool()
@@ -304,7 +304,10 @@ def worktree_remove(
         branch_bit = (f" Branch '{data['branch']}' deleted." if data.get("branch_deleted")
                       else f" Branch '{data['branch']}' kept ({data.get('branch_note', 'not deleted')}).")
     tabs_bit = _orphaned_tabs_warning(data.get("orphaned_tabs"))
-    return f"Teardown '{name}' (session '{session}'){session_bit}; worktree deleted.{branch_bit}{tabs_bit}"
+    record_note = teardown_record_note(data)
+    record_bit = f" {record_note[0].upper()}{record_note[1:]}." if record_note else ""
+    return (f"Teardown '{name}' (session '{session}'){session_bit}; worktree deleted."
+            f"{branch_bit}{tabs_bit}{record_bit}")
 
 
 def _orphaned_tabs_warning(orphaned: list | None) -> str:

{agentwire_dev-1.80.0 → agentwire_dev-1.81.0}/agentwire/session_cli.py

@@ -35,11 +35,13 @@ from .core import (
     _set_session_name_env,
     build_agent_command,
     load_config,
+    load_session_metadata,
     mirror_role_prompt_remote,
     notify_portal_session_created,
     parse_env_args,
     record_session_launch,
     resolve_default_created_by,
+    session_metadata_path,
     tmux_session_exists,
     unparented_delegation_warning,
 )
@@ -74,6 +76,7 @@ from .worktree import (
     register_worktree,
     remove_worktree,
     safe_worktree_name,
+    teardown_record_note,
     teardown_session_note,
     tmux_safe_name,
     worktree_session_name,
@@ -1686,6 +1689,7 @@ def _worktree_prune(args, project_path: Path, worktree_dir: Path, json_mode: boo
     gc_merged_out = []
     gc_refused = []
     gc_orphaned_tabs = []
+    gc_records = []
     gc_merged = getattr(args, 'gc_merged', False)
     for e in list(worktree_registry.entries(project_path)):
         wt_path = Path(e.get("worktree_path", ""))
@@ -1709,6 +1713,12 @@ def _worktree_prune(args, project_path: Path, worktree_dir: Path, json_mode: boo
                 )
                 if result["success"]:
                     gc_merged_out.append(e["session"])
+                    if result.get("record_left"):
+                        gc_records.append({
+                            "session": e["session"],
+                            "record_left": result["record_left"],
+                            "record_orphaned_ids": result["record_orphaned_ids"],
+                        })
                     for t in result.get("orphaned_tabs") or []:
                         gc_orphaned_tabs.append({**t, "session": e["session"]})
                 else:
@@ -1720,7 +1730,8 @@ def _worktree_prune(args, project_path: Path, worktree_dir: Path, json_mode: boo
                    capture_output=True)
     if json_mode:
         _output_json({"success": True, "pruned": removed, "gc_merged": gc_merged_out,
-                      "gc_refused": gc_refused, "orphaned_tabs": gc_orphaned_tabs})
+                      "gc_refused": gc_refused, "orphaned_tabs": gc_orphaned_tabs,
+                      "records_left": gc_records})
     else:
         for r in gc_refused:
             print(f"SKIPPED {r['session']}: {r['error']}")
@@ -1732,6 +1743,8 @@ def _worktree_prune(args, project_path: Path, worktree_dir: Path, json_mode: boo
                   f"{ids} — close via tabs_close_mcp")
         if gc_merged_out:
             print(f"GC'd {len(gc_merged_out)} merged worktree{'s' if len(gc_merged_out) != 1 else ''}: {', '.join(gc_merged_out)}")
+        for r in gc_records:
+            print(f"  {r['session']}: {teardown_record_note({**r})}")
         if not removed and not gc_merged_out and not gc_refused:
             print("Nothing to prune.")
     return 0
@@ -1961,6 +1974,29 @@ def _delete_branch_if_safe(
     return True, "merged" if not force else "forced"
 
 
+def _session_record_state(session_name: str) -> tuple[str | None, list[str]]:
+    """What teardown leaves behind: the record's path and its orphaned chain ids.
+
+    ``(None, [])`` when the session has no record. Read-only — teardown never
+    deletes the record (see ``agentwire history prune --dead``).
+    """
+    from .history import survey_chain
+
+    try:
+        path = session_metadata_path(session_name)
+    except ValueError:
+        return None, []
+    if not path.exists():
+        return None, []
+    metadata = load_session_metadata(session_name)
+    ids = list(metadata.get("conversation_ids") or [])
+    cwd = metadata.get("cwd_at_launch")
+    if not ids or not cwd:
+        return str(path.parent), []
+    _, orphans, _ = survey_chain(ids, cwd)
+    return str(path.parent), [loc.conversation_id for loc in orphans]
+
+
 def _teardown_entry(
     project_path: Path, worktree_dir: Path, session_name: str, worktree_path: Path,
     branch: str | None, base: str | None, *, keep_branch: bool = False, force_branch: bool = False,
@@ -2096,7 +2132,10 @@ def _teardown_entry(
     # that closed its own tabs and untracked them normally leaves nothing here.
     orphaned_tabs = chrome_tabs.clear(session_name)
 
+    record_left, record_orphaned_ids = _session_record_state(session_name)
+
     return {"success": True, "session": session_name, "path": str(worktree_path),
+            "record_left": record_left, "record_orphaned_ids": record_orphaned_ids,
             "killed": killed, "worktree_removed": worktree_existed,
             "worktree_existed": worktree_existed,
             "session_existed": session_existed,
@@ -2189,6 +2228,9 @@ def _worktree_remove(args, project_path: Path, worktree_dir: Path, json_mode: bo
             ids = ", ".join(t.get("tab_id", "?") for t in result["orphaned_tabs"])
             msg += (f"; WARNING: {len(result['orphaned_tabs'])} claude-in-chrome tab(s) never closed "
                     f"by this session: {ids} — close via tabs_close_mcp")
+        record_note = teardown_record_note(result)
+        if record_note:
+            msg += "; " + record_note
         print(msg)
     return 0 if result["success"] else 1
 

{agentwire_dev-1.80.0 → agentwire_dev-1.81.0}/agentwire/worktree.py

@@ -243,6 +243,26 @@ def teardown_session_note(result: dict) -> str:
     return f" (NO live tmux session named '{session}' — nothing killed)"
 
 
+def teardown_record_note(result: dict) -> str:
+    """Clause saying what teardown left in the session-record store.
+
+    Teardown never deletes ``~/.agentwire/sessions/<name>`` — the record is
+    the only map from session name to conversation — so it states that it is
+    still there, and whether its chain has orphaned entries. Empty when there
+    was no record (or the teardown did not complete).
+    """
+    record = result.get("record_left")
+    if not record:
+        return ""
+    session = result.get("session") or "?"
+    orphaned = result.get("record_orphaned_ids") or []
+    note = f"session record left at {record}"
+    if orphaned:
+        note += (f" (chain has {len(orphaned)} orphaned conversation(s) — "
+                 f"`agentwire history migrate --session {session}`)")
+    return note + "; drop with `agentwire history prune --dead --yes`"
+
+
 def ensure_worktree(
     project_path: Path,
     branch: str,

{agentwire_dev-1.80.0 → agentwire_dev-1.81.0}/docs/wiki/INDEX.md

@@ -77,6 +77,7 @@ Running AgentWire across machines and exposing the portal.
 Recon notes and evaluations that inform direction (not yet implemented).
 
 - **[Orchestration transport alternatives](research/orchestration-transport-alternatives.md)** — the "we don't use SSH" competitor pitch, evaluated: claims-vs-reality on faster/more-secure, and why the cheap wins are SSH `ControlMaster` multiplexing + a Tailscale mesh underlay rather than a new transport ([#297](https://github.com/dotdevdotdev/agentwire-dev/issues/297))
+- **[How AgentWire differs](research/orchestrator-comparison.md)** — sourced survey of Claude Squad, Conductor, Sculptor, Claude Code agent teams and Multica (license, platforms, isolation, what each does that the other doesn't; unverified claims marked) plus suggested borrows ([#1294](https://github.com/dotdevdotdev/agentwire-dev/issues/1294))
 - **[Briefing Mode feasibility](research/briefing-mode-feasibility.md)** — asymmetric-verbosity orchestration evaluation that informed the shipped Briefing Mode
 
 ## Voice (TTS & STT)

agentwire_dev-1.81.0/docs/wiki/research/orchestrator-comparison.md

@@ -0,0 +1,57 @@
+# How AgentWire differs from other multi-agent coding orchestrators
+
+> Research note for [#1294](https://github.com/dotdevdotdev/agentwire-dev/issues/1294), from the post-1.79 brainstorm ([#1275](https://github.com/dotdevdotdev/agentwire-dev/issues/1275)). Sourced from each project's own repository and docs, read 2026-11-05. Tools move fast: re-check before quoting. **Anything marked _unverified_ was not stated on a primary page.** This is a survey, not a roadmap; the borrow candidates at the end are suggestions, not work done.
+
+## Summary table
+
+| | Form | License | Platforms | Isolation |
+|---|---|---|---|---|
+| **AgentWire** | CLI + tmux + web portal + MCP | Apache-2.0 ([`LICENSE`](../../../LICENSE)) | macOS/Linux + tmux ([quickstart](../quickstart.md)) | git worktree per session, plus no-isolation helper sessions ([worktree sessions](../sessions/worktree-sessions.md), [helper sessions](../sessions/helper-sessions.md)) |
+| [Claude Squad](https://github.com/smtg-ai/claude-squad) | terminal TUI | AGPL-3.0 ([repo](https://github.com/smtg-ai/claude-squad)) | needs tmux and `gh`; OS list _unverified_ ([README](https://github.com/smtg-ai/claude-squad/blob/main/README.md)) | "isolated git workspace" per task; the source tree has [`session/git/worktree*.go`](https://github.com/smtg-ai/claude-squad/tree/main/session/git) |
+| [Conductor](https://www.conductor.build/) | desktop app | _unverified_ (not stated on the [homepage](https://www.conductor.build/) or [docs](https://www.conductor.build/docs/)) | Mac ("Run parallel coding agents on your Mac") | "own workspace, branch, files, terminal, diff, and review path"; mechanism (worktree or not) _unverified_ |
+| [Sculptor](https://github.com/imbue-ai/sculptor) | desktop app | MIT per the GitHub license field ([`LICENSE.md`](https://github.com/imbue-ai/sculptor/blob/main/LICENSE.md)); README says it is not yet truly open source and takes few outside contributions | Mac (Apple Silicon), Linux, Linux ARM64 ([README](https://github.com/imbue-ai/sculptor)) | default is a git worktree; clone and container modes are experimental ([workspaces](https://github.com/imbue-ai/sculptor/blob/main/docs/help/workspaces.md), [container backend](https://github.com/imbue-ai/sculptor/blob/main/docs/help/experimental/container_backend.md)) |
+| [Claude Code agent teams](https://code.claude.com/docs/en/agent-teams) | built into Claude Code | Claude Code's own terms; not an independent project | Any terminal for in-process; split panes need tmux or iTerm2 | none for teammates; the docs say "Break the work so each teammate owns a different set of files". Worktrees are a separate feature ([worktrees](https://code.claude.com/docs/en/worktrees.md)) |
+| [Multica](https://github.com/multica-ai/multica) | self-hostable web workspace + daemon + CLI | Apache-2.0 plus extra conditions (no hosted-service use, branding retention) ([`LICENSE`](https://github.com/multica-ai/multica/blob/main/LICENSE)); the README calls it "source-available" | web, desktop (macOS/Windows/Linux), mobile ([README](https://github.com/multica-ai/multica)) | agents run on "a runtime you control" (a daemon on your machine); per-task isolation mechanism _unverified_ |
+
+## Per tool
+
+### Claude Squad
+- **What:** "a terminal app that manages multiple Claude Code, Codex, Gemini (and other local agents including Aider) in separate workspaces" ([README](https://github.com/smtg-ai/claude-squad/blob/main/README.md)). Built on tmux and `gh`. Highlights: background tasks including auto-accept, and "Review changes before applying them, checkout changes before pushing them".
+- **Does that AgentWire does not:** a single-window TUI that lists every task and reviews its changes in place. Per the README, review happens inside the app.
+- **AgentWire does that it does not:** no sign in its README of voice, a web UI, remote machines, scheduled runs, a parent/child session model, report-back messaging, or a command safety layer. _Absence on a README page is not proof of absence in the code._
+
+### Conductor
+- **What:** "Run parallel coding agents on your Mac" with Claude Code, Codex and Cursor in isolated workspaces ([homepage](https://www.conductor.build/)). The [docs](https://www.conductor.build/docs/) describe a flow of workspace, diff viewer, checks, pull request, merge, archive.
+- **Does that AgentWire does not:** an integrated diff viewer and checks step per workspace, in a native app.
+- **AgentWire does that it does not:** runs off the Mac (Linux, remote machines over SSH), headless and scheduled work, and an agent-facing API (MCP). Pricing, license and the isolation mechanism were not stated on the pages read: _unverified_.
+
+### Sculptor (Imbue)
+- **What:** "a desktop app for running coding agents in parallel" ([README](https://github.com/imbue-ai/sculptor)). Workspace is "by default ... a git worktree"; harnesses are Claude Code and Pi, plus "any terminal-based agents". Experimental research preview.
+- **Does that AgentWire does not:** a Files panel with Browse, Changes and Commits tabs and per-file diffs ([changes](https://github.com/imbue-ai/sculptor/blob/main/docs/help/changes.md)); in-app PR opening and status tracking ([README doc index](https://github.com/imbue-ai/sculptor)); an experimental container or remote backend.
+- **AgentWire does that it does not:** tmux-resident sessions that outlive the UI, voice, channels, and the scheduler. Whether Sculptor has equivalents of the last three is _unverified_.
+
+### Claude Code agent teams
+- **What:** "Experimental and disabled by default" (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). One lead session, teammates that are separate Claude Code instances with a shared task list and a mailbox ([docs](https://code.claude.com/docs/en/agent-teams)).
+- **Does that AgentWire does not:** teammates message each other directly and self-claim tasks from a shared list with dependency tracking; hooks (`TeammateIdle`, `TaskCreated`, `TaskCompleted`) gate quality.
+- **AgentWire does that it does not:** per its stated limitations, there is "No session resumption with in-process teammates", "One team per session", "No nested teams", and teammates are not worktree-isolated. AgentWire sessions are durable tmux sessions that survive the parent, nest arbitrarily, and each worktree session has its own branch. In exchange, agent teams are first-party and need no extra install.
+
+### Multica
+- **What:** "a source-available workspace where you assign work to AI coding agents the way you'd assign it to a teammate": issue board, agents as assignees, Squads, Skills, Autopilots (cron), execution logs, usage analytics, review gates ([README](https://github.com/multica-ai/multica)). A different category: a project-management product with agents, not a terminal orchestrator.
+- **Does that AgentWire does not:** a board, issue assignment, multi-user workspaces and roles, per-run cost analytics, chat integrations (Slack and others), mobile apps. AgentWire ships no PM product by design.
+- **AgentWire does that it does not:** local-first terminal sessions you can attach to, voice, and a damage-control hook layer on every tool call. Whether Multica has an equivalent command guard is _unverified_.
+
+## Where AgentWire sits
+
+Taken together, the sourced differences are:
+
+- **Substrate:** AgentWire's unit is a tmux session addressable from CLI, portal, MCP and remote machines ([concepts](../concepts.md)). The desktop apps (Conductor, Sculptor) and the TUI (Claude Squad) are the UI.
+- **Topology:** parent/child sessions with report-back, fan-out cohorts and a fleet view ([fan-out cohorts](../sessions/fan-out-cohorts.md), [fleet](../sessions/fleet.md)). Claude Squad, Conductor and Sculptor present flat lists of workspaces in their READMEs and homepages; Multica's Squads are leader-routed agent groups.
+- **Safety:** every agent tool call passes through [damage control](../internals/damage-control.md). No other tool surveyed documents an equivalent on the pages read.
+- **What AgentWire is weaker at:** no first-party diff-review UI (below), no native desktop app, and a tmux dependency.
+
+## Worth borrowing (suggested issues, not work done)
+
+1. **Worktree diff-review panel in the portal.** Conductor (diff viewer + checks) and Sculptor (Changes tab with per-file diffs and a Commits tab) both put review next to the agent; Claude Squad reviews in-app too. AgentWire has the `agentwire diff -s <session> [--base] [--json]` CLI command but no portal panel. A per-session panel that calls it, with the Changes/Commits split Sculptor uses, would close the gap.
+2. **Checks surfaced beside the diff** (Conductor's docs list a "Checks" step after the diff viewer; contents _unverified_). Worth filing only if the panel above lands and CI status is not already visible there.
+
+Not on the list: carrying gitignored files into worktrees. Claude Code's [`.worktreeinclude`](https://code.claude.com/docs/en/worktrees.md#copy-gitignored-files-into-worktrees) does this and AgentWire already has `projects.worktrees.copy_files` ([architecture](../architecture.md)).

{agentwire_dev-1.80.0 → agentwire_dev-1.81.0}/docs/wiki/sessions/conversation-identity.md

@@ -291,6 +291,19 @@ carrying the new `session_id`) reports each change:
   because the tail is what restart reads as "current"). Already-last is a no-op,
   so it is idempotent and the launch's own id costs nothing. A session with no
   launch record is left alone: the hook never conjures a partial record.
+- **Only the session's own conversations count (#1289).** A headless
+  `claude -p` run from a pane (a worker's comparison or spike in a scratch dir)
+  inherits `$TMUX_PANE` and fires the same hook. Verified payload shape:
+  `{session_id, transcript_path, cwd, hook_event_name, source}` — `cwd` is the
+  physical path, and a headless run reports `source: "startup"`, identical to a
+  real start, so **`source` is no signal**; `cwd` is. The hook records an id
+  only when `core.session_owns_cwd` says the payload `cwd` (through
+  `history.encode_project_path` of the realpath) equals the recorded
+  `cwd_at_launch` or `worktree_path`. A mismatch, or a payload with no `cwd`,
+  is ignored and the reason goes to the debug log. Chains polluted before this
+  fix keep their stray ids (`restart` skips ids with no transcript under the
+  launch cwd, so they are inert there); `doctor`'s orphaned-history output
+  names nested runs as the likely cause.
 - Errors are logged to `/tmp/claude-hook-debug.log`, never raised.
 
 `restart`'s newest-first walk is unchanged: a `/clear`ed conversation that
@@ -353,7 +366,24 @@ else `cwd_at_launch` — which is what catches the case where the record and the
 transcript still agree with each other and are both stale because the directory
 moved underneath them.
 
-It scores orphans only. A conversation with no history *anywhere* is stated for
+It scores orphans of **live** sessions only (#1292). A session that is not
+running keeps its record under `~/.agentwire/sessions/` after
+`worktree --remove`, so its orphaned chain would otherwise stay red forever;
+doctor lists those as information with the recover command and does not count
+them. Teardown (`worktree --remove`, `--prune --gc-merged`) never deletes the
+record — it is the only map from session name to conversation — but says in its
+output that it left one, and how many of its chain's conversations are
+orphaned. To clean up deliberately:
+
+```bash
+agentwire history prune --dead                    # list dead-session records (deletes nothing)
+agentwire history prune --dead --older-than 14d   # only records untouched that long
+agentwire history prune --dead --yes              # delete exactly what was listed
+```
+
+`doctor`, teardown and `prune` share one chain probe, `history.survey_chain`.
+
+Orphans aside, a conversation with no history *anywhere* is stated for
 live sessions and never counted, because this check cannot say why it's missing
 — never-prompted and Claude-evicted look identical from here — and because
 scoring it would flag hundreds of dead records. Calibration, measured on a real

{agentwire_dev-1.80.0 → agentwire_dev-1.81.0}/pyproject.toml

@@ -29,7 +29,7 @@ dependencies = [
     # PyPI. Engine changes land there, release there, then raise this floor.
     # tests/unit/test_damage_control_pin.py checks the range and the installed engine.
     # Hooks run `python -I -m damage_control.hook`.
-    "damage-control-dev>=0.3.0,<0.4",
+    "damage-control-dev>=0.4.0,<0.5",
     "aiohttp>=3.13.4",  # >=3.13.4 clears CVE-2026-34515 + CVE-2026-34513 (portal-facing)
     "aiohttp-jinja2>=1.6",
     "jinja2>=3.1.0",