okstra 0.201.3 → 0.202.0

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -122,6 +122,7 @@ class MutationAuditResult:
     changed_artifact_paths: tuple[str, ...] = ()
     declared_out_of_plan_paths: tuple[str, ...] = ()
     unobserved_artifact_paths: tuple[str, ...] = ()
+    external_workspace_changes: tuple[str, ...] = ()
 
     def change_summary(self) -> dict[str, Any]:
         return {
@@ -138,6 +139,7 @@ class MutationAuditResult:
             "changedArtifactPaths": list(self.changed_artifact_paths),
             "declaredOutOfPlanPaths": list(self.declared_out_of_plan_paths),
             "unobservedArtifactPaths": list(self.unobserved_artifact_paths),
+            "externalWorkspaceChanges": list(self.external_workspace_changes),
             "beforeDigest": self.before_digest,
             "afterDigest": self.after_digest,
         }
@@ -240,13 +242,13 @@ class ExecutionMutationAudit:
             rows,
             source_changes,
         )
-        artifact_failures, untracked_artifact_changes, switched = (
+        artifact_failures, untracked_artifact_changes, switched, external = (
             _artifact_policy_failures(before, rows, artifact_changed, after=after)
         )
         violations.extend(artifact_failures)
         worker_artifact_changes = {
             path for path in artifact_changed
-            if path not in untracked_artifact_changes and path not in switched
+            if path not in untracked_artifact_changes and path not in switched and path not in external
             and not any(_is_relative_to(before.artifact_root / path, Path(item))
                         for item in before.orchestrator_paths)
         }
@@ -276,11 +278,14 @@ class ExecutionMutationAudit:
             untracked_artifact_paths=tuple(sorted(untracked_artifact_changes)),
             warnings=_audit_warnings(untracked_artifact_changes)
             + _branch_switch_warnings(before, after, switched)
+            + tuple(f"unattributed change outside assigned worktree and artifact paths: {path}"
+                    for path in sorted(external))
             + _plan_change_warnings(rows, source_changes | untracked_changes,
                                     artifact_changed, out_of_plan_edits, unobserved),
-            changed_artifact_paths=tuple(sorted(artifact_changed)),
+            changed_artifact_paths=tuple(sorted(artifact_changed - external)),
             declared_out_of_plan_paths=tuple(out_of_plan_edits),
             unobserved_artifact_paths=tuple(sorted(unobserved)),
+            external_workspace_changes=tuple(sorted(external)),
         )
 
 
