Merge pull request #23 from reoring/roboppi/loop-20260227-121443

feat(agents): expand resident workflows and telemetry

Author: reoring

CHANGELOG.md

@@ -13,6 +13,25 @@ The format is based on Keep a Changelog, and this project follows SemVer where p
 ### Fixed
 
 
+## [0.1.10] - 2026-03-09
+
+### Added
+
+- Added `roboppi agents tasks supersede` and `roboppi agents status get|set` for file-backed workflow status summaries and task replacement flow.
+- Extended the agents workflow DSL with seed task `id`/`depends_on`/`tags`/`requires_plan_approval`, member `role`, and worker `defaultArgs`.
+- Added TUI Timeline/Raw/Usage tabs with structured LLM log summaries, agent runtime usage stats, and dormant-agent visibility.
+
+### Changed
+
+- Agent coordination now prunes stopped resident agents before reconcile, skips dormant members, restores mailbox body previews, and emits task-superseded activity events.
+- The Codex CLI adapter now normalizes legacy sandbox/approval flags and merges task/profile `defaultArgs` before dispatch.
+
+### Fixed
+
+- Clarified agent task claimability and dependency handling, including seeded dependency resolution and broader test coverage.
+- Added verification around supervised IPC capability detection, TUI state/runtime accounting, and prompt-byte tracking in worker costs.
+
+
 ## [0.1.9] - 2026-03-06
 
 ### Added

docs/features/agents.md

@@ -146,6 +146,7 @@ Directory root:
     in_progress/
     completed/
     blocked/
+    superseded/
     tmp/
     _events.jsonl
   locks/
@@ -286,8 +287,9 @@ Task transitions are represented by moving the file:
 
 - `pending/<taskId>.json` -> `in_progress/<taskId>.json`
 - `in_progress/<taskId>.json` -> `completed/<taskId>.json`
+- `pending|in_progress|blocked/<taskId>.json` -> `superseded/<taskId>.json`
 
-Blocked tasks can be stored in `blocked/` to make discovery fast.
+Blocked tasks can be stored in `blocked/` to make discovery fast, and stale coordination tasks can be moved to `superseded/` to preserve audit history without leaving them claimable.
 
 ### 4.4 Event logs
 
@@ -308,6 +310,7 @@ audit. These logs MUST be safe by default.
 { "ts": 1710000000000, "type": "task_added", "task_id": "...", "title": "..." }
 { "ts": 1710000005000, "type": "task_claimed", "task_id": "...", "by": "researcher" }
 { "ts": 1710000010000, "type": "task_completed", "task_id": "...", "by": "researcher" }
