docs: document streamlined Work Order and tmux envelope integration

README.md

@@ -144,7 +144,10 @@ veth IPs aren't routable off the host and Warp forwards no inbound traffic.
 - `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.
 - 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.
+
 
 ## Verification checklist
 

docs/AGENT-TOOLING.md

@@ -76,6 +76,12 @@ box muse <self> send --thread <thread_uuid> "<message>"
 
 Agents and operators can spawn background sessions and send keystrokes to long-running tasks via the shared socket `/tmp/tmux-muse.sock`. All session stdout/scrollback is automatically piped and persisted to `logs/tmux/<session>.log` for auditing and post-mortem analysis.
 
+### Socket Architecture & Isolation
+- **Agent Socket (`/tmp/tmux-muse.sock`)**: Exclusively reserved for agent execution, automated work orders, and operator inspections of agent tasks.
+- **Operator Socket (`/tmp/tmux-1000/default`)**: Reserved for user desktop sessions (`main`, etc.).
+- **Server Persistence Hardening**: The operator tmux server runs with `set -s exit-empty off` and `set -s exit-unattached off` so background sessions persist when clients disconnect or windows close.
+- **Inactivity TTL**: Inactive unattached sessions are automatically pruned after 2 hours (120 minutes) by `bin/netvm-reaper.sh` or via explicit pruning.
+
 ### Via Native CLI:
 ```bash
 # List sessions on shared socket
@@ -107,8 +113,30 @@ Agents can emit structured tool calls in sidechats:
 
 ---
 
-## 5. Best Practices & Invariants
+## 5. Work Orders (`[WO:...]`) & Prompt Envelope Specification
 
-1. **Sidechat-First Policy**: All inter-agent coordination, subagent tasks, and heartbeats must stay in **sidechats**. Do not send automated routine messages to `main` chat.
+When jobs are dispatched to agents via `bin/job-dispatch.py`, they are wrapped in an actionable Work Order envelope generated by `bin/prompt_envelope.py`.
+
+### Work Order Structure
+- **Header**: Prefixed with `[WO:<wo_id>] WORK ORDER - ACTION REQUIRED, NOT INFORMATIONAL.`
+  - `<wo_id>` is a deterministic 8-character identifier derived from the job ID.
+- **Background Session**: Automatically sets up a dedicated tmux session on the shared socket: `work-<agent>-<wo_id>`.
+- **Immediate Tool Directives**: The envelope enforces immediate execution rather than dry prose by specifying the opening tool calls:
+  1. `[TOOL tmux.new {"session": "work-<agent>-<wo_id>", "command": "bash"}]`
+  2. `[TOOL tmux.send {"session": "work-<agent>-<wo_id>", "keys": "..."}]`
+  3. Native subagent spawn or cron timer directive.
+- **Clean Runtime Context**: Includes `THREAD`, `JOB`, and `AGENT` identity parameters. Container-inaccessible host SSH key paths are stripped to ensure agents never enter auth refusal loops.
+- **Completion Contract**: When the task execution finishes, the agent concludes the reply with:
+  ```text
+  [RESULT <job_id>] <one-line summary of what ran and completed>
+  ```
+  The harvester (`bin/response-harvester.py`) detects this line and records the job outcome.
+
+---
+
+## 6. Best Practices & Invariants
+
+1. **Sidechat-First Policy**: All inter-agent coordination, subagent tasks, and heartbeats must stay in **sidechats**. Do not send automated routine messages to `main` chat (see [CHAT_POLICY.md](file:///home/super/Projects/NetVM/CHAT_POLICY.md)).
 2. **Sub-Agent Prioritization**: Break down complex diagnostic or verification jobs by delegating sub-tasks to dedicated subagent threads.
-3. **Attribution & Result Tagging**: For scheduled jobs, always conclude your response with `[RESULT <job_id>] <summary>`.
+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>`.