Add doctor/preflight diagnostics and harden file ops

Author: kroxiksut

AGENTS.MD

@@ -49,3 +49,4 @@ Implement:
 * Config file support
 * Logging
 * Dry-run mode
+* Doctor/preflight diagnostics mode before sync

AI_CONTEXT.MD

@@ -27,6 +27,7 @@ ALLOW DEVELOPERS TO CONTINUE WORK ON A SECOND MACHINE WITHOUT LOSING CODEX LOCAL
 
 ## RUN MODES
 - DIRECT RUN: MANUAL (`PYTHON ...` OR PACKAGED BINARY).
+- DIAGNOSTIC RUN: `DOCTOR`/`PREFLIGHT` TO VALIDATE ENVIRONMENT READINESS BEFORE SYNC.
 - SCHEDULED RUN:
   - WINDOWS: TASK SCHEDULER.
   - MACOS: `LAUNCHD` (LAUNCHAGENT) OR EQUIVALENT SCHEDULED JOB.
@@ -53,6 +54,13 @@ ALLOW DEVELOPERS TO CONTINUE WORK ON A SECOND MACHINE WITHOUT LOSING CODEX LOCAL
   - FORMATS: `TEXT|JSON|LOGFMT` (CONFIGURABLE).
   - ROTATION: RETENTION-BASED, DEFAULT `7` DAYS.
 - FILE-TIME NORMALIZATION: NO DEDICATED NORMALIZATION/CLOCK COMPENSATION IN MVP; RELY ON OS/FILESYSTEM TIMESTAMPS.
+- PREFLIGHT/DOCTOR CHECKS:
+  - CONFIG + RUNTIME PATH READINESS.
+  - WRITE ACCESS PROBES FOR LOCAL/CLOUD/BACKUP/TEMP ROOTS.
+  - CODEX PROCESS SAFETY PRECONDITION.
+  - MANIFEST DATA-VERSION COMPATIBILITY.
+  - SUSPICIOUS LOCAL/CLOUD PROBE MTIME DRIFT (WARNING SIGNAL).
+  - ORPHAN TEMP FILE DETECTION.
 - CLI EXIT CODES (FOR CI/AUTOMATION):
   - `0` SUCCESS (INCLUDING NO-OP).
   - `1` RUNTIME ERROR.

AI_RULES.MD

@@ -41,6 +41,7 @@
 - CONFIGURATION FILE SUPPORT.
 - DETAILED LOGGING.
 - `--DRY-RUN` MODE.
+- `DOCTOR`/`PREFLIGHT` MODE THAT CHECKS RUNTIME READINESS BEFORE SYNC.
 - SCHEDULED MODE:
   - WINDOWS TASK SCHEDULER.
   - MACOS LAUNCHAGENT (`LAUNCHD`).
@@ -65,6 +66,11 @@
 - `4` CONFIG/ARGS ERROR (INVALID CONFIG OR CLI PARAMETERS).
 - `5` SAFE ABORT (FAIL-SAFE STOP).
 
+`DOCTOR`/`PREFLIGHT` MUST:
+- REPORT CHECK RESULTS (`PASS|WARN|FAIL`) WITH CLEAR DETAILS.
+- RETURN `0` WHEN ONLY `PASS/WARN` ARE PRESENT.
+- RETURN `5` WHEN AT LEAST ONE `FAIL` IS PRESENT.
+
 ## 8. MINIMUM MVP TEST SET
 - UNIT TESTS FOR EXCLUSION FILTERING.
 - UNIT TESTS FOR SOURCE-SIDE SELECTION IN COMPARISON LOGIC.

README.MD

@@ -112,6 +112,13 @@ Validation:
 python -m codexsync -c config.toml validate
 ```
 
+Preflight diagnostics (same behavior for `doctor` and `preflight`):
+
+```powershell
+python -m codexsync -c config.toml doctor
+python -m codexsync -c config.toml preflight
+```
+
 Build sync plan (no changes):
 
 ```powershell
@@ -229,6 +236,11 @@ Termination-related exit codes for automation:
 - `4` invalid config or CLI arguments
 - `5` safe abort (`fail-safe`)
 
+`doctor`/`preflight` return:
+
+- `0` when all checks passed or warnings only
+- `5` when at least one preflight check failed
+
 ## Required operation protocol
 
 This tool assumes a strict handoff flow between machines:

