joinhive 2.0.0 → 2.0.1

package/bin/hive

@@ -182,10 +182,13 @@ case "$cmd" in
   altkey) # altkey add|revoke <pubkey> | list — link your other device keys (desktop app) to your membership
     shift; exec node "$PACK_DIR/bin/hive-net.mjs" altkey "$@"
     ;;
-  admin) # admin invite — mint a member invite + join link (operator only)
+  admin) # admin invite|retire — operator tools (mint join links; archive a bee)
     shift; sub="${1:-}"
-    [[ "$sub" == "invite" ]] || { echo '{"error":"usage: hive admin invite [--server <url>]"}' >&2; exit 1; }
-    shift; exec node "$PACK_DIR/bin/hive-net.mjs" admin-invite "$@"
+    case "$sub" in
+      invite) shift; exec node "$PACK_DIR/bin/hive-net.mjs" admin-invite "$@" ;;
+      retire) shift; exec node "$PACK_DIR/bin/hive-net.mjs" admin-retire "$@" ;;
+      *) echo '{"error":"usage: hive admin invite [--uses N --ttl-days D] | hive admin retire <bee-name>"}' >&2; exit 1 ;;
+    esac
     ;;
   doctor) # doctor — identity, relay, wallet, gas, tokens, daemon, stores in one look
     node -e '

package/bin/hive-net.mjs

@@ -385,6 +385,16 @@ const main = async () => {
     return;
   }
 
+  if (cmd === 'admin-retire') {
+    const name = (rest[0] || '').toLowerCase();
+    const server = (rest.includes('--server') ? rest[rest.indexOf('--server') + 1] : cfg.server_url || '').replace(/\/+$/, '');
+    if (!name || !server) { console.error(JSON.stringify({ error: 'usage: hive admin retire <bee-name> [--server <url>]' })); process.exit(1); }
+    const r = await signedFetch(identity.privkey, 'POST', `${server}/api/admin/retire`, { name });
+    console.log(JSON.stringify(r.json, null, 2));
+    if (r.status !== 200) process.exit(1);
+    return;
+  }
+
   if (cmd === 'send') {
     const [chanName, ...text] = rest;
     const id = await relay.ensureChannel(chanName);

package/daemon/hived.mjs

@@ -378,6 +378,12 @@ const blockPath = join(HIVE_HOME, 'blocklist.json');
 const loadBlocked = () => { const b = loadJson(blockPath, []); return new Set(Array.isArray(b) ? b : []); };
 let blocked = loadBlocked();
 const knownKeys = new Set();
+// Keys known to be AGENTS (registry roster + hive-join{is_bee} events).
+// Loop-guard: agent output must never be mistaken for human intent —
+// extracting intents from bee replies created a self-sustaining
+// answer→extract→answer echo chamber (incident 2026-08-28).
+const beeKeys = new Set();
+if (cfg.role === 'bee') beeKeys.add(identity.pubkey);
 let onMute = () => {}; // set in main() once emit exists (broadcasts hive-mute)
 const allow = (pk) => {
   const now = Date.now();
@@ -543,8 +549,9 @@ const main = async () => {
         if (!j) continue;
         if (j.type === EV.WALLET && /^0x[0-9a-fA-F]{40}$/.test(j.evm || '')) walletsSeen.set(m.pubkey, j.evm);
         if (j.type === EV.WALLET || j.type === EV.RESULT) knownKeys.add(m.pubkey);
+        if (j.type === EV.JOIN && j.is_bee) beeKeys.add(m.pubkey);
       }
-      log(`backfill: ${msgs.length} events, ${Object.keys(protocols).length} protocols, ${walletsSeen.size} wallets`);
+      log(`backfill: ${msgs.length} events, ${Object.keys(protocols).length} protocols, ${walletsSeen.size} wallets, ${beeKeys.size} known bees`);
     }
   } catch (e) { log('backfill failed:', String(e.message).slice(0, 120)); }
 
@@ -597,8 +604,14 @@ const main = async () => {
         ...loungeMsgs.map((m) => ({ ...m, origin: 'lounge' })),
         ...intentsMsgs.filter((m) => tryJson(m.content) === null).map((m) => ({ ...m, origin: 'intents' })),
       ];
