Authored by Claude Opus 4.7 (Claude Code). Session continuation from cloud-deployment-trial sprint.

FAIR-band: in-band [16/30] — operator-direction (focus on multi-user cloud deployment, v13 wrap-up ratio discipline). Live verifier (per @neo-gpt cycle-1): GPT 14 / Claude 16 over last 30 merged PRs.

Evidence: L1 (286/286 PASS across orchestrator/; 5 new cycle-2 integration tests proving bootstrap-spread + orchestrator-resolved cadence/jitter pass-through; manual CLI bypass; deterministic jitter; backoff state mutation).

Resolves #11942

Summary

Cycle-2 closes #11942 AC1 (per-repo cadence + deterministic jitter/backoff). With #11952 (AC3+AC4) and #11960 (AC2) already merged, this PR completes the #11942 Epic — all four ACs shipped after architectural cycle-2.

Operator-direction continuation: this is the natural follow-on lane after #11960 (AC2 concurrency-gate) merged. Per the v13 wrap-up ratio discipline, this PR uses an EXISTING ticket (#11942 AC1) — no new ticket cost.

Architectural shift (cycle-2)

Cycle-1 problem (caught by @neo-gpt cycle-1 review at 5d374c7c):

The cycle-1 implementation computed deterministic jitter correctly but the production scheduler invoked tenant-repo-sync on the same cadence used as the per-repo base cadence. With lastRunAttemptAt=0 for fresh repos and Date.now() as now, all repos became due on cycle 1 → thundering herd despite jitter. After cycle 1, non-zero jitter caused all repos to miss the next sweep and become due together on the cycle after → thundering herd cycle 2.

That is not spread across [0, jitterRatio * baseCadenceMs).

Cycle-2 fix (cb010c1d5):

Two architectural decoupling moves:

1. Sweep cadence vs per-repo cadence are now distinct configs

• New AiConfig.orchestrator.tenantRepoSync.sweepCadenceMs (default 60_000 = 1 min) drives Orchestrator scheduling.
• Existing AiConfig.orchestrator.intervals.tenantRepoSyncMs (default 30 min) is now strictly the per-repo default cadence read by isRepoDue().
• Orchestrator scheduling fires every sweepCadenceMs; per-repo decisions use globalCadenceMs (= tenantRepoSyncIntervalMs); jitter actually spreads.

2. Bootstrap seeding (syncTenantRepos)

• Pre-seeds new repos with lastRunAttemptAt = now - baseCadenceMs before iteration. This makes effective due-time now + jitterMs, so subsequent short-cadence sweeps within the jitter window pick up repos at staggered times — actual spread, not synchronized thundering herd.
• Seeded state persists across orchestrator restarts so HA-failover preserves the spread.
• onlyRepoSlugs (manual CLI bypass) skips seeding entirely; operator-initiated sync always fires.

3. Cadence-passthrough (eliminates split source of truth)

Orchestrator now explicitly passes:

return this.tenantRepoSyncService.runTask({
    taskName,
    reason,
    taskStateService: this.taskStateService,
    healthService   : this.healthService,
    writeLog        : this.writeLog.bind(this),
    globalCadenceMs : this.tenantRepoSyncIntervalMs,  // explicit pass — was AiConfig fallback
    jitterRatio     : this.tenantRepoSyncJitterRatio  // explicit pass — was AiConfig fallback
});

This eliminates the cycle-1 bug where Orchestrator.mjs computed this.tenantRepoSyncIntervalMs with env precedence but runTask() defaulted globalCadenceMs from AiConfig.data.orchestrator.intervals.tenantRepoSyncMs directly. Env-overridden deployments now see the same cadence at both layers.

4. New Orchestrator getters

• tenantRepoSyncSweepCadenceMs (env: NEO_ORCHESTRATOR_TENANT_REPO_SYNC_SWEEP_CADENCE_MS) — sweep frequency
• tenantRepoSyncJitterRatio (env: NEO_ORCHESTRATOR_TENANT_REPO_SYNC_JITTER_RATIO) — jitter ratio with env precedence

Existing tenantRepoSyncIntervalMs getter preserved with semantic shift to "per-repo cadence"; the NEO_ORCHESTRATOR_TENANT_REPO_SYNC_INTERVAL_MS env name is unchanged for back-compat (operators who set this for "faster testing" now get faster per-repo cadence under a 1-min sweep).

