Skip to content

docs: observability design (error repro + perf timing) - #162

Draft
EvanBacon wants to merge 27 commits into
mainfrom
cursor/observability-repro-timing-d83f
Draft

EvanBacon wants to merge 27 commits into
mainfrom
cursor/observability-repro-timing-d83f

Conversation

@EvanBacon

@EvanBacon EvanBacon commented Sep 25, 2026 •

Copy link
Copy Markdown
Owner

Docs-only. No runtime code, dependencies, or CI changes.

Rebuilds docs/observability.md on the event log serve-sim already has (src/event-log.ts, surfaced at GET /api/event-log, the /api/event-log/events SSE stream, and serve-sim event-log --json). It documents what that log records today, the small additive fields that make our silent failures reproducible from the log alone, and names the exact hook that produces each field.

What it covers

  • How a bot reads the log back -- the HTTP, SSE, and CLI surfaces, plus a schema_version on the response envelope.
  • Touch input has no visible effect on a headless iOS 27 simulator (Xcode 27) #153 recordable from the log: coord_space, orientation (read from screenConfig() at record time, and kept current for rotations outside 0x07 via the onSharedMjpegFrame dimension-swap observe path / a non-Duo orientation poll mirroring DuoStateMonitor.refreshOrientation), frame (display vs native_portrait), remapped (rawPointForDisplayPoint), and source (cli vs web) added compatibly to the 0x03 payload and read in recordTouchEvent.
  • Did the screen change after a tap, without keeping pixels -- a monotonic frame seq + cheap content seed in onSharedMjpegFrame, written back onto the tap entry with updateEventLogEvent as screen_changed.
  • What an ack can and can't prove -- today only fold (0x0e) waits for a reply; tap/gesture/rotate/button are fire-and-forget. The ack proves the server received and dispatched the frame to the native injector (NativeHid.touch -> SimHIDHandle.touch, wrapped by guard() in native.ts); it does not prove the guest UI reacted -- that's what screen_changed is for.
  • HID health + Device Hub shadowing (isDeviceHubInputShadowed / com.apple.coredevice.dtuhidd.active), helper lifecycle (classifyStaleState, startSimulatorShutdownWatch), and the corrected Native MJPEG preview can show false frame-stall error after rotation #128 (the watchdog is on the fetch() reader, not <img>) and Flaky: SimCameraHelper shm probe — helper exits with a signal during shutdown (bisected to 14ad57f) #143 (supervising parent captures exit code and signal; SIGPIPE is already ignored) notes.
  • Privacy/export defaults: local event log on by default; remote OTLP export opt-in only via a serve-sim-specific variable that never inherits a stray OTEL_EXPORTER_OTLP_ENDPOINT; the correct debug switches (DEBUG=serve-sim:*, SERVE_SIM_DEBUG_HID -- there is no SERVE_SIM_DEBUG).
  • A test plan against the existing event-log, device-hub-input, and helper-lifecycle tests.

The span-tree, histogram buckets, and OpenTelemetry-survey material from the earlier draft are gone; this is scoped to the event log and names only hooks that exist.

Prerequisite

The guide points agents at GET /api/event-log and serve-sim event-log --json on a possibly-remote server. The auth that makes those endpoints safe to reach off-loopback comes from the serve-sim auth/exec security fix (branch fix/api-exec-auth); merge that first.

Design/docs-only -- the field additions it proposes are small and additive, each pinned to a named hook, to be implemented and tested separately.

Open in Web Open in Cursor 

Summary by CodeRabbit

  • Documentation
    • Added a proposal outlining possible diagnostic details for touch input, screen changes, input acknowledgements, device health, service and stream events, and timing.
    • Documented current event-log access, redaction, and privacy constraints. Clarified that the proposed diagnostics are not implemented, would be additive and non-fatal, and would preserve the existing remote-access gate.

@coderabbitai

coderabbitai Bot commented Sep 25, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

No actionable comments were generated in the recent review.

Walkthrough

Adds a design proposal for observability. It documents current event-log behavior and proposes diagnostic fields and event kinds for input, helper and stream lifecycles, and timing. The proposal retains privacy constraints and the remote-readback authentication gate. It does not implement the proposed additions.

