@osfactory/har 1.14.3 → 1.15.1

package/dist/index.js

@@ -38722,6 +38722,26 @@ function substituteEnvTemplate(template, values) {
     }
   );
 }
+function findUnsubstitutedTemplateVars(template) {
+  const allowed = new Set(AGENT_ENV_TEMPLATE_VARS);
+  const found = /* @__PURE__ */ new Map();
+  template.split("\n").forEach((line, idx) => {
+    if (/^\s*#/.test(line)) return;
+    const re2 = /\$(?:\{([A-Za-z_][A-Za-z0-9_]*)([^}]*)(\}?)|([A-Za-z_][A-Za-z0-9_]*))/g;
+    for (let m = re2.exec(line); m !== null; m = re2.exec(line)) {
+      const braced = m[1] !== void 0;
+      const name = braced ? m[1] : m[4];
+      const plain = !braced || m[2] === "" && m[3] === "}";
+      const reason = plain ? "not-substituted" : "parameter-syntax";
+      if (plain && allowed.has(name)) continue;
+      const key = `${reason}:${name}`;
+      const entry = found.get(key) ?? { name, reason, lines: [] };
+      if (!entry.lines.includes(idx + 1)) entry.lines.push(idx + 1);
+      found.set(key, entry);
+    }
+  });
+  return [...found.values()];
+}
 function generateAgentEnvFile(options) {
   const templatePath = options.templatePath ?? path24.join(options.harnessDir, "env.template");
   if (!fs24.existsSync(templatePath)) return false;
@@ -40482,12 +40502,11 @@ function listPm2Processes() {
     return void 0;
   }
 }
-function detectForeignPm2(projectName, agentId, procs) {
+function detectForeignPm2(_projectName, agentId, procs) {
   if (!procs) return void 0;
-  const slotPrefix = `har-${projectName}-agent-${agentId}-`;
   const legacyPrefix = `agent-${agentId}-`;
   const foreign = procs.filter(
-    (p) => p.name && (p.name.startsWith("har-") && p.name.includes(`-agent-${agentId}-`) && !p.name.startsWith(slotPrefix) || p.name.startsWith(legacyPrefix) && !p.name.startsWith("har-"))
+    (p) => p.name && p.name.startsWith(legacyPrefix) && !p.name.startsWith("har-")
   );
   if (foreign.length === 0) return void 0;
   return {
@@ -40497,6 +40516,48 @@ function detectForeignPm2(projectName, agentId, procs) {
     }))
   };
 }
+function freeAgentSlots(harnessRoot, projectName, agentId, procs) {
+  let ids = [];
+  let range;
+  try {
+    range = getAgentSlotRange(harnessRoot);
+    ids = getAgentSlotIds(harnessRoot);
+  } catch {
+    return { free: [] };
+  }
+  const free = ids.filter((id) => {
+    if (id === agentId) return false;
+    const session = readSlotRegistry(harnessRoot, id);
+    if (session !== void 0 && session.status !== "completed") return false;
+    return detectForeignPm2(projectName, id, procs) === void 0;
+  });
+  return { free, range };
+}
+function foreignPm2Advice(agentId, processes, free, range) {
+  const cwds = [
+    ...new Set(processes.map((p) => p.cwd).filter((cwd) => Boolean(cwd)))
+  ];
+  const rangeLabel = range ? `agentSlots ${range.min}\u2013${range.max}` : "agentSlots in .har/stages.json";
+  const higher = free.filter((id) => id > agentId);
+  const suggested = higher[0] ?? free[0];
+  const lines = [];
+  if (suggested !== void 0) {
+    const kind = higher.length > 0 ? "higher slot" : "slot";
+    lines.push(
+      `Use a free ${kind}: har env launch ${suggested} (free: ${free.join(", ")}; ${rangeLabel}).`
+    );
+  } else if (range) {
+    lines.push(`No free slot in ${rangeLabel}. Raise agentSlots.max in .har/stages.json.`);
+  } else {
+    lines.push("Use a different agent slot (see agentSlots in .har/stages.json).");
+  }
+  lines.push(
+    "These processes belong to another project and must not be deleted from this checkout."
+  );
+  const where = cwds.length === 0 ? "that project checkout (cwd unknown)" : cwds.join(", ");
+  lines.push(`To stop that other session, run \`har env teardown ${agentId}\` in ${where}.`);
+  return { lines, suggested };
+}
 function infraEnabled2(env3, service) {
   return ` ${env3.HARNESS_INFRA_SERVICES ?? ""} `.includes(` ${service} `);
 }
