@jaguilar87/gaia 5.0.8 → 5.0.10

package/hooks/modules/tools/bash_validator.py

@@ -911,6 +911,57 @@ class BashValidator:
             reason="Safe by elimination (not blocked, not mutative)",
         )
 
+    def _is_ungranted_t3_component(
+        self, component: str, session_id: str
+    ) -> bool:
+        """Classify a chain component as ungranted-T3 WITHOUT minting or consuming.
+
+        Returns True when the component is a T3 (mutative-verb or
+        flag-dependent) operation for which NO active grant exists -- i.e. the
+        component would, on its own, be blocked pending approval. This is a
+        read-only probe used by the chain COMMAND_SET intake (AC-8) to decide
+        whether >= 2 sub-commands need grouping under ONE consent, BEFORE any
+        per-component minting happens.
+
+        It deliberately does NOT call decide_t3_outcome (no pending minted) and
+        does NOT consume any grant (match_command_set_grant /
+        check_approval_grant are pure lookups; consumption happens later in the
+        real _validate_single_command pass at retry). A component that already
+        matches a COMMAND_SET or semantic grant is treated as NOT ungranted, so
+        it is excluded from a fresh batch.
+        """
+        component = component.strip()
+        if not component:
+            return False
+
+        # Is this T3 (mutative verb or flag-dependent mutation)?
+        detect = detect_mutative_command(component)
+        is_t3 = detect.is_mutative
+        if not is_t3:
+            flag_result = classify_by_flags(component)
+            if (
+                flag_result is not None
+                and flag_result.outcome == FLAG_MUTATIVE
+                and not flag_result.command_family.startswith("git_")
+            ):
+                is_t3 = True
+        if not is_t3:
+            return False
+
+        # Already covered by an active grant? Then it is NOT ungranted -- exclude
+        # it from a fresh batch (pure lookups, no consumption).
+        try:
+            if match_command_set_grant(component) is not None:
+                return False
+        except Exception:
+            pass
+        try:
+            if check_approval_grant(component, session_id=session_id) is not None:
+                return False
+        except Exception:
+            pass
+        return True
+
     def _validate_compound_command(
         self,
         components: List[str],
@@ -918,9 +969,68 @@ class BashValidator:
         session_id: str = "",
         agent_type: str = "",
     ) -> BashValidationResult:
-        """Validate a compound command (multiple components)."""
+        """Validate a compound command (multiple components).
+
+        Chain COMMAND_SET intake (AC-8): when a chain ``a && b && c`` has TWO OR
+        MORE sub-commands that are ungranted T3, classifying them one-at-a-time
+        mints a single-signature pending for the FIRST and short-circuits -- so
+        one approval covers only the first sub-command and the next re-blocks
+        (the double-approval the user hit). To group them, a NON-MINTING
+        classification pass runs FIRST (``_is_ungranted_t3_component``); if >= 2
+        sub-commands are ungranted-T3 (and we are a subagent under the
+        orchestrator), ONE COMMAND_SET pending is minted over exactly those T3
+        sub-commands via ``decide_t3_outcome(command_set=...)``. One approval
+        then covers the chain; each sub-command is still consumed byte-for-byte
+        by its own signature at retry (no consent is widened -- the commands are
+        only grouped). Critically, the per-component minting path
+        (_validate_single_command) is NEVER entered for the batch, so no stray
+        single pendings are minted alongside the COMMAND_SET.
+
+        For every other shape (0 or 1 ungranted-T3, no orchestrator above, or a
+        component that is hard-blocked) the original per-component pass runs
+        unchanged: a hard block fails the chain fast, a lone T3 keeps the
+        singular grant path, and an all-granted/safe chain is allowed.
+        """
         logger.info(f"Compound command detected with {len(components)} components")
 