Changes: Observability Documentation

Layer / File(s) Summary
Event-log contract and readback
docs/observability.md
Documents the current event-log shape, sources, redaction, readback routes, and remote-access authentication. Proposes an additive schema_version for API and SSE envelopes.
Input diagnostics
docs/observability.md
Describes existing touch remapping and input acknowledgements. Proposes touch and screen-change details, input acknowledgements and injection results, and HID health and shadowing fields.
Lifecycle, timing, and privacy details
docs/observability.md
Proposes helper and stream lifecycle events, defines duration fields and omission conditions, and states privacy constraints and the existing remote-readback authentication requirement.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Possibly related issues

  • EvanBacon/serve-sim#174: The proposal sets privacy rules for a possible clipboard path, but does not implement that path.
  • EvanBacon/serve-sim#172: The proposed input diagnostics would distinguish the described ineffective tap from coordinate misses and dead injectors, but do not fix the issue.

Possibly related PRs

Merge Risk: Minimal · previous review da372

The change documents proposed observability improvements without changing runtime behavior. No concrete merge-blocking issue is established by the supplied evidence.

Pre-merge checks: Passed 5

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly identifies a documentation change for observability design and accurately highlights error reproduction and performance timing, which are the main topics of the changeset.
Docstring Coverage Passed No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

Finishing Touches

🧪 Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: fefa53ee-b892-4fbd-9f51-7d0fc5c642de
Commits

Reviewing files that changed from the base of the PR and between da807fe and da372bd.

Files selected for processing: 1

  • docs/observability.md
Files skipped from review as they are similar to previous changes: 1

  • docs/observability.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 5 remain after this review.

Copy link
Copy Markdown
Owner Author

Design review ping for Evan: docs/observability.md on this branch already covers the error-repro fields for #153 / #136 / #128 / #103 / #143 (plus #102 lifecycle) and the perf spans (TTFF, inject send/roundtrip, camera frame interval, helper start/stop, reconnect). Headless-touch is explicit via sim.ui_host, input.target=digitizer, and fire-and-forget inject.ack=none / guest_effect=not_checked.

No doc amend needed this cycle — ready for human review as design-only draft.

Open questions (non-blocking):

  1. Should phase-1 --list expose hid.state even when telemetry is off (doc already leans yes)?
  2. Keep inject.guest_effect opt-in local-only forever, or eventually allow a coarse changed|unchanged without pixels on remote?
  3. Any rename before implement (sim.ui_host vs sim.host_app)?

Copy link
Copy Markdown
Owner Author

Maintenance (2026-09-27): re-checked docs/observability.md on this branch — still correctly prioritizes (1) error-reproduction fields for #153/#136/#128/#103/#143/#102 and (2) performance timing spans (TTFF, inject send/roundtrip, camera frame interval, helper start/stop, reconnect). Opt-in/default-off unchanged.

CI: lint + typecheck green. mergeable_state clean. No review-comment nits to apply. Still design-only draft awaiting Evan human review (questions from prior ping stand). Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-09-28): re-checked — still design-only, still prioritizes error-reproduction fields (#153/#136/#128/#103/#143/#102) and perf timing spans (TTFF, inject, camera interval, helper start/stop, reconnect). CI lint+typecheck green; mergeable clean. No doc amend this cycle. Awaiting Evan review. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-01): amended docs/observability.md (e4e0adb) from the 2026-09-30 #153 repro. Headless portrait taps land; landscape_left misses because CLI/server pass display-normalized points into the native portrait frame (rawPointForDisplayPoint already does { x: y, y: 1 - x } in the web client).

Error-repro: input.orientation, input.frame (display | native_portrait), input.remapped. Signature of the miss is hid.state=ok + inject.result=sent + input.frame=display + input.remapped=false + inject.guest_effect=unchanged, distinct from #136 hid.state=gone.

Perf spans: input.send / input.roundtrip carry those three fields so a landscape miss is not bucketed with a portrait hit. No remap span (arithmetic only). stream.reconnect carries stream.orientation so a #128 false stall is not the same event as a #153 coordinate miss.

Still design-only draft. CI was green on the previous commit; this commit is docs-only. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-02): still design-only. Pushed d7888cc adding worked records so the error-repro fields and perf spans are concrete lines, not only tables.

  • #153 portrait hit vs landscape_left miss (hid.state=ok, inject.result=sent, input.frame=display, input.remapped=false, inject.guest_effect=unchanged), plus the post-remap expectation (input.frame=native_portrait, input.remapped=true).
  • #128 false stall stays a separate stream.stall event (stream.false_positive=true, stream.orientation) so it is not bucketed with the coordinate miss.
  • input.send carries orientation/frame/remapped (same input.send_ms on hit and miss). stream.reconnect carries stream.orientation. No remap span.

