@kal-elsam/kairo-runtime 0.1.0 → 0.1.2

package/README.md

@@ -12,6 +12,10 @@ The npm package (`@kal-elsam/kairo-runtime`) is how Kairo Runtime is distributed
 product identity is the local control plane: setup, status, sync, doctor (with `update`
 as a technical alias).
 
+`@kal-elsam/harness` remains available as a **compatibility bridge** that delegates to
+Kairo Runtime and prints a migration warning. Prefer `@kal-elsam/kairo-runtime` and the
+`kairo` CLI for new installs. See [`packages/harness-bridge/README.md`](packages/harness-bridge/README.md).
+
 Terminal UX aims for Pi-like clarity (clear modes, non-interactive flags, extensible
 commands) without depending on Pi as a runtime or adding a Pi adapter.
 
@@ -47,14 +51,14 @@ curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/inst
 The bootstrap installer:
 
 - requires Node.js 20.12+ and npm
-- runs `@kal-elsam/kairo-runtime` via `npx` (or `npm exec`)
-- ends with `kairo setup --dry-run` by default (no agent configs, no `~/.harness` writes)
+- installs `@kal-elsam/kairo-runtime` globally (`kairo` CLI)
+- runs `kairo setup --dry-run` by default (no agent configs, no `~/.harness` writes)
 - never uses `sudo`, never modifies shell profiles, and never installs AI apps
 
 Apply the plan when you are ready:
 
 ```bash
-npx @kal-elsam/kairo-runtime --yes
+kairo setup --yes
 # or
 curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/install.sh | sh -s -- --yes
 ```
@@ -62,8 +66,8 @@ curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/inst
 CI, scripts, and advanced non-interactive configure:
 
 ```bash
-npx @kal-elsam/kairo-runtime install --agents cursor,codex --yes
-npx @kal-elsam/kairo-runtime setup --yes --agents all
+kairo install --agents cursor,codex --yes
+kairo setup --yes --agents all
 ```
 
 Passthrough examples:
@@ -79,11 +83,11 @@ Control plane:
 kairo status
 kairo sync
 kairo upgrade --dry-run
-npx @kal-elsam/kairo-runtime@latest setup --yes
+kairo setup --yes
 ```
 
 After `install.sh --yes`, verify health with `kairo status`, repair drift with `kairo sync`,
-and move to the latest package with `npx @kal-elsam/kairo-runtime@latest setup --yes`.
+and preview upgrades with `kairo upgrade --dry-run`.
 
 ### Version and updates
 
@@ -649,7 +653,23 @@ Install the harness in enterprise mode because this project will have AI, API, D
 
 ## Publishing
 
-Published on npm as `@kal-elsam/kairo-runtime`. Releases use **npm Trusted Publishing/OIDC** from GitHub Actions — no `NPM_TOKEN`.
+Published on npm as `@kal-elsam/kairo-runtime`. Releases use **npm Trusted Publishing/OIDC**
+from GitHub Actions — no `NPM_TOKEN`.
+
+`@kal-elsam/harness` is published separately as a compatibility bridge from
+`packages/harness-bridge/` (see bridge README).
+
+### Git tags (package-aware)
+
+| Tag pattern | Package | Publish root |
+|---|---|---|
+| `kairo-runtime-v*` | `@kal-elsam/kairo-runtime` | repo root |
+| `harness-bridge-v*` | `@kal-elsam/harness` | `packages/harness-bridge/` |
+| `v*` | legacy / historical root releases | repo root |
+
+Kairo Runtime releases should use `kairo-runtime-vX.Y.Z` going forward. The first
+bootstrap used `v0.1.0`; later releases use package-aware tags such as
+`kairo-runtime-v0.1.1`.
 
 Before tagging a new version:
 
@@ -684,37 +704,74 @@ to end:
   rollback apply (with safety backup), `uninstall`.
 - **workspace:** `install --scope=workspace`, `doctor`, `update --dry-run`.
 
-Release flow:
+Release flow (Kairo Runtime):
 
 ```bash
 # bump version in package.json and package-lock.json
 git add .
-git commit -m "chore: release 0.5.0"
+git commit -m "chore: release kairo-runtime 0.1.1"
 npm run release:check
-git tag v0.5.0
+git tag kairo-runtime-v0.1.1
 git push origin main
