code-coordinator 0.5.236__tar.gz → 0.5.238__tar.gz

{code_coordinator-0.5.236 → code_coordinator-0.5.238}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.236
+Version: 0.5.238
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.236 → code_coordinator-0.5.238}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.236
+Version: 0.5.238
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.236 → code_coordinator-0.5.238}/code_coordinator.egg-info/SOURCES.txt

@@ -62,6 +62,7 @@ coord/conflict_fix.py
 coord/dao.py
 coord/db.py
 coord/dead_end.py
+coord/decomposition_chat.py
 coord/deploy_manifest.py
 coord/deploy_units.py
 coord/deps.py
@@ -478,6 +479,7 @@ tests/test_dashboard_terminal.py
 tests/test_dashboard_terminal_live.py
 tests/test_db.py
 tests/test_dead_end.py
+tests/test_decomposition_chat.py
 tests/test_deploy_coord_db_backup.py
 tests/test_deploy_coord_web_dist.py
 tests/test_deploy_coord_web_rollback.py

{code_coordinator-0.5.236 → code_coordinator-0.5.238}/code_coordinator.egg-info/scm_file_list.json

@@ -91,6 +91,7 @@
     "coord/dashboard/terminal.py",
     "coord/db.py",
     "coord/dead_end.py",
+    "coord/decomposition_chat.py",
     "coord/deploy/README.md",
     "coord/deploy/coord-agent.service",
     "coord/deploy/coord-db-backup.service",
@@ -550,6 +551,7 @@
     "tests/test_dashboard_terminal_live.py",
     "tests/test_db.py",
     "tests/test_dead_end.py",
+    "tests/test_decomposition_chat.py",
     "tests/test_deploy_coord_db_backup.py",
     "tests/test_deploy_coord_web_dist.py",
     "tests/test_deploy_coord_web_rollback.py",

{code_coordinator-0.5.236 → code_coordinator-0.5.238}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.236",
+  "tag": "0.5.238",
   "distance": 0,
-  "node": "g5110d914da8b0140bb620fbe356079028f405900",
+  "node": "g8d13a39e25627c1a4242ac04e7c279023d414a99",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-23"

{code_coordinator-0.5.236 → code_coordinator-0.5.238}/coord/agent.py

@@ -3643,6 +3643,112 @@ MILESTONE_CHAT_DENY_COMMANDS: list[str] = [
     "Bash(coord assign *)",
 ]
 
