gsd-pi 2.76.0 → 2.77.0-dev.2daa994b6

package/src/resources/extensions/gsd/exec-sandbox.ts

@@ -0,0 +1,326 @@
+// GSD Exec Sandbox — tool-output sandboxing for sub-sessions.
+//
+// Runs a script in a subprocess and persists stdout/stderr to
+// `.gsd/exec/<id>.{stdout,stderr,meta.json}`. Only a short digest is
+// returned to the calling agent's context, keeping large outputs
+// (e.g. Playwright snapshots, issue dumps) out of the window.
+//
+// Inspired by mksglu/context-mode (Elastic License 2.0). Independent
+// implementation — no upstream code incorporated.
+
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+
+export interface ExecSandboxRequest {
+  /** Interpreter to use. */
+  runtime: "bash" | "node" | "python";
+  /** Script body. Executed via the runtime's -c equivalent. */
+  script: string;
+  /** Optional purpose/label recorded in meta.json. */
+  purpose?: string;
+  /** Per-invocation timeout in ms. Clamped to `clamp_timeout_ms`. */
+  timeout_ms?: number;
+}
+
+export interface ExecSandboxOptions {
+  /** Project root. stdout/stderr persist under `<baseDir>/.gsd/exec/`. */
+  baseDir: string;
+  /** Absolute upper bound for the timeout. */
+  clamp_timeout_ms: number;
+  /** Default timeout if request omits one. */
+  default_timeout_ms: number;
+  /** Cap on persisted stdout bytes. Further output is truncated with a marker. */
+  stdout_cap_bytes: number;
+  /** Cap on persisted stderr bytes. */
+  stderr_cap_bytes: number;
+  /** Number of trailing stdout chars returned as the digest. */
+  digest_chars: number;
+  /** Env var allowlist (case-sensitive). PATH/HOME always forwarded. */
+  env_allowlist: readonly string[];
+  /** Optional override of process.env for tests. */
+  env?: NodeJS.ProcessEnv;
+  /** Optional override for the current time (tests). */
+  now?: () => Date;
+  /** Optional override for id generation (tests). */
+  generateId?: () => string;
+}
+
+export interface ExecSandboxResult {
+  id: string;
+  runtime: ExecSandboxRequest["runtime"];
+  exit_code: number | null;
+  signal: NodeJS.Signals | null;
+  timed_out: boolean;
+  duration_ms: number;
+  stdout_bytes: number;
+  stderr_bytes: number;
+  stdout_truncated: boolean;
+  stderr_truncated: boolean;
+  stdout_path: string;
+  stderr_path: string;
+  meta_path: string;
+  digest: string;
+}
+
+const ALWAYS_FORWARD_ENV = ["PATH", "HOME"] as const;
+
+export const EXEC_DEFAULTS = {
+  clampTimeoutMs: 600_000,
+  defaultTimeoutMs: 30_000,
+  stdoutCapBytes: 1_048_576,
+  stderrCapBytes: 262_144,
+  digestChars: 300,
+  envAllowlist: [
+    "LANG",
+    "LC_ALL",
+    "TERM",
+    "TZ",
+    "SHELL",
+    "USER",
+    "LOGNAME",
+    "TMPDIR",
+    "NODE_OPTIONS",
+    "PYTHONPATH",
+    "PYTHONIOENCODING",
+  ] as const,
+} as const;
+
+function buildChildEnv(opts: ExecSandboxOptions): NodeJS.ProcessEnv {
+  const source = opts.env ?? process.env;
+  const out: NodeJS.ProcessEnv = {};
+  const allowed = new Set<string>([...ALWAYS_FORWARD_ENV, ...opts.env_allowlist]);
+  for (const key of allowed) {
+    const value = source[key];
+    if (typeof value === "string") out[key] = value;
+  }
+  return out;
+}
+
+function clampTimeout(request: ExecSandboxRequest, opts: ExecSandboxOptions): number {
+  const requested = typeof request.timeout_ms === "number" && Number.isFinite(request.timeout_ms)
+    ? Math.floor(request.timeout_ms)
+    : opts.default_timeout_ms;
+  if (requested < 1) return 1;
+  if (requested > opts.clamp_timeout_ms) return opts.clamp_timeout_ms;
+  return requested;
+}
+
+function resolveCommand(runtime: ExecSandboxRequest["runtime"]): { cmd: string; args: string[] } {
+  switch (runtime) {
+    case "bash":
+      return { cmd: "bash", args: ["-c"] };
+    case "node":
+      return { cmd: process.execPath, args: ["-e"] };
+    case "python":
+      return { cmd: "python3", args: ["-c"] };
+  }
+}
+
+function tail(buf: Buffer, chars: number): string {
+  if (chars <= 0) return "";
+  const text = buf.toString("utf-8");
+  return text.length <= chars ? text : text.slice(text.length - chars);
+}
+
+/**
+ * Run a script in a subprocess, capture stdout/stderr to files under
+ * `.gsd/exec/<id>.{stdout,stderr,meta.json}`, and return an `ExecSandboxResult`
+ * containing the digest plus metadata.
+ *
+ * Errors from spawn failures resolve (not reject) with `exit_code=null`.
+ * The function is pure with respect to its inputs — no global state beyond
+ * filesystem writes under `baseDir`.
+ */
+export function runExecSandbox(
+  request: ExecSandboxRequest,
+  opts: ExecSandboxOptions,
+): Promise<ExecSandboxResult> {
+  return new Promise((resolveP) => {
+    const id = (opts.generateId ?? defaultGenerateId)();
+    const now = (opts.now ?? (() => new Date()))();
+    const execDir = resolve(opts.baseDir, ".gsd", "exec");
+    if (!existsSync(execDir)) mkdirSync(execDir, { recursive: true });
+    const stdoutPath = resolve(execDir, `${id}.stdout`);
+    const stderrPath = resolve(execDir, `${id}.stderr`);
+    const metaPath = resolve(execDir, `${id}.meta.json`);
+
+    const timeoutMs = clampTimeout(request, opts);
+    const { cmd, args } = resolveCommand(request.runtime);
+    const env = buildChildEnv(opts);
+    const useProcessGroup = process.platform !== "win32";
+
+    const started = Date.now();
+    let child;
+    try {
+      child = spawn(cmd, [...args, request.script], {
+        cwd: opts.baseDir,
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+        ...(useProcessGroup ? { detached: true } : {}),
+      });
+    } catch (err) {
+      const duration = Date.now() - started;
+      const message = err instanceof Error ? err.message : String(err);
+      writeFileSync(stdoutPath, "");
+      writeFileSync(stderrPath, `spawn error: ${message}\n`);
+      const result: ExecSandboxResult = {
+        id,
+        runtime: request.runtime,
+        exit_code: null,
+        signal: null,
+        timed_out: false,
+        duration_ms: duration,
+        stdout_bytes: 0,
+        stderr_bytes: Buffer.byteLength(`spawn error: ${message}\n`),
+        stdout_truncated: false,
+        stderr_truncated: false,
+        stdout_path: stdoutPath,
+        stderr_path: stderrPath,
+        meta_path: metaPath,
+        digest: `[spawn error: ${message}]`,
+      };
+      writeMeta(metaPath, result, request, now);
+      resolveP(result);
+      return;
+    }
+
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      const remaining = opts.stdout_cap_bytes - stdoutBytes;
+      if (remaining <= 0) {
+        stdoutTruncated = true;
+        return;
+      }
+      if (chunk.length <= remaining) {
+        stdoutChunks.push(chunk);
+        stdoutBytes += chunk.length;
+      } else {
+        stdoutChunks.push(chunk.subarray(0, remaining));
+        stdoutBytes += remaining;
+        stdoutTruncated = true;
+      }
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      const remaining = opts.stderr_cap_bytes - stderrBytes;
+      if (remaining <= 0) {
+        stderrTruncated = true;
+        return;
+      }
+      if (chunk.length <= remaining) {
+        stderrChunks.push(chunk);
+        stderrBytes += chunk.length;
+      } else {
+        stderrChunks.push(chunk.subarray(0, remaining));
+        stderrBytes += remaining;
+        stderrTruncated = true;
+      }
+    });
+
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      if (useProcessGroup && child.pid != null) {
+        try {
+          process.kill(-child.pid, "SIGKILL");
+        } catch {
+          child.kill("SIGKILL");
+        }
+      } else {
+        child.kill("SIGKILL");
+      }
+    }, timeoutMs);
+    timer.unref?.();
+
+    const finalize = (exitCode: number | null, signal: NodeJS.Signals | null) => {
+      clearTimeout(timer);
+      const duration = Date.now() - started;
+      const stdoutBuf = Buffer.concat(stdoutChunks);
+      const stderrBuf = Buffer.concat(stderrChunks);
+      const stdoutSuffix = stdoutTruncated ? "\n[truncated: stdout cap reached]\n" : "";
+      const stderrSuffix = stderrTruncated ? "\n[truncated: stderr cap reached]\n" : "";
+      writeFileSync(stdoutPath, Buffer.concat([stdoutBuf, Buffer.from(stdoutSuffix, "utf-8")]));
+      writeFileSync(stderrPath, Buffer.concat([stderrBuf, Buffer.from(stderrSuffix, "utf-8")]));
+
+      const digestBody = tail(stdoutBuf, opts.digest_chars);
+      const digest =
+        digestBody.length > 0
+          ? digestBody
+          : timedOut
+            ? "[no stdout — timed out]"
+            : stderrBuf.length > 0
+              ? `[no stdout — tail of stderr]\n${tail(stderrBuf, opts.digest_chars)}`
+              : "[no output]";
+
+      const result: ExecSandboxResult = {
+        id,
+        runtime: request.runtime,
+        exit_code: exitCode,
+        signal,
+        timed_out: timedOut,
+        duration_ms: duration,
+        stdout_bytes: stdoutBytes,
+        stderr_bytes: stderrBytes,
+        stdout_truncated: stdoutTruncated,
+        stderr_truncated: stderrTruncated,
+        stdout_path: stdoutPath,
+        stderr_path: stderrPath,
+        meta_path: metaPath,
+        digest,
+      };
+      writeMeta(metaPath, result, request, now);
+      resolveP(result);
+    };
+
+    child.on("error", (err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      const line = `child error: ${message}\n`;
+      const remaining = opts.stderr_cap_bytes - stderrBytes;
+      if (remaining > 0) {
+        const chunk = Buffer.from(line, "utf-8").subarray(0, remaining);
+        stderrChunks.push(chunk);
+        stderrBytes += chunk.length;
+        if (chunk.length < Buffer.byteLength(line, "utf-8")) stderrTruncated = true;
+      }
+    });
+    child.on("close", (code, signal) => finalize(code, signal));
+  });
+}
+
+function defaultGenerateId(): string {
+  return randomUUID();
+}
+
+function writeMeta(
+  path: string,
+  result: ExecSandboxResult,
+  request: ExecSandboxRequest,
+  now: Date,
+): void {
+  const meta = {
+    id: result.id,
+    runtime: result.runtime,
+    purpose: request.purpose ?? null,
+    script_chars: request.script.length,
+    started_at: now.toISOString(),
+    finished_at: new Date(now.getTime() + result.duration_ms).toISOString(),
+    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,
+  };
+  writeFileSync(path, `${JSON.stringify(meta, null, 2)}\n`);
+}

