@rhizogrip/spore-plugin-telegram 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+spore-plugin-telegram
+Copyright 2026 Christophe Le Bars <clb@toort.net>

package/README.md

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# @rhizogrip/spore-plugin-telegram
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A service that puts your spores in Telegram chats. It runs on the machine the spores are
+on, once per bot, as a systemd user unit, and it is an application against the package:
+everything it does goes through `@rhizogrip/spore`'s exports. It gives spores nothing, so it needs
+no `spore plugin allow`: `spore service` offers it once it is installed.
+
+```bash
+npm i -g @rhizogrip/spore-plugin-telegram
+echo 'TRIAGE_BOT_TOKEN=…' >> ~/.config/spore/environment     # from @BotFather; it never reaches a spore
+mkdir -p ~/.config/spore/telegram
+echo '{"token": "${TRIAGE_BOT_TOKEN}", "chats": {"148392011": "triage"}}' > ~/.config/spore/telegram/triage.json
+spore service define telegram@triage && spore service start telegram@triage
+```
+
+It refuses to start, with exit status 2 and the line to fix, without its bot file, without
+the token the file names, without a Telegram that answers the token, with a state file it
+cannot read, or while another process reads the same bot's updates.
+
+## One bot per file
+
+Each bot is a file, `~/.config/spore/telegram/<bot>.json`, and a service instance of its
+own, `telegram@<bot>`: its name, its avatar, its token, its chats and its state. A spore that
+should have a face of its own on Telegram gets its own bot. One bot may still reach several
+spores, and one spore may be reached through several bots. A chat of a bot is
+`telegram:<bot>/<chat id>` wherever spore names a place an answer goes. No bot's token is
+passed to a spore's runner.
+
+## What it guarantees
+
+- **A message reaches its spore once.** An update is confirmed to Telegram only after
+  `send` has taken it, and it goes to `send` under `telegram:<update_id>` as its
+  `requestId`, so an update Telegram hands over again is not said twice.
+- **A finished turn reaches its chat at least once.** What it owes a chat is an entry in the
+  spore's outbox, settled only after Telegram accepted it; a crash between the two repeats a
+  message rather than losing one. One Telegram will not take is settled refused, with
+  Telegram's reason, and one it still had not taken when its retries ran out is tried again
+  after the spore's next turn or the service's next start.
+- **A reply is its own turn's.** The answer, how the turn ended and what it handed back
+  come from the turn as `watchAll` yields it — its record, whose `output` is the answer, and
+  the messages it answered as `asked`.
+- **A restart loses nothing.** A turn running when the service stopped finishes into the
+  chat's `working…` message; a turn that ended while it was down is posted when it is back.
+- **Nothing fails in silence.** A message a spore refuses is told to the chat; a message
+  Telegram will not take is logged with its chat and turn.
+
+## A turn in a chat
+
+Write to the bot and the message goes to the spore the chat is mapped to. The bot posts
+`working…`, shows which tools run as they run, and edits the answer into that message when
+the turn ends. How the turn ended is added only when it makes the answer partial — a wrap
+or a stop. A longer answer than Telegram's 4096 continues in further messages. What the
+turn left in `data/out/` follows as documents; a file over Telegram's 50 MB is named
+instead.
+
+A message sent while a turn runs lands between its rounds, because that is what `send`
+does, and its `working…` message says it was heard. A turn ending in a question posts the
+question, and the reply answers it. The conversation is the spore's transcript; the service
+keeps none.
+
+A turn that ends without reading your message — one that failed before it got there —
+says so in your `working…` message, and the next turn answers it there.
+
+```
+/status    what the spore is doing, its turns and what they cost, and the running turn's limits
+/stop      end the turn it is running
+/wrap [10m]        ask the running turn to wrap up, now or in a while
+/extend wall 30m   give it more — wall, cost or rounds — up to the extend.<limit> its spore.cmk grants
+```
+
+Only text reaches a spore for now.
+
+## Turns nobody in a chat started
+
+A schedule firing, a job or a webhook starts a turn no chat asked for. Its answer goes to the
+spore's default place, `replyTo` in `config.json`:
+
+```json
+{ "replyTo": { "triage": "telegram:triage/148392011" } }
+```
+
+There it is told `schedule "digest"`, `webhook "forge"` or `job "scan"`, then the answer —
+except when the turn ended `quiet`, which chose to say nothing. A turn that ended without an
+answer any other way is told. A spore with no default tells no chat. A default naming a chat
+that does not reach the spore through this bot is refused, and the log says why.
+
+A turn a terminal asked for is the terminal's: `spore send` follows it, and no chat is told.
+
+## The allow-list is the routing
+
+A bot's `chats` say which chats may talk to it and which spore each reaches, as
+`{ "<chat id>": "<spore>" }`. They are read on every message and followed as they change, so
+a chat is added, moved or removed by editing a line. It lives beside `config.json` and
+`sources.json`: it says who reaches what, and nothing a confined agent reads may say that.
+
+While a turn works, its chat is shown what kind of call ran — `reading a file`, `running a
+command`, `asking forgejo` by the source's name, a run of the same one counted, a slow one
+timed, a failed one marked — and never what it was given: a Telegram message leaves the
+machine, and a command line or a path is yours. A chat can ask for the calls themselves:
+
+```json
+{ "token": "${MAIN_BOT_TOKEN}", "chats": { "51168024": { "spore": "main", "details": true } } }
+```
+
+It is then shown `reading data/report.md`, `running git log --oneline -5`,
+`source forgejo --path …` — the first line, cut short. Choose it for a chat you would let
+read the commands; the others keep the kinds.
+
+Two chats may point at one spore and then share its conversation. A reply goes to the
+chat that asked; a turn nobody in a chat started goes to the spore's default.
+
+A chat not in the file gets silence, and the log gets the line to add:
+
+```
+refused chat 148392011 (@alice) — to allow it, add "148392011": "<a spore>" to the chats of …/telegram/triage.json
+```
+
+which is also how you learn your own chat id: start with `"chats": {}` and message the bot. A
+group's id is negative, and it is the group you add rather than the people in it.
+
+## What a chat is told
+
+Which tool ran, and whether it worked — never its arguments or its result. On a console
+those are the point; in a chat they are a path or a command line leaving the machine.
+`forward.js` is that rule. The answer and the stop reason cross in full.
+
+## What it keeps
+
+`$XDG_STATE_HOME/spore/telegram/<bot>/state.json`, one per bot, written whole and renamed into
+place: where it stands in each spore it follows, in that spore's database, and every message a chat sent that no turn has answered
+yet, with the `working…` message its answer goes into. What a turn owes a chat is not kept
+here: it is the spore's outbox. A spore it starts following starts from where it is. Nothing
+is kept in the repository or in the spores' home.
+
+## Busy
+
+A turn that would start with no admission slot free is refused, and the chat is told it is
+busy. There is no bound of the service's own: the user's slots are the one bound, shared with every other caller.
+
+## Running it as a service
+
+```bash
+spore service define telegram@triage     # checks the bot file and its token, then writes the unit
+spore service start telegram@triage      # now
+spore service enable telegram@triage     # and at every login
+spore service log telegram@triage -f
+```
+
+`define` runs the service's own start-up checks (`spore-telegram.js <bot> --check`) first, so a
+missing bot file or token is refused there rather than as a unit that keeps failing. The unit it
+writes is the template `~/.config/systemd/user/spore-telegram@.service`, marked as spore's, and
+each bot is an instance of it; `spore service` never touches a unit it did not write. `spore
+service rm telegram@<bot>` stops and disables one bot; `spore service rm telegram` stops them all
+and removes the template — each given `--yes` when a bot it stops is running. `spore service ls` says where each service
+stands, and whether lingering is on — without it, user services stop when you log out.
+
+The unit keeps a restart of the service from being a stop of every turn it started
+(`KillMode=process`): their runners are in its control group, and systemd otherwise kills
+the whole group. The service picks them up again from what it saved. A refusal — exit 2 —
+is left refused rather than retried every few seconds.
+
+`~/.config/spore/environment` is what the service and every runner it starts need, since a
+systemd user session starts with almost nothing: each bot's token, `PATH`, the provider
+keys (`<PROVIDER>_API_SK`), `BRAVE_API_SK` if the spores search, and the secrets of the
+sources they are granted. The service reads it itself, so the unit names no environment file:
+its bot's token once, at start, and everything else again for every turn, so a key added or
+changed reaches the next message without a restart. A variable already set in the service's
+own environment wins. Plain `KEY=value` lines, as systemd's `EnvironmentFile=` would read them —
+no `export`, nothing expanded. It holds keys, so keep it mode 0600. The token stays with the
+service; the runners it starts are given the rest.
+
+A running service keeps the code it started from. After installing another version of this
+plugin, `spore service ls` says so — `running @rhizogrip/spore-plugin-telegram 0.1.0, 0.1.1 is
+installed` — and `spore service restart --outdated` brings it up to date.
+
+It imports `@rhizogrip/spore`, declared as a peer. Installed globally beside
+`@rhizogrip/spore-cli`, it gets a copy of its own, which may be another version within the
+range it declares; a workspace another version made is refused at open, never misread.