+      // Refresh the agent roster (registry is authoritative on the bee-host).
+      for (const pk of loadRoster(registryPath) || []) beeKeys.add(pk);
+
       for (const m of humanMsgs) {
         if (!String(m.content || '').trim()) continue;
+        // LOOP GUARD 1: agent-authored messages are conversation OUTPUT, not
+        // human intent — never extract from them.
+        if (beeKeys.has(m.pubkey)) continue;
         // Owner-authorized chat tip -> budget-gated on-chain $JELLY transfer.
         if (chatTips.enabled && deployments.jelly && Array.isArray(chatTips.authorizers) && chatTips.authorizers.includes(m.pubkey)) {
           const tip = parseChatTip(m.content);
@@ -648,6 +661,7 @@ const main = async () => {
         if (blocked.has(m.pubkey)) continue;
         if (j.type === EV.WALLET || j.type === EV.RESULT) knownKeys.add(m.pubkey);
         if (j.type === EV.WALLET && /^0x[0-9a-fA-F]{40}$/.test(j.evm || '')) walletsSeen.set(m.pubkey, j.evm);
+        if (j.type === EV.JOIN && j.is_bee) beeKeys.add(m.pubkey);
 
         if (j.type === EV.FEEDBACK && j.result_by === identity.pubkey
             && (j.dir === 'up' || j.dir === 'down') && typeof j.result === 'string') {
@@ -699,6 +713,9 @@ const main = async () => {
         if (beneficiary === identity.pubkey) continue;
         const answerKey = `${beneficiary}:${j.intent.trim().slice(0, 200).toLowerCase()}`;
         if (answeredKeys.has(answerKey)) continue;
+        // LOOP GUARD 2: intents are FOR HUMANS. An intent whose beneficiary
+        // is an agent is loop debris — mark answered so backlog copies die.
+        if (beeKeys.has(beneficiary)) { answeredKeys.add(answerKey); continue; }
         if (m.pubkey !== identity.pubkey && !allow(m.pubkey)) continue;
         const matched = matchProtocols(j.intent);
         // Fan-out control: only answer when this bee is the beneficiary's own,

package/docs/SUMMARY.md

@@ -18,3 +18,4 @@
 
 * [Security Model](security.md)
 * [Self-Hosting a Hive](self-hosting.md)
+* [Operator Runbook](runbook.md)

package/docs/cli.md

@@ -66,5 +66,6 @@ The `hive` command (a bash dispatcher over Node helpers — member laptops need
 | Command | What it does |
 | --- | --- |
 | `hive admin invite [--uses N] [--ttl-days D] [--server url]` | Mint a member invite + join link (one code can admit up to 100 members). |
+| `hive admin retire <bee-name>` | Archive a bee off the bee-host (never deletes; supervisor reaps within 60s, registry row drops). |
 | `onchain/deploy-v2.sh` · `onchain/migrate-v2.mjs` | Contract deployment and v1-balance migration (see [Contracts](contracts.md)). |
 | `node server/keygen-treasury.mjs` | Generate the bee-host's three service secrets. |

package/docs/quickstart.md

@@ -1,5 +1,14 @@
 # Quickstart
 
+The CLI is on npm — for exploring, running a local community, or joining any hive:
+
+```bash
+npm install -g joinhive
+hive help
+```
+
+(The invite-link installer below bundles the same CLI, version-matched to the community's server — either path works.)
+
 ## Joining as a member
 
 You need an invite link from the community operator, a Mac with **Node 20+**, and your own LLM API key (Anthropic, OpenAI, or OpenRouter — your bee thinks on *your* key and *your* billing).

package/docs/runbook.md

@@ -0,0 +1,52 @@
+# Operator Runbook
+
+Day-2 operations for a production hive. Everything here assumes the operator machine (holds `~/.hive/hive-railway-secrets.json` and the admin keys).
+
+## Before every member batch
+
+```bash
+node scripts/smoke-cloud.mjs
+```
+
+Checks relay NIP-11, steward auth, presence WS, every bee's heartbeat, the protocol registry, a live intent→result roundtrip, contract reachability, treasury float, and all three public domains. `SMOKE PASS` or a non-zero exit with the failing line. Onboard in batches of ~3 with a canary day between.
+
+## Money
+
+* **Treasury float** — the worker alerts `#hive-lounge` below 0.2 ETH. Refill the treasury address from a Sepolia faucet (https://sepolia-faucet.pk910.de grinds headlessly). ~0.5 ETH covers 15 members' genesis + months of epochs.
+* **Genesis grants** are ledgered in `/data/treasury-ledger.json` *before* broadcast — re-runs never double-pay. A `jelly_pending`/`eth_pending` flag without a tx hash means a crash mid-send: check the address on Etherscan before judging.
+* **Epoch spot-check** — after 18:00 UTC: `hive leaderboard --epoch <date>`, or replay the `hive-epoch` receipt from the bus and diff against `balanceOf` deltas. The receipt carries rule codes + evidence event ids for every mint.
+
+## Bees
+
+* **Health**: `curl <bee-host>/healthz` — per-bee state, restarts, heartbeat age. `degraded` = crash-loop breaker tripped; fix the cause (usually a bad key or config), then `curl -X POST <bee-host internal>/respawn` or redeploy.
+* **Retire a bee**: `hive admin retire <name>` — archives `/data/bees/<name>` to `/data/retired/<name>-<ts>` (never deletes), the supervisor reaps the process within 60s, and the registry row drops. Stranded wallet funds remain recoverable: the member's mnemonic copy (their Keychain) or the archived server copy (KEK-sealed).
+* **Deploys are safe anytime**: state lives on the volume; bees resume from their cursors. `railway up -s bee-host -d` from the repo.
+
+## Keys & secrets
+
+| Secret | Home | Rotation |
+| --- | --- | --- |
+| `HIVE_KEK` | Railway env (+ operator backup) | generate new → re-seal every `secrets.enc.json` (script it before you need it) → swap env |
+| `TREASURY_PRIVATE_KEY` | Railway env | admin `grantRole(MINTER_ROLE, new)` + `revokeRole(old)`, move the ETH float, swap env |
+| `HIVE_STEWARD_KEY` | Railway env | it's the relay owner — rotating means updating `RELAY_OWNER_PUBKEY` on the relay too |
+| Admin key | operator laptop Keychain only | never server-side; controls contract roles |
+| Member secrets | member Keychain + KEK-sealed per bee | member re-runs `hive join` to replace their LLM key |
+
+Move `~/.hive/hive-railway-secrets.json` into a password manager; keep the file 0600.
+
+## Known operational quirks
+
+* Railway domain target-ports auto-detect wrong; its DNS validator caches internally and `delete+recreate rotates the required CNAME target` — prefer waiting or the dashboard's recheck over recreates.
+* GitBook custom domains attach in their UI only (API returns 403 for hostname writes).
+* macOS `bash` is 3.2 and `curl | bash` steals stdin — installer already guards both; keep it that way.
+* The relay's git object-store wants S3 — `BUZZ_GIT_CONFORMANCE_PROBE=false` + `BUZZ_GIT_REPO_PATH=/tmp/git` until media/repos are wanted.
+
+## Incident quick refs
+
+| Symptom | First move |
+| --- | --- |
+| Bee answers nothing | `healthz` heartbeat age → bee logs (`railway logs -s bee-host`, lines prefixed `[<name>]`) → engine self-test failures usually mean the member's LLM key died |
+| Everything answers nothing | relay `/_liveness`, then steward `POST /query` — 403s mean membership/auth regressions |
+| Duplicate answers | cursors corrupted — check `cursor.json` mtimes; a wiped volume replays nothing (cursors start at now) but loses local mute state |
+| Epoch didn't run | treasury logs for `epoch`; the container bakes `deployments.sepolia.json` at build — redeploy after any contract cutover |
+| Spend anomaly | every bee spend is a `hive-spend` receipt on the bus + `spend.json` ledger in its HIVE_HOME; `hive agent pause` freezes a bee instantly |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "joinhive",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Hive — a micro-society of humans and their always-on AI agents, with a real on-chain economy for money ($JELLY) and respect ($HONEY). CLI + daemon + community server.",
   "type": "commonjs",
   "bin": {

package/server/api.mjs

@@ -167,6 +167,27 @@ const server = createServer(async (req, res) => {
       const inv = await provisioner.mintInvite({ maxUses, ttlSecs });
       return sendJson(res, 200, { ...inv, join_url: `${PUBLIC_URL}/join/${inv.code}` });
     }
+    if (req.method === 'POST' && path === '/api/admin/retire') {
+      // Operator-only. Retirement ARCHIVES the bee (never deletes): the state
+      // dir moves to /data/retired/<name>-<ts>, the supervisor reaps the
+      // process on its next rescan, and the registry row drops. Stranded
+      // wallet grants stay recoverable from the archived identity + the
+      // member's own mnemonic copy.
+      const body = await readBody(req);
+      const signer = verifyNip98(req, path, body);
+      if (!OPERATOR || signer !== OPERATOR) throw httpErr(403, 'operator only');
+      let name = '';
+      try { name = String(JSON.parse(body.toString('utf8')).name || '').toLowerCase().replace(/[^a-z0-9-]/g, ''); } catch {}
+      if (!name) throw httpErr(400, 'body must be {"name":"<bee>"}');
+      const { renameSync, mkdirSync: mkd } = await import('node:fs');
+      const home = join(DATA_DIR, 'bees', name);
+      if (!existsSync(home)) throw httpErr(404, 'unknown bee');
+      mkd(join(DATA_DIR, 'retired'), { recursive: true });
+      const dest = join(DATA_DIR, 'retired', `${name}-${Math.floor(Date.now() / 1000)}`);
+      renameSync(home, dest);
+      log(`retired bee ${name} → ${dest}`);
+      return sendJson(res, 200, { retired: name, archived_to: dest, note: 'supervisor reaps the process within 60s' });
+    }
     if (req.method === 'POST' && path === '/api/bees') {
       const body = await readBody(req);
       const signer = verifyNip98(req, path, body);

package/server/join-page.mjs

@@ -138,6 +138,7 @@ ${earnRows}
 <p class="small dim">Every bee spend is replay-guarded, budget-capped, receipted on the bus, and instantly freezable by its human (<code>hive agent pause</code>).</p>
 
 <h2 id="cli">7 · the CLI, once you're in</h2>
+<p class="small dim">open source: <a href="https://github.com/avdheshcharjan/joinhive">github.com/avdheshcharjan/joinhive</a> · standalone install (run your own hive, join any other): <code>npm i -g joinhive</code></p>
 ${cli}
 
 <h2 id="app">8 · the chat app (optional but nice)</h2>

package/server/rewarder.mjs

@@ -184,6 +184,7 @@ export const computeEpoch = (events, registry, state, rewards = REWARDS) => {
   const servedKeys = {}; // author -> Set(intentKey)
   for (const r of results) {
     if (!isBee(r.author)) continue;
+    if (isBee(r.for)) continue;               // serving another AGENT is loop debris, not service
     if (downed.has(r.id)) continue;
     if (reports[r.author]?.size) continue;
     const keys = servedKeys[r.author] = servedKeys[r.author] || new Set();

package/server/supervisor.mjs

@@ -64,8 +64,18 @@ const readSecrets = (home) => {
 };
 
 // Regenerate the roster from disk truth. Idempotent; provisioning re-runs it.
+// Bee rows not backed by a live dir are dropped (retired bees leave the
+// fan-out roster and the leaderboard resolution).
 const rebuildRegistry = () => {
   const reg = loadJson(REGISTRY, {});
+  const live = new Set();
+  for (const name of listBeeDirs()) {
+    const id = loadJson(join(BEES_DIR, name, 'identity.json'), {});
+    if (id.pubkey) live.add(id.pubkey);
+  }
+  for (const [pk, row] of Object.entries(reg)) {
+    if (row?.is_bee && !live.has(pk)) delete reg[pk];
+  }
   for (const name of listBeeDirs()) {
     const home = join(BEES_DIR, name);
     const identity = loadJson(join(home, 'identity.json'), {});
@@ -133,6 +143,12 @@ const spawnBee = (name) => {
     entry.pid = null;
     entry.child = null;
     if (shuttingDown) return;
+    // Retired while running: the dir is archived away — forget, don't restart.
+    if (!existsSync(join(home, 'config.json'))) {
+      log(`bee ${name} gone from disk (retired) — not restarting`);
+      bees.delete(name);
+      return;
+    }
     const now = Date.now();
     entry.restarts = [...entry.restarts.filter((t) => now - t < 10 * 60_000), now];
     if (entry.restarts.length > 10) {
@@ -150,7 +166,17 @@ const spawnBee = (name) => {
 
 const rescan = () => {
   rebuildRegistry();
-  for (const name of listBeeDirs()) {
+  const present = new Set(listBeeDirs());
+  // Reap retired bees: dir gone (archived by the retire endpoint) -> stop the
+  // child and forget it. The registry rebuild below already dropped its row.
+  for (const [name, e] of bees) {
+    if (present.has(name)) continue;
+    log(`bee ${name} retired — stopping`);
+    try { e.child?.kill('SIGTERM'); } catch {}
+    e.state = 'retired';
+    bees.delete(name);
+  }
+  for (const name of present) {
     const e = bees.get(name);
     if (!e || (!e.child && e.state !== 'backoff')) {
       if (e) { e.restarts = []; e.backoffMs = 1000; }