@sellable/install 0.1.321 → 0.1.323

package/HERMES-SLACK-PROFILE-SCOPING.md

@@ -1,67 +1,169 @@
 # Hermes Slack Profile Scoping
 
-Sellable customer profiles use one dedicated native Slack app/token pair, one
-workspace-locked plain Sellable MCP, and one native Hermes s6 gateway. There is
-no shared dispatcher, route registry, listener fallback, or shared customer app
+Use this when creating or updating customer Hermes profiles that need Slack
+access.
+
+## Default Rule
+
+For Sellable-managed customer channels, use one dedicated Slack app/token pair
+per active Hermes customer profile. Run native `hermes -p <profile> gateway run`
+for that profile only. Do not run multiple active Hermes profile gateways
+against the same `SLACK_APP_TOKEN`.
+
+The customer's Slack app is bound to the exact Slack channel id and the
+customer's profile-local Sellable MCP config. Customer profiles must not store
+or read Sellable Admin MCP credentials, admin Slack app tokens, or sibling
+profile config.
+
+The shared dispatcher remains a fallback/research path only. Use it only when
+Sellable Admin explicitly owns one shared listener and route registry.
+
+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 production Sellable Reply Bot remains separate HTTP-interactivity product
-infrastructure. Keep Socket Mode off and keep its request URL at
-`https://app.sellable.dev/api/v2/slack/interactions`.
+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: each active customer profile needs its own native Slack
+app token pair unless Sellable Admin deliberately chooses the dispatcher
+fallback.
+
+## 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:
 
-## Public Boundary
+- 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.
 
-Customer onboarding is owned by the Sellable Admin native-app skill through one
-public command:
+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.
+
+## Profile Bootstrap Command
+
+Use the Sellable installer profile bootstrap:
 
 ```bash
-sellable-admin-install hermes customer bootstrap --mode <mode> [approved inputs]
+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
 ```
 
-The operator uses read-only `plan`, then approved `apply`, and later
-`resume|status|verify|rebuild|rollback` with the persisted `runId`. Do not ask
-the operator to coordinate the public Sellable installer, Slack API/CLI,
-cloud-browser, Gmail, profile, or gateway internals separately.
+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.
 
-The approval packet binds exact team/workspace/channel/profile/user identity,
-customer Sellable token-file ref, `gpt-5.6-sol`, redacted evidence root, and the
-exact tested Admin install/MCP and Sellable install/MCP candidates plus all four
-SHA-256 values.
+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.
 
-## Public Sellable Installer Role
+## Resulting Profile Env
 
-The Admin factory calls the pinned `@sellable/install` candidate internally and
-passes the pinned `@sellable/mcp` candidate through `--mcp-package`. The public
-installer writes profile-local Sellable config and Hermes MCP env with:
+For the dedicated customer Slack app model, 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.
+
+The profile's Hermes MCP env must also include the profile-local Sellable
+config, customer workspace lock, and fail-closed guard:
 
 ```yaml
-SELLABLE_CONFIG_PATH: /opt/data/profiles/<customerSlug>/sellable/config.json
-SELLABLE_CONFIGS_DIR: /opt/data/profiles/<customerSlug>/sellable/configs
-SELLABLE_LOCK_WORKSPACE_ID: <approvedWorkspaceId>
+SELLABLE_CONFIG_PATH: /srv/hermes/profiles/acme/sellable/config.json
+SELLABLE_CONFIGS_DIR: /srv/hermes/profiles/acme/sellable/configs
+SELLABLE_LOCK_WORKSPACE_ID: ws_acme
 SELLABLE_REQUIRE_WORKSPACE_LOCK: "1"
 ```
 
