@osfactory/har 0.64.2 → 1.0.0-rc.1

package/dist/templates/profiles/default/docs/readme/port-shared-services.md

@@ -0,0 +1,41 @@
+## 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
+
+Each slot runs **only the primary application** (`HARNESS_PRIMARY_APP` in `harness.env`) — the app agents modify. Everything else runs **once**, shared by all slots on fixed ports:
+
+- **External dependencies** (Postgres, Redis, mail, ...): services in `docker-compose.agent.yml`, enabled via the `HARNESS_INFRA_SERVICES` list in `harness.env`, started by `setup-infra.sh`.
+- **Internal supporting services** (other services of a monolith/monorepo the agent depends on but does not change): either compose services in `docker-compose.agent.yml`, or PM2 processes in an optional `.har/ecosystem.shared.config.cjs` (named `har-shared-<name>`, started by `setup-infra.sh`).
+
+Isolation still applies where it matters: each slot gets its own database (`agent_<id>`, cloned from the template DB), ports, and git worktree.

package/dist/templates/profiles/default/docs/readme/quick-start.md

@@ -0,0 +1,24 @@
+## Quick start
+
+**har CLI or MCP:**
+
+```bash
+har env launch 1
+har env verify 1
+har env verify 1 --full
+har env teardown 1
+```
+
+In Cursor with HAR MCP configured: use `har_launch_environment`, `har_run_verification`, and `har_teardown_environment`.
+
+**Shell shims** (same runtime — each `./.har/*.sh` forwards to `har env`, with a pinned `npx @osfactory/har` fallback):
+
+```bash
+./.har/setup-infra.sh          # when HARNESS_INFRA_SERVICES is non-empty
+./.har/launch.sh 1
+./.har/verify.sh 1             # quick: ecosystem smoke + health
+./.har/verify.sh 1 --full      # + conventional tests/lint, browser-e2e (if installed)
+./.har/teardown.sh 1
+```
+
+Read **`stages.json`** for registered stages and **`verificationStages`** for the expected pass set.

package/dist/templates/profiles/default/docs/readme/readiness-layers.md

@@ -0,0 +1,16 @@
+## 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.

package/dist/templates/profiles/default/docs/readme/verification-contract.md

@@ -0,0 +1,17 @@
+## Verification contract
+
+Steps in `verify.sh` are **project-specific examples** — adapt them to your stack
+during `har env init` / `har env maintain`. The table describes each tier's intent,
+not a fixed command list.
+
+| Mode | Command | Typical steps |
+|------|---------|---------------|
+| 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 plugin: `har env add-plugin playwright` (optional). UI changes should add or update specs under `tests/`.

package/dist/templates/profiles/default/docs/readme/what-s-in-here.md

