bitvid/docs/agents/prompts/client-reliability.md

Area: Client reliability (client-reliability)

Current assignment: client-reliability-8 — active URL-media cancellation

Implementation routing after independent evidence

Dispatch independently ran nine scratch modes: disposed/fifo new cancellation assertions fail naturally after cleanup, seven shared/cross/legacy/rejoin/timeout/error/replacement controls pass. Final-owner media retains1source/3listeners/1timer/1slot/unsettled promise; source-backed Stage3 and owner continuation require releasing obsolete active work. Minimal implementation now authorized ONLY js/ui/urlHealthController.js (retainUrlProbe final-owner cancellation hook, record cancelled state, active media settle/cleanup) plus tests/url-health-lifecycle.test.mjs and unique integrity/spec/evidence notes. Existing observer/cache/HEAD/HLS/torrent/app modules remain read-only. Supersedes investigation-only prohibition for this boundary.

Use existing cancellation paths to settle null, suppress cache/mirrors/stale badge writes, release slot and advance FIFO once. Mark cancelled record unavailable synchronously for same-turn rejoin; old settlement must never remove/paint/cache over replacement. Test both immediate same-turn rejoin and rejoin after microtask, sharing before final release, cross-controller sharing, ownerless legacy consumers, queued competition/FIFO, replacement identity, late success/error/timeout callbacks and cleanup idempotence. Clean src/listeners/timer and pause/load boundary; do not force exit or wait for original timeout. Preserve live-owner healthy/offline caching and normal timeout/retry, shared work, slot cap/FIFO and previous queued/mirror guards.

Explicit spec correction permitted for active-disposed success/offline-cache and disposed-timeout/rejoin expectations ONLY: the old queued-only contract intentionally allowed completed work after disposal; new owner instruction plus Stage3 requires immediate active media cancellation once final registered owner leaves. Replace these with equally strict resource cleanup/null settlement/no cache/no mirrors/no stale writes/fresh replacement assertions; keep separate live-owner success/error/timeout controls. Record Test Integrity Note (spec_correction and new_tests, exact old→new contract/spec source, any did_relax explanation honest) and unique spec change note; do not silently delete scenarios. Every new scenario needs a restored mutant that fails naturally. Mutants must reject disabled cancellation, retained source/listeners/timer, cache-on-cancel, lost shared owner, stale inflight deletion, FIFO disruption as applicable. Report surviving mutants instead of weakening assertions.

Focused real lifecycle/adjacent URL/controller/observer checks and lint now. No browser/full/build yet; request slot when focused results/mutants/lint and merged-tree candidate are ready. Normal unchanged full gate and durable landing/ancestry required before closure. Send READY with files/counts/mutants/contract diff and unverified scopes. No wider Stage3 claim; actual browser/network/HEAD/HLS/torrent remain unverified. Dispatch will coordinate final validation and preview.

Owner exact continuation recorded in PROGRAM supersedes the review idle hold only for this bounded slice. Read RULE-CHANGES newest first, PROGRAM, KNOWN_ISSUES, performance-efficiency-plan Stage3 and test-integrity before work. Claim item8 on integrated current unstable after this coordination commit lands; merge, never rebase. First investigate actual URL observer→controller active media last-owner disposal with controlled external IO. No product or committed-test edits yet; scratch reproduction and unique evidence only. No full/build/browser until explicit slot grant; cheap focused checks allowed.

Measure resource/listener/timer retention, promise settlement, active slots and queued FIFO progress, inflight/cache identity, stale badge writes before/after disposal and controlled completion/timeout. Compare shared visible live owner, cross-controller shared cache if applicable, fresh owner/rejoin before/after cancellation, later same-source request, and legacy ownerless callbacks. Do not treat missing AbortSignal alone as proof; use real ownership entrypoints, actual media cleanup and controlled IO. Report current HEAD, exact commands/counts, baseline and controls, proposed smallest fix boundary and which existing assertions would change. Existing active-success/offline-cache/timeout expectations protect previous queued-only scope; preserve tests now and propose explicit contract correction/integrity note rather than silently weakening them. Cancellation must eventually avoid negative cache, stale UI and deleting a replacement inflight record; live shared owners must continue to get results. Preserve cache, concurrency, FIFO, callback compatibility and existing queued cancellation/orphan mirror guards.