CI on the previous commit was green (lint + typecheck). This commit is docs-only. No review-comment nits. Still awaiting human review. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-04): pushed 9e343c3 on docs/observability.md. Error-repro events and perf spans were still two lines. Same attempt now shares trace.id; spans add span.id / parent.span_id.

span.status stays ok on the #153 landscape miss (inject.result=sent, hid.state=ok, input.remapped=false, inject.guest_effect=unchanged) so a 4 ms input.send is not bucketed with #136 (hid.state=gone → span.status=error). #128 false stall is a different trace and stays span.status=unset when stream.false_positive=true.

No review-comment nits. Prior CI (lint + typecheck) was green; this commit is docs-only. Still design-only draft. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-05): pushed 4f11f61 on docs/observability.md. Error-repro fields now sit on the timing spans, not only on the event lines.

  • #103: stream.startup stays span.status=ok at stream.ttff_ms=180 with stream.saw_first_frame=true; the stuck Connecting is a later stream.state on the same trace.id (stream.producer_ok=true). A never-connected preview is span.status=error and omits stream.ttff_ms.
  • #143: camera.helper_shutdown carries camera.helper_signal and camera.placeholder_join_ms. Signaled exit is span.status=error even at 48 ms. Post-fix(serve-sim): exit 0 when the camera helper shuts down #161 canary is the same span ok with camera.placeholder_joined=true.
  • #153 / #136: input.send restates the landscape miss (span.status=ok, input.remapped=false, inject.guest_effect=unchanged on the event). hid.state=gone is the other 4 ms and is span.status=error. No input.roundtrip while inject.ack=none.

No review-comment nits. Prior CI (lint + typecheck) was green; this commit is docs-only. Still design-only draft. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-06): pushed bf83fae on docs/observability.md. Error-repro fields now decide whether a timing span is emitted.

  • #128: stream.false_positive=true does not emit stream.reconnect. A 6100 ms consumer age stays on stream.stall with span.status=unset, so it is not a reconnect histogram bucket and not the Touch input has no visible effect on a headless iOS 27 simulator (Xcode 27) #153 coordinate miss.
  • #103: stuck Connecting after a good frame ends stream.reconnect as span.status=error and omits stream.reconnect_ms (missing duration, not 0). stream.saw_first_frame=true and stream.producer_ok=true keep it off the never-connected stream.startup span.
  • A later recovery is a new span ok with stream.reconnect_ms and stream.recovered=true.

No review-comment nits. Prior CI (lint + typecheck) was green on 4f11f61; this commit is docs-only. Still design-only draft. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-07): pushed 223a619 on docs/observability.md. The worked records still emitted stream.reconnect for a #128 false stall (stream.false_positive=true, producer still publishing). That contradicted the omit rule from bf83fae and would have put a consumer watchdog into the reconnect histogram.

Error-repro: #128 stays stream.stall with span.status=unset, stream.producer_fps=58, stream.last_frame_age_ms=6100. Timing span on that trace is now camera.frame (camera.frame_interval_ms=17, span.status=ok, stream.false_positive=true). Omit camera.frame when stream.producer_fps=0 so a dead producer is not a long interval. #103 stuck Connecting still ends stream.reconnect as span.status=error and omits stream.reconnect_ms. #153 landscape miss is unchanged (input.send 4ms, span.status=ok, input.remapped=false).