@@ -0,0 +1,28 @@
+## What's in here
+
+**Yours — the configuration surface** (edit freely; drift tracking records adaptations):
+
+| File | Purpose |
+|------|---------|
+| `README.md` | This file — index of the harness |
+| `harness.env` | Schema-validated config: primary app, ports, agent slot limits, `HARNESS_INFRA_SERVICES`, toolchain provisioning, migrate/seed commands |
+| `stages.json` | Registered stages, verification tiers, artifacts, slot limits, gate policy |
+| `stages/` | Project-owned stage scripts registered from `stages.json` |
+| `hooks/` | Optional lifecycle hooks (`pre-launch.sh`, `post-launch.sh`, `pre-verify.sh`, `pre-teardown.sh`, `post-teardown.sh`) |
+| `plugins/` | Optional local plugins (`har plugin create <id>`) |
+| `env.template` | Per-agent env vars (expanded into `.env.agent.<id>` at launch) |
+| `ecosystem.agent.template.cjs` | PM2 processes for the **primary app only** (expanded at launch) |
+| `ecosystem.shared.config.cjs` | Optional — shared app services started once with the infra (only when the repo has supporting services) |
+| `docker-compose.agent.yml` | Shared infrastructure containers (services listed in `HARNESS_INFRA_SERVICES`) |
+| `CLAUDE.agent.md` | Detailed instructions for coding agents |
+| `STAGES.md` | Stage registry and script-contract guide |
+| `justfile` | Optional shortcuts (requires `just`) |
+
+**Generated shims and state** (don't edit — `har env eject` for full ownership):
+
+| File | Purpose |
+|------|---------|
+| `launch.sh` / `verify.sh` / `teardown.sh` / `setup-infra.sh` / `preflight.sh` / `agent-cli.sh` / `attach.sh` | Thin shims forwarding to the packaged runtime (`har env …`); same run records on every surface |
+| `manifest.json` | Runtime version, profile, checksums — managed by the har CLI |
+| `runs/` | Run history from every entry point — `.har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json` (gitignored) |
+| `artifacts/` | Stage outputs: reports, traces, screenshots, logs |

package/dist/templates/profiles/default/profile.manifest.json

@@ -5,5 +5,66 @@
     { "id": "shared-kernel", "path": "runtime-bundles/shared-kernel" },
     { "id": "pm2-runtime", "path": "runtime-bundles/pm2-runtime" },
     { "id": "runtime-default", "path": "har-boilerplate" }
-  ]
+  ],
+  "capabilities": {
+    "processManager": "pm2",
+    "appPortLanes": true,
+    "infra": {
+      "defaultServices": ["db"],
+      "portLanes": "db=15432:15432-15499 minio=19000:19000-19049 minio-console=19050:19050-19099 browser=13001:13001-13099 mailpit-web=18025:18025-18099 mailpit-smtp=11025:11025-11099"
+    },
+    "defaultStages": [
+      "setup-infra",
+      "launch",
+      "verify",
+      "status",
+      "logs",
+      "teardown",
+      "typecheck",
+      "api-health",
+      "unit-tests",
+      "lint",
+      "readiness"
+    ],
+    "defaultEnvKeys": [
+      "HARNESS_PROJECT_NAME",
+      "HARNESS_USE_WORKTREE",
+      "HARNESS_PRIMARY_APP",
+      "HARNESS_TEMPLATE_DB",
+      "HARNESS_FE_BASE_PORT",
+      "HARNESS_API_BASE_PORT",
+      "HARNESS_PORT_STEP",
+      "HARNESS_HEALTH_CHECK_PATH",
+      "HARNESS_INFRA_PORT_LANES",
+      "HARNESS_AGENT_SLOT_MIN",
+      "HARNESS_AGENT_SLOT_MAX",
+      "HARNESS_ECOSYSTEM",
+      "HARNESS_INFRA_SERVICES",
+      "HARNESS_DB_MIGRATE_CMD",
+      "HARNESS_DB_SEED_CMD"
+    ]
+  },
+  "docs": {
+    "README.md": [
+      "intro",
+      "what-s-in-here",
+      "quick-start",
+      "verification-contract",
+      "readiness-layers",
+      "run-history",
+      "for-coding-agents",
+      "architecture",
+      "port-shared-services",
+      "maintaining-this-harness",
+      "session-lifecycle"
+    ],
+    "CLAUDE.agent.md": [
+      "intro",
+      "environment",
+      "readiness",
+      "definition-of-done",
+      "project-commands",
+      "do-not"
+    ]
+  }
 }

package/dist/templates/profiles/ios/docs/claude-agent/definition-of-done.md

@@ -0,0 +1,23 @@
+## 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
+- [ ] Present session handoff (summary, branch, preview URLs) and **wait for user** before `complete`, push, or PR
+- [ ] On user approval of the default: push + open PR (when `gh`/GitHub MCP available), then `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — full verify + validation + teardown, branch kept
+
+### Session handoff
+
+After full verify and commit, stop and propose next steps. Never autonomously run
+`complete`, `teardown`, `git push`, or open a PR. **Default recommendation:** when
+`gh` or GitHub MCP is available, complete the slot **and** open a PR (push → PR →
+`har env complete` / `har_complete_environment`). Offer complete-only or something
+else as alternatives. If PR tooling is unavailable, recommend complete and report
+the session branch for a manual push. Prefer `complete` over bare `teardown` when
+the work succeeded. See `.cursor/rules/har-workflow.mdc` for the handoff shape.
+
+Quick loop: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}`
+
+Stages are the harness's single vocabulary for checks: templates and custom stages compile to generic kinds in `.har/stages.json`, and you interact with them only through the registry (`har_run_stage`, `verify`), never stack-specific tooling. Authoring guide: `.har/STAGES.md`.

package/dist/templates/profiles/ios/docs/claude-agent/do-not.md

