taskops-cli 0.2.0__py3-none-any.whl

taskops/storage/_events.py

@@ -0,0 +1,127 @@
+"""The events table — the append-only log every projection is derived from.
+
+Writes are `INSERT OR IGNORE` on a content-hash id, which is what makes the whole
+replication story work: the same event can arrive from a `git pull` and from the
+relay, and the second one is a no-op instead of a duplicate.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+from ..contracts import Event
+from ._rows import dumps, to_event
+
+__all__ = ["EventTable"]
+
+
+class EventTable:
+    def __init__(self, db: sqlite3.Connection) -> None:
+        self.db = db
+
+    def append(self, event: Event, *, exported: bool = False) -> bool:
+        """True if this event is new here. False means we already had it.
+
+        `seq` is assigned by SQLite's own rowid sequence via a subquery rather
+        than AUTOINCREMENT on the primary key, because the primary key has to stay
+        the content hash — so local ordering and global identity are two columns
+        instead of one compromise.
+        """
+        cursor = self.db.execute(
+            "INSERT OR IGNORE INTO events (id, seq, task, actor, kind, body, ts, "
+            "exported) VALUES (?, (SELECT COALESCE(MAX(seq), 0) + 1 FROM events), "
+            "?, ?, ?, ?, ?, ?)",
+            (event["id"], event["task"], event["actor"], event["kind"],
+             dumps(event["body"]), event["ts"], int(exported)))
+        return cursor.rowcount == 1
+
+    def of_task(self, task_id: str, *, kinds: tuple[str, ...] = ()) -> list[Event]:
+        """One task's history, oldest first."""
+        sql = "SELECT * FROM events WHERE task=?"
+        params: tuple[object, ...] = (task_id,)
+        if kinds:
+            sql += f" AND kind IN ({', '.join('?' * len(kinds))})"
+            params += kinds
+        rows = self.db.execute(sql + " ORDER BY ts, seq", params).fetchall()
+        return [to_event(row) for row in rows]
+
+    def since(self, ts: float, *, limit: int = 500) -> list[Event]:
+        """Everything after a moment — what a standup and the live feed both read."""
+        rows = self.db.execute("SELECT * FROM events WHERE ts > ? "
+                               "ORDER BY ts, seq LIMIT ?", (ts, limit)).fetchall()
+        return [to_event(row) for row in rows]
+
+    def newest_since(self, ts: float, *, limit: int) -> list[Event]:
+        """The LAST `limit` events in a window, oldest first — what a history view reads.
+
+        Not `since(...)[-limit:]`: `LIMIT` applies to the ascending scan, so that expression takes
+        the OLDEST rows and then shows them as the newest. On a thirty-day window over a busy
+        project it produced a timeline that was entirely correct and entirely the wrong end.
+
+        Ordered DESC to pick the tail and reversed here, so callers still get the log's own order.
+        """
+        rows = self.db.execute("SELECT * FROM events WHERE ts > ? "
+                               "ORDER BY ts DESC, seq DESC LIMIT ?", (ts, limit)).fetchall()
+        return [to_event(row) for row in reversed(rows)]
+
+    def after_seq(self, seq: int, *, limit: int = 200) -> list[Event]:
+        """The studio's cursor read: strictly local order, no clock involved.
+
+        A separate process cannot see the in-process event bus, so the live board
+        polls this. Ordering by `ts` there would drop an event whose clock came
+        from a machine running slightly behind.
+        """
+        return self.page_after(seq, limit=limit)[0]
+
+    def page_after(self, seq: int, *, limit: int) -> tuple[list[Event], int]:
+        """The same read, plus the seq of the LAST row scanned — the replication cursor.
+
+        `Event` carries no `seq` on purpose: seq is this machine's local order, not the event's
+        identity, and putting it in the contract would invite a puller to store another
+        machine's numbering as if it were its own. So a page that ends mid-log has to hand its
+        cursor back beside the events rather than inside them.
+
+        Last SCANNED and not last returned, because a caller that filters the page (the HTTP
+        exchange drops local-only kinds) would otherwise re-scan the dropped tail forever.
+        """
+        rows = self.db.execute(
+            "SELECT * FROM events WHERE seq > ? ORDER BY seq LIMIT ?", (seq, limit)
+        ).fetchall()
+        return [to_event(row) for row in rows], int(rows[-1]["seq"]) if rows else seq
+
+    def max_seq(self) -> int:
+        row = self.db.execute("SELECT COALESCE(MAX(seq), 0) AS n FROM events").fetchone()
+        return int(row["n"])
+
+    def unexported(self, *, limit: int = 1000) -> list[Event]:
+        """What the committed log has not seen yet, oldest first."""
+        rows = self.db.execute("SELECT * FROM events WHERE exported = 0 "
+                               "ORDER BY seq LIMIT ?", (limit,)).fetchall()
+        return [to_event(row) for row in rows]
+
+    def mark_exported(self, ids: list[str]) -> None:
+        marks = ", ".join("?" * len(ids))
+        self.db.execute(f"UPDATE events SET exported = 1 WHERE id IN ({marks})",
+                        tuple(ids))
+
+    def count_by_task(self, kind: str) -> dict[str, int]:
+        """How many events of one kind each task has. ONE query for a whole board.
+
+        A board needs a commit count per card, and asking per task is what turns a
+        page that was fine at fifty tasks into one that stalls at five hundred.
+        """
+        rows = self.db.execute("SELECT task, COUNT(*) AS n FROM events "
+                               "WHERE kind=? GROUP BY task", (kind,)).fetchall()
+        return {str(row["task"]): int(row["n"]) for row in rows}
+
+    def latest_by_task(self, kind: str) -> dict[str, Event]:
+        """The most recent event of one kind, per task — the fleet view's read.
+
+        `MAX(seq)` in a subquery rather than sorting in Python: this runs on every
+        board refresh, and `activity` is by far the largest kind in the table.
+        """
+        rows = self.db.execute(
+            "SELECT * FROM events WHERE kind=? AND seq IN ("
+            "  SELECT MAX(seq) FROM events WHERE kind=? GROUP BY task)",
+            (kind, kind)).fetchall()
+        return {str(row["task"]): to_event(row) for row in rows}