docs/DECISIONS.MD

@@ -32,3 +32,15 @@ These checks are out of scope and owned by the user.
 ## D-009: CI target matrix for MVP
 CI runs on Windows and macOS runners (`windows-latest`, `macos-latest`).
 Linux CI is intentionally disabled for MVP until Linux runtime support is explicitly in scope.
+
+## D-010: Preflight diagnostics mode
+The CLI provides `doctor` and `preflight` commands (equivalent behavior).
+These checks are read-mostly and validate runtime readiness before sync:
+- config/runtime path readiness
+- local/cloud/backup/temp write access probes
+- Codex process precondition
+- manifest data-version compatibility
+- suspicious mtime drift between local/cloud probes
+- orphan temp file detection
+
+If any preflight check fails, the command exits with code `5` (`fail-safe`).

docs/PROJECT_CONTEXT.MD

@@ -14,6 +14,7 @@ Key decisions:
 * Stop on two-sided file conflicts and require manual resolution + rerun
 * Keep logging configurable (`text|json|logfmt`) with 7-day default retention
 * In verbose mode (`-v`), print tracked Codex processes for plan/sync/restore diagnostics
+* Provide `doctor`/`preflight` diagnostics before sync to validate writable paths, process state, manifest compatibility, suspicious clock drift, and orphan temp files
 * Use explicit CLI exit codes for automation and CI
 * CI currently targets `windows-latest` and `macos-latest`; Linux CI is intentionally disabled in MVP
 

src/codexsync/app.py

@@ -52,6 +52,34 @@ class ProcessSnapshot:
     sandbox_detected: bool
 
 
