hive-am 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -6,6 +6,50 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## [Unreleased]
 
+## [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
+
+- **Chat** item in the side rail, above Colony. It opens the last conversation you had open (or the first agent if that one no longer exists). With no agents yet, it shows an empty state with a button to create the first one.
+- **Resources strip** above each chat, folded by default. Closed, it is one line that counts the resources running, stopped or failing (failures in red). Open, it shows a card per resource with start or stop, restart and a link to its own screen. It shows the agent's resources and those of its colony, with a switch to see all of them; the choice and whether it is open are remembered.
+- The README now has screenshots of the colony, chat, resources, clusters, changes explorer and HTTP requests.
+
+### Changed
+
+- Servers: **Keeping it healthy** is split into **If it goes down** (restart policy and maximum restarts) and **Health check** (kind, target and restart when unhealthy). The check timing (every, wait, failures in a row) and the stop and log settings are folded, and the defaults are visible.
+- Servers: a restart waits for the port to be free before starting again, so a stop command that does not really stop the service is reported instead of leaving a failed start behind.
+- Servers: the first health check comes one interval after a start instead of right away.
+
+### Fixed
+
+- Entering a chat no longer flashes the default layout first: saved choices (the agent list collapsed, the resources strip open) apply before the first paint, the side panel only animates when you toggle it, and the conversation fades in when its history arrives.
+
 ## [1.3.0] - 2026-10-14
 
 ### Added
