okstra 0.6.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.6.0",
+  "version": "0.6.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.6.0",
-  "builtAt": "2026-05-12T04:57:34.255Z",
+  "package": "0.6.1",
+  "builtAt": "2026-05-12T05:33:06.736Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/run.py

@@ -285,15 +285,27 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     project_root = Path(inp.project_root)
 
     # ---- validate inputs ----
+    # Hint suffix added to every "okstra runtime asset missing" PrepareError below.
+    # These files ship with the package and live under runtime/ — if any are
+    # missing the install is incomplete or stale, not a user-content issue.
+    _INSTALL_HINT = (
+        " This file ships with the okstra package; its absence usually means a stale "
+        "or partial install. Run 'okstra ensure-installed' (or 'okstra install' again) "
+        "to repair the runtime. If the problem persists, run 'okstra doctor' for a "
+        "fuller diagnostic."
+    )
     profile_dir = workspace_root / "prompts" / "profiles"
     profile_file = profile_dir / f"{inp.task_type}.md"
     if not profile_file.is_file():
         raise PrepareError(
-            f"analysis profile file not found for task-type {inp.task_type}: {profile_file}"
+            f"analysis profile file not found for task-type {inp.task_type}: "
+            f"{profile_file}.{_INSTALL_HINT}"
         )
     prompt_template = workspace_root / "prompts" / "launch.template.md"
     if not prompt_template.is_file():
-        raise PrepareError(f"okstra prompt template not found: {prompt_template}")
+        raise PrepareError(
+            f"okstra prompt template not found: {prompt_template}.{_INSTALL_HINT}"
+        )
     task_index_template = (
         workspace_root / "templates" / "project-docs" / "task-index.template.md"
     )
@@ -304,7 +316,9 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     run_validator = workspace_root / "validators" / "validate-run.py"
     for required in (task_index_template, final_report_template, run_validator, source_skill):
         if not required.is_file():
-            raise PrepareError(f"required okstra template or source skill missing: {required}")
+            raise PrepareError(
+                f"required okstra template or source skill missing: {required}.{_INSTALL_HINT}"
+            )
     if not project_root.is_dir():
         raise PrepareError(f"project root not found: {project_root}")
     if not inp.brief_path.is_file():
@@ -329,7 +343,11 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     try:
         upsert_project_json(project_root, inp.project_id)
     except ResolverError as exc:
-        raise PrepareError(f"project.json upsert failed: {exc}") from exc
+        # Surface the project_root in the prefix so the user can tell which
+        # registration failed when multiple projects are in play. The full
+        # underlying ResolverError text (which carries remediation guidance)
+        # is preserved by the `: {exc}` suffix and the `raise ... from exc`.
+        raise PrepareError(f"project.json upsert failed for {project_root}: {exc}") from exc
 
     # ---- workers resolution ----
     profile_workers_csv = ",".join(resolve_profile_workers(profile_file))

package/runtime/python/okstra_project/resolver.py

