feat: add LibreOffice runtime probing and conversion helpers

- Introduced `libreoffice_runtime.py` to encapsulate functions for probing and converting documents using LibreOffice.
- Implemented functions to validate LibreOffice binaries, run conversions, and handle isolated runtime environments.
- Enhanced test suite to cover scenarios for detecting and handling unusable LibreOffice installations.
- Updated workspace bootstrap tests to rewrite LibreOffice runtime paths and validate conversion capabilities.

Author: JetXu-LLM

scripts/bootstrap-workspace.sh

@@ -347,42 +347,78 @@ workspace_runtime_ready() {
   [[ -x "$ROOT/.venv/bin/python" && -f "$ROOT/runtime/bootstrap_state.json" ]]
 }
 
-validated_soffice_binary() {
-  local candidate="$1"
-  local output_path=""
-  local probe_pid=""
-  local ticks=0
-
-  [[ -x "$candidate" ]] || return 1
-  output_path="$(mktemp "${TMPDIR:-/tmp}/docmason-soffice-version.XXXXXX")" || return 1
+probe_libreoffice_validation() {
+  local probe_python=""
+  local shell_line=""
+  local candidate=""
 
-  "$candidate" --version >"$output_path" 2>&1 &
-  probe_pid="$!"
-  while kill -0 "$probe_pid" >/dev/null 2>&1; do
-    if (( ticks >= 150 )); then
-      pkill -P "$probe_pid" >/dev/null 2>&1 || true
-      kill "$probe_pid" >/dev/null 2>&1 || true
-      sleep 0.1
-      pkill -P "$probe_pid" >/dev/null 2>&1 || true
-      kill -9 "$probe_pid" >/dev/null 2>&1 || true
-      wait "$probe_pid" >/dev/null 2>&1 || true
-      rm -f "$output_path"
-      return 1
-    fi
-    sleep 0.1
-    ticks=$((ticks + 1))
-  done
-  if ! wait "$probe_pid" >/dev/null 2>&1; then
-    rm -f "$output_path"
-    return 1
-  fi
-  if grep -qi "libreoffice" "$output_path"; then
-    rm -f "$output_path"
-    printf '%s\n' "$candidate"
+  LIBREOFFICE_BINARY=""
+  LIBREOFFICE_CANDIDATE_BINARY=""
+  LIBREOFFICE_VALIDATION_DETAIL=""
+  LIBREOFFICE_PROBE_CONTRACT=""
+  LIBREOFFICE_DETECTED_BUT_UNUSABLE="0"
+  LIBREOFFICE_VALIDATION_UNAVAILABLE="0"
+
+  probe_python="$(find_host_context_helper_python || true)"
+  if [[ -z "$probe_python" ]]; then
+    for candidate in \
+      "$(command -v soffice 2>/dev/null || true)" \
+      "$(command -v libreoffice 2>/dev/null || true)" \
+      "/Applications/LibreOffice.app/Contents/MacOS/soffice"
+    do
+      [[ -n "$candidate" ]] || continue
+      if [[ -e "$candidate" ]]; then
+        LIBREOFFICE_CANDIDATE_BINARY="$candidate"
+        LIBREOFFICE_VALIDATION_UNAVAILABLE="1"
+        break
+      fi
+    done
+    LIBREOFFICE_VALIDATION_DETAIL="No supported Python runtime was available to validate LibreOffice with the current smoke-probe contract."
     return 0
   fi
-  rm -f "$output_path"
-  return 1
+
+  while IFS= read -r shell_line; do
+    eval "$shell_line"
+  done < <(
+    ROOT="$ROOT" PYTHONPATH="$ROOT/src${PYTHONPATH:+:$PYTHONPATH}" "$probe_python" - <<'PY'
+import os
+import shlex
+import sys
+
+root = os.environ["ROOT"]
+sys.path.insert(0, os.path.join(root, "src"))
+
+payload = {
+    "ready": False,
+    "binary": None,
+    "detail": "",
+    "probe_contract": "",
+    "candidate_failures": [],
+}
+try:
+    from docmason.libreoffice_runtime import LIBREOFFICE_PROBE_CONTRACT, validate_soffice_binary
+
+    payload = validate_soffice_binary(None)
+    if not payload.get("probe_contract"):
+        payload["probe_contract"] = LIBREOFFICE_PROBE_CONTRACT
+except Exception as exc:  # pragma: no cover - launcher fallback path
+    payload["detail"] = f"LibreOffice validation probe failed: {exc}"
+
+
+def emit(name: str, value: object) -> None:
+    text = "" if value is None else str(value)
+    print(f"{name}={shlex.quote(text)}")
+
+
+binary = payload.get("binary")
+ready = bool(payload.get("ready"))
+emit("LIBREOFFICE_BINARY", binary if ready else "")
+emit("LIBREOFFICE_CANDIDATE_BINARY", binary or "")
+emit("LIBREOFFICE_VALIDATION_DETAIL", payload.get("detail") or "")
+emit("LIBREOFFICE_PROBE_CONTRACT", payload.get("probe_contract") or "")
+emit("LIBREOFFICE_DETECTED_BUT_UNUSABLE", "1" if (not ready and binary) else "0")
+PY
+  )
 }
 
 scan_office_renderer_requirement() {
@@ -411,16 +447,21 @@ scan_office_renderer_requirement() {
 
 probe_machine_baseline() {
   local platform_name=""
-  local soffice_binary=""
   local missing=()
-  local candidate=""
+  local baseline_gap_detail=""
 
   MACHINE_BASELINE_APPLICABLE=0
   MACHINE_BASELINE_READY=1
   MACHINE_BASELINE_STATUS="not-applicable"
   MACHINE_BASELINE_DETAIL="Native macOS machine-baseline policy is not active for this host surface."
+  MACHINE_BASELINE_HOST_ACCESS_REASON=""
   BREW_BINARY=""
   LIBREOFFICE_BINARY=""
+  LIBREOFFICE_CANDIDATE_BINARY=""
+  LIBREOFFICE_VALIDATION_DETAIL=""
+  LIBREOFFICE_PROBE_CONTRACT=""
+  LIBREOFFICE_DETECTED_BUT_UNUSABLE="0"
+  LIBREOFFICE_VALIDATION_UNAVAILABLE="0"
   OFFICE_RENDERER_REQUIRED=0
   MACHINE_BASELINE_MISSING_COMPONENTS=()
 
@@ -434,19 +475,16 @@ probe_machine_baseline() {
   if command -v brew >/dev/null 2>&1; then
     BREW_BINARY="$(command -v brew)"
   fi
-  for candidate in \
-    "$(command -v soffice 2>/dev/null || true)" \
-    "$(command -v libreoffice 2>/dev/null || true)" \
-    "/Applications/LibreOffice.app/Contents/MacOS/soffice"
-  do
-    [[ -n "$candidate" ]] || continue
-    soffice_binary="$(validated_soffice_binary "$candidate" || true)"
-    [[ -n "$soffice_binary" ]] && break
-  done
-  LIBREOFFICE_BINARY="$soffice_binary"
+  probe_libreoffice_validation
 
   if [[ "$OFFICE_RENDERER_REQUIRED" == "1" && -z "$LIBREOFFICE_BINARY" ]]; then
-    missing+=("LibreOffice")
+    if [[ "$LIBREOFFICE_VALIDATION_UNAVAILABLE" == "1" ]]; then
+      missing+=("LibreOffice")
+    elif [[ "$LIBREOFFICE_DETECTED_BUT_UNUSABLE" == "1" ]]; then
+      missing+=("LibreOffice (detected but unusable)")
+    else
+      missing+=("LibreOffice")
+    fi
   fi
 
   if (( ${#missing[@]} == 0 )); then
@@ -464,15 +502,39 @@ probe_machine_baseline() {
 
   MACHINE_BASELINE_READY=0
   MACHINE_BASELINE_MISSING_COMPONENTS=("${missing[@]}")
+  if [[ "$LIBREOFFICE_VALIDATION_UNAVAILABLE" == "1" ]]; then
+    baseline_gap_detail="Native Codex machine baseline detected LibreOffice"
+    if [[ -n "$LIBREOFFICE_CANDIDATE_BINARY" ]]; then
+      baseline_gap_detail="$baseline_gap_detail at \`$LIBREOFFICE_CANDIDATE_BINARY\`"
+    fi
+    baseline_gap_detail="$baseline_gap_detail, but the current bootstrap path cannot execute the required smoke probe yet because no supported helper Python or bootstrap runtime is available."
+    if [[ -n "$LIBREOFFICE_VALIDATION_DETAIL" ]]; then
+      baseline_gap_detail="$baseline_gap_detail Validation detail: $LIBREOFFICE_VALIDATION_DETAIL"
+    fi
+    MACHINE_BASELINE_HOST_ACCESS_REASON="Native Codex machine baseline cannot yet validate LibreOffice for the current Office corpus because no supported helper Python or bootstrap runtime is available."
+  elif [[ "$LIBREOFFICE_DETECTED_BUT_UNUSABLE" == "1" ]]; then
+    baseline_gap_detail="Native Codex machine baseline detected LibreOffice"
+    if [[ -n "$LIBREOFFICE_CANDIDATE_BINARY" ]]; then
+      baseline_gap_detail="$baseline_gap_detail at \`$LIBREOFFICE_CANDIDATE_BINARY\`"
+    fi
+    baseline_gap_detail="$baseline_gap_detail, but it is not currently usable for the current Office corpus."
+    if [[ -n "$LIBREOFFICE_VALIDATION_DETAIL" ]]; then
+      baseline_gap_detail="$baseline_gap_detail Validation detail: $LIBREOFFICE_VALIDATION_DETAIL"
+    fi
+    MACHINE_BASELINE_HOST_ACCESS_REASON="Native Codex machine baseline detected LibreOffice, but it is not currently usable for the current Office corpus and needs machine-level repair."
+  else
+    baseline_gap_detail="Native Codex machine baseline is missing ${missing[*]} for the current Office corpus."
+    MACHINE_BASELINE_HOST_ACCESS_REASON="Native Codex machine baseline is missing ${missing[*]} for the current Office corpus and needs machine-level installation."
+  fi
   if [[ "$FULL_MACHINE_ACCESS" == "true" ]]; then
     MACHINE_BASELINE_STATUS="install-required"
-    MACHINE_BASELINE_DETAIL="Native Codex machine baseline is missing ${missing[*]} for the current Office corpus."
+    MACHINE_BASELINE_DETAIL="$baseline_gap_detail"
   else
     MACHINE_BASELINE_STATUS="host-access-upgrade-required"
     if [[ "$PERMISSION_MODE" == "default-permissions" ]]; then
-      MACHINE_BASELINE_DETAIL="Native Codex machine baseline is missing ${missing[*]} for the current Office corpus, and the current thread is still in \`Default permissions\`."
+      MACHINE_BASELINE_DETAIL="$baseline_gap_detail The current thread is still in \`Default permissions\`."
     else
-      MACHINE_BASELINE_DETAIL="Native Codex machine baseline is missing ${missing[*]} for the current Office corpus, and the current turn does not expose \`Full access\` yet."
+      MACHINE_BASELINE_DETAIL="$baseline_gap_detail The current turn does not expose \`Full access\` yet."
     fi
   fi
 }
@@ -507,6 +569,20 @@ emit_host_access_upgrade() {
       printf 'false,\n'
     fi
     printf '  "machine_baseline_status": "%s",\n' "$(json_escape "$MACHINE_BASELINE_STATUS")"
+    printf '  "libreoffice_candidate_binary": '
+    json_string_or_null "$LIBREOFFICE_CANDIDATE_BINARY"
+    printf ',\n'
+    printf '  "libreoffice_validation_detail": '
+    json_string_or_null "$LIBREOFFICE_VALIDATION_DETAIL"
+    printf ',\n'
+    printf '  "libreoffice_probe_contract": '
+    json_string_or_null "$LIBREOFFICE_PROBE_CONTRACT"
+    printf ',\n'
+    if [[ "$LIBREOFFICE_DETECTED_BUT_UNUSABLE" == "1" ]]; then
+      printf '  "libreoffice_detected_but_unusable": true,\n'
+    else
+      printf '  "libreoffice_detected_but_unusable": false,\n'
+    fi
     printf '  "bootstrap_source": '
     json_string_or_null "$BOOTSTRAP_SOURCE"
     printf ',\n'
@@ -584,7 +660,7 @@ probe_machine_baseline
 HOST_ACCESS_REASONS=()
 if [[ "$MACHINE_BASELINE_APPLICABLE" == "1" && "$MACHINE_BASELINE_READY" != "1" && "$FULL_MACHINE_ACCESS" != "true" ]]; then
   HOST_ACCESS_REASONS+=(
-    "Native Codex machine baseline is missing ${MACHINE_BASELINE_MISSING_COMPONENTS[*]} and needs machine-level installation."
+    "${MACHINE_BASELINE_HOST_ACCESS_REASON:-Native Codex machine baseline is not ready and needs machine-level repair.}"
   )
 fi
 if [[ "$WORKSPACE_RUNTIME_READY" != "1" ]]; then

skills/canonical/knowledge-base-sync/SKILL.md

@@ -29,6 +29,7 @@ If the agent cannot run local commands or inspect the resulting artifacts, stop
    - if `sync_status=waiting-shared-job`, treat the existing shared sync job as the legal owner and wait or retry rather than starting a second path
    - if `sync_status=action-required`, surface the blocker directly
      - when the blocker is missing sync capability, route the operator to `prepare`
+     - when the blocker is a repairable Office machine-baseline gap and the host can provide `Full access`, continue through `docmason prepare --yes --json` and then resume the same sync task instead of stopping at a passive blocker report
 4. Treat successful `sync` as the deterministic truth-building path.
    - detect source changes
    - rebuild or reuse staged evidence
@@ -54,7 +55,7 @@ If the agent cannot run local commands or inspect the resulting artifacts, stop
 ## Escalation Rules
 
 - Do not invent a second approval surface. The public approval command is `docmason sync --yes`.
-- If Office rendering is required but unavailable, stop and return the concrete install step.
+- If Office rendering is required but unavailable, stop only when the governed `prepare` path still cannot repair or install LibreOffice honestly; otherwise continue through that repair path first.
 - If staged or hybrid follow-up work requires per-source editing, that bounded work may be parallelized, but the final rerun and final judgment remain on the main path.
 - Do not silently trigger this workflow from an ordinary answer path without surfacing the governed state transition.
 

skills/canonical/workspace-bootstrap/SKILL.md

@@ -42,10 +42,11 @@ If the agent cannot perform these capabilities, stop and explain that the enviro
 5. Run `docmason prepare --json --yes` when the launcher was not used, or when bootstrap needs an explicit rerun to repair or complete the repo-local environment.
 6. If `prepare` reports a degraded result, follow the reported next steps and rerun only the necessary deterministic command.
 7. Use `docs/setup/manual-workspace-recovery.md` only when the launcher or `prepare` still cannot finish honestly after the governed automatic path has already had enough access.
-8. If the corpus already contains PPTX, DOCX, or XLSX files and LibreOffice is missing:
+8. If the corpus already contains PPTX, DOCX, or XLSX files and LibreOffice is missing or detected but unusable:
    - LibreOffice is required only for an Office-rendering corpus; it is not a universal machine baseline dependency
    - on macOS with Homebrew already present, DocMason may use `brew install --cask libreoffice-still`
    - on macOS without Homebrew, DocMason should use the official LibreOffice installer path instead of trying to install Homebrew first
+   - on macOS, if LibreOffice is already detected but fails the governed smoke probe, `prepare --yes` should treat that as a repair or reinstall case rather than as a fake ready state
    - on Linux, install LibreOffice with the distro package manager or the official packages, then ensure `soffice` is on `PATH`
 9. Run `docmason status --json` when you need to confirm the resulting workspace stage.
 10. Recommend `docmason sync --json` when source files are present and the user needs a usable knowledge base next.
@@ -59,7 +60,7 @@ If the agent cannot perform these capabilities, stop and explain that the enviro
 - If the platform or Python version is unsupported, stop and surface that blocker directly.
 - If `prepare` can only proceed through a higher-intrusion install step, explain it explicitly rather than hiding it inside automation.
 - If system-level installation requires additional permissions, request them when the current platform supports that flow; otherwise give the user the exact command or GUI step to run.
-- On native Codex/macOS, if the thread is still in `Default permissions` and higher access is required for downloads or machine-level setup, stop once with an explicit `Full access` upgrade instruction. Do not keep asking lower-level machine-inspection questions.
+- On native Codex/macOS, if the thread is still in `Default permissions` and higher access is required for downloads or machine-level setup, stop once with an explicit `Full access` upgrade instruction. After `Full access` is available, continue through the governed automatic repair or reinstall path instead of stopping at diagnosis alone.
 - For Claude Code or another compatibility host, keep the fallback wording short and host-generic; do not expand it into a second native bootstrap story.
 - Deterministic shell setup steps may run as background or main-agent commands, but the final environment judgment returns to the main agent.
 
@@ -72,6 +73,7 @@ If the agent cannot perform these capabilities, stop and explain that the enviro
 - `prepare` bootstraps repo-local state only.
 - `./scripts/bootstrap-workspace.sh --yes` is the preferred zero-to-working launcher from a raw checkout because it can prepare `.venv` before the package is importable from the `src/` layout.
 - The launcher now performs governed preflight first, then probes bootstrap-Python liveness in bounded time and prefers repo-local candidates before shared ones.
+- The launcher and `prepare` now trust real LibreOffice smoke conversion, not only `soffice --version`, before declaring an Office-rendering machine baseline ready.
 - `runtime/bootstrap_state.json` is the cached ready marker that ordinary ask-time work should reuse.
 - The steady-state runtime is repo-local managed Python `3.13` under `.docmason/toolchain/python/`.
 - On the native Codex path, bootstrap should refresh repo-local skill shims under `.agents/skills/` rather than writing into `~/.codex/skills`.