feat: explain frame-boundary pausing on hit responses and surface the expired next action

.agents/skills/uloop-pause-point/SKILL.md

@@ -100,7 +100,7 @@ Choose the capture mode when enabling a pause point:
 - `trace` remains armed and records each hit without pausing Unity.
 - In every mode, `CapturedVariables` holds the latest hit and `CapturedVariableHistory` holds only strictly older frames, so with a single hit the history is empty (for `single-shot` it always is). When the latest-hit frame is excluded, `CapturedVariableHistoryNote` explains that the latest hit's variables are in `CapturedVariables`.
 - Prefer tracing a line that executes conditionally: a line that runs every frame fills the capped history within a fraction of a second and drops everything recorded before it.
-- In trace mode, Status "Hit" does not mean Play Mode paused; the response carries a StatusNote saying the marker fired while the game kept running.
+- On every Hit, the response carries a StatusNote. In trace mode it says Play Mode was not paused (the marker fired while the game kept running). In single-shot and continuous it says Unity pauses at the next frame boundary, so live reads after the hit reflect post-frame state; use CapturedVariables for at-line values.
 - An Expired response carries a RecommendedNextAction: re-enable the pause point with a longer --timeout-seconds (default 30) and trigger the code path again; clearing the expired marker first is not required.
 - For an already-hit `continuous` or `trace` marker, `await-pause-point` waits for a **new** hit after the wait starts (`LastHitSequence` advancing). It does not return the stale hit that is already present. Read the current hit with `pause-point-status` instead. If await times out while waiting for that new hit, the error stays `PAUSE_POINT_WAIT_TIMEOUT` and `Details.Hint` tells you to pass `--resume-play` (or resume Play Mode) so another hit can occur. A freshly enabled marker (including `enable-pause-point --await`) has no prior hit, so the first hit satisfies the wait as before.
 

.claude/skills/uloop-pause-point/SKILL.md

@@ -100,7 +100,7 @@ Choose the capture mode when enabling a pause point:
 - `trace` remains armed and records each hit without pausing Unity.
 - In every mode, `CapturedVariables` holds the latest hit and `CapturedVariableHistory` holds only strictly older frames, so with a single hit the history is empty (for `single-shot` it always is). When the latest-hit frame is excluded, `CapturedVariableHistoryNote` explains that the latest hit's variables are in `CapturedVariables`.
 - Prefer tracing a line that executes conditionally: a line that runs every frame fills the capped history within a fraction of a second and drops everything recorded before it.
-- In trace mode, Status "Hit" does not mean Play Mode paused; the response carries a StatusNote saying the marker fired while the game kept running.
+- On every Hit, the response carries a StatusNote. In trace mode it says Play Mode was not paused (the marker fired while the game kept running). In single-shot and continuous it says Unity pauses at the next frame boundary, so live reads after the hit reflect post-frame state; use CapturedVariables for at-line values.
 - An Expired response carries a RecommendedNextAction: re-enable the pause point with a longer --timeout-seconds (default 30) and trigger the code path again; clearing the expired marker first is not required.
 - For an already-hit `continuous` or `trace` marker, `await-pause-point` waits for a **new** hit after the wait starts (`LastHitSequence` advancing). It does not return the stale hit that is already present. Read the current hit with `pause-point-status` instead. If await times out while waiting for that new hit, the error stays `PAUSE_POINT_WAIT_TIMEOUT` and `Details.Hint` tells you to pass `--resume-play` (or resume Play Mode) so another hit can occur. A freshly enabled marker (including `enable-pause-point --await`) has no prior hit, so the first hit satisfies the wait as before.
 

Packages/src/Editor/CliOnlyTools~/PausePoint/Skill/SKILL.md

@@ -100,7 +100,7 @@ Choose the capture mode when enabling a pause point:
 - `trace` remains armed and records each hit without pausing Unity.
 - In every mode, `CapturedVariables` holds the latest hit and `CapturedVariableHistory` holds only strictly older frames, so with a single hit the history is empty (for `single-shot` it always is). When the latest-hit frame is excluded, `CapturedVariableHistoryNote` explains that the latest hit's variables are in `CapturedVariables`.
 - Prefer tracing a line that executes conditionally: a line that runs every frame fills the capped history within a fraction of a second and drops everything recorded before it.