Start URL-media only. HEAD/HLS/torrent read-only context if necessary; report evidence before broadening. No app.js/services/nostr/kit/runner/config/styling/scheduler/external/cloud/signers/push/deploy/spend. Storage and QA remain idle unless separately assigned. Send read/next-action then reproduction/controls; await explicit minimal-fix routing after dispatch independently confirms. Done for investigation = measured current behavior and scoped proposal, not active-abort completion. Dispatch owns preview refresh after verified product landing.

Archived completed assignment: client-reliability-7 — cold feed live notification blocker

QA actual-app passive reproduction at386cc60e: fresh Trending/cache0, local relay delivers3 valid signed VIDEO events+EOSE; raw/all/active/appvideo maps3,actual filtered3 and every access/include true,whitelist/lockdown false. Connected visible view remains current0/rendered0/signatureEMPTY/DOM0 after15s;metadata reasoncache. Service emits videos:cache3 then videos:updated(subscription3),but app refresh owner is onVideos callback. Source loadVideos cache/optimistic paths call onVideos;live subscription branch does not. This is a demonstrated local-review blocker,not optional work.

Temporary item ownership: ONLY js/services/nostrService.js loadVideos live-subscription notification path plus minimal service-owned current-consumer state/subscription-clear lifecycle if needed to prevent stale consumer delivery;new focused regression (prefer tests/nostr-service-live-feed-notification.test.mjs),unique integrity/evidence/backlog. Read app/feed/bootstrap and existing tests;do not edit them or sharedTODO without routing. No app.js,cache/filter policy,signer/protocol,runner/config/kit/styling changes. Current service area exclusion is overridden only for this method/item.

Merge unstable non-destructively,claimitem7,read currentrules/KNOWN_ISSUES/test-integrity/localNIP/schema docs. Before edits reproduce actual service coldcache→controlled subscribeVideos callback→actualonVideos consumer notification absent;prove cache0 theneligible updates/deletion callbacks,not event-string assertions. Preserve filtered full-list ordering,deleted updates,tombstone removal,existing videos:updated payload and persistence,callbackthrow isolation/no event loss,optimistic/cache semantics. Reused subscription must notify latest consumer after subsequent load/feed switch; forceFetch/clear must not let late obsolete callbacks notify old or replacement consumers. Include event-only consumer compatibility; do not blindly close over first onVideos. After natural failing regression,implement smallest method-only callback delivery fix and restored failing mutants. Retain no product-policy change or forced refresh substitute.

Cheap focused tests and lint now;no browser/full/build until slot grant. QA owns actual-app execution and will verify cold feed plus original core/mobile baseline after durable fix/preview rebuild. Send reproduction/controls/files before widening;ready event with focused counts/mutants/lint. One unchanged normal full gate can be authoritative after merged focused/lint;avoid duplicate full solely for logs. Normal commit/merge/queue/ancestry/closure rules apply. No external operations/newoptional tasks;idle once local-review blocker is closed.

Archived completed assignment: client-reliability-6 — retain actual history wiring regression

Investigation complete:actual profile→real renderer→DOM remove→real controller/service works locally and through fake synced publish/read. Historical no-op override resurrects removal while existing profile27 tests still pass (worker evidence). Dispatch independently ran local/synced actual wiring exit0 and historical-noop local exit1 after cleanup. No current product failure established.

Test-only retention now authorized: own new tests/profile-history-removal-wiring.test.mjs plus unique integrity/evidence/backlog. No product or existing profile-suite edits. Use actual profile config/factory,renderer,DOM remove,controller/local service;fake only persistence/publish IO and metadata boundaries. Retain local delete+clear+renderer recreation,zero local publishes;synced remove reduced-list replace:true/actor/real recreation through fake publish/read;separate assertions catch historical no-op. Explicitly distinguish any not-yet-proven synced-clear path and report real failure before product routing. Fixture cleanup restores globals/app/module state and blocks network/signers/relays. No source-string or merely config-presence test.

New scenarios need restored failing mutants (historical no-op must kill real wiring cases);no sleeps/retries/expectation weakening. Relevant focused lower-layer/profile suites and lint;request full normal slot after ready. QA now gets bounded actual-app mobile browser baseline after old QA gate ends,so no browser/full/build until dispatch grant. Commit item6,merge verified unstable,normal unchanged full gate/durable ancestry before close. Metadata can be claimed now landed. No app/history service/cache/product scope or new feature authority. Send ready/blocker/landing/final events.

Archived completed assignment: client-reliability-5 — prevent orphaned mirror continuation

Investigation at0c1dd7e8 found a narrow defect, independently reproduced by dispatch at47953970 (administrative roster only): after last-owner disposal during active primary media, primary error starts1 fresh mirror HEAD(expected0). /tmp/bitvid-dispatch-5-active-url.mjs mirror-disposed --expect-no-obsolete-head exits1 after cleanup/retry; mirror-shared control exits0/healthy,resources0/slots0. Bounded active retention/success caching itself is intentional and not a defect.

Implement controller-only lifecycle guard before next mirror request: temporary ownership js/ui/urlHealthController.js, focused tests/url-health-lifecycle.test.mjs and your unique integrity/evidence notes. Existing ownership hook is sufficient. Do not change observer/app/shared cache/HEAD-media-HLS-torrent abort,TTLs/limits/mirror order. Ensure cancellation settles with explicit cancelled outcome, no negative cache, no stale UI or newer inflight deletion. Preserve shared/rejoining live owners and ordered mirrors, active healthy cache and normal timeout/retry behavior. No competing writers: storage-cors owns only storage helper; playback-qa product read-only.

Read current rules/test integrity before edits; retain actual observer/controller/cache regression with controlled external IO and mock clock, no sleeps/retries. Test disposed active failure starts0 mirror HEAD; shared/rejoin owner continues; active success cache,timeout/retry and inflight identity preserved. Every new scenario needs reverted failing mutant. Relevant focused tests/lint/build; coordinate full suite/normal queue through dispatch before expensive run (roster full gate currently underway). QA initially owns shared browser: do not launch browser until dispatch allocates it; request availability and use only your own server/port. No blanket prior-suite reruns for administrative edits. Commit item5, merge unstable (never rebase), unchanged gate/durable ancestry before close. CLI/agent/lander launch must unset inherited NODE_TEST_CONTEXT test transport (operational environment correction, no assertion/gate change). Send blocker/product landing/final events with exact checks/counts/gaps. Dispatch owns preview3000 refresh. No subagents/kit/scheduler/external operations. Continue next actions via dispatch routing under existing owner direction.

Archived investigation: client-reliability-5

Interpreter checkpoint2026-10-20 confirms continuing development under existing direction. Claim item5 after non-destructive merge of unstable. Read RULE-CHANGES, KNOWN_ISSUES, PROGRAM, and performance-efficiency-plan Stage3. Items3/4 are completed: queued torrent/URL cancellation shipped; do not repeat their full qualification.

Investigate active URL/torrent probe lifecycle at HEAD. Start with actual URL observer→controller last-owner disposal during active media work; compare a shared live-owner control, completion/cleanup and a later same-source request. Controlled external fetch/media events only; no public traffic. Measure active resource retention, settlement, slot release and stale/cache effects before disposal, after disposal and after controlled completion. Distinguish bounded timeout behavior and intentional active caching from a demonstrated resource/lifecycle defect; missing AbortSignal alone is insufficient. Inspect active HEAD/HLS/torrent read-only only if needed to identify the smallest next defect. No assumption the old plan is current.

Investigation/evidence only: no product edits, no committed regression changes, no policy/limits/TTL tuning. Scratch diagnostics and your evidence/backlog notes permitted. Send dispatch exact HEAD, reproduction command, expected/actual counts, failing assertion/natural exit after cleanup, shared-owner control, smallest proposed fix files and acceptance. Dispatch will independently assess and route implementation. If no defect reproduces, report an evidence-backed next TODO candidate rather than speculate or silently stop. Preserve dirty/queued work. No subagents needed. No deploy/push/spend/wallet/production-data/scheduler/kit changes; preview3000 preserved. Mailbox event on blocker and completed investigation. Archived briefs below are historical, not new work authorization.

Archived completed assignment: client-reliability-4 — queued URL probe fix

