@osfactory/har 0.1.1 → 0.3.0

package/dist/prompts/system-authoring.md

@@ -58,6 +58,29 @@ PM2 processes for the primary application only, matching how it runs in dev.
 ### `.har/verify.sh`
 Real typecheck, lint, test, and health check commands — replace all TODOs.
 
+## Readiness vs liveness (required)
+Do not treat a passing health check as adaptation complete. A usable agent
+environment has layered readiness:
+
+1. **Infra ready** — shared services and template data stores exist.
+2. **Slot data ready** — every per-slot data store is created or cloned.
+3. **Process ready** — primary app processes are online and health passes.
+4. **Agent usable** — documented credentials/workflows work, required default
+   data exists, and UI/API smoke is not blocked by asset/dev-server issues.
+
+Compare the harness against the repository's full local-dev setup. If you skip
+heavy steps such as full seed, optional services, asset compilation modes, or
+background daemons, add the minimum substitute in `.har/` scripts or document
+why no substitute is needed. If the app has multiple databases/stores, provision
+all per-slot state. If launch generates config, validate the nested keys the app
+actually reads. Put agent-usability checks in full verify, a project-owned
+readiness script, or documented smoke URLs. Health alone is not sufficient for
+UI/auth apps.
+
+Ensure `launch.sh` writes the slot registry before slow or fragile steps, and
+`verify.sh` resolves env/work dir through `agent-slot.sh` so partial launches are
+recoverable.
+
 ### `.har/CLAUDE.agent.md`
 Detailed agent instructions: commands, credentials, architecture, definition of done.
 
