@rubytech/create-realagent 1.0.654 → 1.0.656

package/payload/platform/plugins/cloudflare/scripts/_stream-log.sh

@@ -7,27 +7,38 @@
 # per-conversation file the chat UI's server-side tailer reads.
 #
 # Contract (read by platform/ui/app/lib/script-stream-tailer.ts tailer and
-# .docs/platform.md):
-#   [<ISO-ts>] [<scope>] <kv …>
-#   [<ISO-ts>] [<scope>:<subprocess-tag>] <raw line>
-# Canonical regex — SCRIPT_STREAM_RE at platform/ui/app/lib/script-stream-tailer.ts:51:
-#   ^\[([^\]]+)\] \[([a-z][a-z0-9-]*)((?::[a-z0-9:_-]+)?)\] (.*)$
+# .docs/web-chat.md):
+#   [<ISO-ts>] [script:<scope>] <kv …>
+#   [<ISO-ts>] [script:<scope>:<subprocess-tag>] <raw line>
+# Canonical regex — SCRIPT_STREAM_RE at platform/ui/app/lib/script-stream-tailer.ts:
+#   ^\[([^\]]+)\] \[script:([a-z][a-z0-9-]*)((?::[a-z0-9:_-]+)?)\] (.*)$
+# The literal `script:` prefix is the chat-surface namespace (Task 605). It
+# separates chat-surface emitters from log-file-only scopes (`[mcp:<server>]`
+# from mcp-stderr-tee, `[init]` / `[api-wait-*]` / `[mcp-init-error]` /
+# `[subproc-stderr]` / `[compaction-*]` from claude-agent.ts) which share
+# the same per-conversation stream log but must NOT reach the chat UI.
+# Callers of phase_line / tee_subprocess / tee_subprocess_capture pass the
+# bare scope (e.g. `setup-tunnel`, `list-cf-domains`, `reset-tunnel:cloudflared`);
+# these helpers prepend `script:` to the stream-log write. Stderr mirrors
+# stay unprefixed — stderr is for direct-SSH operators and route-handler
+# `reason=<enum>` regex, not the chat-surface contract.
 # <scope> is any `[a-z][a-z0-9-]*` token (Task 592 generalised from the
 # pre-592 enum `setup-tunnel|reset-tunnel`, which silently filtered out the
 # `[list-cf-domains]` lines Task 589 emitted). <subprocess-tag> may contain
-# lowercase, digits, `-`, `_`, `:`. Adding a new <scope> requires no edit to
-# the regex — the shape is the only contract. Any prefix-shape change must
-# be made on both sides (this helper + script-stream-tailer.ts) atomically.
+# lowercase, digits, `-`, `_`, `:`. Adding a new chat-surface scope requires
+# no edit to the regex — the shape is the only contract. Any prefix-shape
+# change must be made on both sides (this helper + script-stream-tailer.ts)
+# atomically.
 #
 # Inner layers (e.g. a node/python helper a .sh wrapper spawns — Task 598's
 # `list-cf-domains.sh` → `list-cf-domains.ts` pattern) must write phase lines
-# directly to STREAM_LOG_PATH with the same prefix shape: stderr alone is
-# silently discarded by runFormSpawn on exit 0. The build-gate
-# `platform/ui/scripts/check-stream-log-contract.mjs` (Task 600) enforces this
-# by rejecting any .sh under `platform/plugins/*/scripts/` that sources this
-# helper and invokes an interpreter subprocess whose target does not pair a
-# STREAM_LOG_PATH env read with an append/write call. Opt out per invocation
-# with `# stream-log-contract: stderr-only (reason: <prose>)`.
+# directly to STREAM_LOG_PATH with the same prefix shape (including the
+# `script:` namespace): stderr alone is silently discarded by runFormSpawn on
+# exit 0. The build-gate `platform/ui/scripts/check-stream-log-contract.mjs`
+# (Task 600) enforces this by rejecting any .sh under `platform/plugins/*/scripts/`
+# that sources this helper and invokes an interpreter subprocess whose target
+# does not pair a STREAM_LOG_PATH env read with an append/write call. Opt out
+# per invocation with `# stream-log-contract: stderr-only (reason: <prose>)`.
 
 # Exit 1 loudly with the variable name and the invoking scope so direct-SSH
 # invocations fail fast and the operator reads exactly what to set. No
