@osfactory/har 0.18.1 → 0.19.0

package/dist/templates/cursor-rule.mdc.template

@@ -15,13 +15,14 @@ work around it with ad-hoc commands.
 
 ## Before making changes
 
-1. **Launch your slot FIRST — before editing any file.** Use `har_launch_environment` with `agentId: 1` (MCP) or `har env launch 1`. Launch always creates a **fresh session worktree** from the current HEAD and returns its **work dir**.
-2. **Make ALL file edits under the returned work dir — never in the main checkout.** The work dir looks like `~/worktrees/<base-branch>-<sha4>-har-agent-<id>-<rand4>` (recorded in `.har/slots/agent-<id>.json`). Edits there hot-reload in the running slot; use `har env restart <id>` or `./.har/agent-cli.sh <id> restart` if a change doesn't take.
-3. Read [AGENT.md](./AGENT.md) at the repo root
-4. Read [.har/README.md](./.har/README.md) and [.har/stages.json](./.har/stages.json)
-5. After launch, read [.har/CLAUDE.agent.md](./.har/CLAUDE.agent.md) for slot URLs and definition of done
+1. **On the main checkout, switch to the intended base** (usually `main`) — every launch creates a worktree from that HEAD. `--replace` does not select the base.
+2. **Launch your slot FIRST — before editing any file.** Use `har_launch_environment` with `agentId: 1` (MCP) or `har env launch 1`. Launch always creates a **fresh session worktree** and returns its **work dir**.
+3. **Make ALL file edits under the returned work dir — never in the main checkout.** The work dir looks like `~/worktrees/<base-branch>-<sha4>-har-agent-<id>-<rand4>` (recorded in `.har/slots/agent-<id>.json`). Edits there hot-reload in the running slot; use `har env restart <id>` or `./.har/agent-cli.sh <id> restart` if a change doesn't take.
+4. Read [AGENT.md](./AGENT.md) at the repo root
+5. Read [.har/README.md](./.har/README.md) and [.har/stages.json](./.har/stages.json)
+6. After launch, read [.har/CLAUDE.agent.md](./.har/CLAUDE.agent.md) for slot URLs and definition of done
 
-Relaunching a slot **replaces** its previous session (the old branch is kept). Replacement requires explicit confirmation (`--replace`, `confirmReplace=true`, or an interactive prompt). If the previous session has uncommitted changes, you must also pass `force`/`--force` after **explicit user approval** — never autonomously.
+When a slot is occupied: prefer `complete` / `teardown` if the previous task is finished, then launch. Use `--replace` / `confirmReplace=true` only to reuse the same slot id immediately (destroys the old worktree; the old branch is kept if committed). If the previous session has uncommitted changes, you must also pass `force`/`--force` after **explicit user approval** — never autonomously. Failed launches: `--resume` / `recover`, not `--replace`.
 
 ### Slot safety (read before launch)
 
@@ -30,7 +31,7 @@ Relaunching a slot **replaces** its previous session (the old branch is kept). R
 - **Never** set `force`/`confirmReplace` without the user explicitly approving replacement.
 - **Commit early and often** in the session worktree — teardown keeps the branch, not uncommitted work.
 - **Gitignored paths are ephemeral** (`state/`, `runs/`, local clones) — they are lost when the worktree is removed.
-- Optional: set `har env launch <id> --purpose=label`, `HAR_SESSION_PURPOSE=label`, or `./.har/launch.sh <id> --purpose=label` so occupied-slot warnings show what you were doing.
+- With telemetry prompts enabled, Mission Control derives session purpose from the first captured user prompt.
 
 <!-- Monorepo: if this repository contains multiple .har harnesses, list them here
      and pick by the files you are changing. Example:

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

@@ -179,15 +179,17 @@ The authoring agent updates scripts and this README. Review changes before commi
 
 ## Session lifecycle
 
-Every `launch` starts a **fresh session**: a new git worktree from the current HEAD at
+Every `launch` starts a **fresh session**: a new git worktree from the **main
+checkout's current HEAD** at
 `~/worktrees/<base-branch>-<sha4>-har-agent-<id>-<rand4>`, on a branch of the same name.
