okstra 0.43.0 → 0.43.1

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.43.0",
-  "builtAt": "2026-06-04T04:59:06.499Z",
+  "package": "0.43.1",
+  "builtAt": "2026-06-04T05:01:10.794Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -216,6 +216,8 @@ Use agent and subagent names that map cleanly to the selected worker roles. Do n
 
 Spawn **analysis workers only** in the same turn (Phase 4 in Teams mode; Phase 5 with `run_in_background: true` and no `team_name` when Teams unavailable). Preserve exact roster, role labels, assigned models from the task bundle.
 
+**Agent `name` on dispatch (BLOCKING — token-usage attribution depends on it).** Every analysis-worker `Agent(...)` call MUST set `name: "<workerId>-worker"` — `name: "claude-worker"` / `name: "codex-worker"` / `name: "gemini-worker"` — exactly as the report-writer dispatch sets `name: "report-writer"` ([okstra-report-writer](./skills/okstra-report-writer/SKILL.md)). The Agent harness records this `name` as `agentName` in the subagent session jsonl, and the Phase 7 token collector matches each worker's session by that `agentName` (`okstra_token_usage/collect.py`). A worker dispatched **without** `name` produces a session with no `agentName`; the collector cannot attribute it and records the worker as `source: "unavailable"` even though the session exists and is team-tagged (observed in `dev-9692` error-analysis: `claude`/`codex` workers dispatched without `name` → both `unavailable`, while the named `report-writer` collected normally). Convergence reverify dispatches keep the prefix (`<workerId>-worker-reverify-r<N>`); implementation executor/verifier variants keep `<workerId>-worker` / `<workerId>-executor`.
+
 The no-`team_name` fallback (Phase 5) is only legal when team-state's `teamCreate.status` is `"error"` for this run. If `teamCreate` is missing or `attempted: false`, the correct action when an Agent dispatch is rejected for a missing team is to GO BACK to Phase 3 and call `TeamCreate` — never to strip `team_name` and continue.
 
 ### Errors log path wiring (BLOCKING)

package/runtime/bin/okstra-spawn-followups.py