Investigation is complete: at4c54858c real observer/controller/cache gives4 HEAD requests,3 active media probes and1 queued. Dispose/remove last feed then release a slot: obsolete media starts1(expected0); --expect-fixed naturally fails exit1 after cleanup. Shared live-owner control passes exit0, healthy badge, settled4/active0/queued0. Dispatch independently reproduced both against dispatch code at604c8c61 using /tmp/bitvid-dispatch-4-url-lifecycle.mjs. No public IO. Your detailed investigation evidence remains authoritative for fixture details.

Implementation now authorized for item4. Temporary explicit ownership: js/urlHealthObserver.js, js/ui/urlHealthController.js, focused URL lifecycle tests, relevant existing URL health tests, Test Integrity Note and area evidence/backlog notes. Use existing onCardUnregister boundary. No shared cardObserver/VideoListView/app/state-cache module changes without evidence and routing. No HEAD/active media abort, HLS/torrent changes, cache policy/TTLs, mirror order, concurrency, signers, kit or styling changes. Existing callback consumers must remain compatible without editing app.js. If that cannot work safely, report before broadening.

Before edits read current rules and test-integrity standard, merge unstable and preserve investigation notes. Retain a real observer→controller→queue regression with controlled external IO. Cancel queued work only after its last live owner disappears; settle cancellation without negative cache, mirror fallthrough, stale UI mutation or deleting newer inflight records. Preserve live shared owners and existing event/source/playable-mode dedup; later same-source registrations can retry. Keep three-media concurrency and healthy hidden-card reveal. Already-active probes retain prior lifecycle/cache behavior.

Verify last-owner obsolete starts0, shared live owner remains healthy, cancellation settlement and same-source retry, disposed/reused registration stale callbacks, mirror order, concurrency and hidden-card reveal. Every new scenario needs a deliberately broken mutant that fails; preserve assertions and no sleeps/retries. Run focused suites, npm run lint, full npm test with existing60s/file diagnostic bound, npm run build/artifact check and local Chromium/Firefox controlled lifecycle/source-health smoke if available (reserve browser in .task). Report actual playback/fallback gaps; do not claim CPU/RSS benefit from probe counts.

Commit with item4 id, merge unstable (never rebase), verify merged tree and normal landing gate. Durable landed status plus unstable ancestry before close. Send dispatch mailbox on blocker, product landing and final completion including SHA/checks/counts/unverified scope; dispatch owns independent verification and preview refresh. No further item without routing. No subagents needed. No deploy/push/spend/wallet/production-data/scheduler/kit changes.

Archived investigation: client-reliability-4

Owner continuation relayed by interpreter on 2026-10-20 explicitly permits this bounded step during quiet hours. No recurring schedule/config change.

Claim item4 after merging unstable. Read RULE-CHANGES, KNOWN_ISSUES and docs/performance-efficiency-plan.md Stage3. At current HEAD reproduce whether disposed feeds retain/start URL-health queued or active probes, or active torrent probes. Inspect js/urlHealthObserver.js, js/ui/urlHealthController.js, js/gridHealth.js and js/webtorrent.js read-only. Prefer the URL queued-owner case first; old plan concurrency and lifecycle claims may be stale. Use actual observer/controller entry points with deterministic deferred external IO boundaries and no public network. Preserve shared live-owner behavior. Measure started, queued, disposed and settled counts; record exact command, SHA, expected/actual and natural exit. Do not infer a defect merely from missing AbortSignal.

This assignment authorizes investigation and scratch/evidence notes only: no product or committed regression-test changes yet, no test weakening, no browser reservation unless needed, no broad Stage3 implementation. Report the smallest reproduced defect plus proposed files/acceptance to dispatch before fixing. If not reproducible, record why and return the next evidenced TODO candidate for routing. Commit evidence/backlog notes separately through normal queue if needed. Send mailbox on blocker and final investigation result; current mailbox tools deliver a short wake, so archived text below claiming no wake is historical. No subagents needed. No deploy/push/spend/wallet/production-data/scheduler/kit changes. Preserve preview3000. Existing completed item3 evidence follows for context; do not redo it or follow its old implementation steps.

Archived completed assignment: client-reliability-3

Improve robustness/usability with one bounded client-facing fix from pre-launch TODO #34 Stage3: cancel queued torrent health probes when the last card/feed owner is disposed. Prior items1 and2 are done, normally landed at de6918ce and closed at f9adfc8f (425/425 unit files, lint11/11). Do not redo them.

