pactive 0.0.0-stage → 0.0.2-alpha.1

package/src/core/doctor.mjs

@@ -0,0 +1,143 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { NOT_IMPLEMENTED } from './errors.mjs';
+import { ledger } from './lineage.mjs';
+import { resolvePaths } from './paths.mjs';
+import { loadState } from './state.mjs';
+
+const STALE_LOCK_MS = 30000;
+const PEER_TTL_MS = 120000;
+const CLOSED_EVENTS = ['outcome', 'closed', 'settled'];
+
+/**
+ * Read only health report. It never reads credentials and never writes anything.
+ * Host probing is the caller's job: without ctx.hosts the report says so.
+ */
+export async function doctor(ctx = {}) {
+  const env = ctx.env ?? process.env;
+  const paths = ctx.paths ?? resolvePaths(ctx.hostKind ?? 'default', env);
+  const state = ctx.state ?? loadState(paths);
+
+  const warnings = [];
+  const checks = [];
+
+  const dirMode = modeOf(paths.root);
+  checks.push({
+    id: 'state-root',
+    status: dirMode === null ? 'FAIL' : 'PASS',
+    detail: dirMode === null ? `state root is missing: ${paths.root}` : `state root present (${dirMode})`,
+  });
+
+  const fileMode = modeOf(paths.stateFile);
+  checks.push({
+    id: 'perm-dir',
+    status: dirMode === null ? 'FAIL' : dirMode === '0700' ? 'PASS' : 'FAIL',
+    detail: dirMode === null ? 'state root missing' : `dir mode ${dirMode} (expected 0700)`,
+  });
+  checks.push({
+    id: 'perm-file',
+    status: fileMode === null ? 'PASS' : fileMode === '0600' ? 'PASS' : 'FAIL',
+    detail: fileMode === null ? 'state file absent' : `file mode ${fileMode} (expected 0600)`,
+  });
+
+  const quarantined = fs.existsSync(paths.root)
+    ? fs.readdirSync(paths.root).filter((f) => f.includes('.corrupt-'))
+    : [];
+  if (quarantined.length > 0) {
+    warnings.push(`state corrupt artifacts found: ${quarantined.length}`);
+    checks.push({ id: 'state-corrupt', status: 'WARN', detail: `${quarantined.length} quarantined file(s)` });
+  }
+
+  const locksStale = countStaleLocks(paths.locksDir);
+  checks.push({
+    id: 'locks',
+    status: locksStale === 0 ? 'PASS' : 'WARN',
+    detail: `${locksStale} stale lock(s)`,
+  });
+
+  const events = ledger.tail(paths.ledgerFile, Number.MAX_SAFE_INTEGER);
+  const triggered = events.filter((e) => e.event === 'triggered').length;
+  const closed = events.filter((e) => CLOSED_EVENTS.includes(e.event)).length;
+  const dangling = Math.max(0, triggered - closed);
+  if (dangling > 0) {
+    warnings.push(`ledger has ${dangling} dangling trigger(s) without a closing event`);
+  }
+  checks.push({
+    id: 'ledger-closure',
+    status: dangling === 0 ? 'PASS' : 'WARN',
+    detail: `${triggered} triggered, ${closed} closed, ${dangling} dangling`,
+  });
+
+  const hosts = Array.isArray(ctx.hosts)
+    ? ctx.hosts.map((h) => ({
+      host: h.host ?? 'unknown',
+      present: h.present === true,
+      version: h.version ?? null,
+      mode: h.mode ?? null,
+      compatible: h.compatible === true,
+    }))
+    : [];
+  if (!Array.isArray(ctx.hosts)) {
+    warnings.push(`host probing is done by the caller (${NOT_IMPLEMENTED})`);
+    checks.push({ id: 'hosts', status: 'WARN', detail: `host probing not provided (${NOT_IMPLEMENTED})` });
+  } else {
+    for (const host of hosts) {
+      if (!host.present) warnings.push(`host ${host.host} is not present`);
+    }
+    checks.push({ id: 'hosts', status: 'PASS', detail: `${hosts.length} host(s) reported` });
+  }
+
+  const peers = state.peers && typeof state.peers === 'object' ? state.peers : {};
+  const now = Number.isFinite(ctx.now) ? ctx.now : Date.now();
+  const sessions = Object.values(peers).filter((p) => p && Number.isFinite(p.lastSeen) && now - p.lastSeen <= PEER_TTL_MS).length;
+
+  const report = {
+    ok: checks.every((c) => c.status !== 'FAIL'),
+    hosts,
+    stateRoot: paths.root,
+    perm: {
+      dir: dirMode ?? 'absent',
+      file: fileMode ?? 'absent',
+    },
+    idle: {
+      enabled: state.idle?.enabled === true,
+      source: 'core-timeline',
+    },
+    sessions,
+    tasks: Array.isArray(state.tasks) ? state.tasks.length : 0,
+    outbox: Array.isArray(state.outbox) ? state.outbox.length : 0,
+    locksStale,
+    secrets: { credentialsRead: false },
+    warnings,
+    checks,
+  };
+  return report;
+}
+
+function modeOf(target) {
+  try {
+    return (fs.statSync(target).mode & 0o777).toString(8).padStart(4, '0');
+  } catch {
+    return null;
+  }
+}
+
+function countStaleLocks(locksDir) {
+  let names = [];
+  try {
+    names = fs.readdirSync(locksDir);
+  } catch {
+    return 0;
+  }
+  let stale = 0;
+  for (const name of names) {
+    try {
+      const stat = fs.statSync(path.join(locksDir, name));
+      if (Date.now() - stat.mtimeMs > STALE_LOCK_MS) stale += 1;
+    } catch {
+      // the lock vanished while we looked at it
+    }
+  }
+  return stale;
+}