package/bin/spore-telegram.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { loadEnvironment, recordStarted } from '@rhizogrip/spore'
+
+import { createTelegram } from '../src/api.js'
+import { allowed, botNames, botPath, botsDir, botToken } from '../src/bots.js'
+import { createService } from '../src/service.js'
+import { statePath } from '../src/state.js'
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+const REFUSED = 2
+
+const log = (line) => console.error(`${new Date().toISOString()} ${line}`)
+
+const refuse = (err, hint) => {
+  console.error(`spore-telegram: ${err.message}`)
+  if (err.detail) console.error(`  ${err.detail}`)
+  if (hint) console.error(`  ${hint}`)
+  process.exit(REFUSED)
+}
+
+const bot = process.argv.slice(2).find(arg => !arg.startsWith('--'))
+if (!bot) {
+  refuse(new Error('which bot?'), `spore-telegram <bot> runs ${botsDir()}/<bot>.json${botNames().length ? ` — here: ${botNames().join(', ')}` : ''}`)
+}
+
+const launched = { ...process.env }
+try {
+  loadEnvironment()
+} catch (err) {
+  refuse(err)
+}
+
+let file
+let telegram
+try {
+  file = botPath(bot)
+  allowed(file)
+  telegram = createTelegram(botToken(file, process.env))
+} catch (err) {
+  const variable = `${bot.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_BOT_TOKEN`
+  refuse(err, err.type === 'TELEGRAM_NO_BOT'
+    ? `mkdir -p ${botsDir()} && echo '{"token": "$\{${variable}}", "chats": {}}' > ${file}\n  with chats {}, start the bot and message it — the log names every chat it refuses, with its id`
+    : null)
+}
+
+let me
+try {
+  me = await telegram.me()
+} catch (err) {
+  refuse(err, `the token comes from @BotFather, in the variable ${file} names`)
+}
+
+const state = statePath(bot)
+let service
+try {
+  service = createService({ telegram, botFile: file, statePath: state, env: launched, log })
+} catch (err) {
+  refuse(err)
+}
+
+if (process.argv.includes('--check')) {
+  console.log(`spore-telegram ${bot} · @${me.username} · ${file} · state ${state} · ready`)
+  process.exit(0)
+}
+
+const controller = new AbortController()
+for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => controller.abort())
+
+recordStarted(`telegram@${bot}`, { root: ROOT })
+log(`spore-telegram ${bot} · @${me.username} · ${file} · state ${state}`)
+try {
+  await service.run(controller.signal)
+} catch (err) {
+  if (err.type === 'TELEGRAM_CONFLICT') refuse(err, 'one bot token is read by one process — stop the other one, or remove its webhook')
+  log(`stopped — ${err.message}${err.detail ? ` — ${err.detail}` : ''}`)
+  process.exit(1)
+}
+log('stopped')
+process.exit(0)

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@rhizogrip/spore-plugin-telegram",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Telegram for spores: a bot of yours in chats, each chat reaching its spore, run as a service",
+  "author": {
+    "name": "Christophe Le Bars",
+    "email": "clb@toort.net"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RHIZOGRIP/spore.git",
+    "directory": "plugins/telegram"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "NOTICE"
+  ],
+  "peerDependencies": {
+    "@rhizogrip/spore": "^1"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "spore": {
+    "works": "^1",
+    "services": {
+      "telegram": {
+        "what": "a bot of yours in Telegram chats, each chat reaching its spore",
+        "program": "./bin/spore-telegram.js",
+        "instances": {
+          "dir": "telegram",
+          "ext": ".json",
+          "called": "bot"
+        },
+        "check": [
+          "--check"
+        ]
+      }
+    }
+  },
+  "release-it": {
+    "git": {
+      "requireBranch": "main",
+      "commitMessage": "release: plugin-telegram v${version}",
+      "tagName": "plugin-telegram-v${version}",
+      "requireUpstream": false,
+      "push": true
+    },
+    "npm": {
+      "publish": false
+    },
+    "github": {
+      "release": false
+    }
+  },
+  "license": "Apache-2.0"
+}

