@floomhq/signaldash 0.39.0 → 0.39.2

package/README.md

@@ -91,6 +91,24 @@ The MCP server uses the user token created by `login`. It cannot access a
 LinkedIn, WhatsApp, or email account until that channel has been connected for
 the same logged-in user.
 
+## Without an MCP client
+
+If the agent session cannot load the MCP tools (server connected, tools not
+in the roster) the CLI reaches the exact same tool catalog through the exact
+same backend routes and guards, no MCP transport required:
+
+```bash
+npx -y @floomhq/signaldash tools                          # full catalog: name, description, inputSchema
+npx -y @floomhq/signaldash call li_list_chats '{"limit":5}'  # dispatch one tool directly
+```
+
+`call` prints one JSON line to stdout and exits `0` on an HTTP 2xx, `1`
+otherwise (including local argument validation failures, which never reach
+the backend). It is not a fallback that skips anything: it is the same
+dispatcher the MCP `tools/call` handler uses, so the write-control ledger,
+per-account budgets, read-before-send, pacing, provider-warning lock, and
+audit trail all run identically.
+
 ## Operating skill distribution
 
 The canonical [`signaldash` skill](skills/signaldash/SKILL.md) teaches an agent
@@ -102,7 +120,7 @@ setup installs both from the same pinned npm package
 the human chose to execute:
 
 ```bash
-npx -y @floomhq/signaldash@0.39.0 <invite-code>
+npx -y @floomhq/signaldash@0.39.2 <invite-code>
 ```
 
 Run that command in a terminal, not in an agent chat. Do not ask an agent to
@@ -173,14 +191,15 @@ SignalDash exposes:
 - `email_send(to, subject, body)`
 - `li_my_posts(limit, member_id)`
 - `li_post_reactions(post_id, limit, cursor?)`
-- `li_post_comments(post_id, comment_id?, limit, cursor?)`
+- `li_post_comments(post_id, comment_id?, resolve_reply_state?, limit, cursor?)`
 - `li_reply_to_comment(post_id?, parent_comment_id?, trigger_comment_id?, text?, expected_watermark?, secretary_receipt_id?)`
 - `li_like_comment(post_id, parent_comment_id, comment_id, expected_watermark?)`
 - `li_delete_message(chat_id, message_id, confirm)`
 - `li_delete_comment(post_id, comment_id, confirm)`
-- `li_draft_post(text, publish, scheduled_at?, mentions?, attachments?, first_comment?)`
+- `li_draft_post(text, publish, scheduled_at?, content_pipeline_id?, content_pipeline_override?, mentions?, attachments?, first_comment?)`
 - `li_set_scheduled_post_first_comment(id, first_comment, confirm)`
 - `li_scheduled_posts()`
+- `li_scheduled_post_preview(id)`
 - `li_cancel_scheduled_post(id, confirm)`
 - `sd_schedule_message(channel, chat_id, text, scheduled_at, confirm)`
 - `sd_scheduled_messages(state?, channel?)`
@@ -189,6 +208,16 @@ SignalDash exposes:
 Every operation runs through the hosted SignalDash backend. Agents never
 receive the Unipile access key.
 
+When a user's content pipeline is enabled, a future post normally requires its
+exact approved `content_pipeline_id`. A deliberate exception uses
+`content_pipeline_override:{reason}` on the preview call, then repeats the
+identical post, time, mentions, image bytes, first comment, and reason with
+`confirm:true` plus the returned single-use `approval_hash`. The override never
+disables the pipeline. Its reason, preview identity, and approval time are
+stored atomically with the scheduled post and returned by
+`li_scheduled_posts`. Override-approved payloads are immutable; their first
+comment cannot be changed after scheduling.
+
 `li_start_chat` and `wa_start_chat` are separate tools because LinkedIn and
 WhatsApp expose different stable member-ID formats and spend different budget
 lanes. Both use the same safety contract. A first call previews 1 to 10 exact
@@ -227,6 +256,30 @@ readback. `sd_secretary_push_set` is the database kill switch; enabling starts
 from that instant so old rows do not create a backlog. The self-chat is never a
 fallback.
 
+A top-level `li_post_comments` page reports each comment's `reply_counter` but
+no reply objects, which left "did I already answer this?" unanswerable and kept
+the comment loop switched off. `resolve_reply_state:true` reads each comment's
+reply thread and attaches a `reply_state`. Presence and absence are proved to
+different standards on purpose. Seeing an own reply proves `replied_by_me:true`
+whatever the page's completeness, because presence on an incomplete page is
+still presence. `replied_by_me:false` is emitted only when the reply set is
+provably whole, every reply carries a resolvable `author_details.id`, ids are
+unique, every reply belongs to this thread, and no reply is the account
+owner's. Two proofs are accepted: the provider reporting the reply page
+complete, or a zero `reply_counter` together with a reply read that came back
+empty, which is the same pair the reply preflight already requires.
+`replies_read === reply_counter` is deliberately NOT a proof; both numbers are
+returned so a caller can see the corroboration, but SignalDash will not convert
+it into a boolean, because a wrong `false` makes an agent talk over the account
+owner in public. Everything else is `replied_by_me:null` with an explicit
+reason. The flag is off by default and unresolved comments still carry
+`reply_state.state = "unknown"`, so a miss is never mistaken for a proven
+absence. Resolution is bounded per request by
+`SIGNALDASH_REPLY_STATE_MAX_READS` (default 25); that bound is not a daily read
+cap and does not claim to be one. A provider warning, 403 or 429 stops the
+sweep at once and the whole call returns non-2xx carrying the partial evidence,
+so a safety condition is never downgraded into a 200.
+
 `li_reply_to_comment` acts only on an inbound comment on the authenticated
 sender's own post. A preceding `li_post_comments` read records an exact
 per-comment watermark. Immediately before the write, SignalDash re-proves the
