@osfactory/har 0.36.2 → 0.38.0

package/dist/index.js

@@ -7068,7 +7068,7 @@ var init_otel_hooks = __esm({
     path46 = __toESM(require("path"));
     init_control_config();
     init_telemetry_config();
-    OTEL_HOOKS_PACKAGE = "@osfactory/otel-hook@0.1.1";
+    OTEL_HOOKS_PACKAGE = "@osfactory/otel-hook@0.1.2";
     OTEL_HOOKS_PROVIDERS = [
       { id: "cursor", label: "cursor" },
       { id: "claude-code", label: "claude" },
@@ -44506,7 +44506,7 @@ var AgentSlotStatusSchema = external_exports.object({
   attemptId: WorkAttemptIdSchema.optional(),
   sessionStatus: external_exports.enum(["starting", "active", "failed", "completed"]).optional(),
   lastError: external_exports.string().optional(),
-  /** Set when a failed/starting session can be resumed without --replace. */
+  /** Set when a failed/starting session can be resumed with --resume instead of a fresh launch. */
   resumeHint: external_exports.string().optional(),
   /** Worktree checked out to no branch (legacy failure mode; should not happen with sessions). */
   detachedHead: external_exports.boolean().optional(),
@@ -68486,6 +68486,7 @@ function parseHarnessEnvInt(env3, key) {
 
 // src/harness/stages.ts
 var STAGE_REGISTRY_FILE = "stages.json";
+var HAR_AGENT_SLOT_ONBOARD_MAX = 10;
 var AGENT_REQUIRED_KINDS = /* @__PURE__ */ new Set([
   "launch",
   "verify",
@@ -68672,6 +68673,15 @@ ${maxLine}
   fs10.writeFileSync(envPath, content);
   return true;
 }
+function applyAgentSlotMax(repoPath, max) {
+  const slots = HarnessAgentSlotsSchema.parse({ min: HAR_AGENT_SLOT_MIN, max });
+  const registry2 = readStageRegistry(repoPath);
+  writeStageRegistry(repoPath, {
+    ...registry2,
+    agentSlots: slots
+  });
+  syncAgentSlotsToHarnessEnv(repoPath);
+}
 function stageRequiresAgentId(stage) {
   if (typeof stage.requiresAgentId === "boolean") return stage.requiresAgentId;
   return AGENT_REQUIRED_KINDS.has(stage.kind);
@@ -73365,11 +73375,24 @@ function requireApiKey() {
   }
   return key;
 }
+function formatInvalidAgentIdError(id, range) {
+  const idLabel = id === void 0 || id === null || id === "" ? "(missing)" : typeof id === "string" ? id : String(id);
+  const lines2 = [
+    `Invalid agent slot id: ${idLabel}`,
+    `Valid slots: ${range.min}\u2013${range.max} (configured in .har/stages.json \u2192 agentSlots)`,
+    "Run `har env status` to see which slots are in use."
+  ];
+  const num3 = Number(id);
+  if (Number.isInteger(num3) && num3 > range.max) {
+    lines2.push(`To allow slot ${num3}, raise agentSlots.max in .har/stages.json.`);
+  }
+  return lines2.join("\n");
+}
 function validateAgentId(id, repoPath) {
   const num3 = Number(id);
   const range = getAgentSlotRange(repoPath);
   if (!Number.isInteger(num3) || num3 < range.min || num3 > range.max) {
-    throw new Error(`agent-id must be a number between ${range.min} and ${range.max}`);
+    throw new Error(formatInvalidAgentIdError(id, range));
   }
   return num3;
 }
@@ -73950,8 +73973,6 @@ function buildLaunchFlagArgs(flags) {
   const args = [];
   if (flags.worktree === false) args.push("--no-worktree");
   if (flags.claude) args.push("--claude");
-  if (flags.confirmReplace) args.push("--replace");
-  if (flags.force) args.push("--force");
   if (flags.resume) args.push("--resume");
   if (flags.workUnitId) args.push(`--work-id=${flags.workUnitId}`);
   if (flags.attemptId) args.push(`--attempt-id=${flags.attemptId}`);
@@ -74210,6 +74231,7 @@ function registryChanged(before, after) {
 function recordRepoForControlSync(repoPath) {
   if (process.env.HAR_CONTROL_DISABLED === "true") return;
   const resolved = canonicalizeControlRepoPath(repoPath);
+  if (!resolveMainWorkingTree(resolved)) return;
   if (!readManifest(resolved)) return;
   const registry2 = readRegistry();
   if (registry2.repos.includes(resolved)) return;
@@ -74696,7 +74718,7 @@ function describeLaunchBase(repoPath) {
   return [
     `New session will be based on: ${branch}${sha ? ` @ ${sha}` : ""}`,
     `  (HEAD of ${harnessRoot})`,
-    "  --replace does not choose this base \u2014 switch the main checkout first for a new unrelated task."
+    "  Switch the main checkout to your intended base before launching a new session."
   ];
 }
 function formatOccupiedSlot(slot, repoPath, resume) {
@@ -74708,27 +74730,30 @@ function formatOccupiedSlot(slot, repoPath, resume) {
     slot.sessionStatus ? `  Status:   ${slot.sessionStatus}` : void 0,
     slot.lastError ? `  Error:    ${slot.lastError}` : void 0,
     slot.sessionCreatedAt ? `  Since:    ${slot.sessionCreatedAt}` : void 0,
-    slot.dirty ? "  Git:      dirty (uncommitted changes \u2014 commit or use force to discard)" : "  Git:      clean",
+    slot.dirty ? "  Git:      dirty (uncommitted changes \u2014 commit or discard them in the worktree)" : "  Git:      clean",
     "",
     ...describeLaunchBase(repoPath),
     ""
   ];
   if (resume || slot.sessionStatus === "failed" || slot.sessionStatus === "starting") {
     lines2.push(
-      "This session failed partway through launch. Resume without replacing:",
+      "This session failed partway through launch. Resume without a new launch:",
       `  har env launch ${slot.agentId} --resume`,
       `  har env recover ${slot.agentId}`,
       `  ./.har/launch.sh ${slot.agentId} --resume`,
       ""
     );
+  } else {
+    lines2.push(
+      "Free the slot before starting a new session:",
+      slot.dirty ? `  Commit or discard changes in the worktree, then: har env teardown ${slot.agentId} (or complete ${slot.agentId})` : `  har env complete ${slot.agentId}   # or: har env teardown ${slot.agentId}`,
+      `  har env launch ${slot.agentId}`,
+      ""
+    );
   }
   lines2.push(
-    "Prefer complete/teardown when the previous task is finished, then launch.",
-    "Replacing removes the worktree. The session branch is kept only if you committed.",
-    "Gitignored paths (state/, runs/, local clones) are NOT preserved.",
-    "",
-    "To replace: pass confirmReplace=true (MCP), --replace (CLI), or answer y at the prompt.",
-    "If the worktree is dirty, also pass force=true / --force after explicit user approval."
+    "complete/teardown remove the worktree. The session branch is kept only if you committed.",
+    "Gitignored paths (state/, runs/, local clones) are NOT preserved."
   );
   return lines2.filter(Boolean).join("\n");
 }
@@ -74748,42 +74773,18 @@ function checkLaunchGuard(repoPath, agentId, options = {}) {
         reason: [
           `Slot ${agentId} is not resumable (status=${session?.status ?? "none"}).`,
           "Only failed or starting sessions can be resumed.",
-          "Use a normal launch with --replace to start fresh."
+          `Free the slot first: har env teardown ${agentId} (or complete ${agentId}), then har env launch ${agentId}.`
         ].join("\n")
       };
     }
     return { allowed: true, slot };
   }
-  if (isSlotResumable(session) && !options.confirmReplace) {
-    return {
-      allowed: false,
-      blocked: true,
-      slot,
-      reason: formatOccupiedSlot(slot, repoPath)
-    };
-  }
-  if (!options.confirmReplace) {
-    return {
-      allowed: false,
-      blocked: true,
-      slot,
-      reason: formatOccupiedSlot(slot, repoPath)
-    };
-  }
-  if (slot.dirty && !options.force) {
-    return {
-      allowed: false,
-      blocked: true,
-      slot,
-      reason: [
-        formatOccupiedSlot(slot, repoPath),
-        "",
-        "The occupied worktree has uncommitted changes.",
-        "Pass force=true / --force to discard them (only after explicit user approval)."
-      ].join("\n")
-    };
-  }
-  return { allowed: true, slot };
+  return {
+    allowed: false,
+    blocked: true,
+    slot,
+    reason: formatOccupiedSlot(slot, repoPath)
+  };
 }
 
 // src/core/slot-preflight.ts
@@ -74845,24 +74846,20 @@ function inspectSlotReadiness(repoPath, agentId, options = {}) {
   const warnings = [];
   const ports = {};
   const session = readSlotRegistry(harnessRoot, agentId);
-  const guard = options.occupied !== void 0 ? options.occupied.active ? options.resume && isSlotResumable(session) ? { allowed: true } : !options.confirmReplace ? {
+  const guard = options.occupied !== void 0 ? options.occupied.active ? options.resume && isSlotResumable(session) ? { allowed: true } : {
     allowed: false,
     blocked: true,
     reason: `Slot ${agentId} is already in use.`
-  } : options.occupied.dirty && !options.force ? {
-    allowed: false,
-    blocked: true,
-    reason: `Slot ${agentId} worktree has uncommitted changes.`
-  } : { allowed: true } : { allowed: true } : checkLaunchGuard(repoPath, agentId, options);
+  } : { allowed: true } : checkLaunchGuard(repoPath, agentId, options);
   if (!guard.allowed) {
     const resumable = isSlotResumable(session);
     blockers.push({
       code: options.occupied?.dirty ? "slot_dirty" : resumable ? "slot_resumable" : "slot_occupied",
       message: guard.reason ?? `Slot ${agentId} is occupied.`,
-      remediation: resumable ? `Resume the partial launch: har env launch ${agentId} --resume (or har env recover ${agentId})` : guard.slot?.dirty ? "Commit changes in the worktree, or pass --force after explicit user approval." : "Pass --replace (CLI), confirmReplace=true (MCP), or answer y at the launch prompt."
+      remediation: resumable ? `Resume the partial launch: har env launch ${agentId} --resume (or har env recover ${agentId})` : `Free the slot: har env teardown ${agentId} (or complete ${agentId}), then har env launch ${agentId}.`
     });
     remediations.push(
-      resumable ? `har env launch ${agentId} --resume` : guard.slot?.dirty ? "har env preflight <id> --replace --force" : "har env preflight <id> --replace"
+      resumable ? `har env launch ${agentId} --resume` : `har env teardown ${agentId}`
     );
   }
   const pm2Procs = usesPm2 ? options.pm2Processes !== void 0 ? options.pm2Processes : listPm2Processes() : void 0;
@@ -74891,7 +74888,7 @@ function inspectSlotReadiness(repoPath, agentId, options = {}) {
       blockers.push({
         code: "project_mismatch",
         message: `Slot registry projectName=${session.projectName} does not match harness ${projectName}.`,
-        remediation: "Teardown the stale session and relaunch with --replace."
+        remediation: "Teardown the stale session, then relaunch."
       });
     }
   }
@@ -76384,23 +76381,11 @@ async function waitForControlApi(apiUrl = getControlApiUrl(), timeoutMs = 6e4, i
   return false;
 }
 async function discoverHarRepos(options) {
-  const apiUrl = options?.apiUrl ?? getControlApiUrl();
   const repoPaths = new Set(listRegisteredRepos());
   if (options?.cwd) {
     const cwd = canonicalizeControlRepoPath(options.cwd);
     if (readManifest(cwd)) repoPaths.add(cwd);
   }
-  try {
-    const listResponse = await fetch(`${apiUrl}/api/repos`);
-    if (listResponse.ok) {
-      const repos = await listResponse.json();
-      for (const repo of repos) {
-        const resolved = canonicalizeControlRepoPath(repo.path);
-        if (readManifest(resolved)) repoPaths.add(resolved);
-      }
-    }
-  } catch {
-  }
   return [...repoPaths];
 }
 async function syncReposWithControl(options) {
@@ -76641,6 +76626,7 @@ async function syncRepoWithControlAsync(repoPath) {
   if (process.env.HAR_CONTROL_DISABLED === "true" || process.env.NODE_ENV === "test") return;
   const verbose = process.env.HAR_CONTROL_VERBOSE === "true";
   try {
+    recordRepoForControlSync(repoPath);
     const apiUrl = getControlApiUrl();
     if (!await isControlApiReachable(apiUrl)) {
       if (verbose) {
@@ -77000,10 +76986,7 @@ var RunService = class {
     return this.executor.listArtifacts({ repoPath: options.repoPath }, { stageId: options.stageId });
   }
   async preflightEnvironment(options) {
-    const readiness = inspectSlotReadiness(options.repoPath, options.agentId, {
-      confirmReplace: options.confirmReplace,
-      force: options.force
-    });
+    const readiness = inspectSlotReadiness(options.repoPath, options.agentId, {});
     const report = formatPreflightReport(options.agentId, readiness);
     return {
       code: readiness.canLaunch ? 0 : 1,
@@ -77015,8 +76998,6 @@ var RunService = class {
   }
   async launchEnvironment(options) {
     const guard = checkLaunchGuard2(options.repoPath, options.agentId, {
-      confirmReplace: options.confirmReplace,
-      force: options.force,
       resume: options.resume
     });
     if (!guard.allowed) {
@@ -77066,7 +77047,7 @@ Usage from Cursor / Claude / Codex (@osfactory/otel-hook) will appear under Work
     const attemptId = workUnitId ? resumableSession?.attemptId ?? crypto5.randomUUID() : void 0;
     if (workUnitId && attemptId) {
       const conflictingSession = listSlotRegistryEntries(harnessRoot).find(
-        (entry) => entry.workUnitId === workUnitId && !(entry.agentId === options.agentId && (options.resume || options.confirmReplace))
+        (entry) => entry.workUnitId === workUnitId && !(entry.agentId === options.agentId && options.resume)
       );
       if (conflictingSession) {
         return {
@@ -77099,8 +77080,6 @@ Usage from Cursor / Claude / Codex (@osfactory/otel-hook) will appear under Work
       launchFlags: {
         worktree: options.worktree,
         claude: options.claude,
-        confirmReplace: options.confirmReplace,
-        force: options.force,
         resume: options.resume,
         workUnitId,
         attemptId
@@ -77739,10 +77718,11 @@ Slot lifecycle (do not confuse these):
   complete   finish successfully: full verify, then teardown (frees the slot)
   teardown   abandon / free the slot without a completion validation
 
-  --replace  only confirms destroying a previous session on that slot id
-             it does NOT choose main \u2014 new session still uses current HEAD
-  --force    additionally discard dirty uncommitted work (user approval only)
-  --resume   recover failed/starting; never use --replace for that
+Occupied slots always block a new launch:
+  har env complete <id>   # or: har env teardown <id>
+  har env launch <id>     # then start the new session
+
+  --resume   recover a failed/starting session; never needed for a fresh launch
 
 For a new unrelated task: checkout main (or your intended base) on the main
 repo checkout, free the slot (complete/teardown), then launch.`;
@@ -77755,23 +77735,23 @@ var HAR_ENV_EPILOG = `Environment lifecycle:
   teardown <id>    free the slot without recording a completion validation
 
 Occupied slots:
-  Prefer complete/teardown when the previous task is finished, then launch.
-  Use --replace only to reuse the same slot id immediately (destroys old worktree).
-  --replace does not select the base branch \u2014 HEAD of --repo does.
-  Dirty previous worktree also needs --force after explicit user approval.`;
+  Always blocked for a fresh launch \u2014 free the slot first, then launch again:
+    har env complete <id>   # or: har env teardown <id>
+    har env launch <id>
+  A new launch uses the main checkout's current HEAD \u2014 switch that checkout to
+  your intended base first.
+  Failed/starting sessions can be resumed instead: har env launch <id> --resume
+  (or har env recover <id>).`;
 var LAUNCH_COMMAND_DESCRIBE = "Start a fresh agent session (new worktree from the main checkout HEAD)";
-var LAUNCH_REPLACE_DESCRIBE = "Destroy the previous session on this slot and start another (does not choose main; still uses --repo HEAD)";
-var LAUNCH_FORCE_DESCRIBE = "With --replace: discard uncommitted changes in the old worktree (only after explicit user approval)";
-var LAUNCH_RESUME_DESCRIBE = "Continue a failed or starting launch without creating a new worktree (prefer over --replace)";
+var LAUNCH_RESUME_DESCRIBE = "Continue a failed or starting launch without creating a new worktree";
 var LAUNCH_EPILOG = `Every launch creates a NEW session from the current HEAD of --repo (the main
 checkout). The worktree path encodes that base branch \u2014 switch --repo to main
 before launch for a new unrelated task unless you intentionally stack on a
 feature branch.
 
   Free slot:     har env launch 1
-  Occupied:      har env complete 1   # or teardown \u2014 then launch
-                 har env launch 1 --replace          # reuse slot id now
-                 har env launch 1 --replace --force  # + discard dirty work
+  Occupied:      har env complete 1   # or teardown
+                 har env launch 1     # then start the new session
   Failed launch: har env recover 1    # or: har env launch 1 --resume`;
 
 // src/cli/commands/env.ts
@@ -77923,15 +77903,7 @@ var envCommand = {
       type: "boolean",
       default: true,
       describe: "Use an isolated git worktree (default)"
-    }).option("claude", { type: "boolean", default: false }).option("replace", {
-      type: "boolean",
-      default: false,
-      describe: LAUNCH_REPLACE_DESCRIBE
-    }).option("force", {
-      type: "boolean",
-      default: false,
-      describe: LAUNCH_FORCE_DESCRIBE
-    }).option("resume", {
+    }).option("claude", { type: "boolean", default: false }).option("resume", {
       type: "boolean",
       default: false,
       describe: LAUNCH_RESUME_DESCRIBE
@@ -77954,15 +77926,7 @@ var envCommand = {
   ).command(
     "preflight <id>",
     "Check whether a slot can launch now (ports, PM2, Docker, occupied slot)",
-    (y2) => y2.positional("id", { type: "number", describe: "Agent slot id (see .har/stages.json agentSlots)" }).option("repo", { type: "string", default: "." }).option("json", { type: "boolean", default: false, describe: "Structured JSON output" }).option("replace", {
-      type: "boolean",
-      default: false,
-      describe: "Treat an occupied slot as replaceable (same as launch --replace)"
-    }).option("force", {
-      type: "boolean",
-      default: false,
-      describe: "Allow replacing a dirty worktree (only after explicit approval)"
-    }),
+    (y2) => y2.positional("id", { type: "number", describe: "Agent slot id (see .har/stages.json agentSlots)" }).option("repo", { type: "string", default: "." }).option("json", { type: "boolean", default: false, describe: "Structured JSON output" }),
     handlePreflight
   ).command(
     "verify <id>",
@@ -78058,7 +78022,6 @@ async function handleInit(argv) {
     }
     divider();
     success("Harness initialized!");
-    recordRepoForControlSync(repoPath);
     await handleCommitGateOnboarding({
       repoPath,
       ...onboarding.commitGate,
@@ -78323,9 +78286,7 @@ async function handlePreflight(argv) {
   const agentId = validateAgentId(argv.id, repo);
   const result = await preflightEnvironment({
     repoPath: repo,
-    agentId,
-    confirmReplace: argv.replace,
-    force: argv.force
+    agentId
   });
   if (argv.json) {
     const output = SlotReadinessSchema.parse(result.readiness);
@@ -78339,46 +78300,11 @@ async function handlePreflight(argv) {
 async function handleLaunch(argv) {
   const repo = path50.resolve(argv.repo);
   const agentId = validateAgentId(argv.id, repo);
-  let confirmReplace = argv.replace;
-  let force = argv.force;
   if (!argv.resume) {
-    const guard = checkLaunchGuard2(repo, agentId, { confirmReplace, force });
+    const guard = checkLaunchGuard2(repo, agentId, {});
     if (!guard.allowed && guard.blocked) {
-      if (!confirmReplace && process.stdin.isTTY && process.stdout.isTTY) {
-        warn("Occupied slot \u2014 review before replacing:");
-        console.error(guard.reason ?? "");
-        const readline10 = await import("readline");
-        const rl = readline10.createInterface({ input: process.stdin, output: process.stderr });
-        const answer = await new Promise((resolve45) => {
-          rl.question("Replace this slot? [y/N] ", resolve45);
-        });
-        rl.close();
-        if (!/^[Yy]$/.test(answer.trim())) {
-          error("Aborted \u2014 slot left unchanged.");
-          process.exit(2);
-        }
-        confirmReplace = true;
-      }
-    }
-    const guardAfterConfirm = checkLaunchGuard2(repo, agentId, { confirmReplace, force });
-    if (!guardAfterConfirm.allowed && guardAfterConfirm.blocked && guardAfterConfirm.slot?.dirty) {
-      if (!force && process.stdin.isTTY && process.stdout.isTTY) {
-        warn("Worktree has uncommitted changes.");
-        const readline10 = await import("readline");
-        const rl = readline10.createInterface({ input: process.stdin, output: process.stderr });
-        const answer = await new Promise((resolve45) => {
-          rl.question("Discard uncommitted changes? [y/N] ", resolve45);
-        });
-        rl.close();
-        if (!/^[Yy]$/.test(answer.trim())) {
-          error("Aborted \u2014 uncommitted work preserved.");
-          process.exit(2);
-        }
-        force = true;
-      } else if (!force) {
-        error(guardAfterConfirm.reason ?? "Dirty worktree requires --force.");
-        process.exit(2);
-      }
+      error(guard.reason ?? `Slot ${agentId} is occupied.`);
+      process.exit(2);
     }
   }
   const result = await launchEnvironment({
@@ -78386,8 +78312,6 @@ async function handleLaunch(argv) {
     agentId,
     worktree: argv.worktree,
     claude: argv.claude,
-    confirmReplace,
-    force,
     resume: argv.resume,
     workUnitId: argv.workId,
     source: argv.workSource,
@@ -78420,8 +78344,6 @@ async function handleRecover(argv) {
     repo: argv.repo,
     worktree: true,
     claude: false,
-    replace: false,
-    force: false,
     resume: true,
     workId: void 0,
     workSource: void 0,
@@ -89237,13 +89159,9 @@ var LaunchEnvironmentInputSchema = external_exports.object({
   agentId: agentIdSchema,
   worktree: external_exports.boolean().default(true),
   claude: external_exports.boolean().default(false),
-  confirmReplace: external_exports.boolean().default(false).describe(
-    "Destroy the previous session on this slot and start another from main-checkout HEAD. Does not choose main. Prefer complete/teardown when the prior task is finished. Call har_get_status first; get explicit user approval."
-  ),
-  force: external_exports.boolean().default(false).describe(
-    "Discard uncommitted changes in a dirty occupied worktree. Requires confirmReplace=true and explicit user approval \u2014 never set autonomously."
+  resume: external_exports.boolean().default(false).describe(
+    "Resume a failed or partial launch without creating a new worktree. Only valid for failed/starting sessions \u2014 otherwise call har_get_status, then har_complete_environment or har_teardown_environment before launching again."
   ),
-  resume: external_exports.boolean().default(false).describe("Resume a failed or partial launch without creating a new worktree."),
   workUnitId: external_exports.string().min(1).max(128).optional(),
   source: external_exports.string().min(1).max(64).optional(),
   sourceUrl: external_exports.string().url().optional(),
@@ -89269,9 +89187,7 @@ var LaunchEnvironmentOutputSchema = ShellRunOutputSchema.extend({
 });
 var PreflightEnvironmentInputSchema = external_exports.object({
   repo: external_exports.string().default("."),
-  agentId: agentIdSchema,
-  confirmReplace: external_exports.boolean().default(false).describe("Treat an occupied slot as replaceable (same as launch confirmReplace)."),
-  force: external_exports.boolean().default(false).describe("Allow replacing a dirty worktree (requires explicit user approval).")
+  agentId: agentIdSchema
 });
 var PreflightEnvironmentOutputSchema = ShellRunOutputSchema.extend({
   readiness: SlotReadinessSchema,
@@ -89371,24 +89287,16 @@ var HAR_MCP_TOOLS = [
   },
   {
     name: "har_launch_environment",
-    description: "Start a FRESH agent session from the main checkout HEAD (switch that checkout to main first for a new unrelated task). Run BEFORE editing any file: returns workDir \u2014 ALL edits go there, never the main checkout. Prefer har_complete_environment / har_teardown_environment when a prior task is done. Occupied slots block until confirmReplace=true (does NOT choose main). force=true discards dirty work \u2014 never set without user approval. Failed launches: resume=true / har_recover_environment.",
+    description: "Start a FRESH agent session from the main checkout HEAD (switch that checkout to main first for a new unrelated task). Run BEFORE editing any file: returns workDir \u2014 ALL edits go there, never the main checkout. Occupied slots always block: call har_get_status, then har_complete_environment or har_teardown_environment, then relaunch \u2014 unless the session is failed/starting, in which case pass resume=true (or use har_recover_environment).",
     inputSchema: objectJsonSchema(
       {
         repo: repoJsonProperty,
         agentId: agentIdJsonProperty,
         worktree: { type: "boolean" },
         claude: { type: "boolean" },
-        confirmReplace: {
-          type: "boolean",
-          description: "Destroy the previous session on this slot and start another from main-checkout HEAD. Does not choose main. Prefer complete/teardown when the prior task is finished. Call har_get_status first; get explicit user approval."
-        },
-        force: {
-          type: "boolean",
-          description: "Discard uncommitted changes when replacing a dirty worktree. Requires confirmReplace=true and explicit user approval."
-        },
         resume: {
           type: "boolean",
-          description: "Resume a failed or partial launch (status failed/starting) without confirmReplace. Preserves worktree and env."
+          description: "Resume a failed or partial launch (status failed/starting) without creating a new worktree. Preserves worktree and env. Not usable to replace an active/completed slot \u2014 free it with har_complete_environment or har_teardown_environment first."
         },
         workUnitId: {
           type: "string",
@@ -89422,15 +89330,7 @@ var HAR_MCP_TOOLS = [
     inputSchema: objectJsonSchema(
       {
         repo: repoJsonProperty,
-        agentId: agentIdJsonProperty,
-        confirmReplace: {
-          type: "boolean",
-          description: "Treat an occupied slot as replaceable (same as launch confirmReplace)."
-        },
-        force: {
-          type: "boolean",
-          description: "Allow replacing a dirty worktree (only after explicit user approval)."
-        }
+        agentId: agentIdJsonProperty
       },
       ["agentId"]
     )
@@ -89564,7 +89464,6 @@ async function handleMcpToolCall(toolName, args, defaultRepo = ".") {
         smoke: input.smoke,
         profile: input.profile
       });
-      recordRepoForControlSync(repo);
       return jsonContent({
         harnessDir: result.harnessDir,
         validation: result.validation,
@@ -89580,8 +89479,6 @@ async function handleMcpToolCall(toolName, args, defaultRepo = ".") {
         agentId,
         worktree: input.worktree,
         claude: input.claude,
-        confirmReplace: input.confirmReplace,
-        force: input.force,
         resume: input.resume,
         workUnitId: input.workUnitId,
         source: input.source,
@@ -89604,8 +89501,6 @@ async function handleMcpToolCall(toolName, args, defaultRepo = ".") {
         agentId,
         worktree: input.worktree,
         claude: input.claude,
-        confirmReplace: false,
-        force: false,
         resume: true,
         workUnitId: input.workUnitId,
         source: input.source,
@@ -89625,9 +89520,7 @@ async function handleMcpToolCall(toolName, args, defaultRepo = ".") {
       const agentId = validateAgentId(input.agentId, repo);
       const result = await preflightEnvironment({
         repoPath: repo,
-        agentId,
-        confirmReplace: input.confirmReplace,
-        force: input.force
+        agentId
       });
       const parsed = PreflightEnvironmentOutputSchema.parse(result);
       return {
@@ -89964,9 +89857,20 @@ async function runOnboarding(options, deps = {}) {
       warn("Harness has validation errors \u2014 review .har/ after adaptation.");
     }
     harnessInitialized = true;
-    recordRepoForControlSync(repoPath);
     success("Harness scaffolded");
   }
+  let agentSlots = null;
+  if (harnessExists(repoPath)) {
+    if (options.agentSlotsMax !== void 0) {
+      applyAgentSlotMax(repoPath, options.agentSlotsMax);
+      info(`Agent slots: 1\u2013${options.agentSlotsMax} parallel (written to .har/stages.json)`);
+    }
+    try {
+      agentSlots = getAgentSlotRange(repoPath);
+    } catch {
+      agentSlots = null;
+    }
+  }
   const pluginsApplied = [];
   const pluginWarnings = [];
   if (options.plugins.length > 0) {
@@ -90015,7 +89919,8 @@ async function runOnboarding(options, deps = {}) {
     pluginsApplied,
     pluginWarnings,
     adaptationPromptPath,
-    adaptationPromptCopied
+    adaptationPromptCopied,
+    agentSlots
   };
 }
 async function finalizeOnboardingAdaptation(options) {
@@ -90046,6 +89951,27 @@ function parsePluginsFlag(raw) {
   }
   return selected;
 }
+function defaultAgentSlotMaxForProfile(profile) {
+  return profile === "default" ? 5 : 3;
+}
+function parseAgentSlotsFlag(raw) {
+  if (raw === void 0) return void 0;
+  if (!Number.isInteger(raw) || raw < HAR_AGENT_SLOT_MIN || raw > HAR_AGENT_SLOT_ONBOARD_MAX) {
+    throw new Error(
+      `--agent-slots must be an integer from ${HAR_AGENT_SLOT_MIN} to ${HAR_AGENT_SLOT_ONBOARD_MAX}`
+    );
+  }
+  return raw;
+}
+function resolveDefaultAgentSlotsMax(repoPath, profile, alreadyPresent) {
+  if (alreadyPresent) {
+    try {
+      return getAgentSlotRange(repoPath).max;
+    } catch {
+    }
+  }
+  return defaultAgentSlotMaxForProfile(profile);
+}
 async function pauseForGuide(autoYes) {
   if (autoYes || !process.stdin.isTTY || !process.stdout.isTTY) return;
   await esm_default13.prompt([
@@ -90057,20 +89983,23 @@ async function pauseForGuide(autoYes) {
   ]);
 }
 async function promptChoices(args) {
+  const flaggedSlots = parseAgentSlotsFlag(args.agentSlots);
+  const shouldConfigureSlots = !args.skipInit;
   if (args.yes) {
     const telemetry2 = args.telemetry ?? "on";
     return {
       profile: args.profile ?? "default",
       telemetry: telemetry2,
       startControl: args.control ?? telemetry2 !== "off",
-      plugins: parsePluginsFlag(args.plugins) ?? []
+      plugins: parsePluginsFlag(args.plugins) ?? [],
+      agentSlotsMax: shouldConfigureSlots ? flaggedSlots : void 0
     };
   }
   const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
   if (!interactive) {
-    if (args.telemetry === void 0 && args.control === void 0 && args.plugins === void 0 && args.profile === void 0) {
+    if (args.telemetry === void 0 && args.control === void 0 && args.plugins === void 0 && args.profile === void 0 && args.agentSlots === void 0) {
       throw new Error(
-        "Interactive onboarding requires a TTY. Pass --yes or flags (--profile, --telemetry, --control/--no-control, --plugins)."
+        "Interactive onboarding requires a TTY. Pass --yes or flags (--profile, --telemetry, --control/--no-control, --plugins, --agent-slots)."
       );
     }
     const telemetry2 = args.telemetry ?? "on";
@@ -90078,12 +90007,20 @@ async function promptChoices(args) {
       profile: args.profile ?? "default",
       telemetry: telemetry2,
       startControl: args.control ?? telemetry2 !== "off",
-      plugins: parsePluginsFlag(args.plugins) ?? []
+      plugins: parsePluginsFlag(args.plugins) ?? [],
+      agentSlotsMax: shouldConfigureSlots ? flaggedSlots : void 0
     };
   }
   const pluginChoices = listPluginChoices();
-  const alreadyPresent = harnessExists(path59.resolve(args.repo));
+  const repoPath = path59.resolve(args.repo);
+  const alreadyPresent = harnessExists(repoPath);
   const needProfile = !alreadyPresent && !args.skipInit && args.profile === void 0;
+  const needAgentSlots = shouldConfigureSlots && flaggedSlots === void 0;
+  if (needAgentSlots) {
+    info(
+      "Each parallel slot runs an isolated copy of the stack. The practical limit depends on your machine resources (RAM/CPU) and how expensive the stack is to run (Docker services, databases, frontends, etc.). You can change this later in .har/stages.json."
+    );
+  }
   const answers = await esm_default13.prompt([
     {
       type: "list",
@@ -90125,14 +90062,37 @@ async function promptChoices(args) {
         name: plugin.label,
         value: plugin.id
       }))
+    },
+    {
+      type: "number",
+      name: "agentSlotsMax",
+      message: `How many agents do you want to run in parallel? (${HAR_AGENT_SLOT_MIN}\u2013${HAR_AGENT_SLOT_ONBOARD_MAX})`,
+      when: () => needAgentSlots,
+      default: (current) => resolveDefaultAgentSlotsMax(
+        repoPath,
+        args.profile ?? current.profile ?? "default",
+        alreadyPresent
+      ),
+      validate: (value) => {
+        if (value === void 0 || !Number.isInteger(value) || value < HAR_AGENT_SLOT_MIN || value > HAR_AGENT_SLOT_ONBOARD_MAX) {
+          return `Enter an integer from ${HAR_AGENT_SLOT_MIN} to ${HAR_AGENT_SLOT_ONBOARD_MAX}`;
+        }
+        return true;
+      }
     }
   ]);
   const telemetry = args.telemetry ?? answers.telemetry ?? "on";
+  const profile = args.profile ?? answers.profile ?? "default";
+  let agentSlotsMax;
+  if (shouldConfigureSlots) {
+    agentSlotsMax = flaggedSlots ?? answers.agentSlotsMax;
+  }
   return {
-    profile: args.profile ?? answers.profile ?? "default",
+    profile,
     telemetry,
     startControl: args.control ?? answers.startControl ?? telemetry !== "off",
-    plugins: parsePluginsFlag(args.plugins) ?? answers.plugins ?? []
+    plugins: parsePluginsFlag(args.plugins) ?? answers.plugins ?? [],
+    agentSlotsMax
   };
 }
 function printSummary(result) {
@@ -90149,6 +90109,11 @@ function printSummary(result) {
   info(
     `Plugins:        ${result.pluginsApplied.length > 0 ? result.pluginsApplied.join(", ") : "none"}`
   );
+  if (result.agentSlots) {
+    info(
+      `Agent slots:    ${result.agentSlots.min}\u2013${result.agentSlots.max} parallel (see .har/stages.json)`
+    );
+  }
   if (result.adaptationPromptPath) {
     info(`Adapt prompt:   ${result.adaptationPromptPath}`);
     info(
@@ -90185,7 +90150,8 @@ async function handleOnboard(argv) {
       skipInit: argv.skipInit,
       deferAdaptationPrompt: true,
       autoYes: argv.yes,
-      forcePlugins: argv.force
+      forcePlugins: argv.force,
+      agentSlotsMax: choices.agentSlotsMax
     });
     if (result.harnessInitialized || harnessExists(repoPath)) {
       await handleCommitGateOnboarding({
@@ -90248,6 +90214,9 @@ var onboardCommand = {
   }).option("plugins", {
     type: "string",
     describe: "Comma-separated plugins to install (e.g. playwright); --no-plugins to skip; interactive checkbox when omitted"
+  }).option("agent-slots", {
+    type: "number",
+    describe: `Max parallel agent slots to configure in .har/stages.json (${HAR_AGENT_SLOT_MIN}\u2013${HAR_AGENT_SLOT_ONBOARD_MAX})`
   }).option("skip-guide", {
     type: "boolean",
     default: false,