package/src/api.js

@@ -0,0 +1,69 @@
+/**
+ * Every failure is a `TELEGRAM_FAILED`, `retryable` or not, with `context.status` and
+ * `context.retryAfter` (seconds, when Telegram said how long to wait). A request that never
+ * reached Telegram is retryable.
+ */
+
+import { readFileSync } from 'node:fs'
+import { basename } from 'node:path'
+
+import { SporeError } from '@rhizogrip/spore'
+
+const BASE = 'https://api.telegram.org'
+
+export function createTelegram (token, { fetchImpl = fetch, base = BASE } = {}) {
+  if (!token) {
+    throw new SporeError('no bot token', {
+      type: 'TELEGRAM_UNCONFIGURED',
+      detail: 'a bot file names the variable holding its token from @BotFather; it never reaches a spore'
+    })
+  }
+
+  const call = async (method, body, { timeoutMs = 60_000, signal } = {}) => {
+    const timeout = AbortSignal.timeout(timeoutMs)
+    const form = body instanceof FormData
+    let response
+    try {
+      response = await fetchImpl(`${base}/bot${token}/${method}`, {
+        method: 'POST',
+        ...(form ? {} : { headers: { 'content-type': 'application/json' } }),
+        body: form ? body : JSON.stringify(body ?? {}),
+        signal: signal ? AbortSignal.any([signal, timeout]) : timeout
+      })
+    } catch (err) {
+      if (signal?.aborted) throw err
+      throw new SporeError(`telegram ${method} failed`, { type: 'TELEGRAM_FAILED', detail: err.message, retryable: true, context: { status: null, retryAfter: null } })
+    }
+    const answer = await response.json().catch(() => null)
+    if (!answer?.ok) {
+      throw new SporeError(`telegram ${method} failed`, {
+        type: 'TELEGRAM_FAILED',
+        detail: answer?.description || `HTTP ${response.status}`,
+        retryable: response.status >= 500 || response.status === 429,
+        context: { status: response.status, retryAfter: answer?.parameters?.retry_after ?? null }
+      })
+    }
+    return answer.result
+  }
+
+  return {
+    /** `offset` confirms every update before it to Telegram. */
+    updates: (offset, { seconds = 30, signal } = {}) =>
+      call('getUpdates', { offset, timeout: seconds, allowed_updates: ['message'] }, { timeoutMs: (seconds + 15) * 1000, signal }),
+
+    say: (chat, text) => call('sendMessage', { chat_id: chat, text, link_preview_options: { is_disabled: true } }),
+
+    revise: (chat, message, text) =>
+      call('editMessageText', { chat_id: chat, message_id: message, text, link_preview_options: { is_disabled: true } }),
+
+    document: (chat, { path, mime }, caption) => {
+      const form = new FormData()
+      form.append('chat_id', String(chat))
+      form.append('caption', caption)
+      form.append('document', new Blob([readFileSync(path)], { type: mime }), basename(path))
+      return call('sendDocument', form, { timeoutMs: 300_000 })
+    },
+
+    me: () => call('getMe')
+  }
+}

package/src/bots.js

