@osfactory/har 1.0.0-rc.2 → 1.0.0

package/dist/templates/profiles/default/docs/readme/port-shared-services.md

@@ -12,7 +12,7 @@
 | Mailpit | Per machine | `HARNESS_MAILPIT_*_PORT_DEFAULT` | Scan configured ranges |
 | Headless browser | Per machine | `HARNESS_BROWSER_PORT_DEFAULT` | Scan configured ranges |
 
-Resolved ports may differ from the formula when something else is already bound. Always use `./.har/agent-cli.sh <id>` or read `.har/slots/agent-<id>.json` — never hardcode `3010`, `15432`, etc. in app code or tests.
+Resolved ports may differ from the formula when something else is already bound. Always use `har env agent <id>` or read `.har/slots/agent-<id>.json` — never hardcode `3010`, `15432`, etc. in app code or tests.
 
 ### Shared vs per-slot
 
@@ -24,18 +24,18 @@ Resolved ports may differ from the formula when something else is already bound.
 | Primary application | One PM2 ecosystem per slot (isolated ports) | `HARNESS_PRIMARY_APP`, `ecosystem.agent.template.cjs` |
 | Internal supporting services | Shared across all slots | `docker-compose.agent.yml` or `ecosystem.shared.config.cjs` |
 
-Shared infra starts once via `./.har/setup-infra.sh` (also run automatically by `launch.sh`). Per-slot databases are cloned in `launch.sh`.
+Shared infra starts once via `har env setup-infra` (also run automatically by `har env launch`). Per-slot databases are cloned in `har env launch`.
 
 ### Do not
 
 - Hardcode default ports (`3000`, `15432`, `3847`, …) in application code, tests, or agent docs — read from `.env.agent.<id>`, `agent-cli.sh`, or the slot registry
-- Run raw `docker compose` for harness infrastructure — use `setup-infra.sh` / `launch.sh` so ports are scanned and persisted in `.har/state/infra.env`
+- Run raw `docker compose` for harness infrastructure — use `har env setup-infra` / `har env launch` so ports are scanned and persisted in `.har/state/infra.env`
 
 ### Primary app vs shared services
 
 Each slot runs **only the primary application** (`HARNESS_PRIMARY_APP` in `harness.env`) — the app agents modify. Everything else runs **once**, shared by all slots on fixed ports:
 
-- **External dependencies** (Postgres, Redis, mail, ...): services in `docker-compose.agent.yml`, enabled via the `HARNESS_INFRA_SERVICES` list in `harness.env`, started by `setup-infra.sh`.
-- **Internal supporting services** (other services of a monolith/monorepo the agent depends on but does not change): either compose services in `docker-compose.agent.yml`, or PM2 processes in an optional `.har/ecosystem.shared.config.cjs` (named `har-shared-<name>`, started by `setup-infra.sh`).
+- **External dependencies** (Postgres, Redis, mail, ...): services in `docker-compose.agent.yml`, enabled via the `HARNESS_INFRA_SERVICES` list in `harness.env`, started by `har env setup-infra`.
+- **Internal supporting services** (other services of a monolith/monorepo the agent depends on but does not change): either compose services in `docker-compose.agent.yml`, or PM2 processes in an optional `.har/ecosystem.shared.config.cjs` (named `har-shared-<name>`, started by `har env setup-infra`).
 
 Isolation still applies where it matters: each slot gets its own database (`agent_<id>`, cloned from the template DB), ports, and git worktree.

package/dist/templates/profiles/default/docs/readme/quick-start.md

@@ -11,14 +11,8 @@ har env teardown 1
 
 In Cursor with HAR MCP configured: use `har_launch_environment`, `har_run_verification`, and `har_teardown_environment`.
 
-**Shell shims** (same runtime — each `./.har/*.sh` forwards to `har env`, with a pinned `npx @osfactory/har` fallback):
-
-```bash
-./.har/setup-infra.sh          # when HARNESS_INFRA_SERVICES is non-empty
-./.har/launch.sh 1
-./.har/verify.sh 1             # quick: ecosystem smoke + health
-./.har/verify.sh 1 --full      # + conventional tests/lint, browser-e2e (if installed)
-./.har/teardown.sh 1
-```
+`./.har/*.sh` exist as compatibility shims over the same runtime — generated,
+never edited, and not the way to drive the harness. Take explicit ownership of
+them with `har env eject`.
 
 Read **`stages.json`** for registered stages and **`verificationStages`** for the expected pass set.

package/dist/templates/profiles/default/docs/readme/readiness-layers.md