taskops/storage/_leases.py

@@ -0,0 +1,108 @@
+"""The leases table — where a hundred agents avoid each other.
+
+The claim is ONE statement: `INSERT INTO leases` with `task` as the primary key,
+preceded by a delete of whatever has expired. Two agents racing for one task are
+two inserts on one key, and SQLite decides — no advisory lock, no lock file, no
+retry loop. `Store` opens claims with BEGIN IMMEDIATE so the write lock is taken
+before the expiry sweep reads, which is what stops the classic interleaving where
+both sweeps delete the same dead lease and both then insert.
+
+Every method takes `now` rather than reading a clock: expiry is the behaviour most
+worth testing, and a test that has to sleep for fifteen minutes is a test nobody
+runs.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+from ..contracts import Lease
+from ._rows import to_lease
+
+__all__ = ["LeaseTable"]
+
+
+class LeaseTable:
+    def __init__(self, db: sqlite3.Connection) -> None:
+        self.db = db
+
+    def sweep(self, now: float) -> list[str]:
+        """Drop expired leases; return the tasks that just came free.
+
+        Returned rather than silently dropped because a task whose agent died has
+        to be walked back out of `claimed` into `ready`, and only the caller knows
+        how to write that transition.
+        """
+        rows = self.db.execute("SELECT task FROM leases WHERE expires <= ?", (now,)).fetchall()
+        self.db.execute("DELETE FROM leases WHERE expires <= ?", (now,))
+        return [str(row["task"]) for row in rows]
+
+    def acquire(self, lease: Lease) -> bool:
+        """True if the claim landed, False if somebody else holds it.
+
+        `INSERT OR IGNORE` and then checking the row count is the atomic test —
+        asking first and inserting second is the race this exists to avoid.
+        """
+        cursor = self.db.execute(
+            "INSERT OR IGNORE INTO leases (task, actor, session, branch, acquired, "
+            "expires) VALUES (?, ?, ?, ?, ?, ?)",
+            (lease["task"], lease["actor"], lease["session"], lease["branch"],
+             lease["acquired"], lease["expires"]))
+        return cursor.rowcount == 1
+
+    def get(self, task_id: str) -> Lease | None:
+        row = self.db.execute("SELECT * FROM leases WHERE task=?", (task_id,)).fetchone()
+        return to_lease(row) if row else None
+
+    def held_by(self, task_id: str, actor: str, now: float) -> bool:
+        """Does this actor hold a LIVE lease on this task.
+
+        The precondition of every write an agent makes, so it checks expiry here
+        rather than trusting a sweep to have run: a lease that lapsed one second
+        ago is not a lease, whatever the table still says.
+        """
+        row = self.db.execute(
+            "SELECT 1 FROM leases WHERE task=? AND actor=? AND expires > ?", (task_id, actor, now)
+        ).fetchone()
+        return row is not None
+
+    def renew(self, *, task_id: str, actor: str, expires: float) -> bool:
+        """Push the deadline out. Scoped to the holder, so a renewal cannot be
+        used to steal a task by naming somebody else's."""
+        cursor = self.db.execute(
+            "UPDATE leases SET expires=? WHERE task=? AND actor=?", (expires, task_id, actor)
+        )
+        return cursor.rowcount == 1
+
+    def set_branch(self, *, task_id: str, branch: str) -> None:
+        self.db.execute("UPDATE leases SET branch=? WHERE task=?", (branch, task_id))
+
+    def set_session(self, *, task_id: str, session: str) -> None:
+        """Re-point a lease at the session now running it.
+
+        A resumed Claude Code session gets a NEW id, so without this the board shows a
+        live claim whose transcript path names a process that no longer exists.
+        """
+        self.db.execute("UPDATE leases SET session=? WHERE task=?", (session, task_id))
+
+    def release(self, task_id: str) -> None:
+        self.db.execute("DELETE FROM leases WHERE task=?", (task_id,))
+
+    def live(self, now: float) -> list[Lease]:
+        rows = self.db.execute(
+            "SELECT * FROM leases WHERE expires > ? ORDER BY acquired", (now,)
+        ).fetchall()
+        return [to_lease(row) for row in rows]
+
+    def of_actor(self, actor: str, now: float) -> list[Lease]:
+        rows = self.db.execute(
+            "SELECT * FROM leases WHERE actor=? AND expires > ? ORDER BY acquired", (actor, now)
+        ).fetchall()
+        return [to_lease(row) for row in rows]
+
+    def of_session(self, session: str) -> list[Lease]:
+        """What this Claude Code session is holding — the SessionStart read."""
+        rows = self.db.execute(
+            "SELECT * FROM leases WHERE session=? ORDER BY acquired", (session,)
+        ).fetchall()
+        return [to_lease(row) for row in rows]

