@@ -450,11 +450,14 @@ describe("activeAgentTurnsStore", () => {
450450 assert . equal ( ref1 , ref2 , "should return cached array reference" ) ;
451451 } ) ;
452452
453- it ( "preserves a desktop-clock observedAt per channel" , ( ) => {
453+ it ( "anchors a turn to its skew-corrected start, not the local insert clock" , ( ) => {
454+ // The badge anchor must reflect the agent's true start translated into
455+ // desktop time (startedAt + clock offset), so a turn whose event arrives
456+ // with a stale timestamp does NOT reset to ~Date.now(). With a single
457+ // event the offset is exactly Date.now() - startedAt, so the anchor lands
458+ // on Date.now() here — the regression coverage for skew lives below.
454459 const before = Date . now ( ) ;
455460 syncAgentTurnsFromEvents ( AGENT , [
456- // startedAt comes from the (stale) event timestamp; observedAt must
457- // instead anchor to the local clock at insert time.
458461 makeEvent ( {
459462 seq : 1 ,
460463 turnId : "t1" ,
@@ -466,69 +469,114 @@ describe("activeAgentTurnsStore", () => {
466469 const [ summary ] = getActiveTurnsForAgent ( AGENT ) ;
467470 assert . equal ( summary . channelId , "c1" ) ;
468471 assert . ok (
469- summary . observedAt >= before && summary . observedAt <= after ,
470- "observedAt must be the local clock at insert, not the event timestamp " ,
472+ summary . anchorAt >= before && summary . anchorAt <= after ,
473+ "anchorAt must be the skew-corrected start, here equal to the local clock " ,
471474 ) ;
472475 } ) ;
473476
474- it ( "collapses two turns in one channel to the earliest observedAt" , ( ) => {
477+ it ( "gives two turns with different startedAt different anchors (no lockstep)" , ( ) => {
478+ // The lockstep bug: turns processed in the same JS tick were all anchored
479+ // to one shared Date.now(), so their elapsed counters ticked in unison.
480+ // Anchoring to startedAt + offset makes distinct agent-host starts produce
481+ // distinct anchors. A single sampleClockOffset minimum is shared, so the
482+ // anchor difference equals the startedAt difference.
475483 syncAgentTurnsFromEvents ( AGENT , [
476- makeEvent ( { seq : 1 , turnId : "t1" , channelId : "c1" } ) ,
484+ makeEvent ( {
485+ seq : 1 ,
486+ turnId : "t1" ,
487+ channelId : "c-early" ,
488+ timestamp : "2024-01-01T00:00:00Z" ,
489+ } ) ,
490+ makeEvent ( {
491+ seq : 2 ,
492+ turnId : "t2" ,
493+ channelId : "c-late" ,
494+ timestamp : "2024-01-01T00:05:00Z" ,
495+ } ) ,
477496 ] ) ;
478- const firstObservedAt = getActiveTurnsForAgent ( AGENT ) [ 0 ] . observedAt ;
497+ const byChannel = new Map (
498+ getActiveTurnsForAgent ( AGENT ) . map ( ( s ) => [ s . channelId , s . anchorAt ] ) ,
499+ ) ;
500+ assert . notEqual (
501+ byChannel . get ( "c-early" ) ,
502+ byChannel . get ( "c-late" ) ,
503+ "distinct startedAt must yield distinct anchors" ,
504+ ) ;
505+ assert . equal (
506+ byChannel . get ( "c-late" ) - byChannel . get ( "c-early" ) ,
507+ 5 * 60_000 ,
508+ "anchor spacing must equal the agent-host start spacing" ,
509+ ) ;
510+ } ) ;
479511
480- // Second turn in the same channel — its observedAt is >= the first
481- // because the clock is monotonic, so the earliest must still win.
512+ it ( "collapses two turns in one channel to the earliest anchor" , ( ) => {
513+ // Same agent-host start timestamp, distinct turns (seq bumped so the
514+ // second passes the watermark). Identical timestamps mean the offset does
515+ // not move, so the surfaced anchor is stable and the earliest wins.
482516 syncAgentTurnsFromEvents ( AGENT , [
483- makeEvent ( { seq : 2 , turnId : "t2" , channelId : "c1" } ) ,
517+ makeEvent ( {
518+ seq : 1 ,
519+ turnId : "t1" ,
520+ channelId : "c1" ,
521+ timestamp : "2024-01-01T00:00:00Z" ,
522+ } ) ,
523+ ] ) ;
524+ const firstAnchor = getActiveTurnsForAgent ( AGENT ) [ 0 ] . anchorAt ;
525+ syncAgentTurnsFromEvents ( AGENT , [
526+ makeEvent ( {
527+ seq : 2 ,
528+ turnId : "t2" ,
529+ channelId : "c1" ,
530+ timestamp : "2024-01-01T00:00:00Z" ,
531+ } ) ,
484532 ] ) ;
485533 const summaries = getActiveTurnsForAgent ( AGENT ) ;
486534 assert . equal ( summaries . length , 1 , "same channel collapses to one entry" ) ;
487535 assert . equal (
488- summaries [ 0 ] . observedAt ,
489- firstObservedAt ,
490- "earliest observedAt for the channel must be surfaced" ,
536+ summaries [ 0 ] . anchorAt ,
537+ firstAnchor ,
538+ "earliest start's anchor must be surfaced" ,
491539 ) ;
492540 } ) ;
493541
494- it ( "advances to the surviving turn's observedAt after the earliest ends" , ( ) => {
542+ it ( "advances to the surviving turn's anchor after the earliest ends" , ( ) => {
495543 // Two turns in one channel; the array must be rebuilt from the LIVE map
496- // on every mutation, so ending the earliest-observed turn must surface
497- // the survivor's observedAt — not a stale cached minimum.
544+ // on every mutation, so ending the earliest-started turn must surface the
545+ // survivor's (later) anchor — not a stale cached minimum.
498546 syncAgentTurnsFromEvents ( AGENT , [
499- makeEvent ( { seq : 1 , turnId : "t-early" , channelId : "c1" } ) ,
500- ] ) ;
501- const tEarly = getActiveTurnsForAgent ( AGENT ) [ 0 ] . observedAt ;
502-
503- // Force the second turn's observedAt strictly past the first so the
504- // advance is observable even when Date.now() would otherwise collide.
505- const spinUntil = Date . now ( ) + 2 ;
506- while ( Date . now ( ) < spinUntil ) {
507- /* busy-wait one clock tick */
508- }
509- syncAgentTurnsFromEvents ( AGENT , [
510- makeEvent ( { seq : 2 , turnId : "t-later" , channelId : "c1" } ) ,
547+ makeEvent ( {
548+ seq : 1 ,
549+ turnId : "t-early" ,
550+ channelId : "c1" ,
551+ timestamp : "2024-01-01T00:00:00Z" ,
552+ } ) ,
553+ makeEvent ( {
554+ seq : 2 ,
555+ turnId : "t-later" ,
556+ channelId : "c1" ,
557+ timestamp : "2024-01-01T00:02:00Z" ,
558+ } ) ,
511559 ] ) ;
512- assert . equal (
513- getActiveTurnsForAgent ( AGENT ) [ 0 ] . observedAt ,
514- tEarly ,
515- "earliest wins while both turns survive" ,
516- ) ;
560+ const tEarly = getActiveTurnsForAgent ( AGENT ) [ 0 ] . anchorAt ;
517561
518- // End the earliest turn by its turnId.
562+ // End the earliest turn by its turnId. Reuse t-later's timestamp (seq
563+ // bumped to pass the watermark) so the offset does not tighten and the
564+ // surviving anchor's advance is exactly the 2-minute start gap.
519565 syncAgentTurnsFromEvents ( AGENT , [
520566 makeEvent ( {
521567 seq : 3 ,
522568 kind : "turn_completed" ,
523569 turnId : "t-early" ,
524570 channelId : "c1" ,
571+ timestamp : "2024-01-01T00:02:00Z" ,
525572 } ) ,
526573 ] ) ;
527574 const [ survivor ] = getActiveTurnsForAgent ( AGENT ) ;
528575 assert . equal ( survivor . channelId , "c1" ) ;
529- assert . ok (
530- survivor . observedAt > tEarly ,
531- "surfaced observedAt must advance to the surviving turn after eviction" ,
576+ assert . equal (
577+ survivor . anchorAt - tEarly ,
578+ 2 * 60_000 ,
579+ "surfaced anchor must advance to the surviving turn after eviction" ,
532580 ) ;
533581 } ) ;
534582
@@ -642,6 +690,148 @@ describe("activeAgentTurnsStore", () => {
642690 ) ;
643691 } ) ;
644692 } ) ;
693+
694+ describe ( "skew-corrected elapsed (real-time arrival)" , ( ) => {
695+ // The clock offset estimate (running minimum of Date.now() - event time)
696+ // is only meaningful when events arrive at distinct real times — exactly
697+ // how the harness streams them. Faking Date lets us advance the desktop
698+ // clock between events so an earlier event calibrates the offset before the
699+ // measured turn starts. The fixed epoch is the desktop clock floor.
700+ const EPOCH = Date . parse ( "2024-06-01T00:00:00Z" ) ;
701+
702+ beforeEach ( ( ) => {
703+ mock . timers . enable ( { apis : [ "Date" ] , now : EPOCH } ) ;
704+ } ) ;
705+
706+ afterEach ( ( ) => {
707+ mock . timers . reset ( ) ;
708+ } ) ;
709+
710+ /** Agent-host clock = desktop clock + skew, as an ISO timestamp. */
711+ const agentTs = ( desktopMs , skew ) =>
712+ new Date ( desktopMs + skew ) . toISOString ( ) ;
713+
714+ it ( "shows a large elapsed for a turn that started well in the past" , ( ) => {
715+ // Clocks synced (skew 0). An early event at the true present calibrates
716+ // offset ≈ 0. Five true minutes pass. Then the desktop first observes a
717+ // turn whose start timestamp is that 5-minutes-ago instant — the badge
718+ // must read ~5 minutes, not reset to 0s on first sight.
719+ syncAgentTurnsFromEvents ( AGENT , [
720+ makeEvent ( {
721+ seq : 1 ,
722+ kind : "turn_liveness" ,
723+ turnId : "warm" ,
724+ channelId : "c0" ,
725+ timestamp : agentTs ( EPOCH - 1_000 , 0 ) ,
726+ } ) ,
727+ ] ) ;
728+ mock . timers . tick ( 5 * 60_000 ) ; // 5 true minutes elapse
729+ syncAgentTurnsFromEvents ( AGENT , [
730+ makeEvent ( {
731+ seq : 2 ,
732+ turnId : "t1" ,
733+ channelId : "c1" ,
734+ timestamp : agentTs ( EPOCH , 0 ) , // started 5 minutes ago
735+ } ) ,
736+ ] ) ;
737+ const summary = getActiveTurnsForAgent ( AGENT ) . find (
738+ ( s ) => s . channelId === "c1" ,
739+ ) ;
740+ assert . equal (
741+ Date . now ( ) - summary . anchorAt ,
742+ 5 * 60_000 - 1_000 ,
743+ "a 5-minute-old turn must show ~5 minutes elapsed, not 0s" ,
744+ ) ;
745+ } ) ;
746+
747+ it ( "corrects for agent-host clock skew so elapsed tracks true duration" , ( ) => {
748+ // Agent host is 1 hour AHEAD of the desktop. A liveness event received at
749+ // the true present (desktop EPOCH) carries a timestamp an hour in the
750+ // future, calibrating offset ≈ -1h. The turn then starts 30s later in
751+ // true time; its future-stamped start, corrected by the offset, anchors
752+ // to the true start — without correction elapsed would be deeply negative.
753+ const SKEW = 60 * 60_000 ;
754+ syncAgentTurnsFromEvents ( AGENT , [
755+ makeEvent ( {
756+ seq : 1 ,
757+ kind : "turn_liveness" ,
758+ turnId : "warm" ,
759+ channelId : "c0" ,
760+ timestamp : agentTs ( EPOCH , SKEW ) ,
761+ } ) ,
762+ ] ) ;
763+ mock . timers . tick ( 30_000 ) ; // 30s of true time passes
764+ syncAgentTurnsFromEvents ( AGENT , [
765+ makeEvent ( {
766+ seq : 2 ,
767+ turnId : "t1" ,
768+ channelId : "c1" ,
769+ timestamp : agentTs ( EPOCH + 30_000 , SKEW ) ,
770+ } ) ,
771+ ] ) ;
772+ const summary = getActiveTurnsForAgent ( AGENT ) . find (
773+ ( s ) => s . channelId === "c1" ,
774+ ) ;
775+ assert . equal (
776+ Date . now ( ) - summary . anchorAt ,
777+ 0 ,
778+ "a just-started turn under heavy skew must read ~0s, not a negative/huge value" ,
779+ ) ;
780+
781+ // Let the turn run 45s; elapsed must track that true duration exactly.
782+ mock . timers . tick ( 45_000 ) ;
783+ const stillRunning = getActiveTurnsForAgent ( AGENT ) . find (
784+ ( s ) => s . channelId === "c1" ,
785+ ) ;
786+ assert . equal (
787+ Date . now ( ) - stillRunning . anchorAt ,
788+ 45_000 ,
789+ "skew-corrected elapsed must track true duration as the clock advances" ,
790+ ) ;
791+ } ) ;
792+
793+ it ( "retroactively corrects a live turn's anchor when the offset tightens" , ( ) => {
794+ // The design's load-bearing invariant: anchors are derived at READ time,
795+ // so a later, tighter offset must shift an ALREADY-LIVE turn earlier.
796+ // The turn first goes live under a loose offset (its start arrives with a
797+ // +5s processing delay → offset +5000), then a delay-free liveness sample
798+ // tightens the running minimum to 0. The live turn's surfaced anchor must
799+ // move earlier by exactly that 5000ms delta. A regression that froze
800+ // anchorAt at startTurn would leave the anchor at its loose value and
801+ // fail this assertion.
802+ syncAgentTurnsFromEvents ( AGENT , [
803+ makeEvent ( {
804+ seq : 1 ,
805+ turnId : "t1" ,
806+ channelId : "c1" ,
807+ timestamp : agentTs ( EPOCH - 5_000 , 0 ) , // observed 5s after its start
808+ } ) ,
809+ ] ) ;
810+ const looseAnchor = getActiveTurnsForAgent ( AGENT ) . find (
811+ ( s ) => s . channelId === "c1" ,
812+ ) . anchorAt ;
813+
814+ mock . timers . tick ( 1_000 ) ; // 1s of true time so the liveness arrives later
815+ syncAgentTurnsFromEvents ( AGENT , [
816+ makeEvent ( {
817+ seq : 2 ,
818+ kind : "turn_liveness" ,
819+ turnId : "t1" ,
820+ channelId : "c1" ,
821+ timestamp : agentTs ( EPOCH + 1_000 , 0 ) , // delay-free → offset tightens to 0
822+ } ) ,
823+ ] ) ;
824+ const tightAnchor = getActiveTurnsForAgent ( AGENT ) . find (
825+ ( s ) => s . channelId === "c1" ,
826+ ) . anchorAt ;
827+
828+ assert . equal (
829+ tightAnchor - looseAnchor ,
830+ - 5_000 ,
831+ "a tighter offset must shift the live turn's read-time anchor earlier by the tightening delta" ,
832+ ) ;
833+ } ) ;
834+ } ) ;
645835} ) ;
646836
647837describe ( "formatElapsed" , ( ) => {
0 commit comments