meshingly-mcp 0.1.0 → 0.3.0

package/dist/settings-cli.js

@@ -0,0 +1,73 @@
+import { createInterface } from "node:readline";
+import { describeSettings, resetSettings, SETTING_KEYS, writeSetting } from "./settings.js";
+
+/** One line from the user. Resolves with "" when there is none (end of input). */
+function ask(prompt        )                  {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    let answered = false;
+    rl.question(prompt, (answer) => {
+      answered = true;
+      rl.close();
+      resolve(answer);
+    });
+    rl.on("close", () => {
+      if (!answered) resolve("");
+    });
+  });
+}
+
+const HELP = `meshingly-mcp settings: your preferences for this project (stored in your home folder, not in the project: a repository must not be able to ship them).
+
+  npx -y meshingly-mcp settings                 show every setting and where its value comes from
+  npx -y meshingly-mcp settings set <key> <value>
+  npx -y meshingly-mcp settings set <key>        leave the value out to be asked for it (no quoting needed: handy for a command with quotes or $)
+  npx -y meshingly-mcp settings reset           back to the defaults
+
+Keys: ${SETTING_KEYS.join(", ")}
+
+Examples:
+  npx -y meshingly-mcp settings set autoResume true        continue queued work automatically after the limit is back
+  npx -y meshingly-mcp settings set onQuestion recommended  an unattended run takes the recommended option instead of waiting
+  npx -y meshingly-mcp settings set resumeCommand "codex exec -"
+
+You can also just ask your AI session ("turn on the journal", "let every session know what the others did"): it changes the harmless settings itself and asks you to confirm the ones that start programs on this computer.
+A running watcher keeps the values it started with: stop it and start it again after a change.
+An environment variable in your MCP configuration (MESHINGLY_AUTOWATCH, MESHINGLY_WATCH_CMD, MESHINGLY_WATCH_FROM_PEERS) overrides the file.
+`;
+
+/** `meshingly-mcp settings ...`. Returns the process exit code. */
+export async function runSettings(argv          , root = process.env.MESHINGLY_DIR ?? process.cwd())                  {
+  const [verb, key, ...rest] = argv;
+  if (verb === "--help" || verb === "help" || verb === "-h") {
+    console.log(HELP);
+    return 0;
+  }
+  if (verb === undefined) {
+    console.log(describeSettings(root));
+    return 0;
+  }
+  if (verb === "reset") {
+    resetSettings(root);
+    console.log("Settings are back to the defaults.");
+    return 0;
+  }
+  if (verb === "set") {
+    // With no value on the command line the value is asked for: what is typed there never passes through the shell.
+    const value = key && rest.length === 0 ? (await ask(`${key}: `)).trim() : rest.join(" ");
+    if (!key || !value) {
+      console.error(key ? `No value for ${key}: give it after the name, or type it when asked.\n\n${HELP}` : `Usage: settings set <key> <value>\n\n${HELP}`);
+      return 2;
+    }
+    try {
+      writeSetting(root, key, value);
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      return 2;
+    }
+    console.log(`${describeSettings(root)}\n\nSaved. A running watcher keeps its old values: stop it and start it again.`);
+    return 0;
+  }
+  console.error(`Unknown command "${verb}".\n\n${HELP}`);
+  return 2;
+}

package/dist/settings.js

