@opengsd/gsd-pi 1.9.0 → 1.10.0-dev.a5e42e99

package/src/resources/extensions/gsd/compat/compat-marker.ts

@@ -6,8 +6,8 @@
 // (drift to import). gsd-core is oblivious to this file and ignores it.
 
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync, mkdirSync } from "node:fs";
-import { dirname, join, isAbsolute, normalize } from "node:path";
+import { existsSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join, isAbsolute, normalize, relative, resolve } from "node:path";
 
 /** Current marker schema version. Bump on breaking format changes + migrate. */
 export const COMPAT_MARKER_SCHEMA = 2;
@@ -54,6 +54,13 @@ export interface CompatMarker {
   piVersion: string;
 }
 
+export interface ReadCompatMarkerOptions {
+  /** Rewrite invalid-but-derivable marker keys back to safe root-relative keys. */
+  healInvalidKeys?: boolean;
+  /** Quarantine malformed/unsafe markers. Disable only for read-only previews. */
+  quarantineInvalid?: boolean;
+}
+
 /** Marker returned when no marker exists yet (fresh project, first gsd-pi run). */
 export const EMPTY_MARKER: CompatMarker = {
   schema: COMPAT_MARKER_SCHEMA,
@@ -81,6 +88,37 @@ export function computeProjectionSha(content: string): string {
   return createHash("sha256").update(normalizeForHash(content)).digest("hex").slice(0, 16);
 }
 
+function normalizeRealPath(p: string): string {
+  try {
+    return realpathSync.native(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+function rootRelativeKey(rootPath: string, absPath: string): string | null {
+  const root = normalizeRealPath(rootPath);
+  const abs = normalizeRealPath(absPath);
+  const rel = relative(root, abs);
+  if (!rel || rel === ".." || rel.startsWith(`..${sepForRelative(rel)}`) || isAbsolute(rel)) {
+    return null;
+  }
+  return rel.replace(/\\/g, "/");
+}
+
+function sepForRelative(rel: string): string {
+  return rel.includes("\\") ? "\\" : "/";
+}
+
+export function deriveCompatProjectionKey(absPath: string, roots: readonly string[]): string {
+  for (const root of roots) {
+    const key = rootRelativeKey(root, absPath);
+    if (key) return key;
+  }
+  const fallbackRoot = roots[roots.length - 1] ?? dirname(absPath);
+  return relative(fallbackRoot, absPath).replace(/\\/g, "/");
+}
+
 /**
  * Read & validate the marker. A missing marker → EMPTY_MARKER (treat every
  * projection as external on next reconcile). A malformed marker is quarantined
@@ -88,7 +126,12 @@ export function computeProjectionSha(content: string): string {
  * EMPTY_MARKER. A schema-mismatch returns EMPTY_MARKER (forward-compat: refuse
  * to act on a future format we don't understand).
  */
-export function readCompatMarker(basePath: string): CompatMarker {
+export function readCompatMarker(
+  basePath: string,
+  options: ReadCompatMarkerOptions = {},
+): CompatMarker {
+  const healInvalidKeys = options.healInvalidKeys ?? true;
+  const quarantineInvalid = options.quarantineInvalid ?? true;
   const path = compatMarkerPath(basePath);
   if (!existsSync(path)) return emptyMarker();
 
@@ -103,12 +146,16 @@ export function readCompatMarker(basePath: string): CompatMarker {
   try {
     parsed = JSON.parse(raw);
   } catch {
-    quarantine(basePath, raw);
+    if (quarantineInvalid) quarantine(basePath, raw);
     return emptyMarker();
   }
 
+  if (healInvalidKeys && healMarkerProjectionKeys(basePath, parsed) && isValidMarker(parsed)) {
+    writeCompatMarker(basePath, parsed);
+  }
+
   if (!isValidMarker(parsed)) {
-    quarantine(basePath, raw);
+    if (quarantineInvalid) quarantine(basePath, raw);
     return emptyMarker();
   }
   // Promote older markers by defaulting absent fields. Schema 1 → 2 only adds
@@ -245,6 +292,53 @@ function isValidProjectionMap(x: unknown): boolean {
   return true;
 }
 
+function healMarkerProjectionKeys(basePath: string, marker: unknown): marker is CompatMarker {
+  if (typeof marker !== "object" || marker === null) return false;
+  const m = marker as Record<string, unknown>;
+  let changed = false;
+
+  if (typeof m.projections === "object" && m.projections !== null) {
+    changed = healProjectionMapKeys(basePath, ".gsd", m.projections as Record<string, ProjectionEntry>) || changed;
+  }
+
+  const planning = m.planning;
+  if (typeof planning === "object" && planning !== null) {
+    const p = planning as Record<string, unknown>;
+    if (typeof p.projections === "object" && p.projections !== null) {
+      changed = healProjectionMapKeys(basePath, ".planning", p.projections as Record<string, ProjectionEntry>) || changed;
+    }
+    if (typeof p.passthrough === "object" && p.passthrough !== null) {
+      changed = healProjectionMapKeys(basePath, ".planning", p.passthrough as Record<string, ProjectionEntry>) || changed;
+    }
+  }
+
+  return changed;
+}
+
+function healProjectionMapKeys(
+  basePath: string,
+  rootName: ".gsd" | ".planning",
+  map: Record<string, ProjectionEntry>,
+): boolean {
+  let changed = false;
+  const root = join(basePath, rootName);
+
+  for (const key of Object.keys(map)) {
+    if (isSafeProjectionKey(key)) continue;
+    if (key.includes("\0") || isAbsolute(key) || /^[A-Za-z]:/.test(key)) continue;
+    const healedKey = rootRelativeKey(root, resolve(root, key));
+    if (!healedKey || !isSafeProjectionKey(healedKey)) continue;
+
+    if (!map[healedKey]) {
+      map[healedKey] = map[key]!;
+    }
+    delete map[key];
+    changed = true;
+  }
+
+  return changed;
+}
+
 function isValidPlanningMarker(x: unknown): x is PlanningMarker {
   if (typeof x !== "object" || x === null) return false;
   const p = x as Record<string, unknown>;

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

@@ -31,36 +31,37 @@ export const CACHE_MAX = 50;
  * By scoping tools to this allowlist during discuss dispatches, the grammar
  * sent to the provider stays well under provider limits.
  *
- * Included tools and why:
+ * Included tools and why (canonical names only — aliases are no longer
+ * advertised to models by default, see plan 035):
  *   - gsd_summary_save: writes CONTEXT.md artifacts (all discuss prompts)
- *   - gsd_save_summary: alias for above
  *   - gsd_decision_save: records decisions (discuss.md output phase)
- *   - gsd_save_decision: alias for above
  *   - gsd_plan_milestone: writes roadmap (discuss.md single/multi milestone)
- *   - gsd_milestone_plan: alias for above
  *   - gsd_milestone_generate_id: generates milestone IDs (discuss.md multi-milestone)
- *   - gsd_generate_milestone_id: alias for above
  *   - gsd_requirement_save: creates requirements during discuss
- *   - gsd_save_requirement: alias for above
  *   - gsd_requirement_update: updates requirements during discuss
- *   - gsd_update_requirement: alias for above
  */
 export const DISCUSS_TOOLS_ALLOWLIST: readonly string[] = [
   // Context / summary writing
   "gsd_summary_save",
-  "gsd_save_summary",
   // Decision recording
   "gsd_decision_save",
-  "gsd_save_decision",
   // Milestone planning (needed for discuss.md output phase)
   "gsd_plan_milestone",
-  "gsd_milestone_plan",
   // Milestone ID generation (multi-milestone flow)
   "gsd_milestone_generate_id",
-  "gsd_generate_milestone_id",
   // Requirement updates
   "gsd_requirement_save",
-  "gsd_save_requirement",
   "gsd_requirement_update",
-  "gsd_update_requirement",
 ];
+
+// ─── Context Injection ────────────────────────────────────────────────────────
+
+/**
+ * Leading marker stamped on every buildContextMessage() output
+ * (bootstrap/system-context.ts). Single source of truth for the producer and
+ * the consumer: the provider payload policy (filterSupersededContextInjections
+ * in context-masker.ts) matches this prefix to find and dedupe injected
+ * memory/guided/forensics messages after convertToLlm strips their customType.
+ * Both sides import it from here — do not inline the literal in either module.
+ */
+export const GSD_CONTEXT_MESSAGE_SENTINEL = "[GSD Context Injection]";

package/src/resources/extensions/gsd/context-masker.ts

@@ -1,3 +1,5 @@
+import { GSD_CONTEXT_MESSAGE_SENTINEL } from "./constants.js";
+
 /**
  * Observation masking for GSD auto-mode sessions.
  *
@@ -75,6 +77,26 @@ function findTurnBoundary(messages: MaskableMessage[], keepRecentTurns: number):
   return 0;
 }
 
+function countRealUserTurns(messages: MaskableMessage[]): number {
+  let count = 0;
+  for (const m of messages) {
+    if (m.role === "user" && !isBashResultUserMessage(m)) count++;
+  }
+  return count;
+}
+
+/**
+ * Quantizes how many recent turns stay unmasked so the boundary only moves
+ * forward once per full block of `keepRecentTurns` new turns, instead of
+ * every turn. Keeps the masked prefix byte-stable within a block, which is
+ * what lets the LLM provider's prompt cache survive across turns.
+ */
+function quantizedKeepTurns(totalTurns: number, keepRecentTurns: number): number {
+  if (keepRecentTurns <= 0 || totalTurns < 2 * keepRecentTurns) return totalTurns;
+  const maskedTurns = Math.floor((totalTurns - keepRecentTurns) / keepRecentTurns) * keepRecentTurns;
+  return totalTurns - maskedTurns;
+}
+
 /**
  * Detect user messages that originated from bashExecution.
  * After convertToLlm, these are {role: "user", content: [{type:"text", text:"Ran `cmd`\n..."}]}.
@@ -95,7 +117,8 @@ function isMaskableMessage(m: MaskableMessage): boolean {
 
 export function createObservationMask(keepRecentTurns: number = 8) {
   return (messages: MaskableMessage[]): MaskableMessage[] => {
-    const boundary = findTurnBoundary(messages, keepRecentTurns);
+    const totalTurns = countRealUserTurns(messages);
+    const boundary = findTurnBoundary(messages, quantizedKeepTurns(totalTurns, keepRecentTurns));
     if (boundary === 0) return messages;
 
     return messages.map((m, i) => {
@@ -126,6 +149,14 @@ function findResponsesTurnBoundary(items: ResponsesInputItem[], keepRecentTurns:
   return 0;
 }
 
+function countResponsesRealUserTurns(items: ResponsesInputItem[]): number {
+  let count = 0;
+  for (const item of items) {
+    if (item.role === "user" && !isResponsesBashResultUserItem(item)) count++;
+  }
+  return count;
+}
+
 /**
  * Observation masking for OpenAI/Codex Responses API payloads.
  *
@@ -135,7 +166,8 @@ function findResponsesTurnBoundary(items: ResponsesInputItem[], keepRecentTurns:
  */
 export function createResponsesInputObservationMask(keepRecentTurns: number = 8) {
   return (items: ResponsesInputItem[]): ResponsesInputItem[] => {
-    const boundary = findResponsesTurnBoundary(items, keepRecentTurns);
+    const totalTurns = countResponsesRealUserTurns(items);
+    const boundary = findResponsesTurnBoundary(items, quantizedKeepTurns(totalTurns, keepRecentTurns));
     if (boundary === 0) return items;
 
     return items.map((item, i) => {
@@ -219,3 +251,67 @@ export function truncateResponsesInputResultItems(items: ResponsesInputItem[], m
     return item;
   });
 }
+
+// GSD injects at most one context message per turn (memory/guided/forensics —
+// see buildContextMessage in bootstrap/system-context.ts), marked with
+// GSD_CONTEXT_MESSAGE_SENTINEL. convertToLlm strips the distinguishing
+// customType before the payload reaches this hook, so detection is by content
+// prefix instead. Pre-sentinel session history lacks the sentinel, so we also
+// match the stable *bracketed* GSD block labels those injections begin with,
+// letting resumed sessions dedupe older memory/guided blocks.
+//
+// Only GSD-specific bracketed markers belong here — never generic prose. A
+// message is dropped from the payload when it matches, so a natural-language
+// prefix (e.g. the forensics prompt "Debug GSD itself.") could silently delete
+// a real user message that happens to start the same way. Legacy forensics
+// injections without memory are therefore left un-deduped by design; those
+// with memory still match via the "[GSD Context Metadata]" wrapper.
+const LEGACY_GSD_CONTEXT_INJECTION_PREFIXES = [
+  "[GSD Context Metadata]",
+  "[MEMORY — Critical and prompt-relevant memories from the GSD memory store]",
+  "[GSD Guided Execute Context]",
+] as const;
+
+function isGsdContextInjectionText(text: string | undefined): boolean {
+  if (typeof text !== "string") return false;
+  if (text.startsWith(GSD_CONTEXT_MESSAGE_SENTINEL)) return true;
+  return LEGACY_GSD_CONTEXT_INJECTION_PREFIXES.some((prefix) => text.startsWith(prefix));
+}
+
+function isGsdContextInjectionMessage(m: MaskableMessage): boolean {
+  if (m.role !== "user") return false;
+  return isGsdContextInjectionText(firstTextFromContent(m.content));
+}
+
+/**
+ * Removes every GSD context-injection user message except the latest one.
+ * Each turn re-injects a near-identical memory/guided/forensics block; left
+ * in place they duplicate verbatim across an N-turn session. Removal (not
+ * masking) — an empty placeholder still costs tokens and shifts message
+ * positions, breaking cache byte-stability. Pure function: stored history is
+ * never mutated, only the outgoing payload array.
+ */
+export function filterSupersededContextInjections(messages: MaskableMessage[]): MaskableMessage[] {
+  let lastIndex = -1;
+  for (let i = 0; i < messages.length; i++) {
+    if (isGsdContextInjectionMessage(messages[i])) lastIndex = i;
+  }
+  if (lastIndex === -1) return messages;
+  return messages.filter((m, i) => i === lastIndex || !isGsdContextInjectionMessage(m));
+}
+
+function isResponsesGsdContextInjectionItem(item: ResponsesInputItem): boolean {
+  if (item.role !== "user") return false;
+  return isGsdContextInjectionText(firstTextFromContent(item.content));
+}
+
+export function filterSupersededResponsesContextInjections(
+  items: ResponsesInputItem[],
+): ResponsesInputItem[] {
+  let lastIndex = -1;
+  for (let i = 0; i < items.length; i++) {
+    if (isResponsesGsdContextInjectionItem(items[i])) lastIndex = i;
+  }
+  if (lastIndex === -1) return items;
+  return items.filter((item, i) => i === lastIndex || !isResponsesGsdContextInjectionItem(item));
+}

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

@@ -10,7 +10,7 @@
 // writer layer.
 import { createRequire } from "node:module";
 import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { GSDError, GSD_STALE_STATE } from "../errors.js";
 import type { GsdWorkspace, MilestoneScope } from "../workspace.js";
 import { logError, logWarning } from "../workflow-logger.js";
@@ -71,7 +71,10 @@ let _gsdRequire: ReturnType<typeof createRequire> | null | undefined;
 function getGsdRequire(): ReturnType<typeof createRequire> | null {
   if (_gsdRequire !== undefined) return _gsdRequire;
   try {
-    _gsdRequire = createRequire(import.meta.url);
+    // Next.js may emit this module into a CommonJS chunk. Avoid ESM-only module
+    // metadata syntax here; it is a hard parse error there.
+    const packageRoot = process.env.GSD_WEB_PACKAGE_ROOT || process.env.GSD_PKG_ROOT || process.cwd();
+    _gsdRequire = createRequire(resolve(packageRoot, "package.json"));
   } catch {
     _gsdRequire = null;
   }

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -124,11 +124,11 @@ Diagnostics record the file path, scope (global/project), severity (error/warnin
   - `validation` — used for gate evaluation, roadmap reassessment, milestone validation, and doc rewrites. Falls back to `planning` if unset.
   - `uat` — used for UAT runs. Falls back to `completion` if unset.
 
-- `thinking`: per-phase reasoning effort (ADR-026), separate from `models`. Same phase keys as `models`. Values: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. Thinking travels with the model — model choice and reasoning effort are independent controls, so you can run one model across phases at different reasoning levels.
+- `thinking`: per-phase reasoning effort (ADR-026), separate from `models`. Same phase keys as `models`. Values: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Thinking travels with the model — model choice and reasoning effort are independent controls, so you can run one model across phases at different reasoning levels.
   - Two equivalent ways to set it: inline as `models.<phase>.thinking`, or as a separate `thinking:` block keyed by phase. For the same phase, the inline value wins over the block; project preferences win over global; a phase that's unset inherits via the same sibling chain as `models` (e.g. `discuss → planning`).
   - If no thinking is configured for a phase, the session level (set via `/model`) is used, exactly as before — this is fully backward-compatible.
   - `execute-task` (code-writing) has a measured reasoning floor of `medium`: at lower levels models stop planning edits and thrash on file re-reads. The floor applies to the session/default path. An **explicit** `execution` thinking level bypasses the floor and is honored verbatim (with a one-time advisory) — set `execution: low` deliberately if you want it.
-  - Levels a model can't support are clamped to the nearest supported level at dispatch and never sent to the provider, so a model/level mismatch never fails a unit mid-run. `xhigh` support is model-dependent; current examples include OpenAI Codex Max models and Claude Sonnet 5 on Amazon Bedrock.
+  - Levels a model can't support are clamped to the nearest supported level at dispatch and never sent to the provider, so a model/level mismatch never fails a unit mid-run. `xhigh` and `max` support are model-dependent; current examples include `gpt-5.6-sol`, `gpt-5.6-terra`, and `gpt-5.6-luna`, which advertise both.
 
 - `skill_staleness_days`: number — skills unused for this many days get deprioritized during discovery. Set to `0` to disable staleness tracking. Default: `60`.
 
@@ -357,6 +357,37 @@ In `"parent"` mode, slice/task `targetRepositories` default to the declared chil
   - `"replace"` requires `prompt`.
   - `"skip"` is valid with no additional fields.
 
+- `planning_subagent_registry`: object — optional classification for custom planning agents. Each key is an agent id and must set:
+  - `read_only_specialist`: boolean — set to `true` to classify the custom agent as safe for planning dispatch.
+
+- `planning_subagents`: object — project-local widening for read-only planning subagent dispatch. Supported unit keys are `plan-milestone` and `plan-slice`; each has:
+  - `allowed`: string[] — additional planning-safe agents for that unit.
+
+  Agents must be built-in read-only planning specialists (`mnemo`, `scout`, `planner`, `reviewer`, `security`, or `tester`) or registered in `planning_subagent_registry` with `read_only_specialist: true`. The write gate still blocks source writes outside `.gsd/**`, unrestricted bash, stale subagent calls without agent identities, agents outside the read-only registry, and agents not listed for the active unit.
+
+  Example:
+
+  ```yaml
+  planning_subagent_registry:
+    my-custom-planner:
+      read_only_specialist: true
+
+  planning_subagents:
+    plan-milestone:
+      allowed:
+        - scout
+        - planner
+        - my-custom-planner
+        - security
+    plan-slice:
+      allowed:
+        - scout
+        - planner
+        - my-custom-planner
+        - reviewer
+        - security
+  ```
+
   **Known unit types for `before`/`after`:** `research-milestone`, `plan-milestone`, `research-slice`, `plan-slice`, `execute-task`, `complete-slice`, `replan-slice`, `reassess-roadmap`, `run-uat`.
 
 - `experimental`: opt-in experimental features. All features here are **off by default** — you must explicitly set each one to `true` to enable it. Features in this block may change or be removed without a deprecation cycle while in experimental status. Keys:

package/src/resources/extensions/gsd/doctor-engine-checks.ts

@@ -15,13 +15,13 @@ import {
 import { MEMORIES_FTS_REBUILT_KEY } from "./db-memory-fts-schema.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
 import {
-  buildTaskFileName,
   gsdProjectionRoot,
   gsdRoot,
   resolveGsdPathContract,
   resolveMilestoneFile,
   resolveMilestonePath,
   resolveSliceFile,
+  resolveTaskFile,
 } from "./paths.js";
 import { deriveState } from "./state.js";
 import { isClosedStatus } from "./status-guards.js";
@@ -32,6 +32,7 @@ import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { parsePlan } from "./parsers-legacy.js";
 import { parseSummary } from "./files.js";
 import { LAYOUT_SEGMENTS } from "./layout-policy.js";
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 
 const USER_AUTHORED_ARTIFACT_TYPES = new Set(["CONTEXT", "RESEARCH"]);
 
@@ -95,9 +96,29 @@ function reportCheckboxDbStatusDivergence(
   });
 }
 
+function bareDuplicateMilestoneId(milestoneId: string): string | null {
+  const match = milestoneId.match(/^(M\d{3})-[a-z0-9]{6}$/i);
+  return match?.[1]?.toUpperCase() ?? null;
+}
+
+function checkboxDbStatusMilestoneIds(basePath: string, milestoneIds: string[]): string[] {
+  if (!hasFlatPhaseLayout(basePath)) return milestoneIds;
+
+  // Flat-phase directories are keyed by phase number. A restored
+  // M003-xxxxxx row alongside M003 is a stale duplicate for the same
+  // phases/03-* projection, so checking both can compare DB status against two
+  // competing PLAN files and report a persistent false divergence.
+  const allIds = new Set(milestoneIds.map((id) => id.toUpperCase()));
+  return milestoneIds.filter((milestoneId) => {
+    const bareId = bareDuplicateMilestoneId(milestoneId);
+    return !bareId || !allIds.has(bareId);
+  });
+}
+
 function checkProjectionCheckboxDbStatus(basePath: string, milestoneIds: string[], issues: DoctorIssue[]): void {
   for (const milestoneId of milestoneIds) {
-    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+    const roadmapPath = resolveMilestoneFile(artifactBasePath, milestoneId, "ROADMAP");
     const slices = getMilestoneSlices(milestoneId);
 
     if (roadmapPath && existsSync(roadmapPath)) {
@@ -123,7 +144,7 @@ function checkProjectionCheckboxDbStatus(basePath: string, milestoneIds: string[
     }
 
     for (const slice of slices) {
-      const planPath = resolveSliceFile(basePath, milestoneId, slice.id, "PLAN");
+      const planPath = resolveSliceFile(artifactBasePath, milestoneId, slice.id, "PLAN");
       if (!planPath || !existsSync(planPath)) continue;
       try {
         const plan = readFileSync(planPath, "utf-8");
@@ -173,7 +194,7 @@ function artifactExistsOnDisk(basePath: string, artifactPath: string, row?: Arti
   return resolveArtifactDiskPath(basePath, artifactPath, row) !== null;
 }
 
-function resolveLiteralArtifactDiskPath(basePath: string, artifactPath: string): string | null {
+function resolveLiteralArtifactDiskPath(basePath: string, artifactPath: string, row?: ArtifactRow): string | null {
   const relativeArtifactPath = artifactPathRelativeToGsd(artifactPath);
   if (isAbsolute(relativeArtifactPath)) {
     return existsSync(relativeArtifactPath) ? relativeArtifactPath : null;
@@ -182,6 +203,15 @@ function resolveLiteralArtifactDiskPath(basePath: string, artifactPath: string):
     const candidate = join(root, relativeArtifactPath);
     if (isPathInside(root, candidate) && existsSync(candidate)) return candidate;
   }
+  if (row?.milestone_id) {
+    const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, row.milestone_id);
+    if (artifactBasePath !== basePath) {
+      for (const root of [gsdProjectionRoot(artifactBasePath), gsdRoot(artifactBasePath)]) {
+        const candidate = join(root, relativeArtifactPath);
+        if (isPathInside(root, candidate) && existsSync(candidate)) return candidate;
+      }
+    }
+  }
   return null;
 }
 
@@ -208,10 +238,8 @@ function resolveFlatPhaseArtifactDiskPath(basePath: string, row: ArtifactRow): s
   if (!artifactType) return null;
 
   if (row.slice_id && row.task_id) {
-    const phaseDir = resolveMilestonePath(basePath, row.milestone_id);
-    if (!phaseDir || !isFlatPhaseDiskPath(basePath, phaseDir)) return null;
-    const candidate = join(phaseDir, buildTaskFileName(row.task_id, artifactType));
-    return existsSync(candidate) ? candidate : null;
+    const candidate = resolveTaskFile(basePath, row.milestone_id, row.slice_id, row.task_id, artifactType);
+    return candidate && isFlatPhaseDiskPath(basePath, candidate) ? candidate : null;
   }
 
   const candidate = row.slice_id
@@ -226,7 +254,7 @@ function resolveArtifactDiskPath(basePath: string, artifactPath: string, row?: A
     const flatPath = resolveFlatPhaseArtifactDiskPath(basePath, row);
     if (flatPath) return flatPath;
   }
-  return resolveLiteralArtifactDiskPath(basePath, artifactPath);
+  return resolveLiteralArtifactDiskPath(basePath, artifactPath, row);
 }
 
 function taskExistsInPlan(basePath: string, milestoneId: string, sliceId: string, taskId: string): boolean {
@@ -436,7 +464,9 @@ function staleMilestonesArtifactRowFixable(basePath: string, row: ArtifactRow, a
 
 function stalePhasesArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
   const issuePath = artifactPathRelativeToGsd(row.path);
-  return issuePath.startsWith(`${LAYOUT_SEGMENTS.level1}/`) && hasPresentMilestonesReplacement(basePath, row, artifactRows);
+  return issuePath.startsWith(`${LAYOUT_SEGMENTS.level1}/`) &&
+    (hasPresentFlatPhaseReplacement(basePath, row, artifactRows) ||
+      hasPresentMilestonesReplacement(basePath, row, artifactRows));
 }
 
 function staleArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
@@ -809,7 +839,11 @@ export async function checkEngineHealth(
   // block doctor.
   try {
     if (isDbAvailable()) {
-      checkProjectionCheckboxDbStatus(basePath, getAllMilestones().map((milestone) => milestone.id), issues);
+      checkProjectionCheckboxDbStatus(
+        basePath,
+        checkboxDbStatusMilestoneIds(basePath, getAllMilestones().map((milestone) => milestone.id)),
+        issues,
+      );
     }
   } catch {
     // Non-fatal: checkbox-vs-DB divergence check must never block doctor

package/src/resources/extensions/gsd/error-classifier.ts

@@ -65,8 +65,12 @@ const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|web
 // transient errors so auto-mode can retry with reduced budget or fall back to a larger-context model.
 // See: https://github.com/open-gsd/gsd-pi/issues/4528
 const SERVER_RE = /internal(?: server)?[ _-]?error|server[ _-]?error|500|502|503|overloaded|server_error|api_error|service.?unavailable|context (?:window|length) exceed|context window exceed/i;
+// Provider adapters throw this when an upstream stop reason reaches Pi before
+// the adapter knows how to map it. Keep the match scoped so plain "unknown"
+// runtime errors still pause for inspection instead of being retried forever.
+const PROVIDER_STOP_REASON_RE = /unhandled stop reason:\s*(?:abort|unknown)\b/i;
 // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
-const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
+const CONNECTION_RE = /terminated|\babort\b|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
 // Catch-all for V8 JSON.parse errors: all modern variants end with "in JSON at position \d+".
 // This eliminates the need to enumerate every error message variant individually.
 const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i;
@@ -103,7 +107,7 @@ const UNSUPPORTED_MODEL_SCOPE_RE = /\b(?:account|plan|tier|subscription)\b/i;
  *  3. Network (ECONNRESET, ETIMEDOUT, socket hang up, fetch failed, dns)
  *  4. Stream truncation (malformed JSON from mid-stream cut)
  *  5. Server (500/502/503, overloaded, server_error)
- *  6. Connection (terminated, ECONNREFUSED, EPIPE, other side closed)
+ *  6. Connection (terminated, abort/unknown stop reason, ECONNREFUSED, EPIPE, other side closed)
  *  7. Model error (400 invalid argument / payload rejected for this model)
  *  8. Unknown
  */
@@ -163,6 +167,13 @@ export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorCla
     return { kind: "rate-limit", retryAfterMs: delayMs };
   }
 
+  // Provider stop-reason adapter gaps are usually request/stream failures from
+  // the current model. Treat the scoped adapter message as fallback-eligible,
+  // but keep generic unknown errors on the indefinite pause path.
+  if (PROVIDER_STOP_REASON_RE.test(errorMsg)) {
+    return { kind: "connection", retryAfterMs: retryAfterMs ?? 15_000 };
+  }
+
   // 3. Network errors — same-model retry candidate
   if (NETWORK_RE.test(errorMsg)) {
     // Exclude if also matches permanent signals (already handled above for

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

@@ -111,6 +111,7 @@ export const EXEC_DEFAULTS = {
     "LOGNAME",
     "TMPDIR",
     "NODE_OPTIONS",
+    "NODE_PATH",
     "PYTHONPATH",
     "PYTHONIOENCODING",
   ] as const,

package/src/resources/extensions/gsd/flat-phase-migration.ts

@@ -155,6 +155,19 @@ function isInsideFlatProjectionBackup(backupDir: string, src: string): boolean {
   return src === phaseBackupDir || src.startsWith(`${phaseBackupDir}/`) || src.startsWith(`${phaseBackupDir}\\`);
 }
 
+function removeFlatProjectionBackup(backupDir: string): void {
+  const phaseBackupDir = join(backupDir, "__phases");
+  if (!existsSync(phaseBackupDir)) return;
+  try {
+    removePathWithRetries(phaseBackupDir);
+  } catch (err) {
+    logWarning(
+      "migration",
+      `flat-phase migration succeeded but could not remove temporary ${LAYOUT_SEGMENTS.level1}/ backup: ${(err as Error).message}`,
+    );
+  }
+}
+
 function restoreFlatProjectionFromBackup(basePath: string, backupDir: string): void {
   const phaseBackupDir = join(backupDir, "__phases");
   if (!existsSync(phaseBackupDir)) return;
@@ -494,4 +507,5 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       `flat-phase migration succeeded but could not remove ${LEGACY_MIGRATING_SEGMENT}: ${(err as Error).message}`,
     );
   }
+  removeFlatProjectionBackup(backupDir);
 }

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

@@ -385,10 +385,16 @@ const runtimeFilesCleanedUpRepos = new Set<string>();
 // ─── Integration Branch Metadata ───────────────────────────────────────────
 
 /**
- * Path to the milestone metadata file that stores the integration branch.
- * Format: .gsd/milestones/<MID>/<MID>-META.json
+ * Path to the milestone integration-branch metadata file.
+ * Format: .gsd/<MID>-META.json  (deliberately OUTSIDE milestones/<MID>/ so it
+ * cannot poison isLegacyMilestonesLayout — see ADR-045).
  */
-function milestoneMetaPath(basePath: string, milestoneId: string): string {
+export function milestoneMetaPath(basePath: string, milestoneId: string): string {
+  return join(gsdRoot(basePath), `${milestoneId}-META.json`);
+}
+
+/** Legacy location (pre-ADR-045). Read-only fallback for existing on-disk trees. */
+function legacyMilestoneMetaPath(basePath: string, milestoneId: string): string {
   return join(gsdRoot(basePath), "milestones", milestoneId, `${milestoneId}-META.json`);
 }
 
@@ -398,8 +404,12 @@ function milestoneMetaPath(basePath: string, milestoneId: string): string {
  */
 export function readIntegrationBranch(basePath: string, milestoneId: string): string | null {
   try {
-    const metaFile = milestoneMetaPath(basePath, milestoneId);
-    if (!existsSync(metaFile)) return null;
+    let metaFile = milestoneMetaPath(basePath, milestoneId);
+    if (!existsSync(metaFile)) {
+      const legacy = legacyMilestoneMetaPath(basePath, milestoneId);
+      if (!existsSync(legacy)) return null;
+      metaFile = legacy;
+    }
     const data = JSON.parse(readFileSync(metaFile, "utf-8"));
     const branch = data?.integrationBranch;
     if (typeof branch === "string" && branch.trim() !== "" && VALID_BRANCH_NAME.test(branch)) {
@@ -451,7 +461,10 @@ export function writeIntegrationBranch(
   if (existingBranch === branch) return;
 
   const metaFile = milestoneMetaPath(basePath, milestoneId);
-  mkdirSync(join(gsdRoot(basePath), "milestones", milestoneId), { recursive: true });
+  // Ensure the flat .gsd/ root exists (never milestones/<MID>/ — that would
+  // poison layout detection, ADR-045). In production .gsd/ already exists; this
+  // guards fresh trees so the write below can't ENOENT.
+  mkdirSync(gsdRoot(basePath), { recursive: true });
 
   // Merge with existing metadata if present
   let existing: Record<string, unknown> = {};