@@ -168,7 +212,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.3.0...HEAD
+[Unreleased]: https://github.com/hughcbscrt/hive-am/compare/v1.5.0...HEAD
+[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
 [1.2.1]: https://github.com/hughcbscrt/hive-am/compare/v1.2.0...v1.2.1

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" />
@@ -40,10 +36,29 @@ have installed; it does not replace them and it never copies your conversations
 - **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/`.
 
+## Screenshots
+
+<table>
+  <tr>
+    <td width="50%"><img src="docs/manual/en/img/colonia-mapa.jpg" alt="The colony map: colonies, agents and resources as hexagons" /><br /><sub><b>The colony.</b> Agents and resources as hexagons, grouped by colony.</sub></td>
+    <td width="50%"><img src="docs/manual/en/img/chat-conversacion.jpg" alt="A conversation with an orchestrator" /><br /><sub><b>Chat.</b> The real session of the CLI, with tokens, cost and tool calls.</sub></td>
+  </tr>
+  <tr>
+    <td width="50%"><img src="docs/manual/en/img/recurso-servidor-logs.jpg" alt="A server resource with its live logs" /><br /><sub><b>Resources.</b> Servers, containers and databases with live logs.</sub></td>
+    <td width="50%"><img src="docs/manual/en/img/recurso-cluster.jpg" alt="A cluster that starts several resources together" /><br /><sub><b>Clusters.</b> Start and stop a group of resources in order.</sub></td>
+  </tr>
+  <tr>
+    <td width="50%"><img src="docs/manual/en/img/cambios-diff.jpg" alt="The changes explorer showing a diff" /><br /><sub><b>Changes.</b> Git tree, diff, history and commit per agent.</sub></td>
+    <td width="50%"><img src="docs/manual/en/img/http-respuesta.jpg" alt="An HTTP request and its response" /><br /><sub><b>HTTP requests.</b> Run <code>.http</code> files and read the response.</sub></td>
+  </tr>
+</table>
+
+More in the [user manual](docs/manual/en/README.md).
+
 ## Providers
 
 | Provider | Run a turn | Transcript source |

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.3.0",
+  "version": "1.5.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/manager.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import { agents } from '../db.js';
 import { liveOrigin, notifyAgentsChanged } from '../runtime.js';
 import { cleanInbox } from './files.js';
+import { retentionPass, retentionTouched } from '../retention.js';
 import { resolveSendable } from './outbound.js';
 import { syncChannelSkill } from './channel-skill.js';
 import { handleInbound } from './router.js';
@@ -59,10 +60,21 @@ export async function stopConnection(id) {
     catch { /* already down */ }
 }
 let cleaner;
-export const startAll = () => {
-    // Received files are kept for a while, then removed.
+/** Received files are kept for a while, then removed; and what hive-am keeps of its own record is aged out (retention.ts). */
+function housekeeping() {
     cleanInbox();
-    cleaner ??= setInterval(() => cleanInbox(), 6 * 3_600_000).unref();
+    try {
+        const r = retentionPass();
+        if (retentionTouched(r))
+            console.log(`[retention] removed ${r.messages} messages, ${r.dispatches} dispatches, ${r.sessions} sessions; emptied ${r.files} file records`);
+    }
+    catch (e) {
+        console.error('[retention]', e);
+    }
+}
+export const startAll = () => {
+    housekeeping();
+    cleaner ??= setInterval(housekeeping, 6 * 3_600_000).unref();
     return Promise.all(connections.list().filter((c) => c.enabled).map((c) => startConnection(c.id)));
 };
 export const stopAll = () => Promise.all([...running.keys()].map(stopConnection));

package/server/dist/connections/router.js

@@ -12,7 +12,7 @@ const DEFAULT_RATE = 20; // messages per user per minute
 const DEFAULT_CHATTER_PER_MINUTE = 10; // times per minute that chatter nobody aimed at the agent may wake it, per thread
 /** Sent once when a turn aimed at the agent ended without a reply. */
 const NUDGE = '[hive:channel] System reminder: your last turn ended without calling `channel_reply`, so the person received nothing. If you had an answer, send it now with `channel_reply` (if the tool says it is unknown, call it again: it was still connecting). If you chose not to answer, say so in one short sentence with `channel_reply`.';
-export const EFFORTS = ['low', 'medium', 'high'];
+import { validEffort } from '../efforts.js';
 const QUIET_MS = 4000; // group chatter is handed over once it pauses this long, so a burst is one turn
 const LONG_TURN_MS = 45_000; // an unaddressed turn this long did real work: if it never replied, remind it
 const QUIET_RETRIES = 15; // while the agent is busy the hand-over waits (about a minute); after this it is left as context for the next turn
@@ -205,7 +205,7 @@ async function deliver(conn, adapter, thread, m, msgId, addressed, scheduled = f
         await reply(say(conn, T.queued(ahead)));
     const unseen = threadMessages.unseen(thread.id, fresh.seen_id, msgId).map((r) => ({ name: r.user_name ?? r.user_id ?? '?', text: r.text, files: r.files ? parseJson(r.files, undefined, `thread message ${r.id} files`) : undefined }));
     threads.markSeen(thread.id, msgId);
-    const origin = { connectionId: conn.id, threadId: thread.id, externalKey: m.externalKey, platform: conn.kind, place: m.place, userName: m.userName, userId: m.userId, group: !!m.group, mention: m.mention, addressed, replied: false, messageId: m.externalId, effort: EFFORTS.includes(conn.config.effort) ? conn.config.effort : undefined };
+    const origin = { connectionId: conn.id, threadId: thread.id, externalKey: m.externalKey, platform: conn.kind, place: m.place, userName: m.userName, userId: m.userId, group: !!m.group, mention: m.mention, addressed, replied: false, messageId: m.externalId, effort: validEffort(conn.config.effort) ? conn.config.effort : undefined };
     if (addressed)
         await adapter.busy(m.target, 'working', m.externalId).catch(() => undefined);
     const startedAt = Date.now();

package/server/dist/connections/secrets.js

@@ -1,4 +1,5 @@
 import { connections } from './store.js';
+import { objectsStore } from '../objects/store.js';
 /**
  * Last line of defence for text an agent sends to a chat. The instructions tell the agent never to share secrets, but a model can be
  * talked into it (by anyone in a group, or by an admin who does not realise what the output holds), so the text is checked here
@@ -31,6 +32,13 @@ function knownSecrets() {
             if (typeof v === 'string' && v.length >= 8)
                 out.add(v);
         }
+    // The password of a database resource: an agent can use it to connect, but it must never be repeated in a chat.
+    for (const o of objectsStore.list())
+        if (o.kind === 'database') {
+            const pw = o.config.password;
+            if (typeof pw === 'string' && pw.length >= 6)
+                out.add(pw);
+        }
     for (const [k, v] of Object.entries(process.env))
         if (v && v.length >= 12 && SECRET_ENV.test(k))
             out.add(v);