+DECOMPOSITION_CHAT_SYSTEM_PROMPT = """\
+You are a decomposition steward for a customer's APPROVED portal submission \
+that an operator just pulled into this session from the TUI's "Approved \
+work items" panel (#2533, ms-67 contract §4). Unlike `milestone-chat` above \
+(which proposes and waits for confirmation before writing anything), this \
+session's WHOLE JOB is to actually decompose the submission into real \
+coordinator work — there is no separate confirm-then-write step here \
+because pulling the row into this session already IS the operator's \
+confirmation.
+
+The first user message carries: the submission's OUTCOME, AUDIENCE, DONE \
+DEFINITION, and CONSTRAINTS (the four fields the customer described); its \
+mapped repo(s); and `coordinator.yml` topology context for those repo(s) \
+(depends_on, which machines claim each repo).
+
+Your job, in order:
+1. Decide whether this is ORACLE-LOOP-SHAPED work (docs/ORACLE_LOOP.md) — \
+big or cross-cutting enough to warrant a Gate-A contract + independent \
+test-author, or small enough to skip straight to normal dispatch. Discuss \
+this with the operator if it's not obvious; you don't need to wait for \
+explicit confirmation before filing, but flag your reasoning.
+2. Produce one or more GitHub issues describing the work, using:
+
+    coord issue create <repo> --title '<title>' --body '<body>'
+
+   (or `--body-file` for long markdown — never raw `gh issue create`, this \
+repo's own house rule). If the decomposition is milestone-shaped, file an \
+epic/tracking issue first (`coord milestone create <repo> --title '<title>'`) \
+and file the sub-issues, then `coord milestone add-child <repo> <epic> \
+<issue>` each of them onto it.
+3. Queue every filed issue via:
+
+    coord drive-queue add <repo> <issue>
+
+   — NEVER `coord assign` or `coord drive --tmux` (this repo's own standing \
+preference: always go through the drive queue, never ad-hoc dispatch).
+4. Record the portal link so downstream tooling can find this submission's \
+work again (2026-08-22 briefing amendment — this is NOT optional):
+
+    coord portal link <repo> <milestone_number> <submission_id>
+
+   Use the SUBMISSION_ID from your first user message and the milestone \
+number `coord milestone create` printed. If `coord portal link` fails (bad \
+repo, bad milestone number, daemon-host guard), that is a FAILURE of this \
+step — say so explicitly to the operator, do not silently move on.
+
+   **If your decomposition produced a single one-off issue with no \
+milestone/epic** (not a milestone-shaped decomposition): `coord portal \
+link` has NO non-milestone form today — it requires a `milestone_number`, \
+which a one-off issue doesn't have. Do NOT invent one or skip the link \
+silently. Say so explicitly in your final summary to the operator (e.g. \
+"this submission has no recorded portal link — coord portal link only \
+covers milestones, and #2533's own dispatcher found no equivalent for a \
+one-off issue"), so the gap is visible rather than silently lost.
+
+Rules:
+- Do NOT run raw `gh issue create`/`gh issue edit`/`gh pr *`/`gh api -X \
+POST|PATCH|DELETE` or any other mutating `gh` command — the write paths \
+above (`coord issue create`, `coord milestone create/add-child`, `coord \
+drive-queue add`, `coord portal link`) are the only ones you may use.
+- Do NOT run `coord assign <machine> <repo> <issue>` or `coord drive \
+--tmux` — always `coord drive-queue add`.
+- Do NOT run `coord approve` or `coord merge` — outside this session's job.
+- Do NOT run `git push`, `git commit`, or any command that writes to a repo \
+checkout — this session files issues and queues work, it does not touch code.
+- Keep the operator informed: summarize your decomposition plan before \
+filing, and report back what you filed/queued/linked (and any link gap) \
+when done.\
+"""
+
+# Deny list applied to decomposition-chat workers (#2533). Unlike
+# milestone-chat, this type's WHOLE job is to write (issue create /
+# milestone create+add-child / drive-queue add / portal link), so this list
+# is deliberately narrow — it blocks raw `gh` mutations, repo-write git
+# commands, destructive git ops, and the three unrelated `coord` write
+# commands (approve/merge/assign) explicitly out of scope, while every write
+# path this session actually needs (`coord issue create`, `coord milestone
+# create`/`add-child`, `coord drive-queue add`, `coord portal link`) is
+# allowed by omission.
+DECOMPOSITION_CHAT_DENY_COMMANDS: list[str] = [
+    "Bash(gh issue edit *)",
+    "Bash(gh issue create *)",
+    "Bash(gh issue delete *)",
+    "Bash(gh issue close *)",
+    "Bash(gh api -X PATCH *)",
+    "Bash(gh api -X POST *)",
+    "Bash(gh api -X DELETE *)",
+    "Bash(gh pr *)",
+    "Bash(gh repo *)",
+    "Bash(gh milestone *)",
+    "Bash(git push *)",
+    "Bash(git commit *)",
+    "Bash(git reset --hard *)",
+    "Bash(git reset * --hard *)",
+    "Bash(git branch -D *)",
+    "Bash(git branch * -D *)",
+    "Bash(git checkout -- .)",
+    "Bash(git clean -f *)",
+    "Bash(git clean * -f *)",
+    "Bash(rm -rf *)",
+    "Bash(rm -fr *)",
+    "Bash(coord approve *)",
+    "Bash(coord merge *)",
+    "Bash(coord assign *)",
+]
+
 MOCK_AUTHOR_SYSTEM_PROMPT = """\
 You are an independent mock-author agent for Gate A of a milestone \
 (#930, docs/ORACLE_LOOP.md) — the pre-work architecture gate. You have \
@@ -4238,6 +4344,20 @@ def default_worker_command(spec: AssignmentSpec, *, binary: str = DEFAULT_WORKER
         system_prompt = spec.system_prompt if spec.system_prompt else MILESTONE_CHAT_SYSTEM_PROMPT
         system_prompt += build_deny_prompt(MILESTONE_CHAT_DENY_COMMANDS)
         allowed_tools = "Read,Bash"
+    elif spec.type == "decomposition-chat":
+        # #2533 (ms-67 contract §4c): pull an approved portal submission
+        # into a briefed session that decides oracle-loop-shaped-or-not,
+        # files issue(s) via `coord issue create`, queues them via `coord
+        # drive-queue add`, and records `coord portal link` — a mutating
+        # chat type like milestone-chat above, with its own narrow deny
+        # list (see DECOMPOSITION_CHAT_DENY_COMMANDS) rather than
+        # new-issue-chat's blanket one, since this session's whole job is
+        # to write via those specific `coord` commands.
+        system_prompt = (
+            spec.system_prompt if spec.system_prompt else DECOMPOSITION_CHAT_SYSTEM_PROMPT
+        )
+        system_prompt += build_deny_prompt(DECOMPOSITION_CHAT_DENY_COMMANDS)
+        allowed_tools = "Read,Bash"
     elif spec.type == "mock-author":
         # #930 (docs/ORACLE_LOOP.md, Gate A): an independent mock-author
         # agent renders a viewable mock + writes `contract.md` under
@@ -4435,12 +4555,17 @@ def _user_message_line(text: str) -> bytes:
 # a non-closes-issue original (test-author/mock-author/...) — it gets a
 # worktree and runs `gh pr create`, the same GitHub-mutating shape as
 # `type="work"` had before #1142 gave it its own type, so it must stay here.
+# ``decomposition-chat`` (#2533) is a chat too — no git worktree — but its
+# whole job is to mutate GitHub (`coord issue create` / `coord milestone
+# create`/`add-child`) and the drive queue (`coord drive-queue add`), the
+# same "no worktree, but real mutation" shape ``milestone-chat`` has above.
 WRITE_CAPABLE_SPEC_TYPES: frozenset[str] = frozenset({
     "work",
     "review",
     "smoke",
     "conflict-fix",
     "milestone-chat",
+    "decomposition-chat",
     "mock-author",
     "test-author",
     "pr-helper",

{code_coordinator-0.5.236 → code_coordinator-0.5.238}/coord/commands/portal.py

@@ -284,6 +284,56 @@ def portal_link(
     )
 
 
+# ── #2533 (ms-67 PB-3): pull an approved submission into a decomposition chat ──
+
+
+@portal_group.command("decompose-chat")
+@_CONFIG_OPTION
+@click.argument("submission_id")
+@click.option(
+    "--machine",
+    "machine_override",
+    default=None,
+    help="Force a specific machine (must claim every repo the submission maps to).",
+)
+def portal_decompose_chat(config_path, submission_id: str, machine_override: str | None) -> None:
+    """Dispatch a ``type="decomposition-chat"`` session for SUBMISSION_ID (#2533).
+
+    The TUI's "Pull into decomposition session" action (ms-67 contract §4a/
+    §4c) shells this out, exactly the way `coord new-issue-chat` / `coord
+    milestone chat` already work — prints the new assignment id to stdout,
+    which the TUI binds a `ChatController` overlay to once it appears in the
+    board poll.
+
+    Briefs the session with SUBMISSION_ID's outcome / audience / done-
+    definition / constraints, its mapped repo(s), and `coordinator.yml`
+    topology context for those repo(s) (:mod:`coord.decomposition_chat`).
+    The session's own job — deciding whether the work is oracle-loop-shaped,
+    filing issue(s) via `coord issue create`, queueing them via `coord
+    drive-queue add`, and recording `coord portal link` — is described in its
+    system prompt (`coord.agent.DECOMPOSITION_CHAT_SYSTEM_PROMPT`), not here.
+
+    Reads through :func:`coord.approved_work.approved_submissions`, which
+    (like every other portal-bridge reader) resolves state out of this
+    machine's own ``~/.coord/coord.db`` — a daemon-host command, same as
+    ``link``/``publish-mocks`` above.
+    """
+    _refuse_if_thin_client("decompose-chat")
+
+    from coord.decomposition_chat import dispatch_decomposition_chat
+
+    cfg = _load_config(config_path)
+    try:
+        assignment_id, machine = dispatch_decomposition_chat(
+            submission_id, cfg, machine_override=machine_override
+        )
+    except RuntimeError as exc:
+        click.secho(f"error: {exc}", fg="red")
+        raise SystemExit(1) from exc
+    click.echo(assignment_id)
+    click.echo(f"# dispatched to {machine}", err=True)
+
+
 # ── #2513 (PDR-5): manual "publish mocks to portal" ─────────────────────────
 
 

{code_coordinator-0.5.236 → code_coordinator-0.5.238}/coord/db.py

@@ -69,10 +69,22 @@ def _open(path: Path) -> sqlite3.Connection:
     conn.execute("PRAGMA busy_timeout=5000")
     conn.execute("PRAGMA foreign_keys=ON")
     conn.row_factory = sqlite3.Row
-    _ensure_schema(conn)
-    _maybe_migrate_json(conn)
-    _migrate_gate_order(conn)
-    _backfill_orphaned_review_verdicts(conn)
+    # #2598: _ensure_schema/_maybe_migrate_json/_migrate_gate_order/
+    # _backfill_orphaned_review_verdicts are convergent one-time operations,
+    # not per-open invariants — but every one of them ran unconditionally on
+    # every process's DB open, so a read-only command (`coord status`) began
+    # a write transaction (and, for the unconstrained schema_version table,
+    # left a junk row behind — 45,708 of them observed in the field) purely
+    # to open a connection it only ever intended to read from. Gate the
+    # whole block on a cheap read-only version check: a database already at
+    # _DB_SCHEMA_VERSION does none of this work, so opening it issues no
+    # write at all. See _read_schema_version's docstring for why this read
+    # is correct against both the pre-#2598 and post-#2598 table shapes.
+    if _read_schema_version(conn) < _DB_SCHEMA_VERSION:
+        _ensure_schema(conn)
+        _maybe_migrate_json(conn)
+        _migrate_gate_order(conn)
+        _backfill_orphaned_review_verdicts(conn)
     return conn
 
 
@@ -143,13 +155,94 @@ def retry_on_locked(
 
 # ── Schema ────────────────────────────────────────────────────────────────────
 
+# #2598: bumped from the original unversioned "1" written by every process
+# forever. Read by _read_schema_version()/_open() as the target a database
+# must reach before _open() can skip its write path entirely. Whoever adds
+# the NEXT one-shot migration (another _migrate_* or _backfill_* function
+# meant to run once per database, not once per process) must bump this too
+# — otherwise an already-caught-up database (version == _DB_SCHEMA_VERSION)
+# will never run it, because the whole write path is gated on this compare.
+_DB_SCHEMA_VERSION = 2
+
+
+def _read_schema_version(conn: sqlite3.Connection) -> int:
+    """Cheap, read-only probe of how caught-up *conn*'s database is (#2598).
+
+    A plain ``SELECT`` — never begins a write transaction, so calling this
+    to decide whether _open() needs to do any write work cannot itself take
+    the write lock.
+
+    Returns 0 when ``schema_version`` doesn't exist yet (brand-new database)
+    or is empty. Otherwise returns the highest stored value, which reads
+    correctly against *either* table shape: the pre-#2598 unconstrained
+    table (every row holds the same value, so MAX is that value — junk rows
+    don't change the answer) or the post-#2598 constrained table (exactly
+    one row). A pre-#2598 database therefore reads as version 1, which is
+    ``< _DB_SCHEMA_VERSION`` (2) — so it takes the write path exactly once
+    more, which is what collapses its schema_version duplicates and applies
+    the PRIMARY KEY (see _fix_schema_version_table). Every open after that
+    reads 2 and skips the write path entirely.
+    """
+    try:
+        row = conn.execute("SELECT MAX(version) FROM schema_version").fetchone()
+    except sqlite3.OperationalError:
+        return 0  # table doesn't exist yet
+    if row is None or row[0] is None:
+        return 0
+    return int(row[0])
+
+
+def _fix_schema_version_table(conn: sqlite3.Connection) -> None:
+    """Collapse the pre-#2598 unconstrained ``schema_version`` table.
+
+    The original table declared no ``PRIMARY KEY``/``UNIQUE`` constraint, so
+    ``INSERT OR IGNORE INTO schema_version VALUES (1)`` — meant to be a
+    once-per-database no-op — actually succeeded on every single process
+    open, leaving one junk row per open (45,708 observed in the field).
+    This rebuilds the table with a real ``PRIMARY KEY`` on ``version`` so
+    that no longer happens, collapsing any existing duplicate rows down to
+    their distinct values in the process.
+
+    Safe to call against any existing shape: the old broken table (any
+    number of duplicate rows, no constraint), the new constrained table
+    (already migrated — a no-op), or no table at all (fresh database).
+    """
+    row = conn.execute(
+        "SELECT sql FROM sqlite_master WHERE type='table' AND name='schema_version'"
+    ).fetchone()
+    if row is not None and "PRIMARY KEY" in (row[0] or ""):
+        return  # already the constrained post-#2598 shape
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL);
+        CREATE TABLE schema_version_new (version INTEGER PRIMARY KEY);
+        INSERT OR IGNORE INTO schema_version_new
+            SELECT DISTINCT version FROM schema_version;
+        DROP TABLE schema_version;
+        ALTER TABLE schema_version_new RENAME TO schema_version;
+        """
+    )
+    conn.commit()
+
+
+def _set_schema_version(conn: sqlite3.Connection, version: int) -> None:
+    """Overwrite ``schema_version`` with a single row holding *version*.
+
+    ``schema_version`` holds exactly one fact — how caught-up this database
+    is — so a version bump DELETEs the old row rather than accumulating one
+    row per version ever seen (which ``INSERT OR IGNORE``/``INSERT OR
+    REPLACE`` would do here, since they only dedupe on a *matching* primary
+    key, and a version bump's whole point is that the key changes).
+    """
+    conn.execute("DELETE FROM schema_version")
+    conn.execute("INSERT INTO schema_version (version) VALUES (?)", (version,))
+    conn.commit()
+
+
 def _ensure_schema(conn: sqlite3.Connection) -> None:
     """Create all tables and indexes if they don't already exist."""
