@@ -400,7 +400,16 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
             sid = arguments["session_id"]
             session = _store.get(sid)
             if session:
-                _write_generation_metadata(session)
+                # Only stamp the incremental-update baseline when this
+                # session actually produced docs — otherwise an aborted
+                # session would make the next analyze_repo report
+                # "Documentation is up to date" over missing/stale docs.
+                if session.docs_written > 0:
+                    _write_generation_metadata(session)
+                else:
+                    logger.info(
+                        "Session %s wrote no docs; skipping metadata.json baseline update", sid
+                    )
                 # Clean up workspace files on disk
                 if session.workspace is not None:
                     session.workspace.cleanup()
@@ -482,8 +491,9 @@ async def _legacy_generate_docs(arguments: dict[str, Any]) -> list[TextContent]:
         agent_instructions=agent_instructions or None,
     )
 
+    from codewiki.cli.utils.repo_validator import get_git_commit_hash
     from codewiki.src.be.documentation_generator import DocumentationGenerator
-    doc_gen = DocumentationGenerator(backend_config)
+    doc_gen = DocumentationGenerator(backend_config, commit_id=get_git_commit_hash(repo_path) or None)
     await doc_gen.run()
 
     generated_files = []
@@ -554,13 +564,13 @@ def _write_generation_metadata(session: SessionState) -> None:
         output_dir = Path(session.output_dir)
         repo_path = Path(session.repo_path)
 
-        commit_id: str | None = None
-        try:
-            import git
-            repo = git.Repo(repo_path, search_parent_directories=True)
-            commit_id = repo.head.commit.hexsha
-        except Exception:
-            pass
+        # Baseline on the commit analyze_repo saw, NOT the current HEAD:
+        # commits made mid-session were never analyzed, and recording HEAD
+        # here would silently exclude them from the next incremental run.
+        commit_id: str | None = session.analyzed_commit
+        if not commit_id:
+            from codewiki.cli.utils.repo_validator import get_git_commit_hash
+            commit_id = get_git_commit_hash(repo_path) or None
 
         from datetime import datetime
 
 
@@ -39,6 +39,13 @@ class SessionState:
     module_tree: Dict[str, Any] = field(default_factory=dict)
     registry: Dict[str, Any] = field(default_factory=dict)
     workspace: Optional[SessionWorkspace] = field(default=None)
+    # HEAD commit at analyze_repo time — the incremental-update baseline.
+    # close_session must record this commit (not the HEAD at close time),
+    # otherwise commits made mid-session are baselined away undocumented.
+    analyzed_commit: Optional[str] = None
+    # Number of successful write_doc_file/edit_doc_file operations; used to
+    # skip the metadata.json baseline update when a session wrote no docs.
+    docs_written: int = 0
     created_at: float = field(default_factory=time.time)
     last_accessed: float = field(default_factory=time.time)
 
 
