@osfactory/har 0.2.0 → 0.4.0

package/README.md

@@ -39,11 +39,37 @@ npm install && npm run build && npm link
 
 See [AGENT.md](./AGENT.md) for architecture and coding-agent guidance, and [CONTRIBUTING.md](./CONTRIBUTING.md) for the full development workflow, testing on sample projects, and project layout. To report security issues, see [SECURITY.md](./SECURITY.md).
 
+## Harness profiles
+
+`har env init` scaffolds `.har/` from a boilerplate profile. Pick the one that matches what agents need to run — you only choose this once at init time.
+
+| Profile | Best for | What you get |
+|---------|----------|--------------|
+| `default` | Web apps (Next.js, Rails, Django, etc.) | Docker Compose for shared infra, PM2 for the primary app, per-slot ports and preview URLs |
+| `cli` | CLI tools, libraries, npm packages | No PM2 or port wiring — agents run project commands in an isolated git worktree; optional Docker for databases |
+| `ios` | iOS / Swift mobile apps | xcodebuild + iOS Simulator; configure scheme, project, and simulator in `harness.env` |
+
+```bash
+# Web app (default — omit --profile)
+cd my-web-app && har env init
+
+# CLI tool or library
+cd my-cli && har env init --profile cli
+
+# iOS app
+cd MyApp && har env init --profile ios
+har env add-stage rocketsim   # optional: UI flow validation on the simulator
+```
+
+After init, paste the printed adaptation prompt into your coding agent to tailor scripts to your stack. For built-in Claude adaptation: `har env init --auto` (requires `ANTHROPIC_API_KEY`).
+
+Optional stage templates depend on the profile: `har env add-stage playwright` for browser E2E on web apps, `har env add-stage rocketsim` for simulator user-flow checks on iOS.
+
 ## Quick start
 
 ```bash
 cd my-app
-har env init
+har env init                  # or --profile cli / --profile ios
 
 # Paste the printed prompt into your coding agent to adapt .har/ and AGENT.md
 git add .har/ AGENT.md
@@ -55,7 +81,7 @@ har env verify 1
 
 Shell fallback when the CLI is not installed: `./.har/setup-infra.sh`, `./.har/launch.sh 1`, `./.har/verify.sh 1`.
 
-For built-in Claude adaptation (requires `ANTHROPIC_API_KEY`): `har env init --auto`.
+See [Harness profiles](#harness-profiles) above if your repo is a CLI/library or iOS app rather than a web app.
 
 ## Repo layout after init
 
@@ -114,7 +140,7 @@ See `.har/stages/PLAYWRIGHT.md` in the target repo after applying the template.
 | `har control watch` | Continuously sync registered repos |
 | `har mcp` | Start the HAR MCP server (stdio) |
 
-Options: `--force`, `--auto` (built-in Claude adaptation), `--smoke`, `--yes` (auto-apply AGENT.md with `--auto`), `--verbose`, `--profile cli`
+Options: `--force`, `--auto` (built-in Claude adaptation), `--smoke`, `--yes` (auto-apply AGENT.md with `--auto`), `--verbose`, `--profile <default|cli|ios>`
 
 ## MCP Surface
 

package/dist/index.js

@@ -22989,7 +22989,8 @@ var SlotRegistryEntrySchema = external_exports.object({
   purpose: external_exports.string().optional(),
   ports: external_exports.record(external_exports.number()).optional(),
   previewUrls: external_exports.record(external_exports.string()).optional(),
-  status: external_exports.enum(["active", "completed"]).default("active")
+  status: external_exports.enum(["starting", "active", "failed", "completed"]).default("active"),
+  lastError: external_exports.string().optional()
 }).passthrough();
 var AgentSlotHarnessUsageSchema = external_exports.enum([
   "mcp",
@@ -23016,6 +23017,8 @@ var AgentSlotStatusSchema = external_exports.object({
   baseCommit: external_exports.string().optional(),
   sessionCreatedAt: external_exports.string().optional(),
   purpose: external_exports.string().optional(),
+  sessionStatus: external_exports.enum(["starting", "active", "failed", "completed"]).optional(),
+  lastError: external_exports.string().optional(),
   /** Worktree checked out to no branch (legacy failure mode; should not happen with sessions). */
   detachedHead: external_exports.boolean().optional(),
   /** Worktree has uncommitted changes. */
@@ -27864,10 +27867,11 @@ function listRegisteredRepos() {
 var fs23 = __toESM(require("fs"));
 var os4 = __toESM(require("os"));
 var path21 = __toESM(require("path"));
-var import_child_process2 = require("child_process");
+var import_child_process3 = require("child_process");
 
 // src/core/runs.ts
 var crypto2 = __toESM(require("crypto"));
+var import_child_process2 = require("child_process");
 var fs22 = __toESM(require("fs"));
 var os3 = __toESM(require("os"));
 var path20 = __toESM(require("path"));
@@ -27895,6 +27899,34 @@ function readSlotRegistry(repoPath, agentId) {
 
 // src/core/runs.ts
 var RUNS_DIR = "runs";
+function gitCommonDir(cwd) {
+  try {
+    const out = (0, import_child_process2.execSync)("git rev-parse --git-common-dir", {
+      cwd,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "ignore"]
+    }).trim();
+    return out ? path20.resolve(cwd, out) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function sameGitCheckout(a2, b2) {
+  const left2 = gitCommonDir(a2);
+  const right2 = gitCommonDir(b2);
+  return left2 !== void 0 && right2 !== void 0 && left2 === right2;
+}
+function gitPrefix(cwd) {
+  try {
+    return (0, import_child_process2.execSync)("git rev-parse --show-prefix", {
+      cwd,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return "";
+  }
+}
 function getRunsDir(harnessRoot) {
   return path20.join(getHarnessDir(harnessRoot), RUNS_DIR);
 }
@@ -27951,9 +27983,22 @@ function resolveAgentWorkDir(harnessRoot, agentId) {
   const env3 = readHarnessEnv(harnessRoot);
   const projectName = env3.HARNESS_PROJECT_NAME ?? path20.basename(harnessRoot);
   const worktreeDir = path20.join(os3.homedir(), "worktrees", `${projectName}-agent-${agentId}`);
+  const relPrefix = gitPrefix(harnessRoot);
+  const sessionEnvFiles = [];
+  const worktreesRoot = path20.join(os3.homedir(), "worktrees");
+  if (fs22.existsSync(worktreesRoot)) {
+    const suffix = `-har-agent-${agentId}-`;
+    for (const entry2 of fs22.readdirSync(worktreesRoot, { withFileTypes: true })) {
+      if (!entry2.isDirectory() || !entry2.name.includes(suffix)) continue;
+      const sessionDir = path20.join(worktreesRoot, entry2.name);
+      if (!sameGitCheckout(harnessRoot, sessionDir)) continue;
+      sessionEnvFiles.push(path20.join(sessionDir, relPrefix, `.env.agent.${agentId}`));
+    }
+  }
   const candidates = [
     path20.join(worktreeDir, `.env.agent.${agentId}`),
-    path20.join(harnessRoot, `.env.agent.${agentId}`)
+    path20.join(harnessRoot, `.env.agent.${agentId}`),
+    ...sessionEnvFiles.sort()
   ];
   for (const envFile of candidates) {
     if (!fs22.existsSync(envFile)) continue;
@@ -28040,7 +28085,7 @@ function listRuns(repoPath, filter = {}) {
 var BYPASS_WARNING_MS = 15 * 60 * 1e3;
 function readGitRemote(repoPath) {
   try {
-    const remote = (0, import_child_process2.execSync)("git remote get-url origin", {
+    const remote = (0, import_child_process3.execSync)("git remote get-url origin", {
       cwd: repoPath,
       encoding: "utf8",
       stdio: ["pipe", "pipe", "ignore"]
@@ -28052,7 +28097,7 @@ function readGitRemote(repoPath) {
 }
 function runGit(cwd, args) {
   try {
-    return (0, import_child_process2.execSync)(`git ${args}`, {
+    return (0, import_child_process3.execSync)(`git ${args}`, {
       cwd,
       encoding: "utf8",
       stdio: ["pipe", "pipe", "ignore"]
@@ -28064,6 +28109,29 @@ function runGit(cwd, args) {
 function readWorktreeBranch(worktreePath) {
   return runGit(worktreePath, "rev-parse --abbrev-ref HEAD");
 }
+function gitCommonDir2(cwd) {
+  const out = runGit(cwd, "rev-parse --git-common-dir");
+  return out ? path21.resolve(cwd, out) : void 0;
+}
+function sameGitCheckout2(a2, b2) {
+  const left2 = gitCommonDir2(a2);
+  const right2 = gitCommonDir2(b2);
+  return left2 !== void 0 && right2 !== void 0 && left2 === right2;
+}
+function gitPrefix2(cwd) {
+  const out = runGit(cwd, "rev-parse --show-prefix");
+  return out ?? "";
+}
+function discoverSessionWorktreePath(harnessRoot, agentId) {
+  const worktreesRoot = path21.join(os4.homedir(), "worktrees");
+  if (!fs23.existsSync(worktreesRoot)) return void 0;
+  const suffix = `-har-agent-${agentId}-`;
+  const relPrefix = gitPrefix2(harnessRoot);
+  const matches = fs23.readdirSync(worktreesRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory() && entry.name.includes(suffix)).map((entry) => path21.join(worktreesRoot, entry.name)).filter(
+    (candidate) => sameGitCheckout2(harnessRoot, candidate) && fs23.existsSync(path21.join(candidate, relPrefix, `.env.agent.${agentId}`))
+  );
+  return matches.sort()[0];
+}
 function collectWorktreeDrift(harnessRoot, worktreePath, baseCommit) {
   const drift = {};
   drift.detachedHead = runGit(worktreePath, "symbolic-ref -q HEAD") === void 0;
@@ -28112,12 +28180,12 @@ function collectSlotStatus(harnessRoot, agentId, runs) {
     "worktrees",
     `${projectName}-agent-${agentId}`
   );
-  const worktreePath = session?.worktreePath && fs23.existsSync(session.worktreePath) ? session.worktreePath : fs23.existsSync(legacyWorktreePath) ? legacyWorktreePath : void 0;
+  const worktreePath = session?.worktreePath && fs23.existsSync(session.worktreePath) ? session.worktreePath : fs23.existsSync(legacyWorktreePath) ? legacyWorktreePath : discoverSessionWorktreePath(harnessRoot, agentId);
   const workDir = resolveAgentWorkDir(harnessRoot, agentId);
   const envInWorkDir = workDir ? fs23.existsSync(path21.join(workDir, `.env.agent.${agentId}`)) : false;
   const envInRoot = fs23.existsSync(path21.join(harnessRoot, `.env.agent.${agentId}`));
   const envInWorktree = worktreePath ? fs23.existsSync(path21.join(worktreePath, `.env.agent.${agentId}`)) : false;
-  const active = session !== void 0 && session.status === "active" || envInWorkDir || envInRoot || envInWorktree;
+  const active = session !== void 0 && session.status !== "completed" || envInWorkDir || envInRoot || envInWorktree;
   const latest = latestRunForAgent(runs, agentId);
   const verifyRun = runs.find((r2) => r2.agentId === agentId && r2.stageId === "verify");
   let previewUrls = session?.previewUrls;
@@ -28147,6 +28215,8 @@ function collectSlotStatus(harnessRoot, agentId, runs) {
     baseCommit: session?.baseCommit,
     sessionCreatedAt: session?.createdAt,
     purpose: session?.purpose,
+    sessionStatus: session?.status,
+    lastError: session?.lastError,
     ...drift
   };
 }
@@ -28552,6 +28622,8 @@ function formatOccupiedSlot(slot) {
     slot.worktreePath ? `  Worktree: ${slot.worktreePath}` : void 0,
     slot.branch ? `  Branch:   ${slot.branch}` : void 0,
     slot.workDir ? `  Work dir: ${slot.workDir}` : void 0,
+    slot.sessionStatus ? `  Status:   ${slot.sessionStatus}` : void 0,
+    slot.lastError ? `  Error:    ${slot.lastError}` : void 0,
     slot.sessionCreatedAt ? `  Since:    ${slot.sessionCreatedAt}` : void 0,
     slot.dirty ? "  Git:      dirty (uncommitted changes \u2014 commit or use force to discard)" : "  Git:      clean",
     "",
@@ -29379,7 +29451,7 @@ function printNextSteps(auto2) {
 var path28 = __toESM(require("path"));
 
 // src/core/control-lifecycle.ts
-var import_child_process3 = require("child_process");
+var import_child_process4 = require("child_process");
 var path27 = __toESM(require("path"));
 
 // src/core/package-version.ts
@@ -29439,7 +29511,7 @@ function runDockerCompose(args, options) {
   const controlDir = resolveControlDir();
   const composeFiles = resolveControlComposeFiles(options);
   const composeArgs = composeFiles.flatMap((file) => ["-f", file]);
-  const result = (0, import_child_process3.spawnSync)("docker", ["compose", ...composeArgs, ...args], {
+  const result = (0, import_child_process4.spawnSync)("docker", ["compose", ...composeArgs, ...args], {
     cwd: controlDir,
     stdio: "inherit",
     env: buildDockerComposeEnv()

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
 }
 
@@ -278,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,6 +38,14 @@ 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=$(now_ms)
@@ -134,6 +142,7 @@ 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
 

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.
 

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
 }
 
@@ -278,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,6 +35,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
 
 OVERALL_PASS=true
 START_TOTAL=$(now_ms)
@@ -88,6 +96,7 @@ 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
 

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
 }
 
@@ -278,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() {
@@ -139,6 +147,8 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osfactory/har",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "LLM-powered CLI for reproducible agent development environments",
   "keywords": [
     "har",