@@ -5,10 +5,10 @@ section for the repository:
 
 | Layer | What it means | Where to encode it |
 |-------|---------------|--------------------|
-| Infra ready | Shared services and template data stores exist | `setup-infra.sh`, `docker-compose.agent.yml` |
-| Slot data ready | Every per-slot data store is created/cloned | `launch.sh` |
-| Process ready | Primary app is running and health passes | `launch.sh`, `verify.sh` |
-| Agent usable | Login/API/UI smoke works with documented data | `HARNESS_READINESS_CMD`, browser-e2e, `CLAUDE.agent.md` |
+| Infra ready | Shared services and template data stores exist | `har env setup-infra`, `docker-compose.agent.yml` |
+| Slot data ready | Every per-slot data store is created/cloned | `har env launch` |
+| Process ready | Primary app is running and health passes | `har env launch`, `har env verify` |
+| Agent usable | Login/API/UI smoke works with documented data | `HARNESS_READINESS_CMD`, browser-e2e, `.har/README.md` |
 
 If full local-dev setup is too heavy to run in the harness, document the skipped
 steps and add the minimum substitute directly in `.har/` scripts (for example an

package/dist/templates/profiles/default/docs/{claude-agent → readme}/readiness.md

@@ -3,7 +3,7 @@
 Adapt this section for the repository. A passing health check means the process
 is alive; it does not automatically mean an agent can use the app.
 
-- **Health**: `./.har/agent-cli.sh ${AGENT_ID} health`
+- **Health**: `har env agent <id> health`
 - **Agent-usable smoke**: document the login/API/UI workflow agents should try,
   or wire it into `HARNESS_READINESS_CMD` / full verify.
 - **Credentials/default data**: document any test users, tenants, projects, or

package/dist/templates/profiles/default/docs/readme/verification-contract.md

@@ -1,6 +1,6 @@
 ## Verification contract
 
-Steps in `verify.sh` are **project-specific examples** — adapt them to your stack
+Steps in `har env verify` are **project-specific examples** — adapt them to your stack
 during `har env init` / `har env maintain`. The table describes each tier's intent,
 not a fixed command list.
 

package/dist/templates/profiles/default/docs/readme/what-s-in-here.md

@@ -14,7 +14,7 @@
 | `ecosystem.agent.template.cjs` | PM2 processes for the **primary app only** (expanded at launch) |
 | `ecosystem.shared.config.cjs` | Optional — shared app services started once with the infra (only when the repo has supporting services) |
 | `docker-compose.agent.yml` | Shared infrastructure containers (services listed in `HARNESS_INFRA_SERVICES`) |
-| `CLAUDE.agent.md` | Detailed instructions for coding agents |
+| `.har/README.md` | Detailed instructions for coding agents |
 | `STAGES.md` | Stage registry and script-contract guide |
 | `justfile` | Optional shortcuts (requires `just`) |
 
@@ -22,7 +22,7 @@
 
 | File | Purpose |
 |------|---------|
-| `launch.sh` / `verify.sh` / `teardown.sh` / `setup-infra.sh` / `preflight.sh` / `agent-cli.sh` / `attach.sh` | Thin shims forwarding to the packaged runtime (`har env …`); same run records on every surface |
+| `har env launch` / `har env verify` / `har env teardown` / `har env setup-infra` / `preflight.sh` / `agent-cli.sh` / `attach.sh` | Thin shims forwarding to the packaged runtime (`har env …`); same run records on every surface |
 | `manifest.json` | Runtime version, profile, checksums — managed by the har CLI |
 | `runs/` | Run history from every entry point — `.har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json` (gitignored) |
 | `artifacts/` | Stage outputs: reports, traces, screenshots, logs |

package/dist/templates/profiles/default/profile.manifest.json

@@ -1,16 +1,27 @@
 {
   "id": "default",
-  "description": "Web app — shared kernel + PM2 runtime + Docker infra",
+  "description": "Web app \u2014 shared kernel + PM2 runtime + Docker infra",
   "bundles": [
-    { "id": "shared-kernel", "path": "runtime-bundles/shared-kernel" },
-    { "id": "pm2-runtime", "path": "runtime-bundles/pm2-runtime" },
-    { "id": "runtime-default", "path": "har-boilerplate" }
+    {
+      "id": "shared-kernel",
+      "path": "runtime-bundles/shared-kernel"
+    },
+    {
+      "id": "pm2-runtime",
+      "path": "runtime-bundles/pm2-runtime"
+    },
+    {
+      "id": "runtime-default",
+      "path": "har-boilerplate"
+    }
   ],
   "capabilities": {
     "processManager": "pm2",
     "appPortLanes": true,
     "infra": {
-      "defaultServices": ["db"],
+      "defaultServices": [
+        "db"
+      ],
       "portLanes": "db=15432:15432-15499 minio=19000:19000-19049 minio-console=19050:19050-19099 browser=13001:13001-13099 mailpit-web=18025:18025-18099 mailpit-smtp=11025:11025-11099"
     },
     "defaultStages": [
@@ -49,22 +60,19 @@
       "intro",
       "what-s-in-here",
       "quick-start",
+      "environment",
       "verification-contract",
+      "definition-of-done",
+      "readiness",
       "readiness-layers",
       "run-history",
       "for-coding-agents",
+      "project-commands",
       "architecture",
       "port-shared-services",
+      "do-not",
       "maintaining-this-harness",
       "session-lifecycle"
-    ],
-    "CLAUDE.agent.md": [
-      "intro",
-      "environment",
-      "readiness",
-      "definition-of-done",
-      "project-commands",
-      "do-not"
     ]
   }
 }

package/dist/templates/profiles/ios/docs/{claude-agent → readme}/definition-of-done.md

@@ -1,12 +1,12 @@
 ## Definition of done
 
-- [ ] Full verification returns `"status": "pass"` (`har env verify ${AGENT_ID} --full`, MCP `har_run_verification` with `full: true`, or `./.har/verify.sh ${AGENT_ID} --full`)
+- [ ] Full verification returns `"status": "pass"` (`har env verify <id> --full`, MCP `har_run_verification` with `full: true`, or `har env verify <id> --full`)
 - [ ] The slot is agent-usable for this repo's documented smoke workflow when runtime services are involved
 - [ ] When `stages/rocketsim-flows.sh` exists, full verify includes user-flow validation — add or update flow scripts in `flows/` for UI changes
 - [ ] New behavior has automated test coverage (unit tests via XCTest)
 - [ ] Changes committed **in the session worktree** with a clear message
 - [ ] Present session handoff (summary, branch, preview URLs) and **wait for user** before `complete`, push, or PR
-- [ ] On user approval of the default: push + open PR (when `gh`/GitHub MCP available), then `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — full verify + validation + teardown, branch kept
+- [ ] On user approval of the default: push + open PR (when `gh`/GitHub MCP available), then `har env complete <id>` (or MCP `har_complete_environment`) — full verify + validation + teardown, branch kept
 
 ### Session handoff
 
@@ -18,6 +18,6 @@ else as alternatives. If PR tooling is unavailable, recommend complete and repor
 the session branch for a manual push. Prefer `complete` over bare `teardown` when
 the work succeeded. See `.cursor/rules/har-workflow.mdc` for the handoff shape.
 
-Quick loop: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}`
+Quick loop: MCP `har_run_verification`, `har env verify <id>`, or `har env verify <id>`
 
 Stages are the harness's single vocabulary for checks: templates and custom stages compile to generic kinds in `.har/stages.json`, and you interact with them only through the registry (`har_run_stage`, `verify`), never stack-specific tooling. Authoring guide: `.har/STAGES.md`.

package/dist/templates/profiles/ios/docs/{claude-agent → readme}/do-not.md

@@ -1,6 +1,6 @@
 ## Do not
 
 - Work around a failing harness command with ad-hoc setup — fix the harness or report the failure
-- Edit `.env.agent.${AGENT_ID}` by hand
+- Edit `.env.agent.<id>` by hand
 - Run verify before launch (the simulator and worktree must be set up first)
 - Edit the main checkout — all edits go under the session work dir

package/dist/templates/profiles/ios/docs/{claude-agent → readme}/environment.md

@@ -2,13 +2,13 @@
 
 | | |
 |--|--|
-| **Agent ID** | ${AGENT_ID} |
-| **Work dir** | Fresh session worktree per launch — see the launch output or `.har/slots/agent-${AGENT_ID}.json` |
-| **Simulator** | Created for this slot at launch — `HARNESS_SIMULATOR_UDID` in `.env.agent.${AGENT_ID}` |
+| **Agent ID** | <id> |
+| **Work dir** | Fresh session worktree per launch — see the launch output or `.har/slots/agent-<id>.json` |
+| **Simulator** | Created for this slot at launch — `HARNESS_SIMULATOR_UDID` in `.env.agent.<id>` |
 | **Scheme** | Configured in `.har/harness.env` — `HARNESS_XCODE_SCHEME` |
 
 **Never edit the main checkout** — launch FIRST, then make ALL file edits under the work dir from the launch output. An occupied slot always blocks a new launch — run `har env teardown <id>` (or `complete <id>`) first, then launch again.
 
 ```bash
-./.har/agent-cli.sh ${AGENT_ID} status
+har env agent <id> status
 ```

package/dist/templates/profiles/ios/docs/readme/port-shared-services-ios-profile.md

@@ -9,17 +9,17 @@ Pure iOS apps have **no per-slot TCP ports** — agents build and run on a share
 | Optional backend (compose) | Per machine | `HARNESS_*_PORT_DEFAULT` for that service | Scan configured ranges in `harness.env` |
 | iOS Simulator | Per slot | One device created per agent — no harness port | None: `har-<project>-agent-<id>-<model>` is unique per slot |
 
-When your app talks to a local backend, read the resolved host port from `.env.agent.<id>` (set by `setup-infra.sh`) — never hardcode `15432` or similar in tests or flow scripts.
+When your app talks to a local backend, read the resolved host port from `.env.agent.<id>` (set by `har env setup-infra`) — never hardcode `15432` or similar in tests or flow scripts.
 
 ### Shared vs per-slot
 
 | Resource | Model | Configuration |
 |----------|-------|---------------|
-| iOS Simulator | One device created per slot, deleted at teardown | `HARNESS_SIMULATOR_*`, `launch.sh` |
+| iOS Simulator | One device created per slot, deleted at teardown | `HARNESS_SIMULATOR_*`, `har env launch` |
 | Optional backend | One shared compose service | `HARNESS_INFRA_SERVICES` (e.g. `"mock-server"`) |
 | Application code | Isolated git worktree per slot | `HARNESS_USE_WORKTREE=true` |
 
 ### Do not
 
 - Hardcode backend ports in RocketSim flows or unit tests — read from agent env
-- Run raw `docker compose` for harness infrastructure — use `setup-infra.sh`
+- Run raw `docker compose` for harness infrastructure — use `har env setup-infra`

package/dist/templates/profiles/ios/docs/{claude-agent → readme}/project-commands.md

@@ -2,10 +2,10 @@
 
 Target **this slot's** simulator, never `booted` — another agent's device may also
 be booted. `HARNESS_IOS_DESTINATION` and `HARNESS_SIMULATOR_UDID` come from
-`.env.agent.${AGENT_ID}`.
+`.env.agent.<id>`.
 
 ```bash
-source .env.agent.${AGENT_ID}
+source .env.agent.<id>
 
 # Build
 xcodebuild build -scheme MyApp -destination "$HARNESS_IOS_DESTINATION" CODE_SIGNING_ALLOWED=NO
@@ -14,8 +14,8 @@ xcodebuild build -scheme MyApp -destination "$HARNESS_IOS_DESTINATION" CODE_SIGN
 xcodebuild test -scheme MyApp -destination "$HARNESS_IOS_DESTINATION"
 
 # Install and launch on this slot's device
-./.har/agent-cli.sh ${AGENT_ID} install path/to/MyApp.app
-./.har/agent-cli.sh ${AGENT_ID} launch-app
+har env agent <id> install path/to/MyApp.app
+har env agent <id> launch-app
 ```
 
 Adapt for your scheme — see `.har/harness.env`.

package/dist/templates/profiles/ios/docs/readme/quick-start.md

@@ -11,12 +11,6 @@ har env teardown 1
 
 In Cursor with HAR MCP configured: use `har_launch_environment`, `har_run_verification`, and `har_teardown_environment`.
 
-**Shell shims** (same runtime — each `./.har/*.sh` forwards to `har env`, with a pinned `npx @osfactory/har` fallback):
-
-```bash
-./.har/setup-infra.sh          # boots the iOS Simulator
-./.har/launch.sh 1
-./.har/verify.sh 1             # quick: build smoke (compile-only)
-./.har/verify.sh 1 --full      # + unit tests, lint, rocketsim-flows (if installed)
-./.har/teardown.sh 1
-```
+`./.har/*.sh` exist as compatibility shims over the same runtime — generated,
+never edited, and not the way to drive the harness. Take explicit ownership of
+them with `har env eject`.

package/dist/templates/profiles/ios/docs/readme/simulators.md

@@ -12,7 +12,7 @@ store, nothing carried over from the previous session.
 | `HARNESS_SIMULATOR_NAME` | The model to create — `iPhone 16`, `iPhone 17 Pro`, `iPad Air 11-inch (M2)`. Empty means the newest model of the family. See `xcrun simctl list devicetypes`. |
 | `HARNESS_SIMULATOR_FAMILY` | `auto` (read from the name) \| `iPhone` \| `iPad`. An iPad is only created when this resolves to iPad. |
 | `HARNESS_SIMULATOR_UDID` | Run every slot on one existing device instead. Slots then share it — for one-off debugging. |
-| `HARNESS_SIMULATOR_SHARED` | `true` restores one shared simulator for all slots, booted by `setup-infra.sh`. |
+| `HARNESS_SIMULATOR_SHARED` | `true` restores one shared simulator for all slots, booted by `har env setup-infra`. |
 
 The runtime is the newest installed iOS that supports the model — a model retired
 from recent runtimes still resolves against an older one. When nothing matches,
@@ -42,4 +42,4 @@ blaming a sandbox.
 The device lands in `.env.agent.<id>` as `HARNESS_SIMULATOR_UDID`,
 `HARNESS_SIMULATOR_DEVICE_NAME` and `HARNESS_IOS_DESTINATION` — the model stays in
 `HARNESS_SIMULATOR_NAME`, so the two never mean the same thing in one place; what a slot holds is tracked in `.har/simulators/`.
-Use `./.har/agent-cli.sh <id> simulator` to see it.
+Use `har env agent <id> simulator` to see it.

package/dist/templates/profiles/ios/docs/{claude-agent → readme}/user-flow-validation-rocketsim.md

@@ -3,9 +3,9 @@
 If the RocketSim plugin is installed (`har env add-plugin rocketsim`):
 
 ```bash
-./.har/stages/rocketsim-flows.sh ${AGENT_ID}
+./.har/stages/rocketsim-flows.sh <id>
 # included in:
-./.har/verify.sh ${AGENT_ID} --full
+har env verify <id> --full
 ```
 
 Add and edit user flow scripts in `flows/`. Read `.har/stages/ROCKETSIM.md` for the full authoring guide.

package/dist/templates/profiles/ios/docs/readme/verification-contract.md

@@ -1,6 +1,6 @@
 ## Verification contract
 
-Steps in `verify.sh` are **project-specific examples** — adapt them to your stack.
+Steps in `har env verify` are **project-specific examples** — adapt them to your stack.
 The table describes each tier's intent, not a fixed command list.
 
 | Mode | Command | Typical steps |

package/dist/templates/profiles/ios/docs/readme/what-s-in-here.md

@@ -11,7 +11,7 @@
 | `hooks/` | Optional lifecycle hooks (`pre-launch.sh`, `post-launch.sh`, `pre-verify.sh`, `pre-teardown.sh`, `post-teardown.sh`) |
 | `plugins/` | Optional local plugins (`har plugin create <id>`) |
 | `docker-compose.agent.yml` | Optional shared backend services |
-| `CLAUDE.agent.md` | Detailed instructions for coding agents |
+| `.har/README.md` | Detailed instructions for coding agents |
 | `STAGES.md` | Stage registry and script-contract guide |
 | `justfile` | Optional shortcuts (requires `just`) |
 
@@ -19,7 +19,7 @@
 
 | File | Purpose |
 |------|---------|
-| `launch.sh` / `verify.sh` / `teardown.sh` / `setup-infra.sh` / `preflight.sh` / `agent-cli.sh` | Thin shims forwarding to the packaged runtime (`har env …`); same run records on every surface |
+| `har env launch` / `har env verify` / `har env teardown` / `har env setup-infra` / `preflight.sh` / `agent-cli.sh` | Thin shims forwarding to the packaged runtime (`har env …`); same run records on every surface |
 | `manifest.json` | Runtime version, profile, checksums — managed by the har CLI |
 | `runs/` | Run history from every entry point — `.har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json` (gitignored) |
 | `artifacts/` | Stage outputs: test results, screenshots, logs |

package/dist/templates/profiles/ios/profile.manifest.json

@@ -1,9 +1,15 @@
 {
   "id": "ios",
-  "description": "iOS — shared kernel + Xcode/Simulator overlay (simulator runtime lives in the package)",
+  "description": "iOS \u2014 shared kernel + Xcode/Simulator overlay (simulator runtime lives in the package)",
   "bundles": [
-    { "id": "shared-kernel", "path": "runtime-bundles/shared-kernel" },
-    { "id": "runtime-ios", "path": "har-boilerplate-ios" }
+    {
+      "id": "shared-kernel",
+      "path": "runtime-bundles/shared-kernel"
+    },
+    {
+      "id": "runtime-ios",
+      "path": "har-boilerplate-ios"
+    }
   ],
   "capabilities": {
     "processManager": "simulator",
@@ -45,21 +51,18 @@
       "intro",
       "what-s-in-here",
       "quick-start",
+      "environment",
       "user-flow-validation",
       "verification-contract",
+      "definition-of-done",
+      "readiness",
+      "project-commands",
+      "user-flow-validation-rocketsim",
       "configuration",
       "simulators",
       "port-shared-services-ios-profile",
+      "do-not",
       "session-lifecycle"
-    ],
-    "CLAUDE.agent.md": [
-      "intro",
-      "environment",
-      "readiness",
-      "definition-of-done",
-      "project-commands",
-      "user-flow-validation-rocketsim",
-      "do-not"
     ]
   }
 }