-It does not create Slack apps, handle Slack tokens, install Admin MCP, or choose
-the profile/workspace/channel from prompt text.
+`SELLABLE_REQUIRE_WORKSPACE_LOCK=1` means an unbound customer profile fails
+closed before making Sellable API calls instead of falling back to shared or
+admin config state. Only the `sellable-admin` profile should provision,
+inspect, or repair other profiles.
+
+For the shared dispatcher model, do not copy the shared `SLACK_BOT_TOKEN` or
+`SLACK_APP_TOKEN` into customer profile `.env` files. The dispatcher owns those
+tokens and route metadata decides the customer profile.
 
-## Customer Isolation
+## Shared Dispatcher Ownership
+
+The shared Slack dispatcher and its route registry are fallback Sellable Admin
+surfaces. This customer-facing installer must not create shared route bundles or
+write shared listener tokens. Sellable Admin owns Slack app creation and profile
+provisioning, then calls this installer for profile-local Sellable runtime
+bootstrap inside the already-provisioned Hermes profile.
+
+## Verification
+
+Run the installer and dispatcher 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
+scripts/run-phase031-hermes-slack-dispatcher-uat.sh --mode local-fixture
+```
 
-Customer profiles are blank-created. They contain:
+Expected proof:
 
-- dedicated profile-local Slack runtime secrets in mode-`0600` storage
-- exact channel and allowed-human ID allowlists
-- customer-safe manifest with no slash/App Home/assistant/DM/MPIM surfaces
-- the current `openai-codex` `gpt-5.6-sol` model object
-- Hermes root OAuth fallback from `/opt/data/auth.json`
-- pinned plain Sellable MCP locked to one approved workspace
-- one profile-specific native s6 gateway
+- 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
 
-They never contain customer-local `auth.json`, provider pools, OpenRouter/raw
-OpenAI keys, Sellable Admin MCP/admin skills, browser/Gmail/provisioning
-credentials, TOTP material, or sibling data.
+## Current Phase 03 Status
 
-Direct MCP proof before gateway start must show one intended active/visible
-workspace, `siblingInventoryFetched=false`, and no Admin MCP. Slack acceptance
-then requires real API/CLI, secret-file, s6 process, same-thread reply,
-negative-isolation, restart, rollback, rebuild, and redaction receipts tied to
-the immutable package hashes.
+Phase 03 proved the profile-scoped installer path, outbound Hermes send path,
+and live Slack listener for the `sellable-admin` profile. Phase 03.1 now targets
+dedicated native Slack apps per customer profile, profile-local Sellable MCP
+locks, and fail-closed customer profile behavior so managed customer channels
+can be onboarded through the VPS without local-only browser state, manual SSH
+edits, or untracked processes.

package/README.md

@@ -83,37 +83,120 @@ Auth is stored once at:
 ~/.sellable/config.json
 ```
 
-## Hermes Customer Profiles
+## Hermes Profile-Scoped Installs
 
-Customer onboarding is owned by the Sellable Admin native customer bootstrap:
+For a single local Hermes profile, point Sellable auth and memory at the profile
+instead of the global `~/.sellable/config.json`:
 
 ```bash
-sellable-admin-install hermes customer bootstrap --mode <mode> [approved inputs]
+profile="$HOME/.hermes/profiles/acme"
+sellable --host hermes \
+  --sellable-config-path "$profile/sellable/config.json" \
+  --sellable-configs-dir "$profile/sellable/configs"
 ```
 
-That command is the sole operator-facing interface. It calls the exact pinned
-`@sellable/install` tarball internally and passes the exact pinned
-`@sellable/mcp` tarball through `--mcp-package`. Do not ask an operator to run
-the public installer, supply Slack tokens in argv, edit profile files, or manage
-the gateway as separate onboarding steps.
+That writes `SELLABLE_CONFIG_PATH` and `SELLABLE_CONFIGS_DIR` into
+`mcp_servers.sellable.env`, so first-run login, `get_auth_status`, workspace
+switches, and Sellable memory all use the same profile-local files. Hosted MCP
+mode does not receive local filesystem paths.
 
