gsd-pi 2.77.0-dev.eaa4973bc → 2.78.0-dev.aeeb2ca00

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

@@ -15,6 +15,7 @@ import { logWarning, logError } from './workflow-logger.js';
 import { extractVerdict } from './verdict-parser.js';
 import { loadEffectiveGSDPreferences } from './preferences.js';
 import { detectPendingEscalation } from './escalation.js';
+import { isTerminalMilestoneSummaryContent } from './milestone-summary-classifier.js';
 import { isDbAvailable, wasDbOpenAttempted, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, insertMilestone, insertSlice, insertTask, updateSliceStatus, updateTaskStatus, getPendingGateCountForTurn, autoHealSketchFlags, } from './gsd-db.js';
 /**
  * A "ghost" milestone directory contains only META.json (and no substantive
@@ -81,6 +82,10 @@ export function isMilestoneComplete(roadmap) {
 export function isValidationTerminal(validationContent) {
     return extractVerdict(validationContent) != null;
 }
+async function isTerminalMilestoneSummaryFile(path, loader) {
+    const content = await loader(path);
+    return content != null && isTerminalMilestoneSummaryContent(content);
+}
 const CACHE_TTL_MS = 100;
 let _stateCache = null;
 // ── Telemetry counters for derive-path observability ────────────────────────
@@ -138,18 +143,19 @@ export async function getActiveMilestoneId(basePath) {
         const content = roadmapFile ? await loadFile(roadmapFile) : null;
         if (!content) {
             const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (summaryFile)
+            if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, loadFile))
                 continue;
             if (isGhostMilestone(basePath, mid))
                 continue;
             return mid;
         }
         const roadmap = parseRoadmap(content);
-        if (!isMilestoneComplete(roadmap)) {
-            const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (!summaryFile)
-                return mid;
-        }
+        const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
+        if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, loadFile))
+            continue;
+        if (!isMilestoneComplete(roadmap))
+            return mid;
+        return mid;
     }
     return null;
 }
@@ -182,7 +188,7 @@ export async function deriveState(basePath) {
             let synced = false;
             for (const diskId of diskIds) {
                 if (!isGhostMilestone(basePath, diskId)) {
-                    insertMilestone({ id: diskId, status: 'active' });
+                    insertMilestone(diskMilestoneInsert(basePath, diskId));
                     synced = true;
                 }
             }
@@ -240,6 +246,36 @@ function extractContextTitle(content, fallback) {
 // isStatusDone replaced by isClosedStatus from status-guards.ts (single source of truth).
 // Alias kept for backward compatibility within this file.
 const isStatusDone = isClosedStatus;
+function loadSync(path) {
+    if (!path)
+        return null;
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+function diskMilestoneInsert(basePath, mid) {
+    const contextContent = loadSync(resolveMilestoneFile(basePath, mid, "CONTEXT"));
+    const draftContent = !contextContent ? loadSync(resolveMilestoneFile(basePath, mid, "CONTEXT-DRAFT")) : null;
+    const roadmapContent = loadSync(resolveMilestoneFile(basePath, mid, "ROADMAP"));
+    const summaryContent = loadSync(resolveMilestoneFile(basePath, mid, "SUMMARY"));
+    const roadmap = roadmapContent ? parseRoadmap(roadmapContent) : null;
+    const summary = summaryContent ? parseSummary(summaryContent) : null;
+    const summaryTerminal = summaryContent != null && isTerminalMilestoneSummaryContent(summaryContent);
+    const parked = resolveMilestoneFile(basePath, mid, "PARKED") !== null;
+    return {
+        id: mid,
+        title: roadmap
+            ? stripMilestonePrefix(roadmap.title)
+            : (contextContent || draftContent)
+                ? extractContextTitle(contextContent || draftContent, mid)
+                : (summary?.title || mid),
+        status: parked ? "parked" : summaryTerminal ? "complete" : "active",
+        depends_on: parseContextDependsOn(contextContent ?? draftContent),
+    };
+}
 /**
  * Derive GSD state from the milestones/slices/tasks DB tables.
  * Flag files (PARKED, VALIDATION, CONTINUE, REPLAN, REPLAN-TRIGGER, CONTEXT-DRAFT)
@@ -255,7 +291,7 @@ function reconcileDiskToDb(basePath) {
     let synced = false;
     for (const diskId of diskIds) {
         if (!dbIdSet.has(diskId) && !isGhostMilestone(basePath, diskId)) {
-            insertMilestone({ id: diskId, status: 'active' });
+            insertMilestone(diskMilestoneInsert(basePath, diskId));
             synced = true;
         }
     }
@@ -550,9 +586,6 @@ function resolveSliceDependencies(activeMilestoneSlices) {
             return { activeSlice: null, activeSliceRow: null };
         }
     }
-    // First pass: find a slice with ALL dependencies satisfied (strict)
-    let bestFallback = null;
-    let bestFallbackSatisfied = -1;
     for (const s of activeMilestoneSlices) {
         if (isStatusDone(s.status))
             continue;
@@ -561,36 +594,25 @@ function resolveSliceDependencies(activeMilestoneSlices) {
         if (s.depends.every(dep => doneSliceIds.has(dep))) {
             return { activeSlice: { id: s.id, title: s.title }, activeSliceRow: s };
         }
-        // Track the slice with the most satisfied dependencies as fallback
-        const satisfied = s.depends.filter(dep => doneSliceIds.has(dep)).length;
-        if (satisfied > bestFallbackSatisfied || (satisfied === bestFallbackSatisfied && !bestFallback)) {
-            bestFallback = s;
-            bestFallbackSatisfied = satisfied;
-        }
-    }
-    // Fallback: if no slice has all deps met but there ARE incomplete non-deferred
-    // slices, pick the one with the most deps satisfied. This prevents hard-blocking
-    // when dependency metadata is stale (e.g. after reassessment added/removed slices)
-    // or when deps reference slices from previous milestones.
-    if (bestFallback) {
-        const unmet = bestFallback.depends.filter(dep => !doneSliceIds.has(dep));
-        logWarning("state", `No slice has all deps satisfied — falling back to ${bestFallback.id} ` +
-            `(${bestFallbackSatisfied}/${bestFallback.depends.length} deps met, ` +
-            `unmet: ${unmet.join(", ")})`, { mid: activeMilestoneSlices[0]?.milestone_id, sid: bestFallback.id });
-        return { activeSlice: { id: bestFallback.id, title: bestFallback.title }, activeSliceRow: bestFallback };
     }
     return { activeSlice: null, activeSliceRow: null };
 }
 async function reconcileSliceTasks(basePath, milestoneId, sliceId, planFile) {
     let tasks = getSliceTasks(milestoneId, sliceId);
-    if (tasks.length === 0 && planFile) {
+    // #3600/#4974: import missing plan-file tasks even when the DB already has
+    // a partial task set. Existing DB task statuses stay authoritative.
+    if (planFile) {
         try {
             const planContent = await loadFile(planFile);
             if (planContent) {
                 const diskPlan = parsePlan(planContent);
                 if (diskPlan.tasks.length > 0) {
+                    const dbTaskIds = new Set(tasks.map(t => t.id));
+                    let inserted = 0;
                     for (let i = 0; i < diskPlan.tasks.length; i++) {
                         const t = diskPlan.tasks[i];
+                        if (dbTaskIds.has(t.id))
+                            continue;
                         try {
                             insertTask({
                                 id: t.id,
@@ -600,13 +622,16 @@ async function reconcileSliceTasks(basePath, milestoneId, sliceId, planFile) {
                                 status: t.done ? 'complete' : 'pending',
                                 sequence: i + 1,
                             });
+                            inserted++;
                         }
                         catch (insertErr) {
                             logWarning("reconcile", `failed to insert task ${t.id} from plan file: ${insertErr instanceof Error ? insertErr.message : String(insertErr)}`);
                         }
                     }
-                    tasks = getSliceTasks(milestoneId, sliceId);
-                    logWarning("reconcile", `imported ${tasks.length} tasks from plan file for ${milestoneId}/${sliceId} — DB was empty (#3600)`, { mid: milestoneId, sid: sliceId });
+                    if (inserted > 0) {
+                        tasks = getSliceTasks(milestoneId, sliceId);
+                        logWarning("reconcile", `imported ${inserted} missing task(s) from plan file for ${milestoneId}/${sliceId}`, { mid: milestoneId, sid: sliceId });
+                    }
                 }
             }
         }
@@ -988,7 +1013,7 @@ export async function _deriveStateImpl(basePath) {
         const rc = rf ? await cachedLoadFile(rf) : null;
         if (!rc) {
             const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (sf)
+            if (sf && await isTerminalMilestoneSummaryFile(sf, cachedLoadFile))
                 completeMilestoneIds.add(mid);
             continue;
         }
@@ -998,12 +1023,12 @@ export async function _deriveStateImpl(basePath) {
             // Summary is the terminal artifact — if it exists, the milestone is
             // complete even when roadmap checkboxes weren't ticked (#864).
             const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (sf)
+            if (sf && await isTerminalMilestoneSummaryFile(sf, cachedLoadFile))
                 completeMilestoneIds.add(mid);
             continue;
         }
         const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
-        if (sf)
+        if (sf && await isTerminalMilestoneSummaryFile(sf, cachedLoadFile))
             completeMilestoneIds.add(mid);
     }
     // Phase 2: Build registry using cached roadmaps (no re-parsing or re-reading)
@@ -1028,12 +1053,14 @@ export async function _deriveStateImpl(basePath) {
             const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
             if (summaryFile) {
                 const summaryContent = await cachedLoadFile(summaryFile);
-                const summaryTitle = summaryContent
-                    ? (parseSummary(summaryContent).title || mid)
-                    : mid;
-                registry.push({ id: mid, title: summaryTitle, status: 'complete' });
-                completeMilestoneIds.add(mid);
-                continue;
+                if (summaryContent != null && isTerminalMilestoneSummaryContent(summaryContent)) {
+                    const summaryTitle = summaryContent
+                        ? (parseSummary(summaryContent).title || mid)
+                        : mid;
+                    registry.push({ id: mid, title: summaryTitle, status: 'complete' });
+                    completeMilestoneIds.add(mid);
+                    continue;
+                }
             }
             // Ghost milestone (only META.json, no CONTEXT/ROADMAP/SUMMARY) — skip entirely
             if (isGhostMilestone(basePath, mid))
@@ -1087,7 +1114,7 @@ export async function _deriveStateImpl(basePath) {
             const verdict = validationContent ? extractVerdict(validationContent) : undefined;
             // needs-remediation is terminal but requires re-validation (#3596)
             const needsRevalidation = !validationTerminal || verdict === 'needs-remediation';
-            if (summaryFile) {
+            if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, cachedLoadFile)) {
                 // Summary exists → milestone is complete regardless of validation state.
                 // The summary is the terminal artifact (#864).
                 registry.push({ id: mid, title, status: 'complete' });
@@ -1118,7 +1145,7 @@ export async function _deriveStateImpl(basePath) {
             // Roadmap slices not all checked — but if a summary exists, the milestone
             // is still complete. The summary is the terminal artifact (#864).
             const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (summaryFile) {
+            if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, cachedLoadFile)) {
                 registry.push({ id: mid, title, status: 'complete' });
             }
             else if (!activeMilestoneFound) {
@@ -1387,8 +1414,6 @@ export async function _deriveStateImpl(basePath) {
         }
     }
     else {
-        let bestFallbackLegacy = null;
-        let bestFallbackLegacySatisfied = -1;
         for (const s of activeRoadmap.slices) {
             if (s.done)
                 continue;
@@ -1396,20 +1421,6 @@ export async function _deriveStateImpl(basePath) {
                 activeSlice = { id: s.id, title: s.title };
                 break;
             }
-            // Track best fallback
-            const satisfied = s.depends.filter(dep => doneSliceIds.has(dep)).length;
-            if (satisfied > bestFallbackLegacySatisfied) {
-                bestFallbackLegacy = s;
-                bestFallbackLegacySatisfied = satisfied;
-            }
-        }
-        // Fallback: if no slice has all deps met, pick the one with the most deps satisfied
-        if (!activeSlice && bestFallbackLegacy) {
-            const unmet = bestFallbackLegacy.depends.filter(dep => !doneSliceIds.has(dep));
-            logWarning("state", `No slice has all deps satisfied — falling back to ${bestFallbackLegacy.id} ` +
-                `(${bestFallbackLegacySatisfied}/${bestFallbackLegacy.depends.length} deps met, ` +
-                `unmet: ${unmet.join(", ")})`);
-            activeSlice = { id: bestFallbackLegacy.id, title: bestFallbackLegacy.title };
         }
     }
     if (!activeSlice) {

package/dist/resources/extensions/gsd/sync-lock.js

@@ -1,10 +1,9 @@
 // GSD Extension — Advisory Sync Lock
 // Prevents concurrent worktree syncs from colliding via a simple file lock.
-// Stale locks (mtime > 60s) are auto-overridden. Lock acquisition waits up
-// to 5 seconds then skips non-fatally.
-import { existsSync, statSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import { atomicWriteSync } from "./atomic-write.js";
+// Stale locks (mtime > 60s, owner PID confirmed dead) are overridden. Lock
+// acquisition waits up to 5 seconds then skips non-fatally.
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
 const STALE_THRESHOLD_MS = 60_000; // 60 seconds
 const DEFAULT_TIMEOUT_MS = 5_000; // 5 seconds
 const SPIN_INTERVAL_MS = 100; // 100ms polling interval
@@ -17,60 +16,117 @@ function lockFilePath(basePath) {
 function sleepSync(ms) {
     Atomics.wait(SLEEP_VIEW, 0, 0, ms);
 }
+/** True if the given PID is alive in the current process namespace. */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EPERM")
+            return true;
+        return false;
+    }
+}
+/**
+ * Atomically create the lock file with `O_EXCL` semantics. Returns true on
+ * exclusive create, false if the file already existed. Any other error
+ * propagates.
+ */
+function tryCreateLockFile(lp, payload) {
+    // Ensure parent dir exists (`atomicWriteSync` previously did this implicitly).
+    try {
+        mkdirSync(dirname(lp), { recursive: true });
+    }
+    catch {
+        /* best-effort */
+    }
+    let fd;
+    try {
+        // "wx" → O_WRONLY | O_CREAT | O_EXCL — atomic create-if-not-exists on POSIX.
+        fd = openSync(lp, "wx");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EEXIST")
+            return false;
+        throw err;
+    }
+    try {
+        writeSync(fd, payload);
+    }
+    finally {
+        closeSync(fd);
+    }
+    return true;
+}
 /**
  * Acquire an advisory sync lock for the given basePath.
  * Returns { acquired: true } on success, { acquired: false } after timeout.
  *
- * - Creates lock file at {basePath}/.gsd/sync.lock with JSON { pid, acquired_at }
- * - If lock exists and mtime > 60s (stale), overrides it
- * - If lock exists and not stale, spins up to timeoutMs before giving up
+ * Replaces a non-atomic `existsSync` + `atomicWriteSync` (write-temp+rename,
+ * which is not exclusive-create) sequence that allowed two callers to both
+ * believe they had acquired the lock, corrupting the event log.
+ * (Issue #4980 CRIT-4)
+ *
+ * Stale-lock override now also verifies the recorded owner PID is dead
+ * before stealing — prevents a slow event-loop pause (>60s under heavy I/O)
+ * from making a legitimately-held lock appear stale and get stolen.
+ * (Issue #4980 M-concurrency-3)
  */
 export function acquireSyncLock(basePath, timeoutMs = DEFAULT_TIMEOUT_MS) {
     const lp = lockFilePath(basePath);
     const deadline = Date.now() + timeoutMs;
+    const lockData = JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() }, null, 2);
     while (true) {
-        // Check if lock file exists
-        if (existsSync(lp)) {
-            // Check staleness
-            try {
-                const stat = statSync(lp);
-                const age = Date.now() - stat.mtimeMs;
-                if (age > STALE_THRESHOLD_MS) {
-                    // Stale lock — override it
-                    try {
-                        unlinkSync(lp);
+        // First try the fast path: atomic create. No check-then-write race.
+        try {
+            if (tryCreateLockFile(lp, lockData)) {
+                return { acquired: true };
+            }
+        }
+        catch {
+            /* unexpected — fall through to retry */
+        }
+        // File exists. Decide whether to steal (stale + owner dead) or wait.
+        let canSteal = false;
+        try {
+            const stat = statSync(lp);
+            const age = Date.now() - stat.mtimeMs;
+            if (age > STALE_THRESHOLD_MS) {
+                // Verify the recorded owner PID is dead before stealing.
+                let ownerAlive = false;
+                try {
+                    const data = JSON.parse(readFileSync(lp, "utf-8"));
+                    if (typeof data.pid === "number" && data.pid !== process.pid) {
+                        ownerAlive = isPidAlive(data.pid);
                     }
-                    catch { /* race: already removed */ }
                 }
-                else {
-                    // Lock is held and not stale — wait or give up
-                    if (Date.now() >= deadline) {
-                        return { acquired: false };
-                    }
-                    sleepSync(SPIN_INTERVAL_MS);
-                    continue;
+                catch {
+                    // Lock contents unreadable — be conservative and steal only on age.
+                    // A garbage lock file that we cannot parse is safer to remove than
+                    // to leave wedging the lock indefinitely.
                 }
+                canSteal = !ownerAlive;
             }
-            catch {
-                // stat failed (file removed between exists check and stat) — try to acquire
-            }
-        }
-        // Lock file does not exist (or was just removed) — try to write it
-        try {
-            const lockData = {
-                pid: process.pid,
-                acquired_at: new Date().toISOString(),
-            };
-            atomicWriteSync(lp, JSON.stringify(lockData, null, 2));
-            return { acquired: true };
         }
         catch {
-            // Write failed (race condition with another process) — retry or give up
-            if (Date.now() >= deadline) {
-                return { acquired: false };
+            // stat failed (file removed between exists and stat) — retry create.
+            continue;
+        }
+        if (canSteal) {
+            try {
+                unlinkSync(lp);
             }
-            sleepSync(SPIN_INTERVAL_MS);
+            catch { /* race: already removed */ }
+            // Loop back to retry create.
+            continue;
+        }
+        // Lock is held and not stale (or owner is alive) — wait or give up.
+        if (Date.now() >= deadline) {
+            return { acquired: false };
         }
+        sleepSync(SPIN_INTERVAL_MS);
     }
 }
 /**

package/dist/resources/extensions/gsd/tools/validate-milestone.js

@@ -11,6 +11,7 @@
 import { join } from "node:path";
 import { transaction, insertAssessment, deleteAssessmentByScope, getMilestoneSlices, } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
+import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js";
@@ -59,14 +60,18 @@ export async function handleValidateMilestone(params, basePath, opts) {
         return { error: `verdict must be one of: ${VALIDATION_VERDICTS.join(", ")}` };
     }
     // ── Resolve paths and render markdown ────────────────────────────────
+    // #4761: route through the canonical-root resolver so that when a live
+    // worktree exists for this milestone, validation reads/writes the
+    // worktree's artifacts instead of stale project-root state.
     const validationMd = renderValidationMarkdown(params);
+    const canonicalBase = resolveCanonicalMilestoneRoot(basePath, params.milestoneId);
     let validationPath;
-    const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+    const milestoneDir = resolveMilestonePath(canonicalBase, params.milestoneId);
     if (milestoneDir) {
         validationPath = join(milestoneDir, `${params.milestoneId}-VALIDATION.md`);
     }
     else {
-        const gsdDir = join(basePath, ".gsd");
+        const gsdDir = join(canonicalBase, ".gsd");
         const manualDir = join(gsdDir, "milestones", params.milestoneId);
         validationPath = join(manualDir, `${params.milestoneId}-VALIDATION.md`);
     }

package/dist/resources/extensions/gsd/unit-context-composer.js

@@ -0,0 +1,147 @@
+// GSD-2 — UnitContextComposer (#4782 phase 2).
+//
+// Reads a unit type's manifest and orchestrates artifact inlining through
+// a caller-provided resolver. Returns a joined context block suitable for
+// substitution into the unit's prompt template.
+//
+// Design rationale:
+//   - Pure dependency on the manifest module — no circular import with
+//     `auto-prompts.ts` where the per-artifact-key resolver lives.
+//   - Caller-supplied resolver means the composer can be unit-tested with
+//     trivial mocks; production wiring in `auto-prompts.ts` dispatches to
+//     the existing `inlineFile` / `inline*FromDb` helpers.
+//   - Null-returning resolvers are skipped silently: they model the
+//     "artifact is optional / missing / not applicable to this milestone"
+//     case. The composer never errors on a missing artifact.
+//
+// Scope: phase 2 pilot shipped `composeInlinedContext` for static-key
+// inlining. Phase 3.5 (#4924) adds the v2 surface — `composeUnitContext`
+// — which also handles excerpts, computed artifacts, and prepended blocks.
+// `composeInlinedContext` stays for backward compatibility with the
+// already-migrated simple builders.
+//
+// ─── Composer boundary invariant (#4924) ─────────────────────────────────
+//
+// The composer is allowed to:
+//   - order named sections per the manifest's declared sequence
+//   - resolve registered artifacts (static / computed / excerpt / on-demand)
+//   - apply typed policies (knowledge / memory / codebase-map / preferences)
+//
+// The composer must NOT grow:
+//   - arbitrary conditionals on unit state
+//   - loops over caller-supplied data
+//   - string templating beyond section composition (join + separator)
+//
+// Logic that needs those belongs in a typed computed-artifact builder
+// owned by the unit, not in the composer. Reviews must enforce this — it
+// is the difference between an orchestrator and a runaway DSL.
+import { resolveManifest, } from "./unit-context-manifest.js";
+/**
+ * Produce the inlined-context portion of a unit's system prompt by
+ * walking the manifest's `artifacts.inline` list in order and calling
+ * the provided resolver for each key.
+ *
+ * Returns an empty string when the unit type has no manifest registered,
+ * so callers can guard their wiring with a simple truthy check. Unknown
+ * unit types do not error — this mirrors `resolveManifest`'s contract.
+ *
+ * The separator between inlined blocks matches the in-tree convention
+ * (`\n\n---\n\n`) so composer output slots into existing prompt templates
+ * without visible diff.
+ */
+export async function composeInlinedContext(unitType, resolveArtifact) {
+    const manifest = resolveManifest(unitType);
+    if (!manifest)
+        return "";
+    const blocks = [];
+    for (const key of manifest.artifacts.inline) {
+        const body = await resolveArtifact(key);
+        if (body !== null && body.length > 0) {
+            blocks.push(body);
+        }
+    }
+    return blocks.join("\n\n---\n\n");
+}
+/**
+ * Convenience helper returning the manifest's declared budget so callers
+ * can telemetry a mismatch between actual prompt size and declared budget.
+ * Returns null for unknown unit types.
+ */
+export function manifestBudgetChars(unitType) {
+    const manifest = resolveManifest(unitType);
+    return manifest ? manifest.maxSystemPromptChars : null;
+}
+const SECTION_SEPARATOR = "\n\n---\n\n";
+/**
+ * Compose all manifest-declared context for a unit type using the v2
+ * surface. Walks `prepend` first (computed-only), then the `inline` list
+ * (static keys via `resolveArtifact`), then `excerpt` (via `resolveExcerpt`),
+ * then `artifacts.computed` (via the typed registry). Order within each
+ * section follows the manifest's declared sequence.
+ *
+ * Unknown unit types return empty strings for both sections — callers can
+ * fall back to existing imperative wiring without a special case.
+ *
+ * Resolver / registry omissions: if the manifest declares an entry but no
+ * resolver / registry entry is provided, the composer skips it silently.
+ * This matches the v1 contract where a null body is a no-op, and lets
+ * partial migrations land without forcing every consumer to register
+ * every artifact class up-front.
+ */
+export async function composeUnitContext(unitType, opts) {
+    const manifest = resolveManifest(unitType);
+    if (!manifest)
+        return { prepend: "", inline: "" };
+    // Single-source `unitType`: the manifest is resolved against the
+    // function arg, but computed builders read it from `base.unitType`.
+    // If those ever diverge (caller passes one type to composeUnitContext
+    // but a different one in opts.base), the composer would silently
+    // mix one unit's manifest with another unit's computed context.
+    // Normalize here so the composer dispatches a consistent identity
+    // through to every builder.
+    const normalizedOpts = {
+        ...opts,
+        base: { ...opts.base, unitType },
+    };
+    const prependBlocks = await runComputed(manifest.prepend ?? [], normalizedOpts);
+    const inlineBlocks = [];
+    for (const key of manifest.artifacts.inline) {
+        if (!normalizedOpts.resolveArtifact)
+            break;
+        const body = await normalizedOpts.resolveArtifact(key);
+        if (body && body.length > 0)
+            inlineBlocks.push(body);
+    }
+    for (const key of manifest.artifacts.excerpt) {
+        if (!normalizedOpts.resolveExcerpt)
+            break;
+        const body = await normalizedOpts.resolveExcerpt(key);
+        if (body && body.length > 0)
+            inlineBlocks.push(body);
+    }
+    inlineBlocks.push(...await runComputed(manifest.artifacts.computed ?? [], normalizedOpts));
+    return {
+        prepend: prependBlocks.join(SECTION_SEPARATOR),
+        inline: inlineBlocks.join(SECTION_SEPARATOR),
+    };
+}
+/**
+ * Invoke the registered builder for each declared computed id, in order.
+ * Missing registry entries (manifest declares the id but caller didn't
+ * register it) are skipped silently — see composeUnitContext rationale.
+ */
+async function runComputed(ids, opts) {
+    if (ids.length === 0 || !opts.computed)
+        return [];
+    const registry = opts.computed;
+    const out = [];
+    for (const id of ids) {
+        const entry = registry[id];
+        if (!entry)
+            continue;
+        const body = await entry.build(entry.inputs, opts.base);
+        if (body && body.length > 0)
+            out.push(body);
+    }
+    return out;
+}