@osfactory/har 0.1.1 → 0.3.0

package/dist/templates/har-boilerplate-cli/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-cli/harness.env

@@ -38,3 +38,11 @@ har_pg() {
 
 export HARNESS_DB_MIGRATE_CMD="true"
 export HARNESS_DB_SEED_CMD="true"
+
+# Optional readiness/data hooks for repositories that need more than static
+# CLI/library checks. Enable only when this project needs them, and keep scripts
+# idempotent.
+#
+# export HARNESS_TEMPLATE_DBS="main:template___PROJECT_NAME__"
+# export HARNESS_DB_MINIMAL_BOOTSTRAP_CMD="./.har/bootstrap-data.sh"
+# export HARNESS_READINESS_CMD="./.har/readiness.sh"

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

@@ -94,6 +94,46 @@ WORKTREE_DIR=${WORKTREE_DIR}
 NODE_ENV=test
 EOF
 
+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_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_STATUS="starting" \
+  write_slot_registry
+REGISTRY_WRITTEN=true
+
 if [ -f "$WORK_DIR/package.json" ]; then
   log "Installing dependencies..."
   (cd "$WORK_DIR" && npm install --silent)
@@ -118,6 +158,7 @@ SLOT_BRANCH="${BRANCH:-}" \
 SLOT_BASE_BRANCH="${BASE_BRANCH:-}" \
 SLOT_BASE_COMMIT="${BASE_COMMIT:-}" \
 SLOT_PURPOSE="${PURPOSE}" \
+SLOT_STATUS="active" \
   write_slot_registry
 
 log "Agent $AGENT_ID is ready."

package/dist/templates/har-boilerplate-cli/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-cli/verify.sh

@@ -35,9 +35,17 @@ set +a
 WORK_DIR="$(resolve_agent_work_dir "$ENV_FILE")"
 
 echo "==> Verifying agent ${AGENT_ID} in ${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() {
@@ -46,14 +54,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" && 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
@@ -67,9 +75,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');
@@ -90,10 +96,11 @@ run_step "unit-tests" "npm test" || { [ -z "$FULL" ] && true; }
 
 if [ -n "$FULL" ]; then
   run_step "lint" "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
 
-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-ios/CLAUDE.agent.md

@@ -17,9 +17,17 @@
 ./.har/agent-cli.sh ${AGENT_ID} status
 ```
 
+## Readiness
+
+Adapt this section for the repository. A successful build/test run does not
+always mean an agent can use the app. If the app needs a backend, credentials,
+seeded data, or a simulator flow, document it here and wire the smoke into
+`HARNESS_READINESS_CMD`, RocketSim flows, 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/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

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

@@ -67,7 +67,11 @@ This installs `.har/stages/rocketsim-flows.sh` and a `flows/` directory. Add flo
 | Mode | Command | Typical steps |
 |------|---------|---------------|
 | Quick | `har env verify <id>` | build, unit-tests |
-| Full | `har env verify <id> --full` | + lint, **rocketsim-flows** when installed |
+| Full | `har env verify <id> --full` | + lint, optional readiness smoke, **rocketsim-flows** when installed |
+
+For apps that depend on local backends, auth, seeded state, or simulator flows,
+distinguish build/test health from agent usability. Document any skipped full
+dev setup and add a readiness command when agents need a real workflow to pass.
 
 ## Configuration
 

package/dist/templates/har-boilerplate-ios/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-ios/harness.env

@@ -40,3 +40,7 @@ har_infra_enabled() {
     *) return 1 ;;
   esac
 }
+
+# Optional "agent usable" smoke beyond build/test, such as a simulator flow or
+# backend-auth check. Enable only when this project needs it.
+# export HARNESS_READINESS_CMD="./.har/readiness.sh"

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

@@ -94,6 +94,46 @@ WORKTREE_DIR=${WORKTREE_DIR}
 NODE_ENV=test
 EOF
 
+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_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_STATUS="starting" \
+  write_slot_registry
+REGISTRY_WRITTEN=true
+
 if [ -f "$WORK_DIR/package.json" ]; then
   log "Installing dependencies..."
   (cd "$WORK_DIR" && npm install --silent)
@@ -118,6 +158,7 @@ SLOT_BRANCH="${BRANCH:-}" \
 SLOT_BASE_BRANCH="${BASE_BRANCH:-}" \
 SLOT_BASE_COMMIT="${BASE_COMMIT:-}" \
 SLOT_PURPOSE="${PURPOSE}" \
+SLOT_STATUS="active" \
   write_slot_registry
 
 log "Agent $AGENT_ID is ready."

package/dist/templates/har-boilerplate-ios/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-ios/verify.sh

@@ -38,6 +38,14 @@ set +a
 WORK_DIR="$(resolve_agent_work_dir "$ENV_FILE")"
 
 echo "==> Verifying agent ${AGENT_ID} in ${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
 
 # Build xcodebuild project/workspace flags
 xc_target_flags() {
@@ -62,7 +70,7 @@ XC_DESTINATION="${HARNESS_IOS_DESTINATION:-platform=iOS Simulator,name=iPhone 16
 XC_DERIVED="${WORK_DIR}/build/DerivedData"
 
 OVERALL_PASS=true
-START_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+START_TOTAL=$(now_ms)
 RESULTS_JSON="[]"
 
 run_step() {
@@ -71,14 +79,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" && 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
@@ -92,9 +100,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');
@@ -141,11 +147,13 @@ if [ -n "$FULL" ]; then
   run_step "lint" "command -v \"${HARNESS_SWIFTLINT_CMD:-swiftlint}\" >/dev/null 2>&1 && \
     \"${HARNESS_SWIFTLINT_CMD:-swiftlint}\" --quiet 2>&1 || echo 'swiftlint not installed — skipping'" || true
 
+  run_step "readiness" "run_readiness_if_configured \"$AGENT_ID\"" || true
+
   # RocketSim user-flow validation — installed via: har env add-stage rocketsim
   run_rocketsim_flows_if_present "$SCRIPT_DIR" "$AGENT_ID" || true
 fi
 
-END_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+END_TOTAL=$(now_ms)
 TOTAL_MS=$(( END_TOTAL - START_TOTAL ))
 
 node -e "

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osfactory/har",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "LLM-powered CLI for reproducible agent development environments",
   "keywords": [
     "har",
@@ -40,6 +40,11 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/exec": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/npm": "^13.1.5",
     "@types/inquirer": "^9.0.7",
     "@types/jest": "^29.5.12",
     "@types/js-yaml": "^4.0.9",
@@ -49,11 +54,6 @@
     "@typescript-eslint/parser": "^8.62.0",
     "esbuild": "^0.23.0",
     "eslint": "^8.57.1",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/exec": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^11.0.1",
-    "@semantic-release/npm": "^12.0.1",
     "jest": "^29.7.0",
     "semantic-release": "^24.2.3",
     "ts-jest": "^29.2.4",
@@ -73,6 +73,6 @@
   "license": "AGPL-3.0-only",
   "publishConfig": {
     "access": "public",
-    "registry": "https://registry.npmjs.org"
+    "registry": "https://registry.npmjs.org/"
   }
 }