kolega-code 0.27.1__tar.gz → 0.28.1__tar.gz

{kolega_code-0.27.1 → kolega_code-0.28.1}/CHANGELOG.md

@@ -6,6 +6,162 @@ This project uses GitHub Releases for detailed generated release notes. This fil
 
 ## Unreleased
 
+## 0.28.1 - 2026-08-12
+
+### Fixed
+
+- Restored native Tinker tool dispatch so generated tool calls execute through
+  the agent loop instead of being returned as plain assistant output.
+
+## 0.28.0 - 2026-08-11
+
+### Added
+
+- ATIF v1.7 trajectory export: `sessions export --format atif` converts any
+  session (including pre-upgrade v1 sessions, with explicit conversion
+  warnings) into a validated [ATIF](https://github.com/harbor-framework/harbor/blob/main/rfcs/0001-trajectory-format.md)
+  document, and `ask --atif-output FILE` writes one directly when a run ends —
+  completed, failed, or cancelled, with or without `--save`. Embedded subagent
+  trajectories, per-step token metrics, hydrated oversized tool results, and
+  atomic file+assets output; image trajectories require `--output`/a file
+  destination for portable relative asset paths.
+
+- The interactive CLI and `ask` can now load one installed Python extension at
+  launch with `--extension MODULE:FACTORY` and an optional opaque
+  `--extension-config PATH`. An extension contributes ordinary prompt and tool
+  extensions, binds to each top-level agent generation before its first model
+  request, may observe structured LLM trace records (forwarded to every LLM
+  client like the usage ledger), and is cleaned up exactly once per generation,
+  including on interactive agent rebuilds. Extension contracts are exported
+  from the package root, alongside `llm_call_origin`/`helper_origin` and
+  `TinkerTraceRecord`; a minimal example package lives in `examples/extension`.
+
+- Agent Skills can now be enabled or disabled from Settings,
+  `settings.json`, `KOLEGA_CODE_SKILLS`, or `--skills on|off`.
+
+- The TUI status usage panel now shows the provider cache hit percentage
+  alongside the other usage figures.
+
+- After quitting, the CLI prints the exact
+  `kolega-code . --resume <id>` command to resume the session that was just
+  saved.
+
+- Hosts can now continue a restored conversation without inserting a user
+  message: `BaseAgent.continue_from_history_stream()` runs the ordinary agent
+  loop (compaction, tool execution, usage accounting, and cancellation
+  included) and yields the same chunk format. Sessions containing such a
+  continuation turn are not loadable by older kolega-code versions.
+
+- Oversized terminal command output is now spilled to a file instead of being
+  lost: the tool result keeps the bounded head/tail preview plus a path to
+  the full output, and the PTY is drained before detaching so a killed
+  command keeps its final output.
+
+### Changed
+
+- Automatic compaction now gets one recovery attempt when the ordinary pass —
+  which keeps the six most recent messages verbatim — still leaves a request
+  above the model's resolved input budget: a second pass with no retained tail
+  (`keep_recent=0`, journaled with trigger `auto_tail_fallback`) folds
+  everything before the safe boundary into the summary, still without touching
+  the raw history or splitting a tool call from its result. A pass that failed
+  at the model or hit the minimum-history guard is not retried. When the paired
+  `--context-window-tokens` + `--max-output-tokens` cap is active and the
+  request still does not fit, the run now fails closed with
+  `LLMContextWindowExceededError` before the primary model is called (recorded
+  as the `run.failed` error code) instead of dispatching the oversized request;
+  uncapped runs keep the legacy provider-accept-or-reject behavior.
+
+- **Breaking:** `kolega-code ask --json` now streams the semantic session-event
+  protocol — one v2 event envelope per line (`schema: "kolega.session.event"`,
+  stable `id`/`seq`/`timestamp`, agent lineage, typed `payload`) — replacing
+  the former `{"kind": "message"|"event"|"summary"}` records with no
+  compatibility flag. Live output and the new
+  `sessions export --format events-jsonl` return the same records. Every run
+  records the full journal (LLM call ids, subagent turns and tool results,
+  `context.system`, compaction/rewind provenance, and `run.completed`/
+  `run.failed`/`run.cancelled` terminals on every exit path); unsaved runs use
+  an in-memory journal and leave no session state. Plain (non-JSON) `ask`
+  output is unchanged. Session journals now write schema v2 events (v1
+  sessions remain readable; resumed v1 sessions append v2 lines — older
+  kolega-code versions will refuse to read those journals rather than
+  mis-replaying them).
+
+- Tool definitions are now explicit, checked-in artifacts. Every built-in
+  tool's model-visible description lives as data beside the prompt assets
+  (`kolega_code/agent/prompt_templates/tools/`) and its input schema as a
+  literal dict in `kolega_code/agent/tool_definitions.py`; nothing about what
+  the model sees is derived from signatures or docstrings anymore, and the
+  migration is byte-identical on the wire. `ToolExtension` tools (including
+  CLI extensions loaded with `--extension` and MCP tools) now declare an
+  explicit `tool_descriptions` entry alongside `tool_schemas`; a tool missing
+  either fails at registration with a clear error before any model request.
+
+- TUI responsiveness for long sessions is improved: the transcript scrollback
+  window is capped at 120 mounted entries (scroll-up still walks the full
+  history), flush cadences are unified and paced by event-loop lateness,
+  modal inspectors stay on the unpaced base cadence, and the native Tinker
+  stack no longer loads at package import time — faster startup and fewer
+  event-loop stalls.
+
+### Removed
+
+- The `tool_definition_from_callable` helper (and the `Args:`-block
+  strip/keep rules behind it) is gone, including its `kolega_code` package
+  root export: definitions are declared, not derived.
+
+### Fixed
+
+- A session could be opened in two kolega-code instances at once, interleaving
+  duplicate event sequence numbers into the session journal until it became
+  unreadable (and `switch_worktree`/`save` failed with "Session event sequence
+  gap"). Resuming a session that is already open in another instance is now
+  refused with a clear error, journal appends allocate sequence numbers under
+  a cross-process lock, and `kolega-code sessions repair <id>` renumbers a
+  corrupted journal back into a contiguous sequence.
+
+- File tools (`read`, `write`, `edit`, `multi_edit`, `read_image`) now expand
+  a `$KOLEGA_SCRATCHPAD` (or `${KOLEGA_SCRATCHPAD}`) reference in path
+  arguments to the session scratchpad at the tool-dispatch choke point, so
+  the shell spelling no longer creates a literal `$KOLEGA_SCRATCHPAD`
+  directory in the workspace.
+
+- Runtime model-catalog caches created before input-budget conventions were
+  introduced are now ignored safely instead of injecting incomplete model
+  specs that fail later with `KeyError: 'input_budget'`. Refreshing a catalog
+  rewrites it in the current schema.
+
+- Kimi Coding Plan model IDs now match the provider's real wire IDs:
+  `k3-256k` (fixed 256K K3 route) and `kimi-for-coding-highspeed` are
+  recognized, and the fabricated `k3[1m]` ID is gone (Kimi's 1M context is
+  the same `k3` ID, tier-gated). Kimi and Moonshot input budgets treat output
+  as a separate allowance (verified by live probes), so the full context
+  window is usable as input instead of being cut down by the output cap.
+
+- OpenAI and ChatGPT gpt-5.x requests that reproduced reserved Harmony
+  control-token spellings as data (for example after a tool result read a
+  file containing `<|channel|>`-style tokens) were rejected with
+  `APIError: Request blocked`, permanently poisoning the session. The
+  spellings are now escaped on the transport copy only — the persisted
+  transcript is unchanged — and already-poisoned sessions heal on the next
+  request.
+
+- Responses-based providers (OpenAI, ChatGPT, DeepSeek) now return multiple
+  tool calls per model round instead of one at a time.
+
+- After history compaction (automatic or `/compact`) the approved plan and
+  the shared task list are re-injected into the model's context as system
+  reminders, so the model no longer loses track of them mid-run.
+
+- Terminal sessions that end while a backgrounded `&` job still holds the PTY
+  are now reported as exited instead of spinning through the whole yield
+  window, and naturally exited sessions are hidden from the session listing
+  instead of lingering as stale entries.
+
+- The shared terminal-tools guidance now warns that `rg -r` means
+  `--replace` (recursion is the default), which previously made `rg -rn`
+  output look like a redaction layer.
+
 ## 0.27.1 - 2026-08-10
 
 ### Added

{kolega_code-0.27.1 → kolega_code-0.28.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.27.1
+Version: 0.28.1
 Summary: Multi-agent coding in the terminal
 Project-URL: Homepage, https://kolega-ai.github.io/kolega-code/
 Project-URL: Documentation, https://kolega-ai.github.io/kolega-code/
@@ -229,6 +229,7 @@ Classifier: Topic :: Software Development
 Classifier: Topic :: Utilities
 Requires-Python: >=3.11
 Requires-Dist: anthropic==0.101.0
+Requires-Dist: atif==1.7.0
 Requires-Dist: beautifulsoup4==4.14.3
 Requires-Dist: cryptography==48.0.1; sys_platform == 'darwin' and platform_machine == 'x86_64'
 Requires-Dist: cryptography==50.0.0; sys_platform != 'darwin' or platform_machine != 'x86_64'
@@ -277,7 +278,8 @@ Requires-Dist: pytest==9.0.3; extra == 'dev'
 Requires-Dist: ruff==0.15.12; extra == 'dev'
 Requires-Dist: twine==6.2.0; extra == 'dev'
 Provides-Extra: tinker
-Requires-Dist: tinker-cookbook==0.5.3; extra == 'tinker'
+Requires-Dist: tinker-cookbook==0.5.4; extra == 'tinker'
+Requires-Dist: tinker==0.25.0; extra == 'tinker'
 Requires-Dist: tml-renderers==0.1.0; extra == 'tinker'
 Description-Content-Type: text/markdown
 

{kolega_code-0.27.1 → kolega_code-0.28.1}/kolega_code/__init__.py

@@ -28,9 +28,22 @@ from .config import AgentConfig, ModelConfig, ModelProvider, RateLimitConfig
 from .events import AgentConnectionManager
 from .events import AgentEvent, AgentStatus
 
+# CLI-selected extensions
+from .extensions import (
+    KolegaExtensionBundle,
+    KolegaExtensionFactory,
+    KolegaExtensionHost,
+    KolegaExtensionLoadError,
+)
+
 # LLM clients and message models
 from .llm.client import LLMClient
 from .llm.instrumented_client import InstrumentedLLMClient
+from .llm.ledger import LlmCallOrigin, current_llm_call_origin, helper_origin, llm_call_origin
+
+# From the dependency-free leaf module: importing .llm.providers.tinker itself
+# loads the optional native stack (tinker-cookbook -> torch) when installed.
+from .llm.providers.tinker_trace import TinkerTraceRecord
 from .llm.models import (
     ImageBlock,
     Message,
@@ -56,7 +69,7 @@ from .agent.prompt_provider import (
 # Tools
 from .agent.tool_backend.base_tool import BaseTool
 from .agent.tools import ToolCollection, ToolCollectionConfig, ToolExtension
-from .tools import Tool, ToolError, ToolPolicy, ToolRegistry, tool_definition_from_callable
+from .tools import Tool, ToolError, ToolPolicy, ToolRegistry
 
 # Host environment services
 from .agent.common import LogMixin
@@ -102,9 +115,19 @@ __all__ = [
     "AgentConnectionManager",
     "AgentEvent",
     "AgentStatus",
+    # CLI-selected extensions
+    "KolegaExtensionBundle",
+    "KolegaExtensionFactory",
+    "KolegaExtensionHost",
+    "KolegaExtensionLoadError",
     # LLM
     "LLMClient",
     "InstrumentedLLMClient",
+    "LlmCallOrigin",
+    "current_llm_call_origin",
+    "helper_origin",
+    "llm_call_origin",
+    "TinkerTraceRecord",
     "ImageBlock",
     "Message",
     "MessageHistory",
@@ -130,7 +153,6 @@ __all__ = [
     "ToolError",
     "ToolPolicy",
     "ToolRegistry",
-    "tool_definition_from_callable",
     # Services
     "LogMixin",
     "BrowserManager",
@@ -151,4 +173,4 @@ __all__ = [
     "parse_git_status_output",
 ]
 
-__version__ = "0.27.1"
+__version__ = "0.28.1"

{kolega_code-0.27.1 → kolega_code-0.28.1}/kolega_code/_bundled_skills/manifest.json

@@ -14,11 +14,11 @@
     },
     {
       "path": "skills/deep-research/references/gigacode-workflow.md",
-      "sha256": "097807156d55a29d12b16a3a5d496a41fb07f152476e95e390699dec1842bc6a"
+      "sha256": "dbbe41f577bd96e2d6658f353b2cffd1e7971fbba255b803f781e86c3a6d5f1b"
     },
     {
       "path": "skills/deep-research/scripts/deep-research.workflow",
-      "sha256": "5207a175f1f1b4144d1c1e53c66e351c20006444e9d31abc7ce3f9be9204df3c"
+      "sha256": "3928a54b360fbee4a942f2b0172ad7607a7350500f9ea5ad413a9c2dcbce2ed7"
     },
     {
       "path": "skills/deep-research/scripts/materialize_report.py",
@@ -138,7 +138,7 @@
     },
     {
       "path": "skills/pptx/references/operations.md",
-      "sha256": "ef0a0f508b562d65d16624cf126075c33924a156b71efbe4cc0ff995a1be87d1"
+      "sha256": "7e65b53b63b25d6c0a84598946fcbf98c341f2d32ce356801a011ffa408b01bf"
     },
     {
       "path": "skills/pptx/requirements.txt",
@@ -146,11 +146,11 @@
     },
     {
       "path": "skills/pptx/scripts/pptx_tool.py",
-      "sha256": "b67bf31e00ea81904b89b2dc3a48dc346e0a940f99cd86c9c042a81d8b331465"
+      "sha256": "71a90eb26a581e0d7f06e5b1765b4ab26cc494085d2b8ed4a8ec219a3282799e"
     },
     {
       "path": "skills/pptx/scripts/smoke_test.py",
-      "sha256": "200d9d5f1ffdaa8497c589877f0941d8cf79a94743ddb737952e0aeab5179ba0"
+      "sha256": "6b52cc0be763dcf3b7d1ab5e4418f56549d858cc6415fce041b1692d078bc26d"
     },
     {
       "path": "skills/review/SKILL.md",
@@ -217,8 +217,8 @@
     "xlsx"
   ],
   "source": {
-    "commit": "c0ba68e7aee0994318913aa9fcaad4f57cbc11d7",
+    "commit": "2de7491964d92e3dc78f13290d875c800ac6e22d",
     "repository": "https://github.com/kolega-ai/kolega-skills",
-    "tag": "v0.3.0"
+    "tag": "v0.3.2"
   }
 }

{kolega_code-0.27.1 → kolega_code-0.28.1}/kolega_code/_bundled_skills/skills/deep-research/references/gigacode-workflow.md

@@ -192,7 +192,7 @@ The workflow derives every path deterministically:
 
 Scouts write their dossier with `exec_command` and return only a compact record
 plus `dossier_path`. Verification, coverage, drafting, and audit receive paths and
-read the depth they need with `read_file_section`. This is what keeps the
+read the depth they need with `read` (offset/limit for sections). This is what keeps the
 handoffs compact without starving later stages of evidence.
 
 The scratchpad is additive and best-effort. When `workspace` is omitted, a worker

{kolega_code-0.27.1 → kolega_code-0.28.1}/kolega_code/_bundled_skills/skills/deep-research/scripts/deep-research.workflow

@@ -1335,9 +1335,10 @@ WRITE_INSTRUCTIONS = (
 )
 
 READ_INSTRUCTIONS = (
-    "Read the referenced files with read_file_section (preferred) or read_entire_file "
-    "using the absolute paths given. If a file is missing or unreadable, continue from "
-    "the inline records below and note the degradation in your gaps."
+    "Read the referenced files with the read tool (using offset/limit for "
+    "sections) using the absolute paths given. If a file is missing or "
+    "unreadable, continue from the inline records below and note the "
+    "degradation in your gaps."
 )
 
 

{kolega_code-0.27.1 → kolega_code-0.28.1}/kolega_code/_bundled_skills/skills/pptx/references/operations.md

@@ -149,10 +149,12 @@ A create job has this top-level shape:
 }
 ```
 
-`template` is optional. Without one, `python-pptx`'s default presentation is used. With one, the
-template's masters and layouts are retained. Existing template slides are removed by default;
-set `keep_template_slides` to `true` to retain them. Template removal uses the same
-version-aware, reopen-verified relationship adapter as edit operations.
+`template` is optional. Without one, `python-pptx`'s 10 × 7.5-inch (4:3) default presentation is
+used. The schema does not resize a presentation; use a template with the required slide size
+before authoring absolute-inch geometry for another aspect ratio. With a template, its masters,
+layouts, and slide size are retained. Existing template slides are removed by default; set
+`keep_template_slides` to `true` to retain them. Template removal uses the same version-aware,
+reopen-verified relationship adapter as edit operations.
 
 A slide may select a `layout` with either `{"name": "Exact Layout Name"}` or `{"index": 1}`.
 If `layout` is omitted, layout index 1 is used and must exist. Duplicate layout names are
@@ -198,7 +200,9 @@ Supported actions:
 - `replace_image`: select one picture and provide `path`. The replacement must use the same media
   content type. Geometry/crop and unselected picture relationships remain unchanged; the selected
   picture receives a relationship to the validated replacement image.
-- `set_notes`: select a slide and provide plain `text`.
+- `set_notes`: select a slide and provide plain `text`. Written decks include and verify the
+  presentation-level notes-master owner reference required for PowerPoint and Keynote
+  interoperability.
 - `remove_slide`: select exactly one slide.
 - `reorder_slides`: provide `slide_ids` containing every current slide ID exactly once.
 
@@ -263,10 +267,13 @@ Elements:
 
 Chart types are `column`, `bar`, `line`, `line_markers`, `pie`, `doughnut`, `area`, `scatter`,
 and `scatter_lines`. Add `title` and `has_legend` as needed. Tables and charts remain editable.
-Notes are plain text only. Resource files are bounded and validated before use. Images are limited
-to 50 MiB compressed, 20,000 pixels per dimension, 50 million pixels, one frame, and an estimated
-200 MiB decoded raster. Each image path is read once into a bounded immutable byte snapshot;
-Pillow validation, full decode, and `python-pptx` ingestion all consume that same snapshot.
+Notes are plain text only. The tool repairs and validates the notes-master relationship graph that
+`python-pptx` 1.x can otherwise serialize without its presentation-level owner reference, which
+some consumers including Keynote reject. Resource files are bounded and validated before use.
+Images are limited to 50 MiB compressed, 20,000 pixels per dimension, 50 million pixels, one
+frame, and an estimated 200 MiB decoded raster. Each image path is read once into a bounded
+immutable byte snapshot; Pillow validation, full decode, and `python-pptx` ingestion all consume
+that same snapshot.
 
 ## LibreOffice prerequisite
 

{kolega_code-0.27.1 → kolega_code-0.28.1}/kolega_code/_bundled_skills/skills/pptx/scripts/pptx_tool.py

@@ -95,6 +95,7 @@ P_NS = "http://schemas.openxmlformats.org/presentationml/2006/main"
 A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main"
 R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
 NOTES_REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesSlide"
+NOTES_MASTER_REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesMaster"
 SLIDE_REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide"
 OFFICE_DOCUMENT_REL = (
     "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument"
@@ -814,6 +815,92 @@ class OoxmlAdapter:
         for slide_id in ordered_ids:
             slide_id_list.append(by_id[slide_id])
 
+    @classmethod
+    def ensure_notes_master_reference(cls, presentation: Any) -> None:
+        """Repair python-pptx's missing presentation-level notes-master owner reference."""
+
+        cls.require_supported_version()
+        relationships = [
+            (rel_id, relationship)
+            for rel_id, relationship in presentation.part.rels.items()
+            if relationship.reltype == NOTES_MASTER_REL
+        ]
+        root = presentation.part._element
+        master_lists = root.findall(f"{{{P_NS}}}notesMasterIdLst")
+        if not relationships:
+            if master_lists:
+                raise ToolError(
+                    "post_write_validation",
+                    "presentation has a notes-master owner reference without a relationship",
+                )
+            return
+        if len(relationships) != 1 or relationships[0][1].is_external:
+            raise ToolError(
+                "post_write_validation",
+                "presentation must contain exactly one internal notes-master relationship",
+                {"relationships": len(relationships)},
+            )
+        relationship_id = relationships[0][0]
+        if len(master_lists) > 1:
+            raise ToolError(
+                "post_write_validation",
+                "presentation contains duplicate notes-master owner-reference lists",
+            )
+        if master_lists:
+            master_ids = master_lists[0].findall(f"{{{P_NS}}}notesMasterId")
+            if (
+                len(master_ids) != 1
+                or len(master_lists[0]) != 1
+                or master_ids[0].get(f"{{{R_NS}}}id") != relationship_id
+            ):
+                raise ToolError(
+                    "post_write_validation",
+                    "presentation notes-master owner reference conflicts with its relationship",
+                    {"relationship": relationship_id},
+                )
+            return
+
+        master_list = etree.Element(f"{{{P_NS}}}notesMasterIdLst")
+        master_id = etree.SubElement(master_list, f"{{{P_NS}}}notesMasterId")
+        master_id.set(f"{{{R_NS}}}id", relationship_id)
+        children = list(root)
+        slide_master_tag = f"{{{P_NS}}}sldMasterIdLst"
+        successor_tags = {
+            f"{{{P_NS}}}handoutMasterIdLst",
+            f"{{{P_NS}}}sldIdLst",
+            f"{{{P_NS}}}sldSz",
+            f"{{{P_NS}}}notesSz",
+            f"{{{P_NS}}}smartTags",
+            f"{{{P_NS}}}embeddedFontLst",
+            f"{{{P_NS}}}custShowLst",
+            f"{{{P_NS}}}photoAlbum",
+            f"{{{P_NS}}}custDataLst",
+            f"{{{P_NS}}}kinsoku",
+            f"{{{P_NS}}}defaultTextStyle",
+            f"{{{P_NS}}}modifyVerifier",
+            f"{{{P_NS}}}extLst",
+        }
+        slide_master_indexes = [
+            index for index, child in enumerate(children) if child.tag == slide_master_tag
+        ]
+        if len(slide_master_indexes) > 1:
+            raise ToolError(
+                "post_write_validation",
+                "presentation contains duplicate slide-master ID lists",
+            )
+        insert_at = slide_master_indexes[0] + 1 if slide_master_indexes else 0
+        successor_indexes = [
+            index for index, child in enumerate(children) if child.tag in successor_tags
+        ]
+        if successor_indexes and min(successor_indexes) < insert_at:
+            raise ToolError(
+                "post_write_validation",
+                "presentation child order cannot accept a notes-master owner reference",
+            )
+        if not slide_master_indexes and successor_indexes:
+            insert_at = min(successor_indexes)
+        root.insert(insert_at, master_list)
+
     @classmethod
     def paragraph_has_field(cls, paragraph: Any) -> bool:
         cls.require_supported_version()
@@ -944,9 +1031,84 @@ def _open_presentation(path: Path, category: str = "bad_input") -> Any:
         raise ToolError(category, "python-pptx could not reopen the presentation") from exc
 
 
+def _validate_notes_master_reference(path: Path) -> None:
+    try:
+        with zipfile.ZipFile(path) as archive:
+            presentation = _safe_xml(archive.read(PRESENTATION_PART), PRESENTATION_PART)
+            relationships_root = _safe_xml(
+                archive.read(PRESENTATION_RELS),
+                PRESENTATION_RELS,
+            )
+    except (OSError, RuntimeError, zipfile.BadZipFile, KeyError) as exc:
+        raise ToolError(
+            "post_write_validation",
+            "written PPTX notes-master graph could not be inspected",
+        ) from exc
+
+    relationships = [
+        relationship
+        for relationship in relationships_root.findall(f"{{{REL_NS}}}Relationship")
+        if relationship.get("Type") == NOTES_MASTER_REL
+    ]
+    master_lists = presentation.findall(f"{{{P_NS}}}notesMasterIdLst")
+    if not relationships:
+        if master_lists:
+            raise ToolError(
+                "post_write_validation",
+                "written PPTX has a notes-master owner reference without a relationship",
+            )
+        return
+    if len(relationships) != 1 or relationships[0].get("TargetMode") == "External":
+        raise ToolError(
+            "post_write_validation",
+            "written PPTX must contain exactly one internal notes-master relationship",
+            {"relationships": len(relationships)},
+        )
+    if len(master_lists) != 1:
+        raise ToolError(
+            "post_write_validation",
+            "written PPTX is missing its notes-master owner reference",
+            {"owner_reference_lists": len(master_lists)},
+        )
+    master_ids = master_lists[0].findall(f"{{{P_NS}}}notesMasterId")
+    relationship_id = relationships[0].get("Id")
+    if (
+        len(master_ids) != 1
+        or len(master_lists[0]) != 1
+        or master_ids[0].get(f"{{{R_NS}}}id") != relationship_id
+    ):
+        raise ToolError(
+            "post_write_validation",
+            "written PPTX notes-master owner reference does not match its relationship",
+            {"relationship": relationship_id},
+        )
+
+    children = list(presentation)
+    notes_index = children.index(master_lists[0])
+    slide_master_indexes = [
+        index for index, child in enumerate(children) if child.tag == f"{{{P_NS}}}sldMasterIdLst"
+    ]
+    successor_indexes = [
+        index
+        for index, child in enumerate(children)
+        if child.tag in {f"{{{P_NS}}}handoutMasterIdLst", f"{{{P_NS}}}sldIdLst"}
+    ]
+    if (
+        slide_master_indexes
+        and notes_index <= max(slide_master_indexes)
+        or successor_indexes
+        and notes_index >= min(successor_indexes)
+    ):
+        raise ToolError(
+            "post_write_validation",
+            "written PPTX notes-master owner reference is in an invalid presentation order",
+        )
+
+
 def _validate_pptx_output(path: Path, expected_ids: list[int]) -> PackageReport:
     try:
         report = preflight_pptx(path)
+        _validate_notes_master_reference(path)
         reopened = _open_presentation(path, "post_write_validation")
     except ToolError as exc:
         if exc.category in {"bad_input", "resource_limit", "unsupported_operation"}:
@@ -979,6 +1141,7 @@ def _checkpoint_graph_mutation(
     if set(retained) != set(before_ids) & set(expected_ids):
         raise ToolError("post_write_validation", "retained slide ID calculation failed")
     path = checkpoint_dir / f"graph-{ordinal}.pptx"
+    OoxmlAdapter.ensure_notes_master_reference(presentation)
     try:
         presentation.save(str(path))
     except Exception as exc:
@@ -2341,6 +2504,7 @@ def _save_atomic_presentation(
     temporary = _temporary_sibling(destination, ".pptx")
     try:
         _enforce_presentation_limits(presentation)
+        OoxmlAdapter.ensure_notes_master_reference(presentation)
         try:
             presentation.save(str(temporary))
         except Exception as exc: