poi-plugin-mcp 0.2.25 → 0.2.27

package/lib/bridge-controller.js

@@ -1,3 +1,4 @@
+const path = require('path')
 const { createPoiDataBridge } = require('./poi-http-bridge')
 const { loadOrCreateInputToken } = require('./input-token')
 const {
@@ -10,13 +11,14 @@ const {
 function createBridgeController(options = {}) {
   const settingsPath = options.settingsPath || DEFAULT_SETTINGS_FILE
   const logger = options.logger || console
-  const createBridge = options.createBridge || createPoiDataBridge
+  let createBridge = options.createBridge || createPoiDataBridge
 
   let settings = loadSettings(settingsPath)
   let bridge = null
   let recorder = null
   let inputToken = options.inputToken || null
   let pending = Promise.resolve()
+  let reloading = false
 
   function enqueue(action) {
     pending = pending.then(action, action)
@@ -48,6 +50,8 @@ function createBridgeController(options = {}) {
       port: settings.port,
       portFile: options.portFile,
       logger,
+      isWriterTokenEnforced: () => settings.writerTokenEnforced === true,
+      reloadModules: hotReloadModules,
     })
   }
 
@@ -99,6 +103,64 @@ function createBridgeController(options = {}) {
     await runningBridge.stop()
   }
 
+  /**
+   * Hot reload (2026-09-12): purge this plugin's lib/ require cache and
+   * rebuild the bridge from the on-disk code. Live instances (this
+   * controller, the telemetry object wired in index.js, the recorder) keep
+   * their closures and state; only the module table refreshes. Returns after
+   * validation — the swap is scheduled so the HTTP response can flush first.
+   */
+  function hotReloadModules() {
+    if (reloading) {
+      return Promise.reject(new Error('a reload is already in progress'))
+    }
+    return enqueue(async () => {
+      reloading = true
+      try {
+        const libRoot = __dirname
+        for (const key of Object.keys(require.cache)) {
+          if (key.startsWith(libRoot + path.sep) || key === libRoot) {
+            delete require.cache[key]
+          }
+        }
+        // Fresh require throws on a broken build → old bridge untouched.
+        const fresh = require('./poi-http-bridge')
+        const freshFactory = fresh.createPoiDataBridge
+        if (typeof freshFactory !== 'function') {
+          throw new Error('fresh poi-http-bridge does not export createPoiDataBridge')
+        }
+        // Re-read settings: the fresh settings module may normalize new keys.
+        const freshSettings = require('./settings')
+        settings = freshSettings.normalizeSettings(
+          freshSettings.loadSettings(settingsPath),
+        )
+        createBridge = freshFactory
+        const wasEnabled = settings.enabled
+        // Let the /admin/reload response flush on the old connection before
+        // it drops; the swap then runs on the controller's serial queue.
+        setTimeout(() => {
+          enqueue(async () => {
+            try {
+              await stopCurrentBridge()
+              if (wasEnabled) await ensureStarted()
+              logger.log('[poi-plugin-mcp] hot reload complete')
+            } catch (error) {
+              logger.error(`[poi-plugin-mcp] hot reload swap failed: ${error.message}`)
+              // Best effort: the factory is already fresh; the next
+              // ensureStarted (any settings apply or manual start) recovers.
+              try {
+                if (wasEnabled) await ensureStarted()
+              } catch (_) { /* surfaced by the next status poll */ }
+            }
+          })
+        }, 250)
+        return { port: settings.port, deferredSwap: true }
+      } finally {
+        reloading = false
+      }
+    })
+  }
+
   function persist(nextSettings) {
     settings = saveSettings(normalizeSettings(nextSettings), settingsPath)
     return settings
@@ -175,6 +237,18 @@ function createBridgeController(options = {}) {
       return { ...settings }
     },
 
+    /**
+     * 2026-09-12 hot reload: rebuild the HTTP/input layer from the on-disk
+     * lib/ code without restarting poi. Telemetry getters are re-injected
+     * (event generations survive); the recorder session is untouched.
+     *
+     * Ordering: the fresh modules are required BEFORE anything stops — a bad
+     * build throws here, the old bridge keeps serving, and the caller gets a
+     * 500 with the require error. The swap itself is deferred so the
+     * /admin/reload response flushes on the old connection before it drops.
+     */
+    reloadModules: hotReloadModules,
+
     getStatus() {
       const actualPort = bridge ? bridge.getPort() : 0
       const recorderStatus = recorder && typeof recorder.getStatus === 'function'

package/lib/pixi-hit-ledger.js

@@ -0,0 +1,259 @@
+'use strict'
+
+/**
+ * Per-click PIXI hit ledger (0913 admiral ruling: every dispatched click must
+ * name the control it landed on).
+ *
+ * Evidence contract — this ledger is a WITNESS, never a judge:
+ *   - The snapshot is read immediately BEFORE the synthetic input event is
+ *     queued, so a tree mutation inside the dispatch window can still make
+ *     it stale. The authoritative "did the click take effect" signal stays
+ *     the matching API event plus the final-state audit.
+ *   - `eventHit` comes from the game's own hit resolution (EventSystem /
+ *     InteractionManager hitTest) when available; `containment` is a
+ *     world-AABB approximation whose stack makes occlusion visible.
+ *   - Failure is fail-soft: an unavailable probe records why and never
+ *     blocks the dispatch.
+ */
+const fs = require('node:fs')
+const path = require('node:path')
+
+const MAX_STACK = 8
+const MAX_VISIT = 4000
+const MAX_DEPTH = 40
+// Wall-clock bound for the whole snapshot. The page-side script has its own
+// 1500ms timeout, but a throttled renderer can stall the IPC channel until
+// the runtime's 10s inspection bound — a witness must never gate dispatch.
+const CAPTURE_WALL_MS = 1800
+
+function buildHitTestScript(x, y) {
+  return `(() => {
+  const px = ${JSON.stringify(x)}, py = ${JSON.stringify(y)};
+  const shared = globalThis.PIXI && globalThis.PIXI.ticker && globalThis.PIXI.ticker.shared;
+  const head = shared && shared._head;
+  const renderers = [];
+  let node = head ? head.next : null;
+  let guard = 0;
+  while (node && guard < 64) {
+    if (node.context && node.context.renderer) renderers.push(node.context.renderer);
+    node = node.next;
+    guard += 1;
+  }
+  const renderer = renderers.find(
+    (r) => r && r.view && r.view.isConnected === true && r._lastObjectRendered,
+  );
+  if (!renderer) return { available: false, reason: 'stale_renderer' };
+  const describe = (o) => {
+    const record = {};
+    try { record.cls = (o.constructor && o.constructor.name) || null; } catch (_) { record.cls = null; }
+    try { record.name = typeof o.name === 'string' && o.name ? o.name : null; } catch (_) { record.name = null; }
+    try {
+      const tex = o.texture;
+      record.texture = tex && typeof tex.url === 'string' ? tex.url : null;
+      // Atlas forensics (0913 admiral request): the sprite's frame inside its
+      // source atlas sheet + the sheet URL let a hit record be mapped back to
+      // the exact rectangle of the ORIGINAL art for offline cropping/filter.
+      try {
+        const base = tex && tex.baseTexture;
+        const frame = tex && tex.frame;
+        record.atlas = {
+          url: base && typeof base.imageUrl === 'string' ? base.imageUrl : null,
+          frame: frame
+            ? [
+                Math.round(frame.x), Math.round(frame.y),
+                Math.round(frame.width), Math.round(frame.height),
+              ]
+            : null,
+          rotate: tex && typeof tex.rotate === 'number' ? tex.rotate : 0,
+        };
+      } catch (_) { record.atlas = null; }
+    } catch (_) { record.texture = null; record.atlas = null; }
+    try {
+      const b = o.getBounds ? o.getBounds() : null;
+      record.bounds = b
+        ? [Math.round(b.x), Math.round(b.y), Math.round(b.width), Math.round(b.height)]
+        : null;
+    } catch (_) { record.bounds = null; }
+    try {
+      record.interactive = o.eventMode
+        ? o.eventMode !== 'auto' && o.eventMode !== 'none' && o.eventMode !== 'passive'
+        : o.interactive === true;
+    } catch (_) { record.interactive = null; }
+    try { record.visible = o.visible !== false; } catch (_) { record.visible = null; }
+    try { record.alpha = typeof o.alpha === 'number' ? Math.round(o.alpha * 100) / 100 : null; } catch (_) { record.alpha = null; }
+    return record;
+  };
+  const chain = (o) => {
+    const path = [];
+    let cur = o;
+    let steps = 0;
+    while (cur && steps < 6) {
+      path.push((cur.constructor && cur.constructor.name) || 'unknown');
+      cur = cur.parent;
+      steps += 1;
+    }
+    return path;
+  };
+  // 1) The game's own hit resolution — interactive targets only.
+  let eventHit = null;
+  try {
+    const point = { x: px, y: py };
+    const events = renderer.events
+      || (renderer.plugins && renderer.plugins.event)
+      || (renderer.plugins && renderer.plugins.interaction);
+    if (events && typeof events.hitTest === 'function') {
+      const target = events.hitTest(point);
+      if (target) {
+        eventHit = describe(target);
+        eventHit.path = chain(target);
+      }
+    }
+  } catch (_) { eventHit = null; }
+  // 2) World-AABB containment stack — approximate paint order (later entry
+  //    ≈ on top within its branch); makes occlusion (family pages over stale
+  //    choice pairs) visible in the record itself.
+  const stack = [];
+  let visited = 0;
+  const walk = (o, depth) => {
+    if (!o || depth > ${MAX_DEPTH} || visited > ${MAX_VISIT} || stack.length >= ${MAX_STACK}) return;
+    visited += 1;
+    try {
+      if (o.visible !== false && o.renderable !== false) {
+        const b = o.getBounds ? o.getBounds() : null;
+        if (
+          b && px >= b.x && px <= b.x + b.width && py >= b.y && py <= b.y + b.height
+        ) {
+          stack.push(describe(o));
+        }
+      }
+    } catch (_) { /* a node that cannot be described is skipped, not fatal */ }
+    if (stack.length >= ${MAX_STACK}) return;
+    const kids = o.children;
+    if (Array.isArray(kids)) {
+      for (let i = 0; i < kids.length; i += 1) walk(kids[i], depth + 1);
+    }
+  };
+  try { walk(renderer._lastObjectRendered, 0); } catch (_) { /* partial stack is still evidence */ }
+  return {
+    available: true,
+    point: { x: px, y: py },
+    eventHit,
+    containmentCount: stack.length,
+    topmost: stack.length > 0 ? stack[stack.length - 1] : null,
+    stack,
+  };
+})()`
+}
+
+function createPixiHitLedger(options = {}) {
+  const evaluate = options.evaluate
+  const listFrames = options.listFrames
+  const logger = options.logger || console
+  const now = options.now || (() => new Date())
+  const captureWallMs = options.captureWallMs || CAPTURE_WALL_MS
+  const appendFile = options.appendFile
+    || ((file, line) => fs.promises.appendFile(file, line, 'utf8'))
+  const ledgerFile = options.ledgerFile || null
+  let lastFrameId = null
+  let lastFrameLookupAt = 0
+  let ledgerWrite = Promise.resolve()
+
+  if (typeof evaluate !== 'function' || typeof listFrames !== 'function') {
+    return Object.freeze({
+      async capture() { return Object.freeze({ available: false, reason: 'runtime_unavailable' }) },
+    })
+  }
+
+  async function resolveGameFrameId() {
+    const at = Date.now()
+    if (lastFrameId && at - lastFrameLookupAt < 2000) return lastFrameId
+    const frames = await listFrames()
+    const game = frames.find((f) => /kcs2/i.test(f.url || '')) || frames[0]
+    if (!game) return null
+    lastFrameId = game.id
+    lastFrameLookupAt = at
+    return game.id
+  }
+
+  function appendToLedger(line) {
+    if (!ledgerFile) return
+    ledgerWrite = ledgerWrite
+      .then(() => appendFile(ledgerFile, line))
+      .catch((error) => {
+        logger.error(`[poi-plugin-mcp] hit ledger append failed: ${error.message}`)
+      })
+  }
+
+  /**
+   * Snapshot what the live PIXI tree shows at the operation's canonical
+   * point. Never throws: an unavailable probe is a recorded outcome.
+   */
+  async function capture(operation, context = {}) {
+    const capturedAt = now().toISOString()
+    const isClick = operation.operation === 'click'
+    const point = isClick
+      ? { x: operation.x, y: operation.y }
+      : operation.operation === 'drag'
+        ? { x: operation.fromX, y: operation.fromY }
+        : null
+    if (point === null) return Object.freeze({ available: false, reason: 'not_pointer' })
+    const record = {
+      at: capturedAt,
+      operation: operation.operation,
+      point,
+      ...(context.leaseId === undefined ? {} : { leaseId: context.leaseId }),
+      ...(context.ownerSessionId === undefined ? {} : { ownerSessionId: context.ownerSessionId }),
+      ...(context.runId === undefined ? {} : { runId: context.runId }),
+      ...(context.action === undefined ? {} : { action: context.action }),
+    }
+    try {
+      const frameId = await resolveGameFrameId()
+      if (frameId === null) {
+        return Object.freeze({ ...record, available: false, reason: 'game_frame_not_found' })
+      }
+      const response = await Promise.race([
+        evaluate({
+          frameId,
+          script: buildHitTestScript(point.x, point.y),
+          timeoutMs: 1500,
+        }),
+        new Promise((_, reject) => {
+          setTimeout(
+            () => reject(new Error('capture_wall_timeout')),
+            captureWallMs,
+          )
+        }),
+      ])
+      const value = response && response.value
+      // Every outcome is appended — a witness with gaps is worse than a
+      // witness with anomalies (a probe that ran but returned nothing
+      // non-object is itself diagnostic evidence).
+      const hit = value === null || typeof value !== 'object'
+        ? { ...record, available: false, reason: 'probe_empty' }
+        : { ...record, ...value }
+      appendToLedger(`${JSON.stringify(hit)}\n`)
+      return Object.freeze(hit)
+    } catch (error) {
+      const hit = { ...record, available: false, reason: `probe_failed:${error.message}` }
+      appendToLedger(`${JSON.stringify(hit)}\n`)
+      return Object.freeze(hit)
+    }
+  }
+
+  return Object.freeze({ capture })
+}
+
+function defaultLedgerFile(portFile) {
+  if (!portFile || typeof portFile !== 'string') return null
+  try {
+    return path.join(path.dirname(portFile), 'hit-ledger.jsonl')
+  } catch (_) {
+    return null
+  }
+}
+
+module.exports = {
+  buildHitTestScript,
+  createPixiHitLedger,
+  defaultLedgerFile,
+}

package/lib/poi-http-bridge.js

@@ -5,6 +5,7 @@ const os = require('os')
 const path = require('path')
 const packageJson = require('../package.json')
 const { loadOrCreateInputToken } = require('./input-token')
+const { getWriterTokenRegistry, hasValidWriterToken } = require('./writer-tokens')
 const { createPoiInputProvider } = require('./poi-input')
 const { createPoiInputLease } = require('./poi-input-lease')
 const { createPoiScreenshotProvider } = require('./poi-screenshot')
@@ -19,6 +20,10 @@ const {
   speedFromRaw,
   speedMeaning,
 } = require('./fleet-metrics')
+const {
+  createPixiHitLedger,
+  defaultLedgerFile,
+} = require('./pixi-hit-ledger')
 
 const DEFAULT_PORT = 17777
 const DEFAULT_PORT_FILE = path.join(os.homedir(), '.poi-mcp', 'port')
@@ -107,6 +112,14 @@ function createPoiDataBridge(options = {}) {
     inputEnabled ? loadOrCreateInputToken(options.inputTokenFile) : null
   )
   const inputLease = options.inputLease || createPoiInputLease(options.inputLeaseOptions)
+  // 2026-09-12 Phase C: daemon-delegated writer tokens gate the INPUT
+  // surface (clicks, lease takes, debug-eval). Module-level singleton so
+  // settings-triggered bridge re-creation keeps the registered set; a hot
+  // reload purges the module, and the daemon's periodic re-registration
+  // self-heals within one idle cycle.
+  const writerTokens = options.writerTokens || getWriterTokenRegistry()
+  const isWriterTokenEnforced = options.isWriterTokenEnforced ||
+    (() => options.writerTokenEnforced === true)
   let captureScreenshot = options.captureScreenshot || null
   let performInput = options.performInput || null
   let dataQuery = options.dataQuery || null
@@ -116,6 +129,33 @@ function createPoiDataBridge(options = {}) {
   let inputPending = Promise.resolve()
   const pendingActionEventWaits = new Set()
 
+  /**
+   * Writer-token gate for input-capable endpoints. Callers have already
+   * validated the static bearer (transport auth). Three outcomes:
+   * registered token -> pass; missing/rejected token + enforcement -> 403
+   * with a reason a stale process can act on; missing token in observation
+   * mode -> pass and count (legacyAuth), which is the bridge-side
+   * foreign-writer signal.
+   */
+  function authorizeWriterInput(req) {
+    const headerValue = req.headers['x-writer-token']
+    if (hasValidWriterToken(headerValue, writerTokens)) {
+      return { ok: true }
+    }
+    if (isWriterTokenEnforced()) {
+      return {
+        ok: false,
+        status: 403,
+        error:
+          'Writer token rejected: no registered X-Writer-Token matches. ' +
+          'Stale process from a previous daemon generation? Re-submit the work ' +
+          'through the daemon (kc daemon submit) or renew the token.',
+      }
+    }
+    writerTokens.noteLegacyAuth(Date.now(), `${req.method} ${req.url}`)
+    return { ok: true, legacy: true }
+  }
+
   function readStore() {
     const store = getStore()
     if (!store || !store.info) {
@@ -160,6 +200,19 @@ function createPoiDataBridge(options = {}) {
     return dataQuery
   }
 
+  let hitLedger = null
+  function currentHitLedger() {
+    if (!hitLedger) {
+      hitLedger = createPixiHitLedger({
+        evaluate: (request) => currentDataQuery().runtime.evaluate(request),
+        listFrames: () => currentDataQuery().runtime.listFrames(),
+        ledgerFile: defaultLedgerFile(portFile),
+        logger,
+      })
+    }
+    return hitLedger
+  }
+
   async function handleDataRequest(req, res, endpoint) {
     if (req.method !== 'POST') {
       drainRequest(req)
@@ -176,6 +229,17 @@ function createPoiDataBridge(options = {}) {
       )
       return
     }
+    // /debug/evaluate executes arbitrary JS in the game WebView — it is a
+    // write-capable channel and takes the writer-token gate. /query is a
+    // read and stays static-bearer (diagnostics keep working).
+    if (endpoint === '/debug/evaluate') {
+      const writer = authorizeWriterInput(req)
+      if (!writer.ok) {
+        drainRequest(req)
+        sendInputJson(res, writer.status, { error: writer.error })
+        return
+      }
+    }
     try {
       const body = await readRequestBody(
         req,
@@ -218,10 +282,28 @@ function createPoiDataBridge(options = {}) {
       if (!performInput) {
         performInput = createPoiInputProvider({ getStore })
       }
+      // 0913 per-click hit ledger (admiral ruling): snapshot what the live
+      // PIXI tree shows at the pointer before dispatch, gated by the same
+      // debugEvalEnabled setting that owns WebView evaluation. Evidence
+      // only — the response field and ~/.poi-mcp/hit-ledger.jsonl never
+      // gate the dispatch itself (capture is fail-soft and wall-bounded).
+      let hit
+      if (
+        debugEvalEnabled === true &&
+        (operation.operation === 'click' || operation.operation === 'drag')
+      ) {
+        hit = await currentHitLedger().capture(operation, {
+          leaseId: claim.leaseId,
+          ownerSessionId: claim.ownerSessionId,
+          runId: claim.runId,
+          action: claim.action,
+        })
+      }
       const operationName = await performInput(operation)
       return {
         ok: true,
         operation: operationName,
+        ...(hit === undefined ? {} : { hit }),
         sequence: claim.sequence,
         leaseId: claim.leaseId,
         ownerSessionId: claim.ownerSessionId,
@@ -261,6 +343,12 @@ function createPoiDataBridge(options = {}) {
       sendInputJson(res, 403, { error: 'WebView input is disabled.' })
       return
     }
+    const writer = authorizeWriterInput(req)
+    if (!writer.ok) {
+      drainRequest(req)
+      sendInputJson(res, writer.status, { error: writer.error })
+      return
+    }
 
     try {
       const body = await readRequestBody(
@@ -295,6 +383,24 @@ function createPoiDataBridge(options = {}) {
       )
       return
     }
+    // Lease MUTATIONS (acquire/renew/release/revoke) are input-adjacent —
+    // they gate who may click — so the writer-token applies. The plain
+    // GET /input/lease status read stays static-bearer (live 0912: the
+    // dashboard's takeover-button poll flooded the legacy counter and would
+    // 403 under enforcement; reads must not take the writer gate).
+    const leaseMutation =
+      endpoint === '/input/lease/acquire' ||
+      endpoint === '/input/lease/renew' ||
+      endpoint === '/input/lease/release' ||
+      endpoint === '/input/lease/revoke'
+    if (leaseMutation) {
+      const leaseWriter = authorizeWriterInput(req)
+      if (!leaseWriter.ok) {
+        drainRequest(req)
+        sendInputJson(res, leaseWriter.status, { error: leaseWriter.error })
+        return
+      }
+    }
     if (endpoint === '/input/lease') {
       if (req.method !== 'GET') {
         drainRequest(req)
@@ -527,6 +633,79 @@ function createPoiDataBridge(options = {}) {
         return
       }
 
+      // 2026-09-12 Phase C: writer-token administration. The static bearer is
+      // the ADMIN credential here — exactly one caller (the daemon) uses it
+      // to delegate; input endpoints no longer accept it as a writer.
+      if (endpoint === '/writer-tokens') {
+        if (!hasValidBearerToken(req.headers.authorization, inputToken)) {
+          drainRequest(req)
+          sendInputJson(res, 401, { error: 'A valid Bearer token is required.' })
+          return
+        }
+        if (req.method === 'GET') {
+          sendInputJson(res, 200, {
+            enforced: isWriterTokenEnforced(),
+            ...writerTokens.status(),
+          })
+          return
+        }
+        if (req.method !== 'PUT') {
+          drainRequest(req)
+          sendInputJson(res, 405, { error: '/writer-tokens accepts GET or PUT.' })
+          return
+        }
+        try {
+          const body = await readRequestBody(
+            req,
+            MAX_QUERY_BODY_BYTES,
+            'Writer token request body exceeds 64KB.',
+          )
+          const payload = JSON.parse(body || '{}')
+          const outcome = writerTokens.register(payload)
+          sendInputJson(res, 200, { ok: true, ...outcome, ...writerTokens.status() })
+        } catch (error) {
+          sendInputJson(res, 400, { error: error.message })
+        }
+        return
+      }
+
+      // 2026-09-12 hot reload: rebuild the HTTP/input layer from the on-disk
+      // lib/ code without restarting poi. Telemetry state and the recorder
+      // session survive (the controller re-injects the same getters); open
+      // connections drop and clients reconnect.
+      if (endpoint === '/admin/reload') {
+        if (!hasValidBearerToken(req.headers.authorization, inputToken)) {
+          drainRequest(req)
+          sendInputJson(res, 401, { error: 'A valid Bearer token is required.' })
+          return
+        }
+        if (req.method !== 'POST') {
+          drainRequest(req)
+          sendInputJson(res, 405, { error: '/admin/reload only accepts POST.' })
+          return
+        }
+        drainRequest(req)
+        if (typeof options.reloadModules !== 'function') {
+          sendInputJson(res, 501, { error: 'reloadModules is not wired by this controller build' })
+          return
+        }
+        try {
+          const outcome = await options.reloadModules()
+          // After a successful reload THIS bridge instance is stopped and the
+          // fresh one owns the port — report the outcome's port, not the
+          // stale local getPort().
+          sendInputJson(res, 200, {
+            ok: true,
+            reloaded: true,
+            port: (outcome && outcome.port) || getPort(),
+            ...(outcome || {}),
+          })
+        } catch (error) {
+          sendInputJson(res, 500, { ok: false, error: error.message })
+        }
+        return
+      }
+
       if (endpoint === '/screenshot') {
         if (req.method !== 'GET') {
           sendJson(
@@ -769,6 +948,15 @@ function createPoiDataBridge(options = {}) {
         actualPort = 0
         resolve()
       })
+      // Keep-alive clients (the daemon holds persistent connections) never
+      // let close() finish on their own — reap them, but only after the
+      // aborted long-poll responses had a turn to flush (live 0912: an
+      // immediate reap raced the wait-abort writes into ECONNRESET).
+      setImmediate(() => {
+        if (typeof closingServer.closeAllConnections === 'function') {
+          closingServer.closeAllConnections()
+        }
+      })
     })
   }
 

package/lib/settings.js

@@ -8,6 +8,12 @@ const DEFAULT_SETTINGS = Object.freeze({
   inputEnabled: false,
   recordingEnabled: false,
   debugEvalEnabled: false,
+  // 2026-09-12 Phase C: when true, INPUT endpoints (/input, /input/lease*,
+  // /debug/evaluate) require a registered X-Writer-Token in addition to the
+  // static bearer. Observation mode (false) serves legacy static-bearer
+  // requests but counts them — the daemon registers tokens and sends them
+  // either way, so flipping this only rejects leftovers.
+  writerTokenEnforced: false,
 })
 
 const DEFAULT_SETTINGS_FILE = path.join(os.homedir(), '.poi-mcp', 'settings.json')
@@ -26,6 +32,9 @@ function normalizeSettings(input = {}) {
     debugEvalEnabled: typeof input.debugEvalEnabled === 'boolean'
       ? input.debugEvalEnabled
       : DEFAULT_SETTINGS.debugEvalEnabled,
+    writerTokenEnforced: typeof input.writerTokenEnforced === 'boolean'
+      ? input.writerTokenEnforced
+      : DEFAULT_SETTINGS.writerTokenEnforced,
   }
 }
 

package/lib/writer-tokens.js

@@ -0,0 +1,133 @@
+const crypto = require('crypto')
+
+const TOKEN_PATTERN = /^[a-f0-9]{32,128}$/
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000
+
+/**
+ * Daemon-delegated writer tokens (2026-09-12 single-writer plan, Phase C).
+ *
+ * The static input token authorizes whoever can read the file — forever. A
+ * zombie from an earlier session therefore holds a valid credential forever.
+ * This registry replaces that for INPUT endpoints: the daemon mints short
+ * lived tokens (a generation token for itself, one per spawned job), pushes
+ * them here over the admin endpoint, and revokes job tokens when the reaper
+ * collects the job. A process that missed a rotation is rejected with a
+ * readable reason instead of silently competing for clicks.
+ *
+ * Module-level singleton: bridge restarts (settings apply, hot reload) must
+ * not silently drop the registered set — and when a hot reload DOES purge
+ * this module, the daemon's periodic re-registration self-heals within one
+ * idle cycle. The threat model is accidents, not adversaries: holding a
+ * current token is a sufficient proxy for "delegated by the current daemon
+ * generation", so there is deliberately no per-pid challenge/response.
+ */
+function createWriterTokenRegistry() {
+  const entries = new Map() // token -> { label, registeredAt, expiresAt }
+  let legacyAuthCount = 0
+  let lastLegacyAuthAt = null
+  let lastLegacyAuthDetail = null
+
+  function sweep(now = Date.now()) {
+    for (const [token, entry] of entries) {
+      if (entry.expiresAt <= now) entries.delete(token)
+    }
+  }
+
+  return {
+    register(payload, now = Date.now()) {
+      const mode = payload && (payload.mode === 'add' || payload.mode === 'remove') ? payload.mode : 'replace'
+      const list = payload && Array.isArray(payload.tokens) ? payload.tokens : []
+      if (mode === 'replace') entries.clear()
+      let accepted = 0
+      let rejected = []
+      for (const item of list) {
+        const token = item && typeof item.token === 'string' ? item.token : null
+        if (!TOKEN_PATTERN.test(token || '')) {
+          rejected.push('invalid token shape')
+          continue
+        }
+        const ttlMs = Number.isFinite(item.ttlMs) && item.ttlMs > 0 && item.ttlMs <= 7 * DEFAULT_TTL_MS
+          ? Math.trunc(item.ttlMs)
+          : DEFAULT_TTL_MS
+        entries.set(token, {
+          label: typeof item.label === 'string' && item.label !== '' ? item.label.slice(0, 128) : 'unlabeled',
+          registeredAt: now,
+          expiresAt: now + ttlMs,
+        })
+        accepted += 1
+      }
+      if (mode === 'remove') {
+        for (const item of list) {
+          if (item && typeof item.label === 'string') {
+            for (const [token, entry] of entries) {
+              if (entry.label === item.label) entries.delete(token)
+            }
+          }
+        }
+      }
+      sweep(now)
+      return { accepted, rejected: rejected.length }
+    },
+
+    validate(token, now = Date.now()) {
+      if (typeof token !== 'string' || !TOKEN_PATTERN.test(token)) return false
+      const entry = entries.get(token)
+      if (!entry) return false
+      if (entry.expiresAt <= now) {
+        entries.delete(token)
+        return false
+      }
+      return true
+    },
+
+    noteLegacyAuth(now = Date.now(), detail = null) {
+      legacyAuthCount += 1
+      lastLegacyAuthAt = new Date(now).toISOString()
+      lastLegacyAuthDetail = typeof detail === 'string' && detail !== '' ? detail.slice(0, 160) : null
+    },
+
+    status(now = Date.now()) {
+      sweep(now)
+      return {
+        registered: entries.size,
+        tokens: [...entries.values()].map((entry) => ({
+          label: entry.label,
+          registeredAt: new Date(entry.registeredAt).toISOString(),
+          expiresAt: new Date(entry.expiresAt).toISOString(),
+        })),
+        legacyAuthCount,
+        lastLegacyAuthAt,
+        lastLegacyAuthDetail,
+      }
+    },
+  }
+}
+
+let singleton = null
+
+function getWriterTokenRegistry() {
+  if (!singleton) singleton = createWriterTokenRegistry()
+  return singleton
+}
+
+function mintWriterToken() {
+  return crypto.randomBytes(32).toString('hex')
+}
+
+function hasValidWriterToken(headerValue, registry, now = Date.now()) {
+  if (typeof headerValue !== 'string' || headerValue === '') return false
+  // In-process registry lookup: the timing-safe compare discipline applies to
+  // the STATIC bearer token (a file secret); membership here is an in-memory
+  // Map hit against an unregistered attacker-chosen value with no secret to
+  // leak.
+  return registry.validate(headerValue, now)
+}
+
+module.exports = {
+  TOKEN_PATTERN,
+  DEFAULT_TTL_MS,
+  createWriterTokenRegistry,
+  getWriterTokenRegistry,
+  mintWriterToken,
+  hasValidWriterToken,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poi-plugin-mcp",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "description": "Poi data, WebView capture, and opt-in authenticated input bridge for local KanColle tools.",
   "main": "index.js",
   "keywords": [