@sellable/install 0.1.300 → 0.1.302

package/README.md

@@ -1,6 +1,6 @@
 # Sellable Installer
 
-Installs Sellable MCP for Claude Code and Codex.
+Installs Sellable MCP for Claude Code, Codex, and Hermes.
 
 ```bash
 curl -fsSL "https://app.sellable.dev/api/v2/cli/install" | sh
@@ -16,7 +16,9 @@ Windows users can use PowerShell or Windows Terminal:
 iwr "https://app.sellable.dev/api/v2/cli/install.ps1" | iex
 ```
 
-After install, restart Codex Desktop so the Sellable skill appears.
+After install, restart Claude Code, Codex Desktop, or Hermes so Sellable MCP
+tools and skills reload. In an active Hermes session, `/reload-mcp` and
+`/reload-skills` can reload the new config.
 
 Verify the runtime tools with:
 
@@ -32,11 +34,11 @@ sellable create
 ```
 
 Campaign creation, sender send refills, foundation memory, content
-capture/ideation, and post drafting run inside Claude Code or Codex, where the
-Sellable MCP tools and approval flows are available.
+capture/ideation, and post drafting run inside Claude Code, Codex, or Hermes,
+where the Sellable MCP tools and approval flows are available.
 
 Install is auth-free by default. The normal path is first-run login: launch a
-Sellable workflow in Claude Code or Codex and the agent handles Sellable
+Sellable workflow in Claude Code, Codex, or Hermes and the agent handles Sellable
 sign-in with a browser magic-link handoff.
 
 The installer uses package stdio MCP by default:
@@ -45,7 +47,7 @@ The installer uses package stdio MCP by default:
 npm exec --yes --package @sellable/mcp@latest -- sellable-mcp
 ```
 
-That keeps new Claude Code/Codex MCP starts on the latest stable package. The
+That keeps new Claude Code/Codex/Hermes MCP starts on the latest stable package. The
 MCP server also checks npm at startup and during `get_auth_status`, caching the
 result at `~/.sellable/update-check.json` so users are prompted to rerun the
 latest installer only when an update is actually available.
@@ -81,7 +83,7 @@ Auth is stored once at:
 ~/.sellable/config.json
 ```
 
-Claude Code and Codex are configured to launch the same packaged MCP server. The
+Claude Code, Codex, and Hermes are configured to launch the same packaged MCP server. The
 installer also writes Sellable agent definitions from the packaged `agents/`
 registry, but normal create-campaign runs use only the Message Drafting
 background agent (`post-find-leads-message-scout`). Source discovery and
@@ -92,7 +94,7 @@ source-scout agents.
 
 ## Names
 
-Use the same public entrypoints in both hosts:
+Use the same public entrypoints across supported hosts:
 
 - Claude Code: `/sellable:create-campaign`
 - Claude Code: `/sellable:create-ab-test`
@@ -110,6 +112,14 @@ Use the same public entrypoints in both hosts:
 - Codex: `$sellable:create-post`
 - Codex: `$sellable:refresh-sender-engagement`
 - Codex: `$sellable:refill-sends`
+- Hermes: `/sellable-create-campaign`
+- Hermes: `/sellable-create-ab-test`
+- Hermes: `/sellable-create-evergreen-campaigns`
+- Hermes: `/sellable-foundation`
+- Hermes: `/sellable-content`
+- Hermes: `/sellable-create-post`
+- Hermes: `/sellable-refresh-sender-engagement`
+- Hermes: `/sellable-refill-sends`
 - Codex Desktop plugin: `sellable@sellable`
 - Codex visible skill: `Sellable Create Campaign`
 - Codex visible skill: `Sellable Create A/B Test`
@@ -125,7 +135,8 @@ Use the same public entrypoints in both hosts:
 
 Do not ask users to run `/sellable:create-campaign-v2`,
 `$sellable:create-campaign-v2`, `$sellable:load-voice`, or
-`$sellable:sellable:create-campaign`. `create-campaign-v2` is loaded internally
+`$sellable:sellable:create-campaign`. Do not ask Hermes users to run
+`/sellable:create-campaign`; use `/sellable-create-campaign`. `create-campaign-v2` is loaded internally
 by the campaign skill. `foundation` is the preferred entrypoint for durable
 founder/company memory. `content` is the preferred entrypoint for adding
 transcripts, recurring ideas, and post seeds. `create-post` remains a supported
@@ -140,6 +151,12 @@ mode support by writing `default_mode_request_user_input = true` under
 `[features]` in `~/.codex/config.toml`. `codex exec` is non-interactive, so it
 cannot show the structured questionnaire UI.
 
+Hermes skills use plain chat for setup and approval questions unless a
+Hermes-native approval tool is visible in the current session. Hermes exposes
+Sellable MCP tools as `mcp_sellable_<tool>`, for example
+`mcp_sellable_get_auth_status`, `mcp_sellable_start_cli_login`, and
+`mcp_sellable_wait_for_cli_login`.
+
 For Codex Desktop, the installer also writes a local Sellable plugin bundle into
 `~/.sellable/codex-marketplace`, includes the Sellable skill entrypoints, and
 enables it in `~/.codex/config.toml`.
@@ -157,4 +174,4 @@ The installer writes compatibility cache aliases for recent Codex plugin
 versions so stale Desktop skill links resolve to the current wrapper instead of
 showing file/version debugging to the user.
 
-If only one host is installed, `--host all` installs the available host and tells you how to add the other one later.
+If only one host is installed, `--host all` installs the available host and tells you how to add the others later.

package/bin/sellable-install.mjs

@@ -15,6 +15,7 @@ import { dirname, join, relative } from "node:path";
 import { stdout as output } from "node:process";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+import { parseDocument } from "yaml";
 import {
   REQUIRED_SELLABLE_MCP_TOOLS,
   verifySellableMcpRuntime,
@@ -170,7 +171,7 @@ Commands:
   uninstall                Remove Sellable host config and installed artifacts.
 
 Options:
-  --host <host>             claude, codex, or all. Default: all
+  --host <host>             claude, codex, hermes, or all. Default: all
   --server <mode>           package, local, or hosted. Default: package
   --token <token>           Sellable API token. Also reads SELLABLE_TOKEN.
   --workspace-id <id>       Sellable workspace id. Also reads SELLABLE_WORKSPACE_ID.
@@ -190,8 +191,9 @@ Options:
 Auth:
   Install is auth-free by default. Sign in happens on the first run of
   /sellable:create-campaign, /sellable:create-evergreen-campaigns,
-  /sellable:foundation, /sellable:content, /sellable:create-post, or
-  /sellable:refresh-sender-engagement, or /sellable:refill-sends in Claude Code or Codex,
+  /sellable:foundation, /sellable:content, /sellable:create-post,
+  /sellable:refresh-sender-engagement, or /sellable:refill-sends in Claude Code,
+  Codex, or Hermes,
   where the agent walks you through signup or sign-in and stores credentials
   in ~/.sellable/config.json.
 
@@ -203,7 +205,7 @@ Auth:
 
 function printCreateCommandHint() {
   printBanner();
-  console.log(`  ${C.bold}Run Sellable from Claude Code or Codex.${C.reset}`);
+  console.log(`  ${C.bold}Run Sellable from Claude Code, Codex, or Hermes.${C.reset}`);
   console.log("");
   console.log(
     `  ${C.grey}The terminal command installs and verifies Sellable. Campaign creation runs inside your agent session so the workflow can use MCP tools, live state, and approval gates.${C.reset}`
@@ -237,6 +239,18 @@ function printCreateCommandHint() {
     { label: "Refill", command: "$sellable:refill-sends" },
   ]);
   console.log("");
+  console.log("");
+  printAgentBox("Using Hermes?", "hermes", [
+    { label: "Campaign", command: "/sellable-create-campaign" },
+    { label: "A/B Test", command: "/sellable-create-ab-test" },
+    { label: "Evergreen", command: "/sellable-create-evergreen-campaigns" },
+    { label: "Foundation", command: "/sellable-foundation" },
+    { label: "Content", command: "/sellable-content" },
+    { label: "Post", command: "/sellable-create-post" },
+    { label: "Refresh", command: "/sellable-refresh-sender-engagement" },
+    { label: "Refill", command: "/sellable-refill-sends" },
+  ]);
+  console.log("");
   console.log(`   ${"─".repeat(63)}`);
   console.log(`    ${C.grey}If those commands are missing, run:${C.reset}`);
   console.log("");
@@ -249,7 +263,10 @@ function printCreateCommandHint() {
 
 function parseArgs(argv) {
   const opts = {
-    host: process.env.SELLABLE_INSTALL_HOST || "all",
+    host:
+      process.env.SELLABLE_INSTALLER_HOST ||
+      process.env.SELLABLE_INSTALL_HOST ||
+      "all",
     server: process.env.SELLABLE_INSTALL_SERVER || "package",
     token: process.env.SELLABLE_TOKEN || "",
     workspaceId: process.env.SELLABLE_WORKSPACE_ID || "",
@@ -313,8 +330,8 @@ function parseArgs(argv) {
     }
   }
 
-  if (!["claude", "codex", "all"].includes(opts.host)) {
-    throw new Error("--host must be claude, codex, or all");
+  if (!["claude", "codex", "hermes", "all"].includes(opts.host)) {
+    throw new Error("--host must be claude, codex, hermes, or all");
   }
   if (!["package", "local", "hosted"].includes(opts.server)) {
     throw new Error("--server must be package, local, or hosted");
@@ -1175,6 +1192,29 @@ the Claude Code instruction for customer-facing language and host functions.
 
 Do not tell Claude Code users to run \`$sellable:${commandName}\`, use
 \`request_user_input\`, or restart Codex Desktop. Do not describe this run as Codex.`;