@@ -335,6 +388,12 @@ linkedin.com to fill the gap. An empty item list therefore means only that the
 visible SignalDash and Buffer sources are empty, never that the native LinkedIn
 calendar is empty.
 
+`li_scheduled_post_preview` returns a short-lived, single-use browser handoff
+for one exact active SignalDash post owned by the authenticated user. The page
+shows only that post, including its stored image attachments. Preview sessions
+and media routes remain account- and post-scoped, expire independently, and
+are revoked on logout.
+
 `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
@@ -519,8 +578,11 @@ entries strictly one at a time, pauses `SIGNALDASH_WA_DELETE_PACE_MS` between
 them, and stops at `SIGNALDASH_WA_DELETE_BATCH_DEADLINE_MS`, returning the
 untouched remainder as `skipped` with `code: batch_deadline` so the caller can
 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.
+for everyone and can answer successfully without removing anything. SignalDash
+therefore re-reads the canonical provider message and returns success only when
+`deleted: 1` or a genuine `404` proves it gone. A present row or failed
+readback returns `502 deleted_unconfirmed`, records an unknown outcome, and is
+not retryable.
 
 ## Deploying server changes
 

package/bin/sd.mjs

@@ -59,7 +59,37 @@ function updateCfg(update) {
   return updateConfigFile(configPaths().file, update);
 }
 
-async function api(
+function fallbackApiError(response) {
+  const header = name => response.headers?.get?.(name) || null;
+  const declaredCode = header("x-signaldash-error-code");
+  const upstreamStatusHeader = header("x-signaldash-upstream-status");
+  const declaredUpstreamStatus = upstreamStatusHeader === null
+    ? null
+    : Number(upstreamStatusHeader);
+  const requestId = header("x-signaldash-request-id");
+  const upstreamStatus = Number.isInteger(declaredUpstreamStatus)
+    ? declaredUpstreamStatus
+    : null;
+  const messages = {
+    upstream_authentication_failed:
+      "Messaging provider authentication is unavailable.",
+    outcome_unknown:
+      "The provider outcome is unknown. Read the exact thread before any retry.",
+  };
+  const code = declaredCode || "backend_error_response_unreadable";
+  return {
+    error: messages[code]
+      || "SignalDash returned an unreadable error response. The action outcome is unknown; read the exact thread before any retry.",
+    code,
+    http_status: response.status,
+    ...(upstreamStatus !== null ? { upstream_status: upstreamStatus } : {}),
+    ...(requestId ? { request_id: requestId } : {}),
+    retryable: false,
+    ...(declaredCode ? {} : { outcome_unknown: true }),
+  };
+}
+
+export async function api(
   path,
   body,
   { auth = true, method = "POST", backend, token } = {},
@@ -75,7 +105,26 @@ async function api(
     },
     ...(method === "GET" ? {} : { body: JSON.stringify(body || {}) }),
   });
-  const json = await r.json().catch(() => ({}));
+  let json = await r.json().catch(() => null);
+  if (
+    r.status >= 300 &&
+    (
+      !json ||
+      typeof json !== "object" ||
+      Array.isArray(json) ||
+      Object.keys(json).length === 0
+    )
+  ) {
+    // An intermediary can discard or replace a backend error body. Returning
+    // `{}` here erased the only facts an MCP caller can use to distinguish a
+    // definite provider rejection from a send whose delivery is unknown.
+    // The backend repeats its safe classification in headers; when even those
+    // are absent, fail closed as outcome-unknown rather than imply a clean
+    // failure that an agent may retry into a duplicate.
+    json = fallbackApiError(r);
+  } else if (json === null) {
+    json = {};
+  }
   if (
     json &&
     typeof json === "object" &&
@@ -1350,7 +1399,7 @@ const TOOLS = [
   {
     name: "wa_delete_message",
     path: "/wa/delete_message",
-    description: "Delete one WhatsApp message this account SENT, in a chat this account owns. Read the chat first: the exact `message_id` comes from `wa_read_messages`. Only your own messages can be deleted; someone else's is refused with `403 message_not_own`. This is irreversible and is never retried: a delete already recorded for this exact chat and message is refused with `409 duplicate_delete` rather than replayed. WhatsApp applies its own time and role limits to deleting for everyone and can answer successfully without removing anything, so re-read the chat afterwards to confirm. Deletes spend their own daily budget and never consume your send budget.",
+    description: "Delete one WhatsApp message this account SENT, in a chat this account owns. Read the chat first: the exact `message_id` comes from `wa_read_messages`. Only your own messages can be deleted; someone else's is refused with `403 message_not_own`. This is irreversible and is never retried: a delete already recorded for this exact chat and message is refused with `409 duplicate_delete` rather than replayed. SignalDash re-reads after the provider accepts the delete and returns success only when `deleted:1` or a genuine 404 proves the message gone; otherwise it returns `502 deleted_unconfirmed` and refuses a retry. Deletes spend their own daily budget and never consume your send budget.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1480,12 +1529,13 @@ const TOOLS = [
   {
     name: "li_post_comments",
     path: "/li/post_comments",
-    description: "Read one bounded page of comments and authors on a post. Pass comment_id to read replies to that exact parent comment. Pass the exact social_id returned by li_my_posts; a numeric id is resolved against your own recent posts when possible. Read completeness.state, completeness.total, and completeness.next_cursor before treating the list as complete, then pass cursor to continue. The true total comes from the provider response when available; SignalDash never guesses it from li_my_posts.",
+    description: "Read one bounded page of comments and authors on a post. Pass comment_id to read replies to that exact parent comment. Pass resolve_reply_state:true to also learn, per comment, whether you already replied: each comment then carries reply_state with replied_by_me true, false, or null. Only treat a comment as unanswered when reply_state.state is no_replies or answered_by_others; null means unknown and must never be read as nobody-replied. Pass the exact social_id returned by li_my_posts; a numeric id is resolved against your own recent posts when possible. Read completeness.state, completeness.total, and completeness.next_cursor before treating the list as complete, then pass cursor to continue. The true total comes from the provider response when available; SignalDash never guesses it from li_my_posts.",
     inputSchema: {
       type: "object",
       properties: {
         post_id: { type: "string", minLength: 1, maxLength: 500 },
         comment_id: { type: "string", minLength: 1, maxLength: 500, description: "Optional exact parent comment id. When present, returns replies to that comment." },
+        resolve_reply_state: { type: "boolean", description: "Read the connected account identity once and each comment's reply thread to prove whether you already replied. Reply-thread reads are bounded per request. Cannot be combined with comment_id. When omitted every comment still carries reply_state with state unknown, so a miss is never mistaken for a proven absence." },
         limit: { type: "integer", minimum: 1, maximum: 100 },
         cursor: { type: "string", minLength: 1, maxLength: 4000 },
       },
@@ -1529,7 +1579,7 @@ const TOOLS = [
   {
     name: "li_delete_message",
     path: "/li/delete_message",
-    description: "Remediate one exact LinkedIn message sent by this authenticated account, only within the provider's 60-minute window. Requires exact chat and message identity plus confirm:true. SignalDash proves chat ownership, exact-chat membership, own authorship, timestamp eligibility, a separate remediation budget, and post-delete absence. Deletion cannot undo prior delivery, reading, or notifications and does not weaken any send gate.",
+    description: "Remediate one exact LinkedIn message sent by this authenticated account, only within the provider's 60-minute window. Requires exact chat and message identity plus confirm:true. SignalDash proves chat ownership, exact-chat membership, own authorship, timestamp eligibility, a separate remediation budget, and the provider's post-delete state. Success requires `deleted:1` or a genuine 404; otherwise the tool returns `502 deleted_unconfirmed`, locks the sender, and never retries automatically. Deletion cannot undo prior delivery, reading, or notifications and does not weaken any send gate.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1559,7 +1609,7 @@ const TOOLS = [
   {
     name: "li_draft_post",
     path: "/li/create_post",
-    description: "Draft, publish, or schedule a LinkedIn post. Scheduling requires an offset-qualified scheduled_at plus publish:true after exact human approval. Optional mentions, base64 image attachments, and an account-owner-authored first_comment are preserved for the scheduled publish.",
+    description: "Draft, publish, or schedule a LinkedIn post. Scheduling requires an offset-qualified scheduled_at plus publish:true after exact human approval. When the content pipeline is enabled, use an approved content_pipeline_id or preview one exact reasoned content_pipeline_override and repeat it with confirm:true plus its single-use approval_hash. Optional mentions, base64 image attachments, and an account-owner-authored first_comment are preserved for the scheduled publish.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1567,6 +1617,16 @@ const TOOLS = [
         publish: { type: "boolean" },
         scheduled_at: { type: "string", format: "date-time" },
         content_pipeline_id: { type: "string", minLength: 1, maxLength: 200 },
+        content_pipeline_override: {
+          type: "object",
+          properties: {
+            reason: { type: "string", minLength: 8, maxLength: 500 },
+            confirm: { type: "boolean", const: true },
+            approval_hash: { type: "string", minLength: 64, maxLength: 64, pattern: "^[0-9a-f]{64}$" },
+          },
+          required: ["reason"],
+          additionalProperties: false,
+        },
         first_comment: { type: "string", minLength: 1, maxLength: 1250 },
         mentions: {
           type: "array", maxItems: 20,
@@ -1617,6 +1677,19 @@ const TOOLS = [
     description: "Read the shared LinkedIn content calendar from SignalDash and the configured Buffer channel. Always inspect completeness and per-source state. Native LinkedIn scheduled posts and drafts are NOT visible because Unipile has no documented read route for them, and SignalDash does not use raw Voyager routes or linkedin.com browser access. An empty items array is never proof that the native LinkedIn calendar is empty.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
   },
+  {
+    name: "li_scheduled_post_preview",
+    path: "/li/scheduled_post_preview",
+    description: "Create a short-lived one-use browser link for one exact active SignalDash scheduled post. The preview renders only that post, its stored image attachments, and its queued first comment in a read-only session. Requires the exact SignalDash post UUID returned by li_draft_post or li_scheduled_posts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", format: "uuid" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "li_cancel_scheduled_post",
     path: "/li/cancel_scheduled_post",
@@ -1713,6 +1786,64 @@ function mcpTool(name) {
     inputSchema: tool.inputSchema,
   };
 }
+
+// The single source of truth for the tool catalog an agent can see, in full
+// (name, description, inputSchema) -- not just names. MCP `tools/list` and
+// the CLI `signaldash tools` both call this, so the two surfaces can never
+// drift: one entry dropped for a missing inputSchema (see mcpTool above)
+// disappears from both at once instead of only one of them.
+export function listTools() {
+  return TOOLS.map(t => mcpTool(t.name)).filter(Boolean);
+}
+
+// The one dispatcher behind every tool call, whichever door it came through.
+// MCP `tools/call` (stdio) and the CLI `call` command both resolve `name` in
+// this exact TOOLS lookup and hit this exact backend route with these exact
+// arguments -- nothing about a "second path" is a second implementation.
+// Every guard an agent depends on (write-control ledger, per-account budget,
+// read-before-send watermark, pacing/jitter, provider-warning lock, audit
+// trail) lives in server.cjs keyed off the route and the bearer token's
+// account, not off which client asked, so this function has no guard logic
+// of its own to keep in sync -- there is exactly one enforcement point, and
+// both callers share it. Returns `{ unknown: true }` for a name not in
+// TOOLS; callers translate that into their own transport's error shape
+// (MCP: JSON-RPC -32601, unchanged from before this refactor; CLI: a local
+// JSON error understood by scripts) so the shared function stays agnostic
+// to which door is asking.
+export async function callTool(name, args, dependencies = {}) {
+  const request = dependencies.request || api;
+  const t = TOOLS.find(x => x.name === name);
+  if (!t) return { unknown: true };
+  try {
+    return await request(t.path || `/${t.ch}/${t.action}`, args || {});
+  } catch (error) {
+    // A rejected fetch (DNS failure, connection refused, timeout, TLS
+    // error -- anything below the HTTP layer) has no status code and no
+    // response body, and previously escaped uncaught: from the CLI that
+    // broke the documented one-JSON-line/exit-1 contract with a raw stack
+    // trace on stderr, and from MCP's stdio loop it would have crashed the
+    // whole server on one bad network blip, taking every other tool down
+    // with it for the rest of the session. 599 is the conventional
+    // "no real HTTP response" pseudo-status other HTTP clients use for
+    // exactly this case; it satisfies both callers' existing `status >= 300`
+    // / `200 <= status < 300` checks without a third branch at either call
+    // site, so a transport failure gets the same "this was not a success"
+    // treatment as any other non-2xx response. Fails closed exactly like
+    // fallbackApiError above: the outcome is unknown, not a clean failure
+    // safe to retry into a possible duplicate.
+    return {
+      status: 599,
+      json: {
+        error: "SignalDash could not reach the backend. The action outcome is unknown; read the exact thread before any retry.",
+        code: "request_failed",
+        detail: error && error.message ? error.message : String(error),
+        retryable: false,
+        outcome_unknown: true,
+      },
+    };
+  }
+}
+
 export async function runMcp(dependencies = {}) {
   const input = dependencies.input || process.stdin;
   const output = dependencies.output || process.stdout;
@@ -1723,11 +1854,15 @@ export async function runMcp(dependencies = {}) {
     let msg; try { msg = JSON.parse(line); } catch { continue; }
     const { id, method, params } = msg;
     if (method === "initialize") reply(id, { protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "signaldash", version: PACKAGE_VERSION } });
-    else if (method === "tools/list") reply(id, { tools: TOOLS.map(t => mcpTool(t.name)).filter(Boolean) });
+    else if (method === "tools/list") reply(id, { tools: listTools() });
     else if (method === "tools/call") {
-      const t = TOOLS.find(x => x.name === params.name);
-      if (!t) { reply(id, null, { code: -32601, message: "unknown tool" }); continue; }
-      const r = await request(t.path || `/${t.ch}/${t.action}`, params.arguments || {});
+      // Unknown-tool handling is preserved byte-for-byte from before this
+      // refactor (JSON-RPC -32601, no content/isError envelope): callTool()
+      // reports `unknown: true` instead of throwing so this branch can keep
+      // exactly its old reply shape while the CLI's `call` command (below)
+      // gets its own, different, JSON-on-stdout shape for the same case.
+      const r = await callTool(params.name, params.arguments || {}, { request });
+      if (r.unknown) { reply(id, null, { code: -32601, message: "unknown tool" }); continue; }
       reply(id, { content: [{ type: "text", text: JSON.stringify(r.json) }], isError: r.status >= 300 });
     } else if (id !== undefined) reply(id, {});
   }
@@ -1829,8 +1964,11 @@ export async function cmdStatus(dependencies = {}) {
   for (const provider of ["linkedin", "whatsapp", "email"]) {
     const r = await request(`/connect/${provider}/status`, undefined, { method: "GET" });
     const ok = r.status === 200 && r.json.connected;
+    const unavailable = r.json?.code === "upstream_authentication_failed"
+      ? `authentication failed (provider HTTP ${r.json.upstream_status || "unknown"})`
+      : "not connected";
     log("  " + (ok ? chalk.green("+") : chalk.dim("-")) + " " + provider.padEnd(9) +
-        (ok ? chalk.dim(r.json.name || "connected") : chalk.dim("not connected")));
+        (ok ? chalk.dim(r.json.name || "connected") : chalk.dim(unavailable)));
   }
   log("");
 }
@@ -1872,6 +2010,90 @@ export async function cmdConnections(outPath, dependencies = {}) {
 }
 
 
+// Serializes exactly one JSON value with a trailing newline, and nothing
+// else -- no chalk, no ora, no progress text. Both `call` and `tools` write
+// through this so a script piping the CLI's stdout never has to skip
+// decorative lines to find the JSON.
+function jsonLine(value) {
+  return `${JSON.stringify(value)}\n`;
+}
+
+async function readAll(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// The second sanctioned path from issue #100: when an agent session's tool
+// roster does not include the MCP `li_*`/`wa_*`/`sd_*` tools (server
+// connected, but the client never loaded them), this CLI verb reaches the
+// exact same catalog and the exact same backend routes through callTool()
+// above, so it carries every guard the MCP path carries -- there is nothing
+// else to carry, because callTool() IS the MCP path's dispatcher too.
+//
+// Deliberately machine-facing, not human-facing: `signaldash status` and
+// friends print colored, human-readable lines; `call` and `tools` print
+// exactly one JSON value to stdout and communicate everything else (success,
+// refusal, malformed input) through the exit code, so an agent can script
+// against them without scraping prose.
+export async function cmdCall(argv, dependencies = {}) {
+  const request = dependencies.request || api;
+  const input = dependencies.input || process.stdin;
+  const write = dependencies.write || (text => process.stdout.write(text));
+  const [name, ...rest] = argv;
+  if (!name || rest.length > 1) {
+    write(jsonLine({ error: "usage: signaldash call <tool_name> ['<json-args>']", code: "usage" }));
+    process.exitCode = 1;
+    return;
+  }
+  let raw;
+  if (rest.length === 1) {
+    raw = rest[0];
+  } else {
+    // No inline JSON argument: read stdin to EOF when it is piped (a real
+    // agent invocation), but never block on a live TTY waiting for input
+    // nobody is going to type -- an empty/absent body means `{}`.
+    raw = input.isTTY ? "" : await readAll(input);
+  }
+  const trimmed = (raw || "").trim();
+  let args = {};
+  if (trimmed) {
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      write(jsonLine({ error: "arguments must be valid JSON", code: "invalid_json" }));
+      process.exitCode = 1;
+      return;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      write(jsonLine({ error: "arguments must be a JSON object", code: "invalid_json" }));
+      process.exitCode = 1;
+      return;
+    }
+    args = parsed;
+  }
+  const r = await callTool(name, args, { request });
+  if (r.unknown) {
+    write(jsonLine({ error: "unknown tool", code: "unknown_tool", tool: name }));
+    process.exitCode = 1;
+    return;
+  }
+  write(jsonLine(r.json));
+  process.exitCode = r.status >= 200 && r.status < 300 ? 0 : 1;
+}
+
+// The exact same catalog `tools/list` gives an MCP client, in full (name,
+// description, inputSchema) -- so an agent using `call` can discover the
+// right tool name and argument shape without needing the MCP transport
+// loaded at all.
+export async function cmdTools(dependencies = {}) {
+  const write = dependencies.write || (text => process.stdout.write(text));
+  write(jsonLine(listTools()));
+}
+
 function printHelp(log = console.log) {
   log(`SignalDash \u2014 secure LinkedIn, WhatsApp and email access for your AI agent.
 
