@osfactory/har 0.16.1 → 0.17.0

package/dist/index.js

@@ -28652,6 +28652,20 @@ function readSlotRegistry(repoPath, agentId) {
 }
 
 // src/core/local-executor.ts
+function quoteShellArg(arg) {
+  if (/^[A-Za-z0-9_./:=+-]+$/.test(arg)) return arg;
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+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.purpose) args.push(`--purpose=${flags.purpose}`);
+  return args;
+}
 function resolveRepoPath(repoPath) {
   return path24.resolve(repoPath);
 }
@@ -28729,18 +28743,14 @@ function buildExecutionPlan(repoPath, stage, options) {
   };
   const cwd = stage.cwd ? path24.resolve(resolvedRepo, stage.cwd) : resolvedRepo;
   const extraArgs = options.args ?? [];
-  const launchFlagArgs = [];
-  if (stage.kind === "launch" && options.launchFlags) {
-    if (options.launchFlags.worktree === false) launchFlagArgs.push("--no-worktree");
-    if (options.launchFlags.claude) launchFlagArgs.push("--claude");
-    if (options.launchFlags.confirmReplace) launchFlagArgs.push("--replace");
-    if (options.launchFlags.force) launchFlagArgs.push("--force");
-    if (options.launchFlags.resume) launchFlagArgs.push("--resume");
+  const launchFlagArgs = stage.kind === "launch" && options.launchFlags ? buildLaunchFlagArgs(options.launchFlags) : [];
+  if (stage.kind === "launch" && options.launchFlags?.purpose) {
+    mergedEnv.HAR_SESSION_PURPOSE = options.launchFlags.purpose;
   }
   if (stage.command) {
     let shellCommand = substituteAgentId(stage.command, options.agentId);
     for (const extra of [...extraArgs, ...launchFlagArgs]) {
-      shellCommand = `${shellCommand} ${extra}`;
+      shellCommand = `${shellCommand} ${quoteShellArg(extra)}`;
     }
     return { mode: "shell", shellCommand, args: [], cwd, env: mergedEnv };
   }
@@ -29309,6 +29319,7 @@ function collectOccupiedSlot(repoPath, agentId) {
     sessionStatus: session?.status,
     lastError: session?.lastError,
     sessionCreatedAt: session?.createdAt,
+    purpose: session?.purpose,
     dirty,
     harnessUsage: "none"
   };
@@ -29319,6 +29330,7 @@ function formatOccupiedSlot(slot, resume) {
     slot.worktreePath ? `  Worktree: ${slot.worktreePath}` : void 0,
     slot.branch ? `  Branch:   ${slot.branch}` : void 0,
     slot.workDir ? `  Work dir: ${slot.workDir}` : void 0,
+    slot.purpose ? `  Purpose:  ${slot.purpose}` : void 0,
     slot.sessionStatus ? `  Status:   ${slot.sessionStatus}` : void 0,
     slot.lastError ? `  Error:    ${slot.lastError}` : void 0,
     slot.sessionCreatedAt ? `  Since:    ${slot.sessionCreatedAt}` : void 0,
@@ -31105,7 +31117,8 @@ var RunService = class {
           worktreePath: slot.worktreePath,
           branch: slot.branch,
           dirty: slot.dirty,
-          sessionCreatedAt: slot.sessionCreatedAt
+          sessionCreatedAt: slot.sessionCreatedAt,
+          purpose: slot.purpose
         } : void 0
       };
     }
@@ -31134,7 +31147,8 @@ Usage from Claude Code / Codex will appear under Worktrees. Disable: har telemet
         claude: options.claude,
         confirmReplace: options.confirmReplace,
         force: options.force,
-        resume: options.resume
+        resume: options.resume,
+        purpose: options.purpose
       },
       trigger: "cli"
     });
@@ -31453,6 +31467,9 @@ var envCommand = {
       type: "boolean",
       default: false,
       describe: "Resume a failed or partial launch without creating a new worktree"
+    }).option("purpose", {
+      type: "string",
+      describe: "Optional session label stored in the slot registry (shown in status and occupied-slot warnings)"
     }),
     handleLaunch
   ).command(
@@ -31838,6 +31855,7 @@ async function handleLaunch(argv) {
     confirmReplace,
     force,
     resume: argv.resume,
+    purpose: argv.purpose,
     capture: false
   });
   if (result.blocked) {
@@ -39872,7 +39890,10 @@ var LaunchEnvironmentInputSchema = external_exports.object({
   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.")
+  resume: external_exports.boolean().default(false).describe("Resume a failed or partial launch without creating a new worktree."),
+  purpose: external_exports.string().optional().describe(
+    "Optional session label stored in the slot registry (shown in status and occupied-slot warnings)."
+  )
 });
 var LaunchEnvironmentOutputSchema = ShellRunOutputSchema.extend({
   previewUrls: external_exports.record(external_exports.string()).optional(),
@@ -39886,7 +39907,8 @@ var LaunchEnvironmentOutputSchema = ShellRunOutputSchema.extend({
     worktreePath: external_exports.string().optional(),
     branch: external_exports.string().optional(),
     dirty: external_exports.boolean().optional(),
-    sessionCreatedAt: external_exports.string().optional()
+    sessionCreatedAt: external_exports.string().optional(),
+    purpose: external_exports.string().optional()
   }).optional()
 });
 var PreflightEnvironmentInputSchema = external_exports.object({
@@ -40011,6 +40033,10 @@ var HAR_MCP_TOOLS = [
         resume: {
           type: "boolean",
           description: "Resume a failed or partial launch (status failed/starting) without --replace. Preserves worktree and env."
+        },
+        purpose: {
+          type: "string",
+          description: "Optional session label stored in the slot registry (shown in status and occupied-slot warnings)."
         }
       },
       ["agentId"]
@@ -40194,6 +40220,7 @@ async function handleMcpToolCall(toolName, args, defaultRepo = ".") {
         confirmReplace: input.confirmReplace,
         force: input.force,
         resume: input.resume,
+        purpose: input.purpose,
         capture: true
       });
       const parsed = LaunchEnvironmentOutputSchema.parse(result);

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

@@ -30,7 +30,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_SESSION_PURPOSE=label` or `--purpose=label` on launch so occupied-slot warnings show what you were doing.
+- 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.
 
 <!-- Monorepo: if this repository contains multiple .har harnesses, list them here
      and pick by the files you are changing. Example:

package/package.json

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