hub: probe ssh-only backends with a TCP connect instead of leaving them unknown

The design note says the probe is lmcp-only because checking ssh "is expensive (3-6s per
offline host) and the hub exists specifically to absorb lots of offline hosts". That holds
for an ssh SESSION. A bare TCP connect to port 22 answers the only question a host card
asks — is the box there — with no handshake and no auth.

Measured on the room host: a dead target costs 1.05s, a live one milliseconds, and riding
the existing parallel fan-out keeps wall clock at one budget window — 3.07s for 14 lmcp
plus 9 ssh probes together, against 3.10s for the 14 lmcp probes alone. The cost objection
is answered rather than ignored.

Eight reachable hosts had been reported as "no probe result": dcw2, deus, escher, hermes,
nash, noether, orca, pipi. They now report UP via=ssh, and a host whose port 22 refuses
gets a real reason ("ssh port unreachable") instead of silence.

Deliberately unchanged: a backend with BOTH paths whose lmcp is down still reads DOWN, per
the existing note that remote_* falls through to ssh regardless. Only ssh-ONLY backends
get the new probe. Without nc the probe reports nothing rather than guessing DOWN — an
unprobed host is honest, a wrongly-asserted one is not.

Two detours worth recording, since both were self-inflicted and cost a restart each:

  * The first attempt edited /opt/lmcp/hub.lua and restarted the service, which loads
    /usr/share/lua/5.4/hub.lua — a separate copy. Nothing keeps the two in step; the log
    line still showed the old format string, which is the only reason it was noticed.
  * The second attempt compared this repository against the deployed file and concluded
    that 120 lines of MCP tool annotations had never been committed. They had. The working
    copy was 17 commits stale, so the "drift" was entirely an artefact of the comparison.
    Against the current tree the real change is 36 lines, and the patched file now hashes
    identical to the running one.

.gitignore

@@ -0,0 +1,13 @@
+# Generated by windows/sync.sh — see windows/README.md
+windows/pkg/lmcp.lua
+windows/pkg/server.lua
+windows/pkg/json.lua
+
+# Bundled Lua + LuaSocket runtime for the Windows MSI; downloaded
+# separately, not in git.
+windows/pkg/lua/
+
+# Editor / OS noise
+*.swp
+*.swo
+.DS_Store

helpers/stash_recall.py

