(defcustom madrigal-save-sync-timeout 1.0
  "Seconds to wait for replica edits to reach the server before save."
  :type 'number)
(defcustom madrigal-allow-save-buffer-op nil
  "When non-nil, allow tool op `save_buffer` to write files.
Default is nil so saving remains the user's explicit choice."
  :type 'boolean)

     "Do not save files; saving is always the user's explicit choice."

(defun madrigal--flush-replica-to-server (replica-buffer agent-session server-buffer timeout)
  (let* ((deadline (+ (float-time) (max 0.0 timeout)))
         (synced nil))
    (while (and (not synced)
                (< (float-time) deadline))
      (setq synced
            (with-current-buffer replica-buffer
              (let ((replica-text (buffer-substring-no-properties (point-min) (point-max))))
                (with-current-buffer server-buffer
                  (string= replica-text
                           (buffer-substring-no-properties (point-min) (point-max)))))))
      (unless synced
        (let ((agent-proc (crdt--session-network-process agent-session))
              (server-proc (crdt--session-network-process madrigal--server-session)))
          (when (process-live-p agent-proc)
            (accept-process-output agent-proc 0.02))
          (when (process-live-p server-proc)
            (accept-process-output server-proc 0.02)))))
    synced))

         (agent-session (madrigal--agent-session agent))

            (let ((server-buffer (madrigal--server-buffer-from-network-name network-name)))
              (unless (buffer-live-p server-buffer)
                (error "madrigal: no server buffer for %s" network-name))
             (with-current-buffer server-buffer
               (when (and buffer-file-name (buffer-modified-p))
                 (save-buffer))

             (unless madrigal-allow-save-buffer-op
               (error "madrigal: save_buffer disabled; user should save explicitly"))
             (let ((server-buffer (madrigal--server-buffer-from-network-name network-name)))
               (unless (buffer-live-p server-buffer)
                 (error "madrigal: no server buffer for %s" network-name))
               (unless (madrigal--flush-replica-to-server
                        replica agent-session server-buffer madrigal-save-sync-timeout)
                 (error "madrigal: timed out waiting for CRDT sync before save"))
              (with-current-buffer server-buffer
                (when (and buffer-file-name (buffer-modified-p))
                  (save-buffer))

   (concat
     "Execute a sequence of CRDT editing operations in the agent replica. "
     "Operations: open_file, list_buffers, switch_buffer, get_point, goto_char, "
     "search_forward, search_backward, set_region, clear_region, read_region, "
      "insert_text, delete_selection, replace_selection, replace_match, replace_in_selection, "
      "save_buffer. "
      "search_forward/search_backward support needle plus text/query aliases and optional wrap boolean (default true). "
      "Supports references like $1.point to consume previous step outputs.")

    (concat
      "Execute a sequence of CRDT editing operations in the agent replica. "
      "Operations: open_file, list_buffers, switch_buffer, get_point, goto_char, "
      "search_forward, search_backward, set_region, clear_region, read_region, "
       "insert_text, delete_selection, replace_selection, replace_match, replace_in_selection. "
       "save_buffer is disabled by default unless `madrigal-allow-save-buffer-op` is non-nil. "
       "search_forward/search_backward support needle plus text/query aliases and optional wrap boolean (default true). "
       "Supports references like $1.point to consume previous step outputs.")