-git push origin v0.5.0
+git push origin kairo-runtime-v0.1.1
 ```
 
+Bridge release flow:
+
+```bash
+# bump packages/harness-bridge/package.json (+ lockfile)
+git add .
+git commit -m "chore: release harness bridge 0.30.0"
+npm run release:check
+git tag harness-bridge-v0.30.0
+git push origin main
+git push origin harness-bridge-v0.30.0
+```
+
+Legacy `v*` tags still publish from the repo root for historical continuity.
+
 After npm publishes the tag, verify published provenance against git and the registry:
 
 ```bash
 git fetch --tags origin
 git fetch origin main
-npm run release:published -- --version 0.1.0
-npm run smoke:registry -- --version 0.1.0
-npm run smoke:installer -- --version 0.1.0
+npm run release:published -- --version 0.1.1 --tag kairo-runtime-v0.1.1
+npm run smoke:registry -- --version 0.1.1
+npm run smoke:installer -- --version 0.1.1 --tag kairo-runtime-v0.1.1
+npm run smoke:bridge
+```
+
+`release:published` checks npm `version`, npm `gitHead`, the release git tag on
+`origin`, and `origin/main`. Override the package and tag when needed:
+
+```bash
+npm run release:published -- \
+  --package @kal-elsam/kairo-runtime \
+  --tag kairo-runtime-v0.1.1 \
+  --version 0.1.1
+
+npm run release:published -- \
+  --package @kal-elsam/harness \
+  --tag harness-bridge-v0.30.0 \
+  --version 0.30.0
 ```
 
-`release:published` checks npm `version`, npm `gitHead`, local tag `v*`, remote tag on `origin`, and `origin/main`. Override the package with `--package @kal-elsam/kairo-runtime` when needed.
+Without `--tag`, provenance checks fall back to `v${version}` (legacy tags).
 
 `smoke:registry` installs `@kal-elsam/kairo-runtime` from the npm registry (not the local tarball) into a throwaway workspace with a fake `HARNESS_HOME` and npm cache, then runs the recommended flow via `kairo`: `setup --dry-run`, `setup --yes`, `status`, drift simulation, `sync`, `status --json` (expects `overall=ok`), and `uninstall`. Use `latest` by default, pin with `--version x.y.z`, or override with `--package`.
 
-`smoke:installer` validates the public one-liner path: `curl .../install.sh | sh` against GitHub `raw` and the npm registry with isolated `HARNESS_HOME`. Preview must not write `~/.harness`; `--yes --agents all` must reach `kairo status --json` with `overall=ok`, then `kairo uninstall` must remove managed sections. Pin with `--version x.y.z` after publish.
+`smoke:installer` validates the public one-liner path: `curl .../install.sh | sh` against GitHub `raw` and the npm registry with isolated `HARNESS_HOME`. Preview must not write `~/.harness`; `--yes --agents all` must reach `kairo status --json` with `overall=ok`, then `kairo uninstall` must remove managed sections. Pin with `--version x.y.z` after publish. For package-aware Kairo Runtime tags, pass the git tag explicitly:
+
+```bash
+npm run smoke:installer -- --version 0.1.1 --tag kairo-runtime-v0.1.1
+```
+
+Without `--tag`, the install script resolves from legacy `v${version}` tags.
 
-Suggested first publish tag: `kairo-runtime-v0.1.0` (or `v0.30.0` if you prefer repo version continuity).
+Suggested first Kairo Runtime tag after bootstrap: `kairo-runtime-v0.1.1`.
 
-The `publish.yml` workflow runs on `v*` tags and publishes to npm using the `npm-publish` environment.
+The `publish.yml` workflow runs on `v*`, `kairo-runtime-v*`, and `harness-bridge-v*`
+tags and publishes to npm using the `npm-publish` environment.
 It runs `npm run release:check` on `HEAD` immediately before `npm publish`.
 
 See the full policy in `SECURITY.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Gemini, Copilot, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",
@@ -35,6 +35,7 @@
     "ux:smoke": "bash scripts/ux-smoke-test.sh",
     "smoke:registry": "bash scripts/registry-smoke-test.sh",
     "smoke:installer": "bash scripts/installer-smoke-test.sh",
+    "smoke:bridge": "bash scripts/bridge-smoke-test.sh",
     "release:check": "node scripts/check-release-commit.mjs",
     "release:published": "node scripts/check-published-release.mjs"
   },

