@misterhuydo/sentinel 1.0.12 → 1.0.14

package/.cairn/.hint-lock

@@ -1 +1 @@
-2026-03-21T17:01:47.015Z
+2026-03-21T17:34:17.867Z

package/.cairn/session.json

@@ -1,6 +1,6 @@
 {
-  "message": "Auto-checkpoint at 2026-03-21T17:02:51.501Z",
-  "checkpoint_at": "2026-03-21T17:02:51.502Z",
+  "message": "Auto-checkpoint at 2026-03-21T17:25:46.348Z",
+  "checkpoint_at": "2026-03-21T17:25:46.349Z",
   "active_files": [],
   "notes": [],
   "mtime_snapshot": {}

package/package.json

@@ -1,21 +1,21 @@
-{
-  "name": "@misterhuydo/sentinel",
-  "version": "1.0.12",
-  "description": "Sentinel — Autonomous DevOps Agent installer and manager",
-  "bin": {
-    "sentinel": "./bin/sentinel.js"
-  },
-  "scripts": {
-    "prepublishOnly": "node scripts/bundle.js"
-  },
-  "dependencies": {
-    "chalk": "^4.1.2",
-    "fs-extra": "^11.2.0",
-    "prompts": "^2.4.2"
-  },
-  "engines": {
-    "node": ">=16"
-  },
-  "author": "misterhuydo",
-  "license": "MIT"
-}
+{
+  "name": "@misterhuydo/sentinel",
+  "version": "1.0.14",
+  "description": "Sentinel — Autonomous DevOps Agent installer and manager",
+  "bin": {
+    "sentinel": "./bin/sentinel.js"
+  },
+  "scripts": {
+    "prepublishOnly": "node scripts/bundle.js"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "fs-extra": "^11.2.0",
+    "prompts": "^2.4.2"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "author": "misterhuydo",
+  "license": "MIT"
+}

package/python/requirements.txt

@@ -3,3 +3,5 @@ schedule>=1.2
 python-dotenv>=1.0
 requests>=2.31
 jinja2>=3.1
+anthropic>=0.27
+slack-bolt>=1.18

package/python/sentinel/config_loader.py

@@ -51,7 +51,13 @@ class SentinelConfig:
     fix_confidence_threshold: float = 0.7
     log_retention_hours: int = 48
     anthropic_api_key: str = ""
-    marker_confirm_hours: int = 24  # quiet period before confirming a fix
+    marker_confirm_hours: int = 24   # quiet period before confirming a fix
+    config_poll_interval: int = 60   # seconds between config repo git pulls
+    auto_upgrade: bool = True        # auto-upgrade on new patch versions
+    version_pin: str = ""            # if set, never upgrade beyond this version
+    upgrade_check_hours: int = 6     # hours between npm upgrade checks
+    slack_bot_token: str = ""        # xoxb-...
+    slack_app_token: str = ""        # xapp-... (Socket Mode)
 
 
 @dataclass
@@ -137,6 +143,12 @@ class ConfigLoader:
         c.log_retention_hours = int(d.get("LOG_RETENTION_HOURS", 48))
         c.anthropic_api_key = d.get("ANTHROPIC_API_KEY", "")
         c.marker_confirm_hours = int(d.get("MARKER_CONFIRM_HOURS", 24))
+        c.config_poll_interval = int(d.get("CONFIG_POLL_INTERVAL", 60))
+        c.auto_upgrade = d.get("AUTO_UPGRADE", "true").lower() != "false"
+        c.version_pin = d.get("VERSION_PIN", "")
+        c.upgrade_check_hours = int(d.get("UPGRADE_CHECK_HOURS", 6))
+        c.slack_bot_token = d.get("SLACK_BOT_TOKEN", "")
+        c.slack_app_token = d.get("SLACK_APP_TOKEN", "")
         self.sentinel = c
 
     def _load_log_sources(self):

package/python/sentinel/main.py

@@ -8,7 +8,10 @@ Usage:
 
 import argparse
 import asyncio
+import json
 import logging
+import os
+import shutil
 import signal
 import subprocess
 import sys
@@ -24,7 +27,7 @@ from .log_fetcher import fetch_all
 from .log_parser import parse_all, scan_all_for_markers, ErrorEvent
 from .issue_watcher import scan_issues, mark_done, IssueEvent
 from .repo_router import route
-from .reporter import build_and_send, send_fix_notification, send_failure_notification, send_confirmed_notification, send_regression_notification, send_startup_notification
+from .reporter import build_and_send, send_fix_notification, send_failure_notification, send_confirmed_notification, send_regression_notification, send_startup_notification, send_upgrade_notification
 from .state_store import StateStore
 
 logging.basicConfig(
@@ -383,6 +386,160 @@ async def _send_startup_email_delayed(cfg, results: dict, delay: int = 300):
         logger.error("Failed to send startup notification: %s", e)
 
 
+# ── Config repo polling ──────────────────────────────────────────────────────────────────────────
+
+def _poll_config_repo(cfg_loader: ConfigLoader) -> bool:
+    """git pull the project directory if it is a git repo. Returns True if changes were pulled."""
+    project_dir = Path(".")
+    git_dir = project_dir / ".git"
+    if not git_dir.exists():
+        return False
+    try:
+        result = subprocess.run(
+            ["git", "pull", "--rebase", "--autostash"],
+            cwd=str(project_dir),
+            capture_output=True, text=True, timeout=30,
+        )
+        if result.returncode != 0:
+            logger.warning("Config repo git pull failed: %s", result.stderr.strip())
+            return False
+        changed = "Already up to date." not in result.stdout
+        if changed:
+            logger.info("Config repo updated — reloading config\n%s", result.stdout.strip())
+            cfg_loader.load()
+        return changed
+    except Exception as e:
+        logger.warning("Config repo poll error: %s", e)
+        return False
+
+
+async def _config_poll_loop(cfg_loader: ConfigLoader):
+    """Background task: poll config repo for changes every config_poll_interval seconds."""
+    while True:
+        interval = cfg_loader.sentinel.config_poll_interval
+        await asyncio.sleep(interval)
+        try:
+            _poll_config_repo(cfg_loader)
+        except Exception as e:
+            logger.warning("Config poll loop error: %s", e)
+
+
+# ── Auto-upgrade ─────────────────────────────────────────────────────────────────────────────────
+
+def _find_sentinel_code_dir() -> Path | None:
+    """Locate the sentinel/code dir relative to the project working directory."""
+    # Project dir is cwd; code dir is at ../code or ../../code depending on layout
+    for candidate in [
+        Path("../code"),
+        Path("../../code"),
+        Path.home() / "sentinel" / "code",
+    ]:
+        if candidate.exists() and (candidate / "sentinel").exists():
+            return candidate.resolve()
+    return None
+
+
+def _parse_version(v: str) -> tuple:
+    try:
+        return tuple(int(x) for x in v.strip().lstrip("v").split(".")[:3])
+    except Exception:
+        return (0, 0, 0)
+
+
+def _check_and_upgrade(cfg: SentinelConfig) -> bool:
+    """
+    Check npm registry for a newer patch/minor version of @misterhuydo/sentinel.
+    If found (and not blocked by VERSION_PIN), install it, copy Python source to
+    the code dir, then restart via os.execv.
+    Returns True if an upgrade was initiated (process will restart).
+    """
+    try:
+        result = subprocess.run(
+            ["npm", "show", "@misterhuydo/sentinel", "version"],
+            capture_output=True, text=True, timeout=30,
+        )
+        if result.returncode != 0:
+            logger.warning("npm show failed: %s", result.stderr.strip())
+            return False
+        latest = result.stdout.strip()
+    except Exception as e:
+        logger.warning("Upgrade check failed: %s", e)
+        return False
+
+    # Determine current version from package installed globally
+    try:
+        cur_result = subprocess.run(
+            ["npm", "list", "-g", "--depth=0", "--json"],
+            capture_output=True, text=True, timeout=30,
+        )
+        pkg_data = json.loads(cur_result.stdout or "{}")
+        deps = pkg_data.get("dependencies", {})
+        current = deps.get("@misterhuydo/sentinel", {}).get("version", "0.0.0")
+    except Exception:
+        current = "0.0.0"
+
+    current_t = _parse_version(current)
+    latest_t  = _parse_version(latest)
+
+    if cfg.version_pin:
+        pin_t = _parse_version(cfg.version_pin)
+        if latest_t > pin_t:
+            logger.info("Upgrade available (%s → %s) but pinned to %s — skipping",
+                        current, latest, cfg.version_pin)
+            return False
+
+    if latest_t <= current_t:
+        logger.debug("No upgrade available (current=%s, latest=%s)", current, latest)
+        return False
+
+    logger.info("Upgrading @misterhuydo/sentinel %s → %s", current, latest)
+    install = subprocess.run(
+        ["npm", "install", "-g", f"@misterhuydo/sentinel@{latest}"],
+        capture_output=True, text=True, timeout=120,
+    )
+    if install.returncode != 0:
+        logger.error("npm install failed: %s", install.stderr.strip())
+        return False
+
+    # Copy updated Python source from newly installed npm package to code dir
+    code_dir = _find_sentinel_code_dir()
+    if code_dir:
+        try:
+            npm_prefix_result = subprocess.run(
+                ["npm", "root", "-g"], capture_output=True, text=True, timeout=10,
+            )
+            npm_root = npm_prefix_result.stdout.strip()
+            new_src = Path(npm_root) / "@misterhuydo" / "sentinel" / "sentinel"
+            if new_src.exists():
+                dst = code_dir / "sentinel"
+                shutil.copytree(str(new_src), str(dst), dirs_exist_ok=True)
+                logger.info("Python source updated at %s", dst)
+        except Exception as e:
+            logger.warning("Failed to copy updated Python source: %s", e)
+
+    logger.info("Upgrade complete — restarting Sentinel")
+    try:
+        from .reporter import send_upgrade_notification
+        send_upgrade_notification(cfg, current, latest)
+    except Exception:
+        pass
+
+    os.execv(sys.executable, [sys.executable] + sys.argv)
+    return True  # unreachable after execv
+
+
+async def _upgrade_check_loop(cfg_loader: ConfigLoader):
+    """Background task: check for upgrades every upgrade_check_hours hours."""
+    # Wait one full interval before first check so startup isn't slowed
+    await asyncio.sleep(cfg_loader.sentinel.upgrade_check_hours * 3600)
+    while True:
+        try:
+            _check_and_upgrade(cfg_loader.sentinel)
+        except Exception as e:
+            logger.warning("Upgrade check loop error: %s", e)
+        await asyncio.sleep(cfg_loader.sentinel.upgrade_check_hours * 3600)
+
+
 # ── Entry point ──────────────────────────────────────────────────────────────────────────────────
 
 async def run_loop(cfg_loader: ConfigLoader, store: StateStore):
@@ -403,6 +560,12 @@ async def run_loop(cfg_loader: ConfigLoader, store: StateStore):
         logger.info("Startup checks passed — startup email in 5 minutes")
 
     asyncio.ensure_future(_send_startup_email_delayed(cfg_loader.sentinel, results))
+    asyncio.ensure_future(_config_poll_loop(cfg_loader))
+    if cfg_loader.sentinel.auto_upgrade:
+        asyncio.ensure_future(_upgrade_check_loop(cfg_loader))
+    if cfg_loader.sentinel.slack_bot_token:
+        from .slack_bot import run_slack_bot
+        asyncio.ensure_future(run_slack_bot(cfg_loader, store))
 
     while True:
         try:

package/python/sentinel/reporter.py

@@ -345,3 +345,32 @@ def send_startup_notification(cfg: SentinelConfig, results: dict):
     subject = f'[Sentinel] {status_label} — {ts}'
     _send_email(cfg, subject, html)
     logger.info('Startup notification sent to %d recipient(s)', len(cfg.mails))
+
+
+def send_upgrade_notification(cfg: SentinelConfig, old_version: str, new_version: str):
+    if not cfg.mails:
+        return
+    ts = datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')
+    subject = f'[Sentinel] Upgraded {old_version} → {new_version}'
+    html = (
+        '<!DOCTYPE html><html><head><meta charset="utf-8">'
+        '<style>'
+        'body{font-family:Arial,sans-serif;font-size:14px;color:#222}'
+        'h2{color:#1a73e8}'
+        'table{border-collapse:collapse;width:100%;margin-bottom:16px}'
+        'td{padding:5px 10px;border-bottom:1px solid #eee}'
+        '.label{font-weight:bold;width:160px}'
+        '.mono{font-family:monospace;font-size:12px}'
+        '</style></head><body>'
+        '<h2>Sentinel auto-upgraded and restarted</h2>'
+        f'<p>{ts}</p>'
+        '<table>'
+        f'<tr><td class="label">Previous version</td><td class="mono">{old_version}</td></tr>'
+        f'<tr><td class="label">New version</td><td class="mono">{new_version}</td></tr>'
+        '</table>'
+        '<p>Sentinel has restarted automatically with the new version. No action required.</p>'
+        '<hr><small>Sentinel &mdash; Autonomous DevOps Agent</small>'
+        '</body></html>'
+    )
+    _send_email(cfg, subject, html)
+    logger.info('Upgrade notification sent: %s → %s', old_version, new_version)

package/python/sentinel/sentinel_boss.py

@@ -0,0 +1,297 @@
+"""
+sentinel_boss.py — Claude-backed Sentinel Boss.
+
+Claude acts as the boss: reads project state, decides on actions,
+executes them via tool use, and responds naturally. One agentic loop
+per turn — Claude may call multiple tools before replying.
+"""
+
+import json
+import logging
+import os
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# ── System prompt ────────────────────────────────────────────────────────────
+
+_SYSTEM = """\
+You are Sentinel Boss — the AI interface for Sentinel, a 24/7 autonomous DevOps agent.
+
+Sentinel watches production logs, detects errors, generates code fixes via Claude Code,
+and opens GitHub PRs for admin review (or pushes directly if AUTO_PUBLISH=true).
+
+Your job:
+- Understand what the DevOps engineer needs in natural language
+- Query Sentinel's live state (errors, fixes, open PRs) on their behalf
+- Create issue reports when asked to investigate or fix something
+- Control Sentinel (pause/resume) when asked
+- Give honest, concise answers — you know this system inside out
+
+Tone: direct, professional, like a senior engineer who owns the system.
+Don't pad responses. Don't say "Great question!" or "Certainly!".
+If you don't know something, use a tool to find out before saying you don't know.
+
+When the engineer's request is fully handled, end your LAST message with the token: [DONE]
+If you need a follow-up from them, do NOT include [DONE] — wait for their next message.
+"""
+
+# ── Tool definitions ─────────────────────────────────────────────────────────
+
+_TOOLS = [
+    {
+        "name": "get_status",
+        "description": (
+            "Get recent errors, fixes applied, fixes pending review, and open PRs. "
+            "Use for: 'what happened today?', 'any issues?', 'how are things?', "
+            "'what are the open PRs?', 'did sentinel fix anything?'"
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "hours": {
+                    "type": "integer",
+                    "description": "Look-back window in hours (default 24)",
+                    "default": 24,
+                },
+            },
+        },
+    },
+    {
+        "name": "create_issue",
+        "description": (
+            "Queue a fix request for Sentinel to investigate on the next poll cycle. "
+            "Use whenever the engineer reports a bug, customer complaint, or asks you "
+            "to look into something specific. Include every detail they gave you."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "description": "Full problem description — everything the engineer told you",
+                },
+                "target_repo": {
+                    "type": "string",
+                    "description": "Repo name to assign to (omit to let Sentinel auto-route)",
+                },
+            },
+            "required": ["description"],
+        },
+    },
+    {
+        "name": "get_fix_details",
+        "description": "Get full details of a specific fix by fingerprint (8+ hex chars).",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "fingerprint": {"type": "string"},
+            },
+            "required": ["fingerprint"],
+        },
+    },
+    {
+        "name": "list_pending_prs",
+        "description": "List all open Sentinel PRs awaiting admin review.",
+        "input_schema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "pause_sentinel",
+        "description": (
+            "Pause ALL Sentinel fix activity immediately. "
+            "Use when the engineer says 'pause', 'stop', 'freeze', or 'hold off'."
+        ),
+        "input_schema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "resume_sentinel",
+        "description": "Resume Sentinel fix activity after a pause.",
+        "input_schema": {"type": "object", "properties": {}},
+    },
+]
+
+
+# ── Tool execution ────────────────────────────────────────────────────────────
+
+def _run_tool(name: str, inputs: dict, cfg_loader, store) -> str:
+    if name == "get_status":
+        hours = int(inputs.get("hours", 24))
+        errors = store.get_recent_errors(hours)
+        fixes  = store.get_recent_fixes(hours)
+        prs    = store.get_open_prs()
+        top_errors = [
+            {
+                "message": e["message"][:120],
+                "count":   e["count"],
+                "source":  e["source"],
+                "last_seen": e["last_seen"],
+            }
+            for e in errors[:8]
+        ]
+        return json.dumps({
+            "window_hours":    hours,
+            "errors_detected": len(errors),
+            "top_errors":      top_errors,
+            "fixes_applied":   sum(1 for f in fixes if f["status"] == "applied"),
+            "fixes_pending":   sum(1 for f in fixes if f["status"] == "pending"),
+            "fixes_failed":    sum(1 for f in fixes if f["status"] == "failed"),
+            "open_prs":        [
+                {
+                    "repo":   p["repo_name"],
+                    "branch": p["branch"],
+                    "pr_url": p["pr_url"],
+                    "age":    p.get("timestamp", ""),
+                }
+                for p in prs
+            ],
+            "sentinel_paused": Path("SENTINEL_PAUSE").exists(),
+        })
+
+    if name == "create_issue":
+        description = inputs["description"]
+        target_repo = inputs.get("target_repo", "")
+        issues_dir  = Path("issues")
+        issues_dir.mkdir(exist_ok=True)
+        fname   = f"slack-{uuid.uuid4().hex[:8]}.txt"
+        content = (f"TARGET_REPO: {target_repo}\n\n" if target_repo else "") + description
+        (issues_dir / fname).write_text(content, encoding="utf-8")
+        logger.info("Boss created issue: %s", fname)
+        return json.dumps({
+            "status": "queued",
+            "file":   fname,
+            "note":   "Sentinel will pick this up on the next poll cycle.",
+        })
+
+    if name == "get_fix_details":
+        fp  = inputs["fingerprint"]
+        fix = store.get_confirmed_fix(fp) or store.get_marker_seen_fix(fp)
+        if not fix:
+            # Fallback: search recent fixes by prefix
+            recent = store.get_recent_fixes(hours=72)
+            fix    = next((f for f in recent if f.get("fingerprint", "").startswith(fp)), None)
+        return json.dumps(fix or {"error": "not found"})
+
+    if name == "list_pending_prs":
+        prs = store.get_open_prs()
+        return json.dumps({
+            "count":    len(prs),
+            "open_prs": [
+                {
+                    "repo":      p["repo_name"],
+                    "branch":    p["branch"],
+                    "pr_url":    p["pr_url"],
+                    "timestamp": p.get("timestamp", ""),
+                }
+                for p in prs
+            ],
+        })
+
+    if name == "pause_sentinel":
+        Path("SENTINEL_PAUSE").touch()
+        logger.info("Boss: SENTINEL_PAUSE created")
+        return json.dumps({"status": "paused"})
+
+    if name == "resume_sentinel":
+        p = Path("SENTINEL_PAUSE")
+        if p.exists():
+            p.unlink()
+        logger.info("Boss: SENTINEL_PAUSE removed")
+        return json.dumps({"status": "resumed"})
+
+    return json.dumps({"error": f"unknown tool: {name}"})
+
+
+# ── Main entry point ──────────────────────────────────────────────────────────
+
+async def handle_message(
+    message: str,
+    history: list,
+    cfg_loader,
+    store,
+) -> tuple[str, bool]:
+    """
+    Process one user message through the Sentinel Boss (Claude with tool use).
+
+    Args:
+        message:     The user's Slack message text.
+        history:     Conversation history list — mutated in place (role/content dicts).
+        cfg_loader:  ConfigLoader for repo/sentinel config.
+        store:       StateStore for DB queries.
+
+    Returns:
+        (reply_text, is_done)
+        is_done=True  → session complete, release the Slack queue slot.
+        is_done=False → waiting for user follow-up, keep the slot.
+    """
+    try:
+        import anthropic
+    except ImportError:
+        return (
+            ":warning: `anthropic` package not installed. Run: `pip install anthropic`",
+            True,
+        )
+
+    api_key = cfg_loader.sentinel.anthropic_api_key or os.environ.get("ANTHROPIC_API_KEY", "")
+    if not api_key:
+        return (
+            ":warning: `ANTHROPIC_API_KEY` not configured in `sentinel.properties`.",
+            True,
+        )
+
+    client = anthropic.Anthropic(api_key=api_key)
+
+    # Build system context snapshot
+    paused    = Path("SENTINEL_PAUSE").exists()
+    repos     = list(cfg_loader.repos.keys())
+    ts        = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    system    = (
+        _SYSTEM
+        + f"\n\nCurrent time: {ts}"
+        + f"\nSentinel status: {'⏸ PAUSED' if paused else '▶ RUNNING'}"
+        + f"\nManaged repos: {', '.join(repos) if repos else '(none configured)'}"
+    )
+
+    history.append({"role": "user", "content": message})
+    messages = list(history)
+
+    # Agentic loop — Claude may call multiple tools before giving a final reply
+    while True:
+        response = client.messages.create(
+            model="claude-opus-4-6",
+            max_tokens=1024,
+            system=system,
+            tools=_TOOLS,
+            messages=messages,
+        )
+
+        text_parts  = []
+        tool_blocks = []
+        for block in response.content:
+            if block.type == "text":
+                text_parts.append(block.text)
+            elif block.type == "tool_use":
+                tool_blocks.append(block)
+
+        if not tool_blocks:
+            # Final response — no more tool calls
+            reply   = " ".join(text_parts).strip()
+            is_done = "[DONE]" in reply
+            reply   = reply.replace("[DONE]", "").strip()
+            history.append({"role": "assistant", "content": response.content})
+            return reply, is_done
+
+        # Execute tools and continue
+        messages.append({"role": "assistant", "content": response.content})
+        tool_results = []
+        for tc in tool_blocks:
+            result = _run_tool(tc.name, tc.input, cfg_loader, store)
+            logger.info("Boss tool: %s(%s) → %s", tc.name, tc.input, result[:120])
+            tool_results.append({
+                "type":        "tool_result",
+                "tool_use_id": tc.id,
+                "content":     result,
+            })
+        messages.append({"role": "user", "content": tool_results})

