@adapt-toolkit/a2adapt 0.5.1 → 0.7.0

package/dist/cli.js

@@ -4,15 +4,80 @@ import { createRequire } from 'node:module'; const require = createRequire(impor
 // src/cli.ts
 import { spawn, spawnSync } from "node:child_process";
 import { connect } from "node:net";
-import { homedir, userInfo } from "node:os";
-import { resolve, join, dirname } from "node:path";
+import { homedir as homedir2, userInfo } from "node:os";
+import { resolve as resolve2, join as join2, dirname as dirname2 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { createInterface } from "node:readline/promises";
+import * as fs2 from "node:fs";
+
+// src/config.ts
 import * as fs from "node:fs";
-var STATE_DIR = resolve(process.env.A2ADAPT_STATE_DIR ?? resolve(homedir(), ".a2adapt"));
-var PORT = parseInt(process.env.A2ADAPT_PORT ?? "3030", 10);
-var BROKER_URL = process.env.A2ADAPT_BROKER_URL ?? "ws://a2adapt.adaptframework.solutions/broker";
-var PID_PATH = join(STATE_DIR, "daemon.pid");
-var LOG_PATH = join(STATE_DIR, "daemon.log");
+import { homedir } from "node:os";
+import { resolve, join, dirname } from "node:path";
+var DEFAULT_CONFIG = {
+  brokerUrl: "ws://a2adapt.adaptframework.solutions/broker",
+  port: 3030,
+  stateDir: resolve(homedir(), ".a2adapt"),
+  gcIntervalMs: 36e5
+};
+function configPath() {
+  return process.env.A2ADAPT_CONFIG ?? join(homedir(), ".a2adapt", "config.json");
+}
+function readFileConfig() {
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath(), "utf8");
+  } catch {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  const out2 = {};
+  if (typeof parsed.brokerUrl === "string") out2.brokerUrl = parsed.brokerUrl;
+  if (typeof parsed.port === "number" && Number.isFinite(parsed.port)) out2.port = parsed.port;
+  if (typeof parsed.stateDir === "string") out2.stateDir = resolve(parsed.stateDir);
+  if (typeof parsed.gcIntervalMs === "number" && Number.isFinite(parsed.gcIntervalMs)) {
+    out2.gcIntervalMs = parsed.gcIntervalMs;
+  }
+  return out2;
+}
+function envInt(name) {
+  const v = process.env[name];
+  if (v === void 0) return void 0;
+  const n = parseInt(v, 10);
+  return Number.isNaN(n) ? void 0 : n;
+}
+function loadConfig() {
+  const file = readFileConfig();
+  return {
+    brokerUrl: process.env.A2ADAPT_BROKER_URL ?? file.brokerUrl ?? DEFAULT_CONFIG.brokerUrl,
+    port: envInt("A2ADAPT_PORT") ?? file.port ?? DEFAULT_CONFIG.port,
+    stateDir: resolve(process.env.A2ADAPT_STATE_DIR ?? file.stateDir ?? DEFAULT_CONFIG.stateDir),
+    gcIntervalMs: envInt("A2ADAPT_GC_INTERVAL_MS") ?? file.gcIntervalMs ?? DEFAULT_CONFIG.gcIntervalMs
+  };
+}
+function writeConfig(cfg) {
+  const path = configPath();
+  fs.mkdirSync(dirname(path), { recursive: true });
+  fs.writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n", { mode: 384 });
+  try {
+    fs.chmodSync(path, 384);
+  } catch {
+  }
+  return path;
+}
+
+// src/cli.ts
+var CONFIG = loadConfig();
+var STATE_DIR = CONFIG.stateDir;
+var PORT = CONFIG.port;
+var BROKER_URL = CONFIG.brokerUrl;
+var PID_PATH = join2(STATE_DIR, "daemon.pid");
+var LOG_PATH = join2(STATE_DIR, "daemon.log");
 var SELF = fileURLToPath(import.meta.url);
 var out = (...p) => process.stdout.write(`${p.join(" ")}
 `);
@@ -21,7 +86,7 @@ var err = (...p) => process.stderr.write(`${p.join(" ")}
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function readPid() {
   try {
-    const n = parseInt(fs.readFileSync(PID_PATH, "utf8").trim(), 10);
+    const n = parseInt(fs2.readFileSync(PID_PATH, "utf8").trim(), 10);
     return Number.isFinite(n) ? n : null;
   } catch {
     return null;
@@ -40,7 +105,7 @@ function runningPid() {
   if (pid && isAlive(pid)) return pid;
   if (pid) {
     try {
-      fs.rmSync(PID_PATH, { force: true });
+      fs2.rmSync(PID_PATH, { force: true });
     } catch {
     }
   }
@@ -73,8 +138,8 @@ async function cmdStart() {
     out(`a2adapt-mcp is already running (pid ${existing}, port ${PORT}).`);
     return;
   }
-  fs.mkdirSync(STATE_DIR, { recursive: true });
-  const logFd = fs.openSync(LOG_PATH, "a");
+  fs2.mkdirSync(STATE_DIR, { recursive: true });
+  const logFd = fs2.openSync(LOG_PATH, "a");
   const child = spawn(process.execPath, [SELF, "serve"], {
     detached: true,
     stdio: ["ignore", logFd, logFd],
@@ -91,7 +156,7 @@ async function cmdStart() {
     err("failed to spawn the daemon.");
     process.exit(1);
   }
-  fs.writeFileSync(PID_PATH, String(child.pid));
+  fs2.writeFileSync(PID_PATH, String(child.pid));
   out(`starting a2adapt-mcp (pid ${child.pid})\u2026`);
   const ready = await waitForPort(PORT);
   if (ready) {
@@ -125,7 +190,7 @@ async function cmdStop() {
     }
   }
   try {
-    fs.rmSync(PID_PATH, { force: true });
+    fs2.rmSync(PID_PATH, { force: true });
   } catch {
   }
   out("stopped.");
@@ -150,21 +215,80 @@ async function cmdStatus() {
   out(`  state:  ${STATE_DIR}`);
   out(`  logs:   ${LOG_PATH}`);
 }
+async function cmdSetup() {
+  const current = loadConfig();
+  const path = configPath();
+  out(`a2adapt-mcp setup \u2014 ${path}`);
+  out("Enter a value, or press Enter to keep the current [bracketed] one.");
+  out("");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  let next;
+  try {
+    const ask = async (label, cur) => {
+      const ans = (await rl.question(`  ${label} [${cur}]: `)).trim();
+      return ans === "" ? cur : ans;
+    };
+    const brokerUrl = await ask("broker URL", current.brokerUrl);
+    const portStr = await ask("HTTP port", String(current.port));
+    const stateDir = await ask("state dir", current.stateDir);
+    const gcStr = await ask("GC interval (ms)", String(current.gcIntervalMs));
+    const port = parseInt(portStr, 10);
+    if (!Number.isFinite(port) || port <= 0) {
+      err(`invalid port: ${portStr}`);
+      process.exit(1);
+    }
+    const gcIntervalMs = parseInt(gcStr, 10);
+    if (!Number.isFinite(gcIntervalMs) || gcIntervalMs <= 0) {
+      err(`invalid GC interval: ${gcStr}`);
+      process.exit(1);
+    }
+    next = { brokerUrl, port, stateDir: resolve2(stateDir), gcIntervalMs };
+  } finally {
+    rl.close();
+  }
+  writeConfig(next);
+  out("");
+  out(`wrote ${path} (mode 0600):`);
+  out(JSON.stringify(next, null, 2));
+  const shadowed = ["A2ADAPT_BROKER_URL", "A2ADAPT_PORT", "A2ADAPT_STATE_DIR", "A2ADAPT_GC_INTERVAL_MS"].filter((k) => process.env[k] !== void 0);
+  if (shadowed.length) {
+    out("");
+    out(`note: these env vars are set and OVERRIDE the file at runtime: ${shadowed.join(", ")}`);
+  }
+  const pid = runningPid();
+  if (!pid) return;
+  const rl2 = createInterface({ input: process.stdin, output: process.stdout });
+  let restart = false;
+  try {
+    const ans = (await rl2.question(`
+daemon is running (pid ${pid}); restart now to apply? [y/N]: `)).trim().toLowerCase();
+    restart = ans === "y" || ans === "yes";
+  } finally {
+    rl2.close();
+  }
+  if (!restart) {
+    out("not restarting \u2014 changes apply on the next `a2adapt-mcp restart`.");
+    return;
+  }
+  await cmdStop();
+  const r = spawnSync(process.execPath, [SELF, "start"], { stdio: "inherit" });
+  if (r.status !== 0) process.exit(r.status ?? 1);
+}
 function cmdWatch(which) {
   const offsets = /* @__PURE__ */ new Map();
   const scan = (initial) => {
     let names;
     try {
-      names = fs.readdirSync(STATE_DIR, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+      names = fs2.readdirSync(STATE_DIR, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
     } catch {
       return;
     }
     for (const name of names) {
       if (which && name !== which) continue;
-      const logPath = join(STATE_DIR, name, "notifications.log");
+      const logPath = join2(STATE_DIR, name, "notifications.log");
       let size;
       try {
-        size = fs.statSync(logPath).size;
+        size = fs2.statSync(logPath).size;
       } catch {
         continue;
       }
@@ -180,10 +304,10 @@ function cmdWatch(which) {
       }
       let chunk;
       try {
-        const fd = fs.openSync(logPath, "r");
+        const fd = fs2.openSync(logPath, "r");
         const buf = Buffer.alloc(size - seen);
-        fs.readSync(fd, buf, 0, buf.length, seen);
-        fs.closeSync(fd);
+        fs2.readSync(fd, buf, 0, buf.length, seen);
+        fs2.closeSync(fd);
         chunk = buf.toString("utf8");
       } catch {
         continue;
@@ -218,10 +342,10 @@ function cmdWatch(which) {
 var SYSTEMD_UNIT = "a2adapt.service";
 var LAUNCHD_LABEL = "solutions.adaptframework.a2adapt";
 function systemdUnitPath() {
-  return join(homedir(), ".config", "systemd", "user", SYSTEMD_UNIT);
+  return join2(homedir2(), ".config", "systemd", "user", SYSTEMD_UNIT);
 }
 function launchdPlistPath() {
-  return join(homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+  return join2(homedir2(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
 }
 function run(cmd, args) {
   const r = spawnSync(cmd, args, { stdio: "inherit" });
@@ -229,7 +353,7 @@ function run(cmd, args) {
 }
 function installSystemd() {
   const unitPath = systemdUnitPath();
-  fs.mkdirSync(dirname(unitPath), { recursive: true });
+  fs2.mkdirSync(dirname2(unitPath), { recursive: true });
   const unit = `[Unit]
 Description=a2adapt MCP daemon (secure agent-to-agent messaging over ADAPT)
 After=network-online.target
@@ -248,7 +372,7 @@ RestartSec=2
 [Install]
 WantedBy=default.target
 `;
-  fs.writeFileSync(unitPath, unit);
+  fs2.writeFileSync(unitPath, unit);
   out(`wrote ${unitPath}`);
   run("systemctl", ["--user", "daemon-reload"]);
   if (!run("systemctl", ["--user", "enable", "--now", SYSTEMD_UNIT])) {
@@ -269,7 +393,7 @@ function uninstallSystemd() {
   run("systemctl", ["--user", "disable", "--now", SYSTEMD_UNIT]);
   const unitPath = systemdUnitPath();
   try {
-    fs.rmSync(unitPath, { force: true });
+    fs2.rmSync(unitPath, { force: true });
     out(`removed ${unitPath}`);
   } catch (e) {
     err(`failed to remove ${unitPath}: ${String(e)}`);
@@ -279,7 +403,7 @@ function uninstallSystemd() {
 }
 function installLaunchd() {
   const plistPath = launchdPlistPath();
-  fs.mkdirSync(dirname(plistPath), { recursive: true });
+  fs2.mkdirSync(dirname2(plistPath), { recursive: true });
   const plist = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -305,7 +429,7 @@ function installLaunchd() {
 </dict>
 </plist>
 `;
-  fs.writeFileSync(plistPath, plist);
+  fs2.writeFileSync(plistPath, plist);
   out(`wrote ${plistPath}`);
   run("launchctl", ["unload", plistPath]);
   if (!run("launchctl", ["load", "-w", plistPath])) {
@@ -320,7 +444,7 @@ function uninstallLaunchd() {
   const plistPath = launchdPlistPath();
   run("launchctl", ["unload", plistPath]);
   try {
-    fs.rmSync(plistPath, { force: true });
+    fs2.rmSync(plistPath, { force: true });
     out(`removed ${plistPath}`);
   } catch (e) {
     err(`failed to remove ${plistPath}: ${String(e)}`);
@@ -348,14 +472,17 @@ function usage() {
   out("  stop      stop the running daemon");
   out("  restart   stop then start");
   out("  status    show whether the daemon is running");
+  out("  setup     interactively edit the config file (broker / port / state dir / gc)");
   out("  serve     run in the foreground (used by start; handy for debugging)");
   out("  watch [identity]  stream one line per new inbound message (wake source for a Monitor)");
   out("");
   out("  install-service    install + start a boot-persistent service (systemd/launchd)");
   out("  uninstall-service  stop + remove that service");
   out("");
-  out("Config (env): A2ADAPT_BROKER_URL, A2ADAPT_PORT (3030), A2ADAPT_STATE_DIR (~/.a2adapt)");
-  out("(install-service bakes the current config values into the service definition.)");
+  out("Config precedence (per field): env var > config.json > default.");
+  out("  config.json: A2ADAPT_CONFIG, else ~/.a2adapt/config.json \u2014 edit with `setup`.");
+  out("  env: A2ADAPT_BROKER_URL, A2ADAPT_PORT (3030), A2ADAPT_STATE_DIR (~/.a2adapt), A2ADAPT_GC_INTERVAL_MS (3600000)");
+  out("(install-service bakes the resolved config values into the service definition.)");
 }
 async function main() {
   const cmd = process.argv[2] ?? "help";
@@ -363,12 +490,12 @@ async function main() {
     case "serve":
     case "run":
       if (!process.env.A2ADAPT_TRANSPORT) process.env.A2ADAPT_TRANSPORT = "http";
-      fs.mkdirSync(STATE_DIR, { recursive: true });
-      fs.writeFileSync(PID_PATH, String(process.pid));
+      fs2.mkdirSync(STATE_DIR, { recursive: true });
+      fs2.writeFileSync(PID_PATH, String(process.pid));
       {
         const cleanup = () => {
           try {
-            fs.rmSync(PID_PATH, { force: true });
+            fs2.rmSync(PID_PATH, { force: true });
           } catch {
           }
         };
@@ -380,7 +507,7 @@ async function main() {
           });
         }
       }
-      await import(pathToFileURL(join(dirname(SELF), "index.js")).href);
+      await import(pathToFileURL(join2(dirname2(SELF), "index.js")).href);
       break;
     case "start":
       await cmdStart();
@@ -395,6 +522,9 @@ async function main() {
     case "status":
       await cmdStatus();
       break;
+    case "setup":
+      await cmdSetup();
+      break;
     case "watch":
       cmdWatch(process.argv[3]);
       break;

package/dist/hooks/runner.js

@@ -4,10 +4,11 @@ import { createRequire } from 'node:module'; const require = createRequire(impor
 // src/hooks/runner.ts
 import * as fs from "node:fs";
 import { homedir } from "node:os";
-import { resolve, join } from "node:path";
+import { resolve, join, dirname } from "node:path";
 var STATE_DIR = resolve(
   process.env.A2ADAPT_STATE_DIR ?? resolve(homedir(), ".a2adapt")
 );
+var IDENTITY_FILE = ".a2adapt-identity";
 function readStdin() {
   try {
     return fs.readFileSync(0, "utf8");
@@ -72,23 +73,61 @@ ${lines.join("\n")}
 
 To read: choose_identity({ name }) then get_messages() (returns the bodies and marks them read). To wait for live replies, arm a Monitor on the per-identity wake source \`a2adapt-mcp watch <name>\` (each new-mail line wakes you).`;
 }
+function findPinnedIdentity(start) {
+  let dir = resolve(start);
+  for (; ; ) {
+    let raw;
+    try {
+      raw = fs.readFileSync(join(dir, IDENTITY_FILE), "utf8");
+    } catch {
+      const parent = dirname(dir);
+      if (parent === dir) return null;
+      dir = parent;
+      continue;
+    }
+    try {
+      const name = String(JSON.parse(raw).identity ?? "").trim();
+      return name || null;
+    } catch {
+      return null;
+    }
+  }
+}
+function identityExists(name) {
+  try {
+    return fs.statSync(join(STATE_DIR, name)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function renderIdentityDirective(name, exists) {
+  const bind = exists ? `call \`choose_identity({ name: "${name}" })\` to bind it to this session` : `it does not exist yet \u2014 call \`create_identity({ name: "${name}" })\` to create and bind it`;
+  return `a2adapt \u2014 this workspace is pinned to identity "${name}" (via ${IDENTITY_FILE}). Before other a2adapt work, ${bind}. Then arm a Monitor on the wake source \`a2adapt-mcp watch ${name}\` so new mail wakes you. Do this once, up front; if a different identity is already bound, prefer this pinned one.`;
+}
 function sessionStart() {
   const raw = readStdin();
   let source = "";
+  let cwd = process.cwd();
   if (raw) {
     try {
-      source = JSON.parse(raw).source ?? "";
+      const payload = JSON.parse(raw);
+      source = payload.source ?? "";
+      if (typeof payload.cwd === "string" && payload.cwd) cwd = payload.cwd;
     } catch {
     }
   }
   if (source === "compact") return noop();
+  const pinned = findPinnedIdentity(cwd);
   const unread = collectUnread();
-  if (unread.length === 0) return noop();
+  const blocks = [];
+  if (pinned) blocks.push(renderIdentityDirective(pinned, identityExists(pinned)));
+  if (unread.length > 0) blocks.push(renderContext(unread));
+  if (blocks.length === 0) return noop();
   emit({
     continue: true,
     hookSpecificOutput: {
       hookEventName: "SessionStart",
-      additionalContext: renderContext(unread)
+      additionalContext: blocks.join("\n\n")
     }
   });
 }

package/dist/index.js

@@ -2981,7 +2981,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve2.call(this, root, ref);
+      let _sch = resolve3.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a = root.localRefs) === null || _a === void 0 ? void 0 : _a[ref];
         const { schemaId } = this.opts;
@@ -3008,7 +3008,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve2(root, ref) {
+    function resolve3(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3639,7 +3639,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve2(baseURI, relativeURI, options) {
+    function resolve3(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
       schemelessOptions.skipEscape = true;
@@ -3897,7 +3897,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve2,
+      resolve: resolve3,
       resolveComponent,
       equal,
       serialize,
@@ -6873,12 +6873,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs2, exportName) {
+    function addFormats(ajv, list, fs3, exportName) {
       var _a;
       var _b;
       (_a = (_b = ajv.opts.code).formats) !== null && _a !== void 0 ? _a : _b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`;
       for (const f of list)
-        ajv.addFormat(f, fs2[f]);
+        ajv.addFormat(f, fs3[f]);
     }
     module.exports = exports = formatsPlugin;
     Object.defineProperty(exports, "__esModule", { value: true });
@@ -18980,7 +18980,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+        await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error2) {
@@ -18997,7 +18997,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const earlyReject = (error2) => {
         reject(error2);
       };
@@ -19075,7 +19075,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve2(parseResult.data);
+            resolve3(parseResult.data);
           }
         } catch (error2) {
           reject(error2);
@@ -19336,12 +19336,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve2, interval);
+      const timeoutId = setTimeout(resolve3, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -20441,7 +20441,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+      await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -21090,12 +21090,12 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve2) => {
+    return new Promise((resolve3) => {
       const json = serializeMessage(message);
       if (this._stdout.write(json)) {
-        resolve2();
+        resolve3();
       } else {
-        this._stdout.once("drain", resolve2);
+        this._stdout.once("drain", resolve3);
       }
     });
   }
@@ -21594,7 +21594,7 @@ var responseViaResponseObject = async (res, outgoing, options = {}) => {
         });
         if (!chunk) {
           if (i === 1) {
-            await new Promise((resolve2) => setTimeout(resolve2));
+            await new Promise((resolve3) => setTimeout(resolve3));
             maxReadCount = 3;
             continue;
           }
@@ -22094,9 +22094,9 @@ data:
       const initRequest = messages.find((m) => isInitializeRequest(m));
       const clientProtocolVersion = initRequest ? initRequest.params.protocolVersion : req.headers.get("mcp-protocol-version") ?? DEFAULT_NEGOTIATED_PROTOCOL_VERSION;
       if (this._enableJsonResponse) {
-        return new Promise((resolve2) => {
+        return new Promise((resolve3) => {
           this._streamMapping.set(streamId, {
-            resolveJson: resolve2,
+            resolveJson: resolve3,
             cleanup: () => {
               this._streamMapping.delete(streamId);
             }
@@ -22427,23 +22427,75 @@ var StreamableHTTPServerTransport = class {
 };
 
 // src/index.ts
-import { homedir } from "node:os";
-import { resolve, join, dirname } from "node:path";
+import { resolve as resolve2, join as join2, dirname as dirname2 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomBytes, randomUUID } from "node:crypto";
 import { createServer as createHttpServer } from "node:http";
-import * as fs from "node:fs";
+import * as fs2 from "node:fs";
 import { brotliCompressSync, brotliDecompressSync, constants as zlibConstants } from "node:zlib";
 import { adapt_wrapper } from "@adapt-toolkit/sdk/executables";
 import { PacketWrapperConfigurator } from "@adapt-toolkit/sdk/wrappers";
 import { object_to_adapt_value } from "@adapt-toolkit/sdk/wrapper";
-var VERSION = true ? "0.5.1" : "0.0.0-dev";
-var STATE_DIR = resolve(
-  process.env.A2ADAPT_STATE_DIR ?? resolve(homedir(), ".a2adapt")
-);
-var BROKER_URL = process.env.A2ADAPT_BROKER_URL ?? "ws://a2adapt.adaptframework.solutions/broker";
+
+// src/config.ts
+import * as fs from "node:fs";
+import { homedir } from "node:os";
+import { resolve, join, dirname } from "node:path";
+var DEFAULT_CONFIG = {
+  brokerUrl: "ws://a2adapt.adaptframework.solutions/broker",
+  port: 3030,
+  stateDir: resolve(homedir(), ".a2adapt"),
+  gcIntervalMs: 36e5
+};
+function configPath() {
+  return process.env.A2ADAPT_CONFIG ?? join(homedir(), ".a2adapt", "config.json");
+}
+function readFileConfig() {
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath(), "utf8");
+  } catch {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  const out = {};
+  if (typeof parsed.brokerUrl === "string") out.brokerUrl = parsed.brokerUrl;
+  if (typeof parsed.port === "number" && Number.isFinite(parsed.port)) out.port = parsed.port;
+  if (typeof parsed.stateDir === "string") out.stateDir = resolve(parsed.stateDir);
+  if (typeof parsed.gcIntervalMs === "number" && Number.isFinite(parsed.gcIntervalMs)) {
+    out.gcIntervalMs = parsed.gcIntervalMs;
+  }
+  return out;
+}
+function envInt(name) {
+  const v = process.env[name];
+  if (v === void 0) return void 0;
+  const n = parseInt(v, 10);
+  return Number.isNaN(n) ? void 0 : n;
+}
+function loadConfig() {
+  const file = readFileConfig();
+  return {
+    brokerUrl: process.env.A2ADAPT_BROKER_URL ?? file.brokerUrl ?? DEFAULT_CONFIG.brokerUrl,
+    port: envInt("A2ADAPT_PORT") ?? file.port ?? DEFAULT_CONFIG.port,
+    stateDir: resolve(process.env.A2ADAPT_STATE_DIR ?? file.stateDir ?? DEFAULT_CONFIG.stateDir),
+    gcIntervalMs: envInt("A2ADAPT_GC_INTERVAL_MS") ?? file.gcIntervalMs ?? DEFAULT_CONFIG.gcIntervalMs
+  };
+}
+
+// src/index.ts
+var VERSION = true ? "0.7.0" : "0.0.0-dev";
+var CONFIG = loadConfig();
+var STATE_DIR = CONFIG.stateDir;
+var BROKER_URL = CONFIG.brokerUrl;
 var TRANSPORT = process.env.A2ADAPT_TRANSPORT ?? "http";
-var PORT = parseInt(process.env.A2ADAPT_PORT ?? "3030", 10);
+var PORT = CONFIG.port;
+var GC_INTERVAL_MS = CONFIG.gcIntervalMs;
 var log = (...parts) => process.stderr.write(`a2adapt: ${parts.join(" ")}
 `);
 var NAME_RE = /^[A-Za-z0-9 _.-]{1,64}$/;
@@ -22457,15 +22509,15 @@ function validateName(name) {
   return null;
 }
 function locateUnit() {
-  const here = dirname(fileURLToPath(import.meta.url));
+  const here = dirname2(fileURLToPath(import.meta.url));
   const override = process.env.A2ADAPT_UNIT_DIR;
-  const candidates = override ? [resolve(override)] : [join(here, "mufl_code"), join(here, "..", "mufl_code")];
+  const candidates = override ? [resolve2(override)] : [join2(here, "mufl_code"), join2(here, "..", "mufl_code")];
   for (const dir of candidates) {
-    if (!fs.existsSync(dir)) continue;
-    const muflo = fs.readdirSync(dir).find((f) => f.endsWith(".muflo"));
+    if (!fs2.existsSync(dir)) continue;
+    const muflo = fs2.readdirSync(dir).find((f) => f.endsWith(".muflo"));
     if (muflo) {
       const hash = muflo.slice(0, -".muflo".length);
-      const contents = new Uint8Array(fs.readFileSync(join(dir, muflo)));
+      const contents = new Uint8Array(fs2.readFileSync(join2(dir, muflo)));
       return { dir, hash, contents };
     }
   }
@@ -22479,18 +22531,18 @@ var identities = /* @__PURE__ */ new Map();
 var sessionBinding = /* @__PURE__ */ new Map();
 var bindingOwner = /* @__PURE__ */ new Map();
 var evictedSessions = /* @__PURE__ */ new Set();
-var identityDir = (name) => join(STATE_DIR, name);
-var seedPath = (dir) => join(dir, "identity.seed");
-var dataPath = (dir) => join(dir, "state_data.bin");
-var notifyLogPath = (dir) => join(dir, "notifications.log");
-var unreadPath = (dir) => join(dir, "unread.json");
+var identityDir = (name) => join2(STATE_DIR, name);
+var seedPath = (dir) => join2(dir, "identity.seed");
+var dataPath = (dir) => join2(dir, "state_data.bin");
+var notifyLogPath = (dir) => join2(dir, "notifications.log");
+var unreadPath = (dir) => join2(dir, "unread.json");
 function listPersistedNames() {
-  if (!fs.existsSync(STATE_DIR)) return [];
-  return fs.readdirSync(STATE_DIR, { withFileTypes: true }).filter((d) => d.isDirectory() && fs.existsSync(seedPath(join(STATE_DIR, d.name)))).map((d) => d.name);
+  if (!fs2.existsSync(STATE_DIR)) return [];
+  return fs2.readdirSync(STATE_DIR, { withFileTypes: true }).filter((d) => d.isDirectory() && fs2.existsSync(seedPath(join2(STATE_DIR, d.name)))).map((d) => d.name);
 }
 function hasSavedState(dir) {
   try {
-    return fs.existsSync(dataPath(dir)) && fs.statSync(dataPath(dir)).size > 0;
+    return fs2.existsSync(dataPath(dir)) && fs2.statSync(dataPath(dir)).size > 0;
   } catch {
     return false;
   }
@@ -22501,19 +22553,19 @@ function saveState(id) {
       object_to_adapt_value({ name: "::actor::export_state", targ: void 0 })
     );
     const bytes = Buffer.from(exported.Serialize());
-    fs.mkdirSync(id.dir, { recursive: true });
+    fs2.mkdirSync(id.dir, { recursive: true });
     const tmp = `${dataPath(id.dir)}.tmp`;
-    fs.writeFileSync(tmp, bytes);
-    fs.renameSync(tmp, dataPath(id.dir));
+    fs2.writeFileSync(tmp, bytes);
+    fs2.renameSync(tmp, dataPath(id.dir));
   } catch (err) {
     log(`[${id.name}] failed to save state:`, String(err));
   }
 }
 function appendNotifyLog(id, from, msgId, date3) {
   try {
-    fs.mkdirSync(id.dir, { recursive: true });
+    fs2.mkdirSync(id.dir, { recursive: true });
     const line = JSON.stringify({ event: "message_received", from, msg_id: msgId, date: date3 }) + "\n";
-    fs.appendFileSync(notifyLogPath(id.dir), line);
+    fs2.appendFileSync(notifyLogPath(id.dir), line);
   } catch (err) {
     log(`[${id.name}] failed to append notifications.log:`, String(err));
   }
@@ -22526,10 +22578,10 @@ function refreshUnread(id) {
       count: unread.length,
       recent: unread.slice(-10).map((m) => ({ from: m.sender_name, msg_id: m.msg_id, date: m.date }))
     };
-    fs.mkdirSync(id.dir, { recursive: true });
+    fs2.mkdirSync(id.dir, { recursive: true });
     const tmp = `${unreadPath(id.dir)}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(snapshot));
-    fs.renameSync(tmp, unreadPath(id.dir));
+    fs2.writeFileSync(tmp, JSON.stringify(snapshot));
+    fs2.renameSync(tmp, unreadPath(id.dir));
   } catch (err) {
     log(`[${id.name}] failed to refresh unread snapshot:`, String(err));
   }
@@ -22665,9 +22717,9 @@ function createPacket(name, seed, dir) {
 }
 async function provisionIdentity(name) {
   const dir = identityDir(name);
-  fs.mkdirSync(dir, { recursive: true });
+  fs2.mkdirSync(dir, { recursive: true });
   const seed = randomBytes(24).toString("hex");
-  fs.writeFileSync(seedPath(dir), seed, { mode: 384 });
+  fs2.writeFileSync(seedPath(dir), seed, { mode: 384 });
   const id = await createPacket(name, seed, dir);
   await mutatingTx(id, "::actor::set_my_name", { name });
   saveState(id);
@@ -22675,11 +22727,11 @@ async function provisionIdentity(name) {
 }
 async function restoreIdentity(name) {
   const dir = identityDir(name);
-  const seed = fs.readFileSync(seedPath(dir), "utf8").trim();
+  const seed = fs2.readFileSync(seedPath(dir), "utf8").trim();
   const id = await createPacket(name, seed, dir);
   if (hasSavedState(dir)) {
     try {
-      const buf = fs.readFileSync(dataPath(dir));
+      const buf = fs2.readFileSync(dataPath(dir));
       const adaptData = id.pw.packet.ParseValue(new Uint8Array(buf));
       await mutatingTx(id, "::actor::import_state", adaptData);
     } catch (err) {
@@ -22786,10 +22838,10 @@ function packInvite(raw) {
       [zlibConstants.BROTLI_PARAM_SIZE_HINT]: raw.length
     }
   });
-  return Buffer.concat([Buffer.from([INVITE_BROTLI_V1]), compressed]).toString("base64");
+  return Buffer.concat([Buffer.from([INVITE_BROTLI_V1]), compressed]).toString("base64url");
 }
 function unpackInvite(b64) {
-  const outer = Buffer.from(b64.trim(), "base64");
+  const outer = Buffer.from(b64.replace(/\s+/g, ""), "base64url");
   if (outer.length < 2) throw new Error("the invite blob is too short or not valid base64");
   const version2 = outer[0];
   if (version2 === INVITE_BROTLI_V1) return Buffer.from(brotliDecompressSync(outer.subarray(1)));
@@ -22897,7 +22949,7 @@ ${lines.join("\n")}`);
         sessionBinding.delete(holder);
       }
       try {
-        fs.rmSync(id.dir, { recursive: true, force: true });
+        fs2.rmSync(id.dir, { recursive: true, force: true });
       } catch (err) {
         return textResult(`Identity "${name}" removed from memory, but deleting ${id.dir} failed: ${String(err)}`, true);
       }
@@ -23003,6 +23055,23 @@ ${contacts.map((c) => `\u2022 ${c.name} \u2014 ${c.container_id}`).join("\n")}`)
       }
     }
   );
+  server.tool(
+    "remove_contact",
+    "Forget a contact (by name or container id) \u2014 drops it from the bound identity's contacts, so you can no longer message them and inbound messages from them are rejected. This is a contacts-layer forget, NOT a key wipe: the per-peer channel key material persists, so re-adding the same peer reuses the existing encrypted channel rather than re-handshaking. Requires a bound identity.",
+    { contact: external_exports.string().min(1).describe("Contact name or container id to remove.") },
+    async ({ contact }) => {
+      const { id, err } = boundOr();
+      if (err) return err;
+      try {
+        const data = await mutatingTx(id, "::actor::remove_contact", { contact });
+        const name = data.Reduce("removed").Visualize();
+        const cid = data.Reduce("container_id").Visualize();
+        return textResult(`Removed contact "${name}" (${cid}).`);
+      } catch (e) {
+        return textResult(`remove_contact failed: ${String(e)}`, true);
+      }
+    }
+  );
   server.tool(
     "list_incoming_messages",
     "List ALL messages in the bound identity's inbox (decrypted), each with its id and status (unread/read). A read-only history view \u2014 it does not change any status. To consume new mail use get_messages instead.",
@@ -23025,7 +23094,7 @@ ${inbox.map((m) => fmtMsg(m)).join("\n")}`
   );
   server.tool(
     "get_messages",
-    'Fetch the messages the bound identity has not seen yet (status "unread") and mark them "read". This is the ONLY call that returns message bodies. A message is delivered here exactly once, so reading and acting on it immediately will not double-process. Note each message id: pass them to mark_processed when done, or to defer_messages to leave a message for another session.',
+    'Fetch the messages the bound identity has not seen yet (status "unread") and mark them "processed". This is the ONLY call that returns message bodies, and each message is delivered exactly once, so reading and acting on it immediately never double-processes \u2014 no acknowledgement call is needed. If you read a message but crash or want to hand it to another session before acting, call defer_messages to put it back to "unread"; otherwise handled messages are garbage-collected automatically.',
     {},
     async () => {
       const { id, err } = boundOr();
@@ -23039,33 +23108,16 @@ ${inbox.map((m) => fmtMsg(m)).join("\n")}`
           `${fresh.length} new message(s):
 ${fresh.map((m) => fmtMsg(m, false)).join("\n")}
 
-When handled: mark_processed({ msg_ids: [${fresh.map((m) => m.msg_id).join(", ")}] }). To leave any for another session: defer_messages({ msg_ids: [...] }).`
+These are now marked processed (auto-GC'd later). To hand any back to another session: defer_messages({ msg_ids: [${fresh.map((m) => m.msg_id).join(", ")}] }).`
         );
       } catch (e) {
         return textResult(`get_messages failed: ${String(e)}`, true);
       }
     }
   );
-  server.tool(
-    "mark_processed",
-    "Mark the given messages handled \u2014 they are removed from the inbox permanently. Idempotent: ids already gone are ignored. Optional for correctness (get_messages already prevents re-delivery); use it to keep the inbox tidy.",
-    { msg_ids: external_exports.array(external_exports.number().int()).min(1).describe("Message ids (from get_messages) to mark processed.") },
-    async ({ msg_ids }) => {
-      const { id, err } = boundOr();
-      if (err) return err;
-      try {
-        const data = await mutatingTx(id, "::actor::mark_processed", { msg_ids });
-        const n = data.Reduce("processed").Visualize();
-        refreshUnread(id);
-        return textResult(`Marked ${n} message(s) processed.`);
-      } catch (e) {
-        return textResult(`mark_processed failed: ${String(e)}`, true);
-      }
-    }
-  );
   server.tool(
     "defer_messages",
-    `Put already-read messages back into the queue (status "unread") so another session's get_messages will pick them up. Use when you read a message but want to leave it for someone else to process.`,
+    `Put handled messages back into the queue (status "unread") so another session's get_messages picks them up. Works on messages you have read (status "processed") and even ones already queued for GC ("ready_to_delete"), so a message stays recoverable across a full GC cycle.`,
     { msg_ids: external_exports.array(external_exports.number().int()).min(1).describe("Message ids (from get_messages) to defer back to unread.") },
     async ({ msg_ids }) => {
       const { id, err } = boundOr();
@@ -23083,12 +23135,12 @@ When handled: mark_processed({ msg_ids: [${fresh.map((m) => m.msg_id).join(", ")
   return server;
 }
 function readBody(req) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     let data = "";
     req.on("data", (chunk) => data += chunk);
     req.on("end", () => {
       try {
-        resolve2(JSON.parse(data));
+        resolve3(JSON.parse(data));
       } catch (e) {
         reject(e);
       }
@@ -23096,6 +23148,36 @@ function readBody(req) {
     req.on("error", reject);
   });
 }
+var gcTimer = null;
+var gcRunning = false;
+function startGcTimer() {
+  if (gcTimer) return;
+  gcTimer = setInterval(() => {
+    if (gcRunning) return;
+    gcRunning = true;
+    void (async () => {
+      try {
+        for (const id of identities.values()) {
+          try {
+            await mutatingTx(id, "::actor::gc", {});
+          } catch (e) {
+            log(`gc(${id.name}) failed:`, String(e));
+          }
+        }
+      } finally {
+        gcRunning = false;
+      }
+    })();
+  }, GC_INTERVAL_MS);
+  gcTimer.unref?.();
+  log(`message GC timer armed (every ${GC_INTERVAL_MS}ms)`);
+}
+function stopGcTimer() {
+  if (gcTimer) {
+    clearInterval(gcTimer);
+    gcTimer = null;
+  }
+}
 async function main() {
   if (TRANSPORT === "stdio") {
     const server = createMcpServer(() => "stdio");
@@ -23104,8 +23186,10 @@ async function main() {
     await server.connect(transport);
     log("MCP stdio transport connected, booting wrapper\u2026");
     await bootWrapper();
+    startGcTimer();
     log(`MCP server v${VERSION} ready (transport=stdio, identities=${identities.size}, state=${STATE_DIR}, broker=${BROKER_URL})`);
     const flush = () => {
+      stopGcTimer();
       for (const id of identities.values()) saveState(id);
       process.exit(0);
     };
@@ -23115,6 +23199,7 @@ async function main() {
   }
   log("booting wrapper\u2026");
   await bootWrapper();
+  startGcTimer();
   log(`wrapper ready (identities=${identities.size}), starting HTTP server\u2026`);
   const transports = {};
   const httpServer = createHttpServer(async (req, res) => {
@@ -23191,6 +23276,7 @@ async function main() {
   });
   const shutdown = async () => {
     log("shutting down\u2026");
+    stopGcTimer();
     for (const sid of Object.keys(transports)) {
       try {
         await transports[sid].close();

package/dist/mufl_code/actor.mu

@@ -5,16 +5,17 @@
 // encrypted; the key exchange is handled for us by the stdlib `encrypted_channel`
 // library — we only ever address peers by their container id.
 //
-// User transactions (each backs one MCP tool):
+// User transactions (each backs one MCP tool, except gc which the host fires):
 //   set_my_name             — set the display name peers see for me
 //   generate_invite         — make a slim personal invite blob for a named peer
 //   add_contact             — join via an invite blob, reply to the inviter
 //   send_message            — send an e2e-encrypted message to a contact
+//   remove_contact          — forget a contact (drops it from my contacts)
 //   list_contacts           — (readonly) my contacts
 //   list_incoming_messages  — (readonly) my inbox, with per-message id + status
-//   get_messages            — return unread messages + mark them read (sole body egress)
-//   mark_processed          — delete handled messages from the inbox
-//   defer_messages          — flip read messages back to unread for another session
+//   get_messages            — return unread messages + mark them processed (sole body egress)
+//   defer_messages          — flip processed/ready_to_delete messages back to unread
+//   gc                      — two-generation GC of handled messages (host-fired, not a tool)
 //
 // External transactions (inbound, not exposed as tools):
 //   accept_contact          — inviter learns the joiner's identity + name
@@ -55,10 +56,12 @@ application actor loads libraries
         // (each key knows its own function + id), so the reconstructed identity is
         // byte-identical to the signed one and the self-signatures still verify.
         metadef invite_t: ($d -> global_id, $n -> str, $c -> global_id, $k -> key_utils::t_publickey(,), $a -> crypto_signature(,)).
-        // A received message carries a stable per-packet id and a lifecycle
-        // status: "unread" (just arrived) -> "read" (handed to the agent via
-        // get_messages). mark_processed deletes it; defer_messages flips it back
-        // to "unread" so another session can pick it up.
+        // A received message carries a stable per-packet id and a lifecycle status:
+        // "unread" (just arrived) -> "processed" (handed to the agent via
+        // get_messages) -> "ready_to_delete" (first gc tick) -> deleted (next gc
+        // tick). defer_messages flips "processed"/"ready_to_delete" back to "unread"
+        // so another session can pick it up — restorable from either generation,
+        // which is what makes the two-generation gc window race-free.
         metadef message_t: ($msg_id -> int, $sender_id -> global_id, $sender_name -> str, $text -> str, $date -> time, $status -> str).
         // The pre-lifecycle inbox shape (no per-message id/status). import_state
         // migrates blobs in this shape forward — see below.
@@ -236,6 +239,23 @@ application actor loads libraries
         }).
     }
 
+    trn remove_contact _:($contact -> contact_ref: str)
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+
+        target_id = resolve_contact contact_ref.
+        removed = contacts target_id.
+        removed_name = removed? $name.
+
+        delete contacts target_id.
+        if peer_ads target_id != NIL { delete peer_ads target_id. }
+
+        return transaction::success [
+            _return_data ($removed -> removed_name, $container_id -> target_id),
+            _save_state NIL
+        ].
+    }
+
     trn readonly list_contacts _
     {
         return contacts.
@@ -246,13 +266,13 @@ application actor loads libraries
         return inbox.
     }
 
-    // Hand the agent every message it has not seen yet (status "unread") and
-    // flip those to "read". This is the ONLY place message bodies leave the
-    // packet. Delivery is the dedup point: a message is returned by get_messages
-    // exactly once, so an agent that reads and acts immediately never double-
-    // processes — no explicit acknowledgement is required for safety. To leave a
-    // message for another session instead, call defer_messages (status -> unread
-    // again); to discard it for good, call mark_processed (removed from inbox).
+    // Hand the agent every message it has not seen yet (status "unread") and flip
+    // those to "processed" — the ONLY place message bodies leave the packet, and
+    // the sole dedup point: a message is returned exactly once, so an agent that
+    // reads and acts immediately never double-processes. CRASH WINDOW: a
+    // "processed" body has already left; an agent that crashes after get_messages
+    // but before acting must defer_messages to recover it (-> "unread") before gc
+    // promotes it through "ready_to_delete" and deletes it (>= 1 gc cycle).
     trn get_messages _
     {
         current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
@@ -263,16 +283,16 @@ application actor loads libraries
         {
             if (m $status) == "unread"
             {
-                read_m is message_t = (
+                processed_m is message_t = (
                     $msg_id      -> m $msg_id,
                     $sender_id   -> m $sender_id,
                     $sender_name -> m $sender_name,
                     $text        -> m $text,
                     $date        -> m $date,
-                    $status      -> "read"
+                    $status      -> "processed"
                 ).
                 fresh (_count fresh|) -> m.
-                new_inbox (_count new_inbox|) -> read_m.
+                new_inbox (_count new_inbox|) -> processed_m.
             }
             else
             {
@@ -287,40 +307,57 @@ application actor loads libraries
         ].
     }
 
-    // Remove the given messages from the inbox permanently — the agent is done
-    // with them. Idempotent: ids that are already gone are silently skipped.
-    trn mark_processed _:($msg_ids -> ids: int[])
+    // Two-generation garbage collection of handled messages, fired by the host on
+    // a timer (NOT piggybacked on other transactions — that would collapse the
+    // window under traffic). Order matters: (A) delete everything already marked
+    // "ready_to_delete", THEN (B) promote "processed" -> "ready_to_delete". A
+    // single pass keyed on the current status gives exactly that — a message is in
+    // one status, so a freshly-processed message is promoted (not dropped) this
+    // tick and only deleted on the NEXT tick, guaranteeing it survives a full
+    // cycle (>= 1 interval) as a deferrable "ready_to_delete".
+    trn gc _
     {
         current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
 
-        wanted is (int ->> bool) = (,).
-        sc ids -- ( -> id) { wanted id -> TRUE. }
-
-        new_inbox is message_t[] = [].
-        removed is int = 0.
+        kept is message_t[] = [].
+        deleted is int = 0.
+        promoted is int = 0.
         sc inbox -- ( -> m)
         {
-            if wanted (m $msg_id)
+            if (m $status) == "ready_to_delete"
             {
-                removed -> removed + 1.
+                deleted -> deleted + 1.
+            }
+            elif (m $status) == "processed"
+            {
+                kept (_count kept|) -> (
+                    $msg_id      -> m $msg_id,
+                    $sender_id   -> m $sender_id,
+                    $sender_name -> m $sender_name,
+                    $text        -> m $text,
+                    $date        -> m $date,
+                    $status      -> "ready_to_delete"
+                ).
+                promoted -> promoted + 1.
             }
             else
             {
-                new_inbox (_count new_inbox|) -> m.
+                kept (_count kept|) -> m.
             }
         }
-        inbox -> new_inbox.
+        inbox -> kept.
 
         return transaction::success [
-            _return_data ($processed -> removed),
+            _return_data ($deleted -> deleted, $promoted -> promoted),
             _save_state NIL
         ].
     }
 
-    // Put already-read messages back into the queue (status -> "unread") so a
-    // different session will pick them up on its next get_messages. The explicit,
-    // opt-in counterpart to the safe default: forgetting to defer just means the
-    // message stays handled by you; only a deliberate defer re-exposes it.
+    // Put handled messages back into the queue (status -> "unread") so a different
+    // session picks them up on its next get_messages. Restores from EITHER post-
+    // read generation — "processed" or "ready_to_delete" — so a message stays
+    // recoverable across a full gc cycle. The opt-in counterpart to the safe
+    // default: forgetting to defer just means the message stays handled by you.
     trn defer_messages _:($msg_ids -> ids: int[])
     {
         current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
@@ -332,7 +369,7 @@ application actor loads libraries
         deferred is int = 0.
         sc inbox -- ( -> m)
         {
-            if (wanted (m $msg_id)) && ((m $status) == "read")
+            if (wanted (m $msg_id)) && (((m $status) == "processed") || ((m $status) == "ready_to_delete"))
             {
                 new_inbox (_count new_inbox|) -> (
                     $msg_id      -> m $msg_id,
@@ -389,12 +426,13 @@ application actor loads libraries
         pending_invites -> (data $pending_invites) safe (global_id ->> str).
         peer_ads        -> (data $peer_ads) safe (global_id ->> address_document_types::t_address_document).
 
-        // The inbox + next_msg_seq are the only parts the message-lifecycle change
+        // The inbox + next_msg_seq are the only parts the message-lifecycle changes
         // touched. A pre-lifecycle blob has no $next_msg_seq and inbox entries with
         // no id/status — MIGRATE it forward (the whole point of code-independent
         // state is that an old export upgrades, never resets): assign each legacy
         // message a sequential id and status "unread", and seed next_msg_seq past
-        // them. A current blob is taken as-is.
+        // them. A current-shape blob is loaded as-is except the gc vocabulary bump
+        // ("read" -> "processed", see below).
         if (data $next_msg_seq) == NIL
         {
             legacy_inbox = (data $inbox) safe (legacy_message_t[]).
@@ -417,7 +455,24 @@ application actor loads libraries
         }
         else
         {
-            inbox        -> (data $inbox) safe (message_t[]).
+            // Current-shape blob. One vocabulary change: a blob written before the
+            // gc change may carry the old "read" status — migrate it to "processed"
+            // (else such a message is stuck: never returned, gc'd, or deferred).
+            loaded = (data $inbox) safe (message_t[]).
+            upgraded is message_t[] = [].
+            sc loaded -- ( -> m)
+            {
+                mstatus = ((m $status) == "read" ?? "processed" ; m $status).
+                upgraded (_count upgraded|) -> (
+                    $msg_id      -> m $msg_id,
+                    $sender_id   -> m $sender_id,
+                    $sender_name -> m $sender_name,
+                    $text        -> m $text,
+                    $date        -> m $date,
+                    $status      -> mstatus
+                ).
+            }
+            inbox        -> upgraded.
             next_msg_seq -> (data $next_msg_seq) safe int.
         }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adapt-toolkit/a2adapt",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "MCP server daemon for a2adapt — one native ADAPT wrapper hosting N self-sovereign identities, exposing secure agent-to-agent messaging tools over HTTP (Streamable HTTP). Run `a2adapt-mcp start`.",
   "type": "module",
   "license": "MIT",