@@ -101,4 +124,7 @@ Set slot limits in `.har/stages.json` (`agentSlots`) and `.har/harness.env` (`HA
    - unused harness files deleted (`deleteHarnessFile`), e.g. `attach.sh` when unused
    - `.har/README.md` file table matches the files that actually exist
    - `CLAUDE.agent.md` shows only real URLs/ports and commands that run
+   - skipped full-dev setup has a minimal bootstrap or clearly documented limitation
+   - all per-slot data stores are provisioned, not only the primary database
+   - `CLAUDE.agent.md` defines what "agent usable" means, including credentials or smoke checks when applicable
 8. **Call finishAuthoring** when complete

package/dist/templates/adaptation-prompt-init.md

@@ -44,6 +44,39 @@ PM2 processes for the primary application only, matching how it runs in dev. Ski
 ### `.har/verify.sh`
 Real typecheck, lint, test, and health check commands — replace all TODOs.
 
+### Readiness vs liveness (required)
+Do not treat a passing health check as adaptation complete. Before finishing,
+make the harness explicit about the layers that apply to this repository:
+
+1. **Infra ready** — shared services are running and template data stores exist.
+2. **Slot data ready** — every per-slot data store is created or cloned, not only
+   the primary database.
+3. **Process ready** — the primary app processes are online and
+   `HARNESS_HEALTH_CHECK_PATH` passes.
+4. **Agent usable** — a real workflow an agent needs is possible: documented
+   credentials work, a tenant/org/project exists when the app requires one, the
+   UI is not blocked by dev-server overlays, or an authenticated API smoke works.
+
+Compare the harness against the project's full local-dev setup. If the harness
+intentionally skips slow or heavy steps (full seed, optional services, asset
+mode, background daemons), add the minimum substitute directly in `.har/`
+scripts or document why no substitute is needed. In particular:
+
+- If `HARNESS_DB_SEED_CMD` is empty or schema-only, add an idempotent minimal
+  bootstrap step for required tenants/users/settings, or document why schema-only
+  is enough.
+- If the app has multiple databases, schemas, queues, object stores, search
+  indexes, or other per-slot state, provision all of them in `setup-infra.sh`
+  and `launch.sh`.
+- If launch generates config, validate the nested keys the app actually reads
+  against upstream examples/defaults, not only top-level keys.
+- If the dev server can block agents with overlays or noisy HMR failures,
+  choose and document an agent-friendly asset mode.
+- Put Layer 3 checks in `verify --full`, a project-owned readiness script, or
+  documented smoke URLs. Health alone is not sufficient for UI/auth apps.
+- Ensure `launch.sh` writes the slot registry before slow or fragile steps, and
+  `verify.sh` resolves env/work dir through `agent-slot.sh`.
+
 ### Optional Playwright stage
 If the user ran `har env add-stage playwright` (or `@playwright/test` is in package.json):
 
@@ -65,7 +98,7 @@ Agents run in parallel on configurable slot ids. Ports: `BASE + (AGENT_ID × 10)
 Set slot limits in `.har/stages.json` (`agentSlots`) and `.har/harness.env` (`HARNESS_AGENT_SLOT_MIN` / `HARNESS_AGENT_SLOT_MAX`) based on machine capacity.
 
 ### Git worktree
-`launch.sh` creates an isolated worktree at `~/worktrees/<project>-agent-<id>` by default (`HARNESS_USE_WORKTREE=true`). Agents should commit from that worktree, not the main checkout.
+`launch.sh` creates an isolated session worktree at `~/worktrees/<base>-<sha4>-har-agent-<id>-<rand4>` by default (`HARNESS_USE_WORKTREE=true`) and records it in `.har/slots/agent-<id>.json`. Agents should commit from that worktree, not the main checkout.
 
 ## Step 3 — Update repo-root `AGENT.md`
 
@@ -112,6 +145,9 @@ The boilerplate ships more than any single repository needs. Strip it down to st
 - [ ] Unused harness files are deleted (e.g. `attach.sh` when tmux isn't part of the workflow; CLI profile: `ecosystem.agent.template.cjs`, `env.template`)
 - [ ] `.har/README.md` file table lists exactly the files that exist — no more, no less
 - [ ] `.har/CLAUDE.agent.md` shows only real URLs/ports/credentials (e.g. drop the Frontend row for an API-only project) and project commands that actually run
+- [ ] If full seed/setup is skipped, `.har/` provides a minimal bootstrap or clearly documents why none is needed
+- [ ] All per-slot data stores are provisioned, not just the primary database
+- [ ] `.har/CLAUDE.agent.md` defines what "agent usable" means for this repo: login/API smoke, credentials, required default data, and known skipped dev-setup steps
 
 ## Rules
 

package/dist/templates/adaptation-prompt-maintain.md

@@ -28,6 +28,36 @@ Align commands and instructions with the current stack.
 ### `.har/env.template`, `setup-infra.sh`, `docker-compose.agent.yml`
 Update only if infra changed.
 
+### Readiness vs liveness regression check
+Do not treat a passing health check as proof that the harness is still usable.
+When maintaining an existing harness, re-check the layers that apply:
+
+1. **Infra ready** — shared services and template data stores still match the app.
+2. **Slot data ready** — every per-slot data store is created or cloned, not only
+   the primary database.
+3. **Process ready** — app processes are online and `HARNESS_HEALTH_CHECK_PATH`
+   passes.
+4. **Agent usable** — documented credentials/workflows still work, required
+   default data exists, UI/API smoke is not blocked by asset/dev-server issues,
+   and any skipped full-dev setup has a minimal substitute or clear limitation.
+
+Look specifically for drift introduced since the last adaptation:
+
+- A seed command was removed or made schema-only without a minimal bootstrap.
+- A new database, schema, queue, object store, search index, or other per-slot
+  dependency was added but launch only provisions the original primary store.
+- Config generation writes plausible top-level keys while the app reads nested
+  defaults from another file.
+- The dev server mode is fine for humans but blocks browser automation or agents
+  with overlays/noisy HMR.
+- `verify.sh` became health-only and no longer checks the key workflow that makes
+  the slot usable.
+- `launch.sh` writes the slot registry only after fragile late steps; partial
+  launches must remain discoverable by verify/status/teardown.
+
+Update `.har/CLAUDE.agent.md` with skipped setup steps, substitutes, credentials,
+and the repo-specific definition of "agent usable."
+
 ### HAR platform upgrades checklist
 
 When upgrading `@osfactory/har` or adopting new harness standards:

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

@@ -22,9 +22,23 @@ This slot runs **only the primary application** (`HARNESS_PRIMARY_APP`). Externa
 ./.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
 - [ ] When `stages/browser-e2e.sh` exists, full verify includes Playwright — 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

package/dist/templates/har-boilerplate/README.md

@@ -61,10 +61,27 @@ Read **`stages.json`** for registered stages and **`verificationStages`** for th
 | Mode | Command | Typical steps |
 |------|---------|---------------|
 | Quick | `har env verify <id>` or `verify.sh <id>` | Project checks in `verify.sh` (stops early on failure) |
-| Full | `har env verify <id> --full` or `verify.sh <id> --full` | Quick steps + lint + **`browser-e2e`** when `.har/stages/browser-e2e.sh` exists |
+| Full | `har env verify <id> --full` or `verify.sh <id> --full` | Quick steps + lint + optional readiness smoke + **`browser-e2e`** when `.har/stages/browser-e2e.sh` exists |
 
 Install Playwright stage: `har env add-stage playwright` (optional). UI changes should add or update specs under `tests/`.
 
+## Readiness layers
+
+Do not treat a health endpoint as the whole definition of success. Adapt this
+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` |
+
+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
+idempotent bootstrap for required users/tenants/settings). Health alone is not
+enough for UI/auth apps.
+
 ## Run history
 
 | Entry point | Writes `.har/runs/`? |

package/dist/templates/har-boilerplate/agent-cli.sh

@@ -56,7 +56,13 @@ process.stdin.on('end', () => {
     fi
 
     if [ "$PM2_FOUND" = true ]; then
-      :
+      REG_FILE="$(slot_registry_file "$AGENT_ID")"
+      if [ ! -f "$REG_FILE" ]; then
+        echo "Warning: slot registry missing at $REG_FILE — verify/teardown may not resolve this slot."
+      fi
+      if [ -z "$ENV_FILE" ]; then
+        echo "Warning: .env.agent.${AGENT_ID} could not be resolved — relaunch with --replace when ready."
+      fi
     elif [ -n "$ENV_FILE" ] && [ -f "$ENV_FILE" ]; then
       echo "Agent ${AGENT_ID}: active (no PM2 processes)"
       # shellcheck source=/dev/null

package/dist/templates/har-boilerplate/agent-slot.sh

@@ -50,7 +50,8 @@ try {
 # Writes the registry entry from SLOT_* variables:
 #   required: SLOT_AGENT_ID, SLOT_MODE (worktree|root), SLOT_WORK_DIR
 #   optional: SLOT_SUFFIX, SLOT_WORKTREE_PATH, SLOT_BRANCH, SLOT_BASE_BRANCH,
-#             SLOT_BASE_COMMIT, SLOT_PORTS_JSON, SLOT_PREVIEW_URLS_JSON, SLOT_PURPOSE
+#             SLOT_BASE_COMMIT, SLOT_PORTS_JSON, SLOT_PREVIEW_URLS_JSON,
+#             SLOT_PURPOSE, SLOT_STATUS, SLOT_LAST_ERROR
 write_slot_registry() {
   local file
   file="$(slot_registry_file "$SLOT_AGENT_ID")"
@@ -65,7 +66,7 @@ const entry = {
   mode: e.SLOT_MODE,
   workDir: e.SLOT_WORK_DIR,
   createdAt: new Date().toISOString(),
-  status: "active",
+  status: e.SLOT_STATUS || "active",
 };
 if (e.SLOT_SUFFIX) entry.suffix = e.SLOT_SUFFIX;
 if (e.SLOT_WORKTREE_PATH) entry.worktreePath = e.SLOT_WORKTREE_PATH;
@@ -73,6 +74,7 @@ if (e.SLOT_BRANCH) entry.branch = e.SLOT_BRANCH;
 if (e.SLOT_BASE_BRANCH) entry.baseBranch = e.SLOT_BASE_BRANCH;
 if (e.SLOT_BASE_COMMIT) entry.baseCommit = e.SLOT_BASE_COMMIT;
 if (e.SLOT_PURPOSE) entry.purpose = e.SLOT_PURPOSE;
+if (e.SLOT_LAST_ERROR) entry.lastError = e.SLOT_LAST_ERROR;
 for (const [key, env] of [["ports", "SLOT_PORTS_JSON"], ["previewUrls", "SLOT_PREVIEW_URLS_JSON"]]) {
   if (e[env]) try { entry[key] = JSON.parse(e[env]); } catch {}
 }
@@ -115,13 +117,15 @@ slot_dirty_summary() {
 # Print a warning before replacing an occupied slot (stdout — visible to agents).
 print_slot_replace_warning() {
   local agent_id="$1"
-  local reg wt branch work_dir purpose created dirty_summary head
+  local reg wt branch work_dir purpose created status last_error dirty_summary head
   reg="$(slot_registry_file "$agent_id")"
   wt="$(existing_slot_worktree "$agent_id")"
   branch="$(read_slot_field "$reg" branch || true)"
   work_dir="$(read_slot_field "$reg" workDir || true)"
   purpose="$(read_slot_field "$reg" purpose || true)"
   created="$(read_slot_field "$reg" createdAt || true)"
+  status="$(read_slot_field "$reg" status || true)"
+  last_error="$(read_slot_field "$reg" lastError || true)"
   dirty_summary="$(slot_dirty_summary "$wt")"
   if [ -n "$wt" ] && [ -d "$wt" ]; then
     head="$(git -C "$wt" rev-parse --short HEAD 2>/dev/null || true)"
@@ -133,6 +137,8 @@ print_slot_replace_warning() {
   [ -n "$wt" ] && echo "  Worktree:  ${wt}" >&2
   [ -n "$work_dir" ] && echo "  Work dir:  ${work_dir}" >&2
   [ -n "$branch" ] && echo "  Branch:    ${branch}${head:+ @ ${head}}" >&2
+  [ -n "$status" ] && echo "  Status:    ${status}" >&2
+  [ -n "$last_error" ] && echo "  Error:     ${last_error}" >&2
   [ -n "$created" ] && echo "  Since:     ${created}" >&2
   echo "  Git:       ${dirty_summary}" >&2
   echo "" >&2
@@ -182,11 +188,30 @@ require_slot_replace_confirm() {
   exit 2
 }
 
+git_common_dir() {
+  local cwd="$1"
+  local out
+  out="$(git -C "$cwd" rev-parse --git-common-dir 2>/dev/null)" || return 1
+  case "$out" in
+    /*) echo "$out" ;;
+    *) (cd "$cwd" && cd "$out" && pwd) ;;
+  esac
+}
+
+same_git_checkout() {
+  local left right
+  left="$(git_common_dir "$1" || true)"
+  right="$(git_common_dir "$2" || true)"
+  [ -n "$left" ] && [ -n "$right" ] && [ "$left" = "$right" ]
+}
+
 # Echo the previous session's worktree path for a slot: registry first, then
-# the legacy fixed path (pre-registry sessions). Empty output when none exists.
+# legacy and randomized session worktree fallbacks. Empty output when none exists.
 existing_slot_worktree() {
   local agent_id="$1"
-  local reg path
+  local reg path candidate repo_root rel_prefix
+  repo_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+  rel_prefix="$(git -C "$repo_root" rev-parse --show-prefix 2>/dev/null || true)"
   reg="$(slot_registry_file "$agent_id")"
   if [ -f "$reg" ]; then
     path="$(read_slot_field "$reg" worktreePath || true)"
@@ -198,12 +223,20 @@ existing_slot_worktree() {
   path="$HOME/worktrees/${HARNESS_PROJECT_NAME}-agent-${agent_id}"
   if [ -d "$path" ]; then
     echo "$path"
+    return 0
   fi
+  for candidate in "$HOME"/worktrees/*-har-agent-"${agent_id}"-*; do
+    [ -d "$candidate" ] || continue
+    same_git_checkout "$repo_root" "$candidate" || continue
+    [ -f "$candidate/${rel_prefix}.env.agent.${agent_id}" ] || continue
+    echo "$candidate"
+    return 0
+  done
   return 0
 }
 
-# Resolve .env.agent.<id> — registry work dir first, then legacy locations
-# (repo root, pre-registry fixed worktree path).
+# Resolve .env.agent.<id> — registry work dir first, then legacy and
+# randomized session worktree fallbacks.
 resolve_agent_env_file() {
   local agent_id="$1"
   local repo_root="$2"
@@ -229,6 +262,15 @@ resolve_agent_env_file() {
       return 0
     fi
   done
+  local candidate_dir
+  for candidate in "$HOME"/worktrees/*-har-agent-"${agent_id}"-*/${rel_prefix}.env.agent."${agent_id}"; do
+    if [ -f "$candidate" ]; then
+      candidate_dir="$(cd "$(dirname "$candidate")" && pwd)"
+      same_git_checkout "$repo_root" "$candidate_dir" || continue
+      echo "$candidate"
+      return 0
+    fi
+  done
   return 1
 }
 
@@ -259,6 +301,16 @@ resolve_agent_work_dir() {
   echo "$work_dir"
 }
 
+# Portable millisecond clock (GNU date %N is unavailable on macOS/BSD).
+now_ms() {
+  node -e 'process.stdout.write(String(Date.now()))' 2>/dev/null || echo 0
+}
+
+# JSON-escape step output; truncate to 50 lines in node (avoids SIGPIPE under pipefail).
+escape_step_output() {
+  printf '%s' "$1" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const s=d.trim().split('\n').slice(0,50).join('\n');process.stdout.write(JSON.stringify(s))})" 2>/dev/null || echo '""'
+}
+
 # Run browser-e2e on verify --full when the Playwright stage template is installed.
 run_browser_e2e_if_present() {
   local script_dir="$1"
@@ -268,3 +320,14 @@ run_browser_e2e_if_present() {
     "$e2e" "$agent_id"
   fi
 }
+
+# Optional project-owned "agent usable" smoke beyond health.
+run_readiness_if_configured() {
+  local agent_id="$1"
+  if [ -z "${HARNESS_READINESS_CMD:-}" ]; then
+    echo "No HARNESS_READINESS_CMD configured; skipping readiness smoke."
+    return 0
+  fi
+  local cmd="${HARNESS_READINESS_CMD//\{agentId\}/$agent_id}"
+  eval "$cmd"
+}

package/dist/templates/har-boilerplate/harness.env

@@ -48,3 +48,18 @@ har_pg() {
 # Database setup commands (run once against template DB in setup-infra.sh)
 export HARNESS_DB_MIGRATE_CMD="echo 'TODO: set migrate command'"
 export HARNESS_DB_SEED_CMD="echo 'TODO: set seed command'"
+
+# Optional readiness/data hooks for larger apps. Enable only when this project
+# needs them, and keep the scripts idempotent.
+#
+# Multiple per-slot data stores can be represented as logical_name:template_db
+# pairs and handled directly in setup-infra.sh / launch.sh.
+# export HARNESS_TEMPLATE_DBS="main:template___PROJECT_NAME__"
+#
+# Use a minimal bootstrap when full seed is too slow/heavy but the app still
+# needs default tenants, users, settings, feature flags, or similar data.
+# export HARNESS_DB_MINIMAL_BOOTSTRAP_CMD="./.har/bootstrap-data.sh"
+#
+# Use readiness checks for "agent usable" smoke beyond a health endpoint:
+# login/API auth, representative UI page, required data, secondary stores.
+# export HARNESS_READINESS_CMD="./.har/readiness.sh"

package/dist/templates/har-boilerplate/launch.sh

@@ -147,6 +147,55 @@ REPO_ROOT="$WORK_DIR" \
   envsubst '${AGENT_ID} ${API_PORT} ${FE_PORT} ${DEBUG_PORT} ${DB_PORT} ${MINIO_PORT} ${BROWSER_PORT} ${REPO_ROOT}' \
   < "$SCRIPT_DIR/env.template" > "$ENV_FILE"
 
+REGISTRY_WRITTEN=false
+mark_slot_failed() {
+  local exit_code="$?"
+  if [ "$exit_code" != "0" ] && [ "$REGISTRY_WRITTEN" = true ]; then
+    log "Launch failed after creating the session. Recording failed slot state..."
+    set +e
+    SLOT_AGENT_ID="$AGENT_ID" \
+    SLOT_MODE="$([ "$USE_WORKTREE" = true ] && echo worktree || echo root)" \
+    SLOT_WORK_DIR="$WORK_DIR" \
+    SLOT_SUFFIX="${SUFFIX:-}" \
+    SLOT_WORKTREE_PATH="${WORKTREE_DIR:-}" \
+    SLOT_BRANCH="${BRANCH:-}" \
+    SLOT_BASE_BRANCH="${BASE_BRANCH:-}" \
+    SLOT_BASE_COMMIT="${BASE_COMMIT:-}" \
+    SLOT_PURPOSE="${PURPOSE}" \
+    SLOT_PORTS_JSON="{\"frontend\":${FE_PORT},\"api\":${API_PORT},\"debug\":${DEBUG_PORT}}" \
+    SLOT_PREVIEW_URLS_JSON="{\"frontend\":\"http://localhost:${FE_PORT}\",\"api\":\"http://localhost:${API_PORT}\"}" \
+    SLOT_STATUS="failed" \
+    SLOT_LAST_ERROR="launch.sh exited with code ${exit_code}" \
+      write_slot_registry
+    log "  Work dir:  ${WORK_DIR}"
+    log "  Env file:  ${ENV_FILE}"
+    log "  Recovery:  fix the failure, then relaunch with --replace when ready."
+  fi
+}
+trap mark_slot_failed EXIT
+
+# Record the session before slow or fragile setup so verify/status/teardown can
+# recover partial launches that already created a worktree and env file.
+SLOT_AGENT_ID="$AGENT_ID" \
+SLOT_MODE="$([ "$USE_WORKTREE" = true ] && echo worktree || echo root)" \
+SLOT_WORK_DIR="$WORK_DIR" \
+SLOT_SUFFIX="${SUFFIX:-}" \
+SLOT_WORKTREE_PATH="${WORKTREE_DIR:-}" \
+SLOT_BRANCH="${BRANCH:-}" \
+SLOT_BASE_BRANCH="${BASE_BRANCH:-}" \
+SLOT_BASE_COMMIT="${BASE_COMMIT:-}" \
+SLOT_PURPOSE="${PURPOSE}" \
+SLOT_PORTS_JSON="{\"frontend\":${FE_PORT},\"api\":${API_PORT},\"debug\":${DEBUG_PORT}}" \
+SLOT_PREVIEW_URLS_JSON="{\"frontend\":\"http://localhost:${FE_PORT}\",\"api\":\"http://localhost:${API_PORT}\"}" \
+SLOT_STATUS="starting" \
+  write_slot_registry
+REGISTRY_WRITTEN=true
+
+if [ -n "${HARNESS_DB_MINIMAL_BOOTSTRAP_CMD:-}" ]; then
+  log "Running minimal data bootstrap..."
+  (cd "$WORK_DIR" && set -a && . "$ENV_FILE" && set +a && eval "$HARNESS_DB_MINIMAL_BOOTSTRAP_CMD")
+fi
+
 # Generate PM2 ecosystem config
 ECOSYSTEM_FILE="$WORK_DIR/ecosystem.agent.${AGENT_ID}.config.cjs"
 log "Generating $ECOSYSTEM_FILE..."
@@ -199,6 +248,7 @@ SLOT_BASE_COMMIT="${BASE_COMMIT:-}" \
 SLOT_PURPOSE="${PURPOSE}" \
 SLOT_PORTS_JSON="{\"frontend\":${FE_PORT},\"api\":${API_PORT},\"debug\":${DEBUG_PORT}}" \
 SLOT_PREVIEW_URLS_JSON="{\"frontend\":\"http://localhost:${FE_PORT}\",\"api\":\"http://localhost:${API_PORT}\"}" \
+SLOT_STATUS="active" \
   write_slot_registry
 
 # Launch Claude Code in tmux (optional)

package/dist/templates/har-boilerplate/stages.json

@@ -20,7 +20,7 @@
         {
           "path": ".env.agent.{agentId}",
           "kind": "file",
-          "description": "Generated per-agent environment file"
+          "description": "Generated per-agent environment file in the session work dir"
         }
       ]
     },

package/dist/templates/har-boilerplate/verify.sh

@@ -38,9 +38,17 @@ WORK_DIR="$(resolve_agent_work_dir "$ENV_FILE")"
 API_PORT="${API_PORT:-$(( HARNESS_API_BASE_PORT + AGENT_ID * 10 ))}"
 
 echo "==> Verifying agent ${AGENT_ID} (work dir: ${WORK_DIR})..." >&2
+REG_FILE="$(slot_registry_file "$AGENT_ID")"
+echo "    Work dir: ${WORK_DIR}" >&2
+echo "    Env file: ${ENV_FILE}" >&2
+if [ -f "$REG_FILE" ]; then
+  echo "    Registry: ${REG_FILE}" >&2
+else
+  echo "    Registry: missing (${REG_FILE})" >&2
+fi
 
 OVERALL_PASS=true
-START_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+START_TOTAL=$(now_ms)
 RESULTS_JSON="[]"
 
 run_step() {
@@ -49,14 +57,14 @@ run_step() {
   local start end elapsed exit_code output
 
   printf "  → %-40s" "$name..." >&2
-  start=$(date +%s%3N 2>/dev/null || echo "0")
+  start=$(now_ms)
 
   set +e
   output=$(cd "$WORK_DIR" && set -a && . "$ENV_FILE" && set +a && eval "$cmd" 2>&1)
   exit_code=$?
   set -e
 
-  end=$(date +%s%3N 2>/dev/null || echo "0")
+  end=$(now_ms)
   elapsed=$(( end - start ))
 
   local pass_bool step_output_escaped
@@ -70,9 +78,7 @@ run_step() {
     OVERALL_PASS=false
   fi
 
-  step_output_escaped=$(echo "$output" | head -50 | \
-    node -e "let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>process.stdout.write(JSON.stringify(d.trim())))" \
-    2>/dev/null || echo '""')
+  step_output_escaped=$(escape_step_output "$output")
 
   RESULTS_JSON=$(echo "$RESULTS_JSON" | node -e "
 const fs = require('fs');
@@ -92,14 +98,14 @@ run_http_step() {
   local start end elapsed exit_code output
 
   printf "  → %-40s" "$name..." >&2
-  start=$(date +%s%3N 2>/dev/null || echo "0")
+  start=$(now_ms)
 
   set +e
   output=$(curl -sf "$url" 2>&1)
   exit_code=$?
   set -e
 
-  end=$(date +%s%3N 2>/dev/null || echo "0")
+  end=$(now_ms)
   elapsed=$(( end - start ))
 
   local pass_bool step_output_escaped
@@ -112,9 +118,7 @@ run_http_step() {
     OVERALL_PASS=false
   fi
 
-  step_output_escaped=$(echo "$output" | head -50 | \
-    node -e "let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>process.stdout.write(JSON.stringify(d.trim())))" \
-    2>/dev/null || echo '""')
+  step_output_escaped=$(escape_step_output "$output")
 
   RESULTS_JSON=$(echo "$RESULTS_JSON" | node -e "
 const fs = require('fs');
@@ -138,12 +142,13 @@ run_http_step "api-health" "http://localhost:${API_PORT}${HARNESS_HEALTH_CHECK_P
 
 if [ -n "$FULL" ]; then
   run_step "lint" "echo 'TODO: npm run lint'" || true
+  run_step "readiness" "run_readiness_if_configured \"$AGENT_ID\"" || true
   run_step "browser-e2e" "run_browser_e2e_if_present \"$SCRIPT_DIR\" \"$AGENT_ID\"" || true
 fi
 
 # ── Output results ────────────────────────────────────────────────────────────
 
-END_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+END_TOTAL=$(now_ms)
 TOTAL_MS=$(( END_TOTAL - START_TOTAL ))
 
 node -e "

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

@@ -15,9 +15,17 @@
 ./.har/agent-cli.sh ${AGENT_ID} status
 ```
 
+## Readiness
+
+Adapt this section for the repository. For pure CLI/library repos, full verify
+may be enough. If the project needs services, auth, seeded data, or a sample
+workflow, document the required credentials/default data and wire a smoke into
+`HARNESS_READINESS_CMD` or full verify.
+
 ## 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 when runtime services are involved
 - [ ] When `stages/browser-e2e.sh` exists, full verify includes Playwright — adapt specs under `tests/` for UI changes
 - [ ] New behavior has automated test coverage
 - [ ] Changes committed **in the session worktree** with a clear message

package/dist/templates/har-boilerplate-cli/README.md

@@ -59,7 +59,12 @@ Read **`stages.json`** and **`verificationStages`**. Optional: `har env add-stag
 | Mode | Command | Typical steps |
 |------|---------|---------------|
 | Quick | `har env verify <id>` or `verify.sh <id>` | typecheck, unit tests |
-| Full | `har env verify <id> --full` or `verify.sh <id> --full` | + lint, build, **browser-e2e** when `stages/browser-e2e.sh` exists |
+| Full | `har env verify <id> --full` or `verify.sh <id> --full` | + lint, optional readiness smoke, **browser-e2e** when `stages/browser-e2e.sh` exists |
+
+For repos that need runtime services, distinguish health from usability. If the
+harness skips slow local-dev setup, document the skipped steps and add a minimal
+bootstrap/readiness check when agents need default data, credentials, or an
+authenticated workflow.
 
 Use `har env launch 1 --no-worktree` or `./.har/launch.sh 1 --no-worktree` only when working in the repo root.