@osfactory/har 0.1.1

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

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# Namespaced CLI for managing a running agent environment.
+#
+# Usage: ./.har/agent-cli.sh <agent-id> <command> [args...]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/agent-slot.sh"
+
+AGENT_ID="${1:?Usage: agent-cli.sh <agent-id> <command> [args...]}"
+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}"
+export PGPASSWORD="password"
+
+case "$COMMAND" in
+  status)
+    ENV_FILE="$(resolve_agent_env_file "$AGENT_ID" "$REPO_ROOT" || true)"
+    WORKTREE_DIR="$(existing_slot_worktree "$AGENT_ID")"
+
+    PM2_RAW=$(npx --yes pm2 jlist 2>/dev/null || true)
+    PM2_FOUND=false
+
+    if [ -n "$PM2_RAW" ]; then
+      echo "$PM2_RAW" | node -e "
+const agentId = '${AGENT_ID}';
+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);
+    });
+  } catch {
+    process.exit(1);
+  }
+});
+" && PM2_FOUND=true
+    fi
+
+    if [ "$PM2_FOUND" = true ]; then
+      :
+    elif [ -n "$ENV_FILE" ] && [ -f "$ENV_FILE" ]; then
+      echo "Agent ${AGENT_ID}: active (no PM2 processes)"
+      # shellcheck source=/dev/null
+      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"
+    else
+      echo "No active environment for agent ${AGENT_ID}"
+      echo "  Run: ./.har/launch.sh ${AGENT_ID}"
+    fi
+    ;;
+
+  logs)
+    SERVICE="${3:-}"
+    if [ -n "$SERVICE" ]; then
+      npx pm2 logs "agent-${AGENT_ID}-${SERVICE}" --lines 100
+    else
+      npx pm2 logs --name "agent-${AGENT_ID}" --lines 100
+    fi
+    ;;
+
+  restart)
+    SERVICE="${3:-}"
+    if [ -n "$SERVICE" ]; then
+      npx pm2 restart "agent-${AGENT_ID}-${SERVICE}"
+    else
+      npx pm2 jlist 2>/dev/null | node -e "
+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);
+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}');
+" 2>/dev/null || true
+    fi
+    ;;
+
+  psql)
+    QUERY="${3:-}"
+    if [ -n "$QUERY" ]; then
+      har_pg psql -d "agent_${AGENT_ID}" -c "$QUERY"
+    else
+      har_pg psql -d "agent_${AGENT_ID}"
+    fi
+    ;;
+
+  health)
+    if [ -n "${HARNESS_HEALTH_CHECK_PATH:-}" ]; then
+      curl -sf "http://localhost:${API_PORT}${HARNESS_HEALTH_CHECK_PATH}" | node -e "
+const d = require('fs').readFileSync('/dev/stdin','utf8');
+try { console.log(JSON.stringify(JSON.parse(d), null, 2)); } catch { console.log(d); }
+" || curl -v "http://localhost:${API_PORT}${HARNESS_HEALTH_CHECK_PATH}"
+    else
+      echo "No health check path configured in harness.env"
+    fi
+    ;;
+
+  url)
+    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"
+    ;;
+
+  reset-db)
+    echo "==> Resetting database for agent ${AGENT_ID}..."
+    har_pg psql -d postgres -c \
+      "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname='agent_${AGENT_ID}';" \
+      >/dev/null
+    har_pg dropdb --if-exists "agent_${AGENT_ID}"
+    har_pg createdb -T "$HARNESS_TEMPLATE_DB" "agent_${AGENT_ID}"
+    echo "✓ Database reset to clean state"
+    ;;
+
+  slow-queries)
+    har_pg psql -d "agent_${AGENT_ID}" -c "
+SELECT round(mean_exec_time::numeric, 2) AS mean_ms,
+       calls,
+       left(query, 120) AS query
+FROM pg_stat_statements
+ORDER BY mean_exec_time DESC
+LIMIT 20;" 2>/dev/null || echo "pg_stat_statements extension not available"
+    ;;
+
+  exec)
+    shift 2
+    if [ $# -eq 0 ]; then
+      echo "Usage: agent-cli.sh ${AGENT_ID} exec <command>" >&2
+      exit 1
+    fi
+    WORK_DIR="$(resolve_agent_work_dir "" "$AGENT_ID" 2>/dev/null || true)"
+    [ -n "$WORK_DIR" ] && [ -d "$WORK_DIR" ] || WORK_DIR="$REPO_ROOT"
+    PGHOST=localhost PGPORT="$DB_PORT" PGUSER=postgres PGDATABASE="agent_${AGENT_ID}" \
+      bash -c "cd '$WORK_DIR' && $*"
+    ;;
+
+  attach)
+    SESSION="agent-${AGENT_ID}"
+    if ! tmux has-session -t "$SESSION" 2>/dev/null; then
+      echo "No tmux session found: $SESSION" >&2
+      exit 1
+    fi
+    tmux attach -t "$SESSION"
+    ;;
+
+  *)
+    echo "Unknown command: $COMMAND" >&2
+    echo ""
+    echo "Commands: status, logs [service], restart [service], psql [query],"
+    echo "          health, url, reset-db, slow-queries, exec <cmd>, attach"
+    exit 1
+    ;;
+esac

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

