Add Emacs-only timestamp when agent returns control

Append a local HH:MM:SS timestamp to the chat buffer in
--display-agent-end whenever a turn settles to idle (not on
retry/continue). The timestamp is display-only: generated with
format-time-string and inserted into the buffer, never sent to the
pi CLI nor stored in canonical session history, so it is dropped on
history rebuild/reload.

Controlled by pi-coding-agent-show-return-timestamp (default t) and
pi-coding-agent-return-timestamp-format, styled with the new
pi-coding-agent-return-timestamp face.

Author: Lugh

pi-coding-agent-render.el

@@ -616,6 +616,24 @@ follow-up as a fresh prompt.")
                        #'pi-coding-agent--drain-followup-queue-if-idle
                        (current-buffer)))))
 
+(defun pi-coding-agent--insert-return-timestamp ()
+  "Append a local timestamp marking when the agent returned control.
+This decoration lives only in the Emacs chat buffer; it is never sent to
+the pi CLI nor persisted in session history.  Controlled by
+`pi-coding-agent-show-return-timestamp' and
+`pi-coding-agent-return-timestamp-format'."
+  (when pi-coding-agent-show-return-timestamp
+    (let ((stamp (format-time-string pi-coding-agent-return-timestamp-format)))
+      (pi-coding-agent--with-scroll-preservation
+        (save-excursion
+          (goto-char (point-max))
+          (skip-chars-backward "\n")
+          (delete-region (point) (point-max))
+          (insert "\n\n"
+                  (propertize stamp 'face 'pi-coding-agent-return-timestamp
+                              'pi-coding-agent-return-timestamp t)
+                  "\n"))))))
+
 (defun pi-coding-agent--display-agent-end ()
   "Finalize agent turn: normalize whitespace, handle abort, schedule queue."
   ;; Reset per-turn state for clean next turn.
@@ -646,6 +664,11 @@ follow-up as a fresh prompt.")
           (insert "\n"))))
     (pi-coding-agent--set-activity-phase
      (if (eq pi-coding-agent--status 'sending) "thinking" "idle"))
+    ;; Control has returned to the user only when the turn settled to idle
+    ;; (not when pi will retry/continue).  Stamp the local time then.
+    (when (eq pi-coding-agent--status 'idle)
+      (let ((inhibit-read-only t))
+        (pi-coding-agent--insert-return-timestamp)))
     (pi-coding-agent--refresh-header)
     ;; Give immediate post-run compaction/retry events a chance to arrive before
     ;; turning a local follow-up into a new independent prompt.

pi-coding-agent-ui.el

@@ -278,13 +278,34 @@ still operate on the raw table source."
   :type 'boolean
   :group 'pi-coding-agent)
 
+(defcustom pi-coding-agent-show-return-timestamp t
+  "Whether to display a local timestamp when the agent returns control.
+When non-nil, each completed agent turn appends a timestamp line to the
+chat buffer marking when control returned to the user.  This decoration
+is Emacs-only: it is never sent to the pi CLI nor stored in session
+history.  The timestamp is formatted with
+`pi-coding-agent-return-timestamp-format'."
+  :type 'boolean
+  :group 'pi-coding-agent)
+
+(defcustom pi-coding-agent-return-timestamp-format "%H:%M:%S"
+  "`format-time-string' format for the agent-return timestamp.
+Used when `pi-coding-agent-show-return-timestamp' is non-nil."
+  :type 'string
+  :group 'pi-coding-agent)
+
 ;;;; Faces
 
 (defface pi-coding-agent-timestamp
   '((t :inherit shadow))
   "Face for timestamps in message headers."
   :group 'pi-coding-agent)
 
+(defface pi-coding-agent-return-timestamp
+  '((t :inherit shadow :slant italic))
+  "Face for the Emacs-only timestamp marking when the agent returned control."
+  :group 'pi-coding-agent)
+
 (defface pi-coding-agent-tool-name
   '((t :inherit font-lock-function-name-face :weight bold :slant italic))
   "Face for tool names (BASH, READ, etc.) in pi chat."

test/pi-coding-agent-render-test.el

@@ -142,9 +142,47 @@ as the top-level structure."
   "agent_end normalizes trailing whitespace to single newline."
   (with-temp-buffer
     (pi-coding-agent-chat-mode)
-    (pi-coding-agent--append-to-chat "Some response")
-    (pi-coding-agent--display-agent-end)
-    (should (string-suffix-p "response\n" (buffer-string)))))
+    (let ((pi-coding-agent-show-return-timestamp nil))
+      (pi-coding-agent--append-to-chat "Some response")
+      (pi-coding-agent--display-agent-end)
+      (should (string-suffix-p "response\n" (buffer-string))))))
+
+(ert-deftest pi-coding-agent-test-return-timestamp-appended-when-idle ()
+  "agent_end appends a local timestamp line when the turn settles to idle."
+  (with-temp-buffer
+    (pi-coding-agent-chat-mode)
+    (let ((pi-coding-agent-show-return-timestamp t)
+          (pi-coding-agent-return-timestamp-format "%H:%M:%S"))
+      (setq pi-coding-agent--status 'idle)
+      (pi-coding-agent--append-to-chat "Some response")
+      (pi-coding-agent--display-agent-end)
+      ;; Trailing line is a HH:MM:SS timestamp carrying the return marker prop.
+      (should (string-match-p "[0-9][0-9]:[0-9][0-9]:[0-9][0-9]\n\\'"
+                              (buffer-string)))
+      (goto-char (point-max))
+      (forward-line -1)
+      (should (get-text-property (point)
+                                 'pi-coding-agent-return-timestamp)))))
+
+(ert-deftest pi-coding-agent-test-return-timestamp-suppressed-when-disabled ()
+  "No timestamp is added when `pi-coding-agent-show-return-timestamp' is nil."
+  (with-temp-buffer
+    (pi-coding-agent-chat-mode)
+    (let ((pi-coding-agent-show-return-timestamp nil))
+      (setq pi-coding-agent--status 'idle)
+      (pi-coding-agent--append-to-chat "Some response")
+      (pi-coding-agent--display-agent-end)
+      (should (string-suffix-p "response\n" (buffer-string))))))
+
+(ert-deftest pi-coding-agent-test-return-timestamp-suppressed-when-retrying ()
+  "No timestamp is added when the turn will continue (status not idle)."
+  (with-temp-buffer
+    (pi-coding-agent-chat-mode)
+    (let ((pi-coding-agent-show-return-timestamp t))
+      (setq pi-coding-agent--status 'sending)
+      (pi-coding-agent--append-to-chat "Some response")
+      (pi-coding-agent--display-agent-end)
+      (should (string-suffix-p "response\n" (buffer-string))))))
 
 (ert-deftest pi-coding-agent-test-spacing-blank-line-after-user-header ()
   "User header has a blank line after setext underline."
@@ -532,25 +570,27 @@ agent_end + next section's leading newline must not create triple newlines."
     ;; Turn 1: user + assistant
     (pi-coding-agent--display-user-message "Hi")
     (pi-coding-agent--display-agent-start)
-    (pi-coding-agent--display-message-delta "Hello!")
-    (pi-coding-agent--render-complete-message)
-    (pi-coding-agent--display-agent-end)
-    ;; Turn 2: user message
-    (setq pi-coding-agent--assistant-header-shown nil)
-    (pi-coding-agent--display-user-message "Bye")
-    ;; Should never have triple newlines (which would be two blank lines)
-    (should-not (string-match-p "\n\n\n" (buffer-string)))))
+    (let ((pi-coding-agent-show-return-timestamp nil))
+      (pi-coding-agent--display-message-delta "Hello!")
+      (pi-coding-agent--render-complete-message)
+      (pi-coding-agent--display-agent-end)
+      ;; Turn 2: user message
+      (setq pi-coding-agent--assistant-header-shown nil)
+      (pi-coding-agent--display-user-message "Bye")
+      ;; Should never have triple newlines (which would be two blank lines)
+      (should-not (string-match-p "\n\n\n" (buffer-string))))))
 
 (ert-deftest pi-coding-agent-test-spacing-single-blank-line-before-compaction ()
   "Only one blank line between agent response and compaction header."
   (with-temp-buffer
     (pi-coding-agent-chat-mode)
     (pi-coding-agent--display-agent-start)
-    (pi-coding-agent--display-message-delta "Some response.")
-    (pi-coding-agent--render-complete-message)
-    (pi-coding-agent--display-agent-end)
-    (pi-coding-agent--display-compaction-result 50000 "Summary.")
-    (should-not (string-match-p "\n\n\n" (buffer-string)))))
+    (let ((pi-coding-agent-show-return-timestamp nil))
+      (pi-coding-agent--display-message-delta "Some response.")
+      (pi-coding-agent--render-complete-message)
+      (pi-coding-agent--display-agent-end)
+      (pi-coding-agent--display-compaction-result 50000 "Summary.")
+      (should-not (string-match-p "\n\n\n" (buffer-string))))))
 
 (ert-deftest pi-coding-agent-test-spacing-no-double-blank-between-tools ()
   "Consecutive tools have single blank line between them."