History

fix(orchestration): stabilize Codex turn mapping and settlement

- Preserve Codex turn identity while suppressing duplicate diff notifications - Optimize settlement projections and isolate thread visit handling - Add concurrency and regression coverage across server and mobile

Julius Marminge committed 2 months ago

Commit 6502e221 parent 25d2531167 files · +189949 −140Browse files

Showing the changes to docs (3 of 167 files). Show all

Unified · Split

3 files
  1. docs/internals/mobile-development.md +38 −6
  2. docs/internals/performance-regressions.md +34 −0
  3. docs/internals/providers.md +3 −0
docs/internals/mobile-development.md+38−6
@@ -17,9 +17,41 @@ shutdown, but a supervisor created after its cleanup runs would escape it. A clo · 16 unmodified lines
1717 parent scope also closes late arrivals, preventing interrupted startup or runtime
1818 replacement from leaving a WebSocket alive outside the new registry.
1919
20−The [Uniwind patch](../../patches/uniwind@1.11.0.patch) still compiles CSS on Metro
21−updates so newly used classes are discovered. It skips global style invalidation
22−only when the generated stylesheet and theme list are unchanged. Skipping compilation
23−would lose new classes; invalidating every consumer for unchanged output makes an
24−ordinary component edit refresh the whole app. The fingerprint is recorded only
25−after initialization succeeds.
20+Environment supervisor scopes are children of the connection registry scope.
21+The registry's per-environment map supports targeted shutdown, but it cannot be
22+the sole owner: a supervisor created after that map's finalizer has run must
23+still inherit the closed parent scope. Otherwise interrupted startup or runtime
24+replacement can leave a session and WebSocket alive outside the current registry.
25+
26+The compact Home list owns its minute-based presentation clock in a focus effect.
27+Blur clears the interval without a render-driving focus subscription; focus
28+refreshes the clock immediately. Other prop or state changes can still render
29+the hidden list. Exact snooze-expiry timers remain active, and the visible iPad
30+sidebar keeps its own minute updates.
31+
32+Connection and runtime projections are shared per environment. Thread selection
33+consumers should read those atoms instead of repeatedly parsing the same socket
34+URL or constructing new connection objects during each render.
35+
36+The Uniwind dependency patch still recompiles CSS on Metro updates so newly used
37+classes are discovered. It fingerprints the generated native stylesheet and
38+theme list, then skips development-only global invalidation when that output is
39+unchanged. A changed stylesheet or theme list still resets the style caches and
40+notifies subscribers. The digest is committed only after initialization succeeds.
41+Web and production retain their existing initialization behavior.
42+
43+After installing or changing the Uniwind patch, restart Metro once with
44+`vp run dev:client:reset` from `apps/mobile`. pnpm gives patched packages new
45+filesystem paths, and cached transforms can otherwise retain references to the
46+previous package. Ordinary development starts should retain the transform cache.
47+
48+The expo-notifications patch protects `NotificationCenterManager`'s delegate and pending-response
49+arrays with a lock. React runtimes can register and remove delegates concurrently during reloads
50+or native scene startup. Delivery takes a snapshot under the lock and invokes delegates after
51+releasing it, allowing callbacks to register other delegates. Pending-response replay removes
52+only the responses it saw so a response arriving during a callback remains available.
53+
54+Changes to this native patch require a fresh dependency install, CocoaPods refresh, and an iOS
55+rebuild. `vp test run apps/mobile/scripts/notification-center-manager.test.ts` compiles the
56+installed dependency with a small native harness on macOS and runs concurrent registration and
57+delivery checks under ThreadSanitizer without launching a simulator.
docs/internals/performance-regressions.md+34−0
@@ -50,3 +50,37 @@ it must not collect the entire event log before projecting it. · 49 unmodified lines
5050
5151 The focused regression coverage lives in `OrchestrationEventStore.sequence.test.ts`,
5252 `ProjectionRecovery.test.ts`, and the provider runtime recovery tests under `apps/server/src`.
53+
54+## Background work and navigation
55+
56+The settlement worker reads active, unpinned threads without explicit settlement overrides from
57+`ProjectionStore.getSettlementCandidates`. It reads the latest run and user-message timestamps,
58+rejects active runs and pending requests, and checks background work using the same derivation as
59+the shell. It does not load archived histories, fork ancestry, transcript counts, or provider
60+sessions. The orchestrator still validates the current thread before applying settlement.
61+
62+Read receipts use `ProjectionStore.getThread` to load only canonical thread metadata. A visit
63+advances `lastVisitedAt` monotonically without changing `updatedAt` or decoding history. Shell
64+queries use a covering thread/run index for item counts and a partial index for nonterminal
65+background items, including idle items. Latest user-message reads use an index ordered by update
66+time.
67+
68+Command palette results keep live VCS and linked pull-request queries leased to the visible
69+viewport, including a small overscan region. Cached badges remain available while leases are
70+released. Local Git status reads skip divergence calculations; callers that need ahead/behind
71+counts keep the full status path. Cached fetch failures share the existing backoff and log only
72+the actual failed attempt. Unchanged desktop environment bootstrap reads retain their array
73+identity so polling does not invalidate subscribers.
74+
75+Relay awareness queues one pending publication per thread and retains a follow-up when the thread
76+changes during a send. Transcript deltas and tool output do not enqueue awareness work. Run,
77+request, and relevant thread metadata events do. Configuration is checked before shell reads, and
78+connection changes invalidate published identities so relinking can publish unchanged state.
79+Failed publications retry the latest state up to five times with exponential delays. A new
80+relevant event resets the budget; successful publication, disabling, or unlinking cancels retries.
81+After the budget is exhausted, publication waits for another relevant event instead of generating
82+continuous traffic during an outage.
83+
84+Focused coverage: `ProjectionSettlement.test.ts`, `ThreadSettlementService.test.ts`,
85+`runtimeLayer.test.ts`, `AgentAwarenessRelay.test.ts`, `GitVcsDriverCore.test.ts`,
86+`ThreadStatusIndicators.subscriptions.test.tsx`, and `desktopLocal.test.ts`.
docs/internals/providers.md+3−0
@@ -69,6 +69,9 @@ write a diagnostic record. These limits apply to logging; provider event handlin · 68 unmodified lines
6969
7070 Codex thread resume requests exclude historical turns when only the thread identity and update time
7171 are needed. The adapter decodes those metadata fields without loading a duplicate transcript.
72+Its initialization capabilities opt out of `turn/diff/updated`: T3 derives diffs from checkpoints
73+and does not consume the provider's cumulative diff notifications. The logger also filters those
74+notifications before traversal when an older provider still sends them.
7275
7376 ## Registry and routing
7477