@threadcrumbs/threadnauts 1.2.0 → 1.4.0

package/dist/index.html

@@ -6,9 +6,9 @@
     <meta name="color-scheme" content="dark" />
     <title>Threadnauts</title>
     <link rel="icon" href="/favicon.svg?app=threadnauts" type="image/svg+xml" />
-    <script type="module" crossorigin src="/assets/index-C46d6g6p.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/shared-DiTtF988.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-PzTcyxAK.css">
+    <script type="module" crossorigin src="/assets/index-CJXuDA5A.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/shared-CudSvZVV.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-LNc3c53f.css">
   </head>
   <body>
     <div id="app"><div class="boot"><div class="inner">

package/dist/pro-manifest.json

@@ -1,9 +1,9 @@
 {
   "files": [
     {
-      "path": "assets/pro-lBnPFibL.js",
-      "sha256": "e8e7df01da6e616fb37a60ddc2657b63681cfd34adf8fb37116ecad906845a6e",
-      "bytes": 233030
+      "path": "assets/pro-DirsrB9B.js",
+      "sha256": "0040bc8fe354c96a4a81d290bde4a027502f9ea6a42ebe754dccce5c31f2c7df",
+      "bytes": 261373
     }
   ]
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@threadcrumbs/threadnauts",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "A 3D colony sim where every coding-agent thread on your machine is a little bot building something.",
   "license": "SEE LICENSE IN LICENSE.md",
-  "author": "Threadcrumbs LLC",
+  "author": "Threadcrumbs LLC <hello@threadcrumbs.io> (https://threadcrumbs.io)",
   "homepage": "https://threadnauts.io",
   "bugs": {
     "url": "https://threadnauts.io/#contact",
@@ -53,7 +53,7 @@
     "auto-publish": "node ../common/tools/release.mjs"
   },
   "dependencies": {
-    "@threadcrumbs/common": "^0.1.0"
+    "@threadcrumbs/common": "^0.1.9"
   },
   "devDependencies": {
     "@gltf-transform/core": "^4.4.2",

package/server/accents.mjs

@@ -0,0 +1,27 @@
+const HEX_COLOR = /^#[0-9a-f]{6}$/
+
+const asObject = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {})
+
+function asHex(value) {
+  if (Number.isInteger(value) && value >= 0 && value <= 0xffffff) return `#${value.toString(16).padStart(6, '0')}`
+  if (typeof value === 'string' && HEX_COLOR.test(value.toLowerCase())) return value.toLowerCase()
+  return null
+}
+
+function hexColors(...layers) {
+  const out = {}
+  for (const layer of layers) {
+    for (const [name, value] of Object.entries(asObject(layer))) {
+      const hex = asHex(value)
+      if (hex) Object.defineProperty(out, name, { value: hex, enumerable: true, writable: true, configurable: true })
+    }
+  }
+  return out
+}
+
+export function accentsAnswer(state) {
+  return {
+    orgs: hexColors(state?.accentsShown?.orgs, state?.accents?.orgs),
+    repos: hexColors(state?.accentsShown?.plots, state?.accents?.plots),
+  }
+}

package/server/api.mjs

@@ -8,7 +8,9 @@ import { openInTerminal } from './lib/terminal.mjs'
 import { focusWindowOfPid } from './lib/windows.mjs'
 import { localLicensing } from './license.mjs'
 import { localProContent } from './pro-content.mjs'
-import { findThreadgauge, threadgaugeContexts } from './threadgauge.mjs'
+import { findThreadgauge, threadgaugeSessions } from './threadgauge.mjs'
+import { CONTROL_BODY_LIMIT, THREADBARE_RELEASED, checkAnswerBody, checkAsksThread, checkRunBody, threadbareCommander } from './threadbare.mjs'
+import { accentsAnswer } from './accents.mjs'
 import { organizationReader } from '@threadcrumbs/common/orgs'
 import {
   defaultHarness,
@@ -35,7 +37,9 @@ const proContent = () => (proFiles ??= localProContent())
 export const proContentFile = (pathname) => proContent().file(pathname)
 
 const withOrganizations = organizationReader()
-const contextsFromThreadgauge = threadgaugeContexts()
+const sessionsFromThreadgauge = threadgaugeSessions()
+const commander = threadbareCommander({ pro: () => licensing().opens('threadgauge.pro', THREADBARE_RELEASED) })
+const CONTROL_ROUTES = { '/api/threadgauge/run': [checkRunBody, (body) => commander.run(body)], '/api/threadgauge/answer': [checkAnswerBody, (body) => commander.answer(body)] }
 
 let about = null
 const aboutThisApp = () =>
@@ -82,6 +86,7 @@ const emptyState = () => ({
   viewedAt: {},
   trinkets: {},
   accents: {},
+  accentsShown: {},
   districts: 0,
   settings: null,
   updatedAt: 0,
@@ -122,6 +127,7 @@ async function readState() {
       viewedAt: asObject(raw.viewedAt),
       trinkets: asObject(raw.trinkets),
       accents: asObject(raw.accents),
+      accentsShown: asObject(raw.accentsShown),
       districts: Number(raw.districts) || 0,
       settings: raw.settings && typeof raw.settings === 'object' ? raw.settings : null,
       updatedAt: Number(raw.updatedAt) || 0,
@@ -162,6 +168,7 @@ async function writeState(next) {
     viewedAt: asObject(next.viewedAt),
     trinkets: asObject(next.trinkets),
     accents: asObject(next.accents),
+    accentsShown: asObject(next.accentsShown),
     districts: Number(next.districts) || 0,
     settings: next.settings && typeof next.settings === 'object' ? next.settings : null,
     updatedAt: Date.now(),
@@ -421,10 +428,26 @@ function isLocalRequest(req) {
   if (!LOCAL_HOSTS.has(hostnameOf(req.headers.host))) return false
 
   const origin = req.headers.origin
-  if (origin && origin !== 'null') return LOCAL_HOSTS.has(hostnameOf(origin))
+  if (origin && origin !== 'null') return isOwnOrigin(origin, req)
   return req.method === 'GET' || req.method === 'HEAD'
 }
 
+function isOwnOrigin(origin, req) {
+  try {
+    const url = new URL(origin)
+    const port = Number(url.port) || (url.protocol === 'https:' ? 443 : 80)
+    return LOCAL_HOSTS.has(hostnameOf(origin)) && port === req.socket.localPort
+  } catch {
+    return false
+  }
+}
+
+const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE'])
+const sendsJson = (req) => /^application\/json\s*(;|$)/i.test(req.headers['content-type'] || '')
+
+const LOOPBACK_PEER = /^(127\.|::1$|::ffff:127\.)/
+export const isAnotherDevice = (req) =>!LOOPBACK_PEER.test(req.socket.remoteAddress || '')
+
 function readJsonBody(req, limit = 4 * 1024 * 1024) {
   return new Promise((resolve, reject) => {
     let size = 0
@@ -456,6 +479,9 @@ export async function middleware(req, res, next) {
   if (!isLocalRequest(req)) {
     return send(res, 403, { error: 'Threadnauts only answers its own page on this machine' })
   }
+  if (WRITE_METHODS.has(req.method) && !sendsJson(req)) {
+    return send(res, 415, { error: 'Threadnauts only accepts JSON' })
+  }
 
   try {
     if (url.pathname === '/api/threads' && req.method === 'GET') {
@@ -506,12 +532,35 @@ export async function middleware(req, res, next) {
       return send(res, 200, await aboutThisApp())
     }
 
+    if (url.pathname === '/api/accents' && req.method === 'GET') {
+      return send(res, 200, accentsAnswer(await readState()))
+    }
+
     if (url.pathname === '/api/threadgauge' && req.method === 'GET') {
       return send(res, 200, { url: await findThreadgauge() })
     }
 
-    if (url.pathname === '/api/threadgauge/contexts' && req.method === 'GET') {
-      return send(res, 200, await contextsFromThreadgauge())
+    if (url.pathname === '/api/threadgauge/sessions' && req.method === 'GET') {
+      return send(res, 200, await sessionsFromThreadgauge({ id: url.searchParams.get('id'), all: url.searchParams.has('all'), anotherDevice: isAnotherDevice(req) }))
+    }
+
+    if (url.pathname === '/api/threadgauge/commander' && req.method === 'GET') {
+      return send(res, 200, await commander.state({ anotherDevice: isAnotherDevice(req) }))
+    }
+
+    if (url.pathname === '/api/threadgauge/asks' && req.method === 'GET') {
+      if (isAnotherDevice(req)) return send(res, 403, { error: 'Threadnauts answers asks only from the computer it runs on' })
+      const thread = checkAsksThread(url.searchParams.get('thread'))
+      if (!thread) return send(res, 400, { error: 'Say which thread' })
+      return send(res, 200, await commander.asks({ thread }))
+    }
+
+    if (Object.hasOwn(CONTROL_ROUTES, url.pathname) && req.method === 'POST') {
+      if (isAnotherDevice(req)) return send(res, 403, { error: 'Threadnauts sends prompts and answers only from the computer it runs on' })
+      const [check, forward] = CONTROL_ROUTES[url.pathname]
+      const body = check(await readJsonBody(req, CONTROL_BODY_LIMIT).catch(() => null))
+      if (!body) return send(res, 400, { error: 'Threadnauts sends only a prompt or action to one thread, or an answer to one' })
+      return send(res, 200, await forward(body))
     }
 
     if (url.pathname === '/api/pro' && req.method === 'GET') {

package/server/http-server.mjs

@@ -110,6 +110,14 @@ async function serveRequest(req, res) {
   }
 }
 
+export function heldOnIpv6Loopback(port) {
+  return new Promise((resolve) => {
+    const trial = http.createServer()
+    trial.once('error', (err) => resolve(err.code === 'EADDRINUSE'))
+    trial.listen(port, '::1', () => trial.close(() => resolve(false)))
+  })
+}
+
 export function startServer({ port, host }) {
   const server = http.createServer((req, res) => {
     serveRequest(req, res).catch(() => {

package/server/license.mjs

@@ -1,69 +1,72 @@
-import fs from 'node:fs'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { paidThrough, renewalDue } from '@threadcrumbs/common/license'
-import { cloudUrl, licenseStore, threadcrumbsDataDir, trustedKeys } from '@threadcrumbs/common/license/store'
-
-const ENTITLEMENT = 'threadnauts.pro'
-const CLOUD_TIMEOUT_MS = 15000
-
-const runningFromCheckout = fs.existsSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '.git'))
-
-export function licensing({ store, cloudUrl, fetch = globalThis.fetch }) {
-  const describe = (license, at) => ({
-    proThrough: license ? paidThrough(license, ENTITLEMENT, at) : 0,
-    renewalDue: Boolean(license) && renewalDue(license, at),
-  })
-
-  async function status() {
-    const { license, at } = await store.current()
-    return describe(license, at)
-  }
-
-  async function ask(route, body) {
-    if (!cloudUrl) return { error: 'unavailable' }
-    let response
-    try {
-      response = await fetch(`${cloudUrl}${route}`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(CLOUD_TIMEOUT_MS),
-      })
-    } catch {
-      return { error: 'offline' }
-    }
-    const data = await response.json().catch(() => null)
-    if (response.ok && typeof data?.license === 'string') return { license: data.license }
-    return { error: typeof data?.error === 'string' ? data.error : 'unavailable' }
-  }
-
-  async function keep(answer) {
-    if (answer.error) return { ...(await status()), error: answer.error }
-    const saved = await store.save(answer.license)
-    if (!saved.ok) return { ...(await status()), error: 'license_rejected' }
-    return describe(saved.license, saved.at)
-  }
-
-  async function activate(key) {
-    const trimmed = typeof key === 'string' ? key.trim() : ''
-    if (!trimmed) return { ...(await status()), error: 'key_missing' }
-    return keep(await ask('/v1/license', { key: trimmed, device: await store.device() }))
-  }
-
-  async function renew() {
-    const { token, license, at } = await store.current()
-    if (!token || !renewalDue(license, at)) return describe(license, at)
-    return keep(await ask('/v1/license/renew', { license: token }))
-  }
-
-  return { status, activate, renew }
-}
-
-export function localLicensing({ env = process.env, development = runningFromCheckout, fetch } = {}) {
-  return licensing({
-    store: licenseStore({ dir: threadcrumbsDataDir({ env }), keys: trustedKeys({ env, development }) }),
-    cloudUrl: cloudUrl({ env, development }),
-    fetch,
-  })
-}
+import { paidThrough, renewalDue, unlocks } from '@threadcrumbs/common/license'
+import { cloudUrl, licenseStore, threadcrumbsDataDir, trustedKeys } from '@threadcrumbs/common/license/store'
+import { isSourceCheckout } from './source-checkout.mjs'
+
+const ENTITLEMENT = 'threadnauts.pro'
+const CLOUD_TIMEOUT_MS = 15000
+
+const runningFromCheckout = isSourceCheckout()
+
+export function licensing({ store, cloudUrl, fetch = globalThis.fetch }) {
+  const describe = (license, at) => ({
+    proThrough: license ? paidThrough(license, ENTITLEMENT, at) : 0,
+    renewalDue: Boolean(license) && renewalDue(license, at),
+  })
+
+  async function status() {
+    const { license, at } = await store.current()
+    return describe(license, at)
+  }
+
+  async function ask(route, body) {
+    if (!cloudUrl) return { error: 'unavailable' }
+    let response
+    try {
+      response = await fetch(`${cloudUrl}${route}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(CLOUD_TIMEOUT_MS),
+      })
+    } catch {
+      return { error: 'offline' }
+    }
+    const data = await response.json().catch(() => null)
+    if (response.ok && typeof data?.license === 'string') return { license: data.license }
+    return { error: typeof data?.error === 'string' ? data.error : 'unavailable' }
+  }
+
+  async function keep(answer) {
+    if (answer.error) return { ...(await status()), error: answer.error }
+    const saved = await store.save(answer.license)
+    if (!saved.ok) return { ...(await status()), error: 'license_rejected' }
+    return describe(saved.license, saved.at)
+  }
+
+  async function activate(key) {
+    const trimmed = typeof key === 'string' ? key.trim() : ''
+    if (!trimmed) return { ...(await status()), error: 'key_missing' }
+    return keep(await ask('/v1/license', { key: trimmed, device: await store.device() }))
+  }
+
+  async function renew() {
+    const { token, license, at } = await store.current()
+    if (!token || !renewalDue(license, at)) return describe(license, at)
+    return keep(await ask('/v1/license/renew', { license: token }))
+  }
+
+  async function opens(entitlement, releasedAt) {
+    const { license, at } = await store.current()
+    return Boolean(license) && unlocks(license, entitlement, releasedAt, at)
+  }
+
+  return { status, activate, renew, opens }
+}
+
+export function localLicensing({ env = process.env, development = runningFromCheckout, fetch } = {}) {
+  return licensing({
+    store: licenseStore({ dir: threadcrumbsDataDir({ env }), keys: trustedKeys({ env, development }) }),
+    cloudUrl: cloudUrl({ env, development }),
+    fetch,
+  })
+}

package/server/pro-content.mjs

@@ -5,6 +5,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { LICENSE_GRACE, paidThrough } from '@threadcrumbs/common/license'
 import { cloudUrl, licenseStore, threadcrumbsDataDir, trustedKeys } from '@threadcrumbs/common/license/store'
+import { isSourceCheckout } from './source-checkout.mjs'
 
 const ENTITLEMENT = 'threadnauts.pro'
 const APP = 'threadnauts'
@@ -14,7 +15,7 @@ const PAUSE_MS = 20
 
 const here = path.dirname(fileURLToPath(import.meta.url))
 const DIST = path.join(here, '..', 'dist')
-const runningFromCheckout = fs.existsSync(path.join(here, '..', '.git'))
+const runningFromCheckout = isSourceCheckout()
 
 const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex')
 const pause = () => new Promise((resolve) => setTimeout(resolve, PAUSE_MS))

package/server/source-checkout.mjs

@@ -0,0 +1,11 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const PACKAGE_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+const isDirectory = (file) => fs.statSync(file, { throwIfNoEntry: false })?.isDirectory() ?? false
+
+export function isSourceCheckout(root = PACKAGE_ROOT) {
+  return fs.existsSync(path.join(root, '.git')) && isDirectory(path.join(root, 'src')) && isDirectory(path.join(root, 'test'))
+}

package/server/threadbare.mjs

@@ -0,0 +1,252 @@
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import { clip } from '@threadcrumbs/common/lib/telemetry-fields'
+import { threadcrumbsDataDir } from '@threadcrumbs/common/license/store'
+import { isAskId, locateThreadgauge } from './threadgauge.mjs'
+
+export const APP = 'threadnauts'
+export const THREADBARE_RELEASED = Date.UTC(2026, 10, 9) / 1000
+export const CONTROL_BODY_LIMIT = 16 * 1024
+
+const REUSE_FOUND_MS = 15000
+const READ_TIMEOUT_MS = 3000
+const SEND_TIMEOUT_MS = 30000
+const THREAD_MAX = 300
+const VALUE_MAX = 8000
+const OPTIONS_MAX = 8
+const WHY_MAX = 500
+const NAME_MAX = 80
+const PROMPT_MAX = 4000
+const PRESETS_MAX = 120
+
+const PRESET_ID = /^[a-z0-9][a-z0-9-]{0,39}$/
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/
+const COMMANDER_ACTIONS = new Set(['approve', 'deny', 'stop', 'retry'])
+const ANSWER_KINDS = new Set(['option', 'allow', 'deny', 'retry'])
+const APPLIES = new Set(['any', 'asking', 'done', 'working', 'error'])
+const STATUSES = new Set(['asking', 'error', 'done', 'working', 'delegating', 'idle'])
+const THREADS_MAX = 100
+const SEEN_MAX = 100
+const RUN_BATCH = 50
+const APPROVALS = new Set(['approve', 'deny'])
+const HELD_KINDS = new Set(['approval', 'question'])
+const ASKS_MAX = 8
+const DELIVERIES = new Set(['now', 'queued', 'resumed'])
+const PASSED_ERRORS = new Set(['pro', 'not-found', 'uncertain', 'changed', 'setup', 'failed', 'bad-request', 'too-large'])
+
+export const tokenFile = (dataDir) => path.join(dataDir, 'agent-controls', 'apps', `${APP}.token`)
+
+const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v)
+const onlyKeys = (body, keys) => isPlainObject(body) && Object.keys(body).every((key) => keys.includes(key))
+const isThreadId = (v) => typeof v === 'string' && v.length > 0 && v.length <= THREAD_MAX && v.includes(':') && !CONTROL_CHARS.test(v)
+const isAnswerText = (v) => typeof v === 'string' && v.trim().length > 0 && v.length <= VALUE_MAX && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(v)
+
+export const checkAsksThread = (thread) => (isThreadId(thread) ? thread : null)
+
+export function keepAsks(answer) {
+  const asks = Array.isArray(answer?.asks) ? answer.asks : []
+  return {
+    can: answer?.can?.answer === true,
+    why: typeof answer?.why === 'string' ? clip(answer.why, WHY_MAX) : '',
+    asks: asks.filter((ask) => isPlainObject(ask) && isAskId(ask.id) && HELD_KINDS.has(ask.kind)).slice(0, ASKS_MAX).map((ask) => ({ id: ask.id, kind: ask.kind })),
+  }
+}
+
+export function checkRunBody(body) {
+  if (!onlyKeys(body, ['preset', 'threads', 'seen'])) return null
+  const { preset, threads } = body
+  if (typeof preset !== 'string' || !PRESET_ID.test(preset)) return null
+  if (!Array.isArray(threads) || !threads.length || threads.length > THREADS_MAX || !threads.every(isThreadId) || new Set(threads).size !== threads.length) return null
+  if (body.seen === undefined) return { preset, threads: [...threads] }
+  if (!isPlainObject(body.seen)) return null
+  const seen = Object.entries(body.seen)
+  if (!seen.length || seen.length > SEEN_MAX || !seen.every(([thread, ask]) => threads.includes(thread) && isAskId(ask))) return null
+  return { preset, threads: [...threads], seen: Object.fromEntries(seen) }
+}
+
+export function checkAnswerBody(body) {
+  if (!onlyKeys(body, ['thread', 'answer']) || !isThreadId(body.thread)) return null
+  const answer = body.answer
+  if (!isPlainObject(answer) || !ANSWER_KINDS.has(answer.kind)) return null
+  if (answer.id !== undefined && !isAskId(answer.id)) return null
+  const id = answer.id === undefined ? {} : { id: answer.id }
+  if (answer.kind !== 'option') return onlyKeys(answer, ['kind', 'id']) ? { thread: body.thread, answer: { kind: answer.kind, ...id } } : null
+  if (!onlyKeys(answer, ['kind', 'value', 'id'])) return null
+  const value = answer.value
+  const fine = isAnswerText(value) || (Array.isArray(value) && value.length > 0 && value.length <= OPTIONS_MAX && value.every(isAnswerText) && value.join('').length <= VALUE_MAX)
+  return fine ? { thread: body.thread, answer: { kind: 'option', value: Array.isArray(value) ? [...value] : value, ...id } } : null
+}
+
+const runnable = (preset) => preset.kind === 'prompt' || (preset.kind === 'action' && COMMANDER_ACTIONS.has(preset.action))
+
+function keepPreset(raw, builtIn) {
+  if (!isPlainObject(raw) || typeof raw.id !== 'string' || !PRESET_ID.test(raw.id)) return null
+  const kind = raw.kind === 'action' ? 'action' : raw.kind === 'prompt' ? 'prompt' : null
+  if (!kind || typeof raw.name !== 'string' || !raw.name.trim()) return null
+  const preset = { id: raw.id, name: clip(raw.name, NAME_MAX), kind, applies: APPLIES.has(raw.applies) ? raw.applies : 'any', confirm: raw.confirm === true, builtIn }
+  if (kind === 'action') preset.action = typeof raw.action === 'string' ? raw.action : ''
+  if (kind === 'prompt') {
+    if (typeof raw.text !== 'string' || !raw.text.trim()) return null
+    preset.text = raw.text.slice(0, PROMPT_MAX)
+  }
+  if (Array.isArray(raw.when)) preset.when = raw.when.filter((s) => STATUSES.has(s))
+  return runnable(preset) ? preset : null
+}
+
+export function keepPresets(answer) {
+  const list = (items, builtIn) => (Array.isArray(items) ? items.slice(0, PRESETS_MAX).map((p) => keepPreset(p, builtIn)).filter(Boolean) : [])
+  return { builtIn: list(answer?.builtIn, true), mine: list(answer?.mine, false) }
+}
+
+const outcome = {
+  off: () => ({ ok: false, error: 'off', why: 'Turn on “Let Threadnauts send” in Threadgauge’s Settings › Agent controls.' }),
+  missing: () => ({ ok: false, error: 'no-threadgauge', why: 'Threadgauge isn’t running.' }),
+  old: () => ({ ok: false, error: 'old', why: 'This Threadgauge is too old to send prompts and actions. Update it to send from Threadnauts.' }),
+}
+
+function sent(answer) {
+  const kept = { ok: true }
+  if (DELIVERIES.has(answer?.delivery)) kept.delivery = answer.delivery
+  return kept
+}
+
+function refused(answer, fallback) {
+  const error = typeof answer?.error === 'string' ? answer.error : ''
+  const kept = { ok: false, error: PASSED_ERRORS.has(error) ? error : 'failed', why: clip(typeof answer?.why === 'string' && answer.why ? answer.why : fallback, WHY_MAX) }
+  if (typeof answer?.fix?.text === 'string' && answer.fix.text) kept.fix = { text: clip(answer.fix.text, WHY_MAX) }
+  return kept
+}
+
+export function fromThreadgauge(status, answer) {
+  if (status >= 200 && status < 300 && answer?.ok !== false) return sent(answer)
+  const error = typeof answer?.error === 'string' ? answer.error : ''
+  if (status === 403 && (error === 'origin' || error === 'token')) return outcome.off()
+  if (status === 404 && error !== 'not-found') return outcome.old()
+  return refused(answer, `Threadgauge answered ${status}.`)
+}
+
+const UNSAID = { ok: false, error: 'failed', why: 'Threadgauge didn’t say what happened to it.' }
+
+export function resultsFromThreadgauge(threads, status, answer) {
+  if (!Array.isArray(answer?.results)) {
+    const whole = fromThreadgauge(status, answer)
+    return threads.map((thread) => ({ thread, ...(whole.ok ? UNSAID : whole) }))
+  }
+  const said = new Map(answer.results.filter((r) => r && typeof r.thread === 'string').map((r) => [r.thread, r]))
+  return threads.map((thread) => {
+    const result = said.get(thread)
+    return { thread, ...(!result ? UNSAID : result.ok === true ? sent(result) : refused(result, 'Threadgauge didn’t send it.')) }
+  })
+}
+
+export function threadbareCommander({ fetch = globalThis.fetch, find = () => locateThreadgauge({ fetch }), dataDir = () => threadcrumbsDataDir(), pro = async () => false, now = Date.now } = {}) {
+  let found = { at: -Infinity, where: null }
+  const forget = () => (found = { at: -Infinity, where: null })
+
+  async function where() {
+    if (now() - found.at > REUSE_FOUND_MS) found = { at: now(), where: await find() }
+    return found.where
+  }
+
+  async function readToken() {
+    try {
+      return (await fsp.readFile(tokenFile(dataDir()), 'utf8')).trim()
+    } catch {
+      return ''
+    }
+  }
+
+  async function read(origin, route, token = null) {
+    const response = await fetch(`${origin}${route}`, { ...(token ? { headers: { Authorization: `Bearer ${token}` } } : {}), signal: AbortSignal.timeout(READ_TIMEOUT_MS) })
+    return { status: response.status, answer: await response.json().catch(() => null) }
+  }
+
+  async function control(origin, route, body, token) {
+    const response = await fetch(`${origin}/api/threadbare/${route}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+    })
+    return { status: response.status, answer: await response.json().catch(() => null) }
+  }
+
+  async function reachable(shape, act) {
+    const token = await readToken()
+    if (!token) return shape(outcome.off())
+    const at = await where()
+    if (!at) return shape(outcome.missing())
+    try {
+      return await act(at.origin, token)
+    } catch {
+      forget()
+      return shape(outcome.missing())
+    }
+  }
+
+  async function state({ anotherDevice = false } = {}) {
+    if (anotherDevice) return { state: 'this-computer', url: null }
+    const at = await where()
+    if (!at) return { state: 'no-threadgauge', url: null }
+    let presets
+    try {
+      presets = await read(at.origin, '/api/threadbare/presets')
+    } catch {
+      forget()
+      return { state: 'no-threadgauge', url: null }
+    }
+    if (presets.status === 404) return { state: 'old', url: at.url }
+    const allowed = Boolean(await readToken())
+    return { state: allowed ? 'ready' : 'off', url: at.url, pro: Boolean(await pro()), presets: keepPresets(presets.answer) }
+  }
+
+  async function runBatch(origin, token, body) {
+    try {
+      const { status, answer: said } = await control(origin, 'run', body, token)
+      return resultsFromThreadgauge(body.threads, status, said)
+    } catch {
+      forget()
+      return null
+    }
+  }
+
+  function run({ preset, threads, seen = {} }) {
+    const each = (whole) => ({ results: threads.map((thread) => ({ thread, ...whole })) })
+    return reachable(each, async (origin, token) => {
+      const presets = await read(origin, '/api/threadbare/presets')
+      if (presets.status === 404) return each(outcome.old())
+      const { builtIn, mine } = keepPresets(presets.answer)
+      const found = [...builtIn, ...mine].find((p) => p.id === preset)
+      if (!found) return each({ ok: false, error: 'not-found', why: 'That prompt or action isn’t one the Commander can send from Threadgauge now.' })
+      const approval = found.kind === 'action' && APPROVALS.has(found.action)
+      const sendable = approval ? threads.filter((thread) => Object.hasOwn(seen, thread)) : threads
+      const said = new Map()
+      let gone = false
+      for (let at = 0; at < sendable.length; at += RUN_BATCH) {
+        const batch = sendable.slice(at, at + RUN_BATCH)
+        const body = approval ? { preset, threads: batch, seen: Object.fromEntries(batch.map((thread) => [thread, seen[thread]])) } : { preset, threads: batch }
+        const results = gone ? null : await runBatch(origin, token, body)
+        gone = !results
+        for (const result of results ?? batch.map((thread) => ({ thread, ...outcome.missing() }))) said.set(result.thread, result)
+      }
+      const unseen = { ok: false, error: 'changed', why: 'Threadnauts didn’t show what it asks, so it wasn’t answered.' }
+      return { results: threads.map((thread) => said.get(thread) ?? { thread, ...unseen }) }
+    })
+  }
+
+  function answer({ thread, answer: given }) {
+    return reachable((whole) => whole, async (origin, token) => {
+      const { status, answer: said } = await control(origin, 'answer', { thread, answer: given }, token)
+      return fromThreadgauge(status, said)
+    })
+  }
+
+  function asks({ thread }) {
+    return reachable((whole) => whole, async (origin, token) => {
+      const { status, answer: said } = await read(origin, `/api/threadbare/reach?thread=${encodeURIComponent(thread)}`, token)
+      return status === 200 ? { ok: true, ...keepAsks(said) } : fromThreadgauge(status, said)
+    })
+  }
+
+  return { state, run, answer, asks }
+}