okstra 0.201.2 → 0.202.0

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -44,6 +44,7 @@ class MutationSnapshot:
     # 스냅샷이 아직 실행 중인 디스패치에 남아 있고, 그것을 못 읽으면 그 워커가
     # 통째로 error 가 된다. 두 루트가 같으면 None.
     artifact_git_head: str | None = None
+    artifact_observation_roots: tuple[str, ...] = ()
 
     def to_payload(self) -> dict[str, Any]:
         return {
@@ -57,6 +58,7 @@ class MutationSnapshot:
             "digest": self.digest,
             "orchestratorPaths": list(self.orchestrator_paths),
             "artifactGitHead": self.artifact_git_head,
+            "artifactObservationRoots": list(self.artifact_observation_roots),
         }
 
     @classmethod
@@ -75,6 +77,7 @@ class MutationSnapshot:
                 str(payload["artifactGitHead"])
                 if payload.get("artifactGitHead") else None
             ),
+            artifact_observation_roots=tuple(payload.get("artifactObservationRoots", ())),
         )
         expected = _snapshot_digest(
             snapshot.root,
@@ -85,6 +88,7 @@ class MutationSnapshot:
             snapshot.scratch_digests,
             snapshot.git_projection,
             snapshot.orchestrator_paths,
+            snapshot.artifact_observation_roots,
         )
         if snapshot.digest != expected:
             raise MutationAuditError("mutation snapshot digest does not match payload")
@@ -115,6 +119,10 @@ class MutationAuditResult:
     # 에러 원장(contract-violation)이 따로 잡는다.
     untracked_artifact_paths: tuple[str, ...] = ()
     warnings: tuple[str, ...] = ()
+    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 {
@@ -128,6 +136,10 @@ class MutationAuditResult:
             "retryAllowed": self.retry_allowed,
             "violations": list(self.violations),
             "warnings": list(self.warnings),
+            "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,
         }
@@ -147,12 +159,14 @@ class ExecutionMutationAudit:
         generated = _generated_paths(rows)
         file_digests = source_content_snapshot(root, generated)
         artifact_digests = (
-            file_digests
+            dict(file_digests)
             if artifact_root == root
             else _content_snapshot(
                 artifact_root, generated | _non_source_paths(artifact_root)
             )
         )
+        observation_roots = _artifact_observation_roots(rows)
+        artifact_digests.update(_observed_artifact_contents(artifact_root, observation_roots))
         scratch_digests = _scratch_snapshot(rows)
         git_projection = _git_projection(root)
         orchestrator = tuple(
@@ -168,6 +182,7 @@ class ExecutionMutationAudit:
             scratch_digests,
             git_projection,
             orchestrator,
+            observation_roots,
         )
         return MutationSnapshot(
             root=root,
@@ -182,6 +197,7 @@ class ExecutionMutationAudit:
             artifact_git_head=(
                 None if artifact_root == root else _git_head(artifact_root)
             ),
+            artifact_observation_roots=observation_roots,
         )
 
     def compare(
@@ -203,6 +219,13 @@ class ExecutionMutationAudit:
         artifact_changed = _changed_keys(
             before.artifact_digests, after.artifact_digests
         )
+        unobserved = {
+            path for path in artifact_changed
+            if path not in before.artifact_digests
+            and any(_is_within(path, root) for root in after.artifact_observation_roots)
+            and not any(_is_within(path, root) for root in before.artifact_observation_roots)
+        }
+        artifact_changed -= unobserved
         scratch_changed = _changed_keys(
             before.scratch_digests, after.scratch_digests
         )
@@ -218,22 +241,27 @@ class ExecutionMutationAudit:
             after,
             rows,
             source_changes,
-            out_of_plan_edits,
         )
-        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 and path not in external
+            and not any(_is_relative_to(before.artifact_root / path, Path(item))
+                        for item in before.orchestrator_paths)
+        }
         status = _terminal_status(
             rows,
-            source_changed=bool(source_changes),
+            source_changed=bool(source_changes or worker_artifact_changes),
             git_changed=git_changed,
             attempt_succeeded=attempt_succeeded,
             result_present=result_present,
             violations=violations,
         )
         retry_allowed = _retry_allowed(
-            status, bool(source_changes), git_changed, bool(scratch_changed)
+            status, bool(source_changes or worker_artifact_changes), git_changed, bool(scratch_changed)
         )
         return MutationAuditResult(
             status=status,
@@ -249,10 +277,87 @@ class ExecutionMutationAudit:
             git_projection=after.git_projection,
             untracked_artifact_paths=tuple(sorted(untracked_artifact_changes)),
             warnings=_audit_warnings(untracked_artifact_changes)
-            + _branch_switch_warnings(before, after, switched),
+            + _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 - external)),
+            declared_out_of_plan_paths=tuple(out_of_plan_edits),
+            unobserved_artifact_paths=tuple(sorted(unobserved)),
+            external_workspace_changes=tuple(sorted(external)),
         )
 
 
