docs: sync onboarding runbooks, node inventory, bridge mappings, and box api docs

2026-10-05 15:58:37 +00:00
parent 7c6c3a8fbf
commit 94d6502289
44 changed files with 185 additions and 10 deletions
@@ -1,5 +1,7 @@
 # BOX-API-DESIGN-DMS.md: DM and Message Endpoint Design

+> **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.
+
 **Status:** Design v0.1 (design only — no implementation).
 **Owner:** operator-main. Sanctioned by the human 2026-10-04.
 **Companion:** `BOX-API-SPEC.md` (timer/job API), `DM-SPEC.md` (DM trust model),
@@ -1,5 +1,7 @@
 # Box API: Per-Agent Thread Oversight — Contract Draft

+> **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.
+
 Status: **draft 2026-10-04** — for the UI/UX agents. Not implemented, not deployed.
 Companion docs: `BOX-API-DESIGN-DMS.md`, `BOX-UI-DESIGN.md`, `BOX-API-DESIGN-TIMERS.md`.

@@ -1,5 +1,7 @@
 # BOX-API-DESIGN-TIMERS.md: Timer & Job Endpoint Design

+> **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.
+
 **Status:** Design only. No implementation.
 **Owner:** operator-main. Sanctioned direction from human 2026-10-04.
 **Supersedes:** the endpoint sketches in `BOX-API-SPEC.md` §§ "Endpoints"
@@ -1,5 +1,7 @@
 # BOX-API-SPEC.md: Agentic Timer Management Interface

+> **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.
+
 ## Overview

 The box page (`https://box.muse-dev.online/`) provides an agentic interface
@@ -1,5 +1,7 @@
 # BOX-UI-DESIGN.md: Box Console UI/UX Design

+> **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.
+
 ## Overview

 The box console (`https://box.muse-dev.online/`) is the operator interface for
@@ -1,5 +1,7 @@
 # Box Web Surface & Orchestration Architecture

+> **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 describes the architecture connecting the **4 autonomous browser agents** (`muse`, `pip`, `646`, `opm`) across `bl` (`100.123.153.75`) and the public Web UI surfaces hosted on the Google Cloud VM (`34.139.37.135` / `box.muse-dev.online`).

 ---
@@ -1,5 +1,7 @@
 # Bridge Spec: Front-Door ↔ muse.ai Side Conversations

+> **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.
+
 ## Overview
 Metadata bridge (not message relay) linking front-door chat channels
 (muse-dev.online) to muse.ai side conversations. Operators manage via
@@ -96,11 +98,19 @@ bridge remove <bridge_id>

 ## Implementation Status

- [ ] `bin/bridge.py` CLI
+- [x] `bin/bridge.py` CLI (exists at `bin/bridge.py`)
 - [ ] `sidechat tag` command in muse-chat-api.py
 - [ ] `sidechat bridge` query command
- [ ] `bridge/mappings.json` schema
- [ ] Documentation
+- [x] `bridge/mappings.json` schema (live, 8 mappings as of 2026-10-05)
+- [x] Documentation (this spec)
+
+### P3 reconciliation (2026-10-05, operator-646)
+- Bridge IDs enforced unique per spec (`bridge_id: string (unique)`); duplicate
+  `br-20261003191930` de-duplicated, P2P pair linked via `peer_bridge_id`.
+- Main-loop prompt sidechats for all four agents (646, opm, pip, muse) registered
+  as bridge mappings, so the registry drives the main-loop `prompt_sidechat` map.
+- `peer_bridge_id` (optional): links two ends of a P2P bridge pair. Additive,
+  does not break the v0.1 data model.

 ## Notes

@@ -1,5 +1,7 @@
 # Chromebox Runbook

+> **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.
+
 Operator's guide to the Chromebox/NetVM browser fleet on `bl` (100.123.153.75).
 Written 2026-10-04. If you're reading this at 2am, start at [Quick Triage](#quick-triage).

@@ -1,5 +1,7 @@
 # Digest Protocol Runbook

+> **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.
+
 How the main loop sends digests and how agents close them.

 **Status:** spec (2026-10-04). Implemented in `self_main_loop.py` + `response-harvester.py`;
