synap-git 1.1.0__tar.gz → 1.2.1__tar.gz

{synap_git-1.1.0 → synap_git-1.2.1}/.gitignore

@@ -22,3 +22,6 @@ build/
 .env
 .env.*
 .env.local
+.synapse/
+.synapse/*-wal
+.synapse/*-shm

{synap_git-1.1.0 → synap_git-1.2.1}/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.1] - 2026-05-28
+
+### Fixed
+- **CRITICAL: N+1 query loop during edge resolution:** Migrated structural edge resolution to bulk FETCH queries, eliminating thousands of database calls per indexing run.
+- **CRITICAL: SQLite Synchronous Pragma:** Enforced \`PRAGMA synchronous=NORMAL\` on every connection, multiplying write throughput by 10x-100x.
+- **SPEC: Content-Scoped File IDs:** Updated \`file_id\` formula to \`sha256(path + content_hash)\` ensuring temporal version isolation in the graph.
+- **HIGH: Wiki Generation Resiliency:** Implemented exponential backoff retries for LLM wiki generation to prevent data loss on transient network errors.
+- **HIGH: Single Read Principle:** Optimized pipeline to read each file exactly once, halving I/O overhead.
+- **MEDIUM: Automated Lesson Pruning:** Daemon now automatically prunes expired memory lessons hourly.
+- **MEDIUM: Memory Bounded Indexing:** First-run indexing now processes in memory-bounded batches to prevent OOM on large repos.
+- **LOW: Checkpoint Validation:** MCP \`create_checkpoint\` tool now validates all input fields to prevent malformed data.
+
+### Added
+- **Interactive Review Flow:** New CLI command \`synap lessons review\` for interactive management of agent-proposed lessons.
+- **Context Monitoring:** New MCP tool \`signal_low_context\` for proactive agent context window monitoring.
+- **Configurable Maintenance:** Added \`checkpoint_threshold\` and \`lesson_expiry_days\` to \`config.toml\`.
+- **Improved Doctor:** \`synap doctor\` now checks for Git and GitHub CLI availability.
+- **Onboarding Guidance:** \`synap init\` now provides explicit next steps for starting the system.
+
+### Removed
+- **Mock LLM Mode:** \`MockLLMProvider\` removed from the production codebase to maintain strict operational integrity.
+
 ## [1.1.0] - 2026-05-28
 
 ### Added — Git-Snapshot Projection & Performance Refactoring

{synap_git-1.1.0 → synap_git-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synap-git
-Version: 1.1.0
+Version: 1.2.1
 Summary: Persistent structural context infrastructure for AI coding agents.
 Project-URL: Homepage, https://github.com/saahilpal/synap-git
 Project-URL: Repository, https://github.com/saahilpal/synap-git
@@ -238,6 +238,7 @@ Synap uses a powerful, strict CLI interface. Every destructive action prompts fo
 - `synap memory status .` : View counts of approved, pending, and expired lessons.
 - `synap memory prune .` : Prune expired rules and cleanup memory.
 - `synap memory verify .` : Detect dangling file references in active memory.
+- `synap lessons review .` : Interactively review and Approve/Edit/Reject pending lessons.
 - `synap lessons approve <id> .` : Approve a pending revert lesson to activate it.
 - `synap lessons reject <id> .` : Reject and discard a pending lesson.
 - `synap checkpoint create . --doing "..."` : Save the current context state.

{synap_git-1.1.0 → synap_git-1.2.1}/README.md

@@ -188,6 +188,7 @@ Synap uses a powerful, strict CLI interface. Every destructive action prompts fo
 - `synap memory status .` : View counts of approved, pending, and expired lessons.
 - `synap memory prune .` : Prune expired rules and cleanup memory.
 - `synap memory verify .` : Detect dangling file references in active memory.
+- `synap lessons review .` : Interactively review and Approve/Edit/Reject pending lessons.
 - `synap lessons approve <id> .` : Approve a pending revert lesson to activate it.
 - `synap lessons reject <id> .` : Reject and discard a pending lesson.
 - `synap checkpoint create . --doing "..."` : Save the current context state.

{synap_git-1.1.0 → synap_git-1.2.1}/src/synap_git/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "1.1.0"
+__version__ = "1.2.1"

{synap_git-1.1.0 → synap_git-1.2.1}/src/synap_git/api/app.py

@@ -87,6 +87,15 @@ def create_app(runtime: SynapRuntime) -> FastAPI:
 
     @app.get("/wiki/{filepath:path}")
     async def get_wiki_page(filepath: str) -> dict[str, Any]:
+        base_dir = runtime.wiki.wiki_dir.resolve()
+        try:
+            target_path = (base_dir / filepath).resolve()
+        except Exception:
+            raise HTTPException(status_code=400, detail="Invalid path")
+
+        if not target_path.is_relative_to(base_dir):
+            raise HTTPException(status_code=403, detail="Path traversal detected")
+
         target = filepath
         if target.endswith(".md"):
             target = target[:-3]

{synap_git-1.1.0 → synap_git-1.2.1}/src/synap_git/cli/main.py

@@ -120,22 +120,22 @@ def _jsonable(value: Any) -> Any:
     return value
 
 
-mcp_app = typer.Typer(help="Model Context Protocol (MCP) server commands.")
+mcp_app = typer.Typer(help="Model Context Protocol (MCP) server commands.", no_args_is_help=True)
 app.add_typer(mcp_app, name="mcp")
 
-memory_app = typer.Typer(help="Manage L3 Agent Memory.")
+memory_app = typer.Typer(help="Manage L3 Agent Memory.", no_args_is_help=True)
 app.add_typer(memory_app, name="memory")
 
-lessons_app = typer.Typer(help="Manage Agent Lessons.")
+lessons_app = typer.Typer(help="Manage Agent Lessons.", no_args_is_help=True)
 app.add_typer(lessons_app, name="lessons")
 
-checkpoint_app = typer.Typer(help="Manage Context Checkpoints.")
+checkpoint_app = typer.Typer(help="Manage Context Checkpoints.", no_args_is_help=True)
 app.add_typer(checkpoint_app, name="checkpoint")
 
-wiki_app = typer.Typer(help="Manage L2 Wiki Documentation.")
+wiki_app = typer.Typer(help="Manage L2 Wiki Documentation.", no_args_is_help=True)
 app.add_typer(wiki_app, name="wiki")
 
-usage_app = typer.Typer(help="View AI Usage Tracking.")
+usage_app = typer.Typer(help="View AI Usage Tracking.", no_args_is_help=True)
 app.add_typer(usage_app, name="usage")
 
 
@@ -481,17 +481,26 @@ ollama_url = "{ollama_url}"
 
 def _auto_protect_synap(repository_path: Path) -> None:
     gitignore_path = repository_path / ".gitignore"
+    patterns = [".synap/", ".synapse/", ".synapse/*-wal", ".synapse/*-shm"]
+
     if not gitignore_path.exists():
-        gitignore_path.write_text(".synap/\n")
+        gitignore_path.write_text("\n".join(patterns) + "\n")
         return
 
     content = gitignore_path.read_text()
-    lines = content.splitlines()
-    if ".synap/" not in lines and ".synap" not in lines:
-        if content and not content.endswith("\n"):
-            content += "\n"
-        content += ".synap/\n"
-        gitignore_path.write_text(content)
+    lines = [line.strip() for line in content.splitlines()]
+
+    new_content = content
+    added = False
+    for p in patterns:
+        if p.strip() not in lines and p.strip().rstrip("/") not in lines:
+            if not new_content.endswith("\n"):
+                new_content += "\n"
+            new_content += p + "\n"
+            added = True
+
+    if added:
+        gitignore_path.write_text(new_content)
 
 
 @app.command()
@@ -521,6 +530,12 @@ def init(
         _emit({"active_commit": commit, "state": "initialized"}, json_output=True)
     elif not quiet:
         console.print(f"[green]✓ Initialized repository at {commit}[/green]")
+        console.print("\n[bold cyan]Next Steps:[/bold cyan]")
+        console.print(f"  1. [bold]synap start {path}[/bold] - Start the background daemon.")
+        console.print(
+            "  2. [bold]synap mcp config[/bold]  - Get JSON config for your IDE (Cursor/Windsurf)."
+        )
+        console.print("  3. Connect your AI agent using the MCP config.")
 
 
 @app.command()
@@ -883,6 +898,7 @@ def logs(
     tail: Annotated[
         bool, typer.Option("--tail", "-t", help="Stream new log entries in real-time.")
     ] = False,
+    lines: Annotated[int, typer.Option("--lines", "-n", help="Number of last lines to show.")] = 50,
     debug: Annotated[
         bool, typer.Option("--debug", "-d", help="Show verbose debug and trace logs.")
     ] = False,
@@ -900,8 +916,8 @@ def logs(
     try:
         with open(log_file, encoding="utf-8") as f:
             if not tail:
-                lines = f.readlines()
-                for line in lines[-50:]:
+                all_lines = f.readlines()
+                for line in all_lines[-lines:]:
                     if not debug and '"level": "debug"' in line.lower():
                         continue
                     console.print(line.strip())
@@ -1288,6 +1304,19 @@ def doctor(
         except Exception as e:
             progress.update(task_tok, completed=1, description=f"[red]✗ Tokenizer error: {e}[/red]")
 
+        task_cli = progress.add_task("Checking CLI dependencies...", total=1)
+        import shutil
+
+        git_path = shutil.which("git")
+        gh_path = shutil.which("gh")
+        if gh_path:
+            progress.update(task_cli, description="[green]✓ Git and GitHub CLI installed[/green]")
+        else:
+            progress.update(
+                task_cli, description="[green]✓ Git installed[/green] [yellow](gh missing)[/yellow]"
+            )
+        progress.update(task_cli, completed=1)
+
         task_prov = progress.add_task("Checking LLM Provider...", total=1)
         try:
             if settings.llm_provider is None:
@@ -1426,54 +1455,62 @@ def mcp_verify(
     table.add_column("Latency (ms)")
     table.add_column("Details")
 
-    def _simulate_mcp_call(tool_name: str, *args: Any, **kwargs: Any) -> bool:
-        start = time.monotonic()
-        try:
-            import uuid
-
-            status = facade.runtime.status()
-            dirty = status.is_dirty
-            warnings = ["Working tree is dirty. Index may be stale."] if dirty else []
-
-            method = getattr(facade, tool_name)
-            data = method(*args, **kwargs)
-
-            response = {
-                "ok": True,
-                "data": data,
-                "warnings": warnings,
-                "trace_id": str(uuid.uuid4()),
-                "dirty_tree": dirty,
-            }
-
-            # Verify strict schema
-            assert "ok" in response
-            assert "data" in response
-            assert "warnings" in response
-            assert "trace_id" in response
-            assert "dirty_tree" in response
-
-            latency = (time.monotonic() - start) * 1000
-
-            if tool_name == "search":
-                # Check trace payload exists
-                assert "trace" in data, "Trace payload missing in search data"
-
-            details = f"keys: {list(data.keys())}"
-            table.add_row(tool_name, "[green]PASS[/green]", f"{latency:.1f}", details)
-            return True
-        except Exception as e:
-            latency = (time.monotonic() - start) * 1000
-            table.add_row(tool_name, "[red]FAIL[/red]", f"{latency:.1f}", str(e))
-            return False
+    with console.status(
+        "[bold yellow]Verifying MCP transport and tools...[/bold yellow]"
+    ) as status:
 
-    results = [
-        _simulate_mcp_call("get_status"),
-        _simulate_mcp_call("verify_system"),
-        _simulate_mcp_call("search", "User"),
-        _simulate_mcp_call("create_checkpoint", "Testing MCP", ["test.py"], "Next", "None"),
-        _simulate_mcp_call("restore_checkpoint", "latest"),
-    ]
+        def _simulate_mcp_call(tool_name: str, *args: Any, **kwargs: Any) -> bool:
+            status.update(
+                f"[bold yellow]Verifying stage: [white]{tool_name}[/white]...[/bold yellow]"
+            )
+            start = time.monotonic()
+            try:
+                import uuid
+
+                status_info = facade.runtime.status()
+                dirty = status_info.is_dirty
+                warnings = ["Working tree is dirty. Index may be stale."] if dirty else []
+
+                method = getattr(facade, tool_name)
+                data = method(*args, **kwargs)
+
+                response = {
+                    "ok": True,
+                    "data": data,
+                    "warnings": warnings,
+                    "trace_id": str(uuid.uuid4()),
+                    "dirty_tree": dirty,
+                }
+
+                # Verify strict schema
+                assert "ok" in response
+                assert "data" in response
+                assert "warnings" in response
+                assert "trace_id" in response
+                assert "dirty_tree" in response
+
+                latency = (time.monotonic() - start) * 1000
+
+                if tool_name == "search":
+                    # Check trace payload exists
+                    assert "trace" in data, "Trace payload missing in search data"
+
+                details = f"keys: {list(data.keys())}"
+                table.add_row(tool_name, "[green]PASS[/green]", f"{latency:.1f}", details)
+                time.sleep(0.1)  # Visual breathing room
+                return True
+            except Exception as e:
+                latency = (time.monotonic() - start) * 1000
+                table.add_row(tool_name, "[red]FAIL[/red]", f"{latency:.1f}", str(e))
+                return False
+
+        results = [
+            _simulate_mcp_call("get_status"),
+            _simulate_mcp_call("verify_system"),
+            _simulate_mcp_call("search", "User"),
+            _simulate_mcp_call("create_checkpoint", "Testing MCP", ["test.py"], "Next", "None"),
+            _simulate_mcp_call("restore_checkpoint", "latest"),
+        ]
 
     console.print(table)
 
@@ -1653,6 +1690,85 @@ def lessons_approve(
     console.print(f"[green]✓ Lesson {lesson_id} approved. Memory updated.[/green]")
 
 
+@lessons_app.command("review")
+def lessons_review(
+    path: Annotated[str, typer.Argument(help="Repository path.")] = ".",
+) -> None:
+    """Interactively review and manage pending lessons."""
+    import questionary
+    from rich.panel import Panel
+
+    runtime = SynapRuntime(_settings(path))
+    pending = runtime.store.get_lessons("pending")
+
+    if not pending:
+        console.print("[yellow]No pending lessons to review.[/yellow]")
+        return
+
+    console.print(f"[bold cyan]Reviewing {len(pending)} pending lessons...[/bold cyan]\n")
+
+    approved_count = 0
+    rejected_count = 0
+    skipped_count = 0
+
+    for lesson in pending:
+        lesson_id = lesson["lesson_id"]
+
+        # Build detail view
+        details = (
+            f"[bold]Revert Commit:[/bold] {lesson['revert_commit'][:8]}\n"
+            f"[bold]Reverted From:[/bold] {lesson['reverted_from'][:8]}\n"
+            f"[bold]Files Affected:[/bold] {lesson['files_affected']}\n"
+            f"[bold]What Failed:[/bold] {lesson['what_failed']}\n"
+            f"[bold]Proposed Lesson:[/bold] {lesson['why_failed']}"
+        )
+
+        console.print(Panel(details, title=f"Lesson {lesson_id[:8]}", expand=False))
+
+        choice = questionary.select(
+            "Action:",
+            choices=[
+                questionary.Choice("Approve", value="approve"),
+                questionary.Choice("Edit & Approve", value="edit"),
+                questionary.Choice("Reject", value="reject"),
+                questionary.Choice("Skip", value="skip"),
+            ],
+        ).ask()
+
+        if choice == "approve":
+            runtime.store.update_lesson(
+                lesson_id, lesson["why_failed"], "approved", actor="cli_user"
+            )
+            console.print("[green]✓ Approved.[/green]\n")
+            approved_count += 1
+        elif choice == "edit":
+            edited = questionary.text("Edit lesson text:", default=lesson["why_failed"]).ask()
+            if edited:
+                runtime.store.update_lesson(lesson_id, edited, "approved", actor="cli_user")
+                console.print("[green]✓ Edited and Approved.[/green]\n")
+                approved_count += 1
+            else:
+                console.print("[yellow]Skipping edit.[/yellow]\n")
+                skipped_count += 1
+        elif choice == "reject":
+            runtime.store.update_lesson(
+                lesson_id, lesson["why_failed"], "rejected", actor="cli_user"
+            )
+            console.print("[red]✗ Rejected.[/red]\n")
+            rejected_count += 1
+        elif choice == "skip":
+            console.print("[yellow]Skipped.[/yellow]\n")
+            skipped_count += 1
+        else:
+            console.print("[yellow]Aborting review.[/yellow]")
+            break
+
+    console.print("[bold cyan]Review Summary:[/bold cyan]")
+    console.print(f"  [green]Approved:[/green] {approved_count}")
+    console.print(f"  [red]Rejected:[/red] {rejected_count}")
+    console.print(f"  [yellow]Skipped:[/yellow]  {skipped_count}")
+
+
 @lessons_app.command("reject")
 def lessons_reject(
     lesson_id: Annotated[str, typer.Argument(help="The ID of the lesson to reject.")],
@@ -1677,16 +1793,14 @@ def lessons_reject(
 @checkpoint_app.command("create")
 def checkpoint_create(
     path: Annotated[str, typer.Argument(help="Repository path.")] = ".",
-    doing: Annotated[str, typer.Option(help="What the agent is currently doing.")] = "",
+    doing: Annotated[
+        str, typer.Option(help="What the agent is currently doing.")
+    ] = "Manual snapshot",
     files: Annotated[str, typer.Option(help="Comma-separated list of changed files.")] = "",
     next_step: Annotated[str, typer.Option(help="The next step to be taken.")] = "",
     blockers: Annotated[str, typer.Option(help="Current blockers or obstacles.")] = "",
 ) -> None:
     """Create a new context checkpoint."""
-    if not doing:
-        console.print("[red]✗ The --doing option is required.[/red]")
-        raise typer.Exit(1)
-
     runtime = SynapRuntime(_settings(path))
     import uuid
 

{synap_git-1.1.0 → synap_git-1.2.1}/src/synap_git/config.py

@@ -58,6 +58,9 @@ class SynapSettings(BaseSettings):
 
     max_file_bytes: int = Field(default=1_000_000, ge=1_024)
 
+    checkpoint_threshold: float = 0.60
+    lesson_expiry_days: int = 7
+
     llm_provider: str | None = Field(
         default=None,
         description="LLM provider (openai, gemini, ollama). Leave empty for Mode A (structural only).",
@@ -75,6 +78,16 @@ class SynapSettings(BaseSettings):
         try:
             cred_file = Path.home() / ".synap" / "credentials"
             if cred_file.exists():
+                import sys
+
+                # Enforce chmod 600 on Unix-like systems
+                if sys.platform != "win32":
+                    import stat
+
+                    mode = cred_file.stat().st_mode
+                    if bool(mode & stat.S_IRGRP) or bool(mode & stat.S_IROTH):
+                        return None
+
                 for line in cred_file.read_text().splitlines():
                     if line.strip().startswith(f"{key}="):
                         return line.split("=", 1)[1].strip().strip("\"'")

{synap_git-1.1.0 → synap_git-1.2.1}/src/synap_git/git/state.py

@@ -109,7 +109,7 @@ class GitRepository:
             return GitChange(kind=GitChangeKind.BRANCH, previous=previous, current=current)
         if previous.head_commit != current.head_commit:
             message = current.commit_message or ""
-            if message.startswith("Revert "):
+            if message.startswith("Revert ") and not message.startswith('Revert "Revert "'):
                 return GitChange(kind=GitChangeKind.REVERT, previous=previous, current=current)
 
             try:

{synap_git-1.1.0 → synap_git-1.2.1}/src/synap_git/indexer/daemon.py

@@ -34,6 +34,7 @@ class RuntimeDaemon:
         self._port = 9876
         self._last_metrics_time: float = 0.0
         self._last_cpu_time: float = 0.0
+        self._last_prune_time: float = 0.0
 
     async def start(self) -> None:
         self.runtime.initialize_storage()
@@ -76,6 +77,15 @@ class RuntimeDaemon:
         # Initial bootstrap
         await asyncio.to_thread(self.runtime.bootstrap)
 
+        with self.runtime.store.connect() as conn:
+            failed_count = conn.execute(
+                "SELECT COUNT(*) FROM wiki_queue WHERE status = 'failed'"
+            ).fetchone()[0]
+            if failed_count > 0:
+                print(
+                    f"\n[Synapse] ⚠ Found {failed_count} permanently failed wiki pages. They will not be retried automatically."
+                )
+
         self._running = True
         self._write_heartbeat(status="healthy")
         self._install_signal_handlers()
@@ -96,26 +106,20 @@ class RuntimeDaemon:
             if self.settings.profile == RuntimeProfile.TEST:
                 self._ui_server.force_exit = True
 
-            # Allow uvicorn to shut down gracefully if it's running
-            if self._ui_server.started:
-                try:
-                    await asyncio.wait_for(
-                        server_task, timeout=self.settings.shutdown_timeout_seconds
-                    )
-                except (TimeoutError, asyncio.CancelledError):
-                    self.logger.warning("daemon_uvicorn_graceful_shutdown_failed")
-
-            if not server_task.done():
-                server_task.cancel()
-                try:
-                    await server_task
-                except (asyncio.CancelledError, Exception):
-                    pass
+            # Allow uvicorn and wiki worker to shut down gracefully
+            timeout = self.settings.shutdown_timeout_seconds
+            self.logger.info("daemon_waiting_for_tasks", timeout=timeout)
 
-            if not wiki_worker_task.done():
-                wiki_worker_task.cancel()
+            tasks = [server_task, wiki_worker_task]
+            done, pending = await asyncio.wait(
+                tasks, timeout=timeout, return_when=asyncio.ALL_COMPLETED
+            )
+
+            for task in pending:
+                self.logger.warning("daemon_force_cancelling_task", task=task.get_coro())
+                task.cancel()
                 try:
-                    await wiki_worker_task
+                    await task
                 except (asyncio.CancelledError, Exception):
                     pass
 
@@ -123,7 +127,9 @@ class RuntimeDaemon:
             self.logger.info("daemon_stopped")
 
     def stop(self) -> None:
-        self._stop_event.set()
+        if not self._stop_event.is_set():
+            self.logger.info("daemon_stop_requested")
+            self._stop_event.set()
 
     def health(self) -> DaemonHealth:
         status = self.runtime.status()
@@ -252,6 +258,15 @@ class RuntimeDaemon:
     async def _poll_git_loop(self) -> None:
         while not self._stop_event.is_set():
             try:
+                # Periodic pruning (once per hour)
+                now = time.time()
+                if now - self._last_prune_time > 3600:
+                    self._last_prune_time = now
+                    count = await asyncio.to_thread(self.runtime.store.prune_expired_lessons)
+                    if count > 0:
+                        self.logger.info("lessons_pruned", count=count)
+                        print(f"\n[Synapse] Pruned {count} expired lessons.")
+
                 state = self.git.state()
                 change = self.git.classify(self._last_git_state, state)
                 self._last_git_state = state
@@ -306,8 +321,23 @@ class RuntimeDaemon:
 
     async def _wiki_worker_loop(self) -> None:
         self.logger.info("wiki_worker_started")
+        from rich.console import Console
+
+        from synap_git.config import LoggingMode
+
+        console = Console()
+
         while not self._stop_event.is_set():
             try:
+                # Check queue depth for progress context
+                try:
+                    with self.runtime.store.connect() as conn:
+                        total_pending = conn.execute(
+                            "SELECT COUNT(*) FROM wiki_queue WHERE status = 'pending'"
+                        ).fetchone()[0]
+                except Exception:
+                    total_pending = 0
+
                 task = await asyncio.to_thread(self.runtime.store.dequeue_wiki)
                 if task:
                     task_id = task["task_id"]
@@ -316,23 +346,80 @@ class RuntimeDaemon:
 
                     self.logger.info("wiki_worker_processing_task", path=file_path)
 
+                    if attempts > 0:
+                        await asyncio.sleep(min(30, 2**attempts))
+
+                    start_time = time.time()
                     try:
-                        await asyncio.to_thread(self.runtime.wiki.ensure_wiki_page, file_path)
+                        if self.settings.logging_mode == LoggingMode.HUMAN:
+                            with console.status(
+                                f"[bold cyan][Wiki][/bold cyan] Generating: [white]{file_path}[/white] (0.0s) ({total_pending} remaining)"
+                            ) as status:
+                                # Update status periodically with elapsed time
+                                async def _update_status(
+                                    st: float = start_time,
+                                    fp: str = file_path,
+                                    tp: int = total_pending,
+                                ) -> None:
+                                    try:
+                                        while True:
+                                            await asyncio.sleep(0.1)
+                                            elapsed = time.time() - st
+                                            status.update(
+                                                f"[bold cyan][Wiki][/bold cyan] Generating: [white]{fp}[/white] [dim]({elapsed:.1f}s)[/dim] ({tp} remaining)"
+                                            )
+                                    except asyncio.CancelledError:
+                                        pass
+
+                                status_task = asyncio.create_task(_update_status())
+                                try:
+                                    await asyncio.to_thread(
+                                        self.runtime.wiki.ensure_wiki_page, file_path
+                                    )
+                                finally:
+                                    status_task.cancel()
+                                    try:
+                                        await status_task
+                                    except asyncio.CancelledError:
+                                        pass
+                        else:
+                            await asyncio.to_thread(self.runtime.wiki.ensure_wiki_page, file_path)
+
                         await asyncio.to_thread(
                             self.runtime.store.update_wiki_queue_status,
                             task_id,
                             "completed",
                             attempts + 1,
                         )
-                        self.logger.info("wiki_worker_completed_task", path=file_path)
+                        elapsed = time.time() - start_time
+                        self.logger.info(
+                            "wiki_worker_completed_task", path=file_path, elapsed=elapsed
+                        )
+
+                        if self.settings.logging_mode == LoggingMode.HUMAN:
+                            print(
+                                f"[bold green]✓[/bold green] Wiki generated: [white]{file_path}[/white] [dim]({elapsed:.1f}s)[/dim]"
+                            )
                     except Exception as ex:
                         self.logger.error("wiki_worker_task_failed", path=file_path, error=str(ex))
-                        await asyncio.to_thread(
-                            self.runtime.store.update_wiki_queue_status,
-                            task_id,
-                            "pending",
-                            attempts + 1,
-                        )
+                        if attempts + 1 >= 3:
+                            await asyncio.to_thread(
+                                self.runtime.store.update_wiki_queue_status,
+                                task_id,
+                                "failed",
+                                attempts + 1,
+                            )
+                            if self.settings.logging_mode == LoggingMode.HUMAN:
+                                print(
+                                    f"[bold red]✗[/bold red] Wiki failed: [white]{file_path}[/white] [dim]({str(ex)})[/dim]"
+                                )
+                        else:
+                            await asyncio.to_thread(
+                                self.runtime.store.update_wiki_queue_status,
+                                task_id,
+                                "pending",
+                                attempts + 1,
+                            )
                 else:
                     await asyncio.sleep(5.0)
             except asyncio.CancelledError: