brainlayer 1.5.78__tar.gz → 1.5.80__tar.gz

{brainlayer-1.5.78 → brainlayer-1.5.80}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: brainlayer
-Version: 1.5.78
+Version: 1.5.80
 Summary: Persistent local memory for AI agents — 16 BrainBar MCP tools, semantic search, knowledge graph, SQLite
 Project-URL: Homepage, https://brainlayer.etanheyman.com
 Project-URL: Repository, https://github.com/EtanHey/brainlayer

{brainlayer-1.5.78 → brainlayer-1.5.80}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brainlayer"
-version = "1.5.78"
+version = "1.5.80"
 description = "Persistent local memory for AI agents — 16 BrainBar MCP tools, semantic search, knowledge graph, SQLite"
 license = {text = "Apache-2.0"}
 readme = "README.md"

{brainlayer-1.5.78 → brainlayer-1.5.80}/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.etanhey/brainlayer",
   "title": "BrainLayer",
   "description": "Persistent local memory for AI agents \u2014 semantic search, knowledge graph, and 16 BrainBar MCP tools with ToolAnnotations over SQLite.",
-  "version": "1.5.78",
+  "version": "1.5.80",
   "websiteUrl": "https://brainlayer.etanheyman.com",
   "repository": {
     "url": "https://github.com/EtanHey/brainlayer",
@@ -14,7 +14,7 @@
       "registryType": "pypi",
       "registryBaseUrl": "https://pypi.org",
       "identifier": "brainlayer",
-      "version": "1.5.78",
+      "version": "1.5.80",
       "runtimeHint": "pipx",
       "transport": {
         "type": "stdio"

{brainlayer-1.5.78 → brainlayer-1.5.80}/src/brainlayer/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "1.5.78"
+__version__ = "1.5.80"
 # Git sha the distributed package was built from; stamped by the release build, None in a source tree.
 # scripts/sprint_gate.py reads it in "keg" mode to prove the served package is the code under test.
 # No runtime `str | None` annotation: launchd/install.sh imports this under /usr/bin/python3 (3.9).

brainlayer-1.5.80/src/brainlayer/_build.py

@@ -0,0 +1 @@
+BUILD_SHA = "cc301a9f19b679f75278f9cca43c48fc49fe8d7e"

{brainlayer-1.5.78 → brainlayer-1.5.80}/src/brainlayer/backup_daily.py

@@ -406,6 +406,10 @@ class BrainBarDatabaseIdentityError(RuntimeError):
     """BrainBar serves a different database than the one this backup was aimed at."""
 
 
+class BrainBarDatabaseIdentityUnavailableError(BrainBarDatabaseIdentityError):
+    """BrainBar did not confirm its open database; no difference has been established."""
+
+
 # MCPRouter.handleBrainBackupVacuumInto refuses with this before any VACUUM INTO when the
 # request's expected_db_path does not identify the database BrainBar serves.
 BRAINBAR_DB_IDENTITY_MISMATCH = "BrainBar database identity mismatch"
@@ -1230,7 +1234,9 @@ def _refuse_foreign_db_on_production_socket(db_path: Path, socket_path: Path | s
     configured_db = resolve_db_path()
     if not _same_database_file(db_path, configured_db):
         raise BrainBarDatabaseIdentityError(
-            f"{BRAINBAR_DB_IDENTITY_MISMATCH}: refusing to snapshot {db_path} through the production BrainBar "
+            "Backup blocked: BrainBar has a different database open. "
+            "Check the backup database path and BrainBar's configured database. "
+            f"Details: refusing to snapshot {db_path} through the production BrainBar "
             f"socket {resolved_socket}, which serves the configured database {configured_db}; "
             "pass an isolated socket_path to back up any other database"
         )
@@ -1897,15 +1903,22 @@ def request_brainbar_vacuum_into(
                 echo = echo if isinstance(echo, dict) else {}
                 served_identity = (echo.get("db_dev"), echo.get("db_ino"))
                 expected_identity = _file_identity(resolved_expected_db)
-                if not all(isinstance(v, int) for v in served_identity) or served_identity != expected_identity:
-                    # Terminal response: BrainBar has stopped writing this attempt. Whatever it
-                    # vacuumed is not the configured database, so it must not survive here.
+                identity_valid = all(type(v) is int for v in served_identity) and served_identity[1] > 0
+                if not identity_valid or served_identity != expected_identity:
+                    # A terminal response ends this writer. Unconfirmed and foreign snapshots
+                    # both fail closed, but absence of support proves no database difference.
                     attempt_path.unlink(missing_ok=True)
                     _backup_attempt_completion_marker(attempt_path).unlink(missing_ok=True)
+                    if not identity_valid:
+                        raise BrainBarDatabaseIdentityUnavailableError(
+                            "Backup blocked: this BrainBar version cannot confirm which database it has open. "
+                            "Upgrade BrainBar."
+                        )
                     raise BrainBarDatabaseIdentityError(
-                        f"{BRAINBAR_DB_IDENTITY_MISMATCH}: expected {resolved_expected_db} {expected_identity}, "
-                        f"BrainBar reported {echo.get('db_path')!r} {served_identity}; deleted the unconfirmed "
-                        "snapshot. A BrainBar without open-database identity support must be upgraded."
+                        "Backup blocked: BrainBar has a different database open. "
+                        "Check the backup database path and BrainBar's configured database. "
+                        f"Details: expected {resolved_expected_db} {expected_identity}, "
+                        f"BrainBar reported {echo.get('db_path')!r} {served_identity}; deleted the unconfirmed snapshot."
                     )
             if not attempt_path.exists():
                 raise RuntimeError(f"BrainBar backup did not create snapshot: {attempt_path}")

{brainlayer-1.5.78 → brainlayer-1.5.80}/src/brainlayer/brainbar_auto_activation.py

@@ -31,12 +31,15 @@ def brew_processes():
     # Include brew's Ruby entrypoint and Homebrew-owned child executables, even
     # after reparenting. Unknown/unreadable process tables defer activation.
     rows = process_table().splitlines()
-    matches = []
+    matches, readable = [], 0
     for row in rows:
         fields = row.split(None, 3)
-        if len(fields) != 4 or not fields[0].isascii() or not fields[0].isdecimal():
-            raise ValueError("unreadable process table")
-        tokens = fields[3].split()
+        # A process exiting or exec-ing mid-scan can tear one row: empty args
+        # are still checked by comm, a row without a pid and comm is skipped.
+        if len(fields) < 3 or not fields[0].isascii() or not fields[0].isdecimal():
+            continue
+        readable += 1
+        tokens = fields[3].split() if len(fields) == 4 else []
         if Path(fields[2]).name == "brew" or any(
             Path(token).name in {"brew", "brew.rb"} or "/Homebrew/" in token or "/homebrew/Library/Homebrew/" in token
             for token in tokens
@@ -44,6 +47,8 @@ def brew_processes():
             # argv is detection-only: Homebrew curl headers can carry tokens.
             executable = scrub_secrets(Path(fields[2]).name).text[:128]
             matches.append(f"{fields[0]} {executable}")
+    if not readable:
+        raise ValueError("unreadable process table")
     return matches
 
 
@@ -85,6 +90,9 @@ class AutoActivator:
             processes = brew_processes()
         except (OSError, subprocess.SubprocessError) as exc:
             raise ProcessScanUnavailable(type(exc).__name__) from None
+        except ValueError:
+            # Counted and alerted only after 12 ticks, never an immediate refusal.
+            raise ProcessScanUnavailable("unreadable process table") from None
         # Recover before activation can report a new failure on the same alert key.
         self.state.with_suffix(".scan.json").unlink(missing_ok=True)
         reason = active_alerts().get("brainbar-activation", "")
@@ -97,6 +105,7 @@ class AutoActivator:
             (
                 "BrainBar activation process scan failed for >=12 ticks:",
                 "BrainBar activation monitor refused: Command '['/bin/ps',",
+                "BrainBar activation monitor refused: unreadable process table",
             )
         ):
             report("brainbar-activation", None)

brainlayer-1.5.80/src/brainlayer/cli_jobs.py

@@ -0,0 +1,108 @@
+"""Explicit consolidated launcher and component CLI commands."""
+
+import asyncio
+import datetime as dt
+import json
+import sys
+from pathlib import Path
+
+import typer
+
+
+def register(app, jobs_app):
+    @app.command("maintenance-calendar")
+    def maintenance_calendar(
+        lib_dir: Path = typer.Option(Path(__file__).parent / "launchd", "--lib-dir"),
+        scheduled_date: str | None = typer.Option(None, "--date"),
+        state_dir: Path | None = typer.Option(None, "--state-dir"),
+        logs_dir: Path = typer.Option(Path.home() / "Library/Logs/brainlayer", "--logs-dir"),
+        recover_transcripts: bool = typer.Option(False, "--recover-transcripts"),
+        recover_failed: bool = typer.Option(False, "--recover-failed"),
+        status: bool = typer.Option(
+            False, "--status", help="Check failed-step recovery admission without running steps"
+        ),
+    ):
+        """Run BrainLayer Maintenance for one scheduled date."""
+        from .maintenance_calendar import calendar_steps, run_calendar
+        from .paths import supervisor_socket_path
+
+        try:
+            date = dt.date.fromisoformat(scheduled_date) if scheduled_date else dt.date.today()
+        except ValueError as exc:
+            raise typer.BadParameter("date must be ISO YYYY-MM-DD") from exc
+        if recover_failed and recover_transcripts:
+            raise typer.BadParameter("Choose --recover-failed or --recover-transcripts")
+        if status and not recover_failed:
+            raise typer.BadParameter("--status requires --recover-failed")
+        if recover_failed and scheduled_date:
+            raise typer.BadParameter("Failed-step recovery uses the latest scheduled night; omit --date")
+        result = {}
+        directory = state_dir or supervisor_socket_path().parent / "calendar"
+        if directory.resolve() == supervisor_socket_path().parent.resolve():
+            raise typer.BadParameter("calendar custody directory must differ from resident supervisor")
+        try:
+            plan = calendar_steps(sys.executable, str(Path(sys.executable).with_name("brainlayer")), lib_dir, date)
+            code = asyncio.run(
+                run_calendar(
+                    plan,
+                    directory,
+                    logs_dir,
+                    install_signals=True,
+                    transcript_recovery=recover_transcripts,
+                    **(
+                        dict(failed_recovery=True, recovery_status=status, recovery_result=result)
+                        if recover_failed
+                        else {}
+                    ),
+                )
+            )
+        except (OSError, ValueError, RuntimeError, KeyError, TypeError) as exc:
+            if not recover_failed:
+                raise
+            from .maintenance_calendar import recovery_refusal_reason
+
+            results = result.get("results") or {}
+            if result.get("status") == "accepted" and results and all(v == "ok" for v in results.values()):
+                # The retried steps finished and were journaled; only cleanup after them failed.
+                result.update(
+                    reason="Retried successfully; maintenance cleanup afterwards had a problem (see the log)."
+                )
+                code = 0
+            elif results:
+                # The steps ran and did not all succeed: keep their outcome and reason, not an
+                # availability error. A cleanup failure afterwards does not change what ran.
+                if result.get("status") != "failed":
+                    result.update(reason="Retry did not finish successfully; see the step results and logs")
+                result.update(status="failed")
+                code = 1
+            else:
+                status = "failed" if result.get("status") in {"accepted", "failed"} else "refused"
+                result.update(status=status, reason=recovery_refusal_reason(exc), steps=[])
+                code = 1
+        if recover_failed:
+            typer.echo(json.dumps(result, sort_keys=True))
+        raise typer.Exit(code)
+
+    @app.command("daemon")
+    def daemon(manifest: Path = typer.Option(..., "--manifest"), socket: Path | None = typer.Option(None, "--socket")):
+        """Run BrainLayer Daemon from a private command manifest."""
+        from .supervisor_jobs import run_daemon
+
+        run_daemon(manifest, socket)
+
+    @jobs_app.command("component")
+    def component(
+        name: str,
+        action: str,
+        manifest: Path | None = typer.Option(None, "--manifest"),
+        socket: Path | None = typer.Option(None, "--socket"),
+    ):
+        """Status/restart or configured env/log paths for one component."""
+        from .component_jobs import component_action
+
+        try:
+            result = component_action(name, action, manifest=manifest, path=socket)
+        except (OSError, ValueError, RuntimeError, KeyError, TypeError) as exc:
+            typer.echo(json.dumps({"error": str(exc)}))
+            raise typer.Exit(1) from exc
+        typer.echo(json.dumps(result, sort_keys=True))

{brainlayer-1.5.78 → brainlayer-1.5.80}/src/brainlayer/decay_job.py

@@ -5,6 +5,8 @@ from typing import Any
 
 import apsw
 
+from .writer_policy import configure_writer_wal_policy
+
 ARCHIVE_THRESHOLD = 0.1
 
 
@@ -35,6 +37,7 @@ def run_decay_job(
     current_time = time.time() if now is None else now
     connection = apsw.Connection(str(db_path))
     connection.setbusytimeout(30_000)
+    configure_writer_wal_policy(connection)
     cursor = connection.cursor()
 
     last_rowid = 0

{brainlayer-1.5.78 → brainlayer-1.5.80}/src/brainlayer/health_check.py

@@ -1572,14 +1572,15 @@ def _run_health_check_locked(
         if result.missing_embedding_scan.completeness == "complete":
             result.missing_vectors = result.missing_embedding_scan.missing
     except sqlite3.OperationalError as exc:
-        result.missing_embedding_scan = MissingEmbeddingScan(reason=str(exc))
+        # Stable codes for BrainBar's vector notice; the exception text stays in the issue message.
+        result.missing_embedding_scan = MissingEmbeddingScan(reason="sql_error")
         add_issue(
             "missing_embeddings_count_failed",
             "warning" if _text_has_sqlite_busy_signal(exc) else "critical",
             f"could not count missing embeddings: {exc}",
         )
     except Exception as exc:
-        result.missing_embedding_scan = MissingEmbeddingScan(reason=str(exc))
+        result.missing_embedding_scan = MissingEmbeddingScan(reason="unexpected")
         add_issue(
             "missing_embeddings_count_failed",
             "critical",
@@ -1587,18 +1588,26 @@ def _run_health_check_locked(
         )
     scan = result.missing_embedding_scan
     state["missing_embedding_scan"] = asdict(scan)
-    if scan.completeness != "complete":
+    # Keep budget reasons aligned with BrainBarVectorScan.routinePartial in
+    # brain-bar/Sources/BrainBar/Dashboard/ObservabilityView.swift.
+    routine_partial = (
+        scan.completeness == "partial"
+        and scan.scanned > 0
+        and scan.reason in {"instruction_limit", "time_limit", "page_limit", "window_end"}
+    )
+    if scan.completeness != "complete" and not routine_partial:
         add_issue(
             "missing_embeddings_scan_incomplete",
             "warning",
-            f"missing embeddings {scan.completeness}: scanned {scan.scanned} rows ({scan.reason}); not an exact count",
+            "The vector check could not finish. The current backlog is not verified by this check.",
+        )
+    if scan.completeness != "complete" and scan.missing:
+        add_issue(
+            "missing_embeddings_backlog",
+            "warning",
+            f"At least {scan.missing:,} checked {'chunk is' if scan.missing == 1 else 'chunks are'} waiting for vectors. "
+            "See Vector backlog for the latest full count.",
         )
-        if scan.missing:
-            add_issue(
-                "missing_embeddings_backlog",
-                "warning",
-                f"at least {scan.missing} missing embeddings in {scan.scanned} sampled rows",
-            )
 
     hotlane_sample_advanced, hotlane_progressed = _hotlane_progress_sample(state, result.missing_vectors, now)
     if hotlane_progressed:
@@ -1978,7 +1987,15 @@ def _run_health_check_locked(
     state_payload["heal_failures"] = heal_failures
     if job_tick is not None:
         state_payload["job_lifecycle"] = job_tick.state
-    state_payload["heal_tripped"] = sorted(heal_tripped) if result.issues else []
+    state_payload["heal_tripped"] = (
+        sorted(heal_tripped)
+        if result.issues
+        else [
+            key
+            for key in sorted(heal_tripped)
+            if not hotlane_sample_advanced and key == _heal_key(config.hotlane_label, "missing_embeddings_not_draining")
+        ]
+    )
     _record_queue_notice(state_payload, queue_notice_signature)
     state_payload["ts"] = now.isoformat()
     if result.missing_vectors is not None:

{brainlayer-1.5.78 → brainlayer-1.5.80}/src/brainlayer/job_alerts.py

@@ -65,7 +65,12 @@ def report(
     path: Path | None = None,
     notify: Callable[[str], None] = _notify,
 ) -> bool:
-    """Set or clear one episode. Return true only when the visible state changes."""
+    """Set or clear one episode. Return true only when the visible state changes.
+
+    Only a new failure posts a notification, and only when no other active key already
+    carries the identical message (one incident fanned out across keys posts once).
+    Recovery updates the alert file and the health log but never notifies.
+    """
     destination = path or alert_path()
     with _locked(destination):
         current = active_alerts(destination)
@@ -75,15 +80,19 @@ def report(
                 return False
             current.pop(key)
             message = f"BrainLayer {key} recovered"
+            post = False
         else:
             if before is not None and (before == reason or key != "drive-consent"):
                 return False
+            post = reason not in (value for other, value in current.items() if other != key)
             current[key] = reason
             message = reason
         from brainlayer.drive_credentials import _atomic_write
 
         _atomic_write(destination, current)
     LOG.warning("health event job=%s state=%s reason=%s", key, "recovered" if reason is None else "failed", message)
+    if not post:
+        return True
     try:
         notify(message)
     except (OSError, subprocess.SubprocessError) as exc:

{brainlayer-1.5.78 → brainlayer-1.5.80}/src/brainlayer/jsonl_backup.py

@@ -30,6 +30,7 @@ opaque `.pb` implicit records, and per-session `.system_generated` /
 from __future__ import annotations
 
 import datetime as dt
+import errno
 import fcntl
 import functools
 import gzip
@@ -1226,7 +1227,8 @@ class _HashingReader:
 
 def create_jsonl_bundle_with_digests(
     candidates: list[JsonlCandidate], staging_dir: Path, *, date_stamp: str
-) -> tuple[Path, dict[str, str], dict[str, int]]:
+) -> tuple[Path | None, dict[str, str], dict[str, int]]:
+    """Bundle completed source snapshots; return no archive when every source vanished."""
     if not candidates:
         raise ValueError("create_jsonl_bundle requires at least one candidate")
     staging_dir = Path(staging_dir).expanduser()
@@ -1240,30 +1242,37 @@ def create_jsonl_bundle_with_digests(
     sizes: dict[str, int] = {}
     try:
         with tarfile.open(temp_path, "w:gz") as tar:
+            tar.dereference = True
             for candidate in candidates:
-                # Hash and archive the SAME bytes, without holding the file in memory.
-                # Re-reading the source afterwards could record a digest for content the
-                # archive does not contain -- a file that changed while keeping its mtime
-                # and size would then read as covered. Sources reach ~375MB, so the digest
-                # is taken from the very stream tarfile consumes rather than from a copy.
-                # Discovery follows file symlinks, so archive their resolved target as a
-                # regular member too; preserving the link would make verification reject
-                # the whole bundle as non-regular.
-                source_path = candidate.path.resolve()
-                info = tar.gettarinfo(str(source_path), arcname=_archive_name(candidate))
-                with source_path.open("rb") as handle:
-                    reader = _HashingReader(handle)
-                    tar.addfile(info, reader)
+                # Open before fstat so unlink/rotation cannot invalidate the metadata.
+                # Snapshot one member on disk before writing its tar header: an ENOENT
+                # even partway through a read must leave no partial member in the gzip.
+                # Hash exactly the snapshot bytes, at O(buffer) memory. Following links
+                # and dereferencing hardlinks keeps every source a regular member.
+                with tempfile.TemporaryFile(dir=staging_dir) as snapshot:
+                    try:
+                        with candidate.path.open("rb") as handle:
+                            info = tar.gettarinfo(fileobj=handle, arcname=_archive_name(candidate))
+                            reader = _HashingReader(handle)
+                            tarfile.copyfileobj(reader, snapshot, info.size)
+                    except OSError as exc:
+                        if isinstance(exc, FileNotFoundError) or exc.errno == errno.ENOENT:
+                            continue
+                        raise
+                    snapshot.seek(0)
+                    tar.addfile(info, snapshot)
                 digests[candidate.path.as_posix()] = reader.hexdigest()
                 sizes[candidate.path.as_posix()] = info.size
+        if not digests:
+            return None, digests, sizes
         os.replace(temp_path, archive_path)
     finally:
         temp_path.unlink(missing_ok=True)
     return archive_path, digests, sizes
 
 
-def create_jsonl_bundle(candidates: list[JsonlCandidate], staging_dir: Path, *, date_stamp: str) -> Path:
-    """Backwards-compatible wrapper returning only the archive path."""
+def create_jsonl_bundle(candidates: list[JsonlCandidate], staging_dir: Path, *, date_stamp: str) -> Path | None:
+    """Return only the archive path, or None when every candidate vanished."""
     archive_path, _, _ = create_jsonl_bundle_with_digests(candidates, staging_dir, date_stamp=date_stamp)
     return archive_path
 
@@ -1626,7 +1635,18 @@ def run_backup(
     if pending_candidates:
         changed = [candidate for candidate in changed if candidate.path.as_posix() not in pending_icloud_sources]
 
-    if not changed and pending_candidates:
+    archive_path = None
+    bundle_digests: dict[str, str] = {}
+    bundle_sizes: dict[str, int] = {}
+    if changed:
+        archive_path, bundle_digests, bundle_sizes = create_jsonl_bundle_with_digests(
+            changed, staging_dir, date_stamp=date_stamp
+        )
+        bundled = [candidate for candidate in changed if candidate.path.as_posix() in bundle_digests]
+        vanished += len(changed) - len(bundled)
+        changed = bundled
+
+    if archive_path is None and pending_candidates:
         error = (
             f"iCloud coverage is pending; repair deferred while {len(pending_candidates)} source(s) finish uploading"
         )
@@ -1649,7 +1669,7 @@ def run_backup(
         _enqueue_run_summary(result, queue_dir=queue_dir)
         return result
 
-    if not changed and icloud_bootstrap_pending and active:
+    if archive_path is None and icloud_bootstrap_pending and active:
         error = (
             "iCloud coverage is not verified; repair deferred because "
             f"{len(active)} discovered source(s) are still active"
@@ -1672,7 +1692,7 @@ def run_backup(
         _enqueue_run_summary(result, queue_dir=queue_dir)
         return result
 
-    if not changed:
+    if archive_path is None:
         result: dict[str, Any] = {
             "attempted_at": attempted_at,
             "status": "no-op",
@@ -1689,9 +1709,6 @@ def run_backup(
         _enqueue_run_summary(result, queue_dir=queue_dir)
         return result
 
-    archive_path, bundle_digests, bundle_sizes = create_jsonl_bundle_with_digests(
-        changed, staging_dir, date_stamp=date_stamp
-    )
     archive_size = archive_path.stat().st_size
     result = {
         "attempted_at": attempted_at,

{brainlayer-1.5.78 → brainlayer-1.5.80}/src/brainlayer/maintenance.py

@@ -43,7 +43,8 @@ from .paths import get_db_path
 from .pause import DEFAULT_PAUSE_SENTINEL_PATH, pause_applies_to_label, pause_sentinel_state
 from .pipeline.code_intelligence import _pid_is_alive, _pid_start_time
 from .queue_io import get_queue_dir
-from .wal_checkpoint import checkpoint
+from .wal_checkpoint import CheckpointGuardTimeout, checkpoint, get_wal_size
+from .writer_policy import configure_writer_wal_policy
 
 PAUSE_SENTINEL_PATH = DEFAULT_PAUSE_SENTINEL_PATH
 
@@ -64,6 +65,7 @@ _WATCHDOG_DISABLED_BEFORE = "_fleet_watchdog_disabled_before"
 MAINTENANCE_LOCK_TIMEOUT_SECONDS = 4 * 60 * 60
 # VACUUM is interrupted this long before its hold expires, so restore wins the calendar's cut.
 HOLD_UNWIND_S = 30.0
+POST_VACUUM_BUSY_S = 0.25
 VACUUM_PROGRESS_OPS = 100_000  # SQLite VM steps between deadline polls during VACUUM.
 # VACUUM's final copy-back into the main DB runs no VM steps, so the progress handler cannot stop
 # it: a 20.7 GB copy (MBP, 2026-10-19) overran a 60 s cutoff and completed at 328 s, 15.9 s/GB.
@@ -906,6 +908,55 @@ def _checkpoint_full(db_path: Path) -> tuple[int, int, int]:
     return checkpoint(str(db_path), "FULL")
 
 
+def _reclaim_vacuum_wal(
+    config: MaintenanceConfig, *, deadline: float | None, phase: str
+) -> tuple[int, int, int] | None:
+    """Try once before releasing custody, preserving the VACUUM outcome.
+
+    The restore reserve is only checked before starting: ``remaining`` bounds SQLite lock waiting,
+    not the checkpoint's WAL-copy I/O once it runs. The replaced FULL checkpoint had the same limit.
+    """
+    from .maintenance_control import hold_clock
+
+    started = time.monotonic()
+    event = dict(phase=phase, mode="TRUNCATE", wal_before_bytes=get_wal_size(str(config.db_path)))
+    result = None
+    busy = None
+    reason = ""
+    try:
+        remaining = POST_VACUUM_BUSY_S if deadline is None else deadline - HOLD_UNWIND_S - hold_clock()
+        if remaining <= 0:
+            reason = "hold-unwind-reserve"
+        else:
+            result = checkpoint(
+                str(config.db_path),
+                "TRUNCATE",
+                guard_timeout_seconds=0,
+                busy_timeout_seconds=min(POST_VACUUM_BUSY_S, remaining),
+            )
+            busy = result[0]
+            if busy:
+                reason = "reader-or-writer-busy"
+    except CheckpointGuardTimeout:
+        reason = "checkpoint-guard-busy"
+    except Exception as exc:
+        reason = f"{type(exc).__name__}: {exc}"
+    event.update(
+        wal_after_bytes=get_wal_size(str(config.db_path)),
+        duration_ms=(time.monotonic() - started) * 1000,
+        busy=busy,
+        deferred=bool(reason),
+        reason=reason,
+        checkpoint=result,
+    )
+    try:
+        _write_log(config.log_path, event)
+    except Exception as exc:
+        # A failed cleanup receipt must not replace the VACUUM failure or delay restoration.
+        print(f"maintenance WAL reclaim: {json.dumps(event)}; log failed: {exc}", file=sys.stderr)
+    return result
+
+
 def _file_size(path: Path) -> int:
     try:
         return path.stat().st_size
@@ -986,6 +1037,7 @@ def _vacuum(db_path: Path, *, deadline: float | None = None) -> tuple[int, int]:
     before = db_path.stat().st_size
     conn = sqlite3.connect(db_path)
     try:
+        configure_writer_wal_policy(conn)
         if cutoff is not None:
             # Polled on the VACUUM's own thread: no timer race, and an expiry before the statement
             # starts still interrupts it (sqlite3_interrupt with no running statement is a no-op).
@@ -1345,10 +1397,17 @@ def run_maintenance(mode: str, *, config: MaintenanceConfig | None = None, dry_r
             if mode == "full" and backup is not None:
                 result.actions.append(f"verified_local_backup={backup.get('snapshot')}")
                 hold = booted_out.get("_supervisor_hold")
-                result.vacuum_before_bytes, result.vacuum_after_bytes = _vacuum(
-                    config.db_path, deadline=getattr(hold, "deadline", None)
-                )
-                result.checkpoint = _checkpoint_full(config.db_path)
+                deadline = getattr(hold, "deadline", None)
+                # _vacuum closes its connection before returning or raising. Never reclaim
+                # inside its transaction, and never renew custody just to reclaim disk space.
+                # SystemExit/KeyboardInterrupt (SIGTERM) skip the reclaim and unwind straight
+                # to service restore: a full-size TRUNCATE there would delay it by seconds.
+                try:
+                    result.vacuum_before_bytes, result.vacuum_after_bytes = _vacuum(config.db_path, deadline=deadline)
+                except Exception:
+                    result.checkpoint = _reclaim_vacuum_wal(config, deadline=deadline, phase="vacuum-failure")
+                    raise
+                result.checkpoint = _reclaim_vacuum_wal(config, deadline=deadline, phase="post-vacuum")
             if mode == "burn":
                 result.burn = _run_burn_until_empty(config)
                 if result.burn.failed_files: