@opengsd/gsd-pi 1.9.0 → 1.10.0

package/dist/resources/extensions/gsd/compat/compat-marker.js

@@ -5,8 +5,8 @@
 // distinguish gsd-pi's own writes (expected) from external edits made by gsd-core
 // (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;
 /** Marker returned when no marker exists yet (fresh project, first gsd-pi run). */
@@ -32,6 +32,35 @@ export function normalizeForHash(content) {
 export function computeProjectionSha(content) {
     return createHash("sha256").update(normalizeForHash(content)).digest("hex").slice(0, 16);
 }
+function normalizeRealPath(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+function rootRelativeKey(rootPath, absPath) {
+    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) {
+    return rel.includes("\\") ? "\\" : "/";
+}
+export function deriveCompatProjectionKey(absPath, roots) {
+    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
@@ -39,7 +68,9 @@ export function computeProjectionSha(content) {
  * 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) {
+export function readCompatMarker(basePath, options = {}) {
+    const healInvalidKeys = options.healInvalidKeys ?? true;
+    const quarantineInvalid = options.quarantineInvalid ?? true;
     const path = compatMarkerPath(basePath);
     if (!existsSync(path))
         return emptyMarker();
@@ -55,11 +86,16 @@ export function readCompatMarker(basePath) {
         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
@@ -196,6 +232,45 @@ function isValidProjectionMap(x) {
     }
     return true;
 }
+function healMarkerProjectionKeys(basePath, marker) {
+    if (typeof marker !== "object" || marker === null)
+        return false;
+    const m = marker;
+    let changed = false;
+    if (typeof m.projections === "object" && m.projections !== null) {
+        changed = healProjectionMapKeys(basePath, ".gsd", m.projections) || changed;
+    }
+    const planning = m.planning;
+    if (typeof planning === "object" && planning !== null) {
+        const p = planning;
+        if (typeof p.projections === "object" && p.projections !== null) {
+            changed = healProjectionMapKeys(basePath, ".planning", p.projections) || changed;
+        }
+        if (typeof p.passthrough === "object" && p.passthrough !== null) {
+            changed = healProjectionMapKeys(basePath, ".planning", p.passthrough) || changed;
+        }
+    }
+    return changed;
+}
+function healProjectionMapKeys(basePath, rootName, map) {
+    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) {
     if (typeof x !== "object" || x === null)
         return false;

package/dist/resources/extensions/gsd/constants.js

@@ -24,36 +24,35 @@ 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 = [
     // 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/dist/resources/extensions/gsd/context-masker.js

@@ -1,22 +1,4 @@
-/**
- * Observation masking for GSD auto-mode sessions.
- *
- * Replaces tool result content older than N turns with a placeholder.
- * Reduces context bloat between compactions with zero LLM overhead.
- * Preserves message ordering, roles, and all assistant/user messages.
- *
- * Operates on provider payloads after convertToLlm:
- *
- * pi-ai Message[] payloads:
- *   - toolResult messages: { role: "toolResult", content: TextContent[] }
- *   - bash results are already converted to: { role: "user", content: [{type:"text",text:"..."}] }
- *     and start with "Ran `" from bashExecutionToText.
- *
- * OpenAI/Codex Responses payloads:
- *   - conversation items live in `input`, not `messages`
- *   - tool results are { type: "function_call_output", output: string | content[] }
- *   - bash results are user items with input_text content starting with "Ran `"
- */
+import { GSD_CONTEXT_MESSAGE_SENTINEL } from "./constants.js";
 const MASK_PLACEHOLDER = "[result masked — within summarized history]";
 const MASK_CONTENT_BLOCK = [{ type: "text", text: MASK_PLACEHOLDER }];
 const RESPONSES_MASK_CONTENT_BLOCK = [{ type: "input_text", text: MASK_PLACEHOLDER }];
@@ -52,6 +34,26 @@ function findTurnBoundary(messages, keepRecentTurns) {
     }
     return 0;
 }
+function countRealUserTurns(messages) {
+    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, keepRecentTurns) {
+    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..."}]}.
@@ -73,7 +75,8 @@ function isMaskableMessage(m) {
 }
 export function createObservationMask(keepRecentTurns = 8) {
     return (messages) => {
-        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) => {
@@ -104,6 +107,14 @@ function findResponsesTurnBoundary(items, keepRecentTurns) {
     }
     return 0;
 }
+function countResponsesRealUserTurns(items) {
+    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.
  *
@@ -113,7 +124,8 @@ function findResponsesTurnBoundary(items, keepRecentTurns) {
  */
 export function createResponsesInputObservationMask(keepRecentTurns = 8) {
     return (items) => {
-        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) => {
@@ -190,3 +202,67 @@ export function truncateResponsesInputResultItems(items, maxChars = 800) {
         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]",
+];
+function isGsdContextInjectionText(text) {
+    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) {
+    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) {
+    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) {
+    if (item.role !== "user")
+        return false;
+    return isGsdContextInjectionText(firstTextFromContent(item.content));
+}
+export function filterSupersededResponsesContextInjections(items) {
+    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/dist/resources/extensions/gsd/db/engine.js

@@ -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 { logError, logWarning } from "../workflow-logger.js";
 import { createDbAdapter } from "../db-adapter.js";
@@ -31,7 +31,10 @@ function getGsdRequire() {
     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/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -357,6 +357,28 @@ In `"parent"` mode, slice/task `targetRepositories` default to the declared chil
   - `"replace"` requires `prompt`.
   - `"skip"` is valid with no additional fields.
 
+- `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 already be classified by GSD as read-only planning specialists: `mnemo`, `scout`, `planner`, `reviewer`, `security`, or `tester`. The write gate still blocks source writes outside `.gsd/**`, unrestricted bash, stale subagent calls without agent identities, agents outside the global read-only registry, and agents not listed for the active unit.
+
+  Example:
+
+  ```yaml
+  planning_subagents:
+    plan-milestone:
+      allowed:
+        - scout
+        - planner
+        - security
+    plan-slice:
+      allowed:
+        - scout
+        - 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/dist/resources/extensions/gsd/doctor-engine-checks.js

@@ -3,7 +3,7 @@ import { isAbsolute, join, relative, sep } from "node:path";
 import { deleteArtifactByPath, getAllMilestones, getMilestoneSlices, getSliceTasks, isDbAvailable, isMemoriesFtsAvailable, repairTaskCompletionFromSummary, _getAdapter, } from "./gsd-db.js";
 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, } from "./paths.js";
+import { gsdProjectionRoot, gsdRoot, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile, resolveTaskFile, } from "./paths.js";
 import { deriveState } from "./state.js";
 import { isClosedStatus } from "./status-guards.js";
 import { workflowEventLogPath } from "./workflow-event-ledger.js";
@@ -58,6 +58,23 @@ function reportCheckboxDbStatusDivergence(issues, basePath, filePath, scope, uni
         fixable: false,
     });
 }
+function bareDuplicateMilestoneId(milestoneId) {
+    const match = milestoneId.match(/^(M\d{3})-[a-z0-9]{6}$/i);
+    return match?.[1]?.toUpperCase() ?? null;
+}
+function checkboxDbStatusMilestoneIds(basePath, milestoneIds) {
+    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, milestoneIds, issues) {
     for (const milestoneId of milestoneIds) {
         const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
@@ -152,11 +169,8 @@ function resolveFlatPhaseArtifactDiskPath(basePath, row) {
     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
         ? resolveSliceFile(basePath, row.milestone_id, row.slice_id, artifactType)
@@ -325,7 +339,9 @@ function staleMilestonesArtifactRowFixable(basePath, row, artifactRows) {
 }
 function stalePhasesArtifactRowFixable(basePath, row, artifactRows) {
     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, row, artifactRows) {
     return staleMilestonesArtifactRowFixable(basePath, row, artifactRows) ||
@@ -661,7 +677,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied, options)
     // block doctor.
     try {
         if (isDbAvailable()) {
-            checkProjectionCheckboxDbStatus(basePath, getAllMilestones().map((milestone) => milestone.id), issues);
+            checkProjectionCheckboxDbStatus(basePath, checkboxDbStatusMilestoneIds(basePath, getAllMilestones().map((milestone) => milestone.id)), issues);
         }
     }
     catch {

package/dist/resources/extensions/gsd/error-classifier.js

@@ -38,8 +38,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;
@@ -72,7 +76,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
  */
@@ -124,6 +128,12 @@ export function classifyError(errorMsg, retryAfterMs) {
         const delayMs = resetMatch ? Number(resetMatch[1]) * 1000 : 60_000;
         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/dist/resources/extensions/gsd/exec-sandbox.js

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

package/dist/resources/extensions/gsd/flat-phase-migration.js

@@ -130,6 +130,17 @@ function isInsideFlatProjectionBackup(backupDir, src) {
     const phaseBackupDir = join(backupDir, "__phases");
     return src === phaseBackupDir || src.startsWith(`${phaseBackupDir}/`) || src.startsWith(`${phaseBackupDir}\\`);
 }
+function removeFlatProjectionBackup(backupDir) {
+    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.message}`);
+    }
+}
 function restoreFlatProjectionFromBackup(basePath, backupDir) {
     const phaseBackupDir = join(backupDir, "__phases");
     if (!existsSync(phaseBackupDir))
@@ -433,4 +444,5 @@ export async function migrateToFlatPhase(basePath) {
     catch (err) {
         logWarning("migration", `flat-phase migration succeeded but could not remove ${LEGACY_MIGRATING_SEGMENT}: ${err.message}`);
     }
+    removeFlatProjectionBackup(backupDir);
 }

package/dist/resources/extensions/gsd/git-service.js

@@ -229,10 +229,15 @@ export const RUNTIME_EXCLUSION_PATHS = [
 const runtimeFilesCleanedUpRepos = new Set();
 // ─── 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, milestoneId) {
+export function milestoneMetaPath(basePath, milestoneId) {
+    return join(gsdRoot(basePath), `${milestoneId}-META.json`);
+}
+/** Legacy location (pre-ADR-045). Read-only fallback for existing on-disk trees. */
+function legacyMilestoneMetaPath(basePath, milestoneId) {
     return join(gsdRoot(basePath), "milestones", milestoneId, `${milestoneId}-META.json`);
 }
 /**
@@ -241,9 +246,13 @@ function milestoneMetaPath(basePath, milestoneId) {
  */
 export function readIntegrationBranch(basePath, milestoneId) {
     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)) {
@@ -295,7 +304,10 @@ export function writeIntegrationBranch(basePath, milestoneId, branch) {
     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 = {};
     try {