@@ -753,22 +758,12 @@ def _artifact_policy_failures(
     changed: set[str],
     *,
     after: MutationSnapshot | None = None,
-) -> tuple[list[str], set[str], set[str]]:
-    """``(위반 목록, 위반이 아닌 비추적 신규 경로, 브랜치 전환으로 설명되는 경로)``.
-
-    artifact root 의 변경 중 위반으로 남는 것은 두 부류다 — okstra 산출물
-    서브트리(`.okstra/`) 안의 허용 밖 쓰기와, git 이 추적하는 파일의 변경.
-    그 밖의 비추적 신규 파일은 워커의 도구가 남긴 로그·캐시이므로 소스 root 의
-    `_split_tracked` 와 같은 이유로 기록만 한다. artifact root 가 git 레포가
-    아니면 추적 여부를 알 수 없으므로 종전대로 전부 위반으로 본다.
-
-    추적 파일의 변경 중 **artifact root 의 HEAD 가 실행 창 안에서 옮겨졌고 그
-    두 커밋 사이에서 실제로 달라지는 경로**는 워커의 쓰기가 아니라 사람의 브랜치
-    전환이다. 실측(2026-09-09, `fontsninja-v3-site` dev-10627 reverify r1b): 워커가
-    워크트리에서 읽기만 하는 8분 동안 프로젝트 루트에서 `checkout preprod →
-    rebase` 가 있었고, run 브랜치에만 있는 `CardHero.{tsx,styled.ts}` 가 사라져
-    완주한 결과가 `contract-failed-unattributed` 로 폐기됐다. 그 경로는 위반에서
-    빼고 경고로 남긴다. 전환으로 설명되지 않는 추적 파일 변경은 그대로 위반이다.
+) -> tuple[list[str], set[str], set[str], set[str]]:
+    """위반·비추적 파일·브랜치 전환·외부 작업공간 관측을 분리한다.
+
+    작업트리와 기본 체크아웃이 다르면 기본 체크아웃 소스의 변경 주체는
+    전후 비교로 판단할 수 없다. 배정된 산출물 밖의 변경은 관측으로 남기고,
+    `.okstra` 내부의 허용 밖 쓰기와 배정된 소스 정책은 별도로 검사한다.
     """
     allowed = _allowed_artifact_paths(policies)
     orchestrator = {
@@ -799,9 +794,14 @@ def _artifact_policy_failures(
         if path in unauthorized and not _is_within(path, _OKSTRA_ARTIFACT_SUBTREE)
     }
     untracked_outside -= switched
-    violating = unauthorized - untracked_outside - switched
+    external = {
+        path for path in unauthorized - untracked_outside - switched
+        if snapshot.artifact_root != snapshot.root
+        and not _is_within(path, _OKSTRA_ARTIFACT_SUBTREE)
+    }
+    violating = unauthorized - untracked_outside - switched - external
     failures = ["artifact-root change exceeds batch policy union"] if violating else []
-    return failures, untracked_outside, switched
+    return failures, untracked_outside, switched, external
 
 
 def _branch_switch_paths(

package/runtime/python/okstra_ctl/manager_cli.py

@@ -10,6 +10,7 @@ from okstra_project.dirs import okstra_home
 
 from .manager_launch import build_launch_packet
 from .fixed_text import line, value_lines
+from .manager_paths import ManagerPathError
 from .manager_store import (
     ManagerError,
     append_directive,
@@ -19,20 +20,40 @@ from .manager_store import (
     discover_projects,
     init_manager,
     link_project,
+    list_managers,
+    list_projects,
+    list_tasks,
 )
+from .manager_split import split_task
 from .manager_sync import status_task, sync_task
+from .manager_view import write_view
+
+# list 명령마다 목록 한 줄에 싣는 (라벨, 키). 라벨은 "<접두어> <번호> <라벨>" 로 찍힌다.
+_LIST_ROWS = {
+    "discover-projects": ("Project", (("ID", "projectId"), ("root", "projectRoot"),
+                                      ("run count", "runCount"), ("active count", "activeCount"),
+                                      ("last run at", "lastRunAt"))),
+    "list-managers": ("Manager", (("ID", "managerId"), ("created at", "createdAt"),
+                                  ("project count", "projectCount"), ("task count", "taskCount"))),
+    "list-projects": ("Project", (("ID", "projectId"), ("root", "projectRoot"), ("role", "role"),
+                                  ("tags", "tags"), ("linked at", "linkedAt"))),
+    "list-tasks": ("Task", (("group", "taskGroup"), ("ID", "taskId"), ("objective", "objective"),
+                            ("progress mode", "progressMode"), ("child count", "childCount"),
+                            ("created at", "createdAt"))),
+}
 
 
 def render_manager_text(command: str, payload: dict | list[dict]) -> str:
     """manager 모델 표면에 승인된 식별자와 상태만 투영한다."""
     allowed = {"init", "discover-projects", "new-project", "new-task-group", "new-task",
-               "task-assign", "task-note", "task-sync", "task-status", "task-run"}
+               "task-assign", "task-note", "task-sync", "task-status", "task-run", "task-split",
+               "list-managers", "list-projects", "list-tasks", "view"}
     if command not in allowed:
         raise ValueError("unknown manager text purpose")
     rows = [f"Okstra manager {command}\n", line("Status", "ready")]
     if isinstance(payload, list):
         rows.append(line("Result count", len(payload)))
-        rows.extend(_render_manager_projects(payload))
+        rows.extend(_render_list(command, payload))
         return "".join(rows)
     if command == "task-status":
         rows.extend(_render_manager_status(payload))
@@ -44,7 +65,9 @@ def render_manager_text(command: str, payload: dict | list[dict]) -> str:
                        ("Work status", "workStatus"), ("Run command", "command"),
                        ("Backend", "backend"),
                        ("Worker dispatch backend", "workerDispatchBackend"),
-                       ("Project root", "projectRoot"), ("Context path", "contextPath")):
+                       ("Project root", "projectRoot"), ("Context path", "contextPath"),
+                       ("Shell command", "shellCommand"), ("View path", "viewPath"),
+                       ("View URL", "viewUrl")):
         if key in payload:
             rows.append(line(label, payload.get(key)))
     run_args = payload.get("runArgs")
@@ -64,20 +87,27 @@ def render_manager_text(command: str, payload: dict | list[dict]) -> str:
                            ("Directive body", "body"), ("Created at", "createdAt"),
                            ("Source", "source")):
             rows.append(line(label, payload.get(key)))
+    if command == "task-split":
+        briefs = payload.get("briefs") if isinstance(payload.get("briefs"), list) else []
+        rows.append(line("Brief count", len(briefs)))
+        for index, brief in enumerate(briefs, 1):
+            for label, key in (("task key", "taskKey"), ("project ID", "projectId"), ("ticket", "ticketId"),
+                               ("path", "briefPath"), ("status", "briefStatus")):
+                rows.append(line(f"Brief {index} {label}", brief.get(key)))
     if command == "task-sync" and "syncedAt" in payload:
         rows.append(line("Synced at", payload.get("syncedAt")))
     return "".join(rows)
 
 
-def _render_manager_projects(projects: list[dict]) -> list[str]:
+def _render_list(command: str, items: list[dict]) -> list[str]:
+    prefix, fields = _LIST_ROWS[command]
     rows: list[str] = []
-    for index, project in enumerate(projects, 1):
-        if not isinstance(project, dict):
+    for index, item in enumerate(items, 1):
+        if not isinstance(item, dict):
             continue
-        for label, key in (("ID", "projectId"), ("root", "projectRoot"),
-                           ("run count", "runCount"), ("active count", "activeCount"),
-                           ("last run at", "lastRunAt")):
-            rows.append(line(f"Project {index} {label}", project.get(key)))
+        for label, key in fields:
+            value = item.get(key)
+            rows.append(line(f"{prefix} {index} {label}", ", ".join(value) if isinstance(value, list) else value))
     return rows
 
 
@@ -96,6 +126,7 @@ def _render_manager_status(payload: dict) -> list[str]:
             continue
         for label, key in (("task key", "taskKey"), ("run status", "latestRunStatus"),
                            ("current phase", "currentPhase"), ("work status", "workStatus"),
+                           ("summary", "summaryBucket"), ("ticket", "ticketId"), ("brief path", "briefPath"),
                            ("report path", "latestReportRecordPath"), ("error", "error")):
             if key in child:
                 rows.append(line(f"Child {index} {label}", child.get(key)))
@@ -156,6 +187,11 @@ _CLI_EPILOG = r"""Usage:
   okstra manager task assign --manager-id <id> --task-group <task-group> --task-id <task-id> --project-id <project-id>
   okstra manager task note --manager-id <id> --task-group <task-group> --task-id <task-id> --scope <shared|project> --body <text>
   okstra manager task run --manager-id <id> --project-id <project-id> --task-group <task-group> --task-id <task-id>
