annotatable-html 0.0.0-stage → 1.45.3

package/lib/opencode.js

@@ -0,0 +1,195 @@
+'use strict';
+
+/* OpenCode's documented HTTP session API. No SDK dependency or provider credentials are needed. */
+var http = require('http');
+var https = require('https');
+var runPoll = require('./poll-process.js').runPoll;
+
+function request(base, route, method, body, directory, options) {
+  var url = new URL(base);
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return Promise.reject(new Error('OpenCode 地址必须使用 http 或 https'));
+  if (url.username || url.password) return Promise.reject(new Error('OpenCode 服务密码请放在 OPENCODE_SERVER_PASSWORD 中'));
+  url.pathname = url.pathname.replace(/\/$/, '') + route;
+  url.search = '';
+  url.hash = '';
+  var headers = { Accept: 'application/json' };
+  if (directory) headers['x-opencode-directory'] = encodeURIComponent(directory);
+  if (process.env.OPENCODE_SERVER_PASSWORD) headers.Authorization = 'Basic ' + Buffer.from(
+    (process.env.OPENCODE_SERVER_USERNAME || 'opencode') + ':' + process.env.OPENCODE_SERVER_PASSWORD).toString('base64');
+  var data = body === undefined ? null : Buffer.from(JSON.stringify(body));
+  if (data) { headers['Content-Type'] = 'application/json'; headers['Content-Length'] = data.length; }
+  return new Promise(function (resolve, reject) {
+    var req = (url.protocol === 'https:' ? https : http).request(url, { method: method, headers: headers, agent: false }, function (res) {
+      var chunks = [], size = 0;
+      res.on('error', reject);
+      res.on('data', function (chunk) {
+        size += chunk.length;
+        if (size > 1024 * 1024) { req.destroy(new Error('OpenCode 响应过大')); return; }
+        chunks.push(chunk);
+      });
+      res.on('end', function () {
+        if (res.statusCode < 200 || res.statusCode >= 300) { reject(new Error('OpenCode HTTP ' + res.statusCode + '：' + route)); return; }
+        var text = Buffer.concat(chunks).toString('utf8');
+        if (!text) { resolve(null); return; }
+        try { resolve(JSON.parse(text)); } catch (_) { reject(new Error('OpenCode 返回了无效 JSON')); }
+      });
+    });
+    req.setTimeout(options && options.timeoutMs || 10000, function () { req.destroy(new Error('OpenCode 请求超时')); });
+    req.on('error', reject);
+    req.end(data);
+  });
+}
+
+async function pollAnnotations(htmlPath, opts) {
+  opts = opts || {};
+  var base = opts.opencodeUrl || process.env.ANNOTATABLE_OPENCODE_SERVER_URL;
+  var session = opts.opencodeSession || process.env.ANNOTATABLE_OPENCODE_SESSION_ID;
+  var directory = process.env.ANNOTATABLE_OPENCODE_DIRECTORY || process.cwd();
+  if (!base || !session) throw new Error('缺少 OpenCode 会话信息：新开已安装上下文插件的会话，或指定 --opencode-url 和 --opencode-session');
+  var route = '/session/' + encodeURIComponent(session);
+  var info = await request(base, route, 'GET', undefined, directory);
+  if (!info || info.id !== session) throw new Error('OpenCode 返回的会话与目标不符');
+  var result = await runPoll(htmlPath, opts);
+  if (result.hit) {
+    await request(base, route + '/prompt_async', 'POST', { parts: [{ type: 'text', synthetic: true,
+      text: '[annotatable-html 监听事件]\nPOLL_HIT ' + JSON.stringify(result.hit) +
+        '\n按批注工作流读取完整对话并处理。完成后重新挂同一文件的 poll --opencode。'
+    }] }, directory);
+    console.log('OPENCODE_NOTIFIED ' + JSON.stringify({ sessionId: session, file: result.hit.file }));
+  }
+  process.exitCode = result.code;
+}
+
+async function dutySettings(base, id, directory) {
+  var session = await request(base, '/session/' + encodeURIComponent(id), 'GET', undefined, directory);
+  if (!session || session.id !== id || !session.directory) throw new Error('OpenCode 返回其他会话或缺少目录');
+  var cwd = session.directory;
+  var config = await request(base, '/config', 'GET', undefined, cwd);
+  var messages = await request(base, '/session/' + encodeURIComponent(id) + '/message', 'GET', undefined, cwd);
+  var last = messages.slice().reverse().find(m => m.info && m.info.role === 'user' && m.info.model);
+  if (!last || !last.info.model.providerID || !last.info.model.modelID) throw new Error('OpenCode 会话缺少已选模型；先在原会话完成一轮');
+  var user = last.info, agent = user.agent || 'build';
+  var provider = config.provider && config.provider[user.model.providerID] || {};
+  var baseURL = provider.options && provider.options.baseURL || null;
+  if (baseURL) { var endpoint = new URL(baseURL); if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) throw new Error('OpenCode 提供方地址不能含内嵌凭据或查询参数'); }
+  return { cwd: cwd, model: user.model, provider: { npm: provider.npm || null, baseURL: baseURL }, agent: agent, variant: user.variant || null, tools: user.tools || null,
+    permission: config.permission || {}, sessionPermission: session.permission || null,
+    agentPermission: config.agent && config.agent[agent] && config.agent[agent].permission || {} };
+}
+async function dutyBinding(file, options) {
+  var processes = require('./duty-process');
+  var base = options.opencodeUrl || process.env.ANNOTATABLE_OPENCODE_SERVER_URL;
+  var id = options.opencodeSession || process.env.ANNOTATABLE_OPENCODE_SESSION_ID;
+  if (!base || !/^ses_[a-z0-9]+$/i.test(id || '')) throw new Error('OpenCode 续接需要原服务地址和会话编号');
+  var url = new URL(base);
+  if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost'].includes(url.hostname) || url.username || url.password) throw new Error('自动续接只支持无内嵌密码的本机 OpenCode HTTP 服务');
+  var owner = await processes.portOwner(Number(url.port || 80));
+  if (!/^opencode(?:\.exe)?$/i.test(owner.Name)) throw new Error('无法确认 OpenCode 服务进程');
+  var settings = await dutySettings(base, id, options.opencodeDirectory || process.env.ANNOTATABLE_OPENCODE_DIRECTORY);
+  var paths = await request(base, '/path', 'GET');
+  return { threadId: id, binary: options.opencodeBin || owner.ExecutablePath, settings: settings,
+    opencode: { url: url.origin, owners: [processes.identity(owner)], serverCwd: paths.directory,
+      paths: { home: paths.home, config: paths.config, state: paths.state },
+      files: processes.configStamps(settings.cwd, ['opencode.json', 'opencode.jsonc', '.opencode/opencode.json', '.opencode/opencode.jsonc'],
+        [require('path').join(paths.config, 'opencode.json'), require('path').join(paths.config, 'opencode.jsonc')].concat(process.env.OPENCODE_CONFIG ? [require('path').resolve(paths.directory, process.env.OPENCODE_CONFIG)] : [])) } };
+}
+function createDutyAdapter(getBinding, updateBinding) {
+  var processes = require('./duty-process'), duty = require('./duty');
+  async function inspect(base, process) {
+    var b = getBinding();
+    if (!process || duty.canonicalPath(process.ExecutablePath) !== duty.canonicalPath(b.binary)) return null;
+    try {
+      var paths = await request(base, '/path', 'GET', undefined, undefined, { timeoutMs: 1000 });
+      if (duty.canonicalPath(paths.directory) !== duty.canonicalPath(b.opencode.serverCwd)) return null;
+      var s = await request(base, '/session/' + b.threadId, 'GET', undefined, b.settings.cwd, { timeoutMs: 1000 });
+      if (s && s.id === b.threadId && duty.canonicalPath(s.directory) === duty.canonicalPath(b.settings.cwd)) return { url: base, process: process };
+    } catch (_) {}
+    return null;
+  }
+  async function candidates(excludePid) {
+    var b = getBinding(), found = [], listeners = await processes.listeners(b.binary);
+    for (var listener of (Array.isArray(listeners) ? listeners : listeners ? [listeners] : [])) {
+      if (listener.process.ProcessId === excludePid) continue;
+      for (var port of listener.ports) {
+        var value = await inspect('http://127.0.0.1:' + port, listener.process); if (value) found.push(value);
+      }
+    }
+    return found;
+  }
+  async function online() {
+    var b = getBinding(), owner = await processes.processInfo(b.opencode.owners[0].ProcessId), selected;
+    if (processes.sameProcess(b.opencode.owners[0], owner)) selected = await inspect(b.opencode.url, owner);
+    else { var found = await candidates(); if (found.length === 1) selected = found[0]; }
+    if (!selected) return null;
+    if (!processes.sameProcess(b.opencode.owners[0], selected.process)) updateBinding(Object.assign({}, b,
+      { opencode: Object.assign({}, b.opencode, { url: selected.url, owners: [processes.identity(selected.process)] }) }));
+    var states = await request(selected.url, '/session/status', 'GET', undefined, b.settings.cwd);
+    return { available: true, active: !!(states[b.threadId] && states[b.threadId].type !== 'idle'), notify: hit =>
+      request(selected.url, '/session/' + b.threadId + '/prompt_async', 'POST', { parts: [{ type: 'text', synthetic: true, text: duty.prompt(b, hit) }] }, b.settings.cwd) };
+  }
+  async function released(excludePid) {
+    if (!(await processes.ownersExited(getBinding().opencode.owners)).released) return { released: false, reason: 'opencode-server-process-alive' };
+    if ((await candidates(excludePid)).length) return { released: false, reason: 'opencode-session-server-returned' };
+    return { released: true, reason: 'opencode-session-server-exited' };
+  }
+  async function run(hit, onStart) {
+    var b = getBinding(), cp = require('child_process');
+    if (b.opencode.files && !require('util').isDeepStrictEqual(b.opencode.files.map(x => processes.fileStamp(x.file)), b.opencode.files)) throw new Error('OpenCode 配置已改变，请重新注册');
+    if (!(await released()).released) throw new Error('OpenCode 原服务尚未退出');
+    var url = new URL(b.opencode.url), child = cp.spawn(b.binary, ['serve', '--port', url.port || '80', '--hostname', '127.0.0.1'],
+      { cwd: b.opencode.serverCwd, env: processes.agentEnv(), windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    child.stdout.resume(); child.stderr.resume();
+    var record = { host: 'opencode', threadId: b.threadId, pid: child.pid, startedAt: Date.now() }, exited = false;
+    var closed = new Promise(resolve => child.once('close', code => { exited = true; resolve(code); }));
+    var spawnError; child.once('error', error => { spawnError = error; });
+    if (onStart) onStart(record);
+    var base = url.origin, route = '/session/' + b.threadId;
+    var api = (p, method, body) => request(base, p, method || 'GET', body, b.settings.cwd);
+    try {
+      var until = Date.now() + 30000;
+      for (;;) {
+        if (spawnError) throw spawnError;
+        if (exited) throw new Error('OpenCode 无头服务启动失败，保留待办');
+        try { var health = await api('/global/health'); if (health.healthy) break; } catch (_) {}
+        if (Date.now() > until) throw new Error('OpenCode 无头服务未确认启动');
+        await new Promise(resolve => setTimeout(resolve, 300));
+      }
+      var owner = await processes.portOwner(Number(url.port || 80));
+      if (owner.ProcessId !== child.pid) throw new Error('服务端口属于其他进程，不接管');
+      var settings = await dutySettings(base, b.threadId, b.settings.cwd), paths = await request(base, '/path', 'GET');
+      if (JSON.stringify(settings) !== JSON.stringify(b.settings) ||
+          JSON.stringify({ home: paths.home, config: paths.config, state: paths.state }) !== JSON.stringify(b.opencode.paths)) throw new Error('OpenCode 模型、权限或存储位置已改变，请重新注册');
+      record.restored = settings;
+      if (!(await released(child.pid)).released) throw new Error('OpenCode 原会话已重开，暂停无头执行');
+      var before = new Set((await api(route + '/message')).map(m => m.info.id));
+      await api(route + '/prompt_async', 'POST', { model: settings.model, agent: settings.agent, variant: settings.variant || undefined,
+        tools: settings.tools || undefined, parts: [{ type: 'text', synthetic: true, text: duty.prompt(b, hit, { headless: true }) }] });
+      until = Date.now() + 300000;
+      for (;;) {
+        for (var kind of ['permission', 'question']) {
+          var requests = await api('/' + kind);
+          for (var item of requests.filter(x => x.sessionID === b.threadId)) {
+            await api('/' + kind + '/' + item.id + (kind === 'permission' ? '/reply' : '/reject'), 'POST', kind === 'permission' ? { reply: 'reject' } : {});
+            throw new Error('OpenCode 需要人工审批或补充信息，保留待办');
+          }
+        }
+        var messages = await api(route + '/message'), fresh = messages.filter(m => !before.has(m.info.id) && m.info.role === 'assistant');
+        var failed = fresh.find(m => m.info.error);
+        if (failed) throw new Error('OpenCode 模型返回 ' + failed.info.error.name);
+        var states = await api('/session/status'), last = fresh[fresh.length - 1];
+        if (states[b.threadId] && states[b.threadId].action && states[b.threadId].action.reason === 'free_tier_limit') throw new Error('原 OpenCode 模型额度已耗尽，保留待办');
+        if (last && last.info.time.completed && (!states[b.threadId] || states[b.threadId].type === 'idle')) {
+          record.turnId = last.info.id; record.outcome = 'completed'; return record;
+        }
+        if (Date.now() > until) throw new Error('OpenCode 回复超时，保留待办');
+        await new Promise(resolve => setTimeout(resolve, 1000));
+      }
+    } catch (error) {
+      try { if (!exited) await api(route + '/abort', 'POST'); } catch (_) {}
+      record.outcome = 'failed'; record.error = error.message; throw Object.assign(error, { dutyRun: record });
+    } finally { if (!exited) child.kill(); await closed; record.finishedAt = Date.now(); }
+  }
+  return { online: online, released: released, run: run, close: () => {} };
+}
+
+module.exports = { request: request, pollAnnotations: pollAnnotations, dutySettings: dutySettings, dutyBinding: dutyBinding, createDutyAdapter: createDutyAdapter };

package/lib/poll-process.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/* Run the existing single-use poll and capture only its structured hit.
+ * Shared by optional host notification transports; the core polling rules stay unchanged. */
+var path = require('path');
+var cp = require('child_process');
+var readline = require('readline');
+
+function runPoll(htmlPath, opts) {
+  opts = opts || {};
+  var argv = [path.join(__dirname, '..', 'agent', 'annot_poll.js'), path.resolve(htmlPath)];
+  [['--timeout', opts.timeout], ['--interval', opts.interval], ['--exit-code', opts.exitCode],
+    ['--exit-code-timeout', opts.timeoutExitCode]].forEach(function (item) {
+    if (item[1] !== undefined) argv.push(item[0], String(item[1]));
+  });
+  return new Promise(function (resolve, reject) {
+    var hit;
+    var child = cp.spawn(process.execPath, argv, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    var stop = function () { child.kill(); };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    child.stdout.pipe(process.stdout);
+    child.stderr.pipe(process.stderr);
+    var lines = readline.createInterface({ input: child.stdout });
+    lines.on('line', function (line) {
+      if (line.indexOf('POLL_HIT ') !== 0) return;
+      try {
+        var payload = JSON.parse(line.slice(9));
+        if (path.resolve(payload.file) === path.resolve(htmlPath)) hit = payload;
+      } catch (_) { /* Ignore unstructured output. */ }
+    });
+    child.once('error', reject);
+    child.once('close', function (code) {
+      lines.close();
+      process.removeListener('SIGINT', stop);
+      process.removeListener('SIGTERM', stop);
+      resolve({ code: code === null ? 1 : code, hit: hit });
+    });
+  });
+}
+
+module.exports = { runPoll: runPoll };

package/lib/serve.js

@@ -0,0 +1,318 @@
+'use strict';
+/* annotatable serve —— 本地伴随服务器
+ * 静态伺服目录 + 受控写回端点，让可批注 HTML 在 localhost 上获得
+ * 零点击、零授权的全自动保存（同源 POST，仅监听 127.0.0.1）。 */
+
+var http = require('http');
+var fs = require('fs');
+var path = require('path');
+var os = require('os');
+var core = require('./core');   /* v1.26.0：saveDocHtml（锁内 rev 复验+原子写+记票）与 readSideHist（/__annot/hist） */
+
+var MIME = {
+  '.html': 'text/html; charset=utf-8', '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8', '.json': 'application/json',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif', '.svg': 'image/svg+xml', '.ico': 'image/x-icon',
+  '.md': 'text/plain; charset=utf-8'
+};
+
+/* 防本机 CSRF：仅接受 JSON content-type（跨站简单请求会被此拦下），
+   且 Origin 若存在必须为空（file://）或 localhost */
+function sameOriginGuard(req, res) {
+  var ct = (req.headers['content-type'] || '');
+  var og = (req.headers['origin'] || 'null');
+  if (ct.indexOf('application/json') === -1) { res.writeHead(403); res.end('bad content-type'); return false; }
+  if (og !== 'null' && og.indexOf('http://localhost') !== 0 && og.indexOf('http://127.0.0.1') !== 0) { res.writeHead(403); res.end('bad origin'); return false; }
+  return true;
+}
+/* 根目录边界校验与请求路径解析（withinRoot/safeServePath 在 start() 内定义——root 是每次启动的伺服根） */
+function readJsonBody(req, res, cap, cb) {
+  /* v1.28.1：必须按 Buffer 累积、end 时整体解码——旧写法对每个 chunk 独立 toString，
+     多字节 UTF-8 字符恰跨 chunk 边界即被打成 U+FFFD（调研页批语「划线」变「���」、
+     模板装饰 ═══ 变乱码实证；打中中文批注文本=静默数据腐蚀）。cap 按字节计。 */
+  var chunks = [], total = 0, dead = false;
+  req.on('data', function (c) {
+    if (dead) return;
+    chunks.push(c); total += c.length;
+    if (total > cap) { dead = true; req.destroy(); }
+  });
+  req.on('end', function () {
+    if (dead) return;
+    try { cb(JSON.parse(Buffer.concat(chunks).toString('utf8'))); }
+    catch (e) { res.writeHead(400); res.end(String(e.message || e)); }
+  });
+}
+
+/* 探测占用者是不是自家 serve（POST /__annot/ping 应 pong）；1s 超时/连不上按「不是」处理 */
+function probeSelf(port, cb) {
+  var req = http.request({ host: '127.0.0.1', port: port, path: '/__annot/ping', method: 'POST', timeout: 1000 }, function (res) {
+    var b = '';
+    res.on('data', function (c) { b += c; });
+    res.on('end', function () { cb(b.indexOf('pong') !== -1); });
+  });
+  req.on('timeout', function () { req.destroy(); cb(false); });
+  req.on('error', function () { cb(false); });
+  req.end();
+}
+
+function start(root, port, opts) {
+  root = path.resolve(root || process.cwd());
+  try { core.syncKitCode(root, path.join(__dirname, '..')); } catch (e) { /* kit 同步尽力而为 */ }   // v1.38.4 值守开场必经 serve——顺手把文档侧过期 kit 拷贝拉齐（issue#7 根因）
+  if (port === undefined || port === null || port === '' || isNaN(port)) port = 8973;   // --port 0 = 系统挑空闲端口，是合法值别当缺省吞掉
+  var studioProvider = opts && typeof opts.studioProvider === 'function' ? opts.studioProvider : null;
+
+  /* 根目录边界校验：resolve 后必须仍落在伺服根内（防 ../ 越界） */
+  function withinRoot(p) {
+    return p === root || p.indexOf(root + path.sep) === 0;
+  }
+  /* 请求路径 → 伺服根内绝对路径；越界返回 null */
+  function safeServePath(rel) {
+    var p = path.resolve(root, '.' + rel);
+    return withinRoot(p) ? p : null;
+  }
+
+  var server = http.createServer(function (req, res) {
+    var u;
+    try { u = decodeURIComponent(req.url.split('?')[0]); } catch (e) { res.writeHead(400); res.end('bad url'); return; }
+
+    /* 心跳探测：页面据此判断处于服务器模式 */
+    if (req.method === 'POST' && u === '/__annot/ping') { res.writeHead(200); res.end('pong'); return; }
+
+    // A new local agent can resolve one user-specified page without a global duty list.
+    if (req.method === 'GET' && u === '/__annot/context') {
+      var contextPath;
+      try { contextPath = new URL('http://x' + req.url).searchParams.get('path') || ''; }
+      catch (contextError) { res.writeHead(400); res.end('bad path'); return; }
+      var contextFile = contextPath.charAt(0) === '/' && safeServePath(contextPath);
+      if (!contextFile || !/\.html?$/i.test(contextFile)) { res.writeHead(403); res.end('forbidden'); return; }
+      fs.readFile(contextFile, 'utf8', function (err, html) {
+        if (err) { res.writeHead(404); res.end('not found'); return; }
+        var contextStore;
+        try { contextStore = core.readStore(html); } catch (parseError) { /* invalid document */ }
+        if (!contextStore) { res.writeHead(422); res.end('not an annotatable document'); return; }
+        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ service: 'annotatable-html', version: core.pkgVersion(path.join(__dirname, '..')),
+          root: root, file: contextFile, docId: core.docIdOf(html) }));
+      });
+      return;
+    }
+
+    /* live-sync 探测（v1.21.0）：页面轮询本端点拿 rev/mtime，文件变了才热载，
+       免去每秒全文拉取。路径先过 safeServePath 边界校验，再限 .html。 */
+    if (req.method === 'GET' && u === '/__annot/rev') {
+      var qs;
+      try { qs = new URL('http://x' + req.url).searchParams.get('path') || ''; } catch (e0) { qs = ''; }
+      try { qs = decodeURIComponent(qs); } catch (e1) { /* 保持原样 */ }
+      var rfp = safeServePath(qs);
+      if (!rfp) { res.writeHead(403); res.end('forbidden'); return; }
+      if (!/\.html?$/i.test(rfp)) { res.writeHead(403); res.end('只允许查询 .html'); return; }
+      fs.readFile(rfp, 'utf8', function (re1, txt) {
+        if (re1) { res.writeHead(404); res.end('not found'); return; }
+        var rm = txt.match(/"rev"\s*:\s*(\d+)/);
+        var replyRev = function (st) {
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ rev: rm ? parseInt(rm[1], 10) : 0, mtime: st ? st.mtimeMs : 0, size: st ? st.size : txt.length }));
+        };
+        fs.stat(rfp, function (re3, st) { replyRev(re3 ? null : st); });
+      });
+      return;
+    }
+
+    /* 值守心跳查询（v1.33.0，issue#6）：读 .annotatable/<file>.watch.json 报 watcher 存活与心跳年龄。
+       只读端点；路径过 safeServePath 边界校验再限 .html，与 /__annot/rev 同一边界面。
+       页面值守灯据此渲染 在岗/心跳超龄/换班中/无人值守，让人在朝深渊喊话前先看见灯是红的。 */
+    if (req.method === 'GET' && u === '/__annot/status') {
+      var ws0;
+      try { ws0 = new URL('http://x' + req.url).searchParams.get('path') || ''; } catch (e4) { ws0 = ''; }
+      try { ws0 = decodeURIComponent(ws0); } catch (e5) { /* 保持原样 */ }
+      var wsp = safeServePath(ws0);
+      if (!wsp) { res.writeHead(403); res.end('forbidden'); return; }
+      if (!/\.html?$/i.test(wsp)) { res.writeHead(403); res.end('只允许查询 .html'); return; }
+      var replyStatus = function (o) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(o));
+      };
+      fs.readFile(path.join(path.dirname(wsp), '.annotatable', path.basename(wsp) + '.watch.json'), 'utf8', function (we4, wt4) {
+        if (we4) { replyStatus({ watching: false, state: 'none', ageSec: -1 }); return; }
+        try {
+          var wj = JSON.parse(wt4);
+          replyStatus({
+            watching: wj.state === 'watching',
+            state: wj.state || 'none',
+            ageSec: Math.max(0, Math.round((Date.now() - (wj.lastBeat || 0)) / 1000)),
+            pid: wj.pid || 0, startedAt: wj.startedAt || 0
+          });
+        } catch (e6) { replyStatus({ watching: false, state: 'none', ageSec: -1 }); }   // 撕裂心跳 ≈ 无心跳，按保守渲染
+      });
+      return;
+    }
+
+    /* 主题工坊页（v1.17.0）：仅 annotatable studio 启动时提供，内存直出不落盘 */
+    if (req.method === 'GET' && u === '/__annot/studio') {
+      if (!studioProvider) { res.writeHead(404); res.end('studio 未随 annotatable studio 启动'); return; }
+      try {
+        res.writeHead(200, { 'Content-Type': MIME['.html'] });
+        res.end(studioProvider());
+      } catch (e) { res.writeHead(500); res.end(String(e.message || e)); }
+      return;
+    }
+
+    /* 主题工坊保存（v1.17.0）：仅两种固定目标（伺服根目录 / ~/.annotatable），
+       文件名服务端写死，无路径遍历面 */
+    if (req.method === 'POST' && u === '/__annot/theme') {
+      if (!sameOriginGuard(req, res)) return;
+      readJsonBody(req, res, 2 * 1024 * 1024, function (o) {
+        try {
+          if (!o || typeof o.css !== 'string' || (o.css && o.css.indexOf('\x00') !== -1)) throw new Error('bad payload');
+          if (o.css.length > 1024 * 1024) throw new Error('css 过大');
+          var target = o.scope === 'global'
+            ? path.join(os.homedir(), '.annotatable', 'annotatable.theme.css')
+            : path.join(root, 'annotatable.theme.css');
+          fs.mkdirSync(path.dirname(target), { recursive: true });
+          fs.writeFileSync(target, o.css);
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: true, path: target }));
+        } catch (e) {
+          res.writeHead(400); res.end(String(e.message || e));
+        }
+      });
+      return;
+    }
+
+    /* 受控写回：仅伺服目录内、仅 .html，防路径越界 */
+    if (req.method === 'POST' && u === '/__annot/save') {
+      if (!sameOriginGuard(req, res)) return;
+      readJsonBody(req, res, 20 * 1024 * 1024, function (o) {
+        try {
+          if (!o || typeof o.path !== 'string' || typeof o.html !== 'string') throw new Error('bad payload');
+          var rel = o.path;
+          try { rel = decodeURIComponent(rel); } catch (e0) { /* 保持原样 */ }   // location.pathname 是百分号编码，中文文件名须解码
+          var target = path.resolve(root, '.' + rel);
+          if (target !== root && target.indexOf(root + path.sep) !== 0) throw new Error('路径越界');
+          if (!/\.html?$/i.test(target)) throw new Error('只允许写入 .html');
+          if (!fs.existsSync(target)) throw new Error('目标文件不在伺服目录中');
+          /* v1.26.0：rev 复验 + 文档锁 + 原子写 + 写票（saveDocHtml 内部完成）。
+             baseRev 缺省 = 老页面，跳过校验按现状放行；rev 不符 → 409+diskRev，
+             浏览器收到后自动重基合并重试（serverSaveNow 的 409 分支）。 */
+          var sr = core.saveDocHtml(target, o.html, (typeof o.rev === 'number' ? o.rev : null), 'serve');
+          if (!sr.ok) {
+            res.writeHead(409, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'rev-conflict', diskRev: sr.diskRev }));
+            return;
+          }
+          res.writeHead(200); res.end('saved');
+        } catch (e) {
+          res.writeHead(400); res.end(String(e.message || e));
+        }
+      });
+      return;
+    }
+
+    /* v1.26.0 读侧车账本（修待改进⑬半边）：serve 模式页面的「回退恢复原文」/回滚
+       由此取历史快照（FS Access 模式浏览器直读 .annotatable/，不走这里）。
+       只读、限伺服目录内 .html，core.histForFile 内部按 DOC_ID 归属校验防互染。 */
+    if (req.method === 'GET' && u === '/__annot/hist') {
+      var hq;
+      try { hq = new URL('http://x' + req.url).searchParams.get('path') || ''; } catch (e1) { hq = ''; }
+      try { hq = decodeURIComponent(hq); } catch (e2) { /* 保持原样 */ }
+      var hfp = safeServePath(hq);
+      if (!hfp) { res.writeHead(403); res.end('forbidden'); return; }
+      if (!/\.html?$/i.test(hfp)) { res.writeHead(403); res.end('只允许查询 .html'); return; }
+      try {
+        var hj = JSON.stringify(core.histForFile(hfp));   // 先算后写头：histForFile 抛错（如坏路径 ENOENT）走 404，不打崩 serve
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(hj);
+      } catch (e3) {
+        if (!res.headersSent) { res.writeHead(404); res.end('not found'); } else res.end();
+      }
+      return;
+    }
+
+    /* v1.31.0 写侧车账本（serve 页面档案缺失收口）：此前 serve 模式只读不写，浏览器保存的
+       全量历史（含批注层快照/大纸条）无处落盘——版本历史面板「缺批注层快照」、回滚残废。
+       与读端点对称：限伺服目录内 .html；锁内 DOC_ID/文件名归属校验防互染
+       （core.writeHistForFile 内部完成，不符退 409），条数按盘上 store.histCaps 收敛。 */
+    if (req.method === 'POST' && u === '/__annot/hist') {
+      if (!sameOriginGuard(req, res)) return;
+      readJsonBody(req, res, 20 * 1024 * 1024, function (o) {
+        try {
+          if (!o || typeof o.path !== 'string' || !o.hist || typeof o.hist !== 'object') throw new Error('bad payload');
+          var grel = o.path;
+          try { grel = decodeURIComponent(grel); } catch (e0) { /* 保持原样 */ }
+          var gtarget = path.resolve(root, '.' + grel);
+          if (gtarget !== root && gtarget.indexOf(root + path.sep) !== 0) throw new Error('路径越界');
+          if (!/\.html?$/i.test(gtarget)) throw new Error('只允许写 .html 的档案');
+          if (!fs.existsSync(gtarget)) throw new Error('目标文件不在伺服目录中');
+          var gr = core.writeHistForFile(gtarget, o.hist);
+          if (!gr.ok) {
+            res.writeHead(409, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: gr.error }));
+            return;
+          }
+          res.writeHead(200); res.end('hist-saved');
+        } catch (e) {
+          res.writeHead(400); res.end(String(e.message || e));
+        }
+      });
+      return;
+    }
+
+    /* 静态伺服（限制在 root 内） */
+    var rel = u.replace(/^\/+/, '');
+    var fp = rel ? path.resolve(root, rel) : root;
+    if (fp !== root && fp.indexOf(root + path.sep) !== 0) { res.writeHead(403); res.end('forbidden'); return; }
+    fs.stat(fp, function (err, st) {
+      if (!err && st.isDirectory()) fp = path.join(fp, 'index.html');
+      fs.readFile(fp, function (err2, data) {
+        if (err2) { res.writeHead(404); res.end('not found'); return; }
+        res.writeHead(200, { 'Content-Type': MIME[path.extname(fp).toLowerCase()] || 'application/octet-stream' });
+        res.end(data);
+      });
+    });
+  });
+
+  /* v1.26.1：一个坏请求/边角 bug 不再打死整个 serve（值守生命线）——记日志继续伺服。
+     代价：出异常的那条响应可能挂到浏览器超时重试，可接受；无此守卫时进程直接退出，全部自动保存失联。 */
+  if (!(opts && opts.managed)) process.on('uncaughtException', function (err) {
+    console.error('[' + new Date().toISOString() + '] serve 吞掉未捕获异常（继续伺服）: ' + ((err && err.stack) || err));
+  });
+
+  /* v1.27.1：绑定失败必须说实话。此前 EADDRINUSE 没挂 error 监听，异常落进上面的
+     uncaughtException 兜底、嘴上打印「继续伺服」，实际服务器从未 bind 成功、事件循环
+     清空后进程静默退出——值守以为活着，自动保存全失联。现如实报错并探测占用者身份后退出。 */
+  var rejectStart;
+  server.on('error', function (e) {
+    if (opts && opts.managed) { if (rejectStart) rejectStart(e); return; }
+    var code = (e && e.code) || 'UNKNOWN';
+    if (code !== 'EADDRINUSE') {
+      console.error('❌ serve 端口监听失败（' + code + '）：' + ((e && e.message) || e));
+      process.exit(1);
+      return;
+    }
+    console.error('❌ 端口 ' + port + ' 已被占用，serve 没有启动。');
+    probeSelf(port, function (isAnnot) {
+      if (isAnnot) {
+        console.error('   占用者就是另一个 annotatable serve——多半是上次值守/演示没停干净的孤儿进程（HANDOFF 已知坑）。');
+        console.error('   处置二选一：直接复用现有 http://localhost:' + port + '；');
+        console.error('             或 netstat -ano | findstr ":' + port + '" 查 PID 后 taskkill //F //PID <pid>，再重启。');
+      } else {
+        console.error('   处置二选一：换端口重启（--port <其他>，或 --port 0 让系统挑空闲端口）；');
+        console.error('             或 netstat -ano | findstr ":' + port + '" 查占用者 PID，确认不要就 taskkill //F //PID <pid>。');
+      }
+      process.exit(1);
+    });
+  });
+
+  return new Promise(function (resolve, reject) {
+    rejectStart = reject;
+    server.listen(port, '127.0.0.1', function () {
+      var actual = (server.address() && server.address().port) || port;   // --port 0 时以系统实配为准
+      var info = { url: 'http://localhost:' + actual, root: root, port: actual };
+      if (opts && opts.managed) info.close = function () { return new Promise(function (done) { server.close(done); }); };
+      resolve(info);
+    });
+  });
+}
+
+module.exports = { start: start };