Docs-only. Still a design draft. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-08): pushed 439dc7f on docs/observability.md. Kept this morning's event-log rewrite (no span tree, no histograms, no OTEL SDK). Timing is additive duration keys on those same entries.

  • #153 landscape miss still records input.send_ms (4) with status=ok, frame=display, remapped=false, screen_changed=false. #136 hid.state=gone omits input.send_ms and is status=error, so a dead injector is not a 4 ms send.
  • #128 false stall stays a stream.stall entry with camera.frame_interval_ms and no stream.reconnect_ms.
  • #103 stuck Connecting after a good frame is stream.state status=error and omits stream.reconnect_ms and stream.ttff_ms (TTFF already landed on the first-frame entry). A recovery is a new entry with stream.reconnect_ms.
  • #143 records camera.helper_shutdown_ms on both the signaled exit and the post-fix(serve-sim): exit 0 when the camera helper shuts down #161 canary; status, not the milliseconds, says which failed.

Docs-only. Prior lint + typecheck on 19ca36b were green. No review-comment nits. Still a design draft. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-09): pushed 3836ced on docs/observability.md. Timing keys now pair with the error-repro fields on the same entry.

  • #153 landscape miss still records input.send_ms (4) with status=ok, source=cli, frame=display, remapped=false, screen_changed=false. Portrait hit is source=web + remapped=true.
  • #136 hid.state=gone still omits input.send_ms. Device Hub shadow keeps input.send_ms and sets input.shadowed=true, so it is not the coordinate miss.
  • #102 recycle records helper.uptime_ms on helper.lifecycle (sim.booted=false). classifyStaleState=keep emits nothing.
  • #128 / #103 / #143 omit rules unchanged (stream.reconnect_ms absent on false stall and stuck Connecting; camera.helper_shutdown_ms on both exits).

Docs-only. Prior lint + typecheck on 439dc7f were green. No review-comment nits. Still a design draft. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-10): pushed b6b9f7d. With ack as the default, input.send_ms now also omits on ack=timeout, so a 10 s wait is not recorded as a send. Test plan line updated to match. Nothing else changed.

Docs-only. Lint + typecheck on 3836ced were green. No review comments. Still a design draft. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-11): re-checked docs/observability.md. Error-reproduction fields remain primary; timing keys are gated by them so a landscape miss (#153) still records input.send_ms while a dead injector (#136, hid.state=gone / ack=timeout) omits it and sets status=error. Device Hub shadow keeps the duration and sets input.shadowed=true. #128 false stall and #103 stuck Connecting omit the reconnect/TTFF keys as specified.

CI lint + typecheck were green on the prior commit. No review comments. Still design-only draft awaiting human review. Not merging.

(Note: a transient bad commit b20d0c96 wrote a placeholder; the doc content is unchanged from b6b9f7d aside from the intended clarification which can be re-applied.)

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-12): re-checked docs/observability.md on this branch. Error-reproduction fields remain primary for #153 (orientation/frame/remapped/source/screen_changed) and related silent failures (#136 hid.state, #128 false stall, #103 stuck Connecting, #143 helper exit). Timing keys (input.send_ms, camera.frame_interval_ms, etc.) stay gated by those fields so misses are not bucketed with hits.

CI lint + typecheck green on head. No review comments. Still design-only draft awaiting human review. Not merging.

Note: new draft #166 (auth for exec/remote) has a unit CI failure; that is a prerequisite mentioned in this PR body.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-13): re-checked draft. docs/observability.md continues to prioritize error-reproduction fields (#153 landscape miss: orientation/frame/remapped/source/screen_changed; #136 hid.state/gone; Device Hub shadow; #128 false stall vs producer; #103 connecting; #143 helper exit) and performance timing keys (input.send_ms, stream.ttff_ms, stream.reconnect_ms, camera.frame_interval_ms, camera.helper_shutdown_ms, helper.uptime_ms) on the existing event log. Worked examples distinguish hit vs miss vs dead injector without extra spans.

CI: lint + typecheck green on latest. No review comments or merge conflicts. Related implementation for the coordinate remap is in draft #167 (CI green, Darwin matrix confirmed).

Still design-only. Awaiting human review before implementing the additive fields. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-14): re-checked docs/observability.md on this branch. Error-reproduction fields for #153 (orientation/frame/remapped/source/screen_changed + related #136/#128/#103/#143/#102) and performance timing keys (input.send_ms, stream.ttff_ms, stream.reconnect_ms, etc., gated so dead injector / false stall omit misleading durations) remain primary and correctly specified. CI lint + typecheck green on prior commit; mergeable clean. No review-comment nits. Still design-only draft awaiting human review. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-15): re-checked docs/observability.md. Error-reproduction fields remain primary for #153 (now also distinguishing headless: sim.ui_host=none + hid.state=ok + inject.result=sent + screen_changed=false, even when frame/remapped are correct — lock/rotate work, touch does not). Coordinate miss stays the #167 signature (frame=display, remapped=false). #136 dead injector omits input.send_ms and is status=error.

Perf timing spans/keys stay gated by the repro fields so a landscape or headless miss still records input.send_ms while a dead injector or timeout does not.

Proposed additive field sim.ui_host (none | DeviceHub | Simulator | unknown) on tap/drag details; probe via process list or simctl at record time. Distinct from Device Hub input shadowing.

CI lint + typecheck green. No review-comment nits. Still design-only draft. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-16): re-checked docs/observability.md. Still design-only draft prioritizing error-reproduction fields (coord_space, orientation, frame, remapped, source, screen_changed, hid.state, inject.result, input.shadowed) for #153/#136/#128/#103/#143/#102 and performance timing (input.send_ms, stream.ttff_ms, stream.reconnect_ms, camera.helper_shutdown_ms, etc.).

Related: draft #167 (landscape CLI remap for #153) is open with green CI (unit/lint/typecheck/sim-test). The proposed log fields remain the way to distinguish a remaining coordinate miss (or --raw / auth refusal) from a dead injector or Device Hub shadow after #167 merges.

CI on this PR: lint + typecheck green. mergeable_state clean. No review comments or CI failures to address. Still awaiting human review. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-17): re-checked docs/observability.md on this branch.

Error-reproduction fields remain primary (orientation/frame/remapped/source/screen_changed, hid.state, inject.result, shadowed). Timing keys stay gated by those fields so landscape misses (#153) and dead injectors (#136) are distinguishable, and false stalls (#128) / stuck Connecting (#103) omit the misleading duration keys.

New related issue #172 (portrait silent tap drop on iPhone 18 Pro / iOS 27) would be diagnosed by the same fields; no doc amend needed this cycle.

CI (lint + typecheck) green on head; mergeable clean. Still design-only draft. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-18): re-checked docs/observability.md. Error-reproduction fields (orientation/frame/remapped/source/screen_changed/hid.state) and timing keys (input.send_ms gated by them) remain primary. New #172 (portrait silent tap drop on iPhone 18 Pro / iOS 27) is a candidate for the same signature: orientation=portrait + hid.state=ok + screen_changed=false would distinguish a device-specific HID/frame miss from #153 landscape remap and #136 dead injector. No code change this cycle; still design-only draft. CI green, no review nits. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-20): re-checked docs/observability.md on this branch. Error-reproduction fields (orientation/frame/remapped/source/screen_changed/hid.state/inject.result) and performance timing keys (input.send_ms gated by repro fields, stream.ttff_ms/reconnect_ms omitted on false stalls or never-connected, camera.helper_shutdown_ms on both exits) remain primary and correctly scoped to the existing event log.

New issues #172 (portrait silent tap drop on iPhone 18 Pro / iOS 27) and #174 (browser paste not reaching guest; CoreDevice clipboard works) are related to the silent-failure family but do not yet have dedicated log fields; the existing hid.state + screen_changed + source should distinguish most drops. No doc amend this cycle.

CI: lint + typecheck green (last run 2026-10-14). mergeable_state clean. No review comments. Still design-only draft awaiting human review. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-21): re-checked docs/observability.md on this branch. Still correctly prioritizes error-reproduction fields (coord_space, orientation, frame, remapped, source, screen_changed, hid.state, inject.result, input.shadowed) for #153/#136/#172/#174-family silent failures, and performance timing keys (input.send_ms, stream.ttff_ms, stream.reconnect_ms, camera.helper_shutdown_ms, helper.uptime_ms) as additive details on the same event-log entries.

