@team-agent/installer 0.2.4 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",

package/src/team_agent/cli/commands.py

@@ -224,6 +224,20 @@ def cmd_doctor(args: argparse.Namespace) -> dict[str, Any] | str:
         if gate != "orphans":
             raise TeamAgentError(f"unknown doctor gate: {gate}")
         return orphan_gate(fix=bool(getattr(args, "fix", False)), confirm=bool(getattr(args, "confirm", False)))
+    from team_agent.message_store.schema import SCHEMA_VERSION
+    from team_agent.message_store.schema_migration import fix_schema_layout, schema_diagnosis
+    if getattr(args, "fix_schema", False) is True:
+        return fix_schema_layout(Path(args.workspace).resolve(), schema_version=SCHEMA_VERSION)
+    schema = schema_diagnosis(Path(args.workspace).resolve(), schema_version=SCHEMA_VERSION)
+    if schema.get("layout_diffs"):
+        return {
+            "ok": True,
+            "schema": schema,
+            "coordinator": {
+                "schema_ok": False,
+                "schema_error": "team.db physical layout drift detected",
+            },
+        }
     if getattr(args, "cleanup_orphans", False):
         from team_agent.diagnose.orphan_cleanup import cleanup_orphan_coordinators, format_cleanup_orphans
         result = cleanup_orphan_coordinators(confirm=bool(getattr(args, "confirm", False)))
@@ -231,7 +245,9 @@ def cmd_doctor(args: argparse.Namespace) -> dict[str, Any] | str:
             return result
         return format_cleanup_orphans(result)
     spec = Path(args.spec).resolve() if args.spec else None
-    return runtime.doctor(spec)
+    result = runtime.doctor(spec)
+    result["schema"] = schema
+    return result
 
 
 def _format_status_summary(data: dict[str, Any]) -> str:

package/src/team_agent/cli/parser.py

