metawsm

metawsm orchestrates agent work across multiple tickets and workspaces by composing:

• docmgr for ticket/document lifecycle,
• wsm for workspace lifecycle,
• tmux for per-agent runtime sessions.

Current MVP

Implemented command surface:

• metawsm run
• metawsm bootstrap
• metawsm status
• metawsm auth check
• metawsm review sync
• metawsm watch
• metawsm operator
• metawsm forum (ask, answer, assign, state, priority, close, list, thread, watch, signal)
• metawsm resume
• metawsm stop
• metawsm restart
• metawsm cleanup
• metawsm commit
• metawsm pr
• metawsm merge
• metawsm iterate
• metawsm close
• metawsm policy-init
• metawsm tui
• metawsm docs
• metawsm serve

Key implementation decisions:

• HSM-driven lifecycle transitions for run/step/agent states.
• SQLite durable state in .metawsm/metawsm.db.
• Declarative policy file at .metawsm/policy.json.
• Tmux session topology is per agent/workspace pair.
• Close flow enforces clean git state before merge.

Quick Start

Initialize policy:

go run ./cmd/metawsm policy-init

Start the durable daemon (forum worker + HTTP/WebSocket API + optional UI):

go run ./cmd/metawsm serve --addr :3001

Plan a run (no side effects):

go run ./cmd/metawsm run \
  --ticket METAWSM-001 \
  --repos metawsm \
  --doc-home-repo metawsm \
  --doc-seed-mode copy_from_repo_on_start \
  --agent agent \
  --dry-run

Start a bootstrap run with interactive intake:

go run ./cmd/metawsm bootstrap \
  --ticket METAWSM-002 \
  --repos metawsm \
  --doc-home-repo metawsm \
  --base-branch main

Inspect status:

go run ./cmd/metawsm status --ticket METAWSM-003

Answer pending guidance from an agent:

go run ./cmd/metawsm forum signal \
  --run-id RUN_ID \
  --ticket METAWSM-003 \
  --agent-name agent \
  --type guidance_answer \
  --answer "Proceed with the sentinel JSON contract."

Review/merge workflow for completed runs:

go run ./cmd/metawsm merge --ticket METAWSM-003 --dry-run
go run ./cmd/metawsm merge --ticket METAWSM-003

Send operator feedback and kick off another agent iteration:

go run ./cmd/metawsm iterate --ticket METAWSM-003 --feedback "Address the diff comments and add regression tests."

Sync PR review comments and optionally dispatch them into iterate workflow:

# sync only (preview)
go run ./cmd/metawsm review sync --ticket METAWSM-003 --dry-run

# sync + dispatch queued review feedback to agents
go run ./cmd/metawsm review sync --ticket METAWSM-003 --dispatch

Restart the latest run for a ticket:

go run ./cmd/metawsm restart --ticket METAWSM-003

Run the operator supervision loop:

# supervise all active runs
go run ./cmd/metawsm operator --all --interval 15

# run in assist mode (default from policy)
go run ./cmd/metawsm operator --all --llm-mode assist

# run in auto mode
go run ./cmd/metawsm operator --all --llm-mode auto

# observe only (no actions)
go run ./cmd/metawsm operator --all --dry-run

Clean up the latest run for a ticket (kills agent tmux sessions and deletes workspaces):

go run ./cmd/metawsm cleanup --ticket METAWSM-003

Keep workspaces during cleanup:

go run ./cmd/metawsm cleanup --ticket METAWSM-003 --keep-workspaces

Run initial TUI monitor:

# Monitor one run
go run ./cmd/metawsm tui --run-id RUN_ID

# Monitor all active runs
go run ./cmd/metawsm tui

Doc federation view and optional index refresh:

go run ./cmd/metawsm docs --policy .metawsm/policy.json
go run ./cmd/metawsm docs --policy .metawsm/policy.json --refresh

Policy

Default policy file: .metawsm/policy.json. Reference example: examples/policy.example.json.

Important fields:

