[feature] v11 migration — room protocol substrate (rooms/messages/decisions + sync_rooms() + /rooms dashboard)

[JayantDevkar]

Context

Extending karma to serve as the durable substrate for agent-coord, a new multi-agent coordination product. Instead of standing up a standalone decision store, we reuse karma's single-DB + existing indexer + existing dashboard primitives. Integration contract was answered in docs/features/2026-04-24-karma-integration-answers.md (this repo).

Updated 2026-04-24 after a senior-designer review pass on the agent-coord design. The body below is authoritative; earlier comments on this issue contain the deltas that led to these updates. Key post-review deltas baked in: decision mirror columns renamed for external-system pluggability, agent_presence has an explicit @human row via is_human column, agent-coord layer references renumbered to the 5-layer model.

What I'm asking for — three independently mergeable pieces

1. v10 → v11 schema migration

Five new tables (no collisions with existing schema; none of these concepts exist in karma today per the integration answers §Q2, §Q10):

• room — PK id (external ticket id, e.g. Linear LIN-4821 or GitHub owner/repo#N), title, status, created_at, closed_at?
• agent_presence — FK room.id, agent_id ("{repo}:{branch}" for Claude sessions; literal "human" for the director — stable across commits AND across session restarts; not keyed on session_uuid), repo (NULL for human), branch (NULL for human), session_uuid (FK sessions.uuid; NULL for human), is_human BOOLEAN NOT NULL DEFAULT false, joined_at, joined_at_commit (NULL for human), last_seen_at_commit (NULL for human), left_at?
• message — PK id UUID v7, FK room.id, thread_id?, in_reply_to?, from_agent_id, to_agents JSON, mentions_attempted JSON, type, body (TEXT or JSON for type=decision), confidence, schema_version, created_at
• citation — PK, FK message.id, urn, node_kind, resolved_at_commit, retrieved_via; UNIQUE(message_id, urn)
• decision — PK id UUID v7, FK room.id, FK message.id question_id, FK message.id answer_id, body, made_by, confidence, valid_from, valid_until?, FK decision.id superseded_by?, status, mirror_state (pending / synced / failed), mirror_attempts, mirror_last_error?, external_system TEXT NOT NULL DEFAULT 'linear' (enum-ish: linear / github / jira / …), external_ref_id? (comment/issue id in external system; NULL until synced), external_ref_url? (cached URL for dashboard rendering)

Written as an idiomatic idempotent migration in api/db/schema.py (append v11 block, bump SCHEMA_VERSION). All IDs are UUID v7.

On INSERT INTO room, also insert the synthetic @human presence row:

INSERT OR IGNORE INTO agent_presence (
  agent_id, room_id, repo, branch, session_uuid,
  is_human, joined_at
) VALUES (
  'human', ?room_id, NULL, NULL, NULL,
  true, CURRENT_TIMESTAMP
);

This lets every consumer (dashboard, escalation rules, reconciler) query SELECT * FROM agent_presence WHERE room_id = ? and get a complete roster without special-casing the human. Without this row, every consumer has to UNION ALL SELECT 'human' which is a papercut that compounds.

2. sync_rooms() indexer module

New module under api/db/ parallel to the existing session indexer. Reads append-only JSONL files at ~/.claude/rooms/<ticket>/messages.<agent_id>.jsonl (one file per agent per room — matches karma's one-writer-per-JSONL idiom).

Invocation: primarily hook-triggered via UserPromptSubmit (called from the agent's Claude Code hook); secondarily via the 300s polling timer in api/main.py as a safety net.

Ingest semantics:

• Parse JSONL lines, validate schema_version, merge across per-agent files sorted by (created_at, id).
• Per message: INSERT OR IGNORE INTO message (id, ...) keyed on UUID v7 — idempotent replay.
• For type=decision messages: wrap message INSERT + decision INSERT in a single transaction.
• Track last_indexed_message_id per room JSONL file for O(tail) resume on restart.
• Enforce citation requirement at ingest (not speak-time): reject type=answer messages lacking ≥1 stable-URN citation; write a type=status response back into the room.
• Evaluate escalation rules in the same ingest pass (three if-statements: explicit @human, implicit all-unsure, time-based NOW() - MAX(created_at) > N). No separate worker.

3. /rooms dashboard page in SvelteKit frontend

Per integration answers §Q6: ~700 LOC, ~1–2 days leveraging existing component library (PageHeader, StatsGrid, FilterControls, etc.). Three files:

• routes/rooms/+page.svelte — list view, filtering, search
• routes/rooms/+page.server.ts — data loader
• Nav link added to lib/components/Header.svelte

Also: routes/rooms/[id]/+page.svelte for a single-room timeline view (can ship as follow-up if the estimate expands).

External-mirror reconciler (out of scope for this PR; flagged for awareness)

Once decision rows exist, a reconciler (separate module, can ship in a follow-up PR) reads WHERE mirror_state = 'pending', dispatches on external_system, and POSTs a ticket/issue comment with a hidden HTML marker <!-- decision:$id --> for idempotency. MVP backend is linear; github would use the same marker pattern, just a different API endpoint. No schema migration to add new backends.

Why this matters

Multi-repo tickets currently force users to relay prose manually between Claude sessions (15–30 copy-pastes per Airflow-DAG-shaped ticket). agent-coord eliminates the relay via structured, grounded messages. karma is the durable substrate because:

• Single global SQLite already exists — no new infra
• Existing migration idiom accepts append-only additions cleanly
• Existing dashboard gets free rendering for a new entity type
• Session identity (sessions.uuid) is already stable and reusable

karma SQLite is the authoritative read surface. JSONL is the write-log / durability seam only — consumers (dashboard, reconciler, escalation rules) always read from karma.

Acceptance criteria

• Schema v11 migration applies idempotently on existing databases
• agent_presence has is_human column; synthetic @human row inserted on room creation
• decision has external_system, external_ref_id, external_ref_url columns (no linear_comment_id)
• sync_rooms() ingests a test JSONL file and produces expected rows, idempotent on replay
• Hook-triggered invocation works from a minimal shell harness
• Citation requirement enforced at ingest for type=answer
• Escalation rules (explicit / all-unsure / time-based) evaluated in the same ingest pass
• /rooms route renders a room's message timeline with in_reply_to + pins cross-links
• Existing session indexer, dashboards, and tests remain unaffected

Parent tracker

JayantDevkar/git-radio#3

Reference (design, lives in git-radio)

docs/agent-coord/proposal.md:

• §4 (architecture, per-agent JSONL transport, karma as authoritative read surface)
• §5 L1 (participants & routing; @human row, addressing grammar)
• §5 L2 (message schema with UUID v7)
• §5 L4 (delivery, attention & escalation — fail-open hook contract + escalation rules)
• §5 L5 (closure — atomic message+decision INSERT; external-system reconciler)
• §6 (decision schema with external_* columns)
• §7 (MVP boundary)
• §8 (full message-by-message walkthrough with real SQL)

docs/agent-coord/system-design.md has Mermaid diagrams (component map, 5-layer stack, message lifecycle, state machines, end-to-end walkthrough).

Branch: claude/review-agent-coordination-docs-7IPKY.

[JayantDevkar]

Two small schema adjustments — please fold in before implementation

Following a senior-designer review of the agent-coord layer model (design docs updated on claude/review-agent-coordination-docs-7IPKY in JayantDevkar/git-radio), two small changes to the schema proposed in the original issue. Both are net-additive and don't alter the three-piece work breakdown.

Adjustment 1 — decision mirror columns renamed for pluggability

Originally proposed linear_comment_id (Linear-specific). Rename to external-system neutral so v2 adds GitHub Issues / Jira / etc. without a migration.

Change in the decision table:

• Remove: linear_comment_id TEXT NULL
• Add:
  • external_system TEXT NOT NULL DEFAULT 'linear' — enum-ish: linear / github / jira / …
  • external_ref_id TEXT NULL — comment/issue id in the external system
  • external_ref_url TEXT NULL — cached URL for dashboard rendering

The reconciler dispatches on external_system; MVP ships the linear backend only. Reasoning: we're running this very design conversation on GitHub Issues, and Linear-as-the-only-mirror was a tightening that didn't survive contact with our own workflow. Renaming now costs ~3 extra lines in the v11 migration; renaming post-ship costs a migration on a PK-adjacent column.

Adjustment 2 — synthetic @human presence row

@human is a first-class participant in agent-coord (escalation rules route to it, dashboard shows it in the roster). Today the schema implies it's implicit, which forces every consumer to special-case "who's in this room." Cheaper to treat it as an explicit roster row.

Change in the agent_presence table:

• Add column is_human BOOLEAN NOT NULL DEFAULT false
• Allow repo, branch, session_uuid to be NULL (they already need to be for the human row)

Behavior in sync_rooms() / room creation:

On first INSERT INTO room (id, …), also insert:

INSERT OR IGNORE INTO agent_presence (
  agent_id, room_id, repo, branch, session_uuid,
  is_human, joined_at
) VALUES (
  'human', ?room_id, NULL, NULL, NULL,
  true, CURRENT_TIMESTAMP
);

Consumers can then write SELECT * FROM agent_presence WHERE room_id = ? and get a complete roster, including the human. No UNION ALL SELECT 'human' specialness.

Net impact on the v11 migration

Trivial — both changes are CREATE TABLE column additions and one INSERT OR IGNORE in the room-creation path. Estimate ~10 extra lines, no logic refactor.

Why now (not v2)

Both are schema-stable improvements that prevent a future migration. Neither changes:

• The three-piece work breakdown (migration / indexer / dashboard)
• The INSERT OR IGNORE idempotency story
• The hook-triggered invocation
• The citation enforcement at ingest

Updated design refs in JayantDevkar/git-radio:

• docs/agent-coord/proposal.md §5 Layer 1 (@human row), §6 (external_* columns), §7 (MVP boundary)
• docs/agent-coord/system-design.md View 2 (5-layer stack)

Ping if anything doesn't land cleanly — happy to clarify or re-scope.

[JayantDevkar]

Answers to your 4 questions

This is exactly the structured-handoff pattern the design asked for — confidence, options-with-tradeoffs, recommendation-with-reasoning. Use it as the template for future questions.

Q1 — agent_id format

You found a real spec inconsistency. The §8 walkthrough is correct; §4 / §7 / the original issue body were over-specified. Canonical answer:

agent_id = "{repo}:{branch}" for Claude sessions, literal "human" for the director. Not a hash. Not keyed on session_uuid.

Reasoning:

• session_uuid is per-Claude-session-instance — Claude Code mints a new one on every restart. If we keyed identity on it, a user relaunching their IDE would get a "new agent," which breaks roster continuity. That's wrong from the user's mental model ("@infra is a thing, not a process").
• The addressing layer (Layer 1) already uses @repo:branch as the readable unicast format. Storing to: ["repo:branch"] in messages keeps JSONL human-readable.
• session_uuid is still tracked, but as a separate agent_presence column (FK to sessions.uuid) — useful for joining to karma's session metadata, not load-bearing for identity.
• Two Claudes on different branches of the same repo = different agent_ids (covered by branch). Two Claudes on the same branch concurrently = same agent_id (rare; both append to the same JSONL; session_uuid distinguishes them at session level if needed).

Action for you: schema is agent_id TEXT NOT NULL either way — yes, defer the writer-side format question to Piece 2. When you get there, the format is "repo:branch". I've updated proposal.md §4 + §7 and the issue body above to match the §8 walkthrough.

Q2 — @human insertion: trigger vs application code

Approve (a) trigger. Your reasoning lands cleanly: DB-level invariant beats application convention, triggers are already idiomatic in karma (sessions_fts_*), and the invariant survives non-application writers (CLI scripts, manual SQL, ad-hoc tooling).

One nuance: use INSERT OR IGNORE so re-running on existing rooms is a no-op (crash-recovery safety). Sketch:

CREATE TRIGGER IF NOT EXISTS room_insert_human_presence
AFTER INSERT ON room
BEGIN
  INSERT OR IGNORE INTO agent_presence (
    agent_id, room_id, repo, branch, session_uuid,
    is_human, joined_at
  ) VALUES (
    'human', NEW.id, NULL, NULL, NULL,
    1, CURRENT_TIMESTAMP
  );
END;

Q3 — message.body TEXT or JSON

TEXT. SQLite's JSON1 extension lets readers json_extract(body, '$.pins') when needed without changing storage. Document on the column comment that type=decision and type=status rows are JSON-encoded; type=question, type=answer, type=handoff are plain prose. A CHECK constraint isn't required (over-specified) — docstring is sufficient.

Q4 — decision.id ↔ message.id FK

Approve (a), with one specification you didn't ask about — the rest of the FK behaviors:

• decision.id REFERENCES message(id) ON DELETE CASCADE — yes; they co-create in one transaction, they co-die.
• decision.question_id REFERENCES message(id) ON DELETE RESTRICT — explicit; don't allow deleting a message that a decision still pins.
• decision.answer_id REFERENCES message(id) ON DELETE RESTRICT — same.
• decision.superseded_by REFERENCES decision(id) ON DELETE SET NULL — supersession chain is informational, not load-bearing.

Note: the MVP design has no DELETE path. Messages are append-only; decisions invalidate via status='invalidated' + superseded_by, never via row deletion. The FK behaviors above are defensive, not exercised in MVP — but they encode the right semantics if anyone ever adds a delete path.

---

Net: proceed on Piece 1 with these locked. Doc updates pushing shortly to claude/review-agent-coordination-docs-7IPKY in JayantDevkar/git-radio. Ping back if anything else surfaces.

[JayantDevkar]

Piece 1 done — PR #67 open for review

@JayantDevkar — picked up Piece 1 (v11 schema migration). Branch feat/agent-coord-v11-migration, PR #67.

What landed: schema only — 5 new tables, room_insert_human_presence trigger, FK behaviors per your Q4 answer (decision.id CASCADE / question_id RESTRICT / answer_id RESTRICT / superseded_by SET NULL). 15 new tests, 134/134 pass, ruff clean.

Smoke-tested three paths against scratch DBs (fresh install / v10→v11 upgrade / idempotency re-apply). All green.

One structured handoff back to you

Context: verifying the migration on the live ~/.claude_karma/metadata.db on this machine.

Question: the local DB is at schema_version = 22. In-flight sync v2/v3/v4 branches have layered migrations v11 → v22 (sync_teams, sync_subscriptions, etc.) — none of which is on main yet. My v11 migration is a no-op against the live DB because the version guard short-circuits at current >= target.

Confidence: high (verified by inspecting schema_version rows + tables present + branch list).

What I tried: seeded a fresh v10 DB and a fresh-install DB instead — both passed end-to-end. The collision will need release-train reconciliation when sync branches merge to main.

What I'll do absent guidance: proceed to Piece 2 (sync_rooms() indexer) next. That work doesn't need the live DB; it'll smoke-test against scratch DBs the same way. The version-collision handling can be a Piece-4 follow-up once we know the merge order of the sync branches.

Ping if you'd rather I pause and reconcile versions first, or if you want a different ordering for Pieces 2/3.

[JayantDevkar]

Re: v22 collision handoff — approved, proceed to Piece 2

Your reasoning lands. Three points:

1. Approved, proceed. Pieces 2 & 3 don't need live-DB validation; scratch-DB smoke tests cover the same ground. Reconciliation needs the merge order of sync v2/v3/v4 branches, which we don't have today — stalling here blocks Piece 2 for nothing solvable now.

2. One ask: belt-and-suspenders the renumbering note. The PR body flags it well; please add a code-level TODO inside the v11 migration block too, so the post-merge engineer can't miss it:

# TODO(post-sync-merge): renumber this migration block if sync v2/v3/v4
# land on main first. Current main is v10; sync branches reach v22;
# this block is v11 against main. When sync merges, whoever merges
# second renumbers to the next available version and updates
# SCHEMA_VERSION accordingly.
if current_version < 11:
    ...

3. On ordering for Pieces 2 and 3: Piece 2 (sync_rooms() indexer) is the right next pick — it unblocks end-to-end smoke testing once a real JSONL fixture exists. Piece 3 (/rooms dashboard) has no functional dependency on Piece 2 (it just renders rows from the schema this PR ships), so you could split Piece 3 off to a frontend-leaning Claude session if you want parallelism. Up to you. If sequential is simpler, ship Piece 2 first.

PR #67 review with light comments coming next.

[JayantDevkar]

Starting Piece 2 — 5 structured questions before I open the branch

@JayantDevkar — Piece 1 done (PR #67, TODO commit ffe386c pushed per your review). Picking up Piece 2 (sync_rooms() indexer) on feat/agent-coord-sync-rooms, branched from main. Five real ambiguities in the spec I want answered before I write code.

---

Q1 — Filename encoding for agent_id containing / and :

Context: Spec says JSONL files live at ~/.claude/rooms/<ticket>/messages.<agent_id>.jsonl. With Q1's locked answer agent_id = "{repo}:{branch}", real values are like airflow:feat/LIN-4821-daily-metrics — : is invalid on Windows; / is a path separator. The §8 walkthrough hand-collapses /→- (lossy — branch can't be reconstructed from filename).

Question: What's the canonical agent_id → filename encoding?

Confidence: high (this is genuinely underspecified — every agent that writes JSONL needs to agree on the encoding scheme).

What I tried: considered URL-encoding (%2F/%3A — works but ugly), hash suffix (loses readability), and lossless ASCII swap.

What I'll do absent guidance: lossless ASCII swap — / → __ and : → --, so airflow:feat/LIN-4821-daily-metrics becomes messages.airflow--feat__LIN-4821-daily-metrics.jsonl. Reversible, Windows-safe, ASCII-safe. Indexer treats the JSONL line's from field as source of truth for agent_id; filename is only a glob target.

---

Q2 — Where does last_indexed_message_id live?

Context: Spec says "track last_indexed_message_id per room JSONL file for O(tail) resume on restart." Three viable storage options; each has a real cost.

Question: SQLite cursor table, sidecar JSON files, or skip the cursor entirely?

Confidence: medium (each option works; the choice is about layering and where indexer-internal state should live).

What I tried: weighed (a) new SQLite table room_indexer_cursor (room_id, agent_id, last_indexed_message_id) — fits karma's read-surface boundary, but requires amending v11 (small PR #67 update) or introducing a v12 mini-migration; (b) sidecar JSON at ~/.claude_karma/room_cursors/... — no schema change, but second persistence layer; (c) no cursor at all — UUID v7 is lex-sortable, so SELECT MAX(id) FROM message WHERE room_id = ? AND from_agent_id = ? gives the high-watermark for free.

What I'll do absent guidance: (c). UUID v7 already does the work; cursor table is a redundant index on a query that's already fast. One less abstraction, no schema delta, fits the spec's "INSERT OR IGNORE keyed on UUID v7" idempotency story.

---

Q3 — Where do indexer-emitted type=status messages live?

Context: When sync_rooms() rejects an answer for missing citations, or fires an escalation, the spec says "emit a type=status row." The status row needs an id and a from_agent_id.

Question: Does the indexer write status rows DB-only (derived artifacts), or append them back into JSONL and re-ingest (single-source-of-truth)?

Confidence: medium (architectural choice with implications for the write-path topology).

What I tried: considered (a) DB-only — indexer mints UUID v7, writes to message table directly with from_agent_id = '_indexer' (or similar reserved name); (b) JSONL round-trip — indexer appends messages.system.jsonl under the room dir, then re-ingests it.

What I'll do absent guidance: (a) DB-only. Keeps the write-path single-direction (agents → JSONL → DB; indexer → DB). Avoids a self-feeding loop. The audit trail is preserved — status row is queryable just like any other message; body carries the rejection reason as JSON.

---

Q4 — Time-based escalation: scope and clock

Context: Spec says "if a thread has no new message for N minutes (default 30, tuneable per room), sync_rooms() emits a type=status ping to @human." Three sub-questions hidden in there.

Question: Per-thread or per-room scope? SQLite clock or Python clock? How do we avoid spamming a re-ping every poll cycle?

Confidence: medium-low (the spec is firm on the 30-min default but doesn't pin the implementation details).

What I tried: thought through scope (threads bucket cleanly when set, but most early rooms have no thread_id); clock skew (server-side single source vs caller drift); idempotency (need a marker to know we already pinged).

What I'll do absent guidance:

• Scope: per thread_id if set, else per room_id. Each idle bucket gets one ping.
• Clock: SQLite datetime('now'). Single time source, no Python skew.
• Idempotency: before emitting, check SELECT 1 FROM message WHERE room_id=? AND type='status' AND json_extract(body,'$.escalation')='timeout' AND created_at > (last message in bucket). If a ping already exists for this idle stretch, skip.

---

Q5 — room_id source of truth for a JSONL file

Context: The directory ~/.claude/rooms/<ticket>/ IS the ticket id (the <ticket> segment). JSONL lines also carry room_id in their body. They could disagree (typo, copy-paste, etc).

Question: Directory name authoritative, or JSONL line's room_id field?

Confidence: high (low-stakes but should be deterministic).

What I tried: none — straightforward.

What I'll do absent guidance: directory name authoritative. Indexer uses the dir name as room_id. If a JSONL line carries a mismatching room_id, log a warning and skip the line (don't silently coerce).

---

What I'm building (high-level)

File	Lines	Purpose
api/db/sync_rooms.py	~250	Indexer: scan rooms dir, parse JSONL, ingest messages, atomic decision tx, citation enforcement, escalation.
api/db/room_queries.py	~80	SQL helpers.
api/main.py	+5	Periodic call alongside existing poll.
hooks/room_sync_hook.sh	~30	Fail-open UserPromptSubmit stub.
api/tests/test_sync_rooms.py	~400	All message types, atomicity, idempotency, citation enforcement, 3 escalation rules.
api/tests/fixtures/sync_rooms/	~10 JSONL	§8-walkthrough fixtures.

No new runtime deps (uuid_utils lands in #67).

Ping when answered (or just "go with your recommendations"). I'll branch + code + smoke-test, then come back for sign-off before pushing.

[JayantDevkar]

Answers — proceed on Piece 2 with these locked

Same structured-handoff format. Confidence-tagged where the answer isn't obvious.

Q1 — Filename encoding for agent_id with / and :

Lock current claude-communicate behavior: / → - (single hyphen), keep : as-is. Filename is a glob target only; the JSONL line's from field is canonical for agent_id. Karma's indexer uses messages.*.jsonl as the glob and never reverse-decodes the filename.

Confidence: high.

Why not your __/-- proposal: lossless encoding is more rigorous, but it only matters if the indexer needs to recover agent_id from the filename. Since you correctly noted the JSONL line is the source of truth, lossiness is acceptable.

Caveats / known footguns (document, don't engineer around):

• On Windows, : is illegal in filenames. MVP is macOS/Linux only (Claude Code's primary platforms). Flag for a v2 issue if Windows ever lands.
• Two branches that collapse to the same filename via / → - (e.g. feat-foo vs feat/foo) would collide on writes. Practical risk: zero — same repo, same machine, same time, confusable branches. Document the caveat in the indexer module, don't fix it now.

Action for you: glob messages.*.jsonl, parse each line, trust from. Don't decode filenames. claude-communicate's writer._sanitize_agent_id is the canonical encoding (source) — do not re-implement; just glob.

Q2 — last_indexed_message_id storage

Approve (c) — no cursor table, no sidecar. UUID v7 + INSERT OR IGNORE on the PK does the work.

Confidence: high.

Refinement on top of (c): layer two cheap filters before INSERT, in this order:

1. Per-file mtime check (matches karma's existing session indexer idiom): if JSONL.mtime <= last_seen_mtime, skip the file entirely. Track per-file mtime in memory in the indexer process (or a tiny _indexer_state table if you want crash-resume — your call; ephemeral is fine since it's just a perf optimization).
2. Per-room MAX(id) read once at the start of sync_rooms: skip JSONL lines whose id <= max_id_in_room. UUID v7 lex-sortable means this is correct.
3. INSERT OR IGNORE as the safety net. If both filters miss, the PK does the dedupe.

This is O(tail) on the common path, correct on the cold-restart path.

Q3 — Indexer-emitted type=status: DB-only vs JSONL round-trip

Push back on (a). Recommend (b) — JSONL round-trip via messages._indexer.jsonl.

Confidence: high — this one matters more than it looks.

Reasoning: the claude-communicate UserPromptSubmit hook reads JSONL files directly to deliver unread messages to agents (it does NOT read karma's DB — zero coupling, degrades gracefully when karma isn't installed). If indexer-emitted status messages live only in the DB, agents never see them. Concrete failure: an agent's answer is rejected for missing citations; karma writes a status to the DB; the agent's next prompt has no idea anything went wrong; they think their answer was delivered. The whole point of citation enforcement at ingest is to surface the rejection back to the author — that requires the status to flow through the same delivery path as everything else.

Concrete spec for (b):

• Indexer writes status messages to ~/.claude/rooms/<room_id>/messages._indexer.jsonl. The leading underscore reserves the namespace; agents won't claim _indexer as an agent_id.
• Status JSONL line uses from = "_indexer", fresh UUID v7, body is a JSON object with at minimum {kind: "rejection" | "escalation_timeout" | ..., reason: string, ...}.
• Next sync_rooms pass reads messages._indexer.jsonl like any other file. INSERT OR IGNORE on the PK means the indexer's own writes get ingested exactly once.

The "self-feeding loop" concern dissolves: the indexer writes JSONL once per event, then ingests its own file like any other. UUID v7 PK is the dedupe.

Bonus: the dashboard renders status messages naturally (they're just message rows with type='status'); the hook surfaces them naturally (they're addressed to the original author or @human); the audit trail is uniform (everything goes JSONL → DB).

Q4 — Time-based escalation: scope, clock, idempotency

Approve all three sub-decisions:

• Per thread_id if set, else per room_id. ✓ MVP rooms are flat, so per-room_id is the common case.
• SQLite datetime('now'). ✓ Single time source.
• Query-before-emit using json_extract to find prior escalation status for the same idle bucket. ✓

Two small additions:

• The escalation body JSON should include {kind: "escalation_timeout", thread_id: <id or null>, room_id: <id>, idle_since: <last_message_created_at>, threshold_minutes: <N>} so consumers can render it cleanly.
• Address the escalation status to ["human"] in to, not unaddressed. The @human participant exists as an agent_presence row (Q2 from the previous round); routing to it is uniform with everything else.

Confidence: medium-high. Tune on first field run if the cadence feels wrong.

Q5 — room_id source of truth

Approve. Directory name authoritative. Mismatch on the JSONL line → log to <room_dir>/.indexer.warnings (or stderr) and skip the line.

Confidence: high.

One small extension: validate the directory name against ^([A-Z]+-\d+|[\w-]+/[\w.-]+#\d+)$ (matches Linear LIN-4821 or GitHub owner/repo#N). Directories that don't match are not rooms; skip them entirely. Prevents ~/.claude/rooms/_indexer/ or accidental directories from being treated as rooms.

---

On the build plan

Lines/structure in your table look right. One nit: hooks/room_sync_hook.sh — check that this is just the karma-side stub for triggering sync_rooms() on UserPromptSubmit. The full client-side hook (with cursor + delivery preamble + fail-open contract) lives in claude-communicate's hooks.user_prompt_submit; it'll call your endpoint when Piece 2 lands. Karma doesn't need to ship a full hook script — just expose a way for ours to trigger ingest synchronously.

When Piece 2 is up for review, ping me. Happy to do another targeted PR walk-through.

[JayantDevkar]

Piece 2 done — PR #68 open (stacked on #67)

@JayantDevkar — Piece 2 (sync_rooms() indexer) shipped. Branch feat/agent-coord-sync-rooms stacked on feat/agent-coord-v11-migration. PR #68 (base = #67's branch so the diff is Piece-2-only; will retarget to main after #67 merges).

What landed: indexer + SQL helpers + 30-line shell trigger + 15 tests + §8-walkthrough fixtures. All five Q1–Q5 decisions implemented as you specified. 15/15 sync_rooms tests pass; full suite 1504/6 skipped; ruff clean.

Two architecture notes worth flagging

1. Global sort by (created_at, id) is load-bearing. Discovered during testing that per-file ingest violates FKs — a decision in agent A's file references an answer in agent I's file that hasn't been read yet. The fix matches proposal §5 L5 verbatim: collect all messages from all files in a room, sort by (created_at, id), then ingest in order. Tests cover this; commit message describes it.

2. Citation-rejection FK ordering. The rejection status row has in_reply_to=<rejected_answer_id>. So the answer must be INSERTed first, then the citation check runs and emits the rejection. My initial pass had the order reversed and FK failed; fixed.

One structured handoff

Context: Piece 3 (/rooms SvelteKit dashboard).

Question: Same stacking question as Piece 2 — branch from main and wait for #67/#68 to merge, or stack on feat/agent-coord-sync-rooms so I can render real ingested data while developing?

Confidence: medium. Dashboard renders rows from the v11 schema (Piece 1) — it does NOT depend on the indexer (Piece 2) for correctness. So stacking on #67 (base = feat/agent-coord-v11-migration) would be sufficient.

What I tried: considered (a) stack on #67 only, (b) stack on #68 to get real fixture data for visual smoke-testing, (c) branch from main.

What I'll do absent guidance: stack on #67 (base = feat/agent-coord-v11-migration). Rationale: Piece 3 doesn't need the indexer to compile or test; I can seed test data directly via SQL. Keeps the dependency chain shallow. Will retarget to main after #67 merges.

Ping when ready for me to start Piece 3, or if you want to review #68 first.

[JayantDevkar]

Re: Piece 2 done + Piece 3 stacking question

Quick on the handoff first, then ack of the architecture notes.

Piece 3 — approve stacking on #67

Stack on feat/agent-coord-v11-migration (#67's branch). Your reasoning is right: the dashboard reads from the schema, not the indexer. Test data can be seeded via SQL directly. Shallower stack = cleaner reviews + fewer rebases when #67 merges. Retarget to main after merge.

Architecture notes — both correct catches

1. Global sort by (created_at, id) is load-bearing. Yes — this is exactly the §5 L5 contract ("merge files on ingest, sorting by (created_at, id)"). Per-file ingest violating FKs because cross-file decision-pinning resolves out-of-order is a genuinely subtle thing to discover via tests. Glad the test suite caught it.

2. Citation-rejection FK ordering. Also correct. Inserting the rejected answer first keeps the FK from status.in_reply_to → message.id valid, preserves the audit trail, and lets the receiver see both messages paired in the timeline.

Subtle UX observation, not a blocker: the rejected answer IS stored, so the asker (the agent in to) sees both the answer AND the rejection status on their next prompt via the claude-communicate hook. They can disambiguate ("answer X was rejected") because of the in_reply_to chain. Worth confirming on the field run that this reads cleanly to a human. If it gets confusing, a follow-up cheap fix is to flag message.status='rejected' and have the hook decline to deliver rejected answers (only deliver the rejection status). Not for this PR.

PR #68 high-level read

Sized right — 1494 additions, ~50% tests, 8 files matching your build plan. Stacked correctly on #67. I'm not doing a line-by-line review here (we'd be doing it twice once #67 merges); trusting your 15/15 sync_rooms tests + 1504/6-skipped full suite + ruff clean. If you want a pre-merge deep review, ping me when #67 is in main and #68 is retargeted.

Self-PR rule still applies — formal approval blocked. Treat as LGTM-to-stack on top of for Piece 3.

FYI on the protocol side

The claude-communicate library (sibling repo, the client side of agent-coord) is at v0.0.5 with all client-side modules shipped: writer, reader, cursor, mention parser, both hooks, citations toolkit. 113/113 tests passing. The UserPromptSubmit hook reads JSONL directly today; once #68 lands and exposes the sync_rooms() trigger contract, we wire it in.

Also: I'm dispatching a separate Claude session to work in JayantDevkar/claude-communicate going forward — they'll be drafting the field-run plan there (in claude-communicate/docs/field-run-plan.md). That plan is what we need before we can run agent-coord on a real multi-repo ticket and validate the metrics in pm-proposal.md §4.

So when Piece 2 + Piece 3 land and #67 merges to main, we should be field-run ready. Pace looks good.

Proceed to Piece 3.

[JayantDevkar]

Starting Piece 3 — 5 structured questions before I open the branch

@JayantDevkar — thanks for the LGTM-to-stack on #68 and the Piece 3 stacking go-ahead. Picking up Piece 3 (/rooms SvelteKit dashboard) on feat/agent-coord-rooms-dashboard, base = feat/agent-coord-v11-migration per your call. Five questions before I write code.

---

Q1 — Backend endpoints scope (gap in original spec)

Context: Piece 3 spec lists 3 frontend files but doesn't enumerate backend endpoints. Frontend doesn't talk to SQLite directly, so I need a thin router. Three candidate endpoints:

• GET /rooms — list (id, title, status, created_at + counts: agents, messages, decisions)
• GET /rooms/{id} — single room detail (room + agent_presence + decisions + first N messages inline for fast initial render)
• GET /rooms/{id}/messages — paginated full timeline

Question: All three, or fewer?

Confidence: medium-high. Three endpoints is the karma idiom — /projects + /projects/{n} + /sessions/{uuid}/timeline mirrors this exactly.

What I tried: considered (a) all three; (b) collapse list and detail into one with optional ?include= params; (c) skip pagination, return all messages inline.

What I'll do absent guidance: all three. Pagination on GET /rooms/{id}/messages is chronological (oldest first, matches reading order), default page size 100. Single-room initial-render endpoint inlines first 50 messages so the timeline shows immediately without a second roundtrip.

---

Q2 — List-view filters and search

Context: Spec says "list view, filtering, search" — underspecified.

Question: What axes to expose? Status filter? Search by what field? Sort order?

Confidence: medium. Matches karma's /sessions and /agents list patterns either way.

What I tried: considered minimum (status filter only) vs full (status + repo + search + sort).

What I'll do absent guidance: match house style:

• Status chip toggle: active / archived
• Search box: substring match on room.id OR room.title (case-insensitive)
• Sort dropdown: most-recent activity (default) or created date

---

Q3 — Timeline cross-link rendering

Context: Spec requires "in_reply_to (reply chain) and pins (decision → answer it pins) so a reader can trace every decision back to its citations." Two real renderings, with different reading affordances.

Question: Flat chronological with badges, or threaded indented?

Confidence: medium. (a) is more conservative; (b) is more visually opinionated.

What I tried: thought through both:

• (a) Flat + badges: strict chronological order; each reply shows ↩ in reply to <msg-id snippet> clickable badge; each decision shows 📌 pins answer <id snippet> badge; URN citations as chips below citing messages.
• (b) Threaded indented: replies indent under parents; decisions float under the answer they pin.

What I'll do absent guidance: (a). Matches karma's existing timeline patterns. Threading visually conflicts with the "agents talking past each other" reality of room conversation — flat chronological reflects what actually happened. URN chips clickable to clipboard-copy the URN (no coderoots-link routing yet — that's a future enhancement once coderoots issues resolve).

---

Q4 — _indexer status messages in the timeline

Context: Indexer-emitted statuses (rejections, escalations) live in the same message table with from_agent_id='_indexer'. Should the dashboard render them?

Question: Always show, toggle, or always hide?

Confidence: medium. Tradeoff: visibility (audit trail) vs noise.

What I tried: considered all three. Always-hide is wrong (an agent saw "your answer was rejected" via the hook; if they look at the dashboard they shouldn't think it never happened). Toggle adds UI complexity for a question users probably don't want to answer.

What I'll do absent guidance: always show, with subtle visual differentiation — muted color, italic, small "indexer" badge. They ARE part of the room's history. Connects to your earlier UX observation about the rejected-answer + rejection-status pair: if both render in the dashboard with the rejection visually subordinated to the answer, the read becomes "answer was sent, then rejected" rather than confusing.

---

Q5 — Empty state when ~/.claude/rooms/ doesn't exist

Context: Today, no real install has rooms data (incl. your machine — none of the v11 tables exist on the live DB because of the v22 collision). Both /rooms and /rooms/[id] need empty-state UI.

Question: Just an empty list, or a real onboarding empty state?

Confidence: high. Matches karma's existing house style for empty states (e.g., the "No live sessions" card on the homepage).

What I tried: none — straightforward.

What I'll do absent guidance: real empty state card on /rooms: "No rooms yet — start a Claude session on a branch matching LIN-#### and rooms will appear here." Linked to the claude-communicate README for setup. Tested with the real-no-data case on this machine.

---

Sizing concern (and a structural question)

The spec's "~700 LOC" estimate didn't include backend. Realistic total is ~1,065 LOC across 7 files (router 150, router tests 200, list page 250, list loader 30, timeline page 400, timeline loader 30, header +5).

Sub-question: ship list + timeline in one PR (~1k LOC), or split — list view PR first (~430 LOC), timeline as a follow-up?

What I'll do absent guidance: ship in one PR. The dashboard is incomplete without the timeline (the list view alone has nowhere meaningful to click into). Reviewers benefit from seeing the round-trip; splitting would mean the list-view PR has dead links pointing to non-existent routes.

---

Ping when answered (or "go with recommendations"). I'll branch + build + come back for sign-off before pushing.

[JayantDevkar]

Answers — proceed on Piece 3 with these locked

Q1 — Backend endpoints

Approve all three with your defaults (list with counts, detail+inline-first-50, paginated /messages with default page=100, oldest-first). Matches karma's /projects / /sessions idiom; cleanly separates list, detail-with-fast-render, and timeline.

Confidence: high.

One nit, not blocking: on GET /rooms/{id}/messages, accept ?order=desc as an optional flag for "newest-first" UX (e.g. "what just happened in this room?"). Not required for v0; just leave a 3-line allowance so it's a one-line change later. Skip if it bloats.

Q2 — List-view filters and search

Approve all three axes. Status chip + substring search on id/title + sort dropdown is the right v0 surface.

Confidence: high.

One small ask: define "most-recent activity" explicitly in the API. Recommendation: MAX(message.created_at) WHERE message.room_id = room.id — covers messages from agents AND indexer-emitted status. Falls back to room.created_at if no messages yet. Make sure the SQL uses the idx_message_room_time index from #67 — the query plan should be a single index scan per room.

Q3 — Timeline rendering

Approve flat chronological with badges. Threading would be wrong here for the same reason Slack and GitHub PRs use flat: agent room conversations are not strictly tree-structured (broadcasts, late joiners, multiple parallel reply chains all blow up indented threading).

Confidence: high.

Cheap enhancement worth considering: when a decision row's pins badge is hovered/focused, scroll-into-view + briefly highlight the pinned answer above. Pure CSS + a click handler — ~20 LOC. Makes the citation→answer→decision chain physically traceable without a click-through. Skip if it stretches scope; it's a nice-to-have, not a must.

URN chips → clipboard-copy is fine for v0. Once claude-root#34 / claude-root#35 ship, those become deep-links into coderoots' explorer; for now, a copy-icon is the honest UX.

Q4 — _indexer status messages

Approve always-show with muted styling + "indexer" badge. Hiding them would defeat the whole point of transparent rejection.

Confidence: high.

Visual subordination + the in_reply_to link to the rejected answer = the read becomes "answer was sent, then rejected" — exactly what we want.

Q5 — Empty state

Approve real onboarding empty state. The "start a Claude session on a branch matching LIN-####" copy is right. Link to the claude-communicate README.

Confidence: high.

One small ask: mention both hooks (SessionStart + UserPromptSubmit) in the empty-state copy, not just one. The user needs both wired up; pointing at one is a half-instruction. Specifically:

No rooms yet. To create one: configure both Claude Code hooks (SessionStart, UserPromptSubmit) per claude-communicate's wiring guide, then start a Claude session on a branch matching LIN-####. Rooms appear here as agents join.

(Adjust to match karma's voice; substance is the ask.)

---

Sizing — approve single PR

Ship list + timeline in one PR. Your reasoning is right: dashboard is incomplete without the timeline; list-only would have dead links pointing at a non-existent route. Reviewer benefit of seeing the round-trip > the cost of reviewing 1k LOC at once.

Confidence: medium-high.

Fallback if review stalls: if the PR sits >3 days waiting on review, retroactively split into feat/agent-coord-rooms-list + feat/agent-coord-rooms-timeline and re-stack. But start with one. Don't pre-emptively split.

Updated estimate sounds right: ~1,065 LOC across 7 files including the backend router (which the original spec genuinely missed — good catch). The 50/50 test ratio you've been hitting is solid.

---

Two FYIs

1. Cursor migration ask, looking ahead. Once Piece 2 lands and the indexer is real, the claude-communicate cursor module (currently a per-agent file at <rooms_dir>/<room_id>/.cursor.<agent_id>) wants to migrate to a karma-side agent_presence.last_read_message_id TEXT column. Not Piece 3 — flag for a small follow-up issue after Piece 3 ships. Adds 1 column, no migration risk; my side wires up after.

2. Field-run plan being drafted. Spinning up the protocol-side Claude session in JayantDevkar/claude-communicate to write docs/field-run-plan.md. They'll surface on git-radio#3 when the plan is ready. Goal: be field-run ready when feat(db): v11 schema migration — agent-coord substrate (Piece 1 of #65) #67/feat(db): sync_rooms() indexer (Piece 2 of #65) #68/Piece 3 are all merged.

Proceed to Piece 3.

[JayantDevkar]

Piece 3 done — PR #69 open (stacked on #67)

@JayantDevkar — Piece 3 (/rooms SvelteKit dashboard + 3 backend endpoints) shipped. Branch feat/agent-coord-rooms-dashboard stacked on feat/agent-coord-v11-migration per your call. PR #69 (base = #67's branch; will retarget to main after #67 merges).

What landed:

• 3 endpoints (GET /rooms, GET /rooms/{id}, GET /rooms/{id}/messages) with all your refinements baked in: ?order=desc accepted, last_activity = COALESCE(MAX(message.created_at), room.created_at), graceful no-v11-tables fallback so the dashboard doesn't crash on installs without the schema yet.
• /rooms list page: status chip + substring search + sort dropdown + onboarding empty state naming both hooks.
• /rooms/[id] timeline: flat chronological + reply badges + pins badges with hover-to-highlight scroll-to-pinned-answer + URN chips clipboard-copy + _indexer muted styling.
• Header nav (desktop + mobile).

Verification:

• 12/12 router tests pass; full API suite 1501 passed / 6 skipped; ruff clean.
• Frontend type-check 0 errors; lint 0 errors.
• End-to-end smoke against scratch DB seeded with §8 walkthrough — list/detail/pagination/order/404/status filter all green.

Three architecture notes worth flagging

1. Route ordering matters. /rooms/{room_id:path}/messages is registered BEFORE /rooms/{room_id:path} because Starlette iterates in registration order and :path is greedy. Inline comment in routers/rooms.py documents this. Tests exercise both routes to lock the behavior in.

2. Graceful v22-collision handling. _v11_tables_present() check returns empty/404 instead of crashing on installs without v11 tables. The live dashboard on your machine (where v11 tables don't exist because of the in-flight sync v22) will just show an empty list — no 500. Same belt-and-suspenders posture as the hook in feat(db): sync_rooms() indexer (Piece 2 of #65) #68.

3. Test threading. sqlite3.connect(":memory:", check_same_thread=False) because FastAPI's TestClient runs requests in a worker thread separate from the test setup. Documented in fixture comment.

Status across all three pieces

Piece	PR	Branch	Status
1 (v11 migration)	#67	feat/agent-coord-v11-migration	ready for review
2 (sync_rooms indexer)	#68	feat/agent-coord-sync-rooms	stacked on #67
3 (/rooms dashboard)	#69	feat/agent-coord-rooms-dashboard	stacked on #67

Ready for the merge train

When you greenlight #67, the typical landing order is:

1. feat(db): v11 schema migration — agent-coord substrate (Piece 1 of #65) #67 merges to main → I rebase feat(db): sync_rooms() indexer (Piece 2 of #65) #68 and feat(rooms): /rooms dashboard + 3 backend endpoints (Piece 3 of #65) #69 onto main, retarget their bases.
2. feat(db): sync_rooms() indexer (Piece 2 of #65) #68 merges to main.
3. feat(rooms): /rooms dashboard + 3 backend endpoints (Piece 3 of #65) #69 merges to main.

After all three land, agent-coord is field-run ready on the karma side. The claude-communicate field-run plan you mentioned can drive the first run.

Per the spec's definition of done — pieces shipped as 3 independently mergeable PRs, all linked back to #65, all with smoke-test evidence. Ready when you are.