package/src/core/errors.mjs

@@ -0,0 +1,8 @@
+// Shared error helpers. The contract freezes one public error-code constant.
+export const NOT_IMPLEMENTED = 'NOT_IMPLEMENTED';
+
+export function pactiveError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}

package/src/core/guard.mjs

@@ -0,0 +1,95 @@
+export const GUARD_REASONS = ['quiet', 'hourly-limit', 'min-interval', 'cooldown'];
+export const HOUR_WINDOW_MS = 3600000;
+
+/** Quiet hours are local wall clock windows, "HH:MM"; a window may wrap midnight. */
+export function inQuietWindow(quietStart, quietEnd, now) {
+  if (!quietStart || !quietEnd) return false;
+  const start = toMinutes(quietStart);
+  const end = toMinutes(quietEnd);
+  if (start === null || end === null) return false;
+  const d = new Date(now);
+  const current = d.getHours() * 60 + d.getMinutes();
+  if (start === end) return false;
+  if (start < end) return current >= start && current < end;
+  return current >= start || current < end;
+}
+
+function toMinutes(value) {
+  if (typeof value !== 'string') return null;
+  const m = /^(\d{1,2}):(\d{2})$/.exec(value.trim());
+  if (!m) return null;
+  const hours = Number(m[1]);
+  const minutes = Number(m[2]);
+  if (hours > 23 || minutes > 59) return null;
+  return hours * 60 + minutes;
+}
+
+/** The four gates: quiet window, hourly limit, minimum interval, cooldown. */
+export function checkGuard(state, now = Date.now()) {
+  const ts = Number.isFinite(now) ? now : Date.now();
+  const policy = state.policy || {};
+  const guard = state.guard || {};
+
+  if (inQuietWindow(policy.quietStart, policy.quietEnd, ts)) {
+    return { pass: false, reason: 'quiet' };
+  }
+
+  const limit = Number.isFinite(policy.hourlyLimit) ? policy.hourlyLimit : 6;
+  const windowStart = Number.isFinite(guard.hourWindowStart) ? guard.hourWindowStart : 0;
+  const count = Number.isFinite(guard.hourCount) ? guard.hourCount : 0;
+  // The window is only rolled over when it really expired; a count without a
+  // window start still counts for the current hour.
+  const windowExpired = windowStart > 0 && ts - windowStart >= HOUR_WINDOW_MS;
+  if (!windowExpired && count >= limit) {
+    return { pass: false, reason: 'hourly-limit' };
+  }
+
+  const lastTriggerAt = Number.isFinite(guard.lastTriggerAt) ? guard.lastTriggerAt : 0;
+  if (lastTriggerAt > 0) {
+    const minIntervalMs = Number.isFinite(policy.minIntervalMs) ? policy.minIntervalMs : 600000;
+    if (ts - lastTriggerAt < minIntervalMs) {
+      return { pass: false, reason: 'min-interval' };
+    }
+    const cooldownMs = Number.isFinite(policy.cooldownMs) ? policy.cooldownMs : 1800000;
+    if (ts - lastTriggerAt < cooldownMs) {
+      return { pass: false, reason: 'cooldown' };
+    }
+  }
+
+  return { pass: true, reason: 'idle' };
+}
+
+/**
+ * Reserve the right to trigger once for the current activity epoch.
+ * Blocks are reported with a reason; the reservation is recorded in the state.
+ */
+export function reserveTrigger(state, now = Date.now()) {
+  const ts = Number.isFinite(now) ? now : Date.now();
+  const epoch = Number.isFinite(state.epoch) ? state.epoch : 0;
+  if (!state.guard || typeof state.guard !== 'object') {
+    state.guard = { hourWindowStart: 0, hourCount: 0, lastTriggerAt: 0, lastTriggerEpoch: -1 };
+  }
+  const guard = state.guard;
+  if (!Number.isFinite(guard.lastTriggerEpoch)) guard.lastTriggerEpoch = -1;
+
+  const gate = checkGuard(state, ts);
+  if (!gate.pass) {
+    return { reserved: false, epoch, reason: gate.reason };
+  }
+  if (guard.lastTriggerEpoch === epoch) {
+    // one trigger per activity epoch; a new user or agent action opens the next one
+    return { reserved: false, epoch, reason: 'requires-action' };
+  }
+
+  const windowStart = Number.isFinite(guard.hourWindowStart) ? guard.hourWindowStart : 0;
+  if (windowStart > 0 && ts - windowStart >= HOUR_WINDOW_MS) {
+    guard.hourWindowStart = ts;
+    guard.hourCount = 0;
+  } else if (windowStart === 0) {
+    guard.hourWindowStart = ts;
+  }
+  guard.hourCount = (Number.isFinite(guard.hourCount) ? guard.hourCount : 0) + 1;
+  guard.lastTriggerAt = ts;
+  guard.lastTriggerEpoch = epoch;
+  return { reserved: true, epoch };
+}