@@ -1882,6 +2104,14 @@ function printHelp(log = console.log) {
   signaldash connections [file.csv]     export your LinkedIn connections
   signaldash skill                      install the agent skill
   signaldash mcp                        run the MCP server (used by your agent)
+  signaldash tools                      list every tool as JSON (name, description, inputSchema)
+  signaldash call <tool> ['<json-args>']
+                                         call one tool directly -- same routes and
+                                         guards as your agent's MCP tools. A second
+                                         sanctioned path for when MCP tools are not
+                                         loaded in this session; reads args from the
+                                         given JSON or from stdin, prints one JSON
+                                         line, exits 0 on HTTP 2xx else 1.
   signaldash logout                     revoke this device
 
 Your channel credentials stay on the SignalDash server. They are never stored on
@@ -1903,6 +2133,8 @@ 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 === "tools") await cmdTools(dependencies);
+  else if (cmd === "call") await cmdCall(argv.slice(1), dependencies);
   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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/signaldash",
-  "version": "0.39.0",
+  "version": "0.39.2",
   "description": "Secure LinkedIn, WhatsApp, and email access for AI agents",
   "type": "module",
   "bin": {

package/skills/content/SKILL.md

@@ -47,7 +47,9 @@ schedule without Federico approving the exact final text and time.
    through `li_draft_post` with the exact `content_pipeline_id`. SignalDash
    binds it in the same request only after the preflight passes. Same-day
    conflicts, three posts in one week, and a post above baseline inside its
-   two-day breathing window refuse before a schedule row exists.
+   two-day breathing window refuse before a schedule row exists. When Federico
+   asks to inspect the stored result, call `li_scheduled_post_preview` with its
+   exact schedule ID and share the isolated one-post handoff.
 7. Record exact publication evidence, then read the live own post at 24 and 72
    hours and pass its reactions, comments, impressions, and provider evidence
    to `sd_content_pipeline_measure`. The evidence must name `li_my_posts`, the

package/skills/signaldash/SKILL.md

@@ -299,7 +299,24 @@ li_list_chats({"limit": 5})
 
 If the tools are missing but `status` is connected, the account is ready and
 the MCP client is not loaded. Fix the MCP registration or restart the client;
-do not reconnect the account.
+do not reconnect the account. **This is not a reason to use Unipile, the
+provider, or any other path around SignalDash.** If restarting the client is
+not possible in this session, use the CLI directly instead: it is the same
+account, the same backend, and the same guards, only a different door.
+
+```bash
+npx -y @floomhq/signaldash tools
+npx -y @floomhq/signaldash call li_list_chats '{"limit": 5}'
+```
+
+`call` dispatches through the identical route and argument shape as the MCP
+tool of the same name -- the write-control ledger, per-account budget,
+read-before-send, pacing, provider-warning lock, and audit trail all run
+exactly as they do for an MCP call, because both go through the same backend
+route. `tools` lists the full catalog (name, description, `inputSchema`) as
+JSON so the right tool name and argument shape are discoverable without MCP.
+`call` prints exactly one JSON line to stdout and exits 0 on success, 1
+otherwise; script against the exit code and that one line, not prose.
 
 ## Numbered workflow for every account task
 
@@ -419,21 +436,22 @@ Use the exact tool names and argument keys below. Limits are optional.
 | `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_start_chat` | `member_ids` required array of 1-10 exact `@s.whatsapp.net` or `@lid` provider member IDs; `text` required exact first message; `confirm`, `approval_hash`, and `dry_run:true` apply only after preview | Start one direct or group chat under the same exact approval, live member resolution, protected-contact, duplicate-set, and readback contract as LinkedIn. If an `@lid` resolves to another canonical ID, repeat the preview with the returned `resolved_member_id`; SignalDash never substitutes an unapproved identity. A new chat spends one WhatsApp/email send action regardless of member count. An existing exact member-set chat is returned without sending. |
 | `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; `expected_watermark` optional exact 64-character watermark; `mark_read` optional boolean, default false | Send one approved reply, one approved file, or both, in an existing WhatsApp conversation after an immediate re-read. Own outbound additions do not invalidate the read; inbound additions or mutations return `new_messages`, `changed_kind`, and `current_watermark`. Pass `expected_watermark` to bind the send to the exact reviewed state and `mark_read:true` only when the approved workflow also calls for clearing unread after the confirmed send. 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. A re-read failure remains `502 thread_preflight_unavailable`, and a legacy proof with no watermark remains `428 read_before_send_required`; neither costs send budget. 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_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. SignalDash re-reads after the delete and returns success only when `deleted:1` or a genuine 404 proves the message gone. A present row or failed readback returns `502 deleted_unconfirmed`, records an unknown outcome, and must not be retried. |
 | `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; `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 exact `social_id` values. Omit `member_id` to use the connected user's own ID. Pass `social_id`, not a different numeric `id`, to the engagement tools. |
 | `li_post_reactions` | `post_id` required; use the exact `social_id` from `li_my_posts`; `limit` default 50, max 100; `cursor` optional | Read one bounded page of reactors. Always inspect `completeness.state`, `total`, and `next_cursor`; continue with the cursor while state is `incomplete`. Numeric ids are resolved against the user's own recent posts when possible, including ugcPost-backed multi-image posts. The provider total is reported when available and is never guessed from `li_my_posts`. A reaction does not authorize outreach. |
-| `li_post_comments` | `post_id` required; `comment_id` optional exact parent id; use the exact `social_id` from `li_my_posts`; `limit` default 50, max 100; `cursor` optional | Read one bounded page of comments, or pass `comment_id` to read replies to that exact parent. Always inspect `completeness.state`, `total`, and `next_cursor`; continue with the cursor while state is `incomplete`. Numeric ids are resolved against the user's own recent posts when possible. The provider total is reported when available and is never guessed from `li_my_posts`. |
+| `li_post_comments` | `post_id` required; `comment_id` optional exact parent id; `resolve_reply_state` optional boolean, not combinable with `comment_id`; use the exact `social_id` from `li_my_posts`; `limit` default 50, max 100; `cursor` optional | Read one bounded page of comments, or pass `comment_id` to read replies to that exact parent. Pass `resolve_reply_state: true` before replying to anything: each comment then carries `reply_state.replied_by_me`. Skip every comment whose `replied_by_me` is `true`, and skip every comment whose `replied_by_me` is `null`, which means unknown and never means nobody replied. Only `no_replies` and `answered_by_others` are proven unanswered. Always inspect `completeness.state`, `total`, and `next_cursor`; continue with the cursor while state is `incomplete`. Also inspect `reply_resolution.state`; `partial` or `aborted` means some comments were never resolved. Numeric ids are resolved against the user's own recent posts when possible. The provider total is reported when available and is never guessed from `li_my_posts`. |
 | `li_reply_to_comment` | Manual path: `post_id`, `parent_comment_id`, `trigger_comment_id`, and `text` required; `expected_watermark` optional exact 64-character watermark. Secretary path: `secretary_receipt_id` alone. | Reply once to one exact inbound comment on this sender's own post after `li_post_comments`. SignalDash re-proves post ownership, the unchanged trigger, its author and parent, no own duplicate, sender generation, budget, and provider health immediately before writing. A 2xx is not success until readback finds exactly one matching own reply. |
 | `li_like_comment` | `post_id`, `parent_comment_id`, and `comment_id` required; `expected_watermark` optional exact 64-character watermark | Like once one exact inbound comment on this sender's own post after `li_post_comments`. SignalDash re-proves post ownership, the unchanged comment, its author and parent, no own like, sender generation, budget, and provider health immediately before writing. A 2xx is not success until bounded readback finds exactly one own like. |
-| `li_delete_message` | `chat_id`, `message_id`, and `confirm:true` required | Remediate one exact own LinkedIn message within 60 minutes of sending. SignalDash proves account, exact chat, own authorship, timestamp eligibility, a separate remediation budget, and post-delete absence. This cannot undo delivery, reading, or notifications and never relaxes a send gate. |
+| `li_delete_message` | `chat_id`, `message_id`, and `confirm:true` required | Remediate one exact own LinkedIn message within 60 minutes of sending. SignalDash proves account, exact chat, own authorship, timestamp eligibility, a separate remediation budget, and the provider's post-delete state. Success requires `deleted:1` or a genuine 404. A present row or failed readback returns `502 deleted_unconfirmed`, locks the sender, and is never retried automatically. This cannot undo delivery, reading, or notifications and never relaxes a send gate. |
 | `li_delete_comment` | `post_id`, `comment_id`, and `confirm:true` required | Currently unavailable: the fixture-tested Unipile v2 wrapper is held at database capability state `untested` until live compatibility is proved against Federico's own removable comment. When enabled it proves own comment identity and readback. Deletion is remediation, not rollback. |
-| `li_draft_post` | `text` required, max 3000; `publish` optional; `scheduled_at` optional offset-qualified ISO date-time; `content_pipeline_id` required for scheduling while that user's pipeline is enabled; `mentions` optional array of up to 20 exact `{name,profile_id}` objects; `attachments` optional array of up to 4 exact `{filename,content_type,content_base64}` images; `first_comment` optional, max 1250 | Create a server-confirmed draft, publish now, or persist an exact future LinkedIn post and its approved first comment. An enabled pipeline runs its fact, exact-text, shared-calendar, frequency, and breathing preflight before the schedule row is created. |
+| `li_draft_post` | `text` required, max 3000; `publish` optional; `scheduled_at` optional offset-qualified ISO date-time; `content_pipeline_id` normally required for scheduling while that user's pipeline is enabled; `content_pipeline_override` optional exact `{reason,confirm?,approval_hash?}`; `mentions` optional array of up to 20 exact `{name,profile_id}` objects; `attachments` optional array of up to 4 exact `{filename,content_type,content_base64}` images; `first_comment` optional, max 1250 | Create a server-confirmed draft, publish now, or persist an exact future LinkedIn post and its approved first comment. An enabled pipeline normally runs its fact, exact-text, shared-calendar, frequency, and breathing preflight. For one deliberate exception, preview the exact payload with `{reason}`, show it to the human, then repeat it with `confirm:true` and the returned single-use payload-bound `approval_hash`. The audit record preserves the reason, preview ID, and approval time; every non-pipeline provider safety guard remains active. |
 | `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 | Read one shared content-calendar view across SignalDash and the configured Buffer LinkedIn channel. Inspect `completeness` and every `sources.*.state` before treating absence as an empty calendar. Native LinkedIn scheduled posts and drafts are invisible because Unipile has no documented read route for them; SignalDash does not use raw Voyager routes or linkedin.com browser access. An empty `items` array proves only that the visible sources returned no entries. |
+| `li_scheduled_post_preview` | `id` required UUID | Create a short-lived, single-use browser handoff for one exact active SignalDash post. The isolated page includes its stored image attachments through account- and post-scoped protected media routes. |
 | `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. |
@@ -498,6 +516,7 @@ li_delete_comment({"post_id":"exact-v2-post-id","comment_id":"exact-own-comment-
 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_scheduled_post_preview({"id":"00000000-0000-4000-8000-000000000000"})
 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({})
@@ -527,8 +546,17 @@ approval, repeat the identical payload with `publish:true`. Verify the stored
 record with `li_scheduled_posts`. Before scheduling, read that shared view and
 inspect its `completeness` plus the SignalDash, Buffer, and native LinkedIn
 source states. A date conflict in either visible source blocks planning until
-the human resolves it. Native LinkedIn remains explicitly blind, so never call
+the human resolves it. If the human explicitly approves one exception, call
+the preview again with `content_pipeline_override:{reason}`, show the returned
+exact payload, time, comment, reason, and expiry, then repeat that identical
+payload once with `publish:true`, `confirm:true`, and its `approval_hash`. Never
+generate an override silently, reuse its single-use hash, change its reason, or
+disable the pipeline as a shortcut. The schedule and approval consumption
+commit atomically. Once scheduled, its override-bound first comment is
+immutable. Native LinkedIn remains explicitly blind, so never call
 an empty result an empty calendar. For an existing scheduled post, use
+`li_scheduled_post_preview` when the human wants to review the exact stored
+copy and images in isolation. Use
 `li_set_scheduled_post_first_comment` only after approval of the exact comment.
 SignalDash persists the published post ID before sending the comment, so a
 comment failure never republishes the post. It fails interrupted or ambiguous
@@ -704,6 +732,16 @@ 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`.
 
+An explicit `content_pipeline_override` is scoped to one exact scheduled
+payload and expires after 15 minutes. The preview hash binds the post text,
+offset-qualified instant, mention set, image filenames/types/bytes, first
+comment, and exact reason. It bypasses only the enabled content pipeline's
+idea/arc/fact/calendar/frequency/breathing preflight for that one schedule. It
+commits atomically with the schedule, and its bound first comment cannot be
+edited afterward. It
+does not bypass sender resolution, duplicate protection, provider warnings,
+locks, budgets, publication ordering, or first-comment failure handling.
+
 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
@@ -1266,6 +1304,25 @@ Comply:
 Any upstream 429, provider warning, checkpoint, restriction, unusual-activity
 prompt, or HTTP 403 also means stop. Do not retry.
 
+### 502 `upstream_authentication_failed`
+
+Meaning: the provider definitively rejected authentication. The result includes
+`upstream_status` (401 or 403) and is distinct from `outcome_unknown`; a 401 is
+not reported as a timeout. Stop sends on that channel and reconnect or escalate
+the provider credential. `signaldash status` reports the channel as unavailable
+after a send-path 401. An explicit new account claim clears the recorded failure;
+a later confirmed WhatsApp or email send also clears it. LinkedIn 401 durably
+locks its sender, and `sd_budget_status` reports that lock with zero actions
+available now.
+
+Every provider failure from a send includes a `request_id` that is also present
+in the server log beside only the operation and channel. Use it for operator
+correlation; no chat identifier, account identifier, recipient, or message text
+is logged. If an intermediary removes an error body, the MCP client reconstructs
+the safe classification from response headers. With no usable body or headers it
+returns `backend_error_response_unreadable` with `outcome_unknown:true`, never
+an empty object and never permission to retry.
+
 ## Before every send
 
 These rules apply to LinkedIn messages and invitations, WhatsApp, email, and
@@ -1447,9 +1504,10 @@ If the user then asks to take that message back:
    wa_delete_message({"chat_id":"chat_wa_91b2","message_id":"msg_wa_5c71"})
    ```
 
-3. Read the chat again. WhatsApp enforces its own time and role limits and can
-   answer a delete successfully without removing anything, so a 200 is not
-   proof. Only the re-read is.
+3. Require `deleted:true` and `readback_verified:true` in the result. SignalDash
+   performs the provider re-read itself. `502 deleted_unconfirmed` means the
+   provider accepted the delete but the readback did not prove it gone; do not
+   retry that message.
 4. Never delete a message the user did not name. `403 message_not_own` means
    the message is the other person's and cannot be removed by anyone,
    including a group admin. `409 duplicate_delete` means SignalDash already