gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.96d4bb599

package/src/resources/extensions/gsd/auto.ts

@@ -146,6 +146,7 @@ import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
 import {
   createAutoWorktree,
   enterAutoWorktree,
+  enterBranchModeForMilestone,
   teardownAutoWorktree,
   isInAutoWorktree,
   getAutoWorktreePath,
@@ -160,6 +161,7 @@ import {
   escapeStaleWorktree,
 } from "./auto-worktree.js";
 import { pruneQueueOrder } from "./queue-order.js";
+import { startCommandPolling as _startCommandPolling, isRemoteConfigured } from "../remote-questions/manager.js";
 
 import { debugLog, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
 import {
@@ -168,6 +170,7 @@ import {
 } from "./auto-recovery.js";
 import { resolveDispatch, DISPATCH_RULES } from "./auto-dispatch.js";
 import { getErrorMessage } from "./error-utils.js";
+import { recoverFailedMigration } from "./migrate-external.js";
 import { initRegistry, convertDispatchRules } from "./rule-registry.js";
 import { emitJournalEvent as _emitJournalEvent, type JournalEntry } from "./journal.js";
 import {
@@ -201,7 +204,7 @@ import {
 } from "./auto-post-unit.js";
 import { bootstrapAutoSession, openProjectDbIfPresent, type BootstrapDeps } from "./auto-start.js";
 import { initHealthWidget } from "./health-widget.js";
-import { autoLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight, type LoopDeps, type ErrorContext } from "./auto-loop.js";
+import { runLegacyAutoLoop, runUokKernelLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight, type LoopDeps, type ErrorContext } from "./auto-loop.js";
 import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
 // Slice-level parallelism (#2340)
@@ -326,6 +329,7 @@ export function startAutoDetached(
   });
 }
 
+/** Returns true if the project is configured for `isolation:worktree` mode. */
 export function shouldUseWorktreeIsolation(): boolean {
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
   if (prefs?.isolation === "worktree") return true;
@@ -390,6 +394,27 @@ function deregisterSigtermHandler(): void {
   s.sigtermHandler = null;
 }
 
+/**
+ * Wrapper: start background command polling for the configured remote channel
+ * (currently Telegram only). Stores the cleanup function on the session so
+ * every exit path can stop the interval via stopCommandPolling().
+ * No-op when no remote channel is configured.
+ */
+function startAutoCommandPolling(basePath: string): void {
+  if (!isRemoteConfigured()) return;
+  // Clear any existing interval before starting a new one (e.g. resume path).
+  stopAutoCommandPolling();
+  s.commandPollingCleanup = _startCommandPolling(basePath);
+}
+
+/** Wrapper: stop background command polling and clear the stored cleanup. */
+function stopAutoCommandPolling(): void {
+  if (s.commandPollingCleanup) {
+    s.commandPollingCleanup();
+    s.commandPollingCleanup = null;
+  }
+}
+
 export { type AutoDashboardData } from "./auto-dashboard.js";
 
 export function getAutoDashboardData(): AutoDashboardData {
@@ -466,6 +491,15 @@ export function getAutoModeStartModel(): {
   return s.autoModeStartModel;
 }
 
+/**
+ * Update the dashboard-facing dispatched model label.
+ * Used when runtime recovery switches models mid-unit (e.g. provider fallback)
+ * so the AUTO box reflects the active model immediately.
+ */
+export function setCurrentDispatchedModelId(model: { provider: string; id: string } | null): void {
+  s.currentDispatchedModelId = model ? `${model.provider}/${model.id}` : null;
+}
+
 // Tool tracking — delegates to auto-tool-tracking.ts
 export function markToolStart(toolCallId: string, toolName?: string): void {
   _markToolStart(toolCallId, s.active, toolName);
@@ -648,6 +682,7 @@ function handleLostSessionLock(
   s.paused = false;
   deactivateGSD();
   clearUnitTimeout();
+  stopAutoCommandPolling();
   restoreProjectRootEnv();
   restoreMilestoneLockEnv();
   deregisterSigtermHandler();
@@ -687,6 +722,7 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void {
   s.active = false;
   deactivateGSD();
   clearUnitTimeout();
+  stopAutoCommandPolling();
   restoreProjectRootEnv();
   restoreMilestoneLockEnv();
 
@@ -735,6 +771,7 @@ export async function stopAuto(
     // ── Step 1: Timers and locks ──
     try {
       clearUnitTimeout();
+      stopAutoCommandPolling();
       if (lockBase()) clearLock(lockBase());
       if (lockBase()) releaseSessionLock(lockBase());
     } catch (e) {
@@ -1000,6 +1037,7 @@ export async function pauseAuto(
 ): Promise<void> {
   if (!s.active) return;
   clearUnitTimeout();
+  stopAutoCommandPolling();
 
   // Flush queued follow-up messages (#3512).
   // Late async notifications (async_job_result, gsd-auto-wrapup) can trigger
@@ -1103,6 +1141,7 @@ function buildResolverDeps(): WorktreeResolverDeps {
     teardownAutoWorktree,
     createAutoWorktree,
     enterAutoWorktree,
+    enterBranchModeForMilestone,
     getAutoWorktreePath,
     autoCommitCurrentBranch,
     getCurrentBranch,
@@ -1253,6 +1292,11 @@ function buildLoopDeps(): LoopDeps {
   } as unknown as LoopDeps;
 }
 
+/**
+ * Start auto-mode. Handles both fresh-start and resume paths, sets up session
+ * state, enters the milestone worktree or branch, and dispatches the first unit.
+ * No-ops if auto-mode is already active.
+ */
 export async function startAuto(
   ctx: ExtensionCommandContext,
   pi: ExtensionAPI,
@@ -1281,6 +1325,13 @@ export async function startAuto(
   // Escape stale worktree cwd from a previous milestone (#608).
   base = escapeStaleWorktree(base);
 
+  // Heal .gsd.migrating before any branching — covers both fresh-start and
+  // resume paths (#4416). The matching call in auto-start.ts covers the
+  // bootstrap-only path; this call ensures the resume path is also protected.
+  if (recoverFailedMigration(base)) {
+    ctx.ui.notify("Recovered unfinished migration (.gsd.migrating → .gsd).", "info");
+  }
+
   const freshStartAssessment = interruptedAssessment
     ?? await assessInterruptedSession(base);
 
@@ -1438,10 +1489,10 @@ export async function startAuto(
       ctx.ui.notify(summary, level as "info" | "warning" | "error");
     });
 
-    // ── Auto-worktree: re-enter worktree on resume ──
+    // ── Auto-worktree / branch-mode: re-enter on resume ──
     if (
       s.currentMilestoneId &&
-      shouldUseWorktreeIsolation() &&
+      getIsolationMode() !== "none" &&
       s.originalBasePath &&
       !isInAutoWorktree(s.basePath) &&
       !detectWorktreeName(s.basePath) &&
@@ -1533,12 +1584,14 @@ export async function startAuto(
     logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
 
     captureProjectRootEnv(s.originalBasePath || s.basePath);
+    startAutoCommandPolling(s.basePath);
     await runAutoLoopWithUok({
       ctx,
       pi,
       s,
       deps: buildLoopDeps(),
-      runLegacyLoop: autoLoop,
+      runKernelLoop: runUokKernelLoop,
+      runLegacyLoop: runLegacyAutoLoop,
     });
     cleanupAfterLoopExit(ctx);
     return;
@@ -1573,40 +1626,20 @@ export async function startAuto(
   }
   logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
 
+  startAutoCommandPolling(s.basePath);
+
   // Dispatch the first unit
   await runAutoLoopWithUok({
     ctx,
     pi,
     s,
     deps: buildLoopDeps(),
-    runLegacyLoop: autoLoop,
+    runKernelLoop: runUokKernelLoop,
+    runLegacyLoop: runLegacyAutoLoop,
   });
   cleanupAfterLoopExit(ctx);
 }
 
-// ─── Agent End Handler ────────────────────────────────────────────────────────
-
-/**
- * Deprecated thin wrapper — kept as export for backward compatibility.
- * The actual agent_end processing now happens via resolveAgentEnd() in auto-loop.ts,
- * which is called directly from index.ts. The autoLoop() while loop handles all
- * post-unit processing (verification, hooks, dispatch) that this function used to do.
- *
- * If called by straggler code, it simply resolves the pending promise so the loop
- * can continue.
- */
-export async function handleAgentEnd(
-  ctx: ExtensionContext,
-  pi: ExtensionAPI,
-): Promise<void> {
-  if (!s.active || !s.cmdCtx) {
-    // Even when inactive, resolve any pending promise so the loop is unblocked.
-    resolveAgentEndCancelled();
-    return;
-  }
-  clearUnitTimeout();
-  resolveAgentEnd({ messages: [] });
-}
 // describeNextUnit is imported from auto-dashboard.ts and re-exported
 export { describeNextUnit } from "./auto-dashboard.js";
 

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -2,7 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { logWarning } from "../workflow-logger.js";
 import { checkAutoStartAfterDiscuss } from "../guided-flow.js";
-import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto } from "../auto.js";
+import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto, setCurrentDispatchedModelId } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
 import { isSessionSwitchInFlight, resolveAgentEnd } from "../auto-loop.js";
@@ -124,26 +124,11 @@ export async function handleAgentEnd(
     // ── 1. Classify using rawErrorMsg to avoid prose false-positives ────
     const cls = classifyError(rawErrorMsg, explicitRetryAfterMs);
 
-    // ── 1b. Defer to Core RetryHandler for transient errors ─────────────
-    // The Core RetryHandler (agent-session.ts) processes retryable errors
-    // AFTER this extension handler, in the same _processAgentEvent() call.
-    // For transient errors (overloaded, rate limit, server), the Core will
-    // retry in-context — same session, same conversation — which is strictly
-    // better than our Layer 2 pause+resume (which creates a new session).
-    //
-    // If we react here AND the Core also retries, we race: pauseAuto tears
-    // down the session while agent.continue() starts a new turn.
-    //
-    // Solution: Do nothing for transient errors. The Core RetryHandler
-    // runs next in _processAgentEvent and will either:
-    //   a) Retry successfully → new agent_end (success) → we see it next time
-    //   b) Exhaust retries → the agent stays idle, autoLoop's unit timeout
-    //      or stuck detection handles it
-    //
-    // We do NOT call resolveAgentEnd here — that would unblock autoLoop
-    // prematurely while the Core is still retrying in the same session.
-    // We do NOT call pauseAuto — that would tear down the session.
-    if (isTransient(cls)) {
+    // ── 1b. Defer to Core RetryHandler for most transient errors ────────
+    // Core retries transient failures in-session after this handler.
+    // Keep that behavior for non-rate-limit classes to avoid pause/retry races,
+    // but let rate-limit continue into model fallback logic below (#4373).
+    if (isTransient(cls) && cls.kind !== "rate-limit") {
       return;
     }
 
@@ -202,6 +187,7 @@ export async function handleAgentEnd(
             if (modelToSet) {
               const ok = await pi.setModel(modelToSet, { persist: false });
               if (ok) {
+                setCurrentDispatchedModelId({ provider: modelToSet.provider, id: modelToSet.id });
                 ctx.ui.notify(`Model error${errorDetail}. Switched to fallback: ${nextModelId} and resuming.`, "warning");
                 pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
                 return;
@@ -219,6 +205,7 @@ export async function handleAgentEnd(
           if (startModel) {
             const ok = await pi.setModel(startModel, { persist: false });
             if (ok) {
+              setCurrentDispatchedModelId({ provider: startModel.provider, id: startModel.id });
               retryState.networkRetryCount = 0;
               retryState.currentRetryModelId = undefined;
               ctx.ui.notify(`Model error${errorDetail}. Restored session model: ${sessionModel.provider}/${sessionModel.id} and resuming.`, "warning");

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -449,10 +449,14 @@ export function registerDbTools(pi: ExtensionAPI): void {
         depends: Type.Array(Type.String(), { description: "Slice dependency IDs" }),
         demo: Type.String({ description: "Roadmap demo text / After this" }),
         goal: Type.String({ description: "Slice goal" }),
-        successCriteria: Type.String({ description: "Slice success criteria block" }),
-        proofLevel: Type.String({ description: "Slice proof level" }),
-        integrationClosure: Type.String({ description: "Slice integration closure" }),
-        observabilityImpact: Type.String({ description: "Slice observability impact" }),
+        // ADR-011: heavy planning fields are optional for sketch slices; required for full slices.
+        successCriteria: Type.Optional(Type.String({ description: "Slice success criteria block (required for full slices; omit for sketches)" })),
+        proofLevel: Type.Optional(Type.String({ description: "Slice proof level (required for full slices; omit for sketches)" })),
+        integrationClosure: Type.Optional(Type.String({ description: "Slice integration closure (required for full slices; omit for sketches)" })),
+        observabilityImpact: Type.Optional(Type.String({ description: "Slice observability impact (required for full slices; omit for sketches)" })),
+        // ADR-011 sketch-then-refine fields.
+        isSketch: Type.Optional(Type.Boolean({ description: "ADR-011: true marks this slice as a sketch awaiting refine-slice expansion" })),
+        sketchScope: Type.Optional(Type.String({ description: "ADR-011: 2–3 sentence scope boundary, required when isSketch=true" })),
       }), { description: "Planned slices for the milestone" }),
       // ── Enrichment metadata (optional — defaults to empty) ────────────
       status: Type.Optional(Type.String({ description: "Milestone status (defaults to active)" })),
@@ -631,6 +635,20 @@ export function registerDbTools(pi: ExtensionAPI): void {
       keyFiles: Type.Optional(Type.Array(Type.String(), { description: "List of key files created or modified" })),
       keyDecisions: Type.Optional(Type.Array(Type.String(), { description: "List of key decisions made during this task" })),
       blockerDiscovered: Type.Optional(Type.Boolean({ description: "Whether a plan-invalidating blocker was discovered" })),
+      // ADR-011 Phase 2: mid-execution escalation — agent asks the user to resolve an ambiguity.
+      escalation: Type.Optional(Type.Object({
+        question: Type.String({ description: "The question the user needs to answer — one clear sentence." }),
+        options: Type.Array(Type.Object({
+          id: Type.String({ description: "Short id (e.g. 'A', 'B') used by /gsd escalate resolve." }),
+          label: Type.String({ description: "One-line label." }),
+          tradeoffs: Type.String({ description: "1-2 sentences on the tradeoffs of this option." }),
+        }), { minItems: 2, maxItems: 4, description: "2–4 options the user can choose between." }),
+        recommendation: Type.String({ description: "Option id the executor recommends." }),
+        recommendationRationale: Type.String({ description: "Why the recommendation — 1–2 sentences." }),
+        continueWithDefault: Type.Boolean({
+          description: "When true, loop continues (artifact logged for later review). When false, auto-mode pauses until the user resolves via /gsd escalate resolve.",
+        }),
+      }, { description: "ADR-011 Phase 2: optional escalation payload. Only honored when phases.mid_execution_escalation is true." })),
       verificationEvidence: Type.Optional(Type.Array(
         Type.Union([
           Type.Object({
@@ -758,32 +776,26 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     }
     try {
-      const { getSlice, updateSliceStatus } = await import("../gsd-db.js");
+      const { handleSkipSlice } = await import("../tools/skip-slice.js");
       const { invalidateStateCache } = await import("../state.js");
 
-      const slice = getSlice(params.milestoneId, params.sliceId);
-      if (!slice) {
-        return {
-          content: [{ type: "text" as const, text: `Error: Slice ${params.sliceId} not found in milestone ${params.milestoneId}` }],
-          details: { operation: "skip_slice", error: "slice_not_found" } as any,
-        };
-      }
+      const result = handleSkipSlice({
+        milestoneId: params.milestoneId,
+        sliceId: params.sliceId,
+        reason: params.reason,
+      });
 
-      if (slice.status === "complete" || slice.status === "done") {
+      if (result.error) {
         return {
-          content: [{ type: "text" as const, text: `Error: Slice ${params.sliceId} is already complete — cannot skip.` }],
-          details: { operation: "skip_slice", error: "already_complete" } as any,
+          content: [{ type: "text" as const, text: `Error: ${result.error}` }],
+          details: {
+            operation: "skip_slice",
+            error: result.error,
+            errorCode: result.errorCode ?? "skip_failed",
+          } as any,
         };
       }
 
-      if (slice.status === "skipped") {
-        return {
-          content: [{ type: "text" as const, text: `Slice ${params.sliceId} is already skipped.` }],
-          details: { operation: "skip_slice", sliceId: params.sliceId, milestoneId: params.milestoneId } as any,
-        };
-      }
-
-      updateSliceStatus(params.milestoneId, params.sliceId, "skipped");
       invalidateStateCache();
 
       // Rebuild STATE.md so it reflects the skip immediately (#3477).
@@ -796,13 +808,21 @@ export function registerDbTools(pi: ExtensionAPI): void {
         logError("tool", `skip_slice rebuildState failed: ${(err as Error).message}`, { tool: "gsd_skip_slice" });
       }
 
+      const suffix = result.wasAlreadySkipped
+        ? result.tasksSkipped > 0
+          ? ` (already skipped; cascaded ${result.tasksSkipped} leftover task(s) to skipped).`
+          : " (already skipped; no pending tasks to cascade)."
+        : ` Cascaded ${result.tasksSkipped} task(s) to skipped. Auto-mode will advance past this slice.`;
+
       return {
-        content: [{ type: "text" as const, text: `Skipped slice ${params.sliceId} (${params.milestoneId}). Reason: ${params.reason ?? "User-directed skip"}. Auto-mode will advance past this slice.` }],
+        content: [{ type: "text" as const, text: `Skipped slice ${params.sliceId} (${params.milestoneId}). Reason: ${params.reason ?? "User-directed skip"}.${suffix}` }],
         details: {
           operation: "skip_slice",
           sliceId: params.sliceId,
           milestoneId: params.milestoneId,
           reason: params.reason,
+          tasksSkipped: result.tasksSkipped,
+          wasAlreadySkipped: result.wasAlreadySkipped,
         } as any,
       };
     } catch (err) {
@@ -820,12 +840,14 @@ export function registerDbTools(pi: ExtensionAPI): void {
     label: "Skip Slice",
     description:
       "Mark a slice as skipped so auto-mode advances past it without executing. " +
+      "Non-closed tasks within the slice are cascaded to skipped so milestone completion is not blocked by leftover pending tasks (#4375). " +
       "The slice data is preserved for reference. The state machine treats skipped slices like completed ones for dependency satisfaction.",
     promptSnippet: "Skip a GSD slice (mark as skipped, auto-mode will advance past it)",
     promptGuidelines: [
       "Use gsd_skip_slice when a slice should be bypassed — descoped, superseded, or no longer relevant.",
       "Cannot skip a slice that is already complete.",
       "Skipped slices satisfy downstream dependencies just like completed slices.",
+      "All pending/active tasks in the slice are cascaded to skipped; completed tasks are never downgraded.",
     ],
     parameters: Type.Object({
       sliceId: Type.String({ description: "Slice ID (e.g. S02)" }),

package/src/resources/extensions/gsd/bootstrap/memory-tools.ts

@@ -0,0 +1,158 @@
+// GSD2 — Memory tool registration
+//
+// Exposes the memory-layer tools (capture_thought, memory_query, gsd_graph)
+// to the LLM over MCP. All three degrade gracefully when the GSD database
+// is unavailable.
+
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+
+import { ensureDbOpen } from "./dynamic-tools.js";
+import {
+  executeGsdGraph,
+  executeMemoryCapture,
+  executeMemoryQuery,
+} from "../tools/memory-tools.js";
+
+export function registerMemoryTools(pi: ExtensionAPI): void {
+  // ─── capture_thought ────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "capture_thought",
+    label: "Capture Thought",
+    description:
+      "Record a durable piece of project knowledge (decision, convention, gotcha, pattern, " +
+      "preference, or environment detail) into the GSD memory store. Use sparingly — one memory " +
+      "per genuinely reusable insight, not per task.",
+    promptSnippet:
+      "Capture a durable project insight into the GSD memory store (categories: architecture, convention, gotcha, pattern, preference, environment)",
+    promptGuidelines: [
+      "Use capture_thought for insights that will remain useful across future sessions.",
+      "Do NOT capture one-off bug fixes, temporary state, secrets, or task-specific details.",
+      "Keep content to 1–3 sentences.",
+      "Set confidence: 0.6 tentative, 0.8 solid, 0.95 well-confirmed (default 0.8).",
+    ],
+    parameters: Type.Object({
+      category: Type.Union(
+        [
+          Type.Literal("architecture"),
+          Type.Literal("convention"),
+          Type.Literal("gotcha"),
+          Type.Literal("preference"),
+          Type.Literal("environment"),
+          Type.Literal("pattern"),
+        ],
+        { description: "Memory category" },
+      ),
+      content: Type.String({ description: "The memory text (1–3 sentences, no secrets)" }),
+      confidence: Type.Optional(
+        Type.Number({ description: "0.1–0.99, default 0.8", minimum: 0.1, maximum: 0.99 }),
+      ),
+      tags: Type.Optional(Type.Array(Type.String(), { description: "Free-form tags (reserved for future use)" })),
+      scope: Type.Optional(Type.String({ description: "Scope name (reserved for future use; defaults to project)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const ok = await ensureDbOpen();
+      if (!ok) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot capture memory." }],
+          details: { operation: "memory_capture", error: "db_unavailable" },
+          isError: true,
+        };
+      }
+      return executeMemoryCapture(params as Parameters<typeof executeMemoryCapture>[0]);
+    },
+  });
+
+  // ─── memory_query ───────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "memory_query",
+    label: "Query Memory",
+    description:
+      "Search the GSD memory store for relevant memories. Phase 1 uses keyword matching ranked " +
+      "by confidence and reinforcement; future phases add semantic (embedding) retrieval.",
+    promptSnippet:
+      "Search the GSD memory store by keyword; returns ranked memories with id, category, and content",
+    promptGuidelines: [
+      "Use memory_query when you need durable project context that may not be in the current prompt.",
+      "Provide a short keyword-style query — not a full question.",
+      "Use category to narrow results to gotchas, conventions, architecture notes, etc.",
+    ],
+    parameters: Type.Object({
+      query: Type.String({ description: "Keyword query (2+ char terms)" }),
+      k: Type.Optional(Type.Number({ description: "Max results (default 10, max 50)", minimum: 1, maximum: 50 })),
+      category: Type.Optional(
+        Type.Union(
+          [
+            Type.Literal("architecture"),
+            Type.Literal("convention"),
+            Type.Literal("gotcha"),
+            Type.Literal("preference"),
+            Type.Literal("environment"),
+            Type.Literal("pattern"),
+          ],
+          { description: "Restrict results to a single category" },
+        ),
+      ),
+      scope: Type.Optional(Type.String({ description: "Only include memories with this scope (e.g. 'project', 'global')" })),
+      tag: Type.Optional(Type.String({ description: "Only include memories tagged with this value" })),
+      include_superseded: Type.Optional(Type.Boolean({ description: "Include superseded memories (default false)" })),
+      reinforce_hits: Type.Optional(
+        Type.Boolean({ description: "Increment hit_count on returned memories (default false)" }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const ok = await ensureDbOpen();
+      if (!ok) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot query memory." }],
+          details: { operation: "memory_query", error: "db_unavailable" },
+          isError: true,
+        };
+      }
+      return executeMemoryQuery(params as Parameters<typeof executeMemoryQuery>[0]);
+    },
+  });
+
+  // ─── gsd_graph ──────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "gsd_graph",
+    label: "GSD Knowledge Graph",
+    description:
+      "Inspect the relationship graph between memories. mode=query walks supersedes edges from a " +
+      "given memoryId; mode=build is a placeholder that future phases will use to rebuild graph " +
+      "edges from milestone LEARNINGS artifacts.",
+    promptSnippet: "Query the memory relationship graph or trigger a rebuild",
+    promptGuidelines: [
+      "Use mode=query with a memoryId when you want to see how a memory relates to others.",
+      "Phase 1 only exposes supersedes edges; additional relation types arrive in later phases.",
+    ],
+    parameters: Type.Object({
+      mode: Type.Union([Type.Literal("build"), Type.Literal("query")], {
+        description: "build = recompute graph (placeholder), query = inspect edges",
+      }),
+      memoryId: Type.Optional(Type.String({ description: "Memory ID (required when mode=query)" })),
+      depth: Type.Optional(Type.Number({ description: "Hops to traverse (0–5, default 1)", minimum: 0, maximum: 5 })),
+      rel: Type.Optional(Type.Union([
+        Type.Literal("related_to"),
+        Type.Literal("depends_on"),
+        Type.Literal("contradicts"),
+        Type.Literal("elaborates"),
+        Type.Literal("supersedes"),
+      ], { description: "Only include edges with this relation type" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const ok = await ensureDbOpen();
+      if (!ok) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available." }],
+          details: { operation: "gsd_graph", error: "db_unavailable" },
+          isError: true,
+        };
+      }
+      return executeGsdGraph(params as Parameters<typeof executeGsdGraph>[0]);
+    },
+  });
+}

package/src/resources/extensions/gsd/bootstrap/query-tools.ts

@@ -4,6 +4,7 @@ import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { ensureDbOpen } from "./dynamic-tools.js";
 import { executeMilestoneStatus } from "../tools/workflow-tool-executors.js";
+import { checkpointDatabase } from "../gsd-db.js";
 
 export function registerQueryTools(pi: ExtensionAPI): void {
   pi.registerTool({
@@ -31,4 +32,34 @@ export function registerQueryTools(pi: ExtensionAPI): void {
       return executeMilestoneStatus(params);
     },
   });
+
+  pi.registerTool({
+    name: "gsd_checkpoint_db",
+    label: "Checkpoint GSD Database",
+    description:
+      "Flush the SQLite WAL (Write-Ahead Log) into the base gsd.db file. " +
+      "Call this before `git add .gsd/gsd.db` to ensure the committed database " +
+      "contains current milestone/slice/task state rather than stale pre-session content. " +
+      "Safe to call at any time while GSD is running.",
+    promptSnippet: "Flush WAL into gsd.db so git add stages current state",
+    promptGuidelines: [
+      "Call gsd_checkpoint_db immediately before staging .gsd/gsd.db with git add.",
+      "Do not use sqlite3 or shell commands to checkpoint — they are blocked. Use this tool instead.",
+    ],
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+      const dbAvailable = await ensureDbOpen();
+      if (!dbAvailable) {
+        return {
+          content: [{ type: "text", text: "Error: GSD database is not available. Cannot checkpoint." }],
+          details: { operation: "checkpoint_db", error: "db_unavailable" },
+        };
+      }
+      checkpointDatabase();
+      return {
+        content: [{ type: "text", text: "WAL checkpoint complete. gsd.db is now up to date and safe to stage with git add." }],
+        details: { operation: "checkpoint_db", status: "ok" },
+      };
+    },
+  });
 }

package/src/resources/extensions/gsd/bootstrap/register-extension.ts

@@ -9,6 +9,7 @@ import { loadEcosystemExtensions } from "../ecosystem/loader.js";
 import { registerDbTools } from "./db-tools.js";
 import { registerDynamicTools } from "./dynamic-tools.js";
 import { registerJournalTools } from "./journal-tools.js";
+import { registerMemoryTools } from "./memory-tools.js";
 import { registerQueryTools } from "./query-tools.js";
 import { registerHooks } from "./register-hooks.js";
 import { registerShortcuts } from "./register-shortcuts.js";
@@ -85,6 +86,7 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
     ["db-tools", () => registerDbTools(pi)],
     ["journal-tools", () => registerJournalTools(pi)],
     ["query-tools", () => registerQueryTools(pi)],
+    ["memory-tools", () => registerMemoryTools(pi)],
     ["shortcuts", () => registerShortcuts(pi)],
     ["hooks", () => registerHooks(pi, ecosystemHandlers)],
     ["ecosystem", () => {