@rubytech/create-realagent 1.0.844 → 1.0.846

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

@@ -64,6 +64,11 @@ tail -200 ~/.maxy/logs/maxy-ui.log | rg '\[remote-auth\].*resolvedKind='
 
 **Agent searches the filesystem after uploading a zip.** If you uploaded a zip and the agent burns several turns running `find` / `Glob` instead of unzipping, that is the symptom of the recovery-retry attachment-context regression (now closed by the recovery context preservation contract in `.docs/agents.md`). Greppable confirmation is the `[context-overflow-recovery] retry … attachmentsCarried=<n>` line in the conversation stream log. If you see `[context-overflow-recovery] WARN attachment-context-lost`, the regression has returned — surface to support.
 
+**Wrong Claude account answering on a multi-brand device.** On a host running both Maxy and Real Agent, each brand's admin agent reads its own `~/${brand.configDir}/.claude/.credentials.json`; there is no longer a shared `~/.claude/` thrashing them against one another. If a brand reports auth failures or appears to be operating against the wrong subscription, check three things:
+1. `grep "\[claude-auth\] init" ~/.${brand}/logs/server.log | tail -1` — the resolved path must end with `~/.${brand}/.claude/.credentials.json`. If a `[claude-auth] WARN cross-brand-path-detected` line is present, the runtime is still pointing at `~/.claude/`; the brand main service did not pick up the `Environment=CLAUDE_CONFIG_DIR=` setting (re-run the brand installer to refresh the unit file).
+2. `diff <(jq .claudeAiOauth.accessToken ~/.maxy/.claude/.credentials.json) <(jq .claudeAiOauth.accessToken ~/.realagent/.claude/.credentials.json)` — must be non-empty after each brand's operator has run `claude /login` against distinct Anthropic accounts; if it's empty, both brands are still logged in to the same account (operator action, not a code bug).
+3. `grep "\[install\] claude-creds pickup" ~/.${brand}/logs/install-*.log` — fires once on the first post-Task-923 install of any brand and moves the legacy `~/.claude/.credentials.json` into that brand's path. Subsequent brands install with no credentials and require a fresh `claude /login` inside that brand's chat (which writes to the brand-scoped path because the systemd unit env is in scope).
+
 ---
 
 ## Memory Not Working

package/payload/platform/scripts/check-sdk-oauth.mjs

@@ -15,14 +15,19 @@
 //
 // PASS condition: apiKeySource ∈ {'oauth', 'none'}. Both indicate OAuth-only mode:
 // 'oauth' = SDK supplied an OAuth-issued API key; 'none' = SDK supplied no key
-// at all and the claude binary's own ~/.claude/.credentials.json OAuth state is
-// in use. Cross-check with `claude --print --output-format json "Reply…"` to
-// confirm the same value: parity = SDK is faithfully proxying claude's auth.
+// at all and the claude binary's own credentials file is in use. Production
+// brand installs (Task 923) read this file from CLAUDE_CONFIG_DIR — which
+// the brand main service sets to `${persistDir}/.claude` — so the
+// per-brand path is `~/${BRAND.configDir}/.claude/.credentials.json`. This
+// orphan/standalone Pi spike runs without that env var and falls back to
+// `~/.claude/.credentials.json`; that's by design (the spike is not in the
+// production execution path; see Task 746 brief). Cross-check with
+// `claude --print --output-format json "Reply…"` to confirm parity.
 //
 // Verdict reasons (exit 1 unless PASS):
 //   env-set                       ANTHROPIC_API_KEY present (operator must `unset`)
-//   no-oauth-credentials          ~/.claude/.credentials.json unreadable, empty,
-//                                 or contains no OAuth-shaped fields (run `claude login`)
+//   no-oauth-credentials          credentials file unreadable, empty, or
+//                                 contains no OAuth-shaped fields (run `claude login`)
 //   exception:<msg>               SDK import or runtime error
 //   no-system-init                SDK never emitted system.init message
 //   wrong-api-key-source:<value>  apiKeySource ∉ {oauth, none} — value verbatim;
@@ -46,7 +51,9 @@ import { join } from 'node:path'
 const TIMEOUT_MS = 60_000
 const PROMPT = 'Reply with the literal string OK and nothing else.'
 // Claude Code emits apiKeySource='none' when the SDK supplies no API key and