+        # NON-MINTING pre-pass: which components are ungranted T3? (AC-8)
+        if is_subagent and is_ops_mode():
+            ungranted_t3_idx = [
+                idx
+                for idx, comp in enumerate(components)
+                if self._is_ungranted_t3_component(comp, session_id)
+            ]
+            if len(ungranted_t3_idx) >= 2:
+                chain_set = [
+                    {"command": components[idx].strip(), "rationale": ""}
+                    for idx in ungranted_t3_idx
+                ]
+                first_cmd = chain_set[0]["command"]
+                first_detect = detect_mutative_command(first_cmd)
+                verb = first_detect.verb or "command"
+                category = first_detect.category or "MUTATIVE"
+                native_ask_reason = (
+                    f"[T3_APPROVAL_REQUIRED] Chain of {len(chain_set)} T3 commands.\n"
+                    f"Commands:\n"
+                    + "\n".join(f"  - {it['command']}" for it in chain_set)
+                )
+                logger.info(
+                    "Chain COMMAND_SET intake: %d T3 sub-commands grouped under "
+                    "one consent (chain=%s)",
+                    len(chain_set),
+                    " && ".join(it["command"][:30] for it in chain_set),
+                )
+                return decide_t3_outcome(
+                    first_cmd,
+                    verb=verb,
+                    category=category,
+                    has_orchestrator_above=True,
+                    native_ask_reason=native_ask_reason,
+                    session_id=session_id,
+                    agent_type=agent_type,
+                    command_set=chain_set,
+                )
+
         component_results: List[BashValidationResult] = []
         for i, component in enumerate(components, 1):
             result = self._validate_single_command(
@@ -1385,6 +1495,7 @@ def decide_t3_outcome(
     native_ask_reason: str,
     session_id: str = "",
     agent_type: str = "",
+    command_set: list | None = None,
 ) -> BashValidationResult:
     """Single decision point for the outcome of a T3 (state-mutating) command.
 
@@ -1416,34 +1527,68 @@ def decide_t3_outcome(
         native_ask_reason: Reason text for the native-ask fallback branch.
         session_id: Session ID for pending-approval scoping.
         agent_type: Originating agent name (for the sealed payload).
+        command_set: Optional list of ``{command, rationale}`` dicts. When it
+            carries MORE THAN ONE item, this T3 decision covers a chain
+            (``a && b && c``) whose sub-commands are all T3, and the pending is
+            minted as ONE COMMAND_SET envelope (the chain-intake path, AC-8)
+            instead of a single semantic-signature pending. ONE user approval
+            then covers the whole chain; each sub-command is still consumed
+            byte-for-byte by its own signature at retry. A None / single-item
+            set keeps the singular behaviour. Only honoured in the
+            subagent-under-orchestrator branch (the native-ask branch has no
+            COMMAND_SET concept).
 
     Returns:
         A blocked BashValidationResult (allowed=False, tier T3) whose
         block_response is either a "deny" (with approval_id) or an "ask".
     """
+    # A genuine multi-command chain is a set of >= 2 items. Anything else
+    # collapses to the singular path so we never mint a COMMAND_SET for one
+    # command (mirrors _build_sealed_payload's is_command_set guard).
+    _normalized_set: list = []
+    if command_set:
+        for _item in command_set:
+            if isinstance(_item, dict) and _item.get("command"):
+                _normalized_set.append(
+                    {
+                        "command": _item["command"],
+                        "rationale": _item.get("rationale", ""),
+                    }
+                )
+    is_chain_command_set = len(_normalized_set) > 1
+
     if has_orchestrator_above:
         # Subagent-under-orchestrator: deny + persisted approval_id so the
         # orchestrator can run the approval cycle.  Reuse an existing pending
         # approval on retry to avoid generating duplicates while the user reviews.
-        approval_id = _find_pending_in_db(session_id or "", command)
-        if approval_id:
-            logger.info(
-                "Reusing pending approval_id=%s for retry: %s",
-                approval_id, command[:80],
-            )
-            reason = build_t3_blocked_denial_message(
-                approval_id=approval_id,
-                command=command,
-                verb=verb,
-                category=category,
-            )
-            hook_deny = build_hook_permission_response("deny", reason)
-            return BashValidationResult(
-                allowed=False,
-                tier=SecurityTier.T3_BLOCKED,
-                reason=f"T3 {category.lower()} command: {command[:60]}",
-                block_response=hook_deny,
-            )
+        #
+        # For a COMMAND_SET chain the pending id is CONTENT-derived (matching the
+        # plan-first intake), so a retry of the same chain produces the same id
+        # and the fingerprint-dedup in insert_requested reuses the pending. The
+        # singular reuse probe (_find_pending_in_db) matches a SINGLE command's
+        # signature and must NOT be consulted for the chain -- it would match one
+        # leftover single pending of a sub-command and degrade the chain back to
+        # a single grant. So the chain path skips it entirely.
+        if not is_chain_command_set:
+            approval_id = _find_pending_in_db(session_id or "", command)
+            if approval_id:
+                logger.info(
+                    "Reusing pending approval_id=%s for retry: %s",
+                    approval_id, command[:80],
+                )
+                reason = build_t3_blocked_denial_message(
+                    approval_id=approval_id,
+                    command=command,
+                    verb=verb,
+                    category=category,
+                )
+                hook_deny = build_hook_permission_response("deny", reason)
+                return BashValidationResult(
+                    allowed=False,
+                    tier=SecurityTier.T3_BLOCKED,
+                    reason=f"T3 {category.lower()} command: {command[:60]}",
+                    block_response=hook_deny,
+                )
 
         # No existing pending -- insert via DB (D16: exclusive path).
         sealed_payload = _build_sealed_payload(
@@ -1451,13 +1596,25 @@ def decide_t3_outcome(
             verb=verb,
             category=category,
             agent_type=agent_type,
+            command_set=_normalized_set if is_chain_command_set else None,
         )
         try:
             from gaia.approvals.store import insert_requested
+            # COMMAND_SET chains use a CONTENT-derived id (deterministic over the
+            # sub-command list) so a retry of the same chain reproduces the same
+            # id and reuses the pending via fingerprint dedup -- identical to the
+            # plan-first intake in handoff_persister. Singular T3 keeps uuid4.
+            supplied_id = None
+            if is_chain_command_set:
+                from gaia.approvals.store import derive_command_set_id
+                supplied_id = derive_command_set_id(
+                    [it["command"] for it in _normalized_set]
+                )
             approval_id = insert_requested(
                 sealed_payload,
                 agent_id=agent_type or None,
                 session_id=session_id or None,
+                approval_id=supplied_id,
             )
         except Exception as _store_err:
             logger.warning(

package/hooks/post_compact.py

@@ -35,6 +35,7 @@ def _handle_post_compact(event) -> None:
 
     response = {
         "hookSpecificOutput": {
+            "hookEventName": "PostCompact",
             "additionalContext": context,
         }
     }

package/hooks/pre_compact.py

@@ -52,6 +52,7 @@ def _handle_pre_compact(event) -> None:
 
     response = {
         "hookSpecificOutput": {
+            "hookEventName": "PreCompact",
             "additionalContext": context,
         }
     }

package/hooks/user_prompt_submit.py

@@ -194,6 +194,26 @@ if __name__ == "__main__":
             else:
                 logger.info("Could not extract user prompt from stdin, skipping routing")
 
+            # Per-turn VERIFIED pending approvals. Lets the orchestrator present
+            # a pending approval for consent directly from injected context,
+            # WITHOUT dispatching a subagent to derive/verify it (that dispatch's
+            # SubagentStop caused a pending-revocation bug). Emits "" when there
+            # are no verified pendings, so a turn with nothing pending injects
+            # nothing -- this is what keeps the per-turn injection quiet, unlike
+            # the one-shot SessionStart summary it deliberately does not re-emit.
+            try:
+                from modules.session.session_manifest import (
+                    build_per_turn_pending_approvals_block,
+                )
+                pending_block = build_per_turn_pending_approvals_block()
+                if pending_block:
+                    context_parts.append(pending_block)
+            except Exception as _pa_exc:
+                logger.debug(
+                    "per-turn pending approvals injection failed (non-fatal): %s",
+                    _pa_exc,
+                )
+
         additional_context = "\n\n".join(context_parts)
         logger.info("Context injected: %s mode (%d chars)", mode, len(additional_context))
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaguilar87/gaia",
-  "version": "5.0.8",
+  "version": "5.0.10",
   "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
   "main": "index.js",
   "type": "module",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gaia"
-version = "5.0.8"
+version = "5.0.10"
 description = "Multi-agent orchestration system for Claude Code - DevOps automation toolkit"
 requires-python = ">=3.11"
 license = {text = "MIT"}
@@ -12,7 +12,9 @@ readme = "README.md"
 [project.optional-dependencies]
 dev = [
     "pytest==8.3.5",
+    "pytest-cov>=5.0.0",
     "ruff>=0.4.0",
+    "pyyaml>=6.0",
 ]
 
 [tool.ruff]
@@ -32,4 +34,21 @@ include = ["gaia*"]
 testpaths = ["tests", "tools/scan/tests"]
 markers = [
     "parity: JS-Python CLI parity comparison tests",
+    "ci_subset: budget-bounded subset of L2/L3 (LLM) tests run in CI under a controlled token budget (brief #89 AC-6)",
+]
+
+# Branch coverage (brief #89 AC-4): coverage is a DIAGNOSTIC to locate unexercised
+# wiring in the security layer + entry points, NOT a metric-target / vanity gate.
+# No fail_under threshold is set on purpose.
+[tool.coverage.run]
+branch = true
+source = ["hooks/modules/security", "hooks"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+
+[dependency-groups]
+dev = [
+    "cosmic-ray>=8.4.6",
 ]

package/scripts/bootstrap_database.sh

@@ -211,9 +211,13 @@ fi
 #     EXPECTED_SCHEMA_VERSION en doctor.py en el mismo commit.
 #   - Para una DB en el FLOOR, esa migración corre directo (la DB está en el
 #     estado source de la migración). No se necesitan variantes _fresh: un
-#     fresh install ya está en EXPECTED tras schema.sql, así que el loop no
-#     entra (CURRENT == EXPECTED). El guard-probe por-versión del modelo viejo
-#     desaparece junto con la cadena histórica.
+#     fresh install sella el ledger en el FLOOR (Section 3b) y, cuando hay
+#     migraciones forward (EXPECTED > FLOOR), ESTE loop SÍ se replaya en cada
+#     fresh install desde FLOOR+1 hasta EXPECTED contra una DB cuyos objetos
+#     schema.sql ya creó -- por eso las migraciones DEBEN ser idempotentes
+#     (CREATE ... IF NOT EXISTS; ADD COLUMN neutralizado por el guard runner).
+#     El guard-probe por-versión del modelo viejo desaparece junto con la
+#     cadena histórica.
 #
 # Cada migración corre en su propia transacción BEGIN/COMMIT. Si falla, abort
 # -- el ledger NO avanza y el próximo bootstrap retry ve la misma pendiente.
@@ -245,13 +249,58 @@ echo "[bootstrap] schema_version: current=${CURRENT_VERSION}, expected=${EXPECTE
 
 MIG_DIR="${SCRIPT_DIR}/migrations"
 
+# --- Idempotent ADD COLUMN guard (runner-level) ------------------------------
+#
+# Forward migrations are applied on EVERY fresh install: schema.sql produces the
+# EXPECTED shape, the ledger is stamped at the FLOOR, and Section 3c walks
+# FLOOR+1..EXPECTED (this is what test_fresh_install_stamps_floor and
+# test_bootstrap_idempotent_at_floor require). Because schema.sql already
+# carries each migration's target DDL (see migrations/README.md section 1:
+# "add the DDL to schema.sql AND create the migration"), a migration is always
+# replayed against a DB that already has its objects.
+#
+# CREATE ... IF NOT EXISTS makes CREATE statements idempotent under that replay
+# (v18_to_v19 relies on it). But SQLite has NO `ADD COLUMN IF NOT EXISTS`, so a
+# bare `ALTER TABLE t ADD COLUMN c` aborts with "duplicate column name" when the
+# column already exists from schema.sql. This guard restores idempotency for
+# ADD COLUMN at the RUNNER level (not by putting invalid SQL in the .sql file):
+# for each `ALTER TABLE <t> ADD COLUMN <c> ...` line, if column <c> already
+# exists on table <t> (PRAGMA table_info), the line is neutralised (commented
+# out) before the migration runs. Every other statement passes through verbatim.
+#
+# Pure bash + sqlite3, no python3 -- consistent with this script's principles.
+_filter_add_column_idempotent() {
+    # $1 = path to the migration .sql file. Emits the (possibly filtered) SQL on
+    # stdout. Lines that are `ALTER TABLE t ADD COLUMN c` for an existing column
+    # are replaced by a comment; all other lines are passed through unchanged.
+    local mig_file="$1"
+    local line lower table col exists
+    while IFS= read -r line || [ -n "$line" ]; do
+        # Normalise whitespace for matching only (emit the ORIGINAL line).
+        lower="$(printf '%s' "$line" | tr '[:upper:]' '[:lower:]')"
+        if [[ "$lower" =~ alter[[:space:]]+table[[:space:]]+([a-z0-9_]+)[[:space:]]+add[[:space:]]+column[[:space:]]+([a-z0-9_]+) ]]; then
+            table="${BASH_REMATCH[1]}"
+            col="${BASH_REMATCH[2]}"
+            exists="$(sqlite3 "$GAIA_DB" "SELECT COUNT(*) FROM pragma_table_info('${table}') WHERE name='${col}';")"
+            if [ "$exists" -gt 0 ]; then
+                printf -- '-- [bootstrap] skipped (column %s.%s already present): %s\n' "$table" "$col" "$line"
+                continue
+            fi
+        fi
+        printf '%s\n' "$line"
+    done < "$mig_file"
+}
+
 if [ "$CURRENT_VERSION" -lt "$EXPECTED_VERSION" ]; then
-    # Forward-only loop. Reaches here only when a FUTURE migration has been
-    # added (EXPECTED_SCHEMA_VERSION > FLOOR) and the live DB is behind it.
-    # On a fresh install the DB is already at EXPECTED (schema.sql produced the
-    # FLOOR == EXPECTED shape when no forward migrations exist), so this branch
-    # is skipped entirely. Any DB below the FLOOR was already rejected in
-    # Section 3b, so CURRENT_VERSION here is always >= FLOOR.
+    # Forward-only loop. Runs whenever the live DB is behind EXPECTED, which
+    # INCLUDES a fresh install: Section 3b stamps the ledger at the FLOOR, and
+    # when forward migrations exist (EXPECTED > FLOOR) a fresh DB sits at the
+    # FLOOR while EXPECTED is higher, so it enters here and replays FLOOR+1..
+    # EXPECTED. That replay runs against a DB whose objects schema.sql already
+    # created, which is exactly why these migrations MUST be idempotent (CREATE
+    # ... IF NOT EXISTS; ADD COLUMN neutralised by the runner guard above).
+    # Any DB below the FLOOR was already rejected in Section 3b, so
+    # CURRENT_VERSION here is always >= FLOOR.
     for N in $(seq $((CURRENT_VERSION + 1)) "$EXPECTED_VERSION"); do
         PREV=$((N - 1))
         MIG_FILE="${MIG_DIR}/v${PREV}_to_v${N}.sql"
@@ -263,15 +312,15 @@ if [ "$CURRENT_VERSION" -lt "$EXPECTED_VERSION" ]; then
             exit 1
         fi
 
-        # Forward-only: a DB at the FLOOR (or any version below N) is in the
-        # source state of this migration, so we apply it directly inside an
-        # explicit transaction. No per-version guard probe and no _fresh
-        # variant are needed -- the historical "schema.sql already created the
-        # target table" case only existed because the baseline was v1 and the
-        # whole chain was walked on every fresh install. Under the FLOOR model
-        # a fresh install is already at EXPECTED, so it never enters this loop.
+        # Apply the migration inside an explicit transaction. The SQL is passed
+        # through _filter_add_column_idempotent first so that `ADD COLUMN`
+        # statements for columns schema.sql already created are skipped (SQLite
+        # lacks `ADD COLUMN IF NOT EXISTS`). CREATE ... IF NOT EXISTS statements
+        # are already idempotent and pass through unchanged. This is what lets a
+        # fresh install (where schema.sql produced the EXPECTED shape) replay the
+        # FLOOR+1..EXPECTED migrations without aborting on duplicate columns.
         echo "[bootstrap] migration v${PREV}->v${N}: applying ${MIG_FILE}"
-        MIG_SQL="$(cat "$MIG_FILE")"
+        MIG_SQL="$(_filter_add_column_idempotent "$MIG_FILE")"
         if ! sqlite3 "$GAIA_DB" <<EOF
 BEGIN;
 ${MIG_SQL}

package/scripts/migrations/README.md

@@ -17,25 +17,31 @@ The floor is **v18**. It is declared in three places that must agree:
 
 | Location | What it holds |
 |----------|---------------|
-| `gaia/store/schema.sql` | Produces the v18 shape directly (fresh installs land here). |
-| `scripts/bootstrap_database.sh` Section 3b (`SCHEMA_FLOOR=18`) | Seeds/stamps the ledger at the floor; rejects DBs below it. |
-| `bin/cli/doctor.py` (`EXPECTED_SCHEMA_VERSION`) | The version the CLI expects; equals the floor until a forward migration is added. |
+| `gaia/store/schema.sql` | Produces the **latest** (EXPECTED) shape directly -- fresh installs land here, not at the floor. |
+| `scripts/bootstrap_database.sh` Section 3b (`SCHEMA_FLOOR=18`) | Stamps the fresh ledger at the floor; rejects DBs below it. |
+| `bin/cli/doctor.py` (`EXPECTED_SCHEMA_VERSION`) | The version the CLI expects; equals the floor when no forward migration exists, and the highest migration target once they do. |
 
 How bootstrap treats each case:
 
 * **Fresh install** (no `schema_version` rows): `schema.sql` already produced
-  the floor shape, so bootstrap stamps `(version=18, ...)` directly. It does
-  **not** seed v1 and walk the chain.
-* **DB at or above the floor** (the common case, e.g. `~/.gaia/gaia.db`): no
-  migration needed. Section 3c only runs if a forward migration exists.
+  the EXPECTED shape, and Section 3b stamps the ledger at the **floor** (not
+  EXPECTED). Section 3c then replays every forward migration from `floor+1` to
+  EXPECTED against that already-current DB. It does **not** seed v1 and walk the
+  historical chain. Because the migrations run against objects `schema.sql`
+  already created, they **must be idempotent** (see section 1).
+* **DB at or above the floor** (the common case, e.g. `~/.gaia/gaia.db`):
+  Section 3c applies any forward migrations the DB is still behind on, up to
+  EXPECTED.
 * **DB below the floor** (`1 <= version < 18`): **no longer supported** for
   in-place upgrade. Bootstrap aborts with a clear message asking you to
   recreate the DB (back up, delete `~/.gaia/gaia.db`, re-run `gaia install`).
 
 There are no `_fresh` / `_merge` variants under the floor model. Those existed
 only because the old baseline was v1 and the whole chain was walked on every
-fresh install. With the floor, a fresh install is already at the expected
-version after `schema.sql`, so the migration loop is skipped entirely.
+fresh install. Under the floor model the forward-migration loop is still
+replayed on every fresh install (from `floor+1` to EXPECTED) -- so the single
+forward migration file per bump must be idempotent rather than split into
+`_fresh` / `_merge` variants.
 
 ---
 
@@ -48,14 +54,19 @@ version) to `N`:
 1. Add the new DDL to `gaia/store/schema.sql` so fresh installs land in the
    target shape.
 2. Create exactly one `scripts/migrations/v{N-1}_to_v{N}.sql` containing the
-   full DDL delta applied to a DB at version `N-1`.
+   full DDL delta applied to a DB at version `N-1`. It **must be idempotent**
+   (`CREATE ... IF NOT EXISTS`; for `ADD COLUMN`, rely on the runner's
+   existence guard -- SQLite has no `ADD COLUMN IF NOT EXISTS`), because it is
+   replayed on fresh installs against a DB that already has those objects.
 3. Bump `EXPECTED_SCHEMA_VERSION` to `N` in `bin/cli/doctor.py` **in the same
    commit**.
 
 `bootstrap_database.sh` Section 3c then applies `v{N-1}_to_v{N}.sql` inside a
 single `BEGIN/COMMIT` transaction for any DB behind `N`, and stamps the ledger
-only on success. A fresh install is already at `N` after `schema.sql`, so it
-never enters the loop -- no `_fresh` variant is required.
+only on success. A fresh install stamps the ledger at the floor (Section 3b)
+and then replays `floor+1 .. N` here too -- since `schema.sql` already produced
+the `N` shape, the migration runs against objects that already exist, which is
+exactly why it must be idempotent (no `_fresh` variant is used).
 
 `tests/cli/test_schema_version_lockstep.py` enforces that
 `EXPECTED_SCHEMA_VERSION` equals the floor when no forward migrations exist,
@@ -93,8 +104,9 @@ as the ledger grows.
 | `vN_to_vN+1.sql` | Applied to an existing DB at version N. Contains the full DDL delta, applied inside a `BEGIN/COMMIT` transaction by bootstrap Section 3c. |
 
 The historical `_fresh` and `_merge` variants are no longer used: under the
-floor model a fresh install is already at the expected version after
-`schema.sql`, so it never runs a migration script.
+floor model a single idempotent `vN_to_vN+1.sql` covers both an in-place
+upgrade and the fresh-install replay (Section 3c walks `floor+1 .. EXPECTED`
+on every fresh install), so one idempotent file replaces the old split.
 
 ---
 

package/scripts/migrations/schema.checksum

@@ -4,5 +4,5 @@
 # corresponds to (EXPECTED_SCHEMA_VERSION in bin/cli/doctor.py).
 # Do NOT edit by hand: bump EXPECTED_SCHEMA_VERSION + add a migration,
 # then re-run the guard to refresh this file.
-version=18
-sha256=6f728de0625d5011b86eaf536c21785d19cfa08592ecaf086ab46f9b0d0ebda0
+version=20
+sha256=027c8a61e8217b40cbdb07d0b83e7fb18f1ec671d3069dc0a0ce6bb4cc0e8ee9

package/scripts/migrations/v18_to_v19.sql

@@ -0,0 +1,36 @@
+-- Migration v18 -> v19: audit-immutability gap closure (Task B).
+--
+-- Adds BEFORE UPDATE trigger bu_approvals_status_has_event on the approvals
+-- table to enforce that every approvals.status transition is accompanied by a
+-- preceding event row in the append-only approval_events chain.
+--
+-- The trigger fires when status changes to 'approved', 'rejected', or 'revoked'.
+-- It checks that an event row with the matching event_type exists for the
+-- approval_id within the same transaction. If no matching event is found it
+-- raises ABORT, rolling back the UPDATE.
+--
+-- This closes the gap where a direct UPDATE approvals SET status = 'approved'
+-- could flip the status column without leaving an auditable event, violating
+-- the "auditable + immutable" invariant of the approval_events chain.
+--
+-- Bootstrap note: a fresh install (schema.sql) already includes this trigger
+-- via CREATE TRIGGER IF NOT EXISTS; this migration only adds it to existing DBs
+-- that were initialized before v19.
+
+CREATE TRIGGER IF NOT EXISTS bu_approvals_status_has_event
+BEFORE UPDATE OF status ON approvals
+WHEN NEW.status != OLD.status AND NEW.status IN ('approved', 'rejected', 'revoked')
+BEGIN
+    SELECT CASE
+        WHEN (
+            SELECT COUNT(*) FROM approval_events
+             WHERE approval_id = NEW.id
+               AND event_type = CASE NEW.status
+                                    WHEN 'approved' THEN 'APPROVED'
+                                    WHEN 'rejected' THEN 'REJECTED'
+                                    WHEN 'revoked'  THEN 'REVOKED'
+                                END
+        ) = 0
+        THEN RAISE(ABORT, 'approvals: status change requires a preceding event in approval_events')
+    END;
+END;

package/scripts/migrations/v19_to_v20.sql

@@ -0,0 +1,20 @@
+-- Migration v19 -> v20: add multi_use and confirmed columns to approval_grants.
+--
+-- These two columns support the upcoming FS-grant-plane migration:
+--   multi_use INTEGER NOT NULL DEFAULT 0  -- 1 = multi-use grant, 0 = single-use (BOOLEAN)
+--   confirmed INTEGER NOT NULL DEFAULT 0  -- 1 = grant confirmed by user, 0 = pending (BOOLEAN)
+--
+-- Both columns use the established boolean-as-INTEGER convention (DEFAULT 0)
+-- already in use across this schema (e.g. allow_write, can_read, can_write).
+--
+-- SQLite ALTER TABLE ADD COLUMN is safe and additive: existing rows receive the
+-- DEFAULT value and the table is NOT rebuilt.  Zero data loss is guaranteed by
+-- the SQLite specification (https://www.sqlite.org/lang_altertable.html).
+--
+-- Bootstrap note: migrations run once via the version chain.  A fresh install
+-- seeds from schema.sql (which already includes both columns) and then skips
+-- this migration file by version-gating; this file runs only against existing
+-- DBs initialized before v20 (which do not yet have these columns).
+
+ALTER TABLE approval_grants ADD COLUMN multi_use INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE approval_grants ADD COLUMN confirmed INTEGER NOT NULL DEFAULT 0;