@osfactory/har 0.64.2 → 1.0.0-rc.2

package/dist/templates/runtime-bundles/shared-kernel/STAGES.md

@@ -38,32 +38,36 @@ Optional stage fields: `cwd` (working directory), `env` (extra env vars),
 ## Two ways to define a stage
 
 **Command stages** — the default for simple checks (`npm test`, `swiftlint`,
-`make check`). One JSON entry, zero files:
+`make check`). One JSON entry in `.har/stages.json`, zero files:
 
-```bash
-har env add-stage unit-tests-fast --custom --kind test --command "npm test" --verification
+```json
+{ "id": "unit-tests-fast", "kind": "test", "command": "npm test", "tier": "quick" }
 ```
 
+(add the id to `verificationStages` to run it during verify).
+
 **Script stages** — for anything that needs the slot's env, ports, or
-artifacts. Scaffold a contract-compliant skeleton:
+artifacts. Scaffold a project-owned plugin with a contract-compliant skeleton:
 
 ```bash
-har env add-stage db-integrity --custom --script --description "Check DB invariants"
+har plugin create db-integrity --description "Check DB invariants"
+har env add-plugin db-integrity
 ```
 
-then implement the TODO block in `.har/stages/db-integrity.sh`.
+then implement the TODO block in `.har/plugins/db-integrity/stages/db-integrity.sh`
+and reinstall with `har env add-plugin db-integrity --force`.
 
 ## The stage script contract
 
 Every script under `.har/stages/` must:
 
-1. Source `harness.env` and `agent-slot.sh` from `.har/`. Before sourcing,
-   set `SCRIPT_DIR` to the `.har/` directory (not `stages/`) — `agent-slot.sh`
-   resolves the slot registry via `$SCRIPT_DIR/slots/...`.
-2. Take the agent slot id as `$1` (validate with `validate_agent_id`); extra
-   args may follow.
-3. Load the slot env via `resolve_agent_env_file` and run checks from the
-   agent's work dir (`resolve_agent_work_dir`).
+1. Assume the 1.0 stage surface: the runner exports `WORK_DIR`, `ENV_FILE`,
+   `AGENT_ID` and `HAR_HARNESS_DIR`, with `harness.env` and the slot env file
+   already sourced. Never source `agent-slot.sh` — it is retired in 1.0.
+2. Take the agent slot id as `$1`, falling back to the exported `AGENT_ID`
+   (`AGENT_ID="${1:-${AGENT_ID:?...}}"`); extra args may follow.
+3. Guard the runner contract with `${ENV_FILE:?...}` / `${WORK_DIR:?...}`
+   (pointing at `./.har/launch.sh <id>`) and run checks from `$WORK_DIR`.
 4. Write artifacts (reports, screenshots, logs) under `.har/artifacts/<id>/`.
 5. Print **only** the normalized JSON result object on stdout
    (`status`, `stageId`, `agent_id`, `total_ms`, …); log progress to stderr.
@@ -73,10 +77,17 @@ The scaffolded skeleton implements all of this — replace its TODO block.
 
 ## Verification membership
 
-Listing a stage id in `verificationStages` is what includes it in
-`har env verify <id> --full`. Ids that match a registered stage run via their
-script/command; ids without a registry entry (e.g. `typecheck`, `api-health`)
-are inline steps owned by `.har/verify.sh`. Lifecycle kinds
+`verificationStages` is the single namespace for the verification pipeline:
+every id listed must resolve to a registered stage of kind `test` or `custom`,
+and the list order is the execution order. There are no inline steps — the
+ecosystem defaults (`typecheck`, `unit-tests`, `lint`, `readiness`, and
+`api-health` on web profiles) are ordinary registered stages, written at init
+from `HARNESS_ECOSYSTEM`.
+
+Each stage may declare `"tier": "quick" | "full"` (default `full`). Plain
+`har env verify <id>` runs the `quick`-tier stages; `--full` runs the whole
+list. Unresolvable ids are reported by validation (and `har env doctor`) and
+skipped with a warning at run time. Lifecycle kinds
 (`setup`/`launch`/`reset`/`teardown`/`inspect`) and `verify` itself never run
 as part of verification, even if listed.
 
@@ -96,4 +107,7 @@ stack), or `har env add-plugin trivy` (dependency + IaC security scan, any stack
 or `har env add-plugin semgrep` (SAST, any stack)
 installs one. A
 plugin is just packaging: it copies files, merges `package.json` fragments,
-and registers stages through the exact same registry as `add-stage --custom`.
+and registers stages through the exact same registry as everything else.
+Project-owned plugins live in `.har/plugins/<id>/` (`har plugin create <id>`)
+and install from any of four sources — bundled, local, npm, or git — with the
+same format.

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Namespaced CLI for managing a running agent environment.
+# The runtime lives in the HAR package (#234) — this file only forwards to it.
+# Usage: ./.har/agent-cli.sh <agent-id> <command> [args...]
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+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.
+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
+  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}"
+har_runtime_compatible() {
+  local v pinned="__HAR_VERSION__"
+  v="$("$1" --version 2>/dev/null | head -n1)" || return 1
+  [ "${v%%.*}" -ge "${pinned%%.*}" ] 2>/dev/null
+}
+if command -v har >/dev/null 2>&1 && har_runtime_compatible har; then
+  exec har env agent "$@"
+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 "$@"
+elif command -v npx >/dev/null 2>&1; then
+  exec npx --yes @osfactory/har@__HAR_VERSION__ env agent "$@"
+fi
+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/launch.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Launch an isolated agent environment slot (fresh suffixed worktree; occupied slots block).
+# The runtime lives in the HAR package (#234) — this file only forwards to it.
+# Usage: ./.har/launch.sh <agent-id> [--no-worktree] [--resume]
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+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.
+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
+  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}"
+har_runtime_compatible() {
+  local v pinned="__HAR_VERSION__"
+  v="$("$1" --version 2>/dev/null | head -n1)" || return 1
+  [ "${v%%.*}" -ge "${pinned%%.*}" ] 2>/dev/null
+}
+if command -v har >/dev/null 2>&1 && har_runtime_compatible har; then
+  exec har env launch "$@"
+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 launch "$@"
+elif command -v npx >/dev/null 2>&1; then
+  exec npx --yes @osfactory/har@__HAR_VERSION__ env launch "$@"
+fi
+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 launch" >&2
+exit 127

package/dist/templates/runtime-bundles/shared-kernel/lib/verify-runner.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Verification runner: executes the stages.json verification plan.
+// Invoked by .har/verify.sh after it sources harness.env and the agent env
+// file (so the full slot environment is inherited). Replaces the bash
+// run_step/run_http_step/RESULTS_JSON plumbing: step names may contain any
+// characters, no result is ever silently dropped, and stage env vars are
+// passed as real environment entries instead of eval'd shell prefixes.
+//
+// Usage: verify-runner.mjs --agent <id> [--full]
+// Env:   HAR_HARNESS_DIR (the .har dir), WORK_DIR (step cwd)
+//
+// Contract (stdout): { status, agent_id, total_ms, stages: [{name, pass, ms, output?}] }
+// Quick mode stops at the first failing step; full mode runs the whole plan.
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+const RUNNABLE_KINDS = new Set(['test', 'custom']);
+
+const args = process.argv.slice(2);
+const full = args.includes('--full');
+const agentIdx = args.indexOf('--agent');
+const agentId = agentIdx >= 0 ? Number(args[agentIdx + 1]) : NaN;
+if (!Number.isInteger(agentId)) {
+  process.stderr.write('verify-runner: --agent <id> is required\n');
+  process.exit(2);
+}
+
+const harnessDir = process.env.HAR_HARNESS_DIR;
+const workDir = process.env.WORK_DIR;
+if (!harnessDir || !workDir) {
+  process.stderr.write('verify-runner: HAR_HARNESS_DIR and WORK_DIR must be set\n');
+  process.exit(2);
+}
+
+let registry;
+try {
+  registry = JSON.parse(readFileSync(join(harnessDir, 'stages.json'), 'utf8'));
+} catch (err) {
+  process.stderr.write(`verify-runner: cannot read ${join(harnessDir, 'stages.json')}: ${err.message}\n`);
+  process.exit(2);
+}
+
+const ids = Array.isArray(registry.verificationStages) ? registry.verificationStages : [];
+const stages = Array.isArray(registry.stages) ? registry.stages : [];
+
+const plan = [];
+const phantoms = [];
+for (const id of ids) {
+  const stage = stages.find((s) => s && s.id === id);
+  if (!stage || !RUNNABLE_KINDS.has(stage.kind)) {
+    phantoms.push(id);
+    continue;
+  }
+  if (!full && stage.tier !== 'quick') continue;
+  plan.push(stage);
+}
+
+for (const id of phantoms) {
+  process.stderr.write(
+    `  ! verificationStages id "${id}" has no registered runnable stage — fix .har/stages.json (har env doctor reports this)\n`,
+  );
+}
+
+function stepCommand(stage) {
+  if (stage.script) {
+    const script = resolve(harnessDir, stage.script);
+    const quoted = `'${script.replace(/'/g, "'\\''")}'`;
+    return stage.requiresAgentId === false ? quoted : `${quoted} ${agentId}`;
+  }
+  if (stage.command) {
+    return stage.command.split('{agentId}').join(String(agentId));
+  }
+  return null;
+}
+
+const results = [];
+let overallPass = true;
+const startTotal = Date.now();
+
+for (const stage of plan) {
+  const cmd = stepCommand(stage);
+  if (cmd === null) {
+    results.push({ name: stage.id, pass: false, ms: 0, output: 'stage has neither script nor command' });
+    overallPass = false;
+    if (!full) break;
+    continue;
+  }
+
+  process.stderr.write(`  → ${`${stage.id}...`.padEnd(40)}`);
+  const start = Date.now();
+  const child = spawnSync('bash', ['-c', cmd], {
+    cwd: stage.cwd ? resolve(workDir, stage.cwd) : workDir,
+    env: { ...process.env, ...(stage.env ?? {}), HAR_AGENT_ID: String(agentId) },
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  const ms = Date.now() - start;
+  const output = `${child.stdout ?? ''}${child.stderr ?? ''}`.trim();
+  const pass = child.status === 0;
+
+  if (pass) {
+    process.stderr.write(`✓ (${ms}ms)\n`);
+    results.push({ name: stage.id, pass: true, ms });
+  } else {
+    process.stderr.write(`✗ (${ms}ms)\n`);
+    for (const line of output.split('\n').slice(0, 30)) {
+      process.stderr.write(`    ${line}\n`);
+    }
+    results.push({
+      name: stage.id,
+      pass: false,
+      ms,
+      output: output.split('\n').slice(0, 50).join('\n'),
+    });
+    overallPass = false;
+    if (!full) break;
+  }
+}
+
+const out = {
+  status: overallPass && results.length > 0 ? 'pass' : 'fail',
+  agent_id: agentId,
+  total_ms: Date.now() - startTotal,
+  stages: results,
+};
+process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+process.exit(out.status === 'pass' ? 0 : 1);

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Launch readiness gate — run before launch.sh or standalone.
+# The runtime lives in the HAR package (#234) — this file only forwards to it.
+# Usage: ./.har/preflight.sh <agent-id>
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+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.
+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
+  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}"
+har_runtime_compatible() {
+  local v pinned="__HAR_VERSION__"
+  v="$("$1" --version 2>/dev/null | head -n1)" || return 1
+  [ "${v%%.*}" -ge "${pinned%%.*}" ] 2>/dev/null
+}
+if command -v har >/dev/null 2>&1 && har_runtime_compatible har; then
+  exec har env preflight "$@"
+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 preflight "$@"
+elif command -v npx >/dev/null 2>&1; then
+  exec npx --yes @osfactory/har@__HAR_VERSION__ env preflight "$@"
+fi
+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 preflight" >&2
+exit 127

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Set up shared infrastructure for all agent slots. Idempotent.
+# The runtime lives in the HAR package (#234) — this file only forwards to it.
+# Usage: ./.har/setup-infra.sh 
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+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.
+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
+  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}"
+har_runtime_compatible() {
+  local v pinned="__HAR_VERSION__"
+  v="$("$1" --version 2>/dev/null | head -n1)" || return 1
+  [ "${v%%.*}" -ge "${pinned%%.*}" ] 2>/dev/null
+}
+if command -v har >/dev/null 2>&1 && har_runtime_compatible har; then
+  exec har env setup-infra "$@"
+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 setup-infra "$@"
+elif command -v npx >/dev/null 2>&1; then
+  exec npx --yes @osfactory/har@__HAR_VERSION__ env setup-infra "$@"
+fi
+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 setup-infra" >&2
+exit 127

