mobile-automator 0.30.0 → 0.31.0

package/README.md

@@ -73,6 +73,8 @@ In **Cursor**, `init` installs a project rule instead — just ask the agent in
 
 That's it. Scenarios land in `mobile-automator/scenarios/`, results in `mobile-automator/results/`.
 
+**Upgrading:** after `npm i -g mobile-automator@latest`, re-run `mauto init --agent <host>` in each project to refresh the skills, rules and commands it installed. Until you do, `mauto guide` starts with a notice that the host integration is out of date, and `mauto doctor` reports which hosts need refreshing.
+
 ---
 
 ## 🧠 How it works
@@ -135,6 +137,7 @@ Most low-level verbs are called **by the agent**, not by you. The ones you'll ru
 | Command | What it does |
 |---------|--------------|
 | `mauto init --agent <claude\|cursor\|gemini\|copilot\|agents\|all>` | Install native Agent Skills into each host's skills directory; also writes slash-commands/rules + MCP entry for claude/cursor |
+| `mauto doctor` | Report whether the integration `init` installed is missing or out of date, and the `init` command that refreshes it |
 | `mauto setup [--mode aware\|agnostic]` | Scaffold the `mobile-automator/` workspace + config |
 | `mauto devices` · `devices use <id>` · `devices clear` | List / pin / unpin the target device |
 | `mauto guide <generate\|execute\|setup>` | Print the workflow guidance for a topic |

package/bin/mauto.js

@@ -10,4 +10,5 @@ const { run, emitFatal } = require('../src/cli');
 // exit-on-reject listener.
 process.on('unhandledRejection', emitFatal);
 
