@tea-agent/loop-agent 0.44.0-next.4 → 0.44.0-next.5

package/CHANGELOG.md

@@ -2,11 +2,16 @@
 
 ## [Unreleased]
 
+- 修复 Windows 上 pi 节点零提交失败的读写守卫误报：libuv 在 win32 的 `fstat` 返回卷序列号而 `lstat` 恒为 0，跨 API 比较必然失败并误报“文件在打开期间被替换”；现新建共享身份比较 helper，win32 跳过跨 API `dev` 比较但保留 `ino` 与其余全部防护，Console 仓库预览同类比较一并修复（用户 0.42.1/0.43.0 两次实测上报）。
+- 修复研发工作流对 Git submodule 的误拦截：父仓库 `git status` 只能看到 submodule 目录级条目，子仓库内合法写入会被误判 `empty-diff`（脏基线）或越界（净基线），导致 verify/review/closeout 全部跳过；现在状态采集会展开到已初始化子仓库的文件级事实（含嵌套 submodule、中文/带引号路径解码、未初始化与采集失败时如实报错不吞证据），合法子仓库写入正常进入验证链，真实越界仍按文件精确拦截，无 submodule 仓库行为字节级不变。
+
 - Console 新增低饱和的「暮色蓝」深色与「雾光白」浅色主题，保留默认暖纸色；柔和背景、轻量选中态与独立按钮配色减少视觉刺激。顶部仅显示带「主题」悬停提示的紧凑明暗图标按钮，点击后展开「默认 / 深色 / 浅色」，选完自动收起，支持点击外部或 Escape 关闭；初始使用默认主题；即时切换对话、操作与观测界面，刷新后记住选择，浏览器存储不可用时仍可在当前页面切换。
 - Operator Chat 消息流后续对齐：折叠摘要现在统计 retry/step/command/unknown 等 durable 过程节点，Trajectory 与 HTML 导出保留 DAG progress，并使用稳定过程身份避免直播插入导致 Thinking/工具行重挂载。
 - Operator Chat 统一主时间线、Trajectory 与导出使用同一 DSH flow projection：Thinking、工具、重试、命令和完成态节点按事件序交错，保留 completed-turn 折叠；request/unknown 详情改为有界结构化摘要，不再回显裸节点 JSON。
 - Operator Chat 的消息流对齐 DSH Conversation Node：模型步骤、重试、终止错误、输出上限、每次请求上下文、嵌套工具、`/sdd-bingo` 命令回执和未知事件均以稳定节点留痕；同一模型步骤的多次重试聚合为一条紧凑记录，Provider 终态错误改为轻量行且不再暴露原始响应；流式文本按动画帧合并发布，刷新和断线恢复保持同一身份与顺序，轨迹页面和导出同步展示。
- - Operator Chat 在后台断线重连后不再丢消息：检测到中断会自动补齐缺口内容，也不会把正常的历史回放误判成丢事件而反复重连。
+- Operator Chat 在后台断线重连后不再丢消息：检测到中断会自动补齐缺口内容，也不会把正常的历史回放误判成丢事件而反复重连。
+- Operator Chat 新增独立「上下文洞察」面板：提供当前上下文构成、按步/按轮趋势与累计/增量视图、上下文浏览器（系统提示、工具 Schema、消息、注入、工具结果、技能）、上下文事件筛选、文件活动筛选排序，以及 token/cache/cost/timing 统计；`/context` 与详情栏「洞察」共用同一数据面。
+- 「上下文洞察」新增 token 构成饼图（conic-gradient 渲染）、剪枝/压缩明细（区分 prune 与 compact 事件，展示前/后/回收 tokens、移除项数、原因）；趋势柱 hover/click 实时联动上下文浏览器。
 - Operator Chat 的恢复快照现在只会合并属于目标会话的乐观提交；切换会话后，旧会话尚未确认的输入不会再因延迟重连恢复而显示到新会话中。
 - `/sdd-bingo` 成功提示现在展示上报的 Skill 与 Session ID；轨迹顶部会出现当前会话的常驻 SDD 身份栏，可一键复制、首次请求后自动更新；该上报以独立“操作”事件留痕，刷新或导出后仍在，不再伪装成工具调用。
 - Operator Chat 发送消息后的空白光标改为 Codex 式“正在思考”，真实思考、工具过程或最终回答出现后自然接替；并修复了状态偶发显示在用户输入上方的问题。

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.44.0-next.4",
-  "gitSha": "6d1cd2f6dd13854cd48bcd4b38718a53cc24109a",
-  "builtAt": "2026-09-15T17:21:15.173Z"
+  "version": "0.44.0-next.5",
+  "gitSha": "da4e19a774406e1fe79611807fd241e56e6e4c17",
+  "builtAt": "2026-09-16T02:11:12.294Z"
 }

