@opengsd/gsd-pi 1.4.0 → 1.5.0

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -13,6 +13,7 @@ import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
 import { clearAutoCompletionStopInProgress, clearToolInvocationError, getAutoRuntimeSnapshot, getSourceObservationStore, isAutoActive, isAutoCompletionStopInProgress, isAutoPaused, isInteractiveElicitationInFlight, markToolEnd, markToolStart, recordAutoToolSurfaceSnapshot, recordToolInvocationError, } from "../auto-runtime-state.js";
+import { isDeterministicPolicyError, isQueuedUserMessageSkip, isToolInvocationError, isToolUnavailableError, } from "../auto-tool-tracking.js";
 import { applyProviderPayloadPolicy } from "../provider-payload-policy.js";
 import { checkToolCallLoop, recordToolCallLoopMutation, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { MINIMAL_AUTO_BASE_TOOL_NAMES } from "./core-session-tools.js";
@@ -44,7 +45,14 @@ import { clearPendingAutoStart } from "../pending-auto-start.js";
 import { resolveWorkflowToolBasePath } from "./dynamic-tools.js";
 import { getRequiredWorkflowToolsForUnit } from "../unit-tool-contracts.js";
 import { flushAllManifests } from "../workflow-manifest.js";
+import { recordUnitHarnessAbort } from "../unit-runtime.js";
 let approvalQuestionAbortInFlight = false;
+function recordCurrentUnitHarnessAbort(abort) {
+    const dash = getAutoRuntimeSnapshot();
+    if (!dash.active || !dash.basePath || !dash.currentUnit)
+        return;
+    recordUnitHarnessAbort(dash.basePath, dash.currentUnit.type, dash.currentUnit.id, dash.currentUnit.startedAt, abort);
+}
 async function loadWelcomeScreenModule() {
     const candidates = [];
     const gsdBinPath = process.env.GSD_BIN_PATH;
@@ -160,9 +168,23 @@ const WORKFLOW_GSD_TOOL_NAMES = [
     ...MINIMAL_GSD_TOOL_NAMES,
     ...Object.values(AUTO_UNIT_SCOPED_TOOLS).flat(),
 ].filter(isGsdManagedTool);
+const WORKFLOW_ONLY_AUTO_BASE_TOOL_NAMES = [
+    "find",
+    "glob",
+    "grep",
+    "ls",
+    "read",
+    "subagent",
+];
 function isGsdManagedTool(name) {
     return name.startsWith("gsd_") || name === "memory_query" || name === "capture_thought" || name === "gsd_graph";
 }
+function autoBaseToolNamesForUnit(unitType) {
+    const manifest = unitType ? resolveManifest(unitType) : null;
+    return manifest?.tools.mode === "workflow-only"
+        ? WORKFLOW_ONLY_AUTO_BASE_TOOL_NAMES
+        : MINIMAL_AUTO_BASE_TOOL_NAMES;
+}
 /**
  * Resolves requested tool names against active tools using exact and MCP-scoped matches.
  *
@@ -213,7 +235,7 @@ export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registered
         return buildRunUatGsdToolSet(activeToolNames, registeredToolNames);
     }
     const unitTools = unitType ? AUTO_UNIT_SCOPED_TOOLS[unitType] ?? [] : [];
-    const autoBaseTools = new Set(MINIMAL_AUTO_BASE_TOOL_NAMES);
+    const autoBaseTools = new Set(autoBaseToolNamesForUnit(unitType));
     const availableBaseTools = registeredToolNames.filter((name) => autoBaseTools.has(name));
     const preserved = [...new Set([
             ...activeToolNames.filter((name) => autoBaseTools.has(name)),
@@ -446,6 +468,75 @@ function formatLoopGuardBlockReason(reason) {
         return reason;
     return LOOP_GUARD_INTERACTIVE_INSTRUCTIONS.reduce((formatted, instruction) => formatted.replace(instruction, LOOP_GUARD_AUTO_INSTRUCTION), reason);
 }
+function isGateResultPersistenceTool(toolName) {
+    return toolName === "gsd_save_gate_result" || toolName === "gsd_uat_result_save";
+}
+function resultDetails(result) {
+    if (!result || typeof result !== "object")
+        return {};
+    const details = result.details;
+    return details && typeof details === "object" ? details : {};
+}
+function isAbortedExecutionToolResult(toolName, result) {
+    if (toolName !== "gsd_exec" && toolName !== "gsd_uat_exec")
+        return false;
+    const details = resultDetails(result);
+    return details.aborted === true || details.force_resolved === true || details.timed_out === true;
+}
+function isRetryableHarnessToolError(toolName, result, errorText) {
+    if (isGateResultPersistenceTool(toolName))
+        return false;
+    if (isDeterministicPolicyError(errorText))
+        return false;
+    if (toolName === "gsd_exec" || toolName === "gsd_uat_exec") {
+        if (isAbortedExecutionToolResult(toolName, result))
+            return true;
+        if (isToolUnavailableError(errorText))
+            return true;
+        if (isQueuedUserMessageSkip(errorText))
+            return true;
+        return isToolInvocationError(errorText);
+    }
+    if (isToolUnavailableError(errorText))
+        return true;
+    if (isQueuedUserMessageSkip(errorText))
+        return true;
+    return false;
+}
+function recordRetryableHarnessToolError(toolName, result, errorText) {
+    if (!isRetryableHarnessToolError(toolName, result, errorText))
+        return;
+    recordCurrentUnitHarnessAbort({
+        kind: "tool-error",
+        reason: errorText || "Tool execution failed before the unit could complete its gate evaluation.",
+        toolName,
+    });
+}
+function recordRetryableTurnAbort(event) {
+    const origin = typeof event.abortOrigin === "string" ? event.abortOrigin : undefined;
+    if (origin === "session-transition")
+        return;
+    const messages = Array.isArray(event.messages) ? event.messages : [];
+    const lastMsg = messages[messages.length - 1];
+    const stopReason = lastMsg && typeof lastMsg === "object"
+        ? lastMsg.stopReason
+        : undefined;
+    if (stopReason !== "aborted" && stopReason !== "error")
+        return;
+    const errorMessage = lastMsg && typeof lastMsg === "object"
+        ? lastMsg.errorMessage
+        : undefined;
+    const reason = [
+        "Agent turn aborted before the unit could complete its gate evaluation.",
+        origin ? `origin=${origin}` : undefined,
+        typeof stopReason === "string" ? `stopReason=${stopReason}` : undefined,
+        typeof errorMessage === "string" && errorMessage.trim() ? `error=${errorMessage.trim()}` : undefined,
+    ].filter(Boolean).join(" ");
+    recordCurrentUnitHarnessAbort({
+        kind: "turn-abort",
+        reason,
+    });
+}
 function beginSourceObservationStoreForCurrentUnit(ctx) {
     if (!isAutoActive())
         return null;
@@ -696,8 +787,8 @@ export function registerHooks(pi, ecosystemHandlers) {
         await applyCompactionThresholdOverride(ctx);
         await prepareWorkflowMcpForHookContext(ctx, basePath);
         // Migrate legacy .gsd/milestones/ to flat-phase .gsd/phases/ when detected.
-        // Best-effort — never blocks session startup. Skipped inside auto-worktrees
-        // (migration already ran on the project root before the worktree was created).
+        // Fail closed on migration errors: resolvers assume flat-phase paths after
+        // startup, so continuing with nested disk state corrupts later checks.
         try {
             const { isInAutoWorktree } = await import("../auto-worktree.js");
             if (!isInAutoWorktree(basePath)) {
@@ -710,10 +801,18 @@ export function registerHooks(pi, ecosystemHandlers) {
                         await migrateToFlatPhase(basePath);
                     }
                     else {
-                        safetyLogWarning("bootstrap", "flat-phase migration deferred: legacy .gsd/milestones/ layout detected but the workflow database could not be opened — will retry on next session");
+                        safetyLogWarning("bootstrap", "flat-phase migration required: legacy .gsd/milestones/ layout detected but the workflow database could not be opened — fix database access before starting GSD");
+                        throw new Error("flat-phase migration required but the workflow database could not be opened; fix database access before starting GSD");
                     }
                 }
             }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            safetyLogWarning("bootstrap", `flat-phase migration failed: ${message}`);
+            throw new Error(`flat-phase migration failed: ${message}`);
+        }
+        try {
             const projectRoot = resolveWorktreeProjectRoot(basePath);
             const { pruneStaleFlatPhaseBackups } = await import("../flat-phase-migration.js");
             const pruned = pruneStaleFlatPhaseBackups(projectRoot);
@@ -722,7 +821,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             }
         }
         catch (err) {
-            safetyLogWarning("bootstrap", `flat-phase migration: ${err instanceof Error ? err.message : String(err)}`);
+            safetyLogWarning("bootstrap", `flat-phase backup pruning: ${err instanceof Error ? err.message : String(err)}`);
         }
         // Apply show_token_cost preference (#1515)
         try {
@@ -871,6 +970,7 @@ export function registerHooks(pi, ecosystemHandlers) {
     });
     pi.on("agent_end", async (event, ctx) => {
         approvalQuestionAbortInFlight = false;
+        recordRetryableTurnAbort(event);
         resetToolCallLoopGuard();
         resetPendingGatePauseGuard();
         await resetAskUserQuestionsTurnCache();
@@ -1077,6 +1177,12 @@ export function registerHooks(pi, ecosystemHandlers) {
         // ── Loop guard: block repeated identical tool calls ──
         const loopCheck = checkToolCallLoop(toolName, event.input);
         if (loopCheck.block) {
+            recordCurrentUnitHarnessAbort({
+                kind: "tool-loop-guard",
+                reason: loopCheck.reason ?? "Tool-call loop guard blocked a repeated tool call.",
+                toolName,
+                count: loopCheck.count,
+            });
             return { block: true, reason: formatLoopGuardBlockReason(loopCheck.reason) };
         }
         const deferredGateGuard = shouldBlockDeferredApprovalTool(toolName, event.input, discussionBasePath);
@@ -1299,6 +1405,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             // Let recordToolInvocationError classify the failure so non-gsd_ harness
             // errors and deterministic policy rejections are handled consistently.
             recordToolInvocationError(event.toolName, errorText);
+            recordRetryableHarnessToolError(toolName, resultPayload, errorText);
         }
         else if (isAutoActive()) {
             clearToolInvocationError();
@@ -1466,6 +1573,7 @@ export function registerHooks(pi, ecosystemHandlers) {
     // for every finalized tool call on every engine, so error classification
     // and evidence persistence here cover external engines that skip tool_result.
     pi.on("tool_execution_end", async (event) => {
+        const toolName = canonicalToolName(event.toolName);
         markToolEnd(event.toolCallId);
         // #2883/#4974: Capture deterministic invocation/policy errors
         // so postUnitPreVerification can break the retry loop instead of re-dispatching.
@@ -1476,6 +1584,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             // Let recordToolInvocationError classify the failure so non-gsd_ harness
             // errors and deterministic policy rejections are handled consistently.
             recordToolInvocationError(event.toolName, errorText);
+            recordRetryableHarnessToolError(toolName, event.result, errorText);
         }
         else if (isAutoActive()) {
             clearToolInvocationError();

package/dist/resources/extensions/gsd/bootstrap/schedule-wakeup-tool.js

@@ -3,19 +3,63 @@
 import { Type } from "@sinclair/typebox";
 import { getAutoRuntimeSnapshot } from "../auto-runtime-state.js";
 import { scheduleAutoWakeup } from "../auto/schedule-wakeup.js";
+import { logWarning } from "../workflow-logger.js";
 import { resolveCtxCwd } from "./dynamic-tools.js";
 const MAX_WAKEUP_DELAY_SECONDS = 24 * 60 * 60;
+const INTERACTIVE_WAKEUP_CUSTOM_TYPE = "gsd-schedule-wakeup";
+// One pending interactive wakeup per session, keyed by base path — the same
+// scoping auto-mode uses for its wakeup map (see `wakeupKey`). Re-arming cancels
+// only that session's prior timer, so repeated polling never stacks overlapping
+// wakeups, and concurrent projects in one host process don't cancel each other.
+const pendingInteractiveWakeups = new Map();
+function scheduleInteractiveWakeup(pi, key, delaySeconds, prompt, reason) {
+    const existing = pendingInteractiveWakeups.get(key);
+    if (existing)
+        clearTimeout(existing);
+    const handle = setTimeout(() => {
+        if (pendingInteractiveWakeups.get(key) === handle) {
+            pendingInteractiveWakeups.delete(key);
+        }
+        try {
+            void Promise.resolve(pi.sendMessage({
+                customType: INTERACTIVE_WAKEUP_CUSTOM_TYPE,
+                content: prompt,
+                display: true,
+                details: { delaySeconds, reason },
+            }, { triggerTurn: true })).catch((error) => {
+                logWarning("bootstrap", `ScheduleWakeup interactive dispatch failed: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }
+        catch (error) {
+            logWarning("bootstrap", `ScheduleWakeup interactive dispatch failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }, delaySeconds * 1000);
+    pendingInteractiveWakeups.set(key, handle);
+    if (typeof handle === "object" &&
+        handle !== null &&
+        "unref" in handle &&
+        typeof handle.unref === "function") {
+        handle.unref();
+    }
+}
+export function _resetInteractiveWakeupsForTest() {
+    for (const handle of pendingInteractiveWakeups.values()) {
+        clearTimeout(handle);
+    }
+    pendingInteractiveWakeups.clear();
+}
 export function registerScheduleWakeupTool(pi) {
     pi.registerTool({
         name: "ScheduleWakeup",
         label: "Schedule Wakeup",
-        description: "In GSD auto-mode, pause the current unit and continue the same session after a delay. " +
-            "Use this for long external processes that need polling without ending the unit as no-artifact.",
-        promptSnippet: "Schedule a same-session auto-mode wakeup after a delay.",
+        description: "Schedule a delayed continuation turn. In GSD auto-mode, continue the current unit in the same session; " +
+            "outside auto-mode, start a new triggered turn with the supplied wakeup prompt.",
+        promptSnippet: "Schedule a wakeup prompt after a delay.",
         promptGuidelines: [
             "Use ScheduleWakeup at the end of an execute-task turn when waiting for a long external process.",
             "Include a prompt that says exactly what external state to check next and what artifact to write when done.",
             "Re-arm ScheduleWakeup on each polling turn if the external process is still running.",
+            "Outside auto-mode, use ScheduleWakeup when the user asks you to check back or poll later.",
         ],
         parameters: Type.Object({
             delaySeconds: Type.Number({
@@ -34,22 +78,27 @@ export function registerScheduleWakeupTool(pi) {
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const dash = getAutoRuntimeSnapshot();
             const currentUnit = dash.currentUnit;
-            const basePath = dash.basePath || resolveCtxCwd(ctx);
+            const delaySeconds = Math.max(1, Math.min(MAX_WAKEUP_DELAY_SECONDS, Math.floor(params.delaySeconds)));
+            const reason = params.reason ?? "";
             if (!dash.active || !currentUnit) {
+                const interactiveKey = dash.basePath || resolveCtxCwd(ctx);
+                scheduleInteractiveWakeup(pi, interactiveKey, delaySeconds, params.prompt, reason);
                 return {
-                    content: [{ type: "text", text: "ScheduleWakeup is only available during an active GSD auto-mode unit." }],
-                    details: { operation: "schedule_wakeup", error: "auto_mode_inactive" },
-                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: `Wakeup scheduled for ${delaySeconds}s. GSD will start a new turn with the wakeup prompt.`,
+                        }],
+                    details: { operation: "schedule_wakeup", delaySeconds, mode: "interactive" },
                 };
             }
-            const delaySeconds = Math.max(1, Math.min(MAX_WAKEUP_DELAY_SECONDS, Math.floor(params.delaySeconds)));
+            const basePath = dash.basePath || resolveCtxCwd(ctx);
             scheduleAutoWakeup({
                 basePath,
                 unitType: currentUnit.type,
                 unitId: currentUnit.id,
                 delayMs: delaySeconds * 1000,
                 prompt: params.prompt,
-                reason: params.reason ?? "",
+                reason,
                 createdAt: Date.now(),
             });
             return {

package/dist/resources/extensions/gsd/bootstrap/tool-call-loop-guard.js

@@ -24,6 +24,8 @@
  */
 import { createHash } from "node:crypto";
 import { INHERENTLY_REPEATABLE_TOOL_SET } from "./core-session-tools.js";
+import { hasBrowserContractPrefix } from "../../shared/browser-contract.js";
+import { canonicalToolName } from "../engine-hook-contract.js";
 const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
 /** Interactive/user-facing tools where even 1 duplicate is confusing. */
 const STRICT_LOOP_TOOLS = new Set(["ask_user_questions"]);
@@ -111,8 +113,14 @@ export function checkToolCallLoop(toolName, args) {
     perToolCounts.set(toolName, perToolCount);
     perToolLastMutationEpoch.set(toolName, mutationEpoch);
     // Read-only navigation tools are normal context gathering; Guard 1 still
-    // catches true reread loops with identical arguments.
-    if (PER_TOOL_CAP_EXEMPT_TOOLS.has(toolName)) {
+    // catches true reread loops with identical arguments. Browser Automation
+    // Contract tools (browser_*) are the same shape: a browser-backed UAT makes
+    // many distinct-arg calls (read a message, count edits, inspect a card, …),
+    // so the arg-independent per-tool cap misfires on legitimate verification;
+    // Guard 1's identical-signature streak still catches a genuinely stuck
+    // browser loop.
+    if (PER_TOOL_CAP_EXEMPT_TOOLS.has(toolName) ||
+        hasBrowserContractPrefix(canonicalToolName(toolName))) {
         return { block: false, count: consecutiveCount };
     }
     const perToolCap = INHERENTLY_REPEATABLE_TOOL_SET.has(toolName)

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -947,7 +947,7 @@ function allowedPlanningDispatchAgentsList() {
     return [...ALLOWED_PLANNING_DISPATCH_AGENTS].join(", ");
 }
 function allowsControlledSubagentDispatch(policy) {
-    return ((policy.mode === "planning-dispatch" || policy.mode === "verification") &&
+    return ((policy.mode === "planning-dispatch" || policy.mode === "verification" || policy.mode === "workflow-only") &&
         Array.isArray(policy.allowedSubagents));
 }
 function warnMissingControlledDispatchAgentClasses(unitType, mode, toolName) {
@@ -975,6 +975,7 @@ function warnMissingControlledDispatchAgentClasses(unitType, mode, toolName) {
 const PLANNING_SAFE_TOOLS = new Set([
     "read", "grep", "find", "ls", "glob",
     "ask_user_questions",
+    "memory_query",
     "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
     "search_and_read",
 ]);
@@ -1031,6 +1032,9 @@ function planningBlock(unitType, mode, what) {
  *                  → allows Bash for project verification commands, keeps
  *                    writes restricted to .gsd/, and permits subagent dispatch
  *                    only when the manifest declares allowedSubagents.
+ *   - "workflow-only"
+ *                  → allows reads, GSD workflow tools, and declared read-only
+ *                    subagents; blocks generic Bash and direct file writes.
  *
  * `pathOrCommand` is the file path for write/edit-shaped tools and the
  * shell command for bash. Other tools ignore this argument.
@@ -1101,6 +1105,15 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
         }
         return planningBlock(unitType, policy.mode, "subagent dispatch is not permitted in planning units");
     }
+    if (policy.mode === "workflow-only") {
+        if (tool === "bash") {
+            return planningBlock(unitType, policy.mode, `bash is not permitted; use the unit's dedicated GSD workflow tools for durable validation output`);
+        }
+        if (PLANNING_WRITE_TOOLS.has(tool)) {
+            return planningBlock(unitType, policy.mode, `cannot ${tool} "${pathOrCommand}" — direct artifact writes are disabled; call the required GSD workflow tool instead`);
+        }
+        return planningBlock(unitType, policy.mode, `tool "${tool}" is not on the workflow-only allowlist`);
+    }
     if (tool === "bash") {
         if (policy.mode === "verification") {
             if (BASH_VERIFICATION_RE.test(pathOrCommand) || BASH_READ_ONLY_RE.test(pathOrCommand))

package/dist/resources/extensions/gsd/codebase-generator.js

@@ -9,9 +9,11 @@
  */
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, dirname, extname } from "node:path";
+import { join, dirname, extname, relative, sep } from "node:path";
 import { execSync } from "node:child_process";
 import { gsdRoot } from "./paths.js";
+import { createRepositoryRegistryFromPreferences, } from "./repository-registry.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
 // ─── Defaults ────────────────────────────────────────────────────────────────
 const DEFAULT_EXCLUDES = [
     // ── AI / tooling meta ──
@@ -144,6 +146,84 @@ function enumerateFiles(basePath, excludes, maxFiles) {
     const truncated = filtered.length > maxFiles;
     return { files: truncated ? filtered.slice(0, maxFiles) : filtered, truncated };
 }
+/**
+ * Build a workspace-aware registry for parent mode, or null when the project is
+ * single-repo (no declared child repositories). Returns null so the caller falls
+ * back to the legacy single-root enumeration and produces byte-identical output.
+ */
+function loadWorkspaceRegistry(basePath) {
+    const preferences = loadEffectiveGSDPreferences(basePath)?.preferences;
+    const workspace = preferences?.workspace;
+    const mode = workspace?.mode ?? "project";
+    // Parent mode is only meaningful with at least one declared child repo; the
+    // implicit "project" repo is always present, so require a declared non-project id.
+    const hasDeclaredChildRepo = workspace?.repositories
+        ? Object.keys(workspace.repositories).some((id) => id !== "project")
+        : false;
+    if (mode !== "parent" || !hasDeclaredChildRepo) {
+        return null;
+    }
+    return createRepositoryRegistryFromPreferences(basePath, preferences);
+}
+/** Stable key fragment for workspace-aware enumeration inputs (mode + declared repos). */
+function workspaceEnumerationSignature(basePath) {
+    const registry = loadWorkspaceRegistry(basePath);
+    if (!registry)
+        return "single-root";
+    return JSON.stringify({
+        mode: registry.mode,
+        repositories: registry.repositories
+            .map((repo) => ({ id: repo.id, root: repo.root }))
+            .sort((a, b) => a.id.localeCompare(b.id)),
+    });
+}
+/**
+ * Enumerate tracked files across every declared repository in a parent workspace.
+ * Child-repo paths are rewritten to be workspace-relative (e.g. `frontend/src/x`)
+ * and tagged with their declaring repo id so the map can render repo-labelled
+ * sections. The maxFiles cap is applied across the union of all repositories.
+ */
+function enumerateWorkspaceFiles(registry, excludes, maxFiles) {
+    const perRepo = [];
+    const seen = new Set();
+    let totalEligible = 0;
+    for (const repo of registry.repositories) {
+        const rawFiles = lsFiles(repo.root);
+        const repoPrefix = relative(registry.projectRoot, repo.root).split(sep).join("/");
+        const repoEntries = [];
+        for (const file of rawFiles) {
+            // Rewrite before exclusion so workspace-relative patterns (e.g. frontend/…) apply.
+            const workspacePath = repoPrefix ? `${repoPrefix}/${file}` : file;
+            if (shouldExclude(workspacePath, excludes))
+                continue;
+            if (seen.has(workspacePath))
+                continue;
+            seen.add(workspacePath);
+            totalEligible++;
+            repoEntries.push({ workspacePath, repoId: repo.id });
+        }
+        perRepo.push(repoEntries);
+    }
+    const files = [];
+    const repos = [];
+    const indices = new Array(perRepo.length).fill(0);
+    while (files.length < maxFiles) {
+        let progressed = false;
+        for (let i = 0; i < perRepo.length; i++) {
+            if (indices[i] < perRepo[i].length) {
+                const entry = perRepo[i][indices[i]++];
+                files.push(entry.workspacePath);
+                repos.push(entry.repoId);
+                progressed = true;
+                if (files.length >= maxFiles)
+                    break;
+            }
+        }
+        if (!progressed)
+            break;
+    }
+    return { files, repos, truncated: totalEligible > files.length };
+}
 function resolveGeneratorOptions(options) {
     const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])];
     const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES;
@@ -159,38 +239,69 @@ function resolveGeneratorOptions(options) {
         }),
     };
 }
-function computeCodebaseFingerprint(files, resolved, truncated) {
+function computeCodebaseFingerprint(files, resolved, truncated, repos) {
     return createHash("sha1")
         .update(JSON.stringify({
         files,
+        ...(repos ? { repos } : {}),
         truncated,
         optionSignature: resolved.optionSignature,
     }))
         .digest("hex");
 }
 // ─── Grouping ────────────────────────────────────────────────────────────────
-function groupByDirectory(files, descriptions, collapseThreshold) {
+function groupByDirectory(files, descriptions, collapseThreshold, repos) {
     const dirMap = new Map();
-    for (const file of files) {
+    for (let i = 0; i < files.length; i++) {
+        const file = files[i];
         const dir = dirname(file);
-        const dirKey = dir === "." ? "" : dir;
-        if (!dirMap.has(dirKey)) {
-            dirMap.set(dirKey, []);
+        const dirPath = dir === "." ? "" : dir;
+        const repoId = repos?.[i];
+        const groupKey = repoId !== undefined ? `${repoId}\0${dirPath}` : dirPath;
+        if (!dirMap.has(groupKey)) {
+            dirMap.set(groupKey, []);
         }
-        dirMap.get(dirKey).push({
+        dirMap.get(groupKey).push({
             path: file,
             description: descriptions.get(file) ?? "",
+            repo: repoId,
         });
     }
     const groups = [];
-    const sortedDirs = [...dirMap.keys()].sort();
-    for (const dir of sortedDirs) {
-        const dirFiles = dirMap.get(dir);
+    const repoOrder = new Map();
+    if (repos) {
+        for (let i = 0; i < repos.length; i++) {
+            if (!repoOrder.has(repos[i])) {
+                repoOrder.set(repos[i], repoOrder.size);
+            }
+        }
+    }
+    const sortedDirs = [...dirMap.keys()].sort((a, b) => {
+        // Single-repo (project) mode must stay byte-identical to the pre-workspace
+        // output, which ordered directories with a bare `.sort()` (UTF-16 code-unit
+        // order, so uppercase sorts before lowercase). localeCompare would diverge
+        // for mixed-case names (e.g. "Zoo" before "apple" flips), so preserve
+        // code-unit ordering here; only the repo-partitioning key is added on top.
+        if (!repos)
+            return a < b ? -1 : a > b ? 1 : 0;
+        const repoA = dirMap.get(a)[0]?.repo ?? "";
+        const repoB = dirMap.get(b)[0]?.repo ?? "";
+        const orderA = repoOrder.get(repoA) ?? 0;
+        const orderB = repoOrder.get(repoB) ?? 0;
+        if (orderA !== orderB)
+            return orderA - orderB;
+        return a.localeCompare(b);
+    });
+    for (const groupKey of sortedDirs) {
+        const dirFiles = dirMap.get(groupKey);
         dirFiles.sort((a, b) => a.path.localeCompare(b.path));
+        const dirPath = repos ? groupKey.slice(groupKey.indexOf("\0") + 1) : groupKey;
         groups.push({
-            path: dir,
+            path: dirPath,
             files: dirFiles,
             collapsed: dirFiles.length > collapseThreshold,
+            // Each group is scoped to one repo in workspace-aware mode.
+            repo: dirFiles[0]?.repo,
         });
     }
     return groups;
@@ -207,7 +318,18 @@ function renderCodebaseMap(groups, totalFiles, truncated, metadata) {
         lines.push(`Note: Truncated to first ${totalFiles} files. Run with higher --max-files to include all.`);
     }
     lines.push("");
+    let emittedRepo;
     for (const group of groups) {
+        // In a workspace-aware map, partition directories under their declaring
+        // repository. `## [repo-id]` headings are used (not `###`) so they never
+        // collide with the per-directory `### <dir>/` headings or the
+        // `parseCodebaseMap` list-item regexes. Groups are sorted by declaring
+        // repo (enumeration order) then directory path so each repo is contiguous.
+        if (group.repo && group.repo !== emittedRepo) {
+            emittedRepo = group.repo;
+            lines.push(`## [${group.repo}]`);
+            lines.push("");
+        }
         const heading = group.path || "(root)";
         lines.push(`### ${heading}/`);
         if (group.collapsed) {
@@ -250,13 +372,15 @@ function renderCodebaseMap(groups, totalFiles, truncated, metadata) {
 function buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated) {
     const listed = enumerated ?? enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
     const descriptions = existingDescriptions ?? new Map();
-    const groups = groupByDirectory(listed.files, descriptions, resolved.collapseThreshold);
+    const groups = groupByDirectory(listed.files, descriptions, resolved.collapseThreshold, listed.repos);
     const generatedAt = new Date().toISOString().split(".")[0] + "Z";
+    const repoIds = listed.repos ? Array.from(new Set(listed.repos)) : undefined;
     const metadata = {
         generatedAt,
-        fingerprint: computeCodebaseFingerprint(listed.files, resolved, listed.truncated),
+        fingerprint: computeCodebaseFingerprint(listed.files, resolved, listed.truncated, listed.repos),
         fileCount: listed.files.length,
         truncated: listed.truncated,
+        ...(repoIds ? { repositories: repoIds } : {}),
     };
     const content = renderCodebaseMap(groups, listed.files.length, listed.truncated, metadata);
     return {
@@ -273,9 +397,21 @@ function buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated)
  * Generate a fresh CODEBASE.md from scratch.
  * Preserves existing descriptions if `existingDescriptions` is provided.
  */
+/**
+ * Resolve workspace-aware enumeration for parent mode, or undefined to fall
+ * back to the legacy single-root enumeration. Centralized so all three public
+ * entry points (generate/update/ensure) share one discovery path.
+ */
+function resolveWorkspaceEnumeration(basePath, resolved) {
+    const registry = loadWorkspaceRegistry(basePath);
+    if (!registry)
+        return undefined;
+    return enumerateWorkspaceFiles(registry, resolved.excludes, resolved.maxFiles);
+}
 export function generateCodebaseMap(basePath, options, existingDescriptions) {
     const resolved = resolveGeneratorOptions(options);
-    return buildCodebaseMap(basePath, resolved, existingDescriptions);
+    const enumerated = resolveWorkspaceEnumeration(basePath, resolved);
+    return buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated);
 }
 /**
  * Incremental update: re-scan files, preserve existing descriptions,
@@ -293,7 +429,8 @@ export function updateCodebaseMap(basePath, options) {
     const existingFiles = new Set(existingDescriptions.keys());
     // Generate new map preserving descriptions — reuse the returned file list
     // to avoid a second enumeration (prevents race between content and stats).
-    const result = buildCodebaseMap(basePath, resolved, existingDescriptions);
+    const enumerated = resolveWorkspaceEnumeration(basePath, resolved);
+    const result = buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated);
     const currentSet = new Set(result.files);
     // Count changes
     let added = 0;
@@ -326,7 +463,7 @@ function clearFreshnessCache(basePath) {
 }
 export function ensureCodebaseMapFresh(basePath, options, ensureOptions) {
     const resolved = resolveGeneratorOptions(options);
-    const cacheKey = `${basePath}::${resolved.optionSignature}`;
+    const cacheKey = `${basePath}::${resolved.optionSignature}::${workspaceEnumerationSignature(basePath)}`;
     const ttlMs = ensureOptions?.ttlMs ?? DEFAULT_REFRESH_TTL_MS;
     const force = ensureOptions?.force === true;
     const now = Date.now();
@@ -338,8 +475,9 @@ export function ensureCodebaseMapFresh(basePath, options, ensureOptions) {
         }
     }
     const existing = readCodebaseMap(basePath);
-    const listed = enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
-    const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated);
+    const listed = resolveWorkspaceEnumeration(basePath, resolved)
+        ?? enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+    const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated, listed.repos);
     const cacheAndReturn = (result) => {
         freshnessCache.set(cacheKey, { checkedAt: now, result });
         return result;