edge-book 0.17.0 → 0.18.0

package/dist/edge-book.js

@@ -2,11 +2,11 @@
 
 // src/cli.ts
 import { realpathSync } from "fs";
-import { fileURLToPath } from "url";
+import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/cli-shared.ts
-import fs9 from "fs/promises";
-import path10 from "path";
+import fs11 from "fs/promises";
+import path11 from "path";
 
 // src/dialout.ts
 import crypto6 from "crypto";
@@ -18,7 +18,7 @@ import fs from "fs/promises";
 import path from "path";
 var DIALOUT_KEY_FILE = "host-dialout-key.json";
 var KEY_FILE = DIALOUT_KEY_FILE;
-var DEFAULT_PAIR_TTL_MS = 5 * 60 * 1e3;
+var DEFAULT_PAIR_TTL_MS = 10 * 60 * 1e3;
 var PAIRING_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
 function now() {
   return (/* @__PURE__ */ new Date()).toISOString();
@@ -1702,12 +1702,13 @@ async function receiveFriendRequest(store, envelope) {
   return contact;
 }
 async function pendingFriendRequests(store) {
+  const contacts = await store.contacts();
+  return Object.values(contacts).filter((c) => c.relationship_state === "request_received");
+}
+async function unnotifiedFriendRequests(store) {
   const config = await store.config();
   if (config.notify_on_friend_request === false) return [];
-  const contacts = await store.contacts();
-  return Object.values(contacts).filter(
-    (c) => c.relationship_state === "request_received" && !c.notified_at
-  );
+  return (await pendingFriendRequests(store)).filter((c) => !c.notified_at);
 }
 async function markFriendRequestNotified(store, peerAgentId) {
   const contacts = await store.contacts();
@@ -2031,8 +2032,16 @@ async function updateConfig(store, input) {
   if (input.onboarding_nudge_at !== void 0) next.onboarding_nudge_at = input.onboarding_nudge_at;
   if (input.onboarding_nudge_count !== void 0) next.onboarding_nudge_count = input.onboarding_nudge_count;
   if (input.greeter_mode !== void 0) next.greeter_mode = input.greeter_mode;
+  if (input.notifier_prompt_ack !== void 0) next.notifier_prompt_ack = input.notifier_prompt_ack;
+  if (input.notifier_nudge_at !== void 0) next.notifier_nudge_at = input.notifier_nudge_at;
   if (input.support_inbox !== void 0) next.support_inbox = input.support_inbox;
   if (input.greeter_welcome_object_id !== void 0) next.greeter_welcome_object_id = input.greeter_welcome_object_id;
+  if (input.auto_update !== void 0) next.auto_update = input.auto_update;
+  if (input.update_check_at !== void 0) next.update_check_at = input.update_check_at;
+  if (input.update_latest_known !== void 0) next.update_latest_known = input.update_latest_known;
+  if (input.update_nudge_at !== void 0) next.update_nudge_at = input.update_nudge_at;
+  if (input.updated_at !== void 0) next.updated_at = input.updated_at;
+  if (input.dialout_respawn_expected !== void 0) next.dialout_respawn_expected = input.dialout_respawn_expected;
   await writeJson(store.file(CONFIG_FILE), next);
   return next;
 }
@@ -2744,11 +2753,15 @@ var EdgeBookStore = class {
   async receiveFriendRequest(envelope) {
     return receiveFriendRequest(this, envelope);
   }
-  // Inbound friend requests the human hasn't been told about yet. Empty when the
-  // agent has notifications disabled. Read-only — the notifier cron consumes this.
+  // All inbound friend requests awaiting accept/decline (spec-139). Read-only.
   async pendingFriendRequests() {
     return pendingFriendRequests(this);
   }
+  // Inbound friend requests the human hasn't been told about yet. Empty when the
+  // agent has notifications disabled. Read-only — the notifier cron consumes this.
+  async unnotifiedFriendRequests() {
+    return unnotifiedFriendRequests(this);
+  }
   // Stamp a request as notified so it won't surface again (idempotent sweep,
   // mirrors expireEscalations).
   async markFriendRequestNotified(peerAgentId) {
@@ -5110,6 +5123,246 @@ function gateHostFrame(frame) {
   return { ok: false, frameType: type, errorPaths: paths };
 }
 
+// src/update-drift.ts
+import fs9 from "fs/promises";
+
+// src/self-update.ts
+import { execFile } from "child_process";
+import fs8 from "fs/promises";
+import path8 from "path";
+import { fileURLToPath } from "url";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+var REGISTRY_LATEST_URL = "https://registry.npmjs.org/edge-book/latest";
+var REGISTRY_TIMEOUT_MS = 3e3;
+var UPDATE_CHECK_THROTTLE_MS = 24 * 60 * 60 * 1e3;
+var SELF_UPDATE_LOCK = ".edge-book-self-update.lock";
+var LOCK_STALE_MS = 15 * 60 * 1e3;
+var SYSTEM_ROOT_PREFIXES = ["/usr/lib", "/usr/local/lib", "/usr/share", "/opt/homebrew", "/snap/", "/nix/store"];
+var cachedRunning;
+async function runningVersion() {
+  if (cachedRunning) return cachedRunning;
+  try {
+    const pkg = JSON.parse(await fs8.readFile(new URL("../package.json", import.meta.url), "utf8"));
+    cachedRunning = typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    cachedRunning = "0.0.0";
+  }
+  return cachedRunning;
+}
+function compareVersions(a, b) {
+  const pa = a.split("-")[0].split(".").map(Number);
+  const pb = b.split("-")[0].split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+function majorOf(version) {
+  return Number(version.split(".")[0]) || 0;
+}
+function autoUpdateAllowed(running, latest) {
+  const runningMajor = majorOf(running);
+  if (runningMajor >= 1 && majorOf(latest) !== runningMajor) return false;
+  return true;
+}
+async function checkLatest(store, opts = {}) {
+  const now4 = opts.now ?? Date.now();
+  let cached;
+  try {
+    const config = await store.config();
+    cached = config.update_latest_known;
+    if (!opts.force && config.update_check_at !== void 0 && now4 - config.update_check_at < UPDATE_CHECK_THROTTLE_MS) {
+      return cached;
+    }
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const response = await fetchImpl(REGISTRY_LATEST_URL, { signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS) });
+    if (!response.ok) throw new Error(`registry ${response.status}`);
+    const body = await response.json();
+    if (typeof body.version !== "string" || !/^\d+\.\d+\.\d+/.test(body.version)) throw new Error("malformed registry response");
+    await store.updateConfig({ update_check_at: now4, update_latest_known: body.version });
+    return body.version;
+  } catch {
+    await store.updateConfig({ update_check_at: now4 }).catch(() => void 0);
+    return cached;
+  }
+}
+function resolveInstallRoot(modulePath = fileURLToPath(import.meta.url)) {
+  let dir = path8.dirname(modulePath);
+  for (; ; ) {
+    const parent = path8.dirname(dir);
+    if (path8.basename(dir) === "edge-book" && path8.basename(parent) === "node_modules") {
+      return path8.dirname(parent);
+    }
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function notSelfUpdatable(detail, manualCommand) {
+  return new EdgeBookError(
+    "install_not_self_updatable",
+    `install_not_self_updatable: ${detail}. Update manually with the right permissions: ${manualCommand}`
+  );
+}
+async function assertSelfUpdatableRoot(root) {
+  if (root === null) {
+    throw notSelfUpdatable("this edge-book does not run from an npm install root", "npm install -g edge-book@latest");
+  }
+  const manual = `npm install edge-book@latest --prefix ${root}`;
+  if (SYSTEM_ROOT_PREFIXES.some((prefix) => root === prefix.replace(/\/$/, "") || root.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`))) {
+    throw notSelfUpdatable(`install root ${root} is system-managed`, manual);
+  }
+  try {
+    await fs8.access(root, fs8.constants.W_OK);
+    await fs8.access(path8.join(root, "node_modules"), fs8.constants.W_OK);
+  } catch {
+    throw notSelfUpdatable(`install root ${root} is not writable by this process`, manual);
+  }
+  return root;
+}
+async function acquireLock(lockPath, now4) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      await fs8.writeFile(lockPath, `${process.pid} ${new Date(now4).toISOString()}
+`, { flag: "wx" });
+      return;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const stat = await fs8.stat(lockPath).catch(() => null);
+      if (stat && now4 - stat.mtimeMs > LOCK_STALE_MS) {
+        await fs8.rm(lockPath, { force: true });
+        continue;
+      }
+      throw new EdgeBookError("update_in_progress", `update_in_progress: another self-update holds ${lockPath}`);
+    }
+  }
+  throw new EdgeBookError("update_in_progress", `update_in_progress: could not acquire ${lockPath}`);
+}
+async function defaultNpmInstall(spec, root) {
+  await execFileAsync("npm", ["install", spec, "--prefix", root, "--no-audit", "--no-fund"], { timeout: 18e4 });
+}
+async function defaultVerify(root) {
+  const entry = path8.join(root, "node_modules", "edge-book", "dist", "edge-book.js");
+  const { stdout } = await execFileAsync(process.execPath, [entry, "--version"], { timeout: 3e4 });
+  return stdout.trim();
+}
+async function selfAgentId(store) {
+  try {
+    return (await store.identity()).agent_id;
+  } catch {
+    return "self";
+  }
+}
+async function recordFailure(store, from, to, reason) {
+  await store.audit("update.self", await selfAgentId(store), { from, to, ok: false, reason });
+  await logEvent(store, "update.failed", { from, to, reason });
+}
+function restartAdvice(autoRespawn) {
+  return autoRespawn ? "A running dial-out will detect the new install (on reconnect or within 6h) and exit 75 so its supervisor respawns it onto the new code \u2014 no restart needed from you." : "Restart the dial-out process now to pick up the new code \u2014 under this configuration it will NOT restart itself.";
+}
+async function performUpdate(store, root, from, latest, opts, now4) {
+  const install = opts.npmInstall ?? defaultNpmInstall;
+  try {
+    await install(`edge-book@${latest}`, root);
+  } catch (error) {
+    await recordFailure(store, from, latest, eventErrorCode(error));
+    throw new EdgeBookError("update_failed", `update_failed: npm install edge-book@${latest} --prefix ${root} failed; the previous install remains in place.`);
+  }
+  let reported;
+  try {
+    reported = (await (opts.verify ?? defaultVerify)(root)).trim();
+  } catch (error) {
+    reported = `spawn_failed:${eventErrorCode(error)}`;
+  }
+  if (reported !== latest) {
+    await recordFailure(store, from, latest, `verify_mismatch:${reported}`);
+    throw new EdgeBookError("update_failed", `update_failed: the new build reports "${reported}" instead of ${latest}; not trusting it. The npm tree at ${root} may need a manual reinstall.`);
+  }
+  await store.audit("update.self", await selfAgentId(store), { from, to: latest });
+  await logEvent(store, "update.self", { from, to: latest });
+  const config = await store.updateConfig({ updated_at: now4, update_latest_known: latest });
+  const autoRespawn = (config.auto_update ?? "auto") === "auto" && config.dialout_respawn_expected !== false;
+  return { status: "updated", from, to: latest, text: `Updated edge-book ${from} \u2192 ${latest} in ${root}.
+${restartAdvice(autoRespawn)}` };
+}
+async function selfUpdate(store, opts = {}) {
+  const now4 = opts.now ?? Date.now();
+  const from = opts.running ?? await runningVersion();
+  const config = await store.config();
+  const mode = config.auto_update ?? "auto";
+  const latest = await checkLatest(store, { now: now4, fetchImpl: opts.fetchImpl, force: true });
+  if (!latest) {
+    if (opts.ifStale) return { status: "current", from, text: "" };
+    throw new EdgeBookError("registry_unreachable", "registry_unreachable: could not determine the latest edge-book version from the npm registry.");
+  }
+  if (compareVersions(latest, from) <= 0) {
+    return { status: "current", from, to: latest, text: opts.ifStale ? "" : `edge-book ${from} is current (latest published: ${latest}); never downgrading.` };
+  }
+  if (opts.ifStale && (mode !== "auto" || !autoUpdateAllowed(from, latest))) {
+    return { status: "skipped", from, to: latest, text: "" };
+  }
+  const root = await assertSelfUpdatableRoot(opts.installRoot !== void 0 ? opts.installRoot : resolveInstallRoot());
+  if (opts.dryRun) {
+    return { status: "dry_run", from, to: latest, text: `Would update edge-book ${from} \u2192 ${latest} in ${root} (dry run; nothing installed).` };
+  }
+  const lockPath = path8.join(root, SELF_UPDATE_LOCK);
+  await acquireLock(lockPath, now4);
+  try {
+    return await performUpdate(store, root, from, latest, opts, now4);
+  } finally {
+    await fs8.rm(lockPath, { force: true }).catch(() => void 0);
+  }
+}
+
+// src/update-drift.ts
+var DRIFT_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1e3;
+async function installedVersion() {
+  try {
+    const pkg = JSON.parse(await fs9.readFile(new URL("../package.json", import.meta.url), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function createUpdateDriftMonitor(store, deps = {}) {
+  const running = deps.running !== void 0 ? Promise.resolve(deps.running) : runningVersion();
+  const installed = deps.installed ?? installedVersion;
+  const exit = deps.exit ?? ((code) => process.exit(code));
+  const check2 = deps.checkLatestImpl ?? ((s) => checkLatest(s));
+  let timer;
+  async function driftCheck() {
+    try {
+      const inMemory = await running;
+      const onDisk = await installed();
+      if (!onDisk || onDisk === inMemory) return;
+      const config = await store.config();
+      const mode = config.auto_update ?? "auto";
+      const respawnExpected = config.dialout_respawn_expected !== false;
+      await logEvent(store, "dialout.version_drift", { running: inMemory, installed: onDisk, mode, respawn_expected: respawnExpected });
+      if (mode !== "auto" || !respawnExpected) return;
+      console.log(`dialout.restart_for_update: installed edge-book ${onDisk} != running ${inMemory} \u2014 exiting 75 for supervisor respawn`);
+      await logEvent(store, "dialout.restart_for_update", { from: inMemory, to: onDisk });
+      exit(75);
+    } catch {
+    }
+  }
+  return {
+    onConnect: () => driftCheck(),
+    start() {
+      if (timer) return;
+      timer = setInterval(() => {
+        void check2(store).catch(() => void 0).then(() => driftCheck());
+      }, deps.intervalMs ?? DRIFT_CHECK_INTERVAL_MS);
+      timer.unref?.();
+    },
+    stop() {
+      if (timer) clearInterval(timer);
+      timer = void 0;
+    }
+  };
+}
+
 // src/dialout-oneshot.ts
 async function sendPairRegistration(options) {
   const client = new EdgeBookDialoutClient({ ...options, reconnect: false, openLocalApi: false });
@@ -5190,6 +5443,7 @@ function addSocketListener(socket, event, handler) {
 }
 var EdgeBookDialoutClient = class {
   options;
+  driftMonitor;
   store;
   socket;
   localApi;
@@ -5219,6 +5473,7 @@ var EdgeBookDialoutClient = class {
       home: options.home
     };
     this.store = new EdgeBookStore({ home: options.home });
+    this.driftMonitor = options.driftMonitor ?? createUpdateDriftMonitor(this.store);
     this.currentBackoff = this.options.backoffMs;
   }
   async start() {
@@ -5227,6 +5482,7 @@ var EdgeBookDialoutClient = class {
   }
   async stop() {
     this.stopped = true;
+    this.driftMonitor.stop();
     if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
     if (this.heartbeat) clearInterval(this.heartbeat);
     this.socket?.close();
@@ -5235,7 +5491,15 @@ var EdgeBookDialoutClient = class {
   }
   async pair(ttlMs = DEFAULT_PAIR_TTL_MS) {
     const registration = await createPairRegistration(this.store, ttlMs);
+    const ackPromise = this.awaitAck(registration.frame.request_id, "pair_register", "pair_register_ok", 5e3);
     this.send(registration.frame);
+    try {
+      const ack = await ackPromise;
+      if (ack.type === "pair_register_err") throw new EdgeBookError("pair_register_rejected", String(ack.error || "Host rejected the pairing registration"));
+      if (typeof ack.expires_at === "number") registration.expires_at = ack.expires_at;
+    } catch (error) {
+      if (!(error instanceof EdgeBookError && error.code === "host_rpc_timeout")) throw error;
+    }
     return registration;
   }
   // Wait up to ttlMs for a pair_complete frame from the host.
@@ -5275,15 +5539,20 @@ var EdgeBookDialoutClient = class {
   // request_id. `expect` documents the ack type; resolution is by request_id.
   async rpc(type, extra, expect, timeoutMs) {
     const request_id = crypto6.randomUUID();
-    const promise = new Promise((resolve, reject) => {
+    const promise = this.awaitAck(request_id, type, expect, timeoutMs);
+    this.send({ type, request_id, ...extra });
+    return promise;
+  }
+  // Register a pending ack for an already-built frame's request_id (used by
+  // pair(), whose frame is minted in dialout-key.ts rather than by rpc()).
+  awaitAck(request_id, rpcType, expect, timeoutMs) {
+    return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pendingRpc.delete(request_id);
         reject(new EdgeBookError("host_rpc_timeout", `Timed out waiting for ${expect}`));
       }, timeoutMs);
-      this.pendingRpc.set(request_id, { resolve, reject, timer, rpcType: type });
+      this.pendingRpc.set(request_id, { resolve, reject, timer, rpcType });
     });
-    this.send({ type, request_id, ...extra });
-    return promise;
   }
   async revokeSessionsAndWait(timeoutMs = 5e3) {
     const frame = await createSessionsRevokeFrame(this.store);
@@ -5437,6 +5706,8 @@ var EdgeBookDialoutClient = class {
       this.opened?.resolve();
       this.opened = void 0;
       void logEvent(this.store, "dialout.connected", { host: this.options.host });
+      void this.driftMonitor.onConnect();
+      this.driftMonitor.start();
       try {
         const identity = await this.store.identity();
         if (shouldClaimHandle(identity.handle)) {
@@ -5465,7 +5736,7 @@ var EdgeBookDialoutClient = class {
       this.send({ type: "pong" });
       return;
     }
-    if (frame.type === "sessions_list_ok" || frame.type === "session_revoke_one_ok" || frame.type === "mailbox_status_ok" || frame.type === "mailbox_status_err") {
+    if (frame.type === "sessions_list_ok" || frame.type === "session_revoke_one_ok" || frame.type === "mailbox_status_ok" || frame.type === "mailbox_status_err" || frame.type === "pair_register_ok" || frame.type === "pair_register_err") {
       const ack = frame;
       const pending = this.pendingRpc.get(ack.request_id || "");
       if (pending) {
@@ -5479,7 +5750,6 @@ var EdgeBookDialoutClient = class {
       await this.standDown(frame);
       return;
     }
-    if (frame.type === "pair_register_ok" || frame.type === "pair_register_err") return;
     if (frame.type === "pair_complete") {
       this.pairCompleteWaiter.onFrame(frame);
       return;
@@ -5537,6 +5807,7 @@ var EdgeBookDialoutClient = class {
   }
   async standDown(frame) {
     this.stopped = true;
+    this.driftMonitor.stop();
     await logEvent(this.store, "dialout.stand_down", { host: this.options.host, reason: frame.reason, idle_ms: frame.idle_ms });
     if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
     if (this.heartbeat) clearInterval(this.heartbeat);
@@ -5615,22 +5886,22 @@ var EdgeBookDialoutClient = class {
 };
 
 // src/http-relay.ts
-import fs8 from "fs/promises";
+import fs10 from "fs/promises";
 import http2 from "http";
-import path8 from "path";
+import path9 from "path";
 function relayFile(store, agentId) {
-  return path8.join(store, `${encodeURIComponent(agentId)}.jsonl`);
+  return path9.join(store, `${encodeURIComponent(agentId)}.jsonl`);
 }
 async function appendRelayEnvelope(store, agentId, envelope) {
-  await fs8.mkdir(store, { recursive: true });
-  await fs8.appendFile(relayFile(store, agentId), `${JSON.stringify(envelope)}
+  await fs10.mkdir(store, { recursive: true });
+  await fs10.appendFile(relayFile(store, agentId), `${JSON.stringify(envelope)}
 `, "utf8");
 }
 async function drainRelayEnvelopes(store, agentId) {
   const file = relayFile(store, agentId);
   try {
-    const text = await fs8.readFile(file, "utf8");
-    await fs8.writeFile(file, "", "utf8");
+    const text = await fs10.readFile(file, "utf8");
+    await fs10.writeFile(file, "", "utf8");
     return text.split(/\n/).filter(Boolean).map((line) => JSON.parse(line));
   } catch (error) {
     if (error.code === "ENOENT") return [];
@@ -5690,11 +5961,11 @@ async function pullRelayEnvelopes(relayBaseUrl, recipientAgentId) {
 }
 
 // src/store-outbox.ts
-import path9 from "path";
+import path10 from "path";
 var OUTBOX_CAP = 200;
 var DEFAULT_STALE_QUEUE_MS = 10 * 60 * 1e3;
 function outboxPath(home) {
-  return path9.join(resolveHome(home), OUTBOX_FILE);
+  return path10.join(resolveHome(home), OUTBOX_FILE);
 }
 async function readOutbox(home) {
   return readJson(outboxPath(home), []);
@@ -5764,7 +6035,7 @@ function takeRepeated(args, flag) {
   return out;
 }
 async function readEnvelope(filePath) {
-  return JSON.parse(await fs9.readFile(path10.resolve(filePath), "utf8"));
+  return JSON.parse(await fs11.readFile(path11.resolve(filePath), "utf8"));
 }
 async function deliverToEndpoint(envelope, endpoint) {
   await postEnvelope(endpoint, envelope);
@@ -5844,58 +6115,30 @@ ${buildHandleNudge(suggestion)}` };
   }
 }
 
-// src/onboarding-nudge.ts
-var ONBOARDING_NUDGE_THROTTLE_MS = 6 * 60 * 60 * 1e3;
-var ONBOARDING_NUDGE_MAX_EMITS = 3;
-function buildOnboardingNudgeText() {
-  return [
-    `---`,
-    `Onboarding incomplete: this agent has no friends and no shares yet \u2014 the human was likely never onboarded.`,
-    `Load skills/edge-book/prompts/onboard.md and run the first-session script with your human now.`
-  ].join("\n");
-}
-async function maybeAppendOnboardingNudge(store, command, result, now4 = Date.now()) {
-  if (!NUDGE_COMMANDS.has(command)) return result;
-  try {
-    await store.identity();
-    const config = await store.config();
-    const count = config.onboarding_nudge_count ?? 0;
-    if (count >= ONBOARDING_NUDGE_MAX_EMITS) return result;
-    if (config.onboarding_nudge_at !== void 0 && now4 - config.onboarding_nudge_at < ONBOARDING_NUDGE_THROTTLE_MS) return result;
-    const contacts = await store.contacts();
-    if (Object.keys(contacts).length > 0) return result;
-    const objects2 = await store.objects();
-    if (Object.keys(objects2).length > 0) return result;
-    await store.updateConfig({ onboarding_nudge_at: now4, onboarding_nudge_count: count + 1 });
-    return { ...result, text: `${result.text}
-${buildOnboardingNudgeText()}` };
-  } catch {
-    return result;
-  }
-}
-
-// src/cli-identity.ts
-import fs11 from "fs/promises";
-import path11 from "path";
-
-// src/doctor.ts
-import fs10 from "fs/promises";
-
 // src/host-cron.ts
 import { existsSync } from "fs";
 import { execFileSync } from "child_process";
 var FRIEND_REQUESTS_CRON_NAME = "Edge Book \u2014 friend requests";
 var DEFAULT_FRIEND_REQUESTS_SCHEDULE = "*/20 * * * *";
 var HERMES_BIN_CANDIDATES = ["/opt/hermes/.venv/bin/hermes"];
+var NOTIFIER_PROMPT_VERSION = 3;
+function hermesCliDetected() {
+  return HERMES_BIN_CANDIDATES.some((p) => existsSync(p));
+}
 function buildFriendRequestsPrompt(home) {
   return [
     "You are the Edge Book friend-request notifier. Tell the human on their Telegram when someone has asked to connect on Edge Book. Hermes delivers your final assistant reply to their chat.",
     "",
     "This runs every 20 minutes; most runs there will be nothing pending. On any such run \u2014 and on any error \u2014 end your turn with exactly [SILENT] and nothing else. [SILENT] tells Hermes to send no message.",
     "",
-    "1. List pending requests (run once):",
-    `   edge-book friend pending --home ${home} --json`,
-    "   If edge-book is not on PATH, use: npm exec -y edge-book@0.11.0 -- friend pending --home " + home + " --json",
+    "0. Keep this agent's edge-book install current (run once, first; spec-142):",
+    `   edge-book self-update --if-stale --home ${home}`,
+    `   If edge-book is not on PATH, use: npm exec -y edge-book@latest -- self-update --if-stale --home ${home}`,
+    "   Ignore this step's output and continue to step 1 even if it errors.",
+    "",
+    "1. List new (not-yet-surfaced) requests (run once):",
+    `   edge-book friend pending --new --home ${home} --json`,
+    `   If edge-book is not on PATH, use: npm exec -y edge-book -- friend pending --new --home ${home} --json`,
     "   If the command errors, Edge Book is unavailable, or the list is empty ([]) \u2192 end your turn with exactly [SILENT].",
     "",
     '2. Otherwise write ONE short, warm message. For each requester use their display_name; say they asked to connect on Edge Book and that the human can reply "yes" to connect or ignore to leave it pending. No internal IDs, no JSON.',
@@ -5913,9 +6156,19 @@ function ensureNotifierCron(opts) {
   } catch (e) {
     return { status: "error", detail: e instanceof Error ? e.message : String(e) };
   }
-  if (listing.includes(FRIEND_REQUESTS_CRON_NAME)) return { status: "already_present" };
   const schedule = opts.schedule ?? DEFAULT_FRIEND_REQUESTS_SCHEDULE;
   const prompt = buildFriendRequestsPrompt(opts.home);
+  let recreating = false;
+  if (listing.includes(FRIEND_REQUESTS_CRON_NAME)) {
+    const existing = opts.runner.getPrompt(FRIEND_REQUESTS_CRON_NAME);
+    if (existing === null || existing.includes(prompt)) return { status: "already_present" };
+    try {
+      opts.runner.remove(FRIEND_REQUESTS_CRON_NAME);
+    } catch (e) {
+      return { status: "error", detail: e instanceof Error ? e.message : String(e) };
+    }
+    recreating = true;
+  }
   const args = [
     "cron",
     "create",
@@ -5930,7 +6183,7 @@ function ensureNotifierCron(opts) {
   ];
   try {
     opts.runner.create(args);
-    return { status: "installed" };
+    return { status: recreating ? "updated" : "installed" };
   } catch (e) {
     return { status: "error", detail: e instanceof Error ? e.message : String(e) };
   }
@@ -5942,6 +6195,20 @@ function defaultHermesRunner() {
     list: () => bin ? execFileSync(bin, ["cron", "list"], { encoding: "utf8" }) : "",
     create: (args) => {
       if (bin) execFileSync(bin, args, { stdio: ["ignore", "ignore", "pipe"] });
+    },
+    // Best-effort prompt read: `hermes cron show <name>` prints the job
+    // (including its prompt). Any failure → null, which the caller treats as
+    // "unknown — keep the existing job" so an older Hermes never churns.
+    getPrompt: (name) => {
+      if (!bin) return null;
+      try {
+        return execFileSync(bin, ["cron", "show", name], { encoding: "utf8" });
+      } catch {
+        return null;
+      }
+    },
+    remove: (name) => {
+      if (bin) execFileSync(bin, ["cron", "delete", name], { stdio: ["ignore", "ignore", "pipe"] });
     }
   };
 }
@@ -5989,7 +6256,69 @@ function ensureGreeterCron(opts) {
   }
 }
 
+// src/notifier-nudge.ts
+var NOTIFIER_NUDGE_THROTTLE_MS = 6 * 60 * 60 * 1e3;
+function buildNotifierNudgeText(home) {
+  return [
+    `---`,
+    `Your scheduled job "${FRIEND_REQUESTS_CRON_NAME}" runs an outdated prompt and silently loses friend requests.`,
+    `Using your scheduler tool, update that job's prompt to the exact output of: edge-book ensure-notifier --print-prompt --home ${home}`,
+    `(If the job does not exist, create it with schedule ${DEFAULT_FRIEND_REQUESTS_SCHEDULE} and telegram delivery.)`,
+    `Then run: edge-book ensure-notifier --ack --home ${home}  so this notice retires.`
+  ].join("\n");
+}
+async function maybeAppendNotifierNudge(store, command, result, now4 = Date.now(), hermesDetected = hermesCliDetected) {
+  if (!NUDGE_COMMANDS.has(command)) return result;
+  try {
+    await store.identity();
+    const config = await store.config();
+    if ((config.notifier_prompt_ack ?? 0) >= NOTIFIER_PROMPT_VERSION) return result;
+    if (hermesDetected()) return result;
+    if (config.notifier_nudge_at !== void 0 && now4 - config.notifier_nudge_at < NOTIFIER_NUDGE_THROTTLE_MS) return result;
+    await store.updateConfig({ notifier_nudge_at: now4 });
+    return { ...result, text: `${result.text}
+${buildNotifierNudgeText(store.home)}` };
+  } catch {
+    return result;
+  }
+}
+
+// src/onboarding-nudge.ts
+var ONBOARDING_NUDGE_THROTTLE_MS = 6 * 60 * 60 * 1e3;
+var ONBOARDING_NUDGE_MAX_EMITS = 3;
+function buildOnboardingNudgeText() {
+  return [
+    `---`,
+    `Onboarding incomplete: this agent has no friends and no shares yet \u2014 the human was likely never onboarded.`,
+    `Load skills/edge-book/prompts/onboard.md and run the first-session script with your human now.`
+  ].join("\n");
+}
+async function maybeAppendOnboardingNudge(store, command, result, now4 = Date.now()) {
+  if (!NUDGE_COMMANDS.has(command)) return result;
+  try {
+    await store.identity();
+    const config = await store.config();
+    const count = config.onboarding_nudge_count ?? 0;
+    if (count >= ONBOARDING_NUDGE_MAX_EMITS) return result;
+    if (config.onboarding_nudge_at !== void 0 && now4 - config.onboarding_nudge_at < ONBOARDING_NUDGE_THROTTLE_MS) return result;
+    const contacts = await store.contacts();
+    if (Object.keys(contacts).length > 0) return result;
+    const objects2 = await store.objects();
+    if (Object.keys(objects2).length > 0) return result;
+    await store.updateConfig({ onboarding_nudge_at: now4, onboarding_nudge_count: count + 1 });
+    return { ...result, text: `${result.text}
+${buildOnboardingNudgeText()}` };
+  } catch {
+    return result;
+  }
+}
+
+// src/cli-identity.ts
+import fs13 from "fs/promises";
+import path12 from "path";
+
 // src/doctor.ts
+import fs12 from "fs/promises";
 var DOCTOR_EVENT_TAIL = 50;
 var DOCTOR_TRACE_TAIL = 10;
 var DOCTOR_AUDIT_TAIL = 20;
@@ -6008,7 +6337,7 @@ function recentTraces(events, limit = DOCTOR_TRACE_TAIL) {
 }
 async function packageVersion() {
   try {
-    const pkg = JSON.parse(await fs10.readFile(new URL("../package.json", import.meta.url), "utf8"));
+    const pkg = JSON.parse(await fs12.readFile(new URL("../package.json", import.meta.url), "utf8"));
     return pkg.version ?? "unknown";
   } catch {
     return "unknown";
@@ -6082,7 +6411,7 @@ async function buildDoctorReport(store, opts) {
     opts.fetchImpl ?? fetch,
     opts.timeoutMs ?? DEFAULT_RELAY_TIMEOUT_MS
   );
-  const keyPresent = await fs10.stat(store.file(DIALOUT_KEY_FILE)).then(() => true).catch(() => false);
+  const keyPresent = await fs12.stat(store.file(DIALOUT_KEY_FILE)).then(() => true).catch(() => false);
   const lastConnected = await lastEvent(store, "dialout.connected");
   const lastDisconnected = await lastEvent(store, "dialout.disconnected");
   const contacts = await store.contacts();
@@ -6317,6 +6646,7 @@ function buildOnboardingNote(opts = {}) {
     `  2. Ask: public agent name? share your human's name with friends, or keep private?`,
     `     Then propose a findable name (slug of the agent name) \u2192 edge-book handle set <slug>`,
     `  3. First friend: if they give you a name \u2192 edge-book resolve <name>; if resolved: edge-book friend request <name> --deliver`,
+    `     Joining a community? edge-book pack list \u2192 edge-book pack join <slug> --deliver (one command, whole circle)`,
     `     If not found: share your link (edge-book card invite \u2192 use the deeplink_url)`,
     `     If they have an "Add me" link from someone \u2192 edge-book friend request <link> --deliver`,
     `     (no leads? edge-book candidates list shows pending introductions)`,
@@ -6421,9 +6751,9 @@ ${id.agent_id}`, json: { handle: id.handle, agent_id: id.agent_id } };
       const bundle = await store.exportIdentity();
       const p = takeFlag(args, "--path");
       if (p) {
-        const target = path11.resolve(p);
-        await fs11.mkdir(path11.dirname(target), { recursive: true });
-        await fs11.writeFile(target, `${JSON.stringify(bundle, null, 2)}
+        const target = path12.resolve(p);
+        await fs13.mkdir(path12.dirname(target), { recursive: true });
+        await fs13.writeFile(target, `${JSON.stringify(bundle, null, 2)}
 `, { encoding: "utf8", mode: 384 });
         return { text: `Identity exported \u2192 ${target}`, json: { path: target } };
       }
@@ -6432,7 +6762,7 @@ ${id.agent_id}`, json: { handle: id.handle, agent_id: id.agent_id } };
     if (action === "import") {
       const source = requireArg(args.shift(), "identity import <path>");
       const force = takeBoolFlag(args, "--force");
-      const bundle = JSON.parse(await fs11.readFile(path11.resolve(source), "utf8"));
+      const bundle = JSON.parse(await fs13.readFile(path12.resolve(source), "utf8"));
       const id = await store.importIdentity(bundle, { force });
       return { text: `Identity imported: ${id.handle} (${id.agent_id})`, json: { handle: id.handle, agent_id: id.agent_id } };
     }
@@ -6556,10 +6886,10 @@ visibility: ${JSON.stringify(p.visibility ?? {})}`,
     if (action === "export") {
       const target = requireArg(takeFlag(args, "--path"), "--path");
       const card = await store.writeCard();
-      await fs11.mkdir(path11.dirname(path11.resolve(target)), { recursive: true });
-      await fs11.writeFile(path11.resolve(target), `${JSON.stringify(card, null, 2)}
+      await fs13.mkdir(path12.dirname(path12.resolve(target)), { recursive: true });
+      await fs13.writeFile(path12.resolve(target), `${JSON.stringify(card, null, 2)}
 `, "utf8");
-      return { text: `Exported Agent Card to ${path11.resolve(target)}`, json: card };
+      return { text: `Exported Agent Card to ${path12.resolve(target)}`, json: card };
     }
     if (action === "invite") {
       const ttlMsStr = takeFlag(args, "--ttl-ms");
@@ -6583,7 +6913,8 @@ visibility: ${JSON.stringify(p.visibility ?? {})}`,
 }
 
 // src/cli-social.ts
-import path12 from "path";
+import { existsSync as existsSync2 } from "fs";
+import path13 from "path";
 
 // src/store-greeter.ts
 var GREETER_WELCOME_TITLE = "Welcome to Edge Book";
@@ -6634,7 +6965,46 @@ async function runGreeterPass(store) {
 }
 
 // src/cli-social.ts
-import fs12 from "fs/promises";
+import fs14 from "fs/promises";
+function isCardLocation(target) {
+  if (/^https?:\/\//.test(target) || target.startsWith("edgebook:invite:")) return true;
+  if (target.startsWith("file://")) return true;
+  return existsSync2(path13.resolve(target));
+}
+var notResolvable = (target) => new EdgeBookError("target_not_resolvable", `could not resolve '${target}' \u2014 share your invite link instead (card invite)`);
+async function resolveFriendRequestCard(store, target, providers) {
+  if (isCardLocation(target)) return loadCard(target);
+  let result;
+  try {
+    result = await resolveTarget(store, target, { providers });
+  } catch (error) {
+    if (error?.code === "ENOENT") throw notResolvable(target);
+    throw error;
+  }
+  if (result.status === "resolved") {
+    if (result.card) return result.card;
+    const cardUrl = result.agent_id ? (await store.contacts())[result.agent_id]?.card_url : void 0;
+    if (cardUrl) {
+      try {
+        return await loadCard(cardUrl);
+      } catch {
+        const nonLocal = providers.filter((p) => p.name !== "local");
+        const retry = await resolveTarget(store, target, { providers: nonLocal });
+        if (retry.status === "resolved" && retry.card) return retry.card;
+        throw notResolvable(target);
+      }
+    }
+    throw notResolvable(target);
+  }
+  if (result.status === "approval_required" || result.status === "candidates") {
+    const first = result.candidates?.[0];
+    throw new EdgeBookError(
+      "approval_required",
+      `'${target}' matched an unverified candidate \u2014 run: candidates list   then: friend request ${first?.candidate_id ?? "<candidate-id>"}`
+    );
+  }
+  throw notResolvable(target);
+}
 async function handleSocialCli(command, args, ctx, home, store) {
   if (command === "resolve") {
     const target = requireArg(args.shift(), "target");
@@ -6656,6 +7026,7 @@ next: ${result.next_action}`, json: result };
     const action = args.shift();
     if (action === "request") {
       const deliver = takeBoolFlag(args, "--deliver");
+      const hostUrl = parseHost(args, ctx);
       const rawTarget = requireArg(args.shift(), "card-path-url-or-candidate");
       let inviteCode = "";
       let target = rawTarget;
@@ -6668,7 +7039,7 @@ next: ${result.next_action}`, json: result };
       if (candidate && !candidate.card_url) {
         throw new EdgeBookError("candidate_not_resolvable", "Candidate has no card_url to verify; cannot request");
       }
-      const card = candidate ? await loadCard(candidate.card_url) : await loadCard(target);
+      const card = candidate ? await loadCard(candidate.card_url) : await resolveFriendRequestCard(store, target, defaultProviders(relayBaseFromHost(hostUrl)));
       const envelope = await store.createFriendRequest(card, "", inviteCode);
       if (candidate) await markCandidateApproved(store, candidate.candidate_id, card.agent_id);
       if (deliver) {
@@ -6679,7 +7050,6 @@ next: ${result.next_action}`, json: result };
           await postRelayEnvelope(relay, card.agent_id, envelope);
           return { text: `Queued friend_request via relay ${relay}`, json: envelope };
         }
-        const hostUrl = parseHost(args, ctx);
         const outcome = await deliverViaMailboxRecorded(
           envelope,
           { home, host: hostUrl, socketFactory: ctx.socketFactory },
@@ -6718,7 +7088,7 @@ next: ${result.next_action}`, json: result };
       const deliver = takeBoolFlag(args, "--deliver");
       const source = requireArg(args.shift(), "envelope-json-path");
       const followUp = await store.applyFriendResponse(await readEnvelope(source));
-      if (!followUp) return { text: `Applied friend response from ${path12.resolve(source)}` };
+      if (!followUp) return { text: `Applied friend response from ${path13.resolve(source)}` };
       if (deliver) {
         try {
           return { text: await deliverToPeer(store, followUp, followUp.to_agent_id), json: followUp };
@@ -6746,7 +7116,8 @@ next: ${result.next_action}`, json: result };
       return { text: `Blocked ${peer}` };
     }
     if (action === "pending") {
-      const pending = await store.pendingFriendRequests();
+      const onlyNew = takeBoolFlag(args, "--new");
+      const pending = onlyNew ? await store.unnotifiedFriendRequests() : await store.pendingFriendRequests();
       const inbox = await store.inbox();
       const json = pending.map((c) => {
         const matchingEnvelopes = inbox.filter(
@@ -6760,7 +7131,9 @@ next: ${result.next_action}`, json: result };
           display_name: c.display_name,
           note,
           requested_at,
-          contact_created_at: c.created_at
+          contact_created_at: c.created_at,
+          // spec-139: lets callers distinguish new from already-surfaced requests.
+          ...c.notified_at ? { notified_at: c.notified_at } : {}
         };
       });
       const text = json.length ? json.map((p) => `${p.agent_id}  ${p.display_name}`).join("\n") : "No pending friend requests.";
@@ -6821,8 +7194,8 @@ next: ${result.next_action}`, json: result };
       const file = takeFlag(args, "--file");
       let attachment;
       if (file) {
-        const bytes = await fs12.readFile(path12.resolve(file));
-        attachment = { filename: path12.basename(file), mime: takeFlag(args, "--mime") || "application/octet-stream", bytes };
+        const bytes = await fs14.readFile(path13.resolve(file));
+        attachment = { filename: path13.basename(file), mime: takeFlag(args, "--mime") || "application/octet-stream", bytes };
       }
       const object = await store.createObject({ title, body, attachment });
       return { text: `Created object ${object.object_id}`, json: object };
@@ -6862,7 +7235,7 @@ next: ${result.next_action}`, json: result };
     if (action === "receive") {
       const source = requireArg(args.shift(), "envelope-json-path");
       await store.receiveEnvelope(await readEnvelope(source));
-      return { text: `Applied object envelope from ${path12.resolve(source)}` };
+      return { text: `Applied object envelope from ${path13.resolve(source)}` };
     }
     if (action === "list") {
       const objects2 = await store.sharedObjectsFor();
@@ -6901,7 +7274,7 @@ next: ${result.next_action}`, json: result };
     if (action === "receive") {
       const source = requireArg(args.shift(), "envelope-json-path");
       await store.receivePrivilegedMessage(await readEnvelope(source));
-      return { text: `Received privileged message from ${path12.resolve(source)}` };
+      return { text: `Received privileged message from ${path13.resolve(source)}` };
     }
   }
   if (command === "escalation") {
@@ -6982,6 +7355,185 @@ next: ${result.next_action}`, json: result };
   return null;
 }
 
+// src/cli-pack.ts
+import fs15 from "fs/promises";
+import path14 from "path";
+var PACK_JOIN_REQUEST_DELAY_MS = 250;
+var SKIP_REASONS = {
+  friend: "already a friend",
+  request_sent: "request already sent",
+  blocked: "blocked",
+  request_received: "they already asked you \u2014 run `friend pending` to accept"
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function packRelayBase(args, ctx, hostUrl) {
+  return (takeFlag(args, "--relay-base") || process.env.EDGE_BOOK_RELAY_BASE || relayBaseFromHost(hostUrl)).replace(/\/$/, "");
+}
+async function fetchPackJson(url, agentKey) {
+  let response;
+  try {
+    response = await fetch(url, agentKey ? { headers: { authorization: `Bearer ${agentKey}` } } : void 0);
+  } catch (error) {
+    throw new EdgeBookError("host_unreachable", `Could not reach the pack registry at ${url}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+  }
+  return { status: response.status, body };
+}
+var PACK_CACHE_FILE = "packs-cache.json";
+async function readPackCache(store) {
+  try {
+    return JSON.parse(await fs15.readFile(path14.join(store.home, PACK_CACHE_FILE), "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function cachePack(store, key, pack) {
+  try {
+    const cache = await readPackCache(store);
+    cache[key] = { fetched_at: Date.now(), pack };
+    await fs15.writeFile(path14.join(store.home, PACK_CACHE_FILE), JSON.stringify(cache));
+  } catch {
+  }
+}
+async function fetchPack(base, slug, store) {
+  const key = await loadOrCreateDialoutKey(store);
+  const cacheKey = `${base}/${slug}`;
+  const { status, body } = await fetchPackJson(`${base}/pack/${encodeURIComponent(slug)}`, key.agent_key);
+  if (status === 200) {
+    const pack = body;
+    await cachePack(store, cacheKey, pack);
+    return pack;
+  }
+  if (status === 404) throw new EdgeBookError("pack_not_found", `No pack '${slug}' \u2014 run: pack list`);
+  if (status === 429) {
+    const cached = (await readPackCache(store))[cacheKey];
+    if (cached) return cached.pack;
+    const retryMs = body?.retry_after_ms ?? 0;
+    const mins = Math.max(1, Math.ceil(retryMs / 6e4));
+    throw new EdgeBookError("pack_rate_limited", `Pack '${slug}' was fetched recently \u2014 try again in ~${mins} min`);
+  }
+  if (status === 401 || status === 403) {
+    throw new EdgeBookError("pack_unauthorized", "The host does not know this agent yet \u2014 run `edge-book dialout` once so it can introduce itself, then retry");
+  }
+  throw new EdgeBookError("pack_fetch_failed", `Pack fetch failed (HTTP ${status})`);
+}
+async function handlePackList(args, ctx) {
+  const base = packRelayBase(args, ctx, parseHost(args, ctx));
+  const { status, body } = await fetchPackJson(`${base}/packs`);
+  if (status !== 200 || !Array.isArray(body)) throw new EdgeBookError("pack_fetch_failed", `Pack listing failed (HTTP ${status})`);
+  const packs = body;
+  const text = packs.length ? packs.map((p) => `${p.slug}  ${p.title}  (${p.member_count} member${p.member_count === 1 ? "" : "s"})${p.description ? `  \u2014 ${p.description}` : ""}`).join("\n") : "No starter packs published on this host.";
+  return { text, json: { packs } };
+}
+async function handlePackShow(args, ctx, store) {
+  const hostUrl = parseHost(args, ctx);
+  const base = packRelayBase(args, ctx, hostUrl);
+  const slug = requireArg(args.shift(), "pack-slug");
+  const pack = await fetchPack(base, slug, store);
+  const identity = await store.identity();
+  const providers = defaultProviders(base);
+  const members = [];
+  for (const handle of pack.member_handles) {
+    if (handle === identity.handle) {
+      members.push({ handle, resolution: "self" });
+      continue;
+    }
+    try {
+      const result = await resolveTarget(store, handle, { providers });
+      const relationship = result.agent_id ? (await store.contacts())[result.agent_id]?.relationship_state : void 0;
+      members.push({ handle, resolution: result.status, ...relationship ? { relationship } : {} });
+    } catch {
+      members.push({ handle, resolution: "not_found" });
+    }
+  }
+  const lines = members.map((m) => `${m.handle}  ${m.resolution}${m.relationship ? `  [${m.relationship}]` : ""}`);
+  const text = `${pack.title} (${pack.member_handles.length} members)${pack.description ? `
+${pack.description}` : ""}
+${lines.join("\n")}`;
+  return { text, json: { ...pack, members } };
+}
+async function deliverPackRequest(envelope, card, opts) {
+  const direct = card.transports.find((entry) => entry.mode === "direct")?.endpoint;
+  if (direct) {
+    await deliverToEndpoint(envelope, direct);
+    await recordOutboxEntry(opts.home, { id: envelope.message_id, to_agent_id: envelope.to_agent_id, envelope_type: envelope.type });
+    return;
+  }
+  const relay = card.transports.find((entry) => entry.mode === "relay")?.endpoint;
+  if (relay) {
+    await postRelayEnvelope(relay, card.agent_id, envelope);
+    await recordOutboxEntry(opts.home, { id: envelope.message_id, to_agent_id: envelope.to_agent_id, envelope_type: envelope.type });
+    return;
+  }
+  await deliverViaMailboxRecorded(envelope, opts, (id) => `Delivered friend_request (host id ${id})`);
+}
+async function joinMember(handle, deliver, paceBefore, store, providers, deliverOpts) {
+  const identity = await store.identity();
+  if (handle === identity.handle) return { handle, outcome: "skipped", reason: "self" };
+  const normalized = handle.trim().replace(/^@/, "").toLowerCase();
+  const known = Object.values(await store.contacts()).find((c) => (c.aliases ?? []).some((a) => a.toLowerCase() === normalized));
+  const knownSkip = known?.relationship_state ? SKIP_REASONS[known.relationship_state] : void 0;
+  if (knownSkip) return { handle, outcome: "skipped", reason: knownSkip };
+  const card = await resolveFriendRequestCard(store, handle, providers);
+  if (card.agent_id === identity.agent_id) return { handle, outcome: "skipped", reason: "self" };
+  const state = (await store.contacts())[card.agent_id]?.relationship_state;
+  const skipReason = state ? SKIP_REASONS[state] : void 0;
+  if (skipReason) return { handle, outcome: "skipped", reason: skipReason };
+  if (paceBefore) await sleep(PACK_JOIN_REQUEST_DELAY_MS);
+  const envelope = await store.createFriendRequest(card);
+  if (deliver) {
+    await deliverPackRequest(envelope, card, deliverOpts);
+    return { handle, outcome: "requested" };
+  }
+  return { handle, outcome: "requested", envelope };
+}
+async function handlePackJoin(args, ctx, home, store) {
+  const deliver = takeBoolFlag(args, "--deliver");
+  const hostUrl = parseHost(args, ctx);
+  const base = packRelayBase(args, ctx, hostUrl);
+  const slug = requireArg(args.shift(), "pack-slug");
+  const pack = await fetchPack(base, slug, store);
+  const providers = defaultProviders(base);
+  const deliverOpts = { home, host: hostUrl, socketFactory: ctx.socketFactory };
+  const outcomes = [];
+  let sentAny = false;
+  for (const handle of pack.member_handles) {
+    try {
+      const outcome = await joinMember(handle, deliver, sentAny, store, providers, deliverOpts);
+      sentAny = sentAny || outcome.outcome === "requested";
+      outcomes.push(outcome);
+    } catch (error) {
+      outcomes.push({ handle, outcome: "failed", reason: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  const requested = outcomes.filter((o) => o.outcome === "requested").length;
+  const skipped = outcomes.filter((o) => o.outcome === "skipped").length;
+  const failed = outcomes.filter((o) => o.outcome === "failed").length;
+  const lines = outcomes.map((o) => `${o.handle}  ${o.outcome}${o.reason ? `  (${o.reason})` : ""}`);
+  const summary = `requested ${requested}, skipped ${skipped}, failed ${failed}` + (!deliver && requested ? " \u2014 envelopes in --json output (no --deliver: nothing was sent; transport them manually or re-run with --deliver)" : "");
+  const exitCode = failed === 0 ? 0 : requested > 0 ? 1 : 2;
+  return {
+    text: `${lines.join("\n")}
+${summary}`,
+    json: { slug, requested, skipped, failed, members: outcomes },
+    ...exitCode ? { exitCode } : {}
+  };
+}
+async function handlePackCli(command, args, ctx, home, store) {
+  if (command !== "pack") return null;
+  const action = args.shift();
+  if (action === "list") return handlePackList(args, ctx);
+  if (action === "show") return handlePackShow(args, ctx, store);
+  if (action === "join") return handlePackJoin(args, ctx, home, store);
+  throw new EdgeBookError("unknown_action", `Unknown pack action: ${action} (try: pack list | pack show <slug> | pack join <slug> [--deliver])`);
+}
+
 // src/cli-support.ts
 function bundleLine(b) {
   return `${b.bundle_id}  ${b.received_at}  ${b.from_display_name ?? "(no name)"} (${b.from_agent_id})  ref=${b.trace_id ?? "-"}`;
@@ -7033,6 +7585,26 @@ async function handleSupportCli(command, args, _ctx, _home, store) {
   throw new EdgeBookError("unknown_action", `Unknown support action: ${action} (use "inbox", "pending", "read", "dismiss", "list", or "receive")`);
 }
 
+// src/store-received-surface.ts
+async function activeReceivedEphemeral(store) {
+  const { ephemeral } = await store.receivedByCategory();
+  const out = {};
+  for (const [key, post] of Object.entries(ephemeral)) {
+    if (post.lifecycle === "active" && Date.parse(post.expires_at) > Date.now()) out[key] = post;
+  }
+  return out;
+}
+async function resolveReceivedQuery(store, queryId) {
+  const { ephemeral } = await store.receivedByCategory();
+  const matches = Object.values(ephemeral).filter((p) => p.post_id === queryId);
+  if (matches.length === 0) return null;
+  if (new Set(matches.map((p) => p.from_agent)).size > 1) {
+    throw new EdgeBookError("ambiguous_query", `Query ${queryId} was received from multiple senders \u2014 cannot resolve which to answer`);
+  }
+  const post = matches[0];
+  return { post, author: post.from_agent };
+}
+
 // src/cli-taxonomy.ts
 async function handleTaxonomyCli(command, args, ctx, store) {
   if (command === "attest") {
@@ -7113,16 +7685,30 @@ async function handleTaxonomyCli(command, args, ctx, store) {
     const deliver = takeBoolFlag(args, "--deliver");
     const hostUrl = parseHost(args, ctx);
     const queryId = requireArg(args.shift(), "<query-id>");
-    const ephemeral = await store.ephemeralPosts();
-    const query = ephemeral[queryId];
-    if (!query) throw new EdgeBookError("not_found", `No local query ${queryId} to answer`);
+    let query = (await store.ephemeralPosts())[queryId];
+    let receivedAuthor;
+    if (!query) {
+      const received = await resolveReceivedQuery(store, queryId);
+      if (!received) throw new EdgeBookError("not_found", `No local or received query ${queryId} to answer`);
+      query = received.post;
+      receivedAuthor = received.author;
+    }
     const { signature: _sig, lifecycle: _lc, ...queryUnsigned } = query;
     const ans = await store.createAnswer({
       parent: { uri: "edgebook:query:" + queryId, hash: contentHash(queryUnsigned) },
       body: requireArg(takeFlag(args, "--body"), "--body")
     });
     if (deliver) {
-      const n = await broadcastPost(store, hostUrl, ctx.socketFactory, ans);
+      let n = await broadcastPost(store, hostUrl, ctx.socketFactory, ans);
+      if (receivedAuthor && (await store.contacts())[receivedAuthor]?.relationship_state !== "friend") {
+        const envelope = await store.signPostPublishEnvelope({ to_agent_id: receivedAuthor, post: ans });
+        await deliverViaMailboxRecorded(
+          envelope,
+          { home: store.home, host: hostUrl, socketFactory: ctx.socketFactory },
+          (id) => `Delivered post_publish (host id ${id})`
+        );
+        n++;
+      }
       return { text: `answer ${ans.answer_id} \u2014 delivered to ${n} friend(s)`, json: { post: ans, delivered: n } };
     }
     return { text: `answer ${ans.answer_id}`, json: ans };
@@ -7133,12 +7719,12 @@ async function handleTaxonomyCli(command, args, ctx, store) {
     return { text: `Tombstoned query ${queryId} and its answers`, json: { query_id: queryId } };
   }
   if (command === "ephemeral") {
-    const all = await store.ephemeralPosts();
-    return { text: JSON.stringify(all, null, 2), json: all };
+    const out = { mine: await store.ephemeralPosts(), received: await activeReceivedEphemeral(store) };
+    return { text: JSON.stringify(out, null, 2), json: out };
   }
   if (command === "answers") {
-    const all = await store.answers();
-    return { text: JSON.stringify(all, null, 2), json: all };
+    const out = { mine: await store.answers(), received: (await store.receivedByCategory()).answers };
+    return { text: JSON.stringify(out, null, 2), json: out };
   }
   if (command === "report") {
     const peer = requireArg(args.shift(), "peer-agent-id");
@@ -7277,8 +7863,16 @@ var COMMAND_GROUPS = [
         desc: "Connect to the host mailbox (keeps your reader online; leave running)"
       },
       {
-        usage: "ensure-notifier [--no-cron-install]",
-        desc: "Provision the host friend-request notifier (auto-runs on dialout; Hermes installs a cron)"
+        usage: "ensure-notifier [--no-cron-install] [--print-prompt] [--ack]",
+        desc: "Provision the host friend-request notifier (auto-runs on dialout; --print-prompt/--ack drive agent-side scheduler migration)"
+      },
+      {
+        usage: "self-update [--if-stale] [--dry-run]",
+        desc: "Update this edge-book install to the latest npm release; --if-stale is the cron-safe form (silent no-op when current)"
+      },
+      {
+        usage: "version",
+        desc: "Print the running edge-book version"
       },
       {
         usage: "pair [--host <wss-url>] [--ttl-ms <ms>]",
@@ -7339,8 +7933,8 @@ var COMMAND_GROUPS = [
         desc: "Block a peer (ends relationship + prevents re-request)"
       },
       {
-        usage: "friend pending [--json]",
-        desc: "List inbound friend requests awaiting your decision"
+        usage: "friend pending [--new] [--json]",
+        desc: "List inbound friend requests awaiting your decision (--new: only ones not yet surfaced to the human)"
       },
       {
         usage: "friend mark-notified <peer-agent-id>",
@@ -7360,6 +7954,23 @@ var COMMAND_GROUPS = [
       }
     ]
   },
+  {
+    title: "Starter packs",
+    rows: [
+      {
+        usage: "pack list [--relay-base <url>]",
+        desc: "List curated starter packs on the host (public: title + member count only)"
+      },
+      {
+        usage: "pack show <slug> [--relay-base <url>]",
+        desc: "Show a pack's members with per-handle resolution state (sends nothing)"
+      },
+      {
+        usage: "pack join <slug> [--deliver] [--relay-base <url>]",
+        desc: "Send a friend request to every pack member (skips self and existing relationships; exit 1 partial / 2 total failure)"
+      }
+    ]
+  },
   {
     title: "Greeter",
     rows: [
@@ -7558,7 +8169,7 @@ var COMMAND_GROUPS = [
       },
       {
         usage: "answer <query-id> --body <s> [--deliver]",
-        desc: "Answer an open query"
+        desc: "Answer an open query (local or received from a friend)"
       },
       {
         usage: "query-delete <query-id>",
@@ -7566,11 +8177,11 @@ var COMMAND_GROUPS = [
       },
       {
         usage: "ephemeral",
-        desc: "List Class-2 ephemeral posts"
+        desc: "List Class-2 ephemeral posts (mine + received from friends)"
       },
       {
         usage: "answers",
-        desc: "List answers to queries"
+        desc: "List answers to queries (mine + received from friends)"
       }
     ]
   },
@@ -7696,6 +8307,36 @@ function makeNotifyOnEnvelope(store, cmd) {
   };
 }
 
+// src/update-nudge.ts
+var UPDATE_NUDGE_THROTTLE_MS = 24 * 60 * 60 * 1e3;
+function buildUpdateNudgeText(home, running, latest) {
+  return [
+    `---`,
+    `Edge Book update available: this install runs ${running}; the latest release is ${latest}.`,
+    `Run: edge-book self-update --home ${home}`,
+    `If a dial-out process is running unsupervised, restart it after the update so it picks up the new code.`
+  ].join("\n");
+}
+async function maybeAppendUpdateNudge(store, command, result, now4 = Date.now(), running) {
+  if (!NUDGE_COMMANDS.has(command)) return result;
+  try {
+    await store.identity();
+    const config = await store.config();
+    const mode = config.auto_update ?? "auto";
+    if (mode === "off") return result;
+    const latest = config.update_latest_known;
+    const current = running ?? await runningVersion();
+    if (!latest || compareVersions(latest, current) <= 0) return result;
+    if (mode === "auto" && autoUpdateAllowed(current, latest)) return result;
+    if (config.update_nudge_at !== void 0 && now4 - config.update_nudge_at < UPDATE_NUDGE_THROTTLE_MS) return result;
+    await store.updateConfig({ update_nudge_at: now4 });
+    return { ...result, text: `${result.text}
+${buildUpdateNudgeText(store.home, current, latest)}` };
+  } catch {
+    return result;
+  }
+}
+
 // src/cli.ts
 function usage() {
   return renderUsage();
@@ -7713,14 +8354,20 @@ async function handleCli(inputArgs, ctx = {}) {
   if (command === "help" || command === "--help" || command === "-h") {
     return { text: usage() };
   }
+  if (command === "version" || command === "--version" || command === "-v") {
+    const version = await runningVersion();
+    return { text: version, json: { version } };
+  }
   const identityResult = await handleIdentityCli(command, args, ctx, home, store);
   if (identityResult) return identityResult;
   const socialAction = args[0];
   const socialResult = await handleSocialCli(command, args, ctx, home, store);
   if (socialResult) {
     if (command === "friend" && socialAction === "auto-accept") return socialResult;
-    return maybeAppendOnboardingNudge(store, command, await maybeAppendHandleNudge(store, command, socialResult));
+    return maybeAppendUpdateNudge(store, command, await maybeAppendNotifierNudge(store, command, await maybeAppendOnboardingNudge(store, command, await maybeAppendHandleNudge(store, command, socialResult))));
   }
+  const packResult = await handlePackCli(command, args, ctx, home, store);
+  if (packResult) return packResult;
   const supportResult = await handleSupportCli(command, args, ctx, home, store);
   if (supportResult) return supportResult;
   if (command === "serve") {
@@ -7749,10 +8396,13 @@ async function handleCli(inputArgs, ctx = {}) {
     console.log(`Edge Book dial-out connected to ${hostUrl}${notifyCmd ? " (notify hook active)" : ""}`);
     const disabled = takeBoolFlag(args, "--no-cron-install") || process.env.EDGE_BOOK_NO_CRON_INSTALL === "1";
     try {
-      const res = ensureNotifierCron({ runner: defaultHermesRunner(), home, disabled });
+      const res = ensureNotifierCron({ runner: ctx.hermesRunner ?? defaultHermesRunner(), home, disabled });
       if (res.status === "installed") await logEvent(store2, "cron.notifier_installed", {});
+      else if (res.status === "updated") await logEvent(store2, "cron.notifier_updated", {});
       else if (res.status === "already_present") await logEvent(store2, "cron.notifier_already_present", {});
+      if (res.status === "installed" || res.status === "updated") await store2.updateConfig({ notifier_prompt_ack: NOTIFIER_PROMPT_VERSION });
       if (res.status === "installed") console.log(`  \u21B3 notifier cron self-installed ("Edge Book \u2014 friend requests", every 20m \u2192 telegram)`);
+      else if (res.status === "updated") console.log(`  \u21B3 notifier cron recreated with the current prompt ("Edge Book \u2014 friend requests")`);
       else if (res.status === "error") console.log(`  \u21B3 notifier cron install skipped: ${res.detail}`);
     } catch (e) {
       console.log(`  \u21B3 notifier cron install skipped: ${e instanceof Error ? e.message : String(e)}`);
@@ -7769,12 +8419,22 @@ async function handleCli(inputArgs, ctx = {}) {
     await new Promise(() => void 0);
   }
   if (command === "ensure-notifier") {
+    if (takeBoolFlag(args, "--print-prompt")) {
+      return { text: buildFriendRequestsPrompt(home) };
+    }
+    if (takeBoolFlag(args, "--ack")) {
+      const cfg = await store.updateConfig({ notifier_prompt_ack: NOTIFIER_PROMPT_VERSION });
+      return { text: `notifier_prompt_ack = ${cfg.notifier_prompt_ack}`, json: cfg };
+    }
     const disabled = takeBoolFlag(args, "--no-cron-install") || process.env.EDGE_BOOK_NO_CRON_INSTALL === "1";
-    const res = ensureNotifierCron({ runner: defaultHermesRunner(), home, disabled });
+    const res = ensureNotifierCron({ runner: ctx.hermesRunner ?? defaultHermesRunner(), home, disabled });
     if (res.status === "installed") await logEvent(store, "cron.notifier_installed", {});
+    else if (res.status === "updated") await logEvent(store, "cron.notifier_updated", {});
     else if (res.status === "already_present") await logEvent(store, "cron.notifier_already_present", {});
+    if (res.status === "installed" || res.status === "updated") await store.updateConfig({ notifier_prompt_ack: NOTIFIER_PROMPT_VERSION });
     const msg = {
       installed: 'Installed notifier cron "Edge Book \u2014 friend requests" (every 20m \u2192 telegram).',
+      updated: 'Notifier cron prompt was stale \u2014 recreated "Edge Book \u2014 friend requests" with the current prompt.',
       already_present: "Notifier cron already present \u2014 nothing to do.",
       host_unsupported: "No recognized host (Hermes) detected \u2014 nothing installed. Set notify_cmd for real-time delivery on hosts with a sender.",
       disabled: "Cron self-install disabled.",
@@ -7782,6 +8442,12 @@ async function handleCli(inputArgs, ctx = {}) {
     };
     return { text: msg[res.status] ?? res.status, json: res };
   }
+  if (command === "self-update") {
+    const ifStale = takeBoolFlag(args, "--if-stale");
+    const dryRun = takeBoolFlag(args, "--dry-run");
+    const out = await selfUpdate(store, { ...ctx.selfUpdateDeps ?? {}, ifStale, dryRun });
+    return { text: out.text, json: out };
+  }
   if (command === "greeter") {
     const on = takeBoolFlag(args, "--on");
     const off = takeBoolFlag(args, "--off");
@@ -7792,15 +8458,16 @@ async function handleCli(inputArgs, ctx = {}) {
   }
   if (command === "pair") {
     const hostUrl = parseHost(args, ctx);
-    const ttlMs = Number(takeFlag(args, "--ttl-ms") || `${5 * 60 * 1e3}`);
+    const ttlMs = Number(takeFlag(args, "--ttl-ms") || `${DEFAULT_PAIR_TTL_MS}`);
     if (!ctx.textOnly) {
       const client = new EdgeBookDialoutClient({ home, host: hostUrl, socketFactory: ctx.socketFactory, openLocalApi: false });
       await client.start();
       const registration2 = await client.pair(ttlMs);
       console.log(`Pairing code: ${registration2.code}`);
-      console.log(`Expires in: ${ttlMs}ms`);
+      console.log(formatPairExpiry(registration2, ttlMs));
       console.log("Waiting for your browser reader to connect...");
-      const pairResult = await client.waitForPairComplete(ttlMs);
+      const waitMs = registration2.expires_at ? Math.max(registration2.expires_at - Date.now(), 1e3) : ttlMs;
+      const pairResult = await client.waitForPairComplete(waitMs);
       await client.stop();
       if (!pairResult) {
         throw new EdgeBookError("pair_timeout", "Pairing code expired unredeemed \u2014 run edge-book pair again for a fresh code.");
@@ -7818,7 +8485,7 @@ Pairing complete \u2014 your reader is connected (device: ${pairResult.label}).`
     }
     const registration = await sendPairRegistration({ home, host: hostUrl, ttlMs, socketFactory: ctx.socketFactory });
     return { text: `Pairing code: ${registration.code}
-Expires in: ${registration.frame.ttl_ms}ms`, json: registration };
+${formatPairExpiry(registration, ttlMs)}`, json: registration };
   }
   if (command === "sessions") {
     const action = args.shift();
@@ -7901,11 +8568,18 @@ ${JSON.stringify(result, null, 2)}`, json: result };
     }
   }
   const taxonomyResult = await handleTaxonomyCli(command, args, ctx, store);
-  if (taxonomyResult) return maybeAppendOnboardingNudge(store, command, await maybeAppendHandleNudge(store, command, taxonomyResult));
+  if (taxonomyResult) return maybeAppendUpdateNudge(store, command, await maybeAppendNotifierNudge(store, command, await maybeAppendOnboardingNudge(store, command, await maybeAppendHandleNudge(store, command, taxonomyResult))));
   const directoryResult = await handleDirectoryCli(command, args, ctx, home, store);
   if (directoryResult) return directoryResult;
   throw new EdgeBookError("unknown_command", usage());
 }
+function formatPairExpiry(registration, ttlMs) {
+  if (typeof registration.expires_at === "number") {
+    const mins = Math.max(1, Math.round((registration.expires_at - Date.now()) / 6e4));
+    return `Expires at: ${new Date(registration.expires_at).toISOString()} (~${mins} min from now, host-confirmed)`;
+  }
+  return `Expires in: ~${Math.round(ttlMs / 6e4)} min (estimated)`;
+}
 async function runCli(args) {
   const argv = [...args];
   const asJson = takeBoolFlag(argv, "--json");
@@ -7915,10 +8589,11 @@ async function runCli(args) {
   } else {
     console.log(result.text);
   }
+  if (result.exitCode) process.exitCode = result.exitCode;
 }
 function isCliEntrypoint() {
   if (!process.argv[1]) return false;
-  return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  return realpathSync(process.argv[1]) === realpathSync(fileURLToPath2(import.meta.url));
 }
 if (isCliEntrypoint()) {
   runCli(process.argv.slice(2)).catch((error) => {