gsd-pi 2.76.0-dev.4100bd590 → 2.76.0-dev.479ad0e78

package/src/resources/extensions/gsd/token-counter.ts

@@ -22,7 +22,11 @@ async function getEncoder(): Promise<TokenEncoder | null> {
 	try {
 		// @ts-ignore — tiktoken may not have type declarations in extensions tsconfig
 		const tiktoken = await import("tiktoken");
-		encoder = tiktoken.encoding_for_model("gpt-4o") as TokenEncoder;
+		// Use cl100k_base — the most conservative and broadly compatible BPE encoding.
+		// It is shared by GPT-3.5/GPT-4 and gives a safer (larger) estimate than
+		// gpt-4o's o200k_base encoding, which produces fewer tokens for the same text
+		// and would cause context windows for non-OpenAI providers to be under-counted.
+		encoder = tiktoken.get_encoding("cl100k_base") as TokenEncoder;
 		return encoder;
 	} catch {
 		encoderFailed = true;
@@ -30,20 +34,33 @@ async function getEncoder(): Promise<TokenEncoder | null> {
 	}
 }
 
-export async function countTokens(text: string): Promise<number> {
+/**
+ * Count tokens in `text` using tiktoken (cl100k_base) when available.
+ *
+ * When tiktoken is not loaded, falls back to a provider-aware character-ratio
+ * estimate via `estimateTokensForProvider`. Passing `provider` is recommended
+ * so the heuristic fallback is as accurate as possible.
+ */
+export async function countTokens(text: string, provider?: TokenProvider): Promise<number> {
 	const enc = await getEncoder();
 	if (enc) {
 		const tokens = enc.encode(text);
 		return tokens.length;
 	}
-	return Math.ceil(text.length / 4);
+	return estimateTokensForProvider(text, provider ?? "unknown");
 }
 
-export function countTokensSync(text: string): number {
+/**
+ * Synchronous token count — only accurate after `initTokenCounter()` resolves.
+ *
+ * Before init, or when tiktoken is unavailable, falls back to a provider-aware
+ * character-ratio estimate. Passing `provider` is recommended.
+ */
+export function countTokensSync(text: string, provider?: TokenProvider): number {
 	if (encoder) {
 		return encoder.encode(text).length;
 	}
-	return Math.ceil(text.length / 4);
+	return estimateTokensForProvider(text, provider ?? "unknown");
 }
 
 export async function initTokenCounter(): Promise<boolean> {

package/src/resources/extensions/gsd/tools/complete-milestone.ts

@@ -7,7 +7,7 @@
  */
 
 import { join } from "node:path";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, existsSync } from "node:fs";
 
 import {
   transaction,
@@ -202,14 +202,20 @@ export async function handleCompleteMilestone(
     summaryPath = join(manualDir, `${params.milestoneId}-SUMMARY.md`);
   }
 
-  try {
-    await saveFile(summaryPath, summaryMd);
-  } catch (renderErr) {
-    // Disk render failed — roll back DB status so state stays consistent
-    logWarning("tool", `complete_milestone — disk render failed, rolling back DB status: ${(renderErr as Error).message}`);
-    updateMilestoneStatus(params.milestoneId, 'active', null);
-    invalidateStateCache();
-    return { error: `disk render failed: ${(renderErr as Error).message}` };
+  // Guard (#4598): if SUMMARY.md already exists on disk, do not overwrite it.
+  // This handles re-dispatch scenarios (DB/disk state divergence) where a prior
+  // completion already wrote the file. Overwriting would silently destroy the
+  // richer content the agent produced during the original completion run.
+  if (!existsSync(summaryPath)) {
+    try {
+      await saveFile(summaryPath, summaryMd);
+    } catch (renderErr) {
+      // Disk render failed — roll back DB status so state stays consistent
+      logWarning("tool", `complete_milestone — disk render failed, rolling back DB status: ${(renderErr as Error).message}`);
+      updateMilestoneStatus(params.milestoneId, 'active', null);
+      invalidateStateCache();
+      return { error: `disk render failed: ${(renderErr as Error).message}` };
+    }
   }
 
   // Invalidate all caches

package/src/resources/extensions/gsd/tools/exec-search-tool.ts

@@ -0,0 +1,81 @@
+// GSD Exec Search Tool — lists and filters prior gsd_exec runs.
+//
+// Scans .gsd/exec/*.meta.json and returns a ranked summary so agents can
+// re-discover past runs without re-executing. Read-only; no DB writes.
+
+import { searchExecHistory, type ExecSearchOptions } from "../exec-history.js";
+
+export interface ExecSearchToolParams {
+  query?: string;
+  runtime?: "bash" | "node" | "python";
+  failing_only?: boolean;
+  limit?: number;
+}
+
+export interface ToolExecutionResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+  isError?: boolean;
+}
+
+export function executeExecSearch(
+  params: ExecSearchToolParams,
+  opts: { baseDir: string },
+): ToolExecutionResult {
+  const searchOpts: ExecSearchOptions = {
+    query: typeof params.query === "string" ? params.query : undefined,
+    runtime: params.runtime,
+    failing_only: params.failing_only === true,
+    limit: typeof params.limit === "number" ? params.limit : undefined,
+  };
+  const hits = searchExecHistory(opts.baseDir, searchOpts);
+
+  if (hits.length === 0) {
+    return {
+      content: [{ type: "text", text: "No prior gsd_exec runs match those filters." }],
+      details: { operation: "gsd_exec_search", matches: 0 },
+    };
+  }
+
+  const lines: string[] = [`Found ${hits.length} exec run(s), most recent first:`];
+  for (const hit of hits) {
+    const e = hit.entry;
+    const status = formatStatus(e);
+    const purpose = e.purpose ? ` — ${e.purpose}` : "";
+    const truncated = e.stdout_truncated ? " (stdout truncated)" : "";
+    lines.push(
+      `- [${e.id}] ${e.runtime} ${status} ${e.duration_ms}ms${truncated}${purpose}`,
+      `    stdout: ${e.stdout_path}`,
+    );
+    if (hit.digest_preview) {
+      const preview = hit.digest_preview.replace(/\n/g, "\n      ");
+      lines.push(`    preview:\n      ${preview}`);
+    }
+  }
+
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    details: {
+      operation: "gsd_exec_search",
+      matches: hits.length,
+      results: hits.map((hit) => ({
+        id: hit.entry.id,
+        runtime: hit.entry.runtime,
+        exit_code: hit.entry.exit_code,
+        timed_out: hit.entry.timed_out,
+        duration_ms: hit.entry.duration_ms,
+        purpose: hit.entry.purpose,
+        stdout_path: hit.entry.stdout_path,
+        stderr_path: hit.entry.stderr_path,
+        meta_path: hit.entry.meta_path,
+      })),
+    },
+  };
+}
+
+function formatStatus(entry: { exit_code: number | null; timed_out: boolean; signal: string | null }): string {
+  if (entry.timed_out) return "timeout";
+  if (entry.signal) return `signal:${entry.signal}`;
+  if (entry.exit_code === null) return "exit:null";
+  return `exit:${entry.exit_code}`;
+}

package/src/resources/extensions/gsd/tools/exec-tool.ts

@@ -0,0 +1,183 @@
+// GSD Exec Tool — executor for the gsd_exec MCP tool.
+//
+// Thin wrapper around exec-sandbox.ts that reads effective options from
+// the project preferences (context_mode block) and formats the result
+// for MCP return.
+
+import {
+  EXEC_DEFAULTS,
+  runExecSandbox,
+  type ExecSandboxOptions,
+  type ExecSandboxRequest,
+  type ExecSandboxResult,
+} from "../exec-sandbox.js";
+import { isContextModeEnabled, type ContextModeConfig } from "../preferences-types.js";
+
+export interface ExecToolParams {
+  runtime: ExecSandboxRequest["runtime"];
+  script: string;
+  purpose?: string;
+  timeout_ms?: number;
+}
+
+export interface ToolExecutionResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+  isError?: boolean;
+}
+
+export interface ExecToolDeps {
+  baseDir: string;
+  preferences: { context_mode?: ContextModeConfig } | null;
+  /** Optional override for testing. */
+  run?: (req: ExecSandboxRequest, opts: ExecSandboxOptions) => Promise<ExecSandboxResult>;
+  now?: () => Date;
+  generateId?: () => string;
+}
+
+export function buildExecOptions(
+  baseDir: string,
+  cfg: ContextModeConfig | undefined,
+  extras?: Pick<ExecSandboxOptions, "env" | "now" | "generateId">,
+): ExecSandboxOptions {
+  const allowlist = Array.isArray(cfg?.exec_env_allowlist) ? cfg!.exec_env_allowlist! : EXEC_DEFAULTS.envAllowlist;
+  const stdoutCap = clampNumber(
+    cfg?.exec_stdout_cap_bytes,
+    EXEC_DEFAULTS.stdoutCapBytes,
+    4_096,
+    16_777_216,
+  );
+  const defaultTimeout = clampNumber(
+    cfg?.exec_timeout_ms,
+    EXEC_DEFAULTS.defaultTimeoutMs,
+    1_000,
+    EXEC_DEFAULTS.clampTimeoutMs,
+  );
+  const digestChars = clampNumber(cfg?.exec_digest_chars, EXEC_DEFAULTS.digestChars, 0, 4_000);
+  return {
+    baseDir,
+    clamp_timeout_ms: EXEC_DEFAULTS.clampTimeoutMs,
+    default_timeout_ms: defaultTimeout,
+    stdout_cap_bytes: stdoutCap,
+    stderr_cap_bytes: EXEC_DEFAULTS.stderrCapBytes,
+    digest_chars: digestChars,
+    env_allowlist: allowlist,
+    ...extras,
+  };
+}
+
+function clampNumber(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  if (value < min) return min;
+  if (value > max) return max;
+  return Math.floor(value);
+}
+
+function isEnabled(prefs: ExecToolDeps["preferences"]): boolean {
+  return isContextModeEnabled(prefs);
+}
+
+function disabledResult(): ToolExecutionResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text:
+          "gsd_exec is disabled by `context_mode.enabled: false` in preferences. Remove that " +
+          "override (or set it to true) to re-enable sandboxed tool-output execution.",
+      },
+    ],
+    details: { operation: "gsd_exec", error: "context_mode_disabled" },
+    isError: true,
+  };
+}
+
+function paramError(message: string): ToolExecutionResult {
+  return {
+    content: [{ type: "text", text: `Error: ${message}` }],
+    details: { operation: "gsd_exec", error: "invalid_params", detail: message },
+    isError: true,
+  };
+}
+
+export async function executeGsdExec(
+  params: ExecToolParams,
+  deps: ExecToolDeps,
+): Promise<ToolExecutionResult> {
+  if (!isEnabled(deps.preferences)) return disabledResult();
+
+  const runtime = params.runtime;
+  if (runtime !== "bash" && runtime !== "node" && runtime !== "python") {
+    return paramError(`invalid runtime "${String(runtime)}" — must be bash | node | python`);
+  }
+  const script = typeof params.script === "string" ? params.script : "";
+  if (script.trim().length === 0) {
+    return paramError("script is required and must be a non-empty string");
+  }
+  if (Buffer.byteLength(script, "utf8") > 200_000) {
+    return paramError("script exceeds the 200 KB length limit");
+  }
+
+  const opts = buildExecOptions(
+    deps.baseDir,
+    deps.preferences?.context_mode,
+    { now: deps.now, generateId: deps.generateId },
+  );
+  const run = deps.run ?? runExecSandbox;
+
+  try {
+    const result = await run(
+      {
+        runtime,
+        script,
+        ...(typeof params.purpose === "string" ? { purpose: params.purpose } : {}),
+        ...(typeof params.timeout_ms === "number" ? { timeout_ms: params.timeout_ms } : {}),
+      },
+      opts,
+    );
+    return formatResult(result);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text", text: `Error: gsd_exec failed — ${message}` }],
+      details: { operation: "gsd_exec", error: message },
+      isError: true,
+    };
+  }
+}
+
+function formatResult(result: ExecSandboxResult): ToolExecutionResult {
+  const headerLines = [
+    `gsd_exec[${result.id}] runtime=${result.runtime} exit=${formatExit(result)} duration=${result.duration_ms}ms`,
+    `  stdout: ${result.stdout_bytes}B${result.stdout_truncated ? " (truncated)" : ""} → ${result.stdout_path}`,
+    `  stderr: ${result.stderr_bytes}B${result.stderr_truncated ? " (truncated)" : ""} → ${result.stderr_path}`,
+  ];
+  const summary = `${headerLines.join("\n")}\n--- digest ---\n${result.digest}`.trimEnd();
+  return {
+    content: [{ type: "text", text: summary }],
+    details: {
+      operation: "gsd_exec",
+      id: result.id,
+      runtime: result.runtime,
+      exit_code: result.exit_code,
+      signal: result.signal,
+      timed_out: result.timed_out,
+      duration_ms: result.duration_ms,
+      stdout_bytes: result.stdout_bytes,
+      stderr_bytes: result.stderr_bytes,
+      stdout_truncated: result.stdout_truncated,
+      stderr_truncated: result.stderr_truncated,
+      stdout_path: result.stdout_path,
+      stderr_path: result.stderr_path,
+      meta_path: result.meta_path,
+    },
+    isError: result.timed_out || result.signal !== null || result.exit_code !== 0,
+  };
+}
+
+function formatExit(result: ExecSandboxResult): string {
+  if (result.timed_out) return "timeout";
+  if (result.signal) return `signal:${result.signal}`;
+  if (result.exit_code === null) return "null";
+  return String(result.exit_code);
+}