-- In trace mode, Status "Hit" does not mean Play Mode paused; the response carries a StatusNote saying the marker fired while the game kept running.
+- On every Hit, the response carries a StatusNote. In trace mode it says Play Mode was not paused (the marker fired while the game kept running). In single-shot and continuous it says Unity pauses at the next frame boundary, so live reads after the hit reflect post-frame state; use CapturedVariables for at-line values.
 - An Expired response carries a RecommendedNextAction: re-enable the pause point with a longer --timeout-seconds (default 30) and trigger the code path again; clearing the expired marker first is not required.
 - For an already-hit `continuous` or `trace` marker, `await-pause-point` waits for a **new** hit after the wait starts (`LastHitSequence` advancing). It does not return the stale hit that is already present. Read the current hit with `pause-point-status` instead. If await times out while waiting for that new hit, the error stays `PAUSE_POINT_WAIT_TIMEOUT` and `Details.Hint` tells you to pass `--resume-play` (or resume Play Mode) so another hit can occur. A freshly enabled marker (including `enable-pause-point --await`) has no prior hit, so the first hit satisfies the wait as before.
 

cli/project-runner/internal/projectrunner/pause_point_enable.go

@@ -411,7 +411,7 @@ func runPausePointWaitAfterEnable(
 		response.ResolvedMethod = enableFields.ResolvedMethod
 		response.SnapshotTiming = enableFields.SnapshotTiming
 		response = filterPausePointCapturedVariableHistory(response)
-		response = applyPausePointTraceStatusNote(response)
+		response = applyPausePointHitStatusNote(response)
 		response = filterPausePointCapturedVariablesByName(response, options.capturedVariableNames)
 		response = applyPausePointCapturedVariablesMode(response, options.capturedVariablesMode)
 

cli/project-runner/internal/projectrunner/pause_point_enable_test.go

@@ -215,7 +215,7 @@ func TestRunEnablePausePointCommandAwaitsAfterSuccessfulEnable(t *testing.T) {
 }
 
 // Verifies enable-pause-point --await stdout includes StatusNote on a trace-mode Hit.
-// Removing applyPausePointTraceStatusNote from the enable-await hit path makes this test Red.
+// Removing applyPausePointHitStatusNote from the enable-await hit path makes this test Red.
 func TestRunEnablePausePointCommandIncludesStatusNoteOnTraceHit(t *testing.T) {
 	originalQuery := queryPausePointStatus
 	originalPoll := pausePointStatusPoll
@@ -289,6 +289,83 @@ func TestRunEnablePausePointCommandIncludesStatusNoteOnTraceHit(t *testing.T) {
 	assertStdoutHasPausePointTraceStatusNote(t, stdout.Bytes())
 }
 
+// Verifies enable-pause-point --await stdout includes the frame-boundary StatusNote
+// on a non-trace Hit. Removing applyPausePointHitStatusNote from the enable-await
+// hit path makes this test Red.
+func TestRunEnablePausePointCommandIncludesStatusNoteOnSingleShotHit(t *testing.T) {
+	originalQuery := queryPausePointStatus
+	originalPoll := pausePointStatusPoll
+	originalFetch := fetchMatchingLogs
+	pausePointStatusPoll = time.Millisecond
+	t.Cleanup(func() {
+		queryPausePointStatus = originalQuery
+		pausePointStatusPoll = originalPoll
+		fetchMatchingLogs = originalFetch
+	})
+
+	statusResponses := []pausePointStatusResponse{
+		{Id: "jump", Status: pausePointStatusEnabled, IsEnabled: true},
+		{
+			Id:        "jump",
+			Status:    pausePointStatusHit,
+			Mode:      "single-shot",
+			IsEnabled: true,
+			IsHit:     true,
+			HitCount:  1,
+		},
+	}
+	statusCallCount := 0
+	queryPausePointStatus = func(ctx context.Context, connection unityipc.Connection, id string) (pausePointStatusResponse, error) {
+		response := statusResponses[statusCallCount]
+		statusCallCount++
+		return response, nil
+	}
+	fetchMatchingLogs = func(
+		ctx context.Context,
+		connection unityipc.Connection,
+		searchText string,
+		maxCount int,
+	) (pausePointMatchingLogsResult, error) {
+		return pausePointMatchingLogsResult{SearchText: searchText, Logs: []pausePointMatchingLog{}}, nil
+	}
+
+	listener := newLoopbackIpcListener(t)
+	enableRequests := make(chan map[string]any, 1)
+	serverErr := make(chan error, 1)
+	go serveSingleIPCResponse(
+		listener,
+		pausePointEnableCommandName,
+		enableRequests,
+		serverErr,
+		`{"Success":true,"Id":"jump","Status":"Enabled","IsEnabled":true,"TimeoutSeconds":30}`,
+	)
+
+	connection := unityipc.Connection{
+		Endpoint: unityipc.Endpoint{
+			Network: listener.Addr().Network(),
+			Address: listener.Addr().String(),
+		},
+		ProjectRoot: t.TempDir(),
+	}
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := runEnablePausePointCommand(
+		context.Background(),
+		connection,
+		[]string{"--id", "jump", "--await"},
+		t.TempDir(),
+		&stdout,
+		&stderr)
+
+	if code != 0 {
+		t.Fatalf("expected success, got %d with stderr %s", code, stderr.String())
+	}
+
+	assertStdoutHasPausePointStatusNote(t, stdout.Bytes(),
+		"Unity pauses at the next frame boundary; the rest of the hit frame already ran. Read at-line values from CapturedVariables; live reads via execute-dynamic-code reflect post-frame state.")
+}
+
 // Verifies file:line enable --await copies ResolvedLine / ResolvedLineText / ResolvedMethod /
 // SnapshotTiming from the enable response into the await hit payload.
 func TestRunEnablePausePointCommandAwaitPropagatesFileLineResolvedFields(t *testing.T) {

cli/project-runner/internal/projectrunner/pause_point_errors.go

@@ -221,16 +221,24 @@ func pausePointStateError(
 		SafeToRetry: retryable,
 		ProjectRoot: projectRoot,
 		Command:     clicore.PausePointAwaitCommandName,
-		NextActions: []string{
-			"Run `uloop enable-pause-point --id <marker-id>` before waiting.",
-			"Confirm the code path calls `UloopPausePoint.Pause(\"<marker-id>\")` with the same id.",
-			"Check `Details.Status`, `Details.EditorState`, `Details.ElapsedSinceEnabledMilliseconds`, and `Details.RemainingMilliseconds` to distinguish a missed code path from an already-paused Editor.",
-			"If the marker is inside a custom asmdef, add a reference to `UnityCLILoop.PausePoints.Runtime`.",
-		},
-		Details: pausePointStateErrorDetails(options, response),
+		NextActions: pausePointStateNextActions(response),
+		Details:     pausePointStateErrorDetails(options, response),
 	}
 }
 
+func pausePointStateNextActions(response pausePointStatusResponse) []string {
+	nextActions := []string{
+		"Run `uloop enable-pause-point --id <marker-id>` before waiting.",
+		"Confirm the code path calls `UloopPausePoint.Pause(\"<marker-id>\")` with the same id.",
+		"Check `Details.Status`, `Details.EditorState`, `Details.ElapsedSinceEnabledMilliseconds`, and `Details.RemainingMilliseconds` to distinguish a missed code path from an already-paused Editor.",
+		"If the marker is inside a custom asmdef, add a reference to `UnityCLILoop.PausePoints.Runtime`.",
+	}
+	if response.RecommendedNextAction == "" {
+		return nextActions
+	}
+	return append([]string{response.RecommendedNextAction}, nextActions...)
+}
+
 func pausePointStateErrorDetails(
 	options waitForPausePointOptions,
 	response pausePointStatusResponse,

cli/project-runner/internal/projectrunner/pause_point_types.go

@@ -73,9 +73,10 @@ type pausePointStatusResponse struct {
 	// carries that hit. omitempty keeps the field off 0-hit and unfiltered responses.
 	CapturedVariableHistoryNote string `json:"CapturedVariableHistoryNote,omitempty"`
 
-	// StatusNote is set by the CLI, not Unity, when Mode is trace and Status is Hit.
-	// omitempty keeps the field off every other mode and status so the shared status
-	// contract fixture stays unchanged.
+	// StatusNote is set by the CLI, not Unity, when Status is Hit. Trace mode explains
+	// that Play Mode was not paused; other modes explain the frame-boundary pause.
+	// omitempty keeps the field off non-Hit statuses so the shared status contract
+	// fixture stays unchanged.
 	StatusNote string `json:"StatusNote,omitempty"`
 
 	// TriggerResult is set by the CLI, not Unity, only when --trigger was passed. It is omitted

cli/project-runner/internal/projectrunner/pause_point_wait.go

@@ -35,6 +35,10 @@ const (
 	// pausePointTraceStatusNote explains that a trace-mode Hit did not pause Play Mode.
 	pausePointTraceStatusNote = "Trace mode does not pause Play Mode; Status 'Hit' records that the marker fired while the game kept running."
 
+	// Why: a non-trace Hit pauses at the next frame boundary, so live reads after the
+	// pause are already post-frame; agents otherwise treat them as at-line evidence.
+	pausePointHitFrameBoundaryStatusNote = "Unity pauses at the next frame boundary; the rest of the hit frame already ran. Read at-line values from CapturedVariables; live reads via execute-dynamic-code reflect post-frame state."
+
 	// Mode strings mirror UloopPausePointCaptureMode on the Unity side. Await uses an allowlist
 	// (continuous/trace) for the new-hit baseline — never `Mode != "single-shot"` — so an empty
 	// Mode from an older package keeps the historical immediate-Hit success path.
@@ -128,11 +132,17 @@ func filterPausePointCapturedVariableHistory(response pausePointStatusResponse)
 	return response
 }
 
-// applyPausePointTraceStatusNote records that a trace-mode Hit did not pause Play Mode.
-func applyPausePointTraceStatusNote(response pausePointStatusResponse) pausePointStatusResponse {
-	if response.Mode == pausePointModeTrace && response.Status == pausePointStatusHit {
+// applyPausePointHitStatusNote records mode-specific Hit guidance: trace did not
+// pause Play Mode; other modes paused at the next frame boundary.
+func applyPausePointHitStatusNote(response pausePointStatusResponse) pausePointStatusResponse {
+	if response.Status != pausePointStatusHit {
+		return response
+	}
+	if response.Mode == pausePointModeTrace {
 		response.StatusNote = pausePointTraceStatusNote
+		return response
 	}
+	response.StatusNote = pausePointHitFrameBoundaryStatusNote
 	return response
 }
 
@@ -204,7 +214,7 @@ func runPausePointStatusCommand(
 	}
 	response = normalizePausePointStatusResponse(response)
 	response = filterPausePointCapturedVariableHistory(response)
-	response = applyPausePointTraceStatusNote(response)
+	response = applyPausePointHitStatusNote(response)
 	// Evaluated against the raw CapturedVariables, before the filters below can narrow or strip
 	// values, for the same reason as on the await path (runWaitForPausePoint): otherwise an --expect
 	// target not also requested via --captured-variable-names, or whose value names mode stripped,
@@ -260,7 +270,7 @@ func runWaitForPausePoint(
 		response.TriggerResult = triggerResult
 		response.ResumePlayResult = resumeResult
 		response = filterPausePointCapturedVariableHistory(response)
-		response = applyPausePointTraceStatusNote(response)
+		response = applyPausePointHitStatusNote(response)
 		response = filterPausePointCapturedVariablesByName(response, options.capturedVariableNames)
 		response = applyPausePointCapturedVariablesMode(response, options.capturedVariablesMode)
 		// Best-effort: a hit must stay a success even if Unity is busy while paused.