@@ -0,0 +1,270 @@
+#!/usr/bin/env bash
+# Shared slot helpers: agent-id validation, slot registry, work-dir resolution.
+# Source after harness.env (requires $SCRIPT_DIR pointing at the .har directory):
+#   source "$SCRIPT_DIR/harness.env"
+#   source "$SCRIPT_DIR/agent-slot.sh"
+#   validate_agent_id "$AGENT_ID"
+
+validate_agent_id() {
+  local id="${1:-}"
+  local min="${HARNESS_AGENT_SLOT_MIN:-1}"
+  local max="${HARNESS_AGENT_SLOT_MAX:-}"
+
+  if [[ -z "$max" ]]; then
+    echo "Error: HARNESS_AGENT_SLOT_MAX is not set in harness.env" >&2
+    exit 1
+  fi
+
+  if [[ -z "$id" ]] || ! [[ "$id" =~ ^[0-9]+$ ]]; then
+    echo "Error: agent-id must be a positive integer between ${min} and ${max}" >&2
+    exit 1
+  fi
+
+  if (( id < min || id > max )); then
+    echo "Error: agent-id must be between ${min} and ${max}" >&2
+    exit 1
+  fi
+}
+
+# ── Slot registry ─────────────────────────────────────────────────────────────
+# .har/slots/agent-<id>.json is the source of truth for where a session lives
+# (worktree path, work dir, branch, base commit). Written by launch.sh, removed
+# by teardown.sh. Location resolution must go through it — worktree paths carry
+# a random per-session suffix and cannot be derived from the agent id alone.
+
+slot_registry_file() {
+  echo "${SCRIPT_DIR}/slots/agent-${1}.json"
+}
+
+# read_slot_field <registry-file> <field> — echoes the scalar value, empty if absent.
+read_slot_field() {
+  [ -f "${1:-}" ] || return 1
+  node -e '
+try {
+  const v = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))[process.argv[2]];
+  if (v != null && typeof v !== "object") process.stdout.write(String(v));
+} catch {}
+' "$1" "$2"
+}
+
+# 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
+write_slot_registry() {
+  local file
+  file="$(slot_registry_file "$SLOT_AGENT_ID")"
+  mkdir -p "$(dirname "$file")"
+  node -e '
+const fs = require("fs");
+const e = process.env;
+const entry = {
+  version: 1,
+  agentId: Number(e.SLOT_AGENT_ID),
+  projectName: e.HARNESS_PROJECT_NAME || "",
+  mode: e.SLOT_MODE,
+  workDir: e.SLOT_WORK_DIR,
+  createdAt: new Date().toISOString(),
+  status: "active",
+};
+if (e.SLOT_SUFFIX) entry.suffix = e.SLOT_SUFFIX;
+if (e.SLOT_WORKTREE_PATH) entry.worktreePath = e.SLOT_WORKTREE_PATH;
+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;
+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 {}
+}
+fs.writeFileSync(process.argv[1], JSON.stringify(entry, null, 2) + "\n");
+' "$file"
+}
+
+remove_slot_registry() {
+  rm -f "$(slot_registry_file "$1")"
+}
+
+# Exit 0 when the worktree has uncommitted or untracked changes.
+slot_worktree_dirty() {
+  [ -d "${1:-}" ] || return 1
+  [ -n "$(git -C "$1" status --porcelain 2>/dev/null)" ]
+}
+
+# Exit 0 when a slot registry entry or worktree path exists for this agent id.
+slot_is_occupied() {
+  local agent_id="$1"
+  [ -f "$(slot_registry_file "$agent_id")" ] || [ -n "$(existing_slot_worktree "$agent_id")" ]
+}
+
+# Echo "clean" or "dirty (N changed)" for a worktree path.
+slot_dirty_summary() {
+  local wt="${1:-}"
+  if [ -z "$wt" ] || [ ! -d "$wt" ]; then
+    echo "unknown"
+    return 0
+  fi
+  if ! slot_worktree_dirty "$wt"; then
+    echo "clean"
+    return 0
+  fi
+  local count
+  count="$(git -C "$wt" status --porcelain 2>/dev/null | wc -l | tr -d ' ')"
+  echo "dirty (${count} changed)"
+}
+
+# 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
+  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)"
+  dirty_summary="$(slot_dirty_summary "$wt")"
+  if [ -n "$wt" ] && [ -d "$wt" ]; then
+    head="$(git -C "$wt" rev-parse --short HEAD 2>/dev/null || true)"
+  fi
+
+  echo "" >&2
+  echo "⚠ Slot ${agent_id} is already in use — replacing will REMOVE the worktree." >&2
+  [ -n "$purpose" ] && echo "  Purpose:   ${purpose}" >&2
+  [ -n "$wt" ] && echo "  Worktree:  ${wt}" >&2
+  [ -n "$work_dir" ] && echo "  Work dir:  ${work_dir}" >&2
+  [ -n "$branch" ] && echo "  Branch:    ${branch}${head:+ @ ${head}}" >&2
+  [ -n "$created" ] && echo "  Since:     ${created}" >&2
+  echo "  Git:       ${dirty_summary}" >&2
+  echo "" >&2
+  echo "  The session branch is kept only if you committed. Gitignored paths" >&2
+  echo "  (state/, runs/, local clones, .env.local) are NOT preserved." >&2
+  echo "" >&2
+}
+
+# Require explicit confirmation before replacing an occupied slot.
+#   $1 agent_id  $2 force(true/false)  $3 replace(true/false)
+# Exits 1 when replacement must not proceed.
+require_slot_replace_confirm() {
+  local agent_id="$1"
+  local force="$2"
+  local replace="$3"
+  local wt
+
+  slot_is_occupied "$agent_id" || return 0
+
+  print_slot_replace_warning "$agent_id"
+  wt="$(existing_slot_worktree "$agent_id")"
+
+  if [ -n "$wt" ] && slot_worktree_dirty "$wt" && [ "$force" != true ]; then
+    echo "ERROR: previous session for slot ${agent_id} has uncommitted changes." >&2
+    echo "  Commit them in the worktree (branch is kept on teardown), or pass --force to discard." >&2
+    echo "  --force destroys uncommitted work — only use after explicit user approval." >&2
+    exit 1
+  fi
+
+  if [ "$replace" = true ] || [ "${HAR_CONFIRM_REPLACE:-}" = "1" ]; then
+    return 0
+  fi
+
+  if [ -t 0 ] && [ -t 1 ]; then
+    local answer
+    read -r -p "Replace slot ${agent_id}? Uncommitted work is lost unless committed. [y/N] " answer
+    if [[ "$answer" =~ ^[Yy]$ ]]; then
+      return 0
+    fi
+    echo "Aborted — slot ${agent_id} left unchanged." >&2
+    exit 2
+  fi
+
+  echo "ERROR: slot ${agent_id} is occupied." >&2
+  echo "  Pass --replace (or set HAR_CONFIRM_REPLACE=1) after reviewing the warning above." >&2
+  echo "  If the worktree is dirty, also pass --force (only after explicit user approval)." >&2
+  exit 2
+}
+
+# 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.
+existing_slot_worktree() {
+  local agent_id="$1"
+  local reg path
+  reg="$(slot_registry_file "$agent_id")"
+  if [ -f "$reg" ]; then
+    path="$(read_slot_field "$reg" worktreePath || true)"
+    if [ -n "$path" ] && [ -d "$path" ]; then
+      echo "$path"
+      return 0
+    fi
+  fi
+  path="$HOME/worktrees/${HARNESS_PROJECT_NAME}-agent-${agent_id}"
+  if [ -d "$path" ]; then
+    echo "$path"
+  fi
+  return 0
+}
+
+# Resolve .env.agent.<id> — registry work dir first, then legacy locations
+# (repo root, pre-registry fixed worktree path).
+resolve_agent_env_file() {
+  local agent_id="$1"
+  local repo_root="$2"
+  local reg work_dir
+  reg="$(slot_registry_file "$agent_id")"
+  if [ -f "$reg" ]; then
+    work_dir="$(read_slot_field "$reg" workDir || true)"
+    if [ -n "$work_dir" ] && [ -f "$work_dir/.env.agent.${agent_id}" ]; then
+      echo "$work_dir/.env.agent.${agent_id}"
+      return 0
+    fi
+  fi
+  # Worktrees are repo-rooted — if the project lives in a subdirectory (monorepo),
+  # the env file sits under that prefix inside the worktree.
+  local rel_prefix
+  rel_prefix="$(git -C "$repo_root" rev-parse --show-prefix 2>/dev/null || true)"
+  local candidate
+  for candidate in \
+    "$repo_root/.env.agent.${agent_id}" \
+    "$HOME/worktrees/${HARNESS_PROJECT_NAME}-agent-${agent_id}/${rel_prefix}.env.agent.${agent_id}"; do
+    if [ -f "$candidate" ]; then
+      echo "$candidate"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Resolve work dir for verify/e2e — registry first, else the agent env file's
+# variables (call after sourcing the env file). Optional 2nd arg: agent id.
+resolve_agent_work_dir() {
+  local env_file="$1"
+  local agent_id="${2:-${AGENT_ID:-}}"
+  if [ -n "$agent_id" ]; then
+    local reg wd
+    reg="$(slot_registry_file "$agent_id")"
+    if [ -f "$reg" ]; then
+      wd="$(read_slot_field "$reg" workDir || true)"
+      if [ -n "$wd" ] && [ -d "$wd" ]; then
+        echo "$wd"
+        return 0
+      fi
+    fi
+  fi
+  local work_dir="${REPO_ROOT:-}"
+  if [ -z "$work_dir" ] || [ ! -d "$work_dir" ]; then
+    if [ -n "${WORKTREE_DIR:-}" ] && [ -d "$WORKTREE_DIR" ]; then
+      work_dir="$WORKTREE_DIR"
+    else
+      work_dir="$(cd "$(dirname "$env_file")" && pwd)"
+    fi
+  fi
+  echo "$work_dir"
+}
+
+# Run browser-e2e on verify --full when the Playwright stage template is installed.
+run_browser_e2e_if_present() {
+  local script_dir="$1"
+  local agent_id="$2"
+  local e2e="$script_dir/stages/browser-e2e.sh"
+  if [ -x "$e2e" ]; then
+    "$e2e" "$agent_id"
+  fi
+}

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

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Attach to the tmux session for an agent.
+#
+# Usage: ./.har/attach.sh <agent-id>
+set -euo pipefail
+
+AGENT_ID="${1:?Usage: attach.sh <agent-id>}"
+SESSION="agent-${AGENT_ID}"
+
+if ! tmux has-session -t "$SESSION" 2>/dev/null; then
+  echo "No tmux session found: $SESSION" >&2
+  echo "Launch with: ./.har/launch.sh ${AGENT_ID} --claude" >&2
+  exit 1
+fi
+
+exec tmux attach -t "$SESSION"

package/dist/templates/har-boilerplate/docker-compose.agent.yml

@@ -0,0 +1,66 @@
+# Shared infrastructure — ONE instance serves all agent slots (fixed ports).
+#
+# This file is a MENU of common external dependencies. When adapting:
+#   - DELETE services this project does not use (and their volumes)
+#   - ADD anything missing (redis, nats, keycloak, ...)
+#   - Internal supporting services of a monolith/monorepo can also live here
+#     (image: or build:) so agent slots only run the primary application
+# Only services listed in HARNESS_INFRA_SERVICES (harness.env) are started
+# by setup-infra.sh.
+services:
+  db:
+    image: pgvector/pgvector:pg16
+    restart: always
+    ports:
+      - "${AGENT_DB_PORT:-15432}:5432"
+    environment:
+      POSTGRES_PASSWORD: password
+    volumes:
+      - agent-db-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+    command:
+      - postgres
+      - -c
+      - shared_preload_libraries=pg_stat_statements
+      - -c
+      - pg_stat_statements.track=all
+    shm_size: 256m
+
+  minio:
+    image: coollabsio/minio:latest
+    ports:
+      - "${AGENT_MINIO_PORT:-19000}:9000"
+      - "${AGENT_MINIO_CONSOLE_PORT:-19001}:9001"
+    volumes:
+      - agent-minio-data:/minio/data
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+      MINIO_DEFAULT_BUCKETS: default,results
+      MINIO_BROWSER: "off"
+
+  headless-browser:
+    image: ghcr.io/browserless/chromium:v2.38.2
+    restart: always
+    ports:
+      - "${AGENT_BROWSER_PORT:-13001}:3000"
+    shm_size: 512m
+
+  mailpit:
+    image: axllent/mailpit:latest
+    restart: unless-stopped
+    ports:
+      - "${AGENT_MAILPIT_WEB_PORT:-18025}:8025"
+      - "${AGENT_MAILPIT_SMTP_PORT:-11025}:1025"
+    environment:
+      MP_MAX_MESSAGES: 5000
+      MP_SMTP_AUTH_ACCEPT_ANY: 1
+      MP_SMTP_AUTH_ALLOW_INSECURE: 1
+
+volumes:
+  agent-db-data:
+  agent-minio-data:

package/dist/templates/har-boilerplate/ecosystem.agent.template.cjs

@@ -0,0 +1,44 @@
+/**
+ * PM2 Ecosystem Configuration for Agent ${AGENT_ID}
+ *
+ * Auto-generated by launch.sh — do not edit manually.
+ * Customize ecosystem.agent.template.cjs in .har/ to change processes.
+ */
+
+// launch.sh writes this file (and .env.agent.N) to the work dir root,
+// so __dirname IS the work dir — repo root or the agent's git worktree.
+const path = require('path');
+const dotenv = require('dotenv');
+
+const agentEnvPath = path.resolve(__dirname, '.env.agent.${AGENT_ID}');
+const env = dotenv.config({ path: agentEnvPath }).parsed || {};
+
+module.exports = {
+  apps: [
+    // TODO: Replace with the PRIMARY application's dev processes — the ONE app
+    // agents modify (HARNESS_PRIMARY_APP in harness.env). In a monolith or
+    // monorepo with several services, do NOT start them all here: supporting
+    // services the agent depends on but does not change run ONCE for all slots,
+    // either as compose services in docker-compose.agent.yml or via an optional
+    // .har/ecosystem.shared.config.cjs (started by setup-infra.sh, processes
+    // named "har-shared-<name>", fixed ports). A primary app may still need two
+    // processes (e.g. api + frontend) — add one entry per process.
+    {
+      name: 'agent-${AGENT_ID}-api',
+      script: 'npm',
+      args: 'run dev',
+      interpreter: 'none',
+      cwd: __dirname,
+      env: {
+        ...env,
+        NODE_ENV: 'development',
+        PORT: env.API_PORT || env.PORT,
+      },
+      watch: false,
+      autorestart: true,
+      kill_timeout: 5000,
+      merge_logs: true,
+      time: true,
+    },
+  ],
+};

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

@@ -0,0 +1,37 @@
+# Agent environment — generated by launch.sh from env.template
+# DO NOT EDIT — regenerated on every launch
+AGENT_ID=${AGENT_ID}
+
+# Ports (formula: BASE + AGENT_ID * 10)
+PORT=${API_PORT}
+FE_PORT=${FE_PORT}
+API_PORT=${API_PORT}
+DEBUG_PORT=${DEBUG_PORT}
+
+# PostgreSQL
+PGHOST=localhost
+PGPORT=${DB_PORT}
+PGDATABASE=agent_${AGENT_ID}
+PGUSER=postgres
+PGPASSWORD=password
+DATABASE_URL=postgresql://postgres:password@localhost:${DB_PORT}/agent_${AGENT_ID}
+
+# Application
+NODE_ENV=development
+SITE_URL=http://localhost:${API_PORT}
+CORS_ORIGIN=http://localhost:${FE_PORT}
+
+# MinIO / S3 (if enabled)
+S3_ENDPOINT=http://localhost:${MINIO_PORT}
+S3_ACCESS_KEY=minioadmin
+S3_SECRET_KEY=minioadmin
+S3_BUCKET=agent-${AGENT_ID}
+S3_REGION=us-east-1
+S3_FORCE_PATH_STYLE=true
+
+# Headless browser (if enabled)
+HEADLESS_BROWSER_URL=http://localhost:${BROWSER_PORT}
+
+# Mail (if enabled)
+SMTP_HOST=localhost
+SMTP_PORT=11025

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

@@ -0,0 +1,50 @@
+# Shared harness configuration — edit to match your project
+# Generated by har env init, maintained over time with har env maintain
+
+export HARNESS_PROJECT_NAME=__PROJECT_NAME__
+export HARNESS_USE_WORKTREE=true
+
+# Primary application — the ONE app agents modify and run per-slot.
+# In a monolith/monorepo with several services, pick the app agents work on;
+# everything else runs once as a shared service (see docker-compose.agent.yml
+# and optional ecosystem.shared.config.cjs).
+export HARNESS_PRIMARY_APP=app
+
+export HARNESS_TEMPLATE_DB=template___PROJECT_NAME__
+export HARNESS_FE_BASE_PORT=3000
+export HARNESS_API_BASE_PORT=8000
+export HARNESS_HEALTH_CHECK_PATH=/health
+
+# Agent slot limits — set based on what your machine can run in parallel
+export HARNESS_AGENT_SLOT_MIN=1
+export HARNESS_AGENT_SLOT_MAX=5
+
+# Shared infrastructure — space-separated docker compose service names from
+# docker-compose.agent.yml. Started ONCE by setup-infra.sh and shared by all
+# agent slots on fixed ports. Prune/add services in the compose file, then
+# list the ones this project needs here (e.g. "db redis mailpit").
+export HARNESS_INFRA_SERVICES="db"
+
+# Returns 0 when a shared infra service is enabled: har_infra_enabled db
+har_infra_enabled() {
+  case " ${HARNESS_INFRA_SERVICES:-} " in
+    *" $1 "*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Postgres client — uses host tools when installed, otherwise docker exec into
+# the shared db container. Usage: har_pg psql -d postgres -c "SELECT 1"
+#                                 har_pg createdb -T template_x agent_1
+har_pg() {
+  local tool="$1"; shift
+  if command -v "$tool" >/dev/null 2>&1; then
+    PGPASSWORD=password "$tool" -h localhost -p "${AGENT_DB_PORT:-15432}" -U postgres "$@"
+  else
+    docker exec -i -e PGPASSWORD=password "har-${HARNESS_PROJECT_NAME}-db-1" "$tool" -U postgres "$@"
+  fi
+}
+
+# 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'"