@inetafrica/open-claudia 2.14.8 → 2.15.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v2.15.0
+- **Production-hardening pass (P0). Two root causes, closed at the source.** A deep-dive audit traced the reliability and safety gaps to two patterns: (1) **overloaded return contracts** where a falsy value meant both "no id" and "failed", so callers guessed — the exact shape behind v2.14.8's Kazee double-send; and (2) **unsafe shared state under concurrency**, amplified because the owner's Telegram + Kazee turns now share ONE in-memory state object *and* load-modify-write the same JSON files under unified identity. This release fixes both, plus the credential-exposure and crash-durability gaps found alongside them. No new deps, no new required env, no schema change.
+- **One explicit delivery contract, so no caller guesses.** Adapters historically overloaded `send()`'s return: a message id on success, a bare `true` for an idless success (server fast-ack), or a falsy value on failure. `core/io.send()` now collapses every adapter's raw return through `normalizeSendResult` into `{ ok, messageId, editable }` — `messageId` is always a string or null, so `typeof`/edit-target checks are uniform across transports. The runner's final-delivery guard is now `if (!sent.ok)` (an idless success no longer reads as failure → no phantom re-send), and the streaming-preview path keeps the real string id when editable or a truthy sentinel otherwise, so `canEditStatus()` still declines to edit an unaddressable bubble. The loopback approval-prompt send routes through the same normalizer. New `test-delivery-contract.js`.
+- **Crash-safe atomic writes for every durable JSON store.** `state.json`, `sessions.json`, and `identities.json` were each written with a bare `fs.writeFileSync(JSON.stringify(...))` — a crash or a full disk mid-write left a truncated file that fails to parse, and the loaders swallowed the parse error and returned `{}`, i.e. **silent total data loss** (every session pointer, per-user setting, and identity link gone). New `core/fsutil.js` provides `atomicWriteFileSync` (write to a temp file, `fsync`, then `rename` — atomic on POSIX — keeping a `.bak` sibling) and `readJsonWithFallback` (try the file, then its `.bak`, then the default). Every loader/writer in `core/state.js` and `core/identity.js` now uses them, and a failed write logs instead of vanishing. An interrupted flush now falls back to the last good file rather than wiping state.
+- **A synchronous single-flight run-lock closes the double-spawn race.** The turn guard was `if (state.runningProcess)`, but `runningProcess` isn't set until *after* the pre-spawn awaits (recall, auto-compaction, auth preflight). Two turns for one canonical user — the owner's Telegram and Kazee messages sharing one state object — could both pass the check during that window and both spawn, racing the shared state and JSON files. New `state.acquireRunLock()` arms `state.preparingRun` **synchronously** (no `await` between test and set), so the second turn queues cleanly; the lock is released if a run bails before spawning (auth preflight) so a never-spawned turn can't wedge the next one. New `test-run-lock.js` proves the single-flight property on a shared state object.
+- **Dashboard credential exposure closed on three fronts.** (1) `GET /api/config` returned the **raw `.env`** — every bot token, model API key, and the web control token in plaintext — to anyone holding a dashboard session; it now passes through `maskEnv`, which masks any secret-looking key to a 4-char tail (the config UI only ever edits the non-secret `SAFE_KEYS`, and masked values can't round-trip back in). (2) The session cookie was a **static `sha256(password)`** — identical for every login, unexpiring, and impossible to revoke short of a password change; replaced by `core/web-sessions.js`, which mints a random 256-bit token per login, tracks it server-side with a 24h expiry, validates the cookie against that store, and supports individual `revoke` + `revokeAll` (a password change now drops every outstanding session, then re-issues one for the caller). Sessions persist via the atomic writer, so a login survives a restart/upgrade. (3) The bot's own control-plane secrets (`TELEGRAM_BOT_TOKEN`, `KAZEE_BOT_TOKEN`, `BOT_CONTROL_TOKEN`) are now **stripped from the ambient subprocess env** (`botSubprocessEnv`) — the model CLI is authed by its own token/key and `open-claudia` CLIs re-read `.env` from disk, so nothing legitimately needs them, and a prompt-injected agent dumping its environment can no longer read them. New `test-web-sessions.js` (token lifecycle, targeted + mass revoke, expiry sweep, prototype-pollution-key rejection, disk persistence).
+- **Crashes and shutdowns no longer lose state or die silently.** In-memory per-user state (settings, session pointers, usage, compaction timestamps) was only ever flushed opportunistically — a `SIGTERM` (every deploy/restart) or an uncaught exception dropped whatever hadn't been saved. A new best-effort synchronous `persist()` (→ `saveState()`, made crash-safe by the atomic writer above) now runs in `gracefulShutdown` and in the `uncaughtException` handler before exit. And `notifyError` — the last-ditch crash notifier — now **redacts secrets** before sending (`core/redact`), hardens the raw Telegram POST (`req.on("error")` guard so the notifier can't itself throw; correct `Content-Length` via `Buffer.byteLength`), and adds a second path that relays to the owner's **primary channel** via a live adapter, so a Kazee-only owner is reached too (skipped when the raw Telegram ping already covers a Telegram-primary owner — no double-notify).
+- **Agent-space / OpenClaw:** no new deps, no new env, no schema change; Docker image builds identically. All changes are correctness/safety hardening — inert-by-default and back-compatible, with one **visible behaviour change on upgrade**: because the dashboard session model changed, any existing dashboard cookie is invalidated once, so a logged-in browser is asked to log in again after this upgrade (expected, one-time). Three new hermetic tests (`test-run-lock.js`, `test-web-sessions.js`, `test-delivery-contract.js`) wired into `npm test`; full suite green.
+
 ## v2.14.8
 - **Kazee replies no longer post twice.** On a successful send, the Kazee adapter's `send()` returned the created message's id so the runner can edit its streaming preview in place — but it read only `res.message._id`, then fell back to the ActionHero envelope's numeric `messageId`, then `res._id`. chat-central serves the new message's id under `message.id` on some routes (the adapter's own reply-to fetch already handles `m._id || m.id`), so when only `.id` was present `send()` returned `null`. The final-delivery path in `core/runner.js` reads that return as "did the send fail?": `const sent = await send(firstChunk, { replyTo }); if (!sent) await send(firstChunk);`. A successful-but-idless send therefore looked like a failure and the reply was posted a second time — once as a reply-quote, once as a plain bubble (exactly the pair seen in-chat). `send()` now returns `message._id || message.id` (or the top-level equivalents) and **never** the numeric envelope `messageId` — that counter is a per-request id, not a chat message id, and using it also made later `PUT /message/<counter>` edits 500.
 - **A streaming preview minted on one channel is never edited on another.** Under unified identity the owner's Telegram and Kazee turns share ONE per-canonical state object, and `statusMessageId` (the id of the live "typing…/preview" bubble) sat on it untagged. A Telegram message id (e.g. `24991`) could then be edited under the Kazee adapter → `PUT /message/24991` → *"Cast to ObjectId failed"* 500, a frozen preview, and a duplicate final send. `statusMessageId` now carries the channel it was minted on (`statusMessageChannel`, `core/state.js`); every edit-in-place site in `core/runner.js` (streaming tick + final delivery + the external-hold notice) only edits when the channel matches, otherwise it discards the stale id and sends fresh on the correct channel. Telegram-only deployments are unaffected (single channel → always matches).

package/bot.js

@@ -44,6 +44,18 @@ if (adapters.length === 0) {
 const { userStates } = require("./core/state");
 const { killProcessTree } = require("./core/process-tree");
 
+// Flush durable in-memory state (per-user settings, session pointers, usage,
+// compaction timestamps) to disk. Synchronous + best-effort so it is safe to
+// call from a shutdown signal or a crash handler, where the event loop may not
+// survive an async write. Atomic writes (core/fsutil) make an interrupted flush
+// safe: a reader falls back to the last good file or its .bak sibling. Only
+// per-user state is held in memory between turns — sessions and identities are
+// written on every mutation, so there is nothing else to flush here.
+function persist() {
+  try { require("./core/state").saveState(); }
+  catch (e) { console.error("persist: saveState failed:", e?.message); }
+}
+
 async function gracefulShutdown(signal) {
   console.log(`Received ${signal}, shutting down gracefully...`);
   for (const state of userStates.values()) {
@@ -68,17 +80,28 @@ async function gracefulShutdown(signal) {
       }
     }
   } catch (e) {}
+  persist();
   process.exit(0);
 }
 
 process.on("SIGINT", () => gracefulShutdown("SIGINT"));
 process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
 
-// Last-ditch crash notification. Prefers Telegram (cheapest, no setup);
-// falls back silent. Anything richer needs an adapter that's still alive.
+// Last-ditch crash notification: surface failures to the owner instead of
+// letting the process die silently. Secrets are redacted first. Two additive
+// paths so a non-Telegram owner is still reached:
+//   1) a raw Telegram POST — no adapter/people deps, safe even when the event
+//      loop is wedged; owns the (common) Telegram-primary owner, and
+//   2) a best-effort relay to the owner's primary channel via a live adapter,
+//      which covers a Kazee-only owner the raw path can't. Skipped when the raw
+//      Telegram ping already covers a Telegram-primary owner (no double-notify).
 function notifyError(label, err) {
-  const msg = `${label}: ${err?.message || err}`.slice(0, 1000);
+  let msg = `${label}: ${err?.message || err}`;
+  try { msg = require("./core/redact").redactSensitive(msg); } catch (e) {}
+  msg = msg.slice(0, 1000);
   console.error(msg, err?.stack || "");
+
+  let rawTelegram = false;
   try {
     const token = process.env.TELEGRAM_BOT_TOKEN;
     const chatId = process.env.TELEGRAM_CHAT_ID?.split(",")[0];
@@ -86,16 +109,28 @@ function notifyError(label, err) {
       const data = JSON.stringify({ chat_id: chatId, text: msg });
       const req = require("https").request({
         hostname: "api.telegram.org", path: `/bot${token}/sendMessage`,
-        method: "POST", headers: { "Content-Type": "application/json", "Content-Length": data.length },
+        method: "POST", headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(data) },
       });
+      req.on("error", () => {}); // the notifier must never itself throw
       req.write(data);
       req.end();
+      rawTelegram = true;
+    }
+  } catch (e) {}
+
+  try {
+    const owner = require("./core/people").owners()[0];
+    const primary = owner?.primaryChannel?.adapter;
+    const alreadyCovered = rawTelegram && (!primary || primary === "telegram");
+    if (owner && !alreadyCovered) {
+      require("./core/relay").send({ text: msg, target: { personId: owner.id }, kind: "crash-notify" }).catch(() => {});
     }
   } catch (e) {}
 }
 
 process.on("uncaughtException", (err) => {
   notifyError("Uncaught exception", err);
+  try { persist(); } catch (e) {}
   setTimeout(() => process.exit(1), 2000);
 });
 process.on("unhandledRejection", (reason) => notifyError("Unhandled rejection", reason));