@@ -0,0 +1,116 @@
+/**
+ * The bots: for each, its token and who may talk to it, and to which spore.
+ *
+ * One file per bot, `telegram/<bot>.json` beside `config.json`, because a bot is a face a spore
+ * shows on Telegram and each runs as a service instance of its own. The routing is in the same
+ * file because a bot needs it anyway: a chat absent from it is refused. Beside `config.json` and
+ * `sources.json`, for the same reason — it says who reaches what, and nothing a confined agent can
+ * read may say that. The token is `${VAR}`, from the environment, never kept in the file.
+ *
+ * Spores keep the names a person gave them. Deriving one per chat would forbid what the routing
+ * allows: two chats on one spore, a spore reached through two bots, or a chat moved to another
+ * spore by editing a line. Restricting any of it is policy, and policy about chats lives above
+ * spore.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+
+import { CONFIG_FILE, SporeError } from '@rhizogrip/spore'
+
+export const BOTS_DIR = 'telegram'
+const NAME = /^[a-z0-9][a-z0-9._-]*$/i
+const VARIABLE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/
+
+export const botsDir = (configFile = CONFIG_FILE) => resolve(dirname(configFile), BOTS_DIR)
+
+export function botPath (name, configFile = CONFIG_FILE) {
+  if (!NAME.test(name)) {
+    throw new SporeError(`"${name}" cannot be a bot's name`, { type: 'TELEGRAM_BOT_INVALID', detail: 'letters, digits, ., - and _' })
+  }
+  return join(botsDir(configFile), `${name}.json`)
+}
+
+export function botNames (configFile = CONFIG_FILE) {
+  const dir = botsDir(configFile)
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).filter(file => file.endsWith('.json')).map(file => basename(file, '.json')).sort()
+}
+
+function read (path) {
+  if (!existsSync(path)) {
+    throw new SporeError(`no ${path}`, {
+      type: 'TELEGRAM_NO_BOT',
+      detail: 'it names the bot\'s token and which chats may talk to it, as { "token": "${VAR}", "chats": { "<chatId>": "<spore>" } } — a bot with no chats is an open door to something that spends money' // eslint-disable-line no-template-curly-in-string
+    })
+  }
+  let raw
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'))
+  } catch (err) {
+    throw new SporeError(`${path} is not readable JSON`, { type: 'TELEGRAM_BOT_INVALID', detail: err.message })
+  }
+  const unknown = Object.keys(raw ?? {}).filter(key => !['token', 'chats'].includes(key))
+  if (unknown.length) throw new SporeError(`${path} has a field spore does not know — ${unknown.join(', ')}`, { type: 'TELEGRAM_BOT_INVALID', detail: 'a bot has a token and chats' })
+  if (typeof raw.token !== 'string' || !VARIABLE.test(raw.token)) {
+    throw new SporeError(`${path} has no token spore can read`, {
+      type: 'TELEGRAM_BOT_INVALID',
+      detail: 'token names the variable holding the token from @BotFather, as "${REVIEWER_BOT_TOKEN}", set in environment beside config.json' // eslint-disable-line no-template-curly-in-string
+    })
+  }
+  if (typeof raw.chats !== 'object' || raw.chats === null || Array.isArray(raw.chats)) {
+    throw new SporeError(`${path} has no chats`, {
+      type: 'TELEGRAM_BOT_INVALID',
+      detail: 'chats is { "<chatId>": "<spore>" } — {} while you learn your chat id: the log names every chat it refuses'
+    })
+  }
+  return raw
+}
+
+/**
+ * `{ "<chatId>": "<spore>" }`, or `{ "<chatId>": { "spore": "<spore>", "details": true } }` for a
+ * chat shown what each call does — its command or path — rather than only what kind of call it
+ * is: a Telegram message leaves the machine, so that is a choice made per chat. Read on every
+ * update rather than held: adding a chat should not need a restart.
+ */
+function entries (path) {
+  return Object.entries(read(path).chats).map(([chat, entry]) => {
+    const spore = typeof entry === 'string' ? entry : entry?.spore
+    const extra = typeof entry === 'object' && entry !== null ? Object.keys(entry).filter(key => !['spore', 'details'].includes(key)) : []
+    if (typeof spore !== 'string' || !spore || extra.length || (typeof entry === 'object' && entry.details !== undefined && typeof entry.details !== 'boolean')) {
+      throw new SporeError(`${path} maps ${chat} to something that is not a spore`, {
+        type: 'TELEGRAM_BOT_INVALID',
+        detail: 'each chat is a chat id against the name of a spore it may reach, or { "spore": "<name>", "details": true }'
+      })
+    }
+    return { chat, spore, details: typeof entry === 'object' && entry.details === true }
+  })
+}
+
+export function allowed (path) {
+  return Object.fromEntries(entries(path).map(({ chat, spore }) => [chat, spore]))
+}
+
+/** The chats shown each call's command or path, by id. */
+export function detailedChats (path) {
+  return new Set(entries(path).filter(entry => entry.details).map(entry => Number(entry.chat)))
+}
+
+export const tokenVariable = (path) => VARIABLE.exec(read(path).token)[1]
+
+export function botToken (path, env) {
+  const variable = tokenVariable(path)
+  if (!env[variable]) {
+    throw new SporeError(`${path} wants $${variable}, which is not set`, {
+      type: 'TELEGRAM_NO_TOKEN',
+      detail: 'the token from @BotFather goes in environment beside config.json; it never reaches a spore'
+    })
+  }
+  return env[variable]
+}
+
+/**
+ * Every variable a bot here keeps its token in: none of them is passed to a spore's runner. A bot
+ * file that cannot be read is refused rather than skipped, since its token would pass unnoticed.
+ */
+export const tokenVariables = (configFile = CONFIG_FILE) => botNames(configFile).map(name => tokenVariable(botPath(name, configFile)))

package/src/delivery.js

@@ -0,0 +1,28 @@
+export function createDelivery ({ sleep, signal, now = Date.now, giveUpMs = 10 * 60_000 }) {
+  const chains = new Map()
+
+  const attempt = async (step) => {
+    const started = now()
+    let backoff = 1000
+    for (;;) {
+      try {
+        return await step()
+      } catch (err) {
+        if (!err.retryable || signal.aborted || now() - started > giveUpMs) throw err
+        const after = err.context?.retryAfter
+        await sleep(after ? after * 1000 : backoff)
+        backoff = Math.min(backoff * 2, 60_000)
+      }
+    }
+  }
+
+  const to = (chat, work) => {
+    const next = (chains.get(chat) ?? Promise.resolve()).then(() => work(attempt))
+    const settled = next.catch(() => {})
+    chains.set(chat, settled)
+    settled.then(() => { if (chains.get(chat) === settled) chains.delete(chat) })
+    return next
+  }
+
+  return { to, attempt }
+}

package/src/forward.js