+  }
+  if (host === "hermes") {
+    return `## Installed Host Contract
+
+This installed skill is running in Hermes Agent. When the shared workflow body
+or fallback text mentions Claude Code, Codex, or Hermes for internal parity,
+choose the Hermes instruction for customer-facing language and host functions.
+
+- Customer-facing command: \`/sellable-${commandName}\`
+- MCP tool naming: Hermes exposes Sellable tools as \`mcp_sellable_<tool>\`;
+  when shared instructions show \`mcp__sellable__<tool>\`, call the matching
+  \`mcp_sellable_<tool>\` tool instead.
+- Structured questions: ask plainly in chat unless a Hermes-native approval or
+  question tool is visible in the current session.
+- Bootstrap host label: \`host: "Hermes"\`
+- Install/reload blocker label: Hermes install/reload problem
+- Reload instruction: restart Hermes, or run \`/reload-mcp\` in the active
+  Hermes session after install
+
+Do not tell Hermes users to run \`$sellable:${commandName}\` or
+\`/sellable:${commandName}\`, use \`AskUserQuestion\` or \`request_user_input\`,
+or restart Claude Code or Codex Desktop. Do not describe this run as Claude Code
+or Codex.`;
   }
   return "";
 }
@@ -2584,6 +2624,256 @@ function codexPluginSkills() {
   ];
 }
 