package/dist/templates/runtime-bundles/pm2-runtime/attach.sh

@@ -5,11 +5,49 @@
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-AGENT_ID="${1:?Usage: attach.sh <agent-id>}"
-if command -v har >/dev/null 2>&1; then
-  exec har env agent "$AGENT_ID" attach
-elif [ -x "$REPO_ROOT/node_modules/.bin/har" ]; then
-  exec "$REPO_ROOT/node_modules/.bin/har" env agent "$AGENT_ID" attach
+# Loop guard (#291): a pre-1.0 har does not own this runtime kind in the
+# package — it executes this script as authoritative, which would exec back
+# into har forever (one node process per cycle). Trip on re-entry for this
+# harness root, and skip har binaries older than the pinned runtime (#298).
+HAR_SHIM_GUARD="attach@${REPO_ROOT}"
+case ":${HAR_SHIM_REENTRY:-}:" in *":${HAR_SHIM_GUARD}:"*)
+  echo "Error: runtime loop detected — the har CLI that ran this shim delegated back into it." >&2
+  echo "  The har runtime handling this repo is older than the harness contract (pinned: @osfactory/har@__HAR_VERSION__)." >&2
+  echo "  Fix: npm i -g @osfactory/har@latest    # or in this repo: npm i -D @osfactory/har" >&2
+  exit 86
+  ;;
+esac
+export HAR_SHIM_REENTRY="${HAR_SHIM_REENTRY:-}:${HAR_SHIM_GUARD}"
+# True when $1 reports a version >= the pinned runtime. Comparing only the
+# major (#298) made the floor inert for the whole 0.x line: every pre-1.0 har
+# passed it and then bounced straight back into this shim. Compare the full
+# release triple, and treat anything unparseable as unusable.
+har_runtime_compatible() {
+  local v pinned="__HAR_VERSION__" i a b
+  v="$("$1" --version 2>/dev/null | head -n1)" || return 1
+  v="${v#v}"
+  v="${v%%[-+ ]*}"
+  local -a have pin
+  IFS=. read -r -a have <<<"$v"
+  IFS=. read -r -a pin <<<"${pinned%%[-+]*}"
+  for i in 0 1 2; do
+    a="${have[i]:-0}"
+    b="${pin[i]:-0}"
+    case "$a" in ''|*[!0-9]*) return 1 ;; esac
+    case "$b" in ''|*[!0-9]*) return 1 ;; esac
+    [ "$a" -gt "$b" ] && return 0
+    [ "$a" -lt "$b" ] && return 1
+  done
+  return 0
+}
+# `$1` (not a named var) so `har env eject` can lift this delegate verbatim.
+if command -v har >/dev/null 2>&1 && har_runtime_compatible har; then
+  exec har env agent "${1:?Usage: attach.sh <agent-id>}" attach
+elif [ -x "$REPO_ROOT/node_modules/.bin/har" ] && har_runtime_compatible "$REPO_ROOT/node_modules/.bin/har"; then
+  exec "$REPO_ROOT/node_modules/.bin/har" env agent "${1:?Usage: attach.sh <agent-id>}" attach
+elif command -v npx >/dev/null 2>&1; then
+  exec npx --yes @osfactory/har@__HAR_VERSION__ env agent "${1:?Usage: attach.sh <agent-id>}" attach
 fi
