@duypham93/openkit 0.2.8 → 0.2.9

package/.opencode/install-manifest.json

@@ -3,7 +3,7 @@
   "manifestVersion": 1,
   "kit": {
     "name": "OpenKit AI Software Factory",
-    "version": "0.1.0"
+    "version": "0.2.9"
   },
   "registry": {
     "path": "registry.json",

package/.opencode/tests/session-start-hook.test.js

@@ -58,7 +58,7 @@ function makeQuickState(overrides = {}) {
   }
 }
 
-function writeManifest(projectRoot) {
+function writeManifest(projectRoot, version = "0.2.9") {
   const opencodeDir = path.join(projectRoot, ".opencode")
   fs.mkdirSync(opencodeDir, { recursive: true })
   fs.writeFileSync(
@@ -66,7 +66,7 @@ function writeManifest(projectRoot) {
     `${JSON.stringify({
       kit: {
         name: "OpenKit AI Software Factory",
-        version: "0.1.0",
+        version,
         entryAgent: "MasterOrchestrator",
       },
     }, null, 2)}\n`,
@@ -130,14 +130,6 @@ function writeMetaSkill(projectRoot) {
   fs.writeFileSync(path.join(skillDir, "SKILL.md"), "# using-skills\n", "utf8")
 }
 
-function writeFailingPythonShim(projectRoot) {
-  const binDir = path.join(projectRoot, "bin")
-  const shimPath = path.join(binDir, "python3-shim")
-  fs.mkdirSync(binDir, { recursive: true })
-  fs.writeFileSync(shimPath, "#!/usr/bin/env bash\nexit 1\n", { encoding: "utf8", mode: 0o755 })
-  return shimPath
-}
-
 test("session-start emits mode-aware resume hint for quick tasks", () => {
   const projectRoot = makeTempProject()
 
@@ -157,7 +149,7 @@ test("session-start emits mode-aware resume hint for quick tasks", () => {
 
   assert.equal(result.status, 0)
   assert.match(result.stdout, /<openkit_runtime_status>/)
-  assert.match(result.stdout, /kit: OpenKit AI Software Factory v0\.1\.0/)
+  assert.match(result.stdout, /kit: OpenKit AI Software Factory v0\.2\.9/)
   assert.match(result.stdout, /startup skill: skipped/)
   assert.match(result.stdout, /node \.opencode\/workflow-state\.js status/)
   assert.match(result.stdout, /node \.opencode\/workflow-state\.js doctor/)
@@ -265,9 +257,10 @@ test("session-start prints canonical resume guidance and inspection commands", (
 test("session-start degrades gracefully when the JSON helper fails", () => {
   const projectRoot = makeTempProject()
 
+  const manifestPath = path.join(projectRoot, ".opencode", "opencode.json")
   writeManifest(projectRoot)
   writeState(projectRoot, makeQuickState())
-  const pythonShim = writeFailingPythonShim(projectRoot)
+  fs.writeFileSync(manifestPath, '{"kit":', 'utf8')
 
   const result = spawnSync(path.resolve(__dirname, "../../hooks/session-start"), {
     cwd: projectRoot,
@@ -277,7 +270,6 @@ test("session-start degrades gracefully when the JSON helper fails", () => {
       OPENKIT_PROJECT_ROOT: projectRoot,
       OPENKIT_SESSION_START_NO_SKILL: "1",
       OPENKIT_WORKFLOW_STATE: path.join(projectRoot, ".opencode", "workflow-state.json"),
-      OPENKIT_PYTHON_BIN: pythonShim,
     },
   })
 

package/.opencode/tests/workflow-behavior.test.js

@@ -38,7 +38,7 @@ function writeManifest(projectRoot) {
     `${JSON.stringify({
       kit: {
         name: "OpenKit AI Software Factory",
-        version: "0.1.0",
+        version: "0.2.9",
         entryAgent: "MasterOrchestrator",
       },
     }, null, 2)}\n`,

package/.opencode/tests/workflow-contract-consistency.test.js

@@ -39,7 +39,7 @@ function setupTempRuntime(projectRoot) {
     `${JSON.stringify({
       kit: {
         name: "OpenKit AI Software Factory",
-        version: "0.1.0",
+        version: "0.2.9",
         entryAgent: "MasterOrchestrator",
         registry: {
           path: "registry.json",

package/.opencode/tests/workflow-state-cli.test.js

@@ -30,7 +30,7 @@ function setupTempRuntime(projectRoot) {
     `${JSON.stringify({
       kit: {
         name: "OpenKit AI Software Factory",
-        version: "0.1.0",
+        version: "0.2.9",
         entryAgent: "MasterOrchestrator",
         registry: {
           path: "registry.json",
@@ -239,7 +239,7 @@ test("status command prints workflow and runtime summary", () => {
 
   assert.equal(result.status, 0)
   assert.match(result.stdout, /OpenKit runtime status:/)
-  assert.match(result.stdout, /kit: OpenKit AI Software Factory v0\.1\.0/)
+  assert.match(result.stdout, /kit: OpenKit AI Software Factory v0\.2\.9/)
   assert.match(result.stdout, /entry agent: MasterOrchestrator/)
   assert.match(result.stdout, /active profile: openkit-core/)
   assert.match(result.stdout, /registry: .*registry\.json/)
@@ -577,7 +577,7 @@ test("version command prints kit metadata version", () => {
   })
 
   assert.equal(result.status, 0)
-  assert.match(result.stdout, /OpenKit version: 0\.1\.0/)
+  assert.match(result.stdout, /OpenKit version: 0\.2\.9/)
   assert.match(result.stdout, /active profile: openkit-core/)
 })
 

package/assets/openkit-install.json.template

@@ -3,7 +3,7 @@
   "stateVersion": 1,
   "kit": {
     "name": "OpenKit",
-    "version": "0.1.0"
+    "version": "0.2.8"
   },
   "installation": {
     "profile": "openkit-core",

package/docs/maintainer/README.md

@@ -40,7 +40,7 @@ Use it to find canonical repository docs and upkeep surfaces quickly. Do not tre
 
 - The preferred end-user onboarding path is `npm install -g @duypham93/openkit` followed by `openkit run`.
 - The first `openkit run` materializes the managed kit into the OpenCode home directory automatically.
-- `openkit doctor` is the read-only check for the global install and workspace bootstrap state.
+- `openkit doctor` is a non-mutating check for the global install and current workspace readiness state.
 - `openkit install-global`, `openkit install`, and `openkit init` remain available as manual or compatibility commands.
 - The package intentionally avoids npm `postinstall` side effects; setup happens inside the OpenKit CLI where failures and recovery steps are easier to explain.
 

package/docs/operations/runbooks/openkit-daily-usage.md

@@ -80,7 +80,7 @@ If the boundary still feels fuzzy, use the `Lane Decision Matrix` in `context/co
 
 ### 1. Check global install and workspace health
 
-Start with read-only checks:
+Start with non-mutating checks:
 
 ```bash
 openkit doctor
@@ -88,7 +88,7 @@ openkit doctor
 
 What to look for:
 
-- `doctor` confirms the global kit is installed, the workspace root is available, and the current project can launch with OpenKit cleanly
+- `doctor` confirms the global kit is installed, shows the derived workspace root, and reports whether the current project can launch with OpenKit cleanly without mutating local workspace files
 
 If `doctor` reports `install-missing`, run `openkit run` for first-time setup. If `doctor` reports other errors, fix those before trusting resume or task-board behavior.
 

package/hooks/session-start

@@ -1,162 +1,8 @@
 #!/usr/bin/env bash
 
-# This script runs when an AI session starts.
-# It teaches the agent how to use the Skills library by injecting the meta-skill.
-
-set -e
+set -euo pipefail
 
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-KIT_ROOT="${OPENKIT_KIT_ROOT:-$(dirname "$DIR")}"
-PROJECT_ROOT="${OPENKIT_PROJECT_ROOT:-$(pwd)}"
-META_SKILL_PATH="$KIT_ROOT/skills/using-skills/SKILL.md"
-STATE_PATH="${OPENKIT_WORKFLOW_STATE:-$PROJECT_ROOT/.opencode/workflow-state.json}"
-MANIFEST_PATH="$KIT_ROOT/.opencode/opencode.json"
-PYTHON_BIN="${OPENKIT_PYTHON_BIN:-python3}"
-RUNTIME_SUMMARY_MODULE="$KIT_ROOT/.opencode/lib/runtime-summary.js"
-
-KIT_NAME="OpenKit AI Software Factory"
-KIT_VERSION="unknown"
-ENTRY_AGENT="unknown"
-JSON_HELPER_STATUS="ok"
-
-if [ -f "$MANIFEST_PATH" ] && command -v "$PYTHON_BIN" >/dev/null 2>&1; then
-    KIT_INFO_RAW=$("$PYTHON_BIN" - "$MANIFEST_PATH" <<'PY' || true
-import json
-import sys
-
-manifest_path = sys.argv[1]
-
-try:
-    with open(manifest_path, "r", encoding="utf-8") as fh:
-        manifest = json.load(fh)
-except Exception:
-    sys.exit(0)
-
-kit = manifest.get("kit") or {}
-print(kit.get("name", "OpenKit AI Software Factory"))
-print(kit.get("version", "unknown"))
-print(kit.get("entryAgent", "unknown"))
-PY
-)
-    KIT_INFO_1=$(printf '%s\n' "$KIT_INFO_RAW" | sed -n '1p')
-    KIT_INFO_2=$(printf '%s\n' "$KIT_INFO_RAW" | sed -n '2p')
-    KIT_INFO_3=$(printf '%s\n' "$KIT_INFO_RAW" | sed -n '3p')
-    if [ -n "$KIT_INFO_1" ] && [ -n "$KIT_INFO_2" ] && [ -n "$KIT_INFO_3" ]; then
-        KIT_NAME="$KIT_INFO_1"
-        KIT_VERSION="$KIT_INFO_2"
-        ENTRY_AGENT="$KIT_INFO_3"
-    else
-        JSON_HELPER_STATUS="degraded"
-    fi
-elif [ -f "$MANIFEST_PATH" ]; then
-    JSON_HELPER_STATUS="degraded"
-fi
-
-if [ -n "${OPENKIT_SESSION_START_NO_SKILL:-}" ]; then
-    SKILL_STATUS="skipped"
-elif [ -f "$META_SKILL_PATH" ]; then
-    SKILL_STATUS="loaded"
-else
-    SKILL_STATUS="missing"
-fi
-
-echo "<openkit_runtime_status>"
-echo "kit: $KIT_NAME v$KIT_VERSION"
-echo "entry agent: $ENTRY_AGENT"
-echo "state file: $STATE_PATH"
-echo "startup skill: $SKILL_STATUS"
-echo "json helper: $JSON_HELPER_STATUS"
-echo "help: node .opencode/workflow-state.js status"
-echo "doctor: node .opencode/workflow-state.js doctor"
-echo "show: node .opencode/workflow-state.js show"
-echo "</openkit_runtime_status>"
-
-if [ -z "${OPENKIT_SESSION_START_NO_SKILL:-}" ] && [ -f "$META_SKILL_PATH" ]; then
-    echo "<skill_system_instruction>"
-    echo "You are running within the Open Kit AI Software Factory framework."
-    echo "Below are the rules for how you must discover and invoke your skills."
-    echo ""
-    cat "$META_SKILL_PATH"
-    echo "</skill_system_instruction>"
-fi
-
-if [ -f "$STATE_PATH" ] && [ "$JSON_HELPER_STATUS" = "ok" ] && command -v "$PYTHON_BIN" >/dev/null 2>&1; then
-    "$PYTHON_BIN" - "$STATE_PATH" "$RUNTIME_SUMMARY_MODULE" <<'PY' || true
-import json
-import os
-import pathlib
-import subprocess
-import sys
-
-state_path = sys.argv[1]
-runtime_summary_module = sys.argv[2]
-runtime_root = str(pathlib.Path(state_path).resolve().parents[1])
-
-try:
-    with open(state_path, "r", encoding="utf-8") as fh:
-        state = json.load(fh)
-except Exception:
-    sys.exit(0)
-
-mode = state.get("mode")
-stage = state.get("current_stage")
-status = state.get("status")
-owner = state.get("current_owner")
-feature_id = state.get("feature_id")
-feature_slug = state.get("feature_slug")
-work_item_id = state.get("work_item_id")
-
-if not all([mode, stage, status, owner]):
-    sys.exit(0)
-
-task_summary = None
-active_tasks = []
-
-if mode == "full" and work_item_id:
-    try:
-        node_cmd = [
-            "node",
-            "-e",
-            (
-                "const { getRuntimeContext } = require(process.argv[1]);"
-                "const context = getRuntimeContext(process.argv[2], JSON.parse(process.argv[3]));"
-                "process.stdout.write(JSON.stringify(context));"
-            ),
-            runtime_summary_module,
-            runtime_root,
-            json.dumps(state),
-        ]
-        result = subprocess.run(node_cmd, check=True, capture_output=True, text=True)
-        runtime_context = json.loads(result.stdout.strip() or "{}")
-        board_summary = runtime_context.get("taskBoardSummary")
-        if board_summary:
-            task_summary = (
-                f"task board: {board_summary.get('total', 0)} tasks | "
-                f"ready {board_summary.get('ready', 0)} | active {board_summary.get('active', 0)}"
-            )
-            active_tasks = board_summary.get("activeTasks") or []
-    except Exception:
-        task_summary = None
-        active_tasks = []
+NODE_BIN="${OPENKIT_NODE_BIN:-node}"
 
-print("<workflow_resume_hint>")
-print("OpenKit workflow resume context detected.")
-print(f"mode: {mode}")
-print(f"stage: {stage}")
-print(f"status: {status}")
-print(f"owner: {owner}")
-if feature_id and feature_slug:
-    print(f"work item: {feature_id} ({feature_slug})")
-if work_item_id:
-    print(f"active work item id: {work_item_id}")
-if task_summary:
-    print(task_summary)
-if active_tasks:
-    print(f"active tasks: {'; '.join(active_tasks)}")
-print("Read first: AGENTS.md -> context/navigation.md -> context/core/workflow.md -> .opencode/workflow-state.json")
-print("Then load resume guidance from context/core/session-resume.md.")
-if mode == "full" and active_tasks:
-    print("Parallel task support is not yet assumed safe by this hook; confirm with `node .opencode/workflow-state.js doctor` before relying on it.")
-print("</workflow_resume_hint>")
-PY
-fi
+exec "$NODE_BIN" "$DIR/session-start.js" "$@"

package/hooks/session-start.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_KIT_ROOT = path.resolve(SCRIPT_DIR, '..');
+
+function resolveKitRoot(projectRoot, statePath) {
+  if (process.env.OPENKIT_KIT_ROOT) {
+    return path.resolve(process.env.OPENKIT_KIT_ROOT);
+  }
+
+  const candidates = [
+    projectRoot,
+    path.dirname(path.resolve(statePath)),
+    DEFAULT_KIT_ROOT,
+  ];
+
+  for (const candidate of candidates) {
+    const manifestPath = path.join(candidate, '.opencode', 'opencode.json');
+    if (fs.existsSync(manifestPath)) {
+      return candidate;
+    }
+  }
+
+  return DEFAULT_KIT_ROOT;
+}
+
+function print(line = '') {
+  process.stdout.write(`${line}\n`);
+}
+
+function readJsonIfPresent(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { exists: false, value: null, malformed: false };
+  }
+
+  try {
+    return {
+      exists: true,
+      value: JSON.parse(fs.readFileSync(filePath, 'utf8')),
+      malformed: false,
+    };
+  } catch {
+    return {
+      exists: true,
+      value: null,
+      malformed: true,
+    };
+  }
+}
+
+function resolveRuntimeContext(runtimeSummaryModulePath, runtimeRoot, state) {
+  try {
+    const { getRuntimeContext } = require(runtimeSummaryModulePath);
+    return getRuntimeContext(runtimeRoot, state);
+  } catch {
+    const workItemId = state?.work_item_id;
+    if (!workItemId) {
+      return null;
+    }
+
+    const boardPath = path.join(runtimeRoot, '.opencode', 'work-items', workItemId, 'tasks.json');
+    if (!fs.existsSync(boardPath)) {
+      return null;
+    }
+
+    try {
+      const board = JSON.parse(fs.readFileSync(boardPath, 'utf8'));
+      const tasks = Array.isArray(board.tasks) ? board.tasks : [];
+      const activeStatuses = new Set(['claimed', 'in_progress', 'qa_in_progress']);
+      const activeTasks = tasks.filter((task) => activeStatuses.has(task.status));
+      const formattedActiveTasks = activeTasks.map((task) => {
+        if (task.status === 'qa_in_progress' && task.qa_owner) {
+          return `${task.task_id} (${task.status}, qa: ${task.qa_owner})`;
+        }
+
+        if (task.primary_owner) {
+          return `${task.task_id} (${task.status}, primary: ${task.primary_owner})`;
+        }
+
+        return `${task.task_id} (${task.status})`;
+      });
+
+      return {
+        taskBoardSummary: {
+          total: tasks.length,
+          ready: tasks.filter((task) => task.status === 'ready').length,
+          active: activeTasks.length,
+          activeTasks: formattedActiveTasks,
+        },
+      };
+    } catch {
+      return null;
+    }
+  }
+}
+
+function renderResumeHint(state, runtimeSummaryModulePath, statePath) {
+  const mode = state?.mode;
+  const stage = state?.current_stage;
+  const status = state?.status;
+  const owner = state?.current_owner;
+  const featureId = state?.feature_id;
+  const featureSlug = state?.feature_slug;
+  const workItemId = state?.work_item_id;
+
+  if (!mode || !stage || !status || !owner) {
+    return;
+  }
+
+  const runtimeRoot = path.dirname(path.dirname(path.resolve(statePath)));
+  const runtimeContext = mode === 'full' && workItemId
+    ? resolveRuntimeContext(runtimeSummaryModulePath, runtimeRoot, state)
+    : null;
+  const boardSummary = runtimeContext?.taskBoardSummary ?? null;
+  const activeTasks = boardSummary?.activeTasks ?? [];
+
+  print('<workflow_resume_hint>');
+  print('OpenKit workflow resume context detected.');
+  print(`mode: ${mode}`);
+  print(`stage: ${stage}`);
+  print(`status: ${status}`);
+  print(`owner: ${owner}`);
+  if (featureId && featureSlug) {
+    print(`work item: ${featureId} (${featureSlug})`);
+  }
+  if (workItemId) {
+    print(`active work item id: ${workItemId}`);
+  }
+  if (boardSummary) {
+    print(`task board: ${boardSummary.total ?? 0} tasks | ready ${boardSummary.ready ?? 0} | active ${boardSummary.active ?? 0}`);
+  }
+  if (activeTasks.length > 0) {
+    print(`active tasks: ${activeTasks.join('; ')}`);
+  }
+  print('Read first: AGENTS.md -> context/navigation.md -> context/core/workflow.md -> .opencode/workflow-state.json');
+  print('Then load resume guidance from context/core/session-resume.md.');
+  if (mode === 'full' && activeTasks.length > 0) {
+    print('Parallel task support is not yet assumed safe by this hook; confirm with `node .opencode/workflow-state.js doctor` before relying on it.');
+  }
+  print('</workflow_resume_hint>');
+}
+
+const projectRoot = process.env.OPENKIT_PROJECT_ROOT ? path.resolve(process.env.OPENKIT_PROJECT_ROOT) : process.cwd();
+const statePath = process.env.OPENKIT_WORKFLOW_STATE
+  ? path.resolve(process.env.OPENKIT_WORKFLOW_STATE)
+  : path.join(projectRoot, '.opencode', 'workflow-state.json');
+const kitRoot = resolveKitRoot(projectRoot, statePath);
+const metaSkillPath = path.join(kitRoot, 'skills', 'using-skills', 'SKILL.md');
+const manifestPath = path.join(kitRoot, '.opencode', 'opencode.json');
+const runtimeSummaryModulePath = path.join(kitRoot, '.opencode', 'lib', 'runtime-summary.js');
+
+let kitName = 'OpenKit AI Software Factory';
+let kitVersion = 'unknown';
+let entryAgent = 'unknown';
+let jsonHelperStatus = 'ok';
+
+const manifestResult = readJsonIfPresent(manifestPath);
+if (manifestResult.malformed) {
+  jsonHelperStatus = 'degraded';
+} else if (manifestResult.value?.kit) {
+  kitName = manifestResult.value.kit.name || kitName;
+  kitVersion = manifestResult.value.kit.version || kitVersion;
+  entryAgent = manifestResult.value.kit.entryAgent || entryAgent;
+}
+
+let skillStatus = 'missing';
+if (process.env.OPENKIT_SESSION_START_NO_SKILL) {
+  skillStatus = 'skipped';
+} else if (fs.existsSync(metaSkillPath)) {
+  skillStatus = 'loaded';
+}
+
+const stateResult = readJsonIfPresent(statePath);
+if (stateResult.malformed) {
+  jsonHelperStatus = 'degraded';
+}
+
+print('<openkit_runtime_status>');
+print(`kit: ${kitName} v${kitVersion}`);
+print(`entry agent: ${entryAgent}`);
+print(`state file: ${statePath}`);
+print(`startup skill: ${skillStatus}`);
+print(`json helper: ${jsonHelperStatus}`);
+print('help: node .opencode/workflow-state.js status');
+print('doctor: node .opencode/workflow-state.js doctor');
+print('show: node .opencode/workflow-state.js show');
+print('</openkit_runtime_status>');
+
+if (!process.env.OPENKIT_SESSION_START_NO_SKILL && fs.existsSync(metaSkillPath)) {
+  const metaSkill = fs.readFileSync(metaSkillPath, 'utf8');
+  print('<skill_system_instruction>');
+  print('You are running within the Open Kit AI Software Factory framework.');
+  print('Below are the rules for how you must discover and invoke your skills.');
+  print();
+  process.stdout.write(metaSkill);
+  if (!metaSkill.endsWith('\n')) {
+    print();
+  }
+  print('</skill_system_instruction>');
+}
+
+if (jsonHelperStatus === 'ok' && !stateResult.malformed && stateResult.value) {
+  renderResumeHint(stateResult.value, runtimeSummaryModulePath, statePath);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duypham93/openkit",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "type": "module",
   "files": [
     ".opencode/",

package/registry.json

@@ -3,7 +3,7 @@
   "registryVersion": 1,
   "kit": {
     "name": "OpenKit AI Software Factory",
-    "version": "0.1.0",
+    "version": "0.2.9",
     "description": "Local component metadata for the checked-in OpenKit repository and the global-kit compatibility surface.",
     "repositoryRoot": ".",
     "productSurface": {

package/src/command-detection.js

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function listWindowsExecutableExtensions(env) {
+  const raw = env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD';
+  const extensions = raw
+    .split(';')
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean);
+
+  return extensions.length > 0 ? extensions : ['.com', '.exe', '.bat', '.cmd'];
+}
+
+export function isCommandAvailable(command, { env = process.env, platform = process.platform } = {}) {
+  if (typeof command !== 'string' || command.length === 0) {
+    return false;
+  }
+
+  const pathValue = env.PATH ?? '';
+  if (pathValue.length === 0) {
+    return false;
+  }
+
+  const segments = pathValue.split(path.delimiter).filter(Boolean);
+  const hasExtension = path.extname(command).length > 0;
+  const suffixes = platform === 'win32' && !hasExtension ? ['', ...listWindowsExecutableExtensions(env)] : [''];
+
+  for (const segment of segments) {
+    for (const suffix of suffixes) {
+      if (fs.existsSync(path.join(segment, `${command}${suffix}`))) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}

package/src/global/doctor.js

@@ -2,12 +2,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { readJsonIfPresent, validateGlobalInstallState } from './install-state.js';
-import { ensureWorkspaceBootstrap, readWorkspaceMeta } from './workspace-state.js';
+import { inspectWorkspaceMeta } from './workspace-state.js';
 import { getGlobalPaths, getWorkspacePaths } from './paths.js';
+import { isCommandAvailable } from '../command-detection.js';
 
 function isOpenCodeAvailable(env = process.env) {
-  const pathValue = env.PATH ?? '';
-  return pathValue.split(path.delimiter).some((segment) => segment && fs.existsSync(path.join(segment, 'opencode')));
+  return isCommandAvailable('opencode', { env });
 }
 
 function withGuidance(result, nextStep, recommendedCommand = null) {
@@ -59,8 +59,7 @@ export function inspectGlobalDoctor({ projectRoot = process.cwd(), env = process
     issues.push('OpenCode executable is not available on PATH.');
   }
 
-  const workspace = readWorkspaceMeta({ projectRoot, env });
-  ensureWorkspaceBootstrap({ projectRoot, env });
+  const workspace = inspectWorkspaceMeta({ projectRoot, env });
 
   return withGuidance({
     status: issues.length === 0 ? 'healthy' : 'workspace-ready-with-issues',

package/src/global/install-state.js

@@ -1,9 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { getOpenKitVersion } from '../version.js';
+
 const GLOBAL_INSTALL_SCHEMA = 'openkit/global-install-state@1';
 
-export function createGlobalInstallState({ kitVersion = '0.1.0', installedAt = new Date().toISOString(), profile = 'openkit' } = {}) {
+export function createGlobalInstallState({ kitVersion = getOpenKitVersion(), installedAt = new Date().toISOString(), profile = 'openkit' } = {}) {
   return {
     schema: GLOBAL_INSTALL_SCHEMA,
     stateVersion: 1,

package/src/global/materialize.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 
 import { createGlobalInstallState, writeJson } from './install-state.js';
 import { getGlobalPaths } from './paths.js';
+import { getOpenKitVersion } from '../version.js';
 
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = path.resolve(MODULE_DIR, '../..');
@@ -65,7 +66,7 @@ function createOpenCodeConfig() {
   };
 }
 
-export function materializeGlobalInstall({ env = process.env, kitVersion = '0.1.0' } = {}) {
+export function materializeGlobalInstall({ env = process.env, kitVersion = getOpenKitVersion() } = {}) {
   const paths = getGlobalPaths({ env });
 
   removePathIfPresent(paths.kitRoot);
@@ -92,7 +93,7 @@ export function materializeGlobalInstall({ env = process.env, kitVersion = '0.1.
           hooks: [
             {
               type: 'command',
-              command: `${path.join(paths.kitRoot, 'hooks', 'session-start')}`,
+              command: `${JSON.stringify(process.execPath)} ${JSON.stringify(path.join(paths.kitRoot, 'hooks', 'session-start.js'))}`,
               async: false,
             },
           ],

package/src/global/workspace-shim.js

@@ -29,6 +29,49 @@ function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, 'utf8'));
 }
 
+function isSymlink(filePath) {
+  try {
+    return fs.lstatSync(filePath).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function isManagedWorkflowWrapper(content, { requiresAliasMap = false } = {}) {
+  if (typeof content !== 'string' || content.length === 0) {
+    return false;
+  }
+
+  const sharedMarkers = [
+    "require('node:child_process')",
+    'spawnSync(process.execPath',
+    "'--state'",
+    "process.exit(typeof result.status === 'number' ? result.status : 1);",
+  ];
+
+  if (!sharedMarkers.every((marker) => content.includes(marker))) {
+    return false;
+  }
+
+  if (!requiresAliasMap) {
+    return true;
+  }
+
+  return content.includes('const aliasMap = new Map([');
+}
+
+function shouldRefreshRootWorkflowWrapper(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return true;
+  }
+
+  try {
+    return isManagedWorkflowWrapper(fs.readFileSync(filePath, 'utf8'), { requiresAliasMap: true });
+  } catch {
+    return false;
+  }
+}
+
 function relativeTarget(fromPath, toPath) {
   return path.relative(path.dirname(fromPath), toPath) || '.';
 }
@@ -102,7 +145,8 @@ export function ensureWorkspaceShim(paths) {
   }
 
   const workflowCli = `#!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
+// Generated by OpenKit workspace shim.
+const { spawnSync } = require('node:child_process');
 
 const args = process.argv.slice(2);
 const result = spawnSync(process.execPath, [${JSON.stringify(path.join(paths.kitRoot, '.opencode', 'workflow-state.js'))}, '--state', ${JSON.stringify(paths.workflowStatePath)}, ...args], {
@@ -117,8 +161,9 @@ if (result.error) {
 process.exit(typeof result.status === 'number' ? result.status : 1);
 `;
 
-  if (!fs.existsSync(paths.workspaceShimWorkflowCliPath)) {
-    writeFile(paths.workspaceShimWorkflowCliPath, workflowCli, 0o755);
+  const workspaceWrapperExists = fs.existsSync(paths.workspaceShimWorkflowCliPath);
+  writeFile(paths.workspaceShimWorkflowCliPath, workflowCli, 0o755);
+  if (!workspaceWrapperExists) {
     createdPaths.push(paths.workspaceShimWorkflowCliPath);
   }
 
@@ -134,22 +179,20 @@ process.exit(typeof result.status === 'number' ? result.status : 1);
     type: 'dir',
   });
 
-  createIfMissing(createdPaths, {
+  const rootWorkflowStateMode = createIfMissing(createdPaths, {
     linkPath: path.join(paths.projectRoot, '.opencode', 'workflow-state.json'),
     targetPath: paths.workspaceShimWorkflowStatePath,
     type: 'file',
   });
 
   const rootWorkflowStatePath = path.join(paths.projectRoot, '.opencode', 'workflow-state.json');
-  if (!fs.existsSync(rootWorkflowStatePath)) {
-    createdPaths.push(rootWorkflowStatePath);
-  }
-  if (fs.existsSync(paths.workflowStatePath)) {
+  if (fs.existsSync(paths.workflowStatePath) && (rootWorkflowStateMode !== null || isSymlink(rootWorkflowStatePath))) {
     writeJson(rootWorkflowStatePath, readJson(paths.workflowStatePath));
   }
 
-  if (!fs.existsSync(path.join(paths.projectRoot, '.opencode', 'workflow-state.js'))) {
+  if (shouldRefreshRootWorkflowWrapper(path.join(paths.projectRoot, '.opencode', 'workflow-state.js'))) {
     const rootWorkflowCli = `#!/usr/bin/env node
+// Generated by OpenKit workspace shim.
 const { spawnSync } = require('node:child_process');
 
 const rawArgs = process.argv.slice(2);
@@ -173,8 +216,11 @@ process.exit(typeof result.status === 'number' ? result.status : 1);
 `;
 
     const rootWorkflowCliPath = path.join(paths.projectRoot, '.opencode', 'workflow-state.js');
+    const rootWrapperExists = fs.existsSync(rootWorkflowCliPath);
     writeFile(rootWorkflowCliPath, rootWorkflowCli, 0o755);
-    createdPaths.push(rootWorkflowCliPath);
+    if (!rootWrapperExists) {
+      createdPaths.push(rootWorkflowCliPath);
+    }
   }
 
   if (!fs.existsSync(path.join(paths.projectRoot, '.opencode', 'work-items'))) {

package/src/global/workspace-state.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 
 import { getWorkspacePaths } from './paths.js';
 import { ensureWorkspaceShim } from './workspace-shim.js';
+import { getOpenKitVersion } from '../version.js';
 
 const WORKSPACE_STATE_SCHEMA = 'openkit/workspace-state@1';
 
@@ -115,7 +116,7 @@ function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, 'utf8'));
 }
 
-export function createWorkspaceMeta({ projectRoot, workspaceId, kitVersion = '0.1.0', profile = 'openkit' }) {
+export function createWorkspaceMeta({ projectRoot, workspaceId, kitVersion = getOpenKitVersion(), profile = 'openkit' }) {
   return {
     schema: WORKSPACE_STATE_SCHEMA,
     stateVersion: 1,
@@ -171,3 +172,13 @@ export function readWorkspaceMeta(options = {}) {
     index: readJson(paths.workItemIndexPath),
   };
 }
+
+export function inspectWorkspaceMeta(options = {}) {
+  const paths = getWorkspacePaths(options);
+
+  return {
+    paths,
+    meta: fs.existsSync(paths.workspaceMetaPath) ? readJson(paths.workspaceMetaPath) : null,
+    index: fs.existsSync(paths.workItemIndexPath) ? readJson(paths.workItemIndexPath) : null,
+  };
+}

package/src/install/install-state.js

@@ -1,3 +1,5 @@
+import { getOpenKitVersion } from '../version.js'
+
 export const INSTALL_STATE_SCHEMA = "openkit/install-state@1"
 
 const MANAGED_STATUSES = new Set(["managed", "materialized"])
@@ -24,7 +26,7 @@ function isArray(value) {
 }
 
 export function createInstallState({
-  kitVersion = "0.1.0",
+  kitVersion = getOpenKitVersion(),
   profile = "openkit-core",
   managedAssets = [],
   adoptedAssets = [],

package/src/install/materialize.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url"
 import { createInstallState } from "./install-state.js"
 import { applyOpenKitMergePolicy } from "./merge-policy.js"
 import { createMaterializationConflict, qualifyMergeConflicts } from "./conflicts.js"
+import { getOpenKitVersion } from "../version.js"
 
 const ROOT_MANIFEST_ASSET_ID = "runtime.opencode-manifest"
 const ROOT_MANIFEST_PATH = "opencode.json"
@@ -40,7 +41,7 @@ function removeFileIfPresent(filePath) {
   }
 }
 
-export function materializeInstall(projectRoot, { kitVersion = "0.1.0", now } = {}) {
+export function materializeInstall(projectRoot, { kitVersion = getOpenKitVersion(), now } = {}) {
   const desiredRootManifest = readTemplate("assets/opencode.json.template")
   const rootManifestPath = path.join(projectRoot, ROOT_MANIFEST_PATH)
   const installStatePath = path.join(projectRoot, INSTALL_STATE_PATH)

package/src/runtime/doctor.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 
 import { validateInstallState } from '../install/install-state.js';
 import { discoverProjectShape } from '../install/discovery.js';
+import { isCommandAvailable } from '../command-detection.js';
 
 const EXPECTED_MANAGED_ASSETS = {
   'runtime.opencode-manifest': {
@@ -52,15 +53,7 @@ function readJsonIfPresent(filePath) {
 }
 
 function defaultIsOpenCodeAvailable() {
-  const pathValue = process.env.PATH ?? '';
-  return pathValue.split(path.delimiter).some((segment) => {
-    if (!segment) {
-      return false;
-    }
-
-    const candidate = path.join(segment, 'opencode');
-    return fs.existsSync(candidate);
-  });
+  return isCommandAvailable('opencode');
 }
 
 export function inspectManagedDoctor({

package/src/version.js

@@ -0,0 +1,25 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_JSON_PATH = path.resolve(MODULE_DIR, '..', 'package.json');
+
+let cachedVersion = null;
+
+export function getOpenKitVersion() {
+  if (cachedVersion !== null) {
+    return cachedVersion;
+  }
+
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, 'utf8'));
+    cachedVersion = typeof packageJson.version === 'string' && packageJson.version.length > 0
+      ? packageJson.version
+      : 'unknown';
+  } catch {
+    cachedVersion = 'unknown';
+  }
+
+  return cachedVersion;
+}

package/tests/cli/openkit-cli.test.js

@@ -6,6 +6,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { inspectGlobalDoctor } from '../../src/global/doctor.js';
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const worktreeRoot = path.resolve(__dirname, '..', '..');
@@ -96,6 +98,8 @@ test('openkit install-global materializes global kit and profile files', () => {
   assert.equal(fs.existsSync(path.join(profileRoot, 'opencode.json')), true);
   assert.equal(readJson(path.join(profileRoot, 'opencode.json')).default_agent, 'master-orchestrator');
   assert.equal(fs.existsSync(path.join(kitRoot, 'opencode.json')), true);
+  assert.match(readJson(path.join(kitRoot, 'install-state.json')).kit.version, /^0\.2\.9$/);
+  assert.match(readJson(path.join(profileRoot, 'hooks.json')).hooks.SessionStart[0].hooks[0].command, /session-start\.js/);
 });
 
 test('openkit init and install remain compatibility aliases for install-global', () => {
@@ -140,7 +144,7 @@ test('openkit doctor reports install-missing when global install is absent', ()
   assert.match(result.stdout, /Recommended command: openkit run/);
 });
 
-test('openkit doctor reports healthy after global install and bootstraps workspace metadata', () => {
+test('openkit doctor reports healthy without mutating workspace metadata', () => {
   const tempHome = makeTempDir();
   const projectRoot = makeTempDir();
   const fakeBinDir = path.join(tempHome, 'bin');
@@ -168,12 +172,8 @@ test('openkit doctor reports healthy after global install and bootstraps workspa
   assert.match(result.stdout, /Workspace root:/);
   assert.match(result.stdout, /Next: Run openkit run/);
   assert.match(result.stdout, /Recommended command: openkit run/);
-
-  const workspacesRoot = path.join(tempHome, 'workspaces');
-  const workspaceEntries = fs.readdirSync(workspacesRoot);
-  assert.equal(workspaceEntries.length, 1);
-  const workspaceMetaPath = path.join(workspacesRoot, workspaceEntries[0], 'openkit', 'workspace.json');
-  assert.equal(fs.existsSync(workspaceMetaPath), true);
+  assert.equal(fs.existsSync(path.join(tempHome, 'workspaces')), false);
+  assert.equal(fs.existsSync(path.join(projectRoot, '.opencode')), false);
 });
 
 test('openkit run launches opencode with the global profile and workspace env', () => {
@@ -336,9 +336,75 @@ test('openkit run does not overwrite existing repo-local workflow files when cre
   assert.equal(fs.readFileSync(path.join(projectRoot, 'AGENTS.md'), 'utf8'), 'project agents\n');
   assert.equal(fs.readFileSync(path.join(projectRoot, 'context', 'core', 'workflow.md'), 'utf8'), 'project workflow\n');
   assert.equal(fs.readFileSync(path.join(projectRoot, '.opencode', 'workflow-state.js'), 'utf8'), '#!/usr/bin/env node\n');
+  assert.equal(fs.readFileSync(path.join(projectRoot, '.opencode', 'workflow-state.json'), 'utf8'), '{"project":true}\n');
   assert.equal(fs.existsSync(path.join(projectRoot, '.opencode', 'openkit', 'AGENTS.md')), true);
 });
 
+test('openkit run refreshes managed wrappers when the workspace location changes', () => {
+  const tempHomeA = makeTempDir();
+  const tempHomeB = makeTempDir();
+  const projectRoot = makeTempDir();
+  const fakeBinDirA = path.join(tempHomeA, 'bin');
+  const fakeBinDirB = path.join(tempHomeB, 'bin');
+
+  writeExecutable(path.join(fakeBinDirA, 'opencode'), '#!/bin/sh\nexit 0\n');
+  writeExecutable(path.join(fakeBinDirB, 'opencode'), '#!/bin/sh\nexit 0\n');
+
+  let result = runCli(['run'], {
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHomeA,
+      PATH: `${fakeBinDirA}${path.delimiter}${process.env.PATH}`,
+    },
+  });
+
+  assert.equal(result.status, 0);
+
+  result = runCli(['run'], {
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHomeB,
+      PATH: `${fakeBinDirB}${path.delimiter}${process.env.PATH}`,
+    },
+  });
+
+  assert.equal(result.status, 0);
+
+  const workspaceWrapper = fs.readFileSync(path.join(projectRoot, '.opencode', 'openkit', 'workflow-state.js'), 'utf8');
+  assert.match(workspaceWrapper, new RegExp(tempHomeB.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+  assert.doesNotMatch(workspaceWrapper, new RegExp(tempHomeA.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+});
+
+test('openkit doctor recognizes opencode.cmd on Windows-style PATH', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+  const fakeBinDir = path.join(tempHome, 'bin');
+  writeExecutable(path.join(fakeBinDir, 'opencode.cmd'), '@echo off\nexit /b 0\n');
+
+  const installResult = runCli(['install-global'], {
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+    },
+  });
+  assert.equal(installResult.status, 0);
+
+  const doctor = inspectGlobalDoctor({
+    projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+      PATH: fakeBinDir,
+      PATHEXT: '.CMD;.EXE',
+    },
+  });
+
+  assert.equal(doctor.status, 'workspace-ready-with-issues');
+  assert.match(doctor.issues.join('\n'), /OpenCode executable is not available on PATH/);
+});
+
 test('openkit run cleans root compatibility shims when created files are removed', () => {
   const tempHome = makeTempDir();
   const projectRoot = makeTempDir();
@@ -366,7 +432,7 @@ test('openkit run cleans root compatibility shims when created files are removed
   assert.equal(fs.existsSync(path.join(projectRoot, '.opencode', 'openkit', 'AGENTS.md')), true);
 });
 
-test('openkit run creates a module-aware root workflow wrapper with alias support', () => {
+test('openkit run creates CommonJS workflow wrappers without module-boundary warnings', () => {
   const tempHome = makeTempDir();
   const projectRoot = makeTempDir();
   const fakeBinDir = path.join(tempHome, 'bin');
@@ -384,10 +450,23 @@ test('openkit run creates a module-aware root workflow wrapper with alias suppor
 
   assert.equal(result.status, 0);
 
-  const wrapper = fs.readFileSync(path.join(projectRoot, '.opencode', 'workflow-state.js'), 'utf8');
-  assert.match(wrapper, /const \{ spawnSync \} = require\('node:child_process'\);/);
-  assert.match(wrapper, /\['get', 'show'\]/);
-  assert.match(wrapper, /\['--help', 'help'\]/);
+  const rootWrapper = fs.readFileSync(path.join(projectRoot, '.opencode', 'workflow-state.js'), 'utf8');
+  assert.match(rootWrapper, /const \{ spawnSync \} = require\('node:child_process'\);/);
+  assert.match(rootWrapper, /\['get', 'show'\]/);
+  assert.match(rootWrapper, /\['--help', 'help'\]/);
+
+  const workspaceWrapper = fs.readFileSync(path.join(projectRoot, '.opencode', 'openkit', 'workflow-state.js'), 'utf8');
+  assert.match(workspaceWrapper, /const \{ spawnSync \} = require\('node:child_process'\);/);
+  assert.doesNotMatch(workspaceWrapper, /import \{ spawnSync \} from 'node:child_process';/);
+
+  const wrapperRun = spawnSync(process.execPath, ['.opencode/openkit/workflow-state.js', 'help'], {
+    cwd: projectRoot,
+    encoding: 'utf8',
+  });
+
+  assert.equal(wrapperRun.status, 0);
+  assert.match(wrapperRun.stdout, /Usage:/);
+  assert.doesNotMatch(wrapperRun.stderr, /MODULE_TYPELESS_PACKAGE_JSON/);
 });
 
 test('openkit run reports missing opencode after first-time setup completes', () => {
@@ -420,7 +499,7 @@ test('openkit run blocks on invalid global install state and recommends upgrade'
     `${JSON.stringify({
       schema: 'wrong-schema',
       stateVersion: 1,
-      kit: { name: 'OpenKit', version: '0.1.0' },
+      kit: { name: 'OpenKit', version: '0.2.9' },
       installation: {
         profile: 'openkit',
         status: 'installed',

package/tests/global/doctor.test.js

@@ -69,6 +69,11 @@ test('global doctor reports next steps for healthy installs', () => {
   assert.equal(result.status, 'healthy');
   assert.equal(result.nextStep, 'Run openkit run.');
   assert.equal(result.recommendedCommand, 'openkit run');
+  assert.equal(result.workspace.paths.workspaceRoot.includes('workspaces'), true);
+  assert.equal(result.workspace.meta, null);
+  assert.equal(result.workspace.index, null);
+  assert.equal(fs.existsSync(path.join(projectRoot, '.opencode')), false);
+  assert.equal(fs.existsSync(path.join(tempHome, 'workspaces')), false);
 });
 
 test('global doctor recommends upgrade for invalid installs', () => {
@@ -80,7 +85,7 @@ test('global doctor recommends upgrade for invalid installs', () => {
     stateVersion: 1,
     kit: {
       name: 'OpenKit',
-      version: '0.1.0',
+      version: '0.2.9',
     },
     installation: {
       profile: 'openkit',
@@ -127,4 +132,6 @@ test('global doctor reports workspace issues with guidance', () => {
   assert.equal(result.nextStep, 'Review the issues above before relying on this workspace.');
   assert.equal(result.recommendedCommand, null);
   assert.match(result.issues.join('\n'), /OpenCode executable is not available on PATH/);
+  assert.equal(result.workspace.meta, null);
+  assert.equal(fs.existsSync(path.join(projectRoot, '.opencode')), false);
 });

package/tests/global/ensure-install.test.js

@@ -44,6 +44,7 @@ test('ensureGlobalInstall returns none when install is healthy', () => {
   assert.equal(result.action, 'none');
   assert.equal(result.installed, false);
   assert.equal(result.doctor.status, 'healthy');
+  assert.equal(fs.existsSync(path.join(tempHome, 'workspaces')), false);
 });
 
 test('ensureGlobalInstall materializes the global install when it is missing', () => {
@@ -80,7 +81,7 @@ test('ensureGlobalInstall returns blocked when install state is invalid', () =>
     stateVersion: 1,
     kit: {
       name: 'OpenKit',
-      version: '0.1.0',
+      version: '0.2.9',
     },
     installation: {
       profile: 'openkit',

package/tests/runtime/doctor.test.js

@@ -38,7 +38,7 @@ function materializeManagedInstall(projectRoot) {
     stateVersion: 1,
     kit: {
       name: 'OpenKit',
-      version: '0.1.0',
+      version: '0.2.9',
     },
     installation: {
       profile: 'openkit-core',
@@ -110,7 +110,7 @@ test('doctor reports install incomplete for a partial install when install state
     stateVersion: 1,
     kit: {
       name: 'OpenKit',
-      version: '0.1.0',
+      version: '0.2.9',
     },
     installation: {
       profile: 'openkit-core',
@@ -187,7 +187,7 @@ test('doctor reports drift for managed install-state assets it owns in phase 1',
     stateVersion: 1,
     kit: {
       name: 'OpenKit',
-      version: '0.1.0',
+      version: '0.2.9',
     },
     installation: {
       profile: 'custom-profile',
@@ -323,7 +323,7 @@ test('doctor does not report healthy when an adopted root manifest is incompatib
     stateVersion: 1,
     kit: {
       name: 'OpenKit',
-      version: '0.1.0',
+      version: '0.2.9',
     },
     installation: {
       profile: 'openkit-core',
@@ -390,7 +390,7 @@ test('doctor can report healthy when an adopted root manifest still satisfies th
     stateVersion: 1,
     kit: {
       name: 'OpenKit',
-      version: '0.1.0',
+      version: '0.2.9',
     },
     installation: {
       profile: 'openkit-core',