@dotdrelle/wiki-manager 0.15.93 → 0.15.94

package/src/runtime/runner.test.js

@@ -1103,6 +1103,64 @@ test('runtime runs are seeded with the chat that preceded them', async () => {
   assert.equal(clipped[0].content.length, 2000);
 });
 
+test('a compact boundary hides the prior exchanges from the seed but keeps them in the conversation', async () => {
+  const { conversationSeed } = await import('./runner.js');
+  const session = {
+    agentProjection: {
+      conversation: [
+        { role: 'user', content: 'avant 1' },
+        { role: 'assistant', content: 'avant 2' },
+        { role: 'user', content: 'après 1' },
+        { role: 'assistant', content: 'après 2' },
+      ],
+      conversationSeedStart: 2,
+    },
+  };
+  const seed = conversationSeed(session, 'nouvelle question');
+  assert.deepEqual(seed, [
+    { role: 'user', content: 'après 1' },
+    { role: 'assistant', content: 'après 2' },
+  ]);
+  // The pre-compact exchange is gone from the grounding…
+  assert.equal(seed.some((message) => /avant/.test(message.content)), false);
+  // …but it stays in the displayed conversation.
+  assert.equal(session.agentProjection.conversation.length, 4);
+});
+
+test('a stored compact summary is prepended to the seed, ahead of the recent exchanges', async () => {
+  const { conversationSeed } = await import('./runner.js');
+  const session = {
+    agentProjection: {
+      conversation: [
+        { role: 'user', content: 'après 1' },
+        { role: 'assistant', content: 'après 2' },
+      ],
+      conversationSeedStart: 0,
+      conversationSummary: 'Résumé condensé des échanges précédents.',
+    },
+  };
+  const seed = conversationSeed(session, 'nouvelle question');
+  assert.equal(seed.length, 3);
+  assert.equal(seed[0].role, 'user');
+  assert.match(seed[0].content, /Résumé condensé des échanges précédents\./);
+  assert.deepEqual(seed.slice(1), [
+    { role: 'user', content: 'après 1' },
+    { role: 'assistant', content: 'après 2' },
+  ]);
+});
+
+test('no stored summary means no synthetic entry is added to the seed', async () => {
+  const { conversationSeed } = await import('./runner.js');
+  const session = {
+    agentProjection: {
+      conversation: [{ role: 'user', content: 'salut' }],
+      conversationSeedStart: 0,
+    },
+  };
+  const seed = conversationSeed(session, 'autre question');
+  assert.deepEqual(seed, [{ role: 'user', content: 'salut' }]);
+});
+
 test('skipImpossibleTasks propage un échec jusqu’au point fixe', () => {
   /*
    Marquer les seules tâches directement bloquées laissait un résidu : A en

package/src/runtime/server.js

@@ -15,6 +15,29 @@ import { cancelControlChain, cancelQueuedControlItem } from './controlCancellati
 import { generateSkillAcknowledgment, runSkillChain } from './skillRun.js';
 import { emitRuntimeLog } from './supervisor.js';
 import { findSkill, listSkills } from '../core/skills.js';
+import {
+  enrollment,
+  isLoopbackAddress,
+  isTotpEnabled,
+  issueSessionWithTotp,
+  loginAttemptAllowed,
+  loginStatus,
+  pruneLoginAttempts,
+  resetLoginAttempts,
+  revokeSession,
+  verifySessionToken,
+} from './loginSession.js';
+import { loginPageHtml } from './loginPage.js';
+
+function loginErrorText(code) {
+  const messages = {
+    totp_disabled: 'TOTP login is disabled on this manager.',
+    no_enrollment: 'Enrollment expired. Reload this page.',
+    enrollment_requires_loopback: 'Enrollment must be done from the machine running the manager.',
+    invalid_code: 'Invalid verification code.',
+  };
+  return messages[code] ?? 'Verification failed.';
+}
 
 const PRIVATE_CONTROL_INPUTS = new WeakMap();
 
@@ -75,12 +98,85 @@ export function startRuntimeServer({
 
   const server = createServer(async (request, response) => {
     try {
+      const url = new URL(request.url ?? '/', `http://${request.headers.host ?? 'localhost'}`);
+
+      // ── TOTP login surface — public by design: it is the door, not a room ──
+      if (url.pathname === '/login' && request.method === 'GET') {
+        const remoteAddress = request.socket?.remoteAddress ?? null;
+        const current = enrollment();
+        const status = loginStatus();
+        if (!status.enabled) {
+          sendHtml(response, 200, loginPageHtml({ error: 'TOTP login is disabled on this manager.' }));
+          return;
+        }
+        if (!status.enrolled && !isLoopbackAddress(remoteAddress)) {
+          sendHtml(response, 403, loginPageHtml({ error: 'Enrollment must be done from the machine running the manager.' }));
+          return;
+        }
+        sendHtml(response, 200, loginPageHtml({
+          enrolled: status.enrolled,
+          secret: current?.secret ?? null,
+          uri: current?.uri ?? null,
+        }));
+        return;
+      }
+      if (url.pathname === '/login/verify' && request.method === 'POST') {
+        const remoteAddress = request.socket?.remoteAddress ?? null;
+        const allowed = loginAttemptAllowed(remoteAddress);
+        if (!allowed.ok) {
+          sendJson(response, 429, { ok: false, error: `Too many attempts. Try again in ${allowed.retryAfterSeconds}s.` });
+          return;
+        }
+        const body = await readJson(request).catch(() => ({}));
+        const result = issueSessionWithTotp(body?.code, { remoteAddress });
+        if (!result.ok) {
+          sendJson(response, 401, { ok: false, error: loginErrorText(result.error) });
+          return;
+        }
+        resetLoginAttempts(remoteAddress);
+        // Hand the session to the browser as a cookie, on the runtime's own
+        // origin. Cookies ignore the port, so a browser that logged in here
+        // (the ShellUI gate) carries the same `wiki_session` to `serve` when
+        // it runs on this host — one TOTP login for both surfaces. serve sets
+        // its own cookie too when a browser reaches it first.
+        setSessionCookie(response, result.token, result.expiresAt, request);
+        sendJson(response, 200, {
+          ok: true,
+          token: result.token,
+          expiresAt: result.expiresAt,
+          page: loginPageHtml({ enrolled: true, sessionExpiresAt: result.expiresAt }),
+        });
+        return;
+      }
+      if (url.pathname === '/login/status' && request.method === 'GET') {
+        sendJson(response, 200, { ok: true, ...loginStatus() });
+        return;
+      }
+      if (url.pathname === '/logout' && request.method === 'POST') {
+        const body = await readJson(request).catch(() => ({}));
+        // revokeSession refuses without the session's own token — this route
+        // sits before the bearer gate by design, so the token itself is the
+        // only proof that the caller is the session being revoked, not an
+        // unauthenticated third party forcing the operator out.
+        const revoked = revokeSession(body?.token ?? null);
+        sendJson(response, 200, { ok: true, revoked });
+        return;
+      }
+      if (request.method === 'GET' && url.pathname === '/session/verify') {
+        // Public on purpose: the token IS the credential being checked — the
+        // caller already holds it, so verifying it leaks nothing beyond what
+        // possession implies. serve and the shell call this without bearer.
+        const sessionToken = String(url.searchParams.get('token') ?? '').trim();
+        const result = verifySessionToken(sessionToken);
+        sendJson(response, 200, { ok: result.ok, ...result });
+        return;
+      }
+
       if (!isAuthorized(request, token)) {
         sendJson(response, 401, { error: 'Unauthorized' });
         return;
       }
 
-      const url = new URL(request.url ?? '/', `http://${request.headers.host ?? 'localhost'}`);
       if (request.method === 'GET' && url.pathname === '/health') {
         const workspace = workspaceFromUrl(url);
         const context = workspace ? await resolveContext({ workspace }) : null;
@@ -649,6 +745,51 @@ export function startRuntimeServer({
         sendJson(response, 200, { truncated: true, index, removedEvents });
         return;
       }
+      // Compact: a deliberate "forget everything said so far in this
+      // workspace" action (served chat's memory gauge). Unlike
+      // /conversation/truncate above, nothing is deleted from the event log —
+      // the audit trail (GET /audit) stays intact. A single conversation_reset
+      // event is enough: the reducer (core/agentEvents.js) moves the
+      // conversationSeedStart boundary on it, and since executeInteractiveTurn
+      // rebuilds its conversationSeed from a fresh reduceAgentEvents() replay
+      // on every turn, future turns stop seeing anything before this point
+      // while the displayed conversation (and the ShellUI thread) stays whole.
+      if (request.method === 'POST' && url.pathname === '/conversation/compact') {
+        const { workspace, context } = await resolveBodyContext(request, url);
+        if (context?.running) {
+          sendJson(response, 409, { compacted: false, reason: 'run_active' });
+          return;
+        }
+        const resolvedWorkspace = context?.workspace ?? workspace ?? null;
+        if (!resolvedWorkspace) {
+          sendJson(response, 400, { compacted: false, reason: 'workspace_required' });
+          return;
+        }
+        let summary = null;
+        if (context?.session) {
+          const conversation = Array.isArray(context.session.agentProjection?.conversation)
+            ? context.session.agentProjection.conversation
+            : [];
+          const seedStart = Math.max(0, Number(context.session.agentProjection?.conversationSeedStart) || 0);
+          const previousSummary = context.session.agentProjection?.conversationSummary ?? null;
+          // Summarize BEFORE dispatching: the event's payload carries the
+          // result so the reducer only ever has to store a plain string, and
+          // a run cannot start concurrently (already refused with 409 above)
+          // to move conversation.length out from under this read.
+          summary = await summarizeCompactedConversation(context.session, {
+            previousSummary,
+            segment: conversation.slice(seedStart),
+          });
+          dispatchAgentEvent(context.session, createAgentEvent('conversation_reset', {
+            origin: 'user',
+            workspace: resolvedWorkspace,
+            payload: summary ? { summary } : {},
+          }));
+        }
+        publishState(resolvedWorkspace, context);
+        sendJson(response, 200, { compacted: true, summary });
+        return;
+      }
       if (request.method === 'POST' && url.pathname === '/resume') {
         const workspace = workspaceFromUrl(url);
         const result = await resume?.({ workspace });
@@ -681,6 +822,12 @@ export function startRuntimeServer({
     }
   });
 
+  // Housekeeping for the in-memory login-attempt rate limiter: nothing else
+  // ever calls pruneLoginAttempts, so without this the `attempts` Map grows
+  // by one entry per distinct source address for the life of the process.
+  const loginAttemptPruneTimer = setInterval(() => pruneLoginAttempts(), 10 * 60 * 1000);
+  loginAttemptPruneTimer.unref?.();
+
   return new Promise((resolve, reject) => {
     server.once('error', reject);
     server.listen(port, host, () => {
@@ -692,6 +839,7 @@ export function startRuntimeServer({
         publish,
         drainControl: (context) => drainControlQueue(context),
         close: () => new Promise((closeResolve, closeReject) => {
+          clearInterval(loginAttemptPruneTimer);
           for (const client of clients) client.response.end();
           clients.clear();
           server.close((err) => (err ? closeReject(err) : closeResolve()));
@@ -1206,6 +1354,44 @@ async function handleControlMessage(context, store, input, { intent = null, star
  falls back to the deterministic English catalog when no LLM is configured or
  the call fails. The fallback is what keeps the lane deterministic-under-failure.
  */
+const CONVERSATION_SUMMARY_TIMEOUT_MS = 20_000;
+const CONVERSATION_SUMMARY_MAX_INPUT_CHARS = 8_000;
+
+/*
+ A compact does not just cut older turns from conversationSeed — it replaces
+ them with a short rolling summary, so a decision made 20 messages ago is not
+ gone from Donna's grounding entirely, only condensed. Best-effort: no LLM
+ configured, an empty reply, or a call failure all fall back to keeping
+ whatever summary already existed (never worse than before this compact),
+ the same deterministic-under-failure shape as generateControlAcknowledgment.
+ */
+async function summarizeCompactedConversation(session, { previousSummary, segment }) {
+  const llm = session?.llm;
+  const transcript = (Array.isArray(segment) ? segment : [])
+    .filter((message) => ['user', 'assistant'].includes(message?.role) && String(message?.content ?? '').trim())
+    .map((message) => `${message.role === 'user' ? 'User' : 'Assistant'}: ${String(message.content).trim()}`)
+    .join('\n')
+    .slice(0, CONVERSATION_SUMMARY_MAX_INPUT_CHARS);
+  if (!transcript) return previousSummary || null;
+  if (!(llm && typeof llm.complete === 'function')) return previousSummary || null;
+  try {
+    const reply = await llm.complete({
+      system: 'You maintain a compact working memory for Donna, a workspace assistant. You are shown an optional PREVIOUS SUMMARY and a NEW SEGMENT of conversation about to leave the assistant\'s context window. Write ONE updated summary that preserves the facts, decisions, open questions and user preferences that still matter for future turns. Be concise: well under 200 words. Return only the summary text — no preamble, no meta-commentary, no headings.',
+      input: [
+        previousSummary ? `PREVIOUS SUMMARY:\n${previousSummary}` : null,
+        `NEW SEGMENT:\n${transcript}`,
+      ].filter(Boolean).join('\n\n'),
+      signal: AbortSignal.timeout(CONVERSATION_SUMMARY_TIMEOUT_MS),
+    });
+    const text = String(reply ?? '').trim();
+    if (text) return text;
+    emitRuntimeLog(session, 'conversation-compact: LLM returned an empty summary, keeping the previous one');
+  } catch (err) {
+    emitRuntimeLog(session, `conversation-compact: summary LLM call failed, keeping the previous summary — ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return previousSummary || null;
+}
+
 async function generateControlAcknowledgment(session, { kind, input }) {
   const language = String(session?.language ?? '').trim().toLowerCase() || 'en';
   const llm = session?.llm;
@@ -1549,6 +1735,25 @@ function sendJson(response, statusCode, value) {
   response.end(`${JSON.stringify(value)}\n`);
 }
 
+function sendHtml(response, statusCode, html) {
+  response.writeHead(statusCode, { 'Content-Type': 'text/html; charset=utf-8' });
+  response.end(html);
+}
+
+// Mirrors serve's cookie (same name, flags and lifetime) so one runtime-issued
+// session is also the one serve validates. Secure only when the request
+// already arrived over TLS — a localhost HTTP install must still get the
+// cookie, but a proxied HTTPS one must not leak it.
+function setSessionCookie(response, token, expiresAt, request) {
+  const maxAgeSeconds = Math.max(1, Math.floor((Number(expiresAt) - Date.now()) / 1000));
+  const tls = Boolean(request.socket?.encrypted) || request.headers['x-forwarded-proto'] === 'https';
+  const secure = tls ? '; Secure' : '';
+  response.setHeader(
+    'Set-Cookie',
+    `wiki_session=${encodeURIComponent(token)}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAgeSeconds}${secure}`,
+  );
+}
+
 function readRequiredPatchId(body, response) {
   const patchId = String(body.patchId ?? body.id ?? '').trim();
   if (!patchId) {

package/src/runtime/totp.js

@@ -0,0 +1,87 @@
+import { createHmac, randomBytes, timingSafeEqual, createHash } from 'node:crypto';
+
+/*
+ RFC 6238 TOTP with the defaults every authenticator app ships:
+ HMAC-SHA1, 6 digits, 30-second period. Self-contained — no dependency.
+
+ The secret is base32 (RFC 4648, no padding, uppercase), 20 bytes by default.
+ Verification accepts a ±1 window so a drifting clock or a code typed at the
+ end of its period is not a refusal, and compares DIGESTS (constant-time),
+ never the raw strings.
+ */
+
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+
+export function base32Encode(buffer) {
+  let bits = 0;
+  let value = 0;
+  let output = '';
+  for (const byte of buffer) {
+    value = (value << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      output += BASE32_ALPHABET[(value >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) output += BASE32_ALPHABET[(value << (5 - bits)) & 31];
+  return output;
+}
+
+export function base32Decode(input) {
+  const clean = String(input ?? '').toUpperCase().replace(/[^A-Z2-7]/g, '');
+  let bits = 0;
+  let value = 0;
+  const output = [];
+  for (const char of clean) {
+    value = (value << 5) | BASE32_ALPHABET.indexOf(char);
+    bits += 5;
+    if (bits >= 8) {
+      output.push((value >>> (bits - 8)) & 0xff);
+      bits -= 8;
+    }
+  }
+  return Buffer.from(output);
+}
+
+export function generateTotpSecret(bytes = 20) {
+  return base32Encode(randomBytes(bytes));
+}
+
+export function totpCode(secret, timestamp = Date.now(), { digits = 6, period = 30 } = {}) {
+  const counter = Math.floor(Number(timestamp) / 1000 / period);
+  const message = Buffer.alloc(8);
+  message.writeBigUInt64BE(BigInt(counter));
+  const digest = createHmac('sha1', base32Decode(secret)).update(message).digest();
+  const offset = digest[digest.length - 1] & 0x0f;
+  const binary =
+    ((digest[offset] & 0x7f) << 24) |
+    ((digest[offset + 1] & 0xff) << 16) |
+    ((digest[offset + 2] & 0xff) << 8) |
+    (digest[offset + 3] & 0xff);
+  return String(binary % 10 ** digits).padStart(digits, '0');
+}
+
+export function digestEqual(left, right) {
+  const a = createHash('sha256').update(String(left ?? '')).digest();
+  const b = createHash('sha256').update(String(right ?? '')).digest();
+  return timingSafeEqual(a, b);
+}
+
+export function normalizeTotpCode(code) {
+  return String(code ?? '').replace(/\D/g, '').padStart(6, '0').slice(0, 6);
+}
+
+export function verifyTotp(secret, code, { window = 1, period = 30, timestamp = Date.now() } = {}) {
+  const wanted = normalizeTotpCode(code);
+  for (let step = -window; step <= window; step++) {
+    const candidate = totpCode(secret, timestamp + step * period * 1000, { period });
+    if (digestEqual(candidate, wanted)) return true;
+  }
+  return false;
+}
+
+export function otpauthUri(secret, { label = 'wiki', issuer = 'wikiLLM' } = {}) {
+  const params = new URLSearchParams({ secret, issuer, digits: '6', period: '30', algorithm: 'SHA1' });
+  return `otpauth://totp/${encodeURIComponent(`${issuer}:${label}`)}?${params.toString()}`;
+}

package/src/runtime/totp.test.js

@@ -0,0 +1,80 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  base32Decode,
+  base32Encode,
+  generateTotpSecret,
+  normalizeTotpCode,
+  otpauthUri,
+  totpCode,
+  verifyTotp,
+} from './totp.js';
+
+test('base32 round-trips arbitrary bytes', () => {
+  const bytes = Buffer.from([0, 1, 2, 0x7f, 0x80, 0xff, 0x41, 0x42]);
+  assert.equal(base32Encode(bytes), 'AAAQE74A75AUE');
+  assert.deepEqual(base32Decode(base32Encode(bytes)), bytes);
+  // Decoding tolerates lowercase and padding noise.
+  assert.deepEqual(base32Decode('aaaQE74a75aue==='), bytes);
+});
+
+test('generateTotpSecret returns a 32-char base32 secret of 20 bytes', () => {
+  const secret = generateTotpSecret();
+  assert.match(secret, /^[A-Z2-7]{32}$/);
+  assert.equal(base32Decode(secret).length, 20);
+});
+
+// RFC 6238 test vectors (Appendix B), SHA-1, 20-byte ASCII secret
+// "12345678901234567890" — encoded in base32 as the well-known
+// GEZDGNBVGY3TQOJQ GEZDGNBVGY3TQOJQ.
+const RFC_SECRET = 'GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ';
+
+test('totpCode matches the RFC 6238 vectors (8 digits, then 6)', () => {
+  const vectors = [
+    [59, '94287082'],
+    [1111111109, '07081804'],
+    [1111111111, '14050471'],
+    [1234567890, '89005924'],
+    [2000000000, '69279037'],
+    [20000000000, '65353130'],
+  ];
+  for (const [time, expected8] of vectors) {
+    assert.equal(totpCode(RFC_SECRET, time * 1000, { digits: 8 }), expected8, `T=${time}`);
+    assert.equal(totpCode(RFC_SECRET, time * 1000), expected8.slice(2), `T=${time} 6 digits`);
+  }
+});
+
+test('verifyTotp accepts the current step and the ±1 window', () => {
+  const secret = generateTotpSecret();
+  const now = 1_700_000_000_000;
+  const code = totpCode(secret, now);
+  assert.equal(verifyTotp(secret, code, { timestamp: now }), true);
+  assert.equal(verifyTotp(secret, code, { timestamp: now + 30_000 }), true);
+  assert.equal(verifyTotp(secret, code, { timestamp: now - 30_000 }), true);
+  assert.equal(verifyTotp(secret, code, { timestamp: now + 60_000 }), false);
+  assert.equal(verifyTotp(secret, code, { timestamp: now - 60_000 }), false);
+});
+
+test('verifyTotp normalizes spacing and a wrong code is refused', () => {
+  const secret = generateTotpSecret();
+  const now = 1_700_000_000_000;
+  const code = totpCode(secret, now);
+  assert.equal(verifyTotp(secret, ` ${code.slice(0, 3)} ${code.slice(3)} `, { timestamp: now }), true);
+  assert.equal(verifyTotp(secret, '000000', { timestamp: now }), false);
+});
+
+test('normalizeTotpCode keeps six digits', () => {
+  assert.equal(normalizeTotpCode(' 123 456 '), '123456');
+  assert.equal(normalizeTotpCode('42'), '000042');
+  assert.equal(normalizeTotpCode('1234567'), '123456');
+});
+
+test('otpauthUri carries the standard parameters', () => {
+  const uri = otpauthUri('ABCDEF', { label: 'demo', issuer: 'wikiLLM' });
+  assert.ok(uri.startsWith('otpauth://totp/wikiLLM%3Ademo?'));
+  assert.ok(uri.includes('secret=ABCDEF'));
+  assert.ok(uri.includes('issuer=wikiLLM'));
+  assert.ok(uri.includes('digits=6'));
+  assert.ok(uri.includes('period=30'));
+  assert.ok(uri.includes('algorithm=SHA1'));
+});

package/src/runtime/totpLogin.js

@@ -0,0 +1,123 @@
+import { spawn } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+/*
+ The interactive entry gate: `wiki-manager login` opens the runtime's TOTP
+ login page in the browser and polls until a session exists. The shell startup
+ runs the same flow when a session is required and missing.
+
+ Headless/CI never passes through here — it uses the runtime bearer token, not
+ the human session.
+ */
+
+export function runtimeBaseUrl(runtime) {
+  const base = String(runtime?.url ?? process.env.WIKI_MANAGER_RUNTIME_URL ?? 'http://127.0.0.1:7788');
+  return base.replace(/\/+$/, '');
+}
+
+export function loginPageUrl(runtime) {
+  return `${runtimeBaseUrl(runtime)}/login`;
+}
+
+// Returns a promise that reflects the real outcome: spawn() itself does not
+// throw for a missing opener (e.g. no xdg-open on a headless box) — that
+// surfaces asynchronously as an 'error' event — so callers that want to fall
+// back on failure need this to actually reject rather than resolve blindly.
+export function openBrowser(url) {
+  const target = String(url);
+  const options = { detached: true, stdio: 'ignore' };
+  return new Promise((resolveOpen, rejectOpen) => {
+    let child = null;
+    if (process.platform === 'darwin') {
+      child = spawn('open', [target], options);
+    } else if (process.platform === 'win32') {
+      child = spawn('cmd', ['/c', 'start', '', target], options);
+    } else {
+      child = spawn('xdg-open', [target], options);
+    }
+    child.once('error', rejectOpen);
+    child.once('spawn', () => {
+      child.unref?.();
+      resolveOpen();
+    });
+  });
+}
+
+export async function fetchLoginStatus(runtime) {
+  try {
+    const response = await fetch(`${runtimeBaseUrl(runtime)}/login/status`, {
+      signal: AbortSignal.timeout(3000),
+    });
+    if (!response.ok) return null;
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+// /logout requires the session's own token as proof of possession (it sits
+// before the bearer gate by design). The CLI runs on the same host as the
+// runtime, so it reads the active token itself — see currentSessionToken in
+// loginSession.js — rather than calling this without proof.
+export async function revokeRuntimeSession(runtime, token = null) {
+  try {
+    const response = await fetch(`${runtimeBaseUrl(runtime)}/logout`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token }),
+      signal: AbortSignal.timeout(3000),
+    });
+    if (!response.ok) return false;
+    const payload = await response.json().catch(() => ({}));
+    return payload?.revoked === true;
+  } catch {
+    return false;
+  }
+}
+
+/*
+ Requires a valid TOTP session on the runtime, opening the login page and
+ polling when one is missing. Returns:
+   { ok: true }            — session active (or nothing to do: disabled /
+                             runtime unreachable, which the caller announces).
+   { ok: false, error }    — the user did not log in within the timeout.
+ */
+export async function requestTotpSession(runtime, { timeoutMs = 5 * 60 * 1000, open = true, quiet = false } = {}) {
+  const status = await fetchLoginStatus(runtime);
+  // Every caller reaches this only after ensureRuntime() already confirmed
+  // the runtime is up via /health, so a /login/status failure right here is
+  // a real problem (route error, blip), not "nothing to gate" — fail CLOSED,
+  // matching the documented contract for the same scenario in serve, and say
+  // so instead of silently letting the shell start with no TOTP check at all.
+  if (!status) {
+    return { ok: false, error: `Could not reach the runtime's login status (${runtimeBaseUrl(runtime)}/login/status) — refusing to skip the TOTP check.` };
+  }
+  if (!status.enabled) return { ok: true, reason: 'totp_disabled' };
+  if (status.sessionActive) return { ok: true, expiresAt: status.sessionExpiresAt, reason: 'already_active' };
+
+  const url = loginPageUrl(runtime);
+  if (!quiet) console.log(`\x1b[33mTOTP login required — ${url}\x1b[0m`);
+  if (open) {
+    try {
+      await openBrowser(url);
+    } catch {
+      if (!quiet) console.log(`Open ${url} and enter the code from your authenticator.`);
+    }
+  } else if (!quiet) {
+    console.log(`Open ${url} in your browser and enter the code from your authenticator.`);
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const current = await fetchLoginStatus(runtime);
+    if (current?.sessionActive) {
+      if (!quiet) {
+        const until = new Date(current.sessionExpiresAt).toLocaleString();
+        console.log(`\x1b[32mSession active until ${until}\x1b[0m`);
+      }
+      return { ok: true, expiresAt: current.sessionExpiresAt, reason: 'logged_in' };
+    }
+    await sleep(1000);
+  }
+  return { ok: false, error: `No TOTP session after ${Math.round(timeoutMs / 60_000)} min — run "wiki-manager login" to retry.` };
+}