hive-am 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -6,6 +6,55 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-10-20
+
+### Added
+
+- **Fold the main menu to icons.** A button next to the hive-am name folds the sidebar from 220 px to a 64 px column of icons, giving the chat and every other screen more room. Each icon keeps its name as a tooltip and for screen readers, counts stay as small badges and the EN/ES switch stays at hand. The choice is remembered and applied before the page paints, so a reload never flashes the wide menu. On narrow screens (under 760 px) the menu stays the top bar with its labels.
+- **Fold the colony groups of the chat's agent list.** Each colony heading in the side list of the chat is now a button that folds or unfolds its group (mouse or keyboard), and the folded groups are remembered. A folded group still shows the agent you are on and a pulsing dot when one of its agents is working; while searching every group with a match is open. The collapsed list (avatars only) keeps the groups apart with a compact heading per colony (its initials in its color and the count, the full name on hover) that folds the same groups. Orchestrators come first in each group in both modes, the headings are larger and easier to read, and a hive with no agents says "No agents yet" instead of an empty search message.
+- **Slack connections.** A connection can now link an agent to a Slack app, with everything Telegram does: DMs and channels, the allow list (Slack member and channel ids), files in and out, reactions (by Slack name) and the shared single conversation. It runs over **Socket Mode**, so no public URL is needed and hive-am can stay on a laptop; the socket is refreshed and reconnected on its own, and a wrong token says which one. The agent answers **in a thread opened on the message** and keeps answering there; scheduled messages, reminders and the `wake_when_done` notice go to the channel. Replies are sent as `mrkdwn`. The connection form has a working platform selector, the two tokens and Slack's own words; the manual explains how to create the app. Tested against a fake Slack (`sim-slack.ts`).
+- **`/help` and `/id` commands, and `/clear` and `/reset` as other names for `/new`**, on Telegram and Slack alike. `/id` answers the sender's id and the chat's, so an admin can add them. On Slack they come as slash commands (`/hive status`, `/hive-status` or `/status`).
+- **Limit who can talk inside an authorized group or channel.** Each allowed Telegram group or Slack channel now has a mode in the connection form: **Everyone in it** (the default, and what every saved chat keeps, with no migration) or **Only these people**, with its own list of person ids (Telegram user ids, Slack member ids `U…` or `W…`). In a restricted chat only those people can talk, in every topic and thread of it; a member is an admin (`/new`) only if they are also on the connection's people list with **Admin**. Anyone else is ignored, and if they call the agent they are told that the chat only admits its list, with their id and the chat's. With "Listens and chimes in" their messages do not reach the agent even as context. DMs are unchanged. The server refuses an unknown mode, more than 50 members per chat and ids that do not look like the platform's. Tested in `test-chat-access.ts` (no model).
+- **Delegate in the background.** `dispatch` now returns at once with a task id by default (`background` is true unless you pass `background: false` to wait for the answer), the orchestrator can keep answering the person or delegate to other subagents, and when the subagent finishes the orchestrator receives a message with the task id, the subagent and the result, in the place where it was asked (its web conversation, or the same Telegram or Slack thread). The new `dispatch_status` tool reads the state of a task (queued, running, done, failed or interrupted) and its result, and can wait up to 60 seconds for the end. The result lives in hive-am, not in the call: it is announced exactly once, even across a restart; a task left running by a restart is marked interrupted and its orchestrator is told to check the work and send it again; pruning keeps a result nobody has had yet. An orchestrator can have up to 10 unfinished background tasks. The orchestrator's instructions tell it to wait with `background: false` only for a very short task whose answer it needs right now. Tested in `test-dispatch-background.ts` (no model).
+
+### Changed
+
+- **The agent and agent-type forms are one component.** The types screen now renders the agent form (`AgentForm`) in type mode instead of its own copy of the fields, so a new agent field is written once. Nothing visible changes, and saving a type sends only the fields a type stores.
+- **The connection's people list is for direct messages, and each authorized group follows its own rule.** In the form it is now **People (direct messages)**, apart from **Groups** and **Allowed groups** (**Allowed channels** on Slack), each with its own help. The people list still talks in DMs and in groups that are not listed, but no longer opens a group limited to **Only these people**: only that group's members get in, and an empty member list admits nobody. If you already limited a group and someone on the people list talked there, add them to the group's list too. Rows wrap in a narrow drawer.
+- **Someone without access is told at every message aimed at the agent**, not only the first time, so the bot no longer looks dead. To keep a stranger from flooding a chat, it sends at most 5 notices per person and chat and 20 per chat in a minute, then stays silent. The notice of a limited chat now only points to the chat's members ("channel" on Slack).
+
+### Fixed
+
+- **Picking an agent in the chat's side list no longer sends the list back to the top.** The whole agent page was remounted for each agent, list included, so after scrolling down and choosing an agent the list jumped to the start and the chosen agent went out of view. The list now stays mounted (it keeps its scroll and its search text) while the chat still resets its draft, tab and viewed session, and opening or reloading an agent further down scrolls the list just enough to show it.
+- **A long answer from a delegated task, a wake-up or a schedule is no longer refused in a chat.** These notices went through the 8000 character limit of incoming messages, so a subagent's answer longer than that came back as "Message too long." and never reached the orchestrator in its Telegram or Slack thread (it stayed readable with `dispatch_status`). The limit now applies only to what people write.
+- **A delegation longer than five minutes no longer fails with `fetch failed` and loses the answer.** The synchronous `dispatch` held one HTTP request until the subagent finished, and Node's `fetch` gives up after 300 seconds without an answer. It now starts the task and waits with short `dispatch_status` calls (25 seconds each), so it returns the subagent's answer however long it takes. The orchestrator's own CLI is still cut after 10 minutes of silence while it waits on a tool, which is why `dispatch` goes in the background by default. The Recent delegations list shows a task waiting behind a busy subagent as queued (it used to look failed), and its status on hover.
+
+## [1.5.0] - 2026-10-19
+
+### Added
+
+- **Reasoning effort per agent**, in the agent form (and in agent types), right under the model, and used by **every** turn: web chat, channels, schedules, wake-ups and delegations (before, only a Telegram or Slack connection could set it). The field offers only what the provider and model take: `low`, `medium`, `high`, `xhigh` and `max` for Claude Code and Kiro (the last two could not be chosen anywhere before), and for OpenCode the variants the selected model really has, read from its catalog. Changing the provider or the model clears a level that no longer applies, and an agent left at **Default** keeps behaving as before. A connection's effort is now an override of the agent's, takes the same five levels, and an OpenCode level name becomes the variant the model has for it, so the old warning about models without that variant is gone.
+- **Clone an agent**, from its card on the Colony map or the footer of its settings. A clone is a separate agent with the same configuration (prompt, skills, permissions, model, folder and, for an orchestrator, its team) that **runs in parallel** with the original, so two conversations can happen at the same time, and that **shares its notebook**: one notebook, several readers, each note saying which agent wrote it. It does not bring the connections, schedules, wake-ups or resource management of the original. A clone always shows which agent it was cloned from, with a tag on its hexagon in the Colony map, in the Agents list, in the chat header and the list beside it and in the Relations screen, and the original shows how many clones it has. A notebook is now an object of its own: deleting an agent keeps it for the others that share it (and it goes with the last one), **Clear all** says it empties it for everybody, and **Separate** gives an agent its own copy. Existing notebooks are moved without losing a row.
+- **Database management** skill: an agent can use a database resource through twenty `object_db_*` tools: look at the structure (`schema`, `columns`, `describe`, `search`, `ddl`, `sample`, `explain`), run SQL (`query`, and `exec` for several statements in one transaction), keep saved queries and read the history, export a result to a file in its own folder, look at sessions and cancel one, and, with Full access, change how a resource connects, create one and delete one. What an agent may do follows its effective permission (read-only reads, Edit files also writes, `DROP` and `TRUNCATE` need Full access) and the read-only setting of the resource does not bind it. Passwords can be set but never read back: they never appear in an answer, the history, the log or a chat reply. Choosing an agent as the manager of a database gives it the skill. Tried against MariaDB, PostgreSQL, SQL Server and SQLite.
+- The launcher can run hive-am in the background and manage it: `hive-am start --background` (detached, with its output in `run/hive-am.log` in the data folder), `hive-am status`, `hive-am logs [-f] [-n N]`, `hive-am stop` and `hive-am restart`. A second start refuses and names the run that is already there, and a record whose process is gone or was reused by another one is reported as stale and never signalled. Plain `hive-am` behaves as before.
+- Every run of the launcher opens with a welcome that shows the version, the addresses and where the data and the log are. `hive-am version` prints the version, and `hive-am status` shows the version of the run.
+- `hive-am update` looks for a newer version on npm and installs it (`--check` only reports, `--restart` also restarts a run in the background), so updating no longer needs `npm install -g` by hand. It only installs when hive-am was installed globally with npm.
+
+### Changed
+
+- What hive-am keeps of its own record no longer grows for ever. Every six hours (and at start) it forgets: the messages of a channel conversation past the newest 500 once they are 30 days old, the delegations past the newest 200, the delegated conversations of an agent past the newest 50 once they have not been used for 90 days, and the conversations in the list that the CLI no longer has once they have not been used for 90 days (never an agent's current one). The record of a received file is emptied together with the file, so an agent is no longer handed a path that was deleted. The conversations themselves, in each CLI, are never touched.
+- Settings → Sessions of an agent, and the header of the Sessions screen, show the full session id, with a button to copy it.
+
+### Fixed
+
+- The server took the full 5 seconds to shut down and left its database unclosed, because it waited for its HTTP server to finish before dropping the WebSocket connections that were holding it open. It now drops them first and shuts down in a fraction of a second, with the write-ahead log merged.
+- Changes explorer: coming back to the tab now opens the file you were reading, with the folders that lead to it open, and the tab (History, Tags, Compare or Stashes) with what it had selected. Before, a folder with changes always replaced the remembered file with the first changed one, and in a clean folder of more than 40 files the file came back with every folder closed.
+- Chat: the **Jump to latest** button is no longer offered when there is nothing to scroll, and it appears for any scroll up with content out of view (a 25 px scroll up used to leave the last line cut with no button, and a streaming reply pulled the view back down). A taller draft or a resized window keeps the last message in view when you had not scrolled away.
+- OpenCode: changing an agent's permission did not apply to its existing conversation, so an agent switched to Full access kept saying it had no shell. The chat now warns that the permission changed after the conversation started and offers **Apply now**, which starts a new conversation (the current one stays in Sessions). Conversations recorded before this change are not detected.
+- A turn whose tool stops answering no longer holds the agent's queue forever: after 10 minutes of silence it is stopped, reported as failed, and the messages behind it run. A failure while a turn starts is now reported as that turn's error instead of losing the message.
+- A message that begins with a dash (`- something`, a bullet list, `--word`) is no longer read as an option by OpenCode and Kiro, which ended the turn with no answer or an error. The prompt now goes after `--`.
+- A turn that produces no events is reported as a failure, with the first line the tool printed, instead of passing as an empty answer.
+
 ## [1.4.0] - 2026-10-15
 
 ### Added
@@ -186,7 +235,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 - Complete documentation in English and Spanish.
 - npm package with the `hive-am` command.
 
-[Unreleased]: https://github.com/hughcbscrt/hive-am/compare/v1.4.0...HEAD
+[Unreleased]: https://github.com/hughcbscrt/hive-am/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/hughcbscrt/hive-am/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/hughcbscrt/hive-am/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/hughcbscrt/hive-am/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/hughcbscrt/hive-am/compare/v1.2.2...v1.3.0
 [1.2.2]: https://github.com/hughcbscrt/hive-am/compare/v1.2.1...v1.2.2

package/README.md

@@ -12,10 +12,6 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/hive-am"><img alt="npm version" src="https://img.shields.io/npm/v/hive-am?style=flat-square&color=cb3837&logo=npm&logoColor=white" /></a>
   <a href="https://www.npmjs.com/package/hive-am"><img alt="npm downloads" src="https://img.shields.io/npm/dm/hive-am?style=flat-square&color=cb3837" /></a>
-  <a href="https://github.com/hughcbscrt/hive-am/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/hughcbscrt/hive-am?style=flat-square&color=bf963d" /></a>
-  <a href="https://github.com/hughcbscrt/hive-am/pulls?q=is%3Apr"><img alt="Pull requests" src="https://img.shields.io/github/issues-pr-closed/hughcbscrt/hive-am?style=flat-square&color=bf963d" /></a>
-  <a href="https://github.com/hughcbscrt/hive-am/issues"><img alt="Issues" src="https://img.shields.io/github/issues/hughcbscrt/hive-am?style=flat-square&color=bf963d" /></a>
-  <a href="https://github.com/hughcbscrt/hive-am"><img alt="Repo size" src="https://img.shields.io/github/repo-size/hughcbscrt/hive-am?style=flat-square&color=bf963d" /></a>
   <a href="https://github.com/hughcbscrt/hive-am"><img alt="Top language" src="https://img.shields.io/github/languages/top/hughcbscrt/hive-am?style=flat-square&color=3178c6" /></a>
   <img alt="Node 20+" src="https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=nodedotjs&logoColor=white" />
   <img alt="Next.js 15" src="https://img.shields.io/badge/Next.js-15-000000?style=flat-square&logo=nextdotjs&logoColor=white" />
@@ -37,10 +33,11 @@ have installed; it does not replace them and it never copies your conversations
 - **Skills.** Ten skills ship with hive-am (all ordinary: edit or delete them). Assign them to an agent, a type or a colony, and choose per assignment whether they are **always** in the instructions or loaded **on demand** with a `skill_read` tool. Searchable picker with token weights.
 - **Notebook.** An agent can keep a persistent notebook of what it learns (no credentials, no duplicates, every note with its source). You can read and edit it from the agent's settings.
 - **Telegram.** Link a bot to an agent: private chats, groups and topics, one shared session across all of them. In groups the agent can listen to everything and speak only when it adds something; people can mute it per thread and bring it back.
+- **Slack.** The same over Socket Mode (no public URL): DMs and channels, the agent answers in a thread opened on the message, scheduled messages land in the channel, `/hive` slash commands.
 - **Files and images.** People send documents and photos to the agent; the agent sends files back. An optional image model can describe pictures for models that cannot see them.
 - **Permissions that hold.** *Read-only*, *Edit files* and *Full access* are enforced by the CLI itself in all three providers.
 - **Changes explorer.** A Git tab per agent: file tree with highlighting, diff viewer, history, commit, pull, push and branches.
-- **Resources.** Servers, Docker containers, HTTP requests (`.http` files) and clusters that group them live in a colony as hexagons: start, stop, read logs, run requests; agents can look after them.
+- **Resources.** Servers, Docker containers, HTTP requests (`.http` files) and clusters that group them live in a colony as hexagons: start, stop, read logs, run requests; agents can look after them, and an agent with the Database management skill can look inside a database and run SQL, within its permission.
 - **Terminals.** A bottom panel (Ctrl+`) with real shells and object logs, reachable only from this machine.
 - **Local and private.** The server binds to `127.0.0.1`. Data lives in `~/.hive-am/`.
 
@@ -119,14 +116,14 @@ Data lives in `~/.hive-am/hive-am.db` (override with `HIVE_AM_HOME`). The server
 In *Edit files* the agent cannot touch `.git` or private keys (`*.pem`, `*.key`) and cannot write outside its folder. Details and the
 few differences between providers are in [docs/06](docs/reference/en/06-providers.md) and [docs/12](docs/reference/en/12-operations-and-troubleshooting.md).
 
-## Connections (Telegram)
+## Connections (Telegram and Slack)
 
-1. Create a bot with @BotFather and copy its token.
-2. In **Connections**, add a Telegram connection, pick the agent that answers, and list the people (and groups) allowed to talk to it.
+1. Create a bot with @BotFather and copy its token, or create a Slack app with Socket Mode and copy its bot token (`xoxb-`) and app token (`xapp-`) ([manual, chapter 9](docs/manual/en/09-telegram-connections.md#slack)).
+2. In **Connections**, add a Telegram or Slack connection, pick the agent that answers, and list the people (and groups or channels) allowed to talk to it.
 3. Optional: set the group mode (`mention` or `open`), an alias, whether files are accepted, and an image model.
 
 The agent answers through a `channel_reply` tool: its plain text is never delivered. Only authorized people and groups reach it,
-checked on the server. The bot token is stored in `~/.hive-am/hive-am.db` and never returned by the API; see the note about it in
+checked on the server. Tokens are stored in `~/.hive-am/hive-am.db` and never returned by the API; see the note about it in
 [docs/14](docs/reference/en/14-external-connections.md).
 
 ## How it is built

package/bin/hive-am.mjs

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
-// hive-am launcher: starts the API server and the web UI from the published package.
-import { spawn } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+// hive-am launcher: starts the API server and the web UI from the published package, in this terminal or in the background,
+// and stops it, reports on it and shows its log afterwards.
+import { spawn, spawnSync } from 'node:child_process';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
-import { dirname, join } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import * as run from './run.mjs';
 
-const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const self = fileURLToPath(import.meta.url);
+const root = join(dirname(self), '..');
 const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
 const args = process.argv.slice(2);
 
@@ -14,42 +18,249 @@ const HELP = `hive-am ${pkg.version}
 ${pkg.description}
 
 Usage:
-  hive-am [start]        start the server (API + WebSocket, port 4400) and the web UI (port 4401)
-  hive-am --version      print the version
-  hive-am --help         show this help
+  hive-am [start]              start the server (API + WebSocket, port 4400) and the web UI (port 4401) in this terminal
+  hive-am start --background   start it detached, with its output in a log file, and return
+  hive-am status               say whether it is running, since when and whether its ports answer (exit 1 when it is not)
+  hive-am logs [-f] [-n 200]   show the last lines of the log, or follow it
+  hive-am stop                 stop it and wait until it is gone
+  hive-am restart              stop it and start it again in the same mode (in the background when nothing was recorded)
+  hive-am update [--check]     look for a newer version on npm and install it (--check only says; --restart also restarts a run)
+  hive-am version              print the version (so does --version)
+  hive-am --help               show this help
 
 Environment:
-  HIVE_AM_HOME           data folder (default ~/.hive-am)
+  HIVE_AM_HOME           data folder (default ~/.hive-am); the record and the log of a run are in its run/ folder
   HIVE_AM_WEB_PORT       port of the web UI (default 4401)
 
 The API server always uses port 4400: the packaged UI is built to talk to it.
 Requires Node >= ${pkg.engines?.node?.replace('>=', '') ?? '20'} and at least one of the CLIs installed and logged in: claude, opencode, kiro-cli.`;
 
+const COMMANDS = ['start', 'stop', 'status', 'logs', 'restart', 'update', 'version'];
+const fail = (msg, code = 1) => { console.error(msg); process.exit(code); };
+
 if (args.includes('--help') || args.includes('-h')) { console.log(HELP); process.exit(0); }
-if (args.includes('--version') || args.includes('-v')) { console.log(pkg.version); process.exit(0); }
-if (args.length && args[0] !== 'start') { console.error(`Unknown command: ${args[0]}\n\n${HELP}`); process.exit(1); }
+if (args.includes('--version') || args.includes('-v') || args[0] === 'version') { console.log(pkg.version); process.exit(0); }
+
+const cmd = !args.length || args[0].startsWith('-') ? 'start' : args[0];
+const flags = COMMANDS.includes(args[0]) ? args.slice(1) : args;
+if (!COMMANDS.includes(cmd) || (args.length && args[0].startsWith('-') && !['--background', '-b', '--foreground'].includes(args[0]))) fail(`Unknown command: ${args[0]}\n\n${HELP}`);
+
+/** `hive-am logs`: `-f` follows, `-n N` (or `-nN`, `--lines N`) is how many lines. */
+function logOptions(list) {
+  let follow = false, lines = 200;
+  for (let i = 0; i < list.length; i++) {
+    const a = list[i];
+    if (a === '-f' || a === '--follow') follow = true;
+    else if (a === '-n' || a === '--lines') lines = Number(list[++i]);
+    else if (/^-n\d+$/.test(a)) lines = Number(a.slice(2));
+    else fail(`Unknown option for logs: ${a}\n\n${HELP}`);
+  }
+  if (!Number.isInteger(lines) || lines < 1) fail('logs: -n needs a number of lines.');
+  return { follow, lines };
+}
+const startOptions = (list) => {
+  for (const a of list) if (!['--background', '-b', '--foreground', '--run-background'].includes(a)) fail(`Unknown option for start: ${a}\n\n${HELP}`);
+  return { background: list.includes('--background') || list.includes('-b'), detached: list.includes('--run-background') };
+};
+if (cmd !== 'start' && cmd !== 'logs' && cmd !== 'update' && flags.length) fail(`Unknown option for ${cmd}: ${flags[0]}\n\n${HELP}`);
 
 if (process.env.HIVE_AM_PORT && process.env.HIVE_AM_PORT !== '4400') {
-  console.error('HIVE_AM_PORT is not supported by the packaged build: the UI is built to talk to the API on port 4400.');
-  process.exit(1);
+  fail('HIVE_AM_PORT is not supported by the packaged build: the UI is built to talk to the API on port 4400.');
 }
 
 const webPort = process.env.HIVE_AM_WEB_PORT ?? '4401';
-const next = join(dirname(createRequire(import.meta.url).resolve('next/package.json')), 'dist', 'bin', 'next');
-
-const children = [
-  spawn(process.execPath, [join(root, 'server', 'dist', 'index.js')], { cwd: join(root, 'server'), stdio: 'inherit' }),
-  spawn(process.execPath, [next, 'start', '-p', webPort, '-H', '127.0.0.1'], { cwd: join(root, 'web'), stdio: 'inherit' }),
-];
-
-let closing = false;
-const stop = (code = 0) => {
-  if (closing) return;
-  closing = true;
-  for (const c of children) c.kill('SIGTERM');
-  setTimeout(() => process.exit(code), 500).unref();
-};
-for (const c of children) c.on('exit', (code) => { if (!closing) { console.error('hive-am: a process exited, stopping.'); stop(code ?? 1); } });
-process.on('SIGINT', () => stop(0));
-process.on('SIGTERM', () => stop(0));
-setTimeout(() => console.log(`\nhive-am is running → http://127.0.0.1:${webPort}  (API on 127.0.0.1:4400)`), 2500).unref();
+const apiPort = Number(process.env.HIVE_AM_LAUNCHER_API_PORT) || 4400;     // only tests change it: the packaged UI always talks to 4400
+
+/** The two processes of the app. `HIVE_AM_LAUNCHER_CHILDREN` (tests only) replaces them with `[[command, ...args], [command, ...args]]`. */
+function specs() {
+  if (process.env.HIVE_AM_LAUNCHER_CHILDREN) return JSON.parse(process.env.HIVE_AM_LAUNCHER_CHILDREN).map(([c, ...a]) => ({ cmd: c, args: a, cwd: root }));
+  const next = join(dirname(createRequire(import.meta.url).resolve('next/package.json')), 'dist', 'bin', 'next');
+  return [
+    { cmd: process.execPath, args: [join(root, 'server', 'dist', 'index.js')], cwd: join(root, 'server') },
+    { cmd: process.execPath, args: [next, 'start', '-p', webPort, '-H', '127.0.0.1'], cwd: join(root, 'web') },
+  ];
+}
+
+/** Refuses to start over a run that is already there: names it, or the port something else holds. Returns the message, or null when the way is free. */
+async function blocked() {
+  const cur = run.inspect();
+  if (cur.kind === 'running') return `hive-am is already running (pid ${cur.state.pid}, since ${run.clock(cur.state.startedAt)}). See: hive-am status`;
+  for (const [what, port] of [['web UI', webPort], ['API', apiPort]]) {
+    if (await run.portOpen(port)) return `Port ${port} (${what}) is already in use by something that is not a recorded hive-am run. Is hive-am running from another data folder or without the launcher?`;
+  }
+  return null;
+}
+
+/** What a run prints first: the version, where to open it and where it keeps things. In the background it is the first thing in the log. */
+function welcome(mode) {
+  const data = run.dataDir().replace(homedir(), '~');
+  console.log(`
+  hive-am ${pkg.version}
+  ${pkg.description.split(':')[0]}
+
+  web   http://127.0.0.1:${webPort}
+  api   127.0.0.1:${apiPort}
+  data  ${data}
+${mode === 'background' ? '  log   ' + run.logFile().replace(homedir(), '~') + '\n  Stop it with: hive-am stop' : '  Stop it with Ctrl+C'}   (more: hive-am --help)
+`);
+}
+
+/** Runs the app in this process until it stops. In the background the output of both children goes to the same log. */
+function serve(mode) {
+  const children = specs().map((s) => spawn(s.cmd, s.args, { cwd: s.cwd, stdio: 'inherit' }));
+  welcome(mode);
+  run.writeState({ pid: process.pid, stamp: run.processStamp(process.pid), mode, version: pkg.version, startedAt: Date.now(), webPort, apiPort, log: mode === 'background' ? run.logFile() : null });
+  process.on('exit', () => run.removeState(process.pid));
+
+  let closing = false, code = 0, left = children.length;
+  const finish = () => process.exit(code);
+  // Stopping waits for the children to be gone (the server closes its database on the way out); a child that does not go is cut off.
+  const stop = (c = 0) => {
+    if (closing) return;
+    closing = true; code = c;
+    for (const ch of children) ch.kill('SIGTERM');
+    setTimeout(() => { for (const ch of children) ch.kill('SIGKILL'); finish(); }, 8000).unref();
+    if (!left) finish();
+  };
+  for (const c of children) c.on('exit', (exitCode) => {
+    left--;
+    if (!closing) { console.error('hive-am: a process exited, stopping.'); stop(exitCode ?? 1); }
+    if (closing && !left) finish();
+  });
+  process.on('SIGINT', () => stop(0));
+  process.on('SIGTERM', () => stop(0));
+  process.on('SIGHUP', () => { if (mode !== 'background') stop(0); });     // a closed terminal ends a foreground run; a background one has none
+  if (mode === 'background') setInterval(() => run.rotateLog(), 60_000).unref();
+  setTimeout(() => console.log(`\nhive-am is running → http://127.0.0.1:${webPort}  (API on 127.0.0.1:${apiPort})`), 2500).unref();
+}
+
+async function start(list) {
+  const { background, detached } = startOptions(list);
+  const why = await blocked();
+  if (why) fail(why);
+
+  if (!background) { serve(detached ? 'background' : 'foreground'); return; }
+
+  run.rotateLog();
+  mkdirSync(run.runDir(), { recursive: true });
+  const fd = openSync(run.logFile(), 'a');
+  // The launcher itself, again, detached and in its own process group: what `stop` signals is the process that owns the two children.
+  const child = spawn(process.execPath, [self, 'start', '--run-background'], { detached: true, stdio: ['ignore', fd, fd], env: process.env, cwd: process.cwd() });
+  closeSync(fd);
+  let gone = false;
+  child.on('exit', () => { gone = true; });
+  child.unref();
+  for (let i = 0; i < 100 && !gone; i++) {
+    if (run.readState()?.pid === child.pid) {
+      console.log(`hive-am started in the background (pid ${child.pid})\n  web   http://127.0.0.1:${webPort}\n  api   127.0.0.1:${apiPort}\n  log   ${run.logFile()}\n  stop  hive-am stop    (see also: hive-am status, hive-am logs -f)`);
+      process.exit(0);
+    }
+    await run.sleep(100);
+  }
+  const { text } = run.readLog({ tail: 15 });
+  fail(`hive-am did not start in the background.${text ? `\n\nLast lines of ${run.logFile()}:\n${text}` : ''}`);
+}
+
+async function stop() {
+  const cur = run.inspect();
+  if (cur.kind === 'none') fail('hive-am is not running.');
+  if (cur.kind === 'stale') { run.removeState(cur.state.pid); fail(`hive-am is not running: its record was stale (${cur.why}). The record was removed and nothing was signalled.`); }
+  const { state } = cur;
+  const { forced } = await run.stopRun(state);
+  if (run.isAlive(state.pid, state.stamp)) fail(`hive-am (pid ${state.pid}) did not stop, even when forced.`);
+  run.removeState(state.pid);
+  console.log(`hive-am stopped (pid ${state.pid})${forced ? ', after forcing it' : ''}.`);
+  process.exit(0);
+}
+
+async function status() {
+  const cur = run.inspect();
+  if (cur.kind === 'none') { console.log('not running'); process.exit(1); }
+  if (cur.kind === 'stale') { console.log(`not running (stale record: ${cur.why})`); process.exit(1); }
+  const s = cur.state;
+  const [web, api] = await Promise.all([run.portOpen(s.webPort), run.portOpen(s.apiPort)]);
+  const ports = `web http://127.0.0.1:${s.webPort} ${web ? 'up' : 'not answering'}, api 127.0.0.1:${s.apiPort} ${api ? 'up' : 'not answering'}`;
+  console.log(`running (pid ${s.pid}, ${s.version ? `v${s.version}, ` : ''}since ${run.clock(s.startedAt)}, ${s.mode}) ${ports}${web || api ? '' : '\nNothing answers on its ports: it may still be starting, or it is stuck.'}${s.log ? `\nlog ${s.log}` : ''}`);
+  process.exit(0);
+}
+
+async function logs(list) {
+  const { follow, lines } = logOptions(list);
+  const cur = run.inspect();
+  if (cur.kind === 'running' && cur.state.mode === 'foreground') {
+    console.log(`hive-am (pid ${cur.state.pid}) was started in a terminal: its output is shown there, there is no log file for this run.\nTo keep a log, start it with: hive-am start --background`);
+    process.exit(0);
+  }
+  const file = run.logFile();
+  if (!existsSync(file)) { console.log('There is no log yet. Start hive-am with: hive-am start --background'); process.exit(0); }
+  let { text, cursor } = run.readLog({ tail: lines });
+  if (text) console.log(text.replace(/\n$/, ''));
+  if (!follow) process.exit(0);
+  process.on('SIGINT', () => process.exit(0));
+  for (;;) {
+    await run.sleep(500);
+    const next = run.readLog({ after: cursor });
+    if (next.text) process.stdout.write(next.text);
+    cursor = next.cursor;
+  }
+}
+
+async function restart() {
+  const cur = run.inspect();
+  const mode = cur.state?.mode ?? 'background';
+  if (cur.kind === 'running') {
+    const { forced } = await run.stopRun(cur.state);
+    if (run.isAlive(cur.state.pid, cur.state.stamp)) fail(`hive-am (pid ${cur.state.pid}) did not stop, even when forced.`);
+    run.removeState(cur.state.pid);
+    console.log(`hive-am stopped (pid ${cur.state.pid})${forced ? ', after forcing it' : ''}.`);
+  } else console.log('hive-am was not running.');
+  await start(mode === 'background' ? ['--background'] : []);
+}
+
+/** Compares two `x.y.z` versions (a pre-release tag is ignored). */
+const versionCmp = (a, b) => { const n = (v) => String(v).split('-')[0].split('.').map((x) => Number(x) || 0); const [x, y] = [n(a), n(b)]; for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0); return 0; };
+const npm = (list, opts = {}) => spawnSync(process.env.HIVE_AM_NPM || 'npm', list, { encoding: 'utf8', timeout: 120_000, ...opts });
+
+/** How this copy of hive-am was installed, which decides whether it can update itself. `HIVE_AM_LAUNCHER_INSTALL` (tests only) forces the answer. */
+function installKind() {
+  if (process.env.HIVE_AM_LAUNCHER_INSTALL) return process.env.HIVE_AM_LAUNCHER_INSTALL;
+  if (root.includes(`${sep}_npx${sep}`)) return 'npx';
+  if (existsSync(join(root, '.git')) || existsSync(join(root, 'server', 'src'))) return 'source';
+  const g = npm(['root', '-g']).stdout?.trim();
+  return g && root.startsWith(g) ? 'global' : 'other';
+}
+
+async function update(list) {
+  for (const a of list) if (!['--check', '--restart'].includes(a)) fail(`Unknown option for update: ${a}\n\n${HELP}`);
+  const check = list.includes('--check'), again = list.includes('--restart');
+  const view = npm(['view', pkg.name, 'version']);
+  const latest = view.status === 0 ? view.stdout.trim() : '';
+  if (!latest) fail(`Could not ask npm for the latest version of ${pkg.name}${view.error ? ` (${view.error.message})` : ''}. Are you online?`);
+  console.log(`installed ${pkg.version}, latest ${latest}`);
+  if (versionCmp(latest, pkg.version) <= 0) { console.log('hive-am is up to date.'); process.exit(0); }
+  if (check) { console.log(`An update is available. Install it with: hive-am update`); process.exit(0); }
+
+  const kind = installKind();
+  if (kind === 'npx') fail('This copy runs through npx, which fetches what you ask for: start the new version with `npx hive-am@latest`.');
+  if (kind === 'source') fail('This is a source checkout: update it with `git pull` and `npm install`, then rebuild.');
+  if (kind !== 'global') fail(`hive-am was not installed globally with npm (${root}), so it cannot update itself. Install the new version the way you installed this one: npm install -g ${pkg.name}@${latest}`);
+
+  console.log(`Installing ${pkg.name}@${latest} ...`);
+  const r = npm(['install', '-g', `${pkg.name}@${latest}`], { stdio: 'inherit', encoding: undefined });
+  if (r.status !== 0) fail(`npm could not install ${pkg.name}@${latest} (exit ${r.status}). If it is a permissions error, see https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally`);
+  let now = latest;
+  try { now = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version; } catch { /* the folder was replaced: keep what npm installed */ }
+  console.log(`hive-am updated: ${pkg.version} -> ${now}`);
+  const cur = run.inspect();
+  if (cur.kind !== 'running') process.exit(0);
+  if (again) { console.log('Restarting it on the new version ...'); process.exit(spawnSync(process.execPath, [self, 'restart'], { stdio: 'inherit' }).status ?? 1); }
+  console.log(`hive-am (pid ${cur.state.pid}) is still running the old version. Apply the update with: hive-am restart`);
+  process.exit(0);
+}
+
+if (cmd === 'start') await start(flags);
+else if (cmd === 'update') await update(flags);
+else if (cmd === 'stop') await stop();
+else if (cmd === 'status') await status();
+else if (cmd === 'logs') await logs(flags);
+else await restart();

package/bin/run.mjs

@@ -0,0 +1,135 @@
+// What the launcher remembers about the app it started: a state file, a log, and the checks that keep it from touching the wrong process.
+// Plain JavaScript on purpose, with no import from the server: the launcher has to work when the app is down, when the database is broken
+// and when the data folder does not exist yet (importing the server's code would open the database and create the folder).
+import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, truncateSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { createConnection } from 'node:net';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const LOG_MAX = 10 * 1024 * 1024;     // a bigger log is set aside when the launcher starts, and while it runs in the background
+export const STOP_GRACE_MS = 15_000;         // how long `stop` waits for the app to go before it forces it (the server's own shutdown is bounded to 5 s)
+
+export const dataDir = () => process.env.HIVE_AM_HOME || join(homedir(), '.hive-am');
+export const runDir = () => join(dataDir(), 'run');
+export const stateFile = () => join(runDir(), 'hive-am.json');
+export const logFile = () => join(runDir(), 'hive-am.log');
+
+/** An identifier of "this very process" (its start time), so that a pid the system reuses for something else is not mistaken for the app. null = not running. */
+export function processStamp(pid) {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+    const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+    return rest[0] === 'Z' || rest[0] === 'X' ? null : rest[19] ?? null;     // a finished process nobody has collected yet (zombie) is finished
+  } catch (e) {
+    if (e.code !== 'ENOENT' || existsSync('/proc/self')) return null;        // Linux: no such process
+  }
+  try {                                                                      // macOS and others
+    const out = execFileSync('ps', ['-o', 'stat=,lstart=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (!out || out.startsWith('Z')) return null;
+    return out.replace(/^\S+\s+/, '');
+  } catch { return null; }
+}
+export const isAlive = (pid, stamp) => { const s = processStamp(pid); return s !== null && (stamp == null || s === stamp); };
+
+/** The record of a run, or null. `{ pid, stamp, mode: 'foreground' | 'background', startedAt, webPort, apiPort, log }`. */
+export function readState() {
+  try {
+    const s = JSON.parse(readFileSync(stateFile(), 'utf8'));
+    return s && Number.isInteger(s.pid) ? s : null;
+  } catch { return null; }
+}
+export function writeState(s) {
+  mkdirSync(runDir(), { recursive: true });
+  const tmp = `${stateFile()}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(s, null, 2));
+  renameSync(tmp, stateFile());
+}
+/** Removes the record, but only when it is the one of `pid` (a run that ends must not erase the record of the one that replaced it). */
+export function removeState(pid) {
+  const s = readState();
+  if (s && (pid === undefined || s.pid === pid)) rmSync(stateFile(), { force: true });
+}
+
+/**
+ * What the record says about the app: `none` (no record), `running` (the process in it is alive and is the same one) or `stale`
+ * (the pid is gone, or it now belongs to another process: the record is never followed).
+ */
+export function inspect() {
+  const state = readState();
+  if (!state) return { kind: 'none' };
+  const now = processStamp(state.pid);
+  if (now === null) return { kind: 'stale', state, why: `pid ${state.pid} is not running` };
+  if (state.stamp && now !== state.stamp) return { kind: 'stale', state, why: `pid ${state.pid} now belongs to a different process` };
+  return { kind: 'running', state };
+}
+
+/** Whether something accepts connections on a local port. */
+export function portOpen(port, host = '127.0.0.1', timeoutMs = 500) {
+  return new Promise((resolve) => {
+    const s = createConnection({ port: Number(port), host });
+    const done = (v) => { s.destroy(); resolve(v); };
+    s.setTimeout(timeoutMs, () => done(false));
+    s.once('connect', () => done(true));
+    s.once('error', () => done(false));
+  });
+}
+
+/**
+ * Keeps the log from growing for ever. The run writes with O_APPEND to its own file, so the old part is copied aside and the file is
+ * emptied in place (a few lines printed in between can be lost; it is a log, not a ledger).
+ */
+export function rotateLog(file = logFile(), max = LOG_MAX) {
+  try {
+    if (statSync(file).size <= max) return false;
+    copyFileSync(file, `${file}.1`); truncateSync(file, 0);
+    return true;
+  } catch { return false; }
+}
+
+/** The lines of the log. `after` is a byte offset from an earlier call; without it the last `tail` lines come back. */
+export function readLog({ tail = 200, after, file = logFile() } = {}) {
+  let size = 0;
+  try { size = statSync(file).size; } catch { return { text: '', cursor: 0 }; }
+  const MAX = 256 * 1024;
+  const lines = Math.max(1, Math.min(tail, 5000));
+  let from, reset = false;
+  if (after !== undefined && Number.isFinite(after)) {
+    if (after > size) { from = Math.max(0, size - MAX); reset = true; }      // the file was cut or replaced
+    else from = Math.max(after, size - MAX);
+  } else from = Math.max(0, size - lines * 200);
+  const len = size - from;
+  if (len <= 0) return { text: '', cursor: size };
+  const buf = Buffer.alloc(len);
+  const fd = openSync(file, 'r');
+  try { readSync(fd, buf, 0, len, from); } finally { closeSync(fd); }
+  let text = buf.toString('utf8');
+  if (after === undefined) {
+    const all = text.split('\n');
+    if (from > 0) all.shift();                                               // the first line may be cut in half
+    text = all.slice(-lines).join('\n');
+  }
+  return { text, cursor: size, reset: reset || undefined };
+}
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Waits until the process is gone. Returns false when it is still there after `ms`. */
+export async function waitGone(pid, stamp, ms) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) { if (!isAlive(pid, stamp)) return true; await sleep(100); }
+  return !isAlive(pid, stamp);
+}
+
+/** SIGTERM to the launcher (it forwards it to the two processes it owns), then SIGKILL to its whole group when it does not go. */
+export async function stopRun(state, graceMs = STOP_GRACE_MS) {
+  const { pid, stamp } = state;
+  try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ }
+  if (await waitGone(pid, stamp, graceMs)) return { forced: false };
+  // A background run is its own process group (the launcher is its leader): the group takes the children with it.
+  try { process.kill(state.mode === 'background' ? -pid : pid, 'SIGKILL'); } catch { /* gone in between */ }
+  await waitGone(pid, stamp, 3000);
+  return { forced: true };
+}
+
+export const clock = (ms) => new Date(ms).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hive-am",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "A colony of coding agents: orchestrators and subagents over Claude Code, OpenCode and Kiro, with real session resume, a browser UI and Telegram.",
   "keywords": [
     "ai-agents",

package/server/dist/connections/format.js

@@ -37,3 +37,29 @@ export function mdToTelegramHtml(md) {
     s = s.replace(/^#{1,6}\s+(.+)$/gm, '<b>$1</b>');
     return s.replace(/\u0000(\d+)\u0000/g, (_m, i) => stash[Number(i)]);
 }
+/** Slack's three control characters; everything else goes as it is. */
+export const escapeSlack = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/**
+ * Markdown → Slack's `mrkdwn`: `*bold*`, `_italic_`, `~strike~`, code as it is, `<url|label>` links, headings as bold lines.
+ * Slack's own tokens the agent may write (`<@U123>`, `<#C123>`, `<!here>`, `<https://…|…>`) are kept; any other `&`, `<`, `>` is escaped.
+ */
+export function mdToSlackMrkdwn(md) {
+    md = emojiPresentation(md);
+    const stash = [];
+    const keep = (s) => `\u0000${stash.push(s) - 1}\u0000`;
+    let s = md.replace(/```[^\n]*\n?([\s\S]*?)```/g, (_m, code) => keep(`\`\`\`\n${escapeSlack(code.replace(/\n$/, ''))}\n\`\`\``));
+    s = s.replace(/`([^`\n]+)`/g, (_m, code) => keep(`\`${escapeSlack(code)}\``));
+    s = s.replace(/<(?:[@#][A-Z0-9]+(?:\|[^>\n]*)?|![a-z]+(?:\^[A-Z0-9]+)?(?:\|[^>\n]*)?|(?:https?|mailto):[^\s|>]+(?:\|[^>\n]+)?)>/g, (t) => keep(t));
+    s = s.replace(/\[([^\]\n]+)\]\(((?:https?:\/\/|mailto:)[^\s)]+)\)/g, (_m, label, url) => keep(`<${url}|${escapeSlack(label).replace(/\|/g, '¦')}>`));
+    s = escapeSlack(s);
+    s = s.replace(/^#{1,6}\s+(.+)$/gm, (_m, h) => keep(`*${h.replace(/\*\*/g, '').trim()}*`));
+    s = s.replace(/(^|[\s(])\*([^*\n]+)\*(?=$|[\s).,!?:;])/gm, '$1_$2_');
+    s = s.replace(/\*\*([^*\n]+)\*\*/g, (_m, b) => keep(`*${b}*`)).replace(/__([^_\n]+)__/g, (_m, b) => keep(`*${b}*`));
+    s = s.replace(/~~([^~\n]+)~~/g, '~$1~');
+    s = s.replace(/^(\s*)[-*]\s+/gm, '$1• ');
+    s = s.replace(/^&gt;\s?/gm, '> ');
+    // Stashed pieces can hold other stashed pieces (a link inside a heading): resolve until none is left.
+    for (let i = 0; i < 3 && s.includes('\u0000'); i++)
+        s = s.replace(/\u0000(\d+)\u0000/g, (_m, n) => stash[Number(n)]);
+    return s;
+}

package/server/dist/connections/index.js

@@ -1,3 +1,5 @@
 import { registerFactory } from './manager.js';
+import { SlackAdapter } from './slack.js';
 import { TelegramAdapter } from './telegram.js';
 registerFactory('telegram', (c) => new TelegramAdapter(c));
+registerFactory('slack', (c) => new SlackAdapter(c));