package/src/core/identity.mjs

@@ -0,0 +1,35 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { pactiveError } from './errors.mjs';
+
+/**
+ * Stable identity of an agent session.
+ * agentId  = name#hostKind#sessionId
+ * ownerKey = name#hostKind#projectHash  (project hash keeps clones isolated)
+ */
+export function makeIdentity({ name, hostKind, sessionId, cwd } = {}) {
+  const n = typeof name === 'string' ? name.trim() : '';
+  const h = typeof hostKind === 'string' ? hostKind.trim() : '';
+  const s = typeof sessionId === 'string' ? sessionId.trim() : '';
+  if (!n || !h || !s) {
+    throw pactiveError('IDENTITY_INCOMPLETE', 'name, hostKind and sessionId are required');
+  }
+  const projectHash = hashProject(cwd ?? process.cwd());
+  return {
+    agentId: `${n}#${h}#${s}`,
+    ownerKey: `${n}#${h}#${projectHash}`,
+    projectHash,
+  };
+}
+
+export function hashProject(cwd) {
+  let real = path.resolve(String(cwd));
+  try {
+    real = fs.realpathSync(real);
+  } catch {
+    // a not yet existing directory still hashes deterministically
+  }
+  return crypto.createHash('sha256').update(real).digest('hex').slice(0, 12);
+}

package/src/core/idle.mjs

