@floomhq/signaldash 0.27.0 → 0.28.0

package/README.md

@@ -52,7 +52,7 @@ npx -y @floomhq/signaldash connect linkedin claim <account_id>
 Paste this command into a terminal:
 
 ```bash
-claude mcp add signaldash -- npx -y @floomhq/signaldash mcp
+claude mcp add signaldash -s user -- npx -y @floomhq/signaldash mcp
 ```
 
 ### Cursor
@@ -91,7 +91,7 @@ flows. The one-command setup installs the skill from the same pinned npm package
 the human chose to execute:
 
 ```bash
-npx -y @floomhq/signaldash@0.27.0 <invite-code>
+npx -y @floomhq/signaldash@0.28.0 <invite-code>
 ```
 
 Run that command in a terminal, not in an agent chat. Do not ask an agent to
@@ -153,6 +153,9 @@ SignalDash exposes:
 - `li_set_scheduled_post_first_comment(id, first_comment, confirm)`
 - `li_scheduled_posts()`
 - `li_cancel_scheduled_post(id, confirm)`
+- `sd_schedule_message(channel, chat_id, text, scheduled_at, confirm)`
+- `sd_scheduled_messages(state?, channel?)`
+- `sd_cancel_scheduled_message(id, confirm)`
 
 Every operation runs through the hosted SignalDash backend. Agents never
 receive the Unipile access key.
@@ -171,6 +174,31 @@ every refusal names the exact rule and the exact file that tripped it. Nothing
 is ever truncated or dropped silently. LinkedIn messages carry text only, and
 `li_send_message` refuses an `attachments` argument instead of ignoring it.
 
+A recent read is no longer sufficient on its own. A message send re-reads the
+thread immediately before sending and refuses with `409 thread_changed` unless
+it is still the exact thread that was read, which is the guard LinkedIn has
+always had and WhatsApp did not: a 30-minute read window is satisfied just as
+comfortably by a conversation that moved 29 minutes ago as by one nobody has
+touched, and a reply that arrived in between is precisely when a draft stops
+being the right thing to send. The comparison is a hash over the page that was
+read, taken at the same item limit, so the re-read has to match message for
+message. A chat whose most recent read predates this guard carries no such hash
+and is refused with `428 read_before_send_required` until it is read again,
+rather than waved through on a timestamp that cannot answer the question. If the
+re-read itself fails, the send is refused with
+`502 thread_preflight_unavailable`: whether the thread changed is then unknown,
+and unknown is not permission. All three refusals happen before anything is
+reserved, so none of them costs send budget.
+
+A provider answer this process cannot read counts as a re-read that failed, not
+as an empty conversation. Only the two documented list envelopes are hashed;
+anything else yields no hash at all, so a read that hits a drifted shape records
+no authorization (the next send is refused at `428`) and a re-read that hits one
+refuses at `502` rather than being compared. That distinction is the whole
+guard: hashing an unrecognised answer to the hash of an empty thread would let a
+read and a re-read that had both seen nothing agree with each other and satisfy
+the requirement that a human looked at the conversation.
+
 A send is not idempotent, so an unconfirmed one is not silently retryable. If
 the provider times out, fails with a 5xx, or answers 2xx with a body that will
 not parse, the message may well have been delivered: SignalDash records the
@@ -205,6 +233,32 @@ uses the same sender binding, action ledger, duplicate guard, daily budget, and
 provider-warning lock as immediate publishing. An interrupted or ambiguous
 execution fails closed and is never retried automatically.
 
+`sd_schedule_message` puts one exact message into one exact chat at one exact
+time, on WhatsApp or LinkedIn, text only. It enqueues; it never sends. The
+attachment bytes a WhatsApp send accepts are refused here rather than held on
+disk for days. The worker sends,
+through `sendWhatsAppMessage` and through the LinkedIn preflight and write path,
+so a scheduled message clears every guard a live send clears, including the
+daily budget and the duplicate guard, at the moment it fires rather than at the
+moment it was written. Scheduling is refused with
+`428 read_before_send_required` unless this session has already read that exact
+chat, at `limit` 10 or more on LinkedIn, because the row has to carry a hash of
+the conversation it was written against. That hash is read from the recorded
+read and cannot be supplied by the caller: `watermark` and `item_limit` are
+refused by name rather than accepted and overwritten, since a caller that
+believes it set them believes something false. At fire time the worker re-reads
+the thread and compares. Anything other than "unchanged" parks the row in
+`needs_review` with a reason and sends nothing, because a conversation that
+moved is a question for a human and not a failure of the message.
+`sd_scheduled_messages` lists the caller's own rows with those reasons, and
+counts the `needs_review` ones outside whatever filter was asked for, so a
+filtered listing cannot hide a message waiting on a person.
+`sd_cancel_scheduled_message` cancels a row that has not fired.
+A row belonging to another account is refused in exactly the same words as an id
+that never existed, so the refusal cannot be used to prove somebody else's
+message is real. A row that already sent is refused with the plain statement
+that cancelling cannot unsend it.
+
 A campaign is one connection request per approved person, then the approved
 message once a fresh profile read proves that person accepted, then an optional
 follow-up that stops the moment they reply. A pending invitation that merely
@@ -356,6 +410,50 @@ resume exactly those. WhatsApp applies its own time and role limits to deleting
 for everyone and can answer successfully without removing anything, so re-read
 the chat to confirm.
 