• workspace.default_strategy (create|fork|reuse)
• tmux.session_pattern (supports {agent} and {workspace})
• workspace.base_branch (branch used as workspace start-point; default main)
• health.idle_seconds
• health.activity_stalled_seconds
• health.progress_stalled_seconds
• operator.unhealthy_confirmations
• operator.restart_budget
• operator.restart_cooldown_seconds
• operator.stale_run_age_seconds
• operator.llm.mode (off|assist|auto)
• operator.llm.command (V1 default: codex)
• operator.llm.timeout_seconds
• operator.llm.max_tokens
• git_pr.mode (off|assist|auto)
• git_pr.require_all (require all configured checks to pass)
• git_pr.required_checks (tests|forbidden_files|ticket_workflow|clean_tree)
• git_pr.test_commands[] (shell commands run in each target repo)
• git_pr.forbidden_file_patterns[] (glob patterns blocked in changed files)
• git_pr.allowed_repos[] (optional allow-list for commit/PR workflows)
• git_pr.default_labels[] and git_pr.default_reviewers[]
• git_pr.review_feedback.enabled (enable PR review feedback sync)
• git_pr.review_feedback.mode (assist|auto)
• git_pr.review_feedback.include_review_comments (V1 must be true)
• git_pr.review_feedback.ignore_authors[] (optional commenter ignore list)
• git_pr.review_feedback.max_items_per_sync (ingest cap per sync pass)
• git_pr.review_feedback.auto_dispatch_cap_per_interval (operator auto cap)
• close.require_clean_git
• docs.authority_mode (workspace_active)
• docs.seed_mode (none|copy_from_repo_on_start)
• docs.api.workspace_endpoints[] (workspace-scoped docmgr API endpoints)
• docs.api.repo_endpoints[] (repo fallback docmgr API endpoints)
• docs.api.request_timeout_seconds
• agent_profiles[].runner (currently codex or shell)
• agent_profiles[].base_prompt
• agent_profiles[].skills
• agents[].profile (maps each agent to an agent_profiles entry)

Kickoff doc-home selection:

• --doc-home-repo selects which workspace repo hosts ttmp/ for docmgr operations.
• --doc-repo remains as a legacy alias for compatibility.
• Default behavior picks the first --repos entry.

Forum Control Signals

Run lifecycle signaling is forum-first (no file-signal compatibility path). Forum commands are daemon-backed and call metawsm serve (--server defaults to http://127.0.0.1:3001).

Control flow conventions:

• Exactly one control thread per (run_id, agent_name).
• Control signal payloads are versioned (schema_version=1) and posted via metawsm forum signal.
• Supported control signal types:
  • guidance_request
  • guidance_answer
  • completion
  • validation

Examples:

# agent asks for guidance
go run ./cmd/metawsm forum signal \
  --run-id RUN_ID \
  --ticket METAWSM-003 \
  --agent-name agent \
  --type guidance_request \
  --question "Need decision on API schema shape"

# agent marks implementation complete
go run ./cmd/metawsm forum signal \
  --run-id RUN_ID \
  --ticket METAWSM-003 \
  --agent-name agent \
  --type completion \
  --summary "Implemented the requested contract updates"

# agent posts validation result (required for bootstrap close)
go run ./cmd/metawsm forum signal \
  --run-id RUN_ID \
  --ticket METAWSM-003 \
  --agent-name agent \
  --type validation \
  --status passed \
  --done-criteria "tests pass and docs updated"

Operator Escalation Summaries

When metawsm operator escalates in environments using docs.authority_mode=workspace_active, it appends escalation summaries to workspace ticket docs:

• <workspace>/<doc_home_repo>/ttmp/.../<ticket>/changelog.md

Entries include run id, escalation intent, summary/evidence, and requested operator decision.

Daemon API + UI (V1)

metawsm serve hosts:

• HTTP API under /api/v1/...
• WebSocket stream at /api/v1/forum/stream
• Web UI at / (if UI assets are available)

Core API routes:

• GET /api/v1/health
• GET /api/v1/runs, GET /api/v1/runs/{run_id}
• GET/POST /api/v1/forum/threads
• POST /api/v1/forum/threads/{thread_id}/posts|assign|state|priority|close
• POST /api/v1/forum/control/signal
• GET /api/v1/forum/events, GET /api/v1/forum/stats

Development loop:

# terminal 1
make dev-backend

# terminal 2
npm --prefix ui install
make dev-frontend

Single-command dev loop (backend + Vite with hot reload):

make dev-all

Use the Vite URL (default http://127.0.0.1:3000) for UI debugging; /api and WebSocket calls are proxied to metawsm serve.

One-shot daemon startup with prerequisites (installs UI deps, builds assets, then runs server):

make serve-all

Production-style build:

go generate ./internal/web
go build -tags embed ./...

Build & Test

go test ./...
go build -tags embed ./...

Additional Runbook

• Forum runtime/operations runbook: docs/how-to-run-forum.md