-The internal profile stage writes profile-local Sellable paths and the exact
-workspace boundary:
+For zero-shot local or Hostinger/Linux VPS bootstrap, use the profile command:
 
-```yaml
-SELLABLE_CONFIG_PATH: /opt/data/profiles/<customerSlug>/sellable/config.json
-SELLABLE_CONFIGS_DIR: /opt/data/profiles/<customerSlug>/sellable/configs
-SELLABLE_LOCK_WORKSPACE_ID: <approvedWorkspaceId>
-SELLABLE_REQUIRE_WORKSPACE_LOCK: "1"
+```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 \
+  --json
+```
+
+It creates:
+
+```text
+/srv/hermes/profiles/acme/config.yaml
+/srv/hermes/profiles/acme/sellable/config.json
+/srv/hermes/profiles/acme/sellable/configs/
+/srv/hermes/profiles/acme/skills/sellable/
+/srv/hermes/profiles/acme/.env        # only when Slack token inputs are supplied
 ```
 
-The locked MCP requests only the approved workspace, blocks workspace switching
-and creation, and reports `siblingInventoryFetched=false`. The customer profile
-must contain no Admin MCP, admin token, customer-local OAuth, or sibling config.
+Bootstrap also writes `SELLABLE_LOCK_WORKSPACE_ID=<workspace-id>` and
+`SELLABLE_REQUIRE_WORKSPACE_LOCK=1` into the profile's Hermes MCP env.
+Customer profiles are therefore locked to their own Sellable workspace:
+Sellable MCP requests are forced to that workspace, workspace switching/creation
+is blocked, workspace listings are filtered, and a missing lock fails closed
+instead of falling back to shared/admin config. Use the `sellable-admin` profile
+for provisioning or cross-profile inspection.
 
 See [`HERMES-SLACK-PROFILE-SCOPING.md`](./HERMES-SLACK-PROFILE-SCOPING.md) for
-the dedicated native Slack app, root OAuth fallback, immutable package, s6
-gateway, rebuild, and live UAT contract.
+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
+launch. Finish auth with:
+
+```bash
+sellable auth set <token> --workspace-id <workspace_id> \
+  --sellable-config-path /srv/hermes/profiles/acme/sellable/config.json
+```
+
+Slack Socket Mode tokens can be written profile-locally:
+
+```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"
+```
+
+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
+Hermes profile config, restart the gateway/session or run `/reload-mcp` and
+`/reload-skills`.
+
+Validate the active profile with the same path inputs:
+
+```bash
+SELLABLE_CONFIG_PATH=/srv/hermes/profiles/acme/sellable/config.json \
+SELLABLE_CONFIGS_DIR=/srv/hermes/profiles/acme/sellable/configs \
+sellable --verify-only --host hermes --json \
+  --artifact /srv/hermes/profiles/acme/sellable/verify-runtime.json
+```
 
 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/`

package/bin/sellable-install.mjs

@@ -22,6 +22,14 @@ import {
   REQUIRED_SELLABLE_MCP_TOOLS,
   verifySellableMcpRuntime,
 } from "../lib/runtime-verify.mjs";
+import {
+  activateCodexCandidateSelection,
+  installCodexCandidateCache,
+  readCodexPluginSelection,
+  resolveCodexPluginSelectionPaths,
+  restoreCodexPluginSelection,
+  snapshotCodexPluginSelection,
+} from "../lib/codex-plugin-selection.mjs";
 
 const DEFAULT_API_URL = "https://app.sellable.dev";
 const DEFAULT_SERVER_PACKAGE =
@@ -40,7 +48,7 @@ function getInstallVersion() {
   }
 }
 