@@ -0,0 +1,53 @@
+import { checkGuard } from './guard.mjs';
+
+export const IDLE_REASONS = [
+  'idle', 'disabled', 'no-control', 'busy', 'threshold',
+  'quiet', 'hourly-limit', 'min-interval', 'cooldown', 'requires-action',
+];
+
+const POLICY_KEYS = ['quietStart', 'quietEnd', 'hourlyLimit', 'minIntervalMs', 'cooldownMs'];
+
+/**
+ * Four gates must all open before a proactive prompt is allowed:
+ * control returned, agent not busy, activity threshold reached, guard open.
+ */
+export function evaluateIdle(state, now = Date.now(), policy = {}) {
+  const ts = Number.isFinite(now) ? now : Date.now();
+  const p = policy && typeof policy === 'object' ? policy : {};
+  const idleCfg = { ...(state.idle || {}), ...(p.idle || {}) };
+
+  const enabled = firstDefined(p.enabled, p.idleEnabled, idleCfg.enabled, false);
+  const thresholdMs = firstDefined(p.idleThresholdMs, p.thresholdMs, idleCfg.thresholdMs, 0);
+
+  const guardState = { ...state, policy: { ...(state.policy || {}) } };
+  for (const key of POLICY_KEYS) {
+    if (p[key] !== undefined) guardState.policy[key] = p[key];
+  }
+  if (p.policy && typeof p.policy === 'object') Object.assign(guardState.policy, p.policy);
+
+  const guard = checkGuard(guardState, ts);
+  const gates = {
+    control: state.controlReturned === true,
+    notBusy: state.busy === false,
+    threshold: ts - (Number.isFinite(state.lastActivityAt) ? state.lastActivityAt : 0) >= thresholdMs,
+    guard: guard.pass === true,
+  };
+
+  let reason;
+  if (!enabled) reason = 'disabled';
+  else if (!gates.control) reason = 'no-control';
+  else if (!gates.notBusy) reason = 'busy';
+  else if (!gates.threshold) reason = 'threshold';
+  else if (!gates.guard) reason = guard.reason;
+  else reason = 'idle';
+
+  return { idle: reason === 'idle', reason, gates };
+}
+
+function firstDefined(...values) {
+  for (const v of values) {
+    if (v !== undefined && v !== null) return v;
+  }
+  return undefined;
+}
+

package/src/core/index.mjs

@@ -0,0 +1,13 @@
+// Public surface of the core engine. The names below are frozen by the contract.
+export { resolvePaths } from './paths.mjs';
+export { loadState, saveState, mutateState, defaultState } from './state.mjs';
+export { makeIdentity } from './identity.mjs';
+export { markActivity, markControlReturned, getActivity } from './activity.mjs';
+export { evaluateIdle } from './idle.mjs';
+export { checkGuard, reserveTrigger } from './guard.mjs';
+export { schedule } from './scheduler.mjs';
+export { mailbox } from './mailbox.mjs';
+export { ledger } from './lineage.mjs';
+export { config } from './config.mjs';
+export { doctor } from './doctor.mjs';
+export { NOT_IMPLEMENTED } from './errors.mjs';

package/src/core/lineage.mjs

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { pactiveError } from './errors.mjs';
+
+let tmpSeq = 0;
+
+/** Append-only event ledger: one JSON object per line, private file. */
+export const ledger = {
+  append(file, event) {
+    if (typeof file !== 'string' || !file) throw pactiveError('LEDGER_PATH_REQUIRED', 'ledger path is required');
+    const dir = path.dirname(file);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+      fs.chmodSync(dir, 0o700);
+    } catch {
+      // reported by doctor
+    }
+    const record = { ts: Date.now(), ...event };
+    const fd = fs.openSync(file, 'a', 0o600);
+    try {
+      fs.writeSync(fd, `${JSON.stringify(record)}\n`);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    try {
+      fs.chmodSync(file, 0o600);
+    } catch {
+      // reported by doctor
+    }
+    return record;
+  },
+
+  tail(file, n = 20) {
+    const limit = Number.isFinite(n) && n > 0 ? Math.floor(n) : 20;
+    let raw = '';
+    try {
+      raw = fs.readFileSync(file, 'utf8');
+    } catch (err) {
+      if (err.code === 'ENOENT') return [];
+      throw err;
+    }
+    const lines = raw.split('\n').filter((l) => l.trim() !== '');
+    const parsed = [];
+    for (const line of lines) {
+      try {
+        parsed.push(JSON.parse(line));
+      } catch {
+        // a broken line is skipped, the ledger read must not abort
+      }
+    }
+    return parsed.slice(-limit);
+  },
+
+  lineage(file, id) {
+    if (id === undefined || id === null || id === '') return [];
+    const wanted = String(id);
+    return ledger.tail(file, Number.MAX_SAFE_INTEGER).filter((e) => matches(e, wanted));
+  },
+};
+
+function matches(event, id) {
+  if (!event || typeof event !== 'object') return false;
+  if (event.id === id) return true;
+  if (event.taskId === id) return true;
+  if (event.threadId === id) return true;
+  if (event.messageId === id) return true;
+  if (event.outboxId === id) return true;
+  if (event.payload && typeof event.payload === 'object' && event.payload.id === id) return true;
+  return false;
+}