@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+"""OKSTRA follow-up task spawner.
+
+Reads the ``followUpTasks[]`` array from a final-report ``data.json``
+(the JSON SSOT for the final-report markdown) and creates stub task
+directories for rows whose ``autoSpawn`` is ``yes`` AND whose ``origin``
+is not the same-task-key ``phase-continuation`` marker.
+
+Idempotent: rows whose target directory already exists are reported as
+``existing`` and skipped. Existing directories are NEVER mutated.
+
+Output: writes new directories under
+``<project_root>/.okstra/tasks/<task-group>/<new-task-id>/`` with:
+- ``task-manifest.json`` — minimal manifest (schemaVersion 1.0,
+  currentStatus ``todo``, workflow.currentPhase = suggestedTaskType,
+  workflow.currentPhaseState ``not-started``, parentTaskKey /
+  spawnedFromReport recorded under ``relatedTasks``).
+- ``instruction-set/task-brief.md`` — stub brief naming the parent and
+  copying the Reason / Scope cells from the data.json row.
+- ``task-index.md`` — short human-readable summary.
+
+The script DOES NOT call the okstra runtime; it produces just enough
+on-disk state for the next user-driven entry — ``/okstra-run
+task-key=<new-key> task-type=<suggested>`` inside a Claude Code session,
+or ``scripts/okstra.sh --task-key <new-key> --task-type <suggested>``
+in a separate terminal — to pick the follow-up up and re-render a fully
+canonical manifest on first execution.
+
+Usage:
+    python3 scripts/okstra-spawn-followups.py \\
+        <final-report-data.json> \\
+        --project-root <abs-path> \\
+        --task-group <group-slug> \\
+        --parent-task-key <parent-task-key> \\
+        [--dry-run]
+
+Exit codes:
+    0  — at least one follow-up evaluated (including ``skipped`` /
+         ``existing`` only)
+    1  — invocation / parsing failure, or any row failed validation
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from okstra_project.dirs import tasks_root  # noqa: E402
+
+
+SLUG_RE = re.compile(r"[^a-zA-Z0-9-]+")
+
+ALLOWED_TASK_TYPES = {
+    "requirements-discovery",
+    "error-analysis",
+    "implementation-planning",
+    "implementation",
+    "final-verification",
+    "release-handoff",
+}
+ALLOWED_ORIGINS = {
+    "phase-continuation",
+    "out-of-plan",
+    "verifier-concern",
+    "scope-boundary",
+    "open-question",
+    "manual",
+}
+# Origins that point at the SAME task-key (next phase) and therefore
+# must never spawn a new task directory — the user advances via
+# /okstra-run.
+NON_SPAWNING_ORIGINS = {"phase-continuation"}
+
+
+def _slugify(value: str) -> str:
+    value = value.strip()
+    value = SLUG_RE.sub("-", value)
+    value = re.sub(r"-+", "-", value)
+    return value.strip("-").lower()
+
+
+def _validate_row(row: dict) -> tuple[bool, str]:
+    origin = (row.get("origin") or "").strip()
+    if origin not in ALLOWED_ORIGINS:
+        return False, f"invalid origin: {origin!r}"
+    task_type = (row.get("suggestedTaskType") or "").strip()
+    if task_type not in ALLOWED_TASK_TYPES:
+        return False, f"invalid suggestedTaskType: {task_type!r}"
+    if not (row.get("title") or "").strip():
+        return False, "title is empty"
+    if not (row.get("reason") or "").strip():
+        return False, "reason is empty"
+    if not (row.get("newTaskId") or "").strip():
+        return False, "newTaskId is empty"
+    return True, ""
+
+
+def _write_manifest(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+
+
+def _data_to_report_path(data_path: Path) -> Path:
+    """Derive the markdown sibling path used in spawned manifests for
+    the `parentReportPath` field. Falls back to the data.json itself if
+    the suffix is not recognised.
+    """
+    name = data_path.name
+    if name.endswith(".data.json"):
+        return data_path.with_name(name[: -len(".data.json")] + ".md")
+    return data_path.with_suffix(".md")
+
+
+def _spawn_one(
+    *,
+    project_root: Path,
+    task_group: str,
+    parent_task_key: str,
+    parent_report_relative: str,
+    row: dict,
+    dry_run: bool,
+) -> tuple[str, str]:
+    """Returns (status, target_relative_path).
+
+    status ∈ {created, existing, skipped, invalid}
+    """
+    ok, why = _validate_row(row)
+    if not ok:
+        return ("invalid", why)
+
+    new_task_id = _slugify(row["newTaskId"])
+    if not new_task_id:
+        return ("invalid", "newTaskId slug is empty after normalisation")
+
+    task_root = (
+        tasks_root(project_root)
+        / _slugify(task_group)
+        / new_task_id
+    )
+    rel = task_root.relative_to(project_root).as_posix()
+    if task_root.exists():
+        return ("existing", rel)
+    if dry_run:
+        return ("created", rel)
+
+    suggested = row["suggestedTaskType"].strip()
+    title = row["title"].strip()
+    scope = (row.get("scope") or "").strip()
+    reason = row["reason"].strip()
+    origin = row["origin"].strip()
+    priority = (row.get("priority") or "P1").strip()
+    ticket_id = (row.get("ticketId") or "").strip()
+    new_task_key = f"{task_group}/{new_task_id}"
+    now = dt.datetime.now(dt.timezone.utc).isoformat()
+
+    spawned_meta: dict = {
+        "parentTaskKey": parent_task_key,
+        "parentReportPath": parent_report_relative,
+        "origin": origin,
+        "rowId": row.get("id", ""),
+        "priority": priority,
+        "spawnedAt": now,
+    }
+    if ticket_id:
+        spawned_meta["ticketId"] = ticket_id
+
+    manifest_payload = {
+        "schemaVersion": "1.0",
+        "taskGroup": task_group,
+        "taskId": new_task_id,
+        "taskKey": new_task_key,
+        "taskGroupPathSegment": _slugify(task_group),
+        "taskIdPathSegment": new_task_id,
+        "taskType": suggested,
+        "workCategory": "unknown",
+        "currentStatus": "todo",
+        "spawnedFromFollowUp": spawned_meta,
+        "relatedTasks": [
+            {"taskKey": parent_task_key, "relation": "parent-followup-source"},
+        ],
+        "workflow": {
+            "currentPhase": suggested,
+            "currentPhaseState": "not-started",
+            "nextRecommendedPhase": suggested,
+            "phaseStates": {},
+            "awaitingApproval": False,
+            "routingStatus": "follow-up-spawned",
+        },
+    }
+    _write_manifest(task_root / "task-manifest.json", manifest_payload)
+
+    brief_path = task_root / "instruction-set" / "task-brief.md"
+    brief_path.parent.mkdir(parents=True, exist_ok=True)
+    ticket_line = f"- Ticket ID: `{ticket_id}`\n" if ticket_id else ""
+    brief_body = (
+        f"# Follow-up Task Brief — {new_task_key}\n\n"
+        f"- Spawned from: `{parent_task_key}`\n"
+        f"{ticket_line}"
+        f"- Origin: `{origin}`\n"
+        f"- Source report row: `{row.get('id', '')}` in `{parent_report_relative}`\n"
+        f"- Suggested task-type: `{suggested}`\n"
+        f"- Priority: `{priority}`\n"
+        f"- Spawned at: `{now}`\n\n"
+        f"## Title\n\n{title}\n\n"
+        f"## Scope (files / areas)\n\n{scope or '_(미지정)_'}\n\n"
+        f"## Reason / Why deferred from parent run\n\n{reason}\n\n"
+        f"## Next step\n\n"
+        f"이 stub은 사용자가 정식 진입할 때 자동 갱신됩니다. 다음 명령 중 하나로 시작하세요:\n\n"
+        f"- Claude Code 세션 안: `/okstra-run task-key={new_task_key} task-type={suggested}`\n"
+        f"- 별도 터미널: `scripts/okstra.sh --task-key {new_task_key} --task-type {suggested}`\n"
+    )
+    brief_path.write_text(brief_body, encoding="utf-8")
+
+    index_path = task_root / "task-index.md"
+    index_body = (
+        f"# {new_task_key} — Follow-up Task (todo)\n\n"
+        f"- Parent: `{parent_task_key}`\n"
+        f"{ticket_line}"
+        f"- Suggested task-type: `{suggested}`\n"
+        f"- Origin: `{origin}`\n"
+        f"- Priority: `{priority}`\n"
+        f"- Spawned from report: `{parent_report_relative}`\n"
+        f"- Stub brief: `instruction-set/task-brief.md`\n"
+        f"- Status: `todo`\n\n"
+        f"이 task는 자동 생성된 follow-up stub입니다. 정식 진입 시 manifest가 재렌더링됩니다.\n"
+    )
+    index_path.write_text(index_body, encoding="utf-8")
+
+    return ("created", rel)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Spawn follow-up task stubs from a final-report data.json.",
+    )
+    parser.add_argument(
+        "data_file",
+        type=Path,
+        help="Path to the final-report data.json (the JSON SSOT).",
+    )
+    parser.add_argument("--project-root", type=Path, required=True)
+    parser.add_argument(
+        "--task-group",
+        required=True,
+        help="Task-group slug of the parent task.",
+    )
+    parser.add_argument("--parent-task-key", required=True)
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Parse and validate only; do not write files.",
+    )
+    args = parser.parse_args(argv)
+
+    if not args.data_file.exists():
+        print(f"data.json not found: {args.data_file}", file=sys.stderr)
+        return 1
+
+    try:
+        data = json.loads(args.data_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"invalid JSON in {args.data_file}: {exc}", file=sys.stderr)
+        return 1
+
+    rows = data.get("followUpTasks") or []
+    if not rows:
+        print("followUpTasks is empty — nothing to do.")
+        return 0
+
+    # Manifests record the markdown sibling rather than data.json so the
+    # user-facing report (and not the SSOT) is the cite-able artifact.
+    parent_report = _data_to_report_path(args.data_file)
+    try:
+        parent_report_relative = (
+            parent_report.resolve().relative_to(args.project_root.resolve()).as_posix()
+        )
+    except ValueError:
+        parent_report_relative = str(parent_report)
+
+    results = []
+    for row in rows:
+        origin = (row.get("origin") or "").strip().lower()
+        if origin in NON_SPAWNING_ORIGINS:
+            results.append((
+                "skipped",
+                row.get("newTaskId", ""),
+                f"{origin} (advance via /okstra-run, no new task dir)",
+            ))
+            continue
+        if (row.get("autoSpawn") or "").strip().lower() != "yes":
+            results.append((
+                "skipped",
+                row.get("newTaskId", ""),
+                "autoSpawn != yes",
+            ))
+            continue
+        status, info = _spawn_one(
+            project_root=args.project_root,
+            task_group=args.task_group,
+            parent_task_key=args.parent_task_key,
+            parent_report_relative=parent_report_relative,
+            row=row,
+            dry_run=args.dry_run,
+        )
+        results.append((status, row.get("newTaskId", ""), info))
+
+    print(f"Follow-up spawn summary ({'dry-run' if args.dry_run else 'live'}):")
+    for status, task_id, info in results:
+        print(f"  - [{status}] {task_id}: {info}")
+
+    if any(status == "invalid" for status, *_ in results):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_token_usage/collect.py

@@ -118,6 +118,14 @@ def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
     claude_sessions = find_claude_team_sessions(cwd, team_name, lead_sid)
     by_agent: dict[str, list[tuple[str, Path, dict]]] = {}
     lead_path: Path | None = None
+    # Team-tagged non-lead sessions that carry no agentName. These are almost
+    # always a worker dispatched without the Agent `name` arg (so the harness
+    # recorded no agentName) — the session exists and is team-tagged, but there
+    # is nothing to match it to a workerId by. Surfacing them in usageSummary
+    # gives the "unavailable" worker a visible cause instead of vanishing
+    # silently (observed in dev-9692 error-analysis: claude/codex workers
+    # dispatched without `name` → both unavailable, report-writer named → fine).
+    unattributed_sessions: list[str] = []
     for sid, path in claude_sessions.items():
         if sid == lead_sid:
             lead_path = path
@@ -126,6 +134,8 @@ def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
         agent = totals.get("agentName")
         if agent:
             by_agent.setdefault(agent, []).append((sid, path, totals))
+        else:
+            unattributed_sessions.append(sid)
 
     # Lead.
     if lead_path is not None:
@@ -242,6 +252,7 @@ def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
         "teamName": team_name,
         "sessionsFound": len(claude_sessions),
         "unmatchedModels": sorted(set(unmatched_models)),
+        "unattributedTeamSessions": unattributed_sessions,
         "definitions": {
             "totalTokens": "Sum of input + output + cache_creation + cache_read tokens (raw processed volume; matches Anthropic API breakdown). Cache reads are 95%+ in long sessions.",
             "billableEquivalentTokens": "Tokens normalized to base-input-price units (cache_creation_5m x1.25, cache_creation_1h x2.0, cache_read x0.1, output x5). 5m vs 1h is split from usage.cache_creation when the API breakdown is present; otherwise all cache_creation falls into 5m.",

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -366,7 +366,7 @@ okstra token-usage /abs/path/to/run/state/team-state-<task-type>-<seq>.json --wr
 `okstra token-usage` is a thin Node-side wrapper around the python helper installed at `~/.okstra/bin/okstra-token-usage.py`. Calling the python script directly with `python3 "$HOME/..."` is forbidden — the `$HOME` expansion breaks the literal-token permission match and forces a confirmation prompt every call.
 
 The script reads:
-- `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl` for the lead and every Claude-side worker (Claude worker, Report writer worker, plus the Claude wrappers around Codex/Gemini workers). Sessions are discovered by `teamName: okstra-<task-id>`, lead is identified by `lead.sessionId`, and other workers are identified by `agentName` (e.g. `claude-worker`, `codex-worker`, `gemini-worker`, `report-writer`).
+- `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl` for the lead and every Claude-side worker (Claude worker, Report writer worker, plus the Claude wrappers around Codex/Gemini workers). Sessions are discovered by `teamName: okstra-<task-id>`, lead is identified by `lead.sessionId`, and other workers are identified by `agentName` (e.g. `claude-worker`, `codex-worker`, `gemini-worker`, `report-writer`). **For this `agentName` match to work, Lead MUST set the Agent `name` arg to `<workerId>-worker` on every dispatch** (see [agents SKILL.md Phase 4 — "Agent `name` on dispatch"](../../agents/SKILL.md)); a worker dispatched without `name` carries no `agentName`, so the collector cannot attribute its session and records it `unavailable` (now surfaced as a `usageSummary.unattributedTeamSessions` entry rather than dropped silently).
 - `~/.codex/sessions/Y/M/D/rollout-*.jsonl` for the underlying Codex CLI session (matched by `cwd` and timestamp window of the wrapper subagent). Last `event_msg.token_count.total_token_usage.total_tokens` is the session total.
 - `~/.gemini/tmp/<project>/chats/session-*.json` for the underlying Gemini CLI session. Sum of per-message `tokens.total`.
 

package/src/install.mjs

@@ -28,6 +28,7 @@ const BIN_ENTRYPOINTS = [
   "okstra-render-report-views.py",
   "okstra-render-final-report.py",
   "okstra-wrapper-status.py",
+  "okstra-spawn-followups.py",
 ];
 
 const INSTALL_USAGE = `okstra install — install runtime into ~/.okstra