-echo "Error: the 'har' CLI is not available. Install @osfactory/har (npm i -D @osfactory/har) or run: npx @osfactory/har env agent" >&2
+echo "Error: cannot run the HAR runtime — 'har' is not on PATH and Node.js (npx) is unavailable." >&2
+echo "  Install Node.js, then: npm i -D @osfactory/har   # or: npx @osfactory/har@__HAR_VERSION__ env agent" >&2
 exit 127

package/dist/templates/runtime-bundles/shared-kernel/agent-cli.sh

@@ -8,7 +8,7 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 # Loop guard (#291): a pre-1.0 har does not own this runtime kind in the
 # package — it executes this script as authoritative, which would exec back
 # into har forever (one node process per cycle). Trip on re-entry for this
-# harness root, and skip har binaries older than the pinned runtime's major.
+# harness root, and skip har binaries older than the pinned runtime (#298).
 HAR_SHIM_GUARD="agent@${REPO_ROOT}"
 case ":${HAR_SHIM_REENTRY:-}:" in *":${HAR_SHIM_GUARD}:"*)
   echo "Error: runtime loop detected — the har CLI that ran this shim delegated back into it." >&2
@@ -18,10 +18,27 @@ case ":${HAR_SHIM_REENTRY:-}:" in *":${HAR_SHIM_GUARD}:"*)
   ;;
 esac
 export HAR_SHIM_REENTRY="${HAR_SHIM_REENTRY:-}:${HAR_SHIM_GUARD}"