5. Test seam: seedBootstrap parameter

runTask/syncTenantRepos accept seedBootstrap (default true in production). Spec files that simulate "first cycle fires all repos" can opt out via seedBootstrap: false. Required because bootstrap-seeding defers the first-fire of new repos by design.

Component shape

Pure functions in ai/daemons/orchestrator/scheduling/tenantRepoSync.mjs — unchanged from cycle-1:

• computeDeterministicJitter({tenantId, repoSlug, baseCadenceMs, jitterRatio}) — FNV-1a-based stable jitter offset
• isRepoDue({repo, persistedRepoState, now, globalCadenceMs, jitterRatio}) — returns full envelope {due, effectiveCadenceMs, jitterMs, backoffMultiplier, lastRunAttemptAt}

Persistence schema (unchanged from cycle-1, with bootstrap-seeded values appearing on first observation):

{ revisions: { 'tenantId/repoSlug': {
    lastIngestedRev    : 'sha' | null,
    lastRunAttemptAt   : 1716000000000,  // bootstrap-seeded: now - baseCadenceMs
    consecutiveFailures: 0
} } }

syncTenantRepos per-sweep loop (cycle-2 additions):

• Pre-pass: bootstrap-seed new repos (skipped on onlyRepoSlugs and when seedBootstrap: false)
• Per-repo due-check via isRepoDue (unchanged from cycle-1)
• Not-due repos: skip semaphore + work entirely, emit status='not-due' health entry
• Due repos: acquire semaphore + run work + mutate persisted state per outcome

runTask + syncTenantRepos signatures accept globalCadenceMs + jitterRatio + seedBootstrap parameters. Defaults preserved for back-compat with manual CLI invocations; Orchestrator passes orchestrator-resolved values explicitly.

Deltas from ticket

None — cycle-2 implementation matches AC1 prescription:

• ✓ Per-repo cadence stored in tenant-repo-sync-revisions.json alongside lastIngestedRev
• ✓ Deterministic jitter via repoSlug + tenantId hash
• ✓ Jitter window ≤ 20% of cadence (default jitterRatio: 0.20)
• ✓ Backoff doubles on consecutive failures (multiplier 2^consecutiveFailures)
• ✓ Resets on success (consecutiveFailures = 0 after successful sync)

Cycle-2 additions beyond strict AC1 prescription (justified by review feedback):

• Decoupled sweep cadence — required for jitter to actually spread per-repo work
• Bootstrap seeding — required to spread the FIRST sweep (otherwise all repos due at lastRunAttemptAt=0)
• Cadence/jitter pass-through — eliminates split source of truth flagged by GPT
• Manual CLI bypass (onlyRepoSlugs) — unchanged from cycle-1
• Health-payload nextDueAt visibility — unchanged from cycle-1
• Backward-compatible read of pre-AC1 string-shape persistence — unchanged from cycle-1

Test Evidence

npm run test-unit -- test/playwright/unit/ai/daemons/orchestrator/

→ 286/286 PASS (8.0s)

The directly-touched specs:

• scheduling/tenantRepoSync.spec.mjs — 18/18 (unchanged from cycle-1)
• services/TenantRepoSyncService.spec.mjs — 27/27 (22 from cycle-1 + 5 new cycle-2)

The 5 new cycle-2 integration tests cover:

1. bootstrap-spread: first sweep seeds new repos with lastRunAttemptAt=now-baseCadence — verifies seeded state, notDueCount=2 on the seeding sweep
2. bootstrap-spread: seeded repo becomes due on a later sweep within its jitter window — pre-seeds; advances time; verifies distribution sums correctly
3. orchestrator-resolved globalCadenceMs flows through to isRepoDue — explicit globalCadenceMs: 1hr makes a 100ms-elapsed repo not-due (RA3)
4. orchestrator-resolved jitterRatio flows through to isRepoDue — explicit jitterRatio: 0.50 adds offset → not-due at exact-cadence-boundary (RA3)
5. manual CLI (onlyRepoSlugs) bypasses bootstrap seeding — operator-initiated sync always fires

Cycle-2 changes (per @neo-gpt review at 5d374c7c)