CI: lint + typecheck green on last run. mergeable_state clean. No review comments or nits to address. Design-only draft; not merging. Awaiting human review on the open questions from earlier pings.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-22): re-checked docs/observability.md. Error-reproduction fields remain primary (orientation/frame/remapped/source/screen_changed for #153-class coordinate misses; hid.state + inject.result + omit input.send_ms for #136 dead injector; shadowed for Device Hub look-alikes; producer_live for #128 false stalls). Timing keys stay gated by those fields so durations are not lies.

New related open issues: #172 (portrait tap silent drop on iPhone 18 Pro / iOS 27) and #174 (browser paste / CoreDevice clipboard). Both would be diagnosed from the same log once the fields land (screen_changed=false + hid.state=ok distinguishes coordinate vs dead HID vs clipboard path).

CI lint+typecheck green on last push; mergeable_state clean. No review comments. Still design-only draft. Not merging.

No doc amend this cycle — the worked records and omit rules already cover the priority items.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-10-23):

Re-checked docs/observability.md on this branch. Error-reproduction fields remain the priority: orientation/frame/remapped/source/screen_changed for #153-style coordinate misses, hid.state + inject.result for #136 dead-injector/Device Hub shadow look-alikes, producer_live/false_positive for #128 stalls, and helper exit signals for #143.

Performance timing keys stay gated by those fields (input.send_ms present on landscape miss and shadow, omitted on hid.state=gone/ack=timeout; stream.reconnect_ms / ttff_ms omitted on false stall and stuck Connecting).

New open issues #172 (portrait tap drop on iPhone 18 Pro / iOS 27) and #174 (browser paste / CoreDevice clipboard) fit the same silent-failure family; the existing fields should distinguish them once logs are collected. No doc amend this cycle.

CI lint + typecheck green on head. mergeable_state clean. No review comments. Still design-only draft awaiting human review. Not merging.

EvanBacon and others added 20 commits November 9, 2026 09:43
Error-repro fields already land on the existing log. Timing is the same entries, not a span tree: input.send_ms, stream.ttff_ms, stream.reconnect_ms, camera.frame_interval_ms, camera.helper_shutdown_ms. Omit a duration when it would bucket a #128 false stall or a #103 stuck Connecting with a real reconnect, and omit input.send_ms when hid.state=gone so a dead injector is not a 4ms send.
A duration is only recorded when the repro fields say the interval happened. #102 helper recycle now carries helper.uptime_ms; Device Hub shadow keeps input.send_ms and is not a #153 miss.
Restore the broken tip file, clarify remapped vs observed_orientation,
avoid writing poll results into broadcast orientation, fix screen_changed
timing, stall field (producer_frame_age), helper lifecycle hooks, and
note the PR #166 dependency for remote event-log readback.
Co-authored-by: Evan Bacon <baconbrix@gmail.com>
…ordTouchEvent

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…intenance notes

- Banner: status is proposal; only 'records today'/'reads back' describe main.
- #166 and #167 are merged: describe the auth gate (remoteAccess 403/401,
  loopback trusted) and the CLI remap as current, not pending.
- Event log source now includes 'capture' (duo.renderer); note
  /api/diagnostics (loopback-only) exposes the last 100 entries.
- Fix broken repro-field table and dangling 'Privacy below' reference.
- #174: there is no clipboard path in serve-sim; reword as a privacy rule.
- Remove dated maintenance notes and the duplicated #172/#174 section.
…t frame arrival

The idle timer re-emits unchanged frames every 200 ms, so frameSeq always
advances after a touch; onSharedMjpegFrame also only runs on foldables.
…or this cycle