package/dist/templates/runtime-bundles/shared-kernel/stages/README.sh

@@ -5,7 +5,7 @@
 # command vs script stages, and how verificationStages controls verify --full.
 #
 # Scaffold a new one with:
-#   har env add-stage <id> --custom --script
+#   har plugin create <id>   # then: har env add-plugin <id>
 
 echo "Add stage scripts under .har/stages/ and register them in stages.json — see .har/STAGES.md." >&2
 exit 1

package/dist/templates/runtime-bundles/shared-kernel/stages/readiness.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Project readiness smoke: runs HARNESS_READINESS_CMD from harness.env, an
+# optional project-owned "agent usable" check beyond health. Registered as the
+# `readiness` verification stage (tier: full).
+set -euo pipefail
+
+AGENT_ID="${1:?Usage: readiness.sh <agent-id>}"
+
+if [ -z "${HARNESS_READINESS_CMD:-}" ]; then
+  echo "No HARNESS_READINESS_CMD configured; skipping readiness smoke."
+  exit 0
+fi
+
+eval "${HARNESS_READINESS_CMD//\{agentId\}/$AGENT_ID}"

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Tear down one agent slot: stop processes, release resources, keep the session branch.
+# The runtime lives in the HAR package (#234) — this file only forwards to it.
+# Usage: ./.har/teardown.sh <agent-id> [--delete-branch]
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+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.
+HAR_SHIM_GUARD="teardown@${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}"
+har_runtime_compatible() {
+  local v pinned="__HAR_VERSION__"
+  v="$("$1" --version 2>/dev/null | head -n1)" || return 1
+  [ "${v%%.*}" -ge "${pinned%%.*}" ] 2>/dev/null
+}
+if command -v har >/dev/null 2>&1 && har_runtime_compatible har; then
+  exec har env teardown "$@"
+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 teardown "$@"
+elif command -v npx >/dev/null 2>&1; then
+  exec npx --yes @osfactory/har@__HAR_VERSION__ env teardown "$@"
+fi
+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 teardown" >&2
+exit 127

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Verification pipeline (stages.json verificationStages; quick by default, --full for the whole list).
+# The runtime lives in the HAR package (#234) — this file only forwards to it.
+# Usage: ./.har/verify.sh <agent-id> [--full] [--json]   (human output; pass --json for the structured result)
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+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.
+HAR_SHIM_GUARD="verify@${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}"
+har_runtime_compatible() {
+  local v pinned="__HAR_VERSION__"
+  v="$("$1" --version 2>/dev/null | head -n1)" || return 1
+  [ "${v%%.*}" -ge "${pinned%%.*}" ] 2>/dev/null
+}
+if command -v har >/dev/null 2>&1 && har_runtime_compatible har; then
+  exec har env verify "$@"
+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 verify "$@"
+elif command -v npx >/dev/null 2>&1; then
+  exec npx --yes @osfactory/har@__HAR_VERSION__ env verify "$@"
+fi
+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 verify" >&2
+exit 127

