gsd-pi 2.41.0 → 2.42.0-dev.eedc83f

package/README.md

@@ -24,35 +24,98 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.39–v2.40
-
-- **GitHub sync extension** — auto-sync milestones, slices, and tasks to GitHub Issues, PRs, and Milestones. Opt in with `github.enabled: true` in preferences. Requires `gh` CLI.
-- **Skill tool resolution** — skills are now resolved and activated automatically in dispatched prompts based on `always_use_skills`, `prefer_skills`, and `skill_rules` preferences. Skills are matched to dispatch context at build time.
-- **Health check phase 2** — `/gsd doctor` issues now surface in real time across the dashboard widget, workflow visualizer, and HTML reports with severity levels (error/warning/info).
-- **Forensics upgrade** — `/gsd forensics` is now a full-access GSD debugger with structured anomaly detection (stuck loops, cost spikes, timeouts, missing artifacts), unit traces, and LLM-guided root-cause analysis.
-- **Auto PR on milestone completion** — set `git.auto_pr: true` to automatically create a draft PR when a milestone completes. Requires `auto_push: true` and `gh` CLI.
-- **RUNTIME.md template** — declare project-level runtime context (API endpoints, env vars, deployment info) in `.gsd/RUNTIME.md`. Inlined into task execution prompts to prevent hallucination.
-- **Welcome screen** — branded startup UI showing version, active model, available tool keys, and quick-start commands.
-- **`GSD_HOME` and `GSD_PROJECT_ID` env vars** — override the global `~/.gsd` directory and per-project identity hash for CI/CD and multi-clone environments.
-- **Browser and runtime UAT types** — new `browser-executable` and `runtime-executable` UAT types control when auto-mode pauses for validation.
-- **Pipeline decomposition** — auto-loop rewritten from recursive dispatch to a linear phase pipeline (pre-dispatch → dispatch → post-unit → verification → stuck detection) for better debuggability.
-- **Sliding-window stuck detection** — replaces the simple counter with a pattern-aware sliding window, reducing false positives on legitimate retries.
-- **Data-loss recovery** — automatic detection and recovery of `.gsd/` data loss from v2.30.0–v2.38.0 migration issues, with atomic migration and rollback on failure.
-- **Model preferences in guided flow** — per-phase model selection now applies in step mode, not just auto mode.
-
-See the full [Changelog](./CHANGELOG.md) for details.
-
-### Previous highlights (v2.34–v2.38)
-
-- **Reactive task execution (ADR-004)** — graph-derived parallel task dispatch within slices
-- **Anthropic Vertex AI provider** — Claude on Google Vertex AI
-- **cmux integration** — sidebar status, progress bars, and notifications for cmux terminal multiplexer users
-- **Redesigned dashboard** — two-column layout with 4 widget modes (full → small → min → off)
-- **AGENTS.md support** — deprecated `agent-instructions.md` in favor of standard `AGENTS.md` / `CLAUDE.md`
-- **AI-powered triage** — automated issue and PR triage via Claude Haiku
-- **Auto-generated OpenRouter registry** — model registry built from OpenRouter API
-- **`/gsd changelog`** — LLM-summarized release notes for any version
-- **Search budget enforcement** — session-level cap prevents unbounded web search
+## What's New in v2.42.0
+
+### New Features
+
+- **Declarative workflow engine** — define YAML workflows that execute through auto-loop, enabling repeatable multi-step automations without code. (#2024)
+- **Unified rule registry & event journal** — centralized rule registry, event journal with query tool, and standardized tool naming convention. (#1928)
+- **PR risk checker** — CI classifies changed files by system area and surfaces risk level on pull requests. (#1930)
+- **`/gsd fast`** — toggle service tier for supported models, enabling prioritized API routing for faster responses. (#1862)
+- **Web mode CLI flags** — `--host`, `--port`, and `--allowed-origins` flags give full control over the web server bind address and CORS policy. (#1873)
+- **ADR attribution** — architecture decision records now distinguish human, agent, and collaborative authorship. (#1830)
+
+### Key Fixes
+
+- **Node v24 web boot** — resolved `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING` that prevented `gsd --web` from starting on Node v24. (#1864)
+- **Worktree health check for all ecosystems** — broadened from JS-only to 17+ ecosystems (Rust, Go, Python, Java, etc.). (#1860)
+- **Doctor roadmap atomicity** — roadmap checkbox gating now checks summary on disk, not issue detection, preventing false unchecks. (#1915)
+- **Windows path handling** — 8.3 short path resolution, backslash normalization in bash commands, PowerShell browser launch, and parenthesis escaping. (#1960, #1863, #1870, #1872)
+- **Auth token persistence** — web UI auth token survives page refreshes via sessionStorage. (#1877)
+- **German/non-English locale git errors** — git commands now force `LC_ALL=C` to prevent locale-dependent parse failures.
+- **Orphan web server process** — stale web server processes on port 3000 are now cleaned up automatically.
+
+---
+
+## What's New in v2.41.0
+
+### New Features
+
+- **Browser-based web interface** — run GSD from the browser with `gsd --web`. Full project management, real-time progress, and multi-project support via server-sent events. (#1717)
+- **Doctor: worktree lifecycle checks** — `/gsd doctor` now validates worktree health, detects orphaned worktrees, consolidates cleanup, and enhances `/worktree list` with lifecycle status. (#1814)
+- **CI: docs-only PR detection** — PRs that only change documentation skip build and test steps, with a new prompt injection scan for security. (#1699)
+- **Custom Models guide** — new documentation for adding custom providers (Ollama, vLLM, LM Studio, proxies) via `models.json`. (#1670)
+
+### Data Loss Prevention (Critical Fixes)
+
+This release includes 7 fixes preventing silent data loss in auto-mode:
+
+- **Hallucination guard** — execute-task agents that complete with zero tool calls are now rejected as hallucinated. Previously, agents could produce detailed but fabricated summaries without writing any code, wasting ~$25/milestone. (#1838)
+- **Merge anchor verification** — before deleting a milestone worktree/branch, GSD now verifies the code is actually on the integration branch. Prevents orphaning commits when squash-merge produces an empty diff. (#1829)
+- **Dirty working tree detection** — `nativeMergeSquash` now distinguishes dirty-tree rejections from content conflicts, preventing silent commit loss when synced `.gsd/` files block the merge. (#1752)
+- **Doctor cleanup safety** — the `orphaned_completed_units` check no longer auto-fixes during post-task health checks. Previously, timing races could cause the doctor to remove valid completion keys, reverting users to earlier tasks. (#1825)
+- **Root file reverse-sync** — worktree teardown now syncs root-level `.gsd/` files (PROJECT.md, REQUIREMENTS.md, completed-units.json) back to the project root. Previously these were lost on milestone closeout. (#1831)
+- **Empty merge guard** — milestone branches with unanchored code changes are preserved instead of deleted when squash-merge produces nothing to commit. (#1755)
+- **Crash-safe task closeout** — orphaned checkboxes in PLAN.md are unchecked on retry, preventing phantom task completion. (#1759)
+
+### Auto-Mode Stability
+
+- **Terminal hang fix** — `stopAuto()` now resolves pending promises, preventing the terminal from freezing permanently after stopping auto-mode. (#1818)
+- **Signal handler coverage** — SIGHUP and SIGINT now clean up lock files, not just SIGTERM. Prevents stranded locks on VS-Code crash. (#1821)
+- **Needs-discussion routing** — milestones in `needs-discussion` phase now route to the smart entry UI instead of hard-stopping, breaking the infinite loop. (#1820)
+- **Infrastructure error handling** — auto-mode stops immediately on ENOSPC, ENOMEM, and similar unrecoverable errors instead of retrying. (#1780)
+- **Dependency-aware dispatch** — slice dispatch now uses declared `depends_on` instead of positional ordering. (#1770)
+- **Queue mode depth verification** — the write gate now processes depth verification in queue mode, fixing a deadlock where CONTEXT.md writes were permanently blocked. (#1823)
+
+### Roadmap Parser Improvements
+
+- **Table format support** — roadmaps using markdown tables (`| S01 | Title | Risk | Status |`) are now parsed correctly. (#1741)
+- **Prose header fallback** — when `## Slices` contains H3 headers instead of checkboxes, the prose parser is invoked as a fallback. (#1744)
+- **Completion marker detection** — prose headers with `✓` or `(Complete)` markers are correctly identified as done. (#1816)
+- **Zero-slice stub handling** — stub roadmaps from `/gsd queue` return `pre-planning` instead of `blocked`. (#1826)
+- **Immediate roadmap fix** — roadmap checkbox and UAT stub are fixed immediately after last task instead of deferring to `complete-slice`. (#1819)
+
+### State & Git Improvements
+
+- **CONTEXT-DRAFT.md fallback** — `depends_on` is read from CONTEXT-DRAFT.md when CONTEXT.md doesn't exist, preventing draft milestones from being promoted past dependency constraints. (#1743)
+- **Unborn branch support** — `nativeBranchExists` handles repos with zero commits, preventing dispatch deadlock on new repos. (#1815)
+- **Ghost milestone detection** — empty `.gsd/milestones/` directories are skipped instead of crashing `deriveState()`. (#1817)
+- **Default branch detection** — milestone merge detects `master` vs `main` instead of hardcoding. (#1669)
+- **Milestone title extraction** — titles are pulled from CONTEXT.md headings when no ROADMAP exists. (#1729)
+
+### Windows & Platform
+
+- **Windows path handling** — 8.3 short paths, `pathToFileURL` for ESM imports, and `realpathSync.native` fixes across the test suite and verification gate. (#1804)
+- **DEP0190 fix** — `spawnSync` deprecation warning eliminated by passing commands to shell explicitly. (#1827)
+- **Web build skip on Windows** — Next.js webpack EPERM errors on system directories are handled gracefully.
+
+### Developer Experience
+
+- **@ file finder fix** — typing `@` no longer freezes the TUI. The fix adds debounce, dedup, and empty-query short-circuit. (#1832)
+- **Tool-call loop guard** — detects and breaks infinite tool-call loops within a single unit, preventing stack overflow. (#1801)
+- **Completion deferral fix** — roadmap checkbox and UAT stub are fixed at task level, closing the fragile handoff window between last task and `complete-slice`. (#1819)
+
+See the full [Changelog](./CHANGELOG.md) for all 70+ fixes in this release.
+
+### Previous highlights (v2.39–v2.40)
+
+- **GitHub sync extension** — auto-sync milestones to GitHub Issues, PRs, and Milestones
+- **Skill tool resolution** — skills auto-activate in dispatched prompts
+- **Health check phase 2** — real-time doctor issues in dashboard and visualizer
+- **Forensics upgrade** — full-access GSD debugger with anomaly detection
+- **Pipeline decomposition** — auto-loop rewritten as linear phase pipeline
+- **Sliding-window stuck detection** — pattern-aware, fewer false positives
+- **Data-loss recovery** — automatic detection and recovery from v2.30–v2.38 migration issues
 
 ---
 

package/dist/cli-web-branch.d.ts

@@ -13,6 +13,12 @@ export interface CliFlags {
     web?: boolean;
     /** Optional project path for web mode: `gsd --web <path>` or `gsd web start <path>` */
     webPath?: string;
+    /** Custom host to bind web server to: `--host 0.0.0.0` */
+    webHost?: string;
+    /** Custom port for web server: `--port 8080` */
+    webPort?: number;
+    /** Additional allowed origins for CORS: `--allowed-origins http://192.168.1.10:8080` */
+    webAllowedOrigins?: string[];
     help?: boolean;
     version?: boolean;
 }

package/dist/cli-web-branch.js

@@ -29,6 +29,20 @@ export function parseCliArgs(argv) {
                 flags.webPath = args[++i];
             }
         }
+        else if (arg === '--host' && i + 1 < args.length) {
+            flags.webHost = args[++i];
+        }
+        else if (arg === '--port' && i + 1 < args.length) {
+            const portStr = args[++i];
+            const port = parseInt(portStr, 10);
+            if (Number.isFinite(port) && port > 0 && port < 65536) {
+                flags.webPort = port;
+            }
+        }
+        else if (arg === '--allowed-origins' && i + 1 < args.length) {
+            const origins = args[++i].split(',').map(o => o.trim()).filter(Boolean);
+            flags.webAllowedOrigins = (flags.webAllowedOrigins ?? []).concat(origins);
+        }
         else if (arg === '--model' && i + 1 < args.length) {
             flags.model = args[++i];
         }
@@ -216,6 +230,9 @@ export async function runWebCliBranch(flags, deps = {}) {
         cwd: currentCwd,
         projectSessionsDir,
         agentDir,
+        host: flags.webHost,
+        port: flags.webPort,
+        allowedOrigins: flags.webAllowedOrigins,
     });
     if (!status.ok) {
         emitWebModeFailure(stderr, status);

package/dist/cli.js

@@ -14,6 +14,14 @@ import { parseCliArgs as parseWebCliArgs, runWebCliBranch, migrateLegacyFlatSess
 import { stopWebMode } from './web-mode.js';
 import { getProjectSessionsDir } from './project-sessions.js';
 import { markStartup, printStartupTimings } from './startup-timings.js';
+// ---------------------------------------------------------------------------
+// V8 compile cache — Node 22+ can cache compiled bytecode across runs,
+// eliminating repeated parse/compile overhead for unchanged modules.
+// Must be set early so dynamic imports (extensions, lazy subcommands) benefit.
+// ---------------------------------------------------------------------------
+if (parseInt(process.versions.node) >= 22) {
+    process.env.NODE_COMPILE_CACHE ??= join(agentDir, '.compile-cache');
+}
 function exitIfManagedResourcesAreNewer(currentAgentDir) {
     const currentVersion = process.env.GSD_VERSION || '0.0.0';
     const managedVersion = getNewerManagedResourceVersion(currentAgentDir, currentVersion);
@@ -461,8 +469,14 @@ const sessionManager = cliFlags._selectedSessionPath
 exitIfManagedResourcesAreNewer(agentDir);
 initResources(agentDir);
 markStartup('initResources');
+// Overlap resource loading with session manager setup — both are independent.
+// resourceLoader.reload() is the most expensive step (jiti compilation), so
+// starting it early shaves ~50-200ms off interactive startup.
 const resourceLoader = buildResourceLoader(agentDir);
-await resourceLoader.reload();
+const resourceLoadPromise = resourceLoader.reload();
+// While resources load, let session manager finish any async I/O it needs.
+// Then await the resource promise before creating the agent session.
+await resourceLoadPromise;
 markStartup('resourceLoader.reload');
 const { session, extensionsResult } = await createAgentSession({
     authStorage,

package/dist/onboarding.js

@@ -94,7 +94,8 @@ async function loadPico() {
 /** Open a URL in the system browser (best-effort, non-blocking) */
 function openBrowser(url) {
     if (process.platform === 'win32') {
-        execFile('cmd', ['/c', 'start', '', url], () => { });
+        // PowerShell's Start-Process handles URLs with '&' safely; cmd /c start does not.
+        execFile('powershell', ['-c', `Start-Process '${url.replace(/'/g, "''")}'`], () => { });
     }
     else {
         const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';

package/dist/resource-loader.js

@@ -48,14 +48,25 @@ function getBundledGsdVersion() {
     }
 }
 function writeManagedResourceManifest(agentDir) {
-    // Record root-level files currently in the bundled extensions source so that
-    // future upgrades can detect and prune any that get removed or moved.
+    // Record root-level files and subdirectory extension names currently in the
+    // bundled extensions source so that future upgrades can detect and prune any
+    // that get removed or moved.
     let installedExtensionRootFiles = [];
+    let installedExtensionDirs = [];
     try {
         if (existsSync(bundledExtensionsDir)) {
-            installedExtensionRootFiles = readdirSync(bundledExtensionsDir, { withFileTypes: true })
+            const entries = readdirSync(bundledExtensionsDir, { withFileTypes: true });
+            installedExtensionRootFiles = entries
                 .filter(e => e.isFile())
                 .map(e => e.name);
+            installedExtensionDirs = entries
+                .filter(e => e.isDirectory())
+                .filter(e => {
+                // Only track directories that are actual extensions (contain index.js or index.ts)
+                const dirPath = join(bundledExtensionsDir, e.name);
+                return existsSync(join(dirPath, 'index.js')) || existsSync(join(dirPath, 'index.ts'));
+            })
+                .map(e => e.name);
         }
     }
     catch { /* non-fatal */ }
@@ -64,6 +75,7 @@ function writeManagedResourceManifest(agentDir) {
         syncedAt: Date.now(),
         contentHash: computeResourceFingerprint(),
         installedExtensionRootFiles,
+        installedExtensionDirs,
     };
     writeFileSync(getManagedResourceManifestPath(agentDir), JSON.stringify(manifest));
 }
@@ -284,16 +296,20 @@ function pruneRemovedBundledExtensions(manifest, agentDir) {
         return;
     // Current bundled root-level files (what the new version provides)
     const currentSourceFiles = new Set();
+    // Current bundled subdirectory extensions
+    const currentSourceDirs = new Set();
     try {
         if (existsSync(bundledExtensionsDir)) {
             for (const e of readdirSync(bundledExtensionsDir, { withFileTypes: true })) {
                 if (e.isFile())
                     currentSourceFiles.add(e.name);
+                if (e.isDirectory())
+                    currentSourceDirs.add(e.name);
             }
         }
     }
     catch { /* non-fatal */ }
-    const removeIfStale = (fileName) => {
+    const removeFileIfStale = (fileName) => {
         if (currentSourceFiles.has(fileName))
             return; // still in bundle, not stale
         const stale = join(extensionsDir, fileName);
@@ -303,17 +319,33 @@ function pruneRemovedBundledExtensions(manifest, agentDir) {
         }
         catch { /* non-fatal */ }
     };
+    const removeDirIfStale = (dirName) => {
+        if (currentSourceDirs.has(dirName))
+            return; // still in bundle, not stale
+        const stale = join(extensionsDir, dirName);
+        try {
+            if (existsSync(stale))
+                rmSync(stale, { recursive: true, force: true });
+        }
+        catch { /* non-fatal */ }
+    };
     if (manifest?.installedExtensionRootFiles) {
         // Manifest-based: remove previously-installed root files that are no longer bundled
         for (const prevFile of manifest.installedExtensionRootFiles) {
-            removeIfStale(prevFile);
+            removeFileIfStale(prevFile);
+        }
+    }
+    if (manifest?.installedExtensionDirs) {
+        // Manifest-based: remove previously-installed subdirectory extensions that are no longer bundled
+        for (const prevDir of manifest.installedExtensionDirs) {
+            removeDirIfStale(prevDir);
         }
     }
     // Always remove known stale files regardless of manifest state.
     // These were installed by pre-manifest versions so they may not appear in
     // installedExtensionRootFiles even when a manifest exists.
     // env-utils.js was moved from extensions/ root → gsd/ in v2.39.x (#1634)
-    removeIfStale('env-utils.js');
+    removeFileIfStale('env-utils.js');
 }
 /**
  * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.
@@ -416,5 +448,6 @@ export function buildResourceLoader(agentDir) {
     return new DefaultResourceLoader({
         agentDir,
         additionalExtensionPaths: piExtensionPaths,
+        bundledExtensionNames: bundledKeys,
     });
 }

package/dist/resources/extensions/async-jobs/async-bash-tool.js

@@ -83,6 +83,15 @@ export function createAsyncBashTool(getManager, getCwd) {
  */
 function executeBashInBackground(command, cwd, signal, timeout) {
     return new Promise((resolve, reject) => {
+        let settled = false;
+        const safeResolve = (value) => { if (!settled) {
+            settled = true;
+            resolve(value);
+        } };
+        const safeReject = (err) => { if (!settled) {
+            settled = true;
+            reject(err);
+        } };
         const { shell, args } = getShellConfig();
         const resolvedCommand = sanitizeCommand(command);
         const child = spawn(shell, [...args, resolvedCommand], {
@@ -93,11 +102,42 @@ function executeBashInBackground(command, cwd, signal, timeout) {
         });
         let timedOut = false;
         let timeoutHandle;
+        let sigkillHandle;
+        let hardDeadlineHandle;
+        /** Grace period (ms) between SIGTERM and SIGKILL. */
+        const SIGKILL_GRACE_MS = 5_000;
+        /** Hard deadline (ms) after SIGKILL to force-resolve the promise. */
+        const HARD_DEADLINE_MS = 3_000;
         if (timeout !== undefined && timeout > 0) {
             timeoutHandle = setTimeout(() => {
                 timedOut = true;
                 if (child.pid)
                     killTree(child.pid);
+                // If the process ignores SIGTERM, escalate to SIGKILL
+                sigkillHandle = setTimeout(() => {
+                    if (child.pid) {
+                        try {
+                            process.kill(-child.pid, "SIGKILL");
+                        }
+                        catch { /* ignore */ }
+                        try {
+                            process.kill(child.pid, "SIGKILL");
+                        }
+                        catch { /* ignore */ }
+                    }
+                    // Hard deadline: if even SIGKILL doesn't trigger 'close',
+                    // force-resolve so the job doesn't hang forever (#2186).
+                    hardDeadlineHandle = setTimeout(() => {
+                        const output = Buffer.concat(chunks).toString("utf-8");
+                        safeResolve(output
+                            ? `${output}\n\nCommand timed out after ${timeout} seconds (force-killed)`
+                            : `Command timed out after ${timeout} seconds (force-killed)`);
+                    }, HARD_DEADLINE_MS);
+                    if (typeof hardDeadlineHandle === "object" && "unref" in hardDeadlineHandle)
+                        hardDeadlineHandle.unref();
+                }, SIGKILL_GRACE_MS);
+                if (typeof sigkillHandle === "object" && "unref" in sigkillHandle)
+                    sigkillHandle.unref();
             }, timeout * 1000);
         }
         const chunks = [];
@@ -139,23 +179,31 @@ function executeBashInBackground(command, cwd, signal, timeout) {
         child.on("error", (err) => {
             if (timeoutHandle)
                 clearTimeout(timeoutHandle);
+            if (sigkillHandle)
+                clearTimeout(sigkillHandle);
+            if (hardDeadlineHandle)
+                clearTimeout(hardDeadlineHandle);
             signal.removeEventListener("abort", onAbort);
-            reject(err);
+            safeReject(err);
         });
         child.on("close", (code) => {
             if (timeoutHandle)
                 clearTimeout(timeoutHandle);
+            if (sigkillHandle)
+                clearTimeout(sigkillHandle);
+            if (hardDeadlineHandle)
+                clearTimeout(hardDeadlineHandle);
             signal.removeEventListener("abort", onAbort);
             if (spillStream)
                 spillStream.end();
             if (signal.aborted) {
                 const output = Buffer.concat(chunks).toString("utf-8");
-                resolve(output ? `${output}\n\nCommand aborted` : "Command aborted");
+                safeResolve(output ? `${output}\n\nCommand aborted` : "Command aborted");
                 return;
             }
             if (timedOut) {
                 const output = Buffer.concat(chunks).toString("utf-8");
-                resolve(output ? `${output}\n\nCommand timed out after ${timeout} seconds` : `Command timed out after ${timeout} seconds`);
+                safeResolve(output ? `${output}\n\nCommand timed out after ${timeout} seconds` : `Command timed out after ${timeout} seconds`);
                 return;
             }
             const fullOutput = Buffer.concat(chunks).toString("utf-8");
@@ -176,7 +224,7 @@ function executeBashInBackground(command, cwd, signal, timeout) {
             if (code !== 0 && code !== null) {
                 text += `\n\nCommand exited with code ${code}`;
             }
-            resolve(text);
+            safeResolve(text);
         });
     });
 }

package/dist/resources/extensions/gsd/auto/loop.js

@@ -6,11 +6,13 @@
  *
  * Imports from: auto/types, auto/resolve, auto/phases
  */
+import { randomUUID } from "node:crypto";
 import { MAX_LOOP_ITERATIONS, } from "./types.js";
 import { _clearCurrentResolve } from "./resolve.js";
 import { runPreDispatch, runDispatch, runGuards, runUnitPhase, runFinalize, } from "./phases.js";
 import { debugLog } from "../debug-logger.js";
 import { isInfrastructureError } from "./infra-errors.js";
+import { resolveEngine } from "../engine-resolver.js";
 /**
  * Main auto-mode execution loop. Iterates: derive → dispatch → guards →
  * runUnit → finalize → repeat. Exits when s.active becomes false or a
@@ -27,6 +29,10 @@ export async function autoLoop(ctx, pi, s, deps) {
     while (s.active) {
         iteration++;
         debugLog("autoLoop", { phase: "loop-top", iteration });
+        // ── Journal: per-iteration flow grouping ──
+        const flowId = randomUUID();
+        let seqCounter = 0;
+        const nextSeq = () => ++seqCounter;
         if (iteration > MAX_LOOP_ITERATIONS) {
             debugLog("autoLoop", {
                 phase: "exit",
@@ -53,6 +59,7 @@ export async function autoLoop(ctx, pi, s, deps) {
                     unitType: sidecarItem.unitType,
                     unitId: sidecarItem.unitId,
                 });
+                deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "sidecar-dequeue", data: { kind: sidecarItem.kind, unitType: sidecarItem.unitType, unitId: sidecarItem.unitId } });
             }
             const sessionLockBase = deps.lockBase();
             if (sessionLockBase) {
@@ -73,8 +80,88 @@ export async function autoLoop(ctx, pi, s, deps) {
                     break;
                 }
             }
-            const ic = { ctx, pi, s, deps, prefs, iteration };
+            const ic = { ctx, pi, s, deps, prefs, iteration, flowId, nextSeq };
+            deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-start", data: { iteration } });
             let iterData;
+            // ── Custom engine path ──────────────────────────────────────────────
+            // When activeEngineId is a non-dev value, bypass runPreDispatch and
+            // runDispatch entirely — the custom engine drives its own state via
+            // GRAPH.yaml. Shares runGuards and runUnitPhase with the dev path.
+            // After unit execution, verifies then reconciles via the engine layer.
+            //
+            // GSD_ENGINE_BYPASS=1 skips the engine layer entirely — falls through
+            // to the dev path below.
+            if (s.activeEngineId != null && s.activeEngineId !== "dev" && !sidecarItem && process.env.GSD_ENGINE_BYPASS !== "1") {
+                debugLog("autoLoop", { phase: "custom-engine-derive", iteration, engineId: s.activeEngineId });
+                const { engine, policy } = resolveEngine({
+                    activeEngineId: s.activeEngineId,
+                    activeRunDir: s.activeRunDir,
+                });
+                const engineState = await engine.deriveState(s.basePath);
+                if (engineState.isComplete) {
+                    await deps.stopAuto(ctx, pi, "Workflow complete");
+                    break;
+                }
+                debugLog("autoLoop", { phase: "custom-engine-dispatch", iteration });
+                const dispatch = await engine.resolveDispatch(engineState, { basePath: s.basePath });
+                if (dispatch.action === "stop") {
+                    await deps.stopAuto(ctx, pi, dispatch.reason ?? "Engine stopped");
+                    break;
+                }
+                if (dispatch.action === "skip") {
+                    continue;
+                }
+                // dispatch.action === "dispatch"
+                const step = dispatch.step;
+                const gsdState = await deps.deriveState(s.basePath);
+                iterData = {
+                    unitType: step.unitType,
+                    unitId: step.unitId,
+                    prompt: step.prompt,
+                    finalPrompt: step.prompt,
+                    pauseAfterUatDispatch: false,
+                    observabilityIssues: [],
+                    state: gsdState,
+                    mid: s.currentMilestoneId ?? "workflow",
+                    midTitle: "Workflow",
+                    isRetry: false,
+                    previousTier: undefined,
+                };
+                // ── Progress widget (mirrors dev path in runDispatch) ──
+                deps.updateProgressWidget(ctx, iterData.unitType, iterData.unitId, iterData.state);
+                // ── Guards (shared with dev path) ──
+                const guardsResult = await runGuards(ic, s.currentMilestoneId ?? "workflow");
+                if (guardsResult.action === "break")
+                    break;
+                // ── Unit execution (shared with dev path) ──
+                const unitPhaseResult = await runUnitPhase(ic, iterData, loopState);
+                if (unitPhaseResult.action === "break")
+                    break;
+                // ── Verify first, then reconcile (only mark complete on pass) ──
+                debugLog("autoLoop", { phase: "custom-engine-verify", iteration, unitId: iterData.unitId });
+                const verifyResult = await policy.verify(iterData.unitType, iterData.unitId, { basePath: s.basePath });
+                if (verifyResult === "pause") {
+                    await deps.pauseAuto(ctx, pi);
+                    break;
+                }
+                if (verifyResult === "retry") {
+                    debugLog("autoLoop", { phase: "custom-engine-verify-retry", iteration, unitId: iterData.unitId });
+                    continue;
+                }
+                // Verification passed — mark step complete
+                debugLog("autoLoop", { phase: "custom-engine-reconcile", iteration, unitId: iterData.unitId });
+                await engine.reconcile(engineState, {
+                    unitType: iterData.unitType,
+                    unitId: iterData.unitId,
+                    startedAt: s.currentUnit?.startedAt ?? Date.now(),
+                    finishedAt: Date.now(),
+                });
+                deps.clearUnitTimeout();
+                consecutiveErrors = 0;
+                deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration } });
+                debugLog("autoLoop", { phase: "iteration-complete", iteration });
+                continue;
+            }
             if (!sidecarItem) {
                 // ── Phase 1: Pre-dispatch ─────────────────────────────────────────
                 const preDispatchResult = await runPreDispatch(ic, loopState);
@@ -121,6 +208,7 @@ export async function autoLoop(ctx, pi, s, deps) {
             if (finalizeResult.action === "continue")
                 continue;
             consecutiveErrors = 0; // Iteration completed successfully
+            deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration } });
             debugLog("autoLoop", { phase: "iteration-complete", iteration });
         }
         catch (loopErr) {