+# True when $1 reports a version >= the pinned runtime. Comparing only the
+# major (#298) made the floor inert for the whole 0.x line: every pre-1.0 har
+# passed it and then bounced straight back into this shim. Compare the full
+# release triple, and treat anything unparseable as unusable.
 har_runtime_compatible() {
-  local v pinned="__HAR_VERSION__"
+  local v pinned="__HAR_VERSION__" i a b
   v="$("$1" --version 2>/dev/null | head -n1)" || return 1
-  [ "${v%%.*}" -ge "${pinned%%.*}" ] 2>/dev/null
+  v="${v#v}"
+  v="${v%%[-+ ]*}"
+  local -a have pin
+  IFS=. read -r -a have <<<"$v"
+  IFS=. read -r -a pin <<<"${pinned%%[-+]*}"
+  for i in 0 1 2; do
+    a="${have[i]:-0}"
+    b="${pin[i]:-0}"
+    case "$a" in ''|*[!0-9]*) return 1 ;; esac
+    case "$b" in ''|*[!0-9]*) return 1 ;; esac
+    [ "$a" -gt "$b" ] && return 0
+    [ "$a" -lt "$b" ] && return 1
+  done
+  return 0
 }
 if command -v har >/dev/null 2>&1 && har_runtime_compatible har; then
   exec har env agent "$@"

