@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.4fb2d460

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

@@ -14,34 +14,173 @@
  * to stop tooling for the rest of that turn and answer in text.
  *
  * The per-tool-name check (#783 Brief C) tracks call counts within a
- * turn regardless of args, decaying after successful state-mutating tools.
+ * turn regardless of args, decaying after successful state-progressing tools.
  * This catches improvisation
  * loops where the model attempts the same missing workflow tool through
  * varied surfaces (bash → `node -e` → CLI), each with a different
  * signature, so the identical-args streak never trips, while allowing
- * tool-heavy turns that are making file-mutation progress. Whichever guard
- * trips first blocks.
+ * tool-heavy turns that are making progress. Progress means a successful file
+ * mutation (edit/write) or a successful shell/exec call (bg_shell,
+ * gsd_uat_exec, …) — so a local model running a legitimate iterative
+ * debugging loop (restart server, npm install, curl an endpoint) is not
+ * blocked as a false loop (#1206). Whichever guard trips first blocks.
+ *
+ * Thresholds, exempt tools, and enable flags are user-tunable (#1198) via the
+ * `tool_call_loop_guard` key in `.gsd/PREFERENCES.md` and `GSD_TOOL_LOOP_*`
+ * environment variables, applied through {@link configureToolCallLoopGuard}.
+ * Defaults preserve the original hardcoded behavior.
  */
 import { createHash } from "node:crypto";
 import { INHERENTLY_REPEATABLE_TOOL_SET } from "./core-session-tools.js";
-const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
+import { hasBrowserContractPrefix } from "../../shared/browser-contract.js";
+import { canonicalToolName } from "../engine-hook-contract.js";
+/** Built-in defaults. Preserved when preferences/env do not override them. */
+const DEFAULT_MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
+const DEFAULT_PER_TOOL_DEFAULT_CAP = 6;
+const DEFAULT_PER_TOOL_REPEATABLE_CAP = 15;
+const DEFAULT_PER_TOOL_CAP_EXEMPT_TOOLS = ["find", "glob", "grep", "ls", "read", "search_and_read"];
 /** Interactive/user-facing tools where even 1 duplicate is confusing. */
 const STRICT_LOOP_TOOLS = new Set(["ask_user_questions"]);
 const MAX_CONSECUTIVE_STRICT = 1;
+const STATE_MUTATING_TOOL_SET = new Set(["edit", "write", "multi_edit", "notebook_edit"]);
 /**
- * Per-turn cap on calls to the SAME tool name, regardless of args (#783).
+ * Successful shell/exec calls are state progression too (#1206), not just file
+ * mutations. A local model debugging a UAT scenario legitimately restarts
+ * servers, runs `npm install`, and curls endpoints via bg_shell / gsd_uat_exec
+ * with varied args — productive work that never touches a file, so Guard 2's
+ * per-tool cap would otherwise misfire as a false loop. Decaying on these
+ * successful calls keeps the guard from aborting a progressing turn.
  *
- * General-purpose execution tools are routinely called many times per turn
- * (touching multiple files, running several commands), so they get a higher
- * ceiling. Everything else — workflow one-shot tools (e.g. gsd_complete_milestone)
- * and any non-allowlisted tool — gets the default cap. The default is generous
- * enough to absorb legitimate retries but catches the reported improvisation
- * loop (~51 calls) well before a cost spike.
+ * Only successful calls reach {@link recordToolCallLoopMutation}: the
+ * tool_result hook skips `isError` results, and the bash tool throws on
+ * non-zero exit, so a genuinely stuck improvisation loop of failing commands
+ * (#783) never decays and still trips the cap. `async_bash` is excluded
+ * because it only registers a background job; command success is reported
+ * later via `await_job`. `bg_shell` may return `isError: false` for failed
+ * `run`/`start` outcomes, so the hook passes `details` for validation.
  */
-const PER_TOOL_DEFAULT_CAP = 6;
-const PER_TOOL_REPEATABLE_CAP = 15;
-const PER_TOOL_CAP_EXEMPT_TOOLS = new Set(["find", "glob", "grep", "ls", "read", "search_and_read"]);
-const STATE_MUTATING_TOOL_SET = new Set(["edit", "write", "multi_edit", "notebook_edit"]);
+const STATE_PROGRESSING_EXEC_TOOL_SET = new Set([
+    "bash",
+    "bg_shell",
+    "shell",
+    "powershell",
+    "gsd_exec",
+    "gsd_uat_exec",
+]);
+function isSuccessfulBgShellLoopProgress(details) {
+    if (!details || typeof details !== "object")
+        return false;
+    const record = details;
+    switch (record.action) {
+        case "run":
+            return record.exitCode === 0 && record.timedOut !== true;
+        case "start":
+        case "restart": {
+            const process = record.process;
+            if (!process || typeof process !== "object")
+                return false;
+            return process.alive === true;
+        }
+        case "wait_for_ready":
+            return record.ready === true;
+        case "send_and_wait":
+            return record.matched === true;
+        default:
+            return true;
+    }
+}
+function defaultGuardConfig() {
+    return {
+        guardEnabled: true,
+        identicalEnabled: true,
+        maxConsecutiveIdentical: DEFAULT_MAX_CONSECUTIVE_IDENTICAL_CALLS,
+        repeatedEnabled: true,
+        perToolDefaultCap: DEFAULT_PER_TOOL_DEFAULT_CAP,
+        perToolRepeatableCap: DEFAULT_PER_TOOL_REPEATABLE_CAP,
+        perToolExempt: new Set(DEFAULT_PER_TOOL_CAP_EXEMPT_TOOLS),
+    };
+}
+let config = defaultGuardConfig();
+/** Parse a positive-integer env var, returning undefined when unset/invalid. */
+function envPositiveInt(name) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 1 ? Math.floor(n) : undefined;
+}
+/** Parse a boolean env var (`true`/`1` vs `false`/`0`), undefined when unset. */
+function envBool(name) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    const v = raw.trim().toLowerCase();
+    if (v === "true" || v === "1" || v === "yes" || v === "on")
+        return true;
+    if (v === "false" || v === "0" || v === "no" || v === "off")
+        return false;
+    return undefined;
+}
+/** Parse a comma-separated tool-name list env var. */
+function envToolList(name) {
+    const raw = process.env[name];
+    if (!raw)
+        return [];
+    return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+/**
+ * Resolve preferences + environment overrides into the active configuration.
+ * Environment variables win over preferences; preferences win over built-in
+ * defaults. User-supplied exempt tools are additive to the built-in exempt
+ * set so defaults are always preserved.
+ *
+ * Applied to both interactive sessions and `/gsd auto` (called from the
+ * session_start / session_switch hooks).
+ */
+export function configureToolCallLoopGuard(prefs) {
+    const next = defaultGuardConfig();
+    if (prefs) {
+        if (typeof prefs.enabled === "boolean")
+            next.guardEnabled = prefs.enabled;
+        if (prefs.identical_args) {
+            if (typeof prefs.identical_args.enabled === "boolean")
+                next.identicalEnabled = prefs.identical_args.enabled;
+            if (typeof prefs.identical_args.max_consecutive_calls === "number" && prefs.identical_args.max_consecutive_calls >= 1) {
+                next.maxConsecutiveIdentical = Math.floor(prefs.identical_args.max_consecutive_calls);
+            }
+        }
+        if (prefs.repeated_tool) {
+            if (typeof prefs.repeated_tool.enabled === "boolean")
+                next.repeatedEnabled = prefs.repeated_tool.enabled;
+            if (typeof prefs.repeated_tool.default_cap === "number" && prefs.repeated_tool.default_cap >= 1) {
+                next.perToolDefaultCap = Math.floor(prefs.repeated_tool.default_cap);
+            }
+            if (typeof prefs.repeated_tool.repeatable_cap === "number" && prefs.repeated_tool.repeatable_cap >= 1) {
+                next.perToolRepeatableCap = Math.floor(prefs.repeated_tool.repeatable_cap);
+            }
+            for (const tool of prefs.repeated_tool.exempt_tools ?? []) {
+                if (typeof tool === "string" && tool.trim())
+                    next.perToolExempt.add(tool.trim());
+            }
+        }
+    }
+    // Environment overrides (win over preferences).
+    const envEnabled = envBool("GSD_TOOL_LOOP_GUARD_ENABLED");
+    if (envEnabled !== undefined)
+        next.guardEnabled = envEnabled;
+    const envIdenticalMax = envPositiveInt("GSD_TOOL_LOOP_IDENTICAL_MAX");
+    if (envIdenticalMax !== undefined)
+        next.maxConsecutiveIdentical = envIdenticalMax;
+    const envDefaultCap = envPositiveInt("GSD_TOOL_LOOP_REPEATED_DEFAULT_CAP");
+    if (envDefaultCap !== undefined)
+        next.perToolDefaultCap = envDefaultCap;
+    const envRepeatableCap = envPositiveInt("GSD_TOOL_LOOP_REPEATED_REPEATABLE_CAP");
+    if (envRepeatableCap !== undefined)
+        next.perToolRepeatableCap = envRepeatableCap;
+    for (const tool of envToolList("GSD_TOOL_LOOP_EXEMPT_TOOLS"))
+        next.perToolExempt.add(tool);
+    config = next;
+}
 let consecutiveCount = 0;
 let lastSignature = "";
 let lastToolName = "";
@@ -70,14 +209,17 @@ function hashToolCall(toolName, args) {
  * Returns `{ block: true, reason }` when the loop threshold is exceeded.
  *
  * Two independent guards run; whichever trips first blocks:
- *  1. Identical-signature streak (MAX_CONSECUTIVE_IDENTICAL_CALLS, strict for
+ *  1. Identical-signature streak (config.maxConsecutiveIdentical, strict for
  *     ask_user_questions).
- *  2. Per-tool-name cap (PER_TOOL_DEFAULT_CAP / PER_TOOL_REPEATABLE_CAP),
+ *  2. Per-tool-name cap (config.perToolDefaultCap / config.perToolRepeatableCap),
  *     independent of args, reset after file-mutation progress — catches
  *     improvisation loops (#783).
+ *
+ * Both guards, their thresholds, and the per-tool exempt set are user-tunable
+ * via {@link configureToolCallLoopGuard} (#1198).
  */
 export function checkToolCallLoop(toolName, args) {
-    if (!enabled)
+    if (!enabled || !config.guardEnabled)
         return { block: false, count: 0 };
     const sig = hashToolCall(toolName, args);
     if (sig === lastSignature) {
@@ -91,12 +233,14 @@ export function checkToolCallLoop(toolName, args) {
     // ── Guard 1: identical-signature streak ──
     const threshold = STRICT_LOOP_TOOLS.has(toolName)
         ? MAX_CONSECUTIVE_STRICT
-        : MAX_CONSECUTIVE_IDENTICAL_CALLS;
-    if (consecutiveCount > threshold) {
+        : config.maxConsecutiveIdentical;
+    if (config.identicalEnabled && consecutiveCount > threshold) {
         return {
             block: true,
             reason: `Tool loop detected (identical args): ${toolName} called ${consecutiveCount} times ` +
-                `with identical arguments. Blocking to prevent infinite loop. ` +
+                `with identical arguments (max ${threshold}). Blocking to prevent infinite loop. ` +
+                `Raise tool_call_loop_guard.identical_args.max_consecutive_calls in .gsd/PREFERENCES.md ` +
+                `(or GSD_TOOL_LOOP_IDENTICAL_MAX) if this is expected. ` +
                 `Do not retry this tool or call other tools this turn — stop and respond to the user in text.`,
             count: consecutiveCount,
         };
@@ -111,30 +255,52 @@ 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 (!config.repeatedEnabled ||
+        config.perToolExempt.has(toolName) ||
+        hasBrowserContractPrefix(canonicalToolName(toolName))) {
         return { block: false, count: consecutiveCount };
     }
     const perToolCap = INHERENTLY_REPEATABLE_TOOL_SET.has(toolName)
-        ? PER_TOOL_REPEATABLE_CAP
-        : PER_TOOL_DEFAULT_CAP;
+        ? config.perToolRepeatableCap
+        : config.perToolDefaultCap;
     if (perToolCount > perToolCap) {
         return {
             block: true,
             reason: `Tool loop detected (repeated tool): ${toolName} called ${perToolCount} times ` +
                 `this turn (cap ${perToolCap}). Blocking to prevent infinite loop. ` +
                 `The tool may be unavailable or failing repeatedly. ` +
+                `Raise tool_call_loop_guard.repeated_tool.default_cap/repeatable_cap or add "${toolName}" ` +
+                `to tool_call_loop_guard.repeated_tool.exempt_tools in .gsd/PREFERENCES.md ` +
+                `(or GSD_TOOL_LOOP_REPEATED_* / GSD_TOOL_LOOP_EXEMPT_TOOLS) if this is expected. ` +
                 `Do not retry this tool or pivot to other tools this turn — stop and respond to the user in text.`,
             count: perToolCount,
         };
     }
     return { block: false, count: consecutiveCount };
 }
-/** Record successful mutation progress so Guard 2 can decay on the next count. */
-export function recordToolCallLoopMutation(toolName) {
+/**
+ * Record successful state progress so Guard 2 can decay on the next count.
+ * File mutations (edit/write/…) and successful shell/exec calls (bash,
+ * bg_shell, gsd_uat_exec, …) both count as progress (#1092, #1206). The caller
+ * only invokes this for non-error results, so failing improvisation loops
+ * (#783) never decay and still trip the per-tool cap.
+ */
+export function recordToolCallLoopMutation(toolName, details) {
     if (!enabled)
         return;
-    if (!STATE_MUTATING_TOOL_SET.has(toolName))
+    if (STATE_MUTATING_TOOL_SET.has(toolName)) {
+        mutationEpoch++;
+        return;
+    }
+    if (!STATE_PROGRESSING_EXEC_TOOL_SET.has(toolName))
+        return;
+    if (toolName === "bg_shell" && details !== undefined && !isSuccessfulBgShellLoopProgress(details))
         return;
     mutationEpoch++;
 }

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;
@@ -368,9 +506,15 @@ export function ensureCodebaseMapFresh(basePath, options, ensureOptions) {
     }
     const metadata = parseCodebaseMapMetadata(existing);
     const existingDescriptions = parseCodebaseMap(existing);
+    // Compare against the truncated count: when the repository has more tracked
+    // files than maxFiles, the map only lists the first maxFiles entries, so a
+    // stored fileCount above the cap (e.g. from an older map that recorded the
+    // full count) still matches the current truncated listing. Comparing raw
+    // values would flag "file-count-changed" on every turn, rewriting the
+    // timestamp and invalidating the provider KV cache prefix.
     const staleReason = !metadata ? "missing-metadata"
         : metadata.fingerprint !== fingerprint ? "files-changed"
-            : metadata.fileCount !== listed.files.length ? "file-count-changed"
+            : Math.min(metadata.fileCount, resolved.maxFiles) !== listed.files.length ? "file-count-changed"
                 : metadata.truncated !== listed.truncated ? "truncation-changed"
                     : undefined;
     if (!staleReason) {