+    _fix_schema_version_table(conn)
     conn.executescript("""
-        CREATE TABLE IF NOT EXISTS schema_version (
-            version INTEGER NOT NULL
-        );
-
         CREATE TABLE IF NOT EXISTS assignments (
             assignment_id TEXT PRIMARY KEY,
             machine_name TEXT NOT NULL,
@@ -686,13 +779,12 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
             ON portal_outbox(state, submission_id, seq);
         CREATE INDEX IF NOT EXISTS idx_portal_events_submission
             ON portal_events(submission_id);
-
-        INSERT OR IGNORE INTO schema_version VALUES (1);
     """)
     conn.commit()
     # Column-level migrations for existing databases.  SQLite does not support
     # "ADD COLUMN IF NOT EXISTS", so we catch OperationalError instead.
     _migrate_add_columns(conn)
+    _set_schema_version(conn, _DB_SCHEMA_VERSION)
 
 
 def _migrate_add_columns(conn: sqlite3.Connection) -> None:

code_coordinator-0.5.238/coord/decomposition_chat.py

@@ -0,0 +1,260 @@
+"""#2533 (ms-67 contract §4c): dispatch a `type="decomposition-chat"` session
+for "Pull into decomposition session" — the TUI action that turns an
+Approved-work-items row (a signed-off portal submission) into a briefed
+`claude -p` chat whose job is to decide whether the work is oracle-loop-shaped,
+file the resulting GitHub issue(s) via `coord issue create`, and queue them via
+`coord drive-queue add`.
+
+Used by `coord portal decompose-chat <submission_id>` (the CLI command the
+TUI shells out to, mirroring `coord new-issue-chat` / `coord milestone chat`
+— see `coord/new_issue_chat.py` / `coord/milestone_dispatch.py` for the two
+precedents this module follows).
+
+**Reads through the existing bridge, never a new direct portal read**
+(#2533's own briefing): the submission's four briefing fields (outcome /
+audience / done-definition / constraints) plus its server-resolved mapped
+repo(s) come from :func:`coord.approved_work.approved_submissions` — the same
+function that already serves the TUI's `/board` `approved_submissions` block
+(#2532) — rather than re-deriving them from `coord.portal_store` directly.
+
+**Machine selection is generalized to every mapped repo** (contract §4c):
+unlike :func:`coord.new_issue_chat.pick_new_issue_chat_machine` (one repo),
+a submission can map to more than one repo, and the picked machine must be
+able to work on ALL of them — a session that can only reach some of the
+repos it's meant to decompose into is worse than refusing outright. §6.7
+flags this as a genuinely open question the contract does not resolve beyond
+"refuse clearly" — this module's refusal is a plain `RuntimeError`, same
+posture every other dispatcher in this file already uses.
+"""
+from __future__ import annotations
+
+import time
+import uuid
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from coord.config import Config
+    from coord.models import Machine
+
+#: Sentinel `issue_title` this module writes onto the dispatched assignment
+#: — mirrors `dispatch_new_issue_chat`'s own `"(new issue draft)"` sentinel
+#: for a chat type with no real GitHub issue yet. The TUI's own bind path
+#: (`tui/src/app/dialogs.rs::maybe_bind_pending_decomposition_chat`) matches
+#: on this exact string (with the submission id substituted in) since
+#: `Assignment` carries no `submission_id` column of its own — see that
+#: function's doc comment for why this is the module's own choice, not
+#: something #2533's contract pins.
+def _issue_title(submission_id: str) -> str:
+    return f"decomposition: {submission_id}"
+
+
+def pick_decomposition_chat_machine(cfg: "Config", repos: list[str]) -> "Machine | None":
+    """Pick a machine that can work on EVERY repo in *repos*.
+
+    Contract §4c: "the picked machine must list **all** of the submission's
+    mapped repos ... not just one." Returns the first unpaused machine
+    satisfying `m.can_work_on(r)` for every `r` in *repos*. `None` when
+    *repos* is empty (nothing to route) or no single machine covers them
+    all — callers must treat `None` as a hard refusal, never fall back to a
+    partial match.
+    """
+    from coord.machine_pause import paused_set
+
+    if not repos:
+        return None
+    paused = paused_set(cfg.machines)
+    for m in cfg.machines:
+        if m.name in paused:
+            continue
+        if all(m.can_work_on(r) for r in repos):
+            return m
+    return None
+
+
+def _repo_topology_context(cfg: "Config", repos: list[str]) -> str:
+    """One paragraph of `coordinator.yml` topology per mapped repo — the
+    "coordinator.yml topology context ... the same way docs/CUSTOMER_PORTAL.md's
+    design-round step already uses it" #2533's own body asks for.
+
+    No design-round dispatcher exists yet to copy a wire shape from (flagged
+    in ms-67 contract.md §5's own notes as a proposal, not a read-off-the-
+    schema fact) — this is this module's own reasonable rendering: the
+    repo's GitHub slug, its `depends_on`, and which configured machines
+    claim it.
+    """
+    lines: list[str] = []
+    for repo_name in repos:
+        repo_cfg = cfg.repo(repo_name)
+        if repo_cfg is None:
+            lines.append(f"- {repo_name}: (not found in coordinator.yml — check the mapping)")
+            continue
+        machines = [m.name for m in cfg.machines if m.can_work_on(repo_name)]
+        depends = ", ".join(repo_cfg.depends_on) if repo_cfg.depends_on else "(none)"
+        lines.append(
+            f"- {repo_cfg.name} ({repo_cfg.github}): depends_on={depends}; "
+            f"machines={', '.join(machines) if machines else '(none configured)'}"
+        )
+    return "\n".join(lines) if lines else "(no mapped repos)"
+
+
+def build_decomposition_chat_briefing(
+    *,
+    submission: dict[str, Any],
+    topology_context: str,
+) -> str:
+    """Compose the seed briefing the worker sees as its first user message.
+
+    Carries exactly the four submission fields #2533's own body names
+    (outcome / audience / done-definition / constraints) plus the mapped
+    repo(s) and `coordinator.yml` topology context — identical substance to
+    what the Approved-work-items detail pane already shows the operator
+    (ms-67 contract §4b: "nothing hidden between 'looks right in the panel'
+    and 'is what the session got'").
+    """
+    submission_id = submission.get("submission_id", "")
+    repos = submission.get("repos") or []
+    parts: list[str] = []
+    parts.append(f"=== Decomposition chat context for submission {submission_id} ===\n")
+    parts.append(f"Client: {submission.get('client', '')}")
+    parts.append(
+        f"Project: {submission.get('project_id', '')} ({submission.get('project_label', '')})"
+    )
+    parts.append("")
+    parts.append("OUTCOME:")
+    parts.append(submission.get("outcome", "") or "(none provided)")
+    parts.append("")
+    parts.append("AUDIENCE:")
+    parts.append(submission.get("audience", "") or "(none provided)")
+    parts.append("")
+    parts.append("DONE DEFINITION:")
+    parts.append(submission.get("done_definition", "") or "(none provided)")
+    parts.append("")
+    parts.append("CONSTRAINTS:")
+    parts.append(submission.get("constraints", "") or "(none provided)")
+    parts.append("")
+    parts.append(f"MAPPED REPO(S): {', '.join(repos) if repos else '(none)'}")
+    parts.append("")
+    parts.append("COORDINATOR.YML TOPOLOGY CONTEXT:")
+    parts.append(topology_context)
+    parts.append("")
+    parts.append("---")
+    parts.append(
+        "Decide whether this is oracle-loop-shaped work (docs/ORACLE_LOOP.md) "
+        "or small enough to skip straight to normal dispatch, then produce one "
+        "or more GitHub issues via `coord issue create` and queue them via "
+        "`coord drive-queue add`. Once queued, record the portal link via "
+        "`coord portal link` — see your system prompt for the exact command "
+        "and the one-off-issue caveat."
+    )
+    return "\n".join(parts)
+
+
+def dispatch_decomposition_chat(
+    submission_id: str,
+    config: "Config",
+    *,
+    machine_override: str | None = None,
+) -> tuple[str, str]:
+    """End-to-end: look up *submission_id*, pick a machine, seed the
+    briefing, dispatch a ``type="decomposition-chat"`` assignment. Returns
+    ``(assignment_id, machine_name)``.
+
+    Raises ``RuntimeError`` when the submission isn't a currently-approved
+    one, has no mapped repo, no machine claims every mapped repo (or the
+    forced ``machine_override`` doesn't), or the agent rejects the dispatch.
+    """
+    from coord.approved_work import approved_submissions
+
+    rows = approved_submissions(config)
+    submission = next((r for r in rows if r.get("submission_id") == submission_id), None)
+    if submission is None:
+        raise RuntimeError(
+            f"submission {submission_id!r} is not a currently-approved portal "
+            "submission (coord.approved_work.approved_submissions) — nothing to decompose"
+        )
+
+    repos: list[str] = submission.get("repos") or []
+    if not repos:
+        raise RuntimeError(
+            f"submission {submission_id!r} has no mapped repo (portal.project_repos "
+            "in coordinator.yml) — map its project before pulling it into a "
+            "decomposition session"
+        )
+
+    if machine_override:
+        machine = next((m for m in config.machines if m.name == machine_override), None)
+        if machine is None:
+            raise RuntimeError(f"machine {machine_override!r} not in coordinator.yml")
+        missing = [r for r in repos if not machine.can_work_on(r)]
+        if missing:
+            raise RuntimeError(
+                f"machine {machine_override!r} does not list repo(s) "
+                f"{', '.join(missing)} — submission {submission_id!r} maps to "
+                f"{', '.join(repos)}, all of which the target machine must claim"
+            )
+    else:
+        picked = pick_decomposition_chat_machine(config, repos)
+        if picked is None:
+            raise RuntimeError(
+                f"no single machine claims every repo submission {submission_id!r} "
+                f"maps to ({', '.join(repos)}) — decomposition-chat refuses rather "
+                "than dispatching a session that can't reach all of them "
+                "(ms-67 contract §4c/§6.7)"
+            )
+        machine = picked
+
+    topology_context = _repo_topology_context(config, repos)
+    briefing = build_decomposition_chat_briefing(
+        submission=submission, topology_context=topology_context
+    )
+
+    resolved_model = config.models.default
+    from coord.models import Assignment, Proposal
+
+    proposal = Proposal(
+        id=0,
+        machine_name=machine.name,
+        repo_name=repos[0],
+        # No existing issue yet — same 0 sentinel `new-issue-chat` uses.
+        issue_number=0,
+        issue_title=_issue_title(submission_id),
+        rationale="decomposition-chat",
+        briefing=briefing,
+        model=resolved_model,
+        type="decomposition-chat",
+        required_gates=[],
+    )
+
+    from coord.dispatch import dispatch_with_retry
+    from coord.state import record_dispatched_assignment
+
+    response = dispatch_with_retry(
+        proposal,
+        config,
+        max_retries=config.concurrency.max_retries,
+        backoff_base=config.concurrency.backoff_base,
+    )
+
+    assignment_id = response.get("id") or uuid.uuid4().hex[:12]
+
+    repo_cfg = config.repo(repos[0])
+    asg = Assignment(
+        machine_name=machine.name,
+        repo_name=repos[0],
+        issue_number=0,
+        issue_title=_issue_title(submission_id),
+        files_allowed=[],
+        files_forbidden=[],
+        briefing=briefing,
+        assignment_id=assignment_id,
+        status="running",
+        dispatched_at=time.time(),
+        type="decomposition-chat",
+        model=resolved_model,
+    )
+    record_dispatched_assignment(
+        assignment=asg,
+        repo_github=repo_cfg.github if repo_cfg is not None else repos[0],
+    )
+
+    return assignment_id, machine.name