@osfactory/har 0.5.0 → 0.7.0

package/dist/prompts/system-authoring.md

@@ -104,12 +104,36 @@ If the repository contains more than one project or `.har` harness (check for `.
 - Keep a small `AGENT.md` / `CLAUDE.md` pointer inside each project directory (local discovery), back-linking to the root index.
 - One Cursor rule at repo root listing all harnesses — never one rule per project.
 
-## Port allocation
+## Port allocation & shared services
 
-Agents run in parallel on configurable slot ids. Ports: `BASE + (AGENT_ID × 10)`.
+Document ports in `.har/README.md` and configure them in `.har/harness.env`. Resolved values land in `.env.agent.<id>` and `.har/slots/agent-<id>.json` at launch — never hardcode defaults in app code or tests.
+
+### Per-slot app ports (default / PM2 profile)
+
+| Layer | Scope | Rule | On conflict |
+|-------|-------|------|-------------|
+| Frontend | Per slot | `HARNESS_FE_BASE_PORT + (AGENT_ID × HARNESS_PORT_STEP)` | Scan `STEP` increments within the slot lane |
+| API | Per slot | `HARNESS_API_BASE_PORT + (AGENT_ID × STEP)` | Same scan policy |
+| Node debug | Per slot | `9200 + (AGENT_ID × STEP)` | Same scan policy |
+
+### Shared infra ports (when listed in `HARNESS_INFRA_SERVICES`)
+
+| Service | Default var | On conflict |
+|---------|-------------|-------------|
+| Postgres | `HARNESS_DB_PORT_DEFAULT` | Scan `HARNESS_DB_PORT_SCAN_START..END` |
+| MinIO | `HARNESS_MINIO_PORT_DEFAULT` (+ console) | Scan configured ranges in `harness.env` |
+| Mailpit | `HARNESS_MAILPIT_*_PORT_DEFAULT` | Scan configured ranges |
+| Headless browser | `HARNESS_BROWSER_PORT_DEFAULT` | Scan configured ranges |
+
+CLI and iOS profiles typically have no per-slot app ports; optional backends still use the shared-infra model.
 
 Set slot limits in `.har/stages.json` (`agentSlots`) and `.har/harness.env` (`HARNESS_AGENT_SLOT_MIN` / `HARNESS_AGENT_SLOT_MAX`) based on machine capacity.
 
+### Do not
+
+- Hardcode `3000`, `15432`, `3847`, or other defaults in application code, tests, or agent docs
+- Run raw `docker compose` for harness infrastructure — use `setup-infra.sh` / `launch.sh`
+
 ## Rules
 
 1. **Edit .har/ files directly** — no YAML runtime config
@@ -120,6 +144,7 @@ Set slot limits in `.har/stages.json` (`agentSlots`) and `.har/harness.env` (`HA
 6. **Do not edit manifest.json** — managed by har CLI
 7. **Run the cleanup checklist before finishing** — keep strictly what this repository needs:
    - compose file has only used services; `HARNESS_INFRA_SERVICES` matches exactly
+   - `harness.env` has port documentation vars for every enabled infra service; `.har/README.md` explains allocation and shared vs per-slot
    - `env.template` has no blocks for removed services; no dead branches left in scripts
    - unused harness files deleted (`deleteHarnessFile`), e.g. `attach.sh` when unused
    - `.har/README.md` file table matches the files that actually exist

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

@@ -6,6 +6,24 @@ Explore this repository, then edit files in `.har/` directly to make the harness
 
 **Do NOT** create a YAML config or JSON mapping file for runtime behavior. Put behavior directly in the harness scripts and templates.
 
+## HAR profiles (pick the right one at init)
+
+`har env init` scaffolds from one of three boilerplate profiles — **choose the profile that matches this repository**:
+
+| Profile | Best for | What you get |
+|---------|----------|--------------|
+| `default` | **SaaS / web apps** (Next.js, Rails, full-stack, etc.) | Docker Compose shared infra, PM2 for primary app, per-slot ports and preview URLs |
+| `cli` | **CLI tools, libraries, test-suite repos** (typical SWE-bench) | Git worktree by default, no PM2; optional Docker for databases; run project commands in isolation |
+| `ios` | **Mobile iOS / Swift** | xcodebuild + iOS Simulator; scheme/project/simulator in `harness.env` |
+
+```bash
+har env init                  # default (SaaS/web)
+har env init --profile cli    # libraries / CLI / polyglot test repos
+har env init --profile ios    # iOS apps
+```
+
+Do **not** disable worktrees, rewrite launch into repo-root-only mode, or pick the wrong profile unless the project truly requires it.
+
 ## Profile: {{PROFILE}}
 
 {{PROFILE_HINT}}
@@ -38,13 +56,18 @@ Clear index of the harness: what each file does, quick start, architecture, how
 ### `.har/harness.env`
 Primary app, ports, `HARNESS_INFRA_SERVICES`, migrate/seed commands, health check path.
 
+**Toolchain provisioning:** set `HARNESS_ECOSYSTEM` (`auto` detects from manifests) and optional `HARNESS_INSTALL_CMD`. Launch runs `provision-toolchain.sh`, writes resolved paths (`PYTHON_BIN`, `NODE_BIN`, `NPM_BIN`, `XCODEBUILD_BIN`, …) into `.env.agent.<id>`. Verify steps **must** use those paths — never hardcode venv or interpreter locations.
+
 ### `.har/ecosystem.agent.template.cjs` (default profile only)
 PM2 processes for the primary application only, matching how it runs in dev. Skip entirely for the CLI profile.
 
 ### `.har/verify.sh`
 Adapt verification for this repository's toolchain. Step lists in the template are
 **examples, not exhaustive** — add, remove, or reorder `run_step` calls to match
-how this project is built and tested.
+how this project is built and tested. Use toolchain variables from `.env.agent.<id>`
+(e.g. `${NPM_BIN:-npm}`, `${PYTHON_BIN:-python3}`, `${XCODEBUILD_BIN:-xcodebuild}`).
+The stock verify section is keyed by `HARNESS_ECOSYSTEM`; it is a starting point,
+not the repo's final contract. Replace conventions that do not match this project.
 
 **Tier contract:**
 
@@ -56,6 +79,7 @@ how this project is built and tested.
 - **Quick** must stay fast and minimal (syntax, compile, import smoke) — not the full test suite.
 - **Full** holds unit tests, lint, and heavier checks; optional Playwright runs on `--full` when installed.
 - Reuse real commands from `package.json`, `Makefile`, CI, `pyproject.toml`, etc.
+- Remove stock npm/pytest/go/cargo/maven/gradle examples that do not apply.
 - Replace all TODO placeholders in both tiers.
 
 ### Readiness vs liveness (required)
@@ -88,8 +112,9 @@ scripts or document why no substitute is needed. In particular:
   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`.
+- Ensure `launch.sh` writes the slot registry before slow or fragile steps, runs
+  `provision-toolchain.sh` to install deps and record toolchain paths in
+  `.env.agent.<id>`, 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):
@@ -107,10 +132,38 @@ Detailed agent instructions: commands, credentials, architecture, definition of
 ### `.har/env.template`, `setup-infra.sh`, `docker-compose.agent.yml`
 Adapt as needed for the project's infra.
 
-### Port allocation
-Agents run in parallel on configurable slot ids. Ports: `BASE + (AGENT_ID × 10)`.
+### Port allocation & shared services
+
+Document and configure ports in `.har/harness.env` and `.har/README.md`. Use the bundled template's port-allocation block as the contract — do not hardcode ports in app code or tests.
+
+**Per-slot app ports** (default / PM2 profile only):
+
+| Layer | Scope | Rule | On conflict |
+|-------|-------|------|-------------|
+| Frontend | Per slot | `HARNESS_FE_BASE_PORT + (AGENT_ID × HARNESS_PORT_STEP)` | Scan `STEP` increments within the slot lane |
+| API | Per slot | `HARNESS_API_BASE_PORT + (AGENT_ID × STEP)` | Same scan policy |
+| Node debug | Per slot | `9200 + (AGENT_ID × STEP)` | Same scan policy |
+
+**Shared infra ports** (one per machine, all profiles when the service is in `HARNESS_INFRA_SERVICES`):
+
+| Service | Default var | On conflict |
+|---------|-------------|-------------|
+| Postgres | `HARNESS_DB_PORT_DEFAULT` | Scan `HARNESS_DB_PORT_SCAN_START..END` |
+| MinIO | `HARNESS_MINIO_PORT_DEFAULT` (+ console) | Scan configured ranges |
+| Mailpit | `HARNESS_MAILPIT_*_PORT_DEFAULT` | Scan configured ranges |
+| Headless browser | `HARNESS_BROWSER_PORT_DEFAULT` | Scan configured ranges |
+
 Set slot limits in `.har/stages.json` (`agentSlots`) and `.har/harness.env` (`HARNESS_AGENT_SLOT_MIN` / `HARNESS_AGENT_SLOT_MAX`) based on machine capacity.
 
+**Port / infra checklist:**
+
+- [ ] `.har/harness.env` has `HARNESS_FE_BASE_PORT`, `HARNESS_API_BASE_PORT`, `HARNESS_PORT_STEP` (default profile) or explains why they are absent (CLI/iOS)
+- [ ] For each service in `HARNESS_INFRA_SERVICES`, matching `HARNESS_*_PORT_DEFAULT` and `SCAN_*` vars exist in `harness.env`
+- [ ] `.har/README.md` has a **Port & shared services** section (allocation table, shared vs per-slot, do-not rules)
+- [ ] App code and tests read ports from `.env.agent.<id>` / `agent-cli.sh` / slot registry — no hardcoded `3000`, `15432`, `3847`, etc.
+- [ ] `env.template` and `CLAUDE.agent.md` show resolved ports via variables, not literals
+- [ ] Monorepos with `har control up`: document slot-1 conflict if the app port overlaps (e.g. Mission Control on 3847)
+
 ### Git worktree
 `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.
 
@@ -162,6 +215,8 @@ The boilerplate ships more than any single repository needs. Strip it down to st
 - [ ] 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
+- [ ] `.har/README.md` documents port allocation and shared-service model; `harness.env` has the port knobs for every enabled infra service
+- [ ] No hardcoded default ports (`3000`, `15432`, `3847`, …) in app code, tests, or harness docs — use agent env / slot registry
 
 ## Rules
 

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

@@ -6,6 +6,8 @@ The harness already exists. Inspect what changed in the repo since the harness w
 
 **Do NOT** create a YAML config or JSON mapping file for runtime behavior. Put behavior directly in the harness scripts and templates.
 
+{{MAINTAIN_BUNDLE_SECTION}}
+
 ## Step 1 — Inspect the repository
 
 Compare the current repo against the existing harness:
@@ -13,7 +15,7 @@ Compare the current repo against the existing harness:
 - Root manifests, CI, Docker, README
 - New or changed test, lint, build, migrate, or seed commands
 - New services, ports, or environment variables
-- Run `har env maintain` drift report (generator version, template checksum mismatches)
+- Review `.har/maintain/drift-report.json` (generator version, template drift, **missing port documentation vars**)
 
 ## Step 2 — Update `.har/` files
 
@@ -22,8 +24,8 @@ Prefer targeted edits over full rewrites. Key files to review:
 ### `.har/README.md` (required)
 Keep this accurate — it is the harness index. Update whenever scripts, stages, or workflow change.
 
-### `.har/harness.env`, `verify.sh`, `ecosystem.agent.template.cjs`, `CLAUDE.agent.md`
-Align commands and instructions with the current stack.
+### `.har/harness.env`, `verify.sh`, `provision-toolchain.sh`, `ecosystem.agent.template.cjs`, `CLAUDE.agent.md`
+Align commands and instructions with the current stack. Verify steps must use toolchain paths from `.env.agent.<id>` (`PYTHON_BIN`, `NPM_BIN`, `XCODEBUILD_BIN`, …) — never hardcoded venv or interpreter paths. Replace stock ecosystem conventions that do not match the repository; do not leave npm/pytest/go/cargo/maven/gradle examples in place by accident.
 
 ### `.har/env.template`, `setup-infra.sh`, `docker-compose.agent.yml`
 Update only if infra changed.
@@ -64,9 +66,10 @@ When upgrading `@osfactory/har` or adopting new harness standards:
 
 **Generator 0.4.0 — primary app & shared infra services:**
 
-- Migrate `harness.env` from boolean `HARNESS_INFRA_*` flags to the `HARNESS_INFRA_SERVICES` list (space-separated compose service names, e.g. `"db mailpit"`) and add the `har_infra_enabled()` helper — copy both from the bundled template. Update every script that still tests `HARNESS_INFRA_POSTGRES`-style flags (`setup-infra.sh`, `launch.sh`, `teardown.sh`, `agent-cli.sh`) to use `har_infra_enabled <service>`.
+- Migrate `harness.env` from boolean `HARNESS_INFRA_*` flags to the `HARNESS_INFRA_SERVICES` list (space-separated compose service names, e.g. `"db mailpit"`) and add the `har_infra_enabled()` helper — copy both from `.har/maintain/templates/harness.env`. Update every script that still tests `HARNESS_INFRA_POSTGRES`-style flags (`setup-infra.sh`, `launch.sh`, `teardown.sh`, `agent-cli.sh`) to use `har_infra_enabled <service>`.
 - Set `HARNESS_PRIMARY_APP` in `harness.env` to the ONE app agents modify. Ensure `ecosystem.agent.template.cjs` starts only that app's processes. Move any other in-repo services agents depend on but don't change to shared infra: compose services in `docker-compose.agent.yml` or an optional `.har/ecosystem.shared.config.cjs` (processes `har-shared-<name>`; `setup-infra.sh` starts it when present — resync `setup-infra.sh` from the template to get this hook).
 - Prune `docker-compose.agent.yml` to only the services this project uses; delete unused menu services and volumes.
+- **Port & shared services:** ensure `.har/README.md` documents the allocation table and shared vs per-slot model; `harness.env` has every `HARNESS_*_PORT_*` var required for services in `HARNESS_INFRA_SERVICES` (copy missing vars from `.har/maintain/templates/harness.env` when drift reports them). Remove hardcoded ports from app code, tests, and `CLAUDE.agent.md`.
 - Run the **cleanup checklist**: no TODO placeholders, no env blocks for removed services in `env.template`, no dead script branches, `.har/README.md` file table matches the actual files, `CLAUDE.agent.md` shows only real URLs/ports and commands, unused files deleted.
 
 **Earlier standards:**

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

@@ -50,10 +50,12 @@ Quick loop during development: MCP `har_run_verification`, `har env verify ${AGE
 ## Project commands
 
 ```bash
-# TODO: adapt for this repository (see package.json, Makefile, etc.)
+# TODO: adapt for this repository (see package.json, Makefile, pyproject.toml, CI, etc.)
 # npm run typecheck
-# npm test
-# npm run lint
+# pytest -q
+# go test ./...
+# cargo test
+# make test
 ```
 
 ## Do not

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

@@ -12,14 +12,15 @@ Generated and maintained by [`har`](https://github.com/antoineFrau/har). Run `ha
 |------|---------|
 | `README.md` | This file — index of the harness |
 | `manifest.json` | Generator metadata (version, checksums) — do not edit |
-| `harness.env` | Shared config: primary app, ports, agent slot limits, `HARNESS_INFRA_SERVICES`, migrate/seed commands |
+| `harness.env` | Shared config: primary app, ports, agent slot limits, `HARNESS_INFRA_SERVICES`, toolchain provisioning, migrate/seed commands |
 | `stages.json` | Machine-readable registry of runnable harness stages |
 | `stages/` | Optional custom stage scripts registered from `stages.json` |
 | `runs/` | Run history from `har env` / MCP only — `.har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json` (gitignore) |
 | `artifacts/` | Stage outputs: reports, traces, screenshots, logs |
 | `agent-slot.sh` | Shared agent-id validation (reads limits from `harness.env`) |
 | `setup-infra.sh` | Start shared Docker infra + create template database |
-| `launch.sh` | Launch one agent slot (ports, DB clone, PM2 processes) |
+| `launch.sh` | Launch one agent slot (ports, DB clone, toolchain provisioning, PM2 processes) |
+| `provision-toolchain.sh` | Install deps and write toolchain paths to `.env.agent.<id>` |
 | `verify.sh` | Verification pipeline (smoke by default; --full adds tests, lint, e2e) |
 | `teardown.sh` | Tear down one agent slot |
 | `agent-cli.sh` | Manage a running agent (status, logs, psql, health) |
@@ -49,8 +50,8 @@ In Cursor with HAR MCP configured: use `har_launch_environment`, `har_run_verifi
 ```bash
 ./.har/setup-infra.sh          # when HARNESS_INFRA_SERVICES is non-empty
 ./.har/launch.sh 1
-./.har/verify.sh 1             # quick: smoke (typecheck + health)
-./.har/verify.sh 1 --full      # + unit tests, lint, browser-e2e (if Playwright stage installed)
+./.har/verify.sh 1             # quick: ecosystem smoke + health
+./.har/verify.sh 1 --full      # + conventional tests/lint, browser-e2e (if installed)
 ./.har/teardown.sh 1
 ```
 
@@ -64,8 +65,13 @@ not a fixed command list.
 
 | Mode | Command | Typical steps |
 |------|---------|---------------|
-| Quick | `har env verify <id>` or `verify.sh <id>` | Smoke: compile / typecheck / health (stops early on failure) |
-| Full | `har env verify <id> --full` or `verify.sh <id> --full` | + unit tests, lint, optional readiness smoke + **`browser-e2e`** when `.har/stages/browser-e2e.sh` exists |
+| Quick | `har env verify <id>` or `verify.sh <id>` | Stock ecosystem smoke + health (stops early on failure) |
+| Full | `har env verify <id> --full` or `verify.sh <id> --full` | Stock conventional tests/lint, optional readiness smoke + **`browser-e2e`** when `.har/stages/browser-e2e.sh` exists |
+
+The stock commands are deliberately generic conventions keyed by
+`HARNESS_ECOSYSTEM`. Replace them with the repository's real commands during
+adaptation; do not leave Node/npm, Python, Go, Rust, Java, or Ruby defaults in
+place when they do not match the project.
 
 Install Playwright stage: `har env add-stage playwright` (optional). UI changes should add or update specs under `tests/`.
 
@@ -107,14 +113,48 @@ Always use `./.har/agent-cli.sh <id> ...` — never hardcoded ports.
 
 ## Architecture
 
-Each agent slot gets isolated ports: `BASE + (AGENT_ID × 10)`.
+Each agent slot gets isolated app ports. Defaults follow `BASE + (AGENT_ID × HARNESS_PORT_STEP)`; when a default is busy, `launch.sh` scans the slot lane (`STEP` increments) and writes the resolved ports to `.env.agent.<id>` and `.har/slots/agent-<id>.json`.
 
 Configure how many slots your machine can run in parallel in `stages.json` (`agentSlots`) and `harness.env` (`HARNESS_AGENT_SLOT_MIN` / `HARNESS_AGENT_SLOT_MAX`). Keep both in sync.
 
-| Service | Agent 1 | Agent 2 |
-|---------|---------|---------|
+| Service | Agent 1 (default) | Agent 2 (default) |
+|---------|-------------------|-------------------|
 | Frontend | 3010 | 3020 |
 | API | 8010 | 8020 |
+| Node debug | 9210 | 9220 |
+
+## Port & shared services
+
+### Port allocation
+
+| Layer | Scope | Rule | On conflict |
+|-------|-------|------|-------------|
+| App — frontend | Per slot | `HARNESS_FE_BASE_PORT + (AGENT_ID × HARNESS_PORT_STEP)` | Scan `STEP` increments within the slot lane |
+| App — API | Per slot | `HARNESS_API_BASE_PORT + (AGENT_ID × STEP)` | Same scan policy |
+| Node debug | Per slot | `9200 + (AGENT_ID × STEP)` | Same scan policy |
+| Shared Postgres | Per machine | `HARNESS_DB_PORT_DEFAULT` | Scan `HARNESS_DB_PORT_SCAN_START..END` |
+| MinIO / S3 | Per machine | `HARNESS_MINIO_PORT_DEFAULT` (+ console port) | Scan configured ranges in `harness.env` |
+| Mailpit | Per machine | `HARNESS_MAILPIT_*_PORT_DEFAULT` | Scan configured ranges |
+| Headless browser | Per machine | `HARNESS_BROWSER_PORT_DEFAULT` | Scan configured ranges |
+
+Resolved ports may differ from the formula when something else is already bound. Always use `./.har/agent-cli.sh <id>` or read `.har/slots/agent-<id>.json` — never hardcode `3010`, `15432`, etc. in app code or tests.
+
+### Shared vs per-slot
+
+| Resource | Model | Configuration |
+|----------|-------|---------------|
+| Postgres | One shared container; per-slot database `agent_<id>` cloned from template | `HARNESS_INFRA_SERVICES="db"` |
+| MinIO / S3 | One shared container; per-slot bucket `agent-<id>` | `HARNESS_INFRA_SERVICES="... minio"` |
+| Mailpit, Redis, etc. | One shared container on a scanned host port | Listed in `HARNESS_INFRA_SERVICES` |
+| Primary application | One PM2 ecosystem per slot (isolated ports) | `HARNESS_PRIMARY_APP`, `ecosystem.agent.template.cjs` |
+| Internal supporting services | Shared across all slots | `docker-compose.agent.yml` or `ecosystem.shared.config.cjs` |
+
+Shared infra starts once via `./.har/setup-infra.sh` (also run automatically by `launch.sh`). Per-slot databases are cloned in `launch.sh`.
+
+### Do not
+
+- Hardcode default ports (`3000`, `15432`, `3847`, …) in application code, tests, or agent docs — read from `.env.agent.<id>`, `agent-cli.sh`, or the slot registry
+- Run raw `docker compose` for harness infrastructure — use `setup-infra.sh` / `launch.sh` so ports are scanned and persisted in `.har/state/infra.env`
 
 ### Primary app vs shared services
 
@@ -150,6 +190,8 @@ work dir printed by launch, never in the main checkout.
   after explicit user approval.
 - `teardown` removes the worktree but **keeps the session branch** so you can push it
   or open a PR (`--delete-branch` to drop it).
+- If launch fails after creating a worktree/env file, the registry records `status: failed`.
+  Resume without `--replace`: `har env launch <id> --resume` or `har env recover <id>`.
 - `har env complete <id>` finishes a session: full verify (recorded as a validation),
   then teardown — branch kept.
 - `--no-worktree` runs the slot from the repo root instead (single-agent mode).

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

@@ -17,51 +17,94 @@ COMMAND="${2:?Usage: agent-cli.sh <agent-id> <command> [args...]}"
 
 validate_agent_id "$AGENT_ID"
 
-FE_PORT=$(( HARNESS_FE_BASE_PORT + AGENT_ID * 10 ))
-API_PORT=$(( HARNESS_API_BASE_PORT + AGENT_ID * 10 ))
-DB_PORT="${AGENT_DB_PORT:-15432}"
+load_agent_ports "$AGENT_ID" "$REPO_ROOT"
+DB_PORT="${DB_PORT:-${AGENT_DB_PORT:-${HARNESS_DB_PORT_DEFAULT:-15432}}}"
 export PGPASSWORD="password"
 
+PM2_SLOT_PREFIX="$(har_pm2_slot_prefix "$AGENT_ID")"
+
 case "$COMMAND" in
   status)
     ENV_FILE="$(resolve_agent_env_file "$AGENT_ID" "$REPO_ROOT" || true)"
     WORKTREE_DIR="$(existing_slot_worktree "$AGENT_ID")"
-
+    REG_FILE="$(slot_registry_file "$AGENT_ID")"
     PM2_RAW=$(npx --yes pm2 jlist 2>/dev/null || true)
     PM2_FOUND=false
+    PM2_FOREIGN=false
+    PM2_LEGACY=false
 
     if [ -n "$PM2_RAW" ]; then
+      set +e
       echo "$PM2_RAW" | node -e "
 const agentId = '${AGENT_ID}';
+const project = '${HARNESS_PROJECT_NAME}';
+const slotPrefix = 'har-' + project + '-agent-' + agentId + '-';
+const legacyPrefix = 'agent-' + agentId + '-';
 let raw = '';
 process.stdin.on('data', c => raw += c);
 process.stdin.on('end', () => {
   try {
     const arr = JSON.parse(raw);
     if (!Array.isArray(arr)) process.exit(1);
-    const procs = arr.filter(x => x.name && x.name.startsWith('agent-' + agentId + '-'));
-    if (procs.length === 0) process.exit(1);
-    console.log('Agent ' + agentId + ' processes:');
-    procs.forEach(p => {
-      const s = (p.pm2_env?.status || 'unknown').padEnd(10);
-      const mem = Math.round((p.monit?.memory || 0) / 1024 / 1024) + 'MB';
-      const cpu = (p.monit?.cpu || 0) + '%';
-      console.log('  ' + p.name.padEnd(42) + s + '  mem=' + mem + '  cpu=' + cpu);
-    });
+    const owned = arr.filter(x => x.name && x.name.startsWith(slotPrefix));
+    const foreignProject = arr.filter(x =>
+      x.name && x.name.startsWith('har-') && x.name.includes('-agent-' + agentId + '-') && !x.name.startsWith(slotPrefix));
+    const legacy = arr.filter(x => x.name && x.name.startsWith(legacyPrefix) && !x.name.startsWith('har-'));
+    if (owned.length > 0) {
+      console.log('Agent ' + agentId + ' processes (' + project + '):');
+      owned.forEach(p => {
+        const s = (p.pm2_env?.status || 'unknown').padEnd(10);
+        const mem = Math.round((p.monit?.memory || 0) / 1024 / 1024) + 'MB';
+        const cpu = (p.monit?.cpu || 0) + '%';
+        const cwd = p.pm2_env?.pm_cwd || p.pm2_env?.cwd || '';
+        console.log('  ' + p.name.padEnd(48) + s + '  mem=' + mem + '  cpu=' + cpu);
+        if (cwd) console.log('    cwd: ' + cwd);
+      });
+      process.exit(0);
+    }
+    if (foreignProject.length > 0 || legacy.length > 0) {
+      if (foreignProject.length > 0) {
+        console.log('ERROR: foreign PM2 processes match agent ' + agentId + ' but belong to another harness:');
+        foreignProject.forEach(p => console.log('  ' + p.name + '  cwd=' + (p.pm2_env?.pm_cwd || p.pm2_env?.cwd || 'unknown')));
+      }
+      if (legacy.length > 0) {
+        console.log('ERROR: legacy PM2 processes (pre project-scoping) match agent ' + agentId + ':');
+        legacy.forEach(p => console.log('  ' + p.name + '  cwd=' + (p.pm2_env?.pm_cwd || p.pm2_env?.cwd || 'unknown')));
+      }
+      process.exit(2);
+    }
+    process.exit(1);
   } catch {
     process.exit(1);
   }
 });
-" && PM2_FOUND=true
+"
+      pm2_status=$?
+      set -e
+      case "$pm2_status" in
+        0) PM2_FOUND=true ;;
+        2) PM2_FOREIGN=true ;;
+      esac
+    fi
+
+    if [ "$PM2_FOREIGN" = true ]; then
+      exit 1
     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."
+        echo "ERROR: slot registry missing at $REG_FILE but PM2 processes exist for this project." >&2
+        echo "  Another harness may have been torn down incorrectly, or this slot was started outside launch.sh." >&2
+        exit 1
+      fi
+      REG_PROJECT="$(read_slot_field "$REG_FILE" projectName || true)"
+      if [ -n "$REG_PROJECT" ] && [ "$REG_PROJECT" != "$HARNESS_PROJECT_NAME" ]; then
+        echo "ERROR: slot registry projectName=${REG_PROJECT} does not match harness ${HARNESS_PROJECT_NAME}." >&2
+        exit 1
       fi
       if [ -z "$ENV_FILE" ]; then
-        echo "Warning: .env.agent.${AGENT_ID} could not be resolved — relaunch with --replace when ready."
+        echo "ERROR: .env.agent.${AGENT_ID} could not be resolved — relaunch with --replace when ready." >&2
+        exit 1
       fi
     elif [ -n "$ENV_FILE" ] && [ -f "$ENV_FILE" ]; then
       echo "Agent ${AGENT_ID}: active (no PM2 processes)"
@@ -69,6 +112,8 @@ process.stdin.on('end', () => {
       source "$ENV_FILE" 2>/dev/null || true
       echo "  Work dir:  $(resolve_agent_work_dir "$ENV_FILE" "$AGENT_ID")"
       [ -n "$WORKTREE_DIR" ] && [ -d "$WORKTREE_DIR" ] && echo "  Worktree:  $WORKTREE_DIR"
+      echo "  Frontend:  http://localhost:${FE_PORT}"
+      echo "  API:       http://localhost:${API_PORT}"
     else
       echo "No active environment for agent ${AGENT_ID}"
       echo "  Run: ./.har/launch.sh ${AGENT_ID}"
@@ -78,22 +123,23 @@ process.stdin.on('end', () => {
   logs)
     SERVICE="${3:-}"
     if [ -n "$SERVICE" ]; then
-      npx pm2 logs "agent-${AGENT_ID}-${SERVICE}" --lines 100
+      npx pm2 logs "${PM2_SLOT_PREFIX}-${SERVICE}" --lines 100
     else
-      npx pm2 logs --name "agent-${AGENT_ID}" --lines 100
+      npx pm2 logs --name "${PM2_SLOT_PREFIX}" --lines 100
     fi
     ;;
 
   restart)
     SERVICE="${3:-}"
     if [ -n "$SERVICE" ]; then
-      npx pm2 restart "agent-${AGENT_ID}-${SERVICE}"
+      npx pm2 restart "${PM2_SLOT_PREFIX}-${SERVICE}"
     else
       npx pm2 jlist 2>/dev/null | node -e "
+const prefix = '${PM2_SLOT_PREFIX}-';
 const d = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
-const names = d.filter(x => x.name.startsWith('agent-${AGENT_ID}-')).map(x => x.name);
+const names = d.filter(x => x.name && x.name.startsWith(prefix)).map(x => x.name);
 names.forEach(n => require('child_process').execSync('npx pm2 restart ' + n, {stdio:'inherit'}));
-if (names.length === 0) console.log('No processes found for agent ${AGENT_ID}');
+if (names.length === 0) console.log('No processes found for ${PM2_SLOT_PREFIX}');
 " 2>/dev/null || true
     fi
     ;;
@@ -122,9 +168,9 @@ try { console.log(JSON.stringify(JSON.parse(d), null, 2)); } catch { console.log
     echo "Frontend:  http://localhost:${FE_PORT}"
     echo "API:       http://localhost:${API_PORT}"
     har_infra_enabled db               && echo "Database:  agent_${AGENT_ID} @ localhost:${DB_PORT}"
-    har_infra_enabled minio            && echo "MinIO:     http://localhost:19001"
-    har_infra_enabled headless-browser && echo "Browser:   http://localhost:13001"
-    har_infra_enabled mailpit          && echo "Mailpit:   http://localhost:18025"
+    har_infra_enabled minio            && echo "MinIO:     http://localhost:${AGENT_MINIO_CONSOLE_PORT:-19001}"
+    har_infra_enabled headless-browser && echo "Browser:   http://localhost:${AGENT_BROWSER_PORT:-13001}"
+    har_infra_enabled mailpit          && echo "Mailpit:   http://localhost:${AGENT_MAILPIT_WEB_PORT:-18025}"
     ;;
 
   reset-db)
@@ -160,7 +206,7 @@ LIMIT 20;" 2>/dev/null || echo "pg_stat_statements extension not available"
     ;;
 
   attach)
-    SESSION="agent-${AGENT_ID}"
+    SESSION="$(har_tmux_session "$AGENT_ID")"
     if ! tmux has-session -t "$SESSION" 2>/dev/null; then
       echo "No tmux session found: $SESSION" >&2
       exit 1