-The session is recorded in `.har/slots/agent-<id>.json` (the slot registry) — status,
-verify, and teardown resolve the work dir through it. Make ALL file edits under the
-work dir printed by launch, never in the main checkout.
-
-- Relaunching a slot **replaces** its previous session; replacement requires `--replace` /
-  `confirmReplace=true` (or an interactive prompt). Uncommitted changes also need `--force`
-  after explicit user approval.
+Switch that checkout to your intended base before launch. The session is recorded in
+`.har/slots/agent-<id>.json` (the slot registry) — status, verify, and teardown resolve
+the work dir through it. Make ALL file edits under the work dir printed by launch,
+never in the main checkout.
+
+- Prefer `complete` / `teardown` when a task is finished, then launch.
+- `--replace` destroys the previous worktree (requires confirmation); it does **not**
+  choose `main`. Uncommitted changes also need `--force` 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`.

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

@@ -535,6 +535,17 @@ print_slot_replace_warning() {
   [ -n "$created" ] && echo "  Since:     ${created}" >&2
   echo "  Git:       ${dirty_summary}" >&2
   echo "" >&2
+  local base_root="${HARNESS_ROOT:-${REPO_ROOT:-}}"
+  if [ -n "$base_root" ] && [ -d "$base_root" ]; then
+    local base_branch base_sha
+    base_branch="$(git -C "$base_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo detached)"
+    base_sha="$(git -C "$base_root" rev-parse --short HEAD 2>/dev/null || true)"
+    echo "  New session will be based on: ${base_branch}${base_sha:+ @ ${base_sha}}" >&2
+    echo "  (HEAD of ${base_root})" >&2
+    echo "  --replace does not choose this base — switch that checkout first for a new unrelated task." >&2
+    echo "" >&2
+  fi
+  echo "  Prefer complete/teardown when the previous task is finished, then launch." >&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

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

@@ -137,15 +137,17 @@ The authoring agent updates scripts and this README. Review changes before commi
 
 ## Session lifecycle
 
-Every `launch` starts a **fresh session**: a new git worktree from the current HEAD at
+Every `launch` starts a **fresh session**: a new git worktree from the **main
+checkout's current HEAD** at
 `~/worktrees/<base-branch>-<sha4>-har-agent-<id>-<rand4>`, on a branch of the same name.
-The session is recorded in `.har/slots/agent-<id>.json` (the slot registry) — status,
-verify, and teardown resolve the work dir through it. Make ALL file edits under the
-work dir printed by launch, never in the main checkout.
-
-- Relaunching a slot **replaces** its previous session; replacement requires `--replace` /
-  `confirmReplace=true` (or an interactive prompt). Uncommitted changes also need `--force`
-  after explicit user approval.
+Switch that checkout to your intended base before launch. The session is recorded in
+`.har/slots/agent-<id>.json` (the slot registry) — status, verify, and teardown resolve
+the work dir through it. Make ALL file edits under the work dir printed by launch,
+never in the main checkout.
+
+- Prefer `complete` / `teardown` when a task is finished, then launch.
+- `--replace` destroys the previous worktree (requires confirmation); it does **not**
+  choose `main`. Uncommitted changes also need `--force` 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, resume with

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

@@ -515,6 +515,17 @@ print_slot_replace_warning() {
   [ -n "$created" ] && echo "  Since:     ${created}" >&2
   echo "  Git:       ${dirty_summary}" >&2
   echo "" >&2
+  local base_root="${HARNESS_ROOT:-${REPO_ROOT:-}}"
+  if [ -n "$base_root" ] && [ -d "$base_root" ]; then
+    local base_branch base_sha
+    base_branch="$(git -C "$base_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo detached)"
+    base_sha="$(git -C "$base_root" rev-parse --short HEAD 2>/dev/null || true)"
+    echo "  New session will be based on: ${base_branch}${base_sha:+ @ ${base_sha}}" >&2
+    echo "  (HEAD of ${base_root})" >&2
+    echo "  --replace does not choose this base — switch that checkout first for a new unrelated task." >&2
+    echo "" >&2
+  fi
+  echo "  Prefer complete/teardown when the previous task is finished, then launch." >&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

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

@@ -113,10 +113,14 @@ When your app talks to a local backend, read the resolved host port from `.env.a
 
 ## Session lifecycle
 
-Every `launch` starts a **fresh session**: a new git worktree from the current HEAD at
+Every `launch` starts a **fresh session**: a new git worktree from the **main
+checkout's current HEAD** at
 `~/worktrees/<base-branch>-<sha4>-har-agent-<id>-<rand4>`, on a branch of the same name.
-The session is recorded in `.har/slots/agent-<id>.json`.
+Switch that checkout to your intended base before launch. The session is recorded in
+`.har/slots/agent-<id>.json`.
 
-- Relaunching a slot **replaces** its previous session; uncommitted changes require `--force`.
+- Prefer `complete` / `teardown` when a task is finished, then launch.
+- `--replace` destroys the previous worktree; it does **not** choose `main`.
+  Uncommitted changes also require `--force` after explicit approval.
 - `teardown` removes the worktree but **keeps the session branch** for push / PR.
 - `har env complete <id>` finishes a session: full verify + teardown, branch kept.

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

@@ -176,6 +176,17 @@ print_slot_replace_warning() {
   [ -n "$created" ] && echo "  Since:     ${created}" >&2
   echo "  Git:       ${dirty_summary}" >&2
   echo "" >&2
+  local base_root="${HARNESS_ROOT:-${REPO_ROOT:-}}"
+  if [ -n "$base_root" ] && [ -d "$base_root" ]; then
+    local base_branch base_sha
+    base_branch="$(git -C "$base_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo detached)"
+    base_sha="$(git -C "$base_root" rev-parse --short HEAD 2>/dev/null || true)"
+    echo "  New session will be based on: ${base_branch}${base_sha:+ @ ${base_sha}}" >&2
+    echo "  (HEAD of ${base_root})" >&2
+    echo "  --replace does not choose this base — switch that checkout first for a new unrelated task." >&2
+    echo "" >&2
+  fi
+  echo "  Prefer complete/teardown when the previous task is finished, then launch." >&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

package/package.json

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