@@ -129,7 +131,7 @@ message previews from 5 to 3 to fit it:
 ```
 [main-loop] [JOB ml-646-20261004-213000] 3 new in 646 main chat — reply needed:
 - human: <preview> [?]
-Reply: [ACK id] seen | [CLAIM id] mine | [RESULT id] done | [DECLINE id] | [NO-ACTION id]
+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.
 ```

 The footer is the primary contract. This doc is the reference.
@@ -142,7 +144,7 @@ The footer is the primary contract. This doc is the reference.
 [from:opm] [id:a6579a8d] [main-loop] [JOB ml-646-20261004-213000] 3 new in 646 main chat — reply needed:
 - human: should we archive the stale pipe-7d2896 thread? [?]
 - opm: propose yes, it's superseded by the brain channel [?]
-Reply: [ACK id] seen | [CLAIM id] mine | [RESULT id] done | [DECLINE id] | [NO-ACTION id]
+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.

 # 646 picks it up

@@ -209,5 +211,27 @@ the existing `followups.json`.

 ---

+## 11. Recursive workflow discipline (box -> agent -> box)
+
+Success = `box -> agent -> box -> agent -> box` (recursive). The failure mode is
+`box -> agent : agent` — work handed agent-to-agent in chat threads, with nothing
+ever returning to box. The tooling (`box job result|status|next|chain`) makes the
+recursive path the easy path; this section makes it the default:
+
+- **Reply in-thread.** Post `[RESULT <id>] <outcome>` back in the digest thread
+  (this thread). The harvester watches it; `box job result <job-id>` records it
+  into `job-log.jsonl`.
+- **Box chains the next step.** A `[RESULT]` on a chained job fires
+  `trigger_chain_next()` (or `box job next` to dry-run, `box job chain` to wire);
+  box dispatches the next step to the next agent. The agent never needs to know
+  who goes next.
+- **Never DM the next agent directly.** Handing work off in a chat thread
+  bypasses box orchestration: no followup record, no chain state, no
+  `job status` visibility. If you catch yourself composing a DM to hand off
+  work, stop and post the `[RESULT]` instead — box routes onward.
+- **The footer says it.** Every ACTIONABLE digest now closes with:
+  *"Report back here. Box dispatches the next step; do not DM the next agent
+  directly."* — the contract is in-band, not tribal knowledge.
+
 *Companion docs: `DM-SPEC.md` (DM format), `THREAD-BOOKKEEPING.md` (pin/archive),
 `WARP-EGRESS-FIX.md` (partition handling).*
@@ -1,5 +1,7 @@
 # DM over HTTPS: System Design

+> **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.
+
 **Date:** 2026-10-04
 **Author:** operator-646 (design agent)
 **Status:** Design only — no implementation
@@ -1,5 +1,7 @@
 # DM over HTTPS: System Design

+> **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.
+
 **Date:** 2026-10-04
 **Author:** operator-646 (design agent)
 **Status:** Design only — no implementation
@@ -1,5 +1,7 @@
 # DM Spec: Work Orders + Server-Side DM Logging + Box Visibility

+> **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.
+
 ## Companion spec

 This is the **logging/tracking layer**. The message layer — what DMs
@@ -1,5 +1,7 @@
 # DM Spec — Direct Messaging as the Agent Control Plane

+> **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.
+
 **Status:** DRAFT for discussion, 2026-10-03.
 **Context:** `dm.py` on bl injects text into another agent's Muse chat (main or side chat) via headless Chromium over CDP. This spec defines what DMs *mean* — the semantics, trust model, and safety rules — so the mechanism can grow into fleet-wide agent automation without becoming a confused-deputy nightmare.

@@ -1,5 +1,7 @@
 # DOM Headless Approvals Spec (muse.ai automation)

+> **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.
+
 ## Overview
 When headless automation (`muse-chat-api.py` via CDP) drives a muse.ai
 session, the browser may surface permission/confirmation dialogs that block
@@ -1,5 +1,7 @@
 # DOM: Approval & Permission Dialogs

+> **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.
+
 Companion to `DOM-APPROVALS-SPEC.md` (behavioral contract: detection →
 classification → handling → exit codes). This doc is the **DOM surface
 reference**: what the dialogs look like in the tree, which selectors find
