slack-term 1.37.1 → 1.38.0

package/ts/cli.ts

@@ -76,6 +76,9 @@ import {
   search,
   searchAll,
   send as slackSend,
+  pinsAdd,
+  RateLimitError,
+  repliesCursor,
   type MessageMetadata,
   getPermalink,
   scheduleMessage,
@@ -104,9 +107,10 @@ import {
   type ProgressState,
 } from "./todo.ts";
 import { setCacheEnabled } from "./cache.ts";
-import { unescapeArg } from "./escapes.ts";
+import { escapeArg, unescapeArg } from "./escapes.ts";
 import { dayLabel, encodeMentions, encodeMentionsDetailed, findUntaggedMentions, formatYmdHm, mentionWarnings, resolveDateMarkup, resolveMentions, type MentionEncodeResult } from "./format.ts";
 import { quietHoursNotice } from "./quietHours.ts";
+import { LockBusyError, PINLOG_MARKER, acquireLock, composeHead, formatJst, headUpdatedAt, isPinlogHead, parsePinlogId, pinlogId, stripPinlogFooter } from "./pinlog.ts";
 
 function loadDotenv(path: string): void {
   if (!existsSync(path)) return;
@@ -876,6 +880,7 @@ const SCOPE_FOR_METHOD: Record<string, string> = {
   "chat.postMessage": "chat:write",
   "chat.update": "chat:write",
   "chat.delete": "chat:write",
+  "pins.add": "pins:write",
   "conversations.replies": "channels:history (or groups:history)",
   "conversations.history": "channels:history (or groups:history)",
 };
@@ -1364,6 +1369,513 @@ async function cmdDelete(token: string, args: DeleteArgs): Promise<void> {
   console.log(`✓ Deleted (ts: ${ts})`);
 }
 
+// --- pinlog ---
+// A pinned status board: the pinned top-level message is the CURRENT state
+// (HEAD, edited in place — silent), and each change is one short thread reply
+// under it (the log — notifies). Pure helpers live in pinlog.ts; the commands
+// live here because they share the confirm gate with send/edit.
+
+/** Single-quote `s` for a POSIX shell, for the retry commands we print. */
+function shQuote(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/** Which board a subcommand was pointed at: `C…:ts` (what `new` prints), or
+ *  the usual `#chan:ts` / permalink forms. A board IS its message — there is
+ *  no name and nothing local to look up. */
+async function resolvePinlogTarget(
+  token: string, target: string, cookie?: string,
+): Promise<{ channel: string; ts: string; ref: string }> {
+  const id = parsePinlogId(target);
+  if (id) return { ...id, ref: id.channel };
+  const { ref, ts } = splitRefTs(target);
+  if (!ts) {
+    console.error(
+      `Error: ${stripTerminalControls(target)} is a channel, not a board — pass the board's permalink, ` +
+      `#chan:ts, or the id \`new\` printed (C…:ts). Boards in a channel:  slack pinlog ls ${shQuote(target)}`,
+    );
+    process.exit(2);
+  }
+  return { channel: await resolveChannel(token, ref, cookie), ts, ref };
+}
+
+/** The HEAD message itself, or a clean exit when there is none. */
+async function fetchPinlogHead(
+  token: string, channel: string, ts: string, cookie?: string,
+): Promise<Record<string, Json>> {
+  const resp = asRecord((await replies(token, channel, ts, 1, cookie)) as Json);
+  const head = asArray(resp.messages).map(asRecord).find((m) => String(m.ts) === ts);
+  if (!head) {
+    console.error(`Error: no message at ts=${ts} in ${channel}.`);
+    process.exit(1);
+  }
+  return head;
+}
+
+/** The state text for create/update: positional, or `--file` (`-` = stdin).
+ *  A board is many lines, and an agent quoting twenty lines into one argv
+ *  string is where a stray quote eats half of it. */
+function pinlogStateArg(positional: string | undefined, file: string | undefined): string | undefined {
+  if (file !== undefined) {
+    try {
+      return readFileSync(file === "-" ? 0 : file, "utf8").replace(/\n+$/, "");
+    } catch (e: unknown) {
+      console.error(`Error: cannot read --file ${file}: ${e instanceof Error ? e.message : String(e)}`);
+      process.exit(2);
+    }
+  }
+  return positional === undefined ? undefined : unescapeArg(positional);
+}
+
+/** Slack truncates `text` beyond 40,000 characters — which would cut the footer
+ *  off a board, after which `list` cannot find it and `update` refuses it. */
+const PINLOG_MAX_TEXT = 40_000;
+function pinlogCheckSize(what: string, text: string): void {
+  if (text.length > PINLOG_MAX_TEXT) {
+    console.error(`Error: the ${what} is ${text.length} characters; Slack truncates past ${PINLOG_MAX_TEXT}. Shorten it — move detail to a linked page.`);
+    process.exit(2);
+  }
+}
+
+/** Did this failed write DEFINITELY not land? Only a Slack error response
+ *  names a rejection. A network failure, or Slack's own internal_error /
+ *  fatal_error (documented as possibly-partial), means the write MAY have
+ *  landed — and advising a blind retry would then duplicate a board or a
+ *  notifying log line. */
+function pinlogWriteRejected(e: unknown): boolean {
+  const raw = e instanceof Error ? e.message : String(e);
+  const m = raw.match(/Slack error on \S+: (\w+)/);
+  if (e instanceof RateLimitError) return true;
+  return !!m && !["internal_error", "fatal_error", "request_timeout", "service_unavailable"].includes(m[1]!);
+}
+
+/** The quiet-hours line as a warning, or null outside them. The confirm gate
+ *  already prints the clock; this repeats it on the CONFIRMED run too, because
+ *  that is the run whose output an agent actually reads. */
+function pinlogQuietWarning(now: Date, what: string): string | null {
+  const n = quietHoursNotice(now);
+  return n && n.includes("QUIET HOURS") ? `⚠ Quiet hours (JST): ${what}.` : null;
+}
+
+interface PinlogCreateArgs {
+  target: string;
+  /** `-w`, carried into the printed recovery commands. */
+  workspace?: string;
+  state: string;
+  /** Optional first reason, posted as the new board's first thread reply. */
+  log?: string;
+  code?: string;
+  cookie?: string;
+  asBot?: boolean;
+  allowUrlAdjacent?: boolean;
+}
+
+async function cmdPinlogCreate(token: string, args: PinlogCreateArgs): Promise<void> {
+  const { ref, ts } = splitRefTs(args.target);
+  if (ts || parsePinlogId(args.target)) {
+    console.error(
+      "Error: `pinlog new` posts a NEW board — pass a channel (#chan or C…), not a message.\n" +
+      `  To change an existing board:  slack pinlog set ${shQuote(args.target)} '<new state>' '<reason>'`,
+    );
+    process.exit(2);
+  }
+  if (!args.state.trim()) {
+    console.error("Error: the initial state is empty — a board has to say something.");
+    process.exit(2);
+  }
+  guardUrlBoundaries(args.state, args.allowUrlAdjacent);
+  if (args.log !== undefined) {
+    guardUrlBoundaries(args.log, args.allowUrlAdjacent);
+    pinlogCheckSize("reason", args.log);
+  }
+
+  // Every recovery command printed below must act on the SAME workspace: a
+  // `list` that silently checks the default one finds nothing, and the next
+  // step is a duplicate board.
+  const bot = `${args.workspace ? ` -w ${shQuote(args.workspace)}` : ""}${args.asBot ? " --as-bot" : ""}`;
+  const getSelf = selfLookup(token, args.cookie);
+  const channelId = await resolveChannel(token, ref, args.cookie);
+  const self = await getSelf();
+  // The clock is NOT in the hash: the footer's minute moves between preview and
+  // confirm, and a code that expires every minute is a code people stop reading.
+  const code = safetyCode("pinlog-create", channelId, args.state, args.log ?? "", self?.userId ?? "");
+  const now = new Date();
+  const head = composeHead(args.state, now);
+  pinlogCheckSize("HEAD (state + footer)", head);
+  if (args.code !== code) {
+    const dest = await destLabel(token, channelId, ref, args.cookie);
+    // The situation, not just the text: boards already here are the usual
+    // sign that this should be a `set` on one of them, not a second board.
+    const existing = (await pinlogsIn(token, channelId, 200, args.cookie)).found;
+    requireCode(args.code, code, [
+      `--- New pinlog -------------------------------`,
+      fromLine(self, { asBot: args.asBot }),
+      `  → ${dest} — NEW top-level message, then pinned`,
+      ...(existing.length
+        ? [`⚠ ${existing.length} board(s) already in this channel — to change one, use \`slack pinlog set <board> …\` instead:`,
+           ...existing.slice(0, 5).map((m) => `    ${pinlogId(channelId, String(m.ts))}  ${pinlogFirstLine(String(m.text))}`)]
+        : [`  (no other boards in the last 200 messages of this channel)`]),
+      `--- State (the top-level message) ------------`,
+      ...head.split("\n").map((l) => `  ${stripTerminalControls(l)}`),
+      ...(args.log ? [`--- Reason (first thread reply — notifies) ---`, ...args.log.split("\n").map((l) => `  ${stripTerminalControls(l)}`)] : []),
+      `---------------------------------------------`,
+    ]);
+  }
+
+  const attr = sentAttribution("send");
+  let headTs: string;
+  try {
+    // plain: the HEAD must read back verbatim — `update` and `list` find the
+    // footer in the stored text, which Slack rewrites when blocks are attached.
+    headTs = await slackSend(token, channelId, head, undefined, false, args.cookie, true, attr.metadata);
+  } catch (e: unknown) {
+    if (pinlogWriteRejected(e)) {
+      console.error(`✗ HEAD was NOT posted: ${friendlySlackError(e)}`);
+    } else {
+      console.error(
+        `⚠ UNKNOWN whether the HEAD was posted: ${friendlySlackError(e)}\n` +
+        `  Check before retrying, or you will have two boards:  slack pinlog ls ${shQuote(args.target)}${bot}`,
+      );
+    }
+    process.exit(1);
+  }
+  if (!headTs) {
+    console.error("✗ Slack accepted the post but returned no ts — check the channel before retrying, it may have landed.");
+    process.exit(1);
+  }
+  attr.record({ team: self?.team, channel: channelId, target: args.target, ts: headTs, text: head, asBot: args.asBot });
+  const id = pinlogId(channelId, headTs);
+  console.log(`✓ Posted HEAD: ${id}`);
+  const quiet = pinlogQuietWarning(now, "this new top-level post notified everyone who follows the channel");
+  if (quiet) console.error(quiet);
+
+  try {
+    await pinsAdd(token, channelId, headTs, args.cookie);
+    console.log("✓ Pinned");
+  } catch (e: unknown) {
+    // The board EXISTS now. Failing the command here would invite a retry of
+    // `create`, i.e. a second board — so this is reported loudly, but the exit
+    // code stays 0 and the id is already on stdout.
+    const raw = e instanceof Error ? e.message : String(e);
+    const why = /missing_scope/.test(raw)
+      ? `the ${args.asBot ? "bot" : "user"} token lacks the pins:write scope`
+      : friendlySlackError(e);
+    console.error(`⚠ NOT pinned: ${why}.`);
+    console.error(`  The board works unpinned; pin it later with:  slack pinlog pin ${id}${bot}`);
+  }
+
+  if (args.log) {
+    // The board exists either way: a failed first reason is reported with its
+    // exact retry, never by failing `new` (a retry of that would be a 2nd board).
+    try {
+      const logTs = await slackSend(token, channelId, args.log, headTs, false, args.cookie, true);
+      console.log(`✓ Reason posted in the thread (ts: ${logTs})`);
+    } catch (e: unknown) {
+      const noteCode = safetyCode("pinlog-log", channelId, headTs, args.log, self?.userId ?? "");
+      console.error(
+        `${pinlogWriteRejected(e) ? "✗ The reason was NOT posted" : "⚠ UNKNOWN whether the reason was posted"}: ${friendlySlackError(e)}\n` +
+        `  The board IS posted. Retry just the reason (check the thread first):\n` +
+        `    slack pinlog note ${id} ${shQuote(escapeArg(args.log))}${args.allowUrlAdjacent ? " --allow-url-adjacent" : ""}${bot} --code=${noteCode}`,
+      );
+      process.exit(1);
+    }
+  }
+}
+
+interface PinlogUpdateArgs {
+  target: string;
+  state?: string;
+  log: string;
+  logOnly?: boolean;
+  /** Turn an existing message (no footer yet) into a board: the explicit
+   *  opt-out of the marker check, for a board people already ran by hand. */
+  adopt?: boolean;
+  /** `-w`, carried into the printed retry so it acts on the same workspace. */
+  workspace?: string;
+  code?: string;
+  cookie?: string;
+  asBot?: boolean;
+  allowUrlAdjacent?: boolean;
+}
+
+async function cmdPinlogUpdate(token: string, args: PinlogUpdateArgs): Promise<void> {
+  if (!args.log.trim()) {
+    console.error("Error: the reason is required — one short line saying what changed. The thread log is the point of a pinlog.");
+    process.exit(2);
+  }
+  if (!args.logOnly && (args.state === undefined || !args.state.trim())) {
+    console.error("Error: the new state is required (positional or --file). To post only a reason:  slack pinlog note <board> <reason>");
+    process.exit(2);
+  }
+  guardUrlBoundaries(args.log, args.allowUrlAdjacent);
+  if (args.state !== undefined) guardUrlBoundaries(args.state, args.allowUrlAdjacent);
+  pinlogCheckSize("log line", args.log);
+
+  const getSelf = selfLookup(token, args.cookie);
+  const { channel, ts, ref } = await resolvePinlogTarget(token, args.target, args.cookie);
+  // Held from the HEAD fetch through the log post (released on exit): Slack has
+  // no compare-and-swap on chat.update, so without it two confirmed updates can
+  // both read the same HEAD and the second silently erases the first's change.
+  try {
+    acquireLock(`pinlog-${channel}-${ts}`);
+  } catch (e: unknown) {
+    if (!(e instanceof LockBusyError)) throw e;
+    console.error(`Error: another update of ${pinlogId(channel, ts)} is running (${e.holder}). Re-run when it has finished — then re-read the board, it has changed.`);
+    process.exit(1);
+  }
+  const head = await fetchPinlogHead(token, channel, ts, args.cookie);
+  const currentText = typeof head.text === "string" ? head.text : "";
+  if (args.adopt && args.logOnly) {
+    console.error("Error: --adopt rewrites the state with a footer — it does not apply to note.");
+    process.exit(2);
+  }
+  if (!isPinlogHead(currentText) && !args.adopt) {
+    console.error(
+      `Error: the message at ${pinlogId(channel, ts)} is not a pinlog HEAD (no "${PINLOG_MARKER}" footer).\n` +
+      `  Refusing to overwrite it — check the id. To turn this message into a board on purpose, add --adopt.`,
+    );
+    process.exit(1);
+  }
+  const self = await getSelf();
+  const id = pinlogId(channel, ts);
+  const now = new Date();
+  const bot = `${args.workspace ? ` -w ${shQuote(args.workspace)}` : ""}${args.asBot ? " --as-bot" : ""}`;
+  // The retry command for a failed log post is printed with its code already
+  // in it, so the hash for `note` must be computable here without a gate.
+  const logOnlyCode = safetyCode("pinlog-log", channel, ts, args.log, self?.userId ?? "");
+  const logOnlyRetry = `slack pinlog note ${id} ${shQuote(escapeArg(args.log))}${args.allowUrlAdjacent ? " --allow-url-adjacent" : ""}${bot} --code=${logOnlyCode}`;
+
+  const quiet = pinlogQuietWarning(now, "the log reply notified everyone following this thread — hold non-urgent updates until 08:00");
+  if (args.logOnly) {
+    if (args.code !== logOnlyCode) {
+      const dest = await destLabel(token, channel, ref, args.cookie);
+      requireCode(args.code, logOnlyCode, [
+        `--- Pinlog log reply (HEAD unchanged) --------`,
+        fromLine(self, { asBot: args.asBot }),
+        `  → ${dest}, thread of ${id}`,
+        ...args.log.split("\n").map((l) => `  ${stripTerminalControls(l)}`),
+        `---------------------------------------------`,
+      ]);
+    }
+  } else {
+    const newHead = composeHead(args.state!, now);
+    pinlogCheckSize("new HEAD (state + footer)", newHead);
+    // The CURRENT text is in the hash: if someone else updated the board
+    // between your preview and your confirm, the code you were shown no longer
+    // matches, and you re-read before overwriting their change.
+    const adopting = !isPinlogHead(currentText);
+    const code = safetyCode("pinlog-update", channel, ts, currentText, args.state!, args.log, self?.userId ?? "");
+    if (args.code !== code) {
+      const dest = await destLabel(token, channel, ref, args.cookie);
+      const unchanged = stripPinlogFooter(currentText).trim() === stripPinlogFooter(args.state!).trim();
+      requireCode(args.code, code, [
+        `--- Updating pinlog --------------------------`,
+        fromLine(self, { asBot: args.asBot }),
+        `  → ${dest}, ${id}`,
+        `--- Current HEAD -----------------------------`,
+        // Shown, not sent: the HEAD comes from Slack, and an escape sequence in
+        // it could repaint this very preview.
+        ...currentText.split("\n").map((l) => `  ${stripTerminalControls(l)}`),
+        `--- New HEAD (edited in place — silent) ------`,
+        ...newHead.split("\n").map((l) => `  ${stripTerminalControls(l)}`),
+        `--- Log reply (in the thread — notifies) -----`,
+        ...args.log.split("\n").map((l) => `  ${stripTerminalControls(l)}`),
+        `---------------------------------------------`,
+        ...(unchanged ? [`⚠ The state text is unchanged — only the footer time moves. Replies are for real changes.`] : []),
+        ...(adopting ? [`⚠ Adopting: this message has no pinlog footer yet — it becomes a board now.`] : []),
+      ]);
+    }
+
+    const attrEdit = sentAttribution("edit");
+    try {
+      await editMessage(token, channel, ts, newHead, args.cookie, true, attrEdit.metadata);
+    } catch (e: unknown) {
+      const raw = e instanceof Error ? e.message : String(e);
+      const hint = /cant_update_message/.test(raw)
+        ? `\n  Only the HEAD's author can edit it${args.asBot ? "" : " — if the bot created this board, add --as-bot"}.`
+        : "";
+      const what = pinlogWriteRejected(e)
+        ? `✗ HEAD was NOT updated: ${friendlySlackError(e)}${hint}`
+        : `⚠ UNKNOWN whether the HEAD was updated: ${friendlySlackError(e)}\n  Check it first:  slack pinlog get ${id}${bot}`;
+      console.error(`${what}\n  The log reply was NOT posted (a log line for a change the board may not show would be a lie).`);
+      process.exit(1);
+    }
+    attrEdit.record({ team: self?.team, channel, target: args.target, ts, text: newHead, asBot: args.asBot });
+    console.log(`✓ HEAD updated: ${id}`);
+  }
+
+  const attrLog = sentAttribution("send");
+  let logTs: string;
+  try {
+    logTs = await slackSend(token, channel, args.log, ts, false, args.cookie, true, attrLog.metadata);
+  } catch (e: unknown) {
+    const rejected = pinlogWriteRejected(e);
+    console.error(
+      (rejected
+        ? `✗ Log reply was NOT posted: ${friendlySlackError(e)}\n`
+        : `⚠ UNKNOWN whether the log reply was posted: ${friendlySlackError(e)}\n`) +
+      (args.logOnly ? "" : `  The HEAD IS updated — only the log line ${rejected ? "is" : "may be"} missing.\n`) +
+      (rejected ? "" : `  Check the thread first (retrying a reply that landed notifies everyone twice):  slack pinlog get ${id}${bot}\n`) +
+      `  Retry just the log line${rejected ? "" : " (only if it is not there)"}:\n    ${logOnlyRetry}`,
+    );
+    process.exit(1);
+  }
+  attrLog.record({ team: self?.team, channel, target: args.target, ts: logTs, text: args.log, asBot: args.asBot });
+  console.log(`✓ Logged (ts: ${logTs})`);
+  if (quiet) console.error(quiet);
+}
+
+/** Slack stores `&`, `<`, `>` escaped; `show` is for reading, so undo that. */
+function slackUnescape(s: string): string {
+  return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
+
+/** `2026-10-08 15:10 JST` for a Slack ts. */
+function tsJst(ts: string): string {
+  return formatJst(new Date(Number(ts.split(".")[0]) * 1000));
+}
+
+async function pinlogAuthor(token: string, m: Record<string, Json>, cache: Map<string, string>, cookie?: string): Promise<string> {
+  if (typeof m.user === "string") {
+    const hit = cache.get(m.user);
+    if (hit !== undefined) return hit;
+    let name: string;
+    try {
+      name = await userName(token, m.user, cookie);
+    } catch {
+      name = m.user;
+    }
+    cache.set(m.user, name);
+    return name;
+  }
+  const prof = asRecord(m.bot_profile);
+  if (typeof prof.name === "string") return prof.name;
+  return typeof m.username === "string" ? m.username : "bot";
+}
+
+async function cmdPinlogShow(token: string, target: string, cookie?: string, json?: boolean): Promise<void> {
+  const { channel, ts } = await resolvePinlogTarget(token, target, cookie);
+  // Page through the whole thread. Slack returns the oldest replies first, so a
+  // single page silently drops the NEWEST log entries — the ones a reader came
+  // for. Bounded; past the bound, `complete` says so.
+  const msgs: Record<string, Json>[] = [];
+  let cursor: string | undefined;
+  let pages = 0;
+  do {
+    const page = asRecord((await repliesCursor(token, channel, ts, cursor, 200, cookie)) as Json);
+    for (const m of asArray(page.messages).map(asRecord)) {
+      // Every page repeats the parent; keep it once.
+      if (String(m.ts) === ts && msgs.some((x) => String(x.ts) === ts)) continue;
+      msgs.push(m);
+    }
+    const next = asRecord(page.response_metadata).next_cursor;
+    cursor = typeof next === "string" && next ? next : undefined;
+    pages++;
+  } while (cursor && pages < 50);
+  const complete = cursor === undefined;
+  const head = msgs.find((m) => String(m.ts) === ts);
+  if (!head) {
+    console.error(`Error: no message at ts=${ts} in ${channel}.`);
+    process.exit(1);
+  }
+  const text = typeof head.text === "string" ? head.text : "";
+  const log = msgs.filter((m) => String(m.ts) !== ts);
+  if (json) {
+    console.log(JSON.stringify({
+      id: pinlogId(channel, ts),
+      isPinlog: isPinlogHead(text),
+      updated: headUpdatedAt(text),
+      complete,
+      head: text,
+      log: log.map((m) => ({ ts: String(m.ts), user: m.user ?? null, text: typeof m.text === "string" ? m.text : "" })),
+    }));
+    return;
+  }
+  if (!isPinlogHead(text)) {
+    console.error(`⚠ ${pinlogId(channel, ts)} has no "${PINLOG_MARKER}" footer — showing it anyway, but it is not a pinlog HEAD.`);
+  }
+  console.log(`=== HEAD ${pinlogId(channel, ts)} ===`);
+  for (const l of slackUnescape(text).split("\n")) console.log(stripTerminalControls(l));
+  const more = complete ? "" : " — INCOMPLETE: the newest entries are not shown";
+  console.log(`=== log (${log.length}${more}) ===`);
+  // One lookup per author, not per entry: a board is mostly one writer.
+  const authors = new Map<string, string>();
+  for (const m of log) {
+    const body = typeof m.text === "string" ? m.text : "";
+    const author = stripTerminalControls(await pinlogAuthor(token, m, authors, cookie));
+    const lines = slackUnescape(body).split("\n").map((l) => stripTerminalControls(l));
+    console.log(`${tsJst(String(m.ts))}  @${author}: ${lines[0] ?? ""}`);
+    for (const l of lines.slice(1)) console.log(`    ${l}`);
+  }
+}
+
+/** Boards among the last `limit` messages of a channel, newest first — found
+ *  by their footer, which is the only place a board is recorded. */
+async function pinlogsIn(
+  token: string, channelId: string, limit: number, cookie?: string,
+): Promise<{ found: Record<string, Json>[]; scanned: number }> {
+  let scanned = 0;
+  let cursor: string | undefined;
+  const found: Record<string, Json>[] = [];
+  do {
+    const page = asRecord((await history(token, channelId, Math.min(200, limit - scanned), undefined, cursor, cookie)) as Json);
+    const msgs = asArray(page.messages).map(asRecord);
+    scanned += msgs.length;
+    for (const m of msgs) if (typeof m.text === "string" && isPinlogHead(m.text)) found.push(m);
+    const next = asRecord(page.response_metadata).next_cursor;
+    cursor = typeof next === "string" && next ? next : undefined;
+  } while (cursor && scanned < limit);
+  return { found, scanned };
+}
+
+/** A board's first non-empty state line, for one-line listings. */
+function pinlogFirstLine(text: string): string {
+  return stripTerminalControls(stripPinlogFooter(text).split("\n").find((l) => l.trim()) ?? "").slice(0, 80);
+}
+
+async function cmdPinlogList(token: string, target: string, limit: number, cookie?: string): Promise<void> {
+  const { ref, ts } = splitRefTs(target);
+  if (ts || parsePinlogId(target)) {
+    console.error(`Error: \`pinlog ls\` takes a channel. For one board:  slack pinlog get ${shQuote(target)}`);
+    process.exit(2);
+  }
+  const channelId = await resolveChannel(token, ref, cookie);
+  const { found, scanned } = await pinlogsIn(token, channelId, limit, cookie);
+
+  const dest = await destLabel(token, channelId, ref, cookie);
+  if (found.length === 0) {
+    // "None in what we looked at" — not "none exist". Say how far we looked.
+    console.log(`No pinlogs in the last ${scanned} messages of ${dest}.${scanned >= limit ? ` (Older ones: --limit ${limit * 2})` : ""}`);
+    return;
+  }
+  for (const m of found) {
+    const ts = String(m.ts);
+    const id = pinlogId(channelId, ts);
+    const text = String(m.text);
+    const pinned = asArray(m.pinned_to).some((c) => c === channelId) ? "📌" : "  ";
+    const first = pinlogFirstLine(text);
+    const replies = typeof m.reply_count === "number" ? m.reply_count : 0;
+    console.log(`${pinned} ${id}  updated ${headUpdatedAt(text) ?? "?"}  log ${replies}`);
+    console.log(`     ${first}`);
+  }
+}
+
+async function cmdPinlogPin(token: string, target: string, cookie?: string): Promise<void> {
+  const { channel, ts } = await resolvePinlogTarget(token, target, cookie);
+  try {
+    await pinsAdd(token, channel, ts, cookie);
+    console.log(`✓ Pinned ${pinlogId(channel, ts)}`);
+  } catch (e: unknown) {
+    const raw = e instanceof Error ? e.message : String(e);
+    if (/already_pinned/.test(raw)) {
+      console.log(`✓ Already pinned: ${pinlogId(channel, ts)}`);
+      return;
+    }
+    console.error(`✗ NOT pinned: ${friendlySlackError(e)}`);
+    process.exit(1);
+  }
+}
+
 // --- react ---
 interface ReactArgs {
   target: string;
@@ -4294,6 +4806,179 @@ async function main(): Promise<void> {
         await cmdDelete(deleteToken, args);
       },
     )
+    .command(
+      "pinlog",
+      "Pinned status board: the pinned top-level message is the current state (edited in place, silent); each change is one thread reply (the log, notifies)",
+      (y) => {
+        // Every pinlog subcommand acts as ONE identity for both reads and
+        // writes: the bot can only edit what the bot posted, and reading with a
+        // different token than the one that will write is how a preview shows
+        // a message the write then cannot touch.
+        const asBotOpt = { type: "boolean", default: false, describe: "Act via the bot token (xoxb / SLACK_BOT_TOKEN). A board the bot created can only be updated --as-bot: Slack lets a token edit only its own messages." } as const;
+        const pick = async (argv: W & { "as-bot"?: boolean }): Promise<{ token: string; cookie?: string; asBot: boolean }> => {
+          if (argv["as-bot"]) {
+            const bot = requireBotToken();
+            // The bot token is SLACK_BOT_TOKEN whatever -w says. A -w naming a
+            // different workspace would read and write there with the wrong
+            // identity — or in the wrong workspace altogether — so refuse it.
+            if (typeof argv.workspace === "string") {
+              const cookie = ck(argv);
+              const [u, b] = await Promise.all([authScopes(tok(argv), cookie), authScopes(bot)]);
+              if (u.url !== b.url) {
+                console.error(
+                  `Error: --as-bot acts with SLACK_BOT_TOKEN, which belongs to ${b.url}, but -w ${argv.workspace} is ${u.url}.\n` +
+                  "  Drop -w, or set SLACK_BOT_TOKEN to that workspace's bot token.",
+                );
+                process.exit(2);
+              }
+            }
+            return { token: bot, asBot: true };
+          }
+          const cookie = ck(argv);
+          return { token: tok(argv), ...(cookie ? { cookie } : {}), asBot: false };
+        };
+        const fail = (e: unknown): never => {
+          console.error(friendlySlackError(e));
+          process.exit(1);
+        };
+        return y
+          .command(
+            "new <channel> [state] [reason]",
+            "Post a NEW board in a channel and pin it — the state is the top-level message; prints the board's id (C…:ts)",
+            (y2) => y2
+              .positional("channel", { type: "string", demandOption: true, describe: "#chan or channel ID" })
+              .positional("state", { type: "string", describe: "The whole state (\\n for newlines), or use --file" })
+              .positional("reason", { type: "string", describe: "Optional: why the board exists — its first thread reply" })
+              .option("file", { type: "string", describe: "Read the state from a file (- = stdin); then the only positional after <channel> is the reason" })
+              .option("code", { type: "string", describe: "Safety hash to confirm (printed by the preview)" })
+              .option("allow-url-adjacent", { type: "boolean", default: false, describe: "Warn instead of refusing ambiguous bare URL boundaries" })
+              .option("as-bot", asBotOpt)
+              .example('slack pinlog new "#gtm" "販売ブロッカー\\n1. 見積テンプレ — 未"', "preview, then rerun with --code"),
+            async (argv) => {
+              // As with `set`: with --file the state comes from the file, so the
+              // one positional after <channel> is the reason.
+              const fromFile = argv.file !== undefined;
+              if (fromFile && argv.state !== undefined && argv.reason !== undefined) {
+                console.error("Error: with --file, pass only the reason after <channel> (the state comes from the file).");
+                process.exit(2);
+              }
+              const state = fromFile ? pinlogStateArg(undefined, argv.file) : pinlogStateArg(argv.state, undefined);
+              const reason = fromFile ? argv.state : argv.reason;
+              if (state === undefined) {
+                console.error("Error: the state is required (positional or --file).");
+                process.exit(2);
+              }
+              const t = await pick(argv as W & { "as-bot"?: boolean });
+              const args: PinlogCreateArgs = { target: argv.channel!, state, asBot: t.asBot, allowUrlAdjacent: argv["allow-url-adjacent"] };
+              if (reason !== undefined) args.log = unescapeArg(reason);
+              if (t.cookie) args.cookie = t.cookie;
+              if (typeof argv.workspace === "string") args.workspace = argv.workspace;
+              if (argv.code) args.code = argv.code;
+              await cmdPinlogCreate(t.token, args).catch(fail);
+            },
+          )
+          .command(
+            "set <board> [state] [reason]",
+            "Change a board: replace its state (silent edit) AND post the reason in its thread (notifies)",
+            (y2) => y2
+              .positional("board", { type: "string", demandOption: true, describe: "The board: permalink, #chan:ts, or the id `new` printed" })
+              .positional("state", { type: "string", describe: "The WHOLE new state, not a diff (or --file)" })
+              .positional("reason", { type: "string", describe: "One short line: what changed and why (required)" })
+              .option("file", { type: "string", describe: "Read the state from a file (- = stdin); then the only positional after <board> is the reason" })
+              .option("adopt", { type: "boolean", default: false, describe: "Allow a message WITHOUT the pinlog footer: turn a hand-run board into one" })
+              .option("code", { type: "string", describe: "Safety hash to confirm (printed by the preview)" })
+              .option("allow-url-adjacent", { type: "boolean", default: false, describe: "Warn instead of refusing ambiguous bare URL boundaries" })
+              .option("as-bot", asBotOpt)
+              .example('slack pinlog set <board-link> "販売ブロッカー\\n1. 見積テンプレ — 済" "見積テンプレ: 未 → 済"', "")
+              .example('slack pinlog set <board-link> --file board.md "見積テンプレ: 未 → 済"', "state from a file"),
+            async (argv) => {
+              // With --file the state comes from the file, so the one positional
+              // after <board> is the reason.
+              const fromFile = argv.file !== undefined;
+              if (fromFile && argv.state !== undefined && argv.reason !== undefined) {
+                console.error("Error: with --file, pass only the reason after <board> (the state comes from the file).");
+                process.exit(2);
+              }
+              const state = fromFile ? pinlogStateArg(undefined, argv.file) : pinlogStateArg(argv.state, undefined);
+              const reasonRaw = fromFile ? argv.state : argv.reason;
+              if (state === undefined || reasonRaw === undefined) {
+                console.error(
+                  "Error: `pinlog set` needs the whole new state AND the reason:  slack pinlog set <board> '<state>' '<reason>'\n" +
+                  "  Only a reason, state unchanged:  slack pinlog note <board> '<reason>'",
+                );
+                process.exit(2);
+              }
+              const t = await pick(argv as W & { "as-bot"?: boolean });
+              const args: PinlogUpdateArgs = {
+                target: argv.board!, state, log: unescapeArg(reasonRaw), adopt: argv.adopt, asBot: t.asBot,
+                allowUrlAdjacent: argv["allow-url-adjacent"],
+              };
+              if (typeof argv.workspace === "string") args.workspace = argv.workspace;
+              if (t.cookie) args.cookie = t.cookie;
+              if (argv.code) args.code = argv.code;
+              await cmdPinlogUpdate(t.token, args).catch(fail);
+            },
+          )
+          .command(
+            "note <board> <reason>",
+            "Post only a reason in a board's thread (notifies); the state stays as is",
+            (y2) => y2
+              .positional("board", { type: "string", demandOption: true, describe: "The board: permalink, #chan:ts, or the id `new` printed" })
+              .positional("reason", { type: "string", demandOption: true, describe: "One short line, e.g. still blocked — chased X" })
+              .option("code", { type: "string", describe: "Safety hash to confirm (printed by the preview)" })
+              .option("allow-url-adjacent", { type: "boolean", default: false, describe: "Warn instead of refusing ambiguous bare URL boundaries" })
+              .option("as-bot", asBotOpt),
+            async (argv) => {
+              const t = await pick(argv as W & { "as-bot"?: boolean });
+              const args: PinlogUpdateArgs = {
+                target: argv.board!, log: unescapeArg(argv.reason!), logOnly: true, asBot: t.asBot,
+                allowUrlAdjacent: argv["allow-url-adjacent"],
+              };
+              if (typeof argv.workspace === "string") args.workspace = argv.workspace;
+              if (t.cookie) args.cookie = t.cookie;
+              if (argv.code) args.code = argv.code;
+              await cmdPinlogUpdate(t.token, args).catch(fail);
+            },
+          )
+          .command(
+            ["get <board>", "show <board>"],
+            "Show a board's state and its log (read-only)",
+            (y2) => y2
+              .positional("board", { type: "string", demandOption: true, describe: "The board: permalink, #chan:ts, or C…:ts" })
+              .option("json", { type: "boolean", default: false, describe: "One JSON object: {id, isPinlog, updated, head, log[]}" })
+              .option("as-bot", asBotOpt),
+            async (argv) => {
+              const t = await pick(argv as W & { "as-bot"?: boolean });
+              await cmdPinlogShow(t.token, argv.board!, t.cookie, argv.json).catch(fail);
+            },
+          )
+          .command(
+            ["ls <channel>", "list <channel>"],
+            "List the boards in a channel, found by their footer (read-only)",
+            (y2) => y2
+              .positional("channel", { type: "string", demandOption: true })
+              .option("limit", { alias: "n", type: "number", default: 500, describe: "How many recent channel messages to scan" })
+              .option("as-bot", asBotOpt),
+            async (argv) => {
+              const t = await pick(argv as W & { "as-bot"?: boolean });
+              await cmdPinlogList(t.token, argv.channel!, argv.limit, t.cookie).catch(fail);
+            },
+          )
+          .command(
+            "pin <board>",
+            false as unknown as string, // recovery only: `new` prints it when pinning failed
+            (y2) => y2
+              .positional("board", { type: "string", demandOption: true })
+              .option("as-bot", asBotOpt),
+            async (argv) => {
+              const t = await pick(argv as W & { "as-bot"?: boolean });
+              await cmdPinlogPin(t.token, argv.board!, t.cookie).catch(fail);
+            },
+          )
+          .demandCommand(1, "Pick one: ls | get | new | set | note");
+      },
+      () => {},
+    )
     .command(
       "react <target> <emoji>",
       "Add (or --remove) an emoji reaction — a lightweight ack that doesn't grow the thread",