package/dist/templates/runtime-bundles/shared-kernel/launch.sh

@@ -8,7 +8,7 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 # Loop guard (#291): a pre-1.0 har does not own this runtime kind in the
 # package — it executes this script as authoritative, which would exec back
 # into har forever (one node process per cycle). Trip on re-entry for this
-# harness root, and skip har binaries older than the pinned runtime's major.
+# harness root, and skip har binaries older than the pinned runtime (#298).
 HAR_SHIM_GUARD="launch@${REPO_ROOT}"
 case ":${HAR_SHIM_REENTRY:-}:" in *":${HAR_SHIM_GUARD}:"*)
   echo "Error: runtime loop detected — the har CLI that ran this shim delegated back into it." >&2
@@ -18,10 +18,27 @@ case ":${HAR_SHIM_REENTRY:-}:" in *":${HAR_SHIM_GUARD}:"*)
   ;;
 esac
 export HAR_SHIM_REENTRY="${HAR_SHIM_REENTRY:-}:${HAR_SHIM_GUARD}"
+# True when $1 reports a version >= the pinned runtime. Comparing only the
+# major (#298) made the floor inert for the whole 0.x line: every pre-1.0 har
+# passed it and then bounced straight back into this shim. Compare the full
+# release triple, and treat anything unparseable as unusable.
 har_runtime_compatible() {
-  local v pinned="__HAR_VERSION__"
+  local v pinned="__HAR_VERSION__" i a b
   v="$("$1" --version 2>/dev/null | head -n1)" || return 1
-  [ "${v%%.*}" -ge "${pinned%%.*}" ] 2>/dev/null
+  v="${v#v}"
+  v="${v%%[-+ ]*}"
+  local -a have pin
+  IFS=. read -r -a have <<<"$v"
+  IFS=. read -r -a pin <<<"${pinned%%[-+]*}"
+  for i in 0 1 2; do
+    a="${have[i]:-0}"
+    b="${pin[i]:-0}"
+    case "$a" in ''|*[!0-9]*) return 1 ;; esac
+    case "$b" in ''|*[!0-9]*) return 1 ;; esac
+    [ "$a" -gt "$b" ] && return 0
+    [ "$a" -lt "$b" ] && return 1
+  done
+  return 0
 }
 if command -v har >/dev/null 2>&1 && har_runtime_compatible har; then
   exec har env launch "$@"