@@ -0,0 +1,6 @@
+## Do not
+
+- Work around a failing harness command with ad-hoc setup — fix the harness or report the failure
+- Edit `.env.agent.${AGENT_ID}` by hand
+- Run verify before launch (the simulator and worktree must be set up first)
+- Edit the main checkout — all edits go under the session work dir

package/dist/templates/profiles/ios/docs/claude-agent/environment.md

@@ -0,0 +1,14 @@
+## Environment
+
+| | |
+|--|--|
+| **Agent ID** | ${AGENT_ID} |
+| **Work dir** | Fresh session worktree per launch — see the launch output or `.har/slots/agent-${AGENT_ID}.json` |
+| **Simulator** | Created for this slot at launch — `HARNESS_SIMULATOR_UDID` in `.env.agent.${AGENT_ID}` |
+| **Scheme** | Configured in `.har/harness.env` — `HARNESS_XCODE_SCHEME` |
+
+**Never edit the main checkout** — launch FIRST, then make ALL file edits under the work dir from the launch output. An occupied slot always blocks a new launch — run `har env teardown <id>` (or `complete <id>`) first, then launch again.
+
+```bash
+./.har/agent-cli.sh ${AGENT_ID} status
+```

package/dist/templates/profiles/ios/docs/claude-agent/intro.md

@@ -0,0 +1,3 @@
+# Agent ${AGENT_ID} — iOS Development Environment
+
+> [`AGENTS.md`](../AGENTS.md) · [`.har/README.md`](./README.md) · [`stages.json`](./stages.json)

package/dist/templates/profiles/ios/docs/claude-agent/project-commands.md

@@ -0,0 +1,21 @@
+## Project commands
+
+Target **this slot's** simulator, never `booted` — another agent's device may also
+be booted. `HARNESS_IOS_DESTINATION` and `HARNESS_SIMULATOR_UDID` come from
+`.env.agent.${AGENT_ID}`.
+
+```bash
+source .env.agent.${AGENT_ID}
+
+# Build
+xcodebuild build -scheme MyApp -destination "$HARNESS_IOS_DESTINATION" CODE_SIGNING_ALLOWED=NO
+
+# Run unit tests — signed, or an app with entitlements traps at launch
+xcodebuild test -scheme MyApp -destination "$HARNESS_IOS_DESTINATION"
+
+# Install and launch on this slot's device
+./.har/agent-cli.sh ${AGENT_ID} install path/to/MyApp.app
+./.har/agent-cli.sh ${AGENT_ID} launch-app
+```
+
+Adapt for your scheme — see `.har/harness.env`.

package/dist/templates/profiles/ios/docs/claude-agent/readiness.md

@@ -0,0 +1,6 @@
+## 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.

package/dist/templates/profiles/ios/docs/claude-agent/user-flow-validation-rocketsim.md

@@ -0,0 +1,11 @@
+## User-flow validation (RocketSim)
+
+If the RocketSim plugin is installed (`har env add-plugin rocketsim`):
+
+```bash
+./.har/stages/rocketsim-flows.sh ${AGENT_ID}
+# included in:
+./.har/verify.sh ${AGENT_ID} --full
+```
+
+Add and edit user flow scripts in `flows/`. Read `.har/stages/ROCKETSIM.md` for the full authoring guide.

package/dist/templates/profiles/ios/docs/readme/configuration.md

@@ -0,0 +1,7 @@
+## Configuration
+
+Edit **`harness.env`** to set:
+- `HARNESS_XCODE_SCHEME` — your app's shared Xcode scheme
+- `HARNESS_XCODE_WORKSPACE` or `HARNESS_XCODE_PROJECT` — path to the project file
+- `HARNESS_SIMULATOR_NAME` — preferred simulator, matched by exact name
+- `HARNESS_BUNDLE_ID` — app bundle identifier

package/dist/templates/profiles/ios/docs/readme/intro.md