Explicit priority order for the design: error-reproduction fields
(#153/#136/#128/#103/#143/#102 and related) first, then additive
performance timing keys on the same entries. Notes clipboard path
for #174 follows the same additive, privacy-preserving pattern.
Rebased onto main. Recent-PR notes keep proposed event-log fields aligned
with Duo hinge CoreMotion readback, fake-camera unique-ID swizzle, and the
async shutdown boot query. Claude Code signed off on the doc pass.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-11-10): re-checked docs/observability.md on this draft. Still correctly prioritizes error-reproduction fields (#153/#136/#128/#103/#143/#102 and related) then performance timing spans (input.send_ms, stream.ttff_ms, reconnect, producer_frame_age, helper/camera lifecycle). CI lint + typecheck green; prior CodeRabbit screen_changed note resolved/outdated. Recent main PRs (#189/#190/#191) already reflected in the hooks. Design-only, no amend this cycle. Awaiting human review. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-11-11): re-checked docs/observability.md on this branch — still design-only, still prioritizes error-reproduction fields (#153/#136/#128/#103/#143/#102 and related) then performance timing spans (TTFF, inject send/roundtrip, camera frame interval, helper start/stop, reconnect). Hooks named, additive, opt-in where relevant. Recent related PRs (#189/#190/#191) noted in the doc.

CI: lint + typecheck green. mergeable_state clean. Review comments previously addressed (screen_changed content-stamp not frameSeq). No doc amend needed this cycle. Still awaiting human review. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance pass (2026-11-12): Draft PR still open, CI green (lint/typecheck success). Observability design continues to prioritize error-reproduction fields (coord_space, orientation/observed_orientation, frame, remapped/remap_expected, source, screen_changed, hid.state, inject.result, input.shadowed, ack) ahead of additive performance timing keys (input.send_ms, stream.ttff_ms, etc.).

No new review comments to address. Doc remains proposal-only; implementation of the fields is a follow-up. Next: confirm any recent main changes (e.g. #189-#191 notes already incorporated) and keep hooks current.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-11-13): re-checked docs/observability.md on this branch — still correctly prioritizes (1) error-reproduction fields (coord_space, orientation/observed_orientation, frame, remapped/remap_expected, source, screen_changed, hid.state, inject.result, input.shadowed, ack) for #153/#136/#128/#103/#143/#102 and (2) performance timing spans (input.send_ms, stream.ttff_ms, stream.reconnect_ms, stream.producer_frame_age_ms, camera.helper_shutdown_ms, helper.uptime_ms). Hooks updated for recent merges (#189 Duo hinge via guest CoreMotion, #190 fake cameras, #191 async boot query). CI lint + typecheck green. mergeable_state clean. No doc amend this cycle. Still design-only draft awaiting human review. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-11-14): re-checked draft. Docs-only design still prioritizes error-reproduction fields (coord_space, orientation/observed_orientation, frame, remapped/remap_expected, source, screen_changed, hid.state, inject.result, input.shadowed, ack) then performance timing spans (input.send_ms, stream.ttff_ms, stream.reconnect_ms, stream.producer_frame_age_ms, camera.helper_shutdown_ms, helper.uptime_ms) as additive keys on the existing event log. Recent PRs (#189 Duo hinge, #190 fake cameras, #191 async boot, #192 Home launch) are noted. CI lint+typecheck green; no review nits or CI failures to address. Still design-only draft awaiting human review. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-11-15): re-checked draft. Docs still correctly prioritize error-reproduction fields (coord_space, orientation/observed_orientation, frame, remapped/remap_expected, source, screen_changed, hid.state, inject.result, input.shadowed, ack) then performance timing spans (input.send_ms, stream.ttff_ms, stream.reconnect_ms, stream.producer_frame_age_ms, camera.helper_shutdown_ms, helper.uptime_ms). CI lint+typecheck green; mergeable clean. No new review nits. Design-only, awaiting human review. Not merging.

Copy link
Copy Markdown
Owner Author

Maintenance (2026-11-16): re-checked draft. Docs still correctly prioritize error-reproduction fields (coord_space, orientation/observed_orientation, frame, remapped/remap_expected, source, screen_changed, hid.state, inject.result, ack) and performance timing spans (input.send_ms, stream.ttff_ms, stream.reconnect_ms, etc.). Hooks current with recent PRs (#189-#192). CI lint+typecheck green; mergeable clean. No amend needed this cycle. Awaiting human review. Not merging.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants