okstra 0.7.0 → 0.8.0

package/README.kr.md

@@ -48,6 +48,7 @@ okstra/                          npm 패키지 = repo 루트
 ├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
 ├── bin/                         okstra.sh, codex-exec, gemini-exec, ...
 ├── installed-skills.json        설치된 스킬 매니페스트 (uninstall 이 사용)
+├── installed-agents.json        설치된 워커 에이전트 매니페스트 (uninstall 이 사용)
 ├── recent.jsonl, active.jsonl   run 인덱스
 ├── projects/                    프로젝트별 메타데이터 미러
 └── archive/                     완료된 run
@@ -55,6 +56,10 @@ okstra/                          npm 패키지 = repo 루트
 ~/.claude/skills/                Claude Code 가 자동 인식
 └── okstra-*/SKILL.md            스킬 11종 (§3.3 참조)
 
+~/.claude/agents/                Claude Code 가 자동 인식 (subagent 디스커버리 경로)
+└── {claude,codex,gemini,report-writer}-worker.md   worker subagent 정의
+                                 (multi-agent dispatch 필수)
+
 <프로젝트 루트>/.project-docs/okstra/
 ├── project.json                 {projectId, projectRoot, ...} (`/okstra-setup` 이 작성)
 ├── discovery/{task-catalog,latest-task}.json
@@ -68,6 +73,7 @@ okstra/                          npm 패키지 = repo 루트
 | 런타임 코드 (python + bash) | `~/.okstra/{lib/python, bin}` | `okstra install` |
 | agents/prompts/templates/validators | npm 패키지의 `runtime/` | `okstra` 패키지 자체 (`okstra paths` 로 해석) |
 | 스킬 마크다운 | `~/.claude/skills/<name>/SKILL.md` | `okstra install` (`installed-skills.json` 에 트래킹) |
+| 워커 에이전트 마크다운 | `~/.claude/agents/<worker>.md` | `okstra install` (`installed-agents.json` 에 트래킹) |
 | 프로젝트 메타데이터 | `<project>/.project-docs/okstra/` | `/okstra-setup` + 프로젝트 자체 |
 | Run 인덱스 | `~/.okstra/{recent,active}.jsonl` | `prepare_task_bundle` |
 

package/README.md

@@ -47,6 +47,7 @@ okstra/                          npm package = repo root
 ├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
 ├── bin/                         okstra.sh, codex-exec, gemini-exec, ...
 ├── installed-skills.json        manifest of installed skills (used by uninstall)
+├── installed-agents.json        manifest of installed worker agents (used by uninstall)
 ├── recent.jsonl, active.jsonl   run index
 ├── projects/                    per-project metadata mirror
 └── archive/                     completed runs
@@ -54,6 +55,10 @@ okstra/                          npm package = repo root
 ~/.claude/skills/                discovered automatically by Claude Code
 └── okstra-*/SKILL.md            11 skills total (see §3.3)
 
+~/.claude/agents/                discovered automatically by Claude Code
+└── {claude,codex,gemini,report-writer}-worker.md   subagent definitions
+                                 (required for multi-agent dispatch)
+
 <project-root>/.project-docs/okstra/
 ├── project.json                 {projectId, projectRoot, ...} (written by /okstra-setup)
 ├── discovery/{task-catalog,latest-task}.json
@@ -67,6 +72,7 @@ okstra/                          npm package = repo root
 | Runtime code (python + bash) | `~/.okstra/{lib/python, bin}` | `okstra install` |
 | agents/prompts/templates/validators | npm package's `runtime/` | the `okstra` package (resolved via `okstra paths`) |
 | Skill markdown | `~/.claude/skills/<name>/SKILL.md` | `okstra install` (tracked in `installed-skills.json`) |
+| Worker agent markdown | `~/.claude/agents/<worker>.md` | `okstra install` (tracked in `installed-agents.json`) |
 | Project metadata | `<project>/.project-docs/okstra/` | `/okstra-setup` + the project itself |
 | Run index | `~/.okstra/{recent,active}.jsonl` | `prepare_task_bundle` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.7.0",
-  "builtAt": "2026-05-12T08:22:42.014Z",
+  "package": "0.8.0",
+  "builtAt": "2026-05-12T09:54:25.514Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/okstra.sh

@@ -79,6 +79,7 @@ okstra execution summary:
   workers override: ${WORKERS_OVERRIDE:-None}
   executor (implementation only): ${EXECUTOR_OVERRIDE:-default(claude)}
   approved plan: ${APPROVED_PLAN_PATH:-None}
+  approve ack (CLI 승인 의사): ${APPROVE_PLAN_ACK}
   related tasks: ${RELATED_TASKS_RAW:-None}
 CONFIRM_EOF
   printf 'Continue? [y/yes]: ' >&2
