haltija 1.13.0-beta.5 → 1.13.1

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # Changelog
 
+## 1.13.1 (2026-11-01)
+
+### Changed
+
+- **Page text is neutralized by floorplan's own `neutralizeProvenance`** (tosijs-floorplan 0.7.0,
+  virta #3387), replacing haltija's hand copy of that policy. Output is identical.
+- **Schematics use tosijs-floorplan 0.6.0** (virta #3388). Floorplan now draws haltija's ref pill
+  itself (`refStyle: 'pill'`), so haltija's own pill plugin is gone; the picture is unchanged.
+- **A schematic can carry floorplan's `note`**, which says what the drawing can't be trusted to say:
+  nothing could be drawn for the region, or (on the tosi-agent tier) no record carries affordance
+  evidence. haltija now tells floorplan that its DOM map checked every element (`introspected`), so
+  a page with no controls is reported as having none rather than as a blind spot.
+
+### Fixed
+
+- **MCP tools now tell the agent their argument types.** Every optional argument is typed
+  `["string", "null"]` in the API schema, and the MCP server's converter matched none of those, so
+  `click`'s `selector`, `ref`, `text` and every other optional field reached the agent untyped.
+- **The "SCHEMATIC" banner is no longer cut off on narrow viewports** (virta #3381). The geometric
+  frame was sized to the page content alone; it is now at least as wide as the banner, as the
+  stacked layout's always was.
+
+### Security
+
+- **The bundled MCP server (`dist/mcp.js`) carried two vulnerable libraries.** Affected: haltija
+  **1.13.0-beta.4 to 1.13.0**, the releases that ship that bundle. `fast-uri` 3.1.8 (via the MCP
+  SDK's `ajv`; GHSA-333x-w4r6-6crp, GHSA-w74x-v6f9-j3xg, GHSA-wjr9-j795-jxcr, GHSA-xhq7-xmqj-769h)
+  is now 3.1.9, and `zod` 3.25.76 (GHSA-mrhx-c7xc-m3w5, memory exhaustion on oversized
+  collections; no 3.x fix) is now 4.6.7. The MCP server's only caller is the local MCP client over
+  stdio, so neither was reachable from the network.
+- **Development installs only, nothing shipped:** the desktop app's `electron` 43.8.6
+  (GHSA-jr5w-w6x2-84p9, compromised eMudhra intermediate certificates), its `undici` 7.30.1
+  (GHSA-xjj6-f33q-929c), and `body-parser` 2.4.0 (GHSA-27r3-jxmh-p828, via the MCP SDK's express,
+  which the bundle does not include). Lockfile updates; no other dependency moved.
+
+## 1.13.0 (2026-10-18)
+
+The 1.13 betas, released. Read **Security** and **Upgrading from 1.12** before moving off 1.12.x.
+The beta sections below have the detail and the reasoning; this section is the list. The changes
+made after beta.5 are at the end.
+
+### Security
+
+- **Through 1.12.9, anything on your network could drive your browser.** The server listens on
+  every interface and, without `--token`, answered any machine, `/eval` included. Affected: every
+  release through **1.12.9** (the previous `latest`) and **1.13.0-beta.1 to beta.4**. In 1.13.0 a
+  connection from another machine is refused (403) unless the server has a token (virta #815,
+  GitHub #44; first shipped in beta.5). If you stay on 1.12.x, start the server with `--token
+  <secret>` on any network you don't trust.
+- **Pages on this machine can still call the API, and that is by design.** beta.1 listed this as a
+  known issue with "an origin gate planned before 1.13.0". That gate is not coming: the widget is
+  injected into arbitrary pages, so the REST surface must answer any origin, and an origin check
+  would break exactly the pages haltija exists for. `--token` closes it, as it closes a tunnel or
+  reverse proxy running on this machine (which connects from localhost). The README's Security
+  section says what is and isn't covered.
+
+### Upgrading from 1.12
+
+Each of these changes something that worked before. Before → after:
+
+- **Other machines need a token.** Phones, headsets, other computers, and browsers in a container,
+  VM or WSL2 that reach haltija through a forwarded port: they connected freely, and now get a 403
+  until the server has `--token <secret>` and the client sends it (beta.5).
+- **Both transports by default.** `DEV_CHANNEL_MODE` was `http`; it is `both`, so HTTPS 8701 comes
+  up too. `--http` opts out, and says what that costs other projects (beta.1).
+- **The certificate lives in `~/.haltija/certs`.** It was per-install; an existing one is copied
+  forward, so trust you already granted survives (beta.1).
+- **The desktop app's internal server moved from 8701 to 8710.** `HALTIJA_PORT=8701 hj tree`
+  (inspecting the app's own UI) is now `HALTIJA_PORT=8710 hj tree` (beta.1).
+- **Only the server on 8700 takes HTTPS 8701.** A `--port` / `--name` server's HTTPS is now
+  ephemeral, shown in its banner and `/status`, unless you pass `--https-port` (beta.1).
+- **`server` from `haltija/server` is the HTTP listener**, and `server`, `httpServer` and
+  `httpsServer` are typed `ListeningServer` (`port`, `hostname`, `url`, `stop()`) instead of
+  Bun's server type. Code that used other Bun server methods on them needs a cast (beta.1).
+- **Navigate and refresh wait for the page's widget.** They returned at once; now they block until
+  the widget reconnects, up to `--timeout` (default 10 s). A page that doesn't load the widget
+  itself (a bookmarklet tab) waits that long every time: pass `--no-wait` there. `navigate()` and
+  `refresh()` in `DevChannelClient` / `haltija/test` now return `{ reconnected, warning? }` (beta.2).
+- **The widget writes `window.name` while navigating**, and restores the page's own value after.
+  An app that keeps state in `window.name` can see the marker briefly (beta.2).
+- **`press` acts at the focused element.** In `haltija/test` and `DevChannelClient.press` it was one
+  `keydown` at `body`; now it is the full key sequence at the focused element, like `hj key`
+  (beta.4).
+- **Schematics are drawn by tosijs-floorplan.** Same response fields; the picture looks different
+  (beta.5).
+
+### Fixed after beta.5
+
+From the 1.13.0 release review (`reviews/1.13.0-*.md`):
+
+- **A refused connection from another machine is now logged on the server**, once per address, with
+  the `--token` remedy. A browser cannot read why a WebSocket handshake failed, so a widget in a
+  container or VM retried forever while the server said nothing.
+- **`DevChannelClient` and `haltija/test` send `HALTIJA_TOKEN`.** `hj` and the MCP bridge always
+  did; these two never did, so a test suite could not reach a `--token` server at all, which since
+  beta.5 is the setup for any runner on another machine.
+- **`haltija --token=<secret>` sets a token.** The launcher read only `--token <secret>`, so the `=`
+  form, like a misspelled flag, started a server with no token and no complaint. `--flag=value` now
+  works for every launcher flag that takes a value, an unknown flag is reported, and the banner has
+  an `AUTH:` line saying whether a token is in force.
+- **`/drag`, `hj drag` and the `drag` step move pointer-driven controls.** They sent bare mouse
+  events (some of them `CustomEvent`s with no coordinates), so a slider, resize handle or orbit
+  camera that listens for pointer events didn't move while the drag reported success. They now use
+  the same pointer-and-mouse sequence as `dragFrom`, with `buttons` set while pressed.
+- **MCP setup replaces a stale entry.** Before 1.13 setup wrote `node …/apps/mcp/build/index.js`,
+  which no longer exists. `--check` reported such an entry as configured, and re-running setup said
+  "already configured". Both now call it stale, and setup rewrites it. The help named
+  `npx haltija-mcp-setup`, a package that does not exist; it is `npx -p haltija haltija-mcp-setup`.
+- **The `test:integration` lane runs its tests.** It needed a server it was never given, so every
+  1.13 beta attested "0 pass, 11 skip" as a pass. It now starts its own private headless instance,
+  and a lane that only skipped fails.
+- Docs: the README no longer shows a demo image that doesn't exist, and links the API reference and
+  the browser-test guide (`docs/TEST-IN-BROWSER.md`).
+
 ## 1.13.0-beta.5 (2026-10-18)
 
 ### Changed

package/README.md

@@ -8,9 +8,6 @@
 
 Unlike screenshot-based tools, Haltija works with the actual DOM. Unlike Playwright, it connects to your real browser — already logged in, same cookies, same bug you're looking at.
 
-<!-- TODO: Replace with actual GIF showing: 1) bunx haltija launches app, 2) agent queries tree, 3) agent clicks something, 4) highlight shows result -->
-![Haltija in action](docs/assets/demo.gif)
-
 > *Haltija* (Finnish): a guardian spirit that watches over a place. In this case, your DOM.
 
 ---
@@ -337,7 +334,9 @@ app also exists but isn't required for either.
   8701 by default), but without a token it refuses every connection that doesn't come from this
   machine. To use haltija from another device (a phone, a headset, a second computer), start it
   with `--token <secret>` (or `HALTIJA_TOKEN`) and send the same value as `X-Haltija-Token`,
-  `?token=`, or the widget's `token` option.
+  `?token=`, or the widget's `token` option. A browser in a container, VM or WSL2 that reaches
+  haltija through a forwarded port also counts as another machine. The server's terminal names
+  each refused address once.
 - **On this machine, any page you visit can call it.** The widget is injected into arbitrary
   pages, so the REST API answers any origin, `/eval` in your connected tabs included. That is by
   design for a local dev tool, and `--token` closes it too. A tunnel or reverse proxy on this
@@ -411,10 +410,11 @@ hj api                        # Full API reference (markdown)
 hj --help                     # CLI subcommand reference
 ```
 
-- [Full API Reference](./API.md) (auto-generated from schema)
+- [Full API Reference](https://github.com/tonioloewald/haltija/blob/main/API.md) (auto-generated from schema)
 - [Agent Prompt](docs/agent-prompt.md) — Copy-paste prompt for any AI agent
 - [Recipes](docs/recipes.md) — Common workflows
 - [CI Integration](docs/CI-INTEGRATION.md) — E2E testing with Haltija in GitHub Actions
+- [Browser tests from your test runner](docs/TEST-IN-BROWSER.md) — `createBrowserPage` from `haltija/test`: assertions on the host, probes in a real browser
 - [Roadmap](docs/ROADMAP.md)
 
 ---

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.13.0-beta.5",
+  "version": "1.13.1",
   "private": true,
   "description": "Haltija Desktop - God Mode Browser for AI Agents",
   "homepage": "https://github.com/tonioloewald/haltija",

package/apps/desktop/resources/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.13.0-beta.5";
+  var VERSION = "1.13.1";
 
   // src/ws-url.ts
   function httpBaseFromWsUrl(wsUrl2, fallback = "http://localhost:8700") {
@@ -237,7 +237,15 @@
     const at = Math.max(v.lastIndexOf(BOUND_TWO_WAY), v.lastIndexOf(BOUND_TO_DOM));
     return neutralizeArrows(at >= 0 ? v.slice(0, at).trim() : v);
   };
-  var neutralizeArrows = (s) => s.replaceAll(BOUND_TWO_WAY, "<->").replaceAll(BOUND_TO_DOM, "<-");
+  var PROVENANCE_REWRITES = [
+    [BOUND_TWO_WAY, "<->"],
+    [BOUND_TO_DOM, "<-"]
+  ];
+  var neutralizeArrows = (s) => PROVENANCE_REWRITES.reduce((out, [token, neutral]) => out.replaceAll(token, neutral), s);
+  var PROVENANCE_TOKENS = Object.freeze(PROVENANCE_REWRITES.map(([token]) => token));
+  function neutralizeProvenance(text) {
+    return typeof text === "string" ? neutralizeArrows(text) : text;
+  }
   var boundTwoWay = (v) => {
     if (typeof v !== "string")
       return false;
@@ -287,7 +295,6 @@
     return width < targetSize || height < targetSize ? `${width}×${height} — below ${targetSize}×${targetSize} (WCAG 2.5.8)` : null;
   };
   var finiteBounds = (b) => Number.isFinite(b.x) && Number.isFinite(b.y) && Number.isFinite(b.width) && Number.isFinite(b.height);
-  var printable = (value) => value == null || typeof value === "number";
   var intersects = (a, b) => a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
   var contains = (outer, inner) => inner.x >= outer.x && inner.y >= outer.y && inner.x + inner.width <= outer.x + outer.width && inner.y + inner.height <= outer.y + outer.height;
   var esc = (s) => typeof s !== "string" ? "" : s.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
@@ -331,8 +338,8 @@
   };
   var schematic = (description, options = {}) => {
     const {
-      minLabelHeight = 14,
-      maxCaption = 36,
+      minLabelHeight: minLabelHeightIn = 14,
+      maxCaption: maxCaptionIn = 36,
       within: withinIn,
       index: showIndex = false,
       targetSize = TARGET_SIZE_DEFAULT,
@@ -340,9 +347,12 @@
       decorate
     } = options;
     const padIn = options.pad;
-    const pad = padIn === undefined || !printable(padIn) ? 8 : padIn;
+    const pad = padIn === null || typeof padIn === "number" && Number.isFinite(padIn) && padIn >= 0 ? padIn : 8;
     const fontSizeIn = options.fontSize;
-    const fontSize = fontSizeIn === undefined || !printable(fontSizeIn) ? 11 : fontSizeIn;
+    const fontSize = fontSizeIn === null || typeof fontSizeIn === "number" && Number.isFinite(fontSizeIn) && fontSizeIn > 0 ? fontSizeIn : 11;
+    const minLabelHeight = Number.isNaN(minLabelHeightIn) ? 14 : minLabelHeightIn;
+    const maxCaption = typeof maxCaptionIn === "number" && (Number.isNaN(maxCaptionIn) || maxCaptionIn < 1) ? 36 : maxCaptionIn;
+    const refStyle = options.refStyle === "pill" ? "pill" : "stamp";
     const legend = [];
     const within = withinIn == null ? undefined : {
       x: withinIn.x,
@@ -350,7 +360,7 @@
       width: withinIn.width,
       height: withinIn.height
     };
-    const withinOk = within == null || printable(within.x) && printable(within.y) && printable(within.width) && printable(within.height);
+    const withinOk = within == null || finiteBounds(within);
     const geometry = new Map;
     const snapshotOf = (w) => {
       if (geometry.has(w))
@@ -370,22 +380,38 @@
       return g.width > 0 && g.height > 0 && (w.viewportFixed === true || g.x + g.width > 0 && g.y + g.height > 0) && (within == null || w.viewportFixed === true || intersects(g, within));
     });
     const flow = boxes.filter((w) => w.viewportFixed !== true);
-    if (boxes.length === 0) {
-      return {
-        svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 0 0"></svg>',
-        legend
-      };
+    const emptyMap = (why) => why == null ? {
+      svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 0 0"></svg>',
+      legend
+    } : {
+      svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 0 0">' + `<desc>${esc(why)}</desc></svg>`,
+      legend,
+      note: why
+    };
+    if (!withinOk) {
+      return emptyMap("nothing drawn: `within` is not a usable region (a field is not a " + "finite number) — this is not an empty region");
     }
+    if (boxes.length === 0)
+      return emptyMap();
     const fitBoxes = flow.length > 0 ? flow : boxes;
-    const minX = within != null ? within.x - pad : Math.min(...fitBoxes.map((w) => geometry.get(w).x)) - pad;
-    const minY = within != null ? within.y - pad : Math.min(...fitBoxes.map((w) => geometry.get(w).y)) - pad;
-    const maxX = within != null ? within.x + within.width + pad : Math.max(...fitBoxes.map((w) => geometry.get(w).x + geometry.get(w).width)) + pad;
-    const maxY = within != null ? within.y + within.height + pad : Math.max(...fitBoxes.map((w) => geometry.get(w).y + geometry.get(w).height)) + pad;
+    const minXRaw = within != null ? within.x - pad : Math.min(...fitBoxes.map((w) => geometry.get(w).x)) - pad;
+    const minYRaw = within != null ? within.y - pad : Math.min(...fitBoxes.map((w) => geometry.get(w).y)) - pad;
+    const maxXRaw = within != null ? within.x + within.width + pad : Math.max(...fitBoxes.map((w) => geometry.get(w).x + geometry.get(w).width)) + pad;
+    const maxYRaw = within != null ? within.y + within.height + pad : Math.max(...fitBoxes.map((w) => geometry.get(w).y + geometry.get(w).height)) + pad;
+    const overflow = ![
+      minXRaw,
+      minYRaw,
+      maxXRaw,
+      maxYRaw,
+      maxXRaw - minXRaw,
+      maxYRaw - minYRaw
+    ].every(Number.isFinite);
+    const [minX, minY, maxX, maxY] = overflow ? [0, 0, 0, 0] : [minXRaw, minYRaw, maxXRaw, maxYRaw];
     const parts = [
       `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${minX} ${minY} ${maxX - minX} ${maxY - minY}" width="${maxX - minX}" height="${maxY - minY}">`
     ];
     const drawOrder = [...boxes].sort((a, b) => Number(isGround(b)) - Number(isGround(a)));
-    const blind = boxes.some((w) => !isGround(w)) && !description.wiring.some(isInteractive) && !description.wiring.some(hasCapabilityEvidence);
+    const blind = description.introspected !== true && boxes.some((w) => !isGround(w)) && !description.wiring.some(isInteractive) && !description.wiring.some(hasCapabilityEvidence);
     const note = blind ? "no record carries affordance evidence (on, href, contentEditable, " + "a two-way binding, or an interactive/editable assertion), and none " + "shows the producer can see wiring at all (no handler, assertion, " + 'or provenance arrow anywhere) — "nothing here is actionable" is ' + "NOT established; a producer that cannot introspect handlers " + "should assert `interactive`/`editable` per record (see README)" : undefined;
     const boxGeometry = boxes.map((b) => geometry.get(b));
     for (const w of drawOrder) {
@@ -535,9 +561,13 @@
       if (showIndex || w.ref != null || inLegend) {
         const shown = w.ref != null ? String(w.ref) : String(index);
         const indexX = toggle ? x - 3 : x + width - 2;
-        parts.push(`<rect x="${indexX - shown.length * 5 - 1}" y="${y + 1}" ` + `width="${shown.length * 5 + 2}" height="8" fill="white" ` + `opacity="0.85" data-index-backdrop="true"/>`, `<text x="${indexX}" y="${y + 8}" font-size="8" ` + `text-anchor="end" font-family="monospace" fill="black" ` + `opacity="0.8">${esc(shown)}</text>`);
+        if (refStyle === "pill") {
+          parts.push(`<rect x="${indexX - shown.length * 5 - 2}" y="${y + 1}" ` + `width="${shown.length * 5 + 3}" height="9" rx="2" ` + `fill="#0f172a" data-index-backdrop="true"/>`, `<text x="${indexX - 1}" y="${y + 8}" font-size="8" ` + `text-anchor="end" font-family="monospace" font-weight="bold" ` + `fill="white">${esc(shown)}</text>`);
+        } else {
+          parts.push(`<rect x="${indexX - shown.length * 5 - 1}" y="${y + 1}" ` + `width="${shown.length * 5 + 2}" height="8" fill="white" ` + `opacity="0.85" data-index-backdrop="true"/>`, `<text x="${indexX}" y="${y + 8}" font-size="8" ` + `text-anchor="end" font-family="monospace" fill="black" ` + `opacity="0.8">${esc(shown)}</text>`);
+        }
       }
-      if (decorate != null) {
+      if (decorate != null && !overflow) {
         decorate({
           record: w,
           index,
@@ -551,6 +581,9 @@
       }
       parts.push("</g>");
     }
+    if (overflow) {
+      return emptyMap("nothing drawn: the map's extent overflows a finite number (a " + "coordinate, size or pad near Number.MAX_VALUE); the legend still " + "carries every record's facts");
+    }
     const footerExtra = legendNote && legend.length > 0 ? 14 : 0;
     if (footerExtra > 0) {
       parts.push(`<text x="${minX + pad}" y="${maxY + 10}" font-size="8" ` + `font-family="monospace" fill="currentColor" opacity="0.75">` + `${legend.length} element${legend.length === 1 ? "" : "s"} with ` + `details in legend — match by stamped number</text>`);
@@ -570,23 +603,10 @@
   };
 
   // src/floorplan-records.ts
-  function neutralizeArrows2(s) {
-    return s.replaceAll("⟷", "<->").replaceAll("⟵", "<-");
-  }
   var PAGE_TEXT_FIELDS = ["label", "placeholder", "text", "value"];
   function isPureLayout(n) {
     return !!n.children?.length && !n.label && !n.text && n.value === undefined && !n.href && !n.placeholder && !n.contrastFail && !n.interactive && !n.ownBg && !n.ownBorder;
   }
-  function refPill(ctx) {
-    const ref = ctx.record.ref;
-    if (ref == null)
-      return;
-    const shown = String(ref).replace(/[&<>"]/g, "");
-    const toggle = ctx.record.type === "checkbox" || ctx.record.type === "radio";
-    const right = toggle ? ctx.x - 3 : ctx.x + ctx.width - 2;
-    const w = shown.length * 5 + 3;
-    ctx.emit(`<rect x="${right - w + 1}" y="${ctx.y + 1}" width="${w}" height="9" rx="2" fill="#0f172a" opacity="0.9"/>` + `<text x="${right}" y="${ctx.y + 8.5}" text-anchor="end" font-family="ui-monospace,Menlo,monospace" font-size="8" font-weight="bold" fill="#ffffff">${shown}</text>`);
-  }
   var STRUCTURAL_TAGS = new Set([
     "main",
     "nav",
@@ -2045,14 +2065,18 @@
     const bannerSvg = (width) => banner ? `<rect x="0" y="0" width="${width}" height="${BANNER_H}" fill="#7f1d1d"/>` + `<text x="${PAD}" y="17" font-family="ui-monospace,Menlo,monospace" font-size="11" font-weight="bold" fill="#fee2e2">${esc(banner)}</text>` : "";
     if (geometric) {
       const within = fullPage ? undefined : { x: window.scrollX, y: window.scrollY, width: Math.max(1, window.innerWidth), height: Math.max(1, window.innerHeight) };
-      const result = schematic({ wiring: records }, { within, targetSize: 0, pad: PAD, maxCaption: 200, decorate: refPill });
+      const result = schematic({ wiring: records, ...map.source === "tosi-agent" ? {} : { introspected: true } }, { within, targetSize: 0, pad: PAD, maxCaption: 200, refStyle: "pill" });
       const w = Number(/\bwidth="([\d.]+)"/.exec(result.svg)?.[1] || 0);
       const h = Number(/\bheight="([\d.]+)"/.exec(result.svg)?.[1] || 0);
       if (w > 0 && h > 0) {
-        const width = Math.ceil(w);
+        const bannerCtx = banner ? document.createElement("canvas").getContext("2d") : null;
+        if (bannerCtx)
+          bannerCtx.font = "bold 11px ui-monospace, Menlo, monospace";
+        const bannerW = bannerCtx ? Math.ceil(bannerCtx.measureText(banner).width) + PAD * 2 : 0;
+        const width = Math.max(Math.ceil(w), bannerW);
         const height = Math.ceil(h + BANNER_H);
         const svg = `<?xml version="1.0" encoding="UTF-8"?>` + `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">` + `<rect width="${width}" height="${height}" fill="#ffffff"/>` + bannerSvg(width) + result.svg.replace("<svg ", `<svg x="0" y="${BANNER_H}" `) + `</svg>`;
-        return { svg, width, height, layout: "geometric", boundsCoverage };
+        return { svg, width, height, layout: "geometric", boundsCoverage, ...result.note ? { note: result.note } : {} };
       }
     }
     const ROW = 22;
@@ -2070,7 +2094,7 @@
             if (typeof v === "string")
               bound.push(`${k}: ${v}`);
           }
-          if (w.text && /[⟷⟵]/.test(w.text))
+          if (typeof w.text === "string" && PROVENANCE_TOKENS.some((t) => w.text.includes(t)))
             bound.push(String(w.text));
           const handlers = w.on ? Object.entries(w.on).map(([ev, path]) => `${ev} → ${Array.isArray(path) ? path.join(",") : path}`) : [];
           return {
@@ -2193,7 +2217,7 @@
   }
   async function buildSchematicResponse(map, payload2, banner) {
     const canvases = collectCanvasThumbnails();
-    const { svg, width, height, layout, boundsCoverage } = renderMapSchematic(map, canvases, banner, payload2?.fullPage === true, payload2?.layout || "auto");
+    const { svg, width, height, layout, boundsCoverage, note } = renderMapSchematic(map, canvases, banner, payload2?.fullPage === true, payload2?.layout || "auto");
     const format = payload2?.format || "png";
     const raster = await rasterizeSchematic(svg, width, height, payload2?.scale || 1, {
       maxWidth: payload2?.maxWidth,
@@ -2209,6 +2233,7 @@
       source: "schematic",
       layout,
       boundsCoverage,
+      ...note ? { note } : {},
       legend: buildLegend(map),
       canvasesRendered: canvases.filter((c) => c.image).length,
       map
@@ -2492,10 +2517,9 @@
           h: Math.round(r.height)
         };
       } catch {}
-      for (const k of PAGE_TEXT_FIELDS) {
-        if (typeof node[k] === "string" && /[⟷⟵]/.test(node[k]))
-          node[k] = neutralizeArrows2(node[k]);
-      }
+      for (const k of PAGE_TEXT_FIELDS)
+        if (typeof node[k] === "string")
+          node[k] = neutralizeProvenance(node[k]);
       return node;
     };
     const walk = (el) => {

package/bin/launcher-args.mjs

@@ -0,0 +1,35 @@
+/**
+ * The launcher's own flags, and `--flag=value` support for the ones that take a value.
+ *
+ * The launcher read flags with `args.indexOf('--token')`, so `--token=secret` and a typo like
+ * `--tokn secret` both started a server with NO token, silently (1.13.0 review). With the #815 gate
+ * that mostly fails closed for other machines, but a tunnel on this machine connects from loopback,
+ * and the README sends tunnel users to `--token`. So: accept the `=` form, and say when a flag is not
+ * one the launcher knows.
+ */
+export const VALUE_FLAGS = [
+  '--port', '--https-port', '--token', '--name', '--port-file',
+  '--headless-url', '--snapshots-dir', '--docs-dir',
+]
+export const BOOLEAN_FLAGS = [
+  '--app', '--server', '--headless', '--ci', '--http', '--https', '--both', '--force', '-f',
+  '--wait-ready', '--private', '--setup-mcp', '--setup-mcp-check', '--setup-mcp-remove',
+  '--help', '-h',
+]
+
+/** `--token=x` becomes `--token x`, for the value flags only. Returns the unknown flags it saw. */
+export function normalizeLauncherArgs(args) {
+  const out = []
+  const unknown = []
+  for (const a of args) {
+    const eq = a.indexOf('=')
+    const flag = a.startsWith('-') && eq > 0 ? a.slice(0, eq) : a
+    if (flag !== a && VALUE_FLAGS.includes(flag)) {
+      out.push(flag, a.slice(eq + 1))
+      continue
+    }
+    if (a.startsWith('-') && !VALUE_FLAGS.includes(a) && !BOOLEAN_FLAGS.includes(a)) unknown.push(a)
+    out.push(a)
+  }
+  return { args: out, unknown }
+}

package/bin/mcp-locate.mjs

@@ -31,3 +31,20 @@ export function mcpServerCommand(serverPath, root = PACKAGE_ROOT) {
   }
   return { command: 'node', args: [serverPath] }
 }
+
+/**
+ * Why an existing `haltija` MCP entry can no longer start, or null when it looks runnable.
+ *
+ * Before 1.13.0 setup wrote `node …/apps/mcp/build/index.js`, a path the package no longer has, and
+ * `--check` reported such an entry as configured while re-running setup said "already configured",
+ * so nothing short of hand-editing the config could fix it. An entry that names a server file which
+ * is not there is stale, whatever else it says; one that runs a command (`npx …`) is left alone.
+ */
+export function staleMcpEntry(entry) {
+  const args = Array.isArray(entry?.args) ? entry.args : []
+  const script = args.find((a) => typeof a === 'string' && /\.(m?js|ts)$/.test(a))
+  if (!script) return null
+  if (/[\\/]apps[\\/]mcp[\\/]build[\\/]/.test(script)) return `it runs ${script}, the pre-1.13 server location`
+  if (!existsSync(script)) return `it runs ${script}, which does not exist`
+  return null
+}

package/bin/mcp-setup.mjs

@@ -3,18 +3,18 @@
  * haltija-mcp-setup - Configure Claude Code to use Haltija
  *
  * Usage:
- *   npx haltija-mcp-setup          # Create .mcp.json in current directory
- *   npx haltija-mcp-setup --global # Add to user's Claude Code config
- *   npx haltija-mcp-setup --check  # Check if Haltija MCP is configured
- *   npx haltija-mcp-setup --help   # Show help
+ *   npx -p haltija haltija-mcp-setup          # Create .mcp.json in current directory
+ *   npx -p haltija haltija-mcp-setup --global # Add to user's Claude Code config
+ *   npx -p haltija haltija-mcp-setup --check  # Check if Haltija MCP is configured
+ *   npx -p haltija haltija-mcp-setup --help   # Show help
  */
 
 import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs'
 import { homedir } from 'os'
 import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
-import { execSync } from 'child_process'
-import { mcpServerPath, mcpServerCommand } from './mcp-locate.mjs'
+import { execFileSync } from 'child_process'
+import { mcpServerPath, mcpServerCommand, staleMcpEntry } from './mcp-locate.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const args = process.argv.slice(2)
@@ -31,11 +31,11 @@ if (args.includes('--help') || args.includes('-h')) {
 ${bold('haltija-mcp-setup')} - Configure Claude Code to use Haltija
 
 ${bold('Usage:')}
-  npx haltija-mcp-setup          Create .mcp.json in current directory (recommended)
-  npx haltija-mcp-setup --global Add to user's global Claude Code config
-  npx haltija-mcp-setup --check  Check current MCP configuration status
-  npx haltija-mcp-setup --remove Remove Haltija from MCP configuration
-  npx haltija-mcp-setup --help   Show this help
+  npx -p haltija haltija-mcp-setup          Create .mcp.json in current directory (recommended)
+  npx -p haltija haltija-mcp-setup --global Add to user's global Claude Code config
+  npx -p haltija haltija-mcp-setup --check  Check current MCP configuration status
+  npx -p haltija haltija-mcp-setup --remove Remove Haltija from MCP configuration
+  npx -p haltija haltija-mcp-setup --help   Show this help
 
 ${bold('What this does:')}
   Configures Claude Code to connect to the Haltija server, giving Claude
@@ -84,7 +84,11 @@ function checkConfig() {
   if (existsSync(projectMcpPath)) {
     try {
       const config = JSON.parse(readFileSync(projectMcpPath, 'utf8'))
-      if (config.mcpServers?.haltija) {
+      const stale = config.mcpServers?.haltija && staleMcpEntry(config.mcpServers.haltija)
+      if (stale) {
+        console.log(red('✗') + ` Project .mcp.json has a stale Haltija entry: ${stale}`)
+        console.log(dim('  Run setup again to replace it: npx -p haltija haltija-mcp-setup'))
+      } else if (config.mcpServers?.haltija) {
         console.log(green('✓') + ` Project .mcp.json has Haltija configured`)
         console.log(dim(`  Path: ${projectMcpPath}`))
       } else {
@@ -108,9 +112,10 @@ function checkConfig() {
   }
 
   // Check if Haltija server is running
+  const port = process.env.HALTIJA_PORT || '8700'
   try {
-    execSync('curl -s http://localhost:8700/status', { encoding: 'utf8', timeout: 2000 })
-    console.log(green('✓') + ' Haltija server is running on port 8700')
+    execFileSync('curl', ['-sf', `http://localhost:${port}/status`], { encoding: 'utf8', timeout: 2000 })
+    console.log(green('✓') + ` Haltija server is running on port ${port}`)
   } catch {
     console.log(yellow('○') + ' Haltija server not running')
     console.log(dim('  Start with: bunx haltija'))
@@ -145,7 +150,10 @@ function setupProjectConfig() {
   }
 
   // Check if already configured
-  if (config.mcpServers.haltija) {
+  const stale = config.mcpServers.haltija && staleMcpEntry(config.mcpServers.haltija)
+  if (stale) {
+    console.log(yellow('Replacing a stale Haltija entry in .mcp.json:') + ` ${stale}`)
+  } else if (config.mcpServers.haltija) {
     console.log(yellow('Haltija is already configured in .mcp.json'))
     console.log(dim('Use --remove to remove it, or delete .mcp.json manually'))
     process.exit(0)
@@ -178,7 +186,9 @@ function setupGlobalConfig() {
   const addCommand = `claude mcp add --scope user haltija -- ${[command, ...commandArgs].map((a) => JSON.stringify(a)).join(' ')}`
   // Try using claude CLI first
   try {
-    execSync(addCommand, {
+    // An argv, not a shell string: the install path is in the args, and a shell would run any
+    // `$()` or backtick in it.
+    execFileSync('claude', ['mcp', 'add', '--scope', 'user', 'haltija', '--', command, ...commandArgs], {
       encoding: 'utf8',
       stdio: 'inherit'
     })

package/bin/server-list.mjs

@@ -1,6 +1,11 @@
 /** ⚠️  AUTO-GENERATED FROM src/server-list.ts — DO NOT EDIT. Run: bun run build */
+// src/ports.ts
+var DEFAULT_HTTP_PORT = 8700;
+var DEFAULT_HTTPS_PORT = 8701;
+var PUBLIC_PORTS = [DEFAULT_HTTP_PORT, DEFAULT_HTTPS_PORT];
+
 // src/server-list.ts
-function collectCandidates(instances, resolvedPort, defaults = [8700, 8701]) {
+function collectCandidates(instances, resolvedPort, defaults = [...PUBLIC_PORTS]) {
   const byPort = new Map;
   for (const e of instances) {
     byPort.set(String(e.port), { port: String(e.port), name: e.name, cwd: e.cwd ?? null });

package/bin/tosijs-dev.mjs

@@ -18,7 +18,7 @@ import { homedir, platform, tmpdir } from 'os'
 import { fileURLToPath } from 'url'
 import { dirname, join } from 'path'
 import { stalePrivateEntries, pidIsAlive } from './private-state.mjs'
-import { mcpServerPath, mcpServerCommand } from './mcp-locate.mjs'
+import { mcpServerPath, mcpServerCommand, staleMcpEntry } from './mcp-locate.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const serverPath = join(__dirname, '../dist/server.js')
@@ -171,7 +171,11 @@ function checkMcpConfig() {
     if (existsSync(configPath)) {
       try {
         const config = JSON.parse(readFileSync(configPath, 'utf8'))
-        if (config.mcpServers?.haltija) {
+        const stale = config.mcpServers?.haltija && staleMcpEntry(config.mcpServers.haltija)
+        if (stale) {
+          console.log(red('✗') + ` Haltija's Claude Desktop entry is stale: ${stale}`)
+          console.log(dim(`  Run: haltija --setup-mcp (it replaces the entry)`))
+        } else if (config.mcpServers?.haltija) {
           console.log(green('✓') + ' Haltija is configured in Claude Desktop')
           console.log(dim(`  Command: ${config.mcpServers.haltija.command} ${config.mcpServers.haltija.args?.join(' ') || ''}`))
         } else {
@@ -248,7 +252,10 @@ function setupMcp() {
   }
   
   // Check if already configured
-  if (config.mcpServers.haltija) {
+  const stale = config.mcpServers.haltija && staleMcpEntry(config.mcpServers.haltija)
+  if (stale) {
+    console.log(yellow('Replacing a stale Haltija entry:') + ` ${stale}`)
+  } else if (config.mcpServers.haltija) {
     console.log(green('✓') + ' Haltija is already configured in Claude Desktop')
     console.log(dim(`  Config: ${configPath}`))
     console.log('')
@@ -310,6 +317,7 @@ function removeMcp() {
 // ============================================
 
 import { isSubcommand, runSubcommand } from './cli-subcommand.mjs'
+import { normalizeLauncherArgs } from './launcher-args.mjs'
 
 // Check if first positional arg is a subcommand (not a flag, not a port number)
 const firstNonFlag = args.find(a => !a.startsWith('-'))
@@ -349,6 +357,16 @@ if (args.includes('--setup-mcp-remove')) {
   process.exit(0)
 }
 
+// Launcher mode from here on (subcommands took their own flags above). `--flag=value` is split
+// in place, so every `args.indexOf('--flag')` below sees it; an unknown flag is said out loud.
+{
+  const { args: normalized, unknown } = normalizeLauncherArgs(args)
+  args.splice(0, args.length, ...normalized)
+  for (const flag of unknown) {
+    console.error(yellow(`[haltija] unknown option ${flag} is ignored (see haltija --help)`))
+  }
+}
+
 // Set up environment from args
 const env = { ...process.env }
 

package/bin/version.mjs

@@ -3,4 +3,4 @@
  * ⚠️  To change the version, update package.json and run: bun run build
  */
 
-export const HJ_VERSION = '1.13.0-beta.5'
+export const HJ_VERSION = '1.13.1'