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

docs/internals/mobile-development.md +38 −6
docs/internals/performance-regressions.md +34 −0
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
17	parent scope also closes late arrivals, preventing interrupted startup or runtime	17	parent scope also closes late arrivals, preventing interrupted startup or runtime
18	replacement from leaving a WebSocket alive outside the new registry.	18	replacement from leaving a WebSocket alive outside the new registry.
19		19
20	The [Uniwind patch](../../patches/uniwind@1.11.0.patch) still compiles CSS on Metro	20	Environment supervisor scopes are children of the connection registry scope.
21	updates so newly used classes are discovered. It skips global style invalidation	21	The registry's per-environment map supports targeted shutdown, but it cannot be
22	only when the generated stylesheet and theme list are unchanged. Skipping compilation	22	the sole owner: a supervisor created after that map's finalizer has run must
23	would lose new classes; invalidating every consumer for unchanged output makes an	23	still inherit the closed parent scope. Otherwise interrupted startup or runtime
24	ordinary component edit refresh the whole app. The fingerprint is recorded only	24	replacement can leave a session and WebSocket alive outside the current registry.
25	after initialization succeeds.	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
50		50
51	The focused regression coverage lives in `OrchestrationEventStore.sequence.test.ts`,	51	The focused regression coverage lives in `OrchestrationEventStore.sequence.test.ts`,
52	`ProjectionRecovery.test.ts`, and the provider runtime recovery tests under `apps/server/src`.	52	`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
69		69
70	Codex thread resume requests exclude historical turns when only the thread identity and update time	70	Codex thread resume requests exclude historical turns when only the thread identity and update time
71	are needed. The adapter decodes those metadata fields without loading a duplicate transcript.	71	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.
72		75
73	## Registry and routing	76	## Registry and routing
74		77