scanruler-mcp 0.3.0 → 0.4.0

package/src/tools.js

@@ -6,10 +6,11 @@
 // it to the page; a command that hands a file back takes an optional path,
 // and this server writes the file there. The agent never sees the bytes —
 // but for a picture (a command marked returnsImage), which it is shown as an
-// image, and which is written to a file only when it gives a path.
+// image, and which is written to a file only when it gives a path — or, in
+// a batch, where it cannot be shown, always.
 
-import { readFile, stat, writeFile, mkdir } from 'node:fs/promises'
-import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
+import { readdir, readFile, stat, writeFile, mkdir } from 'node:fs/promises'
+import { basename, dirname, extname, isAbsolute, join, resolve } from 'node:path'
 
 export const toolName = (command) => command.name.replace(/\./g, '_')
 
@@ -31,10 +32,27 @@ const outPath = (outDir) => ({
   description: `Where to write the file: a file path, or a folder to write it into under the name ScanRuler gives it. Without it, it goes into ${outDir}.`,
 })
 
-const imagePath = {
+const imagePath = (outDir) => ({
   type: 'string',
   minLength: 1,
-  description: 'Also write the picture to a file: a file path, or a folder to write it into under the name ScanRuler gives it. Without it, it is only shown.',
+  description: `Also write the picture to a file: a file path, or a folder to write it into under the name ScanRuler gives it. Without it, it is only shown — but in scanruler_batch, which shows no picture, it is written into ${outDir} under a new name.`,
+})
+
+/** The `saveTo` a command that replaces the session takes — one with
+ *  `discard`: the session saved as a project file first (mcp.js). */
+const saveToIn = {
+  type: 'string',
+  minLength: 1,
+  description: 'Save the session as a .scanruler project file here first — a file path, or a folder to save it into under its own name — then go on as with discard: true. If the save fails nothing is replaced. The answer says where it went (savedTo).',
+}
+
+/** Whether a command replaces the session, refusing to over work unless
+ *  told `discard` — what `saveTo` is offered on. */
+export const replacesSession = (command) => command.input?.properties?.discard?.type === 'boolean'
+
+const inlineIn = {
+  type: 'boolean',
+  description: 'false, with path: the picture is written to the file and not shown — the answer says where. A picture costs far more context than its text; save the ones you only deliver.',
 }
 
 /** How many significant digits a number keeps in an answer, and the finest
@@ -60,11 +78,12 @@ export const agentJson = (value, exact = false) =>
   exact ? JSON.stringify(value) : JSON.stringify(value, (_key, v) => (typeof v === 'number' && Number.isFinite(v) && !Number.isInteger(v) ? tidy(v) : v))
 
 /** A command as the MCP tool an agent sees. */
-/** The `wait` a tool that changes the session takes: the server runs every
- *  such call as a job (mcp.js), and false answers with the job at once. */
+/** The `wait` a tool that changes the session takes, and a long read
+ *  (Command.long): the server runs every such call as a job (mcp.js), and
+ *  false answers with the job at once. */
 export const waitIn = {
   type: 'boolean',
-  description: 'false: answer at once with { queued: true, job } while the change runs on; scanruler_wait { for: "job", job } gives its answer. true (the default): answer once it is done.',
+  description: 'false: answer at once with { queued: true, job } while the call runs on; scanruler_wait { for: "job", job } gives its answer. true (the default): answer once it is done — or, still running at the server’s answer limit (scanruler_status: server.answerWithin, seconds), with { queued: true, job, after } all the same.',
 }
 
 /** The `timings` a tool that changes the session takes: the server keeps
@@ -82,7 +101,8 @@ export function toolFor(command, { outDir }) {
   let description = command.description
   if (bytesKey) {
     delete input.properties[bytesKey]
-    input.properties.path = inPath
+    const pick = FOLDER_PICKS[command.name]
+    input.properties.path = pick ? { ...inPath, description: `${inPath.description} A folder opens the one ${pick.what} file in it (${pick.kinds.join(', ')}); with more than one, the answer lists them.` } : inPath
     required = required.filter((key) => key !== bytesKey && key !== 'name')
     if (!required.includes('path')) required.unshift('path')
     if (input.properties.name) {
@@ -91,15 +111,23 @@ export function toolFor(command, { outDir }) {
     description += ' The file is read from `path` on this computer and streamed to the page.'
   }
   if (command.returnsImage) {
-    input.properties.path = imagePath
-    description += ' The picture comes back as an image; with `path` it is written to a file too.'
+    input.properties.path = imagePath(outDir)
+    input.properties.inline = inlineIn
+    description += ' The picture comes back as an image; with `path` it is written to a file too, and with `inline: false` only there.'
   } else if (command.returnsFile) {
     input.properties.path = outPath(outDir)
     description += ' The file is written to `path`; the result says where and how large it is, not its bytes.'
   }
+  if (replacesSession(command)) {
+    input.properties.saveTo = saveToIn
+    description += ' With `saveTo`, the session is saved as a project file there first (as project_save does), then replaced as with discard: true — one call to keep what a page holds and start anew.'
+  }
   if (!command.readOnly) {
     input.properties.wait = waitIn
     input.properties.timings = timingsIn
+  } else if (command.long) {
+    // A long read runs as a job too (mcp.js), so it takes wait.
+    input.properties.wait = waitIn
   }
   if (required.length) input.required = required
   else delete input.required
@@ -115,41 +143,188 @@ export function toolFor(command, { outDir }) {
 /** A path as the agent gave it, made absolute against `base`. */
 export const absolute = (path, base) => (isAbsolute(path) ? path : resolve(base, path))
 
+/** What a folder given in place of a file opens, by command: the one file
+ *  of its kind in it. Other commands take a file only. */
+const FOLDER_PICKS = {
+  'scan.open': { what: 'mesh', kinds: ['.stl', '.ply', '.obj'] },
+  'project.load': { what: 'project', kinds: ['.scanruler'] },
+}
+
+/** The file a path names: itself, or — for a folder, where the command
+ *  takes one (FOLDER_PICKS) — the only file of the command's kind in it.
+ *  Refused with the folder's files listed otherwise. */
+async function fileAt(command, file) {
+  const found = await stat(file).catch(() => null)
+  if (!found?.isDirectory()) return file
+  const names = (await readdir(file, { withFileTypes: true })).filter((d) => d.isFile()).map((d) => d.name)
+  const listed = (list) => (list.length > 20 ? `${list.slice(0, 20).join(', ')} and ${list.length - 20} more` : list.join(', '))
+  const pick = FOLDER_PICKS[command.name]
+  if (!pick) throw { code: 'invalid_input', message: `path: ${file} is a folder — give a file${names.length ? ` in it: ${listed(names)}` : ''}.` }
+  const matches = names.filter((n) => pick.kinds.includes(extname(n).toLowerCase()))
+  if (matches.length === 1) return join(file, matches[0])
+  if (matches.length === 0) {
+    throw { code: 'invalid_input', message: `path: ${file} is a folder with no ${pick.what} file in it (${pick.kinds.join(', ')})${names.length ? ` — it holds ${listed(names)}` : ' — it is empty'}. Give the file’s path.` }
+  }
+  throw { code: 'invalid_input', message: `path: ${file} is a folder with ${matches.length} ${pick.what} files — give one of them by its path: ${listed(matches)}.` }
+}
+
+/** How many near names a missing path's refusal lists at most, and how many
+ *  letters off a near name may be. */
+const NEAR_LISTED = 5
+const NEAR_LETTERS = 2
+
+/** A name as nearNames compares it: case ignored, and "-", "_" and a
+ *  space taken alike. */
+const nearForm = (name) => name.toLowerCase().replace(/[-_ ]/g, '_')
+
+/** How many letters `a` and `b` are apart — added, taken out or changed —
+ *  or `most + 1` once past `most`. */
+function lettersApart(a, b, most) {
+  if (Math.abs(a.length - b.length) > most) return most + 1
+  let row = Array.from({ length: b.length + 1 }, (_, j) => j)
+  for (let i = 1; i <= a.length; i++) {
+    const next = [i]
+    for (let j = 1; j <= b.length; j++) next[j] = Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+    if (Math.min(...next) > most) return most + 1
+    row = next
+  }
+  return row[b.length]
+}
+
+/** Where a path that is not there may have been meant: the first folder up
+ *  from it that is there, the name in the path missing from it, and up to
+ *  NEAR_LISTED names in that folder at most NEAR_LETTERS letters off it — a typed
+ *  path's slip, "10_scooter_head" for "10_scooterHead". A near folder is
+ *  given with the rest of the path when that is in it. */
+export async function nearNames(path) {
+  let missing = resolve(path)
+  let folder = dirname(missing)
+  let rest = []
+  for (;;) {
+    if ((await stat(folder).catch(() => null))?.isDirectory()) break
+    if (dirname(folder) === folder) return { folder: null, missing: null, near: [] }
+    rest = [basename(missing), ...rest]
+    missing = folder
+    folder = dirname(folder)
+  }
+  const want = nearForm(basename(missing))
+  const names = await readdir(folder).catch(() => [])
+  const near = names
+    .map((name) => ({ name, apart: lettersApart(nearForm(name), want, NEAR_LETTERS) }))
+    .filter((n) => n.apart <= NEAR_LETTERS)
+    .sort((a, b) => a.apart - b.apart || a.name.localeCompare(b.name))
+    .slice(0, NEAR_LISTED)
+  const paths = []
+  for (const { name } of near) {
+    const whole = join(folder, name, ...rest)
+    paths.push(rest.length && (await stat(whole).catch(() => null)) ? whole : join(folder, name))
+  }
+  return { folder, missing: basename(missing), near: paths }
+}
+
+/** nearNames as a refusal's last sentence. */
+async function nearNote(path) {
+  const { folder, missing, near } = await nearNames(path)
+  if (!folder) return ''
+  if (near.length) return ` Near it: ${near.join(', ')}.`
+  return ` ${folder} is there, with nothing in it named like ${missing}.`
+}
+
 /** The tool call's arguments as the command's input: a path read into the
- *  bytes it names. Returns the input and the input field the bytes go in. */
+ *  bytes it names. Returns the input, the input field the bytes go in, and
+ *  the file read — a folder's one file, when the path named a folder. */
 export async function inputFor(command, args, { cwd }) {
   const input = { ...(args ?? {}) }
+  delete input.saveTo
   const bytesKey = bytesProperty(command)
   if (bytesKey) {
-    const file = absolute(String(input.path ?? ''), cwd)
+    const file = await fileAt(command, absolute(String(input.path ?? ''), cwd))
     delete input.path
     let bytes
     try {
       bytes = new Uint8Array(await readFile(file))
     } catch (e) {
-      throw { code: 'invalid_input', message: `Could not read ${file}: ${e.code === 'ENOENT' ? 'there is no such file' : e.message}.` }
+      if (e.code !== 'ENOENT') throw { code: 'invalid_input', message: `Could not read ${file}: ${e.message}.` }
+      throw { code: 'invalid_input', message: `Could not read ${file}: there is no such file.${await nearNote(file)}` }
     }
     input[bytesKey] = bytes
     if (command.input?.properties?.name && input.name === undefined) input.name = basename(file)
-    return { input, binaryKey: bytesKey }
+    return { input, binaryKey: bytesKey, file }
   }
   if (command.returnsFile || command.returnsImage) delete input.path
-  return { input, binaryKey: null }
+  if (command.returnsImage) delete input.inline
+  return { input, binaryKey: null, file: null }
+}
+
+/** Arguments with every `{ "$file": path }` in them — an object of that one
+ *  key, at any depth — replaced by the JSON the file holds: a long list of
+ *  stations a script wrote need not pass through the conversation. A
+ *  relative path is taken from `cwd`. What a file holds is not looked
+ *  into again. */
+export async function withFiles(value, cwd) {
+  if (Array.isArray(value)) return Promise.all(value.map((v) => withFiles(v, cwd)))
+  if (!value || typeof value !== 'object' || value instanceof Uint8Array) return value
+  const keys = Object.keys(value)
+  if (keys.length === 1 && keys[0] === '$file') {
+    if (typeof value.$file !== 'string' || !value.$file) throw { code: 'invalid_input', message: '$file: give the path of a JSON file.' }
+    const path = absolute(value.$file, cwd)
+    try {
+      return JSON.parse(await readFile(path, 'utf8'))
+    } catch (e) {
+      throw { code: 'invalid_input', message: `$file: ${path} could not be read as JSON (${e?.code === 'ENOENT' ? 'there is no such file' : e instanceof Error ? e.message : String(e)}).` }
+    }
+  }
+  const out = {}
+  for (const key of keys) out[key] = await withFiles(value[key], cwd)
+  return out
+}
+
+/** A file's kind by its extension, as scanruler_files lists it. */
+const KINDS = {
+  mesh: ['.stl', '.ply', '.obj', '.3mf', '.off'],
+  project: ['.scanruler'],
+  step: ['.step', '.stp'],
+  picture: ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp'],
+  drawing: ['.dxf', '.svg', '.pdf'],
+  text: ['.md', '.txt', '.csv', '.json', '.jsonl'],
+}
+export const fileKind = (name) => {
+  const ext = extname(name).toLowerCase()
+  return Object.keys(KINDS).find((kind) => KINDS[kind].includes(ext)) ?? 'other'
 }
 
 /** A picture a command handed back, as MCP content: the image, and the rest
  *  of the result as text — where the picture was written, if the call gave
- *  a path, in place of its bytes. Null for a result with no picture in it. */
+ *  a path, in place of its bytes; written and not shown with `inline:
+ *  false`. Null for a result with no picture in it. */
 export async function imageContent(result, args, { cwd, outDir }) {
   const file = result?.file
   if (!file || !(file.bytes instanceof Uint8Array) || !String(file.mimeType ?? '').startsWith('image/')) return null
   const saved = args?.path ? await saveFileResult(result, args, { cwd, outDir }) : { ...result, file: { name: file.name, mimeType: file.mimeType, size: file.bytes.byteLength } }
+  if (args?.path && args?.inline === false) return [{ type: 'text', text: agentJson(saved) }]
   return [
     { type: 'text', text: agentJson(saved) },
     { type: 'image', data: Buffer.from(file.bytes.buffer, file.bytes.byteOffset, file.bytes.byteLength).toString('base64'), mimeType: file.mimeType },
   ]
 }
 
+/** A picture a batched call handed back, which a batch cannot show:
+ *  written where the call asked, or into `outDir` under the name ScanRuler
+ *  gave it — numbered past one already there, so a batch of renders, or a
+ *  render from an earlier batch, is not written over. The result says
+ *  where, in place of the bytes. A result with no picture in it is as
+ *  saveFileResult leaves it. */
+export async function batchedPicture(result, args, { cwd, outDir }) {
+  const file = result?.file
+  if (args?.path || !file || !(file.bytes instanceof Uint8Array)) return saveFileResult(result, args, { cwd, outDir })
+  const name = String(file.name ?? 'picture.png')
+  const dot = name.lastIndexOf('.')
+  const [stem, ext] = dot > 0 ? [name.slice(0, dot), name.slice(dot)] : [name, '']
+  let target = join(outDir, name)
+  for (let n = 2; await stat(target).catch(() => null); n++) target = join(outDir, `${stem}-${n}${ext}`)
+  return saveFileResult(result, { path: target }, { cwd, outDir })
+}
+
 /** Write a returned file where the call asked, or into `outDir`; the result
  *  then says where, in place of the bytes. */
 export async function saveFileResult(result, args, { cwd, outDir }) {

package/src/update.js

@@ -0,0 +1,380 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// The server keeps itself current. A config written as `npx -y
+// scanruler-mcp` is rarely changed again, and a copy installed or copied by
+// hand never updates at all; so the server does it by itself, in two halves
+// that never hold up the start:
+//
+// - In the background, once it serves, it asks npm's registry which version
+//   is latest — once a day, 2 s at most, the answer kept in update.json
+//   beside tools.json — and when that is newer than itself, has npm fetch it
+//   into npm's cache: `npm exec --yes --package=scanruler-mcp@<v> --
+//   scanruler-mcp --version`, which runs the fetched copy once, so a copy
+//   that does not start is never taken. The session in progress goes on.
+// - At the next start the launcher (bin/scanruler-mcp.js) finds that copy in
+//   update.json (`ready: { version, bin }` — a contract every later version
+//   keeps, since the copy that reads it may be an old one) and runs it in its
+//   own place: the same arguments, stdio passed straight through, its exit
+//   code passed back. No network before serving.
+//
+// Every failure leaves the copy that is running: offline, registry down,
+// fetch or start failed. Off for a copy run from a git checkout (the dev
+// server), with --no-update or SCANRULER_MCP_NO_UPDATE=1, and for a spec
+// pinned in the config (`npx -y scanruler-mcp@0.4.0` is taken as meant).
+// The hand-off is marked in the environment, so a handed-to copy never hands
+// off again in the same start.
+//
+// npx keeps each spec in its own folder, <npm cache>/_npx/<hash>, the hash
+// the first 16 hex digits of the SHA-512 of the spec as written (npm's
+// libnpmexec). A copy run by npx tells from that hash whether its spec was
+// pinned, and finds npm's cache from its own path.
+
+import { spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { basename, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { configDir } from './config.js'
+
+export const PACKAGE = 'scanruler-mcp'
+/** Set on the copy handed to: the version that handed off. */
+export const HANDED_OFF_ENV = 'SCANRULER_MCP_HANDED_OFF'
+/** The launcher's process id, for the copy handed to to stop with it. */
+export const PARENT_ENV = 'SCANRULER_MCP_PARENT_PID'
+export const NO_UPDATE_ENV = 'SCANRULER_MCP_NO_UPDATE'
+export const CHECK_EVERY_MS = 24 * 60 * 60 * 1000
+export const CHECK_WITHIN_MS = 2000
+/** A handed-to copy that fails sooner than this is taken as not starting. */
+export const START_GRACE_MS = 3000
+const FETCH_WITHIN_MS = 5 * 60 * 1000
+const STATE_FILE = 'update.json'
+/** Options that answer and exit: never handed off. */
+const OWN_ANSWERS = ['--help', '--pair', '--version']
+
+const PACKAGE_DIR = fileURLToPath(new URL('..', import.meta.url))
+
+// ---- versions -------------------------------------------------------------
+
+const parse = (v) => {
+  const m = /^(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?$/.exec(typeof v === 'string' ? v : '')
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3]), m[4] ?? null] : null
+}
+
+export const isVersion = (v) => parse(v) !== null
+
+/** Whether version `a` is newer than `b`; false when either is no version. */
+export function newer(a, b) {
+  const x = parse(a)
+  const y = parse(b)
+  if (!x || !y) return false
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i]
+  return x[3] === null && y[3] !== null
+}
+
+/** npx's folder name for a spec: <npm cache>/_npx/<this>. */
+export const npxHash = (spec) => createHash('sha512').update(spec).digest('hex').slice(0, 16)
+
+/** The version of the copy whose bin is `bin`, or null. */
+export function versionAt(bin, read = readFileSync) {
+  try {
+    const v = JSON.parse(read(join(dirname(bin), '..', 'package.json'), 'utf8')).version
+    return isVersion(v) ? v : null
+  } catch {
+    return null
+  }
+}
+
+// ---- how this copy runs -------------------------------------------------------
+
+/** How the copy in `packageDir` was installed: by npx (`npx`, with npm's
+ *  cache, and pinned unless its spec was the bare name or @latest), by npm
+ *  (`installed`: global or a project's), from a git checkout (`checkout`),
+ *  or copied by hand (`copy`). */
+export function installOf(packageDir = PACKAGE_DIR, exists = existsSync) {
+  const parent = dirname(packageDir)
+  if (basename(parent) === 'node_modules') {
+    const npxDir = dirname(parent)
+    if (basename(dirname(npxDir)) === '_npx') {
+      const hash = basename(npxDir)
+      const bare = [PACKAGE, `${PACKAGE}@latest`].some((spec) => npxHash(spec) === hash)
+      return { kind: 'npx', pinned: !bare, npmCache: dirname(dirname(npxDir)) }
+    }
+    return { kind: 'installed', pinned: false }
+  }
+  for (let dir = parent; ; dir = dirname(dir)) {
+    if (exists(join(dir, '.git'))) return { kind: 'checkout', pinned: false }
+    if (dirname(dir) === dir) return { kind: 'copy', pinned: false }
+  }
+}
+
+/** Whether this copy keeps itself current: `updates` is `on`, `off`
+ *  (--no-update, SCANRULER_MCP_NO_UPDATE), `checkout` or `pinned`. A copy
+ *  handed to goes by the launcher's decision, not its own folder — which is
+ *  a pinned spec's. */
+export function updatePolicy({ argv = [], env = process.env, install }) {
+  const handedOffFrom = env[HANDED_OFF_ENV] || null
+  const from = handedOffFrom ? { handedOffFrom } : {}
+  if (argv.includes('--no-update') || /^(1|true|yes|on)$/i.test(env[NO_UPDATE_ENV] ?? '')) return { updates: 'off', ...from }
+  if (handedOffFrom) return { updates: 'on', ...from }
+  if (install.kind === 'checkout') return { updates: 'checkout' }
+  if (install.pinned) return { updates: 'pinned', pinned: true }
+  return { updates: 'on' }
+}
+
+// ---- what is kept ---------------------------------------------------------------
+
+/** update.json: `{ checked, latest, ready?: { version, bin }, failed? }`. */
+export function loadState(dir = configDir()) {
+  try {
+    const kept = JSON.parse(readFileSync(join(dir, STATE_FILE), 'utf8'))
+    return kept && typeof kept === 'object' ? kept : {}
+  } catch {
+    return {}
+  }
+}
+
+/** Merge `patch` into update.json — written whole and renamed into place,
+ *  since two copies may start at once. */
+export function saveState(patch, dir = configDir()) {
+  const next = { ...loadState(dir), ...patch }
+  try {
+    mkdirSync(dir, { recursive: true })
+    const file = join(dir, STATE_FILE)
+    const part = `${file}.${process.pid}.part`
+    writeFileSync(part, JSON.stringify(next, null, 2) + '\n')
+    renameSync(part, file)
+  } catch {
+    // Not kept: the next start asks again.
+  }
+  return next
+}
+
+// ---- the launcher ---------------------------------------------------------------
+
+/** What the launcher runs: `{ run: 'self', why }` or `{ run: 'handoff',
+ *  bin, version }` — read from update.json and the disk alone. */
+export function launchPlan({ argv = [], env = process.env, version, install, state = {}, exists = existsSync, readVersion = versionAt }) {
+  const self = (why) => ({ run: 'self', why })
+  if (env[HANDED_OFF_ENV]) return self('handed-off')
+  if (argv.some((a) => OWN_ANSWERS.includes(a))) return self('answer')
+  const policy = updatePolicy({ argv, env, install })
+  if (policy.updates !== 'on') return self(policy.updates)
+  const ready = state.ready
+  if (!ready || typeof ready.bin !== 'string' || !newer(ready.version, version)) return self('current')
+  if (Array.isArray(state.failed) && state.failed.includes(ready.version)) return self('failed-before')
+  if (!exists(ready.bin) || readVersion(ready.bin) !== ready.version) return self('missing')
+  return { run: 'handoff', bin: ready.bin, version: ready.version }
+}
+
+/** Run the copy at `plan.bin` in this one's place. Resolves `{ code }` with
+ *  its exit code, or `{ fallback }` when it did not start — failed to
+ *  spawn, or ended with an error within START_GRACE_MS, then marked failed
+ *  so the next start does not try it again. */
+export function runHandOff({ plan, argv, version, env = process.env, spawnFn = spawn, now = Date.now, markFailed = () => {}, execPath = process.execPath }) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawnFn(execPath, [plan.bin, ...argv], {
+        stdio: 'inherit',
+        env: { ...env, [HANDED_OFF_ENV]: version, [PARENT_ENV]: String(process.pid) },
+        windowsHide: true,
+      })
+    } catch (e) {
+      resolve({ fallback: `could not start it: ${e?.message ?? e}` })
+      return
+    }
+    const started = now()
+    const forward = (signal) => () => child.kill(signal)
+    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'].map((s) => [s, forward(s)])
+    for (const [s, f] of signals) process.on(s, f)
+    const done = (out) => {
+      for (const [s, f] of signals) process.off(s, f)
+      resolve(out)
+    }
+    child.once('error', (e) => done({ fallback: `could not start it: ${e?.message ?? e}` }))
+    child.once('exit', (code, signal) => {
+      if (code !== 0 && signal === null && now() - started < START_GRACE_MS) {
+        markFailed(plan.version)
+        done({ fallback: `it stopped with code ${code} as it started` })
+      } else done({ code: code ?? 1 })
+    })
+  })
+}
+
+/** The launcher's part: run a newer copy fetched earlier in this one's
+ *  place. Resolves its exit code, or null for this copy to run — always
+ *  null on any failure. */
+export async function launch(argv, { env = process.env, packageDir = PACKAGE_DIR, dir, log = stderrLog } = {}) {
+  try {
+    const version = versionAt(join(packageDir, 'bin', 'scanruler-mcp.js'))
+    const where = dir ?? configDir(env)
+    const plan = launchPlan({ argv, env, version, install: installOf(packageDir), state: loadState(where) })
+    if (plan.run !== 'handoff') return null
+    log(`Starting scanruler-mcp ${plan.version}, fetched earlier, in place of ${version}.`)
+    const out = await runHandOff({
+      plan,
+      argv,
+      version,
+      env,
+      markFailed: (v) => {
+        const failed = loadState(where).failed
+        saveState({ failed: [...(Array.isArray(failed) ? failed : []), v].slice(-5) }, where)
+      },
+    })
+    if ('code' in out) return out.code
+    log(`scanruler-mcp ${plan.version} did not start (${out.fallback}); running ${version}.`)
+    return null
+  } catch {
+    return null
+  }
+}
+
+/** In a copy handed to: stop when the launcher is gone — killed by the
+ *  client, which on Windows does not take its children with it. */
+export function watchParent(env = process.env, { every = 2000, alive = processAlive, exit = () => process.exit(0) } = {}) {
+  const pid = Number(env[PARENT_ENV])
+  if (!env[HANDED_OFF_ENV] || !Number.isInteger(pid) || pid <= 0) return null
+  const timer = setInterval(() => {
+    if (!alive(pid)) exit()
+  }, every)
+  timer.unref?.()
+  return timer
+}
+
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return e?.code === 'EPERM'
+  }
+}
+
+const stderrLog = (line) => process.stderr.write(`[scanruler-mcp] ${line}\n`)
+
+// ---- the background check ---------------------------------------------------------
+
+/** The latest version on the registry npm uses, or null — 2 s at most. */
+export async function fetchLatest({ env = process.env, fetchFn = fetch, within = CHECK_WITHIN_MS } = {}) {
+  try {
+    const registry = (env.npm_config_registry || 'https://registry.npmjs.org/').replace(/\/?$/, '/')
+    const r = await fetchFn(`${registry}${PACKAGE}/latest`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(within) })
+    if (!r.ok) return null
+    const { version } = await r.json()
+    return isVersion(version) ? version : null
+  } catch {
+    return null
+  }
+}
+
+/** How to run npm without a shell: the npm that ran npx, or the one beside
+ *  this Node; `npm` through the shell as the last resort. */
+export function npmCommand(env = process.env, execPath = process.execPath, exists = existsSync) {
+  const given = env.npm_execpath ?? ''
+  const candidates = [
+    /npm-cli\.js$/.test(given) ? given : null,
+    /npx-cli\.js$/.test(given) ? join(dirname(given), 'npm-cli.js') : null,
+    join(dirname(execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    join(dirname(execPath), '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  ]
+  const cli = candidates.find((c) => c && exists(c))
+  return cli ? { file: execPath, args: [cli], shell: false } : { file: 'npm', args: [], shell: process.platform === 'win32' }
+}
+
+/** Run npm with `args` (fixed words and a checked version only — they may
+ *  pass a shell), quietly, from the temp folder: `{ code, stdout }`. */
+export function runNpm(args, { env = process.env, within = FETCH_WITHIN_MS, spawnFn = spawn } = {}) {
+  return new Promise((resolve) => {
+    const npm = npmCommand(env)
+    let child
+    try {
+      child = spawnFn(npm.file, [...npm.args, ...args], {
+        cwd: tmpdir(),
+        env: { ...env, [NO_UPDATE_ENV]: '1', [HANDED_OFF_ENV]: '' },
+        stdio: ['ignore', 'pipe', 'ignore'],
+        shell: npm.shell,
+        windowsHide: true,
+      })
+    } catch {
+      resolve({ code: -1, stdout: '' })
+      return
+    }
+    let stdout = ''
+    child.stdout?.on('data', (d) => {
+      if (stdout.length < 4096) stdout += d
+    })
+    const timer = setTimeout(() => child.kill(), within)
+    timer.unref?.()
+    child.once('error', () => {
+      clearTimeout(timer)
+      resolve({ code: -1, stdout })
+    })
+    child.once('close', (code) => {
+      clearTimeout(timer)
+      resolve({ code: code ?? -1, stdout })
+    })
+  })
+}
+
+/** npm's cache folder when nobody says otherwise. */
+const defaultNpmCache = (env, platform = process.platform) =>
+  platform === 'win32' ? join(env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'npm-cache') : join(homedir(), '.npm')
+
+/** Have npm fetch `version` into its cache and run it once; the bin of the
+ *  copy fetched, or null. */
+export async function prefetch(version, { env = process.env, install = { kind: 'copy' }, npm = runNpm, readVersion = versionAt } = {}) {
+  if (!isVersion(version)) return null
+  const spec = `${PACKAGE}@${version}`
+  const ran = await npm(['exec', '--yes', `--package=${spec}`, '--', PACKAGE, '--version'], { env })
+  if (ran.code !== 0 || ran.stdout.trim() !== version) return null
+  const binIn = (cache) => join(cache, '_npx', npxHash(spec), 'node_modules', PACKAGE, 'bin', 'scanruler-mcp.js')
+  const caches = [install.npmCache, env.npm_config_cache, defaultNpmCache(env)].filter(Boolean)
+  for (const cache of caches) if (readVersion(binIn(cache)) === version) return binIn(cache)
+  const asked = await npm(['config', 'get', 'cache'], { env, within: 30_000 })
+  const cache = asked.code === 0 ? asked.stdout.trim() : ''
+  return cache && readVersion(binIn(cache)) === version ? binIn(cache) : null
+}
+
+/** The background check: ask the registry (once a day), and fetch a newer
+ *  version for the next start. Resolves the state kept. */
+export async function checkForUpdate({ version, dir = configDir(), env = process.env, install = { kind: 'copy' }, now = Date.now, latestOf = () => fetchLatest({ env }), fetchCopy = (v) => prefetch(v, { env, install }), exists = existsSync }) {
+  let state = loadState(dir)
+  const checked = Date.parse(state.checked ?? '')
+  if (!Number.isFinite(checked) || now() - checked > CHECK_EVERY_MS || now() < checked) {
+    const latest = await latestOf()
+    if (!latest) return state
+    state = saveState({ checked: new Date(now()).toISOString(), latest }, dir)
+  }
+  const latest = state.latest
+  if (!newer(latest, version)) return state
+  if (Array.isArray(state.failed) && state.failed.includes(latest)) return state
+  if (state.ready?.version === latest && exists(state.ready.bin)) return state
+  const bin = await fetchCopy(latest)
+  return bin ? saveState({ ready: { version: latest, bin, fetched: new Date(now()).toISOString() } }, dir) : state
+}
+
+/** The server's part, once it serves: the check in the background, and
+ *  what the status says of it — `{ latest, handedOffFrom?, pinned?,
+ *  updates? }` (updates only when off: `off` or `checkout`). */
+export function startUpdates({ version, argv = [], env = process.env, packageDir = PACKAGE_DIR, dir = configDir(env), log = stderrLog, check = checkForUpdate } = {}) {
+  const install = installOf(packageDir)
+  const policy = updatePolicy({ argv, env, install })
+  let state = policy.updates === 'on' ? loadState(dir) : {}
+  const done =
+    policy.updates === 'on'
+      ? new Promise((resolve) => setImmediate(resolve))
+          .then(() => check({ version, dir, env, install }))
+          .then((s) => {
+            state = s
+            if (newer(s.ready?.version, version)) log(`scanruler-mcp ${s.ready.version} is fetched; it starts in place of ${version} next time.`)
+          })
+          .catch(() => {})
+      : Promise.resolve()
+  const info = () => ({
+    latest: isVersion(state.latest) ? state.latest : null,
+    ...(policy.handedOffFrom ? { handedOffFrom: policy.handedOffFrom } : {}),
+    ...(policy.pinned ? { pinned: true } : {}),
+    ...(policy.updates === 'off' || policy.updates === 'checkout' ? { updates: policy.updates } : {}),
+  })
+  return { info, done }
+}