package/src/resources/extensions/gsd/file-lock.ts

@@ -1,12 +1,21 @@
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
 
-function _require(name: string) {
+// The file-lock module is loaded in both CJS builds and ESM sources. Under ESM
+// the bare `require` identifier is not defined, so we always go through
+// createRequire. We try the current module's resolution context first and fall
+// back to the installed gsd-pi package if we are running from a consumer
+// project that does not hoist proper-lockfile.
+const localRequire = createRequire(import.meta.url);
+
+function _require(name: string): any {
   try {
-    return require(name);
+    return localRequire(name);
   } catch {
     try {
-      const gsdPiRequire = require("module").createRequire(
-        require("path").join(process.cwd(), "node_modules", "gsd-pi", "index.js")
+      const gsdPiRequire = createRequire(
+        join(process.cwd(), "node_modules", "gsd-pi", "index.js"),
       );
       return gsdPiRequire(name);
     } catch {
@@ -15,43 +24,107 @@ function _require(name: string) {
   }
 }
 
-export function withFileLockSync<T>(filePath: string, fn: () => T): T {
+export type OnLocked = "fail" | "skip";
+
+export interface FileLockOptions {
+  /**
+   * Behavior when the lock cannot be acquired after retries (ELOCKED).
+   * - "fail" (default): rethrow the ELOCKED error so the caller can react.
+   * - "skip": run fn() unlocked. Only choose this for best-effort writes
+   *   that genuinely tolerate contention (e.g. high-frequency audit appends
+   *   where dropping one entry is acceptable). Silent unlocked execution was
+   *   the legacy behavior and is a correctness hazard for shared state.
+   */
+  onLocked?: OnLocked;
+  /** proper-lockfile retries (default 5). */
+  retries?: number;
+  /** proper-lockfile stale threshold in ms (default 10000). */
+  stale?: number;
+}
+
+const DEFAULT_RETRIES = 5;
+const DEFAULT_STALE_MS = 10000;
+const SYNC_RETRY_DELAY_MS = 50;
+
+// Block the thread for `ms` milliseconds without spinning the CPU.
+// Used by the sync lock retry loop, since proper-lockfile's lockSync does not
+// accept a `retries` option (only the async `lock` does).
+function sleepSync(ms: number): void {
+  if (ms <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function acquireLockSyncWithRetry(
+  lockfile: any,
+  filePath: string,
+  retries: number,
+  stale: number,
+): () => void {
+  let lastErr: any;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return lockfile.lockSync(filePath, { stale });
+    } catch (err: any) {
+      lastErr = err;
+      if (err?.code !== "ELOCKED") throw err;
+      if (attempt < retries) sleepSync(SYNC_RETRY_DELAY_MS);
+    }
+  }
+  throw lastErr;
+}
+
+export function withFileLockSync<T>(
+  filePath: string,
+  fn: () => T,
+  opts: FileLockOptions = {},
+): T {
   const lockfile = _require("proper-lockfile");
   if (!lockfile) return fn();
 
   if (!existsSync(filePath)) return fn();
 
+  const retries = opts.retries ?? DEFAULT_RETRIES;
+  const stale = opts.stale ?? DEFAULT_STALE_MS;
+  const onLocked: OnLocked = opts.onLocked ?? "fail";
+
   try {
-    const release = lockfile.lockSync(filePath, { retries: 5, stale: 10000 });
+    const release = acquireLockSyncWithRetry(lockfile, filePath, retries, stale);
     try {
       return fn();
     } finally {
       release();
     }
   } catch (err: any) {
-    if (err.code === "ELOCKED") {
-      // Could not get lock after retries, let's fallback to un-locked instead of crashing the whole state machine
+    if (err?.code === "ELOCKED" && onLocked === "skip") {
       return fn();
     }
     throw err;
   }
 }
 
-export async function withFileLock<T>(filePath: string, fn: () => Promise<T> | T): Promise<T> {
+export async function withFileLock<T>(
+  filePath: string,
+  fn: () => Promise<T> | T,
+  opts: FileLockOptions = {},
+): Promise<T> {
   const lockfile = _require("proper-lockfile");
   if (!lockfile) return await fn();
 
   if (!existsSync(filePath)) return await fn();
 
+  const retries = opts.retries ?? DEFAULT_RETRIES;
+  const stale = opts.stale ?? DEFAULT_STALE_MS;
+  const onLocked: OnLocked = opts.onLocked ?? "fail";
+
   try {
-    const release = await lockfile.lock(filePath, { retries: 5, stale: 10000 });
+    const release = await lockfile.lock(filePath, { retries, stale });
     try {
       return await fn();
     } finally {
       await release();
     }
   } catch (err: any) {
-    if (err.code === "ELOCKED") {
+    if (err?.code === "ELOCKED" && onLocked === "skip") {
       return await fn();
     }
     throw err;

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

@@ -35,11 +35,12 @@ import { getAutoWorktreePath } from "./auto-worktree.js";
 import { loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
 import { showNextAction } from "../shared/tui.js";
 import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
+import { summarizeWorktreeTelemetry, percentile, type WorktreeTelemetrySummary } from "./worktree-telemetry.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
 export interface ForensicAnomaly {
-  type: "stuck-loop" | "cost-spike" | "timeout" | "missing-artifact" | "crash" | "doctor-issue" | "error-trace" | "journal-stuck" | "journal-guard-block" | "journal-rapid-iterations" | "journal-worktree-failure";
+  type: "stuck-loop" | "cost-spike" | "timeout" | "missing-artifact" | "crash" | "doctor-issue" | "error-trace" | "journal-stuck" | "journal-guard-block" | "journal-rapid-iterations" | "journal-worktree-failure" | "worktree-orphan" | "worktree-unmerged-exit";
   severity: "info" | "warning" | "error";
   unitType?: string;
   unitId?: string;
@@ -113,6 +114,8 @@ interface ForensicReport {
   recentUnits: { type: string; id: string; cost: number; duration: number; model: string; finishedAt: number }[];
   journalSummary: JournalSummary | null;
   activityLogMeta: ActivityLogMeta | null;
+  /** #4764 — worktree lifespan / divergence telemetry aggregates. */
+  worktreeTelemetry: WorktreeTelemetrySummary | null;
 }
 
 // ─── Duplicate Detection ──────────────────────────────────────────────────────
@@ -337,6 +340,16 @@ export async function buildForensicReport(basePath: string): Promise<ForensicRep
   detectCrash(crashLock, anomalies);
   detectDoctorIssues(doctorIssues, anomalies);
   detectErrorTraces(unitTraces, anomalies);
+
+  // 11b. #4764 — worktree lifecycle telemetry
+  let worktreeTelemetry: WorktreeTelemetrySummary | null = null;
+  try {
+    worktreeTelemetry = summarizeWorktreeTelemetry(basePath);
+    detectWorktreeOrphans(worktreeTelemetry, anomalies);
+  } catch {
+    // Telemetry is best-effort — do not let an aggregator failure block the
+    // rest of the forensic report.
+  }
   detectJournalAnomalies(journalSummary, anomalies);
 
   return {
@@ -356,6 +369,7 @@ export async function buildForensicReport(basePath: string): Promise<ForensicRep
     recentUnits,
     journalSummary,
     activityLogMeta,
+    worktreeTelemetry,
   };
 }
 
@@ -783,6 +797,51 @@ function detectMissingArtifacts(completedKeys: string[], basePath: string, activ
   }
 }
 
+/**
+ * #4764 — surface worktree lifecycle and orphan signals in the forensic report.
+ *
+ * Consumes only the aggregated summary (not raw journal events) to respect
+ * the forensics memory-bloat guard in forensics-journal.test.ts — per-event
+ * detail stays in the journal itself where the LLM can query it on demand.
+ */
+function detectWorktreeOrphans(
+  summary: WorktreeTelemetrySummary,
+  anomalies: ForensicAnomaly[],
+): void {
+  // 1. Orphan aggregate — severity depends on reason. In-progress orphans are
+  // the #4761 consumer-side signal (live work sitting on an unmerged branch).
+  for (const [reason, count] of Object.entries(summary.orphansByReason)) {
+    if (count <= 0) continue;
+    const severity: ForensicAnomaly["severity"] =
+      reason === "in-progress-unmerged" ? "warning" : "info";
+    anomalies.push({
+      type: "worktree-orphan",
+      severity,
+      summary: `${count} worktree orphan(s) detected (${reason})`,
+      details:
+        reason === "in-progress-unmerged"
+          ? "Auto-mode exited without completing a milestone; live work sits on an unmerged milestone branch. Run `/gsd auto` to resume, or merge manually."
+          : reason === "complete-unmerged"
+            ? "A completed milestone's branch was never merged back to main. Run `/gsd health --fix` to resolve."
+            : `Reason: ${reason}.`,
+    });
+  }
+
+  // 2. Auto-exit producer signal — #4761's upstream cause.
+  if (summary.exitsWithUnmergedWork > 0) {
+    const reasonBreakdown = Object.entries(summary.exitsByReason)
+      .filter(([, n]) => n > 0)
+      .map(([r, n]) => `${r}=${n}`)
+      .join(", ");
+    anomalies.push({
+      type: "worktree-unmerged-exit",
+      severity: "warning",
+      summary: `${summary.exitsWithUnmergedWork} auto-exit(s) left milestone work unmerged`,
+      details: `Exit reasons: ${reasonBreakdown || "(none)"} · Producer-side signal for #4761-class orphans. Inspect .gsd/journal/*.jsonl with eventType:"auto-exit" for per-exit detail.`,
+    });
+  }
+}
+
 function detectCrash(crashLock: LockData | null, anomalies: ForensicAnomaly[]): void {
   if (!crashLock) return;
   if (isLockProcessAlive(crashLock)) return; // Process still running, not a crash
@@ -972,6 +1031,40 @@ function saveForensicReport(basePath: string, report: ForensicReport, problemDes
     sections.push(``);
   }
 
+  // #4764 — Worktree telemetry summary
+  if (report.worktreeTelemetry) {
+    const t = report.worktreeTelemetry;
+    const p50 = percentile(t.mergeDurationsMs, 0.5);
+    const p95 = percentile(t.mergeDurationsMs, 0.95);
+    sections.push(`## Worktree Telemetry`, ``);
+    sections.push(`- Worktrees created: ${t.worktreesCreated}`);
+    sections.push(`- Worktrees merged: ${t.worktreesMerged}`);
+    sections.push(`- Orphans detected: ${t.orphansDetected}`);
+    if (t.orphansDetected > 0) {
+      const breakdown = Object.entries(t.orphansByReason)
+        .map(([r, n]) => `${r}=${n}`).join(", ");
+      sections.push(`  - By reason: ${breakdown}`);
+    }
+    sections.push(`- Merge conflicts: ${t.mergeConflicts}`);
+    if (t.mergeDurationsMs.length > 0) {
+      sections.push(`- Merge duration p50 / p95: ${p50 ?? "-"} / ${p95 ?? "-"} ms (n=${t.mergeDurationsMs.length})`);
+    }
+    sections.push(`- Auto-exits leaving unmerged work: ${t.exitsWithUnmergedWork}`);
+    if (Object.keys(t.exitsByReason).length > 0) {
+      const breakdown = Object.entries(t.exitsByReason)
+        .sort((a, b) => b[1] - a[1])
+        .map(([r, n]) => `${r}=${n}`).join(", ");
+      sections.push(`  - Exit reasons: ${breakdown}`);
+    }
+    sections.push(`- Canonical-root redirects (#4761 fix fired): ${t.canonicalRedirects}`);
+    // #4765 slice-cadence counters
+    if (t.slicesMerged + t.sliceMergeConflicts + t.milestoneResquashes > 0) {
+      sections.push(`- Slices merged: ${t.slicesMerged} · Slice merge conflicts: ${t.sliceMergeConflicts}`);
+      sections.push(`- Milestone re-squashes: ${t.milestoneResquashes}`);
+    }
+    sections.push(``);
+  }
+
   // Journal summary
   if (report.journalSummary) {
     const js = report.journalSummary;
@@ -1117,6 +1210,30 @@ function formatReportForPrompt(report: ForensicReport): string {
     sections.push("");
   }
 
+  // #4764 — worktree telemetry (compact prompt form)
+  if (report.worktreeTelemetry) {
+    const t = report.worktreeTelemetry;
+    const hasSignal =
+      t.worktreesCreated + t.worktreesMerged + t.orphansDetected +
+      t.exitsWithUnmergedWork + t.canonicalRedirects +
+      t.slicesMerged + t.milestoneResquashes > 0;
+    if (hasSignal) {
+      sections.push("### Worktree Telemetry");
+      sections.push(`- Created: ${t.worktreesCreated} · Merged: ${t.worktreesMerged} · Conflicts: ${t.mergeConflicts}`);
+      sections.push(`- Orphans: ${t.orphansDetected} · Unmerged exits: ${t.exitsWithUnmergedWork} · Redirects (#4761): ${t.canonicalRedirects}`);
+      if (t.orphansDetected > 0) {
+        const breakdown = Object.entries(t.orphansByReason)
+          .map(([r, n]) => `${r}=${n}`).join(", ");
+        sections.push(`- Orphan reasons: ${breakdown}`);
+      }
+      // #4765 — slice-cadence counters (only shown when the feature was exercised)
+      if (t.slicesMerged + t.sliceMergeConflicts + t.milestoneResquashes > 0) {
+        sections.push(`- Slices merged: ${t.slicesMerged} · Slice conflicts: ${t.sliceMergeConflicts} · Re-squashes: ${t.milestoneResquashes}`);
+      }
+      sections.push("");
+    }
+  }
+
   // Activity log metadata
   if (report.activityLogMeta) {
     const meta = report.activityLogMeta;

package/src/resources/extensions/gsd/git-service.ts

@@ -85,6 +85,22 @@ export interface GitPreferences {
    *  for forensic inspection.
    */
   absorb_snapshot_commits?: boolean;
+  /** #4765 — when to collapse worktree commits back to main.
+   *  - "milestone" (default): existing behavior — squash-merge happens once
+   *    at milestone completion or transition.
+   *  - "slice": squash-merge each slice's commits to main as soon as the
+   *    slice passes validation. Shrinks the orphan window from
+   *    milestone-size to slice-size and surfaces merge conflicts per slice
+   *    rather than all at once at milestone end.
+   */
+  collapse_cadence?: "milestone" | "slice";
+  /** #4765 — when `collapse_cadence: "slice"`, optionally re-squash the per-
+   *  slice commits on main into one milestone commit at milestone completion.
+   *  Preserves the "one commit per milestone in main" history shape that
+   *  `collapse_cadence: "milestone"` produces today.
+   *  Default: true when collapse_cadence is "slice", ignored otherwise.
+   */
+  milestone_resquash?: boolean;
 }
 
 export const VALID_BRANCH_NAME = /^[a-zA-Z0-9_\-\/.]+$/;
@@ -210,6 +226,7 @@ export interface PreMergeCheckResult {
  */
 export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
   ".gsd/activity/",
+  ".gsd/audit/",
   ".gsd/forensics/",
   ".gsd/runtime/",
   ".gsd/worktrees/",

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

@@ -26,6 +26,7 @@ import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
  */
 const GSD_RUNTIME_PATTERNS = [
   ".gsd/activity/",
+  ".gsd/audit/",
   ".gsd/forensics/",
   ".gsd/runtime/",
   ".gsd/worktrees/",
@@ -48,6 +49,7 @@ const BASELINE_PATTERNS = [
   // ── GSD state directory (symlink to external storage) ──
   ".gsd",
   ".gsd-id",
+  ".mcp.json",
   ".bg-shell/",
 
   // ── OS junk ──
@@ -319,4 +321,3 @@ custom_instructions:
   writeFileSync(preferencesPath, template, "utf-8");
   return true;
 }
-