package/scripts/bridge-smoke-test.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+BRIDGE_DIR="$ROOT/packages/harness-bridge"
+WORKDIR="$(mktemp -d)"
+FAKE_HOME="$(mktemp -d)"
+NPM_CACHE="$(mktemp -d)"
+
+cleanup() {
+  rm -rf "$WORKDIR" "$FAKE_HOME" "$NPM_CACHE"
+}
+trap cleanup EXIT
+
+export HARNESS_HOME="$FAKE_HOME"
+export npm_config_cache="$NPM_CACHE"
+
+mkdir -p \
+  "$FAKE_HOME/.cursor" \
+  "$FAKE_HOME/.codex" \
+  "$FAKE_HOME/.config/opencode" \
+  "$FAKE_HOME/.claude"
+
+echo "Packing @kal-elsam/kairo-runtime from $ROOT"
+RUNTIME_TGZ="$(cd "$ROOT" && npm pack --silent --pack-destination "$WORKDIR")"
+RUNTIME_TGZ_PATH="$WORKDIR/$RUNTIME_TGZ"
+
+echo "Packing @kal-elsam/harness bridge"
+BRIDGE_TGZ="$(cd "$BRIDGE_DIR" && npm pack --silent --pack-destination "$WORKDIR")"
+BRIDGE_TGZ_PATH="$WORKDIR/$BRIDGE_TGZ"
+
+INSTALL_DIR="$WORKDIR/project"
+mkdir -p "$INSTALL_DIR"
+(
+  cd "$INSTALL_DIR"
+  npm init -y >/dev/null
+  npm install "$RUNTIME_TGZ_PATH" "$BRIDGE_TGZ_PATH" --ignore-scripts
+)
+
+HARNESS_BIN="$INSTALL_DIR/node_modules/@kal-elsam/harness/bin/harness.js"
+
+echo
+echo "== harness --version (warning on stderr, version on stdout) =="
+VERSION_OUTPUT="$(node "$HARNESS_BIN" --version 2>"$WORKDIR/version.stderr" || true)"
+VERSION_STDERR="$(cat "$WORKDIR/version.stderr")"
+
+if ! grep -q "@kal-elsam/harness has moved to @kal-elsam/kairo-runtime" <<<"$VERSION_STDERR"; then
+  echo "Expected migration warning on stderr" >&2
+  echo "stderr: $VERSION_STDERR" >&2
+  exit 1
+fi
+
+if ! grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' <<<"$VERSION_OUTPUT"; then
+  echo "Expected semver on stdout, got: $VERSION_OUTPUT" >&2
+  exit 1
+fi
+
+if grep -q "@kal-elsam/harness has moved" <<<"$VERSION_OUTPUT"; then
+  echo "Migration warning must not appear on stdout" >&2
+  exit 1
+fi
+
+echo "stdout version: $VERSION_OUTPUT"
+
+echo
+echo "== harness status --json (JSON on stdout only) =="
+set +e
+STATUS_OUTPUT="$(node "$HARNESS_BIN" status --json 2>"$WORKDIR/status.stderr")"
+STATUS_EXIT=$?
+set -e
+STATUS_STDERR="$(cat "$WORKDIR/status.stderr")"
+
+if [ "$STATUS_EXIT" -ne 0 ] && [ "$STATUS_EXIT" -ne 1 ]; then
+  echo "Unexpected exit code from harness status --json: $STATUS_EXIT" >&2
+  exit 1
+fi
+
+if ! grep -q "@kal-elsam/harness has moved to @kal-elsam/kairo-runtime" <<<"$STATUS_STDERR"; then
+  echo "Expected migration warning on stderr for status --json" >&2
+  exit 1
+fi
+
+node -e "JSON.parse(process.argv[1])" "$STATUS_OUTPUT"
+
+if grep -q "@kal-elsam/harness has moved" <<<"$STATUS_OUTPUT"; then
+  echo "Migration warning must not appear in JSON stdout" >&2
+  exit 1
+fi
+
+echo
+echo "Bridge smoke test passed."

package/scripts/check-published-release.mjs

@@ -15,10 +15,19 @@ async function defaultFetchJson(url) {
   return response.json();
 }
 