+def _observed_artifact_contents(root: Path, observation_roots: Sequence[str]) -> dict[str, str]:
+    """관측 경계의 링크 자체를 기록하고 링크 목적지는 탐색하지 않는다."""
+    artifact_digests: dict[str, str] = {}
+    for relative in observation_roots:
+        target = root / relative
+        link = next((parent for parent in (*target.parents, target)
+                     if parent != root and _is_relative_to(parent, root)
+                     and parent.is_symlink()), None)
+        if link is not None:
+            artifact_digests[link.relative_to(root).as_posix()] = _path_digest(link)
+            continue
+        if target.is_symlink() or target.is_file():
+            artifact_digests[relative] = _path_digest(target)
+        else:
+            artifact_digests.update({
+                f"{relative}/{key}": value
+                for key, value in _content_snapshot(target, frozenset()).items()
+            })
+    return artifact_digests
+
+
+def _artifact_observation_roots(policies: Sequence[WritePolicy]) -> tuple[str, ...]:
+    """현재 배정의 QA와 실행 산출물은 Git 무시 규칙과 무관하게 관측한다."""
+    roots: set[str] = set()
+    for path in _allowed_artifact_paths(policies):
+        parts = Path(path).parts
+        if len(parts) < 5 or parts[:2] != (".okstra", "tasks"):
+            continue
+        if parts[4] == "qa":
+            roots.add(Path(*parts[:5]).as_posix())
+        elif parts[4] == "runs":
+            boundary = next((i for i, part in enumerate(parts)
+                             if part in {"worker-results", "prompts"}), len(parts) - 1)
+            roots.add(Path(*parts[:boundary]).as_posix())
+        else:
+            roots.add(path)
+    return tuple(sorted(roots))
+
+
+def _plan_change_warnings(
+    policies: Sequence[WritePolicy], source_changes: set[str],
+    artifact_changes: set[str], declared: Sequence[str], unobserved: set[str],
+) -> tuple[str, ...]:
+    """예상 목록과의 차이는 검토 자료이며 쓰기 권한 위반이 아니다."""
+    warnings: list[str] = []
+    for policy in policies:
+        if policy.source_mode != "project-mutation":
+            continue
+        planned = policy.source_policy.get("plannedPaths", ())
+        extra = sorted(path for path in source_changes
+                       if not any(_is_within(path, item) for item in planned))
+        if extra:
+            warnings.append("source changes outside expected plan; review scope: " + ", ".join(extra))
+    observed = {Path(str(policy.source_policy["allowedRoot"])) / path
+                for policy in policies for path in source_changes}
+    observed.update(Path(str(policy.artifact_policy["allowedRoot"])) / path
+                    for policy in policies for path in artifact_changes)
+    roots = {Path(str(policy.source_policy["allowedRoot"])) for policy in policies}
+    roots.update(Path(str(policy.artifact_policy["allowedRoot"])) for policy in policies)
+    missing = sorted(path for path in declared
+                     if not any(root / path in observed for root in roots))
+    if missing:
+        warnings.append("declared changes not observed; reconcile evidence: " + ", ".join(missing))
+    if unobserved:
+        warnings.append(f"artifact baseline coverage unavailable ({len(unobserved)} paths); "
+                        "independently verify current artifacts; see unobservedArtifactPaths")
+    return tuple(warnings)
+
+
 def _audit_warnings(untracked_artifact_changes: set[str]) -> tuple[str, ...]:
     if not untracked_artifact_changes:
         return ()
