loki-mode 6.60.0 → 6.62.0

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Complete installation instructions for all platforms and use cases.
 
-**Version:** v6.60.0
+**Version:** v6.62.0
 
 ---
 
@@ -54,7 +54,7 @@ npm install -g loki-mode
 
 Installs the `loki` CLI and automatically sets up the skill for Claude Code, Codex CLI, and Gemini CLI via the postinstall script.
 
-**Prerequisites:** Node.js 16+
+**Prerequisites:** Node.js 18+
 
 **What it does:**
 - Installs the `loki` CLI binary to your PATH

package/events/bus.py

@@ -9,12 +9,12 @@ import json
 import os
 import time
 import uuid
-import fcntl
+from collections import OrderedDict
 from dataclasses import dataclass, asdict
 from datetime import datetime, timezone
 from enum import Enum
 from pathlib import Path
-from typing import Generator, List, Optional, Set, Callable
+from typing import Generator, List, Optional, Callable
 import threading
 
 
@@ -72,11 +72,35 @@ class LokiEvent:
 
     @classmethod
     def from_dict(cls, data: dict) -> 'LokiEvent':
-        """Create event from dictionary."""
+        """Create event from dictionary.
+
+        Handles compound types like 'session_start' by splitting on underscore
+        and using the first token as the event type.
+        """
+        raw_type = data.get('type', '')
+        raw_source = data.get('source', '')
+
+        # Parse event type, handling compound values like "session_start"
+        try:
+            event_type = EventType(raw_type) if raw_type else EventType.STATE
+        except ValueError:
+            # Try splitting compound type on underscore
+            first_token = raw_type.split('_')[0] if raw_type else ''
+            try:
+                event_type = EventType(first_token)
+            except ValueError:
+                event_type = EventType.STATE
+
+        # Parse event source with fallback
+        try:
+            event_source = EventSource(raw_source) if raw_source else EventSource.CLI
+        except ValueError:
+            event_source = EventSource.CLI
+
         return cls(
             id=data.get('id', ''),
-            type=EventType(data['type']) if data.get('type') else EventType.STATE,
-            source=EventSource(data['source']) if data.get('source') else EventSource.CLI,
+            type=event_type,
+            source=event_source,
             timestamp=data.get('timestamp', ''),
             payload=data.get('payload', {}),
             version=data.get('version', '1.0')
@@ -115,44 +139,54 @@ class EventBus:
         self.pending_dir.mkdir(parents=True, exist_ok=True)
         self.archive_dir.mkdir(parents=True, exist_ok=True)
 
-        # Track processed event IDs to avoid reprocessing
-        self._processed_ids: Set[str] = self._load_processed_ids()
+        # Track processed event IDs with deterministic FIFO eviction order
+        self._processed_ids: OrderedDict = self._load_processed_ids()
 
         # Subscribers for callback-based subscription
         self._subscribers: List[tuple] = []  # [(types, callback), ...]
         self._running = False
         self._thread: Optional[threading.Thread] = None
 
-    def _load_processed_ids(self) -> Set[str]:
-        """Load set of already processed event IDs."""
+    def _load_processed_ids(self) -> OrderedDict:
+        """Load ordered dict of already processed event IDs."""
         try:
             if self.processed_file.exists():
                 with open(self.processed_file, 'r') as f:
                     data = json.load(f)
                     # Keep only last 1000 IDs to prevent unbounded growth
-                    return set(data.get('ids', [])[-1000:])
+                    ids = data.get('ids', [])[-1000:]
+                    return OrderedDict.fromkeys(ids)
         except (json.JSONDecodeError, IOError):
             pass
-        return set()
+        return OrderedDict()
 
     def _save_processed_id(self, event_id: str) -> None:
         """Save event ID as processed."""
-        self._processed_ids.add(event_id)
+        self._processed_ids[event_id] = None
 
-        # Prune to last 1000 (always, regardless of disk write outcome)
-        if len(self._processed_ids) > 1000:
-            pruned = list(self._processed_ids)[-1000:]
-            self._processed_ids = set(pruned)
+        # Prune to last 1000 using FIFO eviction (deterministic order)
+        while len(self._processed_ids) > 1000:
+            self._processed_ids.popitem(last=False)
 
+        lockfile = self.processed_file.with_suffix('.json.lock')
         try:
-            with open(self.processed_file, 'w') as f:
-                fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+            # Use lockfile approach (cross-platform, compatible with TS)
+            fd = os.open(str(lockfile), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            os.close(fd)
+            try:
+                with open(self.processed_file, 'w') as f:
+                    json.dump({'ids': list(self._processed_ids.keys())}, f)
+            finally:
                 try:
-                    json.dump({'ids': list(self._processed_ids)}, f)
-                finally:
-                    fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+                    lockfile.unlink()
+                except OSError:
+                    pass
+        except FileExistsError:
+            # Another process holds the lock; skip this disk write.
+            # In-memory state is already updated.
+            pass
         except IOError:
-            # Disk write failed -- set is already pruned in memory above
+            # Disk write failed -- in-memory state is already updated
             pass
 
     def emit(self, event: LokiEvent) -> str:
@@ -166,14 +200,25 @@ class EventBus:
             The event ID
         """
         event_file = self.pending_dir / f"{event.timestamp.replace(':', '-')}_{event.id}.json"
+        lockfile = event_file.with_suffix('.json.lock')
 
         try:
-            with open(event_file, 'w') as f:
-                fcntl.flock(f.fileno(), fcntl.LOCK_EX)
-                try:
+            # Use lockfile approach (cross-platform, compatible with TS)
+            fd = os.open(str(lockfile), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            os.close(fd)
+            try:
+                with open(event_file, 'w') as f:
                     json.dump(event.to_dict(), f, indent=2)
-                finally:
-                    fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+            finally:
+                try:
+                    lockfile.unlink()
+                except OSError:
+                    pass
+        except FileExistsError:
+            # Lock held by another process; write without lock as fallback
+            # Event files are unique per ID so collision is unlikely
+            with open(event_file, 'w') as f:
+                json.dump(event.to_dict(), f, indent=2)
         except IOError as e:
             raise RuntimeError(f"Failed to emit event: {e}")
 
@@ -286,8 +331,11 @@ class EventBus:
             if timeout and (time.time() - start_time) > timeout:
                 break
 
+            # Set last_check BEFORE fetching to avoid missing events that
+            # arrive between fetch and timestamp update
+            next_check = datetime.now(timezone.utc).isoformat()
             events = self.get_pending_events(types=types, since=last_check)
-            last_check = datetime.now(timezone.utc).isoformat()
+            last_check = next_check
 
             for event in events:
                 yield event
@@ -410,6 +458,59 @@ class EventBus:
                 pass
         return count
 
+    def import_from_jsonl(self, limit: int = 100) -> int:
+        """Bridge: read events from events.jsonl and import as pending events.
+
+        This bridges the gap between the append-only events.jsonl log
+        (written by emit.sh and run.sh) and the pending/ directory
+        consumed by subscribers.
+
+        Args:
+            limit: Maximum number of recent events to import
+
+        Returns:
+            Number of events imported
+        """
+        jsonl_file = self.loki_dir / 'events.jsonl'
+        if not jsonl_file.exists():
+            return 0
+
+        imported = 0
+        try:
+            with open(jsonl_file, 'r') as f:
+                # Read from end of file to get most recent events
+                lines = f.readlines()
+                recent = lines[-limit:] if len(lines) > limit else lines
+
+            for line in recent:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    data = json.loads(line)
+                    event = LokiEvent.from_dict(data)
+
+                    # Skip if already processed
+                    if event.id in self._processed_ids:
+                        continue
+
+                    # Check if pending file already exists
+                    existing = list(self.pending_dir.glob(f'*_{event.id}.json'))
+                    if existing:
+                        continue
+
+                    # Write as pending event
+                    event_file = self.pending_dir / f"{event.timestamp.replace(':', '-')}_{event.id}.json"
+                    with open(event_file, 'w') as f:
+                        json.dump(event.to_dict(), f, indent=2)
+                    imported += 1
+                except (json.JSONDecodeError, KeyError):
+                    continue
+        except IOError:
+            pass
+
+        return imported
+
     def clear_archive(self, older_than_days: int = 7) -> int:
         """
         Clear archived events older than specified days.

package/events/bus.ts

@@ -69,40 +69,54 @@ function getTimestamp(): string {
   return new Date().toISOString();
 }
 
+/**
+ * Sleep helper that does not busy-wait.
+ */
+function sleepSync(ms: number): void {
+  const end = Date.now() + ms;
+  while (Date.now() < end) {
+    // Intentional short spin -- only used for brief lock retries (< 200ms)
+  }
+}
+
 /**
  * Write a file with an exclusive lockfile to prevent concurrent corruption.
  * Creates a .lock file, writes data, then removes the lock.
+ * If the lock cannot be acquired after retries, the write is skipped
+ * and a warning is logged to stderr.
  */
 function writeFileWithLock(filepath: string, data: string): void {
   const lockfile = filepath + ".lock";
-  let fd: number | null = null;
-  try {
-    // Acquire lock by creating lockfile exclusively (fails if already exists)
-    fd = fs.openSync(lockfile, "wx");
-    fs.closeSync(fd);
-    fd = null;
-    // Write the actual data
-    fs.writeFileSync(filepath, data);
-  } catch (e: unknown) {
-    // If lock acquisition failed (file exists), retry once after brief delay
-    if (e instanceof Error && "code" in e && (e as NodeJS.ErrnoException).code === "EEXIST") {
-      // Another process holds the lock; wait briefly and retry
-      const start = Date.now();
-      while (fs.existsSync(lockfile) && Date.now() - start < 1000) {
-        // Busy-wait up to 1 second
-      }
-      try {
-        fd = fs.openSync(lockfile, "wx");
-        fs.closeSync(fd);
-        fd = null;
-        fs.writeFileSync(filepath, data);
-      } catch {
-        // Fall back to unlocked write
-        fs.writeFileSync(filepath, data);
+  const maxRetries = 5;
+  const retryDelayMs = 200;
+  let acquired = false;
+
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      const fd = fs.openSync(lockfile, "wx");
+      fs.closeSync(fd);
+      acquired = true;
+      break;
+    } catch (e: unknown) {
+      if (e instanceof Error && "code" in e && (e as NodeJS.ErrnoException).code === "EEXIST") {
+        // Lock held by another process; wait and retry
+        if (attempt < maxRetries - 1) {
+          sleepSync(retryDelayMs);
+        }
+      } else {
+        throw e;
       }
-    } else {
-      throw e;
     }
+  }
+
+  if (!acquired) {
+    // Lock could not be acquired after retries -- skip write to avoid corruption
+    process.stderr.write(`[loki-events] WARNING: could not acquire lock for ${filepath}, skipping write\n`);
+    return;
+  }
+
+  try {
+    fs.writeFileSync(filepath, data);
   } finally {
     try {
       fs.unlinkSync(lockfile);
@@ -124,7 +138,7 @@ export class EventBus {
   private processedIds: Set<string>;
   private subscribers: Array<{ types: EventType[] | null; callback: EventCallback }>;
   private running: boolean;
-  private pollInterval: NodeJS.Timer | null;
+  private pollInterval: ReturnType<typeof setInterval> | null;
 
   constructor(lokiDir: string = ".loki") {
     this.lokiDir = lokiDir;

package/events/emit.sh

@@ -12,7 +12,7 @@
 # Environment:
 #   LOKI_DIR - Path to .loki directory (default: .loki)
 
-set -uo pipefail
+set -euo pipefail
 
 # Configuration
 LOKI_DIR="${LOKI_DIR:-.loki}"

package/integrations/openclaw/README.md

@@ -0,0 +1,139 @@
+# Loki Mode - OpenClaw Integration
+
+Run Loki Mode autonomous SDLC sessions from any OpenClaw channel (Slack, Discord, Teams, web).
+
+## Installation
+
+1. Install Loki Mode CLI:
+   ```bash
+   npm install -g loki-mode
+   # or
+   brew install asklokesh/tap/loki-mode
+   ```
+
+2. Copy skill to OpenClaw workspace:
+   ```bash
+   cp -r integrations/openclaw/ ~/.openclaw/workspace/skills/loki-mode/
+   ```
+
+3. Configure API keys in the OpenClaw environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY).
+
+## Usage
+
+From any connected channel, the agent will invoke Loki Mode when:
+- You ask it to "build" or "implement" something from a PRD
+- You say "loki mode" with a project reference
+- You provide requirements for autonomous development
+
+## Architecture
+
+```
+Channel (Slack/Discord/Web)
+    |
+    v
+OpenClaw Gateway --> Agent routes to loki-mode skill
+    |
+    v
+loki start --bg --yes <prd>  (background process)
+    |
+    v
+Poll loop: loki status --json (every 30s)
+    |
+    v
+Progress messages back to channel
+```
+
+## Helper Scripts
+
+Two helper scripts are provided in `scripts/` for structured status polling and formatting:
+
+- `poll-status.sh [workdir]` -- Calls `loki status --json` and enriches the output with budget and council data from `.loki/` flat files. Returns a single JSON object.
+- `format-progress.sh` -- Reads the JSON output from `poll-status.sh` via stdin and produces a human-readable multi-line progress message suitable for channel posting.
+
+Example pipeline:
+```bash
+./scripts/poll-status.sh /path/to/project | ./scripts/format-progress.sh
+```
+
+## Configuration
+
+| Env Var | Description | Default |
+|---------|-------------|---------|
+| LOKI_PROVIDER | AI provider (claude/codex/gemini) | claude |
+| LOKI_BUDGET_LIMIT | Cost limit in USD | unlimited |
+| LOKI_MAX_PARALLEL_AGENTS | Max concurrent agents | 10 |
+| LOKI_COMPLEXITY | Force complexity tier (simple/standard/complex) | auto |
+| LOKI_DASHBOARD_PORT | Dashboard HTTP port | 57374 |
+
+## Phase 2: Bridge Daemon (Foundation)
+
+The bridge daemon watches Loki's `.loki/` flat-file events in real time and translates them into OpenClaw gateway messages. This replaces the polling-based approach (Phase 1) with event-driven communication.
+
+### What exists now
+
+| Component | Path | Status |
+|-----------|------|--------|
+| Event schema mapping | `bridge/schema_map.py` | Implemented -- maps 15 Loki event types to OpenClaw `sessions_send` messages |
+| File watcher | `bridge/watcher.py` | Implemented -- polls `events/pending/` and `dashboard-state.json` |
+| CLI entry point | `bridge/__main__.py` | Implemented -- prints mapped events as JSON to stdout |
+
+### Running the bridge (stdout mode)
+
+```bash
+# From the project root where .loki/ exists
+python -m integrations.openclaw.bridge --loki-dir .loki
+
+# With custom poll interval
+python -m integrations.openclaw.bridge --loki-dir .loki --poll-interval 0.5
+
+# The --gateway flag is accepted but not yet functional
+python -m integrations.openclaw.bridge --loki-dir .loki --gateway ws://127.0.0.1:18789
+```
+
+Events are printed to stdout as JSON, one per line:
+```json
+{"method": "sessions_send", "params": {"message": "Loki Mode started. Provider: claude. PRD: my-app.md", "source": "loki-bridge", "event_type": "session.start", "timestamp": "2026-02-12T00:00:00Z", "loki_event_id": "a1b2c3d4"}}
+```
+
+### What is NOT yet implemented
+
+- **WebSocket gateway client** -- the `--gateway` flag is parsed but the actual WebSocket connection to OpenClaw is not built yet. Events go to stdout only.
+- **Reconnection logic** -- automatic reconnect on gateway disconnect.
+- **Event filtering** -- ability to select which event types to forward.
+- **Authentication** -- token-based auth for the OpenClaw gateway.
+- **Backpressure** -- buffering when the gateway is slow or unavailable.
+- **Async I/O** -- the watcher uses synchronous polling; a future version may use asyncio or inotify/kqueue for lower latency.
+- **Two-way communication** -- sending OpenClaw commands back to Loki (pause, stop, etc.).
+
+### Event schema mapping
+
+The bridge normalizes two Loki event formats into a canonical dot-notation key:
+
+1. **Individual JSON files** (`events/pending/*.json` from `events/emit.sh`): `type` + `payload.action` -> `"session.start"`
+2. **JSONL entries** (`events.jsonl` from `emit_event_json`): underscore-compound `type` -> `"session_start"` -> `"session.start"`
+
+Currently mapped event types: `session.start`, `session.stop`, `session.end`, `phase.change`, `iteration.start`, `iteration.complete`, `task.complete`, `error.failed`, `council.vote`, `council.verdict`, `budget.exceeded`, `budget.warning`, `code_review.start`, `code_review.complete`, `watchdog.alert`.
+
+---
+
+## Status JSON Schema
+
+The enriched JSON from `poll-status.sh` contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| status | string | inactive, running, paused, stopped, completed, unknown |
+| phase | string/null | BOOTSTRAP, DISCOVERY, ARCHITECTURE, DEVELOPMENT, QA, DEPLOYMENT |
+| iteration | number | Current iteration count |
+| tasks_completed | number | Tasks finished successfully |
+| tasks_total | number | Total tasks discovered |
+| tasks_failed | number | Tasks that errored |
+| tasks_pending | number | Tasks not yet started |
+| elapsed_minutes | number | Minutes since session start |
+| provider | string | Active AI provider |
+| version | string | Loki Mode version |
+| pid | number/null | Session process ID |
+| dashboard_url | string/null | Dashboard URL if running |
+| budget_used | number/null | USD spent so far |
+| budget_limit | number/null | USD budget cap |
+| council_verdict | string/null | Completion council decision |

package/integrations/openclaw/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: loki-mode
+description: "Launch Loki Mode autonomous SDLC agent. Handles PRD-to-deployment with minimal human intervention. Invoke for multi-phase development tasks, bug fixing campaigns, or full product builds."
+---
+
+# Loki Mode - OpenClaw Skill
+
+## When to use
+- User asks to "build", "implement", or "develop" a feature from a PRD
+- User provides a requirements document and wants autonomous execution
+- User says "loki mode" or references autonomous development
+- User wants to run a full SDLC cycle on a codebase
+
+## Prerequisites
+- `loki` CLI installed on the host (via `npm install -g loki-mode` or Homebrew)
+- One of: Claude Code, Codex CLI, or Gemini CLI installed
+- Corresponding API key set (ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY)
+
+## How to invoke
+
+### Start a session
+Use the bash tool with background mode:
+```
+bash(command: "loki start <prd-path> --bg --yes --no-dashboard", pty: true, background: true, workdir: "<project-dir>")
+```
+
+Key flags:
+- `--bg`: Background mode (session outlives the tool call)
+- `--yes`: Skip confirmation prompts
+- `--no-dashboard`: Avoid port conflicts in sandboxed environments
+- `--provider <claude|codex|gemini>`: Select AI provider (default: claude)
+- `--budget <amount>`: Set cost limit in USD (auto-pause when exceeded)
+
+### Monitor progress
+Poll status every 30 seconds:
+```
+bash(command: "loki status --json", workdir: "<project-dir>")
+```
+
+The JSON output contains:
+- `version`: Loki Mode version string
+- `status`: inactive, running, paused, stopped, completed, unknown
+- `phase`: Current SDLC phase (e.g., BOOTSTRAP, DISCOVERY, ARCHITECTURE, DEVELOPMENT, QA, DEPLOYMENT)
+- `iteration`: Current iteration number
+- `provider`: Which AI provider is active (claude, codex, gemini)
+- `pid`: Process ID of the running session (null if not running)
+- `elapsed_time`: Seconds since session start
+- `dashboard_url`: URL of the web dashboard (null if disabled)
+- `task_counts`: Object with `total`, `completed`, `failed`, `pending` counts
+
+For budget tracking (not in JSON output), read the budget file directly:
+```
+bash(command: "cat .loki/metrics/budget.json 2>/dev/null || echo '{}'", workdir: "<project-dir>")
+```
+Budget JSON fields: `budget_limit`, `budget_used`
+
+### Report progress to channel
+After each poll, summarize changes:
+- Phase transitions ("Moved from ARCHITECTURE to DEVELOPMENT")
+- Task completion counts ("12/20 tasks complete, 0 failed")
+- Elapsed time ("Running for 45 minutes")
+- Error states that need attention (failed tasks > 0, status is unknown)
+
+If budget tracking is active, include cost in updates:
+- "Estimated cost: $4.50 / $50.00 budget"
+
+### Control commands
+- Pause: `bash(command: "loki pause", workdir: "<project-dir>")`
+- Resume: `bash(command: "loki resume", workdir: "<project-dir>")`
+- Stop: `bash(command: "loki stop", workdir: "<project-dir>")`
+- Status: `bash(command: "loki status", workdir: "<project-dir>")`
+- Logs: `bash(command: "loki logs --tail 50", workdir: "<project-dir>")`
+
+### Session complete
+When status becomes "stopped" or "completed":
+1. Run `loki status --json` for final summary
+2. Run `git log --oneline -20` to show commits made
+3. Report final task counts, elapsed time, and duration
+4. If council verdict exists, include it: `cat .loki/council/report.md`
+
+## Critical rules
+- ALWAYS use --bg flag (session must outlive the tool call)
+- ALWAYS use --yes flag (no confirmation prompts in non-interactive channels)
+- NEVER run loki in the OpenClaw workspace directory itself
+- Poll status rather than watching stdout (background mode detaches)
+- If session crashes, check `loki logs` before restarting
+- Respect budget limits -- include cost in every progress update when tracking is active
+- The --no-dashboard flag is recommended to avoid port conflicts in sandboxed environments

package/integrations/openclaw/bridge/__init__.py

@@ -0,0 +1 @@
+# Loki-OpenClaw Bridge -- foundation package

package/integrations/openclaw/bridge/__main__.py

@@ -0,0 +1,88 @@
+"""Loki-OpenClaw Bridge Daemon entry point.
+
+Usage:
+    python -m integrations.openclaw.bridge --loki-dir .loki
+    python -m integrations.openclaw.bridge --loki-dir .loki --gateway ws://127.0.0.1:18789
+
+NOTE: This is a foundation/skeleton. The WebSocket gateway client is not yet
+implemented. Currently logs mapped events to stdout as JSON for testing.
+The --gateway flag is accepted but has no effect until the WebSocket client
+is built in a future phase.
+"""
+
+import argparse
+import json
+import signal
+import sys
+
+from .schema_map import map_event
+from .watcher import LokiFileWatcher
+
+
+def _on_event(event: dict) -> None:
+    """Handle a raw Loki event: map it and print as JSON to stdout."""
+    mapped = map_event(event)
+    if mapped is not None:
+        try:
+            print(json.dumps(mapped), flush=True)
+        except (TypeError, ValueError):
+            pass
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="loki-openclaw-bridge",
+        description="Watch Loki Mode events and translate to OpenClaw gateway format.",
+    )
+    parser.add_argument(
+        "--loki-dir",
+        required=True,
+        help="Path to the .loki directory to watch.",
+    )
+    parser.add_argument(
+        "--gateway",
+        default=None,
+        help=(
+            "WebSocket URL for the OpenClaw gateway (e.g. ws://127.0.0.1:18789). "
+            "Not yet implemented -- events are printed to stdout regardless."
+        ),
+    )
+    parser.add_argument(
+        "--poll-interval",
+        type=float,
+        default=1.0,
+        help="Seconds between directory polls (default: 1.0).",
+    )
+    args = parser.parse_args()
+
+    if args.gateway:
+        print(
+            f"[bridge] --gateway {args.gateway} accepted but WebSocket client "
+            "is not yet implemented. Events will be printed to stdout.",
+            file=sys.stderr,
+        )
+
+    watcher = LokiFileWatcher(
+        loki_dir=args.loki_dir,
+        on_event=_on_event,
+        poll_interval=args.poll_interval,
+    )
+
+    # Graceful shutdown on Ctrl+C and SIGTERM
+    def _shutdown(signum, frame):
+        print("\n[bridge] Shutting down.", file=sys.stderr)
+        watcher.stop()
+
+    signal.signal(signal.SIGINT, _shutdown)
+    signal.signal(signal.SIGTERM, _shutdown)
+
+    print(
+        f"[bridge] Watching {args.loki_dir} (poll every {args.poll_interval}s). "
+        "Press Ctrl+C to stop.",
+        file=sys.stderr,
+    )
+    watcher.start()
+
+
+if __name__ == "__main__":
+    main()