+export function resolveReleaseTag({ version, tag = null }) {
+  if (tag) {
+    return tag;
+  }
+
+  return `v${version}`;
+}
+
 export function parsePublishedReleaseArgs(argv) {
   const args = [...argv];
   let version = null;
   let packageName = "@kal-elsam/kairo-runtime";
+  let tag = null;
 
   for (let index = 2; index < args.length; index += 1) {
     const arg = args[index];
@@ -43,6 +52,16 @@ export function parsePublishedReleaseArgs(argv) {
       continue;
     }
 
+    if (arg === "--tag") {
+      tag = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--tag=")) {
+      tag = arg.slice("--tag=".length);
+      continue;
+    }
+
     throw new Error(`Unknown option "${arg}".`);
   }
 
@@ -50,16 +69,17 @@ export function parsePublishedReleaseArgs(argv) {
     throw new Error("Missing required --version <x.y.z>.");
   }
 
-  return { version, packageName };
+  return { version, packageName, tag };
 }
 
 export async function verifyPublishedRelease({
   version,
   packageName = "@kal-elsam/kairo-runtime",
+  tag = null,
   runGit = defaultRunGit,
   fetchJson = defaultFetchJson
 }) {
-  const tag = `v${version}`;
+  const releaseTag = resolveReleaseTag({ version, tag });
   const encodedPackage = encodeURIComponent(packageName);
   const meta = await fetchJson(`https://registry.npmjs.org/${encodedPackage}/${version}`);
 
@@ -72,10 +92,12 @@ export async function verifyPublishedRelease({
   }
 
   const gitHead = meta.gitHead.trim();
-  const tagSha = runGit(`git rev-parse ${tag}^{commit}`).trim();
+  const tagSha = runGit(`git rev-parse ${releaseTag}^{commit}`).trim();
 
   if (tagSha !== gitHead) {
-    throw new Error(`Local tag ${tag} (${tagSha}) does not match npm gitHead (${gitHead})`);
+    throw new Error(
+      `Local tag ${releaseTag} (${tagSha}) does not match npm gitHead (${gitHead})`
+    );
   }
 
   const mainSha = runGit("git rev-parse origin/main").trim();
@@ -90,17 +112,19 @@ export async function verifyPublishedRelease({
     }
   }
 
-  const remoteTagLine = runGit(`git ls-remote --tags origin refs/tags/${tag}`).trim();
+  const remoteTagLine = runGit(`git ls-remote --tags origin refs/tags/${releaseTag}`).trim();
 
   if (!remoteTagLine.startsWith(gitHead)) {
-    throw new Error(`Remote tag ${tag} on origin does not point to npm gitHead (${gitHead})`);
+    throw new Error(
+      `Remote tag ${releaseTag} on origin does not point to npm gitHead (${gitHead})`
+    );
   }
 
   return {
     version,
     packageName,
     gitHead,
-    tag,
+    tag: releaseTag,
     mainSha,
     tagSha,
     mainAhead: mainSha !== gitHead
@@ -114,8 +138,8 @@ function isMainModule() {
 }
 
 if (isMainModule()) {
-  const { version, packageName } = parsePublishedReleaseArgs(process.argv);
-  const result = await verifyPublishedRelease({ version, packageName });
+  const { version, packageName, tag } = parsePublishedReleaseArgs(process.argv);
+  const result = await verifyPublishedRelease({ version, packageName, tag });
 
   console.log("Published release provenance OK");
   console.log(`Package: ${result.packageName}@${result.version}`);

package/scripts/install.sh

@@ -43,8 +43,9 @@ usage() {
     "" \
     "What it does:" \
     "  1. Checks for Node.js and npm." \
-    "  2. Runs the package via npx (or npm exec) with setup --dry-run (default) or setup --yes (--yes)." \
-    "  3. Prints next steps." \
+    "  2. Installs ${PACKAGE} globally (adds kairo to npm global bin)." \
+    "  3. Runs kairo setup --dry-run (default) or kairo setup --yes (--yes)." \
+    "  4. Prints next steps." \
     "" \
     "Security:" \
     "  - Never uses sudo." \
@@ -62,6 +63,51 @@ append_setup_arg() {
   SETUP_EXTRA="${SETUP_EXTRA}${SETUP_EXTRA:+ }$1"
 }
 
+resolve_global_spec() {
+  if [ "$VERSION" = "latest" ]; then
+    printf '%s@latest' "$PACKAGE"
+  else
+    printf '%s@%s' "$PACKAGE" "$VERSION"
+  fi
+}
+
+resolve_npm_global_bin() {
+  npm_prefix="$(npm prefix -g 2>/dev/null || true)"
+  [ -n "$npm_prefix" ] || return 1
+  printf '%s/bin' "$(printf '%s' "$npm_prefix" | sed 's#/*$##')"
+}
+
+resolve_kairo_bin() {
+  if command -v "$PREFERRED_CLI" >/dev/null 2>&1; then
+    command -v "$PREFERRED_CLI"
+    return 0
+  fi
+
+  global_bin="$(resolve_npm_global_bin || true)"
+  if [ -n "$global_bin" ] && [ -x "${global_bin}/${PREFERRED_CLI}" ]; then
+    printf '%s\n' "${global_bin}/${PREFERRED_CLI}"
+    return 0
+  fi
+
+  return 1
+}
+
+print_path_hint_if_needed() {
+  if command -v "$PREFERRED_CLI" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  global_bin="$(resolve_npm_global_bin || true)"
+  if [ -n "$global_bin" ]; then
+    printf '%s\n' \
+      "" \
+      "PATH note:" \
+      "  ${PREFERRED_CLI} was installed to ${global_bin}." \
+      "  Add it to PATH if the command is not found:" \
+      "    export PATH=\"${global_bin}:\$PATH\""
+  fi
+}
+
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --dry-run)
@@ -137,14 +183,9 @@ require_cmd npm
 
 NODE_VERSION="$(node --version 2>/dev/null || true)"
 NPM_VERSION="$(npm --version 2>/dev/null || true)"
-
-if command -v npx >/dev/null 2>&1; then
-  RUNNER="npx"
-  RUN_CMD="npx --yes ${PACKAGE}@${VERSION} setup ${SETUP_MODE}${SETUP_EXTRA:+ ${SETUP_EXTRA}}"
-else
-  RUNNER="npm-exec"
-  RUN_CMD="npm exec --yes --package=${PACKAGE}@${VERSION} -- ${PREFERRED_CLI} setup ${SETUP_MODE}${SETUP_EXTRA:+ ${SETUP_EXTRA}}"
-fi
+GLOBAL_SPEC="$(resolve_global_spec)"
+GLOBAL_INSTALL_CMD="npm install -g ${GLOBAL_SPEC}"
+SETUP_CMD="${PREFERRED_CLI} setup ${SETUP_MODE}${SETUP_EXTRA:+ ${SETUP_EXTRA}}"
 
 printf '%s\n' \
   "Kairo Runtime bootstrap installer" \
@@ -153,13 +194,13 @@ printf '%s\n' \
   "Prerequisites:" \
   "  node  ${NODE_VERSION:-unknown}" \
   "  npm   ${NPM_VERSION:-unknown}" \
-  "  runner ${RUNNER}" \
   "" \
   "Will run:" \
-  "  ${RUN_CMD}" \
+  "  ${GLOBAL_INSTALL_CMD}" \
+  "  ${SETUP_CMD}" \
   "" \
   "Effects:" \
-  "  - Downloads/runs ${PACKAGE}@${VERSION} via npm (no global install required)." \
+  "  - Installs ${GLOBAL_SPEC} globally (kairo CLI in npm global bin)." \
   "  - Configures managed sections only (never installs AI apps)." \
   "  - Never uses sudo or modifies shell profiles." \
   ""
@@ -181,19 +222,25 @@ if [ "$INSTALLER_DRY_RUN" -eq 1 ]; then
   exit 0
 fi
 
+printf '%s\n' "Installing global CLI..." ""
+# shellcheck disable=SC2086
+npm install -g ${GLOBAL_SPEC}
+
+KAIRO_BIN="$(resolve_kairo_bin || true)"
+if [ -z "$KAIRO_BIN" ]; then
+  die "Installed ${GLOBAL_SPEC}, but ${PREFERRED_CLI} is not available.
+Check npm global bin: $(resolve_npm_global_bin || echo unknown)
+Add it to PATH, then re-run: ${SETUP_CMD}"
+fi
+
 if [ "$APPLY" -eq 1 ]; then
   printf '%s\n' "Applying setup..." ""
 else
   printf '%s\n' "Running preview..." ""
 fi
 
-if [ "$RUNNER" = "npx" ]; then
-  # shellcheck disable=SC2086
-  npx --yes "${PACKAGE}@${VERSION}" setup ${SETUP_MODE} ${SETUP_EXTRA}
-else
-  # shellcheck disable=SC2086
-  npm exec --yes --package="${PACKAGE}@${VERSION}" -- ${PREFERRED_CLI} setup ${SETUP_MODE} ${SETUP_EXTRA}
-fi
+# shellcheck disable=SC2086
+"$KAIRO_BIN" setup ${SETUP_MODE} ${SETUP_EXTRA}
 
 if [ "$APPLY" -eq 1 ]; then
   printf '%s\n' \
@@ -202,24 +249,25 @@ if [ "$APPLY" -eq 1 ]; then
     "Next steps:" \
     "  1. Check health:    ${PREFERRED_CLI} status" \
     "  2. Repair drift:    ${PREFERRED_CLI} sync" \
-    "  3. Upgrade latest:  npx ${PACKAGE}@latest setup --yes" \
+    "  3. Upgrade latest:  ${PREFERRED_CLI} upgrade --dry-run" \
     "" \
     "Version:" \
-    "  Installed CLI:      npx ${PACKAGE} --version" \
-    "  Published package:  npm view ${PACKAGE} version" \
-    "  Preview upgrade:    ${PREFERRED_CLI} upgrade --dry-run"
+    "  Installed CLI:      ${PREFERRED_CLI} --version" \
+    "  Published package:  npm view ${PACKAGE} version"
+  print_path_hint_if_needed
 else
   printf '%s\n' \
     "" \
     "Bootstrap complete." \
     "Next steps:" \
-    "  1. Apply the plan:  npx ${PACKAGE}@${VERSION} setup --yes" \
+    "  1. Apply the plan:  ${PREFERRED_CLI} setup --yes" \
     "     (or re-run installer: curl ... | sh -s -- --yes)" \
-    "  2. Check health:    npx ${PACKAGE}@${VERSION} status" \
-    "  3. Repair drift:    npx ${PACKAGE}@${VERSION} sync" \
+    "  2. Check health:    ${PREFERRED_CLI} status" \
+    "  3. Repair drift:    ${PREFERRED_CLI} sync" \
     "" \
     "Version:" \
-    "  Installed CLI:      npx ${PACKAGE} --version" \
+    "  Installed CLI:      ${PREFERRED_CLI} --version" \
     "  Published package:  npm view ${PACKAGE} version" \
-    "  Update / converge:  npx ${PACKAGE}@latest sync"
+    "  Update / converge:  ${PREFERRED_CLI} sync"
+  print_path_hint_if_needed
 fi

package/scripts/installer-smoke-test.sh

@@ -4,7 +4,9 @@ set -euo pipefail
 PACKAGE="@kal-elsam/kairo-runtime"
 PREFERRED_CLI="kairo"
 VERSION="latest"
+GIT_TAG=""
 REPO="Kal-elSam/harness"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -24,6 +26,14 @@ while [ "$#" -gt 0 ]; do
       VERSION="${1#*=}"
       shift
       ;;
+    --tag)
+      GIT_TAG="$2"
+      shift 2
+      ;;
+    --tag=*)
+      GIT_TAG="${1#*=}"
+      shift
+      ;;
     *)
       echo "Unknown option: $1" >&2
       exit 1
@@ -53,12 +63,13 @@ assert_harness_home_isolated() {
 }
 
 resolve_install_script_url() {
-  if [ "$VERSION" = "latest" ]; then
-    printf '%s\n' "https://raw.githubusercontent.com/${REPO}/main/scripts/install.sh"
-    return
+  local args=(--version "$VERSION" --repo "$REPO")
+
+  if [ -n "$GIT_TAG" ]; then
+    args+=(--tag "$GIT_TAG")
   fi
 
-  printf '%s\n' "https://raw.githubusercontent.com/${REPO}/v${VERSION}/scripts/install.sh"
+  node "${SCRIPT_DIR}/lib/install-script-url.mjs" "${args[@]}"
 }
 
 assert_no_harness_state() {
@@ -117,6 +128,9 @@ cd "$WORKDIR"
 
 INSTALL_SCRIPT_URL="$(resolve_install_script_url)"
 echo "Installer smoke for ${PACKAGE}@${VERSION}"
+if [ -n "$GIT_TAG" ]; then
+  echo "Git tag: ${GIT_TAG}"
+fi
 echo "Install script: ${INSTALL_SCRIPT_URL}"
 echo "Harness home: ${HARNESS_HOME}"
 
@@ -140,15 +154,36 @@ if [ ! -d "$FAKE_HOME/.harness" ]; then
   exit 1
 fi
 
+NPM_GLOBAL_BIN="$(npm prefix -g 2>/dev/null)/bin"
+export PATH="${NPM_GLOBAL_BIN}:${PATH}"
+
+resolve_kairo_bin() {
+  if command -v "$PREFERRED_CLI" >/dev/null 2>&1; then
+    command -v "$PREFERRED_CLI"
+    return 0
+  fi
+  if [ -x "${NPM_GLOBAL_BIN}/${PREFERRED_CLI}" ]; then
+    printf '%s\n' "${NPM_GLOBAL_BIN}/${PREFERRED_CLI}"
+    return 0
+  fi
+  return 1
+}
+
+KAIRO_BIN="$(resolve_kairo_bin || true)"
+if [ -z "$KAIRO_BIN" ]; then
+  echo "Expected ${PREFERRED_CLI} after install.sh global install" >&2
+  exit 1
+fi
+
 echo
 echo "== ${PREFERRED_CLI} status --json =="
-STATUS_JSON="$(npx --yes "${PACKAGE}@${VERSION}" status --json)"
+STATUS_JSON="$("$KAIRO_BIN" status --json)"
 echo "$STATUS_JSON"
 assert_status_ok "$STATUS_JSON"
 
 echo
 echo "== ${PREFERRED_CLI} uninstall =="
-npx --yes "${PACKAGE}@${VERSION}" uninstall
+"$KAIRO_BIN" uninstall
 assert_managed_configs_removed
 
 echo

package/scripts/lib/install-script-url.mjs

@@ -0,0 +1,85 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const DEFAULT_REPO = "Kal-elSam/harness";
+
+export function resolveInstallScriptRef({ version, tag = null }) {
+  if (version === "latest") {
+    return "main";
+  }
+
+  if (tag) {
+    return tag;
+  }
+
+  return `v${version}`;
+}
+
+export function resolveInstallScriptUrl({
+  repo = DEFAULT_REPO,
+  version,
+  tag = null
+}) {
+  const ref = resolveInstallScriptRef({ version, tag });
+  return `https://raw.githubusercontent.com/${repo}/${ref}/scripts/install.sh`;
+}
+
+export function parseInstallScriptUrlArgs(argv) {
+  const args = [...argv];
+  let version = "latest";
+  let tag = null;
+  let repo = DEFAULT_REPO;
+
+  for (let index = 2; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--version") {
+      version = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--version=")) {
+      version = arg.slice("--version=".length);
+      continue;
+    }
+
+    if (arg === "--tag") {
+      tag = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--tag=")) {
+      tag = arg.slice("--tag=".length);
+      continue;
+    }
+
+    if (arg === "--repo") {
+      repo = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--repo=")) {
+      repo = arg.slice("--repo=".length);
+      continue;
+    }
+
+    throw new Error(`Unknown option "${arg}".`);
+  }
+
+  return { version, tag, repo };
+}
+
+function isMainModule() {
+  const entry = process.argv[1];
+
+  if (!entry) {
+    return false;
+  }
+
+  return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(entry);
+}
+
+if (isMainModule()) {
+  const { version, tag, repo } = parseInstallScriptUrlArgs(process.argv);
+  console.log(resolveInstallScriptUrl({ repo, version, tag }));
+}

package/src/cli.js

@@ -31,51 +31,21 @@ import { applyPolicyToOptions, loadPolicyFile } from "./global/policy.js";
 import { resolveHomeDir } from "./global/paths.js";
 import { runWorkspaceDetect, runWorkspaceDoctor, runWorkspaceInit, runWorkspaceUpdate } from "./workspace-cli.js";
 import {
-  ALL_CLI_NAMES,
   LEGACY_PACKAGE_NAME,
   PACKAGE_NAME,
   PREFERRED_CLI,
   formatCliCommand,
-  maybeWarnLegacyCli
+  maybeWarnLegacyCli,
+  resolveSuggestedInvocation
 } from "./global/brand/cli.js";
 import { BRAND } from "./global/brand/index.js";
 
+export { resolveSuggestedInvocation };
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, "..");
 const SCOPES = new Set(["agent-global", "workspace"]);
 