-const CODEX_PLUGIN_VERSION = "0.1.54";
+const CODEX_PLUGIN_VERSION = "0.1.56";
 const CODEX_PLUGIN_COMPAT_VERSIONS = [
   "0.1.8",
   "0.1.9",
@@ -79,6 +87,8 @@ const CODEX_PLUGIN_COMPAT_VERSIONS = [
   "0.1.51",
   "0.1.52",
   "0.1.53",
+  "0.1.54",
+  "0.1.55",
 ];
 const RAW_INSTALL_PACKAGE_SPEC =
   process.env.SELLABLE_INSTALL_PACKAGE_SPEC || "@sellable/install@latest";
@@ -170,6 +180,8 @@ Commands:
                            Save the ask-first prompt-sharing preference.
   setup claude-permissions --allow-common-setup
                            Add common Sellable Bash permissions to Claude settings.
+  codex plugin-selection snapshot|install-cache|activate|restore|status
+                           Approval-gated Phase 98 exact-cache selection controls.
   hermes profile bootstrap  Create a profile-local Hermes config, Sellable auth config,
                            configs dir, skills, and optional Slack .env.
   uninstall                Remove Sellable host config and installed artifacts.
@@ -213,19 +225,26 @@ Auth:
   also pass --sellable-config-path or set SELLABLE_CONFIG_PATH so auth and MCP
   runtime use the same profile-local config file.
 
-Hermes customer profile stage:
-  Managed customer onboarding uses only:
-  sellable-admin-install hermes customer bootstrap --mode <mode> [approved inputs]
-
-  The Admin state machine invokes this package's profile bootstrap internally
-  with exact token-file, workspace-lock, profile-root, and --mcp-package inputs.
-  Operators must not use the low-level profile command to coordinate Slack,
-  profile, or gateway onboarding manually. Customer profiles use root Codex
-  OAuth fallback and contain no local auth.json, provider pool, or Admin MCP.
-
-Hermes customer Slack runtime:
-  Each customer profile uses its own dedicated native Slack app and gateway.
-  Sellable Admin owns the single resumable customer bootstrap interface.
+Hermes profile bootstrap:
+  sellable hermes profile bootstrap --profile acme --profiles-root /srv/hermes/profiles --workspace-id ws_acme --token-file /run/secrets/sellable-token --json
+  sellable hermes profile bootstrap --profile-root "$HOME/.hermes/profiles/acme" --workspace-id ws_acme --json
+
+  Bootstrap writes <profileRoot>/config.yaml, <profileRoot>/sellable/config.json,
+  <profileRoot>/sellable/configs, Sellable Hermes skills, and optional
+  <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 credentials and customer-scoped Slack credentials for
+  customer profiles; shared admin tokens are weaker isolation and should remain
+  internal-only. Bootstrap writes SELLABLE_REQUIRE_WORKSPACE_LOCK=1 whenever a
+  workspace id is supplied, so a customer profile fails closed if the workspace
+  lock is later removed or not yet provisioned.
+
+Hermes shared Slack dispatcher:
+  Shared listener setup and route-registry validation are internal Sellable
+  Admin responsibilities. This customer-facing installer only bootstraps a
+  profile-local Sellable runtime after Sellable Admin provisions the profile
+  and dispatcher route.
 `;
 }
 
@@ -2031,6 +2050,20 @@ then retry \`get_subskill_prompt\`.
 `, host, "create-evergreen-campaigns");
 }
 
