gsd-pi 2.78.1-dev.b6a389b66 → 2.78.1-dev.d8826a445

package/src/resources/extensions/gsd/delegation-policy.ts

@@ -0,0 +1,197 @@
+// Delegation policy — codifies which GSD MCP tools are safe to run as
+// background sub-agents while the foreground /gsd flow continues. Verdicts
+// are derived from the round-1 and round-2 evaluations recorded in this
+// branch's PR description; the rationale field on each entry preserves
+// the reason so future changes have to revisit the analysis explicitly.
+//
+// Default-deny: unknown tools are never backgroundable.
+//
+// ─── Tool-name vs unit-type namespaces ───────────────────────────────────
+// Entries are keyed by canonical MCP tool name (`gsd_*`). The optional
+// `unitType` field is a *secondary* index for the dispatcher's convenience
+// — it bridges this policy to `auto-dispatch.ts`' `DispatchAction.unitType`
+// values. The two namespaces are not 1:1:
+//
+//   - Some tools have no corresponding unit type (e.g. `gsd_doctor`,
+//     `gsd_plan_task`) and intentionally omit `unitType`.
+//   - Some unit types share a tool — e.g. `execute-task`, `execute-task-simple`,
+//     and `reactive-execute` all invoke `gsd_execute`. The current shape
+//     allows only one `unitType` per entry, so those units fall through to
+//     `getVerdictByUnitType() === null` (→ `backgroundable: false`) even
+//     though `gsd_execute` itself is GOOD. This is the intended default-deny
+//     posture until a future PR wires actual background dispatch and
+//     decides whether each unit-level orchestration is safe — the unit
+//     wraps a prompt, harness setup, and post-processing on top of the
+//     tool, and the tool's safety doesn't transfer automatically.
+//
+// Auto-dispatch produces 20 distinct unit types; only 5 are explicitly
+// classified here. The other 15 default-deny:
+//   complete-milestone, complete-slice, discuss-milestone, discuss-project,
+//   discuss-requirements, execute-task, execute-task-simple, gate-evaluate,
+//   reactive-execute, refine-slice, research-decision, research-milestone,
+//   research-project, research-slice, rewrite-docs, run-uat
+//
+// Adding a `unitType` mapping (or a future `unitTypes: string[]`) to an
+// existing entry is the place to lift any of these out of default-deny
+// when the analysis has been done.
+
+export type BackgroundabilityVerdict = "good" | "risky" | "no";
+
+export interface DelegationPolicyEntry {
+  /** Canonical MCP tool name (the verb_object form, e.g. `gsd_plan_slice`). */
+  toolName: string;
+  /** Workflow unit type from auto-dispatch.ts, when one exists. */
+  unitType?: string;
+  verdict: BackgroundabilityVerdict;
+  /** One-line justification grounded in the evaluation findings. */
+  rationale: string;
+  /**
+   * Constraints the caller MUST satisfy when dispatching this unit in the
+   * background. Only populated for `good` and conditional `risky` entries.
+   */
+  constraints?: string[];
+}
+
+const POLICY: Record<string, DelegationPolicyEntry> = {
+  gsd_plan_slice: {
+    toolName: "gsd_plan_slice",
+    unitType: "plan-slice",
+    verdict: "good",
+    rationale:
+      "Self-contained, no user prompts, atomic DB tx; existing slice-parallel-orchestrator pattern transfers cleanly.",
+    constraints: [
+      "Lock the slice from further user discussion once dispatched (context is frozen at dispatch time).",
+      "Foreground must not derive state for that slice while the transaction is in flight.",
+      "Foreground must await background completion before any tool reads the planned tasks/gates.",
+    ],
+  },
+  gsd_execute: {
+    toolName: "gsd_execute",
+    // No `unitType` set on purpose — the underlying tool is safe, but the
+    // unit-level orchestrations that invoke it (`execute-task`,
+    // `execute-task-simple`, `reactive-execute`) wrap additional prompt and
+    // harness work whose safety is a separate analysis. Default-deny those
+    // units until that analysis is recorded; adding `unitType` here would
+    // promote them silently.
+    verdict: "good",
+    rationale:
+      "No DB writes; UUID-isolated stdout/stderr/meta files; existing reactive-execute parallel-subagent precedent.",
+  },
+  gsd_validate_milestone: {
+    toolName: "gsd_validate_milestone",
+    unitType: "validate-milestone",
+    verdict: "good",
+    rationale:
+      "Verdict pre-computed by parallel reviewers; atomic DB tx plus isolated VALIDATION.md write; no user interaction.",
+  },
+  gsd_reassess_roadmap: {
+    toolName: "gsd_reassess_roadmap",
+    unitType: "reassess-roadmap",
+    verdict: "good",
+    rationale:
+      "Narrower mutation scope than plan_milestone; structural guards prevent modification of completed slices.",
+  },
+  gsd_doctor: {
+    toolName: "gsd_doctor",
+    verdict: "risky",
+    rationale:
+      "Diagnostic-only mode (fix=false) is safe to background; fix=true writes STATE.md/ROADMAP.md without session-lock coordination and can race the foreground flow.",
+    constraints: [
+      "Background only with fix=false (diagnostic-only).",
+      "Apply fixes synchronously, only when no foreground unit is dispatched.",
+    ],
+  },
+  gsd_plan_milestone: {
+    toolName: "gsd_plan_milestone",
+    unitType: "plan-milestone",
+    verdict: "risky",
+    rationale:
+      "Inputs require CONTEXT.md from discuss-milestone, so initial questioning is already done by the time it can start; TOCTOU guards and projection coherence make concurrency unsafe.",
+  },
+  gsd_replan_slice: {
+    toolName: "gsd_replan_slice",
+    unitType: "replan-slice",
+    verdict: "risky",
+    rationale:
+      "Blocks the replanning→executing state transition on a gate that waits for S##-REPLAN.md; background failure leaves the flow stuck.",
+  },
+  gsd_plan_task: {
+    toolName: "gsd_plan_task",
+    verdict: "no",
+    rationale:
+      "plan-slice prompt explicitly forbids calling gsd_plan_task separately; per-task granularity multiplies manifest writes and projection re-renders with no payoff.",
+  },
+};
+
+// Alias map keyed on the secondary name; resolves to the canonical entry above.
+// Sourced from packages/mcp-server/src/workflow-tools.ts alias registrations
+// (gsd_milestone_validate, gsd_roadmap_reassess, gsd_slice_replan, gsd_task_plan).
+const ALIASES: Record<string, string> = {
+  gsd_milestone_validate: "gsd_validate_milestone",
+  gsd_roadmap_reassess: "gsd_reassess_roadmap",
+  gsd_slice_replan: "gsd_replan_slice",
+  gsd_task_plan: "gsd_plan_task",
+};
+
+function resolveCanonical(name: string): string {
+  return ALIASES[name] ?? name;
+}
+
+export function getDelegationVerdict(toolName: string): DelegationPolicyEntry | null {
+  return POLICY[resolveCanonical(toolName)] ?? null;
+}
+
+export function isBackgroundable(toolName: string): boolean {
+  const entry = getDelegationVerdict(toolName);
+  return entry?.verdict === "good";
+}
+
+export function listBackgroundableTools(): string[] {
+  return Object.values(POLICY)
+    .filter((entry) => entry.verdict === "good")
+    .map((entry) => entry.toolName)
+    .sort();
+}
+
+export function getVerdictByUnitType(unitType: string): DelegationPolicyEntry | null {
+  for (const entry of Object.values(POLICY)) {
+    if (entry.unitType === unitType) return entry;
+  }
+  return null;
+}
+
+/**
+ * Minimal shape of a dispatch action that the annotator needs to operate on.
+ * Matches the `dispatch` and non-dispatch variants of auto-dispatch.ts'
+ * DispatchAction without depending on it (so this module stays free of
+ * workspace-package transitive imports).
+ */
+export type AnnotatableDispatchAction =
+  | { action: "dispatch"; unitType: string; backgroundable?: boolean; [k: string]: unknown }
+  | { action: "stop"; [k: string]: unknown }
+  | { action: "skip"; [k: string]: unknown };
+
+/**
+ * Annotates a dispatch action in place with `backgroundable: true` when its
+ * unitType has a `good` verdict in the policy. Stop/skip actions pass through
+ * unchanged. Default-deny: unknown unit types resolve to `false`.
+ *
+ * **Mutation contract.** The `backgroundable` field is written directly onto
+ * the passed action object. This is intentional — every dispatch path in
+ * `auto-dispatch.ts` constructs a fresh action object per `where(ctx)` /
+ * `evaluateDispatch(ctx)` invocation, so in-place mutation cannot leak across
+ * dispatch cycles. Future dispatch rules MUST follow that convention: never
+ * cache or share `DispatchAction` objects across calls. If you need to cache,
+ * either freeze the cached object (`Object.freeze`) and clone on read, or
+ * stop calling `annotateBackgroundable` on the shared instance. The annotator
+ * always recomputes from the policy on every call (no internal cache), so
+ * repeated invocations on the same object will overwrite stale values
+ * deterministically — see the `annotateBackgroundable recomputes on each call`
+ * test for the contract pin.
+ */
+export function annotateBackgroundable<T extends AnnotatableDispatchAction>(action: T): T {
+  if (action.action !== "dispatch") return action;
+  const verdict = getVerdictByUnitType(action.unitType);
+  action.backgroundable = verdict?.verdict === "good";
+  return action;
+}

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