+  okstra manager task split --manager-id <id> --task-group <task-group> --task-id <task-id> --plan <split-plan.json> [--overwrite]
+  okstra manager list managers
+  okstra manager list projects --manager-id <id>
+  okstra manager list tasks --manager-id <id>
+  okstra manager view --manager-id <id>
 
   --workspace-root is owned by this command.
 """
@@ -198,7 +234,7 @@ def _parser() -> argparse.ArgumentParser:
     task_new.add_argument("--task", action="append", default=[])
     task_new.add_argument("--objective", default="")
     task_new.add_argument("--common-brief", default="")
-    task_new.add_argument("--progress-mode", choices=["manual", "auto"], default="manual")
+    task_new.add_argument("--progress-mode", choices=["manual", "auto"], default=None)
 
     task = sub.add_parser("task")
     task_sub = task.add_subparsers(dest="task_command", required=True)
@@ -233,6 +269,22 @@ def _parser() -> argparse.ArgumentParser:
     run.add_argument("--task-group", required=True)
     run.add_argument("--task-id", required=True)
     run.add_argument("--child-task-id", default=None)
+
+    split = task_sub.add_parser("split")
+    split.add_argument("--manager-id", required=True)
+    split.add_argument("--task-group", required=True)
+    split.add_argument("--task-id", required=True)
+    split.add_argument("--plan", required=True)
+    split.add_argument("--overwrite", action="store_true")
+
+    listing = sub.add_parser("list")
+    list_sub = listing.add_subparsers(dest="list_command", required=True)
+    list_sub.add_parser("managers")
+    for name in ("projects", "tasks"):
+        list_sub.add_parser(name).add_argument("--manager-id", required=True)
+
+    view = sub.add_parser("view")
+    view.add_argument("--manager-id", required=True)
     return parser
 
 
@@ -322,11 +374,32 @@ def main(argv: list[str] | None = None) -> int:
                 ),
                 args.json,
             )
+        elif args.command == "task" and args.task_command == "split":
+            _emit(
+                "task-split",
+                split_task(
+                    home,
+                    args.manager_id,
+                    args.task_group,
+                    args.task_id,
+                    Path(args.plan),
+                    overwrite=args.overwrite,
+                ),
+                args.json,
+            )
+        elif args.command == "list" and args.list_command == "managers":
+            _emit("list-managers", list_managers(home), args.json)
+        elif args.command == "list" and args.list_command == "projects":
+            _emit("list-projects", list_projects(home, args.manager_id), args.json)
+        elif args.command == "list" and args.list_command == "tasks":
+            _emit("list-tasks", list_tasks(home, args.manager_id), args.json)
+        elif args.command == "view":
+            _emit("view", write_view(home, args.manager_id), args.json)
         else:
             parser.print_help()
             return 2
         return 0
-    except ManagerError as exc:
+    except (ManagerError, ManagerPathError) as exc:
         print(f"okstra manager: {exc}", file=sys.stderr)
         return 2
 

package/runtime/python/okstra_ctl/manager_launch.py

@@ -1,6 +1,7 @@
 """Build manager child launch packets and context documents."""
 from __future__ import annotations
 
+import shlex
 from pathlib import Path
 
 from okstra_ctl.jsonl import append_jsonl, read_jsonl
@@ -15,12 +16,16 @@ from .manager_paths import (
     task_manifest_path,
 )
 from .manager_store import ManagerError, _now_iso, _read_json, _read_json_default, _write_json
+from .manager_sync import _resolve_task_root_read_only
 
 
 WORKER_DISPATCH_BACKEND = "subagent"
-# child lead 는 언제나 subagent 로 뜬다. 예전에는 `$TMUX` 가 잡히면
-# `tmux-child-lead` 를 골랐지만 tmux 백엔드가 사라져 분기가 남지 않았다.
-CHILD_LEAD_BACKEND = "subagent-child-lead"
+# child lead 는 설치본 런처(`okstra.sh`)가 새 host 프로세스로 띄운다. `okstra run`
+# 은 lead host 에 `--launch-only` 를 붙여 task 인자와 `--directive` 를 버리므로
+# child 맥락이 전달되지 않는다(run.mts 의 launch-lead 분기). 런처는 prepare 까지
+# 거친 뒤 `launch-plan --entry-mode spawn-process` 로 lead 를 띄운다.
+CHILD_LEAD_BACKEND = "spawn-process"
+LAUNCHER_RELATIVE = Path("bin") / "okstra.sh"
 LAUNCH_STATUS_PREPARED = "prepared"
 
 
@@ -110,9 +115,14 @@ def _render_context(
         "",
         child.get("assignment") or "",
         "",
-        "## Manager Directives",
-        "",
     ]
+    if child.get("scope"):
+        # `task split` 이 만든 하위 태스크. 이 프로젝트에서 할 범위만 적는다.
+        lines.extend(["## Project Scope", "", f"- ticket: {child.get('ticketId') or ''}",
+                      f"- brief: {child.get('briefPath') or ''}", ""])
+        lines.extend(f"- in scope: {item}" for item in child["scope"])
+        lines.append("")
+    lines.extend(["## Manager Directives", ""])
     for row in directives:
         lines.append(f"- [{row.get('scope')}] {row.get('body')}")
     if not directives:
@@ -214,6 +224,28 @@ def build_launch_packet(
         ),
         encoding="utf-8",
     )
+    command = str(Path(home) / LAUNCHER_RELATIVE)
+    run_args = [
+        "--project-root",
+        project_root,
+        "--project-id",
+        project_id,
+        "--task-group",
+        str(child.get("taskGroup") or task_group),
+        "--task-id",
+        child_task_id_value,
+    ]
+    # `task split` 이 기록한 브리프·권장 phase 를 넘겨 런처가 첫 실행에서 다시 묻지 않게 한다.
+    # phase 는 하위 태스크가 아직 없을 때만 넘긴다. 이미 있으면 런처가 manifest 에서 다음
+    # phase 를 채워야 하는데, 두 값이 다 주어지면 그 채우기를 건너뛴다(autofill_from_manifest).
+    if child.get("recommendedPhase") and _resolve_task_root_read_only(Path(project_root), target_task_key) is None:
+        run_args.extend(["--task-type", str(child["recommendedPhase"])])
+    if child.get("briefPath"):
+        run_args.extend(["--task-brief", str(child["briefPath"])])
+    run_args += [
+        "--directive",
+        f"Read manager child context: {context_path}",
+    ]
     packet = {
         "managerId": manager_id,
         "taskGroup": task_group,
@@ -224,19 +256,9 @@ def build_launch_packet(
         "workerDispatchBackend": WORKER_DISPATCH_BACKEND,
         "projectRoot": project_root,
         "contextPath": str(context_path),
-        "runArgs": [
-            "run",
-            "--project-root",
-            project_root,
-            "--project-id",
-            project_id,
-            "--task-group",
-            str(child.get("taskGroup") or task_group),
-            "--task-id",
-            child_task_id_value,
-            "--directive",
-            f"Read manager child context: {context_path}",
-        ],
+        "command": command,
+        "runArgs": run_args,
+        "shellCommand": shlex.join([command, *run_args]),
         "createdAt": created_at,
     }
     _record_launch_prepared(

package/runtime/python/okstra_ctl/manager_paths.py

@@ -84,6 +84,10 @@ def snapshots_json_path(home: Path, manager_id: str, task_group: str, task_id: s
     return task_root(home, manager_id, task_group, task_id) / "snapshots.json"
 
 
+def split_plan_path(home: Path, manager_id: str, task_group: str, task_id: str) -> Path:
+    return task_root(home, manager_id, task_group, task_id) / "split-plan.json"
+
+
 def events_jsonl_path(home: Path, manager_id: str, task_group: str, task_id: str) -> Path:
     return task_root(home, manager_id, task_group, task_id) / "events.jsonl"
 
@@ -99,3 +103,7 @@ def child_context_path(
     safe_project = _slug_segment(project_id, "project-id")
     safe_task = _slug_segment(child_task_id, "task-id")
     return task_root(home, manager_id, task_group, task_id) / "child-context" / f"{safe_project}-{safe_task}.md"
+
+
+def view_html_path(home: Path, manager_id: str) -> Path:
+    return manager_root(home, manager_id) / "view" / "index.html"