@team-agent/installer 0.2.4 → 0.2.6

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_schema_indexes, 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(
             """
@@ -256,14 +272,8 @@ def initialize_schema(conn: sqlite3.Connection) -> None:
             )
             """
         )
-        conn.execute(
-            "create index if not exists idx_leader_notification_log_uuid "
-            "on leader_notification_log(leader_session_uuid, notified_at)"
-        )
-        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)")
-        conn.execute("create index if not exists idx_result_watchers_owner_team_id on result_watchers(owner_team_id)")
+        _ensure_table_columns(conn, "leader_notification_log", LEADER_NOTIFICATION_LOG_COLUMNS)
+        ensure_schema_indexes(conn)
         conn.execute(f"pragma user_version = {SCHEMA_VERSION}")
 
 

package/src/team_agent/message_store/schema_migration.py

@@ -0,0 +1,446 @@
+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 if not exists {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 if not exists {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 if not exists {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 if not exists {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 if not exists {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 if not exists {table} (
+          a text not null,
+          b text not null,
+          created_at text not null,
+          primary key (a, b)
+        )
+    """,
+    "result_watchers": """
+        create table if not exists {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 if not exists {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)
+        )
+    """,
+}
+
+
+INDEX_SQL: tuple[str, ...] = (
+    "create index if not exists idx_leader_notification_log_uuid on leader_notification_log(leader_session_uuid, notified_at)",
+    "create index if not exists idx_messages_owner_team_id on messages(owner_team_id)",
+    "create index if not exists idx_scheduled_events_owner_team_id on scheduled_events(owner_team_id)",
+    "create index if not exists idx_agent_health_owner_team_id on agent_health(owner_team_id)",
+    "create index if not exists idx_result_watchers_owner_team_id on result_watchers(owner_team_id)",
+)
+
+
+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 ensure_schema_indexes(conn: sqlite3.Connection) -> None:
+    for statement in INDEX_SQL:
+        conn.execute(statement)
+
+
+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]]:
+    # 0.2.6 CI hotfix #3: hold the SQLite RESERVED lock across the diff
+    # read AND the rebuild writes. Earlier code only acquired BEGIN
+    # IMMEDIATE inside ``_rebuild_tables`` — so a concurrent writer
+    # could squeeze a row in between ``_layout_diffs`` and the rebuild,
+    # and the post-rebuild row-count drift check fired with
+    # before != after even though no schema layout was clobbered.
+    # Wrapping the whole sequence makes the drift check an invariant
+    # (no writer can interleave once we hold the lock).
+    conn.row_factory = sqlite3.Row
+    _run_version_migrations(conn, schema_version)
+    started_tx = False
+    if not conn.in_transaction:
+        conn.execute("BEGIN IMMEDIATE")
+        started_tx = True
+    try:
+        diffs = _layout_diffs(conn)
+        if not diffs:
+            if started_tx:
+                conn.execute("COMMIT")
+                started_tx = False
+            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)
+        if started_tx:
+            conn.execute("COMMIT")
+            started_tx = False
+    except Exception:
+        if started_tx and conn.in_transaction:
+            try:
+                conn.execute("ROLLBACK")
+            except sqlite3.Error:
+                pass
+        raise
+    _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]] = {}
+    if not any(_table_exists(conn, table) for table in MANAGED_TABLE_LAYOUTS):
+        return diffs
+    for table, expected in MANAGED_TABLE_LAYOUTS.items():
+        if not _table_exists(conn, table):
+            diffs[table] = {
+                "expected": list(expected),
+                "actual": [],
+                "missing": True,
+            }
+            continue
+        actual = table_layout(conn, table)
+        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]]:
+    # Caller (``ensure_table_layout``) now holds the BEGIN IMMEDIATE for
+    # the full diff+rebuild window, so the drift check between ``before``
+    # and ``after`` is an invariant rather than a concurrency race. The
+    # inner BEGIN/COMMIT/ROLLBACK was removed alongside that move (a
+    # nested BEGIN raises in SQLite and would mask the outer lock).
+    events: list[dict[str, Any]] = []
+    for table, diff in diffs.items():
+        expected = MANAGED_TABLE_LAYOUTS[table]
+        actual = tuple(diff["actual"])
+        before = 0 if diff.get("missing") else _table_count(conn, table)
+        if diff.get("missing"):
+            conn.execute(CREATE_TABLE_SQL[table].format(table=table))
+            after = _table_count(conn, table)
+            if after != before:
+                raise RuntimeError(f"schema rebuild row count changed for {table}: {before} != {after}")
+            events.append({
+                "table": table,
+                "from_layout_columns": [],
+                "to_layout_columns": list(expected),
+                "backup_path": str(backup_path),
+                "row_count_before": before,
+                "row_count_after": after,
+                "missing": True,
+            })
+            continue
+        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,
+        })
+    ensure_schema_indexes(conn)
+    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 _table_exists(conn: sqlite3.Connection, table: str) -> bool:
+    row = conn.execute(
+        "select name from sqlite_master where type = 'table' and name = ?",
+        (table,),
+    ).fetchone()
+    return row is not None
+
+
+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:
+    allowed_keys = {
+        "TEAM_AGENT_SCHEMA_MIGRATION_CRASH_AT",
+        "GAP46_TEST_CRASH",
+        "GAP46_TEST_PARTIAL_REBUILD",
+    }
+    allowed_values = {"1", "crash", "partial", "after_insert_before_rename"}
+    for key in allowed_keys:
+        value = os.environ.get(key)
+        if value in allowed_values:
+            os._exit(97)