@sellable/install 0.1.310 → 0.1.311

package/HERMES-SLACK-PROFILE-SCOPING.md

@@ -0,0 +1,139 @@
+# Hermes Slack Profile Scoping
+
+Use this when creating or updating customer Hermes profiles that need Slack
+access.
+
+## Default Rule
+
+Each Slack-enabled customer profile should have its own Slack app installation:
+
+- one profile-local `SLACK_BOT_TOKEN`
+- one profile-local `SLACK_APP_TOKEN`
+- one `SLACK_HOME_CHANNEL`
+- one fail-closed `SLACK_ALLOWED_CHANNELS` allowlist
+
+The bot should be invited only to the customer's managed channel, normally
+`sellable-{customerSlug}`.
+
+Shared Slack credentials can work for outbound-only smoke tests, but they are a
+weaker isolation model. Do not run multiple active Socket Mode listeners against
+the same Slack app token unless there is a separate dispatcher architecture that
+routes events to profiles.
+
+The 2026-07-06 Hostinger POC proved the native Hermes listener for the
+`sellable-admin` profile with the existing `Sellable Reply Bot` app in
+`#team-chat`: a human mention produced a new Hermes session and a threaded bot
+reply. Treat that as proof that the gateway/listener path works for one owning
+profile, not as approval for multiple active customer profiles sharing one app
+token.
+
+The same day, the `acme` profile reused the same redacted Slack token
+fingerprints for an outbound-only smoke to `#sellable-acme` via:
+
+```bash
+hermes --profile acme send --to slack:C0BFERDV3N0 --subject '[Hermes acme smoke]' ...
+```
+
+That succeeded and is useful as an internal smoke test. It does not change the
+inbound listener rule: only one profile should own an active Socket Mode
+connection for a given `SLACK_APP_TOKEN`.
+
+## Which Slack Values Are Enough
+
+For outbound sends and ordinary Slack Web API calls, the important value is the
+profile-local `SLACK_BOT_TOKEN`.
+
+For native Hermes live listening through Slack Socket Mode, the profile also
+needs `SLACK_APP_TOKEN`, an app-level `xapp-...` token with `connections:write`.
+`SLACK_APP_ID`, `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`,
+`SLACK_SIGNING_SECRET`, `SLACK_VERIFICATION_TOKEN`, `SLACK_TEAM_ID`, and
+`SLACK_OPERATOR_EMAIL` do not replace `SLACK_APP_TOKEN`.
+
+## Required Slack App Shape
+
+Outbound Slack sends can work with fewer permissions. Native Hermes inbound
+listening needs the Slack app itself to be configured for Socket Mode and event
+delivery:
+
+- Enable Socket Mode.
+- Create an app-level token with `connections:write`.
+- Install the bot with `app_mentions:read`, `channels:history`,
+  `channels:read`, `chat:write`, `groups:history`, `groups:read`,
+  `im:history`, `im:read`, `mpim:history`, `mpim:read`, and `users:read`.
+- Subscribe bot events for `app_mention`, `message.channels`,
+  `message.groups`, `message.im`, and `message.mpim`.
+- Reinstall the app after changing scopes or event subscriptions.
+
+If the Slack app has `incoming-webhook`, Slack will ask for a webhook channel
+during reinstall. Pick the profile home channel. That webhook selection does
+not replace `SLACK_ALLOWED_CHANNELS`; keep the profile-local allowlist explicit.
+
+## Bootstrap Command
+
+Use the Sellable installer profile bootstrap:
+
+```bash
+sellable hermes profile bootstrap \
+  --profile acme \
+  --profiles-root /srv/hermes/profiles \
+  --workspace-id ws_acme \
+  --workspace-name Acme \
+  --token-file /run/secrets/sellable-acme-token \
+  --slack-bot-token "$SLACK_BOT_TOKEN" \
+  --slack-app-token "$SLACK_APP_TOKEN" \
+  --slack-home-channel C0ACME12345 \
+  --slack-home-channel-name sellable-acme \
+  --slack-allowed-users U0OPERATOR1 \
+  --slack-require-mention true \
+  --json
+```
+
+If `--slack-home-channel` is supplied and `--slack-allowed-channels` is omitted,
+the installer writes `SLACK_ALLOWED_CHANNELS=<home-channel-id>` automatically.
+That makes the profile fail closed to the customer channel by default.
+
+Use `--slack-allowed-channels C...,G...` only when a profile is intentionally
+allowed to listen in more than one channel. Pass Slack IDs, not `#channel-name`
+strings or wildcards.
+
+## Resulting Profile Env
+
+The profile-local `.env` should contain only scoped Slack keys for that profile:
+
+```env
+SLACK_BOT_TOKEN=...
+SLACK_APP_TOKEN=...
+SLACK_HOME_CHANNEL=C0ACME12345
+SLACK_HOME_CHANNEL_NAME=sellable-acme
+SLACK_ALLOWED_CHANNELS=C0ACME12345
+SLACK_ALLOWED_USERS=U0OPERATOR1
+SLACK_REQUIRE_MENTION=true
+```
+
+Keep the file mode at `0600`. Do not copy raw tokens into planning docs, chat,
+or committed artifacts. Record token fingerprints only.
+
+## Verification
+
+Run the installer UAT before publishing installer changes:
+
+```bash
+npm run test:unit -- tests/install-package/agent-preferences.test.ts
+scripts/run-phase92-hermes-profile-bootstrap-uat.sh --mode local-temp
+scripts/run-phase92-hermes-profile-bootstrap-uat.sh --mode linux-shaped
+```
+
+Expected proof:
+
+- profile-local Sellable config paths remain authoritative
+- generated profile `.env` has `SLACK_HOME_CHANNEL`
+- generated profile `.env` has `SLACK_ALLOWED_CHANNELS`
+- `acme` allowlist points at the `sellable-acme` fixture channel id
+- redaction scan passes
+
+## Current Phase 03 Status
+
+Phase 03 has proved the profile-scoped installer path, outbound Hermes send
+path, and live Slack listener for the `sellable-admin` profile. The
+customer-specific app/token creation path remains the next hardening step before
+multiple active customer listeners are safe.