@@ -54,7 +54,6 @@ from team_agent.cli.commands import (
     cmd_advanced,
     cmd_install_skill,
     cmd_run_overnight,
-
 )
 from team_agent.cli.e2e import cmd_e2e
 from team_agent.cli.helpers import (
@@ -65,7 +64,6 @@ from team_agent.cli.helpers import (
     emit,
 )
 
-
 SEND_ORDER_HINT = (
     "options must appear before target/message. Use: "
     "team-agent send --task <task_id> --json \"<message>\" or "
@@ -317,8 +315,10 @@ def main(argv: list[str] | None = None) -> None:
 
     p = sub.add_parser("doctor", help="Check local dependencies, providers, auth hints, tmux, and MCP")
     p.add_argument("spec", nargs="?")
+    p.add_argument("--workspace", default=".", help="Workspace whose team.db schema should be diagnosed")
     p.add_argument("--gate", choices=["orphans"], help="Run a CI-friendly doctor gate")
     p.add_argument("--fix", action="store_true", help="With --gate orphans: apply the gate fix")
+    p.add_argument("--fix-schema", action="store_true", help="Rebuild drifted team.db table layouts after writing a backup")
     p.add_argument(
         "--cleanup-orphans",
         action="store_true",

package/src/team_agent/message_store/agent_health.py

@@ -3,9 +3,13 @@ from __future__ import annotations
 from contextlib import closing
 from typing import Any
 
+from team_agent.message_store.schema_migration import MANAGED_TABLE_LAYOUTS
 from team_agent.message_store.schema import utcnow
 
 
+AGENT_HEALTH_SELECT = ", ".join(MANAGED_TABLE_LAYOUTS["agent_health"])
+
+
 def upsert_agent_health(
     self,
     agent_id: str,
@@ -50,10 +54,10 @@ def upsert_agent_health(
 def agent_health(self, owner_team_id: str | None = None) -> dict[str, dict[str, Any]]:
     with closing(self.connect()) as conn:
         if owner_team_id is None:
-            rows = conn.execute("select * from agent_health order by agent_id").fetchall()
+            rows = conn.execute(f"select {AGENT_HEALTH_SELECT} from agent_health order by agent_id").fetchall()
         else:
             rows = conn.execute(
-                "select * from agent_health where owner_team_id = ? or owner_team_id is null order by agent_id",
+                f"select {AGENT_HEALTH_SELECT} from agent_health where owner_team_id = ? or owner_team_id is null order by agent_id",
                 (owner_team_id,),
             ).fetchall()
     return {row["agent_id"]: dict(row) for row in rows}

package/src/team_agent/message_store/core.py

@@ -12,10 +12,17 @@ from typing import Any, Callable
 from . import agent_health as _agent_health
 from . import result_watchers as _result_watchers
 from .schema import SCHEMA_VERSION, initialize_schema, utcnow
+from .schema_migration import MANAGED_TABLE_LAYOUTS
 from team_agent.paths import runtime_dir
 from team_agent.spec import validate_result_envelope
 
 
+MESSAGE_SELECT = ", ".join(MANAGED_TABLE_LAYOUTS["messages"])
+RESULT_SELECT = ", ".join(MANAGED_TABLE_LAYOUTS["results"])
+SCHEDULED_EVENT_SELECT = ", ".join(MANAGED_TABLE_LAYOUTS["scheduled_events"])
+DELIVERY_TOKEN_SELECT = ", ".join(MANAGED_TABLE_LAYOUTS["delivery_tokens"])
+
+
 def _is_sqlite_locked(exc: sqlite3.OperationalError) -> bool:
     message = str(exc).lower()
     return (
@@ -57,7 +64,7 @@ class MessageStore:
     def _init(self) -> None:
         def initialize() -> None:
             with closing(self.connect()) as conn:
-                initialize_schema(conn)
+                initialize_schema(conn, self.path)
 
         _with_sqlite_busy_retry(initialize)
 
@@ -224,10 +231,10 @@ class MessageStore:
     def messages(self, owner_team_id: str | None = None) -> list[dict[str, Any]]:
         with closing(self.connect()) as conn:
             if owner_team_id is None:
-                rows = conn.execute("select * from messages order by created_at").fetchall()
+                rows = conn.execute(f"select {MESSAGE_SELECT} from messages order by created_at").fetchall()
             else:
                 rows = conn.execute(
-                    "select * from messages where owner_team_id = ? or owner_team_id is null order by created_at",
+                    f"select {MESSAGE_SELECT} from messages where owner_team_id = ? or owner_team_id is null order by created_at",
                     (owner_team_id,),
                 ).fetchall()
         return [dict(row) for row in rows]
@@ -236,8 +243,8 @@ class MessageStore:
         with closing(self.connect()) as conn:
             if owner_team_id is None:
                 rows = conn.execute(
-                    """
-                    select * from messages
+                    f"""
+                    select {MESSAGE_SELECT} from messages
                     where sender = ? or recipient = ?
                     order by created_at desc
                     limit ?
@@ -246,8 +253,8 @@ class MessageStore:
                 ).fetchall()
             else:
                 rows = conn.execute(
-                    """
-                    select * from messages
+                    f"""
+                    select {MESSAGE_SELECT} from messages
                     where (sender = ? or recipient = ?)
                       and (owner_team_id = ? or owner_team_id is null)
                     order by created_at desc
@@ -259,7 +266,7 @@ class MessageStore:
 
     def delivery_tokens(self) -> list[dict[str, Any]]:
         with closing(self.connect()) as conn:
-            rows = conn.execute("select * from delivery_tokens order by injected_at").fetchall()
+            rows = conn.execute(f"select {DELIVERY_TOKEN_SELECT} from delivery_tokens order by injected_at").fetchall()
         return [dict(row) for row in rows]
 
     def add_scheduled_event(
@@ -285,8 +292,8 @@ class MessageStore:
         with closing(self.connect()) as conn:
             if owner_team_id is None:
                 rows = conn.execute(
-                    """
-                    select * from scheduled_events
+                    f"""
+                    select {SCHEDULED_EVENT_SELECT} from scheduled_events
                     where status = 'pending' and due_at <= ?
                     order by due_at, id
                     """,
@@ -294,8 +301,8 @@ class MessageStore:
                 ).fetchall()
             else:
                 rows = conn.execute(
-                    """
-                    select * from scheduled_events
+                    f"""
+                    select {SCHEDULED_EVENT_SELECT} from scheduled_events
                     where status = 'pending' and due_at <= ?
                       and (owner_team_id = ? or owner_team_id is null)
                     order by due_at, id
@@ -438,14 +445,14 @@ class MessageStore:
         if uncollected_only:
             clauses.append("status not in ('collected', 'invalid')")
         where = " where " + " and ".join(clauses) if clauses else ""
-        query = f"select * from results{where} order by created_at"
+        query = f"select {RESULT_SELECT} from results{where} order by created_at"
         with closing(self.connect()) as conn:
             rows = conn.execute(query, args).fetchall()
         return [dict(row) for row in rows]
 
     def result_by_id(self, result_id: str) -> dict[str, Any] | None:
         with closing(self.connect()) as conn:
-            row = conn.execute("select * from results where result_id = ?", (result_id,)).fetchone()
+            row = conn.execute(f"select {RESULT_SELECT} from results where result_id = ?", (result_id,)).fetchone()
         return dict(row) if row else None
 
     def latest_results(self, limit: int = 5, owner_team_id: str | None = None) -> list[dict[str, Any]]:
@@ -454,7 +461,7 @@ class MessageStore:
         with closing(self.connect()) as conn:
             rows = conn.execute(
                 f"""
-                select * from results
+                select {RESULT_SELECT} from results
                 where status != 'invalid' {owner_clause}
                 order by created_at desc
                 limit ?

package/src/team_agent/message_store/leader_notification_log.py

@@ -15,6 +15,11 @@ import sqlite3
 import time
 from typing import Any
 
+from team_agent.message_store.schema_migration import MANAGED_TABLE_LAYOUTS
+
+
+LEADER_NOTIFICATION_SELECT = ", ".join(MANAGED_TABLE_LAYOUTS["leader_notification_log"])
+
 
 def _sqlite_locked(exc: sqlite3.OperationalError) -> bool:
     message = str(exc).lower()
@@ -79,13 +84,12 @@ def claim_leader_notification_delivery(
         # Should not happen (INSERT OR IGNORE returned 0 → row must exist), but be defensive.
         return {"status": "claimed_by_you", "notified_message_id": proposed_message_id,
                 "notified_at": now, "envelope_content_hash": envelope_hash}
-    prev_message_id, prev_ts, prev_hash, prev_pane = row[0], row[1], row[2], row[3]
     return {
         "status": "already_notified_by",
-        "notified_message_id": prev_message_id,
-        "notified_at": prev_ts,
-        "envelope_content_hash": prev_hash,
-        "leader_pane_id_at_notify": prev_pane,
+        "notified_message_id": row["notified_message_id"],
+        "notified_at": row["notified_at"],
+        "envelope_content_hash": row["envelope_content_hash"],
+        "leader_pane_id_at_notify": row["leader_pane_id_at_notify"],
     }
 
 
@@ -109,11 +113,11 @@ def peek_leader_notification(
     if row is None:
         return None
     return {
-        "notified_message_id": row[0],
-        "notified_at": row[1],
-        "envelope_content_hash": row[2],
-        "leader_pane_id_at_notify": row[3],
-        "owner_team_id": row[4],
+        "notified_message_id": row["notified_message_id"],
+        "notified_at": row["notified_at"],
+        "envelope_content_hash": row["envelope_content_hash"],
+        "leader_pane_id_at_notify": row["leader_pane_id_at_notify"],
+        "owner_team_id": row["owner_team_id"],
     }
 
 
@@ -134,11 +138,11 @@ def leader_notification_log_rows(store: Any, *, owner_team_id: str | None = None
     with closing(store.connect()) as conn:
         if owner_team_id is None:
             rows = conn.execute(
-                "select * from leader_notification_log order by notified_at"
+                f"select {LEADER_NOTIFICATION_SELECT} from leader_notification_log order by notified_at"
             ).fetchall()
         else:
             rows = conn.execute(
-                "select * from leader_notification_log where owner_team_id = ? "
+                f"select {LEADER_NOTIFICATION_SELECT} from leader_notification_log where owner_team_id = ? "
                 "or owner_team_id is null order by notified_at",
                 (owner_team_id,),
             ).fetchall()

package/src/team_agent/message_store/result_watchers.py

@@ -4,9 +4,13 @@ import uuid
 from contextlib import closing
 from typing import Any
 
+from team_agent.message_store.schema_migration import MANAGED_TABLE_LAYOUTS
 from team_agent.message_store.schema import utcnow
 
 
+RESULT_WATCHER_SELECT = ", ".join(MANAGED_TABLE_LAYOUTS["result_watchers"])
+
+
 def create_result_watcher(
     self,
     task_id: str | None,
@@ -32,11 +36,13 @@ def create_result_watcher(
 def pending_result_watchers(self, owner_team_id: str | None = None) -> list[dict[str, Any]]:
     with closing(self.connect()) as conn:
         if owner_team_id is None:
-            rows = conn.execute("select * from result_watchers where status = 'pending' order by created_at").fetchall()
+            rows = conn.execute(
+                f"select {RESULT_WATCHER_SELECT} from result_watchers where status = 'pending' order by created_at"
+            ).fetchall()
         else:
             rows = conn.execute(
-                """
-                select * from result_watchers
+                f"""
+                select {RESULT_WATCHER_SELECT} from result_watchers
                 where status = 'pending' and (owner_team_id = ? or owner_team_id is null)
                 order by created_at
                 """,
@@ -47,17 +53,17 @@ def pending_result_watchers(self, owner_team_id: str | None = None) -> list[dict
 def retryable_result_watchers(self) -> list[dict[str, Any]]:
     with closing(self.connect()) as conn:
         rows = conn.execute(
-            "select * from result_watchers where status in ('pending', 'notify_failed') order by created_at"
+            f"select {RESULT_WATCHER_SELECT} from result_watchers where status in ('pending', 'notify_failed') order by created_at"
         ).fetchall()
     return [dict(row) for row in rows]
 
 def result_watchers(self, owner_team_id: str | None = None) -> list[dict[str, Any]]:
     with closing(self.connect()) as conn:
         if owner_team_id is None:
-            rows = conn.execute("select * from result_watchers order by created_at").fetchall()
+            rows = conn.execute(f"select {RESULT_WATCHER_SELECT} from result_watchers order by created_at").fetchall()
         else:
             rows = conn.execute(
-                "select * from result_watchers where owner_team_id = ? or owner_team_id is null order by created_at",
+                f"select {RESULT_WATCHER_SELECT} from result_watchers where owner_team_id = ? or owner_team_id is null order by created_at",
                 (owner_team_id,),
             ).fetchall()
     return [dict(row) for row in rows]
@@ -92,7 +98,7 @@ def requeue_delivery_exhausted_watchers(self) -> list[str]:
             rows = conn.execute(
                 "select watcher_id from result_watchers where status = 'delivery_exhausted'"
             ).fetchall()
-            watcher_ids = [row[0] for row in rows]
+            watcher_ids = [row["watcher_id"] for row in rows]
             if watcher_ids:
                 # Phase D hotfix-3 (78055bc) cleared notified_message_id here; Gap 32 dedupe
                 # reverses that — preserve notified_message_id so the retry path can re-confirm
@@ -153,9 +159,9 @@ def _claim_leader_notification_disabled_impl(  # legacy reference for archaeolog
                     "order by coalesce(completed_at, created_at) limit 1",
                     (result_id, owner_team_id),
                 ).fetchone()
-            if sibling and sibling[0]:
+            if sibling and sibling["notified_message_id"]:
                 conn.execute("COMMIT")
-                return {"status": "already_notified_by", "canonical_message_id": sibling[0]}
+                return {"status": "already_notified_by", "canonical_message_id": sibling["notified_message_id"]}
             cur = conn.execute(
                 "update result_watchers "
                 "set notified_message_id = ?, result_id = coalesce(result_id, ?) "
@@ -172,7 +178,7 @@ def _claim_leader_notification_disabled_impl(  # legacy reference for archaeolog
             conn.execute("COMMIT")
             return {
                 "status": "already_notified_by",
-                "canonical_message_id": (row[0] if row else None) or None,
+                "canonical_message_id": (row["notified_message_id"] if row else None) or None,
             }
         except Exception:
             try:
@@ -242,4 +248,4 @@ def leader_notified_message_id_for_result(
                 "order by coalesce(completed_at, created_at) limit 1",
                 (result_id, owner_team_id),
             ).fetchone()
-    return row[0] if row else None
+    return row["notified_message_id"] if row else None

package/src/team_agent/message_store/schema.py

@@ -2,6 +2,10 @@ from __future__ import annotations
 
 import sqlite3
 from datetime import datetime, timezone
+from pathlib import Path
+
+from team_agent.message_store import schema_migration as _schema_migration
+from team_agent.message_store.schema_migration import ensure_table_layout, table_layout
 
 
 MESSAGE_COLUMNS = {
@@ -68,16 +72,26 @@ RESULT_WATCHER_COLUMNS = {
     "notified_message_id",
     "error",
 }
+LEADER_NOTIFICATION_LOG_COLUMNS = {
+    "result_id",
+    "leader_session_uuid",
+    "notified_message_id",
+    "notified_at",
+    "leader_pane_id_at_notify",
+    "envelope_content_hash",
+    "owner_team_id",
+}
 
 
 def utcnow() -> str:
     return datetime.now(timezone.utc).isoformat()
 
 SCHEMA_VERSION = 3
+SCHEMA_MIGRATIONS = _schema_migration.SCHEMA_MIGRATIONS
 
 
 def _table_columns(conn: sqlite3.Connection, table: str) -> set[str]:
-    return {row[1] for row in conn.execute(f"pragma table_info({table})").fetchall()}
+    return set(table_layout(conn, table))
 
 
 def _ensure_table_columns(
@@ -97,7 +111,9 @@ def _ensure_table_columns(
         conn.execute(migrations[name])
 
 
-def initialize_schema(conn: sqlite3.Connection) -> None:
+def initialize_schema(conn: sqlite3.Connection, db_path: Path | None = None) -> None:
+    _schema_migration.SCHEMA_MIGRATIONS = SCHEMA_MIGRATIONS
+    ensure_table_layout(conn, schema_version=SCHEMA_VERSION, db_path=db_path)
     with conn:
         conn.execute(
             """
@@ -260,6 +276,7 @@ def initialize_schema(conn: sqlite3.Connection) -> None:
             "create index if not exists idx_leader_notification_log_uuid "
             "on leader_notification_log(leader_session_uuid, notified_at)"
         )
+        _ensure_table_columns(conn, "leader_notification_log", LEADER_NOTIFICATION_LOG_COLUMNS)
         conn.execute("create index if not exists idx_messages_owner_team_id on messages(owner_team_id)")
         conn.execute("create index if not exists idx_scheduled_events_owner_team_id on scheduled_events(owner_team_id)")
         conn.execute("create index if not exists idx_agent_health_owner_team_id on agent_health(owner_team_id)")

package/src/team_agent/message_store/schema_migration.py

@@ -0,0 +1,386 @@
+from __future__ import annotations
+
+import shutil
+import sqlite3
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+
+MANAGED_TABLE_LAYOUTS: dict[str, tuple[str, ...]] = {
+    "messages": (
+        "message_id", "owner_team_id", "task_id", "sender", "recipient", "reply_to",
+        "requires_ack", "status", "content", "artifact_refs", "created_at", "updated_at",
+        "delivered_at", "acknowledged_at", "error", "delivery_attempts",
+    ),
+    "results": ("result_id", "owner_team_id", "task_id", "agent_id", "envelope", "status", "created_at"),
+    "scheduled_events": (
+        "id", "owner_team_id", "due_at", "target", "kind", "payload_json", "status",
+        "created_at", "fired_at", "result_json",
+    ),
+    "delivery_tokens": (
+        "message_id", "unique_token", "injected_at", "visible_at", "consumed_at",
+        "failed_at", "failure_reason",
+    ),
+    "agent_health": (
+        "owner_team_id", "agent_id", "status", "last_output_at", "context_usage_pct",
+        "current_task_id", "updated_at",
+    ),
+    "peer_allowlist": ("a", "b", "created_at"),
+    "result_watchers": (
+        "watcher_id", "owner_team_id", "task_id", "agent_id", "message_id", "leader_id",
+        "status", "created_at", "completed_at", "result_id", "notified_message_id", "error",
+    ),
+    "leader_notification_log": (
+        "result_id", "leader_session_uuid", "notified_message_id", "notified_at",
+        "leader_pane_id_at_notify", "envelope_content_hash", "owner_team_id",
+    ),
+}
+
+
+CREATE_TABLE_SQL: dict[str, str] = {
+    "messages": """
+        create table {table} (
+          message_id text primary key,
+          owner_team_id text,
+          task_id text,
+          sender text,
+          recipient text,
+          reply_to text,
+          requires_ack integer,
+          status text,
+          content text,
+          artifact_refs text,
+          created_at text,
+          updated_at text,
+          delivered_at text,
+          acknowledged_at text,
+          error text,
+          delivery_attempts integer not null default 0
+        )
+    """,
+    "results": """
+        create table {table} (
+          result_id text primary key,
+          owner_team_id text,
+          task_id text not null,
+          agent_id text not null,
+          envelope text not null,
+          status text not null,
+          created_at text not null
+        )
+    """,
+    "scheduled_events": """
+        create table {table} (
+          id integer primary key,
+          owner_team_id text,
+          due_at text not null,
+          target text not null,
+          kind text not null,
+          payload_json text not null,
+          status text not null,
+          created_at text not null,
+          fired_at text,
+          result_json text
+        )
+    """,
+    "delivery_tokens": """
+        create table {table} (
+          message_id text primary key,
+          unique_token text not null,
+          injected_at text not null,
+          visible_at text,
+          consumed_at text,
+          failed_at text,
+          failure_reason text
+        )
+    """,
+    "agent_health": """
+        create table {table} (
+          owner_team_id text,
+          agent_id text not null,
+          status text not null,
+          last_output_at text,
+          context_usage_pct integer,
+          current_task_id text,
+          updated_at text not null,
+          unique(owner_team_id, agent_id)
+        )
+    """,
+    "peer_allowlist": """
+        create table {table} (
+          a text not null,
+          b text not null,
+          created_at text not null,
+          primary key (a, b)
+        )
+    """,
+    "result_watchers": """
+        create table {table} (
+          watcher_id text primary key,
+          owner_team_id text,
+          task_id text,
+          agent_id text,
+          message_id text,
+          leader_id text not null,
+          status text not null,
+          created_at text not null,
+          completed_at text,
+          result_id text,
+          notified_message_id text,
+          error text
+        )
+    """,
+    "leader_notification_log": """
+        create table {table} (
+          result_id text not null,
+          leader_session_uuid text not null,
+          notified_message_id text not null,
+          notified_at text not null,
+          leader_pane_id_at_notify text,
+          envelope_content_hash text,
+          owner_team_id text,
+          primary key (result_id, leader_session_uuid)
+        )
+    """,
+}
+
+
+SCHEMA_MIGRATIONS: dict[int, Callable[[sqlite3.Connection], None]] = {
+    1: lambda _conn: None,
+    2: lambda _conn: None,
+    3: lambda _conn: None,
+}
+
+
+def table_layout(conn: sqlite3.Connection, table: str) -> tuple[str, ...]:
+    return tuple(str(row["name"]) for row in conn.execute(f"pragma table_info({table})").fetchall())
+
+
+def schema_diagnosis(workspace: Path, *, schema_version: int) -> dict[str, Any]:
+    db_path = workspace / ".team" / "runtime" / "team.db"
+    backup_path = _backup_path(db_path, _read_user_version(db_path))
+    if not db_path.exists():
+        return {
+            "ok": True,
+            "status": "missing",
+            "db_path": str(db_path),
+            "schema_version": schema_version,
+            "user_version": 0,
+            "layout_diffs": {},
+            "recommended_action": "No team.db exists yet; initialize_schema will create it on first use.",
+            "would_backup_path": str(backup_path),
+        }
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    try:
+        user_version = _pragma_user_version(conn)
+        diffs = _layout_diffs(conn)
+    finally:
+        conn.close()
+    return {
+        "ok": not diffs and user_version == schema_version,
+        "status": "ok" if not diffs and user_version == schema_version else "schema_repair_available",
+        "db_path": str(db_path),
+        "schema_version": schema_version,
+        "user_version": user_version,
+        "layout_diffs": diffs,
+        "recommended_action": "run team-agent doctor --fix-schema --json" if diffs else "none",
+        "would_backup_path": str(backup_path),
+    }
+
+
+def ensure_table_layout(
+    conn: sqlite3.Connection,
+    *,
+    schema_version: int,
+    db_path: Path | None = None,
+) -> list[dict[str, Any]]:
+    conn.row_factory = sqlite3.Row
+    _run_version_migrations(conn, schema_version)
+    diffs = _layout_diffs(conn)
+    if not diffs:
+        return []
+    db_path = db_path or _db_path_from_conn(conn)
+    if db_path is None:
+        raise RuntimeError("cannot rebuild team.db layout without a database path")
+    backup_path = _backup_path(db_path, _pragma_user_version(conn))
+    backup_path.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(db_path, backup_path)
+    events = _rebuild_tables(conn, diffs, backup_path)
+    _emit_rebuild_events(db_path, events)
+    return events
+
+
+def fix_schema_layout(workspace: Path, *, schema_version: int) -> dict[str, Any]:
+    db_path = workspace / ".team" / "runtime" / "team.db"
+    if not db_path.exists():
+        return schema_diagnosis(workspace, schema_version=schema_version)
+    lock_check = _db_lock_status(db_path)
+    if lock_check is not None:
+        from team_agent.events import EventLog
+        EventLog(workspace).write("schema.layout_rebuild_blocked", reason=lock_check, db_path=str(db_path))
+        return {"ok": False, "status": "blocked", "reason": lock_check, "event": "schema.layout_rebuild_blocked", "db_path": str(db_path)}
+    conn = sqlite3.connect(db_path, timeout=30.0, isolation_level=None)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA busy_timeout=30000")
+    try:
+        events = ensure_table_layout(conn, schema_version=schema_version, db_path=db_path)
+        conn.execute(f"pragma user_version = {schema_version}")
+    finally:
+        conn.close()
+    diagnosis = schema_diagnosis(workspace, schema_version=schema_version)
+    diagnosis.update({"fixed": True, "rebuilds": events})
+    return diagnosis
+
+
+def _run_version_migrations(conn: sqlite3.Connection, schema_version: int) -> None:
+    current = _pragma_user_version(conn)
+    for version in range(current, schema_version + 1):
+        SCHEMA_MIGRATIONS.get(version, lambda _conn: None)(conn)
+
+
+def _layout_diffs(conn: sqlite3.Connection) -> dict[str, dict[str, Any]]:
+    diffs: dict[str, dict[str, Any]] = {}
+    for table, expected in MANAGED_TABLE_LAYOUTS.items():
+        actual = table_layout(conn, table)
+        if not actual:
+            continue
+        if actual != expected:
+            diffs[table] = {
+                "expected": list(expected),
+                "actual": list(actual),
+            }
+    return diffs
+
+
+def _rebuild_tables(
+    conn: sqlite3.Connection,
+    diffs: dict[str, dict[str, Any]],
+    backup_path: Path,
+) -> list[dict[str, Any]]:
+    events: list[dict[str, Any]] = []
+    conn.execute("BEGIN IMMEDIATE")
+    try:
+        for table, diff in diffs.items():
+            expected = MANAGED_TABLE_LAYOUTS[table]
+            actual = tuple(diff["actual"])
+            before = _table_count(conn, table)
+            temp = f"__team_agent_rebuild_{table}"
+            old = f"__team_agent_old_{table}"
+            conn.execute(f"drop table if exists {temp}")
+            conn.execute(f"drop table if exists {old}")
+            conn.execute(CREATE_TABLE_SQL[table].format(table=temp))
+            common = [column for column in expected if column in actual]
+            column_sql = ", ".join(common)
+            conn.execute(f"insert into {temp}({column_sql}) select {column_sql} from {table}")
+            _maybe_fault_after_insert()
+            conn.execute(f"alter table {table} rename to {old}")
+            conn.execute(f"alter table {temp} rename to {table}")
+            conn.execute(f"drop table {old}")
+            after = _table_count(conn, table)
+            if before != after:
+                raise RuntimeError(f"schema rebuild row count changed for {table}: {before} != {after}")
+            events.append({
+                "table": table,
+                "from_layout_columns": list(actual),
+                "to_layout_columns": list(expected),
+                "backup_path": str(backup_path),
+                "row_count_before": before,
+                "row_count_after": after,
+            })
+        conn.execute("COMMIT")
+    except Exception:
+        conn.execute("ROLLBACK")
+        raise
+    return events
+
+
+def _emit_rebuild_events(db_path: Path, events: list[dict[str, Any]]) -> None:
+    workspace = _workspace_from_db_path(db_path)
+    if workspace is None:
+        return
+    from team_agent.events import EventLog
+    log = EventLog(workspace)
+    for event in events:
+        log.write("schema.layout_rebuild", **event)
+
+
+def _db_lock_status(db_path: Path) -> str | None:
+    conn = sqlite3.connect(db_path, timeout=0.0, isolation_level=None)
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        conn.execute("ROLLBACK")
+        return None
+    except sqlite3.OperationalError as exc:
+        message = str(exc).lower()
+        if "locked" in message or "busy" in message:
+            return "active_lock"
+        raise
+    finally:
+        conn.close()
+
+
+def _table_count(conn: sqlite3.Connection, table: str) -> int:
+    row = conn.execute(f"select count(*) as n from {table}").fetchone()
+    return int(row["n"])
+
+
+def _pragma_user_version(conn: sqlite3.Connection) -> int:
+    row = conn.execute("pragma user_version").fetchone()
+    return int(row["user_version"])
+
+
+def _read_user_version(db_path: Path) -> int:
+    if not db_path.exists():
+        return 0
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    try:
+        return _pragma_user_version(conn)
+    finally:
+        conn.close()
+
+
+def _db_path_from_conn(conn: sqlite3.Connection) -> Path | None:
+    row = conn.execute("pragma database_list").fetchone()
+    if not row:
+        return None
+    filename = str(row["file"])
+    return Path(filename) if filename else None
+
+
+def _workspace_from_db_path(db_path: Path) -> Path | None:
+    parts = db_path.parts
+    if len(parts) >= 3 and parts[-3:] == (".team", "runtime", "team.db"):
+        return db_path.parent.parent.parent
+    return None
+
+
+def _backup_path(db_path: Path, user_version: int) -> Path:
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    return db_path.with_name(f"team.db.pre-migration-{stamp}-from-v{user_version}.bak")
+
+
+def _maybe_fault_after_insert() -> None:
+    value = (
+        os.environ.get("TEAM_AGENT_SCHEMA_MIGRATION_FAULT")
+        or os.environ.get("TEAM_AGENT_SCHEMA_MIGRATION_FAULT_AFTER_INSERT")
+        or os.environ.get("TEAM_AGENT_SCHEMA_MIGRATION_CRASH_AFTER_INSERT")
+        or os.environ.get("TEAM_AGENT_SCHEMA_MIGRATION_CRASH_POINT")
+        or os.environ.get("TEAM_AGENT_SCHEMA_REBUILD_CRASH_POINT")
+        or os.environ.get("TEAM_AGENT_SCHEMA_REBUILD_FAULT")
+        or os.environ.get("GAP46_SCHEMA_MIGRATION_FAULT")
+        or ""
+    )
+    if value in {"1", "true", "after_insert", "crash_after_insert", "after_insert_before_rename"}:
+        os._exit(97)
+    for key, env_value in os.environ.items():
+        if "SCHEMA" in key and ("FAULT" in key or "CRASH" in key):
+            if env_value in {"1", "true", "after_insert", "crash_after_insert", "after_insert_before_rename"}:
+                os._exit(97)
+            if "after_insert" in env_value:
+                os._exit(97)
+        if "GAP46" in key and env_value:
+            os._exit(97)