@@ -125,29 +125,8 @@ def _detect_via_git(
     if subpath == ".":
         subpath = ""
 
-    changed: list[str] = []
-    method = "git"
-
-    # 1) Committed changes since last generation
-    if prev_commit != current_commit:
-        try:
-            diff_index = repo.commit(prev_commit).diff(current_commit)
-            seen: set[str] = set()
-            for diff in diff_index:
-                for p in (diff.a_path, diff.b_path):
-                    if p and p not in seen:
-                        if subpath:
-                            if p.startswith(subpath + "/"):
-                                p = p[len(subpath) + 1:]
-                            else:
-                                continue  # outside target subdirectory
-                        changed.append(p)
-                        seen.add(p)
-        except Exception:
-            pass
-
-    # 2) Uncommitted changes: staged (index vs HEAD) + unstaged (working tree vs index) + untracked
-    # Compute output_dir relative prefix so we can skip generated docs
+    # Output-dir prefix (relative to repo_path) so generated docs, metadata
+    # and session workspace files never count as source changes.
     output_dir_rel = ""
     if output_dir is not None:
         try:
@@ -157,34 +136,57 @@ def _detect_via_git(
         except (ValueError, TypeError):
             pass
 
+    def _normalize(p: str) -> Optional[str]:
+        """Strip the monorepo subpath and drop generated/non-source paths."""
+        if subpath:
+            if not p.startswith(subpath + "/"):
+                return None  # outside target subdirectory
+            p = p[len(subpath) + 1:]
+        if p.startswith(".codewiki/"):
+            return None
+        if output_dir_rel and (p == output_dir_rel or p.startswith(output_dir_rel + "/")):
+            return None
+        return p
+
+    changed: list[str] = []
+    seen: set[str] = set()
+
+    def _add(raw: Optional[str]) -> None:
+        if raw:
+            p = _normalize(raw)
+            if p and p not in seen:
+                changed.append(p)
+                seen.add(p)
+
+    # 1) Committed changes since last generation
+    if prev_commit != current_commit:
+        try:
+            diff_index = repo.commit(prev_commit).diff(current_commit)
+        except Exception:
+            # Baseline commit unreachable (shallow clone, rebase, gc).
+            # Committed changes can't be enumerated, and returning an empty
+            # list here would falsely report "up to date" on a clean tree —
+            # fall back to mtime detection instead.
+            logger.warning(
+                "Stored commit %s is unreachable in %s; falling back to mtime detection",
+                prev_commit, repo_path,
+            )
+            return None
+        for diff in diff_index:
+            for p in (diff.a_path, diff.b_path):
+                _add(p)
+
+    # 2) Uncommitted changes: staged (index vs HEAD) + unstaged (working tree vs index) + untracked
     try:
         for d in list(repo.index.diff("HEAD")) + list(repo.index.diff(None)):
-            p = d.a_path
-            if p and p not in changed:
-                if subpath:
-                    if p.startswith(subpath + "/"):
-                        p = p[len(subpath) + 1:]
-                    else:
-                        continue
-                changed.append(p)
+            _add(d.a_path)
+            _add(d.b_path)
         for item in repo.untracked_files:
-            p = item
-            if subpath:
-                if p.startswith(subpath + "/"):
-                    p = p[len(subpath) + 1:]
-                else:
-                    continue
-            # Skip generated docs and session workspace files
-            if p.startswith(".codewiki/"):
-                continue
-            if output_dir_rel and (p == output_dir_rel or p.startswith(output_dir_rel + "/")):
-                continue
-            if p not in changed:
-                changed.append(p)
+            _add(item)
     except Exception:
         pass
 
-    return {"changed_files": changed, "method": method}
+    return {"changed_files": changed, "method": "git"}
 
 
 def _detect_via_mtime(
@@ -327,6 +329,11 @@ def handle_analyze_repo(
         leaf_nodes=leaf_nodes,
     )
 
+    # Record the analyzed commit now — close_session uses it as the
+    # incremental-update baseline in metadata.json.
+    from codewiki.cli.utils.repo_validator import get_git_commit_hash
+    session.analyzed_commit = get_git_commit_hash(repo_path) or None
+
     # Create the workspace with the real session_id
     workspace = SessionWorkspace(repo_path, session.session_id)
     session.workspace = workspace
 
@@ -47,7 +47,7 @@ def handle_read_code_components(
             not_found.append(cid)
             continue
         lang = getattr(node, "language", "")
-        source = getattr(node, "source_code", "").strip()
+        source = (getattr(node, "source_code", None) or "").strip()
         file_path = workspace.write_component_source(cid, source, lang)
         written_files[file_path.name] = cid
 
 
@@ -95,6 +95,7 @@ async def handle_write_doc_file(
         })
 
     await asyncio.to_thread(doc_path.write_text, content, "utf-8")
+    session.docs_written += 1
 
     # Mermaid validation
     mermaid_result = await _validate_mermaid(str(doc_path), filename)
@@ -150,9 +151,7 @@ async def handle_edit_doc_file(
     if not await asyncio.to_thread(doc_path.exists):
         return json.dumps({"error": f"File not found: {filename}. Use write_doc_file to create it."})
 
-    # Save current content to history before editing
     current_content = await asyncio.to_thread(doc_path.read_text, "utf-8")
-    _save_history(session, doc_path, current_content)
 
     if command == "str_replace":
         old_str = arguments.get("old_str")
@@ -167,6 +166,9 @@ async def handle_edit_doc_file(
             return json.dumps({"error": f"old_str appears {occurrences} times in {filename}. Make it unique."})
 
         new_content = current_content.replace(old_str, new_str, 1)
+        # Save history only for edits that actually happen, so undo never
+        # pops a no-op entry left behind by a failed/rejected command.
+        _save_history(session, doc_path, current_content)
         await asyncio.to_thread(doc_path.write_text, new_content, "utf-8")
 
         # Snippet around the edit
@@ -187,6 +189,7 @@ async def handle_edit_doc_file(
         new_str_lines = new_str.split("\n")
         lines = lines[:insert_line] + new_str_lines + lines[insert_line:]
         new_content = "\n".join(lines)
+        _save_history(session, doc_path, current_content)
         await asyncio.to_thread(doc_path.write_text, new_content, "utf-8")
 
         start = max(0, insert_line - 4)
@@ -196,6 +199,8 @@ async def handle_edit_doc_file(
     else:
         return json.dumps({"error": f"Unknown command: {command}. Use str_replace, insert, or undo."})
 
+    session.docs_written += 1
+
     # Mermaid validation
     mermaid_result = await _validate_mermaid(str(doc_path), filename)
 
 
@@ -42,8 +42,13 @@ def _safe_filename(component_id: str) -> str:
     A short hash suffix is appended to prevent collisions when different
     component IDs sanitize to the same string (e.g. ``src/a-b.py`` vs
     ``src/a_b.py``).
+
+    The sanitized part is truncated so the filename stays under the
+    common 255-byte NAME_MAX (separator chars expand to two chars each,
+    so deep paths overflow it easily); the hash suffix keeps truncated
+    names unique.
     """
-    sanitized = re.sub(r"[^\w\-.]", "__", component_id)
+    sanitized = re.sub(r"[^\w\-.]", "__", component_id)[:180]
     hash_suffix = hashlib.sha1(component_id.encode()).hexdigest()[:8]
     return f"{sanitized}_{hash_suffix}.src"
 
 
@@ -237,17 +237,27 @@ async def validate_single_diagram(diagram_content: str, diagram_num: int, line_s
     Returns:
         Error message if invalid, empty string if valid
     """
+    global _MERMAID_PY_BROKEN
     core_error = await _try_pythonmonkey_parse(diagram_content)
     if core_error is None:
         if _MERMAID_PY_BROKEN:
-            return f"  Diagram {diagram_num}: validation skipped (mermaid-py unavailable; set MERMAID_VALIDATE=0 to suppress)"
+            # Validation disabled/unavailable is not a syntax error — a
+            # non-empty return here would make callers report valid diagrams
+            # as broken and send agents into fix loops.
+            logger.debug("Diagram %d: validation skipped (mermaid-py disabled or unavailable)", diagram_num)
+            return ""
         try:
             core_error = await asyncio.wait_for(
                 asyncio.to_thread(_parse_via_mermaid_py, diagram_content),
                 timeout=15.0,
             )
         except asyncio.TimeoutError:
-            return f"  Diagram {diagram_num}: validation timed out (15s) — diagram may be invalid"
+            # Inconclusive, not a parse failure. Latch so the remaining
+            # diagrams (and later calls) don't each block 15s on the same
+            # broken Node.js setup.
+            _MERMAID_PY_BROKEN = True
+            logger.warning("Diagram %d: mermaid validation timed out (15s); skipping further validation", diagram_num)
+            return ""
         except Exception as e:
             return f"  Diagram {diagram_num}: Exception during validation - {str(e)}"