package/README.md

@@ -119,29 +119,11 @@ It creates:
 /srv/hermes/profiles/acme/sellable/config.json
 /srv/hermes/profiles/acme/sellable/configs/
 /srv/hermes/profiles/acme/skills/sellable/
-/srv/hermes/bin/entrypoint-acme.sh
 /srv/hermes/profiles/acme/.env        # only when Slack token inputs are supplied
 ```
 
-For profile paths under a gateway root such as
-`/srv/hermes/profiles/acme`, bootstrap also registers
-`/srv/hermes/profiles/acme/skills/sellable` in the gateway root
-`/srv/hermes/config.yaml` as `skills.external_dirs`. Keep this behavior:
-Hermes Desktop command autocomplete scans the gateway/root skill config, not
-only the selected profile's local skill tree.
-
-Bootstrap also writes `/srv/hermes/bin/entrypoint-acme.sh`. Point the Hermes
-Docker service at that script when this profile should be the Desktop/dashboard
-default:
-
-```yaml
-entrypoint: ["/opt/data/bin/entrypoint-acme.sh"]
-```
-
-The wrapper starts `hermes gateway run` when needed, then intentionally runs
-`hermes -p acme dashboard --isolated`. Without `--isolated`, Hermes OS chat can
-see `/sellable-*` commands while Hermes Desktop autocomplete misses them because
-the dashboard backend is not scoped to the selected profile.
+See [`HERMES-SLACK-PROFILE-SCOPING.md`](./HERMES-SLACK-PROFILE-SCOPING.md) for
+the customer Slack isolation contract and Socket Mode token requirements.
 
 If no token is supplied, bootstrap still creates a pending
 `sellable/config.json` so the profile path is concrete from the first MCP
@@ -163,6 +145,36 @@ sellable hermes profile bootstrap \
   --slack-app-token "$SLACK_APP_TOKEN"
 ```
 
+The Slack app must also be configured for inbound Socket Mode delivery. Outbound
+Slack Web API sends can work before this is complete, but Hermes will not hear
+mentions until the app has Socket Mode enabled, an app-level token with
+`connections:write`, bot scopes/events for `app_mention` plus channel/group/IM
+message events, and a fresh workspace reinstall after scope or event changes.
+
+Scope the profile to its customer channel at install time:
+
+```bash
+sellable hermes profile bootstrap \
+  --profile acme \
+  --profiles-root /srv/hermes/profiles \
+  --workspace-id ws_acme \
+  --slack-bot-token "$SLACK_BOT_TOKEN" \
+  --slack-app-token "$SLACK_APP_TOKEN" \
+  --slack-home-channel C0ACME12345 \
+  --slack-home-channel-name sellable-acme \
+  --slack-allowed-users U0OPERATOR1 \
+  --slack-require-mention true
+```
+
+When `--slack-home-channel` is supplied without
+`--slack-allowed-channels`, bootstrap writes
+`SLACK_ALLOWED_CHANNELS=<home-channel-id>` too. That fail-closes a customer
+profile to the intended channel by default. Use
+`--slack-allowed-channels C...,G...` only when a profile is deliberately allowed
+to listen in multiple channels. Pass channel IDs, not `#channel-name`, and use
+separate Slack bot/app tokens per customer profile when you need hard isolation
+between concurrently listening Hermes profiles.
+
 Customer profiles should use customer-scoped Sellable credentials. A shared
 Sellable admin token can work for internal admin automation, but it is weaker
 isolation and should not be the default for customer profiles. After changing

package/bin/sellable-install.mjs

@@ -13,7 +13,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { stdout as output } from "node:process";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
@@ -217,9 +217,11 @@ Hermes profile bootstrap:
 
   Bootstrap writes <profileRoot>/config.yaml, <profileRoot>/sellable/config.json,
   <profileRoot>/sellable/configs, Sellable Hermes skills, and optional