+function hermesCommandName(commandName) {
+  return `sellable-${commandName}`;
+}
+
+function normalizeHermesSkillMarkdown(markdown, commandName) {
+  const hermesName = hermesCommandName(commandName);
+  let content = String(markdown);
+  if (/^name:\s*.+$/m.test(content)) {
+    content = content.replace(/^name:\s*.+$/m, `name: ${hermesName}`);
+  } else {
+    content = content.replace(/^---\n/m, `---\nname: ${hermesName}\n`);
+  }
+
+  let normalized = content
+    .replace(/mcp__sellable__<tool>/g, "mcp_sellable_<tool>")
+    .replace(/mcp__([A-Za-z0-9_-]+)__<tool>/g, (_, server) => {
+      return `mcp_${String(server).replaceAll("-", "_")}_<tool>`;
+    })
+    .replace(/\bmcp__([A-Za-z0-9_-]+)__([A-Za-z0-9_-]+)\b/g, (_, server, tool) => {
+      return `mcp_${String(server).replaceAll("-", "_")}_${String(tool).replaceAll("-", "_")}`;
+    })
+    .replace(/\bmcp__sellable__/g, "mcp_sellable_")
+    .replace(/\$sellable:/g, "/sellable-")
+    .replace(/\/sellable:/g, "/sellable-")
+    .replace(/Codex install\/reload problem/g, "Hermes install/reload problem")
+    .replace(/Claude Code install\/reload problem/g, "Hermes install/reload problem")
+    .replace(/fully quit and reopen Codex Desktop, then start a new thread/g, "restart Hermes, or run `/reload-mcp` in the active Hermes session")
+    .replace(/fully quit and reopen Claude Code, then start a new session/g, "restart Hermes, or run `/reload-mcp` in the active Hermes session")
+    .replace(/Codex Desktop/g, "Hermes")
+    .replace(/Claude Code\/Codex/g, "Hermes")
+    .replace(/Claude Code or Codex/g, "Hermes")
+    .replace(/Codex or Claude Code/g, "Hermes")
+    .replace(/Claude Code and Codex/g, "Hermes")
+    .replace(/Codex\/Claude/g, "Hermes")
+    .replace(/quick question panel/g, "approval prompt")
+    .replace(/request_user_input/g, "plain chat")
+    .replace(/AskUserQuestion/g, "plain chat");
+
+  normalized = normalized.replace(
+    /Do not tell Hermes users to run[\s\S]*?Do not describe this run as Claude Code\nor Codex\./g,
+    "Do not tell Hermes users to run Codex or Claude command forms, use Codex/Claude structured-question APIs, or restart Codex Desktop or Claude Code. Do not describe this run as Claude Code or Codex."
+  );
+
+  normalized = normalized.replace(
+    /## Structured Questions\n\nUse the host-native structured question gate for intake and approval:[\s\S]*?## Host Runtime Functions/g,
+    `## Structured Questions
+
+Hermes should ask setup questions directly in chat unless the current Hermes
+session exposes a native approval or question tool. Use a bounded approval gate
+only for explicit approval decisions. For open text like LinkedIn URLs, company
+domains, notes, pasted context, campaign ideas, or feedback, ask in normal chat
+and wait for the user to paste the value.
+
+Campaign setup questions are single-choice decisions. Use mutually exclusive
+options and route blended or custom answers through a short free-text follow-up.
+Customer-facing language should call this "a couple setup choices" during
+normal campaign progress.
+
+## Host Runtime Functions`
+  );
+
+  normalized = normalized.replace(
+    /## Names To Use\n\nUse these exact public names[\s\S]*?## Structured Questions/g,
+    `## Names To Use
+
+Use these exact public names for Hermes:
+
+- Hermes command: \`/${hermesName}\`
+- Hermes skill directory: \`skills/sellable/${hermesName}/SKILL.md\`
+- MCP server name: \`sellable\`
+- Hermes MCP tool prefix: \`mcp_sellable_\`
+- Internal workflow prompt: \`create-campaign-v2\`
+
+Do not tell users to run internal subskill names. \`create-campaign-v2\` is only
+the internal subskill loaded through
+\`mcp_sellable_get_subskill_prompt({ subskillName: "create-campaign-v2" })\`.
+
+## Structured Questions`
+  );
+
+  normalized = normalized.replace(
+    /- `ask_user`:[\s\S]*?(?=\n- `load_subprompt`:)/g,
+    `- \`ask_user\`: ask directly in chat unless a Hermes-native approval or
+  question tool is visible in the current session. Use this for
+  multiple-choice intake, campaign-focus choices, source decisions, and
+  approvals. Campaign setup questions are single-choice only; do not use
+  multi-select or checkbox variants.`
+  );
+
+  normalized = normalized.replace(
+    /- `launch_message_drafting`:[\s\S]*?\n\nIf a required interactive/g,
+    `- \`launch_message_drafting\`: if Hermes exposes a background-agent capability,
+  use the compatible Message Drafting agent. Otherwise run the same message
+  drafting branch inline in the parent session with \`statusSource:
+  "parent-thread-fallback"\`.
+
+If a required interactive`
+  );
+
+  normalized = normalized.replace(
+    /Do not silently ask (?:Codex|Hermes) intake or approval questions as plain chat[\s\S]*?Plain chat questions are only acceptable in non-interactive `codex exec`\nsmoke\/rehearsal runs because structured user input is unavailable by design\nthere\.\n\n/g,
+    ""
+  );
+
+  normalized = normalized.replace(
+    /## Active Model Metadata\n\nBefore calling `bootstrap_create_campaign`, collect[\s\S]*?Never invent the model or reasoning effort\. Never pass config defaults as active\nmetadata\. If bootstrap returns `modelQuality\.status === "unknown"`, continue\nwithout asking the user to switch models\.\n\n/g,
+    `## Active Model Metadata
+
+Before calling \`bootstrap_create_campaign\`, pass \`host: "Hermes"\`. If the
+current Hermes session exposes model and effort metadata for this same turn,
+pass those exact values with \`modelMetadataSource: "hermes_runtime_metadata"\`.
+If the current Hermes session context explicitly states both the exact model ID
+and effort/thinking level, pass them with
+\`modelMetadataSource: "hermes_session_context"\`. Otherwise omit \`model\`,
+\`reasoningEffort\`, and \`modelMetadataSource\`.
+
+Never invent the model or reasoning effort. Never inspect Codex or Claude config
+files as proof of the active Hermes session. If bootstrap returns
+\`modelQuality.status === "unknown"\`, continue without asking the user to
+switch models.
+
+`
+  );
+
+  normalized = normalized.replace(/not `plain chat`/g, "not internal API names");
+
+  normalized = normalized
+    .replace(/this is a Codex\ninstall\/reload problem/g, "this is a Hermes\ninstall/reload problem")
+    .replace(/Hermes plugin/g, "Hermes skills");
+
+  return normalized;
+}
+
+function compactHermesEvergreenSkillMd() {
+  return normalizeHermesSkillMarkdown(
+    stampInstalledHost(`---
+name: create-evergreen-campaigns
+description: Create or repair evergreen campaign lanes without launching sends.
+visibility: public
+allowed-tools:
+${allowedToolsYaml(CREATE_EVERGREEN_CAMPAIGNS_ALLOWED_TOOLS)}
+---
+
+# Sellable Create Evergreen Campaigns
+
+Use this as the customer-facing entrypoint for the Sellable
+\`create-evergreen-campaigns\` workflow in Hermes.
+
+## Bootstrap
+
+MCP prompt and command access are required. First call
+\`mcp__sellable__get_auth_status({})\`. Do not inspect repo files, run shell
+commands, use \`npm\`, \`node\`, local harness scripts, or read local prompt
+files to emulate this workflow.
+
+If the Sellable MCP prompt tools are unavailable, stop and say this is a Hermes
+install/reload problem. Tell the user to run
+\`curl -fsSL "https://app.sellable.dev/api/v2/cli/install" | sh\`, then restart
+Hermes or run \`/reload-mcp\`.
+
+## Execute Workflow
+
+1. Load the canonical prompt via
+   \`mcp__sellable__get_subskill_prompt({ subskillName: "create-evergreen-campaigns" })\`.
+   If the response has \`hasMore=true\`, continue with \`nextOffset\` until
+   \`hasMore=false\`.
+2. Ask for bounded approval in normal chat before mutating if the plan requires
+   approval. Do not call Codex app thread tools or Codex CLI workers from
+   Hermes.
+3. Use \`mcp__sellable__setup_evergreen_campaigns({ mode: "plan" })\` for the
+   plan/readback packet, then use the canonical prompt's approved mutation path
+   and return to \`setup_evergreen_campaigns({ mode: "verify" })\` with
+   customer-visible receipts.
+4. Do not launch campaigns, schedule sends, archive campaigns, delete tables,
+   or spend paid credits.
+
+## MCP Prompt Fallback
+
+If exact subskill lookup fails, use
+\`mcp__sellable__search_subskill_prompts({ query: "create-evergreen-campaigns", includePublic: true, includeInternal: true })\`,
+then retry \`get_subskill_prompt\`.
+`, "hermes", "create-evergreen-campaigns"),
+    "create-evergreen-campaigns"
+  );
+}
+
+function hermesSkillDefinitions() {
+  return [
+    {
+      commandName: "create-campaign",
+      dir: hermesCommandName("create-campaign"),
+      skillMd: normalizeHermesSkillMarkdown(
+        createCampaignSkillMd("hermes"),
+        "create-campaign"
+      ),
+      soulMd: createCampaignSoulMd(),
+    },
+    {
+      commandName: "create-ab-test",
+      dir: hermesCommandName("create-ab-test"),
+      skillMd: normalizeHermesSkillMarkdown(
+        createAbTestSkillMd("hermes"),
+        "create-ab-test"
+      ),
+    },
+    {
+      commandName: "create-evergreen-campaigns",
+      dir: hermesCommandName("create-evergreen-campaigns"),
+      skillMd: compactHermesEvergreenSkillMd(),
+    },
+    {
+      commandName: "foundation",
+      dir: hermesCommandName("foundation"),
+      skillMd: normalizeHermesSkillMarkdown(
+        foundationSkillMd("hermes"),
+        "foundation"
+      ),
+    },
+    {
+      commandName: "content",
+      dir: hermesCommandName("content"),
+      skillMd: normalizeHermesSkillMarkdown(contentSkillMd("hermes"), "content"),
+    },
+    {
+      commandName: "create-post",
+      dir: hermesCommandName("create-post"),
+      skillMd: normalizeHermesSkillMarkdown(
+        createPostSkillMd("hermes"),
+        "create-post"
+      ),
+    },
+    {
+      commandName: "refresh-sender-engagement",
+      dir: hermesCommandName("refresh-sender-engagement"),
+      skillMd: normalizeHermesSkillMarkdown(
+        refreshSenderEngagementSkillMd("hermes"),
+        "refresh-sender-engagement"
+      ),
+    },
+    {
+      commandName: "refill-sends",
+      dir: hermesCommandName("refill-sends"),
+      skillMd: normalizeHermesSkillMarkdown(
+        refillSendsSkillMd("hermes"),
+        "refill-sends"
+      ),
+    },
+  ];
+}
+
 function installerPackageRoot() {
   return join(dirname(fileURLToPath(import.meta.url)), "..");
 }
