nomoremeatproxy 0.0.0-stage → 0.1.0

package/src/ledger.mjs

@@ -0,0 +1,118 @@
+// Append-only delivery ledger. Holds ids, states and message hashes, never message text.
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { checkStateDir, writeState } from './writable.mjs';
+
+export function defaultStateDir(env = process.env, platform = process.platform, home = os.homedir()) {
+  if (env.NOMEAT_STATE_DIR) return env.NOMEAT_STATE_DIR;
+  // Not under AppData: Windows gives every Store app a private copy of that folder, so the
+  // two desktop apps would each keep a ledger the other cannot see.
+  if (platform === 'win32') return path.join(home, '.nomoremeatproxy');
+  const stateHome = env.XDG_STATE_HOME ?? path.join(home, '.local', 'state');
+  return path.join(stateHome, 'nomoremeatproxy');
+}
+
+function parseLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    // A crash can leave a torn last line; the entries before it are still valid.
+    return null;
+  }
+}
+
+export function openLedger(stateDir, { now = () => new Date(), readOnly = false } = {}) {
+  const file = path.join(stateDir, 'ledger.jsonl');
+  const readAll = () => {
+    if (!readOnly && !existsSync(file)) {
+      checkStateDir(stateDir);
+      return [];
+    }
+    let contents;
+    try {
+      contents = readFileSync(file, 'utf8');
+    } catch (error) {
+      // existsSync also returns false for denied paths. A read-only report must not turn
+      // unknown routes into "none", or probe for writes while checking a missing ledger.
+      if (readOnly && error.code === 'ENOENT') return [];
+      throw error;
+    }
+    return contents.split('\n').filter(Boolean).map(parseLine).filter(Boolean);
+  };
+  return {
+    file,
+    append(event) {
+      if (readOnly) throw new Error('this ledger is read-only');
+      const entry = { at: now().toISOString(), ...event };
+      writeState(() => {
+        mkdirSync(stateDir, { recursive: true });
+        appendFileSync(file, `${JSON.stringify(entry)}\n`);
+      });
+      return entry;
+    },
+    entries() {
+      return readAll();
+    },
+    history(requestId) {
+      return readAll().filter((entry) => entry.requestId === requestId);
+    },
+    // For an answer that found nothing: names the folder read, as the other side may use another.
+    notFound(what) {
+      return { stateDir, note: `${what} in this state folder; both sides must use the same one (NOMEAT_STATE_DIR)` };
+    },
+    // The thread of the most recent answered call between this caller and peer in this project.
+    // A chat that answered while attended in its app is left out: continuing it later would
+    // mean a headless run on a session the app may still hold. So is the answer to a call the
+    // caller steered into a new or an exact thread, recovered or not: such a thread must not
+    // become the default by being recent.
+    lastThread({ project, from, peer }) {
+      const entries = readAll();
+      const steered = new Set(entries.filter((entry) => entry.steered).map((entry) => entry.requestId));
+      const entry = entries.findLast(
+        (candidate) =>
+          candidate.state === 'answered' &&
+          candidate.threadId &&
+          candidate.delivery !== 'attended' &&
+          !steered.has(candidate.requestId) &&
+          candidate.project === project &&
+          candidate.from === from &&
+          candidate.peer === peer,
+      );
+      return entry?.threadId ?? null;
+    },
+    // The thread named as the standing conversation between this caller and peer in this
+    // project. Set explicitly or by the first call; a side thread never changes it.
+    standingThread({ project, from, peer }) {
+      const entry = readAll().findLast(
+        (candidate) => candidate.state === 'standing' && candidate.project === project && candidate.from === from && candidate.peer === peer,
+      );
+      return entry?.threadId ?? null;
+    },
+    // The access the bridge recorded for a thread. The earliest record wins on purpose: it is
+    // what the thread was created with, and a later resume with write may not have stuck.
+    threadAccess(threadId) {
+      if (!threadId) return null;
+      return readAll().find((entry) => entry.threadId === threadId && entry.access)?.access ?? null;
+    },
+    // The newest call from this caller to this peer that is still waiting for its answer:
+    // submitted, not answered, not failed, not sent without waiting, and recent enough to
+    // still be running.
+    openCall({ project, from, peer, maxAgeMs }) {
+      const entries = readAll();
+      const closed = new Set(entries.filter((entry) => ['answered', 'failed', 'sent'].includes(entry.state)).map((entry) => entry.requestId));
+      const oldest = now().getTime() - maxAgeMs;
+      return (
+        entries.findLast(
+          (entry) =>
+            entry.state === 'submitting' &&
+            entry.project === project &&
+            entry.from === from &&
+            entry.peer === peer &&
+            !closed.has(entry.requestId) &&
+            Date.parse(entry.at) >= oldest,
+        ) ?? null
+      );
+    },
+  };
+}