@@ -40550,12 +40611,17 @@ function inspectSlotReadiness(repoPath, agentId, options = {}) {
   const foreign = usesPm2 ? detectForeignPm2(projectName, agentId, pm2Procs) : void 0;
   if (foreign) {
     const names = foreign.processes.map((p) => p.name).join(", ");
+    const slots = freeAgentSlots(harnessRoot, projectName, agentId, pm2Procs);
+    const advice = foreignPm2Advice(agentId, foreign.processes, slots.free, slots.range);
     blockers.push({
       code: "foreign_pm2",
       message: `Foreign PM2 processes match agent ${agentId}: ${names}`,
-      remediation: "Stop the other harness session (`har env teardown` in that repo) or use a different agent slot.",
-      details: { processes: foreign.processes }
+      remediation: advice.lines.join(" "),
+      details: { processes: foreign.processes, adviceLines: advice.lines }
     });
+    if (advice.suggested !== void 0) {
+      remediations.push(`har env launch ${advice.suggested}`);
+    }
     remediations.push(`Inspect with: ${packageRunner()} pm2 jlist | grep agent-${agentId}`);
   }
   if (usesPm2 && pm2Procs) {
@@ -40708,10 +40774,14 @@ function bashBlockerLines(agentId, b2) {
   switch (b2.code) {
     case "foreign_pm2": {
       const procs = details.processes ?? [];
+      const advice = Array.isArray(details.adviceLines) ? details.adviceLines : [
+        "Use a different agent slot.",
+        "These processes belong to another project and must not be deleted from this checkout."
+      ];
       return [
         `ERROR: foreign PM2 processes match agent ${agentId}:`,
         ...procs.map((p) => `  ${p.name}  cwd=${p.cwd ?? "unknown"}`),
-        "  Stop the other harness session or use a different slot."
+        ...advice.map((line) => `  ${line}`)
       ];
     }
     case "control_port_conflict":
@@ -40814,6 +40884,7 @@ var init_slot_preflight = __esm({
     init_slot_launch_guard_occupied();
     init_slot_ports();
     init_capabilities();
+    init_stages();
     init_slot_registry();
     init_worktree_untracked();
     import_child_process11 = require("child_process");
@@ -42480,7 +42551,7 @@ function detectPm2Issue(projectName, agentId, session, procs) {
   const legacyPrefix = `agent-${agentId}-`;
   const owned = procs.filter((p) => p.name?.startsWith(slotPrefix));
   const foreign = procs.filter(
-    (p) => p.name && (p.name.startsWith("har-") && p.name.includes(`-agent-${agentId}-`) && !p.name.startsWith(slotPrefix) || p.name.startsWith(legacyPrefix) && !p.name.startsWith("har-"))
+    (p) => p.name && p.name.startsWith(legacyPrefix) && !p.name.startsWith("har-")
   );
   if (foreign.length > 0) return "foreign_pm2";
   if (owned.length > 0) {
@@ -84485,6 +84556,7 @@ function applyLine(repoPath, lineSpec, options = {}) {
 // src/harness/doctor.ts
 init_stages();
 init_hooks2();
+init_agent_env();
 
 // src/harness/migrations.ts
 var fs64 = __toESM(require("fs"));
@@ -84969,6 +85041,7 @@ var CHECK_LABELS = {
   "lifecycle-stages": "lifecycle stages (launch/verify/teardown)",
   "verification-ids": "verificationStages ids",
   "port-lanes": "infra port lanes",
+  "env-template": "env.template placeholders",
   "slot-registry": "slot registry worktrees",
   hooks: "lifecycle hooks (.har/hooks)",
   "retired-machinery": "no references to retired runtime machinery",
@@ -85196,6 +85269,27 @@ function runDoctor(repoPath) {
       }
     }
   }
+  const envTemplatePath = path73.join(harnessDir, "env.template");
+  if (!fs65.existsSync(envTemplatePath)) {
+    skipped.add("env-template");
+  } else {
+    const allowed = new Set(AGENT_ENV_TEMPLATE_VARS);
+    const allowedVars = AGENT_ENV_TEMPLATE_VARS.join(", ");
+    const template = fs65.readFileSync(envTemplatePath, "utf8");
+    for (const { name, reason, lines } of findUnsubstitutedTemplateVars(template)) {
+      const rest = lines.slice(1);
+      const more = rest.length ? ` (also line${rest.length > 1 ? "s" : ""} ${rest.join(", ")})` : "";
+      const literalDollar = "A literal `$` cannot be written in env.template: envsubst has no escape and keeps `\\$` as-is";
+      findings.push({
+        check: "env-template",
+        severity: "warning",
+        file: "env.template",
+        line: lines[0],
+        message: reason === "parameter-syntax" ? `\${${name}\u2026} uses shell parameter syntax, which launch never expands \u2014 the whole reference is written literally to .env.agent.<id>${more}` : `\${${name}} is not substituted at launch and will be written literally to .env.agent.<id>${more}`,
+        remedy: reason === "parameter-syntax" && allowed.has(name) ? `Write a plain \${${name}}; :- / :? / # / % are not supported by envsubst` : `Use one of ${allowedVars} (plain \${NAME}, no modifiers), or hard-code the value (variables in harness.env are not substituted into env.template). ${literalDollar}`
+      });
+    }
+  }
   const manifest = readManifest(repoPath);
   if (!manifest?.ejected) {
     skipped.add("ejected-runtime");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osfactory/har",
-  "version": "1.14.3",
+  "version": "1.15.1",
   "description": "HAR: open agent harness CLI and MCP server for coding agents, isolated worktrees, and software-factory workflows",
   "keywords": [
     "har",