taskops/storage/_rows.py

@@ -0,0 +1,90 @@
+"""Rows in, contracts out. The one place that knows a column is JSON.
+
+`labels`, `files` and `body` are JSON text in SQLite and lists or dicts everywhere
+else. Doing that conversion in each table object meant four places knowing which
+columns are encoded, and the fourth one always forgets — so it happens here, and a
+table's job shrinks to writing SQL.
+
+A stored value that is not valid JSON DEGRADES to empty rather than raising: these
+columns are also written by `sync` from a file another machine's taskops appended,
+and one malformed line must not make the whole board unreadable. The event
+`body` is the extreme case — a newer version writes shapes this one has not seen.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from typing import Any, cast
+
+from ..contracts import Event, Lease, Task
+
+__all__ = ["dumps", "as_list", "as_dict", "to_task", "to_lease", "to_event"]
+
+
+def dumps(value: object) -> str:
+    """Compact and key-sorted: the text is compared across machines during sync,
+    so two equal values must serialize identically."""
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), default=str)
+
+
+def as_list(raw: object) -> list[str]:
+    parsed = _loads(raw)
+    if not isinstance(parsed, list):
+        return []
+    return [str(item) for item in cast("list[object]", parsed)]
+
+
+def as_dict(raw: object) -> dict[str, Any]:
+    parsed = _loads(raw)
+    return cast("dict[str, Any]", parsed) if isinstance(parsed, dict) else {}
+
+
+def _loads(raw: object) -> object:
+    if not isinstance(raw, str) or not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+
+
+def to_task(row: sqlite3.Row) -> Task:
+    return Task(
+        id=str(row["id"]),
+        title=str(row["title"]),
+        spec=str(row["spec"]),
+        status=row["status"],
+        priority=int(row["priority"]),
+        parent=str(row["parent"]) if row["parent"] else None,
+        labels=as_list(row["labels"]),
+        files=as_list(row["files"]),
+        created_by=str(row["created_by"]),
+        # `or ""` and not `str(...)`: a row that predates the column reads as NULL after the ALTER,
+        # and `str(None)` would put the string "None" in it — an assignee nobody can be.
+        assignee=str(row["assignee"] or ""),
+        created=float(row["created"]),
+        updated=float(row["updated"]),
+    )
+
+
+def to_lease(row: sqlite3.Row) -> Lease:
+    return Lease(
+        task=str(row["task"]),
+        actor=str(row["actor"]),
+        session=str(row["session"]),
+        branch=str(row["branch"]),
+        acquired=float(row["acquired"]),
+        expires=float(row["expires"]),
+    )
+
+
+def to_event(row: sqlite3.Row) -> Event:
+    return Event(
+        id=str(row["id"]),
+        task=str(row["task"]),
+        actor=str(row["actor"]),
+        kind=row["kind"],
+        body=as_dict(row["body"]),
+        ts=float(row["ts"]),
+    )

taskops/storage/_tasks.py

@@ -0,0 +1,124 @@
+"""The tasks table."""
+
+from __future__ import annotations
+
+import sqlite3
+
+from .._errors import BadRequest, NoSuchTask
+from .._types import EDITABLE_FIELDS, Status
+from ..contracts import Task
+from ._rows import dumps, to_task
+
+__all__ = ["TaskTable"]
+
+_COLUMNS = ("id", "title", "spec", "status", "priority", "parent", "labels",
+            "files", "created_by", "assignee", "created", "updated")
+
+
+def _values(task: Task) -> tuple[object, ...]:
+    """A task in `_COLUMNS` order. One function, so the two orders cannot drift."""
+    return (task["id"], task["title"], task["spec"], task["status"],
+            task["priority"], task["parent"], dumps(task["labels"]),
+            dumps(task["files"]), task["created_by"], task["assignee"],
+            task["created"], task["updated"])
+
+
+class TaskTable:
+    def __init__(self, db: sqlite3.Connection) -> None:
+        self.db = db
+
+    def insert(self, task: Task) -> None:
+        """Fails LOUDLY on a duplicate id rather than replacing.
+
+        Task ids are random, so a collision is either a 1-in-16-million accident or
+        a caller re-sending a plan — and silently overwriting the second case would
+        destroy a task somebody is already working on.
+        """
+        marks = ", ".join("?" * len(_COLUMNS))
+        self.db.execute(f"INSERT INTO tasks ({', '.join(_COLUMNS)}) "
+                        f"VALUES ({marks})", _values(task))
+
+    def upsert(self, task: Task) -> None:
+        """Last-writer-wins by `updated`, for the sync path only.
+
+        Two machines editing one task is rare and the log records both edits, so
+        the loser is recoverable. Refusing the import instead would make a
+        `git pull` fail on something git itself merged cleanly.
+        """
+        if self.get(task["id"]) is None:
+            self.insert(task)
+            return
+        self.db.execute(
+            "UPDATE tasks SET title=?, spec=?, status=?, priority=?, parent=?, "
+            "labels=?, files=?, updated=? WHERE id=? AND updated<=?",
+            (task["title"], task["spec"], task["status"], task["priority"],
+             task["parent"], dumps(task["labels"]), dumps(task["files"]),
+             task["updated"], task["id"], task["updated"]))
+
+    def get(self, task_id: str) -> Task | None:
+        row = self.db.execute("SELECT * FROM tasks WHERE id=?", (task_id,)).fetchone()
+        return to_task(row) if row else None
+
+    def need(self, task_id: str) -> Task:
+        """The read that refuses to return None — most callers cannot proceed."""
+        found = self.get(task_id)
+        if found is None:
+            raise NoSuchTask.named(task_id)
+        return found
+
+    def set_assignee(self, task_id: str, actor: str, *, when: float) -> None:
+        """Point a card at somebody, or back at the pool with "".
+
+        Its own method rather than a general `update`: assignment changes who the SCHEDULER will
+        offer the card to, which is a different kind of write from editing a title, and the two want
+        different events in the log.
+        """
+        self.db.execute("UPDATE tasks SET assignee=?, updated=? WHERE id=?",
+                        (actor, when, task_id))
+
+    def set_field(self, task_id: str, field: str, value: object, *, when: float) -> None:
+        """Rewrite ONE editable column — a title, a spec, a priority.
+
+        The column name is interpolated, so it is checked against `EDITABLE_FIELDS` first and
+        nowhere else: a whitelist at the only place that builds the SQL is the difference
+        between a typo and an injection, and every caller above reaches this one door.
+        """
+        if field not in EDITABLE_FIELDS:
+            raise BadRequest(f"`{field}` is not editable — use one of "
+                             f"{', '.join(EDITABLE_FIELDS)}")
+        self.db.execute(f"UPDATE tasks SET {field}=?, updated=? WHERE id=?",
+                        (value, when, task_id))
+
+    def set_status(self, task_id: str, status: Status, *, when: float) -> None:
+        self.db.execute("UPDATE tasks SET status=?, updated=? WHERE id=?",
+                        (status, when, task_id))
+
+    def all(self) -> list[Task]:
+        """Every task, most urgent first. The board's one read."""
+        rows = self.db.execute("SELECT * FROM tasks "
+                               "ORDER BY priority, created").fetchall()
+        return [to_task(row) for row in rows]
+
+    def with_status(self, statuses: tuple[str, ...]) -> list[Task]:
+        marks = ", ".join("?" * len(statuses))
+        rows = self.db.execute(f"SELECT * FROM tasks WHERE status IN ({marks}) "
+                               f"ORDER BY priority, created", statuses).fetchall()
+        return [to_task(row) for row in rows]
+
+    def children(self, parent: str) -> list[Task]:
+        rows = self.db.execute("SELECT * FROM tasks WHERE parent=? "
+                               "ORDER BY priority, created", (parent,)).fetchall()
+        return [to_task(row) for row in rows]
+
+    def search(self, text: str, *, limit: int = 20) -> list[Task]:
+        """Substring over title and spec, case-insensitive.
+
+        Not FTS5: it is a compile-time option missing from some distro pythons, and
+        a task list is thousands of rows rather than millions. A LIKE scan that
+        always works beats an index absent on a teammate's machine.
+        """
+        like = f"%{text.lower()}%"
+        rows = self.db.execute(
+            "SELECT * FROM tasks WHERE LOWER(title) LIKE ? OR LOWER(spec) LIKE ? "
+            "ORDER BY priority, created LIMIT ?", (like, like, limit)).fetchall()
+        return [to_task(row) for row in rows]

