gsd-pi 2.47.0 → 2.48.0

package/dist/resources/extensions/gsd/auto-start.js

@@ -30,7 +30,7 @@ import { initRoutingHistory } from "./routing-history.js";
 import { restoreHookState, resetHookState } from "./post-unit-hooks.js";
 import { resetProactiveHealing, setLevelChangeCallback } from "./doctor-proactive.js";
 import { snapshotSkills } from "./skill-discovery.js";
-import { isDbAvailable } from "./gsd-db.js";
+import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { hideFooter } from "./auto-dashboard.js";
 import { debugLog, enableDebug, isDebugEnabled, getDebugLogPath, } from "./debug-logger.js";
 import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync, } from "node:fs";
@@ -503,6 +503,13 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 if (milestoneIds.length > 1) {
                     const issues = [];
                     for (const id of milestoneIds) {
+                        // Skip completed/parked milestones — a leftover CONTEXT-DRAFT.md
+                        // on a finished milestone is harmless residue, not an actionable warning.
+                        if (isDbAvailable()) {
+                            const ms = getMilestone(id);
+                            if (ms?.status === "complete" || ms?.status === "parked")
+                                continue;
+                        }
                         const draft = resolveMilestoneFile(base, id, "CONTEXT-DRAFT");
                         if (draft)
                             issues.push(`${id}: has CONTEXT-DRAFT.md (will pause for discussion)`);

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

@@ -197,7 +197,11 @@ export async function buildForensicReport(basePath) {
     // Extensions run from ~/.gsd/agent/extensions/gsd/ at runtime, so path-traversal
     // from import.meta.url would resolve to ~/package.json (wrong on every system).
     const gsdVersion = process.env.GSD_VERSION || "unknown";
-    // 9. Run anomaly detectors
+    // 9. Scan journal for flow timeline and structured events
+    const journalSummary = scanJournalForForensics(basePath);
+    // 10. Gather activity log directory metadata
+    const activityLogMeta = gatherActivityLogMeta(basePath, activeMilestone);
+    // 11. Run anomaly detectors
     if (metrics?.units)
         detectStuckLoops(metrics.units, anomalies);
     if (metrics?.units)
@@ -207,6 +211,7 @@ export async function buildForensicReport(basePath) {
     detectCrash(crashLock, anomalies);
     detectDoctorIssues(doctorIssues, anomalies);
     detectErrorTraces(unitTraces, anomalies);
+    detectJournalAnomalies(journalSummary, anomalies);
     return {
         gsdVersion,
         timestamp: new Date().toISOString(),
@@ -221,10 +226,14 @@ export async function buildForensicReport(basePath) {
         doctorIssues,
         anomalies,
         recentUnits,
+        journalSummary,
+        activityLogMeta,
     };
 }
 // ─── Activity Log Scanner ─────────────────────────────────────────────────────
 const ACTIVITY_FILENAME_RE = /^(\d+)-(.+?)-(.+)\.jsonl$/;
+/** Threshold below which iteration cadence is considered rapid (thrashing). */
+const RAPID_ITERATION_THRESHOLD_MS = 5000;
 function scanActivityLogs(basePath, activeMilestone) {
     const activityDirs = resolveActivityDirs(basePath, activeMilestone);
     const allTraces = [];
@@ -292,6 +301,152 @@ function resolveActivityDirs(basePath, activeMilestone) {
     dirs.push(rootActivityDir);
     return dirs;
 }
+// ─── Journal Scanner ──────────────────────────────────────────────────────────
+/**
+ * Max recent journal files to fully parse for event counts and recent events.
+ * Older files are line-counted only to avoid loading huge amounts of data.
+ */
+const MAX_JOURNAL_RECENT_FILES = 3;
+/** Max recent events to extract for the forensic report timeline. */
+const MAX_JOURNAL_RECENT_EVENTS = 20;
+/**
+ * Intelligently scan journal files for forensic summary.
+ *
+ * Journal files can be huge (thousands of JSONL entries over weeks of auto-mode).
+ * Instead of loading all entries into memory:
+ * - Only fully parse the most recent N daily files (event counts, flow tracking)
+ * - Line-count older files for approximate totals (no JSON parsing)
+ * - Extract only the last 20 events for the timeline
+ */
+function scanJournalForForensics(basePath) {
+    try {
+        const journalDir = join(gsdRoot(basePath), "journal");
+        if (!existsSync(journalDir))
+            return null;
+        const files = readdirSync(journalDir).filter(f => f.endsWith(".jsonl")).sort();
+        if (files.length === 0)
+            return null;
+        // Split into recent (fully parsed) and older (line-counted only)
+        const recentFiles = files.slice(-MAX_JOURNAL_RECENT_FILES);
+        const olderFiles = files.slice(0, -MAX_JOURNAL_RECENT_FILES);
+        // Line-count older files without parsing — avoids loading megabytes of JSON
+        let olderEntryCount = 0;
+        let oldestEntry = null;
+        for (const file of olderFiles) {
+            try {
+                const raw = readFileSync(join(journalDir, file), "utf-8");
+                const lines = raw.split("\n");
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    olderEntryCount++;
+                    // Extract only the timestamp from the first non-empty line of the oldest file
+                    if (!oldestEntry) {
+                        try {
+                            const parsed = JSON.parse(line);
+                            if (parsed.ts)
+                                oldestEntry = parsed.ts;
+                        }
+                        catch { /* skip malformed */ }
+                    }
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+        // Fully parse recent files for event counts and timeline
+        const eventCounts = {};
+        const flowIds = new Set();
+        const recentParsedEntries = [];
+        let recentEntryCount = 0;
+        for (const file of recentFiles) {
+            try {
+                const raw = readFileSync(join(journalDir, file), "utf-8");
+                for (const line of raw.split("\n")) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const entry = JSON.parse(line);
+                        recentEntryCount++;
+                        eventCounts[entry.eventType] = (eventCounts[entry.eventType] ?? 0) + 1;
+                        flowIds.add(entry.flowId);
+                        if (!oldestEntry)
+                            oldestEntry = entry.ts;
+                        // Keep a rolling window of last N events — avoids accumulating unbounded arrays
+                        recentParsedEntries.push({
+                            ts: entry.ts,
+                            flowId: entry.flowId,
+                            eventType: entry.eventType,
+                            rule: entry.rule,
+                            unitId: entry.data?.unitId,
+                        });
+                        if (recentParsedEntries.length > MAX_JOURNAL_RECENT_EVENTS) {
+                            recentParsedEntries.shift();
+                        }
+                    }
+                    catch { /* skip malformed lines */ }
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+        const totalEntries = olderEntryCount + recentEntryCount;
+        if (totalEntries === 0)
+            return null;
+        const newestEntry = recentParsedEntries.length > 0
+            ? recentParsedEntries[recentParsedEntries.length - 1].ts
+            : null;
+        return {
+            totalEntries,
+            flowCount: flowIds.size,
+            eventCounts,
+            recentEvents: recentParsedEntries,
+            oldestEntry,
+            newestEntry,
+            fileCount: files.length,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Activity Log Metadata ────────────────────────────────────────────────────
+function gatherActivityLogMeta(basePath, activeMilestone) {
+    try {
+        const activityDirs = resolveActivityDirs(basePath, activeMilestone);
+        let fileCount = 0;
+        let totalSizeBytes = 0;
+        let oldestFile = null;
+        let newestFile = null;
+        let oldestMtime = Infinity;
+        let newestMtime = 0;
+        for (const activityDir of activityDirs) {
+            if (!existsSync(activityDir))
+                continue;
+            const files = readdirSync(activityDir).filter(f => f.endsWith(".jsonl"));
+            for (const file of files) {
+                const filePath = join(activityDir, file);
+                const stat = statSync(filePath, { throwIfNoEntry: false });
+                if (!stat)
+                    continue;
+                fileCount++;
+                totalSizeBytes += stat.size;
+                if (stat.mtimeMs < oldestMtime) {
+                    oldestMtime = stat.mtimeMs;
+                    oldestFile = file;
+                }
+                if (stat.mtimeMs > newestMtime) {
+                    newestMtime = stat.mtimeMs;
+                    newestFile = file;
+                }
+            }
+        }
+        if (fileCount === 0)
+            return null;
+        return { fileCount, totalSizeBytes, oldestFile, newestFile };
+    }
+    catch {
+        return null;
+    }
+}
 // ─── Completed Keys Loader ────────────────────────────────────────────────────
 function loadCompletedKeys(basePath) {
     const file = join(gsdRoot(basePath), "completed-units.json");
@@ -423,6 +578,64 @@ function detectErrorTraces(traces, anomalies) {
         }
     }
 }
+function detectJournalAnomalies(journal, anomalies) {
+    if (!journal)
+        return;
+    // Detect stuck-detected events from the journal
+    const stuckCount = journal.eventCounts["stuck-detected"] ?? 0;
+    if (stuckCount > 0) {
+        anomalies.push({
+            type: "journal-stuck",
+            severity: stuckCount >= 3 ? "error" : "warning",
+            summary: `Journal recorded ${stuckCount} stuck-detected event(s)`,
+            details: `The auto-mode loop detected it was stuck ${stuckCount} time(s). Check journal events for flow IDs and causal chains to trace the root cause.`,
+        });
+    }
+    // Detect guard-block events (dispatch was blocked by a guard)
+    const guardCount = journal.eventCounts["guard-block"] ?? 0;
+    if (guardCount > 0) {
+        anomalies.push({
+            type: "journal-guard-block",
+            severity: guardCount >= 5 ? "warning" : "info",
+            summary: `Journal recorded ${guardCount} guard-block event(s)`,
+            details: `Dispatch was blocked by a guard condition ${guardCount} time(s). This may indicate a persistent blocking condition preventing progress.`,
+        });
+    }
+    // Detect rapid iterations (many flows in short time = likely thrashing)
+    if (journal.flowCount > 0 && journal.oldestEntry && journal.newestEntry) {
+        const oldest = new Date(journal.oldestEntry).getTime();
+        const newest = new Date(journal.newestEntry).getTime();
+        const spanMs = newest - oldest;
+        if (spanMs > 0 && journal.flowCount > 10) {
+            const avgMs = spanMs / journal.flowCount;
+            if (avgMs < RAPID_ITERATION_THRESHOLD_MS) {
+                anomalies.push({
+                    type: "journal-rapid-iterations",
+                    severity: "warning",
+                    summary: `${journal.flowCount} iterations in ${formatDuration(spanMs)} (avg ${formatDuration(avgMs)}/iteration)`,
+                    details: `Unusually rapid iteration cadence suggests the loop may be thrashing without making progress. Review recent journal events for dispatch-stop or terminal events.`,
+                });
+            }
+        }
+    }
+    // Detect worktree failures from journal events
+    const wtCreateFailed = journal.eventCounts["worktree-create-failed"] ?? 0;
+    const wtMergeFailed = journal.eventCounts["worktree-merge-failed"] ?? 0;
+    const wtFailures = wtCreateFailed + wtMergeFailed;
+    if (wtFailures > 0) {
+        const parts = [];
+        if (wtCreateFailed > 0)
+            parts.push(`${wtCreateFailed} create failure(s)`);
+        if (wtMergeFailed > 0)
+            parts.push(`${wtMergeFailed} merge failure(s)`);
+        anomalies.push({
+            type: "journal-worktree-failure",
+            severity: "warning",
+            summary: `Worktree failures: ${parts.join(", ")}`,
+            details: `Journal recorded worktree operation failures. These may indicate git state corruption or conflicting branches.`,
+        });
+    }
+}
 // ─── Report Persistence ───────────────────────────────────────────────────────
 function saveForensicReport(basePath, report, problemDescription) {
     const dir = join(gsdRoot(basePath), "forensics");
@@ -491,6 +704,48 @@ function saveForensicReport(basePath, report, problemDescription) {
         sections.push(`## Crash Lock`, ``);
         sections.push(redact(formatCrashInfo(report.crashLock)), ``);
     }
+    // Activity log metadata
+    if (report.activityLogMeta) {
+        const meta = report.activityLogMeta;
+        sections.push(`## Activity Log Metadata`, ``);
+        sections.push(`- Files: ${meta.fileCount}`);
+        sections.push(`- Total size: ${(meta.totalSizeBytes / 1024).toFixed(1)} KB`);
+        if (meta.oldestFile)
+            sections.push(`- Oldest: ${meta.oldestFile}`);
+        if (meta.newestFile)
+            sections.push(`- Newest: ${meta.newestFile}`);
+        sections.push(``);
+    }
+    // Journal summary
+    if (report.journalSummary) {
+        const js = report.journalSummary;
+        sections.push(`## Journal Summary`, ``);
+        sections.push(`- Total entries: ${js.totalEntries}`);
+        sections.push(`- Distinct flows (iterations): ${js.flowCount}`);
+        sections.push(`- Daily files: ${js.fileCount}`);
+        if (js.oldestEntry)
+            sections.push(`- Date range: ${js.oldestEntry} — ${js.newestEntry}`);
+        sections.push(``);
+        sections.push(`### Event Type Distribution`, ``);
+        sections.push(`| Event Type | Count |`);
+        sections.push(`|------------|-------|`);
+        for (const [evType, count] of Object.entries(js.eventCounts).sort((a, b) => b[1] - a[1])) {
+            sections.push(`| ${evType} | ${count} |`);
+        }
+        sections.push(``);
+        if (js.recentEvents.length > 0) {
+            sections.push(`### Recent Journal Events (last ${js.recentEvents.length})`, ``);
+            for (const ev of js.recentEvents) {
+                const parts = [`${ev.ts} [${ev.eventType}] flow=${ev.flowId.slice(0, 8)}`];
+                if (ev.rule)
+                    parts.push(`rule=${ev.rule}`);
+                if (ev.unitId)
+                    parts.push(`unit=${ev.unitId}`);
+                sections.push(`- ${parts.join(" ")}`);
+            }
+            sections.push(``);
+        }
+    }
     writeFileSync(filePath, sections.join("\n"), "utf-8");
     return filePath;
 }
@@ -565,6 +820,42 @@ function formatReportForPrompt(report) {
         sections.push(`- Total duration: ${formatDuration(totals.duration)}`);
         sections.push("");
     }
+    // Activity log metadata
+    if (report.activityLogMeta) {
+        const meta = report.activityLogMeta;
+        sections.push("### Activity Log Overview");
+        sections.push(`- Files: ${meta.fileCount}, Total size: ${(meta.totalSizeBytes / 1024).toFixed(1)} KB`);
+        if (meta.oldestFile)
+            sections.push(`- Oldest: ${meta.oldestFile}`);
+        if (meta.newestFile)
+            sections.push(`- Newest: ${meta.newestFile}`);
+        sections.push("");
+    }
+    // Journal summary — structured event timeline
+    if (report.journalSummary) {
+        const js = report.journalSummary;
+        sections.push("### Journal Summary (Iteration Event Log)");
+        sections.push(`- Total entries: ${js.totalEntries}, Distinct flows: ${js.flowCount}, Daily files: ${js.fileCount}`);
+        if (js.oldestEntry)
+            sections.push(`- Date range: ${js.oldestEntry} — ${js.newestEntry}`);
+        // Event type distribution (compact)
+        const eventPairs = Object.entries(js.eventCounts).sort((a, b) => b[1] - a[1]);
+        sections.push(`- Events: ${eventPairs.map(([t, c]) => `${t}(${c})`).join(", ")}`);
+        // Recent events timeline (for tracing what just happened)
+        if (js.recentEvents.length > 0) {
+            sections.push("");
+            sections.push(`**Recent Journal Events (last ${js.recentEvents.length}):**`);
+            for (const ev of js.recentEvents) {
+                const parts = [`${ev.ts} [${ev.eventType}] flow=${ev.flowId.slice(0, 8)}`];
+                if (ev.rule)
+                    parts.push(`rule=${ev.rule}`);
+                if (ev.unitId)
+                    parts.push(`unit=${ev.unitId}`);
+                sections.push(`- ${parts.join(" ")}`);
+            }
+        }
+        sections.push("");
+    }
     // Completed keys count
     sections.push(`### Completed Keys: ${report.completedKeys.length}`);
     sections.push(`### GSD Version: ${report.gsdVersion}`);

package/dist/resources/extensions/gsd/guided-flow.js

@@ -29,7 +29,7 @@ import { showProjectInit, offerMigration } from "./init-wizard.js";
 import { validateDirectory } from "./validate-directory.js";
 import { showConfirm } from "../shared/tui.js";
 import { debugLog } from "./debug-logger.js";
-import { findMilestoneIds, nextMilestoneId, reserveMilestoneId, getReservedMilestoneIds } from "./milestone-ids.js";
+import { findMilestoneIds, nextMilestoneId, reserveMilestoneId, getReservedMilestoneIds, clearReservedMilestoneIds } from "./milestone-ids.js";
 import { parkMilestone, discardMilestone } from "./milestone-actions.js";
 import { resolveModelWithFallbacksForUnit } from "./preferences-models.js";
 // ─── Re-exports (preserve public API for existing importers) ────────────────
@@ -296,6 +296,8 @@ function bootstrapGsdProject(basePath) {
  * and dispatches the headless discuss prompt (no Q&A rounds).
  */
 export async function showHeadlessMilestoneCreation(ctx, pi, basePath, seedContext) {
+    // Clear stale reservations from previous cancelled sessions (#2488)
+    clearReservedMilestoneIds();
     // Ensure .gsd/ is bootstrapped
     bootstrapGsdProject(basePath);
     // Generate next milestone ID
@@ -403,9 +405,14 @@ export async function showDiscuss(ctx, pi, basePath) {
     // Invalidate caches to pick up artifacts written by a just-completed discuss/plan
     invalidateAllCaches();
     const state = await deriveState(basePath);
-    // Guard: no active milestone
+    // No active milestone — check for pending milestones to discuss instead
     if (!state.activeMilestone) {
-        ctx.ui.notify("No active milestone. Run /gsd to create one first.", "warning");
+        const pendingMilestones = state.registry.filter(m => m.status === "pending");
+        if (pendingMilestones.length === 0) {
+            ctx.ui.notify("No active milestone. Run /gsd to create one first.", "warning");
+            return;
+        }
+        await showDiscussQueuedMilestone(ctx, pi, basePath, pendingMilestones);
         return;
     }
     const mid = state.activeMilestone.id;
@@ -526,6 +533,16 @@ export async function showDiscuss(ctx, pi, basePath) {
                 recommended: s.id === firstUndiscussedId,
             };
         });
+        // Offer access to queued milestones when any exist
+        const pendingMilestones = state.registry.filter(m => m.status === "pending");
+        if (pendingMilestones.length > 0) {
+            actions.push({
+                id: "discuss_queued_milestone",
+                label: "Discuss a queued milestone",
+                description: `Refine context for ${pendingMilestones.length} queued milestone(s). Does not affect current execution.`,
+                recommended: false,
+            });
+        }
         const choice = await showNextAction(ctx, {
             title: "GSD — Discuss a slice",
             summary: [
@@ -537,6 +554,10 @@ export async function showDiscuss(ctx, pi, basePath) {
         });
         if (choice === "not_yet")
             return;
+        if (choice === "discuss_queued_milestone") {
+            await showDiscussQueuedMilestone(ctx, pi, basePath, pendingMilestones);
+            return;
+        }
         const chosen = pendingSlices.find(s => s.id === choice);
         if (!chosen)
             return;
@@ -564,6 +585,63 @@ export async function showDiscuss(ctx, pi, basePath) {
         invalidateAllCaches();
     }
 }
+// ─── Queued Milestone Discussion ─────────────────────────────────────────────
+/**
+ * Show a picker of queued (pending) milestones and dispatch a discuss flow for
+ * the chosen one. Discussing a queued milestone does NOT activate it — it only
+ * refines the CONTEXT.md artifact so it is better prepared when auto-mode
+ * eventually reaches it.
+ */
+async function showDiscussQueuedMilestone(ctx, pi, basePath, pendingMilestones) {
+    const actions = pendingMilestones.map((m, i) => {
+        const hasContext = !!resolveMilestoneFile(basePath, m.id, "CONTEXT");
+        const hasDraft = !hasContext && !!resolveMilestoneFile(basePath, m.id, "CONTEXT-DRAFT");
+        const contextStatus = hasContext ? "context ✓" : hasDraft ? "draft context" : "no context yet";
+        return {
+            id: m.id,
+            label: `${m.id}: ${m.title}`,
+            description: `[queued] · ${contextStatus}`,
+            recommended: i === 0,
+        };
+    });
+    const choice = await showNextAction(ctx, {
+        title: "GSD — Discuss a queued milestone",
+        summary: [
+            "Select a queued milestone to discuss.",
+            "Discussing will update its context file. It will not be activated.",
+        ],
+        actions,
+        notYetMessage: "Run /gsd discuss when ready.",
+    });
+    if (choice === "not_yet")
+        return;
+    const chosen = pendingMilestones.find(m => m.id === choice);
+    if (!chosen)
+        return;
+    await dispatchDiscussForMilestone(ctx, pi, basePath, chosen.id, chosen.title);
+}
+/**
+ * Dispatch the guided-discuss-milestone prompt for a milestone without
+ * setting pendingAutoStart — so discussing a queued milestone does not
+ * implicitly activate it when the session ends.
+ */
+async function dispatchDiscussForMilestone(ctx, pi, basePath, mid, milestoneTitle) {
+    const draftFile = resolveMilestoneFile(basePath, mid, "CONTEXT-DRAFT");
+    const draftContent = draftFile ? await loadFile(draftFile) : null;
+    const discussMilestoneTemplates = inlineTemplate("context", "Context");
+    const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false";
+    const basePrompt = loadPrompt("guided-discuss-milestone", {
+        milestoneId: mid,
+        milestoneTitle,
+        inlinedTemplates: discussMilestoneTemplates,
+        structuredQuestionsAvailable,
+        commitInstruction: buildDocsCommitInstruction(`docs(${mid}): milestone context from discuss`),
+    });
+    const prompt = draftContent
+        ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
+        : basePrompt;
+    await dispatchWorkflow(pi, prompt, "gsd-discuss", ctx, "plan-milestone");
+}
 // ─── Smart Entry Point ────────────────────────────────────────────────────────
 /**
  * The one wizard. Reads state, shows contextual options, dispatches into the workflow doc.
@@ -693,6 +771,10 @@ async function handleMilestoneActions(ctx, pi, basePath, milestoneId, milestoneT
 }
 export async function showSmartEntry(ctx, pi, basePath, options) {
     const stepMode = options?.step;
+    // ── Clear stale milestone ID reservations from previous cancelled sessions ──
+    // Reservations only need to survive within a single /gsd interaction.
+    // Without this, each cancelled session permanently bumps the next ID. (#2488)
+    clearReservedMilestoneIds();
     // ── Directory safety check — refuse to operate in system/home dirs ───
     const dirCheck = validateDirectory(basePath);
     if (dirCheck.severity === "blocked") {

package/dist/resources/extensions/gsd/prompts/forensics.md

@@ -36,6 +36,8 @@ GSD extension source code is at: `{{gsdSourceDir}}`
 ├── doctor-history.jsonl         — doctor check history
 ├── activity/                    — session activity logs (JSONL per unit)
 │   └── {seq}-{unitType}-{unitId}.jsonl
+├── journal/                     — structured event journal (JSONL per day)
+│   └── YYYY-MM-DD.jsonl
 ├── runtime/
 │   ├── paused-session.json      — serialized session when auto pauses
 │   └── headless-context.md      — headless resume context
@@ -60,6 +62,32 @@ GSD extension source code is at: `{{gsdSourceDir}}`
 - `usage` field on assistant messages: `input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`, `cost`
 - **To trace a failure**: find the last activity log, search for `isError: true` tool results, then read the agent's reasoning text preceding that error
 
+### Journal Format (`.gsd/journal/`)
+
+The journal is a structured event log for auto-mode iterations. Each daily file contains JSONL entries:
+
+```
+{ ts: "ISO-8601", flowId: "UUID", seq: 0, eventType: "iteration-start", rule?: "rule-name", causedBy?: { flowId, seq }, data?: { unitId, status, ... } }
+```
+
+**Key event types:**
+- `iteration-start` / `iteration-end` — marks loop iteration boundaries
+- `dispatch-match` / `dispatch-stop` — what the auto-mode decided to do (or not do)
+- `unit-start` / `unit-end` — lifecycle of individual work units
+- `terminal` — auto-mode reached a terminal state (all done, budget exceeded, etc.)
+- `guard-block` — dispatch was blocked by a guard condition (e.g. needs user input)
+- `stuck-detected` — the loop detected it was stuck (same unit repeatedly dispatched)
+- `milestone-transition` — a milestone was promoted or completed
+- `worktree-enter` / `worktree-create-failed` / `worktree-merge-start` / `worktree-merge-failed` — worktree operations
+
+**Key concepts:**
+- **flowId**: UUID grouping all events in one iteration. Use to reconstruct what happened in a single loop pass.
+- **causedBy**: Cross-reference to a prior event (same or different flow). Enables causal chain tracing.
+- **seq**: Monotonically increasing within a flow. Reconstruct event order within an iteration.
+
+**To trace a stuck loop**: filter for `stuck-detected` events, then follow `flowId` to see the surrounding dispatch and unit events.
+**To trace a guard block**: filter for `guard-block` events, check `data.reason` for why dispatch was blocked.
+
 ### Crash Lock Format (`auto.lock`)
 
 JSON with fields: `pid`, `startedAt`, `unitType`, `unitId`, `unitStartedAt`, `completedUnits`, `sessionFile`
@@ -78,20 +106,24 @@ A unit dispatched more than once (`type/id` appears multiple times) indicates a
 
 1. **Start with the pre-parsed forensic report** above. The anomaly section contains automated findings — treat these as leads, not conclusions.
 
-2. **Form hypotheses** about which module and code path is responsible. Use the source map to identify candidate files.
+2. **Check the journal timeline** if present. The journal events show the auto-mode's decision sequence (dispatches, guards, stuck detection, worktree operations). Use flow IDs to group related events and trace causal chains.
+
+3. **Cross-reference activity logs and journal**. Activity logs show *what the LLM did* (tool calls, reasoning, errors). Journal events show *what auto-mode decided* (dispatch rules, iteration boundaries, state transitions). Together they reveal the full picture.
+
+4. **Form hypotheses** about which module and code path is responsible. Use the source map to identify candidate files.
 
-3. **Read the actual GSD source code** at `{{gsdSourceDir}}` to confirm or deny each hypothesis. Do not guess what code does — read it.
+5. **Read the actual GSD source code** at `{{gsdSourceDir}}` to confirm or deny each hypothesis. Do not guess what code does — read it.
 
-4. **Trace the code path** from the entry point (usually `auto-loop.ts` dispatch or `auto-dispatch.ts`) through to the failure point. Follow function calls across files.
+6. **Trace the code path** from the entry point (usually `auto-loop.ts` dispatch or `auto-dispatch.ts`) through to the failure point. Follow function calls across files.
 
-5. **Identify the specific file and line** where the bug lives. Determine what kind of defect it is:
+7. **Identify the specific file and line** where the bug lives. Determine what kind of defect it is:
    - Missing edge case / unhandled condition
    - Wrong boolean logic or comparison
    - Race condition or ordering issue
    - State corruption (e.g. completed-units.json out of sync with artifacts)
    - Timeout / recovery logic not triggering correctly
 
-6. **Clarify if needed.** Use ask_user_questions (max 2 questions) only if the report is genuinely insufficient. Do not ask questions you can answer from the data or source code.
+8. **Clarify if needed.** Use ask_user_questions (max 2 questions) only if the report is genuinely insufficient. Do not ask questions you can answer from the data or source code.
 
 ## Output
 

package/dist/resources/extensions/gsd/session-forensics.js

@@ -126,7 +126,16 @@ export function extractTrace(entries) {
                 }
             }
             if (isError && resultText) {
-                errors.push(resultText.slice(0, 300));
+                // Filter out benign "errors" that are normal during code exploration:
+                // - grep/rg/find returning exit code 1 (no matches) is expected POSIX behavior
+                // - User interrupts (Escape/skip) are intentional, not failures
+                const trimmed = resultText.trim();
+                const isBenignNoMatch = pending?.name === "bash" &&
+                    /^\(no output\)\s*\n\s*Command exited with code 1$/m.test(trimmed);
+                const isUserSkip = /^Skipped due to queued user message/i.test(trimmed);
+                if (!isBenignNoMatch && !isUserSkip) {
+                    errors.push(resultText.slice(0, 300));
+                }
             }
         }
     }

package/dist/web/standalone/.next/BUILD_ID

@@ -1 +1 @@
-VPcLnRF4BL8VoJEilBwlB
+zGWUKFTfjCQerNgsPpAbF

package/dist/web/standalone/.next/app-path-routes-manifest.json

@@ -1,22 +1,22 @@
 {
   "/_not-found/page": "/_not-found",
   "/_global-error/page": "/_global-error",
-  "/api/bridge-terminal/resize/route": "/api/bridge-terminal/resize",
-  "/api/bridge-terminal/input/route": "/api/bridge-terminal/input",
   "/api/boot/route": "/api/boot",
+  "/api/bridge-terminal/input/route": "/api/bridge-terminal/input",
+  "/api/bridge-terminal/resize/route": "/api/bridge-terminal/resize",
   "/api/bridge-terminal/stream/route": "/api/bridge-terminal/stream",
-  "/api/cleanup/route": "/api/cleanup",
   "/api/dev-mode/route": "/api/dev-mode",
-  "/api/browse-directories/route": "/api/browse-directories",
-  "/api/captures/route": "/api/captures",
+  "/api/cleanup/route": "/api/cleanup",
   "/api/export-data/route": "/api/export-data",
   "/api/doctor/route": "/api/doctor",
+  "/api/browse-directories/route": "/api/browse-directories",
+  "/api/captures/route": "/api/captures",
   "/api/forensics/route": "/api/forensics",
   "/api/git/route": "/api/git",
-  "/api/hooks/route": "/api/hooks",
   "/api/history/route": "/api/history",
-  "/api/knowledge/route": "/api/knowledge",
+  "/api/hooks/route": "/api/hooks",
   "/api/inspect/route": "/api/inspect",
+  "/api/knowledge/route": "/api/knowledge",
   "/api/live-state/route": "/api/live-state",
   "/api/preferences/route": "/api/preferences",
   "/api/recovery/route": "/api/recovery",
@@ -26,20 +26,20 @@
   "/api/session/command/route": "/api/session/command",
   "/api/session/events/route": "/api/session/events",
   "/api/settings-data/route": "/api/settings-data",
-  "/api/session/manage/route": "/api/session/manage",
   "/api/shutdown/route": "/api/shutdown",
+  "/api/session/manage/route": "/api/session/manage",
   "/api/skill-health/route": "/api/skill-health",
   "/api/steer/route": "/api/steer",
   "/api/terminal/input/route": "/api/terminal/input",
   "/api/switch-root/route": "/api/switch-root",
-  "/api/files/route": "/api/files",
   "/api/terminal/resize/route": "/api/terminal/resize",
   "/api/terminal/sessions/route": "/api/terminal/sessions",
-  "/api/terminal/stream/route": "/api/terminal/stream",
+  "/api/terminal/upload/route": "/api/terminal/upload",
   "/api/undo/route": "/api/undo",
+  "/api/terminal/stream/route": "/api/terminal/stream",
   "/api/visualizer/route": "/api/visualizer",
+  "/api/files/route": "/api/files",
   "/api/update/route": "/api/update",
-  "/api/terminal/upload/route": "/api/terminal/upload",
   "/api/remote-questions/route": "/api/remote-questions",
   "/page": "/"
 }