package/dist/templates/shared-docs/claude-agent/intro.md

@@ -0,0 +1,3 @@
+# Agent ${AGENT_ID} — Development Environment
+
+> [`AGENTS.md`](../AGENTS.md) · [`.har/README.md`](./README.md) · [`stages.json`](./stages.json)

package/dist/templates/shared-docs/readme/maintaining-this-harness.md

@@ -0,0 +1,14 @@
+## Maintaining this harness
+
+When the project stack changes (new services, different test commands, new env vars):
+
+```bash
+har env maintain
+```
+
+The authoring agent reconciles the config surface and this README. Review changes before committing.
+
+Customize through the contract — config (`harness.env`), stages (`stages.json` +
+`stages/`), hooks (`hooks/`), plugins (`plugins/`). The `*.sh` files are generated
+shims over the packaged runtime: don't edit them (`har env eject` exists for full
+ownership). `har env doctor` validates the result.

package/dist/templates/shared-docs/readme/run-history.md

@@ -0,0 +1,5 @@
+## Run history
+
+Every entry point — `./.har/*.sh`, `har env …`, MCP — runs the same packaged runtime and writes the same records under the main checkout `.har/runs/YYYY-MM-DD/`.
+
+With git worktree slots, verification runs code in the worktree but run JSON stays in the main repo `.har/runs/`. Each record includes `workDir` when a slot is active.

