@opengsd/gsd-pi 1.5.0-dev.553dc518 → 1.5.0-dev.c4c8885f

package/dist/resources/extensions/gsd/uok/audit-toggle.js

@@ -1,7 +1,36 @@
 const AUDIT_ENV_KEY = "GSD_UOK_AUDIT_UNIFIED";
+const suppressedBasePaths = new Set();
 export function setUnifiedAuditEnabled(enabled) {
     process.env[AUDIT_ENV_KEY] = enabled ? "1" : "0";
 }
-export function isUnifiedAuditEnabled() {
-    return process.env[AUDIT_ENV_KEY] === "1";
+export function setUnifiedAuditSuppressedForBasePath(basePath, suppressed) {
+    if (suppressed) {
+        suppressedBasePaths.add(basePath);
+        return;
+    }
+    suppressedBasePaths.delete(basePath);
+}
+export function isUnifiedAuditEnabled(basePath) {
+    if (basePath && suppressedBasePaths.has(basePath))
+        return false;
+    return process.env[AUDIT_ENV_KEY] !== "0";
+}
+export function getUnifiedAuditOverride() {
+    const raw = process.env[AUDIT_ENV_KEY];
+    if (raw === "0")
+        return false;
+    if (raw === "1")
+        return true;
+    return undefined;
+}
+export function restoreUnifiedAuditOverride(override) {
+    if (override === undefined) {
+        delete process.env[AUDIT_ENV_KEY];
+        return;
+    }
+    setUnifiedAuditEnabled(override);
+}
+export function clearUnifiedAuditOverrideForTests() {
+    delete process.env[AUDIT_ENV_KEY];
+    suppressedBasePaths.clear();
 }

package/dist/resources/extensions/gsd/uok/audit.js

@@ -7,6 +7,7 @@ import { withFileLockSync } from "../file-lock.js";
 import { gsdRoot } from "../paths.js";
 import { isDbAvailable, insertAuditEvent } from "../gsd-db.js";
 import { CURRENT_UOK_CONTRACT_VERSION, validateAuditEvent } from "./contracts.js";
+import { isUnifiedAuditEnabled } from "./audit-toggle.js";
 function auditLogPath(basePath) {
     return join(gsdRoot(basePath), "audit", "events.jsonl");
 }
@@ -30,6 +31,8 @@ export function emitUokAuditEvent(basePath, event) {
     // Drop writes from a turn superseded by timeout recovery / cancellation.
     if (isStaleWrite("uok-audit"))
         return;
+    if (!isUnifiedAuditEnabled(basePath))
+        return;
     const validation = validateAuditEvent(event);
     if (!validation.ok) {
         throw new Error(`Invalid UOK audit event: ${validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);

package/dist/resources/extensions/gsd/uok/gate-runner.js

@@ -1,5 +1,6 @@
 import { insertGateRun } from "../gsd-db.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+import { isUnifiedAuditEnabled } from "./audit-toggle.js";
 const RETRY_MATRIX = {
     none: 0,
     policy: 0,
@@ -13,6 +14,25 @@ const RETRY_MATRIX = {
     "manual-attention": 0,
     unknown: 0,
 };
+function emitGateAuditIfEnabled(ctx, result) {
+    if (!isUnifiedAuditEnabled(ctx.basePath))
+        return;
+    emitUokAuditEvent(ctx.basePath, buildAuditEnvelope({
+        traceId: ctx.traceId,
+        turnId: ctx.turnId,
+        category: "gate",
+        type: "gate-run",
+        payload: {
+            gateId: result.gateId,
+            gateType: result.gateType,
+            outcome: result.outcome,
+            failureClass: result.failureClass,
+            attempt: result.attempt,
+            maxAttempts: result.maxAttempts,
+            retryable: result.retryable,
+        },
+    }));
+}
 export class UokGateRunner {
     registry = new Map();
     register(gate) {
@@ -55,21 +75,7 @@ export class UokGateRunner {
                 retryable: unknownResult.retryable,
                 evaluatedAt: unknownResult.evaluatedAt,
             });
-            emitUokAuditEvent(ctx.basePath, buildAuditEnvelope({
-                traceId: ctx.traceId,
-                turnId: ctx.turnId,
-                category: "gate",
-                type: "gate-run",
-                payload: {
-                    gateId: unknownResult.gateId,
-                    gateType: unknownResult.gateType,
-                    outcome: unknownResult.outcome,
-                    failureClass: unknownResult.failureClass,
-                    attempt: unknownResult.attempt,
-                    maxAttempts: unknownResult.maxAttempts,
-                    retryable: unknownResult.retryable,
-                },
-            }));
+            emitGateAuditIfEnabled(ctx, unknownResult);
             return unknownResult;
         }
         let attempt = 0;
@@ -125,21 +131,7 @@ export class UokGateRunner {
                 retryable: final.retryable,
                 evaluatedAt: final.evaluatedAt,
             });
-            emitUokAuditEvent(ctx.basePath, buildAuditEnvelope({
-                traceId: ctx.traceId,
-                turnId: ctx.turnId,
-                category: "gate",
-                type: "gate-run",
-                payload: {
-                    gateId: final.gateId,
-                    gateType: final.gateType,
-                    outcome: final.outcome,
-                    failureClass: final.failureClass,
-                    attempt: final.attempt,
-                    maxAttempts: final.maxAttempts,
-                    retryable: final.retryable,
-                },
-            }));
+            emitGateAuditIfEnabled(ctx, final);
             if (!retryable)
                 break;
         }

package/dist/resources/extensions/gsd/uok/gitops.js

@@ -1,5 +1,6 @@
 import { isDbAvailable, upsertTurnGitTransaction } from "../gsd-db.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+import { isUnifiedAuditEnabled } from "./audit-toggle.js";
 export function writeTurnGitTransaction(args) {
     if (!isDbAvailable())
         return;
@@ -16,21 +17,23 @@ export function writeTurnGitTransaction(args) {
         metadata: args.metadata,
         updatedAt: new Date().toISOString(),
     });
-    emitUokAuditEvent(args.basePath, buildAuditEnvelope({
-        traceId: args.traceId,
-        turnId: args.turnId,
-        category: "gitops",
-        type: `turn-git-${args.stage}`,
-        payload: {
-            unitType: args.unitType,
-            unitId: args.unitId,
-            action: args.action,
-            push: args.push,
-            status: args.status,
-            error: args.error,
-            ...(args.metadata ?? {}),
-        },
-    }));
+    if (isUnifiedAuditEnabled(args.basePath)) {
+        emitUokAuditEvent(args.basePath, buildAuditEnvelope({
+            traceId: args.traceId,
+            turnId: args.turnId,
+            category: "gitops",
+            type: `turn-git-${args.stage}`,
+            payload: {
+                unitType: args.unitType,
+                unitId: args.unitId,
+                action: args.action,
+                push: args.push,
+                status: args.status,
+                error: args.error,
+                ...(args.metadata ?? {}),
+            },
+        }));
+    }
 }
 export function writeTurnCloseoutGitRecord(basePath, record, metadata) {
     writeTurnGitTransaction({

package/dist/resources/extensions/gsd/uok/kernel.js

@@ -2,10 +2,11 @@ import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "../paths.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
-import { setUnifiedAuditEnabled } from "./audit-toggle.js";
+import { getUnifiedAuditOverride, restoreUnifiedAuditOverride, setUnifiedAuditEnabled, setUnifiedAuditSuppressedForBasePath, } from "./audit-toggle.js";
 import { resolveUokFlags } from "./flags.js";
 import { createTurnObserver } from "./loop-adapter.js";
 import { incrementLegacyTelemetry } from "../legacy-telemetry.js";
+import { logWarning } from "../workflow-logger.js";
 function parityLogPath(basePath) {
     return join(gsdRoot(basePath), "runtime", "uok-parity.jsonl");
 }
@@ -23,68 +24,141 @@ function resolveKernelPathLabel(flags) {
         return "legacy-fallback";
     return flags.enabled ? "uok-kernel" : "legacy-wrapper";
 }
-export async function runAutoLoopWithUok(args) {
-    const { ctx, pi, s, deps, runKernelLoop, runLegacyLoop } = args;
-    const prefs = deps.loadEffectiveGSDPreferences()?.preferences;
-    const flags = resolveUokFlags(prefs);
-    setUnifiedAuditEnabled(flags.auditUnified);
+function createUokKernelRunPlan(input) {
+    const flags = resolveUokFlags(input.preferences?.preferences);
     const pathLabel = resolveKernelPathLabel(flags);
-    if (pathLabel !== "uok-kernel") {
-        incrementLegacyTelemetry("legacy.uokFallbackUsed");
-    }
-    writeParityEvent(s.basePath, {
-        ts: new Date().toISOString(),
-        path: pathLabel,
+    return {
         flags,
-        phase: "enter",
-    });
-    if (flags.auditUnified) {
-        emitUokAuditEvent(s.basePath, buildAuditEnvelope({
-            traceId: `session:${String(s.autoStartTime || Date.now())}`,
+        pathLabel,
+        traceId: `session:${String(input.autoStartTime || Date.now())}`,
+        useKernel: flags.enabled,
+    };
+}
+function createKernelAuditStateController(basePath) {
+    const previousAuditOverride = getUnifiedAuditOverride();
+    return {
+        apply(enabled) {
+            setUnifiedAuditSuppressedForBasePath(basePath, !enabled);
+            setUnifiedAuditEnabled(enabled);
+        },
+        restore() {
+            restoreUnifiedAuditOverride(previousAuditOverride);
+        },
+    };
+}
+function emitKernelEnterAudit(input) {
+    if (!input.plan.flags.auditUnified)
+        return true;
+    try {
+        emitUokAuditEvent(input.basePath, buildAuditEnvelope({
+            traceId: input.plan.traceId,
             category: "orchestration",
             type: "uok-kernel-enter",
             payload: {
-                flags,
-                sessionId: ctx.sessionManager?.getSessionId?.(),
+                flags: input.plan.flags,
+                sessionId: input.sessionId,
             },
         }));
+        return true;
     }
-    const decoratedDeps = flags.enabled
-        ? {
-            ...deps,
-            uokObserver: createTurnObserver({
-                basePath: s.basePath,
-                gitAction: flags.gitopsTurnAction,
-                gitPush: flags.gitopsTurnPush,
-                enableAudit: flags.auditUnified,
-                enableGitops: flags.gitops,
-            }),
-        }
-        : deps;
+    catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        writeParityEvent(input.basePath, {
+            ts: new Date().toISOString(),
+            path: input.plan.pathLabel,
+            flags: input.plan.flags,
+            phase: "telemetry-error",
+            telemetry: "uok-kernel-enter",
+            error: errorMessage,
+        });
+        logWarning("db", `uok-kernel-enter audit emit failed (non-fatal): ${errorMessage}`);
+        return false;
+    }
+}
+function decorateLoopDepsForKernel(input) {
+    if (!input.plan.useKernel)
+        return input.deps;
+    return {
+        ...input.deps,
+        uokObserver: createTurnObserver({
+            basePath: input.basePath,
+            gitAction: input.plan.flags.gitopsTurnAction,
+            gitPush: input.plan.flags.gitopsTurnPush,
+            enableAudit: input.plan.flags.auditUnified && input.auditHealthy,
+            enableGitops: input.plan.flags.gitops,
+        }),
+    };
+}
+async function executeKernelRunPlan(input) {
+    if (input.plan.useKernel) {
+        await input.runKernelLoop(input.ctx, input.pi, input.s, input.kernelDeps);
+        return;
+    }
+    await input.runLegacyLoop(input.ctx, input.pi, input.s, input.deps);
+}
+export async function runAutoLoopWithUok(args) {
+    const { ctx, pi, s, deps, runKernelLoop, runLegacyLoop } = args;
+    const auditState = createKernelAuditStateController(s.basePath);
+    let plan = null;
     try {
-        if (flags.enabled) {
-            await runKernelLoop(ctx, pi, s, decoratedDeps);
-        }
-        else {
-            await runLegacyLoop(ctx, pi, s, deps);
+        plan = createUokKernelRunPlan({
+            preferences: deps.loadEffectiveGSDPreferences(),
+            autoStartTime: s.autoStartTime,
+        });
+        auditState.apply(plan.flags.auditUnified);
+        if (plan.pathLabel !== "uok-kernel") {
+            incrementLegacyTelemetry("legacy.uokFallbackUsed");
         }
         writeParityEvent(s.basePath, {
             ts: new Date().toISOString(),
-            path: pathLabel,
-            flags,
-            phase: "exit",
-            status: "ok",
+            path: plan.pathLabel,
+            flags: plan.flags,
+            phase: "enter",
+        });
+        const auditHealthy = emitKernelEnterAudit({
+            basePath: s.basePath,
+            plan,
+            sessionId: ctx.sessionManager?.getSessionId?.(),
+        });
+        auditState.apply(plan.flags.auditUnified && auditHealthy);
+        const kernelDeps = decorateLoopDepsForKernel({
+            deps,
+            basePath: s.basePath,
+            plan,
+            auditHealthy,
+        });
+        await executeKernelRunPlan({
+            plan,
+            ctx,
+            pi,
+            s,
+            deps,
+            kernelDeps,
+            runKernelLoop,
+            runLegacyLoop,
         });
-    }
-    catch (err) {
         writeParityEvent(s.basePath, {
             ts: new Date().toISOString(),
-            path: pathLabel,
-            flags,
+            path: plan.pathLabel,
+            flags: plan.flags,
             phase: "exit",
-            status: "error",
-            error: err instanceof Error ? err.message : String(err),
+            status: "ok",
         });
+    }
+    catch (err) {
+        if (plan) {
+            writeParityEvent(s.basePath, {
+                ts: new Date().toISOString(),
+                path: plan.pathLabel,
+                flags: plan.flags,
+                phase: "exit",
+                status: "error",
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
         throw err;
     }
+    finally {
+        auditState.restore();
+    }
 }

package/dist/resources/extensions/gsd/uok/model-policy.js

@@ -1,5 +1,6 @@
 import { computeTaskRequirements, filterToolsForProvider } from "../model-router.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+import { isUnifiedAuditEnabled } from "./audit-toggle.js";
 export function buildRequirementVector(unitType, taskMetadata) {
     if (!unitType)
         return {};
@@ -41,20 +42,22 @@ export function applyModelPolicyFilter(candidates, options) {
             reason,
         };
         decisions.push(decision);
-        emitUokAuditEvent(options.basePath, buildAuditEnvelope({
-            traceId: options.traceId,
-            turnId: options.turnId,
-            category: "model-policy",
-            type: allowed ? "model-policy-allow" : "model-policy-deny",
-            payload: {
-                modelId: model.id,
-                provider: model.provider,
-                api: model.api,
-                reason,
-                unitType: options.unitType,
-                requirements,
-            },
-        }));
+        if (isUnifiedAuditEnabled(options.basePath)) {
+            emitUokAuditEvent(options.basePath, buildAuditEnvelope({
+                traceId: options.traceId,
+                turnId: options.turnId,
+                category: "model-policy",
+                type: allowed ? "model-policy-allow" : "model-policy-deny",
+                payload: {
+                    modelId: model.id,
+                    provider: model.provider,
+                    api: model.api,
+                    reason,
+                    unitType: options.unitType,
+                    requirements,
+                },
+            }));
+        }
         if (allowed)
             eligible.push(model);
     }

package/dist/resources/extensions/gsd/workflow-event-ledger.js

@@ -66,7 +66,7 @@ export function writeWorktreeEventLog(worktreeBasePath, events) {
     atomicWriteSync(logPath, content);
 }
 function emitWorkflowEventAudit(basePath, event) {
-    if (!isUnifiedAuditEnabled())
+    if (!isUnifiedAuditEnabled(basePath))
         return;
     try {
         const normalized = normalizeWorkflowEventCommand(event.cmd) ?? "unknown";

package/dist/resources/extensions/gsd/workflow-logger.js

@@ -209,7 +209,7 @@ function _push(severity, component, message, context) {
     if (_buffer.length > MAX_BUFFER) {
         _buffer.shift();
     }
-    if (_auditBasePath && isUnifiedAuditEnabled()) {
+    if (_auditBasePath && isUnifiedAuditEnabled(_auditBasePath)) {
         try {
             emitUokAuditEvent(_auditBasePath, buildAuditEnvelope({
                 traceId: `workflow-log:${component}`,

package/dist/resources/extensions/gsd/workflow-projections.js

@@ -5,7 +5,7 @@
 // Projections are read-only views of engine state (Layer 3 of the architecture).
 import { _getAdapter, isDbAvailable, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getVerificationEvidence, } from "./gsd-db.js";
 import { atomicWriteSync } from "./atomic-write.js";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { mkdirSync, existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { logWarning } from "./workflow-logger.js";
@@ -13,7 +13,7 @@ import { isClosedStatus } from "./status-guards.js";
 import { deriveState } from "./state.js";
 import { renderPlanFromDb, renderRoadmapFromDb } from "./markdown-renderer.js";
 import { readManifest } from "./workflow-manifest.js";
-import { gsdRoot, resolveSliceFile, resolveMilestonePath, resolveSlicePath, gsdProjectionRoot } from "./paths.js";
+import { gsdRoot, resolveMilestoneFile, resolveSliceFile, resolveTaskFile, relTaskFile } from "./paths.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────
 /**
  * Strip a leading ID prefix (e.g. "M001: " or "S04: ") from a title
@@ -276,26 +276,10 @@ export function renderSummaryProjection(basePath, milestoneId, sliceId, taskId)
         return;
     const evidenceRows = getVerificationEvidence(milestoneId, sliceId, taskId);
     const content = renderSummaryContent(taskRow, sliceId, milestoneId, evidenceRows);
-    // Layout-aware: avoid creating a milestones/ directory as a side effect for
-    // flat-phase projects. If milestonesDir() sees a freshly-created milestones/
-    // dir it treats the project as legacy, breaking all subsequent path resolution.
-    const slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
-    const phaseDir = resolveMilestonePath(basePath, milestoneId);
-    let dir;
-    if (slicePath && phaseDir && slicePath !== phaseDir) {
-        // Legacy layout: slice has its own slices/SID/ subdir → tasks/ subdir
-        dir = join(slicePath, "tasks");
-    }
-    else if (phaseDir) {
-        // Flat-phase: task summaries go in the phase dir (no tasks/ subdir needed)
-        dir = phaseDir;
-    }
-    else {
-        // Fallback: legacy hardcoded path (milestone dir not on disk yet)
-        dir = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks");
-    }
-    mkdirSync(dir, { recursive: true });
-    atomicWriteSync(join(dir, `${taskId}-SUMMARY.md`), content);
+    const summaryPath = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "SUMMARY")
+        ?? join(basePath, relTaskFile(basePath, milestoneId, sliceId, taskId, "SUMMARY", getMilestone(milestoneId)?.title));
+    mkdirSync(dirname(summaryPath), { recursive: true });
+    atomicWriteSync(summaryPath, content);
 }
 // ─── STATE.md Projection ────────────────────────────────────────────────
 /**
@@ -474,7 +458,7 @@ export async function regenerateIfMissing(basePath, milestoneId, sliceId, fileTy
             filePath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN") ?? "";
             break;
         case "ROADMAP":
-            filePath = join(basePath, ".gsd", "milestones", milestoneId, `${milestoneId}-ROADMAP.md`);
+            filePath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP") ?? "";
             break;
         case "SUMMARY":
             // For SUMMARY, we regenerate all task summaries in the slice
@@ -490,8 +474,7 @@ export async function regenerateIfMissing(basePath, milestoneId, sliceId, fileTy
         const doneTasks = taskRows.filter(t => t.status === "done" || t.status === "complete");
         let regenerated = 0;
         for (const task of doneTasks) {
-            const summaryPath = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, "tasks", `${task.id}-SUMMARY.md`);
-            if (!existsSync(summaryPath)) {
+            if (!resolveTaskFile(basePath, milestoneId, sliceId, task.id, "SUMMARY")) {
                 try {
                     renderSummaryProjection(basePath, milestoneId, sliceId, task.id);
                     regenerated++;
@@ -526,7 +509,7 @@ export async function regenerateIfMissing(basePath, milestoneId, sliceId, fileTy
                 return !!(resolveSliceFile(basePath, milestoneId, sliceId, "PLAN"));
             case "ROADMAP":
                 await renderRoadmapFromDb(basePath, milestoneId);
-                return existsSync(filePath);
+                return !!resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
             case "STATE":
                 await renderStateProjection(basePath);
                 return existsSync(filePath);

package/dist/resources/extensions/gsd/workspace.js

@@ -1,26 +1,17 @@
 // gsd-pi + Workspace handle: single source of truth for path resolution per milestone
 import { dirname, join, resolve } from "node:path";
-import { buildMilestoneFileName, canonicalPhaseDirName, isLegacyMilestonesLayout, milestonesDir, resolveGsdPathContract, resolveMilestoneFile, resolveMilestonePath, normalizeRealPath, } from "./paths.js";
+import { resolveGsdPathContract, resolveMilestoneFile, resolveMilestonePath, targetMilestoneFile, normalizeRealPath, } from "./paths.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 function tryRealpath(p) {
     return normalizeRealPath(p);
 }
-function isLegacyMilestoneDirectory(dir) {
-    const parent = dirname(dir);
-    return parent.endsWith("/milestones") || parent.endsWith("\\milestones");
-}
 function scopeMilestoneDir(basePath, milestoneId) {
-    return resolveMilestonePath(basePath, milestoneId) ?? join(milestonesDir(basePath), isLegacyMilestonesLayout(basePath) ? milestoneId : canonicalPhaseDirName(milestoneId));
+    return resolveMilestonePath(basePath, milestoneId)
+        ?? dirname(targetMilestoneFile(basePath, milestoneId, "ROADMAP"));
 }
 function scopeMilestoneFile(basePath, milestoneId, suffix) {
-    const existing = resolveMilestoneFile(basePath, milestoneId, suffix);
-    if (existing)
-        return existing;
-    const dir = scopeMilestoneDir(basePath, milestoneId);
-    const filename = isLegacyMilestoneDirectory(dir)
-        ? `${milestoneId}-${suffix}.md`
-        : buildMilestoneFileName(milestoneId, suffix);
-    return join(dir, filename);
+    return resolveMilestoneFile(basePath, milestoneId, suffix)
+        ?? targetMilestoneFile(basePath, milestoneId, suffix);
 }
 /**
  * Create an immutable GsdWorkspace handle from a raw base path.

package/dist/resources/extensions/shared/gsd-browser-cli.js

@@ -48,6 +48,30 @@ function splitCommandLine(commandLine) {
         return part;
     });
 }
+/**
+ * Extra gsd-browser CLI flags to forward verbatim to the launched daemon, from
+ * GSD_BROWSER_MCP_EXTRA_ARGS. Unlike GSD_BROWSER_MCP_ARGS (a full args override),
+ * these are *appended* to the default `mcp`/`daemon start` invocation so callers
+ * keep the managed session/identity flags. Accepts a JSON array (e.g.
+ * `["--stealth"]`) or a plain, optionally-quoted command-line string
+ * (e.g. `--stealth --browser-path /usr/bin/chromium`). This is the config-level
+ * knob for environments where Chrome needs extra launch flags — e.g. containers
+ * without unprivileged user namespaces, where `--stealth` supplies Chrome's
+ * `--no-sandbox`.
+ */
+function resolveExtraGsdBrowserArgs(env) {
+    const raw = env.GSD_BROWSER_MCP_EXTRA_ARGS?.trim();
+    if (!raw)
+        return [];
+    if (raw.startsWith("[")) {
+        const parsed = parseJsonEnv(env, "GSD_BROWSER_MCP_EXTRA_ARGS");
+        if (!Array.isArray(parsed)) {
+            throw new Error("GSD_BROWSER_MCP_EXTRA_ARGS JSON must be an array of strings");
+        }
+        return parsed.map(String);
+    }
+    return splitCommandLine(raw);
+}
 function buildPathGsdBrowserVersionInvocation(platform) {
     if (platform === "win32") {
         return { command: "cmd", args: ["/d", "/s", "/c", "gsd-browser", "--version"] };
@@ -251,6 +275,10 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
         || (preferPathCli ? "gsd-browser" : undefined)
         || (bundledCliPath ? process.execPath : undefined)
         || "gsd-browser";
+    // Appended after the managed session/identity flags so they survive the
+    // daemon-start transformation (which forwards everything after `mcp`), letting
+    // callers add extra Chrome/gsd-browser launch flags via one config knob.
+    const extraArgs = resolveExtraGsdBrowserArgs(env);
     const args = Array.isArray(explicitArgs) && explicitArgs.length > 0
         ? explicitArgs.map(String)
         : [
@@ -265,6 +293,7 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
             identityKey,
             "--identity-project",
             identityProject,
+            ...extraArgs,
         ];
     const cwd = env.GSD_BROWSER_MCP_CWD?.trim() || resolvedProjectRoot;
     return {