@@ -0,0 +1,136 @@
+/**
+ * What a chat is told while a turn works: what kind of call ran — reading a file, running a
+ * command, asking a source by the name its host gave it — and never what it was given or what
+ * came back. A Telegram message leaves the machine, and a command line or a path is the
+ * operator's. A chat whose allow-list entry says `details` is shown the command or the path as
+ * well: that is a choice made per chat. The answer and the stop reason cross in full.
+ */
+
+export const MAX_MESSAGE = 4096
+
+const PLAIN_ENDINGS = new Set(['answer', 'question'])
+
+const LONGEST = 70
+const SLOW_MS = 5000
+
+// Spore's own programs, by the variable an agent runs them through, and what each is called.
+const PROGRAMS = [
+  [/^node\s+"?\$SPORE_SOURCE"?\s*/, 'source '],
+  [/^node\s+"?\$SPORE_FANOUT"?\s*/, 'fanout '],
+  [/^"?\$SPORE_BROWSER"?\s*/, 'browser '],
+  [/^"?\$SPORE_BRAVE"?\s*/, 'search '],
+  [/^"?\$SPORE_SPAWN"?\s*/, 'spawn '],
+  [/^"?\$SPORE_SQL"?\s*/, 'sql ']
+]
+
+const firstLine = (text) => String(text ?? '').split('\n')[0].replace(/\s+/g, ' ').trim()
+const cut = (text) => (text.length > LONGEST ? `${text.slice(0, LONGEST - 1)}…` : text)
+
+function kind (line) {
+  const source = /^node\s+"?\$SPORE_SOURCE"?\s+([\w.-]+)/.exec(line)
+  if (source) return `asking ${source[1]}`
+  if (/^"?\$SPORE_BROWSER/.test(line)) return 'using the browser'
+  if (/^"?\$SPORE_BRAVE/.test(line)) return 'searching the web'
+  if (/^(node\s+"?\$SPORE_FANOUT|"?\$SPORE_SPAWN)/.test(line)) return 'starting sub-agents'
+  if (/^"?\$SPORE_SQL/.test(line)) return 'reading its records'
+  return 'running a command'
+}
+
+function command (text) {
+  const line = firstLine(text)
+  const plain = kind(line)
+  const program = PROGRAMS.find(([pattern]) => pattern.test(line))
+  const detailed = program ? cut(line.replace(program[0], program[1]).trim()) : `running ${cut(line)}`
+  return { plain, detailed }
+}
+
+/** A call as a chat is told it, plainly and in detail, or null for one it has no use for. */
+export function describe (event) {
+  const { name, args = {} } = event
+  const file = (verb, noun) => ({ plain: `${verb} a ${noun}`, detailed: `${verb} ${cut(firstLine(args.path))}` })
+  if (name === 'read') return file('reading', 'file')
+  if (name === 'write') return file('writing', 'file')
+  if (name === 'edit') return file('editing', 'file')
+  if (name === 'exec' || name === 'wsexec') return command(args.command)
+  if (name === 'ask' || name === 'quiet') return null
+  return { plain: name, detailed: name }
+}
+
+/**
+ * A turn's events folded into what a chat is shown: a call when it starts, its time once it
+ * ends slow, and that it failed. Returns whether anything changed.
+ */
+export function track (items, event) {
+  if (event.event === 'tool_start') {
+    const told = describe(event)
+    if (!told) return false
+    items.push({ callId: event.callId, ...told })
+    return true
+  }
+  if (event.event === 'tool_end') {
+    const item = items.find(i => i.callId === event.callId)
+    if (!item) return false
+    item.durationMs = event.durationMs
+    item.failed = Boolean(event.error)
+    return item.failed || item.durationMs >= SLOW_MS
+  }
+  const note = (text) => {
+    items.push({ plain: text, detailed: text })
+    return true
+  }
+  if (event.event === 'wrap') return note(`wrapping up — reached its ${event.dimension} limit`)
+  if (event.event === 'interject') return note('heard you')
+  return false
+}
+
+/** The lines a chat sees, the last few, a run of the same call counted rather than repeated. */
+export function render (items, { detailed = false, last = 6 } = {}) {
+  const lines = []
+  for (const item of items) {
+    const text = (detailed ? item.detailed : item.plain) +
+      (item.failed ? ' — failed' : '') +
+      (item.durationMs >= SLOW_MS ? ` — ${Math.round(item.durationMs / 1000)} s` : '')
+    const previous = lines.at(-1)
+    if (previous?.text === text) previous.count++
+    else lines.push({ text, count: 1 })
+  }
+  return lines.slice(-last).map(({ text, count }) => `· ${text}${count > 1 ? ` ×${count}` : ''}`)
+}
+
+const ending = (record) => [record.stopReason, record.error].filter(Boolean).join(' · ')
+
+export function reply ({ record }) {
+  const { output } = record
+  if (output) return PLAIN_ENDINGS.has(record.stopReason) ? output : `${output}\n\n— ${ending(record)}`
+  if (record.stopReason === 'quiet') return 'nothing to say'
+  return `no answer · ${ending(record)}`
+}
+
+/** What a chat is told of a turn that answered `asked`, none of it said in a chat: who said it, then the answer. */
+export function announce ({ record, asked }) {
+  const named = (field) => [...new Set(asked.filter(entry => entry[field]).map(entry => `"${entry[field]}"`))]
+  const origins = [
+    named('schedule').length ? `schedule ${named('schedule').join(', ')}` : null,
+    named('hook').length ? `webhook ${named('hook').join(', ')}` : null,
+    named('job').length ? `job ${named('job').join(', ')}` : null
+  ].filter(Boolean)
+  return `${origins.length ? origins.join(' · ') : 'sent from elsewhere'}\n\n${reply({ record })}`
+}
+
+/** A turn ended without reading this chat's message, and nothing is running to read it. */
+export function waiting ({ record }) {
+  return `no answer yet · ${ending(record)} — your message waits for the next turn`
+}
+
+export function pieces (text, limit = MAX_MESSAGE) {
+  const out = []
+  let rest = String(text)
+  while (rest.length > limit) {
+    const cut = rest.lastIndexOf('\n', limit)
+    const at = cut > limit / 2 ? cut : limit
+    out.push(rest.slice(0, at))
+    rest = rest.slice(at).replace(/^\n/, '')
+  }
+  if (rest) out.push(rest)
+  return out
+}

package/src/service.js

@@ -0,0 +1,409 @@
+import { existsSync, statSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+
+import { CONFIG_FILE, changeText, databaseOf, durationText, extendTurn, isWorkspace, lastEventSeq, loadEnvironment, outbox, readConfig, RUNNING, runningLines, send, settleOutbox, show, SporeError, stateOf, stop, turnsSince, watchAll, workspaceFor, wrapTurn } from '@rhizogrip/spore'
+import { allowed, detailedChats, tokenVariables } from './bots.js'
+import { createDelivery } from './delivery.js'
+import { announce, pieces, render, reply, track, waiting } from './forward.js'
+import { loadState, saveState } from './state.js'
+
+const MAX_DOCUMENT = 50 * 1024 * 1024
+const COMMAND = /^\/([a-z]+)(@\w+)?(?:\s+(.+))?$/is
+const NOT_MODIFIED = /message is not modified/
+const TAKES_ARGUMENTS = new Set(['extend', 'wrap'])
+const HELP = 'Anything you write here goes to the spore. /status says what it is doing; /stop ends the turn it is running; /wrap [10m] asks it to wrap up; /extend wall 30m gives it more, as far as its spore.cmk allows.'
+
+const pause = (ms, signal) => new Promise(resolve => {
+  const timer = setTimeout(resolve, ms)
+  signal.addEventListener('abort', () => { clearTimeout(timer); resolve() }, { once: true })
+})
+
+const said = (err) => [err.message, err.detail].filter(Boolean).join(' — ')
+
+/**
+ * One bot, routed by `botFile`. `env` is the environment the service was started with, before
+ * `environment` beside `config.json` was read: that file is read again for every turn, so a key
+ * added to it reaches the next turn without a restart, and a variable the service was started with
+ * still wins. No bot's token is passed on.
+ */
+export function createService ({ telegram, botFile, statePath, env, log, configFile = CONFIG_FILE, sleep = pause, editEveryMs = 2500, followEveryMs = 1000 }) {
+  const sendEnv = () => {
+    const fresh = { ...env }
+    loadEnvironment(configFile, fresh)
+    for (const variable of tokenVariables(configFile)) delete fresh[variable]
+    return fresh
+  }
+  const replyTo = `telegram:${basename(botFile, '.json')}/`
+  const state = loadState(statePath)
+  const stopping = new AbortController()
+  const delivery = createDelivery({ sleep: (ms) => sleep(ms, stopping.signal), signal: stopping.signal })
+  const notes = new WeakMap()
+  const shown = new Map()
+  let chatsOf = new Map()
+  let detailed = new Set()
+  let routeFailure = null
+
+  const save = () => saveState(statePath, state)
+  const noteOf = (entry) => notes.get(entry) ?? Promise.resolve(entry.message)
+
+  const route = () => {
+    const config = readConfig(configFile)
+    return { config, table: allowed(botFile), detailed: detailedChats(botFile) }
+  }
+  const sporeOf = (name, config) => {
+    const ws = workspaceFor(name, { config }).path
+    return isWorkspace(ws) ? ws : null
+  }
+
+  const tell = (chat, text) => delivery.to(chat, async (attempt) => {
+    for (const part of pieces(text)) await attempt(() => telegram.say(chat, part))
+  }).catch(err => log(`chat ${chat}: not delivered — ${said(err)}`))
+
+  const edit = async (attempt, chat, message, text) => {
+    const [first, ...rest] = pieces(text)
+    if (message === null) {
+      await attempt(() => telegram.say(chat, first))
+    } else {
+      try {
+        await attempt(() => telegram.revise(chat, message, first))
+      } catch (err) {
+        if (!NOT_MODIFIED.test(err.detail ?? '')) {
+          if (err.retryable) throw err
+          log(`chat ${chat}: message ${message} cannot be edited (${err.detail}), sending the text anew`)
+          await attempt(() => telegram.say(chat, first))
+        }
+      }
+    }
+    for (const part of rest) await attempt(() => telegram.say(chat, part))
+  }
+
+  const hand = async (attempt, chat, ws, files) => {
+    for (const file of files) {
+      const path = resolve(ws, file.path)
+      if (!existsSync(path)) {
+        await attempt(() => telegram.say(chat, `${file.path} is no longer there`))
+        continue
+      }
+      const bytes = statSync(path).size
+      if (bytes > MAX_DOCUMENT) {
+        await attempt(() => telegram.say(chat, `${file.path} is ${(bytes / 1024 / 1024).toFixed(0)} MB, more than Telegram takes; it is in the spore's workspace`))
+        continue
+      }
+      await attempt(() => telegram.document(chat, { path, mime: file.mime }, file.path))
+    }
+  }
+
+  const status = (ws) => {
+    const one = show({ ws, configFile })
+    return [
+      `${one.name} · ${one.model}`,
+      `${one.state}${one.draining ? ', finishing' : ''} · ${one.lastTurnNo} turns · ${one.billing !== null && one.billing.kind !== 'metered' ? `not metered · ${one.billing.label}` : `$${one.treeUsd.toFixed(4)}`}`,
+      ...(one.turnLimits ? runningLines(one.turnLimits, one.extend) : []),
+      one.last ? `last: ${[one.last.stopReason, one.last.error].filter(Boolean).join(' · ')}` : null,
+      one.waiting ? `${one.waiting} waiting` : null,
+      one.paused ? `paused${one.paused.at ? ` since ${one.paused.at}` : ''}${one.paused.why ? ` (${one.paused.why})` : ''}` : null,
+      one.held.length ? `${one.held.length} routed to wait` : null,
+      ...one.jobs.running.map(job => `job ${job.name}: ${durationText(Date.now() - Date.parse(job.startedAt))} of ${durationText(job.wallMs)}${job.progress ? ` · ${job.progress}` : ''}`)
+    ].filter(Boolean).join('\n')
+  }
+
+  const change = (chat, ws, act) => {
+    let answer
+    try {
+      answer = act()
+    } catch (err) {
+      return tell(chat, said(err))
+    }
+    return tell(chat, changeText(answer))
+  }
+
+  const obey = (chat, ws, command, args = '') => {
+    if (command === 'stop') return tell(chat, stop(ws).stopped ? 'stopping it' : 'nothing is running')
+    if (command === 'status') return tell(chat, status(ws))
+    if (command === 'wrap') return change(chat, ws, () => wrapTurn(ws, args.trim() || undefined))
+    if (command === 'extend') {
+      const [dimension, amount] = args.trim().split(/\s+/)
+      if (!dimension) return tell(chat, '/extend wall 30m, /extend cost 1.50 or /extend rounds 20')
+      return change(chat, ws, () => extendTurn(ws, dimension, amount))
+    }
+    return tell(chat, HELP)
+  }
+
+  const follows = (ws) => {
+    if (state.cursors[ws]) return false
+    state.cursors[ws] = { seq: lastEventSeq(ws), turn: stateOf(ws).lastTurnNo, database: databaseOf(ws) }
+    return true
+  }
+
+  const pass = (chat, ws, text, update) => {
+    if (follows(ws)) save()
+    let sent
+    try {
+      sent = send(ws, text, { requestId: `telegram:${update}`, replyTo: `${replyTo}${chat}`, env: sendEnv() })
+    } catch (err) {
+      log(`chat ${chat}: send refused — ${err.type} ${said(err)}`)
+      return tell(chat, err.type === 'ADMISSION_FULL' ? `busy — ${said(err)}` : `not delivered — ${said(err)}`)
+    }
+    if (sent.repeated) return log(`chat ${chat}: update ${update} was already delivered, as inbox ${sent.inbox}`)
+
+    const entry = { inbox: sent.inbox, chat, message: null }
+    ;(state.pending[ws] ??= []).push(entry)
+    save()
+    notes.set(entry, delivery.to(chat, attempt => attempt(() => telegram.say(chat, sent.started ? 'working…' : 'heard you — still working…')))
+      .then(note => note.message_id, err => {
+        log(`chat ${chat}: no working message — ${said(err)}`)
+        return null
+      })
+      .then(message => {
+        entry.message = message
+        save()
+        return message
+      }))
+  }
+
+  const handle = async (update) => {
+    const message = update.message
+    const chat = message?.chat?.id
+    if (chat === undefined) return
+
+    let read
+    try {
+      read = route()
+    } catch (err) {
+      return log(`refused chat ${chat}: the allow-list is unreadable — ${said(err)}`)
+    }
+    const name = read.table[String(chat)]
+    if (!name) {
+      const who = message.from?.username ? ` (@${message.from.username})` : ''
+      return log(`refused chat ${chat}${who} — to allow it, add "${chat}": "<a spore>" to the chats of ${botFile}`)
+    }
+    let ws
+    try {
+      ws = sporeOf(name, read.config)
+    } catch (err) {
+      log(`chat ${chat}: "${name}" — ${said(err)}`)
+      return tell(chat, `this chat points at "${name}", which is not a spore name — tell whoever runs me`)
+    }
+    if (!ws) {
+      log(`chat ${chat}: no spore "${name}"`)
+      return tell(chat, `there is no spore called "${name}" — tell whoever runs me`)
+    }
+
+    const text = message.text?.trim()
+    if (!text) return tell(chat, 'only text reaches a spore for now')
+    const command = text.match(COMMAND)
+    const asked = command?.[1].toLowerCase()
+    if (command && (!command[3] || TAKES_ARGUMENTS.has(asked))) return obey(chat, ws, asked, command[3])
+    pass(chat, ws, text, update.update_id)
+  }
+
+  const listen = async () => {
+    const { signal } = stopping
+    let offset
+    let backoff = 1000
+    while (!signal.aborted) {
+      let updates
+      try {
+        updates = await telegram.updates(offset, { signal })
+        backoff = 1000
+      } catch (err) {
+        if (signal.aborted) break
+        if (err.context?.status === 409) {
+          throw new SporeError('another process is taking this bot\'s updates', { type: 'TELEGRAM_CONFLICT', detail: err.detail })
+        }
+        if (!err.retryable) throw err
+        log(`poll failed — ${said(err)}`)
+        await sleep(err.context?.retryAfter ? err.context.retryAfter * 1000 : backoff, signal)
+        backoff = Math.min(backoff * 2, 60_000)
+        continue
+      }
+      for (const update of updates) {
+        try {
+          await handle(update)
+        } catch (err) {
+          log(`update ${update.update_id}: ${said(err)}`)
+          const chat = update.message?.chat?.id
+          if (chat !== undefined) tell(chat, `that failed — ${err.message}`)
+        }
+        offset = update.update_id + 1
+      }
+    }
+    if (offset !== undefined) {
+      await telegram.updates(offset, { seconds: 0 }).catch(err => log(`could not confirm the last updates — ${said(err)}`))
+    }
+  }
+
+  const spores = () => {
+    let read
+    try {
+      read = route()
+      routeFailure = null
+    } catch (err) {
+      if (routeFailure !== err.message) log(`allow-list: ${said(err)} — following the spores it last named`)
+      routeFailure = err.message
+      return [...chatsOf.keys()]
+    }
+    detailed = read.detailed
+    const next = new Map()
+    for (const [chat, name] of Object.entries(read.table)) {
+      let ws
+      try {
+        ws = sporeOf(name, read.config)
+      } catch {
+        // Told to the chat, and logged, when it next speaks.
+        continue
+      }
+      if (ws) next.set(ws, [...(next.get(ws) ?? []), Number(chat)])
+    }
+    let moved = false
+    for (const ws of Object.keys(state.cursors)) {
+      if (next.has(ws)) continue
+      delete state.cursors[ws]
+      delete state.pending[ws]
+      moved = true
+    }
+    for (const ws of next.keys()) moved = follows(ws) || moved
+    if (moved) save()
+    chatsOf = next
+    return [...next.keys()]
+  }
+
+  const repaint = (ws) => {
+    const lines = shown.get(ws)
+    lines.timer = null
+    lines.at = Date.now()
+    for (const entry of state.pending[ws] ?? []) {
+      const text = ['working…', ...render(lines.items, { detailed: detailed.has(entry.chat) })].join('\n')
+      delivery.to(entry.chat, async (attempt) => {
+        const message = await noteOf(entry)
+        if (message === null || !state.pending[ws]?.includes(entry)) return
+        await attempt(() => telegram.revise(entry.chat, message, text))
+      }).catch(err => { if (!NOT_MODIFIED.test(err.detail ?? '')) log(`chat ${entry.chat}: progress not shown — ${said(err)}`) })
+    }
+  }
+
+  const onEvent = (ws, event) => {
+    if (!state.pending[ws]?.length) return
+    const lines = shown.get(ws) ?? { items: [], timer: null, at: 0 }
+    shown.set(ws, lines)
+    if (!track(lines.items, event)) return
+    if (!lines.timer) lines.timer = setTimeout(() => repaint(ws), Math.max(0, editEveryMs - (Date.now() - lines.at)))
+  }
+
+  const forget = (ws, notes) => {
+    const kept = (state.pending[ws] ?? []).filter(note => !notes.includes(note))
+    if (kept.length) state.pending[ws] = kept
+    else delete state.pending[ws]
+    save()
+  }
+
+  /**
+   * One outbox entry of this bot's posted to its chat — into the `working…` messages of what it
+   * answers when the chat has them — and settled: delivered once Telegram took it, refused when
+   * the chat does not reach this spore or Telegram will not take it. One Telegram still did not
+   * take when its retries ran out stays pending for the next pass. True when it is settled.
+   */
+  const deliver = async (ws, entry) => {
+    const chat = Number(entry.recipient.slice(replyTo.length))
+    const notes = (state.pending[ws] ?? []).filter(note => note.chat === chat && entry.answers.includes(note.inbox))
+    if (!(chatsOf.get(ws) ?? []).includes(chat)) {
+      const reason = `chat ${entry.recipient.slice(replyTo.length)} does not reach this spore through ${botFile}`
+      settleOutbox(ws, entry.outboxNo, { refused: reason })
+      log(`turn ${entry.turnNo} of ${ws}: refused — ${reason}`)
+      forget(ws, notes)
+      return true
+    }
+    const turn = turnsSince(ws, entry.turnNo - 1).ended[0]
+    const heard = turn.asked.filter(message => entry.answers.includes(message.inboxNo))
+    const text = heard.some(message => message.replyTo) ? reply(turn) : announce({ record: turn.record, asked: heard })
+    const files = (turn.record.produced ?? []).filter(file => file.delivered)
+    try {
+      await delivery.to(chat, async (attempt) => {
+        if (notes.length) {
+          for (const note of notes) await edit(attempt, chat, await noteOf(note), text)
+        } else {
+          for (const part of pieces(text)) await attempt(() => telegram.say(chat, part))
+        }
+        await hand(attempt, chat, ws, files)
+      })
+    } catch (err) {
+      if (err.retryable || stopping.signal.aborted) {
+        log(`turn ${entry.turnNo} of ${ws}: not delivered to chat ${chat} yet — ${said(err)}`)
+        return false
+      }
+      settleOutbox(ws, entry.outboxNo, { refused: said(err) })
+      log(`turn ${entry.turnNo} of ${ws}: chat ${chat} refused it — ${said(err)}`)
+      forget(ws, notes)
+      return true
+    }
+    settleOutbox(ws, entry.outboxNo)
+    forget(ws, notes)
+    return true
+  }
+
+  /**
+   * This bot's pending outbox entries of `ws`, delivered in order: the messages still owed an
+   * answer, or null when the spore's database could not be read or written — a busy one — and
+   * what it holds waits for the next pass.
+   */
+  const drain = async (ws) => {
+    const owed = new Set()
+    try {
+      for (const entry of outbox(ws, { kind: 'telegram', state: 'pending' })) {
+        if (!entry.recipient.startsWith(replyTo)) continue
+        if (!(await deliver(ws, entry))) entry.answers.forEach(inboxNo => owed.add(inboxNo))
+      }
+    } catch (err) {
+      log(`${ws}: its outbox could not be read or settled — ${said(err)}`)
+      return null
+    }
+    return owed
+  }
+
+  const onTurn = async (ws, turn) => {
+    clearTimeout(shown.get(ws)?.timer)
+    shown.delete(ws)
+
+    const read = new Set(turn.asked.map(entry => entry.inboxNo))
+    const left = (state.pending[ws] ?? []).filter(entry => !read.has(entry.inbox))
+    if (left.length && stateOf(ws).state !== RUNNING) {
+      const work = left.map(entry => delivery.to(entry.chat, async (attempt) => edit(attempt, entry.chat, await noteOf(entry), waiting(turn))))
+      for (const outcome of await Promise.allSettled(work)) {
+        if (outcome.status === 'rejected') log(`turn ${turn.record.turnNo} of ${ws}: not told it is waiting — ${said(outcome.reason)}`)
+      }
+    }
+
+    const owed = await drain(ws)
+    if (owed) forget(ws, (state.pending[ws] ?? []).filter(note => read.has(note.inbox) && !owed.has(note.inbox)))
+  }
+
+  const follow = async () => {
+    const { signal } = stopping
+    for (const ws of spores()) await drain(ws)
+    for await (const item of watchAll(spores, { cursors: state.cursors, tick: followEveryMs, signal })) {
+      if (item.event) {
+        onEvent(item.ws, item.event)
+        continue
+      }
+      await onTurn(item.ws, item.turn)
+      if (signal.aborted) break
+      state.cursors[item.ws] = item.cursor
+      save()
+    }
+  }
+
+  const run = async (signal) => {
+    signal.addEventListener('abort', () => stopping.abort(), { once: true })
+    const failed = []
+    const halt = (err) => {
+      failed.push(err)
+      stopping.abort()
+    }
+    await Promise.all([listen().catch(halt), follow().catch(halt)])
+    for (const lines of shown.values()) clearTimeout(lines.timer)
+    save()
+    if (failed.length) throw failed[0]
+  }
+
+  return { run }
+}

package/src/state.js

@@ -0,0 +1,33 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { SporeError } from '@rhizogrip/spore'
+
+export const statePath = (bot, env = process.env) =>
+  join(env.XDG_STATE_HOME || join(homedir(), '.local', 'state'), 'spore', 'telegram', bot, 'state.json')
+
+/**
+ * `cursors` is `watchAll`'s, per workspace. `pending` is, per workspace, every message a chat
+ * sent that no turn has answered yet: its `inbox` number, the chat, and the `working…`
+ * message the answer is edited into.
+ */
+export function loadState (path) {
+  if (!existsSync(path)) return { cursors: {}, pending: {} }
+  try {
+    const { cursors, pending } = JSON.parse(readFileSync(path, 'utf8'))
+    return { cursors, pending }
+  } catch (err) {
+    throw new SporeError(`${path} is not readable`, {
+      type: 'TELEGRAM_STATE_INVALID',
+      detail: `${err.message} — it holds where the bot stood; move it aside to start from now`
+    })
+  }
+}
+
+export function saveState (path, { cursors, pending }) {
+  mkdirSync(dirname(path), { recursive: true })
+  const written = `${path}.${process.pid}`
+  writeFileSync(written, JSON.stringify({ cursors, pending }, null, 2))
+  renameSync(written, path)
+}