@@ -595,6 +700,7 @@ def _snapshot_digest(
     scratch: Mapping[str, str],
     git_projection: Mapping[str, Any],
     orchestrator_paths: Sequence[str],
+    observation_roots: Sequence[str] = (),
 ) -> str:
     encoded = json.dumps(
         {
@@ -606,6 +712,7 @@ def _snapshot_digest(
             "scratch": scratch,
             "gitProjection": git_projection,
             "orchestratorPaths": list(orchestrator_paths),
+            **({"artifactObservationRoots": list(observation_roots)} if observation_roots else {}),
         },
         sort_keys=True,
         separators=(",", ":"),
@@ -651,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 = {
@@ -680,7 +777,7 @@ def _artifact_policy_failures(
         and not any(_is_within(path, item) for item in orchestrator)
     }
     if snapshot.artifact_root == snapshot.root:
-        return [], set(), set()
+        unauthorized = {path for path in unauthorized if _is_within(path, _OKSTRA_ARTIFACT_SUBTREE)}
     tracked = _tracked_paths(snapshot.artifact_root)
     if tracked is None:
         untracked_outside: set[str] = set()
@@ -697,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(
@@ -761,7 +863,6 @@ def _policy_violations(
     after: MutationSnapshot,
     policies: tuple[WritePolicy, ...],
     source_changes: set[str],
-    out_of_plan_edits: Sequence[str],
 ) -> list[str]:
     if all(policy.source_mode == "source-readonly" for policy in policies):
         failures = ["readonly source changed"] if source_changes else []
@@ -769,8 +870,8 @@ def _policy_violations(
             failures.append("gitPolicy disabled but Git projection changed")
         return failures
     policy = next(row for row in policies if row.source_mode == "project-mutation")
-    failures = _source_policy_failures(policy, source_changes, out_of_plan_edits)
-    failures.extend(_git_policy_failures(before, after, policy, source_changes, out_of_plan_edits))
+    failures = _source_policy_failures(policy, source_changes)
+    failures.extend(_git_policy_failures(before, after, policy))
     return failures
 
 
@@ -797,37 +898,14 @@ def _stable_git_projection(snapshot: MutationSnapshot) -> dict[str, Any]:
     }
 
 
-def _path_ledger_is_unenforceable(policy: WritePolicy) -> bool:
-    """옛 계획의 미선언 목록만 면제하고, 산출물 전용 계획의 빈 소스 목록은 집행한다.
-
-    선언 여부가 저장되기 전 정책은 기존의 빈 목록 해석을 유지한다.
-    새 정책은 경로 분류 후에도 선언 여부를 보존하므로 산출물만 남은 계획이
-    임의의 소스 변경이나 커밋을 허용하지 않는다.
-    """
-    source = policy.source_policy
-    return (
-        source.get("mode") == "project-mutation"
-        and not source.get("plannedPaths")
-        and not source.get("plannedPathsDeclared", False)
-    )
-
-
 def _source_policy_failures(
     policy: WritePolicy,
     changed: set[str],
-    out_of_plan_edits: Sequence[str],
 ) -> list[str]:
-    planned = set(policy.source_policy.get("plannedPaths", ()))
-    declared = set(out_of_plan_edits)
     protected = set(policy.source_policy.get("protectedPaths", ()))
     failures: list[str] = []
-    if (
-        not _path_ledger_is_unenforceable(policy)
-        and not changed <= planned | declared
-    ):
-        failures.append("source changes exceed planned and declared out-of-plan paths")
-    if not declared <= changed:
-        failures.append("declared out-of-plan path did not change")
+    if policy.source_mode == "source-readonly" and changed:
+        failures.append("readonly source changed")
     if any(_is_within(path, item) for path in changed for item in protected):
         failures.append("protected path changed")
     return failures
@@ -837,8 +915,6 @@ def _git_policy_failures(
     before: MutationSnapshot,
     after: MutationSnapshot,
     policy: WritePolicy,
-    changed: set[str],
-    out_of_plan_edits: Sequence[str],
 ) -> list[str]:
     git = policy.git_policy
     root = before.root
@@ -857,23 +933,16 @@ def _git_policy_failures(
         failures.append("final Git index contains staged changes")
     if not _is_ancestor(root, str(git.get("expectedBaseCommit")), str(after.git_projection.get("head"))):
         failures.append("final HEAD is not a fast-forward descendant")
-    allowed = set(policy.source_policy.get("plannedPaths", ())) | set(out_of_plan_edits)
-    if _path_ledger_is_unenforceable(policy):
-        # The plan predates the declared path column, so there is no ledger
-        # anyone can be held to. Every other check above still applies; only
-        # the path comparison stands down.
-        return failures
+    protected = policy.source_policy.get("protectedPaths", ())
     if any(
-        not paths <= allowed
+        any(_is_within(path, item) for path in paths for item in protected)
         for paths in _commit_paths_by_commit(
             root,
             str(git.get("expectedBaseCommit")),
             str(after.git_projection.get("head")),
         )
     ):
-        failures.append("commit chain changed paths outside source policy")
-    if not changed <= allowed:
-        failures.append("working tree changed paths outside source policy")
+        failures.append("commit chain changed protected paths")
     return failures
 
 

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(