@@ -25,6 +25,7 @@ import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
 import { dirname } from "node:path";
 import type { Decision, Requirement, GateRow, GateId, GateScope, GateStatus, GateVerdict } from "./types.js";
 import { GSDError, GSD_STALE_STATE } from "./errors.js";
+import type { GsdWorkspace, MilestoneScope } from "./workspace.js";
 import { getGateIdsForTurn, type OwnerTurn } from "./gate-registry.js";
 import { logError, logWarning } from "./workflow-logger.js";
 // Type-only import to avoid a circular runtime dep. The runtime side of
@@ -1259,6 +1260,182 @@ let _exitHandlerRegistered = false;
 let _dbOpenAttempted = false;
 let _lastDbError: Error | null = null;
 let _lastDbPhase: "open" | "initSchema" | "vacuum-recovery" | null = null;
+/**
+ * Identity key of the workspace whose connection is currently active
+ * (currentDb). Set by openDatabaseByWorkspace(); null when the active
+ * connection was opened via the legacy openDatabase(path) path.
+ */
+let _currentIdentityKey: string | null = null;
+
+/**
+ * Workspace-scoped connection cache.
+ * Key: GsdWorkspace.identityKey (realpath-normalized project root).
+ * Value: the DB path and open adapter for that workspace.
+ *
+ * Sibling worktrees of the same project share the same identityKey (set by
+ * createWorkspace) and therefore reuse the same cached connection, preserving
+ * shared-WAL semantics. Different projects get distinct cache entries.
+ *
+ * NOTE: Only one connection is "active" at a time (currentDb/currentPath).
+ * The cache allows fast re-activation of a previously opened connection when
+ * callers switch between known workspaces via openDatabaseByWorkspace().
+ */
+const _dbCache = new Map<string, { dbPath: string; db: DbAdapter }>();
+
+/** Test helper: expose the internal cache for inspection. Not for production use. */
+export function _getDbCache(): ReadonlyMap<string, { dbPath: string; db: DbAdapter }> {
+  return _dbCache;
+}
+
+/**
+ * Close and evict every entry in the workspace connection cache, then call
+ * closeDatabase() to close the active connection.
+ *
+ * Use this for test teardown or process-shutdown paths where every open
+ * connection must be flushed. Normal callers should use closeDatabase() or
+ * closeDatabaseByWorkspace() instead.
+ */
+export function closeAllDatabases(): void {
+  // Close all non-active cached connections first.
+  for (const [key, entry] of _dbCache) {
+    if (entry.db === currentDb) continue; // handled by closeDatabase() below
+    _dbCache.delete(key);
+    try { entry.db.exec("PRAGMA wal_checkpoint(TRUNCATE)"); } catch { /* best-effort */ }
+    try { entry.db.exec("PRAGMA incremental_vacuum(64)"); } catch { /* best-effort */ }
+    try { entry.db.close(); } catch { /* best-effort */ }
+  }
+  closeDatabase();
+}
+
+/**
+ * Open (or reuse) the database connection scoped to the given workspace.
+ *
+ * Uses workspace.identityKey as the cache key, so sibling worktrees of the
+ * same project resolve to the same connection. On a cache hit the existing
+ * adapter is reactivated as the current connection without re-opening the
+ * file. On a cache miss, delegates to openDatabase() for the full
+ * open + schema-init + migration flow, then caches the result.
+ *
+ * When switching to a different workspace, the previously active connection
+ * is preserved in the cache (not closed), so callers can switch back to it
+ * cheaply via a subsequent openDatabaseByWorkspace() call.
+ *
+ * @param workspace A GsdWorkspace created by createWorkspace().
+ * @returns true if the connection is open and ready, false otherwise.
+ */
+export function openDatabaseByWorkspace(workspace: GsdWorkspace): boolean {
+  const key = workspace.identityKey;
+  const dbPath = workspace.contract.projectDb;
+
+  const cached = _dbCache.get(key);
+  if (cached) {
+    // Reactivate the cached connection as the current singleton.
+    currentDb = cached.db;
+    currentPath = cached.dbPath;
+    currentPid = process.pid;
+    _dbOpenAttempted = true;
+    _currentIdentityKey = key;
+    return true;
+  }
+
+  // Cache miss — need to open a new connection.
+  //
+  // If there is a currently active workspace connection, stash it in the
+  // cache under its identity key before calling openDatabase(), because
+  // openDatabase() will call closeDatabase() when the path changes (which
+  // would destroy the existing adapter). By nulling out currentDb first,
+  // we prevent openDatabase() from closing the live adapter.
+  let oldDb: typeof currentDb = null;
+  let oldPath: typeof currentPath = null;
+  let oldPid: typeof currentPid = 0;
+  let oldKey: typeof _currentIdentityKey = null;
+
+  if (currentDb !== null && _currentIdentityKey !== null) {
+    // Snapshot the old globals so we can restore them on failure.
+    oldDb = currentDb;
+    oldPath = currentPath;
+    oldPid = currentPid;
+    oldKey = _currentIdentityKey;
+    // Save the current connection so it stays alive in the cache.
+    _dbCache.set(_currentIdentityKey, {
+      dbPath: currentPath!,
+      db: currentDb,
+    });
+    // Detach from globals so openDatabase() opens fresh without closing it.
+    currentDb = null;
+    currentPath = null;
+    currentPid = 0;
+    _currentIdentityKey = null;
+  }
+
+  // Run the full open/schema/migration flow for the new workspace.
+  // openDatabase() can throw on corrupt DB or permission error — catch so we
+  // can restore the previous connection rather than leaving globals null.
+  let opened: boolean;
+  try {
+    opened = openDatabase(dbPath);
+  } catch (err) {
+    // Failed to open the new DB. Restore the previous workspace connection so
+    // the caller's workspace remains active (it is still safe in _dbCache).
+    if (oldDb !== null) {
+      currentDb = oldDb;
+      currentPath = oldPath;
+      currentPid = oldPid;
+      _currentIdentityKey = oldKey;
+    }
+    throw err;
+  }
+  if (opened && currentDb) {
+    _dbCache.set(key, { dbPath, db: currentDb });
+    _currentIdentityKey = key;
+  } else if (!opened && oldDb !== null) {
+    // Restore the previous connection so the caller's workspace remains active.
+    // The failed attempt left no live adapter, so the globals stayed null.
+    currentDb = oldDb;
+    currentPath = oldPath;
+    currentPid = oldPid;
+    _currentIdentityKey = oldKey;
+  }
+  return opened;
+}
+
+/**
+ * Open (or reuse) the database connection scoped to the workspace in a
+ * MilestoneScope. Thin delegation to openDatabaseByWorkspace().
+ */
+export function openDatabaseByScope(scope: MilestoneScope): boolean {
+  return openDatabaseByWorkspace(scope.workspace);
+}
+
+/**
+ * Close the database connection for the given workspace and remove it from
+ * the cache. If the workspace's connection is currently active (currentDb),
+ * performs a full closeDatabase() including WAL checkpoint. Otherwise only
+ * removes the cache entry (the adapter was already replaced by a later open).
+ */
+export function closeDatabaseByWorkspace(workspace: GsdWorkspace): void {
+  const key = workspace.identityKey;
+  const cached = _dbCache.get(key);
+  if (!cached) return;
+
+  _dbCache.delete(key);
+
+  if (currentDb === cached.db) {
+    // This workspace's connection is the active one — full close.
+    closeDatabase();
+  } else {
+    // Connection was displaced by a later open; close the adapter directly.
+    try {
+      cached.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    } catch (e) { logWarning("db", `WAL checkpoint (byWorkspace) failed: ${(e as Error).message}`); }
+    try {
+      cached.db.exec("PRAGMA incremental_vacuum(64)");
+    } catch (e) { logWarning("db", `incremental vacuum (byWorkspace) failed: ${(e as Error).message}`); }
+    try {
+      cached.db.close();
+    } catch (e) { logWarning("db", `database close (byWorkspace) failed: ${(e as Error).message}`); }
+  }
+}
 
 export function getDbProvider(): ProviderName | null {
   loadProvider();
@@ -1389,6 +1566,13 @@ export function closeDatabase(): void {
     try {
       currentDb.close();
     } catch (e) { logWarning("db", `database close failed: ${(e as Error).message}`); }
+    // If this connection was workspace-tracked, evict it from the cache so
+    // subsequent openDatabaseByWorkspace() calls re-open rather than reactivate
+    // a closed adapter.
+    if (_currentIdentityKey !== null) {
+      _dbCache.delete(_currentIdentityKey);
+      _currentIdentityKey = null;
+    }
     currentDb = null;
     currentPath = null;
     currentPid = 0;

package/src/resources/extensions/gsd/guided-flow-queue.ts

@@ -194,7 +194,7 @@ export async function showQueueAdd(
 
   // ── Dispatch the queue prompt ───────────────────────────────────────
   // Activate the queue phase so the write-gate applies to CONTEXT.md writes
-  setQueuePhaseActive(true);
+  setQueuePhaseActive(true, basePath);
 
   const queueInlinedTemplates = inlineTemplate("context", "Context");
   const prompt = loadPrompt("queue", {