package/python/sentinel/slack_bot.py

@@ -0,0 +1,228 @@
+"""
+slack_bot.py — Slack integration for Sentinel Boss.
+
+One DevOps member is handled at a time per Sentinel instance.
+Others are queued and notified of their position. When the current
+session finishes, the next person is picked up automatically.
+
+Setup (api.slack.com):
+  1. Create a Slack App → Enable Socket Mode → copy App-Level Token (xapp-...)
+  2. Add Bot Token Scopes: app_mentions:read, chat:write, im:history,
+     channels:history, users:read
+  3. Enable Events: app_mention, message.im, message.channels
+  4. Install to workspace → copy Bot Token (xoxb-...)
+  5. Add to sentinel.properties:
+       SLACK_BOT_TOKEN=xoxb-...
+       SLACK_APP_TOKEN=xapp-...
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .sentinel_boss import handle_message
+
+logger = logging.getLogger(__name__)
+
+
+# ── Session and Queue ─────────────────────────────────────────────────────────
+
+@dataclass
+class _Session:
+    user_id:   str
+    user_name: str
+    channel:   str
+    history:   list = field(default_factory=list)
+
+
+class _Queue:
+    """
+    Global sequential queue for a Sentinel instance.
+    One member at a time; others wait.
+    """
+
+    def __init__(self):
+        self._lock:    asyncio.Lock          = asyncio.Lock()
+        self._active:  Optional[_Session]    = None
+        self._waiting: list[tuple[_Session, str]] = []   # (session, first_message)
+
+    async def try_activate(
+        self, user_id: str, user_name: str, channel: str
+    ) -> tuple[str, int, Optional[_Session]]:
+        """
+        Returns:
+          ('active',     0,   session)  — slot is free, session started
+          ('continuing', 0,   session)  — same user already has the slot
+          ('queued',     pos, None)     — added to wait queue at position pos
+        """
+        async with self._lock:
+            if self._active is None:
+                self._active = _Session(user_id, user_name, channel)
+                return "active", 0, self._active
+
+            if self._active.user_id == user_id:
+                return "continuing", 0, self._active
+
+            # Deduplicate — don't queue the same user twice
+            if not any(s.user_id == user_id for s, _ in self._waiting):
+                self._waiting.append((_Session(user_id, user_name, channel), ""))
+
+            pos = next(
+                i + 1
+                for i, (s, _) in enumerate(self._waiting)
+                if s.user_id == user_id
+            )
+            return "queued", pos, None
+
+    async def update_waiting_message(self, user_id: str, message: str):
+        """Overwrite the first message for a queued user (they may rephrase while waiting)."""
+        async with self._lock:
+            for i, (s, _) in enumerate(self._waiting):
+                if s.user_id == user_id:
+                    self._waiting[i] = (s, message)
+                    return
+
+    async def complete(self) -> Optional[tuple[_Session, str]]:
+        """Release the active slot. Returns (next_session, first_message) or None."""
+        async with self._lock:
+            prev = self._active
+            self._active = None
+            if self._waiting:
+                session, msg = self._waiting.pop(0)
+                self._active = session
+                return session, msg
+            return None
+
+    def active_user_name(self) -> Optional[str]:
+        return self._active.user_name if self._active else None
+
+
+_queue = _Queue()
+
+
+# ── Slack bot ─────────────────────────────────────────────────────────────────
+
+async def run_slack_bot(cfg_loader, store) -> None:
+    """
+    Start Slack Bolt in Socket Mode as an asyncio background task.
+    Exits silently if tokens are missing or slack-bolt is not installed.
+    """
+    try:
+        from slack_bolt.async_app import AsyncApp
+        from slack_bolt.adapter.socket_mode.async_handler import AsyncSocketModeHandler
+    except ImportError:
+        logger.warning(
+            "slack-bolt not installed — Slack bot disabled. "
+            "Run: pip install slack-bolt"
+        )
+        return
+
+    cfg = cfg_loader.sentinel
+    if not cfg.slack_bot_token or not cfg.slack_app_token:
+        logger.info("SLACK_BOT_TOKEN / SLACK_APP_TOKEN not set — Slack bot disabled")
+        return
+
+    app = AsyncApp(token=cfg.slack_bot_token)
+
+    # ── Event handlers ────────────────────────────────────────────────────────
+
+    @app.event("app_mention")
+    async def on_mention(event, client):
+        await _dispatch(event, client, cfg_loader, store)
+
+    @app.event("message")
+    async def on_message(event, client):
+        # Handle DMs only (channel_type == "im"); ignore bot messages
+        if event.get("channel_type") == "im" and not event.get("bot_id"):
+            await _dispatch(event, client, cfg_loader, store)
+
+    # ── Start ─────────────────────────────────────────────────────────────────
+
+    handler = AsyncSocketModeHandler(app, cfg.slack_app_token)
+    logger.info("Sentinel Boss connected to Slack (Socket Mode)")
+    await handler.start_async()
+
+
+# ── Dispatcher ────────────────────────────────────────────────────────────────
+
+async def _dispatch(event: dict, client, cfg_loader, store) -> None:
+    user_id = event.get("user", "")
+    channel = event.get("channel", "")
+    text    = _strip_mention(event.get("text", "")).strip()
+
+    if not text:
+        return
+
+    user_name = await _resolve_name(client, user_id)
+
+    status, pos, session = await _queue.try_activate(user_id, user_name, channel)
+
+    if status == "queued":
+        await _queue.update_waiting_message(user_id, text)
+        active = _queue.active_user_name() or "someone"
+        await _post(client, channel,
+            f"I'm working with *{active}* right now. "
+            f"You're *#{pos}* in the queue — I'll come to you when done. :hourglass_flowing_sand:"
+        )
+        return
+
+    # Active or continuing — process the turn
+    await _run_turn(session, text, client, cfg_loader, store)
+
+
+# ── Turn processor ────────────────────────────────────────────────────────────
+
+async def _run_turn(session: _Session, message: str, client, cfg_loader, store) -> None:
+    channel = session.channel
+
+    # Typing indicator
+    await _post(client, channel, "_thinking..._")
+
+    try:
+        reply, is_done = await handle_message(
+            message, session.history, cfg_loader, store
+        )
+    except Exception as e:
+        logger.exception("Sentinel Boss error: %s", e)
+        await _post(client, channel, f":warning: Unhandled error: {e}")
+        is_done = True
+
+    await _post(client, channel, reply)
+
+    if is_done:
+        next_item = await _queue.complete()
+        if next_item:
+            next_session, first_msg = next_item
+            await _post(
+                client, channel,
+                f":white_check_mark: Done with *{session.user_name}*. "
+                f"<@{next_session.user_id}> — you're up!"
+            )
+            if first_msg:
+                # Process their first message immediately
+                await _run_turn(next_session, first_msg, client, cfg_loader, store)
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+async def _post(client, channel: str, text: str) -> None:
+    try:
+        await client.chat_postMessage(channel=channel, text=text)
+    except Exception as e:
+        logger.warning("Slack post failed: %s", e)
+
+
+async def _resolve_name(client, user_id: str) -> str:
+    try:
+        info = await client.users_info(user=user_id)
+        profile = info["user"]["profile"]
+        return profile.get("display_name") or profile.get("real_name") or user_id
+    except Exception:
+        return user_id
+
+
+def _strip_mention(text: str) -> str:
+    """Remove leading <@BOTID> mention from message text."""
+    import re
+    return re.sub(r"^<@[A-Z0-9]+>\s*", "", text)

package/templates/sentinel.properties

@@ -18,3 +18,10 @@ WORKSPACE_DIR=./workspace
 
 # Claude Code auth — set if using API key, leave blank for OAuth
 # ANTHROPIC_API_KEY=sk-ant-...
+
+# Slack Bot (optional) — Sentinel Boss conversational interface
+# Create a Slack App at api.slack.com, enable Socket Mode, add scopes:
+#   app_mentions:read, chat:write, im:history, channels:history, users:read
+# Then install to workspace and paste both tokens here.
+# SLACK_BOT_TOKEN=xoxb-...
+# SLACK_APP_TOKEN=xapp-...

package/templates/workspace-sentinel.properties

@@ -18,3 +18,11 @@ LOG_RETENTION_HOURS=48
 
 # Claude Code binary path
 CLAUDE_CODE_BIN=claude
+
+# Auto-upgrade: check npm for a newer @misterhuydo/sentinel every N hours and restart
+AUTO_UPGRADE=true
+UPGRADE_CHECK_HOURS=6
+# VERSION_PIN=1.0.12   # uncomment to prevent upgrades past this version
+
+# Config repo polling: if the project dir is a git repo, pull for config changes every N seconds
+CONFIG_POLL_INTERVAL=60