@rubytech/create-realagent 1.0.667 → 1.0.669

package/dist/index.js

@@ -206,6 +206,33 @@ function canSudo() {
     const result = spawnSync("sudo", ["-n", "true"], { stdio: "pipe", timeout: 5_000 });
     return result.status === 0;
 }
+// Task 634 — verified-not-asserted apt-dep reconciliation.
+//
+// Returns the subset of `pkgs` that are not currently installed. Uses
+// `dpkg -s <pkg>` per package (exit 0 = installed, any non-zero = missing)
+// so we never parse dpkg's prose output for control flow
+// (feedback_no_stdout_parsing_for_control_flow.md).
+function pkgsMissing(pkgs) {
+    return pkgs.filter((p) => {
+        const r = spawnSync("dpkg", ["-s", p], { stdio: "pipe", timeout: 5_000 });
+        return r.status !== 0;
+    });
+}
+/**
+ * Install a logical group of apt packages, then verify each one landed in
+ * dpkg's installed state. The post-install `dpkg -s` probe catches the
+ * partial-failure class where `apt-get install` returns 0 but a package did
+ * not actually install — silent regressions that would otherwise only
+ * surface at runtime when the binary is missing.
+ */
+function installAptGroup(label, pkgs) {
+    logFile(`  apt install (${label}): ${pkgs.join(" ")}`);
+    shell("apt-get", ["install", "-y", ...pkgs], { sudo: true });
+    const stillMissing = pkgsMissing(pkgs);
+    if (stillMissing.length > 0) {
+        throw new Error(`apt-get install (${label}) returned 0 but packages are still not installed per dpkg -s: ${stillMissing.join(", ")}`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Installation steps
 // ---------------------------------------------------------------------------
@@ -216,28 +243,51 @@ function installSystemDeps() {
         console.log("  Skipping Linux-specific setup (not on Linux).");
         return;
     }
-    if (canSudo()) {
-        shell("apt-get", ["update"], { sudo: true });
-        shell("apt-get", ["install", "-y", "curl", "git", "unzip", "jq", "avahi-daemon", "avahi-utils", "poppler-utils", "ffmpeg"], { sudo: true });
-        // xterm is the *preferred* terminal-emulator binary for the VNC-rendered
-        // Terminal surface (Task 632 — gnome-terminal is a D-Bus launcher that
-        // delegates window creation to the session's gnome-terminal-server,
-        // opening windows on the wrong display; xterm has no IPC layer and
-        // honours DISPLAY directly). Kept in the apt list unconditionally so
-        // vnc.sh's resolve_terminal_bin has a display-safe binary on every
-        // supported distro (Ubuntu 24.04 noble/universe, Debian 12 bookworm/main
-        // verified). xdotool (Task 632) backs the post-spawn display-membership
-        // assertion in vnc.sh check_window_on_display, closing the silent-fail
-        // class where PID is alive but no window is mapped on the target display.
-        shell("apt-get", ["install", "-y", "tigervnc-standalone-server", "python3-websockify", "novnc", "xdg-utils", "chromium", "xterm", "xdotool"], { sudo: true });
-        shell("apt-get", ["install", "-y", "hostapd", "dnsmasq"], { sudo: true });
-        // tmux backs the admin terminal's persistent named session (Task 591).
-        // ttyd is NOT in Debian Bookworm's apt repo (Task 602) — it ships as a
-        // pinned upstream binary installed by provisionTtydBinary() in step 11.
-        shell("apt-get", ["install", "-y", "tmux"], { sudo: true });
+    const BASE_DEPS = ["curl", "git", "unzip", "jq", "avahi-daemon", "avahi-utils", "poppler-utils", "ffmpeg"];
+    // xterm is the *preferred* terminal-emulator binary for the VNC-rendered
+    // Terminal surface (Task 632 — gnome-terminal is a D-Bus launcher that
+    // delegates window creation to the session's gnome-terminal-server,
+    // opening windows on the wrong display; xterm has no IPC layer and
+    // honours DISPLAY directly). Kept in the apt list unconditionally so
+    // vnc.sh's resolve_terminal_bin has a display-safe binary on every
+    // supported distro (Ubuntu 24.04 noble/universe, Debian 12 bookworm/main
+    // verified). xdotool (Task 632) backs the post-spawn display-membership
+    // assertion in vnc.sh check_window_on_display, closing the silent-fail
+    // class where PID is alive but no window is mapped on the target display.
+    const VNC_DEPS = ["tigervnc-standalone-server", "python3-websockify", "novnc", "xdg-utils", "chromium", "xterm", "xdotool"];
+    const WIFI_DEPS = ["hostapd", "dnsmasq"];
+    // tmux backs the admin terminal's persistent named session (Task 591).
+    // ttyd is NOT in Debian Bookworm's apt repo (Task 602) — it ships as a
+    // pinned upstream binary installed by provisionTtydBinary() in step 11.
+    const TERMINAL_DEPS = ["tmux"];
+    const ALL_APT_DEPS = [...BASE_DEPS, ...VNC_DEPS, ...WIFI_DEPS, ...TERMINAL_DEPS];
+    // Task 634 — verify the "deps are present" assumption with `dpkg -s` instead
+    // of asserting it (feedback_loud_failures.md). The previous silent-skip
+    // branch was benign until Task 632 added xdotool (the first new apt dep
+    // since the skip path became load-bearing on user-password-sudo devices).
+    const missing = pkgsMissing(ALL_APT_DEPS);
+    if (missing.length === 0) {
+        logFile(`  all system deps present per dpkg -s (${ALL_APT_DEPS.length} packages) — skipping apt install`);
+        console.log(`  All ${ALL_APT_DEPS.length} system deps already installed — skipping apt install.`);
     }
     else {
-        console.log("  Skipping apt-get (sudo unavailable non-interactively — deps assumed present from prior install)");
+        const canEscalate = canSudo() || process.stdout.isTTY === true;
+        if (!canEscalate) {
+            const repair = `sudo apt-get install -y ${missing.join(" ")}`;
+            console.error(`  MISSING ${missing.length} system deps per dpkg -s: ${missing.join(" ")}`);
+            console.error(`  Non-interactive sudo is unavailable; cannot prompt for password from a non-TTY shell.`);
+            console.error(`  Re-run this installer from an interactive shell, or repair manually:`);
+            console.error(`    ${repair}`);
+            logFile(`  FAIL: missing apt deps without interactive sudo: ${missing.join(",")}`);
+            throw new Error(`installSystemDeps: missing packages (${missing.join(", ")}) and sudo is unavailable non-interactively — repair with: ${repair}`);
+        }
+        console.log(`  Missing apt deps (${missing.length}): ${missing.join(", ")}`);
+        console.log(`  Installing via sudo apt-get — sudo may prompt for your password...`);
+        shell("apt-get", ["update"], { sudo: true });
+        installAptGroup("base utilities", BASE_DEPS);
+        installAptGroup("VNC stack", VNC_DEPS);
+        installAptGroup("WiFi AP", WIFI_DEPS);
+        installAptGroup("terminal", TERMINAL_DEPS);
     }
     // Hostname resolution — four sources, in priority order:
     //   1. --hostname flag (unconditional — the caller is the authority)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.667",
+  "version": "1.0.669",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent": "./dist/index.js"

package/payload/platform/plugins/docs/references/memory-guide.md

@@ -84,7 +84,7 @@ Ask naturally:
 
 Maxy answers relational questions — "list all my people", "how many tasks do I have", "find the person with email X", "show me the 20 most recently created nodes" — via direct read-only Cypher against your Neo4j. This is faster and more precise than semantic search when the question is "the exact set where", not "things similar to".
 
-You can also open a visual view of your graph at any time from the burger menu → **Graph**. Click the **Filter** button in the toolbar to open the filter menu — it lists only the node types that actually exist in your graph, one row per type, showing your per-type node count and sorted so the most-connected types sit at the top. Leaf types that only appear inside a parent (messages inside a conversation, sections inside a document) are never filter rows — you reach them by clicking the parent and exploring its neighbourhood. Infrastructural types (`ToolCall`, `WorkflowRun`, `WorkflowStep`, `ReviewAlert`) never appear as filter rows — the first three are execution plumbing, and `ReviewAlert` has its own dedicated surface in admin chat. Active rows render a force-directed map, coloured by label (Person, Service, KnowledgeDocument, Task, …). Click a node to see its properties and explore its neighbourhood; click the **Back** control or empty canvas to return to your filter view with the same rows still selected. Type in the search box to highlight matches; submitting a search also widens the filter to include any node types the hits belong to, so relevant matches render instead of disappearing into a "not in current view" banner. The **×** buttons on the search box and inside the filter menu clear the current search and the current selection respectively — clearing the filter selection does not touch your saved default.
+You can also open a visual view of your graph at any time from the burger menu → **Graph**. Click the **Filter** button in the toolbar to open the filter menu — it lists only the node types that actually exist in your graph, one row per type, showing your per-type node count and sorted so the most-connected types sit at the top. Leaf types that only appear inside a parent (messages inside a conversation, sections inside a document) are never filter rows — you reach them by clicking the parent and exploring its neighbourhood. Infrastructural types (`ToolCall`, `WorkflowRun`, `WorkflowStep`, `ReviewAlert`) never appear as filter rows — the first three are execution plumbing, and `ReviewAlert` has its own dedicated surface in admin chat. Active rows render a force-directed map, coloured by label (Person, Service, KnowledgeDocument, Task, …). Click a node from the filter view to explore its neighbourhood. Once inside a neighbourhood, clicking another node (a Message inside a Conversation, for example) opens its properties in the side panel without collapsing the view — peer Messages stay on canvas and **Back** still returns to your filter rows in one step. Click the **Back** control or empty canvas to return to your filter view with the same rows still selected. Type in the search box to highlight matches; submitting a search also widens the filter to include any node types the hits belong to, so relevant matches render instead of disappearing into a "not in current view" banner. The **×** buttons on the search box and inside the filter menu clear the current search and the current selection respectively — clearing the filter selection does not touch your saved default.
 
 Conversations and Messages carry role/channel sublabels so you can read the chat topology by colour alone — admin vs public conversations and user vs assistant messages render in distinct shades, and the filter menu splits them into separate rows.
 

package/payload/platform/plugins/docs/references/troubleshooting.md

@@ -172,6 +172,41 @@ Most common failures and fixes:
 - `[terminal-launch] failed err="window absent from target display after spawn" pid=<N> display=:99 observed_windows=0` → the spawned emulator's window landed on the wrong display (Task 632 — almost always a stale gnome-terminal binary on an upgraded install; the fix ships `xterm` as the `:99` default but a stale `resolve_terminal_bin` on an old bundle can still trigger it). Check `which gnome-terminal xterm xdotool` — all three should exist; if not, re-run the installer. Also check `DISPLAY=:99 xdotool search --onlyvisible --class '.'` manually: empty output confirms no window on `:99`; a non-empty result after a fresh click means the window IS there and the check itself is wrong (file an issue).
 - `ensure-terminal action="escalate-vnc-restart"` followed by `degraded` → `Xtigervnc` itself is not coming up. Check `~/.maxy/logs/vnc-boot.log` for the tigervnc startup lines.
 
+## Terminal fails after upgrade — `Invalid response` or `window absent from target display`
+
+**Symptom:** You upgraded a Maxy device and the header-menu **Terminal** click now fails — overlay shows `Invalid response`, or `terminal-launch.log` shows `[terminal-launch] failed err="window absent from target display after spawn" pid=<N> display=:99 observed_windows=0 transport=vnc cmd="/usr/bin/xterm "`. The terminal worked on the previous version and the upgrade reported success.
+
+**What it means:** The installer declared a new apt dep between versions (e.g. `xdotool` in 1.0.667), but on your device the installer's apt step was silently skipped because `sudo` requires a password and the installer could not escalate non-interactively. The declared dep was never installed, and `vnc.sh check_window_on_display` then either failed to find the binary (exit 127 — Task 634 now surfaces this as a distinct `failed err="xdotool not installed — re-run installer to repair"` line) or reached the `window absent` path because its preflight tool was missing. See `.docs/deployment.md` ("sudo interactivity contract") for the full mechanism.
+
+**Check:**
+
+```bash
+dpkg -s xdotool 2>&1 | head -2     # should report "Status: install ok installed"
+which xdotool                      # should return /usr/bin/xdotool
+```
+
+**Fix — two options:**
+
+1. **Re-run the installer from an interactive shell** (preferred on upgrade — picks up any future missing deps too):
+
+   ```bash
+   npx -y @rubytech/create-maxy@latest
+   ```
+
+   The installer now probes `dpkg -s` for every declared apt dep and either prompts you for your sudo password to install missing ones, or loud-fails non-interactively with the exact `sudo apt-get install -y <list>` command to repair. It will no longer print `Skipping apt-get (deps assumed present from prior install)` and continue as if green.
+
+2. **Repair manually** (faster if you only want the one binary):
+
+   ```bash
+   sudo apt-get install -y xdotool
+   ```
+
+   Then click **Terminal** again — it should spawn within a second and the overlay should render the xterm.
+
+**Regression boundary:** if you see `[terminal-launch] failed err="xdotool not installed — re-run installer to repair"` in `~/.maxy/logs/terminal-launch.log`, the vnc.sh preflight is telling you the binary is missing before spawn — same class as above, distinct from the Task 632 `window absent from target display after spawn` string. The two strings never appear for the same click.
+
+---
+
 ## Terminal iframe renders black and cursor vanishes over the canvas
 
 **Symptom:** Header-menu Terminal click appears to succeed — no error toast, overlay opens — but the iframe renders uniformly black, keystrokes do not reach any shell, and the mouse cursor disappears the moment it enters the iframe (visible elsewhere in the page).

package/payload/platform/scripts/vnc.sh

@@ -214,6 +214,16 @@ start_chrome() {
 # loud-fail log if neither is installed — matches the operator invariant
 # "no ttyd fallback, no silent substitution" from Task 627. gnome-terminal
 # retains `--wait` (see Task 627 pgrep-visibility fix). xterm takes no flag.
+# xterm flags for the :99 VNC framebuffer. Fontconfig alias `monospace`
+# resolves via /etc/fonts to the distro's default monospace face (DejaVu
+# Sans Mono on Ubuntu/Debian) — no quoting needed, so the flag string
+# survives unquoted $flags word-splitting in start_terminal_on. Geometry
+# 160x45 fills the Xtigervnc display (1280x800 — see Xtigervnc -geometry
+# flag below) at 11pt; the prior empty flag string left xterm at its 80x24
+# default with the 6x13 `fixed` bitmap font, which rendered ~480x312 px of
+# the 1280x800 framebuffer with a black void around it.
+XTERM_VNC_FLAGS='-fa monospace -fs 11 -geometry 160x45'
+
 resolve_terminal_bin() {
   local target_display="${1:-:99}"
   local xterm_bin='' gnome_bin=''
@@ -221,17 +231,35 @@ resolve_terminal_bin() {
   [ -x /usr/bin/gnome-terminal ] && gnome_bin='/usr/bin/gnome-terminal'
 
   if [ "$target_display" = ":99" ]; then
-    [ -n "$xterm_bin" ] && { printf '%s\t%s\n' "$xterm_bin" ''; return 0; }
+    [ -n "$xterm_bin" ] && { printf '%s\t%s\n' "$xterm_bin" "$XTERM_VNC_FLAGS"; return 0; }
     [ -n "$gnome_bin" ] && { printf '%s\t%s\n' "$gnome_bin" '--wait'; return 0; }
   else
     [ -n "$gnome_bin" ] && { printf '%s\t%s\n' "$gnome_bin" '--wait'; return 0; }
-    [ -n "$xterm_bin" ] && { printf '%s\t%s\n' "$xterm_bin" ''; return 0; }
+    [ -n "$xterm_bin" ] && { printf '%s\t%s\n' "$xterm_bin" "$XTERM_VNC_FLAGS"; return 0; }
   fi
   tlog "failed err=\"no terminal emulator installed (expected /usr/bin/gnome-terminal or /usr/bin/xterm)\""
   log "ERROR: no terminal emulator binary found — install xterm (apt-get install -y xterm)"
   return 1
 }
 
+# Task 634 — runtime preflight for terminal-launch dependencies. Separates
+# exit 127 (xdotool missing from PATH) from exit 1 (xdotool present but no
+# window mapped) in check_window_on_display. The installer now verifies
+# apt deps via `dpkg -s` but an operator can still `apt remove xdotool`
+# post-install, so this is the matching runtime guard. Emits the failure
+# string on stderr so ensureTerminal's extractFailureLine captures it
+# verbatim into server.log's `ensure-terminal err=...` field.
+preflight_terminal_deps() {
+  if command -v xdotool >/dev/null 2>&1; then
+    log "xdotool: $(command -v xdotool)"
+    return 0
+  fi
+  tlog "failed err=\"xdotool not installed — re-run installer to repair\""
+  log "ERROR: xdotool missing — start-terminal cannot assert display-membership (re-run: npx -y @rubytech/create-maxy@latest)"
+  echo "[terminal-launch] failed err=\"xdotool not installed — re-run installer to repair\"" >&2
+  return 1
+}
+
 # Verify that at least one visible window is mapped on $target_display. Closes
 # the "PID visible in pgrep but window is not on target" class of silent fail
 # (Task 632). Uses xdotool's exit code directly — no stdout parsing for
@@ -243,8 +271,14 @@ resolve_terminal_bin() {
 # Returns 0 if any visible window appears on the display within ~1s, 1 otherwise.
 check_window_on_display() {
   local target_display="$1"
+  # Task 634 — route xdotool stderr to vnc-boot.log instead of /dev/null.
+  # preflight_terminal_deps removes the 127-vs-1 conflation from production,
+  # but if xdotool ever fails for a non-missing-binary reason (broken X
+  # server, malformed DISPLAY), the diagnostic now lands in a grep-addressable
+  # log instead of vanishing. Control flow still depends solely on the exit
+  # code (feedback_no_stdout_parsing_for_control_flow.md).
   for _ in 1 2 3; do
-    if DISPLAY="$target_display" xdotool search --onlyvisible --class '.' >/dev/null 2>&1; then
+    if DISPLAY="$target_display" xdotool search --onlyvisible --class '.' >/dev/null 2>>"$LOG_FILE"; then
       return 0
     fi
     sleep 0.3
@@ -386,10 +420,12 @@ start_terminal_on() {
 }
 
 start_terminal() {
+  preflight_terminal_deps || return 1
   start_terminal_on ":99" "vnc"
 }
 
 start_terminal_native() {
+  preflight_terminal_deps || return 1
   discover_native_session
   start_terminal_on "${NATIVE_DISPLAY}" "native"
 }