-// the claude binary uses its own OAuth credentials at ~/.claude/.credentials.json.
+// the claude binary uses its own OAuth credentials at the path resolved from
+// CLAUDE_CONFIG_DIR (Task 923) — falling back to `~/.claude/.credentials.json`
+// when CLAUDE_CONFIG_DIR is unset, as in this orphan Pi spike's runtime.
 // Brief assumed 'oauth' based on stale type-defs; runtime-correct OAuth-only
 // indicator on Claude Code 2.1.x is 'none'. Both accepted; cross-check with
 // `claude --print --output-format json` to confirm parity.

package/payload/platform/scripts/vnc.sh

@@ -4,11 +4,19 @@
 #
 # Usage: vnc.sh start | stop | start-chrome | start-chrome-native | status
 #
-# Components:
-#   Xtigervnc :99        — virtual X11 display + VNC server on port 5900
-#   websockify :6080     — WebSocket bridge serving noVNC static files
-#   Chromium :9222       — headed browser with CDP enabled
-#                          (Playwright MCP connects via --cdp-endpoint)
+# Components (brand-scoped; see Task 553):
+#   Xtigervnc :${VNC_DISPLAY}      — virtual X11 display per brand
+#   websockify :6080               — WebSocket bridge (port shared until follow-up)
+#   Chromium                       — headed browser with --user-data-dir per brand
+#   CDP :9222                      — Playwright MCP endpoint (port shared until follow-up)
+#
+# Brand isolation (Task 553): the X display number and Chromium profile are
+# brand-scoped so two brands on the same device do not share session cookies,
+# extensions, or local storage. Maxy=:99, Real Agent=:100; per-brand value
+# stamped from brand.json.vncDisplay at install time and re-read at runtime.
+# CDP port 9222 and websockify 6080 are NOT yet brand-scoped — until that
+# follow-up lands, only one brand's Chromium can hold CDP at a time and
+# concurrent multi-brand VNC stacks fail loudly on port collision.
 #
 # Task 664 retired the admin-UI terminal surface entirely. This script
 # no longer spawns GUI terminal emulators of any kind; upgrades and
@@ -16,64 +24,103 @@
 # (/api/admin/actions/*) rather than an in-browser terminal.
 #
 # Display modes (DISPLAY_MODE env var, set by installer --display flag):
-#   virtual (default) — Chromium runs on :99 (VNC virtual display)
+#   virtual (default) — Chromium runs on the brand's :${VNC_DISPLAY}
 #   native            — Chromium runs on the login session's real display
 #                        (discovered via loginctl, NOT from $DISPLAY which
-#                         is poisoned by systemd Environment=DISPLAY=:99)
+#                         is poisoned by the systemd Environment=DISPLAY line)
 
 set -uo pipefail
 
-# Derive config dir from brand.json so logs go to the correct brand-specific
-# directory (e.g. ~/.realagent/ instead of ~/.maxy/). Primary source is the
-# script's own filesystem location; $MAXY_PLATFORM_ROOT is a fallback.
+# Derive config dir AND VNC display from brand.json so logs and X display go
+# to the correct brand-specific values (e.g. ~/.realagent/ + :100 instead of
+# ~/.maxy/ + :99). Primary source is the script's own filesystem location;
+# $MAXY_PLATFORM_ROOT is a fallback.
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PLATFORM_ROOT="${MAXY_PLATFORM_ROOT:-$(dirname "$SCRIPT_DIR")}"
 BRAND_JSON="${PLATFORM_ROOT}/config/brand.json"
 CONFIG_DIR=".maxy"
+VNC_DISPLAY_NUM=99
+BRAND_HOSTNAME="maxy"
 if [ -f "$BRAND_JSON" ] && command -v jq >/dev/null 2>&1; then
   _dir=$(jq -r '.configDir // empty' "$BRAND_JSON" 2>/dev/null) || true
   [ -n "$_dir" ] && CONFIG_DIR="$_dir"
+  _vd=$(jq -r '.vncDisplay // empty' "$BRAND_JSON" 2>/dev/null) || true
+  if [ -n "$_vd" ] && [ "$_vd" -eq "$_vd" ] 2>/dev/null; then
+    VNC_DISPLAY_NUM="$_vd"
+  fi
+  _hn=$(jq -r '.hostname // empty' "$BRAND_JSON" 2>/dev/null) || true
+  [ -n "$_hn" ] && BRAND_HOSTNAME="$_hn"
 fi
 
+VNC_DISPLAY=":${VNC_DISPLAY_NUM}"
 MAXY_DIR="${HOME}/${CONFIG_DIR}"
 LOG_DIR="${MAXY_DIR}/logs"
 LOG_FILE="${LOG_DIR}/vnc-boot.log"