+const REFILL_SENDS_FALLBACK_CONTRACT = `<!-- REFILL_CONTRACT_GENERATED:START -->
+contractVersion: 2.0.0
+cacheVersion: refill-contract-v1
+contractHash: e54ba0f80bc534fd70fd8c10c1caab109fe9a91c205cfc423f5f6735cd53fdc1
+scope: workspace_id, target_date, sender_selectors, campaign_selectors, approval_mode, contract_identity, installed_identity
+gates: approval_packet, one_primitive, fresh_reread, normalized_accounting, prep_circuit
+forbidden: direct_send, raw_scheduler_write, campaign_create, campaign_archive_delete, threshold_lowering, unselected_source_mutation, unapproved_campaign_start, sender_config_write
+terminal: projected_full, concrete_blocker, deadline_reached, iteration_limit, operator_stopped
+ready_buffer_exists_is_not_complete
+mcpPackageVersion: installed MCP package spec in host MCP config
+installPackageVersion: ${getInstallVersion()}
+codexPluginVersion: ${CODEX_PLUGIN_VERSION}
+<!-- REFILL_CONTRACT_GENERATED:END -->`;
+
 function refillSendsSkillMd(host = "shared") {
   try {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -2040,7 +2073,10 @@ function refillSendsSkillMd(host = "shared") {
       "skill-templates",
       "refill-sends.md"
     );
-    if (existsSync(templatePath)) {
+    if (
+      process.env.SELLABLE_FORCE_REFILL_TEMPLATE_MISSING !== "1" &&
+      existsSync(templatePath)
+    ) {
       return stampInstalledHost(
         addOrReplaceAllowedTools(
           readFileSync(templatePath, "utf8"),
@@ -2063,6 +2099,14 @@ ${allowedToolsYaml(REFILL_SENDS_ALLOWED_TOOLS)}
 
 # Sellable Refill Sends
 
+${REFILL_SENDS_FALLBACK_CONTRACT}
+
+fallbackSource: embedded
+
+Load \`refill-sends-workflow\`, then \`core/flow.v1.json\`, then
+\`core/contract.v2.json\`, each through the Sellable MCP prompt tools until
+\`hasMore:false\`. Fail closed on unsupported major or stale contract hash.
+
 Use this as the customer-facing entrypoint for the Sellable \`refill-sends\`
 workflow. It supports \`--yolo\` and optional repeated \`--sender <name-or-id>\`
 selectors. It also supports \`--target-date YYYY-MM-DD\` to fill one exact
@@ -2092,9 +2136,9 @@ Desktop, then start a new thread.
 
 1. Call \`mcp__sellable__get_auth_status({})\`.
 2. Resolve the target workspace id from the user request, automation config, or install-time workspace mapping. Pass \`workspaceId\` on every scheduled or \`--yolo\` refill tool call. Missing \`workspaceId\` in scheduled or \`--yolo\` mode is a blocker; return \`WORKSPACE_REQUIRED\` instead of running against shared config state. Do not solve automation workspace uncertainty by changing the shared active workspace.
-3. Normalize invocation arguments with \`mcp__sellable__refill_sends({ yolo, executionMode, requireWorkspace, workspaceId, senders, senderIds, senderNames, targetDate, untilDate })\` when the host exposes typed MCP tools. Type shape: \`refill_sends({ yolo?: boolean, executionMode?: "manual" | "scheduled" | "yolo", requireWorkspace?: boolean, workspaceId?: string, senders?: string[], senderIds?: string[], senderNames?: string[], horizonSendDays?: number, untilDate?: "YYYY-MM-DD", targetDate?: "YYYY-MM-DD" })\`.
+3. Normalize invocation arguments with \`mcp__sellable__refill_sends({ yolo, executionMode, requireWorkspace, workspaceId, senders, senderIds, senderNames, actionTypes, targetDate, untilDate })\` when the host exposes typed MCP tools. Type shape: \`refill_sends({ yolo?: boolean, executionMode?: "manual" | "scheduled" | "yolo", requireWorkspace?: boolean, workspaceId?: string, senders?: string[], senderIds?: string[], senderNames?: string[], actionTypes?: ("send_invite" | "send_inmail_closed")[], horizonSendDays?: number, untilDate?: "YYYY-MM-DD", targetDate?: "YYYY-MM-DD" })\`.
 4. Clover scheduled automation example: \`mcp__sellable__refill_sends({ yolo:false, executionMode:"scheduled", requireWorkspace:true, workspaceId:"cmlq1v8ms0000jx04ang4hi7e" })\`, then \`mcp__sellable__get_refill_target_plan({ intent:"plain", approvalMode:"mark_ready", workspaceId:"cmlq1v8ms0000jx04ang4hi7e" })\`.
-5. Call \`mcp__sellable__get_refill_target_plan({ workspaceId, senders, senderIds, senderNames, targetDate, untilDate })\` before any mutation. Render \`target.eligibleSenderLedger\`, \`target.senderRefillPlans[]\`, and \`target.globalActionQueue\` as the structured packet. Preserve the labels \`Need to prepare\`, \`Goal\`, \`Already sent\`, \`Scheduled\`, \`Ready and waiting to be scheduled\`, and \`Still need\`. In \`--yolo\`, \`mcp__sellable__refill_sends\` maintains a run-local \`refreshedPaidInmailSenderIds\` set, refreshes stale/missing paid InMail facts for each selected paid-InMail sender at most once, reruns \`get_refill_target_plan\`, and returns \`autoPaidInmailRefresh\` plus the post-refresh \`targetPlan\` before choosing the next prep/source-copy/bounded-approval/read-only wait action. Refill ladder: approve generated rows only through the explicit bounded approval gate, process existing same-campaign unenriched/unprepared rows before source work, then same-source copy, then provider-aligned source-more. New source/provider switches change reply-rate baseline and are manual alternates, not \`--yolo\` side effects. Do not present paid-credit refresh as the next operator action after \`refill_sends\` returns that post-refresh plan. For exact-date proof, \`mcp__sellable__get_scheduler_fill_capacity\` is read-only and tells how many cells the scheduler will try to place for a sender/action/date. When ready rows cover the target but scheduled rows do not, \`mcp__sellable__run_scheduler_sweep({ workspaceId, action:"run" })\` may request immediate placement within existing gates and returns a receipt, but it never sends or bypasses limits. If the returned target is already complete, stop with the no-op receipt. If ready rows cover the target but scheduled rows do not, keep the run open in the read-only scheduler wait/re-read loop until projected coverage fills, a concrete non-scheduler blocker appears, or Christian explicitly stops/statuses the run.
+5. Call \`mcp__sellable__get_refill_target_plan({ workspaceId, senders, senderIds, senderNames, actionTypes, targetDate, untilDate })\` before any mutation. Render \`target.eligibleSenderLedger\`, \`target.senderRefillPlans[]\`, and \`target.globalActionQueue\` as the structured packet. Preserve the labels \`Need to prepare\`, \`Goal\`, \`Already sent\`, \`Scheduled\`, \`Ready and waiting to be scheduled\`, and \`Still need\`. In \`--yolo\`, \`mcp__sellable__refill_sends\` maintains a run-local \`refreshedPaidInmailSenderIds\` set, refreshes stale/missing paid InMail facts for each selected paid-InMail sender at most once, reruns \`get_refill_target_plan\`, and returns \`autoPaidInmailRefresh\` plus the post-refresh \`targetPlan\` before choosing the next prep/source-copy/bounded-approval/read-only wait or exact-date sweep action. Refill ladder: approve generated rows only through the explicit bounded approval gate, process existing same-campaign unenriched/unprepared rows before source work, then same-source copy, then provider-aligned source-more. New source/provider switches change reply-rate baseline and are manual alternates, not \`--yolo\` side effects. Do not present paid-credit refresh as the next operator action after \`refill_sends\` returns that post-refresh plan. For exact-date proof, \`mcp__sellable__get_scheduler_fill_capacity\` is read-only and tells how many cells the scheduler will try to place for a sender/action/date. When the planner returns a request-scoped exact-date scheduler sweep, execute \`mcp__sellable__run_scheduler_sweep({ workspaceId, action:"run", targetDate, requestKey, targetShapeRevision })\` once, capture its receipt, and fully reread before another action. It may schedule eligible workspace cells through existing gates, but it never sends directly or bypasses limits. If the returned target is already complete, stop with the no-op receipt. Only non-exact or no-sweep waits use the read-only scheduler wait/re-read loop until projected coverage fills, a concrete non-scheduler blocker appears, or Christian explicitly stops/statuses the run.
 6. Load the canonical prompt and deterministic flow asset via
    \`mcp__sellable__get_subskill_prompt({ subskillName: "refill-sends" })\`,
    then load \`mcp__sellable__get_subskill_prompt({ subskillName: "refill-sends-workflow" })\`,
@@ -2105,8 +2149,7 @@ Desktop, then start a new thread.
    facts are present, refresh exact selected sender facts once, rerun
    \`get_refill_target_plan\`, and only then enter \`wait_for_scheduler\` if
    freshness is clean.
-7. Follow the canonical prompt exactly. Do not launch, start, archive, delete,
-   or write scheduler rows as part of refill sends.
+7. Follow the canonical prompt exactly. Do not directly send, bypass scheduler gates, or raw-write scheduler fields. Only the exact rendered paused-campaign start and request-scoped scheduler sweep may use their existing product-gated paths; do not launch, archive, or delete unrelated work.
 
 ## MCP Prompt Fallback
 
@@ -5807,6 +5850,73 @@ async function main() {
       printCreateCommandHint();
       process.exit(0);
     }
+    if (rawArgs[0] === "codex" && rawArgs[1] === "plugin-selection") {
+      const command = rawArgs[2];
+      const flags = new Map();
+      for (let index = 3; index < rawArgs.length; index += 2) {
+        const flag = rawArgs[index];
+        const value = rawArgs[index + 1];
+        if (!flag?.startsWith("--") || !value || value.startsWith("--")) {
+          throw new Error(`Invalid Codex plugin-selection option: ${flag ?? "<missing>"}`);
+        }
+        flags.set(flag, value);
+      }
+      const required = (name) => {
+        const value = flags.get(name);
+        if (!value) throw new Error(`Missing value for ${name}`);
+        return value;
+      };
+      const paths = resolveCodexPluginSelectionPaths({ home: homedir() });
+      let result;
+      if (command === "status") {
+        result = readCodexPluginSelection({ paths, stableVersion: flags.get("--stable-version") });
+      } else if (command === "snapshot") {
+        result = snapshotCodexPluginSelection({
+          paths,
+          snapshotRoot: required("--snapshot-root"),
+        });
+      } else if (command === "install-cache") {
+        result = installCodexCandidateCache({
+          paths,
+          sourcePluginRoot: required("--source"),
+          version: required("--version"),
+        });
+      } else if (command === "activate") {
+        result = activateCodexCandidateSelection({
+          paths,
+          snapshotManifestPath: required("--snapshot"),
+          expectedSnapshotHash: required("--snapshot-hash"),
+          candidateVersion: required("--candidate-version"),
+          expectedCandidateHash: required("--candidate-hash"),
+          approvalId: required("--approval-id"),
+          approvedAt: required("--approved-at"),
+          restoreBy: required("--restore-by"),
+          now: required("--now"),
+        });
+      } else if (command === "restore") {
+        result = restoreCodexPluginSelection({
+          paths,
+          snapshotManifestPath: required("--snapshot"),
+          expectedSnapshotHash: required("--snapshot-hash"),
+          activationPath: required("--activation"),
+          now: required("--now"),
+          recoveryReason: flags.get("--recovery-reason") || undefined,
+          taskEvidence:
+            flags.has("--task-id") && flags.has("--resolved-candidate-hash")
+              ? {
+                  taskId: flags.get("--task-id"),
+                  resolvedCandidateHash: flags.get("--resolved-candidate-hash"),
+                }
+              : undefined,
+        });
+      } else {
+        throw new Error(
+          "Usage: sellable codex plugin-selection snapshot|install-cache|activate|restore|status"
+        );
+      }
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(0);
+    }
     if (
       rawArgs[0] === "hermes" &&
       rawArgs[1] === "profile" &&