@@ -0,0 +1,7 @@
+# .har — Agent Harness (iOS mobile app profile)
+
+This directory is the **agent harness** for this iOS mobile app repository. It lets AI coding agents build, test, and validate the app in isolated git worktrees against a running iOS Simulator.
+
+Generated and maintained by [`har`](https://github.com/os-factory/har). Run `har env maintain` when the repo stack changes.
+
+**The harness is how you run this project.** Launch a slot to exercise the code in isolation; don't hand-roll Xcode/simulator setup. If a harness command fails, fix the harness or report it — don't silently fall back to ad-hoc commands.

package/dist/templates/profiles/ios/docs/readme/port-shared-services-ios-profile.md

@@ -0,0 +1,25 @@
+## Port & shared services (iOS profile)
+
+Pure iOS apps have **no per-slot TCP ports** — agents build and run on a shared iOS Simulator. Optional backend containers (mock API, etc.) use the same shared-infra model as other profiles.
+
+### Port allocation
+
+| Layer | Scope | Rule | On conflict |
+|-------|-------|------|-------------|
+| Optional backend (compose) | Per machine | `HARNESS_*_PORT_DEFAULT` for that service | Scan configured ranges in `harness.env` |
+| iOS Simulator | Per slot | One device created per agent — no harness port | None: `har-<project>-agent-<id>-<model>` is unique per slot |
+
+When your app talks to a local backend, read the resolved host port from `.env.agent.<id>` (set by `setup-infra.sh`) — never hardcode `15432` or similar in tests or flow scripts.
+
+### Shared vs per-slot
+
+| Resource | Model | Configuration |
+|----------|-------|---------------|
+| iOS Simulator | One device created per slot, deleted at teardown | `HARNESS_SIMULATOR_*`, `launch.sh` |
+| Optional backend | One shared compose service | `HARNESS_INFRA_SERVICES` (e.g. `"mock-server"`) |
+| Application code | Isolated git worktree per slot | `HARNESS_USE_WORKTREE=true` |
+
+### Do not
+
+- Hardcode backend ports in RocketSim flows or unit tests — read from agent env
+- Run raw `docker compose` for harness infrastructure — use `setup-infra.sh`

package/dist/templates/profiles/ios/docs/readme/quick-start.md

@@ -0,0 +1,22 @@
+## Quick start
+
+**har CLI or MCP:**
+
+```bash
+har env launch 1
+har env verify 1
+har env verify 1 --full
+har env teardown 1
+```
+
+In Cursor with HAR MCP configured: use `har_launch_environment`, `har_run_verification`, and `har_teardown_environment`.
+
+**Shell shims** (same runtime — each `./.har/*.sh` forwards to `har env`, with a pinned `npx @osfactory/har` fallback):
+
+```bash
+./.har/setup-infra.sh          # boots the iOS Simulator
+./.har/launch.sh 1
+./.har/verify.sh 1             # quick: build smoke (compile-only)
+./.har/verify.sh 1 --full      # + unit tests, lint, rocketsim-flows (if installed)
+./.har/teardown.sh 1
+```

package/dist/templates/profiles/ios/docs/readme/simulators.md

@@ -0,0 +1,45 @@
+## Simulators
+
+Slots do not share a simulator. Each launch **creates**
+`har-<project>-agent-<id>-<model>` — `har-storefront-agent-2-iPhone-17`, say — and
+teardown deletes it, so two agents never collide on a destination, on an installed
+bundle id, or on a UI session, and the simulators you use by hand are never touched.
+Every launch also starts from a pristine device: no app installed, no leftover
+store, nothing carried over from the previous session.
+
+| Setting | Effect |
+|---------|--------|
+| `HARNESS_SIMULATOR_NAME` | The model to create — `iPhone 16`, `iPhone 17 Pro`, `iPad Air 11-inch (M2)`. Empty means the newest model of the family. See `xcrun simctl list devicetypes`. |
+| `HARNESS_SIMULATOR_FAMILY` | `auto` (read from the name) \| `iPhone` \| `iPad`. An iPad is only created when this resolves to iPad. |
+| `HARNESS_SIMULATOR_UDID` | Run every slot on one existing device instead. Slots then share it — for one-off debugging. |
+| `HARNESS_SIMULATOR_SHARED` | `true` restores one shared simulator for all slots, booted by `setup-infra.sh`. |
+
+The runtime is the newest installed iOS that supports the model — a model retired
+from recent runtimes still resolves against an older one. When nothing matches,
+launch fails and lists the models this machine can create.
+
+If `HARNESS_SIMULATOR_NAME` is not a model but names an existing device, that
+device is used as-is and never deleted — how a hand-renamed simulator is targeted.
+
+### Running from an agent sandbox
+
+`xcrun simctl` reaches CoreSimulatorService over XPC. Coding agents that sandbox
+their shell (Codex, Claude Code and others) usually deny that lookup, so `simctl`
+fails while `xcodebuild` keeps working — every simulator command then dies with
+`CoreSimulatorService connection became invalid`. Nothing is missing on the machine.
+
+Launch and teardown say so when it happens. Either run `har env launch <id>` and
+`har env teardown <id>` from a normal terminal and let the agent work in the
+worktree, or grant the agent unsandboxed access to `xcrun simctl` — the escalation
+must cover every subcommand the harness uses (`list`, `create`, `boot`,
+`bootstatus`, `shutdown`, `delete`), not just `list`.
+
+The same messages distinguish a second cause: if `xcrun simctl` is missing from
+the selected developer directory — no Xcode, or `xcode-select` pointing at the
+Command Line Tools — they say so and print the current selection instead of
+blaming a sandbox.
+
+The device lands in `.env.agent.<id>` as `HARNESS_SIMULATOR_UDID`,
+`HARNESS_SIMULATOR_DEVICE_NAME` and `HARNESS_IOS_DESTINATION` — the model stays in
+`HARNESS_SIMULATOR_NAME`, so the two never mean the same thing in one place; what a slot holds is tracked in `.har/simulators/`.
+Use `./.har/agent-cli.sh <id> simulator` to see it.

package/dist/templates/profiles/ios/docs/readme/user-flow-validation.md

@@ -0,0 +1,9 @@
+## User-flow validation
+
+Add the RocketSim plugin to get reusable UI flow validation:
+
+```bash
+har env add-plugin rocketsim
+```
+
+This installs `.har/stages/rocketsim-flows.sh` and a `flows/` directory. Add flow scripts under `flows/` (see `.har/stages/ROCKETSIM.md`). Full verify automatically runs all flows.

package/dist/templates/profiles/ios/docs/readme/verification-contract.md

@@ -0,0 +1,13 @@
+## Verification contract
+
+Steps in `verify.sh` are **project-specific examples** — adapt them to your stack.
+The table describes each tier's intent, not a fixed command list.
+
+| Mode | Command | Typical steps |
+|------|---------|---------------|
+| Quick | `har env verify <id>` | build smoke (compile-only) |
+| Full | `har env verify <id> --full` | + unit tests, 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.

package/dist/templates/profiles/ios/docs/readme/what-s-in-here.md

@@ -0,0 +1,27 @@
+## What's in here
+
+**Yours — the configuration surface** (edit freely; drift tracking records adaptations):
+
+| File | Purpose |
+|------|---------|
+| `README.md` | This file — index of the harness |
+| `harness.env` | Schema-validated config: Xcode scheme, simulator name, bundle ID, toolchain provisioning, optional infra services |
+| `stages.json` | Registered stages, verification tiers, artifacts, slot limits, gate policy |
+| `stages/` | Project-owned stage scripts registered from `stages.json` |
+| `hooks/` | Optional lifecycle hooks (`pre-launch.sh`, `post-launch.sh`, `pre-verify.sh`, `pre-teardown.sh`, `post-teardown.sh`) |
+| `plugins/` | Optional local plugins (`har plugin create <id>`) |
+| `docker-compose.agent.yml` | Optional shared backend services |
+| `CLAUDE.agent.md` | Detailed instructions for coding agents |
+| `STAGES.md` | Stage registry and script-contract guide |
+| `justfile` | Optional shortcuts (requires `just`) |
+
+**Generated shims and state** (don't edit — `har env eject` for full ownership):
+
+| File | Purpose |
+|------|---------|
+| `launch.sh` / `verify.sh` / `teardown.sh` / `setup-infra.sh` / `preflight.sh` / `agent-cli.sh` | Thin shims forwarding to the packaged runtime (`har env …`); same run records on every surface |
+| `manifest.json` | Runtime version, profile, checksums — managed by the har CLI |
+| `runs/` | Run history from every entry point — `.har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json` (gitignored) |
+| `artifacts/` | Stage outputs: test results, screenshots, logs |
+
+No PM2 or web-port wiring in this profile — agents run xcodebuild commands directly in their worktree.

package/dist/templates/profiles/ios/profile.manifest.json

@@ -1,9 +1,65 @@
 {
   "id": "ios",
-  "description": "iOS — shared kernel + Xcode/Simulator overlay",
+  "description": "iOS — shared kernel + Xcode/Simulator overlay (simulator runtime lives in the package)",
   "bundles": [
     { "id": "shared-kernel", "path": "runtime-bundles/shared-kernel" },
-    { "id": "xcode-sim", "path": "runtime-bundles/xcode-sim" },
     { "id": "runtime-ios", "path": "har-boilerplate-ios" }
-  ]
+  ],
+  "capabilities": {
+    "processManager": "simulator",
+    "appPortLanes": false,
+    "infra": {
+      "defaultServices": [],
+      "portLanes": ""
+    },
+    "defaultStages": [
+      "setup-infra",
+      "launch",
+      "verify",
+      "status",
+      "teardown",
+      "build",
+      "unit-tests",
+      "lint",
+      "readiness"
+    ],
+    "defaultEnvKeys": [
+      "HARNESS_PROJECT_NAME",
+      "HARNESS_USE_WORKTREE",
+      "HARNESS_AGENT_SLOT_MIN",
+      "HARNESS_AGENT_SLOT_MAX",
+      "HARNESS_ECOSYSTEM",
+      "HARNESS_XCODE_WORKSPACE",
+      "HARNESS_XCODE_PROJECT",
+      "HARNESS_XCODE_SCHEME",
+      "HARNESS_SIMULATOR_NAME",
+      "HARNESS_BUNDLE_ID",
+      "HARNESS_SIMULATOR_FAMILY",
+      "HARNESS_SIMULATOR_SHARED",
+      "HARNESS_IOS_DESTINATION",
+      "HARNESS_INFRA_SERVICES"
+    ]
+  },
+  "docs": {
+    "README.md": [
+      "intro",
+      "what-s-in-here",
+      "quick-start",
+      "user-flow-validation",
+      "verification-contract",
+      "configuration",
+      "simulators",
+      "port-shared-services-ios-profile",
+      "session-lifecycle"
+    ],
+    "CLAUDE.agent.md": [
+      "intro",
+      "environment",
+      "readiness",
+      "definition-of-done",
+      "project-commands",
+      "user-flow-validation-rocketsim",
+      "do-not"
+    ]
+  }
 }

package/dist/templates/runtime-bundles/pm2-runtime/attach.sh

@@ -1,22 +1,15 @@
 #!/usr/bin/env bash
 # Attach to the tmux session for an agent.
-#
+# The runtime lives in the HAR package (#234) — this file only forwards to it.
 # Usage: ./.har/attach.sh <agent-id>
 set -euo pipefail
-
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=/dev/null
-source "$SCRIPT_DIR/harness.env"
-# shellcheck source=/dev/null
-source "$SCRIPT_DIR/agent-slot.sh"
-
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 AGENT_ID="${1:?Usage: attach.sh <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
-  echo "Launch with: ./.har/launch.sh ${AGENT_ID} --claude" >&2
-  exit 1
+if command -v har >/dev/null 2>&1; then
+  exec har env agent "$AGENT_ID" attach
+elif [ -x "$REPO_ROOT/node_modules/.bin/har" ]; then
+  exec "$REPO_ROOT/node_modules/.bin/har" env agent "$AGENT_ID" attach
 fi
-
-exec tmux attach -t "$SESSION"
+echo "Error: the 'har' CLI is not available. Install @osfactory/har (npm i -D @osfactory/har) or run: npx @osfactory/har env agent" >&2
+exit 127

package/dist/templates/runtime-bundles/pm2-runtime/env.template

@@ -32,7 +32,7 @@ S3_FORCE_PATH_STYLE=true
 # Headless browser (if enabled)
 HEADLESS_BROWSER_URL=http://localhost:${BROWSER_PORT}
 
-# Toolchain paths — appended by provision-toolchain.sh during launch
+# Toolchain paths — appended by the packaged launch provisioning step
 # NODE_BIN=  NPM_BIN=  PYTHON_BIN=  VIRTUAL_ENV=  GO_BIN=  CARGO_BIN=  JAVA_HOME=
 
 # Mail (if enabled)

package/dist/templates/runtime-bundles/pm2-runtime/stages/api-health.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# API health check for the slot's primary application. Registered as the
+# `api-health` verification stage (tier: quick) on web profiles.
+set -euo pipefail
+
+AGENT_ID="${1:?Usage: api-health.sh <agent-id>}"
+
+PORT="${API_PORT:-$(( ${HARNESS_API_BASE_PORT:?HARNESS_API_BASE_PORT not set} + AGENT_ID * 10 ))}"
+exec curl -sf "http://localhost:${PORT}${HARNESS_HEALTH_CHECK_PATH:-/health}"