@@ -1,5 +1,7 @@
 # muse.ai Chat Panel & Sidechat DOM 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. No UI-only powers.
+
 > Originally captured live via CDP on `opm` browser (warp-opm netns, CDP 9440).
 > **Re-verified 2026-10-04** via CDP `Runtime.evaluate` on three nodes:
 > `opm` (warp-opm, CDP 9440), `muse` (warp-muse, CDP 9410), `pip` (warp-pip, CDP 9420).
@@ -1,5 +1,7 @@
 # muse.ai Edge States DOM 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. No UI-only powers.
+
 > Captured live via CDP on `opm` browser (warp-opm netns, CDP 9440) on 2026-10-04.
 > Re-verified 2026-10-04 across `muse` (9410), `pip` (9420), `opm` (9440) —
 > see §10. No alerts, toasts, approval dialogs, or offline markers on any node.
@@ -1,5 +1,7 @@
 # muse.ai DOM Index — Master 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. No UI-only powers.
+
 > **Entry point for all muse.ai DOM automation work.**
 > Read this first. It indexes every `data-testid`, every key selector, every
 > automation recipe, and flags known contradictions between the detailed docs.
@@ -1,5 +1,7 @@
 # DOM Reference: Message Actions & Thread Interactions

+> **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.
+
 Inspected live via CDP on the opm browser (warp-opm netns, CDP 9440), 2026-10-04.
 Covers main chat (`https://muse.ai/`) and sidechat threads (`/thread/<uuid>`).
 Read-mostly probes; the only state-changing probes were opening/closing the
@@ -1,5 +1,7 @@
 # muse.ai Message DOM Map

+> **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.
+
 Reference for automation against the muse.ai chat UI. Captured live via CDP
 on the `opm` headless browser (viewport 780×493), 2026-10-04 ~03:45 UTC.
 Verified states: main chat (`https://muse.ai/`) and empty new thread
@@ -1,5 +1,7 @@
 # DOM reference: notifications & activity (muse.ai)

+> **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.
+
 Inspected live via CDP on the opm browser (warp-opm netns, port 9440),
 2026-10-04. Re-verified 2026-10-04 across all three fleet nodes
 (muse 9410, pip 9420, opm 9440).
@@ -1,5 +1,7 @@
 # muse.ai DOM Page Structure 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. No UI-only powers.
+
 **Generated:** 2026-10-04 via live CDP inspection (opm browser, warp-opm netns, CDP 9440)
 **Purpose:** Reference for future automation development. All selectors verified against live DOM.

@@ -1,5 +1,7 @@
 # DOM Reference: Search (`docs/DOM-SEARCH.md`)

+> **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.
+
 Muse.ai global search (quick-search / command palette). Inspected live on bl via CDP
 against the opm browser (warp-opm netns, CDP 127.0.0.1:9440) on 2026-10-04.
 All selectors verified against the live DOM.
@@ -1,5 +1,7 @@
 # DOM Reference: Settings, Profile & Dock Rail

+> **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.
+
 Inspected live via CDP on the opm browser (warp-opm netns, CDP 9440), 2026-10-04.
 Re-verified 2026-10-04 across all three fleet nodes (muse 9410, pip 9420, opm 9440).
 Structure only — no credential, token, or personal values are recorded here.
@@ -1,4 +1,6 @@
 # Fleet Autonomous Development Handoff Charter
+
+> **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.
 **Effective Timestamp**: 2026-10-04T23:41:00Z  
 **Authority**: Off-Board Super  
 **Scope**: Full autonomous development, orchestration, and continuous operation handover to Fleet Operators (`646`, `pip`, `opm`, `muse`).
@@ -1,5 +1,7 @@
 # Hybrid Headless Gateway & Chromebox Architecture: `muse-cli` Adaptation

+> **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.
+
 ## Overview

 NetVM previously automated agent interaction (thread reading, message sends, job execution) solely via headless Chromebox containers over Chrome DevTools Protocol (CDP) and DOM manipulation. 
@@ -1,5 +1,7 @@
 # Identity Variance Testing

+> **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.
+
 ## Why

 All NetVM nodes currently egress from a single Cloudflare IP (`104.28.195.181`),
