publishport-opencli 1.8.4-pp.1

package/clis/slock/in-page.js

@@ -0,0 +1,213 @@
+import { UUID_RE } from './resolve.js';
+import { SLOCK_API_BASE } from './shared.js';
+
+// ── Reusable in-page snippet fragments ──────────────────────────────────────
+// Every slock command runs a string of JS inside the logged-in page via
+// page.evaluate. The auth handshake (read token from localStorage), the
+// server-scope resolution (slug → X-Server-Id), and the channel-name → id
+// lookup were copy-pasted into every command. These fragments are the single
+// source of truth so a new command composes them instead of re-deriving them.
+//
+// Envelope contract (what a snippet returns):
+//   { kind: 'ok', rows, meta? }   { kind: 'auth', detail }
+//   { kind: 'http', status, where }   { kind: 'no-server', detail }
+//   { kind: 'unresolvable', detail }
+// See errors.js#dispatchEvaluateResult for how these map to typed errors.
+
+// Emits JS that leaves `token`, `sid` (null unless server-scoped) and `headers`
+// in scope on success, or `return`s an error envelope. Run it first in a snippet.
+export function authHeadersFragment({ serverScoped = false, serverIdOverride = null } = {}) {
+  // R1 — `--server <slug>` was being passed raw as X-Server-Id. The server
+  // only accepts UUIDs, so a slug override returned 500 from /channels/ and
+  // friends. Now: a UUID override is used directly; a slug override is
+  // resolved against /servers/ the same way the active-slug path does
+  // (single source of truth for slug→id). If neither override nor
+  // active-slug yields a known server, we fail loud with `no-server`.
+  // Source-verified (Bugen): /servers/ returns rows of { id, slug, name }.
+  const overrideStr = serverIdOverride ? JSON.stringify(serverIdOverride) : 'null';
+  const UUID_RE_SRC = '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$';
+  const resolveServer = serverScoped
+    ? `
+    if (!sid) {
+      // Determine the slug to look up: override slug (if not a UUID) wins,
+      // otherwise fall back to the active slug from localStorage.
+      const __override = ${overrideStr};
+      const __slug = __override ?? localStorage.getItem('slock_last_server_slug');
+      if (!__slug) return { kind: 'no-server', detail: 'no --server override and localStorage.slock_last_server_slug is empty; run \`slock server-use <slug>\` or pass --server <slug>' };
+      const sres = await fetch('${SLOCK_API_BASE}/servers/', {
+        method: 'GET', credentials: 'include',
+        headers: { authorization: 'Bearer ' + token, accept: 'application/json' },
+      });
+      if (sres.status === 401) return { kind: 'auth', detail: '/servers/ returned 401' };
+      if (!sres.ok) return { kind: 'http', status: sres.status, where: '/servers/' };
+      const slist = await sres.json();
+      const __arr = Array.isArray(slist) ? slist : [];
+      const sm = __arr.find((s) => s && s.slug === __slug);
+      if (!sm) {
+        const __choices = __arr.map((s) => s && s.slug).filter(Boolean).join(', ');
+        return { kind: 'no-server', detail: 'slug "' + __slug + '" not in /servers/' + (__override ? ' (--server)' : ' (active)') + '. Known slugs: ' + __choices };
+      }
+      sid = sm.id;
+    }`
+    : '';
+  // Node-side gate: if the override looks like a UUID, set sid directly and
+  // skip the lookup. Otherwise emit `let sid = null;` so the resolveServer
+  // block runs and treats the override (or active slug) uniformly.
+  const isUuidOverride = !!serverIdOverride && new RegExp(UUID_RE_SRC).test(String(serverIdOverride));
+  const sidInit = isUuidOverride ? overrideStr : 'null';
+  return `
+    // Page-readiness loop: page.goto can return before the SPA's first navigation
+    // settles, leaving location on an opaque interstitial (about:blank, redirector,
+    // etc.). Reading localStorage there throws SecurityError "Access is denied".
+    // Worse, qatester also live-flagged silent-empty fetches when the SPA had
+    // navigated to app.slock.ai but had not yet hydrated the token into
+    // localStorage — fetches then went out with an empty Authorization and the
+    // server happily returned [].
+    //
+    // The loop polls BOTH: (a) location.href is on app.slock.ai (so localStorage
+    // is no longer opaque) and (b) localStorage.slock_access_token is present
+    // (so the SPA finished hydrating). Reading localStorage inside try/catch
+    // because (a) and (b) can be partially satisfied — reading localStorage on
+    // an opaque origin still throws even after a redirect starts.
+    //
+    // 3s ceiling so a real navigation failure fails loud instead of hanging.
+    let __waited = 0;
+    let __reason = 'never reached app.slock.ai';
+    while (true) {
+      let __onHost = false;
+      try { __onHost = location.href.indexOf('app.slock.ai') !== -1; } catch (e) {}
+      if (__onHost) {
+        try {
+          if (localStorage.getItem('slock_access_token')) break;
+          __reason = 'on app.slock.ai but localStorage.slock_access_token not yet hydrated';
+        } catch (e) {
+          __reason = 'localStorage access threw even on app.slock.ai: ' + (e && e.message);
+        }
+      }
+      if (__waited >= 3000) {
+        let __loc;
+        try { __loc = location.href; } catch (e) { __loc = '(unreadable)'; }
+        return { kind: 'http', status: 0, where: 'page-readiness timeout: waited 3000ms (' + __reason + '), location=' + __loc };
+      }
+      await new Promise((r) => setTimeout(r, 50));
+      __waited += 50;
+    }
+    const token = localStorage.getItem('slock_access_token');
+    if (!token) return { kind: 'auth', detail: 'no access token in localStorage' };
+    let sid = ${sidInit};${resolveServer}
+    const headers = {
+      authorization: 'Bearer ' + token,
+      accept: 'application/json',
+      'content-type': 'application/json',
+    };
+    if (sid) headers['x-server-id'] = sid;
+  `;
+}
+
+// Emits JS that declares and sets `channelId` from a channel input that is
+// either a UUID (passthrough) or a "#name"/"name" (case-insensitive lookup
+// against GET /channels/). Requires `headers` from authHeadersFragment. On a
+// miss it `return`s { kind: 'unresolvable' }.
+export function channelResolveFragment(channelInput) {
+  const raw = String(channelInput ?? '');
+  const isUuid = UUID_RE.test(raw);
+  const rawJson = JSON.stringify(raw);
+  const nameJson = JSON.stringify(raw.replace(/^#/, '').toLowerCase());
+  return `
+    let channelId;
+    if (${isUuid}) {
+      channelId = ${rawJson};
+    } else {
+      const cres = await fetch('${SLOCK_API_BASE}/channels/', { credentials: 'include', headers });
+      if (cres.status === 401) return { kind: 'auth', detail: '/channels/ returned 401' };
+      if (!cres.ok) return { kind: 'http', status: cres.status, where: '/channels/' };
+      const carr = await cres.json();
+      const clist = Array.isArray(carr) ? carr : (carr.channels || carr.data || []);
+      const chit = clist.find((c) => (c.name || c.slug || '').toLowerCase() === ${nameJson});
+      if (!chit) return { kind: 'unresolvable', detail: 'no channel matches ' + ${nameJson} };
+      channelId = chit.id;
+    }
+  `;
+}
+
+// Emits JS that expands a "#channel:shortId" short message id into the full
+// messageId UUID via GET /api/messages/context/:shortId?channelId=<id>.
+//
+// Phase 7.1 invariant (kept across rewrites): read `cxd.targetMessageId`,
+// NOT `m.message.id`. The latter is the closest-message-in-context object,
+// which can be a neighbor when the short id is just a prefix — Phase 7.1
+// bug class. Also: 404 from /messages/context means short id not found
+// in that channel — caller should map it to `unresolvable`, distinct from
+// other 404s in surrounding logic (threads-404 / channel-404 mean
+// different things).
+//
+// `shortIdVar` is mutated in-place: on success it holds the resolved UUID.
+//
+// opts:
+//   shortIdVar          name of the JS variable holding the short id (mutated)
+//   parentChannelIdVar  name of the JS variable holding the parent channelId
+//   contextDescription  optional `JSON.stringify`'d JS expression that
+//                       evaluates to a string used in the "not found" detail
+//                       (e.g. `"#general"` becomes `' in #' + 'general'`).
+//                       Pass `"''"` to omit the suffix entirely.
+//
+// Drift-guarded by clis/slock/short-id-canary.test.js — any other file that
+// hand-rolls `cxd.targetMessageId` short-id resolution fails the canary.
+export function resolveShortIdFragment({ shortIdVar, parentChannelIdVar, contextDescription = "''" }) {
+  return `
+    if (!/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(${shortIdVar})) {
+      const cx = await fetch('${SLOCK_API_BASE}/messages/context/' + encodeURIComponent(${shortIdVar}) + '?channelId=' + encodeURIComponent(${parentChannelIdVar}), { credentials:'include', headers });
+      if (cx.status === 404) {
+        const __ctx = ${contextDescription};
+        return { kind: 'unresolvable', detail: 'short id "' + ${shortIdVar} + '" not found' + (__ctx ? ' in #' + __ctx : '') };
+      }
+      if (!cx.ok) return { kind: cx.status===401?'auth':'http', status: cx.status, where:'/messages/context' };
+      const cxd = await cx.json();
+      // CRITICAL — read targetMessageId, NOT m.message.id (Phase 7.1).
+      ${shortIdVar} = cxd.targetMessageId;
+    }
+  `;
+}
+
+// opts: { method, path, body?, serverScoped, serverIdOverride? }
+//   method      'GET' | 'POST' | 'DELETE' | 'PATCH'
+//   serverScoped  when true, resolve slug→id and send X-Server-Id
+//   serverIdOverride  if set, skip the localStorage slug lookup for this call
+// Single fetch to a fixed path. Use buildChannelScopedSnippet when the path
+// depends on a channel that must first be resolved from a name.
+export function buildFetchSnippet(opts) {
+  const method = JSON.stringify(opts.method);
+  const path = JSON.stringify(SLOCK_API_BASE + opts.path);
+  const bodyJson = opts.body === undefined ? 'undefined' : JSON.stringify(JSON.stringify(opts.body));
+  return `
+    ${authHeadersFragment({ serverScoped: opts.serverScoped, serverIdOverride: opts.serverIdOverride })}
+    const res = await fetch(${path}, {
+      method: ${method}, credentials: 'include', headers,
+      body: ${bodyJson},
+    });
+    if (res.status === 401) return { kind: 'auth', detail: ${path} + ' returned 401' };
+    if (!res.ok) return { kind: 'http', status: res.status, where: ${path} };
+    const data = await res.json().catch(() => ({}));
+    return { kind: 'ok', rows: data };
+  `;
+}
+
+// opts: { channelInput, method, pathSuffix?, body?, query?, serverIdOverride? }
+// Resolves channelInput (uuid or #name) then fetches /channels/:id<pathSuffix><query>.
+// Always server-scoped. `query` (if given) must include its leading '?'.
+export function buildChannelScopedSnippet(opts) {
+  const method = JSON.stringify(opts.method);
+  const suffix = JSON.stringify(opts.pathSuffix || '');
+  const query = opts.query ? JSON.stringify(opts.query) : "''";
+  const bodyJson = opts.body === undefined ? 'undefined' : JSON.stringify(JSON.stringify(opts.body));
+  return `
+    ${authHeadersFragment({ serverScoped: true, serverIdOverride: opts.serverIdOverride })}
+    ${channelResolveFragment(opts.channelInput)}
+    const __url = '${SLOCK_API_BASE}/channels/' + encodeURIComponent(channelId) + ${suffix} + ${query};
+    const res = await fetch(__url, { method: ${method}, credentials: 'include', headers, body: ${bodyJson} });
+    if (res.status === 401) return { kind: 'auth', detail: __url + ' returned 401' };
+    if (!res.ok) return { kind: 'http', status: res.status, where: __url };
+    const data = await res.json().catch(() => ({}));
+    return { kind: 'ok', rows: data };
+  `;
+}

package/clis/slock/in-page.test.js

@@ -0,0 +1,362 @@
+import { describe, it, expect, vi } from 'vitest';
+import { buildFetchSnippet, buildChannelScopedSnippet, channelResolveFragment } from './in-page.js';
+import { SLOCK_API_BASE } from './shared.js';
+
+const UUID_A = '11111111-1111-1111-1111-111111111111';
+
+// Run a snippet in this realm with fetch + localStorage stubbed.
+// async + awaited inside try/finally so globals are restored only AFTER
+// the snippet's async IIFE fully settles.
+async function runSnippet(snippet, fetchImpl, lsMap = {}) {
+  const realFetch = globalThis.fetch;
+  const realLS = globalThis.localStorage;
+  const realLocation = globalThis.location;
+  const store = { ...lsMap };
+  globalThis.fetch = fetchImpl;
+  globalThis.localStorage = {
+    getItem: (k) => (k in store ? store[k] : null),
+    setItem: (k, v) => { store[k] = String(v); },
+  };
+  // authHeadersFragment now opens with a page-readiness loop that waits until
+  // location.href contains 'app.slock.ai' (so localStorage on an opaque
+  // interstitial origin doesn't throw SecurityError). Stub a satisfied
+  // location so the snippet doesn't burn 3s of fake time.
+  globalThis.location = { href: 'https://app.slock.ai/' };
+  try {
+    // eslint-disable-next-line no-eval
+    return await eval(`(async () => { ${snippet} })()`);
+  } finally {
+    globalThis.fetch = realFetch;
+    globalThis.localStorage = realLS;
+    globalThis.location = realLocation;
+  }
+}
+
+describe('buildFetchSnippet', () => {
+  it('GET with no body returns the ok envelope on 200', async () => {
+    const snippet = buildFetchSnippet({ method: 'GET', path: '/channels/', serverScoped: true });
+    const fakeFetch = vi.fn()
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [{ id: 's1', slug: 'eng' }] })  // GET /servers/
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [{ id: 'c1', name: 'general' }] });
+    const result = await runSnippet(snippet, fakeFetch, {
+      slock_access_token: 'tkn',
+      slock_last_server_slug: 'eng',
+    });
+    expect(result).toEqual({ kind: 'ok', rows: [{ id: 'c1', name: 'general' }] });
+  });
+
+  it('POST sends the JSON body with content-type header', async () => {
+    const snippet = buildFetchSnippet({
+      method: 'POST',
+      path: '/messages',
+      body: { channelId: 'c1', content: 'hi' },
+      serverScoped: true,
+    });
+    const fakeFetch = vi.fn()
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [{ id: 's1', slug: 'eng' }] })
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => ({ id: 'm1' }) });
+    await runSnippet(snippet, fakeFetch, {
+      slock_access_token: 'tkn',
+      slock_last_server_slug: 'eng',
+    });
+    const call = fakeFetch.mock.calls[1];
+    expect(call[0]).toBe(SLOCK_API_BASE + '/messages');
+    expect(call[1].method).toBe('POST');
+    expect(call[1].headers['content-type']).toBe('application/json');
+    expect(JSON.parse(call[1].body)).toEqual({ channelId: 'c1', content: 'hi' });
+  });
+
+  it('server-scoped path injects X-Server-Id from resolved slug', async () => {
+    const snippet = buildFetchSnippet({ method: 'GET', path: '/channels/', serverScoped: true });
+    const fakeFetch = vi.fn()
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [{ id: 'sid-1', slug: 'eng' }] })
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [] });
+    await runSnippet(snippet, fakeFetch, {
+      slock_access_token: 'tkn',
+      slock_last_server_slug: 'eng',
+    });
+    expect(fakeFetch.mock.calls[1][1].headers['x-server-id']).toBe('sid-1');
+  });
+
+  it('non-server-scoped path does NOT include X-Server-Id', async () => {
+    const snippet = buildFetchSnippet({ method: 'GET', path: '/auth/me', serverScoped: false });
+    const fakeFetch = vi.fn().mockResolvedValueOnce({ ok: true, status: 200, json: async () => ({ id: 'u1' }) });
+    await runSnippet(snippet, fakeFetch, { slock_access_token: 'tkn' });
+    expect(fakeFetch.mock.calls[0][1].headers['x-server-id']).toBeUndefined();
+  });
+
+  it('returns kind:"auth" envelope on 401', async () => {
+    const snippet = buildFetchSnippet({ method: 'GET', path: '/auth/me', serverScoped: false });
+    const fakeFetch = vi.fn().mockResolvedValueOnce({ ok: false, status: 401, json: async () => ({}) });
+    const result = await runSnippet(snippet, fakeFetch, { slock_access_token: 'tkn' });
+    expect(result).toMatchObject({ kind: 'auth' });
+  });
+
+  it('returns kind:"no-server" when localStorage slug is missing on a server-scoped call', async () => {
+    const snippet = buildFetchSnippet({ method: 'GET', path: '/channels/', serverScoped: true });
+    const fakeFetch = vi.fn();
+    const result = await runSnippet(snippet, fakeFetch, { slock_access_token: 'tkn' });
+    expect(result).toMatchObject({ kind: 'no-server' });
+    expect(fakeFetch.mock.calls.length).toBe(0);
+  });
+});
+
+// Red-line: body is always JSON.stringify'd — no string concatenation, so injection is impossible.
+describe('buildFetchSnippet [red-line] injection safety', () => {
+  for (const evil of [
+    `'); alert('x'); ('`,
+    `</script><script>1</script>`,
+    `pizza 🍕 + surrogate 💊`,
+  ]) {
+    it(`content ${JSON.stringify(evil).slice(0, 40)}... round-trips byte-equal`, async () => {
+      const snippet = buildFetchSnippet({
+        method: 'POST',
+        path: '/messages',
+        body: { content: evil, channelId: 'c1' },
+        serverScoped: true,
+      });
+      const fakeFetch = vi.fn()
+        .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [{ id: 'sid', slug: 'eng' }] })
+        .mockResolvedValueOnce({ ok: true, status: 200, json: async () => ({ id: 'm1' }) });
+      await runSnippet(snippet, fakeFetch, {
+        slock_access_token: 'tkn',
+        slock_last_server_slug: 'eng',
+      });
+      const sentBody = JSON.parse(fakeFetch.mock.calls[1][1].body);
+      expect(sentBody.content).toBe(evil);
+    });
+  }
+});
+
+describe('buildChannelScopedSnippet', () => {
+  it('UUID channel + server override: single fetch straight to /channels/:id<suffix>', async () => {
+    const snippet = buildChannelScopedSnippet({
+      channelInput: UUID_A, method: 'GET', pathSuffix: '/members', serverIdOverride: '22222222-2222-2222-2222-222222222222',
+    });
+    const fakeFetch = vi.fn().mockResolvedValueOnce({ ok: true, status: 200, json: async () => [{ id: 'u1' }] });
+    const result = await runSnippet(snippet, fakeFetch, { slock_access_token: 'tkn' });
+    // No /servers/ resolve (override) and no /channels/ resolve (uuid) — one call.
+    expect(fakeFetch).toHaveBeenCalledTimes(1);
+    expect(fakeFetch.mock.calls[0][0]).toBe(`${SLOCK_API_BASE}/channels/${UUID_A}/members`);
+    expect(fakeFetch.mock.calls[0][1].headers['x-server-id']).toBe('22222222-2222-2222-2222-222222222222');
+    expect(result).toEqual({ kind: 'ok', rows: [{ id: 'u1' }] });
+  });
+
+  it('#name channel: resolves slug→sid, then name→id, then hits the target', async () => {
+    const snippet = buildChannelScopedSnippet({
+      channelInput: '#general', method: 'POST', pathSuffix: '/read-all',
+    });
+    const fakeFetch = vi.fn()
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [{ id: 'sid-1', slug: 'eng' }] })   // /servers/
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [{ id: 'chan-7', name: 'general' }] }) // /channels/
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => ({ ok: true, seq: 42 }) });            // target
+    const result = await runSnippet(snippet, fakeFetch, {
+      slock_access_token: 'tkn', slock_last_server_slug: 'eng',
+    });
+    expect(fakeFetch.mock.calls[2][0]).toBe(SLOCK_API_BASE + '/channels/chan-7/read-all');
+    expect(result).toEqual({ kind: 'ok', rows: { ok: true, seq: 42 } });
+  });
+
+  it('unresolvable channel name → kind:"unresolvable", no target fetch', async () => {
+    const snippet = buildChannelScopedSnippet({
+      channelInput: '#ghost', method: 'GET', serverIdOverride: '22222222-2222-2222-2222-222222222222',
+    });
+    const fakeFetch = vi.fn()
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [{ id: 'chan-7', name: 'general' }] }); // /channels/
+    const result = await runSnippet(snippet, fakeFetch, { slock_access_token: 'tkn' });
+    expect(result).toMatchObject({ kind: 'unresolvable' });
+    expect(fakeFetch).toHaveBeenCalledTimes(1); // only the resolve, no target
+  });
+});
+
+describe('channelResolveFragment', () => {
+  it('embeds the lowercased bare name (leading # stripped) as the lookup key', () => {
+    const frag = channelResolveFragment('#General');
+    // The name-lookup key is lowercased with the # stripped...
+    expect(frag).toContain('=== "general"');
+    // ...and never lowercases/strips into a different key.
+    expect(frag).not.toContain('=== "#general"');
+  });
+});
+
+describe('authHeadersFragment R1 — --server slug resolution', () => {
+  // R1 — old behavior: `--server <slug>` was passed RAW as X-Server-Id, server
+  // returned 500 because it only accepts UUIDs. Fix: resolve override slug
+  // against /servers/ the same way active-slug does. UUID overrides bypass
+  // the lookup (already an id).
+  it('UUID override bypasses /servers/ lookup and goes straight to the target with x-server-id=<uuid>', async () => {
+    const snippet = buildFetchSnippet({
+      method: 'GET',
+      path: '/channels/',
+      serverScoped: true,
+      serverIdOverride: '33333333-3333-3333-3333-333333333333',
+    });
+    const fakeFetch = vi.fn().mockResolvedValueOnce({ ok: true, status: 200, json: async () => [{ id: 'c1' }] });
+    const result = await runSnippet(snippet, fakeFetch, { slock_access_token: 'tkn' });
+    // Exactly one fetch — the target. No /servers/ resolve needed.
+    expect(fakeFetch).toHaveBeenCalledTimes(1);
+    expect(fakeFetch.mock.calls[0][0]).toBe(SLOCK_API_BASE + '/channels/');
+    expect(fakeFetch.mock.calls[0][1].headers['x-server-id']).toBe('33333333-3333-3333-3333-333333333333');
+    expect(result.kind).toBe('ok');
+  });
+
+  it('[R1 critical] slug override resolves via /servers/ — NEVER sent raw as x-server-id', async () => {
+    const snippet = buildFetchSnippet({
+      method: 'GET',
+      path: '/channels/',
+      serverScoped: true,
+      serverIdOverride: 'community',
+    });
+    const fakeFetch = vi.fn()
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [
+        { id: 'sid-community-uuid', slug: 'community' },
+        { id: 'sid-botiverse-uuid', slug: 'botiverse' },
+      ] })  // /servers/ lookup
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [{ id: 'c1' }] }); // target
+    const result = await runSnippet(snippet, fakeFetch, {
+      slock_access_token: 'tkn',
+      slock_last_server_slug: 'botiverse',  // active is botiverse — override must win
+    });
+    // First call: /servers/ — resolving the override slug "community".
+    expect(fakeFetch.mock.calls[0][0]).toBe(SLOCK_API_BASE + '/servers/');
+    // Second call: target — with the RESOLVED sid, NOT the raw "community".
+    expect(fakeFetch.mock.calls[1][0]).toBe(SLOCK_API_BASE + '/channels/');
+    const sentSid = fakeFetch.mock.calls[1][1].headers['x-server-id'];
+    expect(sentSid).toBe('sid-community-uuid');
+    expect(sentSid).not.toBe('community'); // regression catch: raw slug must NEVER be sent
+    expect(result.kind).toBe('ok');
+  });
+
+  it('[R1 critical] slug override wins over active slug in localStorage', async () => {
+    // Whether user has done server-use, the override must steer.
+    const snippet = buildFetchSnippet({
+      method: 'GET', path: '/channels/', serverScoped: true, serverIdOverride: 'community',
+    });
+    const fakeFetch = vi.fn()
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [
+        { id: 'sid-community-uuid', slug: 'community' },
+        { id: 'sid-botiverse-uuid', slug: 'botiverse' },
+      ] })
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [] });
+    await runSnippet(snippet, fakeFetch, {
+      slock_access_token: 'tkn',
+      slock_last_server_slug: 'botiverse',
+    });
+    // It MUST have looked up 'community' (not 'botiverse'). Easiest check:
+    // the resolved sid is the community one.
+    expect(fakeFetch.mock.calls[1][1].headers['x-server-id']).toBe('sid-community-uuid');
+  });
+
+  it('slug override that does NOT exist in /servers/ fails loud with no-server + known slugs hint', async () => {
+    const snippet = buildFetchSnippet({
+      method: 'GET', path: '/channels/', serverScoped: true, serverIdOverride: 'no-such-slug',
+    });
+    const fakeFetch = vi.fn()
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => [{ id: 's1', slug: 'community' }, { id: 's2', slug: 'botiverse' }] });
+    const result = await runSnippet(snippet, fakeFetch, { slock_access_token: 'tkn' });
+    expect(result.kind).toBe('no-server');
+    expect(result.detail).toMatch(/no-such-slug/);
+    expect(result.detail).toMatch(/--server/);
+    expect(result.detail).toMatch(/community/);   // hint lists known slugs
+    expect(fakeFetch).toHaveBeenCalledTimes(1);   // bailed before target fetch
+  });
+
+  it('with no override and no active-slug, fails loud with `no-server` mentioning server-use AND --server', async () => {
+    const snippet = buildFetchSnippet({ method: 'GET', path: '/channels/', serverScoped: true });
+    const fakeFetch = vi.fn();
+    const result = await runSnippet(snippet, fakeFetch, { slock_access_token: 'tkn' });
+    expect(result.kind).toBe('no-server');
+    expect(result.detail).toMatch(/server-use/);
+    expect(result.detail).toMatch(/--server/);
+    expect(fakeFetch).not.toHaveBeenCalled();
+  });
+});
+
+describe('authHeadersFragment page-readiness loop', () => {
+  // qatester live-flagged a SecurityError on first command after page.goto:
+  // page.goto returned before app.slock.ai actually loaded, leaving location
+  // on an opaque interstitial — localStorage on opaque origin throws. The
+  // fix is a polled wait inside authHeadersFragment for the SPA host. These
+  // cases lock the wait shape so a future refactor can't quietly strip it.
+
+  it('emits a polled wait that gates on BOTH location AND token-hydrated BEFORE the fetch', () => {
+    const snippet = buildFetchSnippet({ method: 'GET', path: '/whoami', serverScoped: false });
+    // (a) location.href check — guards SecurityError on opaque origins.
+    expect(snippet).toContain("location.href.indexOf('app.slock.ai')");
+    // (b) localStorage token check INSIDE the loop — guards silent-empty
+    // (page is on app.slock.ai but SPA has not yet written the token, so
+    // fetches went out with empty Authorization and server returned []).
+    expect(snippet).toContain("localStorage.getItem('slock_access_token')");
+    // The wait MUST sit before the final fetch; otherwise it doesn't
+    // prevent the SecurityError. Pin order by index.
+    const waitIdx = snippet.indexOf("location.href.indexOf('app.slock.ai')");
+    const fetchIdx = snippet.indexOf('await fetch(');
+    expect(waitIdx).toBeGreaterThan(-1);
+    expect(fetchIdx).toBeGreaterThan(-1);
+    expect(waitIdx).toBeLessThan(fetchIdx);
+  });
+
+  it('has a hard timeout that returns fail-loud kind:http rather than hanging', () => {
+    const snippet = buildFetchSnippet({ method: 'GET', path: '/whoami', serverScoped: false });
+    // Timeout ceiling pinned at 3000ms — change requires intentional bump.
+    expect(snippet).toContain('3000');
+    expect(snippet).toContain("'page-readiness timeout");
+    // Must return a typed envelope (not throw / hang) so the CLI surfaces
+    // a clean error.
+    expect(snippet).toMatch(/return\s*\{\s*kind:\s*'http'/);
+  });
+
+  it('silent-empty guard: on app.slock.ai but token not yet hydrated → timeout fail-loud, never fetches', async () => {
+    const snippet = buildFetchSnippet({ method: 'GET', path: '/whoami', serverScoped: false });
+    const realFetch = globalThis.fetch;
+    const realLS = globalThis.localStorage;
+    const realLocation = globalThis.location;
+    const realSetTimeout = globalThis.setTimeout;
+    globalThis.fetch = vi.fn();
+    // localStorage exists but slock_access_token never appears (the silent-empty
+    // case qatester live-flagged: SPA hadn't hydrated yet).
+    globalThis.localStorage = { getItem: () => null, setItem: () => {} };
+    globalThis.location = { href: 'https://app.slock.ai/' };
+    globalThis.setTimeout = (cb) => realSetTimeout(cb, 0);
+    try {
+      // eslint-disable-next-line no-eval
+      const result = await eval(`(async () => { ${snippet} })()`);
+      expect(result.kind).toBe('http');
+      expect(result.where).toMatch(/not yet hydrated/);
+      // Never fetched, because the loop never broke.
+      expect(globalThis.fetch).not.toHaveBeenCalled();
+    } finally {
+      globalThis.fetch = realFetch;
+      globalThis.localStorage = realLS;
+      globalThis.location = realLocation;
+      globalThis.setTimeout = realSetTimeout;
+    }
+  });
+
+  it('the wait actually triggers when location is NOT app.slock.ai (timeout path returns fail-loud)', async () => {
+    const snippet = buildFetchSnippet({ method: 'GET', path: '/whoami', serverScoped: false });
+    // Stub globals; location stays on a foreign origin so the loop will time out.
+    const realFetch = globalThis.fetch;
+    const realLS = globalThis.localStorage;
+    const realLocation = globalThis.location;
+    const realSetTimeout = globalThis.setTimeout;
+    globalThis.fetch = vi.fn();
+    globalThis.localStorage = { getItem: () => 'fake-token', setItem: () => {} };
+    globalThis.location = { href: 'https://example.com/' };
+    // Fast-forward setTimeout so the 3000ms loop completes instantly under test.
+    globalThis.setTimeout = (cb) => realSetTimeout(cb, 0);
+    try {
+      // eslint-disable-next-line no-eval
+      const result = await eval(`(async () => { ${snippet} })()`);
+      expect(result.kind).toBe('http');
+      expect(result.where).toMatch(/page-readiness timeout/);
+      // fetch must NEVER have been called because we never got past the loop.
+      expect(globalThis.fetch).not.toHaveBeenCalled();
+    } finally {
+      globalThis.fetch = realFetch;
+      globalThis.localStorage = realLS;
+      globalThis.location = realLocation;
+      globalThis.setTimeout = realSetTimeout;
+    }
+  });
+});

package/clis/slock/inbox-done.js

@@ -0,0 +1,40 @@
+// inbox-done.js
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError } from '@jackwener/opencli/errors';
+import { authHeadersFragment, channelResolveFragment } from './in-page.js';
+import { dispatchEvaluateResult } from './errors.js';
+import { SLOCK_SITE, SLOCK_DOMAIN, SLOCK_HOME_URL, SLOCK_API_BASE } from './shared.js';
+
+cli({
+  site: SLOCK_SITE,
+  name: 'inbox-done',
+  access: 'write',
+  description: 'Mark one chat as done / clear it from the inbox (POST /channels/inbox/done)',
+  domain: SLOCK_DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  siteSession: 'persistent',
+  args: [
+    { name: 'channel', positional: true, required: true, help: 'channelId UUID or #name' },
+    { name: 'server', help: 'Override active server' },
+  ],
+  columns: ['channel', 'result'],
+  func: async (page, kwargs) => {
+    const channel = String(kwargs.channel ?? '').trim();
+    if (!channel) throw new ArgumentError('channel required');
+    await page.goto(SLOCK_HOME_URL);
+    // channelId travels in the BODY (not the URL), so resolve then POST the fixed path.
+    const snippet = `
+      ${authHeadersFragment({ serverScoped: true, serverIdOverride: kwargs.server })}
+      ${channelResolveFragment(channel)}
+      const res = await fetch('${SLOCK_API_BASE}/channels/inbox/done', { method:'POST', credentials:'include', headers, body: JSON.stringify({ channelId }) });
+      if (res.status === 401) return { kind: 'auth', detail: '/channels/inbox/done returned 401' };
+      if (!res.ok) return { kind: 'http', status: res.status, where:'/channels/inbox/done' };
+      const data = await res.json().catch(() => ({}));
+      return { kind: 'ok', rows: data };
+    `;
+    const result = await page.evaluate(`(async () => { ${snippet} })()`);
+    dispatchEvaluateResult(result);
+    return [{ channel, result: 'done' }];
+  },
+});

package/clis/slock/inbox-done.test.js

@@ -0,0 +1,21 @@
+import { describe, it, expect, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './inbox-done.js';
+
+function makePage(result = { kind: 'ok', rows: { ok: true } }) {
+  return { goto: vi.fn(), evaluate: vi.fn().mockResolvedValue(result) };
+}
+
+describe('slock inbox-done', () => {
+  const command = getRegistry().get('slock/inbox-done');
+
+  it('resolves a #name channel and POSTs channelId in the body of /inbox/done', async () => {
+    const page = makePage();
+    const rows = await command.func(page, { channel: '#general' });
+    const script = page.evaluate.mock.calls[0][0];
+    expect(script).toContain('"general"');          // channel-name resolution embedded
+    expect(script).toContain('/channels/inbox/done'); // fixed path, channelId in body
+    expect(script).toContain('channelId');
+    expect(rows[0]).toMatchObject({ channel: '#general', result: 'done' });
+  });
+});