+## Releasing
+
+A release is a tag push. `.github/workflows/release.yml` runs `./release.sh` on
+the AX41 self-hosted runner, and that script is the same one a laptop runs, so
+there is no second code path to keep honest:
+
+```bash
+git tag v0.28.0 && git push origin v0.28.0
+```
+
+`release.sh` refuses to publish if the packed files have uncommitted changes or
+if the version in `package.json` is already on the registry, then runs the
+syntax check, the tests, `npm pack`, and the prepublish smoke gate against the
+tarball it just built. That gate installs the tarball into a scratch HOME and
+drives the real CLI, so a package that unpacks but cannot run never ships. Any
+other branch or a `workflow_dispatch` run does all of that and stops one command
+short, at `./release.sh --dry-run`.
+
+**The credential is the `NPM_TOKEN` secret**, an npm granular access token
+scoped to `@floomhq/signaldash` with write access:
+
+```bash
+gh secret set NPM_TOKEN -R floomhq/signaldash
+```
+
+Trusted publishing (OIDC) is not an option here, so do not spend time on it:
+npm does not accept self-hosted runners yet, and this repo is on a self-hosted
+runner because GitHub-hosted minutes are unavailable. The workflow asks the
+registry directly on every run (`scripts/oidc-check.mjs`) and prints the answer,
+because npm's own OIDC helper is written never to throw and turns a refusal into
+an ordinary auth error.
+
+To exercise the publish itself without touching npmjs, run it against a
+throwaway registry:
+
+```bash
+scripts/publish-rehearsal.sh
+```
+
+That starts verdaccio in a container, mints an account on it, and runs the real
+`./release.sh` with no `--dry-run`, then prints what the registry received. It
+is the only way to test the publish command and the tarball a client actually
+downloads before a version number is spent.
+
 ## Development
 
 ```bash

package/bin/sd.mjs

@@ -11,6 +11,7 @@ import { homedir } from "node:os";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { readConfigFile, updateConfigFile } from "../lib/config-file.js";
+import { renderSkillTemplate } from "../lib/skill-template.cjs";
 
 // Lazy-load presentation deps so `mcp` (stdio, machine-facing) stays clean/fast.
 async function ui() {
@@ -20,6 +21,25 @@ async function ui() {
 }
 
 const DEFAULT_BACKEND = process.env.SIGNALDASH_BACKEND || "https://signaldash-api.floom.dev";
+// The shape of an invite code, deliberately a hand-kept copy of
+// INVITE_CODE_SHAPE in server/server.cjs rather than an import: server/ is
+// not in package.json's "files" allowlist, so it never ships in the
+// published npm tarball and bin/sd.mjs cannot depend on it at runtime. Two
+// copies of this shape can therefore never be textually merged into one;
+// test/invite-code-shortening.test.js requires server.cjs (test-only, not
+// shipped) to assert the CLI still accepts every code the live server
+// actually issues, which is the guarantee that matters here.
+//
+// The floor here (8 hex chars) is intentionally HIGHER than the server's
+// own floor (6): the server keeps 6 low for backward compatibility with
+// already-issued short codes it must still honor, but 6 hex chars is only
+// 24 bits of entropy for a value an attacker can brute-force against the
+// login endpoint, so the CLI does not need to (and should not) accept
+// anything shorter than the 32-bit floor this project has always minted
+// against. Every code production has ever issued is 10+ hex chars, or the
+// sd-XXXX-XXXX form below; the shape census is in
+// test/invite-code-shortening.test.js.
+export const INVITE_CODE_REGEX = /^(?:[0-9a-f]{8,32}|sd-[0-9a-f]{4}-[0-9a-f]{4})$/i;
 const PACKAGE_VERSION = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
 ).version;
@@ -87,13 +107,18 @@ export async function cmdLogin(code, backend, dependencies = {}) {
     { auth: false, backend: targetBackend },
   );
   if (r.status !== 200) {
+    // Previously any error whose text loosely matched /used|invalid|unknown/i
+    // was swallowed into "you are already set up" whenever a local token
+    // existed. That was never precise: the server's /login route treats a
+    // revoked code exactly like an unknown one on purpose (same 403, see
+    // server.cjs, so an attacker can't tell them apart), and it does NOT
+    // reject a code that was already redeemed -- re-running `login` with the
+    // SAME valid code succeeds with a fresh 200 token, it never reaches this
+    // branch. So a 403/other error here, even with a local token present,
+    // means the code just typed is wrong, expired, or revoked -- never "you
+    // already did this". Report it honestly instead of masking it as success.
     const msg = String(r.json.error || r.status);
-    if (/used|invalid/i.test(msg) && loadCfg().token) {
-      log("You are already set up on this machine. Run `signaldash status` to see what is connected.");
-      return;
-    }
     error("login failed:", msg);
-    if (/used/i.test(msg)) error("Invite codes are single-use. If you already ran this, try: signaldash status");
     process.exitCode = 1; return;
   }
   updateCfg(current => ({
@@ -106,6 +131,46 @@ export async function cmdLogin(code, backend, dependencies = {}) {
   log("machine, and are never exposed to your agent. Only you can see your data.");
 }
 
+// Store a session token you already hold. The /i/<code> page used to print
+// one as the final step of web onboarding and this command did not exist, so
+// people hit "unknown command" at the one point where they wire up their
+// agent. That page no longer hands out tokens at all (reopening it would have
+// traded a leaked invite code for someone else's live session), so the normal
+// way in is `login <code>`. This stays for a token handed over out of band.
+export async function cmdLoginToken(token, backend, dependencies = {}) {
+  const request = dependencies.request || api;
+  const log = dependencies.log || console.log;
+  const error = dependencies.error || console.error;
+  if (!token) {
+    error("usage: signaldash login-token <token>");
+    process.exitCode = 1; return;
+  }
+  const targetBackend = backend || loadCfg().backend || DEFAULT_BACKEND;
+  // Verify before persisting. A mistyped or expired token written to disk would
+  // fail later as a confusing "not connected" on every command instead of here.
+  const probe = await request(
+    "/connect/whatsapp/status",
+    undefined,
+    { method: "GET", backend: targetBackend, token },
+  );
+  if (probe.status === 401 || probe.status === 403) {
+    error("login failed: that token is not valid. It may have expired, or a newer login replaced it.");
+    process.exitCode = 1; return;
+  }
+  if (probe.status >= 400) {
+    error("login failed:", probe.json.error || probe.status);
+    process.exitCode = 1; return;
+  }
+  updateCfg(current => ({
+    ...current,
+    backend: targetBackend,
+    token,
+  }));
+  log(`Logged in to SignalDash (${targetBackend}).`);
+  log("Your LinkedIn/WhatsApp/email credentials live on that server, not on this");
+  log("machine, and are never exposed to your agent. Only you can see your data.");
+}
+
 export async function cmdLogout(dependencies = {}) {
   const request = dependencies.request || api;
   const log = dependencies.log || console.log;
@@ -947,7 +1012,7 @@ const TOOLS = [
     name: "wa_send_message",
     ch: "wa",
     action: "send",
-    description: "Send a WhatsApp message (rate-safe). args: chat_id, text, attachments. Read the chat first: a send into a thread this account has not read recently is refused. `attachments` optionally carries up to 4 base64 files as exact {filename, content_type, content_base64} objects, at most 16 MiB per file and 16 MiB per message, and accepts images, PDF, CSV, plain text, JSON, xlsx and zip. `text` is the caption and may be omitted when a file is attached, but a call carrying neither text nor an attachment is refused. An attachment send is rate-limited, deduplicated and recorded exactly like a text send, and spends the same daily budget. If a send times out or the provider never confirms it, the message may still have been delivered: SignalDash records it and refuses an identical retry with `409 send_outcome_unknown`. Read the chat, and only if the message is genuinely absent, resend the identical payload with `confirm_resend:true`.",
+    description: "Send a WhatsApp message (rate-safe). args: chat_id, text, attachments. Read the chat first: a send into a thread this account has not read recently is refused. The send re-reads the thread immediately before sending and refuses with `409 thread_changed` if the conversation moved after that read, because a draft written against the old thread may now be deaf or wrong; re-read, revise, and send again. A re-read that fails is `502 thread_preflight_unavailable` and nothing was sent. `attachments` optionally carries up to 4 base64 files as exact {filename, content_type, content_base64} objects, at most 16 MiB per file and 16 MiB per message, and accepts images, PDF, CSV, plain text, JSON, xlsx and zip. `text` is the caption and may be omitted when a file is attached, but a call carrying neither text nor an attachment is refused. An attachment send is rate-limited, deduplicated and recorded exactly like a text send, and spends the same daily budget. If a send times out or the provider never confirms it, the message may still have been delivered: SignalDash records it and refuses an identical retry with `409 send_outcome_unknown`. Read the chat, and only if the message is genuinely absent, resend the identical payload with `confirm_resend:true`.",
     inputSchema: {
       type: "object",
       properties: {
@@ -982,11 +1047,20 @@ const TOOLS = [
         confirm_resend: { type: "boolean", const: true },
       },
       // `text` alone is no longer required: a document with no caption is a
-      // legitimate message. `anyOf` states the real rule to any client that
-      // validates locally, and the backend refuses a call carrying neither
-      // regardless of whether the client checked.
+      // legitimate message.
+      //
+      // Die Regel stand hier bis zum 11.08. als `anyOf` auf oberster Ebene.
+      // Das hat das Werkzeug bei einem Client gekostet, der Schemata lokal
+      // kompiliert: er hat es kommentarlos aus seiner Liste geworfen. Ueber
+      // Tage war wa_send_message das EINZIGE der 45 Werkzeuge, das dort fehlte,
+      // und zugleich das einzige mit einem top-level anyOf. Der Server hat es
+      // die ganze Zeit ausgeliefert.
+      //
+      // Die Regel geht dadurch nicht verloren: das Backend weist einen Aufruf
+      // ohne Text und ohne Anhang ohnehin ab, unabhaengig davon, ob ein Client
+      // vorher geprueft hat. Sie steht in der Beschreibung, wo jeder Client sie
+      // lesen kann, statt in einem Konstrukt, an dem einer von ihnen erstickt.
       required: ["chat_id"],
-      anyOf: [{ required: ["text"] }, { required: ["attachments"] }],
       additionalProperties: false,
     },
   },
@@ -1033,10 +1107,18 @@ const TOOLS = [
   {
     name: "email_list",
     path: "/email/list",
-    description: "List the newest message from each recent email thread. args: limit",
+    description: "List the newest message from each recent email thread. args: limit, cursor",
     inputSchema: {
       type: "object",
-      properties: { limit: { type: "integer", minimum: 1, maximum: 100 } },
+      properties: {
+        limit: { type: "integer", minimum: 1, maximum: 100 },
+        cursor: {
+          type: "string",
+          minLength: 1,
+          maxLength: 4096,
+          description: "Fetch the next page. Use the cursor returned by a previous email_list.",
+        },
+      },
       additionalProperties: false,
     },
   },
@@ -1057,7 +1139,7 @@ const TOOLS = [
   {
     name: "email_send",
     path: "/email/send",
-    description: "Send one approved email after reading that recipient's thread. args: to, subject, body",
+    description: "Send one approved email after reading that recipient's thread. Pass thread_id from email_read to reply inside that thread rather than starting a new one. args: to, subject, body, thread_id",
     inputSchema: {
       type: "object",
       properties: {
@@ -1069,6 +1151,16 @@ const TOOLS = [
         },
         subject: { type: "string", minLength: 1, maxLength: 998 },
         body: { type: "string", minLength: 1, maxLength: 5000 },
+        thread_id: {
+          type: "string",
+          minLength: 1,
+          maxLength: 500,
+          description: "Reply inside this thread. Use the thread_id returned by email_read.",
+        },
+        confirm_resend: {
+          type: "boolean",
+          description: "Only after a send_outcome_unknown refusal, and only once you have read the thread again and confirmed the email is genuinely absent.",
+        },
       },
       required: ["to", "subject", "body"],
       additionalProperties: false,
@@ -1189,6 +1281,65 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
+  // sd_, not wa_ or li_, because these three carry `channel` and act on either
+  // one. The prefixes here are a claim about scope: wa_ and li_ tools reach
+  // exactly one network and their arguments say so, and every tool that spans
+  // both or belongs to SignalDash itself is sd_ already, from sd_contact_state
+  // through the sd_campaign_ and sd_withdrawal_batch_ families.
+  {
+    name: "sd_schedule_message",
+    path: "/sd/schedule_message",
+    description: "Schedule ONE exact message into ONE chat you have already read, on WhatsApp or LinkedIn. Read that exact chat first, at limit 10 or more on LinkedIn: SignalDash records what the thread looked like and refuses to send if the conversation moved before the scheduled time. Requires confirm:true after the human approves the exact channel, chat, text, and time. Text only, no attachments. This is not a follow-up sequence and there is no recurrence: one message, one time.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        channel: { type: "string", enum: ["whatsapp", "linkedin"] },
+        chat_id: { type: "string", minLength: 1, maxLength: 500 },
+        text: { type: "string", minLength: 1, maxLength: 5000 },
+        scheduled_at: { type: "string", format: "date-time" },
+        confirm: { type: "boolean", const: true },
+      },
+      required: ["channel", "chat_id", "text", "scheduled_at", "confirm"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "sd_scheduled_messages",
+    path: "/sd/scheduled_messages",
+    description: "List this authenticated user's scheduled messages and their durable states, optionally filtered by state or channel. Always reports needs_review_count outside that filter: a message in needs_review stopped at send time and is waiting on a human.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        state: {
+          type: "string",
+          enum: [
+            "scheduled",
+            "executing",
+            "sent",
+            "cancelled",
+            "failed",
+            "needs_review",
+          ],
+        },
+        channel: { type: "string", enum: ["whatsapp", "linkedin"] },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "sd_cancel_scheduled_message",
+    path: "/sd/cancel_scheduled_message",
+    description: "Cancel one exact scheduled message while it is still scheduled. Requires id and confirm:true. It cannot stop a message already being sent, and it cannot unsend one that has been sent.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", format: "uuid" },
+        confirm: { type: "boolean", const: true },
+      },
+      required: ["id", "confirm"],
+      additionalProperties: false,
+    },
+  },
 ];
 // No catch-all fallback. It advertised one union of keys for every tool that
 // had no schema of its own -- which is how `li_list_chats` came to offer `text`
@@ -1242,7 +1393,14 @@ export async function cmdSkill(dependencies = {}) {
   if (!ex(src)) { log("skill file not found in package"); process.exitCode = 1; return; }
   const dest = join(homedir(), ".claude", "skills", "signaldash");
   mk(dest, { recursive: true });
-  wf(join(dest, "SKILL.md"), rf(src, "utf8"));
+  // The template pins the bootstrap command to a version placeholder rather
+  // than a typed-in string: package.json is the only source of truth, so an
+  // installed skill can never advertise a stale published release. Rendered
+  // by the shared helper (lib/skill-template.cjs) so this substitution has a
+  // single source of truth shared with the public skill page and the
+  // server's own /skill and /skill.md routes.
+  const template = rf(src, "utf8");
+  wf(join(dest, "SKILL.md"), renderSkillTemplate(template, PACKAGE_VERSION));
   log(`Installed the SignalDash skill to ${dest}/SKILL.md`);
   log("Your agent now knows how to use LinkedIn + WhatsApp safely through SignalDash.");
 }
@@ -1266,7 +1424,7 @@ export async function cmdSetup(code, dependencies = {}) {
   log("  " + chalk.green("+") + " agent skill installed");
 
   try {
-    execSync("claude mcp add signaldash -- npx -y @floomhq/signaldash mcp", { stdio: "ignore" });
+    execSync("claude mcp add signaldash -s user -- npx -y @floomhq/signaldash mcp", { stdio: "ignore" });
     log("  " + chalk.green("+") + " MCP registered with Claude Code");
   } catch {
     log("  " + chalk.yellow("!") + " Claude Code not found. For Cursor, add to .cursor/mcp.json:");
@@ -1365,6 +1523,7 @@ function printHelp(log = console.log) {
   log(`SignalDash \u2014 secure LinkedIn, WhatsApp and email access for your AI agent.
 
   signaldash <invite-code>              set up everything in one go