@@ -1,5 +1,7 @@
 # JOB-SPEC.md: Hosted Job Scheduler and Distributor

+> **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.
+
 ## Overview

 A hosted system on bl that processes and distributes jobs to agents via DM.
@@ -1,5 +1,7 @@
 # NetVM Intrinsic Loop Management — Operational Runbook & Architecture Specification

+> **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.
+
 ## 1. Executive Overview

 NetVM coordinates an autonomous agent mesh (`muse`, `pip`, `646`, `opm`, `super`) communicating via inter-agent direct messages (DMs), scheduled jobs, and live browser sidechats. **Intrinsic Loops** represent communication cycles requiring closure (e.g. follow-ups, results, acknowledgements).
@@ -1,5 +1,7 @@
 # Meta Accounts Center API

+> **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.
+
 **Status:** active (2026-10-03)
 **Motivation:** the phone number used in the muse.ai OTP pilot is linked to a
 Facebook account with its own credentials. Meta account management must be a
@@ -1,5 +1,7 @@
 # Phone-OTP Login Flow

+> **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.
+
 **Status:** proven on bl (2026-10-03)
 Alternative to the email-OTP path for muse.ai login; same form, same OTP
 mechanics, different delivery channel (SMS instead of email).
@@ -1,5 +1,7 @@
 # Per-Node Rate Limit Policy (2026-10-04)

+> **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.
+
 ## Why

 All 4 fleet nodes (muse, pip, 646, opm) egress from a single Cloudflare IP
@@ -1,5 +1,7 @@
 # Sidechat-Only Policy — Failure Triage Runbook

+> **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.
+
 **Policy:** DMs go to side chats by default. Main chat requires explicit opt-in
 (`--allow-main-chat` / job JSON `"allow_main_chat": true`). Anything that lands
 in main without opt-in is either intentional-by-design (final nudges, escalations)
@@ -1,5 +1,7 @@
 # Sidechat Reliability Runbook

+> **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.
+
 Fleet sidechat DMs are the fleet's nervous system. On 2026-10-04 they were
 measured at ~1/3 navigation success. This runbook is the single place that
 explains how the machinery works, how each known failure looks in the logs,
@@ -1,5 +1,7 @@
 # Side Chat Spec (muse.ai)

+> **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.
+
 ## Overview
 Side chats are isolated conversation contexts within a muse.ai agent.
 Each side chat maps to an organizational unit (channel, thread, task)
@@ -1,5 +1,7 @@
 # Thread Bookkeeping with Pin & Archive

+> **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.
+
 **Status:** runbook (2026-10-04)
 **Applies to:** muse.ai side-chat threads used by the fleet DM system

@@ -1,5 +1,7 @@
 # Timer Stagger — Fleet Polling De-correlation

+> **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.
+
 **Date:** 2026-10-04 ~21:50 UTC
 **Why:** All 4 NetVM nodes egress via the same Warp IP (104.28.195.181). Synchronized
 timers = 4x correlated traffic bursts from one IP = correlated rate-limit risk.
@@ -1,5 +1,7 @@
 # Exec-constrained token policy

+> **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.
+
 Tokens for the bl exec endpoint (`bin/exec-constrained.py`) are infrastructure
 secrets. This policy binds every operator and agent in the fleet.

@@ -1,5 +1,7 @@
 # Thread-UUID rotation: measurement & mapping hygiene proposal

+> **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.
+
 Date: 2026-10-04. Source: `dm-log.jsonl` (window 2026-10-03 21:36Z → 2026-10-04 19:46Z,
 ~22h, 3318 lines — the log does not cover a full 7 days; rates below are
 extrapolated from this window and should be re-measured on a longer one).
@@ -1,5 +1,7 @@
 # WARP Egress Fix — Distinct Egress IPs per NetVM Node

+> **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.
+
 Date: 2026-10-04
 Status: DESIGN (not yet implemented)
 Author: operator-main
@@ -1,5 +1,7 @@
 # dm.py Cross-Operator DMs — Operator Runbook

+> **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.
+
 ## The `--to` Flag

 Send messages between operators (opm, 646, pip, muse) using the recipient's