taskops/storage/locate.py

@@ -0,0 +1,76 @@
+"""Finding the project from any path inside it.
+
+Every surface takes a path from someone who was not thinking about where the
+project root is — an agent passes its cwd, a git hook passes wherever git ran it,
+the studio passes whatever was typed. Walking up for `.taskops/` is what makes all
+three the same call, and it is the same convention as `.git` for the same reason.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .._errors import NotInitialized
+
+__all__ = ["PROJECT_DIR", "DB_FILE", "LOG_FILE", "GUIDE_FILE", "REPORTS_DIR", "ENV_ROOT",
+           "resolve_root", "find_root"]
+
+PROJECT_DIR = ".taskops"
+
+DB_FILE = f"{PROJECT_DIR}/db.sqlite"
+"""GITIGNORED. Derived state — every row in it can be rebuilt from the log."""
+
+LOG_FILE = f"{PROJECT_DIR}/events.jsonl"
+"""COMMITTED. The shared source of truth: append-only, one JSON object per line,
+ids that are content hashes. That combination is what lets two developers merge
+their agents' work with `git pull` and no server — a conflict needs two writers of
+the same line, and appenders never produce one."""
+
+GUIDE_FILE = f"{PROJECT_DIR}/GUIDE.md"
+"""The agent-facing manual `taskops init` writes. Read by humans too, which is the
+point: one document, so the two cannot be told different things."""
+
+
+REPORTS_DIR = f"{PROJECT_DIR}/reports"
+"""COMMITTED, unlike everything else generated here. A daily dossier is written ONCE and
+then narrated by a human or a session — so it stops being derived state the moment somebody
+adds a paragraph to it, and a regenerated copy could not carry that paragraph back."""
+
+
+ENV_ROOT = "TASKOPS_ROOT"
+"""Overrides the search entirely. THE mechanism that makes dispatched workers work.
+
+A worker runs in a `git worktree`, which has no `.taskops/` of its own — so walking up would find
+either nothing or, worse, some unrelated project further up the filesystem. With this set, N workers
+in N worktrees all coordinate through ONE board, which is the whole point of dispatching them.
+
+An override and not a fallback: if it is set and wrong, that is an error worth seeing rather than a
+silent walk up to a different project.
+"""
+
+
+def find_root(start: Path | str) -> Path | None:
+    """The nearest ancestor holding `.taskops/`, or None. `$TASKOPS_ROOT` wins outright."""
+    forced = os.environ.get(ENV_ROOT, "").strip()
+    if forced:
+        candidate = Path(forced).expanduser().resolve()
+        return candidate if (candidate / PROJECT_DIR).is_dir() else None
+    here = Path(start).expanduser().resolve()
+    for candidate in (here, *here.parents):
+        if (candidate / PROJECT_DIR).is_dir():
+            return candidate
+    return None
+
+
+def resolve_root(start: Path | str) -> Path:
+    """Same, but a missing project is an error naming the fix.
+
+    Raising rather than creating: `taskops init` also installs git hooks and
+    writes the guide, and a store that appeared silently under whatever directory
+    an agent happened to be in would be a project nobody knows exists.
+    """
+    root = find_root(start)
+    if root is None:
+        raise NotInitialized.at(start)
+    return root

taskops/storage/schema.py

@@ -0,0 +1,66 @@
+"""Bringing a database up to date. The tables themselves are in `_ddl`.
+
+One database file per repository at `<repo>/.taskops/db.sqlite`, and it is a CACHE
+— `storage.sync` can rebuild every row from the committed event log, which is why
+it is gitignored and why a schema change needs no data-migration story.
+
+**WAL, unlike megabrain.** That engine documents its rollback-journal choice as a
+property of its workload rather than a preference: writes there are rare, so
+readers already never wait. Here the workload is the opposite — a hundred agents
+renewing leases and appending events continuously — and the studio reads this
+database on every board refresh while they do. Under a rollback journal that
+refresh stalls on each commit; WAL is what lets a reader run beside a writer.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+from ._ddl import DDL
+
+__all__ = ["apply"]
+
+_PRAGMAS = ("PRAGMA journal_mode=WAL", "PRAGMA synchronous=NORMAL")
+"""`synchronous=NORMAL` and not FULL: under WAL that risks losing the last commits
+to an OS crash, never corruption — and the events those commits carry are also in
+the log or re-derivable from git. Paying a full fsync per lease renewal to protect
+data that is recoverable anyway is the wrong trade at a hundred agents.
+
+`foreign_keys` is deliberately NOT set. There are no FK constraints in the schema:
+`sync` imports events referring to tasks a `git pull` has not delivered yet, and a
+constraint would reject exactly the events that make the project converge.
+"""
+
+_LATE_COLUMNS: tuple[tuple[str, str], ...] = (
+    ("tasks", "assignee TEXT NOT NULL DEFAULT ''"),
+)
+"""Columns added after a table shipped, applied with ALTER on every open so a database written by an
+older taskops keeps working with no migration step anyone has to remember.
+
+`assignee` is the mechanism's first user, and it worked exactly as intended: a database created
+before dispatch existed gains the column on its next open, and every row defaults to the open pool —
+which is what those rows meant."""
+
+
+def apply(db: sqlite3.Connection) -> None:
+    """Create everything missing and backfill late columns. Idempotent."""
+    for pragma in _PRAGMAS:
+        db.execute(pragma)
+    db.executescript(DDL)
+    for table, column in _LATE_COLUMNS:
+        _add_column(db, table, column)
+
+
+def _add_column(db: sqlite3.Connection, table: str, column: str) -> None:
+    """Add a late column, tolerating ONLY the already-present case.
+
+    A bare `except OperationalError: pass` also swallows "database is locked",
+    "disk I/O error" and "no such table" — every real reason a migration fails. The
+    database then opens against a schema nobody migrated and fails later, somewhere
+    else, with no trace of the migration that quietly gave up.
+    """
+    try:
+        db.execute(f"ALTER TABLE {table} ADD COLUMN {column}")
+    except sqlite3.OperationalError as err:
+        if "duplicate column name" not in str(err).lower():
+            raise