feat: completion-enforcement loop (fallback, proof, emit-model, auditor)

Close the loop so dispatched work actually completes on bl:

- on_no_result fallback in followup-sweeper (op + job forms via
  exec-constrained registry / job-dispatch), seeded on the three
  autonomy-pulse jobs; fallback_due() dedupes the gravity path
- gravity.py: add __main__ entry (loop-remediator.timer was a no-op),
  300s re-arm budget, fallback firing + stamp/skip logic
- harvester: proof-of-result followups (result_has_evidence),
  acted-variant NACK, emit-model tool-hint wording
- envelope: RESPONSE RULE states the emit model (agents EMIT
  directives verbatim; runtime executes; works from bare containers)
- completion-audit.py + systemd 15-min timer: per-family funnel,
  swarm drain, followup backlog; digest DM when degraded, 6h heartbeat
- tests/test_completion.py (29 tests), JOB-SPEC.md docs

Tests: 67/67 focused green (completion + tool_calls).

.agents/skills/box/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: box
+description: Use the box CLI to check NetVM fleet health and read the latest from each agent.
+---
+
+# Box Fleet CLI
+
+Use `box` (`/usr/local/bin/box`, the NetVM unified orchestrator CLI) for all fleet observation and agent coordination. Prefer read-only lookups first; coordinate via sidechats, never Main Chat dumps.
+
+Nodes (node == agent == profile): `muse`, `pip`, `646`, `opm`, `def`, `dev`.
+
+## Latest From Each Agent (Default Workflow)
+
+1. `box fleet status` — node health, CDP status, active page/thread.
+2. `box lookup unread` — unread counts across agents.
+3. `box lookup threads` — registered threads and sidechats.
+4. Per agent with activity: `box thread list <agent>`, then `box thread view <agent> <thread_id> --limit 10` (use the thread UUID from the list; `main` only for urgent human-visible items).
+5. `box dm log -n 20` (or `--agent <agent>`) — recent inter-agent DMs, work orders, and acks.
+6. `box approvals check` — agents blocked on browser or key approval.
+
+Add `--json` to any command for machine-readable output when parsing results in scripts.
+
+## Common Commands
+
+- `box fleet status` / `box fleet cdp <node>` — health table / CDP endpoint plus SSH forward.
+- `box thread list [<agent>]` — threads for one agent, or all fleet sidechats when omitted.
+- `box thread view <agent> <thread_id|main> --limit N` — recent messages from one thread.
+- `box dm log -n N [--agent X] [--filter TEXT]` — recent DM activity.
+- `box dm send --agent <self> --to <peer> --target <sidechat> "<msg>"` — peer DM.
+- `box lookup summary|fleet|threads|unread|approvals` — seamless one-shot lookups.
+- `box job list` / `box job log` — scheduled jobs and execution events.
+- `box harvest status` / `box followup list` — harvest watermarks / pending nudges.
+
+## Rules
+
+- Sidechat-first per `CHAT_POLICY.md`: `646 tasks`, `heartbeat` (opm), `646-pip-coord`, `646-opm-coord`. Never route routine checks or coordination through `main`.
+- Never paste multi-KB logs or dumps into chat; write payloads under `logs/` and send a short path pointer instead.
+- Avoid blocking commands in automated runs: `box fleet watch`, `box dm tail`, `box approvals watch`, `box dm chat` (interactive REPL).
+- `box` probes CDP per node and can take several seconds; use generous timeouts and `--json` for scripted use.

.gitignore

@@ -25,3 +25,5 @@ ssl/
 job-scheduler-state.json
 var/
 swarms.json
+subagent-sessions.json
+conversation-nudge-tracker.json

README.md

@@ -140,19 +140,23 @@ veth IPs aren't routable off the host and Warp forwards no inbound traffic.
 - `bin/accounts-health.py` — per-account CDP session probe (runs inside the netns).
 - `bin/accounts-health.sh` — aggregates account vitality from ACCOUNTS.md,
   signs + POSTs to the board health ingest (systemd timer, every 15 min).
-- `bin/muse -a <account> [args]` — interactive terminal entrypoint for muse-cli; enforces account selection, auto-refreshes CDP cookies, and provides interactive email/OTP prompt fallback.
+- `bin/muse` (or `box muse`) — native terminal entrypoint for muse-cli; supports global lookups (`muse status`, `muse threads`, `muse unread`, `muse lookup`, `muse passkey`, `muse tmux`), per-account REPL chats (`muse <account> chat`), and automated CDP cookie extraction.
+- `bin/super-cli.py` (`box` or `super`) — unified orchestrator CLI for fleet health (`box fleet`), seamless lookups (`box lookup`), thread inspections (`box thread list/view`), background tmux (`box tmux`), and passkey reference (`box passkey`).
 - `bin/muse-cli-node <node> [args]` — runs muse-cli inside node's netns with dedicated Cloudflare WARP egress & auto-refreshing cookies.
 - `bin/refresh-node-cookies.py <node>` — extracts fresh cookies from running Chromium CDP in netns into `~/.config/muse-cli/<node>/cookies.txt`.
 - `bin/muse_hybrid.py` — programmatic hybrid bridge combining fast gateway calls with CDP fallbacks.
-- `bin/muse-tmux.py` — shared tmux socket manager (`/tmp/tmux-muse.sock`) for agent background execution, pipe-pane logging, and 2h session pruning.
+- `bin/muse-tmux.py` (`box tmux` / `muse tmux`) — shared tmux socket manager (`/tmp/tmux-muse.sock`) for agent background execution, pipe-pane logging, hybrid netns/container execution, and session pruning.
 - `bin/agent_md.py` — CLI & library for auditing, reading, writing, and synchronizing agent `.md` drive files (`SOUL.md`, `PROACTIVE_PREFERENCES.md`, `HEARTBEAT.md`, etc.) across containers via Hatch WebSocket RPC.
 - `bin/agent-drive-watchdog.py` — background drive watchdog and auto-healing daemon (every 10m via `agent-drive-watchdog.timer`).
 - `bin/swarm_worker/` & `bin/swarm-worker-supervise.sh` — supervised autonomous swarm worker daemon executing queued tasks in a hard sandbox.
 - `bin/fleet-alert-relay.sh` — idempotent alert relay with 3-gate deduplication (watermark + 10m TTL hash + receipt verification) posting critical conditions to `#lobby`.
 - `shared/operators/` — canonical operator drive markdown templates ensuring agents maintain autonomous loops, active supervision, and self-healing reflexes.
 - docs/OPERATOR-DRIVE-RUNBOOK.md — operator runbook for auditing and modifying agent `.md` files via Hatch WebSocket RPC and SSH reverse tunnels.
+- docs/BOX-WEB-SURFACE-GUIDE.md — Box web surface (`box.muse-dev.online`), passkey reality (single .txt file on VM), and agent approval flow.
 - docs/HYBRID-GATEWAY-ADAPTATION.md — architectural guide on the muse-cli fast gateway adaptation and per-node egress isolation.
-- docs/AGENT-TOOLING.md — guide to agent delegation, shared tmux background tooling, Work Orders (`[WO:...]`), and prompt envelope execution.
+- docs/AGENT-TOOLING.md — guide to agent delegation, seamless lookups, shared tmux background tooling, Work Orders (`[WO:...]`), and prompt envelope execution.
+- `bin/docs-lookup.py` (`box docs` / `super docs` / `docs-lookup`) — internal documentation, sentence structure grammar, regex passing engine, and assistive surfaces for `box.muse-dev.online`.
+- `docs_internal/` — dual `.md` and structured `.json` lookup database for autonomous agents, protocol definitions, regex fixtures, and surface selectors.
 
 
 ## Verification checklist

bin/box-ctl.py

@@ -58,6 +58,7 @@ NOTIFY_SIDECHATS = {
     "pip": "pip tasks",
     "muse": "muse tasks",
     "dev": "onboarding-dev",
+    "def": "def tasks",
 }
 VALID_ON_FAILURE = {"retry", "alert", "ignore"}
 KNOWN_PLACEHOLDERS = {"job_id", "job_name", "datetime", "date", "last_run"}
@@ -989,12 +990,13 @@ def act_approval_check(node=None):
     out(True, approvals=res)
 
 
-def act_approval_allow(node, always=False, force=False):
+def act_approval_allow(node, always=False, force=False, message=None, allow_main_chat=False):
     audit("approval-allow", node)
     if node not in VALID_AGENTS:
         fail("BAD_NODE", f"unknown node: {node}")
     import approvals
-    res = approvals.allow_node_approval(node, always=always, force=force, caller="box-ctl")
+    res = approvals.allow_node_approval(node, always=always, force=force, caller="box-ctl",
+                                        message=message, allow_main_chat=allow_main_chat)
     if res.get("ok"):
         kw = {k: v for k, v in res.items() if k != "ok"}
         out(True, **kw)
@@ -1002,12 +1004,13 @@ def act_approval_allow(node, always=False, force=False):
         fail("APPROVAL_FAILED", res.get("error", "approval failed"), res)
 
 
-def act_approval_deny(node):
+def act_approval_deny(node, message=None, allow_main_chat=False):
     audit("approval-deny", node)
     if node not in VALID_AGENTS:
         fail("BAD_NODE", f"unknown node: {node}")
     import approvals
-    res = approvals.deny_node_approval(node, caller="box-ctl")
+    res = approvals.deny_node_approval(node, caller="box-ctl",
+                                       message=message, allow_main_chat=allow_main_chat)
     if res.get("ok"):
         kw = {k: v for k, v in res.items() if k != "ok"}
         out(True, **kw)
@@ -2004,7 +2007,7 @@ def act_swarm_status(sid):
     out(True, swarm=swarm, counts=_swarm_counts(swarm))
 
 
-def act_swarm_attach(sid, slot_str, agent_id):
+def act_swarm_attach(sid, slot_str, agent_id, session_id=None):
     if not agent_id or not SWARM_AGENT_RE.match(agent_id):
         fail("BAD_NAME", "agent id must match ^[A-Za-z0-9-]{1,64}$",
              {"field": "agent_id", "value": agent_id})
@@ -2021,13 +2024,15 @@ def act_swarm_attach(sid, slot_str, agent_id):
              {"swarm_id": sid, "slot": slot_rec["slot"]})
     slot_rec["agent_id"] = agent_id
     slot_rec["status"] = "running"
+    if session_id:
+        slot_rec["subagent_session_id"] = str(session_id)
     slot_rec["updated_ts"] = utcnow()
     swarm["status"] = _swarm_rollup(swarm)
     swarm["updated_ts"] = utcnow()
     _swarm_save(swarms)
     audit("swarm-attach", "%s/%d" % (sid, slot_rec["slot"]))
     out(True, swarm_id=sid, slot=slot_rec["slot"], agent_id=agent_id,
-        status="running")
+        subagent_session_id=session_id, status="running")
 
 
 def act_swarm_report(sid, slot_str):
@@ -3432,9 +3437,9 @@ def main(argv):
                 fail("BAD_ARGS", "usage: swarm-status <swarm-id>")
             act_swarm_status(rest[0])
         elif op == "attach":
-            if len(rest) != 3:
-                fail("BAD_ARGS", "usage: swarm-attach <swarm-id> <slot> <agent-id>")
-            act_swarm_attach(rest[0], rest[1], rest[2])
+            if len(rest) not in (3, 4):
+                fail("BAD_ARGS", "usage: swarm-attach <swarm-id> <slot> <agent-id> [session-id]")
+            act_swarm_attach(rest[0], rest[1], rest[2], rest[3] if len(rest) > 3 else None)
         elif op == "report":
             if len(rest) != 2:
                 fail("BAD_ARGS", "usage: swarm-report <swarm-id> <slot>  (result JSON on stdin)")
@@ -3479,9 +3484,9 @@ def main(argv):
                 fail("BAD_ARGS", "usage: swarm status <swarm-id>")
             act_swarm_status(args[0])
         elif sub == "attach":
-            if len(args) != 3:
-                fail("BAD_ARGS", "usage: swarm attach <swarm-id> <slot> <agent-id>")
-            act_swarm_attach(args[0], args[1], args[2])
+            if len(args) not in (3, 4):
+                fail("BAD_ARGS", "usage: swarm attach <swarm-id> <slot> <agent-id> [session-id]")
+            act_swarm_attach(args[0], args[1], args[2], args[3] if len(args) > 3 else None)
         elif sub == "report":
             if len(args) != 2:
                 fail("BAD_ARGS", "usage: swarm report <swarm-id> <slot>  (result JSON on stdin)")
@@ -3561,16 +3566,30 @@ def main(argv):
         act_approval_check(node)
     elif action in ("approval-allow", "approval-approve"):
         if not rest:
-            fail("BAD_ARGS", "usage: approval-allow <node> [--always] [--force]")
+            fail("BAD_ARGS", "usage: approval-allow <node> [--always] [--force] [--message TEXT] [--allow-main-chat]")
         node = rest[0]
-        always = "--always" in rest[1:]
-        force = "--force" in rest[1:]
-        act_approval_allow(node, always=always, force=force)
+        rest_args = rest[1:]
+        always = "--always" in rest_args
+        force = "--force" in rest_args
+        allow_main_chat = "--allow-main-chat" in rest_args
+        message = None
+        if "--message" in rest_args:
+            mi = rest_args.index("--message")
+            if mi + 1 < len(rest_args):
+                message = rest_args[mi + 1]
+        act_approval_allow(node, always=always, force=force, message=message, allow_main_chat=allow_main_chat)
     elif action == "approval-deny":
         if not rest:
-            fail("BAD_ARGS", "usage: approval-deny <node>")
+            fail("BAD_ARGS", "usage: approval-deny <node> [--message TEXT] [--allow-main-chat]")
         node = rest[0]
-        act_approval_deny(node)
+        rest_args = rest[1:]
+        allow_main_chat = "--allow-main-chat" in rest_args
+        message = None
+        if "--message" in rest_args:
+            mi = rest_args.index("--message")
+            if mi + 1 < len(rest_args):
+                message = rest_args[mi + 1]
+        act_approval_deny(node, message=message, allow_main_chat=allow_main_chat)
     elif action == "approval-auto":
         node = rest[0] if rest else None
         act_approval_auto(node)

bin/box-tui.py

@@ -0,0 +1 @@
+muse-tui.py

bin/chromebox-watchdog.sh

@@ -64,9 +64,9 @@ healthy() {
   local list
   list="$(cdp_list)" \
     || { HEALTH_FAIL_REASON="CDP unreachable on :$CDP_PORT"; return 1; }
-  echo "$list" | grep -q '"type": "page"' \
+  [[ "$list" == *'"type": "page"'* ]] \
     || { HEALTH_FAIL_REASON="CDP up but no page target in list"; return 1; }
-  echo "$list" | grep -E -q '"url": "https://muse\.ai' \
+  [[ "$list" == *'"url": "https://muse.ai'* ]] \
     || { HEALTH_FAIL_REASON="CDP up but not on muse.ai"; return 1; }
   warp_egress_healthy || return 1
   return 0

bin/completion-audit.py

@@ -0,0 +1,312 @@
+#!/usr/bin/env python3
+"""Completion auditor: prove work gets done, or say exactly where it stalls.
+
+Runs on a 15-minute systemd timer (systemd/completion-audit.*). Reads
+job-log.jsonl, swarms.json, and followups.json; computes the completion
+funnel per job family plus swarm drain and followup backlog; writes a JSON
+report under logs/ and posts a compact digest to the ops heartbeat sidechat
+when degraded (or a heartbeat summary every 6h when green).
+
+Read-only except the digest DM and its own log/state files. Exit 0 always
+on a completed audit; tracebacks (real errors) fail the timer visibly.
+"""
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from collections import Counter, defaultdict
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+JOB_LOG = REPO_ROOT / "job-log.jsonl"
+SWARMS_FILE = REPO_ROOT / "swarms.json"
+FOLLOWUPS_FILE = REPO_ROOT / "followups.json"
+LOGS_DIR = REPO_ROOT / "logs"
+STATE_FILE = LOGS_DIR / "completion-audit-state.json"
+
+_JOB_ID_RE = re.compile(r"^(.+)-(\d{8})-(\d{6})-([0-9a-f]{8})$")
+HEARTBEAT_INTERVAL_H = 6
+STALE_RUNNING_MIN = 90
+SILENT_MIN_SENT = 3
+
+
+def utcnow():
+    return datetime.now(timezone.utc)
+
+
+def family_of(job_id):
+    """Strip the dispatch suffix (<name>-YYYYMMDD-HHMMSS-<hex8>) to the family."""
+    m = _JOB_ID_RE.match(job_id or "")
+    return m.group(1) if m else (job_id or "?")
+
+
+def parse_ts(ts):
+    try:
+        t = datetime.fromisoformat(str(ts))
+    except Exception:
+        return None
+    if t.tzinfo is None:
+        t = t.replace(tzinfo=timezone.utc)
+    return t
+
+
+def compute_funnel(events, cutoff):
+    """Aggregate job-log events since cutoff.
+
+    Returns (families, tools) where families maps family -> counters and
+    tools holds global tool_exec stats. Pure over the event list.
+    """
+    families = defaultdict(lambda: Counter())
+    tools = Counter()
+    tool_errs = Counter()
+    for e in events:
+        t = parse_ts(e.get("ts"))
+        if t is None or t < cutoff:
+            continue
+        ty = e.get("type")
+        if ty == "job_sent":
+            families[family_of(e.get("job_id"))]["sent"] += 1
+        elif ty == "job_dispatched":
+            families[family_of(e.get("job_id"))]["dispatched"] += 1
+        elif ty == "tool_exec":
+            tools["total"] += 1
+            if e.get("success"):
+                tools["ok"] += 1
+            else:
+                tools["fail"] += 1
+                tool_errs[e.get("op", "?")] += 1
+        elif ty == "job_result":
+            fam = family_of(e.get("job_id"))
+            families[fam]["results"] += 1
+            families[fam]["ok" if e.get("success") else "fail"] += 1
+        elif ty == "job_failed":
+            families[family_of(e.get("job_id"))]["failed"] += 1
+        elif ty == "fallback_executed":
+            families[family_of(e.get("job_id"))]["fallback_ok"] += 1
+        elif ty == "fallback_failed":
+            families[family_of(e.get("job_id"))]["fallback_fail"] += 1
+        elif ty == "proof_requested":
+            families[family_of(e.get("job_id"))]["proofs"] += 1
+    return families, {"tools": tools, "tool_errs": tool_errs}
+
+
+def swarm_drain(now):
+    """Status counts + stale-running slots from swarms.json."""
+    try:
+        data = json.load(open(SWARMS_FILE))
+    except Exception:
+        return {"error": "swarms.json unreadable"}, []
+    values = data.values() if isinstance(data, dict) else data
+    status = Counter()
+    stale = []
+    for s in values:
+        if not isinstance(s, dict):
+            continue
+        for sl in s.get("slots", []) or []:
+            status[sl.get("status", "?")] += 1
+            if sl.get("status") == "running":
+                upd = parse_ts(sl.get("updated_ts"))
+                if upd and (now - upd) > timedelta(minutes=STALE_RUNNING_MIN):
+                    stale.append({
+                        "swarm": s.get("swarm_id"),
+                        "slot": sl.get("slot"),
+                        "agent": sl.get("agent_id"),
+                        "idle_min": int((now - upd).total_seconds() // 60),
+                    })
+    return {"slots": dict(status)}, stale
+
+
+def followup_backlog(now):
+    """Pending/overdue/escalated counts from followups.json."""
+    try:
+        data = json.load(open(FOLLOWUPS_FILE))
+    except Exception:
+        return {"error": "followups.json unreadable"}
+    values = data.values() if isinstance(data, dict) else data
+    out = Counter()
+    for r in values:
+        if not isinstance(r, dict):
+            continue
+        st = r.get("status", "?")
+        out[st] += 1
+        if st == "pending":
+            dl = parse_ts(r.get("deadline"))
+            if dl and dl < now:
+                out["overdue"] += 1
+    return dict(out)
+
+
+def build_report(hours):
+    now = utcnow()
+    cutoff = now - timedelta(hours=hours)
+    events = []
+    try:
+        with open(JOB_LOG) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    events.append(json.loads(line))
+                except Exception:
+                    continue
+    except FileNotFoundError:
+        pass
+    families, tools = compute_funnel(events, cutoff)
+    fam = {k: dict(v) for k, v in sorted(families.items())}
+    swarm, stale = swarm_drain(now)
+    backlog = followup_backlog(now)
+    totals = Counter()
+    for v in fam.values():
+        for k, n in v.items():
+            totals[k] += n
+    silent = sorted(
+        k for k, v in fam.items()
+        if v.get("sent", 0) >= SILENT_MIN_SENT and v.get("results", 0) == 0)
+    degraded_reasons = []
+    if silent:
+        degraded_reasons.append(f"{len(silent)} silent families: {', '.join(silent[:5])}")
+    if totals.get("failed"):
+        degraded_reasons.append(f"{totals['failed']} job_failed")
+    if tools["tools"].get("fail"):
+        top = tools["tool_errs"].most_common(3)
+        degraded_reasons.append(
+            "tool errors: " + ", ".join(f"{op}x{n}" for op, n in top))
+    if totals.get("fallback_fail"):
+        degraded_reasons.append(f"{totals['fallback_fail']} fallback_failed")
+    if stale:
+        degraded_reasons.append(f"{len(stale)} running slots idle >{STALE_RUNNING_MIN}m")
+    if backlog.get("overdue"):
+        degraded_reasons.append(f"{backlog['overdue']} overdue followups")
+    if backlog.get("escalated"):
+        degraded_reasons.append(f"{backlog['escalated']} escalated followups")
+    return {
+        "ts": now.isoformat(),
+        "window_h": hours,
+        "totals": dict(totals),
+        "tools": {k: dict(v) if isinstance(v, Counter) else v
+                  for k, v in tools.items()},
+        "families": fam,
+        "silent_families": silent,
+        "swarms": swarm,
+        "stale_running": stale[:10],
+        "followups": backlog,
+        "degraded": bool(degraded_reasons),
+        "reasons": degraded_reasons,
+    }
+
+
+def render_digest(rep):
+    t = rep["totals"]
+    tools = rep["tools"].get("tools", {})
+    lines = [
+        f"Completion audit ({rep['window_h']}h, {rep['ts'][:16]}Z)",
+        f"funnel: {t.get('sent', 0)} sent / {t.get('dispatched', 0)} dispatched / "
+        f"{tools.get('total', 0)} tool_exec / {t.get('results', 0)} results "
+        f"({t.get('ok', 0)} ok)",
+    ]
+    if rep["silent_families"]:
+        lines.append("silent: " + ", ".join(rep["silent_families"][:6]))
+    bits = []
+    if t.get("failed"):
+        bits.append(f"{t['failed']} job_failed")
+    if tools.get("fail"):
+        bits.append(f"{tools['fail']} tool errors")
+    if t.get("fallback_ok") or t.get("fallback_fail"):
+        bits.append(f"fallback {t.get('fallback_ok', 0)} ok / {t.get('fallback_fail', 0)} fail")
+    if t.get("proofs"):
+        bits.append(f"{t['proofs']} proof reqs")
+    if bits:
+        lines.append("flags: " + ", ".join(bits))
+    sw = rep["swarms"].get("slots", {})
+    if sw:
+        lines.append("swarms now: " + " / ".join(f"{v} {k}" for k, v in sorted(sw.items())))
+    if rep["stale_running"]:
+        lines.append(f"stale running: {len(rep['stale_running'])} slots (see report)")
+    fb = rep["followups"]
+    if fb and "error" not in fb:
+        lines.append(
+            f"followups now: {fb.get('pending', 0)} pending / {fb.get('overdue', 0)} "
+            f"overdue / {fb.get('escalated', 0)} escalated")
+    if rep["degraded"]:
+        lines.append("verdict: DEGRADED — " + "; ".join(rep["reasons"][:3]))
+    else:
+        lines.append("verdict: HEALTHY — work flowing, results landing")
+    return "\n".join(lines)
+
+
+def should_post(report):
+    """Post on degraded, else heartbeat at most every HEARTBEAT_INTERVAL_H."""
+    if report["degraded"]:
+        return True, "degraded"
+    try:
+        state = json.load(open(STATE_FILE))
+        last = parse_ts(state.get("last_heartbeat"))
+    except Exception:
+        last = None
+    if last is None or (utcnow() - last) > timedelta(hours=HEARTBEAT_INTERVAL_H):
+        return True, "heartbeat"
+    return False, "green-quiet"
+
+
+def post_digest(digest):
+    argv = [sys.executable, str(REPO_ROOT / "bin" / "dm.py"), "send",
+           "--agent", "super", "--to", "opm", "--target", "heartbeat", digest]
+    p = subprocess.run(argv, capture_output=True, text=True, timeout=120)
+    return p.returncode == 0, (p.stdout or p.stderr or "").strip()[:300]
+
+
+def save_report(report):
+    LOGS_DIR.mkdir(parents=True, exist_ok=True)
+    stamp = report["ts"].replace("+00:00", "Z").replace(":", "")
+    dated = LOGS_DIR / f"completion-audit-{stamp[:15]}.json"
+    body = json.dumps(report, indent=2)
+    dated.write_text(body, encoding="utf-8")
+    latest = LOGS_DIR / "completion-audit-latest.json"
+    tmp = LOGS_DIR / f".completion-audit-latest.tmp.{os.getpid()}"
+    tmp.write_text(body, encoding="utf-8")
+    os.replace(tmp, latest)
+    return dated
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Completion funnel auditor")
+    ap.add_argument("--hours", type=int, default=24)
+    ap.add_argument("--post", dest="post", action="store_true", default=True)
+    ap.add_argument("--no-post", dest="post", action="store_false")
+    ap.add_argument("--json", action="store_true", help="Print raw report JSON")
+    args = ap.parse_args()
+
+    report = build_report(args.hours)
+    path = save_report(report)
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print(render_digest(report))
+    print(f"\nreport: {path}")
+    if not args.post:
+        print("post: skipped (--no-post)")
+        return 0
+    do_post, why = should_post(report)
+    if not do_post:
+        print(f"post: skipped ({why})")
+        return 0
+    ok, detail = post_digest(render_digest(report))
+    print(f"post: {'delivered' if ok else 'FAILED'} ({why}) {detail[:120]}")
+    if ok and why == "heartbeat":
+        try:
+            state = {}
+            if STATE_FILE.exists():
+                state = json.loads(STATE_FILE.read_text(encoding="utf-8"))
+            state["last_heartbeat"] = report["ts"]
+            STATE_FILE.write_text(json.dumps(state, indent=2), encoding="utf-8")
+        except Exception as e:
+            print(f"warning: state save failed: {e}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bin/docs-lookup

@@ -0,0 +1 @@
+/home/super/Projects/NetVM/bin/docs-lookup.py

bin/docs-lookup.py

@@ -0,0 +1,606 @@
+#!/usr/bin/env python3
+"""docs-lookup.py — Unified Lookup & Regex Passing Tool for docs_internal/.
+
+Provides high-speed queries, regex passing, grammar validation, and surface
+lookups for autonomous agents and operators interfacing with NetVM, Box,
+and box.muse-dev.online.
+
+Usage:
+  docs-lookup.py search <query>
+  docs-lookup.py surfaces [name]
+  docs-lookup.py sentence [name]
+  docs-lookup.py regex [name] [--test "<string>"]
+  docs-lookup.py parse "<string>"
+  docs-lookup.py get <collection> [key]
+  docs-lookup.py cli [domain]
+  docs-lookup.py overview
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+NETVM_ROOT = Path(__file__).resolve().parent.parent
+LOOKUP_INTERNAL = NETVM_ROOT / "lookup_internal"
+if not LOOKUP_INTERNAL.exists() and (NETVM_ROOT / "docs_internal").exists():
+    LOOKUP_INTERNAL = NETVM_ROOT / "docs_internal"
+DOCS_INTERNAL = LOOKUP_INTERNAL
+
+USE_COLOR = sys.stdout.isatty() and os.environ.get("NO_COLOR") is None
+
+def _c(code: str, text: str) -> str:
+    return f"\033[{code}m{text}\033[0m" if USE_COLOR else str(text)
+
+def c_bold(s: str) -> str: return _c("1", s)
+def c_dim(s: str) -> str: return _c("2", s)
+def c_green(s: str) -> str: return _c("32", s)
+def c_red(s: str) -> str: return _c("31", s)
+def c_yellow(s: str) -> str: return _c("33", s)
+def c_blue(s: str) -> str: return _c("34", s)
+def c_cyan(s: str) -> str: return _c("36", s)
+def c_magenta(s: str) -> str: return _c("35", s)
+
+
+def load_json_file(filename: str) -> Dict[str, Any]:
+    """Safely load a JSON file from docs_internal."""
+    p = DOCS_INTERNAL / filename
+    if not p.is_file():
+        return {}
+    try:
+        with open(p, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        print(f"Error reading {p}: {e}", file=sys.stderr)
+        return {}
+
+
+def load_manifest() -> Dict[str, Any]:
+    return load_json_file("manifest.json")
+
+
+def load_sentence_structures() -> Dict[str, Any]:
+    return load_json_file("sentence_structure.json")
+
+
+def load_regex_patterns() -> Dict[str, Any]:
+    return load_json_file("regex_patterns.json")
+
+
+def load_assistive_surfaces() -> Dict[str, Any]:
+    return load_json_file("assistive_surfaces.json")
+
+
+def load_cli_tools() -> Dict[str, Any]:
+    return load_json_file("cli_tools.json")
+
+
+def load_fleet_nodes() -> Dict[str, Any]:
+    return load_json_file("fleet_nodes.json")
+
+
+def compile_pattern(pat_entry: Dict[str, Any]) -> Tuple[Optional[re.Pattern], Optional[str]]:
+    """Compile a regex entry with its configured flags."""
+    raw_pat = pat_entry.get("pattern", "")
+    flag_names = pat_entry.get("flags", [])
+    flags = 0
+    for fn in flag_names:
+        if hasattr(re, fn):
+            flags |= getattr(re, fn)
+    try:
+        return re.compile(raw_pat, flags), None
+    except Exception as e:
+        return None, str(e)
+
+
+# ---------------------------------------------------------------------------
+# Core Lookup Actions
+# ---------------------------------------------------------------------------
+
+def handle_overview(json_mode: bool = False):
+    manifest = load_manifest()
+    if json_mode:
+        print(json.dumps(manifest, indent=2))
+        return
+
+    print(c_bold("\n=== docs_internal — Internal Agent & Operator Lookup Database ==="))
+    print(c_dim(f"Location: {DOCS_INTERNAL} | Host: {manifest.get('host', 'box.muse-dev.online')}"))
+    print(f"{manifest.get('description', '')}\n")
+
+    print(c_cyan("Available Collections:"))
+    collections = manifest.get("collections", [])
+    for col in collections:
+        cid = col.get("id")
+        name = col.get("name")
+        desc = col.get("description")
+        jfile = col.get("json_file")
+        mfile = col.get("md_file")
+        print(f"  • {c_bold(cid):<20} {c_green(name)}")
+        print(f"    {c_dim(desc)}")
+        print(f"    {c_dim('Files:')} {c_yellow(jfile)} | {c_yellow(mfile)}")
+        print()
+
+    print(c_dim("Query commands: super docs [search|surfaces|sentence|regex|parse|get|cli]"))
+
+
+def handle_search(query: str, json_mode: bool = False):
+    q = query.lower()
+    results = []
+
+    # Search in all JSON files
+    for jpath in sorted(DOCS_INTERNAL.glob("*.json")):
+        try:
+            data = json.loads(jpath.read_text(encoding="utf-8"))
+        except Exception:
+            continue
+
+        def recurse_search(obj, path=""):
+            if isinstance(obj, dict):
+                for k, v in obj.items():
+                    subpath = f"{path}.{k}" if path else k
+                    if q in str(k).lower():
+                        results.append({
+                            "file": jpath.name,
+                            "type": "json_key",
+                            "path": subpath,
+                            "match": str(k),
+                            "preview": str(v)[:160]
+                        })
+                    recurse_search(v, subpath)
+            elif isinstance(obj, list):
+                for idx, item in enumerate(obj):
+                    recurse_search(item, f"{path}[{idx}]")
+            elif isinstance(obj, str):
+                if q in obj.lower():
+                    results.append({
+                        "file": jpath.name,
+                        "type": "json_value",
+                        "path": path,
+                        "match": obj[:120],
+                        "preview": obj[:240]
+                    })
+
+        recurse_search(data)
+
+    # Search in Markdown files
+    for mpath in sorted(DOCS_INTERNAL.glob("*.md")):
+        try:
+            content = mpath.read_text(encoding="utf-8")
+        except Exception:
+            continue
+        lines = content.splitlines()
+        for idx, line in enumerate(lines, 1):
+            if q in line.lower():
+                results.append({
+                    "file": mpath.name,
+                    "type": "markdown",
+                    "line": idx,
+                    "match": line.strip(),
+                    "preview": line.strip()
+                })
+
+    if json_mode:
+        print(json.dumps({"query": query, "count": len(results), "results": results}, indent=2))
+        return
+
+    print(c_bold(f"\nSearch results for '{query}' ({len(results)} matches):"))
+    if not results:
+        print(c_dim("  (no matching entries found)"))
+        return
+
+    for r in results[:40]:
+        if r["type"] == "markdown":
+            print(f"  [{c_yellow(r['file'])}:{c_cyan(str(r['line']))}] {r['match']}")
+        else:
+            print(f"  [{c_blue(r['file'])}:{c_magenta(r['path'])}] {r['preview']}")
+
+
+def handle_surfaces(view_name: Optional[str] = None, json_mode: bool = False):
+    data = load_assistive_surfaces()
+    views = data.get("views", {})
+
+    if view_name:
+        key = view_name.lower().strip()
+        v = views.get(key)
+        if not v:
+            for k, val in views.items():
+                if key in k or key in val.get("name", "").lower():
+                    v = val
+                    key = k
+                    break
+        if not v:
+            err = {"error": f"Surface '{view_name}' not found", "available": list(views.keys())}
+            if json_mode:
+                print(json.dumps(err, indent=2))
+            else:
+                print(c_red(f"Error: Surface '{view_name}' not found. Available: {', '.join(views.keys())}"))
+            sys.exit(1)
+
+        if json_mode:
+            print(json.dumps({key: v}, indent=2))
+            return
+
+        print(c_bold(f"\n=== Assistive Surface: {v.get('name')} (`{key}`) ==="))
+        print(c_dim(f"Host: {data.get('host')} | Tab ID: {v.get('tab_id')}"))
+        print(f"{c_cyan('DOM Tab Selector:')}  {c_yellow(str(v.get('dom_tab_selector')))}")
+        print(f"{c_cyan('DOM Pane Selector:')} {c_yellow(str(v.get('dom_pane_selector')))}")
+        
+        elements = v.get("key_elements", {})
+        if elements:
+            print(c_bold("\nKey DOM Elements / Selectors:"))
+            for el_name, sel in elements.items():
+                print(f"  • {c_magenta(el_name):<20} {c_green(sel)}")
+
+        endpoints = v.get("api_endpoints", [])
+        if endpoints:
+            print(c_bold("\nAssociated REST API Endpoints:"))
+            for ep in endpoints:
+                print(f"  • {c_bold(ep.get('method'))} {c_cyan(ep.get('path'))}")
+                print(f"    {c_dim(ep.get('description'))}")
+                if ep.get("curl_example"):
+                    print(f"    {c_dim('curl:')} {c_yellow(ep.get('curl_example'))}")
+
+        recipe = v.get("assistive_recipe")
+        if recipe:
+            print(c_bold("\nAssistive Recipe:"))
+            print(f"  {recipe}")
+        print()
+        return
+
+    # All views
+    if json_mode:
+        print(json.dumps(data, indent=2))
+        return
+
+    print(c_bold(f"\n=== Assistive Surfaces for {data.get('host', 'box.muse-dev.online')} ==="))
+    print(c_dim(f"Operator PIN: {data.get('auth', {}).get('pin')} | Session Cookie: {data.get('auth', {}).get('cookie_name')}"))
+    print()
+
+    for k, v in views.items():
+        name = v.get("name", k)
+        tab_sel = v.get("dom_tab_selector") or "(modal/overlay)"
+        eps = [f"{ep.get('method')} {ep.get('path')}" for ep in v.get("api_endpoints", [])]
+        ep_summary = ", ".join(eps) if eps else "(no direct endpoint)"
+        print(f"  • {c_bold(k):<16} {c_cyan(name):<30} {c_yellow(tab_sel)}")
+        print(f"    {c_dim('API:')} {ep_summary}")
+        if v.get("assistive_recipe"):
+            print(f"    {c_dim('Hint:')} {v.get('assistive_recipe')[:100]}...")
+        print()
+
+
+def handle_sentence(name: Optional[str] = None, json_mode: bool = False):
+    data = load_sentence_structures()
+    structs = data.get("structures", {})
+
+    if name:
+        key = name.lower().strip()
+        s = structs.get(key)
+        if not s:
+            for k, val in structs.items():
+                if key in k or key in val.get("name", "").lower() or key in val.get("protocol_tag", "").lower():
+                    s = val
+                    key = k
+                    break
+        if not s:
+            err = {"error": f"Sentence structure '{name}' not found", "available": list(structs.keys())}
+            if json_mode:
+                print(json.dumps(err, indent=2))
+            else:
+                print(c_red(f"Error: Sentence structure '{name}' not found. Available: {', '.join(structs.keys())}"))
+            sys.exit(1)
+
+        if json_mode:
+            print(json.dumps({key: s}, indent=2))
+            return
+
+        print(c_bold(f"\n=== Protocol Structure: {s.get('name')} (`{key}`) ==="))
+        print(f"{c_cyan('Tag:')}        {c_bold(s.get('protocol_tag'))}")
+        print(f"{c_cyan('Template:')}   {c_green(s.get('template'))}")
+        print(f"{c_cyan('Lifecycle:')}  {c_yellow(s.get('lifecycle_transition', ''))}")
+        print(f"\n{c_bold('Description:')}\n  {s.get('description')}")
+        print(f"\n{c_bold('Required Fields:')} {', '.join(s.get('required_fields', []))}")
+        if s.get("optional_fields"):
+            print(f"{c_bold('Optional Fields:')} {', '.join(s.get('optional_fields', []))}")
+        print(f"\n{c_bold('Example:')}\n  {c_cyan(s.get('example'))}")
+        print(f"\n{c_bold('Reply Expectation:')}\n  {s.get('reply_expectation')}")
+        print()
+        return
+
+    if json_mode:
+        print(json.dumps(data, indent=2))
+        return
+
+    print(c_bold("\n=== Agent Sentence Structures & Conversational Contracts ==="))
+    print(c_dim("Format rules enforced by response-harvester and self_main_loop.\n"))
+
+    for k, s in structs.items():
+        tag = s.get("protocol_tag", "")
+        desc = s.get("description", "")
+        print(f"  • {c_bold(k):<18} {c_green(tag):<25} {s.get('name')}")
+        print(f"    {c_dim(desc)}")
+        print(f"    {c_dim('Template:')} {c_cyan(s.get('template', ''))}")
+        print()
+
+
+def handle_regex(name: Optional[str] = None, test_str: Optional[str] = None, json_mode: bool = False):
+    data = load_regex_patterns()
+    pats = data.get("patterns", {})
+
+    if name:
+        key = name.lower().strip()
+        p = pats.get(key)
+        if not p:
+            for k, val in pats.items():
+                if key in k or key in val.get("name", "").lower():
+                    p = val
+                    key = k
+                    break
+        if not p:
+            err = {"error": f"Regex pattern '{name}' not found", "available": list(pats.keys())}
+            if json_mode:
+                print(json.dumps(err, indent=2))
+            else:
+                print(c_red(f"Error: Pattern '{name}' not found. Available: {', '.join(pats.keys())}"))
+            sys.exit(1)
+
+        compiled, comp_err = compile_pattern(p)
+
+        test_result = None
+        if test_str is not None:
+            if compiled:
+                m = compiled.search(test_str)
+                test_result = {
+                    "matched": bool(m),
+                    "match_span": m.span() if m else None,
+                    "matched_text": m.group(0) if m else None,
+                    "named_groups": m.groupdict() if m else {},
+                    "groups": list(m.groups()) if m else []
+                }
+            else:
+                test_result = {"matched": False, "error": comp_err}
+
+        if json_mode:
+            out = {key: p, "compiled_ok": bool(compiled)}
+            if test_str is not None:
+                out["test_evaluation"] = test_result
+            print(json.dumps(out, indent=2))
+            return
+
+        print(c_bold(f"\n=== Regex Pattern: {p.get('name')} (`{key}`) ==="))
+        print(f"{c_cyan('Pattern:')}      {c_yellow(p.get('pattern'))}")
+        print(f"{c_cyan('Flags:')}        {', '.join(p.get('flags', [])) or '(none)'}")
+        print(f"{c_cyan('Description:')}  {p.get('description')}")
+        print(f"{c_cyan('Usage:')}        {c_dim(p.get('usage', ''))}")
+
+        ng = p.get("named_groups", {})
+        if ng:
+            print(c_bold("\nNamed Groups:"))
+            for gname, gdesc in ng.items():
+                print(f"  • {c_magenta(gname):<16} {gdesc}")
+
+        if test_str is not None:
+            print(c_bold("\nTest Execution Result:"))
+            print(f"  Input: {c_dim(test_str)}")
+            if test_result.get("matched"):
+                print(f"  Verdict: {c_green('✔ MATCHED')}")
+                print(f"  Matched Text: {c_cyan(test_result['matched_text'])}")
+                if test_result["named_groups"]:
+                    print(f"  Extracted Tokens:")
+                    for k_grp, v_grp in test_result["named_groups"].items():
+                        print(f"    - {c_magenta(k_grp)}: {c_yellow(str(v_grp))}")
+            else:
+                print(f"  Verdict: {c_red('✖ NO MATCH')}")
+                if comp_err:
+                    print(f"  Compile Error: {comp_err}")
+        print()
+        return
+
+    # List patterns
+    if json_mode:
+        print(json.dumps(data, indent=2))
+        return
+
+    print(c_bold("\n=== Master Regex Patterns & Passing Dictionary ==="))
+    print(c_dim("Patterns tested and calibrated across response-harvester, dm, and loop engines.\n"))
+
+    for k, p in pats.items():
+        print(f"  • {c_bold(k):<18} {c_green(p.get('name'))}")
+        print(f"    {c_dim('Pattern:')} {c_yellow(p.get('pattern'))}")
+        print(f"    {c_dim(p.get('description'))}")
+        print()
+
+
+def handle_parse(candidate_str: str, json_mode: bool = False):
+    """Pass candidate_str through all registered regexes and extract tokens."""
+    data = load_regex_patterns()
+    pats = data.get("patterns", {})
+
+    matches = []
+    for k, p in pats.items():
+        compiled, err = compile_pattern(p)
+        if not compiled:
+            continue
+        m = compiled.search(candidate_str)
+        if m:
+            matches.append({
+                "pattern_key": k,
+                "pattern_name": p.get("name"),
+                "matched_text": m.group(0),
+                "named_groups": m.groupdict(),
+                "span": m.span()
+            })
+
+    if json_mode:
+        print(json.dumps({
+            "input": candidate_str,
+            "matched_patterns_count": len(matches),
+            "matches": matches
+        }, indent=2))
+        return
+
+    print(c_bold(f"\n=== Regex Parse Analysis ==="))
+    print(f"Input: {c_dim(candidate_str)}\n")
+
+    if not matches:
+        print(c_yellow("  ⚠ No registered regex pattern matched this string."))
+        return
+
+    print(c_green(f"Matched {len(matches)} pattern(s):"))
+    for match in matches:
+        print(f"\n  • Pattern: {c_bold(match['pattern_name'])} (`{c_cyan(match['pattern_key'])}`)")
+        print(f"    Matched Chunk: {c_yellow(match['matched_text'])}")
+        ng = match["named_groups"]
+        if ng:
+            print(f"    Extracted Tokens:")
+            for gk, gv in ng.items():
+                print(f"      - {c_magenta(gk)}: {c_green(str(gv))}")
+    print()
+
+
+def handle_get(collection: str, key: Optional[str] = None, json_mode: bool = False):
+    col_map = {
+        "manifest": "manifest.json",
+        "sentence": "sentence_structure.json",
+        "sentence_structure": "sentence_structure.json",
+        "regex": "regex_patterns.json",
+        "regex_patterns": "regex_patterns.json",
+        "surfaces": "assistive_surfaces.json",
+        "assistive_surfaces": "assistive_surfaces.json",
+        "cli": "cli_tools.json",
+        "cli_tools": "cli_tools.json",
+        "fleet": "fleet_nodes.json",
+        "fleet_nodes": "fleet_nodes.json",
+    }
+
+    fname = col_map.get(collection.lower().strip())
+    if not fname:
+        print(c_red(f"Error: Unknown collection '{collection}'. Available: {', '.join(col_map.keys())}"), file=sys.stderr)
+        sys.exit(1)
+
+    data = load_json_file(fname)
+    if key:
+        # Check top level or primary container
+        val = None
+        for primary in ["structures", "patterns", "views", "domains", "nodes", "collections"]:
+            if primary in data and isinstance(data[primary], dict) and key in data[primary]:
+                val = data[primary][key]
+                break
+        if val is None and key in data:
+            val = data[key]
+        if val is None:
+            print(c_red(f"Error: Key '{key}' not found in {fname}"), file=sys.stderr)
+            sys.exit(1)
+        data = {key: val}
+
+    print(json.dumps(data, indent=2))
+
+
+def handle_cli(domain: Optional[str] = None, json_mode: bool = False):
+    data = load_cli_tools()
+    domains = data.get("domains", {})
+
+    if domain:
+        d = domains.get(domain.lower().strip())
+        if not d:
+            print(c_red(f"Error: CLI domain '{domain}' not found. Available: {', '.join(domains.keys())}"), file=sys.stderr)
+            sys.exit(1)
+        if json_mode:
+            print(json.dumps({domain: d}, indent=2))
+            return
+        print(c_bold(f"\n=== CLI Tool Domain: super {domain} / box {domain} ==="))
+        print(f"Summary: {d.get('summary')}\n")
+        for sub in d.get("subcommands", []):
+            print(f"  • {c_green(sub['cmd'])}")
+            print(f"    {c_dim(sub['desc'])}\n")
+        return
+
+    if json_mode:
+        print(json.dumps(data, indent=2))
+        return
+
+    print(c_bold("\n=== Unified NetVM & Box CLI Tool Catalog ==="))
+    print(c_dim("Powered by super-cli.py and bin/muse wrapper.\n"))
+    for dom_k, dom_v in domains.items():
+        print(f"  • {c_bold(dom_k):<16} {c_cyan(dom_v.get('summary'))}")
+        for sub in dom_v.get("subcommands", [])[:2]:
+            print(f"    - {c_dim(sub['cmd'])}")
+        print()
+
+
+# ---------------------------------------------------------------------------
+# CLI Argument Parser
+# ---------------------------------------------------------------------------
+
+def build_parser():
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--json", action="store_true", help="Output machine-readable JSON")
+
+    parser = argparse.ArgumentParser(
+        description="docs-lookup — Internal Agent & Operator Documentation Query Engine",
+        parents=[common],
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+
+    sub = parser.add_subparsers(dest="action")
+
+    p_search = sub.add_parser("search", parents=[common], help="Full-text search across docs_internal")
+    p_search.add_argument("query", help="Search keyword or phrase")
+
+    p_surfaces = sub.add_parser("surfaces", parents=[common], help="Lookup assistive surfaces for box.muse-dev.online")
+    p_surfaces.add_argument("name", nargs="?", default=None, help="Surface or tab name")
+
+    p_sentence = sub.add_parser("sentence", parents=[common], help="Lookup agent sentence structures & protocols")
+    p_sentence.add_argument("name", nargs="?", default=None, help="Structure name (e.g. work_order, result)")
+
+    p_regex = sub.add_parser("regex", parents=[common], help="Lookup and test regex patterns")
+    p_regex.add_argument("name", nargs="?", default=None, help="Pattern name (e.g. work_order, verb)")
+    p_regex.add_argument("--test", dest="test_str", default=None, help="Test string to evaluate against pattern")
+
+    p_parse = sub.add_parser("parse", parents=[common], help="Parse an agent utterance through all regex patterns")
+    p_parse.add_argument("string", help="String/utterance to parse")
+
+    p_get = sub.add_parser("get", parents=[common], help="Query raw JSON collection and key")
+    p_get.add_argument("collection", help="Collection name (sentence, regex, surfaces, cli, fleet)")
+    p_get.add_argument("key", nargs="?", default=None, help="Optional specific key")
+
+    p_cli = sub.add_parser("cli", parents=[common], help="Lookup CLI commands and syntax")
+    p_cli.add_argument("domain", nargs="?", default=None, help="CLI domain (fleet, dm, job, etc.)")
+
+    p_overview = sub.add_parser("overview", parents=[common], help="Database overview and collections manifest")
+
+    return parser
+
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+
+    act = args.action
+    json_mode = getattr(args, "json", False)
+
+    if not act or act == "overview":
+        handle_overview(json_mode)
+    elif act == "search":
+        handle_search(args.query, json_mode)
+    elif act == "surfaces":
+        handle_surfaces(args.name, json_mode)
+    elif act == "sentence":
+        handle_sentence(args.name, json_mode)
+    elif act == "regex":
+        handle_regex(args.name, args.test_str, json_mode)
+    elif act == "parse":
+        handle_parse(args.string, json_mode)
+    elif act == "get":
+        handle_get(args.collection, args.key, json_mode)
+    elif act == "cli":
+        handle_cli(args.domain, json_mode)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

bin/exec-constrained.py

@@ -49,7 +49,7 @@ import sys
 import tempfile
 import threading
 import time
-from http.server import HTTPServer, BaseHTTPRequestHandler
+from http.server import ThreadingHTTPServer, BaseHTTPRequestHandler
 import ssl
 
 # ---------------------------------------------------------------- config
@@ -139,33 +139,34 @@ def check_token(token):
 
 
 def check_nonce(nonce):
-    now = time.time()
-    fresh = []
-    try:
-        with open(NONCE_FILE) as f:
-            for line in f:
-                parts = line.split()
-                if len(parts) != 2:
-                    continue
-                n, t = parts
-                try:
-                    if now - float(t) < 2 * SIG_MAX_SKEW:
-                        fresh.append((n, t))
-                except ValueError:
-                    pass
-    except FileNotFoundError:
-        pass
-    if any(n == nonce for n, _ in fresh):
-        return False
-    fresh.append((nonce, str(now)))
-    try:
-        with open(NONCE_FILE, 'w') as f:
-            for n, t in fresh:
-                f.write(f'{n} {t}\n')
-        os.chmod(NONCE_FILE, 0o600)
-    except OSError:
-        return False
-    return True
+    with _nonce_lock:
+        now = time.time()
+        fresh = []
+        try:
+            with open(NONCE_FILE) as f:
+                for line in f:
+                    parts = line.split()
+                    if len(parts) != 2:
+                        continue
+                    n, t = parts
+                    try:
+                        if now - float(t) < 2 * SIG_MAX_SKEW:
+                            fresh.append((n, t))
+                    except ValueError:
+                        pass
+        except FileNotFoundError:
+            pass
+        if any(n == nonce for n, _ in fresh):
+            return False
+        fresh.append((nonce, str(now)))
+        try:
+            with open(NONCE_FILE, 'w') as f:
+                for n, t in fresh:
+                    f.write(f'{n} {t}\n')
+            os.chmod(NONCE_FILE, 0o600)
+        except OSError:
+            return False
+        return True
 
 
 def check_signature(identity, payload, signature):
@@ -364,7 +365,7 @@ def _dm_read_validate(raw):
 def _dm_read_build(a):
     return [sys.executable, os.path.join(BIN_DIR, 'dm.py'), 'read',
             '--agent', a['agent'], '--target', a['target'],
-            '--limit', str(a['limit'])]
+            '--n', str(a['limit'])]
 
 
 def _job_run_validate(raw):
@@ -993,6 +994,67 @@ def _swarm_results_build(a):
     return [sys.executable, os.path.join(BIN_DIR, 'box-ctl.py'), 'swarm-results', a['swarm_id']]
 
 
+# box.exec allowlist: read-only box-ctl actions only (mirrors the read-only
+# subset of box-ctl.py IDEMPOTENT_ACTIONS). Actions with side-effecting
+# subverbs (main-loop enable/disable), path args (git-diff/git-log), or
+# complex argv shapes (job-next, policy-*, quality-validate, job-result)
+# are deliberately excluded.
+BOX_EXEC_NOARG_ACTIONS = frozenset({
+    'fleet-status', 'watchdog-alerts', 'relay-health', 'cdp-latency',
+    'chrome-errors', 'identity-audit', 'timer-list', 'job-list',
+    'vars-list', 'strat-list', 'loop-status', 'loop-health', 'loop-breaks',
+    'thread-list', 'dm-log', 'unread', 'swarm-list', 'quality-check',
+    'git-status',
+})
+BOX_EXEC_ONEARG_ACTIONS = frozenset({
+    'job-get', 'job-status', 'timer-status', 'vars-get', 'vars-history',
+    'strat-get', 'swarm-status', 'swarm-results',
+})
+_BOX_ARG_RE = re.compile(r'^[A-Za-z0-9][A-Za-z0-9/_.-]{0,127}$')
+
+
+def _box_exec_validate(raw):
+    if not isinstance(raw, dict):
+        raise OpError('args must be an object')
+    for k in raw:
+        if k not in {'action', 'arg', 'agent'}:
+            raise OpError(f'unknown arg: {k}')
+    action = raw.get('action')
+    if action in BOX_EXEC_NOARG_ACTIONS:
+        if raw.get('arg') is not None:
+            raise OpError(f'{action} takes no arg')
+        return {'action': action}
+    if action in BOX_EXEC_ONEARG_ACTIONS:
+        arg = raw.get('arg')
+        if arg is None:
+            return {'action': action}
+        if not isinstance(arg, str) or not _BOX_ARG_RE.fullmatch(arg):
+            raise OpError('arg must match safe token')
+        return {'action': action, 'arg': arg}
+    raise OpError(f'unknown or non-read-only box action: {action}')
+
+
+def _box_exec_build(a):
+    argv = [sys.executable, os.path.join(BIN_DIR, 'box-ctl.py'), a['action']]
+    if a.get('arg'):
+        argv.append(a['arg'])
+    return argv
+
+
+def _tools_list_validate(raw):
+    if not isinstance(raw, dict):
+        raise OpError('args must be an object')
+    for k in raw:
+        if k not in {'agent'}:
+            raise OpError(f'unknown arg: {k}')
+    return {}
+
+
+def _tools_list_build(a):
+    return [sys.executable, os.path.join(BIN_DIR, 'exec-constrained.py'),
+            '--list-ops']
+
+
 # op -> {validate, build, timeout, side_effecting, description}
 OPS = {
     'dm.send': {
@@ -1206,6 +1268,16 @@ OPS = {
         'timeout': 10, 'side_effecting': False,
         'desc': 'Canary no-op for watchdogs',
     },
+    'box.exec': {
+        'validate': _box_exec_validate, 'build': _box_exec_build,
+        'timeout': 60, 'side_effecting': False,
+        'desc': 'Call a read-only box-ctl action (fleet-status, dm-log, job-get, ...)',
+    },
+    'tools.list': {
+        'validate': _tools_list_validate, 'build': _tools_list_build,
+        'timeout': 15, 'side_effecting': False,
+        'desc': 'List all exec ops with descriptions (dynamic discovery)',
+    },
 }
 
 # identity -> set of ops. 'master' may invoke everything. Unknown identities
@@ -1294,6 +1366,7 @@ def permitted(ident, op):
 # ------------------------------------------------------- audit log
 
 _audit_lock = threading.Lock()
+_nonce_lock = threading.Lock()
 
 
 def audit(entry):
@@ -1493,6 +1566,19 @@ def main():
     ap.add_argument('--key-file',
                     default='/home/super/.exec-constrained-key.pem')
     ap.add_argument('--work-dir', default='/home/super')
+    ap.add_argument('--list-ops', action='store_true',
+                    help='Print the op registry as JSON and exit (backs tools.list)')
+    args = ap.parse_args()
+
+    if args.list_ops:
+        print(json.dumps({
+            'ok': True,
+            'ops': [{'op': k, 'desc': v.get('desc', ''),
+                     'side_effecting': bool(v.get('side_effecting', False)),
+                     'timeout': v.get('timeout', 30)}
+                    for k, v in sorted(OPS.items())],
+        }))
+        return
     args = ap.parse_args()
 
     TOKEN_FILE, TOKEN_DIR = args.token_file, args.token_dir
@@ -1501,7 +1587,7 @@ def main():
     BIN_DIR, JOBS_DIR = args.bin_dir, args.jobs_dir
     WORK_DIR = args.work_dir
 
-    server = HTTPServer((args.host, args.port), Handler)
+    server = ThreadingHTTPServer((args.host, args.port), Handler)
 
     cert_file = args.cert_file
     key_file = args.key_file

bin/fleet-alert-check.sh

@@ -34,6 +34,11 @@ set -uo pipefail
 
 THRESHOLD="${FLEET_ALERT_THRESHOLD:-2}"
 REALERT_MIN="${FLEET_ALERT_REALERT_MIN:-30}"
+# Approval/input-wait TTLs (seconds): conditions failing longer than this are
+# auto-expired (input waits dismissed, key requests denied) instead of paging
+# forever. Overridable per environment.
+INPUT_WAIT_TTL="${FLEET_ALERT_INPUT_WAIT_TTL:-1800}"
+BROWSER_APPROVAL_TTL="${FLEET_ALERT_BROWSER_APPROVAL_TTL:-1800}"
 QUIET_HOURS="${FLEET_ALERT_QUIET_HOURS:-}"
 DRY_RUN="${FLEET_ALERT_DRY_RUN:-0}"
 INJECT_FAIL="${FLEET_ALERT_INJECT_FAIL:-}"
@@ -51,14 +56,18 @@ NOW=$(date +%s)
 log() { echo "$(date -Iseconds) $*" >> "$LOG"; }
 
 # --- shared consecutive-failure state machine (also used by the container relay) ---
-# usage: state_machine <cond> <failing 0|1>  -> prints "<ACTION> <fails>"
-# ACTION: ALERT_FIRST | ALERT_REALERT | RECOVERY | SUPPRESSED | NONE
+# usage: state_machine <cond> <failing 0|1> [ttl_seconds] -> prints "<ACTION> <fails>"
+# When ttl_seconds > 0 and the condition has failed longer than the TTL,
+# prints "EXPIRED <fails>" so the caller can auto-resolve (dismiss/deny).
+# State entries track first_fail_ts (epoch of first consecutive failure).
+# ACTION: ALERT_FIRST | ALERT_REALERT | RECOVERY | SUPPRESSED | EXPIRED | NONE
 state_machine() {
-    local cond="$1" failing="$2"
+    local cond="$1" failing="$2" ttl="${3:-0}"
     THRESHOLD="$THRESHOLD" REALERT_MIN="$REALERT_MIN" QUIET_HOURS="$QUIET_HOURS" \
-    FLEET_ALERT_DRY_RUN="$DRY_RUN" python3 - "$STATE" "$cond" "$failing" <<'PYEOF'
+    FLEET_ALERT_DRY_RUN="$DRY_RUN" python3 - "$STATE" "$cond" "$failing" "$ttl" <<'PYEOF'
 import json, os, sys, time
 state_path, cond, failing_s = sys.argv[1], sys.argv[2], sys.argv[3]
+ttl_seconds = int(sys.argv[4]) if len(sys.argv) > 4 else 0
 failing = failing_s == "1"
 threshold = int(os.environ.get("THRESHOLD", "2"))
 realert_min = int(os.environ.get("REALERT_MIN", "30"))
@@ -85,23 +94,34 @@ except Exception:
 e = st.get(cond) or {"fails": 0, "alerted": False, "last_alert_ts": 0}
 action = "NONE"
 if failing:
+    if int(e.get("fails", 0)) == 0:
+        e["first_fail_ts"] = now
     e["fails"] = int(e.get("fails", 0)) + 1
-    due = e["fails"] >= threshold and (
-        not e.get("alerted") or now - int(e.get("last_alert_ts", 0)) >= realert_min * 60
-    )
-    if due:
-        first = not e.get("alerted")
-        if not first and in_quiet(qh):
-            action = "SUPPRESSED"
-        else:
-            action = "ALERT_FIRST" if first else "ALERT_REALERT"
-            e["alerted"] = True
-            e["last_alert_ts"] = now
+    # TTL expiry: failing longer than ttl_seconds -> EXPIRED (caller auto-resolves)
+    if ttl_seconds > 0 and now - int(e.get("first_fail_ts", now)) >= ttl_seconds:
+        action = "EXPIRED"
+        # Reset so a fresh incident starts clean after the caller resolves it
+        e["fails"] = 0
+        e["alerted"] = False
+        e.pop("first_fail_ts", None)
+    else:
+        due = e["fails"] >= threshold and (
+            not e.get("alerted") or now - int(e.get("last_alert_ts", 0)) >= realert_min * 60
+        )
+        if due:
+            first = not e.get("alerted")
+            if not first and in_quiet(qh):
+                action = "SUPPRESSED"
+            else:
+                action = "ALERT_FIRST" if first else "ALERT_REALERT"
+                e["alerted"] = True
+                e["last_alert_ts"] = now
 else:
     if e.get("alerted"):
         action = "RECOVERY"
     e["fails"] = 0
     e["alerted"] = False
+    e.pop("first_fail_ts", None)
 st[cond] = e
 if not dry:
     json.dump(st, open(state_path, "w"))
@@ -151,6 +171,28 @@ box_notify() {
     for p in $pids; do wait "$p" 2>/dev/null; done
 }
 
+notify_input_wait() {
+    # Targeted DM for input waits (2026-10-05): DM ONLY the specific agent
+    # whose session is waiting for human input -- not a broadcast to all
+    # healthy agents. The #lobby post still fires via the relay leg for
+    # human visibility; this DM ensures the responsible operator sees it
+    # in their sidechat without digging through lobby noise.
+    # Best-effort: never fatal to the 5-minute check loop.
+    local node="$1"
+    local detail="$2"
+    local msg="[fleet-alert] INPUT WAIT: ${detail} -- reply: box approval reply ${node} \"<msg>\" or box notify ${node} \"<msg>\""
+    msg="${msg:0:900}"
+    if [ "$DRY_RUN" = "1" ]; then
+        log "DRY-RUN would DM $node re input_wait"
+        return 0
+    fi
+    if timeout 60 python3 "$BIN/box-ctl.py" notify "$node" "$msg" >/dev/null 2>&1; then
+        log "input_wait targeted DM sent to $node"
+    else
+        log "input_wait DM to $node failed (best-effort, non-fatal)"
+    fi
+}
+
 injected() { # cond -> 0 if injected-fail
     case ",$INJECT_FAIL," in *,"$1,"*) return 0;; *) return 1;; esac
 }
@@ -185,29 +227,36 @@ HEALTHY_AGENTS=""
     esac
 done
 
-# --- Agent approval blockage detection (catches agents held up on approvals) ---
+# --- Agent approval blockage & input wait detection ---
 "$BIN/netvm-registry.py" 2>/dev/null | while IFS=: read -r node port; do
     [ -n "$node" ] || continue
-    cond="approval:$node"
-    pending_info=$(python3 -c "
-import sys
+    node_data=$(python3 -c "
+import sys, json
 sys.path.insert(0, '$BIN')
 import approvals
 info = approvals.inspect_node_approvals('$node')
-if info.get('has_pending'):
-    print(f\"{info.get('ip') or 'unknown'}|{info.get('title') or ''}\")
-" 2>/dev/null || true)
+out = {
+    'has_pending': info.get('has_pending', False),
+    'target': info.get('target') or info.get('ip') or 'unknown',
+    'title': info.get('title') or '',
+    'waits': info.get('input_waits') or []
+}
+print(json.dumps(out))
+" 2>/dev/null || echo '{"has_pending":false,"target":"unknown","title":"","waits":[]}')
 
-    if [ -n "$pending_info" ]; then
+    # 1. Egress permission dialog
+    cond="approval:$node"
+    has_pending=$(python3 -c "import json,sys; print(1 if json.loads(sys.argv[1]).get('has_pending') else 0)" "$node_data" 2>/dev/null || echo 0)
+    if [ "$has_pending" = "1" ]; then
         failing=1
-        target="${pending_info%%|*}"
+        target=$(python3 -c "import json,sys; print(json.loads(sys.argv[1]).get('target','unknown'))" "$node_data" 2>/dev/null || echo unknown)
         detail="Agent $node held up on browser approval for $target"
     else
         failing=0
         detail="Agent $node approvals clear"
     fi
     injected "$cond" && failing=1
-    read -r action fails < <(state_machine "$cond" "$failing")
+    read -r action fails < <(state_machine "$cond" "$failing" "$BROWSER_APPROVAL_TTL")
     case "$action" in
         ALERT_FIRST|ALERT_REALERT)
             emit_record "ALERT" "$cond" "$detail" "$fails"
@@ -219,6 +268,73 @@ if info.get('has_pending'):
         SUPPRESSED)
             log "$cond still critical x$fails — re-page suppressed"
             ;;
+        EXPIRED)
+            # Browser approval dialog exceeded BROWSER_APPROVAL_TTL without a
+            # human decision: fail closed by denying it.
+            log "$cond EXPIRED after ${BROWSER_APPROVAL_TTL}s without human decision — auto-denying (fail closed)"
+            python3 - "$node" <<'PYEOF3'
+import sys, json
+sys.path.insert(0, "/home/super/Projects/NetVM/bin")
+import approvals
+node = sys.argv[1]
+print(json.dumps(approvals.deny_node_approval(node, caller="approval-ttl-expire")))
+approvals.log_box_ctl("approval-expired", name=node, caller="approval-ttl-expire",
+                      extra={"note": "browser approval TTL elapsed; auto-denied (fail closed)"})
+PYEOF3
+            emit_record "RECOVERY" "$cond" "Agent $node browser approval expired after ${BROWSER_APPROVAL_TTL}s; auto-denied" "$fails"
+            ;;
+    esac
+
+    # 2. Sidebar task waiting on human input
+    cond_in="input_wait:$node"
+    wait_summary=$(python3 -c "
+import json,sys
+w = json.loads(sys.argv[1]).get('waits', [])
+if w:
+    print('; '.join(f\"{item.get('task')}: {item.get('status')}\" for item in w)[:120])
+" "$node_data" 2>/dev/null || true)
+
+    if [ -n "$wait_summary" ]; then
+        failing_in=1
+        detail_in="Agent $node task waiting for human input: $wait_summary"
+    else
+        failing_in=0
+        detail_in="Agent $node tasks running"
+    fi
+    injected "$cond_in" && failing_in=1
+    read -r action_in fails_in < <(state_machine "$cond_in" "$failing_in" "$INPUT_WAIT_TTL")
+    case "$action_in" in
+        ALERT_FIRST|ALERT_REALERT)
+            emit_record "ALERT" "$cond_in" "$detail_in" "$fails_in"
+            echo "$cond_in|$detail_in" >> "$STATE_DIR/.alerts.tmp"
+            ;;
+        RECOVERY)
+            emit_record "RECOVERY" "$cond_in" "$detail_in" "$fails_in"
+            ;;
+        SUPPRESSED)
+            log "$cond_in still critical x$fails_in — re-page suppressed"
+            ;;
+        EXPIRED)
+            # Input wait exceeded INPUT_WAIT_TTL without human response:
+            # auto-dismiss so the agent unblocks. Log the expiry and emit a
+            # RECOVERY record (the wait is gone, not merely un-paged).
+            log "$cond_in EXPIRED after ${INPUT_WAIT_TTL}s without human input — auto-dismissing"
+            python3 - "$node" <<'PYEOF2'
+import sys
+sys.path.insert(0, "/home/super/Projects/NetVM/bin")
+import approvals, json
+node = sys.argv[1]
+info = approvals.inspect_node_approvals(node)
+for w in info.get("input_waits", []) or []:
+    t = w.get("task")
+    if t:
+        approvals.mark_wait_responded(node, t, caller="approval-ttl-expire")
+approvals.log_box_ctl("approval-wait-expired", name=node, caller="approval-ttl-expire",
+                      extra={"note": "input wait TTL elapsed; auto-dismissed"})
+print(json.dumps(approvals.dismiss_node_task(node, caller="approval-ttl-expire")))
+PYEOF2
+            emit_record "RECOVERY" "$cond_in" "Agent $node input wait expired after ${INPUT_WAIT_TTL}s; auto-dismissed" "$fails_in"
+            ;;
     esac
 done
 
@@ -290,8 +406,26 @@ rm -f "$STATE_DIR/.healthy.tmp"
 # Notify for this run's alerts (best effort). Skip entirely when nothing is healthy
 # (notify needs a working browser via dm.py) or in dry-run.
 if [ -n "$HEALTHY_AGENTS" ] && [ -f "$STATE_DIR/.alerts.tmp" ]; then
-    while read -r cond; do
-        [ -n "$cond" ] && box_notify "$cond" "see #lobby for detail"
+    while IFS= read -r line; do
+        # alerts.tmp format: "cond" or "cond|detail" (input_wait carries detail)
+        cond="${line%%|*}"
+        detail="${line#*|}"
+        [ "$detail" = "$line" ] && detail=""
+        [ -n "$cond" ] || continue
+        case "$cond" in
+            input_wait:*)
+                # Targeted: DM only the waiting agent, not a broadcast.
+                node="${cond#input_wait:}"
+                if [ -n "$detail" ]; then
+                    notify_input_wait "$node" "$detail"
+                else
+                    box_notify "$cond" "see #lobby for detail"
+                fi
+                ;;
+            *)
+                box_notify "$cond" "see #lobby for detail"
+                ;;
+        esac
     done < "$STATE_DIR/.alerts.tmp"
 elif [ -f "$STATE_DIR/.alerts.tmp" ]; then
     log "no healthy agents — box notify skipped (DM path needs a working browser)"

bin/followup-sweeper.py

@@ -144,6 +144,164 @@ def _resolve_nudge_thread_uuid(nudge_output):
     return fallback
 
 
+_JOB_ID_RE = re.compile(r"^(.+)-(\d{8})-(\d{6})-([0-9a-f]{8})$")
+_OP_NAME_RE = re.compile(r"^[a-z][a-z0-9_.]{0,63}$")
+_JOB_NAME_RE = re.compile(r"^[a-z0-9-]{1,64}$")
+_FALLBACK_RETRY_S = 3600
+
+
+def fallback_due(rec, now=None):
+    """True when a terminal followup should (re)attempt its on_no_result fallback.
+
+    Fires once per record; a failed attempt may retry after _FALLBACK_RETRY_S.
+    Shared by the sweeper terminal path and gravity remediate so the two
+    firing paths can never double-execute.
+    """
+    fb = rec.get("fallback") or {}
+    if fb.get("ran"):
+        return False
+    ts = fb.get("ts")
+    if not ts:
+        return True
+    try:
+        last = datetime.fromisoformat(str(ts).replace("Z", "+00:00"))
+    except Exception:
+        return True
+    if last.tzinfo is None:
+        last = last.replace(tzinfo=timezone.utc)
+    base = now or utcnow_dt()
+    return (base - last).total_seconds() >= _FALLBACK_RETRY_S
+
+_EXEC_OPS_MOD = None
+
+
+def derive_job_name(job_id):
+    """Extract the job name from a dispatched job_id (<name>-YYYYMMDD-HHMMSS-<hex8>)."""
+    m = _JOB_ID_RE.match(job_id or "")
+    if not m:
+        return None
+    name = m.group(1)
+    if not (JOBS_DIR / f"{name}.json").exists():
+        return None
+    return name
+
+
+def load_job_fallback(job_name):
+    """Return (spec, error) for a job's on_no_result fallback.
+
+    spec is None when the job declares none. Shape:
+      {"job": "<job-name>"}             -> dispatch a fallback job, or
+      {"op": "<exec-op>", "args": {...}} -> run one exec-constrained op.
+    """
+    try:
+        with open(JOBS_DIR / f"{job_name}.json", "r", encoding="utf-8") as f:
+            cfg = json.load(f)
+    except Exception as e:
+        return None, f"unreadable job {job_name}: {e}"
+    spec = cfg.get("on_no_result")
+    if spec is None:
+        return None, None
+    if not isinstance(spec, dict) or set(spec) - {"job", "op", "args"}:
+        return None, "on_no_result must be an object with job|op (+args)"
+    if bool(spec.get("job")) == bool(spec.get("op")):
+        return None, "on_no_result needs exactly one of job|op"
+    if spec.get("job"):
+        jn = spec["job"]
+        if not isinstance(jn, str) or not _JOB_NAME_RE.fullmatch(jn):
+            return None, "on_no_result.job must be a valid job name"
+        if not (JOBS_DIR / f"{jn}.json").exists():
+            return None, f"on_no_result.job {jn!r} does not exist"
+    else:
+        if not isinstance(spec.get("op"), str) or not _OP_NAME_RE.fullmatch(spec["op"]):
+            return None, "on_no_result.op must be a valid op name"
+        if "args" in spec and not isinstance(spec["args"], dict):
+            return None, "on_no_result.args must be an object"
+    return spec, None
+
+
+def _load_exec_ops():
+    global _EXEC_OPS_MOD
+    if _EXEC_OPS_MOD is None:
+        import importlib.util
+        mod_spec = importlib.util.spec_from_file_location(
+            "exec_constrained_sweeper", str(BIN_DIR / "exec-constrained.py"))
+        mod = importlib.util.module_from_spec(mod_spec)
+        mod_spec.loader.exec_module(mod)
+        _EXEC_OPS_MOD = mod
+    return _EXEC_OPS_MOD
+
+
+def run_no_result_fallback(rec, dry_run=False):
+    """Execute a job's on_no_result fallback at terminal followup expiry.
+
+    Returns an outcome dict; never raises (failures are outcome data so
+    one bad spec can't break the sweep).
+    """
+    dm_id = rec.get("dm_id", "?")
+    outcome = {"dm_id": dm_id, "ran": False, "mode": None,
+               "configured": False, "detail": "no job fallback"}
+    try:
+        job_name = derive_job_name(rec.get("job_id"))
+        if not job_name:
+            outcome["detail"] = "no resolvable job_id"
+            return outcome
+        spec, err = load_job_fallback(job_name)
+        if err:
+            outcome.update(configured=True, detail=err)
+            return outcome
+        if spec is None:
+            return outcome
+        outcome["configured"] = True
+        if dry_run:
+            outcome.update(mode="dry_run", detail=json.dumps(spec)[:200])
+            return outcome
+        if spec.get("job"):
+            env = os.environ.copy()
+            env["CHAIN_PREV_JOB_ID"] = rec.get("job_id", "")
+            env["CHAIN_PREV_RESULT"] = (
+                f"TIMEOUT: Agent {rec.get('recipient')} gave no result; "
+                f"on_no_result fallback for job {job_name}")
+            cmd = [sys.executable, str(DISPATCH_PY), spec["job"]]
+            try:
+                p = subprocess.run(cmd, capture_output=True, text=True,
+                                   timeout=180, env=env)
+            except Exception as e:
+                outcome.update(mode="job", detail=f"dispatch exception: {e}")
+                return outcome
+            ok = p.returncode == 0
+            outcome.update(ran=ok, mode="job",
+                           detail=(f"dispatched {spec['job']}" if ok
+                                   else f"dispatch failed: {(p.stderr or p.stdout).strip()[:200]}"))
+        else:
+            mod = _load_exec_ops()
+            op = spec["op"]
+            op_spec = mod.OPS.get(op)
+            if op_spec is None:
+                outcome["detail"] = f"unknown op: {op}"
+                return outcome
+            args = dict(spec.get("args") or {})
+            try:
+                clean = op_spec["validate"](args)
+            except Exception as e:
+                outcome["detail"] = f"op validation failed: {e}"
+                return outcome
+            argv = op_spec["build"](clean)
+            try:
+                p = subprocess.run(argv, capture_output=True, text=True,
+                                   timeout=op_spec.get("timeout", 120))
+            except Exception as e:
+                outcome.update(mode="op", detail=f"op exception: {e}")
+                return outcome
+            ok = p.returncode == 0
+            out = (p.stdout or p.stderr or "").strip()
+            outcome.update(ran=ok, mode="op",
+                           detail=(f"{op} ok: {out[:200]}" if ok
+                                   else f"{op} failed rc={p.returncode}: {out[:200]}"))
+    except Exception as e:
+        outcome["detail"] = f"fallback exception: {e}"
+    return outcome
+
+
 def sweep_cycle(dry_run=False):
     followups = load_followups()
     if not followups:
@@ -152,6 +310,7 @@ def sweep_cycle(dry_run=False):
     now = utcnow_dt()
     nudges_count = 0
     escalations_count = 0
+    fallbacks_count = 0
     modified = False
 
     for dm_id, rec in list(followups.items()):
@@ -334,6 +493,31 @@ def sweep_cycle(dry_run=False):
                                     pipeline_engine.fail_pipeline(run_entry.get("run_id"), "step_timed_out_without_fallback")
                             except Exception:
                                 pass
+                # on_no_result fallback: the agent never replied, so run
+                # the job's declared server-side effect now (if any).
+                # fallback_due() dedupes against the gravity firing path.
+                fb = (run_no_result_fallback(rec) if fallback_due(rec)
+                      else {"configured": False, "ran": False, "mode": None,
+                            "detail": "fallback already ran"})
+                if fb["configured"]:
+                    rec["fallback"] = {"ran": fb["ran"], "mode": fb["mode"],
+                                       "detail": fb["detail"][:200],
+                                       "ts": utcnow_str()}
+                    modified = True
+                    append_job_log({
+                        "ts": utcnow_str(),
+                        "type": ("fallback_executed" if fb["ran"]
+                                 else "fallback_failed"),
+                        "dm_id": dm_id,
+                        "recipient": recipient,
+                        "job_id": rec.get("job_id"),
+                        "mode": fb["mode"],
+                        "detail": fb["detail"][:300],
+                    })
+                    print(f"Sweeper: on_no_result fallback for {dm_id}: "
+                          f"ran={fb['ran']} {fb['detail'][:120]}")
+                    if fb["ran"]:
+                        fallbacks_count += 1
             else:
                 escalations_count += 1
 
@@ -346,6 +530,7 @@ def sweep_cycle(dry_run=False):
         "pending": pending_count,
         "nudges_sent": nudges_count,
         "escalations": escalations_count,
+        "fallbacks": fallbacks_count,
     }
 
 

bin/gravity.py

@@ -632,7 +632,7 @@ def diagnose_breaks() -> list:
             if app.get("has_pending"):
                 node = app["node"]
                 is_trusted = app.get("is_trusted", False)
-                ip = app.get("ip") or "unknown target"
+                ip = app.get("target") or app.get("ip") or "unknown target"
                 breaks.append({
                     "type": "approval_blocked",
                     "severity": "WARNING" if is_trusted else "CRITICAL",
@@ -641,12 +641,78 @@ def diagnose_breaks() -> list:
                     "detail": f"Agent {node} is held up on browser approval for {ip}",
                     "remedy": f"Run 'box approvals auto' or 'box approvals allow {node}'."
                 })
+            for w in app.get("input_waits") or []:
+                node = app["node"]
+                breaks.append({
+                    "type": "input_wait",
+                    "severity": "WARNING",
+                    "component": f"node:{node}",
+                    "agent": node,
+                    "detail": f"Agent {node} task '{w.get('task')}' is waiting: {w.get('status')} ({w.get('when')})",
+                    "remedy": f"Open {node}'s task and answer it, or 'box approvals check --node {node}'."
+                })
     except Exception:
         pass
 
     return breaks
 
 
+def _load_sweeper_module():
+    import importlib.util
+    mod_spec = importlib.util.spec_from_file_location(
+        "followup_sweeper_gravity",
+        str(Path(__file__).resolve().parent / "followup-sweeper.py"))
+    mod = importlib.util.module_from_spec(mod_spec)
+    mod_spec.loader.exec_module(mod)
+    return mod
+
+
+def maybe_run_terminal_fallback(rec, now_iso, dry_run=False):
+    """Run a job's on_no_result fallback once at terminal followup expiry.
+
+    Returns an outcome dict, or None when the record has no resolvable
+    fallback. Never raises. The sweeper terminal path shares the
+    fallback_due() guard, so the two firing paths can't double-execute.
+    """
+    try:
+        sw = _load_sweeper_module()
+    except Exception as e:
+        return {"ran": False, "mode": None,
+                "detail": f"sweeper import failed: {e}"}
+    try:
+        if not sw.fallback_due(rec):
+            return None
+        job_name = sw.derive_job_name(rec.get("job_id"))
+        if not job_name:
+            return None
+        spec, err = sw.load_job_fallback(job_name)
+        if err or spec is None:
+            return None
+        if dry_run:
+            return {"ran": False, "mode": "dry_run",
+                    "detail": json.dumps(spec)[:200]}
+        out = sw.run_no_result_fallback(rec)
+        rec["fallback"] = {"ran": out["ran"], "mode": out["mode"],
+                           "detail": out["detail"][:200], "ts": now_iso}
+        try:
+            sw.append_job_log({
+                "ts": now_iso,
+                "type": ("fallback_executed" if out["ran"]
+                         else "fallback_failed"),
+                "dm_id": rec.get("dm_id"),
+                "recipient": rec.get("recipient"),
+                "job_id": rec.get("job_id"),
+                "mode": out["mode"],
+                "detail": out["detail"][:300],
+            })
+        except Exception:
+            pass
+        return out
+    except Exception as e:
+        return {"ran": False, "mode": None,
+                "detail": f"fallback exception: {e}"}
+
+
 def remediate_breaks(dry_run=False) -> dict:
     """Progressively auto-remediate soft loop breakages while escalating hard breakages.
 
@@ -736,6 +802,20 @@ def remediate_breaks(dry_run=False) -> dict:
                         f_modified = True
                         rearm_sweeper = True
 
+                # Terminal: nudges exhausted and still no reply. Run the
+                # job's on_no_result fallback (server-side guarantee).
+                if is_expired and nudges_sent >= nudges_allowed:
+                    fb = maybe_run_terminal_fallback(rec, now_iso, dry_run)
+                    if fb is not None:
+                        remediated.append({
+                            "action": "terminal_fallback",
+                            "loop_id": dm_id,
+                            "agent": rec.get("recipient"),
+                            "detail": f"on_no_result ran={fb.get('ran')}: {fb.get('detail', '')[:160]}",
+                        })
+                        if not dry_run and "fallback" in rec:
+                            f_modified = True
+
         if f_modified and not dry_run:
             tmp = f"{f_path}.tmp.{os.getpid()}"
             with open(tmp, "w") as f:
@@ -746,7 +826,10 @@ def remediate_breaks(dry_run=False) -> dict:
             sweeper_py = Path("/home/super/Projects/NetVM/bin/followup-sweeper.py")
             if sweeper_py.exists():
                 try:
-                    subprocess.run([sys.executable, str(sweeper_py), "--once"], timeout=10)
+                    # A single nudge send takes ~10s median; give the sweep
+                    # room to finish or it dies mid-first-send every time.
+                    subprocess.run([sys.executable, str(sweeper_py), "--once"],
+                                   timeout=300)
                 except Exception:
                     pass
 
@@ -755,10 +838,10 @@ def remediate_breaks(dry_run=False) -> dict:
         import approvals
         fleet_apps = approvals.check_fleet_approvals()
         for app in fleet_apps:
-            if app.get("has_pending") and app.get("is_trusted"):
+            if app.get("has_pending") and app.get("is_trusted") and app.get("status") != "KEY_APPROVAL":
                 node = app["node"]
                 if not dry_run:
-                    approvals.allow_node_approval(node, caller="loop-remediate")
+                    approvals.allow_node_approval(node, always=True, caller="loop-remediate")
                 remediated.append({
                     "type": "approval_auto_allowed",
                     "agent": node,
@@ -809,4 +892,24 @@ def remediate_breaks(dry_run=False) -> dict:
     }
 
 
+def main(argv=None):
+    import argparse
+    ap = argparse.ArgumentParser(description="Loop gravity: reconcile and remediate followup loops")
+    ap.add_argument("--remediate", action="store_true",
+                    help="Run remediate_breaks once (what loop-remediator.timer invokes)")
+    ap.add_argument("--dry-run", action="store_true",
+                    help="Report actions without writing state or sending anything")
+    args = ap.parse_args(argv)
+    if not args.remediate:
+        ap.print_help()
+        return 2
+    result = remediate_breaks(dry_run=args.dry_run)
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+
+
 

bin/job-dispatch.py

@@ -503,6 +503,26 @@ def main():
     elif job.get("target"):
         target = job.get("target").strip()
 
+    # Pre-dispatch approval & input check (auto-approve trusted; warn if blocked)
+    if not dry_run:
+        try:
+            import approvals
+            app_info = approvals.inspect_node_approvals(agent)
+            if app_info.get("has_pending"):
+                if app_info.get("is_trusted") and app_info.get("status") != "KEY_APPROVAL":
+                    print(f"Pre-dispatch: auto-approving trusted request for {agent} ({app_info.get('target')})")
+                    approvals.allow_node_approval(agent, always=True, caller="job-dispatch")
+                else:
+                    print(f"Warning: Agent '{agent}' has untrusted pending approval ({app_info.get('target')}). Dispatch may stall.", file=sys.stderr)
+                    log_event("job_dispatch_approval_blocked", {"job_id": job_id, "agent": agent, "target": app_info.get("target")})
+            elif app_info.get("status") == "INPUT_WAIT":
+                waits = app_info.get("input_waits", [])
+                w_desc = "; ".join(w.get("task", "") for w in waits)[:80]
+                print(f"Notice: Agent '{agent}' has task waiting for input ({w_desc}).", file=sys.stderr)
+                log_event("job_dispatch_agent_input_wait", {"job_id": job_id, "agent": agent, "waits": w_desc})
+        except Exception:
+            pass
+
     # Sidechat-first policy (2026-10-04): refuse to dispatch to main chat
     # unless the job explicitly opts in. Never fall back to main silently.
     allow_main = bool(job.get("allow_main_chat")) or args.allow_main_chat

bin/lookup

@@ -0,0 +1 @@
+/home/super/Projects/NetVM/bin/docs-lookup.py

bin/lookup_engine.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""lookup_engine.py — Shared Zero-Downtime Hot-Reloading Pattern & Schema Engine.
+
+Provides authoritative runtime access to lookup_internal/ databases for
+daemons (response-harvester, self_main_loop, job-dispatch), CLI commands,
+and agents.
+
+Features:
+- Dynamic mtime-based zero-downtime hot reloading of compiled regex patterns.
+- Pre-flight soft validation of outbound agent sentences and work orders.
+- Direct helper functions for core protocol regexes (RESULT, VERB, TOOL, etc.).
+"""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+NETVM_ROOT = Path(__file__).resolve().parent.parent
+LOOKUP_INTERNAL = NETVM_ROOT / "lookup_internal"
+if not LOOKUP_INTERNAL.exists() and (NETVM_ROOT / "docs_internal").exists():
+    LOOKUP_INTERNAL = NETVM_ROOT / "docs_internal"
+
+# In-memory cache structures with modification timestamps
+_CACHE_MTIMES: Dict[str, float] = {}
+_RAW_CACHE: Dict[str, Any] = {}
+_COMPILED_PATTERNS: Dict[str, re.Pattern] = {}
+
+# Fallback hardcoded regexes in case files are missing or unreadable
+_FALLBACK_RESULT_RE = re.compile(r"\[RESULT\s+([A-Za-z0-9_/-]+)\]\s*(.*?)(?=\[RESULT\s|\Z)", re.S)
+_FALLBACK_VERB_RE = re.compile(r"\[(ACK|CLAIM|RESULT|DECLINE|NO-ACTION)\s+([A-Za-z0-9_/-]+)\]")
+_FALLBACK_TOOL_RE = re.compile(r"\[(TOOL|EXEC|DM)\s+(?:([a-zA-Z0-9_.-]+)\s+)?(\{([^{}]|\{[^{}]*\})*\})\]", re.S)
+_FALLBACK_CONTRACT_FOOTER = (
+    "Reply: [ACK id] seen | [CLAIM id] mine | "
+    "[RESULT id] done | [DECLINE id] | [NO-ACTION id]."
+)
+
+
+def load_lookup_json(filename: str) -> Dict[str, Any]:
+    """Load JSON from lookup_internal/ with mtime-based caching."""
+    target_path = LOOKUP_INTERNAL / filename
+    if not target_path.is_file():
+        return {}
+
+    try:
+        current_mtime = os.path.getmtime(target_path)
+    except OSError:
+        return _RAW_CACHE.get(filename, {})
+
+    if filename in _RAW_CACHE and _CACHE_MTIMES.get(filename) == current_mtime:
+        return _RAW_CACHE[filename]
+
+    try:
+        with open(target_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        _RAW_CACHE[filename] = data
+        _CACHE_MTIMES[filename] = current_mtime
+        return data
+    except Exception as e:
+        print(f"[lookup_engine] Warning: Error reading {target_path}: {e}", file=sys.stderr)
+        return _RAW_CACHE.get(filename, {})
+
+
+def _refresh_compiled_patterns_if_needed():
+    """Checks regex_patterns.json mtime and recompiles if changed."""
+    global _COMPILED_PATTERNS
+    data = load_lookup_json("regex_patterns.json")
+    patterns_data = data.get("patterns", {})
+
+    target_path = LOOKUP_INTERNAL / "regex_patterns.json"
+    current_mtime = _CACHE_MTIMES.get("regex_patterns.json", 0.0)
+    compiled_mtime = _CACHE_MTIMES.get("_compiled_patterns_mtime", 0.0)
+
+    if current_mtime == compiled_mtime and _COMPILED_PATTERNS:
+        return
+
+    new_compiled = {}
+    for key, entry in patterns_data.items():
+        raw_pat = entry.get("pattern", "")
+        flag_names = entry.get("flags", [])
+        flags = 0
+        for fn in flag_names:
+            if hasattr(re, fn):
+                flags |= getattr(re, fn)
+        try:
+            new_compiled[key] = re.compile(raw_pat, flags)
+        except Exception as e:
+            print(f"[lookup_engine] Warning: Failed to compile pattern '{key}': {e}", file=sys.stderr)
+
+    _COMPILED_PATTERNS = new_compiled
+    _CACHE_MTIMES["_compiled_patterns_mtime"] = current_mtime
+
+
+def get_compiled_pattern(name: str) -> Optional[re.Pattern]:
+    """Retrieve a compiled pattern by name, hot-reloading if the database was modified."""
+    _refresh_compiled_patterns_if_needed()
+    return _COMPILED_PATTERNS.get(name)
+
+
+def get_all_compiled_patterns() -> Dict[str, re.Pattern]:
+    """Retrieve all compiled patterns with automatic hot-reloading."""
+    _refresh_compiled_patterns_if_needed()
+    return dict(_COMPILED_PATTERNS)
+
+
+def get_result_regex() -> re.Pattern:
+    """Return the canonical [RESULT ...] regex."""
+    p = get_compiled_pattern("result")
+    return p if p is not None else _FALLBACK_RESULT_RE
+
+
+def get_verb_regex() -> re.Pattern:
+    """Return the canonical [VERB ...] regex (ACK|CLAIM|RESULT|DECLINE|NO-ACTION)."""
+    p = get_compiled_pattern("verb")
+    return p if p is not None else _FALLBACK_VERB_RE
+
+
+def get_tool_regex() -> re.Pattern:
+    """Return the canonical [TOOL ...] regex."""
+    p = get_compiled_pattern("tool_call")
+    return p if p is not None else _FALLBACK_TOOL_RE
+
+
+def get_contract_footer() -> str:
+    """Return standard contract footer string."""
+    struct_data = load_lookup_json("sentence_structure.json")
+    cf = struct_data.get("structures", {}).get("contract_footer", {})
+    return cf.get("example") or _FALLBACK_CONTRACT_FOOTER
+
+
+def parse_agent_utterance(text: str) -> List[Dict[str, Any]]:
+    """Pass text through all registered patterns and extract matched tokens."""
+    _refresh_compiled_patterns_if_needed()
+    patterns_data = load_lookup_json("regex_patterns.json").get("patterns", {})
+    matches = []
+
+    for key, compiled in _COMPILED_PATTERNS.items():
+        m = compiled.search(text)
+        if m:
+            entry = patterns_data.get(key, {})
+            matches.append({
+                "pattern_key": key,
+                "pattern_name": entry.get("name", key),
+                "matched_text": m.group(0),
+                "named_groups": m.groupdict(),
+                "span": m.span()
+            })
+    return matches
+
+
+def validate_outbound_sentence(text: str) -> Tuple[bool, Optional[str], Optional[str]]:
+    """Pre-flight check for outbound messages sent via CLI.
+
+    Returns:
+        (is_valid, matched_kind, warning_or_hint)
+    """
+    cleaned = text.strip()
+    # If message starts with bracketed protocol marker
+    if cleaned.startswith("["):
+        marker = cleaned.split("]")[0] + "]"
+        upper_marker = marker.upper()
+
+        if upper_marker.startswith("[WO:") or upper_marker.startswith("[WORKORDER:"):
+            wo_pat = get_compiled_pattern("work_order")
+            if wo_pat and not wo_pat.search(cleaned):
+                hint = (
+                    "Notice: Message starts with a Work Order marker but does not match canonical structure.\n"
+                    "  Expected format: [WO:<id>] [from <sender>] <title> — <body>\n"
+                    "  Example: [WO:7fce46e0] [from super] Audit endpoints — Check GET /api/stats\n"
+                    "  Hint: Query 'box lookup sentence work_order' for full spec."
+                )
+                return False, "work_order", hint
+            return True, "work_order", None
+
+        if upper_marker.startswith("[ACK:") or upper_marker.startswith("[ACK "):
+            ack_pat = get_compiled_pattern("ack")
+            verb_pat = get_compiled_pattern("verb")
+            if (ack_pat and not ack_pat.search(cleaned)) and (verb_pat and not verb_pat.search(cleaned)):
+                hint = (
+                    "Notice: Message looks like an ACK but deviates from standard syntax.\n"
+                    "  Expected format: [ACK:<id>] [from <sender>] or [ACK <id>]\n"
+                    "  Example: [ACK:7fce46e0] [from 646]"
+                )
+                return False, "ack", hint
+            return True, "ack", None
+
+        if upper_marker.startswith("[RESULT"):
+            res_pat = get_result_regex()
+            if not res_pat.search(cleaned):
+                hint = (
+                    "Notice: Message starts with [RESULT] but deviates from standard syntax.\n"
+                    "  Expected format: [RESULT <job_id>] <status> <summary>\n"
+                    "  Example: [RESULT 7fce46e0] OK Task completed successfully"
+                )
+                return False, "result", hint
+            return True, "result", None
+
+    return True, "plain_message", None

bin/muse

@@ -16,20 +16,28 @@ VALID_ACCOUNTS=("muse" "pip" "646" "opm" "def" "dev")
 show_usage() {
     echo "Usage: muse <account> <command> [arguments...]"
     echo "       muse -a <account> <command> [arguments...]"
+    echo "       muse <global-command> [arguments...]"
     echo ""
     echo "Available accounts:"
     for acct in "${VALID_ACCOUNTS[@]}"; do
         echo "  • $acct"
     done
     echo ""
-    echo "Common commands:"
+    echo "Global lookups & tools:"
+    echo "  tmux [args...]          Manage shared Muse tmux sessions (new, send, capture, ls, kill, prune)"
+    echo "  status                  Fleet overview & node vitality"
+    echo "  threads                 List registered threads and sidechats across fleet"
+    echo "  unread                  View unread counts across all agents"
+    echo "  lookup [subcommand]     Unified lookup (fleet, threads, unread, approvals, key)"
+    echo "  passkey (or key)        View passkey location (VM-only), PIN, & agent approval protocol"
+    echo ""
+    echo "Per-account commands:"
     echo "  chat [--thread <id>]    Launch interactive conversational shell / REPL"
-    echo "  tmux <cmd> [args...]    Manage shared Muse tmux sessions (new, send, capture, ls, kill)"
-    echo "  status                  Check agent status, sessions, and unread"
-    echo "  threads                 List active threads and sidechats"
+    echo "  status                  Check account status, sessions, and unread"
+    echo "  threads                 List active threads and sidechats for account"
     echo "  history --thread <id>   View message history"
     echo "  send --thread <id> msg  Send message to an agent"
-    echo "  unread                  View unread counts"
+    echo "  unread                  View unread counts for account"
     echo ""
     echo "Authentication & Cookie Management:"
     echo "  Cookies are isolated per-node in ~/.config/muse-cli/<account>/"
@@ -37,6 +45,40 @@ show_usage() {
     echo ""
 }
 
+# Direct top-level global actions that do not require an account
+if [[ $# -gt 0 ]]; then
+    case "$1" in
+        tmux)
+            shift
+            exec python3 "$NETVM_BIN/muse-tmux.py" "$@"
+            ;;
+        passkey|key)
+            shift
+            exec python3 "$NETVM_BIN/super-cli.py" passkey "$@"
+            ;;
+        lookup|lookups)
+            shift
+            exec python3 "$NETVM_BIN/super-cli.py" lookup "$@"
+            ;;
+        fleet)
+            shift
+            exec python3 "$NETVM_BIN/super-cli.py" fleet "$@"
+            ;;
+        threads)
+            shift
+            exec python3 "$NETVM_BIN/super-cli.py" thread list "$@"
+            ;;
+        unread)
+            shift
+            exec python3 "$NETVM_BIN/super-cli.py" lookup unread "$@"
+            ;;
+        status)
+            shift
+            exec python3 "$NETVM_BIN/super-cli.py" fleet status "$@"
+            ;;
+    esac
+fi
+
 ACCOUNT=""
 POSITIONAL=()
 

bin/muse-tmux.py

@@ -6,6 +6,7 @@ Socket location: /tmp/tmux-muse.sock (shared across fleet agents & super).
 import sys
 import os
 import re
+import time
 import subprocess
 import argparse
 
@@ -181,6 +182,13 @@ def cmd_attach(args):
     session = args.session
     node = getattr(args, "node", None)
     container = getattr(args, "container", None)
+    
+    # Graceful non-interactive fallback for autonomous agents
+    if not sys.stdin.isatty():
+        sys.stderr.write(f"Notice: Non-interactive terminal (no tty). Capturing recent scrollback for '{session}':\n\n")
+        setattr(args, "lines", getattr(args, "lines", 30) or 30)
+        return cmd_capture(args)
+
     if node:
         cmd = ["/home/super/Projects/NetVM/bin/netvm-exec.sh", node, "--", TMUX_BIN, "-S", f"/tmp/tmux-{node}.sock", "attach", "-t", session]
         os.execv(cmd[0], cmd)

bin/muse_tui.py

@@ -0,0 +1 @@
+muse-tui.py

bin/netvm-exec.sh

@@ -9,5 +9,5 @@ NODE="${1:?usage: netvm-exec.sh <node> -- <cmd> [args...]}"; shift
 [ "${1:-}" = "--" ] && shift
 [ $# -gt 0 ] || { echo "usage: netvm-exec.sh <node> -- <cmd> [args...]"; exit 1; }
 [ -f "/etc/netvm/${NODE}.conf" ] || { echo "no warp identity for '$NODE' (human: netvm-new-identity.sh $NODE)"; exit 1; }
-ip netns list 2>/dev/null | grep -q "^warp-${NODE}" || { echo "node '$NODE' is not up (netvm-node-up.sh $NODE)"; exit 1; }
+[ "$(ip netns list 2>/dev/null | grep -c "^warp-${NODE}")" -ge 1 ] || { echo "node '$NODE' is not up (netvm-node-up.sh $NODE)"; exit 1; }
 exec sudo -n "$NETVM_BIN/netvm-enter.sh" "$NODE" "$(id -u)" "$(id -g)" "$HOME" -- "$@"

bin/prompt_envelope.py

@@ -17,7 +17,10 @@ BOX_API = "https://box.muse-dev.online/api/box"
 
 def _response_rule():
     return (
-        "\nRESPONSE RULE: Execute your steps using [TOOL ...] directives or background tmux commands."
+        "\nRESPONSE RULE: Act by EMITTING [TOOL ...] / [DM ...] directive lines verbatim in your reply"
+        " — you do not run them yourself. The Box runtime on bl executes each directive"
+        " (this works from containers with no box CLI or tmux socket) and posts the result back here."
+        " Background tmux commands work too when you have a shell."
         " When complete, conclude your output with the [RESULT ...] line so the harvester records it.\n"
     )
 
@@ -57,14 +60,22 @@ def pick_profile(job_name):
 
 
 def _tool(op, args):
-    # no ']' inside the JSON: the harvester's [TOOL ...] regex stops at the first one
+    # the harvester extracts JSON args with balanced-brace scanning, so
+    # ']' and nested objects/arrays inside args are safe
     return "[TOOL %s %s]" % (op, json.dumps(args, separators=(", ", ": ")))
 
 
 def spawn_call(job_id, job_name, profile):
     count, _, hint = PROFILES[profile]
-    # no brackets in the task text: the harvester's [TOOL ...] regex stops at the first ']'
     task = "Subagent for job %s (%s): %s." % (job_id, job_name, hint)
+
+
+def dm_call(to, target, message):
+    return "[DM %s]" % json.dumps(
+        {"to": to, "target": target, "message": message[:900]},
+        separators=(", ", ": "))
+
+
     return _tool("swarm.spawn", {"count": count, "task": task[:900], "label": (job_name or "job")[:60]})
 
 
@@ -111,7 +122,9 @@ def wrap(job_name, job_id, agent, target, rendered):
     bottom = (
         "\n--- End Task ---\n\n"
         f"Inspect tmux output: [TOOL tmux.capture {{\"session\": \"{session_name}\", \"lines\": 30}}]\n"
-        "Tools available: cron.create, cron.runs, health.check, swarm.spawn, swarm.list.\n"
+        "Tools: cron.create, cron.runs, health.check, swarm.spawn, swarm.list, dm.send, box.exec, tools.list.\n"
+        "Message a peer: [DM {\"to\": \"<agent>\", \"target\": \"<sidechat>\", \"message\": \"<text>\"}].\n"
+        "Query box: [TOOL box.exec {\"action\": \"<fleet-status|dm-log|job-get|...>\"}] \u2014 [TOOL tools.list {}] lists every op.\n"
     )
     if not has_result:
         bottom += f"When complete, report your verdict: [RESULT {job_id}] OK: <summary of actions>\n"
@@ -119,3 +132,18 @@ def wrap(job_name, job_id, agent, target, rendered):
         bottom += f"Conclude with your [RESULT {job_id}] line reporting outcomes.\n"
     return top + rendered.strip() + "\n" + bottom
 
+
+def wrap_subagent_task(job_id, task_text):
+    """Format an authentic direct task assignment for a subagent worker without test-traffic meta tags."""
+    return (
+        f"Operator assignment for swarm slot {job_id}:\n\n"
+        f"Task:\n"
+        f"{task_text.strip()}\n\n"
+        f"Instructions:\n"
+        f"1. Carry out this task directly using your available tools.\n"
+        f"2. When finished, conclude your final response with your verdict line:\n"
+        f"[RESULT {job_id}] OK: <one-line summary of actions and outcome>\n"
+        f"(or [RESULT {job_id}] FAIL: <reason> if the task could not be completed)\n"
+    )
+
+

bin/response-harvester.py

@@ -83,18 +83,32 @@ try:
 except ImportError:
     HAS_MUSE_HYBRID = False
 
+try:
+    import prompt_envelope
+    HAS_PROMPT_ENVELOPE = True
+except ImportError:
+    HAS_PROMPT_ENVELOPE = False
+
 VALID_AGENTS = ["muse", "pip", "646", "opm", "dev", "def"]
 DEFAULT_PORTS = {"muse": 9410, "pip": 9420, "646": 9430, "opm": 9440, "def": 9450, "dev": 9455}
 
+try:
+    import lookup_engine
+    HAS_LOOKUP_ENGINE = True
+except ImportError:
+    HAS_LOOKUP_ENGINE = False
+
 # Matches EVERY [RESULT <job_id>] marker in a message (use with finditer, not
 # search). The result text is lazy and stops before the next marker (or end of
 # text), so a message closing two jobs records each with its own text instead
 # of the first marker greedily swallowing the second.
-RESULT_RE = re.compile(r"\[RESULT\s+([A-Za-z0-9_-]+)\]\s*(.*?)(?=\[RESULT\s|\Z)", re.S)
+_LOCAL_RESULT_RE = re.compile(r"\[RESULT\s+([A-Za-z0-9_/-]+)\]\s*(.*?)(?=\[RESULT\s|\Z)", re.S)
+RESULT_RE = lookup_engine.get_result_regex() if HAS_LOOKUP_ENGINE else _LOCAL_RESULT_RE
 
 def iter_result_markers(text):
     """Yield (job_id, result_text) for every [RESULT <job_id>] marker in text."""
-    for m in RESULT_RE.finditer(text or ""):
+    current_re = lookup_engine.get_result_regex() if HAS_LOOKUP_ENGINE else RESULT_RE
+    for m in current_re.finditer(text or ""):
         yield m.group(1).strip(), m.group(2).strip()
 
 
@@ -103,12 +117,14 @@ def iter_result_markers(text):
 # ACK/CLAIM acknowledge a digest (nudge-suppressed, NOT closed);
 # RESULT/DECLINE/NO-ACTION close the digest. Every verb match records
 # outcome=<verb> on the followup record.
-VERB_RE = re.compile(r"\[(ACK|CLAIM|RESULT|DECLINE|NO-ACTION)\s+([A-Za-z0-9_-]+)\]")
+_LOCAL_VERB_RE = re.compile(r"\[(ACK|CLAIM|RESULT|DECLINE|NO-ACTION)\s+([A-Za-z0-9_/-]+)\]")
+VERB_RE = lookup_engine.get_verb_regex() if HAS_LOOKUP_ENGINE else _LOCAL_VERB_RE
 
 
 def iter_verb_markers(text):
     """Yield (verb, job_id) for every [VERB <job_id>] marker in text."""
-    for m in VERB_RE.finditer(text or ""):
+    current_re = lookup_engine.get_verb_regex() if HAS_LOOKUP_ENGINE else VERB_RE
+    for m in current_re.finditer(text or ""):
         yield m.group(1), m.group(2).strip()
 
 
@@ -138,6 +154,12 @@ NATIVE_ALIASES = {
     "subagents.spawn": "swarm.spawn",
     "subagent.list": "swarm.list",
     "subagent.status": "swarm.status",
+    "dm": "dm.send",
+    "message.send": "dm.send",
+    "box": "box.exec",
+    "box.run": "box.exec",
+    "tools": "tools.list",
+    "tools.list": "tools.list",
 }
 
 
@@ -168,6 +190,23 @@ def normalize_native_call(op, args):
                     break
         if "count" not in args and "n" in args:
             args["count"] = args.pop("n")
+    elif op == "dm.send":
+        if "message" not in args:
+            for k in ("text", "body", "content", "msg"):
+                if k in args:
+                    args["message"] = args.pop(k)
+                    break
+        if "target" not in args:
+            for k in ("thread", "sidechat", "channel"):
+                if k in args:
+                    args["target"] = args.pop(k)
+                    break
+    elif op == "box.exec":
+        if "action" not in args:
+            for k in ("cmd", "verb", "command", "run"):
+                if k in args:
+                    args["action"] = args.pop(k)
+                    break
     elif op.startswith("tmux."):
         if "session" not in args:
             for k in ("name", "target", "s"):
@@ -182,24 +221,151 @@ def normalize_native_call(op, args):
     return op, args
 
 
+_TOOL_OPEN_RE = re.compile(r"\[(TOOL|EXEC)\s+([a-zA-Z0-9_.-]+)\s*")
+_DM_OPEN_RE = re.compile(r"\[DM\s+")
+
+
+def _extract_balanced_json(s, i):
+    """Extract one JSON object starting at s[i] == '{' (brace-aware, string-aware).
+
+    Returns (obj, end_index) with end_index just past the closing brace,
+    or (None, i) when no balanced object is present. Unlike a first-']'
+    regex this tolerates ']' (and nested objects/arrays) inside args.
+    """
+    if i >= len(s) or s[i] != "{":
+        return None, i
+    depth = 0
+    in_str = False
+    esc = False
+    for j in range(i, len(s)):
+        c = s[j]
+        if in_str:
+            if esc:
+                esc = False
+            elif c == "\\":
+                esc = True
+            elif c == '"':
+                in_str = False
+        elif c == '"':
+            in_str = True
+        elif c == "{":
+            depth += 1
+        elif c == "}":
+            depth -= 1
+            if depth == 0:
+                try:
+                    return json.loads(s[i:j + 1]), j + 1
+                except Exception:
+                    return None, i
+    return None, i
+
+
+def _scan_bracket_calls(text):
+    """Yield (op, args) for [TOOL op {...}] / [EXEC op {...}] / [DM {...}].
+
+    JSON args are extracted with balanced-brace scanning so ']' inside
+    strings, arrays, or nested objects no longer truncates the call.
+    Non-JSON tails keep the legacy first-']' behavior (raw passthrough).
+    """
+    out = []
+    spans = []
+    for m in _TOOL_OPEN_RE.finditer(text or ""):
+        spans.append((m.start(), "tool", m.group(2).strip(), m.end()))
+    for m in _DM_OPEN_RE.finditer(text or ""):
+        spans.append((m.start(), "dm", "dm.send", m.end()))
+    spans.sort()
+    for _, kind, op, pos in spans:
+        if pos < len(text) and text[pos] == "{":
+            args, _ = _extract_balanced_json(text, pos)
+            if args is None:
+                continue
+            if not isinstance(args, dict):
+                args = {"raw": args}
+        elif kind == "dm":
+            continue  # [DM ...] requires a JSON object; skip bare forms
+        else:
+            end = text.find("]", pos)
+            if end == -1:
+                continue
+            raw_args = text[pos:end].strip()
+            if not raw_args:
+                args = {}
+            else:
+                try:
+                    args = json.loads(raw_args)
+                    if not isinstance(args, dict):
+                        args = {"raw": args}
+                except Exception:
+                    args = {"raw": raw_args}
+        out.append((op, args))
+    return out
+
+
+_PROOF_EVIDENCE_RE = re.compile(
+    r"sw-\d{8}-\d{6}-[0-9a-f]{4}"
+    r"|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
+    r"|/(?:[\w.-]+/)+[\w.-]+"
+    r"|\b(?:swarm|timer|cron|job|thread|sidechat|slot)[-_ ]?(?:id|name|uuid)?\s*[:=]"
+    r"|\b\d+/\d+\s*(?:slots?|checks?|workers?)",
+    re.IGNORECASE)
+_UUID_RE = re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}")
+
+
+def result_has_evidence(result_text):
+    """True when a RESULT verdict carries checkable artifacts (IDs, paths, counts)."""
+    return bool(_PROOF_EVIDENCE_RE.search(result_text or ""))
+
+
+def maybe_request_proof(agent, thread_id, job_id, result_text, dry_run=False):
+    """Ask for checkable evidence when a success RESULT has none.
+
+    One-shot per (thread, job) via the nudge tracker. Returns True when a
+    proof followup was scheduled.
+    """
+    if dry_run or not thread_id or not _UUID_RE.fullmatch(thread_id.lower()):
+        return False
+    if result_has_evidence(result_text):
+        return False
+    tracker = load_json_file(NUDGE_TRACKER_FILE)
+    rec = tracker.get(thread_id, {})
+    done = rec.get("proof_jobs", [])
+    if job_id in done:
+        return False
+    ok, res = execute_agent_tool(agent, "followup.create", {
+        "agent": agent,
+        "in_m": 30,
+        "thread": thread_id,
+        "prompt": (
+            f"[PROOF] Your [RESULT {job_id}] has no checkable evidence. "
+            f"Reply in this thread with the swarm/timer IDs, paths, or command output "
+            f"that prove the outcome — or say what is still missing."),
+    })
+    if ok:
+        rec["proof_jobs"] = (done + [job_id])[-50:]
+        tracker[thread_id] = rec
+        save_json_file(NUDGE_TRACKER_FILE, tracker)
+        append_jsonl(JOB_LOG, {
+            "ts": utcnow(),
+            "type": "proof_requested",
+            "job_id": job_id,
+            "agent": agent,
+            "thread_id": thread_id,
+        })
+        return True
+    sys.stderr.write(f"warning: proof followup failed for {job_id}: {res}\n")
+    return False
+
+
 def parse_tool_calls(text):
     """
     Extract structured tool/exec calls from assistant messages.
     Supports:
-      1. [TOOL <op> <json_args>] or [EXEC <op> <json_args>]
-      2. ```box / ```tool / ```exec JSON blocks
+      1. [TOOL <op> <json_args>] or [EXEC <op> <json_args>] (JSON may nest)
+      2. [DM <json_args>] shorthand for dm.send
+      3. ```box / ```tool / ```exec JSON blocks
     """
     calls = []
-    for m in re.finditer(r"\[(?:TOOL|EXEC)\s+([a-zA-Z0-9_.-]+)(?:\s+(.*?))?\]", text or ""):
-        op = m.group(1).strip()
-        raw_args = (m.group(2) or "").strip()
-        args = {}
-        if raw_args:
-            try:
-                args = json.loads(raw_args)
-            except Exception:
-                args = {"raw": raw_args}
-        calls.append((op, args))
+    calls.extend(_scan_bracket_calls(text))
 
     for m in re.finditer(r"```(?:box|tool|exec)\s*\n(.*?)```", text or "", re.DOTALL):
         block = m.group(1).strip()
@@ -295,6 +461,10 @@ def format_tool_result_for_chat(op, raw_output):
         data = json.loads(raw_output)
     except Exception:
         s = str(raw_output).strip()
+        if op == "box.exec":
+            if len(s) > 900:
+                s = s[:900] + "\n…(truncated, refine the call for detail)"
+            return f"box result:\n```\n{s}\n```"
         return s[:500] if len(s) > 500 else s
 
     if op == "health.check" and isinstance(data, dict) and "fleet" in data:
@@ -369,6 +539,26 @@ def format_tool_result_for_chat(op, raw_output):
         sw = data.get("swarm", {})
         return f"Swarm `{sw.get('swarm_id')}`: {sw.get('status')} ({sw.get('done', 0)}/{sw.get('count', 0)} slots completed)."
 
+    if op == "tools.list" and isinstance(data, dict):
+        ops = data.get("ops", [])
+        if not ops:
+            return "No tools registered."
+        ro = [o["op"] for o in ops if not o.get("side_effecting")]
+        se = [o["op"] for o in ops if o.get("side_effecting")]
+        lines = [f"{len(ops)} tools available via [TOOL <op> <args>]."]
+        lines.append("read-only: " + (", ".join(ro) if ro else "none"))
+        if se:
+            lines.append("side-effecting: " + ", ".join(se))
+        return "\n".join(lines)
+
+    if op == "box.exec" and isinstance(data, dict):
+        if data.get("ok") is False:
+            return f"box call failed: {data.get('error', 'unknown error')}"
+        out = json.dumps(data)
+        if len(out) > 900:
+            out = out[:900] + "\n…(truncated, refine the call for detail)"
+        return f"box result:\n```\n{out}\n```"
+
     # General fallback: compact JSON capped to 400 chars
     s = json.dumps(data)
     return s[:400] + "..." if len(s) > 400 else s
@@ -503,6 +693,26 @@ def get_monitored_threads(target_agent=None):
         except Exception:
             continue
 
+    # Also monitor active swarm slot subagents from swarms.json
+    try:
+        if SWARM_FILE.exists():
+            s_data = json.loads(SWARM_FILE.read_text(encoding="utf-8"))
+            for sid, s_info in s_data.items():
+                if sid.startswith("_") or not isinstance(s_info, dict):
+                    continue
+                if s_info.get("status") not in ("running", "pending"):
+                    continue
+                for slot in s_info.get("slots", []):
+                    if slot.get("status") == "running":
+                        sub_id = slot.get("subagent_session_id") or slot.get("thread_uuid") or slot.get("sidechat_id")
+                        ag = slot.get("agent_id")
+                        if sub_id and ag and ag in threads_by_agent:
+                            existing = [t["id"] for t in threads_by_agent[ag]]
+                            if sub_id not in existing:
+                                threads_by_agent[ag].append({"id": sub_id, "name": f"swarm-{sid[:8]}-s{slot.get('slot')}"})
+    except Exception as se:
+        sys.stderr.write(f"warning: failed to add swarm threads to monitor list: {se}\n")
+
     return threads_by_agent
 
 
@@ -738,9 +948,14 @@ def process_messages(raw_messages, agent, thread_id, thread_name, last_wm, follo
                             thread_url = f"https://box.muse-dev.online/thread/{thread_id}"
                             tool_hint = (
                                 f"[Runtime Context: {thread_url}]\n"
-                                f"Tools available: [TOOL <op> <args>] or curl -sk -X POST https://exec.muse-dev.online/exec\n"
+                                f"Tools: EMIT one [TOOL <op> <args>] line per action (you do not run it;"
+                                f" the runtime executes it and replies here). curl -sk -X POST"
+                                f" https://exec.muse-dev.online/exec works too.\n"
+                                f"  • [TOOL tools.list {{}}] — discover every op dynamically\n"
+                                f"  • [TOOL swarm.spawn {{\"count\": 1, \"task\": \"<task>\"}}] — spawn subagents\n"
+                                f"  • [DM {{\"to\": \"<agent>\", \"target\": \"<sidechat>\", \"message\": \"<text>\"}}] — send a DM\n"
+                                f"  • [TOOL box.exec {{\"action\": \"fleet-status\"}}] — call box (read-only actions)\n"
                                 f"  • [TOOL followup.create {{\"in_m\": 5, \"prompt\": \"<reminder>\"}}]\n"
-                                f"  • [TOOL swarm.spawn {{\"count\": 1, \"task\": \"<task>\"}}]\n"
                                 f"  • [TOOL health.check {{}}]\n\n"
                                 f"[Directive: Take next action or close with [RESULT <job_id>] <summary>]"
                             )
@@ -784,7 +999,11 @@ def process_messages(raw_messages, agent, thread_id, thread_name, last_wm, follo
                         else:
                             trigger_chain_next(job_id, result_text, success=not is_fail)
                         if not is_fail:
-                            archive_ephemeral_thread(agent, thread_id, job_id=job_id)
+                            try:
+                                maybe_request_proof(agent, thread_id, job_id, result_text)
+                            except Exception as pe:
+                                sys.stderr.write(f"warning: proof check failed: {pe}\n")
+                        archive_ephemeral_thread(agent, thread_id, job_id=job_id)
                     clear_matching_followups(followups, agent, thread_id, mid, text,
                                              dry_run, job_id=job_id, verb="RESULT")
                 for verb, job_id in verbs:
@@ -794,7 +1013,8 @@ def process_messages(raw_messages, agent, thread_id, thread_name, last_wm, follo
                                              dry_run, job_id=job_id, verb=verb)
             else:
                 clear_matching_followups(followups, agent, thread_id, mid, text, dry_run)
-                maybe_nudge_untagged_sidechat(agent, thread_id, thread_name, mid, text, dry_run=dry_run)
+                maybe_nudge_untagged_sidechat(agent, thread_id, thread_name, mid, text,
+                                              dry_run=dry_run, acted=bool(tool_calls))
 
     return new_messages, new_wm, job_results
 
@@ -925,6 +1145,13 @@ def archive_ephemeral_thread(agent, thread_id, job_id=None):
     except Exception as e:
         sys.stderr.write(f"warning: failed to update job-sidechats state: {e}\n")
 
+    # Complete subagent tracker record if this thread corresponds to an ephemeral subagent session
+    try:
+        import subagent_tracker
+        subagent_tracker.complete_session(thread_id, note=f"Harvested verdict for job {job_id}")
+    except Exception:
+        pass
+
     # Call muse-threads.py archive via subprocess (runs in node's netns)
     try:
         helper = BIN_DIR / "muse-threads.py"
@@ -940,7 +1167,13 @@ def archive_ephemeral_thread(agent, thread_id, job_id=None):
 # NOTE 2026-10-05 (Fix Agent 2/5): dev/def removed from the pool. No worker
 # agents exist on dev/def (no Meta sessions provisioned), so slots dispatched
 # to them froze with null results. Re-add only after real dev/def workers exist.
-SWARM_WORKER_POOL = ["dev", "def", "muse"]
+# NOTE 2026-10-06 (split-brain dispatch fix): the removal above was comment-only;
+# the code still listed dev/def, and the harvester's every-minute dispatch raced
+# the pool daemon claiming slots as dev/def, which refuse on attribution grounds
+# (dev FAILs fast, def freezes until the 60-min reaper). Pool now matches
+# swarm_worker/daemon.py WORKER_POOL exactly: only muse, the single fully
+# authenticated auxiliary worker.
+SWARM_WORKER_POOL = ["muse"]
 
 # Stuck-slot reaper: a slot that stays "running" with no result longer than
 # this is treated as wedged (worker died / dispatch lost). Healthy slots
@@ -968,7 +1201,8 @@ def reconcile_and_dispatch_swarms(dry_run=False):
     """
     Autonomous Swarm Orchestrator:
     1. Scans swarms.json for pending slots.
-    2. Dynamically allocates available auxiliary worker nodes (dev, def, muse).
+    2. Dynamically allocates the auxiliary worker pool (muse only; dev/def have
+    no provisioned worker agents and refuse on attribution grounds).
     3. Provisions ephemeral sidechat per slot and dispatches the task with [RESULT <swarm_id>/<slot>].
     4. Upon completion of all slots, sends completion summary DM to originating coordinator.
     """
@@ -1047,11 +1281,19 @@ def reconcile_and_dispatch_swarms(dry_run=False):
                     slot_target = f"{sid}-s{slot_idx}"
 
                     # Prepare task directive prompt
-                    prompt = (
-                        f"[JOB {sid}/{slot_idx}] Task for swarm slot {slot_idx}:\n"
-                        f"{task_text}\n\n"
-                        f"Reply with [RESULT {sid}/{slot_idx}] OK <summary> or FAIL <reason>."
-                    )
+                    slot_job_id = f"{sid}/{slot_idx}"
+                    if HAS_PROMPT_ENVELOPE and hasattr(prompt_envelope, "wrap_subagent_task"):
+                        prompt = prompt_envelope.wrap_subagent_task(slot_job_id, task_text)
+                    else:
+                        prompt = (
+                            f"Operator assignment for swarm slot {slot_job_id}:\n\n"
+                            f"Task:\n{task_text.strip()}\n\n"
+                            f"Instructions:\n"
+                            f"1. Carry out this task directly using your available tools.\n"
+                            f"2. When finished, conclude your final response with your verdict line:\n"
+                            f"[RESULT {slot_job_id}] OK: <one-line summary of actions and outcome>\n"
+                            f"(or [RESULT {slot_job_id}] FAIL: <reason> if the task could not be completed)\n"
+                        )
 
                     # Native Subagent Execution Bridge:
                     # Spawns an interactive child session directly on the target worker
@@ -1196,7 +1438,13 @@ def check_and_archive_terminal_swarms():
     for sid, swarm in swarms_data.items():
         st = swarm.get("status")
         if st in ("completed", "partial", "killed"):
-            # Check slots or matching sidechats
+            # Check slot subagent sessions
+            for slot in swarm.get("slots", []):
+                sub_id = slot.get("subagent_session_id")
+                ag = slot.get("agent_id")
+                if sub_id and ag:
+                    archive_ephemeral_thread(ag, sub_id, job_id=sid)
+            # Check matching registered sidechats
             for key, val in sc_data.items():
                 if isinstance(val, dict) and not val.get("archived") and val.get("type") != "persistent":
                     if sid in key or (swarm.get("label") and swarm.get("label") in key):
@@ -1207,10 +1455,13 @@ def check_and_archive_terminal_swarms():
 
 
 
-def maybe_nudge_untagged_sidechat(agent, thread_id, thread_name, mid, text, dry_run=False):
+def maybe_nudge_untagged_sidechat(agent, thread_id, thread_name, mid, text, dry_run=False,
+                                acted=False):
     """
     If an agent replies conversationally in a sidechat backed by a job or follow-up
     without providing [RESULT <id>] or tool directives, deliver a terse 1-turn nudge footer.
+    When acted=True the agent DID emit directives but never closed: remind to close
+    with [RESULT] instead of rejecting the (good) action.
     """
     if dry_run or not thread_id or thread_id == "main":
         return
@@ -1255,14 +1506,23 @@ def maybe_nudge_untagged_sidechat(agent, thread_id, thread_name, mid, text, dry_
                 matching_job_id, matching_job_id, prompt_envelope.pick_profile(matching_job_id))
         except Exception:
             _spawn = '[TOOL swarm.spawn {"count": 2, "task": "continue the job work"}]'
-        nudge_msg = (
-            f"{_spawn}\n"
-            f"[STRICT ENFORCEMENT: Conversational commentary is rejected. Work requires active execution.]\n"
-            f"Thread Console: {thread_url}\n"
-            f"Emit executable tool calls now: [TOOL <op> <args>] or curl against https://exec.muse-dev.online/exec\n"
-            f"When all operations are finished, close strictly with [RESULT {matching_job_id}] <outcome>.\n"
-            f"{_spawn}"
-        )
+        if acted:
+            nudge_msg = (
+                f"Action received — now close the loop: reply with [RESULT {matching_job_id}] <outcome>.\n"
+                f"Outcome needs checkable evidence (swarm/timer IDs, paths, or command output), not prose alone.\n"
+                f"Thread Console: {thread_url}"
+            )
+        else:
+            nudge_msg = (
+                f"{_spawn}\n"
+                f"[STRICT ENFORCEMENT: Conversational commentary is rejected. Work requires active execution.]\n"
+                f"Thread Console: {thread_url}\n"
+                f"EMIT tool calls verbatim in your reply — you do not run them yourself;"
+                f" the Box runtime on bl executes each directive and posts the result back here"
+                f" (works from containers with no box CLI). Or curl against https://exec.muse-dev.online/exec\n"
+                f"When all operations are finished, close strictly with [RESULT {matching_job_id}] <outcome>.\n"
+                f"{_spawn}"
+            )
         try:
             import muse_hybrid
             print(f"[{agent}] Injecting 1-turn strict nudge into {thread_name or thread_id[:8]} for job {matching_job_id}")

bin/self_main_loop.py

@@ -280,10 +280,17 @@ def make_digest_id(agent):
 # recursive box->agent->box discipline: post the RESULT back in this thread
 # (box records it and dispatches the next chained step); never DM the next
 # agent directly. ~166 chars, within the 600-char digest budget.
-CONTRACT_FOOTER = ("Reply: [ACK id] seen | [CLAIM id] mine | "
-                   "[RESULT id] done | [DECLINE id] | [NO-ACTION id]. "
-                   "Report back here. Box dispatches the next step; "
-                   "do not DM the next agent directly.")
+try:
+    import lookup_engine
+    HAS_LOOKUP_ENGINE = True
+except ImportError:
+    HAS_LOOKUP_ENGINE = False
+
+_DEFAULT_CONTRACT_FOOTER = ("Reply: [ACK id] seen | [CLAIM id] mine | "
+                           "[RESULT id] done | [DECLINE id] | [NO-ACTION id]. "
+                           "Report back here. Box dispatches the next step; "
+                           "do not DM the next agent directly.")
+CONTRACT_FOOTER = lookup_engine.get_contract_footer() if HAS_LOOKUP_ENGINE else _DEFAULT_CONTRACT_FOOTER
 
 
 def send_prompt(sender, agent, sidechat, digest):

bin/super-cli.py

@@ -403,7 +403,7 @@ def cmd_approvals(args):
     action = getattr(args, "app_action", None) or "check"
     node = getattr(args, "node", None)
 
-    if action in ("check", "list"):
+    if action in ("check", "list", "inspect"):
         nodes = [node] if node else VALID_NODES
         fleet = approvals.check_fleet_approvals(nodes)
         if getattr(args, "json", False):
@@ -415,6 +415,7 @@ def cmd_approvals(args):
         rows = []
         pending_count = 0
         untrusted_count = 0
+        input_wait_count = 0
 
         for it in fleet:
             n = it["node"]
@@ -422,12 +423,28 @@ def cmd_approvals(args):
             if st == "PENDING":
                 pending_count += 1
                 badge = badge_err("PENDING") if not it.get("is_trusted") else badge_warn("PENDING")
-                target = it.get("ip") or "-"
+                target = it.get("target") or it.get("ip") or "-"
                 purp = (it.get("purpose") or it.get("title") or "-")[:50]
                 trust = c_green("TRUSTED") if it.get("is_trusted") else c_red("UNTRUSTED")
                 btns = " ".join([f"[{b}]" for b in it.get("buttons", [])])
                 if not it.get("is_trusted"):
                     untrusted_count += 1
+            elif st == "KEY_APPROVAL":
+                pending_count += 1
+                badge = badge_warn("KEY_REQ")
+                target = it.get("target") or "VM passkey"
+                purp = (it.get("purpose") or it.get("title") or "-")[:50]
+                trust = c_cyan("OPERATOR")
+                btns = " ".join([f"[{b}]" for b in it.get("buttons", ["Allow", "Deny"])])
+                untrusted_count += 1
+            elif st == "INPUT_WAIT":
+                waits = it.get("input_waits") or []
+                badge = badge_warn("INPUT")
+                target = "-"
+                purp = "; ".join(f"{w.get('task')}: {w.get('status')}" for w in waits)[:60]
+                trust = "-"
+                btns = c_dim("answer in task")
+                input_wait_count += 1
             elif st == "UNREACHABLE":
                 badge = badge_dim("OFFLINE")
                 target = "-"
@@ -451,29 +468,71 @@ def cmd_approvals(args):
 
         print_table(headers, rows)
 
+        if input_wait_count > 0:
+            print("\n" + c_yellow(f"  ⚠ {input_wait_count} node(s) have tasks waiting for human input (not auto-resolvable)."))
         if pending_count > 0:
             print("\n" + c_yellow(f"  ⚠ {pending_count} pending approval(s) detected across fleet."))
             if untrusted_count > 0:
-                print(c_red(f"  ⚠ {untrusted_count} UNTRUSTED approval(s) require manual review: 'box approvals allow <node> --force' or 'box approvals deny <node>'."))
+                print(c_red(f"  ⚠ {untrusted_count} approval(s) require manual review / key grant: 'box approvals allow <node>' or 'box approvals deny <node>'."))
             else:
                 print(c_cyan("  All pending approvals are for trusted infrastructure. Run 'box approvals auto' to resolve."))
             print()
-        else:
+        elif input_wait_count == 0:
             print("\n" + c_green("  ✔ All agent approval queues clear. No agents blocked.") + "\n")
 
+        # Verbose or inspect breakdown
+        is_verbose = getattr(args, "verbose", False) or action == "inspect"
+        if is_verbose:
+            print(c_bold("\n=== DETAILED NODE INSPECTION ==="))
+            for it in fleet:
+                n = it["node"]
+                if it.get("has_pending") or it.get("input_waits") or action == "inspect":
+                    print(f"\n  [{c_bold(n)}] Status: {it.get('status')} | Page: {c_cyan(it.get('page_url') or '-')}")
+                    if it.get("has_pending"):
+                        print(f"    Egress Target: {it.get('target') or it.get('ip')} ({'TRUSTED' if it.get('is_trusted') else 'UNTRUSTED'})")
+                        print(f"    Prompt Title : {it.get('title')}")
+                        if it.get("purpose"):
+                            print(f"    Purpose      : {it.get('purpose')}")
+                        print(f"    Buttons      : {', '.join(it.get('buttons') or [])}")
+                    if it.get("input_waits"):
+                        print(f"    Tasks Awaiting Human Input ({len(it['input_waits'])}):")
+                        for w in it["input_waits"]:
+                            print(f"      • {c_bold(w.get('task'))}")
+                            print(f"        Status: {w.get('status')} ({w.get('when')})")
+                    # Correlate with active subagents on this node
+                    try:
+                        import subagent_tracker
+                        active_subs = subagent_tracker.get_active_sessions(n)
+                        if active_subs:
+                            print(f"    Active Subagents on Node ({len(active_subs)}):")
+                            for sub in active_subs[-3:]:
+                                s_id = sub.get("session_id", "")[:8]
+                                s_title = sub.get("title") or "subagent"
+                                print(f"      • [{s_id}] {c_bold(s_title)} (spawned: {sub.get('spawned_at', '-')})")
+                    except Exception:
+                        pass
+            print()
+
     elif action in ("allow", "approve"):
         if not node:
             print(c_red("Error: Must specify node for allow. e.g. 'box approvals allow 646'"), file=sys.stderr)
             sys.exit(1)
         always = getattr(args, "always", False)
         force = getattr(args, "force", False)
-        res = approvals.allow_node_approval(node, always=always, force=force)
+        message = getattr(args, "message", None)
+        allow_main_chat = getattr(args, "allow_main_chat", False)
+        res = approvals.allow_node_approval(node, always=always, force=force, message=message,
+                                            allow_main_chat=allow_main_chat)
         if getattr(args, "json", False):
             print(json.dumps(res, indent=2))
             return
         if res.get("ok"):
-            decision_str = "Always allow this site" if always else "Allow once"
-            print(c_green(f"✔ Approved request on node '{node}' ({decision_str}). Dialog dismissed: {res.get('dismissed')}."))
+            if res.get("type") == "key_approval":
+                notified = "agent notified" if res.get("notified") else "⚠ agent NOT notified (follow up manually)"
+                print(c_green(f"✔ Approved operator key request for node '{node}'. Logged to audit trail. {notified}."))
+            else:
+                decision_str = "Always allow this site" if always else "Allow once"
+                print(c_green(f"✔ Approved request on node '{node}' ({decision_str}). Dialog dismissed: {res.get('dismissed')}."))
         else:
             print(c_red(f"✖ Failed to approve on node '{node}': {res.get('error')}"))
             sys.exit(2 if "Untrusted" in res.get("error", "") else 1)
@@ -482,12 +541,18 @@ def cmd_approvals(args):
         if not node:
             print(c_red("Error: Must specify node for deny. e.g. 'box approvals deny 646'"), file=sys.stderr)
             sys.exit(1)
-        res = approvals.deny_node_approval(node)
+        message = getattr(args, "message", None)
+        allow_main_chat = getattr(args, "allow_main_chat", False)
+        res = approvals.deny_node_approval(node, message=message, allow_main_chat=allow_main_chat)
         if getattr(args, "json", False):
             print(json.dumps(res, indent=2))
             return
         if res.get("ok"):
-            print(c_green(f"✔ Denied request on node '{node}'. Dialog dismissed: {res.get('dismissed')}."))
+            if res.get("type") == "key_approval":
+                notified = "agent notified" if res.get("notified") else "⚠ agent NOT notified (follow up manually)"
+                print(c_green(f"✔ Denied operator key request for node '{node}'. Logged to audit trail. {notified}."))
+            else:
+                print(c_green(f"✔ Denied request on node '{node}'. Dialog dismissed: {res.get('dismissed')}."))
         else:
             print(c_red(f"✖ Failed to deny on node '{node}': {res.get('error')}"))
             sys.exit(1)
@@ -535,6 +600,61 @@ def cmd_approvals(args):
         except KeyboardInterrupt:
             print("\n" + c_dim("Exited watch mode."))
 
+    elif action == "reply":
+        if not node:
+            print(c_red("Error: Must specify node for reply. e.g. 'box approvals reply pip \"proceed\"'"), file=sys.stderr)
+            sys.exit(1)
+        message = getattr(args, "message", "")
+        allow_main = getattr(args, "allow_main_chat", False)
+        res = approvals.reply_node_task(node, message, allow_main_chat=allow_main)
+        if getattr(args, "json", False):
+            print(json.dumps(res, indent=2))
+            return
+        if res.get("ok"):
+            print(c_green(f"✔ Dispatched reply to node '{node}': \"{message}\" (thread: {res.get('page_url')})"))
+        else:
+            print(c_red(f"✖ Failed to reply to node '{node}': {res.get('error')}"))
+            sys.exit(2 if "Main Chat" in res.get("error", "") else 1)
+
+    elif action == "dismiss":
+        if not node:
+            print(c_red("Error: Must specify node for dismiss. e.g. 'box approvals dismiss pip'"), file=sys.stderr)
+            sys.exit(1)
+        res = approvals.dismiss_node_task(node)
+        if getattr(args, "json", False):
+            print(json.dumps(res, indent=2))
+            return
+        if res.get("ok"):
+            print(c_green(f"✔ Dismissed task popup on node '{node}' ({res.get('result')})."))
+        else:
+            print(c_red(f"✖ Failed to dismiss task popup on node '{node}': {res.get('error')}"))
+            sys.exit(1)
+    elif action in ("clear", "clear-all", "clear_all"):
+        target_node = node
+        if action in ("clear-all", "clear_all"):
+            target_node = None
+        res = approvals.clear_node_waits(target_node)
+        if getattr(args, "json", False):
+            print(json.dumps(res, indent=2))
+            return
+        cleared = res.get("total_cleared", 0)
+        target_desc = f"node '{target_node}'" if target_node else "all fleet nodes"
+        print(c_green(f"✔ Cleared {cleared} input wait(s) on {target_desc}."))
+
+    elif action in ("request-key", "request_key"):
+        if not node:
+            print(c_red("Error: Must specify node for request-key. e.g. 'box approvals request-key 646'"), file=sys.stderr)
+            sys.exit(1)
+        reason = getattr(args, "reason", "Operator passkey access requested")
+        caller = os.environ.get("BOX_CALLER") or getattr(args, "from_agent", "super")
+        res = approvals.request_key_approval(node, reason=reason, caller=caller)
+        if getattr(args, "json", False):
+            print(json.dumps(res, indent=2))
+            return
+        print(c_green(f"✔ Registered passkey approval request for node '{node}'."))
+        print(f"  Reason: {c_cyan(reason)}")
+        print(c_dim(f"  Operator can approve with: box approvals allow {node}"))
+
 def resolve_sender(args) -> str:
     explicit = getattr(args, "from_agent", None)
     if explicit and explicit != DEFAULT_SENDER:
@@ -864,6 +984,15 @@ def cmd_dm_send(args):
             sys.exit(1)
         print(c_yellow("  ⚠ [CHAT POLICY OVERRIDE] Main Chat targeted with --allow-main-chat. Keep interaction minimal."))
 
+    # Soft pre-flight grammar check against lookup_internal
+    try:
+        import lookup_engine
+        is_val, kind, hint = lookup_engine.validate_outbound_sentence(message)
+        if not is_val and hint:
+            print(c_yellow(f"\n  ⚠ [GRAMMAR NOTICE]\n  {hint}\n"), file=sys.stderr)
+    except Exception:
+        pass
+
     should_sign = (sender == "super") and not getattr(args, "no_sign", False)
     mid = None
     if should_sign:
@@ -929,7 +1058,8 @@ def cmd_dm_wo(args):
 
     wo_id = hashlib.sha256(f"{sender}-{recipient}-{title}-{time.time()}".encode()).hexdigest()[:8]
     prefix = "[URGENT] " if priority == "urgent" else ""
-    wo_content = f"{prefix}[WO:{wo_id}] {title} — {body}"
+    wo_content = f"{prefix}[WO:{wo_id}] [from {sender}] {title} — {body}"
+
 
     should_sign = (sender == "super") and not getattr(args, "no_sign", False)
     if should_sign:
@@ -1338,7 +1468,31 @@ def cmd_dm_files(args):
 # Domain: THREAD (Chat Oversight via box-chat.py)
 # ---------------------------------------------------------------------------
 def cmd_thread_list(args):
-    agent = args.agent
+    agent = getattr(args, "agent", None)
+    if not agent:
+        print("\n" + c_bold("=== FLEET REGISTERED SIDECHATS & THREAD MAPPINGS ===") + "\n")
+        sc_file = NETVM_ROOT / "job-sidechats.json"
+        rows = []
+        headers = ["TARGET / ALIAS", "AGENT", "THREAD UUID", "PURPOSE / NOTES"]
+        if sc_file.exists():
+            try:
+                with open(sc_file, "r") as f:
+                    data = json.load(f)
+                    for k, v in sorted(data.items()):
+                        if isinstance(v, dict):
+                            ag = v.get("agent", "-")
+                            uuid = v.get("thread_uuid") or v.get("uuid") or "-"
+                            desc = v.get("description") or v.get("purpose") or "-"
+                            rows.append([c_cyan(k), c_bold(ag), uuid, desc[:45]])
+                        elif isinstance(v, str):
+                            rows.append([c_cyan(k), "-", v, "-"])
+            except Exception as e:
+                print(c_red(f"Error reading job-sidechats.json: {e}"))
+        print_table(headers, rows)
+        print("\n" + c_dim("  To view specific thread: box thread view <agent> <uuid|alias>") + "\n")
+        print(c_dim("  To list agent active sessions: box thread list <agent>") + "\n")
+        return
+
     threads = []
     
     def is_noise(title):
@@ -1401,6 +1555,29 @@ def cmd_thread_view(args):
     limit = getattr(args, "limit", 15)
     messages = []
 
+    # 1. Resolve alias or name if known
+    try:
+        import dm
+        resolved = dm.resolve_sidechat_target(thread_id, agent)
+        if resolved and resolved != thread_id:
+            thread_id = resolved
+    except Exception:
+        pass
+
+    # 2. If short UUID prefix (6-12 hex chars), resolve against agent's thread list
+    if re.fullmatch(r"[0-9a-fA-F]{6,12}", str(thread_id).strip()):
+        try:
+            import muse_hybrid
+            gw_threads, _ = muse_hybrid.get_threads(agent)
+            if gw_threads:
+                for t in gw_threads:
+                    sid = t.get("session_id", "")
+                    if sid.lower().startswith(str(thread_id).strip().lower()):
+                        thread_id = sid
+                        break
+        except Exception:
+            pass
+
     # Fast path: try fast headless gateway via muse_hybrid (isolated per-node WARP egress)
     try:
         import muse_hybrid
@@ -3735,14 +3912,278 @@ def cmd_swarm_prune(args):
         sys.stdout.write(res.stdout)
 
 
+def cmd_passkey_info(args):
+    """Display operator passkey reference and agent approval architecture, or fetch from VM."""
+    action = getattr(args, "action", "show") or "show"
+    is_json = getattr(args, "json", False)
+
+    if action in ("fetch", "get"):
+        vm_host = "34.139.37.135"
+        vm_paths = ["/srv/box/passkey.txt", "/etc/netvm/passkey.txt"]
+        cmd = [
+            "ssh",
+            "-o", "BatchMode=yes",
+            "-o", "ConnectTimeout=3",
+            f"super@{vm_host}",
+            f"cat {vm_paths[0]} 2>/dev/null || cat {vm_paths[1]} 2>/dev/null"
+        ]
+        key_content = ""
+        fetch_err = None
+        try:
+            res = subprocess.run(cmd, capture_output=True, text=True, timeout=5)
+            if res.returncode == 0 and res.stdout.strip():
+                key_content = res.stdout.strip()
+            else:
+                fetch_err = res.stderr.strip() or "Empty output or authentication required"
+        except subprocess.TimeoutExpired:
+            fetch_err = "SSH connection timed out"
+        except Exception as e:
+            fetch_err = str(e)
+
+        if key_content:
+            if is_json:
+                print(json.dumps({
+                    "ok": True,
+                    "fetched": True,
+                    "passkey": key_content,
+                    "vm_host": vm_host,
+                    "path": vm_paths[0],
+                    "operator_pin": "3128",
+                    "surface": "https://box.muse-dev.online/"
+                }, indent=2))
+                return
+            print("\n" + c_bold("=== OPERATOR PASSKEY (FETCHED FROM VM) ===") + "\n")
+            print(f"  {c_bold('Passkey Content')}: {c_green(key_content)}")
+            print(f"  {c_bold('Source Host')}    : {c_cyan(vm_host)} ({vm_paths[0]})")
+            print(f"  {c_bold('Web Surface')}    : https://box.muse-dev.online/ (PIN: 3128)\n")
+            return
+        else:
+            if is_json:
+                print(json.dumps({
+                    "ok": False,
+                    "fetched": False,
+                    "vm_host": vm_host,
+                    "path": vm_paths[0],
+                    "fallback_path": vm_paths[1],
+                    "operator_pin": "3128",
+                    "surface": "https://box.muse-dev.online/",
+                    "error": f"Could not fetch passkey directly: {fetch_err}",
+                    "note": "Passkey is stored in a single .txt file on the VM (34.139.37.135) only, NOT on BL (100.123.153.75).",
+                    "operator_command": f"ssh super@{vm_host} 'cat {vm_paths[0]}'",
+                    "agent_approval_command": "box approvals request-key <node> --reason '<reason>'"
+                }, indent=2))
+                return
+            print("\n" + c_bold("=== VM PASSKEY FETCH PROBE ===") + "\n")
+            print(f"  {c_bold('Target VM Host')}   : {c_cyan(vm_host)}")
+            print(f"  {c_bold('Target Paths')}     : {vm_paths[0]} (fallback: {vm_paths[1]})")
+            print(f"  {c_bold('Probe Result')}     : {c_yellow('Direct SSH access unavailable (' + (fetch_err or 'auth required') + ')')}\n")
+            print(c_bold("  Location Reality (VM vs BL):"))
+            print(f"  • {c_yellow('VM (' + vm_host + ')')} : Key material lives in a {c_bold('single text file (.txt)')} on the VM.")
+            print(f"  • {c_red('BL (100.123.153.75)')}  : {c_bold('NO passkey / secret material exists on the dedicated BL.')}\n")
+            print(f"  {c_bold('Console PIN')}        : {c_green('3128')} (sets session cookie: {c_dim('ops_session')} at {c_cyan('https://box.muse-dev.online/')})\n")
+            print(c_bold("  Operator Access:"))
+            print(f"    ssh super@{vm_host} 'cat {vm_paths[0]}'\n")
+            print(c_bold("  Agent UX / Approval Request:"))
+            print(f"    Agents must not hunt BL. If passkey authorization is needed, request it via:")
+            print(f"    {c_cyan('box approvals request-key <node> --reason \"<reason>\"')}\n")
+            return
+
+    if is_json:
+        print(json.dumps({
+            "ok": True,
+            "surface": "https://box.muse-dev.online/",
+            "operator_pin": "3128",
+            "session_cookie": "ops_session",
+            "key_location": {
+                "host": "Google Cloud VM (34.139.37.135)",
+                "canonical_path": "/srv/box/passkey.txt",
+                "fallback_path": "/etc/netvm/passkey.txt",
+                "note": "Stored in a single text file (.txt) on the VM — NOT on the dedicated BL compute node (100.123.153.75)",
+                "credstore_path": "/etc/netvm/meta-credentials/store.age",
+                "credstore_key": "/etc/netvm/meta-credentials/.age-key"
+            },
+            "operator_fetch_cmd": "ssh super@34.139.37.135 'cat /srv/box/passkey.txt'",
+            "agent_approval_protocol": {
+                "rule": "Agents do not hold administrative passkeys or credentials directly. Secrets never reside on bl.",
+                "request_flow": "1. Agent signals APPROVAL_REQUEST: key=<reason> or runs 'box approvals request-key <node>'.\n2. Operator verifies request.\n3. Operator retrieves key/PIN from VM single text file (.txt) or submits OTP.\n4. Operator approves via 'box approvals allow <node>'.",
+                "request_command": "box approvals request-key <node> --reason '<reason>'",
+                "sidechats": ["646 tasks", "pip tasks", "#jobs", "heartbeat"]
+            }
+        }, indent=2))
+        return
+
+    print("\n" + c_bold("=== OPERATOR PASSKEY & KEY MATERIAL ARCHITECTURE ===") + "\n")
+    print(f"  {c_bold('Box Front-Door Console')}: {c_cyan('https://box.muse-dev.online/')}")
+    print(f"  {c_bold('Operator PIN / Passkey')}: {c_green('3128')} (sets session cookie: {c_dim('ops_session')})\n")
+    
+    print(c_bold("  Location Reality (VM vs BL):"))
+    print(f"  • {c_yellow('VM (34.139.37.135)')}      : Key material lives in a {c_bold('single text file (.txt)')} on the VM.")
+    print(f"                            - Canonical path: {c_cyan('/srv/box/passkey.txt')}")
+    print(f"                            - Fallback path : {c_cyan('/etc/netvm/passkey.txt')}")
+    print(f"                            - Fetch command : {c_dim('box passkey fetch')}")
+    print(f"  • {c_red('BL (100.123.153.75)')}      : {c_bold('NO passkey / secret material exists on the dedicated BL.')}")
+    print(f"  • Credstore on VM       : /etc/netvm/meta-credentials/store.age (age-encrypted, root 600)")
+    print(f"  • Age Key on VM         : /etc/netvm/meta-credentials/.age-key\n")
+
+    print(c_bold("  Agent UX & Operator Approval Flow:"))
+    print(f"  1. {c_cyan('Never hunt on bl')}        : Agents must never attempt to grep or locate passkeys on bl.")
+    print(f"  2. {c_cyan('Signal Approval')}         : If an agent requires key access or operator privilege:")
+    print(f"                            - Run: {c_yellow('box approvals request-key <node> --reason \"<reason>\"')}")
+    print(f"                            - Or emit {c_yellow('APPROVAL_NEEDED: <details>')} in task sidechat")
+    print(f"                            - Or exit with code {c_yellow('2')} (per INFRA.md convention)")
+    print(f"  3. {c_cyan('Operator Action')}         : Operator consults the single .txt file on the VM to authenticate")
+    print(f"                            and approves via {c_dim('box approvals allow <node>')}.")
+    print(f"  4. {c_cyan('Target Sidechats')}        : Use dedicated sidechats ({c_dim('646 tasks, pip tasks, #jobs, heartbeat')}).\n")
+
+
+
+def _lookup_unreads(args):
+    print("\n" + c_bold("=== FLEET UNREAD / ACTIVITY STATUS ===") + "\n")
+    headers = ["NODE", "UNREAD COUNT", "ACTIVE PAGE / TITLE", "LAST SEEN / THREAD"]
+    rows = []
+    data = collect_fleet_data()
+    for item in data:
+        n = item["node"]
+        title = item.get("title", "")
+        unread = "0"
+        if "(1)" in title or "(2)" in title or "(3)" in title:
+            m = re.search(r"\((\d+)\)", title)
+            unread = c_yellow(m.group(1)) if m else c_yellow("1+")
+        elif item.get("approval_pending"):
+            unread = c_yellow("APPROVAL")
+        
+        thread_info = "-"
+        if "thread/" in item.get("url", ""):
+            thread_info = item["url"].split("thread/")[-1][:12]
+        elif item.get("url") == "https://muse.ai/":
+            thread_info = "home"
+
+        rows.append([c_bold(n), unread, title[:45], thread_info])
+    print_table(headers, rows)
+    print("\n" + c_dim("  To view unread messages: box thread view <node> <thread>") + "\n")
+
+
+def cmd_lookup(args):
+    """Seamless unified lookup across nodes, threads, unreads, approvals, and keys."""
+    lookup_args = getattr(args, "lookup_args", []) or []
+    if "--json" in lookup_args:
+        setattr(args, "json", True)
+    sub = getattr(args, "target", None)
+    if not sub or sub in ("all", "summary"):
+        print("\n" + c_bold("=== SEAMLESS FLEET LOOKUP SUMMARY ===") + c_dim(f" ({datetime.now().strftime('%H:%M:%S')} local)\n"))
+        # 1. Fleet status
+        cmd_fleet_status(args)
+        # 2. Approvals summary
+        try:
+            import approvals
+            app_list = approvals.check_fleet_approvals(VALID_NODES)
+            pending = [a for a in app_list if a.get("status") == "PENDING"]
+            if pending:
+                print(c_yellow(f"  ⚠ {len(pending)} pending approval(s): {', '.join(a['node'] for a in pending)} (run: box approvals)"))
+            else:
+                print(c_green("  ✔ Approval Queues: All clean"))
+        except Exception:
+            pass
+        # 3. Key note
+        print(c_dim("  ℹ Passkey: Stored in single .txt on VM (34.139.37.135), not bl. (run: box passkey)"))
+        print()
+        return
+
+    if sub in ("key", "passkey", "auth"):
+        cmd_passkey_info(args)
+    elif sub in ("fleet", "nodes"):
+        cmd_fleet_status(args)
+    elif sub in ("threads", "sidechats"):
+        cmd_thread_list(args)
+    elif sub in ("approvals", "approval"):
+        cmd_approvals(args)
+    elif sub in ("docs", "doc", "surfaces", "sentence", "regex", "parse"):
+        extra = getattr(args, "lookup_args", []) or []
+        sub_args = [sub] if sub not in ("docs", "doc") else []
+        cmd = [sys.executable, str(BIN_DIR / "docs-lookup.py")] + sub_args + extra
+        res = subprocess.run(cmd)
+        sys.exit(res.returncode)
+    else:
+        print(f"Unknown lookup target '{sub}'. Choose from: fleet, threads, unread, approvals, key, docs", file=sys.stderr)
+
+
+def cmd_docs_dispatch(args):
+    """Bridge 'box docs' and 'super docs' directly to bin/docs-lookup.py."""
+    d_args = getattr(args, "docs_args", []) or []
+    cmd = [sys.executable, str(BIN_DIR / "docs-lookup.py")] + d_args
+    res = subprocess.run(cmd)
+    sys.exit(res.returncode)
+
+
 def cmd_tmux_dispatch(args):
     """Bridge 'box tmux' commands directly to bin/muse-tmux.py."""
     tmux_bin = str(BIN_DIR / "muse-tmux.py")
-    subcmd = args.tmux_action or "list"
-    cmd = [sys.executable, tmux_bin, subcmd] + (args.tmux_args or [])
+    t_args = getattr(args, "tmux_args", []) or []
+    if not t_args:
+        t_args = ["list"]
+    cmd = [sys.executable, tmux_bin] + t_args
     res = subprocess.run(cmd)
     sys.exit(res.returncode)
 
+
+def cmd_muse_dispatch(args):
+    """Bridge 'box muse' commands to muse-cli-node or interactive REPL / multi-node lookups."""
+    m_args = getattr(args, "muse_args", []) or []
+    if not m_args:
+        cmd = [str(BIN_DIR / "muse"), "--help"]
+        res = subprocess.run(cmd)
+        sys.exit(res.returncode)
+
+    first = m_args[0]
+
+    # If first is 'tmux', dispatch to tmux
+    if first == "tmux":
+        cmd = [sys.executable, str(BIN_DIR / "muse-tmux.py")] + m_args[1:]
+        res = subprocess.run(cmd)
+        sys.exit(res.returncode)
+
+    # If first is a cross-fleet query
+    if first in ("status", "fleet"):
+        cmd_fleet_status(args)
+        return
+
+    if first in ("passkey", "key"):
+        cmd_passkey_info(args)
+        return
+
+    if first in ("lookup", "lookups"):
+        setattr(args, "target", m_args[1] if len(m_args) > 1 else None)
+        cmd_lookup(args)
+        return
+
+    if first in ("threads", "sidechats"):
+        cmd_thread_list(args)
+        return
+
+    if first in ("unread", "unreads"):
+        _lookup_unreads(args)
+        return
+
+    # If first is a valid node
+    if first in VALID_NODES:
+        node = first
+        subargs = m_args[1:]
+        if not subargs:
+            subargs = ["status"]
+        if subargs[0] == "chat":
+            cmd = [sys.executable, str(BIN_DIR / "muse-chat-repl.py"), node] + subargs[1:]
+            res = subprocess.run(cmd)
+            sys.exit(res.returncode)
+        cmd = [str(BIN_DIR / "muse-cli-node"), node] + subargs
+        res = subprocess.run(cmd)
+        sys.exit(res.returncode)
+
+    # Fallback to bin/muse wrapper
+    cmd = [str(BIN_DIR / "muse")] + m_args
+    res = subprocess.run(cmd)
+    sys.exit(res.returncode)
+
+
 def build_parser():
     common = argparse.ArgumentParser(add_help=False)
     common.add_argument("--json", action="store_true", help="Output machine-readable JSON")
@@ -3775,22 +4216,33 @@ def build_parser():
 
         p_app_check = app_sub.add_parser("check", parents=[common], help="Check fleet approval states")
         p_app_check.add_argument("--node", choices=VALID_NODES, default=None, help="Filter by node")
+        p_app_check.add_argument("-v", "--verbose", action="store_true", help="Show detailed task prompts, thread URLs, and card text")
 
         p_app_list = app_sub.add_parser("list", parents=[common], help="Alias for 'check'")
         p_app_list.add_argument("--node", choices=VALID_NODES, default=None, help="Filter by node")
+        p_app_list.add_argument("-v", "--verbose", action="store_true", help="Show detailed task prompts, thread URLs, and card text")
+
+        p_app_inspect = app_sub.add_parser("inspect", parents=[common], help="Inspect detailed approval and input-wait status on a node")
+        p_app_inspect.add_argument("node", choices=VALID_NODES, help="Target node to inspect")
 
         p_app_allow = app_sub.add_parser("allow", parents=[common], help="Approve pending browser request")
         p_app_allow.add_argument("node", choices=VALID_NODES, help="Target node to approve")
         p_app_allow.add_argument("--always", action="store_true", help="Click 'Always allow this site' instead of 'Allow once'")
         p_app_allow.add_argument("--force", action="store_true", help="Force approval even if target is untrusted")
+        p_app_allow.add_argument("--message", default=None, help="Optional message/credential to deliver to the waiting agent")
+        p_app_allow.add_argument("--allow-main-chat", action="store_true", help="Allow reply into Main Chat if agent is waiting there")
 
         p_app_approve = app_sub.add_parser("approve", parents=[common], help="Alias for 'allow'")
         p_app_approve.add_argument("node", choices=VALID_NODES, help="Target node to approve")
         p_app_approve.add_argument("--always", action="store_true", help="Click 'Always allow this site' instead of 'Allow once'")
         p_app_approve.add_argument("--force", action="store_true", help="Force approval even if target is untrusted")
+        p_app_approve.add_argument("--message", default=None, help="Optional message/credential to deliver to the waiting agent")
+        p_app_approve.add_argument("--allow-main-chat", action="store_true", help="Allow reply into Main Chat if agent is waiting there")
 
         p_app_deny = app_sub.add_parser("deny", parents=[common], help="Deny pending browser request")
         p_app_deny.add_argument("node", choices=VALID_NODES, help="Target node to deny")
+        p_app_deny.add_argument("--message", default=None, help="Optional message to deliver to the waiting agent")
+        p_app_deny.add_argument("--allow-main-chat", action="store_true", help="Allow reply into Main Chat if agent is waiting there")
 
         p_app_auto = app_sub.add_parser("auto", parents=[common], help="Auto-approve all trusted requests across fleet")
         p_app_auto.add_argument("--node", choices=VALID_NODES, default=None, help="Target node (or all nodes)")
@@ -3800,6 +4252,23 @@ def build_parser():
         p_app_watch.add_argument("--auto", action="store_true", help="Automatically approve trusted requests as they appear")
         p_app_watch.add_argument("--node", choices=VALID_NODES, default=None, help="Filter by node")
 
+        p_app_reply = app_sub.add_parser("reply", parents=[common], help="Reply to a waiting agent task/prompt in its active thread")
+        p_app_reply.add_argument("node", choices=VALID_NODES, help="Target node to reply to")
+        p_app_reply.add_argument("message", help="Message or answer to dispatch")
+        p_app_reply.add_argument("--allow-main-chat", action="store_true", help="Explicit override if the active thread is Main Chat")
+
+        p_app_dismiss = app_sub.add_parser("dismiss", parents=[common], help="Dismiss any open task dialog/popup on a node")
+        p_app_dismiss.add_argument("node", choices=VALID_NODES, help="Target node to dismiss dialog on")
+
+        p_app_clear = app_sub.add_parser("clear", parents=[common], help="Clear and dismiss pending input waits on a node or all nodes")
+        p_app_clear.add_argument("node", nargs="?", choices=VALID_NODES, default=None, help="Target node (or omit for all nodes)")
+
+        p_app_clear_all = app_sub.add_parser("clear-all", parents=[common], help="Clear and dismiss all pending input waits across fleet")
+
+        p_app_req_key = app_sub.add_parser("request-key", parents=[common], help="Request operator passkey/key approval for an agent")
+        p_app_req_key.add_argument("node", choices=VALID_NODES, help="Target node requesting key")
+        p_app_req_key.add_argument("--reason", default="Passkey authentication required", help="Reason for key request")
+
     # Domain: DM
     p_dm = subparsers.add_parser("dm", parents=[common], help="Inter-agent DMs, work orders ([WO]), acks, live log tail")
     dm_sub = p_dm.add_subparsers(dest="action")
@@ -3878,8 +4347,8 @@ def build_parser():
     p_thread = subparsers.add_parser("thread", parents=[common], help="Inspect agent main chats, sidechats, and scrollbacks")
     thread_sub = p_thread.add_subparsers(dest="action")
 
-    p_thread_list = thread_sub.add_parser("list", parents=[common], help="List active threads for an agent")
-    p_thread_list.add_argument("agent", choices=VALID_NODES, help="Agent node to inspect")
+    p_thread_list = thread_sub.add_parser("list", parents=[common], help="List active threads for an agent or all fleet sidechats")
+    p_thread_list.add_argument("agent", nargs="?", default=None, choices=VALID_NODES + [None], help="Agent node to inspect (default: all registered fleet sidechats)")
 
     p_thread_view = thread_sub.add_parser("view", parents=[common], help="View recent messages from an agent's thread")
     p_thread_view.add_argument("agent", choices=VALID_NODES, help="Agent node to inspect")
@@ -4255,17 +4724,74 @@ def build_parser():
 
     # Domain: TMUX (Headless background tmux sessions with automatic logging)
     p_tmux = subparsers.add_parser("tmux", parents=[common], help="Manage headless background tmux sessions on /tmp/tmux-muse.sock")
-    p_tmux.add_argument("tmux_action", nargs="?", default="list", choices=["list", "ls", "new", "send", "send-keys", "capture", "cap", "tail", "kill", "prune", "attach"], help="tmux action (default: list)")
     p_tmux.add_argument("tmux_args", nargs=argparse.REMAINDER, help="Arguments passed directly to muse-tmux.py")
 
     # Domain: muse (fast headless gateway via muse-cli-node with isolated per-node Cloudflare WARP egress)
     p_muse = subparsers.add_parser("muse", parents=[common], help="Direct headless gateway client (muse-cli-node)")
-    p_muse.add_argument("node", choices=VALID_NODES, help="Target agent node")
-    p_muse.add_argument("muse_args", nargs=argparse.REMAINDER, help="Arguments passed directly to muse-cli-node")
+    p_muse.add_argument("muse_args", nargs=argparse.REMAINDER, help="Arguments passed to muse-cli-node or fleet lookups")
+
+    # Domain: LOOKUP (Unified seamless lookups across nodes, threads, unread, approvals, key, docs)
+    p_lookup = subparsers.add_parser("lookup", aliases=["lookups"], parents=[common], help="Seamless fleet lookups (summary, fleet, threads, unread, approvals, key, docs)")
+    p_lookup.add_argument("target", nargs="?", default="summary", choices=["summary", "fleet", "nodes", "threads", "sidechats", "unread", "unreads", "approvals", "key", "passkey", "docs", "doc", "surfaces", "sentence", "regex", "parse"], help="Lookup target")
+    p_lookup.add_argument("lookup_args", nargs=argparse.REMAINDER, help="Additional arguments passed to lookup engine")
+
+    # Domain: PASSKEY (Operator passkey location & agent approval protocol)
+    p_passkey = subparsers.add_parser("passkey", aliases=["key"], parents=[common], help="Display operator passkey location (VM-only), PIN, & agent approval protocol")
+    p_passkey.add_argument("action", nargs="?", default="show", choices=["show", "fetch", "get"], help="Passkey action: 'show' details or 'fetch' from VM")
+
+    # Domain: DOCS (Internal agent lookups, surfaces, sentence grammar, and regex engine)
+    p_docs = subparsers.add_parser("docs", aliases=["doc"], parents=[common], help="Agent lookups, surfaces for box.muse-dev.online, sentence grammar & regex")
+    p_docs.add_argument("docs_args", nargs=argparse.REMAINDER, help="Arguments passed directly to docs-lookup.py")
 
     return parser
 
 def main():
+    if len(sys.argv) > 1:
+        if sys.argv[1] == "tmux":
+            cmd = [sys.executable, str(BIN_DIR / "muse-tmux.py")] + (sys.argv[2:] or ["list"])
+            res = subprocess.run(cmd)
+            sys.exit(res.returncode)
+        elif sys.argv[1] in ("docs", "doc"):
+            cmd = [sys.executable, str(BIN_DIR / "docs-lookup.py")] + sys.argv[2:]
+            res = subprocess.run(cmd)
+            sys.exit(res.returncode)
+        elif sys.argv[1] == "muse":
+            m_args = sys.argv[2:]
+            if not m_args:
+                cmd = [str(BIN_DIR / "muse"), "--help"]
+                res = subprocess.run(cmd)
+                sys.exit(res.returncode)
+            if m_args[0] == "tmux":
+                cmd = [sys.executable, str(BIN_DIR / "muse-tmux.py")] + (m_args[1:] or ["list"])
+                res = subprocess.run(cmd)
+                sys.exit(res.returncode)
+            if m_args[0] in ("status", "fleet"):
+                sys.argv = [sys.argv[0], "fleet", "status"]
+            elif m_args[0] in ("passkey", "key"):
+                sys.argv = [sys.argv[0], "passkey"] + m_args[1:]
+            elif m_args[0] in ("lookup", "lookups"):
+                sys.argv = [sys.argv[0], "lookup"] + m_args[1:]
+            elif m_args[0] in ("threads", "sidechats"):
+                sys.argv = [sys.argv[0], "thread", "list"] + m_args[1:]
+            elif m_args[0] in ("unread", "unreads"):
+                sys.argv = [sys.argv[0], "lookup", "unread"]
+            elif m_args[0] in VALID_NODES:
+                node = m_args[0]
+                sub = m_args[1:]
+                if not sub:
+                    sub = ["status"]
+                if sub[0] == "chat":
+                    cmd = [sys.executable, str(BIN_DIR / "muse-chat-repl.py"), node] + sub[1:]
+                    res = subprocess.run(cmd)
+                    sys.exit(res.returncode)
+                cmd = [str(BIN_DIR / "muse-cli-node"), node] + sub
+                res = subprocess.run(cmd)
+                sys.exit(res.returncode)
+            else:
+                cmd = [str(BIN_DIR / "muse")] + m_args
+                res = subprocess.run(cmd)
+                sys.exit(res.returncode)
+
     parser = build_parser()
     if len(sys.argv) == 1:
         # Default behavior with no arguments: show fleet status
@@ -4489,12 +5015,16 @@ def main():
         if args.domain == "subagent":
             args.action = "subagent"
         cmd_deploy(args)
+    elif args.domain in ("lookup", "lookups"):
+        cmd_lookup(args)
+    elif args.domain in ("passkey", "key"):
+        cmd_passkey_info(args)
     elif args.domain == "tmux":
         cmd_tmux_dispatch(args)
     elif args.domain == "muse":
-        cmd = [str(BIN_DIR / "muse-cli-node"), args.node] + (args.muse_args or [])
-        res = subprocess.run(cmd)
-        sys.exit(res.returncode)
+        cmd_muse_dispatch(args)
+    elif args.domain in ("docs", "doc"):
+        cmd_docs_dispatch(args)
     else:
         parser.print_help()
 

bin/swarm-worker-supervise.sh

@@ -13,6 +13,7 @@
 set -euo pipefail
 
 SESSION="swarm-worker"
+SOCKET_PATH="/tmp/tmux-muse.sock"
 LOG_DIR="/home/super/Projects/NetVM/logs"
 LOG_FILE="${LOG_DIR}/swarm-worker.log"
 
@@ -24,7 +25,7 @@ WORKER_CMD="python3 /home/super/Projects/NetVM/bin/swarm_worker/daemon.py"
 WORKER_MATCH='swarm_worker/daemon.[p]y'
 
 session_exists() {
-    tmux has-session -t "$SESSION" 2>/dev/null
+    tmux -S "$SOCKET_PATH" has-session -t "$SESSION" 2>/dev/null
 }
 
 worker_alive() {
@@ -34,21 +35,30 @@ worker_alive() {
 do_start() {
     mkdir -p "$LOG_DIR"
     if session_exists; then
-        echo "already running (tmux session $SESSION exists)"
+        echo "already running (tmux session $SESSION exists on $SOCKET_PATH)"
         return 0
     fi
-    tmux new-session -d -s "$SESSION" "$WORKER_CMD >>\"$LOG_FILE\" 2>&1"
+    tmux -S "$SOCKET_PATH" new-session -d -s "$SESSION" "$WORKER_CMD >>\"$LOG_FILE\" 2>&1"
     sleep 1
     if worker_alive; then
-        echo "started tmux session $SESSION (logging to $LOG_FILE)"
+        echo "started tmux session $SESSION on $SOCKET_PATH (logging to $LOG_FILE)"
     else
-        echo "WARNING: session $SESSION created but worker process not detected yet"
+        echo "WARNING: session $SESSION created on $SOCKET_PATH but worker process not detected yet"
     fi
 }
 
 do_stop() {
+    local stopped=0
     if session_exists; then
-        tmux kill-session -t "$SESSION"
+        tmux -S "$SOCKET_PATH" kill-session -t "$SESSION" 2>/dev/null || true
+        stopped=1
+    fi
+    # Also clean up accidental session on default socket if present
+    if tmux has-session -t "$SESSION" 2>/dev/null; then
+        tmux kill-session -t "$SESSION" 2>/dev/null || true
+        stopped=1
+    fi
+    if [ "$stopped" -eq 1 ]; then
         echo "stopped tmux session $SESSION"
     else
         echo "not running (no tmux session $SESSION)"

bin/swarm_worker/daemon.py

@@ -23,15 +23,33 @@ import sys
 import time
 import traceback
 
-# Sibling modules live in the same directory.
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+# Sibling modules live in swarm_worker, common utilities live in bin/.
+_SWARM_DIR = os.path.dirname(os.path.abspath(__file__))
+_BIN_DIR = os.path.dirname(_SWARM_DIR)
+sys.path.insert(0, _SWARM_DIR)
+sys.path.insert(0, _BIN_DIR)
 
 from poller import find_pending_slots
-from executor import execute_task
-from reporter import post_result
+from executor import execute_task, _looks_like_shell
+from reporter import post_result, attach_slot
+
+# Fast gateway integration
+try:
+    import muse_hybrid
+    HAS_MUSE_HYBRID = True
+except ImportError:
+    HAS_MUSE_HYBRID = False
+
+# Prompt envelope formatting
+try:
+    import prompt_envelope
+    HAS_PROMPT_ENVELOPE = True
+except ImportError:
+    HAS_PROMPT_ENVELOPE = False
 
 POLL_INTERVAL = 60          # seconds between poll cycles
 STALE_MINUTES = 5           # slots older than this with no attach are workable
+WORKER_POOL = ["dev", "def", "muse"]
 
 # === SAFETY SWITCH ===
 # True  -> observe only: log what WOULD be done, execute/post nothing.
@@ -46,19 +64,78 @@ logging.basicConfig(
 log = logging.getLogger("swarm-worker")
 
 
+def _select_worker(preferred=None):
+    if preferred and HAS_MUSE_HYBRID and muse_hybrid.is_node_configured(preferred):
+        return preferred
+    for candidate in WORKER_POOL:
+        if HAS_MUSE_HYBRID and muse_hybrid.is_node_configured(candidate):
+            return candidate
+    return preferred or "dev"
+
+
 def process_slot(slot):
     """Execute one slot and report the result. Returns True on full success."""
     swarm_id = slot.get("swarm_id")
     slot_index = slot.get("slot_index")
     task_text = slot.get("task_text") or ""
+    agent_label = slot.get("agent_label")
+    sidechat_id = slot.get("sidechat_id")
     tag = "%s/%s" % (swarm_id, slot_index)
 
     if DRY_RUN:
         log.info("[dry-run] would execute slot %s (agent=%s, task %.80r)",
-                 tag, slot.get("agent_label"), task_text)
+                 tag, agent_label, task_text)
         return True
 
-    log.info("executing slot %s (agent=%s)", tag, slot.get("agent_label"))
+    # If the task is NOT a shell command, dispatch it to an ephemeral Muse subagent.
+    is_shell = _looks_like_shell(task_text)
+    if not is_shell and HAS_MUSE_HYBRID:
+        worker_agent = _select_worker(agent_label)
+        log.info("dispatching subagent slot %s to %s", tag, worker_agent)
+        try:
+            # 1. Start an ephemeral subagent session
+            title = f"sw-{swarm_id[:16]}-s{slot_index}"
+            sess, err = muse_hybrid.start_session(worker_agent, title=title)
+            if err or not sess or not sess.get("session_id"):
+                log.error("failed to start subagent session for %s on %s: %s", tag, worker_agent, err)
+                return False
+
+            sub_sid = sess["session_id"]
+            log.info("subagent session %s created for slot %s on %s", sub_sid, tag, worker_agent)
+
+            # 2. Attach/claim the slot in box state with subagent session_id
+            attached = attach_slot(swarm_id, slot_index, worker_agent, session_id=sub_sid)
+            if not attached:
+                log.warning("failed to attach slot %s to %s; proceeding with dispatch", tag, worker_agent)
+
+            # 3. Format prompt with authentic Operator Directive and RESULT expectation
+            if HAS_PROMPT_ENVELOPE and hasattr(prompt_envelope, "wrap_subagent_task"):
+                prompt_body = prompt_envelope.wrap_subagent_task(tag, task_text)
+            else:
+                prompt_body = (
+                    f"Operator assignment for swarm slot {tag}:\n\n"
+                    f"Task:\n{task_text.strip()}\n\n"
+                    f"Instructions:\n"
+                    f"1. Carry out this task directly using your available tools.\n"
+                    f"2. When finished, conclude your final response with your verdict line:\n"
+                    f"[RESULT {tag}] OK: <one-line summary of actions and outcome>\n"
+                    f"(or [RESULT {tag}] FAIL: <reason> if the task could not be completed)\n"
+                )
+
+            # 4. Asynchronously send message to subagent session
+            res, send_err = muse_hybrid.send_message(worker_agent, prompt_body, thread_id=sub_sid, wait=0)
+            if send_err:
+                log.error("failed to send task to subagent %s on %s: %s", sub_sid, worker_agent, send_err)
+                return False
+
+            log.info("slot %s successfully dispatched to subagent %s (harvester will harvest)", tag, sub_sid)
+            return True
+        except Exception:
+            log.error("subagent dispatch crashed on slot %s:\n%s", tag, traceback.format_exc())
+            return False
+
+    # Otherwise fallback to sandboxed host execution
+    log.info("executing slot %s in sandbox (agent=%s)", tag, agent_label)
     try:
         result = execute_task(task_text)
     except Exception:

bin/swarm_worker/executor.py

@@ -77,11 +77,19 @@ def _looks_like_shell(task_text):
         return False
     if _PROSE_RE.search(t):
         return False
-    # Must start with a word-ish token (not a quote or sentence).
+    # Must start with a plausible executable command or path
     first = t.split()[0] if t.split() else ""
     if not re.match(r"^[a-zA-Z0-9_.\-/]+$", first):
         return False
-    return True
+    # If it's a relative/absolute path, verify it exists and is executable
+    if "/" in first:
+        return os.path.isfile(first) and os.access(first, os.X_OK)
+    # If it's a bare command name, it must exist in standard system bin paths
+    for p in ("/bin", "/usr/bin", "/usr/local/bin"):
+        candidate = os.path.join(p, first)
+        if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+            return True
+    return False
 
 
 def _refused(task_text):

bin/swarm_worker/poller.py

@@ -97,7 +97,8 @@ def find_pending_slots(stale_minutes=STALE_MINUTES):
         return found
     swarms = data.get("swarms", []) if isinstance(data, dict) else []
     for summary in swarms:
-        if (summary.get("status") or "").lower() != "running":
+        summary_status = (summary.get("status") or "").lower()
+        if summary_status not in ("running", "pending"):
             continue
         swarm_id = summary.get("swarm_id")
         if not swarm_id:
@@ -110,6 +111,8 @@ def find_pending_slots(stale_minutes=STALE_MINUTES):
         created_ts = swarm.get("created_ts") or summary.get("created_ts")
         for slot in swarm.get("slots", []):
             status = (slot.get("status") or "").lower()
+            if status in ("done", "failed", "killed"):
+                continue
             result = slot.get("result")
             agent = slot.get("agent_id")
             pending = (status == "pending") or (not agent)

bin/swarm_worker/reporter.py

@@ -97,6 +97,60 @@ def post_result(swarm_id, slot_index, result_dict, dry_run=False):
                   swarm_id, slot_index, str(resp)[:500])
         return False
 
+def attach_slot(swarm_id, slot_index, agent_id, session_id=None, dry_run=False):
+    """Claim/attach a swarm slot to an agent in box state.
+
+    Args:
+        swarm_id: e.g. "sw-20261005-151307-a222"
+        slot_index: int slot number
+        agent_id: agent string, e.g. "dev"
+        session_id: optional subagent session ID string
+        dry_run: if True, simulate attach without changing state.
+
+    Returns:
+        True on success, False on failure.
+    """
+    if dry_run:
+        print("DRY-RUN would run: %s swarm-attach %s %s %s %s"
+              % (BOX_CTL, swarm_id, slot_index, agent_id, session_id or ""))
+        return True
+
+    cmd = [
+        sys.executable, BOX_CTL, "swarm-attach",
+        str(swarm_id), str(slot_index), str(agent_id),
+    ]
+    if session_id:
+        cmd.append(str(session_id))
+
+    try:
+        proc = subprocess.run(
+            cmd,
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            timeout=30,
+        )
+    except Exception as e:
+        log.error("attach_slot %s/%s failed to invoke box-ctl: %s",
+                  swarm_id, slot_index, e)
+        return False
+
+    if proc.returncode != 0:
+        err = proc.stderr.decode("utf-8", "replace")[:500]
+        log.error("attach_slot %s/%s box-ctl rc=%d: %s",
+                  swarm_id, slot_index, proc.returncode, err)
+        return False
+
+    try:
+        resp = json.loads(proc.stdout.decode("utf-8", "replace"))
+    except ValueError:
+        log.error("attach_slot %s/%s: box-ctl returned non-JSON output",
+                  swarm_id, slot_index)
+        return False
+
+    if not resp.get("ok"):
+        log.error("attach_slot %s/%s: box-ctl ok=false: %s",
+                  swarm_id, slot_index, str(resp)[:500])
+        return False
+
     return True
 
 

docs/AGENT-TOOLING.md

@@ -51,7 +51,15 @@ box dm send --agent 646 --to pip --target 646-pip "Hey Pip, start-page onboardin
 You can directly interact with the headless Muse gateway inside your isolated network namespace using either `muse` or `box muse`:
 
 ```bash
-# Using native muse wrapper (interactive prompt & account enforcement)
+# Global lookups & fleet status (no account required)
+muse status                          # Complete fleet overview & node vitality
+muse threads                         # List registered threads and sidechats across fleet
+muse unread                          # View unread counts across all agents
+muse lookup                          # Unified lookup (summary of fleet, approvals, unread)
+muse passkey (or muse key)           # Passkey reference (VM .txt location) & agent approval flow
+muse tmux list                       # List shared tmux sessions across fleet
+
+# Using native muse wrapper for per-account actions:
 muse -a <account> chat               # Interactive conversational REPL with thread selection
 muse -a <account> chat --thread <id> # Direct conversational REPL in specified thread
 muse -a <account> status
@@ -59,19 +67,67 @@ muse -a <account> threads
 muse -a <account> history --thread <thread_uuid> --limit 10
 muse -a <account> send --thread <thread_uuid> "<message>"
 
-# If invoked without -a/--account, it displays valid accounts and usage instructions:
+# If invoked without arguments, it displays available accounts and commands:
 muse
 
 # Alternatively via box CLI:
-box muse <self> threads
+box muse status                      # Cross-fleet status
+box muse <self> status               # Agent-specific status
+box muse <self> threads              # Active sessions for agent
 box muse <self> history --thread <thread_uuid> --limit 10
 box muse <self> unread
+box muse <self> chat                 # Launch interactive chat REPL
 box muse <self> session-start --title "<title>"
 box muse <self> send --thread <thread_uuid> "<message>"
+box muse tmux list                   # Direct bridge to muse-tmux manager
 ```
 
 ---
 
+## 3.1. Unified & Seamless Lookups (`box lookup` & `box thread`)
+
+For fast inspection of fleet state without hunting across multiple tools:
+
+```bash
+# Unified lookup summary (fleet health, pending approvals, key reference)
+box lookup
+box lookup fleet                     # Node health, CDP status, active pages
+box lookup threads                   # List all registered fleet sidechats and mapped UUIDs
+box lookup threads <agent>           # List active threads for a specific agent
+box lookup unread                    # Unread indicators and active tabs across fleet
+box lookup approvals                 # Check if any agent is held on browser approvals
+box lookup key (or box passkey)      # Operator passkey & approval protocol
+
+# Seamless thread inspection:
+box thread list                      # List all registered fleet sidechats across agents
+box thread list <agent>              # List active sessions for an agent
+box thread view <agent> <uuid>       # View recent thread messages (supports short UUID prefix)
+box thread view <agent> "<alias>"    # View thread by registered alias (e.g. "646 tasks", "heartbeat")
+```
+
+---
+
+## 3.2. Operator Passkey & Key Material Architecture
+
+> **Crucial Reality**: Key material and administrative passkeys live in a **single file (`.txt`) on the Google Cloud VM (`34.139.37.135`)**. **NO passkeys or secret stores exist on the dedicated BL (`100.123.153.75`)**.
+
+### Why This Matters:
+- Front-door console access (`https://box.muse-dev.online/`) is secured by operator PIN `3128` (or the passkey in the VM text file).
+- Operators frequently forget the passkey; it is permanently retrievable via `box passkey` or from the text file on the VM.
+- **Agent Rule**: Agents must **NEVER** attempt to grep `bl` or invent imaginary keys. Secrets never reside on the compute node.
+
+### How Agents Get Key Access / Operator Approval:
+When an agent or automated task requires elevated privileges, key material, or operator confirmation:
+1. **Signal the Request**:
+   - In automated scripts: exit with code `2` (the standard `APPROVAL_NEEDED` convention per `INFRA.md`).
+   - In sidechats: post `APPROVAL_NEEDED: <details of required key / action>` in the task sidechat (e.g. `646 tasks`, `pip tasks`, `#jobs`, `heartbeat`).
+2. **Operator Verification**:
+   - The human operator reviews the request in the sidechat or via `box approvals check`.
+   - If approved, the operator retrieves the key from the single `.txt` file on the VM (or submits transient OTP via `box cred submit-otp`).
+3. **Execution**:
+   - The operator authorizes the flow or enters the credential transiently. No raw credentials are saved to `bl` or git.
+
+
 ## 4. Shared & Hybrid Tmux Tooling (`muse tmux`, `box tmux`, & `[TOOL tmux.*]`)
 
 Agents and operators can spawn background sessions and send keystrokes to long-running tasks across three execution tiers:
@@ -147,3 +203,26 @@ When jobs are dispatched to agents via `bin/job-dispatch.py`, they are wrapped i
 2. **Sub-Agent Prioritization**: Break down complex diagnostic or verification jobs by delegating sub-tasks to dedicated subagent threads.
 3. **Execution Reality**: Work is only real if tool calls ran. Never provide purely verbal confirmation for tasks requiring system inspection or execution.
 4. **Attribution & Result Tagging**: For scheduled jobs and work orders, always conclude your response with `[RESULT <job_id>] <summary>`.
+
+---
+
+## 7. Internal Documentation & Agent Lookups (`box docs` & `docs_internal/`)
+
+Agents have access to a structured internal `.md` and `.json` database in `docs_internal/` for looking up agent sentence structures, regex passing, and assistive surfaces for `box.muse-dev.online`:
+
+```bash
+# Query surfaces, DOM selectors, and REST endpoints for box.muse-dev.online
+box docs surfaces jobs
+box docs surfaces dms
+
+# Inspect agent sentence structures and conversational contracts
+box docs sentence work_order
+box docs sentence result
+
+# Test strings or evaluate against canonical regex patterns
+box docs regex result --test "[RESULT 7fce46e0] OK 14 endpoints verified"
+box docs parse "[WO:7fce46e0] [from super] Audit exec — Check stats"
+
+# Full-text search across documentation database
+box docs search "work order"
+```

docs/BOX-WEB-SURFACE-GUIDE.md

@@ -39,12 +39,15 @@ flowchart LR
 ### Trust & Identity Principles
 1. **Host as Source of Truth (`bl`)**: All mutating state, cryptographic keys, job definitions, variables, and browser CDP relays reside on `bl`. The VM does not persist authoritative fleet state.
 2. **On-Demand Tailnet SSH Bridge**: The VM board service bridges into allowlisted verbs in [`bin/box-ctl.py`](file:///home/super/Projects/NetVM/bin/box-ctl.py) using an on-demand Tailnet SSH connection (`super@100.123.153.75`).
-3. **Session Authentication & Brute-Force Defense**:
+3. **Session Authentication & Passkey Location Reality**:
    - Operator console access is unlocked via `POST /api/ops/login` with operator PIN `3128`, establishing cookie `ops_session`.
+   - **Crucial Passkey Reality**: In reality, the passkey material is stored in a **single file (`.txt`) on the Google Cloud VM (`34.139.37.135`)**, **NOT on the dedicated BL (`100.123.153.75`)**.
+   - Operators frequently forget this passkey; retrieve anytime via `box passkey` or from the text file on the VM.
    - Successful PIN logins bypass the rate limiter. Failed attempts are constrained by a 10-attempt sliding window.
-4. **Agent-Scoped Privacy Tiers**:
+4. **Agent-Scoped Privacy Tiers & Approval Flow**:
    - `ops_session` grants unredacted administrative visibility across all DMs, logs, loops, and actions.
    - Unauthenticated or agent-scoped queries receive redacted logs filtered to their respective identities.
+   - **Agent Key Requests**: Agents do not hold administrative keys directly and must never hunt on `bl` for secrets. When elevated key access or approval is required, agents signal `APPROVAL_NEEDED: <details>` in task sidechats (or exit code 2). Operators verify and fulfill from the single `.txt` file on the VM.
 
 ---
 

docs/INBAND-MESSAGING-SPEC.md

@@ -0,0 +1,58 @@
+# In-Band Internal Messaging: Directives, Parsing, Exec Surface
+
+> **Status: Final** — accepted by the owner on 2026-10-06
+> ("i accept the scope contract, mark it Final").
+
+> **Box is the main surface.** All operator work goes through Box
+> (box.muse-dev.online). The web UI, `box` CLI, and agents share the same
+> API endpoints. No UI-only powers.
+
+## Background (researched facts, not decisions)
+
+- Agents receive timer/job DMs wrapped by `bin/prompt_envelope.py` (`wrap()`),
+  currently advertising `[TOOL swarm.spawn]`, `[TOOL cron.create]`,(tmux
+  worker pointer, `[RESULT]` verdict rule.
+- Agents reply with in-band directives. `bin/response-harvester.py`
+  `parse_tool_calls()` extracts `[TOOL op {json}]` / `[EXEC …]`, fenced
+  ```box|tool|exec blocks, and curl-to-/exec payloads; each call runs through
+  the `exec-constrained` HTTPS daemon (`op` allowlist + per-op
+  validate/build) and the result is posted back into the originating thread.
+- Implemented this session, uncommitted: balanced-brace JSON scanning (no
+  more first-`]` truncation), `[DM {…}]` shorthand for `dm.send`, new
+  `box.exec` (read-only box-ctl actions) and `tools.list` (dynamic op
+  discovery) ops, native aliases (`dm`, `box`, `tools`, …), expanded
+  envelope/tool-hint verb lists, `tests/test_tool_calls.py` (38 tests).
+- Related specs: `docs/DM_SPEC.md` (WO + logging layer), `docs/DM_SPEC.md`
+  (control plane), `docs/JOB-SPEC.md` (scheduler/distributor),
+  `CHAT_POLICY.md` (sidechat-first).
+
+## Scope contract (accepted)
+
+- Artifact boundary: this record covers directive syntax/parsing
+  (`[TOOL]`/`[EXEC]`/`[DM]`, fenced blocks), the exec op surface
+  (`box.exec`, `tools.list`, native aliases), and timer-message/envelope
+  content. Out of scope: gateway/browser transport, swarm worker
+  reliability and the failed-slot backlog, new `box` CLI verbs,
+  `CHAT_POLICY.md` changes.
+- Done means: D1–D5 settled in writing below; owner explicitly accepts
+  this record (Draft → Final). Nothing else is a completion dependency.
+- Deferred stages (each needs its own interview): swarm reliability
+  target, `box` CLI inspection verbs for in-band traffic.
+
+## Decisions
+
+| # | Decision | Status |
+|---|----------|--------|
+| D1 | Scope boundary = A (directives + exec surface + envelope; transport, swarm reliability, new CLI verbs, chat policy out) | settled |
+| D2 | `box.exec` = read-only v1 (19 no-arg + 8 one-arg reads); side-effecting box actions stay out, dedicated ops cover writes | settled |
+| D3 | `[DM …]` = strict JSON-only; bare forms without a JSON object are silently ignored | settled |
+| D4 | Broken-JSON directives are skipped silently (no reply, no record) | settled |
+| D5 | `tools.list` returns every op with its `side_effecting` flag; enforcement stays in per-op validation + identity permissions | settled |
+
+## Risks / validation (to fill as decisions settle)
+
+- Full suite: 235–244 tests (count varies run to run), 3–4 failures, all
+  in `test_approvals` / `test_copy_actions`, which import only
+  `approvals` / `gravity` / `muse_tui` — none of this record's modules.
+  Pre-existing/environmental, unrelated to the directive changes.
+  Focused suites green (38 tool-call + 32 docs/prompts tests).

docs/JOB-SPEC.md

@@ -225,6 +225,86 @@ spam if a job misfires in a loop.
 - DMs are logged (dm-log.jsonl) for audit
 - Side chats are per-job, not shared across trust boundaries
 
+## Completion Enforcement
+
+Sending a job DM does not complete work. Four mechanisms close the loop on bl:
+
+### 1. `on_no_result` fallback (server-side guarantee)
+
+A job may declare a fallback effect that runs when its followup reaches
+terminal expiry with no agent result (`bin/followup-sweeper.py`):
+
+```json
+"on_no_result": {"op": "swarm.spawn", "args": {"count": 2, "task": "...", "label": "..."}}
+"on_no_result": {"job": "<another-job-name>"}
+```
+
+- `op` form: validated + built through the `exec-constrained` op registry
+  (same validators the daemon uses), then executed as a subprocess.
+- `job` form: dispatches the named job via `job-dispatch.py` with
+  `CHAIN_PREV_*` timeout context.
+- Outcomes log as `fallback_executed` / `fallback_failed` in `job-log.jsonl`
+  and stamp `rec["fallback"]` on the followup record. Failures never break
+  the sweep. Jobs without the key behave exactly as before.
+- Firing paths (either; never both): the sweeper terminal branch
+  (`nudges_sent >= nudges_allowed`, expired) and `gravity.py:remediate_breaks`
+  (same terminal condition, runs on `loop-remediator.timer` ~every 15m).
+  `fallback_due()` dedupes: fires once per record, retries a failed attempt
+  after 1h. Gravity also revives the local sweep loop (it previously had no
+  `__main__`, so the timer was a no-op) with a 300s re-arm budget (was 10s,
+  which strangled every sweep mid-first-send — median nudge send is ~10s).
+- Split-brain note: the VM board sweeper (`box-request-sweeper.timer`) sends
+  the live `[NUDGE <id>]` DMs from remote `dm_followup` requests; the local
+  sweeper sends `[nudge N/M]` from `followups.json`. Both fire per deadline
+  until a reply resolves both sides. Accept the duplicate nudge as the cost
+  of a guaranteed local path; cross-system dedup is future work.
+- Seeded on: `autonomy-pulse-646`, `autonomy-pulse-pip`, `autonomy-pulse-opm`
+  (each spawns 2 standing-work subagents if the agent naps through the pulse).
+- Race note: set the job's followup timeout longer than the expected work
+  time, or a slow-but-working agent can double-fire alongside the fallback.
+
+### 2. NACK for directive-less replies (existing, sharpened)
+
+`response-harvester.py:maybe_nudge_untagged_sidechat` already rejects
+conversational replies in job-backed threads (1-turn strict nudge, then a
+5-minute escalation timer to opm; tracked in
+`conversation-nudge-tracker.json`). Two refinements:
+
+- Acted-variant: when the agent emitted directives but never closed with
+  `[RESULT]`, the nudge acknowledges the action and demands the close
+  instead of crying "commentary rejected".
+- Emit-model wording: envelope (`prompt_envelope._response_rule`), tool
+  hint, and strict nudge now state plainly that agents EMIT `[TOOL]` /
+  `[DM]` lines verbatim and the Box runtime on bl executes them — this
+  works from containers with no box CLI or tmux socket. (Root cause of the
+  2026-10-06 zero-`tool_exec` stretch: agents believed they had to execute
+  tools locally and declined for lack of a "container equivalent".)
+
+### 3. Proof-of-result followups
+
+A success `[RESULT]` with no checkable artifact (swarm/timer IDs, UUIDs,
+paths, `n/m` completion counts — see `result_has_evidence`) triggers a
+one-shot `followup.create` (+30m, same thread) asking for the evidence, and
+logs `proof_requested`. One per (thread, job). Failures and declines skip
+proof (they already chain via `on_failure`).
+
+### 4. Completion auditor (15-minute timer)
+
+`bin/completion-audit.py` via `systemd/completion-audit.timer`
+(`OnCalendar=*:4/15`, installed to `/etc/systemd/system`):
+
+- Computes the funnel per job family over `--hours` (default 24) from
+  `job-log.jsonl`: sent / dispatched / `tool_exec` / results, plus
+  `fallback_*`, `proof_requested`, and `job_failed` counts.
+- Adds point-in-time swarm slot drain (flags running slots idle >90m) and
+  followup backlog (pending / overdue / escalated).
+- Writes `logs/completion-audit-<ts>.json` + `logs/completion-audit-latest.json`.
+- Posts the digest to `opm` / `heartbeat` only when DEGRADED
+  (silent families, failures, tool errors, stale slots, overdue/escalated
+  followups); when green, posts a heartbeat at most every 6h
+  (`logs/completion-audit-state.json`). Silent-when-healthy otherwise.
+- Read-only except the digest DM and its own log/state files.
+
 ## Future Expansions
 
 1. **Conditional jobs**: Run Job B only if Job A succeeds with specific output

docs_internal

@@ -0,0 +1 @@
+lookup_internal

jobs/autonomy-pulse-646.json

@@ -18,5 +18,13 @@
     "route": "autonomy-pulse"
   },
   "chain_next": null,
-  "on_failure": "alert"
+  "on_failure": "alert",
+  "on_no_result": {
+    "op": "swarm.spawn",
+    "args": {
+      "count": 2,
+      "task": "Standing pulse work for 646 (autonomy-pulse-646): execute your scope standing work: verify timers, check swarm results, act or close; report per-slot verdicts.",
+      "label": "autonomy-pulse-646-fallback"
+    }
+  }
 }

jobs/autonomy-pulse-opm.json

@@ -18,5 +18,13 @@
     "route": "autonomy-pulse"
   },
   "chain_next": null,
-  "on_failure": "alert"
+  "on_failure": "alert",
+  "on_no_result": {
+    "op": "swarm.spawn",
+    "args": {
+      "count": 2,
+      "task": "Standing pulse work for opm (autonomy-pulse-opm): execute your scope standing work: verify timers, check swarm results, act or close; report per-slot verdicts.",
+      "label": "autonomy-pulse-opm-fallback"
+    }
+  }
 }

jobs/autonomy-pulse-pip.json

@@ -18,5 +18,13 @@
     "route": "autonomy-pulse"
   },
   "chain_next": null,
-  "on_failure": "alert"
+  "on_failure": "alert",
+  "on_no_result": {
+    "op": "swarm.spawn",
+    "args": {
+      "count": 2,
+      "task": "Standing pulse work for pip (autonomy-pulse-pip): execute your scope standing work: verify timers, check swarm results, act or close; report per-slot verdicts.",
+      "label": "autonomy-pulse-pip-fallback"
+    }
+  }
 }

jobs/exec-sigkill-investigation-20261005.json

@@ -0,0 +1,14 @@
+{
+  "agent": "646",
+  "chain_next": null,
+  "description": "Investigate exec-constrained.py SIGKILL/wedged-process cluster on bl (2026-10-05 03:37-05:40 UTC). Read-only forensics first.",
+  "dm_target": "646 tasks",
+  "name": "exec-sigkill-investigation-20261005",
+  "on_failure": "alert",
+  "prompt_template": "Investigate the exec-constrained.py SIGKILL/wedged-process cluster on bl (2026-10-05 03:37-05:40 UTC).\n\nJob ID: {job_id}\nTime: {datetime}\n\nBACKGROUND: Read-only deployment reconnaissance found 18 exec-server restarts on 2026-10-05. Notable: SIGKILLs at 03:37, 03:39, 03:49 UTC; wedged-process (Failed to kill) events at 04:19 and 05:40 UTC. The 07:50/09:50/12:51 UTC 502 windows had NO restarts (those were head-of-line blocking, now fixed by ThreadingHTTPServer deploy).\n\nSCOPE (read-only first):\n1. Pull journalctl for exec-constrained.service around 03:30-06:00 UTC 2026-10-05.\n2. Check for OOM-killer activity (dmesg, journal) around 03:37/03:39/03:49.\n3. Identify what sent SIGKILL (manual? OOM? systemd?).\n4. Investigate the 04:19/05:40 wedged processes: what child subprocesses were unkillable? Check for zombie/defunct processes.\n5. Review memory/cgroup pressure history if available.\n6. Correlate with the 18 restarts: are they all explained?\n\nDO NOT restart services or modify config. Read-only forensics.\n\nReport back with: (a) root cause hypothesis for SIGKILLs, (b) root cause for wedged processes, (c) recommended fix (needs user approval before any change).",
+  "sidechat": {
+    "create": false
+  },
+  "timeout": 600,
+  "schedule": "30 3 1 * *"
+}

jobs/test-tmux-wo.json

@@ -0,0 +1,15 @@
+{
+  "name": "test-tmux-wo",
+  "description": "Verification job: execute background tmux task and report output",
+  "agent": "pip",
+  "schedule": null,
+  "timeout": 180,
+  "prompt_template": "Execute a verification command in your background tmux session and capture the output.\n1. Run [TOOL tmux.new {\"session\": \"worker-pip-test\", \"command\": \"bash\"}]\n2. Run [TOOL tmux.send {\"session\": \"worker-pip-test\", \"keys\": \"hostname && whoami && echo TMUX_VERIFIED_SUCCESS\"}]\n3. Capture the output with [TOOL tmux.capture {\"session\": \"worker-pip-test\", \"lines\": 10}]\n4. When done, reply with [RESULT {job_id}] OK: tmux test verified.",
+  "sidechat": {
+    "create": true,
+    "reuse_key": "test-tmux-wo",
+    "name_template": "test-tmux-wo-{date}"
+  },
+  "chain_next": null,
+  "on_failure": "alert"
+}

lookup_internal/CLI-TOOLS.md

@@ -0,0 +1,47 @@
+# CLI Tools Reference & Grammar
+
+> **Box is the main surface.** All operator work goes through Box (`box.muse-dev.online`). The web UI, `box` CLI, and agents share the same API endpoints. No UI-only powers.
+
+NetVM provides a unified command line toolchain anchored by `box` and `super` (`/usr/local/bin/box` and `/home/super/.local/bin/super`), both pointing to the off-board orchestrator script [`bin/super-cli.py`](file:///home/super/Projects/NetVM/bin/super-cli.py).
+
+---
+
+## 1. Quick Command Summary
+
+```text
+box <domain> <action> [options]
+super <domain> <action> [options]
+```
+
+| Domain | Description | Common Invocation |
+|---|---|---|
+| `fleet` | Node status, CDP ports, watch | `box fleet status` |
+| `approvals` | Browser approvals & input waits | `box approvals check -v` |
+| `dm` | Work orders, Acks, log tail | `box dm send --agent 646 --to pip ...` |
+| `thread` | Thread listings & message inspection | `box thread list` |
+| `job` | Timers, scheduled triggers, logs | `box job run box-http-health` |
+| `loop` | Loop health, open loops, nudges | `box loop status` |
+| `vars` | Dynamic runtime variables | `box vars set max_nudge_count 3` |
+| `tmux` | Headless background tmux workers | `box tmux new worker1 --command "bash"` |
+| `deploy` | Spawn subagents & pipelines | `box deploy subagent --agent 646 ...` |
+| `docs` | Internal docs, regexes, & surfaces | `box docs surfaces dashboard` |
+
+---
+
+## 2. Using `box docs` for Real-Time Lookup
+
+Autonomous agents should query the `docs` domain whenever they need schema verification, regex passing, or surface selector lookups:
+
+```bash
+# Search across all internal databases
+box docs search "work order"
+
+# Inspect assistive surfaces on box.muse-dev.online
+box docs surfaces jobs
+
+# Look up sentence grammar specifications
+box docs sentence result
+
+# Test an utterance through the regex engine
+box docs parse "[RESULT 7fce46e0] OK Finished task"
+```

lookup_internal/FLEET-NODES.md

@@ -0,0 +1,34 @@
+# Fleet Topology & Agent Identities
+
+> **Box is the main surface.** All operator work goes through Box (`box.muse-dev.online`). The web UI, `box` CLI, and agents share the same API endpoints. No UI-only powers.
+
+NetVM manages four primary autonomous browser agents and two development/staging nodes isolated inside Linux network namespaces (`warp-*`) on compute host `bl` (`100.123.153.75`).
+
+---
+
+## 1. Node Inventory
+
+| Node | NetNS | CDP Port | Peer IP | Default Sidechat | Primary Role |
+|---|---|---|---|---|---|
+| `muse` | `warp-muse` | 9410 | 10.201.35.2 | `muse tasks` | General assistant, UI testing |
+| `pip` | `warp-pip` | 9411 | 10.201.35.3 | `646-pip-coord` | Pipeline execution & driver |
+| `646` | `warp-646` | 9412 | 10.201.35.4 | `646 tasks` | Operator-646, code & bridge |
+| `opm` | `warp-opm` | 9413 | 10.201.35.5 | `heartbeat` | Operator-main supervisor |
+| `dev` | `warp-dev` | 9414 | 10.201.35.6 | `dev tasks` | Development sandbox |
+| `def` | `warp-def` | 9415 | 10.201.35.7 | `default` | Fallback routing node |
+
+---
+
+## 2. Headless Gateway & CLI Access
+
+Each node has its own isolated Cloudflare WARP egress. To interact with a node:
+```bash
+# Gateway REPL
+muse -a 646 chat
+
+# Direct headless status
+box muse 646 status
+
+# Bounce node
+box fleet restart 646
+```

lookup_internal/README.md

@@ -0,0 +1,77 @@
+# Internal Agent & Operator Documentation (`docs_internal/`)
+
+> **Box is the main surface.** All operator work goes through Box (`box.muse-dev.online`). The web UI, `box` CLI, and agents share the same API endpoints, protocol grammar, and lookup structures.
+
+Welcome to `docs_internal/`. This directory serves as a dual Markdown (`.md`) and structured JSON (`.json`) lookup database for autonomous agents, background daemons, and off-board operators across NetVM.
+
+---
+
+## 1. Directory Structure
+
+```text
+docs_internal/
+├── manifest.json              # Master database manifest and collections schema
+├── README.md                  # This file
+├── sentence_structure.json    # Agent sentence structures, protocols, and grammar
+├── SENTENCE-STRUCTURE.md      # Comprehensive guide to agent communication protocols
+├── regex_patterns.json        # Master regular expression database with test fixtures
+├── REGEX-PATTERNS.md          # Guide to regex parsing, capture groups, and testing
+├── assistive_surfaces.json    # UI tabs, DOM selectors, data-testids & REST endpoints for box.muse-dev.online
+├── SURFACES.md                # Guide to interacting with box.muse-dev.online
+├── cli_tools.json             # CLI command catalog and syntax database
+├── CLI-TOOLS.md               # Guide to super, box, and muse CLI tools
+├── fleet_nodes.json           # Fleet node topology, namespaces, and ports
+└── FLEET-NODES.md             # Guide to fleet agents and network topology
+```
+
+---
+
+## 2. Using the CLI Lookup Engine
+
+You can query this database directly from the shell using `super docs` or `box docs`:
+
+### 2.1 Full-Text Search
+```bash
+box docs search "work order"
+box docs search "cdp"
+```
+
+### 2.2 Inspect Assistive Surfaces for `box.muse-dev.online`
+```bash
+# List all surfaces and views
+box docs surfaces
+
+# Inspect a specific surface (e.g. jobs, dms, loops, dashboard)
+box docs surfaces jobs
+box docs surfaces dms
+```
+
+### 2.3 Inspect Agent Sentence Grammar & Protocols
+```bash
+# List all sentence structures
+box docs sentence
+
+# View full structure specification
+box docs sentence work_order
+box docs sentence result
+```
+
+### 2.4 Regex Passing & Testing
+```bash
+# List available regex patterns
+box docs regex
+
+# Test a string against a specific pattern
+box docs regex work_order --test "[WO:7fce46e0] [from super] Audit — Check status"
+
+# Parse an agent sentence through all patterns to extract captured tokens
+box docs parse "[RESULT 7fce46e0] OK Verified 14 endpoints"
+```
+
+### 2.5 Machine-Readable JSON Output
+Add `--json` to any command for structured JSON output:
+```bash
+box docs sentence work_order --json
+box docs surfaces dashboard --json
+box docs parse "[CLAIM 7fce46e0]" --json
+```

lookup_internal/REGEX-PATTERNS.md

@@ -0,0 +1,87 @@
+# Master Regex Patterns & Passing Reference
+
+> **Box is the main surface.** All operator work goes through Box (`box.muse-dev.online`). The web UI, `box` CLI, and agents share the same API endpoints and parsing patterns.
+
+This document serves as the canonical reference for regular expressions used across NetVM's orchestrators, harvesters, loop state managers, and agent message parsers.
+
+---
+
+## 1. Quick Pattern Directory
+
+| Pattern Key | Purpose | Match Example |
+|---|---|---|
+| `work_order` | Parses `[WO:<id>] [from <sender>] ...` | `[WO:7fce46e0] [from super] Audit — Check stats` |
+| `ack` | Parses `[ACK:<id>] [from <sender>]` | `[ACK:7fce46e0] [from 646]` |
+| `verb` | Matches `[ACK\|CLAIM\|RESULT\|DECLINE\|NO-ACTION <id>]` | `[CLAIM 7fce46e0]` |
+| `result` | Parses `[RESULT <id>] <status> <summary>` | `[RESULT 7fce46e0] OK 14 endpoints healthy` |
+| `tool_call` | Parses inline `[TOOL <op> <args>]` | `[TOOL followup.create {"in_m": 5}]` |
+| `job_tag` | Matches `[JOB <id>]` | `[JOB ml-646-20261005]` |
+| `nudge` | Parses followup SLA nudges | `[NUDGE 7fce46e0] [nudge 1/3] Deadline 19:45: ...` |
+| `fleet_alert` | Parses alert broadcasts | `[fleet-alert] CRITICAL: VM unreachable x2` |
+| `uuid` | RFC 4122 UUID v4 detector | `dc6d72ca-4b02-4217-bf41-7dbca19c5c24` |
+| `short_hex` | 6-12 character hex IDs | `7fce46e0` |
+| `subagent_update`| Subagent status notices | `[SUBAGENT-UPDATE] Subagent 'audit' (4a2b8e) ...` |
+| `swarm_slot` | Swarm worker slot targets | `[JOB swarm-99a/1]` |
+
+---
+
+## 2. Core Patterns & Named Capture Groups
+
+### 2.1 Work Order Pattern (`work_order`)
+```python
+r"^\[WO:(?P<wo_id>[a-f0-9-]+)\]\s+\[from\s+(?P<sender>[a-zA-Z0-9_-]+)\]\s+(?P<title>[^—\n]+?)\s*—\s*(?P<body>.+)$"
+```
+* **Flags**: `re.MULTILINE`, `re.DOTALL`
+* **Groups**:
+  - `wo_id`: The unique tracking ID.
+  - `sender`: Originating identity (`super`, `646`, `pip`, etc.).
+  - `title`: Short task name preceding the em-dash (`—`).
+  - `body`: Instruction payload following the em-dash.
+
+### 2.2 Standard Verbs (`verb`)
+```python
+r"\[(?P<verb>ACK|CLAIM|RESULT|DECLINE|NO-ACTION)\s+(?P<job_id>[A-Za-z0-9_/-]+)\]"
+```
+* **Groups**:
+  - `verb`: One of the 5 canonical lifecycle verbs.
+  - `job_id`: Target job, work order, or swarm slot.
+
+### 2.3 Task Result (`result`)
+```python
+r"\[RESULT\s+(?P<job_id>[A-Za-z0-9_/-]+)\]\s*(?P<status>OK|FAIL|DECLINE|SUCCESS|ERROR)?\s*(?P<summary>.*?)(?=\[RESULT\s|\Z)"
+```
+* **Flags**: `re.DOTALL`
+* **Groups**:
+  - `job_id`: Target task ID.
+  - `status`: Optional explicit status keyword.
+  - `summary`: Detailed response text.
+
+### 2.4 In-Band Tool Directives (`tool_call`)
+```python
+r"\[(?P<engine>TOOL|EXEC)\s+(?P<op>[a-zA-Z0-9_.-]+)\s+(?P<args>\{.*?\})\]"
+```
+* **Groups**:
+  - `engine`: `TOOL` or `EXEC`.
+  - `op`: Method name (e.g. `followup.create`, `health.check`).
+  - `args`: Embedded JSON argument payload.
+
+---
+
+## 3. CLI Pattern Passing & Validation
+
+The unified CLI allows testing strings directly against these patterns:
+
+```bash
+# Test a string against a specific pattern
+super docs regex result --test "[RESULT 7fce46e0] OK Task complete"
+box docs regex work_order --test "[WO:8a12bc44] [from super] Audit — verify 200"
+
+# Parse an agent utterance through ALL registered patterns
+super docs parse "[RESULT 7fce46e0] OK Verified 14 endpoints"
+box docs parse "[TOOL followup.create {\"in_m\": 5, \"prompt\": \"check\"}]"
+
+# View raw JSON pattern definition
+super docs get regex_patterns work_order --json
+```
+
+When run with `--json`, the parser outputs structured dictionary mappings suitable for programmatic ingestion by subagents.

lookup_internal/SENTENCE-STRUCTURE.md

@@ -0,0 +1,153 @@
+# Agent Sentence Structures & Conversational Grammar
+
+> **Box is the main surface.** All operator work goes through Box (`box.muse-dev.online`). The web UI, `box` CLI, and agents share the same API endpoints and protocol grammar.
+
+This master document defines the standardized sentence structures, bracketed markers, conversational contracts, and grammar rules governing autonomous agent communication across NetVM and Box.
+
+---
+
+## 1. Overview & Protocol Lifecycle
+
+Agent communication relies on structured, machine-parsable prefixes embedded into natural language sentences. This allows human operators and autonomous language models to read the same stream while automation engines (`response-harvester.py`, `followup-sweeper.py`, `self_main_loop.py`) extract telemetry, update loop states, and trigger downstream events.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Dispatched: [WO:id] Work Order
+    Dispatched --> Acknowledged: [ACK:id]
+    Dispatched --> Claimed: [CLAIM id]
+    Acknowledged --> Claimed: [CLAIM id]
+    Claimed --> Running: [TOOL op args] / execution
+    Running --> Resolved: [RESULT id] OK <summary>
+    Claimed --> Declined: [DECLINE id] <reason>
+    Claimed --> NoAction: [NO-ACTION id] <reason>
+    Running --> Nudged: [NUDGE id] (SLA warning)
+    Nudged --> Resolved: [RESULT id]
+    Resolved --> [*]
+    Declined --> [*]
+    NoAction --> [*]
+```
+
+---
+
+## 2. Core Sentence Structures
+
+### 2.1 Work Order (`[WO:<id>]`)
+* **Purpose**: Tasking dispatched across operators or from the off-board orchestrator. Creates a tracked loop with an SLA deadline.
+* **Format**:
+  ```text
+  [WO:<dm_id>] [from <sender>] <title> — <body>
+  ```
+* **Required Components**:
+  - `dm_id`: Unique identifier (hex string, e.g. `7fce46e0`).
+  - `sender`: Author identity (`super`, `646`, `pip`, `opm`, `muse`).
+  - `title`: Short task description.
+  - `body`: Detailed instructions and acceptance criteria.
+* **Example**:
+  ```text
+  [WO:8a12bc44] [from super] Audit exec.muse-dev.online endpoints — Verify that allowlisted ops respond with 200 OK.
+  ```
+
+### 2.2 Acknowledgement (`[ACK:<id>]`)
+* **Purpose**: Confirms delivery and receipt of a Work Order or message, preventing re-dispatch.
+* **Format**:
+  ```text
+  [ACK:<dm_id>] [from <sender>]
+  ```
+* **Example**:
+  ```text
+  [ACK:8a12bc44] [from 646]
+  ```
+
+### 2.3 Task Claim (`[CLAIM <id>]`)
+* **Purpose**: Declares exclusive ownership of a task or swarm worker slot.
+* **Format**:
+  ```text
+  [CLAIM <job_id>]
+  ```
+* **Example**:
+  ```text
+  [CLAIM 8a12bc44]
+  ```
+
+### 2.4 Task Completion Result (`[RESULT <id>]`)
+* **Purpose**: Delivers final evidence or outcome, closing the active loop and recording success/failure in `job-log.jsonl`.
+* **Format**:
+  ```text
+  [RESULT <job_id>] <status> <summary>
+  ```
+  *(Status options: `OK`, `FAIL`, `SUCCESS`, `DECLINE`)*
+* **Example**:
+  ```text
+  [RESULT 8a12bc44] OK Verified 14 endpoints; all return valid 200 responses with expected schemas.
+  ```
+
+### 2.5 Task Decline & No-Action
+* **Decline Format**:
+  ```text
+  [DECLINE <job_id>] <reason>
+  ```
+* **No-Action Format**:
+  ```text
+  [NO-ACTION <job_id>] <reason>
+  ```
+
+### 2.6 In-Band Tool Calls (`[TOOL <op> <args>]`)
+* **Purpose**: Inline directive parsed by `response-harvester.py` and executed directly on the host or inside a node netns.
+* **Format**:
+  ```text
+  [TOOL <op> <args_json>]
+  ```
+* **Example**:
+  ```text
+  [TOOL followup.create {"in_m": 5, "prompt": "Re-check Cloudflare WARP proxy status"}]
+  ```
+
+### 2.7 Loop Followup Nudge (`[NUDGE <id>]`)
+* **Purpose**: Automated escalation sent to an agent when an SLA deadline is approaching or breached.
+* **Format**:
+  ```text
+  [NUDGE <loop_id>] [nudge <count>/<max_nudges>] Deadline <time_utc>: <prompt>
+  ```
+* **Example**:
+  ```text
+  [NUDGE 8a12bc44] [nudge 1/3] Deadline 19:45 UTC: Please confirm status of exec audit.
+  ```
+
+### 2.8 Fleet Alert (`[fleet-alert]`)
+* **Purpose**: Infrastructure health broadcasts dispatched to `#lobby` and `#jobs`.
+* **Format**:
+  ```text
+  [fleet-alert] <SEVERITY>: <message>
+  ```
+* **Example**:
+  ```text
+  [fleet-alert] CRITICAL: VM unreachable x2 on port 22
+  ```
+
+---
+
+## 3. Conversational Contract Footer
+
+When issuing prompts to model instances, orchestrators append the **Contract Footer**:
+```text
+Reply: [ACK id] seen | [CLAIM id] mine | [RESULT id] done | [DECLINE id] | [NO-ACTION id].
+```
+This forces strict conformance to parsable reply tokens.
+
+---
+
+## 4. Querying from CLI
+
+Agents and operators can look up these sentence structures using the unified CLI:
+```bash
+# View list of all structures
+super docs sentence
+box docs sentence
+
+# View specific structure specification
+super docs sentence work_order
+super docs sentence result
+
+# Validate or parse an utterance
+super docs parse "[WO:7fce46e0] [from super] Run audit — check endpoints"
+```

lookup_internal/SURFACES.md

@@ -0,0 +1,106 @@
+# Assistive Surfaces Reference — box.muse-dev.online
+
+> **Box is the main surface.** All operator work goes through Box (`box.muse-dev.online`). The web UI, `box` CLI, and agents share the same API endpoints. No UI-only powers.
+
+This guide provides autonomous agents and operators with detailed maps of the visual DOM, interactive controls, API backends, and assistive interaction recipes for `box.muse-dev.online`.
+
+---
+
+## 1. Global Layout & Authentication
+
+* **Production URL**: `https://box.muse-dev.online/`
+* **Google Cloud VM**: `34.139.37.135`
+* **Authoritative Compute Host**: `bl` (`100.123.153.75`)
+* **Operator PIN**: `3128` (establishes `ops_session` cookie via `POST /api/ops/login`)
+* **Agent Authentication**: Header `Authorization: Bearer <operator-token>` or SSH-keygen signature.
+
+### Layout Wireframe
+```text
++----------------------------------------------------------------------------------+
+| [BOX] Fleet Console   box.muse-dev.online  ● [pulse]    [</> API]  [◐ theme]    |
++----------------------------------------------------------------------------------+
+| [Fleet Pulse]   [DMs & Work Orders (N)]   [Timers & Jobs]   [Loop & Strategy (N)]|
++----------------------------------------------------------------------------------+
+|                                                                                  |
+|  <Active Pane Content: Cards / Tables / Modals / Curldrawer>                     |
+|                                                                                  |
++----------------------------------------------------------------------------------+
+```
+
+---
+
+## 2. Views & Navigation Map
+
+### 2.1 Fleet Pulse (`#tab-dashboard`)
+* **Tab Button**: `.tab-btn[data-tab="dashboard"]`
+* **Key Selectors**:
+  - `#fleet-grid`: Grid container for node cards.
+  - `.node-card`: Card representing an agent (`muse`, `pip`, `646`, `opm`).
+  - `.node-badge`: Status badge (`UP`, `WARN`, `DOWN`).
+  - `#fleet-pulse`: Global heartbeat animation.
+* **REST API**:
+  - `GET /api/box/fleet`
+  - Returns array of `{ node, netns, peer_ip, cdp_port, proc_alive, title, latency_ms }`.
+
+### 2.2 DMs & Work Orders (`#tab-dms`)
+* **Tab Button**: `.tab-btn[data-tab="dms"]`
+* **Key Selectors**:
+  - `#dms-table`: Log stream table.
+  - `#dms-tbody`: Dynamic row container.
+  - `#filter-search`: Search text filter input.
+  - `.filter-agent-chip`: Filter by agent (`all`, `super`, `muse`, `pip`, `646`, `opm`).
+  - `.filter-kind-chip`: Filter by message kind (`all`, `workorder`, `ack`, `chat`).
+* **REST API**:
+  - `GET /api/box/dm/log?limit=50`
+  - `POST /api/box/dm/send`
+
+### 2.3 Timers & Scheduled Jobs (`#tab-jobs`)
+* **Tab Button**: `.tab-btn[data-tab="jobs"]`
+* **Key Selectors**:
+  - `#jobs-table`: Systemd user timer table.
+  - `.btn-trigger`: Direct hot-trigger button (`▶ Run`).
+  - `.badge-active`: Active/inactive state indicator.
+* **REST API**:
+  - `GET /api/box/timers`
+  - `POST /api/box/jobs/{name}/trigger` (Returns `202 Accepted` immediately).
+
+### 2.4 Loop & Strategy Matrix (`#tab-loops`)
+* **Tab Button**: `.tab-btn[data-tab="loops"]`
+* **Key Selectors**:
+  - `#loop-health-badge`: Real-time health verdict (e.g. `HEALTHY (89%)`).
+  - `#loops-grid`: Cards for active open loops and deadlines.
+  - `#strat-table`: Table of strategy escalation rules.
+  - `#vars-table`: Interactive table of runtime variables with inline edit buttons.
+* **REST API**:
+  - `GET /api/box/loop/health`
+  - `GET /api/box/loop/status`
+  - `GET /api/box/loop/vars`
+  - `POST /api/box/loop/vars`
+
+---
+
+## 3. Assistive Interaction Recipes
+
+### Recipe A: Querying Fleet Health via CLI
+```bash
+# High level overview
+box fleet
+# Directly query docs database for surface selectors
+box docs surfaces dashboard
+```
+
+### Recipe B: Hot-Triggering a Job via API
+```bash
+# Asynchronously trigger job
+curl -sk -X POST https://box.muse-dev.online/api/box/jobs/box-http-health/trigger
+```
+
+### Recipe C: Resolving a Blocked Modal Dialog
+```bash
+# Check if any agent is held on an approval dialog
+box approvals check
+# Inspect dialog details
+box approvals inspect pip
+# Approve request
+box approvals allow pip
+```

lookup_internal/assistive_surfaces.json

@@ -0,0 +1,173 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Assistive Surfaces for box.muse-dev.online",
+  "version": "1.0.0",
+  "host": "box.muse-dev.online",
+  "origin_vm": "34.139.37.135",
+  "compute_host": "bl (100.123.153.75)",
+  "auth": {
+    "pin": "3128",
+    "cookie_name": "ops_session",
+    "login_endpoint": "/api/ops/login",
+    "agent_header": "Authorization: Bearer <operator-token>",
+    "signature_mechanism": "SSH-keygen -Y sign via Tailnet identity"
+  },
+  "views": {
+    "dashboard": {
+      "name": "Fleet Pulse",
+      "tab_id": "dashboard",
+      "dom_tab_selector": ".tab-btn[data-tab=\"dashboard\"]",
+      "dom_pane_selector": "#tab-dashboard",
+      "key_elements": {
+        "grid": "#fleet-grid",
+        "pulse_indicator": "#fleet-pulse",
+        "node_card": ".node-card",
+        "node_badge": ".node-badge",
+        "active_page_title": ".page-title-preview"
+      },
+      "api_endpoints": [
+        {
+          "method": "GET",
+          "path": "/api/box/fleet",
+          "description": "Real-time CDP latency, node status, current page titles, and queue depths across all nodes.",
+          "curl_example": "curl -sk https://box.muse-dev.online/api/box/fleet"
+        }
+      ],
+      "assistive_recipe": "To check fleet health, read /api/box/fleet or inspect #fleet-grid node cards. Green indicator denotes CDP responsive <100ms."
+    },
+    "dms": {
+      "name": "DMs & Work Orders",
+      "tab_id": "dms",
+      "dom_tab_selector": ".tab-btn[data-tab=\"dms\"]",
+      "dom_pane_selector": "#tab-dms",
+      "key_elements": {
+        "table": "#dms-table",
+        "tbody": "#dms-tbody",
+        "search_input": "#filter-search",
+        "agent_filter_chips": ".filter-agent-chip",
+        "kind_filter_chips": ".filter-kind-chip",
+        "count_badge": "#dms-count-badge"
+      },
+      "api_endpoints": [
+        {
+          "method": "GET",
+          "path": "/api/box/dm/log?limit=50",
+          "description": "Chronological stream of Work Orders, Acks, Results, and inter-operator DMs.",
+          "curl_example": "curl -sk -b 'ops_session=...' https://box.muse-dev.online/api/box/dm/log?limit=30"
+        },
+        {
+          "method": "POST",
+          "path": "/api/box/dm/send",
+          "description": "Dispatch a signed DM or Work Order to a recipient or sidechat target.",
+          "curl_example": "curl -sk -X POST https://box.muse-dev.online/api/box/dm/send -d '{\"agent\":\"646\",\"to\":\"pip\",\"target\":\"646-pip\",\"message\":\"[WO:...] ...\"}'"
+        }
+      ],
+      "assistive_recipe": "Filter by data-agent attribute to isolate node traffic. Search box filters dynamically by text."
+    },
+    "jobs": {
+      "name": "Timers & Jobs",
+      "tab_id": "jobs",
+      "dom_tab_selector": ".tab-btn[data-tab=\"jobs\"]",
+      "dom_pane_selector": "#tab-jobs",
+      "key_elements": {
+        "table": "#jobs-table",
+        "tbody": "#jobs-tbody",
+        "trigger_button": ".btn-trigger",
+        "active_badge": ".badge-active",
+        "unit_name": ".timer-unit-name"
+      },
+      "api_endpoints": [
+        {
+          "method": "GET",
+          "path": "/api/box/timers",
+          "description": "List all active systemd user timer schedules, next run, and last results.",
+          "curl_example": "curl -sk https://box.muse-dev.online/api/box/timers"
+        },
+        {
+          "method": "POST",
+          "path": "/api/box/jobs/{name}/trigger",
+          "description": "Asynchronous hot-trigger calling box-ctl.py job-trigger. Returns 202 Accepted immediately.",
+          "curl_example": "curl -sk -X POST https://box.muse-dev.online/api/box/jobs/box-http-health/trigger"
+        }
+      ],
+      "assistive_recipe": "Clicking ▶ Run invokes hot-trigger without blocking the browser. Button displays Triggering... then Sent."
+    },
+    "loops": {
+      "name": "Loop & Strategy Matrix",
+      "tab_id": "loops",
+      "dom_tab_selector": ".tab-btn[data-tab=\"loops\"]",
+      "dom_pane_selector": "#tab-loops",
+      "key_elements": {
+        "health_badge": "#loop-health-badge",
+        "loops_grid": "#loops-grid",
+        "strategy_table": "#strat-table",
+        "vars_table": "#vars-table",
+        "edit_modal": "#modal-edit-var",
+        "count_badge": "#loops-count-badge"
+      },
+      "api_endpoints": [
+        {
+          "method": "GET",
+          "path": "/api/box/loop/health",
+          "description": "Fleet loop health ratio (answered+closed vs landed) with health verdicts.",
+          "curl_example": "curl -sk https://box.muse-dev.online/api/box/loop/health"
+        },
+        {
+          "method": "GET",
+          "path": "/api/box/loop/status",
+          "description": "Active open loops, deadlines, and current nudge counters.",
+          "curl_example": "curl -sk https://box.muse-dev.online/api/box/loop/status"
+        },
+        {
+          "method": "GET",
+          "path": "/api/box/loop/vars",
+          "description": "Runtime control variables schema, values, and units.",
+          "curl_example": "curl -sk https://box.muse-dev.online/api/box/loop/vars"
+        },
+        {
+          "method": "POST",
+          "path": "/api/box/loop/vars",
+          "description": "Mutate runtime variable without restarting daemons.",
+          "curl_example": "curl -sk -X POST https://box.muse-dev.online/api/box/loop/vars -d '{\"name\":\"max_nudge_count\",\"value\":3}'"
+        }
+      ],
+      "assistive_recipe": "Use loop health ratio to evaluate fleet velocity. Overdue loops can be nudged directly via box loop nudge."
+    },
+    "approvals": {
+      "name": "Agent Approval Surfaces",
+      "tab_id": "approvals",
+      "dom_tab_selector": null,
+      "dom_pane_selector": ".approval-dialog-container",
+      "key_elements": {
+        "dialog": "[data-testid=\"approval-dialog\"]",
+        "allow_btn": "[data-testid=\"approval-allow\"]",
+        "deny_btn": "[data-testid=\"approval-deny\"]",
+        "ip_field": ".approval-requested-ip",
+        "action_desc": ".approval-description"
+      },
+      "api_endpoints": [
+        {
+          "method": "GET",
+          "path": "/api/approvals",
+          "description": "Query pending approvals across all browser nodes.",
+          "curl_example": "curl -sk https://box.muse-dev.online/api/approvals"
+        }
+      ],
+      "assistive_recipe": "If browser agent is blocked on modal, inspect via 'box approvals check' and approve with 'box approvals allow <node>'."
+    },
+    "telemetry_curl": {
+      "name": "View as curl Drawer",
+      "tab_id": null,
+      "dom_tab_selector": "#curl-toggle-btn",
+      "dom_pane_selector": "#curl-drawer",
+      "key_elements": {
+        "toggle_btn": "#curl-toggle-btn",
+        "drawer": "#curl-drawer",
+        "display_code": "#curl-display",
+        "copy_btn": "#curl-copy-btn"
+      },
+      "api_endpoints": [],
+      "assistive_recipe": "Toggles an off-canvas drawer exposing exact curl invocation for the currently active tab and action."
+    }
+  }
+}

lookup_internal/cli_tools.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CLI Tools Reference & Grammar",
+  "version": "1.0.0",
+  "binaries": {
+    "super": {
+      "path": "/home/super/.local/bin/super",
+      "target": "/home/super/Projects/NetVM/bin/super-cli.py",
+      "description": "Unified off-board orchestrator CLI for NetVM & Box."
+    },
+    "box": {
+      "path": "/home/super/.local/bin/box",
+      "target": "/home/super/Projects/NetVM/bin/super-cli.py",
+      "description": "Agent-facing unified CLI (symlink to super-cli.py)."
+    },
+    "muse": {
+      "path": "/home/super/.local/bin/muse",
+      "target": "/home/super/Projects/NetVM/bin/muse",
+      "description": "Direct headless gateway wrapper with isolated per-node WARP netns."
+    }
+  },
+  "domains": {
+    "fleet": {
+      "summary": "Node health, CDP status, active tabs, watch, restart",
+      "subcommands": [
+        {"cmd": "box fleet status", "desc": "Tabular health status of all 4 browser nodes (CDP latency, tabs, proc)"},
+        {"cmd": "box fleet watch", "desc": "Live refresh terminal dashboard of fleet nodes"},
+        {"cmd": "box fleet restart <node>", "desc": "Safely bounce a specific browser netns node"},
+        {"cmd": "box fleet cdp <node>", "desc": "Inspect open DevTools targets and webSocket URLs"}
+      ]
+    },
+    "approvals": {
+      "summary": "Inspect and handle agent browser & gateway approvals",
+      "subcommands": [
+        {"cmd": "box approvals check [-v]", "desc": "Check if any browser agent is waiting on approval dialogs"},
+        {"cmd": "box approvals inspect <node>", "desc": "Inspect pending approval modal prompt and details"},
+        {"cmd": "box approvals allow <node>", "desc": "Approve pending request on target node"},
+        {"cmd": "box approvals deny <node>", "desc": "Reject pending request on target node"}
+      ]
+    },
+    "dm": {
+      "summary": "Inter-agent DMs, work orders ([WO]), acks, live log tail",
+      "subcommands": [
+        {"cmd": "box dm send --agent <self> --to <peer> --target <sidechat> \"<msg>\"", "desc": "Send signed DM"},
+        {"cmd": "box dm wo --agent <self> --to <peer> --target <chat> --title \"<title>\" \"<body>\"", "desc": "Dispatch structured [WO:id]"},
+        {"cmd": "box dm ack <id> --agent <self>", "desc": "Acknowledge received work order"},
+        {"cmd": "box dm log [--limit N]", "desc": "Read stream of signed work orders and DMs"},
+        {"cmd": "box dm tail", "desc": "Live stream incoming DMs"}
+      ]
+    },
+    "thread": {
+      "summary": "Inspect agent main chats, sidechats, and scrollbacks",
+      "subcommands": [
+        {"cmd": "box thread list [agent]", "desc": "List active sidechats and message threads"},
+        {"cmd": "box thread view <agent> <thread_id> [--limit N]", "desc": "Read messages in a specific thread"}
+      ]
+    },
+    "job": {
+      "summary": "Manage scheduled jobs, systemd timers, triggers, logs",
+      "subcommands": [
+        {"cmd": "box job list", "desc": "List registered jobs and systemd user timers"},
+        {"cmd": "box job run <name>", "desc": "Hot-trigger immediate execution of a job"},
+        {"cmd": "box job status <name>", "desc": "Inspect job execution status and logs"}
+      ]
+    },
+    "web": {
+      "summary": "Probe VM web surfaces (box.muse-dev.online), auth, sync",
+      "subcommands": [
+        {"cmd": "box web health", "desc": "Check Google Cloud VM web surface HTTP status"},
+        {"cmd": "box web test-auth", "desc": "Verify operator auth gating and session token"}
+      ]
+    },
+    "loop": {
+      "summary": "Intrinsic loop strategy, health, break taxonomy, and variables",
+      "subcommands": [
+        {"cmd": "box loop status", "desc": "List active open loops, deadlines, and nudge counts"},
+        {"cmd": "box loop health", "desc": "Show fleet loop health ratio and closure rate"},
+        {"cmd": "box loop nudge <id>", "desc": "Manually trigger a followup nudge on an open loop"},
+        {"cmd": "box loop close <id>", "desc": "Close a loop with verdict"}
+      ]
+    },
+    "vars": {
+      "summary": "Inspect and adjust runtime control variables",
+      "subcommands": [
+        {"cmd": "box vars list", "desc": "List all dynamic runtime control variables"},
+        {"cmd": "box vars get <name>", "desc": "Get current value of a variable"},
+        {"cmd": "box vars set <name> <value>", "desc": "Update runtime variable value"},
+        {"cmd": "box vars reset <name>", "desc": "Reset variable to canonical default"}
+      ]
+    },
+    "tmux": {
+      "summary": "Manage headless background tmux sessions on /tmp/tmux-muse.sock",
+      "subcommands": [
+        {"cmd": "box tmux list", "desc": "List active background agent sessions"},
+        {"cmd": "box tmux new <session> --command \"<cmd>\"", "desc": "Spawn new logged session"},
+        {"cmd": "box tmux send <session> \"<keys>\"", "desc": "Send keystrokes to session"},
+        {"cmd": "box tmux capture <session> [--lines N]", "desc": "Capture session output"}
+      ]
+    },
+    "deploy": {
+      "summary": "Spawn sub-agent session and dispatch task",
+      "subcommands": [
+        {"cmd": "box deploy subagent --agent <self> --title \"<title>\" \"<prompt>\"", "desc": "Spawn autonomous subagent"}
+      ]
+    },
+    "docs": {
+      "summary": "Internal documentation, surfaces, sentence grammar, and regex lookup",
+      "subcommands": [
+        {"cmd": "box docs search <query>", "desc": "Search internal docs database"},
+        {"cmd": "box docs surfaces [name]", "desc": "Lookup assistive surfaces for box.muse-dev.online"},
+        {"cmd": "box docs sentence [name]", "desc": "Lookup agent sentence structures and protocols"},
+        {"cmd": "box docs regex [name] [--test \"str\"]", "desc": "Lookup or test regex patterns"},
+        {"cmd": "box docs parse \"<utterance>\"", "desc": "Parse agent utterance through regex engine"}
+      ]
+    }
+  }
+}

lookup_internal/fleet_nodes.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Fleet Topology & Agent Identities",
+  "version": "1.0.0",
+  "nodes": {
+    "muse": {
+      "identity": "muse",
+      "netns": "warp-muse",
+      "egress_ip": "Dedicated Stable Colo IP (WARP)",
+      "cdp_port": 9410,
+      "peer_ip": "10.201.35.2",
+      "default_sidechat": "muse tasks",
+      "role": "General agent, primary chat evaluation"
+    },
+    "pip": {
+      "identity": "pip",
+      "netns": "warp-pip",
+      "egress_ip": "Dedicated Stable Colo IP (WARP)",
+      "cdp_port": 9411,
+      "peer_ip": "10.201.35.3",
+      "default_sidechat": "646-pip-coord",
+      "role": "Pipeline driver, account management"
+    },
+    "646": {
+      "identity": "646",
+      "netns": "warp-646",
+      "egress_ip": "Dedicated Stable Colo IP (WARP)",
+      "cdp_port": 9412,
+      "peer_ip": "10.201.35.4",
+      "default_sidechat": "646 tasks",
+      "role": "Operator-646, code execution, bridge management"
+    },
+    "opm": {
+      "identity": "opm",
+      "netns": "warp-opm",
+      "egress_ip": "Dedicated Stable Colo IP (WARP)",
+      "cdp_port": 9413,
+      "peer_ip": "10.201.35.5",
+      "default_sidechat": "heartbeat",
+      "role": "Operator-main, supervisor, telemetry check"
+    },
+    "dev": {
+      "identity": "dev",
+      "netns": "warp-dev",
+      "egress_ip": "Staging WARP egress",
+      "cdp_port": 9414,
+      "peer_ip": "10.201.35.6",
+      "default_sidechat": "dev tasks",
+      "role": "Development and experimental features"
+    },
+    "def": {
+      "identity": "def",
+      "netns": "warp-def",
+      "egress_ip": "Default fallback egress",
+      "cdp_port": 9415,
+      "peer_ip": "10.201.35.7",
+      "default_sidechat": "default",
+      "role": "Fallback routing node"
+    }
+  }
+}

lookup_internal/manifest.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "docs_internal",
+  "alias": "lookup_internal",
+  "version": "1.1.0",
+  "description": "Internal Agent & Operator Lookup Database for NetVM, Box, and box.muse-dev.online",
+  "created_at": "2026-10-05T19:16:00Z",
+  "host": "box.muse-dev.online",
+  "primary_node": "bl (100.123.153.75)",
+  "collections": [
+    {
+      "id": "sentence_structure",
+      "name": "Agent Sentence Structures & Protocols",
+      "json_file": "sentence_structure.json",
+      "md_file": "SENTENCE-STRUCTURE.md",
+      "description": "Formal grammar, prefixes, intents, work orders, acks, results, and conversational contracts used by autonomous fleet agents.",
+      "keys_count": 14
+    },
+    {
+      "id": "regex_patterns",
+      "name": "Regex Patterns & Passing Engine",
+      "json_file": "regex_patterns.json",
+      "md_file": "REGEX-PATTERNS.md",
+      "description": "Comprehensive regex patterns with capture groups, test fixtures, and passing mechanisms for message harvesting and parsing.",
+      "keys_count": 16
+    },
+    {
+      "id": "assistive_surfaces",
+      "name": "Assistive Surfaces for box.muse-dev.online",
+      "json_file": "assistive_surfaces.json",
+      "md_file": "SURFACES.md",
+      "description": "Catalog of UI views, DOM selectors, data-testids, modals, REST endpoints, and automation recipes for box.muse-dev.online.",
+      "keys_count": 6
+    },
+    {
+      "id": "cli_tools",
+      "name": "CLI Tools Reference & Grammar",
+      "json_file": "cli_tools.json",
+      "md_file": "CLI-TOOLS.md",
+      "description": "Command syntax, options, and dispatch paths for super, box, muse, and orchestrator utilities.",
+      "keys_count": 12
+    },
+    {
+      "id": "fleet_nodes",
+      "name": "Fleet Topology & Agent Identities",
+      "json_file": "fleet_nodes.json",
+      "md_file": "FLEET-NODES.md",
+      "description": "Active fleet agents, network namespaces, WireGuard warp addresses, CDP debugging ports, and task assignments.",
+      "keys_count": 6
+    }
+  ]
+}

lookup_internal/regex_patterns.json

@@ -0,0 +1,348 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Regex Patterns & Passing Engine",
+  "version": "1.0.0",
+  "patterns": {
+    "work_order": {
+      "name": "Work Order Parser",
+      "pattern": "^\\[WO:(?P<wo_id>[a-f0-9-]+)\\]\\s+\\[from\\s+(?P<sender>[a-zA-Z0-9_-]+)\\]\\s+(?P<title>[^—\\n]+?)\\s*—\\s*(?P<body>.+)$",
+      "flags": ["MULTILINE", "DOTALL"],
+      "description": "Matches canonical Work Order messages, extracting unique ID, sender, title, and body.",
+      "named_groups": {
+        "wo_id": "Unique work order identifier (hex or UUID)",
+        "sender": "Originating agent or operator identity",
+        "title": "Short title describing the task",
+        "body": "Full body text and instructions"
+      },
+      "test_samples": {
+        "valid": [
+          "[WO:7fce46e0] [from super] Audit exec.muse-dev.online endpoints — Run full verification and check 200 codes.",
+          "[WO:a1b2c3d4-e5f6-7890-abcd-ef1234567890] [from 646] Deploy patch — Apply fix to response-harvester."
+        ],
+        "invalid": [
+          "Just sending a regular message without tag",
+          "[WO:] missing id [from super] title — body",
+          "[WO:123] missing from tag title — body"
+        ]
+      },
+      "usage": "Used by dm.py, super dm, and self_main_loop.py for tracking work orders."
+    },
+    "ack": {
+      "name": "Acknowledgement Parser",
+      "pattern": "^\\[ACK:(?P<ack_id>[a-f0-9-]+)\\](?:\\s+\\[from\\s+(?P<sender>[a-zA-Z0-9_-]+)\\])?",
+      "flags": ["MULTILINE"],
+      "description": "Matches work order acknowledgement tags, capturing referenced ID and optional sender.",
+      "named_groups": {
+        "ack_id": "Referenced work order ID being acknowledged",
+        "sender": "Optional sender acknowledging the message"
+      },
+      "test_samples": {
+        "valid": [
+          "[ACK:7fce46e0] [from 646]",
+          "[ACK:a1b2c3d4]"
+        ],
+        "invalid": [
+          "ACK: 7fce46e0",
+          "[ACK:]",
+          "Acknowledged without brackets"
+        ]
+      },
+      "usage": "Used by response-harvester.py and followup-sweeper.py to transition loops to acknowledged."
+    },
+    "verb": {
+      "name": "Standard Agent Verb Marker",
+      "pattern": "\\[(?P<verb>ACK|CLAIM|RESULT|DECLINE|NO-ACTION)\\s+(?P<job_id>[A-Za-z0-9_/-]+)\\]",
+      "flags": [],
+      "description": "Matches all standard conversational contract verbs referencing a job ID.",
+      "named_groups": {
+        "verb": "One of ACK, CLAIM, RESULT, DECLINE, NO-ACTION",
+        "job_id": "Target task or job identifier"
+      },
+      "test_samples": {
+        "valid": [
+          "[ACK 7fce46e0]",
+          "[CLAIM job-123]",
+          "[RESULT swarm-4a/2]",
+          "[DECLINE audit-01]",
+          "[NO-ACTION check-99]"
+        ],
+        "invalid": [
+          "[DONE 7fce46e0]",
+          "[RESULT]",
+          "RESULT 7fce46e0 without brackets"
+        ]
+      },
+      "usage": "Primary regex used in response-harvester.py (VERB_RE) for loop state resolution."
+    },
+    "result": {
+      "name": "Task Result & Outcome Parser",
+      "pattern": "\\[RESULT\\s+(?P<job_id>[A-Za-z0-9_/-]+)\\]\\s*(?P<status>OK|FAIL|DECLINE|SUCCESS|ERROR)?\\s*(?P<summary>.*?)(?=\\[RESULT\\s|\\Z)",
+      "flags": ["DOTALL"],
+      "description": "Extracts job ID, optional status flag, and trailing summary for task outcomes.",
+      "named_groups": {
+        "job_id": "Target job or swarm slot ID",
+        "status": "Optional explicit status token (OK, FAIL, etc.)",
+        "summary": "Outcome description and evidence payload"
+      },
+      "test_samples": {
+        "valid": [
+          "[RESULT 7fce46e0] OK Verified 14 endpoints successfully.",
+          "[RESULT test-job] FAIL Connection timed out on port 22",
+          "[RESULT swarm-1/0] Completed slot tasks."
+        ],
+        "invalid": [
+          "Result of job 123 is OK",
+          "[RESULT] missing job id"
+        ]
+      },
+      "usage": "Used in response-harvester.py (RESULT_RE) to harvest results into job-log.jsonl."
+    },
+    "tool_call": {
+      "name": "In-Band Tool Execution Call",
+      "pattern": "\\[(?P<engine>TOOL|EXEC|DM)\\s+(?:(?P<op>[a-zA-Z0-9_.-]+)\\s+)?(?P<args>\\{([^{}]|\\{[^{}]*\\})*\\})\\]",
+      "flags": ["DOTALL"],
+      "description": "Matches inline tool directives with JSON args (one nesting level; response-harvester.py scans balanced braces for arbitrary depth). DM carries no op (implies dm.send).",
+      "named_groups": {
+        "engine": "TOOL, EXEC, or DM (DM implies dm.send)",
+        "op": "Target operation (e.g. followup.create, swarm.spawn); absent for DM",
+        "args": "JSON argument object; may contain ']' and one level of nested objects"
+      },
+      "test_samples": {
+        "valid": [
+          "[TOOL followup.create {\"in_m\": 5, \"prompt\": \"check\"}]",
+          "[EXEC health.check {\"verbose\": true}]",
+          "[TOOL box.exec {\"action\": \"job-get\", \"arg\": \"a-b[0]\"}]",
+          "[DM {\"to\": \"pip\", \"target\": \"pip tasks\", \"message\": \"hi\"}]"
+        ],
+        "invalid": [
+          "[TOOL followup.create without args]",
+          "[TOOL invalid args not json]"
+        ]
+      },
+      "usage": "Parsed by response-harvester.py and exec-constrained.py for automated in-line actions."
+    },
+    "job_tag": {
+      "name": "Job Tracking Tag",
+      "pattern": "\\[JOB\\s+(?P<job_id>[A-Za-z0-9_/-]+)\\]",
+      "flags": [],
+      "description": "Matches job tag markers embedded in digests, tasks, or swarm slots.",
+      "named_groups": {
+        "job_id": "Unique job identifier"
+      },
+      "test_samples": {
+        "valid": [
+          "[JOB ml-646-20261005-191500]",
+          "[JOB swarm-4b/1]"
+        ],
+        "invalid": [
+          "JOB ml-646 without brackets",
+          "[JOB]"
+        ]
+      },
+      "usage": "Used by self_main_loop.py and job-dispatch.py for tracking."
+    },
+    "nudge": {
+      "name": "Loop Followup Nudge Parser",
+      "pattern": "\\[NUDGE\\s+(?P<loop_id>[a-f0-9-]+)\\]\\s*(?:\\[nudge\\s+(?P<count>\\d+)/(?P<max_count>\\d+)\\])?\\s*(?:Deadline\\s+(?P<deadline>[^:]+):)?\\s*(?P<prompt>.*)",
+      "flags": ["MULTILINE"],
+      "description": "Matches automated followup nudges, extracting loop ID, nudge counters, and deadlines.",
+      "named_groups": {
+        "loop_id": "Target loop identifier",
+        "count": "Current nudge sequence number",
+        "max_count": "Maximum allowed nudges before escalation",
+        "deadline": "Deadline timestamp string",
+        "prompt": "Nudge message instructions"
+      },
+      "test_samples": {
+        "valid": [
+          "[NUDGE 7fce46e0] [nudge 1/3] Deadline 19:45 UTC: Please confirm status of exec audit.",
+          "[NUDGE a1b2c3d4] Please review pending pull request."
+        ],
+        "invalid": [
+          "Nudge for 7fce46e0",
+          "[NUDGE]"
+        ]
+      },
+      "usage": "Used by followup-sweeper.py for SLA enforcement."
+    },
+    "fleet_alert": {
+      "name": "Fleet Alert Broadcast Parser",
+      "pattern": "\\[fleet-alert\\]\\s+(?P<severity>CRITICAL|WARN|INFO|RECOVERED):\\s+(?P<message>.+)",
+      "flags": ["MULTILINE"],
+      "description": "Matches infrastructure alert broadcasts dispatched into #lobby and #jobs.",
+      "named_groups": {
+        "severity": "CRITICAL, WARN, INFO, or RECOVERED",
+        "message": "Alert message body"
+      },
+      "test_samples": {
+        "valid": [
+          "[fleet-alert] CRITICAL: VM unreachable x2 on port 22",
+          "[fleet-alert] RECOVERED: VM 34.139.37.135 responded with 200 OK"
+        ],
+        "invalid": [
+          "[alert] CRITICAL: Missing fleet prefix",
+          "fleet-alert: info"
+        ]
+      },
+      "usage": "Used by fleet-alert-check.sh and main-chat-watchdog.py."
+    },
+    "directive": {
+      "name": "Agent Action Directive",
+      "pattern": "\\[Directive:\\s*(?P<directive>.+?)\\]",
+      "flags": ["DOTALL"],
+      "description": "Extracts operational action directives targeting autonomous agents.",
+      "named_groups": {
+        "directive": "Actionable directive instruction"
+      },
+      "test_samples": {
+        "valid": [
+          "[Directive: Take next action or close with [RESULT 7fce46e0] <summary>]",
+          "[Directive: Run audit on node pip]"
+        ],
+        "invalid": [
+          "Directive: without brackets",
+          "[Directive:]"
+        ]
+      },
+      "usage": "Injected into prompts by response-harvester.py and job-dispatch.py."
+    },
+    "runtime_context": {
+      "name": "Runtime Context URL",
+      "pattern": "\\[Runtime Context:\\s*(?P<url>https?://[^\\s\\]]+)\\]",
+      "flags": [],
+      "description": "Extracts assistive web surface or thread URLs from message context.",
+      "named_groups": {
+        "url": "HTTP/HTTPS URL"
+      },
+      "test_samples": {
+        "valid": [
+          "[Runtime Context: https://box.muse-dev.online/thread/7fce46e0]",
+          "[Runtime Context: https://box.muse-dev.online/api/box/fleet]"
+        ],
+        "invalid": [
+          "Runtime Context: not wrapped",
+          "[Runtime Context: invalid-url]"
+        ]
+      },
+      "usage": "Used by assistive surfaces and browser agent navigation routines."
+    },
+    "uuid": {
+      "name": "Canonical UUID Pattern",
+      "pattern": "\\b(?P<uuid>[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\\b",
+      "flags": [],
+      "description": "Standard RFC 4122 UUID v4 detector for threads, messages, and session IDs.",
+      "named_groups": {
+        "uuid": "Matched UUID string"
+      },
+      "test_samples": {
+        "valid": [
+          "dc6d72ca-4b02-4217-bf41-7dbca19c5c24",
+          "d410b9ad-f667-465f-a103-43fabc0f69fe"
+        ],
+        "invalid": [
+          "dc6d72ca-4b02-4217-bf41",
+          "not-a-uuid"
+        ]
+      },
+      "usage": "Thread ID resolution in muse-chat-api.py and super-cli.py."
+    },
+    "short_hex": {
+      "name": "Short Hex Identifier",
+      "pattern": "\\b(?P<hex>[0-9a-fA-F]{6,12})\\b",
+      "flags": [],
+      "description": "Matches 6-12 character hexadecimal hashes used for compact DM IDs and subagent hashes.",
+      "named_groups": {
+        "hex": "Hexadecimal string"
+      },
+      "test_samples": {
+        "valid": [
+          "7fce46e0",
+          "04af8e15",
+          "ca56e39199da"
+        ],
+        "invalid": [
+          "123",
+          "abcdefghijk"
+        ]
+      },
+      "usage": "Compact ID matching across logs and DM tables."
+    },
+    "subagent_update": {
+      "name": "Subagent Update Notification",
+      "pattern": "\\[SUBAGENT-UPDATE\\]\\s+Subagent\\s+'(?P<title>[^']+)'\\s+\\((?P<short_id>[0-9a-fA-F]+)\\)\\s+(?P<message>.+)",
+      "flags": ["MULTILINE"],
+      "description": "Parses status updates and milestones from background subagent executions.",
+      "named_groups": {
+        "title": "Subagent session title",
+        "short_id": "Hex identifier of the subagent session",
+        "message": "Progress update message"
+      },
+      "test_samples": {
+        "valid": [
+          "[SUBAGENT-UPDATE] Subagent 'exec-audit' (4a2b8e) has posted new output.",
+          "[SUBAGENT-UPDATE] Subagent 'health-check' (12ff4a) completed successfully."
+        ],
+        "invalid": [
+          "Subagent update without brackets"
+        ]
+      },
+      "usage": "Used by self_main_loop.py subagent monitor."
+    },
+    "swarm_slot": {
+      "name": "Swarm Slot Task Marker",
+      "pattern": "\\[JOB\\s+(?P<swarm_id>[a-zA-Z0-9_-]+)/(?P<slot>\\d+)\\]",
+      "flags": [],
+      "description": "Matches swarm worker slot task assignments.",
+      "named_groups": {
+        "swarm_id": "ID of parent swarm execution",
+        "slot": "Index of worker slot (e.g. 0, 1, 2)"
+      },
+      "test_samples": {
+        "valid": [
+          "[JOB swarm-99a/0]",
+          "[JOB swarm-4a2b/3]"
+        ],
+        "invalid": [
+          "[JOB swarm-99a]"
+        ]
+      },
+      "usage": "Used in response-harvester.py and swarm_worker."
+    },
+    "contract_footer": {
+      "name": "Contract Footer Verifier",
+      "pattern": "Reply:\\s*\\[ACK\\s+id\\]\\s*seen\\s*\\|\\s*\\[CLAIM\\s+id\\]\\s*mine\\s*\\|\\s*\\[RESULT\\s+id\\]\\s*done\\s*\\|\\s*\\[DECLINE\\s+id\\]\\s*\\|\\s*\\[NO-ACTION\\s+id\\]\\.?",
+      "flags": ["IGNORECASE"],
+      "description": "Validates the presence of the standard agent contract footer in prompt envelopes.",
+      "named_groups": {},
+      "test_samples": {
+        "valid": [
+          "Reply: [ACK id] seen | [CLAIM id] mine | [RESULT id] done | [DECLINE id] | [NO-ACTION id]."
+        ],
+        "invalid": [
+          "Please reply when ready"
+        ]
+      },
+      "usage": "Enforced in self_main_loop.py CONTRACT_FOOTER."
+    },
+    "sender_tag": {
+      "name": "Sender Identity Tag",
+      "pattern": "\\[from[:\\s]+(?P<sender>[a-zA-Z0-9_-]+)\\]",
+      "flags": ["IGNORECASE"],
+      "description": "Matches agent or operator attribution tags in chat messages.",
+      "named_groups": {
+        "sender": "Identity of sender"
+      },
+      "test_samples": {
+        "valid": [
+          "[from:super]",
+          "[from 646]",
+          "[from pip]"
+        ],
+        "invalid": [
+          "from super without brackets"
+        ]
+      },
+      "usage": "Used in chat-history parsing and loop attribution."
+    }
+  }
+}

lookup_internal/sentence_structure.json

@@ -0,0 +1,176 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Agent Sentence Structures & Protocols",
+  "version": "1.0.0",
+  "surface": "box.muse-dev.online",
+  "structures": {
+    "work_order": {
+      "name": "Work Order",
+      "protocol_tag": "[WO:<id>]",
+      "template": "[WO:{dm_id}] [from {sender}] {title} — {body}",
+      "description": "Structured task dispatched between operators or from orchestrator to agent. Initiates a trackable loop.",
+      "required_fields": ["dm_id", "sender", "title", "body"],
+      "optional_fields": ["priority", "due"],
+      "regex_ref": "work_order",
+      "reply_expectation": "Recipient must reply with [ACK id], [CLAIM id], [RESULT id], [DECLINE id], or [NO-ACTION id].",
+      "example": "[WO:7fce46e0] [from super] Audit exec.muse-dev.online endpoints — Please run full check on GET /api/stats and post results.",
+      "lifecycle_transition": "open -> acknowledged -> running -> closed"
+    },
+    "ack": {
+      "name": "Acknowledgement",
+      "protocol_tag": "[ACK:<id>]",
+      "template": "[ACK:{dm_id}] [from {sender}]",
+      "description": "Signals receipt and understanding of a Work Order or message, updating status to acknowledged.",
+      "required_fields": ["dm_id"],
+      "optional_fields": ["sender"],
+      "regex_ref": "ack",
+      "reply_expectation": "Loop remains open awaiting final [RESULT id].",
+      "example": "[ACK:7fce46e0] [from 646]",
+      "lifecycle_transition": "open -> acknowledged"
+    },
+    "claim": {
+      "name": "Task Claim",
+      "protocol_tag": "[CLAIM <id>]",
+      "template": "[CLAIM {job_id}]",
+      "description": "Claims exclusive ownership of an unassigned job or swarm task slot, preventing duplicate worker runs.",
+      "required_fields": ["job_id"],
+      "optional_fields": [],
+      "regex_ref": "verb",
+      "reply_expectation": "Worker must execute task and post [RESULT id] when complete.",
+      "example": "[CLAIM 7fce46e0]",
+      "lifecycle_transition": "acknowledged -> claimed"
+    },
+    "result": {
+      "name": "Task Completion Result",
+      "protocol_tag": "[RESULT <id>]",
+      "template": "[RESULT {job_id}] {status} {summary}",
+      "description": "Delivers the final output, verdict, or evidence of a completed task and closes the tracked loop.",
+      "required_fields": ["job_id", "summary"],
+      "optional_fields": ["status"],
+      "regex_ref": "result",
+      "reply_expectation": "Closes the loop; no further reply required unless sender issues new work order.",
+      "example": "[RESULT 7fce46e0] OK Audit complete: 14 allowlisted ops confirmed healthy, 0 errors.",
+      "lifecycle_transition": "running/claimed -> resolved (closed)"
+    },
+    "decline": {
+      "name": "Task Decline / Refusal",
+      "protocol_tag": "[DECLINE <id>]",
+      "template": "[DECLINE {job_id}] {reason}",
+      "description": "Explicitly declines or rejects a work order with justification (e.g. rate limit, outside domain).",
+      "required_fields": ["job_id", "reason"],
+      "optional_fields": [],
+      "regex_ref": "verb",
+      "reply_expectation": "Closes loop as declined; triggers orchestrator fallback or re-dispatch.",
+      "example": "[DECLINE 7fce46e0] Target node warp-dev is currently down for maintenance.",
+      "lifecycle_transition": "open/claimed -> declined (closed)"
+    },
+    "no_action": {
+      "name": "No Action Warranted",
+      "protocol_tag": "[NO-ACTION <id>]",
+      "template": "[NO-ACTION {job_id}] {reason}",
+      "description": "Acknowledges check but concludes no mutation or action was required (e.g. alert was transient flap).",
+      "required_fields": ["job_id", "reason"],
+      "optional_fields": [],
+      "regex_ref": "verb",
+      "reply_expectation": "Closes loop as resolved without side-effects.",
+      "example": "[NO-ACTION 7fce46e0] Transponder probe recovered before grace period expired.",
+      "lifecycle_transition": "open/claimed -> no-action (closed)"
+    },
+    "tool_call": {
+      "name": "In-Band Tool Execution Call",
+      "protocol_tag": "[TOOL <op> <args>]",
+      "template": "[TOOL {op} {args_json}]",
+      "description": "Synthesized inline tool execution directive parsed by response-harvester and executed on host.",
+      "required_fields": ["op", "args_json"],
+      "optional_fields": [],
+      "regex_ref": "tool_call",
+      "reply_expectation": "System executes op and posts execution result back into thread.",
+      "example": "[TOOL followup.create {\"in_m\": 5, \"prompt\": \"Recheck VM reachability\"}]",
+      "lifecycle_transition": "in-flight execution"
+    },
+    "job_marker": {
+      "name": "Job Tracking Marker",
+      "protocol_tag": "[JOB <id>]",
+      "template": "[JOB {job_id}]",
+      "description": "Identifies an automated task or swarm slot dispatched by scheduler or supervisor.",
+      "required_fields": ["job_id"],
+      "optional_fields": ["slot"],
+      "regex_ref": "job_tag",
+      "reply_expectation": "Worker replies with [RESULT job_id] upon conclusion.",
+      "example": "[JOB swarm-4a2b/1] Task for swarm slot 1: Run identity variance audit.",
+      "lifecycle_transition": "dispatched -> tracked"
+    },
+    "nudge": {
+      "name": "Loop Followup Nudge",
+      "protocol_tag": "[NUDGE <id>]",
+      "template": "[NUDGE {loop_id}] [nudge {count}/{max_nudges}] Deadline {deadline_utc}: {prompt}",
+      "description": "Automated prompt sent to recipient when a work order approaches or exceeds its SLA without an ack/result.",
+      "required_fields": ["loop_id", "count", "max_nudges", "deadline_utc"],
+      "optional_fields": ["prompt"],
+      "regex_ref": "nudge",
+      "reply_expectation": "Recipient must immediately reply with [ACK id] or [RESULT id].",
+      "example": "[NUDGE 7fce46e0] [nudge 1/3] Deadline 19:45 UTC: Please confirm status of exec audit.",
+      "lifecycle_transition": "nudged"
+    },
+    "fleet_alert": {
+      "name": "Fleet Operational Alert",
+      "protocol_tag": "[fleet-alert]",
+      "template": "[fleet-alert] {severity}: {message}",
+      "description": "System or detector broadcast into broadcast sidechats (#lobby, #jobs) regarding infrastructure events.",
+      "required_fields": ["severity", "message"],
+      "optional_fields": [],
+      "regex_ref": "fleet_alert",
+      "reply_expectation": "Broadcast telemetry; no direct reply required unless work order accompanies it.",
+      "example": "[fleet-alert] CRITICAL: VM unreachable x2 on port 22",
+      "lifecycle_transition": "alert -> incident"
+    },
+    "contract_footer": {
+      "name": "Standard Conversational Contract Footer",
+      "protocol_tag": "Reply: [ACK id] seen ...",
+      "template": "Reply: [ACK {id}] seen | [CLAIM {id}] mine | [RESULT {id}] done | [DECLINE {id}] | [NO-ACTION {id}].",
+      "description": "Appended to prompts, digests, and task orders to remind model instances of acceptable parsing grammar.",
+      "required_fields": ["id"],
+      "optional_fields": [],
+      "regex_ref": "contract_footer",
+      "reply_expectation": "Strictly governs model output to use one of the specified reply prefixes.",
+      "example": "Reply: [ACK 7fce46e0] seen | [CLAIM 7fce46e0] mine | [RESULT 7fce46e0] done | [DECLINE 7fce46e0] | [NO-ACTION 7fce46e0].",
+      "lifecycle_transition": "directive"
+    },
+    "directive": {
+      "name": "Agent Action Directive",
+      "protocol_tag": "[Directive: ...]",
+      "template": "[Directive: {directive}]",
+      "description": "Actionable instruction enclosed in square brackets guiding agent forward progression.",
+      "required_fields": ["directive"],
+      "optional_fields": [],
+      "regex_ref": "directive",
+      "reply_expectation": "Agent must fulfill directive in subsequent conversational turn.",
+      "example": "[Directive: Take next action or close with [RESULT 7fce46e0] <summary>]",
+      "lifecycle_transition": "instruction"
+    },
+    "runtime_context": {
+      "name": "Runtime Context URL",
+      "protocol_tag": "[Runtime Context: ...]",
+      "template": "[Runtime Context: {url}]",
+      "description": "Injects thread URL or Web UI surface link for assistive navigation by agent.",
+      "required_fields": ["url"],
+      "optional_fields": [],
+      "regex_ref": "runtime_context",
+      "reply_expectation": "Provides reference telemetry for browser agent.",
+      "example": "[Runtime Context: https://box.muse-dev.online/thread/7fce46e0]",
+      "lifecycle_transition": "telemetry"
+    },
+    "subagent_update": {
+      "name": "Subagent Progress Update",
+      "protocol_tag": "[SUBAGENT-UPDATE]",
+      "template": "[SUBAGENT-UPDATE] Subagent '{title}' ({short_id}) has posted new output.",
+      "description": "Notification relay from background subagent session to parent orchestrator.",
+      "required_fields": ["title", "short_id"],
+      "optional_fields": ["details"],
+      "regex_ref": "subagent_update",
+      "reply_expectation": "Parent logs progress or incorporates findings into main thread.",
+      "example": "[SUBAGENT-UPDATE] Subagent 'exec-audit' (4a2b8e) has posted new output.",
+      "lifecycle_transition": "subagent-relay"
+    }
+  }
+}

shared/operators/AGENTS.md

@@ -20,6 +20,14 @@ Every outbound ask gets a follow-up deadline matched to its round-trip, not a ho
 
 ## Box system (2026-10-04)
 - `https://box.muse-dev.online` — dashboard at `/#dashboard`. Health: `/srv/box/bin/box-health-check.sh {services,data,http}` on the VM (board.service, caddy, sweeper timer; /srv/box + uploads writable; 6 HTTP checks).
+- **Operator Passkey & Key Material Reality (2026-10-05):**
+  - **Location Reality:** The operator passkey / PIN for `https://box.muse-dev.online` is stored in a **single file (`.txt`) on the VM (`34.139.37.135`)** — **NOT on the dedicated BL compute node (`100.123.153.75`)**.
+  - **Operator PIN:** `3128` (unlocks `https://box.muse-dev.online` via `POST /api/ops/login`, establishing `ops_session` cookie). Operators frequently forget this passkey; retrieve from the VM txt file or use `box passkey` on bl.
+  - **Agent Approval Protocol:** Autonomous agents do NOT hold administrative passkeys or credentials directly. Secrets never reside on bl. If an agent requires key access, privileged credentials, or operator elevation, the agent MUST NOT search `bl`. Instead:
+    1. Emit `APPROVAL_NEEDED: <details of required key / action>` in the task sidechat (e.g. `646 tasks`, `pip tasks`, `#jobs`, `heartbeat`), or exit code `2` (INFRA.md convention).
+    2. The human operator validates the request, consults the single `.txt` file on the VM to authenticate/approve, or handles the action via `box approvals`.
+  - **Unified Lookup Surfaces:** Use `box lookup` (or `box key`, `box passkey`, `box tmux`, `box muse`) for instant lookups across nodes, registered threads, unread status, and approvals.
+  - **Internal Docs & Agent Lookup Engine (2026-10-05):** `docs_internal/` holds the canonical database (`.md` and `.json`) for agent sentence grammar (`[WO:...]`, `[ACK:...]`, `[RESULT:...]`), regex passing fixtures, and assistive surfaces for `box.muse-dev.online` (DOM selectors, tabs, and REST routes). Accessible via `box docs surfaces`, `box docs sentence`, `box docs regex`, and `box docs parse`.
 - **Agent-tier API auth:** my `~/.ssh/id_frontdoor` is registered as `operator-646` in `/srv/board/allowed_signers`. Method: `TS=$(date +%s); printf '%s\n%s' "$TS" "<endpoint>" > p; ssh-keygen -Y sign -f ~/.ssh/id_frontdoor -n box p` (file-based, never pipe), then `GET https://box.muse-dev.online/api/box/<path>?identity=operator-646&ts=$TS&sig=<urlencoded p.sig>`. Signature endpoint = last path segment (`fleet`, `log`, `nodes`, …). Verified: `/api/box/fleet` → 200 live fleet array; `/api/box/dm/log` → 200 (agent tier sees only DMs where it's a party — empty is correct). All box APIs are 403 unauthenticated by design.
 - Request-store checker WARN is a path bug: `box-health-check.sh:167` checks `/srv/box/box_requests.jsonl` and `/srv/box/requests.jsonl`, but the real store is `/srv/box/requests/requests.jsonl`. One-line fix (add the real path); WARN is non-fatal by design.
 - `/srv/box/uploads` keeps getting reset to `root:root 700` by the box publish path (3×); manual `chown super:frontdoor; chmod 770` holds. The publish script lives outside reachable repos — durable fix needs the publish owner to add the explicit chown post-deploy.

systemd/completion-audit.service

@@ -0,0 +1,10 @@
+[Unit]
+Description=NetVM completion funnel auditor (15m digest)
+
+[Service]
+Type=oneshot
+User=super
+WorkingDirectory=/home/super/Projects/NetVM
+ExecStart=/usr/bin/python3 /home/super/Projects/NetVM/bin/completion-audit.py --hours 24
+StandardOutput=journal
+StandardError=journal

systemd/completion-audit.timer

@@ -0,0 +1,9 @@
+[Unit]
+Description=Run completion auditor every 15 minutes
+
+[Timer]
+OnCalendar=*:4/15
+Persistent=true
+
+[Install]
+WantedBy=timers.target

tests/test_agent_ranking.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""
+test_agent_ranking.py — Unit test suite for Fleet Agent interaction ranking & sorting:
+1. Agent interaction recording on true input / chat [insert].
+2. Fleet agent sorting/ranking by last interaction descending.
+3. Stable fallback ordering for un-interacted agents.
+4. Persistence and seeding of interaction timestamps.
+5. format_recency helper accuracy.
+"""
+
+import unittest
+from unittest.mock import MagicMock, patch
+import importlib.util
+from pathlib import Path
+import time
+import tempfile
+import json
+
+REPO_ROOT = Path("/home/super/Projects/NetVM")
+TUI_PATH = REPO_ROOT / "bin" / "muse-tui.py"
+
+spec = importlib.util.spec_from_file_location("muse_tui", str(TUI_PATH))
+muse_mod = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(muse_mod)
+
+
+class TestAgentRanking(unittest.TestCase):
+    """Test suite covering fleet agent interaction sorting & recency tracking."""
+
+    def setUp(self):
+        self.mock_stdscr = MagicMock()
+        self.mock_stdscr.getmaxyx.return_value = (30, 100)
+        self.tui = muse_mod.MuseTUI(self.mock_stdscr, initial_mode="muse", initial_node="muse")
+        self.tui.safe_addstr = MagicMock()
+        self.tui.data.history_cache = {}
+        self.tui.data.read_msg_counts = {}
+
+    def test_format_recency(self):
+        """Verify format_recency produces compact, accurate recency strings."""
+        now = time.time()
+        self.assertEqual(muse_mod.format_recency(0.0), "never")
+        self.assertEqual(muse_mod.format_recency(None), "never")
+        self.assertEqual(muse_mod.format_recency(now - 10), "10s ago")
+        self.assertEqual(muse_mod.format_recency(now - 120), "2m ago")
+        self.assertEqual(muse_mod.format_recency(now - 7200), "2h ago")
+        self.assertEqual(muse_mod.format_recency(now - 90000), "1d ago")
+
+    def test_sort_nodes_by_interaction(self):
+        """Verify sort_nodes ranks nodes by last interaction timestamp descending."""
+        data = self.tui.data
+        now = time.time()
+
+        # Set specific timestamps
+        data.agent_interactions["muse"] = now - 500
+        data.agent_interactions["pip"] = now - 100
+        data.agent_interactions["646"] = now - 10   # Most recent
+        data.agent_interactions["opm"] = 0.0        # Never
+        data.agent_interactions["def"] = 0.0        # Never
+
+        data.sort_nodes()
+
+        # Most recent first: 646, then pip, then muse
+        self.assertEqual(data.nodes[0], "646")
+        self.assertEqual(data.nodes[1], "pip")
+        self.assertEqual(data.nodes[2], "muse")
+        # Un-interacted agents should be at the end, retaining baseline order
+        self.assertIn("opm", data.nodes[3:])
+        self.assertIn("def", data.nodes[3:])
+
+    def test_record_interaction_promotes_node_to_top(self):
+        """Verify record_interaction immediately updates timestamp and promotes node to rank 1."""
+        data = self.tui.data
+        # Ensure 'pip' is not at index 0 initially
+        data.record_interaction("646")
+        self.assertEqual(data.nodes[0], "646")
+
+        # Now operator directly interacts with 'pip'
+        t0 = time.time()
+        data.record_interaction("pip")
+        self.assertEqual(data.nodes[0], "pip", "'pip' must be promoted to rank 1 (index 0)")
+        self.assertEqual(data.nodes[1], "646", "'646' must be rank 2")
+        self.assertGreaterEqual(data.agent_interactions["pip"], t0)
+
+    def test_chat_message_submission_triggers_ranking(self):
+        """Verify submitting chat message in INSERT mode promotes the active node."""
+        self.tui.editor_mode = "INSERT"
+        self.tui.data.active_node = "def"
+        self.tui.data.active_thread_id = "test-session-123"
+        self.tui.data.active_thread_title = "Def Task Session"
+
+        # Mock async send to avoid subprocess
+        with patch.object(self.tui, "_async_send_message"):
+            self.tui._execute_input_line("Deploy updated service configuration")
+
+        # 'def' was chatted with directly; it must now be rank 1 at index 0
+        self.assertEqual(self.tui.data.nodes[0], "def", "Chat message send must promote target node to top of list")
+
+    def test_persistence_of_interactions(self):
+        """Verify interaction records persist and load from json correctly."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            fake_int_file = Path(tmpdir) / "agent_interactions.json"
+            now = time.time()
+            fake_int_file.write_text(json.dumps({"opm": now - 50, "dev": now - 10}))
+
+            with patch("pathlib.Path.home", return_value=Path(tmpdir)), \
+                 patch.object(muse_mod.Path, "home", return_value=Path(tmpdir)):
+                # Adjust path to match ~/.config/muse-cli/
+                cfg_dir = Path(tmpdir) / ".config" / "muse-cli"
+                cfg_dir.mkdir(parents=True, exist_ok=True)
+                (cfg_dir / "agent_interactions.json").write_text(json.dumps({"opm": now - 50, "dev": now - 10}))
+
+                mgr = muse_mod.FleetDataManager()
+                mgr.stop()  # Stop background poller
+
+                self.assertAlmostEqual(mgr.agent_interactions.get("dev", 0.0), now - 10, delta=1.0)
+                self.assertAlmostEqual(mgr.agent_interactions.get("opm", 0.0), now - 50, delta=1.0)
+                self.assertEqual(mgr.nodes[0], "dev", "Persisted recent node 'dev' must be rank 1")
+                self.assertEqual(mgr.nodes[1], "opm", "'opm' must be rank 2")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_approvals.py

@@ -29,6 +29,23 @@ class TestApprovalsModule(unittest.TestCase):
     def test_trusted_ips_configuration(self):
         self.assertIn("34.139.37.135", approvals.TRUSTED_IPS)
         self.assertIn("100.123.153.75", approvals.TRUSTED_IPS)
+        self.assertTrue(approvals.is_trusted_target("34.139.37.135"))
+        self.assertTrue(approvals.is_trusted_target("status.muse-dev.online"))
+        self.assertTrue(approvals.is_trusted_target("1.1.1.1"))
+        self.assertFalse(approvals.is_trusted_target("8.8.8.8"))
+        self.assertFalse(approvals.is_trusted_target("malicious-site.com"))
+        self.assertFalse(approvals.is_trusted_target("evilmuse-dev.online"))
+        self.assertFalse(approvals.is_trusted_target(
+            "evil.com", "operator-main wants to reach evil.com for status.muse-dev.online"))
+        self.assertFalse(approvals.is_trusted_target(None, "status.muse-dev.online"))
+
+    def test_redact_sensitive(self):
+        s1 = "Connecting with Bearer ya29.a0AfH6SMAKskd9238jdf"
+        self.assertEqual(approvals.redact_sensitive(s1), "Connecting with Bearer [REDACTED]")
+        s2 = "My api_key: secret12345678"
+        self.assertEqual(approvals.redact_sensitive(s2), "My api_key: [REDACTED]")
+        s3 = "JWT token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0"
+        self.assertIn("[JWT-REDACTED]", approvals.redact_sensitive(s3))
 
     def test_get_node_connection_info(self):
         info = approvals.get_node_connection_info("pip")
@@ -46,6 +63,7 @@ class TestApprovalsModule(unittest.TestCase):
             self.assertIn("has_pending", it)
             self.assertIn("buttons", it)
             self.assertIn("is_trusted", it)
+            self.assertIn("input_waits", it)
 
     def test_auto_approve_fleet_structure(self):
         res = approvals.auto_approve_fleet(nodes=["pip"])
@@ -124,5 +142,106 @@ class TestMuseChatApiConnection(unittest.TestCase):
         self.assertIn("No pending approvals", r.stdout)
 
 
+class TestApprovalsReplySafety(unittest.TestCase):
+    """Test reply policy enforcement on Main Chat."""
+
+    def test_reply_main_chat_refusal(self):
+        cmd = [sys.executable, str(BIN_DIR / "super-cli.py"), "approvals", "reply", "pip", "hello test"]
+        r = subprocess.run(cmd, capture_output=True, text=True)
+        # Should refuse with exit code 2 when target is Main Chat without --allow-main-chat
+        self.assertEqual(r.returncode, 2)
+        self.assertIn("Refusing reply by sidechat-first policy", r.stderr + r.stdout)
+
+
+class TestKeyApprovalsAndPasskey(unittest.TestCase):
+    """Test key approval workflow and passkey retrieval architecture."""
+
+    def test_request_and_resolve_key_approval(self):
+        req = approvals.request_key_approval("dev", reason="UnitTest passkey verification", caller="unit-test")
+        self.assertTrue(req.get("ok"))
+        self.assertEqual(req.get("node"), "dev")
+
+        # Verify active in check_node_key_request
+        pending = approvals.check_node_key_request("dev")
+        self.assertIsNotNone(pending)
+        self.assertEqual(pending.get("reason"), "UnitTest passkey verification")
+
+        # Inspect should report KEY_APPROVAL
+        info = approvals.inspect_node_approvals("dev")
+        self.assertEqual(info.get("status"), "KEY_APPROVAL")
+        self.assertTrue(info.get("has_pending"))
+
+        # Resolve via allow_node_approval
+        res = approvals.allow_node_approval("dev", caller="unit-test")
+        self.assertTrue(res.get("ok"))
+        self.assertEqual(res.get("type"), "key_approval")
+        self.assertEqual(res.get("decision"), "allow")
+
+        # After resolution, pending should be cleared
+        cleared = approvals.check_node_key_request("dev")
+        self.assertIsNone(cleared)
+
+    def test_box_passkey_info_json(self):
+        cmd = [sys.executable, str(BIN_DIR / "super-cli.py"), "passkey", "--json"]
+        r = subprocess.run(cmd, capture_output=True, text=True)
+        self.assertEqual(r.returncode, 0)
+        data = json.loads(r.stdout)
+        self.assertTrue(data.get("ok"))
+        self.assertEqual(data.get("operator_pin"), "3128")
+        self.assertIn("key_location", data)
+        self.assertIn("canonical_path", data["key_location"])
+        self.assertEqual(data["key_location"]["canonical_path"], "/srv/box/passkey.txt")
+
+    def test_box_passkey_fetch_json(self):
+        cmd = [sys.executable, str(BIN_DIR / "super-cli.py"), "passkey", "fetch", "--json"]
+        r = subprocess.run(cmd, capture_output=True, text=True)
+        self.assertEqual(r.returncode, 0)
+        data = json.loads(r.stdout)
+        self.assertIn("operator_pin", data)
+        self.assertEqual(data.get("operator_pin"), "3128")
+        self.assertEqual(data.get("vm_host"), "34.139.37.135")
+        self.assertEqual(data.get("path"), "/srv/box/passkey.txt")
+        self.assertIn("operator_command", data)
+
+    def test_box_lookup_key(self):
+        cmd = [sys.executable, str(BIN_DIR / "super-cli.py"), "lookup", "key", "--json"]
+        r = subprocess.run(cmd, capture_output=True, text=True)
+        self.assertEqual(r.returncode, 0)
+        data = json.loads(r.stdout)
+        self.assertTrue(data.get("ok"))
+        self.assertEqual(data.get("operator_pin"), "3128")
+
+    def test_cli_request_key_lifecycle(self):
+        # 1. Request key
+        r_req = subprocess.run([
+            sys.executable, str(BIN_DIR / "super-cli.py"),
+            "approvals", "request-key", "dev", "--reason", "CLI lifecycle test", "--json"
+        ], capture_output=True, text=True)
+        self.assertEqual(r_req.returncode, 0)
+        req_data = json.loads(r_req.stdout)
+        self.assertTrue(req_data.get("ok"))
+
+        # 2. Check shows KEY_APPROVAL
+        r_check = subprocess.run([
+            sys.executable, str(BIN_DIR / "super-cli.py"),
+            "approvals", "check", "--node", "dev", "--json"
+        ], capture_output=True, text=True)
+        self.assertEqual(r_check.returncode, 0)
+        check_data = json.loads(r_check.stdout)
+        dev_app = next(a for a in check_data["approvals"] if a["node"] == "dev")
+        self.assertEqual(dev_app["status"], "KEY_APPROVAL")
+
+        # 3. Deny key
+        r_deny = subprocess.run([
+            sys.executable, str(BIN_DIR / "super-cli.py"),
+            "approvals", "deny", "dev", "--json"
+        ], capture_output=True, text=True)
+        self.assertEqual(r_deny.returncode, 0)
+        deny_data = json.loads(r_deny.stdout)
+        self.assertTrue(deny_data.get("ok"))
+        self.assertEqual(deny_data.get("decision"), "deny")
+
+
 if __name__ == "__main__":
     unittest.main()
+

tests/test_blocked_approvals.py

@@ -0,0 +1,87 @@
+import unittest
+from unittest.mock import MagicMock, patch
+import importlib.util
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path("/home/super/Projects/NetVM")
+sys.path.insert(0, str(REPO_ROOT / "bin"))
+
+
+class TestBlockedApprovals(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        spec = importlib.util.spec_from_file_location("muse_tui", str(REPO_ROOT / "bin" / "muse-tui.py"))
+        cls.muse_tui = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(cls.muse_tui)
+
+    def setUp(self):
+        self.mock_stdscr = MagicMock()
+        self.mock_stdscr.getmaxyx.return_value = (40, 120)
+        self.app = self.muse_tui.MuseTUI(self.mock_stdscr, initial_mode="muse", initial_node="muse")
+        self.app.data = MagicMock()
+        self.app.data.nodes = ["muse", "pip", "646", "opm", "def", "dev"]
+        self.app.data.active_node = "muse"
+        self.app.data.active_thread_id = "thread-1"
+        self.app.data.active_thread_title = "Main Chat"
+        self.app.data.lock = MagicMock()
+        self.app.data.lock.__enter__.return_value = None
+        self.app.data.lock.__exit__.return_value = None
+
+    def test_slash_blocked_opens_approvals_modal(self):
+        self.app.data.approvals_cache = [
+            {"node": "opm", "status": "PENDING", "title": "Review task", "is_trusted": True},
+            {"node": "646", "status": "PENDING", "title": "SSH connect", "is_trusted": False},
+        ]
+        self.app._execute_input_line("/blocked")
+        self.assertEqual(self.app.modal, "approvals")
+        self.assertEqual(self.app.approvals_sel_idx, 0)
+
+        self.app._execute_input_line("/Blocked")
+        self.assertEqual(self.app.modal, "approvals")
+
+        self.app._execute_input_line("/approvals")
+        self.assertEqual(self.app.modal, "approvals")
+
+    def test_approvals_modal_navigation_and_targeting(self):
+        self.app.modal = "approvals"
+        self.app.approvals_sel_idx = 0
+        self.app.data.approvals_cache = [
+            {"node": "muse", "status": "PENDING", "title": "Task 1"},
+            {"node": "opm", "status": "PENDING", "title": "Task 2"},
+        ]
+
+        # Press 'j' (down)
+        handled = self.app._handle_modal_key(ord('j'))
+        self.assertTrue(handled)
+        self.assertEqual(self.app.approvals_sel_idx, 1)
+
+        # Press '1' (allow) -> should target 'opm' (selected row), not 'muse' (active_node)
+        with patch.object(self.app, "_async_resolve_approval") as mock_resolve:
+            handled = self.app._handle_modal_key(ord('1'))
+            self.assertTrue(handled)
+            self.assertIsNone(self.app.modal)
+            mock_resolve.assert_called_once_with("allow", "opm")
+
+    def test_approvals_modal_navigation_k(self):
+        self.app.modal = "approvals"
+        self.app.approvals_sel_idx = 1
+        self.app.data.approvals_cache = [
+            {"node": "muse", "status": "PENDING", "title": "Task 1"},
+            {"node": "opm", "status": "PENDING", "title": "Task 2"},
+        ]
+
+        # Press 'k' (up)
+        handled = self.app._handle_modal_key(ord('k'))
+        self.assertTrue(handled)
+        self.assertEqual(self.app.approvals_sel_idx, 0)
+
+        # Press '2' (always) -> should target 'muse'
+        with patch.object(self.app, "_async_resolve_approval") as mock_resolve:
+            handled = self.app._handle_modal_key(ord('2'))
+            self.assertTrue(handled)
+            mock_resolve.assert_called_once_with("always", "muse")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_clean_transcript.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+test_clean_transcript.py — Unit and integration tests for clean line-by-line transcript view:
+1. Default display style is 'clean' (no box borders, no bottom rules, no vertical pipe bars).
+2. Clean mode renders bullet header indicators (● AGENT, ▸ YOU) and 2-space indented body lines.
+3. Boxed mode retains classic ASCII/Unicode frames (┌──, │  , └───).
+4. Runtime style toggling via 'b' / 'B' hotkey in Normal mode.
+5. Slash commands: /clean, /boxed, /view, /compact.
+6. Selection and copy extraction (_copy_rendered_line_range) handles clean formatting seamlessly.
+7. Settings persistence in ~/.config/muse-cli/tui_settings.json.
+"""
+import curses
+import importlib.util
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+MUSE_TUI_PATH = REPO_ROOT / "bin" / "muse-tui.py"
+
+spec = importlib.util.spec_from_file_location("muse_tui", MUSE_TUI_PATH)
+muse_tui = importlib.util.module_from_spec(spec)
+sys.modules["muse_tui"] = muse_tui
+spec.loader.exec_module(muse_tui)
+
+MuseTUI = muse_tui.MuseTUI
+
+
+class TestCleanTranscript(unittest.TestCase):
+    def setUp(self):
+        self.mock_stdscr = MagicMock()
+        self.mock_stdscr.getmaxyx.return_value = (30, 100)
+        self.tui = MuseTUI(self.mock_stdscr, initial_mode="muse", initial_node="muse")
+        self.tui.safe_addstr = MagicMock()
+
+        self.messages = [
+            {
+                "role": "assistant",
+                "text": "Same sweep thread, routine — holding on dev-i04.\nSecond line of response.",
+                "message_id": "ast-msg-86648",
+                "seq": 86648,
+            },
+            {
+                "role": "user",
+                "text": "Roger that, continue monitoring.\n[WO:20261006-1] Active",
+                "message_id": "usr-msg-d183a734",
+                "seq": 86649,
+            },
+        ]
+        with self.tui.data.lock:
+            self.tui.data.history_cache[(self.tui.data.active_node, self.tui.data.active_thread_id)] = self.messages
+
+    def test_default_style_is_clean(self):
+        """Verify that newly initialized TUI defaults to 'clean' transcript style."""
+        self.assertEqual(self.tui.transcript_style, "clean")
+
+    def test_render_transcript_clean_mode(self):
+        """In 'clean' mode, lines do NOT contain ┌──, │  , or └───, and use clean bullets."""
+        self.tui.transcript_style = "clean"
+        self.tui._transcript_cache_key = None
+        self.tui._render_transcript(1, 0, 25, 90)
+
+        lines = [item[0] for item in self.tui._transcript_cache_lines]
+        combined = "\n".join(lines)
+
+        # Must not contain box border frames
+        self.assertNotIn("┌──", combined)
+        self.assertNotIn("└──", combined)
+        self.assertNotIn("│  ", combined)
+
+        # Must contain clean indicators
+        self.assertTrue(any(l.startswith("● MUSE") for l in lines), "Agent header must start with clean bullet ●")
+        self.assertTrue(any(l.startswith("▸ YOU") for l in lines), "User header must start with clean prompt ▸")
+
+        # Body lines must use 2-space indentation
+        self.assertTrue(any(l.startswith("  Same sweep thread") for l in lines))
+        self.assertTrue(any(l.startswith("  Second line") for l in lines))
+        self.assertTrue(any(l.startswith("  Roger that") for l in lines))
+
+    def test_render_transcript_boxed_mode(self):
+        """In 'boxed' mode, classic ASCII/Unicode frames (┌──, │  , └───) are rendered."""
+        self.tui.transcript_style = "boxed"
+        self.tui._transcript_cache_key = None
+        self.tui._render_transcript(1, 0, 25, 90)
+
+        lines = [item[0] for item in self.tui._transcript_cache_lines]
+        combined = "\n".join(lines)
+
+        self.assertIn("┌── [MUSE / MUSE AGENT]", combined)
+        self.assertIn("┌── [YOU / OPERATOR]", combined)
+        self.assertIn("│  Same sweep thread", combined)
+        self.assertIn("└──", combined)
+
+    def test_toggle_transcript_style(self):
+        """toggle_transcript_style switches between clean and boxed, invalidating cache."""
+        self.tui.transcript_style = "clean"
+        self.tui._transcript_cache_key = ("some_key",)
+
+        self.tui.toggle_transcript_style()
+        self.assertEqual(self.tui.transcript_style, "boxed")
+        self.assertIsNone(self.tui._transcript_cache_key)
+        self.assertIn("Classic boxed", self.tui.toast_msg)
+
+        self.tui.toggle_transcript_style()
+        self.assertEqual(self.tui.transcript_style, "clean")
+        self.assertIsNone(self.tui._transcript_cache_key)
+        self.assertIn("Clean line-by-line", self.tui.toast_msg)
+
+    def test_normal_mode_hotkey_b_toggles_style(self):
+        """Pressing 'b' or 'B' in normal mode toggles transcript style."""
+        self.tui.editor_mode = "NORMAL"
+        self.tui.copy_mode = False
+        self.tui.transcript_style = "clean"
+
+        handled = self.tui._handle_key(ord('b'))
+        self.assertTrue(handled)
+        self.assertEqual(self.tui.transcript_style, "boxed")
+
+        handled = self.tui._handle_key(ord('B'))
+        self.assertTrue(handled)
+        self.assertEqual(self.tui.transcript_style, "clean")
+
+    def test_slash_commands_clean_and_boxed(self):
+        """Slash commands /clean, /boxed, and /view correctly set style."""
+        self.tui.transcript_style = "clean"
+
+        # /boxed
+        self.tui._execute_input_line("/boxed")
+        self.assertEqual(self.tui.transcript_style, "boxed")
+
+        # /clean
+        self.tui._execute_input_line("/clean")
+        self.assertEqual(self.tui.transcript_style, "clean")
+
+        # /view box
+        self.tui._execute_input_line("/view box")
+        self.assertEqual(self.tui.transcript_style, "boxed")
+
+        # /view clean
+        self.tui._execute_input_line("/view clean")
+        self.assertEqual(self.tui.transcript_style, "clean")
+
+        # /style (toggles)
+        self.tui._execute_input_line("/style")
+        self.assertEqual(self.tui.transcript_style, "boxed")
+
+    def test_copy_range_in_clean_mode(self):
+        """_copy_rendered_line_range strips clean 2-space indents and action buttons."""
+        self.tui.transcript_style = "clean"
+        self.tui._transcript_cache_key = None
+        self.tui._render_transcript(1, 0, 25, 90)
+
+        # Total lines in cache
+        lines = self.tui._transcript_cache_lines
+        copied = self.tui._copy_rendered_line_range(0, len(lines) - 1)
+
+        self.assertNotIn("│", copied)
+        self.assertNotIn("[📋 Copy]", copied)
+        self.assertNotIn("[↩ Reply]", copied)
+        self.assertIn("Same sweep thread", copied)
+        self.assertIn("Roger that, continue monitoring.", copied)
+
+    def test_settings_persistence(self):
+        """Style preference is saved to and loaded from JSON configuration."""
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            fake_cfg = Path(tmp_dir) / "tui_settings.json"
+            with patch("pathlib.Path.home", return_value=Path(tmp_dir)):
+                with patch.object(Path, "mkdir"):
+                    with patch("builtins.open", unittest.mock.mock_open()):
+                        self.tui.set_transcript_style("boxed")
+                        self.assertEqual(self.tui.transcript_style, "boxed")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_completion.py

@@ -0,0 +1,366 @@
+"""Tests for the completion-enforcement loop: on_no_result fallbacks,
+proof-of-result followups, the NACK acted-variant, and the auditor funnel."""
+import importlib.util
+import json
+import sys
+import types
+import unittest
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+def _load(mod_name, rel_path):
+    spec = importlib.util.spec_from_file_location(mod_name, REPO_ROOT / rel_path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+sw = _load("sweeper_completion", "bin/followup-sweeper.py")
+harv = _load("harvester_completion", "bin/response-harvester.py")
+aud = _load("completion_audit_mod", "bin/completion-audit.py")
+grav = _load("gravity_completion", "bin/gravity.py")
+
+
+class DeriveJobName(unittest.TestCase):
+    def test_valid(self):
+        self.assertEqual(
+            sw.derive_job_name("autonomy-pulse-646-20261006-060000-ed9a26af"),
+            "autonomy-pulse-646",
+        )
+
+    def test_invalid_shapes(self):
+        for bad in (None, "", "nonsense", "job-2026-1-abc",
+                    "nonexistent-job-20261006-060000-ed9a26af"):
+            self.assertIsNone(sw.derive_job_name(bad), bad)
+
+
+class LoadJobFallback(unittest.TestCase):
+    def test_seeded_pulse_jobs(self):
+        for name in ("autonomy-pulse-646", "autonomy-pulse-pip",
+                     "autonomy-pulse-opm"):
+            spec, err = sw.load_job_fallback(name)
+            self.assertIsNone(err, name)
+            self.assertIsNotNone(spec, name)
+            self.assertEqual(spec["op"], "swarm.spawn")
+            self.assertEqual(spec["args"]["count"], 2)
+
+    def test_absent_is_none(self):
+        spec, err = sw.load_job_fallback("646-daily-checkin")
+        self.assertIsNone(spec)
+        self.assertIsNone(err)
+
+
+class RunNoResultFallback(unittest.TestCase):
+    def test_unresolvable_rec(self):
+        out = sw.run_no_result_fallback({"dm_id": "x"})
+        self.assertFalse(out["ran"])
+        self.assertFalse(out["configured"])
+
+    def test_job_without_spec(self):
+        out = sw.run_no_result_fallback(
+            {"dm_id": "x", "job_id": "646-daily-checkin-20261006-090000-abcdef12",
+             "recipient": "646"})
+        self.assertFalse(out["ran"])
+        self.assertFalse(out["configured"])
+
+    def test_dry_run_marks_configured(self):
+        out = sw.run_no_result_fallback(
+            {"dm_id": "x",
+             "job_id": "autonomy-pulse-646-20261006-060000-ed9a26af",
+             "recipient": "646"},
+            dry_run=True)
+        self.assertTrue(out["configured"])
+        self.assertFalse(out["ran"])
+
+    def test_op_path_uses_validated_build(self):
+        calls = {}
+
+        class FakeOpError(Exception):
+            pass
+
+        def fake_validate(args):
+            calls["validated"] = dict(args)
+            return {"echo": "yes"}
+
+        def fake_build(clean):
+            calls["built"] = clean
+            return ["/bin/echo", "fallback-ok"]
+
+        fake_mod = types.SimpleNamespace(
+            OPS={"probe.op": {"validate": fake_validate, "build": fake_build,
+                              "timeout": 10}})
+        orig_exec, orig_load, orig_derive = (
+            sw._load_exec_ops, sw.load_job_fallback, sw.derive_job_name)
+        sw._load_exec_ops = lambda: fake_mod
+        sw.load_job_fallback = lambda name: (
+            ({"op": "probe.op", "args": {"a": 1}}, None))
+        sw.derive_job_name = lambda jid: "autonomy-pulse-646"
+        try:
+            out = sw.run_no_result_fallback(
+                {"dm_id": "x", "job_id": "whatever", "recipient": "646"})
+        finally:
+            sw._load_exec_ops, sw.load_job_fallback, sw.derive_job_name = (
+                orig_exec, orig_load, orig_derive)
+        self.assertTrue(out["ran"], out)
+        self.assertEqual(out["mode"], "op")
+        self.assertEqual(calls["validated"], {"a": 1})
+        self.assertEqual(calls["built"], {"echo": "yes"})
+        self.assertIn("fallback-ok", out["detail"])
+
+    def test_unknown_op_is_outcome_not_raise(self):
+        orig_exec, orig_load, orig_derive = (
+            sw._load_exec_ops, sw.load_job_fallback, sw.derive_job_name)
+        sw._load_exec_ops = lambda: types.SimpleNamespace(OPS={})
+        sw.load_job_fallback = lambda name: ({"op": "nope.nope"}, None)
+        sw.derive_job_name = lambda jid: "autonomy-pulse-646"
+        try:
+            out = sw.run_no_result_fallback(
+                {"dm_id": "x", "job_id": "whatever", "recipient": "646"})
+        finally:
+            sw._load_exec_ops, sw.load_job_fallback, sw.derive_job_name = (
+                orig_exec, orig_load, orig_derive)
+        self.assertTrue(out["configured"])
+        self.assertFalse(out["ran"])
+        self.assertIn("unknown op", out["detail"])
+
+
+class FallbackDue(unittest.TestCase):
+    def test_fresh_record_due(self):
+        self.assertTrue(sw.fallback_due({"dm_id": "x"}))
+
+    def test_ran_never_due(self):
+        self.assertFalse(sw.fallback_due(
+            {"fallback": {"ran": True, "ts": "2026-10-06T00:00:00+00:00"}}))
+
+    def test_failed_recent_not_due(self):
+        from datetime import datetime, timezone, timedelta
+        ts = (datetime.now(timezone.utc) - timedelta(minutes=5)).isoformat()
+        self.assertFalse(sw.fallback_due(
+            {"fallback": {"ran": False, "ts": ts}}))
+
+    def test_failed_old_due(self):
+        self.assertTrue(sw.fallback_due(
+            {"fallback": {"ran": False, "ts": "2026-10-05T00:00:00+00:00"}}))
+
+
+class GravityFallback(unittest.TestCase):
+    def test_dry_run_configured(self):
+        rec = {"dm_id": "x",
+               "job_id": "autonomy-pulse-646-20261006-060000-ed9a26af",
+               "recipient": "646"}
+        out = grav.maybe_run_terminal_fallback(
+            rec, "2026-10-06T08:00:00+00:00", dry_run=True)
+        self.assertIsNotNone(out)
+        self.assertFalse(out["ran"])
+        self.assertNotIn("fallback", rec)
+
+    def test_no_spec_returns_none(self):
+        rec = {"dm_id": "x",
+               "job_id": "646-daily-checkin-20261006-090000-abcdef12",
+               "recipient": "646"}
+        self.assertIsNone(grav.maybe_run_terminal_fallback(
+            rec, "2026-10-06T08:00:00+00:00", dry_run=True))
+
+    def test_already_ran_returns_none(self):
+        rec = {"dm_id": "x",
+               "job_id": "autonomy-pulse-646-20261006-060000-ed9a26af",
+               "recipient": "646",
+               "fallback": {"ran": True, "ts": "2026-10-06T07:00:00+00:00"}}
+        self.assertIsNone(grav.maybe_run_terminal_fallback(
+            rec, "2026-10-06T08:00:00+00:00", dry_run=True))
+
+
+class GravityEntry(unittest.TestCase):
+    def test_no_args_prints_help(self):
+        import io
+        from contextlib import redirect_stdout
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = grav.main([])
+        self.assertEqual(rc, 2)
+        self.assertIn("remediate", buf.getvalue())
+
+    def test_remediate_dry_run_returns_json(self):
+        import io
+        from contextlib import redirect_stdout
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = grav.main(["--remediate", "--dry-run"])
+        self.assertEqual(rc, 0)
+        data = json.loads(buf.getvalue())
+        self.assertTrue(data["ok"])
+        self.assertTrue(data["dry_run"])
+
+
+class ResultEvidence(unittest.TestCase):
+    def test_positives(self):
+        for text in (
+            "done, swarm sw-20261006-060000-ab12 reported 2/2",
+            "wrote /tmp/out.json with 40 rows",
+            "timer id: pulse-15m restarted",
+            "thread 1dfb3199-2f99-446c-83e3-848ae2da0a12 swept",
+            "3/3 slots complete",
+        ):
+            self.assertTrue(harv.result_has_evidence(text), text)
+
+    def test_negatives(self):
+        for text in ("OK all good", "done, nothing to report", "", None):
+            self.assertFalse(harv.result_has_evidence(text), repr(text))
+
+
+class ProofRequest(unittest.TestCase):
+    def _patch(self, tmp_path):
+        orig = (harv.NUDGE_TRACKER_FILE, harv.JOB_LOG, harv.execute_agent_tool)
+        harv.NUDGE_TRACKER_FILE = tmp_path / "tracker.json"
+        harv.JOB_LOG = tmp_path / "job-log.jsonl"
+        calls = []
+        harv.execute_agent_tool = lambda a, op, args: (
+            calls.append((a, op, args)), (True, "scheduled"))[1]
+        return orig, calls
+
+    def test_bare_result_schedules_proof(self):
+        import tempfile
+        with tempfile.TemporaryDirectory() as td:
+            orig, calls = self._patch(Path(td))
+            try:
+                ok = harv.maybe_request_proof(
+                    "646", "1dfb3199-2f99-446c-83e3-848ae2da0a12",
+                    "job-1", "OK all good")
+            finally:
+                (harv.NUDGE_TRACKER_FILE, harv.JOB_LOG,
+                 harv.execute_agent_tool) = orig
+        self.assertTrue(ok)
+        self.assertEqual(calls[0][1], "followup.create")
+        self.assertEqual(calls[0][2]["in_m"], 30)
+        self.assertIn("PROOF", calls[0][2]["prompt"])
+
+    def test_evidence_skips(self):
+        ok = harv.maybe_request_proof(
+            "646", "1dfb3199-2f99-446c-83e3-848ae2da0a12",
+            "job-1", "done, swarm sw-20261006-060000-ab12")
+        self.assertFalse(ok)
+
+    def test_bad_thread_and_dry_run_skip(self):
+        self.assertFalse(harv.maybe_request_proof(
+            "646", "main", "job-1", "OK"))
+        self.assertFalse(harv.maybe_request_proof(
+            "646", "1dfb3199-2f99-446c-83e3-848ae2da0a12",
+            "job-1", "OK", dry_run=True))
+
+    def test_one_shot_per_job(self):
+        import tempfile
+        with tempfile.TemporaryDirectory() as td:
+            orig, calls = self._patch(Path(td))
+            try:
+                kw = dict(agent="646",
+                          thread_id="1dfb3199-2f99-446c-83e3-848ae2da0a12",
+                          job_id="job-9", result_text="OK")
+                self.assertTrue(harv.maybe_request_proof(**kw))
+                self.assertFalse(harv.maybe_request_proof(**kw))
+            finally:
+                (harv.NUDGE_TRACKER_FILE, harv.JOB_LOG,
+                 harv.execute_agent_tool) = orig
+        self.assertEqual(len(calls), 1)
+
+
+class NackActedVariant(unittest.TestCase):
+    def test_acted_variant_text(self):
+        import tempfile
+        sent = []
+        fake = types.ModuleType("muse_hybrid")
+        fake.send_message = lambda a, m, thread_id=None, wait=0: sent.append(m)
+        with tempfile.TemporaryDirectory() as td:
+            tp = Path(td)
+            (tp / "followups.json").write_text(json.dumps({
+                "m1": {"status": "pending",
+                       "thread_uuid": "1dfb3199-2f99-446c-83e3-848ae2da0a12",
+                       "job_id": "job-7", "recipient": "646"}}))
+            orig = (harv.NUDGE_TRACKER_FILE, harv.FOLLOWUPS_FILE,
+                    sys.modules.get("muse_hybrid"))
+            harv.NUDGE_TRACKER_FILE = tp / "tracker.json"
+            harv.FOLLOWUPS_FILE = tp / "followups.json"
+            sys.modules["muse_hybrid"] = fake
+            try:
+                harv.maybe_nudge_untagged_sidechat(
+                    "646", "1dfb3199-2f99-446c-83e3-848ae2da0a12",
+                    "646 tasks", "mid-1", "some prose", acted=True)
+            finally:
+                (harv.NUDGE_TRACKER_FILE, harv.FOLLOWUPS_FILE,
+                 old_mod) = orig
+                if old_mod is None:
+                    sys.modules.pop("muse_hybrid", None)
+                else:
+                    sys.modules["muse_hybrid"] = old_mod
+        self.assertEqual(len(sent), 1)
+        self.assertIn("Action received", sent[0])
+        self.assertIn("[RESULT job-7]", sent[0])
+        self.assertNotIn("STRICT ENFORCEMENT", sent[0])
+
+
+class AuditorFunnel(unittest.TestCase):
+    def _events(self):
+        base = "2026-10-06T07:00:00+00:00"
+        return [
+            {"ts": base, "type": "job_sent",
+             "job_id": "work-finder-20261006-070000-aaaaaaaa"},
+            {"ts": base, "type": "job_dispatched",
+             "job_id": "work-finder-20261006-070000-aaaaaaaa"},
+            {"ts": base, "type": "tool_exec", "op": "swarm.spawn",
+             "success": True},
+            {"ts": base, "type": "job_result",
+             "job_id": "work-finder-20261006-070000-aaaaaaaa",
+             "success": True},
+            {"ts": base, "type": "job_sent",
+             "job_id": "pulse-20261006-070000-bbbbbbbb"},
+            {"ts": base, "type": "job_failed",
+             "job_id": "pulse-20261006-070000-bbbbbbbb"},
+        ]
+
+    def test_funnel_counts(self):
+        from datetime import datetime, timezone
+        fam, tools = aud.compute_funnel(
+            self._events(), datetime(2026, 10, 6, 6, 0, tzinfo=timezone.utc))
+        self.assertEqual(fam["work-finder"]["sent"], 1)
+        self.assertEqual(fam["work-finder"]["results"], 1)
+        self.assertEqual(fam["pulse"]["failed"], 1)
+        self.assertEqual(tools["tools"]["total"], 1)
+        self.assertEqual(tools["tools"]["ok"], 1)
+
+    def test_family_of(self):
+        self.assertEqual(aud.family_of("a-b-20261006-070000-aaaaaaaa"), "a-b")
+        self.assertEqual(aud.family_of("weird"), "weird")
+
+    def test_digest_verdicts(self):
+        healthy = {"ts": "2026-10-06T07:00:00+00:00", "window_h": 6,
+                   "totals": {"sent": 4, "dispatched": 4, "results": 4,
+                              "ok": 4},
+                   "tools": {"tools": {"total": 3, "ok": 3}, "tool_errs": {}},
+                   "families": {}, "silent_families": [], "swarms": {},
+                   "stale_running": [], "followups": {"pending": 1},
+                   "degraded": False, "reasons": []}
+        out = aud.render_digest(healthy)
+        self.assertIn("HEALTHY", out)
+        self.assertIn("4 sent", out)
+        bad = dict(healthy, degraded=True,
+                   reasons=["1 silent families: x"],
+                   silent_families=["x"])
+        self.assertIn("DEGRADED", aud.render_digest(bad))
+
+    def test_should_post_policy(self):
+        import tempfile
+        with tempfile.TemporaryDirectory() as td:
+            orig = aud.STATE_FILE
+            aud.STATE_FILE = Path(td) / "state.json"
+            try:
+                self.assertTrue(aud.should_post({"degraded": True})[0])
+                ok, why = aud.should_post({"degraded": False})
+                self.assertTrue(ok)
+                self.assertEqual(why, "heartbeat")
+            finally:
+                aud.STATE_FILE = orig
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_context_menus.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""
+test_context_menus.py — Unit and integration tests for Right-Click function(s)
+and Context Action Menus in NetVM/Muse TUI:
+1. Right-click on Chat List (sidebar sidechats/threads) opens `chat_context` menu.
+2. Right-click on Fleet Agents panel opens `agent_context` menu.
+3. Right-click on Transcript message opens `message_context` menu.
+4. Chat Context Menu actions (Open, Pin/Unpin, Mark as Read, Copy ID, Copy URL, Reply, Close).
+5. Fleet Agent Context Menu actions (Open, Sync, Approvals, Mark All Read, Tmux, Work Order).
+6. Message Context Menu actions (Reply, Copy Text, Pin to Prompts, Copy ID).
+7. Keyboard navigation (j/k, 1-8, Enter) and mouse click selection inside context menus.
+8. Normal mode hotkeys ('x' / 'c') and slash commands (/context chat, /context agent).
+"""
+import curses
+import importlib.util
+import os
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+MUSE_TUI_PATH = REPO_ROOT / "bin" / "muse-tui.py"
+
+spec = importlib.util.spec_from_file_location("muse_tui", MUSE_TUI_PATH)
+muse_tui = importlib.util.module_from_spec(spec)
+sys.modules["muse_tui"] = muse_tui
+spec.loader.exec_module(muse_tui)
+
+MuseTUI = muse_tui.MuseTUI
+
+
+class TestContextMenus(unittest.TestCase):
+    def setUp(self):
+        self.mock_stdscr = MagicMock()
+        self.mock_stdscr.getmaxyx.return_value = (30, 100)
+        self.tui = MuseTUI(self.mock_stdscr, initial_mode="muse", initial_node="muse")
+        self.tui.safe_addstr = MagicMock()
+
+        # Seed mock threads
+        self.threads = [
+            {"session_id": "sess-main-1234", "title": "Main Chat", "is_main": True, "pinned": False},
+            {"session_id": "sess-side-5678", "title": "Audit Sidechat", "is_main": False, "pinned": True},
+            {"session_id": "sess-side-9999", "title": "Dev Sidechat", "is_main": False, "pinned": False},
+        ]
+        with self.tui.data.lock:
+            self.tui.data.pinned_threads["muse"] = set()
+            self.tui.data.threads_cache["muse"] = list(self.threads)
+            self.tui.data.active_thread_id = "sess-main-1234"
+            self.tui.data.active_thread_title = "Main Chat"
+            self.tui.data.history_cache[("muse", "sess-main-1234")] = [
+                {"role": "user", "text": "Hello muse", "seq": 1, "message_id": "mid-user-1"},
+                {"role": "assistant", "text": "System ready", "seq": 2, "message_id": "mid-agent-2"},
+            ]
+            self.tui.data.history_cache[("muse", "sess-side-5678")] = [
+                {"role": "user", "text": "Review log", "seq": 3, "message_id": "mid-user-3"},
+            ]
+
+    def test_right_click_on_chat_list_opens_chat_context(self):
+        """Right-clicking a thread row in sidebar opens chat_context modal."""
+        # Screen layout: content_y = 1, visible_agents = 6, divider_y = 8, threads_hdr_y = 9, list_y = 10
+        # Right click on thread index 1 (sess-side-5678) at my = 11, mx = 10
+        bstate = curses.BUTTON3_CLICKED
+        self.tui._handle_mouse(mx=10, my=11, bstate=bstate)
+
+        self.assertEqual(self.tui.modal, "chat_context")
+        self.assertIsNotNone(self.tui.context_chat)
+        self.assertEqual(self.tui.context_chat["thread"]["session_id"], "sess-side-5678")
+        self.assertEqual(self.tui.context_chat["thread"]["title"], "Audit Sidechat")
+
+    def test_right_click_on_fleet_agent_opens_agent_context(self):
+        """Right-clicking an agent row in sidebar opens agent_context modal."""
+        # Row content_y + 1 = 2 is first agent (index 0 = 'muse')
+        # Row content_y + 2 = 3 is second agent
+        bstate = getattr(curses, "BUTTON3_PRESSED", 0x800)
+        with self.tui.data.lock:
+            second_agent = self.tui.data.nodes[1] if len(self.tui.data.nodes) > 1 else "muse"
+
+        self.tui._handle_mouse(mx=10, my=3, bstate=bstate)
+
+        self.assertEqual(self.tui.modal, "agent_context")
+        self.assertIsNotNone(self.tui.context_agent)
+        self.assertEqual(self.tui.context_agent["node"], second_agent)
+
+    def test_right_click_on_transcript_opens_message_context(self):
+        """Right-clicking a message in transcript opens message_context modal."""
+        # Populate rendered lines in transcript
+        self.tui._render_transcript(1, 26, 25, 74)
+        # Click on transcript area mx = 50, my = 5
+        bstate = curses.BUTTON3_CLICKED
+        self.tui._handle_mouse(mx=50, my=5, bstate=bstate)
+
+        self.assertEqual(self.tui.modal, "message_context")
+        self.assertIsNotNone(self.tui.context_message)
+        self.assertIn("text", self.tui.context_message)
+
+    def test_chat_context_pin_action(self):
+        """Executing 'pin' action in chat_context toggles pin state."""
+        t = {"session_id": "sess-side-9999", "title": "Dev Sidechat", "pinned": False}
+        self.tui.context_chat = {"node": "muse", "thread": t, "index": 2}
+        self.tui.modal = "chat_context"
+
+        # Press 'p'
+        self.tui._handle_modal_key(ord('p'))
+        self.assertIsNone(self.tui.modal)
+        self.assertIn("📌 Pinned chat", self.tui.toast_msg)
+        self.assertIn("sess-side-9999", self.tui.data.pinned_threads.get("muse", set()))
+
+    def test_chat_context_mark_read_action(self):
+        """Executing 'read' action marks thread as read."""
+        t = {"session_id": "sess-side-5678", "title": "Audit Sidechat"}
+        self.tui.context_chat = {"node": "muse", "thread": t, "index": 1}
+        self.tui.modal = "chat_context"
+
+        self.tui._handle_modal_key(ord('m'))
+        self.assertIsNone(self.tui.modal)
+        self.assertIn("Marked 'Audit Sidechat' as read", self.tui.toast_msg)
+        self.assertEqual(self.tui.data.get_unread_count("muse", "sess-side-5678"), 0)
+
+    def test_chat_context_copy_id_action(self):
+        """Executing 'copy_id' action copies session ID to clipboard."""
+        t = {"session_id": "sess-side-5678", "title": "Audit Sidechat"}
+        self.tui.context_chat = {"node": "muse", "thread": t, "index": 1}
+        self.tui.modal = "chat_context"
+
+        mod = sys.modules.get(MuseTUI.__module__, muse_tui)
+        with patch.object(mod, "copy_to_clipboard") as mock_cp1, \
+             patch.object(muse_tui, "copy_to_clipboard") as mock_cp2:
+            self.tui._handle_modal_key(ord('y'))
+            self.assertTrue(mock_cp1.called or mock_cp2.called)
+            self.assertIn("Copied session ID", self.tui.toast_msg)
+
+    def test_chat_context_reply_action(self):
+        """Executing 'reply' action switches to chat and quotes latest message."""
+        t = {"session_id": "sess-main-1234", "title": "Main Chat"}
+        self.tui.context_chat = {"node": "muse", "thread": t, "index": 0}
+        self.tui.modal = "chat_context"
+
+        self.tui._handle_modal_key(ord('r'))
+        self.assertIsNone(self.tui.modal)
+        self.assertIsNotNone(self.tui.reply_target)
+        self.assertEqual(self.tui.reply_target["role"], "assistant")
+        self.assertIn("System ready", self.tui.reply_target["text"])
+
+    def test_agent_context_actions(self):
+        """Agent context menu hotkeys execute appropriate agent actions."""
+        self.tui.context_agent = {"node": "muse"}
+        self.tui.modal = "agent_context"
+
+        # Mark all chats on agent as read ('m')
+        self.tui._handle_modal_key(ord('m'))
+        self.assertIsNone(self.tui.modal)
+        self.assertIn("Marked all chats on MUSE as read", self.tui.toast_msg)
+
+        # Open chat with agent ('1')
+        self.tui.context_agent = {"node": "muse"}
+        self.tui.modal = "agent_context"
+        self.tui._handle_modal_key(ord('1'))
+        self.assertIsNone(self.tui.modal)
+        self.assertIn("Switched to agent", self.tui.toast_msg)
+
+    def test_normal_mode_x_opens_chat_context(self):
+        """Pressing 'x' in normal mode when focused on sidebar opens chat_context."""
+        self.tui.editor_mode = "NORMAL"
+        self.tui.focus_pane = "sidebar"
+        self.tui.thread_sel_idx = 1
+
+        handled = self.tui._handle_key(ord('x'))
+        self.assertTrue(handled)
+        self.assertEqual(self.tui.modal, "chat_context")
+        self.assertEqual(self.tui.context_chat["thread"]["session_id"], "sess-side-5678")
+
+    def test_slash_command_context(self):
+        """Slash command /context opens chat_context or agent_context."""
+        self.tui._execute_input_line("/context chat")
+        self.assertEqual(self.tui.modal, "chat_context")
+
+        self.tui.modal = None
+        self.tui._execute_input_line("/context agent")
+        self.assertEqual(self.tui.modal, "agent_context")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_copy_actions.py

@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+"""
+test_copy_actions.py — Unit and integration tests for:
+1. Multi-environment clipboard engine (desktop utilities, OSC 52, internal buffer).
+2. Transcript formatting engine (Markdown structured headers, roles, seq, id).
+3. UI-first button approach:
+   - Clickable [📋 Copy All] in thread header.
+   - Clickable [📋 Copy] button on each message header.
+4. Normal mode hotkeys:
+   - 'y': copy latest/active message to clipboard.
+   - 'Y': copy entire chat transcript to clipboard.
+5. Slash commands:
+   - '/copy', '/yank', '/cp': copy full transcript.
+   - '/copy last', '/copy message': copy latest message.
+"""
+import curses
+import importlib.util
+import os
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+MUSE_TUI_PATH = REPO_ROOT / "bin" / "muse-tui.py"
+
+spec = importlib.util.spec_from_file_location("muse_tui", MUSE_TUI_PATH)
+muse_tui = importlib.util.module_from_spec(spec)
+sys.modules["muse_tui"] = muse_tui
+spec.loader.exec_module(muse_tui)
+
+MuseTUI = muse_tui.MuseTUI
+copy_to_clipboard = muse_tui.copy_to_clipboard
+strip_message_metadata = muse_tui.strip_message_metadata
+
+
+class TestCopyActions(unittest.TestCase):
+    def setUp(self):
+        self.mock_stdscr = MagicMock()
+        self.mock_stdscr.getmaxyx.return_value = (30, 100)
+        self.tui = MuseTUI(self.mock_stdscr, initial_mode="muse", initial_node="muse")
+        self.tui.safe_addstr = MagicMock()
+
+        # Seed conversation history for testing
+        self.messages = [
+            {
+                "role": "user",
+                "text": "Hello muse, check system status",
+                "message_id": "usr-msg-12345678",
+                "seq": 1,
+            },
+            {
+                "role": "assistant",
+                "text": "All services nominal.\nCDP port 9222 active.",
+                "message_id": "ast-msg-87654321",
+                "seq": 2,
+            },
+            {
+                "role": "user",
+                "text": "Please summarize logs",
+                "message_id": "usr-msg-99999999",
+                "seq": 3,
+            },
+        ]
+        self.tui.data.history_cache[("muse", "thread-abc")] = list(self.messages)
+        self.tui.data.active_node = "muse"
+        self.tui.data.active_thread_id = "thread-abc"
+        self.tui.data.active_thread_title = "Diagnostics"
+
+    def test_strip_message_metadata(self):
+        """Verify strip_message_metadata strips reply headers and unquotes quoted lines."""
+        raw = (
+            "> Replying to ASSISTANT (seq:12620):\n"
+            "> Relevant to the timer question: the loop scout just surfaced 6 unanswered jobs.\n"
+            "> So part of getting work done is already queued.\n\n"
+            "yes, proceed with spawning 5 sub agents to assist you ; continue at all costs"
+        )
+        expected = (
+            "Relevant to the timer question: the loop scout just surfaced 6 unanswered jobs.\n"
+            "So part of getting work done is already queued.\n\n"
+            "yes, proceed with spawning 5 sub agents to assist you ; continue at all costs"
+        )
+        self.assertEqual(strip_message_metadata(raw), expected)
+
+        # Message without reply tags remains unchanged
+        no_tags = "Standard message without reply headers."
+        self.assertEqual(strip_message_metadata(no_tags), no_tags)
+
+    def test_copy_to_clipboard_osc52(self):
+        """Verify copy_to_clipboard formats and flushes OSC 52 sequence."""
+        with patch("sys.stdout.write") as mock_write, patch("sys.stdout.flush"):
+            ok = copy_to_clipboard("test-copy-payload")
+            self.assertTrue(ok)
+            # Verify OSC 52 sequence was written
+            args = [call.args[0] for call in mock_write.call_args_list]
+            osc_written = any("\033]52;c;" in a for a in args)
+            self.assertTrue(osc_written)
+
+    def test_get_formatted_transcript_content(self):
+        """Verify structured Markdown output contains thread title, roles, seq, id, and text."""
+        formatted = self.tui.get_formatted_transcript()
+        self.assertIn("# Chat Transcript: Diagnostics", formatted)
+        self.assertIn("Node: MUSE | Thread ID: thread-abc | Total Messages: 3", formatted)
+        self.assertIn("### [YOU / OPERATOR] id:usr-msg-", formatted)
+        self.assertIn("Hello muse, check system status", formatted)
+        self.assertIn("### [MUSE / MUSE AGENT] seq:2 id:ast-msg-", formatted)
+        self.assertIn("All services nominal.", formatted)
+        self.assertIn("Please summarize logs", formatted)
+
+    def test_copy_transcript_to_clipboard(self):
+        """Verify copy_transcript_to_clipboard updates internal buffer and sets success toast."""
+        with patch.object(muse_tui, "copy_to_clipboard", return_value=True):
+            ok = self.tui.copy_transcript_to_clipboard()
+            self.assertTrue(ok)
+            self.assertIn("# Chat Transcript: Diagnostics", self.tui.clipboard_buf)
+            self.assertIn("Copied full transcript (3 msgs", self.tui.toast_msg)
+
+    def test_copy_message_to_clipboard_latest(self):
+        """Verify copy_message_to_clipboard defaults to latest message."""
+        with patch.object(muse_tui, "copy_to_clipboard", return_value=True):
+            ok = self.tui.copy_message_to_clipboard()
+            self.assertTrue(ok)
+            self.assertEqual(self.tui.clipboard_buf, "Please summarize logs")
+            self.assertIn("Copied clean message to clipboard", self.tui.toast_msg)
+
+    def test_copy_message_to_clipboard_with_and_without_context(self):
+        """Verify with_context toggles between metadata stripping and raw text."""
+        raw = "> Replying to ASSISTANT (seq:1):\n> Quoted header\n\nActual response body"
+        with patch.object(muse_tui, "copy_to_clipboard", return_value=True):
+            # Clean text (without context)
+            self.tui.copy_message_to_clipboard(raw, with_context=False)
+            self.assertEqual(self.tui.clipboard_buf, "Quoted header\n\nActual response body")
+            self.assertIn("clean message", self.tui.toast_msg)
+
+            # Raw text (with context)
+            self.tui.copy_message_to_clipboard(raw, with_context=True)
+            self.assertEqual(self.tui.clipboard_buf, raw)
+            self.assertIn("message with context", self.tui.toast_msg)
+
+    def test_copy_message_to_clipboard_explicit(self):
+        """Verify copy_message_to_clipboard with explicit message text."""
+        with patch.object(muse_tui, "copy_to_clipboard", return_value=True):
+            custom_text = "Specific arbitrary message payload"
+            ok = self.tui.copy_message_to_clipboard(custom_text)
+            self.assertTrue(ok)
+            self.assertEqual(self.tui.clipboard_buf, custom_text)
+
+    def test_render_transcript_buttons(self):
+        """Verify [📋 Copy All], [📋 Copy] and [📑+ Context] buttons are rendered and registered."""
+        self.tui._render_transcript(y=1, x=24, h=25, w=76)
+
+        # Check [📋 Copy All] bounds registered
+        self.assertIsNotNone(self.tui._btn_copy_all_bounds)
+        btn_y, x_start, x_end = self.tui._btn_copy_all_bounds
+        self.assertEqual(btn_y, 1)
+        self.assertGreater(x_end, x_start)
+
+        # Verify button string was rendered to screen at btn coordinates
+        calls = [c for c in self.tui.safe_addstr.call_args_list if "[📋 Copy All]" in str(c)]
+        self.assertTrue(len(calls) > 0, "[📋 Copy All] must be rendered to stdscr")
+        win_arg, call_y, call_x, call_text, call_attr = calls[0].args
+        self.assertEqual(call_y, 1)
+        self.assertEqual(call_x, x_start)
+
+        # Check individual message copy buttons registered
+        self.assertGreater(len(self.tui._msg_copy_buttons), 0)
+        self.assertGreater(len(self.tui._msg_copy_context_buttons), 0)
+        for (my, mx1, mx2, raw_text) in self.tui._msg_copy_buttons:
+            self.assertGreater(mx2, mx1)
+            self.assertIn(raw_text, [m["text"] for m in self.messages])
+        for (my, mx1, mx2, raw_text) in self.tui._msg_copy_context_buttons:
+            self.assertGreater(mx2, mx1)
+            self.assertIn(raw_text, [m["text"] for m in self.messages])
+
+    def test_render_transcript_narrow_screen_retains_copy_button(self):
+        """Verify [📋 Copy All] is retained next to message count even with long title & narrow width."""
+        self.tui.data.active_thread_title = "Extremely Long Comprehensive Diagnostics Thread Title Exceeding Width"
+        self.tui._render_transcript(y=1, x=10, h=20, w=48)
+
+        self.assertIsNotNone(self.tui._btn_copy_all_bounds)
+        btn_y, x_start, x_end = self.tui._btn_copy_all_bounds
+        self.assertEqual(btn_y, 1)
+        self.assertLessEqual(x_end, 10 + 48, "Button must stay within transcript boundary")
+        calls = [c for c in self.tui.safe_addstr.call_args_list if "[📋 Copy All]" in str(c)]
+        self.assertTrue(len(calls) > 0)
+
+    def test_mouse_click_copy_all(self):
+        """Verify clicking [📋 Copy All] copies full transcript to clipboard."""
+        self.tui._render_transcript(y=1, x=24, h=25, w=76)
+        btn_y, x_start, x_end = self.tui._btn_copy_all_bounds
+        click_x = (x_start + x_end) // 2
+
+        with patch.object(self.tui, "copy_transcript_to_clipboard") as mock_copy_all:
+            handled = self.tui._handle_mouse(click_x, btn_y, curses.BUTTON1_CLICKED)
+            self.assertTrue(handled)
+            mock_copy_all.assert_called_once()
+
+    def test_mouse_click_message_copy(self):
+        """Verify clicking an individual [📋 Copy] button copies that specific message without context."""
+        self.tui._render_transcript(y=1, x=24, h=25, w=76)
+        self.assertGreater(len(self.tui._msg_copy_buttons), 0)
+        first_btn = self.tui._msg_copy_buttons[0]
+        msg_y, x_start, x_end, raw_text = first_btn
+        click_x = (x_start + x_end) // 2
+
+        with patch.object(self.tui, "copy_message_to_clipboard") as mock_copy_msg:
+            handled = self.tui._handle_mouse(click_x, msg_y, curses.BUTTON1_CLICKED)
+            self.assertTrue(handled)
+            mock_copy_msg.assert_called_once_with(raw_text, with_context=False)
+
+    def test_mouse_click_message_copy_context(self):
+        """Verify clicking an individual [📑+ Context] button copies that message with full context."""
+        self.tui._render_transcript(y=1, x=24, h=25, w=76)
+        self.assertGreater(len(self.tui._msg_copy_context_buttons), 0)
+        first_btn = self.tui._msg_copy_context_buttons[0]
+        msg_y, x_start, x_end, raw_text = first_btn
+        click_x = (x_start + x_end) // 2
+
+        with patch.object(self.tui, "copy_message_to_clipboard") as mock_copy_msg:
+            handled = self.tui._handle_mouse(click_x, msg_y, curses.BUTTON1_CLICKED)
+            self.assertTrue(handled)
+            mock_copy_msg.assert_called_once_with(raw_text, with_context=True)
+
+    def test_normal_hotkey_y(self):
+        """Verify 'y' in Normal mode copies latest message."""
+        self.tui.editor_mode = "NORMAL"
+        with patch.object(self.tui, "copy_message_to_clipboard") as mock_copy_msg:
+            handled = self.tui._handle_normal_key(ord("y"))
+            self.assertTrue(handled)
+            mock_copy_msg.assert_called_once()
+
+    def test_normal_hotkey_Y(self):
+        """Verify 'Y' in Normal mode copies full transcript."""
+        self.tui.editor_mode = "NORMAL"
+        with patch.object(self.tui, "copy_transcript_to_clipboard") as mock_copy_all:
+            handled = self.tui._handle_normal_key(ord("Y"))
+            self.assertTrue(handled)
+            mock_copy_all.assert_called_once()
+
+    def test_slash_command_copy_all(self):
+        """Verify '/copy' or '/yank' copies full transcript."""
+        with patch.object(self.tui, "copy_transcript_to_clipboard") as mock_copy_all:
+            self.tui._execute_input_line("/copy")
+            mock_copy_all.assert_called_once()
+
+        with patch.object(self.tui, "copy_transcript_to_clipboard") as mock_copy_all:
+            self.tui._execute_input_line("/yank")
+            mock_copy_all.assert_called_once()
+
+    def test_slash_command_copy_last(self):
+        """Verify '/copy last' copies latest message."""
+        with patch.object(self.tui, "copy_message_to_clipboard") as mock_copy_msg:
+            self.tui._execute_input_line("/copy last")
+            mock_copy_msg.assert_called_once()
+
+    def test_enter_visual_copy_mode(self):
+        """Pressing 'v' enters Visual Copy Mode with selection on visible line."""
+        self.tui.editor_mode = "NORMAL"
+        self.tui.copy_mode = False
+        self.tui._render_transcript(y=1, x=24, h=25, w=76)
+
+        ret = self.tui._handle_normal_key(ord('v'))
+        self.assertTrue(ret)
+        self.assertTrue(self.tui.copy_mode)
+        self.assertEqual(self.tui.focus_pane, "transcript")
+        self.assertIsNotNone(self.tui.visual_sel_start)
+        self.assertEqual(self.tui.visual_sel_start, self.tui.copy_cursor_line)
+        self.assertIn("VISUAL line copy mode", self.tui.toast_msg)
+
+    def test_enter_visual_copy_mode_V(self):
+        """Pressing 'V' on transcript enters visual copy mode."""
+        self.tui.editor_mode = "NORMAL"
+        self.tui.focus_pane = "transcript"
+        self.tui.copy_mode = False
+        self.tui._render_transcript(y=1, x=24, h=25, w=76)
+
+        ret = self.tui._handle_normal_key(ord('V'))
+        self.assertTrue(ret)
+        self.assertTrue(self.tui.copy_mode)
+        self.assertIsNotNone(self.tui.visual_sel_start)
+        self.assertIn("VISUAL line copy mode", self.tui.toast_msg)
+
+    def test_message_context_menu_copy_clean_and_context(self):
+        """Verify message_context modal options 2/y (clean) and 3/Y (context) work."""
+        target_msg = {
+            "role": "assistant",
+            "text": "> Replying to USER (seq:4):\n> Previous line\n\nClean response text",
+            "message_id": "msg-xyz-123",
+            "seq": 5,
+        }
+        self.tui.context_message = target_msg
+        self.tui.modal = "message_context"
+
+        with patch.object(self.tui, "copy_message_to_clipboard") as mock_copy:
+            # Key '2' or 'y' copies clean text (with_context=False)
+            self.tui._handle_modal_key(ord('2'))
+            mock_copy.assert_called_with(target_msg["text"], with_context=False)
+
+        self.tui.context_message = target_msg
+        self.tui.modal = "message_context"
+        with patch.object(self.tui, "copy_message_to_clipboard") as mock_copy:
+            # Key '3' or 'Y' copies with context (with_context=True)
+            self.tui._handle_modal_key(ord('3'))
+            mock_copy.assert_called_with(target_msg["text"], with_context=True)
+
+    def test_copy_mode_navigation_and_yank_with_border_stripping(self):
+        """Navigating with 'j'/'k' and yanking with 'y' copies clean text without box borders."""
+        self.tui._render_transcript(y=1, x=24, h=25, w=76)
+        self.tui.copy_mode = True
+        self.tui.visual_sel_start = 2
+        self.tui.copy_cursor_line = 2
+
+        # Move down to line 4
+        self.tui._handle_copy_mode_key(ord('j'))
+        self.assertEqual(self.tui.copy_cursor_line, 3)
+        self.tui._handle_copy_mode_key(ord('j'))
+        self.assertEqual(self.tui.copy_cursor_line, 4)
+
+        # Yank selection with 'y'
+        with patch.object(muse_tui, "copy_to_clipboard", return_value=True) as mock_clip:
+            self.tui._handle_copy_mode_key(ord('y'))
+            self.assertFalse(self.tui.copy_mode)
+            self.assertIsNone(self.tui.visual_sel_start)
+            mock_clip.assert_called_once()
+            copied = mock_clip.call_args[0][0]
+            # Ensure vertical box lines '│  ' are stripped
+            self.assertNotIn("│  ", copied)
+            self.assertIn("Copied", self.tui.toast_msg)
+
+    def test_mouse_drag_select_and_release_copy(self):
+        """Dragging mouse over transcript lines highlights and copies text on release."""
+        self.tui._render_transcript(y=1, x=24, h=25, w=76)
+
+        # 1. Mouse down at screen y=5, x=30 (inside transcript)
+        self.tui._handle_mouse(mx=30, my=5, bstate=curses.BUTTON1_PRESSED)
+        self.assertTrue(self.tui.mouse_dragging)
+        self.assertTrue(self.tui.copy_mode)
+        start_line = self.tui.visual_sel_start
+        self.assertIsNotNone(start_line)
+
+        # 2. Mouse drag to y=8
+        self.tui._handle_mouse(mx=30, my=8, bstate=curses.REPORT_MOUSE_POSITION)
+        self.assertEqual(self.tui.visual_sel_start, start_line)
+        self.assertNotEqual(self.tui.copy_cursor_line, start_line)
+
+        # 3. Mouse release
+        with patch.object(muse_tui, "copy_to_clipboard", return_value=True) as mock_clip:
+            self.tui._handle_mouse(mx=30, my=8, bstate=curses.BUTTON1_RELEASED)
+            self.assertFalse(self.tui.mouse_dragging)
+            self.assertFalse(self.tui.copy_mode)
+            mock_clip.assert_called_once()
+            copied = mock_clip.call_args[0][0]
+            self.assertGreater(len(copied), 0)
+            self.assertIn("Copied selection", self.tui.toast_msg)
+
+    def test_copy_mode_escape_exits(self):
+        """Esc or 'q' clears selection and exits copy mode."""
+        self.tui.copy_mode = True
+        self.tui.visual_sel_start = 5
+        self.tui.copy_cursor_line = 8
+
+        # First Esc clears selection
+        self.tui._handle_copy_mode_key(27)
+        self.assertIsNone(self.tui.visual_sel_start)
+        self.assertTrue(self.tui.copy_mode)
+
+        # Second Esc exits copy mode
+        self.tui._handle_copy_mode_key(27)
+        self.assertFalse(self.tui.copy_mode)
+
+
+if __name__ == "__main__":
+    unittest.main()
+

tests/test_docs_lookup.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""test_docs_lookup.py — Unit tests for docs_internal database and lookup engine."""
+
+import json
+import re
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+LOOKUP_INTERNAL = REPO_ROOT / "lookup_internal"
+DOCS_INTERNAL = REPO_ROOT / "docs_internal"
+DOCS_LOOKUP = REPO_ROOT / "bin" / "docs-lookup.py"
+SUPER_CLI = REPO_ROOT / "bin" / "super-cli.py"
+
+
+class TestDocsInternalDatabase(unittest.TestCase):
+    def test_manifest_and_symlink(self):
+        self.assertTrue(LOOKUP_INTERNAL.is_dir(), "lookup_internal must exist as directory")
+        self.assertTrue(DOCS_INTERNAL.exists(), "docs_internal must exist")
+        self.assertTrue(DOCS_INTERNAL.is_symlink(), "docs_internal must be a symlink to lookup_internal")
+
+        manifest_path = LOOKUP_INTERNAL / "manifest.json"
+        self.assertTrue(manifest_path.is_file(), "manifest.json must exist")
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+        self.assertIn(data.get("name"), ("lookup_internal", "docs_internal"))
+        self.assertIn("collections", data)
+        collections = data["collections"]
+        self.assertGreaterEqual(len(collections), 5)
+        for col in collections:
+            self.assertTrue((LOOKUP_INTERNAL / col["json_file"]).is_file(), f"{col['json_file']} missing")
+            self.assertTrue((LOOKUP_INTERNAL / col["md_file"]).is_file(), f"{col['md_file']} missing")
+
+
+    def test_sentence_structures(self):
+        p = DOCS_INTERNAL / "sentence_structure.json"
+        self.assertTrue(p.is_file())
+        data = json.loads(p.read_text(encoding="utf-8"))
+        structs = data.get("structures", {})
+        self.assertIn("work_order", structs)
+        self.assertIn("ack", structs)
+        self.assertIn("result", structs)
+        self.assertIn("claim", structs)
+        self.assertIn("tool_call", structs)
+        self.assertIn("nudge", structs)
+
+        for name, entry in structs.items():
+            self.assertIn("protocol_tag", entry)
+            self.assertIn("template", entry)
+            self.assertIn("required_fields", entry)
+            self.assertIn("description", entry)
+            self.assertIn("example", entry)
+
+    def test_regex_patterns_and_fixtures(self):
+        p = DOCS_INTERNAL / "regex_patterns.json"
+        self.assertTrue(p.is_file())
+        data = json.loads(p.read_text(encoding="utf-8"))
+        patterns = data.get("patterns", {})
+        self.assertIn("work_order", patterns)
+        self.assertIn("ack", patterns)
+        self.assertIn("verb", patterns)
+        self.assertIn("result", patterns)
+        self.assertIn("tool_call", patterns)
+
+        for pat_name, entry in patterns.items():
+            raw_pat = entry["pattern"]
+            flag_names = entry.get("flags", [])
+            flags = 0
+            for fn in flag_names:
+                flags |= getattr(re, fn)
+            # Must compile cleanly
+            compiled = re.compile(raw_pat, flags)
+
+            # Test valid samples
+            samples = entry.get("test_samples", {})
+            for valid_str in samples.get("valid", []):
+                self.assertIsNotNone(
+                    compiled.search(valid_str),
+                    f"Pattern '{pat_name}' failed to match valid sample: '{valid_str}'"
+                )
+
+            # Test invalid samples
+            for invalid_str in samples.get("invalid", []):
+                self.assertIsNone(
+                    compiled.fullmatch(invalid_str),
+                    f"Pattern '{pat_name}' unexpectedly matched invalid sample: '{invalid_str}'"
+                )
+
+    def test_assistive_surfaces(self):
+        p = DOCS_INTERNAL / "assistive_surfaces.json"
+        self.assertTrue(p.is_file())
+        data = json.loads(p.read_text(encoding="utf-8"))
+        self.assertEqual(data.get("host"), "box.muse-dev.online")
+        self.assertIn("views", data)
+        views = data["views"]
+        self.assertIn("dashboard", views)
+        self.assertIn("dms", views)
+        self.assertIn("jobs", views)
+        self.assertIn("loops", views)
+
+        # Check dashboard surface details
+        dash = views["dashboard"]
+        self.assertEqual(dash["dom_pane_selector"], "#tab-dashboard")
+        self.assertEqual(dash["key_elements"]["grid"], "#fleet-grid")
+        self.assertEqual(dash["api_endpoints"][0]["path"], "/api/box/fleet")
+
+    def test_cli_tools_reference(self):
+        p = DOCS_INTERNAL / "cli_tools.json"
+        self.assertTrue(p.is_file())
+        data = json.loads(p.read_text(encoding="utf-8"))
+        self.assertIn("binaries", data)
+        self.assertIn("super", data["binaries"])
+        self.assertIn("box", data["binaries"])
+        self.assertIn("domains", data)
+        domains = data["domains"]
+        self.assertIn("fleet", domains)
+        self.assertIn("dm", domains)
+        self.assertIn("job", domains)
+        self.assertIn("docs", domains)
+
+
+class TestDocsLookupCLI(unittest.TestCase):
+    def run_cmd(self, args: list) -> subprocess.CompletedProcess:
+        return subprocess.run(
+            [sys.executable, str(DOCS_LOOKUP)] + args,
+            capture_output=True,
+            text=True
+        )
+
+    def test_cli_overview_json(self):
+        res = self.run_cmd(["overview", "--json"])
+        self.assertEqual(res.returncode, 0, res.stderr)
+        out = json.loads(res.stdout)
+        self.assertEqual(out.get("name"), "docs_internal")
+
+    def test_cli_search(self):
+        res = self.run_cmd(["search", "work order", "--json"])
+        self.assertEqual(res.returncode, 0, res.stderr)
+        out = json.loads(res.stdout)
+        self.assertGreater(out.get("count", 0), 0)
+
+    def test_cli_surfaces(self):
+        res = self.run_cmd(["surfaces", "jobs", "--json"])
+        self.assertEqual(res.returncode, 0, res.stderr)
+        out = json.loads(res.stdout)
+        self.assertIn("jobs", out)
+        self.assertEqual(out["jobs"]["dom_tab_selector"], ".tab-btn[data-tab=\"jobs\"]")
+
+    def test_cli_sentence(self):
+        res = self.run_cmd(["sentence", "work_order", "--json"])
+        self.assertEqual(res.returncode, 0, res.stderr)
+        out = json.loads(res.stdout)
+        self.assertIn("work_order", out)
+        self.assertEqual(out["work_order"]["protocol_tag"], "[WO:<id>]")
+
+    def test_cli_regex_test(self):
+        res = self.run_cmd([
+            "regex", "result",
+            "--test", "[RESULT 7fce46e0] OK 14 allowlisted ops confirmed",
+            "--json"
+        ])
+        self.assertEqual(res.returncode, 0, res.stderr)
+        out = json.loads(res.stdout)
+        self.assertIn("result", out)
+        eval_res = out.get("test_evaluation", {})
+        self.assertTrue(eval_res.get("matched"))
+        self.assertEqual(eval_res["named_groups"]["job_id"], "7fce46e0")
+        self.assertEqual(eval_res["named_groups"]["status"], "OK")
+
+    def test_cli_parse(self):
+        res = self.run_cmd([
+            "parse",
+            "[WO:7fce46e0] [from super] Audit exec endpoints — Check /api/stats",
+            "--json"
+        ])
+        self.assertEqual(res.returncode, 0, res.stderr)
+        out = json.loads(res.stdout)
+        self.assertGreaterEqual(out.get("matched_patterns_count", 0), 2)
+        pattern_keys = [m["pattern_key"] for m in out.get("matches", [])]
+        self.assertIn("work_order", pattern_keys)
+
+    def test_super_cli_integration(self):
+        res = subprocess.run(
+            [sys.executable, str(SUPER_CLI), "docs", "surfaces", "dashboard", "--json"],
+            capture_output=True,
+            text=True
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        out = json.loads(res.stdout)
+        self.assertIn("dashboard", out)
+
+
+class TestLookupEngine(unittest.TestCase):
+    def test_lookup_engine_imports_and_hot_reload(self):
+        sys.path.insert(0, str(REPO_ROOT / "bin"))
+        import lookup_engine
+
+        # Verify compiled patterns
+        pats = lookup_engine.get_all_compiled_patterns()
+        self.assertGreaterEqual(len(pats), 14)
+        self.assertIn("result", pats)
+        self.assertIn("verb", pats)
+
+        res_re = lookup_engine.get_result_regex()
+        self.assertIsNotNone(res_re.search("[RESULT 7fce46e0] OK Done"))
+
+        verb_re = lookup_engine.get_verb_regex()
+        self.assertIsNotNone(verb_re.search("[CLAIM 7fce46e0]"))
+
+        # Verify soft validation
+        val_ok, kind, hint = lookup_engine.validate_outbound_sentence("[WO:7fce46e0] [from super] Audit — OK")
+        self.assertTrue(val_ok)
+        self.assertEqual(kind, "work_order")
+
+        val_fail, kind_f, hint_f = lookup_engine.validate_outbound_sentence("[WO:invalid] bad format")
+        self.assertFalse(val_fail)
+        self.assertEqual(kind_f, "work_order")
+        self.assertIn("Expected format", hint_f)
+
+
+if __name__ == "__main__":
+    unittest.main()
+

tests/test_main_nav.py

@@ -56,8 +56,8 @@ class TestSidechatNavigationLogic(unittest.TestCase):
         import dm
         # Well-known mappings
         self.assertEqual(dm.resolve_sidechat_target("main"), "main")
-        self.assertEqual(dm.resolve_sidechat_target("646 tasks"), "1e75a740-d08f-443d-a0f9-793db196e24f")
-        self.assertEqual(dm.resolve_sidechat_target("heartbeat"), "1e75a740-d08f-443d-a0f9-793db196e24f")
+        self.assertEqual(dm.resolve_sidechat_target("646 tasks"), "1dfb3199-2f99-446c-83e3-848ae2da0a12")
+        self.assertEqual(dm.resolve_sidechat_target("heartbeat"), "757198c3-c1b2-48b8-ba2b-062c84f71b02")
 
     def test_uuid_regex_detection(self):
         import dm, re

tests/test_notifications.py

@@ -0,0 +1,207 @@
+import unittest
+import time
+from unittest.mock import MagicMock
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "bin"))
+
+import muse_tui
+
+class TestNotificationCounters(unittest.TestCase):
+    def setUp(self):
+        self.dm = muse_tui.FleetDataManager()
+        # Mock background loops from interfering with testing
+        self.dm.running = False
+        self.dm.read_msg_counts = {}
+        # Isolate threads and history caches for tests
+        self.dm.nodes = ["pip", "646"]
+        self.dm.threads_cache = {"pip": [], "646": []}
+        self.dm.history_cache = {}
+
+    def test_unread_count_calculation(self):
+        node = "pip"
+        tid = "test-thread-123"
+        key = (node, tid)
+
+        # Initially no messages -> unread is 0
+        self.assertEqual(self.dm.get_unread_count(node, tid), 0)
+
+        # 5 messages arrive in cache
+        self.dm.history_cache[key] = [{"text": f"msg {i}"} for i in range(5)]
+        self.assertEqual(self.dm.get_unread_count(node, tid), 5)
+
+        # Read 3 messages
+        self.dm.mark_thread_read(node, tid, count=3)
+        self.assertEqual(self.dm.get_unread_count(node, tid), 2)
+
+        # Read all messages
+        self.dm.mark_thread_read(node, tid)
+        self.assertEqual(self.dm.get_unread_count(node, tid), 0)
+
+    def test_node_and_fleet_unread_total(self):
+        # Configure test threads for pip and 646
+        self.dm.threads_cache["pip"] = [
+            {"session_id": "pip-chat-1", "is_main": True},
+            {"session_id": "pip-chat-2", "is_main": False},
+        ]
+        self.dm.threads_cache["646"] = [
+            {"session_id": "646-chat-1", "is_main": True},
+        ]
+
+        # Populate message histories
+        self.dm.history_cache[("pip", "pip-chat-1")] = [{"text": "1"}, {"text": "2"}]
+        self.dm.history_cache[("pip", "pip-chat-2")] = [{"text": "a"}, {"text": "b"}, {"text": "c"}]
+        self.dm.history_cache[("646", "646-chat-1")] = [{"text": "x"}]
+
+        # Before reading: pip has 5, 646 has 1, total fleet is 6
+        self.assertEqual(self.dm.get_node_unread_total("pip"), 5)
+        self.assertEqual(self.dm.get_node_unread_total("646"), 1)
+        self.assertEqual(self.dm.get_fleet_unread_total(), 6)
+
+        # Read pip-chat-1
+        self.dm.mark_thread_read("pip", "pip-chat-1")
+        self.assertEqual(self.dm.get_node_unread_total("pip"), 3)
+        self.assertEqual(self.dm.get_fleet_unread_total(), 4)
+
+    def test_dwell_clearing_logic(self):
+        tui = muse_tui.MuseTUI(MagicMock())
+        tui.data.running = False
+        active_node = "muse"
+        active_tid = "muse-thread-abc"
+
+        tui.data.active_node = active_node
+        tui.data.active_thread_id = active_tid
+        tui.data.history_cache[(active_node, active_tid)] = [{"text": "msg"}] * 4
+        self.assertEqual(tui.data.get_unread_count(active_node, active_tid), 4)
+
+        # Simulated dwell < 5.0 seconds
+        tui.cur_chat_enter_time = time.time() - 2.0
+        tui.last_dwell_check_target = (active_node, active_tid)
+        # Should not clear yet
+        if time.time() - tui.cur_chat_enter_time >= 5.0:
+            tui.data.mark_thread_read(active_node, active_tid)
+        self.assertEqual(tui.data.get_unread_count(active_node, active_tid), 4)
+
+        # Simulated dwell >= 5.0 seconds
+        tui.cur_chat_enter_time = time.time() - 5.5
+        if time.time() - tui.cur_chat_enter_time >= 5.0:
+            tui.data.mark_thread_read(active_node, active_tid)
+        self.assertEqual(tui.data.get_unread_count(active_node, active_tid), 0)
+
+    def test_agent_sorting_and_initial_selection(self):
+        # Configure nodes
+        self.dm.nodes = ["pip", "muse", "opm", "646"]
+        self.dm.threads_cache = {
+            "pip": [{"session_id": "p1"}],
+            "muse": [{"session_id": "m1"}],
+            "opm": [{"session_id": "o1"}],
+            "646": [{"session_id": "c1"}],
+        }
+        # Give opm 5 unread messages, muse 2 unreads, pip 0, 646 0
+        self.dm.history_cache = {
+            ("opm", "o1"): [{"text": f"msg {i}"} for i in range(5)],
+            ("muse", "m1"): [{"text": f"msg {i}"} for i in range(2)],
+        }
+        self.dm.agent_interactions = {"pip": 100.0, "646": 200.0, "muse": 50.0, "opm": 0.0}
+
+        self.dm.sort_nodes()
+        # opm should be first (highest unread = 5)
+        # muse should be second (unread = 2)
+        # 646 should be third (interaction = 200.0)
+        # pip should be fourth (interaction = 100.0)
+        self.assertEqual(self.dm.nodes, ["opm", "muse", "646", "pip"])
+
+        # Default initial_node=None in MuseTUI picks nodes[0] (top of list) and its Main Chat
+        tui = muse_tui.MuseTUI(MagicMock(), initial_node=None)
+        tui.data.running = False
+        self.assertEqual(tui.data.active_node, tui.data.nodes[0])
+        self.assertIsNotNone(tui.data.active_thread_id)
+        top_node = tui.data.nodes[0]
+        top_threads = {t.get("session_id") for t in tui.data.threads_cache.get(top_node, [])}
+        self.assertIn(tui.data.active_thread_id, top_threads)
+
+    def test_reply_workflow(self):
+        tui = muse_tui.MuseTUI(MagicMock())
+        tui.data.running = False
+
+        msg = {
+            "role": "assistant",
+            "message_id": "msg-987654321",
+            "seq": 42,
+            "text": "Please confirm deployment parameters before we proceed.",
+        }
+
+        # 1. Trigger reply
+        ok = tui.trigger_reply_to_message(msg)
+        self.assertTrue(ok)
+        self.assertIsNotNone(tui.reply_target)
+        self.assertEqual(tui.reply_target["seq"], 42)
+        self.assertEqual(tui.reply_target["role"], "assistant")
+        self.assertEqual(tui.editor_mode, "INSERT")
+
+        # 2. Cancel reply with Esc sequence
+        tui._read_escape_sequence = MagicMock(return_value=[])  # standalone Esc
+        tui._handle_escape_sequence()
+        self.assertIsNone(tui.reply_target)
+        self.assertEqual(tui.editor_mode, "NORMAL")
+
+        # 3. Trigger reply again and execute input line
+        tui.trigger_reply_to_message(msg)
+        dispatched_messages = []
+        tui._async_send_message = lambda node, tid, text: dispatched_messages.append((node, tid, text))
+
+        tui._execute_input_line("Confirmed, deploy now.")
+        self.assertIsNone(tui.reply_target)
+        self.assertEqual(len(dispatched_messages), 1)
+        node, tid, sent_text = dispatched_messages[0]
+        self.assertIn("> Replying to ASSISTANT (seq:42):", sent_text)
+        self.assertIn("Please confirm deployment parameters before we proceed.", sent_text)
+        self.assertIn("Confirmed, deploy now.", sent_text)
+
+    def test_sidechat_notifications_and_transcript_divider(self):
+        tui = muse_tui.MuseTUI(MagicMock())
+        tui.data.running = False
+        active_node = "muse"
+        active_tid = "sidechat-worker-42"
+        tui.data.active_node = active_node
+        tui.data.active_thread_id = active_tid
+
+        tui.data.threads_cache[active_node] = [
+            {"session_id": "main-chat", "is_main": True, "title": "Main Chat"},
+            {"session_id": active_tid, "is_main": False, "title": "Worker Task 42"},
+            {"session_id": "sidechat-worker-43", "is_main": False, "title": "Worker Task 43"},
+        ]
+
+        # 3 total messages, read count is 1 -> 2 unread messages in active sidechat
+        tui.data.history_cache[(active_node, active_tid)] = [
+            {"role": "user", "text": "initial prompt", "message_id": "m1"},
+            {"role": "assistant", "text": "update 1", "message_id": "m2"},
+            {"role": "assistant", "text": "update 2", "message_id": "m3"},
+        ]
+        tui.data.read_msg_counts[(active_node, active_tid)] = 1
+
+        self.assertEqual(tui.data.get_unread_count(active_node, active_tid), 2)
+        self.assertEqual(tui.data.get_node_unread_total(active_node), 2)
+
+        # Mock safe_addstr to capture rendered strings
+        rendered_texts = []
+        tui.safe_addstr = lambda win, y, x, text, attr=0: rendered_texts.append(text)
+
+        # 1. Render sidebar
+        tui._render_sidebar(0, 0, 30, 32)
+        # Should contain ●2 inline notification badge
+        has_badge = any("●2" in s for s in rendered_texts)
+        self.assertTrue(has_badge, "Sidechats list row or header must render inline ●2 unread badge")
+
+        # 2. Render transcript
+        rendered_texts.clear()
+        tui._render_transcript(0, 32, 30, 80)
+        # Should render the unread divider banner or unread pill
+        has_div = any("2 NEW UNREAD MESSAGE" in s for s in rendered_texts)
+        has_hdr_pill = any("[● 2 new]" in s for s in rendered_texts)
+        self.assertTrue(has_div or has_hdr_pill, "Transcript must display unread banner or pill")
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_paste_handling.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""
+test_paste_handling.py — Unit tests for long string / chunk paste handling in MuseTUI:
+1. Multi-line chunk pasting preserves newlines and does not send immediately.
+2. Enter key submits the entire chunk as a single message and single history item.
+3. Bracketed paste sequences (\033[200~ ... \033[201~) are correctly parsed and captured.
+4. Alt+Enter (ESC + Enter) inserts newlines for multiline composition.
+5. Unbracketed rapid paste bursts preserve newlines without line-by-line send.
+6. Arrow keys navigate lines within multiline buffer.
+7. UTF-8 multibyte characters are correctly decoded and inserted into buffer.
+8. Multiline messages or file paths starting with '/' are delivered as messages.
+"""
+
+import unittest
+from unittest.mock import MagicMock, patch
+import importlib.util
+from pathlib import Path
+import curses
+
+REPO_ROOT = Path("/home/super/Projects/NetVM")
+TUI_PATH = REPO_ROOT / "bin" / "muse-tui.py"
+
+spec = importlib.util.spec_from_file_location("muse_tui", str(TUI_PATH))
+muse_mod = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(muse_mod)
+
+
+class TestPasteHandling(unittest.TestCase):
+    def setUp(self):
+        self.mock_stdscr = MagicMock()
+        self.mock_stdscr.getmaxyx.return_value = (30, 100)
+        self.tui = muse_mod.MuseTUI(self.mock_stdscr, initial_mode="muse", initial_node="muse")
+        self.tui.safe_addstr = MagicMock()
+        self.tui.data.running = False  # Keep background thread stopped
+        self.tui.data.active_node = "muse"
+        self.tui.data.active_thread_id = "test-session"
+        self.tui.data.active_thread_title = "Main Chat"
+        self.tui.data.threads_cache["muse"] = [{"session_id": "test-session", "is_main": True}]
+
+    def test_insert_pasted_text_multiline(self):
+        """Pasting a multiline chunk enters input_buf in full without sending."""
+        chunk = "Line 1: Hello\nLine 2: World\nLine 3: Agent instruction"
+        self.tui.editor_mode = "NORMAL"
+        self.tui.input_buf = ""
+        self.tui.input_cursor = 0
+
+        self.tui._insert_pasted_text(chunk)
+
+        self.assertEqual(self.tui.editor_mode, "INSERT")
+        self.assertEqual(self.tui.input_buf, chunk)
+        self.assertEqual(self.tui.input_cursor, len(chunk))
+        self.assertIn("3 lines", self.tui.toast_msg)
+        # Verify nothing was sent yet
+        self.assertEqual(len(self.tui.input_history), 0)
+
+    def test_multiline_send_as_single_chunk(self):
+        """Submitting a multiline buffer records ONE history entry and sends ONCE."""
+        chunk = "Line 1: def test():\n    print('NetVM')\nLine 3: return True"
+        self.tui.editor_mode = "INSERT"
+        self.tui.input_buf = chunk
+        self.tui.input_cursor = len(chunk)
+
+        sent_messages = []
+        self.tui._async_send_message = lambda node, tid, text: sent_messages.append((node, tid, text))
+
+        # Simulate user pressing Enter on the completed multiline chunk
+        # With no characters waiting in stdin (peek_c = -1)
+        self.mock_stdscr.getch.return_value = -1
+        ret = self.tui._handle_insert_key(10)
+
+        self.assertTrue(ret)
+        self.assertEqual(self.tui.input_buf, "")
+        self.assertEqual(len(self.tui.input_history), 1)
+        self.assertEqual(self.tui.input_history[0], chunk)
+        self.assertEqual(len(sent_messages), 1)
+        self.assertEqual(sent_messages[0][0], "muse")
+        self.assertEqual(sent_messages[0][1], "test-session")
+        self.assertEqual(sent_messages[0][2], chunk)
+
+    def test_bracketed_paste_capture(self):
+        """\033[200~ bracketed paste reads until \033[201~ and captures content."""
+        payload = "Multi-line code snippet:\n```python\nx = 42\nprint(x)\n```"
+        # Simulate stream of getch returns: payload bytes followed by \033[201~ then -1
+        stream = list(payload.encode("utf-8")) + [27, ord('['), ord('2'), ord('0'), ord('1'), ord('~')]
+
+        call_idx = 0
+        def mock_getch():
+            nonlocal call_idx
+            if call_idx < len(stream):
+                val = stream[call_idx]
+                call_idx += 1
+                return val
+            return -1
+
+        self.mock_stdscr.getch.side_effect = mock_getch
+        self.tui.input_buf = ""
+        self.tui.input_cursor = 0
+
+        handled = self.tui._handle_bracketed_paste()
+        self.assertTrue(handled)
+        self.assertEqual(self.tui.input_buf, payload)
+        self.assertEqual(self.tui.input_cursor, len(payload))
+        self.assertEqual(self.tui.editor_mode, "INSERT")
+
+    def test_alt_enter_inserts_newline(self):
+        """Alt+Enter (ESC + 10 or 13) inserts newline into input_buf."""
+        self.tui.editor_mode = "INSERT"
+        self.tui.input_buf = "First line"
+        self.tui.input_cursor = len(self.tui.input_buf)
+
+        # Mock _read_escape_sequence returning [10] (Enter)
+        with patch.object(self.tui, "_read_escape_sequence", return_value=[10]):
+            res = self.tui._handle_escape_sequence()
+
+        self.assertTrue(res)
+        self.assertEqual(self.tui.input_buf, "First line\n")
+        self.assertEqual(self.tui.input_cursor, len("First line\n"))
+
+    def test_multiline_cursor_navigation(self):
+        """Up and Down arrow navigate across lines inside multiline input_buf."""
+        self.tui.editor_mode = "INSERT"
+        self.tui.input_buf = "Line A\nLine B\nLine C"
+        # Place cursor at end of "Line C"
+        self.tui.input_cursor = len(self.tui.input_buf)
+
+        # Press Up: cursor should move to "Line B"
+        self.tui._handle_insert_key(curses.KEY_UP)
+        curr_text = self.tui.input_buf[:self.tui.input_cursor]
+        self.assertTrue(curr_text.endswith("Line B") or "Line B" in curr_text)
+
+        # Press Up again: cursor should move to "Line A"
+        self.tui._handle_insert_key(curses.KEY_UP)
+        curr_text = self.tui.input_buf[:self.tui.input_cursor]
+        self.assertTrue(curr_text.startswith("Line A"))
+
+        # Press Down: cursor should move back down to "Line B"
+        self.tui._handle_insert_key(curses.KEY_DOWN)
+        curr_text = self.tui.input_buf[:self.tui.input_cursor]
+        self.assertIn("Line B", curr_text)
+
+    def test_unicode_multibyte_input(self):
+        """Multi-byte UTF-8 bytes assemble into correct unicode characters."""
+        self.tui.editor_mode = "INSERT"
+        self.tui.input_buf = "Test: "
+        self.tui.input_cursor = len(self.tui.input_buf)
+
+        # 'é' is 0xC3, 0xA9 (195, 169)
+        self.tui._handle_insert_key(195)
+        self.assertEqual(self.tui.input_buf, "Test: ")  # incomplete byte, not added yet
+        self.tui._handle_insert_key(169)
+        self.assertEqual(self.tui.input_buf, "Test: é")
+        self.assertEqual(self.tui.input_cursor, len("Test: é"))
+
+    def test_path_starting_with_slash_delivers_as_message(self):
+        """A string starting with a file path like '/var/log/syslog' is sent as message."""
+        line = "/var/log/syslog contains error details"
+        sent = []
+        self.tui._async_send_message = lambda node, tid, text: sent.append(text)
+
+        self.tui._execute_input_line(line)
+        self.assertEqual(len(sent), 1)
+        self.assertEqual(sent[0], line)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_prompts.py

@@ -0,0 +1,449 @@
+#!/usr/bin/env python3
+"""
+test_prompts.py — Comprehensive unit and integration test suite for:
+1. PromptManager persistence, defaults, formulation, deletion, and pin sorting.
+2. Compact persistent prompt shelf in View 1 (Agent Chat) and 1-click auto-fill.
+3. Expanded Prompt Library modal ('P') with Vim hjkl navigation, preview scroll, and Enter/click fill.
+4. Searchable chat history sends ('s' / Ctrl-R) aggregating session and history cache.
+5. 'p' pinning chat sent messages to the prompt fill / list in history search and transcript view.
+6. Horizontal scrolling of prompt shelf via chips bounds, navigation buttons, wheel, and '[' / ']'.
+"""
+
+import unittest
+from unittest.mock import MagicMock, patch
+import importlib.util
+from pathlib import Path
+import tempfile
+import time
+import json
+import curses
+
+REPO_ROOT = Path("/home/super/Projects/NetVM")
+TUI_PATH = REPO_ROOT / "bin" / "muse-tui.py"
+
+spec = importlib.util.spec_from_file_location("muse_tui", str(TUI_PATH))
+muse_mod = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(muse_mod)
+
+
+class TestPromptManager(unittest.TestCase):
+    """Test suite covering PromptManager storage, formulation, and pin ranking."""
+
+    def setUp(self):
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.storage_file = Path(self.temp_dir.name) / "test_prompts.json"
+        self.pm = muse_mod.PromptManager(storage_path=self.storage_file)
+
+    def tearDown(self):
+        self.temp_dir.cleanup()
+
+    def test_default_prompts_seeded_and_persisted(self):
+        """Verify PromptManager initializes with default prompts and writes to disk."""
+        self.assertTrue(self.storage_file.exists())
+        prompts = self.pm.get_sorted_prompts()
+        self.assertGreaterEqual(len(prompts), 5)
+        titles = [p["title"] for p in prompts]
+        self.assertIn("Fleet Audit", titles)
+        self.assertIn("Work Order", titles)
+        self.assertIn("CDP Inspect", titles)
+
+    def test_add_and_delete_prompt(self):
+        """Verify formulation of custom prompt skills and subsequent deletion."""
+        new_p = self.pm.add_prompt(
+            title="Custom Health Probe",
+            prompt_text="Run detailed tcpdump and box health probes on all nodes.",
+            tags=["probe", "custom"],
+            pinned=True
+        )
+        self.assertEqual(new_p["title"], "Custom Health Probe")
+        self.assertTrue(new_p["pinned"])
+
+        # Check persistence
+        reloaded = muse_mod.PromptManager(storage_path=self.storage_file)
+        prompts = reloaded.get_sorted_prompts()
+        self.assertTrue(any(p["id"] == new_p["id"] for p in prompts))
+
+        # Delete
+        self.assertTrue(self.pm.delete_prompt(new_p["id"]))
+        prompts_after = self.pm.get_sorted_prompts()
+        self.assertFalse(any(p["id"] == new_p["id"] for p in prompts_after))
+
+    def test_toggle_pin_prompt(self):
+        """Verify toggle_pin_prompt alters pinned flag and affects sorted order."""
+        prompts = self.pm.get_sorted_prompts()
+        target = prompts[-1]  # Get unpinned prompt
+        target_id = target["id"]
+
+        new_state = self.pm.toggle_pin_prompt(target_id)
+        self.assertTrue(new_state)
+
+        # In sorted prompts, newly pinned should be among first
+        sorted_p = self.pm.get_sorted_prompts()
+        first_few_ids = [p["id"] for p in sorted_p[:4]]
+        self.assertIn(target_id, first_few_ids)
+
+    def test_pin_chat_send(self):
+        """Verify pinning a chat sent message formats title, pins to top, and persists."""
+        sent_text = "Investigate high CDP drop rates and verify routing table on node 646."
+        prompt, is_new = self.pm.pin_chat_send(sent_text, node="646")
+        self.assertTrue(is_new)
+        self.assertTrue(prompt["pinned"])
+        self.assertEqual(prompt["prompt"], sent_text)
+        self.assertIn("Investigate high CDP", prompt["title"])
+
+        # Pinned chat send should be first in sorted prompts
+        sorted_p = self.pm.get_sorted_prompts()
+        self.assertEqual(sorted_p[0]["id"], prompt["id"])
+
+        # Pinning same text again should mark pinned without creating duplicate
+        p2, is_new2 = self.pm.pin_chat_send(sent_text, node="646")
+        self.assertFalse(is_new2)
+        self.assertEqual(p2["id"], prompt["id"])
+
+    def test_toggle_pin_chat_send(self):
+        """Verify toggle_pin_chat_send flips pinned state between True and False."""
+        sent_text = "Investigate high CDP drop rates and verify routing table."
+        p1, is_new = self.pm.toggle_pin_chat_send(sent_text, node="646")
+        self.assertTrue(is_new)
+        self.assertTrue(p1["pinned"])
+
+        # Toggle again: should unpin
+        p2, is_new2 = self.pm.toggle_pin_chat_send(sent_text, node="646")
+        self.assertFalse(is_new2)
+        self.assertFalse(p2["pinned"])
+
+        # Toggle again: should re-pin
+        p3, is_new3 = self.pm.toggle_pin_chat_send(sent_text, node="646")
+        self.assertFalse(is_new3)
+        self.assertTrue(p3["pinned"])
+
+
+class TestPromptTUIIntegration(unittest.TestCase):
+    """Test suite covering TUI compact shelf, click auto-fill, modals, and sends search."""
+
+    def setUp(self):
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.storage_file = Path(self.temp_dir.name) / "test_prompts.json"
+
+        self.mock_stdscr = MagicMock()
+        self.mock_stdscr.getmaxyx.return_value = (30, 100)
+        self.tui = muse_mod.MuseTUI(self.mock_stdscr, initial_mode="muse", initial_node="muse")
+        self.tui.data.stop()
+        self.tui.safe_addstr = MagicMock()
+
+        # Replace prompt manager with isolated instance
+        self.tui.prompt_manager = muse_mod.PromptManager(storage_path=self.storage_file)
+        self.tui.prompts = self.tui.prompt_manager.get_sorted_prompts()
+
+        # Clear history cache to isolate unit test data
+        self.tui.data.history_cache.clear()
+
+        # Seed sample chat history
+        self.tui.data.history_cache[("muse", "thread_1")] = [
+            {"role": "user", "text": "Check all docker network bridges.", "message_id": "m1"},
+            {"role": "assistant", "text": "All docker network bridges are operational.", "message_id": "m2"},
+            {"role": "user", "text": "Inspect CDP latency on pip and opm.", "message_id": "m3"},
+        ]
+        self.tui.data.active_node = "muse"
+        self.tui.data.active_thread_id = "thread_1"
+        self.tui.data.active_thread_title = "thread_1"
+        self.tui.input_history = ["Recent typed command from session"]
+
+    def tearDown(self):
+        self.temp_dir.cleanup()
+
+    def test_compact_prompt_shelf_render_and_chip_bounds(self):
+        """Verify _render_prompt_shelf populates chip bounds and button boundaries."""
+        self.tui._render_prompt_shelf(y=24, x=0, h=2, w=100)
+        bounds = self.tui._prompt_chip_bounds
+        self.assertGreater(len(bounds), 0, "Prompt chips should be registered with bounding boxes")
+
+        first_start, first_end, first_prompt = bounds[0]
+        self.assertGreater(first_end, first_start)
+        self.assertIn("title", first_prompt)
+        self.assertTrue(hasattr(self.tui, "_btn_expand_bounds"))
+        self.assertTrue(hasattr(self.tui, "_btn_sends_bounds"))
+
+    def test_one_click_auto_fill_from_shelf(self):
+        """Verify clicking a prompt chip immediately auto-fills input_buf and sets INSERT mode."""
+        self.tui._render_prompt_shelf(y=24, x=0, h=2, w=100)
+        first_start, first_end, first_prompt = self.tui._prompt_chip_bounds[0]
+
+        # Simulate click on chip
+        click_x = (first_start + first_end) // 2
+        click_y = 25  # Row 1 of prompt shelf (chip row)
+        res = self.tui._handle_mouse(mx=click_x, my=click_y, bstate=curses.BUTTON1_CLICKED)
+        self.assertTrue(res)
+
+        # Input buffer should contain prompt text
+        self.assertEqual(self.tui.input_buf, first_prompt["prompt"])
+        self.assertEqual(self.tui.input_cursor, len(first_prompt["prompt"]))
+        self.assertEqual(self.tui.editor_mode, "INSERT")
+        self.assertIn("Filled prompt", self.tui.toast_msg)
+
+    def test_expand_prompts_modal_and_vim_navigation(self):
+        """Verify pressing 'P' expands modal and hjkl keys navigate and Enter fills."""
+        # Press capital 'P' in NORMAL mode
+        self.tui.editor_mode = "NORMAL"
+        self.tui.focus_pane = "transcript"
+        res = self.tui._handle_key(ord('P'))
+        self.assertTrue(res)
+        self.assertEqual(self.tui.modal, "prompts")
+        self.assertEqual(self.tui.prompt_sel_idx, 0)
+
+        # 'j' moves down
+        self.tui._handle_key(ord('j'))
+        self.assertEqual(self.tui.prompt_sel_idx, 1)
+
+        # 'k' moves up
+        self.tui._handle_key(ord('k'))
+        self.assertEqual(self.tui.prompt_sel_idx, 0)
+
+        # 'G' jumps to last
+        self.tui._handle_key(ord('G'))
+        self.assertEqual(self.tui.prompt_sel_idx, len(self.tui.prompts) - 1)
+
+        # 'g' jumps to first
+        self.tui._handle_key(ord('g'))
+        self.assertEqual(self.tui.prompt_sel_idx, 0)
+
+        # Enter fills selected prompt and switches to INSERT
+        expected_text = self.tui.prompts[0]["prompt"]
+        self.tui._handle_key(10)  # Enter
+        self.assertIsNone(self.tui.modal)
+        self.assertEqual(self.tui.input_buf, expected_text)
+        self.assertEqual(self.tui.editor_mode, "INSERT")
+
+    def test_searchable_chat_history_sends(self):
+        """Verify get_chat_sends aggregates past sends and filters with query."""
+        sends = self.tui.get_chat_sends()
+        self.assertGreaterEqual(len(sends), 3)
+        texts = [s["text"] for s in sends]
+        self.assertIn("Recent typed command from session", texts)
+        self.assertIn("Check all docker network bridges.", texts)
+        self.assertIn("Inspect CDP latency on pip and opm.", texts)
+
+        # Filter query
+        filtered = self.tui.get_chat_sends("docker")
+        self.assertEqual(len(filtered), 1)
+        self.assertEqual(filtered[0]["text"], "Check all docker network bridges.")
+
+    def test_pin_chat_send_to_prompt_fill_in_history_search(self):
+        """Verify 'p' in history_search toggles pin and unpin for highlighted send."""
+        self.tui.modal = "history_search"
+        self.tui.modal_input_buf = ""
+        self.tui.history_search_sel = 0
+
+        initial_prompts_count = len(self.tui.prompts)
+        sends = self.tui.get_chat_sends()
+        target_send_text = sends[0]["text"]
+
+        # Press 'p': 1st time pins
+        res = self.tui._handle_key(ord('p'))
+        self.assertTrue(res)
+
+        self.assertEqual(len(self.tui.prompts), initial_prompts_count + 1)
+        top_prompt = self.tui.prompts[0]
+        self.assertTrue(top_prompt["pinned"])
+        self.assertEqual(top_prompt["prompt"], target_send_text)
+        self.assertIn("Pinned", self.tui.toast_msg)
+
+        # Press 'p': 2nd time UNPINS
+        res2 = self.tui._handle_key(ord('p'))
+        self.assertTrue(res2)
+
+        target_prompt_obj = [p for p in self.tui.prompt_manager.prompts if p["prompt"] == target_send_text][0]
+        self.assertFalse(target_prompt_obj["pinned"])
+        self.assertIn("Unpinned", self.tui.toast_msg)
+
+        # Press 'p': 3rd time RE-PINS
+        res3 = self.tui._handle_key(ord('p'))
+        self.assertTrue(res3)
+        self.assertTrue(target_prompt_obj["pinned"])
+        self.assertIn("Pinned", self.tui.toast_msg)
+
+    def test_history_search_mouse_toggle_pin(self):
+        """Verify clicking the pin column in history_search toggles pin/unpin."""
+        self.tui.modal = "history_search"
+        self.tui.modal_input_buf = ""
+        self.tui.history_search_sel = 0
+
+        sends = self.tui.get_chat_sends()
+        target_text = sends[0]["text"]
+
+        h, w = self.tui.stdscr.getmaxyx()
+        modal_w = min(74, w - 6)
+        modal_h = min(20, h - 4)
+        top_y = (h - modal_h) // 2
+        left_x = (w - modal_w) // 2
+
+        # 1st click pins
+        click_y = top_y + 4
+        click_x = left_x + 4
+        handled = self.tui._handle_mouse(click_x, click_y, curses.BUTTON1_CLICKED)
+        self.assertTrue(handled)
+        target_prompt = [p for p in self.tui.prompt_manager.prompts if p["prompt"] == target_text][0]
+        self.assertTrue(target_prompt["pinned"])
+        self.assertIn("Pinned", self.tui.toast_msg)
+
+        # 2nd click unpins
+        handled2 = self.tui._handle_mouse(click_x, click_y, curses.BUTTON1_CLICKED)
+        self.assertTrue(handled2)
+        self.assertFalse(target_prompt["pinned"])
+        self.assertIn("Unpinned", self.tui.toast_msg)
+
+    def test_transcript_view_p_pins_latest_send(self):
+        """Verify pressing 'p' on transcript pins the current thread's latest sent message."""
+        self.tui.modal = None
+        self.tui.editor_mode = "NORMAL"
+        self.tui.focus_pane = "transcript"
+
+        initial_count = len(self.tui.prompts)
+        # In current thread, latest user message is "Inspect CDP latency on pip and opm."
+        res = self.tui._handle_key(ord('p'))
+        self.assertTrue(res)
+
+        self.assertEqual(len(self.tui.prompts), initial_count + 1)
+        self.assertEqual(self.tui.prompts[0]["prompt"], "Inspect CDP latency on pip and opm.")
+        self.assertTrue(self.tui.prompts[0]["pinned"])
+        self.assertIn("Pinned", self.tui.toast_msg)
+
+    def test_sidebar_p_still_toggles_thread_pin(self):
+        """Verify pressing 'p' when focus is on sidebar preserves thread pinning."""
+        self.tui.modal = None
+        self.tui.editor_mode = "NORMAL"
+        self.tui.focus_pane = "sidebar"
+
+        # Ensure thread_1 is unpinned initially
+        self.tui.data.pinned_threads.setdefault("muse", set()).discard("thread_1")
+
+        # Mock threads cache
+        self.tui.data.threads_cache["muse"] = [
+            {"session_id": "thread_1", "title": "Test Chat", "is_main": False}
+        ]
+        self.tui.thread_sel_idx = 0
+
+        res = self.tui._handle_key(ord('p'))
+        self.assertTrue(res)
+        self.assertIn("thread_1", self.tui.data.pinned_threads.get("muse", set()))
+        self.assertIn("Pinned chat", self.tui.toast_msg)
+
+        # Clean up disk state
+        self.tui.data.toggle_pin_thread("muse", "thread_1")
+
+    def test_bracket_keys_scroll_prompt_shelf(self):
+        """Verify '[' and ']' scroll the compact prompt shelf horizontally."""
+        self.tui.editor_mode = "NORMAL"
+        self.tui.focus_pane = "transcript"
+        self.tui.prompt_scroll_idx = 0
+
+        self.tui._handle_key(ord(']'))
+        self.assertEqual(self.tui.prompt_scroll_idx, 1)
+
+        self.tui._handle_key(ord('['))
+        self.assertEqual(self.tui.prompt_scroll_idx, 0)
+
+    def test_slash_prompt_and_sends_commands(self):
+        """Verify /prompt save and /sends slash commands formulate and open modals."""
+        self.tui.input_buf = "Check loop telemetry on all nodes"
+        self.tui._execute_input_line("/prompt save Telemetry Check")
+
+        prompts = self.tui.prompt_manager.get_sorted_prompts()
+        saved = [p for p in prompts if p["title"] == "Telemetry Check"]
+        self.assertEqual(len(saved), 1)
+        self.assertEqual(saved[0]["prompt"], "Check loop telemetry on all nodes")
+
+        # /prompt add
+        self.tui._execute_input_line("/prompt add Quick Probe | ping all nodes")
+        saved_add = [p for p in self.tui.prompt_manager.get_sorted_prompts() if p["title"] == "Quick Probe"]
+        self.assertEqual(len(saved_add), 1)
+        self.assertEqual(saved_add[0]["prompt"], "ping all nodes")
+
+        # /prompt del
+        self.tui._execute_input_line(f"/prompt del {saved_add[0]['id']}")
+        saved_del = [p for p in self.tui.prompt_manager.get_sorted_prompts() if p["title"] == "Quick Probe"]
+        self.assertEqual(len(saved_del), 0)
+
+        # /sends opens history search
+        self.tui._execute_input_line("/sends docker")
+        self.assertEqual(self.tui.modal, "history_search")
+        self.assertEqual(self.tui.modal_input_buf, "docker")
+
+    def test_shelf_buttons_mouse_clicks(self):
+        """Verify clicking buttons on row 0 of prompt shelf opens modals and scrolls."""
+        self.tui._render_prompt_shelf(y=24, x=0, h=2, w=100)
+
+        # Click [P:Expand]
+        exp_x = (self.tui._btn_expand_bounds[0] + self.tui._btn_expand_bounds[1]) // 2
+        self.tui._handle_mouse(mx=exp_x, my=24, bstate=curses.BUTTON1_CLICKED)
+        self.assertEqual(self.tui.modal, "prompts")
+        self.tui.modal = None
+
+        # Click [🔍 Sends]
+        sends_x = (self.tui._btn_sends_bounds[0] + self.tui._btn_sends_bounds[1]) // 2
+        self.tui._handle_mouse(mx=sends_x, my=24, bstate=curses.BUTTON1_CLICKED)
+        self.assertEqual(self.tui.modal, "history_search")
+        self.tui.modal = None
+
+        # Click [►]
+        next_x = (self.tui._btn_next_bounds[0] + self.tui._btn_next_bounds[1]) // 2
+        self.tui.prompt_scroll_idx = 0
+        self.tui._handle_mouse(mx=next_x, my=24, bstate=curses.BUTTON1_CLICKED)
+        self.assertEqual(self.tui.prompt_scroll_idx, 1)
+
+        # Click [◄]
+        prev_x = (self.tui._btn_prev_bounds[0] + self.tui._btn_prev_bounds[1]) // 2
+        self.tui._handle_mouse(mx=prev_x, my=24, bstate=curses.BUTTON1_CLICKED)
+        self.assertEqual(self.tui.prompt_scroll_idx, 0)
+
+    def test_mouse_wheel_scrolling_on_shelf(self):
+        """Verify mouse wheel up/down over prompt shelf scrolls chips."""
+        self.tui._render_prompt_shelf(y=24, x=0, h=2, w=100)
+        self.tui.prompt_scroll_idx = 0
+
+        # Wheel down over prompt shelf (my=25)
+        self.tui._handle_mouse(mx=50, my=25, bstate=0x200000)
+        self.assertEqual(self.tui.prompt_scroll_idx, 1)
+
+        # Wheel up over prompt shelf (my=25)
+        self.tui._handle_mouse(mx=50, my=25, bstate=0x10000)
+        self.assertEqual(self.tui.prompt_scroll_idx, 0)
+
+    def test_prompt_modal_pin_toggle_and_delete(self):
+        """Verify 'p' toggles pin and 'd' deletes in prompt modal."""
+        self.tui.modal = "prompts"
+        self.tui.prompt_sel_idx = 0
+        target = self.tui.prompts[0]
+        initial_pin = target.get("pinned", False)
+
+        # Press 'p' to toggle pin
+        self.tui._handle_key(ord('p'))
+        toggled = [p for p in self.tui.prompts if p["id"] == target["id"]][0]
+        self.assertEqual(toggled.get("pinned", False), not initial_pin)
+
+        # Now select the prompt and press 'd' to delete
+        target_idx = [i for i, p in enumerate(self.tui.prompts) if p["id"] == target["id"]][0]
+        self.tui.prompt_sel_idx = target_idx
+        self.tui._handle_key(ord('d'))
+        self.assertFalse(any(p["id"] == target["id"] for p in self.tui.prompts))
+
+    def test_formulate_prompt_modal(self):
+        """Verify prompt_formulate modal creates and saves new prompt."""
+        self.tui.modal = "prompt_formulate"
+        self.tui.input_buf = "Draft message from input composer"
+        self.tui.modal_input_buf = "New Diagnostic"
+        self.tui.modal_input_cursor = len(self.tui.modal_input_buf)
+
+        # Press Enter
+        self.tui._handle_key(10)
+        self.assertIsNone(self.tui.modal)
+
+        # Check prompt exists in manager
+        matching = [p for p in self.tui.prompts if p["title"] == "New Diagnostic"]
+        self.assertEqual(len(matching), 1)
+        self.assertEqual(matching[0]["prompt"], "Draft message from input composer")
+        self.assertTrue(matching[0]["pinned"])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_rate_limits.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""
+test_rate_limits.py — Tests for rate-limiting, adaptive polling, backoff, and circuit breaker.
+"""
+import curses
+import importlib.util
+import json
+import os
+import sys
+import time
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+MUSE_TUI_PATH = REPO_ROOT / "bin" / "muse-tui.py"
+
+spec = importlib.util.spec_from_file_location("muse_tui_rl", MUSE_TUI_PATH)
+muse_tui_rl = importlib.util.module_from_spec(spec)
+sys.modules["muse_tui_rl"] = muse_tui_rl
+spec.loader.exec_module(muse_tui_rl)
+
+FleetDataManager = muse_tui_rl.FleetDataManager
+MuseTUI = muse_tui_rl.MuseTUI
+run_command_isolated = muse_tui_rl.run_command_isolated
+
+
+class TestRateLimitingAndBackoff(unittest.TestCase):
+    def setUp(self):
+        # In tests, start_poller is disabled by default
+        self.mgr = FleetDataManager(start_poller=False)
+
+    def test_poller_disabled_in_tests_by_default(self):
+        """FleetDataManager does not leak background poller threads during unit test runs."""
+        self.assertIsNone(self.mgr.poller_thread)
+
+    def test_rate_limit_cooldown_marking(self):
+        """Marking a node as rate-limited sets cooldown window and rate_limited flag."""
+        self.assertFalse(self.mgr.is_node_rate_limited("muse"))
+        self.assertEqual(self.mgr.get_node_cooldown_remaining("muse"), 0)
+
+        self.mgr.mark_node_rate_limited("muse", cooldown_seconds=30.0, reason="HTTP 429")
+        self.assertTrue(self.mgr.is_node_rate_limited("muse"))
+        self.assertGreater(self.mgr.get_node_cooldown_remaining("muse"), 20)
+        self.assertTrue(self.mgr.node_status["muse"]["rate_limited"])
+
+    def test_tiered_backoff_progression(self):
+        """Consecutive rate-limit occurrences escalate (30s -> 60s -> 120s max), and clear resets."""
+        # Incident 1: 30s
+        self.mgr.mark_node_rate_limited("pip", reason="429 first")
+        cd1 = self.mgr.get_node_cooldown_remaining("pip")
+        self.assertTrue(25 <= cd1 <= 31)
+
+        # Incident 2: 60s
+        self.mgr.mark_node_rate_limited("pip", reason="429 second")
+        cd2 = self.mgr.get_node_cooldown_remaining("pip")
+        self.assertTrue(55 <= cd2 <= 61)
+
+        # Incident 3: 120s max
+        self.mgr.mark_node_rate_limited("pip", reason="429 third")
+        cd3 = self.mgr.get_node_cooldown_remaining("pip")
+        self.assertTrue(110 <= cd3 <= 121)
+
+        # Success resets backoff
+        self.mgr.clear_node_rate_limit("pip")
+        self.assertFalse(self.mgr.is_node_rate_limited("pip"))
+        self.assertEqual(self.mgr.get_node_cooldown_remaining("pip"), 0)
+        self.assertEqual(self.mgr.rate_limit_consecutive["pip"], 0)
+
+    def test_retry_after_header_parsing(self):
+        """When output includes Retry-After, that explicit duration is used."""
+        with patch.object(muse_tui_rl, "run_command_isolated", return_value=(1, "", "Error 429: Too Many Requests. Retry-After: 85")):
+            self.mgr._fetch_history("646", "thread-xyz")
+            self.assertTrue(self.mgr.is_node_rate_limited("646"))
+            cd = self.mgr.get_node_cooldown_remaining("646")
+            self.assertTrue(80 <= cd <= 86)
+
+    def test_rate_limited_node_skips_fetches(self):
+        """Rate-limited nodes are skipped by _fetch_history and _run_fetch_threads."""
+        self.mgr.mark_node_rate_limited("muse", cooldown_seconds=60.0)
+
+        with patch.object(muse_tui_rl, "run_command_isolated") as mock_cmd:
+            self.mgr._fetch_history("muse", "thread-123")
+            mock_cmd.assert_not_called()
+
+            self.mgr._run_fetch_threads("muse")
+            mock_cmd.assert_not_called()
+
+    def test_rate_limit_detection_from_command_output(self):
+        """When CLI command outputs 429 or rate limit text, node is placed on cooldown."""
+        with patch.object(muse_tui_rl, "run_command_isolated", return_value=(1, "", "Error 429: Too Many Requests")):
+            self.mgr._fetch_history("pip", "thread-abc")
+            self.assertTrue(self.mgr.is_node_rate_limited("pip"))
+            self.assertGreater(self.mgr.get_node_cooldown_remaining("pip"), 0)
+
+    def test_record_activity_updates_timestamp(self):
+        """record_activity updates last_user_activity timestamp."""
+        old_time = self.mgr.last_user_activity
+        time.sleep(0.01)
+        self.mgr.record_activity()
+        self.assertGreaterEqual(self.mgr.last_user_activity, old_time)
+
+    def test_run_command_isolated_handles_quick_command(self):
+        """run_command_isolated runs a command and returns returncode, stdout, stderr."""
+        rc, stdout, stderr = run_command_isolated(["echo", "hello rate limit"], timeout=2.0)
+        self.assertEqual(rc, 0)
+        self.assertIn("hello rate limit", stdout)
+
+    def test_run_command_isolated_terminates_on_timeout(self):
+        """run_command_isolated cleanly kills process group on timeout without zombies."""
+        rc, stdout, stderr = run_command_isolated(["sleep", "10"], timeout=0.1)
+        self.assertEqual(rc, -1)
+        self.assertIn("timed out", stderr)
+
+
+class TestRateLimitUserInteraction(unittest.TestCase):
+    def setUp(self):
+        self.mock_stdscr = MagicMock()
+        self.mock_stdscr.getmaxyx.return_value = (30, 100)
+        self.mock_stdscr.getch.return_value = -1
+        self.tui = MuseTUI(self.mock_stdscr, initial_mode="muse", initial_node="muse")
+        self.tui.safe_addstr = MagicMock()
+
+    def test_soft_guardrail_send_during_cooldown(self):
+        """Sending during cooldown warns on first Enter, preserves buffer, and forces on second Enter."""
+        self.tui.data.mark_node_rate_limited("muse", cooldown_seconds=30.0)
+        self.tui.editor_mode = "INSERT"
+        self.tui.input_buf = "Status report please"
+        self.tui.input_cursor = len(self.tui.input_buf)
+
+        # First Enter tap: warns and does not clear input_buf
+        with patch.object(self.tui, "_async_send_message") as mock_send:
+            self.tui._handle_insert_key(10)
+            mock_send.assert_not_called()
+            self.assertEqual(self.tui.input_buf, "Status report please")
+            self.assertIn("cooldown", self.tui.toast_msg)
+            self.assertIn("Press Enter again", self.tui.toast_msg)
+
+        # Second Enter tap within 2.5s: bypasses cooldown, loads into history, and delivers
+        with patch("threading.Thread") as mock_thread:
+            self.tui._handle_insert_key(10)
+            self.assertFalse(self.tui.data.is_node_rate_limited("muse"))
+            self.assertIn("Sending message to MUSE", self.tui.toast_msg)
+            self.assertEqual(self.tui.input_buf, "")
+            # Ensure message was immediately loaded into history cache!
+            msgs = self.tui.data.history_cache.get(("muse", self.tui.data.active_thread_id), [])
+            self.assertTrue(any(m.get("text") == "Status report please" and m.get("role") == "user" for m in msgs))
+
+    def test_two_tap_manual_sync_override(self):
+        """Pressing 'r' during cooldown warns on first press and bypasses cooldown on double-tap."""
+        self.tui.data.mark_node_rate_limited("muse", cooldown_seconds=45.0)
+
+        # First 'r' tap: warns
+        self.tui._handle_normal_key(ord('r'))
+        self.assertTrue(self.tui.data.is_node_rate_limited("muse"))
+        self.assertIn("cooling down", self.tui.toast_msg)
+        self.assertIn("Press 'r' again", self.tui.toast_msg)
+
+        # Second 'r' tap within 2s: clears rate limit and forces sync
+        with patch.object(self.tui.data, "lazy_fetch_threads") as mock_fetch:
+            self.tui._handle_normal_key(ord('r'))
+            self.assertFalse(self.tui.data.is_node_rate_limited("muse"))
+            self.assertIn("Force-syncing", self.tui.toast_msg)
+            mock_fetch.assert_called_with("muse", force=True)
+
+    def test_agent_context_menu_sync_override(self):
+        """Context menu 'sync' action also respects two-tap override during cooldown."""
+        self.tui.data.mark_node_rate_limited("pip", cooldown_seconds=30.0)
+        self.tui.context_agent = {"node": "pip"}
+
+        # First selection: warns
+        self.tui._execute_agent_action("sync")
+        self.assertTrue(self.tui.data.is_node_rate_limited("pip"))
+        self.assertIn("cooling down", self.tui.toast_msg)
+
+        # Second selection within 2s: forces sync
+        with patch.object(self.tui.data, "lazy_fetch_threads") as mock_fetch:
+            self.tui._execute_agent_action("sync")
+            self.assertFalse(self.tui.data.is_node_rate_limited("pip"))
+            self.assertIn("Force-syncing", self.tui.toast_msg)
+            mock_fetch.assert_called_with("pip", force=True)
+
+    def test_optimistic_message_persistence_across_fetch(self):
+        """Optimistic user messages are preserved even if server history lags behind."""
+        self.tui.data.history_cache[("muse", "sess-test")] = []
+        self.tui.data.add_optimistic_message("muse", "sess-test", "New uncommitted instruction")
+        cached = self.tui.data.history_cache.get(("muse", "sess-test"), [])
+        self.assertEqual(len(cached), 1)
+        self.assertEqual(cached[0]["text"], "New uncommitted instruction")
+
+        # Simulate remote fetch returning older history that doesn't yet have the new message
+        old_server_msgs = [{"role": "assistant", "text": "Earlier reply"}]
+        with patch.object(muse_tui_rl, "run_command_isolated", return_value=(0, json.dumps(old_server_msgs), "")):
+            self.tui.data._fetch_history("muse", "sess-test")
+            updated = self.tui.data.history_cache.get(("muse", "sess-test"), [])
+            # Both the older server message AND the pending user message should exist!
+            self.assertEqual(len(updated), 2)
+            self.assertEqual(updated[0]["text"], "Earlier reply")
+            self.assertEqual(updated[1]["text"], "New uncommitted instruction")
+
+
+if __name__ == "__main__":
+    import json
+    unittest.main()

tests/test_scrollback.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""
+test_scrollback.py — Comprehensive unit and integration test suite for:
+1. Transcript scrollback rendering, line wrapping, and frame cache.
+2. Jump-to-top ('g', Home) and bounds-capped scrolling ('k', Up arrow, PgUp).
+3. Immediate downward movement ('j', Down arrow, PgDn) without 9999 offset blockage.
+4. Jump-to-bottom ('G', End) re-engaging auto_scroll = True.
+5. Thread and node switching resetting transcript scroll offset to 0.
+6. Message send input line execution resetting scroll offset to bottom.
+7. Mouse wheel scrolling within bounds.
+"""
+
+import unittest
+from unittest.mock import MagicMock, patch
+import importlib.util
+from pathlib import Path
+import curses
+
+REPO_ROOT = Path("/home/super/Projects/NetVM")
+TUI_PATH = REPO_ROOT / "bin" / "muse-tui.py"
+
+spec = importlib.util.spec_from_file_location("muse_tui", str(TUI_PATH))
+muse_mod = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(muse_mod)
+
+
+class TestScrollbackSubsystem(unittest.TestCase):
+    """Test suite covering transcript scrollback, bounds clamping, and cache performance."""
+
+    def setUp(self):
+        self.mock_stdscr = MagicMock()
+        self.mock_stdscr.getmaxyx.return_value = (30, 100)
+        self.tui = muse_mod.MuseTUI(self.mock_stdscr, initial_mode="muse", initial_node="muse")
+        self.tui.safe_addstr = MagicMock()
+
+        # Seed realistic history cache (50 messages, multi-line)
+        test_msgs = []
+        for i in range(50):
+            role = "user" if i % 2 == 0 else "assistant"
+            test_msgs.append({
+                "role": role,
+                "text": f"Message {i}: This is a test message to simulate rich chat transcript history.\nLine 2 of message {i}",
+                "seq": i,
+                "message_id": f"msg-{i:04d}",
+            })
+        self.tui.data.history_cache[("muse", "test_thread")] = test_msgs
+        self.tui.data.active_node = "muse"
+        self.tui.data.active_thread_id = "test_thread"
+        self.tui.data.active_thread_title = "Test Thread"
+
+    def test_initial_render_and_line_caching(self):
+        """Verify _render_transcript populates cache and calculates total lines."""
+        self.tui._render_transcript(y=2, x=24, h=26, w=76)
+
+        total_lines = self.tui.transcript_total_lines
+        self.assertGreater(total_lines, 50, "50 multi-line messages should yield > 50 rendered lines")
+        self.assertIsNotNone(self.tui._transcript_cache_key)
+        self.assertGreater(len(self.tui._transcript_cache_lines), 0)
+        self.assertTrue(self.tui.auto_scroll)
+        self.assertEqual(self.tui.transcript_scroll_offset, 0)
+
+        # Re-render with same parameters: should hit cache without recomputing lines
+        cached_lines_ref = self.tui._transcript_cache_lines
+        self.tui._render_transcript(y=2, x=24, h=26, w=76)
+        self.assertIs(self.tui._transcript_cache_lines, cached_lines_ref)
+
+    def test_jump_to_top_and_down_scrolling(self):
+        """Verify 'g' jumps to top without 9999 offset bug, and 'j' immediately scrolls down."""
+        # 1. Initial render to establish dimensions
+        self.tui._render_transcript(y=2, x=24, h=26, w=76)
+        max_scroll = max(0, self.tui.transcript_total_lines - self.tui.transcript_height)
+        self.assertGreater(max_scroll, 0)
+
+        # 2. Press 'g' (or Home) to jump to top
+        self.tui.focus_pane = "transcript"
+        handled = self.tui._handle_normal_key(ord('g'))
+        self.assertTrue(handled)
+        self.assertFalse(self.tui.auto_scroll)
+        self.assertEqual(self.tui.transcript_scroll_offset, max_scroll, "Jump to top must equal max_scroll, not 9999")
+
+        # 3. Press 'j' (Down arrow) to scroll down by 3 lines
+        handled = self.tui._handle_normal_key(ord('j'))
+        self.assertTrue(handled)
+        self.assertEqual(self.tui.transcript_scroll_offset, max_scroll - 3, "Down arrow must immediately decrement offset")
+
+        # 4. Render frame: bounds check should preserve offset
+        self.tui._render_transcript(y=2, x=24, h=26, w=76)
+        self.assertEqual(self.tui.transcript_scroll_offset, max_scroll - 3)
+
+    def test_jump_to_bottom_re_engages_auto_scroll(self):
+        """Verify 'G' (or End) resets offset to 0 and re-engages auto_scroll."""
+        self.tui._render_transcript(y=2, x=24, h=26, w=76)
+        self.tui.focus_pane = "transcript"
+
+        # Scroll up
+        self.tui._handle_normal_key(ord('k'))
+        self.assertFalse(self.tui.auto_scroll)
+        self.assertGreater(self.tui.transcript_scroll_offset, 0)
+
+        # Press 'G' to jump to bottom
+        handled = self.tui._handle_normal_key(ord('G'))
+        self.assertTrue(handled)
+        self.assertTrue(self.tui.auto_scroll)
+        self.assertEqual(self.tui.transcript_scroll_offset, 0)
+
+    def test_uncapped_scroll_up_prevented(self):
+        """Verify repeated 'k' / PageUp keys never exceed max_scroll."""
+        self.tui._render_transcript(y=2, x=24, h=26, w=76)
+        self.tui.focus_pane = "transcript"
+        max_scroll = max(0, self.tui.transcript_total_lines - self.tui.transcript_height)
+
+        # Hammer scroll up 100 times
+        for _ in range(100):
+            self.tui._handle_normal_key(ord('k'))
+
+        self.assertEqual(self.tui.transcript_scroll_offset, max_scroll, "Scroll offset must be capped at max_scroll")
+
+        # Render frame
+        self.tui._render_transcript(y=2, x=24, h=26, w=76)
+        self.assertEqual(self.tui.transcript_scroll_offset, max_scroll)
+
+    def test_mouse_wheel_scrolling(self):
+        """Verify mouse wheel up scrolls up and mouse wheel down scrolls back to auto_scroll."""
+        self.tui._render_transcript(y=2, x=24, h=26, w=76)
+        content_y, content_h = 2, 26
+        sidebar_w = 24
+        transcript_mx = sidebar_w + 10  # Mouse inside transcript pane
+        transcript_my = content_y + 5
+
+        # Mouse wheel up mask
+        wheel_up_mask = 0x10000
+        self.tui._handle_mouse(transcript_mx, transcript_my, wheel_up_mask)
+        self.assertFalse(self.tui.auto_scroll)
+        self.assertEqual(self.tui.transcript_scroll_offset, 3)
+
+        # Mouse wheel down mask (curses.BUTTON5_PRESSED or 0x200000)
+        wheel_down_mask = getattr(curses, "BUTTON5_PRESSED", 0x200000)
+        self.tui._handle_mouse(transcript_mx, transcript_my, wheel_down_mask)
+        self.assertEqual(self.tui.transcript_scroll_offset, 0)
+        self.assertTrue(self.tui.auto_scroll)
+
+    def test_target_switch_resets_scroll(self):
+        """Verify switching active node or thread automatically resets scroll state."""
+        self.tui._render_transcript(y=2, x=24, h=26, w=76)
+        self.tui.focus_pane = "transcript"
+        self.tui._handle_normal_key(ord('g'))  # Scrolled all the way up
+        self.assertFalse(self.tui.auto_scroll)
+        self.assertGreater(self.tui.transcript_scroll_offset, 0)
+
+        # Switch to another thread
+        self.tui.data.history_cache[("muse", "other_thread")] = [
+            {"role": "user", "text": "Hello new thread", "seq": 1, "message_id": "m1"}
+        ]
+        self.tui.data.active_thread_id = "other_thread"
+
+        # Next render detects target switch
+        self.tui._render_transcript(y=2, x=24, h=26, w=76)
+        self.assertTrue(self.tui.auto_scroll, "Target switch must restore auto_scroll")
+        self.assertEqual(self.tui.transcript_scroll_offset, 0, "Target switch must reset transcript_scroll_offset")
+
+    def test_message_send_resets_scroll(self):
+        """Verify sending a chat message resets scroll offset to follow live response."""
+        self.tui._render_transcript(y=2, x=24, h=26, w=76)
+        self.tui.focus_pane = "transcript"
+        self.tui._handle_normal_key(ord('g'))
+        self.assertFalse(self.tui.auto_scroll)
+        self.assertGreater(self.tui.transcript_scroll_offset, 0)
+
+        # Mock async send to avoid actual network / subprocess calls
+        with patch.object(self.tui, "_async_send_message"):
+            self.tui._execute_input_line("Test message from operator")
+
+        self.assertTrue(self.tui.auto_scroll, "Message send must restore auto_scroll")
+        self.assertEqual(self.tui.transcript_scroll_offset, 0, "Message send must reset scroll offset to 0")
+
+    def test_insert_mode_typing_and_batch_processing(self):
+        """Verify insert mode appends characters and updates cursor cleanly."""
+        self.tui.editor_mode = "INSERT"
+        for ch in "hello netvm":
+            handled = self.tui._handle_insert_key(ord(ch))
+            self.assertTrue(handled)
+        self.assertEqual(self.tui.input_buf, "hello netvm")
+        self.assertEqual(self.tui.input_cursor, 11)
+
+        # Backspace
+        self.tui._handle_insert_key(curses.KEY_BACKSPACE)
+        self.assertEqual(self.tui.input_buf, "hello netv")
+        self.assertEqual(self.tui.input_cursor, 10)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_tool_calls.py

@@ -0,0 +1,271 @@
+"""Tests for TOOL/DM directive parsing, native aliases, and the
+box.exec / tools.list exec ops (dynamic in-band message passing)."""
+import importlib.util
+import json
+import re
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+def _load(mod_name, rel_path):
+    spec = importlib.util.spec_from_file_location(mod_name, REPO_ROOT / rel_path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+harv = _load("harvester_tool_calls", "bin/response-harvester.py")
+exc = _load("exec_constrained_tool_calls", "bin/exec-constrained.py")
+env = _load("prompt_envelope_tool_calls", "bin/prompt_envelope.py")
+
+
+class ParseToolCalls(unittest.TestCase):
+    def test_simple(self):
+        self.assertEqual(
+            harv.parse_tool_calls("[TOOL health.check {}]"),
+            [("health.check", {})],
+        )
+
+    def test_exec_engine(self):
+        calls = harv.parse_tool_calls('[EXEC cron.runs {"limit": 3}]')
+        self.assertEqual(calls, [("cron.runs", {"limit": 3})])
+
+    def test_bracket_inside_json_survives(self):
+        text = '[TOOL box.exec {"action": "job-get", "arg": "a-b[0]"}]'
+        self.assertEqual(
+            harv.parse_tool_calls(text),
+            [("box.exec", {"action": "job-get", "arg": "a-b[0]"})],
+        )
+
+    def test_nested_objects_and_arrays(self):
+        args = {"outer": {"inner": [1, 2, {"k": "v]w"}]}, "list": ["a", "b]c"]}
+        text = "[TOOL swarm.spawn %s]" % json.dumps(args)
+        self.assertEqual(harv.parse_tool_calls(text), [("swarm.spawn", args)])
+
+    def test_escaped_quotes_and_braces_in_strings(self):
+        args = {"prompt": 'say "{hi}" \\ done'}
+        text = "[TOOL followup.create %s]" % json.dumps(args)
+        op, got = harv.parse_tool_calls(text)[0]
+        self.assertEqual(op, "followup.create")
+        self.assertEqual(got["prompt"], args["prompt"])
+
+    def test_dm_shorthand(self):
+        text = '[DM {"to": "pip", "target": "pip tasks", "message": "hi [you]"}]'
+        self.assertEqual(
+            harv.parse_tool_calls(text),
+            [("dm.send", {"to": "pip", "target": "pip tasks", "message": "hi [you]"})],
+        )
+
+    def test_dm_bare_form_skipped(self):
+        self.assertEqual(harv.parse_tool_calls("[DM hello pip]"), [])
+
+    def test_no_args(self):
+        self.assertEqual(
+            harv.parse_tool_calls("[TOOL cron.runs]"), [("cron.runs", {})]
+        )
+
+    def test_legacy_raw_passthrough(self):
+        self.assertEqual(
+            harv.parse_tool_calls("[TOOL foo bar baz]"),
+            [("foo", {"raw": "bar baz"})],
+        )
+
+    def test_broken_json_skipped(self):
+        self.assertEqual(harv.parse_tool_calls("[TOOL foo {bad}]"), [])
+
+    def test_fenced_block(self):
+        text = '```tool\n{"op": "health.check", "args": {}}\n```'
+        self.assertEqual(harv.parse_tool_calls(text), [("health.check", {})])
+
+    def test_dedupe_repeated_call(self):
+        text = "[TOOL health.check {}] ... [TOOL health.check {}]"
+        self.assertEqual(harv.parse_tool_calls(text), [("health.check", {})])
+
+    def test_native_aliases_applied(self):
+        text = '[TOOL subagent.spawn {"count": 1, "task": "t"}]'
+        self.assertEqual(
+            harv.parse_tool_calls(text),
+            [("swarm.spawn", {"count": 1, "task": "t"})],
+        )
+        text = '[TOOL cron.create {"kind": "runonce", "in_m": 5, "prompt": "p"}]'
+        op, args = harv.parse_tool_calls(text)[0]
+        self.assertEqual(op, "followup.create")
+        self.assertNotIn("kind", args)
+        self.assertEqual(args["in_m"], 5)
+
+
+class NormalizeNativeCall(unittest.TestCase):
+    def test_dm_synonyms(self):
+        op, args = harv.normalize_native_call(
+            "dm", {"to": "pip", "thread": "pip tasks", "text": "hi"})
+        self.assertEqual(op, "dm.send")
+        self.assertEqual(args["message"], "hi")
+        self.assertEqual(args["target"], "pip tasks")
+
+    def test_box_synonyms(self):
+        op, args = harv.normalize_native_call("box", {"cmd": "fleet-status"})
+        self.assertEqual((op, args), ("box.exec", {"action": "fleet-status"}))
+
+    def test_tools_alias(self):
+        op, args = harv.normalize_native_call("tools", {})
+        self.assertEqual(op, "tools.list")
+
+
+class FormatToolResult(unittest.TestCase):
+    def test_tools_list_grouping(self):
+        out = harv.format_tool_result_for_chat("tools.list", json.dumps({
+            "ok": True,
+            "ops": [
+                {"op": "health.check", "side_effecting": False},
+                {"op": "dm.send", "side_effecting": True},
+            ],
+        }))
+        self.assertIn("2 tools", out)
+        self.assertIn("health.check", out)
+        self.assertIn("dm.send", out)
+
+    def test_box_exec_string_fenced(self):
+        out = harv.format_tool_result_for_chat("box.exec", "NODE UP")
+        self.assertIn("```", out)
+        self.assertIn("NODE UP", out)
+
+    def test_box_exec_string_truncated(self):
+        out = harv.format_tool_result_for_chat("box.exec", "x" * 2000)
+        self.assertIn("truncated", out)
+        self.assertLess(len(out), 1200)
+
+    def test_box_exec_json_dict_passthrough(self):
+        out = harv.format_tool_result_for_chat(
+            "box.exec", json.dumps({"ok": True, "nodes": []}))
+        self.assertIn("```", out)
+        self.assertIn('"nodes": []', out)
+
+    def test_box_exec_json_error(self):
+        out = harv.format_tool_result_for_chat(
+            "box.exec", json.dumps({"ok": False, "error": "BAD_NAME"}))
+        self.assertIn("BAD_NAME", out)
+
+
+class BoxExecOp(unittest.TestCase):
+    def test_noarg_ok(self):
+        self.assertEqual(
+            exc._box_exec_validate({"action": "fleet-status"}),
+            {"action": "fleet-status"},
+        )
+
+    def test_agent_key_tolerated(self):
+        self.assertEqual(
+            exc._box_exec_validate({"action": "unread", "agent": "646"}),
+            {"action": "unread"},
+        )
+
+    def test_onearg_ok(self):
+        self.assertEqual(
+            exc._box_exec_validate({"action": "job-get", "arg": "abc-123"}),
+            {"action": "job-get", "arg": "abc-123"},
+        )
+
+    def test_rejects_unknown_action(self):
+        with self.assertRaises(exc.OpError):
+            exc._box_exec_validate({"action": "job-trigger"})
+
+    def test_rejects_side_effecting(self):
+        for action in ("vars-set", "job-delete", "timer-create", "md-write"):
+            with self.assertRaises(exc.OpError, msg=action):
+                exc._box_exec_validate({"action": action})
+
+    def test_rejects_excluded_idempotent(self):
+        for action in ("main-loop", "quality-validate", "git-diff", "job-next"):
+            with self.assertRaises(exc.OpError, msg=action):
+                exc._box_exec_validate({"action": action})
+
+    def test_rejects_bad_arg(self):
+        for bad in ("../x", "a b", "a;b", "", "x" * 200):
+            with self.assertRaises(exc.OpError, msg=bad):
+                exc._box_exec_validate({"action": "job-get", "arg": bad})
+
+    def test_rejects_arg_on_noarg_action(self):
+        with self.assertRaises(exc.OpError):
+            exc._box_exec_validate({"action": "fleet-status", "arg": "x"})
+
+    def test_build_argv(self):
+        argv = exc._box_exec_build({"action": "job-get", "arg": "abc"})
+        self.assertEqual(argv[-2:], ["job-get", "abc"])
+        self.assertTrue(argv[1].endswith("box-ctl.py"))
+
+    def test_registered_read_only(self):
+        self.assertIn("box.exec", exc.OPS)
+        self.assertFalse(exc.OPS["box.exec"]["side_effecting"])
+        self.assertIn("tools.list", exc.OPS)
+        self.assertFalse(exc.OPS["tools.list"]["side_effecting"])
+
+    def test_permissions_cover_agents(self):
+        for ident in ("muse", "pip", "646", "opm", "dev", "def"):
+            self.assertIn("box.exec", exc.PERMISSIONS[ident])
+            self.assertIn("tools.list", exc.PERMISSIONS[ident])
+
+    def test_list_ops_subcommand(self):
+        p = subprocess.run(
+            [sys.executable, str(REPO_ROOT / "bin" / "exec-constrained.py"),
+             "--list-ops"],
+            capture_output=True, text=True, timeout=30,
+        )
+        self.assertEqual(p.returncode, 0)
+        data = json.loads(p.stdout)
+        self.assertTrue(data["ok"])
+        names = {o["op"] for o in data["ops"]}
+        for want in ("box.exec", "tools.list", "dm.send", "swarm.spawn",
+                     "health.check", "followup.create"):
+            self.assertIn(want, names)
+
+
+class CanonicalToolPattern(unittest.TestCase):
+    def test_samples_match(self):
+        data = json.loads(
+            (REPO_ROOT / "lookup_internal" / "regex_patterns.json").read_text())
+        pat = data["patterns"]["tool_call"]["pattern"]
+        rx = re.compile(pat, re.S)
+        for s in data["patterns"]["tool_call"]["test_samples"]["valid"]:
+            self.assertIsNotNone(rx.search(s), s)
+        for s in data["patterns"]["tool_call"]["test_samples"]["invalid"]:
+            self.assertIsNone(rx.search(s), s)
+
+    def test_dm_sample_has_no_op(self):
+        data = json.loads(
+            (REPO_ROOT / "lookup_internal" / "regex_patterns.json").read_text())
+        rx = re.compile(data["patterns"]["tool_call"]["pattern"], re.S)
+        m = rx.search('[DM {"to": "pip"}]')
+        self.assertIsNotNone(m)
+        self.assertEqual(m.group("engine"), "DM")
+        self.assertIsNone(m.group("op"))
+
+
+class EnvelopeRoundTrip(unittest.TestCase):
+    def test_wrap_advertises_new_verbs(self):
+        body = env.wrap("work-finder", "work-finder-1", "646",
+                        "646 tasks", "Do the thing.")
+        for token in ("dm.send", "box.exec", "tools.list", "[DM {"):
+            self.assertIn(token, body)
+
+    def test_spawn_call_parses(self):
+        text = env.spawn_call("jid-1", "work-finder", "work")
+        op, args = harv.parse_tool_calls(text)[0]
+        self.assertEqual(op, "swarm.spawn")
+        self.assertIn("count", args)
+        self.assertIn("task", args)
+
+    def test_dm_call_parses(self):
+        text = env.dm_call("pip", "pip tasks", "hello [brackets] work")
+        self.assertEqual(
+            harv.parse_tool_calls(text),
+            [("dm.send", {"to": "pip", "target": "pip tasks",
+                          "message": "hello [brackets] work"})],
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

web/box/www/box.js

@@ -67,7 +67,7 @@
 
     // Check hash on load
     const hash = window.location.hash.replace('#', '');
-    if (['dashboard', 'dms', 'jobs', 'loops'].includes(hash)) {
+    if (['dashboard', 'dms', 'jobs', 'loops', 'lookup'].includes(hash)) {
       switchTab(hash);
     }
   }
@@ -1188,6 +1188,8 @@
       codeEl.textContent = `curl -s -H "Authorization: Bearer <token>" \\\n  https://box.muse-dev.online/api/box/timers`;
     } else if (currentTab === 'loops') {
       codeEl.textContent = `curl -s -H "Authorization: Bearer <token>" \\\n  https://box.muse-dev.online/api/box/loop/status\n\ncurl -s -H "Authorization: Bearer <token>" \\\n  https://box.muse-dev.online/api/box/loop/health`;
+    } else if (currentTab === 'lookup') {
+      codeEl.textContent = `curl -s -H "Authorization: Bearer <token>" \\\n  https://box.muse-dev.online/api/box/lookup\n\n# Or CLI lookup on bl:\nbox lookup surfaces\nbox lookup parse "[RESULT 7fce46e0] OK Done"`;
     }
   }
 
@@ -1278,6 +1280,171 @@
     }
   }
 
+  // -------------------------------------------------------------------------
+  // 8. Lookup & Grammar Surface Integration
+  // -------------------------------------------------------------------------
+  window.setLookupPreset = function (text) {
+    const input = document.getElementById('lookup-test-input');
+    if (input) {
+      input.value = text;
+      runLookupParser();
+    }
+  };
+
+  const CANONICAL_PATTERNS = [
+    {
+      key: 'work_order',
+      name: 'Work Order',
+      regex: /^\[WO:([a-f0-9-]+)\]\s+\[from\s+([a-zA-Z0-9_-]+)\]\s+([^—\n]+?)\s*—\s*(.+)$/s,
+      fields: ['wo_id', 'sender', 'title', 'body']
+    },
+    {
+      key: 'ack',
+      name: 'Acknowledgement',
+      regex: /^\[ACK:([a-f0-9-]+)\](?:\s+\[from\s+([a-zA-Z0-9_-]+)\])?/,
+      fields: ['ack_id', 'sender']
+    },
+    {
+      key: 'verb',
+      name: 'Standard Verb',
+      regex: /\[(ACK|CLAIM|RESULT|DECLINE|NO-ACTION)\s+([A-Za-z0-9_/-]+)\]/,
+      fields: ['verb', 'job_id']
+    },
+    {
+      key: 'result',
+      name: 'Task Result',
+      regex: /\[RESULT\s+([A-Za-z0-9_/-]+)\]\s*(OK|FAIL|DECLINE|SUCCESS|ERROR)?\s*(.*?)(?=\[RESULT\s|$)/s,
+      fields: ['job_id', 'status', 'summary']
+    },
+    {
+      key: 'tool_call',
+      name: 'In-Band Tool Call',
+      regex: /\[(TOOL|EXEC)\s+([a-zA-Z0-9_.-]+)\s+(\{.*?\})\]/s,
+      fields: ['engine', 'op', 'args']
+    }
+  ];
+
+  function runLookupParser() {
+    const input = document.getElementById('lookup-test-input');
+    const resBox = document.getElementById('lookup-parse-result');
+    if (!input || !resBox) return;
+
+    const val = input.value.trim();
+    if (!val) {
+      resBox.style.display = 'none';
+      return;
+    }
+
+    const matches = [];
+    CANONICAL_PATTERNS.forEach(pat => {
+      const m = pat.regex.exec(val);
+      if (m) {
+        const tokens = {};
+        pat.fields.forEach((f, idx) => {
+          tokens[f] = m[idx + 1] !== undefined ? m[idx + 1].trim() : null;
+        });
+        matches.push({
+          key: pat.key,
+          name: pat.name,
+          matchedText: m[0],
+          tokens: tokens
+        });
+      }
+    });
+
+    resBox.style.display = 'block';
+    if (matches.length === 0) {
+      resBox.innerHTML = `
+        <div style="color: var(--warn); display: flex; align-items: center; gap: 8px;">
+          <span>⚠</span>
+          <span>No canonical sentence pattern matched this input. Check required tags: [WO:id] [from sender], [ACK:id], [RESULT id] OK, or [CLAIM id].</span>
+        </div>
+      `;
+    } else {
+      let html = `<div style="color: var(--ok); font-weight: 700; margin-bottom: 8px;">✔ Valid Syntax — Matched ${matches.length} Pattern(s):</div>`;
+      matches.forEach(m => {
+        html += `
+          <div style="border-top: 1px solid var(--border); padding-top: 8px; margin-top: 8px;">
+            <div style="font-weight: 600; color: var(--accent); margin-bottom: 4px;">Pattern: ${m.name} (<code>${m.key}</code>)</div>
+            <div style="color: var(--muted); font-size: 11px; margin-bottom: 6px;">Matched Chunk: <span style="color: var(--fg);">${m.matchedText}</span></div>
+            <div style="display: flex; flex-wrap: wrap; gap: 8px;">
+        `;
+        Object.entries(m.tokens).forEach(([k, v]) => {
+          html += `
+            <div style="background: var(--bg); border: 1px solid var(--border); padding: 4px 8px; border-radius: 4px; font-size: 12px;">
+              <span style="color: var(--muted);">${k}:</span> <strong style="color: var(--ok);">${v || '-'}</strong>
+            </div>
+          `;
+        });
+        html += `</div></div>`;
+      });
+      resBox.innerHTML = html;
+    }
+  }
+
+  function renderLookupSurfaces() {
+    const tbody = document.getElementById('lookup-surfaces-tbody');
+    if (!tbody) return;
+
+    const surfaces = [
+      { name: 'Fleet Pulse', id: 'dashboard', selector: '.tab-btn[data-tab="dashboard"]', route: 'GET /api/box/fleet', hint: 'Real-time CDP status, page titles, and queue depths across all nodes.' },
+      { name: 'DMs & Work Orders', id: 'dms', selector: '.tab-btn[data-tab="dms"]', route: 'GET /api/box/dm/log?limit=50', hint: 'Chronological audit trail of signed work orders, acks, and agent replies.' },
+      { name: 'Timers & Jobs', id: 'jobs', selector: '.tab-btn[data-tab="jobs"]', route: 'GET /api/box/timers', hint: 'Systemd user timers with hot-trigger buttons (POST /api/box/jobs/{name}/trigger).' },
+      { name: 'Loop & Strategy', id: 'loops', selector: '.tab-btn[data-tab="loops"]', route: 'GET /api/box/loop/health', hint: 'Fleet loop velocity, open SLA deadlines, strategies, and runtime variables.' },
+      { name: 'Lookup & Grammar', id: 'lookup', selector: '.tab-btn[data-tab="lookup"]', route: 'GET /api/box/lookup', hint: 'Interactive regex testing, sentence grammar, and DOM surface maps.' },
+      { name: 'Approvals Surface', id: 'approvals', selector: '[data-testid="approval-dialog"]', route: 'GET /api/approvals', hint: 'Permission modals and operator elevation requests (exit code 2 contract).' }
+    ];
+
+    tbody.innerHTML = surfaces.map(s => `
+      <tr>
+        <td style="font-weight: 600; color: var(--fg);">${s.name}</td>
+        <td><code>#tab-${s.id}</code></td>
+        <td><code style="color: var(--accent);">${s.selector}</code></td>
+        <td><code style="color: var(--ok);">${s.route}</code></td>
+        <td style="color: var(--muted); font-size: 12px;">${s.hint}</td>
+      </tr>
+    `).join('');
+  }
+
+  function renderLookupSentences() {
+    const grid = document.getElementById('lookup-sentence-grid');
+    if (!grid) return;
+
+    const cards = [
+      { name: 'Work Order', tag: '[WO:<id>]', template: '[WO:{id}] [from {sender}] {title} — {body}', lifecycle: 'open -> claimed -> resolved', desc: 'Dispatches actionable, trackable tasking between operators or from orchestrator.' },
+      { name: 'Acknowledgement', tag: '[ACK:<id>]', template: '[ACK:{id}] [from {sender}]', lifecycle: 'open -> acknowledged', desc: 'Confirms receipt of task without closing the tracked loop.' },
+      { name: 'Task Claim', tag: '[CLAIM <id>]', template: '[CLAIM {job_id}]', lifecycle: 'acknowledged -> claimed', desc: 'Declares worker ownership of a task or swarm slot, preventing duplicate runs.' },
+      { name: 'Task Result', tag: '[RESULT <id>]', template: '[RESULT {job_id}] {status} {summary}', lifecycle: 'claimed -> resolved', desc: 'Submits completion evidence and resolves the active loop.' },
+      { name: 'Task Decline', tag: '[DECLINE <id>]', template: '[DECLINE {job_id}] {reason}', lifecycle: 'claimed -> declined', desc: 'Explicit rejection of a task with reason, prompting fallback.' },
+      { name: 'In-Band Tool Call', tag: '[TOOL <op> <args>]', template: '[TOOL {op} {args_json}]', lifecycle: 'in-flight execution', desc: 'Inline tool directive parsed and executed directly by response-harvester.' }
+    ];
+
+    grid.innerHTML = cards.map(c => `
+      <div class="node-card" style="padding: 16px;">
+        <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px;">
+          <span style="font-weight: 700; color: var(--fg);">${c.name}</span>
+          <span class="node-status-badge badge-active">${c.tag}</span>
+        </div>
+        <div style="font-family: var(--font-mono); font-size: 12px; color: var(--accent); background: var(--bg); padding: 6px 8px; border-radius: 4px; margin-bottom: 8px; word-break: break-all;">${c.template}</div>
+        <div style="font-size: 12px; color: var(--muted); margin-bottom: 8px;">${c.desc}</div>
+        <div style="font-size: 11px; color: var(--muted); text-transform: uppercase;">Lifecycle: <span style="color: var(--ok);">${c.lifecycle}</span></div>
+      </div>
+    `).join('');
+  }
+
+  function setupLookupTab() {
+    const parseBtn = document.getElementById('lookup-parse-btn');
+    const input = document.getElementById('lookup-test-input');
+    if (parseBtn) parseBtn.addEventListener('click', runLookupParser);
+    if (input) {
+      input.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter') runLookupParser();
+      });
+    }
+    renderLookupSurfaces();
+    renderLookupSentences();
+  }
+
   // -------------------------------------------------------------------------
   // 9. Initialization
   // -------------------------------------------------------------------------
@@ -1291,6 +1458,7 @@
     setupTabs();
     setupFilters();
     setupCurlDrawer();
+    setupLookupTab();
 
     // Initial Fetch & Start Polling
     refreshData();

web/box/www/index.html

@@ -47,6 +47,9 @@
       Loop & Strategy
       <span id="loops-count-badge" class="tab-badge">0</span>
     </button>
+    <button class="tab-btn" data-tab="lookup">
+      Lookup &amp; Grammar
+    </button>
   </nav>
 
   <!-- Main Container -->
@@ -242,6 +245,63 @@
       </div>
     </section>
 
+    <!-- Tab 5: Lookup & Grammar -->
+    <section id="tab-lookup" class="tab-pane">
+      <!-- Section 1: Interactive Regex & Sentence Parser -->
+      <div class="section-heading">
+        <div class="section-title">Interactive Sentence &amp; Regex Parser</div>
+        <div class="section-subtitle">Test and validate agent sentence structures against lookup_internal patterns</div>
+      </div>
+      <div class="table-card" style="padding: 16px;">
+        <div style="display: flex; gap: 8px; margin-bottom: 12px;">
+          <input type="text" id="lookup-test-input" placeholder="Type or paste an agent message (e.g. [WO:7fce46e0] [from super] Audit — Check stats)..." style="flex: 1; padding: 10px 14px; background: var(--bg); border: 1px solid var(--border); border-radius: 6px; color: var(--fg); font-family: var(--font-mono); font-size: 13px;">
+          <button id="lookup-parse-btn" class="btn-control" style="background: var(--accent); color: #fff; font-weight: 600; padding: 0 18px;">Parse &amp; Validate</button>
+        </div>
+        <div style="display: flex; gap: 8px; margin-bottom: 12px;">
+          <span style="font-size: 11px; color: var(--muted); text-transform: uppercase; align-self: center;">Presets:</span>
+          <button class="btn-control preset-btn" onclick="setLookupPreset('[WO:7fce46e0] [from super] Audit exec.muse-dev.online — Check 200 OK codes')">[WO]</button>
+          <button class="btn-control preset-btn" onclick="setLookupPreset('[ACK:7fce46e0] [from 646]')">[ACK]</button>
+          <button class="btn-control preset-btn" onclick="setLookupPreset('[CLAIM 7fce46e0]')">[CLAIM]</button>
+          <button class="btn-control preset-btn" onclick="setLookupPreset('[RESULT 7fce46e0] OK 14 endpoints verified healthy')">[RESULT]</button>
+          <button class="btn-control preset-btn" onclick="setLookupPreset('[TOOL followup.create {&quot;in_m&quot;: 5, &quot;prompt&quot;: &quot;Recheck reachability&quot;}]')">[TOOL]</button>
+        </div>
+        <div id="lookup-parse-result" style="display: none; background: var(--surface); border: 1px solid var(--border); border-radius: 6px; padding: 12px; font-family: var(--font-mono); font-size: 13px;">
+          <!-- Rendered dynamically -->
+        </div>
+      </div>
+
+      <!-- Section 2: Sentence Structure Catalog -->
+      <div class="section-heading" style="margin-top: 24px;">
+        <div class="section-title">Protocol Grammar &amp; Conversational Contracts</div>
+        <div class="section-subtitle">Authoritative patterns from lookup_internal/sentence_structure.json</div>
+      </div>
+      <div id="lookup-sentence-grid" class="grid-nodes">
+        <!-- Rendered dynamically by box.js -->
+      </div>
+
+      <!-- Section 3: Assistive Surfaces Catalog -->
+      <div class="section-heading" style="margin-top: 24px;">
+        <div class="section-title">Assistive Surfaces Map for box.muse-dev.online</div>
+        <div class="section-subtitle">DOM Selectors, data-testids, and REST endpoints for browser agents</div>
+      </div>
+      <div class="table-card">
+        <table id="lookup-surfaces-table" class="data-table">
+          <thead>
+            <tr>
+              <th style="width: 120px;">Surface</th>
+              <th style="width: 150px;">Tab / Pane ID</th>
+              <th style="width: 240px;">DOM Tab Selector</th>
+              <th style="width: 240px;">API Route</th>
+              <th>Assistive Purpose &amp; Hint</th>
+            </tr>
+          </thead>
+          <tbody id="lookup-surfaces-tbody">
+            <!-- Rendered dynamically by box.js -->
+          </tbody>
+        </table>
+      </div>
+    </section>
+
   </main>
 
   <!-- 'View as curl' Drawer -->