gsd-pi 2.74.0 → 2.75.0-dev.2203010a0

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

@@ -17,6 +17,8 @@ import { gsdRoot } from "./paths.js";
 import { getAndClearSkills } from "./skill-telemetry.js";
 import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 import { parseUnitId } from "./unit-id.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
+import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
 // Re-export from shared — import directly from format-utils to avoid pulling
 // in the full barrel (mod.js → ui.js → @gsd/pi-tui) which breaks when loaded
 // outside jiti's alias resolution (e.g. dynamic import in auto-loop reports).
@@ -31,6 +33,7 @@ export function classifyUnitPhase(unitType) {
             return "discussion";
         case "plan-milestone":
         case "plan-slice":
+        case "refine-slice":
             return "planning";
         case "execute-task":
             return "execution";
@@ -152,6 +155,23 @@ export function snapshotUnitMetrics(ctx, unitType, unitId, startedAt, model, opt
         ledger.units.push(unit);
     }
     saveLedger(basePath, ledger);
+    if (isUnifiedAuditEnabled()) {
+        emitUokAuditEvent(basePath, buildAuditEnvelope({
+            traceId: opts?.traceId ?? `metrics:${unitType}:${unitId}`,
+            turnId: opts?.turnId,
+            causedBy: opts?.causedBy,
+            category: "metrics",
+            type: "unit-metrics-snapshot",
+            payload: {
+                unitType,
+                unitId,
+                model,
+                tokens: unit.tokens,
+                cost: unit.cost,
+                toolCalls: unit.toolCalls,
+            },
+        }));
+    }
     return unit;
 }
 /**

package/dist/resources/extensions/gsd/milestone-validation-gates.js

@@ -10,7 +10,7 @@
  * gate registry so the definitions stay in lockstep with prompt builders,
  * dispatch rules, and state derivation. See gate-registry.ts.
  */