-run(process.argv);
+// run() catches everything into emitFatal itself, so the promise never rejects.
+void run(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-automator",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Host-agnostic mauto CLI for AI-driven mobile QA automation — analyzes a mobile project and drives devices through mobile-mcp.",
   "homepage": "https://github.com/sh3lan93/mobile-automator#readme",
   "repository": {
@@ -26,6 +26,7 @@
     "prepublishOnly": "npm test",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
+    "lint": "eslint .",
     "lint:guides": "jest tests/lint",
     "lint:schema-additive": "jest tests/lint/schema-additive.test.js",
     "test:unit": "jest tests/unit",
@@ -39,9 +40,15 @@
     "commander": "^12.1.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^22.20.5",
+    "eslint": "^9.39.5",
+    "globals": "^17.13.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
-    "js-yaml": "^4.3.2"
+    "js-yaml": "^4.3.2",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.72.0"
   },
   "engines": {
     "node": ">=22.12.0"

package/src/cli.js

@@ -7,7 +7,6 @@ const { Command } = require('commander');
 const { version: PKG_VERSION } = require('../package.json');
 
 const { ok, fail, render, exitCodeFor } = require('./output/envelope');
-const { DeviceBridge } = require('./device/bridge');
 const selectionStore = require('./device/selection');
 const { engineHint } = require('./device/engine-hints');
 const { ScenarioValidator } = require('./scenario/validator');
@@ -24,6 +23,9 @@ const { validateAt } = require('./config/schema');
 const { scaffold } = require('./setup/scaffold');
 const guideEmitter = require('./guide/emitter');
 const { ADAPTERS } = require('./init/adapters');
+const { inspectHosts, ADVISORY_FS_CODES } = require('./init/host-plan');
+const { renderStaleNotice, installedBefore, refreshHint } = require('./init/stale-notice');
+const { doctorReport } = require('./init/doctor');
 const { isSemanticAction, ACTION_METHOD, selectResolver } = require('./device/semantic-press');
 const connection = require('./device/connection');
 const { isSupportedHost, unsupportedHostError } = require('./device/host-support');
@@ -991,7 +993,20 @@ async function handleTelemetryFlush({ projectRoot, env = process.env, flusher })
 }
 
 // RAW content on success; fail envelope only when the topic is unknown.
-function handleGuide({ projectRoot, emitter = guideEmitter, config = configManager }, topic) {
+//
+// #144: when a host integration `mauto init` wrote is missing or out of date,
+// a notice is prepended. It lives HERE and never inside emitter.emitGuide /
+// emitBootstrap: init embeds emitBootstrap in the cursor rule and the MCP
+// prompts server serves emitGuide, so putting it there would make init's
+// output depend on workspace state (and break byte-identical reruns). The
+// inspection is advisory: a filesystem fault that means "the workspace's
+// integration files can't be read" simply yields no notice, while any other
+// failure escapes to the envelope boundary — a defect in the inspection must
+// be visible, not silently disable the notice forever.
+function handleGuide(
+  { projectRoot, emitter = guideEmitter, config = configManager, inspect = inspectHosts },
+  topic
+) {
   const cfg = config.load(projectRoot);
   const mode = config.resolveMode(cfg);
   let raw;
@@ -1003,6 +1018,14 @@ function handleGuide({ projectRoot, emitter = guideEmitter, config = configManag
       exitKind: 'invalid_input',
     };
   }
+  let stale;
+  try {
+    stale = inspect(projectRoot).filter((h) => h.stale);
+  } catch (err) {
+    if (!(err && ADVISORY_FS_CODES.has(err.code))) throw err;
+    stale = [];
+  }
+  if (stale.length) raw = renderStaleNotice(stale) + raw;
   return { raw, exitKind: 'ok' };
 }
 
@@ -1130,7 +1153,7 @@ function hintForAdapterError(cls) {
 function applyOneAdapter(adapter, agent, projectRoot) {
   try {
     const r = adapter.apply({ projectRoot });
-    return { agent, ok: true, written: r.written, merged: r.merged };
+    return { agent, ok: true, changes: r.changes };
   } catch (err) {
     return {
       agent,
@@ -1141,15 +1164,16 @@ function applyOneAdapter(adapter, agent, projectRoot) {
   }
 }
 
-function handleInit({ projectRoot, adapters = ADAPTERS }, agent) {
+function handleInit({ projectRoot, adapters = ADAPTERS, inspect = inspectHosts }, agent) {
   const known = Object.keys(adapters);
   if (agent === 'all') {
+    const wasInstalled = installedBefore(inspect, projectRoot);
     // Continue-on-error: every host is attempted; the result is ONE envelope
     // carrying a per-agent ok/failed map. `ok` only when all succeed.
     const perAgent = known.map((a) => applyOneAdapter(adapters[a], a, projectRoot));
     const failed = perAgent.filter((r) => !r.ok);
     if (failed.length === 0) {
-      return { envelope: ok({ agents: perAgent }), exitKind: 'ok' };
+      return { envelope: ok({ agents: perAgent }, refreshHint(perAgent, wasInstalled)), exitKind: 'ok' };
     }
     return {
       envelope: fail(
@@ -1172,6 +1196,7 @@ function handleInit({ projectRoot, adapters = ADAPTERS }, agent) {
       exitKind: 'invalid_input',
     };
   }
+  const wasInstalled = installedBefore(inspect, projectRoot);
   const r = applyOneAdapter(adapter, agent, projectRoot);
   if (!r.ok) {
     // A malformed host config is the user's input, not an environment fault —
@@ -1189,11 +1214,21 @@ function handleInit({ projectRoot, adapters = ADAPTERS }, agent) {
     };
   }
   return {
-    envelope: ok({ agent: r.agent, written: r.written, merged: r.merged }),
+    envelope: ok({ agent: r.agent, changes: r.changes }, refreshHint([r], wasInstalled)),
     exitKind: 'ok',
   };
 }
 
+// `mauto doctor` (#144): report whether the host integration `mauto init`
+// wrote is missing or out of date. A report, not a gate — always ok. The
+// report itself (data + hint) lives in src/init/doctor.js; this is the
+// handler-shape adapter to the emit contract. An unexpected fs error from the
+// inspection (EACCES, ...) is left to the envelope boundary to classify.
+function handleDoctor({ projectRoot, inspect = inspectHosts }) {
+  const { data, hint } = doctorReport({ projectRoot, inspect });
+  return { envelope: ok(data, hint), exitKind: 'ok' };
+}
+
 // --- Issue #91: persistent device session daemon -------------------------
 //
 // `mauto session start|status|end` manage the per-workspace daemon that holds
@@ -1210,7 +1245,7 @@ async function handleSessionStart(
     projectRoot,
     spawn = require('./device/session-spawn'),
     client = require('./device/session-client'),
-    readHandle = require('./device/resolve-connection').readHandleDevice,
+    readHandle: readHandleDevice = require('./device/resolve-connection').readHandleDevice,
   },
   opts = {}
 ) {
@@ -1233,7 +1268,7 @@ async function handleSessionStart(
     // pinned to A reported already_running:true, device:B while every verb
     // kept driving A. Fail with a hint instead — the agent stays in control
     // and decides whether to `session end` and repin.
-    const pinned = readHandle(projectRoot);
+    const pinned = readHandleDevice(projectRoot);
     if (device !== null && device !== pinned) {
       return {
         envelope: fail(
@@ -1391,7 +1426,7 @@ async function handleDevicesClear({
   store = selectionStore,
   projectRoot,
   isAlive = require('./device/connection').isSessionAlive,
-  readHandle = require('./device/resolve-connection').readHandleDevice,
+  readHandle: readHandleDevice = require('./device/resolve-connection').readHandleDevice,
 } = {}) {
   const previous = store.read(projectRoot);
   store.clear(projectRoot);
@@ -1403,7 +1438,7 @@ async function handleDevicesClear({
   if (!alive) {
     return { envelope: ok({ cleared: previous || null }), exitKind: 'ok' };
   }
-  const pinned = readHandle(projectRoot);
+  const pinned = readHandleDevice(projectRoot);
   return {
     envelope: ok(
       { cleared: previous || null, daemon_still_pinned: pinned },
@@ -2126,6 +2161,13 @@ function buildProgram(deps = {}) {
       emit(r, humanFlag());
     }));
 
+  // No requireWorkspace: like guide, doctor runs on the discovered workspace
+  // or cwd, and must work before `mauto setup` has ever run.
+  program
+    .command('doctor')
+    .description("Report whether this project's agent integration (mauto init) is missing or out of date")
+    .action(withEnvelope(() => emit(handleDoctor({ projectRoot }), humanFlag())));
+
   // --- Issue #91: device session lifecycle ---------------------------------
 
   const session = program
@@ -2325,7 +2367,7 @@ function makeEmitters({ projectRoot = process.cwd() } = {}) {
   // needed). A Date.now() stamped at require time would measure from whenever
   // cli.js was loaded, which is not process start for anything that requires it
   // first (a test harness, bin/mauto.js's own guards).
-  function finish({ text = '', exitKind, ok, errorKind, exitCode = exitCodeFor(exitKind) }) {
+  function finish({ text = '', exitKind, ok: succeeded, errorKind, exitCode = exitCodeFor(exitKind) }) {
     // The flag-resolved id when a command parsed, the environment otherwise: a
     // parse failure reaches no preAction hook and so has no flag, but it is
     // still part of the run and is exactly the class of failure (#146) this
@@ -2355,7 +2397,7 @@ function makeEmitters({ projectRoot = process.cwd() } = {}) {
       // tying this line to a run. sends:false in the event catalog.
       run_id: runId || undefined,
       session_id: resolvedSessionId || undefined,
-      ok,
+      ok: succeeded,
       error_kind: errorKind,
       exit_code: exitCode,
       dur_ms: Math.round(process.uptime() * 1000),
@@ -2498,6 +2540,7 @@ module.exports = {
   handleMemoryAdd,
   handleMemoryForget,
   handleInit,
+  handleDoctor,
   handleSessionStart,
   handleSessionStatus,
   handleSessionEnd,

package/src/device/bridge.js

@@ -44,7 +44,7 @@ class DeviceBridge {
   // Tap at absolute screen coordinates. The agent derives x,y from listElements
   // centers, so the bridge stays free of any element targeting logic.
   async tap({ x, y } = {}) {
-    return this._call('mobile_click_on_screen_at_coordinates', { x, y });
+    return await this._call('mobile_click_on_screen_at_coordinates', { x, y });
   }
 
   // Long-press at absolute screen coordinates. Optional duration (ms) overrides
@@ -52,18 +52,18 @@ class DeviceBridge {
   async longPress({ x, y, duration } = {}) {
     const args = { x, y };
     if (duration !== undefined) args.duration = duration;
-    return this._call('mobile_long_press_on_screen_at_coordinates', args);
+    return await this._call('mobile_long_press_on_screen_at_coordinates', args);
   }
 
   // Double-tap at absolute screen coordinates.
   async doubleTap({ x, y } = {}) {
-    return this._call('mobile_double_tap_on_screen', { x, y });
+    return await this._call('mobile_double_tap_on_screen', { x, y });
   }
 
   // Type into the focused element. We never auto-submit; pressing ENTER is a
   // distinct, explicit action via pressButton.
   async type(text) {
-    return this._call('mobile_type_keys', { text, submit: false });
+    return await this._call('mobile_type_keys', { text, submit: false });
   }
 
   // Swipe in a cardinal direction.
@@ -135,32 +135,32 @@ class DeviceBridge {
 
   // Press a hardware/system button (BACK, HOME, ENTER, ...).
   async pressButton(button) {
-    return this._call('mobile_press_button', { button });
+    return await this._call('mobile_press_button', { button });
   }
 
   // Launch an installed app by its package/bundle identifier.
   async launchApp(packageName) {
-    return this._call('mobile_launch_app', { packageName });
+    return await this._call('mobile_launch_app', { packageName });
   }
 
   // Install an app from a local artifact (apk/ipa) path.
   async installApp(appPath) {
-    return this._call('mobile_install_app', { path: appPath });
+    return await this._call('mobile_install_app', { path: appPath });
   }
 
   // Uninstall an app by its bundle/package identifier.
   async uninstallApp(appId) {
-    return this._call('mobile_uninstall_app', { bundle_id: appId });
+    return await this._call('mobile_uninstall_app', { bundle_id: appId });
   }
 
   // Open a URL (deep link or web) on the device.
   async openUrl(url) {
-    return this._call('mobile_open_url', { url });
+    return await this._call('mobile_open_url', { url });
   }
 
   // Set the device orientation ('portrait'/'landscape').
   async setOrientation(orientation) {
-    return this._call('mobile_set_orientation', { orientation });
+    return await this._call('mobile_set_orientation', { orientation });
   }
 
   // Crash reports currently readable on the device, as the agnostic crash

package/src/device/mobile-mcp-client.js

@@ -133,8 +133,8 @@ async function createCall({
     throw connectError(err, connectTimeoutMs);
   }
 
-  async function rawCall(toolName, args = {}) {
-    const res = await client.callTool({ name: toolName, arguments: args });
+  async function rawCall(toolName, toolArgs = {}) {
+    const res = await client.callTool({ name: toolName, arguments: toolArgs });
     return parseToolResult(res);
   }
   const { call } = makeCall({ rawCall, device });

package/src/device/resolve-connection.js

@@ -31,8 +31,6 @@ function defaultCreateCall(opts) {
   return require('./mobile-mcp-client').createCall(opts);
 }
 
-const NOOP_CLOSE = () => Promise.resolve();
-
 // Read the live daemon's pinned device from its handle, or null. A null pin
 // means the daemon serves whatever device mobile-mcp selected (matches any
 // request that doesn't pin a specific device).

package/src/device/session-daemon.js

@@ -386,7 +386,13 @@ async function startDaemon({
     clearFlush();
     if (!flush || stopping) return;
     if (!(delayMs > 0) || !Number.isFinite(delayMs)) return;
-    flushTimer = setTimeout(async () => {
+    // tick() never rejects (its flush() is wrapped), so `void` is honest here.
+    flushTimer = setTimeout(() => {
+      void tick();
+    }, delayMs);
+    if (typeof flushTimer.unref === 'function') flushTimer.unref();
+
+    async function tick() {
       if (stopping) return;
       if (inFlight > 0) {
         armFlush(delayMs);
@@ -402,8 +408,7 @@ async function startDaemon({
         // current caller.
       }
       armFlush(next);
-    }, delayMs);
-    if (typeof flushTimer.unref === 'function') flushTimer.unref();
+    }
   }
 
   async function stop(reason = 'explicit') {
@@ -541,7 +546,27 @@ async function startDaemon({
       return true;
     };
 
-    socket.on('data', async (chunk) => {
+    // A plain listener around an async body, never `socket.on('data', async …)`:
+    // the emitter ignores the returned promise, so a throw in the body would be
+    // an unhandled rejection, and bin/mauto-session-daemon.js exits on those.
+    // Found by @typescript-eslint/no-misused-promises (#164).
+    socket.on('data', (chunk) => {
+      handleData(chunk).catch(onHandlerError);
+    });
+
+    // Recorded, then the idle clock re-armed: handleData paused it for the
+    // frame that threw, and nothing else would restart it. The remaining frames
+    // of that chunk are lost; the socket and the daemon both keep serving.
+    function onHandlerError(err) {
+      safeObserve({
+        level: 'error',
+        event: 'daemon.handler_error',
+        message: err && (err.message || String(err)),
+      });
+      armIdle();
+    }
+
+    async function handleData(chunk) {
       const frames = parser.push(chunk);
       for (const f of frames) {
         // Pause the idle clock while we handle a frame so it can never fire
@@ -554,11 +579,20 @@ async function startDaemon({
           continue;
         }
         const req = f.value;
+        // Valid JSON is not yet a request: `null` would throw on `req.type`
+        // below, and a primitive or array is no frame the protocol defines.
+        if (req === null || typeof req !== 'object' || Array.isArray(req)) {
+          await reply({ id: null, ok: false, error: { message: 'malformed frame: not a JSON object' } });
+          armIdle();
+          continue;
+        }
 
         if (req.type === 'shutdown') {
           await reply({ id: req.id, ok: true, result: { stopping: true } });
           // Reply already flushed (awaited) — now tear down.
-          setImmediate(() => stop('shutdown').catch(() => {}));
+          setImmediate(() => {
+            stop('shutdown').catch(() => {});
+          });
           continue;
         }
         if (req.type === 'ping') {
@@ -616,7 +650,7 @@ async function startDaemon({
         await reply({ id: req.id, ok: false, error: { message: `unknown request type: ${req.type}` } });
         armIdle();
       }
-    });
+    }
 
     socket.on('error', () => {
       sockets.delete(socket);

package/src/guide/emitter.js

@@ -113,6 +113,7 @@ function emitBootstrap() {
     ['result', 'record step results and finalize a run'],
     ['setup', 'scaffold the workspace and write a config'],
     ['config', 'get/set values in the workspace config'],
+    ['doctor', 'report whether the agent integration `mauto init` installed is missing or out of date'],
     ['guide', 'print the guide for a workflow topic'],
     ['schema', 'print the scenario, result, or config JSON schema'],
   ];

package/src/init/adapters.js

@@ -7,82 +7,30 @@
 // yields byte-identical files). claude/cursor additionally keep writing their
 // thin slash-command/rule and merging the shared `mauto` MCP server entry.
 // Adapters never clobber a file they don't own.
+//
+// WHAT each host owns lives in host-plan.js (`planHost`); this module only
+// applies that plan, so the staleness detector and the writers share one
+// source (#144).
 
 const fs = require('fs');
 const path = require('path');
 
-const guideEmitter = require('../guide/emitter');
-const { renderSkill, readInvariants, SKILL_TOPICS } = require('./skill-renderer');
-const { SKILL_META } = require('./skill-meta');
-
-const TOPICS = ['generate', 'execute', 'setup'];
-
-// The single mauto MCP server entry merged into a vendor's mcp config.
-const MAUTO_SERVER = { command: 'mauto', args: ['mcp'] };
-
-// Per-agent skills directory (relative to projectRoot). claude uses its own
-// namespace; cursor/gemini/copilot each use their native dir; `agents` targets
-// the open-standard location.
-const SKILL_DEST = {
-  claude: path.join('.claude', 'skills'),
-  cursor: path.join('.cursor', 'skills'),
-  gemini: path.join('.gemini', 'skills'),
-  copilot: path.join('.github', 'skills'),
-  agents: path.join('.agents', 'skills'),
-};
-
-// BACK-COMPAT FALLBACK — NOT the live instruction surface for a current host.
-//
-// Claude Code merged custom commands into skills, and a same-named skill wins:
-//   "if a skill and a command share the same name, the skill takes precedence"
-//   https://code.claude.com/docs/en/skills
-// We write both `mobile-automator-<topic>.md` here and a skill folder of the
-// same name, so on any host with skills support THIS FILE IS NEVER READ.
-// Editing it to change agent behavior on a current host does nothing — change
-// `<topic>.invariants.md` (directives) or the guide content (workflow) instead.
-//
-// It still wins in two places, which is why it is kept and why it must not be
-// thin: a Claude Code old enough to predate skills, and a workspace whose last
-// `mauto init` predates the release that started writing skills. On both, this
-// file IS the registered surface — so it renders from the same two sources the
-// skill does (`SKILL_META` + `<topic>.invariants.md`) and can never drift into
-// being the weaker of the two. The `description` frontmatter matters for the
-// same reason: without it a host derives one by truncating the body, which
-// yields a description of the mechanism rather than of when to use this.
-function claudeCommandBody(topic) {
-  return (
-    '---\n' +
-    `description: ${SKILL_META[topic].description}\n` +
-    '---\n\n' +
-    `Run \`mauto guide ${topic}\` and follow it.\n\n` +
-    '## Non-negotiable directives (always apply)\n' +
-    `${readInvariants(topic)}\n`
-  );
-}
-
-function cursorRuleBody() {
-  return (
-    '---\n' +
-    'description: Mobile Automator — drive mobile QA through the mauto CLI.\n' +
-    'alwaysApply: true\n' +
-    '---\n\n' +
-    guideEmitter.emitBootstrap() +
-    '\nRun `mauto guide <topic>` (generate|execute|setup) before a workflow. ' +
-    'Drive the device only through `mauto` verbs.\n'
-  );
-}
+const { planHost, HOSTS, MAUTO_SERVER, SKILL_DEST } = require('./host-plan');
 
+// Returns 'created' | 'updated' | 'unchanged'.
 function writeIfChanged(filePath, content) {
   const prev = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
-  if (prev === content) return false;
+  if (prev === content) return 'unchanged';
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, content);
-  return true;
+  return prev === null ? 'created' : 'updated';
 }
 
+// Returns { changed, status } where status is 'created' | 'updated' | 'unchanged'.
 function mergeMcpConfig(filePath) {
   let doc = {};
-  if (fs.existsSync(filePath)) {
+  const existed = fs.existsSync(filePath);
+  if (existed) {
     const existing = fs.readFileSync(filePath, 'utf8');
     try {
       doc = JSON.parse(existing);
@@ -101,62 +49,31 @@ function mergeMcpConfig(filePath) {
   }
   doc.mcpServers.mauto = { ...MAUTO_SERVER };
   const next = JSON.stringify(doc, null, 2) + '\n';
-  const prev = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
-  if (prev === next) return { changed: false };
+  const prev = existed ? fs.readFileSync(filePath, 'utf8') : null;
+  if (prev === next) return { changed: false, status: 'unchanged' };
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, next);
-  return { changed: true };
-}
-
-// Install one SKILL.md folder per topic under the agent's skills dir. Only the
-// folders we own are written; foreign skill folders are never touched.
-function writeSkills(projectRoot, agent, written) {
-  const root = path.join(projectRoot, SKILL_DEST[agent]);
-  for (const topic of SKILL_TOPICS) {
-    const { dirName, content } = renderSkill(topic);
-    const file = path.join(root, dirName, 'SKILL.md');
-    writeIfChanged(file, content);
-    written.push(file);
-  }
+  return { changed: true, status: prev === null ? 'created' : 'updated' };
 }
 
-function makeAdapter(agent, extra) {
+function makeAdapter(agent) {
   return {
     apply({ projectRoot }) {
-      const written = [];
-      const merged = [];
-      if (extra) extra({ projectRoot, written, merged });
-      writeSkills(projectRoot, agent, written);
-      return { agent, written, merged };
+      const plan = planHost(agent);
+      const changes = [];
+      for (const { rel, content } of plan.files) {
+        const file = path.join(projectRoot, rel);
+        changes.push({ path: file, status: writeIfChanged(file, content) });
+      }
+      if (plan.mcp) {
+        const mcpPath = path.join(projectRoot, plan.mcp);
+        changes.push({ path: mcpPath, status: mergeMcpConfig(mcpPath).status });
+      }
+      return { agent, changes };
     },
   };
 }
 
-const ADAPTERS = {
-  claude: makeAdapter('claude', ({ projectRoot, written, merged }) => {
-    const commandsDir = path.join(projectRoot, '.claude', 'commands');
-    for (const topic of TOPICS) {
-      const file = path.join(commandsDir, `mobile-automator-${topic}.md`);
-      writeIfChanged(file, claudeCommandBody(topic));
-      written.push(file);
-    }
-    const mcpPath = path.join(projectRoot, '.mcp.json');
-    mergeMcpConfig(mcpPath);
-    merged.push(mcpPath);
-  }),
-
-  cursor: makeAdapter('cursor', ({ projectRoot, written, merged }) => {
-    const rulePath = path.join(projectRoot, '.cursor', 'rules', 'mobile-automator.mdc');
-    writeIfChanged(rulePath, cursorRuleBody());
-    written.push(rulePath);
-    const mcpPath = path.join(projectRoot, '.cursor', 'mcp.json');
-    mergeMcpConfig(mcpPath);
-    merged.push(mcpPath);
-  }),
-
-  gemini: makeAdapter('gemini'),
-  copilot: makeAdapter('copilot'),
-  agents: makeAdapter('agents'),
-};
+const ADAPTERS = Object.fromEntries(HOSTS.map((agent) => [agent, makeAdapter(agent)]));
 
 module.exports = { ADAPTERS, MAUTO_SERVER, SKILL_DEST };

package/src/init/doctor.js

@@ -0,0 +1,30 @@
+'use strict';
+
+// `mauto doctor` (#144): report whether the host integration `mauto init`
+// wrote is missing or out of date. A report, not a gate — the CLI always
+// renders it as an ok envelope. The inspection is honest: an unexpected fs
+// error from inspectHosts (EACCES, ...) propagates to the caller's envelope
+// boundary to classify, it is never swallowed.
+
+const { HOSTS } = require('./host-plan');
+const { initCommands } = require('./stale-notice');
+
+// Returns { data, hint } for the `mauto doctor` envelope.
+function doctorReport({ projectRoot, inspect }) {
+  const installed = inspect(projectRoot).filter((h) => h.installed);
+  const stale = installed.filter((h) => h.stale).map((h) => h.agent);
+  const data = {
+    initialised: installed.length > 0,
+    hosts: installed.map(({ agent, stale: s, files, mcp }) => ({ agent, stale: s, files, mcp })),
+    stale,
+  };
+  let hint = null;
+  if (stale.length) {
+    hint = initCommands(stale).map((c) => `run \`${c}\``).join('; ');
+  } else if (installed.length === 0) {
+    hint = `no host integration found — run \`mauto init --agent <host>\` (${HOSTS.join(' | ')} | all)`;
+  }
+  return { data, hint };
+}
+
+module.exports = { doctorReport };

package/src/init/host-plan.js

@@ -0,0 +1,197 @@
+'use strict';
+
+// HostPlan — the single source of "what `mauto init --agent <host>` owns".
+//
+// Every byte init writes is a pure function of the installed package: the
+// rendered skills, the claude command bodies, the cursor rule and the `mauto`
+// MCP server entry. None of it reads config.json. So "is this host's
+// integration stale?" is answered by "would init write different bytes?" — no
+// version stamp exists or is needed (#144).
+//
+// The writers (adapters.js) and the detector (inspectHosts) both read
+// `planHost`, so detection cannot drift from what init actually writes.
+
+const fs = require('fs');
+const path = require('path');
+const { isDeepStrictEqual } = require('util');
+
+const guideEmitter = require('../guide/emitter');
+const { renderSkill, readInvariants, SKILL_TOPICS } = require('./skill-renderer');
+const { SKILL_META } = require('./skill-meta');
+
+const TOPICS = ['generate', 'execute', 'setup'];
+
+// The single mauto MCP server entry merged into a vendor's mcp config.
+const MAUTO_SERVER = { command: 'mauto', args: ['mcp'] };
+
+// Per-agent skills directory (relative to projectRoot). claude uses its own
+// namespace; cursor/gemini/copilot each use their native dir; `agents` targets
+// the open-standard location.
+const SKILL_DEST = {
+  claude: path.join('.claude', 'skills'),
+  cursor: path.join('.cursor', 'skills'),
+  gemini: path.join('.gemini', 'skills'),
+  copilot: path.join('.github', 'skills'),
+  agents: path.join('.agents', 'skills'),
+};
+
+const HOSTS = Object.keys(SKILL_DEST);
+
+// Filesystem errno values that mean "the workspace's integration files can't
+// be read the way they normally sit" — a file or its parent is missing,
+// unreadable, or a directory sits where a file is expected. The advisory
+// surfaces that consume the inspection without failing (`guide`'s notice,
+// init's pre-run probe) treat these as "say nothing", never as a reason to
+// fail the verb. Any other errno (or a non-errno throw) escapes: a defect in
+// the inspection itself must be visible, not silently absorbed.
+const ADVISORY_FS_CODES = new Set(['ENOENT', 'EACCES', 'EPERM', 'EISDIR', 'ENOTDIR']);
+
+// BACK-COMPAT FALLBACK — NOT the live instruction surface for a current host.
+//
+// Claude Code merged custom commands into skills, and a same-named skill wins:
+//   "if a skill and a command share the same name, the skill takes precedence"
+//   https://code.claude.com/docs/en/skills
+// We write both `mobile-automator-<topic>.md` here and a skill folder of the
+// same name, so on any host with skills support THIS FILE IS NEVER READ.
+// Editing it to change agent behavior on a current host does nothing — change
+// `<topic>.invariants.md` (directives) or the guide content (workflow) instead.
+//
+// It still wins in two places, which is why it is kept and why it must not be
+// thin: a Claude Code old enough to predate skills, and a workspace whose last
+// `mauto init` predates the release that started writing skills. On both, this
+// file IS the registered surface — so it renders from the same two sources the
+// skill does (`SKILL_META` + `<topic>.invariants.md`) and can never drift into
+// being the weaker of the two. The `description` frontmatter matters for the
+// same reason: without it a host derives one by truncating the body, which
+// yields a description of the mechanism rather than of when to use this.
+function claudeCommandBody(topic) {
+  return (
+    '---\n' +
+    `description: ${SKILL_META[topic].description}\n` +
+    '---\n\n' +
+    `Run \`mauto guide ${topic}\` and follow it.\n\n` +
+    '## Non-negotiable directives (always apply)\n' +
+    `${readInvariants(topic)}\n`
+  );
+}
+
+function cursorRuleBody() {
+  return (
+    '---\n' +
+    'description: Mobile Automator — drive mobile QA through the mauto CLI.\n' +
+    'alwaysApply: true\n' +
+    '---\n\n' +
+    guideEmitter.emitBootstrap() +
+    '\nRun `mauto guide <topic>` (generate|execute|setup) before a workflow. ' +
+    'Drive the device only through `mauto` verbs.\n'
+  );
+}
+
+// One SKILL.md folder per topic under the agent's skills dir. Only the folders
+// we own are listed; foreign skill folders are never part of the plan.
+function skillFiles(agent) {
+  return SKILL_TOPICS.map((topic) => {
+    const { dirName, content } = renderSkill(topic);
+    return { rel: path.join(SKILL_DEST[agent], dirName, 'SKILL.md'), content };
+  });
+}
+
+// Everything init owns for one host, in write order. `files` are written whole;
+// `mcp` (when non-null) is the host config into which the `mauto` server entry
+// is merged. Paths are relative to the project root.
+function planHost(agent) {
+  if (!Object.prototype.hasOwnProperty.call(SKILL_DEST, agent)) {
+    throw new Error(`unknown agent: ${agent}`);
+  }
+  const files = [];
+  let mcp = null;
+  if (agent === 'claude') {
+    for (const topic of TOPICS) {
+      files.push({
+        rel: path.join('.claude', 'commands', `mobile-automator-${topic}.md`),
+        content: claudeCommandBody(topic),
+      });
+    }
+    mcp = '.mcp.json';
+  } else if (agent === 'cursor') {
+    files.push({
+      rel: path.join('.cursor', 'rules', 'mobile-automator.mdc'),
+      content: cursorRuleBody(),
+    });
+    mcp = path.join('.cursor', 'mcp.json');
+  }
+  files.push(...skillFiles(agent));
+  return { files, mcp };
+}
+
+function readOrNull(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+// The mauto entry is compared semantically — the user's formatting, key order
+// and other servers never make a host look stale.
+function inspectMcp(file) {
+  const raw = readOrNull(file);
+  if (raw === null) return { status: 'missing', hasEntry: false };
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    return { status: 'unreadable', hasEntry: false };
+  }
+  if (doc == null || typeof doc !== 'object' || Array.isArray(doc)) {
+    return { status: 'unreadable', hasEntry: false };
+  }
+  const servers = doc.mcpServers;
+  const entry =
+    servers && typeof servers === 'object' && !Array.isArray(servers) ? servers.mauto : undefined;
+  if (entry === undefined) return { status: 'missing', hasEntry: false };
+  return {
+    status: isDeepStrictEqual(entry, MAUTO_SERVER) ? 'current' : 'outdated',
+    hasEntry: true,
+  };
+}
+
+// Per-host report of what init owns vs. what is on disk. Never throws on a
+// malformed host config (that is reported as 'unreadable').
+function inspectHosts(projectRoot) {
+  return HOSTS.map((agent) => {
+    const plan = planHost(agent);
+    let installed = false;
+    const files = plan.files.map(({ rel, content }) => {
+      const abs = path.join(projectRoot, rel);
+      const onDisk = readOrNull(abs);
+      if (onDisk !== null) installed = true;
+      const status = onDisk === null ? 'missing' : onDisk === content ? 'current' : 'outdated';
+      return { path: abs, status };
+    });
+    let mcp = null;
+    if (plan.mcp) {
+      const abs = path.join(projectRoot, plan.mcp);
+      const { status, hasEntry } = inspectMcp(abs);
+      if (hasEntry) installed = true;
+      mcp = { path: abs, status };
+    }
+    const stale =
+      installed &&
+      (files.some((f) => f.status !== 'current') || (mcp !== null && mcp.status !== 'current'));
+    return { agent, installed, stale, files, mcp };
+  });
+}
+
+module.exports = {
+  HOSTS,
+  ADVISORY_FS_CODES,
+  MAUTO_SERVER,
+  SKILL_DEST,
+  TOPICS,
+  claudeCommandBody,
+  cursorRuleBody,
+  planHost,
+  inspectHosts,
+};

package/src/init/skill-renderer.js

@@ -21,7 +21,7 @@ const TITLES = {
 
 // The non-negotiable directives for a topic, verbatim from disk. Exported so
 // every surface that has to carry these directives renders them from this one
-// source rather than restating them — see `claudeCommandBody` in adapters.js.
+// source rather than restating them — see `claudeCommandBody` in host-plan.js.
 function readInvariants(topic) {
   return fs.readFileSync(path.join(CONTENT_DIR, `${topic}.invariants.md`), 'utf8').trim();
 }

package/src/init/stale-notice.js

@@ -0,0 +1,85 @@
+'use strict';
+
+// The advisory `mauto guide` prepends when a host integration that
+// `mauto init` wrote is missing or out of date (#144).
+//
+// Every surface init has ever written tells the agent to run
+// `mauto guide <topic>`, so a notice here reaches every stale workspace. It
+// tells the agent to TELL THE USER — init is never run on the user's behalf.
+//
+// The text is read by the agent alongside the guide, so it is held to the
+// guide lint guards: no OS names, no `{{`, no raw engine tool names
+// (tests/lint/stale-notice-fixture.js feeds it to them).
+
+const { HOSTS } = require('./host-plan');
+
+function byHostOrder(a, b) {
+  return HOSTS.indexOf(a) - HOSTS.indexOf(b);
+}
+
+// The init command(s) that refresh `agents`: one per host, in HOSTS order, or
+// the single `--agent all` when every host needs it.
+function initCommands(agents) {
+  const unique = [...new Set(agents)].sort(byHostOrder);
+  if (HOSTS.every((h) => unique.includes(h))) return ['mauto init --agent all'];
+  return unique.map((a) => `mauto init --agent ${a}`);
+}
+
+function describeHost(h) {
+  const statuses = h.files.map((f) => f.status);
+  if (h.mcp) statuses.push(h.mcp.status);
+  const missing = statuses.filter((s) => s === 'missing').length;
+  const outdated = statuses.filter((s) => s === 'outdated').length;
+  const parts = [];
+  if (missing) parts.push(`${missing} missing`);
+  if (outdated) parts.push(`${outdated} outdated`);
+  if (h.mcp && h.mcp.status === 'unreadable') parts.push('MCP config unreadable');
+  return `${h.agent} (${parts.join(', ')})`;
+}
+
+function joinList(items) {
+  if (items.length <= 2) return items.join(' and ');
+  return `${items.slice(0, -1).join(', ')}, and ${items[items.length - 1]}`;
+}
+
+// Which hosts already had an integration BEFORE this init run (#144). A
+// refresh of a host that was never installed is a fresh install, not an
+// upgrade, so it gets no hint. Advisory only — an inspection failure (an
+// unreadable workspace) must never fail init, so it means "no hosts".
+function installedBefore(inspect, projectRoot) {
+  try {
+    return new Set(inspect(projectRoot).filter((h) => h.installed).map((h) => h.agent));
+  } catch {
+    return new Set();
+  }
+}
+
+// `refreshed N stale file(s) for <agent>` for each previously-installed host
+// whose run created or updated anything; null when there is nothing to say.
+// `results` hold per-agent adapter results (`{ ok, agent, changes }`).
+function refreshHint(results, wasInstalled) {
+  const parts = [];
+  for (const r of results) {
+    if (!r.ok || !wasInstalled.has(r.agent)) continue;
+    const n = r.changes.filter((c) => c.status === 'created' || c.status === 'updated').length;
+    if (n > 0) parts.push(`refreshed ${n} stale file(s) for ${r.agent}`);
+  }
+  return parts.length ? parts.join('; ') : null;
+}
+
+// `staleHosts`: entries from inspectHosts() with `stale: true`. Returns a
+// markdown blockquote followed by a blank line, or '' when there is nothing
+// stale. Output is independent of input order.
+function renderStaleNotice(staleHosts) {
+  if (!staleHosts || staleHosts.length === 0) return '';
+  const hosts = [...staleHosts].sort((a, b) => byHostOrder(a.agent, b.agent));
+  const commands = initCommands(hosts.map((h) => h.agent)).map((c) => `\`${c}\``);
+  return (
+    '> **Notice — host integration out of date.** This project\'s agent integration was installed ' +
+    'by an older `mauto` and is missing or out of date: ' +
+    `${hosts.map(describeHost).join(', ')}. ` +
+    `Tell the user to run ${joinList(commands)} to refresh it, then continue with this guide.\n\n`
+  );
+}
+
+module.exports = { renderStaleNotice, initCommands, installedBefore, refreshHint };

package/src/mcp/server.js

@@ -31,11 +31,14 @@ function buildServer({ projectRoot } = {}) {
     { capabilities: { prompts: {} } }
   );
 
-  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  // Plain functions, not async: both handlers are synchronous, and the SDK
+  // accepts a result or a promise of one. It calls them inside a .then(), so a
+  // throw (an unknown prompt name) still becomes an MCP error reply.
+  server.setRequestHandler(ListPromptsRequestSchema, () => ({
     prompts: handlers.listPrompts(),
   }));
 
-  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  server.setRequestHandler(GetPromptRequestSchema, (request) => {
     return handlers.getPrompt(request.params.name);
   });
 

package/src/memory/entries.js

@@ -12,6 +12,7 @@ const ENTRY_RE = /^-\s+\[(\d{4}-\d{2}-\d{2})\]\[asserted\]\s+(.*)$/;
 
 function sanitizeEntryText(raw) {
   return String(raw == null ? '' : raw)
+    // eslint-disable-next-line no-control-regex -- matching control chars is the point
     .replace(/[\u0000-\u001F\u007F]+/g, ' ') // control chars / newlines / tabs -> space
     .replace(/\s+/g, ' ')
     .trim();

package/src/observe/vocab.js

@@ -46,6 +46,7 @@ const EVENT_NAMES = Object.freeze([
   'daemon.engine_exit',
   'daemon.lock_conflict',
   'daemon.undeliverable',
+  'daemon.handler_error',
   // Emitted by the flush path, which lands in a later slice-5 task; declared
   // now because its event shape is already exercised by unit tests.
   'telemetry.flush',
@@ -79,6 +80,7 @@ const VERB_NAMES = Object.freeze([
   'bootstrap',
   'memory',
   'init',
+  'doctor',
   'session',
   'devices',
   'crash',