@@ -75,9 +75,12 @@ def resolve_project_root(*, explicit_root: str = "",
     if git_top is not None:
         return git_top.resolve()
     raise ResolverError(
-        "PROJECT_ROOT 를 해석할 수 없습니다. "
-        "--project-root 를 명시하거나, 프로젝트 루트(또는 그 하위)에서 실행하거나, "
-        "git 작업 트리 안에서 실행해 주십시오.")
+        "could not resolve PROJECT_ROOT from cwd. "
+        "Pass --project-root <abs-path>, "
+        "run from inside a project (a directory with .project-docs/okstra/project.json at or above cwd), "
+        "or run from inside a git working tree. "
+        "(PROJECT_ROOT 를 해석할 수 없습니다 — --project-root 를 명시하거나, "
+        "프로젝트 루트 또는 그 하위에서 실행하거나, git 작업 트리 안에서 실행해 주십시오.)")
 
 
 def upsert_project_json(project_root: Path, project_id: str, *,
@@ -100,13 +103,20 @@ def upsert_project_json(project_root: Path, project_id: str, *,
             data = json.loads(target.read_text())
         except (OSError, json.JSONDecodeError) as exc:
             raise ResolverError(
-                f"project.json 을 읽을 수 없습니다: {target} ({exc})") from exc
+                f"failed to read project.json at {target}: {exc} "
+                f"(project.json 을 읽을 수 없습니다.) "
+                f"If the file is corrupted, delete it and re-run 'okstra setup --project-id <id>'."
+            ) from exc
         existing_id = str(data.get("projectId") or "")
         if existing_id and existing_id != project_id:
             raise ResolverError(
-                f"projectId 불일치: project.json={existing_id!r}, "
-                f"인자={project_id!r}. "
-                f"동일 PROJECT_ROOT 에서는 하나의 projectId 만 사용할 수 있습니다.")
+                f"projectId mismatch: existing project.json has {existing_id!r} "
+                f"but the supplied argument is {project_id!r}. "
+                f"okstra allows only one projectId per PROJECT_ROOT. "
+                f"To fix: re-run with --project-id {existing_id!r} to keep the existing registration, "
+                f"or manually delete {target} if you intend to re-register this directory "
+                f"under a different id. "
+                f"(projectId 불일치: 한 PROJECT_ROOT 에는 하나의 projectId 만 허용됩니다.)")
         result = {
             "projectId": project_id,
             "projectRoot": abs_root,

package/src/check-project.mjs

@@ -103,10 +103,15 @@ export async function run(args) {
   );
 
   if (probe.code !== 0) {
+    const raw = probe.stderr.trim() || probe.stdout.trim();
     emit(opts, {
       ok: false,
       stage: "python",
-      reason: `python invocation failed: ${probe.stderr.trim() || probe.stdout.trim()}`,
+      reason:
+        `python invocation failed: ${raw}. ` +
+        "This usually means the okstra runtime is stale or missing — " +
+        "run 'okstra doctor' to diagnose, then 'okstra ensure-installed' " +
+        "to repair.",
     });
     return 1;
   }

package/src/setup.mjs

@@ -1,6 +1,8 @@
 import { promises as fs } from "node:fs";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { resolve as resolvePath } from "node:path";
 import { resolvePaths } from "./paths.mjs";
 
 const USAGE = `okstra setup — register the current project with okstra
@@ -192,8 +194,51 @@ export async function run(args) {
   try {
     resolved = await resolveProjectRoot(paths, opts.projectRoot);
   } catch (err) {
+    if (err.code === "RESOLVER") {
+      const cwd = resolvePath(process.cwd());
+      const home = resolvePath(homedir());
+      const inHome = cwd === home;
+      process.stderr.write(
+        "error: 'okstra setup' registers the CURRENT directory as an okstra project,\n" +
+          "       but no project root could be resolved from here.\n" +
+          `       cwd: ${cwd}\n` +
+          (inHome
+            ? "       (this looks like your home directory — setup is project-level, not machine-level;\n" +
+              "        machine-level install is 'okstra install', which you've likely already done.)\n"
+            : "") +
+          "\nFix one of:\n" +
+          "  1. cd into the project you want to register, then re-run:\n" +
+          "       cd <your project> && okstra setup --project-id <id>\n" +
+          "  2. pass an explicit path:\n" +
+          "       okstra setup --project-root <abs-path> --project-id <id>\n" +
+          "  3. run from inside any git working tree (the toplevel becomes PROJECT_ROOT).\n" +
+          `\n(underlying error: ${err.message})\n`,
+      );
+      return 2;
+    }
+    // Non-RESOLVER path: typically python invocation failure (PYTHONPATH wrong,
+    // ~/.okstra missing, python3 not on PATH, okstra_project module missing).
+    // The user can't fix this by adjusting setup arguments — it's a runtime
+    // health issue, not a PROJECT_ROOT issue. Reword accordingly.
+    const looksLikePythonFailure = /python invocation failed|ModuleNotFoundError|No module named/.test(
+      err.message,
+    );
+    if (looksLikePythonFailure) {
+      process.stderr.write(
+        "error: 'okstra setup' could not start because the okstra runtime is not\n" +
+          "       reachable from this process. This is almost always a stale or\n" +
+          "       incomplete install, not a problem with your setup arguments.\n" +
+          "\nFix:\n" +
+          "  1. run 'okstra doctor' to see exactly what is missing\n" +
+          "  2. run 'okstra ensure-installed' (or 'npx -y okstra@latest install')\n" +
+          "     to repair the runtime\n" +
+          "  3. retry: okstra setup --project-id <id>\n" +
+          `\n(underlying error: ${err.message})\n`,
+      );
+      return 1;
+    }
     process.stderr.write(`error: could not resolve PROJECT_ROOT: ${err.message}\n`);
-    return err.code === "RESOLVER" ? 2 : 1;
+    return 1;
   }
   const { projectRoot, projectJsonPath } = resolved;