@@ -115,7 +116,9 @@ PY_ARGS=(
 [[ -n "${EXECUTOR_OVERRIDE-}" ]] && PY_ARGS+=(--executor "$EXECUTOR_OVERRIDE")
 [[ -n "${RELATED_TASKS_RAW-}" ]] && PY_ARGS+=(--related-tasks "$RELATED_TASKS_RAW")
 [[ -n "${APPROVED_PLAN_PATH-}" ]] && PY_ARGS+=(--approved-plan "$APPROVED_PLAN_PATH")
+[[ "$APPROVE_PLAN_ACK" == "true" ]] && PY_ARGS+=(--approve)
 [[ -n "${CLARIFICATION_RESPONSE_PATH-}" ]] && PY_ARGS+=(--clarification-response "$CLARIFICATION_RESPONSE_PATH")
+[[ -n "${WORK_CATEGORY-}" ]] && PY_ARGS+=(--work-category "$WORK_CATEGORY")
 [[ "$RENDER_ONLY" == "true" ]] && PY_ARGS+=(--render-only)
 [[ "$REFRESH_OKSTRA_ASSETS" == "true" ]] && PY_ARGS+=(--refresh-assets)
 

package/runtime/prompts/profiles/implementation-planning.md

@@ -40,7 +40,7 @@
 - Authority & permissions assumption (HARD RULE — applies to every okstra task-type):
   - **Assume the user (and their team) holds full authority and every permission required for the anticipated work.** Treat external approvals, third-party access grants, role/IAM permissions, organisational sign-off, legal/compliance review, vendor coordination, and "verify access exists" steps as already satisfied unless the user explicitly states otherwise in the task brief.
   - Do NOT add such items to option trade-offs, dependency/migration risk, validation checklists, rollout plans, `Open Questions`, or day/effort estimates. They are not legitimate sources of schedule extension; effort sizing must reflect engineering work only.
-  - The `User Approval Request` block at the end of the plan is the only authorised approval gate — that gate is the user themselves and is expected to be cleared without external coordination.
+  - The `User Approval Request (사용자 승인 게이트)` block at the **top of the final report** (immediately under the metadata header, before `Section 0`) is the only authorised approval gate — that gate is the user themselves, who clears it either by (a) editing the single checkbox `- [ ] Approved` to `- [x] Approved` directly, or (b) invoking the next phase with `--approve` so the CLI invocation itself is treated as the approval signal and the runtime flips the checkbox on the user's behalf. No external coordination is expected.
 - Non-goals:
   - code-level micro-optimization unless it changes the implementation approach
   - **source code edits of any kind** — this run produces a plan document only; Edit/Write on project source files is forbidden until the plan is approved and a separate `implementation` run starts
@@ -66,7 +66,7 @@
   - dependency / migration risk assessment (ordering constraints, data backfills, feature-flag prerequisites, cross-team coordination)
   - validation checklist (pre / mid / post) — each item is an exact command or observable outcome
   - rollback strategy — exact revert path (commits, flags, migrations) and the signal that triggers rollback
-  - explicit `User Approval Request` block — the next `implementation` run must not begin until the user replies with explicit approval
+  - explicit `User Approval Request (사용자 승인 게이트)` block placed at the **top of the report** with a single canonical checkbox marker `- [ ] Approved` (user toggles to `- [x] Approved` to authorise the next `implementation` run). Section `4.5.8` is retained only as a back-pointer to this top block for validator/key-substring compatibility — it must NOT carry an independent marker.
   - `Open Questions` block listing every ambiguity flagged during pre-planning that the user must resolve before approval
 - No-placeholder rule (plan failures — reject any option or step that contains these):
   - "TBD", "TODO", "implement later", "fill in details", "add appropriate error handling", "handle edge cases", "write tests for the above" without actual test code

package/runtime/prompts/profiles/implementation.md

@@ -26,7 +26,11 @@
   - the read-only MCP servers declared in the task brief's `## Available MCP Servers` section may be queried by both executor and verifiers as a read-only cross-check (sanity-checking row counts after a migration script's dry-run, comparing observed schema against the plan's expectations, etc.); that section is the canonical source of which servers and tools exist for this run, and any MCP-derived evidence MUST cite server, table, and the SELECT used. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files, never through this MCP.
 - Pre-implementation gate (mandatory — refuse to start if any item fails):
   - the run brief MUST cite `--approved-plan <path>` pointing to a `final-report.md` produced by a prior `implementation-planning` run located under `runs/implementation-planning/.../reports/final-report.md`
-  - that file MUST contain a `User Approval Request` block AND a recorded user approval marker matching one of the following line-anchored, case-insensitive forms (the runtime regex in `okstra_ctl.run._validate_approved_plan` enforces this and rejects the run with `PrepareError` before any prompt is generated): `APPROVED` (alone, followed by `:`, or end-of-line), `[x] Approved`, or `User Approval: APPROVED|granted|yes`. Free-form approvals such as "lgtm", "go ahead", or paraphrased confirmations are intentionally NOT accepted; if the user's approval is informal, re-edit the plan file to add one of the exact markers above before invoking the implementation run.
+  - that file MUST contain a `User Approval Request` block (canonically placed at the **top of the report**, immediately under the metadata header) AND a recorded user approval marker. The canonical, recommended form is the single markdown checkbox line `- [x] Approved`. The runtime regex in `okstra_ctl.run._validate_approved_plan` also accepts (case-insensitive, line-anchored, optional leading `-`/`*`/`+` bullet): `APPROVED` (alone, followed by `:`, or end-of-line), `[x] Approved`, or `User Approval: APPROVED|granted|yes`. Free-form approvals such as "lgtm", "go ahead", or paraphrased confirmations are intentionally NOT accepted; if the user's approval is informal, re-edit the plan file to flip the top checkbox to `- [x] Approved` before invoking the implementation run.
+  - Two equally-valid approval paths exist (both end up satisfying the same regex gate):
+    - **Manual edit** — the user opens the report, flips `- [ ] Approved` to `- [x] Approved`, saves, then runs `okstra ... --task-type implementation --approved-plan <path>`.
+    - **CLI ack** — the user runs `okstra ... --task-type implementation --approved-plan <path> --approve`. The CLI invocation itself is modelled as the user's act of approval; the runtime (`okstra_ctl.run._apply_cli_approval`) flips the checkbox in the report file and appends an audit line `- 승인 일시 (CLI ack): <ISO8601> — recorded by \`okstra --approve\`` before the standard regex validation runs. Use this when running unattended or when you want a single command to both approve and launch the next phase.
+  - The `--approve` flag is **only meaningful with `--task-type implementation` and `--approved-plan <path>`**. Passing it with any other task-type causes `PrepareError` (the runtime refuses to silently ignore approval signals). It is also a no-op if the file already carries a valid approval marker (idempotent — only an audit line is appended, the marker is not re-toggled).
   - the file's `Recommended option` and its bite-sized step list become the authoritative scope for this run; any deviation must be justified in the final report and routed back to a new `implementation-planning` run instead of being silently expanded.
 - Pre-implementation context exploration (executor before first edit):
   - re-read the approved plan end-to-end and extract: file list, step order, validation commands, rollback path

package/runtime/python/lib/okstra/cli.sh

@@ -140,6 +140,10 @@ while [[ $# -gt 0 ]]; do
       RELATED_TASKS_RAW="$(require_option_value --related-tasks "${2-}")"
       shift 2
       ;;
+    --work-category)
+      WORK_CATEGORY="$(require_option_value --work-category "${2-}")"
+      shift 2
+      ;;
     --task-type)
       ANALYSIS_TYPE="$(require_option_value --task-type "${2-}")"
       shift 2
@@ -180,6 +184,13 @@ while [[ $# -gt 0 ]]; do
       APPROVED_PLAN_PATH="$(require_option_value --approved-plan "${2-}")"
       shift 2
       ;;
+    --approve)
+      # 사용자가 CLI 명령을 입력한 행위 자체를 plan 승인 의사로 간주한다.
+      # 런타임에서 approved-plan 파일의 승인 체크박스를 [x] 로 갱신하고
+      # 승인 시각/방식을 함께 기록한다 (scripts/okstra_ctl/run.py 참조).
+      APPROVE_PLAN_ACK="true"
+      shift
+      ;;
     -h|--help)
       usage
       exit 0
@@ -209,7 +220,7 @@ while [[ $# -gt 0 ]]; do
           printf '  hint: did you mean --task-id?\n' >&2
           ;;
       esac
-      printf '  valid options: --render-only --resume-clarification --yes --refresh-assets --workers --lead-model --claude-model --codex-model --gemini-model --report-writer-model --executor --related-tasks --task-type --project-id --project-root --task-group --task-id --task-brief --directive --clarification-response --approved-plan -h|--help\n' >&2
+      printf '  valid options: --render-only --resume-clarification --yes --refresh-assets --workers --lead-model --claude-model --codex-model --gemini-model --report-writer-model --related-tasks --task-type --project-id --project-root --task-group --task-id --task-brief --directive --clarification-response --approved-plan --approve -h|--help\n' >&2
       usage
       exit 1
       ;;

package/runtime/python/lib/okstra/globals.sh

@@ -25,6 +25,7 @@ CODEX_MODEL_OVERRIDE=""
 GEMINI_MODEL_OVERRIDE=""
 REPORT_WRITER_MODEL_OVERRIDE=""
 EXECUTOR_OVERRIDE=""
+WORK_CATEGORY=""
 RELATED_TASKS_RAW=""
 ANALYSIS_TYPE=""
 BRIEF_PATH=""
@@ -37,6 +38,7 @@ REVIEW_PROFILE=""
 DIRECTIVE=""
 CLARIFICATION_RESPONSE_PATH=""
 APPROVED_PLAN_PATH=""
+APPROVE_PLAN_ACK="false"
 CLARIFICATION_RESPONSE_FILE=""
 CLARIFICATION_RESPONSE_RELATIVE_PATH=""
 PROJECT_ROOT=""

package/runtime/python/lib/okstra/usage.sh

@@ -39,6 +39,12 @@ optional arguments:
                        should prefer --resume-clarification, which wraps this flag.
   --approved-plan      Path to the approved final-report.md from a prior implementation-planning run.
                        Required when --task-type=implementation; the file MUST contain a recorded user approval marker.
+  --approve            Treat the user's CLI invocation itself as the plan-approval signal. Only meaningful
+                       together with --approved-plan and --task-type=implementation. The runtime updates the
+                       top "User Approval Request" block of the approved-plan file: flips
+                       \`- [ ] Approved\` to \`- [x] Approved\` and appends an approval audit line
+                       (timestamp + "CLI --approve"). Use this for scripted/CI flows or when you want a
+                       single command to both approve and launch the next phase.
   --task-key <project-id:task-group:task-id>
                        Shorthand for --project-id/--task-group/--task-id. When the matching task-manifest.json
                        exists, brief-path and task-type are auto-filled from it (taskBriefPath and
@@ -72,6 +78,11 @@ options:
                       providers are dispatched as read-only verifiers regardless of this selection.
                       Has no effect on other task types.
   --related-tasks      Optional comma-separated related task identifiers. Example: auth-token-refresh,frontend-login-ui
+  --work-category      Work-category classification for this task. One of:
+                       bugfix | feature | refactor | ops | improvement | unknown.
+                       Defaults to 'unknown' when omitted. Use this when the
+                       lifecycle skipped --task-type=requirements-discovery
+                       (where work-category would otherwise be inferred).
   --task-type          Set the task purpose for this run and select the matching profile file.
   -h, --help           Show this help.
 

package/runtime/python/okstra_ctl/render.py

@@ -438,10 +438,19 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
     if current_phase:
         phase_states[current_phase] = current_phase_state
     work_category = existing.get("workCategory") or ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")
-    next_recommended_phase = (
-        workflow.get("nextRecommendedPhase")
-        or default_next_phase.get(current_phase, ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", "unknown"))
+    # Compute the canonical next phase from current_phase deterministically.
+    # Only preserve `existing.workflow.nextRecommendedPhase` when it is a
+    # legitimate forward pointer — i.e. NOT equal to `current_phase` itself
+    # (which would mean the lifecycle pointer has stalled on the current
+    # phase and would loop forever).
+    canonical_next = default_next_phase.get(
+        current_phase, ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", "unknown")
     )
+    existing_next = workflow.get("nextRecommendedPhase") or ""
+    if existing_next and existing_next != current_phase:
+        next_recommended_phase = existing_next
+    else:
+        next_recommended_phase = canonical_next
     last_completed_phase = workflow.get("lastCompletedPhase") or ctx.get("WORKFLOW_LAST_COMPLETED_PHASE", "")
     routing_status = workflow.get("routingStatus") or ctx.get("WORKFLOW_ROUTING_STATUS", "not-applicable")
     awaiting_approval = workflow.get("awaitingApproval")

package/runtime/python/okstra_ctl/run.py

@@ -21,6 +21,7 @@ import re
 import shutil
 import subprocess
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
@@ -55,7 +56,7 @@ from .workers import normalize_workers, resolve_profile_workers
 from .workflow import compute_workflow_state
 
 APPROVED_PLAN_PATTERN = re.compile(
-    r"^[ \t]*(APPROVED([ \t]|:|$)|\[x\][ \t]*Approved|"
+    r"^[ \t]*(?:[-*+][ \t]+)?(APPROVED([ \t]|:|$)|\[x\][ \t]*Approved|"
     r"User[ \t]+Approval[ \t]*:[ \t]*(APPROVED|granted|yes))",
     re.IGNORECASE | re.MULTILINE,
 )
@@ -83,10 +84,12 @@ class PrepareInputs:
     report_writer_model: str = ""
     executor: str = ""
     related_tasks_raw: str = ""
+    work_category: str = ""
     approved_plan_path: str = ""
     clarification_response_path: str = ""  # absolute or empty
     render_only: bool = False
     refresh_assets: bool = False
+    approve_plan_ack: bool = False
 
 
 @dataclass
@@ -108,11 +111,65 @@ def _validate_approved_plan(path: str) -> None:
     if not APPROVED_PLAN_PATTERN.search(p.read_text(encoding="utf-8", errors="replace")):
         raise PrepareError(
             f"approved plan has no recognised user-approval marker: {path}\n"
-            '  expected one of (case-insensitive, line-anchored): "APPROVED", '
-            '"[x] Approved", "User Approval: APPROVED|granted|yes"'
+            '  canonical form (single line, top-of-report block): "- [x] Approved"\n'
+            '  also accepted (case-insensitive, line-anchored, optional leading bullet): '
+            '"APPROVED", "[x] Approved", "User Approval: APPROVED|granted|yes"\n'
+            "  shortcut: re-run okstra with --approve to have the CLI itself "
+            "record the approval marker on this file."
         )
 
 
+# `- [ ] Approved` 라인을 정확히 한 번만 매치한다. 좌측 leading whitespace 와
+# 옵션 bullet 은 보존된 채 체크박스 안쪽 공백만 `x` 로 갱신된다.
+APPROVAL_UNCHECKED_PATTERN = re.compile(
+    r"^([ \t]*(?:[-*+][ \t]+)?)\[[ \t]\][ \t]*Approved[ \t]*$",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+
+def _apply_cli_approval(path: str) -> str:
+    """`--approve` 가 지정된 경우 approved-plan 파일에 사용자 승인 마커를 새겨 넣는다.
+
+    Returns a short human-readable description of the action taken (used in the
+    runtime audit line). Idempotent: if the file already carries a valid
+    approval marker, no edits are written and `"already-approved"` is returned.
+    """
+    p = Path(path)
+    if not p.is_file():
+        raise PrepareError(f"approved plan file not found: {path}")
+    body = p.read_text(encoding="utf-8", errors="replace")
+
+    audit_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    audit_line = (
+        f"- 승인 일시 (CLI ack): {audit_iso} — recorded by `okstra --approve` "
+        "(user CLI invocation treated as approval signal)"
+    )
+
+    if APPROVED_PLAN_PATTERN.search(body):
+        # 이미 사용자(또는 이전 --approve 호출)가 마커를 남긴 상태. audit 라인이
+        # 없으면 보조적으로 한 줄만 추가하고 마커 자체는 건드리지 않는다.
+        if audit_line.split(" — ")[1] in body:
+            return "already-approved"
+        new_body = body.rstrip("\n") + "\n" + audit_line + "\n"
+        p.write_text(new_body, encoding="utf-8")
+        return "already-approved-audit-appended"
+
+    if APPROVAL_UNCHECKED_PATTERN.search(body):
+        new_body, count = APPROVAL_UNCHECKED_PATTERN.subn(
+            lambda m: f"{m.group(1)}[x] Approved", body, count=1,
+        )
+        new_body = new_body.rstrip("\n") + "\n" + audit_line + "\n"
+        p.write_text(new_body, encoding="utf-8")
+        return "checkbox-flipped"
+
+    raise PrepareError(
+        f"--approve was given but the approved-plan file has no `User Approval Request` "
+        f"checkbox to flip: {path}\n"
+        "  expected a line of the form `- [ ] Approved` near the top of the report "
+        "(see templates/reports/final-report.template.md)."
+    )
+
+
 def _ensure_task_directories(ctx: dict) -> None:
     for key in (
         "TASK_ROOT", "INSTRUCTION_SET_DIR", "RUNS_DIR", "HISTORY_DIR",
@@ -268,6 +325,7 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         ("--report-writer-model", inp.report_writer_model or ctx.get("REPORT_WRITER_MODEL_DISPLAY", "")),
         ("--executor", inp.executor or ctx.get("EXECUTOR_PROVIDER", "")),
         ("--related-tasks", inp.related_tasks_raw),
+        ("--work-category", inp.work_category),
     ]
     argv: list[str] = []
     for flag, val in pairs:
@@ -330,7 +388,19 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             raise PrepareError(
                 "task-type implementation requires --approved-plan <path-to-final-report.md>"
             )
+        if inp.approve_plan_ack:
+            # 사용자가 직접 `--approve` 를 입력한 행위 자체를 승인 의사로 모델링한다.
+            # 파일을 먼저 갱신한 뒤 동일한 검증 경로를 그대로 통과시킨다 — 검증
+            # 책임을 단일 지점(`_validate_approved_plan`)으로 유지한다.
+            _apply_cli_approval(inp.approved_plan_path)
         _validate_approved_plan(inp.approved_plan_path)
+    elif inp.approve_plan_ack:
+        # implementation 외 task-type 에서 `--approve` 는 의미가 없다. 사용자에게
+        # 정확한 시점을 알려주기 위해 조용히 무시하지 않고 즉시 거부한다.
+        raise PrepareError(
+            "--approve is only meaningful with --task-type implementation "
+            "and --approved-plan <path>"
+        )
     if inp.clarification_response_path and not Path(inp.clarification_response_path).is_file():
         raise PrepareError(
             f"clarification response file not found: {inp.clarification_response_path}"
@@ -487,11 +557,15 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     cleanup_obsolete_generated_docs(
         project_root=project_root, instruction_set_dir=Path(ctx["INSTRUCTION_SET_DIR"]),
     )
-    if not inp.render_only:
-        write_claude_resume_command_file(
-            resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_FILE"]),
-            project_root=project_root, claude_session_id=claude_session_id,
-        )
+    # Always materialise the resume command script. Even in --render-only
+    # preparation flows the user (or a later non-interactive runner) may
+    # invoke it manually; deferring its creation until interactive launch
+    # leaves runs/<phase>/sessions/ empty and the manifest pointing at a
+    # path that does not exist.
+    write_claude_resume_command_file(
+        resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_FILE"]),
+        project_root=project_root, claude_session_id=claude_session_id,
+    )
 
     # ---- write instruction-set scaffolding ----
     instruction_set = Path(ctx["INSTRUCTION_SET_DIR"])
@@ -569,6 +643,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         current_run_status=ctx["CURRENT_RUN_STATUS"],
         current_task_status=ctx["CURRENT_TASK_STATUS"],
         render_only=inp.render_only,
+        work_category=inp.work_category,
     ))
     render_team_state(ctx["TEAM_STATE_FILE"], ctx)
     render_task_manifest(ctx["TASK_MANIFEST_FILE"], ctx)
@@ -639,9 +714,29 @@ def main(argv: list[str]) -> int:
     p.add_argument("--executor", default="")
     p.add_argument("--related-tasks", default="", dest="related_tasks_raw")
     p.add_argument("--approved-plan", default="", dest="approved_plan_path")
+    p.add_argument(
+        "--approve",
+        action="store_true",
+        dest="approve_plan_ack",
+        help=(
+            "Treat the CLI invocation itself as the plan approval signal. "
+            "Flips `- [ ] Approved` to `- [x] Approved` in the --approved-plan file "
+            "and appends an audit line."
+        ),
+    )
     p.add_argument("--clarification-response", default="", dest="clarification_response_path")
     p.add_argument("--render-only", action="store_true", dest="render_only")
     p.add_argument("--refresh-assets", action="store_true", dest="refresh_assets")
+    p.add_argument(
+        "--work-category",
+        default="",
+        dest="work_category",
+        help=(
+            "Work-category classification for this task "
+            "(bugfix / feature / refactor / ops / improvement). "
+            "Falls back to `unknown` when omitted."
+        ),
+    )
     args = p.parse_args(argv)
 
     project_root = Path(args.project_root).expanduser().resolve()
@@ -677,10 +772,12 @@ def main(argv: list[str]) -> int:
         report_writer_model=args.report_writer_model,
         executor=args.executor,
         related_tasks_raw=args.related_tasks_raw,
+        work_category=args.work_category,
         approved_plan_path=args.approved_plan_path,
         clarification_response_path=clarification_abs,
         render_only=args.render_only,
         refresh_assets=args.refresh_assets,
+        approve_plan_ack=args.approve_plan_ack,
     )
     try:
         out = prepare_task_bundle(inputs)

package/runtime/python/okstra_ctl/workflow.py

@@ -138,6 +138,7 @@ def compute_workflow_state(
     current_run_status: str,
     current_task_status: str,
     render_only: bool,
+    work_category: str = "",
 ) -> dict:
     """WORKFLOW_* + PHASE_* 값을 dict 로 돌려준다."""
     if current_run_status == "in-progress":
@@ -170,8 +171,10 @@ def compute_workflow_state(
     rules = PHASE_RULES.get(task_type, PHASE_RULES_UNKNOWN)
     last_completed = task_type if current_run_status == "completed" else ""
 
+    resolved_work_category = (work_category or "").strip() or "unknown"
+
     return {
-        "WORKFLOW_WORK_CATEGORY": "unknown",
+        "WORKFLOW_WORK_CATEGORY": resolved_work_category,
         "WORKFLOW_CURRENT_PHASE": task_type,
         "WORKFLOW_CURRENT_PHASE_STATE": phase_state,
         "WORKFLOW_NEXT_RECOMMENDED_PHASE": default_next_phase_for(task_type),

package/runtime/skills/okstra-status/SKILL.md

@@ -43,7 +43,7 @@ Extract the following fields from each task.
 |------|------|
 | `taskKey` | `<project-id>:<task-group>:<task-id>` |
 | `taskType` | latest task type |
-| `workCategory` | bugfix / feature / improvement / refactor / ops-change / unknown |
+| `workCategory` | bugfix / feature / improvement / refactor / ops-change / unknown. Display `unknown` as-is, but flag with `(unset)` annotation so the reader knows the requirements-discovery classification was skipped or no `--work-category` flag was passed. |
 | `currentStatus` | task-level status |
 | `currentPhase` | lifecycle current phase |
 | `currentPhaseState` | lifecycle phase state |
@@ -213,7 +213,16 @@ Accepted `<status>` values: `todo`, `in-progress`, `blocked`, `done`.
 
 ### Default Value Convention
 
-If `workStatus` is missing or empty in any manifest, treat it as `in-progress` for read purposes. Do not back-fill the field on read; only write it when the user explicitly issues an update.
+If `workStatus` is missing or empty in any manifest, infer the display value from the lifecycle state — DO NOT default to a static `in-progress`:
+
+| Manifest state | Inferred display |
+|---|---|
+| `currentStatus == "completed"` AND `workflow.nextRecommendedPhase` in (`done-or-follow-up`, empty) | `done` (inferred) |
+| `currentStatus == "completed"` AND `workflow.currentPhaseState == "completed"` | `phase-done` (inferred) |
+| `currentStatus == "contract-violated"` OR `workflow.currentPhaseState == "blocked"` | `blocked` (inferred) |
+| anything else | `in-progress` (default) |
+
+Annotate inferred values with `(inferred)` or `(default)` in the rendered output so the reader can see which value is user-set vs. system-inferred. Do not back-fill the field on read; only write it when the user explicitly issues an update.
 
 ### Catalog Sync Note
 

package/runtime/templates/reports/final-report.template.md

@@ -6,6 +6,18 @@
 - Lead Model: `{{LEAD_MODEL}}`
 - Clarification Response Carried In: `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}`
 
+## User Approval Request (사용자 승인 게이트)
+
+> **이 블록은 `task-type` = `implementation-planning` 결과에서만 의미를 가집니다.** 다른 task-type의 보고서에서는 이 섹션 전체를 삭제하세요.
+>
+> 다음 `implementation` run은 아래 체크박스가 `[x]`로 표시되어 있을 때에만 진입할 수 있습니다 (`okstra_ctl.run._validate_approved_plan` 가 이 마커를 line-anchored 정규식으로 검사하여 통과/거부합니다). 본문(`Sections 1`–`4.5`)을 끝까지 읽고, `4.5.9 Open Questions`가 비어 있거나 모두 해소된 뒤 승인해 주세요.
+
+- 승인 여부 (사용자가 직접 편집): `- [ ] Approved` ← 승인하려면 `[ ]` 를 `[x]` 로 변경하여 저장하세요.
+- 승인 후 다음 단계 명령어 (방법 A — 수동 편집): `okstra --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로>`
+- 승인 + 실행 한 번에 (방법 B — CLI 자체를 승인 의사로): `okstra --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로> --approve`
+  - 방법 B 는 `--approve` 입력 행위 자체를 승인 의사로 모델링합니다. 런타임이 본 블록의 체크박스를 자동으로 `[x]` 로 바꾸고, 본 섹션 하단에 `승인 일시 (CLI ack): <ISO8601>` audit 라인을 한 줄 덧붙입니다.
+- 승인을 보류하거나 거부하려면 체크박스는 `[ ]` 로 두고 `--approve` 도 사용하지 마세요. 필요한 변경 사항은 `4.5.9 Open Questions` 또는 `Section 5 Clarification Requests` 에 기록한 뒤 같은 phase 를 재실행해 주세요.
+
 ## 0. Clarification Response Carried In From Previous Run
 - Source file: `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}`
 - If the source path is empty, write `- No prior clarification response was provided for this run.` and skip the rest of this section.
@@ -89,9 +101,9 @@
 ### 4.5.7 Rollback Strategy (롤백 전략)
 - 정확한 revert 경로(commits, flags, migrations 등)와 롤백을 트리거하는 신호(에러율, latency, 사용자 보고 등)를 명시합니다.
 
-### 4.5.8 User Approval Request (사용자 승인 요청)
-- 다음 `implementation` run을 시작해도 되는지에 대한 명시적 승인 요청 블록입니다. 사용자가 명시적으로 승인하기 전까지는 이 plan을 코드로 옮기지 않습니다.
-- 승인 시 사용할 명령어 한 줄을 함께 적습니다: `okstra --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로>`
+### 4.5.8 User Approval Request (사용자 승인 요청 — 본 보고서 상단 참조)
+- 실제 승인 게이트는 본 보고서 **상단 `User Approval Request (사용자 승인 게이트)` 블록**에 있습니다. 이 하위 섹션은 validator가 요구하는 영문 키워드(`User Approval Request`)와 본문 구조 일관성을 위해 남겨 둡니다.
+- 본 섹션에는 승인 결정에 영향을 주는 *플랜 측 보충 메모*만 적습니다(예: 위험을 줄이기 위한 사전 작업, 승인 전 사용자가 확인해 두어야 할 사항). 승인 마커는 본 섹션이 아니라 상단 블록의 체크박스로만 부여합니다.
 
 ### 4.5.9 Open Questions
 - pre-planning에서 발견된 모든 모호점을 항목으로 남겨, 사용자가 승인 전에 해소해야 할 질문 목록으로 사용합니다.

package/runtime/validators/validate-run.py

@@ -36,11 +36,31 @@ def default_next_phase(task_type: str) -> str:
         "requirements-discovery": "pending-routing-decision",
         "error-analysis": "implementation-planning",
         "implementation-planning": "implementation",
+        "implementation": "final-verification",
         "final-verification": "done-or-follow-up",
     }
     return mapping.get(task_type, "unknown")
 
 
+def advance_next_phase(
+    current_phase: str,
+    phase_sequence: list,
+) -> str:
+    """Compute the next recommended phase after `current_phase` completes.
+
+    Walk `phase_sequence` and return the entry following `current_phase`.
+    Falls back to the static `default_next_phase` mapping when the current
+    phase is the terminal entry or is absent from the sequence (e.g. custom
+    task types that aren't part of the standard 5-phase lifecycle).
+    """
+    if isinstance(phase_sequence, list) and current_phase in phase_sequence:
+        idx = phase_sequence.index(current_phase)
+        if idx + 1 < len(phase_sequence):
+            return phase_sequence[idx + 1]
+        return "done-or-follow-up"
+    return default_next_phase(current_phase)
+
+
 def update_workflow_metadata(
     run_manifest: dict,
     task_manifest: dict,
@@ -77,9 +97,10 @@ def update_workflow_metadata(
         if current_phase:
             phase_states[current_phase] = current_phase_state
         last_completed_phase = current_phase or workflow.get("lastCompletedPhase", "")
-        next_recommended_phase = (
-            workflow.get("nextRecommendedPhase") or default_next_phase(current_phase)
-        )
+        # Validation just passed → actively advance to the next phase in
+        # the sequence rather than preserving a stale value that may equal
+        # current_phase (which would cause the lifecycle pointer to stall).
+        next_recommended_phase = advance_next_phase(current_phase, phase_sequence)
     else:
         current_phase_state = "blocked"
         if current_phase:
@@ -98,6 +119,12 @@ def update_workflow_metadata(
     awaiting_approval = workflow.get("awaitingApproval")
     if not isinstance(awaiting_approval, bool):
         awaiting_approval = False
+    # 승인 게이트(`User Approval Request`)는 implementation 진입 직전에 한 번만 의미를 가진다.
+    # implementation run 이 검증을 통과했다는 것은 `_validate_approved_plan` 이 이미 사용자
+    # 마커를 소비했다는 뜻이므로, 이 시점에 awaitingApproval 플래그를 명시적으로 내려
+    # 다음 phase 의 status 뷰에서 stale 상태로 남지 않게 한다.
+    if validation_status == "passed" and current_phase == "implementation":
+        awaiting_approval = False
 
     last_safe_checkpoint = workflow.get("lastSafeCheckpoint", {})
     if not isinstance(last_safe_checkpoint, dict):
@@ -440,6 +467,28 @@ def validate_team_state_usage(team_state: dict, failures: list[str]) -> None:
             "Run `python3 scripts/okstra-token-usage.py <team-state> --write --summary "
             "--substitute-final-report <final-report>`."
         )