-  <profileRoot>/.env Slack token keys. Use customer-scoped Sellable credentials
-  for customer profiles; a shared admin token is weaker isolation and should
-  remain internal-only.
+  <profileRoot>/.env Slack token and channel-scope keys. For customer profiles,
+  pass --slack-home-channel; bootstrap defaults SLACK_ALLOWED_CHANNELS to that
+  exact channel id unless --slack-allowed-channels is supplied. Use
+  customer-scoped Sellable and Slack credentials for customer profiles; shared
+  admin tokens are weaker isolation and should remain internal-only.
 `;
 }
 
@@ -1180,10 +1182,9 @@ const REFRESH_SENDER_ENGAGEMENT_ALLOWED_TOOLS = [
   "mcp__sellable__get_campaign_table_schema",
   "mcp__sellable__list_tables",
   "mcp__sellable__get_rows_minimal",
+  "mcp__sellable__refresh_sender_engagement",
   "mcp__sellable__fetch_linkedin_posts",
-  "mcp__sellable__select_promising_posts",
   "mcp__sellable__fetch_post_engagers",
-  "mcp__sellable__add_on_demand_leads",
 ];
 
 function allowedToolsYaml(tools) {
@@ -2145,10 +2146,10 @@ ${allowedToolsYaml(REFRESH_SENDER_ENGAGEMENT_ALLOWED_TOOLS)}
 
 Use this as the customer-facing entrypoint for the Sellable
 \`refresh-sender-engagement\` workflow. It finds active sender-owned Post
-Engagers / Signal Discovery campaigns, fetches recent sender-authored LinkedIn
-posts, pulls latest engagers, filters to ICP, and adds net-new leads with
-dedupe. It never creates messages, approves rows, schedules sends, or launches
-campaigns.
+Engagers campaigns, runs the typed \`refresh_sender_engagement\` command in
+\`mode:"dry_run"\`, and gates any \`mode:"apply"\` call with the returned
+\`dryRunFingerprint\`. It never creates messages, approves rows, schedules
+sends, or launches campaigns.
 
 ## Bootstrap
 
@@ -2168,9 +2169,15 @@ Desktop, then start a new thread.
    \`mcp__sellable__get_subskill_prompt({ subskillName: "refresh-sender-engagement" })\`.
    If the response has \`hasMore=true\`, continue with \`nextOffset\` until
    \`hasMore=false\`.
-3. Follow the canonical prompt exactly. Target active/paused sender-owned Post
-   Engagers campaigns backed by Signal Discovery, and do not touch shared lanes
-   or send-state tools.
+3. Follow the canonical prompt exactly. Prefer
+   \`mcp__sellable__refresh_sender_engagement\` for dry-run and apply. Do not use
+   primitive lead import tools as an alternate write path.
+4. For manual runs, show the dry-run target workspace, sender, campaign/table,
+   expected impact, and \`dryRunFingerprint\`; wait for explicit approval before
+   apply. For scheduled automations, apply only with the fingerprint from the
+   immediately preceding dry run.
+5. Do not touch shared lanes, campaign status, approval, message preparation, or
+   send-state tools.
 
 ## MCP Prompt Fallback
 
@@ -3663,87 +3670,6 @@ function hermesSkillsRoot(opts = {}) {
   return join(hermesHome(opts), "skills", "sellable");
 }
 
-function hermesGatewayRoot(opts = {}) {
-  const profileRoot = hermesHome(opts);
-  const profilesRoot = dirname(profileRoot);
-  if (basename(profilesRoot) !== "profiles") return null;
-  return dirname(profilesRoot);
-}
-
-function hermesGatewayConfigPath(opts = {}) {
-  const root = hermesGatewayRoot(opts);
-  if (!root) return null;
-  return join(root, "config.yaml");
-}
-
-function hermesDashboardEntrypointPath(opts = {}, profile = "") {
-  const root = hermesGatewayRoot(opts);
-  if (!root) return null;
-  const safeProfile = String(profile || basenameSafe(hermesHome(opts))).replace(
-    /[^A-Za-z0-9_.-]/g,
-    "_"
-  );
-  return join(root, "bin", `entrypoint-${safeProfile}.sh`);
-}
-
-function hermesDashboardCommand(profile) {
-  return `hermes -p ${profile} dashboard --isolated --host 0.0.0.0 --port 4860 --no-open --skip-build`;
-}
-
-function hermesDashboardEntrypointContent(opts, profile) {
-  const quotedProfile = shellQuote(profile);
-  const quotedProfileRoot = shellQuote(hermesHome(opts));
-  const gatewayRoot = hermesGatewayRoot(opts);
-  const quotedGatewayRoot = shellQuote(gatewayRoot || dirname(hermesHome(opts)));
-  const quotedDashboardLog = shellQuote(join(hermesHome(opts), "logs", "dashboard.log"));
-  return `#!/usr/bin/env bash
-set -euo pipefail
-
-# This file is generated by sellable hermes profile bootstrap.
-# It preserves the Hostinger image startup shape, but launches the dashboard in
-# an isolated Sellable profile. Without --isolated, Hermes OS chat can see
-# profile skills while Desktop slash autocomplete stays on the default profile.
-profile=${quotedProfile}
-profile_root=${quotedProfileRoot}
-gateway_root=${quotedGatewayRoot}
-dashboard_log=${quotedDashboardLog}
-dashboard_port="\${HERMES_DASHBOARD_PORT:-4860}"
-run_as=()
-if command -v gosu >/dev/null 2>&1; then
-  run_as=(gosu hermes)
-fi
-
-chown -R hermes:hermes "$gateway_root" 2>/dev/null || true
-mkdir -p "$gateway_root/logs" "$profile_root/logs"
-chown -R hermes:hermes "$gateway_root/logs" "$profile_root/logs" 2>/dev/null || true
-
-if [[ -f "$gateway_root/config.yaml" ]]; then
-  if ! pgrep -f "hermes gateway run" >/dev/null 2>&1; then
-    "\${run_as[@]}" nohup hermes gateway run >>"$gateway_root/logs/gateway.log" 2>&1 </dev/null &
-  fi
-fi
-
-for v in ADMIN_USERNAME ADMIN_PASSWORD; do
-  if [[ -z "\${!v:-}" ]]; then
-    echo "missing required environment variable $v" >&2
-    exit 1
-  fi
-done
-
-export HERMES_DASHBOARD_BASIC_AUTH_USERNAME="$ADMIN_USERNAME"
-export HERMES_DASHBOARD_BASIC_AUTH_PASSWORD="$ADMIN_PASSWORD"
-
-exec "\${run_as[@]}" hermes -p "$profile" dashboard --isolated --host 0.0.0.0 --port "$dashboard_port" --no-open --skip-build >>"$dashboard_log" 2>&1
-`;
-}
-
-function writeHermesDashboardEntrypoint(opts, profile) {
-  const path = hermesDashboardEntrypointPath(opts, profile);
-  if (!path) return null;
-  writeFile(path, hermesDashboardEntrypointContent(opts, profile), opts, 0o755);
-  return path;
-}
-
 function hermesLikelyInstalled() {
   return (
     Boolean(process.env.HERMES_HOME?.trim()) ||
@@ -3823,38 +3749,6 @@ function writeHermesMcpServer(opts) {
   return configPath;
 }
 
-function writeHermesGatewaySkillDirectory(opts) {
-  const configPath = hermesGatewayConfigPath(opts);
-  if (!configPath || configPath === hermesConfigPath(opts)) return null;
-
-  const skillDir = hermesSkillsRoot(opts);
-  const raw = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
-  const config = parseHermesConfig(raw, configPath);
-  // Hermes Desktop slash autocomplete scans the gateway/root HERMES_HOME. A
-  // profile can execute its own skills without this, but Desktop will not show
-  // /sellable-* commands until the root scanner sees the profile skill dir.
-  const skills =
-    config.skills && typeof config.skills === "object" && !Array.isArray(config.skills)
-      ? config.skills
-      : {};
-  const current = Array.isArray(skills.external_dirs)
-    ? skills.external_dirs
-    : skills.external_dirs
-      ? [skills.external_dirs]
-      : [];
-  const externalDirs = current.includes(skillDir) ? current : [...current, skillDir];
-  const nextConfig = {
-    ...config,
-    skills: {
-      ...skills,
-      external_dirs: externalDirs,
-    },
-  };
-
-  writeHermesConfig(configPath, nextConfig, opts);
-  return { configPath, skillDir };
-}
-
 function installHermesSkills(opts) {
   const root = hermesSkillsRoot(opts);
   for (const skill of hermesSkillDefinitions()) {
@@ -3875,15 +3769,8 @@ function installHermes(opts) {
   try {
     skillsRoot = installHermesSkills(opts);
     const configPath = writeHermesMcpServer(opts);
-    const gateway = writeHermesGatewaySkillDirectory(opts);
     logVerbose(`${C.grey}+ Hermes config updated: ${configPath}${C.reset}`);
-    return {
-      installed: true,
-      configPath,
-      skillsRoot,
-      gatewayConfigPath: gateway?.configPath || null,
-      gatewayExternalSkillsDir: gateway?.skillDir || null,
-    };
+    return { installed: true, configPath, skillsRoot };
   } catch (err) {
     if (skillsRoot && !opts.dryRun) {
       rmSync(skillsRoot, { recursive: true, force: true });
@@ -3904,6 +3791,12 @@ function parseHermesProfileBootstrapArgs(argv) {
     apiUrl: process.env.SELLABLE_API_URL || DEFAULT_API_URL,
     slackBotToken: process.env.SLACK_BOT_TOKEN || "",
     slackAppToken: process.env.SLACK_APP_TOKEN || "",
+    slackHomeChannel: process.env.SLACK_HOME_CHANNEL || "",
+    slackHomeChannelName: process.env.SLACK_HOME_CHANNEL_NAME || "",
+    slackAllowedChannels: process.env.SLACK_ALLOWED_CHANNELS || "",
+    slackFreeResponseChannels: process.env.SLACK_FREE_RESPONSE_CHANNELS || "",
+    slackAllowedUsers: process.env.SLACK_ALLOWED_USERS || "",
+    slackRequireMention: process.env.SLACK_REQUIRE_MENTION || "",
     server: process.env.SELLABLE_INSTALL_SERVER || "package",
     mcpPackage: DEFAULT_SERVER_PACKAGE,
     localCommand: process.env.SELLABLE_MCP_LOCAL_COMMAND || "",
@@ -3936,6 +3829,12 @@ function parseHermesProfileBootstrapArgs(argv) {
     else if (arg === "--api-url") opts.apiUrl = next();
     else if (arg === "--slack-bot-token") opts.slackBotToken = next();
     else if (arg === "--slack-app-token") opts.slackAppToken = next();
+    else if (arg === "--slack-home-channel") opts.slackHomeChannel = next();
+    else if (arg === "--slack-home-channel-name") opts.slackHomeChannelName = next();
+    else if (arg === "--slack-allowed-channels") opts.slackAllowedChannels = next();
+    else if (arg === "--slack-free-response-channels") opts.slackFreeResponseChannels = next();
+    else if (arg === "--slack-allowed-users") opts.slackAllowedUsers = next();
+    else if (arg === "--slack-require-mention") opts.slackRequireMention = next();
     else if (arg === "--server") opts.server = next();
     else if (arg === "--mcp-package") {
       opts.mcpPackage = normalizeWindowsPackageSpec(next());
@@ -4037,6 +3936,111 @@ function renderEnvFile({ entries, passthrough }) {
   return `${lines.join("\n")}${lines.length ? "\n" : ""}`;
 }
 
+function normalizeSlackChannelIds(value, key) {
+  const raw = String(value || "").trim();
+  if (!raw) return "";
+  const ids = raw
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+  if (ids.length === 0) return "";
+
+  for (const id of ids) {
+    if (
+      id === "*" ||
+      /^all$/i.test(id) ||
+      id.startsWith("#") ||
+      /\s/.test(id) ||
+      !/^[A-Z][A-Z0-9]{8,}$/.test(id)
+    ) {
+      throw new Error(
+        `${key} must be comma-separated Slack channel IDs, not names, wildcards, or free text. Bad value: ${id}`
+      );
+    }
+  }
+  return [...new Set(ids)].join(",");
+}
+
+function normalizeSlackSingleChannelId(value, key) {
+  const normalized = normalizeSlackChannelIds(value, key);
+  if (normalized.includes(",")) {
+    throw new Error(`${key} must be a single Slack channel ID`);
+  }
+  return normalized;
+}
+
+function normalizeSlackUserIds(value, key) {
+  const raw = String(value || "").trim();
+  if (!raw) return "";
+  const ids = raw
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+  if (ids.length === 0) return "";
+
+  for (const id of ids) {
+    if (!/^[UW][A-Z0-9]{8,}$/.test(id)) {
+      throw new Error(`${key} must be comma-separated Slack user IDs. Bad value: ${id}`);
+    }
+  }
+  return [...new Set(ids)].join(",");
+}
+
+function normalizeSlackChannelName(value, key) {
+  const raw = String(value || "").trim();
+  if (!raw) return "";
+  if (raw.startsWith("#") || /[\s,]/.test(raw)) {
+    throw new Error(`${key} must be a Slack channel name without #, spaces, or commas`);
+  }
+  return raw;
+}
+
+function normalizeSlackBoolean(value, key) {
+  const raw = String(value || "").trim().toLowerCase();
+  if (!raw) return "";
+  if (raw !== "true" && raw !== "false") {
+    throw new Error(`${key} must be true or false`);
+  }
+  return raw;
+}
+
+function buildSlackProfileEnv(parsed) {
+  const homeChannel = normalizeSlackSingleChannelId(
+    parsed.slackHomeChannel,
+    "SLACK_HOME_CHANNEL"
+  );
+  const explicitAllowedChannels = normalizeSlackChannelIds(
+    parsed.slackAllowedChannels,
+    "SLACK_ALLOWED_CHANNELS"
+  );
+  const allowedChannels = explicitAllowedChannels || homeChannel;
+
+  return {
+    SLACK_BOT_TOKEN: parsed.slackBotToken.trim(),
+    SLACK_APP_TOKEN: parsed.slackAppToken.trim(),
+    SLACK_HOME_CHANNEL: homeChannel,
+    SLACK_HOME_CHANNEL_NAME: normalizeSlackChannelName(
+      parsed.slackHomeChannelName,
+      "SLACK_HOME_CHANNEL_NAME"
+    ),
+    // Customer Hermes profiles must fail closed to their channel. If the caller
+    // supplies only a home channel, we treat that as the allowlist too.
+    SLACK_ALLOWED_CHANNELS: allowedChannels,
+    SLACK_FREE_RESPONSE_CHANNELS: normalizeSlackChannelIds(
+      parsed.slackFreeResponseChannels,
+      "SLACK_FREE_RESPONSE_CHANNELS"
+    ),
+    SLACK_ALLOWED_USERS: normalizeSlackUserIds(
+      parsed.slackAllowedUsers,
+      "SLACK_ALLOWED_USERS"
+    ),
+    SLACK_REQUIRE_MENTION: normalizeSlackBoolean(
+      parsed.slackRequireMention,
+      "SLACK_REQUIRE_MENTION"
+    ),
+  };
+}
+
 function findDuplicateSlackTokenProfiles(profileRoot, slackTokens) {
   const duplicates = [];
   const profilesRoot = dirname(profileRoot);
@@ -4089,10 +4093,14 @@ function runHermesProfileBootstrap(argv) {
     const sellableConfigsDir = join(profileRoot, "sellable", "configs");
     const envPath = join(profileRoot, ".env");
     const { token, source: tokenSource } = readBootstrapToken(parsed);
+    const slackEnv = buildSlackProfileEnv(parsed);
     const slackTokens = {
-      SLACK_BOT_TOKEN: parsed.slackBotToken.trim(),
-      SLACK_APP_TOKEN: parsed.slackAppToken.trim(),
+      SLACK_BOT_TOKEN: slackEnv.SLACK_BOT_TOKEN,
+      SLACK_APP_TOKEN: slackEnv.SLACK_APP_TOKEN,
     };
+    const slackEnvKeys = Object.entries(slackEnv)
+      .filter(([, value]) => value)
+      .map(([key]) => key);
     const opts = {
       ...parsed,
       host: "hermes",
@@ -4121,8 +4129,6 @@ function runHermesProfileBootstrap(argv) {
         sellableConfigPath,
         sellableConfigsDir,
         skillsRoot: hermesSkillsRoot(opts),
-        gatewayConfigPath: hermesGatewayConfigPath(opts),
-        hermesDashboardEntrypointPath: hermesDashboardEntrypointPath(opts, profile),
       },
       auth: {
         apiUrl: opts.apiUrl,
@@ -4136,17 +4142,29 @@ function runHermesProfileBootstrap(argv) {
         keys: Object.entries(slackTokens)
           .filter(([, value]) => value)
           .map(([key]) => key),
+        envKeys: slackEnvKeys,
         fingerprints: Object.fromEntries(
           Object.entries(slackTokens)
             .filter(([, value]) => value)
             .map(([key, value]) => [key, tokenFingerprint(value)])
         ),
-      },
-      dashboard: {
-        command: hermesDashboardCommand(profile),
-        composeEntrypoint: hermesDashboardEntrypointPath(opts, profile)
-          ? `entrypoint: ["${hermesDashboardEntrypointPath(opts, profile)}"]`
-          : null,
+        scope: {
+          homeChannel: slackEnv.SLACK_HOME_CHANNEL || null,
+          homeChannelName: slackEnv.SLACK_HOME_CHANNEL_NAME || null,
+          allowedChannels: slackEnv.SLACK_ALLOWED_CHANNELS
+            ? slackEnv.SLACK_ALLOWED_CHANNELS.split(",")
+            : [],
+          freeResponseChannels: slackEnv.SLACK_FREE_RESPONSE_CHANNELS
+            ? slackEnv.SLACK_FREE_RESPONSE_CHANNELS.split(",")
+            : [],
+          allowedUsersCount: slackEnv.SLACK_ALLOWED_USERS
+            ? slackEnv.SLACK_ALLOWED_USERS.split(",").length
+            : 0,
+          requireMention:
+            slackEnv.SLACK_REQUIRE_MENTION === ""
+              ? null
+              : slackEnv.SLACK_REQUIRE_MENTION === "true",
+        },
       },
       created: [],
       updated: [],
@@ -4191,7 +4209,7 @@ function runHermesProfileBootstrap(argv) {
     if (existsSync(envPath)) {
       envState = parseEnvLines(readFileSync(envPath, "utf8"));
     }
-    for (const [key, value] of Object.entries(slackTokens)) {
+    for (const [key, value] of Object.entries(slackEnv)) {
       if (!value) continue;
       const existing = envState.entries.get(key);
       if (existing && existing !== value && !opts.overwriteEnv) {
@@ -4213,12 +4231,6 @@ function runHermesProfileBootstrap(argv) {
     }
 
     const hermesConfigExisted = existsSync(hermesConfigPath(opts));
-    const gatewayConfigPath = hermesGatewayConfigPath(opts);
-    const gatewayConfigExisted = gatewayConfigPath ? existsSync(gatewayConfigPath) : false;
-    const dashboardEntrypointPath = hermesDashboardEntrypointPath(opts, profile);
-    const dashboardEntrypointExisted = dashboardEntrypointPath
-      ? existsSync(dashboardEntrypointPath)
-      : false;
     const skillsExisted = existsSync(hermesSkillsRoot(opts));
     const authExisted = existsSync(sellableConfigPath);
     const configsDirExisted = existsSync(sellableConfigsDir);
@@ -4257,9 +4269,8 @@ function runHermesProfileBootstrap(argv) {
       mkdirSync(sellableConfigsDir, { recursive: true, mode: 0o700 });
       writeHermesProfileSellableConfig(sellableConfigPath, nextAuth, opts);
       installHermes(opts);
-      writeHermesDashboardEntrypoint(opts, profile);
-      if (Object.values(slackTokens).some(Boolean)) {
-        for (const [key, value] of Object.entries(slackTokens)) {
+      if (Object.values(slackEnv).some(Boolean)) {
+        for (const [key, value] of Object.entries(slackEnv)) {
           if (value) envState.entries.set(key, value);
         }
         writeFile(envPath, renderEnvFile(envState), opts, 0o600);
@@ -4273,25 +4284,21 @@ function runHermesProfileBootstrap(argv) {
     (hermesConfigExisted ? summary.updated : summary.created).push(
       hermesConfigPath(opts)
     );
-    if (gatewayConfigPath) {
-      (gatewayConfigExisted ? summary.updated : summary.created).push(
-        gatewayConfigPath
-      );
-    }
-    if (dashboardEntrypointPath) {
-      (dashboardEntrypointExisted ? summary.updated : summary.created).push(
-        dashboardEntrypointPath
-      );
-    } else {
-      summary.skipped.push(
-        "Hermes dashboard entrypoint: profile root is not under a gateway profiles directory"
-      );
-    }
     (skillsExisted ? summary.updated : summary.created).push(hermesSkillsRoot(opts));
-    if (Object.values(slackTokens).some(Boolean)) {
+    if (Object.values(slackEnv).some(Boolean)) {
       (envExisted ? summary.updated : summary.created).push(envPath);
     } else {
-      summary.skipped.push("Slack env: no Slack tokens supplied");
+      summary.skipped.push("Slack env: no Slack tokens or channel scope supplied");
+    }
+    if (slackEnv.SLACK_HOME_CHANNEL && !parsed.slackAllowedChannels.trim()) {
+      summary.warnings.push(
+        "Slack scope defaulted SLACK_ALLOWED_CHANNELS to SLACK_HOME_CHANNEL for fail-closed profile listening."
+      );
+    }
+    if (slackEnv.SLACK_BOT_TOKEN && !slackEnv.SLACK_APP_TOKEN) {
+      summary.warnings.push(
+        "Slack bot token is present without SLACK_APP_TOKEN; outbound Slack sends may work, but native Hermes Socket Mode listening still requires an xapp app-level token with connections:write."
+      );
     }
     if (!token) {
       summary.warnings.push(

package/lib/runtime-verify.mjs

@@ -35,6 +35,7 @@ export const REQUIRED_SELLABLE_MCP_TOOLS = [
   "refresh_paid_inmail_credits",
   "run_scheduler_sweep",
   "refill_sends",
+  "refresh_sender_engagement",
   "setup_evergreen_campaigns",
   "start_campaign_message_preparation",
   "get_campaign_message_preparation_status",
@@ -75,6 +76,14 @@ export const CREATE_CAMPAIGN_SMOKE_CALLS = [
       limit: 1200,
     },
   },
+  {
+    name: "get_subskill_prompt",
+    arguments: {
+      subskillName: "refresh-sender-engagement",
+      offset: 0,
+      limit: 1200,
+    },
+  },
   {
     name: "refill_sends",
     arguments: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/install",
-  "version": "0.1.310",
+  "version": "0.1.311",
   "type": "module",
   "description": "One-command installer for Sellable MCP in Claude Code, Codex, and Hermes",
   "bin": {
@@ -15,7 +15,8 @@
     "lib",
     "agents",
     "skill-templates",
-    "README.md"
+    "README.md",
+    "HERMES-SLACK-PROFILE-SCOPING.md"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",

package/skill-templates/refresh-sender-engagement.md

@@ -19,10 +19,9 @@ allowed-tools:
   - mcp__sellable__get_campaign_table_schema
   - mcp__sellable__list_tables
   - mcp__sellable__get_rows_minimal
+  - mcp__sellable__refresh_sender_engagement
   - mcp__sellable__fetch_linkedin_posts
-  - mcp__sellable__select_promising_posts
   - mcp__sellable__fetch_post_engagers
-  - mcp__sellable__add_on_demand_leads
 ---
 
 # Refresh Sender Engagement
@@ -34,7 +33,7 @@ You are a pipeline supply agent. People who engage with a sender's LinkedIn post
 <inputs>
 The invoking prompt names the senders ("refresh sender engagement for csreyes92 and thomas"). Resolve each via `list_senders` (match name/handle/LinkedIn URL). With no names given, inspect the active workspace and refresh every connected sender that has an active/paused sender-owned Post Engagers campaign backed by Signal Discovery.
 
-Optional: lookback window (default: posts from the last 30 days), engagement sources (default `both` reactions+comments), target sender names/ids, maximum posts per sender (default 5, hard cap 5 unless the user explicitly asks for more), and target campaign ids/names when the user wants to force a specific campaign.
+Optional: target sender names/ids, `tableId` when the user wants to force a specific campaign table, maximum posts per sender (default 5, hard cap 5 unless the user explicitly asks for more), and maximum engager pages per tracked post.
 </inputs>
 
 <entrypoint>
@@ -53,39 +52,36 @@ suggest `refill-sends`.
 <objective>
 For each target sender/campaign:
 
-1. **Find active Signal Discovery/Post Engagers campaigns first**:
+1. **Authenticate and resolve workspace**:
    - Call `get_auth_status` and confirm the active workspace.
-   - Call `get_campaigns` and, when needed, `list_tables`/`get_campaign` to find candidate campaigns.
-   - Keep only active or paused campaign-backed sender-owned Post Engagers campaigns. Strong signals include campaign/table names like `<Sender> - Post Engagers`, `sourceProvider:"signal-discovery"`, sender attachment to exactly one sender, and source/list/table readback indicating post engagers.
-   - Exclude shared Signal Discovery lanes, Shared Cold Fallback lanes, archived/completed campaigns, non-campaign tables, direct/on-demand-only campaigns, and any campaign attached to multiple senders unless the user explicitly selected it and the readback proves it is sender-owned.
-   - If no matching campaign exists for a sender, report "no active Post Engagers Signal Discovery campaign — create one first" and skip; do not silently create campaigns.
-2. **Resolve the sender and source boundary**:
-   - Match each candidate campaign to its sender from `list_senders`/`get_sender`.
-   - Use the sender's own LinkedIn profile URL/handle as the only source author boundary.
-   - Never scrape third-party authors into a sender-owned Post Engagers campaign.
-3. **Find relevant sender-authored posts to refresh**:
-   - Call `fetch_linkedin_posts({ linkedinUrl: sender profile, limit: 25 })`.
-   - Keep original posts authored by that exact sender, not reposts, from the lookback window.
-   - Rank posts by recency, engagement count, and fit to the campaign's buyer/problem/topic. Prefer posts likely to attract the target buyer over generic company updates.
-   - If the campaign has an existing Signal Discovery/source state that names tracked/selected posts, prefer refreshing those posts when they are still inside the lookback window and relevant; otherwise choose the strongest recent sender-authored posts.
-   - When the product flow expects selected posts to be visible, call `select_promising_posts` before scraping.
-4. **Pull latest engagers**:
-   - For the top posts (up to 5 per sender per run), call `fetch_post_engagers({ postUrl, sources })`.
-   - Default `sources` to `"both"` unless the user requested reactions-only or comments-only.
-5. **Filter to ICP** using the campaign's existing headline ICP criteria (from `get_campaign` brief/rubrics/table schema). Judge each engager's headline against those criteria; exclude obvious non-fits, the sender's own colleagues, existing employees, students/job-seekers, competitors, and anyone with no usable headline. When the campaign has no criteria, keep likely decision-makers/operators and exclude weak-fit profiles.
-6. **Add net-new leads only**:
-   - Use `add_on_demand_leads({ tableId, leads, skipDuplicates: true })` with name, headline-derived title, profile URL, and source/post context where the tool accepts it.
-   - Dedupe is mandatory. Never disable dedupe on a scheduled run.
-   - Do not generate, approve, schedule, or send messages.
-7. **Report**: campaigns inspected, target campaigns selected, posts scanned, engagers found, ICP-passing, net-new added per sender/campaign. If a sender posted nothing in the window, say "no recent posts — nothing to refresh" (that is a truthful no-op, not a failure).
+   - If there is no active workspace or auth is missing, stop with the MCP guidance. Do not use local env files or repo scripts as a substitute for MCP auth.
+   - Resolve each target sender with `list_senders`/`get_sender`. Use the sender id returned by the product, not a guessed handle.
+2. **Use the typed product command first**:
+   - Call `refresh_sender_engagement` in `mode:"dry_run"` for each sender.
+   - Always pass `workspaceId`, `senderId`, and any user-specified `tableId`, `maxPosts`, or `maxEngagerPages`.
+   - Treat the dry-run response as the campaign/source boundary authority. It should identify the sender-owned Post Engagers slot, campaign, workflow table, source provider `campaign-tracked-post`, source table type `tracked_post_engager_source_list`, expected tracked posts, expected engager refresh/import work, and a `dryRunFingerprint`.
+   - If the typed command reports no eligible sender-owned Post Engagers campaign, no tracked posts, no recent posts, or a workspace/sender mismatch, report that exact blocker and stop for that sender. Do not silently create campaigns or fall back to shared lanes.
+3. **Gate writes with dry-run proof**:
+   - Never call `refresh_sender_engagement` in `mode:"apply"` before a successful dry run from this same run.
+   - For manual runs, show the target workspace, sender, campaign/table, source lead list, expected tracked posts, expected row/import impact, and `dryRunFingerprint`, then wait for explicit user approval before apply.
+   - For scheduled automations where the user has already authorized refreshes, apply is allowed only with the exact `dryRunFingerprint` from the immediately preceding dry run.
+   - If apply rejects the fingerprint as stale or mismatched, rerun dry-run and ask for approval again for manual runs.
+4. **Apply through the typed command only**:
+   - Call `refresh_sender_engagement({ mode:"apply", workspaceId, senderId, tableId?, maxPosts?, maxEngagerPages?, dryRunFingerprint })`.
+   - The apply path must materialize/refresh tracked posts, import deduped tracked-post engagers into the campaign table, and preserve product idempotency. Do not use `add_on_demand_leads` or raw table row writes for the same operation.
+5. **Read-only fallback is diagnostic only**:
+   - If the typed command is unavailable, use `get_subskill_prompt`/`search_subskill_prompts` and stop with `blocked: missing_refresh_sender_engagement_tool`.
+   - `fetch_linkedin_posts` and `fetch_post_engagers` may be used only to explain source availability or diagnose provider issues. They are not an alternate write path.
+6. **Report**: campaigns inspected, target campaign/table, tracked posts materialized/refreshed, engagers scanned, ICP-passing/importable, net-new rows imported, duplicates skipped, and any no-op reason per sender/campaign. If a sender posted nothing in the window, say "no recent posts — nothing to refresh" (that is a truthful no-op, not a failure).
 </objective>
 
 <safety>
-- LinkedIn operations here are read-only fetches plus adding rows to a campaign table. **No messages are generated, approved, or sent by this skill.**
+- LinkedIn operations here are read-only fetches plus a typed product import into a campaign table. **No messages are generated, approved, scheduled, or sent by this skill.**
 - Respect workspace boundaries: only add leads to campaigns in the active workspace, and only for senders that belong to it.
 - Respect campaign boundaries: only add engagers to the matched sender-owned Post Engagers campaign/table. Do not mix shared-lane engagers into sender-owned campaigns or sender-owned engagers into shared lanes.
 - Cap provider usage per run: at most 5 posts × `fetch_post_engagers` per sender. If the invoking automation wants more, it must say so explicitly.
-- Never call `start_campaign`, `attach_sequence`, `queue_campaign_cells`, `start_campaign_message_preparation`, approval tools, or any send/schedule tool.
+- Never call `start_campaign`, `attach_sequence`, `queue_campaign_cells`, `start_campaign_message_preparation`, approval tools, send/schedule tools, or shared-lane mutation tools.
+- Never create campaigns, change campaign status, change sender ownership, approve campaign cells, or start message prep as part of this refresh.
 </safety>
 
 <output>