package/core/config.js

@@ -229,13 +229,25 @@ function loadChannels() {
   return channels;
 }
 
+// The bot's own control-plane secrets. No subprocess the bot spawns — the
+// Claude/Codex/Cursor CLI, sub-agents, the recall walker, tools, auth flows —
+// ever needs these: the model CLI is authed via CLAUDE_CODE_OAUTH_TOKEN (added
+// on top by claudeSubprocessEnv) or its own API key, and `open-claudia` CLI
+// invocations re-read the .env file from disk. Stripping them from the ambient
+// subprocess env closes the easiest exfil path — a prompt-injected agent (or any
+// child) dumping its own environment can no longer read the bot's Telegram/Kazee
+// tokens or the web control token.
+const CONFINED_SECRET_KEYS = ["TELEGRAM_BOT_TOKEN", "KAZEE_BOT_TOKEN", "BOT_CONTROL_TOKEN"];
+
 function botSubprocessEnv() {
   // Credential confinement (5b): the operational keyring is deliberately NOT
   // merged here. Agent shells, sub-agents, and every other bot subprocess run
   // cred-free; keyring values enter ONLY tool-run subprocesses (tools.runEnv —
   // the keys a tool declares via --requires) and the logged escape hatch
   // (`keyring exec --reason`). See core/tool-guard.js for the deny-gate half.
-  return { ...process.env, PATH: FULL_PATH, HOME: process.env.HOME || require("os").homedir() };
+  const env = { ...process.env, PATH: FULL_PATH, HOME: process.env.HOME || require("os").homedir() };
+  for (const k of CONFINED_SECRET_KEYS) delete env[k];
+  return env;
 }
 
 module.exports = {

package/core/fsutil.js

@@ -0,0 +1,38 @@
+// Crash-safe JSON persistence. A bare writeFileSync can be interrupted
+// mid-write (crash, OOM kill, power loss) and leave a truncated, unparseable
+// file — for irreplaceable state (identities, sessions, per-user buckets) that
+// is data loss. Instead we write to a sibling temp file, fsync it to durable
+// storage, optionally snapshot the last-good file to `<file>.bak`, then rename
+// the temp over the target. A POSIX rename is atomic, so a reader always sees
+// either the whole old file or the whole new one — never a half-written one.
+
+const fs = require("fs");
+const path = require("path");
+
+function atomicWriteFileSync(file, data, { backup = false } = {}) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  const fd = fs.openSync(tmp, "w");
+  try {
+    fs.writeSync(fd, data);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  // Snapshot the previous good version before we overwrite, so a corrupt or
+  // wrong write is still recoverable via readJsonWithFallback.
+  if (backup) {
+    try { if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.bak`); } catch (e) {}
+  }
+  fs.renameSync(tmp, file);
+}
+
+// Parse JSON from `file`, transparently falling back to `<file>.bak` if the
+// primary is missing or corrupt, and to `fallback` if neither is usable.
+function readJsonWithFallback(file, fallback) {
+  try { return JSON.parse(fs.readFileSync(file, "utf-8")); } catch (e) {}
+  try { return JSON.parse(fs.readFileSync(`${file}.bak`, "utf-8")); } catch (e) {}
+  return fallback;
+}
+
+module.exports = { atomicWriteFileSync, readJsonWithFallback };

package/core/identity.js

@@ -3,8 +3,8 @@
 // transport. Default canonical is `<transport>:<channelId>`; the user
 // can override with /link <email-or-id> to merge state across channels.
 
-const fs = require("fs");
 const { IDENTITIES_FILE } = require("./config");
+const { atomicWriteFileSync, readJsonWithFallback } = require("./fsutil");
 
 function normalizeCanonicalUserId(value) {
   return String(value || "").trim().toLowerCase();
@@ -19,21 +19,18 @@ function defaultCanonicalForChannel(transport, channelId) {
 }
 
 function loadIdentities() {
-  try {
-    const raw = JSON.parse(fs.readFileSync(IDENTITIES_FILE, "utf-8"));
-    return {
-      channels: raw && typeof raw.channels === "object" ? raw.channels : {},
-      preferred: raw && typeof raw.preferred === "object" ? raw.preferred : {},
-    };
-  } catch (e) {
-    return { channels: {}, preferred: {} };
-  }
+  const raw = readJsonWithFallback(IDENTITIES_FILE, null);
+  return {
+    channels: raw && typeof raw.channels === "object" ? raw.channels : {},
+    preferred: raw && typeof raw.preferred === "object" ? raw.preferred : {},
+  };
 }
 
 const identities = loadIdentities();
 
 function saveIdentities() {
-  try { fs.writeFileSync(IDENTITIES_FILE, JSON.stringify(identities, null, 2)); } catch (e) {}
+  try { atomicWriteFileSync(IDENTITIES_FILE, JSON.stringify(identities, null, 2), { backup: true }); }
+  catch (e) { console.error("saveIdentities: write failed:", e.message); }
 }
 
 // A channel is a "configured owner channel" when its (transport, channelId)

package/core/io.js

@@ -4,14 +4,35 @@
 
 const { currentAdapter, currentChannelId, currentUserId } = require("./context");
 
+// Adapters historically overloaded their send() return value: a message id
+// (Telegram numeric, Kazee ObjectId string) on success, a bare `true` when
+// delivery succeeded but no editable id came back (server fast-ack), or a
+// falsy value (null/false/undefined) on failure. Callers then guessed —
+// `if (!sent)` read an idless success as a failure (the Kazee double-send),
+// and a `typeof === "string"` edit-guard silently rejected Telegram's numeric
+// id. Collapse every adapter's raw return into ONE explicit shape so no caller
+// has to guess: { ok, messageId, editable }. messageId is always a string or
+// null, so downstream typeof/edit-target checks are uniform across transports.
+function normalizeSendResult(raw) {
+  if (raw === null || raw === undefined || raw === false) {
+    return { ok: false, messageId: null, editable: false };
+  }
+  if (raw === true) {
+    return { ok: true, messageId: null, editable: false };
+  }
+  const id = String(raw);
+  if (!id) return { ok: true, messageId: null, editable: false };
+  return { ok: true, messageId: id, editable: true };
+}
+
 async function send(text, opts = {}) {
   const adapter = currentAdapter();
   const channelId = opts.channelId || currentChannelId();
   if (!adapter || !channelId) {
     console.error("send() called outside chat context");
-    return null;
+    return { ok: false, messageId: null, editable: false };
   }
-  return adapter.send(channelId, text, opts);
+  return normalizeSendResult(await adapter.send(channelId, text, opts));
 }
 
 async function editMessage(messageId, text, opts = {}) {
@@ -75,4 +96,4 @@ function splitMessage(text, maxLen = 4000) {
   return chunks;
 }
 
-module.exports = { send, editMessage, deleteMessage, sendVoice, sendVoiceEnd, sendFile, typing, splitMessage };
+module.exports = { send, editMessage, deleteMessage, sendVoice, sendVoiceEnd, sendFile, typing, splitMessage, normalizeSendResult };

package/core/loopback.js

@@ -512,8 +512,9 @@ async function handleJson(req, res, url, kind) {
       // <pre> needs Telegram's HTML parse mode to render; other adapters ignore it.
       const sendOpts = { keyboard };
       if (adapter.type === "telegram") sendOpts.parseMode = "HTML";
-      const ok = await adapter.send(channelId, text, sendOpts);
-      if (!ok) { approvals.decide(rec.id, "denied", "send-failed"); return reply(res, 500, { error: "could not deliver approval prompt" }); }
+      const { normalizeSendResult } = require("./io");
+      const sent = normalizeSendResult(await adapter.send(channelId, text, sendOpts));
+      if (!sent.ok) { approvals.decide(rec.id, "denied", "send-failed"); return reply(res, 500, { error: "could not deliver approval prompt" }); }
       audit.log("tool.approval.requested", { id: rec.id, tool: rec.tool, verb: rec.verb, channelId });
       return reply(res, 200, { ok: true, id: rec.id });
     } catch (e) { return reply(res, 400, { error: e.message }); }

package/core/runner.js

@@ -11,7 +11,7 @@ const {
   AUTO_COMPACT_TOKENS, MIN_COMPACT_INTERVAL_MS, MAX_PROCESS_TIMEOUT, COMPACT_SUMMARY_TIMEOUT, botSubprocessEnv,
   CONFIG_DIR, WORKSPACE, config,
 } = require("./config");
-const { currentState, saveState, recordSession, userOwnsClaudeSession, resetSessionUsage } = require("./state");
+const { currentState, saveState, recordSession, userOwnsClaudeSession, resetSessionUsage, acquireRunLock } = require("./state");
 const { chatContext, currentChannelId, currentAdapter, currentUserId } = require("./context");
 const { splitLeadingOriginGroup } = require("./queue-drain");
 const { buildSystemPrompt, promptWithDynamicContext } = require("./system-prompt");
@@ -803,7 +803,7 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   try { externalSpeaker = require("./relationship").isCurrentSpeakerGuarded(); } catch (e) {}
   cwd = resolveRunCwd(cwd);
 
-  if (state.runningProcess) {
+  if (!acquireRunLock(state)) {
     // Capture the origin channel so the drained reply routes back to where the
     // message came from. Under unified identity the owner's channels share one
     // run-lock and queue, so a Kazee message queued during a Telegram run must
@@ -815,6 +815,9 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
 
   const authPreflight = preflightClaudeAuthMessage();
   if (authPreflight) {
+    // Lock was armed synchronously above; release it before bailing so the
+    // next turn isn't wedged behind a run that never spawned.
+    state.preparingRun = false;
     await send(authPreflight, { replyTo: replyToMsgId });
     return;
   }
@@ -864,7 +867,8 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   };
   // Pre-spawn window (recall/compaction/auth): /stop has no process to kill, so
   // it sets state.cancelRequested and we bail at the checkpoint before spawning.
-  state.preparingRun = true;
+  // preparingRun was armed synchronously by acquireRunLock() at the top of this
+  // function so the lock already spans the auth/compact awaits above — no re-arm.
   state.cancelRequested = false;
   startTyping();
   state.statusMessageId = null;
@@ -1252,7 +1256,12 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
           state.statusMessageChannel = null;
         }
         if (!state.statusMessageId && assistantText) {
-          state.statusMessageId = await send(display.length > 4000 ? display.slice(-4000) : display, telegramHtmlOpts({ replyTo: replyToMsgId }));
+          const previewResult = await send(display.length > 4000 ? display.slice(-4000) : display, telegramHtmlOpts({ replyTo: replyToMsgId }));
+          // Keep the real string id when the preview is editable (Telegram +
+          // Kazee both normalize to a string now); otherwise a truthy sentinel
+          // so we don't re-post a fresh preview each tick, while canEditStatus()
+          // (typeof string) still declines to edit an unaddressable message.
+          state.statusMessageId = previewResult.editable ? previewResult.messageId : (previewResult.ok ? true : null);
           state.statusMessageChannel = channelId;
         } else if (canEditStatus()) {
           await editMessage(state.statusMessageId, display.length > 4000 ? display.slice(-4000) : display, telegramHtmlOpts({ streaming: true }));
@@ -1528,7 +1537,7 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
         await editMessage(state.statusMessageId, firstChunk, telegramHtmlOpts({ streaming: true }));
       } else {
         const sent = await send(firstChunk, telegramHtmlOpts({ replyTo: replyToMsgId }));
-        if (!sent) await send(firstChunk);
+        if (!sent.ok) await send(firstChunk);
         for (let i = 1; i < chunks.length; i++) {
           await send(chunks[i], telegramHtmlOpts());
         }

package/core/state.js

@@ -17,9 +17,10 @@ const {
   identities,
 } = require("./identity");
 const { currentChannelId, currentCanonicalUserId } = require("./context");
+const { atomicWriteFileSync, readJsonWithFallback } = require("./fsutil");
 
 function loadStateFile() {
-  try { return JSON.parse(fs.readFileSync(STATE_FILE, "utf-8")); } catch (e) { return {}; }
+  return readJsonWithFallback(STATE_FILE, {});
 }
 
 function mergeSavedState(existing, next) {
@@ -120,6 +121,17 @@ function resetSettings(state = currentState()) {
   state.settings = freshSettings();
 }
 
+// Synchronous single-flight run-lock. Returns true and arms the lock if no turn
+// is running or preparing for this user; false if the caller must queue. There
+// must be NO await between calling this and the work it guards, so two turns for
+// one canonical user (owner's Telegram + Kazee sharing one state under unified
+// identity) can never both acquire and then race the shared state + JSON files.
+function acquireRunLock(state = currentState()) {
+  if (state.runningProcess || state.preparingRun) return false;
+  state.preparingRun = true;
+  return true;
+}
+
 function saveState() {
   const data = { users: { ...(savedState.users || {}) } };
   for (const [id, s] of userStates) {
@@ -135,14 +147,14 @@ function saveState() {
     };
   }
   savedState.users = data.users;
-  try { fs.writeFileSync(STATE_FILE, JSON.stringify(data)); } catch (e) {}
+  try { atomicWriteFileSync(STATE_FILE, JSON.stringify(data), { backup: true }); }
+  catch (e) { console.error("saveState: write failed:", e.message); }
 }
 
 // ── Sessions ────────────────────────────────────────────────────────
 
 function loadSessions() {
-  let raw;
-  try { raw = JSON.parse(fs.readFileSync(SESSIONS_FILE, "utf-8")); } catch (e) { return {}; }
+  const raw = readJsonWithFallback(SESSIONS_FILE, null);
   if (!raw || typeof raw !== "object") return {};
   const looksLegacy = Object.values(raw).some((v) => Array.isArray(v));
   if (looksLegacy) return { [canonicalForTelegram(CHAT_ID || "")]: raw };
@@ -161,7 +173,8 @@ function loadSessions() {
 }
 
 function saveSessions(sessions) {
-  try { fs.writeFileSync(SESSIONS_FILE, JSON.stringify(sessions, null, 2)); } catch (e) {}
+  try { atomicWriteFileSync(SESSIONS_FILE, JSON.stringify(sessions, null, 2), { backup: true }); }
+  catch (e) { console.error("saveSessions: write failed:", e.message); }
 }
 
 function recordSession(userId, projectName, sessionId, title) {
@@ -308,6 +321,7 @@ module.exports = {
   currentState,
   resetSessionUsage,
   resetSettings,
+  acquireRunLock,
   saveState,
   loadSessions,
   saveSessions,

package/core/web-sessions.js

@@ -0,0 +1,78 @@
+// Revocable dashboard sessions. The web login used to set the cookie to a
+// static sha256(password): identical for every session, valid until the password
+// changed, and impossible to revoke — a leaked cookie or /otp link granted
+// permanent access. Instead we mint a random 256-bit token per login, track it
+// server-side with an expiry, and validate the cookie against that store. Tokens
+// can be individually revoked, expire on their own, and are all dropped when the
+// password changes. Persisted via the atomic writer (core/fsutil) so a login
+// survives a bot restart/upgrade, and a torn write falls back to the last good
+// file rather than logging everyone out.
+
+const crypto = require("crypto");
+const path = require("path");
+const CONFIG_DIR = require("../config-dir");
+const { atomicWriteFileSync, readJsonWithFallback } = require("./fsutil");
+
+const SESSIONS_FILE = path.join(CONFIG_DIR, "web-sessions.json");
+const TTL_MS = 24 * 60 * 60 * 1000; // 24h — matches the cookie Max-Age
+
+function load() {
+  const raw = readJsonWithFallback(SESSIONS_FILE, {});
+  return raw && typeof raw === "object" ? raw : {};
+}
+
+function persist(sessions) {
+  try { atomicWriteFileSync(SESSIONS_FILE, JSON.stringify(sessions), { backup: true }); }
+  catch (e) { console.error("web-sessions: write failed:", e.message); }
+}
+
+// Drop expired (or malformed) entries in place. Returns true if anything went.
+function sweep(sessions, now = Date.now()) {
+  let changed = false;
+  for (const token of Object.keys(sessions)) {
+    const meta = sessions[token];
+    if (!meta || typeof meta.expires !== "number" || meta.expires <= now) {
+      delete sessions[token];
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+// Mint and persist a fresh session token, returning it for the Set-Cookie.
+function issue() {
+  const token = crypto.randomBytes(32).toString("hex");
+  const sessions = load();
+  sweep(sessions);
+  const now = Date.now();
+  sessions[token] = { created: now, expires: now + TTL_MS };
+  persist(sessions);
+  return token;
+}
+
+// Is this cookie token a live, unexpired session? hasOwnProperty guards against
+// an attacker presenting "__proto__"/"constructor" and hitting the prototype.
+function valid(token) {
+  if (!token || typeof token !== "string") return false;
+  const sessions = load();
+  if (!Object.prototype.hasOwnProperty.call(sessions, token)) return false;
+  const meta = sessions[token];
+  if (!meta || typeof meta.expires !== "number" || meta.expires <= Date.now()) return false;
+  return true;
+}
+
+function revoke(token) {
+  if (!token) return;
+  const sessions = load();
+  if (Object.prototype.hasOwnProperty.call(sessions, token)) {
+    delete sessions[token];
+    persist(sessions);
+  }
+}
+
+// Kill every session — used when the password changes.
+function revokeAll() {
+  persist({});
+}
+
+module.exports = { issue, valid, revoke, revokeAll, sweep, TTL_MS, SESSIONS_FILE };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "2.14.8",
+  "version": "2.15.0",
   "description": "Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat",
   "main": "bot.js",
   "bin": {
@@ -9,7 +9,7 @@
   "scripts": {
     "setup": "node setup.js",
     "start": "node bot.js",
-    "test": "OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node -e \"require('./vault'); console.log('OK')\" && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-runner-watchdog-static.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-usage-accounting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-engine.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-discoverer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-project-transcripts-smoke.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-abilities.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-extraction.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-couse.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-transfer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-tiers.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-merge-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-learning-e2e.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-pack-nesting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-journal-dedupe.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-read-signal.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tools.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tooling-mode.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-manifest.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-evolution.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-approval-async.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-unified-identity.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-queue-routing.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-persona-packs.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-speaker-persona.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-persona-pipeline.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-relationship-gate.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-relationship.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-enforcer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-identity-prune.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-kazee-message-id.js"
+    "test": "OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node -e \"require('./vault'); console.log('OK')\" && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-runner-watchdog-static.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-usage-accounting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-engine.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-discoverer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-project-transcripts-smoke.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-abilities.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-extraction.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-couse.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-transfer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-tiers.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-merge-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-learning-e2e.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-pack-nesting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-journal-dedupe.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-read-signal.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tools.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tooling-mode.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-manifest.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-evolution.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-approval-async.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-unified-identity.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-queue-routing.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-persona-packs.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-speaker-persona.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-persona-pipeline.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-relationship-gate.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-relationship.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-enforcer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-identity-prune.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-kazee-message-id.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-delivery-contract.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-run-lock.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-web-sessions.js"
   },
   "files": [
     "bot.js",
@@ -61,7 +61,10 @@
     "test-relationship.js",
     "test-enforcer.js",
     "test-identity-prune.js",
-    "test-kazee-message-id.js"
+    "test-kazee-message-id.js",
+    "test-delivery-contract.js",
+    "test-run-lock.js",
+    "test-web-sessions.js"
   ],
   "keywords": [
     "claude",

package/test-delivery-contract.js

@@ -0,0 +1,88 @@
+// P0-6: end-to-end delivery-contract regression test. Drives core/io.send()
+// through fake adapters that reproduce every real adapter return shape
+// (Telegram numeric id, Kazee ObjectId string, Kazee idless-success sentinel,
+// hard failure) and pins the normalized { ok, messageId, editable } contract
+// plus the two behaviours that contract exists to guarantee:
+//   1. an idless success is NEVER re-sent (the v2.14.8 Kazee double-send), and
+//   2. a real failure IS re-sent exactly once.
+// No network, no bot — just the async chat scope + the io layer.
+
+const assert = require("assert");
+process.env.OPEN_CLAUDIA_TEST = "1";
+
+const io = require("./core/io");
+const { runInChat } = require("./core/context");
+
+// A fake adapter whose send() returns a programmed value and records each call.
+function makeAdapter(type, returns) {
+  const calls = [];
+  const adapter = {
+    type, id: type,
+    send: async (channelId, text, opts) => {
+      calls.push({ channelId: String(channelId), text, opts: opts || {} });
+      return typeof returns === "function" ? returns(calls.length - 1) : returns;
+    },
+  };
+  return { adapter, calls };
+}
+
+const inChat = (adapter, fn) => runInChat({ adapter, channelId: "chan-1", transport: adapter.type }, fn);
+
+(async () => {
+  // 1. Telegram numeric id → editable, id normalized to a string.
+  {
+    const { adapter, calls } = makeAdapter("telegram", 4242);
+    const r = await inChat(adapter, () => io.send("hi"));
+    assert.deepStrictEqual(r, { ok: true, messageId: "4242", editable: true }, "telegram numeric id");
+    assert.strictEqual(calls.length, 1, "telegram sent once");
+  }
+
+  // 2. Kazee ObjectId string → editable.
+  {
+    const { adapter } = makeAdapter("kazee", "67aef6a338dd0d6db55c684c");
+    const r = await inChat(adapter, () => io.send("hi"));
+    assert.deepStrictEqual(r, { ok: true, messageId: "67aef6a338dd0d6db55c684c", editable: true }, "kazee objectid");
+  }
+
+  // 3. Kazee idless success (bare true) → delivered but NOT editable.
+  {
+    const { adapter } = makeAdapter("kazee", true);
+    const r = await inChat(adapter, () => io.send("hi"));
+    assert.deepStrictEqual(r, { ok: true, messageId: null, editable: false }, "kazee idless success");
+  }
+
+  // 4. Hard failures collapse to a single not-ok shape.
+  for (const bad of [null, undefined, false]) {
+    const { adapter } = makeAdapter("telegram", bad);
+    const r = await inChat(adapter, () => io.send("hi"));
+    assert.deepStrictEqual(r, { ok: false, messageId: null, editable: false }, `failure ${String(bad)}`);
+  }
+
+  // 5. THE guard: mirror runner.js final delivery —
+  //      const sent = await send(x); if (!sent.ok) await send(x);
+  const deliver = async () => {
+    const sent = await io.send("reply");
+    if (!sent.ok) await io.send("reply");
+  };
+
+  {
+    // idless success must resolve to exactly ONE post (no double-send).
+    const { adapter, calls } = makeAdapter("kazee", true);
+    await inChat(adapter, deliver);
+    assert.strictEqual(calls.length, 1, "idless success must NOT double-send (v2.14.8 regression)");
+  }
+  {
+    // a real failure must trigger exactly one resend (two posts total).
+    const { adapter, calls } = makeAdapter("telegram", null);
+    await inChat(adapter, deliver);
+    assert.strictEqual(calls.length, 2, "hard failure must resend exactly once");
+  }
+
+  // 6. loopback approval-prompt path uses the exported normalizer on a raw
+  //    adapter return and must get the identical contract.
+  assert.deepStrictEqual(io.normalizeSendResult(true), { ok: true, messageId: null, editable: false });
+  assert.deepStrictEqual(io.normalizeSendResult(null), { ok: false, messageId: null, editable: false });
+  assert.deepStrictEqual(io.normalizeSendResult(99), { ok: true, messageId: "99", editable: true });
+
+  console.log("delivery-contract OK");
+})().catch((e) => { console.error(e); process.exit(1); });

package/test-run-lock.js

@@ -0,0 +1,63 @@
+// P0-3: single-flight run-lock regression test. Under unified identity the
+// owner's Telegram and Kazee turns resolve to ONE canonical user and therefore
+// share ONE in-memory state object. If two of those turns could both pass the
+// "is a run in progress?" check they would race the shared state and the JSON
+// files behind it. acquireRunLock() closes that window by arming the lock
+// SYNCHRONOUSLY (no await between the check and the arm), so the second turn is
+// always refused and queued. This test pins that contract on the raw helper.
+
+const assert = require("assert");
+process.env.OPEN_CLAUDIA_TEST = "1";
+
+const { acquireRunLock } = require("./core/state");
+
+// A run-lock must be synchronous — its whole point is that no await can
+// interleave between the check and the arm. If this ever returned a Promise the
+// guarantee would silently evaporate.
+{
+  const r = acquireRunLock({ runningProcess: null, preparingRun: false });
+  assert.strictEqual(typeof r, "boolean", "acquireRunLock must be synchronous (return a boolean, not a Promise)");
+}
+
+// Idle → acquires and arms preparingRun.
+{
+  const s = { runningProcess: null, preparingRun: false };
+  assert.strictEqual(acquireRunLock(s), true, "idle state acquires");
+  assert.strictEqual(s.preparingRun, true, "acquiring arms preparingRun");
+}
+
+// Already preparing (armed but not yet spawned) → refused, lock left intact.
+{
+  const s = { runningProcess: null, preparingRun: true };
+  assert.strictEqual(acquireRunLock(s), false, "preparing state is refused");
+  assert.strictEqual(s.preparingRun, true, "refusal leaves the existing lock armed");
+}
+
+// A process is actively running → refused.
+{
+  const s = { runningProcess: { pid: 123 }, preparingRun: false };
+  assert.strictEqual(acquireRunLock(s), false, "running process is refused");
+}
+
+// THE guarantee: two turns sharing ONE state object (owner's Telegram + Kazee
+// under unified identity). Exactly one may acquire; the other must be refused
+// until the first fully releases.
+{
+  const shared = { runningProcess: null, preparingRun: false };
+
+  const first = acquireRunLock(shared);   // Telegram turn arrives
+  const second = acquireRunLock(shared);  // Kazee turn arrives before the first releases
+  assert.strictEqual(first, true, "first turn wins the lock");
+  assert.strictEqual(second, false, "second concurrent turn is refused (no double-acquire)");
+
+  // First turn spawns its process, then finishes and clears both flags.
+  shared.preparingRun = false;
+  shared.runningProcess = { pid: 1 };     // spawned
+  assert.strictEqual(acquireRunLock(shared), false, "still refused while the process runs");
+  shared.runningProcess = null;           // turn complete
+
+  // Now the queued second turn (drained from messageQueue) can proceed.
+  assert.strictEqual(acquireRunLock(shared), true, "lock is re-acquirable once the turn fully releases");
+}
+
+console.log("run-lock OK");

package/test-web-sessions.js

@@ -0,0 +1,74 @@
+// P0-4: revocable dashboard sessions. The old web login set the cookie to a
+// static sha256(password) — identical for every session, unexpiring, and
+// impossible to revoke. This pins the replacement contract: random per-login
+// tokens, validated server-side, individually revocable, killable en masse on
+// password change, expiring on their own, and surviving a restart (persisted).
+// Prototype-pollution keys must never validate.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const assert = require("assert");
+process.env.OPEN_CLAUDIA_TEST = "1";
+
+// Hermetic config dir: point HOME at a temp dir BEFORE requiring the module, so
+// web-sessions.json lands under a throwaway ~/.open-claudia.
+const HOME = fs.mkdtempSync(path.join(os.tmpdir(), "oc-websess-"));
+process.env.HOME = HOME;
+
+const sessions = require("./core/web-sessions");
+
+function cleanup() { try { fs.rmSync(HOME, { recursive: true, force: true }); } catch (_) {} }
+
+try {
+  // issue() → a fresh 256-bit hex token that immediately validates.
+  const a = sessions.issue();
+  assert.strictEqual(typeof a, "string");
+  assert.match(a, /^[0-9a-f]{64}$/, "token is 32 random bytes hex");
+  assert.strictEqual(sessions.valid(a), true, "freshly issued token is valid");
+
+  // Distinct tokens per login; both live independently.
+  const b = sessions.issue();
+  assert.notStrictEqual(a, b, "each login mints a distinct token");
+  assert.ok(sessions.valid(a) && sessions.valid(b), "both sessions are live");
+
+  // Junk / empty / non-string never validates.
+  for (const bad of ["", "nope", null, undefined, 123, {}]) {
+    assert.strictEqual(sessions.valid(bad), false, `garbage token rejected: ${String(bad)}`);
+  }
+
+  // Prototype-pollution keys must not slip through the object lookup.
+  for (const evil of ["__proto__", "constructor", "prototype", "hasOwnProperty", "toString"]) {
+    assert.strictEqual(sessions.valid(evil), false, `prototype key rejected: ${evil}`);
+  }
+
+  // Persistence: the token is written to disk so it survives a bot restart.
+  const onDisk = JSON.parse(fs.readFileSync(sessions.SESSIONS_FILE, "utf-8"));
+  assert.ok(Object.prototype.hasOwnProperty.call(onDisk, a), "session persisted to disk");
+  assert.strictEqual(typeof onDisk[a].expires, "number", "persisted entry carries an expiry");
+
+  // Individual revoke: only the named token dies.
+  sessions.revoke(a);
+  assert.strictEqual(sessions.valid(a), false, "revoked token no longer validates");
+  assert.strictEqual(sessions.valid(b), true, "revoke is targeted, others survive");
+
+  // revokeAll: every session dies (the password-change semantics).
+  const c = sessions.issue();
+  assert.ok(sessions.valid(b) && sessions.valid(c), "sessions live before revokeAll");
+  sessions.revokeAll();
+  assert.ok(!sessions.valid(b) && !sessions.valid(c), "revokeAll kills every session");
+
+  // Expiry: an entry past its expires is swept and never validates.
+  const expired = { deadtok: { created: 1, expires: 1 } };
+  assert.strictEqual(sessions.sweep(expired), true, "sweep reports it dropped the expired entry");
+  assert.strictEqual(Object.keys(expired).length, 0, "expired entry removed");
+  fs.writeFileSync(sessions.SESSIONS_FILE, JSON.stringify({ oldtok: { created: 1, expires: Date.now() - 1000 } }));
+  assert.strictEqual(sessions.valid("oldtok"), false, "an expired persisted token is rejected");
+
+  cleanup();
+  console.log("web-sessions OK");
+} catch (e) {
+  cleanup();
+  console.error(e);
+  process.exit(1);
+}

package/web.js

@@ -10,6 +10,7 @@ const {
   usageAlertPolicy,
   usageTrend,
 } = require("./core/usage-log");
+const webSessions = require("./core/web-sessions");
 
 const ENV_FILE = path.join(CONFIG_DIR, ".env");
 const AUTH_FILE = path.join(CONFIG_DIR, "auth.json");
@@ -136,12 +137,7 @@ function checkAuth(req) {
   const cookie = (req.headers.cookie || "").split(";").find((c) => c.trim().startsWith("oc_session="));
   if (!cookie) return false;
   const token = cookie.split("=")[1]?.trim();
-  const expected = crypto.createHash("sha256").update(getPassword()).digest("hex");
-  return token === expected;
-}
-
-function authToken() {
-  return crypto.createHash("sha256").update(getPassword()).digest("hex");
+  return webSessions.valid(token);
 }
 
 // ── Config helpers ─────────────────────────────────────────────────
@@ -161,6 +157,26 @@ function saveEnv(env) {
   fs.writeFileSync(ENV_FILE, content);
 }
 
+// GET /api/config used to return the raw .env — every bot token, model API key
+// and control-plane secret in plaintext to anyone with a dashboard session. The
+// config UI only ever edits the non-secret SAFE_KEYS, so mask any secret-looking
+// value before it leaves the server (keeping a 4-char tail so the owner can still
+// tell a value is set / which one it is). Masked values can never round-trip back
+// in: the POST handler rejects every key outside SAFE_KEYS.
+const SECRET_KEY_RE = /(TOKEN|SECRET|PASSWORD|API_?KEY|_KEY|CREDENTIAL|WEBHOOK|SESSION|PRIVATE)/i;
+function maskEnv(env) {
+  const out = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (v && SECRET_KEY_RE.test(k)) {
+      const s = String(v);
+      out[k] = s.length <= 8 ? "••••••••" : `••••${s.slice(-4)}`;
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
 function loadAuth() {
   try { return JSON.parse(fs.readFileSync(AUTH_FILE, "utf-8")); } catch (e) { return { authorized: [], pending: [] }; }
 }
@@ -255,7 +271,7 @@ async function handleAPI(req, res, body) {
     if (password === getPassword()) {
       res.writeHead(200, {
         "Content-Type": "application/json",
-        "Set-Cookie": `oc_session=${authToken()}; Path=/; HttpOnly; SameSite=Strict; Max-Age=86400`,
+        "Set-Cookie": `oc_session=${webSessions.issue()}; Path=/; HttpOnly; SameSite=Strict; Max-Age=86400`,
       });
       return res.end(JSON.stringify({ ok: true, mustChangePassword: !isPasswordChanged() }));
     }
@@ -360,7 +376,7 @@ async function handleAPI(req, res, body) {
   if (url === "/api/config") {
     const env = loadEnv();
     res.writeHead(200, { "Content-Type": "application/json" });
-    return res.end(JSON.stringify(env));
+    return res.end(JSON.stringify(maskEnv(env)));
   }
 
   // Update config (whitelist safe keys only)
@@ -502,9 +518,12 @@ async function handleAPI(req, res, body) {
       return res.end(JSON.stringify({ error: complexityError }));
     }
     setPassword(newPassword);
+    // Changing the password invalidates every outstanding session, then we
+    // re-issue one so the caller who just changed it stays logged in.
+    webSessions.revokeAll();
     res.writeHead(200, {
       "Content-Type": "application/json",
-      "Set-Cookie": `oc_session=${authToken()}; Path=/; HttpOnly; SameSite=Strict; Max-Age=86400`,
+      "Set-Cookie": `oc_session=${webSessions.issue()}; Path=/; HttpOnly; SameSite=Strict; Max-Age=86400`,
     });
     return res.end(JSON.stringify({ ok: true }));
   }
@@ -1137,7 +1156,7 @@ function startWebServer() {
       if (consume(token)) {
         res.writeHead(302, {
           "Location": "/",
-          "Set-Cookie": `oc_session=${authToken()}; Path=/; HttpOnly; SameSite=Strict; Max-Age=86400`,
+          "Set-Cookie": `oc_session=${webSessions.issue()}; Path=/; HttpOnly; SameSite=Strict; Max-Age=86400`,
         });
         return res.end();
       }