Pushed at cb010c1d5:

1. RA1 — scheduler composition fix: added sweepCadenceMs config (default 1min) + bootstrap seeding (syncTenantRepos pre-pass) so deterministic jitter actually spreads tenant repo work across the jitter window. Sweep cadence is now decoupled from per-repo cadence; first-bootstrap deployments no longer thundering-herd.
2. RA2 — cadence pass-through: Orchestrator now explicitly passes globalCadenceMs: this.tenantRepoSyncIntervalMs AND jitterRatio: this.tenantRepoSyncJitterRatio into runTask(). The cycle-1 split source of truth (env-resolved cadence at scheduler vs AiConfig-default at runTask) is gone.
3. RA3 — integration tests: 5 new tests in TenantRepoSyncService.spec.mjs covering bootstrap seeding, multi-sweep behavior, and cadence/jitter pass-through. Plus updated 8 existing tests with seedBootstrap: false opt-out (they test in-loop iteration semantics, not bootstrap behavior).
4. RA4 — FAIR-band correction: [17/30] (stale) → [16/30] (in-band per GPT's live verifier of last 30 merged PRs).

Post-Merge Validation

• Operator confirms multi-tenant first-bootstrap deployment doesn't thundering-herd (clones spread across ~20% of cadence window via 1-min sweep cadence)
• Operator confirms a persistently-failing repo backs off (cycle 1 fail → 2× cadence; cycle 2 fail → 4× cadence; eventual success resets to 1×)
• Operator confirms NEO_ORCHESTRATOR_TENANT_REPO_SYNC_SWEEP_CADENCE_MS (new) and NEO_ORCHESTRATOR_TENANT_REPO_SYNC_JITTER_RATIO (new) env overrides take effect on next sweep
• #11942 Epic complete with this merge — all 4 ACs shipped (AC1 = this PR; AC2 = #11960; AC3+AC4 = #11952)

Avoided Traps

• ✓ Did NOT introduce a separate persistence file for per-repo state — extended existing tenant-repo-sync-revisions.json with backward-compat read, single-source-of-truth preserved
• ✓ Did NOT design a separate schedule-emitter that fires per-repo events — kept the existing single-task-per-cycle architecture with per-repo due-checks inside; matches the cloud-deployment-trial-tested shape
• ✓ Did NOT apply due-check or bootstrap seeding to manual CLI invocations — operator-initiated sync should always fire; onlyRepoSlugs bypass preserves manual sync semantics
• ✓ Did NOT introduce schemaVersion field speculatively — migration is detectable via shape-tell (string vs object); adding schemaVersion would be speculative-support per feedback_truth_in_code
• ✓ (cycle-2) Did NOT keep the cycle-1 split source of truth — Orchestrator now passes both globalCadenceMs and jitterRatio explicitly into runTask(); AiConfig defaults remain as the manual-CLI fallback only
• ✓ (cycle-2) Did NOT couple sweep cadence to per-repo cadence — they're separate configs; sweep fires frequently, per-repo decisions own their cadence

v13 wrap-up ratio accounting

This PR uses EXISTING ticket #11942 (no new ticket cost). Per the operator's 2026-05-25 ratio constraint (1 new ticket : 2-3 PRs minimum):

• Session ratio so far: 2 new tickets (#11954 + #11955, both already merged) : 7 PRs landed (#11951 + #11952 + #11953-by-GPT + #11956 + #11957 + #11958-by-GPT + #11959 + #11960) ≈ 1:3.5 ratio
• This PR adds: 0 new ticket + 1 PR → 0:1 incremental → keeps overall ratio strongly positive
• Discussion #11961 graduation (now landed as #10103) added 1 epic + 3 sub-tickets (#11963, #11965, #11964) and 2 sub-PRs in-flight (#11967 + #11966) → multi-PR yield on existing graduation work

Authority

#11942 was filed by me 2026-05-25 as a follow-up to #11790 cycle-1 review feedback. AC3+AC4 shipped via #11952, AC2 shipped via #11960, AC1 ships here. Self-assigned, operator-aligned with the "we need to make progress" framing on existing v13 tickets pre-graduation.

Authored by [Claude Opus 4.7] (Claude Code) — Session continuation from cloud-deployment-trial sprint.