+  signaldash login-token <token>        store a session token you were given
   signaldash status                     show what is connected
   signaldash connect linkedin|whatsapp|email
   signaldash connections [file.csv]     export your LinkedIn connections
@@ -1380,8 +1539,9 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
   const [cmd, a, b, c] = argv;
   const log = dependencies.log || console.log;
   if (cmd === "setup") await cmdSetup(a, dependencies);
-  else if (cmd && /^[0-9a-f]{8,}$/i.test(cmd) && !["login","logout","connect","mcp","skill"].includes(cmd)) await cmdSetup(cmd, dependencies);
+  else if (cmd && INVITE_CODE_REGEX.test(cmd) && !["login","logout","connect","mcp","skill"].includes(cmd)) await cmdSetup(cmd, dependencies);
   else if (cmd === "login") await cmdLogin(a, b === "--backend" ? c : undefined, dependencies);
+  else if (cmd === "login-token") await cmdLoginToken(a, b === "--backend" ? c : undefined, dependencies);
   else if (cmd === "logout") await cmdLogout(dependencies);
   else if (cmd === "connect" && b === "claim") await cmdClaim(a, c, dependencies);
   else if (cmd === "connect") await cmdConnect(a, dependencies);
@@ -1390,8 +1550,7 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
   else if (cmd === "connections" || (cmd === "export" && a === "connections")) await cmdConnections(cmd === "export" ? b : a, dependencies);
   else if (cmd === "--version" || cmd === "-v") log(PACKAGE_VERSION);
   else if (cmd === "skill") await cmdSkill(dependencies);