+CHROMIUM_PROFILE_DIR="${MAXY_DIR}/chromium-profile"
 
 mkdir -p "$LOG_DIR"
 
 log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >> "$LOG_FILE"; }
 
 kill_stale() {
-  pkill -f 'chromium.*remote-debugging-port=9222' 2>/dev/null || true
-  pkill -f 'Xtigervnc :99' 2>/dev/null || true
+  # Brand-scoped matchers (Task 553): pkill on --user-data-dir narrows the
+  # Chromium kill to this brand's profile only, so two brands on the same
+  # device do not stomp on each other. Xtigervnc matcher narrows to this
+  # brand's display number.
+  pkill -f "chromium.*--user-data-dir=${CHROMIUM_PROFILE_DIR}" 2>/dev/null || true
+  pkill -f "Xtigervnc ${VNC_DISPLAY}" 2>/dev/null || true
   pkill -f 'websockify.*6080' 2>/dev/null || true
-  rm -f /tmp/.X99-lock /tmp/.X11-unix/X99
-  # Clear Chromium profile locks left by unclean shutdown — without this,
-  # Chromium refuses to start after a service restart or power loss.
-  # System Chromium stores locks under ~/.config/chromium/; snap-installed
-  # Chromium (Ubuntu) stores them under ~/snap/chromium/common/chromium/.
-  rm -f "${HOME}/.config/chromium/SingletonLock" \
-        "${HOME}/.config/chromium/SingletonCookie" \
-        "${HOME}/.config/chromium/SingletonSocket" 2>/dev/null || true
-  rm -f "${HOME}/snap/chromium/common/chromium/SingletonLock" \
-        "${HOME}/snap/chromium/common/chromium/SingletonCookie" \
-        "${HOME}/snap/chromium/common/chromium/SingletonSocket" 2>/dev/null || true
+  rm -f "/tmp/.X${VNC_DISPLAY_NUM}-lock" "/tmp/.X11-unix/X${VNC_DISPLAY_NUM}"
+  # Clear this brand's Chromium profile locks left by unclean shutdown.
+  # Without this, Chromium refuses to start after a service restart or
+  # power loss. The per-brand profile path means peer brands' locks are
+  # never touched here.
+  rm -f "${CHROMIUM_PROFILE_DIR}/SingletonLock" \
+        "${CHROMIUM_PROFILE_DIR}/SingletonCookie" \
+        "${CHROMIUM_PROFILE_DIR}/SingletonSocket" 2>/dev/null || true
   sleep 2
 
   # If any VNC-stack processes survived SIGTERM, force-kill them.
   local survivors=0
-  pgrep -f 'chromium.*remote-debugging-port=9222' >/dev/null 2>&1 && survivors=1
-  pgrep -f 'Xtigervnc :99' >/dev/null 2>&1 && survivors=1
+  pgrep -f "chromium.*--user-data-dir=${CHROMIUM_PROFILE_DIR}" >/dev/null 2>&1 && survivors=1
+  pgrep -f "Xtigervnc ${VNC_DISPLAY}" >/dev/null 2>&1 && survivors=1
   pgrep -f 'websockify.*6080' >/dev/null 2>&1 && survivors=1
   if [ "$survivors" -eq 1 ]; then
     log "SIGTERM survivors detected — sending SIGKILL"
-    pkill -9 -f 'chromium.*remote-debugging-port=9222' 2>/dev/null || true
-    pkill -9 -f 'Xtigervnc :99' 2>/dev/null || true
+    pkill -9 -f "chromium.*--user-data-dir=${CHROMIUM_PROFILE_DIR}" 2>/dev/null || true
+    pkill -9 -f "Xtigervnc ${VNC_DISPLAY}" 2>/dev/null || true
     pkill -9 -f 'websockify.*6080' 2>/dev/null || true
     sleep 1
   fi
 }
 
