@osfactory/har 0.6.0 → 0.8.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

@@ -132,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.
 
@@ -187,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
 
@@ -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/README.md

@@ -113,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
 
@@ -156,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