package/src/core/lock.mjs

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { pactiveError } from './errors.mjs';
+
+export const LOCK_STALE_MS = 30000;
+export const LOCK_TIMEOUT_MS = 10000;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(dir, 0o700);
+  } catch {
+    // A directory we cannot tighten is reported by doctor, not silently ignored here.
+  }
+  return dir;
+}
+
+/**
+ * Cross-process mutex: an exclusive lock file plus a stale timeout.
+ * A stale lock is taken over (never silently dropped) and reported through onStale.
+ */
+export async function withLock(locksDir, name, fn, opts = {}) {
+  const staleMs = opts.staleMs ?? LOCK_STALE_MS;
+  const timeoutMs = opts.timeoutMs ?? LOCK_TIMEOUT_MS;
+  ensureDir(locksDir);
+  const lockFile = path.join(locksDir, `${name}.lock`);
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    try {
+      const fd = fs.openSync(lockFile, 'wx', 0o600);
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }));
+      fs.closeSync(fd);
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      let stat = null;
+      try {
+        stat = fs.statSync(lockFile);
+      } catch {
+        continue; // the lock vanished between the failed open and the stat
+      }
+      if (Date.now() - stat.mtimeMs > staleMs) {
+        try {
+          fs.unlinkSync(lockFile);
+        } catch {
+          // another process may have taken it over already
+        }
+        if (typeof opts.onStale === 'function') opts.onStale(lockFile);
+        continue;
+      }
+      if (Date.now() > deadline) {
+        throw pactiveError('LOCK_TIMEOUT', `could not acquire lock ${lockFile}`);
+      }
+      await sleep(20);
+    }
+  }
+
+  try {
+    return await fn();
+  } finally {
+    try {
+      fs.unlinkSync(lockFile);
+    } catch {
+      // the lock was already removed
+    }
+  }
+}

package/src/core/mailbox.mjs