Current evidence

At f9adfc8f, dispatch ran /tmp/bitvid-dispatch-obsolete-probe-scenario.mjs. It imports actual gridHealth.js and torrentClient, uses real DOM cards and attachHealthBadges with a controllable IntersectionObserver, and replaces only the external probePeers boundary with deferred promises (no live network). Five cards enter: four probes start, one waits. Dispose the returned observer registration, remove feed DOM, then release active probes: one obsolete probe still starts, expected zero. The assertion fails with1!==0. This is stronger than the earlier isolated ProbeQueue class inspection; it is not a browser CPU or real-torrent measurement. Inspect the diagnostic for fixture details and reproduce against your own worktree before editing. Retain a proper regression in the repository.

Ownership for this item

Temporary explicit ownership: js/gridHealth.js; a small queue/owner helper if needed (prefer js/gridHealthQueue.js); focused lifecycle tests (prefer tests/grid-health-lifecycle.test.mjs); relevant existing grid-health tests and Test Integrity Note; your backlog/evidence/area notes. Existing js/dom/cardObserver.js already exposes onCardUnregister: use that boundary. Report specific evidence before editing that shared module or VideoListView lifecycle.

Do not edit js/app.js, URL-health plumbing, js/webtorrent.js or vendor bundle, active-probe abort behavior, playback/magnet helpers, cache policy/TTLs, concurrency limits, signers, payments, styling, test runner, fleet config, or kit infrastructure. No other worker owns this bounded scope. No subagents needed.

Plan and done

1. Read current RULE-CHANGES, PROGRAM, RESUME-BRIEF, KNOWN_ISSUES, AGENTS, repo memory and test integrity standard. Merge unstable, claim client-reliability-3, reproduce actual five-card lifecycle before edits, and record started/queued counts.
2. Associate queued work with live card/feed owners. Disposing the last owner prevents the queued probe from starting; discarding one owner must not cancel shared work needed by a live card. Leave already-active probe behavior unchanged.
3. Preserve deduplication, priority and current concurrency (four), healthy/negative TTLs, valid magnet bytes and WSS policy. Cancelled jobs must settle without creating unhealthy cache entries or deleting newer inflight entries. Later live cards must be able to request the same source. Disposed registrations must not receive stale UI effects.
4. Test actual observer/queue/probe boundaries: last-owner disposal, two owners sharing a queued source, re-request after cancellation, concurrency/priority preservation, and a healthy hidden-card reveal path. Use controlled probes and no public relay/torrent traffic. Kill a deliberately broken variant for each new scenario or explain grouped mutant coverage; include integrity notes. No arbitrary sleeps/retries/relaxed assertions.
5. Run focused suites, full npm test with the existing60s/file diagnostic bound, npm run lint, npm run build, and a local browser lifecycle/health smoke where available. This is product code: report browser/source-fallback verification and any gap honestly. Reserve the shared browser in .task. No CPU improvement claim without measurement; this item measures obsolete starts, not the entire performance plan.
6. Commit with client-reliability-3, merge unstable (never rebase), verify merged tree, submit through unchanged normal landq, verify durable landed status and unstable ancestry, then close item. Route new out-of-scope failures to dispatch; do not weaken gates or broaden automatically.

Completion handoff and operating limits

Send a dispatch mailbox event when blocked, when code lands, and at final completion, including SHA, exact checks/counts, unverified behavior and next step. The generated startup message said to report only when blocked; the new assignment explicitly replaces that reporting instruction with landing/final-completion events as well. The previous completion left no unread dispatch event. File-mailbox delivery only records a message: it does not start a Codex turn or wake idle dispatch. The operator currently supplies the new turn/tmux input; do not claim unattended monitoring. No scheduler or kit changes in this task. No additional work after this item without routing.

Owner routine-work delegation was relayed from Codex desktop chat and recorded with provenance in PROGRAM. No deploys, spending, production data, real-wallet operations, or schedulers. Preserve fleet-bitvid:preview at http://127.0.0.1:3000; dispatch syncs and rebuilds after verified product changes land. Keep .task current, communicate directly via mailbox, and disclose tool/permission blockers without bypassing controls.