@@ -0,0 +1,271 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+/**
+ * Per-project preferences of the person using Meshingly. They are changed from a terminal (`meshingly-mcp settings`),
+ * never through an MCP tool: the settings decide what runs unattended on this computer, so a model that a peer's
+ * message talked into something must not be able to change them. (An agent with shell access could still edit the
+ * file, exactly as it could edit its own permission settings: the guarantee is about the tool surface.)
+ *
+ * They live in the user's home directory, keyed by the project's path, and NOT in the project's own `.meshingly/`:
+ * a repository can ship a `.meshingly/` folder, and a command to run unattended must never come from there.
+ */
+                           
+                                                                                            
+                      
+                                                                        
+                        
+                                                                                  
+                      
+                                                                                   
+                                     
+                                                                                                          
+                                             
+                                                                                                                    
+                  
+                                                                                         
+                                
+                                                                                                                                         
+                        
+                                                                   
+                      
+                                      
+                               
+ 
+
+                                                                                                                                      
+
+export const SETTING_INFO                                                                                                               = {
+  autoResume: {
+    kind: { type: "boolean" },
+    default: false,
+    env: "MESHINGLY_AUTOWATCH",
+    description: "Start the background watcher automatically, so queued work continues after the usage limit is back.",
+  },
+  resumeCommand: {
+    kind: { type: "string" },
+    default: "claude -p",
+    env: "MESHINGLY_WATCH_CMD",
+    description: "Command that receives the handoff on stdin and continues the work. Add the permissions it needs yourself.",
+  },
+  trustPeers: {
+    kind: { type: "boolean" },
+    default: false,
+    env: "MESHINGLY_WATCH_FROM_PEERS",
+    description: "Also run handoffs written by teammates. Their text starts an agent on this computer: only for people you trust.",
+  },
+  onQuestion: {
+    kind: { type: "enum", values: ["stop", "recommended"] },
+    default: "stop",
+    description:
+      "When an unattended run would ask a question: stop = park the question for a person; recommended = take the option it recommends, note the assumption and carry on (never for deleting, spending, publishing or pushing).",
+  },
+  journal: {
+    kind: { type: "enum", values: ["off", "milestones", "detailed"] },
+    default: "off",
+    description:
+      "Sessions write short notes for the other sessions (milestones: finished steps and decisions; detailed: every step). Everyone in the collaboration can read them.",
+  },
+  catchUp: {
+    kind: { type: "int", min: 0, max: 200 },
+    default: 0,
+    description: "How many recent entries (notes, handoffs, messages) a session reads when it joins or starts, so it knows what the other sessions did. 0 = none.",
+  },
+  modelMayStartWatcher: {
+    kind: { type: "boolean" },
+    default: false,
+    description: "Let an AI session start the background watcher with its meshingly_watch_start tool. Off: only you start it (watch command, or autoResume).",
+  },
+  settleMinutes: {
+    kind: { type: "int", min: 0, max: 240 },
+    default: 5,
+    description: "How long a handoff without a limit-reset time waits before the watcher runs it, in case the session that parked it is still working.",
+  },
+  maxAttempts: { kind: { type: "int", min: 1, max: 10 }, default: 3, description: "Failed runs per handoff before the watcher gives up on it." },
+  checkIntervalSeconds: { kind: { type: "int", min: 5, max: 3600 }, default: 60, description: "Seconds between queue checks." },
+};
+
+export const SETTING_KEYS = Object.keys(SETTING_INFO)                         ;
+
+/**
+ * Settings an AI session may change itself when the user asks for it in the conversation. They decide what is shared inside
+ * the collaboration or how patient the watcher is; none of them starts a program.
+ */
+export const MODEL_MAY_SET                              = new Set(["journal", "catchUp", "settleMinutes", "maxAttempts", "checkIntervalSeconds"]);
+
+/**
+ * Whether a change needs the user's own approval, which the model cannot give. Everything does, except what is on the
+ * allow-list above and switching a supervision-reducing setting back off: a setting added later is guarded until someone
+ * deliberately puts it on the list.
+ */
+export function needsApproval(key                , value         )          {
+  if (MODEL_MAY_SET.has(key)) return false;
+  if ((key === "autoResume" || key === "trustPeers" || key === "modelMayStartWatcher") && value === false) return false;
+  if (key === "onQuestion" && value === "stop") return false;
+  return true;
+}
+
+/** What a change means, in the words the user sees when asked to approve it. */
+export function riskNote(key                , value         )         {
+  switch (key) {
+    case "autoResume":
+      return "a background process will start an AI agent on this computer whenever queued work is ready";
+    case "resumeCommand":
+      return `this command will be run unattended, with queued work as its input: ${String(value)}`;
+    case "trustPeers":
+      return "handoffs written by teammates will start an AI agent on this computer";
+    case "onQuestion":
+      return "unattended runs will decide questions themselves instead of waiting for you (never deleting, spending, publishing or pushing)";
+    case "modelMayStartWatcher":
+      return "an AI session may start the background watcher without asking you again";
+    default:
+      return "this changes how Meshingly runs on this computer";
+  }
+}
+
+/** Where this project's settings are kept: under the user's home (MESHINGLY_HOME overrides it, for tests), keyed by the project's path. */
+export function settingsPath(root        )         {
+  // The same folder must give the same file however it was spelled (c:\dev vs C:\Dev, a symlink): otherwise a setting
+  // made from one shell would be silently ignored by a server started from another.
+  let real = resolve(root);
+  try {
+    real = realpathSync.native(real);
+  } catch {
+    /* the folder does not exist (yet): use the path as given */
+  }
+  const key = createHash("sha256").update(process.platform === "win32" ? real.toLowerCase() : real).digest("hex").slice(0, 16);
+  return join(process.env.MESHINGLY_HOME ?? join(homedir(), ".meshingly"), "projects", `${key}.json`);
+}
+const file = settingsPath;
+
+/** Turns text into a valid value for the setting, or says why not. */
+export function parseSetting(key                , raw         )                                                                                {
+  const { kind } = SETTING_INFO[key];
+  const text = typeof raw === "string" ? raw.trim() : raw;
+  switch (kind.type) {
+    case "boolean": {
+      if (typeof text === "boolean") return { ok: true, value: text };
+      const t = String(text).toLowerCase();
+      if (["true", "on", "yes", "1"].includes(t)) return { ok: true, value: true };
+      if (["false", "off", "no", "0"].includes(t)) return { ok: true, value: false };
+      return { ok: false, reason: "use true or false" };
+    }
+    case "enum":
+      return typeof text === "string" && kind.values.includes(text) ? { ok: true, value: text } : { ok: false, reason: `use one of: ${kind.values.join(", ")}` };
+    case "int": {
+      // Not Number(): it turns "", true and [3] into numbers, and a malformed value must never become a valid setting.
+      const n = typeof text === "number" ? text : typeof text === "string" && /^-?\d+$/.test(text) ? Number(text) : Number.NaN;
+      return Number.isInteger(n) && n >= kind.min && n <= kind.max ? { ok: true, value: n } : { ok: false, reason: `use a whole number from ${kind.min} to ${kind.max}` };
+    }
+    case "string":
+      return typeof text === "string" && text.length > 0 && text.length <= 300 && !/[\r\n]/.test(text) ? { ok: true, value: text } : { ok: false, reason: "use a single line of 1 to 300 characters" };
+  }
+}
+
+                           
+                   
+                                                                                                     
+                                                                      
+                                                                          
+                   
+ 
+
+export function resolveSettings(root        , env                    = process.env)           {
+  const values = Object.fromEntries(SETTING_KEYS.map((k) => [k, SETTING_INFO[k].default]))                       ;
+  const sources = Object.fromEntries(SETTING_KEYS.map((k) => [k, "default"]))                       ;
+  let problem                    ;
+
+  if (existsSync(file(root))) {
+    try {
+      const stored = JSON.parse(readFileSync(file(root), "utf8"))                           ;
+      for (const k of SETTING_KEYS) {
+        if (!(k in stored)) continue;
+        const parsed = parseSetting(k, stored[k]);
+        if (parsed.ok) {
+          (values                                      )[k] = parsed.value;
+          sources[k] = "file";
+        } else {
+          problem = `${k} in the settings file is invalid (${parsed.reason}); the default is used`;
+        }
+      }
+    } catch (err) {
+      problem = `the settings file could not be read (${err instanceof Error ? err.message : String(err)}); the defaults are used`;
+    }
+  }
+  for (const k of SETTING_KEYS) {
+    const name = SETTING_INFO[k].env;
+    const raw = name ? env[name] : undefined;
+    if (!name || raw === undefined || raw === "") continue;
+    const parsed = parseSetting(k, raw);
+    if (parsed.ok) {
+      (values                                      )[k] = parsed.value;
+      sources[k] = "environment";
+    }
+  }
+  return { values, sources, ...(problem ? { problem } : {}) };
+}
+
+/** Writes one setting to the project's settings file. Throws an Error whose message says what is wrong. */
+export function writeSetting(root        , key        , raw        )           {
+  return writeSettings(root, { [key]: raw });
+}
+
+/** Writes several settings in one go: all are checked first, then saved with a single rename, so a failure leaves none of them half applied. */
+export function writeSettings(root        , entries                        )           {
+  const checked                                                    = [];
+  for (const [key, raw] of Object.entries(entries)) {
+    if (!SETTING_KEYS.includes(key                  )) throw new Error(`Unknown setting "${key}". Settings: ${SETTING_KEYS.join(", ")}.`);
+    const k = key                  ;
+    const parsed = parseSetting(k, raw);
+    if (!parsed.ok) throw new Error(`${k}: ${parsed.reason}.`);
+    checked.push([k, parsed.value]);
+  }
+  let stored                          = {};
+  try {
+    if (existsSync(file(root))) stored = JSON.parse(readFileSync(file(root), "utf8"))                           ;
+  } catch {
+    stored = {}; // a broken file is replaced, not extended
+  }
+  for (const [k, value] of checked) stored[k] = value;
+  mkdirSync(dirname(file(root)), { recursive: true });
+  const tmp = `${file(root)}.tmp`;
+  writeFileSync(tmp, JSON.stringify(stored, null, 2), { mode: 0o600 });
+  renameSync(tmp, file(root));
+  return resolveSettings(root).values;
+}
+
+export function resetSettings(root        )       {
+  rmSync(file(root), { force: true });
+}
+
+export function describeSettings(root        , env                    = process.env)         {
+  const { values, sources, problem } = resolveSettings(root, env);
+  const lines = SETTING_KEYS.map((k) => `${k.padEnd(21)} ${String(values[k]).padEnd(12)} ${sources[k] === "default" ? "(default)" : `(${sources[k]})`}  ${SETTING_INFO[k].description}`);
+  lines.push("", `File: ${settingsPath(root)}`);
+  if (problem) lines.push(`Note: ${problem}.`);
+  return lines.join("\n");
+}
+
+/** What a session is told about the journal. Empty when it is off. */
+export function journalPolicy(level                     )         {
+  if (level === "off") return "";
+  const when =
+    level === "detailed"
+      ? "after each step you take (what you changed, which files, what you decided and why, what comes next)"
+      : "after each milestone you finish (a feature done, a bug found or fixed, a decision made, what comes next)";
+  return `The user turned the journal on (${level}): ${when}, call meshingly_journal with one to three sentences. The other sessions in this collaboration, including your own later ones on other computers, read these notes to know what happened here, and everyone in the collaboration can read them. Never put secrets in a note.`;
+}
+
+/** Appended to the prompt of an unattended run. */
+export function questionPolicy(onQuestion                        )         {
+  if (onQuestion === "stop") {
+    return "Nobody is at the keyboard. If you need an answer from the user to go on, do not guess: call meshingly_handoff with needsPerson=true, the question and what you have done so far, then stop.";
+  }
+  return [
+    "Nobody is at the keyboard, and the user chose that you carry on instead of waiting.",
+    "When you would ask the user to choose, take the option you would recommend, write down the assumption you made, and continue. Put every such assumption in your final summary and in meshingly_done.",
+    "Exception: never decide for the user anything that deletes data, spends money, publishes, pushes, or contacts other people. For those, call meshingly_handoff with needsPerson=true, the question and what you have done so far, then stop.",
+  ].join(" ");
+}