@@ -0,0 +1,162 @@
+import { NOT_IMPLEMENTED } from './errors.mjs';
+
+export const PEER_TTL_MS = 120000;
+export const RECEIPT_STATES = ['accepted', 'queued', 'rejected', 'error', 'unreachable'];
+
+let seq = 0;
+
+/**
+ * Cross session mailbox: a live peer gets the message in its inbox, an absent
+ * peer leaves the message in the outbox. "queued" is never reported as accepted.
+ */
+export const mailbox = {
+  send(state, msg, now = Date.now()) {
+    const ts = Number.isFinite(now) ? now : Date.now();
+    if (!msg || typeof msg !== 'object') {
+      return { ok: false, state: 'rejected', reason: 'message-required', at: ts };
+    }
+    if (!state.peers || typeof state.peers !== 'object') state.peers = {};
+    if (!Array.isArray(state.outbox)) state.outbox = [];
+
+    const target = resolveTarget(state, msg.to, ts);
+    if (!target.ok) {
+      return { ok: false, state: 'rejected', reason: target.reason, at: ts };
+    }
+
+    const id = msg.id ?? `msg-${ts}-${(seq += 1)}`;
+    const message = {
+      id,
+      from: msg.from ?? state.identity?.agentId ?? '',
+      to: target.agentId,
+      kind: msg.kind ?? 'text',
+      body: msg.body ?? '',
+      at: ts,
+      state: 'pending',
+      threadId: msg.threadId ?? id,
+      inReplyTo: msg.inReplyTo ?? null,
+      ackedAt: 0,
+      reason: null,
+    };
+
+    const peer = state.peers[target.agentId];
+    if (peer && isFresh(peer, ts)) {
+      message.state = 'accepted';
+      if (!Array.isArray(peer.inbox)) peer.inbox = [];
+      peer.inbox.push(message);
+      return { ok: true, state: 'accepted', id, at: ts };
+    }
+
+    message.state = 'queued';
+    message.reason = 'peer-offline';
+    state.outbox.push(message);
+    return { ok: true, state: 'queued', id, outboxId: id, reason: 'peer-offline', at: ts };
+  },
+
+  ack(state, id, now = Date.now()) {
+    const ts = Number.isFinite(now) ? now : Date.now();
+    const message = findMessage(state, id);
+    if (!message) return null;
+    message.ackedAt = ts;
+    return message;
+  },
+
+  reply(state, id, body, now = Date.now()) {
+    const ts = Number.isFinite(now) ? now : Date.now();
+    const original = findMessage(state, id);
+    if (!original) {
+      return { ok: false, state: 'rejected', reason: 'unknown-message', at: ts };
+    }
+    return mailbox.send(state, {
+      from: original.to,
+      to: original.from,
+      body,
+      kind: original.kind,
+      threadId: original.threadId ?? original.id,
+      inReplyTo: original.id,
+    }, ts);
+  },
+
+  inbox(state, agentId) {
+    const peer = state.peers && typeof state.peers === 'object' ? state.peers[agentId] : null;
+    return peer && Array.isArray(peer.inbox) ? [...peer.inbox] : [];
+  },
+
+  outbox(state, agentId) {
+    if (!Array.isArray(state.outbox)) return [];
+    return state.outbox.filter((m) => m.to === agentId).map((m) => ({ ...m }));
+  },
+
+  /** Retry the outbox. A failed attempt stays queued, it is never rewritten. */
+  async drain(state, now = Date.now(), deliver) {
+    const ts = Number.isFinite(now) ? now : Date.now();
+    if (!Array.isArray(state.outbox)) return [];
+    const pending = state.outbox.filter((m) => m.state === 'queued').sort((a, b) => a.at - b.at);
+    const receipts = [];
+    for (const message of pending) {
+      if (typeof deliver !== 'function') {
+        receipts.push({ ok: false, id: message.id, state: 'error', reason: NOT_IMPLEMENTED, at: ts });
+        break;
+      }
+      let receipt;
+      try {
+        receipt = await deliver(message);
+      } catch (err) {
+        receipt = { ok: false, state: 'error', reason: err && err.message ? err.message : String(err) };
+      }
+      const state5 = receipt && receipt.state ? receipt.state : 'error';
+      receipts.push({ ...receipt, id: message.id, at: ts });
+      if (state5 === 'accepted') {
+        message.state = 'accepted';
+        message.deliveredAt = ts;
+        state.outbox = state.outbox.filter((m) => m.id !== message.id);
+        const peer = state.peers && state.peers[message.to];
+        if (peer) {
+          if (!Array.isArray(peer.inbox)) peer.inbox = [];
+          peer.inbox.push({ ...message });
+        }
+      } else {
+        // still queued: a failure must never look like a delivery
+        message.state = 'queued';
+        message.lastAttempt = { state: state5, reason: receipt && receipt.reason, at: ts };
+      }
+    }
+    return receipts;
+  },
+};
+
+function isFresh(peer, now) {
+  const lastSeen = peer && Number.isFinite(peer.lastSeen) ? peer.lastSeen : 0;
+  return lastSeen > 0 && now - lastSeen <= PEER_TTL_MS;
+}
+
+function resolveTarget(state, to, now) {
+  const peers = state.peers || {};
+  const ids = Object.keys(peers);
+  if (typeof to === 'string' && to.trim()) {
+    const wanted = to.trim();
+    if (peers[wanted]) return { ok: true, agentId: wanted };
+    const matches = ids.filter((id) => id.startsWith(`${wanted}#`));
+    if (matches.length === 1) return { ok: true, agentId: matches[0] };
+    if (matches.length > 1) return { ok: false, reason: 'ambiguous-target' };
+    return { ok: true, agentId: wanted }; // unknown peer: the message waits in the outbox
+  }
+  const live = ids.filter((id) => isFresh(peers[id], now));
+  if (live.length === 1) return { ok: true, agentId: live[0] };
+  if (live.length > 1) return { ok: false, reason: 'ambiguous-target' };
+  return { ok: false, reason: 'no-target' };
+}
+
+function findMessage(state, id) {
+  if (!id) return null;
+  if (Array.isArray(state.outbox)) {
+    const queued = state.outbox.find((m) => m.id === id);
+    if (queued) return queued;
+  }
+  const peers = state.peers && typeof state.peers === 'object' ? state.peers : {};
+  for (const peer of Object.values(peers)) {
+    if (!peer || !Array.isArray(peer.inbox)) continue;
+    const found = peer.inbox.find((m) => m.id === id);
+    if (found) return found;
+  }
+  return null;
+}