+        return
+    # Reject zero-valued usage when the collector flagged any source as
+    # `unavailable`. This catches the silent-failure mode where the
+    # collector ran but couldn't locate session jsonls (e.g. empty
+    # claudeSession.sessionId, missing subagent jsonl).
+    grand_total = summary.get("grandTotalTokens", 0)
+    if isinstance(grand_total, (int, float)) and grand_total == 0:
+        lead = team_state.get("leadUsage") or {}
+        if lead.get("source") == "unavailable":
+            failures.append(
+                "team-state.usageSummary.grandTotalTokens is 0 and leadUsage.source is "
+                f"`unavailable` — {lead.get('note', 'reason unknown')}. Re-collect once "
+                "the lead session jsonl is locatable."
+            )
+        for worker in team_state.get("workers") or []:
+            role = (worker or {}).get("role") or (worker or {}).get("workerId") or "<worker>"
+            usage = (worker or {}).get("usage") or {}
+            if usage.get("source") == "unavailable":
+                failures.append(
+                    f"team-state.workers[{role}].usage.source is `unavailable` while "
+                    f"grandTotalTokens is 0 — {usage.get('note', 'reason unknown')}."
+                )
 
 
 PLANNING_REQUIRED_SECTIONS = (
@@ -479,6 +528,56 @@ def validate_phase_boundary(
             )
 
 
+def _refresh_task_catalog(project_root: Path, task_manifest: dict) -> tuple[bool, str]:
+    """Regenerate `discovery/task-catalog.json` so it stops trailing the
+    authoritative `task-manifest.json` after validation.
+
+    Resolves the catalog output path from the manifest, scans every
+    `task-manifest.json` under the tasks root, and rewrites the catalog
+    via `render_task_catalog_discovery`. Returns (ok, message); failure
+    is non-fatal — the validator logs a warning instead of breaking the
+    overall validation result.
+    """
+    catalog_relative = (task_manifest.get("taskCatalogPath") or "").strip()
+    if not catalog_relative:
+        return False, "taskCatalogPath missing from task-manifest — skip catalog refresh"
+
+    here = Path(__file__).resolve().parent
+    candidates = [
+        here.parent / "scripts",
+        here.parent / "python",
+    ]
+    env_pp = os.environ.get("OKSTRA_PYTHONPATH", "").strip()
+    if env_pp:
+        candidates.append(Path(env_pp))
+    for candidate in candidates:
+        if candidate.is_dir() and (candidate / "okstra_ctl").is_dir():
+            if str(candidate) not in sys.path:
+                sys.path.insert(0, str(candidate))
+            break
+
+    try:
+        from okstra_ctl.render import render_task_catalog_discovery  # noqa: E402
+    except Exception as exc:  # noqa: BLE001
+        return False, f"okstra_ctl import failed: {exc}"
+
+    tasks_root = (project_root / ".project-docs" / "okstra" / "tasks").resolve()
+    catalog_path = (project_root / catalog_relative).resolve()
+    ctx = {
+        "PROJECT_ROOT": str(project_root),
+        "OKSTRA_TASKS_ROOT": str(tasks_root),
+        "PROJECT_ID": task_manifest.get("projectId", ""),
+        "RUN_TIMESTAMP_ISO": utc_now(),
+        "TASK_KEY": task_manifest.get("taskKey", ""),
+        "OKSTRA_LATEST_TASK_RELATIVE_PATH": "",
+    }
+    try:
+        render_task_catalog_discovery(str(catalog_path), ctx)
+    except Exception as exc:  # noqa: BLE001
+        return False, f"render_task_catalog_discovery raised: {exc}"
+    return True, f"task-catalog refreshed at {catalog_relative}"
+
+
 def _import_token_usage():
     """Resolve and import the okstra_token_usage package across layouts.
 
@@ -512,6 +611,22 @@ def _needs_token_autofix(team_state: dict, report_path: Path) -> bool:
         content = report_path.read_text()
         if any(p in content for p in TOKEN_PLACEHOLDERS):
             return True
+    # Even if the collector already ran (collectedAt is set), trigger when
+    # every recorded usage is zero AND at least one source is "unavailable".
+    # That combination means the previous collection silently failed to
+    # locate session jsonls — we must surface accuracy failures rather than
+    # let zeroed data ship as the final answer.
+    grand_total = summary.get("grandTotalTokens", 0)
+    if isinstance(grand_total, (int, float)) and grand_total == 0:
+        lead_unavailable = (
+            (team_state.get("leadUsage") or {}).get("source") == "unavailable"
+        )
+        workers_unavailable = any(
+            (w or {}).get("usage", {}).get("source") == "unavailable"
+            for w in (team_state.get("workers") or [])
+        )
+        if lead_unavailable or workers_unavailable:
+            return True
     return False
 
 
@@ -690,6 +805,18 @@ def main() -> int:
     write_json(run_manifest_path, run_manifest)
     write_json(task_manifest_path, task_manifest)
 
+    # Best-effort: regenerate discovery/task-catalog.json so downstream
+    # tools (okstra-schedule, FleetView listings, etc.) don't read a stale
+    # snapshot frozen at instruction-set generation time.
+    catalog_ok, catalog_msg = _refresh_task_catalog(project_root, task_manifest)
+    if catalog_ok:
+        print(f"validate-run: {catalog_msg}", file=sys.stderr)
+    else:
+        print(
+            f"validate-run: task-catalog refresh skipped — {catalog_msg}",
+            file=sys.stderr,
+        )
+
     if args.final_status:
         final_status_path = resolve_input(args.final_status)
         final_status_path.parent.mkdir(parents=True, exist_ok=True)

package/src/install.mjs

@@ -6,7 +6,9 @@ import { getPackageRoot } from "./version.mjs";
 import { resolvePaths } from "./paths.mjs";
 
 const SKILLS_MANIFEST_REL = "installed-skills.json";
+const AGENTS_MANIFEST_REL = "installed-agents.json";
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
+const CLAUDE_AGENTS_DIR = join(homedir(), ".claude", "agents");
 
 const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "lib"];
 const BIN_ENTRYPOINTS = [
@@ -32,18 +34,23 @@ Effect (copy mode):
   ${"$HOME"}/.okstra/lib/python   <- runtime/python
   ${"$HOME"}/.okstra/bin           <- runtime/bin
   ${"$HOME"}/.claude/skills/<name> <- runtime/skills/<name>   (per skill)
+  ${"$HOME"}/.claude/agents/<worker>.md <- runtime/agents/workers/<worker>.md
   ${"$HOME"}/.okstra/installed-skills.json   <- manifest of installed skills
+  ${"$HOME"}/.okstra/installed-agents.json   <- manifest of installed workers
   ${"$HOME"}/.okstra/version       <- installed package version stamp
 
 Effect (link mode):
   ${"$HOME"}/.okstra/lib/python/<pkg> -> <repo>/scripts/<pkg>   (symlink)
   ${"$HOME"}/.okstra/bin/<name>.sh    -> <repo>/scripts/<name>.sh
   ${"$HOME"}/.claude/skills/<name>    -> <repo>/skills/<name>   (symlink dir)
+  ${"$HOME"}/.claude/agents/<worker>.md -> <repo>/agents/workers/<worker>.md
   ${"$HOME"}/.okstra/dev-link         <- <repo> path stamp
   ${"$HOME"}/.okstra/version          <- installed package version stamp
 
-agents/ is NOT copied — it stays inside the package (copy mode) or is
-resolved to <repo>/agents (link mode) via 'okstra paths --field agents'.
+Worker agent definitions are installed into ${"$HOME"}/.claude/agents/ so
+that Claude Code's subagent discovery picks them up; they cannot live
+inside the package alone because the harness only scans ~/.claude/agents/
+and <project>/.claude/agents/.
 `;
 
 const ENSURE_USAGE = `okstra ensure-installed — idempotent install check
@@ -218,6 +225,9 @@ async function installLinkMode(repoPath, paths, opts) {
   const skillResult = await installSkillsLink(repoAbs, { dryRun, quiet });
   await writeSkillsManifest(paths.home, skillResult.installed, { dryRun });
 
+  const agentResult = await installAgentsLink(repoAbs, { dryRun, quiet });
+  await writeAgentsManifest(paths.home, agentResult.installed, { dryRun });
+
   if (!dryRun) {
     await writeFileAtomic(join(paths.home, "dev-link"), repoAbs + "\n", 0o644);
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
@@ -274,6 +284,98 @@ async function writeSkillsManifest(home, names, opts) {
   );
 }
 
+async function writeAgentsManifest(home, names, opts) {
+  const { dryRun = false } = opts ?? {};
+  const data = {
+    version: 1,
+    installedAt: new Date().toISOString(),
+    agents: Array.from(new Set(names)).sort(),
+  };
+  if (dryRun) {
+    process.stdout.write(`[dry-run] write agents manifest: ${data.agents.length} entries\n`);
+    return;
+  }
+  await writeFileAtomic(
+    join(home, AGENTS_MANIFEST_REL),
+    JSON.stringify(data, null, 2) + "\n",
+    0o644,
+  );
+}
+
+async function listWorkerFiles(workersRoot) {
+  try {
+    const entries = await fs.readdir(workersRoot, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isFile() && e.name.endsWith(".md"))
+      .map((e) => e.name);
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+async function installAgentsCopy(runtimeRoot, opts) {
+  const { refresh, dryRun, quiet } = opts;
+  const srcRoot = join(runtimeRoot, "agents", "workers");
+  const names = await listWorkerFiles(srcRoot);
+  if (names.length === 0) {
+    if (!quiet) process.stdout.write("  agents: runtime/agents/workers empty — skipped\n");
+    return { installed: [] };
+  }
+  if (!dryRun) await fs.mkdir(CLAUDE_AGENTS_DIR, { recursive: true });
+  let copied = 0;
+  let skipped = 0;
+  for (const name of names) {
+    const src = join(srcRoot, name);
+    const dst = join(CLAUDE_AGENTS_DIR, name);
+    let needsCopy = refresh;
+    if (!needsCopy) {
+      try {
+        await fs.access(dst);
+        const [a, b] = await Promise.all([hashFile(src), hashFile(dst)]);
+        needsCopy = a !== b;
+      } catch {
+        needsCopy = true;
+      }
+    }
+    if (!needsCopy) {
+      skipped++;
+      continue;
+    }
+    if (dryRun) {
+      process.stdout.write(`[dry-run] copy ${src} -> ${dst}\n`);
+    } else {
+      const buf = await fs.readFile(src);
+      await writeFileAtomic(dst, buf, 0o644);
+    }
+    copied++;
+  }
+  if (!quiet) {
+    process.stdout.write(
+      `  agents: copied=${copied} skipped=${skipped} -> ${CLAUDE_AGENTS_DIR}/ (${names.length} workers)\n`,
+    );
+  }
+  return { installed: names };
+}
+
+async function installAgentsLink(repoAbs, opts) {
+  const { dryRun, quiet } = opts;
+  const srcRoot = join(repoAbs, "agents", "workers");
+  const names = await listWorkerFiles(srcRoot);
+  if (names.length === 0) {
+    if (!quiet) process.stdout.write("  agents: <repo>/agents/workers missing — skipped\n");
+    return { installed: [] };
+  }
+  if (!dryRun) await fs.mkdir(CLAUDE_AGENTS_DIR, { recursive: true });
+  for (const name of names) {
+    const src = join(srcRoot, name);
+    const dst = join(CLAUDE_AGENTS_DIR, name);
+    const action = await ensureSymlink(src, dst, { dryRun });
+    if (!quiet) process.stdout.write(`  agents/${name}: ${action}\n`);
+  }
+  return { installed: names };
+}
+
 async function installSkillsCopy(runtimeRoot, opts) {
   const { refresh, dryRun, quiet } = opts;
   const srcRoot = join(runtimeRoot, "skills");
@@ -402,6 +504,9 @@ export async function runInstall(args) {
   const skillResult = await installSkillsCopy(runtimeRoot, opts);
   await writeSkillsManifest(paths.home, skillResult.installed, { dryRun: opts.dryRun });
 
+  const agentResult = await installAgentsCopy(runtimeRoot, opts);
+  await writeAgentsManifest(paths.home, agentResult.installed, { dryRun: opts.dryRun });
+
   if (!opts.dryRun) {
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
   }
@@ -419,6 +524,29 @@ export async function runInstall(args) {
   return 0;
 }
 
+async function agentDriftReasons(paths) {
+  const reasons = [];
+  const workersDir = join(paths.agents, "workers");
+  const expected = await listWorkerFiles(workersDir);
+  if (expected.length === 0) return reasons;
+  for (const name of expected) {
+    const target = join(CLAUDE_AGENTS_DIR, name);
+    try {
+      const lst = await fs.lstat(target);
+      if (lst.isSymbolicLink()) {
+        try {
+          await fs.stat(target);
+        } catch {
+          reasons.push(`dangling symlink ${target}`);
+        }
+      }
+    } catch {
+      reasons.push(`missing agent ${target}`);
+    }
+  }
+  return reasons;
+}
+
 function summarise(label, result, target) {
   if (result.missingSource) {
     process.stdout.write(`  ${label}: source directory missing — skipped\n`);
@@ -447,6 +575,9 @@ export async function runEnsureInstalled(args) {
   if (!(await fileExists(join(CLAUDE_SKILLS_DIR, "okstra-setup", "SKILL.md")))) {
     reasons.push(`missing ${CLAUDE_SKILLS_DIR}/okstra-setup/SKILL.md`);
   }
+  for (const reason of await agentDriftReasons(paths)) {
+    reasons.push(reason);
+  }
 
   if (reasons.length === 0) {
     if (!quiet) process.stdout.write(`okstra runtime OK (package ${paths.package})\n`);

package/src/uninstall.mjs

@@ -26,21 +26,34 @@ const FALLBACK_SKILL_NAMES = [
   "okstra-time-summary",
 ];
 
+const FALLBACK_AGENT_NAMES = [
+  "claude-worker.md",
+  "codex-worker.md",
+  "gemini-worker.md",
+  "report-writer-worker.md",
+];
+
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
+const CLAUDE_AGENTS_DIR = join(homedir(), ".claude", "agents");
 const SKILLS_MANIFEST_REL = "installed-skills.json";
+const AGENTS_MANIFEST_REL = "installed-agents.json";
 
-const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra and ~/.claude/skills
+const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra, ~/.claude/skills, ~/.claude/agents
 
 Usage:
   okstra uninstall              Remove ~/.okstra/{lib, bin/<known>, version,
-                                dev-link, installed-skills.json} AND
-                                ~/.claude/skills/<name> for every entry in
-                                the install manifest (fallback: hard-coded
-                                okstra-* names). Preserves user data:
-                                recent.jsonl, active.jsonl, projects/,
-                                archive/, state.json, .locks/
+                                dev-link, installed-skills.json,
+                                installed-agents.json} AND
+                                ~/.claude/skills/<name> AND
+                                ~/.claude/agents/<worker>.md for every
+                                entry in the install manifests (fallback:
+                                hard-coded okstra-* / *-worker.md names).
+                                Preserves user data: recent.jsonl,
+                                active.jsonl, projects/, archive/,
+                                state.json, .locks/
   okstra uninstall --purge      Remove the entire ~/.okstra directory AND
-                                ~/.claude/skills/<okstra-*> (DESTRUCTIVE).
+                                ~/.claude/skills/<okstra-*> AND
+                                ~/.claude/agents/<*-worker.md> (DESTRUCTIVE).
                                 Requires -y or an interactive confirmation
   okstra uninstall --dry-run    Print the plan without touching disk
   okstra uninstall -y           Skip confirmation prompt for --purge
@@ -112,10 +125,13 @@ export async function runUninstall(args) {
     }
     if (!opts.quiet) process.stdout.write(`purging ${paths.home}\n`);
     await removePath(paths.home, opts);
-    // Skills live outside ~/.okstra — purge those too with the fallback list.
+    // Skills and worker agents live outside ~/.okstra — purge those too.
     for (const name of FALLBACK_SKILL_NAMES) {
       await removePath(join(CLAUDE_SKILLS_DIR, name), opts);
     }
+    for (const name of FALLBACK_AGENT_NAMES) {
+      await removePath(join(CLAUDE_AGENTS_DIR, name), opts);
+    }
     return 0;
   }
 
@@ -154,6 +170,16 @@ export async function runUninstall(args) {
   }
   await removePath(join(paths.home, SKILLS_MANIFEST_REL), opts);
 
+  // Remove worker agents we own. Same authoritative-manifest pattern as skills.
+  const agentNames = await readAgentsManifest(paths.home);
+  if (!opts.quiet) {
+    process.stdout.write(`  agents: removing ${agentNames.length} entries from ${CLAUDE_AGENTS_DIR}\n`);
+  }
+  for (const name of agentNames) {
+    await removePath(join(CLAUDE_AGENTS_DIR, name), opts);
+  }
+  await removePath(join(paths.home, AGENTS_MANIFEST_REL), opts);
+
   await removePath(join(paths.home, "version"), opts);
   await removePath(join(paths.home, "dev-link"), opts);
 
@@ -173,3 +199,14 @@ async function readSkillsManifest(home) {
   }
   return FALLBACK_SKILL_NAMES;
 }
+
+async function readAgentsManifest(home) {
+  try {
+    const raw = await fs.readFile(join(home, AGENTS_MANIFEST_REL), "utf8");
+    const data = JSON.parse(raw);
+    if (Array.isArray(data?.agents)) return data.agents;
+  } catch {
+    /* fall through */
+  }
+  return FALLBACK_AGENT_NAMES;
+}