@@ -3152,6 +3442,7 @@ exec ${shellQuote(npmCommand)} exec --yes --package ${shellQuote(INSTALL_PACKAGE
 const WATCH_MODE_DRIVER_ENV = {
   claude: "SELLABLE_WATCH_MODE_DRIVER=claude",
   codex: "SELLABLE_WATCH_MODE_DRIVER=codex",
+  hermes: "SELLABLE_WATCH_MODE_DRIVER=hermes",
 };
 
 function withHostedWatchModeDriver(rawUrl, driver) {
@@ -3277,6 +3568,169 @@ function codexPluginMcpServerMatches(content, opts) {
   }
 }
 
+function hermesHome() {
+  return process.env.HERMES_HOME?.trim() || join(homedir(), ".hermes");
+}
+
+function hermesConfigPath() {
+  return join(hermesHome(), "config.yaml");
+}
+
+function hermesSkillsRoot() {
+  return join(hermesHome(), "skills", "sellable");
+}
+
+function hermesLikelyInstalled() {
+  return (
+    Boolean(process.env.HERMES_HOME?.trim()) ||
+    commandExists("hermes") ||
+    existsSync(hermesConfigPath()) ||
+    existsSync(join(hermesHome(), "skills"))
+  );
+}
+
+function parseHermesConfig(raw, configPath = hermesConfigPath()) {
+  const source = raw.trim() ? raw : "{}\n";
+  const doc = parseDocument(source, { prettyErrors: false });
+  if (doc.errors.length > 0) {
+    throw new Error(
+      `Invalid Hermes config YAML at ${configPath}: ${doc.errors[0].message}`
+    );
+  }
+  const value = doc.toJSON() ?? {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(
+      `Invalid Hermes config YAML at ${configPath}: expected a mapping at the document root`
+    );
+  }
+  return value;
+}
+
+function readHermesConfig() {
+  const configPath = hermesConfigPath();
+  const raw = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  return { raw, config: parseHermesConfig(raw, configPath), configPath };
+}
+
+function hermesMcpServer(opts) {
+  if (opts.server === "hosted") {
+    return {
+      url: withHostedWatchModeDriver(opts.hostedUrl, "hermes"),
+      enabled: true,
+      env: {
+        SELLABLE_WATCH_MODE_DRIVER: "hermes",
+      },
+    };
+  }
+
+  const [command, args] = mcpCommand(opts);
+  return {
+    command,
+    args,
+    enabled: true,
+    env: {
+      SELLABLE_WATCH_MODE_DRIVER: "hermes",
+    },
+  };
+}
+
+function writeHermesConfig(configPath, config, opts) {
+  if (opts.dryRun) return;
+  mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
+  const doc = parseDocument("{}\n");
+  doc.contents = config;
+  writeFileSync(configPath, String(doc), { mode: 0o600 });
+}
+
+function writeHermesMcpServer(opts) {
+  const { config, configPath } = readHermesConfig();
+  const existingMcpServers =
+    config.mcp_servers &&
+    typeof config.mcp_servers === "object" &&
+    !Array.isArray(config.mcp_servers)
+      ? config.mcp_servers
+      : {};
+  const nextConfig = {
+    ...config,
+    mcp_servers: {
+      ...existingMcpServers,
+      sellable: hermesMcpServer(opts),
+    },
+  };
+  writeHermesConfig(configPath, nextConfig, opts);
+  return configPath;
+}
+
+function installHermesSkills(opts) {
+  const root = hermesSkillsRoot();
+  for (const skill of hermesSkillDefinitions()) {
+    const skillRoot = join(root, skill.dir);
+    writeFile(join(skillRoot, "SKILL.md"), skill.skillMd, opts);
+    if (skill.soulMd) {
+      writeFile(join(skillRoot, "SOUL.md"), skill.soulMd, opts);
+    }
+  }
+  return root;
+}
+
+function installHermes(opts) {
+  // Parse config before writing skills so invalid user YAML cannot leave a
+  // half-installed Hermes skill tree behind.
+  readHermesConfig();
+  let skillsRoot = null;
+  try {
+    skillsRoot = installHermesSkills(opts);
+    const configPath = writeHermesMcpServer(opts);
+    logVerbose(`${C.grey}+ Hermes config updated: ${configPath}${C.reset}`);
+    return { installed: true, configPath, skillsRoot };
+  } catch (err) {
+    if (skillsRoot && !opts.dryRun) {
+      rmSync(skillsRoot, { recursive: true, force: true });
+    }
+    throw err;
+  }
+}
+
+function hermesMcpServerMatches(config, opts) {
+  const server = config?.mcp_servers?.sellable;
+  if (!server || typeof server !== "object") return false;
+  const expected = hermesMcpServer(opts);
+  return JSON.stringify(server) === JSON.stringify(expected);
+}
+
+function hermesSkillChecks() {
+  const root = hermesSkillsRoot();
+  const skills = hermesSkillDefinitions();
+  const paths = skills.map((skill) => join(root, skill.dir, "SKILL.md"));
+  const allPresent = paths.every((skillPath) => existsSync(skillPath));
+  const contents = paths
+    .filter((skillPath) => existsSync(skillPath))
+    .map((skillPath) => readFileSync(skillPath, "utf8"));
+  const commandNamesCurrent =
+    contents.length === skills.length &&
+    skills.every((skill, index) =>
+      contents[index]?.includes(`name: ${hermesCommandName(skill.commandName)}`)
+    );
+  const slashCommandsCurrent =
+    contents.length === skills.length &&
+    skills.every((skill, index) =>
+      contents[index]?.includes(`/${hermesCommandName(skill.commandName)}`)
+    );
+  const forbiddenSyntax = contents.some((content) =>
+    /\$sellable:|\/sellable:|mcp__sellable__|request_user_input|AskUserQuestion/.test(
+      content
+    )
+  );
+  return {
+    root,
+    paths,
+    allPresent,
+    commandNamesCurrent,
+    slashCommandsCurrent,
+    forbiddenSyntax,
+  };
+}
+
 function installClaude(opts) {
   if (!commandExists("claude")) {
     const message =
@@ -3558,6 +4012,13 @@ function warningCheck(ok, label) {
   return { ok, label, required: false };
 }
 
+function firstRunCommandForHost(host) {
+  if (host === "hermes") return "/sellable-create-campaign";
+  if (host === "codex") return "$sellable:create-campaign";
+  if (host === "claude") return "/sellable:create-campaign";
+  return "/sellable:create-campaign, $sellable:create-campaign, or /sellable-create-campaign";
+}
+
 async function verify(opts) {
   const startedAt = new Date().toISOString();
   const stored = readStoredAuth();
@@ -3573,7 +4034,7 @@ async function verify(opts) {
     checks.push(
       warningCheck(
         true,
-        `Auth: not yet signed in — sign in on first run of /sellable:create-campaign`
+        `Auth: not yet signed in — sign in on first run of ${firstRunCommandForHost(opts.host)}`
       )
     );
   }
@@ -3860,6 +4321,88 @@ async function verify(opts) {
       )
     );
   }
+  if (opts.host === "hermes" || opts.host === "all") {
+    let hermesConfig = null;
+    let hermesConfigError = "";
+    try {
+      hermesConfig = readHermesConfig().config;
+    } catch (err) {
+      hermesConfigError = err instanceof Error ? err.message : String(err);
+    }
+    const npmPresent = opts.server !== "package" || commandExists(packageManagerCommand());
+    const skillChecks = hermesSkillChecks();
+    const configMatches = hermesConfig
+      ? hermesMcpServerMatches(hermesConfig, opts)
+      : false;
+    const hasHermesDriver =
+      hermesConfig?.mcp_servers?.sellable?.env?.SELLABLE_WATCH_MODE_DRIVER ===
+      "hermes";
+
+    const check =
+      opts.host === "hermes" ? requiredCheck : warningCheck;
+    checks.push(
+      check(
+        !hermesConfigError,
+        hermesConfigError || `Hermes config readable: ${hermesConfigPath()}`
+      )
+    );
+    checks.push(
+      check(
+        configMatches,
+        configMatches
+          ? "Hermes Sellable MCP entry canonical"
+          : "Hermes Sellable MCP entry missing or stale"
+      )
+    );
+    checks.push(
+      check(
+        hasHermesDriver,
+        hasHermesDriver
+          ? "Hermes watch mode driver pinned to hermes"
+          : "Hermes watch mode driver missing"
+      )
+    );
+    checks.push(
+      check(
+        skillChecks.allPresent,
+        skillChecks.allPresent
+          ? "Hermes Sellable skills present"
+          : "Hermes Sellable skills missing"
+      )
+    );
+    checks.push(
+      check(
+        skillChecks.commandNamesCurrent,
+        skillChecks.commandNamesCurrent
+          ? "Hermes skill names current"
+          : "Hermes skill names stale"
+      )
+    );
+    checks.push(
+      check(
+        skillChecks.slashCommandsCurrent,
+        skillChecks.slashCommandsCurrent
+          ? "Hermes slash command hints current"
+          : "Hermes slash command hints stale"
+      )
+    );
+    checks.push(
+      check(
+        !skillChecks.forbiddenSyntax,
+        !skillChecks.forbiddenSyntax
+          ? "Hermes skills use Hermes MCP/tool syntax"
+          : "Hermes skills contain Claude/Codex-only syntax"
+      )
+    );
+    checks.push(
+      check(
+        npmPresent,
+        npmPresent
+          ? "Hermes package runtime command present"
+          : `Hermes package runtime command missing: ${packageManagerCommand()}`
+      )
+    );
+  }
 
   let runtimeMcp;
   try {
@@ -4042,7 +4585,7 @@ function printNextSteps(installedHosts, authReused) {
       `      ${C.bold}Almost there — install an agent first.${C.reset}`
     );
     console.log(
-      `        ${C.yellow}!${C.reset} No agent CLI found (Claude Code or Codex)`
+      `        ${C.yellow}!${C.reset} No agent CLI/profile found (Claude Code, Codex, or Hermes)`
     );
     console.log("");
     console.log("");
@@ -4086,6 +4629,7 @@ function printNextSteps(installedHosts, authReused) {
 
   const hasClaude = installedHosts.includes("Claude Code");
   const hasCodex = installedHosts.includes("Codex");
+  const hasHermes = installedHosts.includes("Hermes");
 
   // Header
   if (authReused) {
@@ -4101,6 +4645,11 @@ function printNextSteps(installedHosts, authReused) {
     console.log(`        ${C.green}✓${C.reset} Skills installed`);
     console.log(`        ${C.green}✓${C.reset} Codex custom agents installed`);
   }
+  if (hasHermes) {
+    console.log(
+      `        ${C.green}✓${C.reset} Hermes skills and MCP config installed`
+    );
+  }
   if (hasClaude) {
     console.log(
       `        ${C.green}✓${C.reset} Claude slash commands and custom agents installed`
@@ -4144,6 +4693,19 @@ function printNextSteps(installedHosts, authReused) {
     ]);
     console.log("");
   }
+  if (hasHermes) {
+    printAgentBox("Using Hermes?", "hermes", [
+      { label: "Campaign", command: "/sellable-create-campaign" },
+      { label: "A/B Test", command: "/sellable-create-ab-test" },
+      { label: "Evergreen", command: "/sellable-create-evergreen-campaigns" },
+      { label: "Foundation", command: "/sellable-foundation" },
+      { label: "Content", command: "/sellable-content" },
+      { label: "Post", command: "/sellable-create-post" },
+      { label: "Refresh", command: "/sellable-refresh-sender-engagement" },
+      { label: "Refill", command: "/sellable-refill-sends" },
+    ]);
+    console.log("");
+  }
 
   console.log("");
   console.log(`   ${"─".repeat(63)}`);
@@ -4173,7 +4735,7 @@ function removeTomlSection(content, header) {
   return content.replace(pattern, "");
 }
 
-function runUninstall() {
+function runUninstall(opts = { host: "all" }) {
   console.log("");
   console.log(`  ${C.bold}Uninstalling Sellable…${C.reset}`);
   console.log("");
@@ -4184,7 +4746,7 @@ function runUninstall() {
 
   // 1) Surgical removal from Codex config.toml
   const codexConfigPath = join(codexHome(), "config.toml");
-  if (existsSync(codexConfigPath)) {
+  if ((opts.host === "codex" || opts.host === "all") && existsSync(codexConfigPath)) {
     try {
       const before = readFileSync(codexConfigPath, "utf8");
       const ts = new Date()
@@ -4221,10 +4783,11 @@ function runUninstall() {
         `  ${C.yellow}!${C.reset} Could not edit Codex config: ${err instanceof Error ? err.message : String(err)}`
       );
     }
-  } else {
+  } else if (opts.host === "codex" || opts.host === "all") {
     skipped.push(`Codex config not found at ${codexConfigPath}`);
   }
 
+  if (opts.host === "codex" || opts.host === "all") {
   for (const agent of [...codexCustomAgents(), ...legacyCodexCustomAgents()]) {
     const agentPath = join(codexHome(), "agents", agent.filename);
     if (!existsSync(agentPath)) continue;
@@ -4237,9 +4800,10 @@ function runUninstall() {
       );
     }
   }
+  }
 
   // 2) Claude Code MCP removal
-  if (commandExists("claude")) {
+  if ((opts.host === "claude" || opts.host === "all") && commandExists("claude")) {
     const r = spawnSync("claude", ["mcp", "remove", "sellable"], {
       encoding: "utf8",
     });
@@ -4248,10 +4812,11 @@ function runUninstall() {
     } else {
       skipped.push(`Claude Code MCP (none registered or already removed)`);
     }
-  } else {
+  } else if (opts.host === "claude" || opts.host === "all") {
     skipped.push(`Claude Code CLI not found`);
   }
 
+  if (opts.host === "claude" || opts.host === "all") {
   for (const agent of [
     ...claudeCustomAgents(),
     ...legacyClaudeCustomAgents(),
@@ -4279,10 +4844,66 @@ function runUninstall() {
       );
     }
   }
+  }
 
-  // 3) Surgical removal of Sellable-installed artifacts inside ~/.sellable/
+  // 3) Hermes config and skill removal
+  if (opts.host === "hermes" || opts.host === "all") {
+    const configPath = hermesConfigPath();
+    if (existsSync(configPath)) {
+      try {
+        const before = readFileSync(configPath, "utf8");
+        const ts = new Date()
+          .toISOString()
+          .replace(/[-:]/g, "")
+          .replace(/\..+/, "");
+        const backupPath = `${configPath}.bak-sellable-uninstall-${ts}`;
+        writeFileSync(backupPath, before, { mode: 0o600 });
+        const config = parseHermesConfig(before, configPath);
+        if (
+          config.mcp_servers &&
+          typeof config.mcp_servers === "object" &&
+          !Array.isArray(config.mcp_servers) &&
+          "sellable" in config.mcp_servers
+        ) {
+          const nextMcpServers = { ...config.mcp_servers };
+          delete nextMcpServers.sellable;
+          writeHermesConfig(
+            configPath,
+            { ...config, mcp_servers: nextMcpServers },
+            { dryRun: false }
+          );
+          removed.push(`Hermes config (sellable removed in ${configPath})`);
+          removed.push(`  backup: ${backupPath}`);
+        } else {
+          skipped.push(`Hermes config had no sellable MCP server`);
+        }
+      } catch (err) {
+        console.log(
+          `  ${C.yellow}!${C.reset} Could not edit Hermes config: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    } else {
+      skipped.push(`Hermes config not found at ${configPath}`);
+    }
+
+    const skillsRoot = hermesSkillsRoot();
+    if (existsSync(skillsRoot)) {
+      try {
+        rmSync(skillsRoot, { recursive: true, force: true });
+        removed.push(`${skillsRoot}`);
+      } catch (err) {
+        console.log(
+          `  ${C.yellow}!${C.reset} Could not remove ${skillsRoot}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    } else {
+      skipped.push(`Hermes Sellable skills not found at ${skillsRoot}`);
+    }
+  }
+
+  // 4) Surgical removal of Sellable-installed artifacts inside ~/.sellable/
   const sellableDir = join(homedir(), ".sellable");
-  if (existsSync(sellableDir)) {
+  if (opts.host === "all" && existsSync(sellableDir)) {
     const tracked = [
       "config.json",
       "update-check.json",
@@ -4321,13 +4942,13 @@ function runUninstall() {
         // ignore
       }
     }
-  } else {
+  } else if (opts.host === "all") {
     skipped.push(`~/.sellable not present`);
   }
 
-  // 4) Self-shim
+  // 5) Self-shim
   const shimPath = join(homedir(), ".local", "bin", "sellable");
-  if (existsSync(shimPath)) {
+  if (opts.host === "all" && existsSync(shimPath)) {
     try {
       rmSync(shimPath, { force: true });
       removed.push(`${shimPath}`);
@@ -4440,6 +5061,13 @@ async function main() {
       console.log(`    Codex: $sellable:create-post`);
       console.log(`    Codex: $sellable:refresh-sender-engagement`);
       console.log(`    Codex: $sellable:refill-sends`);
+      console.log(`    Hermes: /sellable-create-campaign`);
+      console.log(`    Hermes: /sellable-create-evergreen-campaigns`);
+      console.log(`    Hermes: /sellable-foundation`);
+      console.log(`    Hermes: /sellable-content`);
+      console.log(`    Hermes: /sellable-create-post`);
+      console.log(`    Hermes: /sellable-refresh-sender-engagement`);
+      console.log(`    Hermes: /sellable-refill-sends`);
       process.exit(0);
     }
     if (rawArgs[0] === "prefs") {
@@ -4482,7 +5110,8 @@ async function main() {
       process.exit(0);
     }
     if (rawArgs[0] === "uninstall") {
-      runUninstall();
+      const opts = parseArgs(rawArgs.slice(1));
+      runUninstall(opts);
       process.exit(0);
     }
     if (rawArgs[0] === "create") {
@@ -4500,7 +5129,7 @@ async function main() {
     if (!opts.verifyOnly) {
       printBanner();
       console.log(
-        `  ${C.bold}Connecting Sellable to Claude Code and Codex…${C.reset}`
+        `  ${C.bold}Connecting Sellable to Claude Code, Codex, and Hermes…${C.reset}`
       );
       console.log("");
     } else if (!opts.json) {
@@ -4536,6 +5165,15 @@ async function main() {
           installedHosts.push("Codex");
         }
       }
+      if (
+        opts.host === "hermes" ||
+        (opts.host === "all" && hermesLikelyInstalled())
+      ) {
+        const result = installHermes(opts);
+        if (result.installed) {
+          installedHosts.push("Hermes");
+        }
+      }
     }
 
     if (opts.dryRun) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sellable/install",
-  "version": "0.1.300",
+  "version": "0.1.302",
   "type": "module",
-  "description": "One-command installer for Sellable MCP in Claude Code and Codex",
+  "description": "One-command installer for Sellable MCP in Claude Code, Codex, and Hermes",
   "bin": {
     "sellable": "bin/sellable-install.mjs"
   },
@@ -18,13 +18,15 @@
     "README.md"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.2"
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "yaml": "^2.8.1"
   },
   "keywords": [
     "sellable",
     "mcp",
     "claude-code",
     "codex",
+    "hermes",
     "linkedin",
     "outbound"
   ],

package/skill-templates/refill-sends-evergreen.md

@@ -0,0 +1,19 @@
+---
+name: refill-sends-evergreen
+description: Deprecated alias for refill-sends-v2.
+visibility: public
+allowed-tools:
+  - mcp__sellable__get_subskill_prompt
+---
+
+# Refill Sends Evergreen
+
+Superseded by refill-sends-v2. The prompt name now redirects through
+`DEPRECATED_SUBSKILL_PROMPT_REPLACEMENTS`; do not call this deprecated prompt
+directly.
+
+Use `refill-sends-v2` instead:
+
+```text
+get_subskill_prompt({ subskillName: "refill-sends-v2" })
+```

package/skill-templates/refill-sends-v2.md

@@ -0,0 +1,156 @@
+---
+name: refill-sends-v2
+description: Execute refill sends v2 through the fenced evergreen refill loop, with dry-run and resume support.
+visibility: public
+allowed-tools:
+  - mcp__sellable__refill_sends_v2
+  - mcp__sellable__get_refill_plan_v2
+  - mcp__sellable__get_subskill_prompt
+  - mcp__sellable__get_subskill_asset
+  - mcp__sellable__get_auth_status
+  - mcp__sellable__get_active_workspace
+  - mcp__sellable__list_workspaces
+  - mcp__sellable__get_workspace
+---
+
+# Refill Sends V2
+
+Use this command for refill requests such as "refill sends", "fill evergreen
+senders", "load everyone up", "run Damiano", or "show a dry run for this
+workspace".
+
+Host command names:
+
+- Claude Code: `/sellable:refill-sends-v2`
+- Codex: `$sellable:refill-sends-v2`
+
+`refill_sends_v2` is the execution surface. In real-run mode it starts or
+resumes a fenced refill run, reads a fresh packet, executes only the packet's
+named bounded work, verifies the result, and returns either a terminal report, a
+blocked report, or an in-progress resume handle. In dry-run mode it stays
+read-only and writes only a dry-run journal.
+
+## Entry
+
+Resolve the explicit `workspaceId` from the request, automation config, or
+active workspace readback. Scheduled or autonomous usage must carry
+`workspaceId` on every tool call. If the workspace is missing or ambiguous, stop
+with `WORKSPACE_REQUIRED`; do not switch the shared active workspace.
+
+For a real refill run:
+
+```text
+refill_sends_v2({ workspaceId, intent:"auto", senderIds?, approvalMode? })
+```
+
+For read-only inspection:
+
+```text
+refill_sends_v2({ workspaceId, dryRun:true, intent:"auto", senderIds? })
+```
+
+To resume an in-progress run, pass the handle back exactly:
+
+```text
+refill_sends_v2({ workspaceId, runId, fence })
+```
+
+If a stale handle loses the lease, the tool reports the holder status and the
+approximately 10 minute lockout window. Reinvoke with the current handle or wait
+for lease expiry; never guess a fence.
+
+The default `intent:"auto"` inspects `managed_waterfall`,
+`dashboard_evergreen`, and `active_campaign` lane sources. Report the lane
+source and lane chain as proof for every selected sender.
+
+If membership blocks a workspace read, report the structured
+`workspace_access` blocker instead of retrying auth or switching workspaces.
+
+## Authority
+
+The run may execute only packet-named bounded work:
+
+- approve generated messages that are ready for review (`approve_messages`);
+- enrich the next batch of unenriched rows (`enrich_more`);
+- copy leads already found into the campaign table (`reconcile_source_copy`);
+- re-run errored enrichment/message cells (`rerun_errored_cells`);
+- find more leads via this campaign's original source (`add_leads_same_source`)
+  only for mechanical same-source continuations;
+- start the paused campaign so ready rows can schedule (`start_campaign`) only
+  when the campaign is in the packet's pinned lane chain;
+- refresh paid InMail credit facts during bootstrap and once per scheduler-wait
+  entry when the packet requires it.
+
+The loop records planned -> did -> outcome before and after every foreign
+mutation. It refuses stale packets by fingerprint and validates packet
+coherence before dispatch. The planner owns repair decisions: if a batch needs
+repair, the next packet names the repair rung; the loop bounds and refuses, it
+does not improvise fixes.
+
+Do not create campaigns, switch provider families, lower thresholds, write
+scheduler fields, send messages, archive/delete campaigns, or mutate
+brief/filter/message/sequence/sender config unless a separate exact approval
+packet explicitly authorizes that work. In short: no campaign creation, no
+provider-family switch, no threshold lowering, no scheduler writes, no
+launch/send/archive/delete, and no brief/filter/message/sequence/sender
+mutation.
+
+## Continuations
+
+Sales Nav and Prospeo source continuations that are not yolo-safe are blocked
+as executable scoped handoffs. The report will include text shaped like:
+
+```text
+$sellable:create-campaign [campaignId]
+```
+
+That handoff is run in a separate thread only after explicit approval. Scope is
+strict: add leads through this campaign's existing source, keep the same
+saved-search identity, import mode `add` into the same source list, and do
+source work only. It is never a new campaign, provider-family switch, brief
+change, rubric change, message change, sequence change, or sender change.
+
+## Verification
+
+The loop verifies whole rows before replanning. It reattaches to an own active
+prep job instead of re-dispatching, waits on foreign prep jobs without adopting
+their outcomes, waits on active enrichment/import work by rereading the packet,
+and treats capped scheduler capacity as complete.
+
+Scheduler waits are cross-invocation. Each tool call polls briefly under the
+host guard, heartbeats the run lease, and may return:
+
+```text
+{ status:"in_progress", runId, fence, gate, guidance }
+```
+
+Reinvoke with that handle. The approximately five minute scheduler budget is at
+the run level, not one tool call. A window-closed or loaded-awaiting scheduler
+report must include remaining-ready count, exact expected pickup time, and the
+resume handle; never treat bare "awaiting scheduler" copy as a final answer.
+
+After the first prep batch, read the conversion-verdict journal line. It is
+rendered from packet facts: `supplyCensus`, `censusReason`, and
+`pipelineDiagnosis.firstFailing`. If the verdict is honest rubric failure, the
+human decision is to update the rubric or change lead source; refill does not
+mutate those automatically.
+
+## Results
+
+Terminal reasons are:
+
+- `complete`
+- `capped_by_scheduler`
+- `loaded_awaiting_scheduler`
+- `lanes_exhausted`
+- `blocked`
+- `no_refillable_campaigns`
+- `not_an_evergreen_workspace`
+
+Report campaign names and sender names first, ids second. Include the terminal
+reason or resume handle, lane source, lane chain, chosen label with token
+secondary, plan revision, journal path, blocked continuation packets, and
+firstFailing checklist when present.
+
+Real-run journals live under `~/.sellable/refill/runs` by default and append an
+index line. Dry runs include the dry marker and do not create run records.

package/skill-templates/refill-sends.md

@@ -97,8 +97,11 @@ That command helper normalizes arguments and returns the execution contract. In
 non-yolo mode it does not mutate. In `--yolo`, it may execute exactly one safe
 bounded primitive from the fresh `target.globalActionQueue[0]`, then reread and
 return the new target plan; currently safe primitives are paid-credit refresh,
-existing-row message preparation, same-source row copy, and read-only wait
-rereads. It does not run unbounded approval, lower
+existing-row message preparation, generated-message approval, receipt-proven
+same-source row copy, and read-only wait rereads. Same-source copy/source
+fallback is safe only after receipt-proven exhaustion:
+`hasMoreFrontierRows:false`, zero `approvalCandidates`, no `stuckActiveCells`,
+and no non-terminal `approvedNotDispatched` work. It does not run unbounded approval, lower
 paid-InMail thresholds, switch source families, create campaigns, launch, send,
 or write scheduler rows. Continue with the workflow below for route selection,
 state rereads, approval gating, source import, preparation, and bounded
@@ -198,7 +201,10 @@ Structured planner packet:
 - `target.senderRefillPlans[]` is the canonical sender-level packet; read and
   display it before mutation.
 - Each sender packet includes `campaignRanking.options`, `sourcePlan`,
-  `nextActions`, and `manualAlternates`.
+  `refillReceipt`, `nextActions`, and `manualAlternates`.
+- `refillReceipt` is the public ladder receipt. It carries the selected
+  campaign/sender/lane summary, skipped rungs, existing-row frontier proof, and
+  any absolute `wait.deadlineAt`.
 - Preserve these coverage labels exactly: `Need to prepare`, `Goal`,
   `Already sent`, `Scheduled`, `Ready and waiting to be scheduled`, and
   `Still need`.
@@ -217,6 +223,13 @@ from the selected source (`selectedLeadListId`, provider, and source
 fingerprint preserved), then use provider-aligned source-more. A new source or
 provider switch changes the reply-rate baseline and is a manual alternate, not a
 `--yolo` side effect.
+Source/copy/fallback requires receipt-proven exhaustion of earlier rungs:
+`existingRowFrontier.hasMoreFrontierRows:false`, zero `approvalCandidates`, no
+fresh active prep, no `stuckActiveCells`, and no non-terminal
+`approvedNotDispatched` rows. Treat anomalies, `stuckActiveCells`, and
+non-terminal `approvedNotDispatched` as diagnose-and-report gates, not
+exhaustion. Terminal `approvedNotDispatched` blockers may be reported, then the
+ladder can proceed.
 
 Run-local paid-credit guard: in `--yolo`, the `refill_sends` MCP command
 automatically maintains a `refreshedPaidInmailSenderIds` set for the current
@@ -266,6 +279,10 @@ interval, until projected coverage fills the target, a concrete non-scheduler
 blocker appears, or Christian explicitly asks to stop or only receive a status
 report. Treat `awaiting_scheduler_after_ready_buffer` as an in-progress wait
 state, not a close-out condition.
+Wait actions are gates, not competing goals. When `wait_for_active_work` or
+`wait_for_scheduler` includes receipt `wait.deadlineAt`, honor that absolute
+deadline; if it is expired on this call, escalate to diagnostics with the
+receipt evidence instead of issuing another blind wait.
 If paid InMail credit facts are stale or missing and the first target plan
 contains `refresh_paid_inmail_credits`, do not present that as the operator's
 next action in `--yolo`. Do not present paid-credit refresh as the next operator