gsd-pi 2.80.0-dev.c5f2443b3 → 2.80.0-dev.d4fc28e6b

package/dist/resources/extensions/gsd/gsd-db.js

@@ -22,6 +22,7 @@
 // intentionally independent store for cross-worktree claim races and is
 // excluded from this invariant.
 import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
 import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
 import { dirname } from "node:path";
 import { GSDError, GSD_STALE_STATE } from "./errors.js";
@@ -36,7 +37,7 @@ import { rowToActiveDecision, rowToActiveRequirement, rowToDecision, rowToRequir
 import { rowToGate } from "./db-gate-rows.js";
 import { rowToArtifact, rowToMilestone } from "./db-milestone-artifact-rows.js";
 import { backupDatabaseBeforeMigration } from "./db-migration-backup.js";
-import { applyMigrationV2Artifacts, applyMigrationV3Memories, applyMigrationV4DecisionMadeBy, applyMigrationV5HierarchyTables, applyMigrationV6SliceSummaries, applyMigrationV7Dependencies, applyMigrationV8PlanningFields, applyMigrationV9Ordering, applyMigrationV10ReplanTrigger, applyMigrationV11TaskPlanning, applyMigrationV12QualityGates, applyMigrationV13HotPathIndexes, applyMigrationV14SliceDependencies, applyMigrationV15AuditTables, applyMigrationV16EscalationSource, applyMigrationV17TaskEscalation, applyMigrationV18MemorySources, applyMigrationV19MemoryFts, applyMigrationV20MemoryRelations, applyMigrationV21StructuredMemories, applyMigrationV22QualityGateRepair, applyMigrationV23MilestoneQueue, } from "./db-migration-steps.js";
+import { applyMigrationV2Artifacts, applyMigrationV3Memories, applyMigrationV4DecisionMadeBy, applyMigrationV5HierarchyTables, applyMigrationV6SliceSummaries, applyMigrationV7Dependencies, applyMigrationV8PlanningFields, applyMigrationV9Ordering, applyMigrationV10ReplanTrigger, applyMigrationV11TaskPlanning, applyMigrationV12QualityGates, applyMigrationV13HotPathIndexes, applyMigrationV14SliceDependencies, applyMigrationV15AuditTables, applyMigrationV16EscalationSource, applyMigrationV17TaskEscalation, applyMigrationV18MemorySources, applyMigrationV19MemoryFts, applyMigrationV20MemoryRelations, applyMigrationV21StructuredMemories, applyMigrationV22QualityGateRepair, applyMigrationV23MilestoneQueue, applyMigrationV26MilestoneCommitAttributions, applyMigrationV27ArtifactHash, applyMigrationV28MemoryLastHitAt, } from "./db-migration-steps.js";
 import { isMemoriesFtsAvailableSchema, tryCreateMemoriesFtsSchema } from "./db-memory-fts-schema.js";
 import { createDbOpenState } from "./db-open-state.js";
 import { createRuntimeKvTableV25 } from "./db-runtime-kv-schema.js";
@@ -52,7 +53,7 @@ const providerLoader = createSqliteProviderLoader({
     nodeVersion: process.versions.node,
     writeStderr: (message) => process.stderr.write(message),
 });
-export const SCHEMA_VERSION = 25;
+export const SCHEMA_VERSION = 28;
 function initSchema(db, fileBacked) {
     if (fileBacked)
         db.exec("PRAGMA journal_mode=WAL");
@@ -246,6 +247,18 @@ function migrateSchema(db) {
             createRuntimeKvTableV25(db);
             recordSchemaVersion(db, 25);
         }
+        if (currentVersion < 26) {
+            applyMigrationV26MilestoneCommitAttributions(db);
+            recordSchemaVersion(db, 26);
+        }
+        if (currentVersion < 27) {
+            applyMigrationV27ArtifactHash(db);
+            recordSchemaVersion(db, 27);
+        }
+        if (currentVersion < 28) {
+            applyMigrationV28MemoryLastHitAt(db);
+            recordSchemaVersion(db, 28);
+        }
         db.exec("COMMIT");
     }
     catch (err) {
@@ -817,8 +830,9 @@ export function clearArtifacts() {
 export function insertArtifact(a) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    currentDb.prepare(`INSERT OR REPLACE INTO artifacts (path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at)
-     VALUES (:path, :artifact_type, :milestone_id, :slice_id, :task_id, :full_content, :imported_at)`).run({
+    const contentHash = createHash("sha256").update(a.full_content).digest("hex");
+    currentDb.prepare(`INSERT OR REPLACE INTO artifacts (path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at, content_hash)
+     VALUES (:path, :artifact_type, :milestone_id, :slice_id, :task_id, :full_content, :imported_at, :content_hash)`).run({
         ":path": a.path,
         ":artifact_type": a.artifact_type,
         ":milestone_id": a.milestone_id,
@@ -826,6 +840,7 @@ export function insertArtifact(a) {
         ":task_id": a.task_id,
         ":full_content": a.full_content,
         ":imported_at": new Date().toISOString(),
+        ":content_hash": contentHash,
     });
 }
 export function insertMilestone(m) {
@@ -1158,6 +1173,47 @@ export function getSliceTasks(milestoneId, sliceId) {
     const rows = currentDb.prepare("SELECT * FROM tasks WHERE milestone_id = :mid AND slice_id = :sid ORDER BY sequence, id").all({ ":mid": milestoneId, ":sid": sliceId });
     return rows.map(rowToTask);
 }
+export function getCompletedMilestoneTaskFileHints(milestoneId) {
+    if (!currentDb)
+        return [];
+    const rows = currentDb.prepare(`SELECT files, key_files
+     FROM tasks
+     WHERE milestone_id = :mid AND status IN ('complete', 'done')`).all({ ":mid": milestoneId });
+    const hints = new Set();
+    for (const row of rows) {
+        for (const raw of [row["files"], row["key_files"]]) {
+            for (const file of parseStringArrayColumn(raw)) {
+                const normalized = normalizeRepoPath(file);
+                if (normalized)
+                    hints.add(normalized);
+            }
+        }
+    }
+    return [...hints];
+}
+function parseStringArrayColumn(raw) {
+    if (Array.isArray(raw))
+        return raw.filter((entry) => typeof entry === "string");
+    if (typeof raw !== "string")
+        return [];
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return [];
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed))
+            return parsed.filter((entry) => typeof entry === "string");
+        if (typeof parsed === "string")
+            return [parsed];
+    }
+    catch {
+        return trimmed.split(",");
+    }
+    return [];
+}
+function normalizeRepoPath(file) {
+    return file.trim().replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
 // ─── ADR-011 Phase 2 escalation helpers ──────────────────────────────────
 /** Set pause-on-escalation state on a completed task. Mutually exclusive with awaiting_review. */
 export function setTaskEscalationPending(milestoneId, sliceId, taskId, artifactPath) {
@@ -1476,6 +1532,13 @@ export function reconcileWorktreeDb(mainDbPath, worktreeDbPath) {
             const hasEscalationAwaiting = wtTaskInfo.some((col) => col["name"] === "escalation_awaiting_review");
             const hasEscalationArtifact = wtTaskInfo.some((col) => col["name"] === "escalation_artifact_path");
             const hasEscalationOverride = wtTaskInfo.some((col) => col["name"] === "escalation_override_applied_at");
+            const wtArtifactInfo = adapter.prepare("PRAGMA wt.table_info('artifacts')").all();
+            const hasArtifactContentHash = wtArtifactInfo.some((col) => col["name"] === "content_hash");
+            const wtMemoryInfo = adapter.prepare("PRAGMA wt.table_info('memories')").all();
+            const hasMemoryScope = wtMemoryInfo.some((col) => col["name"] === "scope");
+            const hasMemoryTags = wtMemoryInfo.some((col) => col["name"] === "tags");
+            const hasMemoryStructuredFields = wtMemoryInfo.some((col) => col["name"] === "structured_fields");
+            const hasMemoryLastHitAt = wtMemoryInfo.some((col) => col["name"] === "last_hit_at");
             const decConf = adapter.prepare(`SELECT m.id FROM decisions m INNER JOIN wt.decisions w ON m.id = w.id WHERE m.decision != w.decision OR m.choice != w.choice OR m.rationale != w.rationale OR ${hasMadeBy ? "m.made_by != w.made_by" : "'agent' != 'agent'"} OR m.superseded_by IS NOT w.superseded_by`).all();
             for (const row of decConf)
                 conflicts.push(`decision ${row["id"]}: modified in both`);
@@ -1508,12 +1571,17 @@ export function reconcileWorktreeDb(mainDbPath, worktreeDbPath) {
                  supporting_slices, validation, notes, full_content, superseded_by
           FROM wt.requirements
         `).run());
+                // V27: preserve content_hash. If the worktree predates V27 (no column),
+                // fall back to the main DB's existing hash so reconcile doesn't null
+                // out integrity fingerprints on artifacts that were unchanged in wt.
                 merged.artifacts = countChanges(adapter.prepare(`
           INSERT OR REPLACE INTO artifacts (
-            path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at
+            path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at, content_hash
           )
-          SELECT path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at
-          FROM wt.artifacts
+          SELECT w.path, w.artifact_type, w.milestone_id, w.slice_id, w.task_id, w.full_content, w.imported_at,
+                 ${hasArtifactContentHash ? "w.content_hash" : "m.content_hash"}
+          FROM wt.artifacts w
+          LEFT JOIN artifacts m ON m.path = w.path
         `).run());
                 // Merge milestones — worktree may have updated status/planning fields.
                 // Never downgrade status: complete > active > pre-planning (#4372).
@@ -1611,15 +1679,25 @@ export function reconcileWorktreeDb(mainDbPath, worktreeDbPath) {
           FROM wt.tasks w
           LEFT JOIN tasks m ON m.milestone_id = w.milestone_id AND m.slice_id = w.slice_id AND m.id = w.id
         `).run());
-                // Merge memories — keep worktree-learned insights
+                // Merge memories — keep worktree-learned insights.
+                // V18 (scope, tags), V21 (structured_fields), V28 (last_hit_at): for each
+                // column the wt may not yet have (older worktree DB), fall back to the
+                // main DB's existing value via LEFT JOIN so reconcile never silently
+                // resets these fields to defaults on rows that already had them.
                 merged.memories = countChanges(adapter.prepare(`
           INSERT OR REPLACE INTO memories (
             seq, id, category, content, confidence, source_unit_type, source_unit_id,
-            created_at, updated_at, superseded_by, hit_count
+            created_at, updated_at, superseded_by, hit_count,
+            scope, tags, structured_fields, last_hit_at
           )
-          SELECT seq, id, category, content, confidence, source_unit_type, source_unit_id,
-                 created_at, updated_at, superseded_by, hit_count
-          FROM wt.memories
+          SELECT w.seq, w.id, w.category, w.content, w.confidence, w.source_unit_type, w.source_unit_id,
+                 w.created_at, w.updated_at, w.superseded_by, w.hit_count,
+                 ${hasMemoryScope ? "w.scope" : "COALESCE(m.scope, 'project')"},
+                 ${hasMemoryTags ? "w.tags" : "COALESCE(m.tags, '[]')"},
+                 ${hasMemoryStructuredFields ? "w.structured_fields" : "m.structured_fields"},
+                 ${hasMemoryLastHitAt ? "w.last_hit_at" : "m.last_hit_at"}
+          FROM wt.memories w
+          LEFT JOIN memories m ON m.id = w.id
         `).run());
                 // Merge verification evidence — append-only, use INSERT OR IGNORE to avoid duplicates
                 merged.verification_evidence = countChanges(adapter.prepare(`
@@ -1735,6 +1813,7 @@ export function deleteMilestone(milestoneId) {
         currentDb.prepare(`DELETE FROM replan_history WHERE milestone_id = :mid`).run({ ":mid": milestoneId });
         currentDb.prepare(`DELETE FROM assessments WHERE milestone_id = :mid`).run({ ":mid": milestoneId });
         currentDb.prepare(`DELETE FROM artifacts WHERE milestone_id = :mid`).run({ ":mid": milestoneId });
+        currentDb.prepare(`DELETE FROM milestone_commit_attributions WHERE milestone_id = :mid`).run({ ":mid": milestoneId });
         currentDb.prepare(`DELETE FROM milestone_leases WHERE milestone_id = :mid`).run({ ":mid": milestoneId });
         currentDb.prepare(`DELETE FROM milestones WHERE id = :mid`).run({ ":mid": milestoneId });
     });
@@ -1962,6 +2041,59 @@ export function upsertTurnGitTransaction(entry) {
         ":updated_at": entry.updatedAt,
     });
 }
+export function getMilestoneCommitAttributionShas(milestoneId) {
+    if (!currentDb)
+        return [];
+    const rows = currentDb.prepare(`SELECT commit_sha
+     FROM milestone_commit_attributions
+     WHERE milestone_id = :mid
+     ORDER BY created_at, commit_sha`).all({ ":mid": milestoneId });
+    return rows
+        .map((row) => typeof row["commit_sha"] === "string" ? row["commit_sha"] : "")
+        .filter(Boolean);
+}
+export function recordMilestoneCommitAttribution(entry) {
+    if (!currentDb)
+        return;
+    transaction(() => {
+        currentDb.prepare(`INSERT OR REPLACE INTO milestone_commit_attributions (
+        commit_sha, milestone_id, slice_id, task_id, source, confidence, files_json, created_at
+      ) VALUES (
+        :commit_sha, :milestone_id, :slice_id, :task_id, :source, :confidence, :files_json, :created_at
+      )`).run({
+            ":commit_sha": entry.commitSha,
+            ":milestone_id": entry.milestoneId,
+            ":slice_id": entry.sliceId ?? null,
+            ":task_id": entry.taskId ?? null,
+            ":source": entry.source,
+            ":confidence": entry.confidence,
+            ":files_json": JSON.stringify(entry.files),
+            ":created_at": entry.createdAt,
+        });
+        currentDb.prepare(`INSERT OR IGNORE INTO audit_events (
+        event_id, trace_id, turn_id, caused_by, category, type, ts, payload_json
+      ) VALUES (
+        :event_id, :trace_id, :turn_id, :caused_by, :category, :type, :ts, :payload_json
+      )`).run({
+            ":event_id": `milestone-commit-attribution:${entry.milestoneId}:${entry.commitSha}`,
+            ":trace_id": "milestone-commit-attribution",
+            ":turn_id": null,
+            ":caused_by": null,
+            ":category": "git",
+            ":type": "milestone-commit-attribution-recorded",
+            ":ts": entry.createdAt,
+            ":payload_json": JSON.stringify({
+                commitSha: entry.commitSha,
+                milestoneId: entry.milestoneId,
+                sliceId: entry.sliceId ?? null,
+                taskId: entry.taskId ?? null,
+                source: entry.source,
+                confidence: entry.confidence,
+                files: entry.files,
+            }),
+        });
+    });
+}
 export function insertAuditEvent(entry) {
     if (!currentDb)
         return;
@@ -2048,6 +2180,7 @@ export function clearEngineHierarchy() {
         currentDb.exec("DELETE FROM slice_dependencies");
         currentDb.exec("DELETE FROM assessments");
         currentDb.exec("DELETE FROM replan_history");
+        currentDb.exec("DELETE FROM milestone_commit_attributions");
         currentDb.exec("DELETE FROM tasks");
         currentDb.exec("DELETE FROM slices");
         currentDb.exec("DELETE FROM milestone_leases");
@@ -2323,7 +2456,7 @@ export function updateMemoryContentRow(id, content, confidence, updatedAt) {
 export function incrementMemoryHitCount(id, updatedAt) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    currentDb.prepare("UPDATE memories SET hit_count = hit_count + 1, updated_at = :updated_at WHERE id = :id").run({ ":updated_at": updatedAt, ":id": id });
+    currentDb.prepare("UPDATE memories SET hit_count = hit_count + 1, updated_at = :updated_at, last_hit_at = :last_hit_at WHERE id = :id").run({ ":updated_at": updatedAt, ":last_hit_at": updatedAt, ":id": id });
 }
 export function supersedeMemoryRow(oldId, newId, updatedAt) {
     if (!currentDb)

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

@@ -16,7 +16,7 @@ import { invalidateAllCaches } from "./cache.js";
 import { startAutoDetached } from "./auto.js";
 import { clearLock } from "./crash-recovery.js";
 import { assessInterruptedSession, formatInterruptedSessionRunningMessage, formatInterruptedSessionSummary, } from "./interrupted-session.js";
-import { listUnitRuntimeRecords, clearUnitRuntimeRecord } from "./unit-runtime.js";
+import { listUnitRuntimeRecords, clearUnitRuntimeRecord, isInFlightRuntimePhase } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdHome } from "./gsd-home.js";
 import { gsdRoot, milestonesDir, resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, clearPathCache, } from "./paths.js";
@@ -51,6 +51,23 @@ export { showQueue, handleQueueReorder, showQueueAdd, buildExistingMilestonesCon
 import { logWarning } from "./workflow-logger.js";
 import { deleteRuntimeKv } from "./db/runtime-kv.js";
 import { PAUSED_SESSION_KV_KEY } from "./interrupted-session.js";
+import { buildWorkflowDispatchContent } from "./workflow-protocol.js";
+import { isFullGsdToolSurfaceRequested, restoreGsdWorkflowTools, scopeGsdWorkflowToolsForDispatch } from "./bootstrap/register-hooks.js";
+function scheduleAutoStartAfterIdle(ctx, pi, basePath, verboseMode, options, launch = startAutoDetached) {
+    const waitForIdle = typeof ctx.waitForIdle === "function"
+        ? ctx.waitForIdle.bind(ctx)
+        : async () => { };
+    void waitForIdle()
+        .then(() => {
+        setTimeout(() => launch(ctx, pi, basePath, verboseMode, options), 0);
+    })
+        .catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`Auto-start failed while waiting for the prior turn to settle: ${message}`, "error");
+        logWarning("guided", `auto-start idle wait failed: ${message}`);
+    });
+}
+export const _scheduleAutoStartAfterIdleForTest = scheduleAutoStartAfterIdle;
 // ─── Scope-based validator wrappers ──────────────────────────────────────────
 // These thin wrappers accept a MilestoneScope so callers that already hold a
 // pinned scope never have to re-derive (basePath, milestoneId) separately.
@@ -71,6 +88,19 @@ export function verifyExpectedArtifactForScope(scope, unitType, unitId) {
 export function resolveExpectedArtifactPathForScope(scope, unitType, unitId) {
     return resolveExpectedArtifactPath(unitType, unitId, scope.workspace.projectRoot);
 }
+async function runQuickTaskChoice(ctx, pi) {
+    if (!ctx.hasUI) {
+        ctx.ui.notify("Run /gsd quick <task> for small bounded work, or /gsd do <task> for natural-language routing.", "info");
+        return;
+    }
+    const task = (await ctx.ui.input("Quick task", "Describe the small task to run with /gsd quick"))?.trim();
+    if (!task) {
+        ctx.ui.notify("Quick task cancelled.", "info");
+        return;
+    }
+    const { handleQuick } = await import("./quick.js");
+    await handleQuick(task, ctx, pi);
+}
 /**
  * Scope-based overload of isGhostMilestone.
  * Binds basePath and milestoneId from the scope, ensuring path resolution
@@ -312,7 +342,7 @@ async function dispatchNextDeepProjectSetupStage(entry) {
     const { DISPATCH_RULES, hasPendingDeepStage } = await import("./auto-dispatch.js");
     if (!hasPendingDeepStage(prefs, entry.basePath)) {
         pendingDeepProjectSetupMap.delete(entry.basePath);
-        startAutoDetached(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
+        scheduleAutoStartAfterIdle(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
         return true;
     }
     const state = await deriveState(entry.basePath);
@@ -346,14 +376,14 @@ async function dispatchNextDeepProjectSetupStage(entry) {
         }
         else if (hasPendingDeepStage(prefs, entry.basePath)) {
             pendingDeepProjectSetupMap.delete(entry.basePath);
-            startAutoDetached(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
+            scheduleAutoStartAfterIdle(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
             return true;
         }
         return false;
     }
     if (!USER_DRIVEN_DEEP_SETUP_UNITS.has(result.unitType)) {
         pendingDeepProjectSetupMap.delete(entry.basePath);
-        startAutoDetached(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
+        scheduleAutoStartAfterIdle(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
         return true;
     }
     entry.currentUnitType = result.unitType;
@@ -531,7 +561,7 @@ export function checkAutoStartAfterDiscuss() {
     }
     pendingAutoStartMap.delete(basePath);
     ctx.ui.notify(`Milestone ${milestoneId} ready.`, "success");
-    startAutoDetached(ctx, pi, basePath, false, { step });
+    scheduleAutoStartAfterIdle(ctx, pi, basePath, false, { step });
     return true;
 }
 /**
@@ -817,38 +847,55 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType)
             return;
         }
     }
-    // Scope tools for discuss flows (#2949).
+    // Scope tools for guided workflow turns (#2949, token-consumption savings).
     // Providers with grammar-based constrained decoding (xAI/Grok) return
     // "Grammar is too complex" when the combined tool schema is too large.
-    // Discuss flows only need a small subset of GSD tools — strip the heavy
-    // planning/execution/completion tools to keep the grammar within limits.
+    // Guided workflow turns only need the active unit's tool surface; strip
+    // unrelated GSD tools and broad non-GSD tools for this queued turn, then
+    // restore so the narrowed surface does not leak into future dispatches.
     let savedTools = null;
-    if (unitType?.startsWith("discuss-")) {
+    try {
         const currentTools = pi.getActiveTools();
-        savedTools = currentTools;
-        // Keep all non-GSD tools (builtins, other extensions) and only the
-        // GSD tools on the discuss allowlist.
-        const scopedTools = currentTools.filter((t) => !t.startsWith("gsd_") || DISCUSS_TOOLS_ALLOWLIST.includes(t));
-        pi.setActiveTools(scopedTools);
-        debugLog("discuss-tool-scoping", {
-            unitType,
-            before: currentTools.length,
-            after: scopedTools.length,
-            removed: currentTools.length - scopedTools.length,
-        });
-    }
-    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
-    const workflow = readFileSync(workflowPath, "utf-8");
-    pi.sendMessage({
-        customType,
-        content: `Read the following GSD workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${note}`,
-        display: false,
-    }, { triggerTurn: true });
-    // Restore full tool set after the message is queued. The LLM turn has
-    // already captured the scoped set — restoring prevents the narrowed
-    // tools from leaking into subsequent dispatches (#3628).
-    if (savedTools) {
-        pi.setActiveTools(savedTools);
+        savedTools = {
+            tools: currentTools,
+            visibleSkills: typeof pi.getVisibleSkills === "function" ? pi.getVisibleSkills() : undefined,
+            restoreVisibleSkills: typeof pi.setVisibleSkills === "function",
+        };
+        if (unitType?.startsWith("discuss-") && !isFullGsdToolSurfaceRequested()) {
+            // Keep all non-GSD tools (builtins, other extensions) and only the
+            // GSD tools on the discuss allowlist.
+            const scopedTools = currentTools.filter((t) => !t.startsWith("gsd_") || DISCUSS_TOOLS_ALLOWLIST.includes(t));
+            pi.setActiveTools(scopedTools);
+            const scopedState = scopeGsdWorkflowToolsForDispatch(pi, unitType);
+            savedTools = {
+                tools: currentTools,
+                visibleSkills: scopedState?.visibleSkills ?? savedTools.visibleSkills,
+                restoreVisibleSkills: scopedState?.restoreVisibleSkills ?? savedTools.restoreVisibleSkills,
+            };
+            debugLog("discuss-tool-scoping", {
+                unitType,
+                before: currentTools.length,
+                after: pi.getActiveTools().length,
+                removed: currentTools.length - pi.getActiveTools().length,
+            });
+        }
+        else {
+            savedTools = scopeGsdWorkflowToolsForDispatch(pi, unitType) ?? savedTools;
+        }
+        const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
+        const workflow = readFileSync(workflowPath, "utf-8");
+        pi.sendMessage({
+            customType,
+            content: buildWorkflowDispatchContent({ workflow, workflowPath, task: note }),
+            display: false,
+        }, { triggerTurn: true });
+    }
+    finally {
+        // Restore full tool set after the message is queued. The LLM turn has
+        // already captured the scoped set — restoring prevents the narrowed
+        // tools from leaking into subsequent dispatches (#3628). The finally
+        // block ensures restoration even if sendMessage throws.
+        restoreGsdWorkflowTools(pi, savedTools);
     }
 }
 function getStructuredQuestionsAvailability(pi, ctx) {
@@ -1469,8 +1516,8 @@ function selfHealRuntimeRecords(basePath, ctx) {
                 cleared++;
                 continue;
             }
-            // Clear records stuck in dispatched or timeout phase (process died mid-unit)
-            if (phase === "dispatched" || phase === "timeout") {
+            // Clear records stuck in an in-flight phase (process died mid-unit).
+            if (isInFlightRuntimePhase(phase)) {
                 clearUnitRuntimeRecord(basePath, unitType, unitId);
                 cleared++;
             }
@@ -1695,6 +1742,20 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             return;
         }
     }
+    if (interrupted.classification !== "recoverable") {
+        try {
+            const { autoImportMarkdownHierarchyIfDbMismatch } = await import("./migration-auto-check.js");
+            const result = await autoImportMarkdownHierarchyIfDbMismatch(basePath);
+            if (result.action === "imported") {
+                ctx.ui.notify(`Recovered migrated planning state into gsd.db (${result.reason}): ${result.afterDb.milestones} milestone(s), ${result.afterDb.slices} slice(s), ${result.afterDb.tasks} task(s).`, "info");
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            ctx.ui.notify(`GSD could not auto-import existing planning state into gsd.db: ${message}`, "warning");
+            logWarning("guided", `planning state auto-import failed: ${message}`, { file: "guided-flow.ts" });
+        }
+    }
     // Always derive from the project root — the assessment may have derived
     // state from a worktree path that was cleaned up in the stale branch above.
     const state = await deriveState(basePath);
@@ -1716,8 +1777,8 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     // standard wizard below.
     {
         const prefs = loadEffectiveGSDPreferences(basePath)?.preferences;
-        const { hasPendingDeepStage } = await import("./auto-dispatch.js");
-        if (hasPendingDeepStage(prefs, basePath)) {
+        const { shouldRunDeepProjectSetup } = await import("./auto-dispatch.js");
+        if (shouldRunDeepProjectSetup(state, prefs, basePath)) {
             await startDeepProjectSetupForeground(ctx, pi, basePath, stepMode);
             return;
         }
@@ -1780,16 +1841,24 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 title: "GSD — Get Shit Done",
                 summary: ["No active milestone."],
                 actions: [
+                    {
+                        id: "quick_task",
+                        label: "Quick task",
+                        description: "For small bounded work, run /gsd quick <task> or /gsd do <task>.",
+                        recommended: true,
+                    },
                     {
                         id: "new_milestone",
                         label: "Create next milestone",
-                        description: "Define what to build next.",
-                        recommended: true,
+                        description: "Define a larger body of work with planning artifacts.",
                     },
                 ],
                 notYetMessage: "Run /gsd when ready.",
             });
-            if (choice === "new_milestone") {
+            if (choice === "quick_task") {
+                await runQuickTaskChoice(ctx, pi);
+            }
+            else if (choice === "new_milestone") {
                 setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
                 await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
             }
@@ -1809,11 +1878,16 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             title: `GSD — ${milestoneId}: ${milestoneTitle}`,
             summary: ["All milestones complete."],
             actions: [
+                {
+                    id: "quick_task",
+                    label: "Quick task",
+                    description: "Do a small bounded task without opening a milestone.",
+                    recommended: true,
+                },
                 {
                     id: "new_milestone",
                     label: "Start new milestone",
                     description: "Define and plan the next milestone.",
-                    recommended: true,
                 },
                 {
                     id: "status",
@@ -1823,7 +1897,10 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             ],
             notYetMessage: "Run /gsd when ready.",
         });
-        if (choice === "new_milestone") {
+        if (choice === "quick_task") {
+            await runQuickTaskChoice(ctx, pi);
+        }
+        else if (choice === "new_milestone") {
             const milestoneIds = findMilestoneIds(basePath);
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
@@ -1916,13 +1993,18 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
             const hasContext = !!(contextFile && await loadFile(contextFile));
             const actions = [
+                {
+                    id: "quick_task",
+                    label: "Quick task instead",
+                    description: "Use this when the work is small and should not become a milestone.",
+                    recommended: true,
+                },
                 {
                     id: "plan",
                     label: "Create roadmap",
                     description: hasContext
                         ? "Context captured. Decompose into slices with a boundary map."
                         : "Decompose the milestone into slices with a boundary map.",
-                    recommended: true,
                 },
                 ...(!hasContext ? [{
                         id: "discuss",
@@ -1946,7 +2028,10 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 actions,
                 notYetMessage: "Run /gsd when ready.",
             });
-            if (choice === "plan") {
+            if (choice === "quick_task") {
+                await runQuickTaskChoice(ctx, pi);
+            }
+            else if (choice === "plan") {
                 setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
                 await dispatchWorkflow(pi, await buildPlanMilestonePrompt(milestoneId, milestoneTitle, basePath), "gsd-run", ctx, "plan-milestone");
             }