package/dist/templates/runtime-bundles/shared-kernel/preflight.sh

@@ -8,7 +8,7 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 # Loop guard (#291): a pre-1.0 har does not own this runtime kind in the
 # package — it executes this script as authoritative, which would exec back
 # into har forever (one node process per cycle). Trip on re-entry for this
-# harness root, and skip har binaries older than the pinned runtime's major.
+# harness root, and skip har binaries older than the pinned runtime (#298).
 HAR_SHIM_GUARD="preflight@${REPO_ROOT}"
 case ":${HAR_SHIM_REENTRY:-}:" in *":${HAR_SHIM_GUARD}:"*)
   echo "Error: runtime loop detected — the har CLI that ran this shim delegated back into it." >&2
@@ -18,10 +18,27 @@ case ":${HAR_SHIM_REENTRY:-}:" in *":${HAR_SHIM_GUARD}:"*)
   ;;
 esac
 export HAR_SHIM_REENTRY="${HAR_SHIM_REENTRY:-}:${HAR_SHIM_GUARD}"
+# True when $1 reports a version >= the pinned runtime. Comparing only the
+# major (#298) made the floor inert for the whole 0.x line: every pre-1.0 har
+# passed it and then bounced straight back into this shim. Compare the full
+# release triple, and treat anything unparseable as unusable.
 har_runtime_compatible() {
-  local v pinned="__HAR_VERSION__"
+  local v pinned="__HAR_VERSION__" i a b
   v="$("$1" --version 2>/dev/null | head -n1)" || return 1
-  [ "${v%%.*}" -ge "${pinned%%.*}" ] 2>/dev/null
+  v="${v#v}"
+  v="${v%%[-+ ]*}"
+  local -a have pin
+  IFS=. read -r -a have <<<"$v"
+  IFS=. read -r -a pin <<<"${pinned%%[-+]*}"
+  for i in 0 1 2; do
+    a="${have[i]:-0}"
+    b="${pin[i]:-0}"
+    case "$a" in ''|*[!0-9]*) return 1 ;; esac
+    case "$b" in ''|*[!0-9]*) return 1 ;; esac
+    [ "$a" -gt "$b" ] && return 0
+    [ "$a" -lt "$b" ] && return 1
+  done
+  return 0
 }
 if command -v har >/dev/null 2>&1 && har_runtime_compatible har; then
   exec har env preflight "$@"