-import { _getAdapter } from "./gsd-db.js";
+import { isDbAvailable, upsertQualityGate } from "./gsd-db.js";
 import { getGatesForTurn } from "./gate-registry.js";
 /**
  * Insert milestone-level quality_gates records for a validation run.
@@ -24,21 +24,22 @@ import { getGatesForTurn } from "./gate-registry.js";
  * in gate-registry.ts automatically flows through here.
  */
 export function insertMilestoneValidationGates(milestoneId, sliceId, verdict, evaluatedAt) {
-    const db = _getAdapter();
-    if (!db)
+    if (!isDbAvailable())
         return;
     const gateVerdict = verdict === "pass" ? "pass" : "flag";
     const milestoneGates = getGatesForTurn("validate-milestone");
     for (const def of milestoneGates) {
-        db.prepare(`INSERT OR REPLACE INTO quality_gates
-       (milestone_id, slice_id, gate_id, scope, task_id, status, verdict, rationale, findings, evaluated_at)
-       VALUES (:mid, :sid, :gid, 'milestone', '', 'complete', :verdict, :rationale, '', :evaluated_at)`).run({
-            ":mid": milestoneId,
-            ":sid": sliceId,
-            ":gid": def.id,
-            ":verdict": gateVerdict,
-            ":rationale": `${def.promptSection} — milestone validation verdict: ${verdict}`,
-            ":evaluated_at": evaluatedAt,
+        upsertQualityGate({
+            milestoneId,
+            sliceId,
+            gateId: def.id,
+            scope: "milestone",
+            taskId: "",
+            status: "complete",
+            verdict: gateVerdict,
+            rationale: `${def.promptSection} — milestone validation verdict: ${verdict}`,
+            findings: "",
+            evaluatedAt,
         });
     }
 }

package/dist/resources/extensions/gsd/model-cost-table.js

@@ -10,7 +10,8 @@
  */
 export const BUNDLED_COST_TABLE = [
     // Anthropic
-    { id: "claude-opus-4-6", inputPer1k: 0.015, outputPer1k: 0.075, updatedAt: "2025-03-15" },
+    { id: "claude-opus-4-6", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-04-16" },
+    { id: "claude-opus-4-7", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-04-16" },
     { id: "claude-sonnet-4-6", inputPer1k: 0.003, outputPer1k: 0.015, updatedAt: "2025-03-15" },
     { id: "claude-haiku-4-5", inputPer1k: 0.0008, outputPer1k: 0.004, updatedAt: "2025-03-15" },
     { id: "claude-sonnet-4-5-20250514", inputPer1k: 0.003, outputPer1k: 0.015, updatedAt: "2025-03-15" },
@@ -41,6 +42,7 @@ export const BUNDLED_COST_TABLE = [
     { id: "gpt-5.3-codex", inputPer1k: 0.005, outputPer1k: 0.02, updatedAt: "2026-03-29" },
     { id: "gpt-5.3-codex-spark", inputPer1k: 0.0003, outputPer1k: 0.0012, updatedAt: "2026-03-29" },
     { id: "gpt-5.4", inputPer1k: 0.005, outputPer1k: 0.02, updatedAt: "2026-03-29" },
+    { id: "gpt-5.4-mini", inputPer1k: 0.00075, outputPer1k: 0.0045, updatedAt: "2026-04-18" },
     // Google
     { id: "gemini-2.0-flash", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2025-03-15" },
     { id: "gemini-flash-2.0", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2025-03-15" },

package/dist/resources/extensions/gsd/model-router.js

@@ -17,6 +17,7 @@ export const MODEL_CAPABILITY_TIER = {
     "gpt-4.1-nano": "light",
     "gpt-5-mini": "light",
     "gpt-5-nano": "light",
+    "gpt-5.4-mini": "light",
     "gpt-5.1-codex-mini": "light",
     "gpt-5.3-codex-spark": "light",
     "gemini-2.0-flash": "light",
@@ -32,6 +33,7 @@ export const MODEL_CAPABILITY_TIER = {
     "deepseek-chat": "standard",
     // Heavy-tier models (most capable)
     "claude-opus-4-6": "heavy",
+    "claude-opus-4-7": "heavy",
     "claude-3-opus-latest": "heavy",
     "gpt-4-turbo": "heavy",
     "gpt-5": "heavy",
@@ -54,7 +56,8 @@ const MODEL_COST_PER_1K_INPUT = {
     "claude-3-5-haiku-latest": 0.0008,
     "claude-sonnet-4-6": 0.003,
     "claude-sonnet-4-5-20250514": 0.003,
-    "claude-opus-4-6": 0.015,
+    "claude-opus-4-6": 0.005,
+    "claude-opus-4-7": 0.005,
     "gpt-4o-mini": 0.00015,
     "gpt-4o": 0.0025,
     "gpt-4.1": 0.002,
@@ -63,6 +66,7 @@ const MODEL_COST_PER_1K_INPUT = {
     "gpt-5": 0.01,
     "gpt-5-mini": 0.0003,
     "gpt-5-nano": 0.0001,
+    "gpt-5.4-mini": 0.00075,
     "gpt-5-pro": 0.015,
     "gpt-5.1": 0.005,
     "gpt-5.1-codex-max": 0.003,
@@ -84,6 +88,7 @@ const MODEL_COST_PER_1K_INPUT = {
 export const MODEL_CAPABILITY_PROFILES = {
     // ── Anthropic ──────────────────────────────────────────────────────────────
     "claude-opus-4-6": { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
+    "claude-opus-4-7": { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
     "claude-sonnet-4-6": { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
     "claude-sonnet-4-5-20250514": { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
     "claude-3-5-sonnet-latest": { coding: 82, debugging: 78, research: 72, reasoning: 78, speed: 62, longContext: 70, instruction: 82 },
@@ -101,6 +106,7 @@ export const MODEL_CAPABILITY_PROFILES = {
     "gpt-5": { coding: 92, debugging: 88, research: 85, reasoning: 92, speed: 40, longContext: 85, instruction: 90 },
     "gpt-5-mini": { coding: 62, debugging: 52, research: 48, reasoning: 52, speed: 88, longContext: 52, instruction: 74 },
     "gpt-5-nano": { coding: 42, debugging: 32, research: 28, reasoning: 32, speed: 95, longContext: 32, instruction: 62 },
+    "gpt-5.4-mini": { coding: 70, debugging: 60, research: 55, reasoning: 60, speed: 84, longContext: 60, instruction: 78 },
     "gpt-5-pro": { coding: 94, debugging: 90, research: 88, reasoning: 94, speed: 35, longContext: 88, instruction: 92 },
     "gpt-5.1": { coding: 93, debugging: 89, research: 86, reasoning: 93, speed: 42, longContext: 86, instruction: 91 },
     "gpt-5.1-codex-max": { coding: 90, debugging: 85, research: 70, reasoning: 85, speed: 55, longContext: 75, instruction: 85 },

package/dist/resources/extensions/gsd/native-git-bridge.js

@@ -4,7 +4,9 @@
 //
 // Both READ and WRITE operations are native — push operations remain as
 // execSync calls because git2 credential handling is too complex.
-import { execSync, execFileSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { GSDError, GSD_GIT_ERROR } from "./errors.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { getErrorMessage } from "./error-utils.js";
@@ -206,7 +208,7 @@ export function nativeIsRepo(basePath) {
         return native.gitIsRepo(basePath);
     }
     try {
-        execSync("git rev-parse --git-dir", { cwd: basePath, stdio: "pipe" });
+        execFileSync("git", ["rev-parse", "--git-dir"], { cwd: basePath, stdio: "pipe" });
         return true;
     }
     catch {
@@ -534,6 +536,136 @@ export function nativeAddAll(basePath) {
 export function nativeAddTracked(basePath) {
     gitFileExec(basePath, ["add", "-u"]);
 }
+function isDotGsdIgnored(basePath) {
+    for (const path of [".gsd", ".gsd/"]) {
+        try {
+            execFileSync("git", ["check-ignore", "-q", path], {
+                cwd: basePath,
+                stdio: "pipe",
+                env: GIT_NO_PROMPT_ENV,
+            });
+            return true;
+        }
+        catch {
+            // exit 1 means this form is not ignored; try the next variant
+        }
+    }
+    return false;
+}
+/**
+ * Determine whether the project opts out of GSD-managed `.gitignore` via
+ * `git.manage_gitignore: false` in `.gsd/PREFERENCES.md`. Uses a minimal
+ * inline parser to avoid importing the full preferences module (which would
+ * introduce a circular dependency back into this low-level bridge).
+ *
+ * Returns true when management is disabled. Any parse failure or missing
+ * file returns false (default: GSD may manage `.gitignore`).
+ */
+function isGitignoreManagementDisabled(basePath) {
+    const prefsPath = join(basePath, ".gsd", "PREFERENCES.md");
+    if (!existsSync(prefsPath))
+        return false;
+    try {
+        const content = readFileSync(prefsPath, "utf-8");
+        // Look for `manage_gitignore: false` under a `git:` block. The preference
+        // is indented; a loose regex is sufficient since we only care about the
+        // explicit opt-out case.
+        return /^\s*manage_gitignore\s*:\s*false\s*$/m.test(content);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Self-heal path for the symlinked-`.gsd` staging failure: append `.gsd` to
+ * `.gitignore` so subsequent `git add -A` calls succeed without the symlink
+ * pathspec error. Honors the `git.manage_gitignore: false` opt-out.
+ *
+ * Returns true when `.gitignore` now contains an entry covering `.gsd`
+ * (either pre-existing or newly appended). Returns false when the opt-out
+ * is set or the write fails.
+ */
+function trySelfHealGsdGitignore(basePath) {
+    if (isGitignoreManagementDisabled(basePath))
+        return false;
+    const gitignorePath = join(basePath, ".gitignore");
+    try {
+        const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+        const lines = new Set(existing.split("\n").map(l => l.trim()).filter(l => l && !l.startsWith("#")));
+        if (lines.has(".gsd") || lines.has(".gsd/"))
+            return true;
+        const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+        const block = `${prefix}\n# ── GSD self-heal: .gsd is a symlink to external state ──\n.gsd\n`;
+        writeFileSync(gitignorePath, existing + block, "utf-8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Stage untracked files individually while skipping anything under `.gsd`.
+ * Used as a last-resort when `.gsd` is a symlink, not gitignored, and
+ * `git.manage_gitignore: false` forbids the self-heal path. Protects user
+ * work by never silently dropping new real files.
+ */
+function stageUntrackedExcludingDotGsd(basePath) {
+    // Stage tracked modifications first. `git add -u` never fails on pathspec
+    // issues because it doesn't walk untracked trees.
+    gitFileExec(basePath, ["add", "-u"]);
+    // Enumerate untracked paths via porcelain output. `?? ` prefix marks
+    // untracked files (status respects `.gitignore`).
+    const status = gitFileExec(basePath, ["status", "--porcelain=v1", "-z"], true);
+    if (!status)
+        return;
+    const untracked = [];
+    for (const entry of status.split("\0")) {
+        if (!entry)
+            continue;
+        // Porcelain format: "XY path" where XY is the 2-char status code.
+        if (entry.length < 4)
+            continue;
+        const code = entry.slice(0, 2);
+        const path = entry.slice(3);
+        if (code !== "??")
+            continue;
+        // Skip GSD runtime artifacts. Under `manage_gitignore: false` the user
+        // may not have these in `.gitignore`, so we filter explicitly to avoid
+        // committing transient state (.gsd external link, migration lock,
+        // background shell scratch dir).
+        if (path === ".gsd" || path.startsWith(".gsd/"))
+            continue;
+        if (path === ".gsd-id" || path === ".gsd.migrating")
+            continue;
+        if (path === ".bg-shell" || path.startsWith(".bg-shell/"))
+            continue;
+        untracked.push(path);
+    }
+    if (untracked.length === 0)
+        return;
+    // Stage in chunks to avoid exceeding ARG_MAX on large change sets.
+    const CHUNK = 200;
+    for (let i = 0; i < untracked.length; i += CHUNK) {
+        gitFileExec(basePath, ["add", "--", ...untracked.slice(i, i + CHUNK)]);
+    }
+}
+/**
+ * Handle `nativeAddAllWithExclusions` failing with "beyond a symbolic link"
+ * when `.gsd` is a symlink. Self-heals by adding `.gsd` to `.gitignore`, or
+ * falls back to explicit per-file staging so user work is never dropped.
+ */
+function fallbackStageWithSymlinkedDotGsd(basePath) {
+    if (isDotGsdIgnored(basePath)) {
+        gitFileExec(basePath, ["add", "-A"]);
+        return;
+    }
+    if (trySelfHealGsdGitignore(basePath)) {
+        gitFileExec(basePath, ["add", "-A"]);
+        return;
+    }
+    // `manage_gitignore: false` — protect work by staging files explicitly.
+    stageUntrackedExcludingDotGsd(basePath);
+}
 /**
  * Stage all files with pathspec exclusions (git add -A -- ':!pattern' ...).
  * Excluded paths are never hashed by git, preventing hangs on large
@@ -569,12 +701,12 @@ export function nativeAddAllWithExclusions(basePath, exclusions) {
             return;
         }
         // When .gsd is a symlink, git rejects `:!.gsd/...` pathspecs with
-        // "beyond a symbolic link". Fall back to `git add -u` which only
-        // stages changes to already-tracked files — O(tracked) not O(filesystem).
-        // Using `git add -A` here would traverse the entire working tree,
-        // hanging indefinitely on repos with large untracked data dirs. (#1977)
+        // "beyond a symbolic link". Hand off to the self-heal fallback which
+        // either adds `.gsd` to `.gitignore` and retries `git add -A`, or stages
+        // real files explicitly when `git.manage_gitignore: false` forbids the
+        // self-heal path. Either way, user work is protected from silent drops.
         if (stderr.includes("beyond a symbolic link")) {
-            gitFileExec(basePath, ["add", "-u"]);
+            fallbackStageWithSymlinkedDotGsd(basePath);
             return;
         }
         throw new GSDError(GSD_GIT_ERROR, `git add -A with exclusions failed in ${basePath}: ${getErrorMessage(err)}`);
@@ -629,7 +761,10 @@ export function nativeCommit(basePath, message, options) {
     }
     // Fallback: use git commit with stdin pipe for safe multi-line messages
     try {
-        const result = execSync(`git commit --no-verify -F -${options?.allowEmpty ? " --allow-empty" : ""}`, {
+        const args = ["commit", "--no-verify", "-F", "-"];
+        if (options?.allowEmpty)
+            args.push("--allow-empty");
+        const result = execFileSync("git", args, {
             cwd: basePath,
             stdio: ["pipe", "pipe", "pipe"],
             encoding: "utf-8",
@@ -767,7 +902,7 @@ export function nativeResetHard(basePath) {
         native.gitResetHard(basePath);
         return;
     }
-    execSync("git reset --hard HEAD", { cwd: basePath, stdio: "pipe" });
+    execFileSync("git", ["reset", "--hard", "HEAD"], { cwd: basePath, stdio: "pipe" });
 }
 /**
  * Soft reset to a target ref (git reset --soft <ref>).

package/dist/resources/extensions/gsd/notification-widget.js

@@ -1,49 +1,34 @@
-// GSD Extension — Notification Widget
-// Always-on ambient widget rendered belowEditor showing unread count and
-// the most recent notification message. Refreshes every 30 seconds.
-// Widget key: "gsd-notifications", placement: "belowEditor"
+// GSD Extension — Notification Status
+// Always-on ambient notification chip surfaced as an extension status on the
+// footer pwd row. Refreshes on store change + on a 30s timer. Hidden when
+// unread=0. Key sorts late so the chip renders to the right of other
+// extension statuses.
 import { getUnreadCount, onNotificationStoreChange } from "./notification-store.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
-// ─── Pure rendering ──���────────────────────────���─────────────────────────
-export function buildNotificationWidgetLines() {
+// Key chosen to sort after alphabetic extension keys so the chip lands on the
+// far right of the extension-status block.
+const STATUS_KEY = "zz-notifications";
+export function buildNotificationChip() {
     const unread = getUnreadCount();
     if (unread === 0)
-        return [];
-    return [`  🔔 Notifications: ${unread} unread  (${formattedShortcutPair("notifications")})`];
+        return "";
+    return `🔔 ${unread} unread (${formattedShortcutPair("notifications")})`;
+}
+// Retained for backwards compatibility with tests and the RPC fallback path
+// that still expected a line-array widget. Returns empty when no unread.
+export function buildNotificationWidgetLines() {
+    const chip = buildNotificationChip();
+    return chip ? [`  ${chip}`] : [];
 }
-// ─── Widget init ────────────────────────────────────────────────────────
 const REFRESH_INTERVAL_MS = 30_000;
-/**
- * Initialize the always-on notification widget (belowEditor).
- * Call once from session_start after the notification store is initialized.
- */
 export function initNotificationWidget(ctx) {
     if (!ctx.hasUI)
         return;
-    // String-array fallback for RPC mode
-    ctx.ui.setWidget("gsd-notifications", buildNotificationWidgetLines(), { placement: "belowEditor" });
-    // Factory-based widget for TUI mode
-    ctx.ui.setWidget("gsd-notifications", (_tui, _theme) => {
-        let cachedLines;
-        const refresh = () => {
-            cachedLines = undefined;
-            _tui.requestRender();
-        };
-        const unsubscribe = onNotificationStoreChange(refresh);
-        const refreshTimer = setInterval(refresh, REFRESH_INTERVAL_MS);
-        return {
-            render(_width) {
-                if (!cachedLines)
-                    cachedLines = buildNotificationWidgetLines();
-                return cachedLines;
-            },
-            invalidate() {
-                cachedLines = undefined;
-            },
-            dispose() {
-                unsubscribe();
-                clearInterval(refreshTimer);
-            },
-        };
-    }, { placement: "belowEditor" });
+    const push = () => {
+        const chip = buildNotificationChip();
+        ctx.ui.setStatus(STATUS_KEY, chip.length > 0 ? chip : undefined);
+    };
+    push();
+    onNotificationStoreChange(push);
+    setInterval(push, REFRESH_INTERVAL_MS).unref?.();
 }

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

@@ -3,6 +3,7 @@
 import { execFileSync } from "node:child_process";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { CmuxClient, emitOsc777Notification, resolveCmuxConfig } from "../cmux/index.js";
+import { sendRemoteNotification } from "../remote-questions/notify.js";
 /**
  * Send a native desktop notification. Non-blocking, non-fatal.
  * macOS: osascript, Linux: notify-send, Windows: skipped.
@@ -14,6 +15,9 @@ export function sendDesktopNotification(title, message, level = "info", kind = "
         title = formatNotificationTitle(projectName);
     }
     const loaded = loadEffectiveGSDPreferences()?.preferences;
+    // Remote notifications fire independently of desktop preferences.
+    // sendRemoteNotification handles "not configured" gracefully (early return).
+    void sendRemoteNotification(title, message).catch(() => { });
     if (!shouldSendDesktopNotification(kind, loaded?.notifications))
         return;
     const cmux = resolveCmuxConfig(loaded);

package/dist/resources/extensions/gsd/onboarding-state.js

@@ -0,0 +1,133 @@
+// GSD — Onboarding completion record (~/.gsd/agent/onboarding.json)
+//
+// First-class state for the onboarding wizard so re-entry, resume, and the
+// web boot probe all read the same source of truth. Replaces the implicit
+// "settings.defaultProvider exists" heuristic.
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { logWarning } from "./workflow-logger.js";
+/**
+ * Bump `FLOW_VERSION` whenever a new required step is added to ONBOARDING_STEPS.
+ * Records with an older flowVersion are treated as "needs partial re-onboarding"
+ * by isOnboardingComplete().
+ */
+export const FLOW_VERSION = 1;
+const RECORD_VERSION = 1;
+// Inline agentDir computation (mirrors src/app-paths.ts) — keep this module
+// rootDir-clean for the resources tsconfig; importing from src/ pulls files
+// outside src/resources and breaks the build.
+const AGENT_DIR = process.env.GSD_CODING_AGENT_DIR ||
+    join(process.env.GSD_HOME || join(homedir(), ".gsd"), "agent");
+const FILE = join(AGENT_DIR, "onboarding.json");
+const DEFAULT = {
+    version: RECORD_VERSION,
+    flowVersion: FLOW_VERSION,
+    completedAt: null,
+    completedSteps: [],
+    skippedSteps: [],
+    lastResumePoint: null,
+};
+export function readOnboardingRecord() {
+    if (!existsSync(FILE))
+        return { ...DEFAULT };
+    try {
+        const raw = JSON.parse(readFileSync(FILE, "utf-8"));
+        return {
+            version: typeof raw.version === "number" ? raw.version : RECORD_VERSION,
+            flowVersion: typeof raw.flowVersion === "number" ? raw.flowVersion : 0,
+            completedAt: typeof raw.completedAt === "string" ? raw.completedAt : null,
+            completedSteps: Array.isArray(raw.completedSteps) ? raw.completedSteps.filter(s => typeof s === "string") : [],
+            skippedSteps: Array.isArray(raw.skippedSteps) ? raw.skippedSteps.filter(s => typeof s === "string") : [],
+            lastResumePoint: typeof raw.lastResumePoint === "string" ? raw.lastResumePoint : null,
+        };
+    }
+    catch {
+        // Corrupt/unreadable — fall back to defaults rather than crashing onboarding flow
+        return { ...DEFAULT };
+    }
+}
+function atomicWrite(record) {
+    mkdirSync(dirname(FILE), { recursive: true });
+    const tmp = `${FILE}.tmp.${process.pid}.${Date.now()}`;
+    try {
+        writeFileSync(tmp, JSON.stringify(record, null, 2), "utf-8");
+        renameSync(tmp, FILE);
+    }
+    catch (err) {
+        // Best-effort: drop the tmp file if the rename failed (don't leak stale tmps)
+        try {
+            if (existsSync(tmp))
+                unlinkSync(tmp);
+        }
+        catch { /* swallow secondary error */ }
+        throw err;
+    }
+}
+export function writeOnboardingRecord(patch) {
+    const current = readOnboardingRecord();
+    const next = {
+        ...current,
+        ...patch,
+        version: RECORD_VERSION,
+        // flowVersion is sticky on writes unless explicitly patched
+        flowVersion: typeof patch.flowVersion === "number" ? patch.flowVersion : current.flowVersion,
+    };
+    try {
+        atomicWrite(next);
+    }
+    catch (err) {
+        // Non-fatal for the wizard, but make the failure diagnosable. The next boot
+        // will re-prompt for onboarding because the record didn't persist; the
+        // logWarning entry tells the user why.
+        logWarning("state", `Failed to persist onboarding record: ${err instanceof Error ? err.message : String(err)}`, {
+            file: FILE,
+        });
+    }
+    return next;
+}
+/**
+ * Onboarding is "complete" when there's a completedAt timestamp AND the
+ * flowVersion matches the current FLOW_VERSION. A flowVersion bump means
+ * a new required step exists and the user should re-enter to configure it.
+ */
+export function isOnboardingComplete() {
+    const r = readOnboardingRecord();
+    return r.completedAt !== null && r.flowVersion === FLOW_VERSION;
+}
+export function markStepCompleted(stepId) {
+    const r = readOnboardingRecord();
+    if (r.completedSteps.includes(stepId)) {
+        writeOnboardingRecord({ lastResumePoint: stepId });
+        return;
+    }
+    writeOnboardingRecord({
+        completedSteps: [...r.completedSteps, stepId],
+        skippedSteps: r.skippedSteps.filter(s => s !== stepId),
+        lastResumePoint: stepId,
+    });
+}
+export function markStepSkipped(stepId) {
+    const r = readOnboardingRecord();
+    if (r.skippedSteps.includes(stepId) || r.completedSteps.includes(stepId))
+        return;
+    writeOnboardingRecord({
+        skippedSteps: [...r.skippedSteps, stepId],
+        lastResumePoint: stepId,
+    });
+}
+export function markOnboardingComplete(completedSteps) {
+    writeOnboardingRecord({
+        completedAt: new Date().toISOString(),
+        flowVersion: FLOW_VERSION,
+        completedSteps,
+    });
+}
+export function resetOnboarding() {
+    writeOnboardingRecord({
+        completedAt: null,
+        completedSteps: [],
+        skippedSteps: [],
+        lastResumePoint: null,
+    });
+}

package/dist/resources/extensions/gsd/parallel-orchestrator.js

@@ -20,8 +20,13 @@ import { writeSessionStatus, readAllSessionStatuses, readSessionStatus, removeSe
 import { analyzeParallelEligibility, } from "./parallel-eligibility.js";
 import { getErrorMessage } from "./error-utils.js";
 import { logWarning } from "./workflow-logger.js";
+import { resolveUokFlags } from "./uok/flags.js";
+import { selectConflictFreeBatch } from "./uok/execution-graph.js";
 // ─── Module State ──────────────────────────────────────────────────────────
 let state = null;
+function overlapKey(a, b) {
+    return a < b ? `${a}::${b}` : `${b}::${a}`;
+}
 // ─── Persistence ──────────────────────────────────────────────────────────
 const ORCHESTRATOR_STATE_FILE = "orchestrator.json";
 const TMP_SUFFIX = ".tmp";
@@ -277,6 +282,7 @@ export async function startParallel(basePath, milestoneIds, prefs) {
         return { started: [], errors: [{ mid: "all", error: "Cannot start parallel from within a parallel worker" }] };
     }
     const config = resolveParallelConfig(prefs);
+    const uokFlags = resolveUokFlags(prefs);
     // Release any leftover state from a previous session before reassigning
     if (state) {
         for (const w of state.workers.values()) {
@@ -324,8 +330,34 @@ export async function startParallel(basePath, milestoneIds, prefs) {
     };
     const started = [];
     const errors = [];
+    let filteredMilestoneIds = milestoneIds;
+    if (uokFlags.executionGraph && milestoneIds.length > 1) {
+        try {
+            const requestedIds = new Set(milestoneIds);
+            const candidates = await analyzeParallelEligibility(basePath);
+            const overlapPairs = new Set();
+            for (const overlap of candidates.fileOverlaps) {
+                if (!requestedIds.has(overlap.mid1) || !requestedIds.has(overlap.mid2))
+                    continue;
+                overlapPairs.add(overlapKey(overlap.mid1, overlap.mid2));
+            }
+            filteredMilestoneIds = selectConflictFreeBatch({
+                orderedIds: milestoneIds,
+                maxParallel: milestoneIds.length,
+                hasConflict: (candidate, existing) => overlapPairs.has(overlapKey(candidate, existing)),
+            });
+            if (filteredMilestoneIds.length < milestoneIds.length) {
+                const skipped = milestoneIds.filter((mid) => !filteredMilestoneIds.includes(mid));
+                logWarning("parallel", `uok execution graph filtered ${skipped.length} conflicting milestone(s): ${skipped.join(", ")}`);
+            }
+        }
+        catch (e) {
+            logWarning("parallel", `uok execution graph overlap analysis failed; using legacy milestone selection: ${e.message}`);
+            filteredMilestoneIds = milestoneIds;
+        }
+    }
     // Cap to max_workers
-    const toStart = milestoneIds.slice(0, config.max_workers);
+    const toStart = filteredMilestoneIds.slice(0, config.max_workers);
     for (const mid of toStart) {
         // Check budget ceiling before each spawn
         if (isBudgetExceeded()) {