package/src/resources/extensions/gsd/tools/resume-tool.ts

@@ -0,0 +1,40 @@
+// GSD Resume Tool — returns the contents of .gsd/last-snapshot.md so
+// agents can re-orient after compaction or session resume without
+// re-deriving project memory state.
+
+import { readCompactionSnapshot } from "../compaction-snapshot.js";
+
+export interface ResumeToolParams {
+  /** Ignored — reserved for future variant (e.g. dated snapshots). */
+  _variant?: string;
+}
+
+export interface ToolExecutionResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+  isError?: boolean;
+}
+
+export function executeResume(
+  _params: ResumeToolParams,
+  opts: { baseDir: string },
+): ToolExecutionResult {
+  const snapshot = readCompactionSnapshot(opts.baseDir);
+  if (snapshot == null) {
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            "No snapshot found at .gsd/last-snapshot.md. The snapshot is written automatically " +
+            "on session_before_compact (enabled by default; set context_mode.enabled=false to opt out).",
+        },
+      ],
+      details: { operation: "gsd_resume", found: false },
+    };
+  }
+  return {
+    content: [{ type: "text", text: snapshot }],
+    details: { operation: "gsd_resume", found: true, bytes: Buffer.byteLength(snapshot, "utf-8") },
+  };
+}