-export function resolveSuggestedInvocation(packageName, argv = process.argv) {
-  const invokedPath = argv[1] ?? PREFERRED_CLI;
-  const invokedBase = basename(invokedPath);
-
-  if (!invokedBase.endsWith(".js") && ALL_CLI_NAMES.has(invokedBase)) {
-    return invokedBase;
-  }
-
-  const packageManager = detectInvocationPackageManager();
-
-  switch (packageManager) {
-    case "pnpm":
-      return `pnpm dlx ${packageName}`;
-    case "yarn":
-      return `yarn dlx ${packageName}`;
-    case "bun":
-      return `bunx ${packageName}`;
-    default:
-      return `npx ${packageName}`;
-  }
-}
-
-function detectInvocationPackageManager() {
-  const execPath = process.env.npm_execpath ?? "";
-  const userAgent = process.env.npm_config_user_agent ?? "";
-
-  if (execPath.includes("pnpm") || userAgent.startsWith("pnpm/")) return "pnpm";
-  if (execPath.includes("yarn") || userAgent.startsWith("yarn/")) return "yarn";
-  if (execPath.includes("bun") || userAgent.startsWith("bun/")) return "bun";
-  return "npm";
-}
-
 export async function runCli(argv) {
   const { command, options } = parseArgs(argv);
   maybeWarnLegacyCli(process.argv, { json: options.json });

package/src/global/brand/cli.js

@@ -50,3 +50,44 @@ export function formatCliCommand(subcommand, cliName = PREFERRED_CLI) {
   const trimmed = subcommand.trim();
   return trimmed ? `${cliName} ${trimmed}` : cliName;
 }
+
+function detectInvocationPackageManager() {
+  const execPath = process.env.npm_execpath ?? "";
+  const userAgent = process.env.npm_config_user_agent ?? "";
+
+  if (execPath.includes("pnpm") || userAgent.startsWith("pnpm/")) return "pnpm";
+  if (execPath.includes("yarn") || userAgent.startsWith("yarn/")) return "yarn";
+  if (execPath.includes("bun") || userAgent.startsWith("bun/")) return "bun";
+  return "npm";
+}
+
+export function resolveSuggestedInvocation(packageName = PACKAGE_NAME, argv = process.argv) {
+  const invokedPath = argv[1] ?? PREFERRED_CLI;
+  const invokedBase = basename(invokedPath);
+
+  if (!invokedBase.endsWith(".js") && ALL_CLI_NAMES.has(invokedBase)) {
+    return invokedBase;
+  }
+
+  const packageManager = detectInvocationPackageManager();
+
+  switch (packageManager) {
+    case "pnpm":
+      return `pnpm dlx ${packageName}`;
+    case "yarn":
+      return `yarn dlx ${packageName}`;
+    case "bun":
+      return `bunx ${packageName}`;
+    default:
+      return `npx ${packageName}`;
+  }
+}
+
+export function formatSuggestedCliCommand(
+  subcommand,
+  { packageName = PACKAGE_NAME, argv = process.argv, suggestedInvocation } = {}
+) {
+  const invoke = suggestedInvocation ?? resolveSuggestedInvocation(packageName, argv);
+  const trimmed = subcommand.trim();
+  return trimmed ? `${invoke} ${trimmed}` : invoke;
+}

package/src/global/brand/index.js

@@ -82,4 +82,10 @@ export function commandHeader(label) {
   return `${BRAND.displayName} ${label}`;
 }
 
-export { formatCliCommand, PREFERRED_CLI } from "./cli.js";
+export {
+  formatCliCommand,
+  formatSuggestedCliCommand,
+  PACKAGE_NAME,
+  PREFERRED_CLI,
+  resolveSuggestedInvocation
+} from "./cli.js";

package/src/global/ink/setup-state.js

@@ -1,4 +1,4 @@
-import { AGENT_HINTS, BRAND, PREFERRED_CLI, formatCliCommand, getAgentLabel, WIZARD_COPY } from "../brand/index.js";
+import { AGENT_HINTS, BRAND, formatCliCommand, getAgentLabel, PREFERRED_CLI, WIZARD_COPY } from "../brand/index.js";
 import { formatAgentMultiselectHint } from "../clack/theme.js";
 
 export const SETUP_STEPS = {