package/dist/templates/shared-docs/readme/session-lifecycle.md

@@ -0,0 +1,20 @@
+## Session lifecycle
+
+Every `launch` starts a **fresh session**: a new git worktree from the **main
+checkout's current HEAD** at
+`~/worktrees/<base-branch>-<sha4>-har-agent-<id>-<rand4>`, on a branch of the same name.
+Switch that checkout to your intended base before launch. The session is recorded in
+`.har/slots/agent-<id>.json` (the slot registry) — status, verify, and teardown resolve
+the work dir through it. Make ALL file edits under the work dir printed by launch,
+never in the main checkout.
+
+- Occupied slots always block a new launch: `har env complete <id>` (or `teardown <id>`),
+  then `har env launch <id>`. A new launch never chooses `main` for you — switch the
+  main checkout to your intended base first.
+- `teardown` removes the worktree but **keeps the session branch** so you can push it
+  or open a PR (`--delete-branch` to drop it).
+- If launch fails after creating a worktree/env file, the registry records `status: failed`.
+  Resume it instead of starting fresh: `har env launch <id> --resume` or `har env recover <id>`.
+- `har env complete <id>` finishes a session: full verify (recorded as a validation),
+  then teardown — branch kept.
+- `--no-worktree` runs the slot from the repo root instead (single-agent mode).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osfactory/har",
-  "version": "0.64.2",
+  "version": "1.0.0-rc.2",
   "description": "HAR: open agent harness CLI and MCP server for coding agents, isolated worktrees, and software-factory workflows",
   "keywords": [
     "har",

package/dist/templates/har-boilerplate/CLAUDE.agent.md

@@ -1,83 +0,0 @@
-# Agent ${AGENT_ID} — Development Environment
-
-> [`AGENTS.md`](../AGENTS.md) · [`.har/README.md`](./README.md) · [`stages.json`](./stages.json)
-
-## Environment
-
-| | |
-|--|--|
-| **Agent ID** | ${AGENT_ID} |
-| **Frontend** | http://localhost:${FE_PORT} |
-| **API** | http://localhost:${API_PORT} |
-| **Database** | `agent_${AGENT_ID}` on `localhost:${DB_PORT}` (when `db` is in `HARNESS_INFRA_SERVICES`) |
-| **Work dir** | Fresh session worktree per launch — see the launch output or `.har/slots/agent-${AGENT_ID}.json` |
-
-**Never edit the main checkout** — launch FIRST, then make ALL file edits under the work dir from the launch output. Edits there hot-reload in the running slot; use `./.har/agent-cli.sh ${AGENT_ID} restart` if a change doesn't take. An occupied slot always blocks a new launch — run `./.har/teardown.sh ${AGENT_ID}` (or `complete`) first, then launch again.
-
-This slot runs **only the primary application** (`HARNESS_PRIMARY_APP`). External dependencies and any supporting services run once, shared by all slots — `setup-infra.sh` manages them; never start them yourself.
-
-```bash
-./.har/agent-cli.sh ${AGENT_ID} status
-./.har/agent-cli.sh ${AGENT_ID} logs api
-./.har/agent-cli.sh ${AGENT_ID} health
-```
-
-## Readiness
-
-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`
-- **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
-  settings created by the harness.
-- **Skipped full-dev setup**: document anything intentionally omitted from the
-  upstream developer setup and the minimal substitute in `.har/`.
-
-## 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`)
-- [ ] The slot is agent-usable for this repo's documented smoke workflow, not only health-check green
-- [ ] Full verify runs every registered stage in `stages.json` `verificationStages` (Playwright, custom checks, …) — when `stages/browser-e2e.sh` exists, adapt specs under `tests/` for UI changes
-- [ ] New behavior has automated test coverage (unit and/or browser as appropriate)
-- [ ] Changes committed **in the session worktree** with a clear message
-- [ ] The user got the preview URLs to test the app themselves
-- [ ] 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
-
-### Session handoff
-
-After full verify and commit, stop and propose next steps. Never autonomously run
-`complete`, `teardown`, `git push`, or open a PR. **Default recommendation:** when
-`gh` or GitHub MCP is available, complete the slot **and** open a PR (push → PR →
-`har env complete` / `har_complete_environment`). Offer complete-only or something
-else as alternatives. If PR tooling is unavailable, recommend complete and report
-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 during development: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}` (smoke + health only; `--full` adds the registered verification stages).
-
-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`.
-
-## Project commands
-
-```bash
-# TODO: adapt for this repository (see package.json, Makefile, pyproject.toml, CI, etc.)
-# npm run typecheck
-# pytest -q
-# go test ./...
-# cargo test
-# make test
-```
-
-## Do not
-
-- Hand-roll docker/dev-server startup — `launch` is how you run the app (manual testing, browser, screenshots included)
-- Work around a failing harness command with ad-hoc setup — fix the harness or report the failure
-- Hardcode ports — use agent env / `agent-cli.sh url`
-- Run raw `docker compose` for shared harness infra — use `setup-infra.sh`
-- Start other services of the repo in your slot — only the primary app runs per-slot; shared services are already running
-- Edit `.env.agent.${AGENT_ID}` or PM2 ecosystem files by hand
-- Run `verify` before `launch` when health or e2e steps need a running server
-- Edit the main checkout — all edits go under the session work dir