okstra 0.96.1 → 0.97.0

package/src/cli-registry.mjs

@@ -3,35 +3,35 @@ const SUMMARY_COLUMN = 25;
 export const COMMAND_REGISTRY = [
   {
     name: "install",
-    module: "./install.mjs",
+    module: "./commands/lifecycle/install.mjs",
     export: "runInstall",
     category: "admin",
     summary: ["Install runtime; seed skills into existing agent homes"],
   },
   {
     name: "ensure-installed",
-    module: "./install.mjs",
+    module: "./commands/lifecycle/install.mjs",
     export: "runEnsureInstalled",
     category: "admin",
     summary: ["Verify install is fresh; reinstall if stale (idempotent)"],
   },
   {
     name: "uninstall",
-    module: "./uninstall.mjs",
+    module: "./commands/lifecycle/uninstall.mjs",
     export: "runUninstall",
     category: "admin",
     summary: ["Remove runtime + skills (user data preserved by default)"],
   },
   {
     name: "setup",
-    module: "./setup.mjs",
+    module: "./commands/lifecycle/setup.mjs",
     export: "run",
     category: "admin",
     summary: ["Register the current project (.okstra/project.json)"],
   },
   {
     name: "doctor",
-    module: "./doctor.mjs",
+    module: "./commands/lifecycle/doctor.mjs",
     export: "run",
     category: "admin",
     summary: [
@@ -40,42 +40,49 @@ export const COMMAND_REGISTRY = [
   },
   {
     name: "check-project",
-    module: "./check-project.mjs",
+    module: "./commands/lifecycle/check-project.mjs",
     export: "run",
     category: "admin",
     summary: ["Verify the current project has been registered with setup"],
   },
   {
     name: "config",
-    module: "./config.mjs",
+    module: "./commands/lifecycle/config.mjs",
     export: "run",
     category: "admin",
     summary: ["Read / write okstra settings (e.g. PR template path)"],
   },
   {
     name: "migrate",
-    module: "./migrate.mjs",
+    module: "./commands/lifecycle/migrate.mjs",
     export: "run",
     category: "admin",
     summary: ["Move legacy .project-docs/okstra/ to .okstra/ (one-shot)"],
   },
   {
     name: "git-reconcile",
-    module: "./git-reconcile.mjs",
+    module: "./commands/execute/git-reconcile.mjs",
     export: "run",
     category: "admin",
     summary: ["Reconcile stale stage SHAs after external git history changes"],
   },
   {
     name: "handoff",
-    module: "./handoff.mjs",
+    module: "./commands/execute/handoff.mjs",
     export: "run",
     category: "admin",
     summary: ["Stage-group release-handoff helpers (eligible/assemble/record)"],
   },
+  {
+    name: "integrate-stages",
+    module: "./commands/execute/integrate-stages.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["stage 들을 task 브랜치에 통합 머지하고 stage worktree 를 정리"],
+  },
   {
     name: "paths",
-    module: "./paths.mjs",
+    module: "./commands/lifecycle/paths.mjs",
     export: "run",
     category: "admin",
     summary: [
@@ -84,56 +91,63 @@ export const COMMAND_REGISTRY = [
   },
   {
     name: "task-list",
-    module: "./task-list.mjs",
+    module: "./commands/inspect/task-list.mjs",
     export: "run",
     category: "introspection",
     summary: ["List tasks registered in the current project"],
   },
   {
     name: "task-show",
-    module: "./task-show.mjs",
+    module: "./commands/inspect/task-show.mjs",
     export: "run",
     category: "introspection",
     summary: ["Summarize a task's manifest + workflow phase state"],
   },
   {
     name: "context-cost",
-    module: "./context-cost.mjs",
+    module: "./commands/inspect/context-cost.mjs",
     export: "run",
     category: "introspection",
     summary: ["Estimate file/read context cost for a task bundle"],
   },
   {
     name: "error-report",
-    module: "./error-report.mjs",
+    module: "./commands/inspect/error-report.mjs",
     export: "run",
     category: "introspection",
     summary: ["Aggregate okstra-run error logs into a task-level report"],
   },
+  {
+    name: "error-zip",
+    module: "./commands/inspect/error-zip.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Bundle cross-project okstra error logs into a zip"],
+  },
   {
     name: "recap",
-    module: "./recap.mjs",
+    module: "./commands/inspect/recap.mjs",
     export: "run",
     category: "introspection",
     summary: ["Assemble a task's run-to-run phase recap or append a recap log entry"],
   },
   {
     name: "worktree-lookup",
-    module: "./worktree-lookup.mjs",
+    module: "./commands/execute/worktree-lookup.mjs",
     export: "run",
     category: "introspection",
     summary: ["Look up registered worktree for a task-key"],
   },
   {
     name: "plan-validate",
-    module: "./plan-validate.mjs",
+    module: "./commands/execute/plan-validate.mjs",
     export: "run",
     category: "introspection",
     summary: ["Check an approved-plan file for the approval marker"],
   },
   {
     name: "render-bundle",
-    module: "./render-bundle.mjs",
+    module: "./commands/execute/render-bundle.mjs",
     export: "run",
     category: "introspection",
     summary: [
@@ -143,14 +157,14 @@ export const COMMAND_REGISTRY = [
   },
   {
     name: "run",
-    module: "./run.mjs",
+    module: "./commands/execute/run.mjs",
     export: "run",
     category: "introspection",
     summary: ["Host-aware auto execution front door"],
   },
   {
     name: "codex-run",
-    module: "./codex-run.mjs",
+    module: "./commands/execute/codex-run.mjs",
     export: "run",
     category: "introspection",
     summary: [
@@ -160,21 +174,21 @@ export const COMMAND_REGISTRY = [
   },
   {
     name: "codex-dispatch",
-    module: "./codex-dispatch.mjs",
+    module: "./commands/execute/codex-dispatch.mjs",
     export: "run",
     category: "introspection",
     summary: ["Dispatch CLI-backed workers for a prepared Codex run"],
   },
   {
     name: "team",
-    module: "./team.mjs",
+    module: "./commands/execute/team.mjs",
     export: "run",
     category: "introspection",
     summary: ["Dispatch and await tmux-pane workers for external leads"],
   },
   {
     name: "wizard",
-    module: "./wizard.mjs",
+    module: "./commands/execute/wizard.mjs",
     export: "run",
     category: "introspection",
     summary: [
@@ -184,7 +198,7 @@ export const COMMAND_REGISTRY = [
   },
   {
     name: "token-usage",
-    module: "./token-usage.mjs",
+    module: "./commands/execute/token-usage.mjs",
     export: "run",
     category: "introspection",
     summary: [
@@ -195,42 +209,42 @@ export const COMMAND_REGISTRY = [
   },
   {
     name: "render-views",
-    module: "./render-views.mjs",
+    module: "./commands/report/render-views.mjs",
     export: "run",
     category: "introspection",
     summary: ["Render slim AI + self-contained HTML views of a final report"],
   },
   {
     name: "render-final-report",
-    module: "./render-final-report.mjs",
+    module: "./commands/report/render-final-report.mjs",
     export: "run",
     category: "introspection",
     summary: ["Render the markdown sibling of a final-report data.json"],
   },
   {
     name: "inject-report-index",
-    module: "./inject-report-index.mjs",
+    module: "./commands/report/inject-report-index.mjs",
     export: "run",
     category: "introspection",
     summary: ["Add the top-of-report Index + scroll anchors to a report"],
   },
   {
     name: "spawn-followups",
-    module: "./spawn-followups.mjs",
+    module: "./commands/execute/spawn-followups.mjs",
     export: "run",
     category: "introspection",
     summary: ["Create follow-up task bundles from a final report"],
   },
   {
     name: "error-log",
-    module: "./error-log.mjs",
+    module: "./commands/execute/error-log.mjs",
     export: "run",
     category: "introspection",
     summary: ["Append run error events to the run error log"],
   },
   {
     name: "memory",
-    module: "./memory.mjs",
+    module: "./commands/memory/memory.mjs",
     export: "run",
     category: "introspection",
     summary: [

package/src/{codex-dispatch.mjs → commands/execute/codex-dispatch.mjs}

@@ -1,5 +1,5 @@
-import { runPythonModule } from "./_python-helper.mjs";
-import { resolvePaths } from "./paths.mjs";
+import { runPythonModule } from "../../lib/python-helper.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
 
 const USAGE = `okstra codex-dispatch — dispatch CLI-backed workers for a prepared Codex run
 
@@ -66,5 +66,5 @@ export async function run(args) {
     args: buildCodexDispatchArgs(args, paths),
     stdio: "inherit-stdout",
   });
-  return result.code ?? 0;
+  return result.code;
 }

package/src/{codex-run.mjs → commands/execute/codex-run.mjs}

@@ -1,5 +1,5 @@
-import { runPythonModule } from "./_python-helper.mjs";
-import { resolvePaths } from "./paths.mjs";
+import { runPythonModule } from "../../lib/python-helper.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
 
 const USAGE = `okstra codex-run — prepare a render-only Codex lead task bundle
 
@@ -64,5 +64,5 @@ export async function run(args) {
     args: buildCodexRunArgs(args, paths.workspace),
     stdio: "inherit-stdout",
   });
-  return result.code ?? 0;
+  return result.code;
 }

package/src/{error-log.mjs → commands/execute/error-log.mjs}

@@ -1,4 +1,4 @@
-import { runInstalledScript } from "./_python-helper.mjs";
+import { runInstalledScript } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra error-log — append okstra run error events to the run error log
 

package/src/{git-reconcile.mjs → commands/execute/git-reconcile.mjs}

@@ -1,4 +1,4 @@
-import { runPythonModule } from "./_python-helper.mjs";
+import { runPythonModule } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra git-reconcile — okstra 밖 git 히스토리 변경 후 기록 화해
 

package/src/{handoff.mjs → commands/execute/handoff.mjs}

@@ -1,4 +1,4 @@
-import { runPythonModule } from "./_python-helper.mjs";
+import { runPythonModule } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra handoff — release-handoff stage-group 보조 (자격/수집/기록)
 
@@ -13,6 +13,8 @@ Usage:
     --report-path <md> --data-json <json>
   okstra handoff record-pr --plan-run-root <dir> --stages 2,3 \\
     --branch <b> --url <u>
+  okstra handoff local-checkout --project-root <dir> --project-id <id> \\
+    --task-group <g> --task-id <t>
 
 Exit codes: 0 ok / 1 자격·전제 위반 / 2 stage 간 merge 충돌(conflicts 동봉)
 `;

package/src/commands/execute/integrate-stages.mjs

@@ -0,0 +1,25 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra integrate-stages — stage 들을 task 브랜치에 통합 머지 + worktree 정리
+
+A thin shim over \`python3 -m okstra_ctl.stage_integrate\`.
+
+Usage:
+  okstra integrate-stages --project-id <id> \\
+    --task-group <g> --task-id <t> --plan-run-root <dir> \\
+    --task-worktree-path <dir> [--stage-map-json '<json>']
+
+Exit codes: 0 ok / 2 stage 간 merge 충돌 / 1 python 프로세스 비정상 종료(폴백)
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const { code } = await runPythonModule({
+    module: "okstra_ctl.stage_integrate",
+    args,
+  });
+  return code ?? 1;
+}

package/src/{plan-validate.mjs → commands/execute/plan-validate.mjs}

@@ -1,4 +1,4 @@
-import { runPythonSnippet, emitJsonError } from "./_python-helper.mjs";
+import { runPythonSnippet, emitJsonError } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra plan-validate — verify an approved-plan file has a recognised approval marker
 

package/src/{render-bundle.mjs → commands/execute/render-bundle.mjs}

@@ -1,6 +1,6 @@
-import { runPythonModule } from "./_python-helper.mjs";
-import { resolvePaths } from "./paths.mjs";
-import { resolveRuntime } from "./runtime-resolver.mjs";
+import { runPythonModule } from "../../lib/python-helper.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
+import { resolveRuntime } from "../../lib/runtime-resolver.mjs";
 
 const USAGE = `okstra render-bundle — preview the task bundle without launching claude
 
@@ -107,5 +107,5 @@ export async function run(args) {
     args: finalArgs,
     stdio: "inherit-stdout",
   });
-  return result.code ?? 0;
+  return result.code;
 }

package/src/{run.mjs → commands/execute/run.mjs}

@@ -1,7 +1,7 @@
-import { runEnsureInstalled } from "./install.mjs";
-import { runPythonModule } from "./_python-helper.mjs";
-import { resolvePaths } from "./paths.mjs";
-import { resolveRuntime } from "./runtime-resolver.mjs";
+import { runEnsureInstalled } from "../lifecycle/install.mjs";
+import { runPythonModule } from "../../lib/python-helper.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
+import { resolveRuntime } from "../../lib/runtime-resolver.mjs";
 
 const USAGE = `okstra run — host-aware okstra execution front door
 

package/src/{spawn-followups.mjs → commands/execute/spawn-followups.mjs}

@@ -1,4 +1,4 @@
-import { runInstalledScript } from "./_python-helper.mjs";
+import { runInstalledScript } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra spawn-followups — create follow-up task bundles from a final report
 

package/src/{team.mjs → commands/execute/team.mjs}

@@ -1,5 +1,5 @@
-import { runPythonModule } from "./_python-helper.mjs";
-import { resolvePaths } from "./paths.mjs";
+import { runPythonModule } from "../../lib/python-helper.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
 
 const USAGE = `okstra team — dispatch and await tmux-pane workers for external leads
 
@@ -59,5 +59,5 @@ export async function run(args) {
     args: buildTeamArgs(args, paths),
     stdio: "inherit-stdout",
   });
-  return result.code ?? 0;
+  return result.code;
 }

package/src/{token-usage.mjs → commands/execute/token-usage.mjs}

@@ -1,4 +1,4 @@
-import { runInstalledScript } from "./_python-helper.mjs";
+import { runInstalledScript } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra token-usage — collect token usage for a run
 

package/src/{wizard.mjs → commands/execute/wizard.mjs}

@@ -2,8 +2,8 @@ import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { runPythonModule } from "./_python-helper.mjs";
-import { resolvePaths } from "./paths.mjs";
+import { runPythonModule } from "../../lib/python-helper.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
 
 const USAGE = `okstra wizard — interactive okstra-run input collector
 
@@ -31,19 +31,28 @@ All subcommands emit a single JSON object on stdout. On validation failure
 'step' returns {ok:false, error, current} so the skill can re-prompt.
 `;
 
-function parseFlags(args) {
+// Every wizard flag takes a value (there are no boolean flags), so the token
+// after a flag is always its value — even free-text answers that begin with
+// "--". A heuristic that rejects "--"-prefixed values would make legitimate
+// directive/base-ref answers unsubmittable. The inline "--key=value" form lets
+// callers pass any value (including empty) unambiguously.
+export function parseFlags(args) {
   const out = {};
   for (let i = 0; i < args.length; i += 1) {
     const a = args[i];
     if (!a.startsWith("--")) {
       throw new Error(`unexpected positional argument: ${a}`);
     }
+    const eq = a.indexOf("=");
+    if (eq !== -1) {
+      out[a.slice(2, eq)] = a.slice(eq + 1);
+      continue;
+    }
     const key = a.slice(2);
-    const next = args[i + 1];
-    if (next === undefined || next.startsWith("--")) {
+    if (i + 1 >= args.length) {
       throw new Error(`flag --${key} requires a value`);
     }
-    out[key] = next;
+    out[key] = args[i + 1];
     i += 1;
   }
   return out;

package/src/{worktree-lookup.mjs → commands/execute/worktree-lookup.mjs}

@@ -1,4 +1,4 @@
-import { runPythonSnippet, emitJsonError } from "./_python-helper.mjs";
+import { runPythonSnippet, emitJsonError } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra worktree-lookup — look up registered worktree for a task-key
 

package/src/{context-cost.mjs → commands/inspect/context-cost.mjs}

@@ -1,4 +1,4 @@
-import { runPythonModule } from "./_python-helper.mjs";
+import { runPythonModule } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra context-cost — estimate context/read cost for a task bundle
 
@@ -23,5 +23,5 @@ export async function run(args) {
     args,
     stdio: "inherit-stdout",
   });
-  return result.code ?? 0;
+  return result.code;
 }

package/src/{error-report.mjs → commands/inspect/error-report.mjs}

@@ -1,4 +1,4 @@
-import { runPythonModule } from "./_python-helper.mjs";
+import { runPythonModule } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra error-report — aggregate okstra-run error logs into a task report
 
@@ -23,5 +23,5 @@ export async function run(args) {
     args,
     stdio: "inherit-stdout",
   });
-  return result.code ?? 0;
+  return result.code;
 }

package/src/commands/inspect/error-zip.mjs

@@ -0,0 +1,25 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra error-zip — bundle cross-project okstra error logs into a zip
+
+Usage:
+  okstra error-zip --out <path>
+
+Walks the global run-index (~/.okstra/recent.jsonl + active.jsonl), collects
+every target project's runs/*/logs/errors-*.jsonl, anonymizes records, and
+writes a .zip (report.md + errors/anonymized.jsonl) to <path>. Read-only
+against every target's .okstra/. Prints a JSON summary to stdout.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const result = await runPythonModule({
+    module: "okstra_ctl.error_zip",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}

package/src/{recap.mjs → commands/inspect/recap.mjs}

@@ -1,4 +1,4 @@
-import { runPythonModule } from "./_python-helper.mjs";
+import { runPythonModule } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra recap — assemble a task's run-to-run phase recap, or append a recap log entry
 
@@ -23,5 +23,5 @@ export async function run(args) {
     args,
     stdio: "inherit-stdout",
   });
-  return result.code ?? 0;
+  return result.code;
 }

package/src/{task-list.mjs → commands/inspect/task-list.mjs}

@@ -1,4 +1,4 @@
-import { runPythonSnippet, emitJsonError } from "./_python-helper.mjs";
+import { runPythonSnippet, emitJsonError } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra task-list — list okstra tasks registered in this project
 

package/src/{task-show.mjs → commands/inspect/task-show.mjs}

@@ -1,4 +1,4 @@
-import { runPythonSnippet, emitJsonError } from "./_python-helper.mjs";
+import { runPythonSnippet, emitJsonError } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra task-show — summarize a task's manifest and workflow state
 

package/src/{check-project.mjs → commands/lifecycle/check-project.mjs}

@@ -1,7 +1,7 @@
 import { promises as fs } from "node:fs";
 import { join } from "node:path";
-import { buildPythonpath, resolvePaths } from "./paths.mjs";
-import { fileExists, runProcess } from "./_proc.mjs";
+import { buildPythonpath, resolvePaths } from "../../lib/paths.mjs";
+import { fileExists, runProcess } from "../../lib/proc.mjs";
 
 const USAGE = `okstra check-project — verify that the current project has okstra setup
 

package/src/{config.mjs → commands/lifecycle/config.mjs}

@@ -1,9 +1,9 @@
 import { promises as fs } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve, isAbsolute } from "node:path";
-import { buildPythonpath, resolvePaths } from "./paths.mjs";
-import { OKSTRA_DIR, projectJsonPath } from "./okstra-dirs.mjs";
-import { fileExists, runProcess } from "./_proc.mjs";
+import { buildPythonpath, resolvePaths } from "../../lib/paths.mjs";
+import { OKSTRA_DIR, projectJsonPath } from "../../lib/okstra-dirs.mjs";
+import { fileExists, runProcess } from "../../lib/proc.mjs";
 
 const USAGE = `okstra config — read / write okstra settings (project + global scopes)
 

package/src/{doctor.mjs → commands/lifecycle/doctor.mjs}

@@ -1,11 +1,11 @@
 import { promises as fs } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { resolvePaths } from "./paths.mjs";
-import { fileExists, runProcess } from "./_proc.mjs";
-import { runPythonSnippet } from "./_python-helper.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
+import { fileExists, runProcess } from "../../lib/proc.mjs";
+import { runPythonSnippet } from "../../lib/python-helper.mjs";
 import { runtimeIncludesClaudeAssets, validateInstallRuntime } from "./install.mjs";
-import { resolveRuntime } from "./runtime-resolver.mjs";
+import { resolveRuntime } from "../../lib/runtime-resolver.mjs";
 
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
 const REQUIRED_SKILLS = ["okstra-setup", "okstra-run"];

package/src/{install.mjs → commands/lifecycle/install.mjs}

@@ -2,12 +2,12 @@ import { promises as fs } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { join, relative, resolve as resolveAbs } from "node:path";
-import { getPackageRoot } from "./version.mjs";
-import { resolvePaths } from "./paths.mjs";
-import { fileExists } from "./_proc.mjs";
-import { buildRuntimeManifest, RUNTIMES_MANIFEST_REL } from "./runtime-manifest.mjs";
-import { normalizeRuntimeRequest, resolveRuntime } from "./runtime-resolver.mjs";
-import { OBSOLETE_INTERNAL_SKILL_NAMES, USER_SKILL_NAMES } from "./skill-catalog.mjs";
+import { getPackageRoot } from "../../lib/version.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
+import { fileExists } from "../../lib/proc.mjs";
+import { buildRuntimeManifest, RUNTIMES_MANIFEST_REL } from "../../lib/runtime-manifest.mjs";
+import { normalizeRuntimeRequest, resolveRuntime } from "../../lib/runtime-resolver.mjs";
+import { OBSOLETE_INTERNAL_SKILL_NAMES, USER_SKILL_NAMES } from "../../lib/skill-catalog.mjs";
 
 const SKILLS_MANIFEST_REL = "installed-skills.json";
 const AGENTS_MANIFEST_REL = "installed-agents.json";
@@ -284,16 +284,21 @@ async function ensureSymlink(target, linkPath, opts) {
     return "linked";
   }
   await fs.mkdir(join(linkPath, ".."), { recursive: true });
+  // readlink returns EINVAL for both a missing link and an existing non-symlink
+  // file, so unlink alone would silently destroy a real file. lstat lets us
+  // refuse to clobber any existing entry that is not a symlink.
+  let existing;
   try {
-    await fs.unlink(linkPath);
+    existing = await fs.lstat(linkPath);
   } catch (err) {
-    if (err.code !== "ENOENT") {
-      // Existing directory or regular file — refuse to clobber automatically.
-      throw new Error(
-        `refuse to replace ${linkPath} (not a symlink). Remove it manually and retry, or run 'okstra uninstall' first.`,
-      );
-    }
+    if (err.code !== "ENOENT") throw err;
+  }
+  if (existing && !existing.isSymbolicLink()) {
+    throw new Error(
+      `refuse to replace ${linkPath} (not a symlink). Remove it manually and retry, or run 'okstra uninstall' first.`,
+    );
   }
+  if (existing) await fs.unlink(linkPath);
   await fs.symlink(target, linkPath);
   return "linked";
 }

package/src/{migrate.mjs → commands/lifecycle/migrate.mjs}

@@ -1,4 +1,4 @@
-import { runPythonModule } from "./_python-helper.mjs";
+import { runPythonModule } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra migrate — move legacy .project-docs/okstra/ to .okstra/ (one-shot)