@misterhuydo/sentinel 1.0.13 → 1.0.15

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:16:10.950Z",
-  "checkpoint_at": "2026-03-21T17:16:10.951Z",
+  "message": "Auto-checkpoint at 2026-03-21T17:41:53.418Z",
+  "checkpoint_at": "2026-03-21T17:41:53.419Z",
   "active_files": [],
   "notes": [],
   "mtime_snapshot": {}

package/lib/generate.js

@@ -5,18 +5,24 @@ const path = require('path');
 
 // ── Per-project files ─────────────────────────────────────────────────────────
 
-function writeExampleProject(projectDir, codeDir, pythonBin, anthropicKey = '') {
+function writeExampleProject(projectDir, codeDir, pythonBin, anthropicKey = '', slackTokens = {}) {
   const configDir = path.join(projectDir, 'config', 'log-configs');
   const repoDir   = path.join(projectDir, 'config', 'repo-configs');
   fs.ensureDirSync(configDir);
   fs.ensureDirSync(repoDir);
 
   const tplDir = path.join(__dirname, '..', 'templates');
-  // Per-project sentinel.properties: MAILS, GITHUB_TOKEN, optional API key
+  // Per-project sentinel.properties: MAILS, GITHUB_TOKEN, optional API key, optional Slack
   let sentinelProps = fs.readFileSync(path.join(tplDir, 'sentinel.properties'), 'utf8');
   if (anthropicKey) {
     sentinelProps = sentinelProps.replace(/^# ANTHROPIC_API_KEY=.*/m, `ANTHROPIC_API_KEY=${anthropicKey}`);
   }
+  if (slackTokens.botToken) {
+    sentinelProps = sentinelProps.replace(/^# SLACK_BOT_TOKEN=.*/m, `SLACK_BOT_TOKEN=${slackTokens.botToken}`);
+  }
+  if (slackTokens.appToken) {
+    sentinelProps = sentinelProps.replace(/^# SLACK_APP_TOKEN=.*/m, `SLACK_APP_TOKEN=${slackTokens.appToken}`);
+  }
   fs.writeFileSync(path.join(projectDir, 'config', 'sentinel.properties'), sentinelProps);
   fs.copySync(path.join(tplDir, 'log-configs', '_example.properties'), path.join(configDir, '_example.properties'));
   fs.copySync(path.join(tplDir, 'repo-configs', '_example.properties'), path.join(repoDir,   '_example.properties'));

package/lib/init.js

@@ -68,9 +68,27 @@ module.exports = async function init() {
       message: 'SMTP host',
       initial: 'smtp.gmail.com',
     },
+    {
+      type: 'confirm',
+      name: 'setupSlack',
+      message: 'Set up Slack Bot (Sentinel Boss — conversational AI interface)?',
+      initial: false,
+    },
+    {
+      type: prev => prev ? 'password' : null,
+      name: 'slackBotToken',
+      message: 'Slack Bot Token  (xoxb-...)',
+      validate: v => v.startsWith('xoxb-') ? true : 'Should start with xoxb-',
+    },
+    {
+      type: (_, { slackBotToken }) => slackBotToken ? 'password' : null,
+      name: 'slackAppToken',
+      message: 'Slack App-Level Token  (xapp-...)',
+      validate: v => v.startsWith('xapp-') ? true : 'Should start with xapp-',
+    },
   ], { onCancel: () => process.exit(0) });
 
-  const { workspace, authMode, anthropicKey, example, systemd, smtpUser, smtpPassword, smtpHost } = answers;
+  const { workspace, authMode, anthropicKey, example, systemd, smtpUser, smtpPassword, smtpHost, setupSlack, slackBotToken, slackAppToken } = answers;
   const codeDir = path.join(workspace, 'code');
 
   // ── Python ──────────────────────────────────────────────────────────────────
@@ -123,6 +141,15 @@ module.exports = async function init() {
     info('Skipping auth — start.sh will prompt for login if needed');
   }
 
+  // ── Slack Bot ────────────────────────────────────────────────────────────────
+  if (slackBotToken && slackAppToken) {
+    step('Slack Bot (Sentinel Boss)…');
+    ok('Tokens will be written to the project sentinel.properties');
+    info('Sentinel Boss starts automatically when the project starts');
+  } else if (setupSlack) {
+    warn('Slack tokens not provided — add them to config/sentinel.properties later');
+  }
+
   // ── Workspace structure ─────────────────────────────────────────────────────
   step('Creating workspace…');
   fs.ensureDirSync(workspace);
@@ -132,7 +159,7 @@ module.exports = async function init() {
   if (example) {
     step('Creating example project…');
     const exampleDir = path.join(workspace, 'my-project');
-    writeExampleProject(exampleDir, codeDir, pythonBin, anthropicKey || '');
+    writeExampleProject(exampleDir, codeDir, pythonBin, anthropicKey || '', { botToken: slackBotToken || '', appToken: slackAppToken || '' });
     ok(`Example project: ${exampleDir}`);
   }
 

package/package.json

@@ -1,21 +1,21 @@
-{
-  "name": "@misterhuydo/sentinel",
-  "version": "1.0.13",
-  "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.15",
+  "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

@@ -56,6 +56,8 @@ class SentinelConfig:
     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
@@ -145,6 +147,8 @@ class ConfigLoader:
         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

@@ -563,6 +563,9 @@ async def run_loop(cfg_loader: ConfigLoader, store: StateStore):
     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/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-...