+# Refuse to start when this brand's display is already held by an unrelated
+# process (e.g. a peer brand's Xtigervnc whose vncDisplay collides, or a
+# manual Xvfb invocation). Loud-fail so the operator sees the held-by-pid
+# rather than silently sharing a display with another stack. Task 553.
+check_display_collision() {
+  local lock="/tmp/.X${VNC_DISPLAY_NUM}-lock"
+  local socket="/tmp/.X11-unix/X${VNC_DISPLAY_NUM}"
+  local held_pid=""
+  if [ -f "$lock" ]; then
+    held_pid="$(cat "$lock" 2>/dev/null | tr -d ' ' || true)"
+  fi
+  # Empty / stale lock → nothing to refuse. kill_stale will clean it up.
+  if [ -z "$held_pid" ] || ! kill -0 "$held_pid" 2>/dev/null; then
+    return 0
+  fi
+  # Live PID — but is it OUR own previous Xtigervnc? If yes, kill_stale will
+  # handle it; only refuse when the holder is unrelated to this brand's
+  # vnc.sh stack.
+  if pgrep -f "Xtigervnc ${VNC_DISPLAY}" 2>/dev/null | grep -qx "$held_pid"; then
+    return 0
+  fi
+  log "[vnc.sh:collision] brand=${BRAND_HOSTNAME} display=${VNC_DISPLAY} held-by-pid=${held_pid} socket=${socket}"
+  echo "ERROR: display ${VNC_DISPLAY} is held by PID ${held_pid} (not this brand's Xtigervnc)" >&2
+  echo "       Refusing to start; resolve the collision before retrying." >&2
+  exit 1
+}
+
 wait_for_port() {
   local port="$1" max="${2:-40}"
   for _ in $(seq 1 "$max"); do
@@ -134,12 +181,15 @@ discover_native_session() {
 start_chrome_on() {
   local target_display="$1"
   local label="$2"  # "vnc" (native mode uses start_chrome_native instead)
-  pkill -f 'chromium.*remote-debugging-port=9222' 2>/dev/null || true
+  # Brand-scoped Chromium kill: only this brand's profile-bound chromium.
+  pkill -f "chromium.*--user-data-dir=${CHROMIUM_PROFILE_DIR}" 2>/dev/null || true
   sleep 0.3
 
-  log "Starting Chromium on ${target_display} (${label}) with CDP on :9222"
+  mkdir -p "${CHROMIUM_PROFILE_DIR}"
+  log "Starting Chromium on ${target_display} (${label}) profile=${CHROMIUM_PROFILE_DIR} CDP=:9222"
 
   DISPLAY="${target_display}" /usr/bin/chromium \
+    --user-data-dir="${CHROMIUM_PROFILE_DIR}" \
     --ozone-platform=x11 \
     --no-sandbox \
     --test-type \
@@ -182,7 +232,7 @@ start_chrome_on() {
 }
 
 start_chrome() {
-  start_chrome_on ":99" "vnc"
+  start_chrome_on "${VNC_DISPLAY}" "vnc"
 }
 
 # ---------------------------------------------------------------------------
@@ -194,16 +244,18 @@ start_chrome() {
 start_chrome_native() {
   discover_native_session
 
-  pkill -f 'chromium.*remote-debugging-port=9222' 2>/dev/null || true
+  # Brand-scoped Chromium kill: only this brand's profile-bound chromium.
+  pkill -f "chromium.*--user-data-dir=${CHROMIUM_PROFILE_DIR}" 2>/dev/null || true
   sleep 0.3
 
+  mkdir -p "${CHROMIUM_PROFILE_DIR}"
   log "Starting Chromium natively (${NATIVE_SESSION_TYPE}, $(
     if [ "$NATIVE_SESSION_TYPE" = "wayland" ]; then
       echo "WAYLAND_DISPLAY=${NATIVE_WAYLAND_DISPLAY}"
     else
       echo "DISPLAY=${NATIVE_DISPLAY}"
     fi
-  )) with CDP on :9222"
+  )) profile=${CHROMIUM_PROFILE_DIR} CDP=:9222"
 
   local ozone_flag="--ozone-platform=x11"
   local -a env_vars=("DISPLAY=${NATIVE_DISPLAY}")
@@ -214,6 +266,7 @@ start_chrome_native() {
   fi
 
   env "${env_vars[@]}" /usr/bin/chromium \
+    --user-data-dir="${CHROMIUM_PROFILE_DIR}" \
     "$ozone_flag" \
     --no-sandbox \
     --test-type \
@@ -256,11 +309,17 @@ start_chrome_native() {
 
 case "${1:-}" in
   start)
-    log "DISPLAY_MODE=${DISPLAY_MODE:-virtual}"
+    log "[vnc.sh] start brand=${BRAND_HOSTNAME} display=${VNC_DISPLAY} profile=${CHROMIUM_PROFILE_DIR} mode=${DISPLAY_MODE:-virtual}"
+    # Collision check runs BEFORE kill_stale: kill_stale removes the X lock
+    # file, so a check after kill_stale would always see an empty lock and
+    # never refuse. The check itself is a no-op for our own brand's prior
+    # Xtigervnc (kill_stale will reap it); it only refuses when the holder
+    # is unrelated to this brand's vnc.sh stack.
+    check_display_collision
     kill_stale
-    log "Starting Xtigervnc on :99"
+    log "Starting Xtigervnc on ${VNC_DISPLAY}"
 
-    Xtigervnc :99 \
+    Xtigervnc "${VNC_DISPLAY}" \
       -geometry 1280x800 \
       -depth 24 \
       -rfbport 5900 \
@@ -310,7 +369,7 @@ case "${1:-}" in
     ;;
 
   stop)
-    log "Stopping VNC stack"
+    log "[vnc.sh] stop brand=${BRAND_HOSTNAME} display=${VNC_DISPLAY}"
     kill_stale
     log "VNC stack stopped"
     ;;

package/payload/platform/templates/agents/admin/IDENTITY.md

@@ -247,9 +247,11 @@ When `<previous-context>` is present:
 
 When `<previous-context>` is absent, Neo4j was unreachable or no prior context exists — proceed normally, using tool calls to establish state.
 
-A separate `<recovery-context>` block on the user-message side appears only when the previous turn was aborted AND the platform could not perform a true SDK resume (the parent's pending tool_use_id was not captured, or the SDK session id was lost). Treat it as the authoritative description of what failed and what was incomplete — do not re-execute the failed work, do not call `session-list` to figure out what was happening, and do not re-research the blocker. The block coexists with `<previous-context>` (system-prompt session summary) on the recovery turn; the two are not duplicates — `<previous-context>` orients you to the session, `<recovery-context>` orients you to the specific failed turn.
+A `<recovery-context>` block on the user-message side appears whenever the previous turn was aborted by a stall recovery — both when the platform performed a true SDK resume AND when it fell back to a cold-create handoff. Treat it as the authoritative description of what failed, what was incomplete, and what to do now. Do not re-execute the failed work, do not call `session-list` to figure out what was happening, and do not re-research the blocker. The block coexists with `<previous-context>` (system-prompt session summary) on the recovery turn; the two are not duplicates — `<previous-context>` orients you to the session, `<recovery-context>` orients you to the specific failed turn.
 
-When the platform CAN resume, the recovery is invisible at the prompt layer: the prior conversation is replayed by the API and the next user message you receive contains a `tool_result` for the previously in-flight tool_use, summarising what completed before the pause. This means a "Continue" turn may arrive with no preamble — read the `tool_result` content to see how many sub-tasks completed, then continue the work. Do not assume a stalled subagent failed in approach: many stalls are upstream API latency, not the subagent's fault.
+The block has two shapes. The **resume variant** announces "a synthetic tool_result for the in-flight tool_use_id was just pushed above this message" and instructs you to read it for the completed-work summary, then resume by re-issuing the next pending step concretely. The **handoff variant** carries an LLM-generated continuation summary describing what was happening before the abort. In both shapes, the next operator message means resume the work — never treat it as empty, never ask "what would you like to do?", never wait for direction.
+
+The platform also operates an api-wait-ping liveness gate: a heartbeat-driven stall fire is suppressed while the SDK API request is still alive (most recent ping within the gate window), bounded by a 600 s cap. When the cap forces an abort, the synthetic tool_result names "API request stayed alive past the 600 s cap without producing tokens" — this is upstream API latency, not the subagent's approach. Do not infer specialist failure from a long stall; many stalls are not the subagent's fault.
 
 In managed context mode, conversation history is provided within `<conversation-history>` tags. Use `session-compact-status` to retrieve older archived context if needed.
 

package/payload/platform/templates/systemd/edge.service.template

@@ -26,7 +26,7 @@ Environment=MAXY_UI_HOST=127.0.0.1
 Environment=MAXY_UI_PORT=__MAXY_UI_PORT__
 Environment=WEBSOCKIFY_HOST=127.0.0.1
 Environment=WEBSOCKIFY_PORT=6080
-Environment=DISPLAY=:99
+Environment=DISPLAY=:__VNC_DISPLAY__
 Environment=MAXY_PLATFORM_ROOT=__INSTALL_DIR__/platform
 Environment=PATH=%h/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
 StandardOutput=append:__PERSIST_DIR__/logs/edge.log