diff --git a/docs/G2_RUNBOOK.md b/docs/G2_RUNBOOK.md new file mode 100644 index 0000000..b6eeb6e --- /dev/null +++ b/docs/G2_RUNBOOK.md @@ -0,0 +1,392 @@ +# G2 Runbook - Gateway/Node Pairing Preparation + +## Status + +Draft for user authorization. G2 execution is not open yet. + +This runbook is an execution-before-action checklist. It may be used only after the user explicitly authorizes G2. It does not authorize token injection, `openclaw node run`, VPS approval, service changes, Nginx changes, Docker changes, or any mutation by itself. + +## Sources Reviewed + +- `USER_STATUS.md` +- `AGENT_BOARD.md` +- `handoff/ORCHESTRATOR.md` +- `D:\openclaw\OPENCLAW_EXEC_NODE_PLAN.md` +- `evidence/pc-baseline-20260515.md` +- `evidence/vps-baseline-20260515.md` +- `evidence/verify-vps-baseline-20260515.md` +- `sync-state/heartbeat-pc.json` +- `sync-state/heartbeat-vps.json` +- `sync-state/README.md` + +## G2 Goal + +G2 prepares the OpenClaw execution path immediately before smoke testing: + +- Start the Windows PC node in foreground mode and connect it to the VPS Gateway. +- Approve the pairing on the VPS/Gateway side. +- Confirm the execution plane is ready for G3 smoke testing, without running the G3 smoke test yet unless separately authorized. + +G2 does not install a persistent service. G4 covers persistence later. + +## Current Baseline + +- G0A, G0B, and G1 are complete in `AGENT_BOARD.md`. +- PC baseline shows OpenClaw CLI `OpenClaw 2026.5.7 (eeef486)`, `openclaw node --help` availability, Tailscale availability, outbound TCP 443 success to `openclaw.smartmotor.cloud`, and no PC OpenClaw public port exposure. +- VPS baseline shows `openclaw-gateway` running healthy in Docker on `services_appnet`, with Gateway CLI available inside the `openclaw-gateway` container. +- VPS verifier accepted G1 with follow-up observations about `/opt/service` versus `/opt/services`, `docker-composite.yml` versus `docker-compose.openclaw.yml`, and the Nginx route/config anomaly. +- Sync-state files exist for PC and VPS. PC heartbeat currently reports `dirty`; this is expected while control-plane documents are being edited, but CORRECTION must re-check sync health before any G2 execution. + +## Actions Requiring Explicit User Authorization + +These actions must not be performed unless the user explicitly authorizes G2 execution: + +- Injecting or setting `OPENCLAW_GATEWAY_TOKEN` on the Windows PC. +- Running `openclaw node run`. +- Reading or using any real token, password, API key, private key, cookie, or secret value. +- Approving a device pairing request on the VPS. +- Running `openclaw nodes pending` or `openclaw nodes approve` if it changes approval state. +- Starting G3 smoke test from QQ or phone Control UI. +- Installing, starting, restarting, stopping, or persisting any PC/VPS service. +- Changing firewall, network, Nginx, Docker compose, bind mounts, container images, environment variables, or service state. + +## Secret Handling Rules + +- Never write token/password/API key/private key/cookie values into files, evidence, logs, commits, or chat. +- Do not paste `OPENCLAW_GATEWAY_TOKEN` into chat. +- Do not echo or print the token. +- Evidence may say that a token was set locally, but must not include its value. +- Pairing request IDs may be recorded only if they are not secrets. +- If a command prints a secret or prompts to display one, stop and record a blocker without copying the value. + +## smartmotor.cloud Freeze Rules + +G2 must not affect the public `smartmotor.cloud` website during filing review. + +Forbidden during G2: + +- Changing homepage content. +- Changing content reachable from homepage links. +- Changing static assets. +- Changing Nginx routing or route files. +- Changing Docker bind mounts or container images. +- Changing `/opt/services/docker-composite.yml` or equivalent service entries that could alter public website output. +- Restarting or reloading public website services unless a later approved rollback plan explicitly authorizes it. + +## Role Task Split + +### PC_EXECUTOR + +Scope: Windows PC only. + +Planned G2 task: + +- Confirm no stale OpenClaw node process is running. +- After explicit user authorization, set the Gateway token only in the local shell/session. +- Run the node in foreground mode. +- Capture non-secret evidence of connection and pairing request ID if shown. +- Stop immediately on any secret exposure, fatal connection error, or request for unapproved mutation. + +May write: + +- `evidence/pc-g2-node-run-YYYYMMDD.md` +- `handoff/PC_EXECUTOR.md` +- `rollback/pc-g2-node-run-YYYYMMDD.md` + +### VPS_EXECUTOR + +Scope: VPS Gateway approval only. + +Planned G2 task: + +- Confirm Gateway-side CLI command shape using `--help` if needed. +- After explicit user authorization and after PC evidence provides a pairing request ID or pending node ID, approve the correct request. +- Capture non-secret approval evidence. +- Do not restart/reload services or change Gateway/Nginx/Docker configuration. + +May write: + +- `evidence/vps-g2-approve-YYYYMMDD.md` +- `handoff/VPS_EXECUTOR.md` +- `rollback/vps-g2-approve-YYYYMMDD.md` + +### PC_VERIFIER + +Scope: Independent validation of PC-side G2 evidence. + +Planned G2 verification: + +- Confirm PC foreground node evidence shows connection to the expected Gateway. +- Confirm token value is absent from evidence. +- Confirm no service install/start/status command was executed. +- Confirm no PC firewall, network, environment persistence, scheduled task, or public port exposure change occurred. + +May write: + +- `evidence/verify-pc-g2-YYYYMMDD.md` +- `handoff/PC_VERIFIER.md` + +### VPS_VERIFIER + +Scope: Independent validation of VPS-side G2 evidence and freeze compliance. + +Planned G2 verification: + +- Confirm only the intended pairing approval occurred. +- Confirm no restart, reload, token rotation, Nginx edit, Docker compose edit, bind mount change, image change, or public website content change occurred. +- Confirm the frozen website policy remains intact. +- Track existing path/route anomalies as follow-up observations, not automatic blockers unless they affect G2. + +May write: + +- `evidence/verify-vps-g2-YYYYMMDD.md` +- `handoff/VPS_VERIFIER.md` + +### CORRECTION + +Scope: Guardrails and drift detection. + +Planned G2 monitoring: + +- Confirm sync health before G2 execution starts. +- Block G2 if heartbeat is stale, sync error files exist, evidence is not visible on both sides, or repo state prevents coordination. +- Block G2 if any task tries to bypass user authorization or freeze rules. +- Block G2 if any secret appears in evidence, handoffs, logs, commits, or chat. + +May write: + +- `handoff/CORRECTION.md` +- `tasks/T7-correction-monitor.md` + +## Step Plan + +### Step 0 - ORCHESTRATOR Authorization Check + +Prerequisites: + +- User explicitly says to authorize G2 execution. +- G0A, G0B, and G1 remain complete. +- CORRECTION reports sync health not blocked. +- No `sync-state/error-pc.md` or `sync-state/error-vps.md` exists. +- PC and VPS agents can see the same latest control-plane state. + +Command draft: + +```text +No PC/VPS command. ORCHESTRATOR records authorization and opens G2 tasks. +``` + +Expected output: + +- `USER_STATUS.md` and `AGENT_BOARD.md` show G2 authorized/in progress. +- G2 executor tasks move from `draft` to `ready`. + +Stop conditions: + +- User authorization is ambiguous. +- Sync health is blocked. +- Any evidence or handoff contains a secret. +- Website freeze risk is unresolved. + +### Step 1 - PC Rollback Note Before Token/Node Run + +Prerequisites: + +- Step 0 complete. +- PC_EXECUTOR is assigned and has read the runbook. + +Command draft: + +```text +No operational command. Write rollback note before action. +``` + +Expected output: + +- `rollback/pc-g2-node-run-YYYYMMDD.md` exists. +- Rollback note says foreground node can be stopped with `Ctrl+C`, shell token can be cleared by closing the shell or removing the session environment variable, and no persistent service is installed in G2. + +Stop conditions: + +- Rollback note would require recording a secret. +- PC_EXECUTOR cannot confirm this is foreground-only. + +### Step 2 - PC Token Injection + +Prerequisites: + +- User explicitly authorizes token use. +- Token is provided out-of-band or typed locally by the user, not pasted into repo/chat. +- PC shell is local and not being logged into evidence. + +Command draft: + +```powershell +$env:OPENCLAW_GATEWAY_TOKEN = "" +``` + +Expected output: + +- No command output containing the token. +- Evidence records only: "Gateway token was set in local shell session; value not displayed or recorded." + +Stop conditions: + +- Token appears in terminal output, file, evidence, chat, or logs. +- Executor is asked to store token persistently. +- Token source or target Gateway is unclear. + +### Step 3 - PC Foreground Node Run + +Prerequisites: + +- Step 2 complete. +- No stale foreground node process conflicts are reported. +- No service install/start command is planned. + +Command draft: + +```powershell +openclaw node run --host openclaw.smartmotor.cloud --port 443 --tls --display-name "desktop-vuor0gs" +``` + +Expected output: + +- Foreground process keeps running. +- Logs show connection attempt to Gateway. +- If pairing is required, logs show a non-secret request ID or pending node ID. +- No PC public port is exposed. + +Stop conditions: + +- Command prints a secret. +- Fatal connection error repeats. +- Command asks to install or persist a service. +- Command attempts to bind a public PC port. +- Gateway host differs from `openclaw.smartmotor.cloud` without ORCHESTRATOR review. + +### Step 4 - VPS Rollback Note Before Approval + +Prerequisites: + +- PC evidence includes a non-secret pairing request ID or pending node ID, or Gateway shows a matching pending node. +- User explicitly authorizes VPS-side approval. + +Command draft: + +```text +No approval command yet. Write rollback note before action. +``` + +Expected output: + +- `rollback/vps-g2-approve-YYYYMMDD.md` exists. +- Rollback note explains how to stop the PC foreground node and how to escalate if the wrong request is approved. It must not invent destructive revoke commands. + +Stop conditions: + +- Request identity is ambiguous. +- Approval would require changing Gateway config, restarting services, or reading secrets. + +### Step 5 - VPS Pairing Approval + +Prerequisites: + +- Step 4 complete. +- VPS_EXECUTOR can target the `openclaw-gateway` container CLI without changing Docker/Nginx configuration. +- Request ID or node ID matches PC evidence and display name. + +Command drafts: + +```bash +docker exec -it openclaw-gateway node openclaw.mjs devices approve +docker exec -it openclaw-gateway node openclaw.mjs nodes pending +docker exec -it openclaw-gateway node openclaw.mjs nodes approve +``` + +Expected output: + +- The intended PC device/node is approved. +- Gateway shows the PC node online or approved. +- Evidence contains request IDs or node IDs only if non-secret. + +Stop conditions: + +- Multiple indistinguishable pending requests exist. +- Command would print or require a token/password. +- Command requires restart/reload/config mutation. +- Any action risks changing frozen website output. + +### Step 6 - G2 Verification + +Prerequisites: + +- PC_EXECUTOR and VPS_EXECUTOR evidence exists. +- No secret-bearing evidence exists. + +Command draft: + +```text +Verifier review only. No new PC/VPS mutation. +``` + +Expected output: + +- PC_VERIFIER accepts or returns PC G2 evidence. +- VPS_VERIFIER accepts or returns VPS G2 evidence. +- CORRECTION confirms no sync, secret, or freeze blocker. +- ORCHESTRATOR may mark G2 complete only after verifier acceptance. + +Stop conditions: + +- Missing evidence. +- Any evidence contains a secret. +- Approval cannot be tied to the intended PC node. +- Website freeze compliance is uncertain. + +## Rollback and Recovery Strategy + +G2 uses foreground execution to keep recovery simple: + +- Before PC action: write a PC rollback note. +- If foreground node misbehaves: stop it with `Ctrl+C`. +- If token was set in the shell: close the shell or clear the session environment variable. Do not write the token value. +- If pairing request is wrong or ambiguous: do not approve; block and ask ORCHESTRATOR/CORRECTION. +- If wrong approval appears to have happened: stop the PC foreground node, preserve non-secret evidence, and ask VPS_EXECUTOR to identify an official revoke/remove flow using `--help` or documentation before any corrective command. +- If sync becomes unhealthy: pause cross-device work until both sides can see the same evidence through Git. +- If freeze risk appears: stop all VPS-side action and route to CORRECTION. + +## Evidence Checklist + +PC_EXECUTOR evidence should include: + +- Authorization was received. +- Rollback note path. +- Token was set locally without value disclosure. +- Exact node command used. +- Connection/pairing status summary. +- Pairing request ID if non-secret. +- Confirmation no install/start/service/firewall/network/public-port change occurred. + +VPS_EXECUTOR evidence should include: + +- Authorization was received. +- Rollback note path. +- Pending request or node identity used for approval. +- Exact approval command shape, without secrets. +- Approval result summary. +- Confirmation no restart/reload/token rotation/Nginx/Docker/public website change occurred. + +Verifier evidence should include: + +- PC and VPS evidence reviewed. +- No secrets found. +- Intended PC node identity confirmed. +- Frozen website rule not violated. +- G2 accepted or returned with findings. + +## Decision: Should ORCHESTRATOR Request G2 Authorization? + +Yes, but only as a request for explicit user authorization, not as execution. + +The baseline evidence is sufficient to ask the user whether to open G2. The next user-facing question should be: "Authorize G2 execution now?" If the user says yes, ORCHESTRATOR must first open the draft tasks, require rollback notes, and keep each token/run/approval action behind the explicit authorization boundaries in this runbook. diff --git a/tasks/T10-G2-VPS-pairing-approve.md b/tasks/T10-G2-VPS-pairing-approve.md new file mode 100644 index 0000000..dcb6393 --- /dev/null +++ b/tasks/T10-G2-VPS-pairing-approve.md @@ -0,0 +1,58 @@ +# T10 - G2 VPS Pairing Approval + +## Status + +draft + +## Owner + +VPS_EXECUTOR + +## Dependencies + +- T9 produces a non-secret pairing request ID or pending node ID +- User explicitly authorizes VPS-side approval +- CORRECTION confirms sync-health is not blocked + +## Scope + +Approve the intended PC node/device pairing on the VPS Gateway side. + +This task does not authorize service restarts, reloads, token rotation, Gateway configuration changes, Nginx changes, Docker compose edits, bind mount changes, image changes, or public website changes. + +## Required Evidence + +- `rollback/vps-g2-approve-YYYYMMDD.md` written before approval action. +- Confirmation that request identity matched the PC evidence and display name. +- Exact command shape used, without secrets. +- Approval result summary. +- Confirmation that no restart, reload, token rotation, Nginx route edit, Docker compose edit, bind mount change, image change, service-state mutation, or frozen website output change was performed. +- Evidence written to `evidence/vps-g2-approve-YYYYMMDD.md`. +- `handoff/VPS_EXECUTOR.md` updated. + +## Command Drafts + +Do not run these until G2 approval is explicitly authorized. + +```bash +docker exec -it openclaw-gateway node openclaw.mjs devices approve +docker exec -it openclaw-gateway node openclaw.mjs nodes pending +docker exec -it openclaw-gateway node openclaw.mjs nodes approve +``` + +## Expected Output + +- The intended PC device/node is approved. +- Gateway shows the PC node online or approved. +- Evidence contains only non-secret request IDs or node IDs. + +## Stop Conditions + +- User authorization is absent or ambiguous. +- Request identity is ambiguous or multiple indistinguishable pending requests exist. +- A command asks for or prints a token/password. +- Approval would require restart, reload, token rotation, config mutation, Nginx changes, Docker changes, or any action that could affect frozen `smartmotor.cloud` website output. + +## Acceptance + +VPS_VERIFIER must review this evidence before ORCHESTRATOR can count the VPS half of G2 as accepted. diff --git a/tasks/T9-G2-PC-node-run.md b/tasks/T9-G2-PC-node-run.md new file mode 100644 index 0000000..434844b --- /dev/null +++ b/tasks/T9-G2-PC-node-run.md @@ -0,0 +1,61 @@ +# T9 - G2 PC Foreground Node Run + +## Status + +draft + +## Owner + +PC_EXECUTOR + +## Dependencies + +- G0A complete +- G0B complete +- G1 accepted +- User explicitly authorizes G2 execution +- CORRECTION confirms sync-health is not blocked + +## Scope + +Prepare and run the Windows PC OpenClaw node in foreground mode for Gateway pairing. + +This task is not ready until ORCHESTRATOR records explicit user authorization for G2. It does not authorize service installation, startup persistence, firewall changes, network changes, or any public port exposure. + +## Required Evidence + +- `rollback/pc-g2-node-run-YYYYMMDD.md` written before token or node-run action. +- Confirmation that `OPENCLAW_GATEWAY_TOKEN` was set only in the local shell/session and that the token value was not printed or recorded. +- Exact foreground node command used, without secrets. +- Connection status summary and non-secret pairing request ID or pending node ID if shown. +- Confirmation that no `openclaw node install`, `start`, `restart`, `stop`, `uninstall`, firewall, network, scheduled task, environment persistence, or public-port exposure change was performed. +- Evidence written to `evidence/pc-g2-node-run-YYYYMMDD.md`. +- `handoff/PC_EXECUTOR.md` updated. + +## Command Drafts + +Do not run these until G2 is explicitly authorized. + +```powershell +$env:OPENCLAW_GATEWAY_TOKEN = "" +openclaw node run --host openclaw.smartmotor.cloud --port 443 --tls --display-name "desktop-vuor0gs" +``` + +## Expected Output + +- Foreground node process remains running. +- Logs show connection attempt to `openclaw.smartmotor.cloud`. +- Pairing request ID or pending node ID appears if approval is required. +- No secret value appears in evidence. + +## Stop Conditions + +- User authorization is absent or ambiguous. +- Any command asks to print, persist, or store a token. +- Any command prints a secret. +- Any step requires PC service install/start, scheduled task changes, firewall changes, network changes, or public port exposure. +- Gateway host or display name differs from the runbook without ORCHESTRATOR review. + +## Acceptance + +PC_VERIFIER must review this evidence before ORCHESTRATOR can count the PC half of G2 as accepted.