Add repository harness for coding agents (#1157)

Co-authored-by: xingzhi <chuzihao.czh@alibaba-inc.com>

docs/harness/worktree-runbook.md

@@ -0,0 +1,64 @@
+# Worktree Runbook
+
+Use a separate git worktree for agent changes so local user work remains
+untouched.
+
+## Create A Worktree
+
+```bash
+git fetch origin --prune
+git worktree add -b codex/<short-topic> ../worktrees/hermes-web-ui-<short-topic> origin/main
+cd ../worktrees/hermes-web-ui-<short-topic>
+```
+
+If the repository uses a fork remote, push to the remote requested by the task.
+Do not rewrite or reset unrelated branches.
+
+## Install
+
+```bash
+npm ci --ignore-scripts
+npm rebuild node-pty
+```
+
+Desktop package dependencies are separate:
+
+```bash
+npm ci --prefix packages/desktop --no-audit --no-fund
+```
+
+## Isolated Runtime
+
+Use per-worktree state and ports to avoid colliding with a running local app:
+
+```bash
+export PORT=18648
+export HERMES_WEB_UI_HOME="$PWD/.tmp/hermes-web-ui"
+export HERMES_WEBUI_STATE_DIR="$HERMES_WEB_UI_HOME"
+export UPLOAD_DIR="$PWD/.tmp/uploads"
+npm run dev
+```
+
+Do not point `HERMES_WEB_UI_HOME` at a user's real `~/.hermes-web-ui` when a task
+only needs local verification.
+
+## Browser Checks
+
+For browser-visible changes:
+
+```bash
+npm run test:e2e
+```
+
+Prefer existing Playwright fixtures and mocked backend services. Add real-service
+requirements only when the behavior cannot be represented with mocks.
+
+## Cleanup
+
+After a PR is pushed and no more local work is needed:
+
+```bash
+git worktree remove ../worktrees/hermes-web-ui-<short-topic>
+```
+
+Only remove the worktree you created.