package/dist/executors/shell-write-guard.js

@@ -4,6 +4,7 @@ import { constants, createReadStream } from "node:fs";
 import { access, lstat, readlink, unlink } from "node:fs/promises";
 import path from "node:path";
 import { pathMatchesPattern } from "../shared/git-progress.js";
+import { expandWorkspaceStatus, hasGitmodulesFile, synthesizeExpandedPorcelain, } from "../shared/git-workspace-status.js";
 import { ResilientGitCommandError, runResilientGitCommand, } from "../shared/resilient-git.js";
 async function sha256File(filePath) {
     const hash = createHash("sha256");
@@ -411,6 +412,7 @@ async function resolveGitExecutableCandidates(platform, env) {
     return ["git"];
 }
 export async function readGitStatusPorcelain(cwd, options = {}) {
+    let parentPorcelain;
     try {
         const result = await runResilientGitCommand({
             cwd,
@@ -419,9 +421,12 @@ export async function readGitStatusPorcelain(cwd, options = {}) {
             attempts: options.attempts,
             retryDelayMs: options.retryDelayMs,
         });
-        if (result.code === 0)
-            return result.stdout;
-        throw new Error(result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`);
+        if (result.code === 0) {
+            parentPorcelain = result.stdout;
+        }
+        else {
+            throw new Error(result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`);
+        }
     }
     catch (error) {
         if (error instanceof ResilientGitCommandError) {
@@ -436,6 +441,24 @@ export async function readGitStatusPorcelain(cwd, options = {}) {
         }
         throw error;
     }
+    // Submodule workspaces: a parent-only porcelain hides every file inside a
+    // registered submodule behind a single directory-level gitlink entry,
+    // which historically produced false empty-diff and false violations
+    // (plan 2026-09-15-development-workflow-git-submodule). Repositories
+    // without .gitmodules keep the parent bytes verbatim — byte-identical
+    // behavior for every non-submodule workspace.
+    if (!(await hasGitmodulesFile(cwd)))
+        return parentPorcelain;
+    const observation = await expandWorkspaceStatus({
+        rootCwd: cwd,
+        parentPorcelain,
+        hasGitmodulesFile: true,
+    });
+    if (!observation.complete) {
+        const failed = observation.repos.find((repo) => repo.state === "status-read-failed");
+        throw new Error(`workspace status expansion incomplete: submodule ${failed?.repoRelativePath ?? "unknown"} status read failed: ${failed?.errorDetail ?? "unknown error"}`);
+    }
+    return synthesizeExpandedPorcelain(observation.entries);
 }
 export async function readGitStatusPorcelainWithDependencies(cwd, options, dependencies) {
     const candidates = await dependencies.resolveExecutableCandidates();

package/dist/shared/file-identity.js

@@ -0,0 +1,23 @@
+/**
+ * Compare two stat records as the same file identity.
+ *
+ * POSIX: `dev` and `ino` together identify the inode; both must match.
+ *
+ * win32: libuv reports `dev` inconsistently across stat APIs — `fstat()`
+ * (from an open handle) returns the volume serial number while `lstat()`
+ * (from a path) returns 0. A cross-API comparison therefore always fails on
+ * Windows even when the path still refers to the same file, breaking every
+ * guard that rechecks identity after opening (user-reported on 0.42.1 and
+ * 0.43.0, Node 23.x). On win32 the `dev` field is skipped and `ino` plus the
+ * caller-side type/link/realpath checks remain the identity boundary.
+ *
+ * When both stats come from the same API the comparison is exact on every
+ * platform; the win32 relaxation only affects cross-API rechecks.
+ */
+export function sameFileIdentity(opened, current, platform = process.platform) {
+    if (current.ino !== opened.ino)
+        return false;
+    if (platform !== "win32" && current.dev !== opened.dev)
+        return false;
+    return true;
+}

package/dist/shared/git-workspace-status.js

@@ -0,0 +1,480 @@
+import { access, lstat } from "node:fs/promises";
+import path from "node:path";
+import { runResilientGitCommand } from "./resilient-git.js";
+const MAX_SUBMODULE_DEPTH = 4;
+export const DEFAULT_WORKSPACE_STATUS_DEPENDENCIES = {
+    runGit: (cwd, args) => runResilientGitCommand({ cwd, args, readOnly: true }).then((result) => ({
+        code: result.code,
+        stdout: result.stdout,
+        stderr: result.stderr,
+    })),
+    readSubmoduleStatus: async (cwd) => {
+        const result = await runResilientGitCommand({
+            cwd,
+            args: ["status", "--porcelain=v1", "--untracked-files=all"],
+            readOnly: true,
+        });
+        if (result.code !== 0) {
+            throw new Error(result.stderr.trim() ||
+                result.stdout.trim() ||
+                `git status exited ${result.code}`);
+        }
+        return result.stdout;
+    },
+};
+/** Parse porcelain v1 output into normalized path -> "XY" entries. */
+export function parsePorcelainEntries(porcelain) {
+    const entries = new Map();
+    for (const line of porcelain.split("\n")) {
+        const trimmed = line.trimEnd();
+        if (!trimmed)
+            continue;
+        const x = trimmed[0] ?? " ";
+        const y = trimmed[1] ?? " ";
+        const rawPath = trimmed.slice(3);
+        if (!rawPath)
+            continue;
+        const normalized = normalizeWorkspacePath(unquoteGitPath(renameTargetPath(rawPath)));
+        if (!normalized)
+            continue;
+        entries.set(normalized, `${x}${y}`);
+    }
+    return entries;
+}
+/**
+ * Return the destination path of a porcelain path field. Rename entries
+ * render as `ORIG -> DEST` where either side may independently be C-quoted;
+ * splitting on a quoted ` -> ` (or unquoting before splitting) corrupts the
+ * key with residual quotes or half-decoded octal. Scan for the last
+ * outside-quote separator instead, then return the still-quoted DEST for
+ * the caller to unquote.
+ */
+function renameTargetPath(rawPath) {
+    let inQuotes = false;
+    let separatorIndex = -1;
+    for (let i = 0; i < rawPath.length - 3; i += 1) {
+        const char = rawPath[i];
+        if (char === "\\") {
+            i += 1; // skip the escaped character; it cannot open/close quotes
+            continue;
+        }
+        if (char === '"')
+            inQuotes = !inQuotes;
+        if (!inQuotes && rawPath.startsWith(" -> ", i))
+            separatorIndex = i;
+    }
+    if (separatorIndex === -1)
+        return rawPath;
+    return rawPath.slice(separatorIndex + 4);
+}
+function normalizeWorkspacePath(value) {
+    const target = value.includes(" -> ")
+        ? (value.split(" -> ").at(-1) ?? value)
+        : value;
+    // Embedded-repo untracked entries render as `dir/`; strip the trailing
+    // slash so the key matches the registered submodule path form.
+    return target.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}
+/**
+ * Unquote a git C-quoted path (`"..."` with C-style escapes; non-ASCII bytes
+ * arrive as octal like \346\225\260). Returns the input unchanged when not
+ * quoted. This keeps Chinese/space paths (e.g. `source/需求.md`) comparable
+ * against writeSet patterns.
+ */
+export function unquoteGitPath(value) {
+    if (value.length < 2 || !value.startsWith('"') || !value.endsWith('"')) {
+        return value;
+    }
+    const inner = value.slice(1, -1);
+    let out = "";
+    for (let i = 0; i < inner.length; i += 1) {
+        const char = inner[i];
+        if (char !== "\\") {
+            out += char;
+            continue;
+        }
+        const next = inner[i + 1];
+        if (next === undefined)
+            break;
+        if (next === "n")
+            out += "\n";
+        else if (next === "t")
+            out += "\t";
+        else if (next === "r")
+            out += "\r";
+        else if (next === "\\")
+            out += "\\";
+        else if (next === '"')
+            out += '"';
+        else if (/[0-7]{3}/.test(inner.slice(i + 1, i + 4))) {
+            // Octal byte escape: collect consecutive escapes into one string
+            // and decode as UTF-8. `continue` skips the shared `i += 1` below
+            // (i already points past the consumed run).
+            const bytes = [];
+            let j = i;
+            while (j < inner.length && inner[j] === "\\" && /[0-7]{3}/.test(inner.slice(j + 1, j + 4))) {
+                bytes.push(Number.parseInt(inner.slice(j + 1, j + 4), 8));
+                j += 4;
+            }
+            out += Buffer.from(bytes).toString("utf8");
+            i = j - 1;
+            continue;
+        }
+        else {
+            out += next;
+        }
+        i += 1;
+    }
+    return out;
+}
+/**
+ * Read registered submodule directories from `.gitmodules` via
+ * `git config -f .gitmodules --get-regexp` (structured output; no
+ * shell-quoting hazards). Returns [] when the file is absent or empty.
+ */
+export async function readSubmoduleRegistrations(rootCwd, dependencies = DEFAULT_WORKSPACE_STATUS_DEPENDENCIES) {
+    const result = await dependencies.runGit(rootCwd, [
+        "config",
+        "-f",
+        ".gitmodules",
+        "--get-regexp",
+        "^submodule\\..*\\.path$",
+    ]);
+    // Exit 1 with no stderr = the file exists but has no matching keys.
+    // Any other non-zero exit (unreadable file, parse error) must fail closed:
+    // returning [] would silently drop every submodule from observation.
+    if (result.code === 1 && !result.stderr.trim())
+        return [];
+    if (result.code !== 0) {
+        throw new Error(`git config -f .gitmodules failed (exit ${result.code}): ${result.stderr.trim() || result.stdout.trim() || "no output"}`);
+    }
+    if (!result.stdout.trim())
+        return [];
+    const paths = [];
+    for (const line of result.stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        // Line format: `submodule.<name>.path <value>`. The value may contain
+        // spaces; split on the first space after the key only.
+        const separator = trimmed.indexOf(" ");
+        if (separator <= 0)
+            continue;
+        const submodulePath = trimmed.slice(separator + 1).trim();
+        if (!submodulePath)
+            continue;
+        paths.push(normalizeWorkspacePath(submodulePath));
+    }
+    return paths;
+}
+/**
+ * Probe the gitlink state of one submodule against its parent repository.
+ * Porcelain codes cannot distinguish "dirty content inside the submodule"
+ * (covered by the child's file-level entries) from "the child HEAD actually
+ * moved" (a git mutation the child's own clean status cannot express), so
+ * the relevant SHAs are compared directly.
+ *
+ * Three facts are captured so staged gitlinks and repeated moves cannot
+ * hide a mutation:
+ * - `indexSha`: what the parent index records for the gitlink now.
+ * - `headTreeSha`: what the parent HEAD tree records (detects `git add sub`
+ *   staged after a commit — the working gitlink moved but index == HEAD is
+ *   not the full story; see gitlinkMutated).
+ * - `headSha`: the child's checked-out HEAD.
+ *
+ * `readFailed` maps to the caller's fail-closed incomplete path.
+ */
+async function readGitlinkState(parentRoot, submodulePath, dependencies) {
+    const ls = await dependencies.runGit(parentRoot, [
+        "ls-files",
+        "-s",
+        "--",
+        submodulePath,
+    ]);
+    const line = ls.code !== 0
+        ? undefined
+        : ls.stdout.split("\n").find((entry) => entry.trim());
+    // `160000 <sha> 0\t<path>` for a gitlink entry.
+    const indexSha = line?.split(/\s+/)[1];
+    const headTree = await dependencies.runGit(parentRoot, [
+        "rev-parse",
+        `HEAD:${submodulePath}`,
+    ]);
+    const headTreeSha = headTree.code === 0 ? headTree.stdout.trim() : undefined;
+    const rev = await dependencies.runGit(joinFsPath(parentRoot, submodulePath), ["rev-parse", "HEAD"]);
+    const headSha = rev.code === 0 ? rev.stdout.trim() : undefined;
+    if (ls.code !== 0 || rev.code !== 0) {
+        return {
+            indexSha,
+            headTreeSha,
+            headSha,
+            readFailed: true,
+            errorDetail: `ls-files exit ${ls.code}; rev-parse exit ${rev.code}: ${rev.stderr.trim() || ls.stderr.trim() || "no output"}`,
+        };
+    }
+    return { indexSha, headTreeSha, headSha, readFailed: false };
+}
+/**
+ * A gitlink mutation is any state where the working gitlink (child HEAD)
+ * disagrees with what the parent's committed or staged history expects, or
+ * where the parent index gitlink is itself dirty relative to HEAD:
+ * - child HEAD != index: writer moved the submodule HEAD (committed inside
+ *   the submodule, or checked out another commit).
+ * - index != HEAD tree: the gitlink change was staged (`git add sub`) but
+ *   not committed — still an unauthorized git mutation during a run.
+ * - child HEAD != HEAD tree (index clean): a moved HEAD not yet staged;
+ *   the classic in-submodule commit.
+ * When the parent has never committed the submodule (fresh `submodule add`,
+ *   no `HEAD:<path>`), only the index-vs-child comparison applies.
+ */
+function gitlinkMutated(state) {
+    const { indexSha, headTreeSha, headSha } = state;
+    if (indexSha !== undefined && headSha !== undefined && indexSha !== headSha) {
+        return true;
+    }
+    if (headTreeSha !== undefined &&
+        indexSha !== undefined &&
+        headTreeSha !== indexSha) {
+        return true;
+    }
+    if (headTreeSha !== undefined &&
+        headSha !== undefined &&
+        headTreeSha !== headSha) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Sentinel key for a mutated gitlink. Embeds the observed SHA triple so the
+ * key changes when the gitlink moves again (a constant key would make a
+ * second move on a dirty baseline indistinguishable from no move).
+ */
+function gitlinkSentinelKey(workspacePath, state) {
+    const fingerprint = [state.indexSha, state.headTreeSha, state.headSha]
+        .map((sha) => sha ?? "-")
+        .join("+");
+    return `${GITLINK_SENTINEL_PREFIX}${workspacePath}@${fingerprint}`;
+}
+async function submoduleWorkingTreeInitialized(rootCwd, submodulePath) {
+    try {
+        const info = await lstat(path.resolve(rootCwd, ...submodulePath.split("/"), ".git"));
+        return info.isFile() || info.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function collectSubmoduleEntries(input) {
+    // undefined = collection failed for this submodule (recorded, fail-closed).
+    const repoRoot = joinFsPath(input.rootCwd, input.workspacePath);
+    try {
+        const porcelain = await input.dependencies.readSubmoduleStatus(repoRoot);
+        input.repos.push({
+            repoRelativePath: input.repoWorkspacePath,
+            repoId: input.repoWorkspacePath,
+            state: "clean-status-read",
+            porcelain,
+        });
+        const childEntries = parsePorcelainEntries(porcelain);
+        const expanded = new Map();
+        for (const [childPath, code] of childEntries) {
+            expanded.set(`${input.repoWorkspacePath}/${childPath}`, code);
+        }
+        if (input.depth < MAX_SUBMODULE_DEPTH) {
+            const nestedPaths = await readSubmoduleRegistrations(repoRoot, input.dependencies);
+            for (const nestedPath of nestedPaths) {
+                const nestedWorkspacePath = `${input.repoWorkspacePath}/${nestedPath}`;
+                const initialized = await submoduleWorkingTreeInitialized(repoRoot, nestedPath);
+                if (!initialized) {
+                    input.repos.push({
+                        repoRelativePath: nestedWorkspacePath,
+                        repoId: nestedWorkspacePath,
+                        state: "uninitialized",
+                        porcelain: "",
+                    });
+                    continue;
+                }
+                // Gitlink probe at this nesting level: the parent of `nested` is the
+                // current repository (repoRoot). Same three-SHA semantics as the
+                // top level; a moved nested HEAD surfaces as a SHA-tagged sentinel.
+                const nestedGitlink = await readGitlinkState(repoRoot, nestedPath, input.dependencies);
+                if (nestedGitlink.readFailed) {
+                    input.repos.push({
+                        repoRelativePath: nestedWorkspacePath,
+                        repoId: nestedWorkspacePath,
+                        state: "status-read-failed",
+                        porcelain: "",
+                        errorDetail: `gitlink probe failed: ${nestedGitlink.errorDetail ?? "unknown"}`,
+                    });
+                    continue;
+                }
+                const nestedEntries = await collectSubmoduleEntries({
+                    rootCwd: repoRoot,
+                    workspacePath: nestedPath,
+                    repoWorkspacePath: nestedWorkspacePath,
+                    depth: input.depth + 1,
+                    repos: input.repos,
+                    dependencies: input.dependencies,
+                });
+                if (nestedEntries === undefined) {
+                    // Nested collection failures are recorded in the shared
+                    // repos array with state status-read-failed; completeness
+                    // is derived from those states after the top-level loop.
+                    continue;
+                }
+                for (const [nestedFile, code] of nestedEntries) {
+                    // nestedEntries keys are already full workspace paths
+                    // (prefixed with nestedWorkspacePath).
+                    expanded.set(nestedFile, code);
+                }
+                if (gitlinkMutated(nestedGitlink)) {
+                    expanded.set(gitlinkSentinelKey(nestedWorkspacePath, nestedGitlink), "M ");
+                }
+                // Drop the child's own directory-level entry for the nested
+                // submodule (gitlink ` M nested` or embedded `?? nested/`);
+                // its file facts now come from the nested repository.
+                expanded.delete(`${input.repoWorkspacePath}/${nestedPath}`);
+            }
+        }
+        return expanded;
+    }
+    catch (error) {
+        input.repos.push({
+            repoRelativePath: input.repoWorkspacePath,
+            repoId: input.repoWorkspacePath,
+            state: "status-read-failed",
+            porcelain: "",
+            errorDetail: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+}
+function joinFsPath(root, workspacePath) {
+    return path.resolve(root, ...workspacePath.split("/"));
+}
+/**
+ * Expand a parent porcelain snapshot into workspace file-level facts.
+ * Callers pass the already-captured parent porcelain so the parent bytes are
+ * captured once and reused.
+ */
+export async function expandWorkspaceStatus(input) {
+    const dependencies = input.dependencies ?? DEFAULT_WORKSPACE_STATUS_DEPENDENCIES;
+    const parentEntries = parsePorcelainEntries(input.parentPorcelain);
+    const repos = [
+        {
+            repoRelativePath: "",
+            repoId: "parent",
+            state: "clean-status-read",
+            porcelain: input.parentPorcelain,
+        },
+    ];
+    const entries = new Map();
+    let complete = true;
+    const registrations = input.hasGitmodulesFile
+        ? await readSubmoduleRegistrations(input.rootCwd, dependencies)
+        : [];
+    for (const registration of registrations) {
+        const initialized = await submoduleWorkingTreeInitialized(input.rootCwd, registration);
+        if (!initialized) {
+            repos.push({
+                repoRelativePath: registration,
+                repoId: registration,
+                state: "uninitialized",
+                porcelain: "",
+            });
+            continue;
+        }
+        // Gitlink probe: SHA-compare the parent index gitlink against the
+        // child's checked-out HEAD. Only a real HEAD move (e.g. the writer
+        // committed inside the submodule) becomes a sentinel; dirty child
+        // content stays covered by the child's file-level entries.
+        const gitlink = await readGitlinkState(input.rootCwd, registration, dependencies);
+        if (gitlink.readFailed) {
+            repos.push({
+                repoRelativePath: registration,
+                repoId: registration,
+                state: "status-read-failed",
+                porcelain: "",
+                errorDetail: `gitlink probe failed: ${gitlink.errorDetail ?? "unknown"}`,
+            });
+            complete = false;
+            continue;
+        }
+        const submoduleEntries = await collectSubmoduleEntries({
+            rootCwd: input.rootCwd,
+            workspacePath: registration,
+            repoWorkspacePath: registration,
+            depth: 1,
+            repos,
+            dependencies,
+        });
+        if (submoduleEntries === undefined) {
+            complete = false;
+            continue;
+        }
+        for (const [workspacePath, code] of submoduleEntries) {
+            entries.set(workspacePath, code);
+        }
+        if (gitlinkMutated(gitlink)) {
+            entries.set(gitlinkSentinelKey(registration, gitlink), "M ");
+        }
+    }
+    // Completeness is derived from the recorded repo states: any
+    // status-read-failed repository at any depth (top-level or nested)
+    // makes the observation incomplete, so nested failures bubble up.
+    // (.gitmodules read failures throw and fail the whole observation.)
+    const completeNow = complete &&
+        !repos.some((repo) => repo.state === "status-read-failed");
+    // Parent entries: keep everything except directory-level gitlink entries
+    // of submodules whose own status was read successfully AND whose gitlink
+    // is unchanged. When the parent still reports the submodule as modified
+    // (gitlink differs from the index — the writer committed inside the
+    // submodule, or checked out another commit), keep a sentinel entry so the
+    // change stays visible in the expanded delta instead of silently
+    // vanishing behind the child's clean status. The child's clean file-level
+    // status cannot distinguish "gitlink untouched" from "gitlink moved";
+    // only the parent entry can, so it is preserved whenever non-clean.
+    const expandedRegistrations = new Set(repos
+        .filter((repo) => repo.repoRelativePath !== "" &&
+        repo.state === "clean-status-read")
+        .map((repo) => repo.repoRelativePath));
+    for (const [parentPath, code] of parentEntries) {
+        if (expandedRegistrations.has(parentPath)) {
+            // Directory-level submodule entries are dropped: file-level facts
+            // come from the child repos, and a moved gitlink is surfaced by the
+            // SHA probe as a sentinel during the registration loop. Porcelain
+            // codes cannot distinguish dirty content from a moved HEAD, so no
+            // code-based sentinel may be derived here.
+            continue;
+        }
+        if (entries.has(parentPath))
+            continue; // child facts take precedence
+        entries.set(parentPath, code);
+    }
+    return {
+        parentPorcelain: input.parentPorcelain,
+        entries,
+        repos,
+        complete: completeNow,
+    };
+}
+/** Prefix marking a preserved parent gitlink fact (mutated submodule HEAD). */
+export const GITLINK_SENTINEL_PREFIX = "\u0000gitlink\u0000/";
+/** Serialize expanded entries back into sorted porcelain-v1-shaped lines. */
+export function synthesizeExpandedPorcelain(entries) {
+    const lines = [];
+    for (const [filePath, code] of [...entries.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+        lines.push(`${code} ${filePath}`);
+    }
+    return lines.join("\n") + (lines.length > 0 ? "\n" : "");
+}
+/** Check for a `.gitmodules` file at the repository root. */
+export async function hasGitmodulesFile(rootCwd) {
+    try {
+        await access(path.resolve(rootCwd, ".gitmodules"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/shared/path-safety.js

@@ -1,6 +1,7 @@
 import { constants as fsConstants } from "node:fs";
 import { lstat, open, realpath } from "node:fs/promises";
 import path from "node:path";
+import { sameFileIdentity } from "./file-identity.js";
 function assertContained(root, target, label) {
     if (target === root || !target.startsWith(`${root}${path.sep}`)) {
         throw new Error(`${label}: path escapes boundary: ${target}`);
@@ -81,8 +82,7 @@ export async function readFileBoundarySafe(input) {
         if (current.isSymbolicLink() ||
             !current.isFile() ||
             current.nlink !== 1 ||
-            current.dev !== opened.dev ||
-            current.ino !== opened.ino) {
+            !sameFileIdentity(opened, current)) {
             throw new Error(`${input.label}: path changed while opening`);
         }
         return await handle.readFile();