-  else if (cmd === "logout") await cmdLogout(dependencies);
-  else if (cmd && !["help","--help","-h"].includes(cmd) && !/^[0-9a-f]{8,}$/i.test(cmd)) { (dependencies.error || console.error)(`unknown command: ${cmd}`); printHelp(log); process.exitCode = 1; }
+  else if (cmd && !["help","--help","-h"].includes(cmd) && !INVITE_CODE_REGEX.test(cmd)) { (dependencies.error || console.error)(`unknown command: ${cmd}`); printHelp(log); process.exitCode = 1; }
   else printHelp(log);
 }
 

package/lib/cli.js

@@ -290,7 +290,7 @@ export async function connectCommand(channel, options, dependencies = {}) {
 }
 
 function registrationLine() {
-  return "Register: claude mcp add signaldash -- npx -y @floomhq/signaldash mcp | Cursor command: npx -y @floomhq/signaldash mcp";
+  return "Register: claude mcp add signaldash -s user -- npx -y @floomhq/signaldash mcp | Cursor command: npx -y @floomhq/signaldash mcp";
 }
 
 export async function mcpCommand(options, dependencies = {}) {

package/lib/skill-template.cjs

@@ -0,0 +1,32 @@
+'use strict';
+
+// Single source of truth for substituting the skill template's version
+// placeholder. Three call sites independently need this exact substitution:
+// `cmdSkill` in bin/sd.mjs (installs the skill into ~/.claude/skills), the
+// public signaldash.dev page renderer (ops/render-skill-page.mjs and
+// ops/render-skill-markdown.mjs), and the server's own /skill + /skill.md
+// routes (server/server.cjs). Before this file existed the substitution was
+// hand-duplicated in bin/sd.mjs and ops/render-skill-page.mjs, and the
+// server routes and ops/sync-public-skill.sh did not substitute at all --
+// which is how the publicly served skill ended up telling agents to run
+// `npx -y @floomhq/signaldash@{{PACKAGE_VERSION}} <invite-code>`, a command
+// that does not exist.
+//
+// .cjs so both ESM (bin/sd.mjs, ops/*.mjs, via Node's CJS/ESM interop) and
+// CommonJS (server/server.cjs) call sites can require/import it without a
+// build step or a second copy.
+
+const PACKAGE_VERSION_PLACEHOLDER = '{{PACKAGE_VERSION}}';
+
+function renderSkillTemplate(rawMarkdown, packageVersion) {
+  if (typeof rawMarkdown !== 'string') {
+    throw new TypeError('renderSkillTemplate: rawMarkdown must be a string');
+  }
+  if (typeof packageVersion !== 'string' || !packageVersion) {
+    throw new TypeError('renderSkillTemplate: packageVersion must be a non-empty string');
+  }
+  return rawMarkdown.split(PACKAGE_VERSION_PLACEHOLDER).join(packageVersion);
+}
+
+exports.renderSkillTemplate = renderSkillTemplate;
+exports.PACKAGE_VERSION_PLACEHOLDER = PACKAGE_VERSION_PLACEHOLDER;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/signaldash",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Secure LinkedIn, WhatsApp, and email access for AI agents",
   "type": "module",
   "bin": {
@@ -18,7 +18,7 @@
   },
   "scripts": {
     "test": "node --test",
-    "check": "node --check bin/sd.mjs && node --check server/server.cjs && node --check server/attachments.cjs && node --check server/write-control.cjs && node --check server/voice-profile.cjs && node --check server/campaign-store.cjs && node --check server/campaign-runner.cjs && node --check server/withdrawal-store.cjs && node --check server/post-scheduler.cjs && node --check bin/signaldash.js && node --check lib/cli.js && node --check lib/config-file.js && node --check lib/mcp.js && node --check lib/rate-guard.js && node --check lib/secrets.js && node --check lib/unipile.js"
+    "check": "node --check bin/sd.mjs && node --check server/server.cjs && node --check server/composio-email.cjs && node --check server/attachments.cjs && node --check server/write-control.cjs && node --check server/voice-profile.cjs && node --check server/campaign-store.cjs && node --check server/campaign-runner.cjs && node --check server/withdrawal-store.cjs && node --check server/post-scheduler.cjs && node --check server/message-scheduler.cjs && node --check bin/signaldash.js && node --check lib/cli.js && node --check lib/config-file.js && node --check lib/mcp.js && node --check lib/rate-guard.js && node --check lib/secrets.js && node --check lib/unipile.js"
   },
   "keywords": [
     "mcp",

package/skills/signaldash/SKILL.md

@@ -39,18 +39,20 @@ ask the human to review and run the pinned package bootstrap in their terminal.
 1. The human runs the currently published, pinned package:
 
    ```bash
-   npx -y @floomhq/signaldash@0.27.0 <invite-code>
+   npx -y @floomhq/signaldash@{{PACKAGE_VERSION}} <invite-code>
    ```
 
    This logs in, copies the package-bundled skill into Claude Code, registers
    the local MCP server, and starts the hosted account-connection flow.
 
-2. The installed skill lives in a directory that the current agent discovers.
-   Common locations are:
+2. The package writes the installed copy to the one location it supports
+   today:
 
    - Claude Code: `~/.claude/skills/signaldash/SKILL.md`
-   - Codex: `~/.codex/skills/signaldash/SKILL.md`
-   - Portable project scope: `.agents/skills/signaldash/SKILL.md`
+
+   Other clients (Codex, a portable `.agents/skills/` layout, etc.) are not
+   written automatically. Copy this same reviewed file into that client's own
+   skill directory by hand and reload skill discovery there.
 
 3. Confirm that the installed file begins with `name: signaldash` and contains the
    `Before every send` section. A partial copy is not installed.
@@ -63,7 +65,7 @@ ask the human to review and run the pinned package bootstrap in their terminal.
    account setup:
 
    ```bash
-   npx -y @floomhq/signaldash@0.27.0 skill
+   npx -y @floomhq/signaldash@{{PACKAGE_VERSION}} skill
    ```
 
    Expected success:
@@ -159,7 +161,7 @@ one, or reuse somebody else's code.
 After the user provides the code, run:
 
 ```bash
-npx -y @floomhq/signaldash <invite-code>
+npx -y @floomhq/signaldash@{{PACKAGE_VERSION}} <invite-code>
 ```
 
 The invite is a hexadecimal string. The command logs in, installs the bundled
@@ -374,12 +376,12 @@ Use the exact tool names and argument keys below. Limits are optional.
 | `wa_read_messages` | `chat_id` required; `limit` 1-100, default 30 | Verify a WhatsApp contact and recent history before summarizing, drafting, or sending. |
 | `wa_get_attachment` | `chat_id`, `message_id`, `attachment_id` all required, max 500 characters each | Download one attachment of one message in a chat this account owns. Read the chat first: the exact `message_id` and `attachment_id` come from `wa_read_messages`. Returns the stored path on the SignalDash host, mimetype, byte size and sha256. |
 | `wa_transcribe_voice` | `chat_id`, `message_id`, `attachment_id` all required, max 500 characters each; `backend` optional, exactly `gemini` or `whisper` | Turn one WhatsApp voice note into text through SignalDash instead of fetching provider bytes yourself. Always read the returned `backend`: `gemini` is the accurate default, `whisper-small` is the weak local fallback and mangles German with English terms mixed in, and a fallback also carries `fallback_reason`. Non-audio attachments are refused with `415 not_audio`; an unknown backend with `400 unknown_backend`; a transcription that exceeds its time limit returns `504 transcription_timeout` with the stored audio path. |
-| `wa_send_message` | `chat_id` required; `text` optional only when a file is attached, max 5000 characters; `attachments` optional array of up to 4 exact `{filename, content_type, content_base64}` files, at most 16 MiB per file and 16 MiB per message, types `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `application/pdf`, `text/csv`, `text/plain`, `application/json`, `application/zip`, xlsx | Send one approved reply, one approved file, or both, in an existing WhatsApp conversation after an immediate re-read. A file spends the same daily send budget and is recorded the same way as a text message; there is no separate attachment budget. A call carrying neither text nor an attachment is refused with `400 text_or_attachment_required`. Attachments are checked before anything is reserved, so a refusal costs no send: `400 unsupported_attachment_type`, `400 attachment_too_large`, `400 attachments_too_large`, `400 too_many_attachments`, `400 malformed_attachment_base64`, `400 invalid_attachment_filename`, and `413 request_too_large` when the whole body is too big to read. Nothing is ever truncated or dropped silently. The same caption with the same file is refused as `409 duplicate_send`; the same caption with a different file is a different message and goes through. If a send times out or the provider never confirms it, the message may still have been delivered: an identical retry is refused with `409 send_outcome_unknown`. Read the chat AGAIN, and ONLY if the message is genuinely absent, resend the identical payload with `confirm_resend:true`. The re-read is enforced, not advisory: a `confirm_resend` whose most recent read of that chat predates the failed attempt is refused with `428 reread_after_failed_send_required`, because a read taken before the attempt cannot show whether the message arrived. LinkedIn messages carry text only. |
+| `wa_send_message` | `chat_id` required; `text` optional only when a file is attached, max 5000 characters; `attachments` optional array of up to 4 exact `{filename, content_type, content_base64}` files, at most 16 MiB per file and 16 MiB per message, types `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `application/pdf`, `text/csv`, `text/plain`, `application/json`, `application/zip`, xlsx | Send one approved reply, one approved file, or both, in an existing WhatsApp conversation after an immediate re-read. A file spends the same daily send budget and is recorded the same way as a text message; there is no separate attachment budget. A call carrying neither text nor an attachment is refused with `400 text_or_attachment_required`. Attachments are checked before anything is reserved, so a refusal costs no send: `400 unsupported_attachment_type`, `400 attachment_too_large`, `400 attachments_too_large`, `400 too_many_attachments`, `400 malformed_attachment_base64`, `400 invalid_attachment_filename`, and `413 request_too_large` when the whole body is too big to read. Nothing is ever truncated or dropped silently. The same caption with the same file is refused as `409 duplicate_send`; the same caption with a different file is a different message and goes through. If a send times out or the provider never confirms it, the message may still have been delivered: an identical retry is refused with `409 send_outcome_unknown`. Read the chat AGAIN, and ONLY if the message is genuinely absent, resend the identical payload with `confirm_resend:true`. The re-read is enforced, not advisory: a `confirm_resend` whose most recent read of that chat predates the failed attempt is refused with `428 reread_after_failed_send_required`, because a read taken before the attempt cannot show whether the message arrived. The send also re-reads the thread immediately before sending and refuses with `409 thread_changed` if the conversation moved after the read that authorized it, or with `502 thread_preflight_unavailable` if that re-read fails; in both cases nothing was sent and no budget was spent. A chat whose most recent read predates thread-change detection is refused with `428 read_before_send_required` until it is read again. LinkedIn messages carry text only. |
 | `wa_delete_message` | `chat_id`, `message_id` both required, max 500 characters each | Retract one message THIS account sent, in a chat this account owns. The exact `message_id` comes from `wa_read_messages`. Irreversible and never retried: someone else's message is refused with `403 message_not_own`, a message outside this chat with `403 message_forbidden`, and a delete already recorded for this exact chat and message with `409 duplicate_delete`. Deletes spend their own daily budget, so `429 rate_limit_exceeded` here never means you are out of sends. WhatsApp applies its own time and role limits to deleting for everyone and can answer successfully without removing anything, so read the chat again to confirm the message is gone. |
 | `wa_delete_messages` | `messages` required array of 1-200 exact `{chat_id, message_id}` objects | Retract several messages this account sent. Same ownership, budget and audit path as `wa_delete_message`, executed strictly one at a time with a pause between them, never in parallel. Always read the per-entry `ok`, `code` and `error`: a partial result is normal. Entries the batch never reached before its time limit come back with `skipped:true` and `code:batch_deadline`, and were not attempted; resend exactly those to resume. |
-| `email_list` | `limit` integer 1-100, default 20 | List the newest message in each recent email thread and obtain `thread_id`. |
-| `email_read` | `thread_id` required; `limit` 1-100, default 30 | Read an email thread and authorize its exact participant addresses for a later send. |
-| `email_send` | `to` required as an array of exactly one valid address; `subject` required, max 998; `body` required, max 5000 | Send one approved email to a participant in a recently read existing thread. |
+| `email_list` | `limit` integer 1-100, default 20; `cursor` optional, max 4096 | List the newest message in each recent email thread and obtain `thread_id`. The response carries a `cursor`; pass it back to read the next page, and omit it for the first. |
+| `email_read` | `thread_id` required; `limit` 1-100, default 30 | Read an email thread and authorize its exact participant addresses for a later send. Everyone on `cc` counts as a participant, so a read authorizes them too. The newest messages are returned, not the oldest, so the people being replied to are always in the window. |
+| `email_send` | `to` required as an array of exactly one valid address; `subject` required, max 998, single line; `body` required, max 5000; `thread_id` optional, max 500 | Send one approved email to a participant in a recently read existing thread. Pass the `thread_id` you read to reply inside that thread; omit it only when starting a new one. A blank or oversized `thread_id` is refused with `400 invalid_request` rather than quietly starting a new thread beside the original. The same subject and body to the same person in the same thread is refused as `409 duplicate_send`; the same words in a different thread are a different message and go through. A subject containing a line break is refused with `400 invalid_request`, because a subject is one header line; a body with line breaks is normal and sends. If a send leaves this host and the provider never answers, the retry is refused as `409 send_outcome_unknown`: read the thread again, and only if the email is genuinely absent resend with `confirm_resend: true`. |
 | `li_my_posts` | `limit` default 10, max 50; `member_id` optional | Find the user's latest posts and post IDs. Omit `member_id` to use the connected user's own ID. |
 | `li_post_reactions` | `post_id` required; `limit` default 50, max 100 | Identify who reacted to one post and assess warm signals. A reaction does not authorize outreach. |
 | `li_post_comments` | `post_id` required; `limit` default 50, max 100 | Read comments and authors for one post; prioritize questions and substantive responses. |
@@ -387,6 +389,9 @@ Use the exact tool names and argument keys below. Limits are optional.
 | `li_set_scheduled_post_first_comment` | `id` required UUID; `first_comment` required, max 1250; `confirm:true` required | Attach one exact approved first comment to a scheduled post. SignalDash publishes it through the same connected account after the post and never republishes the post if the comment fails. |
 | `li_scheduled_posts` | no arguments | List only this authenticated user's scheduled LinkedIn posts and their durable states. |
 | `li_cancel_scheduled_post` | `id` required UUID; `confirm:true` required | Cancel one exact post while it is still scheduled. It cannot recall an executing or published post. |
+| `sd_schedule_message` | `channel` required, `whatsapp` or `linkedin`; `chat_id` required, max 500; `text` required, max 5000; `scheduled_at` required offset-qualified ISO date-time from 60 seconds to 365 days ahead; `confirm:true` required | Schedule one exact message into one chat you have already read. Read that exact chat first, at `limit` 10 or more on LinkedIn: SignalDash records what the thread looked like and refuses at send time if the conversation moved. Text only; attachments are refused rather than dropped. One message at one time, never a sequence. |
+| `sd_scheduled_messages` | `state` optional, one of `scheduled`, `executing`, `sent`, `cancelled`, `failed`, `needs_review`; `channel` optional | List only this authenticated user's scheduled messages and their durable states. Returns every matching row, unpaginated, and always reports `needs_review_count` outside your filter. |
+| `sd_cancel_scheduled_message` | `id` required UUID; `confirm:true` required | Cancel one exact message while its state is still `scheduled`. It cannot stop one already being sent, and it cannot unsend one that has been sent. |
 
 Representative calls:
 
@@ -430,7 +435,7 @@ wa_delete_message({"chat_id":"chat_wa_91b2","message_id":"msg_wa_5c71"})
 wa_delete_messages({"messages":[{"chat_id":"chat_wa_91b2","message_id":"msg_wa_5c71"},{"chat_id":"chat_wa_91b2","message_id":"msg_wa_5c72"}]})
 email_list({"limit":20})
 email_read({"thread_id":"thread_email_c402","limit":30})
-email_send({"to":["amina@example.com"],"subject":"Re: Case study","body":"Hi Amina,\n\nHere is the case study."})
+email_send({"to":["amina@example.com"],"subject":"Re: Case study","body":"Hi Amina,\n\nHere is the case study.","thread_id":"thread_email_c402"})
 li_my_posts({"limit":5})
 li_post_reactions({"post_id":"post_urn_8821","limit":50})
 li_post_comments({"post_id":"post_urn_8821","limit":50})
@@ -438,6 +443,10 @@ li_draft_post({"text":"Most agents need better context, not more autonomy."})
 li_set_scheduled_post_first_comment({"id":"00000000-0000-4000-8000-000000000000","first_comment":"https://github.com/xai-org/x-algorithm","confirm":true})
 li_scheduled_posts({})
 li_cancel_scheduled_post({"id":"00000000-0000-4000-8000-000000000000","confirm":true})
+sd_schedule_message({"channel":"whatsapp","chat_id":"chat_wa_91b2","text":"Following up on the Q3 numbers, as promised.","scheduled_at":"2026-08-19T09:00:00Z","confirm":true})
+sd_scheduled_messages({})
+sd_scheduled_messages({"state":"needs_review"})
+sd_cancel_scheduled_message({"id":"00000000-0000-4000-8000-000000000000","confirm":true})
 ```
 
 List and read success returns JSON with `items` and often a `cursor`. A message
@@ -565,6 +574,52 @@ this week, failed attempts today, remaining dedicated and shared capacity,
 `consecutive_errors`, `disabled_reason`, and every recent unparseable record.
 Never describe a disabled or erroring worker as active.
 
+### Scheduling one exact message
+
+`sd_schedule_message` holds one exact message for one exact future instant and
+sends it once. It is not a follow-up, a sequence, or a reminder that repeats.
+Schedule a message only when the user asked for that message at that time.
+
+A scheduled send is the only write in SignalDash that reaches a person with
+nobody watching, so it is guarded twice: once when you schedule it and once
+again at the moment it fires.
+
+At schedule time you must have read the exact chat, on LinkedIn at `limit` 10 or
+more. SignalDash records what that read returned. A message you cannot prove was
+written against a real, recent view of the conversation is refused now rather
+than accepted and quietly parked days later, while there is still a human in the
+room to hear about it. This is why `watermark` and `item_limit` are not
+arguments: they are read off the record of your own read, and a proof a caller
+could supply is not a proof.
+
+At fire time SignalDash re-reads the thread and compares it. If the conversation
+moved, the message is not sent. It goes to `needs_review` for a human instead,
+because a message written on Monday against Monday's conversation may be deaf or
+wrong by Thursday, and the person receiving it has no way to know it was written
+before their reply existed. Everything else the live send path checks still
+applies at that moment: chat ownership, contact suppression, the duplicate
+guard, and the daily send budget.
+
+`confirm:true` is required, and it means the human approved this exact channel,
+chat, text, and time. `scheduled_at` must carry `Z` or an explicit numeric UTC
+offset. SignalDash does not infer a timezone: it does not know which one you
+meant, and the cost of guessing wrong is a message arriving in the middle of
+somebody's night.
+
+Check `sd_scheduled_messages` after scheduling, and read `needs_review_count`
+every time even when you filtered it out. A row in `needs_review` stopped at
+send time and is waiting on a person; its `failure_detail` says what stopped it.
+For some of those rows whether the message reached the other person is genuinely
+unknown, and that is the answer to report, not a guess in either direction.
+
+`sd_cancel_scheduled_message` works only while the state is `scheduled`. It
+cannot stop a message that is already being sent, and it cannot unsend one that
+has been sent: that text is in the other person's chat and nothing here takes it
+back. If a sent message was wrong, say so in the chat. A cancel that names an id
+belonging to somebody else is refused in exactly the same words as an id that
+never existed, so a refusal never tells you whether another account's message is
+real.
+
 ### Post scheduling and campaign time boundary
 
 SignalDash supports an exact one-time future LinkedIn post through
@@ -579,10 +634,17 @@ never retried and never causes the post to be published again. Use
 requires a fresh list, the exact id, approval, and
 `confirm:true`; it works only while state is `scheduled`.
 
-SignalDash does not expose a general message scheduler. The first executable
-campaign scope has no user-selected future start date, recurring schedule,
-automatic follow-up, acceptance-triggered message, or multi-message
-("double text") sequence. Do not claim that any such action was queued.
+Everything SignalDash can schedule is one exact thing at one exact time:
+`li_draft_post` for a post, `sd_schedule_message` for a message. There is no
+recurring schedule, no automatic follow-up, no acceptance-triggered message and
+no multi-message ("double text") sequence anywhere in this tool set, and the
+first executable campaign scope has no user-selected future start date either.
+Do not claim that any such action was queued, and do not try to assemble one out
+of several scheduled messages into the same chat. That is not only forbidden, it
+does not work: the first message landing is itself a change to the conversation,
+so the second one, written against the thread as it was before, fails its
+fire-time freshness check and parks as `needs_review` for a human. You get one
+message sent and one waiting, which is worse than having scheduled nothing.
 
 The common server write authority enforces the design-approved time controls
 for every campaign action:
@@ -954,6 +1016,29 @@ and the command exits with failure.
 These controls run on the server. Prompt instructions, a new session, or a
 different calling order cannot bypass them.
 
+### 403 `channel_required`
+
+Meaning: this session has not yet completed its own QR scan, so it has no
+linked channel. An invite code proves an operator sent it to this person. It
+does not prove the person still controls a channel some earlier session
+linked, so a session that has not scanned cannot read stored data about the
+person or about third parties, and cannot change persistent settings. This
+covers `sd_contact_state`, `li_search_connections`, `sd_settings_set`, and
+every campaign and withdrawal-batch tool.
+
+Comply:
+
+1. Do not retry the tool and do not switch to another tool to read the same
+   data.
+2. Relay the personal setup link to the human and have them finish the QR
+   scan, exactly as in "First-time setup".
+3. Confirm with the status check in step 3 of that section, then retry.
+
+`sd_settings_get`, `sd_budget_status`, `sd_auto_accept_status`, and
+`sd_voice_profile` are deliberately not behind this guard: the first three are
+how you verify a live session during setup, and `sd_voice_profile` reports
+`<channel>_not_connected` instead.
+
 ### 428 `read_before_send_required`
 
 Meaning: this user has not successfully read the exact chat recently, or the
@@ -970,6 +1055,48 @@ Comply:
 
 Do not satisfy this guard by reading a different chat with a similar name.
 
+A LinkedIn or WhatsApp message send also returns this code when the most recent
+read of that chat predates thread-change detection and therefore carries no
+record of what the thread looked like. Read the chat again and send.
+
+`sd_schedule_message` returns it for the same reason and one more: a LinkedIn
+read of fewer than 10 messages is not recorded as proof at all, so reading that
+thread again at the same shallow depth returns this code again. Read at `limit`
+10 or more. The refusal names the depth and the window it enforced; read what it
+says rather than repeating the call. The check runs before the `confirm` gate,
+so you find out you have to read the chat before you ask anyone to approve a
+message you cannot yet schedule.
+
+### 409 `thread_changed`
+
+Meaning: the exact chat moved after the read that authorized the send. Both
+`li_send_message` and `wa_send_message` re-read the thread immediately before
+sending and refuse unless it is still the thread that was read. A read inside
+the 30-minute window is not enough on its own: a thread that changed 29 minutes
+ago satisfies the window and is still not the conversation the draft was
+written against.
+
+Comply:
+
+1. Do not resend the same text.
+2. Re-read the exact chat and read the new messages.
+3. Revise the draft against what the thread now says, and obtain approval again.
+4. Send once, promptly.
+
+A `502 thread_preflight_unavailable` on a send means that re-read itself failed,
+so whether the thread changed is unknown and nothing was sent. Retry the send
+later; do not treat it as a delivery. It also covers a re-read the provider
+answered successfully but in a shape SignalDash does not recognise, which is the
+same fact: no answer about whether the conversation moved. In that case a `428
+read_before_send_required` on the next attempt is expected too, because a read
+of an unrecognised shape records no authorization.
+
+Your own send moves the thread too, so two messages in a row are refused unless
+you read the chat between them. This is not a glitch to work around: the second
+message was drafted against a conversation that no longer exists, if only
+because the first message is now in it. Read, confirm the first message landed
+as intended, then send the second. If you meant one message, send one message.
+
 ### 409 `duplicate_send`
 
 Meaning: the exact message was already sent to that chat, or the exact email
@@ -1006,7 +1133,8 @@ claim that SignalDash has resolved a person across channels.
 
 ### 409 invitation and context preflight blocks
 
-`thread_changed`, `already_connected`, `existing_conversation`,
+`thread_changed` (also returned by a message send, see above),
+`already_connected`, `existing_conversation`,
 `conversation_state_incomplete`, `invitation_already_pending`,
 `inbound_invitation_pending`, `invitation_not_pending`,
 `invitation_state_incomplete`, and `relationship_unverified` mean the exact