package/dist/templates/runtime-bundles/shared-kernel/setup-infra.sh

@@ -8,7 +8,7 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 # Loop guard (#291): a pre-1.0 har does not own this runtime kind in the
 # package — it executes this script as authoritative, which would exec back
 # into har forever (one node process per cycle). Trip on re-entry for this
-# harness root, and skip har binaries older than the pinned runtime's major.
+# harness root, and skip har binaries older than the pinned runtime (#298).
 HAR_SHIM_GUARD="setup-infra@${REPO_ROOT}"
 case ":${HAR_SHIM_REENTRY:-}:" in *":${HAR_SHIM_GUARD}:"*)
   echo "Error: runtime loop detected — the har CLI that ran this shim delegated back into it." >&2
@@ -18,10 +18,27 @@ case ":${HAR_SHIM_REENTRY:-}:" in *":${HAR_SHIM_GUARD}:"*)
   ;;
 esac
 export HAR_SHIM_REENTRY="${HAR_SHIM_REENTRY:-}:${HAR_SHIM_GUARD}"
+# True when $1 reports a version >= the pinned runtime. Comparing only the
+# major (#298) made the floor inert for the whole 0.x line: every pre-1.0 har
+# passed it and then bounced straight back into this shim. Compare the full
+# release triple, and treat anything unparseable as unusable.
 har_runtime_compatible() {
-  local v pinned="__HAR_VERSION__"
+  local v pinned="__HAR_VERSION__" i a b
   v="$("$1" --version 2>/dev/null | head -n1)" || return 1
-  [ "${v%%.*}" -ge "${pinned%%.*}" ] 2>/dev/null
+  v="${v#v}"
+  v="${v%%[-+ ]*}"
+  local -a have pin
+  IFS=. read -r -a have <<<"$v"
+  IFS=. read -r -a pin <<<"${pinned%%[-+]*}"
+  for i in 0 1 2; do
+    a="${have[i]:-0}"
+    b="${pin[i]:-0}"
+    case "$a" in ''|*[!0-9]*) return 1 ;; esac
+    case "$b" in ''|*[!0-9]*) return 1 ;; esac
+    [ "$a" -gt "$b" ] && return 0
+    [ "$a" -lt "$b" ] && return 1
+  done
+  return 0
 }
 if command -v har >/dev/null 2>&1 && har_runtime_compatible har; then
   exec har env setup-infra "$@"