+{ "ts": 1710000015000, "type": "task_superseded", "task_id": "...", "by": "lead", "reason": "stale contract" }
 ```
 
 The full message body SHOULD NOT be copied into `_events.jsonl` unless explicitly
@@ -408,9 +411,10 @@ Add a `roboppi agents` CLI group:
 - `roboppi agents message ack --context <dir> --for <memberId> --message-id <uuid>`
 
 - `roboppi agents tasks add --context <dir> --title ... --description ... [--depends-on ...]`
-- `roboppi agents tasks list --context <dir> [--status pending|in_progress|completed]`
+- `roboppi agents tasks list --context <dir> [--status pending|in_progress|completed|blocked|superseded]`
 - `roboppi agents tasks claim --context <dir> --task-id <uuid> --member <memberId>`
 - `roboppi agents tasks complete --context <dir> --task-id <uuid> --member <memberId> [--artifact <path>]`
+- `roboppi agents tasks supersede --context <dir> --task-id <uuid> --member <memberId> [--reason <text>] [--replacement-task-id <uuid>]`
 
 Return values MUST be JSON so workers can parse them reliably.
 
@@ -486,10 +490,10 @@ Implementation note:
 - Prefer `roboppi agents message ...` subcommands that accept structured JSON via
   stdin (`--json-stdin`) to avoid quoting errors.
 
-### 6.3 Optional: MCP server (future)
+### 6.3 MCP server
 
-For better ergonomics (no shell quoting, richer schemas), provide an MCP server
-`roboppi agents mcp` that exposes tools:
+For better ergonomics (no shell quoting, richer schemas), `roboppi agents mcp`
+exposes a stdio MCP server with tools:
 
 - `agents_send_message`
 - `agents_broadcast`
@@ -499,6 +503,11 @@ For better ergonomics (no shell quoting, richer schemas), provide an MCP server
 - `agents_tasks_list`
 - `agents_tasks_claim`
 - `agents_tasks_complete`
+- `agents_tasks_supersede`
+- `agents_status_get`
+- `agents_status_set`
+- `agents_specialist_activate`
+- `agents_specialist_deactivate`
 
 Teammate sessions (Claude Code) already load MCP servers as part of context.
 This aligns with the Claude agent teams note that teammates "load the same

docs/guides/agents.md

@@ -248,6 +248,17 @@ roboppi agents tasks complete \
 
 Artifact paths must be relative and must not contain `..` segments.
 
+Supersede stale coordination work without pretending it succeeded:
+
+```bash
+roboppi agents tasks supersede \
+  --context "$ROBOPPI_AGENTS_CONTEXT_DIR" \
+  --task-id "<uuid>" \
+  --member lead \
+  --reason "stale rerun contract" \
+  --replacement-task-id "<new-uuid>"
+```
+
 ### Housekeeping
 
 Requeue stale processing messages and stale in-progress tasks:

docs/spec/agents.md

@@ -24,7 +24,7 @@ Out of scope for this document:
 
 - multi-host agents support
 - nested agentss
-- MCP transport delivery (`roboppi agents mcp`) in v1
+- broader MCP coverage beyond the current `roboppi agents mcp` surface
 
 ## 1. Source Of Truth
 
@@ -44,7 +44,7 @@ The following are treated as implemented baseline:
   - `init`
   - `members list`
   - `message send|broadcast|recv|ack`
-  - `tasks add|list|claim|complete`
+  - `tasks add|list|claim|complete|supersede`
   - `housekeep`
 - Metadata-only `_events.jsonl` emission for mailbox/tasks.
 - Capability wiring of `MAILBOX` / `TASKS` in workflow/daemon/type layers.

examples/README.ja.md

@@ -42,6 +42,7 @@ timeout 10s ./roboppi daemon examples/daemon/simple-cron.yaml --verbose
 - `examples/todo-loop.yaml`: 反復ループの最小パターン
 - `examples/agent-pr-loop.yaml`: 大きめのエージェントループ（デモは `examples/agent-pr-loop-demo/`）
 - `examples/appthrust-dashboard/workflow.yaml`: チームプロジェクト向けの本番ワークフロー（design -> todo -> implement -> validate）
+- `examples/kubernetes-operator-dev-loop/workflow.yaml`: Kubernetes operator / controller 開発向けの汎用的な長期 agents ループ
 
 ## daemon の例
 

examples/README.md

@@ -43,6 +43,7 @@ timeout 10s ./roboppi daemon examples/daemon/simple-cron.yaml --verbose
 - `examples/subworkflow-loop.yaml`: subworkflow step + completion_check loop (see `examples/subworkflow-loop-child.yaml`)
 - `examples/agent-pr-loop.yaml`: larger multi-step agent loop (see demo under `examples/agent-pr-loop-demo/`)
 - `examples/appthrust-dashboard/workflow.yaml`: production workflow for a team project (design -> todo -> implement -> validate)
+- `examples/kubernetes-operator-dev-loop/workflow.yaml`: generic long-running agents loop for Kubernetes operator / controller development
 
 ## Daemon examples
 

examples/kubernetes-operator-dev-loop/README.md

@@ -0,0 +1,66 @@
+# Kubernetes Operator Dev Loop
+
+This example is a generic long-running agents workflow for developing a
+Kubernetes operator or controller-based platform component.
+
+It is derived from a real multi-agent development loop, but the repo-specific
+names and assumptions were removed so it can serve as a reusable example.
+
+## What It Demonstrates
+
+- A lead-driven implement -> review -> verify loop
+- Planner-owned living TODO, memory, issue index, and rerun contract state
+- Dormant specialist activation for:
+  - manual verification
+  - long-running E2E
+  - Kubernetes debugging
+  - spec clarification
+  - provenance / rerun gatekeeping
+  - loop and stall recovery
+- Completion checks that look at TODO state, blockers, and verification results
+
+## Intended Workspace
+
+Run it against a repository that already has some combination of:
+
+- `request.md`
+- `implementation-plan.md` or an equivalent repo-local design/plan document
+- `ARCHITECTURE.md` or `docs/**`
+- controller / API / chart / test code
+
+Typical fit:
+
+- an operator repo with CRDs and controllers
+- a platform repo with Kubernetes reconciliation logic
+- a repo where local fast gates and separate cluster-backed validation both exist
+
+## Run
+
+```bash
+cd /home/reoring/project/roboppi
+bun run src/workflow/run.ts \
+  examples/kubernetes-operator-dev-loop/workflow.yaml \
+  --workspace /path/to/your/operator-repo \
+  --verbose
+```
+
+Or with the built binary:
+
+```bash
+cd /home/reoring/project/roboppi
+./roboppi workflow \
+  examples/kubernetes-operator-dev-loop/workflow.yaml \
+  --workspace /path/to/your/operator-repo \
+  --verbose
+```
+
+## Notes
+
+- The workflow loads the colocated `agents.yaml` automatically.
+- `context_dir` is relative to the target workspace, so state is written under
+  `.roboppi-loop/operator-dev/` in that repo.
+- You will usually want to adapt:
+  - the fast-gate commands in `workflow.yaml`
+  - the repo-local plan filename
+  - the dormant specialist policies in `agents.yaml`
+  - the completion-check criteria