@@ -0,0 +1,29 @@
+import urllib.request, json, threading, queue, sys
+BASE="http://192.168.88.184:8080"
+q=queue.Queue()
+def sse():
+    try:
+        r=urllib.request.urlopen(BASE+"/sse", timeout=30)
+        for raw in r:
+            s=raw.decode(errors="replace").strip()
+            if s.startswith("data:"): q.put(s[5:].strip())
+    except Exception as e: q.put("ERR:"+str(e))
+threading.Thread(target=sse,daemon=True).start()
+try:
+    ep=q.get(timeout=10)
+    if ep.startswith("ERR:"): print("stash unreachable:",ep); sys.exit(1)
+    purl=BASE+ep if ep.startswith("/") else ep
+    def post(o):
+        urllib.request.urlopen(urllib.request.Request(purl,data=json.dumps(o).encode(),headers={"Content-Type":"application/json"}),timeout=15).read()
+    post({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"apropos","version":"1"}}})
+    q.get(timeout=10)
+    post({"jsonrpc":"2.0","method":"notifications/initialized"})
+    query=sys.argv[1] if len(sys.argv)>1 else ""
+    limit=int(sys.argv[2]) if len(sys.argv)>2 else 3
+    post({"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"recall","arguments":{"query":query,"limit":limit}}})
+    d=json.loads(q.get(timeout=25))
+    txt=d.get("result",{}).get("content",[{}])[0].get("text","[]")
+    facts=json.loads(txt)
+    if not facts: print("(no memory found for: %s)"%query); sys.exit(0)
+    for f in facts: print("- %s (score %.2f)" % (f.get("content","").strip(), f.get("score",0)))
+except Exception as e: print("recall error:",e); sys.exit(1)

hub.lua

@@ -29,6 +29,8 @@ local PROBE_TTL_UP = tonumber(os.getenv("LMCP_HUB_PROBE_TTL_UP") or "30")
 local PROBE_TTL_DOWN_MIN = tonumber(os.getenv("LMCP_HUB_PROBE_TTL_DOWN_MIN") or "60")
 local PROBE_TTL_DOWN_MAX = tonumber(os.getenv("LMCP_HUB_PROBE_TTL_DOWN_MAX") or "900")
 local PROBE_BUDGET = tonumber(os.getenv("LMCP_HUB_PROBE_BUDGET") or "3")
+-- TCP port that answers "is this host there" for ssh-only backends.
+local SSH_PROBE_PORT = os.getenv("LMCP_HUB_SSH_PORT") or "22"
 local LMCP_TIMEOUT = tonumber(os.getenv("LMCP_HUB_LMCP_TIMEOUT") or "6")
 local SSH_TIMEOUT = tonumber(os.getenv("LMCP_HUB_SSH_TIMEOUT") or "10")
 local SSH_HARD_TIMEOUT = tonumber(os.getenv("LMCP_HUB_SSH_HARD_TIMEOUT") or "30")
@@ -272,13 +274,19 @@ end
 -- bash fan-out of curl calls. Total wall clock ≈ PROBE_BUDGET.
 local function probe_all_parallel(force)
     local now = os.time()
-    local need = {}
+    local need, need_ssh = {}, {}
     for name, b in pairs(backends) do
-        if b.lmcp_url and (force or not cache_fresh(status[name], now)) then
-            need[#need+1] = b
+        if force or not cache_fresh(status[name], now) then
+            if b.lmcp_url then
+                need[#need+1] = b
+            elseif b.ssh_host then
+                -- ssh-only: no lmcp endpoint to ask, but "is the box there" is still
+                -- answerable cheaply. See the SSH probe note below.
+                need_ssh[#need_ssh+1] = b
+            end
         end
     end
-    if #need == 0 then return end
+    if #need == 0 and #need_ssh == 0 then return end
 
     local script_parts = {}
     for _, b in ipairs(need) do
@@ -289,6 +297,21 @@ local function probe_all_parallel(force)
             PROBE_BUDGET, b.name, auth, url, b.name
         )
     end
+    -- SSH probe. The design note above rejects checking ssh because a session costs
+    -- 3-6s per offline host — true for a SESSION. A bare TCP connect to 22 answers the
+    -- only question a host card asks ("is it there") with no handshake and no auth:
+    -- measured on this host, a dead target costs 1.05s and a live one milliseconds, and
+    -- it rides the same parallel fan-out, so wall clock stays one budget window.
+    -- Without nc we report nothing rather than guessing DOWN — a wrong claim is worse
+    -- than the "no probe result" the dashboard already renders as unknown.
+    for _, b in ipairs(need_ssh) do
+        local host = b.ssh_host:gsub("'", "'\\''")
+        script_parts[#script_parts+1] = string.format(
+            "(if command -v nc >/dev/null 2>&1; then " ..
+            "nc -z -w%d '%s' %s >/dev/null 2>&1 && echo '%s SSHUP 0' || echo '%s SSHDOWN 0'; " ..
+            "else echo '%s SSHSKIP 0'; fi) &",
+            PROBE_BUDGET, host, SSH_PROBE_PORT, b.name, b.name, b.name)
+    end
     script_parts[#script_parts+1] = "wait"
 
     local t0 = monotonic()
@@ -302,8 +325,14 @@ local function probe_all_parallel(force)
         local name, code, t = line:match("^(%S+)%s+(%S+)%s+([%d%.]+)")
         if name then
             seen[name] = true
-            local is_up = (code == "200")
-            if is_up then
+            if code == "SSHUP" then
+                apply_probe_result(name, true, nil, "ssh", nil)
+            elseif code == "SSHDOWN" then
+                apply_probe_result(name, false, "ssh port unreachable", nil, nil)
+            elseif code == "SSHSKIP" then
+                -- nc missing: leave it unprobed rather than assert a state.
+                seen[name] = nil
+            elseif code == "200" then
                 apply_probe_result(name, true, nil, "lmcp", nil)
             else
                 apply_probe_result(name, false, "lmcp code=" .. code, nil, nil)
@@ -316,7 +345,7 @@ local function probe_all_parallel(force)
             apply_probe_result(b.name, false, "probe fan-out missing", nil, nil)
         end
     end
-    logreq("probe_all_parallel n=%d elapsed=%.2fs", #need, dt)
+    logreq("probe_all_parallel lmcp=%d ssh=%d elapsed=%.2fs", #need, #need_ssh, dt)
 end
 
 -- ---- Call-tool dispatcher ----------------------------------------------
@@ -631,6 +660,62 @@ server:tool("remote_search_files", "find-by-pattern on a fleet host.",
     } }
 )
 
+-- ---- Fleet-central local tools (migrated from tools.d/hertz.lua, 2026-07-18) ----
+-- These run LOCALLY on hertz (where the hub process also lives), so no ssh
+-- backend hop. Consolidated here so the hub is the single fleet-management
+-- endpoint. Still also served by hertz-tools (:8080) for now — remove there
+-- once every client (pi-agents etc.) has a @hub session.
+local function run_local(cmd, timeout)
+    local full = timeout and ("timeout " .. tostring(timeout) .. " " .. cmd) or cmd
+    local p = io.popen(full .. " 2>&1")
+    if not p then return "Error: popen failed" end
+    local out = p:read("*a")
+    p:close()
+    return out or ""
+end
+
+server:tool("apropos",
+    "Search shared fleet memory (stash) for facts about the fleet, projects, decisions, and preferences. query = 2-6 words on the topic; limit = max results (default 3). Read-only.",
+    { type = "object", properties = {
+        query = { type = "string",  description = "2-6 words describing what to recall" },
+        limit = { type = "integer", description = "max results, default 3" },
+    }, required = { "query" } },
+    function(a)
+        local q = tostring(a.query or ""):gsub("[^%w%s%-%.]", " "):gsub("%s+", " ")
+        if q:gsub("%s", "") == "" then return "Error: query required" end
+        local lim = tonumber(a.limit) or 3
+        return run_local("python3 /opt/lmcp/helpers/stash_recall.py '" .. q .. "' " .. lim, 30)
+    end,
+    { annotations = {
+        title           = "Apropos (fleet memory)",
+        readOnlyHint    = true,
+        destructiveHint = false,
+        idempotentHint  = true,
+        openWorldHint   = true,
+    } }
+)
+
+server:tool("wake_fleet",
+    "Wake a fleet NUC (pve1..pve4) via Fritz!Box Wake-on-LAN. Powers a node ON only; it cannot power anything off. Node boots in ~30-60s.",
+    { type = "object", properties = {
+        node = { type = "string", description = "Node to wake: '1'..'4' or 'pve1'..'pve4'" },
+    }, required = { "node" } },
+    function(a)
+        local node = tostring(a.node or ""):gsub("[^%w]", "")
+        if not node:match("^p?v?e?[1-4]$") then
+            return "Error: node must be 1-4 or pve1-pve4 (got: " .. tostring(a.node) .. ")"
+        end
+        return run_local("sudo /root/.local/bin/wake-pve " .. node, 15)
+    end,
+    { annotations = {
+        title           = "Wake fleet NUC",
+        readOnlyHint    = false,
+        destructiveHint = false,
+        idempotentHint  = true,
+        openWorldHint   = true,
+    } }
+)
+
 io.stderr:write(string.format("lmcp-hub starting on port %d with %d backends from %s\n",
     server.port, (function() local n = 0; for _ in pairs(backends) do n = n + 1 end; return n end)(), CONF_PATH))
 server:run()

lmcp.lua

@@ -7,6 +7,22 @@ local json = require('json')
 local lmcp = {}
 lmcp.__index = lmcp
 
+-- Module-level coroutine→ctx registry (issue #11). Weak keys so
+-- coroutines that die without explicit cleanup get GC'd out.
+-- Each ctx table carries a `server` back-reference, so any code with
+-- a coroutine handle can find both ctx and its owning lmcp instance.
+local _ctx_by_co = setmetatable({}, { __mode = "k" })
+
+-- server.lua and any other library code can call lmcp.current_ctx() to
+-- access the ctx of the currently-running dispatch coroutine. Returns
+-- nil outside coroutine context. Used by server.lua:run() to do
+-- transparent auto-cancellation of long-running shell-out polls.
+function lmcp.current_ctx()
+    local co = coroutine.running()
+    if co == nil then return nil end
+    return _ctx_by_co[co]
+end
+
 -- Read auth token from config file if present
 local function read_conf(path)
     local conf = {}
@@ -69,6 +85,16 @@ function lmcp.new(name, opts)
     -- server calls `:roots(session_id, ...)`; invalidated when the client
     -- sends notifications/roots/list_changed.
     self._roots_cache = {}
+    -- Pending handler coroutines (issue #20 — concurrent dispatch).
+    -- Each entry: { co, conn, wake_at, finalise }. The scheduler tick
+    -- resumes any whose wake_at has passed and runs `finalise` on the
+    -- coroutine's return value to build the deferred response.
+    self._pending_handlers = {}
+    -- Cancellation flags (issue #11). Keyed by stringified JSON-RPC
+    -- request id. Only ever holds in-flight ids — see the
+    -- notifications/cancelled handler in handle_request which checks
+    -- for in-flight before inserting. Cleared by _finalise_dispatch.
+    self._cancelled_ids = {}
     -- Notification queue: drained by Streamable HTTP transport (issue #16).
     -- Today delivery is a no-op; we still enqueue so the emission code
     -- path is exercised. Capped + deduped to keep the queue useful.
@@ -137,10 +163,29 @@ end
 --     structuredContent (issue #13; spec-strict clients get first-class
 --     structured access)
 function lmcp:tool(name, description, params_schema, handler, opts)
+    -- Normalise empty inputSchema.properties → nil. JSON Schema allows
+    -- omitting `properties` on a `type: "object"` schema (means "any
+    -- object, no constraints"). Without this, an empty Lua properties
+    -- table goes through json.lua's is_array → emitted as `[]` →
+    -- spec-strict clients (Zod et al.) reject with
+    -- `expected: record, received: array`. The same gotcha already
+    -- bit `ping` in v1.0.0-rc1 (project_json_empty_table_gotcha
+    -- memory). v1.1.1 fix.
+    local schema = params_schema or { type = "object" }
+    if type(schema.properties) == "table" and next(schema.properties) == nil then
+        -- Clone the schema and drop the empty `properties` key. Avoids
+        -- mutating the caller's table (in case they re-use it across
+        -- registrations).
+        local clean = {}
+        for k, v in pairs(schema) do
+            if k ~= "properties" then clean[k] = v end
+        end
+        schema = clean
+    end
     self.tools[name] = {
         name = name,
         description = description,
-        inputSchema = params_schema or { type = "object", properties = {} },
+        inputSchema = schema,
         handler = handler,
         annotations  = opts and opts.annotations  or nil,
         outputSchema = opts and opts.outputSchema or nil,
@@ -413,9 +458,28 @@ function lmcp:handle_request(req)
         if method == "notifications/roots/list_changed" then
             -- Invalidate cached roots for the session that sent this.
             if req._session_id then self._roots_cache[req._session_id] = nil end
+        elseif method == "notifications/cancelled" then
+            -- Issue #11 — flip cancel flag for the named request id,
+            -- but ONLY if the request is actually in-flight. Cancels
+            -- for unknown/already-completed ids drop silently (per Phase
+            -- 5 review fix #2 — prevents unbounded map growth).
+            local rid = (req.params or {}).requestId
+            if rid ~= nil then
+                local rid_str = tostring(rid)
+                local in_flight = false
+                -- Scan _ctx_by_co for a matching live request.
+                for _, c in pairs(_ctx_by_co) do
+                    if c.request_id ~= nil
+                       and tostring(c.request_id) == rid_str then
+                        in_flight = true; break
+                    end
+                end
+                if in_flight then
+                    self._cancelled_ids[rid_str] = true
+                end
+            end
         end
-        -- (Other client→server notifications: cancelled, message — no
-        -- action today; add side-effects here as needed.)
+        -- (Other client→server notifications drop silently.)
         return nil
     end
 
@@ -484,15 +548,59 @@ function lmcp:handle_request(req)
         if not tool then
             return jsonrpc_error(id, -32601, "Tool not found: " .. tostring(tool_name))
         end
-        -- ctx exposes the request's _meta (issue #13) and the session_id
-        -- (issue #9 — so handlers can call self:sample(ctx.session_id, …)).
-        -- Handlers that don't declare a second parameter ignore it (Lua
-        -- call discards extras).
-        local ctx = {
+        -- ctx exposes the request's _meta (issue #13), the session_id
+        -- (issue #9 — handlers can call self:sample(ctx.session_id, …)),
+        -- progress() and cancelled() (issue #11), and a `server` back-ref
+        -- (so lmcp.current_ctx() can find the right server instance
+        -- without a singleton). Handlers that don't declare a second
+        -- parameter ignore it (Lua call discards extras).
+        local rid_str = tostring(id)
+        local ptoken = (params._meta or {}).progressToken  -- nil if absent
+        local ctx
+        ctx = {
             _meta = params._meta,
             request_id = id,
             session_id = req._session_id,
+            server = self,
+            -- progress(p, total?, message?): emits notifications/progress
+            -- on session's notify_q. No-op if client didn't supply a
+            -- progressToken. Type-checks; rejects non-numeric progress.
+            progress = function(p, total, message)
+                if ptoken == nil then return false end
+                if type(p) ~= "number" then return false end
+                if total ~= nil and type(total) ~= "number" then return false end
+                local sess = self._sessions[req._session_id]
+                if not sess then return false end
+                local np = { progressToken = ptoken, progress = p }
+                if total   ~= nil then np.total   = total end
+                if message ~= nil then np.message = tostring(message) end
+                sess.notify_q[#sess.notify_q + 1] = {
+                    jsonrpc = JSONRPC, method = "notifications/progress",
+                    params = np,
+                }
+                return true
+            end,
+            -- cancelled(): true if a notifications/cancelled for this
+            -- request id has been received.
+            cancelled = function()
+                return self._cancelled_ids[rid_str] == true
+            end,
         }
+
+        -- Register on the currently-running coroutine so lmcp.current_ctx()
+        -- (and thus server.lua:run()'s auto-cancel) can find this ctx.
+        -- Pure-Lua handlers also get this registration; harmless.
+        local co = coroutine.running()
+        if co ~= nil then _ctx_by_co[co] = ctx end
+
+        -- Pre-handler cancellation short-circuit (Phase 5 review fix #9).
+        -- If a notifications/cancelled landed for this id before dispatch
+        -- reached here, skip the handler entirely. _finalise_dispatch
+        -- will see `not result` and suppress the response.
+        if self._cancelled_ids[rid_str] then
+            return nil
+        end
+
         local ok, result = pcall(tool.handler, arguments, ctx)
         if ok then
             local resp = { isError = false }
@@ -831,7 +939,7 @@ local function _check_auth(self, conn)
     if not self._auth_token then return true end
     if conn.method == "OPTIONS" then return true end
     local auth = conn.headers["authorization"] or ""
-    local token = auth:match("^Bearer%s+(.+)$")
+    local token = auth:match("^[Bb]earer%s+(.+)$")
     return token == self._auth_token
 end
 
@@ -887,6 +995,10 @@ end
 
 -- ---- Dispatch a fully-parsed POST body ----
 
+-- Forward declarations: used by _dispatch_post, defined below.
+local _drive_handler_co
+local _finalise_dispatch
+
 local function _dispatch_post(self, conn)
     local body = conn.body
     if body == "" then
@@ -942,28 +1054,112 @@ local function _dispatch_post(self, conn)
     -- expose it to handler ctx (issue #9 — sampling needs to know which
     -- session to push the request onto).
     rpc_req._session_id = sess.id
+    -- Stash the JSON-RPC id on the conn so _finalise_dispatch can clear
+    -- the cancellation flag for this request after building the response
+    -- (issue #11). Notifications have nil id; that's fine — the
+    -- nil-guard in _finalise_dispatch keeps tostring(nil) out of the
+    -- cancel map.
+    conn.dispatch_id = rpc_req.id
 
-    -- Normal client request / notification. Dispatch via handle_request.
-    local response = self:handle_request(rpc_req)
-    if not response then
+    -- Concurrent handler dispatch (issue #20). Wrap the dispatch call in
+    -- a coroutine so any tool handler that goes through server.lua:run()
+    -- (which yields when polling its sentinel file) can return control to
+    -- the event loop while it waits. Other connections continue making
+    -- progress.
+    --
+    -- The coroutine resumes itself synchronously the first time. If it
+    -- completes without yielding (pure-Lua handlers, ping, etc.) the
+    -- response is built inline as before. If it yields, we park it in
+    -- self._pending_handlers and return nil — the conn enters
+    -- dispatching_async, the scheduler tick resumes when wake_at passes.
+    local co = coroutine.create(function()
+        return self:handle_request(rpc_req)
+    end)
+    return _drive_handler_co(self, conn, co)
+end
+
+-- Resume a handler coroutine until it completes or yields. On completion,
+-- build the deferred HTTP response (preserving the Accept-aware shape).
+-- On yield, register in self._pending_handlers and return nil — the conn
+-- is parked in dispatching_async until the scheduler resumes it.
+_drive_handler_co = function(self, conn, co)
+    local rok, ryield = coroutine.resume(co)
+    if coroutine.status(co) == "dead" then
+        return _finalise_dispatch(self, conn, rok, ryield, co)
+    end
+    -- Suspended. Parse the yield payload.
+    local wake_at = (type(ryield) == "table" and ryield.wake_at) or 0
+    self._pending_handlers[#self._pending_handlers + 1] = {
+        co = co, conn = conn, wake_at = wake_at,
+    }
+    conn.state = "dispatching_async"
+    return nil  -- no write_buf change; conn parks
+end
+
+-- Build the HTTP response for a completed dispatch. `rok` is the coroutine.resume
+-- success flag; `result` is the handler/dispatch return (a JSON-RPC string when
+-- rok=true; an error message when rok=false). Used by both the sync path
+-- (_dispatch_post tail) and the async resume path (_scheduler_tick).
+-- Also: clears cancellation flag and ctx-by-co registry entry for this
+-- request (issue #11 — single cleanup site per Phase 5 review fix #7).
+_finalise_dispatch = function(self, conn, rok, result, co)
+    local session_id = conn.session_id
+
+    -- Cleanup (always): drop the coroutine's ctx entry and any
+    -- cancellation flag for this request id.
+    if co ~= nil then _ctx_by_co[co] = nil end
+    local rid = conn.dispatch_id
+    local was_cancelled = false
+    if rid ~= nil then
+        local rid_str = tostring(rid)
+        if self._cancelled_ids[rid_str] then
+            was_cancelled = true
+            self._cancelled_ids[rid_str] = nil
+        end
+    end
+    -- Issue #11: cancelled requests get a -32800 JSON-RPC error response.
+    -- The MCP spec wording is "SHOULD NOT respond" (not MUST NOT). A silent
+    -- TCP-close would be cleaner but the spawned shell subprocess in
+    -- server.lua:run() inherits the socket FD via fork(), so the kernel
+    -- keeps the connection alive until that shell exits (i.e. the
+    -- underlying long-running command completes anyway). The error
+    -- response gives the client a structured signal and exits curl
+    -- immediately, which is the practical UX they want. JSON-RPC 2.0
+    -- code -32800 is the convention for "Request cancelled."
+    if was_cancelled then
+        return _build_http_response("200 OK",
+            { ["Content-Type"] = "application/json",
+              ["Access-Control-Allow-Origin"] = "*" },
+            jsonrpc_error(rid, -32800, "Request cancelled"),
+            session_id)
+    end
+
+    if not rok then
+        -- Internal dispatch error — surface as a JSON-RPC error response.
+        return _build_http_response("500 Internal Server Error",
+            { ["Content-Type"] = "application/json",
+              ["Access-Control-Allow-Origin"] = "*" },
+            jsonrpc_error(nil, -32603, "Internal error: " .. tostring(result)),
+            session_id)
+    end
+    if not result then
         -- Notification → 202 Accepted, no body.
         return _build_http_response("202 Accepted",
             { ["Content-Type"] = "application/json",
               ["Access-Control-Allow-Origin"] = "*" },
-            "", conn.session_id)
+            "", session_id)
     end
-
-    -- If client accepts SSE, respond as a single-event SSE stream.
-    -- Otherwise plain JSON body.
+    -- Accept-aware response shape (re-checked at finalise time; survives
+    -- parking because conn.headers is captured by the closure scope).
     local accept = conn.headers["accept"] or ""
     if accept:find("text/event%-stream") then
-        local hdrs = _build_sse_headers(conn.session_id)
-        return hdrs .. _sse_event(response)
+        local hdrs = _build_sse_headers(session_id)
+        return hdrs .. _sse_event(result)
     end
     return _build_http_response("200 OK",
         { ["Content-Type"] = "application/json",
           ["Access-Control-Allow-Origin"] = "*" },
-        response, conn.session_id)
+        result, session_id)
 end
 
 local function _dispatch_options(conn)
@@ -1119,8 +1315,19 @@ local function _conn_read(self, conn)
             conn.state = "sse_open"
             conn.last_heart = os.time()
         elseif conn.method == "POST" then
-            conn.write_buf = _dispatch_post(self, conn)
-            conn.state = "writing"
+            -- _dispatch_post may return nil (issue #20) if the handler
+            -- coroutine yielded. In that case it set conn.state =
+            -- "dispatching_async" itself and parked the coroutine.
+            local resp = _dispatch_post(self, conn)
+            if resp then
+                conn.write_buf = resp
+                -- _finalise_dispatch sets conn.state = "closing" for
+                -- cancelled requests (issue #11); only override if not.
+                if conn.state ~= "closing" then
+                    conn.state = "writing"
+                end
+            end
+            -- else: conn already parked; scheduler tick will finalise.
         else
             conn.write_buf = _build_http_response("405 Method Not Allowed",
                 { ["Content-Type"] = "text/plain",
@@ -1195,6 +1402,73 @@ local function _heartbeat_tick(self)
     end
 end
 
+-- Issue #20 — scheduler tick. Resume any parked dispatch coroutine whose
+-- wake_at has passed. On completion, build the deferred response and
+-- queue it for write. If the connection died while the handler was
+-- parked, drop the coroutine.
+--
+-- gettime() is wall-clock (luasocket uses gettimeofday) — NOT monotonic.
+-- A large NTP step backwards could delay resumes; forwards could bunch
+-- them. Acceptable for the deployment fleet (chrony slews); revisit if
+-- a use case appears that needs CLOCK_MONOTONIC.
+local function _scheduler_tick(self)
+    if not self._pending_handlers[1] then return end
+    local socket = require("socket")
+    local now = socket.gettime()
+    local i = 1
+    while i <= #self._pending_handlers do
+        local p = self._pending_handlers[i]
+        if p.conn.state == "closing" then
+            -- Connection died mid-handler; drop the coroutine entirely
+            -- and free its ctx entry (issue #11 cleanup discipline).
+            _ctx_by_co[p.co] = nil
+            if p.conn.dispatch_id ~= nil then
+                self._cancelled_ids[tostring(p.conn.dispatch_id)] = nil
+            end
+            table.remove(self._pending_handlers, i)
+        elseif now >= p.wake_at then
+            -- Time to resume. Remove from pending BEFORE resume so a
+            -- re-yielding handler re-adds itself cleanly via _drive_handler_co.
+            table.remove(self._pending_handlers, i)
+            local rok, ryield = coroutine.resume(p.co)
+            if coroutine.status(p.co) == "dead" then
+                local resp = _finalise_dispatch(self, p.conn, rok, ryield, p.co)
+                p.conn.write_buf = (p.conn.write_buf or "") .. resp
+                -- _finalise_dispatch may set conn.state = "closing" for
+                -- cancelled requests; only transition to writing if it
+                -- didn't already pick the closing path.
+                if p.conn.state ~= "closing" then
+                    p.conn.state = "writing"
+                end
+            else
+                -- Yielded again — re-park.
+                local wake_at = (type(ryield) == "table" and ryield.wake_at) or 0
+                self._pending_handlers[#self._pending_handlers + 1] = {
+                    co = p.co, conn = p.conn, wake_at = wake_at,
+                }
+            end
+        else
+            i = i + 1
+        end
+    end
+end
+
+-- Returns the earliest pending wake_at as an offset from now, or nil if
+-- no handlers are parked. Used to tighten the select() timeout so the
+-- scheduler wakes on the right beat.
+local function _next_pending_delay(self)
+    if not self._pending_handlers[1] then return nil end
+    local socket = require("socket")
+    local now = socket.gettime()
+    local earliest = math.huge
+    for _, p in ipairs(self._pending_handlers) do
+        if p.wake_at < earliest then earliest = p.wake_at end
+    end
+    local d = earliest - now
+    if d < 0 then return 0 end
+    return d
+end
+
 -- ---- Public: server-initiated request (for sampling/roots/etc.) ----
 -- Enqueues a JSON-RPC request on the session's SSE stream. The callback
 -- fires when the client POSTs back the response (matched by id).
@@ -1322,7 +1596,14 @@ function lmcp:run()
             end
         end
 
-        local ready_r, ready_w = socket.select(reads, writes, SELECT_TIMEOUT)
+        -- Tighten select timeout if a parked handler is due sooner.
+        -- Otherwise a 100ms tick adds 100ms latency to short shell-tool runs.
+        local select_timeout = SELECT_TIMEOUT
+        local next_pend = _next_pending_delay(self)
+        if next_pend and next_pend < select_timeout then
+            select_timeout = next_pend
+        end
+        local ready_r, ready_w = socket.select(reads, writes, select_timeout)
 
         for _, sock in ipairs(ready_r or {}) do
             if sock == server_sock then
@@ -1365,9 +1646,11 @@ function lmcp:run()
         -- Per-tick maintenance.
         _drain_notifications(self)
         _heartbeat_tick(self)
+        _scheduler_tick(self)  -- issue #20: resume due dispatch coroutines
 
         -- After draining, attempt immediate writes on conns whose write_buf
-        -- just got bytes (so list_changed / heartbeat appears within one tick).
+        -- just got bytes (so list_changed / heartbeat / async-completed
+        -- responses appear within one tick).
         for sock, conn in pairs(self._conns) do
             if conn.write_buf ~= "" and conn.state ~= "closing" then
                 pcall(_conn_write, conn)

server.lua

@@ -35,7 +35,51 @@ local function tmpname()
     end
 end
 
+-- Lazy-required luasocket — only needed in the coroutine path for
+-- gettime(). Avoids forcing luasocket as a hard dep at server.lua
+-- load time (callers like example_server already require it via lmcp).
+local _socket = nil
+local function gettime()
+    if not _socket then _socket = require("socket") end
+    return _socket.gettime()
+end
+
+-- Lazy access to the lmcp module for cross-module ctx lookup (issue #11).
+-- server.lua doesn't statically require lmcp (it's an example/runtime
+-- server, not the library); but lmcp must already be loaded when we run.
+-- Defensive: if the lookup fails for any reason, current_ctx returns nil
+-- and run() falls back to non-cancellable behaviour.
+local _lmcp_mod = nil
+local function current_ctx()
+    if _lmcp_mod == false then return nil end
+    if _lmcp_mod == nil then
+        local ok, mod = pcall(require, "lmcp")
+        _lmcp_mod = ok and mod or false
+        if _lmcp_mod == false then return nil end
+    end
+    return _lmcp_mod.current_ctx and _lmcp_mod.current_ctx() or nil
+end
+
+-- in_coroutine() — true if we're running inside an lmcp dispatch
+-- coroutine (issue #20). Handles both Lua 5.4 (coroutine.running →
+-- (co, isMain)) and LuaJIT 5.1 (coroutine.running → nil on main).
+local function in_coroutine()
+    local co, is_main = coroutine.running()
+    if co == nil then return false end       -- 5.1 / LuaJIT main
+    if is_main then return false end          -- 5.4 main thread
+    return true
+end
+
 local function sleep_ms(ms)
+    -- Coroutine-aware: yield with a wake deadline instead of busy-blocking.
+    -- The lmcp event loop services I/O for other connections while this
+    -- coroutine sleeps, then resumes it once the deadline elapses.
+    -- (Issue #20: gives concurrent tool dispatch without changing handler
+    -- source code — tools that go through run() get it for free.)
+    if in_coroutine() then
+        coroutine.yield({ wake_at = gettime() + (ms / 1000) })
+        return
+    end
     if WINDOWS then
         -- ping loopback: ~1s per -n count. For sub-second, use busy-wait.
         if ms < 500 then
@@ -78,6 +122,35 @@ local function run(cmd, timeout_sec)
     local out_file = base .. ".out"
     local done_file = base .. ".done"
 
+    -- Wall-clock deadline rather than an accumulated interval-counter:
+    -- when we're inside a dispatch coroutine (issue #20), the scheduler
+    -- may delay our resume by more than `interval`, so an accumulator
+    -- diverges from real elapsed. gettime() comparison stays honest in
+    -- both busy-poll and yield-resume modes.
+    --
+    -- Auto-cancellation (issue #11): if a ctx is available on the
+    -- running coroutine AND it has been cancelled, exit the polling
+    -- loop early. The interval is capped at 500ms when a ctx is
+    -- present so worst-case cancel latency is ~0.5s, not ~2s.
+    local started = gettime()
+    local cancelled = false
+    local function poll_loop()
+        local interval = WINDOWS and 100 or 50  -- ms
+        while gettime() - started < timeout_sec do
+            if file_exists(done_file) then return true end
+            local ctx = current_ctx()
+            if ctx and ctx.cancelled and ctx.cancelled() then
+                cancelled = true
+                return false
+            end
+            sleep_ms(interval)
+            if interval < 2000 then interval = math.floor(interval * 1.5) end
+            -- When cancellable, cap so we can respond to cancel quickly.
+            if ctx and interval > 500 then interval = 500 end
+        end
+        return false
+    end
+
     if WINDOWS then
         -- Write a batch wrapper that runs the command and signals completion
         local bat_file = base .. ".bat"
@@ -89,49 +162,51 @@ local function run(cmd, timeout_sec)
         bf:close()
         os.execute('start /B cmd /C "' .. bat_file .. '"')
 
-        -- Poll for sentinel
-        local elapsed = 0
-        local interval = 100  -- ms
-        while elapsed < timeout_sec * 1000 do
-            if file_exists(done_file) then break end
-            sleep_ms(interval)
-            elapsed = elapsed + interval
-            if interval < 2000 then interval = math.floor(interval * 1.5) end
-        end
-
+        local completed = poll_loop()
         local output = read_file(out_file)
         remove_silent(bat_file)
         remove_silent(out_file)
         remove_silent(done_file)
 
-        if elapsed >= timeout_sec * 1000 then
+        if not completed then
+            if cancelled then return "(cancelled)" end
             return output or ("Error: command timed out after " .. timeout_sec .. "s")
         end
         return output and output ~= "" and output or "(no output)"
     else
-        -- POSIX: use shell backgrounding + wait with timeout
-        -- sh -c '(cmd > out 2>&1; echo $? > done) &' then poll
+        -- POSIX: run in its OWN session/process group (setsid) so a
+        -- timeout or cancel can kill the WHOLE tree instead of orphaning
+        -- backgrounded children (the classic "shell timed out, children
+        -- kept thrashing" bug). $! is the setsid leader pid == pgid.
+        local pid_file = base .. ".pid"
         local sh_cmd = string.format(
             "(%s) > '%s' 2>&1; echo $? > '%s'",
             cmd, out_file, done_file
         )
-        os.execute("sh -c '" .. sh_cmd:gsub("'", "'\\''") .. "' &")
+        os.execute("setsid sh -c '" .. sh_cmd:gsub("'", "'\\''")
+            .. "' & echo $! > '" .. pid_file .. "'")
+        local pgid = (read_file(pid_file) or ""):match("(%d+)")
+        remove_silent(pid_file)
 
-        local elapsed = 0
-        local interval = 50  -- ms
-        while elapsed < timeout_sec * 1000 do
-            if file_exists(done_file) then break end
-            sleep_ms(interval)
-            elapsed = elapsed + interval
-            if interval < 2000 then interval = math.floor(interval * 1.5) end
+        local completed = poll_loop()
+
+        -- Timeout or cancel -> kill the entire process group. No orphans.
+        if not completed and pgid then
+            os.execute("kill -TERM -" .. pgid .. " 2>/dev/null")
+            sleep_ms(300)
+            os.execute("kill -KILL -" .. pgid .. " 2>/dev/null")
         end
 
         local output = read_file(out_file)
         remove_silent(out_file)
         remove_silent(done_file)
 
-        if elapsed >= timeout_sec * 1000 then
-            return output or ("Error: command timed out after " .. timeout_sec .. "s")
+        if not completed then
+            if cancelled then return "(cancelled -- process group killed)" end
+            return (output and output ~= "" and (output .. "\n") or "")
+                .. "Error: command timed out after " .. timeout_sec
+                .. "s -- the process group was KILLED (nothing is still running). "
+                .. "For a long-running command, re-run it with shell_bg."
         end
         return output and output ~= "" and output or "(no output)"
     end
@@ -142,6 +217,13 @@ end
 local server_name = os.getenv("LMCP_NAME") or (WINDOWS and "windows-tools" or "linux-tools")
 local server = lmcp.new(server_name, {
     port = tonumber(os.getenv("LMCP_PORT") or arg[1]) or 8080,
+    -- LMCP_HOST: bind interface (default 0.0.0.0). Hosts that need
+    -- single-interface binding (hertz: 192.168.88.18 only) set this.
+    host = os.getenv("LMCP_HOST"),
+    -- LMCP_CONF: path to a conf file with bearer-token entries
+    -- (e.g. /opt/herding/etc/hertz-tools.conf). Read by lmcp.lua's
+    -- read_conf; the `.godparticle` entry becomes the bearer token.
+    conf = os.getenv("LMCP_CONF"),
 })
 
 -- ---- Tools ----
@@ -218,7 +300,15 @@ server:tool("shell_bg",
             f:close()
             os.remove(pid_file)
         end
-        return string.format("launched pid=%s log=%s", pid, log)
+        -- register so list_jobs/kill_job can see and reap it (no more reboots)
+        if pid ~= "?" then
+            local reg = io.open("/tmp/lmcp-bg-jobs.tsv", "a")
+            if reg then
+                reg:write(pid.."\t"..log.."\t"..os.date("%Y-%m-%dT%H:%M:%S").."\t"..inner:gsub("[\t\n]"," ").."\n")
+                reg:close()
+            end
+        end
+        return string.format("launched pid=%s log=%s (kill with kill_job pid=%s)", pid, log, pid)
     end, {
         annotations = {
             title           = "Run shell (background)",
@@ -229,6 +319,42 @@ server:tool("shell_bg",
         },
     })
 
+server:tool("kill_job",
+    "Kill a runaway background job by PID. SIGKILLs the whole process group of a shell_bg/setsid job so no children survive. Use when a background job is thrashing a machine.",
+    { type = "object", properties = { pid = { type = "integer", description = "PID from shell_bg / list_jobs" } }, required = { "pid" } },
+    function(a)
+        if WINDOWS then return "Error: kill_job is Linux-only" end
+        local pid = tostring(a.pid or ""):match("(%d+)")
+        if not pid then return "Error: numeric pid required" end
+        os.execute("kill -KILL -"..pid.." 2>/dev/null; kill -KILL "..pid.." 2>/dev/null")
+        sleep_ms(200)
+        local alive = os.execute("kill -0 "..pid.." 2>/dev/null")
+        if alive == true or alive == 0 then return "pid "..pid.." may still be alive (uninterruptible?)" end
+        return "killed pid "..pid.." (process group)"
+    end,
+    { annotations = { title = "Kill background job", destructiveHint = true } })
+
+server:tool("list_jobs",
+    "List background jobs started via shell_bg and whether each is still running. Use to find runaway jobs to kill_job.",
+    { type = "object", properties = {} },
+    function()
+        if WINDOWS then return "Error: list_jobs is Linux-only" end
+        local reg = io.open("/tmp/lmcp-bg-jobs.tsv", "r")
+        if not reg then return "(no background jobs recorded)" end
+        local out = {}
+        for line in reg:lines() do
+            local pid, log, ts, cmd = line:match("^(%d+)\t([^\t]*)\t([^\t]*)\t(.*)$")
+            if pid then
+                local alive = os.execute("kill -0 "..pid.." 2>/dev/null")
+                local st = (alive == true or alive == 0) and "RUNNING" or "done"
+                table.insert(out, string.format("pid=%s [%s] %s log=%s\n    %s", pid, st, ts, log, (cmd or ""):sub(1,100)))
+            end
+        end
+        reg:close()
+        return #out>0 and table.concat(out, "\n") or "(no background jobs recorded)"
+    end,
+    { annotations = { title = "List background jobs", readOnlyHint = true } })
+
 server:tool("read_file", "Read a file.", {
     type = "object",
     properties = { path = { type = "string" } },
@@ -1008,6 +1134,46 @@ if WINDOWS then
     })
 end
 
+-- ---- host-local tool plugins (issue #22) ----
+-- Load every .lua file in LMCP_TOOLS_DIR (default /opt/lmcp/tools.d on POSIX,
+-- %ProgramData%\lmcp\tools.d on Windows). Each file is invoked as a function
+-- receiving the configured `server` instance and the `run` helper:
+--
+--     local server, run = ...
+--     server:tool("my_local_tool", "...", {...}, function(a) return run(...) end)
+--
+-- This is the standard plugin pattern (nginx conf.d/, systemd-tmpfiles.d, …).
+-- Hosts can ship their own tools alongside the packaged generics without
+-- forking the upstream server.lua.
+local plugin_dir = os.getenv("LMCP_TOOLS_DIR")
+    or (WINDOWS and (os.getenv("ProgramData") or "C:\\ProgramData") .. "\\lmcp\\tools.d"
+                 or "/opt/lmcp/tools.d")
+local list_cmd = WINDOWS
+    and ('dir /b "' .. plugin_dir .. '\\*.lua" 2>nul')
+    or  ('ls -1 "'  .. plugin_dir ..  '"/*.lua 2>/dev/null')
+local lh = io.popen(list_cmd)
+if lh then
+    for path in lh:lines() do
+        -- On Windows `dir /b` emits bare filenames; prefix the dir.
+        local full = path:match("[/\\]") and path
+                  or (plugin_dir .. (WINDOWS and "\\" or "/") .. path)
+        local chunk, err = loadfile(full)
+        if chunk then
+            local ok, perr = pcall(chunk, server, run)
+            if ok then
+                io.stderr:write("lmcp: loaded plugin " .. full .. "\n")
+            else
+                io.stderr:write("lmcp: plugin " .. full .. " errored: "
+                    .. tostring(perr) .. "\n")
+            end
+        else
+            io.stderr:write("lmcp: plugin " .. full .. " load error: "
+                .. tostring(err) .. "\n")
+        end
+    end
+    lh:close()
+end
+
 local transport = os.getenv("LMCP_TRANSPORT") or "http"
 if transport == "stdio" then
     if os.getenv("LMCP_PORT") then

tools.d/boltzmann.lua

@@ -0,0 +1,30 @@
+-- boltzmann-tools plugin: `stash` — fleet persistent-memory CLI wrapper.
+-- Receives (server, run). Runs the stash CLI inside the memory Incus container's
+-- stash-stash-1 docker container (which has NO shell — /stash is invoked directly
+-- as argv; docker exec handles that, no `sh -c` inside the container).
+local server, run = ...
+
+server:tool("stash",
+    "Fleet persistent memory (stash knowledge graph on the memory container). "
+    .. "`command` = a stash subcommand + its args as ONE string. "
+    .. "Examples: command:=\"recall escher plug AIN\"  |  command:=\"facts\"  |  "
+    .. "command:=\"remember 'the NAS is at 192.168.88.10'\"  |  command:=\"namespace list\". "
+    .. "Wrap multi-word text in single quotes. Read subcommands: recall, facts, namespace list, "
+    .. "goal list, context show. Write: remember, forget, consolidate run.",
+    { type = "object", properties = {
+        command = { type = "string",
+            description = "stash subcommand + args, e.g. \"recall <query>\" or \"remember '<text>'\"" },
+    }, required = { "command" } },
+    function(a)
+        local c = tostring(a.command or ""):gsub("^%s+", ""):gsub("%s+$", "")
+        if c == "" then return "Error: command required (e.g. command:=\"recall <query>\")" end
+        return run("incus exec memory -- docker exec stash-stash-1 /stash " .. c, 60)
+    end,
+    { annotations = {
+        title           = "Stash fleet memory",
+        readOnlyHint    = false,
+        destructiveHint = false,
+        idempotentHint  = false,
+        openWorldHint   = true,
+    } }
+)

tools.d/hertz.lua

@@ -0,0 +1,292 @@
+-- /opt/lmcp/tools.d/hertz.lua — hertz-specific tool registrations.
+--
+-- Invoked by the packaged server.lua's tools.d scan (lmcp ≥ v1.2.0, issue #22).
+-- Receives (server, run) — the configured lmcp instance and the
+-- coroutine-aware run() helper. We add hertz-only tools on top of the
+-- packaged generics (shell, read_file, write_file, edit_file, list_dir,
+-- search_files, fetch, web_search, shell_bg).
+--
+-- Previously these all lived in /opt/lmcp/server.lua (a copy-paste fork of
+-- the packaged server.lua). That pattern drifted on every release; now the
+-- packaged file stays canonical and only the genuine hertz-specifics live
+-- here.
+
+local server, run = ...
+
+-- Local helpers — single-host scoped, not worth lifting into the packaged lib.
+local function read_file_raw(path)
+    local f = io.open(path, 'r')
+    if not f then return nil end
+    local c = f:read('*a'); f:close(); return c
+end
+
+local function farad(cmd, timeout)
+    return run("incus exec farad -- sh -c " .. string.format("%q", cmd),
+        timeout or 15)
+end
+
+-- ---- LXD tools ----
+
+server:tool("incus_exec", "Execute a command inside an Incus container on hertz.", {
+    type = "object",
+    properties = {
+        container = { type = "string", description = "Container name" },
+        command   = { type = "string", description = "Command to execute" },
+        timeout   = { type = "integer", default = 30 },
+    },
+    required = { "container", "command" },
+}, function(a)
+    return run(string.format("incus exec %s -- sh -c %q",
+        a.container:gsub("[^%w%-]", ""), a.command), a.timeout or 30)
+end)
+
+server:tool("incus_list", "List all Incus containers on hertz.",
+    { type = "object" },
+    function() return run("incus list -c ns4 -f csv", 10) end)
+
+-- ---- Fritz!Box tools ----
+
+server:tool("fritz", "Execute Fritz!Box TR-064 command (info, hosts, wan, "
+    .. "wol <mac>, reconnect, reboot, reboot-repeater <ip>, routes, route-add, "
+    .. "route-del, services, actions, call).",
+    {
+        type = "object",
+        properties = {
+            command = { type = "string", description = "fritz subcommand and args" },
+        },
+        required = { "command" },
+    },
+    function(a) return run("sudo /root/.local/bin/fritz " .. a.command, 15) end)
+
+-- ---- Network tools ----
+
+server:tool("ping_host", "Check if a host is reachable (1 ICMP ping, 2s timeout).", {
+    type = "object",
+    properties = { host = { type = "string" } },
+    required = { "host" },
+}, function(a)
+    local host = a.host:gsub("[^%w%.%-:]", "")
+    return run("ping -c1 -W2 " .. host, 5)
+end)
+
+server:tool("network_status",
+    "Check reachability of all infrastructure hosts and MCP endpoints.",
+    { type = "object" },
+    function()
+        local script = [[
+hosts="hertz:localhost boltzmann:boltzmann tesla:tesla data:192.168.88.30 broglie:192.168.88.160 higgs:10.170.16.10"
+for entry in $hosts; do
+    name="${entry%%:*}"
+    ip="${entry#*:}"
+    if ping -c1 -W2 "$ip" >/dev/null 2>&1; then
+        status="UP"
+        if [ "$name" != "data" ]; then
+            if timeout 3 bash -c "echo >/dev/tcp/${ip}/8080" 2>/dev/null; then
+                status="UP (MCP ok)"
+            else
+                status="UP (no MCP)"
+            fi
+        fi
+    else
+        status="DOWN"
+    fi
+    printf "%-12s %-20s %s\n" "$name" "$ip" "$status"
+done
+]]
+        return run(script, 30)
+    end)
+
+server:tool("wol_and_wait",
+    "Wake the data server via Fritz!Box WoL and wait until it (or broglie MCP) is reachable.",
+    {
+        type = "object",
+        properties = {
+            mac          = { type = "string",  default = "", description = "MAC address (auto-detected if empty)" },
+            wait_for_mcp = { type = "boolean", default = true, description = "Wait for broglie MCP instead of just ping" },
+            timeout      = { type = "integer", default = 120 },
+        },
+    },
+    function(a)
+        local mac = a.mac
+        if not mac or mac == "" then
+            local hosts_out = run("sudo /root/.local/bin/fritz hosts 2>/dev/null | grep -i 'data\\|192.168.88.30'", 10)
+            mac = hosts_out and hosts_out:match("(%x%x:%x%x:%x%x:%x%x:%x%x:%x%x)") or ""
+            if mac == "" then return "Error: could not detect MAC for data. Provide it manually." end
+        end
+        run("sudo /root/.local/bin/fritz wol " .. mac:gsub("[^%x:]", ""), 10)
+
+        local timeout = a.timeout or 120
+        local check
+        if a.wait_for_mcp == false then
+            check = "ping -c1 -W2 192.168.88.30"
+        else
+            check = "timeout 3 bash -c 'echo >/dev/tcp/192.168.88.160/8080'"
+        end
+        local target = (a.wait_for_mcp == false) and "data" or "broglie:8080"
+
+        local elapsed = 0
+        while elapsed < timeout do
+            os.execute("sleep 5")
+            elapsed = elapsed + 5
+            local rc = os.execute(check)
+            if rc == true or rc == 0 then
+                return string.format("WoL sent to %s. %s reachable after %ds.",
+                    mac, target, elapsed)
+            end
+        end
+        return string.format("WoL sent to %s but %s not reachable after %ds.",
+            mac, target, timeout)
+    end)
+
+-- ---- Proxmox fallback ----
+
+server:tool("pct_exec",
+    "Execute a command in a Proxmox CT on data (SSH fallback when broglie is down).",
+    {
+        type = "object",
+        properties = {
+            ctid    = { type = "string", description = "Container ID (e.g. 108, 165)" },
+            command = { type = "string" },
+            timeout = { type = "integer", default = 30 },
+        },
+        required = { "ctid", "command" },
+    },
+    function(a)
+        local ctid = a.ctid:gsub("[^%d]", "")
+        return run(string.format("ssh -o ConnectTimeout=5 root@data 'pct exec %s -- sh -c %q'",
+            ctid, a.command), a.timeout or 30)
+    end)
+
+-- ---- Home Assistant ----
+
+server:tool("ha_cli",
+    "Run Home Assistant CLI command inside farad (e.g. 'core restart', 'backups list', 'info').",
+    {
+        type = "object",
+        properties = {
+            command  = { type = "string", description = "ha subcommand, e.g. 'core restart', 'supervisor info', 'backups list'" },
+            raw_json = { type = "boolean", default = false, description = "Return raw JSON output" },
+        },
+        required = { "command" },
+    },
+    function(a)
+        local flags = a.raw_json and " --raw-json" or ""
+        return farad("ha " .. a.command .. flags)
+    end)
+
+server:tool("ha_api",
+    "Call Home Assistant Core REST API. Requires token in /opt/lmcp/ha_token on hertz.",
+    {
+        type = "object",
+        properties = {
+            method   = { type = "string", default = "GET" },
+            endpoint = { type = "string", description = "/api/states, /api/services/climate/set_temperature, etc." },
+            body     = { type = "string", description = "JSON body for POST" },
+        },
+        required = { "endpoint" },
+    },
+    function(a)
+        local token = read_file_raw("/opt/lmcp/ha_token")
+        if not token or token == "" then
+            return "Error: no HA token. Create a long-lived token in HA UI → Profile → "
+                .. "Long-Lived Access Tokens, then: echo '<token>' | sudo tee /opt/lmcp/ha_token"
+        end
+        token = token:gsub("%s+", "")
+        local method = (a.method or "GET"):upper()
+        local cmd = string.format(
+            "curl -sf -X %s -H 'Authorization: Bearer %s' -H 'Content-Type: application/json'",
+            method, token)
+        if a.body and a.body ~= "" then
+            cmd = cmd .. " -d " .. string.format("'%s'", a.body:gsub("'", "'\\''"))
+        end
+        cmd = cmd .. " http://localhost:8123" .. a.endpoint
+        return farad(cmd, 15)
+    end)
+
+-- ---- MQTT (Eurotronic thermostats + general) ----
+
+server:tool("mqtt_pub", "Publish an MQTT message (via Mosquitto in farad).", {
+    type = "object",
+    properties = {
+        topic   = { type = "string" },
+        message = { type = "string" },
+        retain  = { type = "boolean", default = false },
+    },
+    required = { "topic", "message" },
+}, function(a)
+    local retain = a.retain and "-r " or ""
+    return farad(string.format("mosquitto_pub %s-t '%s' -m '%s'",
+        retain, a.topic:gsub("'", "'\\''"), a.message:gsub("'", "'\\''")))
+end)
+
+server:tool("mqtt_sub",
+    "Subscribe to MQTT topics and collect messages (via Mosquitto in farad).",
+    {
+        type = "object",
+        properties = {
+            topic   = { type = "string",  description = "Topic pattern, e.g. 'eurotronic/#' or '#'" },
+            count   = { type = "integer", default = 10, description = "Number of messages to collect" },
+            timeout = { type = "integer", default = 5,  description = "Seconds to wait" },
+            verbose = { type = "boolean", default = true, description = "Show topics with messages" },
+        },
+        required = { "topic" },
+    },
+    function(a)
+        local v = a.verbose ~= false and "-v " or ""
+        return farad(string.format("mosquitto_sub %s-t '%s' -C %d -W %d",
+            v, a.topic:gsub("'", "'\\''"), a.count or 10, a.timeout or 5),
+            (a.timeout or 5) + 5)
+    end)
+
+-- ---- Mediagrab (kids show downloader) ----
+
+server:tool("mediagrab",
+    "Manage kids show downloads in doppler container. Commands: list, weekly, "
+    .. "archive, test <url>, add '<json>'",
+    {
+        type = "object",
+        properties = {
+            command = { type = "string", description = "Command: list, weekly, archive, 'test <url>', 'add <json>'" },
+        },
+        required = { "command" },
+    },
+    function(a)
+        return run("incus exec doppler -- python3 /opt/mediagrab/mediagrab.py "
+            .. a.command, 120)
+    end)
+
+-- ---- Fleet wake (pipi: wake-only, no power-off) ----
+server:tool("wake_fleet",
+    "Wake a fleet NUC (pve1..pve4) via Fritz!Box Wake-on-LAN. Powers a node ON only; it cannot power anything off. Node boots in ~30-60s.",
+    {
+        type = "object",
+        properties = {
+            node = { type = "string", description = "Node to wake: '1'..'4' or 'pve1'..'pve4'" },
+        },
+        required = { "node" },
+    },
+    function(a)
+        local node = tostring(a.node or ""):gsub("[^%w]", "")
+        if not node:match("^p?v?e?[1-4]$") then
+            return "Error: node must be 1-4 or pve1-pve4 (got: " .. tostring(a.node) .. ")"
+        end
+        return run("sudo /root/.local/bin/wake-pve " .. node .. " 2>&1", 15)
+    end)
+
+-- ---- apropos: lean facade for stash recall (read-only memory) ----
+server:tool("apropos",
+    "Search shared fleet memory (stash) for facts about the fleet, projects, decisions, and preferences. query = 2-6 words on the topic; limit = max results (default 3). Read-only.",
+    {
+        type = "object",
+        properties = {
+            query = { type = "string",  description = "2-6 words describing what to recall" },
+            limit = { type = "integer", description = "max results, default 3" },
+        },
+        required = { "query" },
+    },
+    function(a)
+        local q = tostring(a.query or ""):gsub("[^%w%s%-%.]", " "):gsub("%s+", " ")
+        if q:gsub("%s","") == "" then return "Error: query required" end
+        local lim = tonumber(a.limit) or 3
+        return run("python3 /opt/lmcp/helpers/stash_recall.py '" .. q .. "' " .. lim, 30)
+    end)

tools.d/nash.lua

@@ -0,0 +1,103 @@
+-- /opt/lmcp/tools.d/nash.lua -- nash shared memory tools
+--
+-- Provides add/search/list/delete tools for the nash memory service.
+-- Requires NASH_URL env var (e.g. http://192.168.88.143:8000).
+-- When unset, tools return an error guiding the user to set it.
+--
+-- SPDX-License-Identifier: MIT
+
+local server, run = ...
+
+local function nash_url()
+    local url = os.getenv("NASH_URL")
+    if not url or url == "" then return nil end
+    return url:gsub("/+$", "")
+end
+
+local function curl_json(url, method, body, timeout)
+    timeout = timeout or 10
+    local out = "/tmp/lmcp-nash-" .. os.time() .. "-" .. math.random(10000, 99999) .. ".json"
+    local fmt = "http_code=%{http_code}"
+    local cmd
+    if body then
+        local tmp = out .. ".req"
+        local f = io.open(tmp, "w")
+        if f then f:write(body); f:close() end
+        cmd = string.format(
+            "curl -sS -X %s --max-time %d -H 'Content-Type: application/json' --data-binary '@%s' -o '%s' -w '%s' '%s'",
+            method, timeout, tmp, out, fmt, url
+        )
+        os.execute("rm -f '" .. tmp .. "' 2>/dev/null")
+    else
+        cmd = string.format(
+            "curl -sS -X %s --max-time %d -o '%s' -w '%s' '%s'",
+            method, timeout, out, fmt, url
+        )
+    end
+    local raw = run(cmd, timeout + 5) or ""
+    local http_code = tonumber(raw:match("(%d+)$")) or 0
+    local body_out = ""
+    local f = io.open(out, "r")
+    if f then body_out = f:read("*a") or ""; f:close() end
+    os.execute("rm -f '" .. out .. "' 2>/dev/null")
+    return body_out, http_code
+end
+
+server:tool("nash_add", "Store a text entry in shared nash memory.", {
+    type = "object",
+    properties = {
+        text = { type = "string", description = "Text content to remember" },
+    },
+    required = { "text" },
+}, function(a)
+    local base = nash_url()
+    if not base then return "Error: set NASH_URL env var (e.g. http://192.168.88.143:8000)" end
+    local json, code = curl_json(base .. "/add", "POST", '{"text":' .. require("json").encode(a.text) .. '}')
+    if code ~= 200 then return "Error: nash API HTTP " .. code .. ": " .. json end
+    return json
+end)
+
+server:tool("nash_search", "Semantic search across shared nash memory.", {
+    type = "object",
+    properties = {
+        query = { type = "string", description = "Search query" },
+        limit = { type = "integer", description = "Max results (default 5)", default = 5 },
+    },
+    required = { "query" },
+}, function(a)
+    local base = nash_url()
+    if not base then return "Error: set NASH_URL env var (e.g. http://192.168.88.143:8000)" end
+    local body = '{"query":' .. require("json").encode(a.query) .. ',"limit":' .. (a.limit or 5) .. '}'
+    local json, code = curl_json(base .. "/search", "POST", body)
+    if code ~= 200 then return "Error: nash API HTTP " .. code .. ": " .. json end
+    return json
+end)
+
+server:tool("nash_list", "List all entries in shared nash memory.", {
+    type = "object",
+    properties = {
+        limit = { type = "integer", description = "Max results (default 100)", default = 100 },
+    },
+}, function(a)
+    local base = nash_url()
+    if not base then return "Error: set NASH_URL env var (e.g. http://192.168.88.143:8000)" end
+    local body = '{"limit":' .. (a.limit or 100) .. '}'
+    local json, code = curl_json(base .. "/scroll", "POST", body)
+    if code ~= 200 then return "Error: nash API HTTP " .. code .. ": " .. json end
+    return json
+end)
+
+server:tool("nash_delete", "Delete an entry from shared nash memory by ID.", {
+    type = "object",
+    properties = {
+        id = { type = "string", description = "Entry ID to delete" },
+    },
+    required = { "id" },
+}, function(a)
+    local base = nash_url()
+    if not base then return "Error: set NASH_URL env var (e.g. http://192.168.88.143:8000)" end
+    local body = '{"id":' .. require("json").encode(a.id) .. '}'
+    local json, code = curl_json(base .. "/delete", "POST", body)
+    if code ~= 200 then return "Error: nash API HTTP " .. code .. ": " .. json end
+    return json
+end)

windows/README.md

@@ -0,0 +1,57 @@
+# lmcp Windows MSI build
+
+This directory contains the WiX manifest and packaging files for the
+Windows MSI build of lmcp.
+
+## Recommended: cross-build on Linux (one command)
+
+```sh
+./build-msi.sh /path/to/output/dir
+```
+
+Downloads Lua 5.4 Win64 binaries from LuaBinaries, cross-compiles
+LuaSocket via `mingw-w64`, stages `pkg/lua/`, and runs `wixl` to
+produce `lmcp-<version>.msi`. No Windows VM required.
+
+Prereqs on a Debian/Ubuntu builder:
+```sh
+sudo apt install wixl unzip gcc-mingw-w64-x86-64 \
+                 binutils-mingw-w64-x86-64 mingw-w64-x86-64-dev curl
+```
+
+Version comes from `lmcp.wxs` `Version="…"`. Bump that before
+building a release.
+
+## Alternative: build on Windows via WiX toolset
+
+```cmd
+sync.sh                                  REM see "tracked vs. generated"
+REM ensure pkg/lua/ has the runtime — see below
+candle.exe lmcp.wxs
+light.exe lmcp.wixobj -o lmcp-1.x.y.msi
+```
+
+## What's tracked vs. generated
+
+- **Tracked** (edit in git):
+  - `lmcp.wxs` — WiX MSI manifest
+  - `sync.sh` — copies root .lua sources → `pkg/`
+  - `README.md` — this file
+  - `pkg/install_service.bat` — Windows service installer
+  - `pkg/start.bat` — manual launcher
+
+- **Generated / external** (gitignored):
+  - `pkg/lmcp.lua`, `pkg/server.lua`, `pkg/json.lua` — produced by
+    `sync.sh`. Never edit directly; edit the root files and re-sync.
+  - `pkg/lua/` — the Lua + LuaSocket runtime drop-in. Download
+    separately and place here. Suggested source: the lua-binaries
+    project (https://github.com/rjpcomputing/luaforwindows) or a
+    similar pre-built bundle. The MSI expects `pkg/lua/lua.exe`,
+    `pkg/lua/lua54.dll`, and the `pkg/lua/socket/` + `pkg/lua/mime/`
+    subdirectories per the manifest.
+
+## Issue history
+
+Issue #18 (closed in v1.1.0) introduced this workflow after the
+`pkg/` lua sources had silently drifted ~6 months out of date,
+missing every feature added since April 2026.

windows/build-msi.sh

@@ -0,0 +1,100 @@
+#!/bin/sh
+# windows/build-msi.sh — produce lmcp-<ver>.msi on Linux via wixl.
+#
+# This is the first-time-discovered cross-build path: download Lua 5.4
+# Win64 binaries from LuaBinaries, cross-compile LuaSocket with mingw-w64,
+# stage windows/pkg/lua/, then invoke wixl on the WiX manifest.
+#
+# Avoids the VM106-clone + WiX-on-Windows path entirely. ~1 minute on a
+# warm cache; ~3-5 minutes cold (downloads ~700 KB + cross-compiles).
+#
+# Prereqs (apt install on Debian aarch64):
+#   apt-get install -y wixl unzip gcc-mingw-w64-x86-64 binutils-mingw-w64-x86-64 \
+#                      mingw-w64-x86-64-dev
+#
+# Usage: ./build-msi.sh [output_dir]
+#   Output: $output_dir/lmcp-<ver>.msi (default: $PWD)
+#
+# Version comes from windows/lmcp.wxs Version="…" attribute.
+set -eu
+
+here=$(dirname "$(readlink -f "$0")")
+root=$(cd "$here/.." && pwd)
+out_dir=${1:-$PWD}
+work=$(mktemp -d /tmp/lmcp-msi-XXXXXX)
+trap "rm -rf $work" EXIT
+
+# Versions — bump as upstream releases.
+LUA_VER=5.4.2
+LUASOCKET_VER=3.1.0
+
+# Pull current lmcp version from the WiX manifest.
+lmcp_ver=$(sed -n 's/.*Version="\([^"]*\)".*/\1/p' "$here/lmcp.wxs" | head -1)
+[ -n "$lmcp_ver" ] || { echo "build-msi.sh: cannot parse Version from lmcp.wxs" >&2; exit 1; }
+
+echo "build-msi.sh: lmcp $lmcp_ver, lua $LUA_VER, luasocket $LUASOCKET_VER"
+
+echo "==> 1/5 sync lmcp .lua sources into pkg/"
+"$here/sync.sh"
+
+echo "==> 2/5 fetch lua $LUA_VER win64 binaries + dev library"
+cd "$work"
+curl -sSLf -o lua-bin.zip \
+    "https://downloads.sourceforge.net/project/luabinaries/${LUA_VER}/Tools%20Executables/lua-${LUA_VER}_Win64_bin.zip"
+curl -sSLf -o lua-lib.zip \
+    "https://downloads.sourceforge.net/project/luabinaries/${LUA_VER}/Windows%20Libraries/Dynamic/lua-${LUA_VER}_Win64_dllw6_lib.zip"
+mkdir -p luabin lualib include/lua/54 include/lua54 bin/lua/54 bin/lua54 lib/lua/54 lib/lua54
+unzip -q -o lua-bin.zip -d luabin
+unzip -q -o lua-lib.zip -d lualib
+cp lualib/include/*.h include/lua/54/
+cp lualib/include/*.h include/lua54/
+cp lualib/liblua54.a lib/lua/54/
+cp lualib/liblua54.a lib/lua54/
+cp lualib/lua54.dll bin/lua/54/
+cp lualib/lua54.dll bin/lua54/
+
+echo "==> 3/5 cross-compile LuaSocket $LUASOCKET_VER for win64"
+curl -sSLf -o luasocket.tar.gz \
+    "https://github.com/lunarmodules/luasocket/archive/refs/tags/v${LUASOCKET_VER}.tar.gz"
+tar xzf luasocket.tar.gz
+cd "luasocket-${LUASOCKET_VER}"
+make -s PLAT=mingw \
+    CC=x86_64-w64-mingw32-gcc \
+    LD=x86_64-w64-mingw32-gcc \
+    LUAV=54 \
+    LUAINC_mingw_base="$work/include" \
+    LUALIB_mingw_base="$work/bin" \
+    > /dev/null
+
+echo "==> 4/5 stage pkg/lua/"
+pkg_lua="$here/pkg/lua"
+rm -rf "$pkg_lua"
+mkdir -p "$pkg_lua/socket" "$pkg_lua/mime"
+
+# WiX manifest expects "lua.exe" (not "lua54.exe").
+cp "$work/luabin/lua54.exe"        "$pkg_lua/lua.exe"
+cp "$work/luabin/lua54.dll"        "$pkg_lua/lua54.dll"
+cp src/socket.lua                  "$pkg_lua/"
+cp src/mime.lua                    "$pkg_lua/"
+cp src/ltn12.lua                   "$pkg_lua/"
+cp src/socket-3.0.0.dll            "$pkg_lua/socket/core.dll"
+cp src/ftp.lua                     "$pkg_lua/socket/"
+cp src/headers.lua                 "$pkg_lua/socket/"
+cp src/http.lua                    "$pkg_lua/socket/"
+cp src/smtp.lua                    "$pkg_lua/socket/"
+cp src/tp.lua                      "$pkg_lua/socket/"
+cp src/url.lua                     "$pkg_lua/socket/"
+cp src/mime-1.0.3.dll              "$pkg_lua/mime/core.dll"
+
+echo "==> 5/5 wixl: produce MSI"
+# wixl wants forward slashes; rewrite Windows-style backslashes in Source=.
+wxs_tmp="$work/lmcp.wxs"
+sed 's|Source="pkg\\|Source="pkg/|g; s|\\\([a-zA-Z]\)|/\1|g' "$here/lmcp.wxs" > "$wxs_tmp"
+mkdir -p "$out_dir"
+out_msi="$out_dir/lmcp-${lmcp_ver}.msi"
+(cd "$here" && wixl -v "$wxs_tmp" -o "$out_msi")
+
+echo ""
+echo "==> done: $out_msi"
+ls -la "$out_msi"
+sha256sum "$out_msi"

windows/lmcp.wxs

@@ -0,0 +1,119 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
+  <!-- Bump Version on every release. See windows/README.md. -->
+  <Product Id="*"
+           Name="lmcp — Lua MCP Server"
+           Language="1033"
+           Version="1.1.0"
+           Manufacturer="QAP'LA Project"
+           UpgradeCode="A7F3E2D1-4B5C-6D7E-8F9A-0B1C2D3E4F5A">
+
+    <Package InstallerVersion="200"
+             Compressed="yes"
+             InstallScope="perMachine"
+             Description="Lightweight MCP server in Lua. 2MB RSS."
+             Comments="Zero-dependency MCP server." />
+
+    <MediaTemplate EmbedCab="yes" />
+
+    <MajorUpgrade DowngradeErrorMessage="A newer version is already installed." />
+
+    <Directory Id="TARGETDIR" Name="SourceDir">
+      <Directory Id="ProgramFiles64Folder">
+        <Directory Id="INSTALLFOLDER" Name="lmcp">
+          <Directory Id="LUA_DIR" Name="lua">
+            <Directory Id="SOCKET_DIR" Name="socket" />
+            <Directory Id="MIME_DIR" Name="mime" />
+          </Directory>
+        </Directory>
+      </Directory>
+    </Directory>
+
+    <!-- lmcp application files -->
+    <DirectoryRef Id="INSTALLFOLDER">
+      <Component Id="JsonLua" Guid="B1A2C3D4-E5F6-7890-ABCD-EF1234567890">
+        <File Id="json.lua" Source="pkg\json.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="LmcpLua" Guid="B1A2C3D4-E5F6-7890-ABCD-EF1234567891">
+        <File Id="lmcp.lua" Source="pkg\lmcp.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="ServerLua" Guid="B1A2C3D4-E5F6-7890-ABCD-EF1234567892">
+        <File Id="server.lua" Source="pkg\server.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="StartBat" Guid="B1A2C3D4-E5F6-7890-ABCD-EF1234567893">
+        <File Id="start.bat" Source="pkg\start.bat" KeyPath="yes" />
+      </Component>
+      <Component Id="InstallService" Guid="B1A2C3D4-E5F6-7890-ABCD-EF1234567894">
+        <File Id="install_service.bat" Source="pkg\install_service.bat" KeyPath="yes" />
+      </Component>
+    </DirectoryRef>
+
+    <!-- Lua runtime -->
+    <DirectoryRef Id="LUA_DIR">
+      <Component Id="LuaExe" Guid="C2B3D4E5-F6A7-8901-BCDE-F12345678900">
+        <File Id="lua.exe" Source="pkg\lua\lua.exe" KeyPath="yes" />
+      </Component>
+      <Component Id="LuaDll" Guid="C2B3D4E5-F6A7-8901-BCDE-F12345678901">
+        <File Id="lua54.dll" Source="pkg\lua\lua54.dll" KeyPath="yes" />
+      </Component>
+      <Component Id="SocketLua" Guid="C2B3D4E5-F6A7-8901-BCDE-F12345678902">
+        <File Id="socket.lua" Source="pkg\lua\socket.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="MimeLua" Guid="C2B3D4E5-F6A7-8901-BCDE-F12345678903">
+        <File Id="mime.lua" Source="pkg\lua\mime.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="Ltn12Lua" Guid="C2B3D4E5-F6A7-8901-BCDE-F12345678904">
+        <File Id="ltn12.lua" Source="pkg\lua\ltn12.lua" KeyPath="yes" />
+      </Component>
+    </DirectoryRef>
+
+    <!-- LuaSocket native DLLs -->
+    <DirectoryRef Id="SOCKET_DIR">
+      <Component Id="SocketCoreDll" Guid="D3C4E5F6-A7B8-9012-CDEF-123456789010">
+        <File Id="socket_core.dll" Name="core.dll" Source="pkg\lua\socket\core.dll" KeyPath="yes" />
+      </Component>
+      <Component Id="SocketFtp" Guid="D3C4E5F6-A7B8-9012-CDEF-123456789011">
+        <File Id="ftp.lua" Source="pkg\lua\socket\ftp.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="SocketHeaders" Guid="D3C4E5F6-A7B8-9012-CDEF-123456789012">
+        <File Id="headers.lua" Source="pkg\lua\socket\headers.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="SocketHttp" Guid="D3C4E5F6-A7B8-9012-CDEF-123456789013">
+        <File Id="http.lua" Source="pkg\lua\socket\http.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="SocketTp" Guid="D3C4E5F6-A7B8-9012-CDEF-123456789014">
+        <File Id="tp.lua" Source="pkg\lua\socket\tp.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="SocketUrl" Guid="D3C4E5F6-A7B8-9012-CDEF-123456789015">
+        <File Id="url.lua" Source="pkg\lua\socket\url.lua" KeyPath="yes" />
+      </Component>
+    </DirectoryRef>
+
+    <DirectoryRef Id="MIME_DIR">
+      <Component Id="MimeCoreDll" Guid="E4D5F6A7-B8C9-0123-DEFA-234567890120">
+        <File Id="mime_core.dll" Name="core.dll" Source="pkg\lua\mime\core.dll" KeyPath="yes" />
+      </Component>
+    </DirectoryRef>
+
+    <Feature Id="MainFeature" Title="lmcp Server" Level="1">
+      <ComponentRef Id="JsonLua" />
+      <ComponentRef Id="LmcpLua" />
+      <ComponentRef Id="ServerLua" />
+      <ComponentRef Id="StartBat" />
+      <ComponentRef Id="InstallService" />
+      <ComponentRef Id="LuaExe" />
+      <ComponentRef Id="LuaDll" />
+      <ComponentRef Id="SocketLua" />
+      <ComponentRef Id="MimeLua" />
+      <ComponentRef Id="Ltn12Lua" />
+      <ComponentRef Id="SocketCoreDll" />
+      <ComponentRef Id="SocketFtp" />
+      <ComponentRef Id="SocketHeaders" />
+      <ComponentRef Id="SocketHttp" />
+      <ComponentRef Id="SocketTp" />
+      <ComponentRef Id="SocketUrl" />
+      <ComponentRef Id="MimeCoreDll" />
+    </Feature>
+
+  </Product>
+</Wix>

windows/pkg/install_service.bat

@@ -0,0 +1,24 @@
+@echo off
+REM Install lmcp as a Windows service using NSSM (Non-Sucking Service Manager)
+REM Download nssm from https://nssm.cc if not present
+
+if not exist "%~dp0nssm.exe" (
+    echo ERROR: nssm.exe not found in %~dp0
+    echo Download from https://nssm.cc and place nssm.exe here.
+    exit /b 1
+)
+
+set INSTALL_DIR=%~dp0
+set SERVICE_NAME=lmcp
+
+echo Installing lmcp as Windows service...
+%INSTALL_DIR%nssm.exe install %SERVICE_NAME% "%INSTALL_DIR%lua\lua.exe" "%INSTALL_DIR%server.lua"
+%INSTALL_DIR%nssm.exe set %SERVICE_NAME% AppDirectory "%INSTALL_DIR%"
+%INSTALL_DIR%nssm.exe set %SERVICE_NAME% AppEnvironmentExtra "LMCP_PORT=8080"
+%INSTALL_DIR%nssm.exe set %SERVICE_NAME% DisplayName "lmcp MCP Server"
+%INSTALL_DIR%nssm.exe set %SERVICE_NAME% Description "Lightweight MCP server in Lua"
+%INSTALL_DIR%nssm.exe set %SERVICE_NAME% Start SERVICE_AUTO_START
+%INSTALL_DIR%nssm.exe start %SERVICE_NAME%
+
+echo Done. Service '%SERVICE_NAME%' installed and started.
+echo Check: sc query %SERVICE_NAME%

windows/pkg/start.bat

@@ -0,0 +1,7 @@
+@echo off
+REM lmcp — Lua MCP Server
+REM Start the server on port 8080 (or LMCP_PORT if set)
+cd /d "%~dp0"
+if not defined LMCP_PORT set LMCP_PORT=8080
+echo Starting lmcp on port %LMCP_PORT%...
+lua\lua.exe server.lua

windows/sync.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+# windows/sync.sh — refresh windows/pkg/ from root .lua sources (issue #18).
+#
+# Run BEFORE invoking the WiX build so the MSI bundles whatever is in
+# master. The .lua files in windows/pkg/ are regenerated on every run
+# and are gitignored — never edit them directly.
+#
+# Idempotent: re-running just re-copies. Safe to call from a Makefile,
+# a CI step, or by hand before `candle.exe + light.exe`.
+
+set -eu
+
+here=$(dirname "$(readlink -f "$0")")
+root=$(cd "$here/.." && pwd)
+
+for f in lmcp.lua server.lua json.lua; do
+    if [ ! -f "$root/$f" ]; then
+        echo "windows/sync.sh: missing source $root/$f" >&2
+        exit 1
+    fi
+    cp "$root/$f" "$here/pkg/$f"
+    echo "  synced $f"
+done
+
+echo "windows/sync.sh: done — pkg/ matches root .lua at $(date +%Y-%m-%dT%H:%M:%S)"