package/dist/watch.js

@@ -0,0 +1,328 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { BEAT_MS, clearBeat, killTree, stateFile, takeCurrentRun, writeBeat } from "./background.js";
+import { Meshingly, ToolError } from "./connection.js";
+import { LEASE_MS } from "./queue.js";
+import { questionPolicy, resolveSettings,               } from "./settings.js";
+
+                               
+                                                                                          
+                  
+                     
+                                                                             
+                
+                                                                              
+                     
+                                                                              
+                                     
+                                                             
+                      
+                                                                                                                  
+                   
+                                                                                                                 
+                   
+                                                                                                              
+                    
+                      
+                              
+ 
+
+const HELP = `meshingly-mcp watch: wakes up an AI session when work is waiting in the Meshingly queue.
+
+Usage: npx -y meshingly-mcp watch [--cmd "claude -p"] [--interval 60] [--once] [--from-peers] [--on-question stop|recommended] [--dir <project>]
+
+It checks the queue; when a handoff is open and its "limit expected back" time has passed (a handoff without one
+waits a few minutes, in case its session is still working), it claims the handoff and starts the command with the
+handoff as the prompt, in the project directory. If the command succeeds the handoff is marked finished. If it fails
+(for example the usage limit is still out) the handoff goes back to the queue and is retried later, up to
+--max-attempts times. Handoffs marked as a question for a person are never run.
+
+  --cmd             Command that reads the prompt from stdin. Default: claude -p
+                    Add the permissions the work needs yourself, e.g. "claude -p --permission-mode acceptEdits".
+  --interval        Seconds between checks. Default 60.
+  --once            Check once and exit, so cron or Task Scheduler can run it.
+  --from-peers      Also run handoffs written by OTHER sessions. By default only this project's own session is
+                    trusted, because a handoff is text that starts an AI agent on your computer: enable this
+                    only for a collaboration whose members you trust.
+  --on-question     What a run does when it would ask you something: stop (default) or recommended.
+  --max-attempts    Default 3.
+  --settle-minutes  Default 5.
+  --dir             Project directory holding .meshingly/. Default: the current directory.
+
+Every option has a setting that is used when the flag is absent: npx -y meshingly-mcp settings
+`;
+
+function sleep(ms        , signal             )                {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve();
+    const done = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal.addEventListener("abort", done, { once: true });
+  });
+}
+
+/** Runs the command with the prompt on stdin and resolves with its exit code (124 when it was stopped for running too long). */
+function runCommand(command        , prompt        , cwd        , env                   , maxRunMs        , signal             )                  {
+  return new Promise((resolve, reject) => {
+    // Detached on POSIX: its own process group, so a timeout can end the agent and not just the shell around it.
+    const child = spawn(command, { shell: true, cwd, env, stdio: ["pipe", "inherit", "inherit"], detached: process.platform !== "win32" });
+    let timedOut = false;
+    const stop = () => {
+      if (child.pid) killTree(child.pid);
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      stop();
+    }, maxRunMs);
+    signal.addEventListener("abort", stop, { once: true });
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", stop);
+      resolve(timedOut ? 124 : (code ?? 1));
+    });
+    // A command that exits before reading its input closes the pipe: that is a failed run, not a crash of the watcher.
+    child.stdin.on("error", () => {});
+    child.stdin.end(prompt);
+  });
+}
+
+/** Failed attempts and retry times per handoff, kept on disk: `--once` under cron and every restart would otherwise start from zero. */
+                 
+                                
+                               
+                                                                                                            
+                   
+ 
+
+function loadState(root        )        {
+  const st        = { attempts: new Map(), retryAt: new Map() };
+  try {
+    if (!existsSync(stateFile(root))) return st;
+    const raw = JSON.parse(readFileSync(stateFile(root), "utf8"))                                                                             ;
+    for (const [id, n] of Object.entries(raw.attempts ?? {})) if (typeof n === "number") st.attempts.set(id, n);
+    for (const [id, n] of Object.entries(raw.retryAt ?? {})) if (typeof n === "number") st.retryAt.set(id, n);
+  } catch {
+    /* a damaged file means a fresh start, not a crash */
+  }
+  return st;
+}
+
+/** Writes the state, keeping only handoffs that still exist. */
+function saveState(root        , st       , live             )       {
+  const pick = (m                     ) => Object.fromEntries([...m].filter(([id]) => live.has(id)));
+  try {
+    mkdirSync(join(root, ".meshingly"), { recursive: true });
+    const tmp = `${stateFile(root)}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ attempts: pick(st.attempts), retryAt: pick(st.retryAt), ...(st.current ? { current: st.current } : {}) }));
+    renameSync(tmp, stateFile(root));
+  } catch {
+    /* losing the counters is better than stopping the watcher */
+  }
+}
+
+/** Looks at the queue once and runs at most one handoff. Returns whether it ran one. */
+async function pass(m           , o              , st       , root        )                   {
+  const { items, self } = await m.openHandoffs();
+  const now = Date.now();
+  const known = new Set(items.map((h) => h.id));
+  for (const h of items) {
+    if (o.signal.aborted) return false;
+    if (h.status !== "open") continue; // someone is on it (a live session of this project included)
+    if (h.needsPerson) continue; // a question for a human, not work for an agent
+    if (!o.fromPeers && h.fromSessionId !== self) continue;
+    if ((st.attempts.get(h.id) ?? 0) >= o.maxAttempts) continue;
+    if ((st.retryAt.get(h.id) ?? 0) > now) continue;
+    if (h.resetsAt) {
+      if (Date.parse(h.resetsAt) > now) continue; // the limit is not back yet
+    } else if (now - h.createdAt < o.settleMs) {
+      continue; // no reset time: the session that parked it may still be working
+    }
+
+    let prompt        ;
+    try {
+      prompt = await m.claim({ id: h.id });
+    } catch (err) {
+      if (err instanceof ToolError) {
+        o.log(`"${h.title}": ${err.message}`);
+        continue;
+      }
+      throw err;
+    }
+    const attempt = (st.attempts.get(h.id) ?? 0) + 1;
+    st.attempts.set(h.id, attempt);
+    st.current = h.id;
+    saveState(root, st, known);
+    o.log(`"${h.title}": claimed, starting the command (attempt ${attempt}/${o.maxAttempts})`);
+
+    const full = `${prompt}\n\nContinue this work in the current project directory. When it is finished, call meshingly_done with handoff id ${h.id}. If you are about to run out of usage again, call meshingly_handoff with the new state and stop.\n\n${questionPolicy(o.onQuestion)}`;
+    let code        ;
+    try {
+      code = await runCommand(o.command, full, root, { ...process.env, MESHINGLY_DIR: root }, o.maxRunMs, o.signal);
+    } catch (err) {
+      o.log(`"${h.title}": could not start the command: ${err instanceof Error ? err.message : String(err)}`);
+      code = 127;
+    }
+    st.current = undefined;
+
+    // The run may have parked its own continuation (usage ran out again, or it has a question). That new handoff
+    // replaces this one, and it inherits the attempt count and waits like a failure would: otherwise it would be
+    // picked up at once, with fresh counters, in an endless loop. (A handoff parked meanwhile by the project's own live
+    // session looks the same from here: it is only delayed, never lost.)
+    const after = await m.openHandoffs();
+    const parked = after.items.filter((n) => !known.has(n.id) && n.fromSessionId === self && n.status === "open");
+    const wait = o.backoffMs * attempt;
+    for (const n of parked) {
+      st.attempts.set(n.id, attempt);
+      st.retryAt.set(n.id, Date.now() + wait);
+      o.log(`"${n.title}": parked by the run; it will not be started before ${new Date(Date.now() + wait).toISOString()}`);
+    }
+    if (parked.length > 0) {
+      // Whatever the exit code, the continuation carries the work forward: handing the original back too would leave two copies.
+      await m.done({ id: h.id, summary: "continued in a new handoff" });
+      o.log(`"${h.title}": replaced by the handoff the run parked`);
+    } else if (code === 0) {
+      // The agent normally reports "done" itself; this makes it so when it did not (the call is idempotent).
+      await m.done({ id: h.id, summary: "finished by the watcher's run" });
+      o.log(`"${h.title}": finished`);
+    } else {
+      await m.release({ id: h.id });
+      st.retryAt.set(h.id, Date.now() + wait);
+      o.log(
+        attempt >= o.maxAttempts
+          ? `"${h.title}": failed (exit ${code}); giving up after ${attempt} attempts, it stays in the queue for a person or another session`
+          : `"${h.title}": failed (exit ${code}); back in the queue, next try in ${Math.round(wait / 60000)} min`,
+      );
+    }
+    saveState(root, st, new Set([...known, ...after.items.map((n) => n.id)]));
+    return true;
+  }
+  saveState(root, st, known);
+  return false;
+}
+
+export async function watch(m           , o              , root        )                {
+  // A watcher that was killed in the middle of a run left its claim behind: give it back instead of making everyone wait for the lease.
+  const stale = takeCurrentRun(root);
+  if (stale) {
+    try {
+      await m.release({ id: stale });
+      o.log(`gave back a handoff that a previous watcher was working on when it stopped`);
+    } catch (err) {
+      o.log(`could not give back an interrupted handoff: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  const st = loadState(root);
+  while (!o.signal.aborted) {
+    try {
+      // Drain what is ready; a failed item waits for its retry time, so this cannot spin.
+      while (await pass(m, o, st, root)) {
+        /* next item */
+      }
+    } catch (err) {
+      o.log(`check failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (o.once) return;
+    await sleep(o.intervalMs, o.signal);
+  }
+}
+
+/** Entry point for `meshingly-mcp watch ...`. Returns the process exit code. */
+export async function runWatch(argv          )                  {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        cmd: { type: "string" },
+        interval: { type: "string" },
+        once: { type: "boolean", default: false },
+        "from-peers": { type: "boolean" },
+        "on-question": { type: "string" },
+        "max-attempts": { type: "string" },
+        "settle-minutes": { type: "string" },
+        dir: { type: "string" },
+        help: { type: "boolean", default: false },
+      },
+    }));
+  } catch (err) {
+    console.error(`${err instanceof Error ? err.message : String(err)}\n\n${HELP}`);
+    return 2;
+  }
+  if (values.help) {
+    console.log(HELP);
+    return 0;
+  }
+  const root = values.dir ?? process.env.MESHINGLY_DIR ?? process.cwd();
+  // A flag wins; otherwise the setting (which an environment variable in the MCP configuration overrides).
+  const saved = resolveSettings(root);
+  const interval = values.interval === undefined ? saved.values.checkIntervalSeconds : Number(values.interval);
+  const maxAttempts = values["max-attempts"] === undefined ? saved.values.maxAttempts : Number(values["max-attempts"]);
+  const settleMinutes = values["settle-minutes"] === undefined ? saved.values.settleMinutes : Number(values["settle-minutes"]);
+  const onQuestion = values["on-question"] ?? saved.values.onQuestion;
+  const command = values.cmd ?? saved.values.resumeCommand;
+  const fromPeers = values["from-peers"] ?? saved.values.trustPeers;
+  if (
+    !(interval >= 5) ||
+    !Number.isInteger(maxAttempts) ||
+    maxAttempts < 1 ||
+    !(settleMinutes >= 0) ||
+    (onQuestion !== "stop" && onQuestion !== "recommended")
+  ) {
+    console.error(`--interval must be at least 5 seconds, --max-attempts a whole number of 1 or more, --settle-minutes 0 or more and --on-question stop or recommended.\n\n${HELP}`);
+    return 2;
+  }
+  const m = new Meshingly(root);
+  const stamp = (line        ) => console.error(`${new Date().toISOString()} meshingly watch: ${line}`);
+
+  if (!m.connected()) {
+    console.error("Connect this project first (ask your AI session to set up Meshingly; if .meshingly/connection.json is damaged, delete it), then run the watcher again.");
+    return 1;
+  }
+  console.error(m.status());
+  if (saved.problem) stamp(`warning: ${saved.problem}`);
+  const abort = new AbortController();
+  process.once("SIGINT", () => abort.abort());
+  process.once("SIGTERM", () => abort.abort());
+
+  // Proof of life for meshingly_watch_status and stop: a pid alone could be a stranger's after a reboot.
+  let beat                            ;
+  if (!values.once) {
+    writeBeat(root);
+    beat = setInterval(() => writeBeat(root), BEAT_MS);
+    beat.unref();
+  }
+  stamp(`watching the queue every ${interval}s with "${command}"${fromPeers ? " (also handoffs from peers)" : " (own handoffs only)"}, on a question: ${onQuestion}`);
+  try {
+    await watch(
+      m,
+      {
+        command,
+        intervalMs: interval * 1000,
+        once: values.once === true,
+        fromPeers,
+        onQuestion,
+        maxAttempts,
+        settleMs: settleMinutes * 60_000,
+        maxRunMs: LEASE_MS - 10 * 60_000,
+        backoffMs: 30 * 60_000,
+        signal: abort.signal,
+        log: stamp,
+      },
+      root,
+    );
+  } finally {
+    if (beat) clearInterval(beat);
+    if (!values.once) clearBeat(root);
+  }
+  return 0;
+}