@smartergpt/lexrunner 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,31 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-07-30
+
+### Added
+
+- **Windows-to-native-WSL Attempt projection** - Added a read-only containment preflight,
+  versioned projection and path-mapping contracts, rollback-safe native provisioning, and
+  identity-bound launch, worker, receipt, verification, acceptance, and cleanup behavior.
+- **Shared projection lifecycle** - Added matching CLI
+  `attempt projection prepare|status|cleanup|quarantine` operations and MCP lifecycle tools with
+  explicit mutation authority, path-private diagnostics, bounded quarantine inspection, and a
+  recovery runbook.
+- **Independent merge review gate** - Documented a mandatory-by-default, exact-head review step
+  whose verdict is invalidated by candidate changes and whose opt-out requires an explicit warned
+  `review_bypassed` receipt.
+
+### Fixed
+
+- **Plan validation diagnostics** - Return the individual validation failures instead of only an
+  aggregate count, preserving the dogfood evidence needed to repair invalid plans.
+- **Explicit plan references** - Resolve explicitly selected plan artifacts consistently across
+  MCP status, ordering, and gate operations.
+- **Projection durability and recovery** - Fail closed across selection revocation/publication,
+  staging ownership, quarantine marker persistence, directory sync failures, source refresh, and
+  active-worktree cleanup refusal.
+
 ---
 
 ## [1.2.1] - 2026-07-21

package/README.mcp.md

@@ -113,6 +113,40 @@ This MCP server follows the same architectural pattern as LexBrain and LexMap:
 
 ## Available Tools
 
+### preflight_attempt_containment
+
+Checks whether the current runtime and declared repository/worktree roots can host LexRunner's
+physical directory-identity boundary before an Attempt packet is constructed. This tool is always
+read-only and does not require `ALLOW_MUTATIONS`.
+
+It returns `native_ready`, `broker_required`, or `unsupported` with stable reason codes, bounded
+next actions, verification depth for each root, and a privacy-safe binding digest. Native Windows
+and WSL DrvFS/9P inputs recommend a native-WSL projection without weakening the containment
+boundary.
+
+### Native WSL projection lifecycle
+
+Four tools share one bounded lifecycle service with the matching
+`lex-pr attempt projection <operation> --input <file|-> --json` commands:
+
+- `get_native_wsl_projection_status` reads exact lifecycle state without creating control, lock,
+  projection, or SQLite state.
+- `inspect_native_wsl_projection_quarantine` reads privacy-bounded quarantine counts and entry
+  digests.
+- `prepare_native_wsl_projection` prepares or exactly reuses the requested committed base.
+- `cleanup_native_wsl_projection` removes an exact idle projection and its matching quarantine
+  state; active worktrees are refused.
+
+Prepare and cleanup require both `"mutation": {"authorized": true}` in the input and the MCP
+server mutation gate. Status and quarantine inspection remain available when mutations are
+disabled. All results omit source/native paths and expose stable digests, reason codes, bounded
+command evidence, counts, and next actions.
+
+On success, pass the returned `selectionDigest` to projected `attempt prepare`. Launch resolves
+the engine-authored selection, emits the machine-verifiable execution path mapping, and preserves
+the request's exact `base_sha` even when the Windows source HEAD or dirty state later changes.
+See the [native Windows-to-WSL projection workflow](docs/workflows/native-wsl-projection.md).
+
 ### mcp_lexrunner_plan_create
 
 Creates a plan from configuration files or auto-discovers from GitHub PRs. This is a **convenience wrapper** that combines PR discovery (`pr_list`), plan generation, validation, and file writing into a single operation.
@@ -428,11 +462,21 @@ Executes gates for plan items. Can work with either an internal plan (created vi
 
 > **Deprecated alias:** `gates.run`
 
+All overlapping integration tools use the same plan-reference precedence:
+
+1. `planFile`, when supplied. The explicit reference is authoritative and never falls through.
+2. `plan.json` in the repository root.
+3. `<profile>/runner/plan.json` as the backward-compatible `plan_create` fallback.
+
+Their results include the same path-independent `planArtifact` identity. Compare its canonical
+`digest` to verify that status, merge ordering, gate execution, and merge preview consumed the
+same frozen plan.
+
 **Parameters:**
 
-- `planFile` (string, optional): Path to external plan.json file. If not provided, uses internal state from the profile directory.
-- `onlyItem` (string, optional): Run gates for specific item only
-- `onlyGate` (string, optional): Run specific gate only
+- `planFile` (string, optional): Explicit path to an authored plan
+- `onlyItem` (string, optional): Execute gates for this item only
+- `onlyGate` (string, optional): Execute this gate only
 - `outDir` (string, optional): Output directory for gate results
 
 **Returns:**
@@ -451,11 +495,20 @@ Executes gates for plan items. Can work with either an internal plan (created vi
       ]
     }
   ],
-  "allGreen": true
+  "allGreen": true,
+  "planArtifact": {
+    "contract": "plan-artifact-identity-v1",
+    "kind": "execution-plan",
+    "schema": "lexrunner.execution-plan",
+    "schemaVersion": "1.0.0",
+    "digest": "sha256:...",
+    "target": "main",
+    "itemCount": 1
+  }
 }
 ```
 
-**Example (using internal plan):**
+**Example (using repository or profile fallback):**
 
 ```json
 {
@@ -481,7 +534,8 @@ Executes gates for plan items. Can work with either an internal plan (created vi
 
 **Use Cases:**
 
-- **Internal state**: Run gates on a plan created via `mcp_lexrunner_plan_create` (default behavior)
+- **Authored plan**: Run gates directly from a repository-root or explicitly referenced plan
+- **Profile fallback**: Continue using a plan created via `mcp_lexrunner_plan_create`
 - **External orchestration**: Run gates on programmatically-created or externally-managed plan files
 - **Parallel workflows**: Execute gates on multiple independent plans in parallel merge-weave operations
 
@@ -493,14 +547,29 @@ Applies merge operations with environment-based gating.
 
 **Parameters:**
 
+- `planFile` (string, optional): Explicit path to an authored plan, using the same fallback precedence as gate execution
 - `dryRun` (boolean, optional): Simulate merge without making changes (default: `true`)
 
 **Returns:**
 
 ```json
 {
-  "allowed": false,
-  "message": "Mutations not allowed. Set ALLOW_MUTATIONS=true or use dryRun=true."
+  "mode": "dry-run",
+  "dryRun": true,
+  "ok": true,
+  "status": "preview",
+  "totalItems": 1,
+  "levels": [["item1"]],
+  "artifactRefs": [],
+  "planArtifact": {
+    "contract": "plan-artifact-identity-v1",
+    "kind": "execution-plan",
+    "schema": "lexrunner.execution-plan",
+    "schemaVersion": "1.0.0",
+    "digest": "sha256:...",
+    "target": "main",
+    "itemCount": 1
+  }
 }
 ```
 
@@ -510,6 +579,7 @@ Applies merge operations with environment-based gating.
 {
   "name": "mcp_lexrunner_weave_apply",
   "arguments": {
+    "planFile": "plan.json",
     "dryRun": true
   }
 }
@@ -580,6 +650,7 @@ const externalGatesResult = await client.callTool("mcp_lexrunner_gate_run", {
 
 // Check merge eligibility (dry run)
 const mergeResult = await client.callTool("mcp_lexrunner_weave_apply", {
+  planFile: "/tmp/merge-batch/plan.json",
   dryRun: true,
 });
 ```

package/README.md

@@ -111,13 +111,14 @@ The checked-in package version is the single source for `lex-pr --version`.
 
 <!-- BEGIN GENERATED PACKAGE VERSION -->
 
-Current repository package version: **1.2.1**. npm availability and dist-tags are separate
+Current repository package version: **1.3.0**. npm availability and dist-tags are separate
 release evidence; inspect the registry rather than inferring publication from source metadata.
 <!-- END GENERATED PACKAGE VERSION -->
 
-See the [1.2.1 publication repair](docs/releases/1.2.1.md) and underlying
-[1.2.0 compatibility decision](docs/releases/1.2.0.md) for the package disposition, semver
-rationale, supported assisted behavior, and deferred headless guarantees.
+See the [1.3.0 release notes](docs/releases/1.3.0.md), the
+[1.2.1 publication repair](docs/releases/1.2.1.md), and the underlying
+[1.2.0 compatibility decision](docs/releases/1.2.0.md) for package disposition, semver rationale,
+supported assisted behavior, and deferred guarantees.
 
 ## Choose a surface
 
@@ -125,8 +126,13 @@ rationale, supported assisted behavior, and deferred headless guarantees.
   `weave merge-order`, and `gate run`.
 - **Agent/MCP:** use the matching canonical tools and bounded contracts in
   [`docs/AX.md`](docs/AX.md) and [`README.mcp.md`](README.mcp.md).
-- **Assisted agent work:** use `attempt prepare`, `attempt start`, worker attachment/heartbeat,
-  receipt submission, verification, and acceptance. The foreground host still owns worker launch.
+- **Assisted agent work:** run `attempt preflight` before packet construction. When it reports
+  `broker_required`, use `attempt projection status|prepare` to bind the exact committed base into
+  native WSL, then continue with `attempt prepare`, `attempt start`, worker
+  attachment/heartbeat, receipt submission, verification, and acceptance. The foreground host
+  still owns worker launch. Follow the
+  [native Windows-to-WSL projection workflow](docs/workflows/native-wsl-projection.md) for recovery
+  and cleanup.
 - **Advanced operators:** read the
   [orchestration primitives](docs/architecture/orchestration-primitives.md),
   [headless supervisor boundary](docs/architecture/headless-supervisor.md), and

package/dist/{adapters-DciX_uRh.d.ts → adapters-r7_TjMwo.d.ts}

@@ -156,6 +156,8 @@ declare function gitOperationError(ctx: GitOperationContext): AXError;
 interface PlanValidationContext {
     errors: string[];
     planPath?: string;
+    errorCount?: number;
+    errorsTruncated?: boolean;
 }
 /**
  * Create an AXError for plan validation failures

package/dist/{autopilot-APNRAJTS.js → autopilot-JXO4MZ6H.js}

@@ -16,12 +16,12 @@ import {
   hasCapability,
   parseAutopilotConfig,
   validateAutopilotConfig
-} from "./chunk-6HASN2LZ.js";
+} from "./chunk-WSJEPY7T.js";
 import "./chunk-4FFGNTAV.js";
 import "./chunk-6A4IE3TI.js";
-import "./chunk-6TB2UCBZ.js";
+import "./chunk-VAGHAQT2.js";
 import "./chunk-UHFMFO54.js";
-import "./chunk-L7YDEIPO.js";
+import "./chunk-26SCN2LJ.js";
 import "./chunk-TPVORFSN.js";
 import "./chunk-55VWJYZY.js";
 import "./chunk-AXOAVRTU.js";

package/dist/{chunk-L7YDEIPO.js → chunk-26SCN2LJ.js}

@@ -148,15 +148,23 @@ function gitOperationError(ctx) {
 }
 function planValidationError(ctx) {
   const nextActions = ["Review the plan file for schema violations"];
+  const errorCount = ctx.errorCount ?? ctx.errors.length;
   if (ctx.planPath) {
     nextActions.push(`Plan file: ${ctx.planPath}`);
   }
-  nextActions.push(`Errors: ${ctx.errors.join("; ")}`);
+  if (ctx.errors.length > 0) {
+    nextActions.push(`Errors: ${ctx.errors.join("; ")}`);
+  }
+  if (ctx.errorsTruncated) {
+    nextActions.push(
+      `Only the first ${ctx.errors.length} of ${errorCount} validation errors are included`
+    );
+  }
   return createAXError(
     ErrorCodes.PLAN_VALIDATION_FAILED,
-    `Plan validation failed with ${ctx.errors.length} error(s)`,
+    `Plan validation failed with ${errorCount} error(s)`,
     nextActions,
-    { ...ctx }
+    { ...ctx, errorCount, errorsTruncated: ctx.errorsTruncated ?? false }
   );
 }
 function toAXError(error, code = ErrorCodes.INTERNAL_ERROR, nextActions) {
@@ -503,6 +511,12 @@ var ErrorCodes = {
   PLAN_VALIDATION_FAILED: "PLAN_VALIDATION_FAILED",
   /** Plan file not found */
   PLAN_NOT_FOUND: "PLAN_NOT_FOUND",
+  /** Explicit plan reference is empty, overlong, or otherwise invalid */
+  PLAN_REFERENCE_INVALID: "PLAN_REFERENCE_INVALID",
+  /** Plan reference exists but cannot be read as a bounded regular file */
+  PLAN_UNREADABLE: "PLAN_UNREADABLE",
+  /** Plan exceeds the bounded integration artifact limits */
+  PLAN_ARTIFACT_LIMIT_EXCEEDED: "PLAN_ARTIFACT_LIMIT_EXCEEDED",
   /** Cycle detected in plan item dependencies */
   PLAN_CYCLE_DETECTED: "PLAN_CYCLE_DETECTED",
   /** Referenced dependency not found in plan */

package/dist/{chunk-6TB2UCBZ.js → chunk-VAGHAQT2.js}

@@ -2,7 +2,7 @@ import {
   AXErrorException,
   cycleDetectedError,
   unknownDependencyError
-} from "./chunk-L7YDEIPO.js";
+} from "./chunk-26SCN2LJ.js";
 import {
   METRICS,
   metrics

package/dist/{chunk-6HASN2LZ.js → chunk-WSJEPY7T.js}

@@ -8,14 +8,14 @@ import {
 import {
   MemoryMonitor,
   computeMergeOrder
-} from "./chunk-6TB2UCBZ.js";
+} from "./chunk-VAGHAQT2.js";
 import {
   canonicalJSONStringify
 } from "./chunk-UHFMFO54.js";
 import {
   securitySarifParseError,
   securityScanFailedError
-} from "./chunk-L7YDEIPO.js";
+} from "./chunk-26SCN2LJ.js";
 import {
   emitGateFrame2 as emitGateFrame
 } from "./chunk-TPVORFSN.js";
@@ -3204,7 +3204,7 @@ function runTaskkill(pid) {
 }
 
 // src/gates.ts
-async function executeGate(gate, policy, artifactDir, timeoutMs = 3e4, itemName, skipValidation = false, repoRoot, turnCostTracker) {
+async function executeGate(gate, policy, artifactDir, timeoutMs = 3e4, itemName, skipValidation = false, repoRoot, turnCostTracker, suppressStdout = false) {
   if (!skipValidation && gate.input) {
     try {
       validateGateInput(gate.name, gate.input);
@@ -3229,9 +3229,11 @@ async function executeGate(gate, policy, artifactDir, timeoutMs = 3e4, itemName,
   for (let attempt = 1; attempt <= retryConfig.maxAttempts; attempt++) {
     if (attempt > 1 && retryConfig.backoffSeconds > 0) {
       const delayMs = retryConfig.backoffSeconds * 1e3;
-      console.log(
-        `\u23F3 Retrying gate '${gate.name}' (attempt ${attempt}/${retryConfig.maxAttempts}) after ${retryConfig.backoffSeconds}s delay...`
-      );
+      if (!suppressStdout) {
+        console.log(
+          `\u23F3 Retrying gate '${gate.name}' (attempt ${attempt}/${retryConfig.maxAttempts}) after ${retryConfig.backoffSeconds}s delay...`
+        );
+      }
       await new Promise((resolve5) => setTimeout(resolve5, delayMs));
     }
     const result = await executeGateAttempt(gate, artifactDir, attempt, timeoutMs, repoRoot);
@@ -3258,7 +3260,14 @@ async function executeGate(gate, policy, artifactDir, timeoutMs = 3e4, itemName,
         console.error(formatErrorForUser(classified));
         attemptRecords.push(attemptRecord);
         if (itemName && attemptRecords.length > 1) {
-          await writeFlakeReport(itemName, gate.name, attemptRecords, totalDuration, artifactDir);
+          await writeFlakeReport(
+            itemName,
+            gate.name,
+            attemptRecords,
+            totalDuration,
+            artifactDir,
+            suppressStdout
+          );
         }
         return result;
       } else if (classified.type === "transient" /* Transient */ && attempt < retryConfig.maxAttempts) {
@@ -3274,9 +3283,18 @@ async function executeGate(gate, policy, artifactDir, timeoutMs = 3e4, itemName,
     attemptRecords.push(attemptRecord);
     if (result.status === "pass") {
       if (attempt > 1) {
-        console.log(`\u2705 Gate '${gate.name}' succeeded on attempt ${attempt}`);
+        if (!suppressStdout) {
+          console.log(`\u2705 Gate '${gate.name}' succeeded on attempt ${attempt}`);
+        }
         if (itemName) {
-          await writeFlakeReport(itemName, gate.name, attemptRecords, totalDuration, artifactDir);
+          await writeFlakeReport(
+            itemName,
+            gate.name,
+            attemptRecords,
+            totalDuration,
+            artifactDir,
+            suppressStdout
+          );
         }
       }
       return result;
@@ -3285,7 +3303,14 @@ async function executeGate(gate, policy, artifactDir, timeoutMs = 3e4, itemName,
       if (attempt > 1) {
         console.error(`\u274C Gate '${gate.name}' failed after ${attempt} attempts`);
         if (itemName) {
-          await writeFlakeReport(itemName, gate.name, attemptRecords, totalDuration, artifactDir);
+          await writeFlakeReport(
+            itemName,
+            gate.name,
+            attemptRecords,
+            totalDuration,
+            artifactDir,
+            suppressStdout
+          );
         }
       }
       return result;
@@ -3294,7 +3319,7 @@ async function executeGate(gate, policy, artifactDir, timeoutMs = 3e4, itemName,
   }
   return lastResult;
 }
-async function writeFlakeReport(itemName, gateName, attempts, totalDuration, artifactDir) {
+async function writeFlakeReport(itemName, gateName, attempts, totalDuration, artifactDir, suppressStdout = false) {
   if (attempts.length <= 1) {
     return;
   }
@@ -3316,7 +3341,9 @@ async function writeFlakeReport(itemName, gateName, attempts, totalDuration, art
   const reportPath = path9.join(flakeReportDir, `${itemName}-${gateName}.json`);
   const reportContent = canonicalJSONStringify(flakeReport);
   fs9.writeFileSync(reportPath, reportContent, "utf-8");
-  console.log(`\u{1F4CA} Flake report written: ${reportPath}`);
+  if (!suppressStdout) {
+    console.log(`\u{1F4CA} Flake report written: ${reportPath}`);
+  }
 }
 async function executeGateAttempt(gate, artifactDir, attempt, timeoutMs, repoRoot) {
   const startedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -3349,7 +3376,7 @@ async function executeGateAttempt(gate, artifactDir, attempt, timeoutMs, repoRoo
 }
 async function executeLocalGate(gate, artifactDir, attempt, startedAt, startTime, timeoutMs, repoRoot) {
   try {
-    const { getCommandValidator } = await import("./commandValidator-VHBB2H3K.js");
+    const { getCommandValidator } = await import("./commandValidator-LVEMJTZP.js");
     const validator = getCommandValidator();
     validator.validate(gate.run);
   } catch (validationError) {
@@ -3575,29 +3602,31 @@ ${violations.map((v) => `  - ${v}`).join("\n")}`;
     lastAttempt: startedAt
   };
 }
-async function emitGateExecutionFrame(gateName, itemName, result, runId) {
+async function emitGateExecutionFrame(gateName, itemName, result, runId, emitReceipt = true) {
   if (result.status === "blocked" || result.status === "skipped" || result.status === "retrying") {
     return void 0;
   }
   const passed = result.status === "pass";
   const duration = result.duration || 0;
   const outcome = passed ? "success" : "failure";
-  emitGateReceipt(
-    gateName,
-    itemName,
-    passed,
-    duration,
-    runId,
-    { log: true, json: true },
-    // Include detailed context for failure receipts
-    !passed ? {
-      error: result.stderr,
-      exitCode: result.exitCode,
-      artifacts: result.artifacts,
-      failureKind: result.failureKind,
-      descendantsReaped: result.timeoutCleanup?.descendantsReaped
-    } : void 0
-  );
+  if (emitReceipt) {
+    emitGateReceipt(
+      gateName,
+      itemName,
+      passed,
+      duration,
+      runId,
+      { log: true, json: true },
+      // Include detailed context for failure receipts
+      !passed ? {
+        error: result.stderr,
+        exitCode: result.exitCode,
+        artifacts: result.artifacts,
+        failureKind: result.failureKind,
+        descendantsReaped: result.timeoutCleanup?.descendantsReaped
+      } : void 0
+    );
+  }
   if (!runId) {
     return void 0;
   }
@@ -3622,6 +3651,9 @@ async function executeItemGates(item, policy, executionState, artifactDir, timeo
     fs9.mkdirSync(itemArtifactDir, { recursive: true });
   }
   for (const gate of item.gates) {
+    if (options?.onlyGate && gate.name !== options.onlyGate) {
+      continue;
+    }
     if (shouldBlockGate(gate, policy)) {
       const blockedResult = {
         gate: gate.name,
@@ -3652,7 +3684,13 @@ async function executeItemGates(item, policy, executionState, artifactDir, timeo
           options.baseDir
         );
       }
-      await emitGateExecutionFrame(gate.name, item.name, result2, options?.runId);
+      await emitGateExecutionFrame(
+        gate.name,
+        item.name,
+        result2,
+        options?.runId,
+        options?.emitReceipt !== false
+      );
       continue;
     }
     const result = await executeGate(
@@ -3663,7 +3701,8 @@ async function executeItemGates(item, policy, executionState, artifactDir, timeo
       item.name,
       skipValidation,
       repoRoot,
-      options?.turnCostTracker
+      options?.turnCostTracker,
+      options?.suppressStdout
     );
     results.push(result);
     executionState.updateGateResult(item.name, result);
@@ -3681,7 +3720,13 @@ async function executeItemGates(item, policy, executionState, artifactDir, timeo
       );
       await promptCounterExampleIfEnabled(result, options);
     }
-    await emitGateExecutionFrame(gate.name, item.name, result, options?.runId);
+    await emitGateExecutionFrame(
+      gate.name,
+      item.name,
+      result,
+      options?.runId,
+      options?.emitReceipt !== false
+    );
   }
   return results;
 }
@@ -3699,7 +3744,9 @@ async function executeGatesWithPolicy(plan, executionState, artifactDir, timeout
   try {
     const hostilityScore = runEnvironmentQualityCheck({ cwd: workingDir });
     const adjustment = calculateHostilityAdjustedTimeout(timeoutMs, hostilityScore);
-    logTimeoutAdjustment(adjustment, "all_gates");
+    if (!options?.suppressStdout) {
+      logTimeoutAdjustment(adjustment, "all_gates");
+    }
     effectiveTimeoutMs = adjustment.adjustedTimeoutMs;
   } catch {
   }
@@ -3717,7 +3764,9 @@ async function executeGatesWithPolicy(plan, executionState, artifactDir, timeout
   if (!fs9.existsSync(artifactDir)) {
     fs9.mkdirSync(artifactDir, { recursive: true });
   }
-  const executionOrder = buildExecutionOrder(plan);
+  const executionOrder = buildExecutionOrder(plan).filter(
+    (itemName) => !options?.onlyItem || itemName === options.onlyItem
+  );
   const maxWorkers = policy.maxWorkers;
   const pendingNodes = [...executionOrder];
   const executing = /* @__PURE__ */ new Set();