package/src/listen.mjs

@@ -0,0 +1,36 @@
+// The listening loop a Claude chat runs in the desktop app: keep a heartbeat so callers know
+// the chat is attended, and emit each incoming request once. Also the line printed for it.
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// Every request line says how to show it, so the owner sees the incoming message even when
+// the chat no longer remembers the rule. The instruction comes before the message, which
+// comes last because a long notification is cut off at the end. Kept short: it is paid for
+// on every request.
+export function requestLine({ requestId, from, hop, maxHops, file, message }) {
+  const instruction = `Before anything else you write in the chat, quote the whole message and name ${from} as its sender. If message is cut off in this line, read all of it from file first. Then write your answer, then send that same answer with: nomeat reply --request-id ${requestId}`;
+  return { requestId, from, hop, maxHops, file, instruction, message };
+}
+
+// `holdClaim`, asked when the loop ends without an error, says whether to leave the claim live
+// for the chat's next start (`listen --once`) instead of releasing it.
+export async function runListener({ mailbox, box, session, emit, onHeartbeat = () => {}, stopped = () => false, holdClaim = () => false, sleep = wait, now = () => Date.now(), pollMs = 1000, beatMs = 5000 }) {
+  const lease = mailbox.claimListener(box, session);
+  let hold = false;
+  try {
+    mailbox.purge();
+    let lastBeat = -Infinity;
+    while (!stopped()) {
+      const renew = now() - lastBeat >= beatMs;
+      const requests = lease.poll(renew);
+      if (requests === null) break;
+      if (renew) lastBeat = now();
+      for (const request of requests) emit(request);
+      if (renew) onHeartbeat();
+      await sleep(pollMs);
+    }
+    hold = holdClaim();
+  } finally {
+    if (hold) lease.hold();
+    else lease.release();
+  }
+}

package/src/listener-lease.mjs