package/src/resources/extensions/gsd/uok/plan-v2.ts

@@ -38,6 +38,29 @@ function hasFileContent(path: string | null): boolean {
   }
 }
 
+function getArtifactLookupBases(basePath: string): string[] {
+  const bases = [basePath];
+  const projectRoot = process.env.GSD_PROJECT_ROOT;
+  if (projectRoot && projectRoot.trim().length > 0 && projectRoot !== basePath) {
+    bases.push(projectRoot);
+  }
+  return bases;
+}
+
+function hasMilestoneFileContent(
+  basePath: string,
+  milestoneId: string,
+  suffix: string,
+): boolean {
+  const bases = getArtifactLookupBases(basePath);
+  for (const candidateBase of bases) {
+    if (hasFileContent(resolveMilestoneFile(candidateBase, milestoneId, suffix))) {
+      return true;
+    }
+  }
+  return false;
+}
+
 function countSliceResearchArtifacts(basePath: string, milestoneId: string, slices: SliceRow[]): number {
   let count = 0;
   for (const slice of slices) {
@@ -60,9 +83,9 @@ export function compileUnitGraphFromState(basePath: string, state: GSDState): Pl
   const slices = getMilestoneSlices(mid).sort((a, b) => Number(a.sequence ?? 0) - Number(b.sequence ?? 0));
   const nodes: UokGraphNode[] = [];
   const clarifyRoundLimit = PLAN_V2_CLARIFY_ROUND_LIMIT;
-  const draftContextIncluded = hasFileContent(resolveMilestoneFile(basePath, mid, "CONTEXT-DRAFT"));
-  const finalizedContextIncluded = hasFileContent(resolveMilestoneFile(basePath, mid, "CONTEXT"));
-  const researchSynthesized = hasFileContent(resolveMilestoneFile(basePath, mid, "RESEARCH"))
+  const draftContextIncluded = hasMilestoneFileContent(basePath, mid, "CONTEXT-DRAFT");
+  const finalizedContextIncluded = hasMilestoneFileContent(basePath, mid, "CONTEXT");
+  const researchSynthesized = hasMilestoneFileContent(basePath, mid, "RESEARCH")
     || countSliceResearchArtifacts(basePath, mid, slices) > 0;
 
   if (isExecutionEntryPhase(state.phase) && !finalizedContextIncluded) {

package/src/resources/extensions/gsd/workflow-logger.ts

@@ -57,7 +57,9 @@ export type LogComponent =
   | "ecosystem"     // GSD ecosystem extension loader and dispatch
   | "memory-embeddings" // Memory layer embedding generation
   | "memory-ingest"     // Memory layer ingestion pipeline
-  | "memory-backfill";  // ADR-013: decisions->memories backfill
+  | "memory-backfill"   // ADR-013: decisions->memories backfill
+  | "context-mode"     // Context-mode exec sandbox and compaction snapshot
+  | "preflight";       // Clean-root preflight gate at milestone completion
 
 export interface LogEntry {
   ts: string;

package/src/resources/extensions/gsd/workflow-mcp.ts

@@ -23,6 +23,9 @@ export interface WorkflowCapabilityOptions {
 const MCP_WORKFLOW_TOOL_SURFACE = new Set([
   "ask_user_questions",
   "gsd_decision_save",
+  "gsd_exec",
+  "gsd_exec_search",
+  "gsd_resume",
   "gsd_complete_milestone",
   "gsd_complete_task",
   "gsd_complete_slice",

package/src/resources/extensions/gsd/worktree-resolver.ts

@@ -79,6 +79,35 @@ export interface NotifyCtx {
   ) => void;
 }
 
+// ─── Path Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Worktree marker segment — present in any path produced by worktreePath().
+ * Used to strip the worktree suffix and recover the project root (#3729).
+ */
+const WORKTREE_MARKER = "/.gsd/worktrees/";
+
+/**
+ * Resolve the project root from session path state.
+ *
+ * Prefers `originalBasePath` (always the project root when set), but falls
+ * back to `basePath` when `originalBasePath` is falsy (e.g. fresh AutoSession
+ * with default empty string). If `basePath` itself is inside a worktree
+ * directory (contains `/.gsd/worktrees/`), strip that suffix to recover the
+ * actual project root — preventing double-nested worktree paths (#3729).
+ */
+export function resolveProjectRoot(
+  originalBasePath: string,
+  basePath: string,
+): string {
+  let resolved = originalBasePath || basePath;
+  const markerIdx = resolved.indexOf(WORKTREE_MARKER);
+  if (markerIdx !== -1) {
+    resolved = resolved.slice(0, markerIdx);
+  }
+  return resolved;
+}
+
 // ─── WorktreeResolver ──────────────────────────────────────────────────────
 
 export class WorktreeResolver {
@@ -99,12 +128,12 @@ export class WorktreeResolver {
 
   /** Original project root — always the non-worktree path. */
   get projectRoot(): string {
-    return this.s.originalBasePath || this.s.basePath;
+    return resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
   }
 
   /** Path for auto.lock file — same as the old lockBase(). */
   get lockPath(): string {
-    return this.s.originalBasePath || this.s.basePath;
+    return resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
   }
 
   // ── Private Helpers ────────────────────────────────────────────────────
@@ -182,7 +211,10 @@ export class WorktreeResolver {
       return;
     }
 
-    const basePath = this.s.originalBasePath || this.s.basePath;
+    // Resolve the project root for worktree operations via shared helper.
+    // Handles the case where originalBasePath is falsy and basePath is itself
+    // a worktree path — prevents double-nested worktree paths (#3729).
+    const basePath = resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
     debugLog("WorktreeResolver", {
       action: "enterMilestone",
       milestoneId,
@@ -569,11 +601,13 @@ export class WorktreeResolver {
         }
       }
 
-      // Re-throw MergeConflictError so the auto loop can detect real code
-      // conflicts and stop instead of retrying forever (#2330).
-      if (err instanceof MergeConflictError) {
-        throw err;
-      }
+      // Restore state before re-throwing so callers always get a consistent
+      // session (#4380).
+      this.restoreToProjectRoot();
+      // Re-throw: MergeConflictError stops the auto loop (#2330); non-conflict
+      // errors (permission denied, filesystem failures) must also propagate so
+      // broken states are diagnosable (#4380).
+      throw err;
     }
 
     // Always restore basePath and rebuild — whether merge succeeded or failed
@@ -659,6 +693,8 @@ export class WorktreeResolver {
         error: msg,
       });
       ctx.notify(`Milestone merge failed (branch mode): ${msg}`, "warning");
+      // Re-throw all errors so callers can apply their own recovery logic (#4380).
+      throw err;
     }
   }
 
@@ -681,7 +717,16 @@ export class WorktreeResolver {
       currentMilestoneId,
       nextMilestoneId,
     });
-    this.mergeAndExit(currentMilestoneId, ctx);
+    try {
+      this.mergeAndExit(currentMilestoneId, ctx);
+    } catch (err) {
+      // mergeAndExit emits a warning and restores state when it fails during
+      // merge/cleanup. But if it throws before recovery runs (e.g., in
+      // validateMilestoneId or emitJournalEvent), basePath won't be restored
+      // to projectRoot — re-throw so we don't enter the next milestone with
+      // the current one unmerged.
+      if (this.s.basePath !== this.projectRoot) throw err;
+    }
     this.enterMilestone(nextMilestoneId, ctx);
   }
 }

package/src/resources/skills/verify-before-complete/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: verify-before-complete
-description: Block completion claims until verification evidence has been produced in the current message. Use before marking a task/slice/milestone complete, before creating a commit or PR, before saying "it works" or "tests pass", and any time you are about to claim work is done. The rule is: evidence before claims, always — running the verification must happen now, not "earlier in the session". Fresh output or no claim.
+description: >-
+  Block completion claims until verification evidence has been produced in the current message. Use before marking a task/slice/milestone complete, before creating a commit or PR, before saying "it works" or "tests pass", and any time you are about to claim work is done. The rule is: evidence before claims, always — running the verification must happen now, not "earlier in the session". Fresh output or no claim.
 ---
 
 <objective>

package/src/resources/skills/write-docs/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: write-docs
-description: Collaborative document authoring workflow for proposals, technical specs, decision docs, README sections, ADRs, and long-form prose that must work for fresh readers. Use when asked to "write the docs", "draft a proposal", "write a spec", "write an RFC", "write the README", or when a document needs to be understandable by someone without this session's context. Three stages: gather context, iterate on structure, reader-test for a stranger.
+description: >-
+  Collaborative document authoring workflow for proposals, technical specs, decision docs, README sections, ADRs, and long-form prose that must work for fresh readers. Use when asked to "write the docs", "draft a proposal", "write a spec", "write an RFC", "write the README", or when a document needs to be understandable by someone without this session's context. Three stages: gather context, iterate on structure, reader-test for a stranger.
 ---
 
 <objective>