@osfactory/har 0.40.0 → 0.42.0

package/README.md

@@ -2,18 +2,22 @@
   <img src="assets/logo.png" alt="HAR logo" width="120">
 </p>
 
-# HAR — Harnesses for coding agents
+# HAR: The open harness for multi-agent coding workflows
 
 [![Release](https://img.shields.io/github/v/release/os-factory/har)](https://github.com/os-factory/har/releases)
 [![CI](https://github.com/os-factory/har/actions/workflows/test.yml/badge.svg)](https://github.com/os-factory/har/actions/workflows/test.yml)
 [![Documentation](https://img.shields.io/badge/docs-harproject.dev-38c976)](https://harproject.dev/)
 
-**Give coding agents a real place to work.**
-
-HAR is an open-source, agent-agnostic standard for building multi-agent coding workflows. It makes your repository agent-ready, so you can run a whole fleet of coding agents in parallel, with deterministic validation gates, verifiable proof, and full observability across every agent.
+HAR is an open-source, agent-agnostic framework for building multi-agent coding workflows. Run a fleet of coding agents in parallel on any repository, with deterministic validation gates, verifiable proof, and full observability across every agent, all extensible and customizable to your own workflow and tooling.
 
 Works with **Claude Code** · **Cursor** · **Codex** · any MCP agent.
 
+## What's included out of the box
+
+- **HAR.** The core harness, available as both a CLI and an MCP server. It turns any repository into isolated worktrees with deterministic launch, verify, and teardown stages for coding agents to work in.
+- **Mission Control.** HAR's open-source local dashboard. It gives you one place to keep track of every repository, worktree, run, validation, and artifact across your projects.
+- **Plugins.** A growing ecosystem of open source plugins that further expand HAR's customizability and functionality.
+
 ## Install
 
 ```bash
@@ -29,40 +33,59 @@ har env launch 1          # isolated worktree + running stack for agent slot 1
 har env verify 1 --full   # run the project's real checks, record what passed
 ```
 
-That’s it. Your agents discover launch, verify, and teardown through the project’s `.har/` contract — not by guessing shell commands.
+Full walkthrough: [Quickstart](https://harproject.dev/docs/getting-started/quick-start/).
+
+## Why HAR
 
-Full walkthrough: [Quick start](https://harproject.dev/docs/getting-started/quick-start/).
+Getting a single coding agent to work in a repo is easy. Scaling that into a real multi-agent workflow, where several agents run at once and humans still trust the output, is where it breaks down. HAR was built to close those gaps:
 
-## How it works
+1. **No standard way to run or verify a repo.** That knowledge is scattered across a README, a CLAUDE.md, Cursor rules, and CI yaml today, drifting out of sync with each other and the actual codebase. HAR replaces all of that with one machine-readable contract (.har/) that Claude Code, Cursor, Codex, or any MCP agent reads the same way.
 
-1. **Discover** — The agent reads one stable interface instead of guessing project-specific shell commands.
-2. **Isolate** — Every task gets a clean slot: dedicated session worktree, ports, and local services.
-3. **Build** — The agent edits inside the harness, without touching the main checkout.
-4. **Verify** — Project checks become a deterministic pipeline with normalized status, logs, and artifacts.
-5. **Hand off** — Reviewers get a branch plus evidence: what ran and the exact validated tree.
+2. **Multiple agents on one repo collide.** Shared dev server, shared database, shared ports, conflicting git state. HAR gives each agent its own worktree, ports, and database per slot, so a fleet can genuinely run concurrently.
 
-## Why HAR
+3. **Trusting an agent's change means re-verifying it yourself.** Every task runs the same deterministic verify step and leaves an evidence trail, logs, artifacts, a validated tree hash, so a reviewer can check proof of what ran instead of relying on the agent's self-report.
+
+4. **One platform's sandbox locks you in.** If the contract lives inside a vendor's hosted dashboard, switching coding agents later means rebuilding the whole verification setup. HAR's contract is an open standard living in the repo itself, portable across whichever agent or tool you adopt.
+
+5. **Hand-rolled scripts rot as the stack changes.** A new dependency, a new service, a new env var, and nobody updates the script until an agent's run fails for a confusing reason. `har env maintain` diffs your installed harness against current templates and flags drift before it causes a silent failure.
 
-- **Project-owned** — The workflow lives with the code, not inside a vendor dashboard.
-- **Agent-agnostic** — One stable contract for CLI users, MCP agents, and future tools.
-- **Evidence-first** — Every run can leave logs, artifacts, status, and a validated tree hash.
+HAR coordinates the work around the model, so agents can focus on the code and reviewers can trust the result.
 
-## What HAR is not
+## How HAR works
 
-- A coding model
-- A replacement for CI/CD
-- A new test runner
-- A hosted platform lock-in
+```mermaid
+flowchart LR
+    D["Discover<br/>reads the harness contract"] --> I["Isolate<br/>one slot per agent"]
 
-HAR coordinates the work around the model so agents can focus on the code — and reviewers can trust the result.
+    I --> A1["Agent 1<br/>own worktree, branch, ports, DB"] --> B1["Build"] --> V1["Verify"]
+    I --> A2["Agent 2<br/>own worktree, branch, ports, DB"] --> B2["Build"] --> V2["Verify"]
+
+    V1 --> H["Hand off<br/>branch + evidence"]
+    V2 --> H
+```
+
+1. **Discover.** The agent asks the harness what this project looks like, including its stack, its scripts, and what checks are available.
+
+2. **Isolate.** Every task gets its own slot. That means a fresh copy of the repo on its own branch, with its own ports and, where the project needs it, its own database. Nothing is shared with the main checkout or with any other agent's slot.
+
+3. **Build.** The agent edits and tests its work entirely inside that isolated copy. The main checkout stays untouched the whole time.
+
+4. **Verify.** The project's own checks, whatever they are, run through the same pipeline every time and produce a consistent result. A full verification goes further and captures the state of the entire codebase at that moment, so a pass is tied to the exact code that was checked.
+
+5. **Hand off.** Once verification passes, the session is torn down, but the branch and the proof of what ran are kept. A reviewer gets the code plus the evidence that it was checked.
 
 ## Documentation
 
-Everything beyond install and first commands lives at **[https://harproject.dev/](https://harproject.dev/)**:
+Everything beyond install and first commands lives at [harproject.dev](https://harproject.dev/).
 
-- [Introduction](https://harproject.dev/docs/getting-started/introduction/) · [Core concepts](https://harproject.dev/docs/getting-started/concepts/)
-- [CLI reference](https://harproject.dev/docs/reference/cli/) · [MCP tools](https://harproject.dev/docs/reference/mcp/)
-- [Mission Control](https://harproject.dev/docs/guides/mission-control/) · [Architecture](https://harproject.dev/docs/project/architecture/)
+- **[Core concepts](https://harproject.dev/docs/getting-started/concepts/).** Defines the terms the rest of the docs rely on, things like harness, slot, worktree, stage, run, and validation.
+- **[Agent integrations](https://harproject.dev/docs/guides/agent-integrations/).** How to install HAR workflows for Cursor, Claude Code, Codex, and other MCP clients.
+- **[Verification and commit gate](https://harproject.dev/docs/guides/verification/).** How HAR binds a successful check to exact code and enforces that result at commit time.
+- **[Plugins](https://harproject.dev/docs/guides/plugins/).** How to install framework-specific verification bundles, like Playwright and RocketSim, that register stages in your harness.
+- **[CLI reference](https://harproject.dev/docs/reference/cli/).** Every command and option the `har` executable exposes.
+- **[MCP tools](https://harproject.dev/docs/reference/mcp/).** The structured tools an MCP-connected agent calls directly, for discovery, session control, verification, and evidence.
+- **[Mission Control](https://harproject.dev/docs/guides/mission-control/).** How to run the local dashboard that tracks repositories, worktrees, runs, validations, and artifacts.
+- **[Architecture](https://harproject.dev/docs/project/architecture/).** HAR's internal layers, contracts, and extension points, for anyone building a plugin or contributing to the core.
 
 ## Contributing
 
@@ -70,9 +93,9 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup, the dogfood harness lo
 
 ## Sponsors
 
-HAR is sponsored by [Kerno](https://kerno.io) — runtime code and security review for coding agents.
+HAR is sponsored by [Kerno](https://kerno.io), runtime code and security review for coding agents.
 
-<p align="center">
+<p align="left">
   <a href="https://kerno.io">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="assets/kerno-logo.svg">

package/dist/index.js

@@ -31068,6 +31068,27 @@ function writePortalWatermark(repoPath, portalUrl, lastSyncedAt) {
   }
   writeState(state);
 }
+function readRunsWatermarkEntry(repoPath, target) {
+  const canonical = canonicalizeControlRepoPath(repoPath);
+  const entry = readState().states.find(
+    (state) => state.repoPath === canonical && state.portalUrl === target
+  );
+  return entry ? { lastSyncedAt: entry.lastSyncedAt, repoId: entry.repoId } : null;
+}
+function writeRunsWatermark(repoPath, target, repoId, lastSyncedAt) {
+  const canonical = canonicalizeControlRepoPath(repoPath);
+  const state = readState();
+  const existing = state.states.find(
+    (entry) => entry.repoPath === canonical && entry.portalUrl === target
+  );
+  if (existing) {
+    existing.lastSyncedAt = lastSyncedAt;
+    existing.repoId = repoId;
+  } else {
+    state.states.push({ repoPath: canonical, portalUrl: target, lastSyncedAt, repoId });
+  }
+  writeState(state);
+}
 function selectSince(rows, since, getTimestamp) {
   let maxSyncedAt = null;
   const selected = [];
@@ -31275,6 +31296,7 @@ var init_portal_usage_merge = __esm({
 // src/core/control-sync.ts
 var control_sync_exports = {};
 __export(control_sync_exports, {
+  chunkBySerializedSize: () => chunkBySerializedSize,
   discoverHarRepos: () => discoverHarRepos,
   ensureRepoRegisteredWithControl: () => ensureRepoRegisteredWithControl,
   isControlApiReachable: () => isControlApiReachable,
@@ -31286,13 +31308,80 @@ __export(control_sync_exports, {
   syncRunWithControlAsync: () => syncRunWithControlAsync,
   waitForControlApi: () => waitForControlApi
 });
+function maxSyncBatchBytes() {
+  const raw = Number(process.env.HAR_SYNC_MAX_BATCH_BYTES);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_MAX_BATCH_BYTES;
+}
+function chunkBySerializedSize(items, maxBytes) {
+  const batches = [];
+  let current = [];
+  let currentBytes = 0;
+  for (const item of items) {
+    const itemBytes = Buffer.byteLength(JSON.stringify(item), "utf8");
+    if (current.length > 0 && currentBytes + itemBytes > maxBytes) {
+      batches.push(current);
+      current = [];
+      currentBytes = 0;
+    }
+    current.push(item);
+    currentBytes += itemBytes;
+  }
+  if (current.length > 0) batches.push(current);
+  return batches;
+}
+function runTimestamp(run2) {
+  return run2.finishedAt ?? run2.startedAt;
+}
+function rewindSince(since) {
+  if (!since) return null;
+  const raw = Number(process.env.HAR_SYNC_OVERLAP_MS);
+  const overlap = Number.isFinite(raw) && raw >= 0 ? raw : DEFAULT_SYNC_OVERLAP_MS;
+  return new Date(new Date(since).getTime() - overlap).toISOString();
+}
+function runsWatermarkTarget(target) {
+  return `runs:${target}`;
+}
+async function syncRunBatches(newRuns, repoPath, runsTarget, getRepoId, dryRun, send) {
+  const ordered = [...newRuns].sort((a2, b3) => runTimestamp(a2).localeCompare(runTimestamp(b3)));
+  const batches = chunkBySerializedSize(ordered, maxSyncBatchBytes());
+  const toSend = batches.length > 0 ? batches : [[]];
+  for (let i2 = 0; i2 < toSend.length; i2++) {
+    const batch = toSend[i2];
+    await send(batch, i2);
+    if (!dryRun && batch.length > 0) {
+      writeRunsWatermark(repoPath, runsTarget, getRepoId(), runTimestamp(batch[batch.length - 1]));
+    }
+  }
+}
+function describeFetchFailure(url, bodyBytes, err) {
+  const base = err instanceof Error ? err.message : String(err);
+  const cause = err.cause;
+  const code = cause?.code ? ` [${cause.code}]` : "";
+  const detail = cause?.message && cause.message !== base ? `: ${cause.message}` : "";
+  const size = bodyBytes > 0 ? ` (request body ${(bodyBytes / 1024 / 1024).toFixed(2)} MB)` : "";
+  return `${base}${code}${detail}${size} \u2014 POST ${url}`;
+}
+async function postForResponse(url, headers, payload) {
+  let lastErr;
+  for (let attempt = 1; attempt <= MAX_FETCH_ATTEMPTS; attempt++) {
+    try {
+      return await fetch(url, { method: "POST", headers, body: payload });
+    } catch (err) {
+      lastErr = err;
+      if (attempt < MAX_FETCH_ATTEMPTS) {
+        await new Promise((resolve47) => setTimeout(resolve47, attempt * 100));
+      }
+    }
+  }
+  throw new Error(describeFetchFailure(url, Buffer.byteLength(payload, "utf8"), lastErr));
+}
 async function postJson(url, body, dryRun) {
   if (dryRun) return null;
-  const response = await fetch(url, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(body)
-  });
+  const response = await postForResponse(
+    url,
+    { "Content-Type": "application/json" },
+    JSON.stringify(body)
+  );
   if (!response.ok) {
     const text = await response.text().catch(() => "");
     throw new Error(`Control API ${response.status}: ${text || response.statusText}`);
@@ -31300,14 +31389,14 @@ async function postJson(url, body, dryRun) {
   return await response.json();
 }
 function postPortalOnce(target, endpoint, body) {
-  return fetch(`${target.url}${endpoint}`, {
-    method: "POST",
-    headers: {
+  return postForResponse(
+    `${target.url}${endpoint}`,
+    {
       "Content-Type": "application/json",
       Authorization: `Bearer ${target.token}`
     },
-    body: JSON.stringify(body)
-  });
+    JSON.stringify(body)
+  );
 }
 async function refreshPortalToken(target) {
   if (!target.refreshToken) return false;
@@ -31331,7 +31420,7 @@ async function refreshPortalToken(target) {
   return true;
 }
 async function postPortal(target, endpoint, body, dryRun) {
-  if (dryRun) return;
+  if (dryRun) return null;
   let response = await postPortalOnce(target, endpoint, body);
   if ((response.status === 401 || response.status === 403) && await refreshPortalToken(target)) {
     response = await postPortalOnce(target, endpoint, body);
@@ -31345,6 +31434,7 @@ async function postPortal(target, endpoint, body, dryRun) {
     const text = await response.text().catch(() => "");
     throw new Error(`har-portal sync failed: HTTP ${response.status}${text ? ` \u2014 ${text}` : ""}`);
   }
+  return await response.json().catch(() => null);
 }
 function resolvePortalUserEmail() {
   return readPortalCredentials()?.email || void 0;
@@ -31441,7 +31531,6 @@ async function buildPortalPayload(repoPath, controlApiUrl, since) {
     path: repoPath,
     ...manifest ? { manifest } : {},
     ...stagesRegistry ? { stagesRegistry } : {},
-    runs,
     slots: status.slots,
     generatedAt: status.generatedAt,
     ...validations.length > 0 ? { validations } : {},
@@ -31450,7 +31539,7 @@ async function buildPortalPayload(repoPath, controlApiUrl, since) {
     ...validationBindings.length > 0 ? { validationBindings } : {},
     ...usage2.length > 0 ? { usage: usage2 } : {}
   };
-  return { syncBody, events, maxSyncedAt };
+  return { syncBody, runs, events, maxSyncedAt };
 }
 async function isControlApiReachable(apiUrl = getControlApiUrl()) {
   try {
@@ -31488,7 +31577,7 @@ async function syncReposWithControl(options) {
     try {
       await withTimeout(
         syncRepoWithControl({ repoPath, apiUrl, dryRun: options.dryRun, cloud: options.cloud, full: options.full }),
-        SYNC_TIMEOUT_MS,
+        EXPLICIT_SYNC_TIMEOUT_MS,
         "control sync"
       );
       synced++;
@@ -31551,7 +31640,7 @@ async function ensureRepoRegisteredWithControl(repoPath, apiUrl) {
 }
 async function syncRepoWithLocalControl(options) {
   const apiUrl = options.apiUrl ?? getControlApiUrl();
-  const { repoPath, dryRun } = options;
+  const { repoPath, dryRun, full } = options;
   const registerResult = await registerRepoWithControl({ ...options, repoPath });
   const repoId = registerResult?.id;
   if (!repoId && !dryRun) {
@@ -31562,11 +31651,11 @@ async function syncRepoWithLocalControl(options) {
     if (!existing) {
       return;
     }
-    await syncRepoRunsAndSlots(apiUrl, existing.id, repoPath, dryRun);
+    await syncRepoRunsAndSlots(apiUrl, existing.id, repoPath, dryRun, full);
     return;
   }
   if (repoId) {
-    await syncRepoRunsAndSlots(apiUrl, repoId, repoPath, dryRun);
+    await syncRepoRunsAndSlots(apiUrl, repoId, repoPath, dryRun, full);
   }
 }
 async function syncRepoWithPortal(options, controlApiUrl) {
@@ -31574,10 +31663,28 @@ async function syncRepoWithPortal(options, controlApiUrl) {
   if (!portal) return;
   const { repoPath, dryRun, full } = options;
   const since = full ? null : readPortalWatermark(repoPath, portal.url);
-  const { syncBody, events, maxSyncedAt } = await buildPortalPayload(repoPath, controlApiUrl, since);
-  await postPortal(portal, "/api/sync", syncBody, dryRun);
-  if (events.length > 0) {
-    await postPortal(portal, "/api/otel", { path: repoPath, events, spans: [] }, dryRun);
+  const runsTarget = runsWatermarkTarget(portal.url);
+  const stored = full ? null : readRunsWatermarkEntry(repoPath, runsTarget);
+  const runsSince = rewindSince(stored?.lastSyncedAt ?? null);
+  const { syncBody, runs, events, maxSyncedAt } = await buildPortalPayload(
+    repoPath,
+    controlApiUrl,
+    since
+  );
+  const { selected: newRuns } = selectSince(runs, runsSince, runTimestamp);
+  let repoId;
+  await syncRunBatches(newRuns, repoPath, runsTarget, () => repoId, dryRun, async (batch, i2) => {
+    const body = i2 === 0 ? { ...syncBody, runs: batch } : { path: repoPath, runs: batch };
+    const res = await postPortal(portal, "/api/sync", body, dryRun);
+    if (i2 === 0 && typeof res?.repositoryId === "string") repoId = res.repositoryId;
+  });
+  if (!full && !dryRun && stored?.repoId && repoId && stored.repoId !== repoId) {
+    await syncRunBatches(listRuns(repoPath), repoPath, runsTarget, () => repoId, dryRun, async (batch) => {
+      await postPortal(portal, "/api/sync", { path: repoPath, runs: batch }, dryRun);
+    });
+  }
+  for (const batch of chunkBySerializedSize(events, maxSyncBatchBytes())) {
+    await postPortal(portal, "/api/otel", { path: repoPath, events: batch, spans: [] }, dryRun);
   }
   if (!dryRun && maxSyncedAt) {
     writePortalWatermark(repoPath, portal.url, maxSyncedAt);
@@ -31618,10 +31725,15 @@ async function syncRepoWithControl(options) {
   await syncRepoWithLocalControl({ ...options, repoPath, apiUrl });
   await syncRepoWithPortal({ ...options, repoPath }, apiUrl);
 }
-async function syncRepoRunsAndSlots(apiUrl, repoId, repoPath, dryRun) {
+async function syncRepoRunsAndSlots(apiUrl, repoId, repoPath, dryRun, full) {
+  const runsTarget = runsWatermarkTarget(apiUrl);
+  const stored = full ? null : readRunsWatermarkEntry(repoPath, runsTarget);
+  const runsSince = rewindSince(stored?.repoId === repoId ? stored?.lastSyncedAt ?? null : null);
   const runs = listRuns(repoPath);
-  const runsBody = SyncRunsInputSchema.parse({ runs });
-  await postJson(`${apiUrl}/api/repos/${repoId}/runs`, runsBody, dryRun);
+  const { selected: newRuns } = selectSince(runs, runsSince, runTimestamp);
+  await syncRunBatches(newRuns, repoPath, runsTarget, () => repoId, dryRun, async (batch) => {
+    await postJson(`${apiUrl}/api/repos/${repoId}/runs`, SyncRunsInputSchema.parse({ runs: batch }), dryRun);
+  });
   const status = collectEnvironmentStatus(repoPath);
   const slotsBody = SyncSlotsInputSchema.parse({
     slots: status.slots,
@@ -31776,7 +31888,7 @@ async function syncRunWithControlAsync(repoPath, run2) {
 `);
   }
 }
-var path27, SYNC_TIMEOUT_MS;
+var path27, DEFAULT_MAX_BATCH_BYTES, DEFAULT_SYNC_OVERLAP_MS, MAX_FETCH_ATTEMPTS, SYNC_TIMEOUT_MS, EXPLICIT_SYNC_TIMEOUT_MS;
 var init_control_sync = __esm({
   "src/core/control-sync.ts"() {
     "use strict";
@@ -31800,7 +31912,11 @@ var init_control_sync = __esm({
     init_portal_usage_merge();
     init_schema2();
     init_portal_watermark();
+    DEFAULT_MAX_BATCH_BYTES = 4 * 1024 * 1024;
+    DEFAULT_SYNC_OVERLAP_MS = 6e4;
+    MAX_FETCH_ATTEMPTS = 3;
     SYNC_TIMEOUT_MS = 15e3;
+    EXPLICIT_SYNC_TIMEOUT_MS = 12e4;
   }
 });
 
@@ -89812,7 +89928,7 @@ var HAR_MCP_TOOLS = [
       force: { type: "boolean" },
       auto: { type: "boolean" },
       smoke: { type: "boolean" },
-      profile: { type: "string", enum: ["default", "cli"] }
+      profile: { type: "string", enum: ["default", "cli", "ios"] }
     })
   },
   {

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

@@ -5,32 +5,31 @@ alwaysApply: true
 
 # HAR Harness Workflow
 
-This repository uses a `.har/` agent harness. Follow this workflow on every change.
+This repository uses a `.har/` agent harness. Follow this on every change.
 
-The harness is **how you run the project**, not only how you verify it. To see the app
-live (manual testing, browser sessions, screenshots), launch a slot — never hand-roll
-docker/dev-server startup; the harness already encodes DB setup, ports, and env.
-If a harness command fails, fix the harness or surface the failure — do not quietly
-work around it with ad-hoc commands.
+The harness is **how you run the project**, not only how you verify it. Launch a
+slot for live apps, browsers, and screenshots — never hand-roll docker/dev-server
+startup. If a harness command fails, fix the harness or surface the failure.
 
 ## Before making changes
 
-1. **On the main checkout, switch to the intended base** (usually `main`) — every launch creates a worktree from that HEAD.
-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**. If the task binds to a durable external work item (a GitHub issue, a Linear ticket, a task from the user's tracker), pass `workUnitId` + `title` on launch (`har_launch_environment` `workUnitId`/`title`, or CLI `--work-id`/`--work-title`) so Mission Control attributes usage and events to that work item instead of leaving them session-only.
-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
-
-When a slot is occupied: it always blocks a new launch. Run `complete` / `teardown` on that slot id first, then `launch` again. Occupied slots do not choose the base branch either way — switch the main checkout to your intended base before launching. Failed/starting launches can be resumed instead: `--resume` / `recover`.
-
-### Slot safety (read before launch)
-
-- **One slot ≈ one task** — do not share slot 1 across unrelated chats; use slot 2+ for parallel work.
-- **Call `har_get_status` / `har env status`** before launch when a slot may be occupied.
-- **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.
-- With telemetry on (default, including prompts), Mission Control derives session purpose from the first captured user prompt.
+1. On the **main checkout**, switch to the intended base (usually `main`) — launch
+   creates a worktree from that HEAD.
+2. **Launch first** — MCP `har_launch_environment` / `har env launch 1`. Use the
+   returned **work dir** for ALL edits (never the main checkout). Path looks like
+   `~/worktrees/<base>-<sha4>-har-agent-<id>-<rand4>` (see `.har/slots/agent-<id>.json`).
+   Bind tracker work with `workUnitId`/`title` or `--work-id`/`--work-title` when needed.
+3. Read `AGENT.md`, `.har/README.md`, `.har/stages.json`, then
+   `.har/CLAUDE.agent.md` (slot URLs / definition of done).
+4. Hot-reload usually applies; if not, `./.har/agent-cli.sh <id> restart` (no-op on
+   cli/ios profiles without managed processes).
+
+**Occupied slots always block.** Run `complete` / `teardown`, then `launch`. Resume
+failed/starting launches with `--resume` / `recover`. Prefer a free slot (2+) over
+sharing slot 1 across unrelated chats. Check `har_get_status` / `har env status`
+first. Commit early — teardown keeps the branch, not uncommitted work. Gitignored
+paths are ephemeral. With telemetry on, 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:
@@ -45,102 +44,33 @@ When a slot is occupied: it always blocks a new launch. Run `complete` / `teardo
 Run harness commands from the directory that owns the harness (e.g. `cd apps/admin`).
 -->
 
-
 ## After making changes
 
-Validate through the harness — do not skip verification or substitute ad-hoc npm/test commands.
-
-### 1. HAR MCP (preferred in Cursor when `.cursor/mcp.json` has the har server)
-
-- `har_run_verification` with `agentId: 1` — fast loop (typecheck + unit tests)
-- `har_run_verification` with `agentId: 1, full: true` — required before declaring work done
-- `har_complete_environment` with `agentId: 1` — **recommended finish** (full verify + validation record + teardown, branch kept). **Propose and wait for user approval** before invoking — never run autonomously
-- `har_teardown_environment` with `agentId: 1` — plain cleanup only (also keeps the branch; `deleteBranch: true` to drop it). Prefer `complete` when the work succeeded
-
-### 2. HAR CLI (when `har` is installed)
-
-```bash
-har env launch 1        # FIRST, before editing — prints the work dir
-har env verify 1
-har env verify 1 --full
-har env complete 1      # done: verify + validate + teardown, branch kept for PR
-har env teardown 1      # plain cleanup (--delete-branch to drop the branch)
-```
-
-### 3. Shell fallback (no CLI/MCP installed)
-
-```bash
-./.har/launch.sh 1
-./.har/verify.sh 1
-./.har/verify.sh 1 --full
-./.har/teardown.sh 1
-```
-
-Commit your work **inside the session worktree** on its session branch. After completion the branch survives teardown — the user decides whether to push it and open a PR. Run JSON stays in the main checkout `.har/runs/`.
+Prefer MCP → CLI → shell. Quick verify for the loop; **full verify before done**.
 
-## UI changes
+- MCP: `har_run_verification` / `full: true`; finish with `har_complete_environment`
+  (propose; wait for approval) or `har_teardown_environment`
+- CLI: `har env verify 1`, `har env verify 1 --full`, `complete 1`, `teardown 1`
+- Shell: `./.har/verify.sh 1`, `./.har/verify.sh 1 --full`, `./.har/teardown.sh 1`
 
-When the Playwright stage is installed (`.har/stages/browser-e2e.sh` exists), add or update specs under `tests/`. Full verify includes browser-e2e.
+Commit in the session worktree. Run JSON stays in the main checkout `.har/runs/`.
+UI changes with Playwright: update specs under `tests/` (full verify includes browser-e2e).
 
 ## Definition of done
 
-- Full verification returns pass (`har env verify 1 --full`, MCP `har_run_verification` with `full: true`, or `./.har/verify.sh 1 --full`)
-- All edits live in the session worktree (main checkout untouched: `git status` clean there)
-- New behavior has automated test coverage
-- Changes committed in the session worktree
-- Show the user the slot preview URLs so they can test the app themselves
-- Do not declare work complete without running full verify
-- **Present session handoff and wait for the user's next instruction** — do not end the session without the handoff prompt
+- Full verify passes; edits only in the session worktree; tests cover new behavior;
+  changes committed; show preview URLs; then **session handoff** (below).
 
 ## Session handoff (required)
 
-After full verify passes and changes are committed, **stop and hand off**. Never
-autonomously run `complete`, `teardown`, `git push`, or create a pull request.
-
-Present a handoff that includes:
-
-1. **Summary** of what changed
-2. **Session branch** name (from launch / `.har/slots/agent-<id>.json`)
-3. **Preview URLs** when the slot has a running app
-4. **Numbered next-step options** — then wait for the user
-
-Options to offer:
-
-1. **Complete the slot** (recommended) — `har env complete <id>` / MCP
-   `har_complete_environment`: full verify + validation record + worktree/runtime
-   teardown; **branch kept**. Prefer this over bare `teardown` when the work
-   succeeded.
-2. **Open a PR** — only if `gh` CLI or GitHub MCP is available. Create the PR
-   **only after explicit user approval**.
-3. **Keep the branch only** — if PR tooling is unavailable, report the session
-   branch and how to push manually. The branch already exists from launch.
-
-Canonical handoff shape:
-
-```markdown
-## Session handoff
-
-**Summary:** …
-**Branch:** `<session-branch>` (session worktree)
-**Preview:** … (if applicable)
-
-Next steps — tell me which you want:
-1. **Complete the slot** — I'll run `har env complete <id>` (full verify + validation record + teardown; branch kept)
-2. **Open a PR** — I can create one with `gh`/GitHub MCP (requires your approval)
-3. **Something else** — e.g. keep the slot running, more changes, or push only
-
-I'll wait for your instruction before running complete, teardown, push, or PR.
-```
-
-Omit option 2 when neither `gh` nor GitHub MCP is available; replace it with push
-instructions for the session branch.
+After full verify and commit, stop. Include summary, session branch
+(`.har/slots/agent-<id>.json`), and preview URLs. Propose: (1) complete the slot
+(`har env complete` / `har_complete_environment` — branch kept), (2) open a PR if
+`gh`/GitHub MCP is available, or (3) something else. Wait for the user — never
+autonomously complete, teardown, push, or open a PR.
 
 ## Commit gate
 
-Each full verify records the exact code state it validated (a git tree hash under
-`.har/validations/`). When the har commit gate is installed (`har hooks install`),
-`git commit` is blocked unless the staged changes match a state that passed full verify.
-
-- Any edit after verify — even one character — requires re-running `har env verify <id> --full`
-- Stage everything you verified (`git add -A`); partially staged trees were never verified and will be rejected
-- Do not bypass the gate (`--no-verify`, `HAR_SKIP_GATE=1`) — bypasses are recorded and visible in Mission Control
+Full verify records a tree hash under `.har/validations/`. With `har hooks install`,
+commits must match a passing full verify. Re-verify after any edit; `git add -A` the
+verified tree. Do not bypass (`--no-verify`, `HAR_SKIP_GATE=1`).

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

@@ -52,8 +52,7 @@ After full verify and commit, stop and propose next steps. Never autonomously ru
 `complete`, `teardown`, `git push`, or open a PR. Prefer `complete` over bare
 `teardown` when the work succeeded. Offer a PR only if `gh` or GitHub MCP is
 available (and only after explicit approval); otherwise report the session branch
-for a manual push. See `.cursor/rules/har-workflow.mdc` for the canonical handoff
-template.
+for a manual push. See `.cursor/rules/har-workflow.mdc` for the handoff shape.
 
 Quick loop during development: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}` (smoke + health only; `--full` adds the registered verification stages).
 

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

@@ -2,7 +2,7 @@
 
 This directory is the **agent harness** for this repository. It lets AI coding agents (Cursor, Claude Code, etc.) run the project in isolated environments with their own ports, database, and verification workflow.
 
-Generated and maintained by [`har`](https://github.com/antoineFrau/har). Run `har env maintain` when the repo stack changes.
+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.** Need the app live — manual testing, a browser session, screenshots? `launch` a slot; don't hand-roll docker/dev-server startup. If a harness command fails, fix the harness or report it — don't silently fall back to ad-hoc commands.
 

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

@@ -38,8 +38,7 @@ After full verify and commit, stop and propose next steps. Never autonomously ru
 `complete`, `teardown`, `git push`, or open a PR. Prefer `complete` over bare
 `teardown` when the work succeeded. Offer a PR only if `gh` or GitHub MCP is
 available (and only after explicit approval); otherwise report the session branch
-for a manual push. See `.cursor/rules/har-workflow.mdc` for the canonical handoff
-template.
+for a manual push. 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}`
 

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

@@ -2,7 +2,7 @@
 
 This directory is the **agent harness** for this repository. It lets AI coding agents run the project in isolated git worktrees with optional Docker-backed shared infra.
 
-Generated and maintained by [`har`](https://github.com/antoineFrau/har). Run `har env maintain` when the repo stack changes.
+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 setup. If a harness command fails, fix the harness or report it — don't silently fall back to ad-hoc commands.
 

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

@@ -40,8 +40,7 @@ After full verify and commit, stop and propose next steps. Never autonomously ru
 `complete`, `teardown`, `git push`, or open a PR. Prefer `complete` over bare
 `teardown` when the work succeeded. Offer a PR only if `gh` or GitHub MCP is
 available (and only after explicit approval); otherwise report the session branch
-for a manual push. See `.cursor/rules/har-workflow.mdc` for the canonical handoff
-template.
+for a manual push. 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}`
 

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

@@ -2,7 +2,7 @@
 
 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/antoineFrau/har). Run `har env maintain` when the repo stack changes.
+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/package.json

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