gsd-pi 2.76.0 → 2.77.0-dev.1d17f366c

package/dist/resources/extensions/gsd/tools/complete-task.js

@@ -21,6 +21,7 @@ import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { isStaleWrite } from "../auto/turn-epoch.js";
 import { buildEscalationArtifact, writeEscalationArtifact } from "../escalation.js";
 /**
  * Map an execute-task-owned gate id to the CompleteTaskParams field whose
@@ -167,6 +168,18 @@ export async function handleCompleteTask(params, basePath) {
         }
         const existingTask = getTask(params.milestoneId, params.sliceId, params.taskId);
         if (existingTask && isClosedStatus(existingTask.status)) {
+            // Stale-turn path: a timed-out turn that was superseded by recovery
+            // can still reach this code when its LLM call eventually returns and
+            // invokes gsd_complete_task. Returning an error would produce noisy
+            // "already complete — use reopen first" logs in the orphaned turn.
+            // Instead, signal the duplicate via a non-mutating success shape that
+            // callers can detect via `duplicate: true` / `stale: true`.
+            if (isStaleWrite("complete-task")) {
+                // Sentinel handled below — outside the transaction — so we don't
+                // render SUMMARY.md or flip plan checkboxes for a stale duplicate.
+                guardError = "__stale_duplicate__";
+                return;
+            }
             guardError = `task ${params.taskId} is already complete — use gsd_task_reopen first if you need to redo it`;
             return;
         }
@@ -201,6 +214,24 @@ export async function handleCompleteTask(params, basePath) {
             });
         }
     });
+    if (guardError === "__stale_duplicate__") {
+        // Orphaned-turn duplicate: the task is already complete from the
+        // superseded turn's earlier (real) call. Return a non-mutating success
+        // so the stale LLM tool call unwinds cleanly. summaryPath is synthesized
+        // from the existing on-disk layout; no file is written.
+        const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
+        const staleSummaryPath = tasksDir
+            ? join(tasksDir, `${params.taskId}-SUMMARY.md`)
+            : join(basePath, ".gsd", "milestones", params.milestoneId, "slices", params.sliceId, "tasks", `${params.taskId}-SUMMARY.md`);
+        return {
+            taskId: params.taskId,
+            sliceId: params.sliceId,
+            milestoneId: params.milestoneId,
+            summaryPath: staleSummaryPath,
+            duplicate: true,
+            stale: true,
+        };
+    }
     if (guardError) {
         return { error: guardError };
     }

package/dist/resources/extensions/gsd/tools/exec-search-tool.js

@@ -0,0 +1,59 @@
+// 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 } from "../exec-history.js";
+export function executeExecSearch(params, opts) {
+    const searchOpts = {
+        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 = [`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) {
+    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/dist/resources/extensions/gsd/tools/exec-tool.js

@@ -0,0 +1,126 @@
+// 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, } from "../exec-sandbox.js";
+import { isContextModeEnabled } from "../preferences-types.js";
+export function buildExecOptions(baseDir, cfg, extras) {
+    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, fallback, min, max) {
+    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) {
+    return isContextModeEnabled(prefs);
+}
+function disabledResult() {
+    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) {
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        details: { operation: "gsd_exec", error: "invalid_params", detail: message },
+        isError: true,
+    };
+}
+export async function executeGsdExec(params, deps) {
+    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) {
+    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) {
+    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/dist/resources/extensions/gsd/tools/memory-tools.js

@@ -58,7 +58,8 @@ export function executeMemoryCapture(params) {
     const confidence = clampConfidence(params.confidence);
     const scope = normalizeScope(params.scope);
     const tags = normalizeTags(params.tags);
-    const id = createMemory({ category, content, confidence, scope, tags });
+    const structuredFields = normalizeStructuredFields(params.structuredFields);
+    const id = createMemory({ category, content, confidence, scope, tags, structuredFields });
     if (!id) {
         return {
             content: [{ type: "text", text: "Error: failed to create memory." }],
@@ -82,6 +83,19 @@ function normalizeTags(value) {
         return [];
     return value.filter((t) => typeof t === "string" && t.trim().length > 0).slice(0, 10);
 }
+function normalizeStructuredFields(value) {
+    if (value == null)
+        return null;
+    if (typeof value !== "object" || Array.isArray(value))
+        return null;
+    // Only accept plain objects (Object.prototype or null prototype). Class
+    // instances and exotic objects won't round-trip cleanly through JSON, so
+    // reject them here instead of producing a partially-serialized payload.
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && proto !== Object.prototype)
+        return null;
+    return value;
+}
 function clampConfidence(value) {
     if (typeof value !== "number" || !Number.isFinite(value))
         return 0.8;
@@ -200,6 +214,16 @@ function includeSupersededMemories(rankedActive) {
                     /* leave empty */
                 }
             }
