@rubytech/create-sitedesk-code 0.1.524 → 0.1.526

package/payload/platform/scripts/check-no-task-id-leaks.mjs

@@ -24,9 +24,10 @@
 // rule covers test titles, and test bodies that assert on citations are
 // equivalent to titles for this gate's purpose.
 
-import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
 import { dirname, join, relative, sep, basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { findCitations } from './lib/task-id-citation.mjs'
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
 // REPO_ROOT is overridable so the `.test.sh` self-test can point the gate at a
@@ -40,7 +41,6 @@ const SCAN_ROOTS = [
   join(REPO_ROOT, 'platform', 'plugins'),
   join(REPO_ROOT, 'platform', 'ui', 'server'),
   join(REPO_ROOT, 'platform', 'ui', 'app'),
-  join(REPO_ROOT, 'packages', 'create-maxy', 'src'),
 ]
 
 const ALLOWED_EXTS = new Set(['.sh', '.ts', '.tsx', '.js', '.mjs', '.cjs'])
@@ -52,27 +52,70 @@ const TASK_ID_RE = /\(Task \d+\)/
 // Markdown mode. Unlike code files — where a citation is legal in a comment and
 // only the parenthetical operator-visible form is rejected — a shipped `.md`
 // loads into a client-facing agent's context wholesale, so ANY citation form
-// leaks. Catches `Task NNN`, `(Task NNN)`, `Tasks NNN`, `since Task NNN`. It
-// deliberately does NOT match bare `#NNN`: every `#NNN` in the corpus is a hex
-// colour and there is no signal to separate `#732`-issue from `#732`-hex.
-// Two alternatives:
-//   `\bTasks?[\s-]+\d{2,4}` — capital-T, any separator: `Task 732`, `(Task 732)`,
-//     `Tasks 12`, the hyphenated `Pre-Task-748` / `post-Task-904` forms.
-//   `\btasks?\s+\d{2,4}` — lowercase but SPACE-separated only: catches prose
-//     citations like "before task 127", while a lowercase HYPHENATED `task-537`
-//     stays exempt because that shape is a branch slug or a `.tasks/<n>-…-task-NNN.md`
-//     file-path reference (file paths are out of this gate's scope). The 2-digit
-//     floor keeps single-digit domain counts ("task 1 of 3") out.
-const MD_TASK_ID_RE = /\bTasks?[\s-]+\d{2,4}|\btasks?\s+\d{2,4}/
+// leaks. The regex and the paragraph-aware scan live in
+// `lib/task-id-citation.mjs`, shared with the bundle's payload audit so the two
+// surfaces cannot disagree about what a citation is.
+//
+// The roots are what the client payload CARRIES, not a list somebody maintains.
+// `bundle.js` copies all of `platform/` and all of `premium-plugins/` into the
+// payload, so those two trees are the roots. Naming `platform/plugins` and
+// `platform/templates` instead is what let `platform/docs` ship 296 citations
+// to every install without this gate ever looking at it.
 const MD_SCAN_ROOTS = [
-  join(REPO_ROOT, 'platform', 'plugins'),
-  join(REPO_ROOT, 'platform', 'templates'),
-  // Premium bundles are copied verbatim into the client payload
-  // (`payload/premium-plugins/<bundle>/`), so their shipped markdown loads into
-  // the client agent the same as core plugins — any citation form leaks.
+  join(REPO_ROOT, 'platform'),
   join(REPO_ROOT, 'premium-plugins'),
 ]
 
+// The trees under the roots above that `bundle.js` keeps OUT of the payload,
+// mirroring its filter. A path here is unscanned because it does not ship; a
+// path not here is scanned because it does. Each entry names the exclusion in
+// `bundle.js` that makes it true, so the two files can be checked against each
+// other by reading them. `.docs/` and `.tasks/` need no entry: they sit outside
+// both roots and stay citation-rich.
+//
+// This list is a hand-kept mirror, and that is the one place the two surfaces
+// can still drift. An exclusion added to `bundle.js` and forgotten here makes
+// the gate scan a tree that does not ship, which is noisy but fail-safe. An
+// exclusion REMOVED from `bundle.js` and forgotten here is the dangerous
+// direction: a tree starts shipping and stops being scanned. The payload audit
+// in `bundle.js` is what catches that one, because it consults neither list.
+const MD_NOT_SHIPPED = [
+  // bundle.js `src.startsWith(UI_DIR)` — ui ships as a compiled bundle, not source.
+  join(REPO_ROOT, 'platform', 'ui'),
+  // bundle.js `src.startsWith(DOCS_DIR)` — sprint plans and specs are
+  // development records and do not ship.
+  join(REPO_ROOT, 'platform', 'docs'),
+  // bundle.js `src.startsWith(DOT_DOCS_DIR)` — same, for the dotted twin. The
+  // widened scan is what found this one: a `platform/*/` census does not match
+  // a dotdir, so `platform/.docs` shipped unseen by both the old roots and the
+  // measurement that motivated the change.
+  join(REPO_ROOT, 'platform', '.docs'),
+  // bundle.js `src.includes("/config/accounts/")`, `"/data/accounts/"` and
+  // `"/data/uploads/"` — live account data never ships. An account directory
+  // holds real markdown (`SCHEMA.md`, `AGENTS.md`), so without these three the
+  // gate would read a client's own files and could refuse a commit over a
+  // citation in something no payload carries.
+  join(REPO_ROOT, 'platform', 'config', 'accounts'),
+  join(REPO_ROOT, 'platform', 'data', 'accounts'),
+  join(REPO_ROOT, 'platform', 'data', 'uploads'),
+]
+
+function isNotShipped(file) {
+  return MD_NOT_SHIPPED.some((dir) => file === dir || file.startsWith(dir + sep))
+}
+
+// Every root names itself on every run. Before this, a tree outside the roots
+// produced no output at all, so nothing distinguished "scanned and clean" from
+// "never looked at", and a root that stopped existing was swallowed by walk()'s
+// bare catch — which is exactly how the archived `packages/create-maxy`
+// installer tree sat in this list for months pointing at a directory that does
+// not exist, proving nothing. A missing root logs rather than fails, because
+// the `.test.sh` fixture tree deliberately creates only some of them.
+function logRoot(kind, root, files) {
+  const exists = existsSync(root) ? 'yes' : 'no'
+  console.log(`[task-id-leak] root=${relative(REPO_ROOT, root)} kind=${kind} exists=${exists} files=${files}`)
+}
+
 function isCommentLine(line) {
   const trimmed = line.replace(/^\s+/, '')
   if (trimmed.startsWith('#')) return true
@@ -115,6 +158,7 @@ function* walk(root) {
 const leaks = []
 
 for (const root of SCAN_ROOTS) {
+  let scanned = 0
   for (const file of walk(root)) {
     if (!shouldScanFile(file)) continue
     let content
@@ -123,6 +167,7 @@ for (const root of SCAN_ROOTS) {
     } catch {
       continue
     }
+    scanned++
     const lines = content.split('\n')
     for (let i = 0; i < lines.length; i++) {
       const line = lines[i]
@@ -131,59 +176,30 @@ for (const root of SCAN_ROOTS) {
       leaks.push({ file: relative(REPO_ROOT, file), line: i + 1, content: line.trim() })
     }
   }
+  logRoot('code', root, scanned)
 }
 
-// Markdown scan — shipped operator-loadable docs. Reuses `walk` (which already
-// skips node_modules/dist/build/.next/payload/__tests__) and matches against
-// MD_TASK_ID_RE with no comment skip: the whole doc is agent content.
-// .docs/ and .tasks/ are not under MD_SCAN_ROOTS, so they stay citation-rich.
-//
-// Scanned per paragraph, not per line: a markdown soft-wrap can split a single
-// citation across two source lines (`... (Task\n659) ...`), which renders as
-// `(Task 659)` but matches neither line in isolation. Consecutive non-blank
-// lines are joined with a space (the soft-break a renderer would insert) and
-// scanned as one string; a blank line ends the paragraph, so the join never
-// crosses a paragraph break. Every match in the paragraph is reported, mapped
-// back to the source line where the match starts, preserving exact-line and
-// multi-citation reporting.
-const MD_TASK_ID_RE_G = new RegExp(MD_TASK_ID_RE.source, 'g')
-
-function flushParagraph(file, joined, lineStarts) {
-  if (joined === '') return
-  for (const m of joined.matchAll(MD_TASK_ID_RE_G)) {
-    let lineNo = lineStarts[0].lineNo
-    for (const ls of lineStarts) {
-      if (ls.offset <= m.index) lineNo = ls.lineNo
-    }
-    leaks.push({ file: relative(REPO_ROOT, file), line: lineNo, content: m[0] })
-  }
-}
-
+// Markdown scan — every `.md` the payload carries. Reuses `walk` (which already
+// skips node_modules/dist/build/.next/payload/__tests__), drops the trees
+// `bundle.js` excludes from the payload, and applies no comment skip: the whole
+// doc is agent content.
 for (const root of MD_SCAN_ROOTS) {
+  let scanned = 0
   for (const file of walk(root)) {
     if (!file.endsWith('.md')) continue
+    if (isNotShipped(file)) continue
     let content
     try {
       content = readFileSync(file, 'utf-8')
     } catch {
       continue
     }
-    const lines = content.split('\n')
-    let joined = ''
-    let lineStarts = []
-    for (let i = 0; i < lines.length; i++) {
-      if (lines[i].trim() === '') {
-        flushParagraph(file, joined, lineStarts)
-        joined = ''
-        lineStarts = []
-        continue
-      }
-      if (joined !== '') joined += ' '
-      lineStarts.push({ offset: joined.length, lineNo: i + 1 })
-      joined += lines[i]
+    scanned++
+    for (const c of findCitations(content)) {
+      leaks.push({ file: relative(REPO_ROOT, file), line: c.line, content: c.match })
     }
-    flushParagraph(file, joined, lineStarts)
   }
+  logRoot('md', root, scanned)
 }
 
 if (leaks.length > 0) {
@@ -194,8 +210,10 @@ if (leaks.length > 0) {
   console.error('')
   console.error('Code files: citations belong in inline comments only, never in operator-visible')
   console.error('strings (stderr/stdout, logs, systemd --description=, error messages, console.*).')
-  console.error('Shipped markdown (platform/plugins, platform/templates, premium-plugins): no task')
-  console.error('citation in any form — the whole doc loads into a client-facing agent. Dev docs')
-  console.error('(.docs/, .tasks/) are exempt and keep their citations.')
+  console.error('Shipped markdown (everything under platform/ and premium-plugins/ that the payload')
+  console.error('carries): no task citation in any form — the whole doc loads into a client-facing')
+  console.error('agent. The trees that do NOT ship are exempt, and MD_NOT_SHIPPED in this file is')
+  console.error('the list of them; the dev docs (.docs/, .tasks/) sit outside the roots entirely')
+  console.error('and keep their citations.')
   process.exit(1)
 }

package/payload/platform/scripts/lib/canonical-tool-names.mjs

@@ -36,44 +36,61 @@ function extractFrontmatter(md) {
   return md.slice(3, end)
 }
 
-// Collect `- name: <x>` entries under a bare `tools:` block and under a bare
-// `hidden:` block. Both contribute names a specialist may list in its `tools:`
+// Collect the declared entries under a bare `tools:` block and a bare `hidden:`
+// block. Both contribute names a specialist may list in its `tools:`
 // frontmatter, so both belong to the live set. Task 1998 gave the hidden block
-// the same name+riskClass shape as tools, so the two branches now read alike;
-// this parser stays separate from tool-surface.ts on purpose, so a drift in one
+// the same name+riskClass shape as tools, so the two branches read alike; this
+// parser stays separate from tool-surface.ts on purpose, so a drift in one
 // shows up as a diff rather than as agreement between a parser and itself.
-function parseToolNames(frontmatter) {
+//
+// Field values are returned as raw trimmed strings, or absent when the manifest
+// has no such line. Judging them is the caller's job: the generator wants only
+// names, and the gate wants to decide whether a value is one the session
+// manager would accept.
+export function parseToolEntries(frontmatter) {
   const lines = frontmatter.split('\n')
-  const names = []
+  const entries = []
   let mode = null // 'tools' | 'hidden' | null
+  let current = null
+  const flush = () => { if (current) { entries.push(current); current = null } }
   for (const line of lines) {
     if (/^tools\s*:/.test(line)) {
+      flush()
       mode = /^tools\s*:\s*$/.test(line) ? 'tools' : null
       continue
     }
     if (/^hidden\s*:/.test(line)) {
+      flush()
       mode = /^hidden\s*:\s*$/.test(line) ? 'hidden' : null
       continue
     }
-    if (/^\S/.test(line) && line.trim() !== '') { mode = null; continue }
-    if (mode === 'tools') {
-      const m = line.match(/^\s+-\s+name:\s*(.+?)\s*$/)
-      if (m) names.push(m[1])
-    } else if (mode === 'hidden') {
-      const m = line.match(/^\s+-\s+name:\s*(.+?)\s*$/)
-      if (m) names.push(m[1])
-    }
+    if (/^\S/.test(line) && line.trim() !== '') { flush(); mode = null; continue }
+    if (mode === null) continue
+    const name = line.match(/^\s+-\s+name:\s*(.+?)\s*$/)
+    if (name) { flush(); current = { block: mode, name: name[1] }; continue }
+    // A list item that does not lead with `name:` is malformed — a tools entry
+    // with no name, or a hidden entry written as a bare string. loadToolSurface
+    // throws on both, so the entry is recorded without a name and reported by
+    // validateToolEntries rather than silently dropped.
+    if (/^\s+-\s+/.test(line)) { flush(); current = { block: mode }; continue }
+    if (current === null) continue
+    const pub = line.match(/^\s+publicAllowlist:\s*(.+?)\s*$/)
+    if (pub) { current.publicAllowlist = pub[1].trim(); continue }
+    const adm = line.match(/^\s+adminAllowlist:\s*(.+?)\s*$/)
+    if (adm) { current.adminAllowlist = adm[1].trim(); continue }
+    const risk = line.match(/^\s+riskClass:\s*(.+?)\s*$/)
+    if (risk) { current.riskClass = risk[1].trim(); continue }
   }
-  return names
+  flush()
+  return entries
 }
 
-/** Returns { plugins, names } — `plugins` is the sorted list of maxy plugin
- *  directory basenames that declare a tool surface; `names` is the sorted list
- *  of canonical long-prefix tool names across all of them. */
-export function computeCanonicalToolNames(pluginsRoot = PLATFORM_PLUGINS_ROOT) {
-  const plugins = []
-  const names = new Set()
-  if (!existsSync(pluginsRoot)) return { plugins, names: [] }
+/** Walk every plugin directory that has a PLUGIN.md with a parseable
+ *  frontmatter and at least one declared entry. Shared by the name derivation
+ *  and the field validation so the two can never disagree about which
+ *  manifests are in scope. */
+function* walkPluginManifests(pluginsRoot) {
+  if (!existsSync(pluginsRoot)) return
   for (const entry of readdirSync(pluginsRoot).sort()) {
     if (entry.startsWith('.')) continue
     const dir = join(pluginsRoot, entry)
@@ -82,10 +99,97 @@ export function computeCanonicalToolNames(pluginsRoot = PLATFORM_PLUGINS_ROOT) {
     if (!existsSync(manifest)) continue
     const fm = extractFrontmatter(readFileSync(manifest, 'utf-8'))
     if (fm === null) continue
-    const toolNames = parseToolNames(fm)
-    if (toolNames.length === 0) continue
-    plugins.push(entry)
-    for (const t of toolNames) names.add(canonicalToolName(entry, t))
+    const entries = parseToolEntries(fm)
+    if (entries.length === 0) continue
+    yield { plugin: entry, entries }
+  }
+}
+
+/** Returns { plugins, names } — `plugins` is the sorted list of maxy plugin
+ *  directory basenames that declare a tool surface; `names` is the sorted list
+ *  of canonical long-prefix tool names across all of them. */
+export function computeCanonicalToolNames(pluginsRoot = PLATFORM_PLUGINS_ROOT) {
+  const plugins = []
+  const names = new Set()
+  for (const { plugin, entries } of walkPluginManifests(pluginsRoot)) {
+    plugins.push(plugin)
+    // A malformed entry has no name to derive a canonical name from. The gate
+    // reports it; this list stays exactly what it was before that shape was
+    // recorded, so the generated artifact does not move.
+    for (const e of entries) {
+      if (e.name !== undefined) names.add(canonicalToolName(plugin, e.name))
+    }
   }
   return { plugins: plugins.sort(), names: Array.from(names).sort() }
 }
+
+/** Every declared entry across every plugin, stamped with its plugin. The
+ *  build gate validates these against the session manager's RISK_CLASSES; see
+ *  validateToolEntries. */
+export function computeToolEntries(pluginsRoot = PLATFORM_PLUGINS_ROOT) {
+  const out = []
+  for (const { plugin, entries } of walkPluginManifests(pluginsRoot)) {
+    for (const e of entries) out.push({ plugin, ...e })
+  }
+  return out
+}
+
+// The gate validates risk classes against the session manager's own list rather
+// than a copy, so the two cannot drift. The gate is plain .mjs run by bare node
+// and the declaration is TypeScript, so it is read as text.
+const RISK_CLASSES_RE = /export const RISK_CLASSES:[^=]*=\s*\[([^\]]*)\]/
+
+/** The valid risk classes, read from tool-surface.ts. Throws rather than
+ *  returning a fallback: a gate that validated against a hardcoded copy could
+ *  drift from the parser it protects, and one that validated against an empty
+ *  set would accept every value. */
+export function readRiskClasses(tsPath) {
+  let src
+  try {
+    src = readFileSync(tsPath, 'utf-8')
+  } catch {
+    throw new Error(`cannot read ${tsPath}, which declares RISK_CLASSES — refusing to validate risk classes without it`)
+  }
+  const m = src.match(RISK_CLASSES_RE)
+  if (m === null) {
+    throw new Error(`no 'export const RISK_CLASSES ... = [...]' declaration in ${tsPath} — refusing to validate risk classes against a set that cannot be read`)
+  }
+  const classes = m[1]
+    .split(',')
+    .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+    .filter((s) => s.length > 0)
+  if (classes.length === 0) {
+    throw new Error(`RISK_CLASSES in ${tsPath} parsed to an empty set — refusing to validate against it`)
+  }
+  return classes
+}
+
+/** Judge parsed entries against the rules loadToolSurface enforces. A tools
+ *  entry must declare both allowlist flags as YAML booleans and a riskClass in
+ *  the set; a hidden entry must declare a riskClass and carries no allowlist
+ *  flags at all. Missing and invalid are both violations, because
+ *  loadToolSurface throws on both. Returns every violation rather than the
+ *  first: an author who mistyped one field has often mistyped its sibling. */
+export function validateToolEntries(entries, riskClasses) {
+  const valid = new Set(riskClasses)
+  const list = riskClasses.join('|')
+  const violations = []
+  for (const e of entries) {
+    if (typeof e.name !== 'string' || e.name.length === 0) {
+      violations.push({ plugin: e.plugin, name: '<unnamed>', message: 'tool entry has no name' })
+      continue
+    }
+    const add = (message) => violations.push({ plugin: e.plugin, name: e.name, message })
+    const subject = e.block === 'hidden' ? 'every hidden tool' : 'every tool'
+    if (e.block === 'tools') {
+      for (const field of ['publicAllowlist', 'adminAllowlist']) {
+        const v = e[field]
+        if (v === undefined) add(`${subject} must declare ${field}: <true|false>`)
+        else if (v !== 'true' && v !== 'false') add(`${field} must be true or false, got ${JSON.stringify(v)}`)
+      }
+    }
+    if (e.riskClass === undefined) add(`${subject} must declare riskClass: <${list}>`)
+    else if (!valid.has(e.riskClass)) add(`riskClass must be one of ${list}, got ${JSON.stringify(e.riskClass)}`)
+  }
+  return violations
+}

package/payload/platform/scripts/lib/task-id-citation.mjs

@@ -0,0 +1,67 @@
+// Single source of truth for what counts as an internal task citation in
+// shipped markdown, and for how a markdown file is scanned for one.
+//
+// Two consumers, deliberately. `platform/scripts/check-no-task-id-leaks.mjs`
+// scans the SOURCE trees at commit time; `packages/create-maxy-code/scripts/
+// bundle.js` scans the ASSEMBLED payload at bundle time. They answer different
+// questions, "could this ship?" and "did this ship?", and a divergence between
+// two copies of the regex would let one pass what the other rejects, with the
+// payload audit failing a publish for something the commit gate allowed. The
+// regex and the scan live here so neither consumer carries its own copy.
+//
+// A shipped `.md` loads into a client-facing agent's context wholesale, so ANY
+// citation form leaks. Catches `Task NNN`, `(Task NNN)`, `Tasks NNN`,
+// `since Task NNN`. It deliberately does NOT match bare `#NNN`: every `#NNN` in
+// the corpus is a hex colour and there is no signal to separate `#732`-issue
+// from `#732`-hex.
+// Two alternatives:
+//   `\bTasks?[\s-]+\d{2,4}` — capital-T, any separator: `Task 732`, `(Task 732)`,
+//     `Tasks 12`, the hyphenated `Pre-Task-748` / `post-Task-904` forms.
+//   `\btasks?\s+\d{2,4}` — lowercase but SPACE-separated only: catches prose
+//     citations like "before task 127", while a lowercase HYPHENATED `task-537`
+//     stays exempt because that shape is a branch slug or a
+//     `.tasks/<n>-…-task-NNN.md` file-path reference (file paths are out of
+//     scope). The 2-digit floor keeps single-digit domain counts ("task 1 of
+//     3") out.
+export const MD_TASK_ID_RE = /\bTasks?[\s-]+\d{2,4}|\btasks?\s+\d{2,4}/
+
+// Scanned per paragraph, not per line: a markdown soft-wrap can split a single
+// citation across two source lines (`... (Task\n659) ...`), which renders as
+// `(Task 659)` but matches neither line in isolation. Consecutive non-blank
+// lines are joined with a space (the soft-break a renderer would insert) and
+// scanned as one string; a blank line ends the paragraph, so the join never
+// crosses a paragraph break. Every match in the paragraph is reported, mapped
+// back to the source line where the match starts, preserving exact-line and
+// multi-citation reporting.
+export function findCitations(content) {
+  const re = new RegExp(MD_TASK_ID_RE.source, 'g')
+  const found = []
+  const lines = content.split('\n')
+  let joined = ''
+  let lineStarts = []
+
+  function flush() {
+    if (joined === '') return
+    for (const m of joined.matchAll(re)) {
+      let lineNo = lineStarts[0].lineNo
+      for (const ls of lineStarts) {
+        if (ls.offset <= m.index) lineNo = ls.lineNo
+      }
+      found.push({ line: lineNo, match: m[0] })
+    }
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === '') {
+      flush()
+      joined = ''
+      lineStarts = []
+      continue
+    }
+    if (joined !== '') joined += ' '
+    lineStarts.push({ offset: joined.length, lineNo: i + 1 })
+    joined += lines[i]
+  }
+  flush()
+  return found
+}

package/payload/platform/scripts/vnc.sh

@@ -126,6 +126,45 @@ case ":$(echo "$CHROMIUM_REALPATH" | tr '/' ':'):" in
     ;;
 esac
 CHROMIUM_CONFINEMENT="non-snap"
+
+# resolve the websockify bind address from the install-time config file
+# (packages/create-maxy-code/src/index.ts writeWebsockifyBindFile). The
+# installer decides it once, from the same classifier that decided the edge
+# bind, so this script never re-derives host state and can never disagree with
+# the edge about whether the box is publicly reachable.
+#
+# Called from the `start` branch rather than at the top level, unlike the
+# Chromium resolution above: `stop`, `status` and the per-cycle `cdp-liveness`
+# probe bind nothing, so a partial install should not take them down too.
+#
+# Absent or unparseable is fatal, matching brand.json and chromium-binary.path.
+# This script and the file ship in the same payload, so absence means a
+# tampered or partial install — and both possible defaults are wrong for one
+# host class: a wildcard re-opens a cloud box to the internet, a loopback kills
+# the LAN noVNC page on a Pi with no signal beyond a page that will not load.
+resolve_websockify_bind() {
+  local websockify_bind_file websockify_bind_line
+  websockify_bind_file="${PLATFORM_ROOT}/config/websockify-bind"
+  if [ ! -r "$websockify_bind_file" ]; then
+    log "[vnc.sh:websockify] FATAL: ${websockify_bind_file} missing or unreadable"
+    echo "ERROR: ${websockify_bind_file} missing or unreadable." >&2
+    echo "       Re-run the installer to provision the websockify bind posture." >&2
+    exit 1
+  fi
+  websockify_bind_line="$(head -n1 "$websockify_bind_file")"
+  WEBSOCKIFY_BIND="$(printf '%s\n' "$websockify_bind_line" | sed -n 's/.*bind=\([^ ]*\).*/\1/p')"
+  WEBSOCKIFY_BIND_KIND="$(printf '%s\n' "$websockify_bind_line" | sed -n 's/.*kind=\([^ ]*\).*/\1/p')"
+  case "$WEBSOCKIFY_BIND" in
+    "[::]"|"127.0.0.1") ;;
+    *)
+      log "[vnc.sh:websockify] FATAL: ${websockify_bind_file} names no recognised bind address (line=${websockify_bind_line})"
+      echo "ERROR: ${websockify_bind_file} does not name a recognised bind address." >&2
+      echo "       Re-run the installer to rewrite it." >&2
+      exit 1
+      ;;
+  esac
+  [ -n "$WEBSOCKIFY_BIND_KIND" ] || WEBSOCKIFY_BIND_KIND="unknown"
+}
 # The standing cdp-liveness probe runs every rss-sampler cycle; skip this
 # per-invocation resolution line on that path so vnc-boot.log is not spammed.
 # The FATAL guards above still run (and hard-exit) on every invocation.
@@ -541,7 +580,12 @@ case "${1:-}" in
     pkill -f "websockify.*${WEBSOCKIFY_PORT}" 2>/dev/null || true
     sleep 0.2
 
-    websockify --web /usr/share/novnc "[::]:${WEBSOCKIFY_PORT}" "localhost:${RFB_PORT}" >> "$LOG_FILE" 2>&1 &
+    # The bind address is the install-time host decision, not a constant: on a
+    # host with no private LAN interface the noVNC page and the RFB port behind
+    # it must not be reachable from off the box. Task 2089.
+    resolve_websockify_bind
+    log "websockify-bind address=${WEBSOCKIFY_BIND} kind=${WEBSOCKIFY_BIND_KIND} port=${WEBSOCKIFY_PORT}"
+    websockify --web /usr/share/novnc "${WEBSOCKIFY_BIND}:${WEBSOCKIFY_PORT}" "localhost:${RFB_PORT}" >> "$LOG_FILE" 2>&1 &
 
     if wait_for_port "${WEBSOCKIFY_PORT}"; then
       log "websockify ready on :${WEBSOCKIFY_PORT} → localhost:${RFB_PORT}"

package/payload/server/{chunk-VUXKXOJU.js → chunk-7MGR5M6G.js}

@@ -3970,7 +3970,7 @@ async function startConnection(accountId) {
   const hasAuth = await authExists(authDir);
   if (!hasAuth) {
     console.error(`${TAG17} no credentials for account=${accountId}`);
-    return;
+    throw new Error(`no credentials for account=${accountId}`);
   }
   let platformAccountId;
   let houseAccountId;
@@ -4006,7 +4006,9 @@ async function startConnection(accountId) {
     lidMapping: null
   };
   connections.set(accountId, conn);
-  await connectWithReconnect(conn);
+  void connectWithReconnect(conn).catch((err) => {
+    console.error(`${TAG17} connection loop ended in error account=${accountId}: ${formatError(err)}`);
+  });
 }
 async function stopConnection(accountId) {
   const conn = connections.get(accountId);

package/payload/server/{manager-4TJK3YOY.js → manager-6XOWHREK.js}

@@ -28,7 +28,7 @@ import {
   startConnection,
   stopConnection,
   storeMessage
-} from "./chunk-VUXKXOJU.js";
+} from "./chunk-7MGR5M6G.js";
 import "./chunk-XCR5D2G3.js";
 import "./chunk-PFF6I7KP.js";
 export {

package/payload/server/server.js

@@ -180,7 +180,7 @@ import {
   waitForConnection,
   warnNonUuidAccount,
   writeChatMetadataMerged
-} from "./chunk-VUXKXOJU.js";
+} from "./chunk-7MGR5M6G.js";
 import {
   ACCOUNTS_DIR,
   BIN_DIR,
@@ -5008,7 +5008,7 @@ async function defaultHttpGet(url) {
   }
 }
 async function defaultResolve(accountId) {
-  const { resolveSocket: resolveSocket2 } = await import("./manager-4TJK3YOY.js");
+  const { resolveSocket: resolveSocket2 } = await import("./manager-6XOWHREK.js");
   return resolveSocket2(accountId);
 }
 async function fetchAvatar(accountId, jid, deps = {}) {
@@ -6620,15 +6620,21 @@ app3.post("/disconnect", async (c) => {
   }
 });
 app3.post("/reconnect", async (c) => {
+  let accountId = "(unresolved)";
   try {
     const body = await c.req.json().catch(() => ({}));
-    const accountId = validateAccountId(body.accountId);
+    accountId = validateAccountId(body.accountId);
     const denial = selfOrHouseScopeDenial(c, accountId, "reconnect");
     if (denial) return denial;
     await startConnection(accountId);
+    console.error(
+      `[whatsapp:route] op=reconnect account=${accountId} started=true outcome=accepted reason=none`
+    );
     return c.json({ reconnecting: true, accountId });
   } catch (err) {
-    console.error(`${TAG14} reconnect error: ${String(err)}`);
+    console.error(
+      `[whatsapp:route] op=reconnect account=${accountId} started=false outcome=refused reason=${String(err)}`
+    );
     return c.json({ error: String(err) }, 500);
   }
 });

package/payload/platform/.docs/search-surface-contract.md

@@ -1,58 +0,0 @@
-# Search-surface parity contract
-
-Three operator/agent surfaces run the same `hybrid()` search engine
-(`platform/lib/graph-search`). The contract: **the same query yields the same
-node set on every surface** unless a surface declares an explicit, documented
-divergence.
-
-| Surface | Entry point | Labels default | Vector floor |
-|---|---|---|---|
-| Chat (agent recall) | `memory-search` MCP tool → `memorySearch()` | none set ⇒ all labels | `DEFAULT_VECTOR_THRESHOLD` (0.82) |
-| `/graph` admin page | `GET /api/admin/graph-search` | no chips ⇒ all labels; chips narrow | `DEFAULT_VECTOR_THRESHOLD` (0.82), `?threshold` overrides |
-| `/data` admin page | `GET /api/admin/graph-search?labels=FileArtifact` | `FileArtifact` only (files) | `DEFAULT_VECTOR_THRESHOLD` (0.82), `?threshold` overrides; show-all sends `?threshold=0` |
-
-## The two parity rules (Task 635)
-
-1. **All labels by default.** A caller that passes no labels (chat) or an empty
-   chip set (`/graph`) searches every label — the route forwards `undefined` to
-   `hybrid()`, the lib's no-label gate, which queries every vector index. The
-   `*` wildcard is a separate explicit opt-in to the same all-labels path (no
-   current caller sends it; `/data` sends a real `FileArtifact` label instead).
-   `/graph` no longer rejects an empty chip set with a 400; chips, when present,
-   narrow post-filter.
-
-2. **One vector floor, defined once.** `DEFAULT_VECTOR_THRESHOLD = 0.82` lives
-   in `platform/lib/graph-search/src/index.ts` and is the single source of
-   truth. Each *surface* opts into it as its default; `hybrid()` itself keeps
-   the `vectorThreshold === undefined ⇒ no floor` contract. Two literals of
-   0.82 in two files would be a drift vector — there is one constant, imported
-   by both the route (`src`) and `memory-search` (`dist`, so the lib must be
-   rebuilt for the memory plugin to see a change).
-
-## Declared divergences (allowed, by explicit caller or post-filter)
-
-- **`/data` is files-only.** It sends `labels=FileArtifact` — a deliberate
-  server-side caller filter to file nodes, not a parity break. (It also
-  triggers the route's `FileArtifact` index-reconcile branch before searching.)
-- **`graph-subgraph` pivot mask.** `GET /api/admin/graph-subgraph?q=…` runs
-  `hybrid()` with `expandHops: 0` and **no** vector floor. Its output is not a
-  result list — it is intersected with a clicked node's neighbourhood to
-  narrow a pivot. "Same query, same results" does not apply to an intersection
-  mask, so it intentionally stays unthresholded.
-- **Post-search projections** — the chat public-twin property rewrite and the
-  `/graph` Message→Conversation parent merge run after the engine returns and
-  do not change which nodes the engine selected.
-
-## Diagnostics
-
-```
-logs-read.sh --tail server 100 | grep -E '\[graph-search\]'
-```
-
-- `op=labels-default applied=all` — a no-chip `/graph` request took the
-  all-labels path. Its absence on a no-labels request is the regression signal.
-- `labels=all` (query line) — no chips (all labels); `labels=*` — explicit
-  wildcard opt-in; `labels=FileArtifact` — `/data` files search;
-  `labels=Person,…` — narrowed chip search.
-- `threshold=0.82` on a default request; `threshold=off` only when an explicit
-  `?threshold=0` was passed.