+@dataclass(slots=True, frozen=True)
+class PreflightCheckResult:
+    name: str
+    status: str
+    details: str
+
+
+@dataclass(slots=True)
+class PreflightReport:
+    checks: list[PreflightCheckResult]
+
+    @property
+    def failures(self) -> list[PreflightCheckResult]:
+        return [item for item in self.checks if item.status == "FAIL"]
+
+    @property
+    def warnings(self) -> list[PreflightCheckResult]:
+        return [item for item in self.checks if item.status == "WARN"]
+
+    @property
+    def passed(self) -> list[PreflightCheckResult]:
+        return [item for item in self.checks if item.status == "PASS"]
+
+    @property
+    def is_ok(self) -> bool:
+        return not self.failures
+
+
 def build_context(
     config_path: Path,
     manual_terminate_confirmation_override: bool | None = None,
@@ -184,6 +212,63 @@ def validate_config_only(config_path: Path) -> None:
         raise
 
 
+def run_preflight(config_path: Path) -> PreflightReport:
+    checks: list[PreflightCheckResult] = []
+
+    try:
+        cfg = load_config(config_path)
+        checks.append(PreflightCheckResult("config", "PASS", f"Loaded config from {config_path}"))
+    except Exception as exc:
+        checks.append(PreflightCheckResult("config", "FAIL", f"Cannot load config: {exc}"))
+        return PreflightReport(checks=checks)
+
+    try:
+        initialize_runtime_paths(cfg)
+        checks.append(PreflightCheckResult("runtime_paths", "PASS", "Runtime paths are initialized"))
+    except Exception as exc:
+        checks.append(PreflightCheckResult("runtime_paths", "FAIL", f"Runtime path initialization failed: {exc}"))
+        return PreflightReport(checks=checks)
+
+    local_dir: Path | None = None
+    cloud_dir: Path | None = None
+    try:
+        local_dir, cloud_dir = resolve_state_dirs(cfg.paths.local_state_dir, cfg.paths.cloud_root_dir)
+        checks.append(PreflightCheckResult("state_dirs", "PASS", f"local={local_dir}; cloud={cloud_dir}"))
+    except Exception as exc:
+        checks.append(PreflightCheckResult("state_dirs", "FAIL", f"State directories are not ready: {exc}"))
+
+    if local_dir is not None:
+        checks.append(_check_write_access("local_write", local_dir))
+    if cloud_dir is not None:
+        checks.append(_check_write_access("cloud_write", cloud_dir))
+
+    checks.append(_check_write_access("backup_write", cfg.paths.backup_dir))
+    checks.append(_check_write_access("temp_write", cfg.paths.temp_dir))
+
+    try:
+        _ = load_manifest(cfg.state.manifest_file, cfg.state.data_version)
+        checks.append(PreflightCheckResult("manifest", "PASS", "Manifest data version is compatible"))
+    except Exception as exc:
+        checks.append(PreflightCheckResult("manifest", "FAIL", f"Manifest check failed: {exc}"))
+
+    checks.append(_check_process_state(cfg))
+    if local_dir is not None and cloud_dir is not None:
+        checks.append(_check_clock_drift(local_dir, cloud_dir))
+    checks.append(_check_orphan_temp_files(cfg.paths.temp_dir))
+
+    return PreflightReport(checks=checks)
+
+
+def print_preflight_report(report: PreflightReport) -> None:
+    print("Preflight report:")
+    for item in report.checks:
+        print(f"  [{item.status}] {item.name}: {item.details}")
+    print(
+        "Summary: "
+        f"pass={len(report.passed)} warn={len(report.warnings)} fail={len(report.failures)}"
+    )
+
+
 def initialize_runtime_paths(cfg: AppConfig) -> None:
     """
     Prepares runtime directories/files for first run.
@@ -546,3 +631,72 @@ def _is_included_root(relative_path: str, include_roots: list[str]) -> bool:
         if rel == root or rel.startswith(f"{root}/"):
             return True
     return False
+
+
+def _check_write_access(name: str, directory: Path) -> PreflightCheckResult:
+    probe = directory / f".codexsync-preflight-{uuid.uuid4().hex}.tmp"
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+        with probe.open("w", encoding="utf-8") as fh:
+            fh.write("ok")
+        return PreflightCheckResult(name, "PASS", f"Write access confirmed for {directory}")
+    except Exception as exc:
+        return PreflightCheckResult(name, "FAIL", f"Cannot write to {directory}: {exc}")
+    finally:
+        probe.unlink(missing_ok=True)
+
+
+def _check_process_state(cfg: AppConfig) -> PreflightCheckResult:
+    if not cfg.safety.require_codex_stopped:
+        return PreflightCheckResult("codex_process", "WARN", "Process check is disabled by safety.require_codex_stopped=false")
+
+    try:
+        snapshot = collect_process_snapshot(cfg)
+    except Exception as exc:
+        if cfg.safety.fail_on_unknown:
+            return PreflightCheckResult("codex_process", "FAIL", f"Cannot verify process state safely: {exc}")
+        return PreflightCheckResult("codex_process", "WARN", f"Process check unavailable: {exc}")
+
+    if snapshot.sandbox_detected:
+        return PreflightCheckResult("codex_process", "FAIL", "codex-windows-sandbox is running")
+    if snapshot.main_processes:
+        details = ", ".join(f"{proc.name}:{proc.pid}" for proc in snapshot.main_processes)
+        return PreflightCheckResult("codex_process", "FAIL", f"Codex process is running: {details}")
+    return PreflightCheckResult("codex_process", "PASS", "Codex process is not running")
+
+
+def _check_clock_drift(local_dir: Path, cloud_dir: Path) -> PreflightCheckResult:
+    local_probe = local_dir / f".codexsync-clock-{uuid.uuid4().hex}.tmp"
+    cloud_probe = cloud_dir / f".codexsync-clock-{uuid.uuid4().hex}.tmp"
+    threshold_seconds = 5
+    try:
+        local_probe.write_text("clock", encoding="utf-8")
+        cloud_probe.write_text("clock", encoding="utf-8")
+        local_mtime = local_probe.stat().st_mtime_ns
+        cloud_mtime = cloud_probe.stat().st_mtime_ns
+        delta_seconds = abs(local_mtime - cloud_mtime) / 1_000_000_000
+        if delta_seconds > threshold_seconds:
+            return PreflightCheckResult(
+                "clock_drift",
+                "WARN",
+                f"Suspicious mtime delta between local/cloud probes: {delta_seconds:.3f}s (> {threshold_seconds}s)",
+            )
+        return PreflightCheckResult("clock_drift", "PASS", f"Probe mtime delta={delta_seconds:.3f}s")
+    except Exception as exc:
+        return PreflightCheckResult("clock_drift", "WARN", f"Clock drift probe failed: {exc}")
+    finally:
+        local_probe.unlink(missing_ok=True)
+        cloud_probe.unlink(missing_ok=True)
+
+
+def _check_orphan_temp_files(temp_dir: Path) -> PreflightCheckResult:
+    if not temp_dir.exists():
+        return PreflightCheckResult("orphan_temp_files", "PASS", "Temp directory does not exist yet")
+    orphan_files = [path for path in temp_dir.rglob("*.tmp") if path.is_file()]
+    if orphan_files:
+        return PreflightCheckResult(
+            "orphan_temp_files",
+            "WARN",
+            f"Found {len(orphan_files)} orphan temp file(s) in {temp_dir}",
+        )
+    return PreflightCheckResult("orphan_temp_files", "PASS", "No orphan temp files found")

src/codexsync/backup.py

@@ -70,9 +70,11 @@ def prune(self) -> None:
     def _backup_file_zip(self, file_path: Path, relative_path: str) -> Path:
         snapshot_zip = self._snapshot_path
         snapshot_zip.parent.mkdir(parents=True, exist_ok=True)
-        arcname = relative_path.replace("\\", "/")
-        arcname = self._deduplicate_zip_entry(arcname)
         with zipfile.ZipFile(snapshot_zip, mode="a", compression=zipfile.ZIP_DEFLATED) as zf:
+            if not self._zip_entries:
+                self._zip_entries.update(zf.namelist())
+            arcname = relative_path.replace("\\", "/")
+            arcname = self._deduplicate_zip_entry(arcname)
             zf.write(file_path, arcname=arcname)
         return snapshot_zip
 

src/codexsync/cli.py

@@ -7,8 +7,10 @@
 from .app import (
     build_context,
     collect_process_snapshot,
+    print_preflight_report,
     print_plan,
     restore_from_backup,
+    run_preflight,
     run_sync,
     validate_config_only,
 )
@@ -49,6 +51,8 @@ def build_parser() -> argparse.ArgumentParser:
     sub = parser.add_subparsers(dest="command", required=True)
 
     sub.add_parser("validate", help="Validate config only")
+    sub.add_parser("doctor", help="Run environment diagnostics before sync")
+    sub.add_parser("preflight", help="Run environment diagnostics before sync")
     sub.add_parser("plan", help="Build and print sync plan")
 
     sync = sub.add_parser("sync", help="Run synchronization")
@@ -98,6 +102,15 @@ def main(argv: list[str] | None = None) -> int:
             print("Config is valid.")
             return int(ExitCode.OK)
 
+        if args.command in {"doctor", "preflight"}:
+            report = run_preflight(config_path)
+            print_preflight_report(report)
+            if report.is_ok:
+                print("Preflight checks passed.")
+                return int(ExitCode.OK)
+            print("Preflight checks failed.")
+            return int(ExitCode.FAIL_SAFE)
+
         if args.command == "plan":
             ctx = build_context(
                 config_path,

src/codexsync/sync_engine.py

@@ -26,6 +26,8 @@ def __init__(
         self._fail_on_unknown = fail_on_unknown
 
     def execute(self, plan: SyncPlan, dry_run: bool = True) -> None:
+        if not dry_run:
+            self._cleanup_orphaned_temp_files()
         for action in plan.to_local:
             self._copy(action, dry_run=dry_run)
         for action in plan.to_cloud:
@@ -50,8 +52,14 @@ def _copy(self, action: CopyAction, dry_run: bool) -> None:
             os.replace(staged, action.dst)
         except OSError:
             if self._fail_on_unknown:
+                LOG.exception("atomic replace failed for staged file %s -> %s", staged, action.dst)
+                raise
+            try:
+                shutil.copy2(staged, action.dst)
+            except OSError:
+                LOG.exception("fallback copy failed for staged file %s -> %s", staged, action.dst)
                 raise
-            shutil.copy2(staged, action.dst)
+        finally:
             staged.unlink(missing_ok=True)
 
     @staticmethod
@@ -69,3 +77,15 @@ def _stage_copy(self, action: CopyAction) -> Path:
             fallback.parent.mkdir(parents=True, exist_ok=True)
             shutil.copy2(action.src, fallback)
             return fallback
+
+    def _cleanup_orphaned_temp_files(self) -> None:
+        if not self._temp_dir.exists():
+            return
+        removed = 0
+        for path in self._temp_dir.rglob("*.tmp"):
+            if not path.is_file():
+                continue
+            path.unlink(missing_ok=True)
+            removed += 1
+        if removed:
+            LOG.info("removed %d orphaned temporary file(s) in %s", removed, self._temp_dir)