@@ -0,0 +1,88 @@
+// One live listener per project/peer on this machine. The JSON heartbeat stays readable
+// by existing callers. A SQLite writer lock serializes the check and file operations across
+// processes; the OS releases it on crash. No lock is held while a listener sleeps or emits.
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+
+export const LISTENER_MAX_AGE_MS = 20_000;
+// How long a claim stays live after `listen --once` exits, while the chat finishes its turn.
+export const HELD_CLAIM_MS = 5 * 60_000;
+
+function heartbeat(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export function liveListener(file, now) {
+  // Discovery is advisory: as before the guard, an unreadable heartbeat means no
+  // known listener. Writers use the strict read under the lock and never guess ownership.
+  let beat;
+  try {
+    beat = heartbeat(file);
+  } catch {
+    return null;
+  }
+  return beat && now() - beat.at <= LISTENER_MAX_AGE_MS ? { session: beat.session } : null;
+}
+
+function locked(file, operation) {
+  // Load the built-in only on the listener path. Node 22.15+ ships it; no npm install.
+  const DatabaseSync = process.getBuiltinModule('node:sqlite')?.DatabaseSync;
+  if (!DatabaseSync) throw new Error('listening requires a Node.js 22.15+ build with built-in SQLite');
+  const db = new DatabaseSync(file);
+  try {
+    db.exec('PRAGMA busy_timeout=5000; BEGIN IMMEDIATE');
+    return operation();
+  } finally {
+    db.close(); // ends the lock-only transaction, including when operation throws
+  }
+}
+
+export function claimListener({ file, peer, session = null, now, writeJson, collect }) {
+  mkdirSync(path.dirname(file), { recursive: true });
+  const exclusive = (fn) => locked(`${file}.lock.sqlite`, fn);
+  const run = randomUUID();
+  const beat = (ahead = 0) => writeJson(file, { session, run, at: now() + ahead });
+  const owns = () => heartbeat(file)?.run === run;
+
+  exclusive(() => {
+    const previous = heartbeat(file);
+    if (previous && now() - previous.at <= LISTENER_MAX_AGE_MS) {
+      // Two anonymous processes cannot establish that they belong to the same chat.
+      // A pre-guard listener cannot be fenced, even if it has the same session id.
+      if (!session || previous.session !== session || !previous.run) {
+        throw new Error(`${peer} already has a listener for this project (${previous.session || 'unknown chat'}); stop it first or wait for its last heartbeat to expire`);
+      }
+    }
+    beat();
+  });
+
+  return {
+    poll(renew) {
+      return exclusive(() => {
+        if (!owns()) return null; // replaced; never refresh or consume another run's work
+        if (renew) beat();
+        return collect();
+      });
+    },
+    release() {
+      exclusive(() => {
+        if (owns()) rmSync(file);
+      });
+    },
+    // Leaves the claim live for HELD_CLAIM_MS, so callers keep waiting in the inbox and the
+    // same chat's next start (same session) takes it over. The beat is stamped ahead so the
+    // usual freshness check expires it then. Limit: a restart later than that lets calls
+    // fall back to the standing chat, and a chat that stopped for good holds callers that long.
+    hold() {
+      exclusive(() => {
+        if (owns()) beat(HELD_CLAIM_MS - LISTENER_MAX_AGE_MS);
+      });
+    },
+  };
+}

package/src/mailbox.mjs

@@ -0,0 +1,145 @@
+// File mailbox for handing a call to a Claude chat that is listening in the desktop app.
+// Message text lives here only until the reply is collected; the ledger still holds none.
+//
+// Layout under <state>/inbox:
+//   listeners/<key>.json   heartbeat of the chat attending one peer name in one project
+//   requests/<id>.json     posted by a caller, not yet taken by the listener
+//   delivered/<id>.json    taken by the listener, not yet answered
+//   replies/<id>.json      answered, not yet collected by the caller
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { claimListener, liveListener } from './listener-lease.mjs';
+import { writeState } from './writable.mjs';
+
+export { LISTENER_MAX_AGE_MS } from './listener-lease.mjs';
+const STALE_FILE_MS = 24 * 60 * 60 * 1000;
+const STAGES = Object.freeze(['requests', 'delivered', 'replies']);
+const SAFE_NAME = /^[A-Za-z0-9._-]{1,80}$/;
+
+const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+const fileName = (requestId) => `${SAFE_NAME.test(requestId) ? requestId : sha256(requestId)}.json`;
+
+// Windows compares paths without case, and the same folder must give one key from any shell.
+export function mailboxKey({ project, peer }, platform = process.platform) {
+  const folder = platform === 'win32' ? project.toLowerCase() : project;
+  return sha256(`${folder}\n${peer}`).slice(0, 16);
+}
+
+// Limit: removals (rmSync) are not wrapped; a folder that refuses them refuses this first.
+function writeJson(file, value) {
+  writeState(() => {
+    mkdirSync(path.dirname(file), { recursive: true });
+    // Written whole and then renamed, so a reader never sees half a file.
+    const partial = `${file}.${process.pid}.tmp`;
+    writeFileSync(partial, JSON.stringify(value));
+    renameSync(partial, file);
+  });
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+const listJson = (dir) => (existsSync(dir) ? readdirSync(dir).filter((name) => name.endsWith('.json')) : []);
+
+export function openMailbox(stateDir, { now = () => Date.now() } = {}) {
+  const root = path.join(stateDir, 'inbox');
+  const stageFile = (stage, requestId) => path.join(root, stage, fileName(requestId));
+  const listenerFile = (box) => path.join(root, 'listeners', `${mailboxKey(box)}.json`);
+
+  const mailbox = {
+    // --- listener side ---
+    claimListener(box, session) {
+      return claimListener({ file: listenerFile(box), peer: box.peer, session, now, writeJson, collect: () => mailbox.collect(box) });
+    },
+    // Takes every waiting request addressed to this box, oldest first.
+    collect(box) {
+      const key = mailboxKey(box);
+      const dir = path.join(root, 'requests');
+      const waiting = listJson(dir)
+        .map((name) => ({ name, request: readJson(path.join(dir, name)) }))
+        .filter(({ request }) => request?.key === key)
+        .sort((a, b) => a.request.at - b.request.at);
+      const taken = [];
+      for (const { name, request } of waiting) {
+        writeState(() => mkdirSync(path.join(root, 'delivered'), { recursive: true }));
+        try {
+          const file = path.join(root, 'delivered', name);
+          // A repost of an id already taken or answered is dropped, not printed again. Callers
+          // refuse a retry of a taken id and remove their repost when they take a waiting
+          // answer; this catches a repost that slips in between. Limit: once the answer is
+          // collected nothing is left to match, so a resend forced past the ledger is handed
+          // over again.
+          if (existsSync(file) || existsSync(path.join(root, 'replies', name))) {
+            rmSync(path.join(dir, name), { force: true });
+            continue;
+          }
+          renameSync(path.join(dir, name), file);
+          // The file is named so a listener whose notice was cut short can read the whole text.
+          taken.push({ ...request, file });
+        } catch {
+          // The caller withdrew it in the meantime.
+        }
+      }
+      return taken;
+    },
+    answer(requestId, reply) {
+      const open = ['requests', 'delivered'].some((stage) => existsSync(stageFile(stage, requestId)));
+      if (!open) throw new Error(`no open request "${requestId}" in the mailbox`);
+      writeJson(stageFile('replies', requestId), { requestId, reply, at: now() });
+      rmSync(stageFile('requests', requestId), { force: true });
+      rmSync(stageFile('delivered', requestId), { force: true });
+    },
+    // Removes leftovers of calls nobody came back for.
+    purge() {
+      for (const stage of STAGES) {
+        const dir = path.join(root, stage);
+        for (const name of listJson(dir)) {
+          const file = path.join(dir, name);
+          if (now() - statSync(file).mtimeMs > STALE_FILE_MS) rmSync(file, { force: true });
+        }
+      }
+    },
+
+    // --- caller side ---
+
+    listener(box) {
+      return liveListener(listenerFile(box), now);
+    },
+    // Every chat that is listening now, in any project and under any peer name.
+    listeners() {
+      const dir = path.join(root, 'listeners');
+      return listJson(dir).map((name) => liveListener(path.join(dir, name), now)).filter(Boolean);
+    },
+    post({ project, peer, requestId, from, hop, maxHops, message }) {
+      writeJson(stageFile('requests', requestId), { key: mailboxKey({ project, peer }), requestId, from, hop, maxHops, message, at: now() });
+    },
+    // The reply, or null while there is none. Reading it clears it, and a retry's repost with
+    // it: removed first, so the listener never finds the repost without the reply beside it.
+    takeReply(requestId) {
+      const file = stageFile('replies', requestId);
+      const stored = readJson(file);
+      if (!stored) return null;
+      rmSync(stageFile('requests', requestId), { force: true });
+      rmSync(file, { force: true });
+      return stored.reply;
+    },
+    // True while a listener holds the request: taken and not yet answered. Purge ends it after a day.
+    taken(requestId) {
+      return existsSync(stageFile('delivered', requestId));
+    },
+    // True when the request had not been taken yet and is now gone, so nothing was delivered.
+    withdraw(requestId) {
+      const file = stageFile('requests', requestId);
+      if (!existsSync(file)) return false;
+      rmSync(file, { force: true });
+      return true;
+    },
+  };
+  return mailbox;
+}

package/src/orient.mjs

@@ -0,0 +1,72 @@
+// Read-only orientation. No vendor commands, write probes, listener claims or messages.
+import { accessSync, constants, statSync } from 'node:fs';
+import path from 'node:path';
+import { defaultStateDir, openLedger } from './ledger.mjs';
+import { openMailbox } from './mailbox.mjs';
+import { DEFAULT_PEERS } from './peers.mjs';
+
+export function stateAccess(dir) {
+  let existing = path.resolve(dir);
+  let exists = true;
+  for (;;) {
+    try {
+      const stat = statSync(existing);
+      if (!stat.isDirectory()) return { exists, writable: false, checked: existing, reason: 'not a directory' };
+      accessSync(existing, constants.W_OK | constants.X_OK);
+      return { exists, writable: true, checked: existing };
+    } catch (error) {
+      if (error.code !== 'ENOENT') return { exists, writable: false, checked: existing, reason: error.code ?? 'unknown' };
+      exists = false;
+      const parent = path.dirname(existing);
+      if (parent === existing) return { exists, writable: false, checked: existing, reason: 'no existing parent' };
+      existing = parent;
+    }
+  }
+}
+
+export function orient({ cwd = process.cwd(), from, stateDir = defaultStateDir() } = {}) {
+  const project = path.resolve(cwd);
+  const location = path.resolve(stateDir);
+  const ledger = openLedger(location, { readOnly: true });
+  const mailbox = openMailbox(location);
+  const routes = new Map();
+  for (const entry of ledger.entries()) {
+    if (entry.project === project && typeof entry.from === 'string' && entry.from && Object.hasOwn(DEFAULT_PEERS, entry.peer) && (!from || entry.from === from || entry.peer === from)) {
+      routes.set(JSON.stringify([entry.from, entry.peer]), { project, from: entry.from, peer: entry.peer });
+    }
+  }
+  if (from) for (const peer of Object.keys(DEFAULT_PEERS)) {
+    if (peer === from) continue;
+    routes.set(JSON.stringify([from, peer]), { project, from, peer });
+    if (Object.hasOwn(DEFAULT_PEERS, from)) routes.set(JSON.stringify([peer, from]), { project, from: peer, peer: from });
+  }
+  const listeners = Object.entries(DEFAULT_PEERS).filter(([, peer]) => peer.vendor === 'claude').map(([peer]) => ({
+    peer, registration: mailbox.listener({ project, peer }),
+  }));
+  const sortedRoutes = [...routes.values()].sort((a, b) => Number(Object.hasOwn(DEFAULT_PEERS, b.from)) - Number(Object.hasOwn(DEFAULT_PEERS, a.from)) || a.from.localeCompare(b.from) || a.peer.localeCompare(b.peer));
+  const vendor = DEFAULT_PEERS[from]?.vendor;
+  return {
+    project,
+    projectResolution: 'absolute lexical path from --cwd or the current directory; no symlink canonicalization',
+    state: {
+      location,
+      access: stateAccess(location),
+      note: 'Advisory filesystem permission check only; no write attempted. Sandboxes or ACLs may still refuse writes. Both assistants must use this same location.',
+    },
+    routes: sortedRoutes.slice(0, 20).map((route) => ({
+      from: route.from, peer: route.peer,
+      role: !from ? 'project route' : route.from === from ? 'outgoing' : 'incoming',
+      standing: ledger.standingThread(route),
+      fallback: ledger.lastThread(route),
+    })),
+    routesOmitted: Math.max(0, sortedRoutes.length - 20),
+    listeners,
+    routing: 'An unpinned Claude call may use a registered listener unless that peer is waiting for this caller; otherwise the standing thread, then the last eligible answer, then a new chat. Explicit --thread and --new bypass this default.',
+    listenerNote: 'Registration/heartbeat freshness only, including held listen --once claims; delivery and end-to-end reachability not tested.',
+    nextSteps: {
+      caller: `Use find --side ${vendor === 'codex' ? 'claude' : vendor === 'claude' ? 'codex' : '<codex|claude>'} --project --cwd ${JSON.stringify(project)} to locate chats, then read --side <side> --thread <id>. Inspect standing --to <peer> --from ${from ? JSON.stringify(from) : '<caller>'} --cwd ${JSON.stringify(project)} before changing a route.`,
+      listener: `${vendor === 'codex' ? 'Codex callers do not run listen; the receiving Claude Desktop chat does.' : vendor === 'claude' ? 'As a Claude peer, listen in the exact intended Desktop chat.' : 'Caller side unknown; only a Claude Desktop chat runs listen.'} Run listen --as <peer> --thread <this exact chat id> --once --cwd <project>, then restart after output; reply by request-id. This report does not start it.`,
+      owner: 'Run npm run doctor from the bridge installation for installation/sign-in checks. Only a separately authorized real call and reply can test delivery.',
+    },
+  };
+}

package/src/peers.mjs

@@ -0,0 +1,18 @@
+// Peer names are the words the owner uses: "call Astra", "spin off Sol".
+
+export const DEFAULT_PEERS = Object.freeze({
+  astra: Object.freeze({ vendor: 'codex', model: 'gpt-6-astra', effort: 'ultra' }),
+  sol: Object.freeze({ vendor: 'codex', model: 'gpt-6.1-sol', effort: 'ultra' }),
+  fable: Object.freeze({ vendor: 'claude', model: 'claude-fable-5-2' }),
+  opus: Object.freeze({ vendor: 'claude', model: 'claude-opus-5-5', effort: 'high' }),
+});
+
+export function resolvePeer(name, { model, effort, peers = DEFAULT_PEERS } = {}) {
+  const key = String(name ?? '').toLowerCase();
+  const peer = Object.hasOwn(peers, key) ? peers[key] : undefined;
+  if (!peer) {
+    throw new Error(`unknown peer "${name}"; known peers: ${Object.keys(peers).join(', ')}`);
+  }
+  const level = effort ?? peer.effort;
+  return { name: key, vendor: peer.vendor, model: model ?? peer.model, ...(level === undefined ? {} : { effort: level }) };
+}

package/src/remote-control-store.mjs

@@ -0,0 +1,116 @@
+// Per-install consent and durable Desktop work; never store prompts, replies or target paths.
+// Public API: bind/disable, enqueue, due/work, report/retry, status.
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { checkStateDir, writeState } from './writable.mjs';
+
+export const REMINDER_MS = 5 * 60_000;
+export const MAX_NOTICES = 3;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function sessionId(value) {
+  const id = String(value ?? '').replace(/^local_/, '').toLowerCase();
+  if (!UUID.test(id)) throw new Error('Expected a Claude Desktop session UUID');
+  return id;
+}
+
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS coordinator (singleton INTEGER PRIMARY KEY CHECK(singleton=1), box TEXT NOT NULL, session TEXT NOT NULL);
+  CREATE TABLE IF NOT EXISTS jobs (target TEXT PRIMARY KEY, state TEXT NOT NULL, receipt TEXT, notified INTEGER, verified INTEGER, attempts INTEGER NOT NULL DEFAULT 0);
+`;
+const counts = (db) => Object.fromEntries(db.prepare('SELECT state, COUNT(*) AS n FROM jobs GROUP BY state').all().map(r => [r.state, r.n]));
+const bound = (db) => db.prepare('SELECT box, session FROM coordinator').get();
+const matches = (db, box, session) => {
+  const current = bound(db);
+  return current && current.box === box && current.session === session;
+};
+
+export function remoteStore(dir, { now = Date.now } = {}) {
+  const file = path.join(dir, 'remote-control.sqlite');
+  function access(fn, { create = false, write = false, absent = null } = {}) {
+    if (!create && !existsSync(file)) {
+      checkStateDir(dir);
+      return absent;
+    }
+    const SQLite = process.getBuiltinModule('node:sqlite')?.DatabaseSync;
+    if (!SQLite) throw new Error('Remote Control provisioning requires Node.js with built-in SQLite');
+    return writeState(() => {
+      if (create) mkdirSync(dir, { recursive: true });
+      const db = new SQLite(file);
+      try {
+        db.exec('PRAGMA busy_timeout=5000');
+        if (write) db.exec('BEGIN IMMEDIATE');
+        if (create) db.exec(SCHEMA);
+        const result = fn(db);
+        if (write) db.exec('COMMIT');
+        return result;
+      } finally { db.close(); }
+    });
+  }
+  return {
+    bind(box, session) {
+      session = sessionId(session);
+      return access(db => {
+        if (bound(db) && !matches(db, box, session)) throw new Error('A different coordinator is bound; disable the old binding first');
+        db.prepare('INSERT OR IGNORE INTO coordinator VALUES(1, ?, ?)').run(box, session);
+        return { enabled: true, coordinator: session };
+      }, { create: true, write: true });
+    },
+    disable() {
+      return access(db => {
+        db.exec("DELETE FROM coordinator; UPDATE jobs SET state='cancelled', receipt=NULL WHERE state IN ('pending','approval-required','unavailable')");
+        return { enabled: false };
+      }, { write: true, absent: { enabled: false } });
+    },
+    enqueue(target) {
+      target = sessionId(target);
+      return access(db => {
+        if (!bound(db)) return { state: 'not-configured' };
+        db.prepare("INSERT OR IGNORE INTO jobs(target, state) VALUES(?, 'pending')").run(target);
+        return { state: db.prepare('SELECT state FROM jobs WHERE target=?').get(target).state };
+      }, { write: true, absent: { state: 'not-configured' } });
+    },
+    due(box, session) {
+      return access(db => {
+        if (!matches(db, box, session)) return [];
+        const when = now();
+        db.prepare("UPDATE jobs SET state='unavailable', receipt=NULL WHERE state='pending' AND attempts>=? AND notified<=?").run(MAX_NOTICES, when - REMINDER_MS);
+        const rows = db.prepare("SELECT target FROM jobs WHERE state='pending' AND (notified IS NULL OR notified<=?) ORDER BY notified, rowid LIMIT 8").all(when - REMINDER_MS);
+        const mark = db.prepare('UPDATE jobs SET notified=?, attempts=attempts+1, receipt=COALESCE(receipt,?) WHERE target=?');
+        for (const { target } of rows) mark.run(when, randomUUID(), target);
+        return rows.map(r => r.target);
+      }, { write: true, absent: [] });
+    },
+    work(box, session) {
+      return access(db => matches(db, box, session)
+        ? db.prepare("SELECT target, receipt, attempts FROM jobs WHERE state='pending' AND receipt IS NOT NULL ORDER BY rowid").all() : [], { absent: [] });
+    },
+    report(target, receipt, result) {
+      target = sessionId(target);
+      if (!['active', 'approval-required', 'unavailable'].includes(result)) throw new Error('Result must be active, approval-required, or unavailable');
+      const recorded = access(db => {
+        const job = db.prepare('SELECT state, receipt FROM jobs WHERE target=?').get(target);
+        if (!bound(db) || !receipt || job?.receipt !== receipt || !['pending', result].includes(job.state)) {
+          throw new Error('No matching outstanding Desktop verification');
+        }
+        if (job.state === 'pending') db.prepare('UPDATE jobs SET state=?, verified=? WHERE target=?').run(result, result === 'active' ? now() : null, target);
+        return { target, state: result };
+      }, { write: true });
+      if (!recorded) throw new Error('No Remote Control configuration');
+      return recorded;
+    },
+    retry(target) {
+      target = sessionId(target);
+      const changed = access(db => bound(db) && db.prepare("UPDATE jobs SET state='pending', receipt=NULL, notified=NULL, attempts=0 WHERE target=? AND state IN ('approval-required','unavailable')").run(target).changes, { write: true });
+      if (!changed) throw new Error('No eligible blocked job; only bridge-created jobs can be retried');
+      return { target, state: 'pending' };
+    },
+    status(target) {
+      if (target) target = sessionId(target);
+      return access(db => ({
+        enabled: Boolean(bound(db)), coordinator: bound(db)?.session ?? null,
+        ...(target ? { target, job: db.prepare('SELECT state, attempts, verified AS verifiedAtMs FROM jobs WHERE target=?').get(target) ?? null } : { counts: counts(db) }),
+      }), { absent: { enabled: false, ...(target ? { target, job: null } : { counts: {} }) } });
+    },
+  };
+}

package/src/remote-control.mjs

@@ -0,0 +1,64 @@
+// Wire new Claude Desktop imports to an owner's explicitly bound, attended coordinator.
+// No headless fallback: only the Desktop session tools can change and verify this switch.
+import path from 'node:path';
+import { mailboxKey } from './mailbox.mjs';
+import { resolvePeer } from './peers.mjs';
+import { sessionId } from './remote-control-store.mjs';
+
+export function provisionNewChat({ outcome, vendor, optOut, store, createdForRequest }) {
+  if (vendor !== 'claude' || optOut || outcome.state !== 'answered' || outcome.delivery !== 'headless'
+      || outcome.continued !== false || !outcome.app?.opened) return;
+  // The ID is the session returned by this creation, never an ID in a user's prompt.
+  try {
+    if (!createdForRequest(outcome.threadId)) throw new Error('Desktop target differs from the session ID allocated by the bridge; not enrolled');
+    outcome.app.remoteControl = store.enqueue(outcome.threadId);
+  }
+  catch (error) { outcome.app.remoteControl = { state: 'setup-error', reason: error.message }; }
+}
+
+function liveIdentity(values, mailbox) {
+  const peer = resolvePeer(values.as);
+  if (peer.vendor !== 'claude') throw new Error('The coordinator must be a Claude Desktop peer');
+  const box = { peer: peer.name, project: path.resolve(values.cwd ?? process.cwd()) };
+  const session = sessionId(values.thread);
+  const live = mailbox.listener(box)?.session;
+  if (!live || sessionId(live) !== session) throw new Error('Start the named Desktop chat listener in this project first; its ID must match --thread');
+  return { key: mailboxKey(box), session };
+}
+
+export function remoteCommand(action, values, { store, mailbox }) {
+  if (action === 'enable' || action === 'work') {
+    const { key, session } = liveIdentity(values, mailbox);
+    if (action === 'enable') return store.bind(key, session);
+    return {
+      jobs: store.work(key, session),
+      instructions: 'For listed targets only, recheck work before acting. Call native get_session(local_<target>), set_remote_control(enabled=true) if needed, then get_session again. Report active only if that session shows remoteControlState on AND remoteControlActive true. If import or connection is delayed, leave pending. Report approval-required or unavailable if blocked. Never use headless or change global settings.',
+      report: 'nomeat remote-control report --target <target> --receipt <receipt> --result active|approval-required|unavailable',
+    };
+  }
+  if (action === 'disable') return store.disable();
+  if (action === 'status') return store.status(values.target);
+  if (action === 'report') return store.report(values.target, values.receipt, values.result);
+  if (action === 'retry') return store.retry(values.target);
+  throw new Error('remote-control needs enable, disable, status, work, report, or retry');
+}
+
+// The listener announces durable work, not a regular peer call. Missing Desktop/offline:
+// jobs survive. Unacknowledged notices are reissued and enabling an already-on chat is safe.
+export function notifyRemoteWork({ store, box, session, emit, warn }) {
+  if (!session) return () => {};
+  let lastError;
+  return () => {
+    try {
+      const targets = store.due(mailboxKey(box), sessionId(session));
+      if (targets.length) emit({
+        kind: 'remote-control', message: 'ASK: Enable and verify Remote Control for new bridge chats. Run the work command below, follow its Desktop instructions, then report each result. Do not use nomeat reply.',
+        args: ['remote-control', 'work', '--as', box.peer, '--thread', session, '--cwd', box.project],
+      });
+      lastError = undefined;
+    } catch (error) {
+      if (lastError !== error.message) warn(`Remote Control check skipped: ${error.message}`);
+      lastError = error.message;
+    }
+  };
+}