python-hwpx-automation 7.0.4__tar.gz → 7.1.0__tar.gz

{python_hwpx_automation-7.0.4/src/python_hwpx_automation.egg-info → python_hwpx_automation-7.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx-automation
-Version: 7.0.4
+Version: 7.1.0
 Summary: Task-oriented HWPX document automation for Python, with an optional MCP adapter.
 Author: Kohkyuhyun
 License-Expression: Apache-2.0
@@ -20,7 +20,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: python-hwpx<7,>=6.3.0
+Requires-Dist: python-hwpx<7,>=6.4.0
 Requires-Dist: pydantic<3,>=2.11
 Requires-Dist: cryptography>=42.0
 Requires-Dist: anyio>=4.0
@@ -74,10 +74,9 @@ Dynamic: license-file
 
 <!-- release-state: release-approved -->
 > [!NOTE]
-> 아직 공개되지 않은 7.0.4 후보입니다.
-> 후보 조합: `python-hwpx 6.3.0 → python-hwpx-automation 7.0.4 → hwpx-plugin 2.1.0`.
-> 공개 트레인: `python-hwpx 6.3.0 → python-hwpx-automation 7.0.3 → hwpx-plugin 2.0.3`.
-> 계약은 `8c278ebd5becba08`이며 도구 표면과 최소 호환 버전은 유지합니다.
+> 이 소스는 발행 승인된(release-approved) 7.1.0 후보입니다. 원격 발행과 실제 설치 관찰 전까지 공개 좌표는 유지합니다.
+> 후보: `python-hwpx 6.4.0 → python-hwpx-automation 7.1.0 → hwpx-plugin 2.2.0` (`ba0211fc854a0a97`).
+> 공개 트레인: `python-hwpx 6.3.0 → python-hwpx-automation 7.0.4 → hwpx-plugin 2.1.0` (`8c278ebd5becba08`).
 > 공개 좌표는 core·automation PyPI와 plugin GitHub
 > Release·marketplace·실제 marketplace 설치 관찰 후에만 승격합니다.
 > [릴리스 runbook](docs/release-runbook.md)
@@ -134,7 +133,7 @@ Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MC
       "command": "uvx",
       "args": [
         "--from",
-        "python-hwpx-automation[mcp]==7.0.3",
+        "python-hwpx-automation[mcp]==7.0.4",
         "hwpx-automation-mcp"
       ],
       "env": {
@@ -241,3 +240,5 @@ python scripts/run_conformance.py run \
 ## License · Maintainer
 
 Apache-2.0 ([LICENSE](LICENSE) · [NOTICE](NOTICE)) — **Kohkyuhyun** [@airmang](https://github.com/airmang) · [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)
+
+기존 문서 수정은 [조회·대상 확정·보존 저장·검증 안내](docs/existing-edit-navigation.md)를 먼저 확인하세요. 새 문서는 document-plan, 에이전트 연결은 선택 MCP와 호스트 플러그인을 사용합니다.

{python_hwpx_automation-7.0.4 → python_hwpx_automation-7.1.0}/README.md

@@ -14,10 +14,9 @@
 
 <!-- release-state: release-approved -->
 > [!NOTE]
-> 아직 공개되지 않은 7.0.4 후보입니다.
-> 후보 조합: `python-hwpx 6.3.0 → python-hwpx-automation 7.0.4 → hwpx-plugin 2.1.0`.
-> 공개 트레인: `python-hwpx 6.3.0 → python-hwpx-automation 7.0.3 → hwpx-plugin 2.0.3`.
-> 계약은 `8c278ebd5becba08`이며 도구 표면과 최소 호환 버전은 유지합니다.
+> 이 소스는 발행 승인된(release-approved) 7.1.0 후보입니다. 원격 발행과 실제 설치 관찰 전까지 공개 좌표는 유지합니다.
+> 후보: `python-hwpx 6.4.0 → python-hwpx-automation 7.1.0 → hwpx-plugin 2.2.0` (`ba0211fc854a0a97`).
+> 공개 트레인: `python-hwpx 6.3.0 → python-hwpx-automation 7.0.4 → hwpx-plugin 2.1.0` (`8c278ebd5becba08`).
 > 공개 좌표는 core·automation PyPI와 plugin GitHub
 > Release·marketplace·실제 marketplace 설치 관찰 후에만 승격합니다.
 > [릴리스 runbook](docs/release-runbook.md)
@@ -74,7 +73,7 @@ Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MC
       "command": "uvx",
       "args": [
         "--from",
-        "python-hwpx-automation[mcp]==7.0.3",
+        "python-hwpx-automation[mcp]==7.0.4",
         "hwpx-automation-mcp"
       ],
       "env": {
@@ -181,3 +180,5 @@ python scripts/run_conformance.py run \
 ## License · Maintainer
 
 Apache-2.0 ([LICENSE](LICENSE) · [NOTICE](NOTICE)) — **Kohkyuhyun** [@airmang](https://github.com/airmang) · [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)
+
+기존 문서 수정은 [조회·대상 확정·보존 저장·검증 안내](docs/existing-edit-navigation.md)를 먼저 확인하세요. 새 문서는 document-plan, 에이전트 연결은 선택 MCP와 호스트 플러그인을 사용합니다.

{python_hwpx_automation-7.0.4 → python_hwpx_automation-7.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx-automation"
-version = "7.0.4"
+version = "7.1.0"
 description = "Task-oriented HWPX document automation for Python, with an optional MCP adapter."
 readme = "README.md"
 authors = [{ name = "Kohkyuhyun" }]
@@ -31,7 +31,7 @@ dependencies = [
     # breaking an already-published automation line. WP-F (engine surface 6.0):
     # this line adapted to the new namespace surface (design §9 WP-F) — the dev0
     # pre-release qualifier tracks core's own not-yet-tagged 6.0 identity.
-    "python-hwpx>=6.3.0,<7", # HWPX object model, OXML/OPC, format-native primitives
+    "python-hwpx>=6.4.0,<7", # HWPX object model, OXML/OPC, format-native primitives
 
     "pydantic>=2.11,<3",
     "cryptography>=42.0",

{python_hwpx_automation-7.0.4 → python_hwpx_automation-7.1.0}/src/hwpx_automation/handlers/read_export.py

@@ -38,6 +38,7 @@ from ..upstream import (
     open_document,
 )
 from ..utils.helpers import default_max_chars, resolve_path, truncate_response
+from ..utils.read_budget import bound_document_summary
 from ._shared import _with_document_state
 
 _OUTPUT_MODES = {"full", "chunks"}
@@ -920,7 +921,8 @@ def get_document_map(
             "hwpx_extract_json",
         ],
     }
-    return _with_document_state(result, path)
+    result = _with_document_state(result, path)
+    return bound_document_summary(result) if summary_mode else result
 
 
 def hwpx_to_markdown(

{python_hwpx_automation-7.0.4 → python_hwpx_automation-7.1.0}/src/hwpx_automation/identity.json

@@ -5,22 +5,29 @@
   "releaseState": {
     "status": "release-approved",
     "candidate": {
-      "pythonHwpx": "6.3.0",
+      "pythonHwpx": "6.4.0",
       "canonicalDistribution": "python-hwpx-automation",
-      "canonicalAutomation": "7.0.4",
+      "canonicalAutomation": "7.1.0",
       "compatibilityDistribution": "hwpx-mcp-server",
-      "compatibility": "7.0.4",
-      "plugin": "2.1.0",
-      "contractHash": "8c278ebd5becba08"
+      "compatibility": "7.1.0",
+      "plugin": "2.2.0",
+      "contractHash": "ba0211fc854a0a97"
     },
     "currentPublic": {
       "pythonHwpx": "6.3.0",
       "primaryDistribution": "python-hwpx-automation",
-      "primaryApplication": "7.0.3",
-      "plugin": "2.0.3",
+      "primaryApplication": "7.0.4",
+      "plugin": "2.1.0",
       "contractHash": "8c278ebd5becba08"
     },
-    "promotionGate": "Three states are mandatory: unreleased-candidate while auditing; release-approved only after separate owner approval and while currentPublic still names the previously observed coherent stack; released only in a follow-up commit after remote truth is observed for core, canonical automation, the compatibility distribution, the plugin GitHub release, the marketplace entry, and a real marketplace install. The automation tag workflow publishes only release-approved, leaves currentPublic unchanged, and hands an attached receipt to plugin publication."
+    "promotionGate": "Three states are mandatory: unreleased-candidate while auditing; release-approved only after separate owner approval and while currentPublic still names the previously observed coherent stack; released only in a follow-up commit after remote truth is observed for core, canonical automation, the compatibility distribution, the plugin GitHub release, the marketplace entry, and a real marketplace install. The automation tag workflow publishes only release-approved, leaves currentPublic unchanged, and hands an attached receipt to plugin publication.",
+    "previousPublic": {
+      "pythonHwpx": "6.3.0",
+      "primaryDistribution": "python-hwpx-automation",
+      "primaryApplication": "7.0.4",
+      "plugin": "2.1.0",
+      "contractHash": "8c278ebd5becba08"
+    }
   },
   "releaseFloors": {
     "description": "Frozen historical coordinates. Unlike releaseState these do not advance train by train; they pin the pre-6.0 legacy compatibility cap that every core 5 resolution must be observed against. They live here so the release path has no version literal that is not declared data.",

{python_hwpx_automation-7.0.4 → python_hwpx_automation-7.1.0}/src/hwpx_automation/office/agent/cli.py

@@ -23,6 +23,10 @@ from .blueprint import (
 )
 from .commands import apply_document_commands
 from .document import HwpxAgentDocument
+from .form_plan import (
+    MIXED_FORM_PLAN_SCHEMA, MIXED_FORM_COMPILED_PLAN_SCHEMA,
+    apply_mixed_form_fill, apply_mixed_form_plan,
+)
 from .model import (
     AGENT_BATCH_SCHEMA,
     AgentBatchResult,
@@ -536,6 +540,15 @@ def _run_replay(args: argparse.Namespace, *, stdin: TextIO, stdout: TextIO) -> i
     return _exit_code(result.error)
 
 
+def _apply_batch_request(request: Mapping[str, Any], store: dict[str, Any]) -> AgentBatchResult:
+    schema = request.get("schemaVersion")
+    if schema == MIXED_FORM_PLAN_SCHEMA:
+        return apply_mixed_form_fill(request, idempotency_store=store)
+    if schema == MIXED_FORM_COMPILED_PLAN_SCHEMA:
+        return apply_mixed_form_plan(request, idempotency_store=store)
+    return apply_document_commands(request, idempotency_store=store)
+
+
 def _run_mutation(
     args: argparse.Namespace,
     *,
@@ -550,7 +563,7 @@ def _run_mutation(
     exit_code = EXIT_OK
     results: list[AgentBatchResult] = []
     for request in requests:
-        result = apply_document_commands(request, idempotency_store=store)
+        result = _apply_batch_request(request, store)
         results.append(result)
         exit_code = max(exit_code, _exit_code(result.error))
     if args.output_format == "human":

{python_hwpx_automation-7.0.4 → python_hwpx_automation-7.1.0}/src/hwpx_automation/office/agent/document.py

@@ -21,7 +21,7 @@ from .model import (
     AgentNode,
     NODE_PROPERTY_CATALOG_V1,
 )
-from .path import SemanticPath, canonicalize_path, identified_segment, indexed_segment
+from .path import SemanticPath, canonicalize_path, identified_segment, indexed_segment, parse_path
 from .query import QueryRecord as _QueryRecord
 from .query import QueryResult, evaluate_selector, parse_selector
 from .story import (
@@ -804,9 +804,37 @@ class HwpxAgentDocument:
                 f"childLimit must be 1..{MAX_CHILDREN_PER_NODE}",
                 target="childLimit",
             )
-        record = self.resolve_record(path, expected_revision=expected_revision)
+        try:
+            record = self.resolve_record(path, expected_revision=expected_revision)
+        except AgentContractError as exc:
+            if exc.code != "not_found":
+                raise
+            record = self._resolve_indexed_read_path(path, expected_revision)
         return self._public_node(record, depth=depth, child_limit=child_limit)
 
+    def _resolve_indexed_read_path(self, path: str, revision: str | None) -> NodeRecord:
+        """Navigate omitted children; return a canonical path for subsequent edits.
+
+        Only get() calls this helper. Commands continue to require the exact
+        canonical path, so a navigation alias never silently retargets a write.
+        """
+        record = self._records["/"]
+        for segment in parse_path(path).segments:
+            direct = record.path.rstrip("/") + "/" + segment.canonical()
+            if direct in record.child_paths:
+                record = self.resolve_record(direct, expected_revision=revision)
+                continue
+            children = [self._records[p] for p in record.child_paths
+                        if self._records[p].kind == segment.kind]
+            if segment.index is None or segment.index > len(children):
+                raise AgentContractError("not_found", "indexed read target not found", target=path)
+            if revision is None:
+                raise AgentContractError(
+                    "volatile_target", "indexed navigation requires the current revision", target=path
+                )
+            record = self.resolve_record(children[segment.index - 1].path, expected_revision=revision)
+        return record
+
     def query(
         self,
         selector: str,

{python_hwpx_automation-7.0.4 → python_hwpx_automation-7.1.0}/src/hwpx_automation/office/rendering/_render_hwpx_mac.applescript

@@ -30,6 +30,10 @@ property closeDocPrefix : "문서 닫기"
 
 on run argv
 	if (count of argv) < 2 then return "ERR: usage: <input.hwpx> <out.pdf> [timeoutSecs]"
+	if item 1 of argv is "--close-owned" then
+		closeOwnedDocument(item 2 of argv)
+		return "CLEANUP"
+	end if
 	set inputPath to item 1 of argv
 	set outPdf to item 2 of argv
 	set timeoutSecs to 90
@@ -41,6 +45,18 @@ on run argv
 
 	set inputBase to do shell script "basename " & quoted form of inputPath
 
+	if listContains(windowNames(), inputBase) then return "ERR: staged document already open"
+	if listContains(windowNames(), pdfDialogTitle) then return "ERR: existing PDF dialog"
+	-- Do not drive menus while another document owns a modal sheet.
+	tell application "System Events"
+		if exists process procName then
+			tell process procName
+				repeat with w in windows
+					if (count of sheets of w) > 0 then return "ERR: existing modal sheet"
+				end repeat
+			end tell
+		end if
+	end tell
 	try
 		-- 1) Open the staged input. LaunchServices focuses Hancom (launching it
 		--    if needed) and opens the document.
@@ -61,7 +77,7 @@ on run argv
 
 		-- 4) Wait for the export dialog.
 		if not (waitForWindowNamed(pdfDialogTitle, 30)) then
-			return "ERR: PDF save dialog did not appear"
+			error "PDF save dialog did not appear"
 		end if
 		delay 1.0
 
@@ -94,19 +110,14 @@ on run argv
 		-- 8) Always close the document so the next render starts from a clean
 		--    session, even if the wait above was noisy. Discard any save-changes
 		--    prompt (we only exported; the doc content is unmodified).
-		try
-			clickFileMenuItemByPrefix(closeDocPrefix)
-			dismissCloseSheetIfPresent()
-		end try
+		set closed to closeOwnedDocument(inputBase)
+		if not closed then return "ERR: owned document cleanup incomplete"
 
 		if not wrote then return "ERR: PDF not written to " & outPdf
 		return "OK"
 	on error errMsg number errNum
 		-- Best-effort cleanup so a mid-flow error doesn't leak an open document.
-		try
-			clickFileMenuItemByPrefix(closeDocPrefix)
-			dismissCloseSheetIfPresent()
-		end try
+		closeOwnedDocument(inputBase)
 		return "ERR: " & errMsg & " (" & errNum & ")"
 	end try
 end run
@@ -221,29 +232,30 @@ on dismissOverwriteSheetIfPresent()
 	return false
 end dismissOverwriteSheetIfPresent
 
--- If closing surfaces a save-changes sheet, discard (저장 안 함 / 안 함). We only
--- exported a PDF, so the document content is unchanged.
-on dismissCloseSheetIfPresent()
-	repeat 6 times
-		set handled to false
-		try
-			tell application "System Events" to tell process procName
-				repeat with wn in windowNames()
-					set w to (first window whose name is (wn as string))
-					if (count of sheets of w) > 0 then
-						repeat with b in buttons of (sheet 1 of w)
-							set bn to (name of b as string)
-							if bn contains "안 함" or bn contains "안함" then
-								click b
-								set handled to true
-							end if
-						end repeat
-					end if
-				end repeat
-			end tell
-		end try
-		if handled then return true
-		delay 0.3
-	end repeat
-	return false
-end dismissCloseSheetIfPresent
+-- Never discard a sheet belonging to any other document. If ownership cannot
+-- be proved, leave the GUI for the user and report failure rather than kill it.
+on closeOwnedDocument(winName)
+    if not listContains(windowNames(), winName) then return false
+    if listContains(windowNames(), pdfDialogTitle) then return false
+    try
+        raiseWindowNamed(winName)
+        tell application "System Events" to tell process procName
+            if name of front window is not winName then return false
+        end tell
+        clickFileMenuItemByPrefix(closeDocPrefix)
+        tell application "System Events" to tell process procName
+            if exists (first window whose name is winName) then
+                set owned to (first window whose name is winName)
+                if (count of sheets of owned) > 0 then
+                    repeat with b in buttons of sheet 1 of owned
+                        set bn to name of b as string
+                        if bn contains "안 함" or bn contains "안함" then click b
+                    end repeat
+                end if
+            end if
+        end tell
+        return waitForWindowGone(winName, 2)
+    on error
+        return false
+    end try
+end closeOwnedDocument

python_hwpx_automation-7.1.0/src/hwpx_automation/office/rendering/mac_session.py

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Owned, cancellable Mac GUI adapter for the existing serialized worker."""
+from __future__ import annotations
+
+import os
+import plistlib
+import subprocess
+import tempfile
+import threading
+from pathlib import Path
+
+from .oracle import MacHancomOracle
+
+
+class _OwnedMacOracle(MacHancomOracle):
+    def __init__(self, *, timeout: float) -> None:
+        super().__init__(timeout=timeout, budget_seconds=timeout)
+        self.guard = threading.Lock()
+        self.process: subprocess.Popen[str] | None = None
+        self.cancelled = threading.Event()
+
+    def _run_render_script(self, cmd: list[str], timeout: float) -> subprocess.CompletedProcess[str]:
+        with self.guard:
+            if self.cancelled.is_set():
+                raise OSError("render cancelled before launch")
+            process = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+            self.process = process
+        try:
+            try:
+                stdout, stderr = process.communicate(timeout=timeout)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.communicate()
+                raise
+            if self.cancelled.is_set():
+                raise OSError("render cancelled")
+            return subprocess.CompletedProcess(cmd, process.returncode, stdout, stderr)
+        finally:
+            with self.guard:
+                self.process = None
+
+    def abort(self) -> None:
+        self.cancelled.set()
+        with self.guard:
+            if self.process is not None and self.process.poll() is None:
+                self.process.kill()  # our osascript only; never the user's app
+
+
+class MacHancomSession:
+    real_hancom = True
+    backend = "mac-gui-worker"
+
+    def __init__(self, *, timeout_seconds: float = 120) -> None:
+        self.oracle = _OwnedMacOracle(timeout=timeout_seconds)
+        app = self.oracle._app_path()
+        if app is None or not self.oracle.available():
+            raise RuntimeError("MAC_HANCOM_UNAVAILABLE")
+        with (Path(app) / "Contents/Info.plist").open("rb") as handle:
+            info = plistlib.load(handle)
+        version, build = info.get("CFBundleShortVersionString"), info.get("CFBundleVersion")
+        if not version or not build:
+            raise RuntimeError("MAC_HANCOM_BUILD_UNKNOWN")
+        self.hancom_build = f"{version} ({build})"
+
+    def render_pdf(self, source: Path, target: Path) -> Path | None:
+        from hwpx_automation.workflow.render_queue import inspect_hwpx
+        inspect_hwpx(source.read_bytes(), filename=source.name, principal_id="local-worker")
+        # The Mac desktop is shared even across worker roots/processes. flock
+        # lives until the rendering/owned cleanup exits, including watchdogs.
+        import fcntl
+        lock = Path(tempfile.gettempdir()) / f"hwpx-hancom-gui-{os.getuid()}.lock"
+        with lock.open("a") as handle:
+            try:
+                fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError:
+                raise RuntimeError("MAC_GUI_BUSY") from None
+            try:
+                result = self.oracle.render_pdf(str(source), str(target))
+                return Path(result) if result else None
+            finally:
+                fcntl.flock(handle, fcntl.LOCK_UN)
+
+    def abort(self) -> None:
+        self.oracle.abort()
+
+    def close(self) -> None:
+        self.abort()

{python_hwpx_automation-7.0.4 → python_hwpx_automation-7.1.0}/src/hwpx_automation/office/rendering/oracle.py

@@ -500,11 +500,10 @@ class MacHancomOracle(RenderBackend):
         open <input> → 파일 (File) > "PDF로 저장하기..." → NSSavePanel (Return = 저장)
         → 파일 > "문서 닫기"
 
-    The save panel is *document-relative* (it pre-fills 위치 = the input's
-    directory and the name field = the input's stem), so :meth:`render_pdf`
-    stages the input as ``<out_dir>/<out_stem>.hwpx`` and the panel writes exactly
-    ``<out_dir>/<out_stem>.pdf`` with no path typing. The target is pre-deleted so
-    no overwrite sheet appears.
+    The save panel is document-relative. Each render stages a uniquely named
+    copy in a private temporary directory, exports beside it, closes only that
+    owned document, then promotes a complete PDF to the caller's output path.
+    Existing caller files survive a failed render.
 
     Operational notes: the GUI is a single shared session, so renders MUST be
     serialized (the default serial :meth:`render_many` does this). Requires a
@@ -599,57 +598,49 @@ class MacHancomOracle(RenderBackend):
         src = os.path.abspath(hwpx_path)
         out_pdf = os.path.abspath(out_pdf)
         out_dir = os.path.dirname(out_pdf)
-        out_stem = os.path.splitext(os.path.basename(out_pdf))[0]
         os.makedirs(out_dir, exist_ok=True)
 
-        # Stage the input next to the target, named as the target stem, so the
-        # document-relative save panel needs no typing (see class docstring).
-        staged = os.path.join(out_dir, out_stem + ".hwpx")
-        staged_is_source = os.path.abspath(staged) == src
-
-        try:  # pre-delete target -> the overwrite ("대치?") sheet never appears
-            if os.path.exists(out_pdf):
-                os.remove(out_pdf)
-        except OSError:
-            pass
-
         deadline = _deadline_from(self.budget_seconds)
         run_timeout = _clamped_timeout(self.timeout + 60.0, deadline)
         if run_timeout is None:
             return None
-        # The AppleScript receives its own internal wait limit; keep it inside
-        # the clamped subprocess timeout so the script never outlives the budget.
         script_timeout = max(1, int(min(self.timeout, run_timeout)))
-
-        cleanup_staged = False
-        try:
-            if not staged_is_source:
-                shutil.copyfile(src, staged)
-                cleanup_staged = True
+        # Unique owned document name: a prior render or user document can never
+        # be mistaken for this job. Never pre-delete or stage over caller files.
+        with tempfile.TemporaryDirectory(prefix="hwpx-render-", dir=out_dir) as folder:
+            name = Path(folder).name
+            staged = Path(folder) / (name + ".hwpx")
+            staged_pdf = staged.with_suffix(".pdf")
+            shutil.copyfile(src, staged)
             with resources.as_file(
-                resources.files("hwpx_automation.office.rendering").joinpath(
-                    _MAC_BACKEND_SCRIPT
-                )
+                resources.files("hwpx_automation.office.rendering").joinpath(_MAC_BACKEND_SCRIPT)
             ) as script:
-                cmd = [
-                    self._osascript, str(script), staged, out_pdf, str(script_timeout),
-                ]
+                cmd = [self._osascript, str(script), str(staged), str(staged_pdf), str(script_timeout)]
                 try:
-                    subprocess.run(
-                        cmd, capture_output=True, text=True,
-                        timeout=run_timeout, check=False,
-                    )
+                    proc = self._run_render_script(cmd, run_timeout)
                 except (subprocess.TimeoutExpired, OSError):
+                    # Best-effort cleanup is restricted to our uniquely named
+                    # document. The worker adapter also handles cancellation.
+                    self._close_owned_document(script, staged.name)
                     return None
-            if os.path.exists(out_pdf) and os.path.getsize(out_pdf) > 0:
+            if proc.returncode != 0 or (proc.stdout or "").strip() != "OK":
+                return None
+            if staged_pdf.is_file() and staged_pdf.read_bytes().rstrip().endswith(b"%%EOF"):
+                os.replace(staged_pdf, out_pdf)
                 return out_pdf
             return None
-        finally:
-            if cleanup_staged:
-                try:
-                    os.remove(staged)
-                except OSError:
-                    pass
+
+    def _run_render_script(self, cmd: list[str], timeout: float) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, check=False)
+
+    def _close_owned_document(self, script: Path, name: str) -> None:
+        try:
+            subprocess.run(
+                [self._osascript, str(script), "--close-owned", name],
+                capture_output=True, text=True, timeout=3, check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            pass
 
     def refresh_document(self, hwpx_path: str) -> bool:
         """Open ``hwpx_path``, let dirty fields regenerate, save in place, close.