+            let structuredFields = null;
+            if (typeof row["structured_fields"] === "string" && row["structured_fields"].length > 0) {
+                try {
+                    const parsed = JSON.parse(row["structured_fields"]);
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        structuredFields = parsed;
+                    }
+                }
+                catch { /* leave null */ }
+            }
             return {
                 seq: row["seq"],
                 id: row["id"],
@@ -214,6 +238,7 @@ function includeSupersededMemories(rankedActive) {
                 hit_count: row["hit_count"],
                 scope: row["scope"] ?? "project",
                 tags,
+                structured_fields: structuredFields,
             };
         });
     }

package/dist/resources/extensions/gsd/tools/resume-tool.js

@@ -0,0 +1,23 @@
+// 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 function executeResume(_params, opts) {
+    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/dist/resources/extensions/gsd/uok/audit.js

@@ -1,6 +1,8 @@
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
+import { isStaleWrite } from "../auto/turn-epoch.js";
+import { withFileLockSync } from "../file-lock.js";
 import { gsdRoot } from "../paths.js";
 import { isDbAvailable, insertAuditEvent } from "../gsd-db.js";
 function auditLogPath(basePath) {
@@ -22,9 +24,23 @@ export function buildAuditEnvelope(args) {
     };
 }
 export function emitUokAuditEvent(basePath, event) {
+    // Drop writes from a turn superseded by timeout recovery / cancellation.
+    if (isStaleWrite("uok-audit"))
+        return;
     try {
         ensureAuditDir(basePath);
-        appendFileSync(auditLogPath(basePath), `${JSON.stringify(event)}\n`, "utf-8");
+        const path = auditLogPath(basePath);
+        // proper-lockfile requires the target file to exist before locking.
+        // Touch it via open(O_APPEND|O_CREAT) so the first writer wins the race
+        // atomically at the kernel level.
+        if (!existsSync(path))
+            closeSync(openSync(path, "a"));
+        // onLocked: "skip" — audit writes are best-effort; under heavy contention
+        // POSIX O_APPEND atomicity still protects small line writes, so skipping
+        // the lock rather than stalling orchestration is the correct tradeoff.
+        withFileLockSync(path, () => {
+            appendFileSync(path, `${JSON.stringify(event)}\n`, "utf-8");
+        }, { onLocked: "skip" });
     }
     catch {
         // Best-effort: audit writes must never break orchestration.

package/dist/resources/extensions/gsd/uok/dispatch-envelope.js

@@ -0,0 +1,33 @@
+export function buildDispatchEnvelope(input) {
+    return {
+        action: input.action,
+        nodeKind: input.node?.kind,
+        unitType: input.unitType,
+        unitId: input.unitId,
+        prompt: input.prompt,
+        reason: {
+            reasonCode: input.reasonCode,
+            summary: input.summary,
+            evidence: input.evidence,
+            blockedBy: input.blockedBy,
+        },
+        gateVerdict: input.gateVerdict,
+        constraints: input.node
+            ? {
+                reads: input.node.reads,
+                writes: input.node.writes,
+                dependsOn: input.node.dependsOn,
+            }
+            : undefined,
+        trace: input.trace,
+    };
+}
+export function explainDispatch(envelope) {
+    const subject = envelope.unitType && envelope.unitId
+        ? `${envelope.unitType} ${envelope.unitId}`
+        : envelope.nodeKind ?? envelope.action;
+    const blocked = envelope.reason.blockedBy && envelope.reason.blockedBy.length > 0
+        ? ` Blocked by: ${envelope.reason.blockedBy.map((b) => `${b.kind}:${b.id}`).join(", ")}.`
+        : "";
+    return `[${envelope.reason.reasonCode}] ${subject}: ${envelope.reason.summary}.${blocked}`;
+}

package/dist/resources/extensions/gsd/uok/execution-graph.js

@@ -68,6 +68,16 @@ export function buildSidecarQueueNodes(queue) {
         metadata: { index },
     }));
 }
+export function buildExecutionGraphSnapshot(nodes, phase) {
+    const sorted = topologicalSort(nodes);
+    return {
+        capturedAt: new Date().toISOString(),
+        phase,
+        nodes: sorted,
+        order: sorted.map((node) => node.id),
+        conflicts: detectFileConflicts(nodes),
+    };
+}
 export async function scheduleSidecarQueue(queue) {
     if (queue.length <= 1)
         return [...queue];

package/dist/resources/extensions/gsd/uok/gitops.js

@@ -32,7 +32,7 @@ export function writeTurnGitTransaction(args) {
         },
     }));
 }
-export function writeTurnCloseoutGitRecord(basePath, record) {
+export function writeTurnCloseoutGitRecord(basePath, record, metadata) {
     writeTurnGitTransaction({
         basePath,
         traceId: record.traceId,
@@ -45,6 +45,7 @@ export function writeTurnCloseoutGitRecord(basePath, record) {
         status: record.failureClass === "git" ? "failed" : "ok",
         error: record.failureClass === "git" ? "git closeout failure" : undefined,
         metadata: {
+            ...(metadata ?? {}),
             turnStatus: record.status,
             finishedAt: record.finishedAt,
             activityFile: record.activityFile,

package/dist/resources/extensions/gsd/uok/loop-adapter.js

@@ -1,12 +1,35 @@
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import { writeTurnCloseoutGitRecord, writeTurnGitTransaction } from "./gitops.js";
+import { acquireWriterToken, nextWriteRecord, releaseWriterToken } from "./writer.js";
 export function createTurnObserver(options) {
     let current = null;
+    let writerToken = null;
     const phaseResults = [];
+    function nextSequenceMetadata(category, operation, metadata) {
+        if (!writerToken)
+            return metadata ?? {};
+        const record = nextWriteRecord({
+            basePath: options.basePath,
+            token: writerToken,
+            category,
+            operation,
+            metadata,
+        });
+        return {
+            ...(metadata ?? {}),
+            writeSequence: record.sequence.sequence,
+            writerTokenId: record.writerToken.tokenId,
+        };
+    }
     return {
         onTurnStart(contract) {
             current = contract;
             phaseResults.length = 0;
+            writerToken = acquireWriterToken({
+                basePath: options.basePath,
+                traceId: contract.traceId,
+                turnId: contract.turnId,
+            });
             if (options.enableGitops) {
                 writeTurnGitTransaction({
                     basePath: options.basePath,
@@ -18,10 +41,10 @@ export function createTurnObserver(options) {
                     action: options.gitAction,
                     push: options.gitPush,
                     status: "ok",
-                    metadata: {
+                    metadata: nextSequenceMetadata("gitops", "insert", {
                         iteration: contract.iteration,
                         sidecarKind: contract.sidecarKind,
-                    },
+                    }),
                 });
             }
             if (options.enableAudit) {
@@ -30,12 +53,12 @@ export function createTurnObserver(options) {
                     turnId: contract.turnId,
                     category: "orchestration",
                     type: "turn-start",
-                    payload: {
+                    payload: nextSequenceMetadata("audit", "append", {
                         iteration: contract.iteration,
                         unitType: contract.unitType,
                         unitId: contract.unitId,
                         sidecarKind: contract.sidecarKind,
-                    },
+                    }),
                 }));
             }
         },
@@ -59,7 +82,7 @@ export function createTurnObserver(options) {
                     action: options.gitAction,
                     push: options.gitPush,
                     status: "ok",
-                    metadata: { action },
+                    metadata: nextSequenceMetadata("gitops", "update", { action }),
                 });
             }
             if (phase === "unit") {
@@ -73,7 +96,7 @@ export function createTurnObserver(options) {
                     action: options.gitAction,
                     push: options.gitPush,
                     status: "ok",
-                    metadata: { action },
+                    metadata: nextSequenceMetadata("gitops", "update", { action }),
                 });
             }
             if (phase === "finalize") {
@@ -87,7 +110,7 @@ export function createTurnObserver(options) {
                     action: options.gitAction,
                     push: options.gitPush,
                     status: "ok",
-                    metadata: { action },
+                    metadata: nextSequenceMetadata("gitops", "update", { action }),
                 });
             }
         },
@@ -102,14 +125,14 @@ export function createTurnObserver(options) {
                     turnId: merged.turnId,
                     category: "orchestration",
                     type: "turn-result",
-                    payload: {
+                    payload: nextSequenceMetadata("audit", "append", {
                         unitType: merged.unitType,
                         unitId: merged.unitId,
                         status: merged.status,
                         failureClass: merged.failureClass,
                         error: merged.error,
                         phaseCount: merged.phaseResults.length,
-                    },
+                    }),
                 }));
             }
             if (options.enableGitops) {
@@ -124,8 +147,12 @@ export function createTurnObserver(options) {
                     gitPushed: options.gitPush,
                     finishedAt: merged.finishedAt,
                 };
-                writeTurnCloseoutGitRecord(options.basePath, closeout);
+                writeTurnCloseoutGitRecord(options.basePath, closeout, nextSequenceMetadata("gitops", "update", { action: "record" }));
+            }
+            if (writerToken) {
+                releaseWriterToken(options.basePath, writerToken);
             }
+            writerToken = null;
             current = null;
             phaseResults.length = 0;
         },

package/dist/resources/extensions/gsd/uok/parity-report.js

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "../paths.js";
+function parityLogPath(basePath) {
+    return join(gsdRoot(basePath), "runtime", "uok-parity.jsonl");
+}
+function reportPath(basePath) {
+    return join(gsdRoot(basePath), "runtime", "uok-parity-report.json");
+}
+function increment(bucket, key) {
+    const normalized = key && key.trim().length > 0 ? key : "unknown";
+    bucket[normalized] = (bucket[normalized] ?? 0) + 1;
+}
+export function parseParityEvents(raw) {
+    return raw
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return { status: "error", error: "invalid parity json line" };
+        }
+    });
+}
+export function buildParityReport(events, sourcePath) {
+    const paths = {};
+    const statuses = {};
+    const criticalMismatches = [];
+    let fallbackInvocations = 0;
+    for (const event of events) {
+        increment(paths, event.path);
+        increment(statuses, event.status);
+        if (event.path === "legacy-fallback")
+            fallbackInvocations += 1;
+        if (event.status === "error") {
+            criticalMismatches.push(event.error ?? "parity event reported error");
+        }
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        sourcePath,
+        totalEvents: events.length,
+        paths,
+        statuses,
+        criticalMismatches,
+        fallbackInvocations,
+    };
+}
+export function writeParityReport(basePath) {
+    const sourcePath = parityLogPath(basePath);
+    const raw = existsSync(sourcePath) ? readFileSync(sourcePath, "utf-8") : "";
+    const report = buildParityReport(parseParityEvents(raw), sourcePath);
+    mkdirSync(join(gsdRoot(basePath), "runtime"), { recursive: true });
+    writeFileSync(reportPath(basePath), JSON.stringify(report, null, 2) + "\n", "utf-8");
+    return report;
+}

package/dist/resources/extensions/gsd/uok/plan-v2.js

@@ -3,12 +3,15 @@ import { join } from "node:path";
 import { gsdRoot, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "../gsd-db.js";
 const PLAN_V2_CLARIFY_ROUND_LIMIT = 3;
-const EXECUTION_ENTRY_PHASES = new Set([
+export const EXECUTION_ENTRY_PHASES = new Set([
     "executing",
     "summarizing",
     "validating-milestone",
     "completing-milestone",
 ]);
+export function isExecutionEntryPhase(phase) {
+    return EXECUTION_ENTRY_PHASES.has(phase);
+}
 function graphOutputPath(basePath) {
     return join(gsdRoot(basePath), "runtime", "uok-plan-v2-graph.json");
 }
@@ -22,6 +25,29 @@ function hasFileContent(path) {
         return false;
     }
 }
+function getArtifactLookupBases(basePath) {
+    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, milestoneId, suffix) {
+    const bases = getArtifactLookupBases(basePath);
+    for (const candidateBase of bases) {
+        if (hasFileContent(resolveMilestoneFile(candidateBase, milestoneId, suffix))) {
+            return true;
+        }
+    }
+    return false;
+}
+export function hasFinalizedMilestoneContext(basePath, milestoneId) {
+    return hasMilestoneFileContent(basePath, milestoneId, "CONTEXT");
+}
+export function isMissingFinalizedContextResult(result) {
+    return !result.ok && result.finalizedContextIncluded === false;
+}
 function countSliceResearchArtifacts(basePath, milestoneId, slices) {
     let count = 0;
     for (const slice of slices) {
@@ -31,9 +57,6 @@ function countSliceResearchArtifacts(basePath, milestoneId, slices) {
     }
     return count;
 }
-function isExecutionEntryPhase(phase) {
-    return EXECUTION_ENTRY_PHASES.has(phase);
-}
 export function compileUnitGraphFromState(basePath, state) {
     const mid = state.activeMilestone?.id;
     if (!mid)
@@ -43,9 +66,9 @@ export function compileUnitGraphFromState(basePath, state) {
     const slices = getMilestoneSlices(mid).sort((a, b) => Number(a.sequence ?? 0) - Number(b.sequence ?? 0));
     const nodes = [];
     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) {
         const reason = draftContextIncluded