@osfactory/har 1.3.0 → 1.5.0

package/dist/index.js

@@ -4796,7 +4796,9 @@ var init_schema = __esm({
       toolCallId: external_exports.string().optional(),
       correlationId: external_exports.string().optional(),
       workUnitId: WorkUnitIdSchema.optional(),
-      attemptId: WorkAttemptIdSchema.optional()
+      attemptId: WorkAttemptIdSchema.optional(),
+      /** One occupancy of a slot (#316) — records are scoped to it, not to slot id. */
+      occupancyKey: external_exports.string().min(1).optional()
     }).passthrough();
     AgentTrajectoryRecordSchema = AgentTrajectoryRecordV1Schema;
     USAGE_HARVEST_VERSION = 2;
@@ -4811,6 +4813,8 @@ var init_schema = __esm({
       suffix: external_exports.string().optional(),
       workUnitId: WorkUnitIdSchema.optional(),
       attemptId: WorkAttemptIdSchema.optional(),
+      /** One occupancy of a slot (#316) — usage is scoped to it, not to slot id. */
+      occupancyKey: external_exports.string().min(1).optional(),
       tokensInput: external_exports.number().nonnegative().default(0),
       tokensOutput: external_exports.number().nonnegative().default(0),
       tokensCacheRead: external_exports.number().nonnegative().default(0),
@@ -32752,6 +32756,13 @@ function findValidation(checkoutDir, treeHash) {
     return void 0;
   }
 }
+function findPassingFullValidation(input) {
+  if (!isCheckoutRoot(input.checkoutDir)) return void 0;
+  const { treeHash } = computeWorktreeSnapshot(input.checkoutDir);
+  const record2 = findValidation(input.checkoutDir, treeHash) ?? (input.harnessRoot ? findValidation(input.harnessRoot, treeHash) : void 0);
+  if (record2?.status === "pass" && record2.full) return record2;
+  return void 0;
+}
 function attachCommit(checkoutDir, treeHash, commitSha) {
   const record2 = findValidation(checkoutDir, treeHash);
   if (!record2) return void 0;
@@ -59038,10 +59049,12 @@ var require_run_async = __commonJS({
 // src/core/otel-hooks.ts
 var otel_hooks_exports = {};
 __export(otel_hooks_exports, {
+  HOOK_TIMEOUT_SECONDS: () => HOOK_TIMEOUT_SECONDS,
   LEGACY_CURSOR_ONLY_HOOK_EVENTS: () => LEGACY_CURSOR_ONLY_HOOK_EVENTS,
   OTEL_HOOKS_AGENTS: () => OTEL_HOOKS_AGENTS,
   OTEL_HOOKS_PACKAGE: () => OTEL_HOOKS_PACKAGE,
   OTEL_HOOKS_PROVIDERS: () => OTEL_HOOKS_PROVIDERS,
+  buildOtelHookSetupArgs: () => buildOtelHookSetupArgs,
   buildOtelHooksConfig: () => buildOtelHooksConfig,
   disableOtelHooksExport: () => disableOtelHooksExport,
   ensureOtelHooks: () => ensureOtelHooks,
@@ -59147,11 +59160,22 @@ function writeOtelHooksWrapper(otelHookCommand, hooksHome = getOtelHooksHome())
   const stateDir = getOtelHooksStateDir(hooksHome);
   const script = `#!/usr/bin/env bash
 # Managed by har telemetry \u2014 invokes @osfactory/otel-hook with HAR config.
-set -euo pipefail
-exec "${otelHookCommand}" run \\
+#
+# Two rules for this wrapper (#328):
+#   1. Bounded. Export and flush budgets keep it well inside the per-hook
+#      timeout the agent enforces, so an unreachable Mission Control costs
+#      milliseconds instead of stalling the session.
+#   2. Silent about its own failures. Dropped telemetry must never fail an
+#      agent turn, so the exit status is always 0 \u2014 a non-zero hook exit can
+#      block a tool call.
+set -uo pipefail
+"${otelHookCommand}" run \\
   --config-file "${configPath}" \\
   --state-dir "${stateDir}" \\
-  "$@"
+  --timeout-ms ${HOOK_EXPORT_TIMEOUT_MS} \\
+  --flush-timeout-ms ${HOOK_FLUSH_TIMEOUT_MS} \\
+  "$@" || true
+exit 0
 `;
   fs68.writeFileSync(wrapperPath, script, { mode: 493 });
   try {
@@ -59244,23 +59268,30 @@ function isOtelHookCommand(command2, wrapperPath) {
 function normalizeLegacyProviderFlagsInCommand(command2) {
   return command2.replace(/(^|\s)--cursor(?=\s|$)/g, "$1--provider cursor").replace(/(^|\s)--claude(?=\s|$)/g, "$1--provider claude-code").replace(/(^|\s)--codex(?=\s|$)/g, "$1--provider codex");
 }
+function buildOtelHookSetupArgs(providerId, hookCommand) {
+  return [
+    "setup",
+    "--provider",
+    providerId,
+    "--scope",
+    "global",
+    "--hook-command",
+    hookCommand,
+    "--managed-marker",
+    "otel-hook",
+    // Written into each generated hook entry so the agent bounds it (#328).
+    // Without this the agent falls back to its own default and an unreachable
+    // collector stalls the session before its first model request.
+    "--timeout-seconds",
+    String(HOOK_TIMEOUT_SECONDS)
+  ];
+}
 function runSetupProvider(providerId, otelHookCommand, wrapperPath) {
   const hookCommand = `${wrapperPath} --provider ${providerId}`;
-  const result = (0, import_child_process19.spawnSync)(
-    otelHookCommand,
-    [
-      "setup",
-      "--provider",
-      providerId,
-      "--scope",
-      "global",
-      "--hook-command",
-      hookCommand,
-      "--managed-marker",
-      "otel-hook"
-    ],
-    { encoding: "utf8", timeout: 6e4 }
-  );
+  const result = (0, import_child_process19.spawnSync)(otelHookCommand, buildOtelHookSetupArgs(providerId, hookCommand), {
+    encoding: "utf8",
+    timeout: 6e4
+  });
   if (result.status === 0) {
     return { ok: true, detail: `setup --provider ${providerId}` };
   }
@@ -59487,7 +59518,7 @@ function ensureOtelHooks(options) {
 function disableOtelHooksExport() {
   return writeOtelHooksConfig(buildOtelHooksConfig({ enabled: false }));
 }
-var import_child_process19, fs68, os22, path76, OTEL_HOOKS_PACKAGE, OTEL_HOOKS_PROVIDERS, OTEL_HOOKS_AGENTS, LEGACY_CURSOR_ONLY_HOOK_EVENTS;
+var import_child_process19, fs68, os22, path76, OTEL_HOOKS_PACKAGE, HOOK_TIMEOUT_SECONDS, HOOK_EXPORT_TIMEOUT_MS, HOOK_FLUSH_TIMEOUT_MS, OTEL_HOOKS_PROVIDERS, OTEL_HOOKS_AGENTS, LEGACY_CURSOR_ONLY_HOOK_EVENTS;
 var init_otel_hooks = __esm({
   "src/core/otel-hooks.ts"() {
     "use strict";
@@ -59498,6 +59529,9 @@ var init_otel_hooks = __esm({
     init_control_config();
     init_telemetry_config();
     OTEL_HOOKS_PACKAGE = "@osfactory/otel-hook@0.2.0";
+    HOOK_TIMEOUT_SECONDS = 10;
+    HOOK_EXPORT_TIMEOUT_MS = 1500;
+    HOOK_FLUSH_TIMEOUT_MS = 500;
     OTEL_HOOKS_PROVIDERS = [
       { id: "cursor", label: "cursor" },
       { id: "claude-code", label: "claude" },
@@ -79330,9 +79364,9 @@ Usage from Cursor / Claude / Codex (@osfactory/otel-hook) will appear under Work
     return envResult;
   }
   /**
-   * Finish a session: full verification (recorded as a validation keyed by the
-   * worktree tree hash), then teardown. The session branch is kept so the user
-   * can push it and open a PR.
+   * Finish a session: reuse the last matching passing full validation (or
+   * re-run verify when asked), then teardown. The session branch is kept so
+   * the user can push it and open a PR.
    */
   async completeEnvironment(options) {
     const harnessRoot = resolveHarnessRoot(options.repoPath);
@@ -79344,9 +79378,11 @@ Usage from Cursor / Claude / Codex (@osfactory/otel-hook) will appear under Work
         stderr: `No active session for agent ${options.agentId}. Run launch first.`
       };
     }
+    const runVerify = shouldReverifyOnComplete(options);
     let verification;
     let validation2;
-    if (!options.skipVerify) {
+    let reusedValidation = false;
+    if (runVerify) {
       const verify = await this.runVerification({
         repoPath: options.repoPath,
         agentId: options.agentId,
@@ -79359,11 +79395,27 @@ Usage from Cursor / Claude / Codex (@osfactory/otel-hook) will appear under Work
       if (verify.code !== 0 || verification?.status !== "pass") {
         return {
           ...verify,
-          stderr: verify.stderr + "\nVerification failed \u2014 session NOT completed. Fix the failures and rerun, or complete with skipVerify."
+          stderr: verify.stderr + "\nVerification failed \u2014 session NOT completed. Fix the failures and rerun `complete --verify`, or use teardown to free the slot without claiming completion."
         };
       }
+    } else {
+      const checkoutDir = resolveValidationCheckoutDir({
+        worktreePath: session.worktreePath,
+        workDir: session.workDir,
+        harnessRoot
+      });
+      validation2 = findPassingFullValidation({ checkoutDir, harnessRoot });
+      if (!validation2) {
+        return {
+          code: 1,
+          stdout: "",
+          stderr: `No passing full validation matches the current worktree. The tree may have changed since the last \`har env verify --full\`. Re-run verification with: har env complete ${options.agentId} --verify
+Or free the slot without claiming completion: har env teardown ${options.agentId}`
+        };
+      }
+      reusedValidation = true;
     }
-    if (session.workUnitId && session.attemptId && !options.skipVerify && !validation2) {
+    if (session.workUnitId && session.attemptId && runVerify && !validation2) {
       return {
         code: 1,
         stdout: "",
@@ -79387,11 +79439,13 @@ Usage from Cursor / Claude / Codex (@osfactory/otel-hook) will appear under Work
       trigger: options.trigger
     });
     if (teardown.code !== 0) return { ...teardown, verification };
+    const reusedNote = reusedValidation && validation2 ? `Reused passing full validation ${validation2.validationId} for tree ${validation2.treeHash}.
+` : "";
     const branchNote = session.branch ? `Branch kept: ${session.branch} \u2014 push it with: git push -u origin ${session.branch}
 ` : "";
     return {
       ...teardown,
-      stdout: teardown.stdout + branchNote,
+      stdout: teardown.stdout + reusedNote + branchNote,
       branch: session.branch,
       workDir: session.workDir,
       worktreePath: session.worktreePath,
@@ -79430,6 +79484,10 @@ Usage from Cursor / Claude / Codex (@osfactory/otel-hook) will appear under Work
     return toEnvironmentRunResult(result);
   }
 };
+function shouldReverifyOnComplete(options) {
+  if (options.verify === true) return true;
+  return options.skipVerify === false;
+}
 var defaultRunService = new RunService();
 function createRunService(executor = localScriptExecutor) {
   return new RunService(executor);
@@ -79919,12 +79977,12 @@ Typical agent workflow:
   har env launch <id>            # new session from the main checkout's HEAD
   # \u2026edit only under the printed work dir\u2026
   har env verify <id> --full
-  har env complete <id>          # done: verify + free the slot (branch kept for PR)
+  har env complete <id>          # done: reuse last full validation + free the slot (branch kept for PR)
 
 Slot lifecycle (do not confuse these):
   launch     start a NEW session (worktree from $REPO_ROOT HEAD)
   recover    resume a failed/partial launch (keeps the existing worktree)
-  complete   finish successfully: full verify, then teardown (frees the slot)
+  complete   finish successfully: reuse last matching full validation, then teardown (frees the slot)
   teardown   abandon / free the slot without a completion validation
 
 Occupied slots always block a new launch:
@@ -79940,7 +79998,7 @@ var HAR_ENV_EPILOG = `Environment lifecycle:
   launch <id>      fresh session worktree from the main checkout's current HEAD
   recover <id>     alias for launch --resume (failed/starting only)
   verify <id>      run checks (--full before declaring done)
-  complete <id>    full verify + teardown; keeps branch for push/PR (frees slot)
+  complete <id>    reuse last full validation + teardown; --verify to re-run; keeps branch (frees slot)
   teardown <id>    free the slot without recording a completion validation
 
 Occupied slots:
@@ -80168,11 +80226,15 @@ var envCommand = {
     handleTeardown
   ).command(
     "complete <id>",
-    "Finish a session: full verify (recorded as validation), teardown, keep the branch for a PR",
-    (y) => y.positional("id", { type: "number", describe: "Agent slot id (see .har/stages.json agentSlots)" }).option("repo", { type: "string", default: "." }).option("skip-verify", {
+    "Finish a session: reuse the last matching full validation, teardown, keep the branch for a PR",
+    (y) => y.positional("id", { type: "number", describe: "Agent slot id (see .har/stages.json agentSlots)" }).option("repo", { type: "string", default: "." }).option("verify", {
       type: "boolean",
       default: false,
-      describe: "Tear down without running verification (no validation is recorded)"
+      describe: "Re-run full verification before teardown (use when the tree may have changed since the last passing --full)"
+    }).option("skip-verify", {
+      type: "boolean",
+      hidden: true,
+      describe: "Deprecated no-op: complete already skips re-verification by default"
     }),
     handleComplete
   ).command(
@@ -80694,6 +80756,7 @@ async function handleComplete(argv) {
   const result = await completeEnvironment({
     repoPath: repo,
     agentId,
+    verify: argv.verify,
     skipVerify: argv.skipVerify,
     capture: false
   });
@@ -90261,6 +90324,14 @@ async function runLineGate(options) {
   }
   const registry2 = readStageRegistry(repoPath);
   const registeredIds = new Set(registry2.stages.map((s) => s.id));
+  if (options.agentId === void 0) {
+    const needSlot = required2.filter((stage) => registry2.stages.find((s) => s.id === stage.id)?.requiresAgentId).map((stage) => stage.id);
+    if (needSlot.length > 0) {
+      throw new Error(
+        `Gate stage(s) ${needSlot.join(", ")} run in an agent slot \u2014 pass --agent <id> (har line gate ${options.station} --line ${lineId} --agent 1).`
+      );
+    }
+  }
   const results = [];
   let pass = true;
   for (const stage of required2) {
@@ -90431,7 +90502,12 @@ var PreflightEnvironmentOutputSchema = ShellRunOutputSchema.extend({
 var CompleteEnvironmentInputSchema = external_exports.object({
   repo: external_exports.string().default("."),
   agentId: agentIdSchema,
-  skipVerify: external_exports.boolean().default(false).describe("Tear down without running verification (no validation is recorded)")
+  verify: external_exports.boolean().optional().describe(
+    "Re-run full verification before teardown when the tree may have changed since the last passing --full"
+  ),
+  skipVerify: external_exports.boolean().optional().describe(
+    "Deprecated. Complete already skips re-verification by default. Pass verify=true to re-run; skipVerify=false still forces a re-run."
+  )
 });
 var CompleteEnvironmentOutputSchema = ShellRunOutputSchema.extend({
   branch: external_exports.string().optional().describe("Session branch kept for the user to push / open a PR"),
@@ -90739,14 +90815,18 @@ var HAR_MCP_TOOLS = [
   },
   {
     name: "har_complete_environment",
-    description: "Finish a session when the work is done: runs full verification (recorded as a validation of the worktree tree hash), tears the slot down, and KEEPS the session branch so the user can push it and open a PR.",
+    description: "Finish a session when the work is done: reuses the last passing full validation for the current worktree (or re-runs verify when verify=true), tears the slot down, and KEEPS the session branch so the user can push it and open a PR.",
     inputSchema: objectJsonSchema(
       {
         repo: repoJsonProperty,
         agentId: agentIdJsonProperty,
+        verify: {
+          type: "boolean",
+          description: "Re-run full verification before teardown when the tree may have changed since the last passing --full"
+        },
         skipVerify: {
           type: "boolean",
-          description: "Tear down without running verification (no validation is recorded)"
+          description: "Deprecated. Complete already skips re-verification by default. Pass verify=true to re-run."
         }
       },
       ["agentId"]
@@ -91083,6 +91163,7 @@ async function handleMcpToolCall(toolName, args, defaultRepo = ".") {
       const result = await completeEnvironment({
         repoPath: repo,
         agentId,
+        verify: input.verify,
         skipVerify: input.skipVerify,
         capture: true,
         trigger: "mcp"
@@ -91277,7 +91358,7 @@ var ONBOARDING_GUIDE_STEPS = [
     body: [
       "Quick:  har env verify <id>",
       "Done:   har env verify <id> --full   then   har env complete <id>",
-      "`complete` records a validation, frees the slot, and keeps the session branch for a PR."
+      "`complete` reuses the last matching full validation, frees the slot, and keeps the session branch for a PR. Pass --verify if the tree changed."
     ].join("\n")
   },
   {
@@ -92459,6 +92540,12 @@ async function handleStatus3(argv) {
   info(`Mission Control: ${apiUrl} (${reachable ? "reachable" : "not reachable"})`);
   info(`OTLP endpoint: ${payload.otelEndpoint}`);
   info(`Hooks home:    ${payload.otelHooksHome}`);
+  if (enabled && !reachable) {
+    warn(
+      "Agent hooks are installed but Mission Control is not reachable \u2014 each turn pays the export timeout for telemetry nobody receives."
+    );
+    info("Start it with: har control up   \u2022   or stop exporting: har telemetry off");
+  }
   printSignals();
 }
 async function handleOn(argv) {

package/dist/templates/agent-skills/har-wt.md

@@ -57,7 +57,8 @@ Do not substitute ad-hoc test commands for harness verification. Any edit after
 ## 5. Finish
 
 ```bash
-har env complete <id>   # full verify + validation record + teardown, keeps the session branch
+har env complete <id>   # reuse last passing full validation + teardown, keeps the session branch
+har env complete <id> --verify   # re-run full verify first if the tree may have changed
 ```
 
 Report to the user: verification result, the session branch name (so they can push / open a PR), and the slot preview URLs if the app is running.

package/dist/templates/profiles/cli/docs/readme/definition-of-done.md

@@ -6,7 +6,7 @@
 - [ ] New behavior has automated test coverage
 - [ ] Changes committed **in the session worktree** with a clear message
 - [ ] Present session handoff (summary, branch, preview URLs) and **wait for user** before `complete`, push, or PR
-- [ ] On user approval of the default: push + open PR (when `gh`/GitHub MCP available), then `har env complete <id>` (or MCP `har_complete_environment`) — full verify + validation + teardown, branch kept
+- [ ] On user approval of the default: push + open PR (when `gh`/GitHub MCP available), then `har env complete <id>` (or MCP `har_complete_environment`) — reuse last passing full validation + teardown, branch kept. Pass `--verify` / `verify: true` if the tree may have changed.
 
 ### Session handoff
 

package/dist/templates/profiles/default/docs/readme/definition-of-done.md

@@ -7,7 +7,7 @@
 - [ ] Changes committed **in the session worktree** with a clear message
 - [ ] The user got the preview URLs to test the app themselves
 - [ ] Present session handoff (summary, branch, preview URLs) and **wait for user** before `complete`, push, or PR
-- [ ] On user approval of the default: push + open PR (when `gh`/GitHub MCP available), then `har env complete <id>` (or MCP `har_complete_environment`) — full verify + validation + teardown, branch kept
+- [ ] On user approval of the default: push + open PR (when `gh`/GitHub MCP available), then `har env complete <id>` (or MCP `har_complete_environment`) — reuse last passing full validation + teardown, branch kept. Pass `--verify` / `verify: true` if the tree may have changed.
 
 ### Session handoff
 

package/dist/templates/profiles/ios/docs/readme/definition-of-done.md

@@ -6,7 +6,7 @@
 - [ ] New behavior has automated test coverage (unit tests via XCTest)
 - [ ] Changes committed **in the session worktree** with a clear message
 - [ ] Present session handoff (summary, branch, preview URLs) and **wait for user** before `complete`, push, or PR
-- [ ] On user approval of the default: push + open PR (when `gh`/GitHub MCP available), then `har env complete <id>` (or MCP `har_complete_environment`) — full verify + validation + teardown, branch kept
+- [ ] On user approval of the default: push + open PR (when `gh`/GitHub MCP available), then `har env complete <id>` (or MCP `har_complete_environment`) — reuse last passing full validation + teardown, branch kept. Pass `--verify` / `verify: true` if the tree may have changed.
 
 ### Session handoff
 

package/dist/templates/shared-docs/readme/session-lifecycle.md

@@ -15,6 +15,7 @@ never in the main checkout.
   or open a PR (`--delete-branch` to drop it).
 - If launch fails after creating a worktree/env file, the registry records `status: failed`.
   Resume it instead of starting fresh: `har env launch <id> --resume` or `har env recover <id>`.
-- `har env complete <id>` finishes a session: full verify (recorded as a validation),
-  then teardown — branch kept.
+- `har env complete <id>` finishes a session: reuses the last matching passing
+  full validation, then teardown — branch kept. Pass `--verify` to re-run full
+  verify if the tree may have changed.
 - `--no-worktree` runs the slot from the repo root instead (single-agent mode).

package/package.json

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