You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 49361de
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/adr/0024-screen-recording-provable-signal.md
+18-99Lines changed: 18 additions & 99 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -68,7 +68,7 @@ Six rules make the table operational:
68
68
A collection, validation, or commit failure preserves the material that a retry needs.
69
69
Only session teardown and failed-start rollback invoke forced cleanup.
70
70
Forced cleanup is never inferred from "finish threw".
71
-
The mechanism is in the shared coordinator (`capture-kit/durable-capture/transitions.ts`).
71
+
The mechanism is in the shared coordinator (the durable-capturetransitions owner).
72
72
But each kind must earn its scope.
73
73
Each of app-log, audio-probe, and perf-capture gets its own failed-finish test that proves what its retry needs.
74
74
A kind whose retry needs nothing keeps its current disposal explicitly.
@@ -79,74 +79,13 @@ the reduction of the Android device marker to marker-only content (2.6), and `--
79
79
80
80
## 1. Context
81
81
82
-
`record start` / `record stop` is one command family.
83
-
But each of its fixes in the last three months touched 10 to 35 files (#2447, #2457, #2487, #2534, #2564, #2565, #2566).
84
-
The subsystem has ~10,150 production lines and ~19,000 test lines across these areas:
85
-
86
-
-`contracts`
87
-
-`capture-kit`
88
-
-`host-kit`
89
-
- four platform packages
90
-
- nine `src/platform-runtime-screen-recording-*` hosts
91
-
- eight daemon modules
92
-
93
-
Nine user-facing record bugs were filed since July 2026.
94
-
In five of them, the ownership machinery refused because of its own uncertainty:
95
-
96
-
| Issue | Refusal | Native cause? |
97
-
| --- | --- | --- |
98
-
|#2549|`ps` 1 s probe timed out under load → `cleanup-pending`, session wedged | no |
99
-
|#2550| device manifest `deviceId` ≠ current serial → "recovery evidence already exists" | no |
100
-
|#2476| reused pid → "completed evidence cannot be safely retired" | no |
101
-
|#2281| client window expired → no CLI path to the finished export | no |
102
-
|#1117| daemon lost session state → "no active recording" | no |
103
-
|#2170| CoreSimulator host lock after `SIGKILL`| yes |
104
-
|#1651| validator rejected a static single-frame clip; `moov` patched in place | yes |
105
-
|#615|`screenrecord` 180 s cap | yes |
106
-
|#2551| clip ends at the last screen change | yes |
107
-
108
-
Three facts make the fail-closed contract cost more than it protects:
109
-
110
-
-**Reattachment is already dead on four of five backends.**
111
-
`reattachAppleRecording` and the HarmonyOS and web operations return `unreattachable` unconditionally.
112
-
After daemon loss, `finishRecoveredDurableCapture` runs descriptor cleanup and then **throws**.
113
-
It throws even when cleanup succeeded and the finalized MP4 is on disk.
114
-
Only Android can answer `active` or `completed`.
115
-
Ten ownership and outcome enums express distinctions that four backends cannot make.
116
-
-**Daemon loss mid-recording is rare and already mitigated.**
117
-
An active recording holds off the idle reaper.
118
-
The startup reaper already sends `SIGINT` to orphaned `simctl recordVideo` children from `owned-processes.json`.
119
-
The local daemon logs of the maintainer hold zero recording reattachments.
120
-
All the reported failures are ordinary same-daemon stops.
121
-
-**A failed export destroys its own retry.**
122
-
`finishDurableCaptureHandle` calls `handle.forceCleanup()` when `finish` throws (`transitions.ts`, `compensateFailedFinish`).
123
-
On Android, that reaches `cleanupVerifiedAndroidEvidence`, which removes the remote artifact and marker.
124
-
A pull that fails once under load leaves nothing to pull a second time.
125
-
126
-
`#2551` was reproduced with raw `adb` on an API 36 emulator.
127
-
`SIGINT` at +16 s produced a clip whose last frame is at +12.6 s, the last screen change.
128
-
Changes after the last input were captured.
129
-
The clip length comes from the change-driven encoding of `screenrecord`, not from our stop path.
130
-
Disclosure (PR #2566) is the whole fix.
82
+
A playable export and a stopped recorder are independent facts. The earlier recovery contract could refuse a usable export when ownership was uncertain. A failed export could also destroy the material that a retry needed. Platform backends need different identity and stop procedures, while the coordinator needs one guarded stop-and-export path.
Commands and recovery use one recording coordinator. The coordinator owns the manifest and calls the platform backend and shared finalizer. Native orphan markers cover incomplete starts before a manifest exists.
150
89
151
90
The coordinator reuses the existing manifest store, fence, pending-transfer guard, and completed replay (PR #2534).
152
91
There is no new framework.
@@ -237,7 +176,7 @@ Native-path disposition is complete only after fenced retirement succeeds or the
237
176
A path marked retirable still needs its manifest until retirement completes.
238
177
239
178
**Checkpoints mark durable, valid artifacts; they never mark attempts.**
240
-
`collected` is recorded only after the collected copy passes the playability sniff (`ftyp` + `moov`, the existing check in `video.ts`).
179
+
`collected` is recorded only after the collected copy passes the playability sniff (`ftyp` + `moov`, the existing video check).
241
180
Thus a pull of a not-yet-finalized MP4 leaves no checkpoint.
242
181
`finalized` is recorded after the export is written.
243
182
Step 1 records its observation.
@@ -249,7 +188,7 @@ A retry resumes at the first missing checkpoint, after it re-runs step 1 when it
249
188
The collected copy is preserved until step 4 commits.
250
189
The finalizer reads it and writes the export beside it.
251
190
Thus a retry after a failed commit re-runs nothing that changes the video.
252
-
Today, `exportProcessedVideo` applies the touch overlay **in place** (`overlay.ts` renames the processed file over its input; PR #2586 removed start trimming).
191
+
Today, `exportProcessedVideo` applies the touch overlay **in place** (the overlay owner renames the processed file over its input; PR #2586 removed start trimming).
253
192
That is why the copy is required: without it, a retry after a commit failure would burn the overlay twice.
1. If the session already holds a live handle, refuse (`recording already in progress`).
284
223
2. If the recording manifest of the device is `open` and **actively owned**, refuse.
285
-
Actively owned means: the owner named in the manifest is alive by the existing owner-identity check (`host-kit/internal/owner-identity.ts`), and that owner holds the fence.
224
+
Actively owned means: the owner named in the manifest is alive by the existing host-kitowner-identity check, and that owner holds the fence.
286
225
This is the ADR 0019 rule, and it is unchanged.
287
226
3. Otherwise, the manifest is abandoned or completed.
288
227
Hand it to recovery (2.5) under the ownership guard **before** launch.
@@ -368,7 +307,7 @@ Section 5 currently has these requirements:
368
307
369
308
- Every durable facet exposes `reattach` and `cleanup`.
370
309
- Uncertain cleanup stays `cleanup-pending`.
371
-
- When finish throws, forced cleanup runs (in `transitions.ts`).
310
+
- When finish throws, forced cleanup runs in the durable-capture transitions owner.
372
311
373
312
The proposed amendment:
374
313
*Screen recording would be a **stop-and-collect** resource.
@@ -389,15 +328,15 @@ This step comes after 2.1–2.7, and 2.1–2.7 do not require it.
389
328
390
329
## 3. Cross-platform matrix
391
330
392
-
| Backend |`stop` from a live handle |`stop` from a descriptor (recovery) |`collect`| Today after daemon loss |
393
-
| --- | --- | --- | --- | --- |
394
-
| iOS / tvOS simulator |`ChildProcess.kill` tiers; descendant markers probed before pid signals | probe markers; signal on ours; `unconfirmed` if the host is silent; `lost` on mismatch | local copy of the `simctl` output file; native file retained until the writer is proven gone | cleanup signals, then **throws**|
395
-
| iOS device (CoreDevice), macOS | runner stop RPC bound to `runnerSessionId`| same RPC if the runner session matches; `lost` if the runner restarted | device copy (iOS); local copy of the runner's output file (macOS) | cleanup stops the runner, **never retrieves**, throws |
396
-
| Android | probe `/proc`, then `kill -2` → `-9`; `unconfirmed` when `/proc` is unreadable | same, from the pid triple in the descriptor |`adb pull` of every chunk, playability sniff | reattach through the device manifest; five ownership states |
397
-
| HarmonyOS | one `aa start` toggle, tracked by the handle |**no signal**; `mediatool query` by file name; `unconfirmed` if found, `lost` if not | stage + `hdc file recv`|`cleanup-pending`, manual |
398
-
| Web | provider `record stop` on the session browser | stop if the browser is alive, else `lost`| local copy of the WebM; native file retained while the browser is not proven gone |`cleanup-pending`, manual |
399
-
| Limrun (iOS, Android) | provider stop RPC on the live session; the served download URL is memoized so a stop is never repeated |**no signal**: the recording lives and dies with the instance; `unreattachable`| HTTP download of the served MP4 to the output path, bounded by a deadline that ends inside the `record` request window (60 s of its 90 s envelope) and not cancellable; retriable from the memoized URL while the instance lives |`cleanup-pending`, manual; the instance (and its file) is deleted on lease release |
| Backend |`stop` from a live handle |`stop` from a descriptor (recovery) |`collect`|
332
+
| --- | --- | --- | --- |
333
+
| iOS / tvOS simulator |`ChildProcess.kill` tiers; descendant markers probed before pid signals | probe markers; signal on ours; `unconfirmed` if the host is silent; `lost` on mismatch | local copy of the `simctl` output file; native file retained until the writer is proven gone |
334
+
| iOS device (CoreDevice), macOS | runner stop RPC bound to `runnerSessionId`| same RPC if the runner session matches; `lost` if the runner restarted | device copy (iOS); local copy of the runner's output file (macOS) |
335
+
| Android | probe `/proc`, then `kill -2` → `-9`; `unconfirmed` when `/proc` is unreadable | same, from the pid triple in the descriptor |`adb pull` of every chunk, playability sniff |
336
+
| HarmonyOS | one `aa start` toggle, tracked by the handle |**no signal**; `mediatool query` by file name; `unconfirmed` if found, `lost` if not | stage + `hdc file recv`|
337
+
| Web | provider `record stop` on the session browser | stop if the browser is alive, else `lost`| local copy of the WebM; native file retained while the browser is not proven gone |
338
+
| Limrun (iOS, Android) | provider stop RPC on the live session; the served download URL is memoized so a stop is never repeated |**no signal**: the recording lives and dies with the instance; `unreattachable`| HTTP download of the served MP4 to the output path, bounded by a deadline that ends inside the `record` request window (60 s of its 90 s envelope) and not cancellable; retriable from the memoized URL while the instance lives |
|`record stop` paths | 2 (live; recovery that throws on 4 backends) | 1 | 1 |
559
-
| Files on an Android stop path | 9 |~7 |~6 |
560
-
561
-
The reduction is modest, because the device marker stays, the root host files stay, and rotation stays below API 34.
562
-
What this design buys is one path, one store, three enums, and no refusal that a silent host or a reused pid can produce.
563
-
A later, separate ADR may fold the nine root host files into per-platform transports once the layering gates (R16) are re-cut.
564
-
That is shape, not policy, and no row of the table in section 1 needs it.
483
+
The proposed end state has one stop path and one lifecycle store. Rotation remains below API 34. A later, separate ADR may fold the root host files into per-platform transports once the R16 layering gates are re-cut.
565
484
566
485
Deletion test:
567
486
568
487
-`screenRecordingReattach`, `screenRecordingCleanup`, `cleanup-pending` for recording, and `ScreenRecordingAdmissionLedger` no longer exist in production.
569
-
-`transitions.ts` has no cleanup-on-failed-finish path.
488
+
-The durable-capture transitions owner has no cleanup-on-failed-finish path.
570
489
- Every situation in the rules table has a passing test on every backend where it applies.
0 commit comments