@opengsd/gsd-pi 1.1.1-dev.2034b16 → 1.1.1-dev.2de7ea0

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -78,18 +78,10 @@ function getRequiredVerificationClasses(milestoneId: string): string[] {
   return required;
 }
 
-async function collectPersistedBrowserEvidence(basePath: string, milestoneId: string): Promise<string> {
-  const chunks: string[] = [];
-  for (const slice of getMilestoneSlices(milestoneId)) {
-    const artifactPath = `milestones/${milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
-    const artifact = getArtifact(artifactPath);
-    if (artifact?.full_content) chunks.push(artifact.full_content);
-
-    const assessmentPath = resolveSliceFile(basePath, milestoneId, slice.id, "ASSESSMENT");
-    const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
-    if (assessmentContent) chunks.push(assessmentContent);
-  }
-  return chunks.join("\n\n");
+function hasRuntimeExecutableUatEvidenceText(text: string): boolean {
+  if (!/\buatType:\s*runtime-executable\b/i.test(text)) return false;
+  if (!/\bverdict:\s*PASS\b/i.test(text)) return false;
+  return /^\|\s*[^|\n]+\s*\|\s*runtime\s*\|\s*PASS\s*\|[^|\n]*\bgsd_uat_exec\b/mi.test(text);
 }
 
 async function browserEvidenceGateRequiresAttention(
@@ -114,7 +106,38 @@ async function browserEvidenceGateRequiresAttention(
   ]);
   if (!hasBrowserRequiredText(requirementText)) return false;
 
-  const persistedEvidence = await collectPersistedBrowserEvidence(basePath, params.milestoneId);
+  // Collect per-slice evidence so the runtime bypass is checked independently
+  // for each slice. Concatenating all slices before checking would allow runtime
+  // evidence from one slice to cover another slice's browser requirements.
+  const sliceEvidencePairs: Array<{ sliceRequirementText: string; evidenceText: string }> = [];
+  for (const slice of slices) {
+    const chunks: string[] = [];
+    const artifactPath = `milestones/${params.milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
+    const artifact = getArtifact(artifactPath);
+    if (artifact?.full_content) chunks.push(artifact.full_content);
+    const assessmentPath = resolveSliceFile(basePath, params.milestoneId, slice.id, "ASSESSMENT");
+    const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
+    if (assessmentContent) chunks.push(assessmentContent);
+    sliceEvidencePairs.push({
+      sliceRequirementText: compactTextParts([slice.demo, slice.goal, slice.success_criteria]),
+      evidenceText: chunks.join("\n\n"),
+    });
+  }
+  const persistedEvidence = sliceEvidencePairs.map((s) => s.evidenceText).join("\n\n");
+
+  // Runtime bypass: each slice whose own requirement text has browser-observable
+  // criteria must have its own runtime-executable UAT evidence. When no individual
+  // slice has slice-level browser requirements (e.g., they come from milestone-level
+  // fields only), fall back to checking whether any slice has runtime evidence.
+  const browserRequiringSlices = sliceEvidencePairs.filter((s) =>
+    hasBrowserRequiredText(s.sliceRequirementText),
+  );
+  const runtimeBypasses =
+    browserRequiringSlices.length > 0
+      ? browserRequiringSlices.every((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText))
+      : sliceEvidencePairs.some((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText));
+  if (runtimeBypasses) return false;
+
   const validationEvidence = compactTextParts([
     params.successCriteriaChecklist,
     params.verificationClasses,
@@ -184,14 +207,22 @@ export async function handleValidateMilestone(
   const requiredClasses = getRequiredVerificationClasses(params.milestoneId);
   if (requiredClasses.length > 0) {
     const verificationClasses = params.verificationClasses ?? "";
-    const missingClass = requiredClasses.find(
+    const missingClasses = requiredClasses.filter(
       (className) => !new RegExp(`\\b${className}\\b`, "i").test(verificationClasses),
     );
-    if (missingClass) {
+    if (missingClasses.length === 1) {
+      const missingClass = missingClasses[0];
       return {
         error: `verificationClasses must include canonical row "${missingClass}" because this milestone planned ${missingClass.toLowerCase()} verification`,
       };
     }
+    if (missingClasses.length > 1) {
+      const quotedClasses = missingClasses.map((className) => `"${className}"`).join(", ");
+      const plannedClasses = missingClasses.map((className) => className.toLowerCase()).join(", ");
+      return {
+        error: `verificationClasses must include canonical rows ${quotedClasses} because this milestone planned ${plannedClasses} verification`,
+      };
+    }
   }
 
   const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, params.milestoneId);

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -1150,6 +1150,9 @@ function validateUatChecks(basePath: string, params: UatResultSaveParams): strin
 function validateUatMode(params: UatResultSaveParams): string | null {
   const modes = new Set(params.checks.map((check) => check.mode));
   const hasHuman = params.checks.some((check) => check.result === "NEEDS-HUMAN");
+  if (params.uatType === "artifact-driven" && hasHuman && params.verdict === "PASS") {
+    return "artifact-driven UAT cannot PASS with human-only checks";
+  }
   if (
     hasHuman &&
     params.verdict === "PASS" &&
@@ -1167,12 +1170,13 @@ function validateUatMode(params: UatResultSaveParams): string | null {
   if (params.uatType === "live-runtime" && !modes.has("runtime") && !modes.has("browser")) {
     return "live-runtime UAT requires runtime or browser evidence";
   }
-  if (params.uatType === "artifact-driven" && hasHuman && params.verdict === "PASS") {
-    return "artifact-driven UAT cannot PASS with human-only checks";
-  }
   return null;
 }
 
+function quoteToolNames(toolNames: readonly string[]): string {
+  return toolNames.map((toolName) => `"${toolName}"`).join(", ");
+}
+
 function validateCanonicalPresentation(params: UatResultSaveParams): string | null {
   const aliasHints: Record<string, string> = {
     gsd_save_summary: "gsd_summary_save",
@@ -1180,10 +1184,11 @@ function validateCanonicalPresentation(params: UatResultSaveParams): string | nu
     gsd_complete_slice: "gsd_slice_complete",
     gsd_milestone_complete: "gsd_complete_milestone",
   };
+  const errors: string[] = [];
   for (const toolName of params.presentation.presentedTools) {
     const baseName = parseMcpToolName(toolName)?.tool ?? toolName;
     const canonical = aliasHints[baseName];
-    if (canonical) return `presentation tool "${toolName}" uses an alias; use canonical "${canonical}"`;
+    if (canonical) errors.push(`presentation tool "${toolName}" uses an alias; use canonical "${canonical}"`);
   }
 
   const presentedCanonical = new Set(
@@ -1191,10 +1196,13 @@ function validateCanonicalPresentation(params: UatResultSaveParams): string | nu
       canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)
     ),
   );
-  for (const requiredTool of RUN_UAT_WORKFLOW_TOOL_NAMES) {
-    if (!presentedCanonical.has(requiredTool)) {
-      return `presentation is missing required UAT tool "${requiredTool}"`;
-    }
+  const missingRequiredTools = RUN_UAT_WORKFLOW_TOOL_NAMES.filter(
+    (requiredTool) => !presentedCanonical.has(requiredTool),
+  );
+  if (missingRequiredTools.length === 1) {
+    errors.push(`presentation is missing required UAT tool "${missingRequiredTools[0]}"`);
+  } else if (missingRequiredTools.length > 1) {
+    errors.push(`presentation is missing required UAT tools ${quoteToolNames(missingRequiredTools)}`);
   }
 
   const forbiddenCanonical = new Set(
@@ -1202,24 +1210,33 @@ function validateCanonicalPresentation(params: UatResultSaveParams): string | nu
       .filter((toolName) => !toolName.includes("*"))
       .map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)),
   );
+  const forbiddenPresentedTools: string[] = [];
   for (const toolName of params.presentation.presentedTools) {
     const canonical = canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName);
     if (toolName === "mcp__gsd-workflow__*" || forbiddenCanonical.has(canonical)) {
-      return `presentation includes forbidden run-uat tool "${toolName}"`;
+      forbiddenPresentedTools.push(toolName);
     }
   }
+  if (forbiddenPresentedTools.length === 1) {
+    errors.push(`presentation includes forbidden run-uat tool "${forbiddenPresentedTools[0]}"`);
+  } else if (forbiddenPresentedTools.length > 1) {
+    errors.push(`presentation includes forbidden run-uat tools ${quoteToolNames(forbiddenPresentedTools)}`);
+  }
 
   const blockedCanonical = new Set(
     params.presentation.blockedTools.map((entry) =>
       canonicalWorkflowToolName(parseMcpToolName(entry.name)?.tool ?? entry.name)
     ),
   );
-  for (const blockedTool of ["gsd_exec", "gsd_summary_save", "gsd_save_gate_result"]) {
-    if (!blockedCanonical.has(blockedTool)) {
-      return `presentation must record "${blockedTool}" as blocked during run-uat`;
-    }
+  const missingBlockedTools = ["gsd_exec", "gsd_summary_save", "gsd_save_gate_result"].filter(
+    (blockedTool) => !blockedCanonical.has(blockedTool),
+  );
+  if (missingBlockedTools.length === 1) {
+    errors.push(`presentation must record "${missingBlockedTools[0]}" as blocked during run-uat`);
+  } else if (missingBlockedTools.length > 1) {
+    errors.push(`presentation must record ${quoteToolNames(missingBlockedTools)} as blocked during run-uat`);
   }
-  return null;
+  return errors.length > 0 ? errors.join("; ") : null;
 }
 
 function nextUatAttempt(basePath: string, milestoneId: string, sliceId: string): number {

package/src/resources/extensions/gsd/types.ts

@@ -270,6 +270,29 @@ export interface GSDActiveUnit {
 
 // ─── Post-Unit Hook Types ─────────────────────────────────────────────────
 
+export type PostUnitHookCriticality = "advisory" | "blocking";
+
+export type PostUnitHookOutcomeVerdict =
+  | "pass"
+  | "advisory"
+  | "needs-rework"
+  | "needs-remediation"
+  | "needs-attention";
+
+export type PostUnitHookOnBlockAction =
+  | "retry-unit"
+  | "retry-task"
+  | "queue-task"
+  | "queue-slice"
+  | "pause";
+
+export interface PostUnitHookOnBlockConfig {
+  /** Routing action for blocking hook findings. */
+  action: PostUnitHookOnBlockAction;
+  /** Optional artifact used by compatibility retry routing. */
+  artifact?: string;
+}
+
 export interface PostUnitHookConfig {
   /** Unique hook identifier — used in idempotency keys and logging. */
   name: string;
@@ -283,8 +306,12 @@ export interface PostUnitHookConfig {
   model?: string;
   /** Expected output file name (relative to task/slice dir). Used for idempotency — skip if exists. */
   artifact?: string;
+  /** Whether the hook is advisory or blocks unit advancement. Default advisory. */
+  criticality?: PostUnitHookCriticality;
   /** If this file is produced instead of artifact, re-run the trigger unit then re-run hooks. */
   retry_on?: string;
+  /** Optional routing for blocking findings. */
+  on_block?: PostUnitHookOnBlockConfig;
   /** Agent definition file to use. */
   agent?: string;
   /** Set false to disable without removing config. Default true. */
@@ -317,6 +344,31 @@ export interface HookDispatchResult {
   unitId: string;
 }
 
+export interface PostUnitGateBlock {
+  /** Blocking hook name. */
+  hookName: string;
+  /** The unit type that triggered the gate. */
+  triggerUnitType: string;
+  /** The unit ID that triggered the gate. */
+  triggerUnitId: string;
+  /** Gate artifact name, when configured. */
+  artifact?: string;
+  /** Absolute path to the gate artifact, when known. */
+  artifactPath?: string;
+  /** Parsed blocking verdict, when present. */
+  verdict?: PostUnitHookOutcomeVerdict | "failed";
+  /** Configured routing action that caused the pause. */
+  action: PostUnitHookOnBlockAction;
+  /** Human-readable pause reason. */
+  reason: string;
+  /** Current hook cycle count. */
+  cycle: number;
+  /** Configured max cycle count. */
+  maxCycles: number;
+  /** Optional compatibility retry artifact. */
+  retryArtifact?: string;
+}
+
 // ─── Budget & Notification Types ──────────────────────────────────────────
 
 export type BudgetEnforcementMode = "warn" | "pause" | "halt";
@@ -452,6 +504,15 @@ export interface PreDispatchResult {
 export interface PersistedHookState {
   /** Cycle counts keyed as "hookName/triggerUnitType/triggerUnitId". */
   cycleCounts: Record<string, number>;
+  /** In-flight hook, persisted so blocking gates cannot be skipped after resume. */
+  activeHook?: HookExecutionState | null;
+  /** Remaining hook queue by hook name and trigger unit. */
+  hookQueue?: Array<{
+    hookName: string;
+    triggerUnitType: string;
+    triggerUnitId: string;
+    forceRun?: boolean;
+  }>;
   /** Timestamp of last state save. */
   savedAt: string;
 }
@@ -465,6 +526,8 @@ export interface HookStatusEntry {
   enabled: boolean;
   /** What unit types it targets. */
   targets: string[];
+  /** Whether this post-unit hook is advisory or blocking. */
+  criticality?: PostUnitHookCriticality;
   /** Current cycle counts for active triggers. */
   activeCycles: Record<string, number>;
 }

package/src/resources/extensions/gsd/verdict-parser.ts

@@ -7,9 +7,60 @@
 
 import { extractUatType } from "./files.js";
 import type { UatType } from "./files.js";
+import { splitFrontmatter, parseFrontmatterMap } from "../shared/frontmatter.js";
+import { parse as parseYaml } from "yaml";
+
+function normalizeVerdict(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  let verdict = value.trim().toLowerCase();
+  if (!verdict) return undefined;
+  if (verdict === "passed") verdict = "pass";
+  return verdict;
+}
+
+function getCaseInsensitive(obj: Record<string, unknown>, key: string): unknown {
+  const lowerKey = key.toLowerCase();
+  for (const [candidate, value] of Object.entries(obj)) {
+    if (candidate.toLowerCase() === lowerKey) return value;
+  }
+  return undefined;
+}
 
 // ── Verdict extraction ──────────────────────────────────────────────────
 
+/**
+ * Extract and normalize the frontmatter `verdict` value.
+ *
+ * Supports both top-level `verdict` and the hook outcome shape
+ * `outcome.verdict`. Returns `undefined` when frontmatter is absent or has no
+ * verdict field.
+ */
+export function extractFrontmatterVerdict(content: string): string | undefined {
+  const [frontmatterLines] = splitFrontmatter(content);
+  if (!frontmatterLines) return undefined;
+
+  try {
+    const parsed = parseYaml(frontmatterLines.join("\n")) as unknown;
+    if (parsed && typeof parsed === "object") {
+      const root = parsed as Record<string, unknown>;
+      const topLevel = normalizeVerdict(getCaseInsensitive(root, "verdict"));
+      if (topLevel) return topLevel;
+      const outcome = getCaseInsensitive(root, "outcome");
+      if (outcome && typeof outcome === "object") {
+        const nested = normalizeVerdict(getCaseInsensitive(outcome as Record<string, unknown>, "verdict"));
+        if (nested) return nested;
+      }
+    }
+  } catch {
+    // Fall through to the permissive parser used by legacy frontmatter paths.
+  }
+
+  const frontmatter = parseFrontmatterMap(frontmatterLines);
+  const topLevel = normalizeVerdict(getCaseInsensitive(frontmatter, "verdict"));
+  if (topLevel) return topLevel;
+  return undefined;
+}
+
 /**
  * Extract and normalize the `verdict` value from YAML frontmatter.
  *
@@ -21,24 +72,14 @@ import type { UatType } from "./files.js";
  */
 export function extractVerdict(content: string): string | undefined {
   // Primary: YAML frontmatter verdict (canonical format)
-  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
-  if (fmMatch) {
-    const verdictMatch = fmMatch[1].match(/verdict:\s*([\w-]+)/i);
-    if (verdictMatch) {
-      let v = verdictMatch[1].toLowerCase();
-      if (v === "passed") v = "pass";
-      return v;
-    }
-    return undefined;
-  }
+  const [frontmatterLines] = splitFrontmatter(content);
+  if (frontmatterLines) return extractFrontmatterVerdict(content);
 
   // Fallback: detect verdict in markdown body (LLM manual writes, #2960).
   // Matches patterns like: **Verdict:** PASS, **Verdict:** ✅ PASS, **Verdict** needs-remediation
   const bodyMatch = content.match(/\*\*Verdict:?\*\*\s*(?:✅\s*)?(\w[\w-]*)/i);
   if (bodyMatch) {
-    let v = bodyMatch[1].toLowerCase();
-    if (v === "passed") v = "pass";
-    return v;
+    return normalizeVerdict(bodyMatch[1]);
   }
 
   return undefined;

package/src/resources/extensions/shared/gsd-browser-cli.ts

@@ -0,0 +1,172 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const GSD_BROWSER_MCP_SERVER_NAME = "gsd-browser";
+
+export interface GsdBrowserMcpLaunchConfig {
+  serverName: string;
+  command: string;
+  args: string[];
+  cwd: string;
+  env?: Record<string, string>;
+  projectRoot: string;
+  sessionName: string;
+}
+
+export interface GsdBrowserMcpLaunchOptions {
+  sessionName?: string;
+  sessionSuffix?: string;
+}
+
+function parseJsonEnv<T>(env: NodeJS.ProcessEnv, name: string): T | undefined {
+  const raw = env[name];
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    throw new Error(`Invalid JSON in ${name}`);
+  }
+}
+
+function sanitizeSessionSegment(value: string): string {
+  return value
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+}
+
+function compareSemverLocal(a: string, b: string): number {
+  const left = a.split(".").map(Number);
+  const right = b.split(".").map(Number);
+  for (let index = 0; index < Math.max(left.length, right.length); index++) {
+    const leftValue = left[index] || 0;
+    const rightValue = right[index] || 0;
+    if (leftValue > rightValue) return 1;
+    if (leftValue < rightValue) return -1;
+  }
+  return 0;
+}
+
+function parseGsdBrowserVersion(output: string): string | null {
+  return output.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
+}
+
+function resolveBundledGsdBrowserPackageVersion(): string | null {
+  try {
+    const requireFromHere = createRequire(import.meta.url);
+    const packageJsonPath = requireFromHere.resolve("@opengsd/gsd-browser/package.json");
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as { version?: unknown };
+    return typeof pkg.version === "string" ? parseGsdBrowserVersion(pkg.version) : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolvePathGsdBrowserVersion(env: NodeJS.ProcessEnv): string | null {
+  const explicit = env.GSD_BROWSER_PATH_VERSION?.trim();
+  if (explicit) return parseGsdBrowserVersion(explicit);
+
+  try {
+    return parseGsdBrowserVersion(execFileSync("gsd-browser", ["--version"], {
+      encoding: "utf-8",
+      env,
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000,
+    }));
+  } catch {
+    return null;
+  }
+}
+
+function shouldPreferPathGsdBrowser(env: NodeJS.ProcessEnv): boolean {
+  const pathVersion = resolvePathGsdBrowserVersion(env);
+  if (!pathVersion) return false;
+
+  const bundledVersion = resolveBundledGsdBrowserPackageVersion();
+  return !bundledVersion || compareSemverLocal(pathVersion, bundledVersion) > 0;
+}
+
+export function resolveBundledGsdBrowserCliPath(env: NodeJS.ProcessEnv = process.env): string | null {
+  const explicit = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+  if (explicit) return explicit;
+
+  try {
+    const requireFromHere = createRequire(import.meta.url);
+    const packageJsonPath = requireFromHere.resolve("@opengsd/gsd-browser/package.json");
+    const candidate = resolve(packageJsonPath, "..", "bin", "gsd-browser");
+    if (existsSync(candidate)) return candidate;
+  } catch {
+    // Fall through to path candidates for source/dist layouts.
+  }
+
+  const candidates = [
+    resolve(fileURLToPath(new URL("../../../../node_modules/@opengsd/gsd-browser/bin/gsd-browser", import.meta.url))),
+    resolve(fileURLToPath(new URL("../../../../node_modules/.bin/gsd-browser", import.meta.url))),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+export function buildGsdBrowserSessionName(projectRoot: string, suffix?: string): string {
+  const resolvedProjectRoot = resolve(projectRoot);
+  const base = sanitizeSessionSegment(basename(resolvedProjectRoot)) || "project";
+  const hash = createHash("sha1").update(resolvedProjectRoot).digest("hex").slice(0, 8);
+  const cleanSuffix = suffix ? sanitizeSessionSegment(suffix) : "";
+  return cleanSuffix ? `gsd-${base}-${hash}-${cleanSuffix}` : `gsd-${base}-${hash}`;
+}
+
+export function resolveGsdBrowserMcpLaunchConfig(
+  projectRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+  options: GsdBrowserMcpLaunchOptions = {},
+): GsdBrowserMcpLaunchConfig {
+  const resolvedProjectRoot = resolve(projectRoot);
+  const serverName = env.GSD_BROWSER_MCP_NAME?.trim() || GSD_BROWSER_MCP_SERVER_NAME;
+  const explicitArgs = parseJsonEnv<unknown>(env, "GSD_BROWSER_MCP_ARGS");
+  const explicitEnv = parseJsonEnv<Record<string, string>>(env, "GSD_BROWSER_MCP_ENV");
+  const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
+  const explicitCliPath = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+  const preferPathCli = !explicitCommand && !explicitCliPath && shouldPreferPathGsdBrowser(env);
+  const bundledCliPath = !explicitCommand && !explicitCliPath && !preferPathCli
+    ? resolveBundledGsdBrowserCliPath(env)
+    : null;
+  const sessionName =
+    options.sessionName?.trim() || buildGsdBrowserSessionName(resolvedProjectRoot, options.sessionSuffix);
+  const command =
+    explicitCommand
+    || explicitCliPath
+    || (preferPathCli ? "gsd-browser" : undefined)
+    || (bundledCliPath ? process.execPath : undefined)
+    || "gsd-browser";
+  const args = Array.isArray(explicitArgs) && explicitArgs.length > 0
+    ? explicitArgs.map(String)
+    : [
+        ...(bundledCliPath ? [bundledCliPath] : []),
+        "mcp",
+        "--session",
+        sessionName,
+        "--identity-scope",
+        "project",
+        "--identity-project",
+        resolvedProjectRoot,
+      ];
+  const cwd = env.GSD_BROWSER_MCP_CWD?.trim() || resolvedProjectRoot;
+
+  return {
+    serverName,
+    command,
+    args,
+    cwd,
+    ...(explicitEnv ? { env: explicitEnv } : {}),
+    projectRoot: resolvedProjectRoot,
+    sessionName,
+  };
+}