@@ -56,12 +67,16 @@ stream_log_ts() {
 # tool's stderr capture carries it. Both paths matter: the stream log is
 # the live tailer surface; stderr is the exit-time Bash-tool surface.
 #
+# The stream-log write carries the `script:` chat-surface namespace (Task 605);
+# the stderr mirror stays unprefixed because stderr is read by direct-SSH
+# operators and the route-handler `reason=<enum>` regex, not the chat UI.
+#
 # Usage: phase_line <scope> <key=value …>
 phase_line() {
   local scope="$1"; shift
   local ts
   ts="$(stream_log_ts)"
-  printf '[%s] [%s] %s\n' "${ts}" "${scope}" "$*" >> "${STREAM_LOG_PATH}"
+  printf '[%s] [script:%s] %s\n' "${ts}" "${scope}" "$*" >> "${STREAM_LOG_PATH}"
   printf '[%s] %s\n' "${scope}" "$*" >&2
 }
 
@@ -97,7 +112,7 @@ tee_subprocess() {
   "${buf_prefix[@]}" "$@" 2>&1 | while IFS= read -r line; do
     local ts
     ts="$(stream_log_ts)"
-    printf '[%s] [%s] %s\n' "${ts}" "${tag}" "${line}" >> "${STREAM_LOG_PATH}"
+    printf '[%s] [script:%s] %s\n' "${ts}" "${tag}" "${line}" >> "${STREAM_LOG_PATH}"
     printf '%s\n' "${line}" >&2
   done
   return "${PIPESTATUS[0]}"
@@ -132,7 +147,7 @@ tee_subprocess_capture() {
   "${buf_prefix[@]}" "$@" 2>&1 | while IFS= read -r line; do
     local ts
     ts="$(stream_log_ts)"
-    printf '[%s] [%s] %s\n' "${ts}" "${tag}" "${line}" >> "${STREAM_LOG_PATH}"
+    printf '[%s] [script:%s] %s\n' "${ts}" "${tag}" "${line}" >> "${STREAM_LOG_PATH}"
     printf '%s\n' "${line}"
   done
   return "${PIPESTATUS[0]}"

package/payload/platform/plugins/cloudflare/scripts/list-cf-domains.ts

@@ -91,15 +91,18 @@ function logPhase(line: string): void {
   // Stream log: direct write by the TS helper (not via wrapper tee) so phase
   // lines reach the per-conversation file the Task 592 tailer reads, even on
   // exit 0 where runFormSpawn discards `result.stderr`. Format parity with
-  // `_stream-log.sh phase_line`: `[<ISO-ts>] [<scope>] <content>\n`, asserted
-  // by the vitest regression under platform/ui/__tests__. Sync append so the
+  // `_stream-log.sh phase_line`: `[<ISO-ts>] [script:<scope>] <content>\n` —
+  // the `script:` prefix is Task 605's chat-surface namespace so the line
+  // passes the tightened tailer regex (`[mcp:*]` / `[init]` / `[api-wait-*]`
+  // lines in the same file are excluded by construction). Asserted by the
+  // vitest regression under platform/ui/__tests__. Sync append so the
   // terminal `phase=script-exit code=0 count=N` lands before process exit.
   const streamLogPath = process.env.STREAM_LOG_PATH;
   if (!streamLogPath || streamLogWriteFailed) return;
   try {
     appendFileSync(
       streamLogPath,
-      `[${new Date().toISOString()}] [list-cf-domains] ${line}\n`,
+      `[${new Date().toISOString()}] [script:list-cf-domains] ${line}\n`,
     );
   } catch (err) {
     streamLogWriteFailed = true;
@@ -368,6 +371,79 @@ export type CdpEvaluator = (expression: string) => Promise<unknown>;
 // without proportional robustness.
 const STABLE_POLL_THRESHOLD = 2;
 
+// Cap the `domains=[…]` payload on per-poll and complete phase lines. The
+// extractor already implicitly bounds the list via the FQDN regex + Set
+// dedupe, but a pathological CF redesign could emit thousands of href
+// matches; the cap keeps the stream log readable without masking the real
+// capture size (the `count=` field carries the exact n).
+const DOMAINS_PAYLOAD_MAX_CHARS = 1000;
+
+function formatDomains(domains: string[]): string {
+  const joined = domains.join(",");
+  return joined.length > DOMAINS_PAYLOAD_MAX_CHARS
+    ? joined.slice(0, DOMAINS_PAYLOAD_MAX_CHARS - 3) + "..."
+    : joined;
+}
+
+type DumpMode = "stable" | "unstable" | "empty-or-drift";
+type DumpResult = { path: string } | { err: string };
+
+// Snapshot the operator's current dashboard HTML so post-hoc diagnosis of a
+// partial, unstable, or empty scrape has the exact DOM the scrape observed
+// at exit. Called on all three `scrapeDomains` exit paths — the filename's
+// `mode` field names which path fired, and the `pid<pid>` suffix prevents
+// collision if two invocations land in the same millisecond. Loud-fail
+// preserved: on any throw (evaluator rejected, CONFIG_DIR unset, writeFile
+// ENOENT), return `{err}` so the caller emits a separate
+// `phase=dump-write-failed` line and the complete line carries
+// `dump=failed`. The scrape's real signal must never be masked.
+async function dumpHtml(
+  evaluator: CdpEvaluator,
+  count: number,
+  mode: DumpMode,
+): Promise<DumpResult> {
+  try {
+    const html = (await evaluator(
+      "document.documentElement.outerHTML.slice(0, 100000)",
+    )) as string;
+    // CONFIG_DIR is set by list-cf-domains.sh before the spawn. A silent
+    // fallback would dump logs into the wrong brand's directory on a Real
+    // Agent install — a silent-miswrite masking the wrapper-side break it
+    // came from. Per Task 473 doctrine: loud-fail on absent runtime-derived
+    // values.
+    const configDir = process.env.CONFIG_DIR;
+    if (!configDir) {
+      throw new Error(
+        "CONFIG_DIR env var not set by wrapper — refusing to guess brand log directory",
+      );
+    }
+    const logDir = resolve(homedir(), configDir, "logs");
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const dumpPath = resolve(
+      logDir,
+      `list-cf-domains-${ts}-count${count}-${mode}-pid${process.pid}.html`,
+    );
+    await writeFile(dumpPath, typeof html === "string" ? html : String(html), "utf-8");
+    return { path: dumpPath };
+  } catch (err) {
+    return {
+      err: (err instanceof Error ? err.message : String(err)).slice(0, 120),
+    };
+  }
+}
+
+// Render the `dump=<path>` field for a complete-line, and emit a separate
+// loud-fail `phase=dump-write-failed` line on failure. Keeps the on-success
+// complete line terse and routes every failure through the same observation
+// primitive so investigators have one grep pattern for all dump write errors.
+function dumpField(result: DumpResult, mode: DumpMode): string {
+  if ("path" in result) return `dump=${result.path}`;
+  logPhase(
+    `phase=dump-write-failed mode=${mode} detail="${result.err.replace(/"/g, "'")}"`,
+  );
+  return "dump=failed";
+}
+
 export async function scrapeDomains(evaluator: CdpEvaluator): Promise<string[]> {
   const deadline = Date.now() + SCRAPE_POLL_MS;
   let lastOutcome: ScrapeOutcome | null = null;
@@ -385,13 +461,25 @@ export async function scrapeDomains(evaluator: CdpEvaluator): Promise<string[]>
       const outcome = (await evaluator(SCRAPE_EXPRESSION)) as ScrapeOutcome;
       lastOutcome = outcome;
 
+      // Per-poll trajectory line (Task 608). Names the exact list captured at
+      // this iteration so a partial-capture scenario (e.g. 2-zone account
+      // rendering count=1 on poll K because zone B has not hydrated yet) is
+      // legible from the stream log alone. Emitted only on successful
+      // evaluator returns — the catch branch emits `phase=scrape-retry`
+      // instead, because "zero observed" and "failed to observe" are
+      // semantically distinct signals for a downstream reader.
+      logPhase(
+        `phase=dom-scrape-poll n=${polls} count=${outcome.domains.length} domains=[${formatDomains(outcome.domains)}]`,
+      );
+
       if (outcome.reason === "ok" && outcome.domains.length > 0) {
         lastNonEmptyDomains = outcome.domains;
         if (outcome.domains.length === stableCount) {
           stableIterations += 1;
           if (stableIterations >= STABLE_POLL_THRESHOLD) {
+            const dump = await dumpHtml(evaluator, outcome.domains.length, "stable");
             logPhase(
-              `phase=dom-scrape-complete result=ok count=${outcome.domains.length} polls=${polls} stable_polls=${stableIterations} unstable=false`,
+              `phase=dom-scrape-complete result=ok count=${outcome.domains.length} polls=${polls} stable_polls=${stableIterations} unstable=false domains=[${formatDomains(outcome.domains)}] ${dumpField(dump, "stable")}`,
             );
             return outcome.domains;
           }
@@ -409,7 +497,7 @@ export async function scrapeDomains(evaluator: CdpEvaluator): Promise<string[]>
       }
     } catch (err) {
       logPhase(
-        `phase=scrape-retry err="${(err instanceof Error ? err.message : String(err)).slice(0, 120)}"`,
+        `phase=scrape-retry n=${polls} err="${(err instanceof Error ? err.message : String(err)).slice(0, 120)}"`,
       );
     }
     await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
@@ -419,10 +507,10 @@ export async function scrapeDomains(evaluator: CdpEvaluator): Promise<string[]>
   //
   // (i) We saw non-empty results but they never stabilised across two
   //     consecutive polls — the page is either paginating or re-rendering
-  //     the zone list. Return the last non-empty observation and flag
-  //     `unstable=true` on the phase line so the operator can see the race
-  //     in the stream log. This is NOT drift — the HTML dump would be
-  //     misleading noise, so we suppress it.
+  //     the zone list. Return the last non-empty observation, flag
+  //     `unstable=true` on the phase line, and snapshot the DOM so
+  //     partial-capture-that-also-races is diagnosable (Task 608 extends
+  //     the dump to this path — pre-task, only empty-or-drift dumped).
   //
   // (ii) We never saw non-empty results — this is either a genuinely empty
   //      account OR CF has drifted the href URL shape so Source A yields
@@ -430,37 +518,17 @@ export async function scrapeDomains(evaluator: CdpEvaluator): Promise<string[]>
   //      HTML so the operator can distinguish the two by inspecting the
   //      dump file.
   if (lastNonEmptyDomains.length > 0) {
+    const dump = await dumpHtml(evaluator, lastNonEmptyDomains.length, "unstable");
     logPhase(
-      `phase=dom-scrape-complete result=ok count=${lastNonEmptyDomains.length} polls=${polls} stable_polls=${stableIterations} unstable=true`,
+      `phase=dom-scrape-complete result=ok count=${lastNonEmptyDomains.length} polls=${polls} stable_polls=${stableIterations} unstable=true domains=[${formatDomains(lastNonEmptyDomains)}] ${dumpField(dump, "unstable")}`,
     );
     return lastNonEmptyDomains;
   }
 
-  try {
-    const html = (await evaluator("document.documentElement.outerHTML.slice(0, 100000)")) as string;
-    // CONFIG_DIR is set by list-cf-domains.sh before the spawn. A silent
-    // fallback would dump logs into the wrong brand's directory on a Real
-    // Agent install — a silent-miswrite masking the wrapper-side break it
-    // came from. Per Task 473 doctrine: loud-fail on absent runtime-derived
-    // values.
-    const configDir = process.env.CONFIG_DIR;
-    if (!configDir) {
-      throw new Error(
-        "CONFIG_DIR env var not set by wrapper — refusing to guess brand log directory",
-      );
-    }
-    const logDir = resolve(homedir(), configDir, "logs");
-    const ts = new Date().toISOString().replace(/[:.]/g, "-");
-    const dumpPath = resolve(logDir, `list-cf-domains-${ts}.html`);
-    await writeFile(dumpPath, typeof html === "string" ? html : String(html), "utf-8");
-    logPhase(
-      `phase=dom-scrape-complete result=empty-or-drift dump=${dumpPath} lastReason=${lastOutcome?.reason ?? "unknown"} polls=${polls}`,
-    );
-  } catch (err) {
-    logPhase(
-      `phase=dom-scrape-complete result=empty-or-drift dump=failed lastReason=${lastOutcome?.reason ?? "unknown"} polls=${polls} err="${(err instanceof Error ? err.message : String(err)).slice(0, 120)}"`,
-    );
-  }
+  const dump = await dumpHtml(evaluator, 0, "empty-or-drift");
+  logPhase(
+    `phase=dom-scrape-complete result=empty-or-drift count=0 polls=${polls} lastReason=${lastOutcome?.reason ?? "unknown"} ${dumpField(dump, "empty-or-drift")}`,
+  );
   return [];
 }
 

package/payload/platform/plugins/cloudflare/scripts/setup-tunnel.sh

@@ -65,7 +65,8 @@ mkdir -p "${CFG_DIR}"
 # Control flow, rewritten per Task 556:
 #   1. CDP precheck on 127.0.0.1:9222 — loud failure if Chromium isn't up.
 #   2. Spawn cloudflared with stdout+stderr teed line-by-line to
-#      $STREAM_LOG_PATH with prefix [setup-tunnel:cloudflared].
+#      $STREAM_LOG_PATH with prefix [script:setup-tunnel:cloudflared]
+#      (Task 605's chat-surface namespace — see _stream-log.sh header).
 #   3. Extract the authorize URL with a tolerant regex as it streams.
 #   4. Drive the VNC Chromium to that URL via CDP `PUT /json/new?<url>`.
 #   5. Wait for ~/.cloudflared/cert.pem to land with bounded timeout.
@@ -113,7 +114,7 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
       --origincert "${CFG_DIR}/cert.pem" tunnel login 2>&1 |
       while IFS= read -r line; do
         ts="$(stream_log_ts)"
-        printf '[%s] [setup-tunnel:cloudflared] %s\n' "${ts}" "${line}" >> "${STREAM_LOG_PATH}"
+        printf '[%s] [script:setup-tunnel:cloudflared] %s\n' "${ts}" "${line}" >> "${STREAM_LOG_PATH}"
         printf '%s\n' "${line}" >&2
         printf '%s\n' "${line}" > "${LAST_LINE_FILE}"
         if [ ! -s "${URL_FILE}" ]; then
@@ -418,8 +419,8 @@ for H in "${HOSTNAMES[@]}"; do
   phase_line setup-tunnel step=route-dns hostname="${H}" tunnel_id="${TUNNEL_ID}"
   ROUTE_LOG="$(mktemp -t maxy-route-dns.XXXXXX)"
   # tee_subprocess_capture streams cloudflared's combined stdout+stderr
-  # into STREAM_LOG_PATH line-by-line with the [setup-tunnel:cloudflared]
-  # tag (live-tailable) AND passes the same output through this shell's
+  # into STREAM_LOG_PATH line-by-line with the [script:setup-tunnel:cloudflared]
+  # tag (live-tailable — Task 605 chat-surface namespace) AND passes the same output through this shell's
   # stdout so the `> "${ROUTE_LOG}"` redirection can capture it for the
   # failure-path phase_line. Exit code is cloudflared's PIPESTATUS[0].
   if tee_subprocess_capture setup-tunnel:cloudflared -- \

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

@@ -0,0 +1,98 @@
+# Adherence Fidelity
+
+User-facing reference for the attention-weighted correction ledger that makes agent adherence compound. Canonical platform documentation lives at [`.docs/agents.md`](../../../../.docs/agents.md) § Adherence Fidelity — this reference mirrors the same behaviour for operators reading plugin docs.
+
+---
+
+## What it solves
+
+The agent's prerogatives (PRECISE, CONCISE, EVIDENCE-BASED) are prose at the top of every system prompt. Without a compounding mechanism, a rule corrected 50 times has the same attention weight as a rule corrected once. Adherence Fidelity adds a per-agent ledger whose rendered summary is inserted into the system prompt every turn, so the agent sees its own recidivism with counts, samples, and recency.
+
+## How an operator sees it
+
+**In chat:** ask the agent *"what is my adherence score?"* or *"what are my top rule violations?"* The admin agent answers via the `adherence-read` tool, which reads the ledger file on disk — the number is authoritative.
+
+**Via API:** `GET /api/admin/adherence?agent=admin` returns the ledger JSON, plus `constraints` (whether capability routing is active for the next turn) and an optional `rendered` block when called with `?block=1`.
+
+**On the filesystem:** `{accountDir}/agents/{agentName}/adherence-ledger.json` is the source of truth. `jq` queries work directly:
+
+```bash
+jq '{score, top: (.rules | sort_by(-.count) | .[0])}' \
+  ~/.maxy/<accountId>/agents/admin/adherence-ledger.json
+```
+
+## Score
+
+```
+score = 100 × (1 − rules_violating_in_rolling_7d / n_rules)
+```
+
+An agent with three rules, zero of which have a violation in the last 7 days, scores 100%. One out of three scores 67%. All three scores 0%.
+
+## Top offenders
+
+The rendered ledger block bolds the top-3 rules by `count` (all-time, not just the rolling window) and quotes their most recent `last_sample`. Rules 4 through 10 appear as one-liners. Zero-recidivism rules (`count = 0` and `rolling_7d = 0`) are omitted entirely.
+
+Sort order: `count DESC, last_violated_at DESC`.
+
+## Capability routing at threshold
+
+When any rule's `rolling_7d` reaches `5`, the next turn's spawn is clamped:
+
+- `--max-turns` drops to `5` — the agent has fewer turns to sprawl.
+- Non-core tools drop from the allowed set (currently the specialist roles).
+- The offending rule renders with a `BLOCKING:` prefix in the ledger block so it dominates the prompt.
+
+The constraint is computed once per turn at the top of `invokeAgent` and frozen for that spawn — one-turn granularity. The next turn reads the updated ledger and re-evaluates, so a single clean turn begins to lift the constraint as `rolling_7d` decays.
+
+## Data flow per turn
+
+```
+┌─ Pre-turn ────────────────────────────────────┐
+│ loadAdherenceLedger(accountDir, accountId)    │
+│ renderAdherenceLedger(ledger, blockingRules)  │
+│ → inject at <!-- ADHERENCE-LEDGER-INSERT -->  │
+│ computeConstraints(ledger)                    │
+│ → clamp max-turns, drop tools                 │
+└────────────────────────────────────────────────┘
+                    │
+                    ▼
+              Assistant stream
+                    │
+                    ▼
+┌─ Post-turn ───────────────────────────────────┐
+│ criticAndRecord(responseText) — Haiku         │
+│ → verdict=pass   → recordPass()               │
+│ → verdict=violation → recordViolation()       │
+│ Fire-and-forget. Non-blocking.                │
+└────────────────────────────────────────────────┘
+```
+
+## What the ledger file looks like
+
+```json
+{
+  "agent_id": "admin",
+  "account_id": "abc123...",
+  "rules": [
+    {
+      "rule_id": "PRECISE",
+      "canonical_text": "Use exact names...",
+      "rule_family": "prerogative",
+      "count": 7,
+      "violations": ["2026-04-19T10:12:00Z", "..."],
+      "last_violated_at": "2026-04-21T09:30:12Z",
+      "last_sample": "Something that paraphrased tool output…",
+      "current_streak": 2,
+      "rolling_7d": 5
+    }
+  ],
+  "updated_at": "2026-04-21T09:30:13Z"
+}
+```
+
+## Limits and deferrals
+
+v1 covers the admin agent only. Specialist subagents (`personal-assistant`, `project-manager`, `research-assistant`, `content-producer`) do not receive their own ledger injection yet — their `.md` templates load via `--plugin-dir` and have no TS-side assembly site. Follow-up task filed.
+
+No cross-agent rule inheritance, no user-visible correction-ack signal, no blocking-critic retry loop in v1 — each is a separate follow-up task. See [`.docs/agents.md`](../../../../.docs/agents.md) § Adherence Fidelity for the full deferral list with task numbers.

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

@@ -8,7 +8,7 @@ Each installation has its own Cloudflare account. Sign-in is OAuth in the device
 |------|--------|
 | **Product identity** (Maxy vs Real Agent) | `brand.json` (`productName`, `configDir`) — known at install. |
 | **Cloudflare account identity** | `cert.pem` from OAuth. One account per brand per device. |
-| **Domain scope** (which zones the operator can route) | Live Cloudflare dashboard at form-render time via `list-cf-domains.sh`, not `brand.json`. Brand identity has no authority over which domains the operator's CF account holds. |
+| **Domain scope** (which zones the operator can route) | Live Cloudflare dashboard at form-render time via `list-cf-domains.sh`, not `brand.json`. Brand identity has no authority over which domains the operator's CF account holds. When the scrape returns an unexpected count (e.g. 1 on a two-zone account), the stream log's per-poll `phase=dom-scrape-poll n=<k> count=<n> domains=[…]` trajectory + the on-disk HTML dump at `~/{configDir}/logs/list-cf-domains-<ts>-count<n>-<mode>-pid<pid>.html` (Task 608 — written on every scrape outcome, not just empty ones) give the operator everything they need to triage the cause without re-running. |
 | **Local tunnel state** | `~/{configDir}/cloudflared/` — `cert.pem`, `<UUID>.json`, `config.yml`, `tunnel.state`, `alias-domains.json`. |
 
 There is no token-based auth for the operator-owned path (Mode A). To switch Cloudflare accounts, run `reset-tunnel.sh` (which deletes the cert and every tunnel on the current account), then run `setup-tunnel.sh` again — `cloudflared tunnel login` inside the setup script will pick a fresh account when you sign in.

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

@@ -68,7 +68,7 @@ The admin UI includes a live terminal surface that opens a real shell on your Pi
 
 The tmux session outlives admin-server restarts — running an upgrade inside this terminal means you see the live shell output continuously, even through the admin server's own restart mid-upgrade. Closing the browser tab does not kill the running work; re-opening the Software Update window reattaches to the same session during an active upgrade and scrollback shows everything that happened in the meantime. Password-protected `sudo` prompts appear natively inside the terminal, and the password you type never leaves the Pi — the admin-server proxy is a raw byte pipe that never inspects frame payloads.
 
-The Software Update window mounts the terminal lazily: the WebSocket is opened on the first Upgrade click, not when the window opens. Until you click Upgrade, the terminal area shows "Ready to upgrade." and no network traffic flows. If the admin server cannot reach `ttyd`, the window renders an inline "Admin terminal not available" message with the exact re-install command and a Try again button — no silent reconnect loops, no empty black rectangle. The scrollback-across-reopen behaviour above still applies during an active upgrade (a sessionStorage flag remembers that an upgrade is in flight so reopening the window re-mounts the terminal and reattaches).
+The Software Update window mounts the terminal lazily: neither the terminal, its WebSocket, nor its black-backgrounded container render until you click Upgrade. Pre-click, the window shows a small "Ready to upgrade — click Upgrade to begin." line, no network traffic flows, and the upgrade UI is the lifecycle indicator — not the terminal. After you click, the window adds a status row above the terminal ("Upgrading to v… · elapsed: Ns · Downloading installer…" flipping to "Running installer…" on the first byte of installer output) so the 5–30 second npx cold-start window is never silent. The upgrade command is dispatched the moment the WebSocket opens — you won't see "terminal not ready" warnings on a healthy device. If the admin server cannot reach `ttyd`, the window renders an inline "Admin terminal not available" message with the exact re-install command and a Try again button. The scrollback-across-reopen behaviour above still applies during an active upgrade (a sessionStorage flag remembers that an upgrade is in flight so reopening the window re-mounts the terminal and reattaches; the elapsed counter keeps ticking from the original start time).
 
 ## AI Content Provenance
 

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

@@ -125,6 +125,20 @@ npx -y @rubytech/create-maxy@latest
 
 Then return to the upgrade window and click **Try again**. The window re-probes `/api/health` and, once ttyd is listening, the terminal area mounts as normal. If the problem persists, check the boot log for `[ttyd] upstream NOT reachable on 127.0.0.1:7681` and follow the `maxy-ttyd` restart steps above.
 
+## Upgrade spinner turns but terminal stays blank
+
+**Symptom:** You clicked **Upgrade**, the progress row is showing with an elapsed counter ticking, but the terminal area below stays empty for more than about a minute with no output.
+
+**What it means:** The upgrade command was dispatched successfully (`onReady` fired), but `ttyd` is not relaying any bytes back from the installer — the `npx` process may have crashed before it printed anything, or `ttyd` itself has lost its PTY.
+
+**Fix:** SSH to the device and check the ttyd unit:
+
+```bash
+sudo systemctl --user status maxy-ttyd
+```
+
+If it's not running, restart it with `sudo systemctl --user restart maxy-ttyd`. Then close and reopen the Software Update window. If `ttyd` is healthy and the spinner keeps turning with no output, the installer process itself has died — re-run `npx -y @rubytech/create-maxy@latest` from an SSH shell directly.
+
 ## Orphan Account Directory Archived to `.trash/`
 
 **What happened:** During upgrade, the installer detected multiple account directories under `~/maxy/data/accounts/` and identified one as live (its `admins` list matches the device's `users.json`). Non-matching siblings are archived — not deleted — under `~/maxy/data/accounts/.trash/<uuid>-<ISO8601-ts>/`.

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

@@ -16,6 +16,8 @@ Three rules govern every turn. They are load-bearing — when they conflict with
 
 A landfill graph defeats EVIDENCE-BASED: search returns noise, the agent re-writes the noise, the noise compounds. Compress on write; filter on read.
 
+<!-- ADHERENCE-LEDGER-INSERT -->
+
 ---
 
 ## Intent Gate — First Principle

package/payload/server/package.json

@@ -6,6 +6,7 @@
     "neo4j-driver": "^6.0.1",
     "@anthropic-ai/sdk": "^0.55.0",
     "@whiskeysockets/baileys": "7.0.0-rc.9",
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "proper-lockfile": "^4.1.2"
   }
 }